\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename python.info
@documentencoding UTF-8
@ifinfo
@*Generated by Sphinx 8.1.3.@*
@end ifinfo
@settitle Python
@defindex ge
@paragraphindent 0
@exampleindent 4
@finalout
@dircategory Miscellaneous
@direntry
* python: (python.info). One line description of project
@end direntry

@c %**end of header

@copying
@quotation
Python 3.13.1, janvier 05, 2025

Author name not set

Copyright @copyright{} 2001-2025, Python Software Foundation
@end quotation

@end copying

@titlepage
@title Python
@insertcopying
@end titlepage
@contents

@c %** start of user preamble

@c %** end of user preamble

@ifnottex
@node Top
@top Python
@insertcopying
@end ifnottex

@c %**start of body
@anchor{contents doc}@anchor{134}
@menu
* Nouveautés de Python:: 
* Le tutoriel Python:: 
* Installation et utilisation de Python:: 
* La référence du langage Python:: 
* La bibliothèque standard:: 
* Extension et intégration de l'interpréteur Python:: 
* Manuel de référence de l'API Python/C:: 
* Installation de modules Python:: 
* Les HOWTOs de Python:: 
* Questions fréquemment posées sur Python:: 
* Deprecations:: 
* Glossaire:: 
* About this documentation:: 
* S'attaquer aux bogues:: 
* Copyright:: 
* Histoire et licence:: 
* Index des modules Python:: 
* Index:: 

@detailmenu
 --- The Detailed Node Listing ---

Nouveautés de Python

* What's New In Python 3.13: What's New In Python 3 13. 
* What's New In Python 3.12: What's New In Python 3 12. 
* Les nouveautés de Python 3.11: Les nouveautés de Python 3 11. 
* Les nouveautés de Python 3.10: Les nouveautés de Python 3 10. 
* Les nouveautés de Python 3.9: Les nouveautés de Python 3 9. 
* Nouveautés de Python 3.8: Nouveautés de Python 3 8. 
* What's New In Python 3.7: What's New In Python 3 7. 
* What's New In Python 3.6: What's New In Python 3 6. 
* Nouveautés de Python 3.5: Nouveautés de Python 3 5. 
* Nouveautés de Python 3.4: Nouveautés de Python 3 4. 
* Nouveautés de Python 3.3: Nouveautés de Python 3 3. 
* Nouveautés de Python 3.2: Nouveautés de Python 3 2. 
* Nouveautés de Python 3.1: Nouveautés de Python 3 1. 
* Nouveautés de Python 3.0: Nouveautés de Python 3 0. 
* Nouveautés de Python 2.7: Nouveautés de Python 2 7. 
* Nouveautés de Python 2.6: Nouveautés de Python 2 6. 
* Nouveautés de Python 2.5: Nouveautés de Python 2 5. 
* Nouveautés de Python 2.4: Nouveautés de Python 2 4. 
* Nouveautés de Python 2.3: Nouveautés de Python 2 3. 
* Nouveautés de Python 2.2: Nouveautés de Python 2 2. 
* Nouveautés de Python 2.1: Nouveautés de Python 2 1. 
* Nouveautés de Python 2.0: Nouveautés de Python 2 0. 
* Changelog:: 

What's New In Python 3.13

* Summary: Summary -- Release Highlights. Release Highlights
* Nouvelles fonctionnalités:: 
* Autres changements au langage:: 
* Nouveaux modules:: 
* Modules améliorés:: 
* Optimisations:: 
* Removed Modules And APIs:: 
* New Deprecations:: 
* CPython Bytecode Changes:: 
* Changements à l'API C:: 
* Changements à la compilation:: 
* Porting to Python 3.13: Porting to Python 3 13. 
* Regression Test Changes:: 
* Notable changes in 3.13.1: Notable changes in 3 13 1. 

Nouvelles fonctionnalités

* A better interactive interpreter:: 
* Improved error messages:: 
* Free-threaded CPython:: 
* An experimental just-in-time (JIT) compiler: An experimental just-in-time JIT compiler. 
* Defined mutation semantics for locals(): Defined mutation semantics for locals. 
* Support for mobile platforms:: 

Modules améliorés

* argparse:: 
* array:: 
* ast:: 
* asyncio:: 
* base64:: 
* compileall:: 
* concurrent.futures: concurrent futures. 
* configparser:: 
* copy:: 
* ctypes:: 
* dbm:: 
* dis:: 
* doctest:: 
* email:: 
* enum:: 
* fractions:: 
* glob:: 
* importlib:: 
* io:: 
* ipaddress:: 
* itertools:: 
* marshal:: 
* math:: 
* mimetypes:: 
* mmap:: 
* multiprocessing:: 
* os:: 
* os.path: os path. 
* pathlib:: 
* pdb:: 
* queue:: 
* random:: 
* re:: 
* shutils:: 
* site:: 
* sqlite3:: 
* ssl:: 
* statistics:: 
* subprocess:: 
* sys:: 
* tempfile:: 
* time:: 
* tkinter:: 
* traceback:: 
* types:: 
* typing:: 
* unicodedata:: 
* venv:: 
* warnings:: 
* xml:: 
* zipimport:: 

Removed Modules And APIs

* PEP 594; Remove "dead batteries" from the standard library: PEP 594 Remove "dead batteries" from the standard library. 
* 2to3:: 
* builtins:: 
* configparser: configparser<2>. 
* importlib.metadata: importlib metadata. 
* locale:: 
* opcode:: 
* optparse:: 
* pathlib: pathlib<2>. 
* re: re<2>. 
* tkinter.tix: tkinter tix. 
* turtle:: 
* typing: typing<2>. 
* unittest:: 
* urllib:: 
* webbrowser:: 

New Deprecations

* Pending Removal in Python 3.14: Pending Removal in Python 3 14. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15. 
* Pending removal in Python 3.16: Pending removal in Python 3 16. 
* Pending Removal in Future Versions:: 

Changements à l'API C

* Nouvelles fonctionnalités: Nouvelles fonctionnalités<2>. 
* Changed C APIs:: 
* Limited C API Changes:: 
* Removed C APIs:: 
* Deprecated C APIs:: 

Deprecated C APIs

* Pending Removal in Python 3.14: Pending Removal in Python 3 14<2>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<2>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<2>. 

Porting to Python 3.13

* Changements dans l'API Python:: 
* Changements dans l'API C:: 

Notable changes in 3.13.1

* sys: sys<2>. 

What's New In Python 3.12

* Résumé – Points marquants de cette version:: 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<3>. 
* Nouvelles fonctionnalités reliées aux indications de types:: 
* Autres changements au langage: Autres changements au langage<2>. 
* Nouveaux modules: Nouveaux modules<2>. 
* Modules améliorés: Modules améliorés<2>. 
* Optimisations: Optimisations<2>. 
* Changements au code intermédiaire CPython:: 
* Demos and Tools:: 
* Obsolescence:: 
* Retraits:: 
* Porting to Python 3.12: Porting to Python 3 12. 
* Changements à la compilation: Changements à la compilation<2>. 
* Changements à l'API C: Changements à l'API C<2>. 

Nouvelles fonctionnalités

* PEP 695; Type Parameter Syntax: PEP 695 Type Parameter Syntax. 
* PEP 701; Syntactic formalization of f-strings: PEP 701 Syntactic formalization of f-strings. 
* PEP 684; A Per-Interpreter GIL: PEP 684 A Per-Interpreter GIL. 
* PEP 669; Low impact monitoring for CPython: PEP 669 Low impact monitoring for CPython. 
* PEP 688; Making the buffer protocol accessible in Python: PEP 688 Making the buffer protocol accessible in Python. 
* PEP 709; Comprehension inlining: PEP 709 Comprehension inlining. 
* Improved Error Messages:: 

Nouvelles fonctionnalités reliées aux indications de types

* PEP 692; Using TypedDict for more precise **kwargs typing: PEP 692 Using TypedDict for more precise **kwargs typing. 
* PEP 698; Override Decorator for Static Typing: PEP 698 Override Decorator for Static Typing. 

Modules améliorés

* array: array<2>. 
* asyncio: asyncio<2>. 
* calendar:: 
* csv:: 
* dis: dis<2>. 
* fractions: fractions<2>. 
* importlib.resources: importlib resources. 
* inspect:: 
* itertools: itertools<2>. 
* math: math<2>. 
* os: os<2>. 
* os.path: os path<2>. 
* pathlib: pathlib<3>. 
* pdb: pdb<2>. 
* random: random<2>. 
* shutils: shutils<2>. 
* sqlite3: sqlite3<2>. 
* statistics: statistics<2>. 
* sys: sys<3>. 
* tempfile: tempfile<2>. 
* threading:: 
* tkinter: tkinter<2>. 
* tokenize:: 
* types: types<2>. 
* typing: typing<3>. 
* unicodedata: unicodedata<2>. 
* unittest: unittest<2>. 
* uuid:: 

Obsolescence

* Pending Removal in Python 3.13: Pending Removal in Python 3 13. 
* Pending Removal in Python 3.14: Pending Removal in Python 3 14<3>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<3>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<2>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<3>. 

Retraits

* asynchat and asyncore:: 
* configparser: configparser<3>. 
* distutils:: 
* ensurepip:: 
* enum: enum<2>. 
* ftplib:: 
* gzip:: 
* hashlib:: 
* importlib: importlib<2>. 
* imp:: 
* io: io<2>. 
* locale: locale<2>. 
* smtpd:: 
* sqlite3: sqlite3<3>. 
* ssl: ssl<2>. 
* unittest: unittest<3>. 
* webbrowser: webbrowser<2>. 
* xml.etree.ElementTree: xml etree ElementTree. 
* zipimport: zipimport<2>. 
* Autres:: 

Porting to Python 3.12

* Changements dans l'API Python: Changements dans l'API Python<2>. 

Changements à l'API C

* Nouvelles fonctionnalités: Nouvelles fonctionnalités<4>. 
* Porting to Python 3.12: Porting to Python 3 12<2>. 
* Obsolescence: Obsolescence<2>. 
* Retraits: Retraits<2>. 

Obsolescence

* Pending Removal in Python 3.14: Pending Removal in Python 3 14<4>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<4>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<4>. 

Les nouveautés de Python 3.11

* Résumé – Points forts de la publication:: 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<5>. 
* Nouvelles fonctionnalités reliées aux indications de types: Nouvelles fonctionnalités reliées aux indications de types<2>. 
* Autres changements au langage: Autres changements au langage<3>. 
* Autres changements à l'implémentation de CPython:: 
* Nouveaux modules: Nouveaux modules<3>. 
* Modules améliorés: Modules améliorés<3>. 
* Optimisations: Optimisations<3>. 
* Faster CPython:: 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<2>. 
* Obsolescence: Obsolescence<3>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12. 
* Retraits: Retraits<3>. 
* Portage vers Python 3.11: Portage vers Python 3 11. 
* Changements à la compilation: Changements à la compilation<3>. 
* Changements à l'API C: Changements à l'API C<3>. 
* Notable changes in 3.11.4: Notable changes in 3 11 4. 
* Notable changes in 3.11.5: Notable changes in 3 11 5. 

Nouvelles fonctionnalités

* PEP 657 ; amélioration de l'emplacement des erreurs dans les traces d'appels: PEP 657 amélioration de l'emplacement des erreurs dans les traces d'appels. 
* PEP 654 ; Groupes d'exception et except*: PEP 654 Groupes d'exception et except*. 
* PEP 678; Exceptions can be enriched with notes: PEP 678 Exceptions can be enriched with notes. 
* Améliorations du lanceur Windows py.exe: Améliorations du lanceur Windows py exe. 

Nouvelles fonctionnalités reliées aux indications de types

* PEP 646; Variadic generics: PEP 646 Variadic generics. 
* PEP 655; Marking individual TypedDict items as required or not-required: PEP 655 Marking individual TypedDict items as required or not-required. 
* PEP 673; Self type: PEP 673 Self type. 
* PEP 675; Arbitrary literal string type: PEP 675 Arbitrary literal string type. 
* PEP 681; Data class transforms: PEP 681 Data class transforms. 
* PEP 563 may not be the future:: 

Modules améliorés

* asyncio: asyncio<3>. 
* contextlib:: 
* dataclasses:: 
* datetime:: 
* enum: enum<3>. 
* fcntl:: 
* fractions: fractions<3>. 
* functools:: 
* gzip: gzip<2>. 
* hashlib: hashlib<2>. 
* IDLE et idlelib:: 
* inspect: inspect<2>. 
* locale: locale<3>. 
* logging:: 
* math: math<3>. 
* operator:: 
* os: os<3>. 
* pathlib: pathlib<4>. 
* re: re<3>. 
* shutils: shutils<3>. 
* socket:: 
* sqlite3: sqlite3<4>. 
* string:: 
* sys: sys<4>. 
* sysconfig:: 
* tempfile: tempfile<3>. 
* threading: threading<2>. 
* time: time<2>. 
* tkinter: tkinter<3>. 
* traceback: traceback<2>. 
* typing: typing<4>. 
* unicodedata: unicodedata<3>. 
* unittest: unittest<4>. 
* venv: venv<2>. 
* warnings: warnings<2>. 
* zipfile:: 

Faster CPython

* Faster Startup:: 
* Faster Runtime:: 
* Misc:: 
* FAQ:: 
* À propos:: 

Faster Startup

* Frozen imports / Static code objects:: 

Faster Runtime

* Cheaper@comma{} lazy Python frames: Cheaper lazy Python frames. 
* Inlined Python function calls:: 
* PEP 659; Specializing Adaptive Interpreter: PEP 659 Specializing Adaptive Interpreter. 

FAQ

* How should I write my code to utilize these speedups?:: 
* Will CPython 3.11 use more memory?: Will CPython 3 11 use more memory?. 
* I don't see any speedups in my workload. Why?: I don't see any speedups in my workload Why?. 
* Is there a JIT compiler?:: 

Changements au code intermédiaire CPython

* New opcodes:: 
* Replaced opcodes:: 
* Changed/removed opcodes:: 

Obsolescence

* Language/Builtins:: 
* Modules:: 
* Bibliothèque Standard:: 

Changements à l'API C

* Nouvelles fonctionnalités: Nouvelles fonctionnalités<6>. 
* Portage vers Python 3.11: Portage vers Python 3 11<2>. 
* Obsolescence: Obsolescence<4>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12<2>. 
* Retraits: Retraits<4>. 

Notable changes in 3.11.4

* tarfile:: 

Notable changes in 3.11.5

* OpenSSL:: 

Les nouveautés de Python 3.10

* Résumé – Points forts de la publication: Résumé – Points forts de la publication<2>. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<7>. 
* Nouvelles fonctionnalités reliées aux indications de types: Nouvelles fonctionnalités reliées aux indications de types<3>. 
* Autres changements au langage: Autres changements au langage<4>. 
* Nouveaux modules: Nouveaux modules<4>. 
* Modules améliorés: Modules améliorés<4>. 
* Optimisations: Optimisations<4>. 
* Obsolescence: Obsolescence<5>. 
* Retrait:: 
* Portage vers Python 3.10: Portage vers Python 3 10. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<3>. 
* Changements à la compilation: Changements à la compilation<4>. 
* Changements à l'API C: Changements à l'API C<4>. 
* Notable security feature in 3.10.7: Notable security feature in 3 10 7. 
* Notable security feature in 3.10.8: Notable security feature in 3 10 8. 
* Notable changes in 3.10.12: Notable changes in 3 10 12. 

Nouvelles fonctionnalités

* Gestionnaires de contextes entre parenthèses:: 
* Meilleurs messages d'erreurs:: 
* PEP 626 ; numéros de lignes précis pour le débogage et les autres outils: PEP 626 numéros de lignes précis pour le débogage et les autres outils. 
* PEP 634 ; filtrage par motifs structurels: PEP 634 filtrage par motifs structurels. 
* EncodingWarning et option encoding="locale" optionnels:: 

Meilleurs messages d'erreurs

* SyntaxError:: 
* IndentationError:: 
* AttributeError:: 
* NameError:: 

PEP 634 : filtrage par motifs structurels

* Syntaxe et opérations:: 
* Approche déclarative:: 
* Filtre simple ; apparier à un littéral: Filtre simple apparier à un littéral. 
* Filtres avec un littéral et une variable:: 
* Filtres et classes:: 
* Filtres imbriqués:: 
* Filtres complexes et attrape-tout:: 
* Garde:: 
* Autres fonctionnalités importantes:: 

Filtre simple : apparier à un littéral

* Comportement sans l'attrape-tout:: 

Filtres et classes

* Filtres avec arguments positionnels:: 

Nouvelles fonctionnalités reliées aux indications de types

* PEP 604 ; nouvel opérateur d'union de types: PEP 604 nouvel opérateur d'union de types. 
* PEP 612 ; variables de spécification de paramètres: PEP 612 variables de spécification de paramètres. 
* PEP 613 ; TypeAlias: PEP 613 TypeAlias. 
* PEP 647 ; gardes de type définies par l'utilisateur: PEP 647 gardes de type définies par l'utilisateur. 

Modules améliorés

* asyncio: asyncio<4>. 
* argparse: argparse<2>. 
* array: array<3>. 
* asynchat@comma{} asyncore@comma{} smtpd: asynchat asyncore smtpd. 
* base64: base64<2>. 
* bdb:: 
* bisect:: 
* codecs:: 
* collections.abc: collections abc. 
* contextlib: contextlib<2>. 
* curses:: 
* dataclasses: dataclasses<2>. 
* distutils: distutils<2>. 
* doctest: doctest<2>. 
* encodings:: 
* enum: enum<4>. 
* fileinput:: 
* faulthandler:: 
* gc:: 
* glob: glob<2>. 
* hashlib: hashlib<3>. 
* hmac:: 
* IDLE et idlelib: IDLE et idlelib<2>. 
* importlib.metadata: importlib metadata<2>. 
* inspect: inspect<3>. 
* itertools: itertools<3>. 
* linecache:: 
* os: os<4>. 
* os.path: os path<3>. 
* pathlib: pathlib<5>. 
* platform:: 
* pprint:: 
* py_compile:: 
* pyclbr:: 
* shelve:: 
* statistics: statistics<3>. 
* site: site<2>. 
* socket: socket<2>. 
* ssl: ssl<3>. 
* sqlite3: sqlite3<5>. 
* sys: sys<5>. 
* _thread:: 
* threading: threading<3>. 
* traceback: traceback<3>. 
* types: types<3>. 
* typing: typing<5>. 
* unittest: unittest<5>. 
* urllib.parse: urllib parse. 
* xml: xml<2>. 
* zipimport: zipimport<3>. 

dataclasses

* __slots__:: 
* Champs obligatoirement nommés:: 

Portage vers Python 3.10

* Changements à la syntaxe de Python:: 
* Changements dans l'API Python: Changements dans l'API Python<3>. 
* Changements dans l'API C: Changements dans l'API C<2>. 

Changements à l'API C

* PEP 652 ; maintenance d'une ABI stable: PEP 652 maintenance d'une ABI stable. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<8>. 
* Portage vers Python 3.10: Portage vers Python 3 10<2>. 
* Obsolescence: Obsolescence<6>. 
* Retrait: Retrait<2>. 

Notable changes in 3.10.12

* tarfile: tarfile<2>. 

Les nouveautés de Python 3.9

* Résumé – Points marquants de cette version: Résumé – Points marquants de cette version<2>. 
* Vous devez vérifier la présence de DeprecationWarning dans votre code:: 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<9>. 
* Autres changements au langage: Autres changements au langage<5>. 
* Nouveaux modules: Nouveaux modules<5>. 
* Modules améliorés: Modules améliorés<5>. 
* Optimisations: Optimisations<5>. 
* Obsolescence: Obsolescence<7>. 
* Retraits: Retraits<5>. 
* Portage vers Python 3.9: Portage vers Python 3 9. 
* Changements à la compilation: Changements à la compilation<5>. 
* Changements à l'API C: Changements à l'API C<5>. 
* Changements importants dans Python 3.9.1: Changements importants dans Python 3 9 1. 
* Changements importants dans Python 3.9.2: Changements importants dans Python 3 9 2. 
* Notable changes in Python 3.9.3: Notable changes in Python 3 9 3. 
* Notable changes in Python 3.9.5: Notable changes in Python 3 9 5. 
* Notable security feature in 3.9.14: Notable security feature in 3 9 14. 
* Notable changes in 3.9.17: Notable changes in 3 9 17. 

Nouvelles fonctionnalités

* Opérateurs de fusion et de mise à jour de dictionnaires:: 
* Nouvelles méthodes sur les chaînes pour retirer des préfixes et des suffixes:: 
* Indication des types paramétrables dans les collections natives:: 
* Nouvel analyseur syntaxique:: 

Nouveaux modules

* zoneinfo:: 
* graphlib:: 

Modules améliorés

* ast: ast<2>. 
* asyncio: asyncio<5>. 
* compileall: compileall<2>. 
* concurrent.futures: concurrent futures<2>. 
* curses: curses<2>. 
* datetime: datetime<2>. 
* distutils: distutils<3>. 
* fcntl: fcntl<2>. 
* ftplib: ftplib<2>. 
* gc: gc<2>. 
* hashlib: hashlib<4>. 
* http:: 
* IDLE et idlelib: IDLE et idlelib<3>. 
* imaplib:: 
* importlib: importlib<3>. 
* inspect: inspect<4>. 
* ipaddress: ipaddress<2>. 
* math: math<4>. 
* multiprocessing: multiprocessing<2>. 
* nntplib:: 
* os: os<5>. 
* pathlib: pathlib<6>. 
* pdb: pdb<3>. 
* poplib:: 
* pprint: pprint<2>. 
* pydoc:: 
* random: random<3>. 
* signal:: 
* smtplib:: 
* socket: socket<3>. 
* time: time<3>. 
* sys: sys<6>. 
* tracemalloc:: 
* typing: typing<6>. 
* unicodedata: unicodedata<4>. 
* venv: venv<3>. 
* xml: xml<3>. 

Portage vers Python 3.9

* Changements dans l'API Python: Changements dans l'API Python<4>. 
* Changements dans l'API C: Changements dans l'API C<3>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<4>. 

Changements à l'API C

* Nouvelles fonctionnalités: Nouvelles fonctionnalités<10>. 
* Portage vers Python 3.9: Portage vers Python 3 9<2>. 
* Retraits: Retraits<6>. 

Changements importants dans Python 3.9.1

* typing: typing<7>. 
* Prise en charge de macOS 11.0 (Big Sur) et de Mac sur processeur Apple: Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple. 

Changements importants dans Python 3.9.2

* collections.abc: collections abc<2>. 
* urllib.parse: urllib parse<2>. 

Notable changes in Python 3.9.5

* urllib.parse: urllib parse<3>. 

Notable changes in 3.9.17

* tarfile: tarfile<3>. 

Nouveautés de Python 3.8

* Summary: Summary -- Release highlights. Release highlights
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<11>. 
* Autres changements au langage: Autres changements au langage<6>. 
* Nouveaux modules: Nouveaux modules<6>. 
* Modules améliorés: Modules améliorés<6>. 
* Optimizations:: 
* Build and C API Changes:: 
* Obsolescence: Obsolescence<8>. 
* API and Feature Removals:: 
* Porting to Python 3.8: Porting to Python 3 8. 
* Notable changes in Python 3.8.1: Notable changes in Python 3 8 1. 
* Notable changes in Python 3.8.2: Notable changes in Python 3 8 2. 
* Notable changes in Python 3.8.3: Notable changes in Python 3 8 3. 
* Notable changes in Python 3.8.8: Notable changes in Python 3 8 8. 
* Notable changes in Python 3.8.9: Notable changes in Python 3 8 9. 
* Notable changes in Python 3.8.10: Notable changes in Python 3 8 10. 
* Notable changes in Python 3.8.10: Notable changes in Python 3 8 10<2>. 
* Notable changes in Python 3.8.12: Notable changes in Python 3 8 12. 
* Notable security feature in 3.8.14: Notable security feature in 3 8 14. 
* Notable changes in 3.8.17: Notable changes in 3 8 17. 

Nouvelles fonctionnalités

* Expression d'affectation:: 
* Positional-only parameters:: 
* Parallel filesystem cache for compiled bytecode files:: 
* Debug build uses the same ABI as release build:: 
* f-strings support = for self-documenting expressions and debugging:: 
* PEP 578; Python Runtime Audit Hooks: PEP 578 Python Runtime Audit Hooks. 
* PEP 587; Python Initialization Configuration: PEP 587 Python Initialization Configuration. 
* PEP 590; Vectorcall; a fast calling protocol for CPython: PEP 590 Vectorcall a fast calling protocol for CPython. 
* Pickle protocol 5 with out-of-band data buffers:: 

Modules améliorés

* ast: ast<3>. 
* asyncio: asyncio<6>. 
* builtins: builtins<2>. 
* collections:: 
* cProfile:: 
* csv: csv<2>. 
* curses: curses<3>. 
* ctypes: ctypes<2>. 
* datetime: datetime<3>. 
* functools: functools<2>. 
* gc: gc<3>. 
* gettext:: 
* gzip: gzip<3>. 
* IDLE et idlelib: IDLE et idlelib<4>. 
* inspect: inspect<5>. 
* io: io<3>. 
* itertools: itertools<4>. 
* json.tool: json tool. 
* logging: logging<2>. 
* math: math<5>. 
* mmap: mmap<2>. 
* multiprocessing: multiprocessing<3>. 
* os: os<6>. 
* os.path: os path<4>. 
* pathlib: pathlib<7>. 
* pickle:: 
* plistlib:: 
* pprint: pprint<3>. 
* py_compile: py_compile<2>. 
* shlex:: 
* shutils: shutils<4>. 
* socket: socket<4>. 
* ssl: ssl<4>. 
* statistics: statistics<4>. 
* sys: sys<7>. 
* tarfile: tarfile<4>. 
* threading: threading<4>. 
* tokenize: tokenize<2>. 
* tkinter: tkinter<4>. 
* time: time<4>. 
* typing: typing<8>. 
* unicodedata: unicodedata<5>. 
* unittest: unittest<6>. 
* venv: venv<4>. 
* weakref:: 
* xml: xml<4>. 
* xmlrpc:: 

Porting to Python 3.8

* Changes in Python behavior:: 
* Changements dans l'API Python: Changements dans l'API Python<5>. 
* Changements dans l'API C: Changements dans l'API C<4>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<5>. 
* Demos and Tools: Demos and Tools<2>. 

Notable changes in Python 3.8.10

* Prise en charge de macOS 11.0 (Big Sur) et de Mac sur processeur Apple: Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple<2>. 

Notable changes in Python 3.8.10

* urllib.parse: urllib parse<4>. 

Notable changes in Python 3.8.12

* Changements dans l'API Python: Changements dans l'API Python<6>. 

Notable changes in 3.8.17

* tarfile: tarfile<5>. 

What's New In Python 3.7

* Summary: Summary -- Release Highlights<2>. Release Highlights
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<12>. 
* Autres changements au langage: Autres changements au langage<7>. 
* Nouveaux modules: Nouveaux modules<7>. 
* Modules améliorés: Modules améliorés<7>. 
* Changements à l'API C: Changements à l'API C<6>. 
* Changements à la compilation: Changements à la compilation<6>. 
* Optimizations: Optimizations<2>. 
* Autres changements à l'implémentation de CPython: Autres changements à l'implémentation de CPython<2>. 
* Deprecated Python Behavior:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods. 
* Deprecated functions and types of the C API:: 
* Platform Support Removals:: 
* API and Feature Removals: API and Feature Removals<2>. 
* Module Removals:: 
* Windows-only Changes:: 
* Porting to Python 3.7: Porting to Python 3 7. 
* Notable changes in Python 3.7.1: Notable changes in Python 3 7 1. 
* Notable changes in Python 3.7.2: Notable changes in Python 3 7 2. 
* Notable changes in Python 3.7.6: Notable changes in Python 3 7 6. 
* Notable changes in Python 3.7.10: Notable changes in Python 3 7 10. 
* Notable changes in Python 3.7.11: Notable changes in Python 3 7 11. 
* Notable security feature in 3.7.14: Notable security feature in 3 7 14. 

Nouvelles fonctionnalités

* PEP 563; Postponed Evaluation of Annotations: PEP 563 Postponed Evaluation of Annotations. 
* PEP 538; Legacy C Locale Coercion: PEP 538 Legacy C Locale Coercion. 
* PEP 540; Forced UTF-8 Runtime Mode: PEP 540 Forced UTF-8 Runtime Mode. 
* PEP 553; Built-in breakpoint(): PEP 553 Built-in breakpoint. 
* PEP 539; New C API for Thread-Local Storage: PEP 539 New C API for Thread-Local Storage. 
* PEP 562; Customization of Access to Module Attributes: PEP 562 Customization of Access to Module Attributes. 
* PEP 564; New Time Functions With Nanosecond Resolution: PEP 564 New Time Functions With Nanosecond Resolution. 
* PEP 565; Show DeprecationWarning in __main__: PEP 565 Show DeprecationWarning in __main__. 
* PEP 560; Core Support for typing module and Generic Types: PEP 560 Core Support for typing module and Generic Types. 
* PEP 552; Hash-based .pyc Files: PEP 552 Hash-based pyc Files. 
* PEP 545; Python Documentation Translations: PEP 545 Python Documentation Translations. 
* Python Development Mode (-X dev): Python Development Mode -X dev. 

Nouveaux modules

* contextvars:: 
* dataclasses: dataclasses<3>. 
* importlib.resources: importlib resources<2>. 

Modules améliorés

* argparse: argparse<3>. 
* asyncio: asyncio<7>. 
* binascii:: 
* calendar: calendar<2>. 
* collections: collections<2>. 
* compileall: compileall<3>. 
* concurrent.futures: concurrent futures<3>. 
* contextlib: contextlib<3>. 
* cProfile: cProfile<2>. 
* crypt:: 
* datetime: datetime<4>. 
* dbm: dbm<2>. 
* decimal:: 
* dis: dis<3>. 
* distutils: distutils<4>. 
* enum: enum<5>. 
* functools: functools<3>. 
* gc: gc<4>. 
* hmac: hmac<2>. 
* http.client: http client. 
* http.server: http server. 
* idlelib and IDLE:: 
* importlib: importlib<4>. 
* io: io<4>. 
* ipaddress: ipaddress<3>. 
* itertools: itertools<5>. 
* locale: locale<4>. 
* logging: logging<3>. 
* math: math<6>. 
* mimetypes: mimetypes<2>. 
* msilib:: 
* multiprocessing: multiprocessing<4>. 
* os: os<7>. 
* pathlib: pathlib<8>. 
* pdb: pdb<4>. 
* py_compile: py_compile<3>. 
* pydoc: pydoc<2>. 
* queue: queue<2>. 
* re: re<4>. 
* signal: signal<2>. 
* socket: socket<5>. 
* socketserver:: 
* sqlite3: sqlite3<6>. 
* ssl: ssl<5>. 
* string: string<2>. 
* subprocess: subprocess<2>. 
* sys: sys<8>. 
* time: time<5>. 
* tkinter: tkinter<5>. 
* tracemalloc: tracemalloc<2>. 
* types: types<4>. 
* unicodedata: unicodedata<6>. 
* unittest: unittest<7>. 
* unittest.mock: unittest mock. 
* urllib.parse: urllib parse<5>. 
* uu:: 
* uuid: uuid<2>. 
* warnings: warnings<3>. 
* xml: xml<5>. 
* xml.etree: xml etree. 
* xmlrpc.server: xmlrpc server. 
* zipapp:: 
* zipfile: zipfile<2>. 

Deprecated Python modules, functions and methods

* aifc:: 
* asyncio: asyncio<8>. 
* collections: collections<3>. 
* dbm: dbm<3>. 
* enum: enum<6>. 
* gettext: gettext<2>. 
* importlib: importlib<5>. 
* locale: locale<5>. 
* macpath:: 
* threading: threading<5>. 
* socket: socket<6>. 
* ssl: ssl<6>. 
* sunau:: 
* sys: sys<9>. 
* wave:: 

Porting to Python 3.7

* Changes in Python Behavior:: 
* Changements dans l'API Python: Changements dans l'API Python<7>. 
* Changements dans l'API C: Changements dans l'API C<5>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<6>. 
* Windows-only Changes: Windows-only Changes<2>. 
* Other CPython implementation changes:: 

What's New In Python 3.6

* Résumé – Points forts de la publication: Résumé – Points forts de la publication<3>. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<13>. 
* Autres changements au langage: Autres changements au langage<8>. 
* Nouveaux modules: Nouveaux modules<8>. 
* Modules améliorés: Modules améliorés<8>. 
* Optimizations: Optimizations<3>. 
* Build and C API Changes: Build and C API Changes<2>. 
* Autres Améliorations:: 
* Obsolescence: Obsolescence<9>. 
* Retraits: Retraits<7>. 
* Porting to Python 3.6: Porting to Python 3 6. 
* Notable changes in Python 3.6.2: Notable changes in Python 3 6 2. 
* Notable changes in Python 3.6.4: Notable changes in Python 3 6 4. 
* Notable changes in Python 3.6.5: Notable changes in Python 3 6 5. 
* Notable changes in Python 3.6.7: Notable changes in Python 3 6 7. 
* Notable changes in Python 3.6.10: Notable changes in Python 3 6 10. 
* Notable changes in Python 3.6.13: Notable changes in Python 3 6 13. 
* Notable changes in Python 3.6.14: Notable changes in Python 3 6 14. 

Nouvelles fonctionnalités

* PEP 498; Formatted string literals: PEP 498 Formatted string literals. 
* PEP 526; Syntax for variable annotations: PEP 526 Syntax for variable annotations. 
* PEP 515; Underscores in Numeric Literals: PEP 515 Underscores in Numeric Literals. 
* PEP 525; Asynchronous Generators: PEP 525 Asynchronous Generators. 
* PEP 530; Asynchronous Comprehensions: PEP 530 Asynchronous Comprehensions. 
* PEP 487; Simpler customization of class creation: PEP 487 Simpler customization of class creation. 
* PEP 487; Descriptor Protocol Enhancements: PEP 487 Descriptor Protocol Enhancements. 
* PEP 519; Adding a file system path protocol: PEP 519 Adding a file system path protocol. 
* PEP 495; Local Time Disambiguation: PEP 495 Local Time Disambiguation. 
* PEP 529; Change Windows filesystem encoding to UTF-8: PEP 529 Change Windows filesystem encoding to UTF-8. 
* PEP 528; Change Windows console encoding to UTF-8: PEP 528 Change Windows console encoding to UTF-8. 
* PEP 520; Preserving Class Attribute Definition Order: PEP 520 Preserving Class Attribute Definition Order. 
* PEP 468; Preserving Keyword Argument Order: PEP 468 Preserving Keyword Argument Order. 
* New dict implementation:: 
* PEP 523; Adding a frame evaluation API to CPython: PEP 523 Adding a frame evaluation API to CPython. 
* PYTHONMALLOC environment variable:: 
* DTrace and SystemTap probing support:: 

Nouveaux modules

* secrets:: 

Modules améliorés

* array: array<4>. 
* ast: ast<4>. 
* asyncio: asyncio<9>. 
* binascii: binascii<2>. 
* cmath:: 
* collections: collections<4>. 
* concurrent.futures: concurrent futures<4>. 
* contextlib: contextlib<4>. 
* datetime: datetime<5>. 
* decimal: decimal<2>. 
* distutils: distutils<5>. 
* email: email<2>. 
* encodings: encodings<2>. 
* enum: enum<7>. 
* faulthandler: faulthandler<2>. 
* fileinput: fileinput<2>. 
* hashlib: hashlib<5>. 
* http.client: http client<2>. 
* idlelib and IDLE: idlelib and IDLE<2>. 
* importlib: importlib<6>. 
* inspect: inspect<6>. 
* json:: 
* logging: logging<4>. 
* math: math<7>. 
* multiprocessing: multiprocessing<5>. 
* os: os<8>. 
* pathlib: pathlib<9>. 
* pdb: pdb<5>. 
* pickle: pickle<2>. 
* pickletools:: 
* pydoc: pydoc<3>. 
* random: random<4>. 
* re: re<5>. 
* readline:: 
* rlcompleter:: 
* shlex: shlex<2>. 
* site: site<3>. 
* sqlite3: sqlite3<7>. 
* socket: socket<7>. 
* socketserver: socketserver<2>. 
* ssl: ssl<7>. 
* statistics: statistics<5>. 
* struct:: 
* subprocess: subprocess<3>. 
* sys: sys<10>. 
* telnetlib:: 
* time: time<6>. 
* timeit:: 
* tkinter: tkinter<6>. 
* traceback: traceback<4>. 
* tracemalloc: tracemalloc<3>. 
* typing: typing<9>. 
* unicodedata: unicodedata<7>. 
* unittest.mock: unittest mock<2>. 
* urllib.request: urllib request. 
* urllib.robotparser: urllib robotparser. 
* venv: venv<5>. 
* warnings: warnings<4>. 
* winreg:: 
* winsound:: 
* xmlrpc.client: xmlrpc client. 
* zipfile: zipfile<3>. 
* zlib:: 

Obsolescence

* Nouveaux mot-clefs:: 
* Deprecated Python behavior:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<2>. 
* xml: xml<6>. 
* Deprecated functions and types of the C API: Deprecated functions and types of the C API<2>. 
* Deprecated Build Options:: 

Deprecated Python modules, functions and methods

* asynchat:: 
* asyncore:: 
* dbm: dbm<4>. 
* distutils: distutils<6>. 
* grp:: 
* importlib: importlib<7>. 
* os: os<9>. 
* re: re<6>. 
* ssl: ssl<8>. 
* tkinter: tkinter<7>. 
* venv: venv<6>. 

Retraits

* API and Feature Removals: API and Feature Removals<3>. 

Porting to Python 3.6

* Changes in 'python' Command Behavior:: 
* Changements dans l'API Python: Changements dans l'API Python<8>. 
* Changements dans l'API C: Changements dans l'API C<6>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<7>. 

Notable changes in Python 3.6.2

* New make regen-all build target:: 
* Removal of make touch build target:: 

Nouveautés de Python 3.5

* Résumé – Points forts de la publication: Résumé – Points forts de la publication<4>. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<14>. 
* Autres changements au langage: Autres changements au langage<9>. 
* Nouveaux modules: Nouveaux modules<9>. 
* Modules améliorés: Modules améliorés<9>. 
* Other module-level changes:: 
* Optimizations: Optimizations<4>. 
* Build and C API Changes: Build and C API Changes<3>. 
* Obsolescence: Obsolescence<10>. 
* Retraits: Retraits<8>. 
* Portage vers Python 3.5: Portage vers Python 3 5. 
* Notable changes in Python 3.5.4: Notable changes in Python 3 5 4. 

Nouvelles fonctionnalités

* PEP 492 - Coroutines with async and await syntax:: 
* PEP 465 - A dedicated infix operator for matrix multiplication:: 
* PEP 448 - Additional Unpacking Generalizations:: 
* PEP 461 - percent formatting support for bytes and bytearray:: 
* PEP 484 - Type Hints:: 
* PEP 471 - os.scandir() function: PEP 471 - os scandir function -- a better and faster directory iterator. a better and faster directory iterator
* PEP 475; Retry system calls failing with EINTR: PEP 475 Retry system calls failing with EINTR. 
* PEP 479; Change StopIteration handling inside generators: PEP 479 Change StopIteration handling inside generators. 
* PEP 485; A function for testing approximate equality: PEP 485 A function for testing approximate equality. 
* PEP 486; Make the Python Launcher aware of virtual environments: PEP 486 Make the Python Launcher aware of virtual environments. 
* PEP 488 ; Élimination des fichiers PYO: PEP 488 Élimination des fichiers PYO. 
* PEP 489; Multi-phase extension module initialization: PEP 489 Multi-phase extension module initialization. 

Nouveaux modules

* typing: typing<10>. 
* zipapp: zipapp<2>. 

Modules améliorés

* argparse: argparse<4>. 
* asyncio: asyncio<10>. 
* bz2:: 
* cgi:: 
* cmath: cmath<2>. 
* code:: 
* collections: collections<5>. 
* collections.abc: collections abc<3>. 
* compileall: compileall<4>. 
* concurrent.futures: concurrent futures<5>. 
* configparser: configparser<4>. 
* contextlib: contextlib<5>. 
* csv: csv<3>. 
* curses: curses<4>. 
* dbm: dbm<5>. 
* difflib:: 
* distutils: distutils<7>. 
* doctest: doctest<3>. 
* email: email<3>. 
* enum: enum<8>. 
* faulthandler: faulthandler<3>. 
* functools: functools<4>. 
* glob: glob<3>. 
* gzip: gzip<4>. 
* heapq:: 
* http: http<2>. 
* http.client: http client<3>. 
* idlelib and IDLE: idlelib and IDLE<3>. 
* imaplib: imaplib<2>. 
* imghdr:: 
* importlib: importlib<8>. 
* inspect: inspect<7>. 
* io: io<5>. 
* ipaddress: ipaddress<4>. 
* json: json<2>. 
* linecache: linecache<2>. 
* locale: locale<6>. 
* logging: logging<5>. 
* lzma:: 
* math: math<8>. 
* multiprocessing: multiprocessing<6>. 
* operator: operator<2>. 
* os: os<10>. 
* pathlib: pathlib<10>. 
* pickle: pickle<3>. 
* poplib: poplib<2>. 
* re: re<7>. 
* readline: readline<2>. 
* selectors:: 
* shutils: shutils<5>. 
* signal: signal<3>. 
* smtpd: smtpd<2>. 
* smtplib: smtplib<2>. 
* sndhdr:: 
* socket: socket<8>. 
* ssl: ssl<9>. 
* sqlite3: sqlite3<8>. 
* subprocess: subprocess<4>. 
* sys: sys<11>. 
* sysconfig: sysconfig<2>. 
* tarfile: tarfile<6>. 
* threading: threading<6>. 
* time: time<7>. 
* timeit: timeit<2>. 
* tkinter: tkinter<8>. 
* traceback: traceback<5>. 
* types: types<5>. 
* unicodedata: unicodedata<8>. 
* unittest: unittest<8>. 
* unittest.mock: unittest mock<3>. 
* urllib: urllib<2>. 
* wsgiref:: 
* xmlrpc: xmlrpc<2>. 
* xml.sax: xml sax. 
* zipfile: zipfile<4>. 

ssl

* Memory BIO Support:: 
* Application-Layer Protocol Negotiation Support:: 
* Other Changes:: 

Obsolescence

* Nouveaux mot-clefs: Nouveaux mot-clefs<2>. 
* Deprecated Python Behavior: Deprecated Python Behavior<2>. 
* Unsupported Operating Systems:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<3>. 

Retraits

* API and Feature Removals: API and Feature Removals<4>. 

Portage vers Python 3.5

* Changes in Python behavior: Changes in Python behavior<2>. 
* Changements dans l'API Python: Changements dans l'API Python<9>. 
* Changements dans l'API C: Changements dans l'API C<7>. 

Notable changes in Python 3.5.4

* New make regen-all build target: New make regen-all build target<2>. 
* Removal of make touch build target: Removal of make touch build target<2>. 

Nouveautés de Python 3.4

* Summary: Summary -- Release Highlights<3>. Release Highlights
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<15>. 
* Nouveaux modules: Nouveaux modules<10>. 
* Modules améliorés: Modules améliorés<10>. 
* CPython Implementation Changes:: 
* Obsolescence: Obsolescence<11>. 
* Retraits: Retraits<9>. 
* Portage vers Python 3.4: Portage vers Python 3 4. 
* Changed in 3.4.3: Changed in 3 4 3. 

Nouvelles fonctionnalités

* PEP 453; Explicit Bootstrapping of PIP in Python Installations: PEP 453 Explicit Bootstrapping of PIP in Python Installations. 
* PEP 446; Newly Created File Descriptors Are Non-Inheritable: PEP 446 Newly Created File Descriptors Are Non-Inheritable. 
* Improvements to Codec Handling:: 
* PEP 451; A ModuleSpec Type for the Import System: PEP 451 A ModuleSpec Type for the Import System. 
* Autres changements au langage: Autres changements au langage<10>. 

PEP 453: Explicit Bootstrapping of PIP in Python Installations

* Bootstrapping pip By Default:: 
* Documentation Changes:: 

Nouveaux modules

* asyncio: asyncio<11>. 
* ensurepip: ensurepip<2>. 
* enum: enum<9>. 
* pathlib: pathlib<11>. 
* selectors: selectors<2>. 
* statistics: statistics<6>. 
* tracemalloc: tracemalloc<4>. 

Modules améliorés

* abc:: 
* aifc: aifc<2>. 
* argparse: argparse<5>. 
* audioop:: 
* base64: base64<3>. 
* collections: collections<6>. 
* colorsys:: 
* contextlib: contextlib<6>. 
* dbm: dbm<6>. 
* dis: dis<4>. 
* doctest: doctest<4>. 
* email: email<4>. 
* filecmp:: 
* functools: functools<5>. 
* gc: gc<5>. 
* glob: glob<4>. 
* hashlib: hashlib<6>. 
* hmac: hmac<3>. 
* html:: 
* http: http<3>. 
* idlelib and IDLE: idlelib and IDLE<4>. 
* importlib: importlib<9>. 
* inspect: inspect<8>. 
* ipaddress: ipaddress<5>. 
* logging: logging<6>. 
* marshal: marshal<2>. 
* mmap: mmap<3>. 
* multiprocessing: multiprocessing<7>. 
* operator: operator<3>. 
* os: os<11>. 
* pdb: pdb<6>. 
* pickle: pickle<4>. 
* plistlib: plistlib<2>. 
* poplib: poplib<3>. 
* pprint: pprint<4>. 
* pty:: 
* pydoc: pydoc<4>. 
* re: re<8>. 
* resource:: 
* select:: 
* shelve: shelve<2>. 
* shutils: shutils<6>. 
* smtpd: smtpd<3>. 
* smtplib: smtplib<3>. 
* socket: socket<9>. 
* sqlite3: sqlite3<9>. 
* ssl: ssl<10>. 
* stat:: 
* struct: struct<2>. 
* subprocess: subprocess<5>. 
* sunau: sunau<2>. 
* sys: sys<12>. 
* tarfile: tarfile<7>. 
* textwrap:: 
* threading: threading<7>. 
* traceback: traceback<6>. 
* types: types<6>. 
* urllib: urllib<3>. 
* unittest: unittest<9>. 
* venv: venv<7>. 
* wave: wave<2>. 
* weakref: weakref<2>. 
* xml.etree: xml etree<2>. 
* zipfile: zipfile<5>. 

CPython Implementation Changes

* PEP 445; Customization of CPython Memory Allocators: PEP 445 Customization of CPython Memory Allocators. 
* PEP 442; Safe Object Finalization: PEP 442 Safe Object Finalization. 
* PEP 456; Secure and Interchangeable Hash Algorithm: PEP 456 Secure and Interchangeable Hash Algorithm. 
* PEP 436; Argument Clinic: PEP 436 Argument Clinic. 
* Other Build and C API Changes:: 
* Autres Améliorations: Autres Améliorations<2>. 
* Significant Optimizations:: 

Obsolescence

* Deprecations in the Python API:: 
* Fonctionnalités obsolètes:: 

Retraits

* Operating Systems No Longer Supported:: 
* API and Feature Removals: API and Feature Removals<5>. 
* Code Cleanups:: 

Portage vers Python 3.4

* Changes in 'python' Command Behavior: Changes in 'python' Command Behavior<2>. 
* Changements dans l'API Python: Changements dans l'API Python<10>. 
* Changements dans l'API C: Changements dans l'API C<8>. 

Changed in 3.4.3

* PEP 476; Enabling certificate verification by default for stdlib http clients: PEP 476 Enabling certificate verification by default for stdlib http clients. 

Nouveautés de Python 3.3

* Résumé – Points forts de la publication: Résumé – Points forts de la publication<5>. 
* PEP 405; Virtual Environments: PEP 405 Virtual Environments. 
* PEP 420; Implicit Namespace Packages: PEP 420 Implicit Namespace Packages. 
* PEP 3118; New memoryview implementation and buffer protocol documentation: PEP 3118 New memoryview implementation and buffer protocol documentation. 
* PEP 393; Flexible String Representation: PEP 393 Flexible String Representation. 
* PEP 397; Python Launcher for Windows: PEP 397 Python Launcher for Windows. 
* PEP 3151; Reworking the OS and IO exception hierarchy: PEP 3151 Reworking the OS and IO exception hierarchy. 
* PEP 380; Syntax for Delegating to a Subgenerator: PEP 380 Syntax for Delegating to a Subgenerator. 
* PEP 409; Suppressing exception context: PEP 409 Suppressing exception context. 
* PEP 414; Explicit Unicode literals: PEP 414 Explicit Unicode literals. 
* PEP 3155; Qualified name for classes and functions: PEP 3155 Qualified name for classes and functions. 
* PEP 412; Key-Sharing Dictionary: PEP 412 Key-Sharing Dictionary. 
* PEP 362; Function Signature Object: PEP 362 Function Signature Object. 
* PEP 421; Adding sys.implementation: PEP 421 Adding sys implementation. 
* Using importlib as the Implementation of Import:: 
* Autres changements au langage: Autres changements au langage<11>. 
* A Finer-Grained Import Lock:: 
* Builtin functions and types:: 
* Nouveaux modules: Nouveaux modules<11>. 
* Modules améliorés: Modules améliorés<11>. 
* Optimizations: Optimizations<5>. 
* Build and C API Changes: Build and C API Changes<4>. 
* Obsolescence: Obsolescence<12>. 
* Portage vers Python 3.3: Portage vers Python 3 3. 

PEP 3118: New memoryview implementation and buffer protocol documentation

* Caractéristiques:: 
* API changes:: 

PEP 393: Flexible String Representation

* Functionality:: 
* Performance and resource usage:: 

PEP 421: Adding sys.implementation

* SimpleNamespace:: 

Using importlib as the Implementation of Import

* New APIs:: 
* Visible Changes:: 

Nouveaux modules

* faulthandler: faulthandler<4>. 
* ipaddress: ipaddress<6>. 
* lzma: lzma<2>. 

Modules améliorés

* abc: abc<2>. 
* array: array<5>. 
* base64: base64<4>. 
* binascii: binascii<3>. 
* bz2: bz2<2>. 
* codecs: codecs<2>. 
* collections: collections<7>. 
* contextlib: contextlib<7>. 
* crypt: crypt<2>. 
* curses: curses<5>. 
* datetime: datetime<6>. 
* decimal: decimal<3>. 
* email: email<5>. 
* ftplib: ftplib<3>. 
* functools: functools<6>. 
* gc: gc<6>. 
* hmac: hmac<4>. 
* http: http<4>. 
* html: html<2>. 
* imaplib: imaplib<3>. 
* inspect: inspect<9>. 
* io: io<6>. 
* itertools: itertools<6>. 
* logging: logging<7>. 
* math: math<9>. 
* mmap: mmap<4>. 
* multiprocessing: multiprocessing<8>. 
* nntplib: nntplib<2>. 
* os: os<12>. 
* pdb: pdb<7>. 
* pickle: pickle<5>. 
* pydoc: pydoc<5>. 
* re: re<9>. 
* sched:: 
* select: select<2>. 
* shlex: shlex<3>. 
* shutils: shutils<7>. 
* signal: signal<4>. 
* smtpd: smtpd<4>. 
* smtplib: smtplib<4>. 
* socket: socket<10>. 
* socketserver: socketserver<3>. 
* sqlite3: sqlite3<10>. 
* ssl: ssl<11>. 
* stat: stat<2>. 
* struct: struct<3>. 
* subprocess: subprocess<6>. 
* sys: sys<13>. 
* tarfile: tarfile<8>. 
* tempfile: tempfile<4>. 
* textwrap: textwrap<2>. 
* threading: threading<8>. 
* time: time<8>. 
* types: types<7>. 
* unittest: unittest<10>. 
* urllib: urllib<4>. 
* webbrowser: webbrowser<3>. 
* xml.etree.ElementTree: xml etree ElementTree<2>. 
* zlib: zlib<2>. 

decimal

* Caractéristiques: Caractéristiques<2>. 
* API changes: API changes<2>. 

email

* Policy Framework:: 
* Provisional Policy with New Header API:: 
* Other API Changes:: 

Obsolescence

* Unsupported Operating Systems: Unsupported Operating Systems<2>. 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<4>. 
* Deprecated functions and types of the C API: Deprecated functions and types of the C API<3>. 
* Fonctionnalités obsolètes: Fonctionnalités obsolètes<2>. 

Portage vers Python 3.3

* Portage de code Python:: 
* Porting C code:: 
* Building C extensions:: 
* Command Line Switch Changes:: 

Nouveautés de Python 3.2

* PEP 384; Defining a Stable ABI: PEP 384 Defining a Stable ABI. 
* PEP 389; Argparse Command Line Parsing Module: PEP 389 Argparse Command Line Parsing Module. 
* PEP 391; Dictionary Based Configuration for Logging: PEP 391 Dictionary Based Configuration for Logging. 
* PEP 3148; The concurrent.futures module: PEP 3148 The concurrent futures module. 
* PEP 3147; PYC Repository Directories: PEP 3147 PYC Repository Directories. 
* PEP 3149; ABI Version Tagged .so Files: PEP 3149 ABI Version Tagged so Files. 
* PEP 3333; Python Web Server Gateway Interface v1.0.1: PEP 3333 Python Web Server Gateway Interface v1 0 1. 
* Autres changements au langage: Autres changements au langage<12>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules. 
* Fils d'exécution:: 
* Optimizations: Optimizations<6>. 
* Unicode:: 
* Codecs:: 
* Documentation:: 
* IDLE:: 
* Code Repository:: 
* Build and C API Changes: Build and C API Changes<5>. 
* Portage vers Python 3.2: Portage vers Python 3 2. 

New, Improved, and Deprecated Modules

* email: email<6>. 
* elementtree:: 
* functools: functools<7>. 
* itertools: itertools<7>. 
* collections: collections<8>. 
* threading: threading<9>. 
* datetime and time:: 
* math: math<10>. 
* abc: abc<3>. 
* io: io<7>. 
* reprlib:: 
* logging: logging<8>. 
* csv: csv<4>. 
* contextlib: contextlib<8>. 
* decimal and fractions:: 
* ftp:: 
* popen:: 
* select: select<3>. 
* gzip and zipfile:: 
* tarfile: tarfile<9>. 
* hashlib: hashlib<7>. 
* ast: ast<5>. 
* os: os<13>. 
* shutils: shutils<8>. 
* sqlite3: sqlite3<11>. 
* html: html<3>. 
* socket: socket<11>. 
* ssl: ssl<12>. 
* nntp:: 
* certificates:: 
* imaplib: imaplib<4>. 
* http.client: http client<4>. 
* unittest: unittest<11>. 
* random: random<5>. 
* poplib: poplib<4>. 
* asyncore: asyncore<2>. 
* tempfile: tempfile<5>. 
* inspect: inspect<10>. 
* pydoc: pydoc<6>. 
* dis: dis<5>. 
* dbm: dbm<7>. 
* ctypes: ctypes<3>. 
* site: site<4>. 
* sysconfig: sysconfig<3>. 
* pdb: pdb<8>. 
* configparser: configparser<5>. 
* urllib.parse: urllib parse<6>. 
* mailbox:: 
* turtledemo:: 

Nouveautés de Python 3.1

* PEP 372; Ordered Dictionaries: PEP 372 Ordered Dictionaries. 
* PEP 378; Format Specifier for Thousands Separator: PEP 378 Format Specifier for Thousands Separator. 
* Autres changements au langage: Autres changements au langage<13>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<2>. 
* Optimizations: Optimizations<7>. 
* IDLE: IDLE<2>. 
* Build and C API Changes: Build and C API Changes<6>. 
* Portage vers Python 3.1: Portage vers Python 3 1. 

Nouveautés de Python 3.0

* Common Stumbling Blocks:: 
* Overview Of Syntax Changes:: 
* Changes Already Present In Python 2.6: Changes Already Present In Python 2 6. 
* Library Changes:: 
* PEP 3101; A New Approach To String Formatting: PEP 3101 A New Approach To String Formatting. 
* Changes To Exceptions:: 
* Miscellaneous Other Changes:: 
* Build and C API Changes: Build and C API Changes<7>. 
* Performances:: 
* Portage vers Python 3.0: Portage vers Python 3 0. 

Common Stumbling Blocks

* Print Is A Function:: 
* Views And Iterators Instead Of Lists:: 
* Ordering Comparisons:: 
* Integers:: 
* Text Vs. Data Instead Of Unicode Vs. 8-bit: Text Vs Data Instead Of Unicode Vs 8-bit. 

Overview Of Syntax Changes

* New Syntax:: 
* Changed Syntax:: 
* Removed Syntax:: 

Miscellaneous Other Changes

* Operators And Special Methods:: 
* Builtins:: 

Nouveautés de Python 2.7

* The Future for Python 2.x: The Future for Python 2 x. 
* Changes to the Handling of Deprecation Warnings:: 
* Python 3.1 Features: Python 3 1 Features. 
* PEP 372; Adding an Ordered Dictionary to collections: PEP 372 Adding an Ordered Dictionary to collections. 
* PEP 378; Format Specifier for Thousands Separator: PEP 378 Format Specifier for Thousands Separator<2>. 
* PEP 389; The argparse Module for Parsing Command Lines: PEP 389 The argparse Module for Parsing Command Lines. 
* PEP 391; Dictionary-Based Configuration For Logging: PEP 391 Dictionary-Based Configuration For Logging. 
* PEP 3106; Dictionary Views: PEP 3106 Dictionary Views. 
* PEP 3137; The memoryview Object: PEP 3137 The memoryview Object. 
* Autres changements au langage: Autres changements au langage<14>. 
* New and Improved Modules:: 
* Build and C API Changes: Build and C API Changes<8>. 
* Autres changements et corrections:: 
* Portage vers Python 2.7: Portage vers Python 2 7. 
* New Features Added to Python 2.7 Maintenance Releases: New Features Added to Python 2 7 Maintenance Releases. 
* Remerciements:: 

Autres changements au langage

* Interpreter Changes:: 
* Optimizations: Optimizations<8>. 

New and Improved Modules

* New module; importlib: New module importlib. 
* New module; sysconfig: New module sysconfig. 
* ttk; Themed Widgets for Tk: ttk Themed Widgets for Tk. 
* Updated module; unittest: Updated module unittest. 
* Module mis-à-jour ; ElementTree 1.3: Module mis-à-jour ElementTree 1 3. 

Build and C API Changes

* Capsules:: 
* Port-Specific Changes; Windows: Port-Specific Changes Windows. 
* Port-Specific Changes; Mac OS X: Port-Specific Changes Mac OS X. 
* Port-Specific Changes; FreeBSD: Port-Specific Changes FreeBSD. 

New Features Added to Python 2.7 Maintenance Releases

* Two new environment variables for debug mode:: 
* PEP 434; IDLE Enhancement Exception for All Branches: PEP 434 IDLE Enhancement Exception for All Branches. 
* PEP 466; Network Security Enhancements for Python 2.7: PEP 466 Network Security Enhancements for Python 2 7. 
* PEP 477; Backport ensurepip (PEP 453) to Python 2.7: PEP 477 Backport ensurepip PEP 453 to Python 2 7. 
* PEP 476; Enabling certificate verification by default for stdlib http clients: PEP 476 Enabling certificate verification by default for stdlib http clients<2>. 
* PEP 493; HTTPS verification migration tools for Python 2.7: PEP 493 HTTPS verification migration tools for Python 2 7. 
* New make regen-all build target: New make regen-all build target<3>. 
* Removal of make touch build target: Removal of make touch build target<3>. 

PEP 477: Backport ensurepip (PEP 453) to Python 2.7

* Bootstrapping pip By Default: Bootstrapping pip By Default<2>. 
* Documentation Changes: Documentation Changes<2>. 

Nouveautés de Python 2.6

* Python 3.0: Python 3 0. 
* Changes to the Development Process:: 
* PEP 343; The 'with' statement: PEP 343 The 'with' statement. 
* PEP 366; Explicit Relative Imports From a Main Module: PEP 366 Explicit Relative Imports From a Main Module. 
* PEP 370; Per-user site-packages Directory: PEP 370 Per-user site-packages Directory. 
* PEP 371; The multiprocessing Package: PEP 371 The multiprocessing Package. 
* PEP 3101; Advanced String Formatting: PEP 3101 Advanced String Formatting. 
* PEP 3105; print As a Function: PEP 3105 print As a Function. 
* PEP 3110; Exception-Handling Changes: PEP 3110 Exception-Handling Changes. 
* PEP 3112; Byte Literals: PEP 3112 Byte Literals. 
* PEP 3116; New I/O Library: PEP 3116 New I/O Library. 
* PEP 3118; Revised Buffer Protocol: PEP 3118 Revised Buffer Protocol. 
* PEP 3119; Abstract Base Classes: PEP 3119 Abstract Base Classes. 
* PEP 3127; Integer Literal Support and Syntax: PEP 3127 Integer Literal Support and Syntax. 
* PEP 3129; Class Decorators: PEP 3129 Class Decorators. 
* PEP 3141; A Type Hierarchy for Numbers: PEP 3141 A Type Hierarchy for Numbers. 
* Autres changements au langage: Autres changements au langage<15>. 
* New and Improved Modules: New and Improved Modules<2>. 
* Deprecations and Removals:: 
* Build and C API Changes: Build and C API Changes<9>. 
* Portage vers Python 2.6: Portage vers Python 2 6. 
* Remerciements: Remerciements<2>. 

Changes to the Development Process

* New Issue Tracker; Roundup: New Issue Tracker Roundup. 
* New Documentation Format; reStructuredText Using Sphinx: New Documentation Format reStructuredText Using Sphinx. 

PEP 343: The 'with' statement

* Écrire des gestionnaires de contexte:: 
* Le module contextlib:: 

PEP 3141: A Type Hierarchy for Numbers

* The fractions Module:: 

Autres changements au langage

* Optimizations: Optimizations<9>. 
* Interpreter Changes: Interpreter Changes<2>. 

New and Improved Modules

* The ast module:: 
* The future_builtins module:: 
* The json module; JavaScript Object Notation: The json module JavaScript Object Notation. 
* The plistlib module; A Property-List Parser: The plistlib module A Property-List Parser. 
* ctypes Enhancements:: 
* Improved SSL Support:: 

Build and C API Changes

* Port-Specific Changes; Windows: Port-Specific Changes Windows<2>. 
* Port-Specific Changes; Mac OS X: Port-Specific Changes Mac OS X<2>. 
* Port-Specific Changes; IRIX: Port-Specific Changes IRIX. 

Nouveautés de Python 2.5

* PEP 308 ; Expressions conditionnelles: PEP 308 Expressions conditionnelles. 
* PEP 309 ; Application partielle de fonction: PEP 309 Application partielle de fonction. 
* PEP 314; Metadata for Python Software Packages v1.1: PEP 314 Metadata for Python Software Packages v1 1. 
* PEP 328; Absolute and Relative Imports: PEP 328 Absolute and Relative Imports. 
* PEP 338; Executing Modules as Scripts: PEP 338 Executing Modules as Scripts. 
* PEP 341; Unified try/except/finally: PEP 341 Unified try/except/finally. 
* PEP 342; New Generator Features: PEP 342 New Generator Features. 
* PEP 343; The 'with' statement: PEP 343 The 'with' statement<2>. 
* PEP 352; Exceptions as New-Style Classes: PEP 352 Exceptions as New-Style Classes. 
* PEP 353; Using ssize_t as the index type: PEP 353 Using ssize_t as the index type. 
* PEP 357; The '__index__' method: PEP 357 The '__index__' method. 
* Autres changements au langage: Autres changements au langage<16>. 
* Modules ajoutés@comma{} modifiés@comma{} et supprimés: Modules ajoutés modifiés et supprimés. 
* Build and C API Changes: Build and C API Changes<10>. 
* Portage vers Python 2.5: Portage vers Python 2 5. 
* Remerciements: Remerciements<3>. 

PEP 343: The 'with' statement

* Écrire des gestionnaires de contexte: Écrire des gestionnaires de contexte<2>. 
* Le module contextlib: Le module contextlib<2>. 

Autres changements au langage

* Changements de l’interpréteur interactif:: 
* Optimizations: Optimizations<10>. 

Modules ajoutés, modifiés, et supprimés

* The ctypes package:: 
* The ElementTree package:: 
* The hashlib package:: 
* The sqlite3 package:: 
* The wsgiref package:: 

Build and C API Changes

* Port-Specific Changes:: 

Nouveautés de Python 2.4

* PEP 218; Built-In Set Objects: PEP 218 Built-In Set Objects. 
* PEP 237; Unifying Long Integers and Integers: PEP 237 Unifying Long Integers and Integers. 
* PEP 289; Generator Expressions: PEP 289 Generator Expressions. 
* PEP 292; Simpler String Substitutions: PEP 292 Simpler String Substitutions. 
* PEP 318; Decorators for Functions and Methods: PEP 318 Decorators for Functions and Methods. 
* PEP 322; Reverse Iteration: PEP 322 Reverse Iteration. 
* PEP 324; New subprocess Module: PEP 324 New subprocess Module. 
* PEP 327; Decimal Data Type: PEP 327 Decimal Data Type. 
* PEP 328; Multi-line Imports: PEP 328 Multi-line Imports. 
* PEP 331; Locale-Independent Float/String Conversions: PEP 331 Locale-Independent Float/String Conversions. 
* Autres changements au langage: Autres changements au langage<17>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<3>. 
* Build and C API Changes: Build and C API Changes<11>. 
* Portage vers Python 2.4: Portage vers Python 2 4. 
* Remerciements: Remerciements<4>. 

PEP 327: Decimal Data Type

* Why is Decimal needed?:: 
* The Decimal type:: 
* The Context type:: 

Autres changements au langage

* Optimizations: Optimizations<11>. 

New, Improved, and Deprecated Modules

* cookielib:: 
* doctest: doctest<5>. 

Build and C API Changes

* Port-Specific Changes: Port-Specific Changes<2>. 

Nouveautés de Python 2.3

* PEP 218; A Standard Set Datatype: PEP 218 A Standard Set Datatype. 
* PEP 255 ; Générateurs simples: PEP 255 Générateurs simples. 
* PEP 263; Source Code Encodings: PEP 263 Source Code Encodings. 
* PEP 273; Importing Modules from ZIP Archives: PEP 273 Importing Modules from ZIP Archives. 
* PEP 277; Unicode file name support for Windows NT: PEP 277 Unicode file name support for Windows NT. 
* PEP 278; Universal Newline Support: PEP 278 Universal Newline Support. 
* PEP 279; enumerate(): PEP 279 enumerate. 
* PEP 282; The logging Package: PEP 282 The logging Package. 
* PEP 285 ; Un type booléen: PEP 285 Un type booléen. 
* PEP 293; Codec Error Handling Callbacks: PEP 293 Codec Error Handling Callbacks. 
* PEP 301; Package Index and Metadata for Distutils: PEP 301 Package Index and Metadata for Distutils. 
* PEP 302; New Import Hooks: PEP 302 New Import Hooks. 
* PEP 305; Comma-separated Files: PEP 305 Comma-separated Files. 
* PEP 307; Pickle Enhancements: PEP 307 Pickle Enhancements. 
* Extended Slices:: 
* Autres changements au langage: Autres changements au langage<18>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<4>. 
* Pymalloc; A Specialized Object Allocator: Pymalloc A Specialized Object Allocator. 
* Build and C API Changes: Build and C API Changes<12>. 
* Autres changements et corrections: Autres changements et corrections<2>. 
* Portage vers Python 2.3: Portage vers Python 2 3. 
* Remerciements: Remerciements<5>. 

Autres changements au langage

* String Changes:: 
* Optimizations: Optimizations<12>. 

New, Improved, and Deprecated Modules

* Date/Time Type:: 
* The optparse Module:: 

Build and C API Changes

* Port-Specific Changes: Port-Specific Changes<3>. 

Nouveautés de Python 2.2

* Introduction:: 
* PEP 252 et 253 ; Changements concernant les types et classes: PEP 252 et 253 Changements concernant les types et classes. 
* PEP 234 ; Itérateurs: PEP 234 Itérateurs. 
* PEP 255 ; Générateurs simples: PEP 255 Générateurs simples<2>. 
* PEP 237; Unifying Long Integers and Integers: PEP 237 Unifying Long Integers and Integers<2>. 
* PEP 238; Changing the Division Operator: PEP 238 Changing the Division Operator. 
* Unicode Changes:: 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes. 
* New and Improved Modules: New and Improved Modules<3>. 
* Interpreter Changes and Fixes:: 
* Autres changements et corrections: Autres changements et corrections<3>. 
* Remerciements: Remerciements<6>. 

PEP 252 et 253 : Changements concernant les types et classes

* Anciennes et nouvelles classes:: 
* Descripteurs:: 
* Héritage multiple ; la règle du diamant: Héritage multiple la règle du diamant. 
* Attribute Access:: 
* Related Links:: 

Nouveautés de Python 2.1

* Introduction: Introduction<2>. 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes<2>. 
* PEP 236 ; Directives __future__: PEP 236 Directives __future__. 
* PEP 207; Rich Comparisons: PEP 207 Rich Comparisons. 
* PEP 230; Warning Framework: PEP 230 Warning Framework. 
* PEP 229; New Build System: PEP 229 New Build System. 
* PEP 205; Weak References: PEP 205 Weak References. 
* PEP 232 ; Attributs de fonctions: PEP 232 Attributs de fonctions. 
* PEP 235; Importing Modules on Case-Insensitive Platforms: PEP 235 Importing Modules on Case-Insensitive Platforms. 
* PEP 217; Interactive Display Hook: PEP 217 Interactive Display Hook. 
* PEP 208; New Coercion Model: PEP 208 New Coercion Model. 
* PEP 241; Metadata in Python Packages: PEP 241 Metadata in Python Packages. 
* New and Improved Modules: New and Improved Modules<4>. 
* Autres changements et corrections: Autres changements et corrections<4>. 
* Remerciements: Remerciements<7>. 

Nouveautés de Python 2.0

* Introduction: Introduction<3>. 
* À propos de Python 1.6.: À propos de Python 1 6. 
* Nouveau processus de développement:: 
* Unicode: Unicode<2>. 
* Compréhensions de listes:: 
* Opérateurs d’affectation augmentées:: 
* Méthodes de chaînes de caractères:: 
* Garbage Collection of Cycles:: 
* Other Core Changes:: 
* Porting to 2.0: Porting to 2 0. 
* Extending/Embedding Changes:: 
* Distutils; Making Modules Easy to Install: Distutils Making Modules Easy to Install. 
* Modules XML:: 
* Module changes:: 
* Nouveaux modules: Nouveaux modules<12>. 
* IDLE Improvements:: 
* Deleted and Deprecated Modules:: 
* Remerciements: Remerciements<8>. 

Other Core Changes

* Changements mineurs du langage:: 
* Changements concernant les fonctions primitives:: 

Modules XML

* Support de SAX2:: 
* Support du DOM:: 
* Relationship to PyXML:: 

Changelog

* Python next:: 
* Python 3.13.1 final: Python 3 13 1 final. 
* Python 3.13.0 final: Python 3 13 0 final. 
* Python 3.13.0 release candidate 3: Python 3 13 0 release candidate 3. 
* Python 3.13.0 release candidate 2: Python 3 13 0 release candidate 2. 
* Python 3.13.0 release candidate 1: Python 3 13 0 release candidate 1. 
* Python 3.13.0 beta 4: Python 3 13 0 beta 4. 
* Python 3.13.0 beta 3: Python 3 13 0 beta 3. 
* Python 3.13.0 beta 2: Python 3 13 0 beta 2. 
* Python 3.13.0 beta 1: Python 3 13 0 beta 1. 
* Python 3.13.0 alpha 6: Python 3 13 0 alpha 6. 
* Python 3.13.0 alpha 5: Python 3 13 0 alpha 5. 
* Python 3.13.0 alpha 4: Python 3 13 0 alpha 4. 
* Python 3.13.0 alpha 3: Python 3 13 0 alpha 3. 
* Python 3.13.0 alpha 2: Python 3 13 0 alpha 2. 
* Python 3.13.0 alpha 1: Python 3 13 0 alpha 1. 
* Python 3.12.0 beta 1: Python 3 12 0 beta 1. 
* Python 3.12.0 alpha 7: Python 3 12 0 alpha 7. 
* Python 3.12.0 alpha 6: Python 3 12 0 alpha 6. 
* Python 3.12.0 alpha 5: Python 3 12 0 alpha 5. 
* Python 3.12.0 alpha 4: Python 3 12 0 alpha 4. 
* Python 3.12.0 alpha 3: Python 3 12 0 alpha 3. 
* Python 3.12.0 alpha 2: Python 3 12 0 alpha 2. 
* Python 3.12.0 alpha 1: Python 3 12 0 alpha 1. 
* Python 3.11.0 beta 1: Python 3 11 0 beta 1. 
* Python 3.11.0 alpha 7: Python 3 11 0 alpha 7. 
* Python 3.11.0 alpha 6: Python 3 11 0 alpha 6. 
* Python 3.11.0 alpha 5: Python 3 11 0 alpha 5. 
* Python 3.11.0 alpha 4: Python 3 11 0 alpha 4. 
* Python 3.11.0 alpha 3: Python 3 11 0 alpha 3. 
* Python 3.11.0 alpha 2: Python 3 11 0 alpha 2. 
* Python 3.11.0 alpha 1: Python 3 11 0 alpha 1. 
* Python 3.10.0 beta 1: Python 3 10 0 beta 1. 
* Python 3.10.0 alpha 7: Python 3 10 0 alpha 7. 
* Python 3.10.0 alpha 6: Python 3 10 0 alpha 6. 
* Python 3.10.0 alpha 5: Python 3 10 0 alpha 5. 
* Python 3.10.0 alpha 4: Python 3 10 0 alpha 4. 
* Python 3.10.0 alpha 3: Python 3 10 0 alpha 3. 
* Python 3.10.0 alpha 2: Python 3 10 0 alpha 2. 
* Python 3.10.0 alpha 1: Python 3 10 0 alpha 1. 
* Python 3.9.0 beta 1: Python 3 9 0 beta 1. 
* Python 3.9.0 alpha 6: Python 3 9 0 alpha 6. 
* Python 3.9.0 alpha 5: Python 3 9 0 alpha 5. 
* Python 3.9.0 alpha 4: Python 3 9 0 alpha 4. 
* Python 3.9.0 alpha 3: Python 3 9 0 alpha 3. 
* Python 3.9.0 alpha 2: Python 3 9 0 alpha 2. 
* Python 3.9.0 alpha 1: Python 3 9 0 alpha 1. 
* Python 3.8.0 beta 1: Python 3 8 0 beta 1. 
* Python 3.8.0 alpha 4: Python 3 8 0 alpha 4. 
* Python 3.8.0 alpha 3: Python 3 8 0 alpha 3. 
* Python 3.8.0 alpha 2: Python 3 8 0 alpha 2. 
* Python 3.8.0 alpha 1: Python 3 8 0 alpha 1. 
* Python 3.7.0 final: Python 3 7 0 final. 
* Python 3.7.0 release candidate 1: Python 3 7 0 release candidate 1. 
* Python 3.7.0 beta 5: Python 3 7 0 beta 5. 
* Python 3.7.0 beta 4: Python 3 7 0 beta 4. 
* Python 3.7.0 beta 3: Python 3 7 0 beta 3. 
* Python 3.7.0 beta 2: Python 3 7 0 beta 2. 
* Python 3.7.0 beta 1: Python 3 7 0 beta 1. 
* Python 3.7.0 alpha 4: Python 3 7 0 alpha 4. 
* Python 3.7.0 alpha 3: Python 3 7 0 alpha 3. 
* Python 3.7.0 alpha 2: Python 3 7 0 alpha 2. 
* Python 3.7.0 alpha 1: Python 3 7 0 alpha 1. 
* Python 3.6.6 final: Python 3 6 6 final. 
* Python 3.6.6 release candidate 1: Python 3 6 6 release candidate 1. 
* Python 3.6.5 final: Python 3 6 5 final. 
* Python 3.6.5 release candidate 1: Python 3 6 5 release candidate 1. 
* Python 3.6.4 final: Python 3 6 4 final. 
* Python 3.6.4 release candidate 1: Python 3 6 4 release candidate 1. 
* Python 3.6.3 final: Python 3 6 3 final. 
* Python 3.6.3 release candidate 1: Python 3 6 3 release candidate 1. 
* Python 3.6.2 final: Python 3 6 2 final. 
* Python 3.6.2 release candidate 2: Python 3 6 2 release candidate 2. 
* Python 3.6.2 release candidate 1: Python 3 6 2 release candidate 1. 
* Python 3.6.1 final: Python 3 6 1 final. 
* Python 3.6.1 release candidate 1: Python 3 6 1 release candidate 1. 
* Python 3.6.0 final: Python 3 6 0 final. 
* Python 3.6.0 release candidate 2: Python 3 6 0 release candidate 2. 
* Python 3.6.0 release candidate 1: Python 3 6 0 release candidate 1. 
* Python 3.6.0 beta 4: Python 3 6 0 beta 4. 
* Python 3.6.0 beta 3: Python 3 6 0 beta 3. 
* Python 3.6.0 beta 2: Python 3 6 0 beta 2. 
* Python 3.6.0 beta 1: Python 3 6 0 beta 1. 
* Python 3.6.0 alpha 4: Python 3 6 0 alpha 4. 
* Python 3.6.0 alpha 3: Python 3 6 0 alpha 3. 
* Python 3.6.0 alpha 2: Python 3 6 0 alpha 2. 
* Python 3.6.0 alpha 1: Python 3 6 0 alpha 1. 
* Python 3.5.5 final: Python 3 5 5 final. 
* Python 3.5.5 release candidate 1: Python 3 5 5 release candidate 1. 
* Python 3.5.4 final: Python 3 5 4 final. 
* Python 3.5.4 release candidate 1: Python 3 5 4 release candidate 1. 
* Python 3.5.3 final: Python 3 5 3 final. 
* Python 3.5.3 release candidate 1: Python 3 5 3 release candidate 1. 
* Python 3.5.2 final: Python 3 5 2 final. 
* Python 3.5.2 release candidate 1: Python 3 5 2 release candidate 1. 
* Python 3.5.1 final: Python 3 5 1 final. 
* Python 3.5.1 release candidate 1: Python 3 5 1 release candidate 1. 
* Python 3.5.0 final: Python 3 5 0 final. 
* Python 3.5.0 release candidate 4: Python 3 5 0 release candidate 4. 
* Python 3.5.0 release candidate 3: Python 3 5 0 release candidate 3. 
* Python 3.5.0 release candidate 2: Python 3 5 0 release candidate 2. 
* Python 3.5.0 release candidate 1: Python 3 5 0 release candidate 1. 
* Python 3.5.0 beta 4: Python 3 5 0 beta 4. 
* Python 3.5.0 beta 3: Python 3 5 0 beta 3. 
* Python 3.5.0 beta 2: Python 3 5 0 beta 2. 
* Python 3.5.0 beta 1: Python 3 5 0 beta 1. 
* Python 3.5.0 alpha 4: Python 3 5 0 alpha 4. 
* Python 3.5.0 alpha 3: Python 3 5 0 alpha 3. 
* Python 3.5.0 alpha 2: Python 3 5 0 alpha 2. 
* Python 3.5.0 alpha 1: Python 3 5 0 alpha 1. 

Python next

* Windows:: 
* Tools/Demos:: 
* Tests:: 
* Security:: 
* Library:: 
* Core and Builtins:: 
* C API:: 
* Build:: 

Python 3.13.1 final

* macOS:: 
* Windows: Windows<2>. 
* Tools/Demos: Tools/Demos<2>. 
* Tests: Tests<2>. 
* Security: Security<2>. 
* Library: Library<2>. 
* IDLE: IDLE<3>. 
* Documentation: Documentation<2>. 
* Core and Builtins: Core and Builtins<2>. 
* C API: C API<2>. 
* Build: Build<2>. 

Python 3.13.0 final

* Core and Builtins: Core and Builtins<3>. 

Python 3.13.0 release candidate 3

* macOS: macOS<2>. 
* Windows: Windows<3>. 
* Tests: Tests<3>. 
* Library: Library<3>. 
* IDLE: IDLE<4>. 
* Documentation: Documentation<3>. 
* Core and Builtins: Core and Builtins<4>. 
* C API: C API<3>. 
* Build: Build<3>. 

Python 3.13.0 release candidate 2

* macOS: macOS<3>. 
* Windows: Windows<4>. 
* Tools/Demos: Tools/Demos<3>. 
* Tests: Tests<4>. 
* Security: Security<3>. 
* Library: Library<4>. 
* IDLE: IDLE<5>. 
* Core and Builtins: Core and Builtins<5>. 
* C API: C API<4>. 
* Build: Build<4>. 

Python 3.13.0 release candidate 1

* Tests: Tests<5>. 
* Security: Security<4>. 
* Library: Library<5>. 
* IDLE: IDLE<6>. 
* Core and Builtins: Core and Builtins<6>. 
* C API: C API<5>. 
* Build: Build<5>. 

Python 3.13.0 beta 4

* Tests: Tests<6>. 
* Library: Library<6>. 
* IDLE: IDLE<7>. 
* Documentation: Documentation<4>. 
* Core and Builtins: Core and Builtins<7>. 
* C API: C API<6>. 
* Build: Build<6>. 

Python 3.13.0 beta 3

* Core and Builtins: Core and Builtins<8>. 
* Library: Library<7>. 
* Build: Build<7>. 
* C API: C API<7>. 

Python 3.13.0 beta 2

* Security: Security<5>. 
* Core and Builtins: Core and Builtins<9>. 
* Library: Library<8>. 
* Tests: Tests<7>. 
* Build: Build<8>. 
* Windows: Windows<5>. 
* C API: C API<8>. 

Python 3.13.0 beta 1

* Security: Security<6>. 
* Core and Builtins: Core and Builtins<10>. 
* Library: Library<9>. 
* Documentation: Documentation<5>. 
* Build: Build<9>. 
* Windows: Windows<6>. 
* macOS: macOS<4>. 
* IDLE: IDLE<8>. 
* C API: C API<9>. 

Python 3.13.0 alpha 6

* Core and Builtins: Core and Builtins<11>. 
* Library: Library<10>. 
* Documentation: Documentation<6>. 
* Tests: Tests<8>. 
* Build: Build<10>. 
* Windows: Windows<7>. 
* C API: C API<10>. 

Python 3.13.0 alpha 5

* Security: Security<7>. 
* Core and Builtins: Core and Builtins<12>. 
* Library: Library<11>. 
* Documentation: Documentation<7>. 
* Tests: Tests<9>. 
* Build: Build<11>. 
* Windows: Windows<8>. 
* macOS: macOS<5>. 
* IDLE: IDLE<9>. 
* Tools/Demos: Tools/Demos<4>. 
* C API: C API<11>. 

Python 3.13.0 alpha 4

* Security: Security<8>. 
* Core and Builtins: Core and Builtins<13>. 
* Library: Library<12>. 
* Documentation: Documentation<8>. 
* Tests: Tests<10>. 
* Build: Build<12>. 
* Windows: Windows<9>. 
* macOS: macOS<6>. 
* IDLE: IDLE<10>. 
* Tools/Demos: Tools/Demos<5>. 
* C API: C API<12>. 

Python 3.13.0 alpha 3

* Security: Security<9>. 
* Core and Builtins: Core and Builtins<14>. 
* Library: Library<13>. 
* Documentation: Documentation<9>. 
* Tests: Tests<11>. 
* Build: Build<13>. 
* Windows: Windows<10>. 
* macOS: macOS<7>. 
* IDLE: IDLE<11>. 
* C API: C API<13>. 

Python 3.13.0 alpha 2

* Core and Builtins: Core and Builtins<15>. 
* Library: Library<14>. 
* Tests: Tests<12>. 
* Build: Build<14>. 
* Windows: Windows<11>. 
* macOS: macOS<8>. 
* IDLE: IDLE<12>. 
* Tools/Demos: Tools/Demos<6>. 
* C API: C API<14>. 

Python 3.13.0 alpha 1

* Security: Security<10>. 
* Core and Builtins: Core and Builtins<16>. 
* Library: Library<15>. 
* Documentation: Documentation<10>. 
* Tests: Tests<13>. 
* Build: Build<15>. 
* Windows: Windows<12>. 
* macOS: macOS<9>. 
* IDLE: IDLE<13>. 
* Tools/Demos: Tools/Demos<7>. 
* C API: C API<15>. 

Python 3.12.0 beta 1

* Security: Security<11>. 
* Core and Builtins: Core and Builtins<17>. 
* Library: Library<16>. 
* Documentation: Documentation<11>. 
* Tests: Tests<14>. 
* Build: Build<16>. 
* Windows: Windows<13>. 
* macOS: macOS<10>. 
* IDLE: IDLE<14>. 
* Tools/Demos: Tools/Demos<8>. 
* C API: C API<16>. 

Python 3.12.0 alpha 7

* Core and Builtins: Core and Builtins<18>. 
* Library: Library<17>. 
* Documentation: Documentation<12>. 
* Tests: Tests<15>. 
* Build: Build<17>. 
* Windows: Windows<14>. 
* Tools/Demos: Tools/Demos<9>. 
* C API: C API<17>. 

Python 3.12.0 alpha 6

* Security: Security<12>. 
* Core and Builtins: Core and Builtins<19>. 
* Library: Library<18>. 
* Documentation: Documentation<13>. 
* Tests: Tests<16>. 
* Build: Build<18>. 
* Windows: Windows<15>. 
* macOS: macOS<11>. 
* C API: C API<18>. 

Python 3.12.0 alpha 5

* Security: Security<13>. 
* Core and Builtins: Core and Builtins<20>. 
* Library: Library<19>. 
* Documentation: Documentation<14>. 
* Tests: Tests<17>. 
* Build: Build<19>. 
* Windows: Windows<16>. 

Python 3.12.0 alpha 4

* Core and Builtins: Core and Builtins<21>. 
* Library: Library<20>. 
* Documentation: Documentation<15>. 
* Tests: Tests<18>. 
* Build: Build<20>. 
* Windows: Windows<17>. 
* macOS: macOS<12>. 
* Tools/Demos: Tools/Demos<10>. 
* C API: C API<19>. 

Python 3.12.0 alpha 3

* Security: Security<14>. 
* Core and Builtins: Core and Builtins<22>. 
* Library: Library<21>. 
* Documentation: Documentation<16>. 
* Tests: Tests<19>. 
* Build: Build<21>. 
* Windows: Windows<18>. 
* macOS: macOS<13>. 
* Tools/Demos: Tools/Demos<11>. 
* C API: C API<20>. 

Python 3.12.0 alpha 2

* Security: Security<15>. 
* Core and Builtins: Core and Builtins<23>. 
* Library: Library<22>. 
* Documentation: Documentation<17>. 
* Tests: Tests<20>. 
* Build: Build<22>. 
* Windows: Windows<19>. 
* macOS: macOS<14>. 
* C API: C API<21>. 

Python 3.12.0 alpha 1

* Security: Security<16>. 
* Core and Builtins: Core and Builtins<24>. 
* Library: Library<23>. 
* Documentation: Documentation<18>. 
* Tests: Tests<21>. 
* Build: Build<23>. 
* Windows: Windows<20>. 
* macOS: macOS<15>. 
* IDLE: IDLE<15>. 
* Tools/Demos: Tools/Demos<12>. 
* C API: C API<22>. 

Python 3.11.0 beta 1

* Security: Security<17>. 
* Core and Builtins: Core and Builtins<25>. 
* Library: Library<24>. 
* Documentation: Documentation<19>. 
* Tests: Tests<22>. 
* Build: Build<24>. 
* Windows: Windows<21>. 
* macOS: macOS<16>. 
* Tools/Demos: Tools/Demos<13>. 
* C API: C API<23>. 

Python 3.11.0 alpha 7

* Core and Builtins: Core and Builtins<26>. 
* Library: Library<25>. 
* Documentation: Documentation<20>. 
* Tests: Tests<23>. 
* Build: Build<25>. 
* Windows: Windows<22>. 
* macOS: macOS<17>. 
* Tools/Demos: Tools/Demos<14>. 
* C API: C API<24>. 

Python 3.11.0 alpha 6

* Core and Builtins: Core and Builtins<27>. 
* Library: Library<26>. 
* Documentation: Documentation<21>. 
* Tests: Tests<24>. 
* Build: Build<26>. 
* Windows: Windows<23>. 
* IDLE: IDLE<16>. 
* C API: C API<25>. 

Python 3.11.0 alpha 5

* Core and Builtins: Core and Builtins<28>. 
* Library: Library<27>. 
* Documentation: Documentation<22>. 
* Tests: Tests<25>. 
* Build: Build<27>. 
* Windows: Windows<24>. 
* macOS: macOS<18>. 
* IDLE: IDLE<17>. 
* C API: C API<26>. 

Python 3.11.0 alpha 4

* Core and Builtins: Core and Builtins<29>. 
* Library: Library<28>. 
* Documentation: Documentation<23>. 
* Tests: Tests<26>. 
* Build: Build<28>. 
* Windows: Windows<25>. 
* macOS: macOS<19>. 
* C API: C API<27>. 

Python 3.11.0 alpha 3

* Core and Builtins: Core and Builtins<30>. 
* Library: Library<29>. 
* Documentation: Documentation<24>. 
* Tests: Tests<27>. 
* Build: Build<29>. 
* Windows: Windows<26>. 
* macOS: macOS<20>. 
* C API: C API<28>. 

Python 3.11.0 alpha 2

* Core and Builtins: Core and Builtins<31>. 
* Library: Library<30>. 
* Documentation: Documentation<25>. 
* Tests: Tests<28>. 
* Build: Build<30>. 
* Windows: Windows<27>. 
* macOS: macOS<21>. 
* IDLE: IDLE<18>. 
* C API: C API<29>. 

Python 3.11.0 alpha 1

* Security: Security<18>. 
* Core and Builtins: Core and Builtins<32>. 
* Library: Library<31>. 
* Documentation: Documentation<26>. 
* Tests: Tests<29>. 
* Build: Build<31>. 
* Windows: Windows<28>. 
* macOS: macOS<22>. 
* IDLE: IDLE<19>. 
* Tools/Demos: Tools/Demos<15>. 
* C API: C API<30>. 

Python 3.10.0 beta 1

* Security: Security<19>. 
* Core and Builtins: Core and Builtins<33>. 
* Library: Library<32>. 
* Documentation: Documentation<27>. 
* Tests: Tests<30>. 
* Build: Build<32>. 
* Windows: Windows<29>. 
* macOS: macOS<23>. 
* IDLE: IDLE<20>. 
* C API: C API<31>. 

Python 3.10.0 alpha 7

* Security: Security<20>. 
* Core and Builtins: Core and Builtins<34>. 
* Library: Library<33>. 
* Documentation: Documentation<28>. 
* Tests: Tests<31>. 
* Build: Build<33>. 
* Windows: Windows<30>. 
* IDLE: IDLE<21>. 
* C API: C API<32>. 

Python 3.10.0 alpha 6

* Security: Security<21>. 
* Core and Builtins: Core and Builtins<35>. 
* Library: Library<34>. 
* Documentation: Documentation<29>. 
* Tests: Tests<32>. 
* Build: Build<34>. 
* Windows: Windows<31>. 
* macOS: macOS<24>. 
* IDLE: IDLE<22>. 
* C API: C API<33>. 

Python 3.10.0 alpha 5

* Security: Security<22>. 
* Core and Builtins: Core and Builtins<36>. 
* Library: Library<35>. 
* Documentation: Documentation<30>. 
* Tests: Tests<33>. 
* Build: Build<35>. 
* Windows: Windows<32>. 
* macOS: macOS<25>. 
* IDLE: IDLE<23>. 
* C API: C API<34>. 

Python 3.10.0 alpha 4

* Core and Builtins: Core and Builtins<37>. 
* Library: Library<36>. 
* Documentation: Documentation<31>. 
* Tests: Tests<34>. 
* Build: Build<36>. 
* macOS: macOS<26>. 
* Tools/Demos: Tools/Demos<16>. 
* C API: C API<35>. 

Python 3.10.0 alpha 3

* Security: Security<23>. 
* Core and Builtins: Core and Builtins<38>. 
* Library: Library<37>. 
* Documentation: Documentation<32>. 
* Tests: Tests<35>. 
* Build: Build<37>. 
* Windows: Windows<33>. 
* macOS: macOS<27>. 
* IDLE: IDLE<24>. 
* Tools/Demos: Tools/Demos<17>. 
* C API: C API<36>. 

Python 3.10.0 alpha 2

* Security: Security<24>. 
* Core and Builtins: Core and Builtins<39>. 
* Library: Library<38>. 
* Documentation: Documentation<33>. 
* Tests: Tests<36>. 
* Build: Build<38>. 
* Windows: Windows<34>. 
* macOS: macOS<28>. 
* IDLE: IDLE<25>. 
* C API: C API<37>. 

Python 3.10.0 alpha 1

* Security: Security<25>. 
* Core and Builtins: Core and Builtins<40>. 
* Library: Library<39>. 
* Documentation: Documentation<34>. 
* Tests: Tests<37>. 
* Build: Build<39>. 
* Windows: Windows<35>. 
* macOS: macOS<29>. 
* IDLE: IDLE<26>. 
* C API: C API<38>. 

Python 3.9.0 beta 1

* Security: Security<26>. 
* Core and Builtins: Core and Builtins<41>. 
* Library: Library<40>. 
* Documentation: Documentation<35>. 
* Tests: Tests<38>. 
* Build: Build<40>. 
* Windows: Windows<36>. 
* macOS: macOS<30>. 
* Tools/Demos: Tools/Demos<18>. 
* C API: C API<39>. 

Python 3.9.0 alpha 6

* Security: Security<27>. 
* Core and Builtins: Core and Builtins<42>. 
* Library: Library<41>. 
* Documentation: Documentation<36>. 
* Tests: Tests<39>. 
* Build: Build<41>. 
* Windows: Windows<37>. 
* macOS: macOS<31>. 
* IDLE: IDLE<27>. 
* Tools/Demos: Tools/Demos<19>. 
* C API: C API<40>. 

Python 3.9.0 alpha 5

* Security: Security<28>. 
* Core and Builtins: Core and Builtins<43>. 
* Library: Library<42>. 
* Documentation: Documentation<37>. 
* Tests: Tests<40>. 
* Build: Build<42>. 
* Windows: Windows<38>. 
* macOS: macOS<32>. 
* IDLE: IDLE<28>. 
* Tools/Demos: Tools/Demos<20>. 
* C API: C API<41>. 

Python 3.9.0 alpha 4

* Security: Security<29>. 
* Core and Builtins: Core and Builtins<44>. 
* Library: Library<43>. 
* Documentation: Documentation<38>. 
* Tests: Tests<41>. 
* Build: Build<43>. 
* Windows: Windows<39>. 
* IDLE: IDLE<29>. 
* C API: C API<42>. 

Python 3.9.0 alpha 3

* Core and Builtins: Core and Builtins<45>. 
* Library: Library<44>. 
* Documentation: Documentation<39>. 
* Build: Build<44>. 
* IDLE: IDLE<30>. 
* C API: C API<43>. 

Python 3.9.0 alpha 2

* Security: Security<30>. 
* Core and Builtins: Core and Builtins<46>. 
* Library: Library<45>. 
* Documentation: Documentation<40>. 
* Tests: Tests<42>. 
* Build: Build<45>. 
* Windows: Windows<40>. 
* macOS: macOS<33>. 
* IDLE: IDLE<31>. 
* C API: C API<44>. 

Python 3.9.0 alpha 1

* Security: Security<31>. 
* Core and Builtins: Core and Builtins<47>. 
* Library: Library<46>. 
* Documentation: Documentation<41>. 
* Tests: Tests<43>. 
* Build: Build<46>. 
* Windows: Windows<41>. 
* macOS: macOS<34>. 
* IDLE: IDLE<32>. 
* Tools/Demos: Tools/Demos<21>. 
* C API: C API<45>. 

Python 3.8.0 beta 1

* Security: Security<32>. 
* Core and Builtins: Core and Builtins<48>. 
* Library: Library<47>. 
* Documentation: Documentation<42>. 
* Tests: Tests<44>. 
* Build: Build<47>. 
* Windows: Windows<42>. 
* macOS: macOS<35>. 
* IDLE: IDLE<33>. 
* Tools/Demos: Tools/Demos<22>. 
* C API: C API<46>. 

Python 3.8.0 alpha 4

* Security: Security<33>. 
* Core and Builtins: Core and Builtins<49>. 
* Library: Library<48>. 
* Documentation: Documentation<43>. 
* Tests: Tests<45>. 
* Build: Build<48>. 
* Windows: Windows<43>. 
* macOS: macOS<36>. 
* IDLE: IDLE<34>. 
* Tools/Demos: Tools/Demos<23>. 
* C API: C API<47>. 

Python 3.8.0 alpha 3

* Security: Security<34>. 
* Core and Builtins: Core and Builtins<50>. 
* Library: Library<49>. 
* Documentation: Documentation<44>. 
* Tests: Tests<46>. 
* Build: Build<49>. 
* Windows: Windows<44>. 
* IDLE: IDLE<35>. 
* Tools/Demos: Tools/Demos<24>. 
* C API: C API<48>. 

Python 3.8.0 alpha 2

* Core and Builtins: Core and Builtins<51>. 
* Library: Library<50>. 
* Documentation: Documentation<45>. 
* Tests: Tests<47>. 
* Windows: Windows<45>. 
* IDLE: IDLE<36>. 

Python 3.8.0 alpha 1

* Security: Security<35>. 
* Core and Builtins: Core and Builtins<52>. 
* Library: Library<51>. 
* Documentation: Documentation<46>. 
* Tests: Tests<48>. 
* Build: Build<50>. 
* Windows: Windows<46>. 
* macOS: macOS<37>. 
* IDLE: IDLE<37>. 
* Tools/Demos: Tools/Demos<25>. 
* C API: C API<49>. 

Python 3.7.0 final

* Library: Library<52>. 
* C API: C API<50>. 

Python 3.7.0 release candidate 1

* Core and Builtins: Core and Builtins<53>. 
* Library: Library<53>. 
* Documentation: Documentation<47>. 
* Build: Build<51>. 
* Windows: Windows<47>. 
* IDLE: IDLE<38>. 

Python 3.7.0 beta 5

* Core and Builtins: Core and Builtins<54>. 
* Library: Library<54>. 
* Documentation: Documentation<48>. 
* Tests: Tests<49>. 
* Build: Build<52>. 
* macOS: macOS<38>. 
* IDLE: IDLE<39>. 

Python 3.7.0 beta 4

* Core and Builtins: Core and Builtins<55>. 
* Library: Library<55>. 
* Documentation: Documentation<49>. 
* Tests: Tests<50>. 
* Build: Build<53>. 
* Windows: Windows<48>. 
* macOS: macOS<39>. 
* IDLE: IDLE<40>. 
* Tools/Demos: Tools/Demos<26>. 

Python 3.7.0 beta 3

* Security: Security<36>. 
* Core and Builtins: Core and Builtins<56>. 
* Library: Library<56>. 
* Documentation: Documentation<50>. 
* Tests: Tests<51>. 
* Build: Build<54>. 
* Windows: Windows<49>. 
* macOS: macOS<40>. 
* IDLE: IDLE<41>. 
* Tools/Demos: Tools/Demos<27>. 
* C API: C API<51>. 

Python 3.7.0 beta 2

* Security: Security<37>. 
* Core and Builtins: Core and Builtins<57>. 
* Library: Library<57>. 
* Documentation: Documentation<51>. 
* Tests: Tests<52>. 
* Build: Build<55>. 
* Windows: Windows<50>. 
* macOS: macOS<41>. 
* IDLE: IDLE<42>. 
* Tools/Demos: Tools/Demos<28>. 

Python 3.7.0 beta 1

* Core and Builtins: Core and Builtins<58>. 
* Library: Library<58>. 
* Documentation: Documentation<52>. 
* Tests: Tests<53>. 
* Build: Build<56>. 
* Windows: Windows<51>. 
* macOS: macOS<42>. 
* C API: C API<52>. 

Python 3.7.0 alpha 4

* Core and Builtins: Core and Builtins<59>. 
* Library: Library<59>. 
* Documentation: Documentation<53>. 
* Tests: Tests<54>. 
* Windows: Windows<52>. 
* Tools/Demos: Tools/Demos<29>. 
* C API: C API<53>. 

Python 3.7.0 alpha 3

* Core and Builtins: Core and Builtins<60>. 
* Library: Library<60>. 
* Documentation: Documentation<54>. 
* Tests: Tests<55>. 
* Build: Build<57>. 
* Windows: Windows<53>. 
* macOS: macOS<43>. 
* IDLE: IDLE<43>. 
* Tools/Demos: Tools/Demos<30>. 
* C API: C API<54>. 

Python 3.7.0 alpha 2

* Core and Builtins: Core and Builtins<61>. 
* Library: Library<61>. 
* Documentation: Documentation<55>. 
* Build: Build<58>. 
* IDLE: IDLE<44>. 
* C API: C API<55>. 

Python 3.7.0 alpha 1

* Security: Security<38>. 
* Core and Builtins: Core and Builtins<62>. 
* Library: Library<62>. 
* Documentation: Documentation<56>. 
* Tests: Tests<56>. 
* Build: Build<59>. 
* Windows: Windows<54>. 
* IDLE: IDLE<45>. 
* Tools/Demos: Tools/Demos<31>. 
* C API: C API<56>. 

Python 3.6.6 release candidate 1

* Core and Builtins: Core and Builtins<63>. 
* Library: Library<63>. 
* Documentation: Documentation<57>. 
* Tests: Tests<57>. 
* Build: Build<60>. 
* Windows: Windows<55>. 
* macOS: macOS<44>. 
* IDLE: IDLE<46>. 
* Tools/Demos: Tools/Demos<32>. 
* C API: C API<57>. 

Python 3.6.5 final

* Tests: Tests<58>. 
* Build: Build<61>. 

Python 3.6.5 release candidate 1

* Security: Security<39>. 
* Core and Builtins: Core and Builtins<64>. 
* Library: Library<64>. 
* Documentation: Documentation<58>. 
* Tests: Tests<59>. 
* Build: Build<62>. 
* Windows: Windows<56>. 
* macOS: macOS<45>. 
* IDLE: IDLE<47>. 
* Tools/Demos: Tools/Demos<33>. 
* C API: C API<58>. 

Python 3.6.4 release candidate 1

* Core and Builtins: Core and Builtins<65>. 
* Library: Library<65>. 
* Documentation: Documentation<59>. 
* Tests: Tests<60>. 
* Build: Build<63>. 
* Windows: Windows<57>. 
* macOS: macOS<46>. 
* IDLE: IDLE<48>. 
* Tools/Demos: Tools/Demos<34>. 
* C API: C API<59>. 

Python 3.6.3 final

* Library: Library<66>. 
* Build: Build<64>. 

Python 3.6.3 release candidate 1

* Security: Security<40>. 
* Core and Builtins: Core and Builtins<66>. 
* Library: Library<67>. 
* Documentation: Documentation<60>. 
* Tests: Tests<61>. 
* Build: Build<65>. 
* Windows: Windows<58>. 
* IDLE: IDLE<49>. 
* Tools/Demos: Tools/Demos<35>. 

Python 3.6.2 release candidate 2

* Security: Security<41>. 

Python 3.6.2 release candidate 1

* Security: Security<42>. 
* Core and Builtins: Core and Builtins<67>. 
* Library: Library<68>. 
* IDLE: IDLE<50>. 
* C API: C API<60>. 
* Build: Build<66>. 
* Documentation: Documentation<61>. 
* Tools/Demos: Tools/Demos<36>. 
* Tests: Tests<62>. 
* Windows: Windows<59>. 

Python 3.6.1 final

* Core and Builtins: Core and Builtins<68>. 
* Build: Build<67>. 

Python 3.6.1 release candidate 1

* Core and Builtins: Core and Builtins<69>. 
* Library: Library<69>. 
* IDLE: IDLE<51>. 
* Windows: Windows<60>. 
* C API: C API<61>. 
* Documentation: Documentation<62>. 
* Tests: Tests<63>. 
* Build: Build<68>. 

Python 3.6.0 release candidate 2

* Core and Builtins: Core and Builtins<70>. 
* Tools/Demos: Tools/Demos<37>. 
* Windows: Windows<61>. 
* Build: Build<69>. 

Python 3.6.0 release candidate 1

* Core and Builtins: Core and Builtins<71>. 
* Library: Library<70>. 
* C API: C API<62>. 
* Documentation: Documentation<63>. 
* Tools/Demos: Tools/Demos<38>. 

Python 3.6.0 beta 4

* Core and Builtins: Core and Builtins<72>. 
* Library: Library<71>. 
* Documentation: Documentation<64>. 
* Tests: Tests<64>. 
* Build: Build<70>. 

Python 3.6.0 beta 3

* Core and Builtins: Core and Builtins<73>. 
* Library: Library<72>. 
* Windows: Windows<62>. 
* Build: Build<71>. 
* Tests: Tests<65>. 

Python 3.6.0 beta 2

* Core and Builtins: Core and Builtins<74>. 
* Library: Library<73>. 
* Windows: Windows<63>. 
* C API: C API<63>. 
* Build: Build<72>. 
* Tests: Tests<66>. 

Python 3.6.0 beta 1

* Core and Builtins: Core and Builtins<75>. 
* Library: Library<74>. 
* IDLE: IDLE<52>. 
* C API: C API<64>. 
* Tests: Tests<67>. 
* Build: Build<73>. 
* Tools/Demos: Tools/Demos<39>. 
* Windows: Windows<64>. 

Python 3.6.0 alpha 4

* Core and Builtins: Core and Builtins<76>. 
* Library: Library<75>. 
* IDLE: IDLE<53>. 
* Tests: Tests<68>. 
* Windows: Windows<65>. 
* Build: Build<74>. 

Python 3.6.0 alpha 3

* Security: Security<43>. 
* Core and Builtins: Core and Builtins<77>. 
* Library: Library<76>. 
* IDLE: IDLE<54>. 
* C API: C API<65>. 
* Build: Build<75>. 
* Tools/Demos: Tools/Demos<40>. 
* Documentation: Documentation<65>. 
* Tests: Tests<69>. 

Python 3.6.0 alpha 2

* Security: Security<44>. 
* Core and Builtins: Core and Builtins<78>. 
* Library: Library<77>. 
* IDLE: IDLE<55>. 
* Documentation: Documentation<66>. 
* Tests: Tests<70>. 
* Windows: Windows<66>. 
* Build: Build<76>. 
* C API: C API<66>. 
* Tools/Demos: Tools/Demos<41>. 

Python 3.6.0 alpha 1

* Security: Security<45>. 
* Core and Builtins: Core and Builtins<79>. 
* Library: Library<78>. 
* IDLE: IDLE<56>. 
* Documentation: Documentation<67>. 
* Tests: Tests<71>. 
* Build: Build<77>. 
* Windows: Windows<67>. 
* Tools/Demos: Tools/Demos<42>. 
* C API: C API<67>. 

Python 3.5.5 release candidate 1

* Security: Security<46>. 
* Core and Builtins: Core and Builtins<80>. 
* Library: Library<79>. 

Python 3.5.4 final

* Library: Library<80>. 

Python 3.5.4 release candidate 1

* Security: Security<47>. 
* Core and Builtins: Core and Builtins<81>. 
* Library: Library<81>. 
* Documentation: Documentation<68>. 
* Tests: Tests<72>. 
* Build: Build<78>. 
* Windows: Windows<68>. 
* C API: C API<68>. 

Python 3.5.3 release candidate 1

* Security: Security<48>. 
* Core and Builtins: Core and Builtins<82>. 
* Library: Library<82>. 
* IDLE: IDLE<57>. 
* C API: C API<69>. 
* Documentation: Documentation<69>. 
* Tests: Tests<73>. 
* Tools/Demos: Tools/Demos<43>. 
* Windows: Windows<69>. 
* Build: Build<79>. 

Python 3.5.2 final

* Core and Builtins: Core and Builtins<83>. 
* Tests: Tests<74>. 
* IDLE: IDLE<58>. 

Python 3.5.2 release candidate 1

* Security: Security<49>. 
* Core and Builtins: Core and Builtins<84>. 
* Library: Library<83>. 
* IDLE: IDLE<59>. 
* Documentation: Documentation<70>. 
* Tests: Tests<75>. 
* Build: Build<80>. 
* Windows: Windows<70>. 
* Tools/Demos: Tools/Demos<44>. 

Python 3.5.1 final

* Core and Builtins: Core and Builtins<85>. 
* Windows: Windows<71>. 

Python 3.5.1 release candidate 1

* Core and Builtins: Core and Builtins<86>. 
* Library: Library<84>. 
* IDLE: IDLE<60>. 
* Documentation: Documentation<71>. 
* Tests: Tests<76>. 
* Build: Build<81>. 
* Windows: Windows<72>. 
* Tools/Demos: Tools/Demos<45>. 

Python 3.5.0 final

* Build: Build<82>. 

Python 3.5.0 release candidate 4

* Library: Library<85>. 
* Build: Build<83>. 

Python 3.5.0 release candidate 3

* Core and Builtins: Core and Builtins<87>. 
* Library: Library<86>. 

Python 3.5.0 release candidate 2

* Core and Builtins: Core and Builtins<88>. 
* Library: Library<87>. 

Python 3.5.0 release candidate 1

* Core and Builtins: Core and Builtins<89>. 
* Library: Library<88>. 
* IDLE: IDLE<61>. 
* Documentation: Documentation<72>. 
* Tests: Tests<77>. 

Python 3.5.0 beta 4

* Core and Builtins: Core and Builtins<90>. 
* Library: Library<89>. 
* Build: Build<84>. 

Python 3.5.0 beta 3

* Core and Builtins: Core and Builtins<91>. 
* Library: Library<90>. 
* Tests: Tests<78>. 
* Documentation: Documentation<73>. 
* Build: Build<85>. 

Python 3.5.0 beta 2

* Core and Builtins: Core and Builtins<92>. 
* Library: Library<91>. 

Python 3.5.0 beta 1

* Core and Builtins: Core and Builtins<93>. 
* Library: Library<92>. 
* IDLE: IDLE<62>. 
* Tests: Tests<79>. 
* Documentation: Documentation<74>. 
* Tools/Demos: Tools/Demos<46>. 

Python 3.5.0 alpha 4

* Core and Builtins: Core and Builtins<94>. 
* Library: Library<93>. 
* Build: Build<86>. 
* Tests: Tests<80>. 
* Tools/Demos: Tools/Demos<47>. 
* C API: C API<70>. 

Python 3.5.0 alpha 3

* Core and Builtins: Core and Builtins<95>. 
* Library: Library<94>. 
* Build: Build<87>. 
* Tests: Tests<81>. 
* Tools/Demos: Tools/Demos<48>. 

Python 3.5.0 alpha 2

* Core and Builtins: Core and Builtins<96>. 
* Library: Library<95>. 
* Build: Build<88>. 
* C API: C API<71>. 
* Windows: Windows<73>. 

Python 3.5.0 alpha 1

* Core and Builtins: Core and Builtins<97>. 
* Library: Library<96>. 
* IDLE: IDLE<63>. 
* Build: Build<89>. 
* C API: C API<72>. 
* Documentation: Documentation<75>. 
* Tests: Tests<82>. 
* Tools/Demos: Tools/Demos<49>. 
* Windows: Windows<74>. 

Le tutoriel Python

* Mise en bouche:: 
* Mode d'emploi de l'interpréteur Python:: 
* Introduction informelle à Python:: 
* D'autres outils de contrôle de flux:: 
* Structures de données:: 
* Modules: Modules<2>. 
* Les entrées/sorties:: 
* Erreurs et exceptions:: 
* Classes:: 
* Survol de la bibliothèque standard:: 
* Survol de la bibliothèque standard: Survol de la bibliothèque standard -- Deuxième partie. Deuxième partie
* Environnements virtuels et paquets:: 
* Pour aller plus loin:: 
* Édition interactive des entrées et substitution d'historique:: 
* Floating-Point Arithmetic; Issues and Limitations: Floating-Point Arithmetic Issues and Limitations. 
* Annexe:: 

Mode d'emploi de l'interpréteur Python

* Lancement de l'interpréteur:: 
* L'interpréteur et son environnement:: 

Lancement de l'interpréteur

* Passage d'arguments:: 
* Mode interactif:: 

L'interpréteur et son environnement

* Encodage du code source:: 

Introduction informelle à Python

* Utilisation de Python comme une calculatrice:: 
* Premiers pas vers la programmation:: 

Utilisation de Python comme une calculatrice

* Les nombres:: 
* Text:: 
* Listes:: 

D'autres outils de contrôle de flux

* L'instruction if:: 
* L'instruction for:: 
* La fonction range(): La fonction range. 
* Les instructions break et continue:: 
* La clause else au sein des boucles:: 
* L'instruction pass:: 
* L'instruction match:: 
* Définir des fonctions:: 
* Davantage sur la définition des fonctions:: 
* Aparté ; le style de codage: Aparté le style de codage. 

Davantage sur la définition des fonctions

* Valeur par défaut des arguments:: 
* Les arguments nommés:: 
* Paramètres spéciaux:: 
* Listes d'arguments arbitraires:: 
* Séparation des listes d'arguments:: 
* Fonctions anonymes:: 
* Chaînes de documentation:: 
* Annotations de fonctions:: 

Paramètres spéciaux

* Les arguments positionnels-ou-nommés:: 
* Paramètres positionnels uniquement:: 
* Arguments nommés uniquement:: 
* Exemples de fonctions:: 
* Récapitulatif:: 

Structures de données

* Compléments sur les listes:: 
* L'instruction del:: 
* n-uplets et séquences:: 
* Ensembles:: 
* Dictionnaires:: 
* Techniques de boucles:: 
* Plus d'informations sur les conditions:: 
* Comparer des séquences avec d'autres types:: 

Compléments sur les listes

* Utilisation des listes comme des piles:: 
* Utilisation des listes comme des files:: 
* Listes en compréhension:: 
* Listes en compréhensions imbriquées:: 

Modules

* Les modules en détail:: 
* Modules standards:: 
* La fonction dir(): La fonction dir. 
* Les paquets:: 

Les modules en détail

* Exécuter des modules comme des scripts:: 
* Les dossiers de recherche de modules:: 
* Fichiers Python « compilés »:: 

Les paquets

* Importer * depuis un paquet:: 
* Références internes dans un paquet:: 
* Paquets dans plusieurs dossiers:: 

Les entrées/sorties

* Formatage de données:: 
* Lecture et écriture de fichiers:: 

Formatage de données

* Les chaines de caractères formatées (f-strings): Les chaines de caractères formatées f-strings. 
* La méthode de chaine de caractères format(): La méthode de chaine de caractères format. 
* Formatage de chaînes à la main:: 
* Anciennes méthodes de formatage de chaînes:: 

Lecture et écriture de fichiers

* Méthodes des objets fichiers:: 
* Sauvegarde de données structurées avec le module json:: 

Erreurs et exceptions

* Les erreurs de syntaxe:: 
* Exceptions:: 
* Gestion des exceptions:: 
* Déclencher des exceptions:: 
* Chaînage d'exceptions:: 
* Exceptions définies par l'utilisateur:: 
* Définition d'actions de nettoyage:: 
* Actions de nettoyage prédéfinies:: 
* Levée et gestion de multiples exceptions non corrélées:: 
* Enrichissement des exceptions avec des notes:: 

Classes

* Objets et noms ; préambule: Objets et noms préambule. 
* Portées et espaces de nommage en Python:: 
* Une première approche des classes:: 
* Remarques diverses:: 
* Héritage:: 
* Variables privées:: 
* Trucs et astuces:: 
* Itérateurs:: 
* Générateurs:: 
* Expressions et générateurs:: 

Portées et espaces de nommage en Python

* Exemple de portées et d'espaces de nommage:: 

Une première approche des classes

* Syntaxe de définition des classes:: 
* Objets classes:: 
* Objets instances:: 
* Objets méthode:: 
* Variables de classe et d’instance:: 

Héritage

* Héritage multiple:: 

Survol de la bibliothèque standard

* Interface avec le système d'exploitation:: 
* Jokers sur les noms de fichiers:: 
* Paramètres passés en ligne de commande:: 
* Redirection de la sortie d'erreur et fin d'exécution:: 
* Recherche de motifs dans les chaînes:: 
* Mathématiques:: 
* Accès à internet:: 
* Dates et heures:: 
* Compression de données:: 
* Mesure des performances:: 
* Contrôle qualité:: 
* Piles fournies:: 

Survol de la bibliothèque standard -- Deuxième partie

* Formatage de l'affichage:: 
* Gabarits (templates en anglais): Gabarits templates en anglais. 
* Traitement des données binaires:: 
* Fils d'exécution: Fils d'exécution<2>. 
* Journalisation:: 
* Références faibles:: 
* Outils pour les listes:: 
* Decimal Floating-Point Arithmetic:: 

Environnements virtuels et paquets

* Introduction: Introduction<4>. 
* Création d'environnements virtuels:: 
* Gestion des paquets avec pip:: 

Édition interactive des entrées et substitution d'historique

* Complétion automatique et édition de l'historique:: 
* Alternatives à l'interpréteur interactif:: 

Floating-Point Arithmetic:  Issues and Limitations

* Erreurs de représentation:: 

Annexe

* Mode interactif: Mode interactif<2>. 

Mode interactif

* Gestion des erreurs:: 
* Scripts Python exécutables:: 
* Configuration du mode interactif:: 
* Modules de personnalisation:: 

Installation et utilisation de Python

* Ligne de commande et environnement:: 
* Utilisation de Python sur les plateformes Unix:: 
* Configurer Python:: 
* Utilisation de Python sur Windows:: 
* Using Python on macOS:: 
* Using Python on Android:: 
* Using Python on iOS:: 
* Éditeurs et IDEs:: 

Ligne de commande et environnement

* Ligne de commande:: 
* Variables d'environnement:: 

Ligne de commande

* Options de l'interface:: 
* Options génériques:: 
* Options diverses:: 
* Controlling color:: 
* Options à ne pas utiliser:: 

Variables d'environnement

* Variables en mode débogage:: 

Utilisation de Python sur les plateformes Unix

* Récupérer et installer la dernière version de Python:: 
* Compiler Python:: 
* Fichiers et chemins liés à Python:: 
* Divers:: 
* Version personnalisée d'OpenSSL:: 

Récupérer et installer la dernière version de Python

* Sur Linux:: 
* Sur FreeBSD et OpenBSD:: 

Configurer Python

* Build Requirements:: 
* Generated files:: 
* Options de configuration:: 
* Python Build System:: 
* Compiler and linker flags:: 

Generated files

* configure script:: 

Options de configuration

* Options générales:: 
* C compiler options:: 
* Linker options:: 
* Options for third-party dependencies:: 
* Options de WebAssembly:: 
* Options d'installation:: 
* Options de performance:: 
* Compilation de Python en mode débogage:: 
* Debug options:: 
* Linker options: Linker options<2>. 
* Libraries options:: 
* Security Options:: 
* macOS Options:: 
* iOS Options:: 
* Cross Compiling Options:: 

Python Build System

* Main files of the build system:: 
* Main build steps:: 
* Main Makefile targets:: 
* C extensions:: 

Main Makefile targets

* make:: 
* make platform:: 
* make profile-opt:: 
* make clean:: 
* make distclean:: 
* make install:: 
* make test:: 
* make buildbottest:: 
* make regen-all:: 

Compiler and linker flags

* Preprocessor flags:: 
* Compiler flags:: 
* Linker flags:: 

Utilisation de Python sur Windows

* L'installateur complet:: 
* Le paquet Microsoft Store:: 
* Les paquets nuget.org: Les paquets nuget org. 
* Le paquet intégrable:: 
* Paquets alternatifs:: 
* Configurer Python: Configurer Python<2>. 
* Mode UTF-8:: 
* Lanceur Python pour Windows:: 
* Recherche de modules:: 
* Modules supplémentaires:: 
* Compiler Python sous Windows:: 
* Autres plateformes:: 

L'installateur complet

* Étapes d'installation:: 
* Suppression de la limitation MAX_PATH:: 
* Installation sans l'interface utilisateur:: 
* Installation sans téléchargement:: 
* Modification d'une installation:: 
* Installing Free-threaded Binaries:: 

Le paquet Microsoft Store

* Problèmes connus:: 

Problèmes connus

* Redirection des données locales@comma{} du registre et des chemins temporaires: Redirection des données locales du registre et des chemins temporaires. 

Les paquets nuget.org

* Free-threaded packages:: 

Le paquet intégrable

* Application Python:: 
* Embarquer Python:: 

Configurer Python

* Digression ; définition des variables d'environnement: Digression définition des variables d'environnement. 
* Trouver l'exécutable Python:: 

Lanceur Python pour Windows

* Pour commencer:: 
* Lignes Shebang:: 
* Arguments dans les lignes shebang:: 
* Personnalisation:: 
* Diagnostics:: 
* Exécution à vide:: 
* Installation à la demande:: 
* Codes de retour:: 

Pour commencer

* Depuis la ligne de commande:: 
* Environnements virtuels:: 
* À partir d'un script:: 
* À partir d'associations de fichiers:: 

Personnalisation

* Personnalisation via des fichiers INI:: 
* Personnalisation des versions Python par défaut:: 

Modules supplémentaires

* PyWin32:: 
* cx_Freeze:: 

Using Python on macOS

* Using Python for macOS from python.org: Using Python for macOS from python org. 
* Alternative Distributions:: 
* Installation de paquets Python additionnels:: 
* GUI Programming:: 
* Sujets avancés:: 
* Autres ressources:: 

Using Python for macOS from python.org

* Étapes d'installation: Étapes d'installation<2>. 
* Comment exécuter un script Python:: 

Sujets avancés

* Installing Free-threaded Binaries: Installing Free-threaded Binaries<2>. 
* Installing using the command line:: 
* Distributing Python Applications:: 
* App Store Compliance:: 

Using Python on Android

* Adding Python to an Android app:: 

Using Python on iOS

* Python at runtime on iOS:: 
* Installing Python on iOS:: 
* App Store Compliance: App Store Compliance<2>. 

Python at runtime on iOS

* iOS version compatibility:: 
* Platform identification:: 
* Standard library availability:: 
* Binary extension modules:: 
* Compiler stub binaries:: 

Installing Python on iOS

* Tools for building iOS apps:: 
* Adding Python to an iOS project:: 
* Testing a Python package:: 

La référence du langage Python

* Introduction: Introduction<5>. 
* Analyse lexicale:: 
* Modèle de données:: 
* Modèle d'exécution:: 
* Le système d'importation:: 
* Expressions:: 
* Les instructions simples:: 
* Instructions composées:: 
* Composants de plus haut niveau:: 
* Spécification complète de la grammaire:: 

Introduction

* Autres implémentations:: 
* Notations:: 

Analyse lexicale

* Structure des lignes:: 
* Autres lexèmes:: 
* Identifiants et mots-clés:: 
* Littéraux:: 
* Opérateurs:: 
* Délimiteurs:: 

Structure des lignes

* Lignes logiques:: 
* Lignes physiques:: 
* Commentaires:: 
* Déclaration d'encodage:: 
* Continuation de ligne explicite:: 
* Continuation de ligne implicite:: 
* Lignes vierges:: 
* Indentation:: 
* Espaces entre lexèmes:: 

Identifiants et mots-clés

* Mots-clés:: 
* Mots-clés ad hoc:: 
* Classes réservées pour les identifiants:: 

Littéraux

* Littéraux de chaînes de caractères et de suites d'octets:: 
* Concaténation de chaînes de caractères:: 
* f-strings:: 
* Littéraux numériques:: 
* Entiers littéraux:: 
* Floating-point literals:: 
* Imaginaires littéraux:: 

Littéraux de chaînes de caractères et de suites d'octets

* Escape sequences:: 

Modèle de données

* Objets@comma{} valeurs et types: Objets valeurs et types. 
* Hiérarchie des types standards:: 
* Méthodes spéciales:: 
* Coroutines:: 

Hiérarchie des types standards

* None:: 
* NotImplemented:: 
* Ellipse:: 
* numbers.Number: numbers Number. 
* Séquences:: 
* Ensembles: Ensembles<2>. 
* Tableaux de correspondances:: 
* Types appelables:: 
* Modules: Modules<3>. 
* Classes déclarées par le développeur:: 
* Instances de classe: Instances de classe<2>. 
* Objets entrées-sorties (ou objets fichiers): Objets entrées-sorties ou objets fichiers. 
* Types internes:: 

numbers.Number

* numbers.Integral: numbers Integral. 
* numbers.Real (float): numbers Real float. 
* numbers.Complex (complex): numbers Complex complex. 

Séquences

* Séquences immuables:: 
* Séquences mutables:: 

Tableaux de correspondances

* Dictionnaires: Dictionnaires<2>. 

Types appelables

* Fonctions définies par l'utilisateur:: 
* Méthodes d'instances:: 
* Fonctions génératrices (ou générateurs): Fonctions génératrices ou générateurs. 
* Fonctions coroutines:: 
* Fonctions génératrices (ou générateurs) asynchrones: Fonctions génératrices ou générateurs asynchrones. 
* Fonctions natives:: 
* Méthodes natives:: 
* Classes: Classes<2>. 
* Instances de classe:: 

Fonctions définies par l'utilisateur

* Special read-only attributes:: 
* Special writable attributes:: 

Modules

* Import-related attributes on module objects:: 
* Other writable attributes on module objects:: 
* Module dictionaries:: 

Classes déclarées par le développeur

* Special attributes:: 
* Special methods:: 

Instances de classe

* Special attributes: Special attributes<2>. 

Types internes

* Objets Code:: 
* Objets cadres:: 
* Objets traces d'appels:: 
* Objets tranches:: 
* Objets méthodes statiques:: 
* Objets méthodes de classes:: 

Objets Code

* Special read-only attributes: Special read-only attributes<2>. 
* Methods on code objects:: 

Objets cadres

* Special read-only attributes: Special read-only attributes<3>. 
* Special writable attributes: Special writable attributes<2>. 
* Frame object methods:: 

Méthodes spéciales

* Personnalisation de base:: 
* Personnalisation de l'accès aux attributs:: 
* Personnalisation de la création de classes:: 
* Personnalisation des instances et vérification des sous-classes:: 
* Émulation de types génériques:: 
* Émulation d'objets appelables:: 
* Émulation de types conteneurs:: 
* Émulation de types numériques:: 
* Gestionnaire de contexte With:: 
* Arguments positionnels dans le filtrage par motif sur les classes:: 
* Emulating buffer types:: 
* Recherche des méthodes spéciales:: 

Personnalisation de l'accès aux attributs

* Personnalisation de l'accès aux attributs d'un module:: 
* Implémentation de descripteurs:: 
* Invocation des descripteurs:: 
* créneaux prédéfinis (__slots__): créneaux prédéfinis __slots__. 

Personnalisation de la création de classes

* Métaclasses:: 
* Résolution des entrées MRO:: 
* Détermination de la métaclasse appropriée:: 
* Préparation de l'espace de nommage de la classe:: 
* Exécution du corps de la classe:: 
* Création de l'objet classe:: 
* Cas d'utilisations des métaclasses:: 

Émulation de types génériques

* Intention de __class_getitem__:: 
* __class_getitem__ contre __getitem__:: 

Coroutines

* Objets attendables (awaitable): Objets attendables awaitable. 
* Objets coroutines:: 
* Itérateurs asynchrones:: 
* Gestionnaires de contexte asynchrones:: 

Modèle d'exécution

* Structure d'un programme:: 
* Noms et liaisons:: 
* Exceptions: Exceptions<2>. 

Noms et liaisons

* Liaisons des noms:: 
* Résolution des noms:: 
* Annotation scopes:: 
* Lazy evaluation:: 
* Noms natifs et restrictions d'exécution:: 
* Interaction avec les fonctionnalités dynamiques:: 

Le système d'importation

* importlib: importlib<10>. 
* Les paquets: Les paquets<2>. 
* Recherche:: 
* Chargement:: 
* Le chercheur dans path:: 
* Remplacement du système d'importation standard:: 
* Importations relatives au paquet:: 
* Cas particulier de __main__:: 
* Références:: 

Les paquets

* Paquets classiques:: 
* Paquets espaces de nommage:: 

Recherche

* Cache des modules:: 
* Chercheurs et chargeurs:: 
* Points d'entrées automatiques pour l'importation:: 
* Méta-chemins:: 

Chargement

* Chargeurs:: 
* Sous-modules:: 
* Spécificateurs de modules:: 
* l'attribut __path__ des modules:: 
* Représentation textuelle d'un module:: 
* Invalidation de bytecode mis en cache:: 

Le chercheur dans path

* Chercheurs d'entrée dans path:: 
* Protocole des chercheurs d'entrée dans path:: 

Cas particulier de __main__

* __main__.__spec__: __main__ __spec__. 

Expressions

* Conversions arithmétiques:: 
* Atomes:: 
* Primaires:: 
* Expression await:: 
* L'opérateur puissance:: 
* Arithmétique unaire et opérations sur les bits:: 
* Opérations arithmétiques binaires:: 
* Opérations de décalage:: 
* Opérations binaires bit à bit:: 
* Comparaisons:: 
* Opérations booléennes:: 
* Expressions d'affectation:: 
* Expressions conditionnelles:: 
* Expressions lambda:: 
* Listes d'expressions:: 
* Ordre d'évaluation:: 
* Priorités des opérateurs:: 

Atomes

* Identifiants (noms): Identifiants noms. 
* Littéraux: Littéraux<2>. 
* Formes parenthésées:: 
* Agencements des listes@comma{} ensembles et dictionnaires: Agencements des listes ensembles et dictionnaires. 
* Agencements de listes:: 
* Agencements d'ensembles:: 
* Agencements de dictionnaires:: 
* Expressions génératrices:: 
* Expressions yield:: 

Identifiants (noms)

* Private name mangling:: 

Expressions yield

* Méthodes des générateurs-itérateurs:: 
* Exemples:: 
* Fonctions génératrices asynchrones:: 
* Méthodes des générateurs-itérateurs asynchrones:: 

Primaires

* Références à des attributs:: 
* sélection (ou indiçage): sélection ou indiçage. 
* Tranches:: 
* Appels:: 

Comparaisons

* Comparaisons de valeurs:: 
* Opérations de tests d’appartenance à un ensemble:: 
* Comparaisons d'identifiants:: 

Les instructions simples

* Les expressions:: 
* Les assignations:: 
* L'instruction assert:: 
* L'instruction pass: L'instruction pass<2>. 
* L'instruction del: L'instruction del<2>. 
* L'instruction return:: 
* L'instruction yield:: 
* L'instruction raise:: 
* L'instruction break:: 
* L'instruction continue:: 
* L'instruction import:: 
* L'instruction global:: 
* L'instruction nonlocal:: 
* The type statement:: 

Les assignations

* Les assignations augmentées:: 
* Les assignations annotées:: 

L'instruction import

* L'instruction future:: 

Instructions composées

* L'instruction if: L'instruction if<2>. 
* L'instruction while:: 
* L'instruction for: L'instruction for<2>. 
* L'instruction try:: 
* L'instruction with:: 
* L'instruction match: L'instruction match<2>. 
* Définition de fonctions:: 
* Définition de classes:: 
* Coroutines: Coroutines<2>. 
* Type parameter lists:: 

L'instruction try

* clause except:: 
* clause except*:: 
* clause else:: 
* clause finally:: 

L'instruction match

* Aperçu:: 
* Gardes:: 
* Bloc case attrape-tout:: 
* Filtres:: 

Filtres

* Filtres OU:: 
* Filtres AS:: 
* Filtres littéraux:: 
* Filtres de capture:: 
* Filtres attrape-tout:: 
* Filtres par valeurs:: 
* Filtres de groupes:: 
* Filtres de séquences:: 
* Filtres associatifs:: 
* Filtres de classes:: 

Coroutines

* Définition de fonctions coroutines:: 
* L'instruction async for:: 
* L'instruction async with:: 

Type parameter lists

* Generic functions:: 
* Generic classes:: 
* Generic type aliases:: 

Composants de plus haut niveau

* Programmes Python complets:: 
* Fichier d'entrée:: 
* Entrée interactive:: 
* Entrée d'expression:: 

La bibliothèque standard

* Introduction: Introduction<6>. 
* Fonctions natives: Fonctions natives<2>. 
* Constantes natives:: 
* Types natifs:: 
* Exceptions natives:: 
* Services de Manipulation de Texte:: 
* Services autour des Données Binaires:: 
* Types de données:: 
* Modules numériques et mathématiques:: 
* Modules de programmation fonctionnelle:: 
* Accès aux Fichiers et aux Dossiers:: 
* Persistance des données:: 
* Compression de donnée et archivage:: 
* Formats de fichiers:: 
* Service de cryptographie:: 
* Services génériques du système d'exploitation:: 
* Command Line Interface Libraries:: 
* Exécution concourante:: 
* Réseau et communication entre processus:: 
* Traitement des données provenant d'Internet:: 
* Outils de traitement de balises structurées:: 
* Gestion des protocoles internet:: 
* Services multimédia:: 
* Internationalisation:: 
* Cadriciels d'applications:: 
* Interfaces Utilisateur Graphiques avec Tk:: 
* Outils de développement:: 
* Débogueur et instrumentation:: 
* Paquets et distribution de paquets logiciels:: 
* Environnement d'exécution Python:: 
* Interpréteurs Python personnalisés:: 
* Importer des modules:: 
* Services du Langage Python:: 
* Services spécifiques à MS Windows:: 
* Services spécifiques à Unix:: 
* Modules command-line interface (CLI): Modules command-line interface CLI. 
* Modules remplacés:: 
* Removed Modules:: 
* Considérations de sécurité: Considérations de sécurité<4>. 

Introduction

* Notes sur la disponibilité:: 

Notes sur la disponibilité

* Plateformes WebAssembly:: 
* Mobile platforms:: 

Constantes natives

* Constantes ajoutées par le module site:: 

Types natifs

* Valeurs booléennes:: 
* Opérations booléennes — and@comma{} or@comma{} not: Opérations booléennes — and or not. 
* Comparaisons: Comparaisons<2>. 
* Types numériques — int@comma{} float@comma{} complex: Types numériques — int float complex. 
* Boolean Type - bool:: 
* Les types itérateurs:: 
* Types séquentiels — list@comma{} tuple@comma{} range: Types séquentiels — list tuple range. 
* Type Séquence de Texte — str:: 
* Séquences Binaires — bytes@comma{} bytearray@comma{} vue mémoire: Séquences Binaires — bytes bytearray vue mémoire. 
* Types d'ensembles — set@comma{} frozenset: Types d'ensembles — set frozenset. 
* Les types de correspondances — dict:: 
* Le type gestionnaire de contexte:: 
* Types d'annotation de type — Alias générique@comma{} Union: Types d'annotation de type — Alias générique Union. 
* Autres types natifs:: 
* Attributs spéciaux:: 
* Limitation de longueur de conversion de chaîne vers un entier:: 

Types numériques — int, float, complex

* Opérations sur les bits des nombres entiers:: 
* Méthodes supplémentaires sur les entiers:: 
* Méthodes supplémentaires sur les nombres à virgule flottante:: 
* Hachage des types numériques:: 

Les types itérateurs

* Types générateurs:: 

Types séquentiels — list, tuple, range

* Opérations communes sur les séquences:: 
* Types de séquences immuables:: 
* Types de séquences mutables:: 
* Listes: Listes<2>. 
* N-uplets:: 
* Ranges:: 

Type Séquence de Texte — str

* Méthodes de chaînes de caractères: Méthodes de chaînes de caractères<2>. 
* Formatage de chaines à la printf:: 

Séquences Binaires — bytes, bytearray, vue mémoire

* Objets bytes:: 
* Objets bytearray:: 
* Opérations sur les bytes et bytearray:: 
* Formatage de bytes a la printf:: 
* Vues mémoire:: 

Les types de correspondances — dict

* Les vues de dictionnaires:: 

Types d'annotation de type — Alias générique, Union

* Type Alias générique:: 
* Type Union:: 

Type Alias générique

* Classes génériques standards:: 
* Attributs spéciaux des alias génériques:: 

Autres types natifs

* Modules: Modules<4>. 
* Les classes et instances de classes:: 
* Fonctions:: 
* Méthodes:: 
* Objets code:: 
* Objets type:: 
* L'objet Null:: 
* L'objet points de suspension (ou ellipse): L'objet points de suspension ou ellipse. 
* L'objet NotImplemented:: 
* Objets internes:: 

Limitation de longueur de conversion de chaîne vers un entier

* API concernées:: 
* Configuration de la limite:: 
* Configuration recommandée:: 

Exceptions natives

* Contexte des exceptions:: 
* Hériter des exceptions natives:: 
* Classes mères:: 
* Exceptions concrètes:: 
* Avertissements:: 
* Exception groups:: 
* Hiérarchie des exceptions:: 

Exceptions concrètes

* Exceptions système:: 

Services de Manipulation de Texte

* string: string --- Common string operations. Common string operations
* re: re --- Regular expression operations. Regular expression operations
* difflib: difflib --- Helpers for computing deltas. Helpers for computing deltas
* textwrap: textwrap --- Text wrapping and filling. Text wrapping and filling
* unicodedata: unicodedata --- Unicode Database. Unicode Database
* stringprep: stringprep --- Internet String Preparation. Internet String Preparation
* readline: readline --- GNU readline interface. GNU readline interface
* rlcompleter: rlcompleter --- Completion function for GNU readline. Completion function for GNU readline

string --- Common string operations

* Chaînes constantes:: 
* Formatage personnalisé de chaîne:: 
* Syntaxe de formatage de chaîne:: 
* Chaînes modèles:: 
* Fonctions d'assistance:: 

Syntaxe de formatage de chaîne

* Mini-langage de spécification de format:: 
* Exemples de formats:: 

re --- Regular expression operations

* Syntaxe des expressions rationnelles:: 
* Contenu du module:: 
* Objets d'expressions rationnelles:: 
* Objets de correspondance:: 
* Exemples d'expressions rationnelles:: 

Contenu du module

* Flags:: 
* Fonctions: Fonctions<2>. 
* Exceptions: Exceptions<3>. 

Exemples d'expressions rationnelles

* Rechercher une paire:: 
* Simuler scanf(): Simuler scanf. 
* Comparaison de search() et match(): Comparaison de search et match. 
* Construire un répertoire téléphonique:: 
* Mélanger les lettres des mots:: 
* Trouver tous les adverbes:: 
* Trouver tous les adverbes et leurs positions:: 
* Notation brute de chaînes:: 
* Écrire un analyseur lexical:: 

difflib --- Helpers for computing deltas

* SequenceMatcher Objects:: 
* SequenceMatcher Examples:: 
* Differ Objects:: 
* Differ Example:: 
* A command-line interface to difflib:: 
* ndiff example:: 

readline --- GNU readline interface

* Fichier d'initialisation:: 
* Tampon de ligne:: 
* Fichier d'historique:: 
* Liste d'historique:: 
* Fonctions de rappel au démarrage:: 
* Complétion:: 
* Exemple:: 

Services autour des Données Binaires

* struct: struct --- Interpret bytes as packed binary data. Interpret bytes as packed binary data
* codecs: codecs --- Codec registry and base classes. Codec registry and base classes

struct --- Interpret bytes as packed binary data

* Fonctions et exceptions:: 
* Chaînes de spécification du format:: 
* Applications:: 
* Classes: Classes<3>. 

Chaînes de spécification du format

* Boutisme@comma{} taille et alignement: Boutisme taille et alignement. 
* Caractères de format:: 
* Exemples: Exemples<2>. 

Applications

* Native Formats:: 
* Standard Formats:: 

codecs --- Codec registry and base classes

* Classes de base de codecs:: 
* Encodings and Unicode:: 
* Standard Encodings:: 
* Python Specific Encodings:: 
* encodings.idna: encodings idna --- Internationalized Domain Names in Applications. Internationalized Domain Names in Applications
* encodings.mbcs: encodings mbcs --- Windows ANSI codepage. Windows ANSI codepage
* encodings.utf_8_sig: encodings utf_8_sig --- UTF-8 codec with BOM signature. UTF-8 codec with BOM signature

Classes de base de codecs

* Gestionnaires d'erreurs:: 
* Stateless Encoding and Decoding:: 
* Incremental Encoding and Decoding:: 
* Stream Encoding and Decoding:: 

Incremental Encoding and Decoding

* IncrementalEncoder Objects:: 
* IncrementalDecoder Objects:: 

Stream Encoding and Decoding

* StreamWriter Objects:: 
* StreamReader Objects:: 
* StreamReaderWriter Objects:: 
* StreamRecoder Objects:: 

Python Specific Encodings

* Text Encodings:: 
* Binary Transforms:: 
* Text Transforms:: 

Types de données

* datetime — Types de base pour la date et l'heure:: 
* zoneinfo: zoneinfo --- IANA time zone support. IANA time zone support
* calendar: calendar --- General calendar-related functions. General calendar-related functions
* collections: collections --- Container datatypes. Container datatypes
* collections.abc: collections abc --- Abstract Base Classes for Containers. Abstract Base Classes for Containers
* heapq: heapq --- Heap queue algorithm. Heap queue algorithm
* bisect: bisect --- Array bisection algorithm. Array bisection algorithm
* array: array --- Efficient arrays of numeric values. Efficient arrays of numeric values
* weakref: weakref --- Weak references. Weak references
* types: types --- Dynamic type creation and names for built-in types. Dynamic type creation and names for built-in types
* copy: copy --- Shallow and deep copy operations. Shallow and deep copy operations
* pprint — L’affichage élégant de données:: 
* reprlib: reprlib --- Alternate repr implementation. Alternate repr() implementation
* enum: enum --- Support for enumerations. Support for enumerations
* graphlib: graphlib --- Functionality to operate with graph-like structures. Functionality to operate with graph-like structures

datetime — Types de base pour la date et l'heure

* Objets avisés et naïfs:: 
* Constantes:: 
* Types disponibles:: 
* Objets timedelta:: 
* Objets date:: 
* Objets datetime:: 
* Objets time:: 
* Objets tzinfo:: 
* Objets timezone:: 
* strftime() and strptime() Behavior: strftime and strptime Behavior. 

Types disponibles

* Propriétés communes:: 
* Catégorisation d'un objet en « avisé » ou « naïf »:: 

Objets timedelta

* Exemples d'utilisation de la classe timedelta ;: Exemples d'utilisation de la classe timedelta. 

Objets date

* Exemple d'utilisation de la classe date ;: Exemple d'utilisation de la classe date. 

Objets datetime

* Exemple d'utilisation de la classe datetime ;: Exemple d'utilisation de la classe datetime. 

Objets time

* Exemples d'utilisation de time:: 

strftime() and strptime() Behavior

* strftime() and strptime() Format Codes: strftime and strptime Format Codes. 
* Détail technique:: 

zoneinfo --- IANA time zone support

* Utilisation de ZoneInfo:: 
* Sources de données:: 
* La classe ZoneInfo:: 
* Fonctions: Fonctions<3>. 
* Variables globales:: 
* Exceptions et avertissements:: 

Sources de données

* Configurer les sources de données:: 

Configurer les sources de données

* Configuration à la compilation:: 
* Configuration par l'environnement:: 
* Configuration à l'exécution:: 

La classe ZoneInfo

* Représentation sous forme de chaîne de caractères:: 
* Sérialisation Pickle:: 

calendar --- General calendar-related functions

* Utilisation en ligne de commande.: Utilisation en ligne de commande. 

collections --- Container datatypes

* Objets ChainMap:: 
* Objets Counter:: 
* Objets deque:: 
* Objets defaultdict:: 
* namedtuple() ; fonction de construction pour n-uplets avec des champs nommés: namedtuple fonction de construction pour n-uplets avec des champs nommés. 
* Objets OrderedDict:: 
* Objets UserDict:: 
* Objets UserList:: 
* Objets UserString:: 

Objets ChainMap

* Exemples et cas pratiques utilisant ChainMap:: 

Objets deque

* Cas pratiques utilisant deque:: 

Objets defaultdict

* Exemples utilisant defaultdict:: 

Objets OrderedDict

* Exemples et cas pratiques utilisant OrderDict:: 

collections.abc --- Abstract Base Classes for Containers

* Classes de base abstraites de collections:: 
* Collections Abstract Base Classes: Collections Abstract Base Classes -- Detailed Descriptions. Detailed Descriptions
* Exemples et recettes:: 

heapq --- Heap queue algorithm

* Exemples simples:: 
* Notes d'implémentation de la file de priorité:: 
* Théorie:: 

bisect --- Array bisection algorithm

* Notes sur la performance:: 
* Chercher dans des listes triées:: 
* Exemples: Exemples<3>. 

weakref --- Weak references

* Objets à références faibles:: 
* Exemple: Exemple<2>. 
* Finalizer Objects:: 
* Comparing finalizers with __del__() methods: Comparing finalizers with __del__ methods. 

types --- Dynamic type creation and names for built-in types

* Dynamic Type Creation:: 
* Standard Interpreter Types:: 
* Additional Utility Classes and Functions:: 
* Coroutine Utility Functions:: 

pprint — L’affichage élégant de données

* Fonctions: Fonctions<4>. 
* Les Objets PrettyPrinter:: 
* Exemple: Exemple<3>. 

reprlib --- Alternate repr() implementation

* Repr Objects:: 
* Subclassing Repr Objects:: 

enum --- Support for enumerations

* Contenu du module: Contenu du module<2>. 
* Types de données: Types de données<2>. 
* Utilitaires et décorateurs:: 
* Notes:: 

Types de données

* Noms de la forme __dunder__ disponibles:: 
* Noms de la forme _sunder_ disponibles:: 

graphlib --- Functionality to operate with graph-like structures

* Exceptions: Exceptions<4>. 

Modules numériques et mathématiques

* numbers: numbers --- Numeric abstract base classes. Numeric abstract base classes
* math: math --- Mathematical functions. Mathematical functions
* cmath: cmath --- Mathematical functions for complex numbers. Mathematical functions for complex numbers
* decimal: decimal --- Decimal fixed-point and floating-point arithmetic. Decimal fixed-point and floating-point arithmetic
* fractions: fractions --- Rational numbers. Rational numbers
* random: random --- Generate pseudo-random numbers. Generate pseudo-random numbers
* statistics: statistics --- Mathematical statistics functions. Mathematical statistics functions

numbers --- Numeric abstract base classes

* La tour numérique:: 
* Notes for type implementers:: 

Notes for type implementers

* Ajouter plus d'ABC numériques:: 
* Implémentation des opérations arithmétiques:: 

math --- Mathematical functions

* Number-theoretic functions:: 
* Floating point arithmetic:: 
* Floating point manipulation functions:: 
* Power@comma{} exponential and logarithmic functions: Power exponential and logarithmic functions. 
* Summation and product functions:: 
* Conversion angulaire:: 
* Fonctions trigonométriques:: 
* Fonctions hyperboliques:: 
* Fonctions spéciales:: 
* Constantes: Constantes<2>. 

cmath --- Mathematical functions for complex numbers

* Conversion vers et à partir de coordonnées polaires:: 
* Fonctions logarithme et exponentielle:: 
* Fonctions trigonométriques: Fonctions trigonométriques<2>. 
* Fonctions hyperboliques: Fonctions hyperboliques<2>. 
* Fonctions de classifications:: 
* Constantes: Constantes<3>. 

decimal --- Decimal fixed-point and floating-point arithmetic

* Introduction pratique:: 
* Les objets Decimal:: 
* Objets de contexte:: 
* Constantes: Constantes<4>. 
* Modes d'arrondi:: 
* Signaux:: 
* Floating-Point Notes:: 
* Working with threads:: 
* Cas pratiques:: 
* FAQ decimal:: 

Les objets Decimal

* Opérandes logiques:: 

Floating-Point Notes

* Mitigating round-off error with increased precision:: 
* Special values:: 

random --- Generate pseudo-random numbers

* Fonctions de gestion d'état:: 
* Fonctions pour les octets:: 
* Fonctions pour les entiers:: 
* Fonctions pour les séquences:: 
* Discrete distributions:: 
* Distributions pour les nombres réels:: 
* Générateur alternatif:: 
* Remarques sur la reproductibilité:: 
* Exemples: Exemples<4>. 
* Cas pratiques: Cas pratiques<2>. 
* Command-line usage:: 
* Command-line example:: 

statistics --- Mathematical statistics functions

* Moyennes et mesures de la tendance centrale:: 
* Mesures de la dispersion:: 
* Statistics for relations between two inputs:: 
* Détails des fonctions:: 
* Exceptions: Exceptions<5>. 
* Objets NormalDist:: 
* Examples and Recipes:: 

Examples and Recipes

* Classic probability problems:: 
* Monte Carlo inputs for simulations:: 
* Approximating binomial distributions:: 
* Naive bayesian classifier:: 

Modules de programmation fonctionnelle

* itertools: itertools --- Functions creating iterators for efficient looping. Functions creating iterators for efficient looping
* functools: functools --- Higher-order functions and operations on callable objects. Higher-order functions and operations on callable
                        objects
* operator — Opérateurs standards en tant que fonctions:: 

itertools --- Functions creating iterators for efficient looping

* Itertool Functions:: 
* Recettes itertools:: 

functools --- Higher-order functions and operations on callable objects

* Objets partial:: 

operator — Opérateurs standards en tant que fonctions

* Correspondances entre opérateurs et fonctions:: 
* Opérateurs en-place:: 

Accès aux Fichiers et aux Dossiers

* pathlib — Chemins de système de fichiers orientés objet:: 
* os.path: os path --- Common pathname manipulations. Common pathname manipulations
* stat: stat --- Interpreting stat results. Interpreting stat() results
* filecmp: filecmp --- File and Directory Comparisons. File and Directory Comparisons
* tempfile: tempfile --- Generate temporary files and directories. Generate temporary files and directories
* glob: glob --- Unix style pathname pattern expansion. Unix style pathname pattern expansion
* fnmatch: fnmatch --- Unix filename pattern matching. Unix filename pattern matching
* linecache: linecache --- Random access to text lines. Random access to text lines
* shutil: shutil --- High-level file operations. High-level file operations

pathlib — Chemins de système de fichiers orientés objet

* Utilisation basique:: 
* Exceptions: Exceptions<6>. 
* Chemins purs:: 
* Chemins concrets:: 
* Pattern language:: 
* Comparaison avec les outils du module glob:: 
* Comparaison aux modules os et os.path: Comparaison aux modules os et os path. 

Chemins purs

* Propriétés générales:: 
* Opérateurs: Opérateurs<2>. 
* Accéder aux parties individuelles:: 
* Méthodes et propriétés:: 

Chemins concrets

* Analyse et génération des URI:: 
* Expansion et résolution de chemins:: 
* Requête sur type et statut du fichier:: 
* Lecture et écriture de fichiers: Lecture et écriture de fichiers<2>. 
* Lecture des dossiers:: 
* Création de fichiers et de dossiers:: 
* Renommage et suppression:: 
* Permissions et propriété:: 

Comparaison  aux modules os et os.path

* Outils correspondants:: 

filecmp --- File and Directory Comparisons

* La classe dircmp:: 

tempfile --- Generate temporary files and directories

* Exemples: Exemples<5>. 
* Fonctions et variables obsolètes:: 

glob --- Unix style pathname pattern expansion

* Exemples: Exemples<6>. 

shutil --- High-level file operations

* Opérations sur les répertoires et les fichiers:: 
* Archiving operations:: 
* Querying the size of the output terminal:: 

Opérations sur les répertoires et les fichiers

* Platform-dependent efficient copy operations:: 
* copytree example:: 
* rmtree example:: 

Archiving operations

* Archiving example:: 
* Archiving example with base_dir:: 

Persistance des données

* pickle: pickle --- Python object serialization. Python object serialization
* copyreg: copyreg --- Register pickle support functions. Register pickle support functions
* shelve: shelve --- Python object persistence. Python object persistence
* marshal: marshal --- Internal Python object serialization. Internal Python object serialization
* dbm: dbm --- Interfaces to Unix "databases". Interfaces to Unix "databases"
* sqlite3: sqlite3 --- DB-API 2 0 interface for SQLite databases. DB-API 2.0 interface for SQLite databases

pickle --- Python object serialization

* Relations aux autres modules Python:: 
* Format du flux de données:: 
* Interface du module:: 
* Quels objets sont sérialisables ?:: 
* Sérialisation des instances d'une classe:: 
* Réduction personnalisée pour les types@comma{} fonctions et autres objets: Réduction personnalisée pour les types fonctions et autres objets. 
* Tampons hors-bande:: 
* Restriction des noms dans l'espace de nommage global:: 
* Performances: Performances<2>. 
* Exemples: Exemples<7>. 

Relations aux autres modules Python

* Comparaison avec marshal:: 
* Comparaison avec json:: 

Sérialisation des instances d'une classe

* Persistance d'objets externes:: 
* Tables de distribution:: 
* Traitement des objets à état:: 

Tampons hors-bande

* API des producteurs:: 
* API des consommateurs:: 
* Exemple: Exemple<4>. 

copyreg --- Register pickle support functions

* Exemple: Exemple<5>. 

shelve --- Python object persistence

* Limites:: 
* Exemple: Exemple<6>. 

dbm --- Interfaces to Unix "databases"

* dbm.sqlite3: dbm sqlite3 --- SQLite backend for dbm. SQLite backend for dbm
* dbm.gnu: dbm gnu --- GNU database manager. GNU database manager
* dbm.ndbm: dbm ndbm --- New Database Manager. New Database Manager
* dbm.dumb: dbm dumb --- Portable DBM implementation. Portable DBM implementation

sqlite3 --- DB-API 2.0 interface for SQLite databases

* Tutoriel:: 
* Références: Références<2>. 
* How-to guides:: 
* Explanation:: 

Références

* Fonctions du module:: 
* Fonctions et constantes du module:: 
* Connection objects:: 
* Cursor objects:: 
* Row objects:: 
* Blob objects:: 
* PrepareProtocol objects:: 
* Exceptions: Exceptions<7>. 
* SQLite and Python types:: 
* Default adapters and converters (deprecated): Default adapters and converters deprecated. 
* Command-line interface:: 

How-to guides

* How to use placeholders to bind values in SQL queries:: 
* How to adapt custom Python types to SQLite values:: 
* How to convert SQLite values to custom Python types:: 
* Adapter and converter recipes:: 
* How to use connection shortcut methods:: 
* How to use the connection context manager:: 
* How to work with SQLite URIs:: 
* How to create and use row factories:: 
* How to handle non-UTF-8 text encodings:: 

How to adapt custom Python types to SQLite values

* How to write adaptable objects:: 
* How to register adapter callables:: 

Explanation

* Transaction control:: 

Transaction control

* Transaction control via the autocommit attribute:: 
* Transaction control via the isolation_level attribute:: 

Compression de donnée et archivage

* zlib: zlib --- Compression compatible with gzip. Compression compatible with gzip
* gzip: gzip --- Support for gzip files. Support for gzip files
* bz2: bz2 --- Support for bzip2 compression. Support for bzip2 compression
* lzma: lzma --- Compression using the LZMA algorithm. Compression using the LZMA algorithm
* zipfile: zipfile --- Work with ZIP archives. Work with ZIP archives
* tarfile: tarfile --- Read and write tar archive files. Read and write tar archive files

gzip --- Support for gzip files

* Exemples d'utilisation:: 
* Interface en ligne de commande:: 

Interface en ligne de commande

* Options de la ligne de commande:: 

bz2 --- Support for bzip2 compression

* (Dé)compression de fichiers: Dé compression de fichiers. 
* (Dé)compression incrémentielle: Dé compression incrémentielle. 
* (Dé)compression en une fois: Dé compression en une fois. 
* Exemples d'utilisation: Exemples d'utilisation<2>. 

lzma --- Compression using the LZMA algorithm

* Lire et écrire des fichiers compressés:: 
* Compresser et décompresser une donnée en mémoire:: 
* Divers: Divers<2>. 
* Préciser des chaînes de filtre personnalisées:: 
* Exemples: Exemples<8>. 

zipfile --- Work with ZIP archives

* Objets ZipFile:: 
* Objets Path:: 
* Objets PyZipFile:: 
* Objets ZipInfo:: 
* Interface en ligne de commande: Interface en ligne de commande<2>. 
* Problèmes de décompression:: 

Interface en ligne de commande

* Options de la ligne de commande: Options de la ligne de commande<2>. 

Problèmes de décompression

* À cause du fichier lui-même:: 
* Limitations du système de fichiers:: 
* Ressources limitées:: 
* Interruption:: 
* Comportements par défaut de l'extraction:: 

tarfile --- Read and write tar archive files

* Les objets TarFile:: 
* Les objets TarInfo:: 
* Extraction filters:: 
* Interface en ligne de commande: Interface en ligne de commande<3>. 
* Exemples: Exemples<9>. 
* Formats tar pris en charge:: 
* Problèmes unicode:: 

Extraction filters

* Default named filters:: 
* Filter errors:: 
* Hints for further verification:: 
* Supporting older Python versions:: 
* Stateful extraction filter example:: 

Interface en ligne de commande

* Options de la ligne de commande: Options de la ligne de commande<3>. 

Formats de fichiers

* csv: csv --- CSV File Reading and Writing. CSV File Reading and Writing
* configparser: configparser --- Configuration file parser. Configuration file parser
* tomllib: tomllib --- Parse TOML files. Parse TOML files
* netrc: netrc --- netrc file processing. netrc file processing
* plistlib: plistlib --- Generate and parse Apple plist files. Generate and parse Apple .plist files

csv --- CSV File Reading and Writing

* Contenu du module: Contenu du module<3>. 
* Dialectes et paramètres de formatage:: 
* Objets lecteurs:: 
* Objets transcripteurs:: 
* Exemples: Exemples<10>. 

configparser --- Configuration file parser

* Premiers pas:: 
* Types de données prises en charge:: 
* Valeurs de substitution:: 
* Structure des fichiers INI prise en change:: 
* Unnamed Sections:: 
* Interpolation des valeurs:: 
* Protocole d'accès associatif:: 
* Personnalisation du comportement de l'analyseur:: 
* Legacy API Examples:: 
* ConfigParser Objects:: 
* RawConfigParser Objects:: 
* Exceptions: Exceptions<8>. 

tomllib --- Parse TOML files

* Exemples: Exemples<11>. 
* Conversion Table:: 

netrc --- netrc file processing

* Objets netrc:: 

plistlib --- Generate and parse Apple .plist files

* Exemples: Exemples<12>. 

Service de cryptographie

* hashlib: hashlib --- Algorithmes de hachage sécurisés et synthèse de messages. Algorithmes de hachage sécurisés et synthèse de
                        messages
* hmac: hmac --- Keyed-Hashing for Message Authentication. Keyed-Hashing for Message Authentication
* secrets: secrets --- Generate secure random numbers for managing secrets. Generate secure random numbers for managing secrets

hashlib --- Algorithmes de hachage sécurisés et synthèse de messages

* Algorithmes de hachage:: 
* Utilisation:: 
* Constructeurs:: 
* Attributes:: 
* Objets de calcul d'empreinte:: 
* Empreintes de messages de taille variable SHAKE:: 
* Calcul d'empreinte (ou hachage) de fichiers: Calcul d'empreinte ou hachage de fichiers. 
* Dérivation de clé:: 
* BLAKE2:: 

BLAKE2

* Création d'objets de calcul d'empreinte:: 
* Constantes: Constantes<5>. 
* Exemples: Exemples<13>. 
* Crédits:: 

Exemples

* Hachage simple:: 
* Production de tailles d'empreintes différentes:: 
* Hachage avec clé – Code d'authentification de message:: 
* Hachage randomisé:: 
* Personnalisation: Personnalisation<2>. 
* Mode Arbre:: 

secrets --- Generate secure random numbers for managing secrets

* Nombres aléatoires:: 
* Génération de jetons:: 
* Autres fonctions:: 
* Recettes et bonnes pratiques:: 

Génération de jetons

* Combien d'octets mon jeton doit-il comporter ?:: 

Services génériques du système d'exploitation

* os: os --- Miscellaneous operating system interfaces. Miscellaneous operating system interfaces
* io: io --- Core tools for working with streams. Core tools for working with streams
* time: time --- Time access and conversions. Time access and conversions
* logging: logging --- Logging facility for Python. Logging facility for Python
* logging.config: logging config --- Logging configuration. Logging configuration
* logging.handlers: logging handlers --- Logging handlers. Logging handlers
* platform: platform --- Access to underlying platform's identifying data. Access to underlying platform's identifying data
* errno: errno --- Standard errno system symbols. Standard errno system symbols
* ctypes: ctypes --- A foreign function library for Python. A foreign function library for Python

os --- Miscellaneous operating system interfaces

* Noms de fichiers@comma{} arguments en ligne de commande@comma{} et variables d'environnement: Noms de fichiers arguments en ligne de commande et variables d'environnement. 
* Le mode UTF-8 de Python:: 
* Paramètres de processus:: 
* Création de fichiers objets:: 
* Opérations sur les descripteurs de fichiers:: 
* Fichiers et répertoires:: 
* Gestion des processus:: 
* Interface pour l'ordonnanceur:: 
* Diverses informations sur le système:: 
* Nombres aléatoires: Nombres aléatoires<2>. 

Opérations sur les descripteurs de fichiers

* Demander la taille d'un terminal:: 
* Héritage de descripteurs de fichiers:: 

Fichiers et répertoires

* Timer File Descriptors:: 
* Attributs étendus pour Linux:: 

io --- Core tools for working with streams

* Aperçu: Aperçu<2>. 
* Encodage de texte:: 
* Interface de haut niveau du module:: 
* Class hierarchy:: 
* Performances: Performances<3>. 

Aperçu

* Entrée/sortie de texte:: 
* Binary I/O:: 
* Raw I/O:: 

Encodage de texte

* Opt-in EncodingWarning:: 

Class hierarchy

* I/O Base Classes:: 
* Raw File I/O:: 
* Buffered Streams:: 
* Entrée/sortie de texte: Entrée/sortie de texte<2>. 

Performances

* Binary I/O: Binary I/O<2>. 
* Entrée/sortie de texte: Entrée/sortie de texte<3>. 
* Fils d'exécution: Fils d'exécution<3>. 
* Réentrance:: 

time --- Time access and conversions

* Fonctions: Fonctions<5>. 
* Constantes d’identification d’horloge:: 
* Constantes de fuseau horaire:: 

logging --- Logging facility for Python

* Enregistreurs:: 
* Niveaux de journalisation:: 
* Gestionnaires:: 
* Formateurs:: 
* Filtres: Filtres<2>. 
* Objets LogRecord:: 
* LogRecord attributes:: 
* LoggerAdapter Objects:: 
* Thread Safety:: 
* Fonctions de niveau module:: 
* Module-Level Attributes:: 
* Integration with the warnings module:: 

logging.config --- Logging configuration

* Configuration functions:: 
* Security considerations:: 
* Configuration dictionary schema:: 
* Configuration file format:: 

Configuration dictionary schema

* Dictionary Schema Details:: 
* Incremental Configuration:: 
* Object connections:: 
* User-defined objects:: 
* Handler configuration order:: 
* Access to external objects:: 
* Access to internal objects:: 
* Import resolution and custom importers:: 
* Configuring QueueHandler and QueueListener:: 

logging.handlers --- Logging handlers

* Gestionnaire à flux — StreamHandler:: 
* Gestionnaire à fichier — FileHandler:: 
* Gestionnaire à puits sans fond — NullHandler:: 
* Gestionnaire à fichier avec surveillance — WatchedFileHandler:: 
* Base des gestionnaires à roulement — BaseRotatingHandler:: 
* Gestionnaire à roulement de fichiers — RotatingFileHandler:: 
* Gestionnaire à roulement de fichiers périodique — TimedRotatingFileHandler:: 
* Gestionnaire à connecteur — SocketHandler:: 
* DatagramHandler:: 
* SysLogHandler:: 
* NTEventLogHandler:: 
* SMTPHandler:: 
* MemoryHandler:: 
* HTTPHandler:: 
* QueueHandler:: 
* QueueListener:: 

platform ---  Access to underlying platform's identifying data

* Multiplateformes:: 
* Plateforme Java:: 
* Plateforme Windows:: 
* macOS Platform:: 
* iOS Platform:: 
* Plateformes Unix:: 
* Linux Platforms:: 
* Android Platform:: 

ctypes --- A foreign function library for Python

* Didacticiel de ctypes:: 
* Référence du module:: 

Didacticiel de ctypes

* Chargement des DLL:: 
* Accès aux fonctions des DLL chargées:: 
* Appel de fonctions:: 
* Types de données de base:: 
* Appel de fonctions@comma{} suite: Appel de fonctions suite. 
* Calling variadic functions:: 
* Appel de fonctions avec des types de données personnalisés:: 
* Définition du type des arguments nécessaires (prototypes de fonction): Définition du type des arguments nécessaires prototypes de fonction. 
* Types de sortie:: 
* Passage de pointeurs (passage de paramètres par référence): Passage de pointeurs passage de paramètres par référence. 
* Structures et unions:: 
* Alignement et boutisme des structures et des unions:: 
* Champs de bits dans les structures et les unions:: 
* Tableaux:: 
* Pointeurs:: 
* Conversions de type:: 
* Types incomplets:: 
* Fonctions de rappel:: 
* Accès aux variables exportées depuis une DLL:: 
* Pièges:: 
* Types de données à taille flottante:: 

Référence du module

* Recherche de bibliothèques partagées:: 
* Chargement des bibliothèques partagées:: 
* Fonctions externes:: 
* Prototypes de fonction:: 
* Fonctions utilitaires:: 
* Types de données: Types de données<3>. 
* Types de données de base: Types de données de base<2>. 
* Types de données dérivés de Structure:: 
* Tableaux et pointeurs:: 

Command Line Interface Libraries

* argparse: argparse --- Parser for command-line options arguments and subcommands. Parser for command-line options, arguments and
                        subcommands
* optparse: optparse --- Parser for command line options. Parser for command line options
* getpass: getpass --- Portable password input. Portable password input
* fileinput: fileinput --- Iterate over lines from multiple input streams. Iterate over lines from multiple input streams
* curses: curses --- Terminal handling for character-cell displays. Terminal handling for character-cell displays
* curses.textpad: curses textpad --- Text input widget for curses programs. Text input widget for curses programs
* curses.ascii: curses ascii --- Utilities for ASCII characters. Utilities for ASCII characters
* curses.panel: curses panel --- A panel stack extension for curses. A panel stack extension for curses

argparse --- Parser for command-line options, arguments and subcommands

* Objets ArgumentParser:: 
* La méthode add_argument(): La méthode add_argument. 
* La méthode parse_args(): La méthode parse_args. 
* Autres outils:: 
* Exceptions: Exceptions<9>. 

Objets ArgumentParser

* Le paramètre prog:: 
* Le paramètre usage:: 
* Le paramètre description:: 
* Le paramètre epilog:: 
* Le paramètre parents:: 
* Le paramètre formatter_class:: 
* Le paramètre prefix_chars:: 
* Le paramètre fromfile_prefix_chars:: 
* Le paramètre argument_default:: 
* Le paramètre allow_abbrev:: 
* Le paramètre conflict_handler:: 
* Le paramètre add_help:: 
* Le paramètre exit_on_error:: 

La méthode add_argument()

* Le paramètre name_or_flags:: 
* Le paramètre action:: 
* Le paramètre nargs:: 
* Le paramètre const:: 
* Le paramètre default:: 
* Le paramètre type:: 
* Le paramètre choices:: 
* Le paramètre required:: 
* Le paramètre help:: 
* Le paramètre metavar:: 
* Le paramètre dest:: 
* deprecated:: 
* Classes Action:: 

La méthode parse_args()

* Syntaxe de la valeur des options:: 
* Arguments invalides:: 
* Arguments contenant -:: 
* Arguments abrégés (par comparaison de leurs préfixes): Arguments abrégés par comparaison de leurs préfixes. 
* Au-delà de sys.argv: Au-delà de sys argv. 
* L'objet Namespace:: 

Autres outils

* Sous commandes:: 
* Objets FileType:: 
* Groupes d'arguments:: 
* Exclusion mutuelle:: 
* Valeurs par défaut de l'analyseur:: 
* Afficher l'aide:: 
* Analyse partielle:: 
* Personnaliser le parsing de fichiers:: 
* Méthodes d'interruptions:: 
* Analyse entremêlée:: 
* Registering custom types or actions:: 

Exceptions

* Tutoriel argparse:: 
* Migrating optparse code to argparse:: 

Tutoriel argparse

* Concepts:: 
* Les bases:: 
* Introduction aux arguments positionnels:: 
* Introduction aux arguments optionnels:: 
* Combinaison d'arguments positionnels et optionnels:: 
* Aller un peu plus loin:: 
* How to translate the argparse output:: 
* Custom type converters:: 
* Conclusion:: 

Introduction aux arguments optionnels

* Les paramètres raccourcis:: 

Aller un peu plus loin

* Specifying ambiguous arguments:: 
* Paramètres en conflit:: 

optparse --- Parser for command line options

* Choosing an argument parsing library:: 
* Introduction: Introduction<7>. 
* Background:: 
* Tutoriel: Tutoriel<2>. 
* Reference Guide:: 
* Option Callbacks:: 
* Extending optparse:: 
* Exceptions: Exceptions<10>. 

Background

* Terminology:: 
* What are options for?:: 
* What are positional arguments for?:: 

Tutoriel

* Understanding option actions:: 
* The store action:: 
* Handling boolean (flag) options: Handling boolean flag options. 
* Other actions:: 
* Valeurs par défaut:: 
* Generating help:: 
* Printing a version string:: 
* How optparse handles errors:: 
* Putting it all together:: 

Generating help

* Grouping Options:: 

Reference Guide

* Creating the parser:: 
* Populating the parser:: 
* Defining options:: 
* Option attributes:: 
* Standard option actions:: 
* Standard option types:: 
* Analyse des arguments:: 
* Querying and manipulating your option parser:: 
* Conflicts between options:: 
* Nettoyage:: 
* Other methods:: 

Option Callbacks

* Defining a callback option:: 
* How callbacks are called:: 
* Raising errors in a callback:: 
* Callback example 1; trivial callback: Callback example 1 trivial callback. 
* Callback example 2; check option order: Callback example 2 check option order. 
* Callback example 3; check option order (generalized): Callback example 3 check option order generalized. 
* Callback example 4; check arbitrary condition: Callback example 4 check arbitrary condition. 
* Callback example 5; fixed arguments: Callback example 5 fixed arguments. 
* Callback example 6; variable arguments: Callback example 6 variable arguments. 

Extending optparse

* Adding new types:: 
* Adding new actions:: 

curses --- Terminal handling for character-cell displays

* Fonctions: Fonctions<6>. 
* Window Objects:: 
* Constantes: Constantes<6>. 

curses.textpad --- Text input widget for curses programs

* Textbox objects:: 

curses.panel --- A panel stack extension for curses

* Fonctions: Fonctions<7>. 
* Panel Objects:: 

Exécution concourante

* threading: threading --- Thread-based parallelism. Thread-based parallelism
* multiprocessing: multiprocessing --- Process-based parallelism. Process-based parallelism
* multiprocessing.shared_memory: multiprocessing shared_memory --- Shared memory for direct access across processes. Shared memory for direct access across
                                 processes
* The concurrent package:: 
* concurrent.futures: concurrent futures --- Launching parallel tasks. Launching parallel tasks
* subprocess: subprocess --- Subprocess management. Subprocess management
* sched: sched --- Event scheduler. Event scheduler
* queue: queue --- A synchronized queue class. A synchronized queue class
* contextvars: contextvars --- Context Variables. Context Variables
* _thread: _thread --- Low-level threading API. Low-level threading API

threading --- Thread-based parallelism

* Données locales au fil d'exécution:: 
* Objets Threads:: 
* Verrous:: 
* RLock Objects:: 
* Condition Objects:: 
* Semaphore Objects:: 
* Event Objects:: 
* Timer Objects:: 
* Barrier Objects:: 
* Using locks@comma{} conditions@comma{} and semaphores in the with statement: Using locks conditions and semaphores in the with statement. 

Semaphore Objects

* Semaphore Example:: 

multiprocessing --- Process-based parallelism

* Introduction: Introduction<8>. 
* Référence:: 
* Lignes directrices de programmation:: 
* Exemples: Exemples<14>. 

Introduction

* La classe Process:: 
* Contextes et méthodes de démarrage:: 
* Échange d'objets entre les processus:: 
* Synchronisation entre processus:: 
* Partager un état entre les processus:: 
* Utiliser un pool de workers:: 

Référence

* Process et exceptions:: 
* Tubes (pipes) et files (queues): Tubes pipes et files queues. 
* Divers: Divers<3>. 
* Objets de connexions:: 
* Primitives de synchronisation:: 
* Objets ctypes partagés:: 
* Gestionnaires: Gestionnaires<2>. 
* Objets mandataires:: 
* Pools de processus:: 
* Auditeurs et Clients:: 
* Clés d'authentification:: 
* Journalisation: Journalisation<2>. 
* Le module multiprocessing.dummy: Le module multiprocessing dummy. 

Objets ctypes partagés

* Le module multiprocessing.sharedctypes: Le module multiprocessing sharedctypes. 

Gestionnaires

* Gestionnaires personnalisés:: 
* Utiliser un gestionnaire distant:: 

Objets mandataires

* Nettoyage: Nettoyage<2>. 

Auditeurs et Clients

* Formats d'adresses:: 

Lignes directrices de programmation

* Toutes les méthodes de démarrage:: 
* Les méthodes de démarrage spawn et forkserver:: 

concurrent.futures --- Launching parallel tasks

* Executor Objects:: 
* ThreadPoolExecutor:: 
* ProcessPoolExecutor:: 
* Future Objects:: 
* Module Functions:: 
* Exception classes:: 

ThreadPoolExecutor

* ThreadPoolExecutor Example:: 

ProcessPoolExecutor

* ProcessPoolExecutor Example:: 

subprocess --- Subprocess management

* Utiliser le module subprocess:: 
* Considérations de sécurité:: 
* Objets Popen:: 
* Utilitaires Popen pour Windows:: 
* Ancienne interface (API) haut-niveau: Ancienne interface API haut-niveau. 
* Remplacer les fonctions plus anciennes par le module subprocess:: 
* Remplacement des fonctions originales d'invocation du shell:: 
* Notes: Notes<2>. 

Utiliser le module subprocess

* Arguments fréquemment utilisés:: 
* Constructeur de Popen:: 
* Exceptions: Exceptions<11>. 

Utilitaires Popen pour Windows

* Constantes Windows:: 

Remplacer les fonctions plus anciennes par le module subprocess

* Remplacement de la substitution de commandes de terminal /bin/sh:: 
* Remplacer les pipes du shell:: 
* Remplacer os.system(): Remplacer os system. 
* Remplacer les fonctions de la famille os.spawn: Remplacer les fonctions de la famille os spawn. 
* Remplacer os.popen()@comma{} os.popen2()@comma{} os.popen3(): Remplacer os popen os popen2 os popen3. 
* Replacing functions from the popen2 module:: 

Notes

* Convertir une séquence d'arguments vers une chaîne de caractères sous Windows:: 
* Disabling use of vfork() or posix_spawn(): Disabling use of vfork or posix_spawn. 

sched --- Event scheduler

* Scheduler Objects:: 

queue --- A synchronized queue class

* Objets Queue:: 
* Objets SimpleQueue:: 

Objets Queue

* Terminating queues:: 

contextvars --- Context Variables

* Variables de contexte:: 
* Gestion de contexte manuelle:: 
* Gestion avec asyncio:: 

Réseau et communication entre processus

* asyncio: asyncio --- Asynchronous I/O. Asynchronous I/O
* socket: socket --- Low-level networking interface. Low-level networking interface
* ssl: ssl --- TLS/SSL wrapper for socket objects. TLS/SSL wrapper for socket objects
* select: select --- Waiting for I/O completion. Waiting for I/O completion
* selectors: selectors --- High-level I/O multiplexing. High-level I/O multiplexing
* signal: signal --- Set handlers for asynchronous events. Set handlers for asynchronous events
* mmap: mmap --- Memory-mapped file support. Memory-mapped file support

asyncio --- Asynchronous I/O

* Exécuteurs (runners): Exécuteurs runners. 
* Coroutines et tâches:: 
* Flux (streams): Flux streams. 
* Primitives de synchronisation: Primitives de synchronisation<2>. 
* Sous-processus:: 
* Files d'attente (queues): Files d'attente queues. 
* Exceptions: Exceptions<13>. 
* Boucle d'évènements:: 
* Futures:: 
* Transports et Protocoles:: 
* Politiques:: 
* Prise en charge de la plate-forme:: 
* Extension:: 
* Index de l'API de haut niveau:: 
* Index de l'API de bas niveau:: 
* Programmer avec asyncio:: 

Exécuteurs (runners)

* Exécution d'un programme asynchrone:: 
* Gestionnaire de contexte de l'exécuteur:: 
* Gestion de l'interruption par le clavier:: 

Coroutines et tâches

* Coroutines: Coroutines<3>. 
* Attendables:: 
* Création de tâches:: 
* Annulation de tâche:: 
* Groupes de tâches:: 
* Attente:: 
* Exécution de tâches de manière concurrente:: 
* Eager Task Factory:: 
* Protection contre l'annulation:: 
* Délais d'attente:: 
* Primitives d'attente:: 
* Exécution dans des fils d'exécution (threads): Exécution dans des fils d'exécution threads. 
* Planification depuis d'autres fils d'exécution:: 
* Introspection:: 
* Objets Task:: 

Groupes de tâches

* Terminating a Task Group:: 

Flux (streams)

* Flux lecteurs (StreamReader): Flux lecteurs StreamReader. 
* Flux écrivains (StreamWriter): Flux écrivains StreamWriter. 
* Exemples: Exemples<15>. 

Exemples

* Client d'écho TCP utilisant des flux:: 
* Serveur d'écho TCP utilisant des flux:: 
* Récupération des en-têtes HTTP:: 
* Ouverture d'un connecteur pour attendre les données à l'aide de flux:: 

Primitives de synchronisation

* Verrou (lock): Verrou lock. 
* Événement (Event): Événement Event. 
* Condition:: 
* Sémaphore:: 
* Sémaphore capé (BoundedSemaphore): Sémaphore capé BoundedSemaphore. 
* Barrière (Barrier): Barrière Barrier. 

Sous-processus

* Créer des sous-processus:: 
* Constantes: Constantes<7>. 
* Interagir avec les sous-processus:: 

Interagir avec les sous-processus

* Sous-processus et fils d'exécution:: 
* Exemples: Exemples<16>. 

Files d'attente (queues)

* File d'attente (queue): File d'attente queue. 
* File avec priorité:: 
* Pile (LIFO): Pile LIFO. 
* Exceptions: Exceptions<12>. 
* Exemples: Exemples<17>. 

Boucle d'évènements

* Méthodes de la boucle d'évènements:: 
* Fonctions de rappel sur des descripteurs:: 
* Objets Serveur:: 
* Implémentations de boucle d'évènements:: 
* Exemples: Exemples<18>. 

Méthodes de la boucle d'évènements

* Démarrer et arrêter une boucle d'évènements:: 
* Planification des fonctions de rappel:: 
* Planification des rappels différés:: 
* Création de Futures et des tâches:: 
* Création de connexions:: 
* Création de serveurs:: 
* Transfert de fichiers:: 
* Passage du flux en TLS:: 
* Surveillance de descripteur de fichier:: 
* Travail direct avec des objets socket:: 
* DNS:: 
* Travail avec des tubes (pipes): Travail avec des tubes pipes. 
* Signaux Unix:: 
* Exécution de code dans des pools de threads ou de processus:: 
* API de gestion d'erreur:: 
* Activation du mode débogage:: 
* Exécution de sous-processus:: 

Exemples

* "Hello World" avec call_soon(): "Hello World" avec call_soon. 
* Affichage de la date actuelle avec call_later(): Affichage de la date actuelle avec call_later. 
* Surveillance des événements de lecture pour un descripteur de fichier:: 
* Gestion des signaux SIGINT et SIGTERM:: 

Futures

* Fonctions pour Future:: 
* Objet Future:: 

Transports et Protocoles

* Transports:: 
* Protocoles:: 
* Exemples: Exemples<19>. 

Transports

* Hiérarchie des transports:: 
* Classe de base des Transports:: 
* Transports en lecture seule:: 
* Transports en lecture-écriture:: 
* Transports par datagrammes:: 
* Transports entre sous-processus:: 

Protocoles

* Protocoles de base:: 
* Protocoles de base: Protocoles de base<2>. 
* Protocoles connectés:: 
* Protocoles connectés avec tampon:: 
* Protocoles par datagrammes (non connectés): Protocoles par datagrammes non connectés. 
* Protocoles liés aux sous-processus:: 

Exemples

* Serveur écho en TCP:: 
* Client écho en TCP:: 
* Serveur écho en UDP:: 
* Client écho en UDP:: 
* Connexion de connecteurs existants:: 
* loop.subprocess_exec() et SubprocessProtocol: loop subprocess_exec et SubprocessProtocol. 

Politiques

* Obtenir et définir la politique:: 
* Objets politiques:: 
* Observateurs de processus:: 
* Politiques personnalisées:: 

Prise en charge de la plate-forme

* Toutes plateformes:: 
* Windows: Windows<75>. 
* macOS: macOS<47>. 

Windows

* Prise en charge des sous-processus sous Windows:: 

Extension

* Écriture d'une boucle d'événements personnalisée:: 
* Constructeurs privés Future et Task:: 
* Prise en charge de la durée de vie des tâches:: 

Index de l'API de haut niveau

* Tâches:: 
* Files d'attente:: 
* Sous-processus: Sous-processus<2>. 
* Flux (streams): Flux streams<2>. 
* Synchronisation:: 
* Exceptions: Exceptions<14>. 

Index de l'API de bas niveau

* Obtenir une boucle d'évènements:: 
* Méthodes de la boucle d'évènements: Méthodes de la boucle d'évènements<2>. 
* Transports: Transports<2>. 
* Protocoles: Protocoles<2>. 
* Politiques de boucle d'événements:: 

Programmer avec asyncio

* Mode débogage:: 
* Programmation concurrente et multi-fils:: 
* Exécution de code bloquant:: 
* Journalisation: Journalisation<3>. 
* Détection des coroutines jamais attendues:: 
* Détection des exceptions jamais récupérées:: 

socket --- Low-level networking interface

* Socket families:: 
* Module contents:: 
* Socket Objects:: 
* Notes on socket timeouts:: 
* Exemple: Exemple<7>. 

Module contents

* Exceptions: Exceptions<15>. 
* Constantes: Constantes<8>. 
* Fonctions: Fonctions<8>. 

Fonctions

* Creating sockets:: 
* Autres fonctions: Autres fonctions<2>. 

Notes on socket timeouts

* Timeouts and the connect method:: 
* Timeouts and the accept method:: 

ssl --- TLS/SSL wrapper for socket objects

* Fonctions@comma{} constantes et exceptions: Fonctions constantes et exceptions. 
* SSL Sockets:: 
* SSL Contexts:: 
* Certificates:: 
* Exemples: Exemples<20>. 
* Notes on non-blocking sockets:: 
* Memory BIO Support: Memory BIO Support<2>. 
* SSL session:: 
* Security considerations: Security considerations<2>. 
* TLS 1.3: TLS 1 3. 

Fonctions, constantes et exceptions

* Création de connecteurs:: 
* Création de contexte:: 
* Exceptions: Exceptions<16>. 
* Random generation:: 
* Certificate handling:: 
* Constantes: Constantes<9>. 

Certificates

* Certificate chains:: 
* CA certificates:: 
* Combined key and certificate:: 
* Self-signed certificates:: 

Exemples

* Testing for SSL support:: 
* Client-side operation:: 
* Server-side operation:: 

Security considerations

* Best defaults:: 
* Manual settings:: 
* Multi-processing:: 

Manual settings

* Verifying certificates:: 
* Protocol versions:: 
* Cipher selection:: 

select --- Waiting for I/O completion

* /dev/poll Polling Objects:: 
* Edge and Level Trigger Polling (epoll) Objects: Edge and Level Trigger Polling epoll Objects. 
* Polling Objects:: 
* Kqueue Objects:: 
* Kevent Objects:: 

selectors --- High-level I/O multiplexing

* Introduction: Introduction<9>. 
* Classes: Classes<4>. 
* Exemples: Exemples<21>. 

signal --- Set handlers for asynchronous events

* General rules:: 
* Module contents: Module contents<2>. 
* Examples:: 
* Note on SIGPIPE:: 
* Note on Signal Handlers and Exceptions:: 

General rules

* Execution of Python signal handlers:: 
* Signals and threads:: 

mmap --- Memory-mapped file support

* MADV_* Constants:: 
* MAP_* Constants:: 

Traitement des données provenant d'Internet

* email: email --- An email and MIME handling package. An email and MIME handling package
* json: json --- JSON encoder and decoder. JSON encoder and decoder
* mailbox: mailbox --- Manipulate mailboxes in various formats. Manipulate mailboxes in various formats
* mimetypes: mimetypes --- Map filenames to MIME types. Map filenames to MIME types
* base64: base64 --- Base16 Base32 Base64 Base85 Data Encodings. Base16, Base32, Base64, Base85 Data Encodings
* binascii: binascii --- Convert between binary and ASCII. Convert between binary and ASCII
* quopri: quopri --- Encode and decode MIME quoted-printable data. Encode and decode MIME quoted-printable data

email --- An email and MIME handling package

* email.message; Representing an email message: email message Representing an email message. 
* email.parser; Parsing email messages: email parser Parsing email messages. 
* email.generator; Generating MIME documents: email generator Generating MIME documents. 
* email.policy; Policy Objects: email policy Policy Objects. 
* email.errors; Exception and Defect classes: email errors Exception and Defect classes. 
* email.headerregistry; Custom Header Objects: email headerregistry Custom Header Objects. 
* email.contentmanager; Managing MIME Content: email contentmanager Managing MIME Content. 
* email; Exemples: email Exemples. 
* email.message.Message ; représentation d'un message électronique à l'aide de l'API compat32: email message Message représentation d'un message électronique à l'aide de l'API compat32. 
* email.mime; Creating email and MIME objects from scratch: email mime Creating email and MIME objects from scratch. 
* email.header; Internationalized headers: email header Internationalized headers. 
* email.charset; Representing character sets: email charset Representing character sets. 
* email.encoders; Encoders: email encoders Encoders. 
* email.utils; Miscellaneous utilities: email utils Miscellaneous utilities. 
* email.iterators; Iterators: email iterators Iterators. 

email.parser: Parsing email messages

* API FeedParser:: 
* API de Parser:: 
* Notes complémentaires:: 

email.contentmanager: Managing MIME Content

* Instances de gestionnaires de contenus:: 

json --- JSON encoder and decoder

* Utilisation de base:: 
* Encodeurs et décodeurs:: 
* Exceptions: Exceptions<17>. 
* Conformité au standard et Interopérabilité:: 
* Interface en ligne de commande: Interface en ligne de commande<4>. 

Conformité au standard et Interopérabilité

* Encodage des caractères:: 
* Valeurs numériques infinies et NaN:: 
* Noms répétés au sein d'un objet:: 
* Valeurs de plus haut niveau (hors objets ou tableaux): Valeurs de plus haut niveau hors objets ou tableaux. 
* Limitations de l'implémentation:: 

Interface en ligne de commande

* Options de la ligne de commande: Options de la ligne de commande<4>. 

mailbox --- Manipulate mailboxes in various formats

* Mailbox objects:: 
* Message objects:: 
* Exceptions: Exceptions<18>. 
* Exemples: Exemples<22>. 

Mailbox objects

* Maildir objects:: 
* mbox objects:: 
* MH objects:: 
* Babyl objects:: 
* MMDF objects:: 

Message objects

* MaildirMessage objects:: 
* mboxMessage objects:: 
* MHMessage objects:: 
* BabylMessage objects:: 
* MMDFMessage objects:: 

mimetypes --- Map filenames to MIME types

* MimeTypes Objects:: 

base64 --- Base16, Base32, Base64, Base85 Data Encodings

* Considérations de sécurité: Considérations de sécurité<2>. 

Outils de traitement de balises structurées

* html: html --- HyperText Markup Language support. HyperText Markup Language support
* html.parser: html parser --- Simple HTML and XHTML parser. Simple HTML and XHTML parser
* html.entities: html entities --- Definitions of HTML general entities. Definitions of HTML general entities
* Modules de traitement XML:: 
* xml.etree.ElementTree: xml etree ElementTree --- The ElementTree XML API. The ElementTree XML API
* xml.dom: xml dom --- The Document Object Model API. The Document Object Model API
* xml.dom.minidom: xml dom minidom --- Minimal DOM implementation. Minimal DOM implementation
* xml.dom.pulldom: xml dom pulldom --- Support for building partial DOM trees. Support for building partial DOM trees
* xml.sax: xml sax --- Support for SAX2 parsers. Support for SAX2 parsers
* xml.sax.handler: xml sax handler --- Base classes for SAX handlers. Base classes for SAX handlers
* xml.sax.saxutils: xml sax saxutils --- SAX Utilities. SAX Utilities
* xml.sax.xmlreader: xml sax xmlreader --- Interface for XML parsers. Interface for XML parsers
* xml.parsers.expat: xml parsers expat --- Fast XML parsing using Expat. Fast XML parsing using Expat

html.parser --- Simple HTML and XHTML parser

* Exemple d'application de l'analyseur HTML:: 
* Méthodes de la classe HTMLParser:: 
* Exemples: Exemples<23>. 

Modules de traitement XML

* Vulnérabilités XML:: 
* The defusedxml Package:: 

xml.etree.ElementTree --- The ElementTree XML API

* Tutoriel: Tutoriel<3>. 
* Prise en charge de XPath:: 
* Référence: Référence<2>. 
* Prise en charge de XInclude:: 
* Référence: Référence<3>. 

Tutoriel

* Arborescence et éléments XML:: 
* Analyse XML:: 
* API à flux tiré:: 
* Atteinte d'éléments d'intérêt:: 
* Modification d'un fichier XML:: 
* Création de documents XML:: 
* Analyse d'un XML avec des espaces de noms:: 

Prise en charge de XPath

* Exemple: Exemple<8>. 
* Prise en charge de la syntaxe XPath:: 

Référence

* Fonctions: Fonctions<9>. 

Prise en charge de XInclude

* Exemple: Exemple<9>. 

Référence

* Fonctions: Fonctions<10>. 
* Objets Element:: 
* Objets ElementTree:: 
* Objets QName:: 
* Objets TreeBuilder:: 
* Objets XMLParser:: 
* Objets XMLPullParser:: 
* Exceptions: Exceptions<19>. 

xml.dom --- The Document Object Model API

* Contenu du module: Contenu du module<4>. 
* Objets dans le DOM:: 
* Conformité:: 

Objets dans le DOM

* Objets DOMImplementation:: 
* Objets nœuds:: 
* Objet NodeList:: 
* Objets DocumnentType:: 
* Objets Document:: 
* Objets Elements:: 
* Objets Attr:: 
* Objets NameNodeMap:: 
* Objets Comment:: 
* Objets Text et CDATASection:: 
* Objets ProcessingInstruction:: 
* Exceptions: Exceptions<20>. 

Conformité

* Correspondance des types:: 
* Méthodes d'accès:: 

xml.dom.minidom --- Minimal DOM implementation

* Objets DOM:: 
* Exemple DOM:: 
* minidom et le standard DOM:: 

xml.dom.pulldom --- Support for building partial DOM trees

* Objets DOMEventStream:: 

xml.sax --- Support for SAX2 parsers

* Les objets SAXException:: 

xml.sax.handler --- Base classes for SAX handlers

* Objets ContentHandler:: 
* Objets DTDHandler:: 
* Objets EntityResolver:: 
* Objets ErrorHandler:: 
* Objets LexicalHandler:: 

xml.sax.xmlreader --- Interface for XML parsers

* XMLReader Objects:: 
* IncrementalParser Objects:: 
* Locator Objects:: 
* InputSource Objects:: 
* The Attributes Interface:: 
* The AttributesNS Interface:: 

xml.parsers.expat --- Fast XML parsing using Expat

* Objets XMLParser: Objets XMLParser<2>. 
* ExpatError Exceptions:: 
* Exemple: Exemple<10>. 
* Content Model Descriptions:: 
* Expat error constants:: 

Gestion des protocoles internet

* webbrowser: webbrowser --- Convenient web-browser controller. Convenient web-browser controller
* wsgiref: wsgiref --- WSGI Utilities and Reference Implementation. WSGI Utilities and Reference Implementation
* urllib: urllib --- URL handling modules. URL handling modules
* urllib.request: urllib request --- Extensible library for opening URLs. Extensible library for opening URLs
* urllib.response: urllib response --- Response classes used by urllib. Response classes used by urllib
* urllib.parse: urllib parse --- Parse URLs into components. Parse URLs into components
* urllib.error: urllib error --- Exception classes raised by urllib request. Exception classes raised by urllib.request
* urllib.robotparser: urllib robotparser --- Parser for robots txt. Parser for robots.txt
* http: http --- HTTP modules. HTTP modules
* http.client: http client --- HTTP protocol client. HTTP protocol client
* ftplib: ftplib --- FTP protocol client. FTP protocol client
* poplib: poplib --- POP3 protocol client. POP3 protocol client
* imaplib: imaplib --- IMAP4 protocol client. IMAP4 protocol client
* smtplib: smtplib --- SMTP protocol client. SMTP protocol client
* uuid: uuid --- UUID objects according to RFC 4122. UUID objects according to RFC 4122
* socketserver: socketserver --- A framework for network servers. A framework for network servers
* http.server: http server --- HTTP servers. HTTP servers
* http.cookies: http cookies --- HTTP state management. HTTP state management
* http.cookiejar: http cookiejar --- Cookie handling for HTTP clients. Cookie handling for HTTP clients
* xmlrpc: xmlrpc --- XMLRPC server and client modules. XMLRPC server and client modules
* xmlrpc.client: xmlrpc client --- XML-RPC client access. XML-RPC client access
* xmlrpc.server: xmlrpc server --- Basic XML-RPC servers. Basic XML-RPC servers
* ipaddress: ipaddress --- IPv4/IPv6 manipulation library. IPv4/IPv6 manipulation library

webbrowser --- Convenient web-browser controller

* Browser Controller Objects:: 

wsgiref --- WSGI Utilities and Reference Implementation

* wsgiref.util — outils pour les environnements WSGI: wsgiref util — outils pour les environnements WSGI. 
* wsgiref.headers: wsgiref headers -- WSGI response header tools. WSGI response header tools
* wsgiref.simple_server: wsgiref simple_server -- a simple WSGI HTTP server. a simple WSGI HTTP server
* wsgiref.validate: wsgiref validate --- WSGI conformance checker. WSGI conformance checker
* wsgiref.handlers: wsgiref handlers -- server/gateway base classes. server/gateway base classes
* wsgiref.types: wsgiref types -- WSGI types for static type checking. WSGI types for static type checking
* Exemples: Exemples<24>. 

urllib.request --- Extensible library for opening URLs

* Request Objects:: 
* OpenerDirector Objects:: 
* BaseHandler Objects:: 
* HTTPRedirectHandler Objects:: 
* HTTPCookieProcessor Objects:: 
* ProxyHandler Objects:: 
* HTTPPasswordMgr Objects:: 
* HTTPPasswordMgrWithPriorAuth Objects:: 
* AbstractBasicAuthHandler Objects:: 
* HTTPBasicAuthHandler Objects:: 
* ProxyBasicAuthHandler Objects:: 
* AbstractDigestAuthHandler Objects:: 
* HTTPDigestAuthHandler Objects:: 
* ProxyDigestAuthHandler Objects:: 
* HTTPHandler Objects:: 
* HTTPSHandler Objects:: 
* FileHandler Objects:: 
* DataHandler Objects:: 
* FTPHandler Objects:: 
* CacheFTPHandler Objects:: 
* UnknownHandler Objects:: 
* HTTPErrorProcessor Objects:: 
* Exemples: Exemples<25>. 
* Legacy interface:: 
* urllib.request Restrictions: urllib request Restrictions. 

urllib.parse --- Parse URLs into components

* URL Parsing:: 
* URL parsing security:: 
* Parsing ASCII Encoded Bytes:: 
* Structured Parse Results:: 
* URL Quoting:: 

http --- HTTP modules

* Codes d'état HTTP:: 
* HTTP status category:: 
* HTTP methods:: 

http.client --- HTTP protocol client

* Les objets HTTPConnection:: 
* Les objets HTTPResponse:: 
* Exemples: Exemples<26>. 
* Les objets HTTPMessage:: 

ftplib --- FTP protocol client

* Référence: Référence<4>. 

Référence

* FTP objects:: 
* FTP_TLS objects:: 
* Module variables:: 

poplib --- POP3 protocol client

* POP3 Objects:: 
* POP3 Example:: 

imaplib --- IMAP4 protocol client

* IMAP4 Objects:: 
* IMAP4 Example:: 

smtplib --- SMTP protocol client

* SMTP Objects:: 
* SMTP Example:: 

uuid --- UUID objects according to RFC 4122

* Utilisation en ligne de commande.: Utilisation en ligne de commande<2>. 
* Exemple: Exemple<11>. 
* Command-Line Example:: 

socketserver --- A framework for network servers

* Notes sur la création de serveurs:: 
* Objets serveur:: 
* Objets gestionnaire de requêtes:: 
* Exemples: Exemples<27>. 

Exemples

* Exemple pour socketserver.TCPServer: Exemple pour socketserver TCPServer. 
* Exemple pour socketserver.UDPServer: Exemple pour socketserver UDPServer. 
* Classes de mélange asynchrone:: 

http.server --- HTTP servers

* Considérations de sécurité: Considérations de sécurité<3>. 

http.cookies --- HTTP state management

* Objets Cookie:: 
* Objets Morsel:: 
* Exemple: Exemple<12>. 

http.cookiejar --- Cookie handling for HTTP clients

* CookieJar and FileCookieJar Objects:: 
* FileCookieJar subclasses and co-operation with web browsers:: 
* CookiePolicy Objects:: 
* DefaultCookiePolicy Objects:: 
* Objets Cookie: Objets Cookie<2>. 
* Exemples: Exemples<28>. 

xmlrpc.client --- XML-RPC client access

* ServerProxy Objects:: 
* Objets DateTime:: 
* Binary Objects:: 
* Fault Objects:: 
* ProtocolError Objects:: 
* MultiCall Objects:: 
* Convenience Functions:: 
* Example of Client Usage:: 
* Example of Client and Server Usage:: 

xmlrpc.server --- Basic XML-RPC servers

* SimpleXMLRPCServer Objects:: 
* CGIXMLRPCRequestHandler:: 
* Documenting XMLRPC server:: 
* DocXMLRPCServer Objects:: 
* DocCGIXMLRPCRequestHandler:: 

SimpleXMLRPCServer Objects

* SimpleXMLRPCServer Example:: 

ipaddress --- IPv4/IPv6 manipulation library

* Fonctions fabriques pratiques:: 
* Adresses IP:: 
* Définitions de réseaux IP:: 
* Objets interface:: 
* Autres fonctions au niveau de module:: 
* Exceptions personnalisées:: 

Adresses IP

* Objets adresse:: 
* Conversion vers les chaînes et les entiers:: 
* Opérateurs: Opérateurs<3>. 

Opérateurs

* Opérateurs de comparaison:: 
* Opérateurs arithmétiques:: 

Définitions de réseaux IP

* Préfixe@comma{} masque réseau et masque de l'hôte: Préfixe masque réseau et masque de l'hôte. 
* Objets réseau:: 
* Opérateurs: Opérateurs<4>. 

Opérateurs

* Opérateurs logiques:: 
* Itération:: 
* Réseaux en tant que conteneurs d'adresses:: 

Objets interface

* Opérateurs: Opérateurs<5>. 

Opérateurs

* Opérateurs logiques: Opérateurs logiques<2>. 

Services multimédia

* wave: wave --- Read and write WAV files. Read and write WAV files
* colorsys: colorsys --- Conversions between color systems. Conversions between color systems

wave --- Read and write WAV files

* Objets Wave_read:: 
* Objets Wave_write:: 

Internationalisation

* gettext: gettext --- Multilingual internationalization services. Multilingual internationalization services
* locale: locale --- Internationalization services. Internationalization services

gettext --- Multilingual internationalization services

* API GNU gettext:: 
* API basée sur les classes:: 
* Internationaliser vos programmes et modules:: 
* Remerciements: Remerciements<9>. 

API basée sur les classes

* La classe NullTranslations:: 
* La classe GNUTranslations:: 
* Support du catalogue de message de Solaris:: 
* Le constructeur Catalog:: 

Internationaliser vos programmes et modules

* Localiser votre module:: 
* Localiser votre application:: 
* Changer de langue à la volée:: 
* Traductions différées:: 

locale --- Internationalization services

* Contexte@comma{} détails@comma{} conseils@comma{} astuces et mises en garde: Contexte détails conseils astuces et mises en garde. 
* Pour les auteurs d'extensions et les programmes qui intègrent Python:: 
* Accéder aux catalogues de messages:: 

Cadriciels d'applications

* turtle — Tortue graphique:: 
* cmd: cmd --- Support for line-oriented command interpreters. Support for line-oriented command interpreters
* shlex: shlex --- Simple lexical analysis. Simple lexical analysis

turtle — Tortue graphique

* Introduction: Introduction<10>. 
* Get started:: 
* Tutoriel: Tutoriel<4>. 
* How to...: How to. 
* Turtle graphics reference:: 
* Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes:: 
* Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes:: 
* Classes publiques:: 
* Explication:: 
* Aide et configuration:: 
* turtledemo — Scripts de démonstration:: 
* Modifications depuis Python 2.6: Modifications depuis Python 2 6. 
* Modifications depuis Python 3.0: Modifications depuis Python 3 0. 

Tutoriel

* Starting a turtle environment:: 
* Basic drawing:: 
* Making algorithmic patterns:: 

Basic drawing

* Réglage des stylos:: 
* The turtle's position:: 

How to...

* Get started as quickly as possible:: 
* Use the turtle module namespace:: 
* Use turtle graphics in a script:: 
* Use object-oriented turtle graphics:: 

Turtle graphics reference

* Les méthodes du module Turtle:: 
* Méthodes de TurtleScreen/Screen:: 

Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes

* Les mouvements dans le module Turtle:: 
* Connaître l'état de la tortue:: 
* Paramètres de mesure:: 
* Réglage des stylos: Réglage des stylos<2>. 
* État de la tortue:: 
* Utilisation des événements:: 
* Méthodes spéciales de la tortue:: 
* Formes composées:: 

Réglage des stylos

* État des stylos:: 
* Réglage des couleurs:: 
* Remplissage:: 
* Plus des réglages pour le dessin:: 

État de la tortue

* Visibilité:: 
* Apparence:: 

Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes

* Réglage de la fenêtre:: 
* Réglage de l'animation:: 
* Utilisation des événements concernant l'écran:: 
* Méthodes de saisie:: 
* Paramétrages et méthodes spéciales:: 
* Méthodes spécifiques à Screen@comma{} non héritées de TurtleScreen: Méthodes spécifiques à Screen non héritées de TurtleScreen. 

Aide et configuration

* Utilisation de l'aide:: 
* Traduction de chaînes de documents en différentes langues:: 
* Comment configurer Screen et Turtle:: 

cmd --- Support for line-oriented command interpreters

* Objets Cmd:: 
* Exemple: Exemple<13>. 

shlex --- Simple lexical analysis

* shlex Objects:: 
* Parsing Rules:: 
* Improved Compatibility with Shells:: 

Interfaces Utilisateur Graphiques avec Tk

* tkinter: tkinter --- Python interface to Tcl/Tk. Python interface to Tcl/Tk
* tkinter.colorchooser: tkinter colorchooser --- Color choosing dialog. Color choosing dialog
* tkinter.font: tkinter font --- Tkinter font wrapper. Tkinter font wrapper
* Boîtes de dialogue Tkinter:: 
* tkinter.messagebox: tkinter messagebox --- Tkinter message prompts. Tkinter message prompts
* tkinter.scrolledtext: tkinter scrolledtext --- Scrolled Text Widget. Scrolled Text Widget
* tkinter.dnd: tkinter dnd --- Drag and drop support. Drag and drop support
* tkinter.ttk: tkinter ttk --- Tk themed widgets. Tk themed widgets
* IDLE: IDLE<64>. 

tkinter --- Python interface to Tcl/Tk

* Architecture:: 
* Modules Tkinter:: 
* Guide de survie Tkinter:: 
* Fils d'exécution multiples:: 
* Guide pratique:: 
* Gestionnaires de fichiers:: 

Guide de survie Tkinter

* Un simple programme Hello World:: 
* Concepts importants de Tk:: 
* Comprendre comment Tkinter enveloppe Tcl/Tk:: 
* Comment puis-je… ? Quelle option… ?:: 
* Navigation dans le manuel de référence Tcl/Tk:: 

Guide pratique

* Définition des options:: 
* L'empaqueteur:: 
* Options de l'empaqueteur:: 
* Association des variables de l'objet graphique:: 
* Le gestionnaire de fenêtres:: 
* Types de données des options Tk:: 
* Liaisons et événements:: 
* Le paramètre index:: 
* Images:: 

Boîtes de dialogue Tkinter

* tkinter.simpledialog – Boîtes de dialogue de saisie standard de Tkinter: tkinter simpledialog – Boîtes de dialogue de saisie standard de Tkinter. 
* tkinter.filedialog – Boîtes de dialogue de sélection de fichiers: tkinter filedialog – Boîtes de dialogue de sélection de fichiers. 
* tkinter.commondialog – Modèles de fenêtre de dialogue: tkinter commondialog – Modèles de fenêtre de dialogue. 

tkinter.filedialog – Boîtes de dialogue de sélection de fichiers

* Boîtes de dialogue de chargement et sauvegarde natives:: 

tkinter.ttk --- Tk themed widgets

* Utilisation de Ttk:: 
* Widgets Ttk:: 
* Widget:: 
* Combobox:: 
* Spinbox:: 
* Carnet de notes (notebook): Carnet de notes notebook. 
* Barre de progression:: 
* Séparateur:: 
* Poignée de redimensionnement:: 
* Arborescence:: 
* Style Ttk:: 

Widget

* Options standards:: 
* Options de widget avec barre de défilement:: 
* Options d'étiquette (label): Options d'étiquette label. 
* Options de compatibilité:: 
* États des widgets:: 
* ttk.Widget: ttk Widget. 

Combobox

* Options:: 
* Événements virtuels:: 
* ttk.Combobox: ttk Combobox. 

Spinbox

* Options: Options<2>. 
* Événements virtuels: Événements virtuels<2>. 
* ttk.Spinbox: ttk Spinbox. 

Carnet de notes (notebook)

* Options: Options<3>. 
* Options d'onglet:: 
* Identifiants d'onglet:: 
* Événements virtuels: Événements virtuels<3>. 
* ttk.Notebook: ttk Notebook. 

Barre de progression

* Options: Options<4>. 
* ttk.Progressbar: ttk Progressbar. 

Séparateur

* Options: Options<5>. 

Poignée de redimensionnement

* Notes spécifiques à une plateforme:: 
* Bogues:: 

Arborescence

* Options: Options<6>. 
* Options d'éléments:: 
* Options de balise:: 
* Identifiants de colonnes:: 
* Événements virtuels: Événements virtuels<4>. 
* ttk.Treeview: ttk Treeview. 

Style Ttk

* Dispositions de mise en page:: 

IDLE

* Menus:: 
* Editing and Navigation:: 
* Startup and Code Execution:: 
* Help and Preferences:: 
* idlelib:: 

Menus

* Menu File (Console et Éditeur): Menu File Console et Éditeur. 
* Menu Edit (console et éditeur): Menu Edit console et éditeur. 
* Menu Format (fenêtre d'édition uniquement): Menu Format fenêtre d'édition uniquement. 
* Menu Run (fenêtre d'édition uniquement): Menu Run fenêtre d'édition uniquement. 
* Menu Shell (fenêtre de console uniquement): Menu Shell fenêtre de console uniquement. 
* Menu Debug (fenêtre de console uniquement): Menu Debug fenêtre de console uniquement. 
* Menu Options (console et éditeur): Menu Options console et éditeur. 
* Menu Windows (console et éditeur): Menu Windows console et éditeur. 
* Menu Help (console et éditeur): Menu Help console et éditeur. 
* Context menus:: 

Editing and Navigation

* Fenêtre d'édition:: 
* Raccourcis clavier:: 
* Indentation automatique:: 
* Recherche et substitution:: 
* Complétions:: 
* Info-bulles:: 
* Contexte du code:: 
* Shell window:: 
* Coloration du texte:: 

Startup and Code Execution

* Utilisation de la ligne de commande:: 
* Échec au démarrage:: 
* Exécuter le code de l'utilisateur:: 
* Sortie de l'utilisateur sur la console:: 
* Développer des applications tkinter:: 
* Exécution sans sous-processus:: 

Help and Preferences

* Sources d'aide:: 
* Modifier les préférences:: 
* IDLE sous macOS:: 
* Extensions:: 

Outils de développement

* typing — Prise en charge des annotations de type:: 
* pydoc: pydoc --- Documentation generator and online help system. Documentation generator and online help system
* Python Development Mode:: 
* doctest — Exemples de tests interactifs en Python:: 
* unittest: unittest --- Unit testing framework. Unit testing framework
* unittest.mock: unittest mock --- mock object library. mock object library
* unittest.mock: unittest mock --- getting started. getting started
* test: test --- Regression tests package for Python. Regression tests package for Python
* test.support: test support --- Utilities for the Python test suite. Utilities for the Python test suite
* test.support.socket_helper: test support socket_helper --- Utilities for socket tests. Utilities for socket tests
* test.support.script_helper: test support script_helper --- Utilities for the Python execution tests. Utilities for the Python execution tests
* test.support.bytecode_helper: test support bytecode_helper --- Support tools for testing correct bytecode generation. Support tools for testing correct bytecode
                                generation
* test.support.threading_helper: test support threading_helper --- Utilities for threading tests. Utilities for threading tests
* test.support.os_helper: test support os_helper --- Utilities for os tests. Utilities for os tests
* test.support.import_helper: test support import_helper --- Utilities for import tests. Utilities for import tests
* test.support.warnings_helper: test support warnings_helper --- Utilities for warnings tests. Utilities for warnings tests

typing — Prise en charge des annotations de type

* Specification for the Python Type System:: 
* Alias de type:: 
* NewType:: 
* Annotating callable objects:: 
* Génériques:: 
* Annotating tuples:: 
* The type of class objects:: 
* Annotating generators and coroutines:: 
* Types génériques définis par l'utilisateur:: 
* Le type Any:: 
* Sous-typage nominal et sous-typage structurel:: 
* Classe de données:: 
* Étapes d'Obsolescence des Fonctionnalités Majeures:: 

Classe de données

* Special typing primitives:: 
* Protocoles: Protocoles<3>. 
* ABCs for working with IO:: 
* Functions and decorators:: 
* Utilitaires d'introspection:: 
* Constante:: 
* Deprecated aliases:: 

Special typing primitives

* Special types:: 
* Special forms:: 
* Building generic types and type aliases:: 
* Other special directives:: 

Deprecated aliases

* Aliases to built-in types:: 
* Aliases to types in collections:: 
* Aliases to other concrete types:: 
* Aliases to container ABCs in collections.abc: Aliases to container ABCs in collections abc. 
* Aliases to asynchronous ABCs in collections.abc: Aliases to asynchronous ABCs in collections abc. 
* Aliases to other ABCs in collections.abc: Aliases to other ABCs in collections abc. 
* Aliases to contextlib ABCs:: 

Python Development Mode

* Effects of the Python Development Mode:: 
* ResourceWarning Example:: 
* Bad file descriptor error example:: 

doctest — Exemples de tests interactifs en Python

* Utilisation simple ; vérifier des exemples dans des docstrings: Utilisation simple vérifier des exemples dans des docstrings. 
* Utilisation simple ; vérifier des exemples dans un fichier texte: Utilisation simple vérifier des exemples dans un fichier texte. 
* Comment ça marche:: 
* API de base:: 
* API de tests unitaires:: 
* API avancé:: 
* Débogage:: 
* Éditorial:: 

Comment ça marche

* Quelles docstrings sont considérées ?:: 
* Comment les exemples docstring sont-ils identifiés ?:: 
* Quel est le contexte d'exécution ?:: 
* Qu'en est-il des exceptions ?:: 
* Options de ligne de commande:: 
* Instructions:: 
* Avertissements: Avertissements<2>. 

API avancé

* Objets doctest:: 
* Exemples d'objets:: 
* Objets DocTestFinder:: 
* Objets DocTestParser:: 
* Objets TestResults:: 
* Objets DocTestRunner:: 
* Objets OutputChecker:: 

unittest --- Unit testing framework

* Exemple basique:: 
* Interface en ligne de commande: Interface en ligne de commande<5>. 
* Découverte des tests:: 
* Organiser le code de test:: 
* Réutilisation d'ancien code de test:: 
* Ignorer des tests et des erreurs prévisibles:: 
* Distinguer les itérations de test à l'aide de sous-tests:: 
* Classes et fonctions:: 
* Classes et modules d'aménagements des tests:: 
* Traitement des signaux:: 

Interface en ligne de commande

* Options de la ligne de commande: Options de la ligne de commande<5>. 

Classes et fonctions

* Scénarios de tests:: 
* Regroupement des tests:: 
* Chargement et exécution des tests:: 

Chargement et exécution des tests

* Protocole de chargement des tests (load_tests Protocol): Protocole de chargement des tests load_tests Protocol. 

Classes et modules d'aménagements des tests

* Classes de mise en place (setUpClass) et de démantèlement des tests (tearDownClass): Classes de mise en place setUpClass et de démantèlement des tests tearDownClass. 
* Module de mise en place (setUpModule) et de démantèlement des tests (tearDownModule): Module de mise en place setUpModule et de démantèlement des tests tearDownModule. 

unittest.mock --- mock object library

* Guide rapide:: 
* La classe Mock:: 
* The patchers:: 
* MagicMock and magic method support:: 
* Helpers:: 
* Order of precedence of side_effect@comma{} return_value and wraps: Order of precedence of side_effect return_value and wraps. 

La classe Mock

* Calling:: 
* Deleting Attributes:: 
* Mock names and the name attribute:: 
* Attaching Mocks as Attributes:: 

The patchers

* patch:: 
* patch.object: patch object. 
* patch.dict: patch dict. 
* patch.multiple: patch multiple. 
* patch methods; start and stop: patch methods start and stop. 
* patch builtins:: 
* TEST_PREFIX:: 
* Nesting Patch Decorators:: 
* Where to patch:: 
* Patching Descriptors and Proxy Objects:: 

MagicMock and magic method support

* Mocking Magic Methods:: 
* Magic Mock:: 

Helpers

* sentinel:: 
* DEFAULT:: 
* appel:: 
* create_autospec:: 
* ANY:: 
* FILTER_DIR:: 
* mock_open:: 
* Autospeccing:: 
* Sealing mocks:: 

unittest.mock --- getting started

* Utilisation de Mock ou l'art de singer:: 
* Patch Decorators:: 
* Further Examples:: 

Utilisation de Mock ou l'art de singer

* Simulation des méthodes:: 
* S'assurer de la bonne utilisation d'un objet:: 
* Simulation des classes:: 
* Naming your mocks:: 
* Tracking all Calls:: 
* Setting Return Values and Attributes:: 
* Raising exceptions with mocks:: 
* Side effect functions and iterables:: 
* Mocking asynchronous iterators:: 
* Mocking asynchronous context manager:: 
* Creating a Mock from an Existing Object:: 
* Using side_effect to return per file content:: 

Further Examples

* Mocking chained calls:: 
* Partial mocking:: 
* Mocking a Generator Method:: 
* Applying the same patch to every test method:: 
* Mocking Unbound Methods:: 
* Checking multiple calls with mock:: 
* Coping with mutable arguments:: 
* Nesting Patches:: 
* Mocking a dictionary with MagicMock:: 
* Mock subclasses and their attributes:: 
* Mocking imports with patch.dict: Mocking imports with patch dict. 
* Tracking order of calls and less verbose call assertions:: 
* More complex argument matching:: 

test --- Regression tests package for Python

* Writing Unit Tests for the test package:: 
* Running tests using the command-line interface:: 

Débogueur et instrumentation

* Table des évènements d'audit:: 
* bdb: bdb --- Debugger framework. Debugger framework
* faulthandler: faulthandler --- Dump the Python traceback. Dump the Python traceback
* pdb — Le débogueur Python:: 
* The Python Profilers:: 
* timeit: timeit --- Measure execution time of small code snippets. Measure execution time of small code snippets
* trace: trace --- Trace or track Python statement execution. Trace or track Python statement execution
* tracemalloc: tracemalloc --- Trace memory allocations. Trace memory allocations

faulthandler --- Dump the Python traceback

* Dumping the traceback:: 
* Fault handler state:: 
* Dumping the tracebacks after a timeout:: 
* Dumping the traceback on a user signal:: 
* Issue with file descriptors:: 
* Exemple: Exemple<14>. 

pdb — Le débogueur Python

* Commande du débogueur:: 

The Python Profilers

* Introduction to the profilers:: 
* Instant User's Manual:: 
* profile and cProfile Module Reference:: 
* The Stats Class:: 
* What Is Deterministic Profiling?:: 
* Limitations:: 
* Calibration:: 
* Using a custom timer:: 

timeit --- Measure execution time of small code snippets

* Exemples simples: Exemples simples<2>. 
* Interface Python:: 
* Interface en ligne de commande: Interface en ligne de commande<6>. 
* Exemples: Exemples<29>. 

trace --- Trace or track Python statement execution

* Utilisation en ligne de commande.: Utilisation en ligne de commande<3>. 
* Programmatic Interface:: 

Utilisation en ligne de commande.

* Main options:: 
* Modifiers:: 
* Filters:: 

tracemalloc --- Trace memory allocations

* Exemples: Exemples<30>. 
* API:: 

Exemples

* Display the top 10:: 
* Compute differences:: 
* Get the traceback of a memory block:: 
* Pretty top:: 

Pretty top

* Record the current and peak size of all traced memory blocks:: 

API

* Fonctions: Fonctions<11>. 
* DomainFilter:: 
* Filter:: 
* Frame:: 
* Snapshot:: 
* Statistic:: 
* StatisticDiff:: 
* Trace:: 
* Traceback:: 

Paquets et distribution de paquets logiciels

* ensurepip: ensurepip --- Bootstrapping the pip installer. Bootstrapping the pip installer
* venv: venv --- Creation of virtual environments. Creation of virtual environments
* zipapp: zipapp --- Manage executable Python zip archives. Manage executable Python zip archives

ensurepip --- Bootstrapping the pip installer

* Interface en ligne de commande: Interface en ligne de commande<7>. 
* API du module:: 

venv --- Creation of virtual environments

* Création d'environnements virtuels: Création d'environnements virtuels<2>. 
* How venvs work:: 
* API: API<2>. 
* Un exemple d'extension de EnvBuilder:: 

zipapp --- Manage executable Python zip archives

* Exemple de base:: 
* Interface en ligne de commande: Interface en ligne de commande<8>. 
* API Python:: 
* Exemples: Exemples<31>. 
* Spécification de l'interprète:: 
* Création d'applications autonomes avec zipapp:: 
* Le format d'archive d'application Zip Python:: 

Création d'applications autonomes avec zipapp

* Mises en garde:: 

Environnement d'exécution Python

* sys: sys --- System-specific parameters and functions. System-specific parameters and functions
* sys.monitoring: sys monitoring --- Execution event monitoring. Execution event monitoring
* sysconfig: sysconfig --- Provide access to Python's configuration information. Provide access to Python's configuration information
* builtins: builtins --- Built-in objects. Built-in objects
* __main__: __main__ --- Top-level code environment. Top-level code environment
* warnings: warnings --- Warning control. Warning control
* dataclasses: dataclasses --- Data Classes. Data Classes
* contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with:: 
* abc: abc --- Abstract Base Classes. Abstract Base Classes
* atexit: atexit --- Exit handlers. Exit handlers
* traceback: traceback --- Print or retrieve a stack traceback. Print or retrieve a stack traceback
* __future__: __future__ --- Future statement definitions. Future statement definitions
* gc: gc --- Garbage Collector interface. Garbage Collector interface
* inspect: inspect --- Inspect live objects. Inspect live objects
* site: site --- Site-specific configuration hook. Site-specific configuration hook

sys.monitoring --- Execution event monitoring

* Tool identifiers:: 
* Events:: 
* Turning events on and off:: 
* Registering callback functions:: 

Tool identifiers

* Registering and using tools:: 

Events

* Local events:: 
* Ancillary events:: 
* Other events:: 
* The STOP_ITERATION event:: 

Turning events on and off

* Setting events globally:: 
* Per code object events:: 
* Disabling events:: 

Registering callback functions

* Callback function arguments:: 

sysconfig --- Provide access to Python's configuration information

* Configuration variables:: 
* Installation paths:: 
* User scheme:: 
* Home scheme:: 
* Prefix scheme:: 
* Installation path functions:: 
* Autres fonctions: Autres fonctions<3>. 
* Using sysconfig as a script:: 

User scheme

* posix_user:: 
* nt_user:: 
* osx_framework_user:: 

Home scheme

* posix_home:: 

Prefix scheme

* posix_prefix:: 
* nt:: 

__main__ --- Top-level code environment

* __name__ == '__main__':: 
* Le fichier __main__.py dans les paquets Python: Le fichier __main__ py dans les paquets Python. 
* import __main__:: 

__name__ == '__main__'

* Qu'est-ce que l'« environnement d'exécution principal » ?:: 
* Utilisation idiomatique:: 
* Considérations liées à l'empaquetage:: 

Le fichier __main__.py dans les paquets Python

* Utilisation idiomatique: Utilisation idiomatique<2>. 

warnings --- Warning control

* Catégories d'avertissement:: 
* Le filtre des avertissements:: 
* Suppression temporaire des avertissements:: 
* Tester les avertissements:: 
* Mise à jour du code pour les nouvelles versions des dépendances:: 
* Fonctions disponibles:: 
* Gestionnaires de contexte disponibles:: 

Le filtre des avertissements

* Repeated Warning Suppression Criteria:: 
* Rédaction de filtres d'avertissement:: 
* Filtre d'avertissement par défaut:: 
* Outrepasser le filtre par défaut:: 

dataclasses --- Data Classes

* Classe de données: Classe de données<2>. 
* Post-initialisation:: 
* Variables de classe:: 
* Variables d'initialisation:: 
* Instances figées:: 
* Héritage: Héritage<2>. 
* Re-ordering of keyword-only parameters in __init__(): Re-ordering of keyword-only parameters in __init__. 
* Fabriques de valeurs par défaut:: 
* Valeurs par défaut mutables:: 
* Descriptor-typed fields:: 

contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with

* Utilitaires:: 
* Exemples et Recettes:: 
* Gestionnaires de contexte à usage unique@comma{} réutilisables et réentrants: Gestionnaires de contexte à usage unique réutilisables et réentrants. 

Exemples et Recettes

* Gérer un nombre variable de gestionnaires de contexte:: 
* Attraper des exceptions depuis les méthodes __enter__:: 
* Nettoyer dans une méthode __enter__:: 
* Remplacer un try-finally avec une option variable:: 
* Utiliser un gestionnaire de contexte en tant que décorateur de fonction:: 

Gestionnaires de contexte à usage unique, réutilisables et réentrants

* Gestionnaires de contexte réentrants:: 
* Gestionnaires de contexte réutilisables:: 

atexit --- Exit handlers

* Exemple avec atexit:: 

traceback --- Print or retrieve a stack traceback

* Fonctions de niveau module: Fonctions de niveau module<2>. 
* TracebackException Objects:: 
* StackSummary Objects:: 
* FrameSummary Objects:: 
* Examples of Using the Module-Level Functions:: 
* Examples of Using TracebackException:: 

__future__ --- Future statement definitions

* Contenu du module: Contenu du module<5>. 

inspect --- Inspect live objects

* Types et membres:: 
* Récupération du code source:: 
* Introspection des appelables avec l'objet Signature:: 
* Classes et fonctions: Classes et fonctions<2>. 
* La pile d'interpréteur:: 
* Recherche dynamique d'attributs:: 
* Current State of Generators@comma{} Coroutines@comma{} and Asynchronous Generators: Current State of Generators Coroutines and Asynchronous Generators. 
* Bit d'option des objets code:: 
* Buffer flags:: 
* Interface en ligne de commande: Interface en ligne de commande<9>. 

site --- Site-specific configuration hook

* sitecustomize:: 
* usercustomize:: 
* Readline configuration:: 
* Module contents: Module contents<3>. 
* Interface en ligne de commande: Interface en ligne de commande<10>. 

Interpréteurs Python personnalisés

* code: code --- Interpreter base classes. Interpreter base classes
* codeop: codeop --- Compile Python code. Compile Python code

code --- Interpreter base classes

* Interactive Interpreter Objects:: 
* Interactive Console Objects:: 

Importer des modules

* zipimport: zipimport --- Import modules from Zip archives. Import modules from Zip archives
* pkgutil: pkgutil --- Package extension utility. Package extension utility
* modulefinder: modulefinder --- Find modules used by a script. Find modules used by a script
* runpy: runpy --- Locating and executing Python modules. Locating and executing Python modules
* importlib: importlib --- The implementation of import. The implementation of import
* importlib.resources: importlib resources -- Package resource reading opening and access. Package resource reading, opening and access
* importlib.resources.abc: importlib resources abc -- Abstract base classes for resources. Abstract base classes for resources
* importlib.metadata: importlib metadata -- Accessing package metadata. Accessing package metadata
* The initialization of the sys.path module search path: The initialization of the sys path module search path. 

zipimport --- Import modules from Zip archives

* Objets zimporter:: 
* Exemples: Exemples<32>. 

modulefinder --- Find modules used by a script

* Exemples d'utilisation de la classe ModuleFinder:: 

importlib --- The implementation of import

* Introduction: Introduction<11>. 
* Fonctions: Fonctions<12>. 
* importlib.abc: importlib abc -- Abstract base classes related to import. Abstract base classes related to import
* importlib.machinery: importlib machinery -- Importers and path hooks. Importers and path hooks
* importlib.util: importlib util -- Utility code for importers. Utility code for importers
* Exemples: Exemples<33>. 

Exemples

* Importing programmatically:: 
* Checking if a module can be imported:: 
* Importing a source file directly:: 
* Implementing lazy imports:: 
* Setting up an importer:: 
* Approximating importlib.import_module(): Approximating importlib import_module. 

importlib.resources -- Package resource reading, opening and access

* API par fonction:: 

importlib.metadata -- Accessing package metadata

* Aperçu: Aperçu<3>. 
* API par fonction: API par fonction<2>. 
* Distributions:: 
* Distribution Discovery:: 
* Extending the search algorithm:: 

API par fonction

* Entry points:: 
* Distribution metadata:: 
* Distribution versions:: 
* Distribution files:: 
* Distribution requirements:: 
* Mapping import to distribution packages:: 

Extending the search algorithm

* Exemple: Exemple<15>. 

The initialization of the sys.path module search path

* Environnements virtuels: Environnements virtuels<2>. 
* _pth files:: 
* Embedded Python:: 

Services du Langage Python

* ast: ast --- Abstract Syntax Trees. Abstract Syntax Trees
* symtable: symtable --- Access to the compiler's symbol tables. Access to the compiler's symbol tables
* token: token --- Constants used with Python parse trees. Constants used with Python parse trees
* keyword: keyword --- Testing for Python keywords. Testing for Python keywords
* tokenize: tokenize --- Tokenizer for Python source. Tokenizer for Python source
* tabnanny: tabnanny --- Detection of ambiguous indentation. Detection of ambiguous indentation
* pyclbr: pyclbr --- Python module browser support. Python module browser support
* py_compile: py_compile --- Compile Python source files. Compile Python source files
* compileall: compileall --- Byte-compile Python libraries. Byte-compile Python libraries
* dis: dis --- Disassembler for Python bytecode. Disassembler for Python bytecode
* pickletools: pickletools --- Tools for pickle developers. Tools for pickle developers

ast --- Abstract Syntax Trees

* Grammaire abstraite:: 
* Classes de nœuds:: 
* Outils du module ast:: 
* Options du compilateur:: 
* Utilisation en ligne de commande: Utilisation en ligne de commande<4>. 

Classes de nœuds

* Root nodes:: 
* Littéraux: Littéraux<3>. 
* Variables:: 
* Expressions: Expressions<2>. 
* Instructions: Instructions<2>. 
* Contrôle de l'exécution:: 
* Pattern matching:: 
* Type parameters:: 
* Définition de fonctions et de classes:: 
* async et await:: 

Expressions

* Indiçage:: 
* Compréhensions:: 

Instructions

* Importations:: 

symtable --- Access to the compiler's symbol tables

* Generating Symbol Tables:: 
* Examining Symbol Tables:: 
* Utilisation en ligne de commande.: Utilisation en ligne de commande<5>. 

tokenize --- Tokenizer for Python source

* Analyse Lexicale:: 
* Utilisation en ligne de commande.: Utilisation en ligne de commande<6>. 
* Exemples: Exemples<34>. 

pyclbr --- Python module browser support

* Objets fonctions:: 
* Objets classes: Objets classes<2>. 

py_compile --- Compile Python source files

* Interface en ligne de commande: Interface en ligne de commande<11>. 

compileall --- Byte-compile Python libraries

* Utilisation en ligne de commande: Utilisation en ligne de commande<7>. 
* Fonctions publiques:: 

dis --- Disassembler for Python bytecode

* Command-line interface: Command-line interface<2>. 
* Analyse du code intermédiaire:: 
* Analyse de fonctions:: 
* Les instructions du code intermédiaire en Python:: 
* Opcode collections:: 

pickletools --- Tools for pickle developers

* Utilisation de la ligne de commande: Utilisation de la ligne de commande<2>. 
* Programmatic Interface: Programmatic Interface<2>. 

Utilisation de la ligne de commande

* Options de la ligne de commande: Options de la ligne de commande<6>. 

Services spécifiques à MS Windows

* msvcrt: msvcrt --- Useful routines from the MS VC++ runtime. Useful routines from the MS VC++ runtime
* winreg: winreg --- Windows registry access. Windows registry access
* winsound: winsound --- Sound-playing interface for Windows. Sound-playing interface for Windows

msvcrt --- Useful routines from the MS VC++ runtime

* Opérations sur les fichiers:: 
* Entrées-sorties sur un terminal:: 
* Autres fonctions: Autres fonctions<4>. 

winreg --- Windows registry access

* Fonctions: Fonctions<13>. 
* Constantes: Constantes<10>. 
* Registry Handle Objects:: 

Constantes

* HKEY_* Constants:: 
* Access Rights:: 
* Value Types:: 

Access Rights

* 64-bit Specific:: 

Services spécifiques à Unix

* posix: posix --- The most common POSIX system calls. The most common POSIX system calls
* pwd: pwd --- The password database. The password database
* grp: grp --- The group database. The group database
* termios: termios --- POSIX style tty control. POSIX style tty control
* tty: tty --- Terminal control functions. Terminal control functions
* pty: pty --- Pseudo-terminal utilities. Pseudo-terminal utilities
* fcntl: fcntl --- The fcntl and ioctl system calls. The fcntl and ioctl system calls
* resource: resource --- Resource usage information. Resource usage information
* syslog: syslog --- Unix syslog library routines. Unix syslog library routines

posix --- The most common POSIX system calls

* Prise en charge de gros fichiers:: 
* Contenu du Module:: 

termios --- POSIX style tty control

* Exemple: Exemple<16>. 

pty --- Pseudo-terminal utilities

* Exemple: Exemple<17>. 

resource --- Resource usage information

* Resource Limits:: 
* Resource Usage:: 

syslog --- Unix syslog library routines

* Exemples: Exemples<35>. 

Exemples

* Exemple simple:: 

Modules remplacés

* getopt: getopt --- C-style parser for command line options. C-style parser for command line options

Removed Modules

* aifc: aifc --- Read and write AIFF and AIFC files. Read and write AIFF and AIFC files
* asynchat: asynchat --- Asynchronous socket command/response handler. Asynchronous socket command/response handler
* asyncore: asyncore --- Asynchronous socket handler. Asynchronous socket handler
* audioop: audioop --- Manipulate raw audio data. Manipulate raw audio data
* cgi: cgi --- Common Gateway Interface support. Common Gateway Interface support
* cgitb: cgitb --- Traceback manager for CGI scripts. Traceback manager for CGI scripts
* chunk: chunk --- Read IFF chunked data. Read IFF chunked data
* crypt: crypt --- Function to check Unix passwords. Function to check Unix passwords
* distutils: distutils --- Building and installing Python modules. Building and installing Python modules
* imghdr: imghdr --- Determine the type of an image. Determine the type of an image
* imp: imp --- Access the import internals. Access the import internals
* mailcap: mailcap --- Mailcap file handling. Mailcap file handling
* msilib: msilib --- Read and write Microsoft Installer files. Read and write Microsoft Installer files
* nis: nis --- Interface to Sun’s NIS Yellow Pages. Interface to Sun’s NIS (Yellow Pages)
* nntplib: nntplib --- NNTP protocol client. NNTP protocol client
* ossaudiodev: ossaudiodev --- Access to OSS-compatible audio devices. Access to OSS-compatible audio devices
* pipes: pipes --- Interface to shell pipelines. Interface to shell pipelines
* smtpd: smtpd --- SMTP Server. SMTP Server
* sndhdr: sndhdr --- Determine type of sound file. Determine type of sound file
* spwd: spwd --- The shadow password database. The shadow password database
* sunau: sunau --- Read and write Sun AU files. Read and write Sun AU files
* telnetlib: telnetlib --- Telnet client. Telnet client
* uu: uu --- Encode and decode uuencode files. Encode and decode uuencode files
* xdrlib: xdrlib --- Encode and decode XDR data. Encode and decode XDR data

Extension et intégration de l'interpréteur Python

* Les outils tiers recommandés:: 
* Création d'extensions sans outils tiers:: 
* Intégrer l'interpréteur CPython dans une plus grande application:: 

Création d'extensions sans outils tiers

* Étendre Python en C ou C++:: 
* Tutoriel ; définir des types dans des extensions: Tutoriel définir des types dans des extensions. 
* Définir les types d'extension ; divers sujets: Définir les types d'extension divers sujets. 
* Construire des extensions C et C++:: 
* Construire des extensions C et C++ sur Windows:: 

Étendre Python en C ou C++

* Un exemple simple:: 
* Intermezzo ; les erreurs et les exceptions: Intermezzo les erreurs et les exceptions. 
* Retour vers l'exemple:: 
* La fonction d'initialisation et le tableau des méthodes du module:: 
* Compilation et liaison:: 
* Appeler des fonctions Python en C:: 
* Extraire des paramètres dans des fonctions d'extension:: 
* Paramètres nommés pour des fonctions d'extension:: 
* Créer des valeurs arbitraires:: 
* Compteurs de références:: 
* Écrire des extensions en C++:: 
* Fournir une API en langage C pour un module d'extension:: 

Compteurs de références

* Comptage de références en Python:: 
* Règles concernant la possession de références:: 
* Terrain dangereux:: 
* Pointeurs NULL:: 

Tutoriel : définir des types dans des extensions

* Les bases: Les bases<2>. 
* ajout de données et de méthodes à l'exemple basique:: 
* Contrôle précis sur les attributs de données:: 
* Prise en charge du ramasse-miettes cyclique:: 
* Sous-classement d'autres types:: 

Définir les types d'extension : divers sujets

* Finalisation et libération de mémoire:: 
* Présentation de l'objet:: 
* Gestion des attributs:: 
* Comparaison des objets:: 
* Gestion de protocoles abstraits:: 
* Prise en charge de la référence faible:: 
* Plus de suggestions:: 

Gestion des attributs

* Gestion des attributs génériques:: 
* Gestion des attributs de type spécifiques:: 

Construire des extensions C et C++

* Building C and C++ Extensions with setuptools:: 

Construire des extensions C et C++ sur Windows

* Une approche "recette de cuisine":: 
* Différences entre Unix et Windows:: 
* Utiliser les DLL en pratique:: 

Intégrer l'interpréteur CPython dans une plus grande application

* Intégrer Python dans une autre application:: 

Intégrer Python dans une autre application

* Intégration de très haut niveau:: 
* Au-delà de l'intégration de haut niveau ; survol: Au-delà de l'intégration de haut niveau survol. 
* Intégration pure:: 
* Étendre un Python intégré:: 
* Intégrer Python dans du C++:: 
* Compiler et Lier en environnement Unix ou similaire:: 

Manuel de référence de l'API Python/C

* Introduction: Introduction<12>. 
* Stabilité de l’API C:: 
* The Very High Level Layer:: 
* Reference Counting:: 
* Gestion des exceptions: Gestion des exceptions<2>. 
* Utilitaires: Utilitaires<2>. 
* Couche d'abstraction des objets:: 
* Couche des objets concrets:: 
* Initialization@comma{} Finalization@comma{} and Threads: Initialization Finalization and Threads. 
* Python Initialization Configuration:: 
* Memory Management:: 
* Implémentation d'objets:: 
* Version des API et ABI:: 
* Monitoring C API:: 
* Generating Execution Events:: 

Introduction

* Coding standards:: 
* Include Files:: 
* Useful macros:: 
* Objects@comma{} Types and Reference Counts: Objects Types and Reference Counts. 
* Exceptions: Exceptions<21>. 
* Embarquer Python: Embarquer Python<2>. 
* Debugging Builds:: 

Objects, Types and Reference Counts

* Compteurs de références: Compteurs de références<2>. 
* Types:: 

Compteurs de références

* Reference Count Details:: 

Stabilité de l’API C

* Unstable C API:: 
* ABI stable:: 
* Considérations relatives aux plateformes:: 
* Contenu de l’API restreinte:: 

ABI stable

* Limited C API:: 
* Stable ABI:: 
* Porté de l’API restreinte et performance:: 
* Inconvénients de l’API restreinte:: 

Gestion des exceptions

* Printing and clearing:: 
* Lever des exceptions:: 
* Issuing warnings:: 
* Querying the error indicator:: 
* Traitement des signaux: Traitement des signaux<2>. 
* Exception Classes:: 
* Objets exception:: 
* Objets exception Unicode:: 
* Contrôle de la récursion:: 
* Exceptions standards:: 
* Standard Warning Categories:: 

Utilitaires

* Operating System Utilities:: 
* System Functions:: 
* Process Control:: 
* Importer des modules: Importer des modules<2>. 
* Data marshalling support:: 
* Analyse des arguments et construction des valeurs:: 
* Conversion et formatage de chaînes:: 
* PyHash API:: 
* Réflexion:: 
* Codec registry and support functions:: 
* PyTime C API:: 
* Support for Perf Maps:: 

Analyse des arguments et construction des valeurs

* Analyse des arguments: Analyse des arguments<2>. 
* Construction des valeurs:: 

Analyse des arguments

* Chaînes et tampons:: 
* Les nombres: Les nombres<2>. 
* Autres objets:: 
* Fonction de l'API:: 

Codec registry and support functions

* Codec lookup API:: 
* Registry API for Unicode encoding error handlers:: 

PyTime C API

* Types: Types<2>. 
* Clock Functions:: 
* Raw Clock Functions:: 
* Conversion functions:: 

Couche d'abstraction des objets

* Protocole Objet:: 
* Call Protocol:: 
* Number Protocol:: 
* Sequence Protocol:: 
* Protocole de correspondance:: 
* Protocole d'itération:: 
* Protocole tampon:: 

Call Protocol

* The tp_call Protocol:: 
* The Vectorcall Protocol:: 
* Object Calling API:: 
* Call Support API:: 

The Vectorcall Protocol

* Contrôle de la récursion: Contrôle de la récursion<2>. 
* Vectorcall Support API:: 

Protocole tampon

* La structure buffer:: 
* Buffer request types:: 
* Complex arrays:: 
* Fonctions relatives aux tampons:: 

Buffer request types

* request-independent fields:: 
* readonly@comma{} format: readonly format. 
* shape@comma{} strides@comma{} suboffsets: shape strides suboffsets. 
* contiguity requests:: 
* compound requests:: 

Complex arrays

* NumPy-style; shape and strides: NumPy-style shape and strides. 
* PIL-style; shape@comma{} strides and suboffsets: PIL-style shape strides and suboffsets. 

Couche des objets concrets

* Objets fondamentaux:: 
* Objets numériques:: 
* Objets séquences:: 
* Objets conteneurs:: 
* Objets fonctions: Objets fonctions<2>. 
* Autres objets: Autres objets<2>. 

Objets fondamentaux

* Objets type: Objets type<2>. 
* L'objet None:: 

Objets type

* Creating Heap-Allocated Types:: 

Objets numériques

* Objets Integer:: 
* Les objets booléens:: 
* Floating-Point Objects:: 
* Objets représentant des nombres complexes:: 

Floating-Point Objects

* Pack and Unpack functions:: 

Pack and Unpack functions

* Pack functions:: 
* Unpack functions:: 

Objets représentant des nombres complexes

* Nombres complexes en tant que structures C:: 
* Nombres complexes en tant qu'objets Python:: 

Objets séquences

* Objets bytes: Objets bytes<2>. 
* Objets tableau d'octets:: 
* Objets Unicode et Codecs:: 
* Tuple Objects:: 
* Struct Sequence Objects:: 
* List Objects:: 

Objets tableau d'octets

* Macros de vérification de type:: 
* Fonctions directes sur l'API:: 
* Macros:: 

Objets Unicode et Codecs

* Objets Unicode:: 
* Built-in Codecs:: 
* Methods and Slot Functions:: 

Objets Unicode

* Type Unicode:: 
* Unicode Character Properties:: 
* Creating and accessing Unicode strings:: 
* Locale Encoding:: 
* File System Encoding:: 
* wchar_t Support:: 

Built-in Codecs

* Generic Codecs:: 
* UTF-8 Codecs:: 
* UTF-32 Codecs:: 
* UTF-16 Codecs:: 
* UTF-7 Codecs:: 
* Unicode-Escape Codecs:: 
* Raw-Unicode-Escape Codecs:: 
* Latin-1 Codecs:: 
* ASCII Codecs:: 
* Character Map Codecs:: 
* MBCS codecs for Windows:: 
* Methods & Slots:: 

Objets conteneurs

* Objets dictionnaires:: 
* Set Objects:: 

Objets fonctions

* Objets fonction:: 
* Instance Method Objects:: 
* Objets méthode: Objets méthode<2>. 
* Objets Cellules:: 
* Objets code: Objets code<2>. 
* Extra information:: 

Autres objets

* Objets fichiers:: 
* Module Objects:: 
* Itérateurs: Itérateurs<2>. 
* Les descripteurs:: 
* Slice Objects:: 
* Objets de type MemoryView:: 
* Objets à références faibles: Objets à références faibles<2>. 
* Capsules: Capsules<2>. 
* Objets décrivant les frames:: 
* Objets générateur:: 
* Objets coroutines: Objets coroutines<2>. 
* Context Variables Objects:: 
* Objets DateTime: Objets DateTime<2>. 
* Objects for Type Hinting:: 

Module Objects

* Initializing C modules:: 
* Module lookup:: 

Initializing C modules

* Single-phase initialization:: 
* Multi-phase initialization:: 
* Low-level module creation functions:: 
* Support functions:: 

Slice Objects

* Ellipsis Object:: 

Objets décrivant les frames

* Frame Locals Proxies:: 
* Internal Frames:: 

Initialization, Finalization, and Threads

* Before Python Initialization:: 
* Global configuration variables:: 
* Initializing and finalizing the interpreter:: 
* Process-wide parameters:: 
* Thread State and the Global Interpreter Lock:: 
* Sub-interpreter support:: 
* Asynchronous Notifications:: 
* Profiling and Tracing:: 
* Reference tracing:: 
* Support avancé du débogueur:: 
* Thread Local Storage Support:: 
* Primitives de synchronisation: Primitives de synchronisation<3>. 

Thread State and the Global Interpreter Lock

* Releasing the GIL from extension code:: 
* Non-Python created threads:: 
* Cautions about fork(): Cautions about fork. 
* High-level API:: 
* Low-level API:: 

Sub-interpreter support

* A Per-Interpreter GIL:: 
* Bugs and caveats:: 

Thread Local Storage Support

* Thread Specific Storage (TSS) API: Thread Specific Storage TSS API. 
* Thread Local Storage (TLS) API: Thread Local Storage TLS API. 

Thread Specific Storage (TSS) API

* Dynamic Allocation:: 
* Méthodes: Méthodes<2>. 

Primitives de synchronisation

* Python Critical Section API:: 

Python Initialization Configuration

* Example:: 
* PyWideStringList:: 
* PyStatus:: 
* PyPreConfig:: 
* Preinitialize Python with PyPreConfig:: 
* PyConfig:: 
* Initialization with PyConfig:: 
* Isolated Configuration:: 
* Python Configuration:: 
* Python Path Configuration:: 
* Py_GetArgcArgv(): Py_GetArgcArgv. 
* Multi-Phase Initialization Private Provisional API:: 

Memory Management

* Aperçu: Aperçu<4>. 
* Allocator Domains:: 
* Raw Memory Interface:: 
* Memory Interface:: 
* Object allocators:: 
* Default Memory Allocators:: 
* Customize Memory Allocators:: 
* Debug hooks on the Python memory allocators:: 
* The pymalloc allocator:: 
* The mimalloc allocator:: 
* tracemalloc C API:: 
* Exemples: Exemples<36>. 

The pymalloc allocator

* Customize pymalloc Arena Allocator:: 

Implémentation d'objets

* Allouer des objets dans le tas:: 
* Common Object Structures:: 
* Objets type: Objets type<3>. 
* Supporting Cyclic Garbage Collection:: 

Common Object Structures

* Base object types and macros:: 
* Implementing functions and methods:: 
* Accessing attributes of extension types:: 

Accessing attributes of extension types

* Member flags:: 
* Member types:: 
* Defining Getters and Setters:: 

Objets type

* Quick Reference:: 
* PyTypeObject Definition:: 
* PyObject Slots:: 
* PyVarObject Slots:: 
* PyTypeObject Slots:: 
* Static Types:: 
* Heap Types:: 
* Number Object Structures:: 
* Mapping Object Structures:: 
* Sequence Object Structures:: 
* Buffer Object Structures:: 
* Async Object Structures:: 
* Slot Type typedefs:: 
* Exemples: Exemples<37>. 

Quick Reference

* "tp slots":: 
* sub-slots:: 
* slot typedefs:: 

Supporting Cyclic Garbage Collection

* Controlling the Garbage Collector State:: 
* Querying Garbage Collector State:: 

Generating Execution Events

* Managing the Monitoring State:: 

Installation de modules Python

* Vocabulaire:: 
* Utilisation de base: Utilisation de base<2>. 
* Comment puis-je … ?:: 
* Les problèmes d'installation typiques:: 

Comment puis-je … ?

* ... Installer pip avec une version de Python antérieures à la 3.4 ?: Installer pip avec une version de Python antérieures à la 3 4 ?. 
* ... Installer des paquets juste pour l'utilisateur actuel ?: Installer des paquets juste pour l'utilisateur actuel ?. 
* ... Installer des paquets Python scientifiques ?: Installer des paquets Python scientifiques ?. 
* ... Travailler avec plusieurs versions de Python installés en parallèle ?: Travailler avec plusieurs versions de Python installés en parallèle ?. 

Les problèmes d'installation typiques

* Installer dans le Python du système sur Linux:: 
* Pip n'est pas installé:: 
* Installation d'extensions binaires:: 

Les HOWTOs de Python

* Portage des modules d'extension vers Python 3:: 
* Programmation Curses avec Python:: 
* Descriptor Guide:: 
* Debugging C API extensions and CPython Internals with GDB:: 
* Guide sur l'utilisation d'Enum:: 
* Guide pratique ; programmation fonctionnelle: Guide pratique programmation fonctionnelle. 
* Tutoriel sur la journalisation:: 
* Recettes pour la journalisation:: 
* Guide des expressions régulières:: 
* Guide pratique ; programmation avec les sockets: Guide pratique programmation avec les sockets. 
* Sorting Techniques:: 
* Guide Unicode:: 
* Guide pratique ; récupérer des ressources web en utilisant le module urllib: Guide pratique récupérer des ressources web en utilisant le module urllib. 
* Introduction au module ipaddress:: 
* Instrumenter CPython avec DTrace et SystemTap:: 
* Python support for the Linux perf profiler:: 
* Bonnes pratiques concernant les annotations:: 
* Isolating Extension Modules:: 
* timer file descriptor HOWTO:: 
* The Python 2.3 Method Resolution Order: The Python 2 3 Method Resolution Order. 
* Python experimental support for free threading:: 
* C API Extension Support for Free Threading:: 

Programmation Curses avec Python

* Qu'est-ce que curses ?:: 
* Lancement et arrêt une application curses:: 
* Fenêtres et tampons (pads en anglais): Fenêtres et tampons pads en anglais. 
* Affichage de texte:: 
* Entrées de l'utilisateur:: 
* Pour aller plus loin: Pour aller plus loin<2>. 

Qu'est-ce que curses ?

* Le module curses de Python:: 

Affichage de texte

* Attributs et couleurs:: 

Descriptor Guide

* Introduction: Introduction<13>. 
* Exemple complet pratique:: 
* Tutoriel technique:: 
* Équivalents en Python pur:: 

Introduction

* Un exemple simple ; un descripteur qui renvoie une constante: Un exemple simple un descripteur qui renvoie une constante. 
* Recherches dynamiques:: 
* Attributs gérés:: 
* Noms personnalisés:: 
* Réflexions finales:: 

Exemple complet pratique

* Classe « validateur »:: 
* Validateurs personnalisés:: 
* Application pratique:: 

Tutoriel technique

* Résumé:: 
* Définition et introduction:: 
* Protocole descripteur:: 
* Présentation de l'appel de descripteur:: 
* Appel depuis une instance:: 
* Appel depuis une classe:: 
* Appel depuis super:: 
* Résumé de la logique d'appel:: 
* Notification automatique des noms:: 
* Exemple d'ORM:: 

Équivalents en Python pur

* Propriétés:: 
* Fonctions et méthodes:: 
* Types de méthodes:: 
* Méthodes statiques:: 
* Méthodes de classe:: 
* Objets membres et __slots__:: 

Debugging C API extensions and CPython Internals with GDB

* Prerequisites:: 
* Using the Debug build and Development mode:: 
* Using the python-gdb extension:: 
* Use with GDB commands:: 

Prerequisites

* Setup with Python built from source:: 
* Setup for Python from a Linux distro:: 

Using the python-gdb extension

* Pretty-printers:: 
* py-list:: 
* py-up and py-down:: 
* py-bt:: 
* py-print:: 
* py-locals:: 

Guide sur l'utilisation d'Enum

* Accès par programme aux membres de l'énumération et à leurs attributs:: 
* Duplication des membres et des valeurs d'une énumération:: 
* Garantie de valeurs d'énumération uniques:: 
* Utilisation de valeurs automatiques:: 
* Itération: Itération<2>. 
* Comparaisons: Comparaisons<3>. 
* Membres et attributs autorisés des énumérations:: 
* Restrictions sur la dérivation d'énumérations:: 
* Dataclass support:: 
* Sérialisation:: 
* API fonctionnelle:: 
* Déclinaisons d'énumérations:: 
* When to use __new__() vs. __init__(): When to use __new__ vs __init__. 
* How are Enums and Flags different?:: 
* Enum Cookbook:: 
* Dérivations d'EnumType:: 

Déclinaisons d'énumérations

* IntEnum:: 
* StrEnum:: 
* IntFlag:: 
* Flag:: 
* Autres énumérations:: 

When to use __new__() vs. __init__()

* Approfondissements:: 

Approfondissements

* Noms de la forme __dunder__ disponibles: Noms de la forme __dunder__ disponibles<2>. 
* Noms de la forme _sunder_ disponibles: Noms de la forme _sunder_ disponibles<2>. 
* _Private__names:: 
* Types des membres d'une Enum:: 
* Création de membres mélangés avec d'autres types de données:: 
* Valeur booléenne des classes et membres Enum:: 
* Méthodes dans les classes Enum:: 
* Combinaisons de membres de Flag:: 
* Précisions sur Flag et IntFlag:: 

How are Enums and Flags different?

* Classes Enum:: 
* Flag Classes:: 
* Membres d'une Enum (les instances): Membres d'une Enum les instances. 
* Flag Members:: 

Enum Cookbook

* Omission de valeurs:: 
* Énumération ordonnée:: 
* Énumération sans doublon:: 
* MultiValueEnum:: 
* Planète:: 
* Intervalle de temps:: 

Omission de valeurs

* Utilisation d'auto:: 
* Utilisation d'object:: 
* Utilisation d'une chaîne de caractères descriptive:: 
* Using a custom __new__(): Using a custom __new__. 

Guide pratique : programmation fonctionnelle

* Introduction: Introduction<14>. 
* Itérateurs: Itérateurs<3>. 
* Expressions génératrices et compréhension de listes:: 
* Générateurs: Générateurs<2>. 
* Fonctions natives: Fonctions natives<3>. 
* Le module itertools:: 
* Le module functools:: 
* Expressions lambda et fonctions courtes:: 
* Historique des modifications et remerciements:: 
* Références: Références<3>. 

Introduction

* Preuves formelles:: 
* Modularité:: 
* Facilité de débogage et de test:: 
* Composabilité:: 

Itérateurs

* Types de données itérables:: 

Générateurs

* Transmettre des valeurs au générateur:: 

Le module itertools

* Créer de nouveaux itérateurs:: 
* Appliquer des fonctions au contenu des itérateurs:: 
* Sélectionner des éléments:: 
* Fonctions combinatoires:: 
* Grouper les éléments:: 

Le module functools

* Le module operator:: 

Références

* Général:: 
* Spécifique à Python:: 
* Documentation Python:: 

Tutoriel sur la journalisation

* Les bases de l'utilisation du module logging:: 
* Usage avancé de Logging:: 
* Niveaux de journalisation: Niveaux de journalisation<2>. 
* Gestionnaires utiles:: 
* Exceptions levées par la journalisation:: 
* Utilisation d'objets arbitraires comme messages:: 
* Optimisation:: 
* Autres ressources: Autres ressources<2>. 

Les bases de l'utilisation du module logging

* Quand utiliser logging:: 
* Un exemple simple: Un exemple simple<2>. 
* Enregistrer les évènements dans un fichier:: 
* Journalisation de données variables:: 
* Modifier le format du message affiché:: 
* Afficher l'horodatage dans les messages:: 
* Étapes suivantes:: 

Usage avancé de Logging

* Flux du processus de journalisation:: 
* Loggers:: 
* Handlers:: 
* Formatters:: 
* Configuration de logging:: 
* Comportement par défaut (si aucune configuration n'est fournie): Comportement par défaut si aucune configuration n'est fournie. 
* Configuration de la journalisation pour une bibliothèque:: 

Niveaux de journalisation

* Niveaux personnalisés:: 

Recettes pour la journalisation

* Journalisation dans plusieurs modules:: 
* Journalisation avec des fils d’exécution multiples:: 
* Plusieurs gestionnaires et formateurs:: 
* Journalisation vers plusieurs destinations:: 
* Personnalisation du niveau de journalisation:: 
* Exemple d’un serveur de configuration:: 
* Utilisation de gestionnaires bloquants:: 
* Envoi et réception d’événements de journalisation à travers le réseau:: 
* Ajout d’informations contextuelles dans la journalisation:: 
* Use of contextvars:: 
* Ajout d'informations contextuelles dans la journalisation:: 
* Journalisation vers un fichier unique à partir de plusieurs processus:: 
* Utilisation du roulement de fichiers:: 
* Utilisation d’autres styles de formatage:: 
* Personnalisation de LogRecord:: 
* Subclassing QueueHandler and QueueListener- a ZeroMQ example:: 
* Subclassing QueueHandler and QueueListener- a pynng example:: 
* Exemple de configuration basée sur un dictionnaire:: 
* Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux:: 
* Exemple plus élaboré avec traitement en parallèle:: 
* Insertion d’une BOM dans les messages envoyés à un SysLogHandler:: 
* Journalisation structurée:: 
* Personnalisation des gestionnaires avec dictConfig(): Personnalisation des gestionnaires avec dictConfig. 
* Using particular formatting styles throughout your application:: 
* Configuring filters with dictConfig(): Configuring filters with dictConfig. 
* Customized exception formatting:: 
* Speaking logging messages:: 
* Buffering logging messages and outputting them conditionally:: 
* Sending logging messages to email@comma{} with buffering: Sending logging messages to email with buffering. 
* Formatting times using UTC (GMT) via configuration: Formatting times using UTC GMT via configuration. 
* Using a context manager for selective logging:: 
* A CLI application starter template:: 
* A Qt GUI for logging:: 
* Logging to syslog with RFC5424 support:: 
* How to treat a logger like an output stream:: 
* Patterns to avoid:: 
* Autres ressources: Autres ressources<3>. 

Envoi et réception d’événements de journalisation à travers le réseau

* Journalisation en production à l’aide d’un connecteur en écoute sur le réseau:: 

Ajout d’informations contextuelles dans la journalisation

* Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles:: 
* Utilisation de filtres pour transmettre des informations contextuelles:: 

Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles

* Utilisation d’objets autres que les dictionnaires pour passer des informations contextuelles:: 

Journalisation vers un fichier unique à partir de plusieurs processus

* Utilisation de concurrent.futures.ProcessPoolExecutor: Utilisation de concurrent futures ProcessPoolExecutor. 
* Déploiement d’applications Web avec Gunicorn et uWSGI:: 

Subclassing QueueHandler and QueueListener- a ZeroMQ example

* Subclass QueueHandler:: 
* Subclass QueueListener:: 

Subclassing QueueHandler and QueueListener- a pynng example

* Subclass QueueListener: Subclass QueueListener<2>. 
* Subclass QueueHandler: Subclass QueueHandler<2>. 

Using particular formatting styles throughout your application

* Using LogRecord factories:: 
* Using custom message objects:: 

Patterns to avoid

* Opening the same log file multiple times:: 
* Using loggers as attributes in a class or passing them as parameters:: 
* Adding handlers other than NullHandler to a logger in a library:: 
* Creating a lot of loggers:: 

Guide des expressions régulières

* Introduction: Introduction<15>. 
* Motifs simples:: 
* Utilisation des expressions régulières:: 
* Des motifs plus puissants:: 
* Modification de chaînes:: 
* Problèmes classiques:: 
* Vos commentaires:: 

Motifs simples

* Correspondance de caractères:: 
* Répétitions:: 

Utilisation des expressions régulières

* Compilation des expressions régulières:: 
* La maudite barre oblique inverse:: 
* Recherche de correspondances:: 
* Fonctions de niveau module: Fonctions de niveau module<3>. 
* Options de compilation:: 

Des motifs plus puissants

* Plus de métacaractères:: 
* Regroupement:: 
* Groupes non de capture et groupes nommés:: 
* Assertions prédictives:: 

Modification de chaînes

* Découpage de chaînes:: 
* Recherche et substitution: Recherche et substitution<2>. 

Problèmes classiques

* Utilisez les méthodes du type string:: 
* match() contre search(): match contre search. 
* Glouton contre non-glouton:: 
* Utilisez re.VERBOSE: Utilisez re VERBOSE. 

Guide pratique : programmation avec les sockets

* Connecteurs (sockets): Connecteurs sockets. 
* Création d'un connecteur:: 
* Utilisation d'un connecteur:: 
* Déconnexion:: 
* Connecteurs non bloquants:: 

Connecteurs (sockets)

* Historique:: 

Création d'un connecteur

* IPC (Communication Entre Processus): IPC Communication Entre Processus. 

Utilisation d'un connecteur

* Données binaires:: 

Déconnexion

* Quand les connecteurs meurent:: 

Sorting Techniques

* Les bases du tri:: 
* Fonctions clef:: 
* Operator Module Functions and Partial Function Evaluation:: 
* Ascendant et descendant:: 
* Stabilité des tris et tris complexes:: 
* Decorate-Sort-Undecorate:: 
* Comparison Functions:: 
* Et n'oublions pas:: 
* Partial Sorts:: 

Guide Unicode

* Introduction à Unicode:: 
* Prise en charge Unicode de Python:: 
* Lecture et écriture de données Unicode:: 
* Remerciements: Remerciements<10>. 

Introduction à Unicode

* Définitions:: 
* Encodages:: 
* Références: Références<4>. 

Prise en charge Unicode de Python

* Le type String:: 
* Conversion en octets:: 
* Littéraux Unicode dans le code source Python:: 
* Propriétés Unicode:: 
* Comparaison de chaînes de caractères:: 
* Expressions régulières Unicode:: 
* Références: Références<5>. 

Lecture et écriture de données Unicode

* Noms de fichiers Unicode:: 
* Conseils pour écrire des programmes compatibles Unicode:: 
* Références: Références<6>. 

Conseils pour écrire des programmes compatibles Unicode

* Conversion entre les encodages de fichiers:: 
* Fichiers dans un encodage inconnu:: 

Guide pratique : récupérer des ressources web en utilisant le module urllib

* Introduction: Introduction<16>. 
* Fetching URLs:: 
* Gestion des exceptions: Gestion des exceptions<3>. 
* info and geturl:: 
* Openers and Handlers:: 
* Basic Authentication:: 
* Proxies:: 
* Sockets and Layers:: 
* Notes: Notes<3>. 

Fetching URLs

* Data:: 
* Headers:: 

Gestion des exceptions

* URLError:: 
* HTTPError:: 
* Wrapping it Up:: 

HTTPError

* Error Codes:: 

Wrapping it Up

* Number 1:: 
* Number 2:: 

Introduction au module ipaddress

* Créer un objet Adresse/Réseau/Interface:: 
* Inspecter les objets Address/Network/Interface:: 
* Réseaux en tant que listes d'adresses:: 
* Comparaisons: Comparaisons<4>. 
* Utiliser des adresse IP avec d'autre modules:: 
* Obtenir plus de détails lors de l'échec de la création de l'instance:: 

Créer un objet Adresse/Réseau/Interface

* Note sur les versions d'IP:: 
* Adresses IP des hôtes:: 
* Définir des réseaux:: 
* Interfaces des hôtes:: 

Instrumenter CPython avec DTrace et SystemTap

* Activer les marqueurs statiques:: 
* Sondes DTrace statiques:: 
* Marqueurs statiques SystemTap:: 
* Marqueurs statiques disponibles:: 
* Tapsets de SystemTap:: 
* Exemples: Exemples<38>. 

Python support for the Linux perf profiler

* How to enable perf profiling support:: 
* How to obtain the best results:: 
* How to work without frame pointers:: 

Bonnes pratiques concernant les annotations

* Accès au dictionnaire des annotations d'un objet dans Python 3.10 et plus récent: Accès au dictionnaire des annotations d'un objet dans Python 3 10 et plus récent. 
* Accès au dictionnaire des annotations d'un objet en Python 3.9 et antérieur: Accès au dictionnaire des annotations d'un objet en Python 3 9 et antérieur. 
* Conversion manuelle des annotations contenues dans une chaîne de caractères:: 
* Bonnes pratiques pour __annotations__ dans toutes les versions de Python:: 
* Les curiosités concernant __annotations__:: 

Isolating Extension Modules

* Who should read this:: 
* Background: Background<2>. 
* Making Modules Safe with Multiple Interpreters:: 
* Heap Types: Heap Types<2>. 
* Open Issues:: 

Background

* Enter Per-Module State:: 
* Isolated Module Objects:: 
* Surprising Edge Cases:: 

Making Modules Safe with Multiple Interpreters

* Managing Global State:: 
* Managing Per-Module State:: 
* Opt-Out; Limiting to One Module Object per Process: Opt-Out Limiting to One Module Object per Process. 
* Module State Access from Functions:: 

Heap Types

* Changing Static Types to Heap Types:: 
* Defining Heap Types:: 
* Garbage-Collection Protocol:: 
* Module State Access from Classes:: 
* Module State Access from Regular Methods:: 
* Module State Access from Slot Methods@comma{} Getters and Setters: Module State Access from Slot Methods Getters and Setters. 
* Lifetime of the Module State:: 

Garbage-Collection Protocol

* tp_traverse in Python 3.8 and lower: tp_traverse in Python 3 8 and lower. 
* Delegating tp_traverse:: 
* Defining tp_dealloc:: 
* Not overriding tp_free:: 
* Avoiding PyObject_New:: 

Open Issues

* Per-Class Scope:: 
* Lossless Conversion to Heap Types:: 

timer file descriptor HOWTO

* Exemples: Exemples<39>. 

The Python 2.3 Method Resolution Order

* The beginning:: 
* The C3 Method Resolution Order:: 
* Exemples: Exemples<40>. 
* Bad Method Resolution Orders:: 
* The end:: 
* Resources:: 

Python experimental support for free threading

* Installation:: 
* Identifying free-threaded Python:: 
* The global interpreter lock in free-threaded Python:: 
* Thread safety:: 
* Known limitations:: 

Known limitations

* Immortalization:: 
* Objets cadres: Objets cadres<2>. 
* Itérateurs: Itérateurs<4>. 
* Single-threaded performance:: 

C API Extension Support for Free Threading

* Identifying the Free-Threaded Build in C:: 
* Module Initialization:: 
* General API Guidelines:: 
* Borrowed References:: 
* Memory Allocation APIs:: 
* Thread State and GIL APIs:: 
* Protecting Internal Extension State:: 
* Building Extensions for the Free-Threaded Build:: 

Module Initialization

* Multi-Phase Initialization:: 
* Single-Phase Initialization:: 

General API Guidelines

* Container Thread Safety:: 

Container Thread Safety

* PyDict_Next:: 

Building Extensions for the Free-Threaded Build

* Limited C API and Stable ABI:: 
* Windows: Windows<76>. 

Questions fréquemment posées sur Python

* FAQ générale sur Python:: 
* FAQ de programmation:: 
* FAQ sur l'histoire et la conception:: 
* FAQ sur la bibliothèque et les extensions:: 
* FAQ extension/intégration:: 
* FAQ ; Python et Windows: FAQ Python et Windows. 
* FAQ interface graphique:: 
* FAQ "Pourquoi Python est installé sur mon ordinateur ?":: 

FAQ générale sur Python

* Informations générales:: 
* Python c'est le monde réel:: 

Informations générales

* Qu'est-ce que Python ?:: 
* Qu'est ce que la Python Software Foundation ?:: 
* Existe-t-il des restrictions liées à la propriété intellectuelle quant à l'utilisation de Python ?:: 
* Pourquoi Python a été créé ?:: 
* Pour quoi Python est-il fait ?:: 
* Comment fonctionne le numérotage des versions de Python ?:: 
* Comment obtenir une copie du code source de Python ?:: 
* Comment obtenir la documentation de Python ?:: 
* Je n'ai jamais programmé avant. Existe-t-il un tutoriel Python ?: Je n'ai jamais programmé avant Existe-t-il un tutoriel Python ?. 
* Y a-t-il un forum ou une liste de diffusion dédié à Python ?:: 
* Comment obtenir une version bêta test de Python ?:: 
* Comment soumettre un rapport de bogues ou un correctif pour Python ?:: 
* Existe-t-il des articles publiés au sujet de Python auxquels je peux me référer ?:: 
* Y a-t-il des livres au sujet de Python ?:: 
* Où www.python.org est-il localisé dans le monde ?: Où www python org est-il localisé dans le monde ?. 
* Pourquoi le nom Python ?:: 
* Dois-je aimer "Monty Python's Flying Circus" ?:: 

Python c'est le monde réel

* Quel est le niveau de stabilité de Python ?:: 
* Combien de personnes utilisent Python ?:: 
* Y a-t-il un nombre de projets significatif réalisés en Python ?:: 
* Quelles sont les nouveautés en développement attendues pour Python ?:: 
* Est-il raisonnable de proposer des changements incompatibles dans Python ?:: 
* Existe-t-il un meilleur langage de programmation pour les programmeurs débutants ?:: 

FAQ de programmation

* Questions générales:: 
* Fondamentaux:: 
* Nombres et chaînes de caractères:: 
* Performances: Performances<4>. 
* Séquences (n-uplets / listes): Séquences n-uplets / listes. 
* Objets:: 
* Modules: Modules<5>. 

Questions générales

* Existe-t-il un débogueur de code source avec points d'arrêts@comma{} exécution pas-à-pas@comma{} etc. ?: Existe-t-il un débogueur de code source avec points d'arrêts exécution pas-à-pas etc ?. 
* Existe-t-il des outils pour aider à trouver des bogues ou faire de l'analyse statique de code ?:: 
* Comment créer un binaire autonome à partir d'un script Python ?:: 
* Existe-t-il des normes de développement ou un guide de style pour écrire des programmes Python ?:: 

Fondamentaux

* Pourquoi une UnboundLocalError est levée alors qu'une variable a une valeur ?:: 
* Quelles sont les règles pour les variables locales et globales en Python ?:: 
* Pourquoi des expressions lambda définies dans une boucle avec des valeurs différentes retournent-elles le même résultat ?:: 
* Comment partager des variables globales entre modules ?:: 
* Quelles sont les « bonnes pratiques » pour utiliser import dans un module ?:: 
* Pourquoi les arguments par défaut sont-ils partagés entre les objets ?:: 
* Comment passer des paramètres optionnels ou nommés d'une fonction à l'autre ?:: 
* Quelle est la différence entre les arguments et les paramètres ?:: 
* Pourquoi modifier la liste 'y' modifie aussi la liste 'x' ?:: 
* Comment écrire une fonction qui modifie ses paramètres ? (passage par référence): Comment écrire une fonction qui modifie ses paramètres ? passage par référence. 
* Comment construire une fonction d'ordre supérieur en Python ?:: 
* Comment copier un objet en Python ?:: 
* Comment récupérer les méthodes ou les attributs d'un objet ?:: 
* Comment un code peut-il obtenir le nom d'un objet ?:: 
* Qu'en est-il de la précédence de l'opérateur virgule ?:: 
* Existe-t-il un équivalent à l'opérateur ternaire « ?; » du C ?: Existe-t-il un équivalent à l'opérateur ternaire « ? » du C ?. 
* Est-il possible d'écrire des programmes obscurcis (obfuscated) d'une ligne en Python ?: Est-il possible d'écrire des programmes obscurcis obfuscated d'une ligne en Python ?. 
* Que signifie la barre oblique (/) dans la liste des paramètres d'une fonction ?: Que signifie la barre oblique / dans la liste des paramètres d'une fonction ?. 

Nombres et chaînes de caractères

* Comment écrire des entiers hexadécimaux ou octaux ?:: 
* Pourquoi -22 // 10 donne-t-il -3 ?:: 
* Pourquoi ai-je une erreur de syntaxe en essayant de lire un attribut d'un entier littéral ?:: 
* Comment convertir une chaîne de caractères en nombre ?:: 
* Comment convertir un nombre en chaîne de caractères ?:: 
* Comment modifier une chaîne de caractères « sur place » ?:: 
* Comment utiliser des chaînes de caractères pour appeler des fonctions/méthodes ?:: 
* Existe-t-il un équivalent à la fonction chomp() de Perl@comma{} pour retirer les caractères de fin de ligne d'une chaîne de caractères ?: Existe-t-il un équivalent à la fonction chomp de Perl pour retirer les caractères de fin de ligne d'une chaîne de caractères ?. 
* Existe-t-il un équivalent à scanf() ou sscanf() ?: Existe-t-il un équivalent à scanf ou sscanf ?. 
* Que signifient les erreurs UnicodeDecodeError ou UnicodeEncodeError ?:: 
* Can I end a raw string with an odd number of backslashes?:: 

Performances

* Mon programme est trop lent. Comment l'accélérer ?: Mon programme est trop lent Comment l'accélérer ?. 
* Quelle est la manière la plus efficace de concaténer un grand nombre de chaînes de caractères ?:: 

Séquences (n-uplets / listes)

* Comment convertir les listes en n-uplets et inversement ?:: 
* Qu'est-ce qu'un indice négatif ?:: 
* Comment itérer à rebours sur une séquence ?:: 
* Comment retirer les doublons d'une liste ?:: 
* Comment retirer les doublons d'une liste:: 
* Comment construire un tableau en Python ?:: 
* Comment créer une liste à plusieurs dimensions ?:: 
* Comment appliquer une méthode ou une fonction à une séquence d'objets ?:: 
* Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?:: 
* Je souhaite faire un classement compliqué ; peut-on faire une transformation de Schwartz en Python ?: Je souhaite faire un classement compliqué peut-on faire une transformation de Schwartz en Python ?. 
* Comment ordonner une liste en fonction des valeurs d'une autre liste ?:: 

Objets

* Qu'est-ce qu'une classe ?:: 
* Qu'est-ce qu'une méthode ?:: 
* Qu'est-ce que self ?:: 
* Comment vérifier si un objet est une instance d'une classe donnée ou d'une sous-classe de celle-ci ?:: 
* Qu'est-ce que la délégation ?:: 
* Comment appeler une méthode définie dans une classe mère depuis une classe dérivée qui la surcharge ?:: 
* Comment organiser un code pour permettre de changer la classe mère plus facilement ?:: 
* Comment créer des données statiques de classe et des méthodes statiques de classe ?:: 
* Comment surcharger les constructeurs (ou méthodes) en Python ?: Comment surcharger les constructeurs ou méthodes en Python ?. 
* J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam.: J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam. 
* Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet.: Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet. 
* Comment obtenir toutes les instances d'une classe ?:: 
* Pourquoi le résultat de id() peut-il être le même pour deux objets différents ?: Pourquoi le résultat de id peut-il être le même pour deux objets différents ?. 
* Quand puis-je raisonnablement utiliser le test d'identité is ?:: 
* Comment définir dans une classe fille les attributs d'une instance immuable ?:: 
* Comment mettre en cache le résultat d'une méthode ?:: 

Modules

* Comment créer des fichiers .pyc ?: Comment créer des fichiers pyc ?. 
* Comment obtenir le nom du module actuel ?:: 
* Comment avoir des modules qui s'importent mutuellement ?:: 
* __import__('x.y.z') renvoie <module 'x'> ; comment accéder à z ?: __import__ 'x y z' renvoie <module 'x'> ; comment accéder à z ?. 
* Quand j'édite un module et que je le réimporte@comma{} je ne vois pas les changements. Pourquoi ?: Quand j'édite un module et que je le réimporte je ne vois pas les changements Pourquoi ?. 

FAQ sur l'histoire et la conception

* Pourquoi Python utilise-t-il l'indentation pour grouper les instructions ?:: 
* Pourquoi ai-je d'étranges résultats suite à de simples opérations arithmétiques ?:: 
* Pourquoi les calculs à virgules flottantes sont si imprécis ?:: 
* Pourquoi les chaînes de caractères Python sont-elles immuables ?:: 
* Pourquoi self doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?:: 
* Pourquoi ne puis-je pas utiliser d'assignation dans une expression ?:: 
* Pourquoi Python utilise des méthodes pour certaines fonctionnalités (ex ; list.index()) mais des fonctions pour d'autres (ex ; len(list)) ?: Pourquoi Python utilise des méthodes pour certaines fonctionnalités ex list index mais des fonctions pour d'autres ex len list ?. 
* Pourquoi join() est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?: Pourquoi join est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?. 
* À quel point les exceptions sont-elles rapides ?:: 
* Pourquoi n'y a-t-il pas une instruction switch ou une structure similaire à switch / case en Python ?:: 
* Est-il possible d'émuler des fils d'exécution dans l'interpréteur plutôt que se baser sur les implémentations spécifiques aux systèmes d'exploitation ?:: 
* Pourquoi les expressions lambda ne peuvent pas contenir d'instructions ?:: 
* Python peut-il être compilé en code machine@comma{} en C ou dans un autre langage ?: Python peut-il être compilé en code machine en C ou dans un autre langage ?. 
* Comment Python gère la mémoire ?:: 
* Pourquoi CPython n'utilise-t-il pas un modèle de ramasse-miettes plus traditionnel ?:: 
* Pourquoi toute la mémoire n'est pas libérée lorsque CPython s'arrête ?:: 
* Pourquoi les n-uplets et les list sont deux types de données séparés ?:: 
* Comment les listes sont-elles implémentées dans CPython ?:: 
* Comment les dictionnaires sont-ils implémentés dans CPython ?:: 
* Pourquoi les clés du dictionnaire sont immuables ?:: 
* Pourquoi list.sort() ne renvoie pas la liste triée ?: Pourquoi list sort ne renvoie pas la liste triée ?. 
* Comment spécifier une interface et appliquer une spécification d’interface en Python ?:: 
* Pourquoi n'y a-t-il pas de goto en Python ?:: 
* Pourquoi les chaînes de caractères brutes (r-strings) ne peuvent-elles pas se terminer par un backslash ?: Pourquoi les chaînes de caractères brutes r-strings ne peuvent-elles pas se terminer par un backslash ?. 
* Pourquoi la déclaration with pour les assignations d'attributs n'existe pas en Python ?:: 
* Pourquoi l'instruction with ne prend-elle pas en charge les générateurs ?:: 
* Pourquoi les deux-points sont-ils nécessaires pour les déclarations if/while/def/class ?:: 
* Pourquoi Python permet-il les virgules à la fin des listes et des n-uplets ?:: 

FAQ sur la bibliothèque et les extensions

* Questions générales sur la bibliothèque:: 
* Tâches fréquentes:: 
* Fils d'exécution: Fils d'exécution<4>. 
* Les entrées/sorties: Les entrées/sorties<2>. 
* Programmation réseau et Internet:: 
* Bases de données:: 
* Mathématiques et calcul numérique:: 

Questions générales sur la bibliothèque

* Comment trouver un module ou une application pour effectuer la tâche X ?:: 
* Où sont stockés les fichiers sources math.py@comma{} socket.py@comma{} regex.py@comma{} etc ?: Où sont stockés les fichiers sources math py socket py regex py etc ?. 
* Comment rendre un script Python exécutable sous Unix ?:: 
* Existe-t-il un module curses ou termcap en Python ?:: 
* Existe-t-il un équivalent à la fonction C onexit() en Python ?: Existe-t-il un équivalent à la fonction C onexit en Python ?. 
* Pourquoi mes gestionnaires de signaux ne fonctionnent-ils pas ?:: 

Tâches fréquentes

* Comment tester un programme ou un composant Python ?:: 
* Comment générer la documentation à partir des docstrings ?:: 
* Comment détecter qu'une touche est pressée ?:: 

Fils d'exécution

* Comment programmer avec des fils d'exécution ?:: 
* Aucun de mes fils ne semble s'exécuter ; pourquoi ?: Aucun de mes fils ne semble s'exécuter pourquoi ?. 
* Comment découper et répartir une tâche au sein d'un ensemble de fils d'exécutions ?:: 
* Quels types de mutations sur des variables globales sont compatibles avec les programmes à fils d'exécution multiples ? sécurisé ?:: 
* Pourquoi ne pas se débarrasser du verrou global de l'interpréteur ?:: 

Les entrées/sorties

* Comment supprimer un fichier ? (et autres questions sur les fichiers…): Comment supprimer un fichier ? et autres questions sur les fichiers…. 
* Comment copier un fichier ?:: 
* Comment lire (ou écrire) des données binaires ?: Comment lire ou écrire des données binaires ?. 
* Il me semble impossible d'utiliser os.read() sur un tube créé avec os.popen() ; pourquoi ?: Il me semble impossible d'utiliser os read sur un tube créé avec os popen ; pourquoi ?. 
* Comment accéder au port de transmission en série (RS-232) ?: Comment accéder au port de transmission en série RS-232 ?. 
* Pourquoi fermer sys.stdout@comma{} sys.stdin@comma{} sys.stderr ne les ferme pas réellement ?: Pourquoi fermer sys stdout sys stdin sys stderr ne les ferme pas réellement ?. 

Programmation réseau et Internet

* Quels sont les outils Python dédiés à au web ?:: 
* Quel module utiliser pour générer du HTML ?:: 
* Comment envoyer un courriel avec un script Python ?:: 
* Comment éviter de bloquer dans la méthode connect() d'un connecteur réseau ?: Comment éviter de bloquer dans la méthode connect d'un connecteur réseau ?. 

Bases de données

* Existe-t-il des modules Python pour s'interfacer avec des bases de données ?:: 
* Comment implémenter la persistance d'objets en Python ?:: 

Mathématiques et calcul numérique

* Comment générer des nombres aléatoires en Python ?:: 

FAQ extension/intégration

* Puis-je créer mes propres fonctions en C ?:: 
* Puis-je créer mes propres fonctions en C++ ?:: 
* Écrire directement en C est difficile ; existe-t-il des alternatives ?:: 
* Comment puis-je exécuter des instructions quelconques Python à partir de C ?:: 
* Comment puis-je évaluer une expression quelconque de Python à partir de C ?:: 
* Comment puis-je extraire des donnés en C d'un objet Python ?:: 
* Comment utiliser Py_BuildValue() pour créer un n-uplet de longueur définie ?: Comment utiliser Py_BuildValue pour créer un n-uplet de longueur définie ?. 
* Comment puis-je appeler la méthode d'un objet à partir de C ?:: 
* Comment puis-je récupérer la sortie de PyErr_Print() (ou tout ce qui s'affiche sur stdout/stderr) ?: Comment puis-je récupérer la sortie de PyErr_Print ou tout ce qui s'affiche sur stdout/stderr ?. 
* Comment accéder à un module écrit en Python à partir de C ?:: 
* Comment s'interfacer avec les objets C++ depuis Python ?:: 
* J'ai ajouté un module en utilisant le fichier Setup et la compilation échoue ; pourquoi ?:: 
* Comment déboguer une extension ?:: 
* Je veux compiler un module Python sur mon système Linux@comma{} mais il manque certains fichiers. Pourquoi ?: Je veux compiler un module Python sur mon système Linux mais il manque certains fichiers Pourquoi ?. 
* Comment distinguer une « entrée incomplète » (incomplete input) d'une « entrée invalide » (invalid input) ?: Comment distinguer une « entrée incomplète » incomplete input d'une « entrée invalide » invalid input ?. 
* Comment puis-je trouver les symboles g++ indéfinis __builtin_new ou __pure_virtual ?:: 
* Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python (p. ex. en utilisant l'héritage) ?: Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python p ex en utilisant l'héritage ?. 

FAQ : Python et Windows

* Comment exécuter un programme Python sous Windows ?:: 
* Comment rendre des scripts Python exécutables ?:: 
* Pourquoi Python met-il du temps à démarrer ?:: 
* Comment construire un exécutable depuis un script Python ?:: 
* Est-ce qu'un fichier *.pyd est la même chose qu'une DLL ?: Est-ce qu'un fichier * pyd est la même chose qu'une DLL ?. 
* Comment puis-je intégrer Python dans une application Windows ?:: 
* Comment empêcher mon éditeur d'utiliser des tabulations dans mes fichiers Python ?:: 
* Comment puis-je vérifier de manière non bloquante qu'une touche a été pressée ?:: 
* Comment résoudre l'erreur « api-ms-win-crt-runtime-l1-1-0.dll manquante » ?: Comment résoudre l'erreur « api-ms-win-crt-runtime-l1-1-0 dll manquante » ?. 

FAQ interface graphique

* Questions générales sur l'interface graphique:: 
* Quelles boîtes à outils IUG existent pour Python ?:: 
* Questions à propos de Tkinter:: 

Questions à propos de Tkinter

* Comment puis-je geler (freezer) les applications Tkinter ?: Comment puis-je geler freezer les applications Tkinter ?. 
* Puis-je modifier des événements Tk pendant l'écoute des E/S ?:: 
* Je n'arrive pas à faire fonctionner les raccourcis clavier dans Tkinter ; pourquoi ?: Je n'arrive pas à faire fonctionner les raccourcis clavier dans Tkinter pourquoi ?. 

FAQ "Pourquoi Python est installé sur mon ordinateur ?"

* Qu'est-ce que Python ?: Qu'est-ce que Python ?<2>. 
* Pourquoi Python est installé sur ma machine ?:: 
* Puis-je supprimer Python ?:: 

Deprecations

* Pending Removal in Python 3.14: Pending Removal in Python 3 14<5>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<5>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<3>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<5>. 
* C API Deprecations:: 

C API Deprecations

* Pending Removal in Python 3.14: Pending Removal in Python 3 14<6>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<6>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<6>. 

About this documentation

* Contributors to the Python documentation:: 

S'attaquer aux bogues

* Bogues de documentation:: 
* Utilisation du gestionnaire de tickets Python:: 
* Commencer à contribuer à Python vous-même:: 

Histoire et licence

* Histoire du logiciel:: 
* Conditions générales pour accéder à@comma{} ou utiliser@comma{} Python: Conditions générales pour accéder à ou utiliser Python. 
* Licences et remerciements pour les logiciels tiers:: 

Conditions générales pour accéder à, ou utiliser, Python

* PSF LICENSE AGREEMENT FOR PYTHON 3.13.1: PSF LICENSE AGREEMENT FOR PYTHON 3 13 1. 
* LICENCE D'UTILISATION BEOPEN.COM POUR PYTHON 2.0: LICENCE D'UTILISATION BEOPEN COM POUR PYTHON 2 0. 
* LICENCE D'UTILISATION CNRI POUR PYTHON 1.6.1: LICENCE D'UTILISATION CNRI POUR PYTHON 1 6 1. 
* LICENCE D'UTILISATION CWI POUR PYTHON 0.9.0 à 1.2: LICENCE D'UTILISATION CWI POUR PYTHON 0 9 0 à 1 2. 
* LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3.13.1: LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3 13 1. 

Licences et remerciements pour les logiciels tiers

* Mersenne twister:: 
* Interfaces de connexion (sockets): Interfaces de connexion sockets. 
* Interfaces de connexion asynchrones:: 
* Gestion de témoin (cookie): Gestion de témoin cookie. 
* Traçage d'exécution:: 
* Les fonctions UUencode et UUdecode:: 
* Appel de procédures distantes en XML (RPC@comma{} pour Remote Procedure Call): Appel de procédures distantes en XML RPC pour Remote Procedure Call. 
* test_epoll:: 
* Select kqueue:: 
* SipHash24:: 
* strtod et dtoa:: 
* OpenSSL: OpenSSL<2>. 
* expat:: 
* libffi:: 
* zlib: zlib<3>. 
* cfuhash:: 
* libmpdec:: 
* Ensemble de tests C14N du W3C:: 
* mimalloc:: 
* asyncio: asyncio<12>. 
* Global Unbounded Sequences (GUS): Global Unbounded Sequences GUS. 

@end detailmenu
@end menu

@node Nouveautés de Python,Le tutoriel Python,Top,Top
@anchor{whatsnew/index doc}@anchor{135}@anchor{whatsnew/index python-documentation-contents}@anchor{136}@anchor{whatsnew/index what-s-new-in-python}@anchor{137}@anchor{whatsnew/index whatsnew-index}@anchor{138}
@chapter Nouveautés de Python


La série d'essais "Quoi de neuf dans Python" reprend les plus importants changements entres les versions majeures de Python. Elles sont à lire pour quiconque souhaitant être à jour suite à une nouvelle sortie.

@menu
* What's New In Python 3.13: What's New In Python 3 13. 
* What's New In Python 3.12: What's New In Python 3 12. 
* Les nouveautés de Python 3.11: Les nouveautés de Python 3 11. 
* Les nouveautés de Python 3.10: Les nouveautés de Python 3 10. 
* Les nouveautés de Python 3.9: Les nouveautés de Python 3 9. 
* Nouveautés de Python 3.8: Nouveautés de Python 3 8. 
* What's New In Python 3.7: What's New In Python 3 7. 
* What's New In Python 3.6: What's New In Python 3 6. 
* Nouveautés de Python 3.5: Nouveautés de Python 3 5. 
* Nouveautés de Python 3.4: Nouveautés de Python 3 4. 
* Nouveautés de Python 3.3: Nouveautés de Python 3 3. 
* Nouveautés de Python 3.2: Nouveautés de Python 3 2. 
* Nouveautés de Python 3.1: Nouveautés de Python 3 1. 
* Nouveautés de Python 3.0: Nouveautés de Python 3 0. 
* Nouveautés de Python 2.7: Nouveautés de Python 2 7. 
* Nouveautés de Python 2.6: Nouveautés de Python 2 6. 
* Nouveautés de Python 2.5: Nouveautés de Python 2 5. 
* Nouveautés de Python 2.4: Nouveautés de Python 2 4. 
* Nouveautés de Python 2.3: Nouveautés de Python 2 3. 
* Nouveautés de Python 2.2: Nouveautés de Python 2 2. 
* Nouveautés de Python 2.1: Nouveautés de Python 2 1. 
* Nouveautés de Python 2.0: Nouveautés de Python 2 0. 
* Changelog:: 

@end menu

@node What's New In Python 3 13,What's New In Python 3 12,,Nouveautés de Python
@anchor{whatsnew/3 13 doc}@anchor{139}@anchor{whatsnew/3 13 what-s-new-in-python-3-13}@anchor{13a}
@section What's New In Python 3.13


@*Editors: 
Adam Turner and Thomas Wouters


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the issue number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :gh:`12345`.)
@c 
@c This saves the maintainer the effort of going through the VCS log
@c when researching a change.

This article explains the new features in Python 3.13, compared to 3.12.
Python 3.13 was released on October 7, 2024.
For full details, see the @ref{13b,,changelog}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 719
PEP 719@footnote{https://peps.python.org/pep-0719/} -- Python 3.13 Release Schedule


@menu
* Summary: Summary -- Release Highlights. Release Highlights
* Nouvelles fonctionnalités:: 
* Autres changements au langage:: 
* Nouveaux modules:: 
* Modules améliorés:: 
* Optimisations:: 
* Removed Modules And APIs:: 
* New Deprecations:: 
* CPython Bytecode Changes:: 
* Changements à l'API C:: 
* Changements à la compilation:: 
* Porting to Python 3.13: Porting to Python 3 13. 
* Regression Test Changes:: 
* Notable changes in 3.13.1: Notable changes in 3 13 1. 

@end menu

@node Summary -- Release Highlights,Nouvelles fonctionnalités,,What's New In Python 3 13
@anchor{whatsnew/3 13 summary-release-highlights}@anchor{13c}
@subsection Summary -- Release Highlights


@c This section singles out the most important changes in Python 3.13.
@c Brevity is key.

Python 3.13 is the latest stable release of the Python programming
language, with a mix of changes to the language, the implementation
and the standard library.
The biggest changes include a new @ref{13d,,interactive interpreter}@anchor{whatsnew/3 13 whatsnew313-better-interactive-interpreter}@anchor{13d},
experimental support for running in a @ref{13e,,free-threaded mode}@anchor{whatsnew/3 13 whatsnew313-free-threaded-cpython}@anchor{13e} (
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}),
and a @ref{13f,,Just-In-Time compiler}@anchor{whatsnew/3 13 whatsnew313-jit-compiler}@anchor{13f} (
@geindex Python Enhancement Proposals; PEP 744
PEP 744@footnote{https://peps.python.org/pep-0744/}).

Error messages continue to improve, with tracebacks now highlighted in color
by default. The @ref{140,,locals()} builtin now has @ref{141,,defined semantics} for changing the returned mapping,
and type parameters now support default values.

The library changes contain removal of deprecated APIs and modules,
as well as the usual improvements in user-friendliness and correctness.
Several legacy standard library modules have now @ref{142,,been removed}@anchor{whatsnew/3 13 whatsnew313-pep594}@anchor{142} following their deprecation in Python 3.11 (
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}).

This article doesn't attempt to provide a complete specification
of all new features, but instead gives a convenient overview.
For full details refer to the documentation,
such as the @ref{143,,Library Reference}
and @ref{144,,Language Reference}.
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.
See @ref{145,,Porting to Python 3.13} for guidance on upgrading from
earlier versions of Python.


__________________________________________________________________


@c PEP-sized items next.

Améliorations de l'interpréteur :


@itemize *

@item 
A greatly improved @ref{13d,,interactive interpreter} and
@ref{146,,improved error messages}.

@item 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}: The @ref{140,,locals()} builtin now has
@ref{141,,defined semantics} when mutating the
returned mapping. Python debuggers and similar tools may now more reliably
update local variables in optimized scopes even during concurrent code
execution.

@item 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}: CPython 3.13 has experimental support for running with the
@ref{147,,global interpreter lock} disabled. See @ref{13e,,Free-threaded CPython} for more details.

@item 
@geindex Python Enhancement Proposals; PEP 744
PEP 744@footnote{https://peps.python.org/pep-0744/}: A basic @ref{13f,,JIT compiler} was added.
It is currently disabled by default (though we may turn it on later).
Performance improvements are modest -- we expect to improve this
over the next few releases.

@item 
Color support in the new @ref{13d,,interactive interpreter},
as well as in @ref{146,,tracebacks}
and @ref{148,,doctest} output.
This can be disabled through the 
@geindex PYTHON_COLORS
@geindex variable d'environnement; PYTHON_COLORS
@ref{149,,PYTHON_COLORS} and NO_COLOR@footnote{https://no-color.org/}
environment variables.
@end itemize

Python data model improvements:


@itemize *

@item 
@ref{14a,,__static_attributes__} stores the names of attributes accessed
through @code{self.X} in any function in a class body.

@item 
@ref{14b,,__firstlineno__} records the first line number of a class
definition.
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
Add a new @ref{14c,,PythonFinalizationError} exception, raised when an operation
is blocked during @ref{14d,,finalization}.

@item 
The @ref{6,,argparse} module now supports deprecating command-line options,
positional arguments, and subcommands.

@item 
The new functions @ref{14e,,base64.z85encode()} and @ref{14f,,base64.z85decode()}
support encoding and decoding Z85 data@footnote{https://rfc.zeromq.org/spec/32/}.

@item 
The @ref{25,,copy} module now has a @ref{150,,copy.replace()} function,
with support for many builtin types and any class defining
the @ref{151,,__replace__()} method.

@item 
The new @ref{35,,dbm.sqlite3} module is now the default @ref{31,,dbm} backend.

@item 
The @ref{a0,,os} module has a @ref{152,,suite of new functions}
for working with Linux's timer notification file descriptors.

@item 
The @ref{b7,,random} module now has a @ref{153,,command-line interface}.
@end itemize

Security improvements:


@itemize *

@item 
@ref{154,,ssl.create_default_context()} sets @ref{155,,ssl.VERIFY_X509_PARTIAL_CHAIN}
and @ref{156,,ssl.VERIFY_X509_STRICT} as default flags.
@end itemize

C API improvements:


@itemize *

@item 
The @ref{157,,Py_mod_gil} slot is now used to indicate that
an extension module supports running with the @ref{158,,GIL} disabled.

@item 
The @ref{159,,PyTime C API} has been added,
providing access to system clocks.

@item 
@ref{15a,,PyMutex} is a new lightweight mutex that occupies a single byte.

@item 
There is a new @ref{15b,,suite of functions}
for generating 
@geindex Python Enhancement Proposals; PEP 669
PEP 669@footnote{https://peps.python.org/pep-0669/} monitoring events in the C API.
@end itemize

Nouvelles fonctionnalités de typage :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}: Type parameters (@ref{15c,,typing.TypeVar}, @ref{15d,,typing.ParamSpec},
and @ref{15e,,typing.TypeVarTuple}) now support defaults.

@item 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}: The new @ref{15f,,warnings.deprecated()} decorator adds support
for marking deprecations in the type system and at runtime.

@item 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/}: @ref{160,,typing.ReadOnly} can be used to mark an item of a
@ref{161,,typing.TypedDict} as read-only for type checkers.

@item 
@geindex Python Enhancement Proposals; PEP 742
PEP 742@footnote{https://peps.python.org/pep-0742/}: @ref{162,,typing.TypeIs} provides more intuitive
type narrowing behavior, as an alternative to @ref{163,,typing.TypeGuard}.
@end itemize

Platform support:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 730
PEP 730@footnote{https://peps.python.org/pep-0730/}: Apple's iOS is now an @ref{164,,officially supported platform}, at 
@geindex Python Enhancement Proposals; PEP 11#tier-3
tier 3@footnote{https://peps.python.org/pep-0011/#tier-3}.

@item 
@geindex Python Enhancement Proposals; PEP 738
PEP 738@footnote{https://peps.python.org/pep-0738/}: Android is now an @ref{164,,officially supported platform}, at 
@geindex Python Enhancement Proposals; PEP 11#tier-3
tier 3@footnote{https://peps.python.org/pep-0011/#tier-3}.

@item 
@code{wasm32-wasi} is now supported as a 
@geindex Python Enhancement Proposals; PEP 11#tier-2
tier 2@footnote{https://peps.python.org/pep-0011/#tier-2} platform.

@item 
@code{wasm32-emscripten} is no longer an officially supported platform.
@end itemize

Important removals:


@itemize *

@item 
@ref{142,,PEP 594}: The remaining 19 "dead batteries"
(legacy stdlib modules) have been removed from the standard library:
@code{aifc}, @code{audioop}, @code{cgi}, @code{cgitb}, @code{chunk},
@code{crypt}, @code{imghdr}, @code{mailcap}, @code{msilib}, @code{nis},
@code{nntplib}, @code{ossaudiodev}, @code{pipes}, @code{sndhdr},
@code{spwd}, @code{sunau}, @code{telnetlib}, @code{uu} and @code{xdrlib}.

@item 
Remove the @code{2to3} tool and @code{lib2to3} module
(deprecated in Python 3.11).

@item 
Remove the @code{tkinter.tix} module (deprecated in Python 3.6).

@item 
Remove the @code{locale.resetlocale()} function.

@item 
Remove the @code{typing.io} and @code{typing.re} namespaces.

@item 
Remove chained @ref{165,,classmethod} descriptors.
@end itemize

Release schedule changes:

@geindex Python Enhancement Proposals; PEP 602
PEP 602@footnote{https://peps.python.org/pep-0602/} ("Annual Release Cycle for Python") has been updated
to extend the full support ('bugfix') period for new releases to two years.
This updated policy means that:


@itemize *

@item 
Python 3.9--3.12 have one and a half years of full support,
followed by three and a half years of security fixes.

@item 
Python 3.13 and later have two years of full support,
followed by three years of security fixes.
@end itemize

@node Nouvelles fonctionnalités,Autres changements au langage,Summary -- Release Highlights,What's New In Python 3 13
@anchor{whatsnew/3 13 new-features}@anchor{166}
@subsection Nouvelles fonctionnalités


@menu
* A better interactive interpreter:: 
* Improved error messages:: 
* Free-threaded CPython:: 
* An experimental just-in-time (JIT) compiler: An experimental just-in-time JIT compiler. 
* Defined mutation semantics for locals(): Defined mutation semantics for locals. 
* Support for mobile platforms:: 

@end menu

@node A better interactive interpreter,Improved error messages,,Nouvelles fonctionnalités
@anchor{whatsnew/3 13 a-better-interactive-interpreter}@anchor{167}
@subsubsection A better interactive interpreter


Python now uses a new @ref{168,,interactive} shell by default, based on code
from the PyPy project@footnote{https://pypy.org/}.
When the user starts the @ref{169,,REPL} from an interactive terminal,
the following new features are now supported:


@itemize *

@item 
Multiline editing with history preservation.

@item 
Direct support for REPL-specific commands like @code{help}, @code{exit},
and @code{quit}, without the need to call them as functions.

@item 
Prompts and tracebacks with @ref{16a,,color enabled by default}.

@item 
Interactive help browsing using @code{F1} with a separate command
history.

@item 
History browsing using @code{F2} that skips output as well as the
@ref{16b,,>>>} and @ref{16c,,...} prompts.

@item 
"Paste mode" with @code{F3} that makes pasting larger blocks of code
easier (press @code{F3} again to return to the regular prompt).
@end itemize

To disable the new interactive shell,
set the 
@geindex PYTHON_BASIC_REPL
@geindex variable d'environnement; PYTHON_BASIC_REPL
@ref{16d,,PYTHON_BASIC_REPL} environment variable.
For more on interactive mode, see @ref{16e,,Mode interactif}.

(Contributed by Pablo Galindo Salgado, Łukasz Langa, and
Lysandros Nikolaou in gh-111201@footnote{https://github.com/python/cpython/issues/111201} based on code from the PyPy project.
Windows support contributed by Dino Viehland and Anthony Shaw.)

@node Improved error messages,Free-threaded CPython,A better interactive interpreter,Nouvelles fonctionnalités
@anchor{whatsnew/3 13 improved-error-messages}@anchor{16f}@anchor{whatsnew/3 13 whatsnew313-improved-error-messages}@anchor{146}
@subsubsection Improved error messages



@itemize *

@item 
The interpreter now uses color by default when displaying tracebacks in the
terminal. This feature @ref{16a,,can be controlled}
via the new 
@geindex PYTHON_COLORS
@geindex variable d'environnement; PYTHON_COLORS
@ref{149,,PYTHON_COLORS} environment variable as well as
the canonical NO_COLOR@footnote{https://no-color.org/} and FORCE_COLOR@footnote{https://force-color.org/} environment variables.
(Contributed by Pablo Galindo Salgado in gh-112730@footnote{https://github.com/python/cpython/issues/112730}.)
@end itemize

@c Apparently this how you hack together a formatted link:
@c (https://www.docutils.org/docs/ref/rst/directives.html#replacement-text)


@itemize *

@item 
A common mistake is to write a script with the same name as a
standard library module. When this results in errors, we now
display a more helpful error message:

@example
$ python random.py
Traceback (most recent call last):
  File "/home/me/random.py", line 1, in <module>
    import random
  File "/home/me/random.py", line 3, in <module>
    print(random.randint(5))
          ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/me/random.py' since it has the same name as the standard library module named 'random' and prevents importing that standard library module)
@end example

Similarly, if a script has the same name as a third-party
module that it attempts to import and this results in errors,
we also display a more helpful error message:

@example
$ python numpy.py
Traceback (most recent call last):
  File "/home/me/numpy.py", line 1, in <module>
    import numpy as np
  File "/home/me/numpy.py", line 3, in <module>
    np.array([1, 2, 3])
    ^^^^^^^^
AttributeError: module 'numpy' has no attribute 'array' (consider renaming '/home/me/numpy.py' if it has the same name as a library you intended to import)
@end example

(Contributed by Shantanu Jain in gh-95754@footnote{https://github.com/python/cpython/issues/95754}.)

@item 
The error message now tries to suggest the correct keyword argument
when an incorrect keyword argument is passed to a function.

@example
>>> "Better error messages!".split(max_split=1)
Traceback (most recent call last):
  File "<python-input-0>", line 1, in <module>
    "Better error messages!".split(max_split=1)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
TypeError: split() got an unexpected keyword argument 'max_split'. Did you mean 'maxsplit'?
@end example

(Contributed by Pablo Galindo Salgado and Shantanu Jain in gh-107944@footnote{https://github.com/python/cpython/issues/107944}.)
@end itemize

@node Free-threaded CPython,An experimental just-in-time JIT compiler,Improved error messages,Nouvelles fonctionnalités
@anchor{whatsnew/3 13 free-threaded-cpython}@anchor{170}
@subsubsection Free-threaded CPython


CPython now has experimental support for running in a free-threaded mode,
with the @ref{147,,global interpreter lock} (GIL) disabled.
This is an experimental feature and therefore is not enabled by default.
The free-threaded mode requires a different executable,
usually called @code{python3.13t} or @code{python3.13t.exe}.
Pre-built binaries marked as `free-threaded' can be installed as part of
the official @ref{171,,Windows}
and @ref{172,,macOS} installers,
or CPython can be built from source with the @ref{173,,--disable-gil} option.

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.
Free-threaded builds of CPython support optionally running with the GIL
enabled at runtime using the environment variable 
@geindex PYTHON_GIL
@geindex variable d'environnement; PYTHON_GIL
@ref{174,,PYTHON_GIL} or
the command-line option @ref{175,,-X gil=1}.

To check if the current interpreter supports free-threading, @ref{176,,python -VV}
and @ref{177,,sys.version} contain "experimental free-threading build".
The new @code{sys._is_gil_enabled()} function can be used to check whether
the GIL is actually disabled in the running process.

C-API extension modules need to be built specifically for the free-threaded
build. Extensions that support running with the @ref{158,,GIL} disabled should
use the @ref{157,,Py_mod_gil} slot. Extensions using single-phase init should
use @ref{178,,PyUnstable_Module_SetGIL()} to indicate whether they support
running with the GIL disabled. Importing C extensions that don't use these
mechanisms will cause the GIL to be enabled, unless the GIL was explicitly
disabled with the 
@geindex PYTHON_GIL
@geindex variable d'environnement; PYTHON_GIL
@ref{174,,PYTHON_GIL} environment variable or the
@ref{175,,-X gil=0} option.
pip 24.1 or newer is required to install packages with C extensions in the
free-threaded build.

This work was made possible thanks to many individuals and
organizations, including the large community of contributors to Python
and third-party projects to test and enable free-threading support.
Notable contributors include:
Sam Gross, Ken Jin, Donghee Na, Itamar Oren, Matt Page, Brett Simmers,
Dino Viehland, Carl Meyer, Nathan Goldbaum, Ralf Gommers,
Lysandros Nikolaou, and many others.
Many of these contributors are employed by Meta, which has
provided significant engineering resources to support this project.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/} "Making the Global Interpreter Lock Optional in CPython"
contains rationale and information surrounding this work.

Porting Extension Modules to Support Free-Threading@footnote{https://py-free-threading.github.io/porting/}: A community-maintained
porting guide for extension authors.


@node An experimental just-in-time JIT compiler,Defined mutation semantics for locals,Free-threaded CPython,Nouvelles fonctionnalités
@anchor{whatsnew/3 13 an-experimental-just-in-time-jit-compiler}@anchor{179}
@subsubsection An experimental just-in-time (JIT) compiler


When CPython is configured and built using
the @code{--enable-experimental-jit} option,
a just-in-time (JIT) compiler is added which may speed up some Python programs.
On Windows, use @code{PCbuild/build.bat --experimental-jit} to enable the JIT
or @code{--experimental-jit-interpreter} to enable the Tier 2 interpreter.
Build requirements and further supporting information are contained at@footnote{https://github.com/python/cpython/blob/main/Tools/jit/README.md}
@code{Tools/jit/README.md}.

The @code{--enable-experimental-jit} option takes these (optional) values,
defaulting to @code{yes} if @code{--enable-experimental-jit} is present
without the optional value.


@itemize *

@item 
@code{no}: Disable the entire Tier 2 and JIT pipeline.

@item 
@code{yes}: Enable the JIT.
To disable the JIT at runtime, pass the environment variable @code{PYTHON_JIT=0}.

@item 
@code{yes-off}: Build the JIT but disable it by default.
To enable the JIT at runtime, pass the environment variable @code{PYTHON_JIT=1}.

@item 
@code{interpreter}: Enable the Tier 2 interpreter but disable the JIT.
The interpreter can be disabled by running with @code{PYTHON_JIT=0}.
@end itemize

The internal architecture is roughly as follows:


@itemize *

@item 
We start with specialized `Tier 1 bytecode'.
See @ref{17a,,What's new in 3.11} for details.

@item 
When the Tier 1 bytecode gets hot enough, it gets translated
to a new purely internal intermediate representation (IR),
called the `Tier 2 IR', and sometimes referred to as micro-ops ("uops").

@item 
The Tier 2 IR uses the same stack-based virtual machine as Tier 1,
but the instruction format is better suited to translation to machine code.

@item 
We have several optimization passes for Tier 2 IR, which are applied
before it is interpreted or translated to machine code.

@item 
There is a Tier 2 interpreter, but it is mostly intended for debugging
the earlier stages of the optimization pipeline.
The Tier 2 interpreter can be enabled by configuring Python
with @code{--enable-experimental-jit=interpreter}.

@item 
When the JIT is enabled, the optimized
Tier 2 IR is translated to machine code, which is then executed.

@item 
The machine code translation process uses a technique called
`copy-and-patch'. It has no runtime dependencies, but there is a new
build-time dependency on LLVM.
@end itemize


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 744
PEP 744@footnote{https://peps.python.org/pep-0744/}


(JIT by Brandt Bucher, inspired by a paper by Haoran Xu and Fredrik Kjolstad.
Tier 2 IR by Mark Shannon and Guido van Rossum.
Tier 2 optimizer by Ken Jin.)

@node Defined mutation semantics for locals,Support for mobile platforms,An experimental just-in-time JIT compiler,Nouvelles fonctionnalités
@anchor{whatsnew/3 13 defined-mutation-semantics-for-locals}@anchor{17b}@anchor{whatsnew/3 13 whatsnew313-locals-semantics}@anchor{141}
@subsubsection Defined mutation semantics for @code{locals()}


Historically, the expected result of mutating the return value of
@ref{140,,locals()} has been left to individual Python implementations to define.
Starting from Python 3.13, 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/} standardises
the historical behavior of CPython for most code execution scopes,
but changes @ref{17c,,optimized scopes}
(functions, generators, coroutines, comprehensions, and generator expressions)
to explicitly return independent snapshots of the currently assigned local
variables, including locally referenced nonlocal variables captured in closures.

This change to the semantics of @ref{140,,locals()} in optimized scopes also
affects the default behavior of code execution functions that implicitly
target @code{locals()} if no explicit namespace is provided
(such as @ref{17d,,exec()} and @ref{17e,,eval()}).
In previous versions, whether or not changes could be accessed by calling
@code{locals()} after calling the code execution function was
implementation-dependent. In CPython specifically, such code would typically
appear to work as desired, but could sometimes fail in optimized scopes based
on other code (including debuggers and code execution tracing tools)
potentially resetting the shared snapshot in that scope.
Now, the code will always run against an independent snapshot of
the local variables in optimized scopes, and hence the changes will never
be visible in subsequent calls to @code{locals()}.
To access the changes made in these cases, an explicit namespace reference
must now be passed to the relevant function.
Alternatively, it may make sense to update affected code to use a higher level
code execution API that returns the resulting code execution namespace
(e.g. @ref{17f,,runpy.run_path()} when executing Python files from disk).

To ensure debuggers and similar tools can reliably update local variables in
scopes affected by this change, @ref{180,,FrameType.f_locals} now
returns a write-through proxy to the frame's local and locally referenced
nonlocal variables in these scopes, rather than returning an inconsistently
updated shared @code{dict} instance with undefined runtime semantics.

See 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/} for more details, including related C API changes
and deprecations. Porting notes are also provided below for the affected
@ref{181,,Python APIs} and @ref{182,,C APIs}.

(PEP and implementation contributed by Mark Shannon and Tian Gao in
gh-74929@footnote{https://github.com/python/cpython/issues/74929}. Documentation updates provided by Guido van Rossum and
Alyssa Coghlan.)

@node Support for mobile platforms,,Defined mutation semantics for locals,Nouvelles fonctionnalités
@anchor{whatsnew/3 13 support-for-mobile-platforms}@anchor{183}@anchor{whatsnew/3 13 whatsnew313-platform-support}@anchor{164}
@subsubsection Support for mobile platforms


@geindex Python Enhancement Proposals; PEP 730
PEP 730@footnote{https://peps.python.org/pep-0730/}: iOS is now a 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} supported platform, with the
@code{arm64-apple-ios} and @code{arm64-apple-ios-simulator} targets at tier 3
(iPhone and iPad devices released after 2013 and the Xcode iOS simulator
running on Apple silicon hardware, respectively).
@code{x86_64-apple-ios-simulator}
(the Xcode iOS simulator running on older @code{x86_64} hardware)
is not a tier 3 supported platform, but will have best-effort support.
(PEP written and implementation contributed by Russell Keith-Magee in
gh-114099@footnote{https://github.com/python/cpython/issues/114099}.)

@geindex Python Enhancement Proposals; PEP 738
PEP 738@footnote{https://peps.python.org/pep-0738/}: Android is now a 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} supported platform, with the
@code{aarch64-linux-android} and @code{x86_64-linux-android} targets at tier 3.
The 32-bit targets @code{arm-linux-androideabi} and @code{i686-linux-android}
are not tier 3 supported platforms, but will have best-effort support.
(PEP written and implementation contributed by Malcolm Smith in
gh-116622@footnote{https://github.com/python/cpython/issues/116622}.)


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 730
PEP 730@footnote{https://peps.python.org/pep-0730/}, 
@geindex Python Enhancement Proposals; PEP 738
PEP 738@footnote{https://peps.python.org/pep-0738/}


@node Autres changements au langage,Nouveaux modules,Nouvelles fonctionnalités,What's New In Python 3 13
@anchor{whatsnew/3 13 other-language-changes}@anchor{184}
@subsection Autres changements au langage



@itemize *

@item 
The compiler now strips common leading whitespace
from every line in a docstring.
This reduces the size of the @ref{185,,bytecode cache}
(such as @code{.pyc} files), with reductions in file size of around 5%,
for example in @code{sqlalchemy.orm.session} from SQLAlchemy 2.0.
This change affects tools that use docstrings, such as @ref{3a,,doctest}.

@example
>>> def spam():
...     """
...         This is a docstring with
...           leading whitespace.
...
...         It even has multiple paragraphs!
...     """
...
>>> spam.__doc__
'\nThis is a docstring with\n  leading whitespace.\n\nIt even has multiple paragraphs!\n'
@end example

(Contributed by Inada Naoki in gh-81283@footnote{https://github.com/python/cpython/issues/81283}.)

@item 
@ref{186,,Annotation scopes} within class scopes
can now contain lambdas and comprehensions.
Comprehensions that are located within class scopes
are not inlined into their parent scope.

@example
class C[T]:
    type Alias = lambda: T
@end example

(Contributed by Jelle Zijlstra in gh-109118@footnote{https://github.com/python/cpython/issues/109118} and gh-118160@footnote{https://github.com/python/cpython/issues/118160}.)

@item 
@ref{187,,Future statements} are no longer triggered by
relative imports of the @ref{0,,__future__} module,
meaning that statements of the form @code{from .__future__ import ...}
are now simply standard relative imports, with no special features activated.
(Contributed by Jeremiah Gabriel Pascual in gh-118216@footnote{https://github.com/python/cpython/issues/118216}.)

@item 
@ref{188,,global} declarations are now permitted in @ref{189,,except} blocks
when that global is used in the @ref{18a,,else} block.
Previously this raised an erroneous @ref{18b,,SyntaxError}.
(Contributed by Irit Katriel in gh-111123@footnote{https://github.com/python/cpython/issues/111123}.)

@item 
Add 
@geindex PYTHON_FROZEN_MODULES
@geindex variable d'environnement; PYTHON_FROZEN_MODULES
@ref{18c,,PYTHON_FROZEN_MODULES}, a new environment variable that
determines whether frozen modules are ignored by the import machinery,
equivalent to the @ref{175,,-X frozen_modules} command-line option.
(Contributed by Yilei Yang in gh-111374@footnote{https://github.com/python/cpython/issues/111374}.)

@item 
Add @ref{18d,,support for the perf profiler} working
without frame pointers@footnote{https://en.wikipedia.org/wiki/Call_stack} through
the new environment variable 
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex variable d'environnement; PYTHON_PERF_JIT_SUPPORT
@ref{18e,,PYTHON_PERF_JIT_SUPPORT}
and command-line option @ref{175,,-X perf_jit}.
(Contributed by Pablo Galindo in gh-118518@footnote{https://github.com/python/cpython/issues/118518}.)

@item 
The location of a @code{.python_history} file can be changed via the
new 
@geindex PYTHON_HISTORY
@geindex variable d'environnement; PYTHON_HISTORY
@ref{18f,,PYTHON_HISTORY} environment variable.
(Contributed by Levi Sabah, Zackery Spytz and Hugo van Kemenade
in gh-73965@footnote{https://github.com/python/cpython/issues/73965}.)

@item 
Classes have a new @ref{14a,,__static_attributes__} attribute.
This is populated by the compiler with a tuple of the class's attribute names
which are assigned through @code{self.<name>} from any function in its body.
(Contributed by Irit Katriel in gh-115775@footnote{https://github.com/python/cpython/issues/115775}.)

@item 
The compiler now creates a @code{__firstlineno__} attribute on classes
with the line number of the first line of the class definition.
(Contributed by Serhiy Storchaka in gh-118465@footnote{https://github.com/python/cpython/issues/118465}.)

@item 
The @ref{17d,,exec()} and @ref{17e,,eval()} builtins now accept
the `globals' and `locals' arguments as keywords.
(Contributed by Raphael Gaschignard in gh-105879@footnote{https://github.com/python/cpython/issues/105879})

@item 
The @ref{190,,compile()} builtin now accepts a new flag,
@code{ast.PyCF_OPTIMIZED_AST}, which is similar to @code{ast.PyCF_ONLY_AST}
except that the returned AST is optimized according to
the value of the `optimize' argument.
(Contributed by Irit Katriel in gh-108113@footnote{https://github.com/python/cpython/issues/108113}).

@item 
Add a @ref{191,,__name__} attribute on @ref{192,,property} objects.
(Contributed by Eugene Toder in gh-101860@footnote{https://github.com/python/cpython/issues/101860}.)

@item 
Add @ref{14c,,PythonFinalizationError}, a new exception derived from
@ref{193,,RuntimeError} and used to signal when operations are blocked
during @ref{14d,,finalization}.
The following callables now raise @code{PythonFinalizationError},
instead of @ref{193,,RuntimeError}:


@itemize *

@item 
@ref{194,,_thread.start_new_thread()}

@item 
@ref{195,,os.fork()}

@item 
@ref{196,,os.forkpty()}

@item 
@ref{197,,subprocess.Popen}
@end itemize

(Contributed by Victor Stinner in gh-114570@footnote{https://github.com/python/cpython/issues/114570}.)

@item 
Allow the `count' argument of @ref{198,,str.replace()} to be a keyword.
(Contributed by Hugo van Kemenade in gh-106487@footnote{https://github.com/python/cpython/issues/106487}.)

@item 
Many functions now emit a warning if a boolean value is passed as
a file descriptor argument.
This can help catch some errors earlier.
(Contributed by Serhiy Storchaka in gh-82626@footnote{https://github.com/python/cpython/issues/82626}.)

@item 
Added @code{name} and @code{mode} attributes
for compressed and archived file-like objects in
the @ref{13,,bz2}, @ref{89,,lzma}, @ref{dd,,tarfile}, and @ref{130,,zipfile} modules.
(Contributed by Serhiy Storchaka in gh-115961@footnote{https://github.com/python/cpython/issues/115961}.)
@end itemize

@node Nouveaux modules,Modules améliorés,Autres changements au langage,What's New In Python 3 13
@anchor{whatsnew/3 13 new-modules}@anchor{199}
@subsection Nouveaux modules



@itemize *

@item 
@ref{35,,dbm.sqlite3}: An SQLite backend for @ref{31,,dbm}.
(Contributed by Raymond Hettinger and Erlend E. Aasland in gh-100414@footnote{https://github.com/python/cpython/issues/100414}.)
@end itemize

@node Modules améliorés,Optimisations,Nouveaux modules,What's New In Python 3 13
@anchor{whatsnew/3 13 improved-modules}@anchor{19a}
@subsection Modules améliorés


@menu
* argparse:: 
* array:: 
* ast:: 
* asyncio:: 
* base64:: 
* compileall:: 
* concurrent.futures: concurrent futures. 
* configparser:: 
* copy:: 
* ctypes:: 
* dbm:: 
* dis:: 
* doctest:: 
* email:: 
* enum:: 
* fractions:: 
* glob:: 
* importlib:: 
* io:: 
* ipaddress:: 
* itertools:: 
* marshal:: 
* math:: 
* mimetypes:: 
* mmap:: 
* multiprocessing:: 
* os:: 
* os.path: os path. 
* pathlib:: 
* pdb:: 
* queue:: 
* random:: 
* re:: 
* shutils:: 
* site:: 
* sqlite3:: 
* ssl:: 
* statistics:: 
* subprocess:: 
* sys:: 
* tempfile:: 
* time:: 
* tkinter:: 
* traceback:: 
* types:: 
* typing:: 
* unicodedata:: 
* venv:: 
* warnings:: 
* xml:: 
* zipimport:: 

@end menu

@node argparse,array,,Modules améliorés
@anchor{whatsnew/3 13 argparse}@anchor{19b}
@subsubsection argparse



@itemize *

@item 
Add the `deprecated' parameter to the
@ref{19c,,add_argument()}
and @code{add_parser()} methods, to enable deprecating
command-line options, positional arguments, and subcommands.
(Contributed by Serhiy Storchaka in gh-83648@footnote{https://github.com/python/cpython/issues/83648}.)
@end itemize

@node array,ast,argparse,Modules améliorés
@anchor{whatsnew/3 13 array}@anchor{19d}
@subsubsection `array'



@itemize *

@item 
Add the @code{'w'} type code (@code{Py_UCS4}) for Unicode characters.
It should be used instead of the deprecated @code{'u'} type code.
(Contributed by Inada Naoki in gh-80480@footnote{https://github.com/python/cpython/issues/80480}.)

@item 
Register @ref{19e,,array.array} as a @ref{19f,,MutableSequence}
by implementing the @ref{1a0,,clear()} method.
(Contributed by Mike Zimin in gh-114894@footnote{https://github.com/python/cpython/issues/114894}.)
@end itemize

@node ast,asyncio,array,Modules améliorés
@anchor{whatsnew/3 13 ast}@anchor{1a1}
@subsubsection `ast'



@itemize *

@item 
The constructors of node types in the @ref{8,,ast} module are now
stricter in the arguments they accept,
with more intuitive behavior when arguments are omitted.

If an optional field on an AST node is not included as an argument when
constructing an instance, the field will now be set to @code{None}. Similarly,
if a list field is omitted, that field will now be set to an empty list,
and if an @code{expr_context} field is omitted, it defaults to
@ref{1a2,,Load()}.
(Previously, in all cases, the attribute would be missing on the newly
constructed AST node instance.)

In all other cases, where a required argument is omitted,
the node constructor will emit a @ref{1a3,,DeprecationWarning}.
This will raise an exception in Python 3.15.
Similarly, passing a keyword argument to the constructor
that does not map to a field on the AST node is now deprecated,
and will raise an exception in Python 3.15.

These changes do not apply to user-defined subclasses of @ref{1a4,,ast.AST}
unless the class opts in to the new behavior
by defining the @ref{1a5,,AST._field_types} mapping.

(Contributed by Jelle Zijlstra in gh-105858@footnote{https://github.com/python/cpython/issues/105858}, gh-117486@footnote{https://github.com/python/cpython/issues/117486}, and gh-118851@footnote{https://github.com/python/cpython/issues/118851}.)

@item 
@ref{1a6,,ast.parse()} now accepts an optional argument `optimize'
which is passed on to @ref{190,,compile()}.
This makes it possible to obtain an optimized AST.
(Contributed by Irit Katriel in gh-108113@footnote{https://github.com/python/cpython/issues/108113}.)
@end itemize

@node asyncio,base64,ast,Modules améliorés
@anchor{whatsnew/3 13 asyncio}@anchor{1a7}
@subsubsection `asyncio'



@itemize *

@item 
@ref{1a8,,asyncio.as_completed()} now returns an object that is both an
@ref{1a9,,asynchronous iterator} and a plain @ref{1aa,,iterator}
of @ref{1ab,,awaitables}.
The awaitables yielded by asynchronous iteration include original task
or future objects that were passed in,
making it easier to associate results with the tasks being completed.
(Contributed by Justin Arthur in gh-77714@footnote{https://github.com/python/cpython/issues/77714}.)

@item 
@ref{1ac,,asyncio.loop.create_unix_server()} will now automatically remove
the Unix socket when the server is closed.
(Contributed by Pierre Ossman in gh-111246@footnote{https://github.com/python/cpython/issues/111246}.)

@item 
@ref{1ad,,DatagramTransport.sendto()} will now send zero-length
datagrams if called with an empty bytes object.
The transport flow control also now accounts for the datagram header
when calculating the buffer size.
(Contributed by Jamie Phan in gh-115199@footnote{https://github.com/python/cpython/issues/115199}.)

@item 
Add @ref{1ae,,Queue.shutdown}
and @ref{1af,,QueueShutDown} to manage queue termination.
(Contributed by Laurie Opperman and Yves Duprat in gh-104228@footnote{https://github.com/python/cpython/issues/104228}.)

@item 
Add the @ref{1b0,,Server.close_clients()} and @ref{1b1,,Server.abort_clients()}
methods, which more forcefully close an asyncio server.
(Contributed by Pierre Ossman in gh-113538@footnote{https://github.com/python/cpython/issues/113538}.)

@item 
Accept a tuple of separators in @ref{1b2,,StreamReader.readuntil()},
stopping when any one of them is encountered.
(Contributed by Bruce Merry in gh-81322@footnote{https://github.com/python/cpython/issues/81322}.)

@item 
Improve the behavior of @ref{1b3,,TaskGroup} when
an external cancellation collides with an internal cancellation.
For example, when two task groups are nested
and both experience an exception in a child task simultaneously,
it was possible that the outer task group would hang,
because its internal cancellation was swallowed by the inner task group.

In the case where a task group is cancelled externally
and also must raise an @ref{1b4,,ExceptionGroup},
it will now call the parent task's @ref{1b5,,cancel()} method.
This ensures that a @ref{1b6,,CancelledError} will be raised
at the next @ref{1b7,,await}, so the cancellation is not lost.

An added benefit of these changes is that task groups now preserve
the cancellation count (@ref{1b8,,cancelling()}).

In order to handle some corner cases, @ref{1b9,,uncancel()} may now
reset the undocumented @code{_must_cancel} flag
when the cancellation count reaches zero.

(Inspired by an issue reported by Arthur Tacca in gh-116720@footnote{https://github.com/python/cpython/issues/116720}.)

@item 
When @ref{1ba,,TaskGroup.create_task()} is called on an inactive
@ref{1b3,,TaskGroup}, the given coroutine will be closed (which
prevents a @ref{1bb,,RuntimeWarning} about the given coroutine being
never awaited).
(Contributed by Arthur Tacca and Jason Zhang in gh-115957@footnote{https://github.com/python/cpython/issues/115957}.)
@end itemize

@node base64,compileall,asyncio,Modules améliorés
@anchor{whatsnew/3 13 base64}@anchor{1bc}
@subsubsection base64



@itemize *

@item 
Add @ref{14e,,z85encode()} and @ref{14f,,z85decode()} functions
for encoding @ref{1bd,,bytes} as Z85 data@footnote{https://rfc.zeromq.org/spec/32/}
and decoding Z85-encoded data to @code{bytes}.
(Contributed by Matan Perelman in gh-75299@footnote{https://github.com/python/cpython/issues/75299}.)
@end itemize

@node compileall,concurrent futures,base64,Modules améliorés
@anchor{whatsnew/3 13 compileall}@anchor{1be}
@subsubsection `compileall'



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{1bf,,os.process_cpu_count()} instead of @ref{1c0,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node concurrent futures,configparser,compileall,Modules améliorés
@anchor{whatsnew/3 13 concurrent-futures}@anchor{1c1}
@subsubsection `concurrent.futures'



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{1bf,,os.process_cpu_count()} instead of @ref{1c0,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node configparser,copy,concurrent futures,Modules améliorés
@anchor{whatsnew/3 13 configparser}@anchor{1c2}
@subsubsection configparser



@itemize *

@item 
@ref{1c3,,ConfigParser} now has support for unnamed sections,
which allows for top-level key-value pairs.
This can be enabled with the new `allow_unnamed_section' parameter.
(Contributed by Pedro Sousa Lacerda in gh-66449@footnote{https://github.com/python/cpython/issues/66449}.)
@end itemize

@node copy,ctypes,configparser,Modules améliorés
@anchor{whatsnew/3 13 copy}@anchor{1c4}
@subsubsection copy



@itemize *

@item 
The new @ref{150,,replace()} function and the @ref{151,,replace protocol} make creating modified copies of objects much simpler.
This is especially useful when working with immutable objects.
The following types support the @ref{150,,replace()} function
and implement the replace protocol:


@itemize *

@item 
@ref{1c5,,collections.namedtuple()}

@item 
@ref{1c6,,dataclasses.dataclass}

@item 
@ref{1c7,,datetime.datetime}, @ref{1c8,,datetime.date}, @ref{1c9,,datetime.time}

@item 
@ref{1ca,,inspect.Signature}, @ref{1cb,,inspect.Parameter}

@item 
@ref{1cc,,types.SimpleNamespace}

@item 
@ref{1cd,,code objects}
@end itemize

Any user-defined class can also support @ref{150,,copy.replace()} by defining
the @ref{151,,__replace__()} method.
(Contributed by Serhiy Storchaka in gh-108751@footnote{https://github.com/python/cpython/issues/108751}.)
@end itemize

@node ctypes,dbm,copy,Modules améliorés
@anchor{whatsnew/3 13 ctypes}@anchor{1ce}
@subsubsection ctypes



@itemize *

@item 
As a consequence of necessary internal refactoring, initialization of
internal metaclasses now happens in @code{__init__} rather
than in @code{__new__}. This affects projects that subclass these internal
metaclasses to provide custom initialization.
Generally:


@itemize -

@item 
Custom logic that was done in @code{__new__} after calling @code{super().__new__}
should be moved to @code{__init__}.

@item 
To create a class, call the metaclass, not only the metaclass's
@code{__new__} method.
@end itemize

See gh-124520@footnote{https://github.com/python/cpython/issues/124520} for discussion and links to changes in some affected
projects.

@item 
@ref{1cf,,ctypes.Structure} objects have a new @ref{1d0,,_align_}
attribute which allows the alignment of the structure being packed to/from
memory to be specified explicitly.
(Contributed by Matt Sanderson in gh-112433@footnote{https://github.com/python/cpython/issues/112433})
@end itemize

@node dbm,dis,ctypes,Modules améliorés
@anchor{whatsnew/3 13 dbm}@anchor{1d1}
@subsubsection dbm



@itemize *

@item 
Add @ref{35,,dbm.sqlite3}, a new module which implements an SQLite backend,
and make it the default @code{dbm} backend.
(Contributed by Raymond Hettinger and Erlend E. Aasland in gh-100414@footnote{https://github.com/python/cpython/issues/100414}.)

@item 
Allow removing all items from the database through
the new @ref{1d2,,gdbm.clear()} and @ref{1d3,,ndbm.clear()} methods.
(Contributed by Donghee Na in gh-107122@footnote{https://github.com/python/cpython/issues/107122}.)
@end itemize

@node dis,doctest,dbm,Modules améliorés
@anchor{whatsnew/3 13 dis}@anchor{1d4}
@subsubsection dis



@itemize *

@item 
Change the output of @ref{38,,dis} module functions to show logical
labels for jump targets and exception handlers, rather than offsets.
The offsets can be added with the new
@ref{1d5,,-O} command-line option
or the `show_offsets' argument.
(Contributed by Irit Katriel in gh-112137@footnote{https://github.com/python/cpython/issues/112137}.)

@item 
@ref{1d6,,get_instructions()} no longer represents cache entries
as separate instructions.
Instead, it returns them as part of the @ref{1d7,,Instruction},
in the new `cache_info' field.
The `show_caches' argument to @ref{1d6,,get_instructions()} is deprecated
and no longer has any effect.
(Contributed by Irit Katriel in gh-112962@footnote{https://github.com/python/cpython/issues/112962}.)
@end itemize

@node doctest,email,dis,Modules améliorés
@anchor{whatsnew/3 13 doctest}@anchor{1d8}@anchor{whatsnew/3 13 whatsnew313-doctest}@anchor{148}
@subsubsection doctest



@itemize *

@item 
@ref{3a,,doctest} output is now colored by default.
This can be controlled via the new 
@geindex PYTHON_COLORS
@geindex variable d'environnement; PYTHON_COLORS
@ref{149,,PYTHON_COLORS} environment
variable as well as the canonical NO_COLOR@footnote{https://no-color.org/}
and FORCE_COLOR@footnote{https://force-color.org/} environment variables.
See also @ref{16a,,Controlling color}.
(Contributed by Hugo van Kemenade in gh-117225@footnote{https://github.com/python/cpython/issues/117225}.)

@item 
The @ref{1d9,,DocTestRunner.run()} method now counts the number of skipped tests.
Add the @ref{1da,,DocTestRunner.skips} and @ref{1db,,TestResults.skipped} attributes.
(Contributed by Victor Stinner in gh-108794@footnote{https://github.com/python/cpython/issues/108794}.)
@end itemize

@node email,enum,doctest,Modules améliorés
@anchor{whatsnew/3 13 email}@anchor{1dc}
@subsubsection email



@itemize *

@item 
Headers with embedded newlines are now quoted on output.
The @ref{40,,generator} will now refuse to serialize (write) headers
that are improperly folded or delimited, such that they would be parsed as
multiple headers or joined with adjacent data.
If you need to turn this safety feature off,
set @ref{1dd,,verify_generated_headers}.
(Contributed by Bas Bloemsaat and Petr Viktorin in gh-121650@footnote{https://github.com/python/cpython/issues/121650}.)

@item 
@ref{1de,,getaddresses()} and @ref{1df,,parseaddr()} now
return @code{('@w{'}, '@w{'})} pairs in more situations where invalid email addresses
are encountered instead of potentially inaccurate values.
The two functions have a new optional `strict' parameter (default @code{True}).
To get the old behavior (accepting malformed input), use @code{strict=False}.
@code{getattr(email.utils, 'supports_strict_parsing', False)} can be used
to check if the `strict' parameter is available.
(Contributed by Thomas Dwyer and Victor Stinner for gh-102988@footnote{https://github.com/python/cpython/issues/102988} to improve
the 
@geindex Common Vulnerabilities and Exposures; CVE 2023-27043
CVE 2023-27043@footnote{https://www.cve.org/CVERecord?id=CVE-2023-27043} fix.)
@end itemize

@node enum,fractions,email,Modules améliorés
@anchor{whatsnew/3 13 enum}@anchor{1e0}
@subsubsection enum



@itemize *

@item 
@ref{1e1,,EnumDict} has been made public to better support subclassing
@ref{1e2,,EnumType}.
@end itemize

@node fractions,glob,enum,Modules améliorés
@anchor{whatsnew/3 13 fractions}@anchor{1e3}
@subsubsection @code{fractions}



@itemize *

@item 
@ref{1e4,,Fraction} objects now support the standard
@ref{1e5,,format specification mini-language} rules
for fill, alignment, sign handling, minimum width, and grouping.
(Contributed by Mark Dickinson in gh-111320@footnote{https://github.com/python/cpython/issues/111320}.)
@end itemize

@node glob,importlib,fractions,Modules améliorés
@anchor{whatsnew/3 13 glob}@anchor{1e6}
@subsubsection glob



@itemize *

@item 
Add @ref{1e7,,translate()}, a function to convert a path specification
with shell-style wildcards to a regular expression.
(Contributed by Barney Gale in gh-72904@footnote{https://github.com/python/cpython/issues/72904}.)
@end itemize

@node importlib,io,glob,Modules améliorés
@anchor{whatsnew/3 13 importlib}@anchor{1e8}
@subsubsection `importlib'



@itemize *

@item 
The following functions in @ref{7a,,importlib.resources} now allow accessing
a directory (or tree) of resources, using multiple positional arguments
(the `encoding' and `errors' arguments in the text-reading functions
are now keyword-only):


@itemize *

@item 
@ref{1e9,,is_resource()}

@item 
@ref{1ea,,open_binary()}

@item 
@ref{1eb,,open_text()}

@item 
@ref{1ec,,path()}

@item 
@ref{1ed,,read_binary()}

@item 
@ref{1ee,,read_text()}
@end itemize

These functions are no longer deprecated and are not scheduled for removal.
(Contributed by Petr Viktorin in gh-116608@footnote{https://github.com/python/cpython/issues/116608}.)

@item 
@ref{1ef,,contents()} remains deprecated in favor of
the fully-featured @ref{1f0,,Traversable} API.
However, there is now no plan to remove it.
(Contributed by Petr Viktorin in gh-116608@footnote{https://github.com/python/cpython/issues/116608}.)
@end itemize

@node io,ipaddress,importlib,Modules améliorés
@anchor{whatsnew/3 13 io}@anchor{1f1}
@subsubsection io



@itemize *

@item 
The @ref{1f2,,IOBase} finalizer now logs any errors raised by
the @ref{1f3,,close()} method with @ref{1f4,,sys.unraisablehook}.
Previously, errors were ignored silently by default,
and only logged in @ref{1f5,,Python Development Mode}
or when using a @ref{1f6,,Python debug build}.
(Contributed by Victor Stinner in gh-62948@footnote{https://github.com/python/cpython/issues/62948}.)
@end itemize

@node ipaddress,itertools,io,Modules améliorés
@anchor{whatsnew/3 13 ipaddress}@anchor{1f7}
@subsubsection `ipaddress'



@itemize *

@item 
Add the @ref{1f8,,IPv4Address.ipv6_mapped} property,
which returns the IPv4-mapped IPv6 address.
(Contributed by Charles Machalow in gh-109466@footnote{https://github.com/python/cpython/issues/109466}.)

@item 
Fix @code{is_global} and @code{is_private} behavior in
@ref{1f9,,IPv4Address}, @ref{1fa,,IPv6Address},
@ref{1fb,,IPv4Network}, and @ref{1fc,,IPv6Network}.
(Contributed by Jakub Stasiak in gh-113171@footnote{https://github.com/python/cpython/issues/113171}.)
@end itemize

@node itertools,marshal,ipaddress,Modules améliorés
@anchor{whatsnew/3 13 itertools}@anchor{1fd}
@subsubsection itertools



@itemize *

@item 
@ref{1fe,,batched()} has a new `strict' parameter,
which raises a @ref{1ff,,ValueError} if the final batch is shorter
than the specified batch size.
(Contributed by Raymond Hettinger in gh-113202@footnote{https://github.com/python/cpython/issues/113202}.)
@end itemize

@node marshal,math,itertools,Modules améliorés
@anchor{whatsnew/3 13 marshal}@anchor{200}
@subsubsection marshal



@itemize *

@item 
Add the `allow_code' parameter in module functions.
Passing @code{allow_code=False} prevents serialization and de-serialization
of code objects which are incompatible between Python versions.
(Contributed by Serhiy Storchaka in gh-113626@footnote{https://github.com/python/cpython/issues/113626}.)
@end itemize

@node math,mimetypes,marshal,Modules améliorés
@anchor{whatsnew/3 13 math}@anchor{201}
@subsubsection `math'



@itemize *

@item 
The new function @ref{202,,fma()} performs fused multiply-add operations.
This computes @code{x * y + z} with only a single round,
and so avoids any intermediate loss of precision.
It wraps the @code{fma()} function provided by C99,
and follows the specification of the IEEE 754 "fusedMultiplyAdd" operation
for special cases.
(Contributed by Mark Dickinson and Victor Stinner in gh-73468@footnote{https://github.com/python/cpython/issues/73468}.)
@end itemize

@node mimetypes,mmap,math,Modules améliorés
@anchor{whatsnew/3 13 mimetypes}@anchor{203}
@subsubsection mimetypes



@itemize *

@item 
Add the @ref{204,,guess_file_type()} function to guess a MIME type
from a filesystem path.
Using paths with @ref{205,,guess_type()} is now @ref{206,,soft deprecated}.
(Contributed by Serhiy Storchaka in gh-66543@footnote{https://github.com/python/cpython/issues/66543}.)
@end itemize

@node mmap,multiprocessing,mimetypes,Modules améliorés
@anchor{whatsnew/3 13 mmap}@anchor{207}
@subsubsection mmap



@itemize *

@item 
@ref{208,,mmap} is now protected from crashing on Windows when the
mapped memory is inaccessible due to file system errors or access violations.
(Contributed by Jannis Weigend in gh-118209@footnote{https://github.com/python/cpython/issues/118209}.)

@item 
@ref{208,,mmap} has a new @ref{209,,seekable()} method
that can be used when a seekable file-like object is required.
The @ref{20a,,seek()} method now returns the new absolute position.
(Contributed by Donghee Na and Sylvie Liberman in gh-111835@footnote{https://github.com/python/cpython/issues/111835}.)

@item 
The new UNIX-only `trackfd' parameter for @ref{208,,mmap} controls
file descriptor duplication;
if false, the file descriptor specified by `fileno' will not be duplicated.
(Contributed by Zackery Spytz and Petr Viktorin in gh-78502@footnote{https://github.com/python/cpython/issues/78502}.)
@end itemize

@node multiprocessing,os,mmap,Modules améliorés
@anchor{whatsnew/3 13 multiprocessing}@anchor{20b}
@subsubsection `multiprocessing'



@itemize *

@item 
The default number of worker threads and processes is now selected using
@ref{1bf,,os.process_cpu_count()} instead of @ref{1c0,,os.cpu_count()}.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)
@end itemize

@node os,os path,multiprocessing,Modules améliorés
@anchor{whatsnew/3 13 os}@anchor{20c}
@subsubsection `os'



@itemize *

@item 
Add @ref{1bf,,process_cpu_count()} function to get the number
of logical CPU cores usable by the calling thread of the current process.
(Contributed by Victor Stinner in gh-109649@footnote{https://github.com/python/cpython/issues/109649}.)

@item 
@ref{1c0,,cpu_count()} and @ref{1bf,,process_cpu_count()} can be overridden
through the new environment variable 
@geindex PYTHON_CPU_COUNT
@geindex variable d'environnement; PYTHON_CPU_COUNT
@ref{20d,,PYTHON_CPU_COUNT}
or the new command-line option @ref{175,,-X cpu_count}.
This option is useful for users who need to limit CPU resources
of a container system without having to modify application code
or the container itself.
(Contributed by Donghee Na in gh-109595@footnote{https://github.com/python/cpython/issues/109595}.)

@item 
Add a @ref{152,,low level interface} to Linux's
@code{timer file descriptors@footnote{https://manpages.debian.org/timerfd_create(2)}}
via @ref{20e,,timerfd_create()},
@ref{20f,,timerfd_settime()}, @ref{210,,timerfd_settime_ns()},
@ref{211,,timerfd_gettime()}, @ref{212,,timerfd_gettime_ns()},
@ref{213,,TFD_NONBLOCK}, @ref{214,,TFD_CLOEXEC},
@ref{215,,TFD_TIMER_ABSTIME}, and @ref{216,,TFD_TIMER_CANCEL_ON_SET}
(Contributed by Masaru Tsuchiyama in gh-108277@footnote{https://github.com/python/cpython/issues/108277}.)

@item 
@ref{217,,lchmod()} and the `follow_symlinks' argument of @ref{218,,chmod()}
are both now available on Windows.
Note that the default value of `follow_symlinks'
in @code{lchmod()} is @code{False} on Windows.
(Contributed by Serhiy Storchaka in gh-59616@footnote{https://github.com/python/cpython/issues/59616}.)

@item 
@ref{219,,fchmod()} and support for file descriptors in @ref{218,,chmod()}
are both now available on Windows.
(Contributed by Serhiy Storchaka in gh-113191@footnote{https://github.com/python/cpython/issues/113191}.)

@item 
On Windows, @ref{21a,,mkdir()} and @ref{21b,,makedirs()} now support passing
a `mode' value of @code{0o700} to apply access control to the new directory.
This implicitly affects @ref{21c,,tempfile.mkdtemp()}
and is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2024-4030
CVE 2024-4030@footnote{https://www.cve.org/CVERecord?id=CVE-2024-4030}.
Other values for `mode' continue to be ignored.
(Contributed by Steve Dower in gh-118486@footnote{https://github.com/python/cpython/issues/118486}.)

@item 
@ref{21d,,posix_spawn()} now accepts @code{None} for the `env' argument,
which makes the newly spawned process use the current process environment.
(Contributed by Jakub Kulik in gh-113119@footnote{https://github.com/python/cpython/issues/113119}.)

@item 
@ref{21d,,posix_spawn()} can now use the @ref{21e,,POSIX_SPAWN_CLOSEFROM}
attribute in the `file_actions' parameter on platforms that support
@code{posix_spawn_file_actions_addclosefrom_np()}.
(Contributed by Jakub Kulik in gh-113117@footnote{https://github.com/python/cpython/issues/113117}.)
@end itemize

@node os path,pathlib,os,Modules améliorés
@anchor{whatsnew/3 13 os-path}@anchor{21f}
@subsubsection @code{os.path}



@itemize *

@item 
Add @ref{220,,isreserved()} to check if a path is reserved
on the current system.
This function is only available on Windows.
(Contributed by Barney Gale in gh-88569@footnote{https://github.com/python/cpython/issues/88569}.)

@item 
On Windows, @ref{221,,isabs()} no longer considers paths
starting with exactly one slash (@code{\} or @code{/}) to be absolute.
(Contributed by Barney Gale and Jon Foster in gh-44626@footnote{https://github.com/python/cpython/issues/44626}.)

@item 
@ref{222,,realpath()} now resolves MS-DOS style file names
even if the file is not accessible.
(Contributed by Moonsik Park in gh-82367@footnote{https://github.com/python/cpython/issues/82367}.)
@end itemize

@node pathlib,pdb,os path,Modules améliorés
@anchor{whatsnew/3 13 pathlib}@anchor{223}
@subsubsection `pathlib'



@itemize *

@item 
Add @ref{224,,UnsupportedOperation}, which is raised instead of
@ref{225,,NotImplementedError} when a path operation isn't supported.
(Contributed by Barney Gale in gh-89812@footnote{https://github.com/python/cpython/issues/89812}.)

@item 
Add a new constructor for creating @ref{226,,Path} objects
from 'file' URIs (@code{file:///}), @ref{227,,Path.from_uri()}.
(Contributed by Barney Gale in gh-107465@footnote{https://github.com/python/cpython/issues/107465}.)

@item 
Add @ref{228,,PurePath.full_match()} for matching paths with
shell-style wildcards, including the recursive wildcard "@code{**}".
(Contributed by Barney Gale in gh-73435@footnote{https://github.com/python/cpython/issues/73435}.)

@item 
Add the @ref{229,,PurePath.parser} class attribute to store the
implementation of @ref{a1,,os.path} used
for low-level path parsing and joining.
This will be either @code{posixpath} or @code{ntpath}.

@item 
Add `recurse_symlinks' keyword-only argument to
@ref{22a,,Path.glob()} and @ref{22b,,rglob()}.
(Contributed by Barney Gale in gh-77609@footnote{https://github.com/python/cpython/issues/77609}.)

@item 
@ref{22a,,Path.glob()} and @ref{22b,,rglob()}
now return files and directories when given a pattern that ends with "@code{**}".
Previously, only directories were returned.
(Contributed by Barney Gale in gh-70303@footnote{https://github.com/python/cpython/issues/70303}.)

@item 
Add the `follow_symlinks' keyword-only argument to
@ref{22c,,Path.is_file},
@ref{22d,,Path.is_dir},
@ref{22e,,Path.owner()}, and @ref{22f,,Path.group()}.
(Contributed by Barney Gale in gh-105793@footnote{https://github.com/python/cpython/issues/105793} and Kamil Turek in gh-107962@footnote{https://github.com/python/cpython/issues/107962}.)
@end itemize

@node pdb,queue,pathlib,Modules améliorés
@anchor{whatsnew/3 13 pdb}@anchor{230}
@subsubsection `pdb'



@itemize *

@item 
@ref{231,,breakpoint()} and @ref{232,,set_trace()} now enter the debugger immediately
rather than on the next line of code to be executed. This change prevents the
debugger from breaking outside of the context when @code{breakpoint()} is positioned
at the end of the context.
(Contributed by Tian Gao in gh-118579@footnote{https://github.com/python/cpython/issues/118579}.)

@item 
@code{sys.path[0]} is no longer replaced by the directory of the script
being debugged when @ref{233,,sys.flags.safe_path} is set.
(Contributed by Tian Gao and Christian Walther in gh-111762@footnote{https://github.com/python/cpython/issues/111762}.)

@item 
@ref{12f,,zipapp} is now supported as a debugging target.
(Contributed by Tian Gao in gh-118501@footnote{https://github.com/python/cpython/issues/118501}.)

@item 
Add ability to move between chained exceptions during
post-mortem debugging in @ref{234,,pm()} using
the new @ref{235,,exceptions [exc_number]} command for Pdb.
(Contributed by Matthias Bussonnier in gh-106676@footnote{https://github.com/python/cpython/issues/106676}.)

@item 
Expressions and statements whose prefix is a pdb command are now correctly
identified and executed.
(Contributed by Tian Gao in gh-108464@footnote{https://github.com/python/cpython/issues/108464}.)
@end itemize

@node queue,random,pdb,Modules améliorés
@anchor{whatsnew/3 13 queue}@anchor{236}
@subsubsection queue



@itemize *

@item 
Add @ref{237,,Queue.shutdown} and @ref{238,,ShutDown}
to manage queue termination.
(Contributed by Laurie Opperman and Yves Duprat in gh-104750@footnote{https://github.com/python/cpython/issues/104750}.)
@end itemize

@node random,re,queue,Modules améliorés
@anchor{whatsnew/3 13 random}@anchor{239}
@subsubsection `random'



@itemize *

@item 
Add a @ref{153,,command-line interface}.
(Contributed by Hugo van Kemenade in gh-118131@footnote{https://github.com/python/cpython/issues/118131}.)
@end itemize

@node re,shutils,random,Modules améliorés
@anchor{whatsnew/3 13 re}@anchor{23a}
@subsubsection @code{re}



@itemize *

@item 
Rename @code{re.error} to @ref{23b,,PatternError} for improved clarity.
@code{re.error} is kept for backward compatibility.
@end itemize

@node shutils,site,re,Modules améliorés
@anchor{whatsnew/3 13 shutil}@anchor{23c}
@subsubsection @code{shutils}



@itemize *

@item 
Support the `dir_fd' and `follow_symlinks' keyword arguments
in @ref{23d,,chown()}.
(Contributed by Berker Peksag and Tahia K in gh-62308@footnote{https://github.com/python/cpython/issues/62308})
@end itemize

@node site,sqlite3,shutils,Modules améliorés
@anchor{whatsnew/3 13 site}@anchor{23e}
@subsubsection @code{site}



@itemize *

@item 
@code{.pth} files are now decoded using UTF-8 first,
and then with the @ref{23f,,locale encoding} if UTF-8 decoding fails.
(Contributed by Inada Naoki in gh-117802@footnote{https://github.com/python/cpython/issues/117802}.)
@end itemize

@node sqlite3,ssl,site,Modules améliorés
@anchor{whatsnew/3 13 sqlite3}@anchor{240}
@subsubsection @code{sqlite3}



@itemize *

@item 
A @ref{241,,ResourceWarning} is now emitted if a @ref{242,,Connection}
object is not @ref{243,,closed} explicitly.
(Contributed by Erlend E. Aasland in gh-105539@footnote{https://github.com/python/cpython/issues/105539}.)

@item 
Add the `filter' keyword-only parameter to @ref{244,,Connection.iterdump()}
for filtering database objects to dump.
(Contributed by Mariusz Felisiak in gh-91602@footnote{https://github.com/python/cpython/issues/91602}.)
@end itemize

@node ssl,statistics,sqlite3,Modules améliorés
@anchor{whatsnew/3 13 ssl}@anchor{245}
@subsubsection @code{ssl}



@itemize *

@item 
The @ref{154,,create_default_context()} API now includes
@ref{155,,VERIFY_X509_PARTIAL_CHAIN} and @ref{156,,VERIFY_X509_STRICT}
in its default flags.

@cartouche
@quotation Note 
@ref{156,,VERIFY_X509_STRICT} may reject pre-
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}
or malformed certificates that the underlying OpenSSL implementation
might otherwise accept.
Whilst disabling this is not recommended, you can do so using:

@example
import ssl

ctx = ssl.create_default_context()
ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT
@end example
@end quotation
@end cartouche

(Contributed by William Woodruff in gh-112389@footnote{https://github.com/python/cpython/issues/112389}.)
@end itemize

@node statistics,subprocess,ssl,Modules améliorés
@anchor{whatsnew/3 13 statistics}@anchor{246}
@subsubsection @code{statistics}



@itemize *

@item 
Add @ref{247,,kde()} for kernel density estimation.
This makes it possible to estimate a continuous probability density function
from a fixed number of discrete samples.
(Contributed by Raymond Hettinger in gh-115863@footnote{https://github.com/python/cpython/issues/115863}.)

@item 
Add @ref{248,,kde_random()} for sampling from an
estimated probability density function created by @ref{247,,kde()}.
(Contributed by Raymond Hettinger in gh-115863@footnote{https://github.com/python/cpython/issues/115863}.)
@end itemize

@node subprocess,sys,statistics,Modules améliorés
@anchor{whatsnew/3 13 subprocess}@anchor{249}@anchor{whatsnew/3 13 whatsnew313-subprocess}@anchor{24a}
@subsubsection subprocess



@itemize *

@item 
The @ref{d5,,subprocess} module now uses the @ref{21d,,posix_spawn()} function in
more situations.

Notably, when `close_fds' is @code{True} (the default),
@ref{21d,,posix_spawn()} will be used when the C library provides
@code{posix_spawn_file_actions_addclosefrom_np()},
which includes recent versions of Linux, FreeBSD, and Solaris.
On Linux, this should perform similarly to the existing
Linux @code{vfork()} based code.

A private control knob @code{subprocess._USE_POSIX_SPAWN} can
be set to @code{False} if you need to force @ref{d5,,subprocess}
to never use @ref{21d,,posix_spawn()}.
Please report your reason and platform details in
the @ref{24b,,issue tracker} if you set this
so that we can improve our API selection logic for everyone.
(Contributed by Jakub Kulik in gh-113117@footnote{https://github.com/python/cpython/issues/113117}.)
@end itemize

@node sys,tempfile,subprocess,Modules améliorés
@anchor{whatsnew/3 13 sys}@anchor{24c}
@subsubsection `sys'



@itemize *

@item 
Add the @ref{24d,,_is_interned()} function to test if a string was interned.
This function is not guaranteed to exist in all implementations of Python.
(Contributed by Serhiy Storchaka in gh-78573@footnote{https://github.com/python/cpython/issues/78573}.)
@end itemize

@node tempfile,time,sys,Modules améliorés
@anchor{whatsnew/3 13 tempfile}@anchor{24e}
@subsubsection tempfile



@itemize *

@item 
On Windows, the default mode @code{0o700} used by @ref{21c,,tempfile.mkdtemp()} now
limits access to the new directory due to changes to @ref{21a,,os.mkdir()}.
This is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2024-4030
CVE 2024-4030@footnote{https://www.cve.org/CVERecord?id=CVE-2024-4030}.
(Contributed by Steve Dower in gh-118486@footnote{https://github.com/python/cpython/issues/118486}.)
@end itemize

@node time,tkinter,tempfile,Modules améliorés
@anchor{whatsnew/3 13 time}@anchor{24f}
@subsubsection `time'



@itemize *

@item 
On Windows, @ref{250,,monotonic()} now uses the
@code{QueryPerformanceCounter()} clock for a resolution of 1 microsecond,
instead of the @code{GetTickCount64()} clock which has
a resolution of 15.6 milliseconds.
(Contributed by Victor Stinner in gh-88494@footnote{https://github.com/python/cpython/issues/88494}.)

@item 
On Windows, @ref{251,,time()} now uses the
@code{GetSystemTimePreciseAsFileTime()} clock for a resolution of 1 microsecond,
instead of the @code{GetSystemTimeAsFileTime()} clock which has
a resolution of 15.6 milliseconds.
(Contributed by Victor Stinner in gh-63207@footnote{https://github.com/python/cpython/issues/63207}.)
@end itemize

@node tkinter,traceback,time,Modules améliorés
@anchor{whatsnew/3 13 tkinter}@anchor{252}
@subsubsection tkinter



@itemize *

@item 
Add @ref{ef,,tkinter} widget methods:
@code{tk_busy_hold()}, @code{tk_busy_configure()},
@code{tk_busy_cget()}, @code{tk_busy_forget()},
@code{tk_busy_current()}, and @code{tk_busy_status()}.
(Contributed by Miguel, klappnase and Serhiy Storchaka in gh-72684@footnote{https://github.com/python/cpython/issues/72684}.)

@item 
The @ref{ef,,tkinter} widget method @code{wm_attributes()} now accepts
the attribute name without the minus prefix to get window attributes,
for example @code{w.wm_attributes('alpha')}
and allows specifying attributes and values to set as keyword arguments,
for example @code{w.wm_attributes(alpha=0.5)}.
(Contributed by Serhiy Storchaka in gh-43457@footnote{https://github.com/python/cpython/issues/43457}.)

@item 
@code{wm_attributes()} can now return attributes as a @ref{253,,dict},
by using the new optional keyword-only parameter `return_python_dict'.
(Contributed by Serhiy Storchaka in gh-43457@footnote{https://github.com/python/cpython/issues/43457}.)

@item 
@code{Text.count()} can now return a simple @ref{254,,int}
when the new optional keyword-only parameter `return_ints' is used.
Otherwise, the single count is returned as a 1-tuple or @code{None}.
(Contributed by Serhiy Storchaka in gh-97928@footnote{https://github.com/python/cpython/issues/97928}.)

@item 
Support the "vsapi" element type in
the @ref{255,,element_create()} method of
@ref{256,,tkinter.ttk.Style}.
(Contributed by Serhiy Storchaka in gh-68166@footnote{https://github.com/python/cpython/issues/68166}.)

@item 
Add the @code{after_info()} method for Tkinter widgets.
(Contributed by Cheryl Sabella in gh-77020@footnote{https://github.com/python/cpython/issues/77020}.)

@item 
Add a new @code{copy_replace()} method to @code{PhotoImage}
to copy a region from one image to another,
possibly with pixel zooming, subsampling, or both.
(Contributed by Serhiy Storchaka in gh-118225@footnote{https://github.com/python/cpython/issues/118225}.)

@item 
Add `from_coords' parameter to the @code{PhotoImage} methods
@code{copy()}, @code{zoom()} and @code{subsample()}.
Add `zoom' and `subsample' parameters to the @code{PhotoImage} method
@code{copy()}.
(Contributed by Serhiy Storchaka in gh-118225@footnote{https://github.com/python/cpython/issues/118225}.)

@item 
Add the @code{PhotoImage} methods
@code{read()} to read an image from a file
and @code{data()} to get the image data.
Add `background' and `grayscale' parameters to the @code{write()} method.
(Contributed by Serhiy Storchaka in gh-118271@footnote{https://github.com/python/cpython/issues/118271}.)
@end itemize

@node traceback,types,tkinter,Modules améliorés
@anchor{whatsnew/3 13 traceback}@anchor{257}
@subsubsection traceback



@itemize *

@item 
Add the @ref{258,,exc_type_str} attribute
to @ref{259,,TracebackException},
which holds a string display of the `exc_type'.
Deprecate the @ref{25a,,exc_type} attribute,
which holds the type object itself.
Add parameter `save_exc_type' (default @code{True})
to indicate whether @code{exc_type} should be saved.
(Contributed by Irit Katriel in gh-112332@footnote{https://github.com/python/cpython/issues/112332}.)

@item 
Add a new `show_group' keyword-only parameter to
@ref{25b,,TracebackException.format_exception_only()} to (recursively) format
the nested exceptions of a @ref{25c,,BaseExceptionGroup} instance.
(Contributed by Irit Katriel in gh-105292@footnote{https://github.com/python/cpython/issues/105292}.)
@end itemize

@node types,typing,traceback,Modules améliorés
@anchor{whatsnew/3 13 types}@anchor{25d}
@subsubsection @code{types}



@itemize *

@item 
@ref{1cc,,SimpleNamespace} can now take a single positional argument
to initialise the namespace's arguments.
This argument must either be a mapping or an iterable of key-value pairs.
(Contributed by Serhiy Storchaka in gh-108191@footnote{https://github.com/python/cpython/issues/108191}.)
@end itemize

@node typing,unicodedata,types,Modules améliorés
@anchor{whatsnew/3 13 typing}@anchor{25e}
@subsubsection `typing'



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/}: Add @ref{160,,ReadOnly}, a special typing construct
to mark a @ref{161,,TypedDict} item as read-only for type checkers.

@item 
@geindex Python Enhancement Proposals; PEP 742
PEP 742@footnote{https://peps.python.org/pep-0742/}: Add @ref{162,,TypeIs}, a typing construct
that can be used to instruct a type checker how to narrow a type.

@item 
Add @ref{25f,,NoDefault}, a sentinel object used to represent
the defaults of some parameters in the @ref{103,,typing} module.
(Contributed by Jelle Zijlstra in gh-116126@footnote{https://github.com/python/cpython/issues/116126}.)

@item 
Add @ref{260,,get_protocol_members()} to return the set of members
defining a @ref{261,,typing.Protocol}.
(Contributed by Jelle Zijlstra in gh-104873@footnote{https://github.com/python/cpython/issues/104873}.)

@item 
Add @ref{262,,is_protocol()} to check whether a class
is a @ref{261,,Protocol}.
(Contributed by Jelle Zijlstra in gh-104873@footnote{https://github.com/python/cpython/issues/104873}.)

@item 
@ref{263,,ClassVar} can now be nested in @ref{264,,Final},
and vice versa.
(Contributed by Mehdi Drissi in gh-89547@footnote{https://github.com/python/cpython/issues/89547}.)
@end itemize

@node unicodedata,venv,typing,Modules améliorés
@anchor{whatsnew/3 13 unicodedata}@anchor{265}
@subsubsection `unicodedata'



@itemize *

@item 
Update the Unicode database to version 15.1.0@footnote{https://www.unicode.org/versions/Unicode15.1.0/}.
(Contributed by James Gerity in gh-109559@footnote{https://github.com/python/cpython/issues/109559}.)
@end itemize

@node venv,warnings,unicodedata,Modules améliorés
@anchor{whatsnew/3 13 venv}@anchor{266}
@subsubsection `venv'



@itemize *

@item 
Add support for creating source control management (SCM) ignore files
in a virtual environment's directory.
By default, Git is supported.
This is implemented as opt-in via the API,
which can be extended to support other SCMs
(@ref{267,,EnvBuilder} and @ref{268,,create()}),
and opt-out via the CLI, using @code{--without-scm-ignore-files}.
(Contributed by Brett Cannon in gh-108125@footnote{https://github.com/python/cpython/issues/108125}.)
@end itemize

@node warnings,xml,venv,Modules améliorés
@anchor{whatsnew/3 13 warnings}@anchor{269}
@subsubsection warnings



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}: The new @ref{15f,,warnings.deprecated()} decorator provides a way to
communicate deprecations to a @ref{26a,,static type checker}
and to warn on usage of deprecated classes and functions.
A @ref{1a3,,DeprecationWarning} may also be emitted when
a decorated function or class is used at runtime.
(Contributed by Jelle Zijlstra in gh-104003@footnote{https://github.com/python/cpython/issues/104003}.)
@end itemize

@node xml,zipimport,warnings,Modules améliorés
@anchor{whatsnew/3 13 xml}@anchor{26b}
@subsubsection `xml'



@itemize *

@item 
Allow controlling Expat >=2.6.0 reparse deferral (
@geindex Common Vulnerabilities and Exposures; CVE 2023-52425
CVE 2023-52425@footnote{https://www.cve.org/CVERecord?id=CVE-2023-52425})
by adding five new methods:


@itemize *

@item 
@ref{26c,,xml.etree.ElementTree.XMLParser.flush()}

@item 
@ref{26d,,xml.etree.ElementTree.XMLPullParser.flush()}

@item 
@ref{26e,,xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()}

@item 
@ref{26f,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()}

@item 
@code{xml.sax.expatreader.ExpatParser.flush()}
@end itemize

(Contributed by Sebastian Pipping in gh-115623@footnote{https://github.com/python/cpython/issues/115623}.)

@item 
Add the @code{close()} method for the iterator returned by
@ref{270,,iterparse()} for explicit cleanup.
(Contributed by Serhiy Storchaka in gh-69893@footnote{https://github.com/python/cpython/issues/69893}.)
@end itemize

@node zipimport,,xml,Modules améliorés
@anchor{whatsnew/3 13 zipimport}@anchor{271}
@subsubsection @code{zipimport}



@itemize *

@item 
Add support for ZIP64@footnote{https://en.wikipedia.org/wiki/Zip_(file_format)#ZIP64} format files.
Everybody loves huge data, right?
(Contributed by Tim Hatch in gh-94146@footnote{https://github.com/python/cpython/issues/94146}.)
@end itemize

@node Optimisations,Removed Modules And APIs,Modules améliorés,What's New In Python 3 13
@anchor{whatsnew/3 13 optimizations}@anchor{272}
@subsection Optimisations



@itemize *

@item 
Several standard library modules have had
their import times significantly improved.
For example, the import time of the @ref{103,,typing} module
has been reduced by around a third by removing dependencies
on @ref{b8,,re} and @ref{23,,contextlib}.
Other modules to enjoy import-time speedups include
@ref{50,,email.utils}, @ref{55,,enum}, @ref{5e,,functools},
@ref{79,,importlib.metadata}, and @ref{ec,,threading}.
(Contributed by Alex Waygood, Shantanu Jain, Adam Turner, Daniel Hollas,
and others in gh-109653@footnote{https://github.com/python/cpython/issues/109653}.)

@item 
@ref{273,,textwrap.indent()} is now around 30% faster than before for large input.
(Contributed by Inada Naoki in gh-107369@footnote{https://github.com/python/cpython/issues/107369}.)

@item 
The @ref{d5,,subprocess} module now uses the @ref{21d,,posix_spawn()} function in
more situations, including when `close_fds' is @code{True} (the default)
on many modern platforms.
This should provide a notable performance increase
when launching processes on FreeBSD and Solaris.
See the @ref{24a,,subprocess} section above for details.
(Contributed by Jakub Kulik in gh-113117@footnote{https://github.com/python/cpython/issues/113117}.)
@end itemize

@node Removed Modules And APIs,New Deprecations,Optimisations,What's New In Python 3 13
@anchor{whatsnew/3 13 removed-modules-and-apis}@anchor{274}
@subsection Removed Modules And APIs


@menu
* PEP 594; Remove "dead batteries" from the standard library: PEP 594 Remove "dead batteries" from the standard library. 
* 2to3:: 
* builtins:: 
* configparser: configparser<2>. 
* importlib.metadata: importlib metadata. 
* locale:: 
* opcode:: 
* optparse:: 
* pathlib: pathlib<2>. 
* re: re<2>. 
* tkinter.tix: tkinter tix. 
* turtle:: 
* typing: typing<2>. 
* unittest:: 
* urllib:: 
* webbrowser:: 

@end menu

@node PEP 594 Remove "dead batteries" from the standard library,2to3,,Removed Modules And APIs
@anchor{whatsnew/3 13 pep-594-remove-dead-batteries-from-the-standard-library}@anchor{275}
@subsubsection PEP 594: Remove "dead batteries" from the standard library


@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} proposed removing 19 modules from the standard library,
colloquially referred to as 'dead batteries' due to their
historic, obsolete, or insecure status.
All of the following modules were deprecated in Python 3.11,
and are now removed:


@itemize *

@item 
@code{aifc}

@item 
@code{audioop}

@item 
@code{chunk}

@item 
@code{cgi} and @code{cgitb}


@itemize *

@item 
@code{cgi.FieldStorage} can typically be replaced with
@ref{276,,urllib.parse.parse_qsl()} for @code{GET} and @code{HEAD} requests,
and the @ref{44,,email.message} module or the multipart@footnote{https://pypi.org/project/multipart/} library
for @code{POST} and @code{PUT} requests.

@item 
@code{cgi.parse()} can be replaced by calling
@ref{277,,urllib.parse.parse_qs()} directly on the desired query string,
unless the input is @code{multipart/form-data},
which should be replaced as described below for @code{cgi.parse_multipart()}.

@item 
@code{cgi.parse_header()} can be replaced with the functionality
in the @ref{3b,,email} package, which implements the same MIME RFCs.
For example, with @ref{278,,email.message.EmailMessage}:

@example
from email.message import EmailMessage

msg = EmailMessage()
msg['content-type'] = 'application/json; charset="utf8"'
main, params = msg.get_content_type(), msg['content-type'].params
@end example

@item 
@code{cgi.parse_multipart()} can be replaced with the functionality
in the @ref{3b,,email} package, which implements the same MIME RFCs,
or with the multipart@footnote{https://pypi.org/project/multipart/} library.
For example, the @ref{278,,email.message.EmailMessage}
and @ref{279,,email.message.Message} classes.
@end itemize

@item 
@code{crypt} and the private @code{_crypt} extension.
The @ref{67,,hashlib} module may be an appropriate replacement
when simply hashing a value is required.
Otherwise, various third-party libraries on PyPI are available:


@itemize *

@item 
bcrypt@footnote{https://pypi.org/project/bcrypt/}:
Modern password hashing for your software and your servers.

@item 
passlib@footnote{https://pypi.org/project/passlib/}:
Comprehensive password hashing framework supporting over 30 schemes.

@item 
argon2-cffi@footnote{https://pypi.org/project/argon2-cffi/}:
The secure Argon2 password hashing algorithm.

@item 
legacycrypt@footnote{https://pypi.org/project/legacycrypt/}:
@ref{2a,,ctypes} wrapper to the POSIX crypt library call
and associated functionality.

@item 
crypt_r@footnote{https://pypi.org/project/crypt_r/}:
Fork of the @code{crypt} module,
wrapper to the @code{crypt_r(3)@footnote{https://manpages.debian.org/crypt_r(3)}} library call
and associated functionality.
@end itemize

@item 
@code{imghdr}:
The filetype@footnote{https://pypi.org/project/filetype/}, puremagic@footnote{https://pypi.org/project/puremagic/}, or python-magic@footnote{https://pypi.org/project/python-magic/} libraries
should be used as replacements.
For example, the @code{puremagic.what()} function can be used
to replace the @code{imghdr.what()} function for all file formats
that were supported by @code{imghdr}.

@item 
@code{mailcap}:
Use the @ref{8e,,mimetypes} module instead.

@item 
@code{msilib}

@item 
@code{nis}

@item 
@code{nntplib}:
Use the pynntp@footnote{https://pypi.org/project/pynntp/} library from PyPI instead.

@item 
@code{ossaudiodev}:
For audio playback, use the pygame@footnote{https://pypi.org/project/pygame/} library from PyPI instead.

@item 
@code{pipes}:
Use the @ref{d5,,subprocess} module instead.
Use @ref{27a,,shlex.quote()} to replace the undocumented @code{pipes.quote}
function.

@item 
@code{sndhdr}:
The filetype@footnote{https://pypi.org/project/filetype/}, puremagic@footnote{https://pypi.org/project/puremagic/}, or python-magic@footnote{https://pypi.org/project/python-magic/} libraries
should be used as replacements.

@item 
@code{spwd}:
Use the python-pam@footnote{https://pypi.org/project/python-pam/} library from PyPI instead.

@item 
@code{sunau}

@item 
@code{telnetlib},
Use the telnetlib3@footnote{https://pypi.org/project/telnetlib3/} or Exscript@footnote{https://pypi.org/project/Exscript/} libraries from PyPI instead.

@item 
@code{uu}:
Use the @ref{e,,base64} module instead, as a modern alternative.

@item 
@code{xdrlib}
@end itemize

(Contributed by Victor Stinner and Zachary Ware in gh-104773@footnote{https://github.com/python/cpython/issues/104773} and gh-104780@footnote{https://github.com/python/cpython/issues/104780}.)

@node 2to3,builtins,PEP 594 Remove "dead batteries" from the standard library,Removed Modules And APIs
@anchor{whatsnew/3 13 to3}@anchor{27b}
@subsubsection 2to3



@itemize *

@item 
Remove the @code{2to3} program and the @code{lib2to3} module,
previously deprecated in Python 3.11.
(Contributed by Victor Stinner in gh-104780@footnote{https://github.com/python/cpython/issues/104780}.)
@end itemize

@node builtins,configparser<2>,2to3,Removed Modules And APIs
@anchor{whatsnew/3 13 builtins}@anchor{27c}
@subsubsection builtins



@itemize *

@item 
Remove support for chained @ref{165,,classmethod} descriptors
(introduced in gh-63272@footnote{https://github.com/python/cpython/issues/63272}).
These can no longer be used to wrap other descriptors,
such as @ref{192,,property}.
The core design of this feature was flawed and led to several problems.
To "pass-through" a @ref{165,,classmethod}, consider using
the @code{__wrapped__} attribute that was added in Python 3.10.
(Contributed by Raymond Hettinger in gh-89519@footnote{https://github.com/python/cpython/issues/89519}.)

@item 
Raise a @ref{193,,RuntimeError} when calling @ref{27d,,frame.clear()}
on a suspended frame (as has always been the case for an executing frame).
(Contributed by Irit Katriel in gh-79932@footnote{https://github.com/python/cpython/issues/79932}.)
@end itemize

@node configparser<2>,importlib metadata,builtins,Removed Modules And APIs
@anchor{whatsnew/3 13 id3}@anchor{27e}
@subsubsection configparser



@itemize *

@item 
Remove the undocumented @code{LegacyInterpolation} class,
deprecated in the docstring since Python 3.2,
and at runtime since Python 3.11.
(Contributed by Hugo van Kemenade in gh-104886@footnote{https://github.com/python/cpython/issues/104886}.)
@end itemize

@node importlib metadata,locale,configparser<2>,Removed Modules And APIs
@anchor{whatsnew/3 13 importlib-metadata}@anchor{27f}
@subsubsection @code{importlib.metadata}



@itemize *

@item 
Remove deprecated subscript (@ref{280,,__getitem__()}) access for
@ref{281,,EntryPoint} objects.
(Contributed by Jason R. Coombs in gh-113175@footnote{https://github.com/python/cpython/issues/113175}.)
@end itemize

@node locale,opcode,importlib metadata,Removed Modules And APIs
@anchor{whatsnew/3 13 locale}@anchor{282}
@subsubsection locale



@itemize *

@item 
Remove the @code{locale.resetlocale()} function, deprecated in Python 3.11.
Use @code{locale.setlocale(locale.LC_ALL, "")} instead.
(Contributed by Victor Stinner in gh-104783@footnote{https://github.com/python/cpython/issues/104783}.)
@end itemize

@node opcode,optparse,locale,Removed Modules And APIs
@anchor{whatsnew/3 13 opcode}@anchor{283}
@subsubsection opcode



@itemize *

@item 
Move @code{opcode.ENABLE_SPECIALIZATION} to @code{_opcode.ENABLE_SPECIALIZATION}.
This field was added in 3.12, it was never documented,
and is not intended for external use.
(Contributed by Irit Katriel in gh-105481@footnote{https://github.com/python/cpython/issues/105481}.)

@item 
Remove @code{opcode.is_pseudo()}, @code{opcode.MIN_PSEUDO_OPCODE},
and @code{opcode.MAX_PSEUDO_OPCODE}, which were added in Python 3.12,
but were neither documented nor exposed through @ref{38,,dis},
and were not intended to be used externally.
(Contributed by Irit Katriel in gh-105481@footnote{https://github.com/python/cpython/issues/105481}.)
@end itemize

@node optparse,pathlib<2>,opcode,Removed Modules And APIs
@anchor{whatsnew/3 13 optparse}@anchor{284}
@subsubsection optparse



@itemize *

@item 
This module is no longer considered @ref{206,,soft deprecated}.
While @ref{6,,argparse} remains preferred for new projects that
aren't using a third party command line argument processing
library, there are aspects of the way @code{argparse} works that
mean the lower level @code{optparse} module may provide a better
foundation for `writing' argument processing libraries, and
for implementing command line applications which adhere more
strictly than @code{argparse} does to various Unix command line
processing conventions that originate in the behaviour of the
C @code{getopt()} function .
(Contributed by Alyssa Coghlan and Serhiy Storchaka in gh-126180@footnote{https://github.com/python/cpython/issues/126180}.)
@end itemize

@node pathlib<2>,re<2>,optparse,Removed Modules And APIs
@anchor{whatsnew/3 13 id4}@anchor{285}
@subsubsection `pathlib'



@itemize *

@item 
Remove the ability to use @ref{226,,Path} objects as context managers.
This functionality was deprecated and has had no effect since Python 3.9.
(Contributed by Barney Gale in gh-83863@footnote{https://github.com/python/cpython/issues/83863}.)
@end itemize

@node re<2>,tkinter tix,pathlib<2>,Removed Modules And APIs
@anchor{whatsnew/3 13 id5}@anchor{286}
@subsubsection @code{re}



@itemize *

@item 
Remove the undocumented, deprecated, and broken
@code{re.template()} function and @code{re.TEMPLATE} / @code{re.T} flag.
(Contributed by Serhiy Storchaka and Nikita Sobolev in gh-105687@footnote{https://github.com/python/cpython/issues/105687}.)
@end itemize

@node tkinter tix,turtle,re<2>,Removed Modules And APIs
@anchor{whatsnew/3 13 tkinter-tix}@anchor{287}
@subsubsection tkinter.tix



@itemize *

@item 
Remove the @code{tkinter.tix} module, deprecated in Python 3.6.
The third-party Tix library which the module wrapped is unmaintained.
(Contributed by Zachary Ware in gh-75552@footnote{https://github.com/python/cpython/issues/75552}.)
@end itemize

@node turtle,typing<2>,tkinter tix,Removed Modules And APIs
@anchor{whatsnew/3 13 turtle}@anchor{288}
@subsubsection turtle



@itemize *

@item 
Remove the @code{RawTurtle.settiltangle()} method,
deprecated in the documentation since Python 3.1
and at runtime since Python 3.11.
(Contributed by Hugo van Kemenade in gh-104876@footnote{https://github.com/python/cpython/issues/104876}.)
@end itemize

@node typing<2>,unittest,turtle,Removed Modules And APIs
@anchor{whatsnew/3 13 id6}@anchor{289}
@subsubsection `typing'



@itemize *

@item 
Remove the @code{typing.io} and @code{typing.re} namespaces,
deprecated since Python 3.8.
The items in those namespaces can be imported directly
from the @ref{103,,typing} module.
(Contributed by Sebastian Rittau in gh-92871@footnote{https://github.com/python/cpython/issues/92871}.)

@item 
Remove the keyword-argument method of creating
@ref{161,,TypedDict} types, deprecated in Python 3.11.
(Contributed by Tomas Roun in gh-104786@footnote{https://github.com/python/cpython/issues/104786}.)
@end itemize

@node unittest,urllib,typing<2>,Removed Modules And APIs
@anchor{whatsnew/3 13 unittest}@anchor{28a}
@subsubsection unittest



@itemize *

@item 
Remove the following @ref{105,,unittest} functions, deprecated in Python 3.11:


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

Use @ref{28b,,TestLoader} methods instead:


@itemize *

@item 
@ref{28c,,loadTestsFromModule()}

@item 
@ref{28d,,loadTestsFromTestCase()}

@item 
@ref{28e,,getTestCaseNames()}
@end itemize

(Contributed by Hugo van Kemenade in gh-104835@footnote{https://github.com/python/cpython/issues/104835}.)

@item 
Remove the untested and undocumented @code{TestProgram.usageExit()}
method, deprecated in Python 3.11.
(Contributed by Hugo van Kemenade in gh-104992@footnote{https://github.com/python/cpython/issues/104992}.)
@end itemize

@node urllib,webbrowser,unittest,Removed Modules And APIs
@anchor{whatsnew/3 13 urllib}@anchor{28f}
@subsubsection urllib



@itemize *

@item 
Remove the `cafile', `capath', and `cadefault' parameters of the
@ref{290,,urllib.request.urlopen()} function, deprecated in Python 3.6.
Use the `context' parameter instead with an @ref{291,,SSLContext} instance.
The @ref{292,,ssl.SSLContext.load_cert_chain()} function
can be used to load specific certificates,
or let @ref{154,,ssl.create_default_context()} select
the operating system's trusted certificate authority (CA) certificates.
(Contributed by Victor Stinner in gh-105382@footnote{https://github.com/python/cpython/issues/105382}.)
@end itemize

@node webbrowser,,urllib,Removed Modules And APIs
@anchor{whatsnew/3 13 webbrowser}@anchor{293}
@subsubsection webbrowser



@itemize *

@item 
Remove the untested and undocumented @code{MacOSX} class,
deprecated in Python 3.11.
Use the @code{MacOSXOSAScript} class (introduced in Python 3.2) instead.
(Contributed by Hugo van Kemenade in gh-104804@footnote{https://github.com/python/cpython/issues/104804}.)

@item 
Remove the deprecated @code{MacOSXOSAScript._name} attribute.
Use the @ref{294,,MacOSXOSAScript.name}
attribute instead.
(Contributed by Nikita Sobolev in gh-105546@footnote{https://github.com/python/cpython/issues/105546}.)
@end itemize

@node New Deprecations,CPython Bytecode Changes,Removed Modules And APIs,What's New In Python 3 13
@anchor{whatsnew/3 13 new-deprecations}@anchor{295}
@subsection New Deprecations



@itemize *

@item 
@ref{296,,User-defined functions}:


@itemize *

@item 
Deprecate assignment to a function's @ref{297,,__code__} attribute,
where the new code object's type does not match the function's type.
The different types are:
plain function, generator, async generator, and coroutine.
(Contributed by Irit Katriel in gh-81137@footnote{https://github.com/python/cpython/issues/81137}.)
@end itemize

@item 
@ref{7,,array}:


@itemize *

@item 
Deprecate the @code{'u'} format code (@code{wchar_t}) at runtime.
This format code has been deprecated in documentation since Python 3.3,
and will be removed in Python 3.16.
Use the @code{'w'} format code (@ref{298,,Py_UCS4})
for Unicode characters instead.
(Contributed by Hugo van Kemenade in gh-80480@footnote{https://github.com/python/cpython/issues/80480}.)
@end itemize

@item 
@ref{2a,,ctypes}:


@itemize *

@item 
Deprecate the undocumented @code{SetPointerType()} function,
to be removed in Python 3.15.
(Contributed by Victor Stinner in gh-105733@footnote{https://github.com/python/cpython/issues/105733}.)

@item 
@ref{206,,Soft-deprecate} the @ref{299,,ARRAY()}
function in favour of @code{type * length} multiplication.
(Contributed by Victor Stinner in gh-105733@footnote{https://github.com/python/cpython/issues/105733}.)
@end itemize

@item 
@ref{36,,decimal}:


@itemize *

@item 
Deprecate the non-standard and undocumented @ref{29a,,Decimal}
format specifier @code{'N'},
which is only supported in the @code{decimal} module's C implementation.
(Contributed by Serhiy Storchaka in gh-89902@footnote{https://github.com/python/cpython/issues/89902}.)
@end itemize

@item 
@ref{38,,dis}:


@itemize *

@item 
Deprecate the @code{HAVE_ARGUMENT} separator.
Check membership in @ref{29b,,hasarg} instead.
(Contributed by Irit Katriel in gh-109319@footnote{https://github.com/python/cpython/issues/109319}.)
@end itemize

@item 
@ref{62,,gettext}:


@itemize *

@item 
Deprecate non-integer numbers as arguments to functions and methods
that consider plural forms in the @code{gettext} module,
even if no translation was found.
(Contributed by Serhiy Storchaka in gh-88434@footnote{https://github.com/python/cpython/issues/88434}.)
@end itemize

@item 
@ref{63,,glob}:


@itemize *

@item 
Deprecate the undocumented @code{glob0()} and @code{glob1()} functions.
Use @ref{29c,,glob()} and pass a @ref{29d,,path-like object} specifying
the root directory to the `root_dir' parameter instead.
(Contributed by Barney Gale in gh-117337@footnote{https://github.com/python/cpython/issues/117337}.)
@end itemize

@item 
@ref{71,,http.server}:


@itemize *

@item 
Deprecate @ref{29e,,CGIHTTPRequestHandler},
to be removed in Python 3.15.
Process-based CGI HTTP servers have been out of favor for a very long time.
This code was outdated, unmaintained, and rarely used.
It has a high potential for both security and functionality bugs.
(Contributed by Gregory P. Smith in gh-109096@footnote{https://github.com/python/cpython/issues/109096}.)

@item 
Deprecate the @code{--cgi} flag to
the @code{python -m http.server} command-line interface,
to be removed in Python 3.15.
(Contributed by Gregory P. Smith in gh-109096@footnote{https://github.com/python/cpython/issues/109096}.)
@end itemize

@item 
@ref{8e,,mimetypes}:


@itemize *

@item 
@ref{206,,Soft-deprecate} file path arguments
to @ref{205,,guess_type()},
use @ref{204,,guess_file_type()} instead.
(Contributed by Serhiy Storchaka in gh-66543@footnote{https://github.com/python/cpython/issues/66543}.)
@end itemize

@item 
@ref{b8,,re}:


@itemize *

@item 
Deprecate passing the optional `maxsplit', `count', or `flags' arguments
as positional arguments to the module-level
@ref{29f,,split()}, @ref{2a0,,sub()}, and @ref{2a1,,subn()} functions.
These parameters will become @ref{2a2,,keyword-only}
in a future version of Python.
(Contributed by Serhiy Storchaka in gh-56166@footnote{https://github.com/python/cpython/issues/56166}.)
@end itemize

@item 
@ref{a3,,pathlib}:


@itemize *

@item 
Deprecate @ref{2a3,,PurePath.is_reserved()},
to be removed in Python 3.15.
Use @ref{220,,os.path.isreserved()} to detect reserved paths on Windows.
(Contributed by Barney Gale in gh-88569@footnote{https://github.com/python/cpython/issues/88569}.)
@end itemize

@item 
@ref{a9,,platform}:


@itemize *

@item 
Deprecate @ref{2a4,,java_ver()},
to be removed in Python 3.15.
This function is only useful for Jython support, has a confusing API,
and is largely untested.
(Contributed by Nikita Sobolev in gh-116349@footnote{https://github.com/python/cpython/issues/116349}.)
@end itemize

@item 
@ref{b4,,pydoc}:


@itemize *

@item 
Deprecate the undocumented @code{ispackage()} function.
(Contributed by Zackery Spytz in gh-64020@footnote{https://github.com/python/cpython/issues/64020}.)
@end itemize

@item 
@ref{ce,,sqlite3}:


@itemize *

@item 
Deprecate passing more than one positional argument to
the @ref{2a5,,connect()} function
and the @ref{242,,Connection} constructor.
The remaining parameters will become keyword-only in Python 3.15.
(Contributed by Erlend E. Aasland in gh-107948@footnote{https://github.com/python/cpython/issues/107948}.)

@item 
Deprecate passing name, number of arguments, and the callable as keyword
arguments for @ref{2a6,,Connection.create_function()}
and @ref{2a7,,Connection.create_aggregate()}
These parameters will become positional-only in Python 3.15.
(Contributed by Erlend E. Aasland in gh-108278@footnote{https://github.com/python/cpython/issues/108278}.)

@item 
Deprecate passing the callback callable by keyword for the
@ref{2a8,,set_authorizer()},
@ref{2a9,,set_progress_handler()}, and
@ref{2aa,,set_trace_callback()}
@ref{242,,Connection} methods.
The callback callables will become positional-only in Python 3.15.
(Contributed by Erlend E. Aasland in gh-108278@footnote{https://github.com/python/cpython/issues/108278}.)
@end itemize

@item 
@ref{d8,,sys}:


@itemize *

@item 
Deprecate the @ref{2ab,,_enablelegacywindowsfsencoding()} function,
to be removed in Python 3.16.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
(Contributed by Inada Naoki in gh-73427@footnote{https://github.com/python/cpython/issues/73427}.)
@end itemize

@item 
@ref{dd,,tarfile}:


@itemize *

@item 
Deprecate the undocumented and unused @code{TarFile.tarfile} attribute,
to be removed in Python 3.16.
(Contributed in gh-115256@footnote{https://github.com/python/cpython/issues/115256}.)
@end itemize

@item 
@ref{fd,,traceback}:


@itemize *

@item 
Deprecate the @ref{25a,,TracebackException.exc_type} attribute.
Use @ref{258,,TracebackException.exc_type_str} instead.
(Contributed by Irit Katriel in gh-112332@footnote{https://github.com/python/cpython/issues/112332}.)
@end itemize

@item 
@ref{103,,typing}:


@itemize *

@item 
Deprecate the undocumented keyword argument syntax for creating
@ref{2ad,,NamedTuple} classes
(e.g. @code{Point = NamedTuple("Point", x=int, y=int)}),
to be removed in Python 3.15.
Use the class-based syntax or the functional syntax instead.
(Contributed by Alex Waygood in gh-105566@footnote{https://github.com/python/cpython/issues/105566}.)

@item 
Deprecate omitting the `fields' parameter when creating
a @ref{2ad,,NamedTuple} or @ref{161,,typing.TypedDict} class,
and deprecate passing @code{None} to the `fields' parameter of both types.
Python 3.15 will require a valid sequence for the `fields' parameter.
To create a NamedTuple class with zero fields,
use @code{class NT(NamedTuple): pass} or @code{NT = NamedTuple("NT", ())}.
To create a TypedDict class with zero fields,
use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}.
(Contributed by Alex Waygood in gh-105566@footnote{https://github.com/python/cpython/issues/105566} and gh-105570@footnote{https://github.com/python/cpython/issues/105570}.)

@item 
Deprecate the @ref{2ae,,typing.no_type_check_decorator()} decorator function,
to be removed in in Python 3.15.
After eight years in the @ref{103,,typing} module,
it has yet to be supported by any major type checker.
(Contributed by Alex Waygood in gh-106309@footnote{https://github.com/python/cpython/issues/106309}.)

@item 
Deprecate @ref{2af,,typing.AnyStr}.
In Python 3.16, it will be removed from @code{typing.__all__},
and a @ref{1a3,,DeprecationWarning} will be emitted at runtime
when it is imported or accessed.
It will be removed entirely in Python 3.18.
Use the new @ref{2b0,,type parameter syntax} instead.
(Contributed by Michael The in gh-107116@footnote{https://github.com/python/cpython/issues/107116}.)
@end itemize

@item 
@ref{112,,wave}:


@itemize *

@item 
Deprecate the @ref{2b1,,getmark()}, @code{setmark()},
and @ref{2b2,,getmarkers()} methods of
the @ref{2b3,,Wave_read} and @ref{2b4,,Wave_write} classes,
to be removed in Python 3.15.
(Contributed by Victor Stinner in gh-105096@footnote{https://github.com/python/cpython/issues/105096}.)
@end itemize
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@menu
* Pending Removal in Python 3.14: Pending Removal in Python 3 14. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15. 
* Pending removal in Python 3.16: Pending removal in Python 3 16. 
* Pending Removal in Future Versions:: 

@end menu

@node Pending Removal in Python 3 14,Pending Removal in Python 3 15,,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-14}@anchor{2b5}
@subsubsection Pending Removal in Python 3.14



@itemize *

@item 
@ref{6,,argparse}: The `type', `choices', and `metavar' parameters
of @code{argparse.BooleanOptionalAction} are deprecated
and will be removed in 3.14.
(Contributed by Nikita Sobolev in gh-92248@footnote{https://github.com/python/cpython/issues/92248}.)

@item 
@ref{8,,ast}: The following features have been deprecated in documentation
since Python 3.8, now cause a @ref{1a3,,DeprecationWarning} to be emitted at
runtime when they are accessed or used, and will be removed in Python 3.14:


@itemize *

@item 
@code{ast.Num}

@item 
@code{ast.Str}

@item 
@code{ast.Bytes}

@item 
@code{ast.NameConstant}

@item 
@code{ast.Ellipsis}
@end itemize

Use @ref{2b6,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{a,,asyncio}:


@itemize *

@item 
The child watcher classes @ref{2b7,,MultiLoopChildWatcher},
@ref{2b8,,FastChildWatcher}, @ref{2b9,,AbstractChildWatcher}
and @ref{2ba,,SafeChildWatcher} are deprecated and
will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
@ref{2bb,,asyncio.set_child_watcher()}, @ref{2bc,,asyncio.get_child_watcher()},
@ref{2bd,,asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@ref{2be,,asyncio.AbstractEventLoopPolicy.get_child_watcher()} are deprecated
and will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
The @ref{2bf,,get_event_loop()} method of the
default event loop policy now emits a @ref{1a3,,DeprecationWarning} if there
is no current event loop set and it decides to create one.
(Contributed by Serhiy Storchaka and Guido van Rossum in gh-100160@footnote{https://github.com/python/cpython/issues/100160}.)
@end itemize

@item 
@ref{1e,,collections.abc}: Deprecated @ref{2c0,,ByteString}.
Prefer @code{Sequence} or @ref{2c1,,Buffer}.
For use in typing, prefer a union, like @code{bytes | bytearray},
or @ref{2c1,,collections.abc.Buffer}.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)

@item 
@ref{3b,,email}: Deprecated the `isdst' parameter in @ref{2c2,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{77,,importlib.abc} deprecated classes:


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

Use @ref{7b,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{1f0,,importlib.resources.abc.Traversable}

@item 
@ref{2c3,,importlib.resources.abc.TraversableResources}
@end itemize

(Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963@footnote{https://github.com/python/cpython/issues/93963}.)

@item 
@ref{80,,itertools} had undocumented, inefficient, historically buggy,
and inconsistent support for copy, deepcopy, and pickle operations.
This will be removed in 3.14 for a significant reduction in code
volume and maintenance burden.
(Contributed by Raymond Hettinger in gh-101588@footnote{https://github.com/python/cpython/issues/101588}.)

@item 
@ref{93,,multiprocessing}: The default start method will change to a safer one on
Linux, BSDs, and other non-macOS POSIX platforms where @code{'fork'} is currently
the default (gh-84559@footnote{https://github.com/python/cpython/issues/84559}). Adding a runtime warning about this was deemed too
disruptive as the majority of code is not expected to care. Use the
@ref{2c4,,get_context()} or
@ref{2c5,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{2c6,,Contextes et méthodes de démarrage}.

@item 
@ref{a3,,pathlib}: @ref{2c7,,is_relative_to()} and
@ref{2c8,,relative_to()}: passing additional arguments is
deprecated.

@item 
@ref{a8,,pkgutil}: @ref{2c9,,find_loader()} and @ref{2ca,,get_loader()}
now raise @ref{1a3,,DeprecationWarning};
use @ref{2cb,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b0,,pty}:


@itemize *

@item 
@code{master_open()}: use @ref{2cc,,pty.openpty()}.

@item 
@code{slave_open()}: use @ref{2cc,,pty.openpty()}.
@end itemize

@item 
@ref{ce,,sqlite3}:


@itemize *

@item 
@ref{2cd,,version} and @ref{2ce,,version_info}.

@item 
@ref{2cf,,execute()} and @ref{2d0,,executemany()}
if @ref{2d1,,named placeholders} are used and
`parameters' is a sequence instead of a @ref{253,,dict}.
@end itemize

@item 
@ref{103,,typing}: @ref{2d2,,ByteString}, deprecated since Python 3.9,
now causes a @ref{1a3,,DeprecationWarning} to be emitted when it is used.

@item 
@ref{107,,urllib}:
@code{urllib.parse.Quoter} is deprecated: it was not intended to be a
public API.
(Contributed by Gregory P. Smith in gh-88168@footnote{https://github.com/python/cpython/issues/88168}.)
@end itemize

@node Pending Removal in Python 3 15,Pending removal in Python 3 16,Pending Removal in Python 3 14,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-15}@anchor{2d3}
@subsubsection Pending Removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2d4,,__cached__} on a module while
failing to set @ref{2d5,,__spec__.cached}
is deprecated. In Python 3.15, @code{__cached__} will cease to be set or
take into consideration by the import system or standard library. (gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
Setting @ref{2d6,,__package__} on a module while
failing to set @ref{2d7,,__spec__.parent}
is deprecated. In Python 3.15, @code{__package__} will cease to be set or
take into consideration by the import system or standard library. (gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2a,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{71,,http.server}:


@itemize *

@item 
The obsolete and rarely used @ref{29e,,CGIHTTPRequestHandler}
has been deprecated since Python 3.13.
No direct replacement exists.
`Anything' is better than CGI to interface
a web server with a request handler.

@item 
The @code{--cgi} flag to the @code{python -m http.server}
command-line interface has been deprecated since Python 3.13.
@end itemize

@item 
@ref{85,,locale}:


@itemize *

@item 
The @ref{2d8,,getdefaultlocale()} function
has been deprecated since Python 3.11.
Its removal was originally planned for Python 3.13 (gh-90817@footnote{https://github.com/python/cpython/issues/90817}),
but has been postponed to Python 3.15.
Use @ref{2d9,,getlocale()}, @ref{2da,,setlocale()},
and @ref{2db,,getencoding()} instead.
(Contributed by Hugo van Kemenade in gh-111187@footnote{https://github.com/python/cpython/issues/111187}.)
@end itemize

@item 
@ref{a3,,pathlib}:


@itemize *

@item 
@ref{2a3,,PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{220,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{a9,,platform}:


@itemize *

@item 
@ref{2a4,,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.
@end itemize

@item 
@ref{ec,,threading}:


@itemize *

@item 
@ref{2dc,,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.
@end itemize

@item 
@ref{102,,types}:


@itemize *

@item 
@ref{2dd,,types.CodeType}: Accessing @ref{2de,,co_lnotab} was
deprecated in 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}
since 3.10 and was planned to be removed in 3.12,
but it only got a proper @ref{1a3,,DeprecationWarning} in 3.12.
May be removed in 3.15.
(Contributed by Nikita Sobolev in gh-101866@footnote{https://github.com/python/cpython/issues/101866}.)
@end itemize

@item 
@ref{103,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2ad,,NamedTuple} classes
(e.g. @code{Point = NamedTuple("Point", x=int, y=int)})
has been deprecated since Python 3.13.
Use the class-based syntax or the functional syntax instead.

@item 
The @ref{2ae,,typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{103,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@ref{112,,wave}:


@itemize *

@item 
The @ref{2b1,,getmark()}, @code{setmark()},
and @ref{2b2,,getmarkers()} methods of
the @ref{2b3,,Wave_read} and @ref{2b4,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize
@end itemize

@node Pending removal in Python 3 16,Pending Removal in Future Versions,Pending Removal in Python 3 15,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-python-3-16}@anchor{2df}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2e0,,__loader__} on a module while
failing to set @ref{2e1,,__spec__.loader}
is deprecated. In Python 3.16, @code{__loader__} will cease to be set or
taken into consideration by the import system or the standard library.
@end itemize

@item 
@ref{7,,array}:


@itemize *

@item 
The @code{'u'} format code (@code{wchar_t})
has been deprecated in documentation since Python 3.3
and at runtime since Python 3.13.
Use the @code{'w'} format code (@ref{298,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{a,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16,
use @ref{2e2,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)
@end itemize

@item 
@ref{12,,builtins}:


@itemize *

@item 
Bitwise inversion on boolean types, @code{~True} or @code{~False}
has been deprecated since Python 3.12,
as it produces surprising and unintuitive results (@code{-2} and @code{-1}).
Use @code{not x} instead for the logical negation of a Boolean.
In the rare case that you need the bitwise inversion of
the underlying integer, convert to @code{int} explicitly (@code{~int(x)}).
@end itemize

@item 
@ref{c4,,shutil}:


@itemize *

@item 
The @code{ExecError} exception
has been deprecated since Python 3.14.
It has not been used by any function in @code{shutil} since Python 3.4,
and is now an alias of @ref{193,,RuntimeError}.
@end itemize

@item 
@ref{d7,,symtable}:


@itemize *

@item 
The @ref{2e3,,Class.get_methods} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{d8,,sys}:


@itemize *

@item 
The @ref{2ab,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{dd,,tarfile}:


@itemize *

@item 
The undocumented and unused @code{TarFile.tarfile} attribute
has been deprecated since Python 3.13.
@end itemize
@end itemize

@node Pending Removal in Future Versions,,Pending removal in Python 3 16,New Deprecations
@anchor{whatsnew/3 13 pending-removal-in-future-versions}@anchor{2e4}
@subsubsection Pending Removal in Future Versions


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


@itemize *

@item 
@ref{6,,argparse}: Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
@ref{7,,array}'s @code{'u'} format code (gh-57281@footnote{https://github.com/python/cpython/issues/57281})

@item 
@ref{12,,builtins}:


@itemize *

@item 
@code{bool(NotImplemented)}.

@item 
Generators: @code{throw(type, exc, tb)} and @code{athrow(type, exc, tb)}
signature is deprecated: use @code{throw(exc)} and @code{athrow(exc)} instead,
the single argument signature.

@item 
Currently Python accepts numeric literals immediately followed by keywords,
for example @code{0in x}, @code{1or x}, @code{0if 1else 2}.  It allows confusing and
ambiguous expressions like @code{[0x1for x in y]} (which can be interpreted as
@code{[0x1 for x in y]} or @code{[0x1f or x in y]}).  A syntax warning is raised
if the numeric literal is immediately followed by one of keywords
@ref{2e5,,and}, @ref{18a,,else}, @ref{2e6,,for}, @ref{2e7,,if},
@ref{2e8,,in}, @ref{2e9,,is} and @ref{2ea,,or}.  In a future release it
will be changed to a syntax error. (gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
Support for @code{__index__()} and @code{__int__()} method returning non-int type:
these methods will be required to return an instance of a strict subclass of
@ref{254,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{2eb,,float}: these methods will be required to return an instance of
@ref{2eb,,float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{2ec,,complex}: these methods will be required to return an instance of
@ref{2ec,,complex}.

@item 
Delegation of @code{int()} to @code{__trunc__()} method.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{2ec,,complex()} constructor is now deprecated; it should only be passed
as a single positional argument.
(Contributed by Serhiy Storchaka in gh-109218@footnote{https://github.com/python/cpython/issues/109218}.)
@end itemize

@item 
@ref{14,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{2ed,,calendar.JANUARY} and
@ref{2ee,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{2de,,codeobject.co_lnotab}: use the @ref{2ef,,codeobject.co_lines()} method
instead.

@item 
@ref{30,,datetime}:


@itemize *

@item 
@ref{2f0,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{2f1,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{62,,gettext}: Plural value must be an integer.

@item 
@ref{76,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.

@item 
@ref{2f2,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{79,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{86,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{2f3,,warning()} instead.

@item 
@ref{8a,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a0,,os}: Calling @ref{2f4,,os.register_at_fork()} in multi-threaded process.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{b8,,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 in gh-91760@footnote{https://github.com/python/cpython/issues/91760}.)

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{c4,,shutil}: @ref{2f5,,rmtree()}'s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{cf,,ssl} options and protocols:


@itemize *

@item 
@ref{291,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{291,,ssl.SSLContext}: @ref{2f6,,set_npn_protocols()} and
@code{selected_npn_protocol()} are deprecated: use ALPN
instead.

@item 
@code{ssl.OP_NO_SSL*} options

@item 
@code{ssl.OP_NO_TLS*} options

@item 
@code{ssl.PROTOCOL_SSLv3}

@item 
@code{ssl.PROTOCOL_TLS}

@item 
@code{ssl.PROTOCOL_TLSv1}

@item 
@code{ssl.PROTOCOL_TLSv1_1}

@item 
@code{ssl.PROTOCOL_TLSv1_2}

@item 
@code{ssl.TLSVersion.SSLv3}

@item 
@code{ssl.TLSVersion.TLSv1}

@item 
@code{ssl.TLSVersion.TLSv1_1}
@end itemize

@item 
@ref{2f7,,sysconfig.is_python_build()} `check_home' parameter is deprecated and
ignored.

@item 
@ref{ec,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{2f8,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{2f9,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{2fa,,threading.Thread.setDaemon()}:
use @ref{2fb,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{2fc,,threading.Thread.setName()}:
use @ref{2fd,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{2fe,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{2ff,,threading.active_count()}.
@end itemize

@item 
@ref{300,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
@ref{301,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{109,,urllib.parse} deprecated functions: @ref{302,,urlparse()} instead


@itemize *

@item 
@code{splitattr()}

@item 
@code{splithost()}

@item 
@code{splitnport()}

@item 
@code{splitpasswd()}

@item 
@code{splitport()}

@item 
@code{splitquery()}

@item 
@code{splittag()}

@item 
@code{splittype()}

@item 
@code{splituser()}

@item 
@code{splitvalue()}

@item 
@code{to_bytes()}
@end itemize

@item 
@ref{10a,,urllib.request}: @ref{303,,URLopener} and
@ref{304,,FancyURLopener} style of invoking requests is
deprecated. Use newer @ref{290,,urlopen()} functions and methods.

@item 
@ref{117,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{124,,xml.etree.ElementTree}: Testing the truth value of an
@ref{305,,Element} is deprecated. In a future release it
will always return @code{True}. Prefer explicit @code{len(elem)} or
@code{elem is not None} tests instead.

@item 
@ref{306,,zipimport.zipimporter.load_module()} is deprecated:
use @ref{307,,exec_module()} instead.
@end itemize

@node CPython Bytecode Changes,Changements à l'API C,New Deprecations,What's New In Python 3 13
@anchor{whatsnew/3 13 cpython-bytecode-changes}@anchor{308}
@subsection CPython Bytecode Changes



@itemize *

@item 
The oparg of @ref{309,,YIELD_VALUE} is now
@code{1} if the yield is part of a yield-from or await, and @code{0} otherwise.
The oparg of @ref{30a,,RESUME} was changed to add a bit indicating
if the except-depth is 1, which is needed to optimize closing of generators.
(Contributed by Irit Katriel in gh-111354@footnote{https://github.com/python/cpython/issues/111354}.)
@end itemize

@node Changements à l'API C,Changements à la compilation,CPython Bytecode Changes,What's New In Python 3 13
@anchor{whatsnew/3 13 c-api-changes}@anchor{30b}
@subsection Changements à l'API C


@menu
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<2>. 
* Changed C APIs:: 
* Limited C API Changes:: 
* Removed C APIs:: 
* Deprecated C APIs:: 

@end menu

@node Nouvelles fonctionnalités<2>,Changed C APIs,,Changements à l'API C
@anchor{whatsnew/3 13 id7}@anchor{30c}
@subsubsection Nouvelles fonctionnalités



@itemize *

@item 
Add the @ref{15b,,PyMonitoring C API}
for generating 
@geindex Python Enhancement Proposals; PEP 669
PEP 669@footnote{https://peps.python.org/pep-0669/} monitoring events:


@itemize *

@item 
@ref{30d,,PyMonitoringState}

@item 
@ref{30e,,PyMonitoring_FirePyStartEvent()}

@item 
@ref{30f,,PyMonitoring_FirePyResumeEvent()}

@item 
@ref{310,,PyMonitoring_FirePyReturnEvent()}

@item 
@ref{311,,PyMonitoring_FirePyYieldEvent()}

@item 
@ref{312,,PyMonitoring_FireCallEvent()}

@item 
@ref{313,,PyMonitoring_FireLineEvent()}

@item 
@ref{314,,PyMonitoring_FireJumpEvent()}

@item 
@ref{315,,PyMonitoring_FireBranchEvent()}

@item 
@ref{316,,PyMonitoring_FireCReturnEvent()}

@item 
@ref{317,,PyMonitoring_FirePyThrowEvent()}

@item 
@ref{318,,PyMonitoring_FireRaiseEvent()}

@item 
@ref{319,,PyMonitoring_FireCRaiseEvent()}

@item 
@ref{31a,,PyMonitoring_FireReraiseEvent()}

@item 
@ref{31b,,PyMonitoring_FireExceptionHandledEvent()}

@item 
@ref{31c,,PyMonitoring_FirePyUnwindEvent()}

@item 
@ref{31d,,PyMonitoring_FireStopIterationEvent()}

@item 
@ref{31e,,PyMonitoring_EnterScope()}

@item 
@ref{31f,,PyMonitoring_ExitScope()}
@end itemize

(Contributed by Irit Katriel in gh-111997@footnote{https://github.com/python/cpython/issues/111997}).

@item 
Add @ref{15a,,PyMutex}, a lightweight mutex that occupies a single byte,
and the new @ref{320,,PyMutex_Lock()} and @ref{321,,PyMutex_Unlock()} functions.
@code{PyMutex_Lock()} will release the @ref{158,,GIL} (if currently held)
if the operation needs to block.
(Contributed by Sam Gross in gh-108724@footnote{https://github.com/python/cpython/issues/108724}.)

@item 
Add the @ref{322,,PyTime C API} to provide access to system clocks:


@itemize *

@item 
@ref{323,,PyTime_t}.

@item 
@ref{324,,PyTime_MIN} and @ref{325,,PyTime_MAX}.

@item 
@ref{326,,PyTime_AsSecondsDouble()}.

@item 
@ref{327,,PyTime_Monotonic()}.

@item 
@ref{328,,PyTime_MonotonicRaw()}.

@item 
@ref{329,,PyTime_PerfCounter()}.

@item 
@ref{32a,,PyTime_PerfCounterRaw()}.

@item 
@ref{32b,,PyTime_Time()}.

@item 
@ref{32c,,PyTime_TimeRaw()}.
@end itemize

(Contributed by Victor Stinner and Petr Viktorin in gh-110850@footnote{https://github.com/python/cpython/issues/110850}.)

@item 
Add the @ref{32d,,PyDict_ContainsString()} function
with the same behavior as @ref{32e,,PyDict_Contains()},
but `key' is specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
(Contributed by Victor Stinner in gh-108314@footnote{https://github.com/python/cpython/issues/108314}.)

@item 
Add the @ref{330,,PyDict_GetItemRef()} and @ref{331,,PyDict_GetItemStringRef()}
functions,
which behave similarly to @ref{332,,PyDict_GetItemWithError()},
but return a  @ref{333,,strong reference} instead of a @ref{334,,borrowed reference}.
Moreover, these functions return @code{-1} on error,
removing the need to check @code{PyErr_Occurred()}.
(Contributed by Victor Stinner in gh-106004@footnote{https://github.com/python/cpython/issues/106004}.)

@item 
Add the @ref{335,,PyDict_SetDefaultRef()} function,
which behaves similarly to @ref{336,,PyDict_SetDefault()},
but returns a @ref{333,,strong reference} instead of a @ref{334,,borrowed reference}.
This function returns @code{-1} on error,
@code{0} on insertion,
and @code{1} if the key was already present in the dictionary.
(Contributed by Sam Gross in gh-112066@footnote{https://github.com/python/cpython/issues/112066}.)

@item 
Add the @ref{337,,PyDict_Pop()} and @ref{338,,PyDict_PopString()} functions
to remove a key from a dictionary and optionally return the removed value.
This is similar to @ref{339,,dict.pop()},
though there is no default value,
and @ref{33a,,KeyError} is not raised for missing keys.
(Contributed by Stefan Behnel and Victor Stinner in gh-111262@footnote{https://github.com/python/cpython/issues/111262}.)

@item 
Add the @ref{33b,,PyMapping_GetOptionalItem()}
and @ref{33c,,PyMapping_GetOptionalItemString()} functions
as alternatives to @ref{33d,,PyObject_GetItem()}
and @ref{33e,,PyMapping_GetItemString()} respectively.
The new functions do not raise @ref{33a,,KeyError}
if the requested key is missing from the mapping.
These variants are more convenient and faster
if a missing key should not be treated as a failure.
(Contributed by Serhiy Storchaka in gh-106307@footnote{https://github.com/python/cpython/issues/106307}.)

@item 
Add the @ref{33f,,PyObject_GetOptionalAttr()}
and @ref{340,,PyObject_GetOptionalAttrString()} functions
as alternatives to  @ref{341,,PyObject_GetAttr()}
and @ref{342,,PyObject_GetAttrString()} respectively.
The new functions do not raise @ref{343,,AttributeError}
if the requested attribute is not found on the object.
These variants are more convenient and faster
if the missing attribute should not be treated as a failure.
(Contributed by Serhiy Storchaka in gh-106521@footnote{https://github.com/python/cpython/issues/106521}.)

@item 
Add the @ref{344,,PyErr_FormatUnraisable()} function
as an extension to @ref{345,,PyErr_WriteUnraisable()}
that allows customizing the warning message.
(Contributed by Serhiy Storchaka in gh-108082@footnote{https://github.com/python/cpython/issues/108082}.)

@item 
Add new functions that return a @ref{333,,strong reference} instead of
a @ref{334,,borrowed reference} for frame locals, globals, and builtins,
as part of @ref{141,,PEP 667}:


@itemize *

@item 
@ref{346,,PyEval_GetFrameBuiltins()} replaces @ref{347,,PyEval_GetBuiltins()}

@item 
@ref{348,,PyEval_GetFrameGlobals()} replaces @ref{349,,PyEval_GetGlobals()}

@item 
@ref{34a,,PyEval_GetFrameLocals()} replaces @ref{34b,,PyEval_GetLocals()}
@end itemize

(Contributed by Mark Shannon and Tian Gao in gh-74929@footnote{https://github.com/python/cpython/issues/74929}.)

@item 
Add the @ref{34c,,Py_GetConstant()} and @ref{34d,,Py_GetConstantBorrowed()}
functions to get @ref{333,,strong}
or @ref{334,,borrowed} references to constants.
For example, @code{Py_GetConstant(Py_CONSTANT_ZERO)} returns a strong reference
to the constant zero.
(Contributed by Victor  Stinner in gh-115754@footnote{https://github.com/python/cpython/issues/115754}.)

@item 
Add the @ref{34e,,PyImport_AddModuleRef()} function
as a replacement for @ref{34f,,PyImport_AddModule()}
that returns a @ref{333,,strong reference} instead of a @ref{334,,borrowed reference}.
(Contributed by Victor Stinner in gh-105922@footnote{https://github.com/python/cpython/issues/105922}.)

@item 
Add the @ref{350,,Py_IsFinalizing()} function to check
whether the main Python interpreter is
@ref{14d,,shutting down}.
(Contributed by Victor Stinner in gh-108014@footnote{https://github.com/python/cpython/issues/108014}.)

@item 
Add the @ref{351,,PyList_GetItemRef()} function
as a replacement for @ref{352,,PyList_GetItem()}
that returns a @ref{333,,strong reference} instead of a @ref{334,,borrowed reference}.
(Contributed by Sam Gross in gh-114329@footnote{https://github.com/python/cpython/issues/114329}.)

@item 
Add the @ref{353,,PyList_Extend()} and @ref{354,,PyList_Clear()} functions,
mirroring the Python @code{list.extend()} and @code{list.clear()} methods.
(Contributed by Victor Stinner in gh-111138@footnote{https://github.com/python/cpython/issues/111138}.)

@item 
Add the @ref{355,,PyLong_AsInt()} function.
It behaves similarly to @ref{356,,PyLong_AsLong()},
but stores the result in a C int instead of a C long.
(Contributed by Victor Stinner in gh-108014@footnote{https://github.com/python/cpython/issues/108014}.)

@item 
Add the @ref{357,,PyLong_AsNativeBytes()}, @ref{358,,PyLong_FromNativeBytes()},
and @ref{359,,PyLong_FromUnsignedNativeBytes()} functions
to simplify converting between native integer types
and Python @ref{254,,int} objects.
(Contributed by Steve Dower in gh-111140@footnote{https://github.com/python/cpython/issues/111140}.)

@item 
Add @ref{35a,,PyModule_Add()} function, which is similar to
@ref{35b,,PyModule_AddObjectRef()} and @ref{35c,,PyModule_AddObject()},
but always steals a reference to the value.
(Contributed by Serhiy Storchaka in gh-86493@footnote{https://github.com/python/cpython/issues/86493}.)

@item 
Add the @ref{35d,,PyObject_GenericHash()} function
that implements the default hashing function of a Python object.
(Contributed by Serhiy Storchaka in gh-113024@footnote{https://github.com/python/cpython/issues/113024}.)

@item 
Add the @ref{35e,,Py_HashPointer()} function to hash a raw pointer.
(Contributed by Victor Stinner in gh-111545@footnote{https://github.com/python/cpython/issues/111545}.)

@item 
Add the @ref{35f,,PyObject_VisitManagedDict()} and
@ref{360,,PyObject_ClearManagedDict()} functions.
which must be called by the traverse and clear functions of a type using
the @ref{361,,Py_TPFLAGS_MANAGED_DICT} flag.
The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to
use these functions with Python 3.11 and 3.12.
(Contributed by Victor Stinner in gh-107073@footnote{https://github.com/python/cpython/issues/107073}.)

@item 
Add the @ref{362,,PyRefTracer_SetTracer()}
and @ref{363,,PyRefTracer_GetTracer()} functions,
which enable tracking object creation and destruction
in the same way that the @ref{fe,,tracemalloc} module does.
(Contributed by Pablo Galindo in gh-93502@footnote{https://github.com/python/cpython/issues/93502}.)

@item 
Add the @ref{364,,PySys_AuditTuple()} function
as an alternative to @ref{365,,PySys_Audit()}
that takes event arguments as a Python @ref{366,,tuple} object.
(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}.)

@item 
Add the @ref{367,,PyThreadState_GetUnchecked()} function
as an alternative to @ref{368,,PyThreadState_Get()}
that doesn't kill the process with a fatal error if it is @code{NULL}.
The caller is responsible for checking if the result is @code{NULL}.
(Contributed by Victor Stinner in gh-108867@footnote{https://github.com/python/cpython/issues/108867}.)

@item 
Add the @ref{369,,PyType_GetFullyQualifiedName()} function
to get the type's fully qualified name.
The module name is prepended if @ref{36a,,type.__module__} is
a string and is not equal to either @code{'builtins'} or @code{'__main__'}.
(Contributed by Victor Stinner in gh-111696@footnote{https://github.com/python/cpython/issues/111696}.)

@item 
Add the @ref{36b,,PyType_GetModuleName()} function
to get the type's module name. This is equivalent to getting the
@ref{36a,,type.__module__} attribute.
(Contributed by Eric Snow and Victor Stinner in gh-111696@footnote{https://github.com/python/cpython/issues/111696}.)

@item 
Add the @ref{36c,,PyUnicode_EqualToUTF8AndSize()}
and @ref{36d,,PyUnicode_EqualToUTF8()} functions
to compare a Unicode object with a const char* UTF-8 encoded string
and @code{1} if they are equal or @code{0} otherwise.
These functions do not raise exceptions.
(Contributed by Serhiy Storchaka in gh-110289@footnote{https://github.com/python/cpython/issues/110289}.)

@item 
Add the @ref{36e,,PyWeakref_GetRef()} function
as an alternative to  @ref{36f,,PyWeakref_GetObject()}
that returns a @ref{333,,strong reference}
or @code{NULL} if the referent is no longer live.
(Contributed by Victor Stinner in gh-105927@footnote{https://github.com/python/cpython/issues/105927}.)

@item 
Add fixed variants of functions which silently ignore errors:


@itemize *

@item 
@ref{370,,PyObject_HasAttrWithError()} replaces @ref{371,,PyObject_HasAttr()}.

@item 
@ref{372,,PyObject_HasAttrStringWithError()}
replaces @ref{373,,PyObject_HasAttrString()}.

@item 
@ref{374,,PyMapping_HasKeyWithError()} replaces @ref{375,,PyMapping_HasKey()}.

@item 
@ref{376,,PyMapping_HasKeyStringWithError()}
replaces @ref{377,,PyMapping_HasKeyString()}.
@end itemize

The new functions return @code{-1} for errors
and the standard @code{1} for true and @code{0} for false.

(Contributed by Serhiy Storchaka in gh-108511@footnote{https://github.com/python/cpython/issues/108511}.)
@end itemize

@node Changed C APIs,Limited C API Changes,Nouvelles fonctionnalités<2>,Changements à l'API C
@anchor{whatsnew/3 13 changed-c-apis}@anchor{378}
@subsubsection Changed C APIs



@itemize *

@item 
The `keywords' parameter of @ref{379,,PyArg_ParseTupleAndKeywords()}
and @ref{37a,,PyArg_VaParseTupleAndKeywords()}
now has type char *const* in C
and const char *const* in C++,
instead of char**.
In C++, this makes these functions compatible with arguments
of type const char *const*, const char**,
or char *const* without an explicit type cast.
In C, the functions only support arguments of type char *const*.
This can be overridden with the @ref{37b,,PY_CXX_CONST} macro.
(Contributed by Serhiy Storchaka in gh-65210@footnote{https://github.com/python/cpython/issues/65210}.)

@item 
@ref{379,,PyArg_ParseTupleAndKeywords()} now supports
non-ASCII keyword parameter names.
(Contributed by Serhiy Storchaka in gh-110815@footnote{https://github.com/python/cpython/issues/110815}.)

@item 
The @code{PyCode_GetFirstFree()} function is now unstable API
and is now named @ref{37c,,PyUnstable_Code_GetFirstFree()}.
(Contributed by Bogdan Romanyuk in gh-115781@footnote{https://github.com/python/cpython/issues/115781}.)

@item 
The @ref{37d,,PyDict_GetItem()}, @ref{37e,,PyDict_GetItemString()},
@ref{375,,PyMapping_HasKey()}, @ref{377,,PyMapping_HasKeyString()},
@ref{371,,PyObject_HasAttr()}, @ref{373,,PyObject_HasAttrString()},
and @ref{37f,,PySys_GetObject()} functions,
each of which clears all errors which occurred when calling them
now reports these errors using @ref{1f4,,sys.unraisablehook()}.
You may replace them with other functions as recommended in the documentation.
(Contributed by Serhiy Storchaka in gh-106672@footnote{https://github.com/python/cpython/issues/106672}.)

@item 
Add support for the @code{%T}, @code{%#T}, @code{%N} and @code{%#N} formats
to @ref{380,,PyUnicode_FromFormat()}:


@itemize *

@item 
@code{%T}: Get the fully qualified name of an object type

@item 
@code{%#T}: As above, but use a colon as the separator

@item 
@code{%N}: Get the fully qualified name of a type

@item 
@code{%#N}: As above, but use a colon as the separator
@end itemize

See 
@geindex Python Enhancement Proposals; PEP 737
PEP 737@footnote{https://peps.python.org/pep-0737/} for more information.
(Contributed by Victor Stinner in gh-111696@footnote{https://github.com/python/cpython/issues/111696}.)

@item 
You no longer have to define the @code{PY_SSIZE_T_CLEAN} macro before
including @code{Python.h} when using @code{#} formats in
@ref{381,,format codes}.
APIs accepting the format codes always use @code{Py_ssize_t} for @code{#} formats.
(Contributed by Inada Naoki in gh-104922@footnote{https://github.com/python/cpython/issues/104922}.)

@item 
If Python is built in @ref{1f6,,debug mode}
or @ref{382,,with assertions},
@ref{383,,PyTuple_SET_ITEM()} and @ref{384,,PyList_SET_ITEM()}
now check the index argument with an assertion.
(Contributed by Victor Stinner in gh-106168@footnote{https://github.com/python/cpython/issues/106168}.)
@end itemize

@node Limited C API Changes,Removed C APIs,Changed C APIs,Changements à l'API C
@anchor{whatsnew/3 13 limited-c-api-changes}@anchor{385}
@subsubsection Limited C API Changes



@itemize *

@item 
The following functions are now included in the Limited C API:


@itemize *

@item 
@ref{386,,PyMem_RawMalloc()}

@item 
@ref{387,,PyMem_RawCalloc()}

@item 
@ref{388,,PyMem_RawRealloc()}

@item 
@ref{389,,PyMem_RawFree()}

@item 
@ref{365,,PySys_Audit()}

@item 
@ref{364,,PySys_AuditTuple()}

@item 
@ref{38a,,PyType_GetModuleByDef()}
@end itemize

(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}, gh-85283@footnote{https://github.com/python/cpython/issues/85283}, and gh-116936@footnote{https://github.com/python/cpython/issues/116936}.)

@item 
Python built with @ref{38b,,--with-trace-refs} (tracing references)
now supports the @ref{38c,,Limited API}.
(Contributed by Victor Stinner in gh-108634@footnote{https://github.com/python/cpython/issues/108634}.)
@end itemize

@node Removed C APIs,Deprecated C APIs,Limited C API Changes,Changements à l'API C
@anchor{whatsnew/3 13 removed-c-apis}@anchor{38d}
@subsubsection Removed C APIs



@itemize *

@item 
Remove several functions, macros, variables, etc
with names prefixed by @code{_Py} or @code{_PY} (which are considered private).
If your project is affected  by one of these removals
and you believe that the removed API should remain available,
please @ref{24b,,open a new issue} to request a public C API
and add @code{cc: @@vstinner} to the issue to notify Victor Stinner.
(Contributed by Victor Stinner in gh-106320@footnote{https://github.com/python/cpython/issues/106320}.)

@item 
Remove old buffer protocols deprecated in Python 3.0.
Use @ref{38e,,Protocole tampon} instead.


@itemize *

@item 
@code{PyObject_CheckReadBuffer()}:
Use @ref{38f,,PyObject_CheckBuffer()} to test
whether the object supports the buffer protocol.
Note that @ref{38f,,PyObject_CheckBuffer()} doesn't guarantee
that @ref{390,,PyObject_GetBuffer()} will succeed.
To test if the object is actually readable,
see the next example of @ref{390,,PyObject_GetBuffer()}.

@item 
@code{PyObject_AsCharBuffer()}, @code{PyObject_AsReadBuffer()}:
Use @ref{390,,PyObject_GetBuffer()} and @ref{391,,PyBuffer_Release()} instead:

@example
Py_buffer view;
if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) @{
    return NULL;
@}
// Use `view.buf` and `view.len` to read from the buffer.
// You may need to cast buf as `(const char*)view.buf`.
PyBuffer_Release(&view);
@end example

@item 
@code{PyObject_AsWriteBuffer()}:
Use @ref{390,,PyObject_GetBuffer()} and @ref{391,,PyBuffer_Release()} instead:

@example
Py_buffer view;
if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) @{
    return NULL;
@}
// Use `view.buf` and `view.len` to write to the buffer.
PyBuffer_Release(&view);
@end example
@end itemize

(Contributed by Inada Naoki in gh-85275@footnote{https://github.com/python/cpython/issues/85275}.)

@item 
Remove various functions deprecated in Python 3.9:


@itemize *

@item 
@code{PyEval_CallObject()}, @code{PyEval_CallObjectWithKeywords()}:
Use @ref{392,,PyObject_CallNoArgs()} or @ref{393,,PyObject_Call()} instead.

@cartouche
@quotation Avertissement 
In @ref{393,,PyObject_Call()}, positional arguments must be a @ref{366,,tuple}
and must not be @code{NULL},
and keyword arguments must be a @ref{253,,dict} or @code{NULL},
whereas the removed functions checked argument types
and accepted @code{NULL} positional and keyword arguments.
To replace @code{PyEval_CallObjectWithKeywords(func, NULL, kwargs)} with
@ref{393,,PyObject_Call()},
pass an empty tuple as positional arguments using
@ref{394,,PyTuple_New(0)}.
@end quotation
@end cartouche

@item 
@code{PyEval_CallFunction()}:
Use @ref{395,,PyObject_CallFunction()} instead.

@item 
@code{PyEval_CallMethod()}:
Use @ref{396,,PyObject_CallMethod()} instead.

@item 
@code{PyCFunction_Call()}:
Use @ref{393,,PyObject_Call()} instead.
@end itemize

(Contributed by Victor Stinner in gh-105107@footnote{https://github.com/python/cpython/issues/105107}.)

@item 
Remove the following old functions to configure the Python initialization,
deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_AddWarnOptionUnicode()}:
Use @ref{397,,PyConfig.warnoptions} instead.

@item 
@code{PySys_AddWarnOption()}:
Use @ref{397,,PyConfig.warnoptions} instead.

@item 
@code{PySys_AddXOption()}:
Use @ref{398,,PyConfig.xoptions} instead.

@item 
@code{PySys_HasWarnOptions()}:
Use @ref{398,,PyConfig.xoptions} instead.

@item 
@code{PySys_SetPath()}:
Set @ref{399,,PyConfig.module_search_paths} instead.

@item 
@code{Py_SetPath()}:
Set @ref{399,,PyConfig.module_search_paths} instead.

@item 
@code{Py_SetStandardStreamEncoding()}:
Set @ref{39a,,PyConfig.stdio_encoding} instead,
and set also maybe @ref{39b,,PyConfig.legacy_windows_stdio} (on Windows).

@item 
@code{_Py_SetProgramFullPath()}:
Set @ref{39c,,PyConfig.executable} instead.
@end itemize

Use the new @ref{39d,,PyConfig} API of the @ref{39e,,Python Initialization Configuration} instead (
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}), added to Python 3.8.
(Contributed by Victor Stinner in gh-105145@footnote{https://github.com/python/cpython/issues/105145}.)

@item 
Remove @code{PyEval_AcquireLock()} and @code{PyEval_ReleaseLock()} functions,
deprecated in Python 3.2.
They didn't update the current thread state.
They can be replaced with:


@itemize *

@item 
@ref{39f,,PyEval_SaveThread()} and @ref{3a0,,PyEval_RestoreThread()};

@item 
low-level @ref{3a1,,PyEval_AcquireThread()} and @ref{3a0,,PyEval_RestoreThread()};

@item 
or @ref{3a2,,PyGILState_Ensure()} and @ref{3a3,,PyGILState_Release()}.
@end itemize

(Contributed by Victor Stinner in gh-105182@footnote{https://github.com/python/cpython/issues/105182}.)

@item 
Remove the @code{PyEval_ThreadsInitialized()} function,
deprecated in Python 3.9.
Since Python 3.7, @code{Py_Initialize()} always creates the GIL:
calling @code{PyEval_InitThreads()} does nothing and
@code{PyEval_ThreadsInitialized()} always returns non-zero.
(Contributed by Victor Stinner in gh-105182@footnote{https://github.com/python/cpython/issues/105182}.)

@item 
Remove the @code{_PyInterpreterState_Get()} alias to
@ref{3a4,,PyInterpreterState_Get()}
which was kept for backward compatibility with Python 3.8.
The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@ref{3a4,,PyInterpreterState_Get()} on Python 3.8 and older.
(Contributed by Victor Stinner in gh-106320@footnote{https://github.com/python/cpython/issues/106320}.)

@item 
Remove the private @code{_PyObject_FastCall()} function:
use @code{PyObject_Vectorcall()} which is available since Python 3.8
(
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}).
(Contributed by Victor Stinner in gh-106023@footnote{https://github.com/python/cpython/issues/106023}.)

@item 
Remove the @code{cpython/pytime.h} header file,
which only contained private functions.
(Contributed by Victor Stinner in gh-106316@footnote{https://github.com/python/cpython/issues/106316}.)

@item 
Remove the undocumented @code{PY_TIMEOUT_MAX} constant from the limited C API.
(Contributed by Victor Stinner in gh-110014@footnote{https://github.com/python/cpython/issues/110014}.)

@item 
Remove the old trashcan macros @code{Py_TRASHCAN_SAFE_BEGIN}
and @code{Py_TRASHCAN_SAFE_END}.
Replace both with the new macros @code{Py_TRASHCAN_BEGIN}
and @code{Py_TRASHCAN_END}.
(Contributed by Irit Katriel in gh-105111@footnote{https://github.com/python/cpython/issues/105111}.)
@end itemize

@node Deprecated C APIs,,Removed C APIs,Changements à l'API C
@anchor{whatsnew/3 13 deprecated-c-apis}@anchor{3a5}
@subsubsection Deprecated C APIs



@itemize *

@item 
Deprecate old Python initialization functions:


@itemize *

@item 
@ref{3a6,,PySys_ResetWarnOptions()}:
Clear @ref{3a7,,sys.warnoptions} and @code{warnings.filters} instead.

@item 
@ref{3a8,,Py_GetExecPrefix()}:
Get @ref{3a9,,sys.exec_prefix} instead.

@item 
@ref{3aa,,Py_GetPath()}:
Get @ref{3ab,,sys.path} instead.

@item 
@ref{3ac,,Py_GetPrefix()}:
Get @ref{3ad,,sys.prefix} instead.

@item 
@ref{3ae,,Py_GetProgramFullPath()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b0,,Py_GetProgramName()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b1,,Py_GetPythonHome()}:
Get @ref{3b2,,PyConfig.home}
or the 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment variable instead.
@end itemize

(Contributed by Victor Stinner in gh-105145@footnote{https://github.com/python/cpython/issues/105145}.)

@item 
@ref{206,,Soft deprecate} the
@ref{347,,PyEval_GetBuiltins()}, @ref{349,,PyEval_GetGlobals()},
and @ref{34b,,PyEval_GetLocals()} functions,
which return a @ref{334,,borrowed reference}.
(Soft deprecated as part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}.)

@item 
Deprecate the @ref{3b4,,PyImport_ImportModuleNoBlock()} function,
which is just an alias to @ref{3b5,,PyImport_ImportModule()} since Python 3.3.
(Contributed by Victor Stinner in gh-105396@footnote{https://github.com/python/cpython/issues/105396}.)

@item 
@ref{206,,Soft deprecate} the
@ref{35c,,PyModule_AddObject()} function.
It should be replaced with @ref{35a,,PyModule_Add()}
or @ref{35b,,PyModule_AddObjectRef()}.
(Contributed by Serhiy Storchaka in gh-86493@footnote{https://github.com/python/cpython/issues/86493}.)

@item 
Deprecate the old @code{Py_UNICODE} and @code{PY_UNICODE_TYPE} types
and the @code{Py_UNICODE_WIDE} define.
Use the @code{wchar_t} type directly instead.
Since Python 3.3, @code{Py_UNICODE} and @code{PY_UNICODE_TYPE}
are just aliases to @code{wchar_t}.
(Contributed by Victor Stinner in gh-105156@footnote{https://github.com/python/cpython/issues/105156}.)

@item 
Deprecate the @ref{36f,,PyWeakref_GetObject()} and
@ref{3b6,,PyWeakref_GET_OBJECT()} functions,
which return a @ref{334,,borrowed reference}.
Replace them with the new @ref{36e,,PyWeakref_GetRef()} function,
which returns a @ref{333,,strong reference}.
The pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat/} can be used to get
@ref{36e,,PyWeakref_GetRef()} on Python 3.12 and older.
(Contributed by Victor Stinner in gh-105927@footnote{https://github.com/python/cpython/issues/105927}.)
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@menu
* Pending Removal in Python 3.14: Pending Removal in Python 3 14<2>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<2>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<2>. 

@end menu

@node Pending Removal in Python 3 14<2>,Pending Removal in Python 3 15<2>,,Deprecated C APIs
@anchor{whatsnew/3 13 id8}@anchor{3b7}
@subsubsection Pending Removal in Python 3.14



@itemize *

@item 
The @code{ma_version_tag} field in @ref{3b8,,PyDictObject} for extension modules
(
@geindex Python Enhancement Proposals; PEP 699
PEP 699@footnote{https://peps.python.org/pep-0699/}; gh-101193@footnote{https://github.com/python/cpython/issues/101193}).

@item 
Creating @ref{3b9,,immutable types} with mutable
bases (gh-95388@footnote{https://github.com/python/cpython/issues/95388}).

@item 
Functions to configure Python's initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{3ba,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{3ba,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{3bb,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{3b2,,PyConfig.home} instead.
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{3bd,,Py_DebugFlag}:
Use @ref{3be,,PyConfig.parser_debug} instead.

@item 
@ref{3bf,,Py_VerboseFlag}:
Use @ref{3c0,,PyConfig.verbose} instead.

@item 
@ref{3c1,,Py_QuietFlag}:
Use @ref{3c2,,PyConfig.quiet} instead.

@item 
@ref{3c3,,Py_InteractiveFlag}:
Use @ref{3c4,,PyConfig.interactive} instead.

@item 
@ref{3c5,,Py_InspectFlag}:
Use @ref{3c6,,PyConfig.inspect} instead.

@item 
@ref{3c7,,Py_OptimizeFlag}:
Use @ref{3c8,,PyConfig.optimization_level} instead.

@item 
@ref{3c9,,Py_NoSiteFlag}:
Use @ref{3ca,,PyConfig.site_import} instead.

@item 
@ref{3cb,,Py_BytesWarningFlag}:
Use @ref{3cc,,PyConfig.bytes_warning} instead.

@item 
@ref{3cd,,Py_FrozenFlag}:
Use @ref{3ce,,PyConfig.pathconfig_warnings} instead.

@item 
@ref{3cf,,Py_IgnoreEnvironmentFlag}:
Use @ref{3d0,,PyConfig.use_environment} instead.

@item 
@ref{3d1,,Py_DontWriteBytecodeFlag}:
Use @ref{3d2,,PyConfig.write_bytecode} instead.

@item 
@ref{3d3,,Py_NoUserSiteDirectory}:
Use @ref{3d4,,PyConfig.user_site_directory} instead.

@item 
@ref{3d5,,Py_UnbufferedStdioFlag}:
Use @ref{3d6,,PyConfig.buffered_stdio} instead.

@item 
@ref{3d7,,Py_HashRandomizationFlag}:
Use @ref{3d8,,PyConfig.use_hash_seed}
and @ref{3d9,,PyConfig.hash_seed} instead.

@item 
@ref{3da,,Py_IsolatedFlag}:
Use @ref{3db,,PyConfig.isolated} instead.

@item 
@ref{3dc,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{3dd,,PyPreConfig.legacy_windows_fs_encoding} instead.

@item 
@ref{3de,,Py_LegacyWindowsStdioFlag}:
Use @ref{39b,,PyConfig.legacy_windows_stdio} instead.

@item 
@code{Py_FileSystemDefaultEncoding}:
Use @ref{3df,,PyConfig.filesystem_encoding} instead.

@item 
@code{Py_HasFileSystemDefaultEncoding}:
Use @ref{3df,,PyConfig.filesystem_encoding} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{3e0,,PyConfig.filesystem_errors} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{3e1,,PyPreConfig.utf8_mode} instead.
(see @ref{3e2,,Py_PreInitialize()})
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.
@end itemize

@node Pending Removal in Python 3 15<2>,Pending Removal in Future Versions<2>,Pending Removal in Python 3 14<2>,Deprecated C APIs
@anchor{whatsnew/3 13 id9}@anchor{3e3}
@subsubsection Pending Removal in Python 3.15



@itemize *

@item 
The bundled copy of @code{libmpdecimal}.

@item 
The @ref{3b4,,PyImport_ImportModuleNoBlock()}:
Use @ref{3b5,,PyImport_ImportModule()} instead.

@item 
@ref{36f,,PyWeakref_GetObject()} and @ref{3b6,,PyWeakref_GET_OBJECT()}:
Use @ref{36e,,PyWeakref_GetRef()} instead.

@item 
@ref{3e4,,Py_UNICODE} type and the @code{Py_UNICODE_WIDE} macro:
Use @code{wchar_t} instead.

@item 
Python initialization functions:


@itemize *

@item 
@ref{3a6,,PySys_ResetWarnOptions()}:
Clear @ref{3a7,,sys.warnoptions} and @code{warnings.filters} instead.

@item 
@ref{3a8,,Py_GetExecPrefix()}:
Get @ref{3e5,,sys.base_exec_prefix} and @ref{3a9,,sys.exec_prefix} instead.

@item 
@ref{3aa,,Py_GetPath()}:
Get @ref{3ab,,sys.path} instead.

@item 
@ref{3ac,,Py_GetPrefix()}:
Get @ref{3e6,,sys.base_prefix} and @ref{3ad,,sys.prefix} instead.

@item 
@ref{3ae,,Py_GetProgramFullPath()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b0,,Py_GetProgramName()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b1,,Py_GetPythonHome()}:
Get @ref{3b2,,PyConfig.home}
or the 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment variable instead.
@end itemize
@end itemize

@node Pending Removal in Future Versions<2>,,Pending Removal in Python 3 15<2>,Deprecated C APIs
@anchor{whatsnew/3 13 id10}@anchor{3e7}
@subsubsection Pending Removal in Future Versions


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


@itemize *

@item 
@ref{3e8,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{3e9,,PyErr_Fetch()}:
Use @ref{3ea,,PyErr_GetRaisedException()} instead.

@item 
@ref{3eb,,PyErr_NormalizeException()}:
Use @ref{3ea,,PyErr_GetRaisedException()} instead.

@item 
@ref{3ec,,PyErr_Restore()}:
Use @ref{3ed,,PyErr_SetRaisedException()} instead.

@item 
@ref{3ee,,PyModule_GetFilename()}:
Use @ref{3ef,,PyModule_GetFilenameObject()} instead.

@item 
@ref{3f0,,PyOS_AfterFork()}:
Use @ref{3f1,,PyOS_AfterFork_Child()} instead.

@item 
@ref{3f2,,PySlice_GetIndicesEx()}:
Use @ref{3f3,,PySlice_Unpack()} and @ref{3f4,,PySlice_AdjustIndices()} instead.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3f5,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3f5,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3f6,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3f6,,PyCodec_Encode()} instead.

@item 
@ref{3f7,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{3f8,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{3f9,,PyObject_Hash()} instead.

@item 
@code{PyDictObject.ma_version_tag} member.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{3fa,,PyThread_create_key()}:
Use @ref{3fb,,PyThread_tss_alloc()} instead.

@item 
@ref{3fc,,PyThread_delete_key()}:
Use @ref{3fd,,PyThread_tss_free()} instead.

@item 
@ref{3fe,,PyThread_set_key_value()}:
Use @ref{3ff,,PyThread_tss_set()} instead.

@item 
@ref{400,,PyThread_get_key_value()}:
Use @ref{401,,PyThread_tss_get()} instead.

@item 
@ref{402,,PyThread_delete_key_value()}:
Use @ref{403,,PyThread_tss_delete()} instead.

@item 
@ref{404,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@node Changements à la compilation,Porting to Python 3 13,Changements à l'API C,What's New In Python 3 13
@anchor{whatsnew/3 13 build-changes}@anchor{405}@anchor{whatsnew/3 13 pythoncapi-compat-project}@anchor{406}
@subsection Changements à la compilation



@itemize *

@item 
@code{arm64-apple-ios} and @code{arm64-apple-ios-simulator} are both
now 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} tier 3 platforms.
(@ref{164,,PEP 730} written
and implementation contributed by Russell Keith-Magee in gh-114099@footnote{https://github.com/python/cpython/issues/114099}.)

@item 
@code{aarch64-linux-android} and @code{x86_64-linux-android} are both
now 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} tier 3 platforms.
(@ref{164,,PEP 738} written
and implementation contributed by Malcolm Smith in gh-116622@footnote{https://github.com/python/cpython/issues/116622}.)

@item 
@code{wasm32-wasi} is now a 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} tier 2 platform.
(Contributed by Brett Cannon in gh-115192@footnote{https://github.com/python/cpython/issues/115192}.)

@item 
@code{wasm32-emscripten} is no longer a 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} supported platform.
(Contributed by Brett Cannon in gh-115192@footnote{https://github.com/python/cpython/issues/115192}.)

@item 
Building CPython now requires a compiler with support for the C11 atomic
library, GCC built-in atomic functions, or MSVC interlocked intrinsics.

@item 
Autoconf 2.71 and aclocal 1.16.5 are now required to regenerate
the @code{configure} script.
(Contributed by Christian Heimes in gh-89886@footnote{https://github.com/python/cpython/issues/89886} and by Victor Stinner in gh-112090@footnote{https://github.com/python/cpython/issues/112090}.)

@item 
SQLite 3.15.2 or newer is required to build
the @ref{ce,,sqlite3} extension module.
(Contributed by Erlend Aasland in gh-105875@footnote{https://github.com/python/cpython/issues/105875}.)

@item 
CPython now bundles the mimalloc library@footnote{https://github.com/microsoft/mimalloc/} by default.
It is licensed under the MIT license;
see @ref{407,,mimalloc license}.
The bundled mimalloc has custom changes, see gh-113141@footnote{https://github.com/python/cpython/issues/113141} for details.
(Contributed by Dino Viehland in gh-109914@footnote{https://github.com/python/cpython/issues/109914}.)

@item 
The @code{configure} option @ref{408,,--with-system-libmpdec}
now defaults to @code{yes}.
The bundled copy of @code{libmpdecimal} will be removed in Python 3.15.

@item 
Python built with @code{configure} @ref{38b,,--with-trace-refs}
(tracing references) is now ABI compatible with the Python release build
and @ref{1f6,,debug build}.
(Contributed by Victor Stinner in gh-108634@footnote{https://github.com/python/cpython/issues/108634}.)

@item 
On POSIX systems, the pkg-config (@code{.pc}) filenames now include the ABI
flags.  For example, the free-threaded build generates @code{python-3.13t.pc}
and the debug build generates @code{python-3.13d.pc}.

@item 
The @code{errno}, @code{fcntl}, @code{grp}, @code{md5}, @code{pwd}, @code{resource},
@code{termios}, @code{winsound},
@code{_ctypes_test}, @code{_multiprocessing.posixshmem}, @code{_scproxy}, @code{_stat},
@code{_statistics}, @code{_testconsole}, @code{_testimportmultiple} and @code{_uuid}
C extensions are now built with the @ref{38c,,limited C API}.
(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}.)
@end itemize

@node Porting to Python 3 13,Regression Test Changes,Changements à la compilation,What's New In Python 3 13
@anchor{whatsnew/3 13 porting-to-python-3-13}@anchor{145}
@subsection Porting to Python 3.13


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changements dans l'API Python:: 
* Changements dans l'API C:: 

@end menu

@node Changements dans l'API Python,Changements dans l'API C,,Porting to Python 3 13
@anchor{whatsnew/3 13 changes-in-the-python-api}@anchor{409}
@subsubsection Changements dans l'API Python

@anchor{whatsnew/3 13 pep667-porting-notes-py}@anchor{181}

@itemize *

@item 
@ref{141,,PEP 667} introduces several changes
to the semantics of @ref{140,,locals()} and @ref{180,,f_locals}:


@itemize *

@item 
Calling @ref{140,,locals()} in an @ref{17c,,optimized scope} now produces an
independent snapshot on each call, and hence no longer implicitly updates
previously returned references. Obtaining the legacy CPython behavior now
requires explicit calls to update the initially returned dictionary with the
results of subsequent calls to @code{locals()}. Code execution functions that
implicitly target @code{locals()} (such as @code{exec} and @code{eval}) must be
passed an explicit namespace to access their results in an optimized scope.
(Changed as part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}.)

@item 
Calling @ref{140,,locals()} from a comprehension at module or class scope
(including via @code{exec} or @code{eval}) once more behaves as if the comprehension
were running as an independent nested function (i.e. the local variables from
the containing scope are not included). In Python 3.12, this had changed
to include the local variables from the containing scope when implementing
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}. (Changed as part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}.)

@item 
Accessing @ref{180,,FrameType.f_locals} in an
@ref{17c,,optimized scope} now returns a write-through proxy rather than a
snapshot that gets updated at ill-specified times. If a snapshot is desired,
it must be created explicitly with @code{dict} or the proxy's @code{.copy()} method.
(Changed as part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}.)
@end itemize

@item 
@ref{40a,,functools.partial} now emits a @ref{40b,,FutureWarning}
when used as a method.
The behavior will change in future Python versions.
Wrap it in @ref{40c,,staticmethod()} if you want to preserve the old behavior.
(Contributed by Serhiy Storchaka in gh-121027@footnote{https://github.com/python/cpython/issues/121027}.)

@item 
An @ref{40d,,OSError} is now raised by @ref{40e,,getpass.getuser()}
for any failure to retrieve a username,
instead of @ref{40f,,ImportError} on non-Unix platforms
or @ref{33a,,KeyError} on Unix platforms where the password database is empty.

@item 
The value of the @code{mode} attribute of @ref{410,,gzip.GzipFile}
is now a string (@code{'rb'} or @code{'wb'}) instead of an integer (@code{1} or @code{2}).
The value of the @code{mode} attribute of the readable file-like object
returned by @ref{411,,zipfile.ZipFile.open()} is now @code{'rb'} instead of @code{'r'}.
(Contributed by Serhiy Storchaka in gh-115961@footnote{https://github.com/python/cpython/issues/115961}.)

@item 
@ref{412,,mailbox.Maildir} now ignores files with a leading dot (@code{.}).
(Contributed by Zackery Spytz in gh-65559@footnote{https://github.com/python/cpython/issues/65559}.)

@item 
@ref{22a,,pathlib.Path.glob()} and @ref{22b,,rglob()} now return both
files and directories if a pattern that ends with "@code{**}" is given,
rather than directories only.
Add a trailing slash to keep the previous behavior and only match directories.

@item 
The @ref{ec,,threading} module now expects the @code{_thread} module
to have an @code{_is_main_interpreter()} function.
This function takes no arguments and returns @code{True}
if the current interpreter is the main interpreter.

Any library or application that provides a custom @code{_thread} module
must provide @code{_is_main_interpreter()},
just like the module's other "private" attributes.
(gh-112826@footnote{https://github.com/python/cpython/issues/112826}.)
@end itemize

@node Changements dans l'API C,,Changements dans l'API Python,Porting to Python 3 13
@anchor{whatsnew/3 13 changes-in-the-c-api}@anchor{413}
@subsubsection Changements dans l'API C



@itemize *

@item 
@code{Python.h} no longer includes the @code{<ieeefp.h>} standard header. It was
included for the @code{finite()} function which is now provided by the
@code{<math.h>} header. It should now be included explicitly if needed. Remove
also the @code{HAVE_IEEEFP_H} macro.
(Contributed by Victor Stinner in gh-108765@footnote{https://github.com/python/cpython/issues/108765}.)

@item 
@code{Python.h} no longer includes these standard header files: @code{<time.h>},
@code{<sys/select.h>} and @code{<sys/time.h>}. If needed, they should now be
included explicitly. For example, @code{<time.h>} provides the @code{clock()} and
@code{gmtime()} functions, @code{<sys/select.h>} provides the @code{select()}
function, and @code{<sys/time.h>} provides the @code{futimes()}, @code{gettimeofday()}
and @code{setitimer()} functions.
(Contributed by Victor Stinner in gh-108765@footnote{https://github.com/python/cpython/issues/108765}.)

@item 
On Windows, @code{Python.h} no longer includes the @code{<stddef.h>} standard
header file. If needed, it should now be included explicitly. For example, it
provides @code{offsetof()} function, and @code{size_t} and @code{ptrdiff_t} types.
Including @code{<stddef.h>} explicitly was already needed by all other
platforms, the @code{HAVE_STDDEF_H} macro is only defined on Windows.
(Contributed by Victor Stinner in gh-108765@footnote{https://github.com/python/cpython/issues/108765}.)

@item 
If the @ref{414,,Py_LIMITED_API} macro is defined, @code{Py_BUILD_CORE},
@code{Py_BUILD_CORE_BUILTIN} and @code{Py_BUILD_CORE_MODULE} macros
are now undefined by @code{<Python.h>}.
(Contributed by Victor Stinner in gh-85283@footnote{https://github.com/python/cpython/issues/85283}.)

@item 
The old trashcan macros @code{Py_TRASHCAN_SAFE_BEGIN} and @code{Py_TRASHCAN_SAFE_END}
were removed. They should be replaced by the new macros @code{Py_TRASHCAN_BEGIN}
and @code{Py_TRASHCAN_END}.

A @code{tp_dealloc} function that has the old macros, such as:

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_SAFE_BEGIN(p);
    ...
    Py_TRASHCAN_SAFE_END
@}
@end example

should migrate to the new macros as follows:

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_BEGIN(p, mytype_dealloc)
    ...
    Py_TRASHCAN_END
@}
@end example

Note that @code{Py_TRASHCAN_BEGIN} has a second argument which
should be the deallocation function it is in. The new macros were
added in Python 3.8 and the old macros were deprecated in Python 3.11.
(Contributed by Irit Katriel in gh-105111@footnote{https://github.com/python/cpython/issues/105111}.)
@end itemize
@anchor{whatsnew/3 13 pep667-porting-notes-c}@anchor{182}

@itemize *

@item 
@ref{141,,PEP 667} introduces several changes
to frame-related functions:


@itemize *

@item 
The effects of mutating the dictionary returned from
@ref{34b,,PyEval_GetLocals()} in an @ref{17c,,optimized scope} have changed.
New dict entries added this way will now `only' be visible to
subsequent @ref{34b,,PyEval_GetLocals()} calls in that frame,
as @ref{415,,PyFrame_GetLocals()}, @ref{140,,locals()},
and @ref{180,,FrameType.f_locals} no longer access
the same underlying cached dictionary.
Changes made to entries for actual variable names and names added via
the write-through proxy interfaces will be overwritten on subsequent calls
to @ref{34b,,PyEval_GetLocals()} in that frame.
The recommended code update depends on how the function was being used,
so refer to the deprecation notice on the function for details.

@item 
Calling @ref{415,,PyFrame_GetLocals()} in an @ref{17c,,optimized scope}
now returns a write-through proxy rather than a snapshot
that gets updated at ill-specified times.
If a snapshot is desired, it must be created explicitly
(e.g. with @ref{416,,PyDict_Copy()}),
or by calling the new @ref{34a,,PyEval_GetFrameLocals()} API.

@item 
@code{PyFrame_FastToLocals()} and @code{PyFrame_FastToLocalsWithError()}
no longer have any effect.
Calling these functions has been redundant since Python 3.11,
when @ref{415,,PyFrame_GetLocals()} was first introduced.

@item 
@code{PyFrame_LocalsToFast()} no longer has any effect.
Calling this function is redundant now that @ref{415,,PyFrame_GetLocals()}
returns a write-through proxy for @ref{17c,,optimized scopes}.
@end itemize
@end itemize

@node Regression Test Changes,Notable changes in 3 13 1,Porting to Python 3 13,What's New In Python 3 13
@anchor{whatsnew/3 13 regression-test-changes}@anchor{417}
@subsection Regression Test Changes



@itemize *

@item 
Python built with @code{configure} @ref{418,,--with-pydebug} now
supports a @ref{175,,-X presite=package.module} command-line
option. If used, it specifies a module that should be imported early
in the lifecycle of the interpreter, before @code{site.py} is executed.
(Contributed by Łukasz Langa in gh-110769@footnote{https://github.com/python/cpython/issues/110769}.)
@end itemize

@node Notable changes in 3 13 1,,Regression Test Changes,What's New In Python 3 13
@anchor{whatsnew/3 13 notable-changes-in-3-13-1}@anchor{419}
@subsection Notable changes in 3.13.1


@menu
* sys: sys<2>. 

@end menu

@node sys<2>,,,Notable changes in 3 13 1
@anchor{whatsnew/3 13 id11}@anchor{41a}
@subsubsection `sys'



@itemize *

@item 
The previously undocumented special function @ref{41b,,sys.getobjects()},
which only exists in specialized builds of Python, may now return objects
from other interpreters than the one it's called in.
@end itemize

@node What's New In Python 3 12,Les nouveautés de Python 3 11,What's New In Python 3 13,Nouveautés de Python
@anchor{whatsnew/3 12 doc}@anchor{41c}@anchor{whatsnew/3 12 what-s-new-in-python-3-12}@anchor{41d}
@section What's New In Python 3.12


@*Éditeur: 
Adam Turner


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the issue number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :gh:`12345`.)
@c 
@c This saves the maintainer the effort of going through the VCS log when
@c researching a change.

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 the @ref{13b,,changelog}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 693
PEP 693@footnote{https://peps.python.org/pep-0693/} -- Python 3.12 Release Schedule


@menu
* Résumé – Points marquants de cette version:: 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<3>. 
* Nouvelles fonctionnalités reliées aux indications de types:: 
* Autres changements au langage: Autres changements au langage<2>. 
* Nouveaux modules: Nouveaux modules<2>. 
* Modules améliorés: Modules améliorés<2>. 
* Optimisations: Optimisations<2>. 
* Changements au code intermédiaire CPython:: 
* Demos and Tools:: 
* Obsolescence:: 
* Retraits:: 
* Porting to Python 3.12: Porting to Python 3 12. 
* Changements à la compilation: Changements à la compilation<2>. 
* Changements à l'API C: Changements à l'API C<2>. 

@end menu

@node Résumé – Points marquants de cette version,Nouvelles fonctionnalités<3>,,What's New In Python 3 12
@anchor{whatsnew/3 12 summary-release-highlights}@anchor{41e}
@subsection Résumé – Points marquants de cette version


@c This section singles out the most important changes in Python 3.12.
@c Brevity is key.

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, the @code{distutils} package has been removed from the standard library.
Filesystem support in @ref{a0,,os} and @ref{a3,,pathlib} has seen a number of improvements,
and several modules have better performance.

The language changes focus on usability,
as @ref{41f,,f-strings} have had many limitations removed
and 'Did you mean ...' suggestions continue to improve.
The new @ref{420,,type parameter syntax}
and @ref{421,,type} statement improve ergonomics for using @ref{422,,generic types} and @ref{423,,type aliases} with 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 the  @ref{143,,Library Reference}
and @ref{144,,Language 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.


__________________________________________________________________


@c PEP-sized items next.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@ref{420,,PEP 695}, type parameter syntax and the @ref{421,,type} statement
@end itemize

New grammar features:


@itemize *

@item 
@ref{424,,PEP 701}, @ref{41f,,f-strings} in the grammar
@end itemize

Améliorations de l'interpréteur :


@itemize *

@item 
@ref{425,,PEP 684}, a unique per-interpreter @ref{147,,GIL}

@item 
@ref{426,,PEP 669}, low impact monitoring

@item 
@ref{427,,Improved 'Did you mean ...' suggestions}@anchor{whatsnew/3 12 improved-error-messages}@anchor{427}
for @ref{428,,NameError}, @ref{40f,,ImportError}, and @ref{18b,,SyntaxError} exceptions
@end itemize

Python data model improvements:


@itemize *

@item 
@ref{429,,PEP 688}, using the @ref{38e,,buffer protocol} from Python
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
The @ref{226,,pathlib.Path} class now supports subclassing

@item 
The @ref{a0,,os} module received several improvements for Windows support

@item 
A @ref{42a,,command-line interface} has been added to the
@ref{ce,,sqlite3} module

@item 
@ref{42b,,isinstance()} checks against @ref{42c,,runtime-checkable protocols} enjoy a speed up of between two and 20 times

@item 
The @ref{a,,asyncio} package has had a number of performance improvements,
with some benchmarks showing a 75% speed up.

@item 
A @ref{42d,,command-line interface} has been added to the
@ref{10f,,uuid} module

@item 
Due to the changes in @ref{424,,PEP 701},
producing tokens via the @ref{fa,,tokenize} module is up to 64% faster.
@end itemize

Security improvements:


@itemize *

@item 
Replace the builtin @ref{67,,hashlib} implementations of
SHA1, SHA3, SHA2-384, SHA2-512, and MD5 with formally verified code from the
HACL*@footnote{https://github.com/hacl-star/hacl-star/} project.
These builtin implementations remain as fallbacks that are only used when
OpenSSL does not provide them.
@end itemize

C API improvements:


@itemize *

@item 
@ref{42e,,PEP 697}, unstable C API tier

@item 
@ref{42f,,PEP 683}, immortal objects
@end itemize

CPython implementation improvements:


@itemize *

@item 
@ref{430,,PEP 709}, comprehension inlining

@item 
@ref{18d,,CPython support} for the Linux @code{perf} profiler

@item 
Implement stack overflow protection on supported platforms
@end itemize

Nouvelles fonctionnalités de typage :


@itemize *

@item 
@ref{431,,PEP 692}, using @ref{161,,TypedDict} to
annotate @ref{432,,**kwargs}

@item 
@ref{433,,PEP 698}, @ref{434,,typing.override()} decorator
@end itemize

Obsolescences, retraits ou restrictions :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/}: Remove @code{wstr} from Unicode objects in Python's C API,
reducing the size of every @ref{435,,str} object by at least 8 bytes.

@item 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/}: Remove the @code{distutils} package.
See 
@geindex Python Enhancement Proposals; PEP 0632#migration-advice
the migration guide@footnote{https://peps.python.org/pep-0632/#migration-advice}
for advice replacing the APIs it provided.
The third-party Setuptools@footnote{https://setuptools.pypa.io/en/latest/deprecated/distutils-legacy.html}
package continues to provide @code{distutils},
if you still require it in Python 3.12 and beyond.

@item 
gh-95299@footnote{https://github.com/python/cpython/issues/95299}: Do not pre-install @code{setuptools} in virtual environments
created with @ref{110,,venv}.
This means that @code{distutils}, @code{setuptools}, @code{pkg_resources},
and @code{easy_install} will no longer available by default; to access these
run @code{pip install setuptools} in the @ref{436,,activated}
virtual environment.

@item 
The @code{asynchat}, @code{asyncore}, and @code{imp} modules have been
removed, along with several @ref{437,,unittest.TestCase}
@ref{438,,method aliases}@anchor{whatsnew/3 12 unittest-testcase-removed-aliases}@anchor{438}.
@end itemize

@node Nouvelles fonctionnalités<3>,Nouvelles fonctionnalités reliées aux indications de types,Résumé – Points marquants de cette version,What's New In Python 3 12
@anchor{whatsnew/3 12 new-features}@anchor{439}
@subsection Nouvelles fonctionnalités


@menu
* PEP 695; Type Parameter Syntax: PEP 695 Type Parameter Syntax. 
* PEP 701; Syntactic formalization of f-strings: PEP 701 Syntactic formalization of f-strings. 
* PEP 684; A Per-Interpreter GIL: PEP 684 A Per-Interpreter GIL. 
* PEP 669; Low impact monitoring for CPython: PEP 669 Low impact monitoring for CPython. 
* PEP 688; Making the buffer protocol accessible in Python: PEP 688 Making the buffer protocol accessible in Python. 
* PEP 709; Comprehension inlining: PEP 709 Comprehension inlining. 
* Improved Error Messages:: 

@end menu

@node PEP 695 Type Parameter Syntax,PEP 701 Syntactic formalization of f-strings,,Nouvelles fonctionnalités<3>
@anchor{whatsnew/3 12 pep-695-type-parameter-syntax}@anchor{43a}@anchor{whatsnew/3 12 whatsnew312-pep695}@anchor{420}
@subsubsection PEP 695: Type Parameter Syntax


Generic classes and functions under 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} were declared using a verbose syntax
that left the scope of type parameters unclear and required explicit declarations of
variance.

@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} introduces a new, more compact and explicit way to create
@ref{43b,,generic classes} and @ref{43c,,functions}:

@example
def max[T](args: Iterable[T]) -> T:
    ...

class list[T]:
    def __getitem__(self, index: int, /) -> T:
        ...

    def append(self, element: T) -> None:
        ...
@end example

In addition, the PEP introduces a new way to declare @ref{43d,,type aliases}
using the @ref{421,,type} statement, which creates an instance of
@ref{43e,,TypeAliasType}:

@example
type Point = tuple[float, float]
@end example

Type aliases can also be @ref{43f,,generic}:

@example
type Point[T] = tuple[T, T]
@end example

The new syntax allows declaring @ref{15e,,TypeVarTuple}
and @ref{15d,,ParamSpec} parameters, as well as @ref{15c,,TypeVar}
parameters with bounds or constraints:

@example
type IntFunc[**P] = Callable[P, int]  # ParamSpec
type LabeledTuple[*Ts] = tuple[str, *Ts]  # TypeVarTuple
type HashableSequence[T: Hashable] = Sequence[T]  # TypeVar with bound
type IntOrStrSequence[T: (int, str)] = Sequence[T]  # TypeVar with constraints
@end example

The value of type aliases and the bound and constraints of type variables
created through this syntax are evaluated only on demand (see
@ref{440,,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. See @ref{2b0,,Type parameter lists} for a detailed description of the
runtime semantics of type parameters.

In order to support these scoping semantics, a new kind of scope is introduced,
the @ref{186,,annotation scope}. Annotation scopes behave for the
most part like function scopes, but interact differently with enclosing class scopes.
In Python 3.13, @ref{441,,annotations} will also be evaluated in
annotation scopes.

See 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} for more details.

(PEP written by Eric Traut. Implementation by Jelle Zijlstra, Eric Traut,
and others in gh-103764@footnote{https://github.com/python/cpython/issues/103764}.)

@node PEP 701 Syntactic formalization of f-strings,PEP 684 A Per-Interpreter GIL,PEP 695 Type Parameter Syntax,Nouvelles fonctionnalités<3>
@anchor{whatsnew/3 12 pep-701-syntactic-formalization-of-f-strings}@anchor{442}@anchor{whatsnew/3 12 whatsnew312-pep701}@anchor{424}
@subsubsection PEP 701: Syntactic formalization of f-strings


@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/} lifts some restrictions on the usage of @ref{41f,,f-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:


@itemize *

@item 
Quote reuse: in Python 3.11, reusing the same quotes as the enclosing f-string
raises a @ref{18b,,SyntaxError}, 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:

@example
>>> 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'
@end example

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:

@example
>>> f"""@{f'@w{'}'@{f'@{f"@{1+1@}"@}'@}'@w{'}'@}"""
'2'
@end example

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

@example
>>> f"@{f"@{f"@{f"@{f"@{f"@{1+1@}"@}"@}"@}"@}"@}"
'2'
@end example

@item 
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:

@example
>>> 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'
@end example

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

@example
>>> 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
@end example
@end itemize

See 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/} for more details.

As a positive side-effect of how this feature has been implemented (by parsing f-strings
with 
@geindex Python Enhancement Proposals; PEP 617
the PEG parser@footnote{https://peps.python.org/pep-0617/}), 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 a @ref{18b,,SyntaxError}:

@example
>>> my_string = f"@{x z y@}" + f"@{1 + 1@}"
  File "<stdin>", line 1
    (x z y)
     ^^^
SyntaxError: f-string: invalid syntax. Perhaps you forgot a comma?
@end example

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:

@example
>>> my_string = f"@{x z y@}" + f"@{1 + 1@}"
  File "<stdin>", line 1
    my_string = f"@{x z y@}" + f"@{1 + 1@}"
                   ^^^
SyntaxError: invalid syntax. Perhaps you forgot a comma?
@end example

(Contributed by Pablo Galindo, Batuhan Taskaya, Lysandros Nikolaou, Cristián
Maureira-Fredes and Marta Gómez in gh-102856@footnote{https://github.com/python/cpython/issues/102856}. PEP written by Pablo Galindo,
Batuhan Taskaya, Lysandros Nikolaou and Marta Gómez).

@node PEP 684 A Per-Interpreter GIL,PEP 669 Low impact monitoring for CPython,PEP 701 Syntactic formalization of f-strings,Nouvelles fonctionnalités<3>
@anchor{whatsnew/3 12 pep-684-a-per-interpreter-gil}@anchor{444}@anchor{whatsnew/3 12 whatsnew312-pep684}@anchor{425}
@subsubsection PEP 684: A Per-Interpreter GIL


@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/} introduces a per-interpreter @ref{147,,GIL},
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 is 
@geindex Python Enhancement Proposals; PEP 554
anticipated for 3.13@footnote{https://peps.python.org/pep-0554/}.

Use the new @ref{445,,Py_NewInterpreterFromConfig()} function to
create an interpreter with its own GIL:

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

For further examples how to use the C-API for sub-interpreters with a
per-interpreter GIL, see @code{Modules/_xxsubinterpretersmodule.c}.

(Contributed by Eric Snow in gh-104210@footnote{https://github.com/python/cpython/issues/104210}, etc.)

@node PEP 669 Low impact monitoring for CPython,PEP 688 Making the buffer protocol accessible in Python,PEP 684 A Per-Interpreter GIL,Nouvelles fonctionnalités<3>
@anchor{whatsnew/3 12 pep-669-low-impact-monitoring-for-cpython}@anchor{446}@anchor{whatsnew/3 12 whatsnew312-pep669}@anchor{426}
@subsubsection PEP 669: Low impact monitoring for CPython


@geindex Python Enhancement Proposals; PEP 669
PEP 669@footnote{https://peps.python.org/pep-0669/} defines a new @ref{d9,,API} for 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.
See  @ref{d9,,sys.monitoring} for details.

(Contributed by Mark Shannon in gh-103082@footnote{https://github.com/python/cpython/issues/103082}.)

@node PEP 688 Making the buffer protocol accessible in Python,PEP 709 Comprehension inlining,PEP 669 Low impact monitoring for CPython,Nouvelles fonctionnalités<3>
@anchor{whatsnew/3 12 pep-688-making-the-buffer-protocol-accessible-in-python}@anchor{447}@anchor{whatsnew/3 12 whatsnew312-pep688}@anchor{429}
@subsubsection PEP 688: Making the buffer protocol accessible in Python


@geindex Python Enhancement Proposals; PEP 688
PEP 688@footnote{https://peps.python.org/pep-0688/} introduces a way to use the @ref{38e,,buffer protocol}
from Python code. Classes that implement the @ref{448,,__buffer__()} method
are now usable as buffer types.

The new @ref{2c1,,collections.abc.Buffer} ABC provides a standard
way to represent buffer objects, for example in type annotations.
The new @ref{449,,inspect.BufferFlags} enum represents the flags that
can be used to customize buffer creation.
(Contributed by Jelle Zijlstra in gh-102500@footnote{https://github.com/python/cpython/issues/102500}.)

@node PEP 709 Comprehension inlining,Improved Error Messages,PEP 688 Making the buffer protocol accessible in Python,Nouvelles fonctionnalités<3>
@anchor{whatsnew/3 12 pep-709-comprehension-inlining}@anchor{44a}@anchor{whatsnew/3 12 whatsnew312-pep709}@anchor{430}
@subsubsection 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.
See 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/} for 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:


@itemize *

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

@item 
The @ref{d7,,symtable} module 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.

@item 
Calling @ref{140,,locals()} inside a comprehension now includes variables
from outside the comprehension, and no longer includes the synthetic @code{.0}
variable for the comprehension "argument".

@item 
A comprehension iterating directly over @code{locals()} (e.g. @code{[k for k in
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. @code{for k in locals():}. To avoid the error, first
create a list of keys to iterate over: @code{keys = list(locals()); [k for k in
keys]}.
@end itemize

(Contributed by Carl Meyer and Vladimir Matveev in 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}.)

@node Improved Error Messages,,PEP 709 Comprehension inlining,Nouvelles fonctionnalités<3>

@subsubsection Improved Error Messages



@itemize *

@item 
Modules from the standard library are now potentially suggested as part of
the error messages displayed by the interpreter when a @ref{428,,NameError} is
raised to the top level. (Contributed by Pablo Galindo in gh-98254@footnote{https://github.com/python/cpython/issues/98254}.)

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

@item 
Improve the error suggestion for @ref{428,,NameError} exceptions for instances.
Now if a @ref{428,,NameError} is raised in a method and the instance has an
attribute that's exactly equal to the name in the exception, the suggestion
will include @code{self.<NAME>} instead of the closest match in the method
scope. (Contributed by Pablo Galindo in gh-99139@footnote{https://github.com/python/cpython/issues/99139}.)

@example
>>> class A:
...    def __init__(self):
...        self.blech = 1
...
...    def foo(self):
...        somethin = blech
...
>>> A().foo()
Traceback (most recent call last):
  File "<stdin>", line 1
    somethin = blech
               ^^^^^
NameError: name 'blech' is not defined. Did you mean: 'self.blech'?
@end example

@item 
Improve the @ref{18b,,SyntaxError} error message when the user types @code{import x
from y} instead of @code{from y import x}. (Contributed by Pablo Galindo in gh-98931@footnote{https://github.com/python/cpython/issues/98931}.)

@example
>>> import a.y.z from b.y.z
Traceback (most recent call last):
  File "<stdin>", line 1
    import a.y.z from b.y.z
    ^^^^^^^^^^^^^^^^^^^^^^^
SyntaxError: Did you mean to use 'from ... import ...' instead?
@end example

@item 
@ref{40f,,ImportError} exceptions raised from failed @code{from <module> import
<name>} statements now include suggestions for the value of @code{<name>} based on the
available names in @code{<module>}. (Contributed by Pablo Galindo in gh-91058@footnote{https://github.com/python/cpython/issues/91058}.)

@example
>>> from collections import chainmap
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: cannot import name 'chainmap' from 'collections'. Did you mean: 'ChainMap'?
@end example
@end itemize

@node Nouvelles fonctionnalités reliées aux indications de types,Autres changements au langage<2>,Nouvelles fonctionnalités<3>,What's New In Python 3 12
@anchor{whatsnew/3 12 new-features-related-to-type-hints}@anchor{44b}
@subsection Nouvelles fonctionnalités reliées aux indications de types


This section covers major changes affecting 
@geindex Python Enhancement Proposals; PEP 484
type hints@footnote{https://peps.python.org/pep-0484/} and
the @ref{103,,typing} module.

@menu
* PEP 692; Using TypedDict for more precise **kwargs typing: PEP 692 Using TypedDict for more precise **kwargs typing. 
* PEP 698; Override Decorator for Static Typing: PEP 698 Override Decorator for Static Typing. 

@end menu

@node PEP 692 Using TypedDict for more precise **kwargs typing,PEP 698 Override Decorator for Static Typing,,Nouvelles fonctionnalités reliées aux indications de types
@anchor{whatsnew/3 12 pep-692-using-typeddict-for-more-precise-kwargs-typing}@anchor{44c}@anchor{whatsnew/3 12 whatsnew312-pep692}@anchor{431}
@subsubsection PEP 692: Using @code{TypedDict} for more precise @code{**kwargs} typing


Typing @code{**kwargs} in a function signature as introduced by 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} allowed
for valid annotations only in cases where all of the @code{**kwargs} were of the
same type.

@geindex Python Enhancement Proposals; PEP 692
PEP 692@footnote{https://peps.python.org/pep-0692/} specifies a more precise way of typing @code{**kwargs} by relying on
typed dictionaries:

@example
from typing import TypedDict, Unpack

class Movie(TypedDict):
  name: str
  year: int

def foo(**kwargs: Unpack[Movie]): ...
@end example

See 
@geindex Python Enhancement Proposals; PEP 692
PEP 692@footnote{https://peps.python.org/pep-0692/} for more details.

(Contributed by Franek Magiera in gh-103629@footnote{https://github.com/python/cpython/issues/103629}.)

@node PEP 698 Override Decorator for Static Typing,,PEP 692 Using TypedDict for more precise **kwargs typing,Nouvelles fonctionnalités reliées aux indications de types
@anchor{whatsnew/3 12 pep-698-override-decorator-for-static-typing}@anchor{44d}@anchor{whatsnew/3 12 whatsnew312-pep698}@anchor{433}
@subsubsection PEP 698: Override Decorator for Static Typing


A new decorator @ref{434,,typing.override()} has been added to the @ref{103,,typing}
module. It indicates to type checkers that the method is intended to override
a method in a superclass. This allows type checkers to catch mistakes where
a method that is intended to override something in a base class
does not in fact do so.

Exemple :

@example
from typing import override

class Base:
  def get_color(self) -> str:
    return "blue"

class GoodChild(Base):
  @@override  # ok: overrides Base.get_color
  def get_color(self) -> str:
    return "yellow"

class BadChild(Base):
  @@override  # type checker error: does not override Base.get_color
  def get_colour(self) -> str:
    return "red"
@end example

See 
@geindex Python Enhancement Proposals; PEP 698
PEP 698@footnote{https://peps.python.org/pep-0698/} for more details.

(Contributed by Steven Troxler in gh-101561@footnote{https://github.com/python/cpython/issues/101561}.)

@node Autres changements au langage<2>,Nouveaux modules<2>,Nouvelles fonctionnalités reliées aux indications de types,What's New In Python 3 12
@anchor{whatsnew/3 12 other-language-changes}@anchor{44e}
@subsection Autres changements au langage



@itemize *

@item 
The parser now raises @ref{18b,,SyntaxError} when parsing source code containing
null bytes. (Contributed by Pablo Galindo in gh-96670@footnote{https://github.com/python/cpython/issues/96670}.)

@item 
A backslash-character pair that is not a valid escape sequence now generates
a @ref{44f,,SyntaxWarning}, instead of @ref{1a3,,DeprecationWarning}.
For example, @code{re.compile("\d+\.\d+")} now emits a @ref{44f,,SyntaxWarning}
(@code{"\d"} is an invalid escape sequence, use raw strings for regular
expression: @code{re.compile(r"\d+\.\d+")}).
In a future Python version, @ref{18b,,SyntaxError} will eventually be raised,
instead of @ref{44f,,SyntaxWarning}.
(Contributed by Victor Stinner in gh-98401@footnote{https://github.com/python/cpython/issues/98401}.)

@item 
Octal escapes with value larger than @code{0o377} (ex: @code{"\477"}), deprecated
in Python 3.11, now produce a @ref{44f,,SyntaxWarning}, instead of
@ref{1a3,,DeprecationWarning}.
In a future Python version they will be eventually a @ref{18b,,SyntaxError}.
(Contributed by Victor Stinner in gh-98401@footnote{https://github.com/python/cpython/issues/98401}.)

@item 
Variables used in the target part of comprehensions that are not stored to
can now be used in assignment expressions (@code{:=}).
For example, in @code{[(b := 1) for a, b.prop in some_iter]}, the assignment to
@code{b} is now allowed. Note that assigning to variables stored to in the target
part of comprehensions (like @code{a}) is still disallowed, as per 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}.
(Contributed by Nikita Sobolev in gh-100581@footnote{https://github.com/python/cpython/issues/100581}.)

@item 
Exceptions raised in a class or type's @code{__set_name__} method are no longer
wrapped by a @ref{193,,RuntimeError}. Context information is added to the
exception as a 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/} note. (Contributed by Irit Katriel in gh-77757@footnote{https://github.com/python/cpython/issues/77757}.)

@item 
When a @code{try-except*} construct handles the entire @ref{1b4,,ExceptionGroup}
and raises one other exception, that exception is no longer wrapped in an
@ref{1b4,,ExceptionGroup}. Also changed in version 3.11.4. (Contributed by Irit
Katriel in gh-103590@footnote{https://github.com/python/cpython/issues/103590}.)

@item 
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 when @ref{450,,PyErr_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@footnote{https://github.com/python/cpython/issues/97922}.)

@item 
All builtin and extension callables expecting boolean parameters now accept
arguments of any type instead of just @ref{451,,bool} and @ref{254,,int}.
(Contributed by Serhiy Storchaka in gh-60203@footnote{https://github.com/python/cpython/issues/60203}.)

@item 
@ref{452,,memoryview} now supports the half-float type (the "e" format code).
(Contributed by Donghee Na and Antoine Pitrou in gh-90751@footnote{https://github.com/python/cpython/issues/90751}.)

@item 
@ref{453,,slice} objects are now hashable, allowing them to be used as dict keys and
set items. (Contributed by Will Bradshaw, Furkan Onder, and Raymond Hettinger in gh-101264@footnote{https://github.com/python/cpython/issues/101264}.)

@item 
@ref{454,,sum()} now uses Neumaier summation to improve accuracy and commutativity
when summing floats or mixed ints and floats.
(Contributed by Raymond Hettinger in gh-100425@footnote{https://github.com/python/cpython/issues/100425}.)

@item 
@ref{1a6,,ast.parse()} now raises @ref{18b,,SyntaxError} instead of @ref{1ff,,ValueError}
when parsing source code containing null bytes. (Contributed by Pablo Galindo
in gh-96670@footnote{https://github.com/python/cpython/issues/96670}.)

@item 
The extraction methods in @ref{dd,,tarfile}, and @ref{455,,shutil.unpack_archive()},
have a new a `filter' argument that allows limiting tar features than may be
surprising or dangerous, such as creating files outside the destination
directory.
See @ref{456,,tarfile extraction filters} for details.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)

@item 
@ref{457,,types.MappingProxyType} instances are now hashable if the underlying
mapping is hashable.
(Contributed by Serhiy Storchaka in gh-87995@footnote{https://github.com/python/cpython/issues/87995}.)

@item 
Add @ref{18d,,support for the perf profiler} through the new
environment variable 
@geindex PYTHONPERFSUPPORT
@geindex variable d'environnement; PYTHONPERFSUPPORT
@ref{458,,PYTHONPERFSUPPORT}
and command-line option @ref{175,,-X perf},
as well as the new @ref{459,,sys.activate_stack_trampoline()},
@ref{45a,,sys.deactivate_stack_trampoline()},
and @ref{45b,,sys.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
in gh-96123@footnote{https://github.com/python/cpython/issues/96123}.)
@end itemize

@node Nouveaux modules<2>,Modules améliorés<2>,Autres changements au langage<2>,What's New In Python 3 12
@anchor{whatsnew/3 12 new-modules}@anchor{45c}
@subsection Nouveaux modules



@itemize *

@item 
None.
@end itemize

@node Modules améliorés<2>,Optimisations<2>,Nouveaux modules<2>,What's New In Python 3 12
@anchor{whatsnew/3 12 improved-modules}@anchor{45d}
@subsection Modules améliorés


@menu
* array: array<2>. 
* asyncio: asyncio<2>. 
* calendar:: 
* csv:: 
* dis: dis<2>. 
* fractions: fractions<2>. 
* importlib.resources: importlib resources. 
* inspect:: 
* itertools: itertools<2>. 
* math: math<2>. 
* os: os<2>. 
* os.path: os path<2>. 
* pathlib: pathlib<3>. 
* pdb: pdb<2>. 
* random: random<2>. 
* shutils: shutils<2>. 
* sqlite3: sqlite3<2>. 
* statistics: statistics<2>. 
* sys: sys<3>. 
* tempfile: tempfile<2>. 
* threading:: 
* tkinter: tkinter<2>. 
* tokenize:: 
* types: types<2>. 
* typing: typing<3>. 
* unicodedata: unicodedata<2>. 
* unittest: unittest<2>. 
* uuid:: 

@end menu

@node array<2>,asyncio<2>,,Modules améliorés<2>
@anchor{whatsnew/3 12 array}@anchor{45e}
@subsubsection `array'



@itemize *

@item 
The @ref{19e,,array.array} class now supports subscripting, making it a
@ref{422,,generic type}. (Contributed by Jelle Zijlstra in gh-98658@footnote{https://github.com/python/cpython/issues/98658}.)
@end itemize

@node asyncio<2>,calendar,array<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 asyncio}@anchor{45f}
@subsubsection `asyncio'



@itemize *

@item 
The performance of writing to sockets in @ref{a,,asyncio} has been
significantly improved. @code{asyncio} now avoids unnecessary copying when
writing to sockets and uses @ref{460,,sendmsg()} if the platform
supports it. (Contributed by Kumar Aditya in gh-91166@footnote{https://github.com/python/cpython/issues/91166}.)

@item 
Add @ref{461,,asyncio.eager_task_factory()} and @ref{462,,asyncio.create_eager_task_factory()}
functions to allow opting an event loop in to eager task execution,
making some use-cases 2x to 5x faster.
(Contributed by Jacob Bower & Itamar Oren in gh-102853@footnote{https://github.com/python/cpython/issues/102853}, gh-104140@footnote{https://github.com/python/cpython/issues/104140}, and gh-104138@footnote{https://github.com/python/cpython/issues/104138})

@item 
On Linux, @ref{a,,asyncio} uses @ref{463,,asyncio.PidfdChildWatcher} by default
if @ref{464,,os.pidfd_open()} is available and functional instead of
@ref{465,,asyncio.ThreadedChildWatcher}.
(Contributed by Kumar Aditya in gh-98024@footnote{https://github.com/python/cpython/issues/98024}.)

@item 
The event loop now uses the best available child watcher for each platform
(@ref{463,,asyncio.PidfdChildWatcher} if supported and
@ref{465,,asyncio.ThreadedChildWatcher} otherwise), so manually
configuring a child watcher is not recommended.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
Add `loop_factory' parameter to @ref{466,,asyncio.run()} to allow specifying
a custom event loop factory.
(Contributed by Kumar Aditya in gh-99388@footnote{https://github.com/python/cpython/issues/99388}.)

@item 
Add C implementation of @ref{467,,asyncio.current_task()} for 4x-6x speedup.
(Contributed by Itamar Oren and Pranav Thulasiram Bhat in gh-100344@footnote{https://github.com/python/cpython/issues/100344}.)

@item 
@ref{468,,asyncio.iscoroutine()} now returns @code{False} for generators as
@ref{a,,asyncio} does not support legacy generator-based coroutines.
(Contributed by Kumar Aditya in gh-102748@footnote{https://github.com/python/cpython/issues/102748}.)

@item 
@ref{469,,asyncio.wait()} and @ref{1a8,,asyncio.as_completed()} now accepts generators
yielding tasks.
(Contributed by Kumar Aditya in gh-78530@footnote{https://github.com/python/cpython/issues/78530}.)
@end itemize

@node calendar,csv,asyncio<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 calendar}@anchor{46a}
@subsubsection calendar



@itemize *

@item 
Add enums @ref{46b,,calendar.Month} and @ref{46c,,calendar.Day}
defining months of the year and days of the week.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)
@end itemize

@node csv,dis<2>,calendar,Modules améliorés<2>
@anchor{whatsnew/3 12 csv}@anchor{46d}
@subsubsection csv



@itemize *

@item 
Add @ref{46e,,csv.QUOTE_NOTNULL} and @ref{46f,,csv.QUOTE_STRINGS} flags to
provide finer grained control of @code{None} and empty strings by
@ref{470,,reader} and @ref{471,,writer} objects.
@end itemize

@node dis<2>,fractions<2>,csv,Modules améliorés<2>
@anchor{whatsnew/3 12 dis}@anchor{472}
@subsubsection dis



@itemize *

@item 
Pseudo instruction opcodes (which are used by the compiler but
do not appear in executable bytecode) are now exposed in the
@ref{38,,dis} module.
@ref{473,,HAVE_ARGUMENT} is still relevant to real opcodes,
but it is not useful for pseudo instructions. Use the new
@ref{29b,,dis.hasarg} collection instead.
(Contributed by Irit Katriel in gh-94216@footnote{https://github.com/python/cpython/issues/94216}.)

@item 
Add the @ref{474,,dis.hasexc} collection to signify instructions that set
an exception handler. (Contributed by Irit Katriel in gh-94216@footnote{https://github.com/python/cpython/issues/94216}.)
@end itemize

@node fractions<2>,importlib resources,dis<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 fractions}@anchor{475}
@subsubsection @code{fractions}



@itemize *

@item 
Objects of type @ref{1e4,,fractions.Fraction} now support float-style
formatting. (Contributed by Mark Dickinson in gh-100161@footnote{https://github.com/python/cpython/issues/100161}.)
@end itemize

@node importlib resources,inspect,fractions<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 importlib-resources}@anchor{476}
@subsubsection importlib.resources



@itemize *

@item 
@ref{477,,importlib.resources.as_file()} now supports resource directories.
(Contributed by Jason R. Coombs in gh-97930@footnote{https://github.com/python/cpython/issues/97930}.)

@item 
Rename first parameter of @ref{478,,importlib.resources.files()} to `anchor'.
(Contributed by Jason R. Coombs in gh-100598@footnote{https://github.com/python/cpython/issues/100598}.)
@end itemize

@node inspect,itertools<2>,importlib resources,Modules améliorés<2>
@anchor{whatsnew/3 12 inspect}@anchor{479}
@subsubsection `inspect'



@itemize *

@item 
Add @ref{47a,,inspect.markcoroutinefunction()} to mark sync functions that return
a @ref{47b,,coroutine} for use with @ref{2e2,,inspect.iscoroutinefunction()}.
(Contributed by Carlton Gibson in gh-99247@footnote{https://github.com/python/cpython/issues/99247}.)

@item 
Add @ref{47c,,inspect.getasyncgenstate()} and @ref{47d,,inspect.getasyncgenlocals()}
for determining the current state of asynchronous generators.
(Contributed by Thomas Krennwallner in gh-79940@footnote{https://github.com/python/cpython/issues/79940}.)

@item 
The performance of @ref{47e,,inspect.getattr_static()} has been considerably
improved. Most calls to the function should be at least 2x faster than they
were in Python 3.11. (Contributed by Alex Waygood in gh-103193@footnote{https://github.com/python/cpython/issues/103193}.)
@end itemize

@node itertools<2>,math<2>,inspect,Modules améliorés<2>
@anchor{whatsnew/3 12 itertools}@anchor{47f}
@subsubsection itertools



@itemize *

@item 
Add @ref{1fe,,itertools.batched()} for collecting into even-sized
tuples where the last batch may be shorter than the rest.
(Contributed by Raymond Hettinger in gh-98363@footnote{https://github.com/python/cpython/issues/98363}.)
@end itemize

@node math<2>,os<2>,itertools<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 math}@anchor{480}
@subsubsection `math'



@itemize *

@item 
Add @ref{481,,math.sumprod()} for computing a sum of products.
(Contributed by Raymond Hettinger in gh-100485@footnote{https://github.com/python/cpython/issues/100485}.)

@item 
Extend @ref{482,,math.nextafter()} to include a `steps' argument
for moving up or down multiple steps at a time. (Contributed by
Matthias Goergens, Mark Dickinson, and Raymond Hettinger in gh-94906@footnote{https://github.com/python/cpython/issues/94906}.)
@end itemize

@node os<2>,os path<2>,math<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 os}@anchor{483}
@subsubsection `os'



@itemize *

@item 
Add @ref{484,,os.PIDFD_NONBLOCK} to open a file descriptor
for a process with @ref{464,,os.pidfd_open()} in non-blocking mode.
(Contributed by Kumar Aditya in gh-93312@footnote{https://github.com/python/cpython/issues/93312}.)

@item 
@ref{485,,os.DirEntry} now includes an @ref{486,,os.DirEntry.is_junction()}
method to check if the entry is a junction.
(Contributed by Charles Machalow in gh-99547@footnote{https://github.com/python/cpython/issues/99547}.)

@item 
Add @ref{487,,os.listdrives()}, @ref{488,,os.listvolumes()} and @ref{489,,os.listmounts()}
functions on Windows for enumerating drives, volumes and mount points.
(Contributed by Steve Dower in gh-102519@footnote{https://github.com/python/cpython/issues/102519}.)

@item 
@ref{48a,,os.stat()} and @ref{48b,,os.lstat()} are now more accurate on Windows.
The @code{st_birthtime} field will now be filled with the creation time
of the file, and @code{st_ctime} is deprecated but still contains the
creation time (but in the future will return the last metadata change,
for consistency with other platforms). @code{st_dev} may be up to 64 bits
and @code{st_ino} up to 128 bits depending on your file system, and
@code{st_rdev} is always set to zero rather than incorrect values.
Both functions may be significantly faster on newer releases of
Windows. (Contributed by Steve Dower in gh-99726@footnote{https://github.com/python/cpython/issues/99726}.)
@end itemize

@node os path<2>,pathlib<3>,os<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 os-path}@anchor{48c}
@subsubsection @code{os.path}



@itemize *

@item 
Add @ref{48d,,os.path.isjunction()} to check if a given path is a junction.
(Contributed by Charles Machalow in gh-99547@footnote{https://github.com/python/cpython/issues/99547}.)

@item 
Add @ref{48e,,os.path.splitroot()} to split a path into a triad
@code{(drive, root, tail)}. (Contributed by Barney Gale in gh-101000@footnote{https://github.com/python/cpython/issues/101000}.)
@end itemize

@node pathlib<3>,pdb<2>,os path<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 pathlib}@anchor{48f}
@subsubsection `pathlib'



@itemize *

@item 
Add support for subclassing @ref{490,,pathlib.PurePath} and
@ref{226,,pathlib.Path}, plus their Posix- and Windows-specific variants.
Subclasses may override the @ref{491,,pathlib.PurePath.with_segments()} method
to pass information between path instances.

@item 
Add @ref{492,,pathlib.Path.walk()} for walking the directory trees and generating
all file or directory names within them, similar to @ref{493,,os.walk()}.
(Contributed by Stanislav Zmiev in gh-90385@footnote{https://github.com/python/cpython/issues/90385}.)

@item 
Add `walk_up' optional parameter to @ref{2c8,,pathlib.PurePath.relative_to()}
to allow the insertion of @code{..} entries in the result; this behavior is
more consistent with @ref{494,,os.path.relpath()}.
(Contributed by Domenico Ragusa in gh-84538@footnote{https://github.com/python/cpython/issues/84538}.)

@item 
Add @ref{495,,pathlib.Path.is_junction()} as a proxy to @ref{48d,,os.path.isjunction()}.
(Contributed by Charles Machalow in gh-99547@footnote{https://github.com/python/cpython/issues/99547}.)

@item 
Add `case_sensitive' optional parameter to @ref{22a,,pathlib.Path.glob()},
@ref{22b,,pathlib.Path.rglob()} and @ref{496,,pathlib.PurePath.match()} for matching
the path's case sensitivity, allowing for more precise control over the matching process.
@end itemize

@node pdb<2>,random<2>,pathlib<3>,Modules améliorés<2>
@anchor{whatsnew/3 12 pdb}@anchor{497}
@subsubsection `pdb'



@itemize *

@item 
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 in gh-103693@footnote{https://github.com/python/cpython/issues/103693}.)
@end itemize

@node random<2>,shutils<2>,pdb<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 random}@anchor{498}
@subsubsection `random'



@itemize *

@item 
Add @ref{499,,random.binomialvariate()}.
(Contributed by Raymond Hettinger in gh-81620@footnote{https://github.com/python/cpython/issues/81620}.)

@item 
Add a default of @code{lambd=1.0} to @ref{49a,,random.expovariate()}.
(Contributed by Raymond Hettinger in gh-100234@footnote{https://github.com/python/cpython/issues/100234}.)
@end itemize

@node shutils<2>,sqlite3<2>,random<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 shutil}@anchor{49b}
@subsubsection @code{shutils}



@itemize *

@item 
@ref{49c,,shutil.make_archive()} now passes the `root_dir' argument to custom
archivers which support it.
In this case it no longer temporarily changes the current working directory
of the process to `root_dir' to perform archiving.
(Contributed by Serhiy Storchaka in gh-74696@footnote{https://github.com/python/cpython/issues/74696}.)

@item 
@ref{2f5,,shutil.rmtree()} now accepts a new argument `onexc' which is an
error handler like `onerror' but which expects an exception instance
rather than a `(typ, val, tb)' triplet. `onerror' is deprecated.
(Contributed by Irit Katriel in gh-102828@footnote{https://github.com/python/cpython/issues/102828}.)

@item 
@ref{49d,,shutil.which()} now consults the `PATHEXT' environment variable to
find matches within `PATH' on Windows even when the given `cmd' includes
a directory component.
(Contributed by Charles Machalow in gh-103179@footnote{https://github.com/python/cpython/issues/103179}.)

@ref{49d,,shutil.which()} will call @code{NeedCurrentDirectoryForExePathW} when
querying for executables on Windows to determine if the current working
directory should be prepended to the search path.
(Contributed by Charles Machalow in gh-103179@footnote{https://github.com/python/cpython/issues/103179}.)

@ref{49d,,shutil.which()} will return a path matching the `cmd' with a component
from @code{PATHEXT} prior to a direct match elsewhere in the search path on
Windows.
(Contributed by Charles Machalow in gh-103179@footnote{https://github.com/python/cpython/issues/103179}.)
@end itemize

@node sqlite3<2>,statistics<2>,shutils<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 sqlite3}@anchor{49e}
@subsubsection @code{sqlite3}



@itemize *

@item 
Add a @ref{42a,,command-line interface}.
(Contributed by Erlend E. Aasland in gh-77617@footnote{https://github.com/python/cpython/issues/77617}.)

@item 
Add the @ref{49f,,sqlite3.Connection.autocommit} attribute
to @ref{242,,sqlite3.Connection}
and the `autocommit' parameter to @ref{2a5,,sqlite3.connect()}
to control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant
@ref{4a0,,transaction handling}.
(Contributed by Erlend E. Aasland in gh-83638@footnote{https://github.com/python/cpython/issues/83638}.)

@item 
Add `entrypoint' keyword-only parameter to
@ref{4a1,,sqlite3.Connection.load_extension()},
for overriding the SQLite extension entry point.
(Contributed by Erlend E. Aasland in gh-103015@footnote{https://github.com/python/cpython/issues/103015}.)

@item 
Add @ref{4a2,,sqlite3.Connection.getconfig()} and
@ref{4a3,,sqlite3.Connection.setconfig()} to @ref{242,,sqlite3.Connection}
to make configuration changes to a database connection.
(Contributed by Erlend E. Aasland in gh-103489@footnote{https://github.com/python/cpython/issues/103489}.)
@end itemize

@node statistics<2>,sys<3>,sqlite3<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 statistics}@anchor{4a4}
@subsubsection @code{statistics}



@itemize *

@item 
Extend @ref{4a5,,statistics.correlation()} to include as a @code{ranked} method
for computing the Spearman correlation of ranked data.
(Contributed by Raymond Hettinger in gh-95861@footnote{https://github.com/python/cpython/issues/95861}.)
@end itemize

@node sys<3>,tempfile<2>,statistics<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 sys}@anchor{4a6}
@subsubsection `sys'



@itemize *

@item 
Add the @ref{d9,,sys.monitoring} namespace to expose the new @ref{426,,PEP 669} monitoring API.
(Contributed by Mark Shannon in gh-103082@footnote{https://github.com/python/cpython/issues/103082}.)

@item 
Add @ref{459,,sys.activate_stack_trampoline()} and
@ref{45a,,sys.deactivate_stack_trampoline()} for activating and deactivating
stack profiler trampolines,
and @ref{45b,,sys.is_stack_trampoline_active()} for querying if stack profiler
trampolines are active.
(Contributed by Pablo Galindo and Christian Heimes
with contributions from Gregory P. Smith [Google] and Mark Shannon
in gh-96123@footnote{https://github.com/python/cpython/issues/96123}.)

@item 
Add @ref{4a7,,sys.last_exc} which holds the last unhandled exception that
was raised (for post-mortem debugging use cases). Deprecate the
three fields that have the same information in its legacy form:
@ref{4a8,,sys.last_type}, @ref{4a9,,sys.last_value} and @ref{4aa,,sys.last_traceback}.
(Contributed by Irit Katriel in gh-102778@footnote{https://github.com/python/cpython/issues/102778}.)

@item 
@ref{4ab,,sys._current_exceptions()} now returns a mapping from thread-id to an
exception instance, rather than to a @code{(typ, exc, tb)} tuple.
(Contributed by Irit Katriel in gh-103176@footnote{https://github.com/python/cpython/issues/103176}.)

@item 
@ref{4ac,,sys.setrecursionlimit()} and @ref{4ad,,sys.getrecursionlimit()}.
The recursion limit now applies only to Python code. Builtin functions do
not use the recursion limit, but are protected by a different mechanism
that prevents recursion from causing a virtual machine crash.
@end itemize

@node tempfile<2>,threading,sys<3>,Modules améliorés<2>
@anchor{whatsnew/3 12 tempfile}@anchor{4ae}
@subsubsection tempfile



@itemize *

@item 
The @ref{4af,,tempfile.NamedTemporaryFile} function has a new optional parameter
`delete_on_close' (Contributed by Evgeny Zorin in gh-58451@footnote{https://github.com/python/cpython/issues/58451}.)

@item 
@ref{21c,,tempfile.mkdtemp()} now always returns an absolute path, even if the
argument provided to the `dir' parameter is a relative path.
@end itemize

@node threading,tkinter<2>,tempfile<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 threading}@anchor{4b0}
@subsubsection threading



@itemize *

@item 
Add @ref{4b1,,threading.settrace_all_threads()} and
@ref{4b2,,threading.setprofile_all_threads()} that allow to set tracing and
profiling functions in all running threads in addition to the calling one.
(Contributed by Pablo Galindo in gh-93503@footnote{https://github.com/python/cpython/issues/93503}.)
@end itemize

@node tkinter<2>,tokenize,threading,Modules améliorés<2>
@anchor{whatsnew/3 12 tkinter}@anchor{4b3}
@subsubsection tkinter



@itemize *

@item 
@code{tkinter.Canvas.coords()} now flattens its arguments.
It now accepts not only coordinates as separate arguments
(@code{x1, y1, x2, y2, ...}) and a sequence of coordinates
(@code{[x1, y1, x2, y2, ...]}), but also coordinates grouped in pairs
(@code{(x1, y1), (x2, y2), ...} and @code{[(x1, y1), (x2, y2), ...]}),
like @code{create_*()} methods.
(Contributed by Serhiy Storchaka in gh-94473@footnote{https://github.com/python/cpython/issues/94473}.)
@end itemize

@node tokenize,types<2>,tkinter<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 tokenize}@anchor{4b4}
@subsubsection tokenize



@itemize *

@item 
The @ref{fa,,tokenize} module includes the changes introduced in 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/}.
(Contributed by Marta Gómez Macías and Pablo Galindo in gh-102856@footnote{https://github.com/python/cpython/issues/102856}.)
See @ref{4b5,,Porting to Python 3.12} for more information on the
changes to the @ref{fa,,tokenize} module.
@end itemize

@node types<2>,typing<3>,tokenize,Modules améliorés<2>
@anchor{whatsnew/3 12 types}@anchor{4b6}
@subsubsection @code{types}



@itemize *

@item 
Add @ref{4b7,,types.get_original_bases()} to allow for further introspection of
@ref{4b8,,Types génériques définis par l'utilisateur} when subclassed. (Contributed by
James Hilton-Balfe and Alex Waygood in gh-101827@footnote{https://github.com/python/cpython/issues/101827}.)
@end itemize

@node typing<3>,unicodedata<2>,types<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 typing}@anchor{4b9}@anchor{whatsnew/3 12 whatsnew-typing-py312}@anchor{4ba}
@subsubsection `typing'



@itemize *

@item 
@ref{42b,,isinstance()} checks against
@ref{42c,,runtime-checkable protocols} now use
@ref{47e,,inspect.getattr_static()} rather than @ref{4bb,,hasattr()} to lookup whether
attributes exist. This means that descriptors and @ref{4bc,,__getattr__()}
methods are no longer unexpectedly evaluated during @code{isinstance()} 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 in gh-102433@footnote{https://github.com/python/cpython/issues/102433}.)

@item 
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
@ref{42b,,isinstance()} checks comparing objects to the protocol. For example:

@example
>>> from typing import Protocol, runtime_checkable
>>> @@runtime_checkable
... class HasX(Protocol):
...     x = 1
...
>>> class Foo: ...
...
>>> 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
@end example

This change was made in order to speed up @code{isinstance()} checks against
runtime-checkable protocols.

@item 
The performance profile of @ref{42b,,isinstance()} checks against
@ref{42c,,runtime-checkable protocols} has changed
significantly. Most @code{isinstance()} 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, @code{isinstance()} checks against protocols with many
members may be slower than in Python 3.11. (Contributed by Alex
Waygood in gh-74690@footnote{https://github.com/python/cpython/issues/74690} and gh-103193@footnote{https://github.com/python/cpython/issues/103193}.)

@item 
All @ref{161,,typing.TypedDict} and @ref{2ad,,typing.NamedTuple} classes now have the
@code{__orig_bases__} attribute. (Contributed by Adrian Garcia Badaracco in
gh-103699@footnote{https://github.com/python/cpython/issues/103699}.)

@item 
Add @code{frozen_default} parameter to @ref{4bd,,typing.dataclass_transform()}.
(Contributed by Erik De Bonte in gh-99957@footnote{https://github.com/python/cpython/issues/99957}.)
@end itemize

@node unicodedata<2>,unittest<2>,typing<3>,Modules améliorés<2>
@anchor{whatsnew/3 12 unicodedata}@anchor{4be}
@subsubsection `unicodedata'



@itemize *

@item 
The Unicode database has been updated to version 15.0.0. (Contributed by
Benjamin Peterson in gh-96734@footnote{https://github.com/python/cpython/issues/96734}).
@end itemize

@node unittest<2>,uuid,unicodedata<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 unittest}@anchor{4bf}
@subsubsection unittest


Add a @code{--durations} command line option, showing the N slowest test cases:

@example
python3 -m unittest --durations=3 lib.tests.test_threading
.....
Slowest test durations
----------------------------------------------------------------------
1.210s     test_timeout (Lib.test.test_threading.BarrierTests)
1.003s     test_default_timeout (Lib.test.test_threading.BarrierTests)
0.518s     test_timeout (Lib.test.test_threading.EventTests)

(0.000 durations hidden.  Use -v to show these durations.)
----------------------------------------------------------------------
Ran 158 tests in 9.869s

OK (skipped=3)
@end example

(Contributed by Giampaolo Rodola in gh-48330@footnote{https://github.com/python/cpython/issues/48330})

@node uuid,,unittest<2>,Modules améliorés<2>
@anchor{whatsnew/3 12 uuid}@anchor{4c0}
@subsubsection uuid



@itemize *

@item 
Add a @ref{42d,,command-line interface}.
(Contributed by Adam Chhina in gh-88597@footnote{https://github.com/python/cpython/issues/88597}.)
@end itemize

@node Optimisations<2>,Changements au code intermédiaire CPython,Modules améliorés<2>,What's New In Python 3 12
@anchor{whatsnew/3 12 optimizations}@anchor{4c1}
@subsection Optimisations



@itemize *

@item 
Remove @code{wstr} and @code{wstr_length} members from Unicode objects.
It reduces object size by 8 or 16 bytes on 64bit platform. (
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/})
(Contributed by Inada Naoki in gh-92536@footnote{https://github.com/python/cpython/issues/92536}.)

@item 
Add experimental support for using the BOLT binary optimizer in the build
process, which improves performance by 1-5%.
(Contributed by Kevin Modzelewski in gh-90536@footnote{https://github.com/python/cpython/issues/90536} and tuned by Donghee Na in gh-101525@footnote{https://github.com/python/cpython/issues/101525})

@item 
Speed up the regular expression substitution (functions @ref{2a0,,re.sub()} and
@ref{2a1,,re.subn()} and corresponding @code{re.Pattern} methods) for
replacement strings containing group references by 2--3 times.
(Contributed by Serhiy Storchaka in gh-91524@footnote{https://github.com/python/cpython/issues/91524}.)

@item 
Speed up @ref{4c2,,asyncio.Task} creation by deferring expensive string formatting.
(Contributed by Itamar Oren in gh-103793@footnote{https://github.com/python/cpython/issues/103793}.)

@item 
The @ref{4c3,,tokenize.tokenize()} and @ref{4c4,,tokenize.generate_tokens()} functions are
up to 64% faster as a side effect of the changes required to cover 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/} in
the @ref{fa,,tokenize} module. (Contributed by Marta Gómez Macías and Pablo Galindo
in gh-102856@footnote{https://github.com/python/cpython/issues/102856}.)

@item 
Speed up @ref{4c5,,super()} method calls and attribute loads via the
new @ref{4c6,,LOAD_SUPER_ATTR} instruction. (Contributed by Carl Meyer and
Vladimir Matveev in gh-103497@footnote{https://github.com/python/cpython/issues/103497}.)
@end itemize

@node Changements au code intermédiaire CPython,Demos and Tools,Optimisations<2>,What's New In Python 3 12
@anchor{whatsnew/3 12 cpython-bytecode-changes}@anchor{4c7}
@subsection Changements au code intermédiaire CPython



@itemize *

@item 
Remove the @code{LOAD_METHOD} instruction. It has been merged into
@ref{4c8,,LOAD_ATTR}. @ref{4c8,,LOAD_ATTR} will now behave like the old
@code{LOAD_METHOD} instruction if the low bit of its oparg is set.
(Contributed by Ken Jin in gh-93429@footnote{https://github.com/python/cpython/issues/93429}.)

@item 
Remove the @code{JUMP_IF_FALSE_OR_POP} and @code{JUMP_IF_TRUE_OR_POP}
instructions. (Contributed by Irit Katriel in gh-102859@footnote{https://github.com/python/cpython/issues/102859}.)

@item 
Remove the @code{PRECALL} instruction. (Contributed by Mark Shannon in
gh-92925@footnote{https://github.com/python/cpython/issues/92925}.)

@item 
Add the @ref{4c9,,BINARY_SLICE} and @ref{4ca,,STORE_SLICE} instructions.
(Contributed by Mark Shannon in gh-94163@footnote{https://github.com/python/cpython/issues/94163}.)

@item 
Add the @ref{4cb,,CALL_INTRINSIC_1} instructions.
(Contributed by Mark Shannon in gh-99005@footnote{https://github.com/python/cpython/issues/99005}.)

@item 
Add the @ref{4cc,,CALL_INTRINSIC_2} instruction.
(Contributed by Irit Katriel in gh-101799@footnote{https://github.com/python/cpython/issues/101799}.)

@item 
Add the @ref{4cd,,CLEANUP_THROW} instruction.
(Contributed by Brandt Bucher in gh-90997@footnote{https://github.com/python/cpython/issues/90997}.)

@item 
Add the @code{END_SEND} instruction.
(Contributed by Mark Shannon in gh-103082@footnote{https://github.com/python/cpython/issues/103082}.)

@item 
Add the @ref{4ce,,LOAD_FAST_AND_CLEAR} instruction as part of the
implementation of 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}. (Contributed by Carl Meyer in gh-101441@footnote{https://github.com/python/cpython/issues/101441}.)

@item 
Add the @ref{4cf,,LOAD_FAST_CHECK} instruction.
(Contributed by Dennis Sweeney in gh-93143@footnote{https://github.com/python/cpython/issues/93143}.)

@item 
Add the @ref{4d0,,LOAD_FROM_DICT_OR_DEREF}, @ref{4d1,,LOAD_FROM_DICT_OR_GLOBALS},
and @ref{4d2,,LOAD_LOCALS} opcodes as part of the implementation of 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.
Remove the @code{LOAD_CLASSDEREF} opcode, which can be replaced with
@ref{4d2,,LOAD_LOCALS} plus @ref{4d0,,LOAD_FROM_DICT_OR_DEREF}. (Contributed
by Jelle Zijlstra in gh-103764@footnote{https://github.com/python/cpython/issues/103764}.)

@item 
Add the @ref{4c6,,LOAD_SUPER_ATTR} instruction. (Contributed by Carl Meyer and
Vladimir Matveev in gh-103497@footnote{https://github.com/python/cpython/issues/103497}.)

@item 
Add the @ref{4d3,,RETURN_CONST} instruction. (Contributed by Wenyang Wang in gh-101632@footnote{https://github.com/python/cpython/issues/101632}.)
@end itemize

@node Demos and Tools,Obsolescence,Changements au code intermédiaire CPython,What's New In Python 3 12
@anchor{whatsnew/3 12 demos-and-tools}@anchor{4d4}
@subsection Demos and Tools



@itemize *

@item 
Remove the @code{Tools/demo/} directory which contained old demo scripts. A copy
can be found in the old-demos project@footnote{https://github.com/gvanrossum/old-demos}.
(Contributed by Victor Stinner in gh-97681@footnote{https://github.com/python/cpython/issues/97681}.)

@item 
Remove outdated example scripts of the @code{Tools/scripts/} directory.
A copy can be found in the old-demos project@footnote{https://github.com/gvanrossum/old-demos}.
(Contributed by Victor Stinner in gh-97669@footnote{https://github.com/python/cpython/issues/97669}.)
@end itemize

@node Obsolescence,Retraits,Demos and Tools,What's New In Python 3 12
@anchor{whatsnew/3 12 deprecated}@anchor{4d5}
@subsection Obsolescence



@itemize *

@item 
@ref{6,,argparse}: The `type', `choices', and `metavar' parameters
of @code{argparse.BooleanOptionalAction} are deprecated
and will be removed in 3.14.
(Contributed by Nikita Sobolev in gh-92248@footnote{https://github.com/python/cpython/issues/92248}.)

@item 
@ref{8,,ast}: The following @ref{8,,ast} features have been deprecated in documentation since
Python 3.8, now cause a @ref{1a3,,DeprecationWarning} to be emitted at runtime
when they are accessed or used, and will be removed in Python 3.14:


@itemize *

@item 
@code{ast.Num}

@item 
@code{ast.Str}

@item 
@code{ast.Bytes}

@item 
@code{ast.NameConstant}

@item 
@code{ast.Ellipsis}
@end itemize

Use @ref{2b6,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{a,,asyncio}:


@itemize *

@item 
The child watcher classes @ref{2b7,,asyncio.MultiLoopChildWatcher},
@ref{2b8,,asyncio.FastChildWatcher}, @ref{2b9,,asyncio.AbstractChildWatcher}
and @ref{2ba,,asyncio.SafeChildWatcher} are deprecated and
will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
@ref{2bb,,asyncio.set_child_watcher()}, @ref{2bc,,asyncio.get_child_watcher()},
@ref{2bd,,asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@ref{2be,,asyncio.AbstractEventLoopPolicy.get_child_watcher()} are deprecated
and will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
The @ref{2bf,,get_event_loop()} method of the
default event loop policy now emits a @ref{1a3,,DeprecationWarning} if there
is no current event loop set and it decides to create one.
(Contributed by Serhiy Storchaka and Guido van Rossum in gh-100160@footnote{https://github.com/python/cpython/issues/100160}.)
@end itemize

@item 
@ref{14,,calendar}: @code{calendar.January} and @code{calendar.February} constants are deprecated and
replaced by @ref{2ed,,calendar.JANUARY} and @ref{2ee,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{1e,,collections.abc}: Deprecated @ref{2c0,,collections.abc.ByteString}.
Prefer @code{Sequence} or @ref{2c1,,collections.abc.Buffer}.
For use in typing, prefer a union, like @code{bytes | bytearray}, or @ref{2c1,,collections.abc.Buffer}.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)

@item 
@ref{30,,datetime}: @ref{1c7,,datetime.datetime}'s @ref{2f0,,utcnow()} and
@ref{2f1,,utcfromtimestamp()} are deprecated and will be
removed in a future version. Instead, use timezone-aware objects to represent
datetimes in UTC: respectively, call @ref{4d6,,now()} and
@ref{4d7,,fromtimestamp()}  with the `tz' parameter set to
@ref{4d8,,datetime.UTC}.
(Contributed by Paul Ganssle in gh-103857@footnote{https://github.com/python/cpython/issues/103857}.)

@item 
@ref{3b,,email}: Deprecate the `isdst' parameter in @ref{2c2,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{77,,importlib.abc}: Deprecated the following classes, scheduled for removal in
Python 3.14:


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

Use @ref{7b,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{1f0,,importlib.resources.abc.Traversable}

@item 
@ref{2c3,,importlib.resources.abc.TraversableResources}
@end itemize

(Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963@footnote{https://github.com/python/cpython/issues/93963}.)

@item 
@ref{80,,itertools}: Deprecate the support for copy, deepcopy, and pickle operations,
which is undocumented, inefficient, historically buggy, and inconsistent.
This will be removed in 3.14 for a significant reduction in code
volume and maintenance burden.
(Contributed by Raymond Hettinger in gh-101588@footnote{https://github.com/python/cpython/issues/101588}.)

@item 
@ref{93,,multiprocessing}: In Python 3.14, the default @ref{93,,multiprocessing}
start method will change to a safer one on Linux, BSDs,
and other non-macOS POSIX platforms where @code{'fork'} is currently
the default (gh-84559@footnote{https://github.com/python/cpython/issues/84559}). Adding a runtime warning about this was deemed too
disruptive as the majority of code is not expected to care. Use the
@ref{2c4,,get_context()} or
@ref{2c5,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{2c6,,contexts and start methods}.

@item 
@ref{a8,,pkgutil}: @ref{2c9,,pkgutil.find_loader()} and @ref{2ca,,pkgutil.get_loader()}
are deprecated and will be removed in Python 3.14;
use @ref{2cb,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b0,,pty}: The module has two undocumented @code{master_open()} and @code{slave_open()}
functions that have been deprecated since Python 2 but only gained a
proper @ref{1a3,,DeprecationWarning} in 3.12. Remove them in 3.14.
(Contributed by Soumendra Ganguly and Gregory P. Smith in gh-85984@footnote{https://github.com/python/cpython/issues/85984}.)

@item 
@ref{a0,,os}:


@itemize *

@item 
The @code{st_ctime} fields return by @ref{48a,,os.stat()} and @ref{48b,,os.lstat()} on
Windows are deprecated. In a future release, they will contain the last
metadata change time, consistent with other platforms. For now, they still
contain the creation time, which is also available in the new @code{st_birthtime}
field. (Contributed by Steve Dower in gh-99726@footnote{https://github.com/python/cpython/issues/99726}.)

@item 
On POSIX platforms, @ref{195,,os.fork()} can now raise a
@ref{1a3,,DeprecationWarning} when it can detect being called from a
multithreaded process. There has always been a fundamental incompatibility
with the POSIX platform when doing so. Even if such code `appeared' to work.
We added the warning to raise awareness as issues encountered by code doing
this are becoming more frequent. See the @ref{195,,os.fork()} documentation for
more details along with this discussion on fork being incompatible with threads@footnote{https://discuss.python.org/t/concerns-regarding-deprecation-of-fork-with-alive-threads/33555} for `why' we're now surfacing this
longstanding platform compatibility problem to developers.
@end itemize

When this warning appears due to usage of @ref{93,,multiprocessing} or
@ref{21,,concurrent.futures} the fix is to use a different
@ref{93,,multiprocessing} start method such as @code{"spawn"} or @code{"forkserver"}.

@item 
@ref{c4,,shutil}: The `onerror' argument of @ref{2f5,,shutil.rmtree()} is deprecated;
use `onexc' instead. (Contributed by Irit Katriel in gh-102828@footnote{https://github.com/python/cpython/issues/102828}.)

@item 
@ref{ce,,sqlite3}:


@itemize *

@item 
@ref{4d9,,default adapters and converters} are now deprecated.
Instead, use the @ref{4da,,Adapter and converter recipes}
and tailor them to your needs.
(Contributed by Erlend E. Aasland in gh-90016@footnote{https://github.com/python/cpython/issues/90016}.)

@item 
In @ref{2cf,,execute()}, @ref{1a3,,DeprecationWarning} is now emitted
when @ref{2d1,,named placeholders} are used together with
parameters supplied as a @ref{4db,,sequence} instead of as a @ref{253,,dict}.
Starting from Python 3.14, using named placeholders with parameters supplied
as a sequence will raise a @ref{4dc,,ProgrammingError}.
(Contributed by Erlend E. Aasland in gh-101698@footnote{https://github.com/python/cpython/issues/101698}.)
@end itemize

@item 
@ref{d8,,sys}: The @ref{4a8,,sys.last_type}, @ref{4a9,,sys.last_value} and @ref{4aa,,sys.last_traceback}
fields are deprecated. Use @ref{4a7,,sys.last_exc} instead.
(Contributed by Irit Katriel in gh-102778@footnote{https://github.com/python/cpython/issues/102778}.)

@item 
@ref{dd,,tarfile}: Extracting tar archives without specifying `filter' is deprecated until
Python 3.14, when @code{'data'} filter will become the default.
See @ref{456,,Extraction filters} for details.

@item 
@ref{103,,typing}:


@itemize *

@item 
@ref{4dd,,typing.Hashable} and @ref{4de,,typing.Sized}, aliases for
@ref{4df,,collections.abc.Hashable} and @ref{4e0,,collections.abc.Sized} respectively, are
deprecated. (gh-94309@footnote{https://github.com/python/cpython/issues/94309}.)

@item 
@ref{2d2,,typing.ByteString}, deprecated since Python 3.9, now causes a
@ref{1a3,,DeprecationWarning} to be emitted when it is used.
(Contributed by Alex Waygood in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)
@end itemize

@item 
@ref{124,,xml.etree.ElementTree}: The module now emits @ref{1a3,,DeprecationWarning}
when testing the truth value of an @ref{305,,xml.etree.ElementTree.Element}.
Before, the Python implementation emitted @ref{40b,,FutureWarning}, and the C
implementation emitted nothing.
(Contributed by Jacob Walls in gh-83122@footnote{https://github.com/python/cpython/issues/83122}.)

@item 
The 3-arg signatures (type, value, traceback) of @ref{4e1,,coroutine throw()}, @ref{4e2,,generator throw()} and
@ref{4e3,,async generator throw()} are deprecated and
may be removed in a future version of Python. Use the single-arg versions
of these functions instead. (Contributed by Ofey Chan in gh-89874@footnote{https://github.com/python/cpython/issues/89874}.)

@item 
@ref{1a3,,DeprecationWarning} is now raised when @ref{2d6,,__package__} on a
module differs from
@ref{2d7,,__spec__.parent} (previously
it was @ref{4e4,,ImportWarning}).
(Contributed by Brett Cannon in gh-65961@footnote{https://github.com/python/cpython/issues/65961}.)

@item 
Setting @ref{2d6,,__package__} or @ref{2d4,,__cached__} on a
module is deprecated, and will cease to be set or taken into consideration by
the import system in Python 3.14. (Contributed by Brett Cannon in gh-65961@footnote{https://github.com/python/cpython/issues/65961}.)

@item 
The bitwise inversion operator (@code{~}) on bool is deprecated. It will throw an
error in Python 3.16. Use @code{not} for logical negation of bools instead.
In the rare case that you really need the bitwise inversion of the underlying
@code{int}, convert to int explicitly: @code{~int(x)}. (Contributed by Tim Hoffmann
in gh-103487@footnote{https://github.com/python/cpython/issues/103487}.)

@item 
Accessing @ref{2de,,co_lnotab} on code objects was deprecated in
Python 3.10 via 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/},
but it only got a proper @ref{1a3,,DeprecationWarning} in 3.12.
May be removed in 3.15.
(Contributed by Nikita Sobolev in gh-101866@footnote{https://github.com/python/cpython/issues/101866}.)
@end itemize

@menu
* Pending Removal in Python 3.13: Pending Removal in Python 3 13. 
* Pending Removal in Python 3.14: Pending Removal in Python 3 14<3>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<3>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<2>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<3>. 

@end menu

@node Pending Removal in Python 3 13,Pending Removal in Python 3 14<3>,,Obsolescence
@anchor{whatsnew/3 12 pending-removal-in-python-3-13}@anchor{4e5}
@subsubsection Pending Removal in Python 3.13


Modules (see 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}):


@itemize *

@item 
@code{aifc}

@item 
@code{audioop}

@item 
@code{cgi}

@item 
@code{cgitb}

@item 
@code{chunk}

@item 
@code{crypt}

@item 
@code{imghdr}

@item 
@code{mailcap}

@item 
@code{msilib}

@item 
@code{nis}

@item 
@code{nntplib}

@item 
@code{ossaudiodev}

@item 
@code{pipes}

@item 
@code{sndhdr}

@item 
@code{spwd}

@item 
@code{sunau}

@item 
@code{telnetlib}

@item 
@code{uu}

@item 
@code{xdrlib}
@end itemize

Other modules:


@itemize *

@item 
@code{lib2to3}, and the @code{2to3} program (gh-84540@footnote{https://github.com/python/cpython/issues/84540})
@end itemize

APIs:


@itemize *

@item 
@code{configparser.LegacyInterpolation} (gh-90765@footnote{https://github.com/python/cpython/issues/90765})

@item 
@code{locale.resetlocale()} (gh-90817@footnote{https://github.com/python/cpython/issues/90817})

@item 
@code{turtle.RawTurtle.settiltangle()} (gh-50096@footnote{https://github.com/python/cpython/issues/50096})

@item 
@code{unittest.findTestCases()} (gh-50096@footnote{https://github.com/python/cpython/issues/50096})

@item 
@code{unittest.getTestCaseNames()} (gh-50096@footnote{https://github.com/python/cpython/issues/50096})

@item 
@code{unittest.makeSuite()} (gh-50096@footnote{https://github.com/python/cpython/issues/50096})

@item 
@code{unittest.TestProgram.usageExit()} (gh-67048@footnote{https://github.com/python/cpython/issues/67048})

@item 
@code{webbrowser.MacOSX} (gh-86421@footnote{https://github.com/python/cpython/issues/86421})

@item 
@ref{165,,classmethod} descriptor chaining (gh-89519@footnote{https://github.com/python/cpython/issues/89519})

@item 
@ref{7a,,importlib.resources} deprecated methods:


@itemize *

@item 
@code{contents()}

@item 
@code{is_resource()}

@item 
@code{open_binary()}

@item 
@code{open_text()}

@item 
@code{path()}

@item 
@code{read_binary()}

@item 
@code{read_text()}
@end itemize

Use @ref{478,,importlib.resources.files()} instead.  Refer to importlib-resources: Migrating from Legacy@footnote{https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy} (gh-106531@footnote{https://github.com/python/cpython/issues/106531})
@end itemize

@node Pending Removal in Python 3 14<3>,Pending Removal in Python 3 15<3>,Pending Removal in Python 3 13,Obsolescence
@anchor{whatsnew/3 12 pending-removal-in-python-3-14}@anchor{4e6}
@subsubsection Pending Removal in Python 3.14



@itemize *

@item 
@ref{6,,argparse}: The `type', `choices', and `metavar' parameters
of @code{argparse.BooleanOptionalAction} are deprecated
and will be removed in 3.14.
(Contributed by Nikita Sobolev in gh-92248@footnote{https://github.com/python/cpython/issues/92248}.)

@item 
@ref{8,,ast}: The following features have been deprecated in documentation
since Python 3.8, now cause a @ref{1a3,,DeprecationWarning} to be emitted at
runtime when they are accessed or used, and will be removed in Python 3.14:


@itemize *

@item 
@code{ast.Num}

@item 
@code{ast.Str}

@item 
@code{ast.Bytes}

@item 
@code{ast.NameConstant}

@item 
@code{ast.Ellipsis}
@end itemize

Use @ref{2b6,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{a,,asyncio}:


@itemize *

@item 
The child watcher classes @ref{2b7,,MultiLoopChildWatcher},
@ref{2b8,,FastChildWatcher}, @ref{2b9,,AbstractChildWatcher}
and @ref{2ba,,SafeChildWatcher} are deprecated and
will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
@ref{2bb,,asyncio.set_child_watcher()}, @ref{2bc,,asyncio.get_child_watcher()},
@ref{2bd,,asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@ref{2be,,asyncio.AbstractEventLoopPolicy.get_child_watcher()} are deprecated
and will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
The @ref{2bf,,get_event_loop()} method of the
default event loop policy now emits a @ref{1a3,,DeprecationWarning} if there
is no current event loop set and it decides to create one.
(Contributed by Serhiy Storchaka and Guido van Rossum in gh-100160@footnote{https://github.com/python/cpython/issues/100160}.)
@end itemize

@item 
@ref{1e,,collections.abc}: Deprecated @ref{2c0,,ByteString}.
Prefer @code{Sequence} or @ref{2c1,,Buffer}.
For use in typing, prefer a union, like @code{bytes | bytearray},
or @ref{2c1,,collections.abc.Buffer}.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)

@item 
@ref{3b,,email}: Deprecated the `isdst' parameter in @ref{2c2,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{77,,importlib.abc} deprecated classes:


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

Use @ref{7b,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{1f0,,importlib.resources.abc.Traversable}

@item 
@ref{2c3,,importlib.resources.abc.TraversableResources}
@end itemize

(Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963@footnote{https://github.com/python/cpython/issues/93963}.)

@item 
@ref{80,,itertools} had undocumented, inefficient, historically buggy,
and inconsistent support for copy, deepcopy, and pickle operations.
This will be removed in 3.14 for a significant reduction in code
volume and maintenance burden.
(Contributed by Raymond Hettinger in gh-101588@footnote{https://github.com/python/cpython/issues/101588}.)

@item 
@ref{93,,multiprocessing}: The default start method will change to a safer one on
Linux, BSDs, and other non-macOS POSIX platforms where @code{'fork'} is currently
the default (gh-84559@footnote{https://github.com/python/cpython/issues/84559}). Adding a runtime warning about this was deemed too
disruptive as the majority of code is not expected to care. Use the
@ref{2c4,,get_context()} or
@ref{2c5,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{2c6,,Contextes et méthodes de démarrage}.

@item 
@ref{a3,,pathlib}: @ref{2c7,,is_relative_to()} and
@ref{2c8,,relative_to()}: passing additional arguments is
deprecated.

@item 
@ref{a8,,pkgutil}: @ref{2c9,,find_loader()} and @ref{2ca,,get_loader()}
now raise @ref{1a3,,DeprecationWarning};
use @ref{2cb,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b0,,pty}:


@itemize *

@item 
@code{master_open()}: use @ref{2cc,,pty.openpty()}.

@item 
@code{slave_open()}: use @ref{2cc,,pty.openpty()}.
@end itemize

@item 
@ref{ce,,sqlite3}:


@itemize *

@item 
@ref{2cd,,version} and @ref{2ce,,version_info}.

@item 
@ref{2cf,,execute()} and @ref{2d0,,executemany()}
if @ref{2d1,,named placeholders} are used and
`parameters' is a sequence instead of a @ref{253,,dict}.
@end itemize

@item 
@ref{103,,typing}: @ref{2d2,,ByteString}, deprecated since Python 3.9,
now causes a @ref{1a3,,DeprecationWarning} to be emitted when it is used.

@item 
@ref{107,,urllib}:
@code{urllib.parse.Quoter} is deprecated: it was not intended to be a
public API.
(Contributed by Gregory P. Smith in gh-88168@footnote{https://github.com/python/cpython/issues/88168}.)
@end itemize

@node Pending Removal in Python 3 15<3>,Pending removal in Python 3 16<2>,Pending Removal in Python 3 14<3>,Obsolescence
@anchor{whatsnew/3 12 pending-removal-in-python-3-15}@anchor{4e7}
@subsubsection Pending Removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2d4,,__cached__} on a module while
failing to set @ref{2d5,,__spec__.cached}
is deprecated. In Python 3.15, @code{__cached__} will cease to be set or
take into consideration by the import system or standard library. (gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
Setting @ref{2d6,,__package__} on a module while
failing to set @ref{2d7,,__spec__.parent}
is deprecated. In Python 3.15, @code{__package__} will cease to be set or
take into consideration by the import system or standard library. (gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2a,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{71,,http.server}:


@itemize *

@item 
The obsolete and rarely used @ref{29e,,CGIHTTPRequestHandler}
has been deprecated since Python 3.13.
No direct replacement exists.
`Anything' is better than CGI to interface
a web server with a request handler.

@item 
The @code{--cgi} flag to the @code{python -m http.server}
command-line interface has been deprecated since Python 3.13.
@end itemize

@item 
@ref{85,,locale}:


@itemize *

@item 
The @ref{2d8,,getdefaultlocale()} function
has been deprecated since Python 3.11.
Its removal was originally planned for Python 3.13 (gh-90817@footnote{https://github.com/python/cpython/issues/90817}),
but has been postponed to Python 3.15.
Use @ref{2d9,,getlocale()}, @ref{2da,,setlocale()},
and @ref{2db,,getencoding()} instead.
(Contributed by Hugo van Kemenade in gh-111187@footnote{https://github.com/python/cpython/issues/111187}.)
@end itemize

@item 
@ref{a3,,pathlib}:


@itemize *

@item 
@ref{2a3,,PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{220,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{a9,,platform}:


@itemize *

@item 
@ref{2a4,,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.
@end itemize

@item 
@ref{ec,,threading}:


@itemize *

@item 
@ref{2dc,,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.
@end itemize

@item 
@ref{102,,types}:


@itemize *

@item 
@ref{2dd,,types.CodeType}: Accessing @ref{2de,,co_lnotab} was
deprecated in 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}
since 3.10 and was planned to be removed in 3.12,
but it only got a proper @ref{1a3,,DeprecationWarning} in 3.12.
May be removed in 3.15.
(Contributed by Nikita Sobolev in gh-101866@footnote{https://github.com/python/cpython/issues/101866}.)
@end itemize

@item 
@ref{103,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2ad,,NamedTuple} classes
(e.g. @code{Point = NamedTuple("Point", x=int, y=int)})
has been deprecated since Python 3.13.
Use the class-based syntax or the functional syntax instead.

@item 
The @ref{2ae,,typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{103,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@ref{112,,wave}:


@itemize *

@item 
The @ref{2b1,,getmark()}, @code{setmark()},
and @ref{2b2,,getmarkers()} methods of
the @ref{2b3,,Wave_read} and @ref{2b4,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize
@end itemize

@node Pending removal in Python 3 16<2>,Pending Removal in Future Versions<3>,Pending Removal in Python 3 15<3>,Obsolescence
@anchor{whatsnew/3 12 pending-removal-in-python-3-16}@anchor{4e8}
@subsubsection Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2e0,,__loader__} on a module while
failing to set @ref{2e1,,__spec__.loader}
is deprecated. In Python 3.16, @code{__loader__} will cease to be set or
taken into consideration by the import system or the standard library.
@end itemize

@item 
@ref{7,,array}:


@itemize *

@item 
The @code{'u'} format code (@code{wchar_t})
has been deprecated in documentation since Python 3.3
and at runtime since Python 3.13.
Use the @code{'w'} format code (@ref{298,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{a,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16,
use @ref{2e2,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)
@end itemize

@item 
@ref{12,,builtins}:


@itemize *

@item 
Bitwise inversion on boolean types, @code{~True} or @code{~False}
has been deprecated since Python 3.12,
as it produces surprising and unintuitive results (@code{-2} and @code{-1}).
Use @code{not x} instead for the logical negation of a Boolean.
In the rare case that you need the bitwise inversion of
the underlying integer, convert to @code{int} explicitly (@code{~int(x)}).
@end itemize

@item 
@ref{c4,,shutil}:


@itemize *

@item 
The @code{ExecError} exception
has been deprecated since Python 3.14.
It has not been used by any function in @code{shutil} since Python 3.4,
and is now an alias of @ref{193,,RuntimeError}.
@end itemize

@item 
@ref{d7,,symtable}:


@itemize *

@item 
The @ref{2e3,,Class.get_methods} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{d8,,sys}:


@itemize *

@item 
The @ref{2ab,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{dd,,tarfile}:


@itemize *

@item 
The undocumented and unused @code{TarFile.tarfile} attribute
has been deprecated since Python 3.13.
@end itemize
@end itemize

@node Pending Removal in Future Versions<3>,,Pending removal in Python 3 16<2>,Obsolescence
@anchor{whatsnew/3 12 pending-removal-in-future-versions}@anchor{4e9}
@subsubsection Pending Removal in Future Versions


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


@itemize *

@item 
@ref{6,,argparse}: Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
@ref{7,,array}'s @code{'u'} format code (gh-57281@footnote{https://github.com/python/cpython/issues/57281})

@item 
@ref{12,,builtins}:


@itemize *

@item 
@code{bool(NotImplemented)}.

@item 
Generators: @code{throw(type, exc, tb)} and @code{athrow(type, exc, tb)}
signature is deprecated: use @code{throw(exc)} and @code{athrow(exc)} instead,
the single argument signature.

@item 
Currently Python accepts numeric literals immediately followed by keywords,
for example @code{0in x}, @code{1or x}, @code{0if 1else 2}.  It allows confusing and
ambiguous expressions like @code{[0x1for x in y]} (which can be interpreted as
@code{[0x1 for x in y]} or @code{[0x1f or x in y]}).  A syntax warning is raised
if the numeric literal is immediately followed by one of keywords
@ref{2e5,,and}, @ref{18a,,else}, @ref{2e6,,for}, @ref{2e7,,if},
@ref{2e8,,in}, @ref{2e9,,is} and @ref{2ea,,or}.  In a future release it
will be changed to a syntax error. (gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
Support for @code{__index__()} and @code{__int__()} method returning non-int type:
these methods will be required to return an instance of a strict subclass of
@ref{254,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{2eb,,float}: these methods will be required to return an instance of
@ref{2eb,,float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{2ec,,complex}: these methods will be required to return an instance of
@ref{2ec,,complex}.

@item 
Delegation of @code{int()} to @code{__trunc__()} method.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{2ec,,complex()} constructor is now deprecated; it should only be passed
as a single positional argument.
(Contributed by Serhiy Storchaka in gh-109218@footnote{https://github.com/python/cpython/issues/109218}.)
@end itemize

@item 
@ref{14,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{2ed,,calendar.JANUARY} and
@ref{2ee,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{2de,,codeobject.co_lnotab}: use the @ref{2ef,,codeobject.co_lines()} method
instead.

@item 
@ref{30,,datetime}:


@itemize *

@item 
@ref{2f0,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{2f1,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{62,,gettext}: Plural value must be an integer.

@item 
@ref{76,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.

@item 
@ref{2f2,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{79,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{86,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{2f3,,warning()} instead.

@item 
@ref{8a,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a0,,os}: Calling @ref{2f4,,os.register_at_fork()} in multi-threaded process.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{b8,,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 in gh-91760@footnote{https://github.com/python/cpython/issues/91760}.)

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{c4,,shutil}: @ref{2f5,,rmtree()}'s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{cf,,ssl} options and protocols:


@itemize *

@item 
@ref{291,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{291,,ssl.SSLContext}: @ref{2f6,,set_npn_protocols()} and
@code{selected_npn_protocol()} are deprecated: use ALPN
instead.

@item 
@code{ssl.OP_NO_SSL*} options

@item 
@code{ssl.OP_NO_TLS*} options

@item 
@code{ssl.PROTOCOL_SSLv3}

@item 
@code{ssl.PROTOCOL_TLS}

@item 
@code{ssl.PROTOCOL_TLSv1}

@item 
@code{ssl.PROTOCOL_TLSv1_1}

@item 
@code{ssl.PROTOCOL_TLSv1_2}

@item 
@code{ssl.TLSVersion.SSLv3}

@item 
@code{ssl.TLSVersion.TLSv1}

@item 
@code{ssl.TLSVersion.TLSv1_1}
@end itemize

@item 
@ref{2f7,,sysconfig.is_python_build()} `check_home' parameter is deprecated and
ignored.

@item 
@ref{ec,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{2f8,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{2f9,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{2fa,,threading.Thread.setDaemon()}:
use @ref{2fb,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{2fc,,threading.Thread.setName()}:
use @ref{2fd,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{2fe,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{2ff,,threading.active_count()}.
@end itemize

@item 
@ref{300,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
@ref{301,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{109,,urllib.parse} deprecated functions: @ref{302,,urlparse()} instead


@itemize *

@item 
@code{splitattr()}

@item 
@code{splithost()}

@item 
@code{splitnport()}

@item 
@code{splitpasswd()}

@item 
@code{splitport()}

@item 
@code{splitquery()}

@item 
@code{splittag()}

@item 
@code{splittype()}

@item 
@code{splituser()}

@item 
@code{splitvalue()}

@item 
@code{to_bytes()}
@end itemize

@item 
@ref{10a,,urllib.request}: @ref{303,,URLopener} and
@ref{304,,FancyURLopener} style of invoking requests is
deprecated. Use newer @ref{290,,urlopen()} functions and methods.

@item 
@ref{117,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{124,,xml.etree.ElementTree}: Testing the truth value of an
@ref{305,,Element} is deprecated. In a future release it
will always return @code{True}. Prefer explicit @code{len(elem)} or
@code{elem is not None} tests instead.

@item 
@ref{306,,zipimport.zipimporter.load_module()} is deprecated:
use @ref{307,,exec_module()} instead.
@end itemize

@node Retraits,Porting to Python 3 12,Obsolescence,What's New In Python 3 12
@anchor{whatsnew/3 12 removed}@anchor{4ea}@anchor{whatsnew/3 12 whatsnew312-removed}@anchor{4eb}
@subsection Retraits


@menu
* asynchat and asyncore:: 
* configparser: configparser<3>. 
* distutils:: 
* ensurepip:: 
* enum: enum<2>. 
* ftplib:: 
* gzip:: 
* hashlib:: 
* importlib: importlib<2>. 
* imp:: 
* io: io<2>. 
* locale: locale<2>. 
* smtpd:: 
* sqlite3: sqlite3<3>. 
* ssl: ssl<2>. 
* unittest: unittest<3>. 
* webbrowser: webbrowser<2>. 
* xml.etree.ElementTree: xml etree ElementTree. 
* zipimport: zipimport<2>. 
* Autres:: 

@end menu

@node asynchat and asyncore,configparser<3>,,Retraits
@anchor{whatsnew/3 12 asynchat-and-asyncore}@anchor{4ec}
@subsubsection asynchat and asyncore



@itemize *

@item 
These two modules have been removed
according to the schedule in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/},
having been deprecated in Python 3.6.
Use @ref{a,,asyncio} instead.
(Contributed by Nikita Sobolev in gh-96580@footnote{https://github.com/python/cpython/issues/96580}.)
@end itemize

@node configparser<3>,distutils,asynchat and asyncore,Retraits
@anchor{whatsnew/3 12 configparser}@anchor{4ed}
@subsubsection configparser



@itemize *

@item 
Several names deprecated in the @ref{22,,configparser} way back in 3.2 have
been removed per gh-89336@footnote{https://github.com/python/cpython/issues/89336}:


@itemize *

@item 
@ref{4ee,,configparser.ParsingError} no longer has a @code{filename} attribute
or argument. Use the @code{source} attribute and argument instead.

@item 
@ref{22,,configparser} no longer has a @code{SafeConfigParser} class. Use the
shorter @ref{1c3,,ConfigParser} name instead.

@item 
@ref{1c3,,configparser.ConfigParser} no longer has a @code{readfp} method.
Use @ref{4ef,,read_file()} instead.
@end itemize
@end itemize

@node distutils,ensurepip,configparser<3>,Retraits
@anchor{whatsnew/3 12 distutils}@anchor{4f0}@anchor{whatsnew/3 12 whatsnew312-removed-distutils}@anchor{4f1}
@subsubsection `distutils'



@itemize *

@item 
Remove the @code{distutils} package. It was deprecated in Python 3.10 by
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/} "Deprecate distutils module". For projects still using
@code{distutils} and cannot be updated to something else, the @code{setuptools}
project can be installed: it still provides @code{distutils}.
(Contributed by Victor Stinner in gh-92584@footnote{https://github.com/python/cpython/issues/92584}.)
@end itemize

@node ensurepip,enum<2>,distutils,Retraits
@anchor{whatsnew/3 12 ensurepip}@anchor{4f2}
@subsubsection ensurepip



@itemize *

@item 
Remove the bundled setuptools wheel from @ref{54,,ensurepip},
and stop installing setuptools in environments created by @ref{110,,venv}.

@code{pip (>= 22.1)} does not require setuptools to be installed in the
environment. @code{setuptools}-based (and @code{distutils}-based) packages
can still be used with @code{pip install}, since pip will provide
@code{setuptools} in the build environment it uses for building a
package.

@code{easy_install}, @code{pkg_resources}, @code{setuptools} and @code{distutils}
are no longer provided by default in environments created with
@code{venv} or bootstrapped with @code{ensurepip}, since they are part of
the @code{setuptools} package. For projects relying on these at runtime,
the @code{setuptools} project should be declared as a dependency and
installed separately (typically, using pip).

(Contributed by Pradyun Gedam in gh-95299@footnote{https://github.com/python/cpython/issues/95299}.)
@end itemize

@node enum<2>,ftplib,ensurepip,Retraits
@anchor{whatsnew/3 12 enum}@anchor{4f3}
@subsubsection enum



@itemize *

@item 
Remove @ref{55,,enum}'s @code{EnumMeta.__getattr__}, which is no longer needed for
enum attribute access.
(Contributed by Ethan Furman in gh-95083@footnote{https://github.com/python/cpython/issues/95083}.)
@end itemize

@node ftplib,gzip,enum<2>,Retraits
@anchor{whatsnew/3 12 ftplib}@anchor{4f4}
@subsubsection `ftplib'



@itemize *

@item 
Remove @ref{5d,,ftplib}'s @code{FTP_TLS.ssl_version} class attribute: use the
`context' parameter instead.
(Contributed by Victor Stinner in gh-94172@footnote{https://github.com/python/cpython/issues/94172}.)
@end itemize

@node gzip,hashlib,ftplib,Retraits
@anchor{whatsnew/3 12 gzip}@anchor{4f5}
@subsubsection gzip



@itemize *

@item 
Remove the @code{filename} attribute of @ref{66,,gzip}'s @ref{410,,gzip.GzipFile},
deprecated since Python 2.6, use the @ref{4f6,,name} attribute
instead. In write mode, the @code{filename} attribute added @code{'.gz'} file
extension if it was not present.
(Contributed by Victor Stinner in gh-94196@footnote{https://github.com/python/cpython/issues/94196}.)
@end itemize

@node hashlib,importlib<2>,gzip,Retraits
@anchor{whatsnew/3 12 hashlib}@anchor{4f7}
@subsubsection `hashlib'



@itemize *

@item 
Remove the pure Python implementation of @ref{67,,hashlib}'s
@ref{4f8,,hashlib.pbkdf2_hmac()}, deprecated in Python 3.10. Python 3.10 and
newer requires OpenSSL 1.1.1 (
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}): this OpenSSL version provides
a C implementation of @ref{4f8,,pbkdf2_hmac()} which is faster.
(Contributed by Victor Stinner in gh-94199@footnote{https://github.com/python/cpython/issues/94199}.)
@end itemize

@node importlib<2>,imp,hashlib,Retraits
@anchor{whatsnew/3 12 importlib}@anchor{4f9}
@subsubsection `importlib'



@itemize *

@item 
Many previously deprecated cleanups in @ref{76,,importlib} have now been
completed:


@itemize *

@item 
References to, and support for @code{module_repr()} has been removed.
(Contributed by Barry Warsaw in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@code{importlib.util.set_package}, @code{importlib.util.set_loader} and
@code{importlib.util.module_for_loader} have all been removed. (Contributed by
Brett Cannon and Nikita Sobolev in gh-65961@footnote{https://github.com/python/cpython/issues/65961} and gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
Support for @code{find_loader()} and @code{find_module()} APIs have been
removed.  (Contributed by Barry Warsaw in gh-98040@footnote{https://github.com/python/cpython/issues/98040}.)

@item 
@code{importlib.abc.Finder}, @code{pkgutil.ImpImporter}, and @code{pkgutil.ImpLoader}
have been removed.  (Contributed by Barry Warsaw in gh-98040@footnote{https://github.com/python/cpython/issues/98040}.)
@end itemize
@end itemize

@node imp,io<2>,importlib<2>,Retraits
@anchor{whatsnew/3 12 imp}@anchor{4fa}@anchor{whatsnew/3 12 whatsnew312-removed-imp}@anchor{4fb}
@subsubsection imp



@itemize *

@item 
The @code{imp} module has been removed.  (Contributed by Barry Warsaw in
gh-98040@footnote{https://github.com/python/cpython/issues/98040}.)

To migrate, consult the following correspondence table:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

imp

@tab

`importlib'

@item

@code{imp.NullImporter}

@tab

Insert @code{None} into @code{sys.path_importer_cache}

@item

@code{imp.cache_from_source()}

@tab

@ref{2f2,,importlib.util.cache_from_source()}

@item

@code{imp.find_module()}

@tab

@ref{2cb,,importlib.util.find_spec()}

@item

@code{imp.get_magic()}

@tab

@ref{4fc,,importlib.util.MAGIC_NUMBER}

@item

@code{imp.get_suffixes()}

@tab

@ref{4fd,,importlib.machinery.SOURCE_SUFFIXES}, @ref{4fe,,importlib.machinery.EXTENSION_SUFFIXES}, and @ref{4ff,,importlib.machinery.BYTECODE_SUFFIXES}

@item

@code{imp.get_tag()}

@tab

@ref{500,,sys.implementation.cache_tag}

@item

@code{imp.load_module()}

@tab

@ref{501,,importlib.import_module()}

@item

@code{imp.new_module(name)}

@tab

@code{types.ModuleType(name)}

@item

@code{imp.reload()}

@tab

@ref{502,,importlib.reload()}

@item

@code{imp.source_from_cache()}

@tab

@ref{503,,importlib.util.source_from_cache()}

@item

@code{imp.load_source()}

@tab

`See below'

@end multitable

@end quotation

Replace @code{imp.load_source()} with:

@example
import importlib.util
import importlib.machinery

def load_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)
    return module
@end example

@item 
Remove @code{imp} functions and attributes with no replacements:


@itemize *

@item 
Undocumented functions:


@itemize *

@item 
@code{imp.init_builtin()}

@item 
@code{imp.load_compiled()}

@item 
@code{imp.load_dynamic()}

@item 
@code{imp.load_package()}
@end itemize

@item 
@code{imp.lock_held()}, @code{imp.acquire_lock()}, @code{imp.release_lock()}:
the locking scheme has changed in Python 3.3 to per-module locks.

@item 
@code{imp.find_module()} constants: @code{SEARCH_ERROR}, @code{PY_SOURCE},
@code{PY_COMPILED}, @code{C_EXTENSION}, @code{PY_RESOURCE}, @code{PKG_DIRECTORY},
@code{C_BUILTIN}, @code{PY_FROZEN}, @code{PY_CODERESOURCE}, @code{IMP_HOOK}.
@end itemize
@end itemize

@node io<2>,locale<2>,imp,Retraits
@anchor{whatsnew/3 12 io}@anchor{504}
@subsubsection io



@itemize *

@item 
Remove @ref{7e,,io}'s @code{io.OpenWrapper} and @code{_pyio.OpenWrapper}, deprecated in Python
3.10: just use @ref{505,,open()} instead. The @ref{505,,open()} (@ref{506,,io.open()})
function is a built-in function. Since Python 3.10, @code{_pyio.open()} is
also a static method.
(Contributed by Victor Stinner in gh-94169@footnote{https://github.com/python/cpython/issues/94169}.)
@end itemize

@node locale<2>,smtpd,io<2>,Retraits
@anchor{whatsnew/3 12 locale}@anchor{507}
@subsubsection locale



@itemize *

@item 
Remove @ref{85,,locale}'s @code{locale.format()} function, deprecated in Python 3.7:
use @ref{508,,locale.format_string()} instead.
(Contributed by Victor Stinner in gh-94226@footnote{https://github.com/python/cpython/issues/94226}.)
@end itemize

@node smtpd,sqlite3<3>,locale<2>,Retraits
@anchor{whatsnew/3 12 smtpd}@anchor{509}
@subsubsection smtpd



@itemize *

@item 
The @code{smtpd} module has been removed according to the schedule in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/},
having been deprecated in Python 3.4.7 and 3.5.4.
Use the aiosmtpd@footnote{https://pypi.org/project/aiosmtpd/} PyPI module or any other
@ref{a,,asyncio}-based server instead.
(Contributed by Oleg Iarygin in gh-93243@footnote{https://github.com/python/cpython/issues/93243}.)
@end itemize

@node sqlite3<3>,ssl<2>,smtpd,Retraits
@anchor{whatsnew/3 12 id2}@anchor{50a}
@subsubsection @code{sqlite3}



@itemize *

@item 
The following undocumented @ref{ce,,sqlite3} features, deprecated in Python
3.10, are now removed:


@itemize *

@item 
@code{sqlite3.enable_shared_cache()}

@item 
@code{sqlite3.OptimizedUnicode}
@end itemize

If a shared cache must be used, open the database in URI mode using the
@code{cache=shared} query parameter.

The @code{sqlite3.OptimizedUnicode} text factory has been an alias for
@ref{435,,str} since Python 3.3. Code that previously set the text factory to
@code{OptimizedUnicode} can either use @code{str} explicitly, or rely on the
default value which is also @code{str}.

(Contributed by Erlend E. Aasland in gh-92548@footnote{https://github.com/python/cpython/issues/92548}.)
@end itemize

@node ssl<2>,unittest<3>,sqlite3<3>,Retraits
@anchor{whatsnew/3 12 ssl}@anchor{50b}
@subsubsection @code{ssl}



@itemize *

@item 
Remove @ref{cf,,ssl}'s @code{ssl.RAND_pseudo_bytes()} function, deprecated in Python 3.6:
use @ref{50c,,os.urandom()} or @ref{50d,,ssl.RAND_bytes()} instead.
(Contributed by Victor Stinner in gh-94199@footnote{https://github.com/python/cpython/issues/94199}.)

@item 
Remove the @code{ssl.match_hostname()} function.
It was deprecated in Python 3.7. OpenSSL performs
hostname matching since Python 3.7, Python no longer uses the
@code{ssl.match_hostname()} function.
(Contributed by Victor Stinner in gh-94199@footnote{https://github.com/python/cpython/issues/94199}.)

@item 
Remove the @code{ssl.wrap_socket()} function, deprecated in Python 3.7:
instead, create a @ref{291,,ssl.SSLContext} object and call its
@ref{50e,,ssl.SSLContext.wrap_socket} method. Any package that still uses
@code{ssl.wrap_socket()} is broken and insecure. The function neither sends a
SNI TLS extension nor validates the server hostname. Code is subject to 
@geindex Common Weakness Enumeration; CWE 295
CWE 295@footnote{https://cwe.mitre.org/data/definitions/295.html}
(Improper Certificate Validation).
(Contributed by Victor Stinner in gh-94199@footnote{https://github.com/python/cpython/issues/94199}.)
@end itemize

@node unittest<3>,webbrowser<2>,ssl<2>,Retraits
@anchor{whatsnew/3 12 id3}@anchor{50f}
@subsubsection unittest



@itemize *

@item 
Remove many long-deprecated @ref{105,,unittest} features:


@itemize *

@item 
A number of @ref{437,,TestCase} method aliases:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Alias obsolètes

@tab

Nom de méthode

@tab

Obsolète en

@item

@code{failUnless}

@tab

@ref{510,,assertTrue()}

@tab

3.1

@item

@code{failIf}

@tab

@ref{511,,assertFalse()}

@tab

3.1

@item

@code{failUnlessEqual}

@tab

@ref{512,,assertEqual()}

@tab

3.1

@item

@code{failIfEqual}

@tab

@ref{513,,assertNotEqual()}

@tab

3.1

@item

@code{failUnlessAlmostEqual}

@tab

@ref{514,,assertAlmostEqual()}

@tab

3.1

@item

@code{failIfAlmostEqual}

@tab

@ref{515,,assertNotAlmostEqual()}

@tab

3.1

@item

@code{failUnlessRaises}

@tab

@ref{516,,assertRaises()}

@tab

3.1

@item

@code{assert_}

@tab

@ref{510,,assertTrue()}

@tab

3.2

@item

@code{assertEquals}

@tab

@ref{512,,assertEqual()}

@tab

3.2

@item

@code{assertNotEquals}

@tab

@ref{513,,assertNotEqual()}

@tab

3.2

@item

@code{assertAlmostEquals}

@tab

@ref{514,,assertAlmostEqual()}

@tab

3.2

@item

@code{assertNotAlmostEquals}

@tab

@ref{515,,assertNotAlmostEqual()}

@tab

3.2

@item

@code{assertRegexpMatches}

@tab

@ref{517,,assertRegex()}

@tab

3.2

@item

@code{assertRaisesRegexp}

@tab

@ref{518,,assertRaisesRegex()}

@tab

3.2

@item

@code{assertNotRegexpMatches}

@tab

@ref{519,,assertNotRegex()}

@tab

3.5

@end multitable


You can use @indicateurl{https://github.com/isidentical/teyit} to automatically modernise
your unit tests.

@item 
Undocumented and broken @ref{437,,TestCase} method
@code{assertDictContainsSubset} (deprecated in Python 3.2).

@item 
Undocumented @ref{28c,,TestLoader.loadTestsFromModule} parameter `use_load_tests'
(deprecated and ignored since Python 3.5).

@item 
An alias of the @ref{51a,,TextTestResult} class:
@code{_TextTestResult} (deprecated in Python 3.2).
@end itemize

(Contributed by Serhiy Storchaka in gh-89325@footnote{https://github.com/python/cpython/issues/89325}.)
@end itemize

@node webbrowser<2>,xml etree ElementTree,unittest<3>,Retraits
@anchor{whatsnew/3 12 webbrowser}@anchor{51b}
@subsubsection webbrowser



@itemize *

@item 
Remove support for obsolete browsers from @ref{114,,webbrowser}.
The removed browsers include: Grail, Mosaic, Netscape, Galeon, Skipstone,
Iceape, Firebird, and Firefox versions 35 and below (gh-102871@footnote{https://github.com/python/cpython/issues/102871}).
@end itemize

@node xml etree ElementTree,zipimport<2>,webbrowser<2>,Retraits
@anchor{whatsnew/3 12 xml-etree-elementtree}@anchor{51c}
@subsubsection xml.etree.ElementTree



@itemize *

@item 
Remove the @code{ElementTree.Element.copy()} method of the
pure Python implementation, deprecated in Python 3.10, use the
@ref{51d,,copy.copy()} function instead.  The C implementation of @ref{124,,xml.etree.ElementTree}
has no @code{copy()} method, only a @code{__copy__()} method.
(Contributed by Victor Stinner in gh-94383@footnote{https://github.com/python/cpython/issues/94383}.)
@end itemize

@node zipimport<2>,Autres,xml etree ElementTree,Retraits
@anchor{whatsnew/3 12 zipimport}@anchor{51e}
@subsubsection @code{zipimport}



@itemize *

@item 
Remove @ref{131,,zipimport}'s @code{find_loader()} and @code{find_module()} methods,
deprecated in Python 3.10: use the @code{find_spec()} method instead.  See
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} for the rationale.
(Contributed by Victor Stinner in gh-94379@footnote{https://github.com/python/cpython/issues/94379}.)
@end itemize

@node Autres,,zipimport<2>,Retraits
@anchor{whatsnew/3 12 others}@anchor{51f}
@subsubsection Autres



@itemize *

@item 
Remove the @code{suspicious} rule from the documentation @code{Makefile} and
@code{Doc/tools/rstlint.py}, both in favor of sphinx-lint@footnote{https://github.com/sphinx-contrib/sphinx-lint}.
(Contributed by Julien Palard in gh-98179@footnote{https://github.com/python/cpython/issues/98179}.)

@item 
Remove the `keyfile' and `certfile' parameters from the
@ref{5d,,ftplib}, @ref{73,,imaplib}, @ref{ab,,poplib} and @ref{c9,,smtplib} modules,
and the `key_file', `cert_file' and `check_hostname' parameters from the
@ref{6e,,http.client} module,
all deprecated since Python 3.6. Use the `context' parameter
(`ssl_context' in @ref{73,,imaplib}) instead.
(Contributed by Victor Stinner in gh-94172@footnote{https://github.com/python/cpython/issues/94172}.)

@item 
Remove @code{Jython} compatibility hacks from several stdlib modules and tests.
(Contributed by Nikita Sobolev in gh-99482@footnote{https://github.com/python/cpython/issues/99482}.)

@item 
Remove @code{_use_broken_old_ctypes_structure_semantics_} flag
from @ref{2a,,ctypes} module.
(Contributed by Nikita Sobolev in gh-99285@footnote{https://github.com/python/cpython/issues/99285}.)
@end itemize

@node Porting to Python 3 12,Changements à la compilation<2>,Retraits,What's New In Python 3 12
@anchor{whatsnew/3 12 porting-to-python-3-12}@anchor{520}@anchor{whatsnew/3 12 whatsnew312-porting-to-python312}@anchor{4b5}
@subsection Porting to Python 3.12


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changements dans l'API Python: Changements dans l'API Python<2>. 

@end menu

@node Changements dans l'API Python<2>,,,Porting to Python 3 12
@anchor{whatsnew/3 12 changes-in-the-python-api}@anchor{521}
@subsubsection Changements dans l'API Python



@itemize *

@item 
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 in gh-91760@footnote{https://github.com/python/cpython/issues/91760}.)

@item 
Remove @code{randrange()} functionality deprecated since Python 3.10.  Formerly,
@code{randrange(10.0)} losslessly converted to @code{randrange(10)}. Now, it raises a
@ref{522,,TypeError}. Also, the exception raised for non-integer values such as
@code{randrange(10.5)} or @code{randrange('10')} has been changed from @ref{1ff,,ValueError} to
@ref{522,,TypeError}.  This also prevents bugs where @code{randrange(1e25)} would silently
select from a larger range than @code{randrange(10**25)}.
(Originally suggested by Serhiy Storchaka gh-86388@footnote{https://github.com/python/cpython/issues/86388}.)

@item 
@ref{523,,argparse.ArgumentParser} changed encoding and error handler
for reading arguments from file (e.g. @code{fromfile_prefix_chars} option)
from default text encoding (e.g. @ref{524,,locale.getpreferredencoding(False)})
to @ref{525,,filesystem encoding and error handler}.
Argument files should be encoded in UTF-8 instead of ANSI Codepage on Windows.

@item 
Remove the @code{asyncore}-based @code{smtpd} module deprecated in Python 3.4.7
and 3.5.4.  A recommended replacement is the
@ref{a,,asyncio}-based aiosmtpd@footnote{https://pypi.org/project/aiosmtpd/} PyPI module.

@item 
@ref{526,,shlex.split()}: Passing @code{None} for `s' argument now raises an
exception, rather than reading @ref{527,,sys.stdin}. The feature was deprecated
in Python 3.9.
(Contributed by Victor Stinner in gh-94352@footnote{https://github.com/python/cpython/issues/94352}.)

@item 
The @ref{a0,,os} module no longer accepts bytes-like paths, like
@ref{528,,bytearray} and @ref{452,,memoryview} types: only the exact
@ref{1bd,,bytes} type is accepted for bytes strings.
(Contributed by Victor Stinner in gh-98393@footnote{https://github.com/python/cpython/issues/98393}.)

@item 
@ref{529,,syslog.openlog()} and @ref{52a,,syslog.closelog()} now fail if used in subinterpreters.
@ref{52b,,syslog.syslog()} may still be used in subinterpreters,
but now only if @ref{529,,syslog.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, @ref{db,,syslog} is a wrapper
around process-global resources, which are best managed from the main interpreter.
(Contributed by Donghee Na in gh-99127@footnote{https://github.com/python/cpython/issues/99127}.)

@item 
The undocumented locking behavior of @ref{52c,,cached_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.

@item 
@ref{4ab,,sys._current_exceptions()} now returns a mapping from thread-id to an
exception instance, rather than to a @code{(typ, exc, tb)} tuple.
(Contributed by Irit Katriel in gh-103176@footnote{https://github.com/python/cpython/issues/103176}.)

@item 
When extracting tar files using @ref{dd,,tarfile} or
@ref{455,,shutil.unpack_archive()}, pass the `filter' argument to limit features
that may be surprising or dangerous.
See @ref{456,,Extraction filters} for details.

@item 
The output of the @ref{4c3,,tokenize.tokenize()} and @ref{4c4,,tokenize.generate_tokens()}
functions is now changed due to the changes introduced in 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/}. This
means that @code{STRING} tokens are not emitted any more for f-strings and the
tokens described in 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/} are now produced instead: @code{FSTRING_START},
@code{FSTRING_MIDDLE} and @code{FSTRING_END} are 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-string @code{f"start @{1+1@} end"}
the old version of the tokenizer emitted:

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

while the new version emits:

@example
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    '"'
@end example

Additionally, there may be some minor behavioral changes as a consequence of the
changes required to support 
@geindex Python Enhancement Proposals; PEP 701
PEP 701@footnote{https://peps.python.org/pep-0701/}. Some of these changes include:


@itemize *

@item 
The @code{type} attribute of the tokens emitted when tokenizing some invalid Python
characters such as @code{!} has changed from @code{ERRORTOKEN} to @code{OP}.

@item 
Incomplete single-line strings now also raise @ref{52d,,tokenize.TokenError} as incomplete
multiline strings do.

@item 
Some incomplete or invalid Python code now raises @ref{52d,,tokenize.TokenError} instead of
returning arbitrary @code{ERRORTOKEN} tokens when tokenizing it.

@item 
Mixing tabs and spaces as indentation in the same file is not supported anymore and will
raise a @ref{52e,,TabError}.
@end itemize

@item 
The @ref{ec,,threading} module now expects the @code{_thread} module to have
an @code{_is_main_interpreter} attribute.  It is a function with no
arguments that returns @code{True} if the current interpreter is the
main interpreter.

Any library or application that provides a custom @code{_thread} module
should provide @code{_is_main_interpreter()}.
(See gh-112826@footnote{https://github.com/python/cpython/issues/112826}.)
@end itemize

@node Changements à la compilation<2>,Changements à l'API C<2>,Porting to Python 3 12,What's New In Python 3 12
@anchor{whatsnew/3 12 build-changes}@anchor{52f}
@subsection Changements à la compilation



@itemize *

@item 
Python no longer uses @code{setup.py} to build shared C extension modules.
Build parameters like headers and libraries are detected in @code{configure}
script. Extensions are built by @code{Makefile}. Most extensions use
@code{pkg-config} and fall back to manual detection.
(Contributed by Christian Heimes in gh-93939@footnote{https://github.com/python/cpython/issues/93939}.)

@item 
@code{va_start()} with two parameters, like @code{va_start(args, format),}
is now required to build Python.
@code{va_start()} is no longer called with a single parameter.
(Contributed by Kumar Aditya in gh-93207@footnote{https://github.com/python/cpython/issues/93207}.)

@item 
CPython now uses the ThinLTO option as the default link time optimization policy
if the Clang compiler accepts the flag.
(Contributed by Donghee Na in gh-89536@footnote{https://github.com/python/cpython/issues/89536}.)

@item 
Add @code{COMPILEALL_OPTS} variable in @code{Makefile} to override @ref{20,,compileall}
options (default: @code{-j0}) in @code{make install}. Also merged the 3
@code{compileall} commands into a single command to build .pyc files for all
optimization levels (0, 1, 2) at once.
(Contributed by Victor Stinner in gh-99289@footnote{https://github.com/python/cpython/issues/99289}.)

@item 
Add platform triplets for 64-bit LoongArch:


@itemize *

@item 
loongarch64-linux-gnusf

@item 
loongarch64-linux-gnuf32

@item 
loongarch64-linux-gnu
@end itemize

(Contributed by Zhang Na in gh-90656@footnote{https://github.com/python/cpython/issues/90656}.)

@item 
@code{PYTHON_FOR_REGEN} now require Python 3.10 or newer.

@item 
Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate
@code{!configure}.
(Contributed by Christian Heimes in gh-89886@footnote{https://github.com/python/cpython/issues/89886}.)

@item 
Windows builds and macOS installers from python.org now use OpenSSL 3.0.
@end itemize

@node Changements à l'API C<2>,,Changements à la compilation<2>,What's New In Python 3 12
@anchor{whatsnew/3 12 c-api-changes}@anchor{530}
@subsection Changements à l'API C


@menu
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<4>. 
* Porting to Python 3.12: Porting to Python 3 12<2>. 
* Obsolescence: Obsolescence<2>. 
* Retraits: Retraits<2>. 

@end menu

@node Nouvelles fonctionnalités<4>,Porting to Python 3 12<2>,,Changements à l'API C<2>
@anchor{whatsnew/3 12 id4}@anchor{531}
@subsubsection Nouvelles fonctionnalités

@anchor{whatsnew/3 12 whatsnew312-pep697}@anchor{42e}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 697
PEP 697@footnote{https://peps.python.org/pep-0697/}: Introduce the @ref{532,,Unstable C API tier},
intended for low-level tools like debuggers and JIT compilers.
This API may change in each minor release of CPython without deprecation
warnings.
Its contents are marked by the @code{PyUnstable_} prefix in names.

Code object constructors:


@itemize -

@item 
@code{PyUnstable_Code_New()} (renamed from @code{PyCode_New})

@item 
@code{PyUnstable_Code_NewWithPosOnlyArgs()} (renamed from @code{PyCode_NewWithPosOnlyArgs})
@end itemize

Extra storage for code objects (
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/}):


@itemize -

@item 
@code{PyUnstable_Eval_RequestCodeExtraIndex()} (renamed from @code{_PyEval_RequestCodeExtraIndex})

@item 
@code{PyUnstable_Code_GetExtra()} (renamed from @code{_PyCode_GetExtra})

@item 
@code{PyUnstable_Code_SetExtra()} (renamed from @code{_PyCode_SetExtra})
@end itemize

The original names will continue to be available until the respective
API changes.

(Contributed by Petr Viktorin in gh-101101@footnote{https://github.com/python/cpython/issues/101101}.)

@item 
@geindex Python Enhancement Proposals; PEP 697
PEP 697@footnote{https://peps.python.org/pep-0697/}: Add an API for extending types whose instance memory layout is
opaque:


@itemize -

@item 
@ref{533,,PyType_Spec.basicsize} can be zero or negative to specify
inheriting or extending the base class size.

@item 
@ref{534,,PyObject_GetTypeData()} and @ref{535,,PyType_GetTypeDataSize()}
added to allow access to subclass-specific instance data.

@item 
@ref{536,,Py_TPFLAGS_ITEMS_AT_END} and @ref{537,,PyObject_GetItemData()}
added to allow safely extending certain variable-sized types, including
@ref{538,,PyType_Type}.

@item 
@ref{539,,Py_RELATIVE_OFFSET} added to allow defining
@ref{53a,,members} in terms of a subclass-specific struct.
@end itemize

(Contributed by Petr Viktorin in gh-103509@footnote{https://github.com/python/cpython/issues/103509}.)

@item 
Add the new @ref{38c,,limited C API} function @ref{53b,,PyType_FromMetaclass()},
which generalizes the existing @ref{53c,,PyType_FromModuleAndSpec()} using
an additional metaclass argument.
(Contributed by Wenzel Jakob in gh-93012@footnote{https://github.com/python/cpython/issues/93012}.)

@item 
API for creating objects that can be called using
@ref{53d,,the vectorcall protocol} was added to the
@ref{53e,,Limited API}:


@itemize *

@item 
@ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL}

@item 
@ref{540,,PyVectorcall_NARGS()}

@item 
@ref{541,,PyVectorcall_Call()}

@item 
@ref{542,,vectorcallfunc}
@end itemize

The @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed from a class
when the class's @ref{543,,__call__()} method is reassigned.
This makes vectorcall safe to use with mutable types (i.e. heap types
without the immutable flag, @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE}).
Mutable types that do not override @ref{544,,tp_call} now
inherit the @code{Py_TPFLAGS_HAVE_VECTORCALL} flag.
(Contributed by Petr Viktorin in gh-93274@footnote{https://github.com/python/cpython/issues/93274}.)

The @ref{361,,Py_TPFLAGS_MANAGED_DICT} and @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF}
flags have been added. This allows extensions classes to support object
@ref{546,,__dict__} and weakrefs with less bookkeeping,
using less memory and with faster access.

@item 
API for performing calls using
@ref{53d,,the vectorcall protocol} was added to the
@ref{53e,,Limited API}:


@itemize *

@item 
@ref{547,,PyObject_Vectorcall()}

@item 
@ref{548,,PyObject_VectorcallMethod()}

@item 
@ref{549,,PY_VECTORCALL_ARGUMENTS_OFFSET}
@end itemize

This means that both the incoming and outgoing ends of the vector call
protocol are now available in the @ref{53e,,Limited API}. (Contributed
by Wenzel Jakob in gh-98586@footnote{https://github.com/python/cpython/issues/98586}.)

@item 
Add two new public functions,
@ref{54a,,PyEval_SetProfileAllThreads()} and
@ref{54b,,PyEval_SetTraceAllThreads()}, that allow to set tracing and profiling
functions in all running threads in addition to the calling one. (Contributed
by Pablo Galindo in gh-93503@footnote{https://github.com/python/cpython/issues/93503}.)

@item 
Add new function @ref{54c,,PyFunction_SetVectorcall()} to the C API
which sets the vectorcall field of a given @ref{54d,,PyFunctionObject}.
(Contributed by Andrew Frost in gh-92257@footnote{https://github.com/python/cpython/issues/92257}.)

@item 
The C API now permits registering callbacks via @ref{54e,,PyDict_AddWatcher()},
@ref{54f,,PyDict_Watch()} and related APIs to be called whenever a dictionary
is modified. This is intended for use by optimizing interpreters, JIT
compilers, or debuggers.
(Contributed by Carl Meyer in gh-91052@footnote{https://github.com/python/cpython/issues/91052}.)

@item 
Add @ref{550,,PyType_AddWatcher()} and @ref{551,,PyType_Watch()} API to register
callbacks to receive notification on changes to a type.
(Contributed by Carl Meyer in gh-91051@footnote{https://github.com/python/cpython/issues/91051}.)

@item 
Add @ref{552,,PyCode_AddWatcher()} and @ref{553,,PyCode_ClearWatcher()}
APIs to register callbacks to receive notification on creation and
destruction of code objects.
(Contributed by Itamar Oren in gh-91054@footnote{https://github.com/python/cpython/issues/91054}.)

@item 
Add @ref{554,,PyFrame_GetVar()} and @ref{555,,PyFrame_GetVarString()} functions to
get a frame variable by its name.
(Contributed by Victor Stinner in gh-91248@footnote{https://github.com/python/cpython/issues/91248}.)

@item 
Add @ref{3ea,,PyErr_GetRaisedException()} and @ref{3ed,,PyErr_SetRaisedException()}
for saving and restoring the current exception.
These functions return and accept a single exception object,
rather than the triple arguments of the now-deprecated
@ref{3e9,,PyErr_Fetch()} and @ref{3ec,,PyErr_Restore()}.
This is less error prone and a bit more efficient.
(Contributed by Mark Shannon in gh-101578@footnote{https://github.com/python/cpython/issues/101578}.)

@item 
Add @code{_PyErr_ChainExceptions1}, which takes an exception instance,
to replace the legacy-API @code{_PyErr_ChainExceptions}, which is now
deprecated. (Contributed by Mark Shannon in gh-101578@footnote{https://github.com/python/cpython/issues/101578}.)

@item 
Add @ref{556,,PyException_GetArgs()} and @ref{557,,PyException_SetArgs()}
as convenience functions for retrieving and modifying
the @ref{558,,args} passed to the exception's constructor.
(Contributed by Mark Shannon in gh-101578@footnote{https://github.com/python/cpython/issues/101578}.)

@item 
Add @ref{3f8,,PyErr_DisplayException()}, which takes an exception instance,
to replace the legacy-api @code{PyErr_Display()}. (Contributed by
Irit Katriel in gh-102755@footnote{https://github.com/python/cpython/issues/102755}).
@end itemize
@anchor{whatsnew/3 12 whatsnew312-pep683}@anchor{42f}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 683
PEP 683@footnote{https://peps.python.org/pep-0683/}: Introduce `Immortal Objects', which allows objects
to bypass reference counts, and related changes to the C-API:


@itemize -

@item 

@table @asis

@item @code{_Py_IMMORTAL_REFCNT}: The reference count that defines an object

as immortal.
@end table

@item 
@code{_Py_IsImmortal} Checks if an object has the immortal reference count.

@item 

@table @asis

@item @code{PyObject_HEAD_INIT} This will now initialize reference count to

@code{_Py_IMMORTAL_REFCNT} when used with @code{Py_BUILD_CORE}.
@end table

@item 

@table @asis

@item @code{SSTATE_INTERNED_IMMORTAL} An identifier for interned unicode objects

that are immortal.
@end table

@item 

@table @asis

@item @code{SSTATE_INTERNED_IMMORTAL_STATIC} An identifier for interned unicode

objects that are immortal and static
@end table

@item 

@table @asis

@item @code{sys.getunicodeinternedsize} This returns the total number of unicode

objects that have been interned. This is now needed for @code{refleak.py} to
correctly track reference counts and allocated blocks
@end table
@end itemize

(Contributed by Eddie Elizondo in gh-84436@footnote{https://github.com/python/cpython/issues/84436}.)

@item 
@geindex Python Enhancement Proposals; PEP 684
PEP 684@footnote{https://peps.python.org/pep-0684/}: Add the new @ref{445,,Py_NewInterpreterFromConfig()}
function and @ref{559,,PyInterpreterConfig}, which may be used
to create sub-interpreters with their own GILs.
(See @ref{425,,PEP 684; A Per-Interpreter GIL} for more info.)
(Contributed by Eric Snow in gh-104110@footnote{https://github.com/python/cpython/issues/104110}.)

@item 
In the limited C API version 3.12, @ref{55a,,Py_INCREF()} and
@ref{55b,,Py_DECREF()} functions are now implemented as opaque function calls to
hide implementation details.
(Contributed by Victor Stinner in gh-105387@footnote{https://github.com/python/cpython/issues/105387}.)
@end itemize

@node Porting to Python 3 12<2>,Obsolescence<2>,Nouvelles fonctionnalités<4>,Changements à l'API C<2>
@anchor{whatsnew/3 12 id5}@anchor{55c}
@subsubsection Porting to Python 3.12



@itemize *

@item 
Legacy Unicode APIs based on @code{Py_UNICODE*} representation has been removed.
Please migrate to APIs based on UTF-8 or @code{wchar_t*}.

@item 
Argument parsing functions like @ref{55d,,PyArg_ParseTuple()} doesn't support
@code{Py_UNICODE*} based format (e.g. @code{u}, @code{Z}) anymore. Please migrate
to other formats for Unicode like @code{s}, @code{z}, @code{es}, and @code{U}.

@item 
@code{tp_weaklist} for all static builtin types is always @code{NULL}.
This is an internal-only field on @code{PyTypeObject}
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) @code{_PyObject_GET_WEAKREFS_LISTPTR()} macro.

@item 
This internal-only @ref{55e,,PyTypeObject.tp_subclasses} may now not be
a valid object pointer.  Its type was changed to void* 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
@ref{55f,,__subclasses__()} (using @ref{396,,PyObject_CallMethod()},
for example).

@item 
Add support of more formatting options (left aligning, octals, uppercase
hexadecimals, @code{intmax_t}, @code{ptrdiff_t}, @code{wchar_t} C
strings, variable width and precision) in @ref{380,,PyUnicode_FromFormat()} and
@ref{560,,PyUnicode_FromFormatV()}.
(Contributed by Serhiy Storchaka in gh-98836@footnote{https://github.com/python/cpython/issues/98836}.)

@item 
An unrecognized format character in @ref{380,,PyUnicode_FromFormat()} and
@ref{560,,PyUnicode_FromFormatV()} now sets a @ref{561,,SystemError}.
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 in gh-95781@footnote{https://github.com/python/cpython/issues/95781}.)

@item 
Fix wrong sign placement in @ref{380,,PyUnicode_FromFormat()} and
@ref{560,,PyUnicode_FromFormatV()}.
(Contributed by Philip Georgi in gh-95504@footnote{https://github.com/python/cpython/issues/95504}.)

@item 
Extension classes wanting to add a @ref{546,,__dict__} or weak reference slot
should use @ref{361,,Py_TPFLAGS_MANAGED_DICT} and
@ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} instead of @code{tp_dictoffset} and
@code{tp_weaklistoffset}, respectively.
The use of @code{tp_dictoffset} and @code{tp_weaklistoffset} is still
supported, but does not fully support multiple inheritance
(gh-95589@footnote{https://github.com/python/cpython/issues/95589}), and performance may be worse.
Classes declaring @ref{361,,Py_TPFLAGS_MANAGED_DICT} must call
@code{_PyObject_VisitManagedDict()} and @code{_PyObject_ClearManagedDict()}
to traverse and clear their instance's dictionaries.
To clear weakrefs, call @ref{562,,PyObject_ClearWeakRefs()}, as before.

@item 
The @ref{563,,PyUnicode_FSDecoder()} function no longer accepts bytes-like
paths, like @ref{528,,bytearray} and @ref{452,,memoryview} types: only the exact
@ref{1bd,,bytes} type is accepted for bytes strings.
(Contributed by Victor Stinner in gh-98393@footnote{https://github.com/python/cpython/issues/98393}.)

@item 
The @ref{564,,Py_CLEAR}, @ref{565,,Py_SETREF} and @ref{566,,Py_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 in gh-98724@footnote{https://github.com/python/cpython/issues/98724}.)

@item 
The interpreter's error indicator is now always normalized. This means
that @ref{567,,PyErr_SetObject()}, @ref{568,,PyErr_SetString()} and the other
functions that set the error indicator now normalize the exception
before storing it. (Contributed by Mark Shannon in gh-101578@footnote{https://github.com/python/cpython/issues/101578}.)

@item 
@code{_Py_RefTotal} is 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 @code{_Py_GetGlobalRefTotal()}.

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


@itemize *

@item 
@ref{569,,PyType_FromSpec()}

@item 
@ref{56a,,PyType_FromSpecWithBases()}

@item 
@ref{53c,,PyType_FromModuleAndSpec()}
@end itemize

Creating classes whose metaclass overrides @ref{56b,,tp_new}
is deprecated, and in Python 3.14+ it will be disallowed.
Note that these functions ignore @code{tp_new} of the metaclass, possibly
allowing incomplete initialization.

Note that @ref{53b,,PyType_FromMetaclass()} (added in Python 3.12)
already disallows creating classes whose metaclass overrides @code{tp_new}
(@ref{56c,,__new__()} in Python).

Since @code{tp_new} overrides almost everything @code{PyType_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
@code{tp_new} was called.
There is no simple general workaround. One of the following may work for you:


@itemize -

@item 
If you control the metaclass, avoid using @code{tp_new} in it:


@itemize -

@item 
If initialization can be skipped, it can be done in
@ref{56d,,tp_init} instead.

@item 
If the metaclass doesn't need to be instantiated from Python,
set its @code{tp_new} to @code{NULL} using
the @ref{56e,,Py_TPFLAGS_DISALLOW_INSTANTIATION} flag.
This makes it acceptable for @code{PyType_From*} functions.
@end itemize

@item 
Avoid @code{PyType_From*} functions: if you don't need C-specific features
(slots or setting the instance size), create types by @ref{56f,,calling}
the metaclass.

@item 
If you `know' the @code{tp_new} can be skipped safely, filter the deprecation
warning out using @ref{570,,warnings.catch_warnings()} from Python.
@end itemize

@item 
@ref{571,,PyOS_InputHook} and @ref{572,,PyOS_ReadlineFunctionPointer} are no
longer called in @ref{573,,subinterpreters}. 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-104668@footnote{https://github.com/python/cpython/issues/104668} for more info.

@item 
@ref{574,,PyLongObject} has had its internals changed for better performance.
Although the internals of @ref{574,,PyLongObject} are private, they are used
by some extension modules.
The internal fields should no longer be accessed directly, instead the API
functions beginning @code{PyLong_...} should be used instead.
Two new `unstable' API functions are provided for efficient access to the
value of @ref{574,,PyLongObject}s which fit into a single machine word:


@itemize *

@item 
@ref{575,,PyUnstable_Long_IsCompact()}

@item 
@ref{576,,PyUnstable_Long_CompactValue()}
@end itemize

@item 
Custom allocators, set via @ref{577,,PyMem_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 @code{@@ericsnowcurrently}.
@end itemize

@node Obsolescence<2>,Retraits<2>,Porting to Python 3 12<2>,Changements à l'API C<2>
@anchor{whatsnew/3 12 id6}@anchor{578}
@subsubsection Obsolescence



@itemize *

@item 
In accordance with 
@geindex Python Enhancement Proposals; PEP 699
PEP 699@footnote{https://peps.python.org/pep-0699/}, the @code{ma_version_tag} field in @ref{3b8,,PyDictObject}
is deprecated for extension modules. Accessing this field will generate a compiler
warning at compile time. This field will be removed in Python 3.14.
(Contributed by Ramvikrams and Kumar Aditya in gh-101193@footnote{https://github.com/python/cpython/issues/101193}. PEP by Ken Jin.)

@item 
Deprecate global configuration variable:


@itemize *

@item 
@ref{3bd,,Py_DebugFlag}: use @ref{3be,,PyConfig.parser_debug}

@item 
@ref{3bf,,Py_VerboseFlag}: use @ref{3c0,,PyConfig.verbose}

@item 
@ref{3c1,,Py_QuietFlag}: use @ref{3c2,,PyConfig.quiet}

@item 
@ref{3c3,,Py_InteractiveFlag}: use @ref{3c4,,PyConfig.interactive}

@item 
@ref{3c5,,Py_InspectFlag}: use @ref{3c6,,PyConfig.inspect}

@item 
@ref{3c7,,Py_OptimizeFlag}: use @ref{3c8,,PyConfig.optimization_level}

@item 
@ref{3c9,,Py_NoSiteFlag}: use @ref{3ca,,PyConfig.site_import}

@item 
@ref{3cb,,Py_BytesWarningFlag}: use @ref{3cc,,PyConfig.bytes_warning}

@item 
@ref{3cd,,Py_FrozenFlag}: use @ref{3ce,,PyConfig.pathconfig_warnings}

@item 
@ref{3cf,,Py_IgnoreEnvironmentFlag}: use @ref{3d0,,PyConfig.use_environment}

@item 
@ref{3d1,,Py_DontWriteBytecodeFlag}: use @ref{3d2,,PyConfig.write_bytecode}

@item 
@ref{3d3,,Py_NoUserSiteDirectory}: use @ref{3d4,,PyConfig.user_site_directory}

@item 
@ref{3d5,,Py_UnbufferedStdioFlag}: use @ref{3d6,,PyConfig.buffered_stdio}

@item 
@ref{3d7,,Py_HashRandomizationFlag}: use @ref{3d8,,PyConfig.use_hash_seed}
and @ref{3d9,,PyConfig.hash_seed}

@item 
@ref{3da,,Py_IsolatedFlag}: use @ref{3db,,PyConfig.isolated}

@item 
@ref{3dc,,Py_LegacyWindowsFSEncodingFlag}: use @ref{3dd,,PyPreConfig.legacy_windows_fs_encoding}

@item 
@ref{3de,,Py_LegacyWindowsStdioFlag}: use @ref{39b,,PyConfig.legacy_windows_stdio}

@item 
@code{Py_FileSystemDefaultEncoding}: use @ref{3df,,PyConfig.filesystem_encoding}

@item 
@code{Py_HasFileSystemDefaultEncoding}: use @ref{3df,,PyConfig.filesystem_encoding}

@item 
@code{Py_FileSystemDefaultEncodeErrors}: use @ref{3e0,,PyConfig.filesystem_errors}

@item 
@code{Py_UTF8Mode}: use @ref{3e1,,PyPreConfig.utf8_mode} (see @ref{3e2,,Py_PreInitialize()})
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.
(Contributed by Victor Stinner in gh-77782@footnote{https://github.com/python/cpython/issues/77782}.)

@item 
Creating @ref{3b9,,immutable types} with mutable
bases is deprecated and will be disabled in Python 3.14. (gh-95388@footnote{https://github.com/python/cpython/issues/95388})

@item 
The @code{structmember.h} header is deprecated, though it continues to be
available and there are no plans to remove it.

Its contents are now available just by including @code{Python.h},
with a @code{Py} prefix added if it was missing:


@itemize -

@item 
@ref{53a,,PyMemberDef}, @ref{579,,PyMember_GetOne()} and
@ref{57a,,PyMember_SetOne()}

@item 
Type macros like @ref{57b,,Py_T_INT}, @ref{57c,,Py_T_DOUBLE}, etc.
(previously @code{T_INT}, @code{T_DOUBLE}, etc.)

@item 
The flags @ref{57d,,Py_READONLY} (previously @code{READONLY}) and
@ref{57e,,Py_AUDIT_READ} (previously all uppercase)
@end itemize

Several items are not exposed from @code{Python.h}:


@itemize -

@item 
@ref{57f,,T_OBJECT} (use @ref{580,,Py_T_OBJECT_EX})

@item 
@ref{581,,T_NONE} (previously undocumented, and pretty quirky)

@item 
The macro @code{WRITE_RESTRICTED} which does nothing.

@item 
The macros @code{RESTRICTED} and @code{READ_RESTRICTED}, equivalents of
@ref{57e,,Py_AUDIT_READ}.

@item 
In some configurations, @code{<stddef.h>} is not included from @code{Python.h}.
It should be included manually when using @code{offsetof()}.
@end itemize

The deprecated header continues to provide its original
contents under the original names.
Your old code can stay unchanged, unless the extra include and non-namespaced
macros bother you greatly.

(Contributed in gh-47146@footnote{https://github.com/python/cpython/issues/47146} by Petr Viktorin, based on
earlier work by Alexander Belopolsky and Matthias Braun.)

@item 
@ref{3e9,,PyErr_Fetch()} and @ref{3ec,,PyErr_Restore()} are deprecated.
Use @ref{3ea,,PyErr_GetRaisedException()} and
@ref{3ed,,PyErr_SetRaisedException()} instead.
(Contributed by Mark Shannon in gh-101578@footnote{https://github.com/python/cpython/issues/101578}.)

@item 
@code{PyErr_Display()} is deprecated. Use @ref{3f8,,PyErr_DisplayException()}
instead. (Contributed by Irit Katriel in gh-102755@footnote{https://github.com/python/cpython/issues/102755}).

@item 
@code{_PyErr_ChainExceptions} is deprecated. Use @code{_PyErr_ChainExceptions1}
instead. (Contributed by Irit Katriel in gh-102192@footnote{https://github.com/python/cpython/issues/102192}.)

@item 
Using @ref{569,,PyType_FromSpec()}, @ref{56a,,PyType_FromSpecWithBases()}
or @ref{53c,,PyType_FromModuleAndSpec()} to create a class whose metaclass
overrides @ref{56b,,tp_new} is deprecated.
Call the metaclass instead.
@end itemize

@c Add deprecations above alphabetically, not here at the end.

@menu
* Pending Removal in Python 3.14: Pending Removal in Python 3 14<4>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<4>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<4>. 

@end menu

@node Pending Removal in Python 3 14<4>,Pending Removal in Python 3 15<4>,,Obsolescence<2>
@anchor{whatsnew/3 12 id7}@anchor{582}
@subsubsection Pending Removal in Python 3.14



@itemize *

@item 
The @code{ma_version_tag} field in @ref{3b8,,PyDictObject} for extension modules
(
@geindex Python Enhancement Proposals; PEP 699
PEP 699@footnote{https://peps.python.org/pep-0699/}; gh-101193@footnote{https://github.com/python/cpython/issues/101193}).

@item 
Creating @ref{3b9,,immutable types} with mutable
bases (gh-95388@footnote{https://github.com/python/cpython/issues/95388}).

@item 
Functions to configure Python's initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{3ba,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{3ba,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{3bb,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{3b2,,PyConfig.home} instead.
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{3bd,,Py_DebugFlag}:
Use @ref{3be,,PyConfig.parser_debug} instead.

@item 
@ref{3bf,,Py_VerboseFlag}:
Use @ref{3c0,,PyConfig.verbose} instead.

@item 
@ref{3c1,,Py_QuietFlag}:
Use @ref{3c2,,PyConfig.quiet} instead.

@item 
@ref{3c3,,Py_InteractiveFlag}:
Use @ref{3c4,,PyConfig.interactive} instead.

@item 
@ref{3c5,,Py_InspectFlag}:
Use @ref{3c6,,PyConfig.inspect} instead.

@item 
@ref{3c7,,Py_OptimizeFlag}:
Use @ref{3c8,,PyConfig.optimization_level} instead.

@item 
@ref{3c9,,Py_NoSiteFlag}:
Use @ref{3ca,,PyConfig.site_import} instead.

@item 
@ref{3cb,,Py_BytesWarningFlag}:
Use @ref{3cc,,PyConfig.bytes_warning} instead.

@item 
@ref{3cd,,Py_FrozenFlag}:
Use @ref{3ce,,PyConfig.pathconfig_warnings} instead.

@item 
@ref{3cf,,Py_IgnoreEnvironmentFlag}:
Use @ref{3d0,,PyConfig.use_environment} instead.

@item 
@ref{3d1,,Py_DontWriteBytecodeFlag}:
Use @ref{3d2,,PyConfig.write_bytecode} instead.

@item 
@ref{3d3,,Py_NoUserSiteDirectory}:
Use @ref{3d4,,PyConfig.user_site_directory} instead.

@item 
@ref{3d5,,Py_UnbufferedStdioFlag}:
Use @ref{3d6,,PyConfig.buffered_stdio} instead.

@item 
@ref{3d7,,Py_HashRandomizationFlag}:
Use @ref{3d8,,PyConfig.use_hash_seed}
and @ref{3d9,,PyConfig.hash_seed} instead.

@item 
@ref{3da,,Py_IsolatedFlag}:
Use @ref{3db,,PyConfig.isolated} instead.

@item 
@ref{3dc,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{3dd,,PyPreConfig.legacy_windows_fs_encoding} instead.

@item 
@ref{3de,,Py_LegacyWindowsStdioFlag}:
Use @ref{39b,,PyConfig.legacy_windows_stdio} instead.

@item 
@code{Py_FileSystemDefaultEncoding}:
Use @ref{3df,,PyConfig.filesystem_encoding} instead.

@item 
@code{Py_HasFileSystemDefaultEncoding}:
Use @ref{3df,,PyConfig.filesystem_encoding} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{3e0,,PyConfig.filesystem_errors} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{3e1,,PyPreConfig.utf8_mode} instead.
(see @ref{3e2,,Py_PreInitialize()})
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.
@end itemize

@node Pending Removal in Python 3 15<4>,Pending Removal in Future Versions<4>,Pending Removal in Python 3 14<4>,Obsolescence<2>
@anchor{whatsnew/3 12 id8}@anchor{583}
@subsubsection Pending Removal in Python 3.15



@itemize *

@item 
The bundled copy of @code{libmpdecimal}.

@item 
The @ref{3b4,,PyImport_ImportModuleNoBlock()}:
Use @ref{3b5,,PyImport_ImportModule()} instead.

@item 
@ref{36f,,PyWeakref_GetObject()} and @ref{3b6,,PyWeakref_GET_OBJECT()}:
Use @ref{36e,,PyWeakref_GetRef()} instead.

@item 
@ref{3e4,,Py_UNICODE} type and the @code{Py_UNICODE_WIDE} macro:
Use @code{wchar_t} instead.

@item 
Python initialization functions:


@itemize *

@item 
@ref{3a6,,PySys_ResetWarnOptions()}:
Clear @ref{3a7,,sys.warnoptions} and @code{warnings.filters} instead.

@item 
@ref{3a8,,Py_GetExecPrefix()}:
Get @ref{3e5,,sys.base_exec_prefix} and @ref{3a9,,sys.exec_prefix} instead.

@item 
@ref{3aa,,Py_GetPath()}:
Get @ref{3ab,,sys.path} instead.

@item 
@ref{3ac,,Py_GetPrefix()}:
Get @ref{3e6,,sys.base_prefix} and @ref{3ad,,sys.prefix} instead.

@item 
@ref{3ae,,Py_GetProgramFullPath()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b0,,Py_GetProgramName()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b1,,Py_GetPythonHome()}:
Get @ref{3b2,,PyConfig.home}
or the 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment variable instead.
@end itemize
@end itemize

@node Pending Removal in Future Versions<4>,,Pending Removal in Python 3 15<4>,Obsolescence<2>
@anchor{whatsnew/3 12 id9}@anchor{584}
@subsubsection Pending Removal in Future Versions


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


@itemize *

@item 
@ref{3e8,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{3e9,,PyErr_Fetch()}:
Use @ref{3ea,,PyErr_GetRaisedException()} instead.

@item 
@ref{3eb,,PyErr_NormalizeException()}:
Use @ref{3ea,,PyErr_GetRaisedException()} instead.

@item 
@ref{3ec,,PyErr_Restore()}:
Use @ref{3ed,,PyErr_SetRaisedException()} instead.

@item 
@ref{3ee,,PyModule_GetFilename()}:
Use @ref{3ef,,PyModule_GetFilenameObject()} instead.

@item 
@ref{3f0,,PyOS_AfterFork()}:
Use @ref{3f1,,PyOS_AfterFork_Child()} instead.

@item 
@ref{3f2,,PySlice_GetIndicesEx()}:
Use @ref{3f3,,PySlice_Unpack()} and @ref{3f4,,PySlice_AdjustIndices()} instead.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3f5,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3f5,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3f6,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3f6,,PyCodec_Encode()} instead.

@item 
@ref{3f7,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{3f8,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{3f9,,PyObject_Hash()} instead.

@item 
@code{PyDictObject.ma_version_tag} member.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{3fa,,PyThread_create_key()}:
Use @ref{3fb,,PyThread_tss_alloc()} instead.

@item 
@ref{3fc,,PyThread_delete_key()}:
Use @ref{3fd,,PyThread_tss_free()} instead.

@item 
@ref{3fe,,PyThread_set_key_value()}:
Use @ref{3ff,,PyThread_tss_set()} instead.

@item 
@ref{400,,PyThread_get_key_value()}:
Use @ref{401,,PyThread_tss_get()} instead.

@item 
@ref{402,,PyThread_delete_key_value()}:
Use @ref{403,,PyThread_tss_delete()} instead.

@item 
@ref{404,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@node Retraits<2>,,Obsolescence<2>,Changements à l'API C<2>
@anchor{whatsnew/3 12 id10}@anchor{585}
@subsubsection Retraits



@itemize *

@item 
Remove the @code{token.h} header file. There was never any public tokenizer C
API. The @code{token.h} header file was only designed to be used by Python
internals.
(Contributed by Victor Stinner in gh-92651@footnote{https://github.com/python/cpython/issues/92651}.)

@item 
Legacy Unicode APIs have been removed. See 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/} for detail.


@itemize *

@item 
@code{PyUnicode_WCHAR_KIND}

@item 
@code{PyUnicode_AS_UNICODE()}

@item 
@code{PyUnicode_AsUnicode()}

@item 
@code{PyUnicode_AsUnicodeAndSize()}

@item 
@code{PyUnicode_AS_DATA()}

@item 
@code{PyUnicode_FromUnicode()}

@item 
@code{PyUnicode_GET_SIZE()}

@item 
@code{PyUnicode_GetSize()}

@item 
@code{PyUnicode_GET_DATA_SIZE()}
@end itemize

@item 
Remove the @code{PyUnicode_InternImmortal()} function macro.
(Contributed by Victor Stinner in gh-85858@footnote{https://github.com/python/cpython/issues/85858}.)
@end itemize

@node Les nouveautés de Python 3 11,Les nouveautés de Python 3 10,What's New In Python 3 12,Nouveautés de Python
@anchor{whatsnew/3 11 doc}@anchor{586}@anchor{whatsnew/3 11 what-s-new-in-python-3-11}@anchor{587}
@section Les nouveautés de Python 3.11


@*Éditeur: 
`Pablo Galindo Salgado'


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Mercurial log
@c when researching a change.

This article explains the new features in Python 3.11, compared to 3.10.
Python 3.11 was released on October 24, 2022.
For full details, see the @ref{13b,,changelog}.

@menu
* Résumé – Points forts de la publication:: 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<5>. 
* Nouvelles fonctionnalités reliées aux indications de types: Nouvelles fonctionnalités reliées aux indications de types<2>. 
* Autres changements au langage: Autres changements au langage<3>. 
* Autres changements à l'implémentation de CPython:: 
* Nouveaux modules: Nouveaux modules<3>. 
* Modules améliorés: Modules améliorés<3>. 
* Optimisations: Optimisations<3>. 
* Faster CPython:: 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<2>. 
* Obsolescence: Obsolescence<3>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12. 
* Retraits: Retraits<3>. 
* Portage vers Python 3.11: Portage vers Python 3 11. 
* Changements à la compilation: Changements à la compilation<3>. 
* Changements à l'API C: Changements à l'API C<3>. 
* Notable changes in 3.11.4: Notable changes in 3 11 4. 
* Notable changes in 3.11.5: Notable changes in 3 11 5. 

@end menu

@node Résumé – Points forts de la publication,Nouvelles fonctionnalités<5>,,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 summary-release-highlights}@anchor{588}@anchor{whatsnew/3 11 whatsnew311-summary}@anchor{589}
@subsection Résumé – Points forts de la publication


@c This section singles out the most important changes in Python 3.11.
@c Brevity is key.


@itemize *

@item 
Python 3.11 est entre 10 et 60 % plus rapide que Python 3.10. En moyenne, nous avons mesuré une multiplication de la vitesse par 1,25 sur la suite de benchmarks standards. Voir les détails sur @ref{58a,,Faster CPython}.
@end itemize

@c PEP-sized items next.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@ref{58b,,PEP 654 ; Groupes d'exception et except*}
@end itemize

Nouvelles fonctionnalités natives :


@itemize *

@item 
@ref{58c,,PEP 678; Exceptions can be enriched with notes}
@end itemize

Nouveaux modules de bibliothèque standard :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 680
PEP 680@footnote{https://peps.python.org/pep-0680/}: @ref{fb,,tomllib} —
Support for parsing TOML@footnote{https://toml.io/} in the Standard Library
@end itemize

Améliorations de l'interpréteur :


@itemize *

@item 
@ref{58d,,PEP 657 ; amélioration de l'emplacement des erreurs dans les traces d'appels}

@item 
New @ref{58e,,-P} command line option and 
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} environment
variable to @ref{590,,disable automatically prepending potentially unsafe paths} to @ref{3ab,,sys.path}
@end itemize

Nouvelles fonctionnalités de typage :


@itemize *

@item 
@ref{591,,PEP 646; Variadic generics}

@item 
@ref{592,,PEP 655; Marking individual TypedDict items as required or not-required}

@item 
@ref{593,,PEP 673; Self type}

@item 
@ref{594,,PEP 675; Arbitrary literal string type}

@item 
@ref{595,,PEP 681; Data class transforms}
@end itemize

Important deprecations, removals and restrictions:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} : @ref{596,,De nombreux anciens modules de la bibliothèque standard sontdevenus obsolètes} et seront supprimés dans la version 3.13

@item 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/} : @ref{597,,les API d'encodage Py_UNICODE ont été supprimées}

@item 
@geindex Python Enhancement Proposals; PEP 670
PEP 670@footnote{https://peps.python.org/pep-0670/}:
@ref{598,,Macros converted to static inline functions}
@end itemize

@node Nouvelles fonctionnalités<5>,Nouvelles fonctionnalités reliées aux indications de types<2>,Résumé – Points forts de la publication,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 new-features}@anchor{599}@anchor{whatsnew/3 11 whatsnew311-features}@anchor{59a}
@subsection Nouvelles fonctionnalités


@menu
* PEP 657 ; amélioration de l'emplacement des erreurs dans les traces d'appels: PEP 657 amélioration de l'emplacement des erreurs dans les traces d'appels. 
* PEP 654 ; Groupes d'exception et except*: PEP 654 Groupes d'exception et except*. 
* PEP 678; Exceptions can be enriched with notes: PEP 678 Exceptions can be enriched with notes. 
* Améliorations du lanceur Windows py.exe: Améliorations du lanceur Windows py exe. 

@end menu

@node PEP 657 amélioration de l'emplacement des erreurs dans les traces d'appels,PEP 654 Groupes d'exception et except*,,Nouvelles fonctionnalités<5>
@anchor{whatsnew/3 11 pep-657-fine-grained-error-locations-in-tracebacks}@anchor{59b}@anchor{whatsnew/3 11 whatsnew311-pep657}@anchor{58d}
@subsubsection PEP 657 : amélioration de l'emplacement des erreurs dans les traces d'appels


When printing tracebacks, the interpreter will now point to the exact expression
that caused the error, instead of just the line. For example:

@example
Traceback (most recent call last):
  File "distance.py", line 11, in <module>
    print(manhattan_distance(p1, p2))
          ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "distance.py", line 6, in manhattan_distance
    return abs(point_1.x - point_2.x) + abs(point_1.y - point_2.y)
                           ^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'x'
@end example

Previous versions of the interpreter would point to just the line, making it
ambiguous which object was @code{None}. These enhanced errors can also be helpful
when dealing with deeply nested @ref{253,,dict} objects and multiple function calls:

@example
Traceback (most recent call last):
  File "query.py", line 37, in <module>
    magic_arithmetic('foo')
  File "query.py", line 18, in magic_arithmetic
    return add_counts(x) / 25
           ^^^^^^^^^^^^^
  File "query.py", line 24, in add_counts
    return 25 + query_user(user1) + query_user(user2)
                ^^^^^^^^^^^^^^^^^
  File "query.py", line 32, in query_user
    return 1 + query_count(db, response['a']['b']['c']['user'], retry=True)
                               ~~~~~~~~~~~~~~~~~~^^^^^
TypeError: 'NoneType' object is not subscriptable
@end example

As well as complex arithmetic expressions:

@example
Traceback (most recent call last):
  File "calculation.py", line 54, in <module>
    result = (x / y / z) * (a / b / c)
              ~~~~~~^~~
ZeroDivisionError: division by zero
@end example

Additionally, the information used by the enhanced traceback feature
is made available via a general API, that can be used to correlate
@ref{185,,bytecode} @ref{59c,,instructions} with source code location.
This information can be retrieved using:


@itemize -

@item 
la méthode @ref{59d,,codeobject.co_positions()} en Python ;

@item 
The @ref{59e,,PyCode_Addr2Location()} function in the C API.
@end itemize

Voir la 
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/} pour plus de détails (contribution de `Pablo Galindo', `Batuhan Taskaya' et `Ammar Askar' dans bpo-43950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43950}).

@cartouche
@quotation Note 
This feature requires storing column positions in @ref{59f,,Objets code},
which may result in a small increase in interpreter memory usage
and disk usage for compiled Python files.
To avoid storing the extra information
and deactivate printing the extra traceback information,
use the @ref{175,,-X no_debug_ranges} command line option
or the 
@geindex PYTHONNODEBUGRANGES
@geindex variable d'environnement; PYTHONNODEBUGRANGES
@ref{5a0,,PYTHONNODEBUGRANGES} environment variable.
@end quotation
@end cartouche

@node PEP 654 Groupes d'exception et except*,PEP 678 Exceptions can be enriched with notes,PEP 657 amélioration de l'emplacement des erreurs dans les traces d'appels,Nouvelles fonctionnalités<5>
@anchor{whatsnew/3 11 pep-654-exception-groups-and-except}@anchor{5a1}@anchor{whatsnew/3 11 whatsnew311-pep654}@anchor{58b}
@subsubsection PEP 654 : Groupes d'exception et @code{except*}


@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/} introduces language features that enable a program
to raise and handle multiple unrelated exceptions simultaneously.
The builtin types @ref{1b4,,ExceptionGroup} and @ref{25c,,BaseExceptionGroup}
make it possible to group exceptions and raise them together,
and the new @ref{5a2,,except*} syntax generalizes
@ref{189,,except} to match subgroups of exception groups.

Voir 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/} pour plus de détails.

(Contributed by Irit Katriel in bpo-45292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45292}. PEP written by
Irit Katriel, Yury Selivanov and Guido van Rossum.)

@node PEP 678 Exceptions can be enriched with notes,Améliorations du lanceur Windows py exe,PEP 654 Groupes d'exception et except*,Nouvelles fonctionnalités<5>
@anchor{whatsnew/3 11 pep-678-exceptions-can-be-enriched-with-notes}@anchor{5a3}@anchor{whatsnew/3 11 whatsnew311-pep678}@anchor{58c}
@subsubsection PEP 678: Exceptions can be enriched with notes


The @ref{5a4,,add_note()} method is added to @ref{5a5,,BaseException}.
It can be used to enrich exceptions with context information
that is not available at the time when the exception is raised.
The added notes appear in the default traceback.

Voir 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/} pour plus de détails.

(Contributed by Irit Katriel in bpo-45607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45607}.
PEP written by Zac Hatfield-Dodds.)

@node Améliorations du lanceur Windows py exe,,PEP 678 Exceptions can be enriched with notes,Nouvelles fonctionnalités<5>
@anchor{whatsnew/3 11 whatsnew311-windows-launcher}@anchor{5a6}@anchor{whatsnew/3 11 windows-py-exe-launcher-improvements}@anchor{5a7}
@subsubsection Améliorations du lanceur Windows @code{py.exe}


The copy of the @ref{5a8,,Lanceur Python pour Windows} included with Python 3.11 has been significantly
updated. It now supports company/tag syntax as defined in 
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} using the
@code{-V:@var{<company>}/@var{<tag>}} argument instead of the limited @code{-@var{<major>}.@var{<minor>}}.
This allows launching distributions other than @code{PythonCore},
the one hosted on python.org@footnote{https://www.python.org}.

When using @code{-V:} selectors, either company or tag can be omitted, but all
installs will be searched. For example, @code{-V:OtherPython/} will select the
"best" tag registered for @code{OtherPython}, while @code{-V:3.11} or @code{-V:/3.11}
will select the "best" distribution with tag @code{3.11}.

When using the legacy @code{-@var{<major>}}, @code{-@var{<major>}.@var{<minor>}},
@code{-@var{<major>}-@var{<bitness>}} or @code{-@var{<major>}.@var{<minor>}-@var{<bitness>}} arguments,
all existing behaviour should be preserved from past versions,
and only releases from @code{PythonCore} will be selected.
However, the @code{-64} suffix now implies "not 32-bit" (not necessarily x86-64),
as there are multiple supported 64-bit platforms.
32-bit runtimes are detected by checking the runtime's tag for a @code{-32} suffix.
All releases of Python since 3.5 have included this in their 32-bit builds.
@anchor{whatsnew/3 11 new-feat-related-type-hints-311}@anchor{5a9}
@node Nouvelles fonctionnalités reliées aux indications de types<2>,Autres changements au langage<3>,Nouvelles fonctionnalités<5>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 new-features-related-to-type-hints}@anchor{5aa}@anchor{whatsnew/3 11 whatsnew311-typing-features}@anchor{5ab}
@subsection Nouvelles fonctionnalités reliées aux indications de types


Cette section couvre les changements majeurs touchant le module @ref{103,,typing} et les indications de types de style 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}.

@menu
* PEP 646; Variadic generics: PEP 646 Variadic generics. 
* PEP 655; Marking individual TypedDict items as required or not-required: PEP 655 Marking individual TypedDict items as required or not-required. 
* PEP 673; Self type: PEP 673 Self type. 
* PEP 675; Arbitrary literal string type: PEP 675 Arbitrary literal string type. 
* PEP 681; Data class transforms: PEP 681 Data class transforms. 
* PEP 563 may not be the future:: 

@end menu

@node PEP 646 Variadic generics,PEP 655 Marking individual TypedDict items as required or not-required,,Nouvelles fonctionnalités reliées aux indications de types<2>
@anchor{whatsnew/3 11 pep-646-variadic-generics}@anchor{5ac}@anchor{whatsnew/3 11 whatsnew311-pep646}@anchor{591}
@subsubsection PEP 646: Variadic generics


@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} previously introduced @ref{15c,,TypeVar}, enabling creation
of generics parameterised with a single type. 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/} adds
@ref{15e,,TypeVarTuple}, enabling parameterisation
with an `arbitrary' number of types. In other words,
a @ref{15e,,TypeVarTuple} is a `variadic' type variable,
enabling `variadic' generics.

This enables a wide variety of use cases.
In particular, it allows the type of array-like structures
in numerical computing libraries such as NumPy and TensorFlow to be
parameterised with the array `shape'. Static type checkers will now
be able to catch shape-related bugs in code that uses these libraries.

Voir 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/} pour plus de détails.

(Contributed by Matthew Rahtz in bpo-43224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43224}, with contributions by
Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew
Rahtz, Pradeep Kumar Srinivasan, and Vincent Siles.)

@node PEP 655 Marking individual TypedDict items as required or not-required,PEP 673 Self type,PEP 646 Variadic generics,Nouvelles fonctionnalités reliées aux indications de types<2>
@anchor{whatsnew/3 11 pep-655-marking-individual-typeddict-items-as-required-or-not-required}@anchor{5ad}@anchor{whatsnew/3 11 whatsnew311-pep655}@anchor{592}
@subsubsection PEP 655: Marking individual @code{TypedDict} items as required or not-required


@ref{5ae,,Required} and @ref{5af,,NotRequired} provide a
straightforward way to mark whether individual items in a
@ref{161,,TypedDict} must be present. Previously, this was only possible
using inheritance.

All fields are still required by default,
unless the `total' parameter is set to @code{False},
in which case all fields are still not-required by default.
For example, the following specifies a @code{TypedDict}
with one required and one not-required key:

@example
class Movie(TypedDict):
   title: str
   year: NotRequired[int]

m1: Movie = @{"title": "Black Panther", "year": 2018@}  # OK
m2: Movie = @{"title": "Star Wars"@}  # OK (year is not required)
m3: Movie = @{"year": 2022@}  # ERROR (missing required field title)
@end example

La définition suivante est équivalente :

@example
class Movie(TypedDict, total=False):
   title: Required[str]
   year: int
@end example

Voir 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/} pour plus de détails.

(Contributed by David Foster and Jelle Zijlstra in bpo-47087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47087}. PEP
written by David Foster.)

@node PEP 673 Self type,PEP 675 Arbitrary literal string type,PEP 655 Marking individual TypedDict items as required or not-required,Nouvelles fonctionnalités reliées aux indications de types<2>
@anchor{whatsnew/3 11 pep-673-self-type}@anchor{5b0}@anchor{whatsnew/3 11 whatsnew311-pep673}@anchor{593}
@subsubsection PEP 673: @code{Self} type


The new @ref{5b1,,Self} annotation provides a simple and intuitive
way to annotate methods that return an instance of their class. This
behaves the same as the @ref{15c,,TypeVar}-based approach
@geindex Python Enhancement Proposals; PEP 484#annotating-instance-and-class-methods
specified in PEP 484@footnote{https://peps.python.org/pep-0484/#annotating-instance-and-class-methods},
but is more concise and easier to follow.

Common use cases include alternative constructors provided as
@ref{165,,classmethod}s,
and @ref{5b2,,__enter__()} methods that return @code{self}:

@example
class MyLock:
    def __enter__(self) -> Self:
        self.lock()
        return self

    ...

class MyInt:
    @@classmethod
    def fromhex(cls, s: str) -> Self:
        return cls(int(s, 16))

    ...
@end example

@ref{5b1,,Self} can also be used to annotate method parameters
or attributes of the same type as their enclosing class.

Voir 
@geindex Python Enhancement Proposals; PEP 673
PEP 673@footnote{https://peps.python.org/pep-0673/} pour plus de détails.

(Contributed by James Hilton-Balfe in bpo-46534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46534}. PEP written by
Pradeep Kumar Srinivasan and James Hilton-Balfe.)

@node PEP 675 Arbitrary literal string type,PEP 681 Data class transforms,PEP 673 Self type,Nouvelles fonctionnalités reliées aux indications de types<2>
@anchor{whatsnew/3 11 pep-675-arbitrary-literal-string-type}@anchor{5b3}@anchor{whatsnew/3 11 whatsnew311-pep675}@anchor{594}
@subsubsection PEP 675: Arbitrary literal string type


The new @ref{5b4,,LiteralString} annotation may be used to indicate
that a function parameter can be of any literal string type. This allows
a function to accept arbitrary literal string types, as well as strings
created from other literal strings. Type checkers can then
enforce that sensitive functions, such as those that execute SQL
statements or shell commands, are called only with static arguments,
providing protection against injection attacks.

Par exemple, une fonction de requête SQL pourrait être annotée de cette façon :

@example
def run_query(sql: LiteralString) -> ...
    ...

def caller(
    arbitrary_string: str,
    query_string: LiteralString,
    table_name: LiteralString,
) -> None:
    run_query("SELECT * FROM students")       # ok
    run_query(query_string)                   # ok
    run_query("SELECT * FROM " + table_name)  # ok
    run_query(arbitrary_string)               # type checker error
    run_query(                                # type checker error
        f"SELECT * FROM students WHERE name = @{arbitrary_string@}"
    )
@end example

Voir 
@geindex Python Enhancement Proposals; PEP 675
PEP 675@footnote{https://peps.python.org/pep-0675/} pour plus de détails.

(Contributed by Jelle Zijlstra in bpo-47088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47088}. PEP written by Pradeep
Kumar Srinivasan and Graham Bleaney.)

@node PEP 681 Data class transforms,PEP 563 may not be the future,PEP 675 Arbitrary literal string type,Nouvelles fonctionnalités reliées aux indications de types<2>
@anchor{whatsnew/3 11 pep-681-data-class-transforms}@anchor{5b5}@anchor{whatsnew/3 11 whatsnew311-pep681}@anchor{595}
@subsubsection PEP 681: Data class transforms


@ref{4bd,,dataclass_transform} may be used to
decorate a class, metaclass, or a function that is itself a decorator.
The presence of @code{@@dataclass_transform()} tells a static type checker that the
decorated object performs runtime "magic" that transforms a class,
giving it @ref{1c6,,dataclass}-like behaviors.

Par exemple :

@example
# The create_model decorator is defined by a library.
@@typing.dataclass_transform()
def create_model(cls: Type[T]) -> Type[T]:
    cls.__init__ = ...
    cls.__eq__ = ...
    cls.__ne__ = ...
    return cls

# The create_model decorator can now be used to create new model classes:
@@create_model
class CustomerModel:
    id: int
    name: str

c = CustomerModel(id=327, name="Eric Idle")
@end example

Voir 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/} pour plus de détails.

(Contributed by Jelle Zijlstra in gh-91860@footnote{https://github.com/python/cpython/issues/91860}. PEP written by
Erik De Bonte and Eric Traut.)

@node PEP 563 may not be the future,,PEP 681 Data class transforms,Nouvelles fonctionnalités reliées aux indications de types<2>
@anchor{whatsnew/3 11 pep-563-may-not-be-the-future}@anchor{5b6}@anchor{whatsnew/3 11 whatsnew311-pep563-deferred}@anchor{5b7}
@subsubsection PEP 563 may not be the future


@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/} Postponed Evaluation of Annotations
(the @code{from __future__ import annotations} @ref{187,,future statement})
that was originally planned for release in Python 3.10
has been put on hold indefinitely.
See this message from the Steering Council@footnote{https://mail.python.org/archives/list/python-dev@@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/}
for more information.

@node Autres changements au langage<3>,Autres changements à l'implémentation de CPython,Nouvelles fonctionnalités reliées aux indications de types<2>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 other-language-changes}@anchor{5b8}@anchor{whatsnew/3 11 whatsnew311-other-lang-changes}@anchor{5b9}
@subsection Autres changements au langage



@itemize *

@item 
Starred unpacking expressions can now be used in @ref{2e6,,for} statements.
(See bpo-46725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46725} for more details.)

@item 
Asynchronous @ref{5ba,,comprehensions} are now allowed
inside comprehensions in @ref{5bb,,asynchronous functions}.
Outer comprehensions implicitly become asynchronous in this case.
(Contributed by Serhiy Storchaka in bpo-33346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33346}.)

@item 
A @ref{522,,TypeError} is now raised instead of an @ref{343,,AttributeError} in
@ref{5bc,,with} statements and @ref{5bd,,contextlib.ExitStack.enter_context()}
for objects that do not support the @ref{5be,,context manager} protocol,
and in @ref{5bf,,async with} statements and
@ref{5c0,,contextlib.AsyncExitStack.enter_async_context()}
for objects not supporting the @ref{5c1,,asynchronous context manager} protocol.
(Contributed by Serhiy Storchaka in bpo-12022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12022} and bpo-44471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44471}.)

@item 
Added @ref{5c2,,object.__getstate__()}, which provides the default
implementation of the @code{__getstate__()} method. @ref{25,,copy}ing
and @ref{a5,,pickle}ing instances of subclasses of builtin types
@ref{528,,bytearray}, @ref{5c3,,set}, @ref{5c4,,frozenset},
@ref{5c5,,collections.OrderedDict}, @ref{5c6,,collections.deque},
@ref{5c7,,weakref.WeakSet}, and @ref{5c8,,datetime.tzinfo} now copies and
pickles instance attributes implemented as @ref{5c9,,slots}.
This change has an unintended side effect: It trips up a small minority
of existing Python projects not expecting @ref{5c2,,object.__getstate__()} to
exist. See the later comments on gh-70766@footnote{https://github.com/python/cpython/issues/70766} for discussions of what
workarounds such code may need.
(Contributed by Serhiy Storchaka in bpo-26579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26579}.)
@end itemize
@anchor{whatsnew/3 11 whatsnew311-pythonsafepath}@anchor{590}

@itemize *

@item 
Added a @ref{58e,,-P} command line option
and a 
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} environment variable,
which disable the automatic prepending to @ref{3ab,,sys.path}
of the script's directory when running a script,
or the current directory when using @ref{5ca,,-c} and @ref{5cb,,-m}.
This ensures only stdlib and installed modules
are picked up by @ref{5cc,,import},
and avoids unintentionally or maliciously shadowing modules
with those in a local (and typically user-writable) directory.
(Contributed by Victor Stinner in gh-57684@footnote{https://github.com/python/cpython/issues/57684}.)

@item 
A @code{"z"} option was added to the @ref{1e5,,Mini-langage de spécification de format} that
coerces negative to positive zero after rounding to the format precision.
See 
@geindex Python Enhancement Proposals; PEP 682
PEP 682@footnote{https://peps.python.org/pep-0682/} for more details.
(Contributed by John Belmonte in gh-90153@footnote{https://github.com/python/cpython/issues/90153}.)

@item 
Bytes are no longer accepted on @ref{3ab,,sys.path}.  Support broke sometime
between Python 3.2 and 3.6, with no one noticing until after Python 3.10.0
was released. In addition, bringing back support would be problematic due to
interactions between @ref{5cd,,-b} and @ref{5ce,,sys.path_importer_cache} when
there is a mixture of @ref{435,,str} and @ref{1bd,,bytes} keys.
(Contributed by Thomas Grainger in gh-91181@footnote{https://github.com/python/cpython/issues/91181}.)
@end itemize

@node Autres changements à l'implémentation de CPython,Nouveaux modules<3>,Autres changements au langage<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 other-cpython-implementation-changes}@anchor{5cf}@anchor{whatsnew/3 11 whatsnew311-other-implementation-changes}@anchor{5d0}
@subsection Autres changements à l'implémentation de CPython



@itemize *

@item 
The special methods @ref{5d1,,__complex__()} for @ref{2ec,,complex}
and @ref{5d2,,__bytes__()} for @ref{1bd,,bytes} are implemented to support
the @ref{5d3,,typing.SupportsComplex} and @ref{5d4,,typing.SupportsBytes} protocols.
(Contributed by Mark Dickinson and Donghee Na in bpo-24234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24234}.)

@item 
@code{siphash13} is added as a new internal hashing algorithm.
It has similar security properties as @code{siphash24},
but it is slightly faster for long inputs.
@ref{435,,str}, @ref{1bd,,bytes}, and some other types
now use it as the default algorithm for @ref{5d5,,hash()}.
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} @ref{5d6,,hash-based .pyc files}
now use @code{siphash13} too.
(Contributed by Inada Naoki in bpo-29410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29410}.)

@item 
When an active exception is re-raised by a @ref{5d7,,raise} statement with no parameters,
the traceback attached to this exception is now always @code{sys.exc_info()[1].__traceback__}.
This means that changes made to the traceback in the current @ref{189,,except} clause are
reflected in the re-raised exception.
(Contributed by Irit Katriel in bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}.)

@item 
The interpreter state's representation of handled exceptions
(aka @code{exc_info} or @code{_PyErr_StackItem})
now only has the @code{exc_value} field; @code{exc_type} and @code{exc_traceback}
have been removed, as they can be derived from @code{exc_value}.
(Contributed by Irit Katriel in bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}.)

@item 
A new @ref{5d8,,command line option}, @code{AppendPath},
has been added for the Windows installer.
It behaves similarly to @code{PrependPath},
but appends the install and scripts directories instead of prepending them.
(Contributed by Bastian Neuburger in bpo-44934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44934}.)

@item 
The @ref{5d9,,PyConfig.module_search_paths_set} field must now be set to @code{1} for
initialization to use @ref{399,,PyConfig.module_search_paths} to initialize
@ref{3ab,,sys.path}. Otherwise, initialization will recalculate the path and replace
any values added to @code{module_search_paths}.

@item 
The output of the @ref{5da,,--help} option now fits in 50 lines/80 columns.
Information about @ref{5db,,Python environment variables}
and @ref{175,,-X} options is now available using the respective
@ref{5dc,,--help-env} and @ref{5dd,,--help-xoptions} flags,
and with the new @ref{5de,,--help-all}.
(Contributed by Éric Araujo in bpo-46142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46142}.)

@item 
Converting between @ref{254,,int} and @ref{435,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{1ff,,ValueError} if the number of digits in string form is
above a limit to avoid potential denial of service attacks due to the
algorithmic complexity. This is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.
This limit can be configured or disabled by environment variable, command
line flag, or @ref{d8,,sys} APIs. See the @ref{5df,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.
@end itemize

@node Nouveaux modules<3>,Modules améliorés<3>,Autres changements à l'implémentation de CPython,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 new-modules}@anchor{5e0}@anchor{whatsnew/3 11 whatsnew311-new-modules}@anchor{5e1}
@subsection Nouveaux modules



@itemize *

@item 
@ref{fb,,tomllib}: For parsing TOML@footnote{https://toml.io/}.
See 
@geindex Python Enhancement Proposals; PEP 680
PEP 680@footnote{https://peps.python.org/pep-0680/} for more details.
(Contributed by Taneli Hukkinen in bpo-40059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40059}.)

@item 
@ref{11b,,wsgiref.types}:
@geindex Python Enhancement Proposals; PEP 3333
WSGI@footnote{https://peps.python.org/pep-3333/}-specific types for static type checking.
(Contributed by Sebastian Rittau in bpo-42012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42012}.)
@end itemize

@node Modules améliorés<3>,Optimisations<3>,Nouveaux modules<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 improved-modules}@anchor{5e2}@anchor{whatsnew/3 11 whatsnew311-improved-modules}@anchor{5e3}
@subsection Modules améliorés


@menu
* asyncio: asyncio<3>. 
* contextlib:: 
* dataclasses:: 
* datetime:: 
* enum: enum<3>. 
* fcntl:: 
* fractions: fractions<3>. 
* functools:: 
* gzip: gzip<2>. 
* hashlib: hashlib<2>. 
* IDLE et idlelib:: 
* inspect: inspect<2>. 
* locale: locale<3>. 
* logging:: 
* math: math<3>. 
* operator:: 
* os: os<3>. 
* pathlib: pathlib<4>. 
* re: re<3>. 
* shutils: shutils<3>. 
* socket:: 
* sqlite3: sqlite3<4>. 
* string:: 
* sys: sys<4>. 
* sysconfig:: 
* tempfile: tempfile<3>. 
* threading: threading<2>. 
* time: time<2>. 
* tkinter: tkinter<3>. 
* traceback: traceback<2>. 
* typing: typing<4>. 
* unicodedata: unicodedata<3>. 
* unittest: unittest<4>. 
* venv: venv<2>. 
* warnings: warnings<2>. 
* zipfile:: 

@end menu

@node asyncio<3>,contextlib,,Modules améliorés<3>
@anchor{whatsnew/3 11 asyncio}@anchor{5e4}@anchor{whatsnew/3 11 whatsnew311-asyncio}@anchor{5e5}
@subsubsection @code{asyncio}



@itemize *

@item 
Added the @ref{1b3,,TaskGroup} class,
an @ref{5e6,,asynchronous context manager}
holding a group of tasks that will wait for all of them upon exit.
For new code this is recommended over using
@ref{5e7,,create_task()} and @ref{5e8,,gather()} directly.
(Contributed by Yury Selivanov and others in gh-90908@footnote{https://github.com/python/cpython/issues/90908}.)

@item 
Added @ref{5e9,,timeout()}, an asynchronous context manager for
setting a timeout on asynchronous operations. For new code this is
recommended over using @ref{5ea,,wait_for()} directly.
(Contributed by Andrew Svetlov in gh-90927@footnote{https://github.com/python/cpython/issues/90927}.)

@item 
Added the @ref{5eb,,Runner} class, which exposes the machinery
used by @ref{466,,run()}.
(Contributed by Andrew Svetlov in gh-91218@footnote{https://github.com/python/cpython/issues/91218}.)

@item 
Added the @ref{5ec,,Barrier} class to the synchronization
primitives in the asyncio library, and the related
@ref{5ed,,BrokenBarrierError} exception.
(Contributed by Yves Duprat and Andrew Svetlov in gh-87518@footnote{https://github.com/python/cpython/issues/87518}.)

@item 
Added keyword argument `all_errors' to @ref{5ee,,asyncio.loop.create_connection()}
so that multiple connection errors can be raised as an @ref{1b4,,ExceptionGroup}.

@item 
Added the @ref{5ef,,asyncio.StreamWriter.start_tls()} method for
upgrading existing stream-based connections to TLS.
(Contributed by Ian Good in bpo-34975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34975}.)

@item 
Added raw datagram socket functions to the event loop:
@ref{5f0,,sock_sendto()},
@ref{5f1,,sock_recvfrom()} and
@ref{5f2,,sock_recvfrom_into()}.
These have implementations in @ref{5f3,,SelectorEventLoop} and
@ref{5f4,,ProactorEventLoop}.
(Contributed by Alex Grönholm in bpo-46805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46805}.)

@item 
Added @ref{1b8,,cancelling()} and
@ref{1b9,,uncancel()} methods to @ref{4c2,,Task}.
These are primarily intended for internal use,
notably by @ref{1b3,,TaskGroup}.
@end itemize

@node contextlib,dataclasses,asyncio<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 contextlib}@anchor{5f5}@anchor{whatsnew/3 11 whatsnew311-contextlib}@anchor{5f6}
@subsubsection contextlib



@itemize *

@item 
Added non parallel-safe @ref{5f7,,chdir()} context manager to change
the current working directory and then restore it on exit. Simple wrapper
around @ref{5f8,,chdir()}. (Contributed by Filipe Laíns in bpo-25625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25625})
@end itemize

@node dataclasses,datetime,contextlib,Modules améliorés<3>
@anchor{whatsnew/3 11 dataclasses}@anchor{5f9}@anchor{whatsnew/3 11 whatsnew311-dataclasses}@anchor{5fa}
@subsubsection @code{dataclasses}



@itemize *

@item 
Change field default mutability check, allowing only defaults which are
@ref{5fb,,hashable} instead of any object which is not an instance of
@ref{253,,dict}, @ref{5fc,,list} or @ref{5c3,,set}. (Contributed by Eric V. Smith in
bpo-44674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44674}.)
@end itemize

@node datetime,enum<3>,dataclasses,Modules améliorés<3>
@anchor{whatsnew/3 11 datetime}@anchor{5fd}@anchor{whatsnew/3 11 whatsnew311-datetime}@anchor{5fe}
@subsubsection `datetime'



@itemize *

@item 
Add @ref{4d8,,datetime.UTC}, a convenience alias for
@ref{5ff,,datetime.timezone.utc}. (Contributed by Kabir Kwatra in gh-91973@footnote{https://github.com/python/cpython/issues/91973}.)

@item 
@ref{600,,datetime.date.fromisoformat()}, @ref{601,,datetime.time.fromisoformat()} and
@ref{602,,datetime.datetime.fromisoformat()} can now be used to parse most ISO 8601
formats (barring only those that support fractional hours and minutes).
(Contributed by Paul Ganssle in gh-80010@footnote{https://github.com/python/cpython/issues/80010}.)
@end itemize

@node enum<3>,fcntl,datetime,Modules améliorés<3>
@anchor{whatsnew/3 11 enum}@anchor{603}@anchor{whatsnew/3 11 whatsnew311-enum}@anchor{604}
@subsubsection enum



@itemize *

@item 
Renamed @code{EnumMeta} to @ref{1e2,,EnumType}
(@code{EnumMeta} kept as an alias).

@item 
Added @ref{605,,StrEnum},
with members that can be used as (and must be) strings.

@item 
Added @ref{606,,ReprEnum},
which only modifies the @ref{607,,__repr__()} of members
while returning their literal values (rather than names)
for @ref{608,,__str__()} and @ref{609,,__format__()}
(used by @ref{435,,str()}, @ref{60a,,format()} and @ref{41f,,f-string}s).

@item 
Changed @ref{60b,,Enum.__format__()} (the default for
@ref{60a,,format()}, @ref{60c,,str.format()} and @ref{41f,,f-string}s) to always produce
the same result as @ref{60d,,Enum.__str__()}:  for enums inheriting from
@ref{606,,ReprEnum} it will be the member's value; for all other enums
it will be the enum and member name (e.g. @code{Color.RED}).

@item 
Added a new `boundary' class parameter to @ref{60e,,Flag} enums
and the @ref{60f,,FlagBoundary} enum with its options,
to control how to handle out-of-range flag values.

@item 
Added the @ref{610,,verify()} enum decorator
and the @ref{611,,EnumCheck} enum with its options,
to check enum classes against several specific constraints.

@item 
Added the @ref{612,,member()} and @ref{613,,nonmember()} decorators,
to ensure the decorated object is/is not converted to an enum member.

@item 
Added the @ref{614,,property()} decorator,
which works like @ref{192,,property()} except for enums.
Use this instead of @ref{615,,types.DynamicClassAttribute()}.

@item 
Added the @ref{616,,global_enum()} enum decorator,
which adjusts @ref{607,,__repr__()} and @ref{608,,__str__()}
to show values as members of their module rather than the enum class.
For example, @code{'re.ASCII'} for the @ref{617,,ASCII} member
of @ref{618,,re.RegexFlag} rather than @code{'RegexFlag.ASCII'}.

@item 
Enhanced @ref{60e,,Flag} to support
@ref{619,,len()}, iteration and @ref{2e8,,in}/@ref{61a,,not in} on its members.
For example, the following now works:
@code{len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)}

@item 
Changed @ref{61b,,Enum} and @ref{60e,,Flag}
so that members are now defined
before @ref{61c,,__init_subclass__()} is called;
@ref{61d,,dir()} now includes methods, etc., from mixed-in data types.

@item 
Changed @ref{60e,,Flag}
to only consider primary values (power of two) canonical
while composite values (@code{3}, @code{6}, @code{10}, etc.) are considered aliases;
inverted flags are coerced to their positive equivalent.
@end itemize

@node fcntl,fractions<3>,enum<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 fcntl}@anchor{61e}@anchor{whatsnew/3 11 whatsnew311-fcntl}@anchor{61f}
@subsubsection @code{fcntl}



@itemize *

@item 
On FreeBSD, the @code{F_DUP2FD} and @code{F_DUP2FD_CLOEXEC} flags respectively
are supported, the former equals to @code{dup2} usage while the latter set
the @code{FD_CLOEXEC} flag in addition.
@end itemize

@node fractions<3>,functools,fcntl,Modules améliorés<3>
@anchor{whatsnew/3 11 fractions}@anchor{620}@anchor{whatsnew/3 11 whatsnew311-fractions}@anchor{621}
@subsubsection @code{fractions}



@itemize *

@item 
Prise en charge de l'initialisation de @ref{1e4,,Fraction} à partir d'une chaîne suivant le style de la 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/} (contribution de `Sergey B Kirpichev' dans bpo-44258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44258}).

@item 
@ref{1e4,,Fraction} implémente maintenant la méthode @code{__int__}, ce qui permet au test @code{isinstance(ma_fraction, typing.SupportsInt)} de passer avec succès (contribution de `Mark Dickinson' dans bpo-44547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44547}).
@end itemize

@node functools,gzip<2>,fractions<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 functools}@anchor{622}@anchor{whatsnew/3 11 whatsnew311-functools}@anchor{623}
@subsubsection functools



@itemize *

@item 
@ref{624,,functools.singledispatch()} now supports @ref{625,,types.UnionType}
and @ref{626,,typing.Union} as annotations to the dispatch argument.:

@example
>>> from functools import singledispatch
>>> @@singledispatch
... def fun(arg, verbose=False):
...     if verbose:
...         print("Let me just say,", end=" ")
...     print(arg)
...
>>> @@fun.register
... def _(arg: int | float, verbose=False):
...     if verbose:
...         print("Strength in numbers, eh?", end=" ")
...     print(arg)
...
>>> from typing import Union
>>> @@fun.register
... def _(arg: Union[list, set], verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)
...
@end example

(Contributed by Yurii Karabas in bpo-46014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46014}.)
@end itemize

@node gzip<2>,hashlib<2>,functools,Modules améliorés<3>
@anchor{whatsnew/3 11 gzip}@anchor{627}@anchor{whatsnew/3 11 whatsnew311-gzip}@anchor{628}
@subsubsection gzip



@itemize *

@item 
The @ref{629,,gzip.compress()} function is now faster when used with the
`mtime=0' argument as it delegates the compression entirely to a single
@ref{62a,,zlib.compress()} operation. There is one side effect of this change: The
gzip file header contains an "OS" byte in its header. That was traditionally
always set to a value of 255 representing "unknown" by the @ref{66,,gzip}
module. Now, when using @ref{629,,compress()} with `mtime=0', it may be
set to a different value by the underlying zlib C library Python was linked
against.
(See gh-112346@footnote{https://github.com/python/cpython/issues/112346} for details on the side effect.)
@end itemize

@node hashlib<2>,IDLE et idlelib,gzip<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 hashlib}@anchor{62b}@anchor{whatsnew/3 11 whatsnew311-hashlib}@anchor{62c}
@subsubsection `hashlib'



@itemize *

@item 
@ref{62d,,hashlib.blake2b()} and @ref{62e,,hashlib.blake2s()} now prefer libb2@footnote{https://www.blake2.net/}
over Python's vendored copy.
(Contributed by Christian Heimes in bpo-47095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47095}.)

@item 
The internal @code{_sha3} module with SHA3 and SHAKE algorithms now uses
`tiny_sha3' instead of the `Keccak Code Package' to reduce code and binary
size. The @ref{67,,hashlib} module prefers optimized SHA3 and SHAKE
implementations from OpenSSL. The change affects only installations without
OpenSSL support.
(Contributed by Christian Heimes in bpo-47098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47098}.)

@item 
Add @ref{62f,,hashlib.file_digest()}, a helper function for efficient hashing
of files or file-like objects.
(Contributed by Christian Heimes in gh-89313@footnote{https://github.com/python/cpython/issues/89313}.)
@end itemize

@node IDLE et idlelib,inspect<2>,hashlib<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 idle-and-idlelib}@anchor{630}@anchor{whatsnew/3 11 whatsnew311-idle}@anchor{631}
@subsubsection @code{IDLE} et @code{idlelib}



@itemize *

@item 
Applique la coloration syntaxique aux fichiers @code{.pyi} (contribution d'`Alex Waygood' et de `Terry Jan Reedy' dans bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447}).

@item 
Include prompts when saving Shell with inputs and outputs.
(Contributed by Terry Jan Reedy in gh-95191@footnote{https://github.com/python/cpython/issues/95191}.)
@end itemize

@node inspect<2>,locale<3>,IDLE et idlelib,Modules améliorés<3>
@anchor{whatsnew/3 11 inspect}@anchor{632}@anchor{whatsnew/3 11 whatsnew311-inspect}@anchor{633}
@subsubsection @code{inspect}



@itemize *

@item 
Add @ref{634,,getmembers_static()} to return all members without
triggering dynamic lookup via the descriptor protocol. (Contributed by
Weipeng Hong in bpo-30533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30533}.)

@item 
Add @ref{635,,ismethodwrapper()}
for checking if the type of an object is a @ref{636,,MethodWrapperType}.
(Contributed by Hakan Çelik in bpo-29418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29418}.)

@item 
Change the frame-related functions in the @ref{7d,,inspect} module to return new
@ref{637,,FrameInfo} and @ref{638,,Traceback} class instances
(backwards compatible with the previous @ref{639,,named tuple}-like interfaces)
that includes the extended 
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/} position information (end
line number, column and end column). The affected functions are:


@itemize *

@item 
@ref{63a,,inspect.getframeinfo()}

@item 
@ref{63b,,inspect.getouterframes()}

@item 
@ref{63c,,inspect.getinnerframes()},

@item 
@ref{63d,,inspect.stack()}

@item 
@ref{63e,,inspect.trace()}
@end itemize

(Contributed by Pablo Galindo in gh-88116@footnote{https://github.com/python/cpython/issues/88116}.)
@end itemize

@node locale<3>,logging,inspect<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 locale}@anchor{63f}@anchor{whatsnew/3 11 whatsnew311-locale}@anchor{640}
@subsubsection locale



@itemize *

@item 
Add @ref{2db,,locale.getencoding()} to get the current locale encoding. It is similar to
@code{locale.getpreferredencoding(False)} but ignores the
@ref{641,,Python UTF-8 Mode}.
@end itemize

@node logging,math<3>,locale<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 logging}@anchor{642}@anchor{whatsnew/3 11 whatsnew311-logging}@anchor{643}
@subsubsection logging



@itemize *

@item 
Added @ref{644,,getLevelNamesMapping()}
to return a mapping from logging level names (e.g. @code{'CRITICAL'})
to the values of their corresponding @ref{645,,Niveaux de journalisation} (e.g. @code{50}, by default).
(Contributed by Andrei Kulakovin in gh-88024@footnote{https://github.com/python/cpython/issues/88024}.)

@item 
Added a @ref{646,,createSocket()} method
to @ref{647,,SysLogHandler}, to match
@ref{648,,SocketHandler.createSocket()}.
It is called automatically during handler initialization
and when emitting an event, if there is no active socket.
(Contributed by Kirill Pinchuk in gh-88457@footnote{https://github.com/python/cpython/issues/88457}.)
@end itemize

@node math<3>,operator,logging,Modules améliorés<3>
@anchor{whatsnew/3 11 math}@anchor{649}@anchor{whatsnew/3 11 whatsnew311-math}@anchor{64a}
@subsubsection @code{math}



@itemize *

@item 
Ajout de @ref{64b,,math.exp2()} : renvoie 2 élevé à la puissance @code{x} (contribution de `Gideon Mitchell' dans bpo-45917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45917}).

@item 
Ajout de @ref{64c,,math.cbrt()} : renvoie la racine cubique de @code{x} (contribution d'`Ajith Ramachandran' dans bpo-44357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44357}).

@item 
Le comportement de @ref{64d,,math.pow()} dans deux cas particuliers a été changé pour être cohérent avec la spécification `IEEE 754'. Les opérations @code{math.pow(0.0, -math.inf)} et @code{math.pow(-0.0, -math.inf)} renvoient maintenant @code{inf}. Elles levaient précédemment @ref{1ff,,ValueError} (contribution de `Mark Dickinson' dans bpo-44339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44339}).

@item 
La valeur @ref{64e,,math.nan} est maintenant toujours disponible (contribution de `Victor Stinner' dans bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917}).
@end itemize

@node operator,os<3>,math<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 operator}@anchor{64f}@anchor{whatsnew/3 11 whatsnew311-operator}@anchor{650}
@subsubsection @code{operator}



@itemize *

@item 
A new function @code{operator.call} has been added, such that
@code{operator.call(obj, *args, **kwargs) == obj(*args, **kwargs)}.
(Contributed by Antony Lee in bpo-44019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44019}.)
@end itemize

@node os<3>,pathlib<4>,operator,Modules améliorés<3>
@anchor{whatsnew/3 11 os}@anchor{651}@anchor{whatsnew/3 11 whatsnew311-os}@anchor{652}
@subsubsection @code{os}



@itemize *

@item 
On Windows, @ref{50c,,os.urandom()} now uses @code{BCryptGenRandom()},
instead of @code{CryptGenRandom()} which is deprecated.
(Contributed by Donghee Na in bpo-44611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44611}.)
@end itemize

@node pathlib<4>,re<3>,os<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 pathlib}@anchor{653}@anchor{whatsnew/3 11 whatsnew311-pathlib}@anchor{654}
@subsubsection `pathlib'



@itemize *

@item 
@ref{22a,,glob()} and @ref{22b,,rglob()} return only
directories if `pattern' ends with a pathname components separator:
@ref{655,,sep} or @ref{656,,altsep}.
(Contributed by Eisuke Kawasima in bpo-22276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22276} and bpo-33392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33392}.)
@end itemize

@node re<3>,shutils<3>,pathlib<4>,Modules améliorés<3>
@anchor{whatsnew/3 11 re}@anchor{657}@anchor{whatsnew/3 11 whatsnew311-re}@anchor{658}
@subsubsection @code{re}



@itemize *

@item 
Le groupement atomique (@code{(?>...)}) et les quantificateurs possessifs (@code{*+}, @code{++}, @code{?+}, @code{@{m,n@}+}) sont maintenant pris en charge dans les expressions régulières (contribution de `Jeffrey C. Jacobs' et de `Serhiy Storchaka' dans bpo-433030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=433030}).
@end itemize

@node shutils<3>,socket,re<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 shutil}@anchor{659}@anchor{whatsnew/3 11 whatsnew311-shutil}@anchor{65a}
@subsubsection @code{shutils}



@itemize *

@item 
Ajout du paramètre optionnel `dir_fd' dans @ref{2f5,,shutil.rmtree()} (contribution de `Serhiy Storchaka' dans bpo-46245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46245}).
@end itemize

@node socket,sqlite3<4>,shutils<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 socket}@anchor{65b}@anchor{whatsnew/3 11 whatsnew311-socket}@anchor{65c}
@subsubsection @code{socket}



@itemize *

@item 
Add CAN Socket support for NetBSD.
(Contributed by Thomas Klausner in bpo-30512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30512}.)

@item 
@ref{65d,,create_connection()} has an option to raise, in case of
failure to connect, an @ref{1b4,,ExceptionGroup} containing all errors
instead of only raising the last error.
(Contributed by Irit Katriel in bpo-29980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29980}.)
@end itemize

@node sqlite3<4>,string,socket,Modules améliorés<3>
@anchor{whatsnew/3 11 sqlite3}@anchor{65e}@anchor{whatsnew/3 11 whatsnew311-sqlite3}@anchor{65f}
@subsubsection @code{sqlite3}



@itemize *

@item 
You can now disable the authorizer by passing @ref{660,,None} to
@ref{2a8,,set_authorizer()}.
(Contributed by Erlend E. Aasland in bpo-44491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44491}.)

@item 
Collation name @ref{661,,create_collation()} can now
contain any Unicode character.  Collation names with invalid characters
now raise @ref{662,,UnicodeEncodeError} instead of @ref{4dc,,sqlite3.ProgrammingError}.
(Contributed by Erlend E. Aasland in bpo-44688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44688}.)

@item 
@ref{ce,,sqlite3} exceptions now include the SQLite extended error code as
@ref{663,,sqlite_errorcode} and the SQLite error name as
@ref{664,,sqlite_errorname}.
(Contributed by Aviv Palivoda, Daniel Shahaf, and Erlend E. Aasland in
bpo-16379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16379} and bpo-24139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24139}.)

@item 
Ajout des méthodes @ref{665,,setlimit()} et @ref{666,,getlimit()} à la classe @ref{242,,sqlite3.Connection} pour affecter et demander les limites de `SQLite' pour une connexion (contribution d'`Erlend E. Aasland' dans bpo-45243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45243}).

@item 
@ref{ce,,sqlite3} affecte maintenant @ref{667,,sqlite3.threadsafety} selon le mode d'exécution à fils multiples (`threading' en anglais) par défaut qui a été compilé dans la bibliothèque `SQLite' sous-jacente  (contribution d'`Erlend E. Aasland' dans bpo-45613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45613}).

@item 
@ref{ce,,sqlite3} C callbacks now use unraisable exceptions if callback
tracebacks are enabled. Users can now register an
@ref{1f4,,unraisable hook handler} to improve their debug
experience.
(Contributed by Erlend E. Aasland in bpo-45828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45828}.)

@item 
Fetch across rollback no longer raises @ref{668,,InterfaceError}.
Instead we leave it to the SQLite library to handle these cases.
(Contributed by Erlend E. Aasland in bpo-44092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44092}.)

@item 
Add @ref{669,,serialize()} and
@ref{66a,,deserialize()} to @ref{242,,sqlite3.Connection} for
serializing and deserializing databases.
(Contributed by Erlend E. Aasland in bpo-41930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41930}.)

@item 
Add @ref{66b,,create_window_function()} to
@ref{242,,sqlite3.Connection} for creating aggregate window functions.
(Contributed by Erlend E. Aasland in bpo-34916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34916}.)

@item 
Add @ref{66c,,blobopen()} to @ref{242,,sqlite3.Connection}.
@ref{66d,,sqlite3.Blob} allows incremental I/O operations on blobs.
(Contributed by Aviv Palivoda and Erlend E. Aasland in bpo-24905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24905}.)
@end itemize

@node string,sys<4>,sqlite3<4>,Modules améliorés<3>
@anchor{whatsnew/3 11 string}@anchor{66e}@anchor{whatsnew/3 11 whatsnew311-string}@anchor{66f}
@subsubsection `string'



@itemize *

@item 
Add @ref{670,,get_identifiers()}
and @ref{671,,is_valid()} to @ref{672,,string.Template},
which respectively return all valid placeholders,
and whether any invalid placeholders are present.
(Contributed by Ben Kehoe in gh-90465@footnote{https://github.com/python/cpython/issues/90465}.)
@end itemize

@node sys<4>,sysconfig,string,Modules améliorés<3>
@anchor{whatsnew/3 11 sys}@anchor{673}@anchor{whatsnew/3 11 whatsnew311-sys}@anchor{674}
@subsubsection @code{sys}



@itemize *

@item 
@ref{675,,sys.exc_info()} now derives the @code{type} and @code{traceback} fields
from the @code{value} (the exception instance), so when an exception is
modified while it is being handled, the changes are reflected in
the results of subsequent calls to @code{exc_info()}.
(Contributed by Irit Katriel in bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}.)

@item 
Ajout de @ref{676,,sys.exception()} qui renvoie l'instance de l'exception active (équivalent à @code{sys.exc_info()[1]}) (contribution d'`Irit Katriel' dans bpo-46328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46328}).

@item 
Add the @ref{677,,sys.flags.safe_path} flag.
(Contributed by Victor Stinner in gh-57684@footnote{https://github.com/python/cpython/issues/57684}.)
@end itemize

@node sysconfig,tempfile<3>,sys<4>,Modules améliorés<3>
@anchor{whatsnew/3 11 sysconfig}@anchor{678}@anchor{whatsnew/3 11 whatsnew311-sysconfig}@anchor{679}
@subsubsection @code{sysconfig}



@itemize *

@item 
Three new @ref{67a,,installation schemes}
(`posix_venv', `nt_venv' and `venv') were added and are used when Python
creates new virtual environments or when it is running from a virtual
environment.
The first two schemes (`posix_venv' and `nt_venv') are OS-specific
for non-Windows and Windows, the `venv' is essentially an alias to one of
them according to the OS Python runs on.
This is useful for downstream distributors who modify
@ref{67b,,sysconfig.get_preferred_scheme()}.
Third party code that creates new virtual environments should use the new
`venv' installation scheme to determine the paths, as does @ref{110,,venv}.
(Contributed by Miro Hrončok in bpo-45413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45413}.)
@end itemize

@node tempfile<3>,threading<2>,sysconfig,Modules améliorés<3>
@anchor{whatsnew/3 11 tempfile}@anchor{67c}@anchor{whatsnew/3 11 whatsnew311-tempfile}@anchor{67d}
@subsubsection tempfile



@itemize *

@item 
@ref{67e,,SpooledTemporaryFile} objects now fully implement the methods
of @ref{67f,,io.BufferedIOBase} or @ref{680,,io.TextIOBase}
(depending on file mode).
This lets them work correctly with APIs that expect file-like objects,
such as compression modules.
(Contributed by Carey Metcalfe in gh-70363@footnote{https://github.com/python/cpython/issues/70363}.)
@end itemize

@node threading<2>,time<2>,tempfile<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 threading}@anchor{681}@anchor{whatsnew/3 11 whatsnew311-threading}@anchor{682}
@subsubsection @code{threading}



@itemize *

@item 
On Unix, if the @code{sem_clockwait()} function is available in the C library
(glibc 2.30 and newer), the @ref{683,,threading.Lock.acquire()} method now uses
the monotonic clock (@ref{684,,time.CLOCK_MONOTONIC}) for the timeout, rather
than using the system clock (@ref{685,,time.CLOCK_REALTIME}), to not be affected
by system clock changes.
(Contributed by Victor Stinner in bpo-41710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41710}.)
@end itemize

@node time<2>,tkinter<3>,threading<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 time}@anchor{686}@anchor{whatsnew/3 11 whatsnew311-time}@anchor{687}
@subsubsection @code{time}



@itemize *

@item 
Sur Unix, @ref{688,,time.sleep()} utilise maintenant une des fonctions @code{clock_nanosleep()} ou @code{nanosleep()}, quand elles sont disponibles, qui ont une résolution de 1 nanoseconde (10@w{^-9} secondes), plutôt que d'utiliser @code{select()} qui a une résolution de 1 microseconde (10@w{^-6} secondes) (contribution de `Benjamin Szőke' et de `Victor Stinner' dans bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302}).

@item 
On Windows 8.1 and newer, @ref{688,,time.sleep()} now uses a waitable timer based
on high-resolution timers@footnote{https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/high-resolution-timers}
which has a resolution of 100 nanoseconds (10@w{^-7} seconds). Previously,
it had a resolution of 1 millisecond (10@w{^-3} seconds).
(Contributed by Benjamin Szőke, Donghee Na, Eryk Sun and Victor Stinner in bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302} and bpo-45429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45429}.)
@end itemize

@node tkinter<3>,traceback<2>,time<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 tkinter}@anchor{689}@anchor{whatsnew/3 11 whatsnew311-tkinter}@anchor{68a}
@subsubsection tkinter



@itemize *

@item 
Added method @code{info_patchlevel()} which returns the exact version of
the Tcl library as a named tuple similar to @ref{68b,,sys.version_info}.
(Contributed by Serhiy Storchaka in gh-91827@footnote{https://github.com/python/cpython/issues/91827}.)
@end itemize

@node traceback<2>,typing<4>,tkinter<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 traceback}@anchor{68c}@anchor{whatsnew/3 11 whatsnew311-traceback}@anchor{68d}
@subsubsection traceback



@itemize *

@item 
Add @ref{68e,,traceback.StackSummary.format_frame_summary()} to allow users
to override which frames appear in the traceback, and how they are
formatted.
(Contributed by Ammar Askar in bpo-44569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44569}.)

@item 
Add @ref{68f,,traceback.TracebackException.print()}, which prints the
formatted @ref{259,,TracebackException} instance to a file.
(Contributed by Irit Katriel in bpo-33809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33809}.)
@end itemize

@node typing<4>,unicodedata<3>,traceback<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 typing}@anchor{690}@anchor{whatsnew/3 11 whatsnew311-typing}@anchor{691}
@subsubsection `typing'


Pour les modifications majeures, voir @ref{5a9,,Nouvelles fonctionnalités reliées aux indications de types}.


@itemize *

@item 
Add @ref{692,,typing.assert_never()} and @ref{693,,typing.Never}.
@ref{692,,typing.assert_never()} is useful for asking a type checker to confirm
that a line of code is not reachable. At runtime, it raises an
@ref{694,,AssertionError}.
(Contributed by Jelle Zijlstra in gh-90633@footnote{https://github.com/python/cpython/issues/90633}.)

@item 
Add @ref{695,,typing.reveal_type()}. This is useful for asking a type checker
what type it has inferred for a given expression. At runtime it prints
the type of the received value.
(Contributed by Jelle Zijlstra in gh-90572@footnote{https://github.com/python/cpython/issues/90572}.)

@item 
Add @ref{696,,typing.assert_type()}. This is useful for asking a type checker
to confirm that the type it has inferred for a given expression matches
the given type. At runtime it simply returns the received value.
(Contributed by Jelle Zijlstra in gh-90638@footnote{https://github.com/python/cpython/issues/90638}.)

@item 
@ref{161,,typing.TypedDict} types can now be generic. (Contributed by
Samodya Abeysiriwardane in gh-89026@footnote{https://github.com/python/cpython/issues/89026}.)

@item 
@ref{2ad,,NamedTuple} types can now be generic.
(Contributed by Serhiy Storchaka in bpo-43923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43923}.)

@item 
Allow subclassing of @ref{697,,typing.Any}. This is useful for avoiding
type checker errors related to highly dynamic class, such as mocks.
(Contributed by Shantanu Jain in gh-91154@footnote{https://github.com/python/cpython/issues/91154}.)

@item 
The @ref{698,,typing.final()} decorator now sets the @code{__final__} attributed on
the decorated object.
(Contributed by Jelle Zijlstra in gh-90500@footnote{https://github.com/python/cpython/issues/90500}.)

@item 
The @ref{699,,typing.get_overloads()} function can be used for introspecting
the overloads of a function. @ref{69a,,typing.clear_overloads()} can be used
to clear all registered overloads of a function.
(Contributed by Jelle Zijlstra in gh-89263@footnote{https://github.com/python/cpython/issues/89263}.)

@item 
The @ref{69b,,__init__()} method of @ref{261,,Protocol} subclasses
is now preserved. (Contributed by Adrian Garcia Badarasco in gh-88970@footnote{https://github.com/python/cpython/issues/88970}.)

@item 
The representation of empty tuple types (@code{Tuple[()]}) is simplified.
This affects introspection, e.g. @code{get_args(Tuple[()])} now evaluates
to @code{()} instead of @code{((),)}.
(Contributed by Serhiy Storchaka in gh-91137@footnote{https://github.com/python/cpython/issues/91137}.)

@item 
Loosen runtime requirements for type annotations by removing the callable
check in the private @code{typing._type_check} function. (Contributed by
Gregory Beauregard in gh-90802@footnote{https://github.com/python/cpython/issues/90802}.)

@item 
@ref{69c,,typing.get_type_hints()} now supports evaluating strings as forward
references in @ref{69d,,PEP 585 generic aliases}.
(Contributed by Niklas Rosenstein in gh-85542@footnote{https://github.com/python/cpython/issues/85542}.)

@item 
@ref{69c,,typing.get_type_hints()} no longer adds @ref{69e,,Optional}
to parameters with @code{None} as a default. (Contributed by Nikita Sobolev
in gh-90353@footnote{https://github.com/python/cpython/issues/90353}.)

@item 
@ref{69c,,typing.get_type_hints()} now supports evaluating bare stringified
@ref{263,,ClassVar} annotations. (Contributed by Gregory Beauregard
in gh-90711@footnote{https://github.com/python/cpython/issues/90711}.)

@item 
@ref{69f,,typing.no_type_check()} no longer modifies external classes and functions.
It also now correctly marks classmethods as not to be type checked. (Contributed
by Nikita Sobolev in gh-90729@footnote{https://github.com/python/cpython/issues/90729}.)
@end itemize

@node unicodedata<3>,unittest<4>,typing<4>,Modules améliorés<3>
@anchor{whatsnew/3 11 unicodedata}@anchor{6a0}@anchor{whatsnew/3 11 whatsnew311-unicodedata}@anchor{6a1}
@subsubsection @code{unicodedata}



@itemize *

@item 
The Unicode database has been updated to version 14.0.0.
(Contributed by Benjamin Peterson in bpo-45190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45190}).
@end itemize

@node unittest<4>,venv<2>,unicodedata<3>,Modules améliorés<3>
@anchor{whatsnew/3 11 unittest}@anchor{6a2}@anchor{whatsnew/3 11 whatsnew311-unittest}@anchor{6a3}
@subsubsection unittest



@itemize *

@item 
Added methods @ref{6a4,,enterContext()} and
@ref{6a5,,enterClassContext()} of class
@ref{437,,TestCase}, method
@ref{6a6,,enterAsyncContext()} of
class @ref{301,,IsolatedAsyncioTestCase} and function
@ref{6a7,,unittest.enterModuleContext()}.
(Contributed by Serhiy Storchaka in bpo-45046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45046}.)
@end itemize

@node venv<2>,warnings<2>,unittest<4>,Modules améliorés<3>
@anchor{whatsnew/3 11 venv}@anchor{6a8}@anchor{whatsnew/3 11 whatsnew311-venv}@anchor{6a9}
@subsubsection @code{venv}



@itemize *

@item 
When new Python virtual environments are created, the `venv'
@ref{67a,,sysconfig installation scheme} is used
to determine the paths inside the environment.
When Python runs in a virtual environment, the same installation scheme
is the default.
That means that downstream distributors can change the default sysconfig install
scheme without changing behavior of virtual environments.
Third party code that also creates new virtual environments should do the same.
(Contributed by Miro Hrončok in bpo-45413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45413}.)
@end itemize

@node warnings<2>,zipfile,venv<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 warnings}@anchor{6aa}@anchor{whatsnew/3 11 whatsnew311-warnings}@anchor{6ab}
@subsubsection warnings



@itemize *

@item 
@ref{570,,warnings.catch_warnings()} now accepts arguments for @ref{6ac,,warnings.simplefilter()},
providing a more concise way to locally ignore warnings or convert them to errors.
(Contributed by Zac Hatfield-Dodds in bpo-47074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47074}.)
@end itemize

@node zipfile,,warnings<2>,Modules améliorés<3>
@anchor{whatsnew/3 11 whatsnew311-zipfile}@anchor{6ad}@anchor{whatsnew/3 11 zipfile}@anchor{6ae}
@subsubsection @code{zipfile}



@itemize *

@item 
Added support for specifying member name encoding for reading metadata
in a @ref{6af,,ZipFile}'s directory and file headers.
(Contributed by Stephen J. Turnbull and Serhiy Storchaka in bpo-28080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28080}.)

@item 
Added @ref{6b0,,ZipFile.mkdir()}
for creating new directories inside ZIP archives.
(Contributed by Sam Ezeh in gh-49083@footnote{https://github.com/python/cpython/issues/49083}.)

@item 
Added @ref{6b1,,stem}, @ref{6b2,,suffix}
and @ref{6b3,,suffixes} to @ref{6b4,,zipfile.Path}.
(Contributed by Miguel Brito in gh-88261@footnote{https://github.com/python/cpython/issues/88261}.)
@end itemize

@node Optimisations<3>,Faster CPython,Modules améliorés<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 optimizations}@anchor{6b5}@anchor{whatsnew/3 11 whatsnew311-optimizations}@anchor{6b6}
@subsection Optimisations


This section covers specific optimizations independent of the
@ref{58a,,Faster CPython} project, which is covered in its own section.


@itemize *

@item 
The compiler now optimizes simple
@ref{6b7,,printf-style % formatting} on string literals
containing only the format codes @code{%s}, @code{%r} and @code{%a} and makes it as
fast as a corresponding @ref{41f,,f-string} expression.
(Contributed by Serhiy Storchaka in bpo-28307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28307}.)

@item 
Integer division (@code{//}) is better tuned for optimization by compilers.
It is now around 20% faster on x86-64 when dividing an @ref{254,,int}
by a value smaller than @code{2**30}.
(Contributed by Gregory P. Smith and Tim Peters in gh-90564@footnote{https://github.com/python/cpython/issues/90564}.)

@item 
@ref{454,,sum()} is now nearly 30% faster for integers smaller than @code{2**30}.
(Contributed by Stefan Behnel in gh-68264@footnote{https://github.com/python/cpython/issues/68264}.)

@item 
Resizing lists is streamlined for the common case,
speeding up @code{list.append()} by ≈15%
and simple @ref{6b8,,list comprehension}s by up to 20-30%
(Contributed by Dennis Sweeney in gh-91165@footnote{https://github.com/python/cpython/issues/91165}.)

@item 
Dictionaries don't store hash values when all keys are Unicode objects,
decreasing @ref{253,,dict} size.
For example, @code{sys.getsizeof(dict.fromkeys("abcdefg"))}
is reduced from 352 bytes to 272 bytes (23% smaller) on 64-bit platforms.
(Contributed by Inada Naoki in bpo-46845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46845}.)

@item 
Using @ref{6b9,,asyncio.DatagramProtocol} is now orders of magnitude faster
when transferring large files over UDP,
with speeds over 100 times higher for a ≈60 MiB file.
(Contributed by msoxzw in gh-91487@footnote{https://github.com/python/cpython/issues/91487}.)

@item 
@ref{8d,,math} functions @ref{6ba,,comb()} and @ref{6bb,,perm()} are now
≈10 times faster for large arguments (with a larger speedup for larger `k').
(Contributed by Serhiy Storchaka in bpo-37295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37295}.)

@item 
The @ref{d1,,statistics} functions @ref{6bc,,mean()},
@ref{6bd,,variance()} and @ref{6be,,stdev()} now consume
iterators in one pass rather than converting them to a @ref{5fc,,list} first.
This is twice as fast and can save substantial memory.
(Contributed by Raymond Hettinger in gh-90415@footnote{https://github.com/python/cpython/issues/90415}.)

@item 
@ref{6bf,,unicodedata.normalize()}
now normalizes pure-ASCII strings in constant time.
(Contributed by Donghee Na in bpo-44987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44987}.)
@end itemize

@node Faster CPython,Changements au code intermédiaire CPython<2>,Optimisations<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 faster-cpython}@anchor{6c0}@anchor{whatsnew/3 11 whatsnew311-faster-cpython}@anchor{58a}
@subsection Faster CPython


CPython 3.11 is an average of
25% faster@footnote{https://github.com/faster-cpython/ideas#published-results}
than CPython 3.10 as measured with the
pyperformance@footnote{https://github.com/python/pyperformance} benchmark suite,
when compiled with GCC on Ubuntu Linux.
Depending on your workload, the overall speedup could be 10-60%.

This project focuses on two major areas in Python:
@ref{6c1,,Faster Startup} and @ref{6c2,,Faster Runtime}.
Optimizations not covered by this project are listed separately under
@ref{6b6,,Optimisations}.

@menu
* Faster Startup:: 
* Faster Runtime:: 
* Misc:: 
* FAQ:: 
* À propos:: 

@end menu

@node Faster Startup,Faster Runtime,,Faster CPython
@anchor{whatsnew/3 11 faster-startup}@anchor{6c3}@anchor{whatsnew/3 11 whatsnew311-faster-startup}@anchor{6c1}
@subsubsection Faster Startup


@menu
* Frozen imports / Static code objects:: 

@end menu

@node Frozen imports / Static code objects,,,Faster Startup
@anchor{whatsnew/3 11 frozen-imports-static-code-objects}@anchor{6c4}@anchor{whatsnew/3 11 whatsnew311-faster-imports}@anchor{6c5}
@subsubsection Frozen imports / Static code objects


Python caches @ref{185,,bytecode} in the @ref{6c6,,__pycache__}
directory to speed up module loading.

Previously in 3.10, Python module execution looked like this:

@example
Read __pycache__ -> Unmarshal -> Heap allocated code object -> Evaluate
@end example

In Python 3.11, the core modules essential for Python startup are "frozen".
This means that their @ref{59f,,Objets code} (and bytecode)
are statically allocated by the interpreter.
This reduces the steps in module execution process to:

@example
Statically allocated code object -> Evaluate
@end example

Le lancement de l'interpréteur est 10 à 15 % plus rapide dans la version 3.11. Cela a un grand impact pour les programmes courts utilisant Python.

(Contributed by Eric Snow, Guido van Rossum and Kumar Aditya in many issues.)

@node Faster Runtime,Misc,Faster Startup,Faster CPython
@anchor{whatsnew/3 11 faster-runtime}@anchor{6c7}@anchor{whatsnew/3 11 whatsnew311-faster-runtime}@anchor{6c2}
@subsubsection Faster Runtime


@menu
* Cheaper@comma{} lazy Python frames: Cheaper lazy Python frames. 
* Inlined Python function calls:: 
* PEP 659; Specializing Adaptive Interpreter: PEP 659 Specializing Adaptive Interpreter. 

@end menu

@node Cheaper lazy Python frames,Inlined Python function calls,,Faster Runtime
@anchor{whatsnew/3 11 cheaper-lazy-python-frames}@anchor{6c8}@anchor{whatsnew/3 11 whatsnew311-lazy-python-frames}@anchor{6c9}
@subsubsection Cheaper, lazy Python frames


Python frames, holding execution information,
are created whenever Python calls a Python function.
The following are new frame optimizations:


@itemize -

@item 
Streamlined the frame creation process.

@item 
Avoided memory allocation by generously re-using frame space on the C stack.

@item 
Streamlined the internal frame struct to contain only essential information.
Frames previously held extra debugging and memory management information.
@end itemize

Old-style @ref{6ca,,frame objects}
are now created only when requested by debuggers
or by Python introspection functions such as @ref{6cb,,sys._getframe()} and
@ref{6cc,,inspect.currentframe()}. For most user code, no frame objects are
created at all. As a result, nearly all Python functions calls have sped
up significantly. We measured a 3-7% speedup in pyperformance.

(Contributed by Mark Shannon in bpo-44590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44590}.)
@anchor{whatsnew/3 11 inline-calls}@anchor{6cd}
@node Inlined Python function calls,PEP 659 Specializing Adaptive Interpreter,Cheaper lazy Python frames,Faster Runtime
@anchor{whatsnew/3 11 inlined-python-function-calls}@anchor{6ce}@anchor{whatsnew/3 11 whatsnew311-inline-calls}@anchor{6cf}
@subsubsection Inlined Python function calls


During a Python function call, Python will call an evaluating C function to
interpret that function's code. This effectively limits pure Python recursion to
what's safe for the C stack.

In 3.11, when CPython detects Python code calling another Python function,
it sets up a new frame, and "jumps" to the new code inside the new frame. This
avoids calling the C interpreting function altogether.

Most Python function calls now consume no C stack space, speeding them up.
In simple recursive functions like fibonacci or
factorial, we observed a 1.7x speedup. This also means recursive functions
can recurse significantly deeper
(if the user increases the recursion limit with @ref{4ac,,sys.setrecursionlimit()}).
We measured a 1-3% improvement in pyperformance.

(Contributed by Pablo Galindo and Mark Shannon in bpo-45256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45256}.)

@node PEP 659 Specializing Adaptive Interpreter,,Inlined Python function calls,Faster Runtime
@anchor{whatsnew/3 11 pep-659-specializing-adaptive-interpreter}@anchor{6d0}@anchor{whatsnew/3 11 whatsnew311-pep659}@anchor{17a}
@subsubsection PEP 659: Specializing Adaptive Interpreter


@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/} is one of the key parts of the Faster CPython project. The general
idea is that while Python is a dynamic language, most code has regions where
objects and types rarely change. This concept is known as `type stability'.

At runtime, Python will try to look for common patterns and type stability
in the executing code. Python will then replace the current operation with a
more specialized one. This specialized operation uses fast paths available only
to those use cases/types, which generally outperform their generic
counterparts. This also brings in another concept called `inline caching', where
Python caches the results of expensive operations directly in the
@ref{185,,bytecode}.

The specializer will also combine certain common instruction pairs into one
superinstruction, reducing the overhead during execution.

Python will only specialize
when it sees code that is "hot" (executed multiple times). This prevents Python
from wasting time on run-once code. Python can also de-specialize when code is
too dynamic or when the use changes. Specialization is attempted periodically,
and specialization attempts are not too expensive,
allowing specialization to adapt to new circumstances.

(PEP written by Mark Shannon, with ideas inspired by Stefan Brunthaler.
See 
@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/} for more information. Implementation by Mark Shannon and Brandt
Bucher, with additional help from Irit Katriel and Dennis Sweeney.)

@c If I missed out anyone, please add them.


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Forme

@tab

Specialization

@tab

Operation speedup
(up to)

@tab

Contributor(s)

@item

Binary
operations

@tab

@code{x + x}

@code{x - x}

@code{x * x}

@tab

Binary add, multiply and subtract for common types
such as @ref{254,,int}, @ref{2eb,,float} and @ref{435,,str}
take custom fast paths for their underlying types.

@tab

10%

@tab

Mark Shannon,
Donghee Na,
Brandt Bucher,
Dennis Sweeney

@item

Subscript

@tab

@code{a[i]}

@tab

Subscripting container types such as @ref{5fc,,list},
@ref{366,,tuple} and @ref{253,,dict} directly index
the underlying data structures.

Subscripting custom @ref{280,,__getitem__()}
is also inlined similar to @ref{6cd,,Inlined Python function calls}.

@tab

10-25%

@tab

Irit Katriel,
Mark Shannon

@item

Store
subscript

@tab

@code{a[i] = z}

@tab

Similar to subscripting specialization above.

@tab

10-25%

@tab

Dennis Sweeney

@item

Appels

@tab

@code{f(arg)}

@code{C(arg)}

@tab

Calls to common builtin (C) functions and types such
as @ref{619,,len()} and @ref{435,,str} directly call their
underlying C version. This avoids going through the
internal calling convention.

@tab

20%

@tab

Mark Shannon,
Ken Jin

@item

Load
global
variable

@tab

@code{print}

@code{len}

@tab

The object's index in the globals/builtins namespace
is cached. Loading globals and builtins require
zero namespace lookups.

@tab

@footnote{
A similar optimization already existed since Python 3.8.
3.11 specializes for more forms and reduces some overhead.
}

@tab

Mark Shannon

@item

Load
attribute

@tab

@code{o.attr}

@tab

Similar to loading global variables. The attribute's
index inside the class/object's namespace is cached.
In most cases, attribute loading will require zero
namespace lookups.

@tab

@footnote{
A similar optimization already existed since Python 3.10.
3.11 specializes for more forms. Furthermore, all attribute loads should
be sped up by @uref{https://bugs.python.org/issue?@@action=redirect&bpo=45947,bpo-45947}.
}

@tab

Mark Shannon

@item

Load
methods for
call

@tab

@code{o.meth()}

@tab

The actual address of the method is cached. Method
loading now has no namespace lookups -- even for
classes with long inheritance chains.

@tab

10-20%

@tab

Ken Jin,
Mark Shannon

@item

Store
attribute

@tab

@code{o.attr = z}

@tab

Similar to load attribute optimization.

@tab

2%
in pyperformance

@tab

Mark Shannon

@item

Unpack
Sequence

@tab

@code{*seq}

@tab

Specialized for common containers such as
@ref{5fc,,list} and @ref{366,,tuple}.
Avoids internal calling convention.

@tab

8%

@tab

Brandt Bucher

@end multitable


@node Misc,FAQ,Faster Runtime,Faster CPython
@anchor{whatsnew/3 11 misc}@anchor{6d1}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-misc}@anchor{6d2}
@subsubsection Misc



@itemize *

@item 
Objects now require less memory due to lazily created object namespaces.
Their namespace dictionaries now also share keys more freely.
(Contributed Mark Shannon in bpo-45340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45340} and bpo-40116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40116}.)

@item 
"Zero-cost" exceptions are implemented, eliminating the cost
of @ref{6d3,,try} statements when no exception is raised.
(Contributed by Mark Shannon in bpo-40222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40222}.)

@item 
A more concise representation of exceptions in the interpreter reduced the
time required for catching an exception by about 10%.
(Contributed by Irit Katriel in bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}.)

@item 
@ref{b8,,re}'s regular expression matching engine has been partially refactored,
and now uses computed gotos (or "threaded code") on supported platforms. As a
result, Python 3.11 executes the pyperformance regular expression benchmarks@footnote{https://pyperformance.readthedocs.io/benchmarks.html#regex-dna} up to 10%
faster than Python 3.10.
(Contributed by Brandt Bucher in gh-91404@footnote{https://github.com/python/cpython/issues/91404}.)
@end itemize

@node FAQ,À propos,Misc,Faster CPython
@anchor{whatsnew/3 11 faq}@anchor{6d4}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-faq}@anchor{6d5}
@subsubsection FAQ


@menu
* How should I write my code to utilize these speedups?:: 
* Will CPython 3.11 use more memory?: Will CPython 3 11 use more memory?. 
* I don't see any speedups in my workload. Why?: I don't see any speedups in my workload Why?. 
* Is there a JIT compiler?:: 

@end menu

@node How should I write my code to utilize these speedups?,Will CPython 3 11 use more memory?,,FAQ
@anchor{whatsnew/3 11 faster-cpython-faq-my-code}@anchor{6d6}@anchor{whatsnew/3 11 how-should-i-write-my-code-to-utilize-these-speedups}@anchor{6d7}
@subsubsection How should I write my code to utilize these speedups?


Write Pythonic code that follows common best practices;
you don't have to change your code.
The Faster CPython project optimizes for common code patterns we observe.

@node Will CPython 3 11 use more memory?,I don't see any speedups in my workload Why?,How should I write my code to utilize these speedups?,FAQ
@anchor{whatsnew/3 11 faster-cpython-faq-memory}@anchor{6d8}@anchor{whatsnew/3 11 will-cpython-3-11-use-more-memory}@anchor{6d9}
@subsubsection Will CPython 3.11 use more memory?


Maybe not; we don't expect memory use to exceed 20% higher than 3.10.
This is offset by memory optimizations for frame objects and object
dictionaries as mentioned above.

@node I don't see any speedups in my workload Why?,Is there a JIT compiler?,Will CPython 3 11 use more memory?,FAQ
@anchor{whatsnew/3 11 faster-cpython-ymmv}@anchor{6da}@anchor{whatsnew/3 11 i-don-t-see-any-speedups-in-my-workload-why}@anchor{6db}
@subsubsection I don't see any speedups in my workload. Why?


Certain code won't have noticeable benefits. If your code spends most of
its time on I/O operations, or already does most of its
computation in a C extension library like NumPy, there won't be significant
speedups. This project currently benefits pure-Python workloads the most.

Furthermore, the pyperformance figures are a geometric mean. Even within the
pyperformance benchmarks, certain benchmarks have slowed down slightly, while
others have sped up by nearly 2x!

@node Is there a JIT compiler?,,I don't see any speedups in my workload Why?,FAQ
@anchor{whatsnew/3 11 faster-cpython-jit}@anchor{6dc}@anchor{whatsnew/3 11 is-there-a-jit-compiler}@anchor{6dd}
@subsubsection Is there a JIT compiler?


No. We're still exploring other optimizations.

@node À propos,,FAQ,Faster CPython
@anchor{whatsnew/3 11 about}@anchor{6de}@anchor{whatsnew/3 11 whatsnew311-faster-cpython-about}@anchor{6df}
@subsubsection À propos


Faster CPython explores optimizations for @ref{6e0,,CPython}. The main team is
funded by Microsoft to work on this full-time. Pablo Galindo Salgado is also
funded by Bloomberg LP to work on the project part-time. Finally, many
contributors are volunteers from the community.

@node Changements au code intermédiaire CPython<2>,Obsolescence<3>,Faster CPython,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 cpython-bytecode-changes}@anchor{6e1}@anchor{whatsnew/3 11 whatsnew311-bytecode-changes}@anchor{6e2}
@subsection Changements au code intermédiaire CPython


The bytecode now contains inline cache entries,
which take the form of the newly-added @ref{6e3,,CACHE} instructions.
Many opcodes expect to be followed by an exact number of caches,
and instruct the interpreter to skip over them at runtime.
Populated caches can look like arbitrary instructions,
so great care should be taken when reading or modifying
raw, adaptive bytecode containing quickened data.

@menu
* New opcodes:: 
* Replaced opcodes:: 
* Changed/removed opcodes:: 

@end menu

@node New opcodes,Replaced opcodes,,Changements au code intermédiaire CPython<2>
@anchor{whatsnew/3 11 new-opcodes}@anchor{6e4}@anchor{whatsnew/3 11 whatsnew311-added-opcodes}@anchor{6e5}
@subsubsection New opcodes



@itemize *

@item 
@code{ASYNC_GEN_WRAP}, @ref{6e6,,RETURN_GENERATOR} and @ref{6e7,,SEND},
used in generators and co-routines.

@item 
@ref{6e8,,COPY_FREE_VARS},
which avoids needing special caller-side code for closures.

@item 
@ref{6e9,,JUMP_BACKWARD_NO_INTERRUPT},
for use in certain loops where handling interrupts is undesirable.

@item 
@ref{6ea,,MAKE_CELL}, to create @ref{6eb,,Objets Cellules}.

@item 
@ref{6ec,,CHECK_EG_MATCH}  and  @code{PREP_RERAISE_STAR},
to handle the @ref{58b,,new exception groups and except*}
added in 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/}.

@item 
@ref{6ed,,PUSH_EXC_INFO}, for use in exception handlers.

@item 
@ref{30a,,RESUME}, a no-op,
for internal tracing, debugging and optimization checks.
@end itemize

@node Replaced opcodes,Changed/removed opcodes,New opcodes,Changements au code intermédiaire CPython<2>
@anchor{whatsnew/3 11 replaced-opcodes}@anchor{6ee}@anchor{whatsnew/3 11 whatsnew311-replaced-opcodes}@anchor{6ef}
@subsubsection Replaced opcodes



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Replaced Opcode(s)

@tab

New Opcode(s)

@tab

Notes

@item


@display
@code{BINARY_*}@w{ }
@code{INPLACE_*}@w{ }
@end display



@tab

@ref{6f0,,BINARY_OP}

@tab

Replaced all numeric binary/in-place
opcodes with a single opcode

@item


@display
@code{CALL_FUNCTION}@w{ }
@code{CALL_FUNCTION_KW}@w{ }
@code{CALL_METHOD}@w{ }
@end display



@tab


@display
@ref{6f1,,CALL}@w{ }
@code{KW_NAMES}@w{ }
@code{PRECALL}@w{ }
@ref{6f2,,PUSH_NULL}@w{ }
@end display



@tab

Decouples argument shifting for methods
from handling of keyword arguments;
allows better specialization of calls

@item


@display
@code{DUP_TOP}@w{ }
@code{DUP_TOP_TWO}@w{ }
@code{ROT_TWO}@w{ }
@code{ROT_THREE}@w{ }
@code{ROT_FOUR}@w{ }
@code{ROT_N}@w{ }
@end display



@tab


@display
@ref{6f3,,COPY}@w{ }
@ref{6f4,,SWAP}@w{ }
@end display



@tab

Stack manipulation instructions

@item


@display
@code{JUMP_IF_NOT_EXC_MATCH}@w{ }
@end display



@tab


@display
@ref{6f5,,CHECK_EXC_MATCH}@w{ }
@end display



@tab

Now performs check but doesn't jump

@item


@display
@code{JUMP_ABSOLUTE}@w{ }
@code{POP_JUMP_IF_FALSE}@w{ }
@code{POP_JUMP_IF_TRUE}@w{ }
@end display



@tab


@display
@ref{6f6,,JUMP_BACKWARD}@w{ }
@code{POP_JUMP_BACKWARD_IF_*}@w{ }
@code{POP_JUMP_FORWARD_IF_*}@w{ }
@end display



@tab

See @footnote{
All jump opcodes are now relative, including the
existing @code{JUMP_IF_TRUE_OR_POP} and @code{JUMP_IF_FALSE_OR_POP}.
The argument is now an offset from the current instruction
rather than an absolute location.
};
@code{TRUE}, @code{FALSE},
@code{NONE} and @code{NOT_NONE} variants
for each direction

@item


@display
@code{SETUP_WITH}@w{ }
@code{SETUP_ASYNC_WITH}@w{ }
@end display



@tab

@ref{6f7,,BEFORE_WITH}

@tab

@ref{5bc,,with} block setup

@end multitable

@anchor{whatsnew/3 11 whatsnew311-changed-opcodes}@anchor{6f8}@anchor{whatsnew/3 11 whatsnew311-removed-opcodes}@anchor{6f9}
@node Changed/removed opcodes,,Replaced opcodes,Changements au code intermédiaire CPython<2>
@anchor{whatsnew/3 11 changed-removed-opcodes}@anchor{6fa}@anchor{whatsnew/3 11 whatsnew311-changed-removed-opcodes}@anchor{6fb}
@subsubsection Changed/removed opcodes



@itemize *

@item 
Changed @ref{6fc,,MATCH_CLASS} and @ref{6fd,,MATCH_KEYS}
to no longer push an additional boolean value to indicate success/failure.
Instead, @code{None} is pushed on failure
in place of the tuple of extracted values.

@item 
Changed opcodes that work with exceptions to reflect them
now being represented as one item on the stack instead of three
(see gh-89874@footnote{https://github.com/python/cpython/issues/89874}).

@item 
Removed @code{COPY_DICT_WITHOUT_KEYS}, @code{GEN_START},
@code{POP_BLOCK}, @code{SETUP_FINALLY} and @code{YIELD_FROM}.
@end itemize
@anchor{whatsnew/3 11 whatsnew311-deprecated}@anchor{6fe}
@node Obsolescence<3>,Pending Removal in Python 3 12,Changements au code intermédiaire CPython<2>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 deprecated}@anchor{6ff}@anchor{whatsnew/3 11 whatsnew311-python-api-deprecated}@anchor{700}
@subsection Obsolescence


Cette section liste les API Python qui sont devenues obsolètes dans la version 3.11.

Deprecated C APIs are @ref{701,,listed separately}.
@anchor{whatsnew/3 11 whatsnew311-deprecated-language}@anchor{702}
@menu
* Language/Builtins:: 
* Modules:: 
* Bibliothèque Standard:: 

@end menu

@node Language/Builtins,Modules,,Obsolescence<3>
@anchor{whatsnew/3 11 language-builtins}@anchor{703}@anchor{whatsnew/3 11 whatsnew311-deprecated-builtins}@anchor{704}
@subsubsection Language/Builtins



@itemize *

@item 
Chaining @ref{165,,classmethod} descriptors (introduced in bpo-19072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19072})
is now deprecated.  It can no longer be used to wrap other descriptors
such as @ref{192,,property}.  The core design of this feature was flawed
and caused a number of downstream problems.  To "pass-through" a
@ref{165,,classmethod}, consider using the @code{__wrapped__} attribute
that was added in Python 3.10.
(Contributed by Raymond Hettinger in gh-89519@footnote{https://github.com/python/cpython/issues/89519}.)

@item 
Octal escapes in string and bytes literals with values larger than @code{0o377}
(255 in decimal) now produce a @ref{1a3,,DeprecationWarning}.
In a future Python version, they will raise a @ref{44f,,SyntaxWarning} and
eventually a @ref{18b,,SyntaxError}.
(Contributed by Serhiy Storchaka in gh-81548@footnote{https://github.com/python/cpython/issues/81548}.)

@item 
The delegation of @ref{254,,int()} to @ref{705,,__trunc__()} is now deprecated.
Calling @code{int(a)} when @code{type(a)} implements @code{__trunc__()} but not
@ref{706,,__int__()} or @ref{707,,__index__()} now raises
a @ref{1a3,,DeprecationWarning}.
(Contributed by Zackery Spytz in bpo-44977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44977}.)
@end itemize

@node Modules,Bibliothèque Standard,Language/Builtins,Obsolescence<3>
@anchor{whatsnew/3 11 modules}@anchor{708}@anchor{whatsnew/3 11 whatsnew311-deprecated-modules}@anchor{709}
@subsubsection Modules

@anchor{whatsnew/3 11 whatsnew311-pep594}@anchor{596}

@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} led to the deprecations of the following modules
slated for removal in Python 3.13:


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{aifc}

@tab

@code{chunk}

@tab

@code{msilib}

@tab

@code{pipes}

@tab

@code{telnetlib}

@item

@code{audioop}

@tab

@code{crypt}

@tab

@code{nis}

@tab

@code{sndhdr}

@tab

@code{uu}

@item

@code{cgi}

@tab

@code{imghdr}

@tab

@code{nntplib}

@tab

@code{spwd}

@tab

@code{xdrlib}

@item

@code{cgitb}

@tab

@code{mailcap}

@tab

@code{ossaudiodev}

@tab

@code{sunau}

@tab

@end multitable


(Contributed by Brett Cannon in bpo-47061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47061} and Victor Stinner in
gh-68966@footnote{https://github.com/python/cpython/issues/68966}.)

@item 
The @code{asynchat}, @code{asyncore} and  @code{smtpd} modules have been
deprecated since at least Python 3.6. Their documentation and deprecation
warnings have now been updated to note they will be removed in Python 3.12.
(Contributed by Hugo van Kemenade in bpo-47022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47022}.)

@item 
The @code{lib2to3} package and @code{2to3} tool
are now deprecated and may not be able to parse Python 3.10 or newer.
See 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/}, introducing the new PEG parser, for details.
(Contributed by Victor Stinner in bpo-40360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40360}.)

@item 
Undocumented modules @code{sre_compile}, @code{sre_constants}
and @code{sre_parse} are now deprecated.
(Contributed by Serhiy Storchaka in bpo-47152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47152}.)
@end itemize

@node Bibliothèque Standard,,Modules,Obsolescence<3>
@anchor{whatsnew/3 11 standard-library}@anchor{70a}@anchor{whatsnew/3 11 whatsnew311-deprecated-stdlib}@anchor{70b}
@subsubsection Bibliothèque Standard



@itemize *

@item 
The following have been deprecated in @ref{22,,configparser} since Python 3.2.
Their deprecation warnings have now been updated to note they will be removed
in Python 3.12:


@itemize *

@item 
the @code{configparser.SafeConfigParser} class

@item 
the @code{configparser.ParsingError.filename} property

@item 
the @code{configparser.RawConfigParser.readfp()} method
@end itemize

(Contributed by Hugo van Kemenade in bpo-45173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45173}.)

@item 
@code{configparser.LegacyInterpolation} has been deprecated in the docstring
since Python 3.2, and is not listed in the @ref{22,,configparser} documentation.
It now emits a @ref{1a3,,DeprecationWarning} and will be removed
in Python 3.13. Use @ref{70c,,configparser.BasicInterpolation} or
@ref{70d,,configparser.ExtendedInterpolation} instead.
(Contributed by Hugo van Kemenade in bpo-46607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46607}.)

@item 
The older set of @ref{7a,,importlib.resources} functions were deprecated
in favor of the replacements added in Python 3.9
and will be removed in a future Python version,
due to not supporting resources located within package subdirectories:


@itemize *

@item 
@code{importlib.resources.contents()}

@item 
@code{importlib.resources.is_resource()}

@item 
@code{importlib.resources.open_binary()}

@item 
@code{importlib.resources.open_text()}

@item 
@code{importlib.resources.read_binary()}

@item 
@code{importlib.resources.read_text()}

@item 
@code{importlib.resources.path()}
@end itemize

@item 
The @ref{2d8,,locale.getdefaultlocale()} function is deprecated and will be
removed in Python 3.15. Use @ref{2da,,locale.setlocale()},
@ref{524,,locale.getpreferredencoding(False)} and
@ref{2d9,,locale.getlocale()} functions instead.
(Contributed by Victor Stinner in gh-90817@footnote{https://github.com/python/cpython/issues/90817}.)

@item 
The @code{locale.resetlocale()} function is deprecated and will be
removed in Python 3.13. Use @code{locale.setlocale(locale.LC_ALL, "")} instead.
(Contributed by Victor Stinner in gh-90817@footnote{https://github.com/python/cpython/issues/90817}.)

@item 
Stricter rules will now be applied for numerical group references
and group names in @ref{70e,,regular expressions}.
Only sequences of ASCII digits will now be accepted as a numerical reference,
and the group name in @ref{1bd,,bytes} patterns and replacement strings
can only contain ASCII letters, digits and underscores.
For now, a deprecation warning is raised for syntax violating these rules.
(Contributed by Serhiy Storchaka in gh-91760@footnote{https://github.com/python/cpython/issues/91760}.)

@item 
In the @ref{b8,,re} module, the @code{re.template()} function
and the corresponding @code{re.TEMPLATE} and @code{re.T} flags
are deprecated, as they were undocumented and lacked an obvious purpose.
They will be removed in Python 3.13.
(Contributed by Serhiy Storchaka and Miro Hrončok in gh-92728@footnote{https://github.com/python/cpython/issues/92728}.)

@item 
@code{turtle.settiltangle()} has been deprecated since Python 3.1;
it now emits a deprecation warning and will be removed in Python 3.13. Use
@ref{70f,,turtle.tiltangle()} instead (it was earlier incorrectly marked
as deprecated, and its docstring is now corrected).
(Contributed by Hugo van Kemenade in bpo-45837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45837}.)

@item 
@ref{300,,typing.Text}, which exists solely to provide compatibility support
between Python 2 and Python 3 code, is now deprecated. Its removal is
currently unplanned, but users are encouraged to use @ref{435,,str} instead
wherever possible.
(Contributed by Alex Waygood in gh-92332@footnote{https://github.com/python/cpython/issues/92332}.)

@item 
The keyword argument syntax for constructing @ref{161,,typing.TypedDict} types
is now deprecated. Support will be removed in Python 3.13. (Contributed by
Jingchen Ye in gh-90224@footnote{https://github.com/python/cpython/issues/90224}.)

@item 
@code{webbrowser.MacOSX} is deprecated and will be removed in Python 3.13.
It is untested, undocumented, and not used by @ref{114,,webbrowser} itself.
(Contributed by Donghee Na in bpo-42255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42255}.)

@item 
The behavior of returning a value from a @ref{437,,TestCase} and
@ref{301,,IsolatedAsyncioTestCase} test methods (other than the
default @code{None} value) is now deprecated.

@item 
Deprecated the following not-formally-documented @ref{105,,unittest} functions,
scheduled for removal in Python 3.13:


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

Use @ref{28b,,TestLoader} methods instead:


@itemize *

@item 
@ref{28c,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{28d,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{28e,,unittest.TestLoader.getTestCaseNames()}
@end itemize

(Contributed by Erlend E. Aasland in bpo-5846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5846}.)

@item 
@code{unittest.TestProgram.usageExit()} is marked deprecated, to be removed
in 3.13.
(Contributed by Carlos Damázio in gh-67048@footnote{https://github.com/python/cpython/issues/67048}.)
@end itemize
@anchor{whatsnew/3 11 whatsnew311-pending-removal}@anchor{710}
@node Pending Removal in Python 3 12,Retraits<3>,Obsolescence<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 pending-removal-in-python-3-12}@anchor{711}@anchor{whatsnew/3 11 whatsnew311-python-api-pending-removal}@anchor{712}
@subsection Pending Removal in Python 3.12


Les API Python suivantes sont devenues obsolètes dans des versions précédentes, et seront supprimées dans la version 3.12.

C APIs pending removal are
@ref{713,,listed separately}.


@itemize *

@item 
The @code{asynchat} module

@item 
The @code{asyncore} module

@item 
The @ref{714,,entire distutils package}

@item 
The @code{imp} module

@item 
The @ref{715,,typing.io} namespace

@item 
The @ref{716,,typing.re} namespace

@item 
@code{cgi.log()}

@item 
@code{importlib.find_loader()}

@item 
@code{importlib.abc.Loader.module_repr()}

@item 
@code{importlib.abc.MetaPathFinder.find_module()}

@item 
@code{importlib.abc.PathEntryFinder.find_loader()}

@item 
@code{importlib.abc.PathEntryFinder.find_module()}

@item 
@code{importlib.machinery.BuiltinImporter.find_module()}

@item 
@code{importlib.machinery.BuiltinLoader.module_repr()}

@item 
@code{importlib.machinery.FileFinder.find_loader()}

@item 
@code{importlib.machinery.FileFinder.find_module()}

@item 
@code{importlib.machinery.FrozenImporter.find_module()}

@item 
@code{importlib.machinery.FrozenLoader.module_repr()}

@item 
@code{importlib.machinery.PathFinder.find_module()}

@item 
@code{importlib.machinery.WindowsRegistryFinder.find_module()}

@item 
@code{importlib.util.module_for_loader()}

@item 
@code{importlib.util.set_loader_wrapper()}

@item 
@code{importlib.util.set_package_wrapper()}

@item 
@code{pkgutil.ImpImporter}

@item 
@code{pkgutil.ImpLoader}

@item 
@code{pathlib.Path.link_to()}

@item 
@code{sqlite3.enable_shared_cache()}

@item 
@code{sqlite3.OptimizedUnicode()}

@item 
@code{PYTHONTHREADDEBUG} environment variable

@item 
The following deprecated aliases in @ref{105,,unittest}:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Deprecated alias

@tab

Nom de méthode

@tab

Deprecated in

@item

@code{failUnless}

@tab

@ref{510,,assertTrue()}

@tab

3.1

@item

@code{failIf}

@tab

@ref{511,,assertFalse()}

@tab

3.1

@item

@code{failUnlessEqual}

@tab

@ref{512,,assertEqual()}

@tab

3.1

@item

@code{failIfEqual}

@tab

@ref{513,,assertNotEqual()}

@tab

3.1

@item

@code{failUnlessAlmostEqual}

@tab

@ref{514,,assertAlmostEqual()}

@tab

3.1

@item

@code{failIfAlmostEqual}

@tab

@ref{515,,assertNotAlmostEqual()}

@tab

3.1

@item

@code{failUnlessRaises}

@tab

@ref{516,,assertRaises()}

@tab

3.1

@item

@code{assert_}

@tab

@ref{510,,assertTrue()}

@tab

3.2

@item

@code{assertEquals}

@tab

@ref{512,,assertEqual()}

@tab

3.2

@item

@code{assertNotEquals}

@tab

@ref{513,,assertNotEqual()}

@tab

3.2

@item

@code{assertAlmostEquals}

@tab

@ref{514,,assertAlmostEqual()}

@tab

3.2

@item

@code{assertNotAlmostEquals}

@tab

@ref{515,,assertNotAlmostEqual()}

@tab

3.2

@item

@code{assertRegexpMatches}

@tab

@ref{517,,assertRegex()}

@tab

3.2

@item

@code{assertRaisesRegexp}

@tab

@ref{518,,assertRaisesRegex()}

@tab

3.2

@item

@code{assertNotRegexpMatches}

@tab

@ref{519,,assertNotRegex()}

@tab

3.5

@end multitable

@end quotation
@end itemize
@anchor{whatsnew/3 11 whatsnew311-removed}@anchor{717}
@node Retraits<3>,Portage vers Python 3 11,Pending Removal in Python 3 12,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 removed}@anchor{718}@anchor{whatsnew/3 11 whatsnew311-python-api-removed}@anchor{719}
@subsection Retraits


Cette section liste les API Python qui ont été supprimées dans la version 3.11.

Removed C APIs are @ref{71a,,listed separately}.


@itemize *

@item 
Removed the @code{@@asyncio.coroutine()} @ref{71b,,decorator}
enabling legacy generator-based coroutines to be compatible with
@ref{71c,,async} / @ref{1b7,,await} code.
The function has been deprecated since Python 3.8 and the removal was
initially scheduled for Python 3.10. Use @ref{5bb,,async def} instead.
(Contributed by Illia Volochii in bpo-43216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43216}.)

@item 
Removed @code{asyncio.coroutines.CoroWrapper} used for wrapping legacy
generator-based coroutine objects in the debug mode.
(Contributed by Illia Volochii in bpo-43216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43216}.)

@item 
Due to significant security concerns, the `reuse_address' parameter of
@ref{71d,,asyncio.loop.create_datagram_endpoint()}, disabled in Python 3.9, is
now entirely removed. This is because of the behavior of the socket option
@code{SO_REUSEADDR} in UDP.
(Contributed by Hugo van Kemenade in bpo-45129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45129}.)

@item 
Removed the @code{binhex} module, deprecated in Python 3.9.
Also removed the related, similarly-deprecated @ref{10,,binascii} functions:


@itemize *

@item 
@code{binascii.a2b_hqx()}

@item 
@code{binascii.b2a_hqx()}

@item 
@code{binascii.rlecode_hqx()}

@item 
@code{binascii.rldecode_hqx()}
@end itemize

The @ref{71e,,binascii.crc_hqx()} function remains available.

(Contributed by Victor Stinner in bpo-45085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45085}.)

@item 
Removed the @code{distutils} @code{bdist_msi} command deprecated in Python 3.9.
Use @code{bdist_wheel} (wheel packages) instead.
(Contributed by Hugo van Kemenade in bpo-45124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45124}.)

@item 
Removed the @ref{280,,__getitem__()} methods of
@ref{71f,,xml.dom.pulldom.DOMEventStream}, @ref{720,,wsgiref.util.FileWrapper}
and @ref{721,,fileinput.FileInput}, deprecated since Python 3.9.
(Contributed by Hugo van Kemenade in bpo-45132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45132}.)

@item 
Removed the deprecated @ref{62,,gettext} functions
@code{lgettext()}, @code{ldgettext()},
@code{lngettext()} and @code{ldngettext()}.
Also removed the @code{bind_textdomain_codeset()} function,
the @code{NullTranslations.output_charset()} and
@code{NullTranslations.set_output_charset()} methods,
and the `codeset' parameter of @code{translation()} and @code{install()},
since they are only used for the @code{l*gettext()} functions.
(Contributed by Donghee Na and Serhiy Storchaka in bpo-44235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44235}.)

@item 
Removed from the @ref{7d,,inspect} module:


@itemize *

@item 
The @code{getargspec()} function, deprecated since Python 3.0;
use @ref{722,,inspect.signature()} or @ref{723,,inspect.getfullargspec()} instead.

@item 
The @code{formatargspec()} function, deprecated since Python 3.5;
use the @ref{722,,inspect.signature()} function
or the @ref{1ca,,inspect.Signature} object directly.

@item 
The undocumented @code{Signature.from_builtin()}
and @code{Signature.from_function()} methods, deprecated since Python 3.5;
use the @ref{724,,Signature.from_callable()}
method instead.
@end itemize

(Contributed by Hugo van Kemenade in bpo-45320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45320}.)

@item 
Removed the @ref{725,,__class_getitem__()} method
from @ref{490,,pathlib.PurePath},
because it was not used and added by mistake in previous versions.
(Contributed by Nikita Sobolev in bpo-46483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46483}.)

@item 
Removed the @code{MailmanProxy} class in the @code{smtpd} module,
as it is unusable without the external @code{mailman} package.
(Contributed by Donghee Na in bpo-35800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35800}.)

@item 
Removed the deprecated @code{split()} method of @code{_tkinter.TkappType}.
(Contributed by Erlend E. Aasland in bpo-38371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38371}.)

@item 
Removed namespace package support from @ref{105,,unittest} discovery.
It was introduced in Python 3.4 but has been broken since Python 3.7.
(Contributed by Inada Naoki in bpo-23882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23882}.)

@item 
Removed the undocumented private @code{float.__set_format__()} method,
previously known as @code{float.__setformat__()} in Python 3.7.
Its docstring said: "You probably don't want to use this function.
It exists mainly to be used in Python's test suite."
(Contributed by Victor Stinner in bpo-46852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46852}.)

@item 
The @code{--experimental-isolated-subinterpreters} configure flag
(and corresponding @code{EXPERIMENTAL_ISOLATED_SUBINTERPRETERS} macro)
have been removed.

@item 
Pynche@footnote{https://pypi.org/project/Pynche/}
--- The Pythonically Natural Color and Hue Editor --- has been moved out
of @code{Tools/scripts} and is being developed independently@footnote{https://gitlab.com/warsaw/pynche/-/tree/main} from the Python source tree.
@end itemize
@anchor{whatsnew/3 11 whatsnew311-porting}@anchor{726}
@node Portage vers Python 3 11,Changements à la compilation<3>,Retraits<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 porting-to-python-3-11}@anchor{727}@anchor{whatsnew/3 11 whatsnew311-python-api-porting}@anchor{728}
@subsection Portage vers Python 3.11


Cette section liste les modifications précédemment décrites et d'autres corrections de bogues dans l'API Python qui pourraient nécessiter des modifications dans votre code.

Porting notes for the C API are
@ref{729,,listed separately}.


@itemize *

@item 
@ref{505,,open()}, @ref{506,,io.open()}, @ref{72a,,codecs.open()} and
@ref{721,,fileinput.FileInput} no longer accept @code{'U'} ("universal newline")
in the file mode. In Python 3, "universal newline" mode is used by default
whenever a file is opened in text mode,
and the @code{'U'} flag has been deprecated since Python 3.3.
The @ref{72b,,newline parameter}
to these functions controls how universal newlines work.
(Contributed by Victor Stinner in bpo-37330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37330}.)

@item 
@ref{1a4,,ast.AST} node positions are now validated when provided to
@ref{190,,compile()} and other related functions. If invalid positions are detected,
a @ref{1ff,,ValueError} will be raised. (Contributed by Pablo Galindo in gh-93351@footnote{https://github.com/python/cpython/issues/93351})

@item 
Prohibited passing non-@ref{72c,,concurrent.futures.ThreadPoolExecutor}
executors to @ref{72d,,asyncio.loop.set_default_executor()}
following a deprecation in Python 3.8.
(Contributed by Illia Volochii in bpo-43234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43234}.)

@item 
@ref{14,,calendar}: The @ref{72e,,calendar.LocaleTextCalendar} and
@ref{72f,,calendar.LocaleHTMLCalendar} classes now use
@ref{2d9,,locale.getlocale()}, instead of using @ref{2d8,,locale.getdefaultlocale()},
if no locale is specified.
(Contributed by Victor Stinner in bpo-46659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46659}.)

@item 
The @ref{a4,,pdb} module now reads the @code{.pdbrc} configuration file with
the @code{'UTF-8'} encoding.
(Contributed by Srinivas Reddy Thatiparthy (శ్రీనివాస్  రెడ్డి తాటిపర్తి) in bpo-41137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41137}.)

@item 
The `population' parameter of @ref{730,,random.sample()} must be a sequence,
and automatic conversion of @ref{5c3,,set}s to @ref{5fc,,list}s
is no longer supported. Also, if the sample size
is larger than the population size, a @ref{1ff,,ValueError} is raised.
(Contributed by Raymond Hettinger in bpo-40465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40465}.)

@item 
The `random' optional parameter of @ref{731,,random.shuffle()} was removed.
It was previously an arbitrary random function to use for the shuffle;
now, @ref{732,,random.random()} (its previous default) will always be used.

@item 
In @ref{b8,,re} @ref{70e,,Syntaxe des expressions rationnelles}, global inline flags (e.g. @code{(?i)})
can now only be used at the start of regular expressions.
Using them elsewhere has been deprecated since Python 3.6.
(Contributed by Serhiy Storchaka in bpo-47066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47066}.)

@item 
In the @ref{b8,,re} module, several long-standing bugs where fixed that,
in rare cases, could cause capture groups to get the wrong result.
Therefore, this could change the captured output in these cases.
(Contributed by Ma Lin in bpo-35859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35859}.)
@end itemize

@node Changements à la compilation<3>,Changements à l'API C<3>,Portage vers Python 3 11,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 build-changes}@anchor{733}@anchor{whatsnew/3 11 whatsnew311-build-changes}@anchor{734}
@subsection Changements à la compilation



@itemize *

@item 
CPython now has 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} 
@geindex Python Enhancement Proposals; PEP 11#tier-3
Tier 3 support@footnote{https://peps.python.org/pep-0011/#tier-3} for
cross compiling to the WebAssembly@footnote{https://webassembly.org/} platforms
Emscripten@footnote{https://emscripten.org/}
(@code{wasm32-unknown-emscripten}, i.e. Python in the browser)
and WebAssembly System Interface (WASI)@footnote{https://wasi.dev/}
(@code{wasm32-unknown-wasi}).
The effort is inspired by previous work like Pyodide@footnote{https://pyodide.org/}.
These platforms provide a limited subset of POSIX APIs; Python standard
libraries features and modules related to networking, processes, threading,
signals, mmap, and users/groups are not available or don't work.
(Emscripten contributed by Christian Heimes and Ethan Smith in gh-84461@footnote{https://github.com/python/cpython/issues/84461}
and WASI contributed by Christian Heimes in gh-90473@footnote{https://github.com/python/cpython/issues/90473};
platforms promoted in gh-95085@footnote{https://github.com/python/cpython/issues/95085})

@item 
Building CPython now requires:


@itemize *

@item 
A C11@footnote{https://en.cppreference.com/w/c/11} compiler and standard library.
Optional C11 features@footnote{https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features}
are not required.
(Contributed by Victor Stinner in bpo-46656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46656},
bpo-45440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45440} and bpo-46640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46640}.)

@item 
Support for IEEE 754@footnote{https://en.wikipedia.org/wiki/IEEE_754}
floating-point numbers.
(Contributed by Victor Stinner in bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917}.)
@end itemize

@item 
The @code{Py_NO_NAN} macro has been removed.
Since CPython now requires IEEE 754 floats, NaN values are always available.
(Contributed by Victor Stinner in bpo-46656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46656}.)

@item 
The @ref{ef,,tkinter} package now requires Tcl/Tk@footnote{https://www.tcl.tk}
version 8.5.12 or newer.
(Contributed by Serhiy Storchaka in bpo-46996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46996}.)

@item 
Build dependencies, compiler flags, and linker flags for most stdlib
extension modules are now detected by @code{configure}. libffi, libnsl,
libsqlite3, zlib, bzip2, liblzma, libcrypt, Tcl/Tk, and uuid flags
are detected by pkg-config@footnote{https://www.freedesktop.org/wiki/Software/pkg-config/} (when available).
@ref{ef,,tkinter} now requires a pkg-config command
to detect development settings for Tcl/Tk@footnote{https://www.tcl.tk} headers and libraries.
(Contributed by Christian Heimes and Erlend Egeberg Aasland in
bpo-45847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45847}, bpo-45747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45747}, and bpo-45763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45763}.)

@item 
libpython is no longer linked against libcrypt.
(Contributed by Mike Gilbert in bpo-45433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45433}.)

@item 
CPython can now be built with the
ThinLTO@footnote{https://clang.llvm.org/docs/ThinLTO.html} option
via passing @code{thin} to @ref{735,,--with-lto}, i.e. @code{--with-lto=thin}.
(Contributed by Donghee Na and Brett Holman in bpo-44340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44340}.)

@item 
Freelists for object structs can now be disabled. A new @code{configure}
option @ref{736,,--without-freelists} can be used to disable all freelists
except empty tuple singleton.
(Contributed by Christian Heimes in bpo-45522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45522}.)

@item 
@code{Modules/Setup} and @code{Modules/makesetup} have been improved and tied up.
Extension modules can now be built through @code{makesetup}. All except some
test modules can be linked statically into a main binary or library.
(Contributed by Brett Cannon and Christian Heimes in bpo-45548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45548},
bpo-45570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45570}, bpo-45571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45571}, and bpo-43974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43974}.)

@cartouche
@quotation Note 
Use the environment variables @code{TCLTK_CFLAGS} and
@code{TCLTK_LIBS} to manually specify the location of Tcl/Tk headers
and libraries. The @code{configure} options
@code{--with-tcltk-includes} and @code{--with-tcltk-libs}
have been removed.

On RHEL 7 and CentOS 7 the development packages do not provide @code{tcl.pc}
and @code{tk.pc}; use @code{TCLTK_LIBS="-ltk8.5 -ltkstub8.5 -ltcl8.5"}.
The directory @code{Misc/rhel7} contains @code{.pc} files and instructions
on how to build Python with RHEL 7's and CentOS 7's Tcl/Tk and OpenSSL.
@end quotation
@end cartouche

@item 
CPython will now use 30-bit digits by default for the Python @ref{254,,int}
implementation. Previously, the default was to use 30-bit digits on platforms
with @code{SIZEOF_VOID_P >= 8}, and 15-bit digits otherwise. It's still possible
to explicitly request use of 15-bit digits via either the
@ref{737,,--enable-big-digits} option to the configure script
or (for Windows) the @code{PYLONG_BITS_IN_DIGIT} variable in @code{PC/pyconfig.h},
but this option may be removed at some point in the future.
(Contributed by Mark Dickinson in bpo-45569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45569}.)
@end itemize

@node Changements à l'API C<3>,Notable changes in 3 11 4,Changements à la compilation<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 c-api-changes}@anchor{738}@anchor{whatsnew/3 11 whatsnew311-c-api}@anchor{739}
@subsection Changements à l'API C


@menu
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<6>. 
* Portage vers Python 3.11: Portage vers Python 3 11<2>. 
* Obsolescence: Obsolescence<4>. 
* Pending Removal in Python 3.12: Pending Removal in Python 3 12<2>. 
* Retraits: Retraits<4>. 

@end menu

@node Nouvelles fonctionnalités<6>,Portage vers Python 3 11<2>,,Changements à l'API C<3>
@anchor{whatsnew/3 11 id5}@anchor{73a}@anchor{whatsnew/3 11 whatsnew311-c-api-new-features}@anchor{73b}
@subsubsection Nouvelles fonctionnalités



@itemize *

@item 
Add a new @ref{73c,,PyType_GetName()} function to get type's short name.
(Contributed by Hai Shi in bpo-42035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42035}.)

@item 
Add a new @ref{73d,,PyType_GetQualName()} function to get type's qualified name.
(Contributed by Hai Shi in bpo-42035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42035}.)

@item 
Add new @ref{73e,,PyThreadState_EnterTracing()} and
@ref{73f,,PyThreadState_LeaveTracing()} functions to the limited C API to
suspend and resume tracing and profiling.
(Contributed by Victor Stinner in bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760}.)

@item 
Added the @ref{740,,Py_Version} constant which bears the same value as
@ref{741,,PY_VERSION_HEX}.
(Contributed by  Gabriele N. Tornetta in bpo-43931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43931}.)

@item 
@ref{742,,Py_buffer} and APIs are now part of the limited API and the stable
ABI:


@itemize *

@item 
@ref{38f,,PyObject_CheckBuffer()}

@item 
@ref{390,,PyObject_GetBuffer()}

@item 
@ref{743,,PyBuffer_GetPointer()}

@item 
@ref{744,,PyBuffer_SizeFromFormat()}

@item 
@ref{745,,PyBuffer_ToContiguous()}

@item 
@ref{746,,PyBuffer_FromContiguous()}

@item 
@ref{747,,PyObject_CopyData()}

@item 
@ref{748,,PyBuffer_IsContiguous()}

@item 
@ref{749,,PyBuffer_FillContiguousStrides()}

@item 
@ref{74a,,PyBuffer_FillInfo()}

@item 
@ref{391,,PyBuffer_Release()}

@item 
@ref{74b,,PyMemoryView_FromBuffer()}

@item 
@ref{74c,,bf_getbuffer} and
@ref{74d,,bf_releasebuffer} type slots
@end itemize

(Contributed by Christian Heimes in bpo-45459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45459}.)

@item 
Added the @ref{38a,,PyType_GetModuleByDef()} function, used to get the module
in which a method was defined, in cases where this information is not
available directly (via @ref{74e,,PyCMethod}).
(Contributed by Petr Viktorin in bpo-46613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46613}.)

@item 
Add new functions to pack and unpack C double (serialize and deserialize):
@ref{74f,,PyFloat_Pack2()}, @ref{750,,PyFloat_Pack4()}, @ref{751,,PyFloat_Pack8()},
@ref{752,,PyFloat_Unpack2()}, @ref{753,,PyFloat_Unpack4()} and
@ref{754,,PyFloat_Unpack8()}.
(Contributed by Victor Stinner in bpo-46906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46906}.)

@item 
Add new functions to get frame object attributes:
@ref{755,,PyFrame_GetBuiltins()}, @ref{756,,PyFrame_GetGenerator()},
@ref{757,,PyFrame_GetGlobals()}, @ref{758,,PyFrame_GetLasti()}.

@item 
Added two new functions to get and set the active exception instance:
@ref{759,,PyErr_GetHandledException()} and @ref{75a,,PyErr_SetHandledException()}.
These are alternatives to @ref{75b,,PyErr_SetExcInfo()} and
@ref{75c,,PyErr_GetExcInfo()} which work with the legacy 3-tuple
representation of exceptions.
(Contributed by Irit Katriel in bpo-46343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46343}.)

@item 
Added the @ref{75d,,PyConfig.safe_path} member.
(Contributed by Victor Stinner in gh-57684@footnote{https://github.com/python/cpython/issues/57684}.)
@end itemize

@node Portage vers Python 3 11<2>,Obsolescence<4>,Nouvelles fonctionnalités<6>,Changements à l'API C<3>
@anchor{whatsnew/3 11 id6}@anchor{75e}@anchor{whatsnew/3 11 whatsnew311-c-api-porting}@anchor{729}
@subsubsection Portage vers Python 3.11

@anchor{whatsnew/3 11 whatsnew311-pep670}@anchor{598}

@itemize *

@item 
Some macros have been converted to static inline functions to avoid
macro pitfalls@footnote{https://gcc.gnu.org/onlinedocs/cpp/Macro-Pitfalls.html}.
The change should be mostly transparent to users,
as the replacement functions will cast their arguments to the expected types
to avoid compiler warnings due to static type checks.
However, when the limited C API is set to >=3.11,
these casts are not done,
and callers will need to cast arguments to their expected types.
See 
@geindex Python Enhancement Proposals; PEP 670
PEP 670@footnote{https://peps.python.org/pep-0670/} for more details.
(Contributed by Victor Stinner and Erlend E. Aasland in gh-89653@footnote{https://github.com/python/cpython/issues/89653}.)

@item 
@ref{75b,,PyErr_SetExcInfo()} no longer uses the @code{type} and @code{traceback}
arguments, the interpreter now derives those values from the exception
instance (the @code{value} argument). The function still steals references
of all three arguments.
(Contributed by Irit Katriel in bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}.)

@item 
@ref{75c,,PyErr_GetExcInfo()} now derives the @code{type} and @code{traceback}
fields of the result from the exception instance (the @code{value} field).
(Contributed by Irit Katriel in bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}.)

@item 
@ref{75f,,_frozen} has a new @code{is_package} field to indicate whether
or not the frozen module is a package.  Previously, a negative value
in the @code{size} field was the indicator.  Now only non-negative values
be used for @code{size}.
(Contributed by Kumar Aditya in bpo-46608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46608}.)

@item 
@ref{760,,_PyFrameEvalFunction()} now takes @code{_PyInterpreterFrame*}
as its second parameter, instead of @code{PyFrameObject*}.
See 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} for more details of how to use this function pointer type.

@item 
@code{PyCode_New()} and @code{PyCode_NewWithPosOnlyArgs()} now take
an additional @code{exception_table} argument.
Using these functions should be avoided, if at all possible.
To get a custom code object: create a code object using the compiler,
then get a modified version with the @code{replace} method.

@item 
@ref{761,,PyCodeObject} no longer has the @code{co_code}, @code{co_varnames},
@code{co_cellvars} and @code{co_freevars} fields.  Instead, use
@ref{762,,PyCode_GetCode()}, @ref{763,,PyCode_GetVarnames()},
@ref{764,,PyCode_GetCellvars()} and @ref{765,,PyCode_GetFreevars()} respectively
to access them via the C API.
(Contributed by Brandt Bucher in bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841} and Ken Jin in gh-92154@footnote{https://github.com/python/cpython/issues/92154}
and gh-94936@footnote{https://github.com/python/cpython/issues/94936}.)

@item 
The old trashcan macros (@code{Py_TRASHCAN_SAFE_BEGIN}/@code{Py_TRASHCAN_SAFE_END})
are now deprecated. They should be replaced by the new macros
@code{Py_TRASHCAN_BEGIN} and @code{Py_TRASHCAN_END}.

A tp_dealloc function that has the old macros, such as:

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_SAFE_BEGIN(p);
    ...
    Py_TRASHCAN_SAFE_END
@}
@end example

should migrate to the new macros as follows:

@example
static void
mytype_dealloc(mytype *p)
@{
    PyObject_GC_UnTrack(p);
    Py_TRASHCAN_BEGIN(p, mytype_dealloc)
    ...
    Py_TRASHCAN_END
@}
@end example

Note that @code{Py_TRASHCAN_BEGIN} has a second argument which
should be the deallocation function it is in.

To support older Python versions in the same codebase, you
can define the following macros and use them throughout
the code (credit: these were copied from the @code{mypy} codebase):

@example
#if PY_VERSION_HEX >= 0x03080000
#  define CPy_TRASHCAN_BEGIN(op, dealloc) Py_TRASHCAN_BEGIN(op, dealloc)
#  define CPy_TRASHCAN_END(op) Py_TRASHCAN_END
#else
#  define CPy_TRASHCAN_BEGIN(op, dealloc) Py_TRASHCAN_SAFE_BEGIN(op)
#  define CPy_TRASHCAN_END(op) Py_TRASHCAN_SAFE_END(op)
#endif
@end example

@item 
The @ref{766,,PyType_Ready()} function now raises an error if a type is defined
with the @ref{767,,Py_TPFLAGS_HAVE_GC} flag set but has no traverse function
(@ref{768,,PyTypeObject.tp_traverse}).
(Contributed by Victor Stinner in bpo-44263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44263}.)

@item 
Heap types with the @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} flag can now inherit
the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} vectorcall protocol.  Previously, this was only possible for
@ref{769,,static types}.
(Contributed by Erlend E. Aasland in bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908})

@item 
Since @ref{76a,,Py_TYPE()} is changed to a inline static function,
@code{Py_TYPE(obj) = new_type} must be replaced with
@code{Py_SET_TYPE(obj, new_type)}: see the @ref{76b,,Py_SET_TYPE()} function
(available since Python 3.9). For backward compatibility, this macro can be
used:

@example
#if PY_VERSION_HEX < 0x030900A4 && !defined(Py_SET_TYPE)
static inline void _Py_SET_TYPE(PyObject *ob, PyTypeObject *type)
@{ ob->ob_type = type; @}
#define Py_SET_TYPE(ob, type) _Py_SET_TYPE((PyObject*)(ob), type)
#endif
@end example

(contribution de `Victor Stinner' dans bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}).

@item 
Since @ref{76c,,Py_SIZE()} is changed to a inline static function,
@code{Py_SIZE(obj) = new_size} must be replaced with
@code{Py_SET_SIZE(obj, new_size)}: see the @ref{76d,,Py_SET_SIZE()} function
(available since Python 3.9). For backward compatibility, this macro can be
used:

@example
#if PY_VERSION_HEX < 0x030900A4 && !defined(Py_SET_SIZE)
static inline void _Py_SET_SIZE(PyVarObject *ob, Py_ssize_t size)
@{ ob->ob_size = size; @}
#define Py_SET_SIZE(ob, size) _Py_SET_SIZE((PyVarObject*)(ob), size)
#endif
@end example

(contribution de `Victor Stinner' dans bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}).

@item 
@code{<Python.h>} no longer includes the header files @code{<stdlib.h>},
@code{<stdio.h>}, @code{<errno.h>} and @code{<string.h>} when the @code{Py_LIMITED_API}
macro is set to @code{0x030b0000} (Python 3.11) or higher. C extensions should
explicitly include the header files after @code{#include <Python.h>}.
(Contributed by Victor Stinner in bpo-45434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45434}.)

@item 
The non-limited API files @code{cellobject.h}, @code{classobject.h}, @code{code.h}, @code{context.h},
@code{funcobject.h}, @code{genobject.h} and @code{longintrepr.h} have been moved to
the @code{Include/cpython} directory. Moreover, the @code{eval.h} header file was
removed. These files must not be included directly, as they are already
included in @code{Python.h}: @ref{76e,,Include Files}. If they have
been included directly, consider including @code{Python.h} instead.
(Contributed by Victor Stinner in bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}.)

@item 
The @code{PyUnicode_CHECK_INTERNED()} macro has been excluded from the
limited C API. It was never usable there, because it used internal structures
which are not available in the limited C API.
(Contributed by Victor Stinner in bpo-46007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46007}.)

@item 
The following frame functions and type are now directly available with
@code{#include <Python.h>}, it's no longer needed to add
@code{#include <frameobject.h>}:


@itemize *

@item 
@ref{76f,,PyFrame_Check()}

@item 
@ref{770,,PyFrame_GetBack()}

@item 
@ref{755,,PyFrame_GetBuiltins()}

@item 
@ref{756,,PyFrame_GetGenerator()}

@item 
@ref{757,,PyFrame_GetGlobals()}

@item 
@ref{758,,PyFrame_GetLasti()}

@item 
@ref{415,,PyFrame_GetLocals()}

@item 
@ref{771,,PyFrame_Type}
@end itemize

(Contributed by Victor Stinner in gh-93937@footnote{https://github.com/python/cpython/issues/93937}.)
@end itemize
@anchor{whatsnew/3 11 pyframeobject-3-11-hiding}@anchor{772}

@itemize *

@item 
The @ref{773,,PyFrameObject} structure members have been removed from the
public C API.

While the documentation notes that the @ref{773,,PyFrameObject} fields are
subject to change at any time, they have been stable for a long time and were
used in several popular extensions.

In Python 3.11, the frame struct was reorganized to allow performance
optimizations. Some fields were removed entirely, as they were details of the
old implementation.

@ref{773,,PyFrameObject} fields:


@itemize *

@item 
@code{f_back}: use @ref{770,,PyFrame_GetBack()}.

@item 
@code{f_blockstack}: removed.

@item 
@code{f_builtins}: use @ref{755,,PyFrame_GetBuiltins()}.

@item 
@code{f_code}: use @ref{774,,PyFrame_GetCode()}.

@item 
@code{f_gen}: use @ref{756,,PyFrame_GetGenerator()}.

@item 
@code{f_globals}: use @ref{757,,PyFrame_GetGlobals()}.

@item 
@code{f_iblock}: removed.

@item 
@code{f_lasti}: use @ref{758,,PyFrame_GetLasti()}.
Code using @code{f_lasti} with @code{PyCode_Addr2Line()} should use
@ref{775,,PyFrame_GetLineNumber()} instead; it may be faster.

@item 
@code{f_lineno}: use @ref{775,,PyFrame_GetLineNumber()}

@item 
@code{f_locals}: use @ref{415,,PyFrame_GetLocals()}.

@item 
@code{f_stackdepth}: removed.

@item 
@code{f_state}: no public API (renamed to @code{f_frame.f_state}).

@item 
@code{f_trace}: no public API.

@item 
@code{f_trace_lines}: use @code{PyObject_GetAttrString((PyObject*)frame, "f_trace_lines")}.

@item 
@code{f_trace_opcodes}: use @code{PyObject_GetAttrString((PyObject*)frame, "f_trace_opcodes")}.

@item 
@code{f_localsplus}: no public API (renamed to @code{f_frame.localsplus}).

@item 
@code{f_valuestack}: removed.
@end itemize

The Python frame object is now created lazily. A side effect is that the
@ref{776,,f_back} member must not be accessed directly,
since its value is now also
computed lazily. The @ref{770,,PyFrame_GetBack()} function must be called
instead.

Debuggers that accessed the @ref{180,,f_locals} directly `must' call
@ref{415,,PyFrame_GetLocals()} instead. They no longer need to call
@code{PyFrame_FastToLocalsWithError()} or @code{PyFrame_LocalsToFast()},
in fact they should not call those functions. The necessary updating of the
frame is now managed by the virtual machine.

Code defining @code{PyFrame_GetCode()} on Python 3.8 and older:

@example
#if PY_VERSION_HEX < 0x030900B1
static inline PyCodeObject* PyFrame_GetCode(PyFrameObject *frame)
@{
    Py_INCREF(frame->f_code);
    return frame->f_code;
@}
#endif
@end example

Code defining @code{PyFrame_GetBack()} on Python 3.8 and older:

@example
#if PY_VERSION_HEX < 0x030900B1
static inline PyFrameObject* PyFrame_GetBack(PyFrameObject *frame)
@{
    Py_XINCREF(frame->f_back);
    return frame->f_back;
@}
#endif
@end example

Or use the pythoncapi_compat project@footnote{https://github.com/python/pythoncapi-compat} to get these two
functions on older Python versions.

@item 
Changes of the @ref{777,,PyThreadState} structure members:


@itemize *

@item 
@code{frame}: removed, use @ref{778,,PyThreadState_GetFrame()} (function added
to Python 3.9 by bpo-40429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40429}).
Warning: the function returns a @ref{333,,strong reference}, need to call
@ref{779,,Py_XDECREF()}.

@item 
@code{tracing}: changed, use @ref{73e,,PyThreadState_EnterTracing()}
and @ref{73f,,PyThreadState_LeaveTracing()}
(functions added to Python 3.11 by bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760}).

@item 
@code{recursion_depth}: removed,
use @code{(tstate->recursion_limit - tstate->recursion_remaining)} instead.

@item 
@code{stackcheck_counter}: removed.
@end itemize

Code defining @code{PyThreadState_GetFrame()} on Python 3.8 and older:

@example
#if PY_VERSION_HEX < 0x030900B1
static inline PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
@{
    Py_XINCREF(tstate->frame);
    return tstate->frame;
@}
#endif
@end example

Code defining @code{PyThreadState_EnterTracing()} and
@code{PyThreadState_LeaveTracing()} on Python 3.10 and older:

@example
#if PY_VERSION_HEX < 0x030B00A2
static inline void PyThreadState_EnterTracing(PyThreadState *tstate)
@{
    tstate->tracing++;
#if PY_VERSION_HEX >= 0x030A00A1
    tstate->cframe->use_tracing = 0;
#else
    tstate->use_tracing = 0;
#endif
@}

static inline void PyThreadState_LeaveTracing(PyThreadState *tstate)
@{
    int use_tracing = (tstate->c_tracefunc != NULL || tstate->c_profilefunc != NULL);
    tstate->tracing--;
#if PY_VERSION_HEX >= 0x030A00A1
    tstate->cframe->use_tracing = use_tracing;
#else
    tstate->use_tracing = use_tracing;
#endif
@}
#endif
@end example

Or use the pythoncapi-compat project@footnote{https://github.com/python/pythoncapi-compat} to get these functions
on old Python functions.

@item 
Distributors are encouraged to build Python with the optimized Blake2
library libb2@footnote{https://www.blake2.net/}.

@item 
The @ref{5d9,,PyConfig.module_search_paths_set} field must now be set to 1 for
initialization to use @ref{399,,PyConfig.module_search_paths} to initialize
@ref{3ab,,sys.path}. Otherwise, initialization will recalculate the path and replace
any values added to @code{module_search_paths}.

@item 
@ref{77a,,PyConfig_Read()} no longer calculates the initial search path, and will not
fill any values into @ref{399,,PyConfig.module_search_paths}. To calculate default
paths and then modify them, finish initialization and use @ref{37f,,PySys_GetObject()}
to retrieve @ref{3ab,,sys.path} as a Python list object and modify it directly.
@end itemize

@node Obsolescence<4>,Pending Removal in Python 3 12<2>,Portage vers Python 3 11<2>,Changements à l'API C<3>
@anchor{whatsnew/3 11 id7}@anchor{77b}@anchor{whatsnew/3 11 whatsnew311-c-api-deprecated}@anchor{701}
@subsubsection Obsolescence



@itemize *

@item 
Deprecate the following functions to configure the Python initialization:


@itemize *

@item 
@code{PySys_AddWarnOptionUnicode()}

@item 
@code{PySys_AddWarnOption()}

@item 
@code{PySys_AddXOption()}

@item 
@code{PySys_HasWarnOptions()}

@item 
@code{PySys_SetArgvEx()}

@item 
@code{PySys_SetArgv()}

@item 
@code{PySys_SetPath()}

@item 
@code{Py_SetPath()}

@item 
@code{Py_SetProgramName()}

@item 
@code{Py_SetPythonHome()}

@item 
@code{Py_SetStandardStreamEncoding()}

@item 
@code{_Py_SetProgramFullPath()}
@end itemize

Use the new @ref{39d,,PyConfig} API of the @ref{39e,,Python Initialization Configuration} instead (
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}).
(Contributed by Victor Stinner in gh-88279@footnote{https://github.com/python/cpython/issues/88279}.)

@item 
Deprecate the @code{ob_shash} member of the @ref{77c,,PyBytesObject}. Use @ref{3f9,,PyObject_Hash()} instead.
(Contributed by Inada Naoki in bpo-46864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46864}.)
@end itemize

@node Pending Removal in Python 3 12<2>,Retraits<4>,Obsolescence<4>,Changements à l'API C<3>
@anchor{whatsnew/3 11 id8}@anchor{77d}@anchor{whatsnew/3 11 whatsnew311-c-api-pending-removal}@anchor{713}
@subsubsection Pending Removal in Python 3.12


The following C APIs have been deprecated in earlier Python releases,
and will be removed in Python 3.12.


@itemize *

@item 
@code{PyUnicode_AS_DATA()}

@item 
@code{PyUnicode_AS_UNICODE()}

@item 
@code{PyUnicode_AsUnicodeAndSize()}

@item 
@code{PyUnicode_AsUnicode()}

@item 
@code{PyUnicode_FromUnicode()}

@item 
@code{PyUnicode_GET_DATA_SIZE()}

@item 
@code{PyUnicode_GET_SIZE()}

@item 
@code{PyUnicode_GetSize()}

@item 
@code{PyUnicode_IS_COMPACT()}

@item 
@code{PyUnicode_IS_READY()}

@item 
@ref{3f7,,PyUnicode_READY()}

@item 
@code{PyUnicode_WSTR_LENGTH()}

@item 
@code{_PyUnicode_AsUnicode()}

@item 
@code{PyUnicode_WCHAR_KIND}

@item 
@ref{77e,,PyUnicodeObject}

@item 
@code{PyUnicode_InternImmortal()}
@end itemize

@node Retraits<4>,,Pending Removal in Python 3 12<2>,Changements à l'API C<3>
@anchor{whatsnew/3 11 id9}@anchor{77f}@anchor{whatsnew/3 11 whatsnew311-c-api-removed}@anchor{71a}
@subsubsection Retraits



@itemize *

@item 
@code{PyFrame_BlockSetup()} and @code{PyFrame_BlockPop()} have been
removed.
(Contributed by Mark Shannon in bpo-40222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40222}.)

@item 
Remove the following math macros using the @code{errno} variable:


@itemize *

@item 
@code{Py_ADJUST_ERANGE1()}

@item 
@code{Py_ADJUST_ERANGE2()}

@item 
@code{Py_OVERFLOWED()}

@item 
@code{Py_SET_ERANGE_IF_OVERFLOW()}

@item 
@code{Py_SET_ERRNO_ON_MATH_ERROR()}
@end itemize

(Contributed by Victor Stinner in bpo-45412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45412}.)

@item 
Remove @code{Py_UNICODE_COPY()} and @code{Py_UNICODE_FILL()} macros, deprecated
since Python 3.3. Use @code{PyUnicode_CopyCharacters()} or @code{memcpy()}
(@code{wchar_t*} string), and @code{PyUnicode_Fill()} functions instead.
(Contributed by Victor Stinner in bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}.)

@item 
Remove the @code{pystrhex.h} header file. It only contains private functions.
C extensions should only include the main @code{<Python.h>} header file.
(Contributed by Victor Stinner in bpo-45434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45434}.)

@item 
Remove the @code{Py_FORCE_DOUBLE()} macro. It was used by the
@code{Py_IS_INFINITY()} macro.
(Contributed by Victor Stinner in bpo-45440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45440}.)

@item 
The following items are no longer available when @ref{414,,Py_LIMITED_API}
is defined:


@itemize *

@item 
@ref{780,,PyMarshal_WriteLongToFile()}

@item 
@ref{781,,PyMarshal_WriteObjectToFile()}

@item 
@ref{782,,PyMarshal_ReadObjectFromString()}

@item 
@ref{783,,PyMarshal_WriteObjectToString()}

@item 
the @code{Py_MARSHAL_VERSION} macro
@end itemize

These are not part of the @ref{784,,limited API}.

(Contributed by Victor Stinner in bpo-45474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45474}.)

@item 
Exclude @ref{3b6,,PyWeakref_GET_OBJECT()} from the limited C API. It never
worked since the @code{PyWeakReference} structure is opaque in the
limited C API.
(Contributed by Victor Stinner in bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}.)

@item 
Remove the @code{PyHeapType_GET_MEMBERS()} macro. It was exposed in the
public C API by mistake, it must only be used by Python internally.
Use the @code{PyTypeObject.tp_members} member instead.
(Contributed by Victor Stinner in bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}.)

@item 
Remove the @code{HAVE_PY_SET_53BIT_PRECISION} macro (moved to the internal C
API).
(Contributed by Victor Stinner in bpo-45412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45412}.)
@end itemize
@anchor{whatsnew/3 11 whatsnew311-pep624}@anchor{597}

@itemize *

@item 
Remove the @ref{3e4,,Py_UNICODE} encoder APIs,
as they have been deprecated since Python 3.3,
are little used
and are inefficient relative to the recommended alternatives.

The removed functions are:


@itemize *

@item 
@code{PyUnicode_Encode()}

@item 
@code{PyUnicode_EncodeASCII()}

@item 
@code{PyUnicode_EncodeLatin1()}

@item 
@code{PyUnicode_EncodeUTF7()}

@item 
@code{PyUnicode_EncodeUTF8()}

@item 
@code{PyUnicode_EncodeUTF16()}

@item 
@code{PyUnicode_EncodeUTF32()}

@item 
@code{PyUnicode_EncodeUnicodeEscape()}

@item 
@code{PyUnicode_EncodeRawUnicodeEscape()}

@item 
@code{PyUnicode_EncodeCharmap()}

@item 
@code{PyUnicode_TranslateCharmap()}

@item 
@code{PyUnicode_EncodeDecimal()}

@item 
@code{PyUnicode_TransformDecimalToASCII()}
@end itemize

See 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/} for details and
@geindex Python Enhancement Proposals; PEP 624#alternative-apis
migration guidance@footnote{https://peps.python.org/pep-0624/#alternative-apis}.
(Contributed by Inada Naoki in bpo-44029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44029}.)
@end itemize

@node Notable changes in 3 11 4,Notable changes in 3 11 5,Changements à l'API C<3>,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 notable-changes-in-3-11-4}@anchor{785}
@subsection Notable changes in 3.11.4


@menu
* tarfile:: 

@end menu

@node tarfile,,,Notable changes in 3 11 4
@anchor{whatsnew/3 11 tarfile}@anchor{786}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{dd,,tarfile}, and @ref{455,,shutil.unpack_archive()},
have a new a `filter' argument that allows limiting tar features than may be
surprising or dangerous, such as creating files outside the destination
directory.
See @ref{456,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@node Notable changes in 3 11 5,,Notable changes in 3 11 4,Les nouveautés de Python 3 11
@anchor{whatsnew/3 11 notable-changes-in-3-11-5}@anchor{787}
@subsection Notable changes in 3.11.5


@menu
* OpenSSL:: 

@end menu

@node OpenSSL,,,Notable changes in 3 11 5
@anchor{whatsnew/3 11 openssl}@anchor{788}
@subsubsection OpenSSL



@itemize *

@item 
Windows builds and macOS installers from python.org now use OpenSSL 3.0.
@end itemize

@node Les nouveautés de Python 3 10,Les nouveautés de Python 3 9,Les nouveautés de Python 3 11,Nouveautés de Python
@anchor{whatsnew/3 10 doc}@anchor{789}@anchor{whatsnew/3 10 what-s-new-in-python-3-10}@anchor{78a}
@section Les nouveautés de Python 3.10


@*Rédacteur: 
`Pablo Galindo Salgado'


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the git log
@c when researching a change.

This article explains the new features in Python 3.10, compared to 3.9.
Python 3.10 was released on October 4, 2021.
For full details, see the @ref{13b,,changelog}.

@menu
* Résumé – Points forts de la publication: Résumé – Points forts de la publication<2>. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<7>. 
* Nouvelles fonctionnalités reliées aux indications de types: Nouvelles fonctionnalités reliées aux indications de types<3>. 
* Autres changements au langage: Autres changements au langage<4>. 
* Nouveaux modules: Nouveaux modules<4>. 
* Modules améliorés: Modules améliorés<4>. 
* Optimisations: Optimisations<4>. 
* Obsolescence: Obsolescence<5>. 
* Retrait:: 
* Portage vers Python 3.10: Portage vers Python 3 10. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<3>. 
* Changements à la compilation: Changements à la compilation<4>. 
* Changements à l'API C: Changements à l'API C<4>. 
* Notable security feature in 3.10.7: Notable security feature in 3 10 7. 
* Notable security feature in 3.10.8: Notable security feature in 3 10 8. 
* Notable changes in 3.10.12: Notable changes in 3 10 12. 

@end menu

@node Résumé – Points forts de la publication<2>,Nouvelles fonctionnalités<7>,,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 summary-release-highlights}@anchor{78b}
@subsection Résumé – Points forts de la publication


@c This section singles out the most important changes in Python 3.10.
@c Brevity is key.

@c PEP-sized items next.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}, Filtrage par motifs structurels : spécification ;

@item 
@geindex Python Enhancement Proposals; PEP 635
PEP 635@footnote{https://peps.python.org/pep-0635/}, Filtrage par motifs structurels : motivation et justification ;

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/}, Filtrage par motifs structurels : tutoriel ;

@item 
bpo-12782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12782}, Les gestionnaires de contextes entre parenthèses sont maintenant autorisés.
@end itemize

Nouvelles fonctionnalités dans la bibliothèque standard :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 618
PEP 618@footnote{https://peps.python.org/pep-0618/}, ajout de la vérification optionnelle de taille dans @code{zip}.
@end itemize

Améliorations de l'interpréteur :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}, numéros de lignes précis pour le débogage et les autres outils.
@end itemize

Nouvelles fonctionnalités de typage :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/}, autorise l'écriture d'union de types sous la forme X | Y ;

@item 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/}, variables de spécification de paramètres.

@item 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/}, alias de types explicites ;

@item 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/}, User-Defined Type Guards
@end itemize

Obsolescences, retraits ou restrictions :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}, mise à jour de la version minimale d'`OpenSSL' à 1.1.1 ;

@item 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/}, obsolescence du module @code{distutils} ;

@item 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/}, obsolescence et préparation du retrait du membre @code{wstr} de @code{PyUnicodeObject} ;

@item 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/}, retrait des API d'encodage @code{Py_UNICODE} ;

@item 
@geindex Python Enhancement Proposals; PEP 597
PEP 597@footnote{https://peps.python.org/pep-0597/}, ajout de l'@code{EncodingWarning} optionnel
@end itemize

@node Nouvelles fonctionnalités<7>,Nouvelles fonctionnalités reliées aux indications de types<3>,Résumé – Points forts de la publication<2>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 new-features}@anchor{78c}
@subsection Nouvelles fonctionnalités


@menu
* Gestionnaires de contextes entre parenthèses:: 
* Meilleurs messages d'erreurs:: 
* PEP 626 ; numéros de lignes précis pour le débogage et les autres outils: PEP 626 numéros de lignes précis pour le débogage et les autres outils. 
* PEP 634 ; filtrage par motifs structurels: PEP 634 filtrage par motifs structurels. 
* EncodingWarning et option encoding="locale" optionnels:: 

@end menu

@node Gestionnaires de contextes entre parenthèses,Meilleurs messages d'erreurs,,Nouvelles fonctionnalités<7>
@anchor{whatsnew/3 10 parenthesized-context-managers}@anchor{78d}@anchor{whatsnew/3 10 whatsnew310-pep563}@anchor{78e}
@subsubsection Gestionnaires de contextes entre parenthèses


Il est maintenant possible de mettre les gestionnaires de contexte entre parenthèses pour les répartir sur plusieurs lignes. Ceci permet le formatage d'une longue série de gestionnaires de contexte sur plusieurs lignes comme ce qui était préalablement possible avec les instructions d'importation. Par exemple, tous ces blocs sont maintenant valides :

@example
with (CtxManager() as example):
    ...

with (
    CtxManager1(),
    CtxManager2()
):
    ...

with (CtxManager1() as example,
      CtxManager2()):
    ...

with (CtxManager1(),
      CtxManager2() as example):
    ...

with (
    CtxManager1() as example1,
    CtxManager2() as example2
):
    ...
@end example

il est aussi possible d'utiliser une virgule en fin de ligne à la fin du groupe entre parenthèses :

@example
with (
    CtxManager1() as example1,
    CtxManager2() as example2,
    CtxManager3() as example3,
):
    ...
@end example

Cette nouvelle syntaxe utilise la capacité `non-LL(1)' du nouvel analyseur syntaxique. Voir 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} pour plus de détails.

(contribution de `Guido van Rossum', `Pablo Galindo' et `Lysandros Nikolaou' dans bpo-12782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12782} et bpo-40334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40334}).

@node Meilleurs messages d'erreurs,PEP 626 numéros de lignes précis pour le débogage et les autres outils,Gestionnaires de contextes entre parenthèses,Nouvelles fonctionnalités<7>
@anchor{whatsnew/3 10 better-error-messages}@anchor{78f}
@subsubsection Meilleurs messages d'erreurs


@menu
* SyntaxError:: 
* IndentationError:: 
* AttributeError:: 
* NameError:: 

@end menu

@node SyntaxError,IndentationError,,Meilleurs messages d'erreurs
@anchor{whatsnew/3 10 syntaxerrors}@anchor{790}
@subsubsection @code{SyntaxError}


Pendant l'analyse syntaxique de code qui contient des parenthèses ou autres balises ouvrantes et fermantes, l'interpréteur inclut maintenant l'emplacement de la balise ou parenthèse non fermée plutôt que d'afficher `SyntaxError: unexpected EOF while parsing' ou d'indiquer un emplacement incorrect. Par exemple, considérez le code suivant (remarquez l'accolade @code{'@{'} non-fermée) :

@example
expected = @{9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
            38: 4, 39: 4, 45: 5, 46: 5, 47: 5, 48: 5, 49: 5, 54: 6,
some_other_code = foo()
@end example

Les versions précédentes de l’interpréteur indiquaient des emplacements qui portaient à confusion pour l'erreur de syntaxe :

@example
File "example.py", line 3
    some_other_code = foo()
                    ^
SyntaxError: invalid syntax
@end example

mais dans Python 3.10, une erreur plus informative est levée :

@example
File "example.py", line 1
    expected = @{9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
               ^
SyntaxError: '@{' was never closed
@end example

De façon similaire, les erreurs impliquant des chaînes littérales non-fermées (avec simples ou triples apostrophes) pointent maintenant vers le début de la chaîne plutôt de mentionner la fin de ligne ou la fin du fichier.

Ces améliorations sont inspirées par un travail préalable sur l'interpréteur `PyPy'

(contribution de `Pablo Galindo' dans bpo-42864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42864} et `Batuhan Taskaya' dans bpo-40176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40176}).

Les exceptions @ref{18b,,SyntaxError} levées par l'interpréteur soulignent maintenant toute la portée de l'expression qui constitue l'erreur de syntaxe plutôt que seulement la position où le problème a été détecté. De cette façon, plutôt que d'afficher (avant Python 3.10) :

@example
>>> foo(x, z for z in range(10), t, w)
  File "<stdin>", line 1
    foo(x, z for z in range(10), t, w)
           ^
SyntaxError: Generator expression must be parenthesized
@end example

Python 3.10 affiche maintenant l'exception comme ceci :

@example
>>> foo(x, z for z in range(10), t, w)
  File "<stdin>", line 1
    foo(x, z for z in range(10), t, w)
           ^^^^^^^^^^^^^^^^^^^^
SyntaxError: Generator expression must be parenthesized
@end example

Cette amélioration est une contribution de `Pablo Galindo' dans bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914}.

Un nombre considérable de nouveaux messages spécialisés pour les exceptions @ref{18b,,SyntaxError} a été incorporé. Certains des plus notables sont :


@itemize *

@item 
@code{:} manquant avant les blocs :

@example
>>> if rocket.position > event_horizon
  File "<stdin>", line 1
    if rocket.position > event_horizon
                                      ^
SyntaxError: expected ':'
@end example

(Contributed by Pablo Galindo in bpo-42997@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42997}.)

@item 
Les `n'-uplets sans parenthèses dans les cibles de compréhensions :

@example
>>> @{x,y for x,y in zip('abcd', '1234')@}
  File "<stdin>", line 1
    @{x,y for x,y in zip('abcd', '1234')@}
     ^
SyntaxError: did you forget parentheses around the comprehension target?
@end example

(Contributed by Pablo Galindo in bpo-43017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43017}.)

@item 
virgules manquantes dans les littéraux de collections et entre les expressions ; :

@example
>>> items = @{
... x: 1,
... y: 2
... z: 3,
  File "<stdin>", line 3
    y: 2
       ^
SyntaxError: invalid syntax. Perhaps you forgot a comma?
@end example

(Contributed by Pablo Galindo in bpo-43822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43822}.)

@item 
types multiples d'@code{Exception} sans parenthèses :

@example
>>> try:
...     build_dyson_sphere()
... except NotEnoughScienceError, NotEnoughResourcesError:
  File "<stdin>", line 3
    except NotEnoughScienceError, NotEnoughResourcesError:
           ^
SyntaxError: multiple exception types must be parenthesized
@end example

(Contributed by Pablo Galindo in bpo-43149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43149}.)

@item 
@code{:} et valeurs manquantes dans les littéraux de dictionnaires :

@example
>>> values = @{
... x: 1,
... y: 2,
... z:
... @}
  File "<stdin>", line 4
    z:
     ^
SyntaxError: expression expected after dictionary key and ':'

>>> values = @{x:1, y:2, z w:3@}
  File "<stdin>", line 1
    values = @{x:1, y:2, z w:3@}
                        ^
SyntaxError: ':' expected after dictionary key
@end example

(Contributed by Pablo Galindo in bpo-43823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43823}.)

@item 
blocs @code{try} sans blocs @code{except} ou @code{finally} :

@example
>>> try:
...     x = 2
... something = 3
  File "<stdin>", line 3
    something  = 3
    ^^^^^^^^^
SyntaxError: expected 'except' or 'finally' block
@end example

(Contributed by Pablo Galindo in bpo-44305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44305}.)

@item 
utilisation de @code{=} au lieu de @code{==} dans les comparaisons :

@example
>>> if rocket.position = event_horizon:
  File "<stdin>", line 1
    if rocket.position = event_horizon:
                       ^
SyntaxError: cannot assign to attribute here. Maybe you meant '==' instead of '='?
@end example

(Contributed by Pablo Galindo in bpo-43797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43797}.)

@item 
utilisation de @code{*} dans les chaînes formatées (`f-strings') :

@example
>>> f"Black holes @{*all_black_holes@} and revelations"
  File "<stdin>", line 1
    (*all_black_holes)
     ^
SyntaxError: f-string: cannot use starred expression here
@end example

(Contributed by Pablo Galindo in bpo-41064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41064}.)
@end itemize

@node IndentationError,AttributeError,SyntaxError,Meilleurs messages d'erreurs
@anchor{whatsnew/3 10 indentationerrors}@anchor{791}
@subsubsection @code{IndentationError}


Plusieurs exceptions @ref{792,,IndentationError} ont maintenant plus de contexte concernant le genre de bloc qui attendait une indentation. Ceci inclut l'emplacement de l'instruction :

@example
>>> def foo():
...    if lel:
...    x = 2
  File "<stdin>", line 3
    x = 2
    ^
IndentationError: expected an indented block after 'if' statement in line 2
@end example

@node AttributeError,NameError,IndentationError,Meilleurs messages d'erreurs
@anchor{whatsnew/3 10 attributeerrors}@anchor{793}
@subsubsection @code{AttributeError}


When printing @ref{343,,AttributeError}, @code{PyErr_Display()} will offer
suggestions of similar attribute names in the object that the exception was
raised from:

@example
>>> collections.namedtoplo
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: module 'collections' has no attribute 'namedtoplo'. Did you mean: namedtuple?
@end example

(contribution de `Pablo Galindo' dans bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}).

@cartouche
@quotation Avertissement 
Notice this won't work if @code{PyErr_Display()} is not called to display the error
which can happen if some other custom error display function is used. This is a common
scenario in some REPLs like IPython.
@end quotation
@end cartouche

@node NameError,,AttributeError,Meilleurs messages d'erreurs
@anchor{whatsnew/3 10 nameerrors}@anchor{794}
@subsubsection @code{NameError}


When printing @ref{428,,NameError} raised by the interpreter, @code{PyErr_Display()}
will offer suggestions of similar variable names in the function that the exception
was raised from:

@example
>>> schwarzschild_black_hole = None
>>> schwarschild_black_hole
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'schwarschild_black_hole' is not defined. Did you mean: schwarzschild_black_hole?
@end example

(contribution de `Pablo Galindo' dans bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}).

@cartouche
@quotation Avertissement 
Notice this won't work if @code{PyErr_Display()} is not called to display the error,
which can happen if some other custom error display function is used. This is a common
scenario in some REPLs like IPython.
@end quotation
@end cartouche

@node PEP 626 numéros de lignes précis pour le débogage et les autres outils,PEP 634 filtrage par motifs structurels,Meilleurs messages d'erreurs,Nouvelles fonctionnalités<7>
@anchor{whatsnew/3 10 pep-626-precise-line-numbers-for-debugging-and-other-tools}@anchor{795}
@subsubsection PEP 626 : numéros de lignes précis pour le débogage et les autres outils


La PEP 626 apporte des numéros de lignes plus précis pour le débogage, le profilage et les outils de mesure de couverture. Les événements de traçage, avec les numéros de ligne corrects, sont générés pour toutes les lignes de code exécutées et seulement pour celles-ci.

The @ref{796,,f_lineno} attribute of frame objects will always contain the
expected line number.

The @ref{2de,,co_lnotab} attribute of
@ref{1cd,,code objects} is deprecated and
will be removed in 3.12.
Code that needs to convert from offset to line number should use the new
@ref{2ef,,co_lines()} method instead.

@node PEP 634 filtrage par motifs structurels,EncodingWarning et option encoding="locale" optionnels,PEP 626 numéros de lignes précis pour le débogage et les autres outils,Nouvelles fonctionnalités<7>
@anchor{whatsnew/3 10 pep-634-structural-pattern-matching}@anchor{797}
@subsubsection PEP 634 : filtrage par motifs structurels


Le filtrage par motifs a été ajouté sous la forme d'une instruction `match' et d'instructions `case' pour les motifs avec des actions associées. Les motifs filtrent des séquences, des dictionnaires, des types de données et des instances de classes. Le filtrage par motifs permet aux programmes d'extraire de l'information de types de données complexes, faire du branchement selon la structure des données et réaliser des actions spécifiques en fonction des différentes formes des données.

@menu
* Syntaxe et opérations:: 
* Approche déclarative:: 
* Filtre simple ; apparier à un littéral: Filtre simple apparier à un littéral. 
* Filtres avec un littéral et une variable:: 
* Filtres et classes:: 
* Filtres imbriqués:: 
* Filtres complexes et attrape-tout:: 
* Garde:: 
* Autres fonctionnalités importantes:: 

@end menu

@node Syntaxe et opérations,Approche déclarative,,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 syntax-and-operations}@anchor{798}
@subsubsection Syntaxe et opérations


La syntaxe générique du filtrage par motifs est :

@example
match subject:
    case <pattern_1>:
        <action_1>
    case <pattern_2>:
        <action_2>
    case <pattern_3>:
        <action_3>
    case _:
        <action_wildcard>
@end example

Une instruction `match' prend une expression et compare successivement sa valeur à différents filtres qui sont donnés comme un ou plusieurs blocs `case'. Plus précisément, le filtrage par motifs s'effectue par :


@enumerate 

@item 
l'utilisation de données qui ont un type et une forme (ici @code{subject}) ;

@item 
l'évaluation de @code{subject} dans une instruction @code{match} ;

@item 
l'application de chaque filtre sur @code{subject} dans des instructions @code{case} de haut en bas jusqu'à ce qu'un appariement soit confirmé ;

@item 
l’exécution de l'action associée au filtre s'il y a appariement ;

@item 
s'il n'y a aucun appariement et que le dernier @code{case} est un filtre `attrape-tout' @code{_}, l'action correspondante est exécutée. S'il n'y a aucun appariement ni filtre attrape-tout, le bloc @code{match} n'effectue aucune opération.
@end enumerate

@node Approche déclarative,Filtre simple apparier à un littéral,Syntaxe et opérations,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 declarative-approach}@anchor{799}
@subsubsection Approche déclarative


Le filtrage par motifs est peut-être connu des lecteurs par l'intermédiaire des langages `C', `Java' ou `JavaScript' (et plusieurs autres langages), avec l'appariement simple d'un sujet (objet de données) à un littéral (filtre) avec l'instruction @code{switch}. Souvent, l'instruction @code{switch} est utilisée pour comparer des objets ou expressions à des instructions @code{case} qui contiennent des littéraux.

Des exemples plus puissants de filtrage par motifs sont présents dans des langages tels que `Scala' et `Elixir'. Avec le filtrage par motifs structurels, l'approche est « déclarative » et énonce les conditions (les motifs) pour apparier les données.

Bien qu'une série d'instructions « impératives » utilisant des instructions « if » imbriquées puisse être utilisée pour accomplir quelque chose de similaire au filtrage par motifs structurels, ceci est moins clair que l'approche « déclarative ». Cette dernière énonce les conditions à remplir pour réaliser un appariement grâce à ses filtres sur des motifs explicites. Bien que le filtrage par motifs structurels puisse être utilisé dans sa forme la plus simple pour comparer une variable à un littéral dans une instruction @code{case}, son intérêt réel en Python réside dans son traitement du sujet selon son type et sa forme.

@node Filtre simple apparier à un littéral,Filtres avec un littéral et une variable,Approche déclarative,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 simple-pattern-match-to-a-literal}@anchor{79a}
@subsubsection Filtre simple : apparier à un littéral


Regardons cet exemple en tant que filtrage par motif dans sa forme la plus simple : une valeur, le sujet, est comparée à (ou « filtrée par ») plusieurs littéraux, les motifs. Dans l'exemple ci-dessous, @code{status} est le sujet de l'instruction @code{match}. Les filtres sont chacune des instructions @code{case}, où les littéraux représentent les codes de status des requêtes. Les actions associées au @code{case} sont exécutés suite à un appariement :

@example
def http_error(status):
    match status:
        case 400:
            return "Bad request"
        case 404:
            return "Not found"
        case 418:
            return "I'm a teapot"
        case _:
            return "Something's wrong with the internet"
@end example

Si on passe 418 à @code{status} dans la fonction ci-haut, elle renvoie @code{"I'm a teapot"}. Avec 500, l'instruction @code{case} qui contient @code{_} apparie comme attrape-tout et la fonction renvoie @code{"Something's wrong with the internet"}. Prenez note que dans le dernier bloc, le nom de variable, @code{_} agit comme un `attrape-tout' et garantit que le sujet sera toujours apparié. L'utilisation de @code{_} est optionnelle.

Vous pouvez combiner plusieurs littéraux dans un seul filtre en utilisant @code{|} (qui se lit « ou ») :

@example
case 401 | 403 | 404:
    return "Not allowed"
@end example

@menu
* Comportement sans l'attrape-tout:: 

@end menu

@node Comportement sans l'attrape-tout,,,Filtre simple apparier à un littéral
@anchor{whatsnew/3 10 behavior-without-the-wildcard}@anchor{79b}
@subsubsection Comportement sans l'attrape-tout


Modifions l'exemple ci-haut en enlevant le dernier bloc @code{case}. Il devient :

@example
def http_error(status):
    match status:
        case 400:
            return "Bad request"
        case 404:
            return "Not found"
        case 418:
            return "I'm a teapot"
@end example

Sans l'utilisation de @code{_} dans une instruction @code{case}, il est possible de ne pas avoir d'appariement. Dans ce cas, il ne se passe rien. Par exemple, si 500 est passé à @code{status}, aucune opération n'est effectuée.

@node Filtres avec un littéral et une variable,Filtres et classes,Filtre simple apparier à un littéral,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 patterns-with-a-literal-and-variable}@anchor{79c}
@subsubsection Filtres avec un littéral et une variable


Les motifs des filtres peuvent prendre une forme similaire aux affectations multiples et un filtre peut être utilisé pour lier plus d'une variable. Dans cet exemple, un point peut être dissocié entre son abscisse et son ordonnée :

@example
# point is an (x, y) tuple
match point:
    case (0, 0):
        print("Origin")
    case (0, y):
        print(f"Y=@{y@}")
    case (x, 0):
        print(f"X=@{x@}")
    case (x, y):
        print(f"X=@{x@}, Y=@{y@}")
    case _:
        raise ValueError("Not a point")
@end example

Le motif du premier filtre comporte deux littéraux, @code{(0, 0)}, et peut être vu comme une extension du filtre sur un littéral montré plus haut. Les motifs des deux filtres suivants regroupent un littéral et une variable. De plus, la variable est liée à la valeur provenant du sujet (@code{point}). Le motif du quatrième filtre capture deux valeurs, ce qui le rend conceptuellement similaire à l'affectation multiple : @code{(x, y) = point}.

@node Filtres et classes,Filtres imbriqués,Filtres avec un littéral et une variable,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 patterns-and-classes}@anchor{79d}
@subsubsection Filtres et classes


Si vous utilisez des classes pour structurer vos données, vous pouvez utiliser le nom de la classe suivie d'une liste d'arguments comme motif de filtre. Ceci ressemble à un appel du constructeur. Ce filtre peut capturer les attributs de la classe dans des variables :

@example
class Point:
    x: int
    y: int

def location(point):
    match point:
        case Point(x=0, y=0):
            print("Origin is the point's location.")
        case Point(x=0, y=y):
            print(f"Y=@{y@} and the point is on the y-axis.")
        case Point(x=x, y=0):
            print(f"X=@{x@} and the point is on the x-axis.")
        case Point():
            print("The point is located somewhere else on the plane.")
        case _:
            print("Not a point")
@end example

@menu
* Filtres avec arguments positionnels:: 

@end menu

@node Filtres avec arguments positionnels,,,Filtres et classes
@anchor{whatsnew/3 10 patterns-with-positional-parameters}@anchor{79e}
@subsubsection Filtres avec arguments positionnels


Vous pouvez utiliser les arguments positionnels avec un certain nombre de classes natives qui définissent l'ordre de leurs attributs, notamment les classes de données (`dataclasses'). Vous pouvez aussi spécifier la position des attributs quand ils sont utilisés dans les filtres en définissant l'attribut spécial @code{__match_args__} dans vos classes. Par exemple, le mettre à @code{("x", "y")} rend tous les filtres ci-dessous équivalents (en particulier, tous provoquent la liaison de l'attribut @code{y} à la variable @code{var}) :

@example
Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)
@end example

@node Filtres imbriqués,Filtres complexes et attrape-tout,Filtres et classes,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 nested-patterns}@anchor{79f}
@subsubsection Filtres imbriqués


Les filtres peuvent être imbriqués de façon arbitraire. Par exemple, si nous avons une courte liste de points, elle peut être appariée comme ceci :

@example
match points:
    case []:
        print("No points in the list.")
    case [Point(0, 0)]:
        print("The origin is the only point in the list.")
    case [Point(x, y)]:
        print(f"A single point @{x@}, @{y@} is in the list.")
    case [Point(0, y1), Point(0, y2)]:
        print(f"Two points on the Y axis at @{y1@}, @{y2@} are in the list.")
    case _:
        print("Something else is found in the list.")
@end example

@node Filtres complexes et attrape-tout,Garde,Filtres imbriqués,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 complex-patterns-and-the-wildcard}@anchor{7a0}
@subsubsection Filtres complexes et attrape-tout


Jusqu'à maintenant, les exemples ont utilisé @code{_} seul dans la dernière instruction @code{case}. Un attrape-tout peut être utilisé dans un filtre plus complexe tel que @code{('error', code, _)}. Par exemple :

@example
match test_variable:
    case ('warning', code, 40):
        print("A warning has been received.")
    case ('error', code, _):
        print(f"An error @{code@} occurred.")
@end example

Dans l'exemple précédent, @code{test_variable} s'apparie à @code{('error', code, 100)} et à @code{('error', code, 800)}.

@node Garde,Autres fonctionnalités importantes,Filtres complexes et attrape-tout,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 guard}@anchor{7a1}
@subsubsection Garde


On peut ajouter une clause @code{if} à un filtre, ce qu'on appelle une « garde ». Si la garde s'évalue à faux, @code{match} poursuit avec la tentative d'appariement du prochain bloc @code{case}. Notez que la capture de valeur se produit avant l'évaluation de la garde :

@example
match point:
    case Point(x, y) if x == y:
        print(f"The point is located on the diagonal Y=X at @{x@}.")
    case Point(x, y):
        print(f"Point is not on the diagonal.")
@end example

@node Autres fonctionnalités importantes,,Garde,PEP 634 filtrage par motifs structurels
@anchor{whatsnew/3 10 other-key-features}@anchor{7a2}
@subsubsection Autres fonctionnalités importantes


Plusieurs autres fonctionnalités importantes :


@itemize -

@item 
Comme dans les affectations multiples, les motifs de filtres qui sont des `n'-uplets ou des listes sont totalement équivalents et autorisent tous les types de séquences. Techniquement, le sujet doit être une séquence. Ainsi, exception importante, les filtres n'autorisent pas les itérateurs. Aussi, pour prémunir d'une erreur commune, les filtres de séquences n'autorisent pas les chaînes ;

@item 
les filtres de séquence peuvent faire intervenir l'affectation étoilée : @code{[x, y, *reste]} ou @code{(x, y, *reste)} ont le même sens que dans une affectation avec @code{=}. Le nom de variable après l'étoile peut aussi être l'attrape-tout @code{_}. Ainsi, @code{(x, y, *_)} est un motif de filtre qui reconnaît les séquences à deux éléments ou plus, en capturant les deux premiers et en ignorant le reste ;

@item 
il existe les filtres d'association, qui ressemblent syntaxiquement aux dictionnaires. Par exemple, le filtre @code{@{"bande_passante": b, "latence": l@}} extrait les valeurs des clés @code{"bande_passante"} et @code{"latence"} dans un dictionnaire. Contrairement aux filtres de séquence, les clés absentes du filtre sont ignorées et le filtre réussit tout de même. L'affectation double-étoilée (@code{**reste}) fonctionne aussi (cependant, @code{**_} serait redondant et n'est donc pas permis) ;

@item 
on peut capturer la valeur d'une partie du motif d'un filtre avec le mot-clé @code{as}, par exemple :

@example
case (Point(x1, y1), Point(x2, y2) as p2): ...
@end example

Ceci lie @code{x1}, @code{y1}, @code{x2}, @code{y2} comme attendu sans la clause @code{as}, et lie @code{p2} à l’entièreté du second élément du sujet ;

@item 
la plupart des littéraux sont comparés par égalité. Néanmoins, les singletons @code{True}, @code{False} et @code{None} sont comparés par identité ;

@item 
les filtres peuvent contenir des noms qui se réfèrent à des constantes. Ces noms doivent impérativement être qualifiés (contenir au moins un point) pour ne pas être interprétés comme des variables de capture :

@example
from enum import Enum
class Color(Enum):
    RED = 0
    GREEN = 1
    BLUE = 2

color = Color.GREEN
match color:
    case Color.RED:
        print("I see red!")
    case Color.GREEN:
        print("Grass is green")
    case Color.BLUE:
        print("I'm feeling the blues :(")
@end example
@end itemize

Pour la spécification complète, voir la 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}. La motivation et la justification des choix sont dans la 
@geindex Python Enhancement Proposals; PEP 635
PEP 635@footnote{https://peps.python.org/pep-0635/}, et un tutoriel plus élaboré se trouve dans la 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/}.

@node EncodingWarning et option encoding="locale" optionnels,,PEP 634 filtrage par motifs structurels,Nouvelles fonctionnalités<7>
@anchor{whatsnew/3 10 optional-encodingwarning-and-encoding-locale-option}@anchor{7a3}@anchor{whatsnew/3 10 whatsnew310-pep597}@anchor{7a4}
@subsubsection @code{EncodingWarning} et option @code{encoding="locale"} optionnels


The default encoding of @ref{7a5,,TextIOWrapper} and @ref{505,,open()} is
platform and locale dependent. Since UTF-8 is used on most Unix
platforms, omitting @code{encoding} option when opening UTF-8 files
(e.g. JSON, YAML, TOML, Markdown) is a very common bug. For example:

@example
# BUG: "rb" mode or encoding="utf-8" should be used.
with open("data.json") as f:
    data = json.load(f)
@end example

Pour trouver ce type de bogue, un @code{EncodingWarning} optionnel a été ajouté. Il est levé quand @ref{677,,sys.flags.warn_default_encoding} est @code{True} et quand l'encodage utilisé est celui défini par les paramètres régionaux.

L'option @code{-X warn_default_encoding} et la variable d’environnement 
@geindex PYTHONWARNDEFAULTENCODING
@geindex variable d'environnement; PYTHONWARNDEFAULTENCODING
@ref{7a6,,PYTHONWARNDEFAULTENCODING} ont été ajoutées pour activer cet avertissement.

Voir @ref{7a7,,Encodage de texte} pour plus d'informations.

@node Nouvelles fonctionnalités reliées aux indications de types<3>,Autres changements au langage<4>,Nouvelles fonctionnalités<7>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 new-feat-related-type-hints}@anchor{7a8}@anchor{whatsnew/3 10 new-features-related-to-type-hints}@anchor{7a9}
@subsection Nouvelles fonctionnalités reliées aux indications de types


Cette section couvre les changements majeurs touchant le module @ref{103,,typing} et les indications de types de style 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}.

@menu
* PEP 604 ; nouvel opérateur d'union de types: PEP 604 nouvel opérateur d'union de types. 
* PEP 612 ; variables de spécification de paramètres: PEP 612 variables de spécification de paramètres. 
* PEP 613 ; TypeAlias: PEP 613 TypeAlias. 
* PEP 647 ; gardes de type définies par l'utilisateur: PEP 647 gardes de type définies par l'utilisateur. 

@end menu

@node PEP 604 nouvel opérateur d'union de types,PEP 612 variables de spécification de paramètres,,Nouvelles fonctionnalités reliées aux indications de types<3>
@anchor{whatsnew/3 10 pep-604-new-type-union-operator}@anchor{7aa}
@subsubsection PEP 604 : nouvel opérateur d'union de types


Un nouvel opérateur d'union de types a été ajouté. Il permet la syntaxe @code{X | Y}. Ceci offre une façon plus propre d'exprimer « soit le type X, soit le type Y » plutôt que d'utiliser @ref{626,,typing.Union}, en particulier pour les indications de types.

Dans les versions précédentes de Python, pour appliquer une indication de type à des fonctions qui acceptent des arguments de plusieurs types, @ref{626,,typing.Union} était utilisée :

@example
def square(number: Union[int, float]) -> Union[int, float]:
    return number ** 2
@end example

Les indications de type peuvent maintenant être écrites de façon plus courte :

@example
def square(number: int | float) -> int | float:
    return number ** 2
@end example

Cette nouvelle syntaxe est aussi acceptée comme le second argument de @ref{42b,,isinstance()} et de @ref{7ab,,issubclass()} :

@example
>>> isinstance(1, int | str)
True
@end example

Voir @ref{7ac,,Type Union} et la 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} pour plus de détails

(contribution de `Maggie Moss' et `Philippe Prados' dans bpo-41428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41428}, avec ajouts par `Yurii Karabas' et `Serhiy Storchaka' dans bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490}).

@node PEP 612 variables de spécification de paramètres,PEP 613 TypeAlias,PEP 604 nouvel opérateur d'union de types,Nouvelles fonctionnalités reliées aux indications de types<3>
@anchor{whatsnew/3 10 pep-612-parameter-specification-variables}@anchor{7ad}
@subsubsection PEP 612 : variables de spécification de paramètres


Deux nouvelles options ont été ajoutées au module @ref{103,,typing} pour améliorer l'information donnée aux vérificateurs de types statiques pour les @code{Callable} définis dans la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}.

La première est la variable de spécification de paramètre. Elles sont utilisées pour transférer le type d'un appelable à un autre – un patron de conception souvent utilisé dans les fonctions d'ordre supérieur et dans les décorateurs. Des exemples d'utilisation se trouvent dans @ref{15d,,typing.ParamSpec}. Préalablement, il n'y avait pas de façon facile pour annoter les dépendances de types des paramètres de manière aussi précise.

La seconde option est le nouvel opérateur @code{Concatenate}. Il est utilisé en conjonction avec les variables de spécification de paramètres pour annoter les types d'un appelable d'ordre supérieur qui ajoute ou retire des paramètres à un autre appelable. Des exemples d'utilisation se trouvent dans @ref{7ae,,typing.Concatenate}.

Voir @ref{7af,,typing.Callable}, @ref{15d,,typing.ParamSpec}, @ref{7ae,,typing.Concatenate}, @ref{7b0,,typing.ParamSpecArgs}, @ref{7b1,,typing.ParamSpecKwargs} et la 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} pour plus de détails

(contribution de `Ken Jin' dans bpo-41559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41559}, avec améliorations mineures par `Jelle Zijlstra' dans bpo-43783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43783} ; PEP écrite par `Mark Mendoza').

@node PEP 613 TypeAlias,PEP 647 gardes de type définies par l'utilisateur,PEP 612 variables de spécification de paramètres,Nouvelles fonctionnalités reliées aux indications de types<3>
@anchor{whatsnew/3 10 pep-613-typealias}@anchor{7b2}
@subsubsection PEP 613 : @code{TypeAlias}


La 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} a ajouté le concept d'alias de types, en exigeant seulement qu'ils soient des assignations non-annotées au niveau du module. Cette simplicité rendait parfois difficile pour les vérificateurs de types de distinguer entre un alias de type et une affectation ordinaire, en particulier quand des références postérieures ou des types invalides étaient impliqués. Comparez :

@example
StrCache = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
@end example

Now the @ref{103,,typing} module has a special value @ref{7b3,,TypeAlias}
which lets you declare type aliases more explicitly:

@example
StrCache: TypeAlias = 'Cache[str]'  # a type alias
LOG_PREFIX = 'LOG[DEBUG]'  # a module constant
@end example

Voir la 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/} pour plus de détails.

(contribution de `Mikhail Golubev' dans bpo-41923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41923}).

@node PEP 647 gardes de type définies par l'utilisateur,,PEP 613 TypeAlias,Nouvelles fonctionnalités reliées aux indications de types<3>
@anchor{whatsnew/3 10 pep-647-user-defined-type-guards}@anchor{7b4}
@subsubsection PEP 647 : gardes de type définies par l'utilisateur


@ref{163,,TypeGuard} has been added to the @ref{103,,typing} module to annotate
type guard functions and improve information provided to static type checkers
during type narrowing.  For more information, please see
@ref{163,,TypeGuard}'s documentation, and 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/}.

(contribution de `Ken Jin' et `Guido van Rossum' dans bpo-43766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43766}. PEP écrit par `Eric Traut').

@node Autres changements au langage<4>,Nouveaux modules<4>,Nouvelles fonctionnalités reliées aux indications de types<3>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 other-language-changes}@anchor{7b5}
@subsection Autres changements au langage



@itemize *

@item 
Le type @ref{254,,int} a une nouvelle méthode @ref{7b6,,int.bit_count()}, qui renvoie le nombre de chiffres uns dans l’expansion binaire d'un entier donné, aussi connue sous le nom de chiffre de population (`population count') (contribution de `Niklas Fiekas' dans bpo-29882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29882}).

@item 
Les vues renvoyées par @ref{7b7,,dict.keys()}, @ref{7b8,,dict.values()} et @ref{7b9,,dict.items()} ont maintenant toutes un attribut @code{mapping} qui donne un objet @ref{457,,types.MappingProxyType} encapsulant le dictionnaire original (contribution de `Dennis Sweeney' dans bpo-40890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40890}).

@item 
@geindex Python Enhancement Proposals; PEP 618
PEP 618@footnote{https://peps.python.org/pep-0618/} : la fonction @ref{7ba,,zip()} a maintenant un argument optionnel @code{strict}, utilisé pour demander que tous les itérables soient de même longueur.

@item 
Les fonctions d'extensions et les fonctions natives qui prennent des arguments entiers n'acceptent plus les @ref{29a,,Decimal}, @ref{1e4,,Fraction} et autres objets qui ne peuvent pas être convertis en entiers sans perte de précision (par exemple ceux qui ont une méthode @ref{706,,__int__()} mais pas une méthode @ref{707,,__index__()}) (contribution de `Serhiy Storchaka' dans bpo-37999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37999}).

@item 
If @ref{7bb,,object.__ipow__()} returns @ref{7bc,,NotImplemented}, the operator will
correctly fall back to @ref{7bd,,object.__pow__()} and @ref{7be,,object.__rpow__()} as expected.
(Contributed by Alex Shkop in bpo-38302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38302}.)

@item 
Les expressions d'affectations peuvent maintenant être utilisées dans les littéraux d'ensembles, dans les compréhensions d'ensembles et dans les indices de séquences (mais pas dans les tranches).

@item 
Les fonctions ont un nouvel attribut @code{__builtins__} qui est utilisé pour repérer les symboles natifs quand la fonction est exécutée, plutôt que de regarder dans @code{__globals__['__builtins__']}. L'attribut est initialisé à partir de @code{__globals__["__builtins__"]} s'il existe, ou des symboles natifs en cours autrement (contribution de `Mark Shannon' dans bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}).

@item 
Deux nouvelles fonctions natives – @ref{7bf,,aiter()} et @ref{7c0,,anext()} – ont été ajoutées pour fournir les équivalents asynchrones de @ref{7c1,,iter()} et de @ref{7c2,,next()}, respectivement (contribution de `Joshua Bronson', `Daniel Pope' et `Justin Wang' dans bpo-31861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31861}).

@item 
Les méthodes statiques (@ref{40c,,@@staticmethod}) et les méthodes de classes (@ref{165,,@@classmethod}) héritent maintenant des attributs de méthodes (@code{__module__}, @code{__name__}, @code{__qualname__}, @code{__doc__}, @code{__annotations__}) et ont un nouvel attribut @code{__wrapped__}. De plus, les méthodes statiques sont maintenant appelables en tant que fonctions classiques (contribution de `Victor Stinner' dans bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682}).

@item 
Les annotations des cibles complexes (toutes cibles autre que @code{simple name} telles que définies dans la 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}) n'ont plus d'effet à l'exécution avec @code{from __future__ import annotations} (contribution de `Batuhan Taskaya' dans bpo-42737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42737}).

@item 
Les objets @code{class} et @code{module} créent maintenant paresseusement un dictionnaire d'annotations vide sur demande. Les dictionnaires d'annotations sont stockés dans le @code{__dict__} de l'objet pour garder la retro-compatibilité.  Cela renforce les bonnes pratiques relatives à @code{__annotations__} ; pour plus d'information, voir @ref{7c3,,Bonnes pratiques concernant les annotations} (contribution de `Larry Hastings' dans bpo-43901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43901}).

@item 
Les annotations qui contiennent @code{yield}, @code{yield from}, @code{await} ou une expression nommée ne sont plus permises sous @code{from __future__ import annotations} à cause de leurs effets secondaires (contribution de `Batuhan Taskaya' dans bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725}).

@item 
L'utilisation de variables non liées, de @code{super()} et d'autres expressions qui peuvent changer le traitement de la table des symboles en tant qu'annotation n'ont plus d'effet sous @code{from __future__ import annotations} (contribution de `Batuhan Taskaya' dans bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725}).

@item 
Le hachage des valeurs `NaN' des types @ref{2eb,,float} et @ref{29a,,decimal.Decimal} dépend maintenant de l'identité de l'objet. Préalablement, cette valeur de hachage était toujours @code{0} alors que les valeurs `NaN' ne sont pas égales entre elles. Cela pouvait potentiellement entrainer un temps d'exécution quadratique en raison des collisions excessives des valeurs de hachage lors de la création de dictionnaires et d'ensembles qui contiennent plusieurs `NaN' (contribution de `Raymond Hettinger' dans bpo-43475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43475}).

@item 
A @ref{18b,,SyntaxError} (instead of a @ref{428,,NameError}) will be raised when deleting
the @ref{7c4,,__debug__} constant.  (Contributed by Donghee Na in bpo-45000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45000}.)

@item 
Les exceptions @ref{18b,,SyntaxError} ont maintenant des attributs @code{end_lineno} et @code{end_offset}. La valeur est @code{None} quand ils ne peuvent pas être déterminés (contribution de `Pablo Galindo' dans bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914}).
@end itemize

@node Nouveaux modules<4>,Modules améliorés<4>,Autres changements au langage<4>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 new-modules}@anchor{7c5}
@subsection Nouveaux modules



@itemize *

@item 
None.
@end itemize

@node Modules améliorés<4>,Optimisations<4>,Nouveaux modules<4>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 improved-modules}@anchor{7c6}
@subsection Modules améliorés


@menu
* asyncio: asyncio<4>. 
* argparse: argparse<2>. 
* array: array<3>. 
* asynchat@comma{} asyncore@comma{} smtpd: asynchat asyncore smtpd. 
* base64: base64<2>. 
* bdb:: 
* bisect:: 
* codecs:: 
* collections.abc: collections abc. 
* contextlib: contextlib<2>. 
* curses:: 
* dataclasses: dataclasses<2>. 
* distutils: distutils<2>. 
* doctest: doctest<2>. 
* encodings:: 
* enum: enum<4>. 
* fileinput:: 
* faulthandler:: 
* gc:: 
* glob: glob<2>. 
* hashlib: hashlib<3>. 
* hmac:: 
* IDLE et idlelib: IDLE et idlelib<2>. 
* importlib.metadata: importlib metadata<2>. 
* inspect: inspect<3>. 
* itertools: itertools<3>. 
* linecache:: 
* os: os<4>. 
* os.path: os path<3>. 
* pathlib: pathlib<5>. 
* platform:: 
* pprint:: 
* py_compile:: 
* pyclbr:: 
* shelve:: 
* statistics: statistics<3>. 
* site: site<2>. 
* socket: socket<2>. 
* ssl: ssl<3>. 
* sqlite3: sqlite3<5>. 
* sys: sys<5>. 
* _thread:: 
* threading: threading<3>. 
* traceback: traceback<3>. 
* types: types<3>. 
* typing: typing<5>. 
* unittest: unittest<5>. 
* urllib.parse: urllib parse. 
* xml: xml<2>. 
* zipimport: zipimport<3>. 

@end menu

@node asyncio<4>,argparse<2>,,Modules améliorés<4>
@anchor{whatsnew/3 10 asyncio}@anchor{7c7}
@subsubsection @code{asyncio}


Ajout de la méthode @code{connect_accepted_socket()} manquante (contribution d'`Alex Grönholm' dans bpo-41332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41332}).

@node argparse<2>,array<3>,asyncio<4>,Modules améliorés<4>
@anchor{whatsnew/3 10 argparse}@anchor{7c8}
@subsubsection @code{argparse}


L'expression @code{"optional arguments"} qui portait à confusion a été remplacée par @code{"options"} dans le message d'aide d'@code{argparse}. Certains tests devront être adaptés s'ils dépendent d'une comparaison exacte dans la sortie d'aide (contribution de `Raymond Hettinger' dans bpo-9694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9694}).

@node array<3>,asynchat asyncore smtpd,argparse<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 array}@anchor{7c9}
@subsubsection @code{array}


La méthode @ref{7ca,,index()} de la classe @ref{19e,,array.array} a maintenant les paramètres optionnels `start' et `stop' (contribution d'`Anders Lorentsen' et de `Zackery Spytz' dans bpo-31956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31956}).

@node asynchat asyncore smtpd,base64<2>,array<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 asynchat-asyncore-smtpd}@anchor{7cb}
@subsubsection @code{asynchat}, @code{asyncore}, @code{smtpd}


Ces modules ont étés déclarés obsolètes dans leur documentation de modules depuis Python 3.6. Un @ref{1a3,,DeprecationWarning} au moment de l'importation est maintenant ajouté pour ces trois modules.

@node base64<2>,bdb,asynchat asyncore smtpd,Modules améliorés<4>
@anchor{whatsnew/3 10 base64}@anchor{7cc}
@subsubsection @code{base64}


Ajout de @ref{7cd,,base64.b32hexencode()} et de @ref{7ce,,base64.b32hexdecode()} pour prendre en charge l'encodage Base32 avec l'alphabet hexadécimal étendu.

@node bdb,bisect,base64<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 bdb}@anchor{7cf}
@subsubsection @code{bdb}


Ajout de @code{clearBreakpoints()} pour supprimer tous les points d'arrêt (contribution d'`Irit Katriel' dans bpo-24160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24160}).

@node bisect,codecs,bdb,Modules améliorés<4>
@anchor{whatsnew/3 10 bisect}@anchor{7d0}
@subsubsection @code{bisect}


Ajout de la possibilité de fournir une fonction @code{key} aux API dans le module @ref{11,,bisect} (contribution de `Raymond Hettinger' dans bpo-4356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4356}).

@node codecs,collections abc,bisect,Modules améliorés<4>
@anchor{whatsnew/3 10 codecs}@anchor{7d1}
@subsubsection @code{codecs}


Ajout d'une fonction @ref{7d2,,codecs.unregister()} pour désinscrire une fonction de recherche de codecs (contribution de `Hai Shi' dans bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}).

@node collections abc,contextlib<2>,codecs,Modules améliorés<4>
@anchor{whatsnew/3 10 collections-abc}@anchor{7d3}
@subsubsection @code{collections.abc}


L'attribut @code{__args__} des @ref{69d,,génériques paramétrables} de @ref{7d4,,collections.abc.Callable} est maintenant cohérent avec @ref{7af,,typing.Callable}. Les génériques de @ref{7d4,,collections.abc.Callable} aplatissent maintenant les types des paramètres à l'instar de @ref{7af,,typing.Callable}. Ceci veut dire que @code{collections.abc.Callable[[int, str], str]} aura un attribut @code{__args__} de valeur @code{(int, str, str)} ; auparavant, il aurait été @code{([int, str], str)}. Pour permettre ce changement, @ref{7d5,,types.GenericAlias} peut être dérivée, et une sous-classe sera renvoyée lors de la surcharge  du type @ref{7d4,,collections.abc.Callable}. Prenez note que @ref{522,,TypeError} sera levée pour des formes invalides de paramétrisation de @ref{7d4,,collections.abc.Callable}, ce qui aurait pu passer silencieusement dans Python 3.9 (contribution de `Ken Jin' dans bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}).

@node contextlib<2>,curses,collections abc,Modules améliorés<4>
@anchor{whatsnew/3 10 contextlib}@anchor{7d6}
@subsubsection @code{contextlib}


Ajout d'un gestionnaire de contexte @ref{7d7,,contextlib.aclosing()} pour fermer de façon sécurisée les générateurs asynchrones et les objets représentants des ressources libérées de façon asynchrone (contribution de `Joongi Kim' et `John Belmonte' dans bpo-41229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41229}).

Ajout d'un gestionnaire de contexte pour prendre en charge @ref{7d8,,contextlib.nullcontext()} (contribution de `Tom Gringauz' dans bpo-41543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41543}).

Add @ref{7d9,,AsyncContextDecorator}, for supporting usage of async
context managers as decorators.

@node curses,dataclasses<2>,contextlib<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 curses}@anchor{7da}
@subsubsection @code{curses}


Les fonctions de couleurs étendues ajoutées dans `ncurses' 6.1 sont utilisées de façon transparente par @ref{7db,,curses.color_content()}, @ref{7dc,,curses.init_color()}, @ref{7dd,,curses.init_pair()} et @ref{7de,,curses.pair_content()}. Une nouvelle fonction, @ref{7df,,curses.has_extended_color_support()}, indique si la prise en charge des couleurs étendues est fournie par la bibliothèque `ncurses' sous-jacente (contribution de `Jeffrey Kintscher' et de `Hans Petter Jansson' dans bpo-36982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36982}).

Les constantes @code{BUTTON5_*} sont maintenant exposées dans le module @ref{2b,,curses} si elles sont fournies par la bibliothèque `curses' sous-jacente (contribution de `Zackery Spytz' dans bpo-39273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39273}).

@node dataclasses<2>,distutils<2>,curses,Modules améliorés<4>
@anchor{whatsnew/3 10 dataclasses}@anchor{7e0}
@subsubsection @code{dataclasses}


@menu
* __slots__:: 
* Champs obligatoirement nommés:: 

@end menu

@node __slots__,Champs obligatoirement nommés,,dataclasses<2>
@anchor{whatsnew/3 10 slots}@anchor{7e1}
@subsubsection @code{__slots__}


Ajout du paramètre @code{slots} dans le décorateur @ref{1c6,,dataclasses.dataclass()} (contribution de `Yurii Karabas' dans bpo-42269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42269}).

@node Champs obligatoirement nommés,,__slots__,dataclasses<2>
@anchor{whatsnew/3 10 keyword-only-fields}@anchor{7e2}
@subsubsection Champs obligatoirement nommés


Les classes de données (@code{dataclass}) prennent maintenant en charge les champs obligatoirement nommés dans la méthode @code{__init__} générée. Il y a plusieurs façons de spécifier les champs obligatoirement nommés.

Vous pouvez indiquer que tous les champs sont obligatoirement nommés :

@example
from dataclasses import dataclass

@@dataclass(kw_only=True)
class Birthday:
    name: str
    birthday: datetime.date
@end example

Les paramètres @code{name} et @code{birthday} sont tous deux obligatoirement nommés dans la méthode @code{__init__} générée.

Pour chaque champ, vous pouvez indiquer s'il est obligatoirement nommé :

@example
from dataclasses import dataclass, field

@@dataclass
class Birthday:
    name: str
    birthday: datetime.date = field(kw_only=True)
@end example

Ici, seulement @code{birthday} est obligatoirement nommé. Si vous assignez @code{kw_only} sur un champ particulier, notez qu'il y a des règles concernant l'ordre des champs puisque les champs obligatoirement nommés doivent suivre les champs optionnellement nommés. Voir la documentation de @code{dataclass} pour plus de détails.

Vous pouvez aussi indiquer que tous les champs qui suivent un marqueur @code{KW_ONLY} sont obligatoirement nommés. Ceci sera probablement l'utilisation la plus commune :

@example
from dataclasses import dataclass, KW_ONLY

@@dataclass
class Point:
    x: float
    y: float
    _: KW_ONLY
    z: float = 0.0
    t: float = 0.0
@end example

Here, @code{z} and @code{t} are keyword-only parameters, while @code{x} and
@code{y} are not.
(Contributed by Eric V. Smith in bpo-43532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43532}.)

@node distutils<2>,doctest<2>,dataclasses<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 distutils}@anchor{7e3}@anchor{whatsnew/3 10 distutils-deprecated}@anchor{714}
@subsubsection @code{distutils}


Le paquet @code{distutil} est entièrement obsolète et sera retiré dans Python 3.12. Ses fonctionnalités pour spécifier la construction de paquets sont déjà complètement remplacées par les paquets tierce-parties  @code{setuptools} et @code{packaging}. Les autres API régulièrement utilisées sont disponibles ailleurs dans la bibliothèque standard (tel que dans @ref{a9,,platform}, @ref{c4,,shutil}, @ref{d5,,subprocess} ou @ref{da,,sysconfig}). Il n'est pas prévu de migrer d'autres fonctionnalités de @code{distutils}, aussi les applications qui utilisent d'autres fonctions du module doivent faire des copies privées du code. Voir la discussion dans la 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/}.

La commande @code{bdist_wininst} qui est obsolète depuis Python 3.8 a été retirée. La commande @code{bdist_wheel} est maintenant recommandée pour distribuer des paquets binaires sous Windows (contribution de `Victor Stinner' dans bpo-42802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42802}).

@node doctest<2>,encodings,distutils<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 doctest}@anchor{7e4}
@subsubsection @code{doctest}


Quand un module ne définit pas @code{__loader__}, @code{__spec__.loader} est utilisé (contribution de `Brett Cannon' dans bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}).

@node encodings,enum<4>,doctest<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 encodings}@anchor{7e5}
@subsubsection @code{encodings}


La fonction @code{encodings.normalize_encoding()} ignore maintenant les caractères non ASCII (contribution de `Hai Shi' dans bpo-39337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39337}).

@node enum<4>,fileinput,encodings,Modules améliorés<4>
@anchor{whatsnew/3 10 enum}@anchor{7e6}
@subsubsection enum


@ref{61b,,Enum} @ref{607,,__repr__()} now returns @code{enum_name.member_name} and
@ref{608,,__str__()} now returns @code{member_name}.  Stdlib enums available as
module constants have a @ref{7e7,,repr()} of @code{module_name.member_name}.
(Contributed by Ethan Furman in bpo-40066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40066}.)

Add @ref{605,,enum.StrEnum} for enums where all members are strings.
(Contributed by Ethan Furman in bpo-41816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41816}.)

@node fileinput,faulthandler,enum<4>,Modules améliorés<4>
@anchor{whatsnew/3 10 fileinput}@anchor{7e8}
@subsubsection @code{fileinput}


Ajout des paramètres @code{encoding} et @code{errors} dans @ref{7e9,,fileinput.input()} et dans @ref{721,,fileinput.FileInput} (contribution d'`Inada Naoki' dans bpo-43712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43712}).

@ref{7ea,,fileinput.hook_compressed()} now returns @ref{7a5,,TextIOWrapper} object
when `mode' is "r" and file is compressed, like uncompressed files.
(Contributed by Inada Naoki in bpo-5758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5758}.)

@node faulthandler,gc,fileinput,Modules améliorés<4>
@anchor{whatsnew/3 10 faulthandler}@anchor{7eb}
@subsubsection @code{faulthandler}


Le module @ref{57,,faulthandler} détecte maintenant si une erreur fatale s'est produite pendant un passage du ramasse-miettes (contribution de `Victor Stinner' dans bpo-44466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44466}).

@node gc,glob<2>,faulthandler,Modules améliorés<4>
@anchor{whatsnew/3 10 gc}@anchor{7ec}
@subsubsection @code{gc}


Ajout de fonctions de rappels d'audit pour @ref{7ed,,gc.get_objects()}, @ref{7ee,,gc.get_referrers()} et @ref{7ef,,gc.get_referents()} (contribution de `Pablo Galindo' dans bpo-43439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43439}).

@node glob<2>,hashlib<3>,gc,Modules améliorés<4>
@anchor{whatsnew/3 10 glob}@anchor{7f0}
@subsubsection @code{glob}


Ajout des paramètres @code{root_dir} et @code{dir_fd} dans @ref{29c,,glob()} et dans @ref{7f1,,iglob()} pour permettre la spécification du répertoire racine utilisé pour la recherche (contribution de `Serhiy Storchaka' dans bpo-38144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38144}).

@node hashlib<3>,hmac,glob<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 hashlib}@anchor{7f2}
@subsubsection @code{hashlib}


La version minimale d'`OpenSSL' pour le module @code{hashlib} est maintenant 1.1.1 (contribution de `Christian Heimes' dans 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} et dans bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669}).

Le module `hashlib' offre une prise en charge préliminaire pour `OpenSSL' 3.0.0 (contribution de `Christian Heimes' dans bpo-38820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38820} et autres tickets).

Le repli vers la version en pur Python de @ref{4f8,,pbkdf2_hmac()} est obsolète. Dorénavant, @code{PBKDF2-HMAC} n'est disponible que si Python a été compilé avec la prise en charge d'`OpenSSL' (contribution de `Christian Heimes' dans bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880}).

@node hmac,IDLE et idlelib<2>,hashlib<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 hmac}@anchor{7f3}
@subsubsection @code{hmac}


L'implémentation interne du module @code{hmac} utilise maintenant `HMAC' d'`OpenSSL' (contribution de `Christian Heimes' dans bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}).

@node IDLE et idlelib<2>,importlib metadata<2>,hmac,Modules améliorés<4>
@anchor{whatsnew/3 10 idle-and-idlelib}@anchor{7f4}
@subsubsection IDLE et @code{idlelib}


IDLE invoque maintenant @ref{7f5,,sys.excepthook()} (lorsque lancé sans @code{'-n'}). Auparavant, les fonctions de rappel définies par l'utilisateur étaient ignorées (contribution par `Ken Hilton' dans bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008}).

Rearrange the settings dialog.  Split the General tab into Windows
and Shell/Ed tabs.  Move help sources, which extend the Help menu, to the
Extensions tab.  Make space for new options and shorten the dialog. The
latter makes the dialog better fit small screens.  (Contributed by Terry Jan
Reedy in bpo-40468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40468}.)  Move the indent space setting from the Font tab to
the new Windows tab.  (Contributed by Mark Roseman and Terry Jan Reedy in
bpo-33962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33962}.)

Les changements ci-dessus ont été rétro-portés dans le cadre de la maintenance de 3.9.

Ajout d'une barre de côté à la console. Déplacement de l'invite de commande principale (@code{>>>}) vers cette barre. Ajout des invites secondaires (@code{...}) à la barre de côté. Le clic de gauche et le glisser optionnel sélectionnent une ou plusieurs lignes de texte, tout comme dans la barre de numéros de ligne de la fenêtre d'édition. Le clic droit après la sélection de lignes de texte affiche un menu contextuel pour copier avec invites (`'copy with prompts''). Ceci combine les invites de la barre de côté avec le texte sélectionné. Cette option apparait aussi dans le menu contextuel pour le texte (contribution de `Tal Einat' dans bpo-37903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37903}).

Utilisation d'espaces plutôt que des tabulations pour indenter le code interactif. Ceci donne au code interactif la « bonne apparence ». Cette fonctionnalité est fortement corrélée à l'ajout de la barre de côté de la console (contribution de `Terry Jan Reedy' dans bpo-37892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37892}).

Coloration des nouveaux @ref{7f6,,mots clés ad-hoc} @ref{7f7,,match}, @ref{7f7,,case} et @ref{7f8,,_} dans les instructions de filtrage par motifs (`pattern matching'). Par contre, cette coloration n'est pas parfaite et elle sera incorrecte dans quelques rares cas, y-compris certains @code{_} dans des instructions @code{case} (contribution de Tal Einat dans bpo-44010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44010}).

Nouveau dans les versions de maintenance 3.10.

Applique la coloration syntaxique aux fichiers @code{.pyi} (contribution d'`Alex Waygood' et de `Terry Jan Reedy' dans bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447}).

Include prompts when saving Shell with inputs and outputs.
(Contributed by Terry Jan Reedy in gh-95191@footnote{https://github.com/python/cpython/issues/95191}.)

@node importlib metadata<2>,inspect<3>,IDLE et idlelib<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 importlib-metadata}@anchor{7f9}
@subsubsection @code{importlib.metadata}


Équivalence de fonctionnalités avec @code{importlib_metadata} 4.6 (historique@footnote{https://importlib-metadata.readthedocs.io/en/latest/history.html}).

@ref{281,,importlib.metadata entry points}
now provide a nicer experience
for selecting entry points by group and name through a new
@ref{281,,importlib.metadata.EntryPoints} class. See the Compatibility
Note in the docs for more info on the deprecation and usage.

Added @ref{7fa,,importlib.metadata.packages_distributions()}
for resolving top-level Python modules and packages to their
@ref{7fb,,importlib.metadata.Distribution}.

@node inspect<3>,itertools<3>,importlib metadata<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 inspect}@anchor{7fc}
@subsubsection @code{inspect}


Quand un module ne définit pas @code{__loader__}, @code{__spec__.loader} est utilisé (contribution de `Brett Cannon' dans bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}).

Add @ref{7fd,,inspect.get_annotations()}, which safely computes the annotations
defined on an object. It works around the quirks of accessing the annotations
on various types of objects, and makes very few assumptions about the object
it examines. @ref{7fd,,inspect.get_annotations()} can also correctly un-stringize
stringized annotations.  @ref{7fd,,inspect.get_annotations()} is now considered
best practice for accessing the annotations dict defined on any Python object;
for more information on best practices for working with annotations, please see
@ref{7c3,,Bonnes pratiques concernant les annotations}.
Relatedly, @ref{722,,inspect.signature()},
@ref{724,,inspect.Signature.from_callable()}, and @code{inspect.Signature.from_function()}
now call @ref{7fd,,inspect.get_annotations()} to retrieve annotations. This means
@ref{722,,inspect.signature()} and @ref{724,,inspect.Signature.from_callable()} can
also now un-stringize stringized annotations.
(Contributed by Larry Hastings in bpo-43817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43817}.)

@node itertools<3>,linecache,inspect<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 itertools}@anchor{7fe}
@subsubsection itertools


Add @ref{7ff,,itertools.pairwise()}.
(Contributed by Raymond Hettinger in bpo-38200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38200}.)

@node linecache,os<4>,itertools<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 linecache}@anchor{800}
@subsubsection @code{linecache}


Quand un module ne définit pas @code{__loader__}, @code{__spec__.loader} est utilisé (contribution de `Brett Cannon' dans bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}).

@node os<4>,os path<3>,linecache,Modules améliorés<4>
@anchor{whatsnew/3 10 os}@anchor{801}
@subsubsection @code{os}


Add @ref{1c0,,os.cpu_count()} support for VxWorks RTOS.
(Contributed by Peixing Xin in bpo-41440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41440}.)

Ajout d'une nouvelle fonction @ref{802,,os.eventfd()} et des fonctions utilitaires associées pour encapsuler l'appel système @code{eventfd2} sur Linux (contribution de `Christian Heimes' dans bpo-41001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41001}).

Add @ref{803,,os.splice()} that allows to move data between two file
descriptors without copying between kernel address space and user
address space, where one of the file descriptors must refer to a
pipe. (Contributed by Pablo Galindo in bpo-41625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41625}.)

Add @ref{804,,O_EVTONLY}, @ref{805,,O_FSYNC}, @ref{806,,O_SYMLINK}
and @ref{807,,O_NOFOLLOW_ANY} for macOS.
(Contributed by Donghee Na in bpo-43106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43106}.)

@node os path<3>,pathlib<5>,os<4>,Modules améliorés<4>
@anchor{whatsnew/3 10 os-path}@anchor{808}
@subsubsection @code{os.path}


@ref{222,,os.path.realpath()} accepte maintenant l'argument nommé `strict'. Lorsqu'il est @code{True}, une @ref{40d,,OSError} est levée si le chemin n'existe pas ou si une boucle de liens symboliques est rencontrée (contribution de `Barney Gale' dans bpo-43757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43757}).

@node pathlib<5>,platform,os path<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 pathlib}@anchor{809}
@subsubsection @code{pathlib}


Add slice support to @ref{80a,,PurePath.parents}.
(Contributed by Joshua Cannon in bpo-35498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35498}.)

Add negative indexing support to @ref{80a,,PurePath.parents}.
(Contributed by Yaroslav Pankovych in bpo-21041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21041}.)

Add @ref{80b,,Path.hardlink_to} method that
supersedes @code{link_to()}. The new method has the same argument
order as @ref{80c,,symlink_to()}.
(Contributed by Barney Gale in bpo-39950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39950}.)

@ref{80d,,pathlib.Path.stat()} et @ref{80e,,chmod()} acceptent maintenant l'argument nommé `follow_symlinks' pour rester cohérent avec les fonctions correspondantes dans le module @ref{a0,,os} (contribution de `Barney Gale' dans bpo-39906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39906}).

@node platform,pprint,pathlib<5>,Modules améliorés<4>
@anchor{whatsnew/3 10 platform}@anchor{80f}
@subsubsection @code{platform}


Add @ref{810,,platform.freedesktop_os_release()} to retrieve operation system
identification from freedesktop.org os-release@footnote{https://www.freedesktop.org/software/systemd/man/os-release.html} standard file.
(Contributed by Christian Heimes in bpo-28468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28468}.)

@node pprint,py_compile,platform,Modules améliorés<4>
@anchor{whatsnew/3 10 pprint}@anchor{811}
@subsubsection @code{pprint}


@ref{812,,pprint.pprint()} accepte maintenant le nouvel argument nommé @code{underscore_numbers} (contribution de `sblondon' dans bpo-42914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42914}).

@ref{ad,,pprint} peut maintenant afficher élégamment les instances de @ref{1c6,,dataclasses.dataclass} (contribution de `Lewis Gaul' dans bpo-43080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43080}).

@node py_compile,pyclbr,pprint,Modules améliorés<4>
@anchor{whatsnew/3 10 py-compile}@anchor{813}
@subsubsection @code{py_compile}


Ajout de l'option de ligne de commande @code{--quiet} à l'interface de @ref{b2,,py_compile} (contribution de `Gregory Schevchenko' dans bpo-38731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38731}).

@node pyclbr,shelve,py_compile,Modules améliorés<4>
@anchor{whatsnew/3 10 pyclbr}@anchor{814}
@subsubsection @code{pyclbr}


Add an @code{end_lineno} attribute to the @code{Function} and @code{Class}
objects in the tree returned by @ref{815,,pyclbr.readmodule()} and
@ref{816,,pyclbr.readmodule_ex()}.  It matches the existing (start) @code{lineno}.
(Contributed by Aviral Srivastava in bpo-38307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38307}.)

@node shelve,statistics<3>,pyclbr,Modules améliorés<4>
@anchor{whatsnew/3 10 shelve}@anchor{817}
@subsubsection @code{shelve}


The @ref{c2,,shelve} module now uses @ref{818,,pickle.DEFAULT_PROTOCOL} by default
instead of @ref{a5,,pickle} protocol @code{3} when creating shelves.
(Contributed by Zackery Spytz in bpo-34204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34204}.)

@node statistics<3>,site<2>,shelve,Modules améliorés<4>
@anchor{whatsnew/3 10 statistics}@anchor{819}
@subsubsection @code{statistics}


Ajout des fonctions @ref{81a,,covariance()}, @ref{4a5,,correlation()} (corrélation de Pearson) et @ref{81b,,linear_regression()} (régression linéaire simple) (contribution de `Tymoteusz Wołodźko' dans bpo-38490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38490}).

@node site<2>,socket<2>,statistics<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 site}@anchor{81c}
@subsubsection @code{site}


Quand un module ne définit pas @code{__loader__}, @code{__spec__.loader} est utilisé (contribution de `Brett Cannon' dans bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}).

@node socket<2>,ssl<3>,site<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 socket}@anchor{81d}
@subsubsection @code{socket}


L'exception @ref{81e,,socket.timeout} est maintenant un alias de @ref{81f,,TimeoutError} (contribution de `Christian Heimes' dans bpo-42413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42413}).

Ajout d'une option pour créer des connecteurs (`socket') `MPTCP' avec @code{IPPROTO_MPTCP} (contribution de `Rui Cunha' dans bpo-43571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43571}).

Ajout de l'option @code{IP_RECVTOS} pour récupérer la valeur des champs `type of service (ToS)' ou `differentiated services code point (DSCP/ECN)' (contribution de `Georg Sauthoff' dans bpo-44077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44077}).

@node ssl<3>,sqlite3<5>,socket<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 ssl}@anchor{820}
@subsubsection @code{ssl}


La version minimale d'`OpenSSL' pour le module @code{ssl} est maintenant 1.1.1 (contribution de `Christian Heimes' dans 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} et dans bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669}).

The ssl module has preliminary support for OpenSSL 3.0.0 and new option
@ref{821,,OP_IGNORE_UNEXPECTED_EOF}.
(Contributed by Christian Heimes in bpo-38820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38820}, bpo-43794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43794},
bpo-43788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43788}, bpo-43791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43791}, bpo-43799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43799}, bpo-43920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43920},
bpo-43789@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43789}, and bpo-43811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43811}.)

Les fonctions obsolètes et l'accès aux constantes obsolètes lèvent maintenant un @ref{1a3,,DeprecationWarning}. @ref{822,,ssl.SSLContext.options} a options @ref{823,,OP_NO_SSLv2} et @ref{824,,OP_NO_SSLv3} définies par défaut ; par conséquent, il ne peut pas avertir si l'option est définie de nouveau. La section @ref{825,,obsolescence} contient la liste des fonctionnalités obsolètes (contribution de `Christian Heimes' dans bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880}).

La configuration du module @code{ssl} est plus sécuritaire par défaut. Les algorithmes de chiffrement sans confidentialité persistante (`forward secrecy') et le code d'authentification de message (MAC) `SHA-1' sont désactivés par défaut. Le niveau 2 de sécurité ne permet pas les clés faibles de moins de 112 bits pour `RSA', `DH' et `ECC'. La version minimale du protocole `TLS' pour @ref{291,,SSLContext} est 1.2. La configuration est basée sur la recherche de `Hynek Schlawack' (contribution de `Christian Heimes' dans bpo-43998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43998}).

Les protocoles obsolètes `SSL' 3.0, `TLS' 1.0 et `TLS' 1.1 ne sont plus officiellement pris en charge. Python ne les bloque pas activement, mais les options de compilation d'`OpenSSL', les configurations du système d'exploitation, les rustines des fabricants et les suites d'algorithmes de chiffrement peuvent empêcher l’établissement d'une connexion.

Ajout d'un paramètre `timeout' à la fonction @ref{826,,ssl.get_server_certificate()} (contribution de `Zackery Spytz' dans bpo-31870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31870}).

Le module @code{ssl} utilise les types du tas et l'initialisation multi-phase (contribution de `Christian Heimes' dans bpo-42333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42333}).

A new verify flag @ref{155,,VERIFY_X509_PARTIAL_CHAIN} has been added.
(Contributed by l0x in bpo-40849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40849}.)

@node sqlite3<5>,sys<5>,ssl<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 sqlite3}@anchor{827}
@subsubsection @code{sqlite3}


Ajout d'événements d'audit pour @code{connect/handle()}, @ref{828,,enable_load_extension()} et @ref{4a1,,load_extension()} (contribution d'`Erlend E. Aasland' dans bpo-43762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43762}).

@node sys<5>,_thread,sqlite3<5>,Modules améliorés<4>
@anchor{whatsnew/3 10 sys}@anchor{829}
@subsubsection @code{sys}


Ajout de l'attribut @ref{82a,,sys.orig_argv} : la liste des arguments de ligne de commande originalement passée à l'exécutable Python (contribution de `Victor Stinner' dans bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}).

Ajout de @ref{82b,,sys.stdlib_module_names} qui contient la liste des noms des modules de la bibliothèque standard (contribution de `Victor Stinner' dans bpo-42955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42955}).

@node _thread,threading<3>,sys<5>,Modules améliorés<4>
@anchor{whatsnew/3 10 thread}@anchor{82c}
@subsubsection @code{_thread}


@ref{82d,,_thread.interrupt_main()} now takes an optional signal number to
simulate (the default is still @ref{82e,,signal.SIGINT}).
(Contributed by Antoine Pitrou in bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356}.)

@node threading<3>,traceback<3>,_thread,Modules améliorés<4>
@anchor{whatsnew/3 10 threading}@anchor{82f}
@subsubsection @code{threading}


Ajout des fonctions @ref{830,,threading.gettrace()} et @ref{831,,threading.getprofile()} pour récupérer les fonctions assignées par @ref{832,,threading.settrace()} et @ref{833,,threading.setprofile()} respectivement (contribution de `Mario Corchero' dans bpo-42251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42251}).

Ajout de @ref{834,,threading.__excepthook__} pour permettre la récupération de @ref{835,,threading.excepthook()} au cas où elle serait affectée à une valeur incorrecte ou différente (contribution de `Mario Corchero' dans bpo-42308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42308}).

@node traceback<3>,types<3>,threading<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 traceback}@anchor{836}
@subsubsection @code{traceback}


Les fonctions @ref{837,,format_exception()}, @ref{838,,format_exception_only()} et @ref{839,,print_exception()} peuvent maintenant prendre un objet exception en argument positionnel (contribution de `Zackery Spytz' et `Matthias Bussonnier' dans bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389}).

@node types<3>,typing<5>,traceback<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 types}@anchor{83a}
@subsubsection @code{types}


Les classes @ref{83b,,types.EllipsisType}, @ref{83c,,types.NoneType} et @ref{83d,,types.NotImplementedType} sont ajoutées de nouveau. Elles fournissent un nouvel ensemble de types facilement interprétable par les vérificateurs de types (contribution de `Bas van Beek' dans bpo-41810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41810}).

@node typing<5>,unittest<5>,types<3>,Modules améliorés<4>
@anchor{whatsnew/3 10 typing}@anchor{83e}
@subsubsection @code{typing}


Pour les changements majeurs, voir @ref{7a8,,Nouvelles fonctionnalités reliées aux indications de types}.

Le comportement de @ref{83f,,typing.Literal} a été changé pour être conforme avec la 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/} et pour correspondre au comportement des vérificateurs de types statiques défini dans la PEP.


@enumerate 

@item 
@code{Literal} dé-duplique maintenant les paramètres.

@item 
La comparaison d'égalité entre objets @code{Literal} ne tient plus compte de l'ordre.

@item 
Les comparaisons de @code{Literal} respectent maintenant les types. Par exemple, @code{Literal[0] == Literal[False]} était préalablement évaluée à @code{True}. Elle est maintenant @code{False}. Pour prendre en charge ce changement, le cache des types de l'implémentation interne peut maintenant différencier entre les types.

@item 
Les objets @code{Literal} lèvent maintenant une exception @ref{522,,TypeError} pendant la comparaison d'égalité si au moins un de leurs paramètres n'est pas @ref{5fb,,hachable}. Notez que déclarer un @code{Literal} avec des paramètres non hachables ne lève pas d'erreur :

@example
>>> from typing import Literal
>>> Literal[@{0@}]
>>> Literal[@{0@}] == Literal[@{False@}]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'set'
@end example
@end enumerate

(contribution de `Yurii Karabas' dans bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345}).

Add new function @ref{840,,typing.is_typeddict()} to introspect if an annotation
is a @ref{161,,typing.TypedDict}.
(Contributed by Patrick Reader in bpo-41792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41792}.)

Subclasses of @code{typing.Protocol} which only have data variables declared
will now raise a @code{TypeError} when checked with @code{isinstance} unless they
are decorated with @ref{42c,,runtime_checkable()}.  Previously, these checks
passed silently.  Users should decorate their
subclasses with the @code{runtime_checkable()} decorator
if they want runtime protocols.
(Contributed by Yurii Karabas in bpo-38908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38908}.)

Importing from the @code{typing.io} and @code{typing.re} submodules will now emit
@ref{1a3,,DeprecationWarning}.  These submodules have been deprecated since
Python 3.8 and will be removed in a future version of Python.  Anything
belonging to those submodules should be imported directly from
@ref{103,,typing} instead.
(Contributed by Sebastian Rittau in bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291}.)

@node unittest<5>,urllib parse,typing<5>,Modules améliorés<4>
@anchor{whatsnew/3 10 unittest}@anchor{841}
@subsubsection @code{unittest}


Ajout d'une nouvelle méthode @ref{842,,assertNoLogs()} pour complémenter la méthode existante @ref{843,,assertLogs()} (contribution de `Kit Yan Choi' dans bpo-39385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39385}).

@node urllib parse,xml<2>,unittest<5>,Modules améliorés<4>
@anchor{whatsnew/3 10 urllib-parse}@anchor{844}
@subsubsection @code{urllib.parse}


Python versions earlier than Python 3.10 allowed using both @code{;} and @code{&} as
query parameter separators in @ref{277,,urllib.parse.parse_qs()} and
@ref{276,,urllib.parse.parse_qsl()}.  Due to security concerns, and to conform with
newer W3C recommendations, this has been changed to allow only a single
separator key, with @code{&} as the default.  This change also affects
@code{cgi.parse()} and @code{cgi.parse_multipart()} as they use the affected
functions internally.  For more details, please see their respective
documentation.
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}.)

The presence of newline or tab characters in parts of a URL allows for some
forms of attacks. Following the WHATWG specification that updates 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html},
ASCII newline @code{\n}, @code{\r} and tab @code{\t} characters are stripped from the
URL by the parser in @ref{109,,urllib.parse} preventing such attacks. The removal
characters are controlled by a new module level variable
@code{urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE}. (See gh-88048@footnote{https://github.com/python/cpython/issues/88048})

@node xml<2>,zipimport<3>,urllib parse,Modules améliorés<4>
@anchor{whatsnew/3 10 xml}@anchor{845}
@subsubsection @code{xml}


Ajout d'une classe @ref{846,,LexicalHandler} au module @ref{129,,xml.sax.handler} (contribution de `Jonathan Gossage' de `Zackery Spytz' dans bpo-35018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35018}).

@node zipimport<3>,,xml<2>,Modules améliorés<4>
@anchor{whatsnew/3 10 zipimport}@anchor{847}
@subsubsection @code{zipimport}


Ajout des méthodes relatives à la 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} : @ref{848,,find_spec()}, @ref{849,,zipimport.zipimporter.create_module()} et @ref{307,,zipimport.zipimporter.exec_module()} (contribution de `Brett Cannon' dans bpo-42131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42131}).

Ajout de la méthode @ref{84a,,invalidate_caches()} (contribution de `Desmond Cheong' dans bpo-14678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14678}).

@node Optimisations<4>,Obsolescence<5>,Modules améliorés<4>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 optimizations}@anchor{84b}
@subsection Optimisations



@itemize *

@item 
Les constructeurs de @ref{435,,str()}, @ref{1bd,,bytes()} et @ref{528,,bytearray()} sont maintenant plus rapides (environ 30—40 % pour les petits objets) (contribution de `Serhiy Storchaka' dans bpo-41334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41334}).

@item 
Le module @ref{bd,,runpy} importe maintenant moins de modules. Le temps de démarrage de la commande @code{python3 -m module-name} est en moyenne 1,4 fois plus rapide. Sur Linux @code{python3 -I -m module-name} importe 69 modules dans Python 3.9, alors qu'elle n'en importe que 51 (18 de moins) dans Python 3.10 (contribution de `Victor Stinner' dans bpo-41006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41006} et dans bpo-41718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41718}).

@item 
L'instruction @code{LOAD_ATTR} utilise maintenant le mécanisme de cache par code d'opération. Elle est environ 36 % plus rapide pour les attributs ordinaires et 44 % plus rapide pour les `slots' (contribution de `Pablo Galindo' et de `Yury Selivanov' dans bpo-42093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42093} et `Guido van Rossum' dans bpo-42927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42927}, basée sur des idées originalement mises en œuvre dans `PyPy' et dans `MicroPython').

@item 
Lors de la construction de Python avec @ref{84c,,--enable-optimizations}, @code{-fno-semantic-interposition} est maintenant ajouté aux lignes de commande de compilation et d'édition des liens. Ceci accélère les binaires de l'interpréteur Python créés avec @ref{84d,,--enable-shared} et @code{gcc} jusqu'à 30 %. Voir cet article@footnote{https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/} (en anglais) pour plus de détails (contribution de `Victor Stinner' et `Pablo Galindo' dans bpo-38980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38980}).

@item 
Ré-usinage du code assurant la gestion du tampon de sortie pour les modules @ref{13,,bz2}, @ref{89,,lzma} et @ref{132,,zlib}. Ajout de la fonction @code{.readall()} à la classe @code{_compression.DecompressReader}. La décompression `bz2' est 1,09 à 1,17 fois plus rapide, la décompression `lzma' est 1,20 à 1,32 fois plus rapide, @code{GzipFile.read(-1)} est 1,11 à 1,18 fois plus rapide (contribution de `Ma Lin', révision par `Gregory P. Smith' dans bpo-41486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41486}).

@item 
When using stringized annotations, annotations dicts for functions are no longer
created when the function is created.  Instead, they are stored as a tuple of
strings, and the function object lazily converts this into the annotations dict
on demand.  This optimization cuts the CPU time needed to define an annotated
function by half.
(Contributed by Yurii Karabas and Inada Naoki in bpo-42202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42202}.)

@item 
Les fonctions de recherche de sous-chaînes telles que @code{str1 in str2} et @code{str2.find(str1)} peuvent utiliser maintenant l'algorithme « bidirectionnel » de recherche de chaînes `Crochemore et Perrin' pour éviter le comportement quadratique sur les longues chaînes (contribution de `Dennis Sweeney' dans bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972}).

@item 
Add micro-optimizations to @code{_PyType_Lookup()} to improve type attribute cache lookup
performance in the common case of cache hits. This makes the interpreter 1.04 times faster
on average. (Contributed by Dino Viehland in bpo-43452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43452}.)

@item 
The following built-in functions now support the faster 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} vectorcall calling convention:
@ref{84e,,map()}, @ref{84f,,filter()}, @ref{850,,reversed()}, @ref{451,,bool()} and @ref{2eb,,float()}.
(Contributed by Donghee Na and Jeroen Demeyer in bpo-43575@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43575}, bpo-43287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43287}, bpo-41922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41922}, bpo-41873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41873} and bpo-41870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41870}.)

@item 
@ref{851,,BZ2File} performance is improved by removing internal @code{RLock}.
This makes @code{BZ2File} thread unsafe in the face of multiple simultaneous
readers or writers, just like its equivalent classes in @ref{66,,gzip} and
@ref{89,,lzma} have always been.  (Contributed by Inada Naoki in bpo-43785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43785}.)
@end itemize

@node Obsolescence<5>,Retrait,Optimisations<4>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 deprecated}@anchor{852}@anchor{whatsnew/3 10 whatsnew310-deprecated}@anchor{825}
@subsection Obsolescence



@itemize *

@item 
Currently Python accepts numeric literals immediately followed by keywords,
for example @code{0in x}, @code{1or x}, @code{0if 1else 2}.  It allows confusing
and ambiguous expressions like @code{[0x1for x in y]} (which can be
interpreted as @code{[0x1 for x in y]} or @code{[0x1f or x in y]}).  Starting in
this release, a deprecation warning is raised if the numeric literal is
immediately followed by one of keywords @ref{2e5,,and}, @ref{18a,,else},
@ref{2e6,,for}, @ref{2e7,,if}, @ref{2e8,,in}, @ref{2e9,,is} and @ref{2ea,,or}.
In future releases it will be changed to syntax warning, and finally to
syntax error.
(Contributed by Serhiy Storchaka in bpo-43833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43833}.)

@item 
Starting in this release, there will be a concerted effort to begin
cleaning up old import semantics that were kept for Python 2.7
compatibility. Specifically,
@code{find_loader()}/@code{find_module()}
(superseded by @ref{853,,find_spec()}),
@ref{854,,load_module()}
(superseded by @ref{855,,exec_module()}),
@code{module_repr()} (which the import system
takes care of for you), the @code{__package__} attribute
(superseded by @code{__spec__.parent}), the @code{__loader__} attribute
(superseded by @code{__spec__.loader}), and the @code{__cached__} attribute
(superseded by @code{__spec__.cached}) will slowly be removed (as well
as other classes and methods in @ref{76,,importlib}).
@ref{4e4,,ImportWarning} and/or @ref{1a3,,DeprecationWarning} will be raised
as appropriate to help identify code which needs updating during
this transition.

@item 
L'espace de noms @code{distutils} est complètement obsolète et sera retiré dans Python 3.12. Voir la section sur les @ref{714,,changements aux modules} pour plus d'information.

@item 
Les arguments non entiers de @ref{856,,random.randrange()} sont obsolètes. La levée de @ref{1ff,,ValueError} dans ce cas est obsolète et est remplacée par @ref{522,,TypeError} (contribution de `Serhiy Storchaka' et `Raymond Hettinger' dans bpo-37319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37319}).

@item 
Les multiples méthodes @code{load_module()} de @ref{76,,importlib} étaient documentées comme obsolètes depuis Python 3.6, mais elles vont maintenant aussi lever un @ref{1a3,,DeprecationWarning}. Utilisez plutôt @ref{855,,exec_module()} (contribution de `Brett Cannon' dans bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}).

@item 
@code{zimport.zipimporter.load_module()} has been deprecated in
preference for @ref{307,,exec_module()}.
(Contributed by Brett Cannon in bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}.)

@item 
L'utilisation de @ref{854,,load_module()} par le système d'importation lève maintenant un @ref{4e4,,ImportWarning} car @ref{855,,exec_module()} est recommandée (contribution de (`Brett Cannon' dans bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}).

@item 
The use of @code{importlib.abc.MetaPathFinder.find_module()} and
@code{importlib.abc.PathEntryFinder.find_module()} by the import system now
trigger an @ref{4e4,,ImportWarning} as
@ref{853,,importlib.abc.MetaPathFinder.find_spec()} and
@ref{857,,importlib.abc.PathEntryFinder.find_spec()}
are preferred, respectively. You can use
@ref{858,,importlib.util.spec_from_loader()} to help in porting.
(Contributed by Brett Cannon in bpo-42134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42134}.)

@item 
The use of @code{importlib.abc.PathEntryFinder.find_loader()} by the import
system now triggers an @ref{4e4,,ImportWarning} as
@ref{857,,importlib.abc.PathEntryFinder.find_spec()} is preferred. You can use
@ref{858,,importlib.util.spec_from_loader()} to help in porting.
(Contributed by Brett Cannon in bpo-43672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43672}.)

@item 
The various implementations of
@code{importlib.abc.MetaPathFinder.find_module()} (
@code{importlib.machinery.BuiltinImporter.find_module()},
@code{importlib.machinery.FrozenImporter.find_module()},
@code{importlib.machinery.WindowsRegistryFinder.find_module()},
@code{importlib.machinery.PathFinder.find_module()},
@code{importlib.abc.MetaPathFinder.find_module()} ),
@code{importlib.abc.PathEntryFinder.find_module()} (
@code{importlib.machinery.FileFinder.find_module()} ), and
@code{importlib.abc.PathEntryFinder.find_loader()} (
@code{importlib.machinery.FileFinder.find_loader()} )
now raise @ref{1a3,,DeprecationWarning} and are slated for removal in
Python 3.12 (previously they were documented as deprecated in Python 3.4).
(Contributed by Brett Cannon in bpo-42135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42135}.)

@item 
@code{importlib.abc.Finder} is deprecated (including its sole method,
@code{find_module()}). Both
@ref{859,,importlib.abc.MetaPathFinder} and @ref{85a,,importlib.abc.PathEntryFinder}
no longer inherit from the class. Users should inherit from one of these two
classes as appropriate instead.
(Contributed by Brett Cannon in bpo-42135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42135}.)

@item 
The deprecations of @code{imp}, @code{importlib.find_loader()},
@code{importlib.util.set_package_wrapper()},
@code{importlib.util.set_loader_wrapper()},
@code{importlib.util.module_for_loader()},
@code{pkgutil.ImpImporter}, and
@code{pkgutil.ImpLoader} have all been updated to list Python 3.12 as the
slated version of removal (they began raising @ref{1a3,,DeprecationWarning} in
previous versions of Python).
(Contributed by Brett Cannon in bpo-43720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43720}.)

@item 
The import system now uses the @code{__spec__} attribute on modules before
falling back on @code{module_repr()} for a module's
@code{__repr__()} method. Removal of the use of @code{module_repr()} is scheduled
for Python 3.12.
(Contributed by Brett Cannon in bpo-42137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42137}.)

@item 
@code{importlib.abc.Loader.module_repr()},
@code{importlib.machinery.FrozenLoader.module_repr()}, and
@code{importlib.machinery.BuiltinLoader.module_repr()} are deprecated and
slated for removal in Python 3.12.
(Contributed by Brett Cannon in bpo-42136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42136}.)

@item 
@code{sqlite3.OptimizedUnicode} est non-documenté et désuète depuis Python 3.3, quand elle devenue un alias de @ref{435,,str}. Elle est maintenant déclarée obsolète et sera retiré dans Python 3.12 (contribution de `Erlend E. Aasland' dans bpo-42264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42264}).

@item 
La fonction native non-documentée @code{sqlite3.enable_shared_cache} est maintenant obsolète et sera retirée dans Python 3.12. Son utilisation est fortement déconseillée dans la documentation de SQLite3. Voir la documentation de SQLite3@footnote{https://sqlite.org/c3ref/enable_shared_cache.html} (en anglais) pour plus de détails. Si un cache partagé est nécessaire, ouvrez la base de données en mode URI en utilisant le paramètre de requête @code{cache=shared} (contribution de `Erlend E. Aasland' dans bpo-24464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24464}).

@item 
Les méthodes suivantes du module @code{threading} sont maintenant obsolètes :


@itemize *

@item 
@code{threading.currentThread} => @ref{2fe,,threading.current_thread()} ;

@item 
@code{threading.activeCount} => @ref{2ff,,threading.active_count()} ;

@item 
@code{threading.Condition.notifyAll} => @ref{2f8,,threading.Condition.notify_all()} ;

@item 
@code{threading.Event.isSet} => @ref{2f9,,threading.Event.is_set()} ;

@item 
@code{threading.Thread.setName} => @ref{2fd,,threading.Thread.name} ;

@item 
@code{threading.thread.getName} => @ref{2fd,,threading.Thread.name} ;

@item 
@code{threading.Thread.isDaemon} => @ref{2fb,,threading.Thread.daemon} ;

@item 
@code{threading.Thread.setDaemon} => @ref{2fb,,threading.Thread.daemon}.
@end itemize

(Contributed by Jelle Zijlstra in gh-87889@footnote{https://github.com/python/cpython/issues/87889}.)

@item 
@code{pathlib.Path.link_to()} is deprecated and slated for removal in
Python 3.12. Use @ref{80b,,pathlib.Path.hardlink_to()} instead.
(Contributed by Barney Gale in bpo-39950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39950}.)

@item 
@code{cgi.log()} est obsolète et sera retirée dans Python 3.12 (contribution de `Inada Naoki' dans bpo-41139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41139}).

@item 
Les fonctionnalités suivantes de @ref{cf,,ssl} sont obsolètes depuis Python 3.6, Python 3.7 ou `OpenSSL' 1.1.0 et seront retirées dans 3.11 :


@itemize *

@item 
@code{OP_NO_SSLv2}, @code{OP_NO_SSLv3}, @code{OP_NO_TLSv1},
@code{OP_NO_TLSv1_1}, @code{OP_NO_TLSv1_2}, and
@code{OP_NO_TLSv1_3} are replaced by
@ref{85b,,minimum_version} and
@ref{85c,,maximum_version}.

@item 
@code{PROTOCOL_SSLv2}, @code{PROTOCOL_SSLv3},
@code{PROTOCOL_SSLv23}, @code{PROTOCOL_TLSv1},
@code{PROTOCOL_TLSv1_1}, @code{PROTOCOL_TLSv1_2}, and
@code{PROTOCOL_TLS} are deprecated in favor of
@ref{85d,,PROTOCOL_TLS_CLIENT} and @ref{85e,,PROTOCOL_TLS_SERVER}

@item 
@code{wrap_socket()} is replaced by @ref{50e,,ssl.SSLContext.wrap_socket()}

@item 
@code{match_hostname()}

@item 
@code{RAND_pseudo_bytes()}, @code{RAND_egd()}

@item 
Les fonctionnalités NPN (`Next Protocol Negotiation') telles que @ref{85f,,ssl.SSLSocket.selected_npn_protocol()} et @ref{2f6,,ssl.SSLContext.set_npn_protocols()} sont remplacées par ALPN (`Application Layer Protocol Negotiation').
@end itemize

@item 
The threading debug (@code{PYTHONTHREADDEBUG} environment variable) is
deprecated in Python 3.10 and will be removed in Python 3.12. This feature
requires a @ref{1f6,,debug build of Python}.
(Contributed by Victor Stinner in bpo-44584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44584}.)

@item 
Importing from the @code{typing.io} and @code{typing.re} submodules will now emit
@ref{1a3,,DeprecationWarning}.  These submodules will be removed in a future version
of Python.  Anything belonging to these submodules should be imported directly
from @ref{103,,typing} instead.
(Contributed by Sebastian Rittau in bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291}.)
@end itemize

@node Retrait,Portage vers Python 3 10,Obsolescence<5>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 removed}@anchor{860}@anchor{whatsnew/3 10 whatsnew310-removed}@anchor{861}
@subsection Retrait



@itemize *

@item 
Les méthodes spéciales @code{__int__}, @code{__float__}, @code{__floordiv__}, @code{__mod__}, @code{__divmod__}, @code{__rfloordiv__}, @code{__rmod__} et @code{__rdivmod__} sont retirées de la classe @ref{2ec,,complex}. Elles levaient toujours une @ref{522,,TypeError} (contribution de `Serhiy Storchaka' dans bpo-41974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41974}).

@item 
La méthode @code{ParserBase.error()} du module privé et non-documenté @code{_markupbase} a été retirée. @ref{862,,html.parser.HTMLParser} est la seule sous-classe de @code{ParserBase} et son implémentation de la méthode @code{error()} a été retirée dans Python 3.5 (contribution de `Berker Peksag' dans bpo-31844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31844}).

@item 
Retrait de l'attribut @code{unicodedata.ucnhash_CAPI} qui était un objet @code{PyCapsule} interne. La structure privée associée @code{_PyUnicode_Name_CAPI} a été déplacée vers l'API C interne (contribution de `Victor Stinner' dans bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}).

@item 
Retrait du module @code{parser} qui était obsolète depuis 3.9 étant donné la transition vers le nouvel analyseur syntaxique PEG. Retrait aussi des fichiers source et en-tête C qui n'étaient utilisés que par l'ancien analyseur, ceci comprend @code{node.h}, @code{parser.h}, @code{graminit.h} et @code{grammar.h}.

@item 
Retrait des fonctions @code{PyParser_SimpleParseStringFlags}, @code{PyParser_SimpleParseStringFlagsFilename}, @code{PyParser_SimpleParseFileFlags} et @code{PyNode_Compile} de l'API C publique. Elles étaient obsolètes depuis 3.9 étant donné la transition vers l'analyseur syntaxique `PEG'.

@item 
Removed the @code{formatter} module, which was deprecated in Python 3.4.
It is somewhat obsolete, little used, and not tested. It was originally
scheduled to be removed in Python 3.6, but such removals were delayed until
after Python 2.7 EOL. Existing users should copy whatever classes they use
into their code.
(Contributed by Donghee Na and Terry J. Reedy in bpo-42299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42299}.)

@item 
Removed the @code{PyModule_GetWarningsModule()} function that was useless
now due to the @code{_warnings} module was converted to a builtin module in 2.6.
(Contributed by Hai Shi in bpo-42599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42599}.)

@item 
Retrait des alias obsolètes @ref{863,,Classes de base abstraites de collections} du module @ref{1d,,collections} (contribution de `Victor Stinner' dans bpo-37324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37324}).

@item 
Le paramètre @code{loop} a été retiré de la majorité de @ref{864,,l'API haut-niveau} d'@ref{a,,asyncio}. Il était obsolète depuis Python 3.8. La motivation pour ce changement avait plusieurs facettes :


@enumerate 

@item 
ceci simplifie l'API haut-niveau ;

@item 
les fonctions dans l'API haut niveau reçoivent implicitement la boucle d'évènements qui tourne dans le présent fil d'exécution depuis Python 3.7. Il n'y a aucun besoin de passer la boucle d'évènements à l'API dans la majorité de son utilisation normale ;

@item 
le passage de la boucle d'évènements cause facilement des erreurs quand plusieurs boucles qui tournent dans plusieurs fils d'exécution sont impliquées.
@end enumerate

Prenez note que l'API bas-niveau accepte toujours le paramètre @code{loop}. Voir @ref{865,,Changements dans l'API Python} pour plus d'exemples sur comment remplacer le code existant

(contribution de `Yurii Karabas', `Andrew Svetlov', `Yury Selivanov' et `Kyle Stanley' dans bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}).
@end itemize

@node Portage vers Python 3 10,Changements au code intermédiaire CPython<3>,Retrait,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 porting-to-python-3-10}@anchor{866}
@subsection Portage vers Python 3.10


Cette section liste les changements mentionnés préalablement et autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changements à la syntaxe de Python:: 
* Changements dans l'API Python: Changements dans l'API Python<3>. 
* Changements dans l'API C: Changements dans l'API C<2>. 

@end menu

@node Changements à la syntaxe de Python,Changements dans l'API Python<3>,,Portage vers Python 3 10
@anchor{whatsnew/3 10 changes-in-the-python-syntax}@anchor{867}
@subsubsection Changements à la syntaxe de Python



@itemize *

@item 
Deprecation warning is now emitted when compiling previously valid syntax
if the numeric literal is immediately followed by a keyword (like in @code{0in x}).
In future releases it will be changed to syntax warning, and finally to a
syntax error.  To get rid of the warning and make the code compatible with
future releases just add a space between the numeric literal and the
following keyword.
(Contributed by Serhiy Storchaka in bpo-43833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43833}.)
@end itemize

@node Changements dans l'API Python<3>,Changements dans l'API C<2>,Changements à la syntaxe de Python,Portage vers Python 3 10
@anchor{whatsnew/3 10 changes-in-the-python-api}@anchor{868}@anchor{whatsnew/3 10 changes-python-api}@anchor{865}
@subsubsection Changements dans l'API Python



@itemize *

@item 
Les paramètres `etype' des fonctions @ref{837,,format_exception()}, @ref{838,,format_exception_only()} et @ref{839,,print_exception()} du module @ref{fd,,traceback} ont étés renommés `exc' (contribution de `Zackery Spytz' et `Matthias Bussonnier' dans bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389}).

@item 
@ref{c,,atexit} : à la fin de l'exécution de Python, si une fonction de rappel qui a été enregistrée avec @ref{869,,atexit.register()} échoue, son exception est maintenant journalisée. Préalablement, seulement certaines exceptions étaient journalisées et la dernière exception était toujours ignorée de façon silencieuse (contribution de `Victor Stinner' dans bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}).

@item 
Les génériques de @ref{7d4,,collections.abc.Callable} aplatissent maintenant les paramètres de types tel qu'il est fait par @ref{7af,,typing.Callable}. Ceci veut dire que @code{collections.abc.Callable[[int, str], str]} aura un attribut @code{__args__} de valeur @code{(int, str, str)} ; préalablement, il aurait été @code{([int, str], str)}. Les codes qui accèdent aux arguments par @ref{86a,,typing.get_args()} ou @code{__args__} doivent tenir compte de ce changement. De plus, @ref{522,,TypeError} sera levée pour des formes invalides de paramétrisation de @ref{7d4,,collections.abc.Callable}, ce qui aurait pu passer silencieusement dans Python 3.9 (contribution de `Ken Jin' dans bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}).

@item 
@ref{86b,,socket.htons()} et @ref{86c,,socket.ntohs()} lèvent maintenant @ref{86d,,OverflowError} plutôt que @ref{1a3,,DeprecationWarning} si le paramètre passé est trop grand pour être stocké dans un entier 16-bit non-signé (contribution de `Erlend E. Aasland' dans bpo-42393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42393}).

@item 
Le paramètre @code{loop} a été retiré de la majorité de @ref{864,,l'API haut-niveau} d'@ref{a,,asyncio} suite à la déclaration de son obsolescence dans Python 3.8.

Une coroutine qui ressemble actuellement à ceci :

@example
async def foo(loop):
    await asyncio.sleep(1, loop=loop)
@end example

Doit être remplacée par ceci :

@example
async def foo():
    await asyncio.sleep(1)
@end example

Si @code{foo()} a été spécifiquement conçue pour `ne pas' s'exécuter dans le fil d'exécution courant, (par exemple pour tourner dans la boucle d'exécution d'un autre fil), l'utilisation de @ref{86e,,asyncio.run_coroutine_threadsafe()} est probablement plus appropriée.

(contribution de `Yurii Karabas', `Andrew Svetlov', `Yury Selivanov' et `Kyle Stanley' dans bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}).

@item 
Le constructeur de @ref{86f,,types.FunctionType} hérite maintenant des définitions natives si le dictionnaire `globals' n'a pas de clé @code{"__builtins__"}, plutôt que d'utiliser @code{@{"None": None@}} pour les définitions natives : même comportement que celui des fonctions @ref{17e,,eval()} et @ref{17d,,exec()}. Définir une fonction avec @code{def function(...): ...} en Python n'est pas affecté, les globales ne peuvent pas être changées avec cette syntaxe : elles héritent aussi des définitions natives courantes (contribution de `Victor Stinner' dans bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}).
@end itemize

@node Changements dans l'API C<2>,,Changements dans l'API Python<3>,Portage vers Python 3 10
@anchor{whatsnew/3 10 changes-in-the-c-api}@anchor{870}
@subsubsection Changements dans l'API C



@itemize *

@item 
Les fonctions de l'API C @code{PyParser_SimpleParseStringFlags}, @code{PyParser_SimpleParseStringFlagsFilename}, @code{PyParser_SimpleParseFileFlags} et @code{PyNode_Compile} ainsi que @code{struct _node}, le type utilisé par ces fonctions, ont été retirés suite à la transition vers le nouvel analyseur syntaxique `PEG'.

Le code source doit maintenant être compilé directement en un objet code, en utilisant par exemple @ref{871,,Py_CompileString()}. L'objet code ainsi produit peut ensuite être évalué, en utilisant par exemple @ref{872,,PyEval_EvalCode()}.

Spécifiquement :


@itemize *

@item 
Un appel à @code{PyParser_SimpleParseStringFlags} suivi de @code{PyNode_Compile} peut être remplacé par @ref{871,,Py_CompileString()} ;

@item 
Il n'y a pas de remplacement immédiat pour @code{PyParser_SimpleParseFileFlags}. Pour compiler du code à partir d'un argument @code{FILE *}, vous devez lire le fichier en C et passer le tampon résultant à @ref{871,,Py_CompileString()}.

@item 
Pour compiler un fichier à partir du @code{char *} de son nom, ouvrez le fichier de façon explicite, lisez son contenu et compilez le résultat. Une façon de faire est d'utiliser le module @ref{7e,,io} en conjonction avec @ref{3b5,,PyImport_ImportModule()}, @ref{396,,PyObject_CallMethod()}, @ref{873,,PyBytes_AsString()} et @ref{871,,Py_CompileString()}, comme dans l'esquisse qui suit (les déclarations et la gestion d'erreurs ne sont pas incluses)

@example
io_module = Import_ImportModule("io");
fileobject = PyObject_CallMethod(io_module, "open", "ss", filename, "rb");
source_bytes_object = PyObject_CallMethod(fileobject, "read", "");
result = PyObject_CallMethod(fileobject, "close", "");
source_buf = PyBytes_AsString(source_bytes_object);
code = Py_CompileString(source_buf, filename, Py_file_input);
@end example

@item 
For @code{FrameObject} objects, the @ref{874,,f_lasti} member now represents a wordcode
offset instead of a simple offset into the bytecode string. This means that this
number needs to be multiplied by 2 to be used with APIs that expect a byte offset
instead (like @ref{875,,PyCode_Addr2Line()} for example). Notice as well that the
@code{f_lasti} member of @code{FrameObject} objects is not considered stable: please
use @ref{775,,PyFrame_GetLineNumber()} instead.
@end itemize
@end itemize

@node Changements au code intermédiaire CPython<3>,Changements à la compilation<4>,Portage vers Python 3 10,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 cpython-bytecode-changes}@anchor{876}
@subsection Changements au code intermédiaire CPython



@itemize *

@item 
The @code{MAKE_FUNCTION} instruction now accepts either a dict or a tuple of
strings as the function's annotations.
(Contributed by Yurii Karabas and Inada Naoki in bpo-42202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42202}.)
@end itemize

@node Changements à la compilation<4>,Changements à l'API C<4>,Changements au code intermédiaire CPython<3>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 build-changes}@anchor{877}
@subsection Changements à la compilation



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} : la version minimale d'`OpenSSL' pour Python est maintenant 1.1.1. `OpenSSL' 1.0.2 n'est plus prise en charge (contribution de `Christian Heimes' dans bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669}).

@item 
Les fonctions de `C99' @code{snprintf()} et @code{vsnprintf()} sont maintenant nécessaires à la compilation de Python (contribution de `Victor Stinner' dans bpo-36020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36020}).

@item 
La version minimale de SQLite pour le module @ref{ce,,sqlite3} est maintenant 3.7.15 (contribution de `Sergey Fedoseev' et `Erlend E. Aasland' dans bpo-40744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40744} et bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}).

@item 
Le module @ref{c,,atexit} doit maintenant toujours être compilé en tant que module natif (contribution de `Victor Stinner' dans bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}).

@item 
Ajout de l'option @ref{878,,--disable-test-modules} au script @code{configure} : ne pas compiler ni installer les modules de tests (contribution de `Xavier de Gaye', `Thomas Petazzoni' et `Peixing Xin' dans bpo-27640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27640}).

@item 
Ajout de l'option @ref{879,,--with-wheel-pkg-dir=PATH} au script @code{./configure}. Si elle est passée, le module @ref{54,,ensurepip} recherche les paquets `wheel' de @code{setuptools} et de @code{pip} dans ce répertoire : si les deux sont présents, ces paquets `wheel' sont utilisés plutôt que ceux inclus avec `ensurepip'.

La politique de paquets de certaines distributions Linux déconseille l'inclusion des dépendances. Par exemple, Fedora installe les paquets `wheel' dans le répertoire @code{/usr/share/python-wheels/} et n'installe pas le paquet @code{ensurepip._bundled}

(contribution de `Victor Stinner' dans bpo-42856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42856}).

@item 
Ajout d'une nouvelle option @ref{87a,,--without-static-libpython} au script @code{configure} pour ne pas compiler la bibliothèque statique @code{libpythonMAJOR.MINOR.a} et ne pas installer le fichier objet @code{python.o}

(contribution de `Victor Stinner' dans bpo-43103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43103}).

@item 
The @code{configure} script now uses the @code{pkg-config} utility, if available,
to detect the location of Tcl/Tk headers and libraries.  As before, those
locations can be explicitly specified with the @code{--with-tcltk-includes}
and @code{--with-tcltk-libs} configuration options.
(Contributed by Manolis Stamatogiannakis in bpo-42603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42603}.)

@item 
Ajout de l'option @ref{87b,,--with-openssl-rpath} au script @code{configure}. Cette option simplifie la compilation de Python avec une installation personnalisée d'OpenSSL, par exemple : @code{./configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto} (contribution de `Christian Heimes' dans bpo-43466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43466}).
@end itemize

@node Changements à l'API C<4>,Notable security feature in 3 10 7,Changements à la compilation<4>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 c-api-changes}@anchor{87c}
@subsection Changements à l'API C


@menu
* PEP 652 ; maintenance d'une ABI stable: PEP 652 maintenance d'une ABI stable. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<8>. 
* Portage vers Python 3.10: Portage vers Python 3 10<2>. 
* Obsolescence: Obsolescence<6>. 
* Retrait: Retrait<2>. 

@end menu

@node PEP 652 maintenance d'une ABI stable,Nouvelles fonctionnalités<8>,,Changements à l'API C<4>
@anchor{whatsnew/3 10 pep-652-maintaining-the-stable-abi}@anchor{87d}
@subsubsection PEP 652 : maintenance d'une ABI stable


L'interface binaire-programme (`Application Binary Interface', `ABI' en anglais) stable pour les modules d'extension ou pour l'intégration de Python est maintenant définie de façon explicite. Le document @ref{53e,,Stabilité de l’API C} décrit les garanties de stabilité pour l'API C et pour l'interface binaire-programme ainsi que les bonnes pratiques pour travailler avec l'interface binaire-programme stable

(contribution de `Petr Viktorin' dans 
@geindex Python Enhancement Proposals; PEP 652
PEP 652@footnote{https://peps.python.org/pep-0652/} et dans bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}).

@node Nouvelles fonctionnalités<8>,Portage vers Python 3 10<2>,PEP 652 maintenance d'une ABI stable,Changements à l'API C<4>
@anchor{whatsnew/3 10 id1}@anchor{87e}
@subsubsection Nouvelles fonctionnalités



@itemize *

@item 
Le résultat de @ref{87f,,PyNumber_Index()} est maintenant exactement de type @ref{254,,int}. Auparavant, le résultat pouvait être une instance d'une classe dérivée de @code{int} (contribution de `Serhiy Storchaka' dans bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792}).

@item 
Ajout d'un nouveau champ @ref{880,,orig_argv} à la structure @ref{39d,,PyConfig} : la liste des arguments de ligne de commande originalement passée à l'exécutable Python (contribution de `Victor Stinner' dans bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}).

@item 
Les macros @ref{881,,PyDateTime_DATE_GET_TZINFO()} et @ref{882,,PyDateTime_TIME_GET_TZINFO()} ont été ajoutées pour récupérer l'attribut @code{tzinfo} des objets @ref{1c7,,datetime.datetime} et @ref{1c9,,datetime.time} (contribution de `Zackery Spytz' dans bpo-30155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30155}).

@item 
Ajout d'une fonction @ref{883,,PyCodec_Unregister()} pour désinscrire une fonction de recherche de codecs (contribution de `Hai Shi' dans bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}).

@item 
Ajout de la fonction @ref{884,,PyIter_Send()} pour acheminer une valeur dans un itérateur sans lever une exception @code{StopIteration} (contribution de `Vladimir Matveev' dans bpo-41756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41756}).

@item 
Ajout de @ref{885,,PyUnicode_AsUTF8AndSize()} à l'API C limitée (contribution d'`Alex Gaynor' dans bpo-41784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41784}).

@item 
Ajout de la fonction @ref{35b,,PyModule_AddObjectRef()} : comparable à @ref{35c,,PyModule_AddObject()} mais ne s’accapare pas une référence à la valeur s'il y a réussite (contribution de `Victor Stinner' dans bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}).

@item 
Ajout des fonctions @ref{886,,Py_NewRef()} et @ref{887,,Py_XNewRef()} pour incrémenter le compteur des références d'un objet et renvoyer l'objet (contribution de `Victor Stinner' dans bpo-42262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42262}).

@item 
Les fonctions @ref{56a,,PyType_FromSpecWithBases()} et @ref{53c,,PyType_FromModuleAndSpec()} n'acceptent maintenant qu'une seule classe pour l'argument `bases' (contribution `Serhiy Storchaka' dans bpo-42423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42423}).

@item 
La fonction @ref{53c,,PyType_FromModuleAndSpec()} accepte maintenant @code{NULL} dans l'emplacement @code{tp_doc} (contribution de `Hai Shi' dans bpo-41832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41832}).

@item 
La fonction @ref{888,,PyType_GetSlot()} peut maintenant accepter des @ref{769,,types statiques} (contribution de `Hai Shi' et `Petr Viktorin' dans bpo-41073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41073}).

@item 
Ajout d'une nouvelle fonction @ref{889,,PySet_CheckExact()} à l'API C pour vérifier si un objet est une instance de @ref{5c3,,set} mais pas une instance d'un sous-type (contribution de `Pablo Galindo' dans bpo-43277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43277}).

@item 
Ajout de @ref{88a,,PyErr_SetInterruptEx()} qui accepte le numéro d'un signal à simuler (contribution d'`Antoine Pitrou' dans bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356}).

@item 
L'API C limitée est maintenant prise en charge si Python est compilé en @ref{1f6,,mode débogage} (si la macro @code{Py_DEBUG} est définie). Dans l'API C limitée, les fonctions @ref{55a,,Py_INCREF()} et @ref{55b,,Py_DECREF()} sont maintenant implémentées en appel de fonctions opaques, plutôt que d'accéder directement au champ @ref{88b,,PyObject.ob_refcnt}. C'est le cas si Python est compilé en mode débogage et que la macro @code{Py_LIMITED_API} vise Python 3.10 ou plus récent. Il est possible de prendre en charge l'API C limitée en mode débogage, car la structure @ref{32f,,PyObject} est la même dans les versions standard et dans les versions débogage depuis Python 3.8 (voir bpo-36465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36465}).

L'API C limitée n'est toujours pas prise en charge dans les compilations spéciales avec l'option @ref{38b,,--with-trace-refs} (macro @code{Py_TRACE_REFS}) (Contribution de `Victor Stinner' dans bpo-43688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43688}).

@item 
Ajout de la fonction @ref{88c,,Py_Is(x@comma{} y)} pour vérifier si l'objet `x' est l'objet `y', tout comme @code{x is y} en Python. Ajout aussi des fonctions @ref{88d,,Py_IsNone()}, @ref{88e,,Py_IsTrue()} et @ref{88f,,Py_IsFalse()} pour vérifier si l'objet est le singleton @code{None}, le singleton @code{True} ou le singleton @code{False}, respectivement (contribution de `Victor Stinner' dans bpo-43753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43753}).

@item 
Ajout de fonctions pour contrôler le ramasse-miettes en C : @ref{890,,PyGC_Enable()}, @ref{891,,PyGC_Disable()} et @ref{892,,PyGC_IsEnabled()}. Ces fonctions permettent d'activer, de désactiver et d'interroger l'état du ramasse-miettes dans du code C sans avoir à importer le module @ref{5f,,gc}.

@item 
Add a new @ref{56e,,Py_TPFLAGS_DISALLOW_INSTANTIATION} type flag to disallow
creating type instances.
(Contributed by Victor Stinner in bpo-43916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43916}.)

@item 
Add a new @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} type flag for creating immutable
type objects: type attributes cannot be set nor deleted.
(Contributed by Victor Stinner and Erlend E. Aasland in bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}.)
@end itemize

@node Portage vers Python 3 10<2>,Obsolescence<6>,Nouvelles fonctionnalités<8>,Changements à l'API C<4>
@anchor{whatsnew/3 10 id2}@anchor{893}
@subsubsection Portage vers Python 3.10



@itemize *

@item 
The @code{PY_SSIZE_T_CLEAN} macro must now be defined to use
@ref{55d,,PyArg_ParseTuple()} and @ref{894,,Py_BuildValue()} formats which use
@code{#}: @code{es#}, @code{et#}, @code{s#}, @code{u#}, @code{y#}, @code{z#}, @code{U#} and @code{Z#}.
See @ref{895,,Analyse des arguments et construction des valeurs} and 
@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/}.
(Contributed by Victor Stinner in bpo-40943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40943}.)

@item 
Étant donné la conversion de @ref{896,,Py_REFCNT()} en fonction statique en-ligne, @code{Py_REFCNT(obj) = new_refcnt} doit être remplacé par @code{Py_SET_REFCNT(obj, new_refcnt)} : voir @ref{897,,Py_SET_REFCNT()} (disponible depuis Python 3.9). Pour la rétro-compatibilité, cette macro peut être utilisée :

@example
#if PY_VERSION_HEX < 0x030900A4
#  define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0)
#endif
@end example

(contribution de `Victor Stinner' dans bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}).

@item 
Appeler @ref{37d,,PyDict_GetItem()} sans avoir obtenu le @ref{158,,GIL} était autorisé pour des raisons historiques. Ceci n'est plus permis (contribution de `Victor Stinner' dans bpo-40839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40839}).

@item 
@code{PyUnicode_FromUnicode(NULL, size)} et @code{PyUnicode_FromStringAndSize(NULL, size)} lèvent maintenant un @code{DeprecationWarning}. Vous devez utiliser @ref{898,,PyUnicode_New()} pour allouer un objet Unicode sans donnée initiale (contribution de `Inada Naoki' dans bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}).

@item 
La structure privée @code{_PyUnicode_Name_CAPI} de l'API PyCapsule @code{unicodedata.ucnhash_CAPI} a été déplacée dans l'API C interne. (Contribution par Victor Stinner dans bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}.)

@item 
@ref{3aa,,Py_GetPath()}, @ref{3ac,,Py_GetPrefix()}, @ref{3a8,,Py_GetExecPrefix()},
@ref{3ae,,Py_GetProgramFullPath()}, @ref{3b1,,Py_GetPythonHome()} and
@ref{3b0,,Py_GetProgramName()} functions now return @code{NULL} if called before
@ref{899,,Py_Initialize()} (before Python is initialized). Use the new
@ref{39e,,Python Initialization Configuration} API to get the @ref{89a,,Python Path Configuration}.
(Contributed by Victor Stinner in bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}.)

@item 
@ref{384,,PyList_SET_ITEM()}, @ref{383,,PyTuple_SET_ITEM()} and
@ref{89b,,PyCell_SET()} macros can no longer be used as l-value or r-value.
For example, @code{x = PyList_SET_ITEM(a, b, c)} and
@code{PyList_SET_ITEM(a, b, c) = x} now fail with a compiler error. It prevents
bugs like @code{if (PyList_SET_ITEM (a, b, c) < 0) ...} test.
(Contributed by Zackery Spytz and Victor Stinner in bpo-30459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30459}.)

@item 
The non-limited API files @code{odictobject.h}, @code{parser_interface.h},
@code{picklebufobject.h}, @code{pyarena.h}, @code{pyctype.h}, @code{pydebug.h},
@code{pyfpe.h}, and @code{pytime.h} have been moved to the @code{Include/cpython}
directory. These files must not be included directly, as they are already
included in @code{Python.h}; see @ref{76e,,Include Files}. If they have
been included directly, consider including @code{Python.h} instead.
(Contributed by Nicholas Sim in bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}.)

@item 
Use the @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} type flag to create immutable type
objects. Do not rely on @ref{89c,,Py_TPFLAGS_HEAPTYPE} to decide if a type
object is mutable or not; check if @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} is set
instead.
(Contributed by Victor Stinner and Erlend E. Aasland in bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}.)

@item 
The undocumented function @code{Py_FrozenMain} has been removed from the
limited API. The function is mainly useful for custom builds of Python.
(Contributed by Petr Viktorin in bpo-26241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26241}.)
@end itemize

@node Obsolescence<6>,Retrait<2>,Portage vers Python 3 10<2>,Changements à l'API C<4>
@anchor{whatsnew/3 10 id3}@anchor{89d}
@subsubsection Obsolescence



@itemize *

@item 
La fonction @code{PyUnicode_InternImmortal()} est maintenant obsolète et sera retirée dans Python 3.12 : utilisez plutôt @ref{89e,,PyUnicode_InternInPlace()} (contribution de `Victor Stinner' dans bpo-41692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41692}).
@end itemize

@node Retrait<2>,,Obsolescence<6>,Changements à l'API C<4>
@anchor{whatsnew/3 10 id4}@anchor{89f}
@subsubsection Retrait



@itemize *

@item 
Retrait des fonctions @code{Py_UNICODE_str*} manipulant des chaînes @code{Py_UNICODE*} (contribution de `Inada Naoki' dans bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}) :


@itemize *

@item 
@code{Py_UNICODE_strlen} : utilisez @ref{8a0,,PyUnicode_GetLength()} ou @ref{8a1,,PyUnicode_GET_LENGTH} ;

@item 
@code{Py_UNICODE_strcat} : utilisez @ref{8a2,,PyUnicode_CopyCharacters()} ou @ref{380,,PyUnicode_FromFormat()} ;

@item 
@code{Py_UNICODE_strcpy}, @code{Py_UNICODE_strncpy} : utilisez @ref{8a2,,PyUnicode_CopyCharacters()} ou @ref{8a3,,PyUnicode_Substring()} ;

@item 
@code{Py_UNICODE_strcmp} : utilisez @ref{8a4,,PyUnicode_Compare()} ;

@item 
@code{Py_UNICODE_strncmp} : utilisez @ref{8a5,,PyUnicode_Tailmatch()} ;

@item 
@code{Py_UNICODE_strchr}, @code{Py_UNICODE_strrchr} : utilisez @ref{8a6,,PyUnicode_FindChar()}.
@end itemize

@item 
Retrait de @code{PyUnicode_GetMax()}. Vous devez migrer vers les nouvelles API de la 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} (contribution de `Inada Naoki' dans bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}).

@item 
Retrait de @code{PyLong_FromUnicode()}. Vous devez migrer vers @ref{8a7,,PyLong_FromUnicodeObject()} (contribution de `Inada Naoki' dans bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}).

@item 
Retrait de @code{PyUnicode_AsUnicodeCopy()}. Vous devez utiliser @ref{8a8,,PyUnicode_AsUCS4Copy()} ou @ref{8a9,,PyUnicode_AsWideCharString()} (contribution de `Inada Naoki' dans bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}).

@item 
Retrait de la variable @code{_Py_CheckRecursionLimit} : elle a été remplacée par le champ @code{ceval.recursion_limit} de la structure @ref{8aa,,PyInterpreterState} (contribution de `Victor Stinner' dans bpo-41834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41834}).

@item 
Retrait des macros non-documentées @code{Py_ALLOW_RECURSION} et @code{Py_END_ALLOW_RECURSION} et du champ @code{recursion_critical} de la structure @ref{8aa,,PyInterpreterState} (contribution de `Serhiy Storchaka' dans bpo-41936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41936}).

@item 
Retrait de la fonction non-documentée @code{PyOS_InitInterrupts()}. L'initialisation de Python installe déjà les gestionnaires de signaux de façon implicite : voir @ref{8ab,,PyConfig.install_signal_handlers} (contribution de `Victor Stinner' dans bpo-41713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41713}).

@item 
Retrait de la fonction @code{PyAST_Validate()}. Il n'est plus possible de construire un objet `AST' (type @code{mod_ty}) avec l'API C publique. La fonction était déjà retirée de l'API C limitée (
@geindex Python Enhancement Proposals; PEP 384
PEP 384@footnote{https://peps.python.org/pep-0384/}) (contribution de `Victor Stinner' dans bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}).

@item 
Retrait du fichier d'en-tête @code{symtable.h} et des fonctions non-documentées :


@itemize *

@item 
@code{PyST_GetScope()} ;

@item 
@code{PySymtable_Build()} ;

@item 
@code{PySymtable_BuildObject()} ;

@item 
@code{PySymtable_Free()} ;

@item 
@code{Py_SymtableString()} ;

@item 
@code{Py_SymtableStringObject()}.
@end itemize

Par erreur, la fonction @code{Py_SymtableString()} faisait partie de l'`ABI' stable, mais elle ne pouvait pas être utilisée, car le fichier d'en-tête @code{symtable.h} était exclu de l'API C limitée.

Utilisez plutôt le module Python @ref{d7,,symtable} (contribution de `Victor Stinner' dans bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}).

@item 
Retrait de @ref{572,,PyOS_ReadlineFunctionPointer()} des fichiers d'en-tête de l'API C limitée et de @code{python3.dll}, la bibliothèque qui fournit l'`ABI' stable sur Windows. Étant donné que la fonction prend un @code{FILE*} en argument, la stabilité de son interface binaire-programme ne peut pas être garantie (contribution de `Petr Viktorin' dans bpo-43868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43868}).

@item 
Retrait des fichiers d'en-tête @code{ast.h}, @code{asdl.h} et @code{Python-ast.h}. Ces fonctions étaient non-documentées et exclues de l'API C limitée. La majorité des noms définis dans ces fichiers d'en-tête n'avaient pas le préfixe @code{Py} et pouvaient ainsi causer des conflits de noms. Par exemple, @code{Python-ast.h} définit une macro @code{Yield} qui était en conflit avec le nom @code{Yield} utilisé dans le fichier d'en-tête @code{<winbase.h>} de Windows. Utilisez plutôt le module Python @ref{8,,ast} (contribution de `Victor Stinner' dans bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}).

@item 
Retrait des fonctions d'analyse syntaxique et de compilation qui utilisent le type @code{struct _mod} car l'API C publique pour manipuler les `AST' a été retirée :


@itemize *

@item 
@code{PyAST_Compile()} ;

@item 
@code{PyAST_CompileEx()} ;

@item 
@code{PyAST_CompileObject()} ;

@item 
@code{PyFuture_FromAST()} ;

@item 
@code{PyFuture_FromASTObject()} ;

@item 
@code{PyParser_ASTFromFile()} ;

@item 
@code{PyParser_ASTFromFileObject()} ;

@item 
@code{PyParser_ASTFromFilename()} ;

@item 
@code{PyParser_ASTFromString()} ;

@item 
@code{PyParser_ASTFromStringObject()}.
@end itemize

Ces fonctions étaient non-documentées et exclues de l'API C limitée (contribution de `Victor Stinner' dans bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}).

@item 
Retrait du fichier d'en-tête @code{pyarena.h} et des fonctions :


@itemize *

@item 
@code{PyArena_New()} ;

@item 
@code{PyArena_Free()} ;

@item 
@code{PyArena_Malloc()} ;

@item 
@code{PyArena_AddPyObject()}.
@end itemize

Ces fonctions étaient non-documentées et exclues de l'API C limitée ; elles n'étaient utilisées que par le compilateur dans l'implémentation interne (contribution de `Victor Stinner' dans bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}).

@item 
Retrait du champ @code{PyThreadState.use_tracing} pour optimiser Python (contribution de `Mark Shannon' dans bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760}).
@end itemize

@node Notable security feature in 3 10 7,Notable security feature in 3 10 8,Changements à l'API C<4>,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 notable-security-feature-in-3-10-7}@anchor{8ac}
@subsection Notable security feature in 3.10.7


Converting between @ref{254,,int} and @ref{435,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{1ff,,ValueError} if the number of digits in string form is
above a limit to avoid potential denial of service attacks due to the
algorithmic complexity. This is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.
This limit can be configured or disabled by environment variable, command
line flag, or @ref{d8,,sys} APIs. See the @ref{5df,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node Notable security feature in 3 10 8,Notable changes in 3 10 12,Notable security feature in 3 10 7,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 notable-security-feature-in-3-10-8}@anchor{8ad}
@subsection Notable security feature in 3.10.8


The deprecated @code{mailcap} module now refuses to inject unsafe text
(filenames, MIME types, parameters) into shell commands. Instead of using such
text, it will warn and act as if a match was not found (or for test commands,
as if the test failed).
(Contributed by Petr Viktorin in gh-98966@footnote{https://github.com/python/cpython/issues/98966}.)

@node Notable changes in 3 10 12,,Notable security feature in 3 10 8,Les nouveautés de Python 3 10
@anchor{whatsnew/3 10 notable-changes-in-3-10-12}@anchor{8ae}
@subsection Notable changes in 3.10.12


@menu
* tarfile: tarfile<2>. 

@end menu

@node tarfile<2>,,,Notable changes in 3 10 12
@anchor{whatsnew/3 10 tarfile}@anchor{8af}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{dd,,tarfile}, and @ref{455,,shutil.unpack_archive()},
have a new a `filter' argument that allows limiting tar features than may be
surprising or dangerous, such as creating files outside the destination
directory.
See @ref{456,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@node Les nouveautés de Python 3 9,Nouveautés de Python 3 8,Les nouveautés de Python 3 10,Nouveautés de Python
@anchor{whatsnew/3 9 doc}@anchor{8b0}@anchor{whatsnew/3 9 what-s-new-in-python-3-9}@anchor{8b1}
@section Les nouveautés de Python 3.9


@*Éditeur: 
Łukasz Langa


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Your text might get
@c rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes will be too small
@c or esoteric to include.  If such a change is added to the text,
@c it might get removed during final editing.
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Mercurial log
@c when researching a change.

This article explains the new features in Python 3.9, compared to 3.8.
Python 3.9 was released on October 5, 2020.
For full details, see the @ref{13b,,changelog}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 596
PEP 596@footnote{https://peps.python.org/pep-0596/} – Calendrier de sortie de Python 3.9


@menu
* Résumé – Points marquants de cette version: Résumé – Points marquants de cette version<2>. 
* Vous devez vérifier la présence de DeprecationWarning dans votre code:: 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<9>. 
* Autres changements au langage: Autres changements au langage<5>. 
* Nouveaux modules: Nouveaux modules<5>. 
* Modules améliorés: Modules améliorés<5>. 
* Optimisations: Optimisations<5>. 
* Obsolescence: Obsolescence<7>. 
* Retraits: Retraits<5>. 
* Portage vers Python 3.9: Portage vers Python 3 9. 
* Changements à la compilation: Changements à la compilation<5>. 
* Changements à l'API C: Changements à l'API C<5>. 
* Changements importants dans Python 3.9.1: Changements importants dans Python 3 9 1. 
* Changements importants dans Python 3.9.2: Changements importants dans Python 3 9 2. 
* Notable changes in Python 3.9.3: Notable changes in Python 3 9 3. 
* Notable changes in Python 3.9.5: Notable changes in Python 3 9 5. 
* Notable security feature in 3.9.14: Notable security feature in 3 9 14. 
* Notable changes in 3.9.17: Notable changes in 3 9 17. 

@end menu

@node Résumé – Points marquants de cette version<2>,Vous devez vérifier la présence de DeprecationWarning dans votre code,,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 summary-release-highlights}@anchor{8b2}
@subsection Résumé – Points marquants de cette version


@c This section singles out the most important changes in Python 3.9.
@c Brevity is key.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}, ajout de l'opérateur d'union à @code{dict} ;

@item 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}, indications des types paramétrables dans les collections natives ;

@item 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/}, restrictions grammaticales assouplies pour les décorateurs.
@end itemize

Nouvelles fonctionnalités natives :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 616
PEP 616@footnote{https://peps.python.org/pep-0616/}, méthodes sur les chaînes pour enlever des préfixes et des suffixes.
@end itemize

Nouvelles fonctionnalités dans la bibliothèque standard :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/}, annotations flexibles pour les fonctions et les variables ;

@item 
ajout de @ref{464,,os.pidfd_open()} qui permet la gestion de processus sans concurrence critique et sans signaux.
@end itemize

Améliorations de l'interpréteur :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/}, accès rapide à l'état des modules à partir des méthodes des types dans les extensions C ;

@item 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/}, CPython utilise maintenant un analyseur lexical `PEG' (`Parsing Expression Grammar') ;

@item 
certains types Python natifs (`range', `tuple', `set', `frozenset', `list', `dict') sont maintenant plus rapides grâce aux appels `vectorcall' (
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}) ;

@item 
le ramasse-miettes ne bloque pas sur les objets ressuscités ;

@item 
a number of Python modules (@code{_abc}, @code{audioop}, @code{_bz2},
@code{_codecs}, @code{_contextvars}, @code{_crypt}, @code{_functools},
@code{_json}, @code{_locale}, @ref{8d,,math}, @ref{9e,,operator}, @ref{bb,,resource},
@ref{ed,,time}, @code{_weakref}) now use multiphase initialization as defined
by PEP 489;

@item 
a number of standard library modules (@code{audioop}, @ref{8,,ast}, @ref{65,,grp},
@code{_hashlib}, @ref{b1,,pwd}, @code{_posixsubprocess}, @ref{b7,,random},
@ref{c0,,select}, @ref{d4,,struct}, @ref{e0,,termios}, @ref{132,,zlib}) are now using
the stable ABI defined by PEP 384.
@end itemize

Nouveaux modules de la bibliothèque :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 615
PEP 615@footnote{https://peps.python.org/pep-0615/}, la base de données des fuseaux horaires de l'IANA est maintenant incluse dans le module @ref{133,,zoneinfo} de la bibliothèque standard ;

@item 
une implémentation du tri topologique d'un graphe est maintenant disponible dans le nouveau module @ref{64,,graphlib}.
@end itemize

Changements aux procédures de publication :


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 602
PEP 602@footnote{https://peps.python.org/pep-0602/}, CPython adopte un cycle annuel de publications.
@end itemize

@node Vous devez vérifier la présence de DeprecationWarning dans votre code,Nouvelles fonctionnalités<9>,Résumé – Points marquants de cette version<2>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 you-should-check-for-deprecationwarning-in-your-code}@anchor{8b3}
@subsection Vous devez vérifier la présence de @code{DeprecationWarning} dans votre code


Quand Python 2.7 était encore pris en charge, plusieurs fonctionnalités dans Python 3 étaient gardées pour la rétro-compatibilité avec Python 2.7. Avec la fin de la prise en charge de Python 2, ces couches de rétro-compatibilité ont été retirées ou le seront bientôt. La plupart d'entre elles émettaient un avertissement @ref{1a3,,DeprecationWarning} depuis plusieurs années. Par exemple, utiliser @code{collections.Mapping} plutôt que @code{collections.abc.Mapping} émettait un @ref{1a3,,DeprecationWarning} depuis Python 3.3, publié en 2012.

Testez votre application avec l'option de ligne de commande @ref{8b4,,-W} @code{default} pour voir les @ref{1a3,,DeprecationWarning} et les @ref{8b5,,PendingDeprecationWarning}, ou même avec @ref{8b4,,-W} @code{error} pour les traiter comme des erreurs. @ref{8b6,,Le filtre des avertissements} peut être utilisé pour ignorer les avertissements provenant de code de tierces parties.

Python 3.9 est la dernière version qui fournit ces couches de rétro compatibilité avec Python 2, afin de donner plus de temps aux mainteneurs de projets Python pour organiser l'arrêt de la prise en charge de Python 2 et pour assurer celle de Python 3.9.

Les alias vers @ref{863,,Abstract Base Classes} dans le module @ref{1d,,collections}, comme l'alias @code{collections.Mapping} vers @ref{8b7,,collections.abc.Mapping}, sont conservés pour une dernière version au titre de la rétrocompatibilité. Ils seront supprimés de Python 3.10.

Plus généralement, essayez d'exécuter vos tests dans le @ref{1f5,,Python Development Mode} qui aide à préparer votre code pour le rendre compatible avec la prochaine version de Python.

Note : certaines déclarations d’obsolescence pré-existantes ont été retirées de cette version de Python. Voir la section @ref{8b8,,Retraits}.

@node Nouvelles fonctionnalités<9>,Autres changements au langage<5>,Vous devez vérifier la présence de DeprecationWarning dans votre code,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 new-features}@anchor{8b9}
@subsection Nouvelles fonctionnalités


@menu
* Opérateurs de fusion et de mise à jour de dictionnaires:: 
* Nouvelles méthodes sur les chaînes pour retirer des préfixes et des suffixes:: 
* Indication des types paramétrables dans les collections natives:: 
* Nouvel analyseur syntaxique:: 

@end menu

@node Opérateurs de fusion et de mise à jour de dictionnaires,Nouvelles méthodes sur les chaînes pour retirer des préfixes et des suffixes,,Nouvelles fonctionnalités<9>
@anchor{whatsnew/3 9 dictionary-merge-update-operators}@anchor{8ba}
@subsubsection Opérateurs de fusion et de mise à jour de dictionnaires


Ajout des opérateurs de fusion (@code{|}) et de mise-à-jour (@code{|=}) à la classe native @ref{253,,dict}. Ils viennent compléter les méthodes existantes @code{dict.update} et @code{@{**d1, **d2@}} pour fusionner des dictionnaires.

Exemple :

@example
>>> x = @{"key1": "value1 from x", "key2": "value2 from x"@}
>>> y = @{"key2": "value2 from y", "key3": "value3 from y"@}
>>> x | y
@{'key1': 'value1 from x', 'key2': 'value2 from y', 'key3': 'value3 from y'@}
>>> y | x
@{'key2': 'value2 from x', 'key3': 'value3 from y', 'key1': 'value1 from x'@}
@end example

Voir 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} pour une description complète (contribution de `Brandt Bucher' dans bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}).

@node Nouvelles méthodes sur les chaînes pour retirer des préfixes et des suffixes,Indication des types paramétrables dans les collections natives,Opérateurs de fusion et de mise à jour de dictionnaires,Nouvelles fonctionnalités<9>
@anchor{whatsnew/3 9 new-string-methods-to-remove-prefixes-and-suffixes}@anchor{8bb}
@subsubsection Nouvelles méthodes sur les chaînes pour retirer des préfixes et des suffixes


@ref{8bc,,str.removeprefix(préfixe)} et @ref{8bd,,str.removesuffix(suffixe)} ont été ajoutées pour supprimer facilement un préfixe ou un suffixe inutile d'une chaîne. Les méthodes correspondantes de @code{bytes}, @code{bytearray} et @code{collections.UserString} ont également été ajoutées. Voir 
@geindex Python Enhancement Proposals; PEP 616
PEP 616@footnote{https://peps.python.org/pep-0616/} pour une description complète (contribution de `Dennis Sweeney' dans bpo-39939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39939}).

@node Indication des types paramétrables dans les collections natives,Nouvel analyseur syntaxique,Nouvelles méthodes sur les chaînes pour retirer des préfixes et des suffixes,Nouvelles fonctionnalités<9>
@anchor{whatsnew/3 9 type-hinting-generics-in-standard-collections}@anchor{8be}
@subsubsection Indication des types paramétrables dans les collections natives


Dans les annotations de type, vous pouvez maintenant utiliser les types de collection natifs tels que @code{list} et @code{dict} comme types génériques au lieu d'importer les types en majuscules correspondants (par exemple @code{List} ou @code{Dict}) à partir de @code{typing}.  D'autres types de la bibliothèque standard sont maintenant génériques, par exemple @code{queue.Queue}.

Exemple :

@example
def greet_all(names: list[str]) -> None:
    for name in names:
        print("Hello", name)
@end example

Voir 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} pour plus de détails (contribution de `Guido van Rossum', `Ethan Smith' et `Batuhan Taşkaya' dans bpo-39481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39481}).

@node Nouvel analyseur syntaxique,,Indication des types paramétrables dans les collections natives,Nouvelles fonctionnalités<9>
@anchor{whatsnew/3 9 new-parser}@anchor{8bf}
@subsubsection Nouvel analyseur syntaxique


Python 3.9 utilise un nouvel analyseur syntaxique, basé sur PEG@footnote{https://en.wikipedia.org/wiki/Parsing_expression_grammar} au lieu de LL(1)@footnote{https://fr.wikipedia.org/wiki/Analyse_LL}. Les performances du nouvel analyseur sont à peu près comparables à celles de l'ancien, mais le formalisme `PEG' est plus souple que `LL(1)' lorsqu'il s'agit de concevoir des nouvelles fonctionnalités du langage. Nous commencerons à utiliser cette flexibilité dans Python 3.10 et les versions suivantes.

Le module @ref{8,,ast} utilise le nouvel analyseur syntaxique et produit le même AST que l'ancien analyseur.

In Python 3.10, the old parser will be deleted and so will all
functionality that depends on it (primarily the @code{parser} module,
which has long been deprecated).  In Python 3.9 `only', you can switch
back to the LL(1) parser using a command line switch (@code{-X
oldparser}) or an environment variable (@code{PYTHONOLDPARSER=1}).

Voir 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} pour plus de détails (contribution de `Guido van Rossum', `Pablo Galindo' et `Lysandros Nikolaou' dans bpo-40334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40334}).

@node Autres changements au langage<5>,Nouveaux modules<5>,Nouvelles fonctionnalités<9>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 other-language-changes}@anchor{8c0}
@subsection Autres changements au langage



@itemize *

@item 
@ref{8c1,,__import__()} lève maintenant @ref{40f,,ImportError} plutôt que @ref{1ff,,ValueError}, ce qui se produisait lorsqu’un import relatif remontait plus loin que le répertoire racine du paquet (contribution de `Ngalim Siregar' dans bpo-37444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37444}).

@item 
Python récupère maintenant le chemin absolu du nom de fichier du script spécifié sur la ligne de commande (ex. : @code{python3 script.py}) : l'attribut @code{__file__} du module @ref{1,,__main__} est devenu un chemin absolu, plutôt qu'un chemin relatif. Ces nouveaux chemins restent valides même après que le répertoire courant est changé par @ref{5f8,,os.chdir()}. En conséquence, les traces d'appels affichent le chemin absolu pour les cadres du module @ref{1,,__main__} dans ce cas (contribution de `Victor Stinner' dans bpo-20443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20443}).

@item 
Dans le @ref{1f5,,mode de développement de Python} et dans les @ref{1f6,,compilations en mode débogage}, les arguments `encoding' et `errors' sont maintenant vérifiés pour les opérations d'encodage et de décodage de chaînes. Exemples : @ref{505,,open()}, @ref{8c2,,str.encode()} et @ref{8c3,,bytes.decode()}.

Par défaut, afin d'améliorer les performances, l'argument `errors' n'est consulté qu'au moment de la première erreur d'encodage-décodage et l'argument `encoding' est parfois ignoré pour les chaînes vides (contribution de `Victor Stinner' dans bpo-37388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37388}).

@item 
@code{"".replace("", s, n)} renvoie maintenant @code{s} plutôt qu'une chaîne vide pour toute valeur non-nulles de @code{n}. Ce comportement est maintenant cohérent avec @code{"".replace("", s)}. Les instances de @ref{1bd,,bytes} et @ref{528,,bytearray} ont le même comportement (contribution de `Serhiy Storchaka' dans bpo-28029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28029}).

@item 
Toute expression valide peut maintenant être utilisée comme décorateur (voir @ref{71b,,decorator}). Préalablement, la grammaire était beaucoup plus contraignante. Voir 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/} pour les détails (contributions de `Brandt Bucher' dans bpo-39702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39702}).

@item 
Aide améliorée pour le module @ref{103,,typing}. La documentation est maintenant visible pour toutes les formes spéciales et les alias générique spéciaux (comme @code{Union} et @code{List}). Utiliser @ref{8c4,,help()} sur un alias générique comme @code{List[int]} montre l'aide correspondant au type réel (@code{list} dans ce cas). (Contribution de Serhiy Storchaka dans bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}).

@item 
L'exécution parallèle de @ref{8c5,,aclose()} / @ref{8c6,,asend()} / @ref{4e3,,athrow()} est maintenant interdite, et @code{ag_running} reflète maintenant le statut réel du générateur asynchrone. (Contribué par Yury Selivanov dans bpo-30773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30773}.)

@item 
Les erreurs inattendues lors d'un appel de la méthode @code{__iter__} ne sont plus masquées par @code{TypeError} dans l'opérateur @ref{2e8,,in} et les fonctions @ref{8c7,,contains()}, @ref{8c8,,indexOf()} et @ref{8c9,,countOf()} du module @ref{9e,,operator}. (Contribué par Serhiy Storchaka dans bpo-40824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40824}.)

@item 
Les expressions lambda sans parenthèses ne peuvent plus être la partie expression dans une clause @code{if} dans les compréhensions de liste et les expressions de générateur. Voir bpo-41848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41848} et bpo-43755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43755} pour plus de détails.
@end itemize

@node Nouveaux modules<5>,Modules améliorés<5>,Autres changements au langage<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 new-modules}@anchor{8ca}
@subsection Nouveaux modules


@menu
* zoneinfo:: 
* graphlib:: 

@end menu

@node zoneinfo,graphlib,,Nouveaux modules<5>
@anchor{whatsnew/3 9 zoneinfo}@anchor{8cb}
@subsubsection `zoneinfo'


Le module @ref{133,,zoneinfo} ajoute la prise en charge de la base de donnée des fuseaux horaires de l'IANA dans la bibliothèque standard. Il ajoute @ref{8cc,,zoneinfo.ZoneInfo}, une implémentation concrète de @ref{5c8,,datetime.tzinfo} à partir des données de fuseaux horaires du système.

Exemple :

@example
>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> # Daylight saving time
>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'

>>> # Standard time
>>> dt += timedelta(days=7)
>>> print(dt)
2020-11-07 12:00:00-08:00
>>> print(dt.tzname())
PST
@end example

As a fall-back source of data for platforms that don't ship the IANA database,
the tzdata@footnote{https://pypi.org/project/tzdata/} module was released as a first-party package -- distributed via
PyPI and maintained by the CPython core team.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 615

@item PEP 615@footnote{https://peps.python.org/pep-0615/} — Prise en charge de la base de donnée des fuseaux horaires de l'IANA dans la bibliothèque standard

PEP écrit et implémenté par `Paul Ganssle'
@end table


@node graphlib,,zoneinfo,Nouveaux modules<5>
@anchor{whatsnew/3 9 graphlib}@anchor{8cd}
@subsubsection `graphlib'


Un nouveau module, @ref{64,,graphlib}, a été ajouté. Il contient la classe @ref{8ce,,graphlib.TopologicalSorter} qui offre des fonctionnalités pour faire le tri topologique de graphes (contribution de `Pablo Galindo', `Tim Peters' et `Larry Hastings' dans bpo-17005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17005}).

@node Modules améliorés<5>,Optimisations<5>,Nouveaux modules<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 improved-modules}@anchor{8cf}
@subsection Modules améliorés


@menu
* ast: ast<2>. 
* asyncio: asyncio<5>. 
* compileall: compileall<2>. 
* concurrent.futures: concurrent futures<2>. 
* curses: curses<2>. 
* datetime: datetime<2>. 
* distutils: distutils<3>. 
* fcntl: fcntl<2>. 
* ftplib: ftplib<2>. 
* gc: gc<2>. 
* hashlib: hashlib<4>. 
* http:: 
* IDLE et idlelib: IDLE et idlelib<3>. 
* imaplib:: 
* importlib: importlib<3>. 
* inspect: inspect<4>. 
* ipaddress: ipaddress<2>. 
* math: math<4>. 
* multiprocessing: multiprocessing<2>. 
* nntplib:: 
* os: os<5>. 
* pathlib: pathlib<6>. 
* pdb: pdb<3>. 
* poplib:: 
* pprint: pprint<2>. 
* pydoc:: 
* random: random<3>. 
* signal:: 
* smtplib:: 
* socket: socket<3>. 
* time: time<3>. 
* sys: sys<6>. 
* tracemalloc:: 
* typing: typing<6>. 
* unicodedata: unicodedata<4>. 
* venv: venv<3>. 
* xml: xml<3>. 

@end menu

@node ast<2>,asyncio<5>,,Modules améliorés<5>
@anchor{whatsnew/3 9 ast}@anchor{8d0}
@subsubsection `ast'


Ajout de l'option `indent' à @ref{8d1,,dump()} qui permet de produire une sortie multi-ligne indentée (contribution de `Serhiy Storchaka' dans bpo-37995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37995}).

Ajout de la fonction @ref{8d2,,ast.unparse()} au module @ref{8,,ast} pour renverser l'analyse syntaxique d'un objet @ref{1a4,,ast.AST} et produire une chaîne de code qui produirait un @ref{1a4,,ast.AST} équivalent lorsqu'il est analysé (contribution de `Pablo Galindo' et `Batuhan Taskaya' dans bpo-38870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38870}).

Ajout de chaînes de documentation aux nœuds AST qui contiennent les signatures `ASDL' utilisées pour construire ce nœud (contribution de `Batuhan Taskaya' dans bpo-39638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39638}).

@node asyncio<5>,compileall<2>,ast<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 asyncio}@anchor{8d3}
@subsubsection `asyncio'


En raison de problèmes de sécurité importants, le paramètre `reuse_address' de @ref{71d,,asyncio.loop.create_datagram_endpoint()} n'est plus supporté. C'est à cause du comportement de l'option socket @code{SO_REUSEADDR} en UDP. Pour plus de détails, voir la documentation de @code{loop.create_datagram_endpoint()}. (Contribué par Kyle Stanley, Antoine Pitrou, et Yury Selivanov dans bpo-37228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37228}.)

Ajout d'une nouvelle @ref{47b,,coroutine} @ref{8d4,,shutdown_default_executor()} qui programme une extinction de l'exécuteur par défaut qui attend que @ref{72c,,ThreadPoolExecutor} se termine. Aussi, @ref{466,,asyncio.run()} à été mis à jour pour utiliser la nouvelle @ref{47b,,coroutine}. (Contribué par Kyle Stanley dans bpo-34037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34037}.)

Ajout de @ref{463,,asyncio.PidfdChildWatcher}, un surveillant de processus enfants spécifique à Linux qui interroge le descripteur de ficher du processus. (bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692})

Added a new @ref{47b,,coroutine} @ref{8d5,,asyncio.to_thread()}. It is mainly used for
running IO-bound functions in a separate thread to avoid blocking the event
loop, and essentially works as a high-level version of
@ref{8d6,,run_in_executor()} that can directly take keyword arguments.
(Contributed by Kyle Stanley and Yury Selivanov in bpo-32309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32309}.)

When cancelling the task due to a timeout, @ref{5ea,,asyncio.wait_for()} will now
wait until the cancellation is complete also in the case when `timeout' is
<= 0, like it does with positive timeouts.
(Contributed by Elvis Pranskevichus in bpo-32751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32751}.)

@ref{a,,asyncio} now raises @ref{522,,TypeError} when calling incompatible
methods with an @ref{8d7,,ssl.SSLSocket} socket.
(Contributed by Ido Michael in bpo-37404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37404}.)

@node compileall<2>,concurrent futures<2>,asyncio<5>,Modules améliorés<5>
@anchor{whatsnew/3 9 compileall}@anchor{8d8}
@subsubsection `compileall'


Ajout de la possibilité d'utiliser des liens physiques pour les fichiers @code{.pyc} dupliqués : paramètre `hardlink_dupes' et option de ligne de commande @code{--hardlink-dupes} (contribution de `Lumír 'Frenzy' Balhar' dans bpo-40495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40495}).

Ajout d'options pour manipuler les chemins des fichiers @code{.pyc} résultants : paramètres `stripdir', `prependdir', `limit_sl_dest' et options de la ligne de commande @code{-s}, @code{-p}, @code{-e}. Ajout de la possibilité de spécifier l'option pour un niveau d'optimisation plus d'une fois (contribution de `Lumír 'Frenzy' Balhar' dans bpo-38112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38112}).

@node concurrent futures<2>,curses<2>,compileall<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 concurrent-futures}@anchor{8d9}
@subsubsection `concurrent.futures'


Ajout du nouveau paramètre `cancel_futures' à @ref{8da,,concurrent.futures.Executor.shutdown()} qui annule tous les futurs en attente qui n'ont pas commencé leur exécution, plutôt que d'attendre qu'ils aient complété avant d'arrêter l'exécuteur (contribution `Kyle Stanley' dans bpo-39349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39349}).

Removed daemon threads from @ref{72c,,ThreadPoolExecutor}
and @ref{8db,,ProcessPoolExecutor}. This improves
compatibility with subinterpreters and predictability in their shutdown
processes. (Contributed by Kyle Stanley in bpo-39812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39812}.)

Workers in @ref{8db,,ProcessPoolExecutor} are now spawned on
demand, only when there are no available idle workers to reuse. This optimizes
startup overhead and reduces the amount of lost CPU time to idle workers.
(Contributed by Kyle Stanley in bpo-39207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39207}.)

@node curses<2>,datetime<2>,concurrent futures<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 curses}@anchor{8dc}
@subsubsection `curses'


Ajout des fonctions @ref{8dd,,curses.get_escdelay()}, @ref{8de,,curses.set_escdelay()}, @ref{8df,,curses.get_tabsize()}, et @ref{8e0,,curses.set_tabsize()} (contribution d'`Anthony Sottile' dans bpo-38312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38312}).

@node datetime<2>,distutils<3>,curses<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 datetime}@anchor{8e1}
@subsubsection `datetime'


The @ref{8e2,,isocalendar()} of @ref{1c8,,datetime.date}
and @ref{8e3,,isocalendar()} of @ref{1c7,,datetime.datetime}
methods now returns a @ref{1c5,,namedtuple()} instead of a @ref{366,,tuple}.
(Contributed by Donghee Na in bpo-24416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24416}.)

@node distutils<3>,fcntl<2>,datetime<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 distutils}@anchor{8e4}
@subsubsection `distutils'


La commande @code{upload} crée maintenant des condensats SHA2-256 et Blake2b-256. Elle ne produit pas MD5 sur les plateformes qui bloquent les condensats MD5 (contribution de `Christian Heimes' dans bpo-40698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40698}).

@node fcntl<2>,ftplib<2>,distutils<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 fcntl}@anchor{8e5}
@subsubsection `fcntl'


Added constants @code{F_OFD_GETLK}, @code{F_OFD_SETLK}
and @code{F_OFD_SETLKW}.
(Contributed by Donghee Na in bpo-38602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38602}.)

@node ftplib<2>,gc<2>,fcntl<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 ftplib}@anchor{8e6}
@subsubsection `ftplib'


@ref{8e7,,FTP} and @ref{8e8,,FTP_TLS} now raise a @ref{1ff,,ValueError}
if the given timeout for their constructor is zero to prevent the creation of
a non-blocking socket. (Contributed by Donghee Na in bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}.)

@node gc<2>,hashlib<4>,ftplib<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 gc}@anchor{8e9}
@subsubsection `gc'


Quand le ramasse-miettes fait un ramassage pour lequel certains objets sont ressuscités (ils sont atteignables à partir de l'extérieur des cycles isolés après que les `finaliseurs' soient exécutés), le ramassage des objets qui sont toujours inatteignables n'est pas suspendu (contribution de `Pablo Galindo' et `Tim Peters' dans bpo-38379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38379}).

Ajout de la fonction @ref{8ea,,gc.is_finalized()} pour vérifier si un objet a été finalisé par le ramasse-miettes (contribution de `Pablo Galindo' dans bpo-39322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39322}).

@node hashlib<4>,http,gc<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 hashlib}@anchor{8eb}
@subsubsection `hashlib'


Le module @ref{67,,hashlib} peut maintenant utiliser les algorithmes de hachage SHA3 et SHAKE XOF de `OpenSSL' quand ils sont disponibles (contribution de `Christian Heimes' dans bpo-37630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37630}).

Les modules de hachage natifs peuvent être désactivés avec @code{./configure --without-builtin-hashlib-hashes} ou activés sélectivement avec par exemple @code{./configure --with-builtin-hashlib-hashes=sha3,blake2} pour forcer l'utilisation de l’implémentation `OpenSSL' (contribution de `Christian Heimes' dans bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}).

@node http,IDLE et idlelib<3>,hashlib<4>,Modules améliorés<5>
@anchor{whatsnew/3 9 http}@anchor{8ec}
@subsubsection `http'


HTTP status codes @code{103 EARLY_HINTS}, @code{418 IM_A_TEAPOT} and @code{425 TOO_EARLY} are added to
@ref{8ed,,http.HTTPStatus}. (Contributed by Donghee Na in bpo-39509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39509} and Ross Rhodes in bpo-39507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39507}.)

@node IDLE et idlelib<3>,imaplib,http,Modules améliorés<5>
@anchor{whatsnew/3 9 idle-and-idlelib}@anchor{8ee}
@subsubsection `IDLE' et `idlelib'


Ajout d'une option pour désactiver le clignotement du curseur (contribution de `Zackery Spytz' dans bpo-4603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4603}).

La fenêtre de complétion de IDLE est maintenant fermée par la touche d'échappement (contribution de `Johnny Najera' dans bpo-38944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38944}).

Ajout de mots clés à la liste de complétion de noms de modules (contribution de `Terry J. Reedy' dans bpo-37765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37765}).

New in 3.9 maintenance releases

IDLE invoque maintenant @ref{7f5,,sys.excepthook()} (lorsque lancé sans @code{'-n'}). Auparavant, les fonctions de rappel définies par l'utilisateur étaient ignorées (contribution par `Ken Hilton' dans bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008}).

Les changements ci-haut ont été rétro-portés dans la version de maintenance de 3.8.

Rearrange the settings dialog.  Split the General tab into Windows
and Shell/Ed tabs.  Move help sources, which extend the Help menu, to the
Extensions tab.  Make space for new options and shorten the dialog. The
latter makes the dialog better fit small screens.  (Contributed by Terry Jan
Reedy in bpo-40468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40468}.)  Move the indent space setting from the Font tab to
the new Windows tab.  (Contributed by Mark Roseman and Terry Jan Reedy in
bpo-33962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33962}.)

Applique la coloration syntaxique aux fichiers @code{.pyi} (contribution d'`Alex Waygood' et de `Terry Jan Reedy' dans bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447}).

@node imaplib,importlib<3>,IDLE et idlelib<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 imaplib}@anchor{8ef}
@subsubsection `imaplib'


@ref{8f0,,IMAP4} and @ref{8f1,,IMAP4_SSL} now have
an optional `timeout' parameter for their constructors.
Also, the @ref{8f2,,open()} method now has an optional `timeout' parameter
with this change. The overridden methods of @ref{8f1,,IMAP4_SSL} and
@ref{8f3,,IMAP4_stream} were applied to this change.
(Contributed by Donghee Na in bpo-38615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38615}.)

@ref{8f4,,imaplib.IMAP4.unselect()} is added.
@ref{8f4,,imaplib.IMAP4.unselect()} frees server's resources associated with the
selected mailbox and returns the server to the authenticated
state. This command performs the same actions as @ref{8f5,,imaplib.IMAP4.close()}, except
that no messages are permanently removed from the currently
selected mailbox. (Contributed by Donghee Na in bpo-40375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40375}.)

@node importlib<3>,inspect<4>,imaplib,Modules améliorés<5>
@anchor{whatsnew/3 9 importlib}@anchor{8f6}
@subsubsection `importlib'


Pour plus de cohérence avec les instructions d'import, @ref{8f7,,importlib.util.resolve_name()} lève maintenant @ref{40f,,ImportError} plutôt que @ref{1ff,,ValueError} pour les tentatives d'import relatifs invalides (contribution de `Ngalim Siregar' dans bpo-37444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37444}).

Les chargeurs d'importation qui publient des objets modules immuables peuvent maintenant aussi publier des paquets immuables en plus des modules individuels (contribution de `Dino Viehland' dans bpo-39336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39336}).

Ajout de la fonction @ref{478,,importlib.resources.files()} qui prend en charge les sous-répertoires dans les données du paquet. Aussi rétro-porté pour les version précédentes de Python dans @code{importlib_resources} version 1.5 (contribution de `Jason R. Coombs' dans bpo-39791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39791}).

Mise à jour de @code{importlib.metadata} à partir de @code{importlib_metadata} version 1.6.1.

@node inspect<4>,ipaddress<2>,importlib<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 inspect}@anchor{8f8}
@subsubsection `inspect'


@ref{8f9,,inspect.BoundArguments.arguments}, qui était un @code{OrderedDict}, devient un @code{dict} natif régulier (contribution de `Inada Naoki' dans bpo-36350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36350} et bpo-39775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39775}).

@node ipaddress<2>,math<4>,inspect<4>,Modules améliorés<5>
@anchor{whatsnew/3 9 ipaddress}@anchor{8fa}
@subsubsection `ipaddress'


@ref{7f,,ipaddress} prend désormais en charge les IPv6 avec une portée spécifiée (adresses IPv6 avec un suffixe @code{%<scope_id>}).

Les adresses IPv6 avec une portée spécifiée peuvent être analysées avec @ref{1fa,,ipaddress.IPv6Address}. S'il est présent, l'indice de la zone de la portée est disponible dans l'attribut @ref{8fb,,scope_id} (contribution de `Oleksandr Pavliuk' dans bpo-34788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34788}).

À partir de Python 3.9.5, le module @ref{7f,,ipaddress} n'accepte plus aucun zéro en tête des chaînes de caractères IPv4. (Contribué par Christian Heimes dans bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}).

@node math<4>,multiprocessing<2>,ipaddress<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 math}@anchor{8fc}
@subsubsection `math'


Extension de la fonction @ref{8fd,,math.gcd()} pour gérer les arguments multiples. Préalablement, elle ne gérait que deux arguments (contribution de `Serhiy Storchaka' dans bpo-39648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39648}).

Ajout de @ref{8fe,,math.lcm()} : renvoie le plus petit commun multiple des arguments spécifiés (contribution de `Mark Dickinson', `Ananthakrishnan' et `Serhiy Storchaka' dans bpo-39479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39479} et bpo-39648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39648}).

Ajout de @ref{482,,math.nextafter()} : renvoie la prochaine valeur à point flottant après `x' en direction de `y' (contribution de `Victor Stinner' dans bpo-39288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39288}).

Ajout de @ref{8ff,,math.ulp()} : renvoie la valeur du bit le moins significatif d'un `float' (contribution de `Victor Stinner' dans bpo-39310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39310}).

@node multiprocessing<2>,nntplib,math<4>,Modules améliorés<5>
@anchor{whatsnew/3 9 multiprocessing}@anchor{900}
@subsubsection `multiprocessing'


La classe @ref{901,,multiprocessing.SimpleQueue} a une nouvelle méthode @ref{902,,close()} pour fermer la queue de façon explicite (contribution de `Victor Stinner' dans bpo-30966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30966}).

@node nntplib,os<5>,multiprocessing<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 nntplib}@anchor{903}
@subsubsection `nntplib'


@code{NNTP} and @code{NNTP_SSL} now raise a @ref{1ff,,ValueError}
if the given timeout for their constructor is zero to prevent the creation of
a non-blocking socket. (Contributed by Donghee Na in bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}.)

@node os<5>,pathlib<6>,nntplib,Modules améliorés<5>
@anchor{whatsnew/3 9 os}@anchor{904}
@subsubsection `os'


Added @ref{905,,CLD_KILLED} and @ref{906,,CLD_STOPPED} for @code{si_code}.
(Contributed by Donghee Na in bpo-38493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38493}.)

Exposed the Linux-specific @ref{464,,os.pidfd_open()} (bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}) and
@ref{907,,os.P_PIDFD} (bpo-38713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38713}) for process management with file
descriptors.

La fonction @ref{908,,os.unsetenv()} est maintenant aussi disponible sur Windows (contribution de `Victor Stinner' dans bpo-39413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39413}).

Les fonctions @ref{909,,os.putenv()} et @ref{908,,os.unsetenv()} sont maintenant toujours disponibles (contribution de `Victor Stinner' dans bpo-39395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39395}).

Ajout de la fonction @ref{90a,,os.waitstatus_to_exitcode()} : convertit la valeur de retour de @code{wait()} en code de sortie (contribution de `Victor Stinner' dans bpo-40094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40094}).

@node pathlib<6>,pdb<3>,os<5>,Modules améliorés<5>
@anchor{whatsnew/3 9 pathlib}@anchor{90b}
@subsubsection `pathlib'


Added @ref{90c,,pathlib.Path.readlink()} which acts similarly to
@ref{90d,,os.readlink()}.
(Contributed by Girts Folkmanis in bpo-30618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30618})

@node pdb<3>,poplib,pathlib<6>,Modules améliorés<5>
@anchor{whatsnew/3 9 pdb}@anchor{90e}
@subsubsection `pdb'


Sur Windows, @ref{90f,,Pdb} gère maintenant @code{~/.pdbrc} (contribution de `Tim Hopper' et `Dan Lidral-Porter' dans bpo-20523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20523}).

@node poplib,pprint<2>,pdb<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 poplib}@anchor{910}
@subsubsection `poplib'


@ref{911,,POP3} and @ref{912,,POP3_SSL} now raise a @ref{1ff,,ValueError}
if the given timeout for their constructor is zero to prevent the creation of
a non-blocking socket. (Contributed by Donghee Na in bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}.)

@node pprint<2>,pydoc,poplib,Modules améliorés<5>
@anchor{whatsnew/3 9 pprint}@anchor{913}
@subsubsection `pprint'


@ref{ad,,pprint} peut maintenant faire l'affichage formaté de @ref{1cc,,types.SimpleNamespace} (contribution de `Carl Bordum Hansen' dans bpo-37376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37376}).

@node pydoc,random<3>,pprint<2>,Modules améliorés<5>
@anchor{whatsnew/3 9 pydoc}@anchor{914}
@subsubsection `pydoc'


The documentation string is now shown not only for class, function,
method etc, but for any object that has its own @ref{915,,__doc__}
attribute.
(Contributed by Serhiy Storchaka in bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}.)

@node random<3>,signal,pydoc,Modules améliorés<5>
@anchor{whatsnew/3 9 random}@anchor{916}
@subsubsection `random'


Ajout de la méthode @code{random.Random.randbytes} : génère des octets aléatoires (contribution de `Victor Stinner' dans bpo-40286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40286}).

@node signal,smtplib,random<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 signal}@anchor{917}
@subsubsection `signal'


Sur Linux, exposition de @ref{918,,signal.pidfd_send_signal()} pour envoyer des signaux à un processus en utilisant un descripteur de fichier plutôt qu'un identifiant de processus (`pid'). (bpo-38712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38712})

@node smtplib,socket<3>,signal,Modules améliorés<5>
@anchor{whatsnew/3 9 smtplib}@anchor{919}
@subsubsection `smtplib'


@ref{91a,,SMTP} and @ref{91b,,SMTP_SSL} now raise a @ref{1ff,,ValueError}
if the given timeout for their constructor is zero to prevent the creation of
a non-blocking socket. (Contributed by Donghee Na in bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}.)

@ref{91c,,LMTP} constructor  now has an optional `timeout' parameter.
(Contributed by Donghee Na in bpo-39329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39329}.)

@node socket<3>,time<3>,smtplib,Modules améliorés<5>
@anchor{whatsnew/3 9 socket}@anchor{91d}
@subsubsection `socket'


The @ref{cb,,socket} module now exports the @ref{91e,,CAN_RAW_JOIN_FILTERS}
constant on Linux 4.1 and greater.
(Contributed by Stefan Tatschner and Zackery Spytz in bpo-25780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25780}.)

The socket module now supports the @ref{91f,,CAN_J1939} protocol on
platforms that support it.  (Contributed by Karl Ding in bpo-40291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40291}.)

Le module @code{socket} possède maintenant les fonctions @ref{920,,socket.send_fds()} et @ref{921,,socket.recv_fds()} (contribution de `Joannah Nanjekye', `Shinya Okano' et `Victor Stinner' dans bpo-28724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28724}).

@node time<3>,sys<6>,socket<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 time}@anchor{922}
@subsubsection `time'


On AIX, @ref{923,,thread_time()} is now implemented with @code{thread_cputime()}
which has nanosecond resolution, rather than
@code{clock_gettime(CLOCK_THREAD_CPUTIME_ID)} which has a resolution of 10 milliseconds.
(Contributed by Batuhan Taskaya in bpo-40192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40192})

@node sys<6>,tracemalloc,time<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 sys}@anchor{924}
@subsubsection `sys'


Added a new @ref{925,,sys.platlibdir} attribute: name of the platform-specific
library directory. It is used to build the path of standard library and the
paths of installed extension modules. It is equal to @code{"lib"} on most
platforms.  On Fedora and SuSE, it is equal to @code{"lib64"} on 64-bit platforms.
(Contributed by Jan Matějek, Matěj Cepl, Charalampos Stratakis and Victor Stinner in bpo-1294959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1294959}.)

Previously, @ref{926,,sys.stderr} was block-buffered when non-interactive. Now
@code{stderr} defaults to always being line-buffered.
(Contributed by Jendrik Seipp in bpo-13601@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13601}.)

@node tracemalloc,typing<6>,sys<6>,Modules améliorés<5>
@anchor{whatsnew/3 9 tracemalloc}@anchor{927}
@subsubsection `tracemalloc'


Ajout de @ref{928,,tracemalloc.reset_peak()} qui affecte la taille d'apogée (la plus grande taille atteinte) du bloc mémoire tracé à la taille courante, pour mesurer la taille d'apogée de parties de code spécifiques (contribution de `Huon Wilson' dans bpo-40630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40630}).

@node typing<6>,unicodedata<4>,tracemalloc,Modules améliorés<5>
@anchor{whatsnew/3 9 typing}@anchor{929}
@subsubsection `typing'


@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/} ajoute le type @ref{92a,,typing.Annotated} pour décorer les types existants avec des métadonnées spécifiques au contexte et le nouveau paramètre @code{include_extras} à @ref{69c,,typing.get_type_hints()} pour récupérer les métadonnées à l'exécution (contribution de `Till Varoquaux' et `Konstantin Kashin').

@node unicodedata<4>,venv<3>,typing<6>,Modules améliorés<5>
@anchor{whatsnew/3 9 unicodedata}@anchor{92b}
@subsubsection `unicodedata'


La base de donnée Unicode a été mise à jour à la version 13.0.0. (bpo-39926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39926}).

@node venv<3>,xml<3>,unicodedata<4>,Modules améliorés<5>
@anchor{whatsnew/3 9 venv}@anchor{92c}
@subsubsection `venv'


Tous les scripts d'activations fournis par @ref{110,,venv} spécifient maintenant la personnalisation de l'invite de façon cohérente en utilisant toujours la valeur spécifiée dans @code{__VENV_PROMPT__}. Précédemment certains scripts utilisaient toujours @code{__VENV_PROMPT__}, d'autres seulement quand la variable était affectée, et un utilisait plutôt @code{__VENV_NAME__} (contribution de `Brett Cannon' dans bpo-37663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37663}).

@node xml<3>,,venv<3>,Modules améliorés<5>
@anchor{whatsnew/3 9 xml}@anchor{92d}
@subsubsection `xml'


Les caractères d'espacement à l'intérieur des attributs sont maintenant préservés lors de la sérialisation d'@ref{124,,xml.etree.ElementTree} en fichier XML. Les fin de lignes ne sont plus normalisées par "n". Ceci est le résultat d'une discussion sur comment interpréter la section 2.11 de la spécification XML (contribution de `Mefistotelis' dans bpo-39011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39011}).

@node Optimisations<5>,Obsolescence<7>,Modules améliorés<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 optimizations}@anchor{92e}
@subsection Optimisations



@itemize *

@item 
L'affectation d'une variable temporaire dans les compréhensions est optimisée. Maintenant @code{for y in [expr]} dans les compréhensions est aussi rapide qu'une affectation simple @code{y = expr}. Par exemple :

@quotation

@code{sums = [s for s in [0] for x in data for s in [s + x]]}
@end quotation

Contrairement à l'opérateur @code{:=}, cet idiome ne laisse pas déborder une variable dans la portée externe.

(contribution de `Serhiy Storchaka' dans bpo-32856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32856}).

@item 
Optimisation de la gestion des signaux dans les applications avec plus d'un fil d'exécution (`multithreaded applications'). Si un fil d'exécution autre que le fil principal reçoit un signal, la boucle d'évaluation du code intermédiaire (`bytecode') n'est plus interrompue à chaque instruction intermédiaire pour vérifier s'il y a des signaux en attente qui ne peuvent être gérés. Seul le fil principal de l'interpréteur principal peut gérer les signaux.

Précédemment, la boucle d'évaluation du code intermédiaire était interrompue à chaque instruction jusqu'à ce que le fil principal gère les signaux (contribution de `Victor Stinner' dans bpo-40010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40010}).

@item 
Optimisation du module @ref{d5,,subprocess} sur FreeBSD en utilisant @code{closefrom()} (contribution de `Ed Maste', `Conrad Meyer', `Kyle Evans', `Kubilay Kocak' et `Victor Stinner' dans bpo-38061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38061}).

@item 
@ref{92f,,PyLong_FromDouble()} is now up to 1.87x faster for values that
fit into long.
(Contributed by Sergey Fedoseev in bpo-37986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37986}.)

@item 
A number of Python builtins (@ref{930,,range}, @ref{366,,tuple}, @ref{5c3,,set},
@ref{5c4,,frozenset}, @ref{5fc,,list}, @ref{253,,dict}) are now sped up by using
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} vectorcall protocol.
(Contributed by Donghee Na, Mark Shannon, Jeroen Demeyer and Petr Viktorin in bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}.)

@item 
Optimisation de @code{difference_update()} pour le cas où l'autre `set' est beaucoup plus grand que celui de base. (Suggestion par `Evgeny Kapun' et codage contribué par `Michele Orrù' dans bpo-8425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8425}.)

@item 
L'allocateur de petits objets de Python (@code{obmalloc.c}) alloue maintenant (au plus) un aréna vide qui reste disponible pour réutilisation immédiate, sans le renvoyer au système d'exploitation. Ceci prévient l'emballement (`thrashing') dans les boucles simples où un aréna pourrait être créé puis détruit à nouveau à chaque itération (contribution de `Tim Peters' dans bpo-37257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37257}).

@item 
@ref{931,,floor division} of float operation now has a better performance. Also
the message of @ref{932,,ZeroDivisionError} for this operation is updated.
(Contributed by Donghee Na in bpo-39434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39434}.)

@item 
Le décodage de courtes chaînes ASCII avec les codecs `UTF-8' et `ascii' est maintenant 15 % plus rapide (contribution de `Inada Naoki' dans bpo-37348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37348}).
@end itemize

Voici un résumé des améliorations de performance de Python 3.4 à Python 3.9 :

@example
Python version                       3.4     3.5     3.6     3.7     3.8    3.9
--------------                       ---     ---     ---     ---     ---    ---

Variable and attribute read access:
    read_local                       7.1     7.1     5.4     5.1     3.9    3.9
    read_nonlocal                    7.1     8.1     5.8     5.4     4.4    4.5
    read_global                     15.5    19.0    14.3    13.6     7.6    7.8
    read_builtin                    21.1    21.6    18.5    19.0     7.5    7.8
    read_classvar_from_class        25.6    26.5    20.7    19.5    18.4   17.9
    read_classvar_from_instance     22.8    23.5    18.8    17.1    16.4   16.9
    read_instancevar                32.4    33.1    28.0    26.3    25.4   25.3
    read_instancevar_slots          27.8    31.3    20.8    20.8    20.2   20.5
    read_namedtuple                 73.8    57.5    45.0    46.8    18.4   18.7
    read_boundmethod                37.6    37.9    29.6    26.9    27.7   41.1

Variable and attribute write access:
    write_local                      8.7     9.3     5.5     5.3     4.3    4.3
    write_nonlocal                  10.5    11.1     5.6     5.5     4.7    4.8
    write_global                    19.7    21.2    18.0    18.0    15.8   16.7
    write_classvar                  92.9    96.0   104.6   102.1    39.2   39.8
    write_instancevar               44.6    45.8    40.0    38.9    35.5   37.4
    write_instancevar_slots         35.6    36.1    27.3    26.6    25.7   25.8

Data structure read access:
    read_list                       24.2    24.5    20.8    20.8    19.0   19.5
    read_deque                      24.7    25.5    20.2    20.6    19.8   20.2
    read_dict                       24.3    25.7    22.3    23.0    21.0   22.4
    read_strdict                    22.6    24.3    19.5    21.2    18.9   21.5

Data structure write access:
    write_list                      27.1    28.5    22.5    21.6    20.0   20.0
    write_deque                     28.7    30.1    22.7    21.8    23.5   21.7
    write_dict                      31.4    33.3    29.3    29.2    24.7   25.4
    write_strdict                   28.4    29.9    27.5    25.2    23.1   24.5

Stack (or queue) operations:
    list_append_pop                 93.4   112.7    75.4    74.2    50.8   50.6
    deque_append_pop                43.5    57.0    49.4    49.2    42.5   44.2
    deque_append_popleft            43.7    57.3    49.7    49.7    42.8   46.4

Timing loop:
    loop_overhead                    0.5     0.6     0.4     0.3     0.3    0.3
@end example

These results were generated from the variable access benchmark script at:
@code{Tools/scripts/var_access_benchmark.py}. The benchmark script displays timings
in nanoseconds.  The benchmarks were measured on an
Intel® Core™ i7-4960HQ processor@footnote{https://ark.intel.com/content/www/us/en/ark/products/76088/intel-core-i7-4960hq-processor-6m-cache-up-to-3-80-ghz.html}
running the macOS 64-bit builds found at
python.org@footnote{https://www.python.org/downloads/macos/}.

@node Obsolescence<7>,Retraits<5>,Optimisations<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 deprecated}@anchor{933}
@subsection Obsolescence



@itemize *

@item 
La commande de `distutils' @code{bdist_msi} est maintenant obsolète, utilisez plutôt @code{bdist_wheel} (paquet `wheel') (contribution de `Hugo van Kemenade' dans bpo-39586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39586}).

@item 
Présentement, @ref{934,,math.factorial()} accepte des instances de @ref{2eb,,float} qui sont des entiers non-négatifs (comme @code{5.0}). Elle lève une @ref{1ff,,ValueError} pour les `floats' non-entiers et négatifs. Ceci est maintenant obsolète. Les versions futures de Python vont lever une @ref{522,,TypeError} pour tous les `floats' (contribution de `Serhiy Storchaka' dans bpo-37315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37315}).

@item 
The @code{parser} and @code{symbol} modules are deprecated and will be
removed in future versions of Python. For the majority of use cases,
users can leverage the Abstract Syntax Tree (AST) generation and compilation
stage, using the @ref{8,,ast} module.

@item 
The Public C API functions @code{PyParser_SimpleParseStringFlags()},
@code{PyParser_SimpleParseStringFlagsFilename()},
@code{PyParser_SimpleParseFileFlags()} and @code{PyNode_Compile()}
are deprecated and will be removed in Python 3.10 together with the old parser.

@item 
L'utilisation de @ref{7bc,,NotImplemented} dans un contexte booléen est devenu obsolète, puisque c'est presque toujours le résultat d'une implémentation incorrecte des opérateurs de comparaison avancés. Ceci va devenir une @ref{522,,TypeError} dans les versions futures de Python (contribution de `Josh Rosenberg' dans bpo-35712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35712}).

@item 
Le module @ref{b7,,random} accepte présentement n'importe quel hachable comme valeur d'ensemencement. Malheureusement, certains de ces types ne garantissent pas une valeur de hachage déterministe. Après Python 3.9, le module va restreindre l'ensemencement à @ref{660,,None}, @ref{254,,int}, @ref{2eb,,float}, @ref{435,,str}, @ref{1bd,,bytes} et @ref{528,,bytearray}.

@item 
Ouvrir un fichier @ref{410,,GzipFile} en écriture sans spécifier l'argument `mode' est obsolète. Dans les futures versions de Python, il sera toujours ouvert en lecture par défaut. Spécifiez l'argument `mode' pour l'ouvrir en écriture et supprimer l'avertissement (contribution de `Serhiy Storchaka' dans bpo-28286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28286}).

@item 
Deprecated the @code{split()} method of @code{_tkinter.TkappType} in
favour of the @code{splitlist()} method which has more consistent and
predictable behavior.
(Contributed by Serhiy Storchaka in bpo-38371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38371}.)

@item 
Le passage explicite d'objets coroutine à @ref{469,,asyncio.wait()} est devenu obsolète et sera retiré dans la version 3.11. (Contribution de `Yury Selivanov' et `Kyle Stanley' dans bpo-34790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34790}.)

@item 
binhex4 and hexbin4 standards are now deprecated. The @code{binhex} module
and the following @ref{10,,binascii} functions are now deprecated:


@itemize *

@item 
@code{b2a_hqx()}, @code{a2b_hqx()}

@item 
@code{rlecode_hqx()}, @code{rledecode_hqx()}
@end itemize

(contribution de `Victor Stinner' dans bpo-39353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39353}).

@item 
Les classes @code{slice}, @code{Index} et @code{ExtSlice} du module @ref{8,,ast} sont considérées obsolètes et seront retirées des versions futures de Python. @code{value} doit être utilisé à la place de @code{Index(value)}. @code{Tuple(slices, Load())} doit être utilisé plutôt que @code{ExtSlice(slices)} (contribution de `Serhiy Storchaka' dans bpo-34822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34822}).

@item 
Les classes @code{Suite}, @code{Param}, @code{AugLoad} et @code{AugStore} du module @ref{8,,ast} sont considérées obsolètes et seront retirées des versions futures de Python. Elles n'étaient pas produites par l'analyseur et n'étaient pas acceptées par le générateur de code dans Python 3 (contribution de `Batuhan Taskaya' dans bpo-39639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39639} et bpo-39969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39969} et `Serhiy Storchaka' dans bpo-39988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39988}).

@item 
The @code{PyEval_InitThreads()} and @code{PyEval_ThreadsInitialized()}
functions are now deprecated and will be removed in Python 3.11. Calling
@code{PyEval_InitThreads()} now does nothing. The @ref{158,,GIL} is initialized
by @ref{899,,Py_Initialize()} since Python 3.7.
(Contributed by Victor Stinner in bpo-39877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39877}.)

@item 
Passer @code{None} comme premier argument à la fonction @ref{526,,shlex.split()} a été rendu obsolète (contribution de `Zackery Spytz' dans bpo-33262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33262}).

@item 
@code{smtpd.MailmanProxy()} is now deprecated as it is unusable without
an external module, @code{mailman}.  (Contributed by Samuel Colvin in bpo-35800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35800}.)

@item 
The @code{lib2to3} module now emits a @ref{8b5,,PendingDeprecationWarning}.
Python 3.9 switched to a PEG parser (see 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/}), and Python 3.10 may
include new language syntax that is not parsable by lib2to3's LL(1) parser.
The @code{lib2to3} module may be removed from the standard library in a future
Python version. Consider third-party alternatives such as LibCST@footnote{https://libcst.readthedocs.io/} or
parso@footnote{https://parso.readthedocs.io/}.
(Contributed by Carl Meyer in bpo-40360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40360}.)

@item 
Le paramètre `random' de @ref{731,,random.shuffle()} est maintenant obsolète (contribution de `Raymond Hettinger' dans bpo-40465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40465}).
@end itemize

@node Retraits<5>,Portage vers Python 3 9,Obsolescence<7>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 removed}@anchor{935}@anchor{whatsnew/3 9 removed-in-python-39}@anchor{8b8}
@subsection Retraits



@itemize *

@item 
The erroneous version at @code{unittest.mock.__version__} has been removed.

@item 
@code{nntplib.NNTP}: @code{xpath()} and @code{xgtitle()} methods have been removed.
These methods are deprecated since Python 3.3. Generally, these extensions
are not supported or not enabled by NNTP server administrators.
For @code{xgtitle()}, please use @code{nntplib.NNTP.descriptions()} or
@code{nntplib.NNTP.description()} instead.
(Contributed by Donghee Na in bpo-39366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39366}.)

@item 
Les méthodes de @ref{19e,,array.array} : @code{tostring()} et @code{fromstring()} ont été retirées. Elles étaient des alias de @code{tobytes()} et @code{frombytes()}, obsolètes depuis Python 3.2 (contribution de `Victor Stinner' dans bpo-38916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38916}).

@item 
La fonction non-documentée @code{sys.callstats()} a été retirée. Depuis Python 3.7, elle était obsolète et retournait toujours @ref{660,,None}. Elle dépendait de l'option de construction @code{CALL_PROFILE} qui avait déjà été retirée dans Python 3.7 (contribution de `Victor Stinner' dans bpo-37414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37414}).

@item 
Les fonctions @code{sys.getcheckinterval()} et @code{sys.setcheckinterval()} ont été retirées. Elle étaient obsolètes depuis Python 3.2. Utilisez plutôt @ref{936,,sys.getswitchinterval()} et @ref{937,,sys.setswitchinterval()} (contribution de `Victor Stinner' dans bpo-37392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37392}).

@item 
La fonction C @code{PyImport_Cleanup()} a été retirée. Elle était documentée comme "Vide la table des modules. Pour usage interne seulement." (contribution de `Victor Stinner' dans bpo-36710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36710}).

@item 
Les modules @code{_dummy_thread} et @code{dummy_threading} ont été retirés. Ces modules étaient obsolètes depuis Python 3.7 qui a besoin de la gestion de fils d'exécution multiples (contribution de `Victor Stinner' dans bpo-37312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37312}).

@item 
@code{aifc.openfp()} alias to @code{aifc.open()}, @code{sunau.openfp()} alias to
@code{sunau.open()}, and @code{wave.openfp()} alias to @ref{938,,wave.open()} have been
removed. They were deprecated since Python 3.7.
(Contributed by Victor Stinner in bpo-37320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37320}.)

@item 
The @code{isAlive()} method of @ref{939,,threading.Thread}
has been removed. It was deprecated since Python 3.8.
Use @ref{93a,,is_alive()} instead.
(Contributed by Donghee Na in bpo-37804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37804}.)

@item 
Les méthodes @code{getchildren()} et @code{getiterator()} des classes @ref{93b,,ElementTree} et @ref{305,,Element} dans le module @ref{124,,ElementTree} ont été retirées. Elle avaient été déclarées obsolètes dans Python 3.2. Utilisez @code{iter(x)} ou @code{list(x)} plutôt que @code{x.getchildren()} et @code{x.iter()} ou @code{list(x.iter())} plutôt que @code{x.getiterator()} (contribution de `Serhiy Storchaka' dans bpo-36543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36543}).

@item 
L'ancienne API @ref{aa,,plistlib} a été retirée, elle était obsolète depuis Python 3.4. Utilisez les fonctions @ref{93c,,load()}, @ref{93d,,loads()}, @ref{93e,,dump()} et @ref{93f,,dumps()}. De plus, le paramètre `use_builtin_types' a été retiré, les objets @ref{1bd,,bytes} natifs sont toujours utilisés.

@item 
La fonction C @code{PyGen_NeedsFinalizing} a été retirée. Elle n'était pas documentée, testée ou utilisée où que ce soit dans CPython après l'implémentation de 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/} (contribution de `Joannah Nanjekye' dans bpo-15088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15088}).

@item 
@code{base64.encodestring()} et @code{base64.decodestring()}, des alias obsolètes depuis Python 3.1, ont été retirées : utilisez plutôt @ref{940,,base64.encodebytes()} et @ref{941,,base64.decodebytes()} (contribution de `Victor Stinner' dans bpo-39351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39351}).

@item 
La fonction @code{fractions.gcd()} a été retirée, elle était obsolète depuis Python 3.5 (bpo-22486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22486}) : utilisez plutôt @ref{8fd,,math.gcd()} (contribution de `Victor Stinner' dans bpo-39350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39350}).

@item 
Le paramètre `buffering' de la classe @ref{851,,bz2.BZ2File} a été retiré. Depuis Python 3.0, il était ignoré et son utilisation levait un @ref{1a3,,DeprecationWarning}. Passez un objet fichier déjà ouvert pour déterminer comment le fichier sera ouvert (contribution de `Victor Stinner' dans bpo-39357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39357}).

@item 
Le paramètre `encoding' de @ref{942,,json.loads()} a été retiré. À partir de Python 3.1, il était obsolète et ignoré ; son utilisation levait un @ref{1a3,,DeprecationWarning} depuis Python 3.8 (contribution de `Inada Naoki' dans bpo-39377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39377}).

@item 
Les instructions @code{with (await asyncio.lock):} et @code{with (yield from asyncio.lock):} ne sont plus prises en charge, utilisez plutôt @code{async with lock}. De même pour @code{asyncio.Condition} et @code{asyncio.Semaphore} (contribution de `Andrew Svetlov' dans bpo-34793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34793}).

@item 
The @code{sys.getcounts()} function, the @code{-X showalloccount} command line
option and the @code{show_alloc_count} field of the C structure
@ref{39d,,PyConfig} have been removed. They required a special Python build by
defining @code{COUNT_ALLOCS} macro.
(Contributed by Victor Stinner in bpo-39489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39489}.)

@item 
L'attribut @code{_field_types} de la classe @ref{2ad,,typing.NamedTuple} a été retiré. Il était obsolète depuis Python 3.8. Utilisez plutôt l'attribut @code{__annotations__} (contribution de `Serhiy Storchaka' dans bpo-40182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40182}).

@item 
The @code{symtable.SymbolTable.has_exec()} method has been removed. It was
deprecated since 2006, and only returning @code{False} when it's called.
(Contributed by Batuhan Taskaya in bpo-40208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40208})

@item 
The @code{asyncio.Task.current_task()} and @code{asyncio.Task.all_tasks()}
have been removed. They were deprecated since Python 3.7 and you can use
@ref{467,,asyncio.current_task()} and @ref{943,,asyncio.all_tasks()} instead.
(Contributed by Rémi Lapeyre in bpo-40967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40967})

@item 
La méthode @code{unescape()} de la classe @ref{862,,html.parser.HTMLParser} a été retirée (elle était obsolète depuis Python 3.4). @ref{944,,html.unescape()} doit être utilisée pour convertir les références de caractère en leurs caractères Unicode correspondants.
@end itemize

@node Portage vers Python 3 9,Changements à la compilation<5>,Retraits<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 porting-to-python-3-9}@anchor{945}
@subsection Portage vers Python 3.9


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changements dans l'API Python: Changements dans l'API Python<4>. 
* Changements dans l'API C: Changements dans l'API C<3>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<4>. 

@end menu

@node Changements dans l'API Python<4>,Changements dans l'API C<3>,,Portage vers Python 3 9
@anchor{whatsnew/3 9 changes-in-the-python-api}@anchor{946}
@subsubsection Changements dans l'API Python



@itemize *

@item 
@ref{8c1,,__import__()} et @ref{8f7,,importlib.util.resolve_name()} lèvent maintenant @ref{40f,,ImportError} où elles levaient précédemment @ref{1ff,,ValueError}. Les appelants qui attrapent les types spécifiques d'exceptions et qui prennent à la fois en charge Python 3.9 et des versions précédentes doivent attraper les deux types avec @code{except (ImportError, ValueError):}.

@item 
Il n'y a plus de traitement spécial dans les scriptes d'activation de @ref{110,,venv} quand @code{__VENV_PROMPT__} est mis à @code{""}.

@item 
The @ref{947,,select.epoll.unregister()} method no longer ignores the
@ref{948,,EBADF} error.
(Contributed by Victor Stinner in bpo-39239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39239}.)

@item 
Le paramètre `compresslevel' de @ref{851,,bz2.BZ2File} est devenu exclusivement nommé (`keyword-only') puisque le paramètre `buffering' a été retiré (contribution de `Victor Stinner' in bpo-39357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39357}).

@item 
Simplification de l'`AST' pour l'indiçage. Les indices simples sont représentés par leur valeur, les tranches étendues sont représentées par des `n'-uplets. @code{Index(value)} va renvoyer @code{value} elle-même, @code{ExtSlice(slices)} va renvoyer @code{Tuple(slices, Load())} (contribution de `Serhiy Storchaka' dans bpo-34822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34822}).

@item 
Le module @ref{76,,importlib} ignore maintenant la variable d’environnement 
@geindex PYTHONCASEOK
@geindex variable d'environnement; PYTHONCASEOK
@ref{949,,PYTHONCASEOK} quand les options de ligne de commande @ref{94a,,-E} ou @ref{94b,,-I} sont utilisées.

@item 
Le paramètre `encoding' a été ajouté aux classes @ref{8e7,,ftplib.FTP} et @ref{8e8,,ftplib.FTP_TLS} en paramètre exclusivement nommé et l'encodage par défaut est passé de `Latin-1' à `UTF-8' en conformité à 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}.

@item 
@ref{8d4,,asyncio.loop.shutdown_default_executor()} a été ajouté à @ref{94c,,AbstractEventLoop}, donc les boucles d'événements alternatives qui héritent de celle-ci devraient définir cette méthode (contribution de `Kyle Stanley' dans bpo-34037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34037}).

@item 
Les valeurs constantes des drapeaux futurs du module @ref{0,,__future__} sont mises à jour pour éviter les collisions avec les drapeaux du compilateur. Précédemment, @code{PyCF_ALLOW_TOP_LEVEL_AWAIT} était en collision avec @code{CO_FUTURE_DIVISION} (contribution de `Batuhan Taskaya' dans bpo-39562@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39562}).

@item 
@code{array('u')} now uses @code{wchar_t} as C type instead of @code{Py_UNICODE}.
This change doesn't affect to its behavior because @code{Py_UNICODE} is alias
of @code{wchar_t} since Python 3.3.
(Contributed by Inada Naoki in bpo-34538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34538}.)

@item 
L'API @ref{94d,,logging.getLogger()} renvoie maintenant le journaliseur racine quand on lui passe le nom @code{'root'}, alors que préalablement il renvoyait un journaliseur non-racine appelé @code{'root'}. Ceci peut affecter les cas où le code de l'utilisateur veut explicitement un journaliseur non-racine appelé @code{'root'}, ou instancie un journaliseur avec @code{logging.getLogger(__name__)} dans un module de niveau principal appelé @code{'root.py'} (contribution de `Vinay Sajip' dans bpo-37742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37742}).

@item 
Division handling of @ref{490,,PurePath} now returns @ref{7bc,,NotImplemented}
instead of raising a @ref{522,,TypeError} when passed something other than an
instance of @code{str} or @ref{490,,PurePath}.  This allows creating
compatible classes that don't inherit from those mentioned types.
(Contributed by Roger Aiudi in bpo-34775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34775}).

@item 
Starting with Python 3.9.5 the @ref{7f,,ipaddress} module no longer
accepts any leading zeros in IPv4 address strings. Leading zeros are
ambiguous and interpreted as octal notation by some libraries. For example
the legacy function @ref{94e,,socket.inet_aton()} treats leading zeros as octal
notatation. glibc implementation of modern @ref{94f,,inet_pton()} does
not accept any leading zeros.
(Contributed by Christian Heimes in bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}).

@item 
@ref{950,,codecs.lookup()} now normalizes the encoding name the same way as
@code{encodings.normalize_encoding()}, except that @ref{950,,codecs.lookup()} also
converts the name to lower case. For example, @code{"latex+latin1"} encoding
name is now normalized to @code{"latex_latin1"}.
(Contributed by Jordon Xu in bpo-37751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37751}.)
@end itemize

@node Changements dans l'API C<3>,Changements au code intermédiaire CPython<4>,Changements dans l'API Python<4>,Portage vers Python 3 9
@anchor{whatsnew/3 9 changes-in-the-c-api}@anchor{951}
@subsubsection Changements dans l'API C



@itemize *

@item 
Les instances de @ref{952,,types alloués sur le tas} (tels que ceux créés avec @ref{569,,PyType_FromSpec()} et les APIs similaires) gardent une référence à leur objet type depuis Python 3.8. Tel qu'indiqué dans "Changements à l'API C" de Python 3.8, pour la grande majorité des cas, il ne devrait pas y avoir d'effets secondaires sauf pour les types qui ont une fonction @ref{768,,tp_traverse} personnalisée. Assurez-vous que toutes les fonctions @code{tp_traverse} personnalisées des types alloués sur le tas visitent le type de l'objet.

@quotation

Exemple :

@example
int
foo_traverse(foo_struct *self, visitproc visit, void *arg) @{
// Rest of the traverse function
#if PY_VERSION_HEX >= 0x03090000
    // This was not needed before Python 3.9 (Python issue 35810 and 40217)
    Py_VISIT(Py_TYPE(self));
#endif
@}
@end example
@end quotation

Si votre fonction de traversée délègue à la @code{tp_traverse} de sa classe mère (ou d'un autre type), assurez-vous que @code{Py_TYPE(self)} ne soit visité qu'une seule fois. Prenez note que seuls les @ref{952,,types du tas} doivent visiter leur type dans @code{tp_traverse}.

@quotation

Par exemple, si votre fonction @code{tp_traverse} inclut :

@example
base->tp_traverse(self, visit, arg)
@end example

alors ajoutez :

@example
#if PY_VERSION_HEX >= 0x03090000
    // This was not needed before Python 3.9 (bpo-35810 and bpo-40217)
    if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) @{
        // a heap type's tp_traverse already visited Py_TYPE(self)
    @} else @{
        Py_VISIT(Py_TYPE(self));
    @}
#else
@end example
@end quotation

(Voir bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810} et bpo-40217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40217} pour plus d'information.)

@item 
Les fonctions @code{PyEval_CallObject}, @code{PyEval_CallFunction}, @code{PyEval_CallMethod} et @code{PyEval_CallObjectWithKeywords} sont obsolètes. Utilisez plutôt @ref{393,,PyObject_Call()} et ses variantes. (Pour plus de détails, voir bpo-29548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29548}.)
@end itemize

@node Changements au code intermédiaire CPython<4>,,Changements dans l'API C<3>,Portage vers Python 3 9
@anchor{whatsnew/3 9 cpython-bytecode-changes}@anchor{953}
@subsubsection Changements au code intermédiaire CPython



@itemize *

@item 
Le code d'opération @ref{954,,LOAD_ASSERTION_ERROR} a été ajouté pour gérer l'instruction @ref{955,,assert}. Précédemment, l'instruction @code{assert} ne fonctionnait pas correctement si l'exception @ref{694,,AssertionError} était masquée (contribution de `Zackery Spytz' dans bpo-34880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34880}).

@item 
Le code d'opération @ref{956,,COMPARE_OP} a été séparé en quatre instructions distinctes :


@itemize *

@item 
@code{COMPARE_OP} pour les comparaisons avancées ;

@item 
@code{IS_OP} pour les tests `is' et `is not' ;

@item 
@code{CONTAINS_OP} pour les tests `in' et `not in' ;

@item 
@code{JUMP_IF_NOT_EXC_MATCH} pour vérifier les exceptions dans les instructions @code{try-except}.
@end itemize

(contribution de `Mark Shannon' dans bpo-39156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39156}).
@end itemize

@node Changements à la compilation<5>,Changements à l'API C<5>,Portage vers Python 3 9,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 build-changes}@anchor{957}
@subsection Changements à la compilation



@itemize *

@item 
Added @code{--with-platlibdir} option to the @code{configure} script: name of the
platform-specific library directory, stored in the new @ref{925,,sys.platlibdir}
attribute. See @ref{925,,sys.platlibdir} attribute for more information.
(Contributed by Jan Matějek, Matěj Cepl, Charalampos Stratakis
and Victor Stinner in bpo-1294959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1294959}.)

@item 
La macro spéciale de compilation @code{COUNT_ALLOCS} a été retirée (contribution de `Victor Stinner' dans bpo-39489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39489}).

@item 
On non-Windows platforms, the @code{setenv()} and @code{unsetenv()}
functions are now required to build Python.
(Contributed by Victor Stinner in bpo-39395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39395}.)

@item 
Sur les plateformes non-Windows, la création d'installateurs @code{bdist_wininst} n'est maintenant officiellement plus pris en charge. (Voir bpo-10945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10945} pour plus de détails.)

@item 
When building Python on macOS from source, @code{_tkinter} now links with
non-system Tcl and Tk frameworks if they are installed in
@code{/Library/Frameworks}, as had been the case on older releases
of macOS. If a macOS SDK is explicitly configured, by using
@ref{958,,--enable-universalsdk} or @code{-isysroot}, only the SDK itself is
searched. The default behavior can still be overridden with
@code{--with-tcltk-includes} and @code{--with-tcltk-libs}.
(Contributed by Ned Deily in bpo-34956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34956}.)

@item 
Python peut maintenant être compilé pour `Windows 10 ARM64' (contribution de `Steve Dower' dans bpo-33125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33125}).

@item 
Certains tests individuels sont maintenant ignorés lorsque @code{--pgo} est utilisé. Les tests en question augmentaient la durée de la tâche `PGO' de manière significative et n'optimisaient probablement pas l'exécutable final. Cela accélère la tâche par un facteur d'environ 15 fois. Le fait de lancer la suite de tests est lent. Ce changement va peut être avoir pour conséquence des exécutables compilés un peu moins optimisés car moins de branches de code seront exécutées. Si vous souhaitez attendre avec une compilation plus lente, l'ancienne manière de fonctionner peut être obtenue avec @code{./configure [..] PROFILE_TASK="-m test --pgo-extended"}. Nous ne garantissons pas quel set de tâches PGO produira une compilation plus rapide. Les utilisateurs qui s'y intéressent devraient exécuter leurs propres `benchmarks', car les résultats peuvent dépendre de l'environnement, de la charge de travail et de la chaîne d'outils du compilateur. (Voir bpo-36044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36044} et bpo-37707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37707} pour plus de détails.)
@end itemize

@node Changements à l'API C<5>,Changements importants dans Python 3 9 1,Changements à la compilation<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 c-api-changes}@anchor{959}
@subsection Changements à l'API C


@menu
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<10>. 
* Portage vers Python 3.9: Portage vers Python 3 9<2>. 
* Retraits: Retraits<6>. 

@end menu

@node Nouvelles fonctionnalités<10>,Portage vers Python 3 9<2>,,Changements à l'API C<5>
@anchor{whatsnew/3 9 id1}@anchor{95a}
@subsubsection Nouvelles fonctionnalités



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/}: Added @ref{53c,,PyType_FromModuleAndSpec()} to associate
a module with a class; @ref{95b,,PyType_GetModule()} and
@ref{95c,,PyType_GetModuleState()} to retrieve the module and its state; and
@ref{74e,,PyCMethod} and @ref{95d,,METH_METHOD} to allow a method to
access the class it was defined in.
(Contributed by Marcel Plch and Petr Viktorin in bpo-38787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38787}.)

@item 
Ajout de la fonction @ref{774,,PyFrame_GetCode()} : récupérer le code d'un cadre. Ajout de la fonction @ref{770,,PyFrame_GetBack()} : récupérer le prochain cadre englobant (contribution de `Victor Stinner' dans bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}).

@item 
Ajout de @ref{775,,PyFrame_GetLineNumber()} à l'API C limité (contribution de `Victor Stinner' dans bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}).

@item 
Ajout des fonctions @ref{95e,,PyThreadState_GetInterpreter()} et @ref{3a4,,PyInterpreterState_Get()} pour récupérer l'interpréteur. Ajout de la fonction @ref{778,,PyThreadState_GetFrame()} pour récupérer le cadre de l'état d'un fil d'exécution Python. Ajout de la fonction @ref{95f,,PyThreadState_GetID()} : récupérer l'identifiant unique de l'état d'un fil d'exécution Python (contribution de `Victor Stinner' dans bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}).

@item 
Ajout de la nouvelle fonction publique @ref{392,,PyObject_CallNoArgs()} à l'API C, qui appelle un objet Python appelable sans aucun argument. C'est la façon la plus efficace d'appeler un objet Python appelable sans aucun argument (contribution de `Victor Stinner' dans bpo-37194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37194}).

@item 
Changements dans l'API C limité (si la macro @code{Py_LIMITED_API} est définie) :


@itemize *

@item 
Fournit @ref{960,,Py_EnterRecursiveCall()} et @ref{961,,Py_LeaveRecursiveCall()} comme fonctions régulières pour l'API limité. Précédemment, elles étaient définies en tant que macros, mais ces macros n'étaient pas compilées avec l'API C limité qui ne peut pas accéder au champ @code{PyThreadState.recursion_depth} (la structure est opaque à l'API C limité) ;

@item 
@code{PyObject_INIT()} et @code{PyObject_INIT_VAR()} deviennent des fonctions "opaques" régulières pour cacher les détails d'implémentation
@end itemize

(contribution de `Victor Stinner' dans bpo-38644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38644} et bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}).

@item 
The @ref{962,,PyModule_AddType()} function is added to help adding a type
to a module.
(Contributed by Donghee Na in bpo-40024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40024}.)

@item 
Ajout des fonctions @ref{963,,PyObject_GC_IsTracked()} et @ref{964,,PyObject_GC_IsFinalized()} à l'API publique qui déterminent respectivement si les objets Python sont présentement suivis ou ont été finalisés par le ramasse-miettes (contribution de `Pablo Galindo Salgado' dans bpo-40241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40241}).

@item 
Added @code{_PyObject_FunctionStr()} to get a user-friendly string
representation of a function-like object.
(Patch by Jeroen Demeyer in bpo-37645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37645}.)

@item 
Ajout de @ref{965,,PyObject_CallOneArg()} pour appeler un objet avec un argument positionnel. (Rustine par `Jeroen Demeyer' dans bpo-37483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37483}.)
@end itemize

@node Portage vers Python 3 9<2>,Retraits<6>,Nouvelles fonctionnalités<10>,Changements à l'API C<5>
@anchor{whatsnew/3 9 id2}@anchor{966}
@subsubsection Portage vers Python 3.9



@itemize *

@item 
@code{PyInterpreterState.eval_frame} (
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/}) nécessite maintenant un nouveau paramètre obligatoire `tstate' (@code{PyThreadState*}) (contribution de `Victor Stinner' dans bpo-38500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38500}).

@item 
Modules d'extension : les fonctions @ref{967,,m_traverse}, @ref{968,,m_clear} et @ref{969,,m_free} de @ref{96a,,PyModuleDef} ne sont plus appelées si l'état du module est demandé mais qu'il n'a pas encore été alloué. C'est le cas immédiatement après que le module a été créé et avant que le module soit exécuté (fonction @ref{96b,,Py_mod_exec}). Plus précisément, ces fonctions ne sont pas appelées si @ref{96c,,m_size} est plus grand que 0 et que l'état du module (tel que renvoyé par @ref{96d,,PyModule_GetState()}) est @code{NULL}.

Les modules d'extensions sans état de module (@code{m_size <= 0}) ne sont pas affectés.

@item 
Si @ref{96e,,Py_AddPendingCall()} est appelée dans un sous-interpréteur, la fonction est planifiée pour appel dans le sous-interpréteur, plutôt que dans l'interpréteur principal. Chaque sous interpréteur a maintenant sa propre liste d'appels planifiés (contribution de `Victor Stinner' dans bpo-39984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39984}).

@item 
Le registre de Windows n'est plus utilisé pour initialiser @ref{3ab,,sys.path} quand l'option @code{-E} est utilisée (si @ref{3d0,,PyConfig.use_environment} est affecté à @code{0}). Ceci est pertinent quand Python est embarqué sur Windows (contribution de `Zackery Spytz' dans bpo-8901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8901}).

@item 
La variable globale @ref{96f,,PyStructSequence_UnnamedField} est maintenant une constante et fait référence à une chaîne constante (contribution de `Serhiy Storchaka' dans bpo-38650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38650}).

@item 
The @code{PyGC_Head} structure is now opaque. It is only defined in the
internal C API (@code{pycore_gc.h}).
(Contributed by Victor Stinner in bpo-40241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40241}.)

@item 
The @code{Py_UNICODE_COPY}, @code{Py_UNICODE_FILL}, @code{PyUnicode_WSTR_LENGTH},
@code{PyUnicode_FromUnicode()}, @code{PyUnicode_AsUnicode()},
@code{_PyUnicode_AsUnicode}, and @code{PyUnicode_AsUnicodeAndSize()} are
marked as deprecated in C.  They have been deprecated by 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} since
Python 3.3.
(Contributed by Inada Naoki in bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}.)

@item 
La fonction @ref{970,,Py_FatalError()} est remplacée par une macro qui ajoute automatiquement une entrée au journal avec le nom de la fonction courante, sauf si la macro @code{Py_LIMITED_API} est définie (contribution de `Victor Stinner' dans bpo-39882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39882}).

@item 
Le protocole `vectorcall' requiert maintenant que l'appelant ne passe que des chaînes pour les noms des arguments nommés. (Voir bpo-37540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37540} pour plus d'informations.)

@item 
Les détails d'implémentation de certaines macros et fonctions sont maintenant cachés :


@itemize *

@item 
la macro @ref{971,,PyObject_IS_GC()} a été convertie en fonction ;

@item 
The @code{PyObject_NEW()} macro becomes an alias to the
@ref{972,,PyObject_New} macro, and the @code{PyObject_NEW_VAR()} macro
becomes an alias to the @ref{973,,PyObject_NewVar} macro. They no longer
access directly the @ref{974,,PyTypeObject.tp_basicsize} member.

@item 
@code{PyObject_GET_WEAKREFS_LISTPTR()} macro was converted to a function:
the macro accessed directly the @ref{975,,PyTypeObject.tp_weaklistoffset}
member.

@item 
La macro @ref{38f,,PyObject_CheckBuffer()} a été convertie en fonction : la macro accédait directement au membre @ref{976,,PyTypeObject.tp_as_buffer} ;

@item 
@ref{977,,PyIndex_Check()} est maintenant toujours déclarée comme une fonction opaque pour cacher ses détails d'implémentation : retrait de la macro @code{PyIndex_Check()}. La macro accédait directement au membre @ref{978,,PyTypeObject.tp_as_number}.
@end itemize

(Voir bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170} pour plus de détails.)
@end itemize

@node Retraits<6>,,Portage vers Python 3 9<2>,Changements à l'API C<5>
@anchor{whatsnew/3 9 id3}@anchor{979}
@subsubsection Retraits



@itemize *

@item 
Exclusion des macros @code{PyFPE_START_PROTECT()} et @code{PyFPE_END_PROTECT()} de l'API C limité (contribution de `Victor Stinner' dans bpo-38835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38835}).

@item 
Le champ @code{tp_print} de @ref{97a,,PyTypeObject} a été retiré. Il était utilisé pour écrire des objets dans des fichiers dans Python 2.7 et dans les versions précédentes. Depuis Python 3.0, il était ignoré et inutilisé (contribution de `Jeroen Demeyer' dans bpo-36974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36974}).

@item 
Changements dans l'API C limité (si la macro @code{Py_LIMITED_API} est définie) :


@itemize *

@item 
Exclusion des fonctions suivantes de l'API C limité :


@itemize *

@item 
@code{PyThreadState_DeleteCurrent()} (contribution de `Joannah Nanjekye' dans bpo-37878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37878}) ;

@item 
@code{_Py_CheckRecursionLimit} ;

@item 
@code{_Py_NewReference()} ;

@item 
@code{_Py_ForgetReference()} ;

@item 
@code{_PyTraceMalloc_NewReference()} ;

@item 
@code{_Py_GetRefTotal()} ;

@item 
Le mécanisme `trashcan' qui n'a jamais fonctionné dans l'API C limité ;

@item 
@code{PyTrash_UNWIND_LEVEL} ;

@item 
@code{Py_TRASHCAN_BEGIN_CONDITION} ;

@item 
@code{Py_TRASHCAN_BEGIN} ;

@item 
@code{Py_TRASHCAN_END} ;

@item 
@code{Py_TRASHCAN_SAFE_BEGIN} ;

@item 
@code{Py_TRASHCAN_SAFE_END}.
@end itemize

@item 
Migration des fonctions et définitions suivantes vers l'API C interne :


@itemize *

@item 
@code{_PyDebug_PrintTotalRefs()} ;

@item 
@code{_Py_PrintReferences()} ;

@item 
@code{_Py_PrintReferenceAddresses()} ;

@item 
@code{_Py_tracemalloc_config} ;

@item 
@code{_Py_AddToAllObjects()} (spécifique aux compilations @code{Py_TRACE_REFS}).
@end itemize
@end itemize

(contribution de `Victor Stinner' dans bpo-38644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38644} et bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}).

@item 
Retrait de la fonction de rappel @code{_PyRuntime.getframe} et de la macro @code{_PyThreadState_GetFrame} qui était un alias pour @code{_PyRuntime.getframe}. Elles étaient exposées uniquement dans l'API C interne. Retrait aussi du type @code{PyThreadFrameGetter} (contribution de `Victor Stinner' dans bpo-39946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39946}).

@item 
Retrait des fonctions suivantes de l'API C. Appelez @ref{97b,,PyGC_Collect()} explicitement pour vider toutes les `free lists' (contribution de `Inada Naoki' et `Victor Stinner' dans bpo-37340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37340}, bpo-38896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38896} et bpo-40428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40428}) :


@itemize *

@item 
@code{PyAsyncGen_ClearFreeLists()} ;

@item 
@code{PyContext_ClearFreeList()} ;

@item 
@code{PyDict_ClearFreeList()} ;

@item 
@code{PyFloat_ClearFreeList()} ;

@item 
@code{PyFrame_ClearFreeList()} ;

@item 
@code{PyList_ClearFreeList()} ;

@item 
@code{PyMethod_ClearFreeList()} et @code{PyCFunction_ClearFreeList()} : les `free lists' des objets méthode liées ont été retirées ;

@item 
@code{PySet_ClearFreeList()} : la `free list' des objets `sets' a été retirée dans Python 3.4 ;

@item 
@code{PyTuple_ClearFreeList()} ;

@item 
@code{PyUnicode_ClearFreeList()} : la `free list' des objets Unicode a été retirée dans Python 3.3.
@end itemize

@item 
Retrait de la fonction @code{_PyUnicode_ClearStaticStrings()} (contribution de `Victor Stinner' dans bpo-39465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39465}).

@item 
Retrait de @code{Py_UNICODE_MATCH}. Elle était devenue obsolète par 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, non-fonctionnelle depuis Python 3.3. La fonction @ref{8a5,,PyUnicode_Tailmatch()} peut être utilisée à sa place (contribution de `Inada Naoki' dans bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}).

@item 
Nettoyage dans les fichiers d'en-têtes d'interfaces déclarées pour lesquelles il n'y avait pas d'implémentation. Les symboles retirés de l'API publique sont : @code{_PyBytes_InsertThousandsGroupingLocale}, @code{_PyBytes_InsertThousandsGrouping}, @code{_Py_InitializeFromArgs}, @code{_Py_InitializeFromWideArgs}, @code{_PyFloat_Repr}, @code{_PyFloat_Digits}, @code{_PyFloat_DigitsInit}, @code{PyFrame_ExtendStack}, @code{_PyAIterWrapper_Type}, @code{PyNullImporter_Type}, @code{PyCmpWrapper_Type}, @code{PySortWrapper_Type}, @code{PyNoArgsFunction} (contribution de `Pablo Galindo Salgado' dans bpo-39372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39372}).
@end itemize

@node Changements importants dans Python 3 9 1,Changements importants dans Python 3 9 2,Changements à l'API C<5>,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-1}@anchor{97c}
@subsection Changements importants dans Python 3.9.1


@menu
* typing: typing<7>. 
* Prise en charge de macOS 11.0 (Big Sur) et de Mac sur processeur Apple: Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple. 

@end menu

@node typing<7>,Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple,,Changements importants dans Python 3 9 1
@anchor{whatsnew/3 9 id4}@anchor{97d}
@subsubsection `typing'


Le comportement de @ref{83f,,typing.Literal} a été changé pour être conforme avec 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/} et pour avoir le comportement des vérificateurs de types statique spécifiés dans le PEP :


@enumerate 

@item 
@code{Literal} de-duplique maintenant les paramètres ;

@item 
Les comparaisons d'égalité entre les objets @code{Literal} sont maintenant indépendantes de l'ordre ;

@item 
Les comparaisons des @code{Literal} respectent maintenant les types. Par exemple, @code{Literal[0] == Literal[False]} évaluait précédemment à @code{True}. C'est maintenant @code{False}. Pour gérer ce changement, le cache interne des types utilisés peut maintenant différentier les types ;

@item 
Les objets @code{Literal} lèvent maintenant une exception @ref{522,,TypeError} lors des comparaisons d'égalités si n'importe quel de leurs paramètres n'est pas @ref{97e,,immuable}. Prenez-note que déclarer un @code{Literal} avec un paramètre mutable ne lève pas une erreur :

@example
>>> from typing import Literal
>>> Literal[@{0@}]
>>> Literal[@{0@}] == Literal[@{False@}]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'set'
@end example
@end enumerate

(Contribution de `Yurii Karabas' dans bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345}.)

@node Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple,,typing<7>,Changements importants dans Python 3 9 1
@anchor{whatsnew/3 9 macos-11-0-big-sur-and-apple-silicon-mac-support}@anchor{97f}
@subsubsection Prise en charge de `macOS' 11.0 (Big Sur) et de Mac sur processeur Apple


Depuis la version 3.9.1, Python est maintenant totalement compatible (compilation et lancement) sur macOS 11.0 (`Big Sur') et sur les Macs Apple Silicon (basés sur l'architecture @code{ARM64}). Un nouveau variant de `build', @code{universal2}, est maintenant disponible et supporte nativement les plateformes @code{ARM64} et @code{Intel 64} en un seul jeu d'exécutables. Les binaires peuvent aussi être compilés sur les versions actuelles de macOS pour ensuite être déployés sur des versions antérieures (testé jusqu'à 10.9), tout en rendant de nouvelles fonctionnalités du système d'exploitation disponibles en fonction de la version du système utilisée à l'exécution ("`weaklinking'").

(contribution de `Ronald Oussoren' et `Lawrence D'Anna' dans bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100}).

@node Changements importants dans Python 3 9 2,Notable changes in Python 3 9 3,Changements importants dans Python 3 9 1,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-2}@anchor{980}
@subsection Changements importants dans Python 3.9.2


@menu
* collections.abc: collections abc<2>. 
* urllib.parse: urllib parse<2>. 

@end menu

@node collections abc<2>,urllib parse<2>,,Changements importants dans Python 3 9 2
@anchor{whatsnew/3 9 collections-abc}@anchor{981}
@subsubsection `collections.abc'


@ref{7d4,,collections.abc.Callable} generic now flattens type parameters, similar
to what @ref{7af,,typing.Callable} currently does.  This means that
@code{collections.abc.Callable[[int, str], str]} will have @code{__args__} of
@code{(int, str, str)}; previously this was @code{([int, str], str)}.  To allow this
change, @ref{7d5,,types.GenericAlias} can now be subclassed, and a subclass will
be returned when subscripting the @ref{7d4,,collections.abc.Callable} type.
Code which accesses the arguments via @ref{86a,,typing.get_args()} or @code{__args__}
need to account for this change.  A @ref{1a3,,DeprecationWarning} may be emitted for
invalid forms of parameterizing @ref{7d4,,collections.abc.Callable} which may have
passed silently in Python 3.9.1.  This @ref{1a3,,DeprecationWarning} will
become a @ref{522,,TypeError} in Python 3.10.
(Contributed by Ken Jin in bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}.)

@node urllib parse<2>,,collections abc<2>,Changements importants dans Python 3 9 2
@anchor{whatsnew/3 9 urllib-parse}@anchor{982}
@subsubsection `urllib.parse'


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{277,,urllib.parse.parse_qs()} and
@ref{276,,urllib.parse.parse_qsl()}.  Due to security concerns, and to conform with
newer W3C recommendations, this has been changed to allow only a single
separator key, with @code{&} as the default.  This change also affects
@code{cgi.parse()} and @code{cgi.parse_multipart()} as they use the affected
functions internally. For more details, please see their respective
documentation.
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}.)

@node Notable changes in Python 3 9 3,Notable changes in Python 3 9 5,Changements importants dans Python 3 9 2,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-3}@anchor{983}
@subsection Notable changes in Python 3.9.3


A security fix alters the @ref{8e7,,ftplib.FTP} behavior to not trust the
IPv4 address sent from the remote server when setting up a passive data
channel.  We reuse the ftp server IP address instead.  For unusual code
requiring the old behavior, set a @code{trust_server_pasv_ipv4_address}
attribute on your FTP instance to @code{True}.  (See gh-87451@footnote{https://github.com/python/cpython/issues/87451})

@node Notable changes in Python 3 9 5,Notable security feature in 3 9 14,Notable changes in Python 3 9 3,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-python-3-9-5}@anchor{984}
@subsection Notable changes in Python 3.9.5


@menu
* urllib.parse: urllib parse<3>. 

@end menu

@node urllib parse<3>,,,Notable changes in Python 3 9 5
@anchor{whatsnew/3 9 id5}@anchor{985}
@subsubsection `urllib.parse'


The presence of newline or tab characters in parts of a URL allows for some
forms of attacks. Following the WHATWG specification that updates 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html},
ASCII newline @code{\n}, @code{\r} and tab @code{\t} characters are stripped from the
URL by the parser in @ref{109,,urllib.parse} preventing such attacks. The removal
characters are controlled by a new module level variable
@code{urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE}. (See gh-88048@footnote{https://github.com/python/cpython/issues/88048})

@node Notable security feature in 3 9 14,Notable changes in 3 9 17,Notable changes in Python 3 9 5,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 notable-security-feature-in-3-9-14}@anchor{986}
@subsection Notable security feature in 3.9.14


Converting between @ref{254,,int} and @ref{435,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{1ff,,ValueError} if the number of digits in string form is
above a limit to avoid potential denial of service attacks due to the
algorithmic complexity. This is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.
This limit can be configured or disabled by environment variable, command
line flag, or @ref{d8,,sys} APIs. See the @ref{5df,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node Notable changes in 3 9 17,,Notable security feature in 3 9 14,Les nouveautés de Python 3 9
@anchor{whatsnew/3 9 notable-changes-in-3-9-17}@anchor{987}
@subsection Notable changes in 3.9.17


@menu
* tarfile: tarfile<3>. 

@end menu

@node tarfile<3>,,,Notable changes in 3 9 17
@anchor{whatsnew/3 9 tarfile}@anchor{988}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{dd,,tarfile}, and @ref{455,,shutil.unpack_archive()},
have a new a `filter' argument that allows limiting tar features than may be
surprising or dangerous, such as creating files outside the destination
directory.
See @ref{456,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@node Nouveautés de Python 3 8,What's New In Python 3 7,Les nouveautés de Python 3 9,Nouveautés de Python
@anchor{whatsnew/3 8 doc}@anchor{989}@anchor{whatsnew/3 8 what-s-new-in-python-3-8}@anchor{98a}
@section Nouveautés de Python 3.8


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Git log
@c when researching a change.

@*Rédacteur: 
Raymond Hettinger


This article explains the new features in Python 3.8, compared to 3.7.
Python 3.8 was released on October 14, 2019.
For full details, see the @ref{13b,,changelog}.

@c from datetime import date
@c from math import cos, radians
@c from unicodedata import normalize
@c import re
@c import math

@menu
* Summary: Summary -- Release highlights. Release highlights
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<11>. 
* Autres changements au langage: Autres changements au langage<6>. 
* Nouveaux modules: Nouveaux modules<6>. 
* Modules améliorés: Modules améliorés<6>. 
* Optimizations:: 
* Build and C API Changes:: 
* Obsolescence: Obsolescence<8>. 
* API and Feature Removals:: 
* Porting to Python 3.8: Porting to Python 3 8. 
* Notable changes in Python 3.8.1: Notable changes in Python 3 8 1. 
* Notable changes in Python 3.8.2: Notable changes in Python 3 8 2. 
* Notable changes in Python 3.8.3: Notable changes in Python 3 8 3. 
* Notable changes in Python 3.8.8: Notable changes in Python 3 8 8. 
* Notable changes in Python 3.8.9: Notable changes in Python 3 8 9. 
* Notable changes in Python 3.8.10: Notable changes in Python 3 8 10. 
* Notable changes in Python 3.8.10: Notable changes in Python 3 8 10<2>. 
* Notable changes in Python 3.8.12: Notable changes in Python 3 8 12. 
* Notable security feature in 3.8.14: Notable security feature in 3 8 14. 
* Notable changes in 3.8.17: Notable changes in 3 8 17. 

@end menu

@node Summary -- Release highlights,Nouvelles fonctionnalités<11>,,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 summary-release-highlights}@anchor{98b}
@subsection Summary -- Release highlights


@c This section singles out the most important changes in Python 3.8.
@c Brevity is key.

@c PEP-sized items next.

@node Nouvelles fonctionnalités<11>,Autres changements au langage<6>,Summary -- Release highlights,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 new-features}@anchor{98c}
@subsection Nouvelles fonctionnalités


@menu
* Expression d'affectation:: 
* Positional-only parameters:: 
* Parallel filesystem cache for compiled bytecode files:: 
* Debug build uses the same ABI as release build:: 
* f-strings support = for self-documenting expressions and debugging:: 
* PEP 578; Python Runtime Audit Hooks: PEP 578 Python Runtime Audit Hooks. 
* PEP 587; Python Initialization Configuration: PEP 587 Python Initialization Configuration. 
* PEP 590; Vectorcall; a fast calling protocol for CPython: PEP 590 Vectorcall a fast calling protocol for CPython. 
* Pickle protocol 5 with out-of-band data buffers:: 

@end menu

@node Expression d'affectation,Positional-only parameters,,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 assignment-expressions}@anchor{98d}
@subsubsection Expression d'affectation


La nouvelle syntaxe @code{:=} affecte une valeur à une variable au sein d’une expression plus large. Cette syntaxe est surnommée affectueusement « opérateur morse » (`walrus operator' en anglais) en raison de sa ressemblance avec les yeux et les défenses d’un morse@footnote{https://en.wikipedia.org/wiki/Walrus#/media/File:Pacific_Walrus_-_Bull_(8247646168).jpg}.

Dans cet exemple, l’opérateur d’affectation permet de ne pas appeler @ref{619,,len()} deux fois :

@example
if (n := len(a)) > 10:
    print(f"List is too long (@{n@} elements, expected <= 10)")
@end example

A similar benefit arises during regular expression matching where
match objects are needed twice, once to test whether a match
occurred and another to extract a subgroup:

@example
discount = 0.0
if (mo := re.search(r'(\d+)% discount', advertisement)):
    discount = float(mo.group(1)) / 100.0
@end example

L’opérateur est également utile avec une boucle `while' qui calcule une valeur pour tester la condition de fin et que cette valeur est également nécessaire dans le corps de la boucle :

@example
# Loop over fixed length blocks
while (block := f.read(256)) != '@w{'}:
    process(block)
@end example

Un autre usage intéressant est l’utilisation dans les compréhensions de listes lorsqu’une valeur calculée dans une condition de filtrage est aussi utilisée dans le corps de l’expression :

@example
[clean_name.title() for name in names
 if (clean_name := normalize('NFC', name)) in allowed_names]
@end example

Essayer de limiter l’usage de l’opérateur morse aux cas clairs permet de réduire la complexité et augmente la lisibilité.

Voir 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} pour une description complète.

(Contributed by Emily Morehouse in bpo-35224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35224}.)

@node Positional-only parameters,Parallel filesystem cache for compiled bytecode files,Expression d'affectation,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 positional-only-parameters}@anchor{98e}
@subsubsection Positional-only parameters


There is a new function parameter syntax @code{/} to indicate that some
function parameters must be specified positionally and cannot be used as
keyword arguments.  This is the same notation shown by @code{help()} for C
functions annotated with Larry Hastings'
Argument Clinic@footnote{https://devguide.python.org/development-tools/clinic/} tool.

Dans l’exemple suivant, les paramètres `a' et `b' sont uniquement positionnels alors que `c' et `d' peuvent être positionnels ou nommés tandis que `e' et `f' doivent être obligatoirement nommés :

@example
def f(a, b, /, c, d, *, e, f):
    print(a, b, c, d, e, f)
@end example

L’appel suivant est valide :

@example
f(10, 20, 30, d=40, e=50, f=60)
@end example

En revanche, celui-ci ne l’est pas :

@example
f(10, b=20, c=30, d=40, e=50, f=60)   # b cannot be a keyword argument
f(10, 20, 30, 40, 50, f=60)           # e must be a keyword argument
@end example

One use case for this notation is that it allows pure Python functions
to fully emulate behaviors of existing C coded functions.  For example,
the built-in @ref{98f,,divmod()} function does not accept keyword arguments:

@example
def divmod(a, b, /):
    "Emulate the built in divmod() function"
    return (a // b, a % b)
@end example

Another use case is to preclude keyword arguments when the parameter
name is not helpful.  For example, the builtin @ref{619,,len()} function has
the signature @code{len(obj, /)}.  This precludes awkward calls such as:

@example
len(obj='hello')  # The "obj" keyword argument impairs readability
@end example

A further benefit of marking a parameter as positional-only is that it
allows the parameter name to be changed in the future without risk of
breaking client code.  For example, in the @ref{d1,,statistics} module, the
parameter name `dist' may be changed in the future.  This was made
possible with the following function specification:

@example
def quantiles(dist, /, *, n=4, method='exclusive')
    ...
@end example

Since the parameters to the left of @code{/} are not exposed as possible
keywords, the parameters names remain available for use in @code{**kwargs}:

@example
>>> def f(a, b, /, **kwargs):
...     print(a, b, kwargs)
...
>>> f(10, 20, a=1, b=2, c=3)         # a and b are used in two ways
10 20 @{'a': 1, 'b': 2, 'c': 3@}
@end example

This greatly simplifies the implementation of functions and methods
that need to accept arbitrary keyword arguments.  For example, here
is an excerpt from code in the @ref{1d,,collections} module:

@example
class Counter(dict):

    def __init__(self, iterable=None, /, **kwds):
        # Note "iterable" is a possible keyword argument
@end example

Voir 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/} pour une description complète.

(Contribution de Pablo Galindo dans bpo-36540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36540}.)

@c TODO: Pablo will sprint on docs at PyCon US 2019.

@node Parallel filesystem cache for compiled bytecode files,Debug build uses the same ABI as release build,Positional-only parameters,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 parallel-filesystem-cache-for-compiled-bytecode-files}@anchor{990}
@subsubsection Parallel filesystem cache for compiled bytecode files


The new 
@geindex PYTHONPYCACHEPREFIX
@geindex variable d'environnement; PYTHONPYCACHEPREFIX
@ref{991,,PYTHONPYCACHEPREFIX} setting (also available as
@ref{175,,-X} @code{pycache_prefix}) configures the implicit bytecode
cache to use a separate parallel filesystem tree, rather than
the default @code{__pycache__} subdirectories within each source
directory.

The location of the cache is reported in @ref{992,,sys.pycache_prefix}
(@ref{660,,None} indicates the default location in @code{__pycache__}
subdirectories).

(Contributed by Carl Meyer in bpo-33499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33499}.)

@node Debug build uses the same ABI as release build,f-strings support = for self-documenting expressions and debugging,Parallel filesystem cache for compiled bytecode files,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 debug-build-uses-the-same-abi-as-release-build}@anchor{993}
@subsubsection Debug build uses the same ABI as release build


Python now uses the same ABI whether it's built in release or debug mode. On
Unix, when Python is built in debug mode, it is now possible to load C
extensions built in release mode and C extensions built using the stable ABI.

Release builds and @ref{1f6,,debug builds} are now ABI compatible: defining the
@code{Py_DEBUG} macro no longer implies the @code{Py_TRACE_REFS} macro, which
introduces the only ABI incompatibility. The @code{Py_TRACE_REFS} macro, which
adds the @ref{41b,,sys.getobjects()} function and the 
@geindex PYTHONDUMPREFS
@geindex variable d'environnement; PYTHONDUMPREFS
@ref{994,,PYTHONDUMPREFS}
environment variable, can be set using the new @ref{38b,,./configure --with-trace-refs} build option.
(Contributed by Victor Stinner in bpo-36465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36465}.)

On Unix, C extensions are no longer linked to libpython except on Android
and Cygwin.
It is now possible
for a statically linked Python to load a C extension built using a shared
library Python.
(Contributed by Victor Stinner in bpo-21536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21536}.)

On Unix, when Python is built in debug mode, import now also looks for C
extensions compiled in release mode and for C extensions compiled with the
stable ABI.
(Contributed by Victor Stinner in bpo-36722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36722}.)

To embed Python into an application, a new @code{--embed} option must be passed to
@code{python3-config --libs --embed} to get @code{-lpython3.8} (link the application
to libpython). To support both 3.8 and older, try @code{python3-config --libs
--embed} first and fallback to @code{python3-config --libs} (without @code{--embed})
if the previous command fails.

Add a pkg-config @code{python-3.8-embed} module to embed Python into an
application: @code{pkg-config python-3.8-embed --libs} includes @code{-lpython3.8}.
To support both 3.8 and older, try @code{pkg-config python-X.Y-embed --libs} first
and fallback to @code{pkg-config python-X.Y --libs} (without @code{--embed}) if the
previous command fails (replace @code{X.Y} with the Python version).

On the other hand, @code{pkg-config python3.8 --libs} no longer contains
@code{-lpython3.8}. C extensions must not be linked to libpython (except on
Android and Cygwin, whose cases are handled by the script);
this change is backward incompatible on purpose.
(Contributed by Victor Stinner in bpo-36721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36721}.)

@node f-strings support = for self-documenting expressions and debugging,PEP 578 Python Runtime Audit Hooks,Debug build uses the same ABI as release build,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 bpo-36817-whatsnew}@anchor{995}@anchor{whatsnew/3 8 f-strings-support-for-self-documenting-expressions-and-debugging}@anchor{996}
@subsubsection f-strings support @code{=} for self-documenting expressions and debugging


Le spécificateur @code{=} a été ajouté aux @ref{41f,,f-string}s. Une f-string telle que @code{f'@{expr=@}'} est transformée en : le texte de l’expression, le signe égal et le résultat de l’évaluation de l’expression. Par exemple :

@example
>>> user = 'eric_idle'
>>> member_since = date(1975, 7, 31)
>>> f'@{user=@} @{member_since=@}'
"user='eric_idle' member_since=datetime.date(1975, 7, 31)"
@end example

The usual @ref{997,,f-string format specifiers} allow more
control over how the result of the expression is displayed:

@example
>>> delta = date.today() - member_since
>>> f'@{user=!s@}  @{delta.days=:,d@}'
'user=eric_idle  delta.days=16,075'
@end example

The @code{=} specifier will display the whole expression so that
calculations can be shown:

@example
>>> print(f'@{theta=@}  @{cos(radians(theta))=:.3f@}')
theta=30  cos(radians(theta))=0.866
@end example

(Contributed by Eric V. Smith and Larry Hastings in bpo-36817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36817}.)

@node PEP 578 Python Runtime Audit Hooks,PEP 587 Python Initialization Configuration,f-strings support = for self-documenting expressions and debugging,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 pep-578-python-runtime-audit-hooks}@anchor{998}
@subsubsection PEP 578: Python Runtime Audit Hooks


The PEP adds an Audit Hook and Verified Open Hook. Both are available from
Python and native code, allowing applications and frameworks written in pure
Python code to take advantage of extra notifications, while also allowing
embedders or system administrators to deploy builds of Python where auditing is
always enabled.

See 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/} for full details.

@node PEP 587 Python Initialization Configuration,PEP 590 Vectorcall a fast calling protocol for CPython,PEP 578 Python Runtime Audit Hooks,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 pep-587-python-initialization-configuration}@anchor{999}
@subsubsection PEP 587: Python Initialization Configuration


The 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} adds a new C API to configure the Python Initialization
providing finer control on the whole configuration and better error reporting.

New structures:


@itemize *

@item 
@ref{39d,,PyConfig}

@item 
@ref{99a,,PyPreConfig}

@item 
@ref{99b,,PyStatus}

@item 
@ref{99c,,PyWideStringList}
@end itemize

Nouvelles fonctions :


@itemize *

@item 
@ref{99d,,PyConfig_Clear()}

@item 
@ref{99e,,PyConfig_InitIsolatedConfig()}

@item 
@ref{99f,,PyConfig_InitPythonConfig()}

@item 
@ref{77a,,PyConfig_Read()}

@item 
@ref{9a0,,PyConfig_SetArgv()}

@item 
@ref{9a1,,PyConfig_SetBytesArgv()}

@item 
@ref{9a2,,PyConfig_SetBytesString()}

@item 
@ref{9a3,,PyConfig_SetString()}

@item 
@ref{9a4,,PyPreConfig_InitIsolatedConfig()}

@item 
@ref{9a5,,PyPreConfig_InitPythonConfig()}

@item 
@ref{9a6,,PyStatus_Error()}

@item 
@ref{9a7,,PyStatus_Exception()}

@item 
@ref{9a8,,PyStatus_Exit()}

@item 
@ref{9a9,,PyStatus_IsError()}

@item 
@ref{9aa,,PyStatus_IsExit()}

@item 
@ref{9ab,,PyStatus_NoMemory()}

@item 
@ref{9ac,,PyStatus_Ok()}

@item 
@ref{9ad,,PyWideStringList_Append()}

@item 
@ref{9ae,,PyWideStringList_Insert()}

@item 
@ref{9af,,Py_BytesMain()}

@item 
@ref{9b0,,Py_ExitStatusException()}

@item 
@ref{3bc,,Py_InitializeFromConfig()}

@item 
@ref{3e2,,Py_PreInitialize()}

@item 
@ref{9b1,,Py_PreInitializeFromArgs()}

@item 
@ref{9b2,,Py_PreInitializeFromBytesArgs()}

@item 
@ref{9b3,,Py_RunMain()}
@end itemize

This PEP also adds @code{_PyRuntimeState.preconfig} (@ref{99a,,PyPreConfig} type)
and @code{PyInterpreterState.config} (@ref{39d,,PyConfig} type) fields to these
internal structures. @code{PyInterpreterState.config} becomes the new
reference configuration, replacing global configuration variables and
other private variables.

See @ref{39e,,Python Initialization Configuration} for the
documentation.

See 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} for a full description.

(Contributed by Victor Stinner in bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}.)

@node PEP 590 Vectorcall a fast calling protocol for CPython,Pickle protocol 5 with out-of-band data buffers,PEP 587 Python Initialization Configuration,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 pep-590-vectorcall-a-fast-calling-protocol-for-cpython}@anchor{9b4}
@subsubsection PEP 590: Vectorcall: a fast calling protocol for CPython


@ref{53d,,The Vectorcall Protocol} is added to the Python/C API.
It is meant to formalize existing optimizations which were already done
for various classes.
Any @ref{769,,static type} implementing a callable can use this
protocol.

This is currently provisional.
The aim is to make it fully public in Python 3.9.

See 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} for a full description.

(Contributed by Jeroen Demeyer, Mark Shannon and Petr Viktorin in bpo-36974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36974}.)

@node Pickle protocol 5 with out-of-band data buffers,,PEP 590 Vectorcall a fast calling protocol for CPython,Nouvelles fonctionnalités<11>
@anchor{whatsnew/3 8 pickle-protocol-5-with-out-of-band-data-buffers}@anchor{9b5}
@subsubsection Pickle protocol 5 with out-of-band data buffers


When @ref{a5,,pickle} is used to transfer large data between Python processes
in order to take advantage of multi-core or multi-machine processing,
it is important to optimize the transfer by reducing memory copies, and
possibly by applying custom techniques such as data-dependent compression.

The @ref{a5,,pickle} protocol 5 introduces support for out-of-band buffers
where 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/}-compatible data can be transmitted separately from the
main pickle stream, at the discretion of the communication layer.

See 
@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} for a full description.

(Contributed by Antoine Pitrou in bpo-36785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36785}.)

@node Autres changements au langage<6>,Nouveaux modules<6>,Nouvelles fonctionnalités<11>,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 other-language-changes}@anchor{9b6}
@subsection Autres changements au langage



@itemize *

@item 
A @ref{9b7,,continue} statement was illegal in the @ref{9b8,,finally} clause
due to a problem with the implementation.  In Python 3.8 this restriction
was lifted.
(Contributed by Serhiy Storchaka in bpo-32489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32489}.)

@item 
The @ref{451,,bool}, @ref{254,,int}, and @ref{1e4,,fractions.Fraction} types
now have an @ref{9b9,,as_integer_ratio()} method like that found in
@ref{2eb,,float} and @ref{29a,,decimal.Decimal}.  This minor API extension
makes it possible to write @code{numerator, denominator =
x.as_integer_ratio()} and have it work across multiple numeric types.
(Contributed by Lisa Roach in bpo-33073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33073} and Raymond Hettinger in
bpo-37819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37819}.)

@item 
Constructors of @ref{254,,int}, @ref{2eb,,float} and @ref{2ec,,complex} will now
use the @ref{707,,__index__()} special method, if available and the
corresponding method @ref{706,,__int__()}, @ref{9ba,,__float__()}
or @ref{5d1,,__complex__()} is not available.
(Contributed by Serhiy Storchaka in bpo-20092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20092}.)

@item 
Added support of @code{\N@{@var{name}@}} escapes in @ref{b8,,regular expressions}:

@example
>>> notice = 'Copyright © 2019'
>>> copyright_year_pattern = re.compile(r'\N@{copyright sign@}\s*(\d@{4@})')
>>> int(copyright_year_pattern.search(notice).group(1))
2019
@end example

(Contributed by Jonathan Eunice and Serhiy Storchaka in bpo-30688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30688}.)

@item 
Dict and dictviews are now iterable in reversed insertion order using
@ref{850,,reversed()}. (Contributed by Rémi Lapeyre in bpo-33462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33462}.)

@item 
The syntax allowed for keyword names in function calls was further
restricted. In particular, @code{f((keyword)=arg)} is no longer allowed. It was
never intended to permit more than a bare name on the left-hand side of a
keyword argument assignment term.
(Contributed by Benjamin Peterson in bpo-34641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34641}.)

@item 
Generalized iterable unpacking in @ref{9bb,,yield} and
@ref{9bc,,return} statements no longer requires enclosing parentheses.
This brings the `yield' and `return' syntax into better agreement with
normal assignment syntax:

@example
>>> def parse(family):
        lastname, *members = family.split()
        return lastname.upper(), *members

>>> parse('simpsons homer marge bart lisa maggie')
('SIMPSONS', 'homer', 'marge', 'bart', 'lisa', 'maggie')
@end example

(Contributed by David Cuthbert and Jordan Chapman in bpo-32117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32117}.)

@item 
When a comma is missed in code such as @code{[(10, 20) (30, 40)]}, the
compiler displays a @ref{44f,,SyntaxWarning} with a helpful suggestion.
This improves on just having a @ref{522,,TypeError} indicating that the
first tuple was not callable.  (Contributed by Serhiy Storchaka in
bpo-15248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15248}.)

@item 
Arithmetic operations between subclasses of @ref{1c8,,datetime.date} or
@ref{1c7,,datetime.datetime} and @ref{9bd,,datetime.timedelta} objects now return
an instance of the subclass, rather than the base class. This also affects
the return type of operations whose implementation (directly or indirectly)
uses @ref{9bd,,datetime.timedelta} arithmetic, such as
@ref{9be,,astimezone()}.
(Contributed by Paul Ganssle in bpo-32417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32417}.)

@item 
When the Python interpreter is interrupted by Ctrl-C (SIGINT) and the
resulting @ref{9bf,,KeyboardInterrupt} exception is not caught, the Python process
now exits via a SIGINT signal or with the correct exit code such that the
calling process can detect that it died due to a Ctrl-C.  Shells on POSIX
and Windows use this to properly terminate scripts in interactive sessions.
(Contributed by Google via Gregory P. Smith in bpo-1054041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1054041}.)

@item 
Some advanced styles of programming require updating the
@ref{2dd,,types.CodeType} object for an existing function.  Since code
objects are immutable, a new code object needs to be created, one
that is modeled on the existing code object.  With 19 parameters,
this was somewhat tedious.  Now, the new @code{replace()} method makes
it possible to create a clone with a few altered parameters.

Here's an example that alters the @ref{6bc,,statistics.mean()} function to
prevent the `data' parameter from being used as a keyword argument:

@example
>>> from statistics import mean
>>> mean(data=[10, 20, 90])
40
>>> mean.__code__ = mean.__code__.replace(co_posonlyargcount=1)
>>> mean(data=[10, 20, 90])
Traceback (most recent call last):
  ...
TypeError: mean() got some positional-only arguments passed as keyword arguments: 'data'
@end example

(Contributed by Victor Stinner in bpo-37032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37032}.)

@item 
For integers, the three-argument form of the @ref{9c0,,pow()} function now
permits the exponent to be negative in the case where the base is
relatively prime to the modulus. It then computes a modular inverse to
the base when the exponent is @code{-1}, and a suitable power of that
inverse for other negative exponents.  For example, to compute the
modular multiplicative inverse@footnote{https://en.wikipedia.org/wiki/Modular_multiplicative_inverse} of 38
modulo 137, write:

@example
>>> pow(38, -1, 137)
119
>>> 119 * 38 % 137
1
@end example

Modular inverses arise in the solution of linear Diophantine equations@footnote{https://en.wikipedia.org/wiki/Diophantine_equation}.
For example, to find integer solutions for @code{4258𝑥 + 147𝑦 = 369},
first rewrite as @code{4258𝑥 ≡ 369 (mod 147)} then solve:

@example
>>> x = 369 * pow(4258, -1, 147) % 147
>>> y = (4258 * x - 369) // -147
>>> 4258 * x + 147 * y
369
@end example

(Contributed by Mark Dickinson in bpo-36027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36027}.)

@item 
Dict comprehensions have been synced-up with dict literals so that the
key is computed first and the value second:

@example
>>> # Dict comprehension
>>> cast = @{input('role? '): input('actor? ') for i in range(2)@}
role? King Arthur
actor? Chapman
role? Black Knight
actor? Cleese

>>> # Dict literal
>>> cast = @{input('role? '): input('actor? ')@}
role? Sir Robin
actor? Eric Idle
@end example

The guaranteed execution order is helpful with assignment expressions
because variables assigned in the key expression will be available in
the value expression:

@example
>>> names = ['Martin von Löwis', 'Łukasz Langa', 'Walter Dörwald']
>>> @{(n := normalize('NFC', name)).casefold() : n for name in names@}
@{'martin von löwis': 'Martin von Löwis',
 'łukasz langa': 'Łukasz Langa',
 'walter dörwald': 'Walter Dörwald'@}
@end example

(Contributed by Jörn Heissler in bpo-35224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35224}.)

@item 
The @ref{9c1,,object.__reduce__()} method can now return a tuple from two to
six elements long. Formerly, five was the limit.  The new, optional sixth
element is a callable with a @code{(obj, state)} signature.  This allows the
direct control over the state-updating behavior of a specific object.  If
not `None', this callable will have priority over the object's
@code{__setstate__()} method.
(Contributed by Pierre Glaser and Olivier Grisel in bpo-35900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35900}.)
@end itemize

@node Nouveaux modules<6>,Modules améliorés<6>,Autres changements au langage<6>,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 new-modules}@anchor{9c2}
@subsection Nouveaux modules



@itemize *

@item 
The new @ref{79,,importlib.metadata} module provides (provisional) support for
reading metadata from third-party packages.  For example, it can extract an
installed package's version number, list of entry points, and more:

@example
>>> # Note following example requires that the popular "requests"
>>> # package has been installed.
>>>
>>> from importlib.metadata import version, requires, files
>>> version('requests')
'2.22.0'
>>> list(requires('requests'))
['chardet (<3.1.0,>=3.0.2)']
>>> list(files('requests'))[:5]
[PackagePath('requests-2.22.0.dist-info/INSTALLER'),
 PackagePath('requests-2.22.0.dist-info/LICENSE'),
 PackagePath('requests-2.22.0.dist-info/METADATA'),
 PackagePath('requests-2.22.0.dist-info/RECORD'),
 PackagePath('requests-2.22.0.dist-info/WHEEL')]
@end example

(Contributed by Barry Warsaw and Jason R. Coombs in bpo-34632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34632}.)
@end itemize

@node Modules améliorés<6>,Optimizations,Nouveaux modules<6>,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 improved-modules}@anchor{9c3}
@subsection Modules améliorés


@menu
* ast: ast<3>. 
* asyncio: asyncio<6>. 
* builtins: builtins<2>. 
* collections:: 
* cProfile:: 
* csv: csv<2>. 
* curses: curses<3>. 
* ctypes: ctypes<2>. 
* datetime: datetime<3>. 
* functools: functools<2>. 
* gc: gc<3>. 
* gettext:: 
* gzip: gzip<3>. 
* IDLE et idlelib: IDLE et idlelib<4>. 
* inspect: inspect<5>. 
* io: io<3>. 
* itertools: itertools<4>. 
* json.tool: json tool. 
* logging: logging<2>. 
* math: math<5>. 
* mmap: mmap<2>. 
* multiprocessing: multiprocessing<3>. 
* os: os<6>. 
* os.path: os path<4>. 
* pathlib: pathlib<7>. 
* pickle:: 
* plistlib:: 
* pprint: pprint<3>. 
* py_compile: py_compile<2>. 
* shlex:: 
* shutils: shutils<4>. 
* socket: socket<4>. 
* ssl: ssl<4>. 
* statistics: statistics<4>. 
* sys: sys<7>. 
* tarfile: tarfile<4>. 
* threading: threading<4>. 
* tokenize: tokenize<2>. 
* tkinter: tkinter<4>. 
* time: time<4>. 
* typing: typing<8>. 
* unicodedata: unicodedata<5>. 
* unittest: unittest<6>. 
* venv: venv<4>. 
* weakref:: 
* xml: xml<4>. 
* xmlrpc:: 

@end menu

@node ast<3>,asyncio<6>,,Modules améliorés<6>
@anchor{whatsnew/3 8 ast}@anchor{9c4}
@subsubsection ast


AST nodes now have @code{end_lineno} and @code{end_col_offset} attributes,
which give the precise location of the end of the node.  (This only
applies to nodes that have @code{lineno} and @code{col_offset} attributes.)

New function @ref{9c5,,ast.get_source_segment()} returns the source code
for a specific AST node.

(Contributed by Ivan Levkivskyi in bpo-33416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33416}.)

The @ref{1a6,,ast.parse()} function has some new flags:


@itemize *

@item 
@code{type_comments=True} causes it to return the text of 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} and
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} type comments associated with certain AST nodes;

@item 
@code{mode='func_type'} can be used to parse 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} "signature type
comments" (returned for function definition AST nodes);

@item 
@code{feature_version=(3, N)} allows specifying an earlier Python 3
version.  For example, @code{feature_version=(3, 4)} will treat
@ref{71c,,async} and @ref{1b7,,await} as non-reserved words.
@end itemize

(Contributed by Guido van Rossum in bpo-35766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35766}.)

@node asyncio<6>,builtins<2>,ast<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 asyncio}@anchor{9c6}
@subsubsection asyncio


@ref{466,,asyncio.run()} has graduated from the provisional to stable API. This
function can be used to execute a @ref{47b,,coroutine} and return the result while
automatically managing the event loop. For example:

@example
import asyncio

async def main():
    await asyncio.sleep(0)
    return 42

asyncio.run(main())
@end example

This is `roughly' equivalent to:

@example
import asyncio

async def main():
    await asyncio.sleep(0)
    return 42

loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
try:
    loop.run_until_complete(main())
finally:
    asyncio.set_event_loop(None)
    loop.close()
@end example

The actual implementation is significantly more complex. Thus,
@ref{466,,asyncio.run()} should be the preferred way of running asyncio programs.

(Contributed by Yury Selivanov in bpo-32314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32314}.)

Running @code{python -m asyncio} launches a natively async REPL.  This allows rapid
experimentation with code that has a top-level @ref{1b7,,await}.  There is no
longer a need to directly call @code{asyncio.run()} which would spawn a new event
loop on every invocation:

@example
$ python -m asyncio
asyncio REPL 3.8.0
Use "await" directly instead of "asyncio.run()".
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>> await asyncio.sleep(10, result='hello')
hello
@end example

(Contributed by Yury Selivanov in bpo-37028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37028}.)

The exception @ref{1b6,,asyncio.CancelledError} now inherits from
@ref{5a5,,BaseException} rather than @ref{9c7,,Exception} and no longer inherits
from @ref{9c8,,concurrent.futures.CancelledError}.
(Contributed by Yury Selivanov in bpo-32528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32528}.)

On Windows, the default event loop is now @ref{5f4,,ProactorEventLoop}.
(Contributed by Victor Stinner in bpo-34687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34687}.)

@ref{5f4,,ProactorEventLoop} now also supports UDP.
(Contributed by Adam Meily and Andrew Svetlov in bpo-29883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29883}.)

@ref{5f4,,ProactorEventLoop} can now be interrupted by
@ref{9bf,,KeyboardInterrupt} ("CTRL+C").
(Contributed by Vladimir Matveev in bpo-23057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23057}.)

Added @ref{9c9,,asyncio.Task.get_coro()} for getting the wrapped coroutine
within an @ref{4c2,,asyncio.Task}.
(Contributed by Alex Grönholm in bpo-36999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36999}.)

Asyncio tasks can now be named, either by passing the @code{name} keyword
argument to @ref{5e7,,asyncio.create_task()} or
the @ref{9ca,,create_task()} event loop method, or by
calling the @ref{9cb,,set_name()} method on the task object. The
task name is visible in the @code{repr()} output of @ref{4c2,,asyncio.Task} and
can also be retrieved using the @ref{9cc,,get_name()} method.
(Contributed by Alex Grönholm in bpo-34270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34270}.)

Added support for
Happy Eyeballs@footnote{https://en.wikipedia.org/wiki/Happy_Eyeballs} to
@ref{5ee,,asyncio.loop.create_connection()}. To specify the behavior, two new
parameters have been added: `happy_eyeballs_delay' and `interleave'. The Happy
Eyeballs algorithm improves responsiveness in applications that support IPv4
and IPv6 by attempting to simultaneously connect using both.
(Contributed by twisteroid ambassador in bpo-33530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33530}.)

@node builtins<2>,collections,asyncio<6>,Modules améliorés<6>
@anchor{whatsnew/3 8 builtins}@anchor{9cd}
@subsubsection builtins


The @ref{190,,compile()} built-in has been improved to accept the
@code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} flag. With this new flag passed,
@ref{190,,compile()} will allow top-level @code{await}, @code{async for} and @code{async with}
constructs that are usually considered invalid syntax. Asynchronous code object
marked with the @code{CO_COROUTINE} flag may then be returned.
(Contributed by Matthias Bussonnier in bpo-34616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34616})

@node collections,cProfile,builtins<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 collections}@anchor{9ce}
@subsubsection collections


The @ref{9cf,,_asdict()} method for
@ref{1c5,,collections.namedtuple()} now returns a @ref{253,,dict} instead of a
@ref{5c5,,collections.OrderedDict}. This works because regular dicts have
guaranteed ordering since Python 3.7. If the extra features of
@code{OrderedDict} are required, the suggested remediation is to cast the
result to the desired type: @code{OrderedDict(nt._asdict())}.
(Contributed by Raymond Hettinger in bpo-35864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35864}.)

@node cProfile,csv<2>,collections,Modules améliorés<6>
@anchor{whatsnew/3 8 cprofile}@anchor{9d0}
@subsubsection cProfile


The @ref{9d1,,cProfile.Profile} class can now be used as a context manager.
Profile a block of code by running:

@example
import cProfile

with cProfile.Profile() as profiler:
      # code to be profiled
      ...
@end example

(Contributed by Scott Sanderson in bpo-29235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29235}.)

@node csv<2>,curses<3>,cProfile,Modules améliorés<6>
@anchor{whatsnew/3 8 csv}@anchor{9d2}
@subsubsection csv


The @ref{9d3,,csv.DictReader} now returns instances of @ref{253,,dict} instead of
a @ref{5c5,,collections.OrderedDict}.  The tool is now faster and uses less
memory while still preserving the field order.
(Contributed by Michael Selik in bpo-34003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34003}.)

@node curses<3>,ctypes<2>,csv<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 curses}@anchor{9d4}
@subsubsection curses


Added a new variable holding structured version information for the
underlying ncurses library: @ref{9d5,,ncurses_version}.
(Contributed by Serhiy Storchaka in bpo-31680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31680}.)

@node ctypes<2>,datetime<3>,curses<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 ctypes}@anchor{9d6}
@subsubsection ctypes


On Windows, @ref{9d7,,CDLL} and subclasses now accept a `winmode' parameter
to specify flags for the underlying @code{LoadLibraryEx} call. The default flags are
set to only load DLL dependencies from trusted locations, including the path
where the DLL is stored (if a full or partial path is used to load the initial
DLL) and paths added by @ref{9d8,,add_dll_directory()}.
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

@node datetime<3>,functools<2>,ctypes<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 datetime}@anchor{9d9}
@subsubsection datetime


Added new alternate constructors @ref{9da,,datetime.date.fromisocalendar()} and
@ref{9db,,datetime.datetime.fromisocalendar()}, which construct @ref{1c8,,date} and
@ref{1c7,,datetime} objects respectively from ISO year, week number, and weekday;
these are the inverse of each class's @code{isocalendar} method.
(Contributed by Paul Ganssle in bpo-36004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36004}.)

@node functools<2>,gc<3>,datetime<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 functools}@anchor{9dc}
@subsubsection functools


@ref{9dd,,functools.lru_cache()} can now be used as a straight decorator rather
than as a function returning a decorator.  So both of these are now supported:

@example
@@lru_cache
def f(x):
    ...

@@lru_cache(maxsize=256)
def f(x):
    ...
@end example

(Contributed by Raymond Hettinger in bpo-36772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36772}.)

Added a new @ref{52c,,functools.cached_property()} decorator, for computed properties
cached for the life of the instance.

@example
import functools
import statistics

class Dataset:
   def __init__(self, sequence_of_numbers):
      self.data = sequence_of_numbers

   @@functools.cached_property
   def variance(self):
      return statistics.variance(self.data)
@end example

(Contributed by Carl Meyer in bpo-21145@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21145})

Added a new @ref{9de,,functools.singledispatchmethod()} decorator that converts
methods into @ref{9df,,generic functions} using
@ref{9e0,,single dispatch}:

@example
from functools import singledispatchmethod
from contextlib import suppress

class TaskManager:

    def __init__(self, tasks):
        self.tasks = list(tasks)

    @@singledispatchmethod
    def discard(self, value):
        with suppress(ValueError):
            self.tasks.remove(value)

    @@discard.register(list)
    def _(self, tasks):
        targets = set(tasks)
        self.tasks = [x for x in self.tasks if x not in targets]
@end example

(Contributed by Ethan Smith in bpo-32380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32380})

@node gc<3>,gettext,functools<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 gc}@anchor{9e1}
@subsubsection `gc'


@ref{7ed,,get_objects()} can now receive an optional `generation' parameter
indicating a generation to get objects from.
(Contributed by Pablo Galindo in bpo-36016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36016}.)

@node gettext,gzip<3>,gc<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 gettext}@anchor{9e2}
@subsubsection gettext


Added @ref{9e3,,pgettext()} and its variants.
(Contributed by Franz Glasner, Éric Araujo, and Cheryl Sabella in bpo-2504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2504}.)

@node gzip<3>,IDLE et idlelib<4>,gettext,Modules améliorés<6>
@anchor{whatsnew/3 8 gzip}@anchor{9e4}
@subsubsection gzip


Added the `mtime' parameter to @ref{629,,gzip.compress()} for reproducible output.
(Contributed by Guo Ci Teo in bpo-34898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34898}.)

A @ref{9e5,,BadGzipFile} exception is now raised instead of @ref{40d,,OSError}
for certain types of invalid or corrupt gzip files.
(Contributed by Filip Gruszczyński, Michele Orrù, and Zackery Spytz in
bpo-6584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6584}.)

@node IDLE et idlelib<4>,inspect<5>,gzip<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 idle-and-idlelib}@anchor{9e6}
@subsubsection `IDLE' et `idlelib'


Output over N lines (50 by default) is squeezed down to a button.
N can be changed in the PyShell section of the General page of the
Settings dialog.  Fewer, but possibly extra long, lines can be squeezed by
right clicking on the output.  Squeezed output can be expanded in place
by double-clicking the button or into the clipboard or a separate window
by right-clicking the button.  (Contributed by Tal Einat in bpo-1529353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1529353}.)

Add "Run Customized" to the Run menu to run a module with customized
settings. Any command line arguments entered are added to sys.argv.
They also re-appear in the box for the next customized run.  One can also
suppress the normal Shell main module restart.  (Contributed by Cheryl
Sabella, Terry Jan Reedy, and others in bpo-5680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5680} and bpo-37627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37627}.)

Added optional line numbers for IDLE editor windows. Windows
open without line numbers unless set otherwise in the General
tab of the configuration dialog.  Line numbers for an existing
window are shown and hidden in the Options menu.
(Contributed by Tal Einat and Saimadhav Heblikar in bpo-17535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17535}.)

OS native encoding is now used for converting between Python strings and Tcl
objects. This allows IDLE to work with emoji and other non-BMP characters.
These characters can be displayed or copied and pasted to or from the
clipboard.  Converting strings from Tcl to Python and back now never fails.
(Many people worked on this for eight years but the problem was finally
solved by Serhiy Storchaka in bpo-13153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13153}.)

New in 3.8.1:

Add option to toggle cursor blink off.  (Contributed by Zackery Spytz
in bpo-4603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4603}.)

La fenêtre de complétion de IDLE est maintenant fermée par la touche d'échappement (contribution de `Johnny Najera' dans bpo-38944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38944}).

The changes above have been backported to 3.7 maintenance releases.

Add keywords to module name completion list.  (Contributed by Terry J.
Reedy in bpo-37765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37765}.)

@node inspect<5>,io<3>,IDLE et idlelib<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 inspect}@anchor{9e7}
@subsubsection `inspect'


The @ref{9e8,,inspect.getdoc()} function can now find docstrings for @code{__slots__}
if that attribute is a @ref{253,,dict} where the values are docstrings.
This provides documentation options similar to what we already have
for @ref{192,,property()}, @ref{165,,classmethod()}, and @ref{40c,,staticmethod()}:

@example
class AudioClip:
    __slots__ = @{'bit_rate': 'expressed in kilohertz to one decimal place',
                 'duration': 'in seconds, rounded up to an integer'@}
    def __init__(self, bit_rate, duration):
        self.bit_rate = round(bit_rate / 1000.0, 1)
        self.duration = ceil(duration)
@end example

(Contributed by Raymond Hettinger in bpo-36326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36326}.)

@node io<3>,itertools<4>,inspect<5>,Modules améliorés<6>
@anchor{whatsnew/3 8 io}@anchor{9e9}
@subsubsection io


In development mode (@ref{175,,-X} @code{env}) and in @ref{1f6,,debug build}, the
@ref{1f2,,io.IOBase} finalizer now logs the exception if the @code{close()} method
fails. The exception is ignored silently by default in release build.
(Contributed by Victor Stinner in bpo-18748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18748}.)

@node itertools<4>,json tool,io<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 itertools}@anchor{9ea}
@subsubsection itertools


The @ref{9eb,,itertools.accumulate()} function added an option `initial' keyword
argument to specify an initial value:

@example
>>> from itertools import accumulate
>>> list(accumulate([10, 5, 30, 15], initial=1000))
[1000, 1010, 1015, 1045, 1060]
@end example

(Contributed by Lisa Roach in bpo-34659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34659}.)

@node json tool,logging<2>,itertools<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 json-tool}@anchor{9ec}
@subsubsection json.tool


Add option @code{--json-lines} to parse every input line as a separate JSON object.
(Contributed by Weipeng Hong in bpo-31553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31553}.)

@node logging<2>,math<5>,json tool,Modules améliorés<6>
@anchor{whatsnew/3 8 logging}@anchor{9ed}
@subsubsection logging


Added a `force' keyword argument to @ref{9ee,,logging.basicConfig()}.
When set to true, any existing handlers attached
to the root logger are removed and closed before carrying out the
configuration specified by the other arguments.

This solves a long-standing problem.  Once a logger or `basicConfig()' had
been called, subsequent calls to `basicConfig()' were silently ignored.
This made it difficult to update, experiment with, or teach the various
logging configuration options using the interactive prompt or a Jupyter
notebook.

(Suggested by Raymond Hettinger, implemented by Donghee Na, and
reviewed by Vinay Sajip in bpo-33897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33897}.)

@node math<5>,mmap<2>,logging<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 math}@anchor{9ef}
@subsubsection `math'


Added new function @ref{9f0,,math.dist()} for computing Euclidean distance
between two points.  (Contributed by Raymond Hettinger in bpo-33089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33089}.)

Expanded the @ref{9f1,,math.hypot()} function to handle multiple dimensions.
Formerly, it only supported the 2-D case.
(Contributed by Raymond Hettinger in bpo-33089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33089}.)

Added new function, @ref{9f2,,math.prod()}, as analogous function to @ref{454,,sum()}
that returns the product of a 'start' value (default: 1) times an iterable of
numbers:

@example
>>> prior = 0.8
>>> likelihoods = [0.625, 0.84, 0.30]
>>> math.prod(likelihoods, start=prior)
0.126
@end example

(Contributed by Pablo Galindo in bpo-35606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35606}.)

Added two new combinatoric functions @ref{6bb,,math.perm()} and @ref{6ba,,math.comb()}:

@example
>>> math.perm(10, 3)    # Permutations of 10 things taken 3 at a time
720
>>> math.comb(10, 3)    # Combinations of 10 things taken 3 at a time
120
@end example

(Contributed by Yash Aggarwal, Keller Fuchs, Serhiy Storchaka, and Raymond
Hettinger in bpo-37128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37128}, bpo-37178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37178}, and bpo-35431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35431}.)

Added a new function @ref{9f3,,math.isqrt()} for computing accurate integer square
roots without conversion to floating point.  The new function supports
arbitrarily large integers.  It is faster than @code{floor(sqrt(n))} but slower
than @ref{9f4,,math.sqrt()}:

@example
>>> r = 650320427
>>> s = r ** 2
>>> isqrt(s - 1)         # correct
650320426
>>> floor(sqrt(s - 1))   # incorrect
650320427
@end example

(Contributed by Mark Dickinson in bpo-36887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36887}.)

The function @ref{934,,math.factorial()} no longer accepts arguments that are not
int-like. (Contributed by Pablo Galindo in bpo-33083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33083}.)

@node mmap<2>,multiprocessing<3>,math<5>,Modules améliorés<6>
@anchor{whatsnew/3 8 mmap}@anchor{9f5}
@subsubsection mmap


The @ref{208,,mmap.mmap} class now has an @ref{9f6,,madvise()} method to
access the @code{madvise()} system call.
(Contributed by Zackery Spytz in bpo-32941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32941}.)

@node multiprocessing<3>,os<6>,mmap<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 multiprocessing}@anchor{9f7}
@subsubsection multiprocessing


Added new @ref{98,,multiprocessing.shared_memory} module.
(Contributed by Davin Potts in bpo-35813@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35813}.)

On macOS, the `spawn' start method is now used by default.
(Contributed by Victor Stinner in bpo-33725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33725}.)

@node os<6>,os path<4>,multiprocessing<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 os}@anchor{9f8}
@subsubsection `os'


Added new function @ref{9d8,,add_dll_directory()} on Windows for providing
additional search paths for native dependencies when importing extension
modules or loading DLLs using @ref{2a,,ctypes}.
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

A new @ref{9f9,,os.memfd_create()} function was added to wrap the
@code{memfd_create()} syscall.
(Contributed by Zackery Spytz and Christian Heimes in bpo-26836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26836}.)

On Windows, much of the manual logic for handling reparse points (including
symlinks and directory junctions) has been delegated to the operating system.
Specifically, @ref{48a,,os.stat()} will now traverse anything supported by the
operating system, while @ref{48b,,os.lstat()} will only open reparse points that
identify as "name surrogates" while others are opened as for @ref{48a,,os.stat()}.
In all cases, @code{stat_result.st_mode} will only have @code{S_IFLNK} set for
symbolic links and not other kinds of reparse points. To identify other kinds
of reparse point, check the new @code{stat_result.st_reparse_tag} attribute.

On Windows, @ref{90d,,os.readlink()} is now able to read directory junctions. Note
that @ref{9fa,,islink()} will return @code{False} for directory junctions,
and so code that checks @code{islink} first will continue to treat junctions as
directories, while code that handles errors from @ref{90d,,os.readlink()} may now
treat junctions as links.

(Contributed by Steve Dower in bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834}.)

@node os path<4>,pathlib<7>,os<6>,Modules améliorés<6>
@anchor{whatsnew/3 8 os-path}@anchor{9fb}
@subsubsection @code{os.path}


@ref{a1,,os.path} functions that return a boolean result like
@ref{9fc,,exists()}, @ref{9fd,,lexists()}, @ref{9fe,,isdir()},
@ref{9ff,,isfile()}, @ref{9fa,,islink()}, and @ref{a00,,ismount()}
now return @code{False} instead of raising @ref{1ff,,ValueError} or its subclasses
@ref{662,,UnicodeEncodeError} and @ref{a01,,UnicodeDecodeError} for paths that contain
characters or bytes unrepresentable at the OS level.
(Contributed by Serhiy Storchaka in bpo-33721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33721}.)

@ref{a02,,expanduser()} on Windows now prefers the 
@geindex USERPROFILE
@geindex variable d'environnement; USERPROFILE
@code{USERPROFILE}
environment variable and does not use 
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME}, which is not normally set
for regular user accounts.
(Contributed by Anthony Sottile in bpo-36264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36264}.)

@ref{9fe,,isdir()} on Windows no longer returns @code{True} for a link to a
non-existent directory.

@ref{222,,realpath()} on Windows now resolves reparse points, including
symlinks and directory junctions.

(Contributed by Steve Dower in bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834}.)

@node pathlib<7>,pickle,os path<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 pathlib}@anchor{a03}
@subsubsection pathlib


@ref{226,,pathlib.Path} methods that return a boolean result like
@ref{a04,,exists()}, @ref{22d,,is_dir()},
@ref{22c,,is_file()}, @ref{a05,,is_mount()},
@ref{a06,,is_symlink()}, @ref{a07,,is_block_device()},
@ref{a08,,is_char_device()}, @ref{a09,,is_fifo()},
@ref{a0a,,is_socket()} now return @code{False} instead of raising
@ref{1ff,,ValueError} or its subclass @ref{662,,UnicodeEncodeError} for paths that
contain characters unrepresentable at the OS level.
(Contributed by Serhiy Storchaka in bpo-33721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33721}.)

Added @code{pathlib.Path.link_to()} which creates a hard link pointing
to a path.
(Contributed by Joannah Nanjekye in bpo-26978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26978})
Note that @code{link_to} was deprecated in 3.10 and removed in 3.12 in
favor of a @code{hardlink_to} method added in 3.10 which matches the
semantics of the existing @code{symlink_to} method.

@node pickle,plistlib,pathlib<7>,Modules améliorés<6>
@anchor{whatsnew/3 8 pickle}@anchor{a0b}
@subsubsection pickle


@ref{a5,,pickle} extensions subclassing the C-optimized @ref{a0c,,Pickler}
can now override the pickling logic of functions and classes by defining the
special @ref{a0d,,reducer_override()} method.
(Contributed by Pierre Glaser and Olivier Grisel in bpo-35900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35900}.)

@node plistlib,pprint<3>,pickle,Modules améliorés<6>
@anchor{whatsnew/3 8 plistlib}@anchor{a0e}
@subsubsection plistlib


Added new @ref{a0f,,plistlib.UID} and enabled support for reading and writing
NSKeyedArchiver-encoded binary plists.
(Contributed by Jon Janzen in bpo-26707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26707}.)

@node pprint<3>,py_compile<2>,plistlib,Modules améliorés<6>
@anchor{whatsnew/3 8 pprint}@anchor{a10}
@subsubsection `pprint'


The @ref{ad,,pprint} module added a `sort_dicts' parameter to several functions.
By default, those functions continue to sort dictionaries before rendering or
printing.  However, if `sort_dicts' is set to false, the dictionaries retain
the order that keys were inserted.  This can be useful for comparison to JSON
inputs during debugging.

In addition, there is a convenience new function, @ref{a11,,pprint.pp()} that is
like @ref{812,,pprint.pprint()} but with `sort_dicts' defaulting to @code{False}:

@example
>>> from pprint import pprint, pp
>>> d = dict(source='input.txt', operation='filter', destination='output.txt')
>>> pp(d, width=40)                  # Original order
@{'source': 'input.txt',
 'operation': 'filter',
 'destination': 'output.txt'@}
>>> pprint(d, width=40)              # Keys sorted alphabetically
@{'destination': 'output.txt',
 'operation': 'filter',
 'source': 'input.txt'@}
@end example

(Contributed by Rémi Lapeyre in bpo-30670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30670}.)

@node py_compile<2>,shlex,pprint<3>,Modules améliorés<6>
@anchor{whatsnew/3 8 py-compile}@anchor{a12}
@subsubsection @code{py_compile}


@ref{a13,,py_compile.compile()} now supports silent mode.
(Contributed by Joannah Nanjekye in bpo-22640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22640}.)

@node shlex,shutils<4>,py_compile<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 shlex}@anchor{a14}
@subsubsection shlex


The new @ref{a15,,shlex.join()} function acts as the inverse of @ref{526,,shlex.split()}.
(Contributed by Bo Bayles in bpo-32102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32102}.)

@node shutils<4>,socket<4>,shlex,Modules améliorés<6>
@anchor{whatsnew/3 8 shutil}@anchor{a16}
@subsubsection @code{shutils}


@ref{a17,,shutil.copytree()} now accepts a new @code{dirs_exist_ok} keyword argument.
(Contributed by Josh Bronson in bpo-20849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20849}.)

@ref{49c,,shutil.make_archive()} now defaults to the modern pax (POSIX.1-2001)
format for new archives to improve portability and standards conformance,
inherited from the corresponding change to the @ref{dd,,tarfile} module.
(Contributed by C.A.M. Gerlach in bpo-30661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30661}.)

@ref{2f5,,shutil.rmtree()} on Windows now removes directory junctions without
recursively removing their contents first.
(Contributed by Steve Dower in bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834}.)

@node socket<4>,ssl<4>,shutils<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 socket}@anchor{a18}
@subsubsection `socket'


Added @ref{a19,,create_server()} and @ref{a1a,,has_dualstack_ipv6()}
convenience functions to automate the necessary tasks usually involved when
creating a server socket, including accepting both IPv4 and IPv6 connections
on the same socket.  (Contributed by Giampaolo Rodolà in bpo-17561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17561}.)

The @ref{a1b,,socket.if_nameindex()}, @ref{a1c,,socket.if_nametoindex()}, and
@ref{a1d,,socket.if_indextoname()} functions have been implemented on Windows.
(Contributed by Zackery Spytz in bpo-37007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37007}.)

@node ssl<4>,statistics<4>,socket<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 ssl}@anchor{a1e}
@subsubsection @code{ssl}


Added @ref{a1f,,post_handshake_auth} to enable and
@ref{a20,,verify_client_post_handshake()} to initiate TLS 1.3
post-handshake authentication.
(Contributed by Christian Heimes in bpo-34670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34670}.)

@node statistics<4>,sys<7>,ssl<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 statistics}@anchor{a21}
@subsubsection @code{statistics}


Added @ref{a22,,statistics.fmean()} as a faster, floating-point variant of
@ref{6bc,,statistics.mean()}.  (Contributed by Raymond Hettinger and
Steven D'Aprano in bpo-35904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35904}.)

Added @ref{a23,,statistics.geometric_mean()}
(Contributed by Raymond Hettinger in bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181}.)

Added @ref{a24,,statistics.multimode()} that returns a list of the most
common values. (Contributed by Raymond Hettinger in bpo-35892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35892}.)

Added @ref{a25,,statistics.quantiles()} that divides data or a distribution
in to equiprobable intervals (e.g. quartiles, deciles, or percentiles).
(Contributed by Raymond Hettinger in bpo-36546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36546}.)

Added @ref{a26,,statistics.NormalDist}, a tool for creating
and manipulating normal distributions of a random variable.
(Contributed by Raymond Hettinger in bpo-36018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36018}.)

@example
>>> temperature_feb = NormalDist.from_samples([4, 12, -3, 2, 7, 14])
>>> temperature_feb.mean
6.0
>>> temperature_feb.stdev
6.356099432828281

>>> temperature_feb.cdf(3)            # Chance of being under 3 degrees
0.3184678262814532
>>> # Relative chance of being 7 degrees versus 10 degrees
>>> temperature_feb.pdf(7) / temperature_feb.pdf(10)
1.2039930378537762

>>> el_niño = NormalDist(4, 2.5)
>>> temperature_feb += el_niño        # Add in a climate effect
>>> temperature_feb
NormalDist(mu=10.0, sigma=6.830080526611674)

>>> temperature_feb * (9/5) + 32      # Convert to Fahrenheit
NormalDist(mu=50.0, sigma=12.294144947901014)
>>> temperature_feb.samples(3)        # Generate random samples
[7.672102882379219, 12.000027119750287, 4.647488369766392]
@end example

@node sys<7>,tarfile<4>,statistics<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 sys}@anchor{a27}
@subsubsection sys


Add new @ref{1f4,,sys.unraisablehook()} function which can be overridden to control
how "unraisable exceptions" are handled. It is called when an exception has
occurred but there is no way for Python to handle it. For example, when a
destructor raises an exception or during garbage collection
(@ref{a28,,gc.collect()}).
(Contributed by Victor Stinner in bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}.)

@node tarfile<4>,threading<4>,sys<7>,Modules améliorés<6>
@anchor{whatsnew/3 8 tarfile}@anchor{a29}
@subsubsection tarfile


The @ref{dd,,tarfile} module now defaults to the modern pax (POSIX.1-2001)
format for new archives, instead of the previous GNU-specific one.
This improves cross-platform portability with a consistent encoding (UTF-8)
in a standardized and extensible format, and offers several other benefits.
(Contributed by C.A.M. Gerlach in bpo-36268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36268}.)

@node threading<4>,tokenize<2>,tarfile<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 threading}@anchor{a2a}
@subsubsection threading


Add a new @ref{835,,threading.excepthook()} function which handles uncaught
@ref{a2b,,threading.Thread.run()} exception. It can be overridden to control how
uncaught @ref{a2b,,threading.Thread.run()} exceptions are handled.
(Contributed by Victor Stinner in bpo-1230540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1230540}.)

Add a new @ref{a2c,,threading.get_native_id()} function and
a @ref{a2d,,native_id}
attribute to the @ref{939,,threading.Thread} class. These return the native
integral Thread ID of the current thread assigned by the kernel.
This feature is only available on certain platforms, see
@ref{a2c,,get_native_id} for more information.
(Contributed by Jake Tesler in bpo-36084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36084}.)

@node tokenize<2>,tkinter<4>,threading<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 tokenize}@anchor{a2e}
@subsubsection tokenize


The @ref{fa,,tokenize} module now implicitly emits a @code{NEWLINE} token when
provided with input that does not have a trailing new line.  This behavior
now matches what the C tokenizer does internally.
(Contributed by Ammar Askar in bpo-33899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33899}.)

@node tkinter<4>,time<4>,tokenize<2>,Modules améliorés<6>
@anchor{whatsnew/3 8 tkinter}@anchor{a2f}
@subsubsection tkinter


Added methods @code{selection_from()},
@code{selection_present()},
@code{selection_range()} and
@code{selection_to()}
in the @code{tkinter.Spinbox} class.
(Contributed by Juliette Monsel in bpo-34829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34829}.)

Added method @code{moveto()}
in the @code{tkinter.Canvas} class.
(Contributed by Juliette Monsel in bpo-23831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23831}.)

The @code{tkinter.PhotoImage} class now has
@code{transparency_get()} and
@code{transparency_set()} methods.  (Contributed by
Zackery Spytz in bpo-25451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25451}.)

@node time<4>,typing<8>,tkinter<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 time}@anchor{a30}
@subsubsection time


Added new clock @ref{a31,,CLOCK_UPTIME_RAW} for macOS 10.12.
(Contributed by Joannah Nanjekye in bpo-35702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35702}.)

@node typing<8>,unicodedata<5>,time<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 typing}@anchor{a32}
@subsubsection `typing'


The @ref{103,,typing} module incorporates several new features:


@itemize *

@item 
A dictionary type with per-key types.  See 
@geindex Python Enhancement Proposals; PEP 589
PEP 589@footnote{https://peps.python.org/pep-0589/} and
@ref{161,,typing.TypedDict}.
TypedDict uses only string keys.  By default, every key is required
to be present. Specify "total=False" to allow keys to be optional:

@example
class Location(TypedDict, total=False):
    lat_long: tuple
    grid_square: str
    xy_coordinate: tuple
@end example

@item 
Literal types.  See 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/} and @ref{83f,,typing.Literal}.
Literal types indicate that a parameter or return value
is constrained to one or more specific literal values:

@example
def get_status(port: int) -> Literal['connected', 'disconnected']:
    ...
@end example

@item 
"Final" variables, functions, methods and classes.  See 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/},
@ref{264,,typing.Final} and @ref{698,,typing.final()}.
The final qualifier instructs a static type checker to restrict
subclassing, overriding, or reassignment:

@example
pi: Final[float] = 3.1415926536
@end example

@item 
Protocol definitions.  See 
@geindex Python Enhancement Proposals; PEP 544
PEP 544@footnote{https://peps.python.org/pep-0544/}, @ref{261,,typing.Protocol} and
@ref{42c,,typing.runtime_checkable()}.  Simple ABCs like
@ref{a33,,typing.SupportsInt} are now @code{Protocol} subclasses.

@item 
New protocol class @ref{a34,,typing.SupportsIndex}.

@item 
New functions @ref{a35,,typing.get_origin()} and @ref{86a,,typing.get_args()}.
@end itemize

@node unicodedata<5>,unittest<6>,typing<8>,Modules améliorés<6>
@anchor{whatsnew/3 8 unicodedata}@anchor{a36}
@subsubsection unicodedata


The @ref{104,,unicodedata} module has been upgraded to use the Unicode 12.1.0@footnote{https://blog.unicode.org/2019/05/unicode-12-1-en.html} release.

New function @ref{a37,,is_normalized()} can be used to verify a string
is in a specific normal form, often much faster than by actually normalizing
the string.  (Contributed by Max Belanger, David Euresti, and Greg Price in
bpo-32285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32285} and bpo-37966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37966}).

@node unittest<6>,venv<4>,unicodedata<5>,Modules améliorés<6>
@anchor{whatsnew/3 8 unittest}@anchor{a38}
@subsubsection unittest


Added @ref{a39,,AsyncMock} to support an asynchronous version of
@ref{a3a,,Mock}.  Appropriate new assert functions for testing
have been added as well.
(Contributed by Lisa Roach in bpo-26467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26467}).

Added @ref{a3b,,addModuleCleanup()} and
@ref{a3c,,addClassCleanup()} to unittest to support
cleanups for @code{setUpModule()} and
@ref{a3d,,setUpClass()}.
(Contributed by Lisa Roach in bpo-24412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24412}.)

Several mock assert functions now also print a list of actual calls upon
failure. (Contributed by Petter Strandmark in bpo-35047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35047}.)

@ref{105,,unittest} module gained support for coroutines to be used as test cases
with @ref{301,,unittest.IsolatedAsyncioTestCase}.
(Contributed by Andrew Svetlov in bpo-32972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32972}.)

Exemple :

@example
import unittest


class TestRequest(unittest.IsolatedAsyncioTestCase):

    async def asyncSetUp(self):
        self.connection = await AsyncConnection()

    async def test_get(self):
        response = await self.connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)

    async def asyncTearDown(self):
        await self.connection.close()


if __name__ == "__main__":
    unittest.main()
@end example

@node venv<4>,weakref,unittest<6>,Modules améliorés<6>
@anchor{whatsnew/3 8 venv}@anchor{a3e}
@subsubsection venv


@ref{110,,venv} now includes an @code{Activate.ps1} script on all platforms for
activating virtual environments under PowerShell Core 6.1.
(Contributed by Brett Cannon in bpo-32718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32718}.)

@node weakref,xml<4>,venv<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 weakref}@anchor{a3f}
@subsubsection weakref


The proxy objects returned by @ref{a40,,weakref.proxy()} now support the matrix
multiplication operators @code{@@} and @code{@@=} in addition to the other
numeric operators. (Contributed by Mark Dickinson in bpo-36669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36669}.)

@node xml<4>,xmlrpc,weakref,Modules améliorés<6>
@anchor{whatsnew/3 8 xml}@anchor{a41}
@subsubsection `xml'


As mitigation against DTD and external entity retrieval, the
@ref{121,,xml.dom.minidom} and @ref{128,,xml.sax} modules no longer process
external entities by default.
(Contributed by Christian Heimes in bpo-17239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17239}.)

The @code{.find*()} methods in the @ref{124,,xml.etree.ElementTree} module
support wildcard searches like @code{@{*@}tag} which ignores the namespace
and @code{@{namespace@}*} which returns all tags in the given namespace.
(Contributed by Stefan Behnel in bpo-28238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28238}.)

The @ref{124,,xml.etree.ElementTree} module provides a new function
@code{–xml.etree.ElementTree.canonicalize()} that implements C14N 2.0.
(Contributed by Stefan Behnel in bpo-13611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13611}.)

The target object of @ref{a42,,xml.etree.ElementTree.XMLParser} can
receive namespace declaration events through the new callback methods
@code{start_ns()} and @code{end_ns()}.  Additionally, the
@ref{a43,,xml.etree.ElementTree.TreeBuilder} target can be configured
to process events about comments and processing instructions to include
them in the generated tree.
(Contributed by Stefan Behnel in bpo-36676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36676} and bpo-36673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36673}.)

@node xmlrpc,,xml<4>,Modules améliorés<6>
@anchor{whatsnew/3 8 xmlrpc}@anchor{a44}
@subsubsection xmlrpc


@ref{a45,,xmlrpc.client.ServerProxy} now supports an optional `headers' keyword
argument for a sequence of HTTP headers to be sent with each request.  Among
other things, this makes it possible to upgrade from default basic
authentication to faster session authentication.
(Contributed by Cédric Krier in bpo-35153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35153}.)

@node Optimizations,Build and C API Changes,Modules améliorés<6>,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 optimizations}@anchor{a46}
@subsection Optimizations



@itemize *

@item 
The @ref{d5,,subprocess} module can now use the @ref{21d,,os.posix_spawn()} function
in some cases for better performance. Currently, it is only used on macOS
and Linux (using glibc 2.24 or newer) if all these conditions are met:


@itemize *

@item 
`close_fds' is false;

@item 
`preexec_fn', `pass_fds', `cwd' and `start_new_session' parameters
are not set;

@item 
the `executable' path contains a directory.
@end itemize

(Contributed by Joannah Nanjekye and Victor Stinner in bpo-35537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35537}.)

@item 
@ref{a47,,shutil.copyfile()}, @ref{a48,,shutil.copy()}, @ref{a49,,shutil.copy2()},
@ref{a17,,shutil.copytree()} and @ref{a4a,,shutil.move()} use platform-specific
"fast-copy" syscalls on Linux and macOS in order to copy the file
more efficiently.
"fast-copy" means that the copying operation occurs within the kernel,
avoiding the use of userspace buffers in Python as in
"@code{outfd.write(infd.read())}".
On Windows @ref{a47,,shutil.copyfile()} uses a bigger default buffer size (1 MiB
instead of 16 KiB) and a @ref{452,,memoryview()}-based variant of
@ref{a4b,,shutil.copyfileobj()} is used.
The speedup for copying a 512 MiB file within the same partition is about
+26% on Linux, +50% on macOS and +40% on Windows. Also, much less CPU cycles
are consumed.
See @ref{a4c,,Platform-dependent efficient copy operations} section.
(Contributed by Giampaolo Rodolà in bpo-33671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33671}.)

@item 
@ref{a17,,shutil.copytree()} uses @ref{a4d,,os.scandir()} function and all copy
functions depending from it use cached @ref{48a,,os.stat()} values. The speedup
for copying a directory with 8000 files is around +9% on Linux, +20% on
Windows and +30% on a Windows SMB share. Also the number of @ref{48a,,os.stat()}
syscalls is reduced by 38% making @ref{a17,,shutil.copytree()} especially faster
on network filesystems. (Contributed by Giampaolo Rodolà in bpo-33695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33695}.)

@item 
The default protocol in the @ref{a5,,pickle} module is now Protocol 4,
first introduced in Python 3.4.  It offers better performance and smaller
size compared to Protocol 3 available since Python 3.0.

@item 
Removed one @ref{a4e,,Py_ssize_t} member from @code{PyGC_Head}.  All GC tracked
objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes.
(Contributed by Inada Naoki in bpo-33597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33597}.)

@item 
@ref{a4f,,uuid.UUID} now uses @code{__slots__} to reduce its memory footprint.
(Contributed by Wouter Bolsterlee and Tal Einat in bpo-30977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30977})

@item 
Improved performance of @ref{a50,,operator.itemgetter()} by 33%.  Optimized
argument handling and added a fast path for the common case of a single
non-negative integer index into a tuple (which is the typical use case in
the standard library).  (Contributed by Raymond Hettinger in
bpo-35664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35664}.)

@item 
Sped-up field lookups in @ref{1c5,,collections.namedtuple()}.  They are now more
than two times faster, making them the fastest form of instance variable
lookup in Python. (Contributed by Raymond Hettinger, Pablo Galindo, and
Joe Jevnik, Serhiy Storchaka in bpo-32492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32492}.)

@item 
The @ref{5fc,,list} constructor does not overallocate the internal item buffer
if the input iterable has a known length (the input implements @code{__len__}).
This makes the created list 12% smaller on average. (Contributed by
Raymond Hettinger and Pablo Galindo in bpo-33234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33234}.)

@item 
Doubled the speed of class variable writes.  When a non-dunder attribute
was updated, there was an unnecessary call to update slots.
(Contributed by Stefan Behnel, Pablo Galindo Salgado, Raymond Hettinger,
Neil Schemenauer, and Serhiy Storchaka in bpo-36012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36012}.)

@item 
Reduced an overhead of converting arguments passed to many builtin functions
and methods.  This sped up calling some simple builtin functions and
methods up to 20--50%.  (Contributed by Serhiy Storchaka in bpo-23867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23867},
bpo-35582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35582} and bpo-36127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36127}.)

@item 
@code{LOAD_GLOBAL} instruction now uses new "per opcode cache" mechanism.
It is about 40% faster now.  (Contributed by Yury Selivanov and Inada Naoki in
bpo-26219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26219}.)
@end itemize

@node Build and C API Changes,Obsolescence<8>,Optimizations,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 build-and-c-api-changes}@anchor{a51}
@subsection Build and C API Changes



@itemize *

@item 
Default @ref{a52,,sys.abiflags} became an empty string: the @code{m} flag for
pymalloc became useless (builds with and without pymalloc are ABI compatible)
and so has been removed. (Contributed by Victor Stinner in bpo-36707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36707}.)

Example of changes:


@itemize *

@item 
Only @code{python3.8} program is installed, @code{python3.8m} program is gone.

@item 
Only @code{python3.8-config} script is installed, @code{python3.8m-config} script
is gone.

@item 
The @code{m} flag has been removed from the suffix of dynamic library
filenames: extension modules in the standard library as well as those
produced and installed by third-party packages, like those downloaded from
PyPI. On Linux, for example, the Python 3.7 suffix
@code{.cpython-37m-x86_64-linux-gnu.so} became
@code{.cpython-38-x86_64-linux-gnu.so} in Python 3.8.
@end itemize

@item 
The header files have been reorganized to better separate the different kinds
of APIs:


@itemize *

@item 
@code{Include/*.h} should be the portable public stable C API.

@item 
@code{Include/cpython/*.h} should be the unstable C API specific to CPython;
public API, with some private API prefixed by @code{_Py} or @code{_PY}.

@item 
@code{Include/internal/*.h} is the private internal C API very specific to
CPython. This API comes with no backward compatibility warranty and should
not be used outside CPython. It is only exposed for very specific needs
like debuggers and profiles which has to access to CPython internals
without calling functions. This API is now installed by @code{make install}.
@end itemize

(Contributed by Victor Stinner in bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134} and bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081},
work initiated by Eric Snow in Python 3.7.)

@item 
Some macros have been converted to static inline functions: parameter types
and return type are well defined, they don't have issues specific to macros,
variables have a local scopes. Examples:


@itemize *

@item 
@ref{55a,,Py_INCREF()}, @ref{55b,,Py_DECREF()}

@item 
@ref{a53,,Py_XINCREF()}, @ref{779,,Py_XDECREF()}

@item 
@code{PyObject_INIT()}, @code{PyObject_INIT_VAR()}

@item 
Private functions: @code{_PyObject_GC_TRACK()},
@code{_PyObject_GC_UNTRACK()}, @code{_Py_Dealloc()}
@end itemize

(Contributed by Victor Stinner in bpo-35059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35059}.)

@item 
The @code{PyByteArray_Init()} and @code{PyByteArray_Fini()} functions have
been removed. They did nothing since Python 2.7.4 and Python 3.2.0, were
excluded from the limited API (stable ABI), and were not documented.
(Contributed by Victor Stinner in bpo-35713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35713}.)

@item 
The result of @code{PyExceptionClass_Name()} is now of type
@code{const char *} rather of @code{char *}.
(Contributed by Serhiy Storchaka in bpo-33818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33818}.)

@item 
The duality of @code{Modules/Setup.dist} and @code{Modules/Setup} has been
removed.  Previously, when updating the CPython source tree, one had
to manually copy @code{Modules/Setup.dist} (inside the source tree) to
@code{Modules/Setup} (inside the build tree) in order to reflect any changes
upstream.  This was of a small benefit to packagers at the expense of
a frequent annoyance to developers following CPython development, as
forgetting to copy the file could produce build failures.

Now the build system always reads from @code{Modules/Setup} inside the source
tree.  People who want to customize that file are encouraged to maintain
their changes in a git fork of CPython or as patch files, as they would do
for any other change to the source tree.

(Contributed by Antoine Pitrou in bpo-32430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32430}.)

@item 
Functions that convert Python number to C integer like
@ref{356,,PyLong_AsLong()} and argument parsing functions like
@ref{55d,,PyArg_ParseTuple()} with integer converting format units like @code{'i'}
will now use the @ref{707,,__index__()} special method instead of
@ref{706,,__int__()}, if available.  The deprecation warning will be
emitted for objects with the @code{__int__()} method but without the
@code{__index__()} method (like @ref{29a,,Decimal} and
@ref{1e4,,Fraction}).  @ref{a54,,PyNumber_Check()} will now return
@code{1} for objects implementing @code{__index__()}.
@ref{a55,,PyNumber_Long()}, @ref{a56,,PyNumber_Float()} and
@ref{a57,,PyFloat_AsDouble()} also now use the @code{__index__()} method if
available.
(Contributed by Serhiy Storchaka in bpo-36048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36048} and bpo-20092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20092}.)

@item 
Heap-allocated type objects will now increase their reference count
in @ref{a58,,PyObject_Init()} (and its parallel macro @code{PyObject_INIT})
instead of in @ref{a59,,PyType_GenericAlloc()}. Types that modify instance
allocation or deallocation may need to be adjusted.
(Contributed by Eddie Elizondo in bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810}.)

@item 
The new function @code{PyCode_NewWithPosOnlyArgs()} allows to create
code objects like @code{PyCode_New()}, but with an extra `posonlyargcount'
parameter for indicating the number of positional-only arguments.
(Contributed by Pablo Galindo in bpo-37221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37221}.)

@item 
@code{Py_SetPath()} now sets @ref{3af,,sys.executable} to the program full
path (@ref{3ae,,Py_GetProgramFullPath()}) rather than to the program name
(@ref{3b0,,Py_GetProgramName()}).
(Contributed by Victor Stinner in bpo-38234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38234}.)
@end itemize

@node Obsolescence<8>,API and Feature Removals,Build and C API Changes,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 deprecated}@anchor{a5a}
@subsection Obsolescence



@itemize *

@item 
The distutils @code{bdist_wininst} command is now deprecated, use
@code{bdist_wheel} (wheel packages) instead.
(Contributed by Victor Stinner in bpo-37481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37481}.)

@item 
Deprecated methods @code{getchildren()} and @code{getiterator()} in
the @ref{124,,ElementTree} module now emit a
@ref{1a3,,DeprecationWarning} instead of @ref{8b5,,PendingDeprecationWarning}.
They will be removed in Python 3.9.
(Contributed by Serhiy Storchaka in bpo-29209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29209}.)

@item 
Passing an object that is not an instance of
@ref{72c,,concurrent.futures.ThreadPoolExecutor} to
@ref{72d,,loop.set_default_executor()} is
deprecated and will be prohibited in Python 3.9.
(Contributed by Elvis Pranskevichus in bpo-34075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34075}.)

@item 
The @ref{280,,__getitem__()} methods of @ref{71f,,xml.dom.pulldom.DOMEventStream},
@ref{720,,wsgiref.util.FileWrapper} and @ref{721,,fileinput.FileInput} have been
deprecated.

Implementations of these methods have been ignoring their `index' parameter,
and returning the next item instead.
(Contributed by Berker Peksag in bpo-9372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9372}.)

@item 
The @ref{2ad,,typing.NamedTuple} class has deprecated the @code{_field_types}
attribute in favor of the @code{__annotations__} attribute which has the same
information. (Contributed by Raymond Hettinger in bpo-36320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36320}.)

@item 
@ref{8,,ast} classes @code{Num}, @code{Str}, @code{Bytes}, @code{NameConstant} and
@code{Ellipsis} are considered deprecated and will be removed in future Python
versions. @ref{2b6,,Constant} should be used instead.
(Contributed by Serhiy Storchaka in bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}.)

@item 
@ref{a5b,,ast.NodeVisitor} methods @code{visit_Num()}, @code{visit_Str()},
@code{visit_Bytes()}, @code{visit_NameConstant()} and @code{visit_Ellipsis()} are
deprecated now and will not be called in future Python versions.
Add the @ref{a5c,,visit_Constant()} method to handle all
constant nodes.
(Contributed by Serhiy Storchaka in bpo-36917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36917}.)

@item 
The @code{asyncio.coroutine()} @ref{71b,,decorator} is deprecated and will be
removed in version 3.10.  Instead of @code{@@asyncio.coroutine}, use
@ref{5bb,,async def} instead.
(Contributed by Andrew Svetlov in bpo-36921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36921}.)

@item 
In @ref{a,,asyncio}, the explicit passing of a `loop' argument has been
deprecated and will be removed in version 3.10 for the following:
@ref{a5d,,asyncio.sleep()}, @ref{5e8,,asyncio.gather()}, @ref{a5e,,asyncio.shield()},
@ref{5ea,,asyncio.wait_for()}, @ref{469,,asyncio.wait()}, @ref{1a8,,asyncio.as_completed()},
@ref{4c2,,asyncio.Task}, @ref{a5f,,asyncio.Lock}, @ref{a60,,asyncio.Event},
@ref{a61,,asyncio.Condition}, @ref{a62,,asyncio.Semaphore},
@ref{a63,,asyncio.BoundedSemaphore}, @ref{a64,,asyncio.Queue},
@ref{a65,,asyncio.create_subprocess_exec()}, and
@ref{a66,,asyncio.create_subprocess_shell()}.

@item 
The explicit passing of coroutine objects to @ref{469,,asyncio.wait()} has been
deprecated and will be removed in version 3.11.
(Contributed by Yury Selivanov in bpo-34790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34790}.)

@item 
The following functions and methods are deprecated in the @ref{62,,gettext}
module: @code{lgettext()}, @code{ldgettext()},
@code{lngettext()} and @code{ldngettext()}.
They return encoded bytes, and it's possible that you will get unexpected
Unicode-related exceptions if there are encoding problems with the
translated strings. It's much better to use alternatives which return
Unicode strings in Python 3. These functions have been broken for a long time.

Function @code{bind_textdomain_codeset()}, methods
@code{output_charset()} and
@code{set_output_charset()}, and the `codeset'
parameter of functions @ref{a67,,translation()} and
@ref{a68,,install()} are also deprecated, since they are only used for
the @code{l*gettext()} functions.
(Contributed by Serhiy Storchaka in bpo-33710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33710}.)

@item 
The @code{isAlive()} method of @ref{939,,threading.Thread}
has been deprecated.
(Contributed by Donghee Na in bpo-35283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35283}.)

@item 
Many builtin and extension functions that take integer arguments will
now emit a deprecation warning for @ref{29a,,Decimal}s,
@ref{1e4,,Fraction}s and any other objects that can be converted
to integers only with a loss (e.g. that have the @ref{706,,__int__()}
method but do not have the @ref{707,,__index__()} method).  In future
version they will be errors.
(Contributed by Serhiy Storchaka in bpo-36048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36048}.)

@item 
Deprecated passing the following arguments as keyword arguments:


@itemize -

@item 
`func' in @ref{a69,,functools.partialmethod()}, @ref{a6a,,weakref.finalize()},
@ref{a6b,,profile.Profile.runcall()}, @code{cProfile.Profile.runcall()},
@ref{a6c,,bdb.Bdb.runcall()}, @ref{a6d,,trace.Trace.runfunc()} and
@ref{a6e,,curses.wrapper()}.

@item 
`function' in @ref{a6f,,unittest.TestCase.addCleanup()}.

@item 
`fn' in the @ref{a70,,submit()} method of
@ref{72c,,concurrent.futures.ThreadPoolExecutor} and
@ref{8db,,concurrent.futures.ProcessPoolExecutor}.

@item 
`callback' in @ref{a71,,contextlib.ExitStack.callback()},
@code{contextlib.AsyncExitStack.callback()} and
@ref{a72,,contextlib.AsyncExitStack.push_async_callback()}.

@item 
`c' and `typeid' in the @code{create()}
method of @code{multiprocessing.managers.Server} and
@code{multiprocessing.managers.SharedMemoryServer}.

@item 
`obj' in @ref{a6a,,weakref.finalize()}.
@end itemize

In future releases of Python, they will be @ref{a73,,positional-only}.
(Contributed by Serhiy Storchaka in bpo-36492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36492}.)
@end itemize

@node API and Feature Removals,Porting to Python 3 8,Obsolescence<8>,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 api-and-feature-removals}@anchor{a74}
@subsection API and Feature Removals


The following features and APIs have been removed from Python 3.8:


@itemize *

@item 
Starting with Python 3.3, importing ABCs from @ref{1d,,collections} was
deprecated, and importing should be done from @ref{1e,,collections.abc}. Being
able to import from collections was marked for removal in 3.8, but has been
delayed to 3.9. (See gh-81134@footnote{https://github.com/python/cpython/issues/81134}.)

@item 
The @code{macpath} module, deprecated in Python 3.7, has been removed.
(Contributed by Victor Stinner in bpo-35471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35471}.)

@item 
The function @code{platform.popen()} has been removed, after having been
deprecated since Python 3.3: use @ref{a75,,os.popen()} instead.
(Contributed by Victor Stinner in bpo-35345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35345}.)

@item 
The function @code{time.clock()} has been removed, after having been
deprecated since Python 3.3: use @ref{a76,,time.perf_counter()} or
@ref{a77,,time.process_time()} instead, depending
on your requirements, to have well-defined behavior.
(Contributed by Matthias Bussonnier in bpo-36895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36895}.)

@item 
The @code{pyvenv} script has been removed in favor of @code{python3.8 -m venv}
to help eliminate confusion as to what Python interpreter the @code{pyvenv}
script is tied to. (Contributed by Brett Cannon in bpo-25427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25427}.)

@item 
@code{parse_qs}, @code{parse_qsl}, and @code{escape} are removed from the @code{cgi}
module.  They are deprecated in Python 3.2 or older. They should be imported
from the @code{urllib.parse} and @code{html} modules instead.

@item 
@code{filemode} function is removed from the @ref{dd,,tarfile} module.
It is not documented and deprecated since Python 3.3.

@item 
The @ref{a42,,XMLParser} constructor no longer accepts
the `html' argument.  It never had an effect and was deprecated in Python 3.4.
All other parameters are now @ref{2a2,,keyword-only}.
(Contributed by Serhiy Storchaka in bpo-29209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29209}.)

@item 
Removed the @code{doctype()} method of @ref{a42,,XMLParser}.
(Contributed by Serhiy Storchaka in bpo-29209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29209}.)

@item 
"unicode_internal" codec is removed.
(Contributed by Inada Naoki in bpo-36297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36297}.)

@item 
The @code{Cache} and @code{Statement} objects of the @ref{ce,,sqlite3} module are not
exposed to the user.
(Contributed by Aviv Palivoda in bpo-30262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30262}.)

@item 
The @code{bufsize} keyword argument of @ref{7e9,,fileinput.input()} and
@ref{721,,fileinput.FileInput()} which was ignored and deprecated since Python 3.6
has been removed. bpo-36952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36952} (Contributed by Matthias Bussonnier.)

@item 
The functions @code{sys.set_coroutine_wrapper()} and
@code{sys.get_coroutine_wrapper()} deprecated in Python 3.7 have been removed;
bpo-36933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36933} (Contributed by Matthias Bussonnier.)
@end itemize

@node Porting to Python 3 8,Notable changes in Python 3 8 1,API and Feature Removals,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 porting-to-python-3-8}@anchor{a78}
@subsection Porting to Python 3.8


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changes in Python behavior:: 
* Changements dans l'API Python: Changements dans l'API Python<5>. 
* Changements dans l'API C: Changements dans l'API C<4>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<5>. 
* Demos and Tools: Demos and Tools<2>. 

@end menu

@node Changes in Python behavior,Changements dans l'API Python<5>,,Porting to Python 3 8
@anchor{whatsnew/3 8 changes-in-python-behavior}@anchor{a79}
@subsubsection Changes in Python behavior



@itemize *

@item 
Yield expressions (both @code{yield} and @code{yield from} clauses) are now disallowed
in comprehensions and generator expressions (aside from the iterable expression
in the leftmost @code{for} clause).
(Contributed by Serhiy Storchaka in bpo-10544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10544}.)

@item 
The compiler now produces a @ref{44f,,SyntaxWarning} when identity checks
(@code{is} and @code{is not}) are used with certain types of literals
(e.g. strings, numbers).  These can often work by accident in CPython,
but are not guaranteed by the language spec.  The warning advises users
to use equality tests (@code{==} and @code{!=}) instead.
(Contributed by Serhiy Storchaka in bpo-34850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34850}.)

@item 
The CPython interpreter can swallow exceptions in some circumstances.
In Python 3.8 this happens in fewer cases.  In particular, exceptions
raised when getting the attribute from the type dictionary are no longer
ignored. (Contributed by Serhiy Storchaka in bpo-35459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35459}.)

@item 
Removed @code{__str__} implementations from builtin types @ref{451,,bool},
@ref{254,,int}, @ref{2eb,,float}, @ref{2ec,,complex} and few classes from
the standard library.  They now inherit @code{__str__()} from @ref{a7a,,object}.
As result, defining the @code{__repr__()} method in the subclass of these
classes will affect their string representation.
(Contributed by Serhiy Storchaka in bpo-36793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36793}.)

@item 
On AIX, @ref{a7b,,sys.platform} doesn't contain the major version anymore.
It is always @code{'aix'}, instead of @code{'aix3'} .. @code{'aix7'}.  Since
older Python versions include the version number, so it is recommended to
always use @code{sys.platform.startswith('aix')}.
(Contributed by M. Felt in bpo-36588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36588}.)

@item 
@code{PyEval_AcquireLock()} and @code{PyEval_AcquireThread()} now
terminate the current thread if called while the interpreter is
finalizing, making them consistent with @ref{3a0,,PyEval_RestoreThread()},
@ref{a7c,,Py_END_ALLOW_THREADS()}, and @ref{3a2,,PyGILState_Ensure()}. If this
behavior is not desired, guard the call by checking @code{_Py_IsFinalizing()}
or @ref{a7d,,sys.is_finalizing()}.
(Contributed by Joannah Nanjekye in bpo-36475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36475}.)
@end itemize

@node Changements dans l'API Python<5>,Changements dans l'API C<4>,Changes in Python behavior,Porting to Python 3 8
@anchor{whatsnew/3 8 changes-in-the-python-api}@anchor{a7e}
@subsubsection Changements dans l'API Python



@itemize *

@item 
The @ref{a7f,,os.getcwdb()} function now uses the UTF-8 encoding on Windows,
rather than the ANSI code page: see 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for the rationale. The
function is no longer deprecated on Windows.
(Contributed by Victor Stinner in bpo-37412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37412}.)

@item 
@ref{197,,subprocess.Popen} can now use @ref{21d,,os.posix_spawn()} in some cases
for better performance. On Windows Subsystem for Linux and QEMU User
Emulation, the @code{Popen} constructor using @ref{21d,,os.posix_spawn()} no longer raises an
exception on errors like "missing program".  Instead the child process fails with a
non-zero @code{returncode}.
(Contributed by Joannah Nanjekye and Victor Stinner in bpo-35537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35537}.)

@item 
The `preexec_fn' argument of * @ref{197,,subprocess.Popen} is no longer
compatible with subinterpreters. The use of the parameter in a
subinterpreter now raises @ref{193,,RuntimeError}.
(Contributed by Eric Snow in bpo-34651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34651}, modified by Christian Heimes
in bpo-37951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37951}.)

@item 
The @code{imap.IMAP4.logout()} method no longer silently ignores arbitrary
exceptions.
(Contributed by Victor Stinner in bpo-36348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36348}.)

@item 
The function @code{platform.popen()} has been removed, after having been deprecated since
Python 3.3: use @ref{a75,,os.popen()} instead.
(Contributed by Victor Stinner in bpo-35345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35345}.)

@item 
The @ref{a80,,statistics.mode()} function no longer raises an exception
when given multimodal data.  Instead, it returns the first mode
encountered in the input data.  (Contributed by Raymond Hettinger
in bpo-35892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35892}.)

@item 
The @ref{a81,,selection()} method of the
@ref{a82,,tkinter.ttk.Treeview} class no longer takes arguments.  Using it with
arguments for changing the selection was deprecated in Python 3.6.  Use
specialized methods like @ref{a83,,selection_set()} for
changing the selection.  (Contributed by Serhiy Storchaka in bpo-31508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31508}.)

@item 
The @code{writexml()}, @code{toxml()} and @code{toprettyxml()} methods of
@ref{121,,xml.dom.minidom}, and the @code{write()} method of @code{xml.etree},
now preserve the attribute order specified by the user.
(Contributed by Diego Rojas and Raymond Hettinger in bpo-34160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34160}.)

@item 
A @ref{32,,dbm.dumb} database opened with flags @code{'r'} is now read-only.
@ref{a84,,dbm.dumb.open()} with flags @code{'r'} and @code{'w'} no longer creates
a database if it does not exist.
(Contributed by Serhiy Storchaka in bpo-32749@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32749}.)

@item 
The @code{doctype()} method defined in a subclass of
@ref{a42,,XMLParser} will no longer be called and will
emit a @ref{1bb,,RuntimeWarning} instead of a @ref{1a3,,DeprecationWarning}.
Define the @ref{a85,,doctype()}
method on a target for handling an XML doctype declaration.
(Contributed by Serhiy Storchaka in bpo-29209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29209}.)

@item 
A @ref{193,,RuntimeError} is now raised when the custom metaclass doesn't
provide the @code{__classcell__} entry in the namespace passed to
@code{type.__new__}.  A @ref{1a3,,DeprecationWarning} was emitted in Python
3.6--3.7.  (Contributed by Serhiy Storchaka in bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}.)

@item 
The @code{cProfile.Profile} class can now be used as a context
manager. (Contributed by Scott Sanderson in bpo-29235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29235}.)

@item 
@ref{a47,,shutil.copyfile()}, @ref{a48,,shutil.copy()}, @ref{a49,,shutil.copy2()},
@ref{a17,,shutil.copytree()} and @ref{a4a,,shutil.move()} use platform-specific
"fast-copy" syscalls (see
@ref{a4c,,Platform-dependent efficient copy operations} section).

@item 
@ref{a47,,shutil.copyfile()} default buffer size on Windows was changed from
16 KiB to 1 MiB.

@item 
The @code{PyGC_Head} struct has changed completely.  All code that touched the
struct member should be rewritten.  (See bpo-33597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33597}.)

@item 
The @ref{8aa,,PyInterpreterState} struct has been moved into the "internal"
header files (specifically Include/internal/pycore_pystate.h).  An
opaque @code{PyInterpreterState} is still available as part of the public
API (and stable ABI).  The docs indicate that none of the struct's
fields are public, so we hope no one has been using them.  However,
if you do rely on one or more of those private fields and have no
alternative then please open a BPO issue.  We'll work on helping
you adjust (possibly including adding accessor functions to the
public API).  (See bpo-35886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35886}.)

@item 
The @ref{a86,,mmap.flush()} method now returns @code{None} on
success and raises an exception on error under all platforms.  Previously,
its behavior was platform-dependent: a nonzero value was returned on success;
zero was returned on error under Windows.  A zero value was returned on
success; an exception was raised on error under Unix.
(Contributed by Berker Peksag in bpo-2122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2122}.)

@item 
@ref{121,,xml.dom.minidom} and @ref{128,,xml.sax} modules no longer process
external entities by default.
(Contributed by Christian Heimes in bpo-17239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17239}.)

@item 
Deleting a key from a read-only @ref{31,,dbm} database (@ref{32,,dbm.dumb},
@ref{33,,dbm.gnu} or @ref{34,,dbm.ndbm}) raises @code{error} (@ref{a87,,dbm.dumb.error},
@ref{a88,,dbm.gnu.error} or @ref{a89,,dbm.ndbm.error}) instead of @ref{33a,,KeyError}.
(Contributed by Xiang Zhang in bpo-33106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33106}.)

@item 
Simplified AST for literals.  All constants will be represented as
@ref{2b6,,ast.Constant} instances.  Instantiating old classes @code{Num},
@code{Str}, @code{Bytes}, @code{NameConstant} and @code{Ellipsis} will return
an instance of @code{Constant}.
(Contributed by Serhiy Storchaka in bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}.)

@item 
@ref{a02,,expanduser()} on Windows now prefers the 
@geindex USERPROFILE
@geindex variable d'environnement; USERPROFILE
@code{USERPROFILE}
environment variable and does not use 
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME}, which is not normally
set for regular user accounts.
(Contributed by Anthony Sottile in bpo-36264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36264}.)

@item 
The exception @ref{1b6,,asyncio.CancelledError} now inherits from
@ref{5a5,,BaseException} rather than @ref{9c7,,Exception} and no longer inherits
from @ref{9c8,,concurrent.futures.CancelledError}.
(Contributed by Yury Selivanov in bpo-32528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32528}.)

@item 
The function @ref{5ea,,asyncio.wait_for()} now correctly waits for cancellation
when using an instance of @ref{4c2,,asyncio.Task}. Previously, upon reaching
`timeout', it was cancelled and immediately returned.
(Contributed by Elvis Pranskevichus in bpo-32751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32751}.)

@item 
The function @ref{a8a,,asyncio.BaseTransport.get_extra_info()} now returns a safe
to use socket object when 'socket' is passed to the `name' parameter.
(Contributed by Yury Selivanov in bpo-37027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37027}.)

@item 
@ref{a8b,,asyncio.BufferedProtocol} has graduated to the stable API.
@end itemize
@anchor{whatsnew/3 8 bpo-36085-whatsnew}@anchor{a8c}

@itemize *

@item 
DLL dependencies for extension modules and DLLs loaded with @ref{2a,,ctypes} on
Windows are now resolved more securely. Only the system paths, the directory
containing the DLL or PYD file, and directories added with
@ref{9d8,,add_dll_directory()} are searched for load-time dependencies.
Specifically, 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} and the current working directory are no longer
used, and modifications to these will no longer have any effect on normal DLL
resolution. If your application relies on these mechanisms, you should check
for @ref{9d8,,add_dll_directory()} and if it exists, use it to add your DLLs
directory while loading your library. Note that Windows 7 users will need to
ensure that Windows Update KB2533623 has been installed (this is also verified
by the installer).
(Contributed by Steve Dower in bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}.)

@item 
The header files and functions related to pgen have been removed after its
replacement by a pure Python implementation. (Contributed by Pablo Galindo
in bpo-36623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36623}.)

@item 
@ref{2dd,,types.CodeType} has a new parameter in the second position of the
constructor (`posonlyargcount') to support positional-only arguments defined
in 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/}. The first argument (`argcount') now represents the total
number of positional arguments (including positional-only arguments). The new
@code{replace()} method of @ref{2dd,,types.CodeType} can be used to make the code
future-proof.

@item 
The parameter @code{digestmod} for @ref{a8d,,hmac.new()} no longer uses the MD5 digest
by default.
@end itemize

@node Changements dans l'API C<4>,Changements au code intermédiaire CPython<5>,Changements dans l'API Python<5>,Porting to Python 3 8
@anchor{whatsnew/3 8 changes-in-the-c-api}@anchor{a8e}
@subsubsection Changements dans l'API C



@itemize *

@item 
The @ref{a8f,,PyCompilerFlags} structure got a new `cf_feature_version'
field. It should be initialized to @code{PY_MINOR_VERSION}. The field is ignored
by default, and is used if and only if @code{PyCF_ONLY_AST} flag is set in
`cf_flags'.
(Contributed by Guido van Rossum in bpo-35766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35766}.)

@item 
The @code{PyEval_ReInitThreads()} function has been removed from the C API.
It should not be called explicitly: use @ref{3f1,,PyOS_AfterFork_Child()}
instead.
(Contributed by Victor Stinner in bpo-36728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36728}.)

@item 
On Unix, C extensions are no longer linked to libpython except on Android
and Cygwin. When Python is embedded, @code{libpython} must not be loaded with
@code{RTLD_LOCAL}, but @code{RTLD_GLOBAL} instead. Previously, using
@code{RTLD_LOCAL}, it was already not possible to load C extensions which
were not linked to @code{libpython}, like C extensions of the standard
library built by the @code{*shared*} section of @code{Modules/Setup}.
(Contributed by Victor Stinner in bpo-21536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21536}.)

@item 
Use of @code{#} variants of formats in parsing or building value (e.g.
@ref{55d,,PyArg_ParseTuple()}, @ref{894,,Py_BuildValue()}, @ref{395,,PyObject_CallFunction()},
etc.) without @code{PY_SSIZE_T_CLEAN} defined raises @code{DeprecationWarning} now.
It will be removed in 3.10 or 4.0.  Read @ref{895,,Analyse des arguments et construction des valeurs} for detail.
(Contributed by Inada Naoki in bpo-36381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36381}.)

@item 
Instances of heap-allocated types (such as those created with
@ref{569,,PyType_FromSpec()}) hold a reference to their type object.
Increasing the reference count of these type objects has been moved from
@ref{a59,,PyType_GenericAlloc()} to the more low-level functions,
@ref{a58,,PyObject_Init()} and @code{PyObject_INIT()}.
This makes types created through @ref{569,,PyType_FromSpec()} behave like
other classes in managed code.

@ref{769,,Statically allocated types} are not affected.

For the vast majority of cases, there should be no side effect.
However, types that manually increase the reference count after allocating
an instance (perhaps to work around the bug) may now become immortal.
To avoid this, these classes need to call Py_DECREF on the type object
during instance deallocation.

To correctly port these types into 3.8, please apply the following
changes:


@itemize *

@item 
Remove @ref{55a,,Py_INCREF} on the type object after allocating an
instance - if any.
This may happen after calling @ref{972,,PyObject_New},
@ref{973,,PyObject_NewVar}, @ref{a90,,PyObject_GC_New()},
@ref{a91,,PyObject_GC_NewVar()}, or any other custom allocator that uses
@ref{a58,,PyObject_Init()} or @code{PyObject_INIT()}.

Exemple :

@example
static foo_struct *
foo_new(PyObject *type) @{
    foo_struct *foo = PyObject_GC_New(foo_struct, (PyTypeObject *) type);
    if (foo == NULL)
        return NULL;
#if PY_VERSION_HEX < 0x03080000
    // Workaround for Python issue 35810; no longer necessary in Python 3.8
    PY_INCREF(type)
#endif
    return foo;
@}
@end example

@item 
Ensure that all custom @code{tp_dealloc} functions of heap-allocated types
decrease the type's reference count.

Exemple :

@example
static void
foo_dealloc(foo_struct *instance) @{
    PyObject *type = Py_TYPE(instance);
    PyObject_GC_Del(instance);
#if PY_VERSION_HEX >= 0x03080000
    // This was not needed before Python 3.8 (Python issue 35810)
    Py_DECREF(type);
#endif
@}
@end example
@end itemize

(Contributed by Eddie Elizondo in bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810}.)

@item 
The @ref{a92,,Py_DEPRECATED()} macro has been implemented for MSVC.
The macro now must be placed before the symbol name.

Exemple :

@example
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
@end example

(Contributed by Zackery Spytz in bpo-33407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33407}.)

@item 
The interpreter does not pretend to support binary compatibility of
extension types across feature releases, anymore.  A @ref{a93,,PyTypeObject}
exported by a third-party extension module is supposed to have all the
slots expected in the current Python version, including
@ref{a94,,tp_finalize} (@ref{3e8,,Py_TPFLAGS_HAVE_FINALIZE}
is not checked anymore before reading @ref{a94,,tp_finalize}).

(Contributed by Antoine Pitrou in bpo-32388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32388}.)

@item 
The functions @code{PyNode_AddChild()} and @code{PyParser_AddToken()} now accept
two additional @code{int} arguments `end_lineno' and `end_col_offset'.

@item 
The @code{libpython38.a} file to allow MinGW tools to link directly against
@code{python38.dll} is no longer included in the regular Windows distribution.
If you require this file, it may be generated with the @code{gendef} and
@code{dlltool} tools, which are part of the MinGW binutils package:

@example
gendef - python38.dll > tmp.def
dlltool --dllname python38.dll --def tmp.def --output-lib libpython38.a
@end example

The location of an installed @code{pythonXY.dll} will depend on the
installation options and the version and language of Windows. See
@ref{a95,,Utilisation de Python sur Windows} for more information. The resulting library should be
placed in the same directory as @code{pythonXY.lib}, which is generally the
@code{libs} directory under your Python installation.

(Contributed by Steve Dower in bpo-37351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37351}.)
@end itemize

@node Changements au code intermédiaire CPython<5>,Demos and Tools<2>,Changements dans l'API C<4>,Porting to Python 3 8
@anchor{whatsnew/3 8 cpython-bytecode-changes}@anchor{a96}
@subsubsection Changements au code intermédiaire CPython



@itemize *

@item 
The interpreter loop  has been simplified by moving the logic of unrolling
the stack of blocks into the compiler.  The compiler emits now explicit
instructions for adjusting the stack of values and calling the
cleaning-up code for @ref{a97,,break}, @ref{9b7,,continue} and
@ref{9bc,,return}.

Removed opcodes @code{BREAK_LOOP}, @code{CONTINUE_LOOP},
@code{SETUP_LOOP} and @code{SETUP_EXCEPT}.  Added new opcodes
@code{ROT_FOUR}, @code{BEGIN_FINALLY}, @code{CALL_FINALLY} and
@code{POP_FINALLY}.  Changed the behavior of @code{END_FINALLY}
and @code{WITH_CLEANUP_START}.

(Contributed by Mark Shannon, Antoine Pitrou and Serhiy Storchaka in
bpo-17611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17611}.)

@item 
Added new opcode @ref{a98,,END_ASYNC_FOR} for handling exceptions raised
when awaiting a next item in an @ref{a99,,async for} loop.
(Contributed by Serhiy Storchaka in bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}.)

@item 
The @ref{a9a,,MAP_ADD} now expects the value as the first element in the
stack and the key as the second element. This change was made so the key
is always evaluated before the value in dictionary comprehensions, as
proposed by 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}. (Contributed by Jörn Heissler in bpo-35224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35224}.)
@end itemize

@node Demos and Tools<2>,,Changements au code intermédiaire CPython<5>,Porting to Python 3 8
@anchor{whatsnew/3 8 demos-and-tools}@anchor{a9b}
@subsubsection Demos and Tools


Added a benchmark script for timing various ways to access variables:
@code{Tools/scripts/var_access_benchmark.py}.
(Contributed by Raymond Hettinger in bpo-35884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35884}.)

Here's a summary of performance improvements since Python 3.3:

@example
Python version                       3.3     3.4     3.5     3.6     3.7     3.8
--------------                       ---     ---     ---     ---     ---     ---

Variable and attribute read access:
    read_local                       4.0     7.1     7.1     5.4     5.1     3.9
    read_nonlocal                    5.3     7.1     8.1     5.8     5.4     4.4
    read_global                     13.3    15.5    19.0    14.3    13.6     7.6
    read_builtin                    20.0    21.1    21.6    18.5    19.0     7.5
    read_classvar_from_class        20.5    25.6    26.5    20.7    19.5    18.4
    read_classvar_from_instance     18.5    22.8    23.5    18.8    17.1    16.4
    read_instancevar                26.8    32.4    33.1    28.0    26.3    25.4
    read_instancevar_slots          23.7    27.8    31.3    20.8    20.8    20.2
    read_namedtuple                 68.5    73.8    57.5    45.0    46.8    18.4
    read_boundmethod                29.8    37.6    37.9    29.6    26.9    27.7

Variable and attribute write access:
    write_local                      4.6     8.7     9.3     5.5     5.3     4.3
    write_nonlocal                   7.3    10.5    11.1     5.6     5.5     4.7
    write_global                    15.9    19.7    21.2    18.0    18.0    15.8
    write_classvar                  81.9    92.9    96.0   104.6   102.1    39.2
    write_instancevar               36.4    44.6    45.8    40.0    38.9    35.5
    write_instancevar_slots         28.7    35.6    36.1    27.3    26.6    25.7

Data structure read access:
    read_list                       19.2    24.2    24.5    20.8    20.8    19.0
    read_deque                      19.9    24.7    25.5    20.2    20.6    19.8
    read_dict                       19.7    24.3    25.7    22.3    23.0    21.0
    read_strdict                    17.9    22.6    24.3    19.5    21.2    18.9

Data structure write access:
    write_list                      21.2    27.1    28.5    22.5    21.6    20.0
    write_deque                     23.8    28.7    30.1    22.7    21.8    23.5
    write_dict                      25.9    31.4    33.3    29.3    29.2    24.7
    write_strdict                   22.9    28.4    29.9    27.5    25.2    23.1

Stack (or queue) operations:
    list_append_pop                144.2    93.4   112.7    75.4    74.2    50.8
    deque_append_pop                30.4    43.5    57.0    49.4    49.2    42.5
    deque_append_popleft            30.8    43.7    57.3    49.7    49.7    42.8

Timing loop:
    loop_overhead                    0.3     0.5     0.6     0.4     0.3     0.3
@end example

The benchmarks were measured on an
Intel® Core™ i7-4960HQ processor@footnote{https://ark.intel.com/content/www/us/en/ark/products/76088/intel-core-i7-4960hq-processor-6m-cache-up-to-3-80-ghz.html}
running the macOS 64-bit builds found at
python.org@footnote{https://www.python.org/downloads/macos/}.
The benchmark script displays timings in nanoseconds.

@node Notable changes in Python 3 8 1,Notable changes in Python 3 8 2,Porting to Python 3 8,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-1}@anchor{a9c}
@subsection Notable changes in Python 3.8.1


En raison de problèmes de sécurité importants, le paramètre `reuse_address' de @ref{71d,,asyncio.loop.create_datagram_endpoint()} n'est plus supporté. C'est à cause du comportement de l'option socket @code{SO_REUSEADDR} en UDP. Pour plus de détails, voir la documentation de @code{loop.create_datagram_endpoint()}. (Contribué par Kyle Stanley, Antoine Pitrou, et Yury Selivanov dans bpo-37228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37228}.)

@node Notable changes in Python 3 8 2,Notable changes in Python 3 8 3,Notable changes in Python 3 8 1,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-2}@anchor{a9d}
@subsection Notable changes in Python 3.8.2


Fixed a regression with the @code{ignore} callback of @ref{a17,,shutil.copytree()}.
The argument types are now str and List[str] again.
(Contributed by Manuel Barkhau and Giampaolo Rodola in gh-83571@footnote{https://github.com/python/cpython/issues/83571}.)

@node Notable changes in Python 3 8 3,Notable changes in Python 3 8 8,Notable changes in Python 3 8 2,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-3}@anchor{a9e}
@subsection Notable changes in Python 3.8.3


The constant values of future flags in the @ref{0,,__future__} module
are updated in order to prevent collision with compiler flags. Previously
@code{PyCF_ALLOW_TOP_LEVEL_AWAIT} was clashing with @code{CO_FUTURE_DIVISION}.
(Contributed by Batuhan Taskaya in gh-83743@footnote{https://github.com/python/cpython/issues/83743})

@node Notable changes in Python 3 8 8,Notable changes in Python 3 8 9,Notable changes in Python 3 8 3,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-8}@anchor{a9f}
@subsection Notable changes in Python 3.8.8


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{277,,urllib.parse.parse_qs()} and
@ref{276,,urllib.parse.parse_qsl()}.  Due to security concerns, and to conform with
newer W3C recommendations, this has been changed to allow only a single
separator key, with @code{&} as the default.  This change also affects
@code{cgi.parse()} and @code{cgi.parse_multipart()} as they use the affected
functions internally. For more details, please see their respective
documentation.
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}.)

@node Notable changes in Python 3 8 9,Notable changes in Python 3 8 10,Notable changes in Python 3 8 8,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-9}@anchor{aa0}
@subsection Notable changes in Python 3.8.9


A security fix alters the @ref{8e7,,ftplib.FTP} behavior to not trust the
IPv4 address sent from the remote server when setting up a passive data
channel.  We reuse the ftp server IP address instead.  For unusual code
requiring the old behavior, set a @code{trust_server_pasv_ipv4_address}
attribute on your FTP instance to @code{True}.  (See gh-87451@footnote{https://github.com/python/cpython/issues/87451})

@node Notable changes in Python 3 8 10,Notable changes in Python 3 8 10<2>,Notable changes in Python 3 8 9,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-10}@anchor{aa1}
@subsection Notable changes in Python 3.8.10


@menu
* Prise en charge de macOS 11.0 (Big Sur) et de Mac sur processeur Apple: Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple<2>. 

@end menu

@node Prise en charge de macOS 11 0 Big Sur et de Mac sur processeur Apple<2>,,,Notable changes in Python 3 8 10
@anchor{whatsnew/3 8 macos-11-0-big-sur-and-apple-silicon-mac-support}@anchor{aa2}
@subsubsection Prise en charge de `macOS' 11.0 (Big Sur) et de Mac sur processeur Apple


As of 3.8.10, Python now supports building and running on macOS 11
(Big Sur) and on Apple Silicon Macs (based on the @code{ARM64} architecture).
A new universal build variant, @code{universal2}, is now available to natively
support both @code{ARM64} and @code{Intel 64} in one set of executables.
Note that support for "weaklinking", building binaries targeted for newer
versions of macOS that will also run correctly on older versions by
testing at runtime for missing features, is not included in this backport
from Python 3.9; to support a range of macOS versions, continue to target
for and build on the oldest version in the range.

(Originally contributed by Ronald Oussoren and Lawrence D'Anna in gh-85272@footnote{https://github.com/python/cpython/issues/85272},
with fixes by FX Coudert and Eli Rykoff, and backported to 3.8 by Maxime Bélanger
and Ned Deily)

@node Notable changes in Python 3 8 10<2>,Notable changes in Python 3 8 12,Notable changes in Python 3 8 10,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 id1}@anchor{aa3}
@subsection Notable changes in Python 3.8.10


@menu
* urllib.parse: urllib parse<4>. 

@end menu

@node urllib parse<4>,,,Notable changes in Python 3 8 10<2>
@anchor{whatsnew/3 8 urllib-parse}@anchor{aa4}
@subsubsection `urllib.parse'


La présence de caractères de saut de ligne ou de tabulation dans une URL permet certaines formes d'attaques. En conformité avec la spécification du `WHATWG' qui met à jour la 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}, les caractères `ASCII' de saut de ligne @code{\n}, @code{\r} et de tabulation @code{\t} sont retirés des URL par l'analyseur dans @ref{109,,urllib.parse} pour contrer ces attaques. Le jeu de caractères à retirer est contrôlé par une nouvelle variable de module @code{urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE} (voir bpo-43882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43882}).

@node Notable changes in Python 3 8 12,Notable security feature in 3 8 14,Notable changes in Python 3 8 10<2>,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-python-3-8-12}@anchor{aa5}
@subsection Notable changes in Python 3.8.12


@menu
* Changements dans l'API Python: Changements dans l'API Python<6>. 

@end menu

@node Changements dans l'API Python<6>,,,Notable changes in Python 3 8 12
@anchor{whatsnew/3 8 id2}@anchor{aa6}
@subsubsection Changements dans l'API Python


Starting with Python 3.8.12 the @ref{7f,,ipaddress} module no longer accepts
any leading zeros in IPv4 address strings. Leading zeros are ambiguous and
interpreted as octal notation by some libraries. For example the legacy
function @ref{94e,,socket.inet_aton()} treats leading zeros as octal notation.
glibc implementation of modern @ref{94f,,inet_pton()} does not accept
any leading zeros.

(Originally contributed by Christian Heimes in bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}, and backported
to 3.8 by Achraf Merzouki.)

@node Notable security feature in 3 8 14,Notable changes in 3 8 17,Notable changes in Python 3 8 12,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-security-feature-in-3-8-14}@anchor{aa7}
@subsection Notable security feature in 3.8.14


Converting between @ref{254,,int} and @ref{435,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{1ff,,ValueError} if the number of digits in string form is
above a limit to avoid potential denial of service attacks due to the
algorithmic complexity. This is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.
This limit can be configured or disabled by environment variable, command
line flag, or @ref{d8,,sys} APIs. See the @ref{5df,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node Notable changes in 3 8 17,,Notable security feature in 3 8 14,Nouveautés de Python 3 8
@anchor{whatsnew/3 8 notable-changes-in-3-8-17}@anchor{aa8}
@subsection Notable changes in 3.8.17


@menu
* tarfile: tarfile<5>. 

@end menu

@node tarfile<5>,,,Notable changes in 3 8 17
@anchor{whatsnew/3 8 id3}@anchor{aa9}
@subsubsection tarfile



@itemize *

@item 
The extraction methods in @ref{dd,,tarfile}, and @ref{455,,shutil.unpack_archive()},
have a new a `filter' argument that allows limiting tar features than may be
surprising or dangerous, such as creating files outside the destination
directory.
See @ref{456,,Extraction filters} for details.
In Python 3.12, use without the `filter' argument will show a
@ref{1a3,,DeprecationWarning}.
In Python 3.14, the default will switch to @code{'data'}.
(Contributed by Petr Viktorin in 
@geindex Python Enhancement Proposals; PEP 706
PEP 706@footnote{https://peps.python.org/pep-0706/}.)
@end itemize

@node What's New In Python 3 7,What's New In Python 3 6,Nouveautés de Python 3 8,Nouveautés de Python
@anchor{whatsnew/3 7 doc}@anchor{aaa}@anchor{whatsnew/3 7 what-s-new-in-python-3-7}@anchor{aab}
@section What's New In Python 3.7


@*Rédacteur: 
Elvis Pranskevichus <@email{elvis@@magic.io}>


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Git log
@c when researching a change.

This article explains the new features in Python 3.7, compared to 3.6.
Python 3.7 was released on June 27, 2018.
For full details, see the @ref{13b,,changelog}.

@menu
* Summary: Summary -- Release Highlights<2>. Release Highlights
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<12>. 
* Autres changements au langage: Autres changements au langage<7>. 
* Nouveaux modules: Nouveaux modules<7>. 
* Modules améliorés: Modules améliorés<7>. 
* Changements à l'API C: Changements à l'API C<6>. 
* Changements à la compilation: Changements à la compilation<6>. 
* Optimizations: Optimizations<2>. 
* Autres changements à l'implémentation de CPython: Autres changements à l'implémentation de CPython<2>. 
* Deprecated Python Behavior:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods. 
* Deprecated functions and types of the C API:: 
* Platform Support Removals:: 
* API and Feature Removals: API and Feature Removals<2>. 
* Module Removals:: 
* Windows-only Changes:: 
* Porting to Python 3.7: Porting to Python 3 7. 
* Notable changes in Python 3.7.1: Notable changes in Python 3 7 1. 
* Notable changes in Python 3.7.2: Notable changes in Python 3 7 2. 
* Notable changes in Python 3.7.6: Notable changes in Python 3 7 6. 
* Notable changes in Python 3.7.10: Notable changes in Python 3 7 10. 
* Notable changes in Python 3.7.11: Notable changes in Python 3 7 11. 
* Notable security feature in 3.7.14: Notable security feature in 3 7 14. 

@end menu

@node Summary -- Release Highlights<2>,Nouvelles fonctionnalités<12>,,What's New In Python 3 7
@anchor{whatsnew/3 7 summary-release-highlights}@anchor{aac}
@subsection Summary -- Release Highlights


@c This section singles out the most important changes in Python 3.7.
@c Brevity is key.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@ref{aad,,PEP 563}, postponed evaluation of type annotations.
@end itemize

Backwards incompatible syntax changes:


@itemize *

@item 
@ref{71c,,async} and @ref{1b7,,await} are now reserved keywords.
@end itemize

Nouveaux modules de la bibliothèque :


@itemize *

@item 
@ref{24,,contextvars}: @ref{aae,,PEP 567 -- Context Variables}

@item 
@ref{2f,,dataclasses}: @ref{aaf,,PEP 557 -- Data Classes}

@item 
@ref{ab0,,importlib.resources}
@end itemize

Nouvelles fonctionnalités natives :


@itemize *

@item 
@ref{ab1,,PEP 553}, the new @ref{231,,breakpoint()} function.
@end itemize

Python data model improvements:


@itemize *

@item 
@ref{ab2,,PEP 562}, customization of access to
module attributes.

@item 
@ref{ab3,,PEP 560}, core support for typing module and
generic types.

@item 
the insertion-order preservation nature of @ref{ab4,,dict}
objects has been declared@footnote{https://mail.python.org/pipermail/python-dev/2017-December/151283.html} to be an official
part of the Python language spec.
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
The @ref{a,,asyncio} module has received new features, significant
@ref{ab5,,usability and performance improvements}.

@item 
The @ref{ed,,time} module gained support for
@ref{ab6,,functions with nanosecond resolution}.
@end itemize

CPython implementation improvements:


@itemize *

@item 
Avoiding the use of ASCII as a default text encoding:


@itemize *

@item 
@ref{ab7,,PEP 538}, legacy C locale coercion

@item 
@ref{ab8,,PEP 540}, forced UTF-8 runtime mode
@end itemize

@item 
@ref{ab9,,PEP 552}, deterministic .pycs

@item 
@ref{aba,,New Python Development Mode}

@item 
@ref{abb,,PEP 565}, improved @ref{1a3,,DeprecationWarning}
handling
@end itemize

C API improvements:


@itemize *

@item 
@ref{abc,,PEP 539}, new C API for thread-local storage
@end itemize

Documentation improvements:


@itemize *

@item 
@ref{abd,,PEP 545}, Python documentation translations

@item 
New documentation translations: Japanese@footnote{https://docs.python.org/ja/},
French@footnote{https://docs.python.org/fr/}, and
Korean@footnote{https://docs.python.org/ko/}.
@end itemize

This release features notable performance improvements in many areas.
The @ref{abe,,Optimizations} section lists them in detail.

For a list of changes that may affect compatibility with previous Python
releases please refer to the @ref{abf,,Porting to Python 3.7} section.

@node Nouvelles fonctionnalités<12>,Autres changements au langage<7>,Summary -- Release Highlights<2>,What's New In Python 3 7
@anchor{whatsnew/3 7 new-features}@anchor{ac0}
@subsection Nouvelles fonctionnalités


@menu
* PEP 563; Postponed Evaluation of Annotations: PEP 563 Postponed Evaluation of Annotations. 
* PEP 538; Legacy C Locale Coercion: PEP 538 Legacy C Locale Coercion. 
* PEP 540; Forced UTF-8 Runtime Mode: PEP 540 Forced UTF-8 Runtime Mode. 
* PEP 553; Built-in breakpoint(): PEP 553 Built-in breakpoint. 
* PEP 539; New C API for Thread-Local Storage: PEP 539 New C API for Thread-Local Storage. 
* PEP 562; Customization of Access to Module Attributes: PEP 562 Customization of Access to Module Attributes. 
* PEP 564; New Time Functions With Nanosecond Resolution: PEP 564 New Time Functions With Nanosecond Resolution. 
* PEP 565; Show DeprecationWarning in __main__: PEP 565 Show DeprecationWarning in __main__. 
* PEP 560; Core Support for typing module and Generic Types: PEP 560 Core Support for typing module and Generic Types. 
* PEP 552; Hash-based .pyc Files: PEP 552 Hash-based pyc Files. 
* PEP 545; Python Documentation Translations: PEP 545 Python Documentation Translations. 
* Python Development Mode (-X dev): Python Development Mode -X dev. 

@end menu

@node PEP 563 Postponed Evaluation of Annotations,PEP 538 Legacy C Locale Coercion,,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-563-postponed-evaluation-of-annotations}@anchor{ac1}@anchor{whatsnew/3 7 whatsnew37-pep563}@anchor{aad}
@subsubsection PEP 563: Postponed Evaluation of Annotations


The advent of type hints in Python uncovered two glaring usability issues
with the functionality of annotations added in 
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/} and refined
further in 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}:


@itemize *

@item 
annotations could only use names which were already available in the
current scope, in other words they didn't support forward references
of any kind; and

@item 
annotating source code had adverse effects on startup time of Python
programs.
@end itemize

Both of these issues are fixed by postponing the evaluation of
annotations.  Instead of compiling code which executes expressions in
annotations at their definition time, the compiler stores the annotation
in a string form equivalent to the AST of the expression in question.
If needed, annotations can be resolved at runtime using
@ref{69c,,typing.get_type_hints()}.  In the common case where this is not
required, the annotations are cheaper to store (since short strings
are interned by the interpreter) and make startup time faster.

Usability-wise, annotations now support forward references, making the
following syntax valid:

@example
class C:
    @@classmethod
    def from_string(cls, source: str) -> C:
        ...

    def validate_b(self, obj: B) -> bool:
        ...

class B:
    ...
@end example

Since this change breaks compatibility, the new behavior needs to be enabled
on a per-module basis in Python 3.7 using a @ref{0,,__future__} import:

@example
from __future__ import annotations
@end example

It will become the default in Python 3.10.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 563

@item PEP 563@footnote{https://peps.python.org/pep-0563/} -- Postponed evaluation of annotations

PEP written and implemented by Łukasz Langa.
@end table


@node PEP 538 Legacy C Locale Coercion,PEP 540 Forced UTF-8 Runtime Mode,PEP 563 Postponed Evaluation of Annotations,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-538-legacy-c-locale-coercion}@anchor{ac2}@anchor{whatsnew/3 7 whatsnew37-pep538}@anchor{ab7}
@subsubsection PEP 538: Legacy C Locale Coercion


An ongoing challenge within the Python 3 series has been determining a sensible
default strategy for handling the "7-bit ASCII" text encoding assumption
currently implied by the use of the default C or POSIX locale on non-Windows
platforms.

@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/} updates the default interpreter command line interface to
automatically coerce that locale to an available UTF-8 based locale as
described in the documentation of the new 
@geindex PYTHONCOERCECLOCALE
@geindex variable d'environnement; PYTHONCOERCECLOCALE
@ref{ac3,,PYTHONCOERCECLOCALE}
environment variable. Automatically setting @code{LC_CTYPE} this way means that
both the core interpreter and locale-aware C extensions (such as
@ref{b9,,readline}) will assume the use of UTF-8 as the default text encoding,
rather than ASCII.

The platform support definition in 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} has also been updated to limit
full text handling support to suitably configured non-ASCII based locales.

As part of this change, the default error handler for @ref{527,,stdin} and
@ref{ac4,,stdout} is now @code{surrogateescape} (rather than @code{strict}) when
using any of the defined coercion target locales (currently @code{C.UTF-8},
@code{C.utf8}, and @code{UTF-8}).  The default error handler for @ref{926,,stderr}
continues to be @code{backslashreplace}, regardless of locale.

Locale coercion is silent by default, but to assist in debugging potentially
locale related integration problems, explicit warnings (emitted directly on
@ref{926,,stderr}) can be requested by setting @code{PYTHONCOERCECLOCALE=warn}.
This setting will also cause the Python runtime to emit a warning if the
legacy C locale remains active when the core interpreter is initialized.

While 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}'s locale coercion has the benefit of also affecting extension
modules (such as GNU @code{readline}), as well as child processes (including those
running non-Python applications and older versions of Python), it has the
downside of requiring that a suitable target locale be present on the running
system. To better handle the case where no suitable target locale is available
(as occurs on RHEL/CentOS 7, for example), Python 3.7 also implements
@ref{ab8,,PEP 540; Forced UTF-8 Runtime Mode}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 538

@item PEP 538@footnote{https://peps.python.org/pep-0538/} -- Coercing the legacy C locale to a UTF-8 based locale

PEP written and implemented by Nick Coghlan.
@end table


@node PEP 540 Forced UTF-8 Runtime Mode,PEP 553 Built-in breakpoint,PEP 538 Legacy C Locale Coercion,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-540-forced-utf-8-runtime-mode}@anchor{ac5}@anchor{whatsnew/3 7 whatsnew37-pep540}@anchor{ab8}
@subsubsection PEP 540: Forced UTF-8 Runtime Mode


The new @ref{175,,-X} @code{utf8} command line option and 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8}
environment variable can be used to enable the @ref{641,,Python UTF-8 Mode}.

When in UTF-8 mode, CPython ignores the locale settings, and uses the
UTF-8 encoding by default.  The error handlers for @ref{527,,sys.stdin} and
@ref{ac4,,sys.stdout} streams are set to @code{surrogateescape}.

The forced UTF-8 mode can be used to change the text handling behavior in
an embedded Python interpreter without changing the locale settings of
an embedding application.

While 
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/}'s UTF-8 mode has the benefit of working regardless of which
locales are available on the running system, it has the downside of having no
effect on extension modules (such as GNU @code{readline}), child processes running
non-Python applications, and child processes running older versions of Python.
To reduce the risk of corrupting text data when communicating with such
components, Python 3.7 also implements @ref{ab8,,PEP 540; Forced UTF-8 Runtime Mode}).

The UTF-8 mode is enabled by default when the locale is @code{C} or @code{POSIX}, and
the 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/} locale coercion feature fails to change it to a UTF-8 based
alternative (whether that failure is due to @code{PYTHONCOERCECLOCALE=0} being set,
@code{LC_ALL} being set, or the lack of a suitable target locale).


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 540

@item PEP 540@footnote{https://peps.python.org/pep-0540/} -- Add a new UTF-8 mode

PEP written and implemented by Victor Stinner
@end table


@node PEP 553 Built-in breakpoint,PEP 539 New C API for Thread-Local Storage,PEP 540 Forced UTF-8 Runtime Mode,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-553-built-in-breakpoint}@anchor{ac7}@anchor{whatsnew/3 7 whatsnew37-pep553}@anchor{ab1}
@subsubsection PEP 553: Built-in @code{breakpoint()}


Python 3.7 includes the new built-in @ref{231,,breakpoint()} function as
an easy and consistent way to enter the Python debugger.

Built-in @code{breakpoint()} calls @ref{ac8,,sys.breakpointhook()}.  By default, the
latter imports @ref{a4,,pdb} and then calls @code{pdb.set_trace()}, but by binding
@code{sys.breakpointhook()} to the function of your choosing, @code{breakpoint()} can
enter any debugger. Additionally, the environment variable
@geindex PYTHONBREAKPOINT
@geindex variable d'environnement; PYTHONBREAKPOINT
@ref{ac9,,PYTHONBREAKPOINT} can be set to the callable of your debugger of
choice.  Set @code{PYTHONBREAKPOINT=0} to completely disable built-in
@code{breakpoint()}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 553

@item PEP 553@footnote{https://peps.python.org/pep-0553/} -- Built-in breakpoint()

PEP written and implemented by Barry Warsaw
@end table


@node PEP 539 New C API for Thread-Local Storage,PEP 562 Customization of Access to Module Attributes,PEP 553 Built-in breakpoint,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-539-new-c-api-for-thread-local-storage}@anchor{aca}@anchor{whatsnew/3 7 whatsnew37-pep539}
@subsubsection PEP 539: New C API for Thread-Local Storage


While Python provides a C API for thread-local storage support; the existing
@ref{acb,,Thread Local Storage (TLS) API} has used
int to represent TLS keys across all platforms.  This has not
generally been a problem for officially support platforms, but that is neither
POSIX-compliant, nor portable in any practical sense.

@geindex Python Enhancement Proposals; PEP 539
PEP 539@footnote{https://peps.python.org/pep-0539/} changes this by providing a new @ref{acc,,Thread Specific Storage (TSS) API} to CPython which supersedes use of the
existing TLS API within the CPython interpreter, while deprecating the existing
API.  The TSS API uses a new type @ref{acd,,Py_tss_t} instead of int
to represent TSS keys--an opaque type the definition of which may depend on
the underlying TLS implementation.  Therefore, this will allow to build CPython
on platforms where the native TLS key is defined in a way that cannot be safely
cast to int.

Note that on platforms where the native TLS key is defined in a way that cannot
be safely cast to int, all functions of the existing TLS API will be
no-op and immediately return failure. This indicates clearly that the old API
is not supported on platforms where it cannot be used reliably, and that no
effort will be made to add such support.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 539

@item PEP 539@footnote{https://peps.python.org/pep-0539/} -- A New C-API for Thread-Local Storage in CPython

PEP written by Erik M. Bray; implementation by Masayuki Yamamoto.
@end table


@node PEP 562 Customization of Access to Module Attributes,PEP 564 New Time Functions With Nanosecond Resolution,PEP 539 New C API for Thread-Local Storage,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-562-customization-of-access-to-module-attributes}@anchor{ace}@anchor{whatsnew/3 7 whatsnew37-pep562}@anchor{ab2}
@subsubsection PEP 562: Customization of Access to Module Attributes


Python 3.7 allows defining @code{__getattr__()} on modules and will call
it whenever a module attribute is otherwise not found.  Defining
@code{__dir__()} on modules is now also allowed.

A typical example of where this may be useful is module attribute deprecation
and lazy loading.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 562

@item PEP 562@footnote{https://peps.python.org/pep-0562/} -- Module @code{__getattr__} and @code{__dir__}

PEP written and implemented by Ivan Levkivskyi
@end table


@node PEP 564 New Time Functions With Nanosecond Resolution,PEP 565 Show DeprecationWarning in __main__,PEP 562 Customization of Access to Module Attributes,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-564-new-time-functions-with-nanosecond-resolution}@anchor{acf}@anchor{whatsnew/3 7 whatsnew37-pep564}@anchor{ab6}
@subsubsection PEP 564: New Time Functions With Nanosecond Resolution


The resolution of clocks in modern systems can exceed the limited precision
of a floating-point number returned by the @ref{251,,time.time()} function
and its variants.  To avoid loss of precision, 
@geindex Python Enhancement Proposals; PEP 564
PEP 564@footnote{https://peps.python.org/pep-0564/} adds six new
"nanosecond" variants of the existing timer functions to the @ref{ed,,time}
module:


@itemize *

@item 
@ref{ad0,,time.clock_gettime_ns()}

@item 
@ref{ad1,,time.clock_settime_ns()}

@item 
@ref{ad2,,time.monotonic_ns()}

@item 
@ref{ad3,,time.perf_counter_ns()}

@item 
@ref{ad4,,time.process_time_ns()}

@item 
@ref{ad5,,time.time_ns()}
@end itemize

The new functions return the number of nanoseconds as an integer value.

@geindex Python Enhancement Proposals; PEP 0564#annex-clocks-resolution-in-python
Measurements@footnote{https://peps.python.org/pep-0564/#annex-clocks-resolution-in-python}
show that on Linux and Windows the resolution of @ref{ad5,,time.time_ns()} is
approximately 3 times better than that of @ref{251,,time.time()}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 564

@item PEP 564@footnote{https://peps.python.org/pep-0564/} -- Add new time functions with nanosecond resolution

PEP written and implemented by Victor Stinner
@end table


@node PEP 565 Show DeprecationWarning in __main__,PEP 560 Core Support for typing module and Generic Types,PEP 564 New Time Functions With Nanosecond Resolution,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-565-show-deprecationwarning-in-main}@anchor{ad6}@anchor{whatsnew/3 7 whatsnew37-pep565}@anchor{abb}
@subsubsection PEP 565: Show DeprecationWarning in @code{__main__}


The default handling of @ref{1a3,,DeprecationWarning} has been changed such that
these warnings are once more shown by default, but only when the code
triggering them is running directly in the @ref{1,,__main__} module.  As a result,
developers of single file scripts and those using Python interactively should
once again start seeing deprecation warnings for the APIs they use, but
deprecation warnings triggered by imported application, library and framework
modules will continue to be hidden by default.

As a result of this change, the standard library now allows developers to choose
between three different deprecation warning behaviours:


@itemize *

@item 
@ref{40b,,FutureWarning}: always displayed by default, recommended for warnings
intended to be seen by application end users (e.g. for deprecated application
configuration settings).

@item 
@ref{1a3,,DeprecationWarning}: displayed by default only in @ref{1,,__main__} and when
running tests, recommended for warnings intended to be seen by other Python
developers where a version upgrade may result in changed behaviour or an
error.

@item 
@ref{8b5,,PendingDeprecationWarning}: displayed by default only when running
tests, intended for cases where a future version upgrade will change the
warning category to @ref{1a3,,DeprecationWarning} or @ref{40b,,FutureWarning}.
@end itemize

Previously both @ref{1a3,,DeprecationWarning} and @ref{8b5,,PendingDeprecationWarning}
were only visible when running tests, which meant that developers primarily
writing single file scripts or using Python interactively could be surprised
by breaking changes in the APIs they used.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 565

@item PEP 565@footnote{https://peps.python.org/pep-0565/} -- Show DeprecationWarning in @code{__main__}

PEP written and implemented by Nick Coghlan
@end table


@node PEP 560 Core Support for typing module and Generic Types,PEP 552 Hash-based pyc Files,PEP 565 Show DeprecationWarning in __main__,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-560-core-support-for-typing-module-and-generic-types}@anchor{ad7}@anchor{whatsnew/3 7 whatsnew37-pep560}@anchor{ab3}
@subsubsection PEP 560: Core Support for @code{typing} module and Generic Types


Initially 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} was designed in such way that it would not introduce `any'
changes to the core CPython interpreter. Now type hints and the @ref{103,,typing}
module are extensively used by the community, so this restriction is removed.
The PEP introduces two special methods @code{__class_getitem__()} and
@code{__mro_entries__}, these methods are now used by most classes and special
constructs in @ref{103,,typing}. As a result, the speed of various operations
with types increased up to 7 times, the generic types can be used without
metaclass conflicts, and several long standing bugs in @ref{103,,typing} module are
fixed.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 560

@item PEP 560@footnote{https://peps.python.org/pep-0560/} -- Core support for typing module and generic types

PEP written and implemented by Ivan Levkivskyi
@end table


@node PEP 552 Hash-based pyc Files,PEP 545 Python Documentation Translations,PEP 560 Core Support for typing module and Generic Types,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-552-hash-based-pyc-files}@anchor{ad8}@anchor{whatsnew/3 7 whatsnew37-pep552}@anchor{ab9}
@subsubsection PEP 552: Hash-based .pyc Files


Python has traditionally checked the up-to-dateness of bytecode cache files
(i.e., @code{.pyc} files) by comparing the source metadata (last-modified timestamp
and size) with source metadata saved in the cache file header when it was
generated. While effective, this invalidation method has its drawbacks.  When
filesystem timestamps are too coarse, Python can miss source updates, leading to
user confusion. Additionally, having a timestamp in the cache file is
problematic for build reproducibility@footnote{https://reproducible-builds.org/} and
content-based build systems.

@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} extends the pyc format to allow the hash of the source file to be
used for invalidation instead of the source timestamp. Such @code{.pyc} files are
called "hash-based". By default, Python still uses timestamp-based invalidation
and does not generate hash-based @code{.pyc} files at runtime. Hash-based @code{.pyc}
files may be generated with @ref{b2,,py_compile} or @ref{20,,compileall}.

Hash-based @code{.pyc} files come in two variants: checked and unchecked. Python
validates checked hash-based @code{.pyc} files against the corresponding source
files at runtime but doesn't do so for unchecked hash-based pycs. Unchecked
hash-based @code{.pyc} files are a useful performance optimization for environments
where a system external to Python (e.g., the build system) is responsible for
keeping @code{.pyc} files up-to-date.

See @ref{5d6,,Invalidation de bytecode mis en cache} for more information.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 552

@item PEP 552@footnote{https://peps.python.org/pep-0552/} -- Deterministic pycs

PEP written and implemented by Benjamin Peterson
@end table


@node PEP 545 Python Documentation Translations,Python Development Mode -X dev,PEP 552 Hash-based pyc Files,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 pep-545-python-documentation-translations}@anchor{ad9}@anchor{whatsnew/3 7 whatsnew37-pep545}@anchor{abd}
@subsubsection PEP 545: Python Documentation Translations


@geindex Python Enhancement Proposals; PEP 545
PEP 545@footnote{https://peps.python.org/pep-0545/} describes the process of creating and maintaining Python
documentation translations.

Three new translations have been added:


@itemize -

@item 
Japanese: @indicateurl{https://docs.python.org/ja/}

@item 
French: @indicateurl{https://docs.python.org/fr/}

@item 
Korean: @indicateurl{https://docs.python.org/ko/}
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 545

@item PEP 545@footnote{https://peps.python.org/pep-0545/} -- Python Documentation Translations

PEP written and implemented by Julien Palard, Inada Naoki, and
Victor Stinner.
@end table


@node Python Development Mode -X dev,,PEP 545 Python Documentation Translations,Nouvelles fonctionnalités<12>
@anchor{whatsnew/3 7 python-development-mode-x-dev}@anchor{ada}@anchor{whatsnew/3 7 whatsnew37-devmode}@anchor{aba}
@subsubsection Python Development Mode (-X dev)


The new @ref{175,,-X} @code{dev} command line option or the new
@geindex PYTHONDEVMODE
@geindex variable d'environnement; PYTHONDEVMODE
@ref{adb,,PYTHONDEVMODE} environment variable can be used to enable
@ref{1f5,,Python Development Mode}.  When in development mode, Python performs
additional runtime checks that are too expensive to be enabled by default.
See @ref{1f5,,Python Development Mode} documentation for the full
description.

@node Autres changements au langage<7>,Nouveaux modules<7>,Nouvelles fonctionnalités<12>,What's New In Python 3 7
@anchor{whatsnew/3 7 other-language-changes}@anchor{adc}
@subsection Autres changements au langage



@itemize *

@item 
An @ref{1b7,,await} expression and comprehensions containing an
@ref{a99,,async for} clause were illegal in the expressions in
@ref{997,,formatted string literals} due to a problem with the
implementation.  In Python 3.7 this restriction was lifted.

@item 
More than 255 arguments can now be passed to a function, and a function can
now have more than 255 parameters. (Contributed by Serhiy Storchaka in
bpo-12844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12844} and bpo-18896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18896}.)

@item 
@ref{add,,bytes.fromhex()} and @ref{ade,,bytearray.fromhex()} now ignore all ASCII
whitespace, not only spaces. (Contributed by Robert Xiao in bpo-28927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28927}.)

@item 
@ref{435,,str}, @ref{1bd,,bytes}, and @ref{528,,bytearray} gained support for
the new @ref{adf,,isascii()} method, which can be used to
test if a string or bytes contain only the ASCII characters.
(Contributed by INADA Naoki in bpo-32677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32677}.)

@item 
@ref{40f,,ImportError} now displays module name and module @code{__file__} path when
@code{from ... import ...} fails. (Contributed by Matthias Bussonnier in
bpo-29546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29546}.)

@item 
Circular imports involving absolute imports with binding a submodule to
a name are now supported.
(Contributed by Serhiy Storchaka in bpo-30024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30024}.)

@item 
@code{object.__format__(x, '@w{'})} is now equivalent to @code{str(x)} rather than
@code{format(str(self), '@w{'})}.
(Contributed by Serhiy Storchaka in bpo-28974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28974}.)

@item 
In order to better support dynamic creation of stack traces,
@ref{ae0,,types.TracebackType} can now be instantiated from Python code, and
the @ref{ae1,,tb_next} attribute on
@ref{ae2,,tracebacks} is now writable.
(Contributed by Nathaniel J. Smith in bpo-30579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30579}.)

@item 
When using the @ref{5cb,,-m} switch, @code{sys.path[0]} is now eagerly expanded
to the full starting directory path, rather than being left as the empty
directory (which allows imports from the `current' working directory at the
time when an import occurs)
(Contributed by Nick Coghlan in bpo-33053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33053}.)

@item 
The new @ref{175,,-X} @code{importtime} option or the
@geindex PYTHONPROFILEIMPORTTIME
@geindex variable d'environnement; PYTHONPROFILEIMPORTTIME
@ref{ae3,,PYTHONPROFILEIMPORTTIME} environment variable can be used to show
the timing of each module import.
(Contributed by Inada Naoki in bpo-31415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31415}.)
@end itemize

@node Nouveaux modules<7>,Modules améliorés<7>,Autres changements au langage<7>,What's New In Python 3 7
@anchor{whatsnew/3 7 new-modules}@anchor{ae4}
@subsection Nouveaux modules


@menu
* contextvars:: 
* dataclasses: dataclasses<3>. 
* importlib.resources: importlib resources<2>. 

@end menu

@node contextvars,dataclasses<3>,,Nouveaux modules<7>
@anchor{whatsnew/3 7 contextvars}@anchor{ae5}@anchor{whatsnew/3 7 whatsnew37-pep567}@anchor{aae}
@subsubsection contextvars


The new @ref{24,,contextvars} module and a set of
@ref{ae6,,new C APIs} introduce
support for `context variables'.  Context variables are conceptually
similar to thread-local variables.  Unlike TLS, context variables
support asynchronous code correctly.

The @ref{a,,asyncio} and @ref{36,,decimal} modules have been updated to use
and support context variables out of the box.  Particularly the active
decimal context is now stored in a context variable, which allows
decimal operations to work with the correct context in asynchronous code.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 567

@item PEP 567@footnote{https://peps.python.org/pep-0567/} -- Context Variables

PEP written and implemented by Yury Selivanov
@end table


@node dataclasses<3>,importlib resources<2>,contextvars,Nouveaux modules<7>
@anchor{whatsnew/3 7 dataclasses}@anchor{ae7}@anchor{whatsnew/3 7 whatsnew37-pep557}@anchor{aaf}
@subsubsection @code{dataclasses}


The new @ref{1c6,,dataclass()} decorator provides a way to declare
`data classes'.  A data class describes its attributes using class variable
annotations.  Its constructor and other magic methods, such as
@ref{607,,__repr__()}, @ref{ae8,,__eq__()}, and
@ref{ae9,,__hash__()} are generated automatically.

Exemple :

@example
@@dataclass
class Point:
    x: float
    y: float
    z: float = 0.0

p = Point(1.5, 2.5)
print(p)   # produces "Point(x=1.5, y=2.5, z=0.0)"
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 557

@item PEP 557@footnote{https://peps.python.org/pep-0557/} -- Data Classes

PEP written and implemented by Eric V. Smith
@end table


@node importlib resources<2>,,dataclasses<3>,Nouveaux modules<7>
@anchor{whatsnew/3 7 importlib-resources}@anchor{aea}@anchor{whatsnew/3 7 whatsnew37-importlib-resources}@anchor{ab0}
@subsubsection importlib.resources


The new @ref{7a,,importlib.resources} module provides several new APIs and one
new ABC for access to, opening, and reading `resources' inside packages.
Resources are roughly similar to files inside packages, but they needn't
be actual files on the physical file system.  Module loaders can provide a
@code{get_resource_reader()} function which returns
a @ref{aeb,,importlib.abc.ResourceReader} instance to support this
new API.  Built-in file path loaders and zip file loaders both support this.

Contributed by Barry Warsaw and Brett Cannon in bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}.


@subsubheading Voir aussi


importlib_resources@footnote{https://importlib-resources.readthedocs.io/en/latest/}
-- a PyPI backport for earlier Python versions.


@node Modules améliorés<7>,Changements à l'API C<6>,Nouveaux modules<7>,What's New In Python 3 7
@anchor{whatsnew/3 7 improved-modules}@anchor{aec}
@subsection Modules améliorés


@menu
* argparse: argparse<3>. 
* asyncio: asyncio<7>. 
* binascii:: 
* calendar: calendar<2>. 
* collections: collections<2>. 
* compileall: compileall<3>. 
* concurrent.futures: concurrent futures<3>. 
* contextlib: contextlib<3>. 
* cProfile: cProfile<2>. 
* crypt:: 
* datetime: datetime<4>. 
* dbm: dbm<2>. 
* decimal:: 
* dis: dis<3>. 
* distutils: distutils<4>. 
* enum: enum<5>. 
* functools: functools<3>. 
* gc: gc<4>. 
* hmac: hmac<2>. 
* http.client: http client. 
* http.server: http server. 
* idlelib and IDLE:: 
* importlib: importlib<4>. 
* io: io<4>. 
* ipaddress: ipaddress<3>. 
* itertools: itertools<5>. 
* locale: locale<4>. 
* logging: logging<3>. 
* math: math<6>. 
* mimetypes: mimetypes<2>. 
* msilib:: 
* multiprocessing: multiprocessing<4>. 
* os: os<7>. 
* pathlib: pathlib<8>. 
* pdb: pdb<4>. 
* py_compile: py_compile<3>. 
* pydoc: pydoc<2>. 
* queue: queue<2>. 
* re: re<4>. 
* signal: signal<2>. 
* socket: socket<5>. 
* socketserver:: 
* sqlite3: sqlite3<6>. 
* ssl: ssl<5>. 
* string: string<2>. 
* subprocess: subprocess<2>. 
* sys: sys<8>. 
* time: time<5>. 
* tkinter: tkinter<5>. 
* tracemalloc: tracemalloc<2>. 
* types: types<4>. 
* unicodedata: unicodedata<6>. 
* unittest: unittest<7>. 
* unittest.mock: unittest mock. 
* urllib.parse: urllib parse<5>. 
* uu:: 
* uuid: uuid<2>. 
* warnings: warnings<3>. 
* xml: xml<5>. 
* xml.etree: xml etree. 
* xmlrpc.server: xmlrpc server. 
* zipapp:: 
* zipfile: zipfile<2>. 

@end menu

@node argparse<3>,asyncio<7>,,Modules améliorés<7>
@anchor{whatsnew/3 7 argparse}@anchor{aed}
@subsubsection argparse


The new @ref{aee,,ArgumentParser.parse_intermixed_args()}
method allows intermixing options and positional arguments.
(Contributed by paul.j3 in bpo-14191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14191}.)

@node asyncio<7>,binascii,argparse<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 asyncio}@anchor{aef}@anchor{whatsnew/3 7 whatsnew37-asyncio}@anchor{ab5}
@subsubsection asyncio


The @ref{a,,asyncio} module has received many new features, usability and
@ref{af0,,performance improvements}.  Notable changes
include:


@itemize *

@item 
The new @ref{af1,,provisional} @ref{466,,asyncio.run()} function can
be used to run a coroutine from synchronous code by automatically creating and
destroying the event loop.
(Contributed by Yury Selivanov in bpo-32314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32314}.)

@item 
asyncio gained support for @ref{24,,contextvars}.
@ref{af2,,loop.call_soon()},
@ref{af3,,loop.call_soon_threadsafe()},
@ref{af4,,loop.call_later()},
@ref{af5,,loop.call_at()}, and
@ref{af6,,Future.add_done_callback()}
have a new optional keyword-only `context' parameter.
@ref{4c2,,Tasks} now track their context automatically.
See 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} for more details.
(Contributed by Yury Selivanov in bpo-32436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32436}.)

@item 
The new @ref{5e7,,asyncio.create_task()} function has been added as a shortcut
to @code{asyncio.get_event_loop().create_task()}.
(Contributed by Andrew Svetlov in bpo-32311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32311}.)

@item 
The new @ref{af7,,loop.start_tls()}
method can be used to upgrade an existing connection to TLS.
(Contributed by Yury Selivanov in bpo-23749@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23749}.)

@item 
The new @ref{af8,,loop.sock_recv_into()}
method allows reading data from a socket directly into a provided buffer making
it possible to reduce data copies.
(Contributed by Antoine Pitrou in bpo-31819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31819}.)

@item 
The new @ref{467,,asyncio.current_task()} function returns the currently running
@ref{4c2,,Task} instance, and the new @ref{943,,asyncio.all_tasks()}
function returns a set of all existing @code{Task} instances in a given loop.
The @code{Task.current_task()} and
@code{Task.all_tasks()} methods have been deprecated.
(Contributed by Andrew Svetlov in bpo-32250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32250}.)

@item 
The new `provisional' @ref{a8b,,BufferedProtocol} class allows
implementing streaming protocols with manual control over the receive buffer.
(Contributed by Yury Selivanov in bpo-32251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32251}.)

@item 
The new @ref{af9,,asyncio.get_running_loop()} function returns the currently
running loop, and raises a @ref{193,,RuntimeError} if no loop is running.
This is in contrast with @ref{2bf,,asyncio.get_event_loop()}, which will `create'
a new event loop if none is running.
(Contributed by Yury Selivanov in bpo-32269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32269}.)

@item 
The new @ref{afa,,StreamWriter.wait_closed()}
coroutine method allows waiting until the stream writer is closed.  The new
@ref{afb,,StreamWriter.is_closing()} method
can be used to determine if the writer is closing.
(Contributed by Andrew Svetlov in bpo-32391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32391}.)

@item 
The new @ref{afc,,loop.sock_sendfile()}
coroutine method allows sending files using @ref{afd,,os.sendfile} when possible.
(Contributed by Andrew Svetlov in bpo-32410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32410}.)

@item 
The new @ref{afe,,Future.get_loop()} and
@code{Task.get_loop()} methods return the instance of the loop on which a task or
a future were created.
@ref{aff,,Server.get_loop()} allows doing the same for
@ref{b00,,asyncio.Server} objects.
(Contributed by Yury Selivanov in bpo-32415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32415} and
Srinivas Reddy Thatiparthy in bpo-32418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32418}.)

@item 
It is now possible to control how instances of @ref{b00,,asyncio.Server} begin
serving.  Previously, the server would start serving immediately when created.
The new `start_serving' keyword argument to
@ref{b01,,loop.create_server()} and
@ref{1ac,,loop.create_unix_server()},
as well as @ref{b02,,Server.start_serving()}, and
@ref{b03,,Server.serve_forever()}
can be used to decouple server instantiation and serving.  The new
@ref{b04,,Server.is_serving()} method returns @code{True}
if the server is serving.  @ref{b00,,Server} objects are now
asynchronous context managers:

@example
srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.
@end example

(Contributed by Yury Selivanov in bpo-32662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32662}.)

@item 
Callback objects returned by
@ref{af4,,loop.call_later()}
gained the new @ref{b05,,when()} method which
returns an absolute scheduled callback timestamp.
(Contributed by Andrew Svetlov in bpo-32741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32741}.)

@item 
The @ref{71d,,loop.create_datagram_endpoint()} method
gained support for Unix sockets.
(Contributed by Quentin Dawans in bpo-31245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31245}.)

@item 
The @ref{b06,,asyncio.open_connection()}, @ref{b07,,asyncio.start_server()} functions,
@ref{5ee,,loop.create_connection()},
@ref{b01,,loop.create_server()},
@ref{b08,,loop.create_accepted_socket()}
methods and their corresponding UNIX socket variants now accept the
`ssl_handshake_timeout' keyword argument.
(Contributed by Neil Aspinall in bpo-29970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29970}.)

@item 
The new @ref{b09,,Handle.cancelled()} method returns
@code{True} if the callback was cancelled.
(Contributed by Marat Sharafutdinov in bpo-31943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31943}.)

@item 
The asyncio source has been converted to use the
@ref{71c,,async}/@ref{1b7,,await} syntax.
(Contributed by Andrew Svetlov in bpo-32193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32193}.)

@item 
The new @ref{b0a,,ReadTransport.is_reading()}
method can be used to determine the reading state of the transport.
Additionally, calls to
@ref{b0b,,ReadTransport.resume_reading()}
and @ref{b0c,,ReadTransport.pause_reading()}
are now idempotent.
(Contributed by Yury Selivanov in bpo-32356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32356}.)

@item 
Loop methods which accept socket paths now support passing
@ref{29d,,path-like objects}.
(Contributed by Yury Selivanov in bpo-32066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32066}.)

@item 
In @ref{a,,asyncio} TCP sockets on Linux are now created with @code{TCP_NODELAY}
flag set by default.
(Contributed by Yury Selivanov and Victor Stinner in bpo-27456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27456}.)

@item 
Exceptions occurring in cancelled tasks are no longer logged.
(Contributed by Yury Selivanov in bpo-30508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30508}.)

@item 
New @code{WindowsSelectorEventLoopPolicy} and
@code{WindowsProactorEventLoopPolicy} classes.
(Contributed by Yury Selivanov in bpo-33792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33792}.)
@end itemize

Several @code{asyncio} APIs have been
@ref{b0d,,deprecated}.

@node binascii,calendar<2>,asyncio<7>,Modules améliorés<7>
@anchor{whatsnew/3 7 binascii}@anchor{b0e}
@subsubsection binascii


The @ref{b0f,,b2a_uu()} function now accepts an optional `backtick'
keyword argument.  When it's true, zeros are represented by @code{'`'}
instead of spaces.  (Contributed by Xiang Zhang in bpo-30103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30103}.)

@node calendar<2>,collections<2>,binascii,Modules améliorés<7>
@anchor{whatsnew/3 7 calendar}@anchor{b10}
@subsubsection calendar


The @ref{b11,,HTMLCalendar} class has new class attributes which ease
the customization of CSS classes in the produced HTML calendar.
(Contributed by Oz Tiram in bpo-30095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30095}.)

@node collections<2>,compileall<3>,calendar<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 collections}@anchor{b12}
@subsubsection collections


@code{collections.namedtuple()} now supports default values.
(Contributed by Raymond Hettinger in bpo-32320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32320}.)

@node compileall<3>,concurrent futures<3>,collections<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 compileall}@anchor{b13}
@subsubsection compileall


@ref{b14,,compileall.compile_dir()} learned the new `invalidation_mode' parameter,
which can be used to enable
@ref{ab9,,hash-based .pyc invalidation}.  The invalidation
mode can also be specified on the command line using the new
@code{--invalidation-mode} argument.
(Contributed by Benjamin Peterson in bpo-31650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31650}.)

@node concurrent futures<3>,contextlib<3>,compileall<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 concurrent-futures}@anchor{b15}
@subsubsection concurrent.futures


@ref{8db,,ProcessPoolExecutor} and
@ref{72c,,ThreadPoolExecutor} now
support the new `initializer' and `initargs' constructor arguments.
(Contributed by Antoine Pitrou in bpo-21423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21423}.)

The @ref{8db,,ProcessPoolExecutor}
can now take the multiprocessing context via the new `mp_context' argument.
(Contributed by Thomas Moreau in bpo-31540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31540}.)

@node contextlib<3>,cProfile<2>,concurrent futures<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 contextlib}@anchor{b16}
@subsubsection contextlib


The new @ref{7d8,,nullcontext()} is a simpler and faster no-op
context manager than @ref{b17,,ExitStack}.
(Contributed by Jesse-Bakker in bpo-10049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10049}.)

The new @ref{b18,,asynccontextmanager()},
@ref{b19,,AbstractAsyncContextManager}, and
@ref{b1a,,AsyncExitStack} have been added to
complement their synchronous counterparts.  (Contributed
by Jelle Zijlstra in bpo-29679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29679} and bpo-30241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30241},
and by Alexander Mohr and Ilya Kulakov in bpo-29302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29302}.)

@node cProfile<2>,crypt,contextlib<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 cprofile}@anchor{b1b}
@subsubsection cProfile


The @ref{27,,cProfile} command line now accepts @code{-m module_name} as an
alternative to script path.  (Contributed by Sanyam Khurana in bpo-21862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21862}.)

@node crypt,datetime<4>,cProfile<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 crypt}@anchor{b1c}
@subsubsection crypt


The @code{crypt} module now supports the Blowfish hashing method.
(Contributed by Serhiy Storchaka in bpo-31664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31664}.)

The @code{mksalt()} function now allows specifying the number of rounds
for hashing.  (Contributed by Serhiy Storchaka in bpo-31702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31702}.)

@node datetime<4>,dbm<2>,crypt,Modules améliorés<7>
@anchor{whatsnew/3 7 datetime}@anchor{b1d}
@subsubsection datetime


The new @ref{602,,datetime.fromisoformat()}
method constructs a @ref{1c7,,datetime} object from a string
in one of the formats output by
@ref{b1e,,datetime.isoformat()}.
(Contributed by Paul Ganssle in bpo-15873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15873}.)

The @ref{5c8,,tzinfo} class now supports sub-minute offsets.
(Contributed by Alexander Belopolsky in bpo-5288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5288}.)

@node dbm<2>,decimal,datetime<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 dbm}@anchor{b1f}
@subsubsection dbm


@ref{32,,dbm.dumb} now supports reading read-only files and no longer writes the
index file when it is not changed.

@node decimal,dis<3>,dbm<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 decimal}@anchor{b20}
@subsubsection decimal


The @ref{36,,decimal} module now uses @ref{aae,,context variables}
to store the decimal context.
(Contributed by Yury Selivanov in bpo-32630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32630}.)

@node dis<3>,distutils<4>,decimal,Modules améliorés<7>
@anchor{whatsnew/3 7 dis}@anchor{b21}
@subsubsection dis


The @ref{b22,,dis()} function is now able to
disassemble nested code objects (the code of comprehensions, generator
expressions and nested functions, and the code used for building nested
classes).  The maximum depth of disassembly recursion is controlled by
the new `depth' parameter.
(Contributed by Serhiy Storchaka in bpo-11822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11822}.)

@node distutils<4>,enum<5>,dis<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 distutils}@anchor{b23}
@subsubsection distutils


@code{README.rst} is now included in the list of distutils standard READMEs and
therefore included in source distributions.
(Contributed by Ryan Gonzalez in bpo-11913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11913}.)

@node enum<5>,functools<3>,distutils<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 enum}@anchor{b24}
@subsubsection enum


The @ref{61b,,Enum} learned the new @code{_ignore_} class property,
which allows listing the names of properties which should not become
enum members.
(Contributed by Ethan Furman in bpo-31801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31801}.)

In Python 3.8, attempting to check for non-Enum objects in @code{Enum}
classes will raise a @ref{522,,TypeError} (e.g. @code{1 in Color}); similarly,
attempting to check for non-Flag objects in a @code{Flag} member will
raise @ref{522,,TypeError} (e.g. @code{1 in Perm.RW}); currently, both operations
return @ref{b25,,False} instead and are deprecated.
(Contributed by Ethan Furman in bpo-33217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33217}.)

@node functools<3>,gc<4>,enum<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 functools}@anchor{b26}
@subsubsection functools


@ref{624,,functools.singledispatch()} now supports registering implementations
using type annotations.
(Contributed by Łukasz Langa in bpo-32227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32227}.)

@node gc<4>,hmac<2>,functools<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 gc}@anchor{b27}
@subsubsection `gc'


The new @ref{b28,,gc.freeze()} function allows freezing all objects tracked
by the garbage collector and excluding them from future collections.
This can be used before a POSIX @code{fork()} call to make the GC copy-on-write
friendly or to speed up collection.  The new @ref{b29,,gc.unfreeze()} functions
reverses this operation.  Additionally, @ref{b2a,,gc.get_freeze_count()} can
be used to obtain the number of frozen objects.
(Contributed by Li Zekun in bpo-31558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31558}.)

@node hmac<2>,http client,gc<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 hmac}@anchor{b2b}
@subsubsection @code{hmac}


The @ref{69,,hmac} module now has an optimized one-shot @ref{b2c,,digest()}
function, which is up to three times faster than @code{HMAC()}.
(Contributed by Christian Heimes in bpo-32433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32433}.)

@node http client,http server,hmac<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 http-client}@anchor{b2d}
@subsubsection http.client


@ref{b2e,,HTTPConnection} and @ref{b2f,,HTTPSConnection}
now support the new `blocksize' argument for improved upload throughput.
(Contributed by Nir Soffer in bpo-31945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31945}.)

@node http server,idlelib and IDLE,http client,Modules améliorés<7>
@anchor{whatsnew/3 7 http-server}@anchor{b30}
@subsubsection http.server


@ref{b31,,SimpleHTTPRequestHandler} now supports the HTTP
@code{If-Modified-Since} header.  The server returns the 304 response status if
the target file was not modified after the time specified in the header.
(Contributed by Pierre Quentel in bpo-29654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29654}.)

@ref{b31,,SimpleHTTPRequestHandler} accepts the new `directory'
argument, in addition to the new @code{--directory} command line argument.
With this parameter, the server serves the specified directory, by default it
uses the current working directory.
(Contributed by Stéphane Wirtel and Julien Palard in bpo-28707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28707}.)

The new @ref{b32,,ThreadingHTTPServer} class
uses threads to handle requests using @code{ThreadingMixin}.
It is used when @code{http.server} is run with @code{-m}.
(Contributed by Julien Palard in bpo-31639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31639}.)

@node idlelib and IDLE,importlib<4>,http server,Modules améliorés<7>
@anchor{whatsnew/3 7 idlelib-and-idle}@anchor{b33}
@subsubsection idlelib and IDLE


Multiple fixes for autocompletion. (Contributed by Louie Lu in bpo-15786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15786}.)

Module Browser (on the File menu, formerly called Class Browser),
now displays nested functions and classes in addition to top-level
functions and classes.
(Contributed by Guilherme Polo, Cheryl Sabella, and Terry Jan Reedy
in bpo-1612262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1612262}.)

The Settings dialog (Options, Configure IDLE) has been partly rewritten
to improve both appearance and function.
(Contributed by Cheryl Sabella and Terry Jan Reedy in multiple issues.)

The font sample now includes a selection of non-Latin characters so that
users can better see the effect of selecting a particular font.
(Contributed by Terry Jan Reedy in bpo-13802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13802}.)
The sample can be edited to include other characters.
(Contributed by Serhiy Storchaka in bpo-31860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31860}.)

The IDLE features formerly implemented as extensions have been reimplemented
as normal features.  Their settings have been moved from the Extensions tab
to other dialog tabs.
(Contributed by Charles Wohlganger and Terry Jan Reedy in bpo-27099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27099}.)

Editor code context option revised.  Box displays all context lines up to
maxlines.  Clicking on a context line jumps the editor to that line.  Context
colors for custom themes is added to Highlights tab of Settings dialog.
(Contributed by Cheryl Sabella and Terry Jan Reedy in bpo-33642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33642},
bpo-33768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33768}, and bpo-33679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33679}.)

On Windows, a new API call tells Windows that tk scales for DPI. On Windows
8.1+ or 10, with DPI compatibility properties of the Python binary
unchanged, and a monitor resolution greater than 96 DPI, this should
make text and lines sharper.  It should otherwise have no effect.
(Contributed by Terry Jan Reedy in bpo-33656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33656}.)

New in 3.7.1:

Output over N lines (50 by default) is squeezed down to a button.
N can be changed in the PyShell section of the General page of the
Settings dialog.  Fewer, but possibly extra long, lines can be squeezed by
right clicking on the output.  Squeezed output can be expanded in place
by double-clicking the button or into the clipboard or a separate window
by right-clicking the button.  (Contributed by Tal Einat in bpo-1529353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1529353}.)

The changes above have been backported to 3.6 maintenance releases.

NEW in 3.7.4:

Add "Run Customized" to the Run menu to run a module with customized
settings. Any command line arguments entered are added to sys.argv.
They re-appear in the box for the next customized run.  One can also
suppress the normal Shell main module restart.  (Contributed by Cheryl
Sabella, Terry Jan Reedy, and others in bpo-5680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5680} and bpo-37627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37627}.)

New in 3.7.5:

Add optional line numbers for IDLE editor windows. Windows
open without line numbers unless set otherwise in the General
tab of the configuration dialog.  Line numbers for an existing
window are shown and hidden in the Options menu.
(Contributed by Tal Einat and Saimadhav Heblikar in bpo-17535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17535}.)

@node importlib<4>,io<4>,idlelib and IDLE,Modules améliorés<7>
@anchor{whatsnew/3 7 importlib}@anchor{b34}
@subsubsection importlib


The @ref{aeb,,importlib.abc.ResourceReader} ABC was introduced to
support the loading of resources from packages.  See also
@ref{ab0,,importlib.resources}.
(Contributed by Barry Warsaw, Brett Cannon in bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}.)

@ref{502,,importlib.reload()} now raises @ref{b35,,ModuleNotFoundError} if the module
lacks a spec.
(Contributed by Garvit Khatri in bpo-29851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29851}.)

@code{importlib.find_spec()} now raises @ref{b35,,ModuleNotFoundError} instead of
@ref{343,,AttributeError} if the specified parent module is not a package (i.e.
lacks a @code{__path__} attribute).
(Contributed by Milan Oberkirch in bpo-30436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30436}.)

The new @code{importlib.source_hash()} can be used to compute the hash of
the passed source.  A @ref{ab9,,hash-based .pyc file}
embeds the value returned by this function.

@node io<4>,ipaddress<3>,importlib<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 io}@anchor{b36}
@subsubsection io


The new @ref{b37,,TextIOWrapper.reconfigure()}
method can be used to reconfigure the text stream with the new settings.
(Contributed by Antoine Pitrou in bpo-30526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30526} and
INADA Naoki in bpo-15216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15216}.)

@node ipaddress<3>,itertools<5>,io<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 ipaddress}@anchor{b38}
@subsubsection `ipaddress'


The new @code{subnet_of()} and @code{supernet_of()} methods of
@ref{1fc,,ipaddress.IPv6Network} and @ref{1fb,,ipaddress.IPv4Network} can
be used for network containment tests.
(Contributed by Michel Albert and Cheryl Sabella in bpo-20825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20825}.)

@node itertools<5>,locale<4>,ipaddress<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 itertools}@anchor{b39}
@subsubsection itertools


@ref{b3a,,itertools.islice()} now accepts
@ref{707,,integer-like objects} as start, stop,
and slice arguments.
(Contributed by Will Roberts in bpo-30537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30537}.)

@node locale<4>,logging<3>,itertools<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 locale}@anchor{b3b}
@subsubsection locale


The new `monetary' argument to @ref{508,,locale.format_string()} can be used
to make the conversion use monetary thousands separators and
grouping strings.  (Contributed by Garvit in bpo-10379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10379}.)

The @ref{524,,locale.getpreferredencoding()} function now always returns @code{'UTF-8'}
on Android or when in the @ref{ab8,,forced UTF-8 mode}.

@node logging<3>,math<6>,locale<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 logging}@anchor{b3c}
@subsubsection logging


@ref{b3d,,Logger} instances can now be pickled.
(Contributed by Vinay Sajip in bpo-30520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30520}.)

The new @ref{b3e,,StreamHandler.setStream()}
method can be used to replace the logger stream after handler creation.
(Contributed by Vinay Sajip in bpo-30522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30522}.)

It is now possible to specify keyword arguments to handler constructors in
configuration passed to @ref{b3f,,logging.config.fileConfig()}.
(Contributed by Preston Landers in bpo-31080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31080}.)

@node math<6>,mimetypes<2>,logging<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 math}@anchor{b40}
@subsubsection `math'


The new @ref{b41,,math.remainder()} function implements the IEEE 754-style remainder
operation.  (Contributed by Mark Dickinson in bpo-29962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29962}.)

@node mimetypes<2>,msilib,math<6>,Modules améliorés<7>
@anchor{whatsnew/3 7 mimetypes}@anchor{b42}
@subsubsection mimetypes


The MIME type of .bmp has been changed from @code{'image/x-ms-bmp'} to
@code{'image/bmp'}.
(Contributed by Nitish Chandra in bpo-22589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22589}.)

@node msilib,multiprocessing<4>,mimetypes<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 msilib}@anchor{b43}
@subsubsection msilib


The new @code{Database.Close()} method can be used
to close the @abbr{MSI} database.
(Contributed by Berker Peksag in bpo-20486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20486}.)

@node multiprocessing<4>,os<7>,msilib,Modules améliorés<7>
@anchor{whatsnew/3 7 multiprocessing}@anchor{b44}
@subsubsection multiprocessing


The new @ref{b45,,Process.close()} method
explicitly closes the process object and releases all resources associated
with it.  @ref{1ff,,ValueError} is raised if the underlying process is still
running.
(Contributed by Antoine Pitrou in bpo-30596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30596}.)

The new @ref{b46,,Process.kill()} method can
be used to terminate the process using the @code{SIGKILL} signal on Unix.
(Contributed by Vitor Pereira in bpo-30794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30794}.)

Non-daemonic threads created by @ref{b47,,Process} are now
joined on process exit.
(Contributed by Antoine Pitrou in bpo-18966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18966}.)

@node os<7>,pathlib<8>,multiprocessing<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 os}@anchor{b48}
@subsubsection `os'


@ref{b49,,os.fwalk()} now accepts the `path' argument as @ref{1bd,,bytes}.
(Contributed by Serhiy Storchaka in bpo-28682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28682}.)

@ref{a4d,,os.scandir()} gained support for @ref{b4a,,file descriptors}.
(Contributed by Serhiy Storchaka in bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}.)

The new @ref{2f4,,register_at_fork()} function allows registering Python
callbacks to be executed at process fork.
(Contributed by Antoine Pitrou in bpo-16500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16500}.)

Added @ref{b4b,,os.preadv()} (combine the functionality of @ref{b4c,,os.readv()} and
@ref{b4d,,os.pread()}) and @ref{b4e,,os.pwritev()} functions (combine the functionality
of @ref{b4f,,os.writev()} and @ref{b50,,os.pwrite()}). (Contributed by Pablo Galindo in
bpo-31368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31368}.)

The mode argument of @ref{21b,,os.makedirs()} no longer affects the file
permission bits of newly created intermediate-level directories.
(Contributed by Serhiy Storchaka in bpo-19930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19930}.)

@ref{b51,,os.dup2()} now returns the new file descriptor.  Previously, @code{None}
was always returned.
(Contributed by Benjamin Peterson in bpo-32441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32441}.)

The structure returned by @ref{48a,,os.stat()} now contains the
@ref{b52,,st_fstype} attribute on Solaris and its derivatives.
(Contributed by Jesús Cea Avión in bpo-32659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32659}.)

@node pathlib<8>,pdb<4>,os<7>,Modules améliorés<7>
@anchor{whatsnew/3 7 pathlib}@anchor{b53}
@subsubsection pathlib


The new @ref{a05,,Path.is_mount()} method is now available
on POSIX systems and can be used to determine whether a path is a mount point.
(Contributed by Cooper Ry Lees in bpo-30897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30897}.)

@node pdb<4>,py_compile<3>,pathlib<8>,Modules améliorés<7>
@anchor{whatsnew/3 7 pdb}@anchor{b54}
@subsubsection `pdb'


@ref{232,,pdb.set_trace()} now takes an optional `header' keyword-only
argument.  If given, it is printed to the console just before debugging
begins.  (Contributed by Barry Warsaw in bpo-31389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31389}.)

@ref{a4,,pdb} command line now accepts @code{-m module_name} as an alternative to
script file.  (Contributed by Mario Corchero in bpo-32206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32206}.)

@node py_compile<3>,pydoc<2>,pdb<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 py-compile}@anchor{b55}
@subsubsection @code{py_compile}


@ref{a13,,py_compile.compile()} -- and by extension, @ref{20,,compileall} -- now
respects the 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable by
unconditionally creating @code{.pyc} files for hash-based validation.
This allows for guaranteeing
reproducible builds@footnote{https://reproducible-builds.org/} of @code{.pyc}
files when they are created eagerly. (Contributed by Bernhard M. Wiedemann
in bpo-29708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29708}.)

@node pydoc<2>,queue<2>,py_compile<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 pydoc}@anchor{b56}
@subsubsection `pydoc'


The pydoc server can now bind to an arbitrary hostname specified by the
new @code{-n} command-line argument.
(Contributed by Feanil Patel in bpo-31128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31128}.)

@node queue<2>,re<4>,pydoc<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 queue}@anchor{b57}
@subsubsection queue


The new @ref{b58,,SimpleQueue} class is an unbounded @abbr{FIFO} queue.
(Contributed by Antoine Pitrou in bpo-14976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14976}.)

@node re<4>,signal<2>,queue<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 re}@anchor{b59}
@subsubsection @code{re}


The flags @ref{617,,re.ASCII}, @ref{b5a,,re.LOCALE} and @ref{b5b,,re.UNICODE}
can be set within the scope of a group.
(Contributed by Serhiy Storchaka in bpo-31690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31690}.)

@ref{29f,,re.split()} now supports splitting on a pattern like @code{r'\b'},
@code{'^$'} or @code{(?=-)} that matches an empty string.
(Contributed by Serhiy Storchaka in bpo-25054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25054}.)

Regular expressions compiled with the @ref{b5a,,re.LOCALE} flag no longer
depend on the locale at compile time.  Locale settings are applied only
when the compiled regular expression is used.
(Contributed by Serhiy Storchaka in bpo-30215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30215}.)

@ref{40b,,FutureWarning} is now emitted if a regular expression contains
character set constructs that will change semantically in the future,
such as nested sets and set operations.
(Contributed by Serhiy Storchaka in bpo-30349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30349}.)

Compiled regular expression and match objects can now be copied
using @ref{51d,,copy.copy()} and @ref{b5c,,copy.deepcopy()}.
(Contributed by Serhiy Storchaka in bpo-10076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10076}.)

@node signal<2>,socket<5>,re<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 signal}@anchor{b5d}
@subsubsection `signal'


The new `warn_on_full_buffer' argument to the @ref{b5e,,signal.set_wakeup_fd()}
function makes it possible to specify whether Python prints a warning on
stderr when the wakeup buffer overflows.
(Contributed by Nathaniel J. Smith in bpo-30050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30050}.)

@node socket<5>,socketserver,signal<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 socket}@anchor{b5f}
@subsubsection `socket'


The new @ref{b60,,socket.getblocking()} method
returns @code{True} if the socket is in blocking mode and @code{False} otherwise.
(Contributed by Yury Selivanov in bpo-32373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32373}.)

The new @ref{b61,,socket.close()} function closes the passed socket file descriptor.
This function should be used instead of @ref{b62,,os.close()} for better
compatibility across platforms.
(Contributed by Christian Heimes in bpo-32454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32454}.)

The @ref{cb,,socket} module now exposes the @code{socket.TCP_CONGESTION}
(Linux 2.6.13), @code{socket.TCP_USER_TIMEOUT} (Linux 2.6.37), and
@code{socket.TCP_NOTSENT_LOWAT} (Linux 3.12) constants.
(Contributed by Omar Sandoval in bpo-26273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26273} and
Nathaniel J. Smith in bpo-29728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29728}.)

Support for @ref{b63,,socket.AF_VSOCK} sockets has been added to allow
communication between virtual machines and their hosts.
(Contributed by Cathy Avery in bpo-27584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27584}.)

Sockets now auto-detect family, type and protocol from file descriptor
by default.
(Contributed by Christian Heimes in bpo-28134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28134}.)

@node socketserver,sqlite3<6>,socket<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 socketserver}@anchor{b64}
@subsubsection socketserver


@code{socketserver.ThreadingMixIn.server_close()} now waits until all non-daemon
threads complete. @code{socketserver.ForkingMixIn.server_close()} now waits
until all child processes complete.

Add a new @code{socketserver.ForkingMixIn.block_on_close} class attribute to
@ref{b65,,socketserver.ForkingMixIn} and @ref{b66,,socketserver.ThreadingMixIn}
classes. Set the class attribute to @code{False} to get the pre-3.7 behaviour.

@node sqlite3<6>,ssl<5>,socketserver,Modules améliorés<7>
@anchor{whatsnew/3 7 sqlite3}@anchor{b67}
@subsubsection @code{sqlite3}


@ref{242,,sqlite3.Connection} now exposes the @ref{b68,,backup()}
method when the underlying SQLite library is at version 3.6.11 or higher.
(Contributed by Lele Gaifax in bpo-27645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27645}.)

The `database' argument of @ref{2a5,,sqlite3.connect()} now accepts any
@ref{29d,,path-like object}, instead of just a string.
(Contributed by Anders Lorentsen in bpo-31843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31843}.)

@node ssl<5>,string<2>,sqlite3<6>,Modules améliorés<7>
@anchor{whatsnew/3 7 ssl}@anchor{b69}
@subsubsection @code{ssl}


The @ref{cf,,ssl} module now uses OpenSSL's builtin API instead of
@code{match_hostname()} to check a host name or an IP address.  Values
are validated during TLS handshake.  Any certificate validation error
including failing the host name check now raises
@ref{b6a,,SSLCertVerificationError} and aborts the handshake with a proper
TLS Alert message.  The new exception contains additional information.
Host name validation can be customized with
@ref{b6b,,SSLContext.hostname_checks_common_name}.
(Contributed by Christian Heimes in bpo-31399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31399}.)

@cartouche
@quotation Note 
The improved host name check requires a `libssl' implementation compatible
with OpenSSL 1.0.2 or 1.1.  Consequently, OpenSSL 0.9.8 and 1.0.1 are no
longer supported (see @ref{b6c,,Platform Support Removals} for more details).
The ssl module is mostly compatible with LibreSSL 2.7.2 and newer.
@end quotation
@end cartouche

The @code{ssl} module no longer sends IP addresses in SNI TLS extension.
(Contributed by Christian Heimes in bpo-32185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32185}.)

@code{match_hostname()} no longer supports partial wildcards like
@code{www*.example.org}.
(Contributed by Mandeep Singh in bpo-23033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23033} and Christian Heimes in
bpo-31399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31399}.)

The default cipher suite selection of the @code{ssl} module now uses a blacklist
approach rather than a hard-coded whitelist.  Python no longer re-enables
ciphers that have been blocked by OpenSSL security updates.  Default cipher
suite selection can be configured at compile time.
(Contributed by Christian Heimes in bpo-31429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31429}.)

Validation of server certificates containing internationalized domain names
(IDNs) is now supported.  As part of this change, the
@ref{b6d,,SSLSocket.server_hostname} attribute
now stores the expected hostname in A-label form (@code{"xn--pythn-mua.org"}),
rather than the U-label form (@code{"pythön.org"}).  (Contributed by
Nathaniel J. Smith and Christian Heimes in bpo-28414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28414}.)

The @code{ssl} module has preliminary and experimental support for TLS 1.3 and
OpenSSL 1.1.1.  At the time of Python 3.7.0 release, OpenSSL 1.1.1 is still
under development and TLS 1.3 hasn't been finalized yet.  The TLS 1.3
handshake and protocol behaves slightly differently than TLS 1.2 and earlier,
see @ref{b6e,,TLS 1.3}.
(Contributed by Christian Heimes in bpo-32947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32947}, bpo-20995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20995},
bpo-29136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29136}, bpo-30622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30622} and bpo-33618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33618})

@ref{8d7,,SSLSocket} and @ref{b6f,,SSLObject} no longer have a public
constructor.  Direct instantiation was never a documented and supported
feature.  Instances must be created with @ref{291,,SSLContext} methods
@ref{50e,,wrap_socket()} and @ref{b70,,wrap_bio()}.
(Contributed by Christian Heimes in bpo-32951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32951})

OpenSSL 1.1 APIs for setting the minimum and maximum TLS protocol version are
available as @ref{85b,,SSLContext.minimum_version}
and @ref{85c,,SSLContext.maximum_version}.
Supported protocols are indicated by several new flags, such as
@ref{b71,,HAS_TLSv1_1}.
(Contributed by Christian Heimes in bpo-32609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32609}.)

Added @ref{a1f,,ssl.SSLContext.post_handshake_auth} to enable and
@ref{a20,,ssl.SSLSocket.verify_client_post_handshake()} to initiate TLS 1.3
post-handshake authentication.
(Contributed by Christian Heimes in gh-78851@footnote{https://github.com/python/cpython/issues/78851}.)

@node string<2>,subprocess<2>,ssl<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 string}@anchor{b72}
@subsubsection `string'


@ref{672,,string.Template} now lets you to optionally modify the regular
expression pattern for braced placeholders and non-braced placeholders
separately.  (Contributed by Barry Warsaw in bpo-1198569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1198569}.)

@node subprocess<2>,sys<8>,string<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 subprocess}@anchor{b73}
@subsubsection subprocess


The @ref{b74,,subprocess.run()} function accepts the new `capture_output'
keyword argument.  When true, stdout and stderr will be captured.
This is equivalent to passing @ref{b75,,subprocess.PIPE} as `stdout' and
`stderr' arguments.
(Contributed by Bo Bayles in bpo-32102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32102}.)

The @code{subprocess.run} function and the @ref{197,,subprocess.Popen} constructor
now accept the `text' keyword argument as an alias
to `universal_newlines'.
(Contributed by Andrew Clegg in bpo-31756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31756}.)

On Windows the default for `close_fds' was changed from @code{False} to
@code{True} when redirecting the standard handles.  It's now possible to set
`close_fds' to true when redirecting the standard handles.  See
@ref{197,,subprocess.Popen}.  This means that `close_fds' now defaults to
@code{True} on all supported platforms.
(Contributed by Segev Finer in bpo-19764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19764}.)

The subprocess module is now more graceful when handling
@ref{9bf,,KeyboardInterrupt} during @ref{b76,,subprocess.call()},
@ref{b74,,subprocess.run()}, or in a @ref{197,,Popen}
context manager.  It now waits a short amount of time for the child
to exit, before continuing the handling of the @code{KeyboardInterrupt}
exception.
(Contributed by Gregory P. Smith in bpo-25942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25942}.)

@node sys<8>,time<5>,subprocess<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 sys}@anchor{b77}
@subsubsection sys


The new @ref{ac8,,sys.breakpointhook()} hook function is called by the
built-in @ref{231,,breakpoint()}.
(Contributed by Barry Warsaw in bpo-31353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31353}.)

On Android, the new @ref{b78,,sys.getandroidapilevel()} returns the build-time
Android API version.
(Contributed by Victor Stinner in bpo-28740@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28740}.)

The new @ref{b79,,sys.get_coroutine_origin_tracking_depth()} function returns
the current coroutine origin tracking depth, as set by
the new @ref{b7a,,sys.set_coroutine_origin_tracking_depth()}.  @ref{a,,asyncio}
has been converted to use this new API instead of
the deprecated @code{sys.set_coroutine_wrapper()}.
(Contributed by Nathaniel J. Smith in bpo-32591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32591}.)

@node time<5>,tkinter<5>,sys<8>,Modules améliorés<7>
@anchor{whatsnew/3 7 time}@anchor{b7b}
@subsubsection time


@geindex Python Enhancement Proposals; PEP 564
PEP 564@footnote{https://peps.python.org/pep-0564/} adds six new functions with nanosecond resolution to the
@ref{ed,,time} module:


@itemize *

@item 
@ref{ad0,,time.clock_gettime_ns()}

@item 
@ref{ad1,,time.clock_settime_ns()}

@item 
@ref{ad2,,time.monotonic_ns()}

@item 
@ref{ad3,,time.perf_counter_ns()}

@item 
@ref{ad4,,time.process_time_ns()}

@item 
@ref{ad5,,time.time_ns()}
@end itemize

New clock identifiers have been added:


@itemize *

@item 
@ref{b7c,,time.CLOCK_BOOTTIME} (Linux): Identical to
@ref{684,,time.CLOCK_MONOTONIC}, except it also includes any time that the
system is suspended.

@item 
@ref{b7d,,time.CLOCK_PROF} (FreeBSD, NetBSD and OpenBSD): High-resolution
per-process CPU timer.

@item 
@ref{b7e,,time.CLOCK_UPTIME} (FreeBSD, OpenBSD): Time whose absolute value is
the time the system has been running and not suspended, providing accurate
uptime measurement.
@end itemize

The new @ref{923,,time.thread_time()} and @ref{b7f,,time.thread_time_ns()} functions
can be used to get per-thread CPU time measurements.
(Contributed by Antoine Pitrou in bpo-32025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32025}.)

The new @ref{b80,,time.pthread_getcpuclockid()} function returns the clock ID
of the thread-specific CPU-time clock.

@node tkinter<5>,tracemalloc<2>,time<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 tkinter}@anchor{b81}
@subsubsection tkinter


The new @ref{b82,,tkinter.ttk.Spinbox} class is now available.
(Contributed by Alan Moore in bpo-32585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32585}.)

@node tracemalloc<2>,types<4>,tkinter<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 tracemalloc}@anchor{b83}
@subsubsection tracemalloc


@ref{b84,,tracemalloc.Traceback} behaves more like regular tracebacks,
sorting the frames from oldest to most recent.
@ref{b85,,Traceback.format()}
now accepts negative `limit', truncating the result to the
@code{abs(limit)} oldest frames.  To get the old behaviour, use
the new `most_recent_first' argument to @code{Traceback.format()}.
(Contributed by Jesse Bakker in bpo-32121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32121}.)

@node types<4>,unicodedata<6>,tracemalloc<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 types}@anchor{b86}
@subsubsection @code{types}


The new @ref{b87,,WrapperDescriptorType},
@ref{636,,MethodWrapperType}, @ref{b88,,MethodDescriptorType},
and @ref{b89,,ClassMethodDescriptorType} classes are now available.
(Contributed by Manuel Krebber and Guido van Rossum in bpo-29377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29377},
and Serhiy Storchaka in bpo-32265@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32265}.)

The new @ref{b8a,,types.resolve_bases()} function resolves MRO entries
dynamically as specified by 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}.
(Contributed by Ivan Levkivskyi in bpo-32717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32717}.)

@node unicodedata<6>,unittest<7>,types<4>,Modules améliorés<7>
@anchor{whatsnew/3 7 unicodedata}@anchor{b8b}
@subsubsection unicodedata


The internal @ref{104,,unicodedata} database has been upgraded to use Unicode 11@footnote{https://www.unicode.org/versions/Unicode11.0.0/}. (Contributed by Benjamin
Peterson.)

@node unittest<7>,unittest mock,unicodedata<6>,Modules améliorés<7>
@anchor{whatsnew/3 7 unittest}@anchor{b8c}
@subsubsection unittest


The new @code{-k} command-line option allows filtering tests by a name
substring or a Unix shell-like pattern.
For example, @code{python -m unittest -k foo} runs
@code{foo_tests.SomeTest.test_something}, @code{bar_tests.SomeTest.test_foo},
but not @code{bar_tests.FooTest.test_something}.
(Contributed by Jonas Haag in bpo-32071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32071}.)

@node unittest mock,urllib parse<5>,unittest<7>,Modules améliorés<7>
@anchor{whatsnew/3 7 unittest-mock}@anchor{b8d}
@subsubsection unittest.mock


The @ref{b8e,,sentinel} attributes now preserve their identity
when they are @ref{25,,copied} or @ref{a5,,pickled}. (Contributed by
Serhiy Storchaka in bpo-20804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20804}.)

The new @ref{b8f,,seal()} function allows sealing
@ref{a3a,,Mock} instances, which will disallow further creation
of attribute mocks.  The seal is applied recursively to all attributes that
are themselves mocks.
(Contributed by Mario Corchero in bpo-30541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30541}.)

@node urllib parse<5>,uu,unittest mock,Modules améliorés<7>
@anchor{whatsnew/3 7 urllib-parse}@anchor{b90}
@subsubsection urllib.parse


@ref{b91,,urllib.parse.quote()} has been updated from 
@geindex RFC; RFC 2396
RFC 2396@footnote{https://datatracker.ietf.org/doc/html/rfc2396.html} to 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html},
adding @code{~} to the set of characters that are never quoted by default.
(Contributed by Christian Theune and Ratnadeep Debnath in bpo-16285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16285}.)

@node uu,uuid<2>,urllib parse<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 uu}@anchor{b92}
@subsubsection uu


The @code{uu.encode()} function now accepts an optional `backtick'
keyword argument.  When it's true, zeros are represented by @code{'`'}
instead of spaces.  (Contributed by Xiang Zhang in bpo-30103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30103}.)

@node uuid<2>,warnings<3>,uu,Modules améliorés<7>
@anchor{whatsnew/3 7 uuid}@anchor{b93}
@subsubsection uuid


The new @ref{b94,,UUID.is_safe} attribute relays information
from the platform about whether generated UUIDs are generated with a
multiprocessing-safe method.
(Contributed by Barry Warsaw in bpo-22807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22807}.)

@ref{b95,,uuid.getnode()} now prefers universally administered
MAC addresses over locally administered MAC addresses.
This makes a better guarantee for global uniqueness of UUIDs returned
from @ref{b96,,uuid.uuid1()}.  If only locally administered MAC addresses are
available, the first such one found is returned.
(Contributed by Barry Warsaw in bpo-32107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32107}.)

@node warnings<3>,xml<5>,uuid<2>,Modules améliorés<7>
@anchor{whatsnew/3 7 warnings}@anchor{b97}
@subsubsection warnings


The initialization of the default warnings filters has changed as follows:


@itemize *

@item 
warnings enabled via command line options (including those for @ref{5cd,,-b}
and the new CPython-specific @ref{175,,-X} @code{dev} option) are always passed
to the warnings machinery via the @ref{3a7,,sys.warnoptions} attribute.

@item 
warnings filters enabled via the command line or the environment now have the
following order of precedence:


@itemize *

@item 
the @code{BytesWarning} filter for @ref{5cd,,-b} (or @code{-bb})

@item 
any filters specified with the @ref{8b4,,-W} option

@item 
any filters specified with the 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS} environment
variable

@item 
any other CPython specific filters (e.g. the @code{default} filter added
for the new @code{-X dev} mode)

@item 
any implicit filters defined directly by the warnings machinery
@end itemize

@item 
in @ref{1f6,,CPython debug builds}, all warnings are now displayed
by default (the implicit filter list is empty)
@end itemize

(Contributed by Nick Coghlan and Victor Stinner in bpo-20361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20361},
bpo-32043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32043}, and bpo-32230@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32230}.)

Deprecation warnings are once again shown by default in single-file scripts and
at the interactive prompt.  See @ref{abb,,PEP 565; Show DeprecationWarning in __main__} for details.
(Contributed by Nick Coghlan in bpo-31975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31975}.)

@node xml<5>,xml etree,warnings<3>,Modules améliorés<7>
@anchor{whatsnew/3 7 xml}@anchor{b99}
@subsubsection `xml'


As mitigation against DTD and external entity retrieval, the
@ref{121,,xml.dom.minidom} and @ref{128,,xml.sax} modules no longer process
external entities by default.
(Contributed by Christian Heimes in gh-61441@footnote{https://github.com/python/cpython/issues/61441}.)

@node xml etree,xmlrpc server,xml<5>,Modules améliorés<7>
@anchor{whatsnew/3 7 xml-etree}@anchor{b9a}
@subsubsection xml.etree


@ref{b9b,,ElementPath} predicates in the @code{find()}
methods can now compare text of the current node with @code{[. = "text"]},
not only text in children.  Predicates also allow adding spaces for
better readability.  (Contributed by Stefan Behnel in bpo-31648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31648}.)

@node xmlrpc server,zipapp,xml etree,Modules améliorés<7>
@anchor{whatsnew/3 7 xmlrpc-server}@anchor{b9c}
@subsubsection xmlrpc.server


@code{SimpleXMLRPCDispatcher.register_function}
can now be used as a decorator.  (Contributed by Xiang Zhang in
bpo-7769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7769}.)

@node zipapp,zipfile<2>,xmlrpc server,Modules améliorés<7>
@anchor{whatsnew/3 7 zipapp}@anchor{b9d}
@subsubsection zipapp


Function @ref{b9e,,create_archive()} now accepts an optional `filter'
argument to allow the user to select which files should be included in the
archive.  (Contributed by Irmen de Jong in bpo-31072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31072}.)

Function @ref{b9e,,create_archive()} now accepts an optional `compressed'
argument to generate a compressed archive.  A command line option
@code{--compress} has also been added to support compression.
(Contributed by Zhiming Wang in bpo-31638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31638}.)

@node zipfile<2>,,zipapp,Modules améliorés<7>
@anchor{whatsnew/3 7 zipfile}@anchor{b9f}
@subsubsection zipfile


@ref{6af,,ZipFile} now accepts the new `compresslevel' parameter to
control the compression level.
(Contributed by Bo Bayles in bpo-21417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21417}.)

Subdirectories in archives created by @code{ZipFile} are now stored in
alphabetical order.
(Contributed by Bernhard M. Wiedemann in bpo-30693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30693}.)

@node Changements à l'API C<6>,Changements à la compilation<6>,Modules améliorés<7>,What's New In Python 3 7
@anchor{whatsnew/3 7 c-api-changes}@anchor{ba0}
@subsection Changements à l'API C


A new API for thread-local storage has been implemented.  See
@ref{abc,,PEP 539; New C API for Thread-Local Storage} for an overview and
@ref{acc,,Thread Specific Storage (TSS) API} for a complete reference.
(Contributed by Masayuki Yamamoto in bpo-25658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25658}.)

The new @ref{aae,,context variables} functionality
exposes a number of @ref{ae6,,new C APIs}.

The new @ref{ba1,,PyImport_GetModule()} function returns the previously
imported module with the given name.
(Contributed by Eric Snow in bpo-28411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28411}.)

The new @ref{ba2,,Py_RETURN_RICHCOMPARE} macro eases writing rich
comparison functions.
(Contributed by Petr Victorin in bpo-23699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23699}.)

The new @ref{ba3,,Py_UNREACHABLE} macro can be used to mark unreachable
code paths.
(Contributed by Barry Warsaw in bpo-31338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31338}.)

The @ref{fe,,tracemalloc} now exposes a C API through the new
@ref{ba4,,PyTraceMalloc_Track()} and @ref{ba5,,PyTraceMalloc_Untrack()}
functions.
(Contributed by Victor Stinner in bpo-30054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30054}.)

The new @code{import__find__load__start()} and
@code{import__find__load__done()} static markers can be used to trace
module imports.
(Contributed by Christian Heimes in bpo-31574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31574}.)

The fields @code{name} and @code{doc} of structures
@ref{53a,,PyMemberDef}, @ref{ba6,,PyGetSetDef},
@ref{ba7,,PyStructSequence_Field}, @ref{ba8,,PyStructSequence_Desc},
and @code{wrapperbase} are now of type @code{const char *} rather of
@code{char *}.  (Contributed by Serhiy Storchaka in bpo-28761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28761}.)

The result of @ref{885,,PyUnicode_AsUTF8AndSize()} and @ref{ba9,,PyUnicode_AsUTF8()}
is now of type @code{const char *} rather of @code{char *}. (Contributed by Serhiy
Storchaka in bpo-28769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28769}.)

The result of @ref{baa,,PyMapping_Keys()}, @ref{bab,,PyMapping_Values()} and
@ref{bac,,PyMapping_Items()} is now always a list, rather than a list or a
tuple. (Contributed by Oren Milman in bpo-28280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28280}.)

Added functions @ref{3f3,,PySlice_Unpack()} and @ref{3f4,,PySlice_AdjustIndices()}.
(Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@ref{3f0,,PyOS_AfterFork()} is deprecated in favour of the new functions
@ref{bad,,PyOS_BeforeFork()}, @ref{bae,,PyOS_AfterFork_Parent()} and
@ref{3f1,,PyOS_AfterFork_Child()}.  (Contributed by Antoine Pitrou in
bpo-16500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16500}.)

The @code{PyExc_RecursionErrorInst} singleton that was part of the public API
has been removed as its members being never cleared may cause a segfault
during finalization of the interpreter. Contributed by Xavier de Gaye in
bpo-22898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22898} and bpo-30697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30697}.

Added C API support for timezones with timezone constructors
@ref{baf,,PyTimeZone_FromOffset()} and @ref{bb0,,PyTimeZone_FromOffsetAndName()},
and access to the UTC singleton with @ref{bb1,,PyDateTime_TimeZone_UTC}.
Contributed by Paul Ganssle in bpo-10381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10381}.

The type of results of @code{PyThread_start_new_thread()} and
@code{PyThread_get_thread_ident()}, and the `id' parameter of
@ref{bb2,,PyThreadState_SetAsyncExc()} changed from long to
unsigned long.
(Contributed by Serhiy Storchaka in bpo-6532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6532}.)

@ref{8a9,,PyUnicode_AsWideCharString()} now raises a @ref{1ff,,ValueError} if the
second argument is @code{NULL} and the wchar_t* string contains null
characters.  (Contributed by Serhiy Storchaka in bpo-30708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30708}.)

Changes to the startup sequence and the management of dynamic memory
allocators mean that the long documented requirement to call
@ref{899,,Py_Initialize()} before calling most C API functions is now
relied on more heavily, and failing to abide by it may lead to segfaults in
embedding applications. See the @ref{abf,,Porting to Python 3.7} section in this
document and the @ref{bb3,,Before Python Initialization} section in the C API documentation
for more details.

The new @ref{bb4,,PyInterpreterState_GetID()} returns the unique ID for a
given interpreter.
(Contributed by Eric Snow in bpo-29102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29102}.)

@ref{bb5,,Py_DecodeLocale()}, @ref{bb6,,Py_EncodeLocale()} now use the UTF-8
encoding when the @ref{ab8,,UTF-8 mode} is enabled.
(Contributed by Victor Stinner in bpo-29240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29240}.)

@ref{bb7,,PyUnicode_DecodeLocaleAndSize()} and @ref{bb8,,PyUnicode_EncodeLocale()}
now use the current locale encoding for @code{surrogateescape} error handler.
(Contributed by Victor Stinner in bpo-29240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29240}.)

The `start' and `end' parameters of @ref{8a6,,PyUnicode_FindChar()} are
now adjusted to behave like string slices.
(Contributed by Xiang Zhang in bpo-28822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28822}.)

@node Changements à la compilation<6>,Optimizations<2>,Changements à l'API C<6>,What's New In Python 3 7
@anchor{whatsnew/3 7 build-changes}@anchor{bb9}
@subsection Changements à la compilation


Support for building @code{--without-threads} has been removed.  The
@ref{ec,,threading} module is now always available.
(Contributed by Antoine Pitrou in bpo-31370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31370}.).

A full copy of libffi is no longer bundled for use when building the
@ref{2a,,_ctypes} module on non-OSX UNIX platforms.  An installed copy
of libffi is now required when building @code{_ctypes} on such platforms.
(Contributed by Zachary Ware in bpo-27979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27979}.)

The Windows build process no longer depends on Subversion to pull in external
sources, a Python script is used to download zipfiles from GitHub instead.
If Python 3.6 is not found on the system (via @code{py -3.6}), NuGet is used to
download a copy of 32-bit Python for this purpose.  (Contributed by Zachary
Ware in bpo-30450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30450}.)

The @ref{cf,,ssl} module requires OpenSSL 1.0.2 or 1.1 compatible libssl.
OpenSSL 1.0.1 has reached end of lifetime on 2016-12-31 and is no longer
supported. LibreSSL is temporarily not supported as well. LibreSSL releases
up to version 2.6.4 are missing required OpenSSL 1.0.2 APIs.

@node Optimizations<2>,Autres changements à l'implémentation de CPython<2>,Changements à la compilation<6>,What's New In Python 3 7
@anchor{whatsnew/3 7 optimizations}@anchor{bba}@anchor{whatsnew/3 7 whatsnew37-perf}@anchor{abe}
@subsection Optimizations


The overhead of calling many methods of various standard library classes
implemented in C has been significantly reduced by porting more code
to use the @code{METH_FASTCALL} convention.
(Contributed by Victor Stinner in bpo-29300@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29300}, bpo-29507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29507},
bpo-29452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29452}, and bpo-29286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29286}.)

Various optimizations have reduced Python startup time by 10% on Linux and
up to 30% on macOS.
(Contributed by Victor Stinner, INADA Naoki in bpo-29585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29585}, and
Ivan Levkivskyi in bpo-31333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31333}.)

Method calls are now up to 20% faster due to the bytecode changes which
avoid creating bound method instances.
(Contributed by Yury Selivanov and INADA Naoki in bpo-26110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26110}.)
@anchor{whatsnew/3 7 whatsnew37-asyncio-perf}@anchor{af0}
The @ref{a,,asyncio} module received a number of notable optimizations for
commonly used functions:


@itemize *

@item 
The @ref{2bf,,asyncio.get_event_loop()} function has been reimplemented in C to
make it up to 15 times faster.
(Contributed by Yury Selivanov in bpo-32296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32296}.)

@item 
@ref{bbb,,asyncio.Future} callback management has been optimized.
(Contributed by Yury Selivanov in bpo-32348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32348}.)

@item 
@ref{5e8,,asyncio.gather()} is now up to 15% faster.
(Contributed by Yury Selivanov in bpo-32355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32355}.)

@item 
@ref{a5d,,asyncio.sleep()} is now up to 2 times faster when the `delay'
argument is zero or negative.
(Contributed by Andrew Svetlov in bpo-32351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32351}.)

@item 
The performance overhead of asyncio debug mode has been reduced.
(Contributed by Antoine Pitrou in bpo-31970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31970}.)
@end itemize

As a result of @ref{ab3,,PEP 560 work}, the import time
of @ref{103,,typing} has been reduced by a factor of 7, and many typing operations
are now faster.
(Contributed by Ivan Levkivskyi in bpo-32226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32226}.)

@ref{bbc,,sorted()} and @ref{bbd,,list.sort()} have been optimized for common cases
to be up to 40-75% faster.
(Contributed by Elliot Gorokhovsky in bpo-28685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28685}.)

@ref{bbe,,dict.copy()} is now up to 5.5 times faster.
(Contributed by Yury Selivanov in bpo-31179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31179}.)

@ref{4bb,,hasattr()} and @ref{bbf,,getattr()} are now about 4 times faster when
`name' is not found and `obj' does not override @ref{4bc,,object.__getattr__()}
or @ref{bc0,,object.__getattribute__()}.
(Contributed by INADA Naoki in bpo-32544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32544}.)

Searching for certain Unicode characters (like Ukrainian capital "Є")
in a string was up to 25 times slower than searching for other characters.
It is now only 3 times slower in the worst case.
(Contributed by Serhiy Storchaka in bpo-24821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24821}.)

The @ref{1c5,,collections.namedtuple()} factory has been reimplemented to
make the creation of named tuples 4 to 6 times faster.
(Contributed by Jelle Zijlstra with further improvements by INADA Naoki,
Serhiy Storchaka, and Raymond Hettinger in bpo-28638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28638}.)

@code{date.fromordinal()} and @code{date.fromtimestamp()} are now up to
30% faster in the common case.
(Contributed by Paul Ganssle in bpo-32403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32403}.)

The @ref{b49,,os.fwalk()} function is now up to 2 times faster thanks to
the use of @ref{a4d,,os.scandir()}.
(Contributed by Serhiy Storchaka in bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}.)

The speed of the @ref{2f5,,shutil.rmtree()} function has been improved by
20--40% thanks to the use of the @ref{a4d,,os.scandir()} function.
(Contributed by Serhiy Storchaka in bpo-28564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28564}.)

Optimized case-insensitive matching and searching of @ref{b8,,regular expressions}.  Searching some patterns can now be up to 20 times faster.
(Contributed by Serhiy Storchaka in bpo-30285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30285}.)

@ref{bc1,,re.compile()} now converts @code{flags} parameter to int object if
it is @code{RegexFlag}.  It is now as fast as Python 3.5, and faster than
Python 3.6 by about 10% depending on the pattern.
(Contributed by INADA Naoki in bpo-31671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31671}.)

The @ref{bc2,,modify()} methods of classes
@ref{bc3,,selectors.EpollSelector}, @ref{bc4,,selectors.PollSelector}
and @ref{bc5,,selectors.DevpollSelector} may be around 10% faster under
heavy loads.  (Contributed by Giampaolo Rodola' in bpo-30014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30014})

Constant folding has been moved from the peephole optimizer to the new AST
optimizer, which is able perform optimizations more consistently.
(Contributed by Eugene Toder and INADA Naoki in bpo-29469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29469} and
bpo-11549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11549}.)

Most functions and methods in @ref{4,,abc} have been rewritten in C.
This makes creation of abstract base classes, and calling @ref{42b,,isinstance()}
and @ref{7ab,,issubclass()} on them 1.5x faster.  This also reduces Python
start-up time by up to 10%. (Contributed by Ivan Levkivskyi and INADA Naoki
in bpo-31333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31333})

Significant speed improvements to alternate constructors for
@ref{1c8,,datetime.date} and @ref{1c7,,datetime.datetime} by using fast-path
constructors when not constructing subclasses. (Contributed by Paul Ganssle
in bpo-32403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32403})

The speed of comparison of @ref{19e,,array.array} instances has been
improved considerably in certain cases.  It is now from 10x to 70x faster
when comparing arrays holding values of the same integer type.
(Contributed by Adrian Wielgosik in bpo-24700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24700}.)

The @ref{bc6,,math.erf()} and @ref{bc7,,math.erfc()} functions now use the (faster)
C library implementation on most platforms.
(Contributed by Serhiy Storchaka in bpo-26121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26121}.)

@node Autres changements à l'implémentation de CPython<2>,Deprecated Python Behavior,Optimizations<2>,What's New In Python 3 7
@anchor{whatsnew/3 7 other-cpython-implementation-changes}@anchor{bc8}
@subsection Autres changements à l'implémentation de CPython



@itemize *

@item 
Trace hooks may now opt out of receiving the @code{line} and opt into receiving
the @code{opcode} events from the interpreter by setting the corresponding new
@ref{bc9,,f_trace_lines} and @ref{bca,,f_trace_opcodes} attributes on the
frame being traced. (Contributed by Nick Coghlan in bpo-31344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31344}.)

@item 
Fixed some consistency problems with namespace package module attributes.
Namespace module objects now have an @code{__file__} that is set to @code{None}
(previously unset), and their @code{__spec__.origin} is also set to @code{None}
(previously the string @code{"namespace"}).  See bpo-32305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32305}.  Also, the
namespace module object's @code{__spec__.loader} is set to the same value as
@code{__loader__} (previously, the former was set to @code{None}).  See
bpo-32303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32303}.

@item 
The @ref{140,,locals()} dictionary now displays in the lexical order that
variables were defined.  Previously, the order was undefined.
(Contributed by Raymond Hettinger in bpo-32690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32690}.)

@item 
The @code{distutils} @code{upload} command no longer tries to change CR
end-of-line characters to CRLF.  This fixes a corruption issue with sdists
that ended with a byte equivalent to CR.
(Contributed by Bo Bayles in bpo-32304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32304}.)
@end itemize

@node Deprecated Python Behavior,Deprecated Python modules functions and methods,Autres changements à l'implémentation de CPython<2>,What's New In Python 3 7
@anchor{whatsnew/3 7 deprecated-python-behavior}@anchor{bcb}
@subsection Deprecated Python Behavior


Yield expressions (both @code{yield} and @code{yield from} clauses) are now deprecated
in comprehensions and generator expressions (aside from the iterable expression
in the leftmost @code{for} clause). This ensures that comprehensions
always immediately return a container of the appropriate type (rather than
potentially returning a @ref{bcc,,generator iterator} object), while generator
expressions won't attempt to interleave their implicit output with the output
from any explicit yield expressions.  In Python 3.7, such expressions emit
@ref{1a3,,DeprecationWarning} when compiled, in Python 3.8 this will be a
@ref{18b,,SyntaxError}.
(Contributed by Serhiy Storchaka in bpo-10544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10544}.)

Returning a subclass of @ref{2ec,,complex} from @ref{5d1,,object.__complex__()} is
deprecated and will be an error in future Python versions.  This makes
@code{__complex__()} consistent with @ref{706,,object.__int__()} and
@ref{9ba,,object.__float__()}.
(Contributed by Serhiy Storchaka in bpo-28894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28894}.)

@node Deprecated Python modules functions and methods,Deprecated functions and types of the C API,Deprecated Python Behavior,What's New In Python 3 7
@anchor{whatsnew/3 7 deprecated-python-modules-functions-and-methods}@anchor{bcd}
@subsection Deprecated Python modules, functions and methods


@menu
* aifc:: 
* asyncio: asyncio<8>. 
* collections: collections<3>. 
* dbm: dbm<3>. 
* enum: enum<6>. 
* gettext: gettext<2>. 
* importlib: importlib<5>. 
* locale: locale<5>. 
* macpath:: 
* threading: threading<5>. 
* socket: socket<6>. 
* ssl: ssl<6>. 
* sunau:: 
* sys: sys<9>. 
* wave:: 

@end menu

@node aifc,asyncio<8>,,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 aifc}@anchor{bce}
@subsubsection aifc


@code{aifc.openfp()} has been deprecated and will be removed in Python 3.9.
Use @code{aifc.open()} instead.
(Contributed by Brian Curtin in bpo-31985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31985}.)

@node asyncio<8>,collections<3>,aifc,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id2}@anchor{bcf}@anchor{whatsnew/3 7 whatsnew37-asyncio-deprecated}@anchor{b0d}
@subsubsection asyncio


Support for directly @code{await}-ing instances of @ref{a5f,,asyncio.Lock} and
other asyncio synchronization primitives has been deprecated.  An
asynchronous context manager must be used in order to acquire and release
the synchronization resource.
(Contributed by Andrew Svetlov in bpo-32253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32253}.)

The @code{asyncio.Task.current_task()} and @code{asyncio.Task.all_tasks()}
methods have been deprecated.
(Contributed by Andrew Svetlov in bpo-32250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32250}.)

@node collections<3>,dbm<3>,asyncio<8>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id3}@anchor{bd0}
@subsubsection collections


In Python 3.8, the abstract base classes in @ref{1e,,collections.abc} will no
longer be exposed in the regular @ref{1d,,collections} module.  This will help
create a clearer distinction between the concrete classes and the abstract
base classes.
(Contributed by Serhiy Storchaka in bpo-25988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25988}.)

@node dbm<3>,enum<6>,collections<3>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id4}@anchor{bd1}
@subsubsection dbm


@ref{32,,dbm.dumb} now supports reading read-only files and no longer writes the
index file when it is not changed.  A deprecation warning is now emitted
if the index file is missing and recreated in the @code{'r'} and @code{'w'}
modes (this will be an error in future Python releases).
(Contributed by Serhiy Storchaka in bpo-28847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28847}.)

@node enum<6>,gettext<2>,dbm<3>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id5}@anchor{bd2}
@subsubsection enum


In Python 3.8, attempting to check for non-Enum objects in @code{Enum}
classes will raise a @ref{522,,TypeError} (e.g. @code{1 in Color}); similarly,
attempting to check for non-Flag objects in a @code{Flag} member will
raise @ref{522,,TypeError} (e.g. @code{1 in Perm.RW}); currently, both operations
return @ref{b25,,False} instead.
(Contributed by Ethan Furman in bpo-33217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33217}.)

@node gettext<2>,importlib<5>,enum<6>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 gettext}@anchor{bd3}
@subsubsection gettext


Using non-integer value for selecting a plural form in @ref{62,,gettext} is
now deprecated.  It never correctly worked. (Contributed by Serhiy Storchaka
in bpo-28692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28692}.)

@node importlib<5>,locale<5>,gettext<2>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id6}@anchor{bd4}
@subsubsection importlib


Methods
@code{MetaPathFinder.find_module()}
(replaced by
@ref{853,,MetaPathFinder.find_spec()})
and
@code{PathEntryFinder.find_loader()}
(replaced by
@ref{857,,PathEntryFinder.find_spec()})
both deprecated in Python 3.4 now emit @ref{1a3,,DeprecationWarning}.
(Contributed by Matthias Bussonnier in bpo-29576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29576}.)

The @ref{bd5,,importlib.abc.ResourceLoader} ABC has been deprecated in
favour of @ref{aeb,,importlib.abc.ResourceReader}.

@node locale<5>,macpath,importlib<5>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id7}@anchor{bd6}
@subsubsection locale


@code{locale.format()} has been deprecated, use @ref{508,,locale.format_string()}
instead.  (Contributed by Garvit in bpo-10379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10379}.)

@node macpath,threading<5>,locale<5>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 macpath}@anchor{bd7}
@subsubsection macpath


The @code{macpath} is now deprecated and will be removed in Python 3.8.
(Contributed by Chi Hsuan Yen in bpo-9850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9850}.)

@node threading<5>,socket<6>,macpath,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 threading}@anchor{bd8}
@subsubsection threading


@code{dummy_threading} and @code{_dummy_thread} have been deprecated.  It is
no longer possible to build Python with threading disabled.
Use @ref{ec,,threading} instead.
(Contributed by Antoine Pitrou in bpo-31370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31370}.)

@node socket<6>,ssl<6>,threading<5>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id8}@anchor{bd9}
@subsubsection `socket'


The silent argument value truncation in @ref{86b,,socket.htons()} and
@ref{86c,,socket.ntohs()} has been deprecated.  In future versions of Python,
if the passed argument is larger than 16 bits, an exception will be raised.
(Contributed by Oren Milman in bpo-28332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28332}.)

@node ssl<6>,sunau,socket<6>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id9}@anchor{bda}
@subsubsection @code{ssl}


@code{ssl.wrap_socket()} is deprecated.  Use
@ref{50e,,ssl.SSLContext.wrap_socket()} instead.
(Contributed by Christian Heimes in bpo-28124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28124}.)

@node sunau,sys<9>,ssl<6>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 sunau}
@subsubsection sunau


@code{sunau.openfp()} has been deprecated and will be removed in Python 3.9.
Use @code{sunau.open()} instead.
(Contributed by Brian Curtin in bpo-31985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31985}.)

@node sys<9>,wave,sunau,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 id10}@anchor{bdc}
@subsubsection sys


Deprecated @code{sys.set_coroutine_wrapper()} and
@code{sys.get_coroutine_wrapper()}.

The undocumented @code{sys.callstats()} function has been deprecated and
will be removed in a future Python version.
(Contributed by Victor Stinner in bpo-28799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28799}.)

@node wave,,sys<9>,Deprecated Python modules functions and methods
@anchor{whatsnew/3 7 wave}@anchor{bdd}
@subsubsection wave


@code{wave.openfp()} has been deprecated and will be removed in Python 3.9.
Use @ref{938,,wave.open()} instead.
(Contributed by Brian Curtin in bpo-31985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31985}.)

@node Deprecated functions and types of the C API,Platform Support Removals,Deprecated Python modules functions and methods,What's New In Python 3 7
@anchor{whatsnew/3 7 deprecated-functions-and-types-of-the-c-api}@anchor{bde}
@subsection Deprecated functions and types of the C API


Function @ref{3f2,,PySlice_GetIndicesEx()} is deprecated and replaced with
a macro if @code{Py_LIMITED_API} is not set or set to a value in the range
between @code{0x03050400} and @code{0x03060000} (not inclusive), or is @code{0x03060100}
or higher.  (Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@ref{3f0,,PyOS_AfterFork()} has been deprecated.  Use @ref{bad,,PyOS_BeforeFork()},
@ref{bae,,PyOS_AfterFork_Parent()} or @ref{3f1,,PyOS_AfterFork_Child()} instead.
(Contributed by Antoine Pitrou in bpo-16500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16500}.)

@node Platform Support Removals,API and Feature Removals<2>,Deprecated functions and types of the C API,What's New In Python 3 7
@anchor{whatsnew/3 7 id11}@anchor{bdf}@anchor{whatsnew/3 7 platform-support-removals}@anchor{b6c}
@subsection Platform Support Removals



@itemize *

@item 
FreeBSD 9 and older are no longer officially supported.

@item 
For full Unicode support, including within extension modules, *nix platforms
are now expected to provide at least one of @code{C.UTF-8} (full locale),
@code{C.utf8} (full locale) or @code{UTF-8} (@code{LC_CTYPE}-only locale) as an
alternative to the legacy @code{ASCII}-based @code{C} locale.

@item 
OpenSSL 0.9.8 and 1.0.1 are no longer supported, which means building CPython
3.7 with SSL/TLS support on older platforms still using these versions
requires custom build options that link to a more recent version of OpenSSL.

Notably, this issue affects the Debian 8 (aka "jessie") and Ubuntu 14.04
(aka "Trusty") LTS Linux distributions, as they still use OpenSSL 1.0.1 by
default.

Debian 9 ("stretch") and Ubuntu 16.04 ("xenial"), as well as recent releases
of other LTS Linux releases (e.g. RHEL/CentOS 7.5, SLES 12-SP3), use OpenSSL
1.0.2 or later, and remain supported in the default build configuration.

CPython's own CI configuration file@footnote{https://github.com/python/cpython/blob/v3.7.13/.travis.yml} provides an
example of using the SSL
compatibility testing infrastructure@footnote{https://github.com/python/cpython/tree/3.13/Tools/ssl/multissltests.py} in
CPython's test suite to build and link against OpenSSL 1.1.0 rather than an
outdated system provided OpenSSL.
@end itemize

@node API and Feature Removals<2>,Module Removals,Platform Support Removals,What's New In Python 3 7
@anchor{whatsnew/3 7 api-and-feature-removals}@anchor{be0}
@subsection API and Feature Removals


The following features and APIs have been removed from Python 3.7:


@itemize *

@item 
The @code{os.stat_float_times()} function has been removed. It was introduced in
Python 2.3 for backward compatibility with Python 2.2, and was deprecated
since Python 3.1.

@item 
Unknown escapes consisting of @code{'\'} and an ASCII letter in replacement
templates for @ref{2a0,,re.sub()} were deprecated in Python 3.5, and will now
cause an error.

@item 
Removed support of the `exclude' argument in @ref{be1,,tarfile.TarFile.add()}.
It was deprecated in Python 2.7 and 3.2.  Use the `filter' argument instead.

@item 
The @code{ntpath.splitunc()} function was deprecated in
Python 3.1, and has now been removed.  Use @ref{be2,,splitdrive()}
instead.

@item 
@ref{1c5,,collections.namedtuple()} no longer supports the `verbose' parameter
or @code{_source} attribute which showed the generated source code for the
named tuple class.  This was part of an optimization designed to speed-up
class creation.  (Contributed by Jelle Zijlstra with further improvements
by INADA Naoki, Serhiy Storchaka, and Raymond Hettinger in bpo-28638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28638}.)

@item 
Functions @ref{451,,bool()}, @ref{2eb,,float()}, @ref{5fc,,list()} and @ref{366,,tuple()} no
longer take keyword arguments.  The first argument of @ref{254,,int()} can now
be passed only as positional argument.

@item 
Removed previously deprecated in Python 2.4 classes @code{Plist}, @code{Dict} and
@code{_InternalDict} in the @ref{aa,,plistlib} module.  Dict values in the result
of functions @code{readPlist()} and
@code{readPlistFromBytes()} are now normal dicts.  You no longer
can use attribute access to access items of these dictionaries.

@item 
The @code{asyncio.windows_utils.socketpair()} function has been
removed.  Use the @ref{be3,,socket.socketpair()} function instead,
it is available on all platforms since Python 3.5.
@code{asyncio.windows_utils.socketpair} was just an alias to
@code{socket.socketpair} on Python 3.5 and newer.

@item 
@ref{a,,asyncio} no longer exports the @ref{c1,,selectors} and
@code{_overlapped} modules as @code{asyncio.selectors} and
@code{asyncio._overlapped}. Replace @code{from asyncio import selectors} with
@code{import selectors}.

@item 
Direct instantiation of @ref{8d7,,ssl.SSLSocket} and @ref{b6f,,ssl.SSLObject}
objects is now prohibited. The constructors were never documented, tested,
or designed as public constructors.  Users were supposed to use
@code{ssl.wrap_socket()} or @ref{291,,ssl.SSLContext}.
(Contributed by Christian Heimes in bpo-32951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32951}.)

@item 
The unused @code{distutils} @code{install_misc} command has been removed.
(Contributed by Eric N. Vander Weele in bpo-29218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29218}.)
@end itemize

@node Module Removals,Windows-only Changes,API and Feature Removals<2>,What's New In Python 3 7
@anchor{whatsnew/3 7 module-removals}@anchor{be4}
@subsection Module Removals


The @code{fpectl} module has been removed.  It was never enabled by
default, never worked correctly on x86-64, and it changed the Python
ABI in ways that caused unexpected breakage of C extensions.
(Contributed by Nathaniel J. Smith in bpo-29137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29137}.)

@node Windows-only Changes,Porting to Python 3 7,Module Removals,What's New In Python 3 7
@anchor{whatsnew/3 7 windows-only-changes}@anchor{be5}
@subsection Windows-only Changes


The python launcher, (py.exe), can accept 32 & 64 bit specifiers `without'
having to specify a minor version as well. So @code{py -3-32} and @code{py -3-64}
become valid as well as @code{py -3.7-32}, also the -`m'-64 and -`m.n'-64 forms
are now accepted to force 64 bit python even if 32 bit would have otherwise
been used. If the specified version is not available py.exe will error exit.
(Contributed by Steve Barnes in bpo-30291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30291}.)

The launcher can be run as @code{py -0} to produce a list of the installed pythons,
`with default marked with an asterisk'. Running @code{py -0p} will include the paths.
If py is run with a version specifier that cannot be matched it will also print
the `short form' list of available specifiers.
(Contributed by Steve Barnes in bpo-30362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30362}.)

@node Porting to Python 3 7,Notable changes in Python 3 7 1,Windows-only Changes,What's New In Python 3 7
@anchor{whatsnew/3 7 porting-to-python-3-7}@anchor{be6}@anchor{whatsnew/3 7 porting-to-python-37}@anchor{abf}
@subsection Porting to Python 3.7


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changes in Python Behavior:: 
* Changements dans l'API Python: Changements dans l'API Python<7>. 
* Changements dans l'API C: Changements dans l'API C<5>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<6>. 
* Windows-only Changes: Windows-only Changes<2>. 
* Other CPython implementation changes:: 

@end menu

@node Changes in Python Behavior,Changements dans l'API Python<7>,,Porting to Python 3 7
@anchor{whatsnew/3 7 changes-in-python-behavior}@anchor{be7}
@subsubsection Changes in Python Behavior



@itemize *

@item 
@ref{71c,,async} and @ref{1b7,,await} names are now reserved keywords.
Code using these names as identifiers will now raise a @ref{18b,,SyntaxError}.
(Contributed by Jelle Zijlstra in bpo-30406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30406}.)

@item 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} is enabled for all code in Python 3.7, meaning that
@ref{be8,,StopIteration} exceptions raised directly or indirectly in
coroutines and generators are transformed into @ref{193,,RuntimeError}
exceptions.
(Contributed by Yury Selivanov in bpo-32670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32670}.)

@item 
@ref{be9,,object.__aiter__()} methods can no longer be declared as
asynchronous.  (Contributed by Yury Selivanov in bpo-31709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31709}.)

@item 
Due to an oversight, earlier Python versions erroneously accepted the
following syntax:

@example
f(1 for x in [1],)

class C(1 for x in [1]):
    pass
@end example

Python 3.7 now correctly raises a @ref{18b,,SyntaxError}, as a generator
expression always needs to be directly inside a set of parentheses
and cannot have a comma on either side, and the duplication of the
parentheses can be omitted only on calls.
(Contributed by Serhiy Storchaka in bpo-32012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32012} and bpo-32023@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32023}.)

@item 
When using the @ref{5cb,,-m} switch, the initial working directory is now added
to @ref{3ab,,sys.path}, rather than an empty string (which dynamically denoted
the current working directory at the time of each import). Any programs that
are checking for the empty string, or otherwise relying on the previous
behaviour, will need to be updated accordingly (e.g. by also checking for
@code{os.getcwd()} or @code{os.path.dirname(__main__.__file__)}, depending on why
the code was checking for the empty string in the first place).
@end itemize

@node Changements dans l'API Python<7>,Changements dans l'API C<5>,Changes in Python Behavior,Porting to Python 3 7
@anchor{whatsnew/3 7 changes-in-the-python-api}@anchor{bea}
@subsubsection Changements dans l'API Python



@itemize *

@item 
@code{socketserver.ThreadingMixIn.server_close()} now waits until all
non-daemon threads complete.  Set the new
@ref{beb,,socketserver.ThreadingMixIn.block_on_close} class attribute to
@code{False} to get the pre-3.7 behaviour.
(Contributed by Victor Stinner in bpo-31233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31233} and bpo-33540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33540}.)

@item 
@code{socketserver.ForkingMixIn.server_close()} now waits until all
child processes complete. Set the new
@code{socketserver.ForkingMixIn.block_on_close} class attribute to @code{False}
to get the pre-3.7 behaviour.
(Contributed by Victor Stinner in bpo-31151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31151} and bpo-33540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33540}.)

@item 
The @ref{bec,,locale.localeconv()} function now temporarily sets the @code{LC_CTYPE}
locale to the value of @code{LC_NUMERIC} in some cases.
(Contributed by Victor Stinner in bpo-31900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31900}.)

@item 
@ref{bed,,pkgutil.walk_packages()} now raises a @ref{1ff,,ValueError} if `path' is
a string.  Previously an empty list was returned.
(Contributed by Sanyam Khurana in bpo-24744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24744}.)

@item 
A format string argument for @ref{bee,,string.Formatter.format()}
is now @ref{a73,,positional-only}.
Passing it as a keyword argument was deprecated in Python 3.5. (Contributed
by Serhiy Storchaka in bpo-29193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29193}.)

@item 
Attributes @ref{bef,,key},
@ref{bf0,,value} and
@ref{bf1,,coded_value} of class
@ref{bf2,,http.cookies.Morsel} are now read-only.
Assigning to them was deprecated in Python 3.5.
Use the @ref{bf3,,set()} method for setting them.
(Contributed by Serhiy Storchaka in bpo-29192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29192}.)

@item 
The `mode' argument of @ref{21b,,os.makedirs()} no longer affects the file
permission bits of newly created intermediate-level directories.
To set their file permission bits you can set the umask before invoking
@code{makedirs()}.
(Contributed by Serhiy Storchaka in bpo-19930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19930}.)

@item 
The @ref{bf4,,struct.Struct.format} type is now @ref{435,,str} instead of
@ref{1bd,,bytes}. (Contributed by Victor Stinner in bpo-21071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21071}.)

@item 
@code{cgi.parse_multipart()} now accepts the `encoding' and `errors'
arguments and returns the same results as
@code{FieldStorage}: for non-file fields, the value associated to a key
is a list of strings, not bytes.
(Contributed by Pierre Quentel in bpo-29979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29979}.)

@item 
Due to internal changes in @ref{cb,,socket}, calling @ref{bf5,,socket.fromshare()}
on a socket created by @ref{bf6,,socket.share} in older
Python versions is not supported.

@item 
@code{repr} for @ref{5a5,,BaseException} has changed to not include the trailing
comma.  Most exceptions are affected by this change.
(Contributed by Serhiy Storchaka in bpo-30399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30399}.)

@item 
@code{repr} for @ref{9bd,,datetime.timedelta} has changed to include the keyword
arguments in the output. (Contributed by Utkarsh Upadhyay in bpo-30302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30302}.)

@item 
Because @ref{2f5,,shutil.rmtree()} is now implemented using the @ref{a4d,,os.scandir()}
function, the user specified handler `onerror' is now called with the first
argument @code{os.scandir} instead of @code{os.listdir} when listing the directory
is failed.

@item 
Support for nested sets and set operations in regular expressions as in
Unicode Technical Standard #18@footnote{https://unicode.org/reports/tr18/} might be added in the future.  This would
change the syntax.  To facilitate this future change a @ref{40b,,FutureWarning}
will be raised in ambiguous cases for the time being.
That include sets starting with a literal @code{'['} or containing literal
character sequences @code{'--'}, @code{'&&'}, @code{'~~'}, and @code{'||'}.  To
avoid a warning, escape them with a backslash.
(Contributed by Serhiy Storchaka in bpo-30349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30349}.)

@item 
The result of splitting a string on a @ref{b8,,regular expression}
that could match an empty string has been changed.  For example
splitting on @code{r'\s*'} will now split not only on whitespaces as it
did previously, but also on empty strings before all non-whitespace
characters and just before the end of the string.
The previous behavior can be restored by changing the pattern
to @code{r'\s+'}.  A @ref{40b,,FutureWarning} was emitted for such patterns since
Python 3.5.

For patterns that match both empty and non-empty strings, the result of
searching for all matches may also be changed in other cases.  For example
in the string @code{'a\n\n'}, the pattern @code{r'(?m)^\s*?$'} will not only
match empty strings at positions 2 and 3, but also the string @code{'\n'} at
positions 2--3.  To match only blank lines, the pattern should be rewritten
as @code{r'(?m)^[^\S\n]*$'}.

@ref{2a0,,re.sub()} now replaces empty matches adjacent to a previous
non-empty match.  For example @code{re.sub('x*', '-', 'abxd')} returns now
@code{'-a-b--d-'} instead of @code{'-a-b-d-'} (the first minus between 'b' and
'd' replaces 'x', and the second minus replaces an empty string between
'x' and 'd').

(Contributed by Serhiy Storchaka in bpo-25054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25054} and bpo-32308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32308}.)

@item 
Change @ref{bf7,,re.escape()} to only escape regex special characters instead
of escaping all characters other than ASCII letters, numbers, and @code{'_'}.
(Contributed by Serhiy Storchaka in bpo-29995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29995}.)

@item 
@ref{b84,,tracemalloc.Traceback} frames are now sorted from oldest to most
recent to be more consistent with @ref{fd,,traceback}.
(Contributed by Jesse Bakker in bpo-32121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32121}.)

@item 
On OSes that support @ref{bf8,,socket.SOCK_NONBLOCK} or
@ref{bf9,,socket.SOCK_CLOEXEC} bit flags, the
@ref{bfa,,socket.type} no longer has them applied.
Therefore, checks like @code{if sock.type == socket.SOCK_STREAM}
work as expected on all platforms.
(Contributed by Yury Selivanov in bpo-32331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32331}.)

@item 
On Windows the default for the `close_fds' argument of
@ref{197,,subprocess.Popen} was changed from @ref{b25,,False} to @ref{bfb,,True}
when redirecting the standard handles. If you previously depended on handles
being inherited when using @ref{197,,subprocess.Popen} with standard io
redirection, you will have to pass @code{close_fds=False} to preserve the
previous behaviour, or use
@ref{bfc,,STARTUPINFO.lpAttributeList}.

@item 
@ref{bfd,,importlib.machinery.PathFinder.invalidate_caches()} -- which implicitly
affects @ref{bfe,,importlib.invalidate_caches()} -- now deletes entries
in @ref{5ce,,sys.path_importer_cache} which are set to @code{None}.
(Contributed by Brett Cannon in bpo-33169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33169}.)

@item 
In @ref{a,,asyncio},
@ref{bff,,loop.sock_recv()},
@ref{c00,,loop.sock_sendall()},
@ref{c01,,loop.sock_accept()},
@ref{c02,,loop.getaddrinfo()},
@ref{c03,,loop.getnameinfo()}
have been changed to be proper coroutine methods to match their
documentation.  Previously, these methods returned @ref{bbb,,asyncio.Future}
instances.
(Contributed by Yury Selivanov in bpo-32327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32327}.)

@item 
@ref{c04,,asyncio.Server.sockets} now returns a copy of the internal list
of server sockets, instead of returning it directly.
(Contributed by Yury Selivanov in bpo-32662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32662}.)

@item 
@ref{bf4,,Struct.format} is now a @ref{435,,str} instance
instead of a @ref{1bd,,bytes} instance.
(Contributed by Victor Stinner in bpo-21071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21071}.)

@item 
@ref{6,,argparse} subparsers can now be made mandatory by passing @code{required=True}
to @ref{c05,,ArgumentParser.add_subparsers()}.
(Contributed by Anthony Sottile in bpo-26510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26510}.)

@item 
@ref{c06,,ast.literal_eval()} is now stricter.  Addition and subtraction of
arbitrary numbers are no longer allowed.
(Contributed by Serhiy Storchaka in bpo-31778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31778}.)

@item 
@ref{c07,,Calendar.itermonthdates}
will now consistently raise an exception when a date falls outside of the
@code{0001-01-01} through @code{9999-12-31} range.  To support applications that
cannot tolerate such exceptions, the new
@ref{c08,,Calendar.itermonthdays3} and
@ref{c09,,Calendar.itermonthdays4} can be used.
The new methods return tuples and are not restricted by the range supported by
@ref{1c8,,datetime.date}.
(Contributed by Alexander Belopolsky in bpo-28292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28292}.)

@item 
@ref{c0a,,collections.ChainMap} now preserves the order of the underlying
mappings.  (Contributed by Raymond Hettinger in bpo-32792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32792}.)

@item 
The @code{submit()} method of @ref{72c,,concurrent.futures.ThreadPoolExecutor}
and @ref{8db,,concurrent.futures.ProcessPoolExecutor} now raises
a @ref{193,,RuntimeError} if called during interpreter shutdown.
(Contributed by Mark Nemec in bpo-33097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33097}.)

@item 
The @ref{1c3,,configparser.ConfigParser} constructor now uses @code{read_dict()}
to process the default values, making its behavior consistent with the
rest of the parser.  Non-string keys and values in the defaults
dictionary are now being implicitly converted to strings.
(Contributed by James Tocknell in bpo-23835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23835}.)

@item 
Several undocumented internal imports were removed.
One example is that @code{os.errno} is no longer available; use @code{import errno}
directly instead.
Note that such undocumented internal imports may be removed any time without
notice, even in micro version releases.
@end itemize

@node Changements dans l'API C<5>,Changements au code intermédiaire CPython<6>,Changements dans l'API Python<7>,Porting to Python 3 7
@anchor{whatsnew/3 7 changes-in-the-c-api}@anchor{c0b}
@subsubsection Changements dans l'API C


The function @ref{3f2,,PySlice_GetIndicesEx()} is considered unsafe for
resizable sequences.  If the slice indices are not instances of @ref{254,,int},
but objects that implement the @code{__index__()} method, the sequence can be
resized after passing its length to @code{PySlice_GetIndicesEx()}.  This
can lead to returning indices out of the length of the sequence.  For
avoiding possible problems use new functions @ref{3f3,,PySlice_Unpack()} and
@ref{3f4,,PySlice_AdjustIndices()}.
(Contributed by Serhiy Storchaka in bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}.)

@node Changements au code intermédiaire CPython<6>,Windows-only Changes<2>,Changements dans l'API C<5>,Porting to Python 3 7
@anchor{whatsnew/3 7 cpython-bytecode-changes}@anchor{c0c}
@subsubsection Changements au code intermédiaire CPython


There are two new opcodes: @ref{c0d,,LOAD_METHOD} and @code{CALL_METHOD}.
(Contributed by Yury Selivanov and INADA Naoki in bpo-26110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26110}.)

The @code{STORE_ANNOTATION} opcode has been removed.
(Contributed by Mark Shannon in bpo-32550@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32550}.)

@node Windows-only Changes<2>,Other CPython implementation changes,Changements au code intermédiaire CPython<6>,Porting to Python 3 7
@anchor{whatsnew/3 7 id12}@anchor{c0e}
@subsubsection Windows-only Changes


The file used to override @ref{3ab,,sys.path} is now called
@code{<python-executable>._pth} instead of @code{'sys.path'}.
See @ref{c0f,,Recherche de modules} for more information.
(Contributed by Steve Dower in bpo-28137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28137}.)

@node Other CPython implementation changes,,Windows-only Changes<2>,Porting to Python 3 7
@anchor{whatsnew/3 7 id13}@anchor{c10}
@subsubsection Other CPython implementation changes


In preparation for potential future changes to the public CPython runtime
initialization API (see 
@geindex Python Enhancement Proposals; PEP 432
PEP 432@footnote{https://peps.python.org/pep-0432/} for an initial, but somewhat outdated,
draft), CPython's internal startup
and configuration management logic has been significantly refactored. While
these updates are intended to be entirely transparent to both embedding
applications and users of the regular CPython CLI, they're being mentioned
here as the refactoring changes the internal order of various operations
during interpreter startup, and hence may uncover previously latent defects,
either in embedding applications, or in CPython itself.
(Initially contributed by Nick Coghlan and Eric Snow as part of
bpo-22257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22257}, and further updated by Nick, Eric, and Victor Stinner in a
number of other issues). Some known details affected:


@itemize *

@item 
@code{PySys_AddWarnOptionUnicode()} is not currently usable by embedding
applications due to the requirement to create a Unicode object prior to
calling @code{Py_Initialize}. Use @code{PySys_AddWarnOption()} instead.

@item 
warnings filters added by an embedding application with
@code{PySys_AddWarnOption()} should now more consistently take precedence
over the default filters set by the interpreter
@end itemize

Due to changes in the way the default warnings filters are configured,
setting @ref{3cb,,Py_BytesWarningFlag} to a value greater than one is no longer
sufficient to both emit @ref{c11,,BytesWarning} messages and have them converted
to exceptions.  Instead, the flag must be set (to cause the warnings to be
emitted in the first place), and an explicit @code{error::BytesWarning}
warnings filter added to convert them to exceptions.

Due to a change in the way docstrings are handled by the compiler, the
implicit @code{return None} in a function body consisting solely of a docstring
is now marked as occurring on the same line as the docstring, not on the
function's header line.

The current exception state has been moved from the frame object to the co-routine.
This simplified the interpreter and fixed a couple of obscure bugs caused by
having swap exception state when entering or exiting a generator.
(Contributed by Mark Shannon in bpo-25612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25612}.)

@node Notable changes in Python 3 7 1,Notable changes in Python 3 7 2,Porting to Python 3 7,What's New In Python 3 7
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-1}@anchor{c12}
@subsection Notable changes in Python 3.7.1


Starting in 3.7.1, @ref{899,,Py_Initialize()} now consistently reads and respects
all of the same environment settings as @ref{c13,,Py_Main()} (in earlier Python
versions, it respected an ill-defined subset of those environment variables,
while in Python 3.7.0 it didn't read any of them due to bpo-34247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34247}). If
this behavior is unwanted, set @ref{3cf,,Py_IgnoreEnvironmentFlag} to 1 before
calling @ref{899,,Py_Initialize()}.

In 3.7.1 the C API for Context Variables
@ref{c14,,was updated} to use
@ref{32f,,PyObject} pointers.  See also bpo-34762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34762}.

In 3.7.1 the @ref{fa,,tokenize} module now implicitly emits a @code{NEWLINE} token
when provided with input that does not have a trailing new line.  This behavior
now matches what the C tokenizer does internally.
(Contributed by Ammar Askar in bpo-33899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33899}.)

@node Notable changes in Python 3 7 2,Notable changes in Python 3 7 6,Notable changes in Python 3 7 1,What's New In Python 3 7
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-2}@anchor{c15}
@subsection Notable changes in Python 3.7.2


In 3.7.2, @ref{110,,venv} on Windows no longer copies the original binaries, but
creates redirector scripts named @code{python.exe} and @code{pythonw.exe} instead.
This resolves a long standing issue where all virtual environments would have
to be upgraded or recreated with each Python update. However, note that this
release will still require recreation of virtual environments in order to get
the new scripts.

@node Notable changes in Python 3 7 6,Notable changes in Python 3 7 10,Notable changes in Python 3 7 2,What's New In Python 3 7
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-6}@anchor{c16}
@subsection Notable changes in Python 3.7.6


En raison de problèmes de sécurité importants, le paramètre `reuse_address' de @ref{71d,,asyncio.loop.create_datagram_endpoint()} n'est plus supporté. C'est à cause du comportement de l'option socket @code{SO_REUSEADDR} en UDP. Pour plus de détails, voir la documentation de @code{loop.create_datagram_endpoint()}. (Contribué par Kyle Stanley, Antoine Pitrou, et Yury Selivanov dans bpo-37228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37228}.)

@node Notable changes in Python 3 7 10,Notable changes in Python 3 7 11,Notable changes in Python 3 7 6,What's New In Python 3 7
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-10}@anchor{c17}
@subsection Notable changes in Python 3.7.10


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{277,,urllib.parse.parse_qs()} and
@ref{276,,urllib.parse.parse_qsl()}.  Due to security concerns, and to conform with
newer W3C recommendations, this has been changed to allow only a single
separator key, with @code{&} as the default.  This change also affects
@code{cgi.parse()} and @code{cgi.parse_multipart()} as they use the affected
functions internally. For more details, please see their respective
documentation.
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}.)

@node Notable changes in Python 3 7 11,Notable security feature in 3 7 14,Notable changes in Python 3 7 10,What's New In Python 3 7
@anchor{whatsnew/3 7 notable-changes-in-python-3-7-11}@anchor{c18}
@subsection Notable changes in Python 3.7.11


A security fix alters the @ref{8e7,,ftplib.FTP} behavior to not trust the
IPv4 address sent from the remote server when setting up a passive data
channel.  We reuse the ftp server IP address instead.  For unusual code
requiring the old behavior, set a @code{trust_server_pasv_ipv4_address}
attribute on your FTP instance to @code{True}.  (See gh-87451@footnote{https://github.com/python/cpython/issues/87451})

The presence of newline or tab characters in parts of a URL allows for some
forms of attacks. Following the WHATWG specification that updates RFC 3986,
ASCII newline @code{\n}, @code{\r} and tab @code{\t} characters are stripped from the
URL by the parser @ref{109,,urllib.parse()} preventing such attacks. The removal
characters are controlled by a new module level variable
@code{urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE}. (See gh-88048@footnote{https://github.com/python/cpython/issues/88048})

@node Notable security feature in 3 7 14,,Notable changes in Python 3 7 11,What's New In Python 3 7
@anchor{whatsnew/3 7 notable-security-feature-in-3-7-14}@anchor{c19}
@subsection Notable security feature in 3.7.14


Converting between @ref{254,,int} and @ref{435,,str} in bases other than 2
(binary), 4, 8 (octal), 16 (hexadecimal), or 32 such as base 10 (decimal)
now raises a @ref{1ff,,ValueError} if the number of digits in string form is
above a limit to avoid potential denial of service attacks due to the
algorithmic complexity. This is a mitigation for 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.
This limit can be configured or disabled by environment variable, command
line flag, or @ref{d8,,sys} APIs. See the @ref{5df,,integer string conversion length limitation} documentation.  The default limit
is 4300 digits in string form.

@node What's New In Python 3 6,Nouveautés de Python 3 5,What's New In Python 3 7,Nouveautés de Python
@anchor{whatsnew/3 6 doc}@anchor{c1a}@anchor{whatsnew/3 6 what-s-new-in-python-3-6}@anchor{c1b}
@section What's New In Python 3.6


@*Editors: 
Elvis Pranskevichus <@email{elvis@@magic.io}>, Yury Selivanov <@email{yury@@magic.io}>


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Mercurial log
@c when researching a change.

This article explains the new features in Python 3.6, compared to 3.5.
Python 3.6 was released on December 23, 2016.  See the
changelog@footnote{https://docs.python.org/3.6/whatsnew/changelog.html} for a full
list of changes.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 494
PEP 494@footnote{https://peps.python.org/pep-0494/} - Python 3.6 Release Schedule


@menu
* Résumé – Points forts de la publication: Résumé – Points forts de la publication<3>. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<13>. 
* Autres changements au langage: Autres changements au langage<8>. 
* Nouveaux modules: Nouveaux modules<8>. 
* Modules améliorés: Modules améliorés<8>. 
* Optimizations: Optimizations<3>. 
* Build and C API Changes: Build and C API Changes<2>. 
* Autres Améliorations:: 
* Obsolescence: Obsolescence<9>. 
* Retraits: Retraits<7>. 
* Porting to Python 3.6: Porting to Python 3 6. 
* Notable changes in Python 3.6.2: Notable changes in Python 3 6 2. 
* Notable changes in Python 3.6.4: Notable changes in Python 3 6 4. 
* Notable changes in Python 3.6.5: Notable changes in Python 3 6 5. 
* Notable changes in Python 3.6.7: Notable changes in Python 3 6 7. 
* Notable changes in Python 3.6.10: Notable changes in Python 3 6 10. 
* Notable changes in Python 3.6.13: Notable changes in Python 3 6 13. 
* Notable changes in Python 3.6.14: Notable changes in Python 3 6 14. 

@end menu

@node Résumé – Points forts de la publication<3>,Nouvelles fonctionnalités<13>,,What's New In Python 3 6
@anchor{whatsnew/3 6 summary-release-highlights}@anchor{c1c}
@subsection Résumé – Points forts de la publication


Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@ref{c1d,,PEP 498}, formatted string literals.

@item 
@ref{c1e,,PEP 515}, underscores in numeric literals.

@item 
@ref{c1f,,PEP 526}, syntax for variable annotations.

@item 
@ref{c20,,PEP 525}, asynchronous generators.

@item 
@ref{c21,,PEP 530}: asynchronous comprehensions.
@end itemize

Nouveaux modules de la bibliothèque :


@itemize *

@item 
@ref{bf,,secrets}: @ref{c22,,PEP 506 -- Adding A Secrets Module To The Standard Library}.
@end itemize

CPython implementation improvements:


@itemize *

@item 
The @ref{ab4,,dict} type has been reimplemented to use
a @ref{c23,,more compact representation}
based on a proposal by Raymond Hettinger@footnote{https://mail.python.org/pipermail/python-dev/2012-December/123028.html}
and similar to the PyPy dict implementation@footnote{https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html}.  This resulted in dictionaries
using 20% to 25% less memory when compared to Python 3.5.

@item 
Customization of class creation has been simplified with the
@ref{c24,,new protocol}.

@item 
The class attribute definition order is
@ref{c25,,now preserved}.

@item 
The order of elements in @code{**kwargs} now
@ref{c26,,corresponds to the order} in which keyword
arguments were passed to the function.

@item 
DTrace and SystemTap @ref{c27,,probing support} has
been added.

@item 
The new @ref{c28,,PYTHONMALLOC} environment variable
can now be used to debug the interpreter memory allocation and access
errors.
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
The @ref{a,,asyncio} module has received new features, significant
usability and performance improvements, and a fair amount of bug fixes.
Starting with Python 3.6 the @code{asyncio} module is no longer provisional
and its API is considered stable.

@item 
A new @ref{c29,,file system path protocol} has been
implemented to support @ref{29d,,path-like objects}.
All standard library functions operating on paths have been updated to
work with the new protocol.

@item 
The @ref{30,,datetime} module has gained support for
@ref{c2a,,Local Time Disambiguation}.

@item 
The @ref{103,,typing} module received a number of
@ref{c2b,,improvements}.

@item 
The @ref{fe,,tracemalloc} module has been significantly reworked
and is now used to provide better output for @ref{241,,ResourceWarning}
as well as provide better diagnostics for memory allocation errors.
See the @ref{c28,,PYTHONMALLOC section} for more
information.
@end itemize

Security improvements:


@itemize *

@item 
The new @ref{bf,,secrets} module has been added to simplify the generation of
cryptographically strong pseudo-random numbers suitable for
managing secrets such as account authentication, tokens, and similar.

@item 
On Linux, @ref{50c,,os.urandom()} now blocks until the system urandom entropy
pool is initialized to increase the security. See the 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/} for the
rationale.

@item 
The @ref{67,,hashlib} and @ref{cf,,ssl} modules now support OpenSSL 1.1.0.

@item 
The default settings and feature set of the @ref{cf,,ssl} module have been
improved.

@item 
The @ref{67,,hashlib} module received support for the BLAKE2, SHA-3 and SHAKE
hash algorithms and the @ref{c2c,,scrypt()} key derivation function.
@end itemize

Windows improvements:


@itemize *

@item 
@ref{c2d,,PEP 528} and @ref{c2e,,PEP 529},
Windows filesystem and console encoding changed to UTF-8.

@item 
The @code{py.exe} launcher, when used interactively, no longer prefers
Python 2 over Python 3 when the user doesn't specify a version (via
command line arguments or a config file).  Handling of shebang lines
remains unchanged - "python" refers to Python 2 in that case.

@item 
@code{python.exe} and @code{pythonw.exe} have been marked as long-path aware,
which means that the 260 character path limit may no longer apply.
See @ref{c2f,,removing the MAX_PATH limitation} for details.

@item 
A @code{._pth} file can be added to force isolated mode and fully specify
all search paths to avoid registry and environment lookup. See
@ref{c0f,,the documentation} for more information.

@item 
A @code{python36.zip} file now works as a landmark to infer
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME}. See @ref{c0f,,the documentation} for
more information.
@end itemize

@node Nouvelles fonctionnalités<13>,Autres changements au langage<8>,Résumé – Points forts de la publication<3>,What's New In Python 3 6
@anchor{whatsnew/3 6 new-features}@anchor{c30}@anchor{whatsnew/3 6 pypy-dict-implementation}@anchor{c31}
@subsection Nouvelles fonctionnalités


@menu
* PEP 498; Formatted string literals: PEP 498 Formatted string literals. 
* PEP 526; Syntax for variable annotations: PEP 526 Syntax for variable annotations. 
* PEP 515; Underscores in Numeric Literals: PEP 515 Underscores in Numeric Literals. 
* PEP 525; Asynchronous Generators: PEP 525 Asynchronous Generators. 
* PEP 530; Asynchronous Comprehensions: PEP 530 Asynchronous Comprehensions. 
* PEP 487; Simpler customization of class creation: PEP 487 Simpler customization of class creation. 
* PEP 487; Descriptor Protocol Enhancements: PEP 487 Descriptor Protocol Enhancements. 
* PEP 519; Adding a file system path protocol: PEP 519 Adding a file system path protocol. 
* PEP 495; Local Time Disambiguation: PEP 495 Local Time Disambiguation. 
* PEP 529; Change Windows filesystem encoding to UTF-8: PEP 529 Change Windows filesystem encoding to UTF-8. 
* PEP 528; Change Windows console encoding to UTF-8: PEP 528 Change Windows console encoding to UTF-8. 
* PEP 520; Preserving Class Attribute Definition Order: PEP 520 Preserving Class Attribute Definition Order. 
* PEP 468; Preserving Keyword Argument Order: PEP 468 Preserving Keyword Argument Order. 
* New dict implementation:: 
* PEP 523; Adding a frame evaluation API to CPython: PEP 523 Adding a frame evaluation API to CPython. 
* PYTHONMALLOC environment variable:: 
* DTrace and SystemTap probing support:: 

@end menu

@node PEP 498 Formatted string literals,PEP 526 Syntax for variable annotations,,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-498-formatted-string-literals}@anchor{c32}@anchor{whatsnew/3 6 whatsnew36-pep498}@anchor{c1d}
@subsubsection PEP 498: Formatted string literals


@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/} introduces a new kind of string literals: `f-strings', or
@ref{997,,formatted string literals}.

Formatted string literals are prefixed with @code{'f'} and are similar to
the format strings accepted by @ref{60c,,str.format()}.  They contain replacement
fields surrounded by curly braces.  The replacement fields are expressions,
which are evaluated at run time, and then formatted using the
@ref{60a,,format()} protocol:

@example
>>> name = "Fred"
>>> f"He said his name is @{name@}."
'He said his name is Fred.'
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: @{value:@{width@}.@{precision@}@}"  # nested fields
'result:      12.35'
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 498

@item PEP 498@footnote{https://peps.python.org/pep-0498/} -- Literal String Interpolation.

PEP written and implemented by Eric V. Smith.
@end table

@ref{997,,Feature documentation}.


@node PEP 526 Syntax for variable annotations,PEP 515 Underscores in Numeric Literals,PEP 498 Formatted string literals,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-526-syntax-for-variable-annotations}@anchor{c33}@anchor{whatsnew/3 6 whatsnew36-pep526}@anchor{c1f}
@subsubsection PEP 526: Syntax for variable annotations


@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} introduced the standard for type annotations of function
parameters, a.k.a. type hints. This PEP adds syntax to Python for annotating
the types of variables including class variables and instance variables:

@example
primes: List[int] = []

captain: str  # Note: no initial value!

class Starship:
    stats: Dict[str, int] = @{@}
@end example

Just as for function annotations, the Python interpreter does not attach any
particular meaning to variable annotations and only stores them in the
@code{__annotations__} attribute of a class or module.

In contrast to variable declarations in statically typed languages,
the goal of annotation syntax is to provide an easy way to specify structured
type metadata for third party tools and libraries via the abstract syntax tree
and the @code{__annotations__} attribute.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} -- Syntax for variable annotations.

PEP written by Ryan Gonzalez, Philip House, Ivan Levkivskyi, Lisa Roach,
and Guido van Rossum. Implemented by Ivan Levkivskyi.
@end table

Tools that use or will use the new syntax:
mypy@footnote{https://www.mypy-lang.org/},
pytype@footnote{https://github.com/google/pytype}, PyCharm, etc.


@node PEP 515 Underscores in Numeric Literals,PEP 525 Asynchronous Generators,PEP 526 Syntax for variable annotations,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-515-underscores-in-numeric-literals}@anchor{c34}@anchor{whatsnew/3 6 whatsnew36-pep515}@anchor{c1e}
@subsubsection PEP 515: Underscores in Numeric Literals


@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/} adds the ability to use underscores in numeric literals for
improved readability.  For example:

@example
>>> 1_000_000_000_000_000
1000000000000000
>>> 0x_FF_FF_FF_FF
4294967295
@end example

Single underscores are allowed between digits and after any base
specifier.  Leading, trailing, or multiple underscores in a row are not
allowed.

The @ref{1e5,,string formatting} language also now has support
for the @code{'_'} option to signal the use of an underscore for a thousands
separator for floating-point presentation types and for integer
presentation type @code{'d'}.  For integer presentation types @code{'b'},
@code{'o'}, @code{'x'}, and @code{'X'}, underscores will be inserted every 4
digits:

@example
>>> '@{:_@}'.format(1000000)
'1_000_000'
>>> '@{:_x@}'.format(0xFFFFFFFF)
'ffff_ffff'
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 515

@item PEP 515@footnote{https://peps.python.org/pep-0515/} -- Underscores in Numeric Literals

PEP written by Georg Brandl and Serhiy Storchaka.
@end table


@node PEP 525 Asynchronous Generators,PEP 530 Asynchronous Comprehensions,PEP 515 Underscores in Numeric Literals,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-525-asynchronous-generators}@anchor{c35}@anchor{whatsnew/3 6 whatsnew36-pep525}@anchor{c20}
@subsubsection PEP 525: Asynchronous Generators


@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} introduced support for native coroutines and @code{async} / @code{await}
syntax to Python 3.5.  A notable limitation of the Python 3.5 implementation
is that it was not possible to use @code{await} and @code{yield} in the same
function body.  In Python 3.6 this restriction has been lifted, making it
possible to define `asynchronous generators':

@example
async def ticker(delay, to):
    """Yield numbers from 0 to *to* every *delay* seconds."""
    for i in range(to):
        yield i
        await asyncio.sleep(delay)
@end example

The new syntax allows for faster and more concise code.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 525

@item PEP 525@footnote{https://peps.python.org/pep-0525/} -- Asynchronous Generators

PEP written and implemented by Yury Selivanov.
@end table


@node PEP 530 Asynchronous Comprehensions,PEP 487 Simpler customization of class creation,PEP 525 Asynchronous Generators,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-530-asynchronous-comprehensions}@anchor{c36}@anchor{whatsnew/3 6 whatsnew36-pep530}@anchor{c21}
@subsubsection PEP 530: Asynchronous Comprehensions


@geindex Python Enhancement Proposals; PEP 530
PEP 530@footnote{https://peps.python.org/pep-0530/} adds support for using @code{async for} in list, set, dict
comprehensions and generator expressions:

@example
result = [i async for i in aiter() if i % 2]
@end example

Additionally, @code{await} expressions are supported in all kinds
of comprehensions:

@example
result = [await fun() for fun in funcs if await condition()]
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 530

@item PEP 530@footnote{https://peps.python.org/pep-0530/} -- Asynchronous Comprehensions

PEP written and implemented by Yury Selivanov.
@end table


@node PEP 487 Simpler customization of class creation,PEP 487 Descriptor Protocol Enhancements,PEP 530 Asynchronous Comprehensions,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-487-simpler-customization-of-class-creation}@anchor{c37}@anchor{whatsnew/3 6 whatsnew36-pep487}@anchor{c24}
@subsubsection PEP 487: Simpler customization of class creation


It is now possible to customize subclass creation without using a metaclass.
The new @code{__init_subclass__} classmethod will be called on the base class
whenever a new subclass is created:

@example
class PluginBase:
    subclasses = []

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.subclasses.append(cls)

class Plugin1(PluginBase):
    pass

class Plugin2(PluginBase):
    pass
@end example

In order to allow zero-argument @ref{4c5,,super()} calls to work correctly from
@ref{61c,,__init_subclass__()} implementations, custom metaclasses must
ensure that the new @code{__classcell__} namespace entry is propagated to
@code{type.__new__} (as described in @ref{c38,,Création de l'objet classe}).


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 487

@item PEP 487@footnote{https://peps.python.org/pep-0487/} -- Simpler customization of class creation

PEP written and implemented by Martin Teichmann.
@end table

@ref{c39,,Feature documentation}


@node PEP 487 Descriptor Protocol Enhancements,PEP 519 Adding a file system path protocol,PEP 487 Simpler customization of class creation,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-487-descriptor-protocol-enhancements}@anchor{c3a}@anchor{whatsnew/3 6 whatsnew36-pep487-descriptors}@anchor{c3b}
@subsubsection PEP 487: Descriptor Protocol Enhancements


@geindex Python Enhancement Proposals; PEP 487
PEP 487@footnote{https://peps.python.org/pep-0487/} extends the descriptor protocol to include the new optional
@ref{c3c,,__set_name__()} method.  Whenever a new class is defined, the new
method will be called on all descriptors included in the definition, providing
them with a reference to the class being defined and the name given to the
descriptor within the class namespace.  In other words, instances of
descriptors can now know the attribute name of the descriptor in the
owner class:

@example
class IntField:
    def __get__(self, instance, owner):
        return instance.__dict__[self.name]

    def __set__(self, instance, value):
        if not isinstance(value, int):
            raise ValueError(f'expecting integer in @{self.name@}')
        instance.__dict__[self.name] = value

    # this is the new initializer:
    def __set_name__(self, owner, name):
        self.name = name

class Model:
    int_field = IntField()
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 487

@item PEP 487@footnote{https://peps.python.org/pep-0487/} -- Simpler customization of class creation

PEP written and implemented by Martin Teichmann.
@end table

@ref{c3d,,Feature documentation}


@node PEP 519 Adding a file system path protocol,PEP 495 Local Time Disambiguation,PEP 487 Descriptor Protocol Enhancements,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-519-adding-a-file-system-path-protocol}@anchor{c3e}@anchor{whatsnew/3 6 whatsnew36-pep519}@anchor{c29}
@subsubsection PEP 519: Adding a file system path protocol


File system paths have historically been represented as @ref{435,,str}
or @ref{1bd,,bytes} objects. This has led to people who write code which
operate on file system paths to assume that such objects are only one
of those two types (an @ref{254,,int} representing a file descriptor
does not count as that is not a file path). Unfortunately that
assumption prevents alternative object representations of file system
paths like @ref{a3,,pathlib} from working with pre-existing code,
including Python's standard library.

To fix this situation, a new interface represented by
@ref{c3f,,os.PathLike} has been defined. By implementing the
@ref{c40,,__fspath__()} method, an object signals that it
represents a path. An object can then provide a low-level
representation of a file system path as a @ref{435,,str} or
@ref{1bd,,bytes} object. This means an object is considered
@ref{29d,,path-like} if it implements
@ref{c3f,,os.PathLike} or is a @ref{435,,str} or @ref{1bd,,bytes} object
which represents a file system path. Code can use @ref{c41,,os.fspath()},
@ref{c42,,os.fsdecode()}, or @ref{c43,,os.fsencode()} to explicitly get a
@ref{435,,str} and/or @ref{1bd,,bytes} representation of a path-like
object.

The built-in @ref{505,,open()} function has been updated to accept
@ref{c3f,,os.PathLike} objects, as have all relevant functions in the
@ref{a0,,os} and @ref{a1,,os.path} modules, and most other functions and
classes in the standard library.  The @ref{485,,os.DirEntry} class
and relevant classes in @ref{a3,,pathlib} have also been updated to
implement @ref{c3f,,os.PathLike}.

The hope is that updating the fundamental functions for operating
on file system paths will lead to third-party code to implicitly
support all @ref{29d,,path-like objects} without any
code changes, or at least very minimal ones (e.g. calling
@ref{c41,,os.fspath()} at the beginning of code before operating on a
path-like object).

Here are some examples of how the new interface allows for
@ref{226,,pathlib.Path} to be used more easily and transparently with
pre-existing code:

@example
>>> import pathlib
>>> with open(pathlib.Path("README")) as f:
...     contents = f.read()
...
>>> import os.path
>>> os.path.splitext(pathlib.Path("some_file.txt"))
('some_file', '.txt')
>>> os.path.join("/a/b", pathlib.Path("c"))
'/a/b/c'
>>> import os
>>> os.fspath(pathlib.Path("some_file.txt"))
'some_file.txt'
@end example

(Implemented by Brett Cannon, Ethan Furman, Dusty Phillips, and Jelle Zijlstra.)


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 519

@item PEP 519@footnote{https://peps.python.org/pep-0519/} -- Adding a file system path protocol

PEP written by Brett Cannon and Koos Zevenhoven.
@end table


@node PEP 495 Local Time Disambiguation,PEP 529 Change Windows filesystem encoding to UTF-8,PEP 519 Adding a file system path protocol,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-495-local-time-disambiguation}@anchor{c44}@anchor{whatsnew/3 6 whatsnew36-pep495}@anchor{c2a}
@subsubsection PEP 495: Local Time Disambiguation


In most world locations, there have been and will be times when local clocks
are moved back.  In those times, intervals are introduced in which local
clocks show the same time twice in the same day. In these situations, the
information displayed on a local clock (or stored in a Python datetime
instance) is insufficient to identify a particular moment in time.

@geindex Python Enhancement Proposals; PEP 495
PEP 495@footnote{https://peps.python.org/pep-0495/} adds the new `fold' attribute to instances of
@ref{1c7,,datetime.datetime} and @ref{1c9,,datetime.time} classes to differentiate
between two moments in time for which local times are the same:

@example
>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0
@end example

The values of the @ref{c45,,fold} attribute have the
value @code{0} for all instances except those that represent the second
(chronologically) moment in time in an ambiguous case.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 495

@item PEP 495@footnote{https://peps.python.org/pep-0495/} -- Local Time Disambiguation

PEP written by Alexander Belopolsky and Tim Peters, implementation
by Alexander Belopolsky.
@end table


@node PEP 529 Change Windows filesystem encoding to UTF-8,PEP 528 Change Windows console encoding to UTF-8,PEP 495 Local Time Disambiguation,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-529-change-windows-filesystem-encoding-to-utf-8}@anchor{c46}@anchor{whatsnew/3 6 whatsnew36-pep529}@anchor{c2e}
@subsubsection PEP 529: Change Windows filesystem encoding to UTF-8


Representing filesystem paths is best performed with str (Unicode) rather than
bytes. However, there are some situations where using bytes is sufficient and
correct.

Prior to Python 3.6, data loss could result when using bytes paths on Windows.
With this change, using bytes to represent paths is now supported on Windows,
provided those bytes are encoded with the encoding returned by
@ref{c47,,sys.getfilesystemencoding()}, which now defaults to @code{'utf-8'}.

Applications that do not use str to represent paths should use
@ref{c43,,os.fsencode()} and @ref{c42,,os.fsdecode()} to ensure their bytes are
correctly encoded. To revert to the previous behaviour, set
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} or call
@ref{2ab,,sys._enablelegacywindowsfsencoding()}.

See 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for more information and discussion of code modifications that
may be required.

@node PEP 528 Change Windows console encoding to UTF-8,PEP 520 Preserving Class Attribute Definition Order,PEP 529 Change Windows filesystem encoding to UTF-8,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-528-change-windows-console-encoding-to-utf-8}@anchor{c48}@anchor{whatsnew/3 6 whatsnew36-pep528}@anchor{c2d}
@subsubsection PEP 528: Change Windows console encoding to UTF-8


The default console on Windows will now accept all Unicode characters and
provide correctly read str objects to Python code. @code{sys.stdin},
@code{sys.stdout} and @code{sys.stderr} now default to utf-8 encoding.

This change only applies when using an interactive console, and not when
redirecting files or pipes. To revert to the previous behaviour for interactive
console use, set 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex variable d'environnement; PYTHONLEGACYWINDOWSSTDIO
@ref{c49,,PYTHONLEGACYWINDOWSSTDIO}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 528

@item PEP 528@footnote{https://peps.python.org/pep-0528/} -- Change Windows console encoding to UTF-8

PEP written and implemented by Steve Dower.
@end table


@node PEP 520 Preserving Class Attribute Definition Order,PEP 468 Preserving Keyword Argument Order,PEP 528 Change Windows console encoding to UTF-8,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-520-preserving-class-attribute-definition-order}@anchor{c4a}@anchor{whatsnew/3 6 whatsnew36-pep520}@anchor{c25}
@subsubsection PEP 520: Preserving Class Attribute Definition Order


Attributes in a class definition body have a natural ordering: the same
order in which the names appear in the source.  This order is now
preserved in the new class's @ref{c4b,,__dict__} attribute.

Also, the effective default class `execution' namespace (returned from
@ref{c4c,,type.__prepare__()}) is now an insertion-order-preserving
mapping.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 520

@item PEP 520@footnote{https://peps.python.org/pep-0520/} -- Preserving Class Attribute Definition Order

PEP written and implemented by Eric Snow.
@end table


@node PEP 468 Preserving Keyword Argument Order,New dict implementation,PEP 520 Preserving Class Attribute Definition Order,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-468-preserving-keyword-argument-order}@anchor{c4d}@anchor{whatsnew/3 6 whatsnew36-pep468}@anchor{c26}
@subsubsection PEP 468: Preserving Keyword Argument Order


@code{**kwargs} in a function signature is now guaranteed to be an
insertion-order-preserving mapping.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 468

@item PEP 468@footnote{https://peps.python.org/pep-0468/} -- Preserving Keyword Argument Order

PEP written and implemented by Eric Snow.
@end table


@node New dict implementation,PEP 523 Adding a frame evaluation API to CPython,PEP 468 Preserving Keyword Argument Order,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 new-dict-implementation}@anchor{c4e}@anchor{whatsnew/3 6 whatsnew36-compactdict}@anchor{c23}
@subsubsection New dict implementation


The @ref{ab4,,dict} type now uses a "compact" representation
based on a proposal by Raymond Hettinger@footnote{https://mail.python.org/pipermail/python-dev/2012-December/123028.html}
which was first implemented by PyPy@footnote{https://morepypy.blogspot.com/2015/01/faster-more-memory-efficient-and-more.html}.
The memory usage of the new @ref{253,,dict()} is between 20% and 25% smaller
compared to Python 3.5.

The order-preserving aspect of this new implementation is considered an
implementation detail and should not be relied upon (this may change in
the future, but it is desired to have this new dict implementation in
the language for a few releases before changing the language spec to mandate
order-preserving semantics for all current and future Python
implementations; this also helps preserve backwards-compatibility
with older versions of the language where random iteration order is
still in effect, e.g. Python 3.5).

(Contributed by INADA Naoki in bpo-27350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27350}. Idea
originally suggested by Raymond Hettinger@footnote{https://mail.python.org/pipermail/python-dev/2012-December/123028.html}.)

@node PEP 523 Adding a frame evaluation API to CPython,PYTHONMALLOC environment variable,New dict implementation,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pep-523-adding-a-frame-evaluation-api-to-cpython}@anchor{c4f}@anchor{whatsnew/3 6 whatsnew36-pep523}@anchor{c50}
@subsubsection PEP 523: Adding a frame evaluation API to CPython


While Python provides extensive support to customize how code
executes, one place it has not done so is in the evaluation of frame
objects.  If you wanted some way to intercept frame evaluation in
Python there really wasn't any way without directly manipulating
function pointers for defined functions.

@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} changes this by providing an API to make frame
evaluation pluggable at the C level. This will allow for tools such
as debuggers and JITs to intercept frame evaluation before the
execution of Python code begins. This enables the use of alternative
evaluation implementations for Python code, tracking frame
evaluation, etc.

This API is not part of the limited C API and is marked as private to
signal that usage of this API is expected to be limited and only
applicable to very select, low-level use-cases. Semantics of the
API will change with Python as necessary.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 523

@item PEP 523@footnote{https://peps.python.org/pep-0523/} -- Adding a frame evaluation API to CPython

PEP written by Brett Cannon and Dino Viehland.
@end table


@node PYTHONMALLOC environment variable,DTrace and SystemTap probing support,PEP 523 Adding a frame evaluation API to CPython,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 pythonmalloc-environment-variable}@anchor{c51}@anchor{whatsnew/3 6 whatsnew36-pythonmalloc}@anchor{c28}
@subsubsection PYTHONMALLOC environment variable


The new 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable allows setting the Python
memory allocators and installing debug hooks.

It is now possible to install debug hooks on Python memory allocators on Python
compiled in release mode using @code{PYTHONMALLOC=debug}. Effects of debug hooks:


@itemize *

@item 
Newly allocated memory is filled with the byte @code{0xCB}

@item 
Freed memory is filled with the byte @code{0xDB}

@item 
Detect violations of the Python memory allocator API. For example,
@ref{c53,,PyObject_Free()} called on a memory block allocated by
@ref{c54,,PyMem_Malloc()}.

@item 
Detect writes before the start of a buffer (buffer underflows)

@item 
Detect writes after the end of a buffer (buffer overflows)

@item 
Check that the @ref{147,,GIL} is held when allocator
functions of @ref{c55,,PYMEM_DOMAIN_OBJ} (ex: @ref{c56,,PyObject_Malloc()}) and
@ref{c57,,PYMEM_DOMAIN_MEM} (ex: @ref{c54,,PyMem_Malloc()}) domains are called.
@end itemize

Checking if the GIL is held is also a new feature of Python 3.6.

Reportez-vous à la fonction @ref{c58,,PyMem_SetupDebugHooks()} pour ce qui concerne les fonctions de débogage de l'allocateur mémoire de Python.

It is now also possible to force the usage of the @code{malloc()} allocator of
the C library for all Python memory allocations using @code{PYTHONMALLOC=malloc}.
This is helpful when using external memory debuggers like Valgrind on
a Python compiled in release mode.

On error, the debug hooks on Python memory allocators now use the
@ref{fe,,tracemalloc} module to get the traceback where a memory block was
allocated.

Example of fatal error on buffer overflow using
@code{python3.6 -X tracemalloc=5} (store 5 frames in traces):

@example
Debug memory block at address p=0x7fbcd41666f8: API 'o'
    4 bytes originally requested
    The 7 pad bytes at p-7 are FORBIDDENBYTE, as expected.
    The 8 pad bytes at tail=0x7fbcd41666fc are not all FORBIDDENBYTE (0xfb):
        at tail+0: 0x02 *** OUCH
        at tail+1: 0xfb
        at tail+2: 0xfb
        at tail+3: 0xfb
        at tail+4: 0xfb
        at tail+5: 0xfb
        at tail+6: 0xfb
        at tail+7: 0xfb
    The block was made by call #1233329 to debug malloc/realloc.
    Data at p: 1a 2b 30 00

Memory block allocated at (most recent call first):
  File "test/test_bytes.py", line 323
  File "unittest/case.py", line 600
  File "unittest/case.py", line 648
  File "unittest/suite.py", line 122
  File "unittest/suite.py", line 84

Fatal Python error: bad trailing pad byte

Current thread 0x00007fbcdbd32700 (most recent call first):
  File "test/test_bytes.py", line 323 in test_hex
  File "unittest/case.py", line 600 in run
  File "unittest/case.py", line 648 in __call__
  File "unittest/suite.py", line 122 in run
  File "unittest/suite.py", line 84 in __call__
  File "unittest/suite.py", line 122 in run
  File "unittest/suite.py", line 84 in __call__
  ...
@end example

(Contributed by Victor Stinner in bpo-26516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26516} and bpo-26564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26564}.)

@node DTrace and SystemTap probing support,,PYTHONMALLOC environment variable,Nouvelles fonctionnalités<13>
@anchor{whatsnew/3 6 dtrace-and-systemtap-probing-support}@anchor{c59}@anchor{whatsnew/3 6 whatsnew36-tracing}@anchor{c27}
@subsubsection DTrace and SystemTap probing support


Python can now be built @code{--with-dtrace} which enables static markers
for the following events in the interpreter:


@itemize *

@item 
function call/return

@item 
garbage collection started/finished

@item 
line of code executed.
@end itemize

This can be used to instrument running interpreters in production,
without the need to recompile specific @ref{1f6,,debug builds} or
providing application-specific profiling/debugging code.

More details in @ref{c5a,,Instrumenter CPython avec DTrace et SystemTap}.

The current implementation is tested on Linux and macOS.  Additional
markers may be added in the future.

(Contributed by Łukasz Langa in bpo-21590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21590}, based on patches by
Jesús Cea Avión, David Malcolm, and Nikhil Benesch.)

@node Autres changements au langage<8>,Nouveaux modules<8>,Nouvelles fonctionnalités<13>,What's New In Python 3 6
@anchor{whatsnew/3 6 other-language-changes}@anchor{c5b}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
A @code{global} or @code{nonlocal} statement must now textually appear
before the first use of the affected name in the same scope.
Previously this was a @ref{44f,,SyntaxWarning}.

@item 
It is now possible to set a @ref{c5c,,special method} to
@code{None} to indicate that the corresponding operation is not available.
For example, if a class sets @code{__iter__()} to @code{None}, the class
is not iterable.
(Contributed by Andrew Barnert and Ivan Levkivskyi in bpo-25958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25958}.)

@item 
Long sequences of repeated traceback lines are now abbreviated as
@code{"[Previous line repeated @{count@} more times]"} (see
@ref{c5d,,traceback} for an example).
(Contributed by Emanuel Barry in bpo-26823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26823}.)

@item 
Import now raises the new exception @ref{b35,,ModuleNotFoundError}
(subclass of @ref{40f,,ImportError}) when it cannot find a module.  Code
that currently checks for ImportError (in try-except) will still work.
(Contributed by Eric Snow in bpo-15767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15767}.)

@item 
Class methods relying on zero-argument @code{super()} will now work correctly
when called from metaclass methods during class creation.
(Contributed by Martin Teichmann in bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}.)
@end itemize

@node Nouveaux modules<8>,Modules améliorés<8>,Autres changements au langage<8>,What's New In Python 3 6
@anchor{whatsnew/3 6 new-modules}@anchor{c5e}
@subsection Nouveaux modules


@menu
* secrets:: 

@end menu

@node secrets,,,Nouveaux modules<8>
@anchor{whatsnew/3 6 secrets}@anchor{c5f}@anchor{whatsnew/3 6 whatsnew36-pep506}@anchor{c22}
@subsubsection secrets


The main purpose of the new @ref{bf,,secrets} module is to provide an obvious way
to reliably generate cryptographically strong pseudo-random values suitable
for managing secrets, such as account authentication, tokens, and similar.

@cartouche
@quotation Avertissement 
Note that the pseudo-random generators in the @ref{b7,,random} module
should `NOT' be used for security purposes.  Use @ref{bf,,secrets}
on Python 3.6+ and @ref{50c,,os.urandom()} on Python 3.5 and earlier.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 506

@item PEP 506@footnote{https://peps.python.org/pep-0506/} -- Adding A Secrets Module To The Standard Library

PEP written and implemented by Steven D'Aprano.
@end table


@node Modules améliorés<8>,Optimizations<3>,Nouveaux modules<8>,What's New In Python 3 6
@anchor{whatsnew/3 6 improved-modules}@anchor{c60}
@subsection Modules améliorés


@menu
* array: array<4>. 
* ast: ast<4>. 
* asyncio: asyncio<9>. 
* binascii: binascii<2>. 
* cmath:: 
* collections: collections<4>. 
* concurrent.futures: concurrent futures<4>. 
* contextlib: contextlib<4>. 
* datetime: datetime<5>. 
* decimal: decimal<2>. 
* distutils: distutils<5>. 
* email: email<2>. 
* encodings: encodings<2>. 
* enum: enum<7>. 
* faulthandler: faulthandler<2>. 
* fileinput: fileinput<2>. 
* hashlib: hashlib<5>. 
* http.client: http client<2>. 
* idlelib and IDLE: idlelib and IDLE<2>. 
* importlib: importlib<6>. 
* inspect: inspect<6>. 
* json:: 
* logging: logging<4>. 
* math: math<7>. 
* multiprocessing: multiprocessing<5>. 
* os: os<8>. 
* pathlib: pathlib<9>. 
* pdb: pdb<5>. 
* pickle: pickle<2>. 
* pickletools:: 
* pydoc: pydoc<3>. 
* random: random<4>. 
* re: re<5>. 
* readline:: 
* rlcompleter:: 
* shlex: shlex<2>. 
* site: site<3>. 
* sqlite3: sqlite3<7>. 
* socket: socket<7>. 
* socketserver: socketserver<2>. 
* ssl: ssl<7>. 
* statistics: statistics<5>. 
* struct:: 
* subprocess: subprocess<3>. 
* sys: sys<10>. 
* telnetlib:: 
* time: time<6>. 
* timeit:: 
* tkinter: tkinter<6>. 
* traceback: traceback<4>. 
* tracemalloc: tracemalloc<3>. 
* typing: typing<9>. 
* unicodedata: unicodedata<7>. 
* unittest.mock: unittest mock<2>. 
* urllib.request: urllib request. 
* urllib.robotparser: urllib robotparser. 
* venv: venv<5>. 
* warnings: warnings<4>. 
* winreg:: 
* winsound:: 
* xmlrpc.client: xmlrpc client. 
* zipfile: zipfile<3>. 
* zlib:: 

@end menu

@node array<4>,ast<4>,,Modules améliorés<8>
@anchor{whatsnew/3 6 array}@anchor{c61}
@subsubsection `array'


Exhausted iterators of @ref{19e,,array.array} will now stay exhausted even
if the iterated array is extended.  This is consistent with the behavior
of other mutable sequences.

Contributed by Serhiy Storchaka in bpo-26492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26492}.

@node ast<4>,asyncio<9>,array<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 ast}@anchor{c62}
@subsubsection ast


The new @ref{2b6,,ast.Constant} AST node has been added.  It can be used
by external AST optimizers for the purposes of constant folding.

Contributed by Victor Stinner in bpo-26146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26146}.

@node asyncio<9>,binascii<2>,ast<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 asyncio}@anchor{c63}
@subsubsection asyncio


Starting with Python 3.6 the @code{asyncio} module is no longer provisional and its
API is considered stable.

Notable changes in the @ref{a,,asyncio} module since Python 3.5.0
(all backported to 3.5.x due to the provisional status):


@itemize *

@item 
The @ref{2bf,,get_event_loop()} function has been changed to
always return the currently running loop when called from coroutines
and callbacks.
(Contributed by Yury Selivanov in bpo-28613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28613}.)

@item 
The @ref{c64,,ensure_future()} function and all functions that
use it, such as @ref{c65,,loop.run_until_complete()},
now accept all kinds of @ref{1ab,,awaitable objects}.
(Contributed by Yury Selivanov.)

@item 
New @ref{86e,,run_coroutine_threadsafe()} function to submit
coroutines to event loops from other threads.
(Contributed by Vincent Michel.)

@item 
New @ref{c66,,Transport.is_closing()}
method to check if the transport is closing or closed.
(Contributed by Yury Selivanov.)

@item 
The @ref{b01,,loop.create_server()}
method can now accept a list of hosts.
(Contributed by Yann Sionneau.)

@item 
New @ref{c67,,loop.create_future()}
method to create Future objects.  This allows alternative event
loop implementations, such as
uvloop@footnote{https://github.com/MagicStack/uvloop}, to provide a faster
@ref{bbb,,asyncio.Future} implementation.
(Contributed by Yury Selivanov in bpo-27041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27041}.)

@item 
New @ref{c68,,loop.get_exception_handler()}
method to get the current exception handler.
(Contributed by Yury Selivanov in bpo-27040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27040}.)

@item 
New @ref{1b2,,StreamReader.readuntil()}
method to read data from the stream until a separator bytes
sequence appears.
(Contributed by Mark Korenberg.)

@item 
The performance of @ref{c69,,StreamReader.readexactly()}
has been improved.
(Contributed by Mark Korenberg in bpo-28370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28370}.)

@item 
The @ref{c02,,loop.getaddrinfo()}
method is optimized to avoid calling the system @code{getaddrinfo}
function if the address is already resolved.
(Contributed by A. Jesse Jiryu Davis.)

@item 
The @ref{c6a,,loop.stop()}
method has been changed to stop the loop immediately after
the current iteration.  Any new callbacks scheduled as a result
of the last iteration will be discarded.
(Contributed by Guido van Rossum in bpo-25593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25593}.)

@item 
@code{Future.set_exception}
will now raise @ref{522,,TypeError} when passed an instance of
the @ref{be8,,StopIteration} exception.
(Contributed by Chris Angelico in bpo-26221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26221}.)

@item 
New @ref{b08,,loop.connect_accepted_socket()}
method to be used by servers that accept connections outside of asyncio,
but that use asyncio to handle them.
(Contributed by Jim Fulton in bpo-27392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27392}.)

@item 
@code{TCP_NODELAY} flag is now set for all TCP transports by default.
(Contributed by Yury Selivanov in bpo-27456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27456}.)

@item 
New @ref{c6b,,loop.shutdown_asyncgens()}
to properly close pending asynchronous generators before closing the
loop.
(Contributed by Yury Selivanov in bpo-28003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28003}.)

@item 
@ref{bbb,,Future} and @ref{4c2,,Task}
classes now have an optimized C implementation which makes asyncio
code up to 30% faster.
(Contributed by Yury Selivanov and INADA Naoki in bpo-26081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26081}
and bpo-28544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28544}.)
@end itemize

@node binascii<2>,cmath,asyncio<9>,Modules améliorés<8>
@anchor{whatsnew/3 6 binascii}@anchor{c6c}
@subsubsection binascii


The @ref{c6d,,b2a_base64()} function now accepts an optional `newline'
keyword argument to control whether the newline character is appended to the
return value.
(Contributed by Victor Stinner in bpo-25357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25357}.)

@node cmath,collections<4>,binascii<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 cmath}@anchor{c6e}
@subsubsection cmath


The new @ref{c6f,,cmath.tau} (`τ') constant has been added.
(Contributed by Lisa Roach in bpo-12345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12345}, see 
@geindex Python Enhancement Proposals; PEP 628
PEP 628@footnote{https://peps.python.org/pep-0628/} for details.)

New constants: @ref{c70,,cmath.inf} and @ref{c71,,cmath.nan} to
match @ref{c72,,math.inf} and @ref{64e,,math.nan}, and also @ref{c73,,cmath.infj}
and @ref{c74,,cmath.nanj} to match the format used by complex repr.
(Contributed by Mark Dickinson in bpo-23229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23229}.)

@node collections<4>,concurrent futures<4>,cmath,Modules améliorés<8>
@anchor{whatsnew/3 6 collections}@anchor{c75}
@subsubsection collections


The new @ref{c76,,Collection} abstract base class has been
added to represent sized iterable container classes.
(Contributed by Ivan Levkivskyi, docs by Neil Girdhar in bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}.)

The new @ref{c77,,Reversible} abstract base class represents
iterable classes that also provide the @code{__reversed__()} method.
(Contributed by Ivan Levkivskyi in bpo-25987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25987}.)

The new @ref{c78,,AsyncGenerator} abstract base class represents
asynchronous generators.
(Contributed by Yury Selivanov in bpo-28720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28720}.)

The @ref{1c5,,namedtuple()} function now accepts an optional
keyword argument `module', which, when specified, is used for
the @ref{36a,,__module__} attribute of the returned named tuple class.
(Contributed by Raymond Hettinger in bpo-17941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17941}.)

The `verbose' and `rename' arguments for
@ref{1c5,,namedtuple()} are now keyword-only.
(Contributed by Raymond Hettinger in bpo-25628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25628}.)

Recursive @ref{5c6,,collections.deque} instances can now be pickled.
(Contributed by Serhiy Storchaka in bpo-26482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26482}.)

@node concurrent futures<4>,contextlib<4>,collections<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 concurrent-futures}@anchor{c79}
@subsubsection concurrent.futures


The @ref{72c,,ThreadPoolExecutor}
class constructor now accepts an optional `thread_name_prefix' argument
to make it possible to customize the names of the threads created by the
pool.
(Contributed by Gregory P. Smith in bpo-27664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27664}.)

@node contextlib<4>,datetime<5>,concurrent futures<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 contextlib}@anchor{c7a}
@subsubsection contextlib


The @ref{c7b,,contextlib.AbstractContextManager} class has been added to
provide an abstract base class for context managers.  It provides a
sensible default implementation for @code{__enter__()} which returns
@code{self} and leaves @code{__exit__()} an abstract method.  A matching
class has been added to the @ref{103,,typing} module as
@ref{c7c,,typing.ContextManager}.
(Contributed by Brett Cannon in bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}.)

@node datetime<5>,decimal<2>,contextlib<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 datetime}@anchor{c7d}
@subsubsection datetime


The @ref{1c7,,datetime} and @ref{1c9,,time} classes have
the new @code{fold} attribute used to disambiguate local time
when necessary.  Many functions in the @ref{30,,datetime} have been
updated to support local time disambiguation.
See @ref{c2a,,Local Time Disambiguation} section for more
information.
(Contributed by Alexander Belopolsky in bpo-24773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24773}.)

The @ref{c7e,,datetime.strftime()} and
@ref{c7f,,date.strftime()} methods now support
ISO 8601 date directives @code{%G}, @code{%u} and @code{%V}.
(Contributed by Ashley Anderson in bpo-12006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12006}.)

The @ref{b1e,,datetime.isoformat()} function
now accepts an optional `timespec' argument that specifies the number
of additional components of the time value to include.
(Contributed by Alessandro Cucci and Alexander Belopolsky in bpo-19475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19475}.)

The @ref{c80,,datetime.combine()} now
accepts an optional `tzinfo' argument.
(Contributed by Alexander Belopolsky in bpo-27661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27661}.)

@node decimal<2>,distutils<5>,datetime<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 decimal}@anchor{c81}
@subsubsection decimal


New @ref{c82,,Decimal.as_integer_ratio()}
method that returns a pair @code{(n, d)} of integers that represent the given
@ref{29a,,Decimal} instance as a fraction, in lowest terms and
with a positive denominator:

@example
>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)
@end example

(Contributed by Stefan Krah amd Mark Dickinson in bpo-25928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25928}.)

@node distutils<5>,email<2>,decimal<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 distutils}@anchor{c83}
@subsubsection distutils


The @code{default_format} attribute has been removed from
@code{distutils.command.sdist.sdist} and the @code{formats}
attribute defaults to @code{['gztar']}. Although not anticipated,
any code relying on the presence of @code{default_format} may
need to be adapted. See bpo-27819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27819} for more details.

@node email<2>,encodings<2>,distutils<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 email}@anchor{c84}
@subsubsection email


The new email API, enabled via the `policy' keyword to various constructors, is
no longer provisional.  The @ref{3b,,email} documentation has been reorganized and
rewritten to focus on the new API, while retaining the old documentation for
the legacy API.  (Contributed by R. David Murray in bpo-24277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24277}.)

The @ref{45,,email.mime} classes now all accept an optional `policy' keyword.
(Contributed by Berker Peksag in bpo-27331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27331}.)

The @ref{c85,,DecodedGenerator} now supports the `policy'
keyword.

There is a new @ref{4f,,policy} attribute,
@ref{c86,,message_factory}, that controls what class is used
by default when the parser creates new message objects.  For the
@ref{c87,,email.policy.compat32} policy this is @ref{279,,Message},
for the new policies it is @ref{278,,EmailMessage}.
(Contributed by R. David Murray in bpo-20476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20476}.)

@node encodings<2>,enum<7>,email<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 encodings}@anchor{c88}
@subsubsection @code{encodings}


On Windows, added the @code{'oem'} encoding to use @code{CP_OEMCP}, and the @code{'ansi'}
alias for the existing @code{'mbcs'} encoding, which uses the @code{CP_ACP} code page.
(Contributed by Steve Dower in bpo-27959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27959}.)

@node enum<7>,faulthandler<2>,encodings<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 enum}@anchor{c89}
@subsubsection enum


Two new enumeration base classes have been added to the @ref{55,,enum} module:
@ref{60e,,Flag} and @code{IntFlags}.  Both are used to define
constants that can be combined using the bitwise operators.
(Contributed by Ethan Furman in bpo-23591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23591}.)

Many standard library modules have been updated to use the
@code{IntFlags} class for their constants.

The new @ref{c8a,,enum.auto} value can be used to assign values to enum
members automatically:

@example
>>> from enum import Enum, auto
>>> class Color(Enum):
...     red = auto()
...     blue = auto()
...     green = auto()
...
>>> list(Color)
[<Color.red: 1>, <Color.blue: 2>, <Color.green: 3>]
@end example

@node faulthandler<2>,fileinput<2>,enum<7>,Modules améliorés<8>
@anchor{whatsnew/3 6 faulthandler}@anchor{c8b}
@subsubsection @code{faulthandler}


On Windows, the @ref{57,,faulthandler} module now installs a handler for Windows
exceptions: see @ref{c8c,,faulthandler.enable()}. (Contributed by Victor Stinner in
bpo-23848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23848}.)

@node fileinput<2>,hashlib<5>,faulthandler<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 fileinput}@anchor{c8d}
@subsubsection @code{fileinput}


@ref{c8e,,hook_encoded()} now supports the `errors' argument.
(Contributed by Joseph Hackman in bpo-25788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25788}.)

@node hashlib<5>,http client<2>,fileinput<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 hashlib}@anchor{c8f}
@subsubsection `hashlib'


@ref{67,,hashlib} supports OpenSSL 1.1.0.  The minimum recommend version is 1.0.2.
(Contributed by Christian Heimes in bpo-26470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26470}.)

BLAKE2 hash functions were added to the module. @ref{62d,,blake2b()}
and @ref{62e,,blake2s()} are always available and support the full
feature set of BLAKE2.
(Contributed by Christian Heimes in bpo-26798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26798} based on code by
Dmitry Chestnykh and Samuel Neves. Documentation written by Dmitry Chestnykh.)

The SHA-3 hash functions @ref{c90,,sha3_224()}, @ref{c91,,sha3_256()},
@ref{c92,,sha3_384()}, @ref{c93,,sha3_512()}, and SHAKE hash functions
@ref{c94,,shake_128()} and @ref{c95,,shake_256()} were added.
(Contributed by Christian Heimes in bpo-16113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16113}. Keccak Code Package
by Guido Bertoni, Joan Daemen, Michaël Peeters, Gilles Van Assche, and
Ronny Van Keer.)

The password-based key derivation function @ref{c2c,,scrypt()} is now
available with OpenSSL 1.1.0 and newer.
(Contributed by Christian Heimes in bpo-27928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27928}.)

@node http client<2>,idlelib and IDLE<2>,hashlib<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 http-client}@anchor{c96}
@subsubsection http.client


@ref{c97,,HTTPConnection.request()} and
@ref{c98,,endheaders()} both now support
chunked encoding request bodies.
(Contributed by Demian Brecht and Rolf Krahl in bpo-12319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12319}.)

@node idlelib and IDLE<2>,importlib<6>,http client<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 idlelib-and-idle}@anchor{c99}
@subsubsection idlelib and IDLE


The idlelib package is being modernized and refactored to make IDLE look and
work better and to make the code easier to understand, test, and improve. Part
of making IDLE look better, especially on Linux and Mac, is using ttk widgets,
mostly in the dialogs.  As a result, IDLE no longer runs with tcl/tk 8.4.  It
now requires tcl/tk 8.5 or 8.6.  We recommend running the latest release of
either.

'Modernizing' includes renaming and consolidation of idlelib modules. The
renaming of files with partial uppercase names is similar to the renaming of,
for instance, Tkinter and TkFont to tkinter and tkinter.font in 3.0.  As a
result, imports of idlelib files that worked in 3.5 will usually not work in
3.6.  At least a module name change will be needed (see idlelib/README.txt),
sometimes more.  (Name changes contributed by Al Swiegart and Terry Reedy in
bpo-24225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24225}.  Most idlelib patches since have been and will be part of the
process.)

In compensation, the eventual result with be that some idlelib classes will be
easier to use, with better APIs and docstrings explaining them.  Additional
useful information will be added to idlelib when available.

New in 3.6.2:

Multiple fixes for autocompletion. (Contributed by Louie Lu in bpo-15786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15786}.)

New in 3.6.3:

Module Browser (on the File menu, formerly called Class Browser),
now displays nested functions and classes in addition to top-level
functions and classes.
(Contributed by Guilherme Polo, Cheryl Sabella, and Terry Jan Reedy
in bpo-1612262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1612262}.)

The IDLE features formerly implemented as extensions have been reimplemented
as normal features.  Their settings have been moved from the Extensions tab
to other dialog tabs.
(Contributed by Charles Wohlganger and Terry Jan Reedy in bpo-27099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27099}.)

The Settings dialog (Options, Configure IDLE) has been partly rewritten
to improve both appearance and function.
(Contributed by Cheryl Sabella and Terry Jan Reedy in multiple issues.)

New in 3.6.4:

The font sample now includes a selection of non-Latin characters so that
users can better see the effect of selecting a particular font.
(Contributed by Terry Jan Reedy in bpo-13802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13802}.)
The sample can be edited to include other characters.
(Contributed by Serhiy Storchaka in bpo-31860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31860}.)

New in 3.6.6:

Editor code context option revised.  Box displays all context lines up to
maxlines.  Clicking on a context line jumps the editor to that line.  Context
colors for custom themes is added to Highlights tab of Settings dialog.
(Contributed by Cheryl Sabella and Terry Jan Reedy in bpo-33642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33642},
bpo-33768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33768}, and bpo-33679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33679}.)

On Windows, a new API call tells Windows that tk scales for DPI. On Windows
8.1+ or 10, with DPI compatibility properties of the Python binary
unchanged, and a monitor resolution greater than 96 DPI, this should
make text and lines sharper.  It should otherwise have no effect.
(Contributed by Terry Jan Reedy in bpo-33656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33656}.)

New in 3.6.7:

Output over N lines (50 by default) is squeezed down to a button.
N can be changed in the PyShell section of the General page of the
Settings dialog.  Fewer, but possibly extra long, lines can be squeezed by
right clicking on the output.  Squeezed output can be expanded in place
by double-clicking the button or into the clipboard or a separate window
by right-clicking the button.  (Contributed by Tal Einat in bpo-1529353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1529353}.)

@node importlib<6>,inspect<6>,idlelib and IDLE<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 importlib}@anchor{c9a}
@subsubsection importlib


Import now raises the new exception @ref{b35,,ModuleNotFoundError}
(subclass of @ref{40f,,ImportError}) when it cannot find a module.  Code
that current checks for @code{ImportError} (in try-except) will still work.
(Contributed by Eric Snow in bpo-15767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15767}.)

@ref{c9b,,importlib.util.LazyLoader} now calls
@ref{c9c,,create_module()} on the wrapped loader, removing the
restriction that @ref{c9d,,importlib.machinery.BuiltinImporter} and
@ref{c9e,,importlib.machinery.ExtensionFileLoader} couldn't be used with
@ref{c9b,,importlib.util.LazyLoader}.

@ref{2f2,,importlib.util.cache_from_source()},
@ref{503,,importlib.util.source_from_cache()}, and
@ref{c9f,,importlib.util.spec_from_file_location()} now accept a
@ref{29d,,path-like object}.

@node inspect<6>,json,importlib<6>,Modules améliorés<8>
@anchor{whatsnew/3 6 inspect}@anchor{ca0}
@subsubsection `inspect'


The @ref{722,,inspect.signature()} function now reports the
implicit @code{.0} parameters generated by the compiler for comprehension and
generator expression scopes as if they were positional-only parameters called
@code{implicit0}. (Contributed by Jelle Zijlstra in bpo-19611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19611}.)

To reduce code churn when upgrading from Python 2.7 and the legacy
@code{inspect.getargspec()} API, the previously documented deprecation of
@ref{723,,inspect.getfullargspec()} has been reversed. While this function is
convenient for single/source Python 2/3 code bases, the richer
@ref{722,,inspect.signature()} interface remains the recommended approach for new
code. (Contributed by Nick Coghlan in bpo-27172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27172})

@node json,logging<4>,inspect<6>,Modules améliorés<8>
@anchor{whatsnew/3 6 json}@anchor{ca1}
@subsubsection json


@ref{ca2,,json.load()} and @ref{942,,json.loads()} now support binary input.  Encoded
JSON should be represented using either UTF-8, UTF-16, or UTF-32.
(Contributed by Serhiy Storchaka in bpo-17909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17909}.)

@node logging<4>,math<7>,json,Modules améliorés<8>
@anchor{whatsnew/3 6 logging}@anchor{ca3}
@subsubsection logging


The new @ref{ca4,,WatchedFileHandler.reopenIfNeeded()}
method has been added to add the ability to check if the log file needs to
be reopened.
(Contributed by Marian Horban in bpo-24884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24884}.)

@node math<7>,multiprocessing<5>,logging<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 math}@anchor{ca5}
@subsubsection `math'


The tau (`τ') constant has been added to the @ref{8d,,math} and @ref{18,,cmath}
modules.
(Contributed by Lisa Roach in bpo-12345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12345}, see 
@geindex Python Enhancement Proposals; PEP 628
PEP 628@footnote{https://peps.python.org/pep-0628/} for details.)

@node multiprocessing<5>,os<8>,math<7>,Modules améliorés<8>
@anchor{whatsnew/3 6 multiprocessing}@anchor{ca6}
@subsubsection multiprocessing


@ref{ca7,,Proxy Objects} returned by
@ref{ca8,,multiprocessing.Manager()} can now be nested.
(Contributed by Davin Potts in bpo-6766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6766}.)

@node os<8>,pathlib<9>,multiprocessing<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 os}@anchor{ca9}
@subsubsection `os'


See the summary of @ref{c29,,PEP 519} for details on how the
@ref{a0,,os} and @ref{a1,,os.path} modules now support
@ref{29d,,path-like objects}.

@ref{a4d,,scandir()} now supports @ref{1bd,,bytes} paths on Windows.

A new @ref{caa,,close()} method allows explicitly closing a
@ref{a4d,,scandir()} iterator.  The @ref{a4d,,scandir()} iterator now
supports the @ref{5be,,context manager} protocol.  If a @code{scandir()}
iterator is neither exhausted nor explicitly closed a @ref{241,,ResourceWarning}
will be emitted in its destructor.
(Contributed by Serhiy Storchaka in bpo-25994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25994}.)

On Linux, @ref{50c,,os.urandom()} now blocks until the system urandom entropy pool
is initialized to increase the security. See the 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/} for the rationale.

The Linux @code{getrandom()} syscall (get random bytes) is now exposed as the new
@ref{cab,,os.getrandom()} function.
(Contributed by Victor Stinner, part of the 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/})

@node pathlib<9>,pdb<5>,os<8>,Modules améliorés<8>
@anchor{whatsnew/3 6 pathlib}@anchor{cac}
@subsubsection pathlib


@ref{a3,,pathlib} now supports @ref{29d,,path-like objects}.
(Contributed by Brett Cannon in bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}.)

See the summary of @ref{c29,,PEP 519} for details.

@node pdb<5>,pickle<2>,pathlib<9>,Modules améliorés<8>
@anchor{whatsnew/3 6 pdb}@anchor{cad}
@subsubsection `pdb'


The @ref{90f,,Pdb} class constructor has a new optional `readrc' argument
to control whether @code{.pdbrc} files should be read.

@node pickle<2>,pickletools,pdb<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 pickle}@anchor{cae}
@subsubsection pickle


Objects that need @code{__new__} called with keyword arguments can now be pickled
using @ref{caf,,pickle protocols} older than protocol version 4.
Protocol version 4 already supports this case.  (Contributed by Serhiy
Storchaka in bpo-24164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24164}.)

@node pickletools,pydoc<3>,pickle<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 pickletools}@anchor{cb0}
@subsubsection pickletools


@ref{cb1,,pickletools.dis()} now outputs the implicit memo index for the
@code{MEMOIZE} opcode.
(Contributed by Serhiy Storchaka in bpo-25382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25382}.)

@node pydoc<3>,random<4>,pickletools,Modules améliorés<8>
@anchor{whatsnew/3 6 pydoc}@anchor{cb2}
@subsubsection `pydoc'


The @ref{b4,,pydoc} module has learned to respect the @code{MANPAGER}
environment variable.
(Contributed by Matthias Klose in bpo-8637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8637}.)

@ref{8c4,,help()} and @ref{b4,,pydoc} can now list named tuple fields in the
order they were defined rather than alphabetically.
(Contributed by Raymond Hettinger in bpo-24879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24879}.)

@node random<4>,re<5>,pydoc<3>,Modules améliorés<8>
@anchor{whatsnew/3 6 random}@anchor{cb3}
@subsubsection `random'


The new @ref{cb4,,choices()} function returns a list of elements of
specified size from the given population with optional weights.
(Contributed by Raymond Hettinger in bpo-18844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18844}.)

@node re<5>,readline,random<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 re}@anchor{cb5}
@subsubsection @code{re}


Added support of modifier spans in regular expressions.  Examples:
@code{'(?i:p)ython'} matches @code{'python'} and @code{'Python'}, but not @code{'PYTHON'};
@code{'(?i)g(?-i:v)r'} matches @code{'GvR'} and @code{'gvr'}, but not @code{'GVR'}.
(Contributed by Serhiy Storchaka in bpo-433028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=433028}.)

Match object groups can be accessed by @code{__getitem__}, which is
equivalent to @code{group()}.  So @code{mo['name']} is now equivalent to
@code{mo.group('name')}.  (Contributed by Eric Smith in bpo-24454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24454}.)

@ref{cb6,,Match} objects now support
@ref{707,,index-like objects} as group
indices.
(Contributed by Jeroen Demeyer and Xiang Zhang in bpo-27177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27177}.)

@node readline,rlcompleter,re<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 readline}@anchor{cb7}
@subsubsection readline


Added @ref{cb8,,set_auto_history()} to enable or disable
automatic addition of input to the history list.  (Contributed by
Tyler Crompton in bpo-26870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26870}.)

@node rlcompleter,shlex<2>,readline,Modules améliorés<8>
@anchor{whatsnew/3 6 rlcompleter}@anchor{cb9}
@subsubsection rlcompleter


Private and special attribute names now are omitted unless the prefix starts
with underscores.  A space or a colon is added after some completed keywords.
(Contributed by Serhiy Storchaka in bpo-25011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25011} and bpo-25209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25209}.)

@node shlex<2>,site<3>,rlcompleter,Modules améliorés<8>
@anchor{whatsnew/3 6 shlex}@anchor{cba}
@subsubsection shlex


The @ref{cbb,,shlex} has much
@ref{cbc,,improved shell compatibility}
through the new `punctuation_chars' argument to control which characters
are treated as punctuation.
(Contributed by Vinay Sajip in bpo-1521950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1521950}.)

@node site<3>,sqlite3<7>,shlex<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 site}@anchor{cbd}
@subsubsection @code{site}


When specifying paths to add to @ref{3ab,,sys.path} in a @code{.pth} file,
you may now specify file paths on top of directories (e.g. zip files).
(Contributed by Wolfgang Langner in bpo-26587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26587}).

@node sqlite3<7>,socket<7>,site<3>,Modules améliorés<8>
@anchor{whatsnew/3 6 sqlite3}@anchor{cbe}
@subsubsection @code{sqlite3}


@ref{cbf,,sqlite3.Cursor.lastrowid} now supports the @code{REPLACE} statement.
(Contributed by Alex LordThorsen in bpo-16864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16864}.)

@node socket<7>,socketserver<2>,sqlite3<7>,Modules améliorés<8>
@anchor{whatsnew/3 6 socket}@anchor{cc0}
@subsubsection `socket'


The @ref{cc1,,ioctl()} function now supports the
@ref{cc2,,SIO_LOOPBACK_FAST_PATH} control code.
(Contributed by Daniel Stokes in bpo-26536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26536}.)

The @ref{cc3,,getsockopt()} constants @code{SO_DOMAIN},
@code{SO_PROTOCOL}, @code{SO_PEERSEC}, and @code{SO_PASSSEC} are now supported.
(Contributed by Christian Heimes in bpo-26907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26907}.)

The @ref{cc4,,setsockopt()} now supports the
@code{setsockopt(level, optname, None, optlen: int)} form.
(Contributed by Christian Heimes in bpo-27744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27744}.)

The socket module now supports the address family
@ref{cc5,,AF_ALG} to interface with Linux Kernel crypto API. @code{ALG_*},
@code{SOL_ALG} and @ref{cc6,,sendmsg_afalg()} were added.
(Contributed by Christian Heimes in bpo-27744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27744} with support from
Victor Stinner.)

New Linux constants @code{TCP_USER_TIMEOUT} and @code{TCP_CONGESTION} were added.
(Contributed by Omar Sandoval, bpo-26273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26273}).

@node socketserver<2>,ssl<7>,socket<7>,Modules améliorés<8>
@anchor{whatsnew/3 6 socketserver}@anchor{cc7}
@subsubsection socketserver


Servers based on the @ref{cc,,socketserver} module, including those
defined in @ref{71,,http.server}, @ref{12e,,xmlrpc.server} and
@ref{11a,,wsgiref.simple_server}, now support the @ref{5be,,context manager}
protocol.
(Contributed by Aviv Palivoda in bpo-26404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26404}.)

The @code{wfile} attribute of
@ref{cc8,,StreamRequestHandler} classes now implements
the @ref{67f,,io.BufferedIOBase} writable interface.  In particular,
calling @ref{cc9,,write()} is now guaranteed to send the
data in full.  (Contributed by Martin Panter in bpo-26721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26721}.)

@node ssl<7>,statistics<5>,socketserver<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 ssl}@anchor{cca}
@subsubsection @code{ssl}


@ref{cf,,ssl} supports OpenSSL 1.1.0.  The minimum recommend version is 1.0.2.
(Contributed by Christian Heimes in bpo-26470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26470}.)

3DES has been removed from the default cipher suites and ChaCha20 Poly1305
cipher suites have been added.
(Contributed by Christian Heimes in bpo-27850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27850} and bpo-27766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27766}.)

@ref{291,,SSLContext} has better default configuration for options
and ciphers.
(Contributed by Christian Heimes in bpo-28043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28043}.)

SSL session can be copied from one client-side connection to another
with the new @ref{ccb,,SSLSession} class.  TLS session resumption can
speed up the initial handshake, reduce latency and improve performance
(Contributed by Christian Heimes in bpo-19500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19500} based on a draft by
Alex Warhawk.)

The new @ref{ccc,,get_ciphers()} method can be used to
get a list of enabled ciphers in order of cipher priority.

All constants and flags have been converted to @ref{ccd,,IntEnum} and
@code{IntFlags}.
(Contributed by Christian Heimes in bpo-28025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28025}.)

Server and client-side specific TLS protocols for @ref{291,,SSLContext}
were added.
(Contributed by Christian Heimes in bpo-28085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28085}.)

Added @ref{a1f,,ssl.SSLContext.post_handshake_auth} to enable and
@ref{a20,,ssl.SSLSocket.verify_client_post_handshake()} to initiate TLS 1.3
post-handshake authentication.
(Contributed by Christian Heimes in gh-78851@footnote{https://github.com/python/cpython/issues/78851}.)

@node statistics<5>,struct,ssl<7>,Modules améliorés<8>
@anchor{whatsnew/3 6 statistics}@anchor{cce}
@subsubsection @code{statistics}


A new @ref{ccf,,harmonic_mean()} function has been added.
(Contributed by Steven D'Aprano in bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181}.)

@node struct,subprocess<3>,statistics<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 struct}@anchor{cd0}
@subsubsection struct


@ref{d4,,struct} now supports IEEE 754 half-precision floats via the @code{'e'}
format specifier.
(Contributed by Eli Stevens, Mark Dickinson in bpo-11734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11734}.)

@node subprocess<3>,sys<10>,struct,Modules améliorés<8>
@anchor{whatsnew/3 6 subprocess}@anchor{cd1}
@subsubsection subprocess


@ref{197,,subprocess.Popen} destructor now emits a @ref{241,,ResourceWarning} warning
if the child process is still running. Use the context manager protocol (@code{with
proc: ...}) or explicitly call the @ref{cd2,,wait()} method to
read the exit status of the child process. (Contributed by Victor Stinner in
bpo-26741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26741}.)

The @ref{197,,subprocess.Popen} constructor and all functions that pass arguments
through to it now accept `encoding' and `errors' arguments. Specifying either
of these will enable text mode for the `stdin', `stdout' and `stderr' streams.
(Contributed by Steve Dower in bpo-6135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6135}.)

@node sys<10>,telnetlib,subprocess<3>,Modules améliorés<8>
@anchor{whatsnew/3 6 sys}@anchor{cd3}
@subsubsection sys


The new @ref{cd4,,getfilesystemencodeerrors()} function returns the name of
the error mode used to convert between Unicode filenames and bytes filenames.
(Contributed by Steve Dower in bpo-27781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27781}.)

On Windows the return value of the @ref{cd5,,getwindowsversion()} function
now includes the `platform_version' field which contains the accurate major
version, minor version and build number of the current operating system,
rather than the version that is being emulated for the process
(Contributed by Steve Dower in bpo-27932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27932}.)

@node telnetlib,time<6>,sys<10>,Modules améliorés<8>
@anchor{whatsnew/3 6 telnetlib}@anchor{cd6}
@subsubsection telnetlib


@code{telnetlib.Telnet} is now a context manager (contributed by
Stéphane Wirtel in bpo-25485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25485}).

@node time<6>,timeit,telnetlib,Modules améliorés<8>
@anchor{whatsnew/3 6 time}@anchor{cd7}
@subsubsection time


The @ref{cd8,,struct_time} attributes @code{tm_gmtoff} and
@code{tm_zone} are now available on all platforms.

@node timeit,tkinter<6>,time<6>,Modules améliorés<8>
@anchor{whatsnew/3 6 timeit}@anchor{cd9}
@subsubsection timeit


The new @ref{cda,,Timer.autorange()} convenience
method has been added to call @ref{cdb,,Timer.timeit()}
repeatedly so that the total run time is greater or equal to 200 milliseconds.
(Contributed by Steven D'Aprano in bpo-6422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6422}.)

@ref{ee,,timeit} now warns when there is substantial (4x) variance
between best and worst times.
(Contributed by Serhiy Storchaka in bpo-23552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23552}.)

@node tkinter<6>,traceback<4>,timeit,Modules améliorés<8>
@anchor{whatsnew/3 6 tkinter}@anchor{cdc}
@subsubsection tkinter


Added methods @code{trace_add()},
@code{trace_remove()} and @code{trace_info()}
in the @code{tkinter.Variable} class.  They replace old methods
@code{trace_variable()}, @code{trace()},
@code{trace_vdelete()} and
@code{trace_vinfo()} that use obsolete Tcl commands and might
not work in future versions of Tcl.
(Contributed by Serhiy Storchaka in bpo-22115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22115}).

@node traceback<4>,tracemalloc<3>,tkinter<6>,Modules améliorés<8>
@anchor{whatsnew/3 6 traceback}@anchor{cdd}@anchor{whatsnew/3 6 whatsnew36-traceback}@anchor{c5d}
@subsubsection traceback


Both the traceback module and the interpreter's builtin exception display now
abbreviate long sequences of repeated lines in tracebacks as shown in the
following example:

@example
>>> def f(): f()
...
>>> f()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 1, in f
  File "<stdin>", line 1, in f
  File "<stdin>", line 1, in f
  [Previous line repeated 995 more times]
RecursionError: maximum recursion depth exceeded
@end example

(Contributed by Emanuel Barry in bpo-26823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26823}.)

@node tracemalloc<3>,typing<9>,traceback<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 tracemalloc}@anchor{cde}
@subsubsection tracemalloc


The @ref{fe,,tracemalloc} module now supports tracing memory allocations in
multiple different address spaces.

The new @ref{cdf,,DomainFilter} filter class has been added
to filter block traces by their address space (domain).

(Contributed by Victor Stinner in bpo-26588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26588}.)

@node typing<9>,unicodedata<7>,tracemalloc<3>,Modules améliorés<8>
@anchor{whatsnew/3 6 typing}@anchor{ce0}@anchor{whatsnew/3 6 whatsnew36-typing}@anchor{c2b}
@subsubsection `typing'


Since the @ref{103,,typing} module is @ref{af1,,provisional},
all changes introduced in Python 3.6 have also been
backported to Python 3.5.x.

The @ref{103,,typing} module has a much improved support for generic type
aliases.  For example @code{Dict[str, Tuple[S, T]]} is now a valid
type annotation.
(Contributed by Guido van Rossum in Github #195@footnote{https://github.com/python/typing/pull/195}.)

The @ref{c7c,,typing.ContextManager} class has been added for
representing @ref{c7b,,contextlib.AbstractContextManager}.
(Contributed by Brett Cannon in bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}.)

The @ref{ce1,,typing.Collection} class has been added for
representing @ref{c76,,collections.abc.Collection}.
(Contributed by Ivan Levkivskyi in bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}.)

The @ref{263,,typing.ClassVar} type construct has been added to
mark class variables.  As introduced in 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}, a variable annotation
wrapped in ClassVar indicates that a given attribute is intended to be used as
a class variable and should not be set on instances of that class.
(Contributed by Ivan Levkivskyi in Github #280@footnote{https://github.com/python/typing/pull/280}.)

A new @ref{ce2,,TYPE_CHECKING} constant that is assumed to be
@code{True} by the static type checkers, but is @code{False} at runtime.
(Contributed by Guido van Rossum in Github #230@footnote{https://github.com/python/typing/issues/230}.)

A new @ref{ce3,,NewType()} helper function has been added to create
lightweight distinct types for annotations:

@example
from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)
@end example

The static type checker will treat the new type as if it were a subclass
of the original type.  (Contributed by Ivan Levkivskyi in Github #189@footnote{https://github.com/python/typing/issues/189}.)

@node unicodedata<7>,unittest mock<2>,typing<9>,Modules améliorés<8>
@anchor{whatsnew/3 6 unicodedata}@anchor{ce4}
@subsubsection unicodedata


The @ref{104,,unicodedata} module now uses data from Unicode 9.0.0@footnote{https://unicode.org/versions/Unicode9.0.0/}.
(Contributed by Benjamin Peterson.)

@node unittest mock<2>,urllib request,unicodedata<7>,Modules améliorés<8>
@anchor{whatsnew/3 6 unittest-mock}@anchor{ce5}
@subsubsection unittest.mock


The @ref{a3a,,Mock} class has the following improvements:


@itemize *

@item 
Two new methods, @ref{ce6,,Mock.assert_called()} and @ref{ce7,,Mock.assert_called_once()} to check if the mock object
was called.
(Contributed by Amit Saha in bpo-26323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26323}.)

@item 
The @ref{ce8,,Mock.reset_mock()} method
now has two optional keyword only arguments: `return_value' and
`side_effect'.
(Contributed by Kushal Das in bpo-21271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21271}.)
@end itemize

@node urllib request,urllib robotparser,unittest mock<2>,Modules améliorés<8>
@anchor{whatsnew/3 6 urllib-request}@anchor{ce9}
@subsubsection urllib.request


If a HTTP request has a file or iterable body (other than a
bytes object) but no @code{Content-Length} header, rather than
throwing an error, @code{AbstractHTTPHandler} now
falls back to use chunked transfer encoding.
(Contributed by Demian Brecht and Rolf Krahl in bpo-12319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12319}.)

@node urllib robotparser,venv<5>,urllib request,Modules améliorés<8>
@anchor{whatsnew/3 6 urllib-robotparser}@anchor{cea}
@subsubsection urllib.robotparser


@ref{ceb,,RobotFileParser} now supports the @code{Crawl-delay} and
@code{Request-rate} extensions.
(Contributed by Nikolay Bogoychev in bpo-16099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16099}.)

@node venv<5>,warnings<4>,urllib robotparser,Modules améliorés<8>
@anchor{whatsnew/3 6 venv}@anchor{cec}
@subsubsection venv


@ref{110,,venv} accepts a new parameter @code{--prompt}. This parameter provides an
alternative prefix for the virtual environment. (Proposed by Łukasz Balcerzak
and ported to 3.6 by Stéphane Wirtel in bpo-22829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22829}.)

@node warnings<4>,winreg,venv<5>,Modules améliorés<8>
@anchor{whatsnew/3 6 warnings}@anchor{ced}
@subsubsection warnings


A new optional `source' parameter has been added to the
@ref{cee,,warnings.warn_explicit()} function: the destroyed object which emitted a
@ref{241,,ResourceWarning}. A `source' attribute has also been added to
@code{warnings.WarningMessage} (contributed by Victor Stinner in
bpo-26568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26568} and bpo-26567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26567}).

When a @ref{241,,ResourceWarning} warning is logged, the @ref{fe,,tracemalloc} module is now
used to try to retrieve the traceback where the destroyed object was allocated.

Example with the script @code{example.py}:

@example
import warnings

def func():
    return open(__file__)

f = func()
f = None
@end example

Output of the command @code{python3.6 -Wd -X tracemalloc=5 example.py}:

@example
example.py:7: ResourceWarning: unclosed file <_io.TextIOWrapper name='example.py' mode='r' encoding='UTF-8'>
  f = None
Object allocated at (most recent call first):
  File "example.py", lineno 4
    return open(__file__)
  File "example.py", lineno 6
    f = func()
@end example

The "Object allocated at" traceback is new and is only displayed if
@ref{fe,,tracemalloc} is tracing Python memory allocations and if the
@ref{111,,warnings} module was already imported.

@node winreg,winsound,warnings<4>,Modules améliorés<8>
@anchor{whatsnew/3 6 winreg}@anchor{cef}
@subsubsection winreg


Added the 64-bit integer type @ref{cf0,,REG_QWORD}.
(Contributed by Clement Rouault in bpo-23026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23026}.)

@node winsound,xmlrpc client,winreg,Modules améliorés<8>
@anchor{whatsnew/3 6 winsound}@anchor{cf1}
@subsubsection winsound


Allowed keyword arguments to be passed to @ref{cf2,,Beep},
@ref{cf3,,MessageBeep}, and @ref{cf4,,PlaySound} (bpo-27982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27982}).

@node xmlrpc client,zipfile<3>,winsound,Modules améliorés<8>
@anchor{whatsnew/3 6 xmlrpc-client}@anchor{cf5}
@subsubsection xmlrpc.client


The @ref{12d,,xmlrpc.client} module now supports unmarshalling
additional data types used by the Apache XML-RPC implementation
for numerics and @code{None}.
(Contributed by Serhiy Storchaka in bpo-26885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26885}.)

@node zipfile<3>,zlib,xmlrpc client,Modules améliorés<8>
@anchor{whatsnew/3 6 zipfile}@anchor{cf6}
@subsubsection zipfile


A new @ref{cf7,,ZipInfo.from_file()} class method
allows making a @ref{cf8,,ZipInfo} instance from a filesystem file.
A new @ref{cf9,,ZipInfo.is_dir()} method can be used
to check if the @ref{cf8,,ZipInfo} instance represents a directory.
(Contributed by Thomas Kluyver in bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}.)

The @ref{411,,ZipFile.open()} method can now be used to
write data into a ZIP file, as well as for extracting data.
(Contributed by Thomas Kluyver in bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}.)

@node zlib,,zipfile<3>,Modules améliorés<8>
@anchor{whatsnew/3 6 zlib}@anchor{cfa}
@subsubsection zlib


The @ref{62a,,compress()} and @ref{cfb,,decompress()} functions now accept
keyword arguments.
(Contributed by Aviv Palivoda in bpo-26243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26243} and
Xiang Zhang in bpo-16764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16764} respectively.)

@node Optimizations<3>,Build and C API Changes<2>,Modules améliorés<8>,What's New In Python 3 6
@anchor{whatsnew/3 6 optimizations}@anchor{cfc}
@subsection Optimizations



@itemize *

@item 
The Python interpreter now uses a 16-bit wordcode instead of bytecode which
made a number of opcode optimizations possible.
(Contributed by Demur Rumed with input and reviews from
Serhiy Storchaka and Victor Stinner in bpo-26647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26647} and bpo-28050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28050}.)

@item 
The @ref{bbb,,asyncio.Future} class now has an optimized C implementation.
(Contributed by Yury Selivanov and INADA Naoki in bpo-26081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26081}.)

@item 
The @ref{4c2,,asyncio.Task} class now has an optimized
C implementation. (Contributed by Yury Selivanov in bpo-28544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28544}.)

@item 
Various implementation improvements in the @ref{103,,typing} module
(such as caching of generic types) allow up to 30 times performance
improvements and reduced memory footprint.

@item 
The ASCII decoder is now up to 60 times as fast for error handlers
@code{surrogateescape}, @code{ignore} and @code{replace} (Contributed
by Victor Stinner in bpo-24870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24870}).

@item 
The ASCII and the Latin1 encoders are now up to 3 times as fast for the
error handler @code{surrogateescape}
(Contributed by Victor Stinner in bpo-25227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25227}).

@item 
The UTF-8 encoder is now up to 75 times as fast for error handlers
@code{ignore}, @code{replace}, @code{surrogateescape}, @code{surrogatepass} (Contributed
by Victor Stinner in bpo-25267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25267}).

@item 
The UTF-8 decoder is now up to 15 times as fast for error handlers
@code{ignore}, @code{replace} and @code{surrogateescape} (Contributed
by Victor Stinner in bpo-25301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25301}).

@item 
@code{bytes % args} is now up to 2 times faster. (Contributed by Victor Stinner
in bpo-25349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25349}).

@item 
@code{bytearray % args} is now between 2.5 and 5 times faster. (Contributed by
Victor Stinner in bpo-25399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25399}).

@item 
Optimize @ref{add,,bytes.fromhex()} and @ref{ade,,bytearray.fromhex()}: they are now
between 2x and 3.5x faster. (Contributed by Victor Stinner in bpo-25401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25401}).

@item 
Optimize @code{bytes.replace(b'@w{'}, b'.')} and @code{bytearray.replace(b'@w{'}, b'.')}:
up to 80% faster. (Contributed by Josh Snider in bpo-26574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26574}).

@item 
Allocator functions of the @ref{c54,,PyMem_Malloc()} domain
(@ref{c57,,PYMEM_DOMAIN_MEM}) now use the @ref{cfd,,pymalloc memory allocator} instead of @code{malloc()} function of the C library. The
pymalloc allocator is optimized for objects smaller or equal to 512 bytes
with a short lifetime, and use @code{malloc()} for larger memory blocks.
(Contributed by Victor Stinner in bpo-26249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26249}).

@item 
@ref{cfe,,pickle.load()} and @ref{cff,,pickle.loads()} are now up to 10% faster when
deserializing many small objects (Contributed by Victor Stinner in
bpo-27056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27056}).

@item 
Passing @ref{d00,,keyword arguments} to a function has an
overhead in comparison with passing @ref{d01,,positional arguments}.  Now in extension functions implemented with using
Argument Clinic this overhead is significantly decreased.
(Contributed by Serhiy Storchaka in bpo-27574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27574}).

@item 
Optimized @ref{29c,,glob()} and @ref{7f1,,iglob()} functions in the
@ref{63,,glob} module; they are now about 3--6 times faster.
(Contributed by Serhiy Storchaka in bpo-25596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25596}).

@item 
Optimized globbing in @ref{a3,,pathlib} by using @ref{a4d,,os.scandir()};
it is now about 1.5--4 times faster.
(Contributed by Serhiy Storchaka in bpo-26032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26032}).

@item 
@ref{124,,xml.etree.ElementTree} parsing, iteration and deepcopy performance
has been significantly improved.
(Contributed by Serhiy Storchaka in bpo-25638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25638}, bpo-25873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25873},
and bpo-25869@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25869}.)

@item 
Creation of @ref{1e4,,fractions.Fraction} instances from floats and
decimals is now 2 to 3 times faster.
(Contributed by Serhiy Storchaka in bpo-25971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25971}.)
@end itemize

@node Build and C API Changes<2>,Autres Améliorations,Optimizations<3>,What's New In Python 3 6
@anchor{whatsnew/3 6 build-and-c-api-changes}@anchor{d02}
@subsection Build and C API Changes



@itemize *

@item 
Python now requires some C99 support in the toolchain to build.
Most notably, Python now uses standard integer types and macros in
place of custom macros like @code{PY_LONG_LONG}.
For more information, see 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/} and bpo-17884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17884}.

@item 
Cross-compiling CPython with the Android NDK and the Android API level set to
21 (Android 5.0 Lollipop) or greater runs successfully. While Android is not
yet a supported platform, the Python test suite runs on the Android emulator
with only about 16 tests failures. See the Android meta-issue bpo-26865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26865}.

@item 
The @code{--enable-optimizations} configure flag has been added. Turning it on
will activate expensive optimizations like PGO.
(Original patch by Alecsandru Patrascu of Intel in bpo-26359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26359}.)

@item 
The @ref{147,,GIL} must now be held when allocator
functions of @ref{c55,,PYMEM_DOMAIN_OBJ} (ex: @ref{c56,,PyObject_Malloc()}) and
@ref{c57,,PYMEM_DOMAIN_MEM} (ex: @ref{c54,,PyMem_Malloc()}) domains are called.

@item 
New @ref{d03,,Py_FinalizeEx()} API which indicates if flushing buffered data
failed.
(Contributed by Martin Panter in bpo-5319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5319}.)

@item 
@ref{379,,PyArg_ParseTupleAndKeywords()} now supports @ref{a73,,positional-only parameters}.  Positional-only parameters are
defined by empty names.
(Contributed by Serhiy Storchaka in bpo-26282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26282}).

@item 
@code{PyTraceback_Print} method now abbreviates long sequences of repeated lines
as @code{"[Previous line repeated @{count@} more times]"}.
(Contributed by Emanuel Barry in bpo-26823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26823}.)

@item 
The new @ref{d04,,PyErr_SetImportErrorSubclass()} function allows for
specifying a subclass of @ref{40f,,ImportError} to raise.
(Contributed by Eric Snow in bpo-15767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15767}.)

@item 
The new @ref{d05,,PyErr_ResourceWarning()} function can be used to generate
a @ref{241,,ResourceWarning} providing the source of the resource allocation.
(Contributed by Victor Stinner in bpo-26567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26567}.)

@item 
The new @ref{d06,,PyOS_FSPath()} function returns the file system
representation of a @ref{29d,,path-like object}.
(Contributed by Brett Cannon in bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}.)

@item 
The @ref{d07,,PyUnicode_FSConverter()} and @ref{563,,PyUnicode_FSDecoder()}
functions will now accept @ref{29d,,path-like objects}.
@end itemize

@node Autres Améliorations,Obsolescence<9>,Build and C API Changes<2>,What's New In Python 3 6
@anchor{whatsnew/3 6 other-improvements}@anchor{d08}
@subsection Autres Améliorations



@itemize *

@item 
When @ref{d09,,--version} (short form: @ref{176,,-V}) is supplied twice,
Python prints @ref{177,,sys.version} for detailed information.

@example
$ ./python -VV
Python 3.6.0b4+ (3.6:223967b49e49+, Nov 21 2016, 20:55:04)
[GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.42.1)]
@end example
@end itemize

@node Obsolescence<9>,Retraits<7>,Autres Améliorations,What's New In Python 3 6
@anchor{whatsnew/3 6 deprecated}@anchor{d0a}
@subsection Obsolescence


@menu
* Nouveaux mot-clefs:: 
* Deprecated Python behavior:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<2>. 
* xml: xml<6>. 
* Deprecated functions and types of the C API: Deprecated functions and types of the C API<2>. 
* Deprecated Build Options:: 

@end menu

@node Nouveaux mot-clefs,Deprecated Python behavior,,Obsolescence<9>
@anchor{whatsnew/3 6 new-keywords}@anchor{d0b}
@subsubsection Nouveaux mot-clefs


@code{async} and @code{await} are not recommended to be used as variable, class,
function or module names.  Introduced by 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} in Python 3.5, they will
become proper keywords in Python 3.7.  Starting in Python 3.6, the use of
@code{async} or @code{await} as names will generate a @ref{1a3,,DeprecationWarning}.

@node Deprecated Python behavior,Deprecated Python modules functions and methods<2>,Nouveaux mot-clefs,Obsolescence<9>
@anchor{whatsnew/3 6 deprecated-python-behavior}@anchor{d0c}
@subsubsection Deprecated Python behavior


Raising the @ref{be8,,StopIteration} exception inside a generator will now
generate a @ref{1a3,,DeprecationWarning}, and will trigger a @ref{193,,RuntimeError}
in Python 3.7.  See @ref{d0d,,PEP 479; Change StopIteration handling inside generators} for details.

The @code{__aiter__()} method is now expected to return an asynchronous
iterator directly instead of returning an awaitable as previously.
Doing the former will trigger a @ref{1a3,,DeprecationWarning}.  Backward
compatibility will be removed in Python 3.7.
(Contributed by Yury Selivanov in bpo-27243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27243}.)

A backslash-character pair that is not a valid escape sequence now generates
a @ref{1a3,,DeprecationWarning}.  Although this will eventually become a
@ref{18b,,SyntaxError}, that will not be for several Python releases.
(Contributed by Emanuel Barry in bpo-27364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27364}.)

When performing a relative import, falling back on @code{__name__} and
@code{__path__} from the calling module when @code{__spec__} or
@code{__package__} are not defined now raises an @ref{4e4,,ImportWarning}.
(Contributed by Rose Ames in bpo-25791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25791}.)

@node Deprecated Python modules functions and methods<2>,xml<6>,Deprecated Python behavior,Obsolescence<9>
@anchor{whatsnew/3 6 deprecated-python-modules-functions-and-methods}@anchor{d0e}
@subsubsection Deprecated Python modules, functions and methods


@menu
* asynchat:: 
* asyncore:: 
* dbm: dbm<4>. 
* distutils: distutils<6>. 
* grp:: 
* importlib: importlib<7>. 
* os: os<9>. 
* re: re<6>. 
* ssl: ssl<8>. 
* tkinter: tkinter<7>. 
* venv: venv<6>. 

@end menu

@node asynchat,asyncore,,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 asynchat}@anchor{d0f}
@subsubsection asynchat


The @code{asynchat} has been deprecated in favor of @ref{a,,asyncio}.
(Contributed by Mariatta in bpo-25002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25002}.)

@node asyncore,dbm<4>,asynchat,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 asyncore}@anchor{d10}
@subsubsection asyncore


The @code{asyncore} has been deprecated in favor of @ref{a,,asyncio}.
(Contributed by Mariatta in bpo-25002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25002}.)

@node dbm<4>,distutils<6>,asyncore,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 dbm}@anchor{d11}
@subsubsection dbm


Unlike other @ref{31,,dbm} implementations, the @ref{32,,dbm.dumb} module
creates databases with the @code{'rw'} mode and allows modifying the database
opened with the @code{'r'} mode.  This behavior is now deprecated and will
be removed in 3.8.
(Contributed by Serhiy Storchaka in bpo-21708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21708}.)

@node distutils<6>,grp,dbm<4>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id2}@anchor{d12}
@subsubsection distutils


The undocumented @code{extra_path} argument to the
@code{distutils.Distribution} constructor is now considered deprecated
and will raise a warning if set.   Support for this parameter will be
removed in a future Python release.  See bpo-27919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27919} for details.

@node grp,importlib<7>,distutils<6>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 grp}@anchor{d13}
@subsubsection grp


The support of non-integer arguments in @ref{d14,,getgrgid()} has been
deprecated.
(Contributed by Serhiy Storchaka in bpo-26129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26129}.)

@node importlib<7>,os<9>,grp,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id3}@anchor{d15}
@subsubsection importlib


The @ref{d16,,importlib.machinery.SourceFileLoader.load_module()} and
@ref{d17,,importlib.machinery.SourcelessFileLoader.load_module()} methods
are now deprecated. They were the only remaining implementations of
@ref{854,,importlib.abc.Loader.load_module()} in @ref{76,,importlib} that had not
been deprecated in previous versions of Python in favour of
@ref{855,,importlib.abc.Loader.exec_module()}.

The @ref{d18,,importlib.machinery.WindowsRegistryFinder} class is now
deprecated. As of 3.6.0, it is still added to @ref{d19,,sys.meta_path} by
default (on Windows), but this may change in future releases.

@node os<9>,re<6>,importlib<7>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id4}@anchor{d1a}
@subsubsection `os'


Undocumented support of general @ref{d1b,,bytes-like objects}
as paths in @ref{a0,,os} functions, @ref{190,,compile()} and similar functions is
now deprecated.
(Contributed by Serhiy Storchaka in bpo-25791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25791} and bpo-26754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26754}.)

@node re<6>,ssl<8>,os<9>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id5}@anchor{d1c}
@subsubsection @code{re}


Support for inline flags @code{(?letters)} in the middle of the regular
expression has been deprecated and will be removed in a future Python
version.  Flags at the start of a regular expression are still allowed.
(Contributed by Serhiy Storchaka in bpo-22493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22493}.)

@node ssl<8>,tkinter<7>,re<6>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id6}@anchor{d1d}
@subsubsection @code{ssl}


OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.
In the future the @ref{cf,,ssl} module will require at least OpenSSL 1.0.2 or
1.1.0.

SSL-related arguments like @code{certfile}, @code{keyfile} and @code{check_hostname}
in @ref{5d,,ftplib}, @ref{6e,,http.client}, @ref{73,,imaplib}, @ref{ab,,poplib},
and @ref{c9,,smtplib} have been deprecated in favor of @code{context}.
(Contributed by Christian Heimes in bpo-28022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28022}.)

A couple of protocols and functions of the @ref{cf,,ssl} module are now
deprecated. Some features will no longer be available in future versions
of OpenSSL. Other features are deprecated in favor of a different API.
(Contributed by Christian Heimes in bpo-28022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28022} and bpo-26470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26470}.)

@node tkinter<7>,venv<6>,ssl<8>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id7}@anchor{d1e}
@subsubsection tkinter


The @code{tkinter.tix} module is now deprecated.  @ref{ef,,tkinter} users
should use @ref{f8,,tkinter.ttk} instead.

@node venv<6>,,tkinter<7>,Deprecated Python modules functions and methods<2>
@anchor{whatsnew/3 6 id8}@anchor{d1f}@anchor{whatsnew/3 6 whatsnew36-venv}@anchor{d20}
@subsubsection venv


The @code{pyvenv} script has been deprecated in favour of @code{python3 -m venv}.
This prevents confusion as to what Python interpreter @code{pyvenv} is
connected to and thus what Python interpreter will be used by the virtual
environment.  (Contributed by Brett Cannon in bpo-25154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25154}.)

@node xml<6>,Deprecated functions and types of the C API<2>,Deprecated Python modules functions and methods<2>,Obsolescence<9>
@anchor{whatsnew/3 6 xml}@anchor{d21}
@subsubsection `xml'



@itemize *

@item 
As mitigation against DTD and external entity retrieval, the
@ref{121,,xml.dom.minidom} and @ref{128,,xml.sax} modules no longer process
external entities by default.
(Contributed by Christian Heimes in gh-61441@footnote{https://github.com/python/cpython/issues/61441}.)
@end itemize

@node Deprecated functions and types of the C API<2>,Deprecated Build Options,xml<6>,Obsolescence<9>
@anchor{whatsnew/3 6 deprecated-functions-and-types-of-the-c-api}@anchor{d22}
@subsubsection Deprecated functions and types of the C API


Undocumented functions @code{PyUnicode_AsEncodedObject()},
@code{PyUnicode_AsDecodedObject()}, @code{PyUnicode_AsEncodedUnicode()}
and @code{PyUnicode_AsDecodedUnicode()} are deprecated now.
Use the @ref{d23,,generic codec based API} instead.

@node Deprecated Build Options,,Deprecated functions and types of the C API<2>,Obsolescence<9>
@anchor{whatsnew/3 6 deprecated-build-options}@anchor{d24}
@subsubsection Deprecated Build Options


The @code{--with-system-ffi} configure flag is now on by default on non-macOS
UNIX platforms.  It may be disabled by using @code{--without-system-ffi}, but
using the flag is deprecated and will not be accepted in Python 3.7.
macOS is unaffected by this change.  Note that many OS distributors already
use the @code{--with-system-ffi} flag when building their system Python.

@node Retraits<7>,Porting to Python 3 6,Obsolescence<9>,What's New In Python 3 6
@anchor{whatsnew/3 6 removed}@anchor{d25}
@subsection Retraits


@menu
* API and Feature Removals: API and Feature Removals<3>. 

@end menu

@node API and Feature Removals<3>,,,Retraits<7>
@anchor{whatsnew/3 6 api-and-feature-removals}@anchor{d26}
@subsubsection API and Feature Removals



@itemize *

@item 
Unknown escapes consisting of @code{'\'} and an ASCII letter in
regular expressions will now cause an error.  In replacement templates for
@ref{2a0,,re.sub()} they are still allowed, but deprecated.
The @ref{b5a,,re.LOCALE} flag can now only be used with binary patterns.

@item 
@code{inspect.getmoduleinfo()} was removed (was deprecated since CPython 3.3).
@ref{d27,,inspect.getmodulename()} should be used for obtaining the module
name for a given path.
(Contributed by Yury Selivanov in bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}.)

@item 
@code{traceback.Ignore} class and @code{traceback.usage}, @code{traceback.modname},
@code{traceback.fullmodname}, @code{traceback.find_lines_from_code},
@code{traceback.find_lines}, @code{traceback.find_strings},
@code{traceback.find_executable_lines} methods were removed from the
@ref{fd,,traceback} module. They were undocumented methods deprecated since
Python 3.2 and equivalent functionality is available from private methods.

@item 
The @code{tk_menuBar()} and @code{tk_bindForTraversal()} dummy methods in
@ref{ef,,tkinter} widget classes were removed (corresponding Tk commands
were obsolete since Tk 4.0).

@item 
The @ref{411,,open()} method of the @ref{6af,,zipfile.ZipFile}
class no longer supports the @code{'U'} mode (was deprecated since Python 3.4).
Use @ref{7a5,,io.TextIOWrapper} for reading compressed text files in
@ref{d28,,universal newlines} mode.

@item 
The undocumented @code{IN}, @code{CDROM}, @code{DLFCN}, @code{TYPES}, @code{CDIO}, and
@code{STROPTS} modules have been removed.  They had been available in the
platform specific @code{Lib/plat-*/} directories, but were chronically out of
date, inconsistently available across platforms, and unmaintained.  The
script that created these modules is still available in the source
distribution at Tools/scripts/h2py.py@footnote{https://github.com/python/cpython/blob/v3.6.15/Tools/scripts/h2py.py}.

@item 
The deprecated @code{asynchat.fifo} class has been removed.
@end itemize

@node Porting to Python 3 6,Notable changes in Python 3 6 2,Retraits<7>,What's New In Python 3 6
@anchor{whatsnew/3 6 porting-to-python-3-6}@anchor{d29}
@subsection Porting to Python 3.6


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changes in 'python' Command Behavior:: 
* Changements dans l'API Python: Changements dans l'API Python<8>. 
* Changements dans l'API C: Changements dans l'API C<6>. 
* Changements au code intermédiaire CPython: Changements au code intermédiaire CPython<7>. 

@end menu

@node Changes in 'python' Command Behavior,Changements dans l'API Python<8>,,Porting to Python 3 6
@anchor{whatsnew/3 6 changes-in-python-command-behavior}@anchor{d2a}
@subsubsection Changes in 'python' Command Behavior



@itemize *

@item 
The output of a special Python build with defined @code{COUNT_ALLOCS},
@code{SHOW_ALLOC_COUNT} or @code{SHOW_TRACK_COUNT} macros is now off by
default.  It can be re-enabled using the @code{-X showalloccount} option.
It now outputs to @code{stderr} instead of @code{stdout}.
(Contributed by Serhiy Storchaka in bpo-23034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23034}.)
@end itemize

@node Changements dans l'API Python<8>,Changements dans l'API C<6>,Changes in 'python' Command Behavior,Porting to Python 3 6
@anchor{whatsnew/3 6 changes-in-the-python-api}@anchor{d2b}
@subsubsection Changements dans l'API Python



@itemize *

@item 
@ref{505,,open()} will no longer allow combining the @code{'U'} mode flag
with @code{'+'}.
(Contributed by Jeff Balogh and John O'Connor in bpo-2091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2091}.)

@item 
@ref{ce,,sqlite3} no longer implicitly commits an open transaction before DDL
statements.

@item 
On Linux, @ref{50c,,os.urandom()} now blocks until the system urandom entropy pool
is initialized to increase the security.

@item 
When @ref{855,,importlib.abc.Loader.exec_module()} is defined,
@ref{c9c,,importlib.abc.Loader.create_module()} must also be defined.

@item 
@ref{d2c,,PyErr_SetImportError()} now sets @ref{522,,TypeError} when its `msg'
argument is not set. Previously only @code{NULL} was returned.

@item 
The format of the @ref{2de,,co_lnotab} attribute of code objects
changed to support
a negative line number delta. By default, Python does not emit bytecode with
a negative line number delta. Functions using @ref{796,,frame.f_lineno},
@code{PyFrame_GetLineNumber()} or @code{PyCode_Addr2Line()} are not affected.
Functions directly decoding @code{co_lnotab} should be updated to use a signed
8-bit integer type for the line number delta, but this is only required to
support applications using a negative line number delta. See
@code{Objects/lnotab_notes.txt} for the @code{co_lnotab} format and how to decode
it, and see the 
@geindex Python Enhancement Proposals; PEP 511
PEP 511@footnote{https://peps.python.org/pep-0511/} for the rationale.

@item 
The functions in the @ref{20,,compileall} module now return booleans instead
of @code{1} or @code{0} to represent success or failure, respectively. Thanks to
booleans being a subclass of integers, this should only be an issue if you
were doing identity checks for @code{1} or @code{0}. See bpo-25768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25768}.

@item 
Reading the @code{port} attribute of
@ref{d2d,,urllib.parse.urlsplit()} and @ref{302,,urlparse()} results
now raises @ref{1ff,,ValueError} for out-of-range values, rather than
returning @ref{660,,None}.  See bpo-20059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20059}.

@item 
The @code{imp} module now raises a @ref{1a3,,DeprecationWarning} instead of
@ref{8b5,,PendingDeprecationWarning}.

@item 
The following modules have had missing APIs added to their @code{__all__}
attributes to match the documented APIs:
@ref{14,,calendar}, @code{cgi}, @ref{29,,csv},
@ref{124,,ElementTree}, @ref{55,,enum},
@ref{5a,,fileinput}, @ref{5d,,ftplib}, @ref{86,,logging}, @ref{8a,,mailbox},
@ref{8e,,mimetypes}, @ref{9f,,optparse}, @ref{aa,,plistlib}, @code{smtpd},
@ref{d5,,subprocess}, @ref{dd,,tarfile}, @ref{ec,,threading} and
@ref{112,,wave}.  This means they will export new symbols when @code{import *}
is used.
(Contributed by Joel Taddei and Jacek Kołodziej in bpo-23883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23883}.)

@item 
When performing a relative import, if @code{__package__} does not compare equal
to @code{__spec__.parent} then @ref{4e4,,ImportWarning} is raised.
(Contributed by Brett Cannon in bpo-25791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25791}.)

@item 
When a relative import is performed and no parent package is known, then
@ref{40f,,ImportError} will be raised. Previously, @ref{561,,SystemError} could be
raised. (Contributed by Brett Cannon in bpo-18018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18018}.)

@item 
Servers based on the @ref{cc,,socketserver} module, including those
defined in @ref{71,,http.server}, @ref{12e,,xmlrpc.server} and
@ref{11a,,wsgiref.simple_server}, now only catch exceptions derived
from @ref{9c7,,Exception}. Therefore if a request handler raises
an exception like @ref{d2e,,SystemExit} or @ref{9bf,,KeyboardInterrupt},
@ref{d2f,,handle_error()} is no longer called, and
the exception will stop a single-threaded server. (Contributed by
Martin Panter in bpo-23430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23430}.)

@item 
@code{spwd.getspnam()} now raises a @ref{d30,,PermissionError} instead of
@ref{33a,,KeyError} if the user doesn't have privileges.

@item 
The @ref{d31,,socket.socket.close()} method now raises an exception if
an error (e.g. @code{EBADF}) was reported by the underlying system call.
(Contributed by Martin Panter in bpo-26685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26685}.)

@item 
The `decode_data' argument for the @code{smtpd.SMTPChannel} and
@code{smtpd.SMTPServer} constructors is now @code{False} by default.
This means that the argument passed to
@code{process_message()} is now a bytes object by
default, and @code{process_message()} will be passed keyword arguments.
Code that has already been updated in accordance with the deprecation
warning generated by 3.5 will not be affected.

@item 
All optional arguments of the @ref{d32,,dump()}, @ref{d33,,dumps()},
@ref{ca2,,load()} and @ref{942,,loads()} functions and
@ref{d34,,JSONEncoder} and @ref{d35,,JSONDecoder} class
constructors in the @ref{81,,json} module are now @ref{2a2,,keyword-only}.
(Contributed by Serhiy Storchaka in bpo-18726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18726}.)

@item 
Les sous-classes de @ref{d36,,type} qui ne redéfinissent pas @code{type.__new__} ne devraient plus utiliser la forme à un argument pour récupérer le type d'un objet.

@item 
As part of 
@geindex Python Enhancement Proposals; PEP 487
PEP 487@footnote{https://peps.python.org/pep-0487/}, the handling of keyword arguments passed to
@ref{d36,,type} (other than the metaclass hint, @code{metaclass}) is now
consistently delegated to @ref{61c,,object.__init_subclass__()}. This means that
@code{type.__new__()} and @code{type.__init__()} both now accept arbitrary
keyword arguments, but @ref{61c,,object.__init_subclass__()} (which is called from
@code{type.__new__()}) will reject them by default. Custom metaclasses
accepting additional keyword arguments will need to adjust their calls to
@code{type.__new__()} (whether direct or via @ref{4c5,,super}) accordingly.

@item 
In @code{distutils.command.sdist.sdist}, the @code{default_format}
attribute has been removed and is no longer honored. Instead, the
gzipped tarfile format is the default on all platforms and no
platform-specific selection is made.
In environments where distributions are
built on Windows and zip distributions are required, configure
the project with a @code{setup.cfg} file containing the following:

@example
[sdist]
formats=zip
@end example

This behavior has also been backported to earlier Python versions
by Setuptools 26.0.0.

@item 
In the @ref{10a,,urllib.request} module and the
@ref{c97,,http.client.HTTPConnection.request()} method, if no Content-Length
header field has been specified and the request body is a file object,
it is now sent with HTTP 1.1 chunked encoding. If a file object has to
be sent to a HTTP 1.0 server, the Content-Length value now has to be
specified by the caller.
(Contributed by Demian Brecht and Rolf Krahl with tweaks from
Martin Panter in bpo-12319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12319}.)

@item 
The @ref{9d3,,DictReader} now returns rows of type
@ref{5c5,,OrderedDict}.
(Contributed by Steve Holden in bpo-27842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27842}.)

@item 
The @code{crypt.METHOD_CRYPT} will no longer be added to @code{crypt.methods}
if unsupported by the platform.
(Contributed by Victor Stinner in bpo-25287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25287}.)

@item 
The `verbose' and `rename' arguments for
@ref{1c5,,namedtuple()} are now keyword-only.
(Contributed by Raymond Hettinger in bpo-25628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25628}.)

@item 
On Linux, @ref{d37,,ctypes.util.find_library()} now looks in
@code{LD_LIBRARY_PATH} for shared libraries.
(Contributed by Vinay Sajip in bpo-9998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9998}.)

@item 
The @ref{8f0,,imaplib.IMAP4} class now handles flags containing the
@code{']'} character in messages sent from the server to improve
real-world compatibility.
(Contributed by Lita Cho in bpo-21815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21815}.)

@item 
The @code{mmap.write()} function now returns the number
of bytes written like other write methods.
(Contributed by Jakub Stasiak in bpo-26335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26335}.)

@item 
The @ref{d38,,pkgutil.iter_modules()} and @ref{bed,,pkgutil.walk_packages()}
functions now return @ref{d39,,ModuleInfo} named tuples.
(Contributed by Ramchandra Apte in bpo-17211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17211}.)

@item 
@ref{2a0,,re.sub()} now raises an error for invalid numerical group
references in replacement templates even if the pattern is not
found in the string.  The error message for invalid group references
now includes the group index and the position of the reference.
(Contributed by SilentGhost, Serhiy Storchaka in bpo-25953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25953}.)

@item 
@ref{6af,,zipfile.ZipFile} will now raise @ref{225,,NotImplementedError} for
unrecognized compression values.  Previously a plain @ref{193,,RuntimeError}
was raised.  Additionally, calling @ref{6af,,ZipFile} methods
on a closed ZipFile or calling the @ref{d3a,,write()} method
on a ZipFile created with mode @code{'r'} will raise a @ref{1ff,,ValueError}.
Previously, a @ref{193,,RuntimeError} was raised in those scenarios.

@item 
when custom metaclasses are combined with zero-argument @ref{4c5,,super()} or
direct references from methods to the implicit @code{__class__} closure
variable, the implicit @code{__classcell__} namespace entry must now be passed
up to @code{type.__new__} for initialisation. Failing to do so will result in
a @ref{1a3,,DeprecationWarning} in Python 3.6 and a @ref{193,,RuntimeError} in
Python 3.8.

@item 
With the introduction of @ref{b35,,ModuleNotFoundError}, import system consumers
may start expecting import system replacements to raise that more specific
exception when appropriate, rather than the less-specific @ref{40f,,ImportError}.
To provide future compatibility with such consumers, implementers of
alternative import systems that completely replace @ref{8c1,,__import__()} will
need to update their implementations to raise the new subclass when a module
can't be found at all. Implementers of compliant plugins to the default
import system shouldn't need to make any changes, as the default import
system will raise the new subclass when appropriate.
@end itemize

@node Changements dans l'API C<6>,Changements au code intermédiaire CPython<7>,Changements dans l'API Python<8>,Porting to Python 3 6
@anchor{whatsnew/3 6 changes-in-the-c-api}@anchor{d3b}
@subsubsection Changements dans l'API C



@itemize *

@item 
The @ref{c54,,PyMem_Malloc()} allocator family now uses the @ref{cfd,,pymalloc allocator} rather than the system @code{malloc()}. Applications calling
@ref{c54,,PyMem_Malloc()} without holding the GIL can now crash. Set the
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable to @code{debug} to validate the
usage of memory allocators in your application. See bpo-26249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26249}.

@item 
@ref{d3c,,Py_Exit()} (and the main interpreter) now override the exit status
with 120 if flushing buffered data failed.  See bpo-5319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5319}.
@end itemize

@node Changements au code intermédiaire CPython<7>,,Changements dans l'API C<6>,Porting to Python 3 6
@anchor{whatsnew/3 6 cpython-bytecode-changes}@anchor{d3d}
@subsubsection Changements au code intermédiaire CPython


There have been several major changes to the @ref{185,,bytecode} in Python 3.6.


@itemize *

@item 
The Python interpreter now uses a 16-bit wordcode instead of bytecode.
(Contributed by Demur Rumed with input and reviews from
Serhiy Storchaka and Victor Stinner in bpo-26647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26647} and bpo-28050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28050}.)

@item 
The new @code{FORMAT_VALUE} and @ref{d3e,,BUILD_STRING} opcodes as part
of the  @ref{c1d,,formatted string literal} implementation.
(Contributed by Eric Smith in bpo-25483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25483} and
Serhiy Storchaka in bpo-27078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27078}.)

@item 
The new @ref{d3f,,BUILD_CONST_KEY_MAP} opcode to optimize the creation
of dictionaries with constant keys.
(Contributed by Serhiy Storchaka in bpo-27140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27140}.)

@item 
The function call opcodes have been heavily reworked for better performance
and simpler implementation.
The @ref{d40,,MAKE_FUNCTION}, @code{CALL_FUNCTION},
@code{CALL_FUNCTION_KW} and @code{BUILD_MAP_UNPACK_WITH_CALL} opcodes
have been modified, the new @ref{d41,,CALL_FUNCTION_EX} and
@code{BUILD_TUPLE_UNPACK_WITH_CALL} have been added, and
@code{CALL_FUNCTION_VAR}, @code{CALL_FUNCTION_VAR_KW} and @code{MAKE_CLOSURE} opcodes
have been removed.
(Contributed by Demur Rumed in bpo-27095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27095}, and Serhiy Storchaka in
bpo-27213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27213}, bpo-28257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28257}.)

@item 
The new @ref{d42,,SETUP_ANNOTATIONS} and @code{STORE_ANNOTATION} opcodes
have been added to support the new @ref{d43,,variable annotation} syntax.
(Contributed by Ivan Levkivskyi in bpo-27985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27985}.)
@end itemize

@node Notable changes in Python 3 6 2,Notable changes in Python 3 6 4,Porting to Python 3 6,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-2}@anchor{d44}
@subsection Notable changes in Python 3.6.2


@menu
* New make regen-all build target:: 
* Removal of make touch build target:: 

@end menu

@node New make regen-all build target,Removal of make touch build target,,Notable changes in Python 3 6 2
@anchor{whatsnew/3 6 new-make-regen-all-build-target}@anchor{d45}
@subsubsection New @code{make regen-all} build target


To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.

Instead, a new @code{make regen-all} command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see
Makefile.pre.in@footnote{https://github.com/python/cpython/tree/3.13/Makefile.pre.in} for details.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Ajouté dans la version 3.6.2.


@node Removal of make touch build target,,New make regen-all build target,Notable changes in Python 3 6 2
@anchor{whatsnew/3 6 removal-of-make-touch-build-target}@anchor{d46}
@subsubsection Removal of @code{make touch} build target


The @code{make touch} build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.

It has been replaced by the new @code{make regen-all} target.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Modifié dans la version 3.6.2.


@node Notable changes in Python 3 6 4,Notable changes in Python 3 6 5,Notable changes in Python 3 6 2,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-4}@anchor{d47}
@subsection Notable changes in Python 3.6.4


The @code{PyExc_RecursionErrorInst} singleton that was part of the public API
has been removed as its members being never cleared may cause a segfault
during finalization of the interpreter.
(Contributed by Xavier de Gaye in bpo-22898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22898} and bpo-30697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30697}.)

@node Notable changes in Python 3 6 5,Notable changes in Python 3 6 7,Notable changes in Python 3 6 4,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-5}@anchor{d48}
@subsection Notable changes in Python 3.6.5


The @ref{bec,,locale.localeconv()} function now sets temporarily the @code{LC_CTYPE}
locale to the @code{LC_NUMERIC} locale in some cases.
(Contributed by Victor Stinner in bpo-31900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31900}.)

@node Notable changes in Python 3 6 7,Notable changes in Python 3 6 10,Notable changes in Python 3 6 5,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-7}@anchor{d49}
@subsection Notable changes in Python 3.6.7


@ref{121,,xml.dom.minidom} and @ref{128,,xml.sax} modules no longer process
external entities by default. See also gh-61441@footnote{https://github.com/python/cpython/issues/61441}.

In 3.6.7 the @ref{fa,,tokenize} module now implicitly emits a @code{NEWLINE} token
when provided with input that does not have a trailing new line.  This behavior
now matches what the C tokenizer does internally.
(Contributed by Ammar Askar in bpo-33899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33899}.)

@node Notable changes in Python 3 6 10,Notable changes in Python 3 6 13,Notable changes in Python 3 6 7,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-10}@anchor{d4a}
@subsection Notable changes in Python 3.6.10


En raison de problèmes de sécurité importants, le paramètre `reuse_address' de @ref{71d,,asyncio.loop.create_datagram_endpoint()} n'est plus supporté. C'est à cause du comportement de l'option socket @code{SO_REUSEADDR} en UDP. Pour plus de détails, voir la documentation de @code{loop.create_datagram_endpoint()}. (Contribué par Kyle Stanley, Antoine Pitrou, et Yury Selivanov dans bpo-37228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37228}.)

@node Notable changes in Python 3 6 13,Notable changes in Python 3 6 14,Notable changes in Python 3 6 10,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-13}@anchor{d4b}
@subsection Notable changes in Python 3.6.13


Earlier Python versions allowed using both @code{;} and @code{&} as
query parameter separators in @ref{277,,urllib.parse.parse_qs()} and
@ref{276,,urllib.parse.parse_qsl()}.  Due to security concerns, and to conform with
newer W3C recommendations, this has been changed to allow only a single
separator key, with @code{&} as the default.  This change also affects
@code{cgi.parse()} and @code{cgi.parse_multipart()} as they use the affected
functions internally. For more details, please see their respective
documentation.
(Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}.)

@node Notable changes in Python 3 6 14,,Notable changes in Python 3 6 13,What's New In Python 3 6
@anchor{whatsnew/3 6 notable-changes-in-python-3-6-14}@anchor{d4c}
@subsection Notable changes in Python 3.6.14


A security fix alters the @ref{8e7,,ftplib.FTP} behavior to not trust the
IPv4 address sent from the remote server when setting up a passive data
channel.  We reuse the ftp server IP address instead.  For unusual code
requiring the old behavior, set a @code{trust_server_pasv_ipv4_address}
attribute on your FTP instance to @code{True}.  (See gh-87451@footnote{https://github.com/python/cpython/issues/87451})

The presence of newline or tab characters in parts of a URL allows for some
forms of attacks. Following the WHATWG specification that updates RFC 3986,
ASCII newline @code{\n}, @code{\r} and tab @code{\t} characters are stripped from the
URL by the parser @ref{109,,urllib.parse()} preventing such attacks. The removal
characters are controlled by a new module level variable
@code{urllib.parse._UNSAFE_URL_BYTES_TO_REMOVE}. (See gh-88048@footnote{https://github.com/python/cpython/issues/88048})

@node Nouveautés de Python 3 5,Nouveautés de Python 3 4,What's New In Python 3 6,Nouveautés de Python
@anchor{whatsnew/3 5 doc}@anchor{d4d}@anchor{whatsnew/3 5 what-s-new-in-python-3-5}@anchor{d4e}
@section Nouveautés de Python 3.5


@*Editors: 
Elvis Pranskevichus <@email{elvis@@magic.io}>, Yury Selivanov <@email{yury@@magic.io}>


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Mercurial log
@c when researching a change.

This article explains the new features in Python 3.5, compared to 3.4.
Python 3.5 was released on September 13, 2015.  See the
changelog@footnote{https://docs.python.org/3.5/whatsnew/changelog.html} for a full
list of changes.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 478
PEP 478@footnote{https://peps.python.org/pep-0478/} - Python 3.5 Release Schedule


@menu
* Résumé – Points forts de la publication: Résumé – Points forts de la publication<4>. 
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<14>. 
* Autres changements au langage: Autres changements au langage<9>. 
* Nouveaux modules: Nouveaux modules<9>. 
* Modules améliorés: Modules améliorés<9>. 
* Other module-level changes:: 
* Optimizations: Optimizations<4>. 
* Build and C API Changes: Build and C API Changes<3>. 
* Obsolescence: Obsolescence<10>. 
* Retraits: Retraits<8>. 
* Portage vers Python 3.5: Portage vers Python 3 5. 
* Notable changes in Python 3.5.4: Notable changes in Python 3 5 4. 

@end menu

@node Résumé – Points forts de la publication<4>,Nouvelles fonctionnalités<14>,,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 summary-release-highlights}@anchor{d4f}
@subsection Résumé – Points forts de la publication


Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
@ref{d50,,PEP 492}, coroutines with async and await syntax.

@item 
@ref{d51,,PEP 465}, a new matrix multiplication operator: @code{a @@ b}.

@item 
@ref{d52,,PEP 448}, additional unpacking generalizations.
@end itemize

Nouveaux modules de la bibliothèque :


@itemize *

@item 
@ref{103,,typing}: @ref{d53,,PEP 484 -- Type Hints}.

@item 
@ref{12f,,zipapp}: @ref{d54,,PEP 441 Improving Python ZIP Application Support}.
@end itemize

Nouvelles fonctionnalités natives :


@itemize *

@item 
@code{bytes % args}, @code{bytearray % args}: @ref{d55,,PEP 461} --
Adding @code{%} formatting to bytes and bytearray.

@item 
New @ref{d56,,bytes.hex()}, @ref{d57,,bytearray.hex()} and @ref{d58,,memoryview.hex()}
methods. (Contributed by Arnon Yaari in bpo-9951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9951}.)

@item 
@ref{452,,memoryview} now supports tuple indexing (including multi-dimensional).
(Contributed by Antoine Pitrou in bpo-23632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23632}.)

@item 
Generators have a new @code{gi_yieldfrom} attribute, which returns the
object being iterated by @code{yield from} expressions. (Contributed
by Benno Leslie and Yury Selivanov in bpo-24450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24450}.)

@item 
A new @ref{d59,,RecursionError} exception is now raised when maximum
recursion depth is reached.  (Contributed by Georg Brandl
in bpo-19235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19235}.)
@end itemize

CPython implementation improvements:


@itemize *

@item 
When the @code{LC_TYPE} locale is the POSIX locale (@code{C} locale),
@ref{527,,sys.stdin} and @ref{ac4,,sys.stdout} now use the
@code{surrogateescape} error handler, instead of the @code{strict} error handler.
(Contributed by Victor Stinner in bpo-19977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19977}.)

@item 
@code{.pyo} files are no longer used and have been replaced by a more flexible
scheme that includes the optimization level explicitly in @code{.pyc} name.
(See @ref{d5a,,PEP 488 overview}.)

@item 
Builtin and extension modules are now initialized in a multi-phase process,
which is similar to how Python modules are loaded.
(See @ref{d5b,,PEP 489 overview}.)
@end itemize

Significant improvements in the standard library:


@itemize *

@item 
@ref{5c5,,collections.OrderedDict} is now
@ref{d5c,,implemented in C}, which makes it
4 to 100 times faster.

@item 
The @ref{cf,,ssl} module gained
@ref{d5d,,support for Memory BIO}, which decouples SSL
protocol handling from network IO.

@item 
The new @ref{a4d,,os.scandir()} function provides a
@ref{d5e,,better and significantly faster way}
of directory traversal.

@item 
@ref{9dd,,functools.lru_cache()} has been mostly
@ref{d5f,,reimplemented in C}, yielding much better
performance.

@item 
The new @ref{b74,,subprocess.run()} function provides a
@ref{d60,,streamlined way to run subprocesses}.

@item 
The @ref{fd,,traceback} module has been significantly
@ref{d61,,enhanced} for improved
performance and developer convenience.
@end itemize

Security improvements:


@itemize *

@item 
SSLv3 is now disabled throughout the standard library.
It can still be enabled by instantiating a @ref{291,,ssl.SSLContext}
manually.  (See bpo-22638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22638} for more details; this change was
backported to CPython 3.4 and 2.7.)

@item 
HTTP cookie parsing is now stricter, in order to protect
against potential injection attacks. (Contributed by Antoine Pitrou
in bpo-22796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22796}.)
@end itemize

Windows improvements:


@itemize *

@item 
A new installer for Windows has replaced the old MSI.
See @ref{a95,,Utilisation de Python sur Windows} for more information.

@item 
Windows builds now use Microsoft Visual C++ 14.0, and extension modules
should use the same.
@end itemize

Please read on for a comprehensive list of user-facing changes, including many
other smaller improvements, CPython optimizations, deprecations, and potential
porting issues.

@node Nouvelles fonctionnalités<14>,Autres changements au langage<9>,Résumé – Points forts de la publication<4>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 new-features}@anchor{d62}
@subsection Nouvelles fonctionnalités


@menu
* PEP 492 - Coroutines with async and await syntax:: 
* PEP 465 - A dedicated infix operator for matrix multiplication:: 
* PEP 448 - Additional Unpacking Generalizations:: 
* PEP 461 - percent formatting support for bytes and bytearray:: 
* PEP 484 - Type Hints:: 
* PEP 471 - os.scandir() function: PEP 471 - os scandir function -- a better and faster directory iterator. a better and faster directory iterator
* PEP 475; Retry system calls failing with EINTR: PEP 475 Retry system calls failing with EINTR. 
* PEP 479; Change StopIteration handling inside generators: PEP 479 Change StopIteration handling inside generators. 
* PEP 485; A function for testing approximate equality: PEP 485 A function for testing approximate equality. 
* PEP 486; Make the Python Launcher aware of virtual environments: PEP 486 Make the Python Launcher aware of virtual environments. 
* PEP 488 ; Élimination des fichiers PYO: PEP 488 Élimination des fichiers PYO. 
* PEP 489; Multi-phase extension module initialization: PEP 489 Multi-phase extension module initialization. 

@end menu

@node PEP 492 - Coroutines with async and await syntax,PEP 465 - A dedicated infix operator for matrix multiplication,,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-492-coroutines-with-async-and-await-syntax}@anchor{d63}@anchor{whatsnew/3 5 whatsnew-pep-492}@anchor{d50}
@subsubsection PEP 492 - Coroutines with async and await syntax


@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} greatly improves support for asynchronous programming in Python
by adding @ref{1ab,,awaitable objects},
@ref{d64,,coroutine functions},
@ref{d65,,asynchronous iteration},
and @ref{5c1,,asynchronous context managers}.

Coroutine functions are declared using the new @ref{5bb,,async def} syntax:

@example
>>> async def coro():
...     return 'spam'
@end example

Inside a coroutine function, the new @ref{1b7,,await} expression can be used
to suspend coroutine execution until the result is available.  Any object
can be `awaited', as long as it implements the @ref{1ab,,awaitable} protocol by
defining the @code{__await__()} method.

PEP 492 also adds @ref{a99,,async for} statement for convenient iteration
over asynchronous iterables.

An example of a rudimentary HTTP client written using the new syntax:

@example
import asyncio

async def http_get(domain):
    reader, writer = await asyncio.open_connection(domain, 80)

    writer.write(b'\r\n'.join([
        b'GET / HTTP/1.1',
        b'Host: %b' % domain.encode('latin-1'),
        b'Connection: close',
        b'@w{'}, b'@w{'}
    ]))

    async for line in reader:
        print('>>>', line)

    writer.close()

loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(http_get('example.com'))
finally:
    loop.close()
@end example

Similarly to asynchronous iteration, there is a new syntax for asynchronous
context managers.  The following script:

@example
import asyncio

async def coro(name, lock):
    print('coro @{@}: waiting for lock'.format(name))
    async with lock:
        print('coro @{@}: holding the lock'.format(name))
        await asyncio.sleep(1)
        print('coro @{@}: releasing the lock'.format(name))

loop = asyncio.get_event_loop()
lock = asyncio.Lock()
coros = asyncio.gather(coro(1, lock), coro(2, lock))
try:
    loop.run_until_complete(coros)
finally:
    loop.close()
@end example

affichera :

@example
coro 2: waiting for lock
coro 2: holding the lock
coro 1: waiting for lock
coro 2: releasing the lock
coro 1: holding the lock
coro 1: releasing the lock
@end example

Note that both @ref{a99,,async for} and @ref{5bf,,async with} can only
be used inside a coroutine function declared with @ref{5bb,,async def}.

Coroutine functions are intended to be run inside a compatible event loop,
such as the @ref{d66,,asyncio loop}.

@cartouche
@quotation Note 

Modifié dans la version 3.5.2: À partir de CPython 3.5.2, @code{__aiter__} peut directement renvoyer des @ref{1a9,,itérateurs asynchrones}. Renvoyer un objet @ref{1ab,,awaitable} entraine un avertissement @ref{8b5,,PendingDeprecationWarning}.

See more details in the @ref{d67,,Itérateurs asynchrones} documentation
section.

@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 492

@item PEP 492@footnote{https://peps.python.org/pep-0492/} -- Coroutines with async and await syntax

PEP written and implemented by Yury Selivanov.
@end table


@node PEP 465 - A dedicated infix operator for matrix multiplication,PEP 448 - Additional Unpacking Generalizations,PEP 492 - Coroutines with async and await syntax,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-465-a-dedicated-infix-operator-for-matrix-multiplication}@anchor{d68}@anchor{whatsnew/3 5 whatsnew-pep-465}@anchor{d51}
@subsubsection PEP 465 - A dedicated infix operator for matrix multiplication


@geindex Python Enhancement Proposals; PEP 465
PEP 465@footnote{https://peps.python.org/pep-0465/} adds the @code{@@} infix operator for matrix multiplication.
Currently, no builtin Python types implement the new operator, however, it
can be implemented by defining @code{__matmul__()}, @code{__rmatmul__()},
and @code{__imatmul__()} for regular, reflected, and in-place matrix
multiplication.  The semantics of these methods is similar to that of
methods defining other infix arithmetic operators.

Matrix multiplication is a notably common operation in many fields of
mathematics, science, engineering, and the addition of @code{@@} allows writing
cleaner code:

@example
S = (H @@ beta - r).T @@ inv(H @@ V @@ H.T) @@ (H @@ beta - r)
@end example

instead of:

@example
S = dot((dot(H, beta) - r).T,
        dot(inv(dot(dot(H, V), H.T)), dot(H, beta) - r))
@end example

NumPy 1.10 has support for the new operator:

@example
>>> import numpy

>>> x = numpy.ones(3)
>>> x
array([ 1., 1., 1.])

>>> m = numpy.eye(3)
>>> m
array([[ 1., 0., 0.],
       [ 0., 1., 0.],
       [ 0., 0., 1.]])

>>> x @@ m
array([ 1., 1., 1.])
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 465

@item PEP 465@footnote{https://peps.python.org/pep-0465/} -- A dedicated infix operator for matrix multiplication

PEP written by Nathaniel J. Smith; implemented by Benjamin Peterson.
@end table


@node PEP 448 - Additional Unpacking Generalizations,PEP 461 - percent formatting support for bytes and bytearray,PEP 465 - A dedicated infix operator for matrix multiplication,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-448-additional-unpacking-generalizations}@anchor{d69}@anchor{whatsnew/3 5 whatsnew-pep-448}@anchor{d52}
@subsubsection PEP 448 - Additional Unpacking Generalizations


@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/} extends the allowed uses of the @code{*} iterable unpacking
operator and @code{**} dictionary unpacking operator.  It is now possible
to use an arbitrary number of unpackings in @ref{d6a,,function calls}:

@example
>>> print(*[1], *[2], 3, *[4, 5])
1 2 3 4 5

>>> def fn(a, b, c, d):
...     print(a, b, c, d)
...

>>> fn(**@{'a': 1, 'c': 3@}, **@{'b': 2, 'd': 4@})
1 2 3 4
@end example

Similarly, tuple, list, set, and dictionary displays allow multiple
unpackings (see @ref{d6b,,Listes d'expressions} and @ref{d6c,,Agencements de dictionnaires}):

@example
>>> *range(4), 4
(0, 1, 2, 3, 4)

>>> [*range(4), 4]
[0, 1, 2, 3, 4]

>>> @{*range(4), 4, *(5, 6, 7)@}
@{0, 1, 2, 3, 4, 5, 6, 7@}

>>> @{'x': 1, **@{'y': 2@}@}
@{'x': 1, 'y': 2@}
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 448

@item PEP 448@footnote{https://peps.python.org/pep-0448/} -- Additional Unpacking Generalizations

PEP written by Joshua Landau; implemented by Neil Girdhar,
Thomas Wouters, and Joshua Landau.
@end table


@node PEP 461 - percent formatting support for bytes and bytearray,PEP 484 - Type Hints,PEP 448 - Additional Unpacking Generalizations,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-461-percent-formatting-support-for-bytes-and-bytearray}@anchor{d6d}@anchor{whatsnew/3 5 whatsnew-pep-461}@anchor{d55}
@subsubsection PEP 461 - percent formatting support for bytes and bytearray


@geindex Python Enhancement Proposals; PEP 461
PEP 461@footnote{https://peps.python.org/pep-0461/} adds support for the @code{%}
@ref{d6e,,interpolation operator} to @ref{1bd,,bytes}
and @ref{528,,bytearray}.

While interpolation is usually thought of as a string operation, there are
cases where interpolation on @code{bytes} or @code{bytearrays} makes sense, and the
work needed to make up for this missing functionality detracts from the
overall readability of the code.  This issue is particularly important when
dealing with wire format protocols, which are often a mixture of binary
and ASCII compatible text.

Exemples :

@example
>>> b'Hello %b!' % b'World'
b'Hello World!'

>>> b'x=%i y=%f' % (1, 2.5)
b'x=1 y=2.500000'
@end example

Unicode is not allowed for @code{%b}, but it is accepted by @code{%a} (equivalent of
@code{repr(obj).encode('ascii', 'backslashreplace')}):

@example
>>> b'Hello %b!' % 'World'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: %b requires bytes, or an object that implements __bytes__, not 'str'

>>> b'price: %a' % '10€'
b"price: '10\\u20ac'"
@end example

Note that @code{%s} and @code{%r} conversion types, although supported, should
only be used in codebases that need compatibility with Python 2.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 461

@item PEP 461@footnote{https://peps.python.org/pep-0461/} -- Adding % formatting to bytes and bytearray

PEP written by Ethan Furman; implemented by Neil Schemenauer and
Ethan Furman.
@end table


@node PEP 484 - Type Hints,PEP 471 - os scandir function -- a better and faster directory iterator,PEP 461 - percent formatting support for bytes and bytearray,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-484-type-hints}@anchor{d6f}@anchor{whatsnew/3 5 whatsnew-pep-484}@anchor{d53}
@subsubsection PEP 484 - Type Hints


Function annotation syntax has been a Python feature since version 3.0
(
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/}), however the semantics of annotations has been left undefined.

Experience has shown that the majority of function annotation
uses were to provide type hints to function parameters and return values.  It
became evident that it would be beneficial for Python users, if the
standard library included the base definitions and tools for type annotations.

@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} introduces a @ref{af1,,provisional module} to
provide these standard definitions and tools, along with some conventions
for situations where annotations are not available.

For example, here is a simple function whose argument and return type
are declared in the annotations:

@example
def greeting(name: str) -> str:
    return 'Hello ' + name
@end example

While these annotations are available at runtime through the usual
@code{__annotations__} attribute, `no automatic type checking happens
at runtime'.  Instead, it is assumed that a separate off-line type checker
(e.g. mypy@footnote{https://mypy-lang.org}) will be used for on-demand
source code analysis.

The type system supports unions, generic types, and a special type
named @ref{697,,Any} which is consistent with (i.e. assignable to
and from) all types.


@subsubheading Voir aussi



@itemize *

@item 
Documentation du module @ref{103,,typing}

@item 

@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} -- Type Hints

PEP written by Guido van Rossum, Jukka Lehtosalo, and Łukasz Langa;
implemented by Guido van Rossum.
@end table

@item 

@table @asis

@geindex Python Enhancement Proposals; PEP 483

@item PEP 483@footnote{https://peps.python.org/pep-0483/} -- The Theory of Type Hints

PEP écrite par Guido van Rossum
@end table
@end itemize


@node PEP 471 - os scandir function -- a better and faster directory iterator,PEP 475 Retry system calls failing with EINTR,PEP 484 - Type Hints,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-471-os-scandir-function-a-better-and-faster-directory-iterator}@anchor{d70}@anchor{whatsnew/3 5 whatsnew-pep-471}@anchor{d5e}
@subsubsection PEP 471 - os.scandir() function -- a better and faster directory iterator


@geindex Python Enhancement Proposals; PEP 471
PEP 471@footnote{https://peps.python.org/pep-0471/} adds a new directory iteration function, @ref{a4d,,os.scandir()},
to the standard library.  Additionally, @ref{493,,os.walk()} is now
implemented using @code{scandir}, which makes it 3 to 5 times faster
on POSIX systems and 7 to 20 times faster on Windows systems.  This is
largely achieved by greatly reducing the number of calls to @ref{48a,,os.stat()}
required to walk a directory tree.

Additionally, @code{scandir} returns an iterator, as opposed to returning
a list of file names, which improves memory efficiency when iterating
over very large directories.

The following example shows a simple use of @ref{a4d,,os.scandir()} to display all
the files (excluding directories) in the given `path' that don't start with
@code{'.'}. The @ref{d71,,entry.is_file()} call will generally
not make an additional system call:

@example
for entry in os.scandir(path):
    if not entry.name.startswith('.') and entry.is_file():
        print(entry.name)
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 471

@item PEP 471@footnote{https://peps.python.org/pep-0471/} -- os.scandir() function -- a better and faster directory iterator

PEP written and implemented by Ben Hoyt with the help of Victor Stinner.
@end table


@node PEP 475 Retry system calls failing with EINTR,PEP 479 Change StopIteration handling inside generators,PEP 471 - os scandir function -- a better and faster directory iterator,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-475-retry-system-calls-failing-with-eintr}@anchor{d72}@anchor{whatsnew/3 5 whatsnew-pep-475}@anchor{d73}
@subsubsection PEP 475: Retry system calls failing with EINTR


An @ref{d74,,errno.EINTR} error code is returned whenever a system call, that
is waiting for I/O, is interrupted by a signal.  Previously, Python would
raise @ref{d75,,InterruptedError} in such cases.  This meant that, when writing a
Python application, the developer had two choices:


@enumerate 

@item 
Ignore the @code{InterruptedError}.

@item 
Handle the @code{InterruptedError} and attempt to restart the interrupted
system call at every call site.
@end enumerate

The first option makes an application fail intermittently.
The second option adds a large amount of boilerplate that makes the
code nearly unreadable.  Compare:

@example
print("Hello World")
@end example

et :

@example
while True:
    try:
        print("Hello World")
        break
    except InterruptedError:
        continue
@end example

@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} implements automatic retry of system calls on
@code{EINTR}.  This removes the burden of dealing with @code{EINTR}
or @ref{d75,,InterruptedError} in user code in most situations and makes
Python programs, including the standard library, more robust.  Note that
the system call is only retried if the signal handler does not raise an
exception.

Below is a list of functions which are now retried when interrupted
by a signal:


@itemize *

@item 
@ref{505,,open()} et @ref{506,,io.open()};

@item 
functions of the @ref{57,,faulthandler} module;

@item 
@ref{a0,,os} functions: @ref{d76,,fchdir()}, @ref{219,,fchmod()},
@ref{d77,,fchown()}, @ref{d78,,fdatasync()}, @ref{d79,,fstat()},
@ref{d7a,,fstatvfs()}, @ref{d7b,,fsync()}, @ref{d7c,,ftruncate()},
@ref{d7d,,mkfifo()}, @ref{d7e,,mknod()}, @ref{d7f,,open()},
@ref{d80,,posix_fadvise()}, @ref{d81,,posix_fallocate()}, @ref{b4d,,pread()},
@ref{b50,,pwrite()}, @ref{d82,,read()}, @ref{b4c,,readv()}, @ref{afd,,sendfile()},
@ref{d83,,wait3()}, @ref{d84,,wait4()}, @ref{d85,,wait()},
@ref{d86,,waitid()}, @ref{d87,,waitpid()}, @ref{d88,,write()},
@ref{b4f,,writev()};

@item 
special cases: @ref{b62,,os.close()} and @ref{b51,,os.dup2()} now ignore
@ref{d74,,EINTR} errors; the syscall is not retried (see the PEP
for the rationale);

@item 
@ref{c0,,select} functions: @ref{d89,,devpoll.poll()},
@ref{d8a,,epoll.poll()},
@ref{d8b,,kqueue.control()},
@ref{d8c,,poll.poll()}, @ref{d8d,,select()};

@item 
methods of the @ref{d8e,,socket} class: @ref{d8f,,accept()},
@ref{d90,,connect()} (except for non-blocking sockets),
@ref{d91,,recv()}, @ref{d92,,recvfrom()},
@ref{d93,,recvmsg()}, @ref{d94,,send()},
@ref{d95,,sendall()}, @ref{460,,sendmsg()},
@ref{d96,,sendto()};

@item 
@ref{d97,,signal.sigtimedwait()} and @ref{d98,,signal.sigwaitinfo()};

@item 
@ref{688,,time.sleep()}.
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 475

@item PEP 475@footnote{https://peps.python.org/pep-0475/} -- Retry system calls failing with EINTR

PEP and implementation written by Charles-François Natali and
Victor Stinner, with the help of Antoine Pitrou (the French connection).
@end table


@node PEP 479 Change StopIteration handling inside generators,PEP 485 A function for testing approximate equality,PEP 475 Retry system calls failing with EINTR,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-479-change-stopiteration-handling-inside-generators}@anchor{d99}@anchor{whatsnew/3 5 whatsnew-pep-479}@anchor{d0d}
@subsubsection PEP 479: Change StopIteration handling inside generators


The interaction of generators and @ref{be8,,StopIteration} in Python 3.4 and
earlier was sometimes surprising, and could conceal obscure bugs.  Previously,
@code{StopIteration} raised accidentally inside a generator function was
interpreted as the end of the iteration by the loop construct driving the
generator.

@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} changes the behavior of generators: when a @code{StopIteration}
exception is raised inside a generator, it is replaced with a
@ref{193,,RuntimeError} before it exits the generator frame.  The main goal of
this change is to ease debugging in the situation where an unguarded
@ref{7c2,,next()} call raises @code{StopIteration} and causes the iteration controlled
by the generator to terminate silently. This is particularly pernicious in
combination with the @code{yield from} construct.

This is a backwards incompatible change, so to enable the new behavior,
a @ref{d9a,,__future__} import is necessary:

@example
>>> from __future__ import generator_stop

>>> def gen():
...     next(iter([]))
...     yield
...
>>> next(gen())
Traceback (most recent call last):
  File "<stdin>", line 2, in gen
StopIteration

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: generator raised StopIteration
@end example

Without a @code{__future__} import, a @ref{8b5,,PendingDeprecationWarning} will be
raised whenever a @ref{be8,,StopIteration} exception is raised inside a generator.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 479

@item PEP 479@footnote{https://peps.python.org/pep-0479/} -- Change StopIteration handling inside generators

PEP written by Chris Angelico and Guido van Rossum. Implemented by
Chris Angelico, Yury Selivanov and Nick Coghlan.
@end table


@node PEP 485 A function for testing approximate equality,PEP 486 Make the Python Launcher aware of virtual environments,PEP 479 Change StopIteration handling inside generators,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-485-a-function-for-testing-approximate-equality}@anchor{d9b}@anchor{whatsnew/3 5 whatsnew-pep-485}@anchor{d9c}
@subsubsection PEP 485: A function for testing approximate equality


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} adds the @ref{d9d,,math.isclose()} and @ref{d9e,,cmath.isclose()}
functions which tell whether two values are approximately equal or
"close" to each other.  Whether or not two values are considered
close is determined according to given absolute and relative tolerances.
Relative tolerance is the maximum allowed difference between @code{isclose}
arguments, relative to the larger absolute value:

@example
>>> import math
>>> a = 5.0
>>> b = 4.99998
>>> math.isclose(a, b, rel_tol=1e-5)
True
>>> math.isclose(a, b, rel_tol=1e-6)
False
@end example

It is also possible to compare two values using absolute tolerance, which
must be a non-negative value:

@example
>>> import math
>>> a = 5.0
>>> b = 4.99998
>>> math.isclose(a, b, abs_tol=0.00003)
True
>>> math.isclose(a, b, abs_tol=0.00001)
False
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 485

@item PEP 485@footnote{https://peps.python.org/pep-0485/} -- Une fonction pour tester des égalités approximées

PEP written by Christopher Barker; implemented by Chris Barker and
Tal Einat.
@end table


@node PEP 486 Make the Python Launcher aware of virtual environments,PEP 488 Élimination des fichiers PYO,PEP 485 A function for testing approximate equality,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-486-make-the-python-launcher-aware-of-virtual-environments}@anchor{d9f}@anchor{whatsnew/3 5 whatsnew-pep-486}@anchor{da0}
@subsubsection PEP 486: Make the Python Launcher aware of virtual environments


@geindex Python Enhancement Proposals; PEP 486
PEP 486@footnote{https://peps.python.org/pep-0486/} makes the Windows launcher (see 
@geindex Python Enhancement Proposals; PEP 397
PEP 397@footnote{https://peps.python.org/pep-0397/}) aware of an active
virtual environment. When the default interpreter would be used and the
@code{VIRTUAL_ENV} environment variable is set, the interpreter in the virtual
environment will be used.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 486

@item PEP 486@footnote{https://peps.python.org/pep-0486/} -- Make the Python Launcher aware of virtual environments

PEP written and implemented by Paul Moore.
@end table


@node PEP 488 Élimination des fichiers PYO,PEP 489 Multi-phase extension module initialization,PEP 486 Make the Python Launcher aware of virtual environments,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-488-elimination-of-pyo-files}@anchor{da1}@anchor{whatsnew/3 5 whatsnew-pep-488}@anchor{d5a}
@subsubsection PEP 488 : Élimination des fichiers PYO


@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} does away with the concept of @code{.pyo} files. This means that
@code{.pyc} files represent both unoptimized and optimized bytecode. To prevent the
need to constantly regenerate bytecode files, @code{.pyc} files now have an
optional @code{opt-} tag in their name when the bytecode is optimized. This has the
side-effect of no more bytecode file name clashes when running under either
@ref{da2,,-O} or @ref{da3,,-OO}. Consequently, bytecode files generated from
@ref{da2,,-O}, and @ref{da3,,-OO} may now exist simultaneously.
@ref{2f2,,importlib.util.cache_from_source()} has an updated API to help with
this change.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 488

@item PEP 488@footnote{https://peps.python.org/pep-0488/} : Élimination des fichiers PYO

PEP written and implemented by Brett Cannon.
@end table


@node PEP 489 Multi-phase extension module initialization,,PEP 488 Élimination des fichiers PYO,Nouvelles fonctionnalités<14>
@anchor{whatsnew/3 5 pep-489-multi-phase-extension-module-initialization}@anchor{da4}@anchor{whatsnew/3 5 whatsnew-pep-489}@anchor{d5b}
@subsubsection PEP 489: Multi-phase extension module initialization


@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} updates extension module initialization to take advantage of the
two step module loading mechanism introduced by 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} in Python 3.4.

This change brings the import semantics of extension modules that opt-in to
using the new mechanism much closer to those of Python source and bytecode
modules, including the ability to use any valid identifier as a module name,
rather than being restricted to ASCII.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 489

@item PEP 489@footnote{https://peps.python.org/pep-0489/} -- Multi-phase extension module initialization

PEP written by Petr Viktorin, Stefan Behnel, and Nick Coghlan;
implemented by Petr Viktorin.
@end table


@node Autres changements au langage<9>,Nouveaux modules<9>,Nouvelles fonctionnalités<14>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 other-language-changes}@anchor{da5}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
Added the @code{"namereplace"} error handlers.  The @code{"backslashreplace"}
error handlers now work with decoding and translating.
(Contributed by Serhiy Storchaka in bpo-19676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19676} and bpo-22286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22286}.)

@item 
The @ref{5cd,,-b} option now affects comparisons of @ref{1bd,,bytes} with
@ref{254,,int}.  (Contributed by Serhiy Storchaka in bpo-23681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23681}.)

@item 
New Kazakh @code{kz1048} and Tajik @code{koi8_t} @ref{da6,,codecs}.
(Contributed by Serhiy Storchaka in bpo-22682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22682} and bpo-22681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22681}.)

@item 
Property docstrings are now writable. This is especially useful for
@ref{1c5,,collections.namedtuple()} docstrings.
(Contributed by Berker Peksag in bpo-24064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24064}.)

@item 
Circular imports involving relative imports are now supported.
(Contributed by Brett Cannon and Antoine Pitrou in bpo-17636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17636}.)
@end itemize

@node Nouveaux modules<9>,Modules améliorés<9>,Autres changements au langage<9>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 new-modules}@anchor{da7}
@subsection Nouveaux modules


@menu
* typing: typing<10>. 
* zipapp: zipapp<2>. 

@end menu

@node typing<10>,zipapp<2>,,Nouveaux modules<9>
@anchor{whatsnew/3 5 typing}@anchor{da8}
@subsubsection `typing'


The new @ref{103,,typing} @ref{af1,,provisional} module
provides standard definitions and tools for function type annotations.
See @ref{d53,,Type Hints} for more information.

@node zipapp<2>,,typing<10>,Nouveaux modules<9>
@anchor{whatsnew/3 5 whatsnew-zipapp}@anchor{d54}@anchor{whatsnew/3 5 zipapp}@anchor{da9}
@subsubsection zipapp


The new @ref{12f,,zipapp} module (specified in 
@geindex Python Enhancement Proposals; PEP 441
PEP 441@footnote{https://peps.python.org/pep-0441/}) provides an API and
command line tool for creating executable Python Zip Applications, which
were introduced in Python 2.6 in bpo-1739468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1739468}, but which were not well
publicized, either at the time or since.

With the new module, bundling your application is as simple as putting all
the files, including a @code{__main__.py} file, into a directory @code{myapp}
and running:

@example
$ python -m zipapp myapp
$ python myapp.pyz
@end example

The module implementation has been contributed by Paul Moore in
bpo-23491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23491}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 441
PEP 441@footnote{https://peps.python.org/pep-0441/} -- Improving Python ZIP Application Support


@node Modules améliorés<9>,Other module-level changes,Nouveaux modules<9>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 improved-modules}@anchor{daa}
@subsection Modules améliorés


@menu
* argparse: argparse<4>. 
* asyncio: asyncio<10>. 
* bz2:: 
* cgi:: 
* cmath: cmath<2>. 
* code:: 
* collections: collections<5>. 
* collections.abc: collections abc<3>. 
* compileall: compileall<4>. 
* concurrent.futures: concurrent futures<5>. 
* configparser: configparser<4>. 
* contextlib: contextlib<5>. 
* csv: csv<3>. 
* curses: curses<4>. 
* dbm: dbm<5>. 
* difflib:: 
* distutils: distutils<7>. 
* doctest: doctest<3>. 
* email: email<3>. 
* enum: enum<8>. 
* faulthandler: faulthandler<3>. 
* functools: functools<4>. 
* glob: glob<3>. 
* gzip: gzip<4>. 
* heapq:: 
* http: http<2>. 
* http.client: http client<3>. 
* idlelib and IDLE: idlelib and IDLE<3>. 
* imaplib: imaplib<2>. 
* imghdr:: 
* importlib: importlib<8>. 
* inspect: inspect<7>. 
* io: io<5>. 
* ipaddress: ipaddress<4>. 
* json: json<2>. 
* linecache: linecache<2>. 
* locale: locale<6>. 
* logging: logging<5>. 
* lzma:: 
* math: math<8>. 
* multiprocessing: multiprocessing<6>. 
* operator: operator<2>. 
* os: os<10>. 
* pathlib: pathlib<10>. 
* pickle: pickle<3>. 
* poplib: poplib<2>. 
* re: re<7>. 
* readline: readline<2>. 
* selectors:: 
* shutils: shutils<5>. 
* signal: signal<3>. 
* smtpd: smtpd<2>. 
* smtplib: smtplib<2>. 
* sndhdr:: 
* socket: socket<8>. 
* ssl: ssl<9>. 
* sqlite3: sqlite3<8>. 
* subprocess: subprocess<4>. 
* sys: sys<11>. 
* sysconfig: sysconfig<2>. 
* tarfile: tarfile<6>. 
* threading: threading<6>. 
* time: time<7>. 
* timeit: timeit<2>. 
* tkinter: tkinter<8>. 
* traceback: traceback<5>. 
* types: types<5>. 
* unicodedata: unicodedata<8>. 
* unittest: unittest<8>. 
* unittest.mock: unittest mock<3>. 
* urllib: urllib<2>. 
* wsgiref:: 
* xmlrpc: xmlrpc<2>. 
* xml.sax: xml sax. 
* zipfile: zipfile<4>. 

@end menu

@node argparse<4>,asyncio<10>,,Modules améliorés<9>
@anchor{whatsnew/3 5 argparse}@anchor{dab}
@subsubsection argparse


The @ref{523,,ArgumentParser} class now allows disabling
@ref{dac,,abbreviated usage} of long options by setting
@ref{dad,,Le paramètre allow_abbrev} to @code{False}.  (Contributed by Jonathan Paugh,
Steven Bethard, paul j3 and Daniel Eriksson in bpo-14910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14910}.)

@node asyncio<10>,bz2,argparse<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 asyncio}@anchor{dae}
@subsubsection asyncio


Since the @ref{a,,asyncio} module is @ref{af1,,provisional},
all changes introduced in Python 3.5 have also been backported to Python 3.4.x.

Notable changes in the @ref{a,,asyncio} module since Python 3.4.0:


@itemize *

@item 
New debugging APIs: @ref{daf,,loop.set_debug()}
and @ref{db0,,loop.get_debug()} methods.
(Contributed by Victor Stinner.)

@item 
The proactor event loop now supports SSL.
(Contributed by Antoine Pitrou and Victor Stinner in bpo-22560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22560}.)

@item 
A new @ref{db1,,loop.is_closed()} method to
check if the event loop is closed.
(Contributed by Victor Stinner in bpo-21326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21326}.)

@item 
A new @ref{9ca,,loop.create_task()}
to conveniently create and schedule a new @ref{4c2,,Task}
for a coroutine.  The @code{create_task} method is also used by all
asyncio functions that wrap coroutines into tasks, such as
@ref{469,,asyncio.wait()}, @ref{5e8,,asyncio.gather()}, etc.
(Contributed by Victor Stinner.)

@item 
A new @ref{db2,,transport.get_write_buffer_limits()}
method to inquire for `high-' and `low-' water limits of the flow
control.
(Contributed by Victor Stinner.)

@item 
The @code{async()} function is deprecated in favor of
@ref{c64,,ensure_future()}.
(Contributed by Yury Selivanov.)

@item 
New @ref{db3,,loop.set_task_factory()} and
@ref{db4,,loop.get_task_factory()}
methods to customize the task factory that @ref{9ca,,loop.create_task()} method uses.  (Contributed by Yury
Selivanov.)

@item 
New @ref{db5,,Queue.join()} and
@ref{db6,,Queue.task_done()} queue methods.
(Contributed by Victor Stinner.)

@item 
The @code{JoinableQueue} class was removed, in favor of the
@ref{a64,,asyncio.Queue} class.
(Contributed by Victor Stinner.)
@end itemize

Nouveautés dans la 3.5.1 :


@itemize *

@item 
The @ref{c64,,ensure_future()} function and all functions that
use it, such as @ref{c65,,loop.run_until_complete()},
now accept all kinds of @ref{1ab,,awaitable objects}.
(Contributed by Yury Selivanov.)

@item 
New @ref{86e,,run_coroutine_threadsafe()} function to submit
coroutines to event loops from other threads.
(Contributed by Vincent Michel.)

@item 
New @ref{c66,,Transport.is_closing()}
method to check if the transport is closing or closed.
(Contributed by Yury Selivanov.)

@item 
The @ref{b01,,loop.create_server()}
method can now accept a list of hosts.
(Contributed by Yann Sionneau.)
@end itemize

Updates in 3.5.2:


@itemize *

@item 
New @ref{c67,,loop.create_future()}
method to create Future objects.  This allows alternative event
loop implementations, such as
uvloop@footnote{https://github.com/MagicStack/uvloop}, to provide a faster
@ref{bbb,,asyncio.Future} implementation.
(Contributed by Yury Selivanov.)

@item 
New @ref{c68,,loop.get_exception_handler()}
method to get the current exception handler.
(Contributed by Yury Selivanov.)

@item 
New @ref{1b2,,StreamReader.readuntil()}
method to read data from the stream until a separator bytes
sequence appears.
(Contributed by Mark Korenberg.)

@item 
The @ref{5ee,,loop.create_connection()}
and @ref{b01,,loop.create_server()}
methods are optimized to avoid calling the system @code{getaddrinfo}
function if the address is already resolved.
(Contributed by A. Jesse Jiryu Davis.)

@item 
The @ref{db7,,loop.sock_connect(sock@comma{} address)}
no longer requires the `address' to be resolved prior to the call.
(Contributed by A. Jesse Jiryu Davis.)
@end itemize

@node bz2,cgi,asyncio<10>,Modules améliorés<9>
@anchor{whatsnew/3 5 bz2}@anchor{db8}
@subsubsection bz2


The @ref{db9,,BZ2Decompressor.decompress}
method now accepts an optional `max_length' argument to limit the maximum
size of decompressed data. (Contributed by Nikolaus Rath in bpo-15955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15955}.)

@node cgi,cmath<2>,bz2,Modules améliorés<9>
@anchor{whatsnew/3 5 cgi}@anchor{dba}
@subsubsection cgi


The @code{FieldStorage} class now supports the @ref{5be,,context manager}
protocol.  (Contributed by Berker Peksag in bpo-20289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20289}.)

@node cmath<2>,code,cgi,Modules améliorés<9>
@anchor{whatsnew/3 5 cmath}@anchor{dbb}
@subsubsection cmath


A new function @ref{d9e,,isclose()} provides a way to test for approximate
equality.  (Contributed by Chris Barker and Tal Einat in bpo-24270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24270}.)

@node code,collections<5>,cmath<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 code}@anchor{dbc}
@subsubsection code


The @ref{dbd,,InteractiveInterpreter.showtraceback()}
method now prints the full chained traceback, just like the interactive
interpreter.  (Contributed by Claudiu Popa in bpo-17442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17442}.)

@node collections<5>,collections abc<3>,code,Modules améliorés<9>
@anchor{whatsnew/3 5 collections}@anchor{dbe}
@subsubsection collections

@anchor{whatsnew/3 5 whatsnew-ordereddict}@anchor{d5c}
The @ref{5c5,,OrderedDict} class is now implemented in C, which
makes it 4 to 100 times faster.  (Contributed by Eric Snow in bpo-16991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16991}.)

@code{OrderedDict.items()},
@code{OrderedDict.keys()},
@code{OrderedDict.values()} views now support
@ref{850,,reversed()} iteration.
(Contributed by Serhiy Storchaka in bpo-19505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19505}.)

The @ref{5c6,,deque} class now defines
@ref{dbf,,index()}, @ref{dc0,,insert()}, and
@ref{dc1,,copy()}, and supports the @code{+} and @code{*} operators.
This allows deques to be recognized as a @ref{19f,,MutableSequence}
and improves their substitutability for lists.
(Contributed by Raymond Hettinger in bpo-23704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23704}.)

Docstrings produced by @ref{1c5,,namedtuple()} can now be updated:

@example
Point = namedtuple('Point', ['x', 'y'])
Point.__doc__ += ': Cartesian coordinate'
Point.x.__doc__ = 'abscissa'
Point.y.__doc__ = 'ordinate'
@end example

(Contributed by Berker Peksag in bpo-24064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24064}.)

The @ref{dc2,,UserString} class now implements the
@code{__getnewargs__()}, @code{__rmod__()}, @ref{dc3,,casefold()},
@ref{dc4,,format_map()}, @ref{dc5,,isprintable()}, and @ref{dc6,,maketrans()}
methods to match the corresponding methods of @ref{435,,str}.
(Contributed by Joe Jevnik in bpo-22189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22189}.)

@node collections abc<3>,compileall<4>,collections<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 collections-abc}@anchor{dc7}
@subsubsection collections.abc


The @code{Sequence.index()} method now
accepts `start' and `stop' arguments to match the corresponding methods
of @ref{366,,tuple}, @ref{5fc,,list}, etc.
(Contributed by Devin Jeanpierre in bpo-23086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23086}.)

A new @ref{dc8,,Generator} abstract base class. (Contributed
by Stefan Behnel in bpo-24018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24018}.)

New @ref{dc9,,Awaitable}, @ref{dca,,Coroutine},
@ref{dcb,,AsyncIterator}, and
@ref{dcc,,AsyncIterable} abstract base classes.
(Contributed by Yury Selivanov in bpo-24184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24184}.)

For earlier Python versions, a backport of the new ABCs is available in an
external PyPI package@footnote{https://pypi.org/project/backports_abc/}.

@node compileall<4>,concurrent futures<5>,collections abc<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 compileall}@anchor{dcd}
@subsubsection compileall


A new @ref{20,,compileall} option, @code{-j @var{N}}, allows running `N' workers
simultaneously to perform parallel bytecode compilation.
The @ref{b14,,compile_dir()} function has a corresponding @code{workers}
parameter.  (Contributed by Claudiu Popa in bpo-16104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16104}.)

Another new option, @code{-r}, allows controlling the maximum recursion
level for subdirectories.  (Contributed by Claudiu Popa in bpo-19628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19628}.)

The @code{-q} command line option can now be specified more than once, in
which case all output, including errors, will be suppressed.  The corresponding
@code{quiet} parameter in @ref{b14,,compile_dir()},
@ref{dce,,compile_file()}, and @ref{dcf,,compile_path()} can now
accept an integer value indicating the level of output suppression.
(Contributed by Thomas Kluyver in bpo-21338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21338}.)

@node concurrent futures<5>,configparser<4>,compileall<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 concurrent-futures}@anchor{dd0}
@subsubsection concurrent.futures


The @ref{dd1,,Executor.map()} method now accepts a
`chunksize' argument to allow batching of tasks to improve performance when
@ref{8db,,ProcessPoolExecutor()} is used.
(Contributed by Dan O'Reilly in bpo-11271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11271}.)

The number of workers in the @ref{72c,,ThreadPoolExecutor}
constructor is optional now.  The default value is 5 times the number of CPUs.
(Contributed by Claudiu Popa in bpo-21527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21527}.)

@node configparser<4>,contextlib<5>,concurrent futures<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 configparser}@anchor{dd2}
@subsubsection configparser


@ref{22,,configparser} now provides a way to customize the conversion
of values by specifying a dictionary of converters in the
@ref{1c3,,ConfigParser} constructor, or by defining them
as methods in @code{ConfigParser} subclasses.  Converters defined in
a parser instance are inherited by its section proxies.

Exemple :

@example
>>> import configparser
>>> conv = @{@}
>>> conv['list'] = lambda v: [e.strip() for e in v.split() if e.strip()]
>>> cfg = configparser.ConfigParser(converters=conv)
>>> cfg.read_string("""
... [s]
... list = a b c d e f g
... """)
>>> cfg.get('s', 'list')
'a b c d e f g'
>>> cfg.getlist('s', 'list')
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> section = cfg['s']
>>> section.getlist('list')
['a', 'b', 'c', 'd', 'e', 'f', 'g']
@end example

(Contributed by Łukasz Langa in bpo-18159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18159}.)

@node contextlib<5>,csv<3>,configparser<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 contextlib}@anchor{dd3}
@subsubsection contextlib


The new @ref{dd4,,redirect_stderr()} @ref{5be,,context manager} (similar to
@ref{dd5,,redirect_stdout()}) makes it easier for utility scripts to
handle inflexible APIs that write their output to @ref{926,,sys.stderr} and
don't provide any options to redirect it:

@example
>>> import contextlib, io, logging
>>> f = io.StringIO()
>>> with contextlib.redirect_stderr(f):
...     logging.warning('warning')
...
>>> f.getvalue()
'WARNING:root:warning\n'
@end example

(Contributed by Berker Peksag in bpo-22389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22389}.)

@node csv<3>,curses<4>,contextlib<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 csv}@anchor{dd6}
@subsubsection csv


The @ref{dd7,,writerow()} method now supports arbitrary iterables,
not just sequences.  (Contributed by Serhiy Storchaka in bpo-23171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23171}.)

@node curses<4>,dbm<5>,csv<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 curses}@anchor{dd8}
@subsubsection curses


The new @ref{dd9,,update_lines_cols()} function updates the @code{LINES}
and @code{COLS} module variables.  This is useful for detecting
manual screen resizing.  (Contributed by Arnon Yaari in bpo-4254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4254}.)

@node dbm<5>,difflib,curses<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 dbm}@anchor{dda}
@subsubsection dbm


@ref{a84,,dumb.open} always creates a new database when the flag
has the value @code{"n"}.  (Contributed by Claudiu Popa in bpo-18039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18039}.)

@node difflib,distutils<7>,dbm<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 difflib}@anchor{ddb}
@subsubsection difflib


The charset of HTML documents generated by
@ref{ddc,,HtmlDiff.make_file()}
can now be customized by using a new `charset' keyword-only argument.
The default charset of HTML document changed from @code{"ISO-8859-1"}
to @code{"utf-8"}.
(Contributed by Berker Peksag in bpo-2052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2052}.)

The @ref{ddd,,diff_bytes()} function can now compare lists of byte
strings.  This fixes a regression from Python 2.
(Contributed by Terry J. Reedy and Greg Ward in bpo-17445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17445}.)

@node distutils<7>,doctest<3>,difflib,Modules améliorés<9>
@anchor{whatsnew/3 5 distutils}@anchor{dde}
@subsubsection distutils


Both the @code{build} and @code{build_ext} commands now accept a @code{-j} option to
enable parallel building of extension modules.
(Contributed by Antoine Pitrou in bpo-5309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5309}.)

The @code{distutils} module now supports @code{xz} compression, and can be
enabled by passing @code{xztar} as an argument to @code{bdist --format}.
(Contributed by Serhiy Storchaka in bpo-16314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16314}.)

@node doctest<3>,email<3>,distutils<7>,Modules améliorés<9>
@anchor{whatsnew/3 5 doctest}@anchor{ddf}
@subsubsection doctest


The @ref{de0,,DocTestSuite()} function returns an empty
@ref{de1,,unittest.TestSuite} if `module' contains no docstrings, instead of
raising @ref{1ff,,ValueError}.  (Contributed by Glenn Jones in bpo-15916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15916}.)

@node email<3>,enum<8>,doctest<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 email}@anchor{de2}
@subsubsection email


A new policy option @ref{de3,,Policy.mangle_from_}
controls whether or not lines that start with @code{"From "} in email bodies are
prefixed with a @code{">"} character by generators.  The default is @code{True} for
@ref{c87,,compat32} and @code{False} for all other policies.
(Contributed by Milan Oberkirch in bpo-20098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20098}.)

A new
@ref{de4,,Message.get_content_disposition()}
method provides easy access to a canonical value for the
@code{Content-Disposition} header.
(Contributed by Abhilash Raj in bpo-21083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21083}.)

A new policy option @ref{de5,,EmailPolicy.utf8}
can be set to @code{True} to encode email headers using the UTF-8 charset instead
of using encoded words.  This allows @code{Messages} to be formatted according to
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html} and used with an SMTP server that supports the 
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}
@code{SMTPUTF8} extension.  (Contributed by R. David Murray in
bpo-24211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24211}.)

The @ref{de6,,mime.text.MIMEText} constructor now
accepts a @ref{de7,,charset.Charset} instance.
(Contributed by Claude Paroz and Berker Peksag in bpo-16324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16324}.)

@node enum<8>,faulthandler<3>,email<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 enum}@anchor{de8}
@subsubsection enum


The @ref{61b,,Enum} callable has a new parameter `start' to
specify the initial number of enum values if only `names' are provided:

@example
>>> Animal = enum.Enum('Animal', 'cat dog', start=10)
>>> Animal.cat
<Animal.cat: 10>
>>> Animal.dog
<Animal.dog: 11>
@end example

(Contributed by Ethan Furman in bpo-21706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21706}.)

@node faulthandler<3>,functools<4>,enum<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 faulthandler}@anchor{de9}
@subsubsection @code{faulthandler}


The @ref{c8c,,enable()}, @ref{dea,,register()},
@ref{deb,,dump_traceback()} and
@ref{dec,,dump_traceback_later()} functions now accept file
descriptors in addition to file-like objects.
(Contributed by Wei Wu in bpo-23566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23566}.)

@node functools<4>,glob<3>,faulthandler<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 functools}@anchor{ded}
@subsubsection functools

@anchor{whatsnew/3 5 whatsnew-lrucache}@anchor{d5f}
Most of the @ref{9dd,,lru_cache()} machinery is now implemented in C, making
it significantly faster.  (Contributed by Matt Joiner, Alexey Kachayev, and
Serhiy Storchaka in bpo-14373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14373}.)

@node glob<3>,gzip<4>,functools<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 glob}@anchor{dee}
@subsubsection glob


The @ref{7f1,,iglob()} and @ref{29c,,glob()} functions now support recursive
search in subdirectories, using the @code{"**"} pattern.
(Contributed by Serhiy Storchaka in bpo-13968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13968}.)

@node gzip<4>,heapq,glob<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 gzip}@anchor{def}
@subsubsection gzip


The `mode' argument of the @ref{410,,GzipFile} constructor now
accepts @code{"x"} to request exclusive creation.
(Contributed by Tim Heaney in bpo-19222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19222}.)

@node heapq,http<2>,gzip<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 heapq}@anchor{df0}
@subsubsection heapq


Element comparison in @ref{df1,,merge()} can now be customized by
passing a @ref{df2,,key function} in a new optional `key' keyword argument,
and a new optional `reverse' keyword argument can be used to reverse element
comparison:

@example
>>> import heapq
>>> a = ['9', '777', '55555']
>>> b = ['88', '6666']
>>> list(heapq.merge(a, b, key=len))
['9', '88', '777', '6666', '55555']
>>> list(heapq.merge(reversed(a), reversed(b), key=len, reverse=True))
['55555', '6666', '777', '88', '9']
@end example

(Contributed by Raymond Hettinger in bpo-13742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13742}.)

@node http<2>,http client<3>,heapq,Modules améliorés<9>
@anchor{whatsnew/3 5 http}@anchor{df3}
@subsubsection `http'


A new @ref{8ed,,HTTPStatus} enum that defines a set of
HTTP status codes, reason phrases and long descriptions written in English.
(Contributed by Demian Brecht in bpo-21793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21793}.)

@node http client<3>,idlelib and IDLE<3>,http<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 http-client}@anchor{df4}
@subsubsection http.client


@ref{df5,,HTTPConnection.getresponse()}
now raises a @ref{df6,,RemoteDisconnected} exception when a
remote server connection is closed unexpectedly.  Additionally, if a
@ref{df7,,ConnectionError} (of which @code{RemoteDisconnected}
is a subclass) is raised, the client socket is now closed automatically,
and will reconnect on the next request:

@example
import http.client
conn = http.client.HTTPConnection('www.python.org')
for retries in range(3):
    try:
        conn.request('GET', '/')
        resp = conn.getresponse()
    except http.client.RemoteDisconnected:
        pass
@end example

(Contributed by Martin Panter in bpo-3566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3566}.)

@node idlelib and IDLE<3>,imaplib<2>,http client<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 idlelib-and-idle}@anchor{df8}
@subsubsection idlelib and IDLE


Since idlelib implements the IDLE shell and editor and is not intended for
import by other programs, it gets improvements with every release.  See
@code{Lib/idlelib/NEWS.txt} for a cumulative list of changes since 3.4.0,
as well as changes made in future 3.5.x releases. This file is also available
from the IDLE Help ‣ About IDLE dialog.

@node imaplib<2>,imghdr,idlelib and IDLE<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 imaplib}@anchor{df9}
@subsubsection `imaplib'


The @ref{8f0,,IMAP4} class now supports the @ref{5be,,context manager} protocol.
When used in a @ref{5bc,,with} statement, the IMAP4 @code{LOGOUT}
command will be called automatically at the end of the block.
(Contributed by Tarek Ziadé and Serhiy Storchaka in bpo-4972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4972}.)

The @ref{73,,imaplib} module now supports 
@geindex RFC; RFC 5161
RFC 5161@footnote{https://datatracker.ietf.org/doc/html/rfc5161.html} (ENABLE Extension)
and 
@geindex RFC; RFC 6855
RFC 6855@footnote{https://datatracker.ietf.org/doc/html/rfc6855.html} (UTF-8 Support) via the @ref{dfa,,IMAP4.enable()}
method.  A new @ref{dfb,,IMAP4.utf8_enabled}
attribute tracks whether or not 
@geindex RFC; RFC 6855
RFC 6855@footnote{https://datatracker.ietf.org/doc/html/rfc6855.html} support is enabled.
(Contributed by Milan Oberkirch, R. David Murray, and Maciej Szulik in
bpo-21800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21800}.)

The @ref{73,,imaplib} module now automatically encodes non-ASCII string usernames
and passwords using UTF-8, as recommended by the RFCs.  (Contributed by Milan
Oberkirch in bpo-21800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21800}.)

@node imghdr,importlib<8>,imaplib<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 imghdr}@anchor{dfc}
@subsubsection imghdr


The @code{what()} function now recognizes the
OpenEXR@footnote{https://www.openexr.com} format
(contributed by Martin Vignali and Claudiu Popa in bpo-20295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20295}),
and the WebP@footnote{https://en.wikipedia.org/wiki/WebP} format
(contributed by Fabrice Aneche and Claudiu Popa in bpo-20197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20197}.)

@node importlib<8>,inspect<7>,imghdr,Modules améliorés<9>
@anchor{whatsnew/3 5 importlib}@anchor{dfd}
@subsubsection importlib


The @ref{c9b,,util.LazyLoader} class allows for
lazy loading of modules in applications where startup time is important.
(Contributed by Brett Cannon in bpo-17621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17621}.)

The @ref{dfe,,abc.InspectLoader.source_to_code()}
method is now a static method.  This makes it easier to initialize a module
object with code compiled from a string by running
@code{exec(code, module.__dict__)}.
(Contributed by Brett Cannon in bpo-21156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21156}.)

The new @ref{dff,,util.module_from_spec()}
function is now the preferred way to create a new module.  As opposed to
creating a @ref{e00,,types.ModuleType} instance directly, this new function
will set the various import-controlled attributes based on the passed-in
spec object.  (Contributed by Brett Cannon in bpo-20383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20383}.)

@node inspect<7>,io<5>,importlib<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 inspect}@anchor{e01}
@subsubsection `inspect'


Both the @ref{1ca,,Signature} and @ref{1cb,,Parameter} classes are
now picklable and hashable.  (Contributed by Yury Selivanov in bpo-20726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20726}
and bpo-20334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20334}.)

A new
@ref{e02,,BoundArguments.apply_defaults()}
method provides a way to set default values for missing arguments:

@example
>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
OrderedDict([('a', 'spam'), ('b', 'ham'), ('args', ())])
@end example

(Contributed by Yury Selivanov in bpo-24190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24190}.)

A new class method
@ref{724,,Signature.from_callable()} makes
subclassing of @ref{1ca,,Signature} easier.  (Contributed
by Yury Selivanov and Eric Snow in bpo-17373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17373}.)

The @ref{722,,signature()} function now accepts a `follow_wrapped'
optional keyword argument, which, when set to @code{False}, disables automatic
following of @code{__wrapped__} links.
(Contributed by Yury Selivanov in bpo-20691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20691}.)

A set of new functions to inspect
@ref{d64,,coroutine functions} and
@ref{47b,,coroutine objects} has been added:
@ref{e03,,iscoroutine()}, @ref{2e2,,iscoroutinefunction()},
@ref{e04,,isawaitable()}, @ref{e05,,getcoroutinelocals()},
and @ref{e06,,getcoroutinestate()}.
(Contributed by Yury Selivanov in bpo-24017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24017} and bpo-24400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24400}.)

The @ref{63d,,stack()}, @ref{63e,,trace()},
@ref{63b,,getouterframes()}, and @ref{63c,,getinnerframes()}
functions now return a list of named tuples.
(Contributed by Daniel Shahaf in bpo-16808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16808}.)

@node io<5>,ipaddress<4>,inspect<7>,Modules améliorés<9>
@anchor{whatsnew/3 5 io}@anchor{e07}
@subsubsection io


A new @ref{e08,,BufferedIOBase.readinto1()}
method, that uses at most one call to the underlying raw stream's
@ref{e09,,RawIOBase.read()} or
@ref{e0a,,RawIOBase.readinto()} methods.
(Contributed by Nikolaus Rath in bpo-20578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20578}.)

@node ipaddress<4>,json<2>,io<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 ipaddress}@anchor{e0b}
@subsubsection `ipaddress'


Both the @ref{1fb,,IPv4Network} and @ref{1fc,,IPv6Network} classes
now accept an @code{(address, netmask)} tuple argument, so as to easily construct
network objects from existing addresses:

@example
>>> import ipaddress
>>> ipaddress.IPv4Network(('127.0.0.0', 8))
IPv4Network('127.0.0.0/8')
>>> ipaddress.IPv4Network(('127.0.0.0', '255.0.0.0'))
IPv4Network('127.0.0.0/8')
@end example

(Contributed by Peter Moody and Antoine Pitrou in bpo-16531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16531}.)

A new @code{reverse_pointer} attribute for the
@ref{1fb,,IPv4Network} and @ref{1fc,,IPv6Network} classes
returns the name of the reverse DNS PTR record:

@example
>>> import ipaddress
>>> addr = ipaddress.IPv4Address('127.0.0.1')
>>> addr.reverse_pointer
'1.0.0.127.in-addr.arpa'
>>> addr6 = ipaddress.IPv6Address('::1')
>>> addr6.reverse_pointer
'1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa'
@end example

(Contributed by Leon Weber in bpo-20480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20480}.)

@node json<2>,linecache<2>,ipaddress<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 json}@anchor{e0c}
@subsubsection json


The @ref{82,,json.tool} command line interface now preserves the order of keys in
JSON objects passed in input.  The new @code{--sort-keys} option can be used
to sort the keys alphabetically. (Contributed by Berker Peksag
in bpo-21650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21650}.)

JSON decoder now raises @ref{e0d,,JSONDecodeError} instead of
@ref{1ff,,ValueError} to provide better context information about the error.
(Contributed by Serhiy Storchaka in bpo-19361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19361}.)

@node linecache<2>,locale<6>,json<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 linecache}@anchor{e0e}
@subsubsection @code{linecache}


A new @ref{e0f,,lazycache()} function can be used to capture information
about a non-file-based module to permit getting its lines later via
@ref{e10,,getline()}. This avoids doing I/O until a line is actually
needed, without having to carry the module globals around indefinitely.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

@node locale<6>,logging<5>,linecache<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 locale}@anchor{e11}
@subsubsection locale


A new @ref{e12,,delocalize()} function can be used to convert a string into
a normalized number string, taking the @code{LC_NUMERIC} settings into account:

@example
>>> import locale
>>> locale.setlocale(locale.LC_NUMERIC, 'de_DE.UTF-8')
'de_DE.UTF-8'
>>> locale.delocalize('1.234,56')
'1234.56'
>>> locale.setlocale(locale.LC_NUMERIC, 'en_US.UTF-8')
'en_US.UTF-8'
>>> locale.delocalize('1,234.56')
'1234.56'
@end example

(Contributed by Cédric Krier in bpo-13918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13918}.)

@node logging<5>,lzma,locale<6>,Modules améliorés<9>
@anchor{whatsnew/3 5 logging}@anchor{e13}
@subsubsection logging


All logging methods (@ref{b3d,,Logger} @ref{e14,,log()},
@ref{e15,,exception()}, @ref{e16,,critical()},
@ref{e17,,debug()}, etc.), now accept exception instances
as an `exc_info' argument, in addition to boolean values and exception
tuples:

@example
>>> import logging
>>> try:
...     1/0
... except ZeroDivisionError as ex:
...     logging.error('exception', exc_info=ex)
ERROR:root:exception
@end example

(Contributed by Yury Selivanov in bpo-20537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20537}.)

The @ref{e18,,handlers.HTTPHandler} class now
accepts an optional @ref{291,,ssl.SSLContext} instance to configure SSL
settings used in an HTTP connection.
(Contributed by Alex Gaynor in bpo-22788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22788}.)

The @ref{e19,,handlers.QueueListener} class now
takes a `respect_handler_level' keyword argument which, if set to @code{True},
will pass messages to handlers taking handler levels into account.
(Contributed by Vinay Sajip.)

@node lzma,math<8>,logging<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 lzma}@anchor{e1a}
@subsubsection lzma


The @ref{e1b,,LZMADecompressor.decompress()}
method now accepts an optional `max_length' argument to limit the maximum
size of decompressed data.
(Contributed by Martin Panter in bpo-15955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15955}.)

@node math<8>,multiprocessing<6>,lzma,Modules améliorés<9>
@anchor{whatsnew/3 5 math}@anchor{e1c}
@subsubsection `math'


Two new constants have been added to the @ref{8d,,math} module: @ref{c72,,inf}
and @ref{64e,,nan}.  (Contributed by Mark Dickinson in bpo-23185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23185}.)

A new function @ref{d9d,,isclose()} provides a way to test for approximate
equality. (Contributed by Chris Barker and Tal Einat in bpo-24270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24270}.)

A new @ref{8fd,,gcd()} function has been added.  The @code{fractions.gcd()}
function is now deprecated. (Contributed by Mark Dickinson and Serhiy
Storchaka in bpo-22486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22486}.)

@node multiprocessing<6>,operator<2>,math<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 multiprocessing}@anchor{e1d}
@subsubsection multiprocessing


@ref{e1e,,sharedctypes.synchronized()}
objects now support the @ref{5be,,context manager} protocol.
(Contributed by Charles-François Natali in bpo-21565@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21565}.)

@node operator<2>,os<10>,multiprocessing<6>,Modules améliorés<9>
@anchor{whatsnew/3 5 operator}@anchor{e1f}
@subsubsection @code{operator}


@ref{e20,,attrgetter()}, @ref{a50,,itemgetter()},
and @ref{e21,,methodcaller()} objects now support pickling.
(Contributed by Josh Rosenberg and Serhiy Storchaka in bpo-22955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22955}.)

New @ref{e22,,matmul()} and @ref{e23,,imatmul()} functions
to perform matrix multiplication.
(Contributed by Benjamin Peterson in bpo-21176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21176}.)

@node os<10>,pathlib<10>,operator<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 os}@anchor{e24}
@subsubsection `os'


The new @ref{a4d,,scandir()} function returning an iterator of
@ref{485,,DirEntry} objects has been added.  If possible, @ref{a4d,,scandir()}
extracts file attributes while scanning a directory, removing the need to
perform subsequent system calls to determine file type or attributes, which may
significantly improve performance.  (Contributed by Ben Hoyt with the help
of Victor Stinner in bpo-22524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22524}.)

On Windows, a new
@ref{e25,,stat_result.st_file_attributes}
attribute is now available.  It corresponds to the @code{dwFileAttributes} member
of the @code{BY_HANDLE_FILE_INFORMATION} structure returned by
@code{GetFileInformationByHandle()}.  (Contributed by Ben Hoyt in bpo-21719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21719}.)

The @ref{50c,,urandom()} function now uses the @code{getrandom()} syscall on Linux 3.17
or newer, and @code{getentropy()} on OpenBSD 5.6 and newer, removing the need to
use @code{/dev/urandom} and avoiding failures due to potential file descriptor
exhaustion.  (Contributed by Victor Stinner in bpo-22181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22181}.)

New @ref{e26,,get_blocking()} and @ref{e27,,set_blocking()} functions allow
getting and setting a file descriptor's blocking mode (@ref{e28,,O_NONBLOCK}.)
(Contributed by Victor Stinner in bpo-22054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22054}.)

The @ref{e29,,truncate()} and @ref{d7c,,ftruncate()} functions are now supported
on Windows.  (Contributed by Steve Dower in bpo-23668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23668}.)

There is a new @ref{e2a,,os.path.commonpath()} function returning the longest
common sub-path of each passed pathname.  Unlike the
@ref{e2b,,os.path.commonprefix()} function, it always returns a valid
path:

@example
>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'
@end example

(Contributed by Rafik Draoui and Serhiy Storchaka in bpo-10395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10395}.)

@node pathlib<10>,pickle<3>,os<10>,Modules améliorés<9>
@anchor{whatsnew/3 5 pathlib}@anchor{e2c}
@subsubsection pathlib


The new @ref{e2d,,Path.samefile()} method can be used
to check whether the path points to the same file as another path, which can
be either another @ref{226,,Path} object, or a string:

@example
>>> import pathlib
>>> p1 = pathlib.Path('/etc/hosts')
>>> p2 = pathlib.Path('/etc/../etc/hosts')
>>> p1.samefile(p2)
True
@end example

(Contributed by Vajrasky Kok and Antoine Pitrou in bpo-19775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19775}.)

The @ref{e2e,,Path.mkdir()} method now accepts a new optional
`exist_ok' argument to match @code{mkdir -p} and @ref{21b,,os.makedirs()}
functionality.  (Contributed by Berker Peksag in bpo-21539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21539}.)

There is a new @ref{e2f,,Path.expanduser()} method to
expand @code{~} and @code{~user} prefixes.  (Contributed by Serhiy Storchaka and
Claudiu Popa in bpo-19776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19776}.)

A new @ref{e30,,Path.home()} class method can be used to get
a @ref{226,,Path} instance representing the user’s home
directory.
(Contributed by Victor Salgado and Mayank Tripathi in bpo-19777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19777}.)

New @ref{e31,,Path.write_text()},
@ref{e32,,Path.read_text()},
@ref{e33,,Path.write_bytes()},
@ref{e34,,Path.read_bytes()} methods to simplify
read/write operations on files.

The following code snippet will create or rewrite existing file
@code{~/spam42}:

@example
>>> import pathlib
>>> p = pathlib.Path('~/spam42')
>>> p.expanduser().write_text('ham')
3
@end example

(Contributed by Christopher Welborn in bpo-20218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20218}.)

@node pickle<3>,poplib<2>,pathlib<10>,Modules améliorés<9>
@anchor{whatsnew/3 5 pickle}@anchor{e35}
@subsubsection pickle


Nested objects, such as unbound methods or nested classes, can now be pickled
using @ref{caf,,pickle protocols} older than protocol version 4.
Protocol version 4 already supports these cases.  (Contributed by Serhiy
Storchaka in bpo-23611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23611}.)

@node poplib<2>,re<7>,pickle<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 poplib}@anchor{e36}
@subsubsection `poplib'


A new @ref{e37,,POP3.utf8()} command enables 
@geindex RFC; RFC 6856
RFC 6856@footnote{https://datatracker.ietf.org/doc/html/rfc6856.html}
(Internationalized Email) support, if a POP server supports it.
(Contributed by Milan OberKirch in bpo-21804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21804}.)

@node re<7>,readline<2>,poplib<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 re}@anchor{e38}
@subsubsection @code{re}


References and conditional references to groups with fixed length are now
allowed in lookbehind assertions:

@example
>>> import re
>>> pat = re.compile(r'(a|b).(?<=\1)c')
>>> pat.match('aac')
<_sre.SRE_Match object; span=(0, 3), match='aac'>
>>> pat.match('bbc')
<_sre.SRE_Match object; span=(0, 3), match='bbc'>
@end example

(Contribution par Serhiy Storchaka; bpo-9179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9179}.)

The number of capturing groups in regular expressions is no longer limited to
100.  (Contributed by Serhiy Storchaka in bpo-22437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22437}.)

The @ref{2a0,,sub()} and @ref{2a1,,subn()} functions now replace unmatched
groups with empty strings instead of raising an exception.
(Contributed by Serhiy Storchaka in bpo-1519638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1519638}.)

The @code{re.error} exceptions have new attributes,
@code{msg}, @code{pattern},
@code{pos}, @code{lineno},
and @code{colno}, that provide better context
information about the error:

@example
>>> re.compile("""
...     (?x)
...     .++
... """)
Traceback (most recent call last):
   ...
sre_constants.error: multiple repeat at position 16 (line 3, column 7)
@end example

(Contribution par Serhiy Storchaka; bpo-22578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22578}.)

@node readline<2>,selectors,re<7>,Modules améliorés<9>
@anchor{whatsnew/3 5 readline}@anchor{e39}
@subsubsection readline


A new @ref{e3a,,append_history_file()} function can be used to append
the specified number of trailing elements in history to the given file.
(Contributed by Bruno Cauet in bpo-22940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22940}.)

@node selectors,shutils<5>,readline<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 selectors}@anchor{e3b}
@subsubsection selectors


The new @ref{bc5,,DevpollSelector} supports efficient
@code{/dev/poll} polling on Solaris.
(Contributed by Giampaolo Rodola' in bpo-18931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18931}.)

@node shutils<5>,signal<3>,selectors,Modules améliorés<9>
@anchor{whatsnew/3 5 shutil}@anchor{e3c}
@subsubsection @code{shutils}


The @ref{a4a,,move()} function now accepts a `copy_function' argument,
allowing, for example, the @ref{a48,,copy()} function to be used instead of
the default @ref{a49,,copy2()} if there is a need to ignore file metadata
when moving.
(Contributed by Claudiu Popa in bpo-19840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19840}.)

The @ref{49c,,make_archive()} function now supports the `xztar' format.
(Contributed by Serhiy Storchaka in bpo-5411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5411}.)

@node signal<3>,smtpd<2>,shutils<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 signal}@anchor{e3d}
@subsubsection `signal'


On Windows, the @ref{b5e,,set_wakeup_fd()} function now also supports
socket handles.  (Contributed by Victor Stinner in bpo-22018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22018}.)

Various @code{SIG*} constants in the @ref{c5,,signal} module have been converted into
@ref{55,,Enums}.  This allows meaningful names to be printed
during debugging, instead of integer "magic numbers".
(Contributed by Giampaolo Rodola' in bpo-21076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21076}.)

@node smtpd<2>,smtplib<2>,signal<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 smtpd}@anchor{e3e}
@subsubsection smtpd


Both the @code{SMTPServer} and @code{SMTPChannel} classes now
accept a `decode_data' keyword argument to determine if the @code{DATA} portion of
the SMTP transaction is decoded using the @code{"utf-8"} codec or is instead
provided to the
@code{SMTPServer.process_message()}
method as a byte string.  The default is @code{True} for backward compatibility
reasons, but will change to @code{False} in Python 3.6.  If `decode_data' is set
to @code{False}, the @code{process_message} method must be prepared to accept keyword
arguments.
(Contributed by Maciej Szulik in bpo-19662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19662}.)

The @code{SMTPServer} class now advertises the @code{8BITMIME} extension
(
@geindex RFC; RFC 6152
RFC 6152@footnote{https://datatracker.ietf.org/doc/html/rfc6152.html}) if `decode_data' has been set @code{True}.  If the client
specifies @code{BODY=8BITMIME} on the @code{MAIL} command, it is passed to
@code{SMTPServer.process_message()}
via the `mail_options' keyword.
(Contributed by Milan Oberkirch and R.  David Murray in bpo-21795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21795}.)

The @code{SMTPServer} class now also supports the @code{SMTPUTF8}
extension (
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}: Internationalized Email).  If the client specified
@code{SMTPUTF8 BODY=8BITMIME} on the @code{MAIL} command, they are passed to
@code{SMTPServer.process_message()}
via the `mail_options' keyword.  It is the responsibility of the
@code{process_message} method to correctly handle the @code{SMTPUTF8} data.
(Contributed by Milan Oberkirch in bpo-21725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21725}.)

It is now possible to provide, directly or via name resolution, IPv6
addresses in the @code{SMTPServer} constructor, and have it
successfully connect.  (Contributed by Milan Oberkirch in bpo-14758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14758}.)

@node smtplib<2>,sndhdr,smtpd<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 smtplib}@anchor{e3f}
@subsubsection `smtplib'


A new @ref{e40,,SMTP.auth()} method provides a convenient way to
implement custom authentication mechanisms. (Contributed by Milan
Oberkirch in bpo-15014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15014}.)

The @ref{e41,,SMTP.set_debuglevel()} method now
accepts an additional debuglevel (2), which enables timestamps in debug
messages. (Contributed by Gavin Chappell and Maciej Szulik in bpo-16914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16914}.)

Both the @ref{e42,,SMTP.sendmail()} and
@ref{e43,,SMTP.send_message()} methods now
support 
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html} (SMTPUTF8).
(Contributed by Milan Oberkirch and R. David Murray in bpo-22027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22027}.)

@node sndhdr,socket<8>,smtplib<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 sndhdr}@anchor{e44}
@subsubsection sndhdr


The @code{what()} and @code{whathdr()} functions  now return
a @ref{1c5,,namedtuple()}.  (Contributed by Claudiu Popa in
bpo-18615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18615}.)

@node socket<8>,ssl<9>,sndhdr,Modules améliorés<9>
@anchor{whatsnew/3 5 socket}@anchor{e45}
@subsubsection `socket'


Functions with timeouts now use a monotonic clock, instead of a system clock.
(Contributed by Victor Stinner in bpo-22043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22043}.)

A new @ref{e46,,socket.sendfile()} method allows
sending a file over a socket by using the high-performance @ref{afd,,os.sendfile()}
function on UNIX, resulting in uploads being from 2 to 3 times faster than when
using plain @ref{d94,,socket.send()}.
(Contributed by Giampaolo Rodola' in bpo-17552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17552}.)

The @ref{d95,,socket.sendall()} method no longer resets the
socket timeout every time bytes are received or sent.  The socket timeout is
now the maximum total duration to send all data.
(Contributed by Victor Stinner in bpo-23853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23853}.)

The `backlog' argument of the @ref{e47,,socket.listen()}
method is now optional.  By default it is set to
@ref{e48,,SOMAXCONN} or to @code{128}, whichever is less.
(Contributed by Charles-François Natali in bpo-21455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21455}.)

@node ssl<9>,sqlite3<8>,socket<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 ssl}@anchor{e49}
@subsubsection @code{ssl}


@menu
* Memory BIO Support:: 
* Application-Layer Protocol Negotiation Support:: 
* Other Changes:: 

@end menu

@node Memory BIO Support,Application-Layer Protocol Negotiation Support,,ssl<9>
@anchor{whatsnew/3 5 memory-bio-support}@anchor{e4a}@anchor{whatsnew/3 5 whatsnew-sslmemorybio}@anchor{d5d}
@subsubsection Memory BIO Support


(Contributed by Geert Jansen in bpo-21965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21965}.)

The new @ref{b6f,,SSLObject} class has been added to provide SSL protocol
support for cases when the network I/O capabilities of @ref{8d7,,SSLSocket}
are not necessary or are suboptimal.  @code{SSLObject} represents
an SSL protocol instance, but does not implement any network I/O methods, and
instead provides a memory buffer interface.  The new @ref{e4b,,MemoryBIO}
class can be used to pass data between Python and an SSL protocol instance.

The memory BIO SSL support is primarily intended to be used in frameworks
implementing asynchronous I/O for which @ref{8d7,,SSLSocket}'s readiness
model ("select/poll") is inefficient.

A new @ref{b70,,SSLContext.wrap_bio()} method can be used
to create a new @code{SSLObject} instance.

@node Application-Layer Protocol Negotiation Support,Other Changes,Memory BIO Support,ssl<9>
@anchor{whatsnew/3 5 application-layer-protocol-negotiation-support}@anchor{e4c}
@subsubsection Application-Layer Protocol Negotiation Support


(Contributed by Benjamin Peterson in bpo-20188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20188}.)

Where OpenSSL support is present, the @ref{cf,,ssl} module now implements
the `Application-Layer Protocol Negotiation' TLS extension as described
in 
@geindex RFC; RFC 7301
RFC 7301@footnote{https://datatracker.ietf.org/doc/html/rfc7301.html}.

The new @ref{e4d,,SSLContext.set_alpn_protocols()}
can be used to specify which protocols a socket should advertise during
the TLS handshake.

The new
@ref{e4e,,SSLSocket.selected_alpn_protocol()}
returns the protocol that was selected during the TLS handshake.
The @ref{e4f,,HAS_ALPN} flag indicates whether ALPN support is present.

@node Other Changes,,Application-Layer Protocol Negotiation Support,ssl<9>
@anchor{whatsnew/3 5 other-changes}@anchor{e50}
@subsubsection Other Changes


There is a new @ref{e51,,SSLSocket.version()} method to
query the actual protocol version in use.
(Contributed by Antoine Pitrou in bpo-20421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20421}.)

The @ref{8d7,,SSLSocket} class now implements
a @code{SSLSocket.sendfile()} method.
(Contributed by Giampaolo Rodola' in bpo-17552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17552}.)

The @code{SSLSocket.send()} method now raises either
the @ref{e52,,ssl.SSLWantReadError} or @ref{e53,,ssl.SSLWantWriteError} exception on a
non-blocking socket if the operation would block. Previously, it would return
@code{0}.  (Contributed by Nikolaus Rath in bpo-20951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20951}.)

The @ref{e54,,cert_time_to_seconds()} function now interprets the input time
as UTC and not as local time, per 
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}.  Additionally, the return
value is always an @ref{254,,int}. (Contributed by Akira Li in bpo-19940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19940}.)

New @code{SSLObject.shared_ciphers()} and
@ref{e55,,SSLSocket.shared_ciphers()} methods return
the list of ciphers sent by the client during the handshake.
(Contributed by Benjamin Peterson in bpo-23186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23186}.)

The @ref{e56,,SSLSocket.do_handshake()},
@ref{e57,,SSLSocket.read()},
@code{SSLSocket.shutdown()}, and
@ref{e58,,SSLSocket.write()} methods of the @ref{8d7,,SSLSocket}
class no longer reset the socket timeout every time bytes are received or sent.
The socket timeout is now the maximum total duration of the method.
(Contributed by Victor Stinner in bpo-23853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23853}.)

The @code{match_hostname()} function now supports matching of IP addresses.
(Contributed by Antoine Pitrou in bpo-23239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23239}.)

@node sqlite3<8>,subprocess<4>,ssl<9>,Modules améliorés<9>
@anchor{whatsnew/3 5 sqlite3}@anchor{e59}
@subsubsection @code{sqlite3}


The @ref{e5a,,Row} class now fully supports the sequence protocol,
in particular @ref{850,,reversed()} iteration and slice indexing.
(Contributed by Claudiu Popa in bpo-10203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10203}; by Lucas Sinclair,
Jessica McKellar, and  Serhiy Storchaka in bpo-13583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13583}.)

@node subprocess<4>,sys<11>,sqlite3<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 subprocess}@anchor{e5b}@anchor{whatsnew/3 5 whatsnew-subprocess}@anchor{d60}
@subsubsection subprocess


The new @ref{b74,,run()} function has been added.
It runs the specified command and returns a
@ref{e5c,,CompletedProcess} object, which describes a finished
process.  The new API is more consistent and is the recommended approach
to invoking subprocesses in Python code that does not need to maintain
compatibility with earlier Python versions.
(Contributed by Thomas Kluyver in bpo-23342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23342}.)

Exemples :

@example
>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')
@end example

@node sys<11>,sysconfig<2>,subprocess<4>,Modules améliorés<9>
@anchor{whatsnew/3 5 sys}@anchor{e5d}
@subsubsection sys


A new @code{set_coroutine_wrapper()} function allows setting a global
hook that will be called whenever a @ref{47b,,coroutine object}
is created by an @ref{5bb,,async def} function.  A corresponding
@code{get_coroutine_wrapper()} can be used to obtain a currently set
wrapper.  Both functions are @ref{af1,,provisional},
and are intended for debugging purposes only.  (Contributed by Yury Selivanov
in bpo-24017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24017}.)

A new @ref{a7d,,is_finalizing()} function can be used to check if the Python
interpreter is @ref{14d,,shutting down}.
(Contributed by Antoine Pitrou in bpo-22696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22696}.)

@node sysconfig<2>,tarfile<6>,sys<11>,Modules améliorés<9>
@anchor{whatsnew/3 5 sysconfig}@anchor{e5e}
@subsubsection @code{sysconfig}


The name of the user scripts directory on Windows now includes the first
two components of the Python version. (Contributed by Paul Moore
in bpo-23437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23437}.)

@node tarfile<6>,threading<6>,sysconfig<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 tarfile}@anchor{e5f}
@subsubsection tarfile


The `mode' argument of the @ref{e60,,open()} function now accepts @code{"x"}
to request exclusive creation.  (Contributed by Berker Peksag in bpo-21717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21717}.)

The @ref{e61,,TarFile.extractall()} and
@ref{e62,,TarFile.extract()} methods now take a keyword
argument `numeric_owner'.  If set to @code{True}, the extracted files and
directories will be owned by the numeric @code{uid} and @code{gid} from the tarfile.
If set to @code{False} (the default, and the behavior in versions prior to 3.5),
they will be owned by the named user and group in the tarfile.
(Contributed by Michael Vogt and Eric Smith in bpo-23193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23193}.)

The @ref{e63,,TarFile.list()} now accepts an optional
`members' keyword argument that can be set to a subset of the list returned
by @ref{e64,,TarFile.getmembers()}.
(Contributed by Serhiy Storchaka in bpo-21549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21549}.)

@node threading<6>,time<7>,tarfile<6>,Modules améliorés<9>
@anchor{whatsnew/3 5 threading}@anchor{e65}
@subsubsection threading


Both the @ref{683,,Lock.acquire()} and
@ref{e66,,RLock.acquire()} methods
now use a monotonic clock for timeout management.
(Contributed by Victor Stinner in bpo-22043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22043}.)

@node time<7>,timeit<2>,threading<6>,Modules améliorés<9>
@anchor{whatsnew/3 5 time}@anchor{e67}
@subsubsection time


The @ref{250,,monotonic()} function is now always available.
(Contributed by Victor Stinner in bpo-22043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22043}.)

@node timeit<2>,tkinter<8>,time<7>,Modules améliorés<9>
@anchor{whatsnew/3 5 timeit}@anchor{e68}
@subsubsection timeit


A new command line option @code{-u} or @code{--unit=@var{U}} can be used to specify the time
unit for the timer output.  Supported options are @code{usec}, @code{msec},
or @code{sec}.  (Contributed by Julian Gindi in bpo-18983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18983}.)

The @ref{e69,,timeit()} function has a new `globals' parameter for
specifying the namespace in which the code will be running.
(Contributed by Ben Roberts in bpo-2527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2527}.)

@node tkinter<8>,traceback<5>,timeit<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 tkinter}@anchor{e6a}
@subsubsection tkinter


The @code{tkinter._fix} module used for setting up the Tcl/Tk environment
on Windows has been replaced by a private function in the @code{_tkinter}
module which makes no permanent changes to environment variables.
(Contributed by Zachary Ware in bpo-20035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20035}.)

@node traceback<5>,types<5>,tkinter<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 traceback}@anchor{e6b}@anchor{whatsnew/3 5 whatsnew-traceback}@anchor{d61}
@subsubsection traceback


New @ref{e6c,,walk_stack()} and @ref{e6d,,walk_tb()}
functions to conveniently traverse frame and
@ref{ae2,,traceback objects}.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

New lightweight classes: @ref{259,,TracebackException},
@ref{e6e,,StackSummary}, and @ref{e6f,,FrameSummary}.
(Contributed by Robert Collins in bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}.)

Both the @ref{e70,,print_tb()} and @ref{e71,,print_stack()} functions
now support negative values for the `limit' argument.
(Contributed by Dmitry Kazakov in bpo-22619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22619}.)

@node types<5>,unicodedata<8>,traceback<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 types}@anchor{e72}
@subsubsection @code{types}


A new @ref{e73,,coroutine()} function to transform
@ref{bcc,,generator} and
@ref{dc8,,generator-like} objects into
@ref{1ab,,awaitables}.
(Contributed by Yury Selivanov in bpo-24017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24017}.)

A new type called @ref{e74,,CoroutineType}, which is used for
@ref{47b,,coroutine} objects created by @ref{5bb,,async def} functions.
(Contributed by Yury Selivanov in bpo-24400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24400}.)

@node unicodedata<8>,unittest<8>,types<5>,Modules améliorés<9>
@anchor{whatsnew/3 5 unicodedata}@anchor{e75}
@subsubsection unicodedata


The @ref{104,,unicodedata} module now uses data from Unicode 8.0.0@footnote{https://unicode.org/versions/Unicode8.0.0/}.

@node unittest<8>,unittest mock<3>,unicodedata<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 unittest}@anchor{e76}
@subsubsection unittest


The @ref{28c,,TestLoader.loadTestsFromModule()}
method now accepts a keyword-only argument `pattern' which is passed to
@code{load_tests} as the third argument.  Found packages are now checked for
@code{load_tests} regardless of whether their path matches `pattern', because it
is impossible for a package name to match the default pattern.
(Contributed by Robert Collins and Barry A. Warsaw in bpo-16662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16662}.)

Unittest discovery errors now are exposed in the
@ref{e77,,TestLoader.errors} attribute of the
@ref{28b,,TestLoader} instance.
(Contributed by Robert Collins in bpo-19746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19746}.)

A new command line option @code{--locals} to show local variables in
tracebacks.  (Contributed by Robert Collins in bpo-22936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22936}.)

@node unittest mock<3>,urllib<2>,unittest<8>,Modules améliorés<9>
@anchor{whatsnew/3 5 unittest-mock}@anchor{e78}
@subsubsection unittest.mock


The @ref{a3a,,Mock} class has the following improvements:


@itemize *

@item 
The class constructor has a new `unsafe' parameter, which causes mock
objects to raise @ref{343,,AttributeError} on attribute names starting
with @code{"assert"}.
(Contributed by Kushal Das in bpo-21238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21238}.)

@item 
A new @ref{e79,,Mock.assert_not_called()}
method to check if the mock object was called.
(Contributed by Kushal Das in bpo-21262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21262}.)
@end itemize

The @ref{e7a,,MagicMock} class now supports @code{__truediv__()},
@code{__divmod__()} and @code{__matmul__()} operators.
(Contributed by Johannes Baiter in bpo-20968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20968}, and Håkan Lövdahl
in bpo-23581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23581} and bpo-23568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23568}.)

It is no longer necessary to explicitly pass @code{create=True} to the
@ref{e7b,,patch()} function when patching builtin names.
(Contributed by Kushal Das in bpo-17660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17660}.)

@node urllib<2>,wsgiref,unittest mock<3>,Modules améliorés<9>
@anchor{whatsnew/3 5 urllib}@anchor{e7c}
@subsubsection urllib


A new
@ref{e7d,,request.HTTPPasswordMgrWithPriorAuth}
class allows HTTP Basic Authentication credentials to be managed so as to
eliminate unnecessary @code{401} response handling, or to unconditionally send
credentials on the first request in order to communicate with servers that
return a @code{404} response instead of a @code{401} if the @code{Authorization} header
is not sent. (Contributed by Matej Cepl in bpo-19494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19494} and Akshit Khurana in
bpo-7159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7159}.)

A new `quote_via' argument for the
@ref{e7e,,parse.urlencode()}
function provides a way to control the encoding of query parts if needed.
(Contributed by Samwyse and Arnon Yaari in bpo-13866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13866}.)

The @ref{290,,request.urlopen()} function accepts an
@ref{291,,ssl.SSLContext} object as a `context' argument, which will be used for
the HTTPS connection.  (Contributed by Alex Gaynor in bpo-22366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22366}.)

The @ref{e7f,,parse.urljoin()} was updated to use the
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html} semantics for the resolution of relative URLs, rather than
@geindex RFC; RFC 1808
RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html} and 
@geindex RFC; RFC 2396
RFC 2396@footnote{https://datatracker.ietf.org/doc/html/rfc2396.html}.
(Contributed by Demian Brecht and Senthil Kumaran in bpo-22118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22118}.)

@node wsgiref,xmlrpc<2>,urllib<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 wsgiref}@anchor{e80}
@subsubsection wsgiref


The `headers' argument of the @ref{e81,,headers.Headers}
class constructor is now optional.
(Contributed by Pablo Torres Navarrete and SilentGhost in bpo-5800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5800}.)

@node xmlrpc<2>,xml sax,wsgiref,Modules améliorés<9>
@anchor{whatsnew/3 5 xmlrpc}@anchor{e82}
@subsubsection xmlrpc


The @ref{a45,,client.ServerProxy} class now supports
the @ref{5be,,context manager} protocol.
(Contributed by Claudiu Popa in bpo-20627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20627}.)

The @ref{a45,,client.ServerProxy} constructor now accepts
an optional @ref{291,,ssl.SSLContext} instance.
(Contributed by Alex Gaynor in bpo-22960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22960}.)

@node xml sax,zipfile<4>,xmlrpc<2>,Modules améliorés<9>
@anchor{whatsnew/3 5 xml-sax}@anchor{e83}
@subsubsection xml.sax


SAX parsers now support a character stream of the
@ref{e84,,xmlreader.InputSource} object.
(Contributed by Serhiy Storchaka in bpo-2175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2175}.)

@ref{e85,,parseString()} now accepts a @ref{435,,str} instance.
(Contributed by Serhiy Storchaka in bpo-10590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10590}.)

@node zipfile<4>,,xml sax,Modules améliorés<9>
@anchor{whatsnew/3 5 zipfile}@anchor{e86}
@subsubsection zipfile


ZIP output can now be written to unseekable streams.
(Contributed by Serhiy Storchaka in bpo-23252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23252}.)

The `mode' argument of @ref{411,,ZipFile.open()} method now
accepts @code{"x"} to request exclusive creation.
(Contributed by Serhiy Storchaka in bpo-21717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21717}.)

@node Other module-level changes,Optimizations<4>,Modules améliorés<9>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 other-module-level-changes}@anchor{e87}
@subsection Other module-level changes


Many functions in the @ref{8f,,mmap}, @code{ossaudiodev}, @ref{cb,,socket},
@ref{cf,,ssl}, and @ref{1b,,codecs} modules now accept writable
@ref{d1b,,bytes-like objects}.
(Contributed by Serhiy Storchaka in bpo-23001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23001}.)

@node Optimizations<4>,Build and C API Changes<3>,Other module-level changes,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 optimizations}@anchor{e88}
@subsection Optimizations


The @ref{493,,os.walk()} function has been sped up by 3 to 5 times on POSIX systems,
and by 7 to 20 times on Windows.  This was done using the new @ref{a4d,,os.scandir()}
function, which exposes file information from the underlying @code{readdir} or
@code{FindFirstFile}/@code{FindNextFile} system calls.  (Contributed by
Ben Hoyt with help from Victor Stinner in bpo-23605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23605}.)

Construction of @code{bytes(int)} (filled by zero bytes) is faster and uses less
memory for large objects. @code{calloc()} is used instead of @code{malloc()} to
allocate memory for these objects.
(Contributed by Victor Stinner in bpo-21233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21233}.)

Some operations on @ref{7f,,ipaddress} @ref{1fb,,IPv4Network} and
@ref{1fc,,IPv6Network} have been massively sped up, such as
@ref{e89,,subnets()}, @ref{e8a,,supernet()},
@ref{e8b,,summarize_address_range()}, @ref{e8c,,collapse_addresses()}.
The speed up can range from 3 to 15 times.
(Contributed by Antoine Pitrou, Michel Albert, and Markus in
bpo-21486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21486}, bpo-21487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21487}, bpo-20826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20826}, bpo-23266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23266}.)

Pickling of @ref{7f,,ipaddress} objects was optimized to produce significantly
smaller output.  (Contributed by Serhiy Storchaka in bpo-23133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23133}.)

Many operations on @ref{e8d,,io.BytesIO} are now 50% to 100% faster.
(Contributed by Serhiy Storchaka in bpo-15381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15381} and David Wilson in
bpo-22003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22003}.)

The @ref{e8e,,marshal.dumps()} function is now faster: 65--85% with versions 3
and 4, 20--25% with versions 0 to 2 on typical data, and up to 5 times in
best cases.
(Contributed by Serhiy Storchaka in bpo-20416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20416} and bpo-23344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23344}.)

The UTF-32 encoder is now 3 to 7 times faster.
(Contributed by Serhiy Storchaka in bpo-15027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15027}.)

Regular expressions are now parsed up to 10% faster.
(Contributed by Serhiy Storchaka in bpo-19380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19380}.)

The @ref{d33,,json.dumps()} function was optimized to run with
@code{ensure_ascii=False} as fast as with @code{ensure_ascii=True}.
(Contributed by Naoki Inada in bpo-23206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23206}.)

The @ref{e8f,,PyObject_IsInstance()} and @ref{e90,,PyObject_IsSubclass()}
functions have been sped up in the common case that the second argument
has @ref{d36,,type} as its metaclass.
(Contributed Georg Brandl by in bpo-22540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22540}.)

Method caching was slightly improved, yielding up to 5% performance
improvement in some benchmarks.
(Contributed by Antoine Pitrou in bpo-22847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22847}.)

Objects from the @ref{b7,,random} module now use 50% less memory on 64-bit
builds.  (Contributed by Serhiy Storchaka in bpo-23488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23488}.)

The @ref{192,,property()} getter calls are up to 25% faster.
(Contributed by Joe Jevnik in bpo-23910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23910}.)

Instantiation of @ref{1e4,,fractions.Fraction} is now up to 30% faster.
(Contributed by Stefan Behnel in bpo-22464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22464}.)

String methods @ref{e91,,find()}, @ref{e92,,rfind()}, @ref{e93,,split()},
@ref{e94,,partition()} and the @ref{2e8,,in} string operator are now significantly
faster for searching 1-character substrings.
(Contributed by Serhiy Storchaka in bpo-23573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23573}.)

@node Build and C API Changes<3>,Obsolescence<10>,Optimizations<4>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 build-and-c-api-changes}@anchor{e95}
@subsection Build and C API Changes


New @code{calloc} functions were added:


@itemize *

@item 
@ref{387,,PyMem_RawCalloc()},

@item 
@ref{e96,,PyMem_Calloc()},

@item 
@ref{e97,,PyObject_Calloc()}.
@end itemize

(Contribution par Victor Stinner; bpo-21233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21233}.)

New encoding/decoding helper functions:


@itemize *

@item 
@ref{bb5,,Py_DecodeLocale()} (replaced @code{_Py_char2wchar()}),

@item 
@ref{bb6,,Py_EncodeLocale()} (replaced @code{_Py_wchar2char()}).
@end itemize

(Contribution par Victor Stinner; bpo-18395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18395}.)

A new @ref{e98,,PyCodec_NameReplaceErrors()} function to replace the unicode
encode error with @code{\N@{...@}} escapes.
(Contributed by Serhiy Storchaka in bpo-19676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19676}.)

A new @ref{e99,,PyErr_FormatV()} function similar to @ref{e9a,,PyErr_Format()},
but accepts a @code{va_list} argument.
(Contributed by Antoine Pitrou in bpo-18711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18711}.)

A new @code{PyExc_RecursionError} exception.
(Contributed by Georg Brandl in bpo-19235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19235}.)

New @ref{e9b,,PyModule_FromDefAndSpec()}, @ref{e9c,,PyModule_FromDefAndSpec2()},
and @ref{e9d,,PyModule_ExecDef()} functions introduced by 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} --
multi-phase extension module initialization.
(Contributed by Petr Viktorin in bpo-24268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24268}.)

New @ref{e9e,,PyNumber_MatrixMultiply()} and
@ref{e9f,,PyNumber_InPlaceMatrixMultiply()} functions to perform matrix
multiplication.
(Contributed by Benjamin Peterson in bpo-21176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21176}.  See also 
@geindex Python Enhancement Proposals; PEP 465
PEP 465@footnote{https://peps.python.org/pep-0465/}
for details.)

The @ref{a94,,PyTypeObject.tp_finalize} slot is now part of the stable ABI.

Windows builds now require Microsoft Visual C++ 14.0, which
is available as part of Visual Studio 2015@footnote{https://visualstudio.microsoft.com/en/vs/older-downloads/#visual-studio-2015-and-other-products}.

Extension modules now include a platform information tag in their filename on
some platforms (the tag is optional, and CPython will import extensions without
it, although if the tag is present and mismatched, the extension won't be
loaded):


@itemize *

@item 
On Linux, extension module filenames end with
@code{.cpython-<major><minor>m-<architecture>-<os>.pyd}:


@itemize *

@item 
@code{<major>} is the major number of the Python version;
for Python 3.5 this is @code{3}.

@item 
@code{<minor>} is the minor number of the Python version;
for Python 3.5 this is @code{5}.

@item 
@code{<architecture>} is the hardware architecture the extension module
was built to run on. It's most commonly either @code{i386} for 32-bit Intel
platforms or @code{x86_64} for 64-bit Intel (and AMD) platforms.

@item 
@code{<os>} is always @code{linux-gnu}, except for extensions built to
talk to the 32-bit ABI on 64-bit platforms, in which case it is
@code{linux-gnu32} (and @code{<architecture>} will be @code{x86_64}).
@end itemize

@item 
On Windows, extension module filenames end with
@code{<debug>.cp<major><minor>-<platform>.pyd}:


@itemize *

@item 
@code{<major>} is the major number of the Python version;
for Python 3.5 this is @code{3}.

@item 
@code{<minor>} is the minor number of the Python version;
for Python 3.5 this is @code{5}.

@item 
@code{<platform>} is the platform the extension module was built for,
either @code{win32} for Win32, @code{win_amd64} for Win64, @code{win_ia64} for
Windows Itanium 64, and @code{win_arm} for Windows on ARM.

@item 
If built in debug mode, @code{<debug>} will be @code{_d},
otherwise it will be blank.
@end itemize

@item 
On OS X platforms, extension module filenames now end with @code{-darwin.so}.

@item 
On all other platforms, extension module filenames are the same as they were
with Python 3.4.
@end itemize

@node Obsolescence<10>,Retraits<8>,Build and C API Changes<3>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 deprecated}@anchor{ea0}
@subsection Obsolescence


@menu
* Nouveaux mot-clefs: Nouveaux mot-clefs<2>. 
* Deprecated Python Behavior: Deprecated Python Behavior<2>. 
* Unsupported Operating Systems:: 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<3>. 

@end menu

@node Nouveaux mot-clefs<2>,Deprecated Python Behavior<2>,,Obsolescence<10>
@anchor{whatsnew/3 5 new-keywords}@anchor{ea1}
@subsubsection Nouveaux mot-clefs


@code{async} and @code{await} are not recommended to be used as variable, class,
function or module names.  Introduced by 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} in Python 3.5, they will
become proper keywords in Python 3.7.

@node Deprecated Python Behavior<2>,Unsupported Operating Systems,Nouveaux mot-clefs<2>,Obsolescence<10>
@anchor{whatsnew/3 5 deprecated-python-behavior}@anchor{ea2}
@subsubsection Deprecated Python Behavior


Raising the @ref{be8,,StopIteration} exception inside a generator will now generate a silent
@ref{8b5,,PendingDeprecationWarning}, which will become a non-silent deprecation
warning in Python 3.6 and will trigger a @ref{193,,RuntimeError} in Python 3.7.
See @ref{d0d,,PEP 479; Change StopIteration handling inside generators}
for details.

@node Unsupported Operating Systems,Deprecated Python modules functions and methods<3>,Deprecated Python Behavior<2>,Obsolescence<10>
@anchor{whatsnew/3 5 unsupported-operating-systems}@anchor{ea3}
@subsubsection Unsupported Operating Systems


Windows XP is no longer supported by Microsoft, thus, per 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}, CPython
3.5 is no longer officially supported on this OS.

@node Deprecated Python modules functions and methods<3>,,Unsupported Operating Systems,Obsolescence<10>
@anchor{whatsnew/3 5 deprecated-python-modules-functions-and-methods}@anchor{ea4}
@subsubsection Deprecated Python modules, functions and methods


The @code{formatter} module has now graduated to full deprecation and is still
slated for removal in Python 3.6.

The @code{asyncio.async()} function is deprecated in favor of
@ref{c64,,ensure_future()}.

The @code{smtpd} module has in the past always decoded the DATA portion of
email messages using the @code{utf-8} codec.  This can now be controlled by the
new `decode_data' keyword to @code{SMTPServer}.  The default value is
@code{True}, but this default is deprecated.  Specify the `decode_data' keyword
with an appropriate value to avoid the deprecation warning.

Directly assigning values to the @ref{bef,,key},
@ref{bf0,,value} and
@ref{bf1,,coded_value} of @ref{bf2,,http.cookies.Morsel}
objects is deprecated.  Use the @ref{bf3,,set()} method
instead.  In addition, the undocumented `LegalChars' parameter of
@ref{bf3,,set()} is deprecated, and is now ignored.

Passing a format string as keyword argument `format_string' to the
@ref{bee,,format()} method of the @ref{ea5,,string.Formatter}
class has been deprecated.
(Contributed by Serhiy Storchaka in bpo-23671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23671}.)

The @code{platform.dist()} and @code{platform.linux_distribution()} functions
are now deprecated.  Linux distributions use too many different ways of
describing themselves, so the functionality is left to a package.
(Contributed by Vajrasky Kok and Berker Peksag in bpo-1322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1322}.)

The previously undocumented @code{from_function} and @code{from_builtin} methods of
@ref{1ca,,inspect.Signature} are deprecated.  Use the new
@ref{724,,Signature.from_callable()}
method instead. (Contributed by Yury Selivanov in bpo-24248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24248}.)

The @code{inspect.getargspec()} function is deprecated and scheduled to be
removed in Python 3.6.  (See bpo-20438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20438} for details.)

The @ref{7d,,inspect} @ref{723,,getfullargspec()},
@ref{ea6,,getcallargs()}, and @code{formatargspec()} functions are
deprecated in favor of the @ref{722,,inspect.signature()} API. (Contributed by Yury
Selivanov in bpo-20438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20438}.)

@ref{ea7,,getargvalues()} and @ref{ea8,,formatargvalues()} functions
were inadvertently marked as deprecated with the release of Python 3.5.0.

Use of @ref{b5a,,re.LOCALE} flag with str patterns or @ref{617,,re.ASCII} is now
deprecated.  (Contributed by Serhiy Storchaka in bpo-22407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22407}.)

Use of unrecognized special sequences consisting of @code{'\'} and an ASCII letter
in regular expression patterns and replacement patterns now raises a
deprecation warning and will be forbidden in Python 3.6.
(Contributed by Serhiy Storchaka in bpo-23622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23622}.)

The undocumented and unofficial `use_load_tests' default argument of the
@ref{28c,,unittest.TestLoader.loadTestsFromModule()} method now is
deprecated and ignored.
(Contributed by Robert Collins and Barry A. Warsaw in bpo-16662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16662}.)

@node Retraits<8>,Portage vers Python 3 5,Obsolescence<10>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 removed}@anchor{ea9}
@subsection Retraits


@menu
* API and Feature Removals: API and Feature Removals<4>. 

@end menu

@node API and Feature Removals<4>,,,Retraits<8>
@anchor{whatsnew/3 5 api-and-feature-removals}@anchor{eaa}
@subsubsection API and Feature Removals


The following obsolete and previously deprecated APIs and features have been
removed:


@itemize *

@item 
The @code{__version__} attribute has been dropped from the email package.  The
email code hasn't been shipped separately from the stdlib for a long time,
and the @code{__version__} string was not updated in the last few releases.

@item 
The internal @code{Netrc} class in the @ref{5d,,ftplib} module was deprecated in
3.4, and has now been removed.
(Contributed by Matt Chaput in bpo-6623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6623}.)

@item 
The concept of @code{.pyo} files has been removed.

@item 
The JoinableQueue class in the provisional @ref{a,,asyncio} module was
deprecated in 3.4.4 and is now removed.
(Contributed by A. Jesse Jiryu Davis in bpo-23464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23464}.)
@end itemize

@node Portage vers Python 3 5,Notable changes in Python 3 5 4,Retraits<8>,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 porting-to-python-3-5}@anchor{eab}
@subsection Portage vers Python 3.5


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changes in Python behavior: Changes in Python behavior<2>. 
* Changements dans l'API Python: Changements dans l'API Python<9>. 
* Changements dans l'API C: Changements dans l'API C<7>. 

@end menu

@node Changes in Python behavior<2>,Changements dans l'API Python<9>,,Portage vers Python 3 5
@anchor{whatsnew/3 5 changes-in-python-behavior}@anchor{eac}
@subsubsection Changes in Python behavior



@itemize *

@item 
Due to an oversight, earlier Python versions erroneously accepted the
following syntax:

@example
f(1 for x in [1], *args)
f(1 for x in [1], **kwargs)
@end example

Python 3.5 now correctly raises a @ref{18b,,SyntaxError}, as generator
expressions must be put in parentheses if not a sole argument to a function.
@end itemize

@node Changements dans l'API Python<9>,Changements dans l'API C<7>,Changes in Python behavior<2>,Portage vers Python 3 5
@anchor{whatsnew/3 5 changes-in-the-python-api}@anchor{ead}
@subsubsection Changements dans l'API Python



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}: System calls are now retried when interrupted by a signal instead
of raising @ref{d75,,InterruptedError} if the Python signal handler does not
raise an exception.

@item 
Before Python 3.5, a @ref{1c9,,datetime.time} object was considered to be false
if it represented midnight in UTC.  This behavior was considered obscure and
error-prone and has been removed in Python 3.5.  See bpo-13936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13936} for full
details.

@item 
The @code{ssl.SSLSocket.send()} method now raises either
@ref{e52,,ssl.SSLWantReadError} or @ref{e53,,ssl.SSLWantWriteError}
on a non-blocking socket if the operation would block.  Previously,
it would return @code{0}.  (Contributed by Nikolaus Rath in bpo-20951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20951}.)

@item 
The @code{__name__} attribute of generators is now set from the function name,
instead of being set from the code name. Use @code{gen.gi_code.co_name} to
retrieve the code name. Generators also have a new @code{__qualname__}
attribute, the qualified name, which is now used for the representation
of a generator (@code{repr(gen)}).
(Contributed by Victor Stinner in bpo-21205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21205}.)

@item 
The deprecated "strict" mode and argument of @ref{862,,HTMLParser},
@code{HTMLParser.error()}, and the @code{HTMLParserError} exception have been
removed.  (Contributed by Ezio Melotti in bpo-15114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15114}.)
The `convert_charrefs' argument of @ref{862,,HTMLParser} is
now @code{True} by default.  (Contributed by Berker Peksag in bpo-21047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21047}.)

@item 
Although it is not formally part of the API, it is worth noting for porting
purposes (ie: fixing tests) that error messages that were previously of the
form "'sometype' does not support the buffer protocol" are now of the form "a
@ref{d1b,,bytes-like object} is required, not 'sometype'".
(Contributed by Ezio Melotti in bpo-16518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16518}.)

@item 
If the current directory is set to a directory that no longer exists then
@ref{eae,,FileNotFoundError} will no longer be raised and instead
@ref{eaf,,find_spec()} will return @code{None}
`without' caching @code{None} in @ref{5ce,,sys.path_importer_cache}, which is
different than the typical case (bpo-22834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22834}).

@item 
HTTP status code and messages from @ref{6e,,http.client} and @ref{71,,http.server}
were refactored into a common @ref{8ed,,HTTPStatus} enum.  The values in
@ref{6e,,http.client} and @ref{71,,http.server} remain available for backwards
compatibility.  (Contributed by Demian Brecht in bpo-21793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21793}.)

@item 
When an import loader defines @code{importlib.machinery.Loader.exec_module()}
it is now expected to also define
@code{create_module()} (raises a
@ref{1a3,,DeprecationWarning} now, will be an error in Python 3.6). If the loader
inherits from @ref{eb0,,importlib.abc.Loader} then there is nothing to do, else
simply define @code{create_module()} to return
@code{None}.  (Contributed by Brett Cannon in bpo-23014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23014}.)

@item 
The @ref{29f,,re.split()} function always ignored empty pattern matches, so the
@code{"x*"} pattern worked the same as @code{"x+"}, and the @code{"\b"} pattern never
worked.  Now @ref{29f,,re.split()} raises a warning if the pattern could match
an empty string.  For compatibility, use patterns that never match an empty
string (e.g. @code{"x+"} instead of @code{"x*"}).  Patterns that could only match
an empty string (such as @code{"\b"}) now raise an error.
(Contributed by Serhiy Storchaka in bpo-22818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22818}.)

@item 
The @ref{bf2,,http.cookies.Morsel} dict-like interface has been made self
consistent:  morsel comparison now takes the @ref{bef,,key}
and @ref{bf0,,value} into account,
@ref{eb1,,copy()} now results in a
@ref{bf2,,Morsel} instance rather than a @ref{253,,dict}, and
@ref{eb2,,update()} will now raise an exception if any of the
keys in the update dictionary are invalid.  In addition, the undocumented
`LegalChars' parameter of @ref{bf3,,set()} is deprecated and
is now ignored.  (Contributed by Demian Brecht in bpo-2211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2211}.)

@item 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} has removed @code{.pyo} files from Python and introduced the optional
@code{opt-} tag in @code{.pyc} file names. The
@ref{2f2,,importlib.util.cache_from_source()} has gained an `optimization'
parameter to help control the @code{opt-} tag. Because of this, the
`debug_override' parameter of the function is now deprecated. @code{.pyo} files
are also no longer supported as a file argument to the Python interpreter and
thus serve no purpose when distributed on their own (i.e. sourceless code
distribution). Due to the fact that the magic number for bytecode has changed
in Python 3.5, all old @code{.pyo} files from previous versions of Python are
invalid regardless of this PEP.

@item 
The @ref{cb,,socket} module now exports the @ref{eb3,,CAN_RAW_FD_FRAMES}
constant on linux 3.6 and greater.

@item 
The @ref{e54,,ssl.cert_time_to_seconds()} function now interprets the input time
as UTC and not as local time, per 
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}.  Additionally, the return
value is always an @ref{254,,int}. (Contributed by Akira Li in bpo-19940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19940}.)

@item 
The @code{pygettext.py} Tool now uses the standard +NNNN format for timezones in
the POT-Creation-Date header.

@item 
The @ref{c9,,smtplib} module now uses @ref{926,,sys.stderr} instead of the previous
module-level @code{stderr} variable for debug output.  If your (test)
program depends on patching the module-level variable to capture the debug
output, you will need to update it to capture sys.stderr instead.

@item 
The @ref{eb4,,str.startswith()} and @ref{eb5,,str.endswith()} methods no longer return
@code{True} when finding the empty string and the indexes are completely out of
range.  (Contributed by Serhiy Storchaka in bpo-24284@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24284}.)

@item 
The @ref{9e8,,inspect.getdoc()} function now returns documentation strings
inherited from base classes.  Documentation strings no longer need to be
duplicated if the inherited documentation is appropriate.  To suppress an
inherited string, an empty string must be specified (or the documentation
may be filled in).  This change affects the output of the @ref{b4,,pydoc}
module and the @ref{8c4,,help()} function.
(Contributed by Serhiy Storchaka in bpo-15582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15582}.)

@item 
Nested @ref{40a,,functools.partial()} calls are now flattened.  If you were
relying on the previous behavior, you can now either add an attribute to a
@ref{40a,,functools.partial()} object or you can create a subclass of
@ref{40a,,functools.partial()}.
(Contributed by Alexander Belopolsky in bpo-7830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7830}.)
@end itemize

@node Changements dans l'API C<7>,,Changements dans l'API Python<9>,Portage vers Python 3 5
@anchor{whatsnew/3 5 changes-in-the-c-api}@anchor{eb6}
@subsubsection Changements dans l'API C



@itemize *

@item 
The undocumented @code{format} member of the
(non-public) @code{PyMemoryViewObject} structure has been removed.
All extensions relying on the relevant parts in @code{memoryobject.h}
must be rebuilt.

@item 
The @code{PyMemAllocator} structure was renamed to
@ref{eb7,,PyMemAllocatorEx} and a new @code{calloc} field was added.

@item 
Removed non-documented macro @code{PyObject_REPR()} which leaked references.
Use format character @code{%R} in @ref{380,,PyUnicode_FromFormat()}-like functions
to format the @ref{7e7,,repr()} of the object.
(Contributed by Serhiy Storchaka in bpo-22453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22453}.)

@item 
Because the lack of the @ref{36a,,__module__} attribute breaks pickling and
introspection, a deprecation warning is now raised for builtin types without
the @ref{36a,,__module__} attribute.  This will be an @ref{343,,AttributeError} in
the future.
(Contributed by Serhiy Storchaka in bpo-20204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20204}.)

@item 
As part of the 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} implementation, the @code{tp_reserved} slot of
@ref{a93,,PyTypeObject} was replaced with a
@ref{eb8,,tp_as_async} slot.  Refer to @ref{eb9,,Objets coroutines} for
new types, structures and functions.
@end itemize

@node Notable changes in Python 3 5 4,,Portage vers Python 3 5,Nouveautés de Python 3 5
@anchor{whatsnew/3 5 notable-changes-in-python-3-5-4}@anchor{eba}
@subsection Notable changes in Python 3.5.4


@menu
* New make regen-all build target: New make regen-all build target<2>. 
* Removal of make touch build target: Removal of make touch build target<2>. 

@end menu

@node New make regen-all build target<2>,Removal of make touch build target<2>,,Notable changes in Python 3 5 4
@anchor{whatsnew/3 5 new-make-regen-all-build-target}@anchor{ebb}
@subsubsection New @code{make regen-all} build target


To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.

Instead, a new @code{make regen-all} command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see
Makefile.pre.in@footnote{https://github.com/python/cpython/tree/3.13/Makefile.pre.in} for details.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Ajouté dans la version 3.5.4.


@node Removal of make touch build target<2>,,New make regen-all build target<2>,Notable changes in Python 3 5 4
@anchor{whatsnew/3 5 removal-of-make-touch-build-target}@anchor{ebc}
@subsubsection Removal of @code{make touch} build target


The @code{make touch} build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.

It has been replaced by the new @code{make regen-all} target.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Modifié dans la version 3.5.4.


@node Nouveautés de Python 3 4,Nouveautés de Python 3 3,Nouveautés de Python 3 5,Nouveautés de Python
@anchor{whatsnew/3 4 doc}@anchor{ebd}@anchor{whatsnew/3 4 what-s-new-in-python-3-4}@anchor{ebe}
@section Nouveautés de Python 3.4


@*Auteur: 
R. David Murray <@email{rdmurray@@bitdance.com}> (Editor)


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document, but the maintainer reserves the
@c right to rewrite any additions. In particular, for obscure or esoteric
@c features, the maintainer may reduce any addition to a simple reference to
@c the new documentation rather than explaining the feature inline.
@c 
@c * While the maintainer will periodically go through Misc/NEWS
@c and add changes, it's best not to rely on this. We know from experience
@c that any changes that aren't in the What's New documentation around the
@c time of the original release will remain largely unknown to the community
@c for years, even if they're added later. We also know from experience that
@c other priorities can arise, and the maintainer will run out of time to do
@c updates -- in such cases, end users will be much better served by partial
@c notifications that at least give a hint about new features to
@c investigate.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS. The What's New should focus on changes that
@c are visible to Python *users* and that *require* a feature release (i.e.
@c most bug fixes should only be recorded in Misc/NEWS)
@c 
@c * PEPs should not be marked Final until they have an entry in What's New.
@c A placeholder entry that is just a section header and a link to the PEP
@c (e.g ":pep:`397` has been implemented") is acceptable. If a PEP has been
@c implemented and noted in What's New, don't forget to mark it as Final!
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to add just a very brief note about a change.  For
@c example: "The :ref:`~socket.transmogrify()` function was added to the
@c :mod:`socket` module."  The maintainer will research the change and
@c write the necessary text (if appropriate). The advantage of doing this
@c is that even if no more descriptive text is ever added, readers will at
@c least have a notification that the new feature exists and a link to the
@c relevant documentation.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c The :ref:`~socket.transmogrify()` function was added to the
@c :mod:`socket` module.  (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Mercurial log
@c when researching a change.
@c 
@c * Cross referencing tip: :ref:`mod.attr` will display as ``mod.attr``,
@c while :ref:`~mod.attr` will display as ``attr``.

This article explains the new features in Python 3.4, compared to 3.3.
Python 3.4 was released on March 16, 2014.  For full details, see the
changelog@footnote{https://docs.python.org/3.4/whatsnew/changelog.html}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 429
PEP 429@footnote{https://peps.python.org/pep-0429/} -- Python 3.4 Release Schedule


@menu
* Summary: Summary -- Release Highlights<3>. Release Highlights
* Nouvelles fonctionnalités: Nouvelles fonctionnalités<15>. 
* Nouveaux modules: Nouveaux modules<10>. 
* Modules améliorés: Modules améliorés<10>. 
* CPython Implementation Changes:: 
* Obsolescence: Obsolescence<11>. 
* Retraits: Retraits<9>. 
* Portage vers Python 3.4: Portage vers Python 3 4. 
* Changed in 3.4.3: Changed in 3 4 3. 

@end menu

@node Summary -- Release Highlights<3>,Nouvelles fonctionnalités<15>,,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 summary-release-highlights}@anchor{ebf}
@subsection Summary -- Release Highlights


@c This section singles out the most important changes in Python 3.4.
@c Brevity is key.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
No new syntax features were added in Python 3.4.
@end itemize

Other new features:


@itemize *

@item 
@ref{ec0,,pip should always be available} (
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}).

@item 
@ref{ec1,,Newly created file descriptors are non-inheritable}
(
@geindex Python Enhancement Proposals; PEP 446
PEP 446@footnote{https://peps.python.org/pep-0446/}).

@item 
command line option for @ref{ec2,,isolated mode}
(bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499}).

@item 
@ref{ec3,,improvements in the handling of codecs}
that are not text encodings (multiple issues).

@item 
@ref{ec4,,A ModuleSpec Type} for the Import System
(
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}).  (Affects importer authors.)

@item 
The @ref{8c,,marshal} format has been made @ref{ec5,,more compact and efficient} (bpo-16475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16475}).
@end itemize

Nouveaux modules de la bibliothèque :


@itemize *

@item 
@ref{a,,asyncio}: @ref{ec6,,New provisional API for asynchronous IO} (
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/}).

@item 
@ref{54,,ensurepip}: @ref{ec7,,Bootstrapping the pip installer}
(
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}).

@item 
@ref{55,,enum}: @ref{ec8,,Support for enumeration types}
(
@geindex Python Enhancement Proposals; PEP 435
PEP 435@footnote{https://peps.python.org/pep-0435/}).

@item 
@ref{a3,,pathlib}: @ref{ec9,,Object-oriented filesystem paths}
(
@geindex Python Enhancement Proposals; PEP 428
PEP 428@footnote{https://peps.python.org/pep-0428/}).

@item 
@ref{c1,,selectors}: @ref{eca,,High-level and efficient I/O multiplexing}, built upon the @ref{c0,,select} module primitives (part
of 
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/}).

@item 
@ref{d1,,statistics}: A basic @ref{ecb,,numerically stable statistics library} (
@geindex Python Enhancement Proposals; PEP 450
PEP 450@footnote{https://peps.python.org/pep-0450/}).

@item 
@ref{fe,,tracemalloc}: @ref{ecc,,Trace Python memory allocations} (
@geindex Python Enhancement Proposals; PEP 454
PEP 454@footnote{https://peps.python.org/pep-0454/}).
@end itemize

Significantly improved library modules:


@itemize *

@item 
@ref{ecd,,Single-dispatch generic functions} in
@ref{5e,,functools} (
@geindex Python Enhancement Proposals; PEP 443
PEP 443@footnote{https://peps.python.org/pep-0443/}).

@item 
New @ref{a5,,pickle} @ref{ece,,protocol 4} (
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/}).

@item 
@ref{93,,multiprocessing} now has @ref{ecf,,an option to avoid using os.fork on Unix} (bpo-8713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8713}).

@item 
@ref{3b,,email} has a new submodule, @ref{3d,,contentmanager}, and
a new @ref{279,,Message} subclass
(@code{EmailMessage}) that @ref{ed0,,simplify MIME handling} (bpo-18891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18891}).

@item 
The @ref{7d,,inspect} and @ref{b4,,pydoc} modules are now capable of
correct introspection of a much wider variety of callable objects,
which improves the output of the Python @ref{8c4,,help()} system.

@item 
The @ref{7f,,ipaddress} module API has been declared stable
@end itemize

Security improvements:


@itemize *

@item 
@ref{ed1,,Secure and interchangeable hash algorithm}
(
@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/}).

@item 
@ref{ec1,,Make newly created file descriptors non-inheritable}
(
@geindex Python Enhancement Proposals; PEP 446
PEP 446@footnote{https://peps.python.org/pep-0446/}) to avoid leaking file descriptors to child processes.

@item 
New command line option for @ref{ec2,,isolated mode},
(bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499}).

@item 
@ref{93,,multiprocessing} now has @ref{ecf,,an option to avoid using os.fork on Unix}.  `spawn' and `forkserver' are
more secure because they avoid sharing data with child processes.

@item 
@ref{93,,multiprocessing} child processes on Windows no longer inherit
all of the parent's inheritable handles, only the necessary ones.

@item 
A new @ref{4f8,,hashlib.pbkdf2_hmac()} function provides
the PKCS#5 password-based key derivation function 2@footnote{https://en.wikipedia.org/wiki/PBKDF2}.

@item 
@ref{ed2,,TLSv1.1 and TLSv1.2 support} for @ref{cf,,ssl}.

@item 
@ref{ed3,,Retrieving certificates from the Windows system cert store support} for @ref{cf,,ssl}.

@item 
@ref{ed4,,Server-side SNI (Server Name Indication) support} for @ref{cf,,ssl}.

@item 
The @ref{291,,ssl.SSLContext} class has a @ref{ed5,,lot of improvements}.

@item 
All modules in the standard library that support SSL now support server
certificate verification, including hostname matching
(@code{ssl.match_hostname()}) and CRLs (Certificate Revocation lists, see
@ref{ed6,,ssl.SSLContext.load_verify_locations()}).
@end itemize

CPython implementation improvements:


@itemize *

@item 
@ref{ed7,,Safe object finalization} (
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}).

@item 
Leveraging 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}, in most cases @ref{ed7,,module globals are no longer set to None during finalization} (bpo-18214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18214}).

@item 
@ref{ed8,,Configurable memory allocators} (
@geindex Python Enhancement Proposals; PEP 445
PEP 445@footnote{https://peps.python.org/pep-0445/}).

@item 
@ref{ed9,,Argument Clinic} (
@geindex Python Enhancement Proposals; PEP 436
PEP 436@footnote{https://peps.python.org/pep-0436/}).
@end itemize

Please read on for a comprehensive list of user-facing changes, including many
other smaller improvements, CPython optimizations, deprecations, and potential
porting issues.

@node Nouvelles fonctionnalités<15>,Nouveaux modules<10>,Summary -- Release Highlights<3>,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 new-features}@anchor{eda}
@subsection Nouvelles fonctionnalités


@menu
* PEP 453; Explicit Bootstrapping of PIP in Python Installations: PEP 453 Explicit Bootstrapping of PIP in Python Installations. 
* PEP 446; Newly Created File Descriptors Are Non-Inheritable: PEP 446 Newly Created File Descriptors Are Non-Inheritable. 
* Improvements to Codec Handling:: 
* PEP 451; A ModuleSpec Type for the Import System: PEP 451 A ModuleSpec Type for the Import System. 
* Autres changements au langage: Autres changements au langage<10>. 

@end menu

@node PEP 453 Explicit Bootstrapping of PIP in Python Installations,PEP 446 Newly Created File Descriptors Are Non-Inheritable,,Nouvelles fonctionnalités<15>
@anchor{whatsnew/3 4 pep-453-explicit-bootstrapping-of-pip-in-python-installations}@anchor{edb}@anchor{whatsnew/3 4 whatsnew-pep-453}@anchor{ec0}
@subsubsection PEP 453: Explicit Bootstrapping of PIP in Python Installations


@menu
* Bootstrapping pip By Default:: 
* Documentation Changes:: 

@end menu

@node Bootstrapping pip By Default,Documentation Changes,,PEP 453 Explicit Bootstrapping of PIP in Python Installations
@anchor{whatsnew/3 4 bootstrapping-pip-by-default}@anchor{edc}
@subsubsection Bootstrapping pip By Default


The new @ref{54,,ensurepip} module (defined in 
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}) provides a standard
cross-platform mechanism to bootstrap the pip installer into Python
installations and virtual environments. The version of @code{pip} included
with Python 3.4.0 is @code{pip} 1.5.4, and future 3.4.x maintenance releases
will update the bundled version to the latest version of @code{pip} that is
available at the time of creating the release candidate.

By default, the commands @code{pipX} and @code{pipX.Y} will be installed on all
platforms (where X.Y stands for the version of the Python installation),
along with the @code{pip} Python package and its dependencies. On Windows and
in virtual environments on all platforms, the unversioned @code{pip} command
will also be installed. On other platforms, the system wide unversioned
@code{pip} command typically refers to the separately installed Python 2
version.

The @code{pyvenv} command line utility and the @ref{110,,venv}
module make use of the @ref{54,,ensurepip} module to make @code{pip} readily
available in virtual environments. When using the command line utility,
@code{pip} is installed by default, while when using the @ref{110,,venv} module
@ref{edd,,API} installation of @code{pip} must be requested explicitly.

For CPython @ref{ede,,source builds on POSIX systems},
the @code{make install} and @code{make altinstall} commands bootstrap @code{pip} by
default.  This behaviour can be controlled through configure options, and
overridden through Makefile options.

On Windows and Mac OS X, the CPython installers now default to installing
@code{pip} along with CPython itself (users may opt out of installing it
during the installation process). Window users will need to opt in to the
automatic @code{PATH} modifications to have @code{pip} available from the command
line by default, otherwise it can still be accessed through the Python
launcher for Windows as @code{py -m pip}.

As 
@geindex Python Enhancement Proposals; PEP 0453#recommendations-for-downstream-distributors
discussed in the PEP@footnote{https://peps.python.org/pep-0453/#recommendations-for-downstream-distributors}
platform packagers may choose not to install
these commands by default, as long as, when invoked, they provide clear and
simple directions on how to install them on that platform (usually using
the system package manager).

@cartouche
@quotation Note 
To avoid conflicts between parallel Python 2 and Python 3 installations,
only the versioned @code{pip3} and @code{pip3.4} commands are bootstrapped by
default when @code{ensurepip} is invoked directly - the @code{--default-pip}
option is needed to also request the unversioned @code{pip} command.
@code{pyvenv} and the Windows installer ensure that the unqualified @code{pip}
command is made available in those environments, and @code{pip} can always be
invoked via the @code{-m} switch rather than directly to avoid ambiguity on
systems with multiple Python installations.
@end quotation
@end cartouche

@node Documentation Changes,,Bootstrapping pip By Default,PEP 453 Explicit Bootstrapping of PIP in Python Installations
@anchor{whatsnew/3 4 documentation-changes}@anchor{edf}
@subsubsection Documentation Changes


As part of this change, the @ref{ee0,,Installation de modules Python} and
distributing-index sections of the documentation have been
completely redesigned as short getting started and FAQ documents. Most
packaging documentation has now been moved out to the Python Packaging
Authority maintained Python Packaging User Guide@footnote{https://packaging.python.org} and the documentation of the individual
projects.

However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as @ref{ee1,,Building C and C++ Extensions with setuptools}
and @ref{ee2,,Building C and C++ Extensions with setuptools}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 453

@item PEP 453@footnote{https://peps.python.org/pep-0453/} -- Explicit bootstrapping of pip in Python installations

PEP written by Donald Stufft and Nick Coghlan, implemented by
Donald Stufft, Nick Coghlan, Martin von Löwis and Ned Deily.
@end table


@node PEP 446 Newly Created File Descriptors Are Non-Inheritable,Improvements to Codec Handling,PEP 453 Explicit Bootstrapping of PIP in Python Installations,Nouvelles fonctionnalités<15>
@anchor{whatsnew/3 4 pep-446-newly-created-file-descriptors-are-non-inheritable}@anchor{ee3}@anchor{whatsnew/3 4 whatsnew-pep-446}@anchor{ec1}
@subsubsection PEP 446: Newly Created File Descriptors Are Non-Inheritable


@geindex Python Enhancement Proposals; PEP 446
PEP 446@footnote{https://peps.python.org/pep-0446/} makes newly created file descriptors @ref{ee4,,non-inheritable}.  In general, this is the behavior an application will
want: when launching a new process, having currently open files also
open in the new process can lead to all sorts of hard to find bugs,
and potentially to security issues.

However, there are occasions when inheritance is desired.  To support
these cases, the following new functions and methods are available:


@itemize *

@item 
@ref{ee5,,os.get_inheritable()}, @ref{ee6,,os.set_inheritable()}

@item 
@ref{ee7,,os.get_handle_inheritable()}, @ref{ee8,,os.set_handle_inheritable()}

@item 
@ref{ee9,,socket.socket.get_inheritable()}, @ref{eea,,socket.socket.set_inheritable()}
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 446

@item PEP 446@footnote{https://peps.python.org/pep-0446/} -- Make newly created file descriptors non-inheritable

PEP written and implemented by Victor Stinner.
@end table


@node Improvements to Codec Handling,PEP 451 A ModuleSpec Type for the Import System,PEP 446 Newly Created File Descriptors Are Non-Inheritable,Nouvelles fonctionnalités<15>
@anchor{whatsnew/3 4 codec-handling-improvements}@anchor{ec3}@anchor{whatsnew/3 4 improvements-to-codec-handling}@anchor{eeb}
@subsubsection Improvements to Codec Handling


Since it was first introduced, the @ref{1b,,codecs} module has always been
intended to operate as a type-neutral dynamic encoding and decoding
system. However, its close coupling with the Python text model, especially
the type restricted convenience methods on the builtin @ref{435,,str},
@ref{1bd,,bytes} and @ref{528,,bytearray} types, has historically obscured that
fact.

As a key step in clarifying the situation, the @ref{eec,,codecs.encode()} and
@ref{eed,,codecs.decode()} convenience functions are now properly documented in
Python 2.7, 3.3 and 3.4. These functions have existed in the @ref{1b,,codecs}
module (and have been covered by the regression test suite) since Python 2.4,
but were previously only discoverable through runtime introspection.

Unlike the convenience methods on @ref{435,,str}, @ref{1bd,,bytes} and
@ref{528,,bytearray}, the @ref{1b,,codecs} convenience functions support arbitrary
codecs in both Python 2 and Python 3, rather than being limited to Unicode text
encodings (in Python 3) or @code{basestring} <-> @code{basestring} conversions (in
Python 2).

In Python 3.4, the interpreter is able to identify the known non-text
encodings provided in the standard library and direct users towards these
general purpose convenience functions when appropriate:

@example
>>> b"abcdef".decode("hex")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LookupError: 'hex' is not a text encoding; use codecs.decode() to handle arbitrary codecs

>>> "hello".encode("rot13")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LookupError: 'rot13' is not a text encoding; use codecs.encode() to handle arbitrary codecs

>>> open("foo.txt", encoding="hex")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
LookupError: 'hex' is not a text encoding; use codecs.open() to handle arbitrary codecs
@end example

In a related change, whenever it is feasible without breaking backwards
compatibility, exceptions raised during encoding and decoding operations
are wrapped in a chained exception of the same type that mentions the
name of the codec responsible for producing the error:

@example
>>> import codecs

>>> codecs.decode(b"abcdefgh", "hex")
Traceback (most recent call last):
  File "/usr/lib/python3.4/encodings/hex_codec.py", line 20, in hex_decode
    return (binascii.a2b_hex(input), len(input))
binascii.Error: Non-hexadecimal digit found

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
binascii.Error: decoding with 'hex' codec failed (Error: Non-hexadecimal digit found)

>>> codecs.encode("hello", "bz2")
Traceback (most recent call last):
  File "/usr/lib/python3.4/encodings/bz2_codec.py", line 17, in bz2_encode
    return (bz2.compress(input), len(input))
  File "/usr/lib/python3.4/bz2.py", line 498, in compress
    return comp.compress(data) + comp.flush()
TypeError: 'str' does not support the buffer interface

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: encoding with 'bz2' codec failed (TypeError: 'str' does not support the buffer interface)
@end example

Finally, as the examples above show, these improvements have permitted
the restoration of the convenience aliases for the non-Unicode codecs that
were themselves restored in Python 3.2. This means that encoding binary data
to and from its hexadecimal representation (for example) can now be written
as:

@example
>>> from codecs import encode, decode
>>> encode(b"hello", "hex")
b'68656c6c6f'
>>> decode(b"68656c6c6f", "hex")
b'hello'
@end example

The binary and text transforms provided in the standard library are detailed
in @ref{eee,,Binary Transforms} and @ref{eef,,Text Transforms}.

(Contributed by Nick Coghlan in bpo-7475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7475}, bpo-17827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17827},
bpo-17828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17828} and bpo-19619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19619}.)

@node PEP 451 A ModuleSpec Type for the Import System,Autres changements au langage<10>,Improvements to Codec Handling,Nouvelles fonctionnalités<15>
@anchor{whatsnew/3 4 pep-451-a-modulespec-type-for-the-import-system}@anchor{ef0}@anchor{whatsnew/3 4 whatsnew-pep-451}@anchor{ec4}
@subsubsection PEP 451: A ModuleSpec Type for the Import System


@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} provides an encapsulation of the information about a module that the
import machinery will use to load it (that is, a module specification).  This
helps simplify both the import implementation and several import-related APIs.
The change is also a stepping stone for several future import-related improvements@footnote{https://mail.python.org/pipermail/python-dev/2013-November/130111.html}.

The public-facing changes from the PEP are entirely backward-compatible.
Furthermore, they should be transparent to everyone but importer authors.  Key
finder and loader methods have been deprecated, but they will continue working.
New importers should use the new methods described in the PEP.  Existing
importers should be updated to implement the new methods.  See the
@ref{ef1,,Obsolescence} section for a list of methods that should be replaced and
their replacements.

@node Autres changements au langage<10>,,PEP 451 A ModuleSpec Type for the Import System,Nouvelles fonctionnalités<15>
@anchor{whatsnew/3 4 other-language-changes}@anchor{ef2}
@subsubsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
Unicode database updated to UCD version 6.3.

@item 
@ref{ef3,,min()} and @ref{ef4,,max()} now accept a `default' keyword-only argument that
can be used to specify the value they return if the iterable they are
evaluating has no elements.  (Contributed by Julian Berman in
bpo-18111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18111}.)

@item 
Module objects are now @ref{ef5,,weakly referenceable}.

@item 
Module @code{__file__} attributes (and related values) should now always
contain absolute paths by default, with the sole exception of
@code{__main__.__file__} when a script has been executed directly using
a relative path.  (Contributed by Brett Cannon in bpo-18416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18416}.)

@item 
All the UTF-* codecs (except UTF-7) now reject surrogates during both
encoding and decoding unless the @code{surrogatepass} error handler is used,
with the exception of the UTF-16 decoder (which accepts valid surrogate pairs)
and the UTF-16 encoder (which produces them while encoding non-BMP characters).
(Contributed by Victor Stinner, Kang-Hao (Kenny) Lu and Serhiy Storchaka in
bpo-12892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12892}.)

@item 
New German EBCDIC @ref{da6,,codec} @code{cp273}.  (Contributed
by Michael Bierenfeld and Andrew Kuchling in bpo-1097797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1097797}.)

@item 
New Ukrainian @ref{da6,,codec} @code{cp1125}.  (Contributed by
Serhiy Storchaka in bpo-19668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19668}.)

@item 
@ref{1bd,,bytes}.join() and @ref{528,,bytearray}.join() now accept arbitrary
buffer objects as arguments.  (Contributed by Antoine Pitrou in
bpo-15958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15958}.)

@item 
The @ref{254,,int} constructor now accepts any object that has an @code{__index__}
method for its `base' argument.  (Contributed by Mark Dickinson in
bpo-16772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16772}.)

@item 
Frame objects now have a @ref{27d,,clear()} method that clears all
references to local variables from the frame.  (Contributed by Antoine Pitrou
in bpo-17934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17934}.)

@item 
@ref{452,,memoryview} is now registered as a @ref{1e,,Sequence},
and supports the @ref{850,,reversed()} builtin.  (Contributed by Nick Coghlan
and Claudiu Popa in bpo-18690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18690} and bpo-19078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19078}.)

@item 
Signatures reported by @ref{8c4,,help()} have been modified and improved in
several cases as a result of the introduction of Argument Clinic and other
changes to the @ref{7d,,inspect} and @ref{b4,,pydoc} modules.

@item 
@ref{ef6,,__length_hint__()} is now part of the formal language
specification (see 
@geindex Python Enhancement Proposals; PEP 424
PEP 424@footnote{https://peps.python.org/pep-0424/}).  (Contributed by Armin Ronacher in
bpo-16148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16148}.)
@end itemize

@node Nouveaux modules<10>,Modules améliorés<10>,Nouvelles fonctionnalités<15>,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 new-modules}@anchor{ef7}
@subsection Nouveaux modules


@menu
* asyncio: asyncio<11>. 
* ensurepip: ensurepip<2>. 
* enum: enum<9>. 
* pathlib: pathlib<11>. 
* selectors: selectors<2>. 
* statistics: statistics<6>. 
* tracemalloc: tracemalloc<4>. 

@end menu

@node asyncio<11>,ensurepip<2>,,Nouveaux modules<10>
@anchor{whatsnew/3 4 asyncio}@anchor{ef8}@anchor{whatsnew/3 4 whatsnew-asyncio}@anchor{ec6}
@subsubsection asyncio


The new @ref{a,,asyncio} module (defined in 
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/}) provides a standard
pluggable event loop model for Python, providing solid asynchronous IO
support in the standard library, and making it easier for other event loop
implementations to interoperate with the standard library and each other.

For Python 3.4, this module is considered a @ref{af1,,provisional API}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3156

@item PEP 3156@footnote{https://peps.python.org/pep-3156/} -- Asynchronous IO Support Rebooted: the "asyncio" Module

PEP written and implementation led by Guido van Rossum.
@end table


@node ensurepip<2>,enum<9>,asyncio<11>,Nouveaux modules<10>
@anchor{whatsnew/3 4 ensurepip}@anchor{ef9}@anchor{whatsnew/3 4 whatsnew-ensurepip}@anchor{ec7}
@subsubsection ensurepip


The new @ref{54,,ensurepip} module is the primary infrastructure for the
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/} implementation.  In the normal course of events end users will not
need to interact with this module, but it can be used to manually bootstrap
@code{pip} if the automated bootstrapping into an installation or virtual
environment was declined.

@ref{54,,ensurepip} includes a bundled copy of @code{pip}, up-to-date as of the first
release candidate of the release of CPython with which it ships (this applies
to both maintenance releases and feature releases).  @code{ensurepip} does not
access the internet.  If the installation has internet access, after
@code{ensurepip} is run the bundled @code{pip} can be used to upgrade @code{pip} to a
more recent release than the bundled one.  (Note that such an upgraded version
of @code{pip} is considered to be a separately installed package and will not be
removed if Python is uninstalled.)

The module is named `ensure'pip because if called when @code{pip} is already
installed, it does nothing.  It also has an @code{--upgrade} option that will
cause it to install the bundled copy of @code{pip} if the existing installed
version of @code{pip} is older than the bundled copy.

@node enum<9>,pathlib<11>,ensurepip<2>,Nouveaux modules<10>
@anchor{whatsnew/3 4 enum}@anchor{efa}@anchor{whatsnew/3 4 whatsnew-enum}@anchor{ec8}
@subsubsection enum


The new @ref{55,,enum} module (defined in 
@geindex Python Enhancement Proposals; PEP 435
PEP 435@footnote{https://peps.python.org/pep-0435/}) provides a standard
implementation of enumeration types, allowing other modules (such as
@ref{cb,,socket}) to provide more informative error messages and better
debugging support by replacing opaque integer constants with backwards
compatible enumeration values.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 435

@item PEP 435@footnote{https://peps.python.org/pep-0435/} -- Adding an Enum type to the Python standard library

PEP written by Barry Warsaw, Eli Bendersky and Ethan Furman,
implemented by Ethan Furman.
@end table


@node pathlib<11>,selectors<2>,enum<9>,Nouveaux modules<10>
@anchor{whatsnew/3 4 pathlib}@anchor{efb}@anchor{whatsnew/3 4 whatsnew-pathlib}@anchor{ec9}
@subsubsection pathlib


The new @ref{a3,,pathlib} module offers classes representing filesystem paths
with semantics appropriate for different operating systems.  Path classes are
divided between `pure paths', which provide purely computational operations
without I/O, and `concrete paths', which inherit from pure paths but also
provide I/O operations.

For Python 3.4, this module is considered a @ref{af1,,provisional API}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 428

@item PEP 428@footnote{https://peps.python.org/pep-0428/} -- The pathlib module -- object-oriented filesystem paths

PEP written and implemented by Antoine Pitrou.
@end table


@node selectors<2>,statistics<6>,pathlib<11>,Nouveaux modules<10>
@anchor{whatsnew/3 4 selectors}@anchor{efc}@anchor{whatsnew/3 4 whatsnew-selectors}@anchor{eca}
@subsubsection selectors


The new @ref{c1,,selectors} module (created as part of implementing 
@geindex Python Enhancement Proposals; PEP 3156
PEP 3156@footnote{https://peps.python.org/pep-3156/})
allows high-level and efficient I/O multiplexing, built upon the
@ref{c0,,select} module primitives.

@node statistics<6>,tracemalloc<4>,selectors<2>,Nouveaux modules<10>
@anchor{whatsnew/3 4 statistics}@anchor{efd}@anchor{whatsnew/3 4 whatsnew-statistics}@anchor{ecb}
@subsubsection @code{statistics}


The new @ref{d1,,statistics} module (defined in 
@geindex Python Enhancement Proposals; PEP 450
PEP 450@footnote{https://peps.python.org/pep-0450/}) offers some core
statistics functionality directly in the standard library. This module
supports calculation of the mean, median, mode, variance and standard
deviation of a data series.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 450

@item PEP 450@footnote{https://peps.python.org/pep-0450/} -- Adding A Statistics Module To The Standard Library

PEP written and implemented by Steven D'Aprano
@end table


@node tracemalloc<4>,,statistics<6>,Nouveaux modules<10>
@anchor{whatsnew/3 4 tracemalloc}@anchor{efe}@anchor{whatsnew/3 4 whatsnew-tracemalloc}@anchor{ecc}
@subsubsection tracemalloc


The new @ref{fe,,tracemalloc} module (defined in 
@geindex Python Enhancement Proposals; PEP 454
PEP 454@footnote{https://peps.python.org/pep-0454/}) is a debug tool to
trace memory blocks allocated by Python. It provides the following information:


@itemize *

@item 
Trace where an object was allocated

@item 
Statistics on allocated memory blocks per filename and per line number:
total size, number and average size of allocated memory blocks

@item 
Compute the differences between two snapshots to detect memory leaks
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 454

@item PEP 454@footnote{https://peps.python.org/pep-0454/} -- Add a new tracemalloc module to trace Python memory allocations

PEP written and implemented by Victor Stinner
@end table


@node Modules améliorés<10>,CPython Implementation Changes,Nouveaux modules<10>,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 improved-modules}@anchor{eff}
@subsection Modules améliorés


@menu
* abc:: 
* aifc: aifc<2>. 
* argparse: argparse<5>. 
* audioop:: 
* base64: base64<3>. 
* collections: collections<6>. 
* colorsys:: 
* contextlib: contextlib<6>. 
* dbm: dbm<6>. 
* dis: dis<4>. 
* doctest: doctest<4>. 
* email: email<4>. 
* filecmp:: 
* functools: functools<5>. 
* gc: gc<5>. 
* glob: glob<4>. 
* hashlib: hashlib<6>. 
* hmac: hmac<3>. 
* html:: 
* http: http<3>. 
* idlelib and IDLE: idlelib and IDLE<4>. 
* importlib: importlib<9>. 
* inspect: inspect<8>. 
* ipaddress: ipaddress<5>. 
* logging: logging<6>. 
* marshal: marshal<2>. 
* mmap: mmap<3>. 
* multiprocessing: multiprocessing<7>. 
* operator: operator<3>. 
* os: os<11>. 
* pdb: pdb<6>. 
* pickle: pickle<4>. 
* plistlib: plistlib<2>. 
* poplib: poplib<3>. 
* pprint: pprint<4>. 
* pty:: 
* pydoc: pydoc<4>. 
* re: re<8>. 
* resource:: 
* select:: 
* shelve: shelve<2>. 
* shutils: shutils<6>. 
* smtpd: smtpd<3>. 
* smtplib: smtplib<3>. 
* socket: socket<9>. 
* sqlite3: sqlite3<9>. 
* ssl: ssl<10>. 
* stat:: 
* struct: struct<2>. 
* subprocess: subprocess<5>. 
* sunau: sunau<2>. 
* sys: sys<12>. 
* tarfile: tarfile<7>. 
* textwrap:: 
* threading: threading<7>. 
* traceback: traceback<6>. 
* types: types<6>. 
* urllib: urllib<3>. 
* unittest: unittest<9>. 
* venv: venv<7>. 
* wave: wave<2>. 
* weakref: weakref<2>. 
* xml.etree: xml etree<2>. 
* zipfile: zipfile<5>. 

@end menu

@node abc,aifc<2>,,Modules améliorés<10>
@anchor{whatsnew/3 4 abc}@anchor{f00}
@subsubsection abc


New function @ref{f01,,abc.get_cache_token()} can be used to know when to invalidate
caches that are affected by changes in the object graph.  (Contributed
by Łukasz Langa in bpo-16832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16832}.)

New class @ref{f02,,ABC} has @ref{f03,,ABCMeta} as its meta class.
Using @code{ABC} as a base class has essentially the same effect as specifying
@code{metaclass=abc.ABCMeta}, but is simpler to type and easier to read.
(Contributed by Bruno Dupuis in bpo-16049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16049}.)

@node aifc<2>,argparse<5>,abc,Modules améliorés<10>
@anchor{whatsnew/3 4 aifc}@anchor{f04}
@subsubsection aifc


The @code{getparams()} method now returns a namedtuple rather than a
plain tuple.  (Contributed by Claudiu Popa in bpo-17818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17818}.)

@code{aifc.open()} now supports the context management protocol: when used in a
@ref{5bc,,with} block, the @code{close()} method of the returned
object will be called automatically at the end of the block.  (Contributed by
Serhiy Storchacha in bpo-16486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16486}.)

The @code{writeframesraw()} and @code{writeframes()}
methods now accept any @ref{d1b,,bytes-like object}.  (Contributed by Serhiy
Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node argparse<5>,audioop,aifc<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 argparse}@anchor{f05}
@subsubsection argparse


The @ref{f06,,FileType} class now accepts `encoding' and
`errors' arguments, which are passed through to @ref{505,,open()}.  (Contributed
by Lucas Maystre in bpo-11175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11175}.)

@node audioop,base64<3>,argparse<5>,Modules améliorés<10>
@anchor{whatsnew/3 4 audioop}@anchor{f07}
@subsubsection audioop


@code{audioop} now supports 24-bit samples.  (Contributed by Serhiy Storchaka
in bpo-12866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12866}.)

New @code{byteswap()} function converts big-endian samples to
little-endian and vice versa.  (Contributed by Serhiy Storchaka in
bpo-19641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19641}.)

All @code{audioop} functions now accept any @ref{d1b,,bytes-like object}.  Strings
are not accepted: they didn't work before, now they raise an error right away.
(Contributed by Serhiy Storchaka in bpo-16685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16685}.)

@node base64<3>,collections<6>,audioop,Modules améliorés<10>
@anchor{whatsnew/3 4 base64}@anchor{f08}
@subsubsection base64


The encoding and decoding functions in @ref{e,,base64} now accept any
@ref{d1b,,bytes-like object} in cases where it previously required a
@ref{1bd,,bytes} or @ref{528,,bytearray} instance.  (Contributed by Nick Coghlan in
bpo-17839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17839}.)

New functions @ref{f09,,a85encode()}, @ref{f0a,,a85decode()},
@ref{f0b,,b85encode()}, and @ref{f0c,,b85decode()} provide the ability to
encode and decode binary data from and to @code{Ascii85} and the git/mercurial
@code{Base85} formats, respectively.  The @code{a85} functions have options that can
be used to make them compatible with the variants of the @code{Ascii85} encoding,
including the Adobe variant.  (Contributed by Martin Morrison, the Mercurial
project, Serhiy Storchaka, and Antoine Pitrou in bpo-17618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17618}.)

@node collections<6>,colorsys,base64<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 collections}@anchor{f0d}
@subsubsection collections


The @ref{f0e,,ChainMap.new_child()} method now accepts an `m' argument specifying
the child map to add to the chain.  This allows an existing mapping and/or a
custom mapping type to be used for the child.  (Contributed by Vinay Sajip in
bpo-16613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16613}.)

@node colorsys,contextlib<6>,collections<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 colorsys}@anchor{f0f}
@subsubsection colorsys


The number of digits in the coefficients for the RGB --- YIQ conversions have
been expanded so that they match the FCC NTSC versions.  The change in
results should be less than 1% and may better match results found elsewhere.
(Contributed by Brian Landers and Serhiy Storchaka in bpo-14323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14323}.)

@node contextlib<6>,dbm<6>,colorsys,Modules améliorés<10>
@anchor{whatsnew/3 4 contextlib}@anchor{f10}
@subsubsection contextlib


The new @ref{f11,,contextlib.suppress} context manager helps to clarify the
intent of code that deliberately suppresses exceptions from a single
statement.  (Contributed by Raymond Hettinger in bpo-15806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15806} and
Zero Piraeus in bpo-19266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19266}.)

The new @ref{dd5,,contextlib.redirect_stdout()} context manager makes it easier
for utility scripts to handle inflexible APIs that write their output to
@ref{ac4,,sys.stdout} and don't provide any options to redirect it.  Using the
context manager, the @ref{ac4,,sys.stdout} output can be redirected to any
other stream or, in conjunction with @ref{f12,,io.StringIO}, to a string.
The latter can be especially useful, for example, to capture output
from a function that was written to implement a command line interface.
It is recommended only for utility scripts because it affects the
global state of @ref{ac4,,sys.stdout}.  (Contributed by Raymond Hettinger
in bpo-15805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15805}.)

The @ref{23,,contextlib} documentation has also been updated to include a
@ref{f13,,discussion} of the
differences between single use, reusable and reentrant context managers.

@node dbm<6>,dis<4>,contextlib<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 dbm}@anchor{f14}
@subsubsection dbm


@ref{f15,,dbm.open()} objects now support the context management protocol.  When
used in a @ref{5bc,,with} statement, the @code{close} method of the database
object will be called automatically at the end of the block.  (Contributed by
Claudiu Popa and Nick Coghlan in bpo-19282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19282}.)

@node dis<4>,doctest<4>,dbm<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 dis}@anchor{f16}
@subsubsection dis


Functions @ref{f17,,show_code()}, @ref{b22,,dis()}, @code{distb()}, and
@ref{f18,,disassemble()} now accept a keyword-only `file' argument that
controls where they write their output.

The @ref{38,,dis} module is now built around an @ref{1d7,,Instruction} class
that provides object oriented access to the details of each individual bytecode
operation.

A new method, @ref{1d6,,get_instructions()}, provides an iterator that emits
the Instruction stream for a given piece of Python code.  Thus it is now
possible to write a program that inspects and manipulates a bytecode
object in ways different from those provided by the @ref{38,,dis} module
itself.  For example:

@example
>>> import dis
>>> for instr in dis.get_instructions(lambda x: x + 1):
...     print(instr.opname)
LOAD_FAST
LOAD_CONST
BINARY_ADD
RETURN_VALUE
@end example

The various display tools in the @ref{38,,dis} module have been rewritten to use
these new components.

In addition, a new application-friendly class @ref{f19,,Bytecode} provides
an object-oriented API for inspecting bytecode in both in human-readable form
and for iterating over instructions.  The @ref{f19,,Bytecode} constructor
takes the same arguments that @code{get_instruction()} does (plus an
optional `current_offset'), and the resulting object can be iterated to produce
@ref{1d7,,Instruction} objects.  But it also has a @ref{f1a,,dis}
method, equivalent to calling @ref{b22,,dis} on the constructor argument, but
returned as a multi-line string:

@example
>>> bytecode = dis.Bytecode(lambda x: x + 1, current_offset=3)
>>> for instr in bytecode:
...     print('@{@} (@{@})'.format(instr.opname, instr.opcode))
LOAD_FAST (124)
LOAD_CONST (100)
BINARY_ADD (23)
RETURN_VALUE (83)
>>> bytecode.dis().splitlines()       
['  1           0 LOAD_FAST                0 (x)',
 '      -->     3 LOAD_CONST               1 (1)',
 '              6 BINARY_ADD',
 '              7 RETURN_VALUE']
@end example

@ref{f19,,Bytecode} also has a class method,
@ref{f1b,,from_traceback()}, that provides the ability to manipulate a
traceback (that is, @code{print(Bytecode.from_traceback(tb).dis())} is equivalent
to @code{distb(tb)}).

(Contributed by Nick Coghlan, Ryan Kelly and Thomas Kluyver in bpo-11816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11816}
and Claudiu Popa in bpo-17916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17916}.)

New function @ref{f1c,,stack_effect()} computes the effect on the Python stack
of a given opcode and argument, information that is not otherwise available.
(Contributed by Larry Hastings in bpo-19722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19722}.)

@node doctest<4>,email<4>,dis<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 doctest}@anchor{f1d}
@subsubsection doctest


A new @ref{f1e,,option flag}, @ref{f1f,,FAIL_FAST}, halts
test running as soon as the first failure is detected.  (Contributed by R.
David Murray and Daniel Urban in bpo-16522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16522}.)

The @ref{3a,,doctest} command line interface now uses @ref{6,,argparse}, and has two
new options, @code{-o} and @code{-f}.  @code{-o} allows @ref{f1e,,doctest options} to be specified on the command line, and @code{-f} is a
shorthand for @code{-o FAIL_FAST} (to parallel the similar option supported by the
@ref{105,,unittest} CLI).  (Contributed by R. David Murray in bpo-11390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11390}.)

@ref{3a,,doctest} will now find doctests in extension module @code{__doc__} strings.
(Contributed by Zachary Ware in bpo-3158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3158}.)

@node email<4>,filecmp,doctest<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 email}@anchor{f20}
@subsubsection email


@ref{f21,,as_string()} now accepts a `policy' argument to
override the default policy of the message when generating a string
representation of it.  This means that @code{as_string} can now be used in more
circumstances, instead of having to create and use a @ref{40,,generator} in
order to pass formatting parameters to its @code{flatten} method.  (Contributed by
R. David Murray in bpo-18600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18600}.)

New method @ref{f22,,as_bytes()} added to produce a bytes
representation of the message in a fashion similar to how @code{as_string}
produces a string representation.  It does not accept the `maxheaderlen'
argument, but does accept the `unixfrom' and `policy' arguments. The
@ref{279,,Message} @ref{f23,,__bytes__()} method
calls it, meaning that @code{bytes(mymsg)} will now produce the intuitive
result:  a bytes object containing the fully formatted message.  (Contributed
by R. David Murray in bpo-18600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18600}.)

The @ref{f24,,Message.set_param()} message now accepts a `replace' keyword argument.
When specified, the associated header will be updated without changing
its location in the list of headers.  For backward compatibility, the default
is @code{False}.  (Contributed by R. David Murray in bpo-18891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18891}.)
@anchor{whatsnew/3 4 whatsnew-email-contentmanager}@anchor{ed0}
A pair of new subclasses of @ref{279,,Message} have been added
(@ref{278,,EmailMessage} and @ref{f25,,MIMEPart}), along with a new sub-module,
@ref{3d,,contentmanager} and a new @ref{4f,,policy} attribute
@ref{f26,,content_manager}.  All documentation is
currently in the new module, which is being added as part of email's new
@ref{af1,,provisional API}.  These classes provide a number of new methods that
make extracting content from and inserting content into email messages much
easier.  For details, see the @ref{3d,,contentmanager} documentation and
the @ref{f27,,email; Exemples}.  These API additions complete the
bulk of the work that was planned as part of the email6 project.  The currently
provisional API is scheduled to become final in Python 3.5 (possibly with a few
minor additions in the area of error handling).  (Contributed by R. David
Murray in bpo-18891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18891}.)

@node filecmp,functools<5>,email<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 filecmp}@anchor{f28}
@subsubsection filecmp


A new @ref{f29,,clear_cache()} function provides the ability to clear the
@ref{59,,filecmp} comparison cache, which uses @ref{48a,,os.stat()} information to
determine if the file has changed since the last compare.  This can be used,
for example, if the file might have been changed and re-checked in less time
than the resolution of a particular filesystem's file modification time field.
(Contributed by Mark Levitt in bpo-18149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18149}.)

New module attribute @ref{f2a,,DEFAULT_IGNORES} provides the list of
directories that are used as the default value for the `ignore' parameter of
the @ref{f2b,,dircmp()} function.  (Contributed by Eli Bendersky in
bpo-15442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15442}.)

@node functools<5>,gc<5>,filecmp,Modules améliorés<10>
@anchor{whatsnew/3 4 functools}@anchor{f2c}
@subsubsection functools


The new @ref{a69,,partialmethod()} descriptor brings partial argument
application to descriptors, just as @ref{40a,,partial()} provides
for normal callables. The new descriptor also makes it easier to get
arbitrary callables (including @ref{40a,,partial()} instances)
to behave like normal instance methods when included in a class definition.
(Contributed by Alon Horev and Nick Coghlan in bpo-4331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4331}.)
@anchor{whatsnew/3 4 whatsnew-singledispatch}@anchor{ecd}
The new @ref{624,,singledispatch()} decorator brings support for
single-dispatch generic functions to the Python standard library. Where
object oriented programming focuses on grouping multiple operations on a
common set of data into a class, a generic function focuses on grouping
multiple implementations of an operation that allows it to work with
`different' kinds of data.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 443

@item PEP 443@footnote{https://peps.python.org/pep-0443/} -- Single-dispatch generic functions

PEP written and implemented by Łukasz Langa.
@end table


@ref{f2d,,total_ordering()} now supports a return value of
@ref{7bc,,NotImplemented} from the underlying comparison function.  (Contributed
by Katie Miller in bpo-10042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10042}.)

A pure-python version of the @ref{40a,,partial()} function is now in the
stdlib; in CPython it is overridden by the C accelerated version, but it is
available for other implementations to use.  (Contributed by Brian Thorne in
bpo-12428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12428}.)

@node gc<5>,glob<4>,functools<5>,Modules améliorés<10>
@anchor{whatsnew/3 4 gc}@anchor{f2e}
@subsubsection `gc'


New function @ref{f2f,,get_stats()} returns a list of three per-generation
dictionaries containing the collections statistics since interpreter startup.
(Contributed by Antoine Pitrou in bpo-16351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16351}.)

@node glob<4>,hashlib<6>,gc<5>,Modules améliorés<10>
@anchor{whatsnew/3 4 glob}@anchor{f30}
@subsubsection glob


A new function @ref{f31,,escape()} provides a way to escape special characters
in a filename so that they do not become part of the globbing expansion but are
instead matched literally.  (Contributed by Serhiy Storchaka in bpo-8402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8402}.)

@node hashlib<6>,hmac<3>,glob<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 hashlib}@anchor{f32}
@subsubsection `hashlib'


A new @ref{4f8,,hashlib.pbkdf2_hmac()} function provides
the PKCS#5 password-based key derivation function 2@footnote{https://en.wikipedia.org/wiki/PBKDF2}.  (Contributed by Christian
Heimes in bpo-18582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18582}.)

The @ref{f33,,name} attribute of @ref{67,,hashlib} hash objects is now
a formally supported interface.  It has always existed in CPython's
@ref{67,,hashlib} (although it did not return lower case names for all supported
hashes), but it was not a public interface and so some other Python
implementations have not previously supported it.  (Contributed by Jason R.
Coombs in bpo-18532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18532}.)

@node hmac<3>,html,hashlib<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 hmac}@anchor{f34}
@subsubsection @code{hmac}


@ref{69,,hmac} now accepts @code{bytearray} as well as @code{bytes} for the `key'
argument to the @ref{a8d,,new()} function, and the `msg' parameter to both the
@ref{a8d,,new()} function and the @ref{f35,,update()} method now
accepts any type supported by the @ref{67,,hashlib} module.  (Contributed
by Jonas Borgström in bpo-18240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18240}.)

The `digestmod' argument to the @ref{a8d,,hmac.new()} function may now be any hash
digest name recognized by @ref{67,,hashlib}.  In addition, the current behavior in
which the value of `digestmod' defaults to @code{MD5} is deprecated: in a
future version of Python there will be no default value.  (Contributed by
Christian Heimes in bpo-17276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17276}.)

With the addition of @ref{f36,,block_size} and @ref{f37,,name}
attributes (and the formal documentation of the @ref{f38,,digest_size}
attribute), the @ref{69,,hmac} module now conforms fully to the 
@geindex Python Enhancement Proposals; PEP 247
PEP 247@footnote{https://peps.python.org/pep-0247/} API.
(Contributed by Christian Heimes in bpo-18775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18775}.)

@node html,http<3>,hmac<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 html}@anchor{f39}
@subsubsection html


New function @ref{944,,unescape()} function converts HTML5 character references to
the corresponding Unicode characters.  (Contributed by Ezio Melotti in
bpo-2927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2927}.)

@ref{862,,HTMLParser} accepts a new keyword argument
`convert_charrefs' that, when @code{True}, automatically converts all character
references.  For backward-compatibility, its value defaults to @code{False}, but
it will change to @code{True} in a future version of Python, so you are invited to
set it explicitly and update your code to use this new feature.  (Contributed
by Ezio Melotti in bpo-13633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13633}.)

The `strict' argument of @ref{862,,HTMLParser} is now deprecated.
(Contributed by Ezio Melotti in bpo-15114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15114}.)

@node http<3>,idlelib and IDLE<4>,html,Modules améliorés<10>
@anchor{whatsnew/3 4 http}@anchor{f3a}
@subsubsection `http'


@ref{f3b,,send_error()} now accepts an
optional additional `explain' parameter which can be used to provide an
extended error description, overriding the hardcoded default if there is one.
This extended error description will be formatted using the
@code{error_message_format} attribute and sent as the body
of the error response.  (Contributed by Karl Cow in bpo-12921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12921}.)

The @ref{71,,http.server} @ref{f3c,,command line interface} now has
a @code{-b/--bind} option that causes the server to listen on a specific address.
(Contributed by Malte Swart in bpo-17764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17764}.)

@node idlelib and IDLE<4>,importlib<9>,http<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 idlelib-and-idle}@anchor{f3d}
@subsubsection idlelib and IDLE


Since idlelib implements the IDLE shell and editor and is not intended for
import by other programs, it gets improvements with every release. See
@code{Lib/idlelib/NEWS.txt} for a cumulative list of changes since 3.3.0,
as well as changes made in future 3.4.x releases. This file is also available
from the IDLE Help ‣ About IDLE dialog.

@node importlib<9>,inspect<8>,idlelib and IDLE<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 importlib}@anchor{f3e}
@subsubsection importlib


The @ref{f3f,,InspectLoader} ABC defines a new method,
@ref{dfe,,source_to_code()} that accepts source
data and a path and returns a code object.  The default implementation
is equivalent to @code{compile(data, path, 'exec', dont_inherit=True)}.
(Contributed by Eric Snow and Brett Cannon in bpo-15627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15627}.)

@ref{f3f,,InspectLoader} also now has a default implementation
for the @ref{f40,,get_code()} method.  However,
it will normally be desirable to override the default implementation
for performance reasons.  (Contributed by Brett Cannon in bpo-18072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18072}.)

The @ref{502,,reload()} function has been moved from @code{imp} to
@ref{76,,importlib} as part of the @code{imp} module deprecation.  (Contributed by
Berker Peksag in bpo-18193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18193}.)

@ref{7c,,importlib.util} now has a @ref{4fc,,MAGIC_NUMBER} attribute
providing access to the bytecode version number.  This replaces the
@code{get_magic()} function in the deprecated @code{imp} module.
(Contributed by Brett Cannon in bpo-18192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18192}.)

New @ref{7c,,importlib.util} functions @ref{2f2,,cache_from_source()}
and @ref{503,,source_from_cache()} replace the same-named functions
in the deprecated @code{imp} module.  (Contributed by Brett Cannon in
bpo-18194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18194}.)

The @ref{76,,importlib} bootstrap @ref{f41,,NamespaceLoader} now conforms to
the @ref{f3f,,InspectLoader} ABC, which means that @code{runpy} and
@code{python -m} can now be used with namespace packages.  (Contributed
by Brett Cannon in bpo-18058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18058}.)

@ref{7c,,importlib.util} has a new function @ref{f42,,decode_source()}
that decodes source from bytes using universal newline processing.  This is
useful for implementing @ref{f43,,InspectLoader.get_source()} methods.

@ref{c9e,,importlib.machinery.ExtensionFileLoader} now has a
@ref{f44,,get_filename()} method.  This was
inadvertently omitted in the original implementation.  (Contributed by Eric
Snow in bpo-19152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19152}.)

@node inspect<8>,ipaddress<5>,importlib<9>,Modules améliorés<10>
@anchor{whatsnew/3 4 inspect}@anchor{f45}
@subsubsection `inspect'


The @ref{7d,,inspect} module now offers a basic @ref{f46,,command line interface} to quickly display source code and other
information for modules, classes and functions.  (Contributed by Claudiu Popa
and Nick Coghlan in bpo-18626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18626}.)

@ref{f47,,unwrap()} makes it easy to unravel wrapper function chains
created by @ref{f48,,functools.wraps()} (and any other API that sets the
@code{__wrapped__} attribute on a wrapper function).  (Contributed by
Daniel Urban, Aaron Iles and Nick Coghlan in bpo-13266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13266}.)

As part of the implementation of the new @ref{55,,enum} module, the
@ref{7d,,inspect} module now has substantially better support for custom
@code{__dir__} methods and dynamic class attributes provided through
metaclasses.  (Contributed by Ethan Furman in bpo-18929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18929} and
bpo-19030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19030}.)

@ref{723,,getfullargspec()} and @code{getargspec()}
now use the @ref{722,,signature()} API. This allows them to
support a much broader range of callables, including those with
@code{__signature__} attributes, those with metadata provided by argument
clinic, @ref{40a,,functools.partial()} objects and more. Note that, unlike
@ref{722,,signature()}, these functions still ignore @code{__wrapped__}
attributes, and report the already bound first argument for bound methods,
so it is still necessary to update your code to use
@ref{722,,signature()} directly if those features are desired.
(Contributed by Yury Selivanov in bpo-17481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17481}.)

@ref{722,,signature()} now supports duck types of CPython functions,
which adds support for functions compiled with Cython.  (Contributed
by Stefan Behnel and Yury Selivanov in bpo-17159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17159}.)

@node ipaddress<5>,logging<6>,inspect<8>,Modules améliorés<10>
@anchor{whatsnew/3 4 ipaddress}@anchor{f49}
@subsubsection `ipaddress'


@ref{7f,,ipaddress} was added to the standard library in Python 3.3 as a
@ref{af1,,provisional API}. With the release of Python 3.4, this qualification
has been removed: @ref{7f,,ipaddress} is now considered a stable API, covered
by the normal standard library requirements to maintain backwards
compatibility.

A new @ref{f4a,,is_global} property is @code{True} if
an address is globally routeable.  (Contributed by Peter Moody in
bpo-17400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17400}.)

@node logging<6>,marshal<2>,ipaddress<5>,Modules améliorés<10>
@anchor{whatsnew/3 4 logging}@anchor{f4b}
@subsubsection logging


The @ref{f4c,,TimedRotatingFileHandler} has a new `atTime'
parameter that can be used to specify the time of day when rollover should
happen.  (Contributed by Ronald Oussoren in bpo-9556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9556}.)

@ref{f4d,,SocketHandler} and
@ref{f4e,,DatagramHandler} now support Unix domain sockets (by
setting `port' to @code{None}).  (Contributed by Vinay Sajip in commit
ce46195b56a9.)

@ref{b3f,,fileConfig()} now accepts a
@ref{f4f,,configparser.RawConfigParser} subclass instance for the `fname'
parameter.  This facilitates using a configuration file when logging
configuration is just a part of the overall application configuration, or where
the application modifies the configuration before passing it to
@ref{b3f,,fileConfig()}.  (Contributed by Vinay Sajip in
bpo-16110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16110}.)

Logging configuration data received from a socket via the
@ref{f50,,logging.config.listen()} function can now be validated before being
processed by supplying a verification function as the argument to the new
`verify' keyword argument.  (Contributed by Vinay Sajip in bpo-15452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15452}.)

@node marshal<2>,mmap<3>,logging<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 marshal}@anchor{f51}@anchor{whatsnew/3 4 whatsnew-marshal-3}@anchor{ec5}
@subsubsection marshal


The default @ref{8c,,marshal} version has been bumped to 3.  The code implementing
the new version restores the Python2 behavior of recording only one copy of
interned strings and preserving the interning on deserialization, and extends
this "one copy" ability to any object type (including handling recursive
references).  This reduces both the size of @code{.pyc} files and the amount of
memory a module occupies in memory when it is loaded from a @code{.pyc} (or
@code{.pyo}) file.  (Contributed by Kristján Valur Jónsson in bpo-16475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16475},
with additional speedups by Antoine Pitrou in bpo-19219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19219}.)

@node mmap<3>,multiprocessing<7>,marshal<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 mmap}@anchor{f52}
@subsubsection mmap


mmap objects are now @ref{ef5,,weakly referenceable}.
(Contributed by Valerie Lambert in bpo-4885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4885}.)

@node multiprocessing<7>,operator<3>,mmap<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 multiprocessing}@anchor{f53}
@subsubsection multiprocessing

@anchor{whatsnew/3 4 whatsnew-multiprocessing-no-fork}@anchor{ecf}
On Unix two new @ref{2c6,,start methods},
@code{spawn} and @code{forkserver}, have been added for starting processes using
@ref{93,,multiprocessing}.  These make the mixing of processes with threads more
robust, and the @code{spawn} method matches the semantics that multiprocessing has
always used on Windows.  New function
@ref{f54,,get_all_start_methods()} reports all start methods
available on the platform, @ref{f55,,get_start_method()} reports
the current start method, and @ref{2c5,,set_start_method()} sets
the start method.  (Contributed by Richard Oudkerk in bpo-8713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8713}.)

@ref{93,,multiprocessing} also now has the concept of a @code{context}, which
determines how child processes are created.  New function
@ref{2c4,,get_context()} returns a context that uses a specified
start method.  It has the same API as the @ref{93,,multiprocessing} module itself,
so you can use it to create @ref{f56,,Pool}s and other
objects that will operate within that context.  This allows a framework and an
application or different parts of the same application to use multiprocessing
without interfering with each other.  (Contributed by Richard Oudkerk in
bpo-18999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18999}.)

Except when using the old `fork' start method, child processes no longer
inherit unneeded handles/file descriptors from their parents (part of
bpo-8713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8713}).

@ref{93,,multiprocessing} now relies on @ref{bd,,runpy} (which implements the
@code{-m} switch) to initialise @code{__main__} appropriately in child processes
when using the @code{spawn} or @code{forkserver} start methods. This resolves some
edge cases where combining multiprocessing, the @code{-m} command line switch,
and explicit relative imports could cause obscure failures in child
processes.  (Contributed by Nick Coghlan in bpo-19946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19946}.)

@node operator<3>,os<11>,multiprocessing<7>,Modules améliorés<10>
@anchor{whatsnew/3 4 operator}@anchor{f57}
@subsubsection @code{operator}


New function @ref{f58,,length_hint()} provides an implementation of the
specification for how the @ref{ef6,,__length_hint__()} special method should
be used, as part of the 
@geindex Python Enhancement Proposals; PEP 424
PEP 424@footnote{https://peps.python.org/pep-0424/} formal specification of this language
feature.  (Contributed by Armin Ronacher in bpo-16148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16148}.)

There is now a pure-python version of the @ref{9e,,operator} module available for
reference and for use by alternate implementations of Python.  (Contributed by
Zachary Ware in bpo-16694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16694}.)

@node os<11>,pdb<6>,operator<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 os}@anchor{f59}
@subsubsection `os'


There are new functions to get and set the @ref{ee4,,inheritable flag} of a file descriptor (@ref{ee5,,os.get_inheritable()},
@ref{ee6,,os.set_inheritable()}) or a Windows handle
(@ref{ee7,,os.get_handle_inheritable()}, @ref{ee8,,os.set_handle_inheritable()}).

New function @ref{1c0,,cpu_count()} reports the number of CPUs available on the
platform on which Python is running (or @code{None} if the count can't be
determined).  The @ref{f5a,,multiprocessing.cpu_count()} function is now implemented
in terms of this function).  (Contributed by Trent Nelson, Yogesh Chaudhari,
Victor Stinner, and Charles-François Natali in bpo-17914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17914}.)

@ref{f5b,,os.path.samestat()} is now available on the Windows platform (and the
@ref{f5c,,os.path.samefile()} implementation is now shared between Unix and
Windows).  (Contributed by Brian Curtin in bpo-11939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11939}.)

@ref{a00,,os.path.ismount()} now recognizes volumes mounted below a drive
root on Windows.  (Contributed by Tim Golden in bpo-9035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9035}.)

@ref{d7f,,os.open()} supports two new flags on platforms that provide them,
@ref{f5d,,O_PATH} (un-opened file descriptor), and @ref{f5e,,O_TMPFILE}
(unnamed temporary file; as of 3.4.0 release available only on Linux systems
with a kernel version of 3.11 or newer that have uapi headers).  (Contributed
by Christian Heimes in bpo-18673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18673} and Benjamin Peterson, respectively.)

@node pdb<6>,pickle<4>,os<11>,Modules améliorés<10>
@anchor{whatsnew/3 4 pdb}@anchor{f5f}
@subsubsection `pdb'


@ref{a4,,pdb} has been enhanced to handle generators, @ref{9bb,,yield}, and
@code{yield from} in a more useful fashion.  This is especially helpful when
debugging @ref{a,,asyncio} based programs.  (Contributed by Andrew Svetlov and
Xavier de Gaye in bpo-16596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16596}.)

The @code{print} command has been removed from @ref{a4,,pdb}, restoring access to the
Python @ref{f60,,print()} function from the pdb command line.  Python2's @code{pdb} did
not have a @code{print} command; instead, entering @code{print} executed the
@code{print} statement.  In Python3 @code{print} was mistakenly made an alias for the
pdb @ref{f61,,p} command.  @code{p}, however, prints the @code{repr} of its argument,
not the @code{str} like the Python2 @code{print} command did.  Worse, the Python3
@code{pdb print} command shadowed the Python3 @code{print} function, making it
inaccessible at the @code{pdb} prompt.  (Contributed by Connor Osborn in
bpo-18764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18764}.)

@node pickle<4>,plistlib<2>,pdb<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 pickle}@anchor{f62}@anchor{whatsnew/3 4 whatsnew-protocol-4}@anchor{ece}
@subsubsection pickle


@ref{a5,,pickle} now supports (but does not use by default) a new pickle protocol,
protocol 4.  This new protocol addresses a number of issues that were present
in previous protocols, such as the serialization of nested classes, very large
strings and containers, and classes whose @code{__new__()} method takes
keyword-only arguments.  It also provides some efficiency improvements.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3154

@item PEP 3154@footnote{https://peps.python.org/pep-3154/} -- Pickle protocol 4

PEP written by Antoine Pitrou and implemented by Alexandre Vassalotti.
@end table


@node plistlib<2>,poplib<3>,pickle<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 plistlib}@anchor{f63}
@subsubsection plistlib


@ref{aa,,plistlib} now has an API that is similar to the standard pattern for
stdlib serialization protocols, with new @ref{93c,,load()},
@ref{93e,,dump()}, @ref{93d,,loads()}, and @ref{93f,,dumps()}
functions.  (The older API is now deprecated.)  In addition to the already
supported XML plist format (@ref{f64,,FMT_XML}), it also now supports
the binary plist format (@ref{f65,,FMT_BINARY}).  (Contributed by Ronald
Oussoren and others in bpo-14455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14455}.)

@node poplib<3>,pprint<4>,plistlib<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 poplib}@anchor{f66}
@subsubsection `poplib'


Two new methods have been added to @ref{ab,,poplib}: @ref{f67,,capa()},
which returns the list of capabilities advertised by the POP server, and
@ref{f68,,stls()}, which switches a clear-text POP3 session into an
encrypted POP3 session if the POP server supports it.  (Contributed by Lorenzo
Catucci in bpo-4473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4473}.)

@node pprint<4>,pty,poplib<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 pprint}@anchor{f69}
@subsubsection `pprint'


The @ref{ad,,pprint} module's @ref{f6a,,PrettyPrinter} class and its
@ref{f6b,,pformat()}, and @ref{812,,pprint()} functions have a new
option, `compact', that controls how the output is formatted.  Currently
setting `compact' to @code{True} means that sequences will be printed with as many
sequence elements as will fit within `width' on each (indented) line.
(Contributed by Serhiy Storchaka in bpo-19132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19132}.)

Long strings are now wrapped using Python's normal line continuation
syntax.  (Contributed by Antoine Pitrou in bpo-17150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17150}.)

@node pty,pydoc<4>,pprint<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 pty}@anchor{f6c}
@subsubsection pty


@ref{f6d,,pty.spawn()} now returns the status value from @ref{d87,,os.waitpid()} on
the child process, instead of @code{None}.  (Contributed by Gregory P. Smith.)

@node pydoc<4>,re<8>,pty,Modules améliorés<10>
@anchor{whatsnew/3 4 pydoc}@anchor{f6e}
@subsubsection `pydoc'


The @ref{b4,,pydoc} module is now based directly on the @ref{722,,inspect.signature()}
introspection API, allowing it to provide signature information for a wider
variety of callable objects. This change also means that @code{__wrapped__}
attributes are now taken into account when displaying help information.
(Contributed by Larry Hastings in bpo-19674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19674}.)

The @ref{b4,,pydoc} module no longer displays the @code{self} parameter for
already bound methods. Instead, it aims to always display the exact current
signature of the supplied callable.  (Contributed by Larry Hastings in
bpo-20710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20710}.)

In addition to the changes that have been made to @ref{b4,,pydoc} directly,
its handling of custom @code{__dir__} methods and various descriptor
behaviours has also been improved substantially by the underlying changes in
the @ref{7d,,inspect} module.

As the @ref{8c4,,help()} builtin is based on @ref{b4,,pydoc}, the above changes also
affect the behaviour of @ref{8c4,,help()}.

@node re<8>,resource,pydoc<4>,Modules améliorés<10>
@anchor{whatsnew/3 4 re}@anchor{f6f}
@subsubsection @code{re}


New @ref{f70,,fullmatch()} function and @code{regex.fullmatch()} method anchor
the pattern at both ends of the string to match.  This provides a way to be
explicit about the goal of the match, which avoids a class of subtle bugs where
@code{$} characters get lost during code changes or the addition of alternatives
to an existing regular expression.  (Contributed by Matthew Barnett in
bpo-16203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16203}.)

The repr of @ref{f71,,regex objects} now includes the pattern
and the flags; the repr of @ref{f72,,match objects} now
includes the start, end, and the part of the string that matched.  (Contributed
by Hugo Lopes Tavares and Serhiy Storchaka in bpo-13592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13592} and
bpo-17087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17087}.)

@node resource,select,re<8>,Modules améliorés<10>
@anchor{whatsnew/3 4 resource}@anchor{f73}
@subsubsection resource


New @ref{f74,,prlimit()} function, available on Linux platforms with a
kernel version of 2.6.36 or later and glibc of 2.13 or later, provides the
ability to query or set the resource limits for processes other than the one
making the call.  (Contributed by Christian Heimes in bpo-16595@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16595}.)

On Linux kernel version 2.6.36 or later, there are also some new
Linux specific constants: @ref{f75,,RLIMIT_MSGQUEUE},
@ref{f76,,RLIMIT_NICE}, @ref{f77,,RLIMIT_RTPRIO},
@ref{f78,,RLIMIT_RTTIME}, and @ref{f79,,RLIMIT_SIGPENDING}.
(Contributed by Christian Heimes in bpo-19324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19324}.)

On FreeBSD version 9 and later, there some new FreeBSD specific constants:
@ref{f7a,,RLIMIT_SBSIZE}, @ref{f7b,,RLIMIT_SWAP}, and
@ref{f7c,,RLIMIT_NPTS}.  (Contributed by Claudiu Popa in
bpo-19343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19343}.)

@node select,shelve<2>,resource,Modules améliorés<10>
@anchor{whatsnew/3 4 select}@anchor{f7d}
@subsubsection select


@ref{f7e,,epoll} objects now support the context management protocol.
When used in a @ref{5bc,,with} statement, the @ref{f7f,,close()}
method will be called automatically at the end of the block.  (Contributed
by Serhiy Storchaka in bpo-16488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16488}.)

@ref{f80,,devpoll} objects now have @ref{f81,,fileno()} and
@ref{f82,,close()} methods, as well as a new attribute
@ref{f83,,closed}.  (Contributed by Victor Stinner in
bpo-18794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18794}.)

@node shelve<2>,shutils<6>,select,Modules améliorés<10>
@anchor{whatsnew/3 4 shelve}@anchor{f84}
@subsubsection @code{shelve}


@ref{f85,,Shelf} instances may now be used in @ref{5bc,,with} statements,
and will be automatically closed at the end of the @code{with} block.
(Contributed by Filip Gruszczyński in bpo-13896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13896}.)

@node shutils<6>,smtpd<3>,shelve<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 shutil}@anchor{f86}
@subsubsection @code{shutils}


@ref{a47,,copyfile()} now raises a specific @ref{f87,,Error} subclass,
@ref{f88,,SameFileError}, when the source and destination are the same
file, which allows an application to take appropriate action on this specific
error.  (Contributed by Atsuo Ishimoto and Hynek Schlawack in
bpo-1492704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1492704}.)

@node smtpd<3>,smtplib<3>,shutils<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 smtpd}@anchor{f89}
@subsubsection smtpd


The @code{SMTPServer} and @code{SMTPChannel} classes now
accept a `map' keyword argument which, if specified, is passed in to
@code{asynchat.async_chat} as its `map' argument.  This allows an application
to avoid affecting the global socket map.  (Contributed by Vinay Sajip in
bpo-11959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11959}.)

@node smtplib<3>,socket<9>,smtpd<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 smtplib}@anchor{f8a}
@subsubsection `smtplib'


@ref{f8b,,SMTPException} is now a subclass of @ref{40d,,OSError}, which allows
both socket level errors and SMTP protocol level errors to be caught in one
try/except statement by code that only cares whether or not an error occurred.
(Contributed by Ned Jackson Lovely in bpo-2118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2118}.)

@node socket<9>,sqlite3<9>,smtplib<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 socket}@anchor{f8c}
@subsubsection `socket'


The socket module now supports the @ref{f8d,,CAN_BCM} protocol on
platforms that support it.  (Contributed by Brian Thorne in bpo-15359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15359}.)

Socket objects have new methods to get or set their @ref{ee4,,inheritable flag}, @ref{ee9,,get_inheritable()} and
@ref{eea,,set_inheritable()}.

The @code{socket.AF_*} and @code{socket.SOCK_*} constants are now enumeration values
using the new @ref{55,,enum} module.  This allows meaningful names to be printed
during debugging, instead of integer "magic numbers".

The @ref{f8e,,AF_LINK} constant is now available on BSD and OSX.

@ref{94f,,inet_pton()} and @ref{f8f,,inet_ntop()} are now supported
on Windows.  (Contributed by Atsuo Ishimoto in bpo-7171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7171}.)

@node sqlite3<9>,ssl<10>,socket<9>,Modules améliorés<10>
@anchor{whatsnew/3 4 sqlite3}@anchor{f90}
@subsubsection @code{sqlite3}


A new boolean parameter to the @ref{2a5,,connect()} function, `uri', can be
used to indicate that the `database' parameter is a @code{uri} (see the SQLite URI documentation@footnote{https://www.sqlite.org/uri.html}).  (Contributed by poq in
bpo-13773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13773}.)

@node ssl<10>,stat,sqlite3<9>,Modules améliorés<10>
@anchor{whatsnew/3 4 ssl}@anchor{f91}
@subsubsection @code{ssl}

@anchor{whatsnew/3 4 whatsnew-tls-11-12}@anchor{ed2}
@ref{f92,,PROTOCOL_TLSv1_1} and @ref{f93,,PROTOCOL_TLSv1_2} (TLSv1.1 and
TLSv1.2 support) have been added; support for these protocols is only available if
Python is linked with OpenSSL 1.0.1 or later.  (Contributed by Michele Orrù and
Antoine Pitrou in bpo-16692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16692}.)
@anchor{whatsnew/3 4 whatsnew34-sslcontext}@anchor{ed5}
New function @ref{154,,create_default_context()} provides a standard way to
obtain an @ref{291,,SSLContext} whose settings are intended to be a
reasonable balance between compatibility and security.  These settings are
more stringent than the defaults provided by the @ref{291,,SSLContext}
constructor, and may be adjusted in the future, without prior deprecation, if
best-practice security requirements change.  The new recommended best
practice for using stdlib libraries that support SSL is to use
@ref{154,,create_default_context()} to obtain an @ref{291,,SSLContext}
object, modify it if needed, and then pass it as the `context' argument
of the appropriate stdlib API.  (Contributed by Christian Heimes
in bpo-19689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19689}.)

@ref{291,,SSLContext} method @ref{ed6,,load_verify_locations()}
accepts a new optional argument `cadata', which can be used to provide PEM or
DER encoded certificates directly via strings or bytes, respectively.
(Contributed by Christian Heimes in bpo-18138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18138}.)

New function @ref{f94,,get_default_verify_paths()} returns
a named tuple of the paths and environment variables that the
@ref{f95,,set_default_verify_paths()} method uses to set
OpenSSL's default @code{cafile} and @code{capath}.  This can be an aid in
debugging default verification issues.  (Contributed by Christian Heimes
in bpo-18143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18143}.)

@ref{291,,SSLContext} has a new method,
@ref{f96,,cert_store_stats()}, that reports the number of loaded
@code{X.509} certs, @code{X.509 CA} certs, and certificate revocation lists
(@code{crl}s), as well as a @ref{f97,,get_ca_certs()} method that
returns a list of the loaded @code{CA} certificates.  (Contributed by Christian
Heimes in bpo-18147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18147}.)

If OpenSSL 0.9.8 or later is available, @ref{291,,SSLContext} has a new
attribute @ref{f98,,verify_flags} that can be used to control the
certificate verification process by setting it to some combination of the new
constants @ref{f99,,VERIFY_DEFAULT}, @ref{f9a,,VERIFY_CRL_CHECK_LEAF},
@ref{f9b,,VERIFY_CRL_CHECK_CHAIN}, or @ref{156,,VERIFY_X509_STRICT}.
OpenSSL does not do any CRL verification by default.  (Contributed by
Christien Heimes in bpo-8813@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8813}.)

New @ref{291,,SSLContext} method @ref{f9c,,load_default_certs()}
loads a set of default "certificate authority" (CA) certificates from default
locations, which vary according to the platform.  It can be used to load both
TLS web server authentication certificates
(@code{purpose=}@ref{f9d,,SERVER_AUTH}) for a client to use to verify a
server, and certificates for a server to use in verifying client certificates
(@code{purpose=}@ref{f9e,,CLIENT_AUTH}).  (Contributed by Christian
Heimes in bpo-19292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19292}.)
@anchor{whatsnew/3 4 whatsnew34-win-cert-store}@anchor{ed3}
Two new windows-only functions, @ref{f9f,,enum_certificates()} and
@ref{fa0,,enum_crls()} provide the ability to retrieve certificates,
certificate information, and CRLs from the Windows cert store.  (Contributed
by Christian Heimes in bpo-17134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17134}.)
@anchor{whatsnew/3 4 whatsnew34-sni}@anchor{ed4}
Support for server-side SNI (Server Name Indication) using the new
@ref{fa1,,ssl.SSLContext.set_servername_callback()} method.
(Contributed by Daniel Black in bpo-8109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8109}.)

The dictionary returned by @ref{fa2,,SSLSocket.getpeercert()} contains additional
@code{X509v3} extension items: @code{crlDistributionPoints}, @code{calIssuers}, and
@code{OCSP} URIs.  (Contributed by Christian Heimes in bpo-18379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18379}.)

@node stat,struct<2>,ssl<10>,Modules améliorés<10>
@anchor{whatsnew/3 4 stat}@anchor{fa3}
@subsubsection stat


The @ref{d0,,stat} module is now backed by a C implementation in @code{_stat}. A C
implementation is required as most of the values aren't standardized and
are platform-dependent.  (Contributed by Christian Heimes in bpo-11016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11016}.)

The module supports new @ref{fa4,,ST_MODE} flags, @ref{fa5,,S_IFDOOR},
@ref{fa6,,S_IFPORT}, and @ref{fa7,,S_IFWHT}.  (Contributed by
Christian Hiemes in bpo-11016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11016}.)

@node struct<2>,subprocess<5>,stat,Modules améliorés<10>
@anchor{whatsnew/3 4 struct}@anchor{fa8}
@subsubsection struct


New function @ref{fa9,,iter_unpack} and a new
@ref{faa,,struct.Struct.iter_unpack()} method on compiled formats provide streamed
unpacking of a buffer containing repeated instances of a given format of data.
(Contributed by Antoine Pitrou in bpo-17804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17804}.)

@node subprocess<5>,sunau<2>,struct<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 subprocess}@anchor{fab}
@subsubsection subprocess


@ref{fac,,check_output()} now accepts an `input' argument that can
be used to provide the contents of @code{stdin} for the command that is run.
(Contributed by Zack Weinberg in bpo-16624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16624}.)

@code{getstatus()} and @ref{fad,,getstatusoutput()} now
work on Windows.  This change was actually inadvertently made in 3.3.4.
(Contributed by Tim Golden in bpo-10197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10197}.)

@node sunau<2>,sys<12>,subprocess<5>,Modules améliorés<10>
@anchor{whatsnew/3 4 sunau}@anchor{fae}
@subsubsection sunau


The @code{getparams()} method now returns a namedtuple rather than a
plain tuple.  (Contributed by Claudiu Popa in bpo-18901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18901}.)

@code{sunau.open()} now supports the context management protocol: when used in a
@ref{5bc,,with} block, the @code{close} method of the returned object will be
called automatically at the end of the block.  (Contributed by Serhiy Storchaka
in bpo-18878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18878}.)

@code{AU_write.setsampwidth()} now supports 24 bit samples, thus adding
support for writing 24 sample using the module.  (Contributed by
Serhiy Storchaka in bpo-19261@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19261}.)

The @code{writeframesraw()} and
@code{writeframes()} methods now accept any @ref{d1b,,bytes-like object}.  (Contributed by Serhiy Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node sys<12>,tarfile<7>,sunau<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 sys}@anchor{faf}
@subsubsection sys


New function @ref{fb0,,sys.getallocatedblocks()} returns the current number of
blocks allocated by the interpreter.  (In CPython with the default
@code{--with-pymalloc} setting, this is allocations made through the
@ref{c56,,PyObject_Malloc()} API.)  This can be useful for tracking memory leaks,
especially if automated via a test suite.  (Contributed by Antoine Pitrou
in bpo-13390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13390}.)

When the Python interpreter starts in @ref{fb1,,interactive mode}, it checks for an @ref{fb2,,__interactivehook__} attribute
on the @ref{d8,,sys} module.  If the attribute exists, its value is called with no
arguments just before interactive mode is started.  The check is made after the
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} file is read, so it can be set there.  The @ref{c6,,site}
module @ref{fb4,,sets it} to a function that enables tab
completion and history saving (in @code{~/.python-history}) if the platform
supports @ref{b9,,readline}.  If you do not want this (new) behavior, you can
override it in 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP}, @ref{c7,,sitecustomize}, or
@ref{10d,,usercustomize} by deleting this attribute from @ref{d8,,sys} (or setting it
to some other callable).  (Contributed by Éric Araujo and Antoine Pitrou in
bpo-5845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5845}.)

@node tarfile<7>,textwrap,sys<12>,Modules améliorés<10>
@anchor{whatsnew/3 4 tarfile}@anchor{fb5}
@subsubsection tarfile


The @ref{dd,,tarfile} module now supports a simple @ref{fb6,,Interface en ligne de commande} when
called as a script directly or via @code{-m}.  This can be used to create and
extract tarfile archives.  (Contributed by Berker Peksag in bpo-13477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13477}.)

@node textwrap,threading<7>,tarfile<7>,Modules améliorés<10>
@anchor{whatsnew/3 4 textwrap}@anchor{fb7}
@subsubsection textwrap


The @ref{fb8,,TextWrapper} class has two new attributes/constructor
arguments: @ref{fb9,,max_lines}, which limits the number of
lines in the output, and @ref{fba,,placeholder}, which is a
string that will appear at the end of the output if it has been truncated
because of `max_lines'.  Building on these capabilities, a new convenience
function @ref{fbb,,shorten()} collapses all of the whitespace in the input
to single spaces and produces a single line of a given `width' that ends with
the `placeholder' (by default, @code{[...]}).  (Contributed by Antoine Pitrou and
Serhiy Storchaka in bpo-18585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18585} and bpo-18725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18725}.)

@node threading<7>,traceback<6>,textwrap,Modules améliorés<10>
@anchor{whatsnew/3 4 threading}@anchor{fbc}
@subsubsection threading


The @ref{939,,Thread} object representing the main thread can be
obtained from the new @ref{fbd,,main_thread()} function.  In normal
conditions this will be the thread from which the Python interpreter was
started.  (Contributed by Andrew Svetlov in bpo-18882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18882}.)

@node traceback<6>,types<6>,threading<7>,Modules améliorés<10>
@anchor{whatsnew/3 4 traceback}@anchor{fbe}
@subsubsection traceback


A new @ref{fbf,,traceback.clear_frames()} function takes a traceback object
and clears the local variables in all of the frames it references,
reducing the amount of memory consumed.  (Contributed by Andrew Kuchling in
bpo-1565525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1565525}.)

@node types<6>,urllib<3>,traceback<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 types}@anchor{fc0}
@subsubsection @code{types}


A new @ref{615,,DynamicClassAttribute()} descriptor provides a way to define
an attribute that acts normally when looked up through an instance object, but
which is routed to the `class' @code{__getattr__} when looked up through the
class.  This allows one to have properties active on a class, and have virtual
attributes on the class with the same name (see @code{Enum} for an example).
(Contributed by Ethan Furman in bpo-19030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19030}.)

@node urllib<3>,unittest<9>,types<6>,Modules améliorés<10>
@anchor{whatsnew/3 4 urllib}@anchor{fc1}
@subsubsection urllib


@ref{10a,,urllib.request} now supports @code{data:} URLs via the
@ref{fc2,,DataHandler} class.  (Contributed by Mathias Panzenböck
in bpo-16423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16423}.)

The http method that will be used by a @ref{fc3,,Request} class
can now be specified by setting a @ref{fc4,,method}
class attribute on the subclass.  (Contributed by Jason R Coombs in
bpo-18978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18978}.)

@ref{fc3,,Request} objects are now reusable: if the
@ref{fc5,,full_url} or @ref{fc6,,data}
attributes are modified, all relevant internal properties are updated.  This
means, for example, that it is now possible to use the same
@ref{fc3,,Request} object in more than one
@ref{fc7,,OpenerDirector.open()} call with different `data' arguments, or to
modify a @ref{fc3,,Request}'s @code{url} rather than recomputing it
from scratch.  There is also a new
@ref{fc8,,remove_header()} method that can be used to remove
headers from a @ref{fc3,,Request}.  (Contributed by Alexey
Kachayev in bpo-16464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16464}, Daniel Wozniak in bpo-17485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17485}, and Damien Brecht
and Senthil Kumaran in bpo-17272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17272}.)

@ref{fc9,,HTTPError} objects now have a
@ref{fca,,headers} attribute that provides access to the
HTTP response headers associated with the error.  (Contributed by
Berker Peksag in bpo-15701@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15701}.)

@node unittest<9>,venv<7>,urllib<3>,Modules améliorés<10>
@anchor{whatsnew/3 4 unittest}@anchor{fcb}
@subsubsection unittest


The @ref{437,,TestCase} class has a new method,
@ref{fcc,,subTest()}, that produces a context manager whose
@ref{5bc,,with} block becomes a "sub-test".  This context manager allows a test
method to dynamically generate subtests  by, say, calling the @code{subTest}
context manager inside a loop.  A single test method can thereby produce an
indefinite number of separately identified and separately counted tests, all of
which will run even if one or more of them fail.  For example:

@example
class NumbersTest(unittest.TestCase):
    def test_even(self):
        for i in range(6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)
@end example

will result in six subtests, each identified in the unittest verbose output
with a label consisting of the variable name @code{i} and a particular value for
that variable (@code{i=0}, @code{i=1}, etc).  See @ref{fcd,,Distinguer les itérations de test à l'aide de sous-tests} for the full
version of this example.  (Contributed by Antoine Pitrou in bpo-16997@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16997}.)

@ref{fce,,unittest.main()} now accepts an iterable of test names for
`defaultTest', where previously it only accepted a single test name as a
string.  (Contributed by Jyrki Pulliainen in bpo-15132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15132}.)

If @ref{fcf,,SkipTest} is raised during test discovery (that is, at the
module level in the test file), it is now reported as a skip instead of an
error.  (Contributed by Zach Ware in bpo-16935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16935}.)

@ref{fd0,,discover()} now sorts the discovered files to provide
consistent test ordering.  (Contributed by Martin Melin and Jeff Ramnani in
bpo-16709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16709}.)

@ref{de1,,TestSuite} now drops references to tests as soon as the test
has been run, if the test is successful.  On Python interpreters that do
garbage collection, this allows the tests to be garbage collected if nothing
else is holding a reference to the test.  It is possible to override this
behavior by creating a @ref{de1,,TestSuite} subclass that defines a
custom @code{_removeTestAtIndex} method.  (Contributed by Tom Wardill, Matt
McClure, and Andrew Svetlov in bpo-11798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11798}.)

A new test assertion context-manager, @ref{843,,assertLogs()},
will ensure that a given block of code emits a log message using the
@ref{86,,logging} module.  By default the message can come from any logger and
have a priority of @code{INFO} or higher, but both the logger name and an
alternative minimum logging level may be specified.  The object returned by the
context manager can be queried for the @ref{fd1,,LogRecord}s and/or
formatted messages that were logged.  (Contributed by Antoine Pitrou in
bpo-18937@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18937}.)

Test discovery now works with namespace packages (Contributed by Claudiu Popa
in bpo-17457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17457}.)

@ref{106,,unittest.mock} objects now inspect their specification signatures when
matching calls, which means an argument can now be matched by either position
or name, instead of only by position.  (Contributed by Antoine Pitrou in
bpo-17015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17015}.)

@code{mock_open()} objects now have @code{readline} and @code{readlines}
methods.  (Contributed by Toshio Kuratomi in bpo-17467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17467}.)

@node venv<7>,wave<2>,unittest<9>,Modules améliorés<10>
@anchor{whatsnew/3 4 venv}@anchor{fd2}
@subsubsection venv


@ref{110,,venv} now includes activation scripts for the @code{csh} and @code{fish}
shells.  (Contributed by Andrew Svetlov in bpo-15417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15417}.)

@ref{267,,EnvBuilder} and the @ref{268,,create()} convenience function
take a new keyword argument `with_pip', which defaults to @code{False}, that
controls whether or not @ref{267,,EnvBuilder} ensures that @code{pip} is
installed in the virtual environment.  (Contributed by Nick Coghlan in
bpo-19552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19552} as part of the 
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/} implementation.)

@node wave<2>,weakref<2>,venv<7>,Modules améliorés<10>
@anchor{whatsnew/3 4 wave}@anchor{fd3}
@subsubsection wave


The @code{getparams()} method now returns a namedtuple rather than a
plain tuple.  (Contributed by Claudiu Popa in bpo-17487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17487}.)

@ref{938,,wave.open()} now supports the context management protocol.  (Contributed
by Claudiu Popa in bpo-17616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17616}.)

@ref{112,,wave} can now @ref{fd4,,write output to unseekable files}.  (Contributed by David Jones, Guilherme Polo, and Serhiy
Storchaka in bpo-5202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5202}.)

The @ref{fd5,,writeframesraw()} and
@ref{fd6,,writeframes()} methods now accept any @ref{d1b,,bytes-like object}.  (Contributed by Serhiy Storchaka in bpo-8311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8311}.)

@node weakref<2>,xml etree<2>,wave<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 weakref}@anchor{fd7}
@subsubsection weakref


New @ref{fd8,,WeakMethod} class simulates weak references to bound
methods.  (Contributed by Antoine Pitrou in bpo-14631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14631}.)

New @ref{a6a,,finalize} class makes it possible to register a callback
to be invoked when an object is garbage collected, without needing to
carefully manage the lifecycle of the weak reference itself.  (Contributed by
Richard Oudkerk in bpo-15528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15528}.)

The callback, if any, associated with a @ref{fd9,,ref} is now
exposed via the @ref{fda,,__callback__} attribute.  (Contributed
by Mark Dickinson in bpo-17643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17643}.)

@node xml etree<2>,zipfile<5>,weakref<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 xml-etree}@anchor{fdb}
@subsubsection xml.etree


A new parser, @ref{fdc,,XMLPullParser}, allows a
non-blocking applications to parse XML documents.  An example can be
seen at @ref{fdd,,API à flux tiré}.  (Contributed by Antoine
Pitrou in bpo-17741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17741}.)

The @ref{124,,xml.etree.ElementTree} @ref{fde,,tostring()} and
@ref{fdf,,tostringlist()} functions, and the
@ref{93b,,ElementTree}
@ref{fe0,,write()} method, now have a
`short_empty_elements' @ref{2a2,,keyword-only parameter}
providing control over whether elements with no content are written in
abbreviated (@code{<tag />}) or expanded (@code{<tag></tag>}) form.  (Contributed by
Ariel Poliak and Serhiy Storchaka in bpo-14377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14377}.)

@node zipfile<5>,,xml etree<2>,Modules améliorés<10>
@anchor{whatsnew/3 4 zipfile}@anchor{fe1}
@subsubsection zipfile


The @ref{fe2,,writepy()} method of the
@ref{fe3,,PyZipFile} class has a new `filterfunc' option that can be
used to control which directories and files are added to the archive.  For
example, this could be used to exclude test files from the archive.
(Contributed by Christian Tismer in bpo-19274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19274}.)

The `allowZip64' parameter to @ref{6af,,ZipFile} and
@code{PyZipfile} is now @code{True} by default.  (Contributed by
William Mallard in bpo-17201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17201}.)

@node CPython Implementation Changes,Obsolescence<11>,Modules améliorés<10>,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 cpython-implementation-changes}@anchor{fe4}
@subsection CPython Implementation Changes


@menu
* PEP 445; Customization of CPython Memory Allocators: PEP 445 Customization of CPython Memory Allocators. 
* PEP 442; Safe Object Finalization: PEP 442 Safe Object Finalization. 
* PEP 456; Secure and Interchangeable Hash Algorithm: PEP 456 Secure and Interchangeable Hash Algorithm. 
* PEP 436; Argument Clinic: PEP 436 Argument Clinic. 
* Other Build and C API Changes:: 
* Autres Améliorations: Autres Améliorations<2>. 
* Significant Optimizations:: 

@end menu

@node PEP 445 Customization of CPython Memory Allocators,PEP 442 Safe Object Finalization,,CPython Implementation Changes
@anchor{whatsnew/3 4 pep-445-customization-of-cpython-memory-allocators}@anchor{fe5}@anchor{whatsnew/3 4 whatsnew-pep-445}@anchor{ed8}
@subsubsection PEP 445: Customization of CPython Memory Allocators


@geindex Python Enhancement Proposals; PEP 445
PEP 445@footnote{https://peps.python.org/pep-0445/} adds new C level interfaces to customize memory allocation in
the CPython interpreter.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 445

@item PEP 445@footnote{https://peps.python.org/pep-0445/} -- Add new APIs to customize Python memory allocators

PEP written and implemented by Victor Stinner.
@end table


@node PEP 442 Safe Object Finalization,PEP 456 Secure and Interchangeable Hash Algorithm,PEP 445 Customization of CPython Memory Allocators,CPython Implementation Changes
@anchor{whatsnew/3 4 pep-442-safe-object-finalization}@anchor{fe6}@anchor{whatsnew/3 4 whatsnew-pep-442}@anchor{ed7}
@subsubsection PEP 442: Safe Object Finalization


@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/} removes the current limitations and quirks of object finalization
in CPython. With it, objects with @code{__del__()} methods, as well as
generators with @ref{9b8,,finally} clauses, can be finalized when they are
part of a reference cycle.

As part of this change, module globals are no longer forcibly set to
@ref{660,,None} during interpreter shutdown in most cases, instead relying
on the normal operation of the cyclic garbage collector.  This avoids a
whole class of interpreter-shutdown-time errors, usually involving
@code{__del__} methods, that have plagued Python since the cyclic GC
was first introduced.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 442

@item PEP 442@footnote{https://peps.python.org/pep-0442/} -- Safe object finalization

PEP written and implemented by Antoine Pitrou.
@end table


@node PEP 456 Secure and Interchangeable Hash Algorithm,PEP 436 Argument Clinic,PEP 442 Safe Object Finalization,CPython Implementation Changes
@anchor{whatsnew/3 4 pep-456-secure-and-interchangeable-hash-algorithm}@anchor{fe7}@anchor{whatsnew/3 4 whatsnew-pep-456}@anchor{ed1}
@subsubsection PEP 456: Secure and Interchangeable Hash Algorithm


@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/} follows up on earlier security fix work done on Python's hash
algorithm to address certain DOS attacks to which public facing APIs backed by
dictionary lookups may be subject.  (See bpo-14621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14621} for the start of the
current round of improvements.)  The PEP unifies CPython's hash code to make it
easier for a packager to substitute a different hash algorithm, and switches
Python's default implementation to a SipHash implementation on platforms that
have a 64 bit data type.  Any performance differences in comparison with the
older FNV algorithm are trivial.

The PEP adds additional fields to the @ref{fe8,,sys.hash_info} named tuple to
describe the hash algorithm in use by the currently executing binary.  Otherwise,
the PEP does not alter any existing CPython APIs.

@node PEP 436 Argument Clinic,Other Build and C API Changes,PEP 456 Secure and Interchangeable Hash Algorithm,CPython Implementation Changes
@anchor{whatsnew/3 4 pep-436-argument-clinic}@anchor{fe9}@anchor{whatsnew/3 4 whatsnew-pep-436}@anchor{ed9}
@subsubsection PEP 436: Argument Clinic


"Argument Clinic" (
@geindex Python Enhancement Proposals; PEP 436
PEP 436@footnote{https://peps.python.org/pep-0436/}) is now part of the CPython build process
and can be used to simplify the process of defining and maintaining
accurate signatures for builtins and standard library extension modules
implemented in C.

Some standard library extension modules have been converted to use Argument
Clinic in Python 3.4, and @ref{b4,,pydoc} and @ref{7d,,inspect} have been updated
accordingly.

It is expected that signature metadata for programmatic introspection will
be added to additional callables implemented in C as part of Python 3.4
maintenance releases.

@cartouche
@quotation Note 
The Argument Clinic PEP is not fully up to date with the state of the
implementation. This has been deemed acceptable by the release manager
and core development team in this case, as Argument Clinic will not
be made available as a public API for third party use in Python 3.4.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 436

@item PEP 436@footnote{https://peps.python.org/pep-0436/} -- The Argument Clinic DSL

PEP written and implemented by Larry Hastings.
@end table


@node Other Build and C API Changes,Autres Améliorations<2>,PEP 436 Argument Clinic,CPython Implementation Changes
@anchor{whatsnew/3 4 other-build-and-c-api-changes}@anchor{fea}
@subsubsection Other Build and C API Changes



@itemize *

@item 
The new @ref{888,,PyType_GetSlot()} function has been added to the stable ABI,
allowing retrieval of function pointers from named type slots when using
the limited API.  (Contributed by Martin von Löwis in bpo-17162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17162}.)

@item 
The new @code{Py_SetStandardStreamEncoding()} pre-initialization API
allows applications embedding the CPython interpreter to reliably force
a particular encoding and error handler for the standard streams.
(Contributed by Bastien Montagne and Nick Coghlan in bpo-16129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16129}.)

@item 
Most Python C APIs that don't mutate string arguments are now correctly
marked as accepting @code{const char *} rather than @code{char *}.  (Contributed
by Serhiy Storchaka in bpo-1772673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1772673}.)

@item 
A new shell version of @code{python-config} can be used even when a python
interpreter is not available (for example, in cross compilation scenarios).

@item 
@ref{380,,PyUnicode_FromFormat()} now supports width and precision
specifications for @code{%s}, @code{%A}, @code{%U}, @code{%V}, @code{%S}, and @code{%R}.
(Contributed by Ysj Ray and Victor Stinner in bpo-7330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7330}.)

@item 
New function @ref{feb,,PyStructSequence_InitType2()} supplements the
existing @ref{fec,,PyStructSequence_InitType()} function.  The difference
is that it returns @code{0} on success and @code{-1} on failure.

@item 
The CPython source can now be compiled using the address sanity checking
features of recent versions of GCC and clang:  the false alarms in the small
object allocator have been silenced.  (Contributed by Dhiru Kholia in
bpo-18596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18596}.)

@item 
The Windows build now uses Address Space Layout Randomization@footnote{https://en.wikipedia.org/wiki/Address_space_layout_randomization} and Data Execution Prevention@footnote{https://en.wikipedia.org/wiki/Data_Execution_Prevention}.  (Contributed by
Christian Heimes in bpo-16632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16632}.)

@item 
New function @ref{fed,,PyObject_LengthHint()} is the C API equivalent
of @ref{f58,,operator.length_hint()}.  (Contributed by Armin Ronacher in
bpo-16148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16148}.)
@end itemize

@node Autres Améliorations<2>,Significant Optimizations,Other Build and C API Changes,CPython Implementation Changes
@anchor{whatsnew/3 4 other-improvements}@anchor{fee}@anchor{whatsnew/3 4 other-improvements-3-4}@anchor{fef}
@subsubsection Autres Améliorations

@anchor{whatsnew/3 4 whatsnew-isolated-mode}@anchor{ec2}

@itemize *

@item 
The @ref{ff0,,python} command has a new @ref{ff1,,option}, @code{-I}, which causes it to run in "isolated mode",
which means that @ref{3ab,,sys.path} contains neither the script's directory nor
the user's @code{site-packages} directory, and all @code{PYTHON*} environment
variables are ignored (it implies both @code{-s} and @code{-E}).  Other
restrictions may also be applied in the future, with the goal being to
isolate the execution of a script from the user's environment.  This is
appropriate, for example, when Python is used to run a system script.  On
most POSIX systems it can and should be used in the @code{#!} line of system
scripts.  (Contributed by Christian Heimes in bpo-16499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16499}.)

@item 
Tab-completion is now enabled by default in the interactive interpreter
on systems that support @ref{b9,,readline}.  History is also enabled by default,
and is written to (and read from) the file @code{~/.python-history}.
(Contributed by Antoine Pitrou and Éric Araujo in bpo-5845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5845}.)

@item 
Invoking the Python interpreter with @code{--version} now outputs the version to
standard output instead of standard error (bpo-18338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18338}). Similar changes
were made to @ref{6,,argparse} (bpo-18920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18920}) and other modules that have
script-like invocation capabilities (bpo-18922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18922}).

@item 
The CPython Windows installer now adds @code{.py} to the 
@geindex PATHEXT
@geindex variable d'environnement; PATHEXT
@code{PATHEXT}
variable when extensions are registered, allowing users to run a python
script at the windows command prompt by just typing its name without the
@code{.py} extension.  (Contributed by Paul Moore in bpo-18569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18569}.)

@item 
A new @code{make} target coverage-report@footnote{https://devguide.python.org/coverage/#measuring-coverage-of-c-code-with-gcov-and-lcov}
will build python, run the test suite, and generate an HTML coverage report
for the C codebase using @code{gcov} and lcov@footnote{https://github.com/linux-test-project/lcov}.

@item 
The @code{-R} option to the @ref{ff2,,python regression test suite} now
also checks for memory allocation leaks, using
@ref{fb0,,sys.getallocatedblocks()}.  (Contributed by Antoine Pitrou in
bpo-13390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13390}.)

@item 
@code{python -m} now works with namespace packages.

@item 
The @ref{d0,,stat} module is now implemented in C, which means it gets the
values for its constants from the C header files, instead of having the
values hard-coded in the python module as was previously the case.

@item 
Loading multiple python modules from a single OS module (@code{.so}, @code{.dll})
now works correctly (previously it silently returned the first python
module in the file).  (Contributed by Václav Šmilauer in bpo-16421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16421}.)

@item 
A new opcode, @code{LOAD_CLASSDEREF}, has been added to fix a bug in the
loading of free variables in class bodies that could be triggered by certain
uses of @ref{c4c,,__prepare__}.  (Contributed by Benjamin Peterson in
bpo-17853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17853}.)

@item 
A number of MemoryError-related crashes were identified and fixed by Victor
Stinner using his 
@geindex Python Enhancement Proposals; PEP 445
PEP 445@footnote{https://peps.python.org/pep-0445/}-based @code{pyfailmalloc} tool (bpo-18408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18408},
bpo-18520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18520}).

@item 
The @code{pyvenv} command now accepts a @code{--copies} option
to use copies rather than symlinks even on systems where symlinks are the
default.  (Contributed by Vinay Sajip in bpo-18807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18807}.)

@item 
The @code{pyvenv} command also accepts a @code{--without-pip}
option to suppress the otherwise-automatic bootstrapping of pip into
the virtual environment.  (Contributed by Nick Coghlan in bpo-19552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19552}
as part of the 
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/} implementation.)

@item 
The encoding name is now optional in the value set for the
@geindex PYTHONIOENCODING
@geindex variable d'environnement; PYTHONIOENCODING
@ref{ff3,,PYTHONIOENCODING} environment variable.  This makes it possible to
set just the error handler, without changing the default encoding.
(Contributed by Serhiy Storchaka in bpo-18818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18818}.)

@item 
The @ref{13,,bz2}, @ref{89,,lzma}, and @ref{66,,gzip} module @code{open} functions now
support @code{x} (exclusive creation) mode.  (Contributed by Tim Heaney and
Vajrasky Kok in bpo-19201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19201}, bpo-19222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19222}, and bpo-19223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19223}.)
@end itemize

@node Significant Optimizations,,Autres Améliorations<2>,CPython Implementation Changes
@anchor{whatsnew/3 4 significant-optimizations}@anchor{ff4}
@subsubsection Significant Optimizations



@itemize *

@item 
The UTF-32 decoder is now 3x to 4x faster.  (Contributed by Serhiy Storchaka
in bpo-14625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14625}.)

@item 
The cost of hash collisions for sets is now reduced.  Each hash table
probe now checks a series of consecutive, adjacent key/hash pairs before
continuing to make random probes through the hash table.  This exploits
cache locality to make collision resolution less expensive.
The collision resolution scheme can be described as a hybrid of linear
probing and open addressing.  The number of additional linear probes
defaults to nine.  This can be changed at compile-time by defining
LINEAR_PROBES to be any value.  Set LINEAR_PROBES=0 to turn-off
linear probing entirely.  (Contributed by Raymond Hettinger in
bpo-18771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18771}.)

@item 
The interpreter starts about 30% faster. A couple of measures lead to the
speedup. The interpreter loads fewer modules on startup, e.g. the @ref{b8,,re},
@ref{1d,,collections} and @ref{85,,locale} modules and their dependencies are no
longer imported by default. The marshal module has been improved to load
compiled Python code faster.  (Contributed by Antoine Pitrou, Christian
Heimes and Victor Stinner in bpo-19219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19219}, bpo-19218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19218}, bpo-19209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19209},
bpo-19205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19205} and bpo-9548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9548}.)

@item 
@ref{851,,bz2.BZ2File} is now as fast or faster than the Python2 version for
most cases.  @ref{ff5,,lzma.LZMAFile} has also been optimized.  (Contributed by
Serhiy Storchaka and Nadeem Vawda in bpo-16034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16034}.)

@item 
@ref{ff6,,random.getrandbits()} is 20%-40% faster for small integers (the most
common use case).  (Contributed by Serhiy Storchaka in bpo-16674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16674}.)

@item 
By taking advantage of the new storage format for strings, pickling of
strings is now significantly faster.  (Contributed by Victor Stinner and
Antoine Pitrou in bpo-15596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15596}.)

@item 
A performance issue in @code{io.FileIO.readall()} has been solved.  This
particularly affects Windows, and significantly speeds up the case of piping
significant amounts of data through @ref{d5,,subprocess}.  (Contributed
by Richard Oudkerk in bpo-15758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15758}.)

@item 
@ref{ff7,,html.escape()} is now 10x faster.  (Contributed by Matt Bryant in
bpo-18020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18020}.)

@item 
On Windows, the native @code{VirtualAlloc} is now used instead of the CRT
@code{malloc} in @code{obmalloc}.  Artificial benchmarks show about a 3% memory
savings.

@item 
@ref{50c,,os.urandom()} now uses a lazily opened persistent file descriptor
so as to avoid using many file descriptors when run in parallel from
multiple threads.  (Contributed by Antoine Pitrou in bpo-18756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18756}.)
@end itemize

@node Obsolescence<11>,Retraits<9>,CPython Implementation Changes,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 deprecated}@anchor{ff8}@anchor{whatsnew/3 4 deprecated-3-4}@anchor{ef1}
@subsection Obsolescence


This section covers various APIs and other features that have been deprecated
in Python 3.4, and will be removed in Python 3.5 or later.  In most (but not
all) cases, using the deprecated APIs will produce a @ref{1a3,,DeprecationWarning}
when the interpreter is run with deprecation warnings enabled (for example, by
using @code{-Wd}).

@menu
* Deprecations in the Python API:: 
* Fonctionnalités obsolètes:: 

@end menu

@node Deprecations in the Python API,Fonctionnalités obsolètes,,Obsolescence<11>
@anchor{whatsnew/3 4 deprecations-in-the-python-api}@anchor{ff9}
@subsubsection Deprecations in the Python API



@itemize *

@item 
As mentioned in @ref{ec4,,PEP 451; A ModuleSpec Type for the Import System}, a number of @ref{76,,importlib}
methods and functions are deprecated: @code{importlib.find_loader()} is
replaced by @ref{2cb,,importlib.util.find_spec()};
@code{importlib.machinery.PathFinder.find_module()} is replaced by
@ref{ffa,,importlib.machinery.PathFinder.find_spec()};
@code{importlib.abc.MetaPathFinder.find_module()} is replaced by
@ref{853,,importlib.abc.MetaPathFinder.find_spec()};
@code{importlib.abc.PathEntryFinder.find_loader()} and
@code{find_module()} are replaced by
@ref{857,,importlib.abc.PathEntryFinder.find_spec()}; all of the @code{@var{xxx}Loader} ABC
@code{load_module} methods (@code{importlib.abc.Loader.load_module()},
@code{importlib.abc.InspectLoader.load_module()},
@code{importlib.abc.FileLoader.load_module()},
@code{importlib.abc.SourceLoader.load_module()}) should no longer be
implemented, instead loaders should implement an
@code{exec_module} method
(@ref{855,,importlib.abc.Loader.exec_module()},
@ref{ffb,,importlib.abc.InspectLoader.exec_module()}
@ref{ffc,,importlib.abc.SourceLoader.exec_module()}) and let the import system
take care of the rest; and
@code{importlib.abc.Loader.module_repr()},
@code{importlib.util.module_for_loader()}, @code{importlib.util.set_loader()},
and @code{importlib.util.set_package()} are no longer needed because their
functions are now handled automatically by the import system.

@item 
The @code{imp} module is pending deprecation. To keep compatibility with
Python 2/3 code bases, the module's removal is currently not scheduled.

@item 
The @code{formatter} module is pending deprecation and is slated for removal
in Python 3.6.

@item 
@code{MD5} as the default `digestmod' for the @ref{a8d,,hmac.new()} function is
deprecated.  Python 3.6 will require an explicit digest name or constructor as
`digestmod' argument.

@item 
The internal @code{Netrc} class in the @ref{5d,,ftplib} module has been documented
as deprecated in its docstring for quite some time.  It now emits a
@ref{1a3,,DeprecationWarning} and will be removed completely in Python 3.5.

@item 
The undocumented `endtime' argument to @ref{cd2,,subprocess.Popen.wait()} should
not have been exposed and is hopefully not in use; it is deprecated and
will mostly likely be removed in Python 3.5.

@item 
The `strict' argument of @ref{862,,HTMLParser} is deprecated.

@item 
The @ref{aa,,plistlib} @code{readPlist()},
@code{writePlist()}, @code{readPlistFromBytes()}, and
@code{writePlistToBytes()} functions are deprecated in favor of the
corresponding new functions @ref{93c,,load()}, @ref{93e,,dump()},
@ref{93d,,loads()}, and @ref{93f,,dumps()}.  @code{Data()}
is deprecated in favor of just using the @ref{1bd,,bytes} constructor.

@item 
The @ref{da,,sysconfig} key @code{SO} is deprecated, it has been replaced by
@code{EXT_SUFFIX}.

@item 
The @code{U} mode accepted by various @code{open} functions is deprecated.
In Python3 it does not do anything useful, and should be replaced by
appropriate uses of @ref{7a5,,io.TextIOWrapper} (if needed) and its `newline'
argument.

@item 
The `parser' argument of @ref{270,,xml.etree.ElementTree.iterparse()} has
been deprecated, as has the `html' argument of
@ref{a42,,XMLParser()}.  To prepare for the removal of the
latter, all arguments to @code{XMLParser} should be passed by keyword.
@end itemize

@node Fonctionnalités obsolètes,,Deprecations in the Python API,Obsolescence<11>
@anchor{whatsnew/3 4 deprecated-features}@anchor{ffd}
@subsubsection Fonctionnalités obsolètes



@itemize *

@item 
Running @ref{ffe,,IDLE} with the @code{-n} flag (no subprocess) is deprecated.
However, the feature will not be removed until bpo-18823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18823} is resolved.

@item 
The site module adding a "site-python" directory to sys.path, if it
exists, is deprecated (bpo-19375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19375}).
@end itemize

@node Retraits<9>,Portage vers Python 3 4,Obsolescence<11>,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 removed}@anchor{fff}
@subsection Retraits


@menu
* Operating Systems No Longer Supported:: 
* API and Feature Removals: API and Feature Removals<5>. 
* Code Cleanups:: 

@end menu

@node Operating Systems No Longer Supported,API and Feature Removals<5>,,Retraits<9>
@anchor{whatsnew/3 4 operating-systems-no-longer-supported}@anchor{1000}
@subsubsection Operating Systems No Longer Supported


Support for the following operating systems has been removed from the source
and build tools:


@itemize *

@item 
OS/2 (bpo-16135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16135}).

@item 
Windows 2000 (changeset e52df05b496a).

@item 
Windows systems where @code{COMSPEC} points to @code{command.com} (bpo-14470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14470}).

@item 
VMS (bpo-16136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16136}).
@end itemize

@node API and Feature Removals<5>,Code Cleanups,Operating Systems No Longer Supported,Retraits<9>
@anchor{whatsnew/3 4 api-and-feature-removals}@anchor{1001}
@subsubsection API and Feature Removals


The following obsolete and previously deprecated APIs and features have been
removed:


@itemize *

@item 
The unmaintained @code{Misc/TextMate} and @code{Misc/vim} directories have been
removed (see the devguide@footnote{https://devguide.python.org}
for suggestions on what to use instead).

@item 
The @code{SO} makefile macro is removed (it was replaced by the
@code{SHLIB_SUFFIX} and @code{EXT_SUFFIX} macros) (bpo-16754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16754}).

@item 
The @code{PyThreadState.tick_counter} field has been removed; its value has
been meaningless since Python 3.2, when the "new GIL" was introduced
(bpo-19199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19199}).

@item 
@code{PyLoader} and @code{PyPycLoader} have been removed from @ref{76,,importlib}.
(Contributed by Taras Lyapun in bpo-15641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15641}.)

@item 
The `strict' argument to @ref{b2e,,HTTPConnection} and
@ref{b2f,,HTTPSConnection} has been removed.  HTTP 0.9-style
"Simple Responses" are no longer supported.

@item 
The deprecated @ref{fc3,,urllib.request.Request} getter and setter methods
@code{add_data}, @code{has_data}, @code{get_data}, @code{get_type}, @code{get_host},
@code{get_selector}, @code{set_proxy}, @code{get_origin_req_host}, and
@code{is_unverifiable} have been removed (use direct attribute access instead).

@item 
Support for loading the deprecated @code{TYPE_INT64} has been removed from
@ref{8c,,marshal}.  (Contributed by Dan Riti in bpo-15480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15480}.)

@item 
@ref{1ca,,inspect.Signature}: positional-only parameters are now required
to have a valid name.

@item 
@ref{609,,object.__format__()} no longer accepts non-empty format strings, it now
raises a @ref{522,,TypeError} instead.  Using a non-empty string has been
deprecated since Python 3.2.  This change has been made to prevent a
situation where previously working (but incorrect) code would start failing
if an object gained a __format__ method, which means that your code may now
raise a @ref{522,,TypeError} if you are using an @code{'s'} format code with objects
that do not have a __format__ method that handles it.  See bpo-7994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7994} for
background.

@item 
@code{difflib.SequenceMatcher.isbjunk()} and
@code{difflib.SequenceMatcher.isbpopular()} were deprecated in 3.2, and have
now been removed: use @code{x in sm.bjunk} and
@code{x in sm.bpopular}, where `sm' is a @ref{1002,,SequenceMatcher} object
(bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}).
@end itemize

@node Code Cleanups,,API and Feature Removals<5>,Retraits<9>
@anchor{whatsnew/3 4 code-cleanups}@anchor{1003}
@subsubsection Code Cleanups



@itemize *

@item 
The unused and undocumented internal @code{Scanner} class has been removed from
the @ref{b4,,pydoc} module.

@item 
The private and effectively unused @code{_gestalt} module has been removed,
along with the private @ref{a9,,platform} functions @code{_mac_ver_lookup},
@code{_mac_ver_gstalt}, and @code{_bcd2str}, which would only have ever been called
on badly broken OSX systems (see bpo-18393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18393}).

@item 
The hardcoded copies of certain @ref{d0,,stat} constants that were included in
the @ref{dd,,tarfile} module namespace have been removed.
@end itemize

@node Portage vers Python 3 4,Changed in 3 4 3,Retraits<9>,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 porting-to-python-3-4}@anchor{1004}
@subsection Portage vers Python 3.4


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Changes in 'python' Command Behavior: Changes in 'python' Command Behavior<2>. 
* Changements dans l'API Python: Changements dans l'API Python<10>. 
* Changements dans l'API C: Changements dans l'API C<8>. 

@end menu

@node Changes in 'python' Command Behavior<2>,Changements dans l'API Python<10>,,Portage vers Python 3 4
@anchor{whatsnew/3 4 changes-in-python-command-behavior}@anchor{1005}
@subsubsection Changes in 'python' Command Behavior



@itemize *

@item 
In a posix shell, setting the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment variable to
an empty value is equivalent to not setting it at all.  However, setting
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} to an empty value was `not' equivalent to not setting it
at all: setting 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} to an empty value was equivalent to
setting it to @code{.}, which leads to confusion when reasoning by analogy to
how 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} works.  The behavior now conforms to the posix convention
for 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}.

@item 
The [X refs, Y blocks] output of a debug (@code{--with-pydebug}) build of the
CPython interpreter is now off by default.  It can be re-enabled using the
@code{-X showrefcount} option.  (Contributed by Ezio Melotti in bpo-17323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17323}.)

@item 
The python command and most stdlib scripts (as well as @ref{6,,argparse}) now
output @code{--version} information to @code{stdout} instead of @code{stderr} (for
issue list see @ref{fef,,Autres Améliorations} above).
@end itemize

@node Changements dans l'API Python<10>,Changements dans l'API C<8>,Changes in 'python' Command Behavior<2>,Portage vers Python 3 4
@anchor{whatsnew/3 4 changes-in-the-python-api}@anchor{1007}
@subsubsection Changements dans l'API Python



@itemize *

@item 
The ABCs defined in @ref{77,,importlib.abc} now either raise the appropriate
exception or return a default value instead of raising
@ref{225,,NotImplementedError} blindly. This will only affect code calling
@ref{4c5,,super()} and falling through all the way to the ABCs. For compatibility,
catch both @ref{225,,NotImplementedError} or the appropriate exception as needed.

@item 
The module type now initializes the @ref{2d6,,__package__} and
@ref{2e0,,__loader__}
attributes to @code{None} by default. To determine if these attributes were set
in a backwards-compatible fashion, use e.g.
@code{getattr(module, '__loader__', None) is not None}.  (bpo-17115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17115}.)

@item 
@code{importlib.util.module_for_loader()} now sets @code{__loader__} and
@code{__package__} unconditionally to properly support reloading. If this is not
desired then you will need to set these attributes manually. You can use
@code{importlib.util.module_to_load()} for module management.

@item 
Import now resets relevant attributes (e.g. @code{__name__}, @code{__loader__},
@code{__package__}, @code{__file__}, @code{__cached__}) unconditionally when reloading.
Note that this restores a pre-3.3 behavior in that it means a module is
re-found when re-loaded (bpo-19413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19413}).

@item 
Frozen packages no longer set @code{__path__} to a list containing the package
name, they now set it to an empty list.  The previous behavior could cause
the import system to do the wrong thing on submodule imports if there was
also a directory with the same name as the frozen package.  The correct way
to determine if a module is a package or not is to use @code{hasattr(module,
'__path__')} (bpo-18065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18065}).

@item 
Frozen modules no longer define a @code{__file__} attribute. It's semantically
incorrect for frozen modules to set the attribute as they are not loaded from
any explicit location. If you must know that a module comes from frozen code
then you can see if the module's @code{__spec__.location} is set to @code{'frozen'},
check if the loader is a subclass of
@ref{1008,,importlib.machinery.FrozenImporter},
or if Python 2 compatibility is necessary you can use @code{imp.is_frozen()}.

@item 
@ref{a13,,py_compile.compile()} now raises @ref{1009,,FileExistsError} if the file path
it would write to is a symlink or a non-regular file. This is to act as a
warning that import will overwrite those files with a regular file regardless
of what type of file path they were originally.

@item 
@ref{100a,,importlib.abc.SourceLoader.get_source()} no longer raises
@ref{40f,,ImportError} when the source code being loaded triggers a
@ref{18b,,SyntaxError} or @ref{a01,,UnicodeDecodeError}. As @ref{40f,,ImportError} is
meant to be raised only when source code cannot be found but it should, it was
felt to be over-reaching/overloading of that meaning when the source code is
found but improperly structured. If you were catching ImportError before and
wish to continue to ignore syntax or decoding issues, catch all three
exceptions now.

@item 
@ref{100b,,functools.update_wrapper()} and @ref{f48,,functools.wraps()} now correctly
set the @code{__wrapped__} attribute to the function being wrapped, even if
that function also had its @code{__wrapped__} attribute set. This means
@code{__wrapped__} attributes now correctly link a stack of decorated
functions rather than every @code{__wrapped__} attribute in the chain
referring to the innermost function. Introspection libraries that
assumed the previous behaviour was intentional can use
@ref{f47,,inspect.unwrap()} to access the first function in the chain that has
no @code{__wrapped__} attribute.

@item 
@ref{723,,inspect.getfullargspec()} has been reimplemented on top of
@ref{722,,inspect.signature()} and hence handles a much wider variety of callable
objects than it did in the past. It is expected that additional builtin and
extension module callables will gain signature metadata over the course of
the Python 3.4 series. Code that assumes that
@ref{723,,inspect.getfullargspec()} will fail on non-Python callables may need
to be adjusted accordingly.

@item 
@ref{100c,,importlib.machinery.PathFinder} now passes on the current working
directory to objects in @ref{100d,,sys.path_hooks} for the empty string. This
results in @ref{5ce,,sys.path_importer_cache} never containing @code{'@w{'}}, thus
iterating through @ref{5ce,,sys.path_importer_cache} based on @ref{3ab,,sys.path}
will not find all keys. A module's @code{__file__} when imported in the current
working directory will also now have an absolute path, including when using
@code{-m} with the interpreter (except for @code{__main__.__file__} when a script
has been executed directly using a relative path) (Contributed by Brett
Cannon in bpo-18416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18416}).  is specified on the command-line)
(bpo-18416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18416}).

@item 
The removal of the `strict' argument to @ref{b2e,,HTTPConnection}
and @ref{b2f,,HTTPSConnection} changes the meaning of the
remaining arguments if you are specifying them positionally rather than by
keyword.  If you've been paying attention to deprecation warnings your code
should already be specifying any additional arguments via keywords.

@item 
Strings between @code{from __future__ import ...} statements now `always' raise
a @ref{18b,,SyntaxError}.  Previously if there was no leading docstring, an
interstitial string would sometimes be ignored.  This brings CPython into
compliance with the language spec; Jython and PyPy already were.
(bpo-17434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17434}).

@item 
@ref{fa2,,ssl.SSLSocket.getpeercert()} and @ref{e56,,ssl.SSLSocket.do_handshake()}
now raise an @ref{40d,,OSError} with @code{ENOTCONN} when the @code{SSLSocket} is not
connected, instead of the previous behavior of raising an
@ref{343,,AttributeError}.  In addition, @ref{fa2,,getpeercert()}
will raise a @ref{1ff,,ValueError} if the handshake has not yet been done.

@item 
@ref{100e,,base64.b32decode()} now raises a @ref{100f,,binascii.Error} when the
input string contains non-b32-alphabet characters, instead of a
@ref{522,,TypeError}.  This particular @ref{522,,TypeError} was missed when the other
@ref{522,,TypeError}s were converted.  (Contributed by Serhiy Storchaka in
bpo-18011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18011}.)  Note: this change was also inadvertently applied in Python
3.3.3.

@item 
The @code{file} attribute is now automatically closed when
the creating @code{cgi.FieldStorage} instance is garbage collected. If you
were pulling the file object out separately from the @code{cgi.FieldStorage}
instance and not keeping the instance alive, then you should either store the
entire @code{cgi.FieldStorage} instance or read the contents of the file
before the @code{cgi.FieldStorage} instance is garbage collected.

@item 
Calling @code{read} or @code{write} on a closed SSL socket now raises an
informative @ref{1ff,,ValueError} rather than the previous more mysterious
@ref{343,,AttributeError} (bpo-9177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9177}).

@item 
@ref{1010,,slice.indices()} no longer produces an @ref{86d,,OverflowError} for huge
values.  As a consequence of this fix, @ref{1010,,slice.indices()} now raises a
@ref{1ff,,ValueError} if given a negative length; previously it returned nonsense
values (bpo-14794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14794}).

@item 
The @ref{2ec,,complex} constructor, unlike the @ref{18,,cmath} functions, was
incorrectly accepting @ref{2eb,,float} values if an object's @code{__complex__}
special method returned one.  This now raises a @ref{522,,TypeError}.
(bpo-16290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16290}.)

@item 
The @ref{254,,int} constructor in 3.2 and 3.3 erroneously accepts @ref{2eb,,float}
values for the `base' parameter.  It is unlikely anyone was doing this, but
if so, it will now raise a @ref{522,,TypeError} (bpo-16772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16772}).

@item 
Defaults for keyword-only arguments are now evaluated `after' defaults for
regular keyword arguments, instead of before.  Hopefully no one wrote any
code that depends on the previous buggy behavior (bpo-16967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16967}).

@item 
Stale thread states are now cleared after @ref{195,,fork()}.  This may cause
some system resources to be released that previously were incorrectly kept
perpetually alive (for example, database connections kept in thread-local
storage).  (bpo-17094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17094}.)

@item 
Parameter names in @code{__annotations__} dicts are now mangled properly,
similarly to @ref{1011,,__kwdefaults__}.
(Contributed by Yury Selivanov in bpo-20625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20625}.)

@item 
@ref{f33,,hashlib.hash.name} now always returns the identifier in lower case.
Previously some builtin hashes had uppercase names, but now that it is a
formal public interface the naming has been made consistent (bpo-18532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18532}).

@item 
Because @ref{de1,,unittest.TestSuite} now drops references to tests after they
are run, test harnesses that reuse a @ref{de1,,TestSuite} to re-run
a set of tests may fail.   Test suites should not be re-used in this fashion
since it means state is retained between test runs, breaking the test
isolation that @ref{105,,unittest} is designed to provide.  However, if the lack
of isolation is considered acceptable, the old behavior can be restored by
creating a @ref{de1,,TestSuite} subclass that defines a
@code{_removeTestAtIndex} method that does nothing (see
@ref{1012,,TestSuite.__iter__()}) (bpo-11798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11798}).

@item 
@ref{105,,unittest} now uses @ref{6,,argparse} for command line parsing.  There are
certain invalid command forms that used to work that are no longer allowed;
in theory this should not cause backward compatibility issues since the
disallowed command forms didn't make any sense and are unlikely to be in use.

@item 
The @ref{29f,,re.split()}, @ref{1013,,re.findall()}, and @ref{2a0,,re.sub()} functions, and
the @code{group()} and @code{groups()} methods of
@code{match} objects now always return a `bytes' object when the string
to be matched is a @ref{d1b,,bytes-like object}.  Previously the return type
matched the input type, so if your code was depending on the return value
being, say, a @code{bytearray}, you will need to change your code.

@item 
@code{audioop} functions now raise an error immediately if passed string
input, instead of failing randomly later on (bpo-16685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16685}).

@item 
The new `convert_charrefs' argument to @ref{862,,HTMLParser}
currently defaults to @code{False} for backward compatibility, but will
eventually be changed to default to @code{True}.  It is recommended that you add
this keyword, with the appropriate value, to any
@ref{862,,HTMLParser} calls in your code (bpo-13633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13633}).

@item 
Since the `digestmod' argument to the @ref{a8d,,hmac.new()} function will in the
future have no default, all calls to @ref{a8d,,hmac.new()} should be changed to
explicitly specify a `digestmod' (bpo-17276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17276}).

@item 
Calling @ref{1014,,sysconfig.get_config_var()} with the @code{SO} key, or looking
@code{SO} up in the results of a call to @ref{1015,,sysconfig.get_config_vars()}
is deprecated.  This key should be replaced by @code{EXT_SUFFIX} or
@code{SHLIB_SUFFIX}, depending on the context (bpo-19555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19555}).

@item 
Any calls to @code{open} functions that specify @code{U} should be modified.
@code{U} is ineffective in Python3 and will eventually raise an error if used.
Depending on the function, the equivalent of its old Python2 behavior can be
achieved using either a `newline' argument, or if necessary by wrapping the
stream in @ref{7a5,,TextIOWrapper} to use its `newline' argument
(bpo-15204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15204}).

@item 
If you use @code{pyvenv} in a script and desire that pip
`not' be installed, you must add @code{--without-pip} to your command
invocation.

@item 
The default behavior of @ref{d32,,json.dump()} and @ref{d33,,json.dumps()} when
an indent is specified has changed: it no longer produces trailing
spaces after the item separating commas at the ends of lines.  This
will matter only if you have tests that are doing white-space-sensitive
comparisons of such output (bpo-16333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16333}).

@item 
@ref{3a,,doctest} now looks for doctests in extension module @code{__doc__}
strings, so if your doctest test discovery includes extension modules that
have things that look like doctests in them you may see test failures you've
never seen before when running your tests (bpo-3158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3158}).

@item 
The @ref{1e,,collections.abc} module has been slightly refactored as
part of the Python startup improvements.  As a consequence of this, it is no
longer the case that importing @ref{1d,,collections} automatically imports
@ref{1e,,collections.abc}.  If your program depended on the (undocumented)
implicit import, you will need to add an explicit @code{import collections.abc}
(bpo-20784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20784}).
@end itemize

@node Changements dans l'API C<8>,,Changements dans l'API Python<10>,Portage vers Python 3 4
@anchor{whatsnew/3 4 changes-in-the-c-api}@anchor{1016}
@subsubsection Changements dans l'API C



@itemize *

@item 
@ref{1017,,PyEval_EvalFrameEx()}, @ref{1018,,PyObject_Repr()}, and
@ref{1019,,PyObject_Str()}, along with some other internal C APIs, now include
a debugging assertion that ensures they are not used in situations where
they may silently discard a currently active exception. In cases where
discarding the active exception is expected and desired (for example,
because it has already been saved locally with @ref{3e9,,PyErr_Fetch()} or
is being deliberately replaced with a different exception), an explicit
@ref{101a,,PyErr_Clear()} call will be needed to avoid triggering the
assertion when invoking these operations (directly or indirectly) and
running against a version of Python that is compiled with assertions
enabled.

@item 
@ref{d2c,,PyErr_SetImportError()} now sets @ref{522,,TypeError} when its `msg'
argument is not set. Previously only @code{NULL} was returned with no exception
set.

@item 
The result of the @ref{572,,PyOS_ReadlineFunctionPointer} callback must
now be a string allocated by @ref{386,,PyMem_RawMalloc()} or
@ref{388,,PyMem_RawRealloc()}, or @code{NULL} if an error occurred, instead of a
string allocated by @ref{c54,,PyMem_Malloc()} or @ref{101b,,PyMem_Realloc()}
(bpo-16742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16742})

@item 
@ref{3fe,,PyThread_set_key_value()} now always set the value. In Python
3.3, the function did nothing if the key already exists (if the current
value is a non-@code{NULL} pointer).

@item 
The @code{f_tstate} (thread state) field of the @ref{773,,PyFrameObject}
structure has been removed to fix a bug: see bpo-14432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14432} for the
rationale.
@end itemize

@node Changed in 3 4 3,,Portage vers Python 3 4,Nouveautés de Python 3 4
@anchor{whatsnew/3 4 changed-in-3-4-3}@anchor{101c}
@subsection Changed in 3.4.3


@menu
* PEP 476; Enabling certificate verification by default for stdlib http clients: PEP 476 Enabling certificate verification by default for stdlib http clients. 

@end menu

@node PEP 476 Enabling certificate verification by default for stdlib http clients,,,Changed in 3 4 3
@anchor{whatsnew/3 4 pep-476}@anchor{101d}@anchor{whatsnew/3 4 pep-476-enabling-certificate-verification-by-default-for-stdlib-http-clients}@anchor{101e}
@subsubsection PEP 476: Enabling certificate verification by default for stdlib http clients


@ref{6e,,http.client} and modules which use it, such as @ref{10a,,urllib.request} and
@ref{12d,,xmlrpc.client}, will now verify that the server presents a certificate
which is signed by a CA in the platform trust store and whose hostname matches
the hostname being requested by default, significantly improving security for
many applications.

For applications which require the old previous behavior, they can pass an
alternate context:

@example
import urllib.request
import ssl

# This disables all verification
context = ssl._create_unverified_context()

# This allows using a specific certificate for the host, which doesn't need
# to be in the trust store
context = ssl.create_default_context(cafile="/path/to/file.crt")

urllib.request.urlopen("https://invalid-cert", context=context)
@end example

@node Nouveautés de Python 3 3,Nouveautés de Python 3 2,Nouveautés de Python 3 4,Nouveautés de Python
@anchor{whatsnew/3 3 doc}@anchor{101f}@anchor{whatsnew/3 3 what-s-new-in-python-3-3}@anchor{1020}
@section Nouveautés de Python 3.3


@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer in :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the Mercurial log
@c when researching a change.

This article explains the new features in Python 3.3, compared to 3.2.
Python 3.3 was released on September 29, 2012.  For full details,
see the changelog@footnote{https://docs.python.org/3.3/whatsnew/changelog.html}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 398
PEP 398@footnote{https://peps.python.org/pep-0398/} - Python 3.3 Release Schedule


@menu
* Résumé – Points forts de la publication: Résumé – Points forts de la publication<5>. 
* PEP 405; Virtual Environments: PEP 405 Virtual Environments. 
* PEP 420; Implicit Namespace Packages: PEP 420 Implicit Namespace Packages. 
* PEP 3118; New memoryview implementation and buffer protocol documentation: PEP 3118 New memoryview implementation and buffer protocol documentation. 
* PEP 393; Flexible String Representation: PEP 393 Flexible String Representation. 
* PEP 397; Python Launcher for Windows: PEP 397 Python Launcher for Windows. 
* PEP 3151; Reworking the OS and IO exception hierarchy: PEP 3151 Reworking the OS and IO exception hierarchy. 
* PEP 380; Syntax for Delegating to a Subgenerator: PEP 380 Syntax for Delegating to a Subgenerator. 
* PEP 409; Suppressing exception context: PEP 409 Suppressing exception context. 
* PEP 414; Explicit Unicode literals: PEP 414 Explicit Unicode literals. 
* PEP 3155; Qualified name for classes and functions: PEP 3155 Qualified name for classes and functions. 
* PEP 412; Key-Sharing Dictionary: PEP 412 Key-Sharing Dictionary. 
* PEP 362; Function Signature Object: PEP 362 Function Signature Object. 
* PEP 421; Adding sys.implementation: PEP 421 Adding sys implementation. 
* Using importlib as the Implementation of Import:: 
* Autres changements au langage: Autres changements au langage<11>. 
* A Finer-Grained Import Lock:: 
* Builtin functions and types:: 
* Nouveaux modules: Nouveaux modules<11>. 
* Modules améliorés: Modules améliorés<11>. 
* Optimizations: Optimizations<5>. 
* Build and C API Changes: Build and C API Changes<4>. 
* Obsolescence: Obsolescence<12>. 
* Portage vers Python 3.3: Portage vers Python 3 3. 

@end menu

@node Résumé – Points forts de la publication<5>,PEP 405 Virtual Environments,,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 summary-release-highlights}@anchor{1021}
@subsection Résumé – Points forts de la publication


@c This section singles out the most important changes in Python 3.3.
@c Brevity is key.

Nouvelles fonctionnalités de syntaxe :


@itemize *

@item 
New @code{yield from} expression for @ref{1022,,generator delegation}.

@item 
The @code{u'unicode'} syntax is accepted again for @ref{435,,str} objects.
@end itemize

Nouveaux modules de la bibliothèque :


@itemize *

@item 
@ref{57,,faulthandler} (helps debugging low-level crashes)

@item 
@ref{7f,,ipaddress} (high-level objects representing IP addresses and masks)

@item 
@ref{89,,lzma} (compress data using the XZ / LZMA algorithm)

@item 
@ref{106,,unittest.mock} (replace parts of your system under test with mock objects)

@item 
@ref{110,,venv} (Python @ref{1023,,virtual environments}, as in the
popular @code{virtualenv} package)
@end itemize

Nouvelles fonctionnalités natives :


@itemize *

@item 
Reworked @ref{1024,,I/O exception hierarchy}.
@end itemize

Implementation improvements:


@itemize *

@item 
Rewritten @ref{1025,,import machinery} based on @ref{76,,importlib}.

@item 
More compact @ref{1026,,unicode strings}.

@item 
More compact @ref{1027,,attribute dictionaries}.
@end itemize

Significantly Improved Library Modules:


@itemize *

@item 
C Accelerator for the @ref{1028,,decimal} module.

@item 
Better unicode handling in the @ref{1029,,email} module
(@ref{102a,,provisional}).
@end itemize

Security improvements:


@itemize *

@item 
Hash randomization is switched on by default.
@end itemize

Please read on for a comprehensive list of user-facing changes.

@node PEP 405 Virtual Environments,PEP 420 Implicit Namespace Packages,Résumé – Points forts de la publication<5>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-405}@anchor{1023}@anchor{whatsnew/3 3 pep-405-virtual-environments}@anchor{102b}
@subsection PEP 405: Virtual Environments


Virtual environments help create separate Python setups while sharing a
system-wide base install, for ease of maintenance.  Virtual environments
have their own set of private site packages (i.e. locally installed
libraries), and are optionally segregated from the system-wide site
packages.  Their concept and implementation are inspired by the popular
@code{virtualenv} third-party package, but benefit from tighter integration
with the interpreter core.

This PEP adds the @ref{110,,venv} module for programmatic access, and the
@code{pyvenv} script for command-line access and
administration.  The Python interpreter checks for a @code{pyvenv.cfg},
file whose existence signals the base of a virtual environment's directory
tree.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 405

@item PEP 405@footnote{https://peps.python.org/pep-0405/} - Python Virtual Environments

PEP written by Carl Meyer; implementation by Carl Meyer and Vinay Sajip
@end table


@node PEP 420 Implicit Namespace Packages,PEP 3118 New memoryview implementation and buffer protocol documentation,PEP 405 Virtual Environments,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-420-implicit-namespace-packages}@anchor{102c}
@subsection PEP 420: Implicit Namespace Packages


Native support for package directories that don't require @code{__init__.py}
marker files and can automatically span multiple path segments (inspired by
various third party approaches to namespace packages, as described in
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/})


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 420

@item PEP 420@footnote{https://peps.python.org/pep-0420/} - Implicit Namespace Packages

PEP written by Eric V. Smith; implementation by Eric V. Smith
and Barry Warsaw
@end table


@node PEP 3118 New memoryview implementation and buffer protocol documentation,PEP 393 Flexible String Representation,PEP 420 Implicit Namespace Packages,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-3118-new-memoryview-implementation-and-buffer-protocol-documentation}@anchor{102d}@anchor{whatsnew/3 3 pep-3118-update}@anchor{102e}
@subsection PEP 3118: New memoryview implementation and buffer protocol documentation


The implementation of 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} has been significantly improved.

The new memoryview implementation comprehensively fixes all ownership and
lifetime issues of dynamically allocated fields in the Py_buffer struct
that led to multiple crash reports. Additionally, several functions that
crashed or returned incorrect results for non-contiguous or multi-dimensional
input have been fixed.

The memoryview object now has a PEP-3118 compliant getbufferproc()
that checks the consumer's request type. Many new features have been
added, most of them work in full generality for non-contiguous arrays
and arrays with suboffsets.

The documentation has been updated, clearly spelling out responsibilities
for both exporters and consumers. Buffer request flags are grouped into
basic and compound flags. The memory layout of non-contiguous and
multi-dimensional NumPy-style arrays is explained.

@menu
* Caractéristiques:: 
* API changes:: 

@end menu

@node Caractéristiques,API changes,,PEP 3118 New memoryview implementation and buffer protocol documentation
@anchor{whatsnew/3 3 features}@anchor{102f}
@subsubsection Caractéristiques



@itemize *

@item 
All native single character format specifiers in struct module syntax
(optionally prefixed with '@@') are now supported.

@item 
With some restrictions, the cast() method allows changing of format and
shape of C-contiguous arrays.

@item 
Multi-dimensional list representations are supported for any array type.

@item 
Multi-dimensional comparisons are supported for any array type.

@item 
One-dimensional memoryviews of hashable (read-only) types with formats B,
b or c are now hashable.  (Contributed by Antoine Pitrou in bpo-13411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13411}.)

@item 
Arbitrary slicing of any 1-D arrays type is supported. For example, it
is now possible to reverse a memoryview in `O'(1) by using a negative step.
@end itemize

@node API changes,,Caractéristiques,PEP 3118 New memoryview implementation and buffer protocol documentation
@anchor{whatsnew/3 3 api-changes}@anchor{1030}
@subsubsection API changes



@itemize *

@item 
The maximum number of dimensions is officially limited to 64.

@item 
The representation of empty shape, strides and suboffsets is now
an empty tuple instead of @code{None}.

@item 
Accessing a memoryview element with format 'B' (unsigned bytes)
now returns an integer (in accordance with the struct module syntax).
For returning a bytes object the view must be cast to 'c' first.

@item 
memoryview comparisons now use the logical structure of the operands
and compare all array elements by value. All format strings in struct
module syntax are supported. Views with unrecognised format strings
are still permitted, but will always compare as unequal, regardless
of view contents.

@item 
For further changes see @ref{1031,,Build and C API Changes} and @ref{1032,,Porting C code}.
@end itemize

(Contribution par Stefan Krah; bpo-10181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10181}.)


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} - Revising the Buffer Protocol


@node PEP 393 Flexible String Representation,PEP 397 Python Launcher for Windows,PEP 3118 New memoryview implementation and buffer protocol documentation,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-393}@anchor{1026}@anchor{whatsnew/3 3 pep-393-flexible-string-representation}@anchor{1033}
@subsection PEP 393: Flexible String Representation


The Unicode string type is changed to support multiple internal
representations, depending on the character with the largest Unicode ordinal
(1, 2, or 4 bytes) in the represented string.  This allows a space-efficient
representation in common cases, but gives access to full UCS-4 on all
systems.  For compatibility with existing APIs, several representations may
exist in parallel; over time, this compatibility should be phased out.

On the Python side, there should be no downside to this change.

On the C API side, 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} is fully backward compatible.  The legacy API
should remain available at least five years.  Applications using the legacy
API will not fully benefit of the memory reduction, or - worse - may use
a bit more memory, because Python may have to maintain two versions of each
string (in the legacy format and in the new efficient storage).

@menu
* Functionality:: 
* Performance and resource usage:: 

@end menu

@node Functionality,Performance and resource usage,,PEP 393 Flexible String Representation
@anchor{whatsnew/3 3 functionality}@anchor{1034}
@subsubsection Functionality


Changes introduced by 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} are the following:


@itemize *

@item 
Python now always supports the full range of Unicode code points, including
non-BMP ones (i.e. from @code{U+0000} to @code{U+10FFFF}).  The distinction between
narrow and wide builds no longer exists and Python now behaves like a wide
build, even under Windows.

@item 
With the death of narrow builds, the problems specific to narrow builds have
also been fixed, for example:


@itemize *

@item 
@ref{619,,len()} now always returns 1 for non-BMP characters,
so @code{len('\U0010FFFF') == 1};

@item 
surrogate pairs are not recombined in string literals,
so @code{'\uDBFF\uDFFF' != '\U0010FFFF'};

@item 
indexing or slicing non-BMP characters returns the expected value,
so @code{'\U0010FFFF'[0]} now returns @code{'\U0010FFFF'} and not @code{'\uDBFF'};

@item 
all other functions in the standard library now correctly handle
non-BMP code points.
@end itemize

@item 
The value of @ref{1035,,sys.maxunicode} is now always @code{1114111} (@code{0x10FFFF}
in hexadecimal).  The @code{PyUnicode_GetMax()} function still returns
either @code{0xFFFF} or @code{0x10FFFF} for backward compatibility, and it should
not be used with the new Unicode API (see bpo-13054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13054}).

@item 
The @code{./configure} flag @code{--with-wide-unicode} has been removed.
@end itemize

@node Performance and resource usage,,Functionality,PEP 393 Flexible String Representation
@anchor{whatsnew/3 3 performance-and-resource-usage}@anchor{1036}
@subsubsection Performance and resource usage


The storage of Unicode strings now depends on the highest code point in the string:


@itemize *

@item 
pure ASCII and Latin1 strings (@code{U+0000-U+00FF}) use 1 byte per code point;

@item 
BMP strings (@code{U+0000-U+FFFF}) use 2 bytes per code point;

@item 
non-BMP strings (@code{U+10000-U+10FFFF}) use 4 bytes per code point.
@end itemize

The net effect is that for most applications, memory usage of string
storage should decrease significantly - especially compared to former
wide unicode builds - as, in many cases, strings will be pure ASCII
even in international contexts (because many strings store non-human
language data, such as XML fragments, HTTP headers, JSON-encoded data,
etc.).  We also hope that it will, for the same reasons, increase CPU
cache efficiency on non-trivial applications. The memory usage of
Python 3.3 is two to three times smaller than Python 3.2, and a little
bit better than Python 2.7, on a Django benchmark (see the PEP for
details).


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 393

@item PEP 393@footnote{https://peps.python.org/pep-0393/} - Flexible String Representation

PEP written by Martin von Löwis; implementation by Torsten Becker
and Martin von Löwis.
@end table


@node PEP 397 Python Launcher for Windows,PEP 3151 Reworking the OS and IO exception hierarchy,PEP 393 Flexible String Representation,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-397}@anchor{1037}@anchor{whatsnew/3 3 pep-397-python-launcher-for-windows}@anchor{1038}
@subsection PEP 397: Python Launcher for Windows


The Python 3.3 Windows installer now includes a @code{py} launcher application
that can be used to launch Python applications in a version independent
fashion.

This launcher is invoked implicitly when double-clicking @code{*.py} files.
If only a single Python version is installed on the system, that version
will be used to run the file. If multiple versions are installed, the most
recent version is used by default, but this can be overridden by including
a Unix-style "shebang line" in the Python script.

The launcher can also be used explicitly from the command line as the @code{py}
application. Running @code{py} follows the same version selection rules as
implicitly launching scripts, but a more specific version can be selected
by passing appropriate arguments (such as @code{-3} to request Python 3 when
Python 2 is also installed, or @code{-2.6} to specifically request an earlier
Python version when a more recent version is installed).

In addition to the launcher, the Windows installer now includes an
option to add the newly installed Python to the system PATH.  (Contributed
by Brian Curtin in bpo-3561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3561}.)


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 397

@item PEP 397@footnote{https://peps.python.org/pep-0397/} - Python Launcher for Windows

PEP written by Mark Hammond and Martin v. Löwis; implementation by
Vinay Sajip.
@end table

Launcher documentation: @ref{5a8,,Lanceur Python pour Windows}

Installer PATH modification: @ref{1039,,Trouver l'exécutable Python}


@node PEP 3151 Reworking the OS and IO exception hierarchy,PEP 380 Syntax for Delegating to a Subgenerator,PEP 397 Python Launcher for Windows,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-3151}@anchor{1024}@anchor{whatsnew/3 3 pep-3151-reworking-the-os-and-io-exception-hierarchy}@anchor{103a}
@subsection PEP 3151: Reworking the OS and IO exception hierarchy


The hierarchy of exceptions raised by operating system errors is now both
simplified and finer-grained.

You don't have to worry anymore about choosing the appropriate exception
type between @ref{40d,,OSError}, @ref{103b,,IOError}, @ref{103c,,EnvironmentError},
@ref{103d,,WindowsError}, @code{mmap.error}, @ref{103e,,socket.error} or
@ref{103f,,select.error}.  All these exception types are now only one:
@ref{40d,,OSError}.  The other names are kept as aliases for compatibility
reasons.

Also, it is now easier to catch a specific error condition.  Instead of
inspecting the @code{errno} attribute (or @code{args[0]}) for a particular
constant from the @ref{56,,errno} module, you can catch the adequate
@ref{40d,,OSError} subclass.  The available subclasses are the following:


@itemize *

@item 
@ref{1040,,BlockingIOError}

@item 
@ref{1041,,ChildProcessError}

@item 
@ref{df7,,ConnectionError}

@item 
@ref{1009,,FileExistsError}

@item 
@ref{eae,,FileNotFoundError}

@item 
@ref{d75,,InterruptedError}

@item 
@ref{1042,,IsADirectoryError}

@item 
@ref{1043,,NotADirectoryError}

@item 
@ref{d30,,PermissionError}

@item 
@ref{1044,,ProcessLookupError}

@item 
@ref{81f,,TimeoutError}
@end itemize

And the @ref{df7,,ConnectionError} itself has finer-grained subclasses:


@itemize *

@item 
@ref{1045,,BrokenPipeError}

@item 
@ref{1046,,ConnectionAbortedError}

@item 
@ref{1047,,ConnectionRefusedError}

@item 
@ref{1048,,ConnectionResetError}
@end itemize

Thanks to the new exceptions, common usages of the @ref{56,,errno} can now be
avoided.  For example, the following code written for Python 3.2:

@example
from errno import ENOENT, EACCES, EPERM

try:
    with open("document.txt") as f:
        content = f.read()
except IOError as err:
    if err.errno == ENOENT:
        print("document.txt file is missing")
    elif err.errno in (EACCES, EPERM):
        print("You are not allowed to read document.txt")
    else:
        raise
@end example

can now be written without the @ref{56,,errno} import and without manual
inspection of exception attributes:

@example
try:
    with open("document.txt") as f:
        content = f.read()
except FileNotFoundError:
    print("document.txt file is missing")
except PermissionError:
    print("You are not allowed to read document.txt")
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3151

@item PEP 3151@footnote{https://peps.python.org/pep-3151/} - Reworking the OS and IO Exception Hierarchy

PEP written and implemented by Antoine Pitrou
@end table


@geindex yield;yield from (in What's New)

@node PEP 380 Syntax for Delegating to a Subgenerator,PEP 409 Suppressing exception context,PEP 3151 Reworking the OS and IO exception hierarchy,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-380}@anchor{1022}@anchor{whatsnew/3 3 pep-380-syntax-for-delegating-to-a-subgenerator}@anchor{1049}
@subsection PEP 380: Syntax for Delegating to a Subgenerator


PEP 380 adds the @code{yield from} expression, allowing a @ref{104a,,generator} to
delegate
part of its operations to another generator. This allows a section of code
containing @ref{9bb,,yield} to be factored out and placed in another generator.
Additionally, the subgenerator is allowed to return with a value, and the
value is made available to the delegating generator.

While designed primarily for use in delegating to a subgenerator, the @code{yield
from} expression actually allows delegation to arbitrary subiterators.

For simple iterators, @code{yield from iterable} is essentially just a shortened
form of @code{for item in iterable: yield item}:

@example
>>> def g(x):
...     yield from range(x, 0, -1)
...     yield from range(x)
...
>>> list(g(5))
[5, 4, 3, 2, 1, 0, 1, 2, 3, 4]
@end example

However, unlike an ordinary loop, @code{yield from} allows subgenerators to
receive sent and thrown values directly from the calling scope, and
return a final value to the outer generator:

@example
>>> def accumulate():
...     tally = 0
...     while 1:
...         next = yield
...         if next is None:
...             return tally
...         tally += next
...
>>> def gather_tallies(tallies):
...     while 1:
...         tally = yield from accumulate()
...         tallies.append(tally)
...
>>> tallies = []
>>> acc = gather_tallies(tallies)
>>> next(acc)  # Ensure the accumulator is ready to accept values
>>> for i in range(4):
...     acc.send(i)
...
>>> acc.send(None)  # Finish the first tally
>>> for i in range(5):
...     acc.send(i)
...
>>> acc.send(None)  # Finish the second tally
>>> tallies
[6, 10]
@end example

The main principle driving this change is to allow even generators that are
designed to be used with the @code{send} and @code{throw} methods to be split into
multiple subgenerators as easily as a single large function can be split into
multiple subfunctions.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 380

@item PEP 380@footnote{https://peps.python.org/pep-0380/} -- Syntaxe pour déléguer à un sous-générateur

PEP written by Greg Ewing; implementation by Greg Ewing, integrated into
3.3 by Renaud Blanch, Ryan Kelly and Nick Coghlan; documentation by
Zbigniew Jędrzejewski-Szmek and Nick Coghlan
@end table


@node PEP 409 Suppressing exception context,PEP 414 Explicit Unicode literals,PEP 380 Syntax for Delegating to a Subgenerator,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-409-suppressing-exception-context}@anchor{104b}
@subsection PEP 409: Suppressing exception context


PEP 409 introduces new syntax that allows the display of the chained
exception context to be disabled. This allows cleaner error messages in
applications that convert between exception types:

@example
>>> class D:
...     def __init__(self, extra):
...         self._extra_attributes = extra
...     def __getattr__(self, attr):
...         try:
...             return self._extra_attributes[attr]
...         except KeyError:
...             raise AttributeError(attr) from None
...
>>> D(@{@}).x
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in __getattr__
AttributeError: x
@end example

Without the @code{from None} suffix to suppress the cause, the original
exception would be displayed by default:

@example
>>> class C:
...     def __init__(self, extra):
...         self._extra_attributes = extra
...     def __getattr__(self, attr):
...         try:
...             return self._extra_attributes[attr]
...         except KeyError:
...             raise AttributeError(attr)
...
>>> C(@{@}).x
Traceback (most recent call last):
  File "<stdin>", line 6, in __getattr__
KeyError: 'x'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 8, in __getattr__
AttributeError: x
@end example

No debugging capability is lost, as the original exception context remains
available if needed (for example, if an intervening library has incorrectly
suppressed valuable underlying details):

@example
>>> try:
...     D(@{@}).x
... except AttributeError as exc:
...     print(repr(exc.__context__))
...
KeyError('x',)
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 409

@item PEP 409@footnote{https://peps.python.org/pep-0409/} - Suppressing exception context

PEP written by Ethan Furman; implemented by Ethan Furman and Nick
Coghlan.
@end table


@node PEP 414 Explicit Unicode literals,PEP 3155 Qualified name for classes and functions,PEP 409 Suppressing exception context,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-414-explicit-unicode-literals}@anchor{104c}
@subsection PEP 414: Explicit Unicode literals


To ease the transition from Python 2 for Unicode aware Python applications
that make heavy use of Unicode literals, Python 3.3 once again supports the
"@code{u}" prefix for string literals. This prefix has no semantic significance
in Python 3, it is provided solely to reduce the number of purely mechanical
changes in migrating to Python 3, making it easier for developers to focus on
the more significant semantic changes (such as the stricter default
separation of binary and text data).


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 414

@item PEP 414@footnote{https://peps.python.org/pep-0414/} - Explicit Unicode literals

PEP written by Armin Ronacher.
@end table


@node PEP 3155 Qualified name for classes and functions,PEP 412 Key-Sharing Dictionary,PEP 414 Explicit Unicode literals,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-3155-qualified-name-for-classes-and-functions}@anchor{104d}
@subsection PEP 3155: Qualified name for classes and functions


Functions and class objects have a new @ref{104e,,__qualname__}
attribute representing
the "path" from the module top-level to their definition.  For global functions
and classes, this is the same as @ref{104f,,__name__}.
For other functions and classes,
it provides better information about where they were actually defined, and
how they might be accessible from the global scope.

Example with (non-bound) methods:

@example
>>> class C:
...     def meth(self):
...         pass
...
>>> C.meth.__name__
'meth'
>>> C.meth.__qualname__
'C.meth'
@end example

Example with nested classes:

@example
>>> class C:
...     class D:
...         def meth(self):
...             pass
...
>>> C.D.__name__
'D'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__name__
'meth'
>>> C.D.meth.__qualname__
'C.D.meth'
@end example

Example with nested functions:

@example
>>> def outer():
...     def inner():
...         pass
...     return inner
...
>>> outer().__name__
'inner'
>>> outer().__qualname__
'outer.<locals>.inner'
@end example

The string representation of those objects is also changed to include the
new, more precise information:

@example
>>> str(C.D)
"<class '__main__.C.D'>"
>>> str(C.D.meth)
'<function C.D.meth at 0x7f46b9fe31e0>'
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3155

@item PEP 3155@footnote{https://peps.python.org/pep-3155/} - Qualified name for classes and functions

PEP written and implemented by Antoine Pitrou.
@end table


@node PEP 412 Key-Sharing Dictionary,PEP 362 Function Signature Object,PEP 3155 Qualified name for classes and functions,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-412}@anchor{1027}@anchor{whatsnew/3 3 pep-412-key-sharing-dictionary}@anchor{1050}
@subsection PEP 412: Key-Sharing Dictionary


Dictionaries used for the storage of objects' attributes are now able to
share part of their internal storage between each other (namely, the part
which stores the keys and their respective hashes).  This reduces the memory
consumption of programs creating many instances of non-builtin types.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 412

@item PEP 412@footnote{https://peps.python.org/pep-0412/} - Key-Sharing Dictionary

PEP written and implemented by Mark Shannon.
@end table


@node PEP 362 Function Signature Object,PEP 421 Adding sys implementation,PEP 412 Key-Sharing Dictionary,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-362-function-signature-object}@anchor{1051}
@subsection PEP 362: Function Signature Object


A new function @ref{722,,inspect.signature()} makes introspection of python
callables easy and straightforward.  A broad range of callables is supported:
python functions, decorated or not, classes, and @ref{40a,,functools.partial()}
objects.  New classes @ref{1ca,,inspect.Signature}, @ref{1cb,,inspect.Parameter}
and @ref{1052,,inspect.BoundArguments} hold information about the call signatures,
such as, annotations, default values, parameters kinds, and bound arguments,
which considerably simplifies writing decorators and any code that validates
or amends calling signatures or arguments.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 362

@item PEP 362@footnote{https://peps.python.org/pep-0362/}: -  Function Signature Object

PEP written by Brett Cannon, Yury Selivanov, Larry Hastings, Jiwon Seo;
implemented by Yury Selivanov.
@end table


@node PEP 421 Adding sys implementation,Using importlib as the Implementation of Import,PEP 362 Function Signature Object,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 pep-421-adding-sys-implementation}@anchor{1053}
@subsection PEP 421: Adding sys.implementation


A new attribute on the @ref{d8,,sys} module exposes details specific to the
implementation of the currently running interpreter.  The initial set of
attributes on @ref{500,,sys.implementation} are @code{name}, @code{version},
@code{hexversion}, and @code{cache_tag}.

The intention of @code{sys.implementation} is to consolidate into one namespace
the implementation-specific data used by the standard library.  This allows
different Python implementations to share a single standard library code base
much more easily.  In its initial state, @code{sys.implementation} holds only a
small portion of the implementation-specific data.  Over time that ratio will
shift in order to make the standard library more portable.

One example of improved standard library portability is @code{cache_tag}.  As of
Python 3.3, @code{sys.implementation.cache_tag} is used by @ref{76,,importlib} to
support 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} compliance.  Any Python implementation that uses
@code{importlib} for its built-in import system may use @code{cache_tag} to control
the caching behavior for modules.

@menu
* SimpleNamespace:: 

@end menu

@node SimpleNamespace,,,PEP 421 Adding sys implementation
@anchor{whatsnew/3 3 simplenamespace}@anchor{1054}
@subsubsection SimpleNamespace


The implementation of @code{sys.implementation} also introduces a new type to
Python: @ref{1cc,,types.SimpleNamespace}.  In contrast to a mapping-based
namespace, like @ref{253,,dict}, @code{SimpleNamespace} is attribute-based, like
@ref{a7a,,object}.  However, unlike @code{object}, @code{SimpleNamespace} instances
are writable.  This means that you can add, remove, and modify the namespace
through normal attribute access.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 421

@item PEP 421@footnote{https://peps.python.org/pep-0421/} - Adding sys.implementation

PEP written and implemented by Eric Snow.
@end table


@node Using importlib as the Implementation of Import,Autres changements au langage<11>,PEP 421 Adding sys implementation,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 importlib}@anchor{1025}@anchor{whatsnew/3 3 using-importlib-as-the-implementation-of-import}@anchor{1055}
@subsection Using importlib as the Implementation of Import


bpo-2377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2377} - Replace __import__ w/ importlib.__import__
bpo-13959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13959} - Re-implement parts of @code{imp} in pure Python
bpo-14605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14605} - Make import machinery explicit
bpo-14646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14646} - Require loaders set __loader__ and __package__

The @ref{8c1,,__import__()} function is now powered by @ref{1056,,importlib.__import__()}.
This work leads to the completion of "phase 2" of 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}. There are
multiple benefits to this change. First, it has allowed for more of the
machinery powering import to be exposed instead of being implicit and hidden
within the C code. It also provides a single implementation for all Python VMs
supporting Python 3.3 to use, helping to end any VM-specific deviations in
import semantics. And finally it eases the maintenance of import, allowing for
future growth to occur.

For the common user, there should be no visible change in semantics.  For
those whose code currently manipulates import or calls import
programmatically, the code changes that might possibly be required are covered
in the @ref{1057,,Porting Python code} section of this document.

@menu
* New APIs:: 
* Visible Changes:: 

@end menu

@node New APIs,Visible Changes,,Using importlib as the Implementation of Import
@anchor{whatsnew/3 3 new-apis}@anchor{1058}
@subsubsection New APIs


One of the large benefits of this work is the exposure of what goes into
making the import statement work. That means the various importers that were
once implicit are now fully exposed as part of the @ref{76,,importlib} package.

The abstract base classes defined in @ref{77,,importlib.abc} have been expanded
to properly delineate between @ref{1059,,meta path finders}
and @ref{105a,,path entry finders} by introducing
@ref{859,,importlib.abc.MetaPathFinder} and
@ref{85a,,importlib.abc.PathEntryFinder}, respectively. The old ABC of
@code{importlib.abc.Finder} is now only provided for backwards-compatibility
and does not enforce any method requirements.

In terms of finders, @ref{105b,,importlib.machinery.FileFinder} exposes the
mechanism used to search for source and bytecode files of a module. Previously
this class was an implicit member of @ref{100d,,sys.path_hooks}.

For loaders, the new abstract base class @ref{105c,,importlib.abc.FileLoader} helps
write a loader that uses the file system as the storage mechanism for a module's
code. The loader for source files
(@ref{105d,,importlib.machinery.SourceFileLoader}), sourceless bytecode files
(@ref{105e,,importlib.machinery.SourcelessFileLoader}), and extension modules
(@ref{c9e,,importlib.machinery.ExtensionFileLoader}) are now available for
direct use.

@ref{40f,,ImportError} now has @code{name} and @code{path} attributes which are set when
there is relevant data to provide. The message for failed imports will also
provide the full name of the module now instead of just the tail end of the
module's name.

The @ref{bfe,,importlib.invalidate_caches()} function will now call the method with
the same name on all finders cached in @ref{5ce,,sys.path_importer_cache} to help
clean up any stored state as necessary.

@node Visible Changes,,New APIs,Using importlib as the Implementation of Import
@anchor{whatsnew/3 3 visible-changes}@anchor{105f}
@subsubsection Visible Changes


For potential required changes to code, see the @ref{1057,,Porting Python code}
section.

Beyond the expanse of what @ref{76,,importlib} now exposes, there are other
visible changes to import. The biggest is that @ref{d19,,sys.meta_path} and
@ref{100d,,sys.path_hooks} now store all of the meta path finders and path entry
hooks used by import.  Previously the finders were implicit and hidden within
the C code of import instead of being directly exposed. This means that one can
now easily remove or change the order of the various finders to fit one's needs.

Another change is that all modules have a @code{__loader__} attribute, storing the
loader used to create the module. 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} has been updated to make this
attribute mandatory for loaders to implement, so in the future once 3rd-party
loaders have been updated people will be able to rely on the existence of the
attribute. Until such time, though, import is setting the module post-load.

Loaders are also now expected to set the @code{__package__} attribute from
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/}. Once again, import itself is already setting this on all loaders
from @ref{76,,importlib} and import itself is setting the attribute post-load.

@code{None} is now inserted into @ref{5ce,,sys.path_importer_cache} when no finder
can be found on @ref{100d,,sys.path_hooks}. Since @code{imp.NullImporter} is not
directly exposed on @ref{100d,,sys.path_hooks} it could no longer be relied upon to
always be available to use as a value representing no finder found.

All other changes relate to semantic changes which should be taken into
consideration when updating code for Python 3.3, and thus should be read about
in the @ref{1057,,Porting Python code} section of this document.

(Implementation by Brett Cannon)

@node Autres changements au langage<11>,A Finer-Grained Import Lock,Using importlib as the Implementation of Import,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 other-language-changes}@anchor{1060}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
Added support for Unicode name aliases and named sequences.
Both @ref{1061,,unicodedata.lookup()} and @code{'\N@{...@}'} now resolve name aliases,
and @ref{1061,,unicodedata.lookup()} resolves named sequences too.

(Contribution par Ezio Melotti; bpo-12753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12753}.)

@item 
Unicode database updated to UCD version 6.1.0

@item 
Equality comparisons on @ref{930,,range()} objects now return a result reflecting
the equality of the underlying sequences generated by those range objects.
(bpo-13201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13201})

@item 
The @code{count()}, @code{find()}, @code{rfind()}, @code{index()} and @code{rindex()}
methods of @ref{1bd,,bytes} and @ref{528,,bytearray} objects now accept an
integer between 0 and 255 as their first argument.

(Contribution par Petri Lehtinen; bpo-12170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12170}.)

@item 
The @code{rjust()}, @code{ljust()}, and @code{center()} methods of @ref{1bd,,bytes}
and @ref{528,,bytearray} now accept a @ref{528,,bytearray} for the @code{fill}
argument.  (Contributed by Petri Lehtinen in bpo-12380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12380}.)

@item 
New methods have been added to @ref{5fc,,list} and @ref{528,,bytearray}:
@code{copy()} and @code{clear()} (bpo-10516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10516}).  Consequently,
@ref{19f,,MutableSequence} now also defines a
@code{clear()} method (bpo-11388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11388}).

@item 
Raw bytes literals can now be written @code{rb"..."} as well as @code{br"..."}.

(Contribution par Antoine Pitrou; bpo-13748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13748}.)

@item 
@ref{1062,,dict.setdefault()} now does only one lookup for the given key, making
it atomic when used with built-in types.

(Contribution par Filip Gruszczyński; bpo-13521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13521}.)

@item 
The error messages produced when a function call does not match the function
signature have been significantly improved.

(Contribution par Benjamin Peterson)
@end itemize

@node A Finer-Grained Import Lock,Builtin functions and types,Autres changements au langage<11>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 a-finer-grained-import-lock}@anchor{1063}
@subsection A Finer-Grained Import Lock


Previous versions of CPython have always relied on a global import lock.
This led to unexpected annoyances, such as deadlocks when importing a module
would trigger code execution in a different thread as a side-effect.
Clumsy workarounds were sometimes employed, such as the
@ref{3b4,,PyImport_ImportModuleNoBlock()} C API function.

In Python 3.3, importing a module takes a per-module lock.  This correctly
serializes importation of a given module from multiple threads (preventing
the exposure of incompletely initialized modules), while eliminating the
aforementioned annoyances.

(Contribution par Antoine Pitrou; bpo-9260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9260}.)

@node Builtin functions and types,Nouveaux modules<11>,A Finer-Grained Import Lock,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 builtin-functions-and-types}@anchor{1064}
@subsection Builtin functions and types



@itemize *

@item 
@ref{505,,open()} gets a new `opener' parameter: the underlying file descriptor
for the file object is then obtained by calling `opener' with (`file',
`flags'). It can be used to use custom flags like @ref{1065,,os.O_CLOEXEC} for
example. The @code{'x'} mode was added: open for exclusive creation, failing if
the file already exists.

@item 
@ref{f60,,print()}: added the `flush' keyword argument. If the `flush' keyword
argument is true, the stream is forcibly flushed.

@item 
@ref{5d5,,hash()}: hash randomization is enabled by default, see
@ref{ae9,,object.__hash__()} and 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED}.

@item 
The @ref{435,,str} type gets a new @ref{dc3,,casefold()} method: return a
casefolded copy of the string, casefolded strings may be used for caseless
matching. For example, @code{'ß'.casefold()} returns @code{'ss'}.

@item 
The sequence documentation has been substantially rewritten to better
explain the binary/text sequence distinction and to provide specific
documentation sections for the individual builtin sequence types
(bpo-4966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4966}).
@end itemize

@node Nouveaux modules<11>,Modules améliorés<11>,Builtin functions and types,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 new-modules}@anchor{1067}
@subsection Nouveaux modules


@menu
* faulthandler: faulthandler<4>. 
* ipaddress: ipaddress<6>. 
* lzma: lzma<2>. 

@end menu

@node faulthandler<4>,ipaddress<6>,,Nouveaux modules<11>
@anchor{whatsnew/3 3 faulthandler}@anchor{1068}
@subsubsection @code{faulthandler}


This new debug module @ref{57,,faulthandler} contains functions to dump Python tracebacks explicitly,
on a fault (a crash like a segmentation fault), after a timeout, or on a user
signal. Call @ref{c8c,,faulthandler.enable()} to install fault handlers for the
@code{SIGSEGV}, @code{SIGFPE}, @code{SIGABRT}, @code{SIGBUS}, and
@code{SIGILL} signals. You can also enable them at startup by setting the
@geindex PYTHONFAULTHANDLER
@geindex variable d'environnement; PYTHONFAULTHANDLER
@ref{1069,,PYTHONFAULTHANDLER} environment variable or by using @ref{175,,-X}
@code{faulthandler} command line option.

Example of a segmentation fault on Linux:

@example
$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
Fatal Python error: Segmentation fault

Current thread 0x00007fb899f39700:
  File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
  File "<stdin>", line 1 in <module>
Segmentation fault
@end example

@node ipaddress<6>,lzma<2>,faulthandler<4>,Nouveaux modules<11>
@anchor{whatsnew/3 3 ipaddress}@anchor{106a}
@subsubsection `ipaddress'


The new @ref{7f,,ipaddress} module provides tools for creating and manipulating
objects representing IPv4 and IPv6 addresses, networks and interfaces (i.e.
an IP address associated with a specific IP subnet).

(Contribution par Google et Peter Moody; 
@geindex Python Enhancement Proposals; PEP 3144
PEP 3144@footnote{https://peps.python.org/pep-3144/})

@node lzma<2>,,ipaddress<6>,Nouveaux modules<11>
@anchor{whatsnew/3 3 lzma}@anchor{106b}
@subsubsection lzma


The newly added @ref{89,,lzma} module provides data compression and decompression
using the LZMA algorithm, including support for the @code{.xz} and @code{.lzma}
file formats.

(Contributed by Nadeem Vawda and Per Øyvind Karlsen in bpo-6715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6715}.)

@node Modules améliorés<11>,Optimizations<5>,Nouveaux modules<11>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 improved-modules}@anchor{106c}
@subsection Modules améliorés


@menu
* abc: abc<2>. 
* array: array<5>. 
* base64: base64<4>. 
* binascii: binascii<3>. 
* bz2: bz2<2>. 
* codecs: codecs<2>. 
* collections: collections<7>. 
* contextlib: contextlib<7>. 
* crypt: crypt<2>. 
* curses: curses<5>. 
* datetime: datetime<6>. 
* decimal: decimal<3>. 
* email: email<5>. 
* ftplib: ftplib<3>. 
* functools: functools<6>. 
* gc: gc<6>. 
* hmac: hmac<4>. 
* http: http<4>. 
* html: html<2>. 
* imaplib: imaplib<3>. 
* inspect: inspect<9>. 
* io: io<6>. 
* itertools: itertools<6>. 
* logging: logging<7>. 
* math: math<9>. 
* mmap: mmap<4>. 
* multiprocessing: multiprocessing<8>. 
* nntplib: nntplib<2>. 
* os: os<12>. 
* pdb: pdb<7>. 
* pickle: pickle<5>. 
* pydoc: pydoc<5>. 
* re: re<9>. 
* sched:: 
* select: select<2>. 
* shlex: shlex<3>. 
* shutils: shutils<7>. 
* signal: signal<4>. 
* smtpd: smtpd<4>. 
* smtplib: smtplib<4>. 
* socket: socket<10>. 
* socketserver: socketserver<3>. 
* sqlite3: sqlite3<10>. 
* ssl: ssl<11>. 
* stat: stat<2>. 
* struct: struct<3>. 
* subprocess: subprocess<6>. 
* sys: sys<13>. 
* tarfile: tarfile<8>. 
* tempfile: tempfile<4>. 
* textwrap: textwrap<2>. 
* threading: threading<8>. 
* time: time<8>. 
* types: types<7>. 
* unittest: unittest<10>. 
* urllib: urllib<4>. 
* webbrowser: webbrowser<3>. 
* xml.etree.ElementTree: xml etree ElementTree<2>. 
* zlib: zlib<2>. 

@end menu

@node abc<2>,array<5>,,Modules améliorés<11>
@anchor{whatsnew/3 3 abc}@anchor{106d}
@subsubsection abc


Improved support for abstract base classes containing descriptors composed with
abstract methods. The recommended approach to declaring abstract descriptors is
now to provide @code{__isabstractmethod__} as a dynamically updated
property. The built-in descriptors have been updated accordingly.


@itemize *

@item 
@ref{106e,,abc.abstractproperty} has been deprecated, use @ref{192,,property}
with @ref{106f,,abc.abstractmethod()} instead.

@item 
@ref{1070,,abc.abstractclassmethod} has been deprecated, use
@ref{165,,classmethod} with @ref{106f,,abc.abstractmethod()} instead.

@item 
@ref{1071,,abc.abstractstaticmethod} has been deprecated, use
@ref{40c,,staticmethod} with @ref{106f,,abc.abstractmethod()} instead.
@end itemize

(Contribution par Darren Dale; bpo-11610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11610}.)

@ref{1072,,abc.ABCMeta.register()} now returns the registered subclass, which means
it can now be used as a class decorator (bpo-10868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10868}).

@node array<5>,base64<4>,abc<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 array}@anchor{1073}
@subsubsection `array'


The @ref{7,,array} module supports the long long type using @code{q} and
@code{Q} type codes.

(Contribution par Oren Tirosh et Hirokazu Yamamoto; bpo-1172711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1172711}.)

@node base64<4>,binascii<3>,array<5>,Modules améliorés<11>
@anchor{whatsnew/3 3 base64}@anchor{1074}
@subsubsection base64


ASCII-only Unicode strings are now accepted by the decoding functions of the
@ref{e,,base64} modern interface. For example, @code{base64.b64decode('YWJj')}
returns @code{b'abc'}.  (Contributed by Catalin Iacob in bpo-13641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13641}.)

@node binascii<3>,bz2<2>,base64<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 binascii}@anchor{1075}
@subsubsection binascii


In addition to the binary objects they normally accept, the @code{a2b_} functions
now all also accept ASCII-only strings as input.  (Contributed by Antoine
Pitrou in bpo-13637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13637}.)

@node bz2<2>,codecs<2>,binascii<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 bz2}@anchor{1076}
@subsubsection bz2


The @ref{13,,bz2} module has been rewritten from scratch. In the process, several
new features have been added:


@itemize *

@item 
New @ref{1077,,bz2.open()} function: open a bzip2-compressed file in binary or
text mode.

@item 
@ref{851,,bz2.BZ2File} can now read from and write to arbitrary file-like
objects, by means of its constructor's `fileobj' argument.

(Contribution par Nadeem Vawda; bpo-5863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5863}.)

@item 
@ref{851,,bz2.BZ2File} and @ref{1078,,bz2.decompress()} can now decompress
multi-stream inputs (such as those produced by the @code{pbzip2} tool).
@ref{851,,bz2.BZ2File} can now also be used to create this type of file, using
the @code{'a'} (append) mode.

(Contribution par Nir Aides; bpo-1625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1625}.)

@item 
@ref{851,,bz2.BZ2File} now implements all of the @ref{67f,,io.BufferedIOBase} API,
except for the @code{detach()} and @code{truncate()} methods.
@end itemize

@node codecs<2>,collections<7>,bz2<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 codecs}@anchor{1079}
@subsubsection @code{codecs}


The @ref{52,,mbcs} codec has been rewritten to handle correctly
@code{replace} and @code{ignore} error handlers on all Windows versions.  The
@ref{52,,mbcs} codec now supports all error handlers, instead of only
@code{replace} to encode and @code{ignore} to decode.

A new Windows-only codec has been added: @code{cp65001} (bpo-13216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13216}). It is the
Windows code page 65001 (Windows UTF-8, @code{CP_UTF8}).  For example, it is used
by @code{sys.stdout} if the console output code page is set to cp65001 (e.g., using
@code{chcp 65001} command).

Multibyte CJK decoders now resynchronize faster.  They only ignore the first
byte of an invalid byte sequence. For example, @code{b'\xff\n'.decode('gb2312',
'replace')} now returns a @code{\n} after the replacement character.

(bpo-12016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12016})

Incremental CJK codec encoders are no longer reset at each call to their
encode() methods. For example:

@example
>>> import codecs
>>> encoder = codecs.getincrementalencoder('hz')('strict')
>>> b'@w{'}.join(encoder.encode(x) for x in '\u52ff\u65bd\u65bc\u4eba\u3002 Bye.')
b'~@{NpJ)l6HK!#~@} Bye.'
@end example

This example gives @code{b'~@{Np~@}~@{J)~@}~@{l6~@}~@{HK~@}~@{!#~@} Bye.'} with older Python
versions.

(bpo-12100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12100})

The @code{unicode_internal} codec has been deprecated.

@node collections<7>,contextlib<7>,codecs<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 collections}@anchor{107a}
@subsubsection collections


Addition of a new @ref{c0a,,ChainMap} class to allow treating a
number of mappings as a single unit.  (Written by Raymond Hettinger for
bpo-11089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11089}, made public in bpo-11297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11297}.)

The abstract base classes have been moved in a new @ref{1e,,collections.abc}
module, to better differentiate between the abstract and the concrete
collections classes.  Aliases for ABCs are still present in the
@ref{1d,,collections} module to preserve existing imports.  (bpo-11085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11085})

@c XXX addition of __slots__ to ABCs not recorded here: internal detail

The @ref{107b,,Counter} class now supports the unary @code{+} and @code{-}
operators, as well as the in-place operators @code{+=}, @code{-=}, @code{|=}, and
@code{&=}.  (Contributed by Raymond Hettinger in bpo-13121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13121}.)

@node contextlib<7>,crypt<2>,collections<7>,Modules améliorés<11>
@anchor{whatsnew/3 3 contextlib}@anchor{107c}
@subsubsection contextlib


@ref{b17,,ExitStack} now provides a solid foundation for
programmatic manipulation of context managers and similar cleanup
functionality. Unlike the previous @code{contextlib.nested} API (which was
deprecated and removed), the new API is designed to work correctly
regardless of whether context managers acquire their resources in
their @code{__init__} method (for example, file objects) or in their
@code{__enter__} method (for example, synchronisation objects from the
@ref{ec,,threading} module).

(bpo-13585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13585})

@node crypt<2>,curses<5>,contextlib<7>,Modules améliorés<11>
@anchor{whatsnew/3 3 crypt}@anchor{107d}
@subsubsection crypt


Addition of salt and modular crypt format (hashing method) and the @code{mksalt()}
function to the @code{crypt} module.

(bpo-10924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10924})

@node curses<5>,datetime<6>,crypt<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 curses}@anchor{107e}
@subsubsection curses



@itemize *

@item 
If the @ref{2b,,curses} module is linked to the ncursesw library, use Unicode
functions when Unicode strings or characters are passed (e.g.
@code{waddwstr()}), and bytes functions otherwise (e.g. @code{waddstr()}).

@item 
Use the locale encoding instead of @code{utf-8} to encode Unicode strings.

@item 
@code{curses.window} has a new @ref{107f,,curses.window.encoding} attribute.

@item 
The @code{curses.window} class has a new @ref{1080,,get_wch()}
method to get a wide character

@item 
The @ref{2b,,curses} module has a new @ref{1081,,unget_wch()} function to
push a wide character so the next @ref{1080,,get_wch()} will return
it
@end itemize

(Contribution par Iñigo Serna; bpo-6755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6755}.)

@node datetime<6>,decimal<3>,curses<5>,Modules améliorés<11>
@anchor{whatsnew/3 3 datetime}@anchor{1082}
@subsubsection datetime



@itemize *

@item 
Equality comparisons between naive and aware @ref{1c7,,datetime}
instances now return @ref{b25,,False} instead of raising @ref{522,,TypeError}
(bpo-15006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15006}).

@item 
New @ref{1083,,datetime.datetime.timestamp()} method: Return POSIX timestamp
corresponding to the @ref{1c7,,datetime} instance.

@item 
The @ref{c7e,,datetime.datetime.strftime()} method supports formatting years
older than 1000.

@item 
The @ref{9be,,datetime.datetime.astimezone()} method can now be
called without arguments to convert datetime instance to the system
timezone.
@end itemize

@node decimal<3>,email<5>,datetime<6>,Modules améliorés<11>
@anchor{whatsnew/3 3 decimal}@anchor{1084}@anchor{whatsnew/3 3 new-decimal}@anchor{1028}
@subsubsection decimal



@table @asis

@item bpo-7652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7652} - integrate fast native decimal arithmetic.

C-module and libmpdec written by Stefan Krah.
@end table

The new C version of the decimal module integrates the high speed libmpdec
library for arbitrary precision correctly rounded decimal floating-point
arithmetic. libmpdec conforms to IBM's General Decimal Arithmetic Specification.

Performance gains range from 10x for database applications to 100x for
numerically intensive applications. These numbers are expected gains
for standard precisions used in decimal floating-point arithmetic. Since
the precision is user configurable, the exact figures may vary. For example,
in integer bignum arithmetic the differences can be significantly higher.

The following table is meant as an illustration. Benchmarks are available
at @indicateurl{https://www.bytereef.org/mpdecimal/quickstart.html}.

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 
@headitem

@tab

decimal.py

@tab

_decimal

@tab

speedup

@item

pi

@tab

42.02s

@tab

0.345s

@tab

120x

@item

telco

@tab

172.19s

@tab

5.68s

@tab

30x

@item

psycopg

@tab

3.57s

@tab

0.29s

@tab

12x

@end multitable

@end quotation

@menu
* Caractéristiques: Caractéristiques<2>. 
* API changes: API changes<2>. 

@end menu

@node Caractéristiques<2>,API changes<2>,,decimal<3>
@anchor{whatsnew/3 3 id1}@anchor{1085}
@subsubsection Caractéristiques



@itemize *

@item 
The @ref{1086,,FloatOperation} signal optionally enables stricter
semantics for mixing floats and Decimals.

@item 
If Python is compiled without threads, the C version automatically
disables the expensive thread local context machinery. In this case,
the variable @ref{1087,,HAVE_THREADS} is set to @code{False}.
@end itemize

@node API changes<2>,,Caractéristiques<2>,decimal<3>
@anchor{whatsnew/3 3 id2}@anchor{1088}
@subsubsection API changes



@itemize *

@item 
The C module has the following context limits, depending on the machine
architecture:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

32-bit

@tab

64-bit

@item

@code{MAX_PREC}

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@code{MAX_EMAX}

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@code{MIN_EMIN}

@tab

@code{-425000000}

@tab

@code{-999999999999999999}

@end multitable

@end quotation

@item 
In the context templates (@ref{1089,,DefaultContext},
@ref{108a,,BasicContext} and @ref{108b,,ExtendedContext})
the magnitude of @code{Emax} and
@code{Emin} has changed to @code{999999}.

@item 
The @ref{29a,,Decimal} constructor in decimal.py does not observe
the context limits and converts values with arbitrary exponents or precision
exactly. Since the C version has internal limits, the following scheme is
used: If possible, values are converted exactly, otherwise
@ref{108c,,InvalidOperation} is raised and the result is NaN. In the
latter case it is always possible to use @ref{108d,,create_decimal()}
in order to obtain a rounded or inexact value.

@item 
The power function in decimal.py is always correctly rounded. In the
C version, it is defined in terms of the correctly rounded
@ref{108e,,exp()} and @ref{108f,,ln()} functions,
but the final result is only "almost always correctly rounded".

@item 
In the C version, the context dictionary containing the signals is a
@ref{1090,,MutableMapping}.  For speed reasons,
@code{flags} and @code{traps} always
refer to the same @ref{1090,,MutableMapping} that the context
was initialized with. If a new signal dictionary is assigned,
@code{flags} and @code{traps}
are updated with the new values, but they do not reference the RHS
dictionary.

@item 
Pickling a @ref{1091,,Context} produces a different output in order
to have a common interchange format for the Python and C versions.

@item 
The order of arguments in the @ref{1091,,Context} constructor has been
changed to match the order displayed by @ref{7e7,,repr()}.

@item 
The @code{watchexp} parameter in the @ref{1092,,quantize()} method
is deprecated.
@end itemize

@node email<5>,ftplib<3>,decimal<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 email}@anchor{1093}@anchor{whatsnew/3 3 new-email}@anchor{1029}
@subsubsection email


@menu
* Policy Framework:: 
* Provisional Policy with New Header API:: 
* Other API Changes:: 

@end menu

@node Policy Framework,Provisional Policy with New Header API,,email<5>
@anchor{whatsnew/3 3 policy-framework}@anchor{1094}
@subsubsection Policy Framework


The email package now has a @ref{4f,,policy} framework.  A
@ref{1095,,Policy} is an object with several methods and properties
that control how the email package behaves.  The primary policy for Python 3.3
is the @ref{1096,,Compat32} policy, which provides backward
compatibility with the email package in Python 3.2.  A @code{policy} can be
specified when an email message is parsed by a @ref{4e,,parser}, or when a
@ref{279,,Message} object is created, or when an email is
serialized using a @ref{40,,generator}.  Unless overridden, a policy passed
to a @code{parser} is inherited by all the @code{Message} object and sub-objects
created by the @code{parser}.  By default a @code{generator} will use the policy of
the @code{Message} object it is serializing.  The default policy is
@ref{c87,,compat32}.

The minimum set of controls implemented by all @code{policy} objects are:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

max_line_length

@tab

The maximum length, excluding the linesep character(s),
individual lines may have when a @code{Message} is
serialized.  Defaults to 78.

@item

linesep

@tab

The character used to separate individual lines when a
@code{Message} is serialized.  Defaults to @code{\n}.

@item

cte_type

@tab

@code{7bit} or @code{8bit}.  @code{8bit} applies only to a
@code{Bytes} @code{generator}, and means that non-ASCII may
be used where allowed by the protocol (or where it
exists in the original input).

@item

raise_on_defect

@tab

Causes a @code{parser} to raise error when defects are
encountered instead of adding them to the @code{Message}
object's @code{defects} list.

@end multitable


A new policy instance, with new settings, is created using the
@ref{1097,,clone()} method of policy objects.  @code{clone} takes
any of the above controls as keyword arguments.  Any control not specified in
the call retains its default value.  Thus you can create a policy that uses
@code{\r\n} linesep characters like this:

@example
mypolicy = compat32.clone(linesep='\r\n')
@end example

Policies can be used to make the generation of messages in the format needed by
your application simpler.  Instead of having to remember to specify
@code{linesep='\r\n'} in all the places you call a @code{generator}, you can specify
it once, when you set the policy used by the @code{parser} or the @code{Message},
whichever your program uses to create @code{Message} objects.  On the other hand,
if you need to generate messages in multiple forms, you can still specify the
parameters in the appropriate @code{generator} call.  Or you can have custom
policy instances for your different cases, and pass those in when you create
the @code{generator}.

@node Provisional Policy with New Header API,Other API Changes,Policy Framework,email<5>
@anchor{whatsnew/3 3 provisional-policy-with-new-header-api}@anchor{1098}
@subsubsection Provisional Policy with New Header API


While the policy framework is worthwhile all by itself, the main motivation for
introducing it is to allow the creation of new policies that implement new
features for the email package in a way that maintains backward compatibility
for those who do not use the new policies.  Because the new policies introduce a
new API, we are releasing them in Python 3.3 as a @ref{102a,,provisional policy}.  Backwards incompatible changes (up to and including
removal of the code) may occur if deemed necessary by the core developers.

The new policies are instances of @ref{1099,,EmailPolicy},
and add the following additional controls:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

refold_source

@tab

Controls whether or not headers parsed by a
@ref{4e,,parser} are refolded by the
@ref{40,,generator}.  It can be @code{none}, @code{long},
or @code{all}.  The default is @code{long}, which means that
source headers with a line longer than
@code{max_line_length} get refolded.  @code{none} means no
line get refolded, and @code{all} means that all lines
get refolded.

@item

header_factory

@tab

A callable that take a @code{name} and @code{value} and
produces a custom header object.

@end multitable


The @code{header_factory} is the key to the new features provided by the new
policies.  When one of the new policies is used, any header retrieved from
a @code{Message} object is an object produced by the @code{header_factory}, and any
time you set a header on a @code{Message} it becomes an object produced by
@code{header_factory}.  All such header objects have a @code{name} attribute equal
to the header name.  Address and Date headers have additional attributes
that give you access to the parsed data of the header.  This means you can now
do things like this:

@example
>>> m = Message(policy=SMTP)
>>> m['To'] = 'Éric <foo@@example.com>'
>>> m['to']
'Éric <foo@@example.com>'
>>> m['to'].addresses
(Address(display_name='Éric', username='foo', domain='example.com'),)
>>> m['to'].addresses[0].username
'foo'
>>> m['to'].addresses[0].display_name
'Éric'
>>> m['Date'] = email.utils.localtime()
>>> m['Date'].datetime
datetime.datetime(2012, 5, 25, 21, 39, 24, 465484, tzinfo=datetime.timezone(datetime.timedelta(-1, 72000), 'EDT'))
>>> m['Date']
'Fri, 25 May 2012 21:44:27 -0400'
>>> print(m)
To: =?utf-8?q?=C3=89ric?= <foo@@example.com>
Date: Fri, 25 May 2012 21:44:27 -0400
@end example

You will note that the unicode display name is automatically encoded as
@code{utf-8} when the message is serialized, but that when the header is accessed
directly, you get the unicode version.  This eliminates any need to deal with
the @ref{41,,email.header} @ref{109a,,decode_header()} or
@ref{109b,,make_header()} functions.

You can also create addresses from parts:

@example
>>> m['cc'] = [Group('pals', [Address('Bob', 'bob', 'example.com'),
...                           Address('Sally', 'sally', 'example.com')]),
...            Address('Bonzo', addr_spec='bonz@@laugh.com')]
>>> print(m)
To: =?utf-8?q?=C3=89ric?= <foo@@example.com>
Date: Fri, 25 May 2012 21:44:27 -0400
cc: pals: Bob <bob@@example.com>, Sally <sally@@example.com>;, Bonzo <bonz@@laugh.com>
@end example

Decoding to unicode is done automatically:

@example
>>> m2 = message_from_string(str(m))
>>> m2['to']
'Éric <foo@@example.com>'
@end example

When you parse a message, you can use the @code{addresses} and @code{groups}
attributes of the header objects to access the groups and individual
addresses:

@example
>>> m2['cc'].addresses
(Address(display_name='Bob', username='bob', domain='example.com'), Address(display_name='Sally', username='sally', domain='example.com'), Address(display_name='Bonzo', username='bonz', domain='laugh.com'))
>>> m2['cc'].groups
(Group(display_name='pals', addresses=(Address(display_name='Bob', username='bob', domain='example.com'), Address(display_name='Sally', username='sally', domain='example.com')), Group(display_name=None, addresses=(Address(display_name='Bonzo', username='bonz', domain='laugh.com'),))
@end example

In summary, if you use one of the new policies, header manipulation works the
way it ought to:  your application works with unicode strings, and the email
package transparently encodes and decodes the unicode to and from the RFC
standard Content Transfer Encodings.

@node Other API Changes,,Provisional Policy with New Header API,email<5>
@anchor{whatsnew/3 3 other-api-changes}@anchor{109c}
@subsubsection Other API Changes


New @ref{109d,,BytesHeaderParser}, added to the @ref{4e,,parser}
module to complement @ref{109e,,HeaderParser} and complete the Bytes
API.

New utility functions:


@itemize *

@item 
@ref{109f,,format_datetime()}: given a @ref{1c7,,datetime},
produce a string formatted for use in an email header.

@item 
@ref{10a0,,parsedate_to_datetime()}: given a date string from
an email header, convert it into an aware @ref{1c7,,datetime},
or a naive @ref{1c7,,datetime} if the offset is @code{-0000}.

@item 
@ref{2c2,,localtime()}: With no argument, returns the
current local time as an aware @ref{1c7,,datetime} using the local
@ref{10a1,,timezone}.  Given an aware @ref{1c7,,datetime},
converts it into an aware @ref{1c7,,datetime} using the
local @ref{10a1,,timezone}.
@end itemize

@node ftplib<3>,functools<6>,email<5>,Modules améliorés<11>
@anchor{whatsnew/3 3 ftplib}@anchor{10a2}
@subsubsection `ftplib'



@itemize *

@item 
@ref{8e7,,ftplib.FTP} now accepts a @code{source_address} keyword argument to
specify the @code{(host, port)} to use as the source address in the bind call
when creating the outgoing socket.  (Contributed by Giampaolo Rodolà
in bpo-8594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8594}.)

@item 
The @ref{8e8,,FTP_TLS} class now provides a new
@ref{10a3,,ccc()} function to revert control channel back to
plaintext.  This can be useful to take advantage of firewalls that know how
to handle NAT with non-secure FTP without opening fixed ports.  (Contributed
by Giampaolo Rodolà in bpo-12139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12139}.)

@item 
Added @ref{10a4,,ftplib.FTP.mlsd()} method which provides a parsable directory
listing format and deprecates @ref{10a5,,ftplib.FTP.nlst()} and
@ref{10a6,,ftplib.FTP.dir()}.  (Contributed by Giampaolo Rodolà in bpo-11072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11072}.)
@end itemize

@node functools<6>,gc<6>,ftplib<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 functools}@anchor{10a7}
@subsubsection functools


The @ref{9dd,,functools.lru_cache()} decorator now accepts a @code{typed} keyword
argument (that defaults to @code{False} to ensure that it caches values of
different types that compare equal in separate cache slots.  (Contributed
by Raymond Hettinger in bpo-13227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13227}.)

@node gc<6>,hmac<4>,functools<6>,Modules améliorés<11>
@anchor{whatsnew/3 3 gc}@anchor{10a8}
@subsubsection `gc'


It is now possible to register callbacks invoked by the garbage collector
before and after collection using the new @ref{10a9,,callbacks} list.

@node hmac<4>,http<4>,gc<6>,Modules améliorés<11>
@anchor{whatsnew/3 3 hmac}@anchor{10aa}
@subsubsection @code{hmac}


A new @ref{10ab,,compare_digest()} function has been added to prevent side
channel attacks on digests through timing analysis.  (Contributed by Nick
Coghlan and Christian Heimes in bpo-15061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15061}.)

@node http<4>,html<2>,hmac<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 http}@anchor{10ac}
@subsubsection `http'


@ref{10ad,,http.server.BaseHTTPRequestHandler} now buffers the headers and writes
them all at once when @ref{10ae,,end_headers()} is
called.  A new method @ref{10af,,flush_headers()}
can be used to directly manage when the accumulated headers are sent.
(Contributed by Andrew Schaaf in bpo-3709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3709}.)

@ref{71,,http.server} now produces valid @code{HTML 4.01 strict} output.
(Contributed by Ezio Melotti in bpo-13295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13295}.)

@ref{10b0,,http.client.HTTPResponse} now has a
@ref{10b1,,readinto()} method, which means it can be used
as an @ref{10b2,,io.RawIOBase} class.  (Contributed by John Kuhn in
bpo-13464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13464}.)

@node html<2>,imaplib<3>,http<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 html}@anchor{10b3}
@subsubsection html


@ref{862,,html.parser.HTMLParser} is now able to parse broken markup without
raising errors, therefore the `strict' argument of the constructor and the
@code{HTMLParseError} exception are now deprecated.
The ability to parse broken markup is the result of a number of bug fixes that
are also available on the latest bug fix releases of Python 2.7/3.2.
(Contributed by Ezio Melotti in bpo-15114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15114}, and bpo-14538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14538},
bpo-13993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13993}, bpo-13960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13960}, bpo-13358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13358}, bpo-1745761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1745761},
bpo-755670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=755670}, bpo-13357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13357}, bpo-12629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12629}, bpo-1200313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1200313},
bpo-670664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=670664}, bpo-13273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13273}, bpo-12888@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12888}, bpo-7311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7311}.)

A new @ref{10b4,,html5} dictionary that maps HTML5 named character
references to the equivalent Unicode character(s) (e.g. @code{html5['gt;'] ==
'>'}) has been added to the @ref{6b,,html.entities} module.  The dictionary is
now also used by @ref{862,,HTMLParser}.  (Contributed by Ezio
Melotti in bpo-11113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11113} and bpo-15156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15156}.)

@node imaplib<3>,inspect<9>,html<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 imaplib}@anchor{10b5}
@subsubsection `imaplib'


The @ref{8f1,,IMAP4_SSL} constructor now accepts an SSLContext
parameter to control parameters of the secure channel.

(Contribution par Sijin Joseph; bpo-8808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8808}.)

@node inspect<9>,io<6>,imaplib<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 inspect}@anchor{10b6}
@subsubsection `inspect'


A new @ref{10b7,,getclosurevars()} function has been added. This function
reports the current binding of all names referenced from the function body and
where those names were resolved, making it easier to verify correct internal
state when testing code that relies on stateful closures.

(Contribution par Meador Inge et Nick Coghlan; bpo-13062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13062}.)

A new @ref{10b8,,getgeneratorlocals()} function has been added. This
function reports the current binding of local variables in the generator's
stack frame, making it easier to verify correct internal state when testing
generators.

(Contribution par Meador Inge; bpo-15153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15153}.)

@node io<6>,itertools<6>,inspect<9>,Modules améliorés<11>
@anchor{whatsnew/3 3 io}@anchor{10b9}
@subsubsection io


The @ref{506,,open()} function has a new @code{'x'} mode that can be used to
exclusively create a new file, and raise a @ref{1009,,FileExistsError} if the file
already exists. It is based on the C11 'x' mode to fopen().

(Contribution par David Townshend; bpo-12760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12760}.)

The constructor of the @ref{7a5,,TextIOWrapper} class has a new
`write_through' optional argument. If `write_through' is @code{True}, calls to
@code{write()} are guaranteed not to be buffered: any data
written on the @ref{7a5,,TextIOWrapper} object is immediately handled to its
underlying binary buffer.

@node itertools<6>,logging<7>,io<6>,Modules améliorés<11>
@anchor{whatsnew/3 3 itertools}@anchor{10ba}
@subsubsection itertools


@ref{9eb,,accumulate()} now takes an optional @code{func} argument for
providing a user-supplied binary function.

@node logging<7>,math<9>,itertools<6>,Modules améliorés<11>
@anchor{whatsnew/3 3 logging}@anchor{10bb}
@subsubsection logging


The @ref{9ee,,basicConfig()} function now supports an optional @code{handlers}
argument taking an iterable of handlers to be added to the root logger.

A class level attribute @code{append_nul} has
been added to @ref{647,,SysLogHandler} to allow control of the
appending of the @code{NUL} (@code{\000}) byte to syslog records, since for some
daemons it is required while for others it is passed through to the log.

@node math<9>,mmap<4>,logging<7>,Modules améliorés<11>
@anchor{whatsnew/3 3 math}@anchor{10bc}
@subsubsection `math'


The @ref{8d,,math} module has a new function, @ref{10bd,,log2()},  which returns
the base-2 logarithm of `x'.

(Written by Mark Dickinson in bpo-11888@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11888}.)

@node mmap<4>,multiprocessing<8>,math<9>,Modules améliorés<11>
@anchor{whatsnew/3 3 mmap}@anchor{10be}
@subsubsection mmap


The @ref{10bf,,read()} method is now more compatible with other file-like
objects: if the argument is omitted or specified as @code{None}, it returns the
bytes from the current file position to the end of the mapping.  (Contributed
by Petri Lehtinen in bpo-12021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12021}.)

@node multiprocessing<8>,nntplib<2>,mmap<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 multiprocessing}@anchor{10c0}
@subsubsection multiprocessing


The new @ref{10c1,,multiprocessing.connection.wait()} function allows polling
multiple objects (such as connections, sockets and pipes) with a timeout.
(Contributed by Richard Oudkerk in bpo-12328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12328}.)

@code{multiprocessing.Connection} objects can now be transferred over
multiprocessing connections.
(Contributed by Richard Oudkerk in bpo-4892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4892}.)

@ref{b47,,multiprocessing.Process} now accepts a @code{daemon} keyword argument
to override the default behavior of inheriting the @code{daemon} flag from
the parent process (bpo-6064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6064}).

New attribute @ref{10c2,,multiprocessing.Process.sentinel} allows a
program to wait on multiple @ref{b47,,Process} objects at one
time using the appropriate OS primitives (for example, @ref{c0,,select} on
posix systems).

New methods @ref{10c3,,multiprocessing.pool.Pool.starmap()} and
@ref{10c4,,starmap_async()} provide
@ref{10c5,,itertools.starmap()} equivalents to the existing
@ref{10c6,,multiprocessing.pool.Pool.map()} and
@ref{10c7,,map_async()} functions.  (Contributed by Hynek
Schlawack in bpo-12708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12708}.)

@node nntplib<2>,os<12>,multiprocessing<8>,Modules améliorés<11>
@anchor{whatsnew/3 3 nntplib}@anchor{10c8}
@subsubsection `nntplib'


The @code{nntplib.NNTP} class now supports the context management protocol to
unconditionally consume @ref{103e,,socket.error} exceptions and to close the NNTP
connection when done:

@example
>>> from nntplib import NNTP
>>> with NNTP('news.gmane.org') as n:
...     n.group('gmane.comp.python.committers')
...
('211 1755 1 1755 gmane.comp.python.committers', 1755, 1, 1755, 'gmane.comp.python.committers')
>>>
@end example

(Contribution par Giampaolo Rodolà; bpo-9795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9795}.)

@node os<12>,pdb<7>,nntplib<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 os}@anchor{10c9}
@subsubsection `os'



@itemize *

@item 
The @ref{a0,,os} module has a new @ref{10ca,,pipe2()} function that makes it
possible to create a pipe with @ref{1065,,O_CLOEXEC} or
@ref{e28,,O_NONBLOCK} flags set atomically. This is especially useful to
avoid race conditions in multi-threaded programs.

@item 
The @ref{a0,,os} module has a new @ref{afd,,sendfile()} function which provides
an efficient "zero-copy" way for copying data from one file (or socket)
descriptor to another. The phrase "zero-copy" refers to the fact that all of
the copying of data between the two descriptors is done entirely by the
kernel, with no copying of data into userspace buffers. @ref{afd,,sendfile()}
can be used to efficiently copy data from a file on disk to a network socket,
e.g. for downloading a file.

(Patch submitted by Ross Lagerwall and Giampaolo Rodolà in bpo-10882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10882}.)

@item 
To avoid race conditions like symlink attacks and issues with temporary
files and directories, it is more reliable (and also faster) to manipulate
file descriptors instead of file names. Python 3.3 enhances existing functions
and introduces new functions to work on file descriptors (bpo-4761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4761},
bpo-10755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10755} and bpo-14626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14626}).


@itemize -

@item 
The @ref{a0,,os} module has a new @ref{b49,,fwalk()} function similar to
@ref{493,,walk()} except that it also yields file descriptors referring to the
directories visited. This is especially useful to avoid symlink races.

@item 
The following functions get new optional `dir_fd' (@ref{10cb,,paths relative to directory descriptors}) and/or `follow_symlinks' (@ref{10cc,,not following symlinks}):
@ref{10cd,,access()}, @ref{10ce,,chflags()}, @ref{218,,chmod()}, @ref{10cf,,chown()},
@ref{10d0,,link()}, @ref{48b,,lstat()}, @ref{21a,,mkdir()}, @ref{d7d,,mkfifo()},
@ref{d7e,,mknod()}, @ref{d7f,,open()}, @ref{90d,,readlink()}, @ref{10d1,,remove()},
@ref{10d2,,rename()}, @ref{10d3,,replace()}, @ref{10d4,,rmdir()}, @ref{48a,,stat()},
@ref{10d5,,symlink()}, @ref{10d6,,unlink()}, @ref{10d7,,utime()}.  Platform
support for using these parameters can be checked via the sets
@ref{10d8,,os.supports_dir_fd} and @code{os.supports_follows_symlinks}.

@item 
The following functions now support a file descriptor for their path argument:
@ref{5f8,,chdir()}, @ref{218,,chmod()}, @ref{10cf,,chown()},
@ref{10d9,,execve()}, @ref{10da,,listdir()}, @ref{10db,,pathconf()}, @ref{9fc,,exists()},
@ref{48a,,stat()}, @ref{10dc,,statvfs()}, @ref{10d7,,utime()}.  Platform support
for this can be checked via the @ref{10dd,,os.supports_fd} set.
@end itemize

@item 
@ref{10cd,,access()} accepts an @code{effective_ids} keyword argument to turn on
using the effective uid/gid rather than the real uid/gid in the access check.
Platform support for this can be checked via the
@ref{10de,,supports_effective_ids} set.

@item 
The @ref{a0,,os} module has two new functions: @ref{10df,,getpriority()} and
@ref{10e0,,setpriority()}. They can be used to get or set process
niceness/priority in a fashion similar to @ref{10e1,,os.nice()} but extended to all
processes instead of just the current one.

(Patch submitted by Giampaolo Rodolà in bpo-10784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10784}.)

@item 
The new @ref{10d3,,os.replace()} function allows cross-platform renaming of a
file with overwriting the destination.  With @ref{10d2,,os.rename()}, an existing
destination file is overwritten under POSIX, but raises an error under
Windows.
(Contributed by Antoine Pitrou in bpo-8828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8828}.)

@item 
The stat family of functions (@ref{48a,,stat()}, @ref{d79,,fstat()},
and @ref{48b,,lstat()}) now support reading a file's timestamps
with nanosecond precision.  Symmetrically, @ref{10d7,,utime()}
can now write file timestamps with nanosecond precision.  (Contributed by
Larry Hastings in bpo-14127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14127}.)

@item 
The new @ref{10e2,,os.get_terminal_size()} function queries the size of the
terminal attached to a file descriptor. See also
@ref{10e3,,shutil.get_terminal_size()}.
(Contributed by Zbigniew Jędrzejewski-Szmek in bpo-13609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13609}.)
@end itemize

@c XXX sort out this mess after beta1


@itemize *

@item 
New functions to support Linux extended attributes (bpo-12720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12720}):
@ref{10e4,,getxattr()}, @ref{10e5,,listxattr()}, @ref{10e6,,removexattr()},
@ref{10e7,,setxattr()}.

@item 
New interface to the scheduler. These functions
control how a process is allocated CPU time by the operating system. New
functions:
@ref{10e8,,sched_get_priority_max()}, @ref{10e9,,sched_get_priority_min()},
@ref{10ea,,sched_getaffinity()}, @ref{10eb,,sched_getparam()},
@ref{10ec,,sched_getscheduler()}, @ref{10ed,,sched_rr_get_interval()},
@ref{10ee,,sched_setaffinity()}, @ref{10ef,,sched_setparam()},
@ref{10f0,,sched_setscheduler()}, @ref{10f1,,sched_yield()},

@item 
New functions to control the file system:


@itemize *

@item 
@ref{d80,,posix_fadvise()}: Announces an intention to access data in a
specific pattern thus allowing the kernel to make optimizations.

@item 
@ref{d81,,posix_fallocate()}: Ensures that enough disk space is allocated
for a file.

@item 
@ref{10f2,,sync()}: Force write of everything to disk.
@end itemize

@item 
Additional new  posix functions:


@itemize *

@item 
@ref{10f3,,lockf()}: Apply, test or remove a POSIX lock on an open file descriptor.

@item 
@ref{b4d,,pread()}: Read from a file descriptor at an offset, the file
offset remains unchanged.

@item 
@ref{b50,,pwrite()}: Write to a file descriptor from an offset, leaving
the file offset unchanged.

@item 
@ref{b4c,,readv()}: Read from a file descriptor into a number of writable buffers.

@item 
@ref{e29,,truncate()}: Truncate the file corresponding to `path', so that
it is at most `length' bytes in size.

@item 
@ref{d86,,waitid()}: Wait for the completion of one or more child processes.

@item 
@ref{b4f,,writev()}: Write the contents of `buffers' to a file descriptor,
where `buffers' is an arbitrary sequence of buffers.

@item 
@ref{10f4,,getgrouplist()} (bpo-9344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9344}): Return list of group ids that
specified user belongs to.
@end itemize

@item 
@ref{10f5,,times()} and @ref{10f6,,uname()}: Return type changed from a tuple to
a tuple-like object with named attributes.

@item 
Some platforms now support additional constants for the @ref{10f7,,lseek()}
function, such as @code{os.SEEK_HOLE} and @code{os.SEEK_DATA}.

@item 
New constants @ref{10f8,,RTLD_LAZY}, @ref{10f9,,RTLD_NOW},
@ref{10fa,,RTLD_GLOBAL}, @ref{10fb,,RTLD_LOCAL}, @ref{10fc,,RTLD_NODELETE},
@ref{10fd,,RTLD_NOLOAD}, and @ref{10fe,,RTLD_DEEPBIND} are available on
platforms that support them.   These are for use with the
@ref{10ff,,sys.setdlopenflags()} function, and supersede the similar constants
defined in @ref{2a,,ctypes} and @code{DLFCN}.  (Contributed by Victor Stinner
in bpo-13226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13226}.)

@item 
@ref{10d5,,os.symlink()} now accepts (and ignores) the @code{target_is_directory}
keyword argument on non-Windows platforms, to ease cross-platform support.
@end itemize

@node pdb<7>,pickle<5>,os<12>,Modules améliorés<11>
@anchor{whatsnew/3 3 pdb}@anchor{1100}
@subsubsection `pdb'


Tab-completion is now available not only for command names, but also their
arguments.  For example, for the @code{break} command, function and file names
are completed.

(Contribution par Georg Brandl; bpo-14210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14210}.)

@node pickle<5>,pydoc<5>,pdb<7>,Modules améliorés<11>
@anchor{whatsnew/3 3 pickle}@anchor{1101}
@subsubsection pickle


@ref{a0c,,pickle.Pickler} objects now have an optional
@ref{1102,,dispatch_table} attribute allowing per-pickler
reduction functions to be set.

(Contribution par Richard Oudkerk; bpo-14166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14166}.)

@node pydoc<5>,re<9>,pickle<5>,Modules améliorés<11>
@anchor{whatsnew/3 3 pydoc}@anchor{1103}
@subsubsection `pydoc'


The Tk GUI and the @code{serve()} function have been removed from the
@ref{b4,,pydoc} module: @code{pydoc -g} and @code{serve()} have been deprecated
in Python 3.2.

@node re<9>,sched,pydoc<5>,Modules améliorés<11>
@anchor{whatsnew/3 3 re}@anchor{1104}
@subsubsection @code{re}


@ref{435,,str} regular expressions now support @code{\u} and @code{\U} escapes.

(Contribution par Serhiy Storchaka; bpo-3665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3665}.)

@node sched,select<2>,re<9>,Modules améliorés<11>
@anchor{whatsnew/3 3 sched}@anchor{1105}
@subsubsection sched



@itemize *

@item 
@ref{1106,,run()} now accepts a `blocking' parameter which when
set to false makes the method execute the scheduled events due to expire
soonest (if any) and then return immediately.
This is useful in case you want to use the @ref{1107,,scheduler} in
non-blocking applications.  (Contributed by Giampaolo Rodolà in bpo-13449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13449}.)

@item 
@ref{1107,,scheduler} class can now be safely used in multi-threaded
environments.  (Contributed by Josiah Carlson and Giampaolo Rodolà in
bpo-8684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8684}.)

@item 
`timefunc' and `delayfunct' parameters of @ref{1107,,scheduler} class
constructor are now optional and defaults to @ref{251,,time.time()} and
@ref{688,,time.sleep()} respectively.  (Contributed by Chris Clark in
bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245}.)

@item 
@ref{1108,,enter()} and @ref{1109,,enterabs()}
`argument' parameter is now optional.  (Contributed by Chris Clark in
bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245}.)

@item 
@ref{1108,,enter()} and @ref{1109,,enterabs()}
now accept a `kwargs' parameter.  (Contributed by Chris Clark in
bpo-13245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13245}.)
@end itemize

@node select<2>,shlex<3>,sched,Modules améliorés<11>
@anchor{whatsnew/3 3 select}@anchor{110a}
@subsubsection select


Solaris and derivative platforms have a new class @ref{f80,,select.devpoll}
for high performance asynchronous sockets via @code{/dev/poll}.
(Contributed by Jesús Cea Avión in bpo-6397@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6397}.)

@node shlex<3>,shutils<7>,select<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 shlex}@anchor{110b}
@subsubsection shlex


The previously undocumented helper function @code{quote} from the
@code{pipes} modules has been moved to the @ref{c3,,shlex} module and
documented.  @ref{27a,,quote()} properly escapes all characters in a string
that might be otherwise given special meaning by the shell.

@node shutils<7>,signal<4>,shlex<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 shutil}@anchor{110c}
@subsubsection @code{shutils}



@itemize *

@item 
Nouvelles fonctions :


@itemize *

@item 
@ref{110d,,disk_usage()}: provides total, used and free disk space
statistics.  (Contributed by Giampaolo Rodolà in bpo-12442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12442}.)

@item 
@ref{23d,,chown()}: allows one to change user and/or group of the given
path also specifying the user/group names and not only their numeric
ids.  (Contributed by Sandro Tosi in bpo-12191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12191}.)

@item 
@ref{10e3,,shutil.get_terminal_size()}: returns the size of the terminal window
to which the interpreter is attached.  (Contributed by Zbigniew
Jędrzejewski-Szmek in bpo-13609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13609}.)
@end itemize

@item 
@ref{a49,,copy2()} and @ref{110e,,copystat()} now preserve file
timestamps with nanosecond precision on platforms that support it.
They also preserve file "extended attributes" on Linux.  (Contributed
by Larry Hastings in bpo-14127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14127} and  bpo-15238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15238}.)

@item 
Several functions now take an optional @code{symlinks} argument: when that
parameter is true, symlinks aren't dereferenced and the operation instead
acts on the symlink itself (or creates one, if relevant).
(Contributed by Hynek Schlawack in bpo-12715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12715}.)

@item 
When copying files to a different file system, @ref{a4a,,move()} now
handles symlinks the way the posix @code{mv} command does, recreating the
symlink rather than copying the target file contents.  (Contributed by
Jonathan Niehof in bpo-9993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9993}.)  @ref{a4a,,move()} now also returns
the @code{dst} argument as its result.

@item 
@ref{2f5,,rmtree()} is now resistant to symlink attacks on platforms
which support the new @code{dir_fd} parameter in @ref{d7f,,os.open()} and
@ref{10d6,,os.unlink()}.  (Contributed by Martin von Löwis and Hynek Schlawack
in bpo-4489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4489}.)
@end itemize

@node signal<4>,smtpd<4>,shutils<7>,Modules améliorés<11>
@anchor{whatsnew/3 3 signal}@anchor{110f}
@subsubsection `signal'



@itemize *

@item 
Le module @ref{c5,,signal} a de nouvelles fonctions :


@itemize *

@item 
@ref{1110,,pthread_sigmask()}: fetch and/or change the signal mask of the
calling thread (Contributed by Jean-Paul Calderone in bpo-8407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8407});

@item 
@ref{1111,,pthread_kill()}: send a signal to a thread;

@item 
@ref{1112,,sigpending()}: examine pending functions;

@item 
@ref{1113,,sigwait()}: wait a signal;

@item 
@ref{d98,,sigwaitinfo()}: wait for a signal, returning detailed
information about it;

@item 
@ref{d97,,sigtimedwait()}: like @ref{d98,,sigwaitinfo()} but with a
timeout.
@end itemize

@item 
The signal handler writes the signal number as a single byte instead of
a nul byte into the wakeup file descriptor. So it is possible to wait more
than one signal and know which signals were raised.

@item 
@ref{1114,,signal.signal()} and @ref{1115,,signal.siginterrupt()} raise an OSError,
instead of a RuntimeError: OSError has an errno attribute.
@end itemize

@node smtpd<4>,smtplib<4>,signal<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 smtpd}@anchor{1116}
@subsubsection smtpd


The @code{smtpd} module now supports 
@geindex RFC; RFC 5321
RFC 5321@footnote{https://datatracker.ietf.org/doc/html/rfc5321.html} (extended SMTP) and 
@geindex RFC; RFC 1870
RFC 1870@footnote{https://datatracker.ietf.org/doc/html/rfc1870.html}
(size extension).  Per the standard, these extensions are enabled if and only
if the client initiates the session with an @code{EHLO} command.

(Initial @code{ELHO} support by Alberto Trevino.  Size extension by Juhana
Jauhiainen.  Substantial additional work on the patch contributed by Michele
Orrù and Dan Boswell.  bpo-8739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8739})

@node smtplib<4>,socket<10>,smtpd<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 smtplib}@anchor{1117}
@subsubsection `smtplib'


The @ref{91a,,SMTP}, @ref{91b,,SMTP_SSL}, and
@ref{91c,,LMTP} classes now accept a @code{source_address} keyword argument
to specify the @code{(host, port)} to use as the source address in the bind call
when creating the outgoing socket.  (Contributed by Paulo Scardine in
bpo-11281@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11281}.)

@ref{91a,,SMTP} now supports the context management protocol, allowing an
@code{SMTP} instance to be used in a @code{with} statement.  (Contributed
by Giampaolo Rodolà in bpo-11289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11289}.)

The @ref{91b,,SMTP_SSL} constructor and the @ref{1118,,starttls()}
method now accept an SSLContext parameter to control parameters of the secure
channel.  (Contributed by Kasun Herath in bpo-8809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8809}.)

@node socket<10>,socketserver<3>,smtplib<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 socket}@anchor{1119}
@subsubsection `socket'



@itemize *

@item 
The @ref{d8e,,socket} class now exposes additional methods to process
ancillary data when supported by the underlying platform:


@itemize *

@item 
@ref{460,,sendmsg()}

@item 
@ref{d93,,recvmsg()}

@item 
@ref{111a,,recvmsg_into()}
@end itemize

(Contributed by David Watson in bpo-6560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6560}, based on an earlier patch by
Heiko Wundram)

@item 
The @ref{d8e,,socket} class now supports the PF_CAN protocol family
(@indicateurl{https://en.wikipedia.org/wiki/Socketcan}), on Linux
(@indicateurl{https://lwn.net/Articles/253425}).

(Contributed by Matthias Fuchs, updated by Tiago Gonçalves in bpo-10141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10141}.)

@item 
The @ref{d8e,,socket} class now supports the PF_RDS protocol family
(@indicateurl{https://en.wikipedia.org/wiki/Reliable_Datagram_Sockets} and
https://oss.oracle.com/projects/rds@footnote{https://web.archive.org/web/20130115155505/https://oss.oracle.com/projects/rds/}).

@item 
The @ref{d8e,,socket} class now supports the @code{PF_SYSTEM} protocol
family on OS X.  (Contributed by Michael Goderbauer in bpo-13777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13777}.)

@item 
New function @ref{111b,,sethostname()} allows the hostname to be set
on Unix systems if the calling process has sufficient privileges.
(Contributed by Ross Lagerwall in bpo-10866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10866}.)
@end itemize

@node socketserver<3>,sqlite3<10>,socket<10>,Modules améliorés<11>
@anchor{whatsnew/3 3 socketserver}@anchor{111c}
@subsubsection socketserver


@ref{111d,,BaseServer} now has an overridable method
@ref{111e,,service_actions()} that is called by the
@ref{111f,,serve_forever()} method in the service loop.
@ref{b65,,ForkingMixIn} now uses this to clean up zombie
child processes.  (Contributed by Justin Warkentin in bpo-11109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11109}.)

@node sqlite3<10>,ssl<11>,socketserver<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 sqlite3}@anchor{1120}
@subsubsection @code{sqlite3}


New @ref{242,,sqlite3.Connection} method
@ref{2aa,,set_trace_callback()} can be used to capture a trace of
all sql commands processed by sqlite.  (Contributed by Torsten Landschoff
in bpo-11688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11688}.)

@node ssl<11>,stat<2>,sqlite3<10>,Modules améliorés<11>
@anchor{whatsnew/3 3 ssl}@anchor{1121}
@subsubsection @code{ssl}



@itemize *

@item 
The @ref{cf,,ssl} module has two new random generation functions:


@itemize *

@item 
@ref{50d,,RAND_bytes()}: generate cryptographically strong
pseudo-random bytes.

@item 
@code{RAND_pseudo_bytes()}: generate pseudo-random bytes.
@end itemize

(Contribution par Victor Stinner; bpo-12049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12049}.)

@item 
The @ref{cf,,ssl} module now exposes a finer-grained exception hierarchy
in order to make it easier to inspect the various kinds of errors.
(Contributed by Antoine Pitrou in bpo-11183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11183}.)

@item 
@ref{292,,load_cert_chain()} now accepts a `password' argument
to be used if the private key is encrypted.
(Contributed by Adam Simpkins in bpo-12803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12803}.)

@item 
Diffie-Hellman key exchange, both regular and Elliptic Curve-based, is
now supported through the @ref{1122,,load_dh_params()} and
@ref{1123,,set_ecdh_curve()} methods.
(Contributed by Antoine Pitrou in bpo-13626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13626} and bpo-13627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13627}.)

@item 
SSL sockets have a new @ref{1124,,get_channel_binding()} method
allowing the implementation of certain authentication mechanisms such as
SCRAM-SHA-1-PLUS.  (Contributed by Jacek Konieczny in bpo-12551@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12551}.)

@item 
You can query the SSL compression algorithm used by an SSL socket, thanks
to its new @ref{1125,,compression()} method.  The new attribute
@ref{1126,,OP_NO_COMPRESSION} can be used to disable compression.
(Contributed by Antoine Pitrou in bpo-13634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13634}.)

@item 
Support has been added for the Next Protocol Negotiation extension using
the @ref{2f6,,ssl.SSLContext.set_npn_protocols()} method.
(Contributed by Colin Marc in bpo-14204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14204}.)

@item 
SSL errors can now be introspected more easily thanks to
@ref{1127,,library} and @ref{1128,,reason} attributes.
(Contributed by Antoine Pitrou in bpo-14837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14837}.)

@item 
The @ref{826,,get_server_certificate()} function now supports IPv6.
(Contributed by Charles-François Natali in bpo-11811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11811}.)

@item 
New attribute @ref{1129,,OP_CIPHER_SERVER_PREFERENCE} allows setting
SSLv3 server sockets to use the server's cipher ordering preference rather
than the client's (bpo-13635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13635}).
@end itemize

@node stat<2>,struct<3>,ssl<11>,Modules améliorés<11>
@anchor{whatsnew/3 3 stat}@anchor{112a}
@subsubsection stat


The undocumented tarfile.filemode function has been moved to
@ref{112b,,stat.filemode()}. It can be used to convert a file's mode to a string of
the form '-rwxrwxrwx'.

(Contribution par Giampaolo Rodolà; bpo-14807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14807}.)

@node struct<3>,subprocess<6>,stat<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 struct}@anchor{112c}
@subsubsection struct


The @ref{d4,,struct} module now supports @code{ssize_t} and @code{size_t} via the
new codes @code{n} and @code{N}, respectively.  (Contributed by Antoine Pitrou
in bpo-3163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3163}.)

@node subprocess<6>,sys<13>,struct<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 subprocess}@anchor{112d}
@subsubsection subprocess


Command strings can now be bytes objects on posix platforms.  (Contributed by
Victor Stinner in bpo-8513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8513}.)

A new constant @ref{112e,,DEVNULL} allows suppressing output in a
platform-independent fashion.  (Contributed by Ross Lagerwall in
bpo-5870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5870}.)

@node sys<13>,tarfile<8>,subprocess<6>,Modules améliorés<11>
@anchor{whatsnew/3 3 sys}@anchor{112f}
@subsubsection sys


The @ref{d8,,sys} module has a new @ref{1130,,thread_info} @ref{639,,named tuple} holding information about the thread implementation
(bpo-11223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11223}).

@node tarfile<8>,tempfile<4>,sys<13>,Modules améliorés<11>
@anchor{whatsnew/3 3 tarfile}@anchor{1131}
@subsubsection tarfile


@ref{dd,,tarfile} now supports @code{lzma} encoding via the @ref{89,,lzma} module.
(Contributed by Lars Gustäbel in bpo-5689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5689}.)

@node tempfile<4>,textwrap<2>,tarfile<8>,Modules améliorés<11>
@anchor{whatsnew/3 3 tempfile}@anchor{1132}
@subsubsection tempfile


@ref{67e,,tempfile.SpooledTemporaryFile}'s
@code{truncate()} method now accepts
a @code{size} parameter.  (Contributed by Ryan Kelly in bpo-9957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9957}.)

@node textwrap<2>,threading<8>,tempfile<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 textwrap}@anchor{1133}
@subsubsection textwrap


The @ref{eb,,textwrap} module has a new @ref{273,,indent()} that makes
it straightforward to add a common prefix to selected lines in a block
of text  (bpo-13857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13857}).

@node threading<8>,time<8>,textwrap<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 threading}@anchor{1134}
@subsubsection threading


@ref{1135,,threading.Condition}, @ref{1136,,threading.Semaphore},
@ref{1137,,threading.BoundedSemaphore}, @ref{1138,,threading.Event}, and
@ref{1139,,threading.Timer}, all of which used to be factory functions returning a
class instance, are now classes and may be subclassed.  (Contributed by Éric
Araujo in bpo-10968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10968}.)

The @ref{939,,threading.Thread} constructor now accepts a @code{daemon} keyword
argument to override the default behavior of inheriting the @code{daemon} flag
value from the parent thread (bpo-6064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6064}).

The formerly private function @code{_thread.get_ident} is now available as the
public function @ref{113a,,threading.get_ident()}.  This eliminates several cases of
direct access to the @code{_thread} module in the stdlib.  Third party code that
used @code{_thread.get_ident} should likewise be changed to use the new public
interface.

@node time<8>,types<7>,threading<8>,Modules améliorés<11>
@anchor{whatsnew/3 3 time}@anchor{113b}
@subsubsection time


The 
@geindex Python Enhancement Proposals; PEP 418
PEP 418@footnote{https://peps.python.org/pep-0418/} added new functions to the @ref{ed,,time} module:


@itemize *

@item 
@ref{113c,,get_clock_info()}: Get information on a clock.

@item 
@ref{250,,monotonic()}: Monotonic clock (cannot go backward), not affected
by system clock updates.

@item 
@ref{a76,,perf_counter()}: Performance counter with the highest available
resolution to measure a short duration.

@item 
@ref{a77,,process_time()}: Sum of the system and user CPU time of the
current process.
@end itemize

Other new functions:


@itemize *

@item 
@ref{113d,,clock_getres()}, @ref{113e,,clock_gettime()} and
@ref{113f,,clock_settime()} functions with @code{CLOCK_@var{xxx}} constants.
(Contributed by Victor Stinner in bpo-10278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10278}.)
@end itemize

To improve cross platform consistency, @ref{688,,sleep()} now raises a
@ref{1ff,,ValueError} when passed a negative sleep value.  Previously this was an
error on posix, but produced an infinite sleep on Windows.

@node types<7>,unittest<10>,time<8>,Modules améliorés<11>
@anchor{whatsnew/3 3 types}@anchor{1140}
@subsubsection @code{types}


Add a new @ref{457,,types.MappingProxyType} class: Read-only proxy of a mapping.
(bpo-14386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14386})

The new functions @ref{1141,,types.new_class()} and @ref{1142,,types.prepare_class()} provide support
for 
@geindex Python Enhancement Proposals; PEP 3115
PEP 3115@footnote{https://peps.python.org/pep-3115/} compliant dynamic type creation. (bpo-14588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14588})

@node unittest<10>,urllib<4>,types<7>,Modules améliorés<11>
@anchor{whatsnew/3 3 unittest}@anchor{1143}
@subsubsection unittest


@ref{516,,assertRaises()}, @ref{518,,assertRaisesRegex()}, @ref{1144,,assertWarns()}, and
@ref{1145,,assertWarnsRegex()} now accept a keyword argument `msg' when used as
context managers.  (Contributed by Ezio Melotti and Winston Ewert in
bpo-10775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10775}.)

@ref{1146,,unittest.TestCase.run()} now returns the @ref{1147,,TestResult}
object.

@node urllib<4>,webbrowser<3>,unittest<10>,Modules améliorés<11>
@anchor{whatsnew/3 3 urllib}@anchor{1148}
@subsubsection urllib


The @ref{fc3,,Request} class, now accepts a `method' argument
used by @ref{1149,,get_method()} to determine what HTTP method
should be used.  For example, this will send a @code{'HEAD'} request:

@example
>>> urlopen(Request('https://www.python.org', method='HEAD'))
@end example

(bpo-1673007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1673007})

@node webbrowser<3>,xml etree ElementTree<2>,urllib<4>,Modules améliorés<11>
@anchor{whatsnew/3 3 webbrowser}@anchor{114a}
@subsubsection webbrowser


The @ref{114,,webbrowser} module supports more "browsers": Google Chrome (named
@code{chrome}, @code{chromium}, @code{chrome-browser} or
@code{chromium-browser} depending on the version and operating system),
and the generic launchers @code{xdg-open}, from the FreeDesktop.org
project, and @code{gvfs-open}, which is the default URI handler for GNOME
3.  (The former contributed by Arnaud Calmettes in bpo-13620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13620}, the latter
by Matthias Klose in bpo-14493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14493}.)

@node xml etree ElementTree<2>,zlib<2>,webbrowser<3>,Modules améliorés<11>
@anchor{whatsnew/3 3 xml-etree-elementtree}@anchor{114b}
@subsubsection xml.etree.ElementTree


The @ref{124,,xml.etree.ElementTree} module now imports its C accelerator by
default; there is no longer a need to explicitly import
@code{xml.etree.cElementTree} (this module stays for backwards compatibility,
but is now deprecated).  In addition,  the @code{iter} family of methods of
@ref{305,,Element} has been optimized (rewritten in C).
The module's documentation has also been greatly improved with added examples
and a more detailed reference.

@node zlib<2>,,xml etree ElementTree<2>,Modules améliorés<11>
@anchor{whatsnew/3 3 zlib}@anchor{114c}
@subsubsection zlib


New attribute @ref{114d,,zlib.Decompress.eof} makes it possible to distinguish
between a properly formed compressed stream and an incomplete or truncated one.
(Contributed by Nadeem Vawda in bpo-12646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12646}.)

New attribute @ref{114e,,zlib.ZLIB_RUNTIME_VERSION} reports the version string of
the underlying @code{zlib} library that is loaded at runtime.  (Contributed by
Torsten Landschoff in bpo-12306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12306}.)

@node Optimizations<5>,Build and C API Changes<4>,Modules améliorés<11>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 optimizations}@anchor{114f}
@subsection Optimizations


Major performance enhancements have been added:


@itemize *

@item 
Thanks to 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, some operations on Unicode strings have been optimized:


@itemize *

@item 
the memory footprint is divided by 2 to 4 depending on the text

@item 
encode an ASCII string to UTF-8 doesn't need to encode characters anymore,
the UTF-8 representation is shared with the ASCII representation

@item 
l’encodeur UTF-8 a été optimisé

@item 
repeating a single ASCII letter and getting a substring of an ASCII string
is 4 times faster
@end itemize

@item 
UTF-8 is now 2x to 4x faster.  UTF-16 encoding is now up to 10x faster.

(Contributed by Serhiy Storchaka, bpo-14624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14624}, bpo-14738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14738} and
bpo-15026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15026}.)
@end itemize

@node Build and C API Changes<4>,Obsolescence<12>,Optimizations<5>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 build-and-c-api-changes}@anchor{1031}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
New 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} related function:


@itemize *

@item 
@ref{1150,,PyMemoryView_FromMemory()}
@end itemize

@item 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} added new Unicode types, macros and functions:


@itemize *

@item 
High-level API:


@itemize *

@item 
@ref{8a2,,PyUnicode_CopyCharacters()}

@item 
@ref{8a6,,PyUnicode_FindChar()}

@item 
@ref{8a0,,PyUnicode_GetLength()}, @ref{8a1,,PyUnicode_GET_LENGTH}

@item 
@ref{898,,PyUnicode_New()}

@item 
@ref{8a3,,PyUnicode_Substring()}

@item 
@ref{1151,,PyUnicode_ReadChar()}, @ref{1152,,PyUnicode_WriteChar()}
@end itemize

@item 
Low-level API:


@itemize *

@item 
@ref{1153,,Py_UCS1}, @ref{1154,,Py_UCS2}, @ref{298,,Py_UCS4} types

@item 
@ref{1155,,PyASCIIObject} and @ref{1156,,PyCompactUnicodeObject} structures

@item 
@ref{3f7,,PyUnicode_READY}

@item 
@ref{1157,,PyUnicode_FromKindAndData()}

@item 
@ref{1158,,PyUnicode_AsUCS4()}, @ref{8a8,,PyUnicode_AsUCS4Copy()}

@item 
@ref{1159,,PyUnicode_DATA}, @ref{115a,,PyUnicode_1BYTE_DATA},
@ref{115b,,PyUnicode_2BYTE_DATA}, @ref{115c,,PyUnicode_4BYTE_DATA}

@item 
@ref{115d,,PyUnicode_KIND} with @code{PyUnicode_Kind} enum:
@code{PyUnicode_WCHAR_KIND}, @ref{115e,,PyUnicode_1BYTE_KIND},
@ref{115f,,PyUnicode_2BYTE_KIND}, @ref{1160,,PyUnicode_4BYTE_KIND}

@item 
@ref{1161,,PyUnicode_READ}, @ref{1162,,PyUnicode_READ_CHAR}, @ref{1163,,PyUnicode_WRITE}

@item 
@ref{1164,,PyUnicode_MAX_CHAR_VALUE}
@end itemize
@end itemize

@item 
@ref{55d,,PyArg_ParseTuple} now accepts a @ref{528,,bytearray} for the @code{c}
format (bpo-12380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12380}).
@end itemize

@node Obsolescence<12>,Portage vers Python 3 3,Build and C API Changes<4>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 deprecated}@anchor{1165}
@subsection Obsolescence


@menu
* Unsupported Operating Systems: Unsupported Operating Systems<2>. 
* Deprecated Python modules@comma{} functions and methods: Deprecated Python modules functions and methods<4>. 
* Deprecated functions and types of the C API: Deprecated functions and types of the C API<3>. 
* Fonctionnalités obsolètes: Fonctionnalités obsolètes<2>. 

@end menu

@node Unsupported Operating Systems<2>,Deprecated Python modules functions and methods<4>,,Obsolescence<12>
@anchor{whatsnew/3 3 unsupported-operating-systems}@anchor{1166}
@subsubsection Unsupported Operating Systems


OS/2 and VMS are no longer supported due to the lack of a maintainer.

Windows 2000 and Windows platforms which set @code{COMSPEC} to @code{command.com}
are no longer supported due to maintenance burden.

OSF support, which was deprecated in 3.2, has been completely removed.

@node Deprecated Python modules functions and methods<4>,Deprecated functions and types of the C API<3>,Unsupported Operating Systems<2>,Obsolescence<12>
@anchor{whatsnew/3 3 deprecated-python-modules-functions-and-methods}@anchor{1167}
@subsubsection Deprecated Python modules, functions and methods



@itemize *

@item 
Passing a non-empty string to @code{object.__format__()} is deprecated, and
will produce a @ref{522,,TypeError} in Python 3.4 (bpo-9856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9856}).

@item 
The @code{unicode_internal} codec has been deprecated because of the
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, use UTF-8, UTF-16 (@code{utf-16-le} or @code{utf-16-be}), or UTF-32
(@code{utf-32-le} or @code{utf-32-be})

@item 
@ref{10a5,,ftplib.FTP.nlst()} and @ref{10a6,,ftplib.FTP.dir()}: use
@ref{10a4,,ftplib.FTP.mlsd()}

@item 
@code{platform.popen()}: use the @ref{d5,,subprocess} module. Check especially
the @ref{1168,,Remplacer les fonctions plus anciennes par le module subprocess} section (bpo-11377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11377}).

@item 
bpo-13374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13374}: The Windows bytes API has been deprecated in the @ref{a0,,os}
module. Use Unicode filenames, instead of bytes filenames, to not depend on
the ANSI code page anymore and to support any filename.

@item 
bpo-13988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13988}: The @code{xml.etree.cElementTree} module is deprecated.  The
accelerator is used automatically whenever available.

@item 
The behaviour of @code{time.clock()} depends on the platform: use the new
@ref{a76,,time.perf_counter()} or @ref{a77,,time.process_time()} function instead,
depending on your requirements, to have a well defined behaviour.

@item 
The @code{os.stat_float_times()} function is deprecated.

@item 
@ref{4,,abc} module:


@itemize *

@item 
@ref{106e,,abc.abstractproperty} has been deprecated, use @ref{192,,property}
with @ref{106f,,abc.abstractmethod()} instead.

@item 
@ref{1070,,abc.abstractclassmethod} has been deprecated, use
@ref{165,,classmethod} with @ref{106f,,abc.abstractmethod()} instead.

@item 
@ref{1071,,abc.abstractstaticmethod} has been deprecated, use
@ref{40c,,staticmethod} with @ref{106f,,abc.abstractmethod()} instead.
@end itemize

@item 
@ref{76,,importlib} package:


@itemize *

@item 
@ref{1169,,importlib.abc.SourceLoader.path_mtime()} is now deprecated in favour of
@ref{116a,,importlib.abc.SourceLoader.path_stats()} as bytecode files now store
both the modification time and size of the source file the bytecode file was
compiled from.
@end itemize
@end itemize

@node Deprecated functions and types of the C API<3>,Fonctionnalités obsolètes<2>,Deprecated Python modules functions and methods<4>,Obsolescence<12>
@anchor{whatsnew/3 3 deprecated-functions-and-types-of-the-c-api}@anchor{116b}
@subsubsection Deprecated functions and types of the C API


The @ref{3e4,,Py_UNICODE} has been deprecated by 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} and will be
removed in Python 4. All functions using this type are deprecated:

Unicode functions and methods using @ref{3e4,,Py_UNICODE} and
@ref{3e4,,Py_UNICODE}* types:


@itemize *

@item 
@code{PyUnicode_FromUnicode}: use @ref{116c,,PyUnicode_FromWideChar()} or
@ref{1157,,PyUnicode_FromKindAndData()}

@item 
@code{PyUnicode_AS_UNICODE}, @code{PyUnicode_AsUnicode()},
@code{PyUnicode_AsUnicodeAndSize()}: use @ref{8a9,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_AS_DATA}: use @ref{1159,,PyUnicode_DATA} with
@ref{1161,,PyUnicode_READ} and @ref{1163,,PyUnicode_WRITE}

@item 
@code{PyUnicode_GET_SIZE}, @code{PyUnicode_GetSize()}: use
@ref{8a1,,PyUnicode_GET_LENGTH} or @ref{8a0,,PyUnicode_GetLength()}

@item 
@code{PyUnicode_GET_DATA_SIZE}: use
@code{PyUnicode_GET_LENGTH(str) * PyUnicode_KIND(str)} (only work on ready
strings)

@item 
@code{PyUnicode_AsUnicodeCopy()}: use @ref{8a8,,PyUnicode_AsUCS4Copy()} or
@ref{8a9,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_GetMax()}
@end itemize

Functions and macros manipulating Py_UNICODE* strings:


@itemize *

@item 
@code{Py_UNICODE_strlen()}: use @ref{8a0,,PyUnicode_GetLength()} or
@ref{8a1,,PyUnicode_GET_LENGTH}

@item 
@code{Py_UNICODE_strcat()}: use @ref{8a2,,PyUnicode_CopyCharacters()} or
@ref{380,,PyUnicode_FromFormat()}

@item 
@code{Py_UNICODE_strcpy()}, @code{Py_UNICODE_strncpy()},
@code{Py_UNICODE_COPY()}: use @ref{8a2,,PyUnicode_CopyCharacters()} or
@ref{8a3,,PyUnicode_Substring()}

@item 
@code{Py_UNICODE_strcmp()}: use @ref{8a4,,PyUnicode_Compare()}

@item 
@code{Py_UNICODE_strncmp()}: use @ref{8a5,,PyUnicode_Tailmatch()}

@item 
@code{Py_UNICODE_strchr()}, @code{Py_UNICODE_strrchr()}: use
@ref{8a6,,PyUnicode_FindChar()}

@item 
@code{Py_UNICODE_FILL()}: use @ref{116d,,PyUnicode_Fill()}

@item 
@code{Py_UNICODE_MATCH}
@end itemize

Encodeurs :


@itemize *

@item 
@code{PyUnicode_Encode()}: use @code{PyUnicode_AsEncodedObject()}

@item 
@code{PyUnicode_EncodeUTF7()}

@item 
@code{PyUnicode_EncodeUTF8()}: use @ref{ba9,,PyUnicode_AsUTF8()} or
@ref{116e,,PyUnicode_AsUTF8String()}

@item 
@code{PyUnicode_EncodeUTF32()}

@item 
@code{PyUnicode_EncodeUTF16()}

@item 
@code{PyUnicode_EncodeUnicodeEscape()} use
@ref{116f,,PyUnicode_AsUnicodeEscapeString()}

@item 
@code{PyUnicode_EncodeRawUnicodeEscape()} use
@ref{1170,,PyUnicode_AsRawUnicodeEscapeString()}

@item 
@code{PyUnicode_EncodeLatin1()}: use @ref{1171,,PyUnicode_AsLatin1String()}

@item 
@code{PyUnicode_EncodeASCII()}: use @ref{1172,,PyUnicode_AsASCIIString()}

@item 
@code{PyUnicode_EncodeCharmap()}

@item 
@code{PyUnicode_TranslateCharmap()}

@item 
@code{PyUnicode_EncodeMBCS()}: use @ref{1173,,PyUnicode_AsMBCSString()} or
@ref{1174,,PyUnicode_EncodeCodePage()} (with @code{CP_ACP} code_page)

@item 
@code{PyUnicode_EncodeDecimal()},
@code{PyUnicode_TransformDecimalToASCII()}
@end itemize

@node Fonctionnalités obsolètes<2>,,Deprecated functions and types of the C API<3>,Obsolescence<12>
@anchor{whatsnew/3 3 deprecated-features}@anchor{1175}
@subsubsection Fonctionnalités obsolètes


The @ref{7,,array} module's @code{'u'} format code is now deprecated and will be
removed in Python 4 together with the rest of the (@ref{3e4,,Py_UNICODE}) API.

@node Portage vers Python 3 3,,Obsolescence<12>,Nouveautés de Python 3 3
@anchor{whatsnew/3 3 porting-to-python-3-3}@anchor{1176}
@subsection Portage vers Python 3.3


Cette section liste les changements mentionnés préalablement et d'autres améliorations qui peuvent demander des changements à votre code.

@menu
* Portage de code Python:: 
* Porting C code:: 
* Building C extensions:: 
* Command Line Switch Changes:: 

@end menu

@node Portage de code Python,Porting C code,,Portage vers Python 3 3
@anchor{whatsnew/3 3 porting-python-code}@anchor{1057}@anchor{whatsnew/3 3 portingpythoncode}@anchor{1177}
@subsubsection Portage de code Python



@itemize *

@item 
Hash randomization is enabled by default. Set the 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED}
environment variable to @code{0} to disable hash randomization. See also the
@ref{ae9,,object.__hash__()} method.

@item 
bpo-12326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12326}: On Linux, sys.platform doesn't contain the major version
anymore. It is now always 'linux', instead of 'linux2' or 'linux3' depending
on the Linux version used to build Python. Replace sys.platform == 'linux2'
with sys.platform.startswith('linux'), or directly sys.platform == 'linux' if
you don't need to support older Python versions.

@item 
bpo-13847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13847}, bpo-14180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14180}: @ref{ed,,time} and @ref{30,,datetime}:
@ref{86d,,OverflowError} is now raised instead of @ref{1ff,,ValueError} if a
timestamp is out of range. @ref{40d,,OSError} is now raised if C functions
@code{gmtime()} or @code{localtime()} failed.

@item 
The default finders used by import now utilize a cache of what is contained
within a specific directory. If you create a Python source file or sourceless
bytecode file, make sure to call @ref{bfe,,importlib.invalidate_caches()} to clear
out the cache for the finders to notice the new file.

@item 
@ref{40f,,ImportError} now uses the full name of the module that was attempted to
be imported. Doctests that check ImportErrors' message will need to be
updated to use the full name of the module instead of just the tail of the
name.

@item 
The `index' argument to @ref{8c1,,__import__()} now defaults to 0 instead of -1
and no longer support negative values. It was an oversight when 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} was
implemented that the default value remained -1. If you need to continue to
perform a relative import followed by an absolute import, then perform the
relative import using an index of 1, followed by another import using an
index of 0. It is preferred, though, that you use
@ref{501,,importlib.import_module()} rather than call @ref{8c1,,__import__()} directly.

@item 
@ref{8c1,,__import__()} no longer allows one to use an index value other than 0
for top-level modules. E.g. @code{__import__('sys', level=1)} is now an error.

@item 
Because @ref{d19,,sys.meta_path} and @ref{100d,,sys.path_hooks} now have finders on
them by default, you will most likely want to use @code{list.insert()} instead
of @code{list.append()} to add to those lists.

@item 
Because @code{None} is now inserted into @ref{5ce,,sys.path_importer_cache}, if you
are clearing out entries in the dictionary of paths that do not have a
finder, you will need to remove keys paired with values of @code{None} `and'
@code{imp.NullImporter} to be backwards-compatible. This will lead to extra
overhead on older versions of Python that re-insert @code{None} into
@ref{5ce,,sys.path_importer_cache} where it represents the use of implicit
finders, but semantically it should not change anything.

@item 
@code{importlib.abc.Finder} no longer specifies a @code{find_module()} abstract
method that must be implemented. If you were relying on subclasses to
implement that method, make sure to check for the method's existence first.
You will probably want to check for @code{find_loader()} first, though, in the
case of working with @ref{105a,,path entry finders}.

@item 
@ref{a8,,pkgutil} has been converted to use @ref{76,,importlib} internally. This
eliminates many edge cases where the old behaviour of the 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} import
emulation failed to match the behaviour of the real import system. The
import emulation itself is still present, but is now deprecated. The
@ref{1178,,pkgutil.iter_importers()} and @ref{bed,,pkgutil.walk_packages()} functions
special case the standard import hooks so they are still supported even
though they do not provide the non-standard @code{iter_modules()} method.

@item 
A longstanding RFC-compliance bug (bpo-1079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1079}) in the parsing done by
@ref{109a,,email.header.decode_header()} has been fixed.  Code that uses the
standard idiom to convert encoded headers into unicode
(@code{str(make_header(decode_header(h))}) will see no change, but code that
looks at the individual tuples returned by decode_header will see that
whitespace that precedes or follows @code{ASCII} sections is now included in the
@code{ASCII} section.  Code that builds headers using @code{make_header} should
also continue to work without change, since @code{make_header} continues to add
whitespace between @code{ASCII} and non-@code{ASCII} sections if it is not already
present in the input strings.

@item 
@ref{1179,,email.utils.formataddr()} now does the correct content transfer
encoding when passed non-@code{ASCII} display names.  Any code that depended on
the previous buggy behavior that preserved the non-@code{ASCII} unicode in the
formatted output string will need to be changed (bpo-1690608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1690608}).

@item 
@ref{117a,,poplib.POP3.quit()} may now raise protocol errors like all other
@code{poplib} methods.  Code that assumes @code{quit} does not raise
@ref{117b,,poplib.error_proto} errors may need to be changed if errors on @code{quit}
are encountered by a particular application (bpo-11291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11291}).

@item 
The @code{strict} argument to @ref{117c,,email.parser.Parser}, deprecated since
Python 2.4, has finally been removed.

@item 
The deprecated method @code{unittest.TestCase.assertSameElements} has been
removed.

@item 
The deprecated variable @code{time.accept2dyear} has been removed.

@item 
The deprecated @code{Context._clamp} attribute has been removed from the
@ref{36,,decimal} module.  It was previously replaced by the public attribute
@code{clamp}.  (See bpo-8540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8540}.)

@item 
The undocumented internal helper class @code{SSLFakeFile} has been removed
from @ref{c9,,smtplib}, since its functionality has long been provided directly
by @ref{117d,,socket.socket.makefile()}.

@item 
Passing a negative value to @ref{688,,time.sleep()} on Windows now raises an
error instead of sleeping forever.  It has always raised an error on posix.

@item 
The @code{ast.__version__} constant has been removed.  If you need to
make decisions affected by the AST version, use @ref{68b,,sys.version_info}
to make the decision.

@item 
Code that used to work around the fact that the @ref{ec,,threading} module used
factory functions by subclassing the private classes will need to change to
subclass the now-public classes.

@item 
The undocumented debugging machinery in the threading module has been
removed, simplifying the code.  This should have no effect on production
code, but is mentioned here in case any application debug frameworks were
interacting with it (bpo-13550@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13550}).
@end itemize

@node Porting C code,Building C extensions,Portage de code Python,Portage vers Python 3 3
@anchor{whatsnew/3 3 porting-c-code}@anchor{1032}
@subsubsection Porting C code



@itemize *

@item 
In the course of changes to the buffer API the undocumented
@code{smalltable} member of the
@ref{742,,Py_buffer} structure has been removed and the
layout of the @code{PyMemoryViewObject} has changed.

All extensions relying on the relevant parts in @code{memoryobject.h}
or @code{object.h} must be rebuilt.

@item 
Due to @ref{1026,,PEP 393}, the @ref{3e4,,Py_UNICODE} type and all
functions using this type are deprecated (but will stay available for
at least five years).  If you were using low-level Unicode APIs to
construct and access unicode objects and you want to benefit of the
memory footprint reduction provided by 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, you have to convert
your code to the new @ref{117e,,Unicode API}.

However, if you only have been using high-level functions such as
@ref{117f,,PyUnicode_Concat()}, @ref{1180,,PyUnicode_Join()} or
@ref{380,,PyUnicode_FromFormat()}, your code will automatically take
advantage of the new unicode representations.

@item 
@ref{1181,,PyImport_GetMagicNumber()} now returns @code{-1} upon failure.

@item 
As a negative value for the `level' argument to @ref{8c1,,__import__()} is no
longer valid, the same now holds for @ref{1182,,PyImport_ImportModuleLevel()}.
This also means that the value of `level' used by
@ref{1183,,PyImport_ImportModuleEx()} is now @code{0} instead of @code{-1}.
@end itemize

@node Building C extensions,Command Line Switch Changes,Porting C code,Portage vers Python 3 3
@anchor{whatsnew/3 3 building-c-extensions}@anchor{1184}
@subsubsection Building C extensions



@itemize *

@item 
The range of possible file names for C extensions has been narrowed.
Very rarely used spellings have been suppressed: under POSIX, files
named @code{xxxmodule.so}, @code{xxxmodule.abi3.so} and
@code{xxxmodule.cpython-*.so} are no longer recognized as implementing
the @code{xxx} module.  If you had been generating such files, you have
to switch to the other spellings (i.e., remove the @code{module} string
from the file names).

(implemented in bpo-14040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14040}.)
@end itemize

@node Command Line Switch Changes,,Building C extensions,Portage vers Python 3 3
@anchor{whatsnew/3 3 command-line-switch-changes}@anchor{1185}
@subsubsection Command Line Switch Changes



@itemize *

@item 
The -Q command-line flag and related artifacts have been removed.  Code
checking sys.flags.division_warning will need updating.

(bpo-10998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10998}, contributed by Éric Araujo.)

@item 
When @code{python} is started with @ref{1186,,-S}, @code{import site}
will no longer add site-specific paths to the module search paths.  In
previous versions, it did.

(bpo-11591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11591}, contributed by Carl Meyer with editions by Éric Araujo.)
@end itemize

@node Nouveautés de Python 3 2,Nouveautés de Python 3 1,Nouveautés de Python 3 3,Nouveautés de Python
@anchor{whatsnew/3 2 doc}@anchor{1187}@anchor{whatsnew/3 2 what-s-new-in-python-3-2}@anchor{1188}
@section Nouveautés de Python 3.2


@*Auteur: 
Raymond Hettinger


@c $Id$
@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten.  (Note, during release candidate phase or just before
@c a beta release, please use the tracker instead -- this helps avoid
@c merge conflicts.   If you must add a suggested entry directly,
@c please put it in an XXX comment and the maintainer will take notice).
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.  It's helpful to
@c add the issue number:
@c 
@c   XXX Describe the transmogrify() function added to the socket
@c   module.
@c 
@c   (Contributed by P.Y. Developer; :issue:`12345`.)
@c 
@c This saves the maintainer the effort of going through the SVN log
@c when researching a change.

This article explains the new features in Python 3.2 as compared to 3.1.
Python 3.2 was released on February 20, 2011. It
focuses on a few highlights and gives a few examples.  For full details, see the
Misc/NEWS@footnote{https://github.com/python/cpython/blob/076ca6c3c8df3030307e548d9be792ce3c1c6eea/Misc/NEWS}
file.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 392
PEP 392@footnote{https://peps.python.org/pep-0392/} - Python 3.2 Release Schedule


@menu
* PEP 384; Defining a Stable ABI: PEP 384 Defining a Stable ABI. 
* PEP 389; Argparse Command Line Parsing Module: PEP 389 Argparse Command Line Parsing Module. 
* PEP 391; Dictionary Based Configuration for Logging: PEP 391 Dictionary Based Configuration for Logging. 
* PEP 3148; The concurrent.futures module: PEP 3148 The concurrent futures module. 
* PEP 3147; PYC Repository Directories: PEP 3147 PYC Repository Directories. 
* PEP 3149; ABI Version Tagged .so Files: PEP 3149 ABI Version Tagged so Files. 
* PEP 3333; Python Web Server Gateway Interface v1.0.1: PEP 3333 Python Web Server Gateway Interface v1 0 1. 
* Autres changements au langage: Autres changements au langage<12>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules. 
* Fils d'exécution:: 
* Optimizations: Optimizations<6>. 
* Unicode:: 
* Codecs:: 
* Documentation:: 
* IDLE:: 
* Code Repository:: 
* Build and C API Changes: Build and C API Changes<5>. 
* Portage vers Python 3.2: Portage vers Python 3 2. 

@end menu

@node PEP 384 Defining a Stable ABI,PEP 389 Argparse Command Line Parsing Module,,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-384-defining-a-stable-abi}@anchor{1189}
@subsection PEP 384: Defining a Stable ABI


In the past, extension modules built for one Python version were often
not usable with other Python versions. Particularly on Windows, every
feature release of Python required rebuilding all extension modules that
one wanted to use. This requirement was the result of the free access to
Python interpreter internals that extension modules could use.

With Python 3.2, an alternative approach becomes available: extension
modules which restrict themselves to a limited API (by defining
Py_LIMITED_API) cannot use many of the internals, but are constrained
to a set of API functions that are promised to be stable for several
releases. As a consequence, extension modules built for 3.2 in that
mode will also work with 3.3, 3.4, and so on. Extension modules that
make use of details of memory structures can still be built, but will
need to be recompiled for every feature release.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 384

@item PEP 384@footnote{https://peps.python.org/pep-0384/} - Defining a Stable ABI

PEP written by Martin von Löwis.
@end table


@node PEP 389 Argparse Command Line Parsing Module,PEP 391 Dictionary Based Configuration for Logging,PEP 384 Defining a Stable ABI,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-389-argparse-command-line-parsing-module}@anchor{118a}
@subsection PEP 389: Argparse Command Line Parsing Module


A new module for command line parsing, @ref{6,,argparse}, was introduced to
overcome the limitations of @ref{9f,,optparse} which did not provide support for
positional arguments (not just options), subcommands, required options and other
common patterns of specifying and validating options.

This module has already had widespread success in the community as a
third-party module.  Being more fully featured than its predecessor, the
@ref{6,,argparse} module is now the preferred module for command-line processing.
The older module is still being kept available because of the substantial amount
of legacy code that depends on it.

Here's an annotated example parser showing features like limiting results to a
set of choices, specifying a `metavar' in the help screen, validating that one
or more positional arguments is present, and making a required option:

@example
import argparse
parser = argparse.ArgumentParser(
            description = 'Manage servers',         # main description for help
            epilog = 'Tested on Solaris and Linux') # displayed after help
parser.add_argument('action',                       # argument name
            choices = ['deploy', 'start', 'stop'],  # three allowed values
            help = 'action on each target')         # help msg
parser.add_argument('targets',
            metavar = 'HOSTNAME',                   # var name used in help msg
            nargs = '+',                            # require one or more targets
            help = 'url for target machines')       # help msg explanation
parser.add_argument('-u', '--user',                 # -u or --user option
            required = True,                        # make it a required argument
            help = 'login as user')
@end example

Example of calling the parser on a command string:

@example
>>> cmd = 'deploy sneezy.example.com sleepy.example.com -u skycaptain'
>>> result = parser.parse_args(cmd.split())
>>> result.action
'deploy'
>>> result.targets
['sneezy.example.com', 'sleepy.example.com']
>>> result.user
'skycaptain'
@end example

Example of the parser's automatically generated help:

@example
>>> parser.parse_args('-h'.split())

usage: manage_cloud.py [-h] -u USER
                       @{deploy,start,stop@} HOSTNAME [HOSTNAME ...]

Manage servers

positional arguments:
  @{deploy,start,stop@}   action on each target
  HOSTNAME              url for target machines

optional arguments:
  -h, --help            show this help message and exit
  -u USER, --user USER  login as user

Tested on Solaris and Linux
@end example

An especially nice @ref{6,,argparse} feature is the ability to define subparsers,
each with their own argument patterns and help displays:

@example
import argparse
parser = argparse.ArgumentParser(prog='HELM')
subparsers = parser.add_subparsers()

parser_l = subparsers.add_parser('launch', help='Launch Control')   # first subgroup
parser_l.add_argument('-m', '--missiles', action='store_true')
parser_l.add_argument('-t', '--torpedos', action='store_true')

parser_m = subparsers.add_parser('move', help='Move Vessel',        # second subgroup
                                 aliases=('steer', 'turn'))         # equivalent names
parser_m.add_argument('-c', '--course', type=int, required=True)
parser_m.add_argument('-s', '--speed', type=int, default=0)
@end example

@example
$ ./helm.py --help                         # top level help (launch and move)
$ ./helm.py launch --help                  # help for launch options
$ ./helm.py launch --missiles              # set missiles=True and torpedos=False
$ ./helm.py steer --course 180 --speed 5   # set movement parameters
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 389

@item PEP 389@footnote{https://peps.python.org/pep-0389/} - New Command Line Parsing Module

PEP written by Steven Bethard.
@end table

@ref{118b,,Migrating optparse code to argparse} for details on the differences from @ref{9f,,optparse}.


@node PEP 391 Dictionary Based Configuration for Logging,PEP 3148 The concurrent futures module,PEP 389 Argparse Command Line Parsing Module,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-391-dictionary-based-configuration-for-logging}@anchor{118c}
@subsection PEP 391:  Dictionary Based Configuration for Logging


The @ref{86,,logging} module provided two kinds of configuration, one style with
function calls for each option or another style driven by an external file saved
in a @ref{22,,configparser} format.  Those options did not provide the flexibility
to create configurations from JSON or YAML files, nor did they support
incremental configuration, which is needed for specifying logger options from a
command line.

To support a more flexible style, the module now offers
@ref{118d,,logging.config.dictConfig()} for specifying logging configuration with
plain Python dictionaries.  The configuration options include formatters,
handlers, filters, and loggers.  Here's a working example of a configuration
dictionary:

@example
@{"version": 1,
 "formatters": @{"brief": @{"format": "%(levelname)-8s: %(name)-15s: %(message)s"@},
                "full": @{"format": "%(asctime)s %(name)-15s %(levelname)-8s %(message)s"@}
                @},
 "handlers": @{"console": @{
                   "class": "logging.StreamHandler",
                   "formatter": "brief",
                   "level": "INFO",
                   "stream": "ext://sys.stdout"@},
              "console_priority": @{
                   "class": "logging.StreamHandler",
                   "formatter": "full",
                   "level": "ERROR",
                   "stream": "ext://sys.stderr"@}
              @},
 "root": @{"level": "DEBUG", "handlers": ["console", "console_priority"]@}@}
@end example

If that dictionary is stored in a file called @code{conf.json}, it can be
loaded and called with code like this:

@example
>>> import json, logging.config
>>> with open('conf.json') as f:
...     conf = json.load(f)
...
>>> logging.config.dictConfig(conf)
>>> logging.info("Transaction completed normally")
INFO    : root           : Transaction completed normally
>>> logging.critical("Abnormal termination")
2011-02-17 11:14:36,694 root            CRITICAL Abnormal termination
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 391

@item PEP 391@footnote{https://peps.python.org/pep-0391/} - Dictionary Based Configuration for Logging

PEP written by Vinay Sajip.
@end table


@node PEP 3148 The concurrent futures module,PEP 3147 PYC Repository Directories,PEP 391 Dictionary Based Configuration for Logging,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-3148-the-concurrent-futures-module}@anchor{118e}
@subsection PEP 3148:  The @code{concurrent.futures} module


Code for creating and managing concurrency is being collected in a new top-level
namespace, `concurrent'.  Its first member is a `futures' package which provides
a uniform high-level interface for managing threads and processes.

The design for @ref{21,,concurrent.futures} was inspired by the
`java.util.concurrent' package.  In that model, a running call and its result
are represented by a @ref{118f,,Future} object that abstracts
features common to threads, processes, and remote procedure calls.  That object
supports status checks (running or done), timeouts, cancellations, adding
callbacks, and access to results or exceptions.

The primary offering of the new module is a pair of executor classes for
launching and managing calls.  The goal of the executors is to make it easier to
use existing tools for making parallel calls. They save the effort needed to
setup a pool of resources, launch the calls, create a results queue, add
time-out handling, and limit the total number of threads, processes, or remote
procedure calls.

Ideally, each application should share a single executor across multiple
components so that process and thread limits can be centrally managed.  This
solves the design challenge that arises when each component has its own
competing strategy for resource management.

Both classes share a common interface with three methods:
@ref{a70,,submit()} for scheduling a callable and
returning a @ref{118f,,Future} object;
@ref{dd1,,map()} for scheduling many asynchronous calls
at a time, and @ref{8da,,shutdown()} for freeing
resources.  The class is a @ref{5be,,context manager} and can be used in a
@ref{5bc,,with} statement to assure that resources are automatically released
when currently pending futures are done executing.

A simple of example of @ref{72c,,ThreadPoolExecutor} is a
launch of four parallel threads for copying files:

@example
import concurrent.futures, shutil
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as e:
    e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
    e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest4.txt')
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3148

@item PEP 3148@footnote{https://peps.python.org/pep-3148/} - Futures -- Execute Computations Asynchronously

PEP written by Brian Quinlan.
@end table

@ref{1190,,Code for Threaded Parallel URL reads}, an
example using threads to fetch multiple web pages in parallel.

@ref{1191,,Code for computing prime numbers in parallel}, an example demonstrating
@ref{8db,,ProcessPoolExecutor}.


@node PEP 3147 PYC Repository Directories,PEP 3149 ABI Version Tagged so Files,PEP 3148 The concurrent futures module,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-3147-pyc-repository-directories}@anchor{1192}
@subsection PEP 3147:  PYC Repository Directories


Python's scheme for caching bytecode in `.pyc' files did not work well in
environments with multiple Python interpreters.  If one interpreter encountered
a cached file created by another interpreter, it would recompile the source and
overwrite the cached file, thus losing the benefits of caching.

The issue of "pyc fights" has become more pronounced as it has become
commonplace for Linux distributions to ship with multiple versions of Python.
These conflicts also arise with CPython alternatives such as Unladen Swallow.

To solve this problem, Python's import machinery has been extended to use
distinct filenames for each interpreter.  Instead of Python 3.2 and Python 3.3 and
Unladen Swallow each competing for a file called "mymodule.pyc", they will now
look for "mymodule.cpython-32.pyc", "mymodule.cpython-33.pyc", and
"mymodule.unladen10.pyc".  And to prevent all of these new files from
cluttering source directories, the `pyc' files are now collected in a
"__pycache__" directory stored under the package directory.

Aside from the filenames and target directories, the new scheme has a few
aspects that are visible to the programmer:


@itemize *

@item 
Imported modules now have a @ref{2d4,,__cached__} attribute which stores
the name of the actual file that was imported:

@example
>>> import collections
>>> collections.__cached__ 
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'
@end example

@item 
The tag that is unique to each interpreter is accessible from the @code{imp}
module:

@example
>>> import imp 
>>> imp.get_tag() 
'cpython-32'
@end example

@item 
Scripts that try to deduce source filename from the imported file now need to
be smarter.  It is no longer sufficient to simply strip the "c" from a ".pyc"
filename.  Instead, use the new functions in the @code{imp} module:

@example
>>> imp.source_from_cache('c:/py32/lib/__pycache__/collections.cpython-32.pyc') 
'c:/py32/lib/collections.py'
>>> imp.cache_from_source('c:/py32/lib/collections.py') 
'c:/py32/lib/__pycache__/collections.cpython-32.pyc'
@end example

@item 
The @ref{b2,,py_compile} and @ref{20,,compileall} modules have been updated to
reflect the new naming convention and target directory.  The command-line
invocation of `compileall' has new options: @code{-i} for
specifying a list of files and directories to compile and @code{-b} which causes
bytecode files to be written to their legacy location rather than
`__pycache__'.

@item 
The @ref{77,,importlib.abc} module has been updated with new @ref{1193,,abstract base classes} for loading bytecode files.  The obsolete
ABCs, @code{PyLoader} and
@code{PyPycLoader}, have been deprecated (instructions on how
to stay Python 3.1 compatible are included with the documentation).
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3147

@item PEP 3147@footnote{https://peps.python.org/pep-3147/} - PYC Repository Directories

PEP written by Barry Warsaw.
@end table


@node PEP 3149 ABI Version Tagged so Files,PEP 3333 Python Web Server Gateway Interface v1 0 1,PEP 3147 PYC Repository Directories,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-3149-abi-version-tagged-so-files}@anchor{1194}
@subsection PEP 3149: ABI Version Tagged .so Files


The PYC repository directory allows multiple bytecode cache files to be
co-located.  This PEP implements a similar mechanism for shared object files by
giving them a common directory and distinct names for each version.

The common directory is "pyshared" and the file names are made distinct by
identifying the Python implementation (such as CPython, PyPy, Jython, etc.), the
major and minor version numbers, and optional build flags (such as "d" for
debug, "m" for pymalloc, "u" for wide-unicode).  For an arbitrary package "foo",
you may see these files when the distribution package is installed:

@example
/usr/share/pyshared/foo.cpython-32m.so
/usr/share/pyshared/foo.cpython-33md.so
@end example

In Python itself, the tags are accessible from functions in the @ref{da,,sysconfig}
module:

@example
>>> import sysconfig
>>> sysconfig.get_config_var('SOABI')       # find the version tag
'cpython-32mu'
>>> sysconfig.get_config_var('EXT_SUFFIX')  # find the full filename extension
'.cpython-32mu.so'
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3149

@item PEP 3149@footnote{https://peps.python.org/pep-3149/} - ABI Version Tagged .so Files

PEP written by Barry Warsaw.
@end table


@node PEP 3333 Python Web Server Gateway Interface v1 0 1,Autres changements au langage<12>,PEP 3149 ABI Version Tagged so Files,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 pep-3333-python-web-server-gateway-interface-v1-0-1}@anchor{1195}
@subsection PEP 3333: Python Web Server Gateway Interface v1.0.1


This informational PEP clarifies how bytes/text issues are to be handled by the
WSGI protocol.  The challenge is that string handling in Python 3 is most
conveniently handled with the @ref{435,,str} type even though the HTTP protocol
is itself bytes oriented.

The PEP differentiates so-called `native strings' that are used for
request/response headers and metadata versus `byte strings' which are used for
the bodies of requests and responses.

The `native strings' are always of type @ref{435,,str} but are restricted to code
points between `U+0000' through `U+00FF' which are translatable to bytes using
`Latin-1' encoding.  These strings are used for the keys and values in the
environment dictionary and for response headers and statuses in the
@code{start_response()} function.  They must follow 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html} with respect to
encoding. That is, they must either be `ISO-8859-1' characters or use
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} MIME encoding.

For developers porting WSGI applications from Python 2, here are the salient
points:


@itemize *

@item 
If the app already used strings for headers in Python 2, no change is needed.

@item 
If instead, the app encoded output headers or decoded input headers, then the
headers will need to be re-encoded to Latin-1.  For example, an output header
encoded in utf-8 was using @code{h.encode('utf-8')} now needs to convert from
bytes to native strings using @code{h.encode('utf-8').decode('latin-1')}.

@item 
Values yielded by an application or sent using the @code{write()} method
must be byte strings.  The @code{start_response()} function and environ
must use native strings.  The two cannot be mixed.
@end itemize

For server implementers writing CGI-to-WSGI pathways or other CGI-style
protocols, the users must to be able access the environment using native strings
even though the underlying platform may have a different convention.  To bridge
this gap, the @ref{117,,wsgiref} module has a new function,
@ref{1196,,wsgiref.handlers.read_environ()} for transcoding CGI variables from
@ref{1197,,os.environ} into native strings and returning a new dictionary.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3333

@item PEP 3333@footnote{https://peps.python.org/pep-3333/} - Python Web Server Gateway Interface v1.0.1

PEP written by Phillip Eby.
@end table


@node Autres changements au langage<12>,New Improved and Deprecated Modules,PEP 3333 Python Web Server Gateway Interface v1 0 1,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 other-language-changes}@anchor{1198}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
String formatting for @ref{60a,,format()} and @ref{60c,,str.format()} gained new
capabilities for the format character `#'.  Previously, for integers in
binary, octal, or hexadecimal, it caused the output to be prefixed with '0b',
'0o', or '0x' respectively.  Now it can also handle floats, complex, and
Decimal, causing the output to always have a decimal point even when no digits
follow it.

@example
>>> format(20, '#o')
'0o24'
>>> format(12.34, '#5.0f')
'  12.'
@end example

(Suggested by Mark Dickinson and implemented by Eric Smith in bpo-7094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7094}.)

@item 
There is also a new @ref{dc4,,str.format_map()} method that extends the
capabilities of the existing @ref{60c,,str.format()} method by accepting arbitrary
@ref{1199,,mapping} objects.  This new method makes it possible to use string
formatting with any of Python's many dictionary-like objects such as
@ref{119a,,defaultdict}, @ref{f85,,Shelf},
@ref{1c3,,ConfigParser}, or @ref{31,,dbm}.  It is also useful with
custom @ref{253,,dict} subclasses that normalize keys before look-up or that
supply a @code{__missing__()} method for unknown keys:

@example
>>> import shelve
>>> d = shelve.open('tmp.shl')
>>> 'The @{project_name@} status is @{status@} as of @{date@}'.format_map(d)
'The testing project status is green as of February 15, 2011'

>>> class LowerCasedDict(dict):
...     def __getitem__(self, key):
...         return dict.__getitem__(self, key.lower())
...
>>> lcd = LowerCasedDict(part='widgets', quantity=10)
>>> 'There are @{QUANTITY@} @{Part@} in stock'.format_map(lcd)
'There are 10 widgets in stock'

>>> class PlaceholderDict(dict):
...     def __missing__(self, key):
...         return '<@{@}>'.format(key)
...
>>> 'Hello @{name@}, welcome to @{location@}'.format_map(PlaceholderDict())
'Hello <name>, welcome to <location>'
@end example
@end itemize

@quotation

(Suggested by Raymond Hettinger and implemented by Eric Smith in
bpo-6081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6081}.)
@end quotation


@itemize *

@item 
The interpreter can now be started with a quiet option, @code{-q}, to prevent
the copyright and version information from being displayed in the interactive
mode.  The option can be introspected using the @ref{677,,sys.flags} attribute:

@example
$ python -q
>>> sys.flags
sys.flags(debug=0, division_warning=0, inspect=0, interactive=0,
optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0,
ignore_environment=0, verbose=0, bytes_warning=0, quiet=1)
@end example

(Contribution par Marcin Wojdyr; bpo-1772833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1772833}).

@item 
The @ref{4bb,,hasattr()} function works by calling @ref{bbf,,getattr()} and detecting
whether an exception is raised.  This technique allows it to detect methods
created dynamically by @ref{4bc,,__getattr__()} or @ref{bc0,,__getattribute__()} which
would otherwise be absent from the class dictionary.  Formerly, `hasattr'
would catch any exception, possibly masking genuine errors.  Now, `hasattr'
has been tightened to only catch @ref{343,,AttributeError} and let other
exceptions pass through:

@example
>>> class A:
...     @@property
...     def f(self):
...         return 1 // 0
...
>>> a = A()
>>> hasattr(a, 'f')
Traceback (most recent call last):
  ...
ZeroDivisionError: integer division or modulo by zero
@end example

(Discovered by Yury Selivanov and fixed by Benjamin Peterson; bpo-9666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9666}.)

@item 
The @ref{435,,str()} of a float or complex number is now the same as its
@ref{7e7,,repr()}. Previously, the @ref{435,,str()} form was shorter but that just
caused confusion and is no longer needed now that the shortest possible
@ref{7e7,,repr()} is displayed by default:

@example
>>> import math
>>> repr(math.pi)
'3.141592653589793'
>>> str(math.pi)
'3.141592653589793'
@end example

(Proposed and implemented by Mark Dickinson; bpo-9337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9337}.)

@item 
@ref{452,,memoryview} objects now have a @ref{119b,,release()} method
and they also now support the context management protocol.  This allows timely
release of any resources that were acquired when requesting a buffer from the
original object.

@example
>>> with memoryview(b'abcdefgh') as v:
...     print(v.tolist())
[97, 98, 99, 100, 101, 102, 103, 104]
@end example

(Contribution par Antoine Pitrou; bpo-9757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9757}.)

@item 
Previously it was illegal to delete a name from the local namespace if it
occurs as a free variable in a nested block:

@example
def outer(x):
    def inner():
        return x
    inner()
    del x
@end example

This is now allowed.  Remember that the target of an @ref{189,,except} clause
is cleared, so this code which used to work with Python 2.6, raised a
@ref{18b,,SyntaxError} with Python 3.1 and now works again:

@example
def f():
    def print_error():
        print(e)
    try:
        something
    except Exception as e:
        print_error()
        # implicit "del e" here
@end example

(See bpo-4617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4617}.)

@item 
@ref{119c,,Struct sequence types} are now subclasses of tuple.
This means that C structures like those returned by @ref{48a,,os.stat()},
@ref{119d,,time.gmtime()}, and @ref{68b,,sys.version_info} now work like a
@ref{639,,named tuple} and now work with functions and methods that
expect a tuple as an argument.  This is a big step forward in making the C
structures as flexible as their pure Python counterparts:

@example
>>> import sys
>>> isinstance(sys.version_info, tuple)
True
>>> 'Version %d.%d.%d %s(%d)' % sys.version_info 
'Version 3.2.0 final(0)'
@end example

(Suggested by Arfrever Frehtes Taifersar Arahesis and implemented
by Benjamin Peterson in bpo-8413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8413}.)

@item 
Warnings are now easier to control using the 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS}
environment variable as an alternative to using @code{-W} at the command line:

@example
$ export PYTHONWARNINGS='ignore::RuntimeWarning::,once::UnicodeWarning::'
@end example

(Suggested by Barry Warsaw and implemented by Philip Jenvey in bpo-7301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7301}.)

@item 
A new warning category, @ref{241,,ResourceWarning}, has been added.  It is
emitted when potential issues with resource consumption or cleanup
are detected.  It is silenced by default in normal release builds but
can be enabled through the means provided by the @ref{111,,warnings}
module, or on the command line.

A @ref{241,,ResourceWarning} is issued at interpreter shutdown if the
@ref{119e,,gc.garbage} list isn't empty, and if @ref{119f,,gc.DEBUG_UNCOLLECTABLE} is
set, all uncollectable objects are printed.  This is meant to make the
programmer aware that their code contains object finalization issues.

A @ref{241,,ResourceWarning} is also issued when a @ref{11a0,,file object} is destroyed
without having been explicitly closed.  While the deallocator for such
object ensures it closes the underlying operating system resource
(usually, a file descriptor), the delay in deallocating the object could
produce various issues, especially under Windows.  Here is an example
of enabling the warning from the command line:

@example
$ python -q -Wdefault
>>> f = open("foo", "wb")
>>> del f
__main__:1: ResourceWarning: unclosed file <_io.BufferedWriter name='foo'>
@end example

(Added by Antoine Pitrou and Georg Brandl in bpo-10093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10093} and bpo-477863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=477863}.)

@item 
@ref{930,,range} objects now support `index' and `count' methods. This is part
of an effort to make more objects fully implement the
@ref{11a1,,collections.Sequence} @ref{1193,,abstract base class}.  As a result, the
language will have a more uniform API.  In addition, @ref{930,,range} objects
now support slicing and negative indices, even with values larger than
@ref{11a2,,sys.maxsize}.  This makes `range' more interoperable with lists:

@example
>>> range(0, 100, 2).count(10)
1
>>> range(0, 100, 2).index(10)
5
>>> range(0, 100, 2)[5]
10
>>> range(0, 100, 2)[0:5]
range(0, 10, 2)
@end example

(Contributed by Daniel Stutzbach in bpo-9213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9213}, by Alexander Belopolsky
in bpo-2690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2690}, and by Nick Coghlan in bpo-10889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10889}.)

@item 
The @ref{11a3,,callable()} builtin function from Py2.x was resurrected.  It provides
a concise, readable alternative to using an @ref{1193,,abstract base class} in an
expression like @code{isinstance(x, collections.Callable)}:

@example
>>> callable(max)
True
>>> callable(20)
False
@end example

(See bpo-10518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10518}.)

@item 
Python's import mechanism can now load modules installed in directories with
non-ASCII characters in the path name.  This solved an aggravating problem
with home directories for users with non-ASCII characters in their usernames.
@end itemize

@quotation

(Required extensive work by Victor Stinner in bpo-9425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9425}.)
@end quotation

@node New Improved and Deprecated Modules,Fils d'exécution,Autres changements au langage<12>,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 new-improved-and-deprecated-modules}@anchor{11a4}
@subsection New, Improved, and Deprecated Modules


Python's standard library has undergone significant maintenance efforts and
quality improvements.

The biggest news for Python 3.2 is that the @ref{3b,,email} package, @ref{8a,,mailbox}
module, and @code{nntplib} modules now work correctly with the bytes/text model
in Python 3.  For the first time, there is correct handling of messages with
mixed encodings.

Throughout the standard library, there has been more careful attention to
encodings and text versus bytes issues.  In particular, interactions with the
operating system are now better able to exchange non-ASCII data using the
Windows MBCS encoding, locale-aware encodings, or UTF-8.

Another significant win is the addition of substantially better support for
`SSL' connections and security certificates.

In addition, more classes now implement a @ref{5be,,context manager} to support
convenient and reliable resource clean-up using a @ref{5bc,,with} statement.

@menu
* email: email<6>. 
* elementtree:: 
* functools: functools<7>. 
* itertools: itertools<7>. 
* collections: collections<8>. 
* threading: threading<9>. 
* datetime and time:: 
* math: math<10>. 
* abc: abc<3>. 
* io: io<7>. 
* reprlib:: 
* logging: logging<8>. 
* csv: csv<4>. 
* contextlib: contextlib<8>. 
* decimal and fractions:: 
* ftp:: 
* popen:: 
* select: select<3>. 
* gzip and zipfile:: 
* tarfile: tarfile<9>. 
* hashlib: hashlib<7>. 
* ast: ast<5>. 
* os: os<13>. 
* shutils: shutils<8>. 
* sqlite3: sqlite3<11>. 
* html: html<3>. 
* socket: socket<11>. 
* ssl: ssl<12>. 
* nntp:: 
* certificates:: 
* imaplib: imaplib<4>. 
* http.client: http client<4>. 
* unittest: unittest<11>. 
* random: random<5>. 
* poplib: poplib<4>. 
* asyncore: asyncore<2>. 
* tempfile: tempfile<5>. 
* inspect: inspect<10>. 
* pydoc: pydoc<6>. 
* dis: dis<5>. 
* dbm: dbm<7>. 
* ctypes: ctypes<3>. 
* site: site<4>. 
* sysconfig: sysconfig<3>. 
* pdb: pdb<8>. 
* configparser: configparser<5>. 
* urllib.parse: urllib parse<6>. 
* mailbox:: 
* turtledemo:: 

@end menu

@node email<6>,elementtree,,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 email}@anchor{11a5}
@subsubsection email


The usability of the @ref{3b,,email} package in Python 3 has been mostly fixed by
the extensive efforts of R. David Murray.  The problem was that emails are
typically read and stored in the form of @ref{1bd,,bytes} rather than @ref{435,,str}
text, and they may contain multiple encodings within a single email.  So, the
email package had to be extended to parse and generate email messages in bytes
format.


@itemize *

@item 
New functions @ref{11a6,,message_from_bytes()} and
@ref{11a7,,message_from_binary_file()}, and new classes
@ref{11a8,,BytesFeedParser} and @ref{11a9,,BytesParser}
allow binary message data to be parsed into model objects.

@item 
Given bytes input to the model, @ref{11aa,,get_payload()}
will by default decode a message body that has a
@code{Content-Transfer-Encoding} of `8bit' using the charset
specified in the MIME headers and return the resulting string.

@item 
Given bytes input to the model, @ref{11ab,,Generator} will
convert message bodies that have a @code{Content-Transfer-Encoding} of
`8bit' to instead have a `7bit' @code{Content-Transfer-Encoding}.

Headers with unencoded non-ASCII bytes are deemed to be 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}-encoded
using the `unknown-8bit' character set.

@item 
A new class @ref{11ac,,BytesGenerator} produces bytes as output,
preserving any unchanged non-ASCII data that was present in the input used to
build the model, including message bodies with a
@code{Content-Transfer-Encoding} of `8bit'.

@item 
The @ref{c9,,smtplib} @ref{91a,,SMTP} class now accepts a byte string
for the `msg' argument to the @ref{e42,,sendmail()} method,
and a new method, @ref{e43,,send_message()} accepts a
@ref{279,,Message} object and can optionally obtain the
`from_addr' and `to_addrs' addresses directly from the object.
@end itemize

(Proposed and implemented by R. David Murray, bpo-4661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4661} and bpo-10321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10321}.)

@node elementtree,functools<7>,email<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 elementtree}@anchor{11ad}
@subsubsection elementtree


The @ref{124,,xml.etree.ElementTree} package and its @code{xml.etree.cElementTree}
counterpart have been updated to version 1.3.

Several new and useful functions and methods have been added:


@itemize *

@item 
@ref{11ae,,xml.etree.ElementTree.fromstringlist()} which builds an XML document
from a sequence of fragments

@item 
@ref{11af,,xml.etree.ElementTree.register_namespace()} for registering a global
namespace prefix

@item 
@ref{fdf,,xml.etree.ElementTree.tostringlist()} for string representation
including all sublists

@item 
@ref{11b0,,xml.etree.ElementTree.Element.extend()} for appending a sequence of zero
or more elements

@item 
@ref{11b1,,xml.etree.ElementTree.Element.iterfind()} searches an element and
subelements

@item 
@ref{11b2,,xml.etree.ElementTree.Element.itertext()} creates a text iterator over
an element and its subelements

@item 
@ref{11b3,,xml.etree.ElementTree.TreeBuilder.end()} closes the current element

@item 
@ref{a85,,xml.etree.ElementTree.TreeBuilder.doctype()} handles a doctype
declaration
@end itemize

Deux méthodes ont été dépréciées :


@itemize *

@item 
@code{xml.etree.ElementTree.getchildren()} use @code{list(elem)} instead.

@item 
@code{xml.etree.ElementTree.getiterator()} use @code{Element.iter} instead.
@end itemize

For details of the update, see Introducing ElementTree@footnote{https://web.archive.org/web/20200703234532/http://effbot.org/zone/elementtree-13-intro.htm}
on Fredrik Lundh's website.

(Contribution par Florent Xicluna et Fredrik Lundh; bpo-6472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6472})

@node functools<7>,itertools<7>,elementtree,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 functools}@anchor{11b4}
@subsubsection functools



@itemize *

@item 
The @ref{5e,,functools} module includes a new decorator for caching function
calls.  @ref{9dd,,functools.lru_cache()} can save repeated queries to an external
resource whenever the results are expected to be the same.

For example, adding a caching decorator to a database query function can save
database accesses for popular searches:

@example
>>> import functools
>>> @@functools.lru_cache(maxsize=300)
... def get_phone_number(name):
...     c = conn.cursor()
...     c.execute('SELECT phonenumber FROM phonelist WHERE name=?', (name,))
...     return c.fetchone()[0]
@end example

@example
>>> for name in user_requests:        
...     get_phone_number(name)        # cached lookup
@end example

To help with choosing an effective cache size, the wrapped function is
instrumented for tracking cache statistics:

@example
>>> get_phone_number.cache_info()     
CacheInfo(hits=4805, misses=980, maxsize=300, currsize=300)
@end example

If the phonelist table gets updated, the outdated contents of the cache can be
cleared with:

@example
>>> get_phone_number.cache_clear()
@end example

(Contributed by Raymond Hettinger and incorporating design ideas from Jim
Baker, Miki Tebeka, and Nick Coghlan; see recipe 498245@footnote{https://code.activestate.com/recipes/498245-lru-and-lfu-cache-decorators/}, recipe 577479@footnote{https://code.activestate.com/recipes/577479-simple-caching-decorator/}, bpo-10586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10586}, and
bpo-10593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10593}.)

@item 
The @ref{f48,,functools.wraps()} decorator now adds a @code{__wrapped__} attribute
pointing to the original callable function.  This allows wrapped functions to
be introspected.  It also copies @ref{11b5,,__annotations__} if
defined.  And now it also gracefully skips over missing attributes such as
@ref{11b6,,__doc__} which
might not be defined for the wrapped callable.

In the above example, the cache can be removed by recovering the original
function:

@example
>>> get_phone_number = get_phone_number.__wrapped__    # uncached function
@end example

(By Nick Coghlan and Terrence Cole; bpo-9567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9567}, bpo-3445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3445}, and
bpo-8814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8814}.)

@item 
To help write classes with rich comparison methods, a new decorator
@ref{f2d,,functools.total_ordering()} will use existing equality and inequality
methods to fill in the remaining methods.

For example, supplying `__eq__' and `__lt__' will enable
@ref{f2d,,total_ordering()} to fill-in `__le__', `__gt__' and `__ge__':

@example
@@total_ordering
class Student:
    def __eq__(self, other):
        return ((self.lastname.lower(), self.firstname.lower()) ==
                (other.lastname.lower(), other.firstname.lower()))

    def __lt__(self, other):
        return ((self.lastname.lower(), self.firstname.lower()) <
                (other.lastname.lower(), other.firstname.lower()))
@end example

With the `total_ordering' decorator, the remaining comparison methods
are filled in automatically.

(Contributed by Raymond Hettinger.)

@item 
To aid in porting programs from Python 2, the @ref{11b7,,functools.cmp_to_key()}
function converts an old-style comparison function to
modern @ref{df2,,key function}:

@example
>>> # locale-aware sort order
>>> sorted(iterable, key=cmp_to_key(locale.strcoll)) 
@end example

For sorting examples and a brief sorting tutorial, see the Sorting HowTo@footnote{https://wiki.python.org/moin/HowTo/Sorting/} tutorial.

(Contributed by Raymond Hettinger.)
@end itemize

@node itertools<7>,collections<8>,functools<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 itertools}@anchor{11b8}
@subsubsection itertools



@itemize *

@item 
The @ref{80,,itertools} module has a new @ref{9eb,,accumulate()} function
modeled on APL's `scan' operator and Numpy's `accumulate' function:

@example
>>> from itertools import accumulate
>>> list(accumulate([8, 2, 50]))
[8, 10, 60]
@end example

@example
>>> prob_dist = [0.1, 0.4, 0.2, 0.3]
>>> list(accumulate(prob_dist))      # cumulative probability distribution
[0.1, 0.5, 0.7, 1.0]
@end example

For an example using @ref{9eb,,accumulate()}, see the @ref{11b9,,examples for the random module}.

(Contributed by Raymond Hettinger and incorporating design suggestions
from Mark Dickinson.)
@end itemize

@node collections<8>,threading<9>,itertools<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 collections}@anchor{11ba}
@subsubsection collections



@itemize *

@item 
The @ref{107b,,collections.Counter} class now has two forms of in-place
subtraction, the existing `-=' operator for saturating subtraction@footnote{https://en.wikipedia.org/wiki/Saturation_arithmetic} and the new
@ref{11bb,,subtract()} method for regular subtraction.  The
former is suitable for multisets@footnote{https://en.wikipedia.org/wiki/Multiset}
which only have positive counts, and the latter is more suitable for use cases
that allow negative counts:

@example
>>> from collections import Counter
>>> tally = Counter(dogs=5, cats=3)
>>> tally -= Counter(dogs=2, cats=8)    # saturating subtraction
>>> tally
Counter(@{'dogs': 3@})
@end example

@example
>>> tally = Counter(dogs=5, cats=3)
>>> tally.subtract(dogs=2, cats=8)      # regular subtraction
>>> tally
Counter(@{'dogs': 3, 'cats': -5@})
@end example

(Contributed by Raymond Hettinger.)

@item 
The @ref{5c5,,collections.OrderedDict} class has a new method
@ref{11bc,,move_to_end()} which takes an existing key and
moves it to either the first or last position in the ordered sequence.

The default is to move an item to the last position.  This is equivalent of
renewing an entry with @code{od[k] = od.pop(k)}.

A fast move-to-end operation is useful for resequencing entries.  For example,
an ordered dictionary can be used to track order of access by aging entries
from the oldest to the most recently accessed.

@example
>>> from collections import OrderedDict
>>> d = OrderedDict.fromkeys(['a', 'b', 'X', 'd', 'e'])
>>> list(d)
['a', 'b', 'X', 'd', 'e']
>>> d.move_to_end('X')
>>> list(d)
['a', 'b', 'd', 'e', 'X']
@end example

(Contributed by Raymond Hettinger.)

@item 
The @ref{5c6,,collections.deque} class grew two new methods
@ref{11bd,,count()} and @ref{11be,,reverse()} that
make them more substitutable for @ref{5fc,,list} objects:

@example
>>> from collections import deque
>>> d = deque('simsalabim')
>>> d.count('s')
2
>>> d.reverse()
>>> d
deque(['m', 'i', 'b', 'a', 'l', 'a', 's', 'm', 'i', 's'])
@end example

(Contributed by Raymond Hettinger.)
@end itemize

@node threading<9>,datetime and time,collections<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 threading}@anchor{11bf}
@subsubsection threading


The @ref{ec,,threading} module has a new @ref{11c0,,Barrier}
synchronization class for making multiple threads wait until all of them have
reached a common barrier point.  Barriers are useful for making sure that a task
with multiple preconditions does not run until all of the predecessor tasks are
complete.

Barriers can work with an arbitrary number of threads.  This is a generalization
of a Rendezvous@footnote{https://en.wikipedia.org/wiki/Synchronous_rendezvous} which
is defined for only two threads.

Implemented as a two-phase cyclic barrier, @ref{11c0,,Barrier} objects
are suitable for use in loops.  The separate `filling' and `draining' phases
assure that all threads get released (drained) before any one of them can loop
back and re-enter the barrier.  The barrier fully resets after each cycle.

Example of using barriers:

@example
from threading import Barrier, Thread

def get_votes(site):
    ballots = conduct_election(site)
    all_polls_closed.wait()        # do not count until all polls are closed
    totals = summarize(ballots)
    publish(site, totals)

all_polls_closed = Barrier(len(sites))
for site in sites:
    Thread(target=get_votes, args=(site,)).start()
@end example

In this example, the barrier enforces a rule that votes cannot be counted at any
polling site until all polls are closed.  Notice how a solution with a barrier
is similar to one with @ref{11c1,,threading.Thread.join()}, but the threads stay alive
and continue to do work (summarizing ballots) after the barrier point is
crossed.

If any of the predecessor tasks can hang or be delayed, a barrier can be created
with an optional `timeout' parameter.  Then if the timeout period elapses before
all the predecessor tasks reach the barrier point, all waiting threads are
released and a @ref{11c2,,BrokenBarrierError} exception is raised:

@example
def get_votes(site):
    ballots = conduct_election(site)
    try:
        all_polls_closed.wait(timeout=midnight - time.now())
    except BrokenBarrierError:
        lockbox = seal_ballots(ballots)
        queue.put(lockbox)
    else:
        totals = summarize(ballots)
        publish(site, totals)
@end example

In this example, the barrier enforces a more robust rule.  If some election
sites do not finish before midnight, the barrier times-out and the ballots are
sealed and deposited in a queue for later handling.

See Barrier Synchronization Patterns@footnote{https://osl.cs.illinois.edu/media/papers/karmani-2009-barrier_synchronization_pattern.pdf}
for more examples of how barriers can be used in parallel computing.  Also, there is
a simple but thorough explanation of barriers in The Little Book of Semaphores@footnote{https://greenteapress.com/semaphores/LittleBookOfSemaphores.pdf}, `section 3.6'.

(Contributed by Kristján Valur Jónsson with an API review by Jeffrey Yasskin in
bpo-8777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8777}.)

@node datetime and time,math<10>,threading<9>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 datetime-and-time}@anchor{11c3}
@subsubsection datetime and time



@itemize *

@item 
The @ref{30,,datetime} module has a new type @ref{10a1,,timezone} that
implements the @ref{5c8,,tzinfo} interface by returning a fixed UTC
offset and timezone name. This makes it easier to create timezone-aware
datetime objects:

@example
>>> from datetime import datetime, timezone

>>> datetime.now(timezone.utc)
datetime.datetime(2010, 12, 8, 21, 4, 2, 923754, tzinfo=datetime.timezone.utc)

>>> datetime.strptime("01/01/2000 12:00 +0000", "%m/%d/%Y %H:%M %z")
datetime.datetime(2000, 1, 1, 12, 0, tzinfo=datetime.timezone.utc)
@end example

@item 
Also, @ref{9bd,,timedelta} objects can now be multiplied by
@ref{2eb,,float} and divided by @ref{2eb,,float} and @ref{254,,int} objects.
And @ref{9bd,,timedelta} objects can now divide one another.

@item 
The @ref{c7f,,datetime.date.strftime()} method is no longer restricted to years
after 1900.  The new supported year range is from 1000 to 9999 inclusive.

@item 
Whenever a two-digit year is used in a time tuple, the interpretation has been
governed by @code{time.accept2dyear}.  The default is @code{True} which means that
for a two-digit year, the century is guessed according to the POSIX rules
governing the @code{%y} strptime format.

Starting with Py3.2, use of the century guessing heuristic will emit a
@ref{1a3,,DeprecationWarning}.  Instead, it is recommended that
@code{time.accept2dyear} be set to @code{False} so that large date ranges
can be used without guesswork:

@example
>>> import time, warnings
>>> warnings.resetwarnings()      # remove the default warning filters

>>> time.accept2dyear = True      # guess whether 11 means 11 or 2011
>>> time.asctime((11, 1, 1, 12, 34, 56, 4, 1, 0))
Warning (from warnings module):
  ...
DeprecationWarning: Century info guessed for a 2-digit year.
'Fri Jan  1 12:34:56 2011'

>>> time.accept2dyear = False     # use the full range of allowable dates
>>> time.asctime((11, 1, 1, 12, 34, 56, 4, 1, 0))
'Fri Jan  1 12:34:56 11'
@end example

Several functions now have significantly expanded date ranges.  When
@code{time.accept2dyear} is false, the @ref{11c4,,time.asctime()} function will
accept any year that fits in a C int, while the @ref{11c5,,time.mktime()} and
@ref{11c6,,time.strftime()} functions will accept the full range supported by the
corresponding operating system functions.
@end itemize

(Contributed by Alexander Belopolsky and Victor Stinner in bpo-1289118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1289118},
bpo-5094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5094}, bpo-6641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6641}, bpo-2706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2706}, bpo-1777412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1777412}, bpo-8013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8013},
and bpo-10827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10827}.)

@c XXX https://bugs.python.org/issue?%40search_text=datetime&%40sort=-activity

@node math<10>,abc<3>,datetime and time,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 math}@anchor{11c7}
@subsubsection `math'


The @ref{8d,,math} module has been updated with six new functions inspired by the
C99 standard.

The @ref{11c8,,isfinite()} function provides a reliable and fast way to detect
special values.  It returns @code{True} for regular numbers and @code{False} for `Nan' or
`Infinity':

@example
>>> from math import isfinite
>>> [isfinite(x) for x in (123, 4.56, float('Nan'), float('Inf'))]
[True, True, False, False]
@end example

The @ref{11c9,,expm1()} function computes @code{e**x-1} for small values of `x'
without incurring the loss of precision that usually accompanies the subtraction
of nearly equal quantities:

@example
>>> from math import expm1
>>> expm1(0.013671875)   # more accurate way to compute e**x-1 for a small x
0.013765762467652909
@end example

The @ref{bc6,,erf()} function computes a probability integral or Gaussian error function@footnote{https://en.wikipedia.org/wiki/Error_function}.  The
complementary error function, @ref{bc7,,erfc()}, is @code{1 - erf(x)}:

@example
>>> from math import erf, erfc, sqrt
>>> erf(1.0/sqrt(2.0))   # portion of normal distribution within 1 standard deviation
0.682689492137086
>>> erfc(1.0/sqrt(2.0))  # portion of normal distribution outside 1 standard deviation
0.31731050786291404
>>> erf(1.0/sqrt(2.0)) + erfc(1.0/sqrt(2.0))
1.0
@end example

The @ref{11ca,,gamma()} function is a continuous extension of the factorial
function.  See @indicateurl{https://en.wikipedia.org/wiki/Gamma_function} for details.  Because
the function is related to factorials, it grows large even for small values of
`x', so there is also a @ref{11cb,,lgamma()} function for computing the natural
logarithm of the gamma function:

@example
>>> from math import gamma, lgamma
>>> gamma(7.0)           # six factorial
720.0
>>> lgamma(801.0)        # log(800 factorial)
4551.950730698041
@end example

(Contributed by Mark Dickinson.)

@node abc<3>,io<7>,math<10>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 abc}@anchor{11cc}
@subsubsection abc


The @ref{4,,abc} module now supports @ref{1070,,abstractclassmethod()} and
@ref{1071,,abstractstaticmethod()}.

These tools make it possible to define an @ref{1193,,abstract base class} that
requires a particular @ref{165,,classmethod()} or @ref{40c,,staticmethod()} to be
implemented:

@example
class Temperature(metaclass=abc.ABCMeta):
    @@abc.abstractclassmethod
    def from_fahrenheit(cls, t):
        ...
    @@abc.abstractclassmethod
    def from_celsius(cls, t):
        ...
@end example

(Patch submitted by Daniel Urban; bpo-5867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5867}.)

@node io<7>,reprlib,abc<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 io}@anchor{11cd}
@subsubsection io


The @ref{e8d,,io.BytesIO} has a new method, @ref{11ce,,getbuffer()}, which
provides functionality similar to @ref{452,,memoryview()}.  It creates an editable
view of the data without making a copy.  The buffer's random access and support
for slice notation are well-suited to in-place editing:

@example
>>> REC_LEN, LOC_START, LOC_LEN = 34, 7, 11

>>> def change_location(buffer, record_number, location):
...     start = record_number * REC_LEN + LOC_START
...     buffer[start: start+LOC_LEN] = location

>>> import io

>>> byte_stream = io.BytesIO(
...     b'G3805  storeroom  Main chassis    '
...     b'X7899  shipping   Reserve cog     '
...     b'L6988  receiving  Primary sprocket'
... )
>>> buffer = byte_stream.getbuffer()
>>> change_location(buffer, 1, b'warehouse  ')
>>> change_location(buffer, 0, b'showroom   ')
>>> print(byte_stream.getvalue())
b'G3805  showroom   Main chassis    '
b'X7899  warehouse  Reserve cog     '
b'L6988  receiving  Primary sprocket'
@end example

(Contribution par Antoine Pitrou; bpo-5506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5506}.)

@node reprlib,logging<8>,io<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 reprlib}@anchor{11cf}
@subsubsection reprlib


When writing a @ref{607,,__repr__()} method for a custom container, it is easy to
forget to handle the case where a member refers back to the container itself.
Python's builtin objects such as @ref{5fc,,list} and @ref{5c3,,set} handle
self-reference by displaying "..." in the recursive part of the representation
string.

To help write such @ref{607,,__repr__()} methods, the @ref{ba,,reprlib} module has a new
decorator, @ref{11d0,,recursive_repr()}, for detecting recursive calls to
@code{__repr__()} and substituting a placeholder string instead:

@example
>>> class MyList(list):
...     @@recursive_repr()
...     def __repr__(self):
...         return '<' + '|'.join(map(repr, self)) + '>'
...
>>> m = MyList('abc')
>>> m.append(m)
>>> m.append('x')
>>> print(m)
<'a'|'b'|'c'|...|'x'>
@end example

(Contribution par Raymond Hettinger; bpo-9826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9826} et bpo-9840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9840})

@node logging<8>,csv<4>,reprlib,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 logging}@anchor{11d1}
@subsubsection logging


In addition to dictionary-based configuration described above, the
@ref{86,,logging} package has many other improvements.

The logging documentation has been augmented by a @ref{11d2,,basic tutorial}, an @ref{11d3,,advanced tutorial}, and a @ref{11d4,,cookbook} of
logging recipes.  These documents are the fastest way to learn about logging.

The @ref{9ee,,logging.basicConfig()} set-up function gained a `style' argument to
support three different types of string formatting.  It defaults to "%" for
traditional %-formatting, can be set to "@{" for the new @ref{60c,,str.format()} style, or
can be set to "$" for the shell-style formatting provided by
@ref{672,,string.Template}.  The following three configurations are equivalent:

@example
>>> from logging import basicConfig
>>> basicConfig(style='%', format="%(name)s -> %(levelname)s: %(message)s")
>>> basicConfig(style='@{', format="@{name@} -> @{levelname@} @{message@}")
>>> basicConfig(style='$', format="$name -> $levelname: $message")
@end example

If no configuration is set-up before a logging event occurs, there is now a
default configuration using a @ref{11d5,,StreamHandler} directed to
@ref{926,,sys.stderr} for events of @code{WARNING} level or higher.  Formerly, an
event occurring before a configuration was set-up would either raise an
exception or silently drop the event depending on the value of
@ref{11d6,,logging.raiseExceptions}.  The new default handler is stored in
@ref{11d7,,logging.lastResort}.

The use of filters has been simplified.  Instead of creating a
@ref{11d8,,Filter} object, the predicate can be any Python callable that
returns @code{True} or @code{False}.

There were a number of other improvements that add flexibility and simplify
configuration.  See the module documentation for a full listing of changes in
Python 3.2.

@node csv<4>,contextlib<8>,logging<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 csv}@anchor{11d9}
@subsubsection csv


The @ref{29,,csv} module now supports a new dialect, @ref{11da,,unix_dialect},
which applies quoting for all fields and a traditional Unix style with @code{'\n'} as
the line terminator.  The registered dialect name is @code{unix}.

The @ref{11db,,csv.DictWriter} has a new method,
@ref{11dc,,writeheader()} for writing-out an initial row to document
the field names:

@example
>>> import csv, sys
>>> w = csv.DictWriter(sys.stdout, ['name', 'dept'], dialect='unix')
>>> w.writeheader()
"name","dept"
>>> w.writerows([
...     @{'name': 'tom', 'dept': 'accounting'@},
...     @{'name': 'susan', 'dept': 'Salesl'@}])
"tom","accounting"
"susan","sales"
@end example

(New dialect suggested by Jay Talbot in bpo-5975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5975}, and the new method
suggested by Ed Abraham in bpo-1537721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1537721}.)

@node contextlib<8>,decimal and fractions,csv<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 contextlib}@anchor{11dd}
@subsubsection contextlib


There is a new and slightly mind-blowing tool
@ref{11de,,ContextDecorator} that is helpful for creating a
@ref{5be,,context manager} that does double duty as a function decorator.

As a convenience, this new functionality is used by
@ref{11df,,contextmanager()} so that no extra effort is needed to support
both roles.

The basic idea is that both context managers and function decorators can be used
for pre-action and post-action wrappers.  Context managers wrap a group of
statements using a @ref{5bc,,with} statement, and function decorators wrap a
group of statements enclosed in a function.  So, occasionally there is a need to
write a pre-action or post-action wrapper that can be used in either role.

For example, it is sometimes useful to wrap functions or groups of statements
with a logger that can track the time of entry and time of exit.  Rather than
writing both a function decorator and a context manager for the task, the
@ref{11df,,contextmanager()} provides both capabilities in a single
definition:

@example
from contextlib import contextmanager
import logging

logging.basicConfig(level=logging.INFO)

@@contextmanager
def track_entry_and_exit(name):
    logging.info('Entering: %s', name)
    yield
    logging.info('Exiting: %s', name)
@end example

Formerly, this would have only been usable as a context manager:

@example
with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()
@end example

Now, it can be used as a decorator as well:

@example
@@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()
@end example

Trying to fulfill two roles at once places some limitations on the technique.
Context managers normally have the flexibility to return an argument usable by
a @ref{5bc,,with} statement, but there is no parallel for function decorators.

In the above example, there is not a clean way for the `track_entry_and_exit'
context manager to return a logging instance for use in the body of enclosed
statements.

(Contribution par Michael Foord; bpo-9110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9110})

@node decimal and fractions,ftp,contextlib<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 decimal-and-fractions}@anchor{11e0}
@subsubsection decimal and fractions


Mark Dickinson crafted an elegant and efficient scheme for assuring that
different numeric datatypes will have the same hash value whenever their actual
values are equal (bpo-8188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8188}):

@example
assert hash(Fraction(3, 2)) == hash(1.5) == \
       hash(Decimal("1.5")) == hash(complex(1.5, 0))
@end example

Some of the hashing details are exposed through a new attribute,
@ref{fe8,,sys.hash_info}, which describes the bit width of the hash value, the
prime modulus, the hash values for `infinity' and `nan', and the multiplier
used for the imaginary part of a number:

@example
>>> sys.hash_info 
sys.hash_info(width=64, modulus=2305843009213693951, inf=314159, nan=0, imag=1000003)
@end example

An early decision to limit the interoperability of various numeric types has
been relaxed.  It is still unsupported (and ill-advised) to have implicit
mixing in arithmetic expressions such as @code{Decimal('1.1') + float('1.1')}
because the latter loses information in the process of constructing the binary
float.  However, since existing floating-point value can be converted losslessly
to either a decimal or rational representation, it makes sense to add them to
the constructor and to support mixed-type comparisons.


@itemize *

@item 
The @ref{29a,,decimal.Decimal} constructor now accepts @ref{2eb,,float} objects
directly so there in no longer a need to use the @ref{11e1,,from_float()}
method (bpo-8257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8257}).

@item 
Mixed type comparisons are now fully supported so that
@ref{29a,,Decimal} objects can be directly compared with @ref{2eb,,float}
and @ref{1e4,,fractions.Fraction} (bpo-2531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2531} and bpo-8188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8188}).
@end itemize

Similar changes were made to @ref{1e4,,fractions.Fraction} so that the
@ref{11e2,,from_float()} and @ref{11e3,,from_decimal()}
methods are no longer needed (bpo-8294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8294}):

@example
>>> from decimal import Decimal
>>> from fractions import Fraction
>>> Decimal(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)
@end example

Another useful change for the @ref{36,,decimal} module is that the
@code{Context.clamp} attribute is now public.  This is useful in creating
contexts that correspond to the decimal interchange formats specified in IEEE
754 (see bpo-8540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8540}).

(Contributed by Mark Dickinson and Raymond Hettinger.)

@node ftp,popen,decimal and fractions,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ftp}@anchor{11e4}
@subsubsection ftp


The @ref{8e7,,ftplib.FTP} class now supports the context management protocol to
unconditionally consume @ref{103e,,socket.error} exceptions and to close the FTP
connection when done:

@example
>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
        ftp.login()
        ftp.dir()

'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
@end example

Other file-like objects such as @ref{208,,mmap.mmap} and @ref{7e9,,fileinput.input()}
also grew auto-closing context managers:

@example
with fileinput.input(files=('log1.txt', 'log2.txt')) as f:
    for line in f:
        process(line)
@end example

(Contributed by Tarek Ziadé and Giampaolo Rodolà in bpo-4972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4972}, and
by Georg Brandl in bpo-8046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8046} and bpo-1286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1286}.)

The @ref{8e8,,FTP_TLS} class now accepts a `context' parameter, which is a
@ref{291,,ssl.SSLContext} object allowing bundling SSL configuration options,
certificates and private keys into a single (potentially long-lived) structure.

(Contribution par Giampaolo Rodolà; bpo-8806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8806})

@node popen,select<3>,ftp,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 popen}@anchor{11e5}
@subsubsection popen


The @ref{a75,,os.popen()} and @ref{197,,subprocess.Popen()} functions now support
@ref{5bc,,with} statements for auto-closing of the file descriptors.

(Contribution par Antoine Pitrou et Brian Curtin; bpo-7461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7461} et bpo-10554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10554})

@node select<3>,gzip and zipfile,popen,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 select}@anchor{11e6}
@subsubsection select


The @ref{c0,,select} module now exposes a new, constant attribute,
@ref{11e7,,PIPE_BUF}, which gives the minimum number of bytes which are
guaranteed not to block when @ref{d8d,,select.select()} says a pipe is ready
for writing.

@example
>>> import select
>>> select.PIPE_BUF  
512
@end example

(Available on Unix systems. Patch by Sébastien Sablé in bpo-9862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9862})

@node gzip and zipfile,tarfile<9>,select<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 gzip-and-zipfile}@anchor{11e8}
@subsubsection gzip and zipfile


@ref{410,,gzip.GzipFile} now implements the @ref{67f,,io.BufferedIOBase}
@ref{1193,,abstract base class} (except for @code{truncate()}).  It also has a
@ref{11e9,,peek()} method and supports unseekable as well as
zero-padded file objects.

The @ref{66,,gzip} module also gains the @ref{629,,compress()} and
@ref{11ea,,decompress()} functions for easier in-memory compression and
decompression.  Keep in mind that text needs to be encoded as @ref{1bd,,bytes}
before compressing and decompressing:

@example
>>> import gzip
>>> s = 'Three shall be the number thou shalt count, '
>>> s += 'and the number of the counting shall be three'
>>> b = s.encode()                        # convert to utf-8
>>> len(b)
89
>>> c = gzip.compress(b)
>>> len(c)
77
>>> gzip.decompress(c).decode()[:42]      # decompress and convert to text
'Three shall be the number thou shalt count'
@end example

(Contributed by Anand B. Pillai in bpo-3488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3488}; and by Antoine Pitrou, Nir
Aides and Brian Curtin in bpo-9962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9962}, bpo-1675951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1675951}, bpo-7471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7471} and
bpo-2846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2846}.)

Also, the @ref{411,,zipfile.ZipExtFile} class was reworked internally to represent
files stored inside an archive.  The new implementation is significantly faster
and can be wrapped in an @ref{11eb,,io.BufferedReader} object for more speedups.  It
also solves an issue where interleaved calls to `read' and `readline' gave the
wrong results.

(Patch submitted by Nir Aides in bpo-7610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7610}.)

@node tarfile<9>,hashlib<7>,gzip and zipfile,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 tarfile}@anchor{11ec}
@subsubsection tarfile


The @ref{11ed,,TarFile} class can now be used as a context manager.  In
addition, its @ref{be1,,add()} method has a new option, `filter',
that controls which files are added to the archive and allows the file metadata
to be edited.

The new `filter' option replaces the older, less flexible `exclude' parameter
which is now deprecated.  If specified, the optional `filter' parameter needs to
be a @ref{d00,,keyword argument}.  The user-supplied filter function accepts a
@ref{11ee,,TarInfo} object and returns an updated
@ref{11ee,,TarInfo} object, or if it wants the file to be excluded, the
function can return @code{None}:

@example
>>> import tarfile, glob

>>> def myfilter(tarinfo):
...     if tarinfo.isfile():             # only save real files
...         tarinfo.uname = 'monty'      # redact the user name
...         return tarinfo

>>> with tarfile.open(name='myarchive.tar.gz', mode='w:gz') as tf:
...     for filename in glob.glob('*.txt'):
...         tf.add(filename, filter=myfilter)
...     tf.list()
-rw-r--r-- monty/501        902 2011-01-26 17:59:11 annotations.txt
-rw-r--r-- monty/501        123 2011-01-26 17:59:11 general_questions.txt
-rw-r--r-- monty/501       3514 2011-01-26 17:59:11 prion.txt
-rw-r--r-- monty/501        124 2011-01-26 17:59:11 py_todo.txt
-rw-r--r-- monty/501       1399 2011-01-26 17:59:11 semaphore_notes.txt
@end example

(Proposed by Tarek Ziadé and implemented by Lars Gustäbel in bpo-6856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6856}.)

@node hashlib<7>,ast<5>,tarfile<9>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 hashlib}@anchor{11ef}
@subsubsection `hashlib'


The @ref{67,,hashlib} module has two new constant attributes listing the hashing
algorithms guaranteed to be present in all implementations and those available
on the current implementation:

@example
>>> import hashlib

>>> hashlib.algorithms_guaranteed
@{'sha1', 'sha224', 'sha384', 'sha256', 'sha512', 'md5'@}

>>> hashlib.algorithms_available
@{'md2', 'SHA256', 'SHA512', 'dsaWithSHA', 'mdc2', 'SHA224', 'MD4', 'sha256',
'sha512', 'ripemd160', 'SHA1', 'MDC2', 'SHA', 'SHA384', 'MD2',
'ecdsa-with-SHA1','md4', 'md5', 'sha1', 'DSA-SHA', 'sha224',
'dsaEncryption', 'DSA', 'RIPEMD160', 'sha', 'MD5', 'sha384'@}
@end example

(Suggested by Carl Chenet in bpo-7418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7418}.)

@node ast<5>,os<13>,hashlib<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ast}@anchor{11f0}
@subsubsection ast


The @ref{8,,ast} module has a wonderful a general-purpose tool for safely
evaluating expression strings using the Python literal
syntax.  The @ref{c06,,ast.literal_eval()} function serves as a secure alternative to
the builtin @ref{17e,,eval()} function which is easily abused.  Python 3.2 adds
@ref{1bd,,bytes} and @ref{5c3,,set} literals to the list of supported types:
strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and @code{None}.

@example
>>> from ast import literal_eval

>>> request = "@{'req': 3, 'func': 'pow', 'args': (2, 0.5)@}"
>>> literal_eval(request)
@{'args': (2, 0.5), 'req': 3, 'func': 'pow'@}

>>> request = "os.system('do something harmful')"
>>> literal_eval(request)
Traceback (most recent call last):
  ...
ValueError: malformed node or string: <_ast.Call object at 0x101739a10>
@end example

(Implemented by Benjamin Peterson and Georg Brandl.)

@node os<13>,shutils<8>,ast<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 os}@anchor{11f1}
@subsubsection `os'


Different operating systems use various encodings for filenames and environment
variables.  The @ref{a0,,os} module provides two new functions,
@ref{c43,,fsencode()} and @ref{c42,,fsdecode()}, for encoding and decoding
filenames:

@example
>>> import os
>>> filename = 'Sehenswürdigkeiten'
>>> os.fsencode(filename)
b'Sehensw\xc3\xbcrdigkeiten'
@end example

Some operating systems allow direct access to encoded bytes in the
environment.  If so, the @ref{11f2,,os.supports_bytes_environ} constant will be
true.

For direct access to encoded environment variables (if available),
use the new @ref{11f3,,os.getenvb()} function or use @ref{11f4,,os.environb}
which is a bytes version of @ref{1197,,os.environ}.

(Contribution par Victor Stinner)

@node shutils<8>,sqlite3<11>,os<13>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 shutil}@anchor{11f5}
@subsubsection @code{shutils}


The @ref{a17,,shutil.copytree()} function has two new options:


@itemize *

@item 
`ignore_dangling_symlinks': when @code{symlinks=False} so that the function
copies a file pointed to by a symlink, not the symlink itself. This option
will silence the error raised if the file doesn't exist.

@item 
`copy_function': is a callable that will be used to copy files.
@ref{a49,,shutil.copy2()} is used by default.
@end itemize

(Contributed by Tarek Ziadé.)

In addition, the @ref{c4,,shutil} module now supports @ref{11f6,,archiving operations} for zipfiles, uncompressed tarfiles, gzipped tarfiles,
and bzipped tarfiles.  And there are functions for registering additional
archiving file formats (such as xz compressed tarfiles or custom formats).

The principal functions are @ref{49c,,make_archive()} and
@ref{455,,unpack_archive()}.  By default, both operate on the current
directory (which can be set by @ref{5f8,,os.chdir()}) and on any sub-directories.
The archive filename needs to be specified with a full pathname.  The archiving
step is non-destructive (the original files are left unchanged).

@example
>>> import shutil, pprint

>>> os.chdir('mydata')  # change to the source directory
>>> f = shutil.make_archive('/var/backup/mydata',
...                         'zip')      # archive the current directory
>>> f                                   # show the name of archive
'/var/backup/mydata.zip'
>>> os.chdir('tmp')                     # change to an unpacking
>>> shutil.unpack_archive('/var/backup/mydata.zip')  # recover the data

>>> pprint.pprint(shutil.get_archive_formats())  # display known formats
[('bztar', "bzip2'ed tar-file"),
 ('gztar', "gzip'ed tar-file"),
 ('tar', 'uncompressed tar file'),
 ('zip', 'ZIP file')]

>>> shutil.register_archive_format(     # register a new archive format
...     name='xz',
...     function=xz.compress,           # callable archiving function
...     extra_args=[('level', 8)],      # arguments to the function
...     description='xz compression'
... )
@end example

(Contributed by Tarek Ziadé.)

@node sqlite3<11>,html<3>,shutils<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 sqlite3}@anchor{11f7}
@subsubsection @code{sqlite3}


The @ref{ce,,sqlite3} module was updated to pysqlite version 2.6.0.  It has two new capabilities.


@itemize *

@item 
The @code{sqlite3.Connection.in_transit} attribute is true if there is an
active transaction for uncommitted changes.

@item 
The @ref{828,,sqlite3.Connection.enable_load_extension()} and
@ref{4a1,,sqlite3.Connection.load_extension()} methods allows you to load SQLite
extensions from ".so" files.  One well-known extension is the fulltext-search
extension distributed with SQLite.
@end itemize

(Contributed by R. David Murray and Shashwat Anand; bpo-8845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8845}.)

@node html<3>,socket<11>,sqlite3<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 html}@anchor{11f8}
@subsubsection html


A new @ref{6a,,html} module was introduced with only a single function,
@ref{ff7,,escape()}, which is used for escaping reserved characters from HTML
markup:

@example
>>> import html
>>> html.escape('x > 2 && x < 7')
'x &gt; 2 &amp;&amp; x &lt; 7'
@end example

@node socket<11>,ssl<12>,html<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 socket}@anchor{11f9}
@subsubsection `socket'


The @ref{cb,,socket} module has two new improvements.


@itemize *

@item 
Socket objects now have a @ref{11fa,,detach()} method which puts
the socket into closed state without actually closing the underlying file
descriptor.  The latter can then be reused for other purposes.
(Added by Antoine Pitrou; bpo-8524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8524}.)

@item 
@ref{65d,,socket.create_connection()} now supports the context management protocol
to unconditionally consume @ref{103e,,socket.error} exceptions and to close the
socket when done.
(Contributed by Giampaolo Rodolà; bpo-9794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9794}.)
@end itemize

@node ssl<12>,nntp,socket<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ssl}@anchor{11fb}
@subsubsection @code{ssl}


The @ref{cf,,ssl} module added a number of features to satisfy common requirements
for secure (encrypted, authenticated) internet connections:


@itemize *

@item 
A new class, @ref{291,,SSLContext}, serves as a container for persistent
SSL data, such as protocol settings, certificates, private keys, and various
other options. It includes a @ref{50e,,wrap_socket()} for creating
an SSL socket from an SSL context.

@item 
A new function, @code{ssl.match_hostname()}, supports server identity
verification for higher-level protocols by implementing the rules of HTTPS
(from 
@geindex RFC; RFC 2818
RFC 2818@footnote{https://datatracker.ietf.org/doc/html/rfc2818.html}) which are also suitable for other protocols.

@item 
The @ref{50e,,ssl.wrap_socket()} constructor function now takes a `ciphers'
argument.  The `ciphers' string lists the allowed encryption algorithms using
the format described in the OpenSSL documentation@footnote{https://docs.openssl.org/1.0.2/man1/ciphers/#cipher-list-format}.

@item 
When linked against recent versions of OpenSSL, the @ref{cf,,ssl} module now
supports the Server Name Indication extension to the TLS protocol, allowing
multiple "virtual hosts" using different certificates on a single IP port.
This extension is only supported in client mode, and is activated by passing
the `server_hostname' argument to @ref{50e,,ssl.SSLContext.wrap_socket()}.

@item 
Various options have been added to the @ref{cf,,ssl} module, such as
@ref{823,,OP_NO_SSLv2} which disables the insecure and obsolete SSLv2
protocol.

@item 
The extension now loads all the OpenSSL ciphers and digest algorithms.  If
some SSL certificates cannot be verified, they are reported as an "unknown
algorithm" error.

@item 
The version of OpenSSL being used is now accessible using the module
attributes @ref{11fc,,ssl.OPENSSL_VERSION} (a string),
@ref{11fd,,ssl.OPENSSL_VERSION_INFO} (a 5-tuple), and
@ref{11fe,,ssl.OPENSSL_VERSION_NUMBER} (an integer).
@end itemize

(Contributed by Antoine Pitrou in bpo-8850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8850}, bpo-1589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1589}, bpo-8322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8322},
bpo-5639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5639}, bpo-4870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4870}, bpo-8484@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8484}, and bpo-8321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8321}.)

@node nntp,certificates,ssl<12>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 nntp}@anchor{11ff}
@subsubsection nntp


The @code{nntplib} module has a revamped implementation with better bytes and
text semantics as well as more practical APIs.  These improvements break
compatibility with the nntplib version in Python 3.1, which was partly
dysfunctional in itself.

Support for secure connections through both implicit (using
@code{nntplib.NNTP_SSL}) and explicit (using @code{nntplib.NNTP.starttls()})
TLS has also been added.

(Contribution par Antoine Pitrou, bpo-9360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9360}, et Andrew Vant, bpo-1926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1926})

@node certificates,imaplib<4>,nntp,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 certificates}@anchor{1200}
@subsubsection certificates


@ref{b2f,,http.client.HTTPSConnection}, @ref{1201,,urllib.request.HTTPSHandler}
and @ref{290,,urllib.request.urlopen()} now take optional arguments to allow for
server certificate checking against a set of Certificate Authorities,
as recommended in public uses of HTTPS.

(Ajouté par Antoine Pitrou; bpo-9003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9003}.)

@node imaplib<4>,http client<4>,certificates,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 imaplib}@anchor{1202}
@subsubsection `imaplib'


Support for explicit TLS on standard IMAP4 connections has been added through
the new @ref{1203,,imaplib.IMAP4.starttls} method.

(Contribution par Lorenzo M. Catucci et Antoine Pitrou; bpo-4471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4471}.)

@node http client<4>,unittest<11>,imaplib<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 http-client}@anchor{1204}
@subsubsection http.client


There were a number of small API improvements in the @ref{6e,,http.client} module.
The old-style HTTP 0.9 simple responses are no longer supported and the `strict'
parameter is deprecated in all classes.

The @ref{b2e,,HTTPConnection} and
@ref{b2f,,HTTPSConnection} classes now have a `source_address'
parameter for a (host, port) tuple indicating where the HTTP connection is made
from.

Support for certificate checking and HTTPS virtual hosts were added to
@ref{b2f,,HTTPSConnection}.

The @ref{c97,,request()} method on connection objects
allowed an optional `body' argument so that a @ref{11a0,,file object} could be used
to supply the content of the request.  Conveniently, the `body' argument now
also accepts an @ref{1205,,iterable} object so long as it includes an explicit
@code{Content-Length} header.  This extended interface is much more flexible than
before.

To establish an HTTPS connection through a proxy server, there is a new
@ref{1206,,set_tunnel()} method that sets the host and
port for HTTP Connect tunneling.

To match the behavior of @ref{71,,http.server}, the HTTP client library now also
encodes headers with ISO-8859-1 (Latin-1) encoding.  It was already doing that
for incoming headers, so now the behavior is consistent for both incoming and
outgoing traffic. (See work by Armin Ronacher in bpo-10980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10980}.)

@node unittest<11>,random<5>,http client<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 unittest}@anchor{1207}
@subsubsection unittest


The unittest module has a number of improvements supporting test discovery for
packages, easier experimentation at the interactive prompt, new testcase
methods, improved diagnostic messages for test failures, and better method
names.


@itemize *

@item 
The command-line call @code{python -m unittest} can now accept file paths
instead of module names for running specific tests (bpo-10620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10620}).  The new
test discovery can find tests within packages, locating any test importable
from the top-level directory.  The top-level directory can be specified with
the @code{-t} option, a pattern for matching files with @code{-p}, and a directory to
start discovery with @code{-s}:

@example
$ python -m unittest discover -s my_proj_dir -p _test.py
@end example

(Contributed by Michael Foord.)

@item 
Experimentation at the interactive prompt is now easier because the
@ref{437,,unittest.TestCase} class can now be instantiated without
arguments:

@example
>>> from unittest import TestCase
>>> TestCase().assertEqual(pow(2, 3), 8)
@end example

(Contributed by Michael Foord.)

@item 
The @ref{105,,unittest} module has two new methods,
@ref{1144,,assertWarns()} and
@ref{1145,,assertWarnsRegex()} to verify that a given warning type
is triggered by the code under test:

@example
with self.assertWarns(DeprecationWarning):
    legacy_function('XYZ')
@end example

(Contribution par Antoine Pitrou; bpo-9754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9754}.)

Another new method, @ref{1208,,assertCountEqual()} is used to
compare two iterables to determine if their element counts are equal (whether
the same elements are present with the same number of occurrences regardless
of order):

@example
def test_anagram(self):
    self.assertCountEqual('algorithm', 'logarithm')
@end example

(Contributed by Raymond Hettinger.)

@item 
A principal feature of the unittest module is an effort to produce meaningful
diagnostics when a test fails.  When possible, the failure is recorded along
with a diff of the output.  This is especially helpful for analyzing log files
of failed test runs. However, since diffs can sometime be voluminous, there is
a new @ref{1209,,maxDiff} attribute that sets maximum length of
diffs displayed.

@item 
In addition, the method names in the module have undergone a number of clean-ups.

For example, @ref{517,,assertRegex()} is the new name for
@code{assertRegexpMatches()} which was misnamed because the
test uses @ref{120a,,re.search()}, not @ref{120b,,re.match()}.  Other methods using
regular expressions are now named using short form "Regex" in preference to
"Regexp" -- this matches the names used in other unittest implementations,
matches Python's old name for the @ref{b8,,re} module, and it has unambiguous
camel-casing.

(Contributed by Raymond Hettinger and implemented by Ezio Melotti.)

@item 
To improve consistency, some long-standing method aliases are being
deprecated in favor of the preferred names:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Old Name

@tab

Preferred Name

@item

@code{assert_()}

@tab

@ref{510,,assertTrue()}

@item

@code{assertEquals()}

@tab

@ref{512,,assertEqual()}

@item

@code{assertNotEquals()}

@tab

@ref{513,,assertNotEqual()}

@item

@code{assertAlmostEquals()}

@tab

@ref{514,,assertAlmostEqual()}

@item

@code{assertNotAlmostEquals()}

@tab

@ref{515,,assertNotAlmostEqual()}

@end multitable

@end quotation

Likewise, the @code{TestCase.fail*} methods deprecated in Python 3.1 are expected
to be removed in Python 3.3.

(Contribution par Ezio Melotti; bpo-9424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9424})

@item 
The @code{assertDictContainsSubset()} method was deprecated
because it was misimplemented with the arguments in the wrong order.  This
created hard-to-debug optical illusions where tests like
@code{TestCase().assertDictContainsSubset(@{'a':1, 'b':2@}, @{'a':1@})} would fail.

(Contributed by Raymond Hettinger.)
@end itemize

@node random<5>,poplib<4>,unittest<11>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 random}@anchor{120c}
@subsubsection `random'


The integer methods in the @ref{b7,,random} module now do a better job of producing
uniform distributions.  Previously, they computed selections with
@code{int(n*random())} which had a slight bias whenever `n' was not a power of two.
Now, multiple selections are made from a range up to the next power of two and a
selection is kept only when it falls within the range @code{0 <= x < n}.  The
functions and methods affected are @ref{856,,randrange()},
@ref{120d,,randint()}, @ref{120e,,choice()}, @ref{731,,shuffle()} and
@ref{730,,sample()}.

(Contribution par Raymond Hettinger; bpo-9025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9025})

@node poplib<4>,asyncore<2>,random<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 poplib}@anchor{120f}
@subsubsection `poplib'


@ref{912,,POP3_SSL} class now accepts a `context' parameter, which is a
@ref{291,,ssl.SSLContext} object allowing bundling SSL configuration options,
certificates and private keys into a single (potentially long-lived)
structure.

(Contribution par Giampaolo Rodolà; bpo-8807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8807})

@node asyncore<2>,tempfile<5>,poplib<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 asyncore}@anchor{1210}
@subsubsection asyncore


@code{asyncore.dispatcher} now provides a
@code{handle_accepted()} method
returning a @code{(sock, addr)} pair which is called when a connection has actually
been established with a new remote endpoint. This is supposed to be used as a
replacement for old @code{handle_accept()} and avoids
the user  to call @code{accept()} directly.

(Contribution par Giampaolo Rodolà; bpo-6706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6706})

@node tempfile<5>,inspect<10>,asyncore<2>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 tempfile}@anchor{1211}
@subsubsection tempfile


The @ref{df,,tempfile} module has a new context manager,
@ref{1212,,TemporaryDirectory} which provides easy deterministic
cleanup of temporary directories:

@example
with tempfile.TemporaryDirectory() as tmpdirname:
    print('created temporary dir:', tmpdirname)
@end example

(Contribution par Neil Schemenauer et Nick Coghlan; bpo-5178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5178}.)

@node inspect<10>,pydoc<6>,tempfile<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 inspect}@anchor{1213}
@subsubsection `inspect'



@itemize *

@item 
The @ref{7d,,inspect} module has a new function
@ref{1214,,getgeneratorstate()} to easily identify the current state of a
generator-iterator:

@example
>>> from inspect import getgeneratorstate
>>> def gen():
...     yield 'demo'
...
>>> g = gen()
>>> getgeneratorstate(g)
'GEN_CREATED'
>>> next(g)
'demo'
>>> getgeneratorstate(g)
'GEN_SUSPENDED'
>>> next(g, None)
>>> getgeneratorstate(g)
'GEN_CLOSED'
@end example

(Contribution par Rodolpho Eckhardt et Nick Coghlan; bpo-10220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10220}.)

@item 
To support lookups without the possibility of activating a dynamic attribute,
the @ref{7d,,inspect} module has a new function, @ref{47e,,getattr_static()}.
Unlike @ref{4bb,,hasattr()}, this is a true read-only search, guaranteed not to
change state while it is searching:

@example
>>> class A:
...     @@property
...     def f(self):
...         print('Running')
...         return 10
...
>>> a = A()
>>> getattr(a, 'f')
Running
10
>>> inspect.getattr_static(a, 'f')
<property object at 0x1022bd788>
@end example
@end itemize

@quotation

(Contributed by Michael Foord.)
@end quotation

@node pydoc<6>,dis<5>,inspect<10>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 pydoc}@anchor{1215}
@subsubsection `pydoc'


The @ref{b4,,pydoc} module now provides a much-improved web server interface, as
well as a new command-line option @code{-b} to automatically open a browser window
to display that server:

@example
$ pydoc3.2 -b
@end example

(Contribution par Ron Adam; bpo-2001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2001}.)

@node dis<5>,dbm<7>,pydoc<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 dis}@anchor{1216}
@subsubsection dis


The @ref{38,,dis} module gained two new functions for inspecting code,
@ref{1217,,code_info()} and @ref{f17,,show_code()}.  Both provide detailed code
object information for the supplied function, method, source code string or code
object.  The former returns a string and the latter prints it:

@example
>>> import dis, random
>>> dis.show_code(random.choice)
Name:              choice
Filename:          /Library/Frameworks/Python.framework/Versions/3.2/lib/python3.2/random.py
Argument count:    2
Kw-only arguments: 0
Number of locals:  3
Stack size:        11
Flags:             OPTIMIZED, NEWLOCALS, NOFREE
Constants:
   0: 'Choose a random element from a non-empty sequence.'
   1: 'Cannot choose from an empty sequence'
Names:
   0: _randbelow
   1: len
   2: ValueError
   3: IndexError
Variable names:
   0: self
   1: seq
   2: i
@end example

In addition, the @ref{b22,,dis()} function now accepts string arguments
so that the common idiom @code{dis(compile(s, '@w{'}, 'eval'))} can be shortened
to @code{dis(s)}:

@example
>>> dis('3*x+1 if x%2==1 else x//2')
  1           0 LOAD_NAME                0 (x)
              3 LOAD_CONST               0 (2)
              6 BINARY_MODULO
              7 LOAD_CONST               1 (1)
             10 COMPARE_OP               2 (==)
             13 POP_JUMP_IF_FALSE       28
             16 LOAD_CONST               2 (3)
             19 LOAD_NAME                0 (x)
             22 BINARY_MULTIPLY
             23 LOAD_CONST               1 (1)
             26 BINARY_ADD
             27 RETURN_VALUE
        >>   28 LOAD_NAME                0 (x)
             31 LOAD_CONST               0 (2)
             34 BINARY_FLOOR_DIVIDE
             35 RETURN_VALUE
@end example

Taken together, these improvements make it easier to explore how CPython is
implemented and to see for yourself what the language syntax does
under-the-hood.

(Contribution par Nick Coghlan; bpo-9147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9147}.)

@node dbm<7>,ctypes<3>,dis<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 dbm}@anchor{1218}
@subsubsection dbm


All database modules now support the @code{get()} and @code{setdefault()} methods.

(Suggested by Ray Allen in bpo-9523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9523}.)

@node ctypes<3>,site<4>,dbm<7>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 ctypes}@anchor{1219}
@subsubsection ctypes


A new type, @ref{121a,,ctypes.c_ssize_t} represents the C @code{ssize_t} datatype.

@node site<4>,sysconfig<3>,ctypes<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 site}@anchor{121b}
@subsubsection @code{site}


The @ref{c6,,site} module has three new functions useful for reporting on the
details of a given Python installation.


@itemize *

@item 
@ref{121c,,getsitepackages()} lists all global site-packages directories.

@item 
@ref{121d,,getuserbase()} reports on the user's base directory where data can
be stored.

@item 
@ref{121e,,getusersitepackages()} reveals the user-specific site-packages
directory path.
@end itemize

@example
>>> import site
>>> site.getsitepackages()
['/Library/Frameworks/Python.framework/Versions/3.2/lib/python3.2/site-packages',
 '/Library/Frameworks/Python.framework/Versions/3.2/lib/site-python',
 '/Library/Python/3.2/site-packages']
>>> site.getuserbase()
'/Users/raymondhettinger/Library/Python/3.2'
>>> site.getusersitepackages()
'/Users/raymondhettinger/Library/Python/3.2/lib/python/site-packages'
@end example

Conveniently, some of site's functionality is accessible directly from the
command-line:

@example
$ python -m site --user-base
/Users/raymondhettinger/.local
$ python -m site --user-site
/Users/raymondhettinger/.local/lib/python3.2/site-packages
@end example

(Contribution par Tarek Ziadé; bpo-6693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6693}.)

@node sysconfig<3>,pdb<8>,site<4>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 sysconfig}@anchor{121f}
@subsubsection @code{sysconfig}


The new @ref{da,,sysconfig} module makes it straightforward to discover
installation paths and configuration variables that vary across platforms and
installations.

The module offers access simple access functions for platform and version
information:


@itemize *

@item 
@ref{1220,,get_platform()} returning values like `linux-i586' or
`macosx-10.6-ppc'.

@item 
@ref{1221,,get_python_version()} returns a Python version string
such as "3.2".
@end itemize

It also provides access to the paths and variables corresponding to one of
seven named schemes used by @code{distutils}.  Those include `posix_prefix',
`posix_home', `posix_user', `nt', `nt_user', `os2', `os2_home':


@itemize *

@item 
@ref{1222,,get_paths()} makes a dictionary containing installation paths
for the current installation scheme.

@item 
@ref{1015,,get_config_vars()} returns a dictionary of platform specific
variables.
@end itemize

There is also a convenient command-line interface:

@example
C:\Python32>python -m sysconfig
Platform: "win32"
Python version: "3.2"
Current installation scheme: "nt"

Paths:
        data = "C:\Python32"
        include = "C:\Python32\Include"
        platinclude = "C:\Python32\Include"
        platlib = "C:\Python32\Lib\site-packages"
        platstdlib = "C:\Python32\Lib"
        purelib = "C:\Python32\Lib\site-packages"
        scripts = "C:\Python32\Scripts"
        stdlib = "C:\Python32\Lib"

Variables:
        BINDIR = "C:\Python32"
        BINLIBDEST = "C:\Python32\Lib"
        EXE = ".exe"
        INCLUDEPY = "C:\Python32\Include"
        LIBDEST = "C:\Python32\Lib"
        SO = ".pyd"
        VERSION = "32"
        abiflags = ""
        base = "C:\Python32"
        exec_prefix = "C:\Python32"
        platbase = "C:\Python32"
        prefix = "C:\Python32"
        projectbase = "C:\Python32"
        py_version = "3.2"
        py_version_nodot = "32"
        py_version_short = "3.2"
        srcdir = "C:\Python32"
        userbase = "C:\Documents and Settings\Raymond\Application Data\Python"
@end example

(Moved out of Distutils by Tarek Ziadé.)

@node pdb<8>,configparser<5>,sysconfig<3>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 pdb}@anchor{1223}
@subsubsection `pdb'


The @ref{a4,,pdb} debugger module gained a number of usability improvements:


@itemize *

@item 
@code{pdb.py} now has a @code{-c} option that executes commands as given in a
@code{.pdbrc} script file.

@item 
A @code{.pdbrc} script file can contain @code{continue} and @code{next} commands
that continue debugging.

@item 
The @ref{90f,,Pdb} class constructor now accepts a `nosigint' argument.

@item 
New commands: @code{l(list)}, @code{ll(long list)} and @code{source} for
listing source code.

@item 
New commands: @code{display} and @code{undisplay} for showing or hiding
the value of an expression if it has changed.

@item 
New command: @code{interact} for starting an interactive interpreter containing
the global and local  names found in the current scope.

@item 
Breakpoints can be cleared by breakpoint number.
@end itemize

(Contributed by Georg Brandl, Antonio Cuni and Ilya Sandler.)

@node configparser<5>,urllib parse<6>,pdb<8>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 configparser}@anchor{1224}
@subsubsection configparser


The @ref{22,,configparser} module was modified to improve usability and
predictability of the default parser and its supported INI syntax.  The old
@code{ConfigParser} class was removed in favor of @code{SafeConfigParser}
which has in turn been renamed to @ref{1c3,,ConfigParser}. Support
for inline comments is now turned off by default and section or option
duplicates are not allowed in a single configuration source.

Config parsers gained a new API based on the mapping protocol:

@example
>>> parser = ConfigParser()
>>> parser.read_string("""
... [DEFAULT]
... location = upper left
... visible = yes
... editable = no
... color = blue
...
... [main]
... title = Main Menu
... color = green
...
... [options]
... title = Options
... """)
>>> parser['main']['color']
'green'
>>> parser['main']['editable']
'no'
>>> section = parser['options']
>>> section['title']
'Options'
>>> section['title'] = 'Options (editable: %(editable)s)'
>>> section['title']
'Options (editable: no)'
@end example

The new API is implemented on top of the classical API, so custom parser
subclasses should be able to use it without modifications.

The INI file structure accepted by config parsers can now be customized. Users
can specify alternative option/value delimiters and comment prefixes, change the
name of the `DEFAULT' section or switch the interpolation syntax.

There is support for pluggable interpolation including an additional interpolation
handler @ref{70d,,ExtendedInterpolation}:

@example
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> parser.read_dict(@{'buildout': @{'directory': '/home/ambv/zope9'@},
...                   'custom': @{'prefix': '/usr/local'@}@})
>>> parser.read_string("""
... [buildout]
... parts =
...   zope9
...   instance
... find-links =
...   $@{buildout:directory@}/downloads/dist
...
... [zope9]
... recipe = plone.recipe.zope9install
... location = /opt/zope
...
... [instance]
... recipe = plone.recipe.zope9instance
... zope9-location = $@{zope9:location@}
... zope-conf = $@{custom:prefix@}/etc/zope.conf
... """)
>>> parser['buildout']['find-links']
'\n/home/ambv/zope9/downloads/dist'
>>> parser['instance']['zope-conf']
'/usr/local/etc/zope.conf'
>>> instance = parser['instance']
>>> instance['zope-conf']
'/usr/local/etc/zope.conf'
>>> instance['zope9-location']
'/opt/zope'
@end example

A number of smaller features were also introduced, like support for specifying
encoding in read operations, specifying fallback values for get-functions, or
reading directly from dictionaries and strings.

(All changes contributed by Łukasz Langa.)

@c XXX consider showing a difflib example

@node urllib parse<6>,mailbox,configparser<5>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 urllib-parse}@anchor{1225}
@subsubsection urllib.parse


A number of usability improvements were made for the @ref{109,,urllib.parse} module.

The @ref{302,,urlparse()} function now supports IPv6@footnote{https://en.wikipedia.org/wiki/IPv6} addresses as described in 
@geindex RFC; RFC 2732
RFC 2732@footnote{https://datatracker.ietf.org/doc/html/rfc2732.html}:

@example
>>> import urllib.parse
>>> urllib.parse.urlparse('http://[dead:beef:cafe:5417:affe:8FA3:deaf:feed]/foo/') 
ParseResult(scheme='http',
            netloc='[dead:beef:cafe:5417:affe:8FA3:deaf:feed]',
            path='/foo/',
            params='@w{'},
            query='@w{'},
            fragment='@w{'})
@end example

The @ref{1226,,urldefrag()} function now returns a @ref{639,,named tuple}:

@example
>>> r = urllib.parse.urldefrag('http://python.org/about/#target')
>>> r
DefragResult(url='http://python.org/about/', fragment='target')
>>> r[0]
'http://python.org/about/'
>>> r.fragment
'target'
@end example

And, the @ref{e7e,,urlencode()} function is now much more flexible,
accepting either a string or bytes type for the `query' argument.  If it is a
string, then the `safe', `encoding', and `error' parameters are sent to
@ref{1227,,quote_plus()} for encoding:

@example
>>> urllib.parse.urlencode([
...      ('type', 'telenovela'),
...      ('name', '¿Dónde Está Elisa?')],
...      encoding='latin-1')
'type=telenovela&name=%BFD%F3nde+Est%E1+Elisa%3F'
@end example

As detailed in @ref{1228,,Parsing ASCII Encoded Bytes}, all the @ref{109,,urllib.parse}
functions now accept ASCII-encoded byte strings as input, so long as they are
not mixed with regular strings.  If ASCII-encoded byte strings are given as
parameters, the return types will also be an ASCII-encoded byte strings:

@example
>>> urllib.parse.urlparse(b'http://www.python.org:80/about/') 
ParseResultBytes(scheme=b'http', netloc=b'www.python.org:80',
                 path=b'/about/', params=b'@w{'}, query=b'@w{'}, fragment=b'@w{'})
@end example

(Work by Nick Coghlan, Dan Mahn, and Senthil Kumaran in bpo-2987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2987},
bpo-5468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5468}, and bpo-9873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9873}.)

@node mailbox,turtledemo,urllib parse<6>,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 mailbox}@anchor{1229}
@subsubsection mailbox


Thanks to a concerted effort by R. David Murray, the @ref{8a,,mailbox} module has
been fixed for Python 3.2.  The challenge was that mailbox had been originally
designed with a text interface, but email messages are best represented with
@ref{1bd,,bytes} because various parts of a message may have different encodings.

The solution harnessed the @ref{3b,,email} package's binary support for parsing
arbitrary email messages.  In addition, the solution required a number of API
changes.

As expected, the @ref{122a,,add()} method for
@ref{122b,,mailbox.Mailbox} objects now accepts binary input.

@ref{f12,,StringIO} and text file input are deprecated.  Also, string input
will fail early if non-ASCII characters are used.  Previously it would fail when
the email was processed in a later step.

There is also support for binary output.  The @ref{122c,,get_file()}
method now returns a file in the binary mode (where it used to incorrectly set
the file to text-mode).  There is also a new @ref{122d,,get_bytes()}
method that returns a @ref{1bd,,bytes} representation of a message corresponding
to a given `key'.

It is still possible to get non-binary output using the old API's
@ref{122e,,get_string()} method, but that approach
is not very useful.  Instead, it is best to extract messages from
a @ref{122f,,Message} object or to load them from binary input.

(Contributed by R. David Murray, with efforts from Steffen Daode Nurpmeso and an
initial patch by Victor Stinner in bpo-9124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9124}.)

@node turtledemo,,mailbox,New Improved and Deprecated Modules
@anchor{whatsnew/3 2 turtledemo}@anchor{1230}
@subsubsection turtledemo


The demonstration code for the @ref{100,,turtle} module was moved from the `Demo'
directory to main library.  It includes over a dozen sample scripts with
lively displays.  Being on @ref{3ab,,sys.path}, it can now be run directly
from the command-line:

@example
$ python -m turtledemo
@end example

(Moved from the Demo directory by Alexander Belopolsky in bpo-10199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10199}.)

@node Fils d'exécution,Optimizations<6>,New Improved and Deprecated Modules,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 multi-threading}@anchor{1231}
@subsection Fils d'exécution



@itemize *

@item 
The mechanism for serializing execution of concurrently running Python threads
(generally known as the @ref{158,,GIL} or Global Interpreter Lock) has
been rewritten.  Among the objectives were more predictable switching
intervals and reduced overhead due to lock contention and the number of
ensuing system calls.  The notion of a "check interval" to allow thread
switches has been abandoned and replaced by an absolute duration expressed in
seconds.  This parameter is tunable through @ref{937,,sys.setswitchinterval()}.
It currently defaults to 5 milliseconds.

Additional details about the implementation can be read from a python-dev mailing-list message@footnote{https://mail.python.org/pipermail/python-dev/2009-October/093321.html}
(however, "priority requests" as exposed in this message have not been kept
for inclusion).

(Contribution par Antoine Pitrou)

@item 
Les verrous standards et récursifs acceptent désormais un argument optionnel `timeout' à leur méthode @ref{683,,acquire()}. (Contribution par Antoine Pitrou; bpo-7316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7316}).

@item 
Pareillement, @ref{1232,,threading.Semaphore.acquire()} acquière un argument `timeout' (Contribution par Torsten Landschoff; bpo-850728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=850728}).

@item 
Regular and recursive lock acquisitions can now be interrupted by signals on
platforms using Pthreads.  This means that Python programs that deadlock while
acquiring locks can be successfully killed by repeatedly sending SIGINT to the
process (by pressing @code{Ctrl+C} in most shells).
(Contributed by Reid Kleckner; bpo-8844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8844}.)
@end itemize

@node Optimizations<6>,Unicode,Fils d'exécution,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 optimizations}@anchor{1233}
@subsection Optimizations


A number of small performance enhancements have been added:


@itemize *

@item 
Python's peephole optimizer now recognizes patterns such @code{x in @{1, 2, 3@}} as
being a test for membership in a set of constants.  The optimizer recasts the
@ref{5c3,,set} as a @ref{5c4,,frozenset} and stores the pre-built constant.

Now that the speed penalty is gone, it is practical to start writing
membership tests using set-notation.  This style is both semantically clear
and operationally fast:

@example
extension = name.rpartition('.')[2]
if extension in @{'xml', 'html', 'xhtml', 'css'@}:
    handle(name)
@end example

(Patch and additional tests contributed by Dave Malcolm; bpo-6690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6690}).

@item 
Serializing and unserializing data using the @ref{a5,,pickle} module is now
several times faster.

(Contributed by Alexandre Vassalotti, Antoine Pitrou
and the Unladen Swallow team in bpo-9410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9410} and bpo-3873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3873}.)

@item 
The Timsort algorithm@footnote{https://en.wikipedia.org/wiki/Timsort} used in
@ref{bbd,,list.sort()} and @ref{bbc,,sorted()} now runs faster and uses less memory
when called with a @ref{df2,,key function}.  Previously, every element of
a list was wrapped with a temporary object that remembered the key value
associated with each element.  Now, two arrays of keys and values are
sorted in parallel.  This saves the memory consumed by the sort wrappers,
and it saves time lost to delegating comparisons.

(Patch by Daniel Stutzbach in bpo-9915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9915}.)

@item 
JSON decoding performance is improved and memory consumption is reduced
whenever the same string is repeated for multiple keys.  Also, JSON encoding
now uses the C speedups when the @code{sort_keys} argument is true.

(Contributed by Antoine Pitrou in bpo-7451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7451} and by Raymond Hettinger and
Antoine Pitrou in bpo-10314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10314}.)

@item 
Recursive locks (created with the @ref{2dc,,threading.RLock()} API) now benefit
from a C implementation which makes them as fast as regular locks, and between
10x and 15x faster than their previous pure Python implementation.

(Contribution par Antoine Pitrou; bpo-3001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3001}.)

@item 
The fast-search algorithm in stringlib is now used by the @ref{e93,,split()},
@ref{1234,,rsplit()}, @ref{1235,,splitlines()} and @ref{198,,replace()} methods on
@ref{1bd,,bytes}, @ref{528,,bytearray} and @ref{435,,str} objects. Likewise, the
algorithm is also used by @ref{e92,,rfind()}, @ref{1236,,rindex()}, @ref{1234,,rsplit()} and
@ref{1237,,rpartition()}.

(Patch by Florent Xicluna in bpo-7622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7622} and bpo-7462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7462}.)

@item 
Integer to string conversions now work two "digits" at a time, reducing the
number of division and modulo operations.

(bpo-6713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6713} by Gawain Bolton, Mark Dickinson, and Victor Stinner.)
@end itemize

There were several other minor optimizations. Set differencing now runs faster
when one operand is much larger than the other (patch by Andress Bennetts in
bpo-8685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8685}).  The @code{array.repeat()} method has a faster implementation
(bpo-1569291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1569291} by Alexander Belopolsky). The @ref{10ad,,BaseHTTPRequestHandler}
has more efficient buffering (bpo-3709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3709} by Andrew Schaaf).  The
@ref{e20,,operator.attrgetter()} function has been sped-up (bpo-10160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10160} by
Christos Georgiou).  And @ref{1c3,,ConfigParser} loads multi-line arguments a bit
faster (bpo-7113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7113} by Łukasz Langa).

@node Unicode,Codecs,Optimizations<6>,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 unicode}@anchor{1238}
@subsection Unicode


Python has been updated to Unicode 6.0.0@footnote{https://unicode.org/versions/Unicode6.0.0/}.  The update to the standard adds
over 2,000 new characters including emoji@footnote{https://en.wikipedia.org/wiki/Emoji}
symbols which are important for mobile phones.

In addition, the updated standard has altered the character properties for two
Kannada characters (U+0CF1, U+0CF2) and one New Tai Lue numeric character
(U+19DA), making the former eligible for use in identifiers while disqualifying
the latter.  For more information, see Unicode Character Database Changes@footnote{https://www.unicode.org/versions/Unicode6.0.0/#Database_Changes}.

@node Codecs,Documentation,Unicode,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 codecs}@anchor{1239}
@subsection Codecs


Support was added for `cp720' Arabic DOS encoding (bpo-1616979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1616979}).

MBCS encoding no longer ignores the error handler argument. In the default
strict mode, it raises an @ref{a01,,UnicodeDecodeError} when it encounters an
undecodable byte sequence and an @ref{662,,UnicodeEncodeError} for an unencodable
character.

The MBCS codec supports @code{'strict'} and @code{'ignore'} error handlers for
decoding, and @code{'strict'} and @code{'replace'} for encoding.

To emulate Python3.1 MBCS encoding, select the @code{'ignore'} handler for decoding
and the @code{'replace'} handler for encoding.

On Mac OS X, Python decodes command line arguments with @code{'utf-8'} rather than
the locale encoding.

By default, @ref{dd,,tarfile} uses @code{'utf-8'} encoding on Windows (instead of
@code{'mbcs'}) and the @code{'surrogateescape'} error handler on all operating
systems.

@node Documentation,IDLE,Codecs,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 documentation}@anchor{123a}
@subsection Documentation


The documentation continues to be improved.


@itemize *

@item 
A table of quick links has been added to the top of lengthy sections such as
@ref{123b,,Fonctions natives}.  In the case of @ref{80,,itertools}, the links are
accompanied by tables of cheatsheet-style summaries to provide an overview and
memory jog without having to read all of the docs.

@item 
In some cases, the pure Python source code can be a helpful adjunct to the
documentation, so now many modules now feature quick links to the latest
version of the source code.  For example, the @ref{5e,,functools} module
documentation has a quick link at the top labeled:

@quotation

`Source code' Lib/functools.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/functools.py}.
@end quotation

(Contributed by Raymond Hettinger; see
rationale@footnote{https://rhettinger.wordpress.com/2011/01/28/open-your-source-more/}.)

@item 
The docs now contain more examples and recipes.  In particular, @ref{b8,,re}
module has an extensive section, @ref{123c,,Exemples d'expressions rationnelles}.  Likewise, the
@ref{80,,itertools} module continues to be updated with new
@ref{123d,,Recettes itertools}.

@item 
The @ref{30,,datetime} module now has an auxiliary implementation in pure Python.
No functionality was changed.  This just provides an easier-to-read alternate
implementation.

(Contribution par Alexander Belopolsky; bpo-9528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9528}.)

@item 
The unmaintained @code{Demo} directory has been removed.  Some demos were
integrated into the documentation, some were moved to the @code{Tools/demo}
directory, and others were removed altogether.

(Contribution par Georg Brandl; bpo-7962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7962}.)
@end itemize

@node IDLE,Code Repository,Documentation,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 idle}@anchor{123e}
@subsection IDLE



@itemize *

@item 
The format menu now has an option to clean source files by stripping
trailing whitespace.

(Contribution par Raymond Hettinger; bpo-5150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5150}.)

@item 
IDLE on Mac OS X now works with both Carbon AquaTk and Cocoa AquaTk.

(Contributed by Kevin Walzer, Ned Deily, and Ronald Oussoren; bpo-6075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6075}.)
@end itemize

@node Code Repository,Build and C API Changes<5>,IDLE,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 code-repository}@anchor{123f}
@subsection Code Repository


In addition to the existing Subversion code repository at @indicateurl{https://svn.python.org}
there is now a Mercurial@footnote{https://www.mercurial-scm.org/} repository at
@indicateurl{https://hg.python.org/}.

After the 3.2 release, there are plans to switch to Mercurial as the primary
repository.  This distributed version control system should make it easier for
members of the community to create and share external changesets.  See
@geindex Python Enhancement Proposals; PEP 385
PEP 385@footnote{https://peps.python.org/pep-0385/} for details.

To learn to use the new version control system, see the Quick Start@footnote{https://www.mercurial-scm.org/wiki/QuickStart} or the Guide to Mercurial Workflows@footnote{https://www.mercurial-scm.org/guide}.

@node Build and C API Changes<5>,Portage vers Python 3 2,Code Repository,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 build-and-c-api-changes}@anchor{1240}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
The `idle', `pydoc' and `2to3' scripts are now installed with a
version-specific suffix on @code{make altinstall} (bpo-10679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10679}).

@item 
The C functions that access the Unicode Database now accept and return
characters from the full Unicode range, even on narrow unicode builds
(Py_UNICODE_TOLOWER, Py_UNICODE_ISDECIMAL, and others).  A visible difference
in Python is that @ref{1241,,unicodedata.numeric()} now returns the correct value
for large code points, and @ref{7e7,,repr()} may consider more characters as
printable.

(Reported by Bupjoe Lee and fixed by Amaury Forgeot D'Arc; bpo-5127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5127}.)

@item 
Computed gotos are now enabled by default on supported compilers (which are
detected by the configure script).  They can still be disabled selectively by
specifying @code{--without-computed-gotos}.

(Contribution par Antoine Pitrou; bpo-9203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9203}.)

@item 
The option @code{--with-wctype-functions} was removed.  The built-in unicode
database is now used for all functions.

(Contribution par Amaury Forgeot D'Arc; bpo-9210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9210}.)

@item 
Hash values are now values of a new type, @ref{1242,,Py_hash_t}, which is
defined to be the same size as a pointer.  Previously they were of type long,
which on some 64-bit operating systems is still only 32 bits long.  As a
result of this fix, @ref{5c3,,set} and @ref{253,,dict} can now hold more than
@code{2**32} entries on builds with 64-bit pointers (previously, they could grow
to that size but their performance degraded catastrophically).

(Suggested by Raymond Hettinger and implemented by Benjamin Peterson;
bpo-9778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9778}.)

@item 
A new macro @code{Py_VA_COPY} copies the state of the variable argument
list.  It is equivalent to C99 `va_copy' but available on all Python platforms
(bpo-2443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2443}).

@item 
A new C API function @code{PySys_SetArgvEx()} allows an embedded interpreter
to set @ref{1243,,sys.argv} without also modifying @ref{3ab,,sys.path}
(bpo-5753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5753}).

@item 
@code{PyEval_CallObject()} is now only available in macro form.  The
function declaration, which was kept for backwards compatibility reasons, is
now removed -- the macro was introduced in 1997 (bpo-8276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8276}).

@item 
There is a new function @ref{1244,,PyLong_AsLongLongAndOverflow()} which
is analogous to @ref{1245,,PyLong_AsLongAndOverflow()}.  They both serve to
convert Python @ref{254,,int} into a native fixed-width type while providing
detection of cases where the conversion won't fit (bpo-7767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7767}).

@item 
The @ref{1246,,PyUnicode_CompareWithASCIIString()} function now returns `not
equal' if the Python string is `NUL' terminated.

@item 
There is a new function @ref{1247,,PyErr_NewExceptionWithDoc()} that is
like @ref{1248,,PyErr_NewException()} but allows a docstring to be specified.
This lets C exceptions have the same self-documenting capabilities as
their pure Python counterparts (bpo-7033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7033}).

@item 
When compiled with the @code{--with-valgrind} option, the pymalloc
allocator will be automatically disabled when running under Valgrind.  This
gives improved memory leak detection when running under Valgrind, while taking
advantage of pymalloc at other times (bpo-2422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2422}).

@item 
Removed the @code{O?} format from the `PyArg_Parse' functions.  The format is no
longer used and it had never been documented (bpo-8837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8837}).
@end itemize

There were a number of other small changes to the C-API.  See the
Misc/NEWS@footnote{https://github.com/python/cpython/blob/v3.2.6/Misc/NEWS}
file for a complete list.

Also, there were a number of updates to the Mac OS X build, see
Mac/BuildScript/README.txt@footnote{https://github.com/python/cpython/blob/v3.2.6/Mac/BuildScript/README.txt}
for details.  For users running a 32/64-bit
build, there is a known problem with the default Tcl/Tk on Mac OS X 10.6.
Accordingly, we recommend installing an updated alternative such as
ActiveState Tcl/Tk 8.5.9@footnote{https://web.archive.org/web/20101208191259/https://www.activestate.com/activetcl/downloads}.
See @indicateurl{https://www.python.org/download/mac/tcltk/} for additional details.

@node Portage vers Python 3 2,,Build and C API Changes<5>,Nouveautés de Python 3 2
@anchor{whatsnew/3 2 porting-to-python-3-2}@anchor{1249}
@subsection Portage vers Python 3.2


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


@itemize *

@item 
The @ref{22,,configparser} module has a number of clean-ups.  The major change is
to replace the old @code{ConfigParser} class with long-standing preferred
alternative @code{SafeConfigParser}.  In addition there are a number of
smaller incompatibilities:


@itemize *

@item 
The interpolation syntax is now validated on
@ref{124a,,get()} and
@ref{124b,,set()} operations. In the default
interpolation scheme, only two tokens with percent signs are valid: @code{%(name)s}
and @code{%%}, the latter being an escaped percent sign.

@item 
The @ref{124b,,set()} and
@ref{124c,,add_section()} methods now verify that
values are actual strings.  Formerly, unsupported types could be introduced
unintentionally.

@item 
Duplicate sections or options from a single source now raise either
@ref{124d,,DuplicateSectionError} or
@ref{124e,,DuplicateOptionError}.  Formerly, duplicates would
silently overwrite a previous entry.

@item 
Inline comments are now disabled by default so now the `;' character
can be safely used in values.

@item 
Comments now can be indented.  Consequently, for `;' or `#' to appear at
the start of a line in multiline values, it has to be interpolated.  This
keeps comment prefix characters in values from being mistaken as comments.

@item 
@code{""} is now a valid value and is no longer automatically converted to an
empty string. For empty strings, use @code{"option ="} in a line.
@end itemize

@item 
The @code{nntplib} module was reworked extensively, meaning that its APIs
are often incompatible with the 3.1 APIs.

@item 
Les objets @ref{528,,bytearray} ne peuvent plus être utilisés en tant que nom de fichiers : ils doivent être convertis en @ref{1bd,,bytes} à la place.

@item 
The @code{array.tostring()} and @code{array.fromstring()} have been renamed to
@ref{124f,,array.tobytes()} and
@ref{1250,,array.frombytes()} for clarity.  The old names
have been deprecated. (See bpo-8990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8990}.)

@item 
Les fonctions @code{PyArg_Parse*()} :


@itemize *

@item 
Le format "t#" a été supprimé : utiliser "s#" ou "s*" à la place

@item 
Les formats "w" et "w#" ont été supprimés : utiliser "w*" à la place
@end itemize

@item 
The @code{PyCObject} type, deprecated in 3.1, has been removed.  To wrap
opaque C pointers in Python objects, the @ref{1251,,PyCapsule} API should be used
instead; the new type has a well-defined interface for passing typing safety
information and a less complicated signature for calling a destructor.

@item 
The @code{sys.setfilesystemencoding()} function was removed because
it had a flawed design.

@item 
The @ref{1252,,random.seed()} function and method now salt string seeds with an
sha512 hash function.  To access the previous version of `seed' in order to
reproduce Python 3.1 sequences, set the `version' argument to `1',
@code{random.seed(s, version=1)}.

@item 
The previously deprecated @code{string.maketrans()} function has been removed
in favor of the static methods @ref{1253,,bytes.maketrans()} and
@ref{1254,,bytearray.maketrans()}.  This change solves the confusion around which
types were supported by the @ref{d2,,string} module.  Now, @ref{435,,str},
@ref{1bd,,bytes}, and @ref{528,,bytearray} each have their own `maketrans' and
`translate' methods with intermediate translation tables of the appropriate
type.

(Contribution par Georg Brandl; bpo-5675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5675}.)

@item 
The previously deprecated @code{contextlib.nested()} function has been removed
in favor of a plain @ref{5bc,,with} statement which can accept multiple
context managers.  The latter technique is faster (because it is built-in),
and it does a better job finalizing multiple context managers when one of them
raises an exception:

@example
with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
    for line in infile:
        if '<critical>' in line:
            outfile.write(line)
@end example

(Contributed by Georg Brandl and Mattias Brändström;
appspot issue 53094@footnote{https://codereview.appspot.com/53094}.)

@item 
@ref{1255,,struct.pack()} now only allows bytes for the @code{s} string pack code.
Formerly, it would accept text arguments and implicitly encode them to bytes
using UTF-8.  This was problematic because it made assumptions about the
correct encoding and because a variable-length encoding can fail when writing
to fixed length segment of a structure.

Code such as @code{struct.pack('<6sHHBBB', 'GIF87a', x, y)} should be rewritten
with to use bytes instead of text, @code{struct.pack('<6sHHBBB', b'GIF87a', x, y)}.

(Discovered by David Beazley and fixed by Victor Stinner; bpo-10783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10783}.)

@item 
The @ref{124,,xml.etree.ElementTree} class now raises an
@ref{1256,,xml.etree.ElementTree.ParseError} when a parse fails. Previously it
raised an @ref{1257,,xml.parsers.expat.ExpatError}.

@item 
The new, longer @ref{435,,str()} value on floats may break doctests which rely on
the old output format.

@item 
In @ref{197,,subprocess.Popen}, the default value for `close_fds' is now
@code{True} under Unix; under Windows, it is @code{True} if the three standard
streams are set to @code{None}, @code{False} otherwise.  Previously, `close_fds'
was always @code{False} by default, which produced difficult to solve bugs
or race conditions when open file descriptors would leak into the child
process.

@item 
Support for legacy HTTP 0.9 has been removed from @ref{10a,,urllib.request}
and @ref{6e,,http.client}.  Such support is still present on the server side
(in @ref{71,,http.server}).

(Contribution par Antoine Pitrou; bpo-10711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10711}.)

@item 
SSL sockets in timeout mode now raise @ref{81e,,socket.timeout} when a timeout
occurs, rather than a generic @ref{1258,,SSLError}.

(Contribution par Antoine Pitrou; bpo-10272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10272}.)

@item 
The misleading functions @code{PyEval_AcquireLock()} and
@code{PyEval_ReleaseLock()} have been officially deprecated.  The
thread-state aware APIs (such as @ref{39f,,PyEval_SaveThread()}
and @ref{3a0,,PyEval_RestoreThread()}) should be used instead.

@item 
Due to security risks, @code{asyncore.handle_accept()} has been deprecated, and
a new function, @code{asyncore.handle_accepted()}, was added to replace it.

(Contribution par Giampaolo Rodola; bpo-6706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6706}.)

@item 
Due to the new @ref{158,,GIL} implementation, @code{PyEval_InitThreads()}
cannot be called before @ref{899,,Py_Initialize()} anymore.
@end itemize

@node Nouveautés de Python 3 1,Nouveautés de Python 3 0,Nouveautés de Python 3 2,Nouveautés de Python
@anchor{whatsnew/3 1 doc}@anchor{1259}@anchor{whatsnew/3 1 what-s-new-in-python-3-1}@anchor{125a}
@section Nouveautés de Python 3.1


@*Auteur: 
Raymond Hettinger


@c $Id$
@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c % Patch 12345
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer.)
@c 
@c This saves the maintainer the effort of going through the SVN log
@c when researching a change.

This article explains the new features in Python 3.1, compared to 3.0.
Python 3.1 was released on June 27, 2009.

@menu
* PEP 372; Ordered Dictionaries: PEP 372 Ordered Dictionaries. 
* PEP 378; Format Specifier for Thousands Separator: PEP 378 Format Specifier for Thousands Separator. 
* Autres changements au langage: Autres changements au langage<13>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<2>. 
* Optimizations: Optimizations<7>. 
* IDLE: IDLE<2>. 
* Build and C API Changes: Build and C API Changes<6>. 
* Portage vers Python 3.1: Portage vers Python 3 1. 

@end menu

@node PEP 372 Ordered Dictionaries,PEP 378 Format Specifier for Thousands Separator,,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 pep-372-ordered-dictionaries}@anchor{125b}
@subsection PEP 372: Ordered Dictionaries


Regular Python dictionaries iterate over key/value pairs in arbitrary order.
Over the years, a number of authors have written alternative implementations
that remember the order that the keys were originally inserted.  Based on
the experiences from those implementations, a new
@ref{5c5,,collections.OrderedDict} class has been introduced.

The OrderedDict API is substantially the same as regular dictionaries
but will iterate over keys and values in a guaranteed order depending on
when a key was first inserted.  If a new entry overwrites an existing entry,
the original insertion position is left unchanged.  Deleting an entry and
reinserting it will move it to the end.

The standard library now supports use of ordered dictionaries in several
modules.  The @ref{22,,configparser} module uses them by default.  This lets
configuration files be read, modified, and then written back in their original
order.  The `_asdict()' method for @ref{1c5,,collections.namedtuple()} now
returns an ordered dictionary with the values appearing in the same order as
the underlying tuple indices.  The @ref{81,,json} module is being built-out with
an `object_pairs_hook' to allow OrderedDicts to be built by the decoder.
Support was also added for third-party tools like PyYAML@footnote{https://pyyaml.org/}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 372

@item PEP 372@footnote{https://peps.python.org/pep-0372/} - Ordered Dictionaries

PEP written by Armin Ronacher and Raymond Hettinger.  Implementation
written by Raymond Hettinger.
@end table


Since an ordered dictionary remembers its insertion order, it can be used
in conjunction with sorting to make a sorted dictionary:

@example
>>> # regular unsorted dictionary
>>> d = @{'banana': 3, 'apple':4, 'pear': 1, 'orange': 2@}

>>> # dictionary sorted by key
>>> OrderedDict(sorted(d.items(), key=lambda t: t[0]))
OrderedDict([('apple', 4), ('banana', 3), ('orange', 2), ('pear', 1)])

>>> # dictionary sorted by value
>>> OrderedDict(sorted(d.items(), key=lambda t: t[1]))
OrderedDict([('pear', 1), ('orange', 2), ('banana', 3), ('apple', 4)])

>>> # dictionary sorted by length of the key string
>>> OrderedDict(sorted(d.items(), key=lambda t: len(t[0])))
OrderedDict([('pear', 1), ('apple', 4), ('orange', 2), ('banana', 3)])
@end example

The new sorted dictionaries maintain their sort order when entries
are deleted.  But when new keys are added, the keys are appended
to the end and the sort is not maintained.

@node PEP 378 Format Specifier for Thousands Separator,Autres changements au langage<13>,PEP 372 Ordered Dictionaries,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 pep-378-format-specifier-for-thousands-separator}@anchor{125c}
@subsection PEP 378: Format Specifier for Thousands Separator


The built-in @ref{60a,,format()} function and the @ref{60c,,str.format()} method use
a mini-language that now includes a simple, non-locale aware way to format
a number with a thousands separator.  That provides a way to humanize a
program's output, improving its professional appearance and readability:

@example
>>> format(1234567, ',d')
'1,234,567'
>>> format(1234567.89, ',.2f')
'1,234,567.89'
>>> format(12345.6 + 8901234.12j, ',f')
'12,345.600000+8,901,234.120000j'
>>> format(Decimal('1234567.89'), ',f')
'1,234,567.89'
@end example

The supported types are @ref{254,,int}, @ref{2eb,,float}, @ref{2ec,,complex}
and @ref{29a,,decimal.Decimal}.

Discussions are underway about how to specify alternative separators
like dots, spaces, apostrophes, or underscores.  Locale-aware applications
should use the existing `n' format specifier which already has some support
for thousands separators.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 378

@item PEP 378@footnote{https://peps.python.org/pep-0378/} - Format Specifier for Thousands Separator

PEP written by Raymond Hettinger and implemented by Eric Smith and
Mark Dickinson.
@end table


@node Autres changements au langage<13>,New Improved and Deprecated Modules<2>,PEP 378 Format Specifier for Thousands Separator,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 other-language-changes}@anchor{125d}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
Directories and zip archives containing a @code{__main__.py}
file can now be executed directly by passing their name to the
interpreter. The directory/zipfile is automatically inserted as the
first entry in sys.path.  (Suggestion and initial patch by Andy Chu;
revised patch by Phillip J. Eby and Nick Coghlan; bpo-1739468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1739468}.)

@item 
The @ref{254,,int()} type gained a @code{bit_length} method that returns the
number of bits necessary to represent its argument in binary:

@example
>>> n = 37
>>> bin(37)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124
@end example

(Contributed by Fredrik Johansson, Victor Stinner, Raymond Hettinger,
and Mark Dickinson; bpo-3439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3439}.)

@item 
The fields in @ref{60a,,format()} strings can now be automatically
numbered:

@example
>>> 'Sir @{@} of @{@}'.format('Gallahad', 'Camelot')
'Sir Gallahad of Camelot'
@end example

Formerly, the string would have required numbered fields such as:
@code{'Sir @{0@} of @{1@}'}.

(Contribution par Eric Smith; bpo-5237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5237}.)

@item 
The @code{string.maketrans()} function is deprecated and is replaced by new
static methods, @ref{1253,,bytes.maketrans()} and @ref{1254,,bytearray.maketrans()}.
This change solves the confusion around which types were supported by the
@ref{d2,,string} module. Now, @ref{435,,str}, @ref{1bd,,bytes}, and
@ref{528,,bytearray} each have their own `maketrans' and `translate'
methods with intermediate translation tables of the appropriate type.

(Contribution par Georg Brandl; bpo-5675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5675}.)

@item 
The syntax of the @ref{5bc,,with} statement now allows multiple context
managers in a single statement:

@example
>>> with open('mylog.txt') as infile, open('a.out', 'w') as outfile:
...     for line in infile:
...         if '<critical>' in line:
...             outfile.write(line)
@end example

With the new syntax, the @code{contextlib.nested()} function is no longer
needed and is now deprecated.

(Contributed by Georg Brandl and Mattias Brändström;
appspot issue 53094@footnote{https://codereview.appspot.com/53094}.)

@item 
@code{round(x, n)} now returns an integer if `x' is an integer.
Previously it returned a float:

@example
>>> round(1123, -2)
1100
@end example

(Contribution par Mark Dickinson; bpo-4707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4707}.)

@item 
Python now uses David Gay's algorithm for finding the shortest floating-point
representation that doesn't change its value.  This should help
mitigate some of the confusion surrounding binary floating-point
numbers.

The significance is easily seen with a number like @code{1.1} which does not
have an exact equivalent in binary floating point.  Since there is no exact
equivalent, an expression like @code{float('1.1')} evaluates to the nearest
representable value which is @code{0x1.199999999999ap+0} in hex or
@code{1.100000000000000088817841970012523233890533447265625} in decimal. That
nearest value was and still is used in subsequent floating-point
calculations.

What is new is how the number gets displayed.  Formerly, Python used a
simple approach.  The value of @code{repr(1.1)} was computed as @code{format(1.1,
'.17g')} which evaluated to @code{'1.1000000000000001'}. The advantage of
using 17 digits was that it relied on IEEE-754 guarantees to assure that
@code{eval(repr(1.1))} would round-trip exactly to its original value.  The
disadvantage is that many people found the output to be confusing (mistaking
intrinsic limitations of binary floating-point representation as being a
problem with Python itself).

The new algorithm for @code{repr(1.1)} is smarter and returns @code{'1.1'}.
Effectively, it searches all equivalent string representations (ones that
get stored with the same underlying float value) and returns the shortest
representation.

The new algorithm tends to emit cleaner representations when possible, but
it does not change the underlying values.  So, it is still the case that
@code{1.1 + 2.2 != 3.3} even though the representations may suggest otherwise.

The new algorithm depends on certain features in the underlying floating-point
implementation.  If the required features are not found, the old
algorithm will continue to be used.  Also, the text pickle protocols
assure cross-platform portability by using the old algorithm.

(Contribution par Eric Smith et Mark Dickinson; bpo-1580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1580}.)
@end itemize

@node New Improved and Deprecated Modules<2>,Optimizations<7>,Autres changements au langage<13>,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 new-improved-and-deprecated-modules}@anchor{125e}
@subsection New, Improved, and Deprecated Modules



@itemize *

@item 
Added a @ref{107b,,collections.Counter} class to support convenient
counting of unique items in a sequence or iterable:

@example
>>> Counter(['red', 'blue', 'red', 'green', 'blue', 'blue'])
Counter(@{'blue': 3, 'red': 2, 'green': 1@})
@end example

(Contribution par Raymond Hettinger; bpo-1696199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1696199}.)

@item 
Added a new module, @ref{f8,,tkinter.ttk} for access to the Tk themed widget set.
The basic idea of ttk is to separate, to the extent possible, the code
implementing a widget's behavior from the code implementing its appearance.

(Contribution par Guilherme Polo; bpo-2983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2983}.)

@item 
The @ref{410,,gzip.GzipFile} and @ref{851,,bz2.BZ2File} classes now support
the context management protocol:

@example
>>> # Automatically close file after writing
>>> with gzip.GzipFile(filename, "wb") as f:
...     f.write(b"xxx")
@end example

(Contribution par Antoine Pitrou)

@item 
The @ref{36,,decimal} module now supports methods for creating a
decimal object from a binary @ref{2eb,,float}.  The conversion is
exact but can sometimes be surprising:

@example
>>> Decimal.from_float(1.1)
Decimal('1.100000000000000088817841970012523233890533447265625')
@end example

The long decimal result shows the actual binary fraction being
stored for `1.1'.  The fraction has many digits because `1.1' cannot
be exactly represented in binary.

(Contributed by Raymond Hettinger and Mark Dickinson.)

@item 
The @ref{80,,itertools} module grew two new functions.  The
@ref{125f,,itertools.combinations_with_replacement()} function is one of
four for generating combinatorics including permutations and Cartesian
products.  The @ref{1260,,itertools.compress()} function mimics its namesake
from APL.  Also, the existing @ref{1261,,itertools.count()} function now has
an optional `step' argument and can accept any type of counting
sequence including @ref{1e4,,fractions.Fraction} and
@ref{29a,,decimal.Decimal}:

@example
>>> [p+q for p,q in combinations_with_replacement('LOVE', 2)]
['LL', 'LO', 'LV', 'LE', 'OO', 'OV', 'OE', 'VV', 'VE', 'EE']

>>> list(compress(data=range(10), selectors=[0,0,1,1,0,1,0,1,0,0]))
[2, 3, 5, 7]

>>> c = count(start=Fraction(1,2), step=Fraction(1,6))
>>> [next(c), next(c), next(c), next(c)]
[Fraction(1, 2), Fraction(2, 3), Fraction(5, 6), Fraction(1, 1)]
@end example

(Contributed by Raymond Hettinger.)

@item 
@ref{1c5,,collections.namedtuple()} now supports a keyword argument
`rename' which lets invalid fieldnames be automatically converted to
positional names in the form _0, _1, etc.  This is useful when
the field names are being created by an external source such as a
CSV header, SQL field list, or user input:

@example
>>> query = input()
SELECT region, dept, count(*) FROM main GROUPBY region, dept

>>> cursor.execute(query)
>>> query_fields = [desc[0] for desc in cursor.description]
>>> UserQuery = namedtuple('UserQuery', query_fields, rename=True)
>>> pprint.pprint([UserQuery(*row) for row in cursor])
[UserQuery(region='South', dept='Shipping', _2=185),
 UserQuery(region='North', dept='Accounting', _2=37),
 UserQuery(region='West', dept='Sales', _2=419)]
@end example

(Contribution par Raymond Hettinger; bpo-1818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1818}.)

@item 
The @ref{2a0,,re.sub()}, @ref{2a1,,re.subn()} and @ref{29f,,re.split()} functions now
accept a flags parameter.

(Contributed by Gregory Smith.)

@item 
The @ref{86,,logging} module now implements a simple @ref{1262,,logging.NullHandler}
class for applications that are not using logging but are calling
library code that does.  Setting-up a null handler will suppress
spurious warnings such as "No handlers could be found for logger foo":

@example
>>> h = logging.NullHandler()
>>> logging.getLogger("foo").addHandler(h)
@end example

(Contribution par Vinay Sajip ; bpo-4384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4384}).

@item 
The @ref{bd,,runpy} module which supports the @code{-m} command line switch
now supports the execution of packages by looking for and executing
a @code{__main__} submodule when a package name is supplied.

(Contribution par Andi Vajda; bpo-4195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4195}.)

@item 
The @ref{a4,,pdb} module can now access and display source code loaded via
@ref{131,,zipimport} (or any other conformant 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} loader).

(Contribution par Alexander Belopolsky; bpo-4201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4201}.)

@item 
@ref{40a,,functools.partial} objects can now be pickled.
@end itemize

@quotation

(Suggested by Antoine Pitrou and Jesse Noller.  Implemented by
Jack Diederich; bpo-5228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5228}.)
@end quotation


@itemize *

@item 
Add @ref{b4,,pydoc} help topics for symbols so that @code{help('@@')}
works as expected in the interactive environment.

(Contribution par David Laban; bpo-4739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4739}.)

@item 
The @ref{105,,unittest} module now supports skipping individual tests or classes
of tests. And it supports marking a test as an expected failure, a test that
is known to be broken, but shouldn't be counted as a failure on a
TestResult:

@example
class TestGizmo(unittest.TestCase):

    @@unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_gizmo_on_windows(self):
        ...

    @@unittest.expectedFailure
    def test_gimzo_without_required_library(self):
        ...
@end example

Also, tests for exceptions have been builtout to work with context managers
using the @ref{5bc,,with} statement:

@example
def test_division_by_zero(self):
    with self.assertRaises(ZeroDivisionError):
        x / 0
@end example

In addition, several new assertion methods were added including
@ref{1263,,assertSetEqual()},
@ref{1264,,assertDictEqual()},
@code{assertDictContainsSubset()},
@ref{1265,,assertListEqual()},
@ref{1266,,assertTupleEqual()},
@ref{1267,,assertSequenceEqual()},
@ref{518,,assertRaisesRegexp()},
@ref{1268,,assertIsNone()},
and @ref{1269,,assertIsNotNone()}.

(Contribution par Benjamin Peterson et Antoine Pitrou)

@item 
The @ref{7e,,io} module has three new constants for the @ref{126a,,seek()}
method: @ref{126b,,SEEK_SET}, @ref{126c,,SEEK_CUR}, and @ref{126d,,SEEK_END}.

@item 
The @ref{68b,,sys.version_info} tuple is now a named tuple:

@example
>>> sys.version_info
sys.version_info(major=3, minor=1, micro=0, releaselevel='alpha', serial=2)
@end example

(Contribution par Ross Ligh; bpo-4285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4285}.)

@item 
The @code{nntplib} and @ref{73,,imaplib} modules now support IPv6.

(Contribution par Derek Morr; bpo-1655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1655} et bpo-1664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1664})

@item 
The @ref{a5,,pickle} module has been adapted for better interoperability with
Python 2.x when used with protocol 2 or lower.  The reorganization of the
standard library changed the formal reference for many objects.  For
example, @code{__builtin__.set} in Python 2 is called @code{builtins.set} in Python
3. This change confounded efforts to share data between different versions of
Python.  But now when protocol 2 or lower is selected, the pickler will
automatically use the old Python 2 names for both loading and dumping. This
remapping is turned-on by default but can be disabled with the `fix_imports'
option:

@example
>>> s = @{1, 2, 3@}
>>> pickle.dumps(s, protocol=0)
b'c__builtin__\nset\np0\n((lp1\nL1L\naL2L\naL3L\natp2\nRp3\n.'
>>> pickle.dumps(s, protocol=0, fix_imports=False)
b'cbuiltins\nset\np0\n((lp1\nL1L\naL2L\naL3L\natp2\nRp3\n.'
@end example

An unfortunate but unavoidable side-effect of this change is that protocol 2
pickles produced by Python 3.1 won't be readable with Python 3.0. The latest
pickle protocol, protocol 3, should be used when migrating data between
Python 3.x implementations, as it doesn't attempt to remain compatible with
Python 2.x.

(Contribution par Alexandre Vassalotti et Antoine Pitrou; bpo-6137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6137}.)

@item 
A new module, @ref{76,,importlib} was added.  It provides a complete, portable,
pure Python reference implementation of the @ref{5cc,,import} statement and its
counterpart, the @ref{8c1,,__import__()} function.  It represents a substantial
step forward in documenting and defining the actions that take place during
imports.

(Contributed by Brett Cannon.)
@end itemize

@node Optimizations<7>,IDLE<2>,New Improved and Deprecated Modules<2>,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 optimizations}@anchor{126e}
@subsection Optimizations


Major performance enhancements have been added:


@itemize *

@item 
The new I/O library (as defined in 
@geindex Python Enhancement Proposals; PEP 3116
PEP 3116@footnote{https://peps.python.org/pep-3116/}) was mostly written in
Python and quickly proved to be a problematic bottleneck in Python 3.0.
In Python 3.1, the I/O library has been entirely rewritten in C and is
2 to 20 times faster depending on the task at hand. The pure Python
version is still available for experimentation purposes through
the @code{_pyio} module.

(Contribution par Amaury Forgeot d'Arc et Antoine Pitrou)

@item 
Added a heuristic so that tuples and dicts containing only untrackable objects
are not tracked by the garbage collector. This can reduce the size of
collections and therefore the garbage collection overhead on long-running
programs, depending on their particular use of datatypes.

(Contribution par Antoine Pitrou; bpo-4688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4688}.)

@item 
Enabling a configure option named @code{--with-computed-gotos}
on compilers that support it (notably: gcc, SunPro, icc), the bytecode
evaluation loop is compiled with a new dispatch mechanism which gives
speedups of up to 20%, depending on the system, the compiler, and
the benchmark.

(Contribution par Antoine Pitrou ainsi qu’un certain nombre d’autres participants ; bpo-4753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4753}).

@item 
The decoding of UTF-8, UTF-16 and LATIN-1 is now two to four times
faster.

(Contribution par Antoine Pitrou et Amaury Forgeot d'Arc; bpo-4868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4868}.)

@item 
The @ref{81,,json} module now has a C extension to substantially improve
its performance.  In addition, the API was modified so that json works
only with @ref{435,,str}, not with @ref{1bd,,bytes}.  That change makes the
module closely match the JSON specification@footnote{https://json.org/}
which is defined in terms of Unicode.

(Contributed by Bob Ippolito and converted to Py3.1 by Antoine Pitrou
and Benjamin Peterson; bpo-4136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4136}.)

@item 
Unpickling now interns the attribute names of pickled objects.  This saves
memory and allows pickles to be smaller.

(Contribution par Jake McGuire et Antoine Pitrou; bpo-5084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5084}.)
@end itemize

@node IDLE<2>,Build and C API Changes<6>,Optimizations<7>,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 idle}@anchor{126f}
@subsection IDLE



@itemize *

@item 
IDLE's format menu now provides an option to strip trailing whitespace
from a source file.

(Contribution par Roger D. Serwy; bpo-5150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5150}.)
@end itemize

@node Build and C API Changes<6>,Portage vers Python 3 1,IDLE<2>,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 build-and-c-api-changes}@anchor{1270}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
Integers are now stored internally either in base @code{2**15} or in base
@code{2**30}, the base being determined at build time.  Previously, they
were always stored in base @code{2**15}.  Using base @code{2**30} gives
significant performance improvements on 64-bit machines, but
benchmark results on 32-bit machines have been mixed.  Therefore,
the default is to use base @code{2**30} on 64-bit machines and base @code{2**15}
on 32-bit machines; on Unix, there's a new configure option
@code{--enable-big-digits} that can be used to override this default.

Apart from the performance improvements this change should be invisible to
end users, with one exception: for testing and debugging purposes there's a
new @ref{1271,,sys.int_info} that provides information about the
internal format, giving the number of bits per digit and the size in bytes
of the C type used to store each digit:

@example
>>> import sys
>>> sys.int_info
sys.int_info(bits_per_digit=30, sizeof_digit=4)
@end example

(Contribution par Mark Dickinson; bpo-4258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4258}.)

@item 
The @ref{1272,,PyLong_AsUnsignedLongLong()} function now handles a negative
`pylong' by raising @ref{86d,,OverflowError} instead of @ref{522,,TypeError}.

(Contribution par Mark Dickinson et Lisandro Dalcrin; bpo-5175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5175})

@item 
Deprecated @code{PyNumber_Int()}.  Use @ref{a55,,PyNumber_Long()} instead.

(Contribution par Mark Dickinson; bpo-4910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4910})

@item 
Added a new @ref{1273,,PyOS_string_to_double()} function to replace the
deprecated functions @code{PyOS_ascii_strtod()} and @code{PyOS_ascii_atof()}.

(Contribution par Mark Dickinson; bpo-5914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5914})

@item 
Added @ref{1251,,PyCapsule} as a replacement for the @code{PyCObject} API.
The principal difference is that the new type has a well defined interface
for passing typing safety information and a less complicated signature
for calling a destructor.  The old type had a problematic API and is now
deprecated.

(Contribution par Larry Hastings; bpo-5630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5630})
@end itemize

@node Portage vers Python 3 1,,Build and C API Changes<6>,Nouveautés de Python 3 1
@anchor{whatsnew/3 1 porting-to-python-3-1}@anchor{1274}
@subsection Portage vers Python 3.1


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


@itemize *

@item 
The new floating-point string representations can break existing doctests.
For example:

@example
def e():
    '@w{'}'Compute the base of natural logarithms.

    >>> e()
    2.7182818284590451

    '@w{'}'
    return sum(1/math.factorial(x) for x in reversed(range(30)))

doctest.testmod()

**********************************************************************
Failed example:
    e()
Expected:
    2.7182818284590451
Got:
    2.718281828459045
**********************************************************************
@end example

@item 
The automatic name remapping in the pickle module for protocol 2 or lower can
make Python 3.1 pickles unreadable in Python 3.0.  One solution is to use
protocol 3.  Another solution is to set the `fix_imports' option to @code{False}.
See the discussion above for more details.
@end itemize

@node Nouveautés de Python 3 0,Nouveautés de Python 2 7,Nouveautés de Python 3 1,Nouveautés de Python
@anchor{whatsnew/3 0 doc}@anchor{1275}@anchor{whatsnew/3 0 what-s-new-in-python-3-0}@anchor{1276}
@section Nouveautés de Python 3.0


@c XXX Add trademark info for Apple, Microsoft.

@*Auteur: 
Guido van Rossum


@c $Id$
@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.  (Note: I didn't get to this for 3.0.
@c GvR.)
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.  (Due to time
@c constraints I haven't managed to do this for 3.0.  GvR.)
@c 
@c * It's helpful to add the bug/patch number as a comment:
@c 
@c % Patch 12345
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer.)
@c 
@c This saves the maintainer the effort of going through the SVN log
@c when researching a change.  (Again, I didn't get to this for 3.0.
@c GvR.)

This article explains the new features in Python 3.0, compared to 2.6.
Python 3.0, also known as "Python 3000" or "Py3K", is the first ever
`intentionally backwards incompatible' Python release. Python 3.0 was released on December 3, 2008.
There are more changes than in a typical release, and more that are important for all
Python users. Nevertheless, after digesting the changes, you'll find
that Python really hasn't changed all that much -- by and large, we're
mostly fixing well-known annoyances and warts, and removing a lot of
old cruft.

This article doesn't attempt to provide a complete specification of
all new features, but instead tries to give a convenient overview.
For full details, you should refer to the documentation for Python
3.0, and/or the many PEPs referenced in the text. If you want to
understand the complete implementation and design rationale for a
particular feature, PEPs usually have more details than the regular
documentation; but note that PEPs usually are not kept up-to-date once
a feature has been fully implemented.

Due to time constraints this document is not as complete as it should
have been.  As always for a new release, the @code{Misc/NEWS} file in the
source distribution contains a wealth of detailed information about
every small thing that was changed.

@c Compare with previous release in 2 - 3 sentences here.

@c add hyperlink when the documentation becomes available online.

@c ======================================================================

@c Large, PEP-level features and changes should be described here.

@c Should there be a new section here for 3k migration?

@c Or perhaps a more general section describing module changes/deprecation?

@c sets module deprecated

@c ======================================================================

@menu
* Common Stumbling Blocks:: 
* Overview Of Syntax Changes:: 
* Changes Already Present In Python 2.6: Changes Already Present In Python 2 6. 
* Library Changes:: 
* PEP 3101; A New Approach To String Formatting: PEP 3101 A New Approach To String Formatting. 
* Changes To Exceptions:: 
* Miscellaneous Other Changes:: 
* Build and C API Changes: Build and C API Changes<7>. 
* Performances:: 
* Portage vers Python 3.0: Portage vers Python 3 0. 

@end menu

@node Common Stumbling Blocks,Overview Of Syntax Changes,,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 common-stumbling-blocks}@anchor{1277}
@subsection Common Stumbling Blocks


This section lists those few changes that are most likely to trip you
up if you're used to Python 2.5.

@menu
* Print Is A Function:: 
* Views And Iterators Instead Of Lists:: 
* Ordering Comparisons:: 
* Integers:: 
* Text Vs. Data Instead Of Unicode Vs. 8-bit: Text Vs Data Instead Of Unicode Vs 8-bit. 

@end menu

@node Print Is A Function,Views And Iterators Instead Of Lists,,Common Stumbling Blocks
@anchor{whatsnew/3 0 print-is-a-function}@anchor{1278}
@subsubsection Print Is A Function


The @code{print} statement has been replaced with a @ref{f60,,print()}
function, with keyword arguments to replace most of the special syntax
of the old @code{print} statement (
@geindex Python Enhancement Proposals; PEP 3105
PEP 3105@footnote{https://peps.python.org/pep-3105/}).  Examples:

@example
Old: print "The answer is", 2*2
New: print("The answer is", 2*2)

Old: print x,           # Trailing comma suppresses newline
New: print(x, end=" ")  # Appends a space instead of a newline

Old: print              # Prints a newline
New: print()            # You must call the function!

Old: print >>sys.stderr, "fatal error"
New: print("fatal error", file=sys.stderr)

Old: print (x, y)       # prints repr((x, y))
New: print((x, y))      # Not the same as print(x, y)!
@end example

You can also customize the separator between items, e.g.:

@example
print("There are <", 2**32, "> possibilities!", sep="")
@end example

which produces:

@example
There are <4294967296> possibilities!
@end example

Note:


@itemize *

@item 
The @ref{f60,,print()} function doesn't support the "softspace" feature of
the old @code{print} statement.  For example, in Python 2.x,
@code{print "A\n", "B"} would write @code{"A\nB\n"}; but in Python 3.0,
@code{print("A\n", "B")} writes @code{"A\n B\n"}.

@item 
Initially, you'll be finding yourself typing the old @code{print x}
a lot in interactive mode.  Time to retrain your fingers to type
@code{print(x)} instead!

@item 
When using the @code{2to3} source-to-source conversion tool, all
@code{print} statements are automatically converted to
@ref{f60,,print()} function calls, so this is mostly a non-issue for
larger projects.
@end itemize

@node Views And Iterators Instead Of Lists,Ordering Comparisons,Print Is A Function,Common Stumbling Blocks
@anchor{whatsnew/3 0 views-and-iterators-instead-of-lists}@anchor{1279}
@subsubsection Views And Iterators Instead Of Lists


Some well-known APIs no longer return lists:


@itemize *

@item 
@ref{253,,dict} methods @ref{7b7,,dict.keys()}, @ref{7b9,,dict.items()} and
@ref{7b8,,dict.values()} return "views" instead of lists.  For example,
this no longer works: @code{k = d.keys(); k.sort()}.  Use @code{k =
sorted(d)} instead (this works in Python 2.5 too and is just
as efficient).

@item 
Also, the @code{dict.iterkeys()}, @code{dict.iteritems()} and
@code{dict.itervalues()} methods are no longer supported.

@item 
@ref{84e,,map()} and @ref{84f,,filter()} return iterators.  If you really need
a list and the input sequences are all of equal length, a quick
fix is to wrap @ref{84e,,map()} in @ref{5fc,,list()}, e.g. @code{list(map(...))},
but a better fix is
often to use a list comprehension (especially when the original code
uses @ref{127a,,lambda}), or rewriting the code so it doesn't need a
list at all.  Particularly tricky is @ref{84e,,map()} invoked for the
side effects of the function; the correct transformation is to use a
regular @ref{2e6,,for} loop (since creating a list would just be
wasteful).

If the input sequences are not of equal length, @ref{84e,,map()} will
stop at the termination of the shortest of the sequences. For full
compatibility with @ref{84e,,map()} from Python 2.x, also wrap the sequences in
@ref{127b,,itertools.zip_longest()}, e.g. @code{map(func, *sequences)} becomes
@code{list(map(func, itertools.zip_longest(*sequences)))}.

@item 
@ref{930,,range()} now behaves like @code{xrange()} used to behave, except
it works with values of arbitrary size.  The latter no longer
exists.

@item 
@ref{7ba,,zip()} renvoie maintenant un itérateur.
@end itemize

@node Ordering Comparisons,Integers,Views And Iterators Instead Of Lists,Common Stumbling Blocks
@anchor{whatsnew/3 0 ordering-comparisons}@anchor{127c}
@subsubsection Ordering Comparisons


Python 3.0 has simplified the rules for ordering comparisons:


@itemize *

@item 
The ordering comparison operators (@code{<}, @code{<=}, @code{>=}, @code{>})
raise a TypeError exception when the operands don't have a
meaningful natural ordering.  Thus, expressions like @code{1 < '@w{'}}, @code{0
> None} or @code{len <= len} are no longer valid, and e.g. @code{None <
None} raises @ref{522,,TypeError} instead of returning
@code{False}.  A corollary is that sorting a heterogeneous list
no longer makes sense -- all the elements must be comparable to each
other.  Note that this does not apply to the @code{==} and @code{!=}
operators: objects of different incomparable types always compare
unequal to each other.

@item 
@ref{bbc,,sorted()} and @ref{bbd,,list.sort()} no longer accept the
`cmp' argument providing a comparison function.  Use the `key'
argument instead. N.B. the `key' and `reverse' arguments are now
"keyword-only".

@item 
The @code{cmp()} function should be treated as gone, and the @code{__cmp__()}
special method is no longer supported.  Use @ref{127d,,__lt__()} for sorting,
@ref{ae8,,__eq__()} with @ref{ae9,,__hash__()}, and other rich comparisons as needed.
(If you really need the @code{cmp()} functionality, you could use the
expression @code{(a > b) - (a < b)} as the equivalent for @code{cmp(a, b)}.)
@end itemize

@node Integers,Text Vs Data Instead Of Unicode Vs 8-bit,Ordering Comparisons,Common Stumbling Blocks
@anchor{whatsnew/3 0 integers}@anchor{127e}
@subsubsection Integers



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}: Essentially, @code{long} renamed to @ref{254,,int}.
That is, there is only one built-in integral type, named
@ref{254,,int}; but it behaves mostly like the old @code{long} type.

@item 
@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/}: An expression like @code{1/2} returns a float.  Use
@code{1//2} to get the truncating behavior.  (The latter syntax has
existed for years, at least since Python 2.2.)

@item 
The @code{sys.maxint} constant was removed, since there is no
longer a limit to the value of integers.  However, @ref{11a2,,sys.maxsize}
can be used as an integer larger than any practical list or string
index.  It conforms to the implementation's "natural" integer size
and is typically the same as @code{sys.maxint} in previous releases
on the same platform (assuming the same build options).

@item 
The @ref{7e7,,repr()} of a long integer doesn't include the trailing @code{L}
anymore, so code that unconditionally strips that character will
chop off the last digit instead.  (Use @ref{435,,str()} instead.)

@item 
Octal literals are no longer of the form @code{0720}; use @code{0o720}
instead.
@end itemize

@node Text Vs Data Instead Of Unicode Vs 8-bit,,Integers,Common Stumbling Blocks
@anchor{whatsnew/3 0 text-vs-data-instead-of-unicode-vs-8-bit}@anchor{127f}
@subsubsection Text Vs. Data Instead Of Unicode Vs. 8-bit


Everything you thought you knew about binary data and Unicode has
changed.


@itemize *

@item 
Python 3.0 uses the concepts of `text' and (binary) `data' instead
of Unicode strings and 8-bit strings.  All text is Unicode; however
`encoded' Unicode is represented as binary data.  The type used to
hold text is @ref{435,,str}, the type used to hold data is
@ref{1bd,,bytes}.  The biggest difference with the 2.x situation is
that any attempt to mix text and data in Python 3.0 raises
@ref{522,,TypeError}, whereas if you were to mix Unicode and 8-bit
strings in Python 2.x, it would work if the 8-bit string happened to
contain only 7-bit (ASCII) bytes, but you would get
@ref{a01,,UnicodeDecodeError} if it contained non-ASCII values.  This
value-specific behavior has caused numerous sad faces over the
years.

@item 
As a consequence of this change in philosophy, pretty much all code
that uses Unicode, encodings or binary data most likely has to
change.  The change is for the better, as in the 2.x world there
were numerous bugs having to do with mixing encoded and unencoded
text.  To be prepared in Python 2.x, start using @code{unicode}
for all unencoded text, and @ref{435,,str} for binary or encoded data
only.  Then the @code{2to3} tool will do most of the work for you.

@item 
You can no longer use @code{u"..."} literals for Unicode text.
However, you must use @code{b"..."} literals for binary data.

@item 
As the @ref{435,,str} and @ref{1bd,,bytes} types cannot be mixed, you
must always explicitly convert between them.  Use @ref{8c2,,str.encode()}
to go from @ref{435,,str} to @ref{1bd,,bytes}, and @ref{8c3,,bytes.decode()}
to go from @ref{1bd,,bytes} to @ref{435,,str}.  You can also use
@code{bytes(s, encoding=...)} and @code{str(b, encoding=...)},
respectively.

@item 
Like @ref{435,,str}, the @ref{1bd,,bytes} type is immutable.  There is a
separate `mutable' type to hold buffered binary data,
@ref{528,,bytearray}.  Nearly all APIs that accept @ref{1bd,,bytes} also
accept @ref{528,,bytearray}.  The mutable API is based on
@ref{19f,,collections.MutableSequence}.

@item 
All backslashes in raw string literals are interpreted literally.
This means that @code{'\U'} and @code{'\u'} escapes in raw strings are not
treated specially.  For example, @code{r'\u20ac'} is a string of 6
characters in Python 3.0, whereas in 2.6, @code{ur'\u20ac'} was the
single "euro" character.  (Of course, this change only affects raw
string literals; the euro character is @code{'\u20ac'} in Python 3.0.)

@item 
The built-in @code{basestring} abstract type was removed.  Use
@ref{435,,str} instead.  The @ref{435,,str} and @ref{1bd,,bytes} types
don't have functionality enough in common to warrant a shared base
class.  The @code{2to3} tool (see below) replaces every occurrence of
@code{basestring} with @ref{435,,str}.

@item 
Files opened as text files (still the default mode for @ref{505,,open()})
always use an encoding to map between strings (in memory) and bytes
(on disk).  Binary files (opened with a @code{b} in the mode argument)
always use bytes in memory.  This means that if a file is opened
using an incorrect mode or encoding, I/O will likely fail loudly,
instead of silently producing incorrect data.  It also means that
even Unix users will have to specify the correct mode (text or
binary) when opening a file.  There is a platform-dependent default
encoding, which on Unixy platforms can be set with the @code{LANG}
environment variable (and sometimes also with some other
platform-specific locale-related environment variables).  In many
cases, but not all, the system default is UTF-8; you should never
count on this default.  Any application reading or writing more than
pure ASCII text should probably have a way to override the encoding.
There is no longer any need for using the encoding-aware streams
in the @ref{1b,,codecs} module.

@item 
The initial values of @ref{527,,sys.stdin}, @ref{ac4,,sys.stdout} and
@ref{926,,sys.stderr} are now unicode-only text files (i.e., they are
instances of @ref{680,,io.TextIOBase}).  To read and write bytes data
with these streams, you need to use their @ref{1280,,io.TextIOBase.buffer}
attribute.

@item 
Filenames are passed to and returned from APIs as (Unicode) strings.
This can present platform-specific problems because on some
platforms filenames are arbitrary byte strings.  (On the other hand,
on Windows filenames are natively stored as Unicode.)  As a
work-around, most APIs (e.g. @ref{505,,open()} and many functions in the
@ref{a0,,os} module) that take filenames accept @ref{1bd,,bytes} objects
as well as strings, and a few APIs have a way to ask for a
@ref{1bd,,bytes} return value.  Thus, @ref{10da,,os.listdir()} returns a
list of @ref{1bd,,bytes} instances if the argument is a @ref{1bd,,bytes}
instance, and @ref{a7f,,os.getcwdb()} returns the current working
directory as a @ref{1bd,,bytes} instance.  Note that when
@ref{10da,,os.listdir()} returns a list of strings, filenames that
cannot be decoded properly are omitted rather than raising
@ref{1281,,UnicodeError}.

@item 
Some system APIs like @ref{1197,,os.environ} and @ref{1243,,sys.argv} can
also present problems when the bytes made available by the system is
not interpretable using the default encoding.  Setting the @code{LANG}
variable and rerunning the program is probably the best approach.

@item 
@geindex Python Enhancement Proposals; PEP 3138
PEP 3138@footnote{https://peps.python.org/pep-3138/}: The @ref{7e7,,repr()} of a string no longer escapes
non-ASCII characters.  It still escapes control characters and code
points with non-printable status in the Unicode standard, however.

@item 
@geindex Python Enhancement Proposals; PEP 3120
PEP 3120@footnote{https://peps.python.org/pep-3120/}: The default source encoding is now UTF-8.

@item 
@geindex Python Enhancement Proposals; PEP 3131
PEP 3131@footnote{https://peps.python.org/pep-3131/}: Non-ASCII letters are now allowed in identifiers.
(However, the standard library remains ASCII-only with the exception
of contributor names in comments.)

@item 
The @code{StringIO} and @code{cStringIO} modules are gone.  Instead,
import the @ref{7e,,io} module and use @ref{f12,,io.StringIO} or
@ref{e8d,,io.BytesIO} for text and data respectively.

@item 
See also the @ref{1282,,Guide Unicode}, which was updated for Python 3.0.
@end itemize

@node Overview Of Syntax Changes,Changes Already Present In Python 2 6,Common Stumbling Blocks,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 overview-of-syntax-changes}@anchor{1283}
@subsection Overview Of Syntax Changes


This section gives a brief overview of every `syntactic' change in
Python 3.0.

@menu
* New Syntax:: 
* Changed Syntax:: 
* Removed Syntax:: 

@end menu

@node New Syntax,Changed Syntax,,Overview Of Syntax Changes
@anchor{whatsnew/3 0 new-syntax}@anchor{1284}
@subsubsection New Syntax



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/}: Function argument and return value annotations.  This
provides a standardized way of annotating a function's parameters
and return value.  There are no semantics attached to such
annotations except that they can be introspected at runtime using
the @code{__annotations__} attribute.  The intent is to
encourage experimentation through metaclasses, decorators or frameworks.

@item 
@geindex Python Enhancement Proposals; PEP 3102
PEP 3102@footnote{https://peps.python.org/pep-3102/}: Keyword-only arguments.  Named parameters occurring
after @code{*args} in the parameter list `must' be specified using
keyword syntax in the call.  You can also use a bare @code{*} in the
parameter list to indicate that you don't accept a variable-length
argument list, but you do have keyword-only arguments.

@item 
Keyword arguments are allowed after the list of base classes in a
class definition.  This is used by the new convention for specifying
a metaclass (see next section), but can be used for other purposes
as well, as long as the metaclass supports it.

@item 
@geindex Python Enhancement Proposals; PEP 3104
PEP 3104@footnote{https://peps.python.org/pep-3104/}: @ref{1285,,nonlocal} statement.  Using @code{nonlocal x}
you can now assign directly to a variable in an outer (but
non-global) scope.  @code{nonlocal} is a new reserved word.

@item 
@geindex Python Enhancement Proposals; PEP 3132
PEP 3132@footnote{https://peps.python.org/pep-3132/}: Extended Iterable Unpacking.  You can now write things
like @code{a, b, *rest = some_sequence}.  And even @code{*rest, a =
stuff}.  The @code{rest} object is always a (possibly empty) list; the
right-hand side may be any iterable.  Example:

@example
(a, *rest, b) = range(5)
@end example

This sets `a' to @code{0}, `b' to @code{4}, and `rest' to @code{[1, 2, 3]}.

@item 
Dictionary comprehensions: @code{@{k: v for k, v in stuff@}} means the
same thing as @code{dict(stuff)} but is more flexible.  (This is
@geindex Python Enhancement Proposals; PEP 274
PEP 274@footnote{https://peps.python.org/pep-0274/} vindicated. :-)

@item 
Set literals, e.g. @code{@{1, 2@}}.  Note that @code{@{@}} is an empty
dictionary; use @code{set()} for an empty set.  Set comprehensions are
also supported; e.g., @code{@{x for x in stuff@}} means the same thing as
@code{set(stuff)} but is more flexible.

@item 
New octal literals, e.g. @code{0o720} (already in 2.6).  The old octal
literals (@code{0720}) are gone.

@item 
New binary literals, e.g. @code{0b1010} (already in 2.6), and
there is a new corresponding built-in function, @ref{1286,,bin()}.

@item 
Bytes literals are introduced with a leading @code{b} or @code{B}, and
there is a new corresponding built-in function, @ref{1bd,,bytes()}.
@end itemize

@node Changed Syntax,Removed Syntax,New Syntax,Overview Of Syntax Changes
@anchor{whatsnew/3 0 changed-syntax}@anchor{1287}
@subsubsection Changed Syntax



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3109
PEP 3109@footnote{https://peps.python.org/pep-3109/} and 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/}: new @ref{5d7,,raise} statement syntax:
@code{raise [@var{expr} [from @var{expr}]]}.  See below.

@item 
@code{as} and @ref{5bc,,with} are now reserved words.  (Since
2.6, actually.)

@item 
@code{True}, @code{False}, and @code{None} are reserved words.  (2.6 partially enforced
the restrictions on @code{None} already.)

@item 
Change from @ref{189,,except} `exc', `var' to
@code{except} `exc' @code{as} `var'.  See 
@geindex Python Enhancement Proposals; PEP 3110
PEP 3110@footnote{https://peps.python.org/pep-3110/}.

@item 
@geindex Python Enhancement Proposals; PEP 3115
PEP 3115@footnote{https://peps.python.org/pep-3115/}: New Metaclass Syntax.  Instead of:

@example
class C:
    __metaclass__ = M
    ...
@end example

you must now use:

@example
class C(metaclass=M):
    ...
@end example

The module-global @code{__metaclass__} variable is no longer
supported.  (It was a crutch to make it easier to default to
new-style classes without deriving every class from
@ref{a7a,,object}.)

@item 
List comprehensions no longer support the syntactic form
@code{[... for @var{var} in @var{item1}, @var{item2}, ...]}.  Use
@code{[... for @var{var} in (@var{item1}, @var{item2}, ...)]} instead.
Also note that list comprehensions have different semantics: they
are closer to syntactic sugar for a generator expression inside a
@ref{5fc,,list()} constructor, and in particular the loop control
variables are no longer leaked into the surrounding scope.

@item 
The `ellipsis' (@code{...}) can be used as an atomic expression
anywhere.  (Previously it was only allowed in slices.)  Also, it
`must' now be spelled as @code{...}.  (Previously it could also be
spelled as @code{. . .}, by a mere accident of the grammar.)
@end itemize

@node Removed Syntax,,Changed Syntax,Overview Of Syntax Changes
@anchor{whatsnew/3 0 removed-syntax}@anchor{1288}
@subsubsection Removed Syntax



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3113
PEP 3113@footnote{https://peps.python.org/pep-3113/}: Tuple parameter unpacking removed.  You can no longer
write @code{def foo(a, (b, c)): ...}.
Use @code{def foo(a, b_c): b, c = b_c} instead.

@item 
Removed backticks (use @ref{7e7,,repr()} instead).

@item 
Removed @code{<>} (use @code{!=} instead).

@item 
Removed keyword: @ref{17d,,exec()} is no longer a keyword; it remains as
a function.  (Fortunately the function syntax was also accepted in
2.x.)  Also note that @ref{17d,,exec()} no longer takes a stream argument;
instead of @code{exec(f)} you can use @code{exec(f.read())}.

@item 
Integer literals no longer support a trailing @code{l} or @code{L}.

@item 
String literals no longer support a leading @code{u} or @code{U}.

@item 
The @ref{1289,,from} `module' @ref{5cc,,import} @code{*} syntax is only
allowed at the module level, no longer inside functions.

@item 
The only acceptable syntax for relative imports is @code{from .[@var{module}]
import @var{name}}.  All @ref{5cc,,import} forms not starting with @code{.} are
interpreted as absolute imports.  (
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/})

@item 
Classic classes are gone.
@end itemize

@node Changes Already Present In Python 2 6,Library Changes,Overview Of Syntax Changes,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 changes-already-present-in-python-2-6}@anchor{128a}
@subsection Changes Already Present In Python 2.6


Since many users presumably make the jump straight from Python 2.5 to
Python 3.0, this section reminds the reader of new features that were
originally designed for Python 3.0 but that were back-ported to Python
2.6.  The corresponding sections in @ref{128b,,Nouveautés de Python 2.6} should be
consulted for longer descriptions.


@itemize *

@item 
@ref{128c,,PEP 343; The 'with' statement}.  The @ref{5bc,,with} statement is now a standard
feature and no longer needs to be imported from the @ref{0,,__future__}.
Also check out @ref{128d,,Écrire des gestionnaires de contexte} and
@ref{128e,,Le module contextlib}.

@item 
@ref{128f,,PEP 366; Explicit Relative Imports From a Main Module}.  This enhances the usefulness of the @ref{5cb,,-m}
option when the referenced module lives in a package.

@item 
@ref{1290,,PEP 370; Per-user site-packages Directory}.

@item 
@ref{1291,,PEP 371; The multiprocessing Package}.

@item 
@ref{1292,,PEP 3101; Advanced String Formatting}.  Note: the 2.6 description mentions the
@ref{60a,,format()} method for both 8-bit and Unicode strings.  In 3.0,
only the @ref{435,,str} type (text strings with Unicode support)
supports this method; the @ref{1bd,,bytes} type does not.  The plan is
to eventually make this the only API for string formatting, and to
start deprecating the @code{%} operator in Python 3.1.

@item 
@ref{1293,,PEP 3105; print As a Function}.  This is now a standard feature and no longer needs
to be imported from @ref{0,,__future__}.  More details were given above.

@item 
@ref{1294,,PEP 3110; Exception-Handling Changes}.  The @ref{189,,except} `exc' @code{as} `var'
syntax is now standard and @code{except} `exc', `var' is no
longer supported.  (Of course, the @code{as} `var' part is still
optional.)

@item 
@ref{1295,,PEP 3112; Byte Literals}.  The @code{b"..."} string literal notation (and its
variants like @code{b'...'}, @code{b"""..."""}, and @code{br"..."}) now
produces a literal of type @ref{1bd,,bytes}.

@item 
@ref{1296,,PEP 3116; New I/O Library}.  The @ref{7e,,io} module is now the standard way of
doing file I/O.  The built-in @ref{505,,open()} function is now an
alias for @ref{506,,io.open()} and has additional keyword arguments
`encoding', `errors', `newline' and `closefd'.  Also note that an
invalid `mode' argument now raises @ref{1ff,,ValueError}, not
@ref{103b,,IOError}.  The binary file object underlying a text file
object can be accessed as @code{f.buffer} (but beware that the
text object maintains a buffer of itself in order to speed up
the encoding and decoding operations).

@item 
@ref{1297,,PEP 3118; Revised Buffer Protocol}.  The old builtin @code{buffer()} is now really gone;
the new builtin @ref{452,,memoryview()} provides (mostly) similar
functionality.

@item 
@ref{1298,,PEP 3119; Abstract Base Classes}.  The @ref{4,,abc} module and the ABCs defined in the
@ref{1d,,collections} module plays a somewhat more prominent role in
the language now, and built-in collection types like @ref{253,,dict}
and @ref{5fc,,list} conform to the @ref{1090,,collections.MutableMapping}
and @ref{19f,,collections.MutableSequence} ABCs, respectively.

@item 
@ref{1299,,PEP 3127; Integer Literal Support and Syntax}.  As mentioned above, the new octal literal
notation is the only one supported, and binary literals have been
added.

@item 
@ref{129a,,PEP 3129; Class Decorators}.

@item 
@ref{129b,,PEP 3141; A Type Hierarchy for Numbers}.  The @ref{9d,,numbers} module is another new use of
ABCs, defining Python's "numeric tower".  Also note the new
@ref{5c,,fractions} module which implements @ref{129c,,numbers.Rational}.
@end itemize

@node Library Changes,PEP 3101 A New Approach To String Formatting,Changes Already Present In Python 2 6,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 library-changes}@anchor{129d}
@subsection Library Changes


Due to time constraints, this document does not exhaustively cover the
very extensive changes to the standard library.  
@geindex Python Enhancement Proposals; PEP 3108
PEP 3108@footnote{https://peps.python.org/pep-3108/} is the
reference for the major changes to the library.  Here's a capsule
review:


@itemize *

@item 
Many old modules were removed.  Some, like @code{gopherlib} (no
longer used) and @code{md5} (replaced by @ref{67,,hashlib}), were
already deprecated by 
@geindex Python Enhancement Proposals; PEP 4
PEP 4@footnote{https://peps.python.org/pep-0004/}.  Others were removed as a result
of the removal of support for various platforms such as Irix, BeOS
and Mac OS 9 (see 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}).  Some modules were also selected for
removal in Python 3.0 due to lack of use or because a better
replacement exists.  See 
@geindex Python Enhancement Proposals; PEP 3108
PEP 3108@footnote{https://peps.python.org/pep-3108/} for an exhaustive list.

@item 
The @code{bsddb3} package was removed because its presence in the
core standard library has proved over time to be a particular burden
for the core developers due to testing instability and Berkeley DB's
release schedule.  However, the package is alive and well,
externally maintained at @indicateurl{https://www.jcea.es/programacion/pybsddb.htm}.

@item 
Some modules were renamed because their old name disobeyed
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}, or for various other reasons.  Here's the list:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Old Name

@tab

New Name

@item

_winreg

@tab

winreg

@item

ConfigParser

@tab

configparser

@item

copy_reg

@tab

copyreg

@item

File d'attente (`queue')

@tab

queue

@item

SocketServer

@tab

socketserver

@item

markupbase

@tab

_markupbase

@item

repr

@tab

reprlib

@item

test.test_support

@tab

test.support

@end multitable


@item 
A common pattern in Python 2.x is to have one version of a module
implemented in pure Python, with an optional accelerated version
implemented as a C extension; for example, @ref{a5,,pickle} and
@code{cPickle}.  This places the burden of importing the accelerated
version and falling back on the pure Python version on each user of
these modules.  In Python 3.0, the accelerated versions are
considered implementation details of the pure Python versions.
Users should always import the standard version, which attempts to
import the accelerated version and falls back to the pure Python
version.  The @ref{a5,,pickle} / @code{cPickle} pair received this
treatment.  The @ref{ae,,profile} module is on the list for 3.1.  The
@code{StringIO} module has been turned into a class in the @ref{7e,,io}
module.

@item 
Some related modules have been grouped into packages, and usually
the submodule names have been simplified.  The resulting new
packages are:


@itemize *

@item 
@ref{31,,dbm} (@code{anydbm}, @code{dbhash}, @code{dbm},
@code{dumbdbm}, @code{gdbm}, @code{whichdb}).

@item 
@ref{6a,,html} (@code{HTMLParser}, @code{htmlentitydefs}).

@item 
@ref{6d,,http} (@code{httplib}, @code{BaseHTTPServer},
@code{CGIHTTPServer}, @code{SimpleHTTPServer}, @code{Cookie},
@code{cookielib}).

@item 
@ref{ef,,tkinter} (all @code{Tkinter}-related modules except
@ref{100,,turtle}).  The target audience of @ref{100,,turtle} doesn't
really care about @ref{ef,,tkinter}.  Also note that as of Python
2.6, the functionality of @ref{100,,turtle} has been greatly enhanced.

@item 
@ref{107,,urllib} (@code{urllib}, @code{urllib2}, @code{urlparse},
@code{robotparse}).

@item 
@ref{12c,,xmlrpc} (@code{xmlrpclib}, @code{DocXMLRPCServer},
@code{SimpleXMLRPCServer}).
@end itemize
@end itemize

Some other changes to standard library modules, not covered by
@geindex Python Enhancement Proposals; PEP 3108
PEP 3108@footnote{https://peps.python.org/pep-3108/}:


@itemize *

@item 
Killed @code{sets}.  Use the built-in @ref{5c3,,set()} class.

@item 
Cleanup of the @ref{d8,,sys} module: removed @code{sys.exitfunc()},
@code{sys.exc_clear()}, @code{sys.exc_type}, @code{sys.exc_value},
@code{sys.exc_traceback}.  (Note that @ref{4a8,,sys.last_type}
etc. remain.)

@item 
Cleanup of the @ref{19e,,array.array} type: the @code{read()} and
@code{write()} methods are gone; use @ref{129e,,fromfile()} and
@ref{129f,,tofile()} instead.  Also, the @code{'c'} typecode for array is
gone -- use either @code{'b'} for bytes or @code{'u'} for Unicode
characters.

@item 
Cleanup of the @ref{9e,,operator} module: removed
@code{sequenceIncludes()} and @code{isCallable()}.

@item 
Cleanup of the @code{thread} module: @code{acquire_lock()} and
@code{release_lock()} are gone; use @ref{683,,acquire()} and
@ref{12a0,,release()} instead.

@item 
Cleanup of the @ref{b7,,random} module: removed the @code{jumpahead()} API.

@item 
The @code{new} module is gone.

@item 
The functions @code{os.tmpnam()}, @code{os.tempnam()} and
@code{os.tmpfile()} have been removed in favor of the @ref{df,,tempfile}
module.

@item 
The @ref{fa,,tokenize} module has been changed to work with bytes.  The
main entry point is now @ref{4c3,,tokenize.tokenize()}, instead of
generate_tokens.

@item 
@code{string.letters} and its friends (@code{string.lowercase} and
@code{string.uppercase}) are gone.  Use
@ref{12a1,,string.ascii_letters} etc. instead.  (The reason for the
removal is that @code{string.letters} and friends had
locale-specific behavior, which is a bad idea for such
attractively named global "constants".)

@item 
Renamed module @code{__builtin__} to @ref{12,,builtins} (removing the
underscores, adding an 's').  The @code{__builtins__} variable
found in most global namespaces is unchanged.  To modify a builtin,
you should use @ref{12,,builtins}, not @code{__builtins__}!
@end itemize

@node PEP 3101 A New Approach To String Formatting,Changes To Exceptions,Library Changes,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 pep-3101-a-new-approach-to-string-formatting}@anchor{12a2}
@subsection 
@geindex Python Enhancement Proposals; PEP 3101
`PEP 3101': A New Approach To String Formatting



@itemize *

@item 
A new system for  built-in string formatting operations replaces the
@code{%} string  formatting operator.   (However, the @code{%}  operator is
still supported;  it will  be deprecated in  Python 3.1  and removed
from the language at some later time.)  Read 
@geindex Python Enhancement Proposals; PEP 3101
PEP 3101@footnote{https://peps.python.org/pep-3101/} for the full
scoop.
@end itemize

@node Changes To Exceptions,Miscellaneous Other Changes,PEP 3101 A New Approach To String Formatting,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 changes-to-exceptions}@anchor{12a3}
@subsection Changes To Exceptions


The APIs for raising and catching exception have been cleaned up and
new powerful features added:


@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 352
PEP 352@footnote{https://peps.python.org/pep-0352/}: All exceptions must be derived (directly or indirectly)
from @ref{5a5,,BaseException}.  This is the root of the exception
hierarchy.  This is not new as a recommendation, but the
`requirement' to inherit from @ref{5a5,,BaseException} is new.  (Python
2.6 still allowed classic classes to be raised, and placed no
restriction on what you can catch.)  As a consequence, string
exceptions are finally truly and utterly dead.

@item 
Almost all exceptions should actually derive from @ref{9c7,,Exception};
@ref{5a5,,BaseException} should only be used as a base class for
exceptions that should only be handled at the top level, such as
@ref{d2e,,SystemExit} or @ref{9bf,,KeyboardInterrupt}.  The recommended
idiom for handling all exceptions except for this latter category is
to use @ref{189,,except} @ref{9c7,,Exception}.

@item 
@code{StandardError} was removed.

@item 
Exceptions no longer behave as sequences.  Use the @ref{558,,args}
attribute instead.

@item 
@geindex Python Enhancement Proposals; PEP 3109
PEP 3109@footnote{https://peps.python.org/pep-3109/}: Raising exceptions.  You must now use @code{raise
@var{Exception}(@var{args})} instead of @code{raise @var{Exception}, @var{args}}.
Additionally, you can no longer explicitly specify a traceback;
instead, if you `have' to do this, you can assign directly to the
@ref{12a4,,__traceback__} attribute (see below).

@item 
@geindex Python Enhancement Proposals; PEP 3110
PEP 3110@footnote{https://peps.python.org/pep-3110/}: Catching exceptions.  You must now use
@code{except @var{SomeException} as @var{variable}} instead
of @code{except @var{SomeException}, @var{variable}}.  Moreover, the
`variable' is explicitly deleted when the @ref{189,,except} block
is left.

@item 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/}: Exception chaining.  There are two cases: implicit
chaining and explicit chaining.  Implicit chaining happens when an
exception is raised in an @ref{189,,except} or @ref{9b8,,finally}
handler block.  This usually happens due to a bug in the handler
block; we call this a `secondary' exception.  In this case, the
original exception (that was being handled) is saved as the
@ref{12a5,,__context__} attribute of the secondary exception.
Explicit chaining is invoked with this syntax:

@example
raise SecondaryException() from primary_exception
@end example

(where `primary_exception' is any expression that produces an
exception object, probably an exception that was previously caught).
In this case, the primary exception is stored on the
@ref{12a6,,__cause__} attribute of the secondary exception.  The
traceback printed when an unhandled exception occurs walks the chain
of @code{__cause__} and @ref{12a5,,__context__} attributes and
prints a
separate traceback for each component of the chain, with the primary
exception at the top.  (Java users may recognize this behavior.)

@item 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/}: Exception objects now store their traceback as the
@ref{12a4,,__traceback__} attribute.  This means that an exception
object now contains all the information pertaining to an exception,
and there are fewer reasons to use @ref{675,,sys.exc_info()} (though the
latter is not removed).

@item 
A few exception messages are improved when Windows fails to load an
extension module.  For example, @code{error code 193} is now @code{%1 is
not a valid Win32 application}.  Strings now deal with non-English
locales.
@end itemize

@node Miscellaneous Other Changes,Build and C API Changes<7>,Changes To Exceptions,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 miscellaneous-other-changes}@anchor{12a7}
@subsection Miscellaneous Other Changes


@menu
* Operators And Special Methods:: 
* Builtins:: 

@end menu

@node Operators And Special Methods,Builtins,,Miscellaneous Other Changes
@anchor{whatsnew/3 0 operators-and-special-methods}@anchor{12a8}
@subsubsection Operators And Special Methods



@itemize *

@item 
@code{!=} now returns the opposite of @code{==}, unless @code{==} returns
@ref{7bc,,NotImplemented}.

@item 
The concept of "unbound methods" has been removed from the language.
When referencing a method as a class attribute, you now get a plain
function object.

@item 
@code{__getslice__()}, @code{__setslice__()} and @code{__delslice__()}
were killed.  The syntax @code{a[i:j]} now translates to
@code{a.__getitem__(slice(i, j))} (or @ref{12a9,,__setitem__()} or
@ref{12aa,,__delitem__()}, when used as an assignment or deletion target,
respectively).

@item 
@geindex Python Enhancement Proposals; PEP 3114
PEP 3114@footnote{https://peps.python.org/pep-3114/}: the standard @ref{7c2,,next()} method has been renamed to
@ref{12ab,,__next__()}.

@item 
The @code{__oct__()} and @code{__hex__()} special methods are removed
-- @ref{12ac,,oct()} and @ref{12ad,,hex()} use @ref{707,,__index__()} now to convert
the argument to an integer.

@item 
Removed support for @code{__members__} and @code{__methods__}.

@item 
The function attributes named @code{func_X} have been renamed to
use the @code{__X__} form, freeing up these names in the function
attribute namespace for user-defined attributes.  To wit,
@code{func_closure}, @code{func_code}, @code{func_defaults},
@code{func_dict}, @code{func_doc}, @code{func_globals},
@code{func_name} were renamed to @ref{12ae,,__closure__},
@ref{297,,__code__}, @ref{12af,,__defaults__},
@ref{12b0,,__dict__}, @ref{11b6,,__doc__},
@ref{12b1,,__globals__}, @ref{12b2,,__name__},
respectively.

@item 
@code{__nonzero__()} is now @ref{12b3,,__bool__()}.
@end itemize

@node Builtins,,Operators And Special Methods,Miscellaneous Other Changes
@anchor{whatsnew/3 0 builtins}@anchor{12b4}
@subsubsection Builtins



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 3135
PEP 3135@footnote{https://peps.python.org/pep-3135/}: New @ref{4c5,,super()}.  You can now invoke @ref{4c5,,super()}
without arguments and (assuming this is in a regular instance method
defined inside a @ref{12b5,,class} statement) the right class and
instance will automatically be chosen.  With arguments, the behavior
of @ref{4c5,,super()} is unchanged.

@item 
@geindex Python Enhancement Proposals; PEP 3111
PEP 3111@footnote{https://peps.python.org/pep-3111/}: @code{raw_input()} was renamed to @ref{12b6,,input()}.  That
is, the new @ref{12b6,,input()} function reads a line from
@ref{527,,sys.stdin} and returns it with the trailing newline stripped.
It raises @ref{12b7,,EOFError} if the input is terminated prematurely.
To get the old behavior of @ref{12b6,,input()}, use @code{eval(input())}.

@item 
A new built-in function @ref{7c2,,next()} was added to call the
@ref{12ab,,__next__()} method on an object.

@item 
The @ref{12b8,,round()} function rounding strategy and return type have
changed.  Exact halfway cases are now rounded to the nearest even
result instead of away from zero.  (For example, @code{round(2.5)} now
returns @code{2} rather than @code{3}.)  @code{round(x[, n])} now
delegates to @code{x.__round__([n])} instead of always returning a
float.  It generally returns an integer when called with a single
argument and a value of the same type as @code{x} when called with two
arguments.

@item 
Moved @code{intern()} to @ref{12b9,,sys.intern()}.

@item 
Removed: @code{apply()}.  Instead of @code{apply(f, args)} use
@code{f(*args)}.

@item 
Removed @ref{11a3,,callable()}.  Instead of @code{callable(f)} you can use
@code{isinstance(f, collections.Callable)}.  The @code{operator.isCallable()}
function is also gone.

@item 
Removed @code{coerce()}.  This function no longer serves a purpose
now that classic classes are gone.

@item 
Removed @code{execfile()}.  Instead of @code{execfile(fn)} use
@code{exec(open(fn).read())}.

@item 
Removed the @code{file} type.  Use @ref{505,,open()}.  There are now several
different kinds of streams that open can return in the @ref{7e,,io} module.

@item 
Removed @code{reduce()}.  Use @ref{12ba,,functools.reduce()} if you really
need it; however, 99 percent of the time an explicit @ref{2e6,,for}
loop is more readable.

@item 
Removed @code{reload()}.  Use @code{imp.reload()}.

@item 
Removed. @code{dict.has_key()} -- use the @ref{2e8,,in} operator
instead.
@end itemize

@c ======================================================================

@node Build and C API Changes<7>,Performances,Miscellaneous Other Changes,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 build-and-c-api-changes}@anchor{12bb}
@subsection Build and C API Changes


Due to time constraints, here is a `very' incomplete list of changes
to the C API.


@itemize *

@item 
Support for several platforms was dropped, including but not limited
to Mac OS 9, BeOS, RISCOS, Irix, and Tru64.

@item 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/}: New Buffer API.

@item 
@geindex Python Enhancement Proposals; PEP 3121
PEP 3121@footnote{https://peps.python.org/pep-3121/}: Extension Module Initialization & Finalization.

@item 
@geindex Python Enhancement Proposals; PEP 3123
PEP 3123@footnote{https://peps.python.org/pep-3123/}: Making @ref{12bc,,PyObject_HEAD} conform to standard C.

@item 
No more C API support for restricted execution.

@item 
@code{PyNumber_Coerce()}, @code{PyNumber_CoerceEx()},
@code{PyMember_Get()}, and @code{PyMember_Set()} C APIs are removed.

@item 
New C API @ref{3b4,,PyImport_ImportModuleNoBlock()}, works like
@ref{3b5,,PyImport_ImportModule()} but won't block on the import lock
(returning an error instead).

@item 
Renamed the boolean conversion C-level slot and method:
@code{nb_nonzero} is now @code{nb_bool}.

@item 
Removed @code{METH_OLDARGS} and @code{WITH_CYCLE_GC} from the C API.
@end itemize

@c ======================================================================

@node Performances,Portage vers Python 3 0,Build and C API Changes<7>,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 performance}@anchor{12bd}
@subsection Performances


The net result of the 3.0 generalizations is that Python 3.0 runs the
pystone benchmark around 10% slower than Python 2.5.  Most likely the
biggest cause is the removal of special-casing for small integers.
There's room for improvement, but it will happen after 3.0 is
released!

@c ======================================================================

@node Portage vers Python 3 0,,Performances,Nouveautés de Python 3 0
@anchor{whatsnew/3 0 porting-to-python-3-0}@anchor{12be}
@subsection Portage vers Python 3.0


For porting existing Python 2.5 or 2.6 source code to Python 3.0, the
best strategy is the following:


@enumerate 0

@item 
(Prerequisite:) Start with excellent test coverage.

@item 
Port to Python 2.6.  This should be no more work than the average
port from Python 2.x to Python 2.(x+1).  Make sure all your tests
pass.

@item 
(Still using 2.6:) Turn on the @code{-3} command line switch.
This enables warnings about features that will be removed (or
change) in 3.0.  Run your test suite again, and fix code that you
get warnings about until there are no warnings left, and all your
tests still pass.

@item 
Run the @code{2to3} source-to-source translator over your source code
tree.  Run the
result of the translation under Python 3.0.  Manually fix up any
remaining issues, fixing problems until all tests pass again.
@end enumerate

It is not recommended to try to write source code that runs unchanged
under both Python 2.6 and 3.0; you'd have to use a very contorted
coding style, e.g. avoiding @code{print} statements, metaclasses,
and much more.  If you are maintaining a library that needs to support
both Python 2.6 and Python 3.0, the best approach is to modify step 3
above by editing the 2.6 version of the source code and running the
@code{2to3} translator again, rather than editing the 3.0 version of the
source code.

For porting C extensions to Python 3.0, please see @ref{12bf,,Portage des modules d'extension vers Python 3}.

@c ======================================================================

@node Nouveautés de Python 2 7,Nouveautés de Python 2 6,Nouveautés de Python 3 0,Nouveautés de Python
@anchor{whatsnew/2 7 doc}@anchor{12c0}@anchor{whatsnew/2 7 what-s-new-in-python-2-7}@anchor{12c1}
@section Nouveautés de Python 2.7


@*Auteur: 
A.M. Kuchling (amk at amk.ca)


@c hyperlink all the methods & functions.

@c T_STRING_INPLACE not described in main docs

@c $Id$
@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.  Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number in a parenthetical comment.
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer; :issue:`12345`.)
@c 
@c This saves the maintainer some effort going through the SVN logs
@c when researching a change.

This article explains the new features in Python 2.7.  Python 2.7 was released
on July 3, 2010.

Numeric handling has been improved in many ways, for both
floating-point numbers and for the @ref{29a,,Decimal} class.
There are some useful additions to the standard library, such as a
greatly enhanced @ref{105,,unittest} module, the @ref{6,,argparse} module
for parsing command-line options, convenient @ref{5c5,,OrderedDict}
and @ref{107b,,Counter} classes in the @ref{1d,,collections} module,
and many other improvements.

Python 2.7 is planned to be the last of the 2.x releases, so we worked
on making it a good release for the long term.  To help with porting
to Python 3, several new features from the Python 3.x series have been
included in 2.7.

This article doesn't attempt to provide a complete specification of
the new features, but instead provides a convenient overview.  For
full details, you should refer to the documentation for Python 2.7 at
@indicateurl{https://docs.python.org}. If you want to understand the rationale for
the design and implementation, refer to the PEP for a particular new
feature or the issue on @indicateurl{https://bugs.python.org} in which a change was
discussed.  Whenever possible, "What's New in Python" links to the
bug/patch item for each change.

@menu
* The Future for Python 2.x: The Future for Python 2 x. 
* Changes to the Handling of Deprecation Warnings:: 
* Python 3.1 Features: Python 3 1 Features. 
* PEP 372; Adding an Ordered Dictionary to collections: PEP 372 Adding an Ordered Dictionary to collections. 
* PEP 378; Format Specifier for Thousands Separator: PEP 378 Format Specifier for Thousands Separator<2>. 
* PEP 389; The argparse Module for Parsing Command Lines: PEP 389 The argparse Module for Parsing Command Lines. 
* PEP 391; Dictionary-Based Configuration For Logging: PEP 391 Dictionary-Based Configuration For Logging. 
* PEP 3106; Dictionary Views: PEP 3106 Dictionary Views. 
* PEP 3137; The memoryview Object: PEP 3137 The memoryview Object. 
* Autres changements au langage: Autres changements au langage<14>. 
* New and Improved Modules:: 
* Build and C API Changes: Build and C API Changes<8>. 
* Autres changements et corrections:: 
* Portage vers Python 2.7: Portage vers Python 2 7. 
* New Features Added to Python 2.7 Maintenance Releases: New Features Added to Python 2 7 Maintenance Releases. 
* Remerciements:: 

@end menu

@node The Future for Python 2 x,Changes to the Handling of Deprecation Warnings,,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 the-future-for-python-2-x}@anchor{12c2}@anchor{whatsnew/2 7 whatsnew27-python31}@anchor{12c3}
@subsection The Future for Python 2.x


Python 2.7 is the last major release in the 2.x series, as the Python
maintainers have shifted the focus of their new feature development efforts
to the Python 3.x series. This means that while Python 2 continues to
receive bug fixes, and to be updated to build correctly on new hardware and
versions of supported operated systems, there will be no new full feature
releases for the language or standard library.

However, while there is a large common subset between Python 2.7 and Python
3, and many of the changes involved in migrating to that common subset, or
directly to Python 3, can be safely automated, some other changes (notably
those associated with Unicode handling) may require careful consideration,
and preferably robust automated regression test suites, to migrate
effectively.

This means that Python 2.7 will remain in place for a long time, providing a
stable and supported base platform for production systems that have not yet
been ported to Python 3. The full expected lifecycle of the Python 2.7
series is detailed in 
@geindex Python Enhancement Proposals; PEP 373
PEP 373@footnote{https://peps.python.org/pep-0373/}.

Some key consequences of the long-term significance of 2.7 are:


@itemize *

@item 
As noted above, the 2.7 release has a much longer period of maintenance
when compared to earlier 2.x versions. Python 2.7 is currently expected to
remain supported by the core development team (receiving security updates
and other bug fixes) until at least 2020 (10 years after its initial
release, compared to the more typical support period of 18--24 months).

@item 
As the Python 2.7 standard library ages, making effective use of the
Python Package Index (either directly or via a redistributor) becomes
more important for Python 2 users. In addition to a wide variety of third
party packages for various tasks, the available packages include backports
of new modules and features from the Python 3 standard library that are
compatible with Python 2, as well as various tools and libraries that can
make it easier to migrate to Python 3. The Python Packaging User Guide@footnote{https://packaging.python.org} provides guidance on downloading and
installing software from the Python Package Index.

@item 
While the preferred approach to enhancing Python 2 is now the publication
of new packages on the Python Package Index, this approach doesn't
necessarily work in all cases, especially those related to network
security. In exceptional cases that cannot be handled adequately by
publishing new or updated packages on PyPI, the Python Enhancement
Proposal process may be used to make the case for adding new features
directly to the Python 2 standard library. Any such additions, and the
maintenance releases where they were added, will be noted in the
@ref{12c4,,New Features Added to Python 2.7 Maintenance Releases} section below.
@end itemize

For projects wishing to migrate from Python 2 to Python 3, or for library
and framework developers wishing to support users on both Python 2 and
Python 3, there are a variety of tools and guides available to help decide
on a suitable approach and manage some of the technical details involved.
The recommended starting point is the pyporting-howto HOWTO guide.

@node Changes to the Handling of Deprecation Warnings,Python 3 1 Features,The Future for Python 2 x,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 changes-to-the-handling-of-deprecation-warnings}@anchor{12c5}
@subsection Changes to the Handling of Deprecation Warnings


For Python 2.7, a policy decision was made to silence warnings only of
interest to developers by default.  @ref{1a3,,DeprecationWarning} and its
descendants are now ignored unless otherwise requested, preventing
users from seeing warnings triggered by an application.  This change
was also made in the branch that became Python 3.2. (Discussed
on stdlib-sig and carried out in bpo-7319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7319}.)

In previous releases, @ref{1a3,,DeprecationWarning} messages were
enabled by default, providing Python developers with a clear
indication of where their code may break in a future major version
of Python.

However, there are increasingly many users of Python-based
applications who are not directly involved in the development of
those applications.  @ref{1a3,,DeprecationWarning} messages are
irrelevant to such users, making them worry about an application
that's actually working correctly and burdening application developers
with responding to these concerns.

You can re-enable display of @ref{1a3,,DeprecationWarning} messages by
running Python with the @ref{8b4,,-Wdefault} (short form:
@ref{8b4,,-Wd}) switch, or by setting the 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS}
environment variable to @code{"default"} (or @code{"d"}) before running
Python.  Python code can also re-enable them
by calling @code{warnings.simplefilter('default')}.

The @code{unittest} module also automatically reenables deprecation warnings
when running tests.

@node Python 3 1 Features,PEP 372 Adding an Ordered Dictionary to collections,Changes to the Handling of Deprecation Warnings,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 python-3-1-features}@anchor{12c6}
@subsection Python 3.1 Features


Much as Python 2.6 incorporated features from Python 3.0,
version 2.7 incorporates some of the new features
in Python 3.1.  The 2.x series continues to provide tools
for migrating to the 3.x series.

A partial list of 3.1 features that were backported to 2.7:


@itemize *

@item 
The syntax for set literals (@code{@{1,2,3@}} is a mutable set).

@item 
Dictionary and set comprehensions (@code{@{i: i*2 for i in range(3)@}}).

@item 
Multiple context managers in a single @ref{5bc,,with} statement.

@item 
A new version of the @ref{7e,,io} library, rewritten in C for performance.

@item 
The ordered-dictionary type described in @ref{12c7,,PEP 372; Adding an Ordered Dictionary to collections}.

@item 
The new @code{","} format specifier described in @ref{12c8,,PEP 378; Format Specifier for Thousands Separator}.

@item 
The @ref{452,,memoryview} object.

@item 
A small subset of the @ref{76,,importlib} module,
@ref{12c9,,described below}.

@item 
The @ref{7e7,,repr()} of a float @code{x} is shorter in many cases: it's now
based on the shortest decimal string that's guaranteed to round back
to @code{x}.  As in previous versions of Python, it's guaranteed that
@code{float(repr(x))} recovers @code{x}.

@item 
Float-to-string and string-to-float conversions are correctly rounded.
The @ref{12b8,,round()} function is also now correctly rounded.

@item 
The @ref{1251,,PyCapsule} type, used to provide a C API for extension modules.

@item 
The @ref{1245,,PyLong_AsLongAndOverflow()} C API function.
@end itemize

Other new Python3-mode warnings include:


@itemize *

@item 
@code{operator.isCallable()} and @code{operator.sequenceIncludes()},
which are not supported in 3.x, now trigger warnings.

@item 
The @code{-3} switch now automatically
enables the @code{-Qwarn} switch that causes warnings
about using classic division with integers and long integers.
@end itemize

@c ========================================================================

@c Large, PEP-level features and changes should be described here.

@c ========================================================================

@node PEP 372 Adding an Ordered Dictionary to collections,PEP 378 Format Specifier for Thousands Separator<2>,Python 3 1 Features,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 pep-0372}@anchor{12c7}@anchor{whatsnew/2 7 pep-372-adding-an-ordered-dictionary-to-collections}@anchor{12ca}
@subsection PEP 372: Adding an Ordered Dictionary to collections


Regular Python dictionaries iterate over key/value pairs in arbitrary order.
Over the years, a number of authors have written alternative implementations
that remember the order that the keys were originally inserted.  Based on
the experiences from those implementations, 2.7 introduces a new
@ref{5c5,,OrderedDict} class in the @ref{1d,,collections} module.

The @ref{5c5,,OrderedDict} API provides the same interface as regular
dictionaries but iterates over keys and values in a guaranteed order
depending on when a key was first inserted:

@example
>>> from collections import OrderedDict
>>> d = OrderedDict([('first', 1),
...                  ('second', 2),
...                  ('third', 3)])
>>> d.items()
[('first', 1), ('second', 2), ('third', 3)]
@end example

If a new entry overwrites an existing entry, the original insertion
position is left unchanged:

@example
>>> d['second'] = 4
>>> d.items()
[('first', 1), ('second', 4), ('third', 3)]
@end example

Deleting an entry and reinserting it will move it to the end:

@example
>>> del d['second']
>>> d['second'] = 5
>>> d.items()
[('first', 1), ('third', 3), ('second', 5)]
@end example

The @ref{12cb,,popitem()} method has an optional `last'
argument that defaults to @code{True}.  If `last' is true, the most recently
added key is returned and removed; if it's false, the
oldest key is selected:

@example
>>> od = OrderedDict([(x,0) for x in range(20)])
>>> od.popitem()
(19, 0)
>>> od.popitem()
(18, 0)
>>> od.popitem(last=False)
(0, 0)
>>> od.popitem(last=False)
(1, 0)
@end example

Comparing two ordered dictionaries checks both the keys and values,
and requires that the insertion order was the same:

@example
>>> od1 = OrderedDict([('first', 1),
...                    ('second', 2),
...                    ('third', 3)])
>>> od2 = OrderedDict([('third', 3),
...                    ('first', 1),
...                    ('second', 2)])
>>> od1 == od2
False
>>> # Move 'third' key to the end
>>> del od2['third']; od2['third'] = 3
>>> od1 == od2
True
@end example

Comparing an @ref{5c5,,OrderedDict} with a regular dictionary
ignores the insertion order and just compares the keys and values.

How does the @ref{5c5,,OrderedDict} work?  It maintains a
doubly linked list of keys, appending new keys to the list as they're inserted.
A secondary dictionary maps keys to their corresponding list node, so
deletion doesn't have to traverse the entire linked list and therefore
remains `O'(1).

The standard library now supports use of ordered dictionaries in several
modules.


@itemize *

@item 
The @ref{22,,ConfigParser} module uses them by default, meaning that
configuration files can now be read, modified, and then written back
in their original order.

@item 
The @ref{9cf,,_asdict()} method for
@ref{1c5,,collections.namedtuple()} now returns an ordered dictionary with the
values appearing in the same order as the underlying tuple indices.

@item 
The @ref{81,,json} module's @ref{d35,,JSONDecoder} class
constructor was extended with an `object_pairs_hook' parameter to
allow @code{OrderedDict} instances to be built by the decoder.
Support was also added for third-party tools like
PyYAML@footnote{https://pyyaml.org/}.
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 372

@item PEP 372@footnote{https://peps.python.org/pep-0372/} - Adding an ordered dictionary to collections

PEP written by Armin Ronacher and Raymond Hettinger;
implemented by Raymond Hettinger.
@end table


@node PEP 378 Format Specifier for Thousands Separator<2>,PEP 389 The argparse Module for Parsing Command Lines,PEP 372 Adding an Ordered Dictionary to collections,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 pep-0378}@anchor{12c8}@anchor{whatsnew/2 7 pep-378-format-specifier-for-thousands-separator}@anchor{12cc}
@subsection PEP 378: Format Specifier for Thousands Separator


To make program output more readable, it can be useful to add
separators to large numbers, rendering them as
18,446,744,073,709,551,616 instead of 18446744073709551616.

The fully general solution for doing this is the @ref{85,,locale} module,
which can use different separators ("," in North America, "." in
Europe) and different grouping sizes, but @ref{85,,locale} is complicated
to use and unsuitable for multi-threaded applications where different
threads are producing output for different locales.

Therefore, a simple comma-grouping mechanism has been added to the
mini-language used by the @ref{60c,,str.format()} method.  When
formatting a floating-point number, simply include a comma between the
width and the precision:

@example
>>> '@{:20,.2f@}'.format(18446744073709551616.0)
'18,446,744,073,709,551,616.00'
@end example

When formatting an integer, include the comma after the width:

@example
>>> '@{:20,d@}'.format(18446744073709551616)
'18,446,744,073,709,551,616'
@end example

This mechanism is not adaptable at all; commas are always used as the
separator and the grouping is always into three-digit groups.  The
comma-formatting mechanism isn't as general as the @ref{85,,locale}
module, but it's easier to use.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 378

@item PEP 378@footnote{https://peps.python.org/pep-0378/} - Format Specifier for Thousands Separator

PEP written by Raymond Hettinger; implemented by Eric Smith.
@end table


@node PEP 389 The argparse Module for Parsing Command Lines,PEP 391 Dictionary-Based Configuration For Logging,PEP 378 Format Specifier for Thousands Separator<2>,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 pep-389-the-argparse-module-for-parsing-command-lines}@anchor{12cd}
@subsection PEP 389: The argparse Module for Parsing Command Lines


The @ref{6,,argparse} module for parsing command-line arguments was
added as a more powerful replacement for the
@ref{9f,,optparse} module.

This means Python now supports three different modules for parsing
command-line arguments: @ref{60,,getopt}, @ref{9f,,optparse}, and
@ref{6,,argparse}.  The @ref{60,,getopt} module closely resembles the C
library's @code{getopt()} function, so it remains useful if you're writing a
Python prototype that will eventually be rewritten in C.
@ref{9f,,optparse} becomes redundant, but there are no plans to remove it
because there are many scripts still using it, and there's no
automated way to update these scripts.  (Making the @ref{6,,argparse}
API consistent with @ref{9f,,optparse}'s interface was discussed but
rejected as too messy and difficult.)

In short, if you're writing a new script and don't need to worry
about compatibility with earlier versions of Python, use
@ref{6,,argparse} instead of @ref{9f,,optparse}.

Voici un exemple :

@example
import argparse

parser = argparse.ArgumentParser(description='Command-line example.')

# Add optional switches
parser.add_argument('-v', action='store_true', dest='is_verbose',
                    help='produce verbose output')
parser.add_argument('-o', action='store', dest='output',
                    metavar='FILE',
                    help='direct output to FILE instead of stdout')
parser.add_argument('-C', action='store', type=int, dest='context',
                    metavar='NUM', default=0,
                    help='display NUM lines of added context')

# Allow any number of additional arguments.
parser.add_argument(nargs='*', action='store', dest='inputs',
                    help='input filenames (default is stdin)')

args = parser.parse_args()
print args.__dict__
@end example

Unless you override it, @code{-h} and @code{--help} switches
are automatically added, and produce neatly formatted output:

@example
-> ./python.exe argparse-example.py --help
usage: argparse-example.py [-h] [-v] [-o FILE] [-C NUM] [inputs [inputs ...]]

Command-line example.

positional arguments:
  inputs      input filenames (default is stdin)

optional arguments:
  -h, --help  show this help message and exit
  -v          produce verbose output
  -o FILE     direct output to FILE instead of stdout
  -C NUM      display NUM lines of added context
@end example

As with @ref{9f,,optparse}, the command-line switches and arguments
are returned as an object with attributes named by the `dest' parameters:

@example
-> ./python.exe argparse-example.py -v
@{'output': None,
 'is_verbose': True,
 'context': 0,
 'inputs': []@}

-> ./python.exe argparse-example.py -v -o /tmp/output -C 4 file1 file2
@{'output': '/tmp/output',
 'is_verbose': True,
 'context': 4,
 'inputs': ['file1', 'file2']@}
@end example

@ref{6,,argparse} has much fancier validation than @ref{9f,,optparse}; you
can specify an exact number of arguments as an integer, 0 or more
arguments by passing @code{'*'}, 1 or more by passing @code{'+'}, or an
optional argument with @code{'?'}.  A top-level parser can contain
sub-parsers to define subcommands that have different sets of
switches, as in @code{svn commit}, @code{svn checkout}, etc.  You can
specify an argument's type as @ref{f06,,FileType}, which will
automatically open files for you and understands that @code{'-'} means
standard input or output.


@subsubheading Voir aussi



@table @asis

@item Documentation du module @ref{6,,argparse}

The documentation page of the argparse module.

@item @ref{118b,,Migrating optparse code to argparse}

Part of the Python documentation, describing how to convert
code that uses @ref{9f,,optparse}.

@geindex Python Enhancement Proposals; PEP 389

@item PEP 389@footnote{https://peps.python.org/pep-0389/} - argparse - New Command Line Parsing Module

PEP written and implemented by Steven Bethard.
@end table


@node PEP 391 Dictionary-Based Configuration For Logging,PEP 3106 Dictionary Views,PEP 389 The argparse Module for Parsing Command Lines,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 pep-391-dictionary-based-configuration-for-logging}@anchor{12ce}
@subsection PEP 391: Dictionary-Based Configuration For Logging


The @ref{86,,logging} module is very flexible; applications can define
a tree of logging subsystems, and each logger in this tree can filter
out certain messages, format them differently, and direct messages to
a varying number of handlers.

All this flexibility can require a lot of configuration.  You can
write Python statements to create objects and set their properties,
but a complex set-up requires verbose but boring code.
@ref{86,,logging} also supports a @ref{b3f,,fileConfig()}
function that parses a file, but the file format doesn't support
configuring filters, and it's messier to generate programmatically.

Python 2.7 adds a @ref{118d,,dictConfig()} function that
uses a dictionary to configure logging.  There are many ways to
produce a dictionary from different sources: construct one with code;
parse a file containing JSON; or use a YAML parsing library if one is
installed.  For more information see @ref{12cf,,Configuration functions}.

The following example configures two loggers, the root logger and a
logger named "network".  Messages sent to the root logger will be
sent to the system log using the syslog protocol, and messages
to the "network" logger will be written to a @code{network.log} file
that will be rotated once the log reaches 1MB.

@example
import logging
import logging.config

configdict = @{
 'version': 1,    # Configuration schema in use; must be 1 for now
 'formatters': @{
     'standard': @{
         'format': ('%(asctime)s %(name)-15s '
                    '%(levelname)-8s %(message)s')@}@},

 'handlers': @{'netlog': @{'backupCount': 10,
                     'class': 'logging.handlers.RotatingFileHandler',
                     'filename': '/logs/network.log',
                     'formatter': 'standard',
                     'level': 'INFO',
                     'maxBytes': 1000000@},
              'syslog': @{'class': 'logging.handlers.SysLogHandler',
                         'formatter': 'standard',
                         'level': 'ERROR'@}@},

 # Specify all the subordinate loggers
 'loggers': @{
             'network': @{
                         'handlers': ['netlog']
             @}
 @},
 # Specify properties of the root logger
 'root': @{
          'handlers': ['syslog']
 @},
@}

# Set up configuration
logging.config.dictConfig(configdict)

# As an example, log two error messages
logger = logging.getLogger('/')
logger.error('Database not found')

netlogger = logging.getLogger('network')
netlogger.error('Connection failed')
@end example

Three smaller enhancements to the @ref{86,,logging} module, all
implemented by Vinay Sajip, are:

@c rev79293


@itemize *

@item 
The @ref{647,,SysLogHandler} class now supports
syslogging over TCP.  The constructor has a `socktype' parameter
giving the type of socket to use, either @ref{12d0,,socket.SOCK_DGRAM}
for UDP or @ref{12d1,,socket.SOCK_STREAM} for TCP.  The default
protocol remains UDP.

@item 
@ref{b3d,,Logger} instances gained a @ref{12d2,,getChild()}
method that retrieves a descendant logger using a relative path.
For example, once you retrieve a logger by doing @code{log = getLogger('app')},
calling @code{log.getChild('network.listen')} is equivalent to
@code{getLogger('app.network.listen')}.

@item 
The @ref{12d3,,LoggerAdapter} class gained an
@ref{12d4,,isEnabledFor()} method that takes a
`level' and returns whether the underlying logger would
process a message of that level of importance.
@end itemize

@c XXX: Logger objects don't have a class declaration so the link don't work


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 391

@item PEP 391@footnote{https://peps.python.org/pep-0391/} - Dictionary-Based Configuration For Logging

PEP written and implemented by Vinay Sajip.
@end table


@node PEP 3106 Dictionary Views,PEP 3137 The memoryview Object,PEP 391 Dictionary-Based Configuration For Logging,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 pep-3106-dictionary-views}@anchor{12d5}
@subsection PEP 3106: Dictionary Views


The dictionary methods @ref{7b7,,keys()}, @ref{7b8,,values()}, and
@ref{7b9,,items()} are different in Python 3.x.  They return an object
called a `view' instead of a fully materialized list.

It's not possible to change the return values of @ref{7b7,,keys()},
@ref{7b8,,values()}, and @ref{7b9,,items()} in Python 2.7 because
too much code would break.  Instead the 3.x versions were added
under the new names @code{viewkeys()}, @code{viewvalues()},
and @code{viewitems()}.

@example
>>> d = dict((i*10, chr(65+i)) for i in range(26))
>>> d
@{0: 'A', 130: 'N', 10: 'B', 140: 'O', 20: ..., 250: 'Z'@}
>>> d.viewkeys()
dict_keys([0, 130, 10, 140, 20, 150, 30, ..., 250])
@end example

Views can be iterated over, but the key and item views also behave
like sets.  The @code{&} operator performs intersection, and @code{|}
performs a union:

@example
>>> d1 = dict((i*10, chr(65+i)) for i in range(26))
>>> d2 = dict((i**.5, i) for i in range(1000))
>>> d1.viewkeys() & d2.viewkeys()
set([0.0, 10.0, 20.0, 30.0])
>>> d1.viewkeys() | range(0, 30)
set([0, 1, 130, 3, 4, 5, 6, ..., 120, 250])
@end example

The view keeps track of the dictionary and its contents change as the
dictionary is modified:

@example
>>> vk = d.viewkeys()
>>> vk
dict_keys([0, 130, 10, ..., 250])
>>> d[260] = '&'
>>> vk
dict_keys([0, 130, 260, 10, ..., 250])
@end example

However, note that you can't add or remove keys while you're iterating
over the view:

@example
>>> for k in vk:
...     d[k*2] = k
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: dictionary changed size during iteration
@end example

You can use the view methods in Python 2.x code, and the 2to3
converter will change them to the standard @ref{7b7,,keys()},
@ref{7b8,,values()}, and @ref{7b9,,items()} methods.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3106

@item PEP 3106@footnote{https://peps.python.org/pep-3106/} - Revamping dict.keys(), .values() and .items()

PEP written by Guido van Rossum.
Backported to 2.7 by Alexandre Vassalotti; bpo-1967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1967}.
@end table


@node PEP 3137 The memoryview Object,Autres changements au langage<14>,PEP 3106 Dictionary Views,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 pep-3137-the-memoryview-object}@anchor{12d6}
@subsection PEP 3137: The memoryview Object


The @ref{452,,memoryview} object provides a view of another object's
memory content that matches the @ref{1bd,,bytes} type's interface.

@example
>>> import string
>>> m = memoryview(string.letters)
>>> m
<memory at 0x37f850>
>>> len(m)           # Returns length of underlying object
52
>>> m[0], m[25], m[26]   # Indexing returns one byte
('a', 'z', 'A')
>>> m2 = m[0:26]         # Slicing returns another memoryview
>>> m2
<memory at 0x37f080>
@end example

The content of the view can be converted to a string of bytes or
a list of integers:

@example
>>> m2.tobytes()
'abcdefghijklmnopqrstuvwxyz'
>>> m2.tolist()
[97, 98, 99, 100, 101, 102, 103, ... 121, 122]
>>>
@end example

@ref{452,,memoryview} objects allow modifying the underlying object if
it's a mutable object.

@example
>>> m2[0] = 75
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> b = bytearray(string.letters)  # Creating a mutable object
>>> b
bytearray(b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ')
>>> mb = memoryview(b)
>>> mb[0] = '*'         # Assign to view, changing the bytearray.
>>> b[0:5]              # The bytearray has been changed.
bytearray(b'*bcde')
>>>
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3137

@item PEP 3137@footnote{https://peps.python.org/pep-3137/} - Immutable Bytes and Mutable Buffer

PEP written by Guido van Rossum.
Implemented by Travis Oliphant, Antoine Pitrou and others.
Backported to 2.7 by Antoine Pitrou; bpo-2396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2396}.
@end table


@node Autres changements au langage<14>,New and Improved Modules,PEP 3137 The memoryview Object,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 other-language-changes}@anchor{12d7}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
The syntax for set literals has been backported from Python 3.x.
Curly brackets are used to surround the contents of the resulting
mutable set; set literals are
distinguished from dictionaries by not containing colons and values.
@code{@{@}} continues to represent an empty dictionary; use
@code{set()} for an empty set.

@example
>>> @{1, 2, 3, 4, 5@}
set([1, 2, 3, 4, 5])
>>> set() # empty set
set([])
>>> @{@}    # empty dict
@{@}
@end example

Backported by Alexandre Vassalotti; bpo-2335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2335}.

@item 
Dictionary and set comprehensions are another feature backported from
3.x, generalizing list/generator comprehensions to use
the literal syntax for sets and dictionaries.

@example
>>> @{x: x*x for x in range(6)@}
@{0: 0, 1: 1, 2: 4, 3: 9, 4: 16, 5: 25@}
>>> @{('a'*x) for x in range(6)@}
set(['@w{'}, 'a', 'aa', 'aaa', 'aaaa', 'aaaaa'])
@end example

Backported by Alexandre Vassalotti; bpo-2333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2333}.

@item 
The @ref{5bc,,with} statement can now use multiple context managers
in one statement.  Context managers are processed from left to right
and each one is treated as beginning a new @code{with} statement.
This means that:

@example
with A() as a, B() as b:
    ... suite of statements ...
@end example

est équivalente à :

@example
with A() as a:
    with B() as b:
        ... suite of statements ...
@end example

The @code{contextlib.nested()} function provides a very similar
function, so it's no longer necessary and has been deprecated.

(Proposed in @indicateurl{https://codereview.appspot.com/53094}; implemented by
Georg Brandl.)

@item 
Conversions between floating-point numbers and strings are
now correctly rounded on most platforms.  These conversions occur
in many different places: @ref{435,,str()} on
floats and complex numbers; the @ref{2eb,,float} and @ref{2ec,,complex}
constructors;
numeric formatting; serializing and
deserializing floats and complex numbers using the
@ref{8c,,marshal}, @ref{a5,,pickle}
and @ref{81,,json} modules;
parsing of float and imaginary literals in Python code;
and @ref{29a,,Decimal}-to-float conversion.

Related to this, the @ref{7e7,,repr()} of a floating-point number `x'
now returns a result based on the shortest decimal string that's
guaranteed to round back to `x' under correct rounding (with
round-half-to-even rounding mode).  Previously it gave a string
based on rounding x to 17 decimal digits.

@c maybe add an example?

The rounding library responsible for this improvement works on
Windows and on Unix platforms using the gcc, icc, or suncc
compilers.  There may be a small number of platforms where correct
operation of this code cannot be guaranteed, so the code is not
used on such systems.  You can find out which code is being used
by checking @ref{12d8,,sys.float_repr_style},  which will be @code{short}
if the new code is in use and @code{legacy} if it isn't.

Implemented by Eric Smith and Mark Dickinson, using David Gay's
@code{dtoa.c} library; bpo-7117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7117}.

@item 
Conversions from long integers and regular integers to floating
point now round differently, returning the floating-point number
closest to the number.  This doesn't matter for small integers that
can be converted exactly, but for large numbers that will
unavoidably lose precision, Python 2.7 now approximates more
closely.  For example, Python 2.6 computed the following:

@example
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935283e+20
>>> n - long(float(n))
65535L
@end example

Python 2.7's floating-point result is larger, but much closer to the
true value:

@example
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935289e+20
>>> n - long(float(n))
-1L
@end example

(Implemented by Mark Dickinson; bpo-3166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3166}.)

Integer division is also more accurate in its rounding behaviours.  (Also
implemented by Mark Dickinson; bpo-1811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1811}.)

@item 
Implicit coercion for complex numbers has been removed; the interpreter
will no longer ever attempt to call a @code{__coerce__()} method on complex
objects.  (Removed by Meador Inge and Mark Dickinson; bpo-5211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5211}.)

@item 
The @ref{60c,,str.format()} method now supports automatic numbering of the replacement
fields.  This makes using @ref{60c,,str.format()} more closely resemble using
@code{%s} formatting:

@example
>>> '@{@}:@{@}:@{@}'.format(2009, 04, 'Sunday')
'2009:4:Sunday'
>>> '@{@}:@{@}:@{day@}'.format(2009, 4, day='Sunday')
'2009:4:Sunday'
@end example

The auto-numbering takes the fields from left to right, so the first @code{@{...@}}
specifier will use the first argument to @ref{60c,,str.format()}, the next
specifier will use the next argument, and so on.  You can't mix auto-numbering
and explicit numbering -- either number all of your specifier fields or none
of them -- but you can mix auto-numbering and named fields, as in the second
example above.  (Contributed by Eric Smith; bpo-5237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5237}.)

Complex numbers now correctly support usage with @ref{60a,,format()},
and default to being right-aligned.
Specifying a precision or comma-separation applies to both the real
and imaginary parts of the number, but a specified field width and
alignment is applied to the whole of the resulting @code{1.5+3j}
output.  (Contributed by Eric Smith; bpo-1588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1588} and bpo-7988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7988}.)

The 'F' format code now always formats its output using uppercase characters,
so it will now produce 'INF' and 'NAN'.
(Contributed by Eric Smith; bpo-3382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3382}.)

A low-level change: the @ref{609,,object.__format__()} method now triggers
a @ref{8b5,,PendingDeprecationWarning} if it's passed a format string,
because the @code{__format__()} method for @ref{a7a,,object} converts
the object to a string representation and formats that.  Previously
the method silently applied the format string to the string
representation, but that could hide mistakes in Python code.  If
you're supplying formatting information such as an alignment or
precision, presumably you're expecting the formatting to be applied
in some object-specific way.  (Fixed by Eric Smith; bpo-7994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7994}.)

@item 
The @ref{254,,int()} and @code{long()} types gained a @code{bit_length}
method that returns the number of bits necessary to represent
its argument in binary:

@example
>>> n = 37
>>> bin(n)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124
@end example

(Contributed by Fredrik Johansson and Victor Stinner; bpo-3439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3439}.)

@item 
The @ref{5cc,,import} statement will no longer try an absolute import
if a relative import (e.g. @code{from .os import sep}) fails.  This
fixes a bug, but could possibly break certain @code{import}
statements that were only working by accident.  (Fixed by Meador Inge;
bpo-7902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7902}.)

@item 
It's now possible for a subclass of the built-in @code{unicode} type
to override the @code{__unicode__()} method.  (Implemented by
Victor Stinner; bpo-1583863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1583863}.)

@item 
The @ref{528,,bytearray} type's @ref{12d9,,translate()} method now accepts
@code{None} as its first argument.  (Fixed by Georg Brandl;
bpo-4759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4759}.)

@c XXX bytearray doesn't seem to be documented

@item 
When using @ref{165,,@@classmethod} and
@ref{40c,,@@staticmethod} to wrap
methods as class or static methods, the wrapper object now
exposes the wrapped function as their @ref{12da,,__func__}
attribute.
(Contributed by Amaury Forgeot d'Arc, after a suggestion by
George Sakkis; bpo-5982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5982}.)

@item 
When a restricted set of attributes were set using @code{__slots__},
deleting an unset attribute would not raise @ref{343,,AttributeError}
as you would expect.  Fixed by Benjamin Peterson; bpo-7604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7604}.)

@item 
Two new encodings are now supported: "cp720", used primarily for
Arabic text; and "cp858", a variant of CP 850 that adds the euro
symbol.  (CP720 contributed by Alexander Belchenko and Amaury
Forgeot d'Arc in bpo-1616979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1616979}; CP858 contributed by Tim Hatch in
bpo-8016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8016}.)

@item 
The @code{file} object will now set the @code{filename} attribute
on the @ref{103b,,IOError} exception when trying to open a directory
on POSIX platforms (noted by Jan Kaliszewski; bpo-4764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4764}), and
now explicitly checks for and forbids writing to read-only file objects
instead of trusting the C library to catch and report the error
(fixed by Stefan Krah; bpo-5677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5677}).

@item 
The Python tokenizer now translates line endings itself, so the
@ref{190,,compile()} built-in function now accepts code using any
line-ending convention.  Additionally, it no longer requires that the
code end in a newline.

@item 
Extra parentheses in function definitions are illegal in Python 3.x,
meaning that you get a syntax error from @code{def f((x)): pass}.  In
Python3-warning mode, Python 2.7 will now warn about this odd usage.
(Noted by James Lingard; bpo-7362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7362}.)

@item 
It's now possible to create weak references to old-style class
objects.  New-style classes were always weak-referenceable.  (Fixed
by Antoine Pitrou; bpo-8268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8268}.)

@item 
When a module object is garbage-collected, the module's dictionary is
now only cleared if no one else is holding a reference to the
dictionary (bpo-7140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7140}).
@end itemize

@c ======================================================================

@menu
* Interpreter Changes:: 
* Optimizations: Optimizations<8>. 

@end menu

@node Interpreter Changes,Optimizations<8>,,Autres changements au langage<14>
@anchor{whatsnew/2 7 interpreter-changes}@anchor{12db}@anchor{whatsnew/2 7 new-27-interpreter}@anchor{12dc}
@subsubsection Interpreter Changes


A new environment variable, 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS},
allows controlling warnings.  It should be set to a string
containing warning settings, equivalent to those
used with the @ref{8b4,,-W} switch, separated by commas.
(Contributed by Brian Curtin; bpo-7301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7301}.)

For example, the following setting will print warnings every time
they occur, but turn warnings from the @ref{70,,Cookie} module into an
error.  (The exact syntax for setting an environment variable varies
across operating systems and shells.)

@example
export PYTHONWARNINGS=all,error:::Cookie:0
@end example

@c ======================================================================

@node Optimizations<8>,,Interpreter Changes,Autres changements au langage<14>
@anchor{whatsnew/2 7 optimizations}@anchor{12dd}
@subsubsection Optimizations


Several performance enhancements have been added:


@itemize *

@item 
A new opcode was added to perform the initial setup for
@ref{5bc,,with} statements, looking up the @ref{5b2,,__enter__()} and
@ref{12de,,__exit__()} methods.  (Contributed by Benjamin Peterson.)

@item 
The garbage collector now performs better for one common usage
pattern: when many objects are being allocated without deallocating
any of them.  This would previously take quadratic
time for garbage collection, but now the number of full garbage collections
is reduced as the number of objects on the heap grows.
The new logic only performs a full garbage collection pass when
the middle generation has been collected 10 times and when the
number of survivor objects from the middle generation exceeds 10% of
the number of objects in the oldest generation.  (Suggested by Martin
von Löwis and implemented by Antoine Pitrou; bpo-4074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4074}.)

@item 
The garbage collector tries to avoid tracking simple containers
which can't be part of a cycle. In Python 2.7, this is now true for
tuples and dicts containing atomic types (such as ints, strings,
etc.). Transitively, a dict containing tuples of atomic types won't
be tracked either. This helps reduce the cost of each
garbage collection by decreasing the number of objects to be
considered and traversed by the collector.
(Contributed by Antoine Pitrou; bpo-4688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4688}.)

@item 
Long integers are now stored internally either in base @code{2**15} or in base
@code{2**30}, the base being determined at build time.  Previously, they
were always stored in base @code{2**15}.  Using base @code{2**30} gives
significant performance improvements on 64-bit machines, but
benchmark results on 32-bit machines have been mixed.  Therefore,
the default is to use base @code{2**30} on 64-bit machines and base @code{2**15}
on 32-bit machines; on Unix, there's a new configure option
@code{--enable-big-digits} that can be used to override this default.

Apart from the performance improvements this change should be
invisible to end users, with one exception: for testing and
debugging purposes there's a new structseq @code{sys.long_info} that
provides information about the internal format, giving the number of
bits per digit and the size in bytes of the C type used to store
each digit:

@example
>>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)
@end example

(Contribution par Mark Dickinson; bpo-4258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4258}.)

Another set of changes made long objects a few bytes smaller: 2 bytes
smaller on 32-bit systems and 6 bytes on 64-bit.
(Contributed by Mark Dickinson; bpo-5260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5260}.)

@item 
The division algorithm for long integers has been made faster
by tightening the inner loop, doing shifts instead of multiplications,
and fixing an unnecessary extra iteration.
Various benchmarks show speedups of between 50% and 150% for long
integer divisions and modulo operations.
(Contributed by Mark Dickinson; bpo-5512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5512}.)
Bitwise operations are also significantly faster (initial patch by
Gregory Smith; bpo-1087418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1087418}).

@item 
The implementation of @code{%} checks for the left-side operand being
a Python string and special-cases it; this results in a 1--3%
performance increase for applications that frequently use @code{%}
with strings, such as templating libraries.
(Implemented by Collin Winter; bpo-5176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5176}.)

@item 
List comprehensions with an @code{if} condition are compiled into
faster bytecode.  (Patch by Antoine Pitrou, back-ported to 2.7
by Jeffrey Yasskin; bpo-4715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4715}.)

@item 
Converting an integer or long integer to a decimal string was made
faster by special-casing base 10 instead of using a generalized
conversion function that supports arbitrary bases.
(Patch by Gawain Bolton; bpo-6713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6713}.)

@item 
The @code{split()}, @code{replace()}, @code{rindex()},
@code{rpartition()}, and @code{rsplit()} methods of string-like types
(strings, Unicode strings, and @ref{528,,bytearray} objects) now use a
fast reverse-search algorithm instead of a character-by-character
scan.  This is sometimes faster by a factor of 10.  (Added by
Florent Xicluna; bpo-7462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7462} and bpo-7622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7622}.)

@item 
The @ref{a5,,pickle} and @code{cPickle} modules now automatically
intern the strings used for attribute names, reducing memory usage
of the objects resulting from unpickling.  (Contributed by Jake
McGuire; bpo-5084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5084}.)

@item 
The @code{cPickle} module now special-cases dictionaries,
nearly halving the time required to pickle them.
(Contributed by Collin Winter; bpo-5670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5670}.)
@end itemize

@c ======================================================================

@node New and Improved Modules,Build and C API Changes<8>,Autres changements au langage<14>,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 new-and-improved-modules}@anchor{12df}
@subsection New and Improved Modules


As in every release, Python's standard library received a number of
enhancements and bug fixes.  Here's a partial list of the most notable
changes, sorted alphabetically by module name. Consult the
@code{Misc/NEWS} file in the source tree for a more complete list of
changes, or look through the Subversion logs for all the details.


@itemize *

@item 
The @ref{f,,bdb} module's base debugging class @ref{12e0,,Bdb}
gained a feature for skipping modules.  The constructor
now takes an iterable containing glob-style patterns such as
@code{django.*}; the debugger will not step into stack frames
from a module that matches one of these patterns.
(Contributed by Maru Newby after a suggestion by
Senthil Kumaran; bpo-5142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5142}.)

@item 
The @ref{10,,binascii} module now supports the buffer API, so it can be
used with @ref{452,,memoryview} instances and other similar buffer objects.
(Backported from 3.x by Florent Xicluna; bpo-7703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7703}.)

@item 
Updated module: the @code{bsddb} module has been updated from 4.7.2devel9
to version 4.8.4 of
the pybsddb package@footnote{https://www.jcea.es/programacion/pybsddb.htm}.
The new version features better Python 3.x compatibility, various bug fixes,
and adds several new BerkeleyDB flags and methods.
(Updated by Jesús Cea Avión; bpo-8156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8156}.  The pybsddb
changelog can be read at @indicateurl{https://hg.jcea.es/pybsddb/file/tip/ChangeLog}.)

@item 
The @ref{13,,bz2} module's @ref{851,,BZ2File} now supports the context
management protocol, so you can write @code{with bz2.BZ2File(...) as f:}.
(Contributed by Hagen Fürstenau; bpo-3860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3860}.)

@item 
New class: the @ref{107b,,Counter} class in the @ref{1d,,collections}
module is useful for tallying data.  @ref{107b,,Counter} instances
behave mostly like dictionaries but return zero for missing keys instead of
raising a @ref{33a,,KeyError}:

@example
>>> from collections import Counter
>>> c = Counter()
>>> for letter in 'here is a sample of english text':
...   c[letter] += 1
...
>>> c 
Counter(@{' ': 6, 'e': 5, 's': 3, 'a': 2, 'i': 2, 'h': 2,
'l': 2, 't': 2, 'g': 1, 'f': 1, 'm': 1, 'o': 1, 'n': 1,
'p': 1, 'r': 1, 'x': 1@})
>>> c['e']
5
>>> c['z']
0
@end example

There are three additional @ref{107b,,Counter} methods.
@ref{12e1,,most_common()} returns the N most common
elements and their counts.  @ref{12e2,,elements()}
returns an iterator over the contained elements, repeating each
element as many times as its count.
@ref{11bb,,subtract()} takes an iterable and
subtracts one for each element instead of adding; if the argument is
a dictionary or another @code{Counter}, the counts are
subtracted.

@example
>>> c.most_common(5)
[(' ', 6), ('e', 5), ('s', 3), ('a', 2), ('i', 2)]
>>> c.elements() ->
   'a', 'a', ' ', ' ', ' ', ' ', ' ', ' ',
   'e', 'e', 'e', 'e', 'e', 'g', 'f', 'i', 'i',
   'h', 'h', 'm', 'l', 'l', 'o', 'n', 'p', 's',
   's', 's', 'r', 't', 't', 'x'
>>> c['e']
5
>>> c.subtract('very heavy on the letter e')
>>> c['e']    # Count is now lower
-1
@end example

Contributed by Raymond Hettinger; bpo-1696199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1696199}.

@c revision 79660

New class: @ref{5c5,,OrderedDict} is described in the earlier
section @ref{12c7,,PEP 372; Adding an Ordered Dictionary to collections}.

New method: The @ref{5c6,,deque} data type now has a
@ref{11bd,,count()} method that returns the number of
contained elements equal to the supplied argument `x', and a
@ref{11be,,reverse()} method that reverses the elements
of the deque in-place.  @ref{5c6,,deque} also exposes its maximum
length as the read-only @ref{12e3,,maxlen} attribute.
(Both features added by Raymond Hettinger.)

The @ref{1c5,,namedtuple} class now has an optional `rename' parameter.
If `rename' is true, field names that are invalid because they've
been repeated or aren't legal Python identifiers will be
renamed to legal names that are derived from the field's
position within the list of fields:

@example
>>> from collections import namedtuple
>>> T = namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True)
>>> T._fields
('field1', '_1', '_2', 'field2')
@end example

(Added by Raymond Hettinger; bpo-1818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1818}.)

Finally, the @ref{8b7,,Mapping} abstract base class now
returns @ref{7bc,,NotImplemented} if a mapping is compared to
another type that isn't a @code{Mapping}.
(Fixed by Daniel Stutzbach; bpo-8729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8729}.)

@item 
Constructors for the parsing classes in the @ref{22,,ConfigParser} module now
take an `allow_no_value' parameter, defaulting to false; if true,
options without values will be allowed.  For example:

@example
>>> import ConfigParser, StringIO
>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-bdb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(StringIO.StringIO(sample_config))
>>> config.get('mysqld', 'user')
'mysql'
>>> print config.get('mysqld', 'skip-bdb')
None
>>> print config.get('mysqld', 'unknown')
Traceback (most recent call last):
  ...
NoOptionError: No option 'unknown' in section: 'mysqld'
@end example

(Contributed by Mats Kindahl; bpo-7005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7005}.)

@item 
Deprecated function: @code{contextlib.nested()}, which allows
handling more than one context manager with a single @ref{5bc,,with}
statement, has been deprecated, because the @code{with} statement
now supports multiple context managers.

@item 
The @ref{6f,,cookielib} module now ignores cookies that have an invalid
version field, one that doesn't contain an integer value.  (Fixed by
John J. Lee; bpo-3924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3924}.)

@item 
The @ref{25,,copy} module's @ref{b5c,,deepcopy()} function will now
correctly copy bound instance methods.  (Implemented by
Robert Collins; bpo-1515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1515}.)

@item 
The @ref{2a,,ctypes} module now always converts @code{None} to a C @code{NULL}
pointer for arguments declared as pointers.  (Changed by Thomas
Heller; bpo-4606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4606}.)  The underlying libffi library@footnote{https://sourceware.org/libffi/} has been updated to version
3.0.9, containing various fixes for different platforms.  (Updated
by Matthias Klose; bpo-8142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8142}.)

@item 
New method: the @ref{30,,datetime} module's @ref{9bd,,timedelta} class
gained a @ref{12e4,,total_seconds()} method that returns the
number of seconds in the duration.  (Contributed by Brian Quinlan; bpo-5788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5788}.)

@item 
New method: the @ref{29a,,Decimal} class gained a
@ref{11e1,,from_float()} class method that performs an exact
conversion of a floating-point number to a @code{Decimal}.
This exact conversion strives for the
closest decimal approximation to the floating-point representation's value;
the resulting decimal value will therefore still include the inaccuracy,
if any.
For example, @code{Decimal.from_float(0.1)} returns
@code{Decimal('0.1000000000000000055511151231257827021181583404541015625')}.
(Implemented by Raymond Hettinger; bpo-4796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4796}.)

Comparing instances of @ref{29a,,Decimal} with floating-point
numbers now produces sensible results based on the numeric values
of the operands.  Previously such comparisons would fall back to
Python's default rules for comparing objects, which produced arbitrary
results based on their type.  Note that you still cannot combine
@code{Decimal} and floating point in other operations such as addition,
since you should be explicitly choosing how to convert between float and
@code{Decimal}.  (Fixed by Mark Dickinson; bpo-2531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2531}.)

The constructor for @ref{29a,,Decimal} now accepts
floating-point numbers (added by Raymond Hettinger; bpo-8257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8257})
and non-European Unicode characters such as Arabic-Indic digits
(contributed by Mark Dickinson; bpo-6595@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6595}).

Most of the methods of the @ref{1091,,Context} class now accept integers
as well as @ref{29a,,Decimal} instances; the only exceptions are the
@ref{12e5,,canonical()} and @ref{12e6,,is_canonical()}
methods.  (Patch by Juan José Conti; bpo-7633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7633}.)

When using @ref{29a,,Decimal} instances with a string's
@ref{60c,,format()} method, the default alignment was previously
left-alignment.  This has been changed to right-alignment, which is
more sensible for numeric types.  (Changed by Mark Dickinson; bpo-6857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6857}.)

Comparisons involving a signaling NaN value (or @code{sNAN}) now signal
@ref{108c,,InvalidOperation} instead of silently returning a true or
false value depending on the comparison operator.  Quiet NaN values
(or @code{NaN}) are now hashable.  (Fixed by Mark Dickinson;
bpo-7279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7279}.)

@item 
The @ref{37,,difflib} module now produces output that is more
compatible with modern @code{diff}/@code{patch} tools
through one small change, using a tab character instead of spaces as
a separator in the header giving the filename.  (Fixed by Anatoly
Techtonik; bpo-7585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7585}.)

@item 
The Distutils @code{sdist} command now always regenerates the
@code{MANIFEST} file, since even if the @code{MANIFEST.in} or
@code{setup.py} files haven't been modified, the user might have
created some new files that should be included.
(Fixed by Tarek Ziadé; bpo-8688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8688}.)

@item 
The @ref{3a,,doctest} module's @ref{12e7,,IGNORE_EXCEPTION_DETAIL} flag
will now ignore the name of the module containing the exception
being tested.  (Patch by Lennart Regebro; bpo-7490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7490}.)

@item 
The @ref{3b,,email} module's @ref{279,,Message} class will
now accept a Unicode-valued payload, automatically converting the
payload to the encoding specified by @code{output_charset}.
(Added by R. David Murray; bpo-1368247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1368247}.)

@item 
The @ref{1e4,,Fraction} class now accepts a single float or
@ref{29a,,Decimal} instance, or two rational numbers, as
arguments to its constructor.  (Implemented by Mark Dickinson;
rationals added in bpo-5812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5812}, and float/decimal in
bpo-8294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8294}.)

Ordering comparisons (@code{<}, @code{<=}, @code{>}, @code{>=}) between
fractions and complex numbers now raise a @ref{522,,TypeError}.
This fixes an oversight, making the @ref{1e4,,Fraction}
match the other numeric types.

@c revision 79455

@item 
New class: @ref{8e8,,FTP_TLS} in
the @ref{5d,,ftplib} module provides secure FTP
connections using TLS encapsulation of authentication as well as
subsequent control and data transfers.
(Contributed by Giampaolo Rodola; bpo-2054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2054}.)

The @ref{12e8,,storbinary()} method for binary uploads can now restart
uploads thanks to an added `rest' parameter (patch by Pablo Mouzo;
bpo-6845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6845}.)

@item 
New class decorator: @ref{f2d,,total_ordering()} in the @ref{5e,,functools}
module takes a class that defines an @ref{ae8,,__eq__()} method and one of
@ref{127d,,__lt__()}, @ref{12e9,,__le__()}, @ref{12ea,,__gt__()}, or @ref{12eb,,__ge__()},
and generates the missing comparison methods.  Since the
@code{__cmp__()} method is being deprecated in Python 3.x,
this decorator makes it easier to define ordered classes.
(Added by Raymond Hettinger; bpo-5479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5479}.)

New function: @ref{11b7,,cmp_to_key()} will take an old-style comparison
function that expects two arguments and return a new callable that
can be used as the `key' parameter to functions such as
@ref{bbc,,sorted()}, @ref{ef3,,min()} and @ref{ef4,,max()}, etc.  The primary
intended use is to help with making code compatible with Python 3.x.
(Added by Raymond Hettinger.)

@item 
New function: the @ref{5f,,gc} module's @ref{12ec,,is_tracked()} returns
true if a given instance is tracked by the garbage collector, false
otherwise. (Contributed by Antoine Pitrou; bpo-4688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4688}.)

@item 
The @ref{66,,gzip} module's @ref{410,,GzipFile} now supports the context
management protocol, so you can write @code{with gzip.GzipFile(...) as f:}
(contributed by Hagen Fürstenau; bpo-3860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3860}), and it now implements
the @ref{67f,,io.BufferedIOBase} ABC, so you can wrap it with
@ref{11eb,,io.BufferedReader} for faster processing
(contributed by Nir Aides; bpo-7471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7471}).
It's also now possible to override the modification time
recorded in a gzipped file by providing an optional timestamp to
the constructor.  (Contributed by Jacques Frechet; bpo-4272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4272}.)

Files in gzip format can be padded with trailing zero bytes; the
@ref{66,,gzip} module will now consume these trailing bytes.  (Fixed by
Tadek Pietraszek and Brian Curtin; bpo-2846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2846}.)

@item 
New attribute: the @ref{67,,hashlib} module now has an @code{algorithms}
attribute containing a tuple naming the supported algorithms.
In Python 2.7, @code{hashlib.algorithms} contains
@code{('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')}.
(Contributed by Carl Chenet; bpo-7418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7418}.)

@item 
The default @ref{10b0,,HTTPResponse} class used by the @ref{6d,,httplib} module now
supports buffering, resulting in much faster reading of HTTP responses.
(Contributed by Kristján Valur Jónsson; bpo-4879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4879}.)

The @ref{b2e,,HTTPConnection} and @ref{b2f,,HTTPSConnection} classes
now support a `source_address' parameter, a @code{(host, port)} 2-tuple
giving the source address that will be used for the connection.
(Contributed by Eldon Ziegler; bpo-3972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3972}.)

@item 
The @code{ihooks} module now supports relative imports.  Note that
@code{ihooks} is an older module for customizing imports,
superseded by the @code{imputil} module added in Python 2.0.
(Relative import support added by Neil Schemenauer.)

@c revision 75423

@item 
The @ref{73,,imaplib} module now supports IPv6 addresses.
(Contributed by Derek Morr; bpo-1655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1655}.)

@item 
New function: the @ref{7d,,inspect} module's @ref{ea6,,getcallargs()}
takes a callable and its positional and keyword arguments,
and figures out which of the callable's parameters will receive each argument,
returning a dictionary mapping argument names to their values.  For example:

@example
>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
...
>>> getcallargs(f, 1, 2, 3)
@{'a': 1, 'b': 2, 'pos': (3,), 'named': @{@}@}
>>> getcallargs(f, a=2, x=4)
@{'a': 2, 'b': 1, 'pos': (), 'named': @{'x': 4@}@}
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() takes at least 1 argument (0 given)
@end example

Contributed by George Sakkis; bpo-3135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3135}.

@item 
Updated module: The @ref{7e,,io} library has been upgraded to the version shipped with
Python 3.1.  For 3.1, the I/O library was entirely rewritten in C
and is 2 to 20 times faster depending on the task being performed.  The
original Python version was renamed to the @code{_pyio} module.

One minor resulting change: the @ref{680,,io.TextIOBase} class now
has an @ref{12ed,,errors} attribute giving the error setting
used for encoding and decoding errors (one of @code{'strict'}, @code{'replace'},
@code{'ignore'}).

The @ref{12ee,,io.FileIO} class now raises an @ref{40d,,OSError} when passed
an invalid file descriptor.  (Implemented by Benjamin Peterson;
bpo-4991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4991}.)  The @ref{12ef,,truncate()} method now preserves the
file position; previously it would change the file position to the
end of the new file.  (Fixed by Pascal Chambon; bpo-6939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6939}.)

@item 
New function: @code{itertools.compress(data, selectors)} takes two
iterators.  Elements of `data' are returned if the corresponding
value in `selectors' is true:

@example
itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
  A, C, E, F
@end example

@c maybe here is better to use >>> list(itertools.compress(...)) instead

New function: @code{itertools.combinations_with_replacement(iter, r)}
returns all the possible `r'-length combinations of elements from the
iterable `iter'.  Unlike @ref{12f0,,combinations()}, individual elements
can be repeated in the generated combinations:

@example
itertools.combinations_with_replacement('abc', 2) =>
  ('a', 'a'), ('a', 'b'), ('a', 'c'),
  ('b', 'b'), ('b', 'c'), ('c', 'c')
@end example

Note that elements are treated as unique depending on their position
in the input, not their actual values.

The @ref{1261,,itertools.count()} function now has a `step' argument that
allows incrementing by values other than 1.  @ref{1261,,count()} also
now allows keyword arguments, and using non-integer values such as
floats or @ref{29a,,Decimal} instances.  (Implemented by Raymond
Hettinger; bpo-5032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5032}.)

@ref{12f0,,itertools.combinations()} and @ref{12f1,,itertools.product()}
previously raised @ref{1ff,,ValueError} for values of `r' larger than
the input iterable.  This was deemed a specification error, so they
now return an empty iterator.  (Fixed by Raymond Hettinger; bpo-4816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4816}.)

@item 
Updated module: The @ref{81,,json} module was upgraded to version 2.0.9 of the
simplejson package, which includes a C extension that makes
encoding and decoding faster.
(Contributed by Bob Ippolito; bpo-4136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4136}.)

To support the new @ref{5c5,,collections.OrderedDict} type, @ref{ca2,,json.load()}
now has an optional `object_pairs_hook' parameter that will be called
with any object literal that decodes to a list of pairs.
(Contributed by Raymond Hettinger; bpo-5381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5381}.)

@item 
The @ref{8a,,mailbox} module's @ref{412,,Maildir} class now records the
timestamp on the directories it reads, and only re-reads them if the
modification time has subsequently changed.  This improves
performance by avoiding unneeded directory scans.  (Fixed by
A.M. Kuchling and Antoine Pitrou; bpo-1607951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1607951}, bpo-6896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6896}.)

@item 
New functions: the @ref{8d,,math} module gained
@ref{bc6,,erf()} and @ref{bc7,,erfc()} for the error function and the complementary error function,
@ref{11c9,,expm1()} which computes @code{e**x - 1} with more precision than
using @ref{12f2,,exp()} and subtracting 1,
@ref{11ca,,gamma()} for the Gamma function, and
@ref{11cb,,lgamma()} for the natural log of the Gamma function.
(Contributed by Mark Dickinson and nirinA raseliarison; bpo-3366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3366}.)

@item 
The @ref{93,,multiprocessing} module's @code{Manager*} classes
can now be passed a callable that will be called whenever
a subprocess is started, along with a set of arguments that will be
passed to the callable.
(Contributed by lekma; bpo-5585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5585}.)

The @ref{f56,,Pool} class, which controls a pool of worker processes,
now has an optional `maxtasksperchild' parameter.  Worker processes
will perform the specified number of tasks and then exit, causing the
@code{Pool} to start a new worker.  This is useful if tasks may leak
memory or other resources, or if some tasks will cause the worker to
become very large.
(Contributed by Charles Cazabon; bpo-6963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6963}.)

@item 
The @code{nntplib} module now supports IPv6 addresses.
(Contributed by Derek Morr; bpo-1664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1664}.)

@item 
New functions: the @ref{a0,,os} module wraps the following POSIX system
calls: @ref{12f3,,getresgid()} and @ref{12f4,,getresuid()}, which return the
real, effective, and saved GIDs and UIDs;
@ref{12f5,,setresgid()} and @ref{12f6,,setresuid()}, which set
real, effective, and saved GIDs and UIDs to new values;
@ref{12f7,,initgroups()}, which initialize the group access list
for the current process.  (GID/UID functions
contributed by Travis H.; bpo-6508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6508}.  Support for initgroups added
by Jean-Paul Calderone; bpo-7333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7333}.)

The @ref{195,,os.fork()} function now re-initializes the import lock in
the child process; this fixes problems on Solaris when @ref{195,,fork()}
is called from a thread.  (Fixed by Zsolt Cserna; bpo-7242@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7242}.)

@item 
In the @ref{a1,,os.path} module, the @ref{12f8,,normpath()} and
@ref{12f9,,abspath()} functions now preserve Unicode; if their input path
is a Unicode string, the return value is also a Unicode string.
(@ref{12f8,,normpath()} fixed by Matt Giuca in bpo-5827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5827};
@ref{12f9,,abspath()} fixed by Ezio Melotti in bpo-3426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3426}.)

@item 
The @ref{b4,,pydoc} module now has help for the various symbols that Python
uses.  You can now do @code{help('<<')} or @code{help('@@')}, for example.
(Contributed by David Laban; bpo-4739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4739}.)

@item 
The @ref{b8,,re} module's @ref{29f,,split()}, @ref{2a0,,sub()}, and @ref{2a1,,subn()}
now accept an optional `flags' argument, for consistency with the
other functions in the module.  (Added by Gregory P. Smith.)

@item 
New function: @ref{17f,,run_path()} in the @ref{bd,,runpy} module
will execute the code at a provided `path' argument.  `path' can be
the path of a Python source file (@code{example.py}), a compiled
bytecode file (@code{example.pyc}), a directory
(@code{./package/}), or a zip archive (@code{example.zip}).  If a
directory or zip path is provided, it will be added to the front of
@code{sys.path} and the module @ref{1,,__main__} will be imported.  It's
expected that the directory or zip contains a @code{__main__.py};
if it doesn't, some other @code{__main__.py} might be imported from
a location later in @code{sys.path}.  This makes more of the machinery
of @ref{bd,,runpy} available to scripts that want to mimic the way
Python's command line processes an explicit path name.
(Added by Nick Coghlan; bpo-6816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6816}.)

@item 
New function: in the @ref{c4,,shutil} module, @ref{49c,,make_archive()}
takes a filename, archive type (zip or tar-format), and a directory
path, and creates an archive containing the directory's contents.
(Added by Tarek Ziadé.)

@ref{c4,,shutil}'s @ref{a47,,copyfile()} and @ref{a17,,copytree()}
functions now raise a @code{SpecialFileError} exception when
asked to copy a named pipe.  Previously the code would treat
named pipes like a regular file by opening them for reading, and
this would block indefinitely.  (Fixed by Antoine Pitrou; bpo-3002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3002}.)

@item 
The @ref{c5,,signal} module no longer re-installs the signal handler
unless this is truly necessary, which fixes a bug that could make it
impossible to catch the EINTR signal robustly.  (Fixed by
Charles-Francois Natali; bpo-8354@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8354}.)

@item 
New functions: in the @ref{c6,,site} module, three new functions
return various site- and user-specific paths.
@ref{121c,,getsitepackages()} returns a list containing all
global site-packages directories,
@ref{121e,,getusersitepackages()} returns the path of the user's
site-packages directory, and
@ref{121d,,getuserbase()} returns the value of the @ref{12fa,,USER_BASE}
environment variable, giving the path to a directory that can be used
to store data.
(Contributed by Tarek Ziadé; bpo-6693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6693}.)

The @ref{c6,,site} module now reports exceptions occurring
when the @ref{c7,,sitecustomize} module is imported, and will no longer
catch and swallow the @ref{9bf,,KeyboardInterrupt} exception.  (Fixed by
Victor Stinner; bpo-3137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3137}.)

@item 
The @ref{65d,,create_connection()} function
gained a `source_address' parameter, a @code{(host, port)} 2-tuple
giving the source address that will be used for the connection.
(Contributed by Eldon Ziegler; bpo-3972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3972}.)

The @ref{12fb,,recv_into()} and @ref{12fc,,recvfrom_into()}
methods will now write into objects that support the buffer API, most usefully
the @ref{528,,bytearray} and @ref{452,,memoryview} objects.  (Implemented by
Antoine Pitrou; bpo-8104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8104}.)

@item 
The @ref{cc,,SocketServer} module's @ref{12fd,,TCPServer} class now
supports socket timeouts and disabling the Nagle algorithm.
The @code{disable_nagle_algorithm} class attribute
defaults to @code{False}; if overridden to be true,
new request connections will have the TCP_NODELAY option set to
prevent buffering many small sends into a single TCP packet.
The @ref{12fe,,timeout} class attribute can hold
a timeout in seconds that will be applied to the request socket; if
no request is received within that time, @ref{12ff,,handle_timeout()}
will be called and @ref{1300,,handle_request()} will return.
(Contributed by Kristján Valur Jónsson; bpo-6192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6192} and bpo-6267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6267}.)

@item 
Updated module: the @ref{ce,,sqlite3} module has been updated to
version 2.6.0 of the pysqlite package@footnote{https://github.com/ghaering/pysqlite}. Version 2.6.0 includes a number of bugfixes, and adds
the ability to load SQLite extensions from shared libraries.
Call the @code{enable_load_extension(True)} method to enable extensions,
and then call @ref{4a1,,load_extension()} to load a particular shared library.
(Updated by Gerhard Häring.)

@item 
The @ref{cf,,ssl} module's @ref{8d7,,SSLSocket} objects now support the
buffer API, which fixed a test suite failure (fix by Antoine Pitrou;
bpo-7133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7133}) and automatically set
OpenSSL's @code{SSL_MODE_AUTO_RETRY}, which will prevent an error
code being returned from @code{recv()} operations that trigger an SSL
renegotiation (fix by Antoine Pitrou; bpo-8222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8222}).

The @ref{50e,,wrap_socket()} constructor function now takes a
`ciphers' argument that's a string listing the encryption algorithms
to be allowed; the format of the string is described
in the OpenSSL documentation@footnote{https://docs.openssl.org/1.0.2/man1/ciphers/}.
(Added by Antoine Pitrou; bpo-8322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8322}.)

Another change makes the extension load all of OpenSSL's ciphers and
digest algorithms so that they're all available.  Some SSL
certificates couldn't be verified, reporting an "unknown algorithm"
error.  (Reported by Beda Kosata, and fixed by Antoine Pitrou;
bpo-8484@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8484}.)

The version of OpenSSL being used is now available as the module
attributes @ref{11fc,,ssl.OPENSSL_VERSION} (a string),
@ref{11fd,,ssl.OPENSSL_VERSION_INFO} (a 5-tuple), and
@ref{11fe,,ssl.OPENSSL_VERSION_NUMBER} (an integer).  (Added by Antoine
Pitrou; bpo-8321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8321}.)

@item 
The @ref{d4,,struct} module will no longer silently ignore overflow
errors when a value is too large for a particular integer format
code (one of @code{bBhHiIlLqQ}); it now always raises a
@ref{1301,,struct.error} exception.  (Changed by Mark Dickinson;
bpo-1523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1523}.)  The @ref{1255,,pack()} function will also
attempt to use @ref{707,,__index__()} to convert and pack non-integers
before trying the @ref{706,,__int__()} method or reporting an error.
(Changed by Mark Dickinson; bpo-8300@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8300}.)

@item 
New function: the @ref{d5,,subprocess} module's
@ref{fac,,check_output()} runs a command with a specified set of arguments
and returns the command's output as a string when the command runs without
error, or raises a @ref{1302,,CalledProcessError} exception otherwise.

@example
>>> subprocess.check_output(['df', '-h', '.'])
'Filesystem     Size   Used  Avail Capacity  Mounted on\n
/dev/disk0s2    52G    49G   3.0G    94%    /\n'

>>> subprocess.check_output(['df', '-h', '/bogus'])
  ...
subprocess.CalledProcessError: Command '['df', '-h', '/bogus']' returned non-zero exit status 1
@end example

(Contributed by Gregory P. Smith.)

The @ref{d5,,subprocess} module will now retry its internal system calls
on receiving an @ref{d74,,EINTR} signal.  (Reported by several people; final
patch by Gregory P. Smith in bpo-1068268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1068268}.)

@item 
New function: @ref{1303,,is_declared_global()} in the @ref{d7,,symtable} module
returns true for variables that are explicitly declared to be global,
false for ones that are implicitly global.
(Contributed by Jeremy Hylton.)

@item 
The @ref{db,,syslog} module will now use the value of @code{sys.argv[0]} as the
identifier instead of the previous default value of @code{'python'}.
(Changed by Sean Reifschneider; bpo-8451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8451}.)

@item 
The @ref{68b,,sys.version_info} value is now a named tuple, with attributes
named @code{major}, @code{minor}, @code{micro},
@code{releaselevel}, and @code{serial}.  (Contributed by Ross
Light; bpo-4285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4285}.)

@ref{cd5,,sys.getwindowsversion()} also returns a named tuple,
with attributes named @code{major}, @code{minor}, @code{build},
@code{platform}, @code{service_pack}, @code{service_pack_major},
@code{service_pack_minor}, @code{suite_mask}, and
@code{product_type}.  (Contributed by Brian Curtin; bpo-7766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7766}.)

@item 
The @ref{dd,,tarfile} module's default error handling has changed, to
no longer suppress fatal errors.  The default error level was previously 0,
which meant that errors would only result in a message being written to the
debug log, but because the debug log is not activated by default,
these errors go unnoticed.  The default error level is now 1,
which raises an exception if there's an error.
(Changed by Lars Gustäbel; bpo-7357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7357}.)

@ref{dd,,tarfile} now supports filtering the @ref{11ee,,TarInfo}
objects being added to a tar file.  When you call @ref{be1,,add()},
you may supply an optional `filter' argument
that's a callable.  The `filter' callable will be passed the
@ref{11ee,,TarInfo} for every file being added, and can modify and return it.
If the callable returns @code{None}, the file will be excluded from the
resulting archive.  This is more powerful than the existing
`exclude' argument, which has therefore been deprecated.
(Added by Lars Gustäbel; bpo-6856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6856}.)
The @ref{11ed,,TarFile} class also now supports the context management protocol.
(Added by Lars Gustäbel; bpo-7232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7232}.)

@item 
The @ref{1304,,wait()} method of the @ref{1138,,threading.Event} class
now returns the internal flag on exit.  This means the method will usually
return true because @ref{1304,,wait()} is supposed to block until the
internal flag becomes true.  The return value will only be false if
a timeout was provided and the operation timed out.
(Contributed by Tim Lesher; bpo-1674032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1674032}.)

@item 
The Unicode database provided by the @ref{104,,unicodedata} module is
now used internally to determine which characters are numeric,
whitespace, or represent line breaks.  The database also
includes information from the @code{Unihan.txt} data file (patch
by Anders Chrigström and Amaury Forgeot d'Arc; bpo-1571184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1571184})
and has been updated to version 5.2.0 (updated by
Florent Xicluna; bpo-8024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8024}).

@item 
The @ref{109,,urlparse} module's @ref{d2d,,urlsplit()} now handles
unknown URL schemes in a fashion compliant with 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}: if the
URL is of the form @code{"<something>://..."}, the text before the
@code{://} is treated as the scheme, even if it's a made-up scheme that
the module doesn't know about.  This change may break code that
worked around the old behaviour.  For example, Python 2.6.4 or 2.5
will return the following:

@example
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '@w{'}, '//host/filename?query', '@w{'}, '@w{'})
@end example

Python 2.7 (and Python 2.6.5) will return:

@example
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '@w{'}, '@w{'})
@end example

(Python 2.7 actually produces slightly different output, since it
returns a named tuple instead of a standard tuple.)

The @ref{109,,urlparse} module also supports IPv6 literal addresses as defined by
@geindex RFC; RFC 2732
RFC 2732@footnote{https://datatracker.ietf.org/doc/html/rfc2732.html} (contributed by Senthil Kumaran; bpo-2987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2987}).

@example
>>> urlparse.urlparse('http://[1080::8:800:200C:417A]/foo')
ParseResult(scheme='http', netloc='[1080::8:800:200C:417A]',
            path='/foo', params='@w{'}, query='@w{'}, fragment='@w{'})
@end example

@item 
New class: the @ref{5c7,,WeakSet} class in the @ref{113,,weakref}
module is a set that only holds weak references to its elements; elements
will be removed once there are no references pointing to them.
(Originally implemented in Python 3.x by Raymond Hettinger, and backported
to 2.7 by Michael Foord.)

@item 
The @ref{124,,xml.etree.ElementTree} library, no longer escapes
ampersands and angle brackets when outputting an XML processing
instruction (which looks like @code{<?xml-stylesheet href="#style1"?>})
or comment (which looks like @code{<!-- comment -->}).
(Patch by Neil Muller; bpo-2746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2746}.)

@item 
The XML-RPC client and server, provided by the @ref{12d,,xmlrpclib} and
@ref{12e,,SimpleXMLRPCServer} modules, have improved performance by
supporting HTTP/1.1 keep-alive and by optionally using gzip encoding
to compress the XML being exchanged.  The gzip compression is
controlled by the @code{encode_threshold} attribute of
@ref{1305,,SimpleXMLRPCRequestHandler}, which contains a size in bytes;
responses larger than this will be compressed.
(Contributed by Kristján Valur Jónsson; bpo-6267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6267}.)

@item 
The @ref{130,,zipfile} module's @ref{6af,,ZipFile} now supports the context
management protocol, so you can write @code{with zipfile.ZipFile(...) as f:}.
(Contributed by Brian Curtin; bpo-5511@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5511}.)

@ref{130,,zipfile} now also supports archiving empty directories and
extracts them correctly.  (Fixed by Kuba Wieczorek; bpo-4710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4710}.)
Reading files out of an archive is faster, and interleaving
@ref{1306,,read()} and
@ref{1307,,readline()} now works correctly.
(Contributed by Nir Aides; bpo-7610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7610}.)

The @ref{1308,,is_zipfile()} function now
accepts a file object, in addition to the path names accepted in earlier
versions.  (Contributed by Gabriel Genellina; bpo-4756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4756}.)

The @ref{1309,,writestr()} method now has an optional `compress_type' parameter
that lets you override the default compression method specified in the
@ref{6af,,ZipFile} constructor.  (Contributed by Ronald Oussoren;
bpo-6003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6003}.)
@end itemize

@c ======================================================================

@c whole new modules get described in subsections here

@menu
* New module; importlib: New module importlib. 
* New module; sysconfig: New module sysconfig. 
* ttk; Themed Widgets for Tk: ttk Themed Widgets for Tk. 
* Updated module; unittest: Updated module unittest. 
* Module mis-à-jour ; ElementTree 1.3: Module mis-à-jour ElementTree 1 3. 

@end menu

@node New module importlib,New module sysconfig,,New and Improved Modules
@anchor{whatsnew/2 7 importlib-section}@anchor{12c9}@anchor{whatsnew/2 7 new-module-importlib}@anchor{130a}
@subsubsection New module: importlib


Python 3.1 includes the @ref{76,,importlib} package, a re-implementation
of the logic underlying Python's @ref{5cc,,import} statement.
@ref{76,,importlib} is useful for implementers of Python interpreters and
to users who wish to write new importers that can participate in the
import process.  Python 2.7 doesn't contain the complete
@ref{76,,importlib} package, but instead has a tiny subset that contains
a single function, @ref{501,,import_module()}.

@code{import_module(name, package=None)} imports a module.  `name' is
a string containing the module or package's name.  It's possible to do
relative imports by providing a string that begins with a @code{.}
character, such as @code{..utils.errors}.  For relative imports, the
`package' argument must be provided and is the name of the package that
will be used as the anchor for
the relative import.  @ref{501,,import_module()} both inserts the imported
module into @code{sys.modules} and returns the module object.

Voici quelques exemples :

@example
>>> from importlib import import_module
>>> anydbm = import_module('anydbm')  # Standard absolute import
>>> anydbm
<module 'anydbm' from '/p/python/Lib/anydbm.py'>
>>> # Relative import
>>> file_util = import_module('..file_util', 'distutils.command')
>>> file_util
<module 'distutils.file_util' from '/python/Lib/distutils/file_util.pyc'>
@end example

@ref{76,,importlib} was implemented by Brett Cannon and introduced in
Python 3.1.

@node New module sysconfig,ttk Themed Widgets for Tk,New module importlib,New and Improved Modules
@anchor{whatsnew/2 7 new-module-sysconfig}@anchor{130b}
@subsubsection New module: sysconfig


The @ref{da,,sysconfig} module has been pulled out of the Distutils
package, becoming a new top-level module in its own right.
@ref{da,,sysconfig} provides functions for getting information about
Python's build process: compiler switches, installation paths, the
platform name, and whether Python is running from its source
directory.

Some of the functions in the module are:


@itemize *

@item 
@ref{1014,,get_config_var()} returns variables from Python's
Makefile and the @code{pyconfig.h} file.

@item 
@ref{1015,,get_config_vars()} returns a dictionary containing
all of the configuration variables.

@item 
@ref{130c,,get_path()} returns the configured path for
a particular type of module: the standard library,
site-specific modules, platform-specific modules, etc.

@item 
@ref{2f7,,is_python_build()} returns true if you're running a
binary from a Python source tree, and false otherwise.
@end itemize

Consult the @ref{da,,sysconfig} documentation for more details and for
a complete list of functions.

The Distutils package and @ref{da,,sysconfig} are now maintained by Tarek
Ziadé, who has also started a Distutils2 package (source repository at
@indicateurl{https://hg.python.org/distutils2/}) for developing a next-generation
version of Distutils.

@node ttk Themed Widgets for Tk,Updated module unittest,New module sysconfig,New and Improved Modules
@anchor{whatsnew/2 7 ttk-themed-widgets-for-tk}@anchor{130d}
@subsubsection ttk: Themed Widgets for Tk


Tcl/Tk 8.5 includes a set of themed widgets that re-implement basic Tk
widgets but have a more customizable appearance and can therefore more
closely resemble the native platform's widgets.  This widget
set was originally called Tile, but was renamed to Ttk (for "themed Tk")
on being added to Tcl/Tck release 8.5.

To learn more, read the @ref{f8,,ttk} module documentation.  You may also
wish to read the Tcl/Tk manual page describing the
Ttk theme engine, available at
@indicateurl{https://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.html}. Some
screenshots of the Python/Ttk code in use are at
@indicateurl{https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki}.

The @ref{f8,,tkinter.ttk} module was written by Guilherme Polo and added in
bpo-2983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2983}.  An alternate version called @code{Tile.py}, written by
Martin Franklin and maintained by Kevin Walzer, was proposed for
inclusion in bpo-2618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2618}, but the authors argued that Guilherme
Polo's work was more comprehensive.

@node Updated module unittest,Module mis-à-jour ElementTree 1 3,ttk Themed Widgets for Tk,New and Improved Modules
@anchor{whatsnew/2 7 unittest-section}@anchor{130e}@anchor{whatsnew/2 7 updated-module-unittest}@anchor{130f}
@subsubsection Updated module: unittest


The @ref{105,,unittest} module was greatly enhanced; many
new features were added.  Most of these features were implemented
by Michael Foord, unless otherwise noted.  The enhanced version of
the module is downloadable separately for use with Python versions 2.4 to 2.6,
packaged as the @code{unittest2} package, from unittest2@footnote{https://pypi.org/project/unittest2/}.

When used from the command line, the module can automatically discover
tests.  It's not as fancy as py.test@footnote{https://pytest.org} or
nose@footnote{https://nose.readthedocs.io/}, but provides a
simple way to run tests kept within a set of package directories.  For example,
the following command will search the @code{test/} subdirectory for
any importable test files named @code{test*.py}:

@example
python -m unittest discover -s test
@end example

Consult the @ref{105,,unittest} module documentation for more details.
(Developed in bpo-6001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6001}.)

The @ref{fce,,main()} function supports some other new options:


@itemize *

@item 
@ref{1310,,-b} or @code{--buffer} will buffer the standard output
and standard error streams during each test.  If the test passes,
any resulting output will be discarded; on failure, the buffered
output will be displayed.

@item 
@ref{1311,,-c} or @code{--catch} will cause the control-C interrupt
to be handled more gracefully.  Instead of interrupting the test
process immediately, the currently running test will be completed
and then the partial results up to the interruption will be reported.
If you're impatient, a second press of control-C will cause an immediate
interruption.

This control-C handler tries to avoid causing problems when the code
being tested or the tests being run have defined a signal handler of
their own, by noticing that a signal handler was already set and
calling it.  If this doesn't work for you, there's a
@ref{1312,,removeHandler()} decorator that can be used to mark tests that
should have the control-C handling disabled.

@item 
@ref{1313,,-f} or @code{--failfast} makes
test execution stop immediately when a test fails instead of
continuing to execute further tests.  (Suggested by Cliff Dyer and
implemented by Michael Foord; bpo-8074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8074}.)
@end itemize

The progress messages now show 'x' for expected failures
and 'u' for unexpected successes when run in verbose mode.
(Contributed by Benjamin Peterson.)

Test cases can raise the @ref{fcf,,SkipTest} exception to skip a
test (bpo-1034053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1034053}).

The error messages for @ref{512,,assertEqual()},
@ref{510,,assertTrue()}, and @ref{511,,assertFalse()}
failures now provide more information.  If you set the
@ref{1314,,longMessage} attribute of your @ref{437,,TestCase} classes to
true, both the standard error message and any additional message you
provide will be printed for failures.  (Added by Michael Foord; bpo-5663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5663}.)

The @ref{516,,assertRaises()} method now
returns a context handler when called without providing a callable
object to run.  For example, you can write this:

@example
with self.assertRaises(KeyError):
    @{@}['foo']
@end example

(Implemented by Antoine Pitrou; bpo-4444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4444}.)

@c rev 78774

Module- and class-level setup and teardown fixtures are now supported.
Modules can contain @code{setUpModule()} and @code{tearDownModule()}
functions.  Classes can have @ref{a3d,,setUpClass()} and
@ref{1315,,tearDownClass()} methods that must be defined as class methods
(using @code{@@classmethod} or equivalent).  These functions and
methods are invoked when the test runner switches to a test case in a
different module or class.

The methods @ref{a6f,,addCleanup()} and
@ref{1316,,doCleanups()} were added.
@ref{a6f,,addCleanup()} lets you add cleanup functions that
will be called unconditionally (after @ref{1317,,setUp()} if
@ref{1317,,setUp()} fails, otherwise after @ref{1318,,tearDown()}). This allows
for much simpler resource allocation and deallocation during tests
(bpo-5679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5679}).

A number of new methods were added that provide more specialized
tests.  Many of these methods were written by Google engineers
for use in their test suites; Gregory P. Smith, Michael Foord, and
GvR worked on merging them into Python's version of @ref{105,,unittest}.


@itemize *

@item 
@ref{1268,,assertIsNone()} and @ref{1269,,assertIsNotNone()} take one
expression and verify that the result is or is not @code{None}.

@item 
@ref{1319,,assertIs()} and @ref{131a,,assertIsNot()}
take two values and check whether the two values evaluate to the same object or not.
(Added by Michael Foord; bpo-2578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2578}.)

@item 
@ref{131b,,assertIsInstance()} and
@ref{131c,,assertNotIsInstance()} check whether
the resulting object is an instance of a particular class, or of
one of a tuple of classes.  (Added by Georg Brandl; bpo-7031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7031}.)

@item 
@ref{131d,,assertGreater()}, @ref{131e,,assertGreaterEqual()},
@ref{131f,,assertLess()}, and @ref{1320,,assertLessEqual()} compare
two quantities.

@item 
@ref{1321,,assertMultiLineEqual()} compares two strings, and if they're
not equal, displays a helpful comparison that highlights the
differences in the two strings.  This comparison is now used by
default when Unicode strings are compared with @ref{512,,assertEqual()}.

@item 
@ref{517,,assertRegexpMatches()} and
@ref{519,,assertNotRegexpMatches()} checks whether the
first argument is a string matching or not matching the regular
expression provided as the second argument (bpo-8038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8038}).

@item 
@ref{518,,assertRaisesRegexp()} checks
whether a particular exception
is raised, and then also checks that the string representation of
the exception matches the provided regular expression.

@item 
@ref{1322,,assertIn()} and @ref{1323,,assertNotIn()}
tests whether `first' is or is not in  `second'.

@item 
@ref{1208,,assertItemsEqual()} tests whether two provided sequences
contain the same elements.

@item 
@ref{1263,,assertSetEqual()} compares whether two sets are equal, and
only reports the differences between the sets in case of error.

@item 
Similarly, @ref{1265,,assertListEqual()} and @ref{1266,,assertTupleEqual()}
compare the specified types and explain any differences without necessarily
printing their full values; these methods are now used by default
when comparing lists and tuples using @ref{512,,assertEqual()}.
More generally, @ref{1267,,assertSequenceEqual()} compares two sequences
and can optionally check whether both sequences are of a
particular type.

@item 
@ref{1264,,assertDictEqual()} compares two dictionaries and reports the
differences; it's now used by default when you compare two dictionaries
using @ref{512,,assertEqual()}.  @code{assertDictContainsSubset()} checks whether
all of the key/value pairs in `first' are found in `second'.

@item 
@ref{514,,assertAlmostEqual()} and @ref{515,,assertNotAlmostEqual()} test
whether `first' and `second' are approximately equal.  This method
can either round their difference to an optionally specified number
of `places' (the default is 7) and compare it to zero, or require
the difference to be smaller than a supplied `delta' value.

@item 
@ref{1324,,loadTestsFromName()} properly honors the
@ref{1325,,suiteClass} attribute of
the @ref{28b,,TestLoader}. (Fixed by Mark Roddy; bpo-6866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6866}.)

@item 
A new hook lets you extend the @ref{512,,assertEqual()} method to handle
new data types.  The @ref{1326,,addTypeEqualityFunc()} method takes a type
object and a function. The function will be used when both of the
objects being compared are of the specified type.  This function
should compare the two objects and raise an exception if they don't
match; it's a good idea for the function to provide additional
information about why the two objects aren't matching, much as the new
sequence comparison methods do.
@end itemize

@ref{fce,,unittest.main()} now takes an optional @code{exit} argument.  If
false, @ref{fce,,main()} doesn't call @ref{1327,,sys.exit()}, allowing
@ref{fce,,main()} to be used from the interactive interpreter.
(Contributed by J. Pablo Fernández; bpo-3379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3379}.)

@ref{1147,,TestResult} has new @ref{1328,,startTestRun()} and
@ref{1329,,stopTestRun()} methods that are called immediately before
and after a test run.  (Contributed by Robert Collins; bpo-5728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5728}.)

With all these changes, the @code{unittest.py} was becoming awkwardly
large, so the module was turned into a package and the code split into
several files (by Benjamin Peterson).  This doesn't affect how the
module is imported or used.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://web.archive.org/web/20210619163128/http://www.voidspace.org.uk/python/articles/unittest2.shtml}

Describes the new features, how to use them, and the
rationale for various design decisions.  (By Michael Foord.)
@end table


@node Module mis-à-jour ElementTree 1 3,,Updated module unittest,New and Improved Modules
@anchor{whatsnew/2 7 elementtree-section}@anchor{132a}@anchor{whatsnew/2 7 updated-module-elementtree-1-3}@anchor{132b}
@subsubsection Module mis-à-jour : ElementTree 1.3


The version of the ElementTree library included with Python was updated to
version 1.3.  Some of the new features are:


@itemize *

@item 
The various parsing functions now take a `parser' keyword argument
giving an @ref{a42,,XMLParser} instance that will
be used.  This makes it possible to override the file's internal encoding:

@example
p = ET.XMLParser(encoding='utf-8')
t = ET.XML("""<root/>""", parser=p)
@end example

Errors in parsing XML now raise a @ref{1256,,ParseError} exception, whose
instances have a @code{position} attribute
containing a (`line', `column') tuple giving the location of the problem.

@item 
ElementTree's code for converting trees to a string has been
significantly reworked, making it roughly twice as fast in many
cases.  The @ref{fe0,,ElementTree.write()}
and @code{Element.write()} methods now have a `method' parameter that can be
"xml" (the default), "html", or "text".  HTML mode will output empty
elements as @code{<empty></empty>} instead of @code{<empty/>}, and text
mode will skip over elements and only output the text chunks.  If
you set the @ref{132c,,tag} attribute of an
element to @code{None} but
leave its children in place, the element will be omitted when the
tree is written out, so you don't need to do more extensive rearrangement
to remove a single element.

Namespace handling has also been improved.  All @code{xmlns:<whatever>}
declarations are now output on the root element, not scattered throughout
the resulting XML.  You can set the default namespace for a tree
by setting the @code{default_namespace} attribute and can
register new prefixes with @ref{11af,,register_namespace()}.  In XML mode,
you can use the true/false `xml_declaration' parameter to suppress the
XML declaration.

@item 
New @ref{305,,Element} method:
@ref{11b0,,extend()} appends the items from a
sequence to the element's children.  Elements themselves behave like
sequences, so it's easy to move children from one element to
another:

@example
from xml.etree import ElementTree as ET

t = ET.XML("""<list>
  <item>1</item> <item>2</item>  <item>3</item>
</list>""")
new = ET.XML('<root/>')
new.extend(t)

# Outputs <root><item>1</item>...</root>
print ET.tostring(new)
@end example

@item 
New @ref{305,,Element} method:
@ref{132d,,iter()} yields the children of the
element as a generator.  It's also possible to write @code{for child in
elem:} to loop over an element's children.  The existing method
@code{getiterator()} is now deprecated, as is @code{getchildren()}
which constructs and returns a list of children.

@item 
New @ref{305,,Element} method:
@ref{11b2,,itertext()} yields all chunks of
text that are descendants of the element.  For example:

@example
t = ET.XML("""<list>
  <item>1</item> <item>2</item>  <item>3</item>
</list>""")

# Outputs ['\n  ', '1', ' ', '2', '  ', '3', '\n']
print list(t.itertext())
@end example

@item 
Deprecated: using an element as a Boolean (i.e., @code{if elem:}) would
return true if the element had any children, or false if there were
no children.  This behaviour is confusing -- @code{None} is false, but
so is a childless element? -- so it will now trigger a
@ref{40b,,FutureWarning}.  In your code, you should be explicit: write
@code{len(elem) != 0} if you're interested in the number of children,
or @code{elem is not None}.
@end itemize

Fredrik Lundh develops ElementTree and produced the 1.3 version;
you can read his article describing 1.3 at
@indicateurl{https://web.archive.org/web/20200703234532/http://effbot.org/zone/elementtree-13-intro.htm}.
Florent Xicluna updated the version included with
Python, after discussions on python-dev and in bpo-6472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6472}.)

@c ======================================================================

@node Build and C API Changes<8>,Autres changements et corrections,New and Improved Modules,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 build-and-c-api-changes}@anchor{132e}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
The latest release of the GNU Debugger, GDB 7, can be scripted using Python@footnote{https://web.archive.org/web/20110715084810/http://sourceware.org/gdb/current/onlinedocs/gdb/Python.html}.
When you begin debugging an executable program P, GDB will look for
a file named @code{P-gdb.py} and automatically read it.  Dave Malcolm
contributed a @code{python-gdb.py} that adds a number of
commands useful when debugging Python itself.  For example,
@code{py-up} and @code{py-down} go up or down one Python stack frame,
which usually corresponds to several C stack frames.  @code{py-print}
prints the value of a Python variable, and @code{py-bt} prints the
Python stack trace.  (Added as a result of bpo-8032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8032}.)

@item 
If you use the @code{.gdbinit} file provided with Python,
the "pyo" macro in the 2.7 version now works correctly when the thread being
debugged doesn't hold the GIL; the macro now acquires it before printing.
(Contributed by Victor Stinner; bpo-3632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3632}.)

@item 
@ref{96e,,Py_AddPendingCall()} is now thread-safe, letting any
worker thread submit notifications to the main Python thread.  This
is particularly useful for asynchronous IO operations.
(Contributed by Kristján Valur Jónsson; bpo-4293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4293}.)

@item 
New function: @ref{132f,,PyCode_NewEmpty()} creates an empty code object;
only the filename, function name, and first line number are required.
This is useful for extension modules that are attempting to
construct a more useful traceback stack.  Previously such
extensions needed to call @code{PyCode_New()}, which had many
more arguments.  (Added by Jeffrey Yasskin.)

@item 
New function: @ref{1247,,PyErr_NewExceptionWithDoc()} creates a new
exception class, just as the existing @ref{1248,,PyErr_NewException()} does,
but takes an extra @code{char *} argument containing the docstring for the
new exception class.  (Added by 'lekma' on the Python bug tracker;
bpo-7033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7033}.)

@item 
New function: @ref{775,,PyFrame_GetLineNumber()} takes a frame object
and returns the line number that the frame is currently executing.
Previously code would need to get the index of the bytecode
instruction currently executing, and then look up the line number
corresponding to that address.  (Added by Jeffrey Yasskin.)

@item 
New functions: @ref{1245,,PyLong_AsLongAndOverflow()} and
@ref{1244,,PyLong_AsLongLongAndOverflow()}  approximates a Python long
integer as a C long or long long.
If the number is too large to fit into
the output type, an `overflow' flag is set and returned to the caller.
(Contributed by Case Van Horsen; bpo-7528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7528} and bpo-7767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7767}.)

@item 
New function: stemming from the rewrite of string-to-float conversion,
a new @ref{1273,,PyOS_string_to_double()} function was added.  The old
@code{PyOS_ascii_strtod()} and @code{PyOS_ascii_atof()} functions
are now deprecated.

@item 
New function: @code{PySys_SetArgvEx()} sets the value of
@code{sys.argv} and can optionally update @code{sys.path} to include the
directory containing the script named by @code{sys.argv[0]} depending
on the value of an `updatepath' parameter.

This function was added to close a security hole for applications
that embed Python.  The old function, @code{PySys_SetArgv()}, would
always update @code{sys.path}, and sometimes it would add the current
directory.  This meant that, if you ran an application embedding
Python in a directory controlled by someone else, attackers could
put a Trojan-horse module in the directory (say, a file named
@code{os.py}) that your application would then import and run.

If you maintain a C/C++ application that embeds Python, check
whether you're calling @code{PySys_SetArgv()} and carefully consider
whether the application should be using @code{PySys_SetArgvEx()}
with `updatepath' set to false.

Security issue reported as 
@geindex Common Vulnerabilities and Exposures; CVE 2008-5983
CVE 2008-5983@footnote{https://www.cve.org/CVERecord?id=CVE-2008-5983};
discussed in bpo-5753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5753}, and fixed by Antoine Pitrou.

@item 
New macros: the Python header files now define the following macros:
@code{Py_ISALNUM},
@code{Py_ISALPHA},
@code{Py_ISDIGIT},
@code{Py_ISLOWER},
@code{Py_ISSPACE},
@code{Py_ISUPPER},
@code{Py_ISXDIGIT},
@code{Py_TOLOWER}, and @code{Py_TOUPPER}.
All of these functions are analogous to the C
standard macros for classifying characters, but ignore the current
locale setting, because in
several places Python needs to analyze characters in a
locale-independent way.  (Added by Eric Smith;
bpo-5793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5793}.)

@c XXX these macros don't seem to be described in the c-api docs.

@item 
Removed function: @code{PyEval_CallObject()} is now only available
as a macro.  A function version was being kept around to preserve
ABI linking compatibility, but that was in 1997; it can certainly be
deleted by now.  (Removed by Antoine Pitrou; bpo-8276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8276}.)

@item 
New format codes: the @code{PyString_FromFormat()},
@code{PyString_FromFormatV()}, and @ref{e9a,,PyErr_Format()} functions now
accept @code{%lld} and @code{%llu} format codes for displaying
C's long long types.
(Contributed by Mark Dickinson; bpo-7228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7228}.)

@item 
The complicated interaction between threads and process forking has
been changed.  Previously, the child process created by
@ref{195,,os.fork()} might fail because the child is created with only a
single thread running, the thread performing the @ref{195,,os.fork()}.
If other threads were holding a lock, such as Python's import lock,
when the fork was performed, the lock would still be marked as
"held" in the new process.  But in the child process nothing would
ever release the lock, since the other threads weren't replicated,
and the child process would no longer be able to perform imports.

Python 2.7 acquires the import lock before performing an
@ref{195,,os.fork()}, and will also clean up any locks created using the
@ref{ec,,threading} module.  C extension modules that have internal
locks, or that call @code{fork()} themselves, will not benefit
from this clean-up.

(Fixed by Thomas Wouters; bpo-1590864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1590864}.)

@item 
The @ref{1330,,Py_Finalize()} function now calls the internal
@code{threading._shutdown()} function; this prevents some exceptions from
being raised when an interpreter shuts down.
(Patch by Adam Olsen; bpo-1722344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1722344}.)

@item 
When using the @ref{53a,,PyMemberDef} structure to define attributes
of a type, Python will no longer let you try to delete or set a
@code{T_STRING_INPLACE} attribute.

@c rev 79644

@item 
Global symbols defined by the @ref{2a,,ctypes} module are now prefixed
with @code{Py}, or with @code{_ctypes}.  (Implemented by Thomas
Heller; bpo-3102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3102}.)

@item 
New configure option: the @code{--with-system-expat} switch allows
building the @ref{125,,pyexpat} module to use the system Expat library.
(Contributed by Arfrever Frehtes Taifersar Arahesis; bpo-7609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7609}.)

@item 
New configure option: the
@code{--with-valgrind} option will now disable the pymalloc
allocator, which is difficult for the Valgrind memory-error detector
to analyze correctly.
Valgrind will therefore be better at detecting memory leaks and
overruns. (Contributed by James Henstridge; bpo-2422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2422}.)

@item 
New configure option: you can now supply an empty string to
@code{--with-dbmliborder=} in order to disable all of the various
DBM modules.  (Added by Arfrever Frehtes Taifersar Arahesis;
bpo-6491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6491}.)

@item 
The @code{configure} script now checks for floating-point rounding bugs
on certain 32-bit Intel chips and defines a @code{X87_DOUBLE_ROUNDING}
preprocessor definition.  No code currently uses this definition,
but it's available if anyone wishes to use it.
(Added by Mark Dickinson; bpo-2937@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2937}.)

@code{configure} also now sets a 
@geindex LDCXXSHARED
@geindex variable d'environnement; LDCXXSHARED
@code{LDCXXSHARED} Makefile
variable for supporting C++ linking.  (Contributed by Arfrever
Frehtes Taifersar Arahesis; bpo-1222585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1222585}.)

@item 
The build process now creates the necessary files for pkg-config
support.  (Contributed by Clinton Roy; bpo-3585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3585}.)

@item 
The build process now supports Subversion 1.7.  (Contributed by
Arfrever Frehtes Taifersar Arahesis; bpo-6094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6094}.)
@end itemize

@menu
* Capsules:: 
* Port-Specific Changes; Windows: Port-Specific Changes Windows. 
* Port-Specific Changes; Mac OS X: Port-Specific Changes Mac OS X. 
* Port-Specific Changes; FreeBSD: Port-Specific Changes FreeBSD. 

@end menu

@node Capsules,Port-Specific Changes Windows,,Build and C API Changes<8>
@anchor{whatsnew/2 7 capsules}@anchor{1331}@anchor{whatsnew/2 7 whatsnew27-capsules}@anchor{1332}
@subsubsection Capsules


Python 3.1 adds a new C datatype, @ref{1251,,PyCapsule}, for providing a
C API to an extension module.  A capsule is essentially the holder of
a C @code{void *} pointer, and is made available as a module attribute; for
example, the @ref{cb,,socket} module's API is exposed as @code{socket.CAPI},
and @ref{104,,unicodedata} exposes @code{ucnhash_CAPI}.  Other extensions
can import the module, access its dictionary to get the capsule
object, and then get the @code{void *} pointer, which will usually point
to an array of pointers to the module's various API functions.

There is an existing data type already used for this,
@code{PyCObject}, but it doesn't provide type safety.  Evil code
written in pure Python could cause a segmentation fault by taking a
@code{PyCObject} from module A and somehow substituting it for the
@code{PyCObject} in module B.   Capsules know their own name,
and getting the pointer requires providing the name:

@example
void *vtable;

if (!PyCapsule_IsValid(capsule, "mymodule.CAPI") @{
        PyErr_SetString(PyExc_ValueError, "argument type invalid");
        return NULL;
@}

vtable = PyCapsule_GetPointer(capsule, "mymodule.CAPI");
@end example

You are assured that @code{vtable} points to whatever you're expecting.
If a different capsule was passed in, @ref{1333,,PyCapsule_IsValid()} would
detect the mismatched name and return false.  Refer to
@ref{1334,,Fournir une API en langage C pour un module d'extension} for more information on using these objects.

Python 2.7 now uses capsules internally to provide various
extension-module APIs, but the @code{PyCObject_AsVoidPtr()} was
modified to handle capsules, preserving compile-time compatibility
with the @code{PyCObject} interface.  Use of
@code{PyCObject_AsVoidPtr()} will signal a
@ref{8b5,,PendingDeprecationWarning}, which is silent by default.

Implemented in Python 3.1 and backported to 2.7 by Larry Hastings;
discussed in bpo-5630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5630}.

@c ======================================================================

@node Port-Specific Changes Windows,Port-Specific Changes Mac OS X,Capsules,Build and C API Changes<8>
@anchor{whatsnew/2 7 port-specific-changes-windows}@anchor{1335}
@subsubsection Port-Specific Changes: Windows



@itemize *

@item 
The @ref{92,,msvcrt} module now contains some constants from
the @code{crtassem.h} header file:
@ref{1336,,CRT_ASSEMBLY_VERSION},
@ref{1337,,VC_ASSEMBLY_PUBLICKEYTOKEN},
and @ref{1338,,LIBRARIES_ASSEMBLY_NAME_PREFIX}.
(Contributed by David Cournapeau; bpo-4365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4365}.)

@item 
The @ref{115,,_winreg} module for accessing the registry now implements
the @ref{1339,,CreateKeyEx()} and @ref{133a,,DeleteKeyEx()}
functions, extended versions of previously supported functions that
take several extra arguments.  The @ref{133b,,DisableReflectionKey()},
@ref{133c,,EnableReflectionKey()}, and @ref{133d,,QueryReflectionKey()}
were also tested and documented.
(Implemented by Brian Curtin: bpo-7347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7347}.)

@item 
The new @code{_beginthreadex()} API is used to start threads, and
the native thread-local storage functions are now used.
(Contributed by Kristján Valur Jónsson; bpo-3582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3582}.)

@item 
The @ref{133e,,os.kill()} function now works on Windows.  The signal value
can be the constants @ref{133f,,CTRL_C_EVENT},
@ref{1340,,CTRL_BREAK_EVENT}, or any integer.  The first two constants
will send @code{Control-C} and @code{Control-Break} keystroke events to
subprocesses; any other value will use the @code{TerminateProcess()}
API.  (Contributed by Miki Tebeka; bpo-1220212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1220212}.)

@item 
The @ref{10da,,os.listdir()} function now correctly fails
for an empty path.  (Fixed by Hirokazu Yamamoto; bpo-5913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5913}.)

@item 
The @ref{8e,,mimetypes} module will now read the MIME database from
the Windows registry when initializing.
(Patch by Gabriel Genellina; bpo-4969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4969}.)
@end itemize

@c ======================================================================

@node Port-Specific Changes Mac OS X,Port-Specific Changes FreeBSD,Port-Specific Changes Windows,Build and C API Changes<8>
@anchor{whatsnew/2 7 port-specific-changes-mac-os-x}@anchor{1341}
@subsubsection Port-Specific Changes: Mac OS X



@itemize *

@item 
The path @code{/Library/Python/2.7/site-packages} is now appended to
@code{sys.path}, in order to share added packages between the system
installation and a user-installed copy of the same version.
(Changed by Ronald Oussoren; bpo-4865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4865}.)


Modifié dans la version 2.7.13: As of 2.7.13, this change was removed.
@code{/Library/Python/2.7/site-packages}, the site-packages directory
used by the Apple-supplied system Python 2.7 is no longer appended to
@code{sys.path} for user-installed Pythons such as from the python.org
installers.  As of macOS 10.12, Apple changed how the system
site-packages directory is configured, which could cause installation
of pip components, like setuptools, to fail.  Packages installed for
the system Python will no longer be shared with user-installed
Pythons. (bpo-28440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28440})

@end itemize

@node Port-Specific Changes FreeBSD,,Port-Specific Changes Mac OS X,Build and C API Changes<8>
@anchor{whatsnew/2 7 port-specific-changes-freebsd}@anchor{1342}
@subsubsection Port-Specific Changes: FreeBSD



@itemize *

@item 
FreeBSD 7.1's @code{SO_SETFIB} constant, used with the @ref{d8e,,socket()} methods
@ref{cc3,,getsockopt()}/@ref{cc4,,setsockopt()} to select an
alternate routing table, is now available in the @ref{cb,,socket}
module.  (Added by Kyle VanderBeek; bpo-8235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8235}.)
@end itemize

@node Autres changements et corrections,Portage vers Python 2 7,Build and C API Changes<8>,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 other-changes-and-fixes}@anchor{1343}
@subsection Autres changements et corrections



@itemize *

@item 
Two benchmark scripts, @code{iobench} and @code{ccbench}, were
added to the @code{Tools} directory.  @code{iobench} measures the
speed of the built-in file I/O objects returned by @ref{505,,open()}
while performing various operations, and @code{ccbench} is a
concurrency benchmark that tries to measure computing throughput,
thread switching latency, and IO processing bandwidth when
performing several tasks using a varying number of threads.

@item 
The @code{Tools/i18n/msgfmt.py} script now understands plural
forms in @code{.po} files.  (Fixed by Martin von Löwis;
bpo-5464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5464}.)

@item 
When importing a module from a @code{.pyc} or @code{.pyo} file
with an existing @code{.py} counterpart, the @ref{1344,,co_filename}
attributes of the resulting code objects are overwritten when the
original filename is obsolete.  This can happen if the file has been
renamed, moved, or is accessed through different paths.  (Patch by
Ziga Seilnacht and Jean-Paul Calderone; bpo-1180193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1180193}.)

@item 
The @code{regrtest.py} script now takes a @code{--randseed=}
switch that takes an integer that will be used as the random seed
for the @code{-r} option that executes tests in random order.
The @code{-r} option also reports the seed that was used
(Added by Collin Winter.)

@item 
Another @code{regrtest.py} switch is @code{-j}, which
takes an integer specifying how many tests run in parallel. This
allows reducing the total runtime on multi-core machines.
This option is compatible with several other options, including the
@code{-R} switch which is known to produce long runtimes.
(Added by Antoine Pitrou, bpo-6152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6152}.)  This can also be used
with a new @code{-F} switch that runs selected tests in a loop
until they fail.  (Added by Antoine Pitrou; bpo-7312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7312}.)

@item 
When executed as a script, the @code{py_compile.py} module now
accepts @code{'-'} as an argument, which will read standard input for
the list of filenames to be compiled.  (Contributed by Piotr
Ożarowski; bpo-8233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8233}.)
@end itemize

@c ======================================================================

@node Portage vers Python 2 7,New Features Added to Python 2 7 Maintenance Releases,Autres changements et corrections,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 porting-to-python-2-7}@anchor{1345}
@subsection Portage vers Python 2.7


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


@itemize *

@item 
The @ref{930,,range()} function processes its arguments more
consistently; it will now call @ref{706,,__int__()} on non-float,
non-integer arguments that are supplied to it.  (Fixed by Alexander
Belopolsky; bpo-1533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1533}.)

@item 
The string @ref{60a,,format()} method changed the default precision used
for floating-point and complex numbers from 6 decimal
places to 12, which matches the precision used by @ref{435,,str()}.
(Changed by Eric Smith; bpo-5920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5920}.)

@item 
Because of an optimization for the @ref{5bc,,with} statement, the special
methods @ref{5b2,,__enter__()} and @ref{12de,,__exit__()} must belong to the object's
type, and cannot be directly attached to the object's instance.  This
affects new-style classes (derived from @ref{a7a,,object}) and C extension
types.  (bpo-6101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6101}.)

@item 
Due to a bug in Python 2.6, the `exc_value' parameter to
@ref{12de,,__exit__()} methods was often the string representation of the
exception, not an instance.  This was fixed in 2.7, so `exc_value'
will be an instance as expected.  (Fixed by Florent Xicluna;
bpo-7853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7853}.)

@item 
When a restricted set of attributes were set using @code{__slots__},
deleting an unset attribute would not raise @ref{343,,AttributeError}
as you would expect.  Fixed by Benjamin Peterson; bpo-7604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7604}.)
@end itemize

In the standard library:


@itemize *

@item 
Operations with @ref{1c7,,datetime} instances that resulted in a year
falling outside the supported range didn't always raise
@ref{86d,,OverflowError}.  Such errors are now checked more carefully
and will now raise the exception. (Reported by Mark Leander, patch
by Anand B. Pillai and Alexander Belopolsky; bpo-7150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7150}.)

@item 
When using @ref{29a,,Decimal} instances with a string's
@ref{60a,,format()} method, the default alignment was previously
left-alignment.  This has been changed to right-alignment, which might
change the output of your programs.
(Changed by Mark Dickinson; bpo-6857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6857}.)

Comparisons involving a signaling NaN value (or @code{sNAN}) now signal
@ref{108c,,InvalidOperation} instead of silently returning a true or
false value depending on the comparison operator.  Quiet NaN values
(or @code{NaN}) are now hashable.  (Fixed by Mark Dickinson;
bpo-7279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7279}.)

@item 
The @ref{124,,xml.etree.ElementTree} library no longer escapes
ampersands and angle brackets when outputting an XML processing
instruction (which looks like @code{<?xml-stylesheet href="#style1"?>})
or comment (which looks like @code{<!-- comment -->}).
(Patch by Neil Muller; bpo-2746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2746}.)

@item 
The @code{readline()} method of @ref{f12,,StringIO} objects now does
nothing when a negative length is requested, as other file-like
objects do.  (bpo-7348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7348}).

@item 
The @ref{db,,syslog} module will now use the value of @code{sys.argv[0]} as the
identifier instead of the previous default value of @code{'python'}.
(Changed by Sean Reifschneider; bpo-8451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8451}.)

@item 
The @ref{dd,,tarfile} module's default error handling has changed, to
no longer suppress fatal errors.  The default error level was previously 0,
which meant that errors would only result in a message being written to the
debug log, but because the debug log is not activated by default,
these errors go unnoticed.  The default error level is now 1,
which raises an exception if there's an error.
(Changed by Lars Gustäbel; bpo-7357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7357}.)

@item 
The @ref{109,,urlparse} module's @ref{d2d,,urlsplit()} now handles
unknown URL schemes in a fashion compliant with 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}: if the
URL is of the form @code{"<something>://..."}, the text before the
@code{://} is treated as the scheme, even if it's a made-up scheme that
the module doesn't know about.  This change may break code that
worked around the old behaviour.  For example, Python 2.6.4 or 2.5
will return the following:

@example
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '@w{'}, '//host/filename?query', '@w{'}, '@w{'})
@end example

Python 2.7 (and Python 2.6.5) will return:

@example
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '@w{'}, '@w{'})
@end example

(Python 2.7 actually produces slightly different output, since it
returns a named tuple instead of a standard tuple.)
@end itemize

For C extensions:


@itemize *

@item 
C extensions that use integer format codes with the @code{PyArg_Parse*}
family of functions will now raise a @ref{522,,TypeError} exception
instead of triggering a @ref{1a3,,DeprecationWarning} (bpo-5080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5080}).

@item 
Use the new @ref{1273,,PyOS_string_to_double()} function instead of the old
@code{PyOS_ascii_strtod()} and @code{PyOS_ascii_atof()} functions,
which are now deprecated.
@end itemize

For applications that embed Python:


@itemize *

@item 
The @code{PySys_SetArgvEx()} function was added, letting
applications close a security hole when the existing
@code{PySys_SetArgv()} function was used.  Check whether you're
calling @code{PySys_SetArgv()} and carefully consider whether the
application should be using @code{PySys_SetArgvEx()} with
`updatepath' set to false.
@end itemize

@c ======================================================================

@node New Features Added to Python 2 7 Maintenance Releases,Remerciements,Portage vers Python 2 7,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 new-features-added-to-python-2-7-maintenance-releases}@anchor{1346}@anchor{whatsnew/2 7 py27-maintenance-enhancements}@anchor{12c4}
@subsection New Features Added to Python 2.7 Maintenance Releases


New features may be added to Python 2.7 maintenance releases when the
situation genuinely calls for it. Any such additions must go through
the Python Enhancement Proposal process, and make a compelling case for why
they can't be adequately addressed by either adding the new feature solely to
Python 3, or else by publishing it on the Python Package Index.

In addition to the specific proposals listed below, there is a general
exemption allowing new @code{-3} warnings to be added in any Python 2.7
maintenance release.

@menu
* Two new environment variables for debug mode:: 
* PEP 434; IDLE Enhancement Exception for All Branches: PEP 434 IDLE Enhancement Exception for All Branches. 
* PEP 466; Network Security Enhancements for Python 2.7: PEP 466 Network Security Enhancements for Python 2 7. 
* PEP 477; Backport ensurepip (PEP 453) to Python 2.7: PEP 477 Backport ensurepip PEP 453 to Python 2 7. 
* PEP 476; Enabling certificate verification by default for stdlib http clients: PEP 476 Enabling certificate verification by default for stdlib http clients<2>. 
* PEP 493; HTTPS verification migration tools for Python 2.7: PEP 493 HTTPS verification migration tools for Python 2 7. 
* New make regen-all build target: New make regen-all build target<3>. 
* Removal of make touch build target: Removal of make touch build target<3>. 

@end menu

@node Two new environment variables for debug mode,PEP 434 IDLE Enhancement Exception for All Branches,,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 two-new-environment-variables-for-debug-mode}@anchor{1347}
@subsubsection Two new environment variables for debug mode


In debug mode, the @code{[xxx refs]} statistic is not written by default, the
@code{PYTHONSHOWREFCOUNT} environment variable now must also be set.
(Contributed by Victor Stinner; bpo-31733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31733}.)

When Python is compiled with @code{COUNT_ALLOC} defined, allocation counts are no
longer dumped by default anymore: the @code{PYTHONSHOWALLOCCOUNT} environment
variable must now also be set. Moreover, allocation counts are now dumped into
stderr, rather than stdout. (Contributed by Victor Stinner; bpo-31692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31692}.)


Ajouté dans la version 2.7.15.


@node PEP 434 IDLE Enhancement Exception for All Branches,PEP 466 Network Security Enhancements for Python 2 7,Two new environment variables for debug mode,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 pep-434-idle-enhancement-exception-for-all-branches}@anchor{1348}
@subsubsection PEP 434: IDLE Enhancement Exception for All Branches


@geindex Python Enhancement Proposals; PEP 434
PEP 434@footnote{https://peps.python.org/pep-0434/} describes a general exemption for changes made to the IDLE
development environment shipped along with Python. This exemption makes it
possible for the IDLE developers to provide a more consistent user
experience across all supported versions of Python 2 and 3.

For details of any IDLE changes, refer to the NEWS file for the specific
release.

@node PEP 466 Network Security Enhancements for Python 2 7,PEP 477 Backport ensurepip PEP 453 to Python 2 7,PEP 434 IDLE Enhancement Exception for All Branches,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 pep-466-network-security-enhancements-for-python-2-7}@anchor{1349}
@subsubsection PEP 466: Network Security Enhancements for Python 2.7


@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} describes a number of network security enhancement proposals
that have been approved for inclusion in Python 2.7 maintenance releases,
with the first of those changes appearing in the Python 2.7.7 release.

@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} related features added in Python 2.7.7:


@itemize *

@item 
@ref{10ab,,hmac.compare_digest()} was backported from Python 3 to make a timing
attack resistant comparison operation available to Python 2 applications.
(Contributed by Alex Gaynor; bpo-21306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21306}.)

@item 
OpenSSL 1.0.1g was upgraded in the official Windows installers published on
python.org. (Contributed by Zachary Ware; bpo-21462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21462}.)
@end itemize

@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} related features added in Python 2.7.8:


@itemize *

@item 
@ref{4f8,,hashlib.pbkdf2_hmac()} was backported from Python 3 to make a hashing
algorithm suitable for secure password storage broadly available to Python
2 applications. (Contributed by Alex Gaynor; bpo-21304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21304}.)

@item 
OpenSSL 1.0.1h was upgraded for the official Windows installers published on
python.org. (Contributed by Zachary Ware in bpo-21671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21671} for 
@geindex Common Vulnerabilities and Exposures; CVE 2014-0224
CVE 2014-0224@footnote{https://www.cve.org/CVERecord?id=CVE-2014-0224}.)
@end itemize

@geindex Python Enhancement Proposals; PEP 466
PEP 466@footnote{https://peps.python.org/pep-0466/} related features added in Python 2.7.9:


@itemize *

@item 
Most of Python 3.4's @ref{cf,,ssl} module was backported. This means @ref{cf,,ssl}
now supports Server Name Indication, TLS1.x settings, access to the platform
certificate store, the @ref{291,,SSLContext} class, and other
features. (Contributed by Alex Gaynor and David Reid; bpo-21308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21308}.)

Refer to the "Version added: 2.7.9" notes in the module documentation for
specific details.

@item 
@ref{50c,,os.urandom()} was changed to cache a file descriptor to @code{/dev/urandom}
instead of reopening @code{/dev/urandom} on every call. (Contributed by Alex
Gaynor; bpo-21305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21305}.)

@item 
@ref{134a,,hashlib.algorithms_guaranteed} and
@ref{134b,,hashlib.algorithms_available} were backported from Python 3 to make
it easier for Python 2 applications to select the strongest available hash
algorithm. (Contributed by Alex Gaynor in bpo-21307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21307})
@end itemize

@node PEP 477 Backport ensurepip PEP 453 to Python 2 7,PEP 476 Enabling certificate verification by default for stdlib http clients<2>,PEP 466 Network Security Enhancements for Python 2 7,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 pep-477-backport-ensurepip-pep-453-to-python-2-7}@anchor{134c}
@subsubsection PEP 477: Backport ensurepip (PEP 453) to Python 2.7


@geindex Python Enhancement Proposals; PEP 477
PEP 477@footnote{https://peps.python.org/pep-0477/} approves the inclusion of the 
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/} ensurepip module and the
improved documentation that was enabled by it in the Python 2.7 maintenance
releases, appearing first in the Python 2.7.9 release.

@menu
* Bootstrapping pip By Default: Bootstrapping pip By Default<2>. 
* Documentation Changes: Documentation Changes<2>. 

@end menu

@node Bootstrapping pip By Default<2>,Documentation Changes<2>,,PEP 477 Backport ensurepip PEP 453 to Python 2 7
@anchor{whatsnew/2 7 bootstrapping-pip-by-default}@anchor{134d}
@subsubsection Bootstrapping pip By Default


The new @ref{54,,ensurepip} module (defined in 
@geindex Python Enhancement Proposals; PEP 453
PEP 453@footnote{https://peps.python.org/pep-0453/}) provides a standard
cross-platform mechanism to bootstrap the pip installer into Python
installations. The version of @code{pip} included with Python 2.7.9 is @code{pip}
1.5.6, and future 2.7.x maintenance releases will update the bundled version to
the latest version of @code{pip} that is available at the time of creating the
release candidate.

By default, the commands @code{pip}, @code{pipX} and @code{pipX.Y} will be installed on
all platforms (where X.Y stands for the version of the Python installation),
along with the @code{pip} Python package and its dependencies.

For CPython @ref{ede,,source builds on POSIX systems},
the @code{make install} and @code{make altinstall} commands do not bootstrap @code{pip}
by default.  This behaviour can be controlled through configure options, and
overridden through Makefile options.

On Windows and Mac OS X, the CPython installers now default to installing
@code{pip} along with CPython itself (users may opt out of installing it
during the installation process). Window users will need to opt in to the
automatic @code{PATH} modifications to have @code{pip} available from the command
line by default, otherwise it can still be accessed through the Python
launcher for Windows as @code{py -m pip}.

As 
@geindex Python Enhancement Proposals; PEP 0477#disabling-ensurepip-by-downstream-distributors
discussed in the PEP@footnote{https://peps.python.org/pep-0477/#disabling-ensurepip-by-downstream-distributors},
platform packagers may choose not to install
these commands by default, as long as, when invoked, they provide clear and
simple directions on how to install them on that platform (usually using
the system package manager).

@node Documentation Changes<2>,,Bootstrapping pip By Default<2>,PEP 477 Backport ensurepip PEP 453 to Python 2 7
@anchor{whatsnew/2 7 documentation-changes}@anchor{134e}
@subsubsection Documentation Changes


As part of this change, the @ref{ee0,,Installation de modules Python} and
distributing-index sections of the documentation have been
completely redesigned as short getting started and FAQ documents. Most
packaging documentation has now been moved out to the Python Packaging
Authority maintained Python Packaging User Guide@footnote{https://packaging.python.org} and the documentation of the individual
projects.

However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as @ref{ee1,,Building C and C++ Extensions with setuptools}
and @ref{ee2,,Building C and C++ Extensions with setuptools}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 453

@item PEP 453@footnote{https://peps.python.org/pep-0453/} -- Explicit bootstrapping of pip in Python installations

PEP written by Donald Stufft and Nick Coghlan, implemented by
Donald Stufft, Nick Coghlan, Martin von Löwis and Ned Deily.
@end table


@node PEP 476 Enabling certificate verification by default for stdlib http clients<2>,PEP 493 HTTPS verification migration tools for Python 2 7,PEP 477 Backport ensurepip PEP 453 to Python 2 7,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 pep-476-enabling-certificate-verification-by-default-for-stdlib-http-clients}@anchor{134f}
@subsubsection PEP 476: Enabling certificate verification by default for stdlib http clients


@geindex Python Enhancement Proposals; PEP 476
PEP 476@footnote{https://peps.python.org/pep-0476/} updated @ref{6d,,httplib} and modules which use it, such as
@ref{10a,,urllib2} and @ref{12d,,xmlrpclib}, to now
verify that the server
presents a certificate which is signed by a Certificate Authority in the
platform trust store and whose hostname matches the hostname being requested
by default, significantly improving security for many applications. This
change was made in the Python 2.7.9 release.

For applications which require the old previous behavior, they can pass an
alternate context:

@example
import urllib2
import ssl

# This disables all verification
context = ssl._create_unverified_context()

# This allows using a specific certificate for the host, which doesn't need
# to be in the trust store
context = ssl.create_default_context(cafile="/path/to/file.crt")

urllib2.urlopen("https://invalid-cert", context=context)
@end example

@node PEP 493 HTTPS verification migration tools for Python 2 7,New make regen-all build target<3>,PEP 476 Enabling certificate verification by default for stdlib http clients<2>,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 pep-493-https-verification-migration-tools-for-python-2-7}@anchor{1350}
@subsubsection PEP 493: HTTPS verification migration tools for Python 2.7


@geindex Python Enhancement Proposals; PEP 493
PEP 493@footnote{https://peps.python.org/pep-0493/} provides additional migration tools to support a more incremental
infrastructure upgrade process for environments containing applications and
services relying on the historically permissive processing of server
certificates when establishing client HTTPS connections.  These additions were
made in the Python 2.7.12 release.

These tools are intended for use in cases where affected applications and
services can't be modified to explicitly pass a more permissive SSL context
when establishing the connection.

For applications and services which can't be modified at all, the new
@code{PYTHONHTTPSVERIFY} environment variable may be set to @code{0} to revert an
entire Python process back to the default permissive behaviour of Python 2.7.8
and earlier.

For cases where the connection establishment code can't be modified, but the
overall application can be, the new @code{ssl._https_verify_certificates()}
function can be used to adjust the default behaviour at runtime.

@node New make regen-all build target<3>,Removal of make touch build target<3>,PEP 493 HTTPS verification migration tools for Python 2 7,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 new-make-regen-all-build-target}@anchor{1351}
@subsubsection New @code{make regen-all} build target


To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.

Instead, a new @code{make regen-all} command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).

More selective regeneration targets are also defined - see
Makefile.pre.in@footnote{https://github.com/python/cpython/tree/3.13/Makefile.pre.in} for details.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Ajouté dans la version 2.7.14.


@node Removal of make touch build target<3>,,New make regen-all build target<3>,New Features Added to Python 2 7 Maintenance Releases
@anchor{whatsnew/2 7 removal-of-make-touch-build-target}@anchor{1352}
@subsubsection Removal of @code{make touch} build target


The @code{make touch} build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.

It has been replaced by the new @code{make regen-all} target.

(Contributed by Victor Stinner in bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}.)


Modifié dans la version 2.7.14.


@c ======================================================================

@node Remerciements,,New Features Added to Python 2 7 Maintenance Releases,Nouveautés de Python 2 7
@anchor{whatsnew/2 7 acknowledgements}@anchor{1353}@anchor{whatsnew/2 7 acks27}@anchor{1354}
@subsection Remerciements


The author would like to thank the following people for offering
suggestions, corrections and assistance with various drafts of this
article: Nick Coghlan, Philip Jenvey, Ryan Lovett, R. David Murray,
Hugh Secker-Walker.

@node Nouveautés de Python 2 6,Nouveautés de Python 2 5,Nouveautés de Python 2 7,Nouveautés de Python
@anchor{whatsnew/2 6 doc}@anchor{1355}@anchor{whatsnew/2 6 what-s-new-in-python-2-6}@anchor{1356}@anchor{whatsnew/2 6 whats-new-in-2-6}@anchor{128b}
@section Nouveautés de Python 2.6


@*Auteur: 
A.M. Kuchling (amk at amk.ca)


@c $Id$
@c Rules for maintenance:
@c 
@c * Anyone can add text to this document.  Do not spend very much time
@c on the wording of your changes, because your text will probably
@c get rewritten to some degree.
@c 
@c * The maintainer will go through Misc/NEWS periodically and add
@c changes; it's therefore more important to add your changes to
@c Misc/NEWS than to this file.
@c 
@c * This is not a complete list of every single change; completeness
@c is the purpose of Misc/NEWS.  Some changes I consider too small
@c or esoteric to include.  If such a change is added to the text,
@c I'll just remove it.  (This is another reason you shouldn't spend
@c too much time on writing your addition.)
@c 
@c * If you want to draw your new text to the attention of the
@c maintainer, add 'XXX' to the beginning of the paragraph or
@c section.
@c 
@c * It's OK to just add a fragmentary note about a change.  For
@c example: "XXX Describe the transmogrify() function added to the
@c socket module."  The maintainer will research the change and
@c write the necessary text.
@c 
@c * You can comment out your additions if you like, but it's not
@c necessary (especially when a final release is some months away).
@c 
@c * Credit the author of a patch or bugfix.   Just the name is
@c sufficient; the e-mail address isn't necessary.
@c 
@c * It's helpful to add the bug/patch number in a parenthetical comment.
@c 
@c XXX Describe the transmogrify() function added to the socket
@c module.
@c (Contributed by P.Y. Developer; :issue:`12345`.)
@c 
@c This saves the maintainer some effort going through the SVN logs
@c when researching a change.

This article explains the new features in Python 2.6, released on October 1,
2008.  The release schedule is described in 
@geindex Python Enhancement Proposals; PEP 361
PEP 361@footnote{https://peps.python.org/pep-0361/}.

The major theme of Python 2.6 is preparing the migration path to
Python 3.0, a major redesign of the language.  Whenever possible,
Python 2.6 incorporates new features and syntax from 3.0 while
remaining compatible with existing code by not removing older features
or syntax.  When it's not possible to do that, Python 2.6 tries to do
what it can, adding compatibility functions in a
@code{future_builtins} module and a @code{-3} switch to warn about
usages that will become unsupported in 3.0.

Some significant new packages have been added to the standard library,
such as the @ref{93,,multiprocessing} and @ref{81,,json} modules, but
there aren't many new features that aren't related to Python 3.0 in
some way.

Python 2.6 also sees a number of improvements and bugfixes throughout
the source.  A search through the change logs finds there were 259
patches applied and 612 bugs fixed between Python 2.5 and 2.6.  Both
figures are likely to be underestimates.

This article doesn't attempt to provide a complete specification of
the new features, but instead provides a convenient overview.  For
full details, you should refer to the documentation for Python 2.6. If
you want to understand the rationale for the design and
implementation, refer to the PEP for a particular new feature.
Whenever possible, "What's New in Python" links to the bug/patch item
for each change.

@c Compare with previous release in 2 - 3 sentences here.
@c add hyperlink when the documentation becomes available online.

@c ========================================================================

@c Large, PEP-level features and changes should be described here.

@c ========================================================================

@menu
* Python 3.0: Python 3 0. 
* Changes to the Development Process:: 
* PEP 343; The 'with' statement: PEP 343 The 'with' statement. 
* PEP 366; Explicit Relative Imports From a Main Module: PEP 366 Explicit Relative Imports From a Main Module. 
* PEP 370; Per-user site-packages Directory: PEP 370 Per-user site-packages Directory. 
* PEP 371; The multiprocessing Package: PEP 371 The multiprocessing Package. 
* PEP 3101; Advanced String Formatting: PEP 3101 Advanced String Formatting. 
* PEP 3105; print As a Function: PEP 3105 print As a Function. 
* PEP 3110; Exception-Handling Changes: PEP 3110 Exception-Handling Changes. 
* PEP 3112; Byte Literals: PEP 3112 Byte Literals. 
* PEP 3116; New I/O Library: PEP 3116 New I/O Library. 
* PEP 3118; Revised Buffer Protocol: PEP 3118 Revised Buffer Protocol. 
* PEP 3119; Abstract Base Classes: PEP 3119 Abstract Base Classes. 
* PEP 3127; Integer Literal Support and Syntax: PEP 3127 Integer Literal Support and Syntax. 
* PEP 3129; Class Decorators: PEP 3129 Class Decorators. 
* PEP 3141; A Type Hierarchy for Numbers: PEP 3141 A Type Hierarchy for Numbers. 
* Autres changements au langage: Autres changements au langage<15>. 
* New and Improved Modules: New and Improved Modules<2>. 
* Deprecations and Removals:: 
* Build and C API Changes: Build and C API Changes<9>. 
* Portage vers Python 2.6: Portage vers Python 2 6. 
* Remerciements: Remerciements<2>. 

@end menu

@node Python 3 0,Changes to the Development Process,,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 python-3-0}@anchor{1357}
@subsection Python 3.0


The development cycle for Python versions 2.6 and 3.0 was
synchronized, with the alpha and beta releases for both versions being
made on the same days.  The development of 3.0 has influenced many
features in 2.6.

Python 3.0 is a far-ranging redesign of Python that breaks
compatibility with the 2.x series.  This means that existing Python
code will need some conversion in order to run on
Python 3.0.  However, not all the changes in 3.0 necessarily break
compatibility.  In cases where new features won't cause existing code
to break, they've been backported to 2.6 and are described in this
document in the appropriate place.  Some of the 3.0-derived features
are:


@itemize *

@item 
A @code{__complex__()} method for converting objects to a complex number.

@item 
Alternate syntax for catching exceptions: @code{except TypeError as exc}.

@item 
The addition of @ref{12ba,,functools.reduce()} as a synonym for the built-in
@code{reduce()} function.
@end itemize

Python 3.0 adds several new built-in functions and changes the
semantics of some existing builtins.  Functions that are new in 3.0
such as @ref{1286,,bin()} have simply been added to Python 2.6, but existing
builtins haven't been changed; instead, the @code{future_builtins}
module has versions with the new 3.0 semantics.  Code written to be
compatible with 3.0 can do @code{from future_builtins import hex, map} as
necessary.

A new command-line switch, @code{-3}, enables warnings
about features that will be removed in Python 3.0.  You can run code
with this switch to see how much work will be necessary to port
code to 3.0.  The value of this switch is available
to Python code as the boolean variable @code{sys.py3kwarning},
and to C extension code as @code{Py_Py3kWarningFlag}.


@subsubheading Voir aussi


The 3`xxx' series of PEPs, which contains proposals for Python 3.0.
@geindex Python Enhancement Proposals; PEP 3000
PEP 3000@footnote{https://peps.python.org/pep-3000/} describes the development process for Python 3.0.
Start with 
@geindex Python Enhancement Proposals; PEP 3100
PEP 3100@footnote{https://peps.python.org/pep-3100/} that describes the general goals for Python
3.0, and then explore the higher-numbered PEPs that propose
specific features.


@node Changes to the Development Process,PEP 343 The 'with' statement,Python 3 0,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 changes-to-the-development-process}@anchor{1358}
@subsection Changes to the Development Process


While 2.6 was being developed, the Python development process
underwent two significant changes: we switched from SourceForge's
issue tracker to a customized Roundup installation, and the
documentation was converted from LaTeX to reStructuredText.

@menu
* New Issue Tracker; Roundup: New Issue Tracker Roundup. 
* New Documentation Format; reStructuredText Using Sphinx: New Documentation Format reStructuredText Using Sphinx. 

@end menu

@node New Issue Tracker Roundup,New Documentation Format reStructuredText Using Sphinx,,Changes to the Development Process
@anchor{whatsnew/2 6 new-issue-tracker-roundup}@anchor{1359}
@subsubsection New Issue Tracker: Roundup


For a long time, the Python developers had been growing increasingly
annoyed by SourceForge's bug tracker.  SourceForge's hosted solution
doesn't permit much customization; for example, it wasn't possible to
customize the life cycle of issues.

The infrastructure committee of the Python Software Foundation
therefore posted a call for issue trackers, asking volunteers to set
up different products and import some of the bugs and patches from
SourceForge.  Four different trackers were examined: Jira@footnote{https://www.atlassian.com/software/jira/},
Launchpad@footnote{https://launchpad.net/},
Roundup@footnote{https://roundup.sourceforge.io/}, and
Trac@footnote{https://trac.edgewall.org/}.
The committee eventually settled on Jira
and Roundup as the two candidates.  Jira is a commercial product that
offers no-cost hosted instances to free-software projects; Roundup
is an open-source project that requires volunteers
to administer it and a server to host it.

After posting a call for volunteers, a new Roundup installation was
set up at @indicateurl{https://bugs.python.org}.  One installation of Roundup can
host multiple trackers, and this server now also hosts issue trackers
for Jython and for the Python web site.  It will surely find
other uses in the future.  Where possible,
this edition of "What's New in Python" links to the bug/patch
item for each change.

Hosting of the Python bug tracker is kindly provided by
Upfront Systems@footnote{https://upfrontsoftware.co.za}
of Stellenbosch, South Africa.  Martin von Löwis put a
lot of effort into importing existing bugs and patches from
SourceForge; his scripts for this import operation are at
@code{https://svn.python.org/view/tracker/importer/} and may be useful to
other projects wishing to move from SourceForge to Roundup.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://bugs.python.org}

The Python bug tracker.

@item @indicateurl{https://bugs.jython.org}:

The Jython bug tracker.

@item @indicateurl{https://roundup.sourceforge.io/}

Roundup downloads and documentation.

@item @indicateurl{https://svn.python.org/view/tracker/importer/}

Martin von Löwis's conversion scripts.
@end table


@node New Documentation Format reStructuredText Using Sphinx,,New Issue Tracker Roundup,Changes to the Development Process
@anchor{whatsnew/2 6 new-documentation-format-restructuredtext-using-sphinx}@anchor{135a}
@subsubsection New Documentation Format: reStructuredText Using Sphinx


The Python documentation was written using LaTeX since the project
started around 1989.  In the 1980s and early 1990s, most documentation
was printed out for later study, not viewed online. LaTeX was widely
used because it provided attractive printed output while remaining
straightforward to write once the basic rules of the markup were
learned.

Today LaTeX is still used for writing publications destined for
printing, but the landscape for programming tools has shifted.  We no
longer print out reams of documentation; instead, we browse through it
online and HTML has become the most important format to support.
Unfortunately, converting LaTeX to HTML is fairly complicated and Fred
L. Drake Jr., the long-time Python documentation editor, spent a lot
of time maintaining the conversion process.  Occasionally people would
suggest converting the documentation into SGML and later XML, but
performing a good conversion is a major task and no one ever committed
the time required to finish the job.

During the 2.6 development cycle, Georg Brandl put a lot of effort
into building a new toolchain for processing the documentation.  The
resulting package is called Sphinx, and is available from
@indicateurl{https://www.sphinx-doc.org/}.

Sphinx concentrates on HTML output, producing attractively styled and
modern HTML; printed output is still supported through conversion to
LaTeX.  The input format is reStructuredText, a markup syntax
supporting custom extensions and directives that is commonly used in
the Python community.

Sphinx is a standalone package that can be used for writing, and
almost two dozen other projects
(listed on the Sphinx web site@footnote{https://www.sphinx-doc.org/en/master/examples.html})
have adopted Sphinx as their documentation tool.


@subsubheading Voir aussi



@table @asis

@item Documenting Python@footnote{https://devguide.python.org/documenting/}

Describes how to write for Python's documentation.

@item Sphinx@footnote{https://www.sphinx-doc.org/}

Documentation and code for the Sphinx toolchain.

@item Docutils@footnote{https://docutils.sourceforge.io}

The underlying reStructuredText parser and toolset.
@end table


@node PEP 343 The 'with' statement,PEP 366 Explicit Relative Imports From a Main Module,Changes to the Development Process,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-0343}@anchor{128c}@anchor{whatsnew/2 6 pep-343-the-with-statement}@anchor{135b}
@subsection PEP 343: The 'with' statement


The previous version, Python 2.5, added the '@ref{5bc,,with}'
statement as an optional feature, to be enabled by a @code{from __future__
import with_statement} directive.  In 2.6 the statement no longer needs to
be specially enabled; this means that @code{with} is now always a
keyword.  The rest of this section is a copy of the corresponding
section from the "What's New in Python 2.5" document; if you're
familiar with the '@code{with}' statement
from Python 2.5, you can skip this section.

The '@ref{5bc,,with}' statement clarifies code that previously would use
@code{try...finally} blocks to ensure that clean-up code is executed.  In this
section, I'll discuss the statement as it will commonly be used.  In the next
section, I'll examine the implementation details and show how to write objects
for use with this statement.

The '@ref{5bc,,with}' statement is a control-flow structure whose basic
structure is:

@example
with expression [as variable]:
    with-block
@end example

The expression is evaluated, and it should result in an object that supports the
context management protocol (that is, has @ref{5b2,,__enter__()} and @ref{12de,,__exit__()}
methods).

The object's @ref{5b2,,__enter__()} is called before `with-block' is executed and
therefore can run set-up code. It also may return a value that is bound to the
name `variable', if given.  (Note carefully that `variable' is `not' assigned
the result of `expression'.)

After execution of the `with-block' is finished, the object's @ref{12de,,__exit__()}
method is called, even if the block raised an exception, and can therefore run
clean-up code.

Some standard Python objects now support the context management protocol and can
be used with the '@ref{5bc,,with}' statement. File objects are one example:

@example
with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...
@end example

After this statement has executed, the file object in `f' will have been
automatically closed, even if the @ref{2e6,,for} loop raised an exception
part-way through the block.

@cartouche
@quotation Note 
In this case, `f' is the same object created by @ref{505,,open()}, because
@ref{5b2,,__enter__()} returns `self'.
@end quotation
@end cartouche

The @ref{ec,,threading} module's locks and condition variables  also support the
'@ref{5bc,,with}' statement:

@example
lock = threading.Lock()
with lock:
    # Critical section of code
    ...
@end example

The lock is acquired before the block is executed and always released once  the
block is complete.

The @code{localcontext()} function in the @ref{36,,decimal} module makes it easy
to save and restore the current decimal context, which encapsulates the desired
precision and rounding characteristics for computations:

@example
from decimal import Decimal, Context, localcontext

# Displays with default precision of 28 digits
v = Decimal('578')
print v.sqrt()

with localcontext(Context(prec=16)):
    # All code in this block uses a precision of 16 digits.
    # The original context is restored on exiting the block.
    print v.sqrt()
@end example

@menu
* Écrire des gestionnaires de contexte:: 
* Le module contextlib:: 

@end menu

@node Écrire des gestionnaires de contexte,Le module contextlib,,PEP 343 The 'with' statement
@anchor{whatsnew/2 6 new-26-context-managers}@anchor{128d}@anchor{whatsnew/2 6 writing-context-managers}@anchor{135c}
@subsubsection Écrire des gestionnaires de contexte


Under the hood, the '@ref{5bc,,with}' statement is fairly complicated. Most
people will only use '@code{with}' in company with existing objects and
don't need to know these details, so you can skip the rest of this section if
you like.  Authors of new objects will need to understand the details of the
underlying implementation and should keep reading.

A high-level explanation of the context management protocol is:


@itemize *

@item 
The expression is evaluated and should result in an object called a "context
manager".  The context manager must have @ref{5b2,,__enter__()} and @ref{12de,,__exit__()}
methods.

@item 
The context manager's @ref{5b2,,__enter__()} method is called.  The value returned
is assigned to `VAR'.  If no @code{as VAR} clause is present, the value is simply
discarded.

@item 
Le code dans `BLOCK' est exécuté.

@item 
If `BLOCK' raises an exception, the context manager's @ref{12de,,__exit__()} method
is called with three arguments, the exception details (@code{type, value, traceback},
the same values returned by @ref{675,,sys.exc_info()}, which can also be @code{None}
if no exception occurred).  The method's return value controls whether an exception
is re-raised: any false value re-raises the exception, and @code{True} will result
in suppressing it.  You'll only rarely want to suppress the exception, because
if you do the author of the code containing the '@ref{5bc,,with}' statement will
never realize anything went wrong.

@item 
If `BLOCK' didn't raise an exception,  the @ref{12de,,__exit__()} method is still
called, but `type', `value', and `traceback' are all @code{None}.
@end itemize

Let's think through an example.  I won't present detailed code but will only
sketch the methods necessary for a database that supports transactions.

(For people unfamiliar with database terminology: a set of changes to the
database are grouped into a transaction.  Transactions can be either committed,
meaning that all the changes are written into the database, or rolled back,
meaning that the changes are all discarded and the database is unchanged.  See
any database textbook for more information.)

Let's assume there's an object representing a database connection. Our goal will
be to let the user write code like this:

@example
db_connection = DatabaseConnection()
with db_connection as cursor:
    cursor.execute('insert into ...')
    cursor.execute('delete from ...')
    # ... more operations ...
@end example

The transaction should be committed if the code in the block runs flawlessly or
rolled back if there's an exception. Here's the basic interface for
@code{DatabaseConnection} that I'll assume:

@example
class DatabaseConnection:
    # Database interface
    def cursor(self):
        "Returns a cursor object and starts a new transaction"
    def commit(self):
        "Commits current transaction"
    def rollback(self):
        "Rolls back current transaction"
@end example

The @ref{5b2,,__enter__()} method is pretty easy, having only to start a new
transaction.  For this application the resulting cursor object would be a useful
result, so the method will return it.  The user can then add @code{as cursor} to
their '@ref{5bc,,with}' statement to bind the cursor to a variable name.

@example
class DatabaseConnection:
    ...
    def __enter__(self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor
@end example

The @ref{12de,,__exit__()} method is the most complicated because it's where most of
the work has to be done.  The method has to check if an exception occurred.  If
there was no exception, the transaction is committed.  The transaction is rolled
back if there was an exception.

In the code below, execution will just fall off the end of the function,
returning the default value of @code{None}.  @code{None} is false, so the exception
will be re-raised automatically.  If you wished, you could be more explicit and
add a @ref{9bc,,return} statement at the marked location.

@example
class DatabaseConnection:
    ...
    def __exit__(self, type, value, tb):
        if tb is None:
            # No exception, so commit
            self.commit()
        else:
            # Exception occurred, so rollback.
            self.rollback()
            # return False
@end example

@node Le module contextlib,,Écrire des gestionnaires de contexte,PEP 343 The 'with' statement
@anchor{whatsnew/2 6 new-module-contextlib}@anchor{128e}@anchor{whatsnew/2 6 the-contextlib-module}@anchor{135d}
@subsubsection Le module `contextlib'


The @ref{23,,contextlib} module provides some functions and a decorator that
are useful when writing objects for use with the '@ref{5bc,,with}' statement.

The decorator is called @code{contextmanager()}, and lets you write a single
generator function instead of defining a new class.  The generator should yield
exactly one value.  The code up to the @ref{9bb,,yield} will be executed as the
@ref{5b2,,__enter__()} method, and the value yielded will be the method's return
value that will get bound to the variable in the '@ref{5bc,,with}' statement's
@code{as} clause, if any.  The code after the @code{yield} will be
executed in the @ref{12de,,__exit__()} method.  Any exception raised in the block will
be raised by the @code{yield} statement.

Using this decorator, our database example from the previous section
could be written as:

@example
from contextlib import contextmanager

@@contextmanager
def db_transaction(connection):
    cursor = connection.cursor()
    try:
        yield cursor
    except:
        connection.rollback()
        raise
    else:
        connection.commit()

db = DatabaseConnection()
with db_transaction(db) as cursor:
    ...
@end example

The @ref{23,,contextlib} module also has a @code{nested(mgr1, mgr2, ...)} function
that combines a number of context managers so you don't need to write nested
'@ref{5bc,,with}' statements.  In this example, the single '@code{with}'
statement both starts a database transaction and acquires a thread lock:

@example
lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
    ...
@end example

Finally, the @code{closing()} function returns its argument so that it can be
bound to a variable, and calls the argument's @code{.close()} method at the end
of the block.

@example
import urllib, sys
from contextlib import closing

with closing(urllib.urlopen('http://www.yahoo.com')) as f:
    for line in f:
        sys.stdout.write(line)
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - The "with" statement

PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland,
Guido van Rossum, and Neal Norwitz.  The PEP shows the code generated for a
'@ref{5bc,,with}' statement, which can be helpful in learning how the statement
works.
@end table

The documentation  for the @ref{23,,contextlib} module.


@c ======================================================================

@node PEP 366 Explicit Relative Imports From a Main Module,PEP 370 Per-user site-packages Directory,PEP 343 The 'with' statement,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-0366}@anchor{128f}@anchor{whatsnew/2 6 pep-366-explicit-relative-imports-from-a-main-module}@anchor{135e}
@subsection PEP 366: Explicit Relative Imports From a Main Module


Python's @ref{5cb,,-m} switch allows running a module as a script.
When you ran a module that was located inside a package, relative
imports didn't work correctly.

The fix for Python 2.6 adds a @ref{2d6,,module.__package__} attribute.
When this attribute is present, relative imports will be
relative to the value of this attribute instead of the
@ref{135f,,__name__} attribute.

PEP 302-style importers can then set @ref{2d6,,__package__} as necessary.
The @ref{bd,,runpy} module that implements the @ref{5cb,,-m} switch now
does this, so relative imports will now work correctly in scripts
running from inside a package.

@c ======================================================================

@node PEP 370 Per-user site-packages Directory,PEP 371 The multiprocessing Package,PEP 366 Explicit Relative Imports From a Main Module,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-0370}@anchor{1290}@anchor{whatsnew/2 6 pep-370-per-user-site-packages-directory}@anchor{1360}
@subsection PEP 370: Per-user @code{site-packages} Directory


When you run Python, the module search path @code{sys.path} usually
includes a directory whose path ends in @code{"site-packages"}.  This
directory is intended to hold locally installed packages available to
all users using a machine or a particular site installation.

Python 2.6 introduces a convention for user-specific site directories.
The directory varies depending on the platform:


@itemize *

@item 
UNIX et Mac OS X : @code{~/.local/}

@item 
Windows : @code{%APPDATA%/Python}
@end itemize

Within this directory, there will be version-specific subdirectories,
such as @code{lib/python2.6/site-packages} on Unix/Mac OS and
@code{Python26/site-packages} on Windows.

If you don't like the default directory, it can be overridden by an
environment variable.  
@geindex PYTHONUSERBASE
@geindex variable d'environnement; PYTHONUSERBASE
@ref{1361,,PYTHONUSERBASE} sets the root
directory used for all Python versions supporting this feature.  On
Windows, the directory for application-specific data can be changed by
setting the 
@geindex APPDATA
@geindex variable d'environnement; APPDATA
@code{APPDATA} environment variable.  You can also
modify the @code{site.py} file for your Python installation.

The feature can be disabled entirely by running Python with the
@ref{1362,,-s} option or setting the 
@geindex PYTHONNOUSERSITE
@geindex variable d'environnement; PYTHONNOUSERSITE
@ref{1363,,PYTHONNOUSERSITE}
environment variable.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 370

@item PEP 370@footnote{https://peps.python.org/pep-0370/} - Per-user @code{site-packages} Directory

PEP written and implemented by Christian Heimes.
@end table


@c ======================================================================

@node PEP 371 The multiprocessing Package,PEP 3101 Advanced String Formatting,PEP 370 Per-user site-packages Directory,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-0371}@anchor{1291}@anchor{whatsnew/2 6 pep-371-the-multiprocessing-package}@anchor{1364}
@subsection PEP 371: The @code{multiprocessing} Package


The new @ref{93,,multiprocessing} package lets Python programs create new
processes that will perform a computation and return a result to the
parent.  The parent and child processes can communicate using queues
and pipes, synchronize their operations using locks and semaphores,
and can share simple arrays of data.

The @ref{93,,multiprocessing} module started out as an exact emulation of
the @ref{ec,,threading} module using processes instead of threads.  That
goal was discarded along the path to Python 2.6, but the general
approach of the module is still similar.  The fundamental class
is the @code{Process}, which is passed a callable object and
a collection of arguments.  The @code{start()} method
sets the callable running in a subprocess, after which you can call
the @code{is_alive()} method to check whether the subprocess is still running
and the @code{join()} method to wait for the process to exit.

Here's a simple example where the subprocess will calculate a
factorial.  The function doing the calculation is written strangely so
that it takes significantly longer when the input argument is a
multiple of 4.

@example
import time
from multiprocessing import Process, Queue


def factorial(queue, N):
    "Compute a factorial."
    # If N is a multiple of 4, this function will take much longer.
    if (N % 4) == 0:
        time.sleep(.05 * N/4)

    # Calculate the result
    fact = 1L
    for i in range(1, N+1):
        fact = fact * i

    # Put the result on the queue
    queue.put(fact)

if __name__ == '__main__':
    queue = Queue()

    N = 5

    p = Process(target=factorial, args=(queue, N))
    p.start()
    p.join()

    result = queue.get()
    print 'Factorial', N, '=', result
@end example

A @ref{1365,,Queue} is used to communicate the result of the factorial.
The @ref{1365,,Queue} object is stored in a global variable.
The child process will use the value of the variable when the child
was created; because it's a @ref{1365,,Queue}, parent and child can use
the object to communicate.  (If the parent were to change the value of
the global variable, the child's value would be unaffected, and vice
versa.)

Two other classes, @code{Pool} and @code{Manager}, provide
higher-level interfaces.  @code{Pool} will create a fixed number of
worker processes, and requests can then be distributed to the workers
by calling @code{apply()} or @code{apply_async()} to add a single request,
and @ref{84e,,map()} or @code{map_async()} to add a number of
requests.  The following code uses a @code{Pool} to spread requests
across 5 worker processes and retrieve a list of results:

@example
from multiprocessing import Pool

def factorial(N, dictionary):
    "Compute a factorial."
    ...
p = Pool(5)
result = p.map(factorial, range(1, 1000, 10))
for v in result:
    print v
@end example

Ceci produit l’affichage suivant :

@example
1
39916800
51090942171709440000
8222838654177922817725562880000000
33452526613163807108170062053440751665152000000000
...
@end example

The other high-level interface, the @code{Manager} class, creates a
separate server process that can hold master copies of Python data
structures.  Other processes can then access and modify these data
structures using proxy objects.  The following example creates a
shared dictionary by calling the @ref{253,,dict()} method; the worker
processes then insert values into the dictionary.  (Locking is not
done for you automatically, which doesn't matter in this example.
@code{Manager}'s methods also include @code{Lock()}, @code{RLock()},
and @code{Semaphore()} to create shared locks.)

@example
import time
from multiprocessing import Pool, Manager

def factorial(N, dictionary):
    "Compute a factorial."
    # Calculate the result
    fact = 1L
    for i in range(1, N+1):
        fact = fact * i

    # Store result in dictionary
    dictionary[N] = fact

if __name__ == '__main__':
    p = Pool(5)
    mgr = Manager()
    d = mgr.dict()         # Create shared dictionary

    # Run tasks using the pool
    for N in range(1, 1000, 10):
        p.apply_async(factorial, (N, d))

    # Mark pool as closed -- no more tasks can be added.
    p.close()

    # Wait for tasks to exit
    p.join()

    # Output results
    for k, v in sorted(d.items()):
        print k, v
@end example

This will produce the output:

@example
1 1
11 39916800
21 51090942171709440000
31 8222838654177922817725562880000000
41 33452526613163807108170062053440751665152000000000
51 15511187532873822802242430164693032110632597200169861120000...
@end example


@subsubheading Voir aussi


The documentation for the @ref{93,,multiprocessing} module.


@table @asis

@geindex Python Enhancement Proposals; PEP 371

@item PEP 371@footnote{https://peps.python.org/pep-0371/} - Addition of the multiprocessing package

PEP written by Jesse Noller and Richard Oudkerk;
implemented by Richard Oudkerk and Jesse Noller.
@end table


@c ======================================================================

@node PEP 3101 Advanced String Formatting,PEP 3105 print As a Function,PEP 371 The multiprocessing Package,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3101}@anchor{1292}@anchor{whatsnew/2 6 pep-3101-advanced-string-formatting}@anchor{1366}
@subsection PEP 3101: Advanced String Formatting


In Python 3.0, the @code{%} operator is supplemented by a more powerful string
formatting method, @ref{60a,,format()}.  Support for the @ref{60c,,str.format()} method
has been backported to Python 2.6.

In 2.6, both 8-bit and Unicode strings have a @code{.format()} method that
treats the string as a template and takes the arguments to be formatted.
The formatting template uses curly brackets (@code{@{}, @code{@}}) as special characters:

@example
>>> # Substitute positional argument 0 into the string.
>>> "User ID: @{0@}".format("root")
'User ID: root'
>>> # Use the named keyword arguments
>>> "User ID: @{uid@}   Last seen: @{last_login@}".format(
...    uid="root",
...    last_login = "5 Mar 2008 07:20")
'User ID: root   Last seen: 5 Mar 2008 07:20'
@end example

Curly brackets can be escaped by doubling them:

@example
>>> "Empty dict: @{@{@}@}".format()
"Empty dict: @{@}"
@end example

Field names can be integers indicating positional arguments, such as
@code{@{0@}}, @code{@{1@}}, etc. or names of keyword arguments.  You can also
supply compound field names that read attributes or access dictionary keys:

@example
>>> import sys
>>> print 'Platform: @{0.platform@}\nPython version: @{0.version@}'.format(sys)
Platform: darwin
Python version: 2.6a1+ (trunk:61261M, Mar  5 2008, 20:29:41)
[GCC 4.0.1 (Apple Computer, Inc. build 5367)]'

>>> import mimetypes
>>> 'Content-type: @{0[.mp4]@}'.format(mimetypes.types_map)
'Content-type: video/mp4'
@end example

Note that when using dictionary-style notation such as @code{[.mp4]}, you
don't need to put any quotation marks around the string; it will look
up the value using @code{.mp4} as the key.  Strings beginning with a
number will be converted to an integer.  You can't write more
complicated expressions inside a format string.

So far we've shown how to specify which field to substitute into the
resulting string.  The precise formatting used is also controllable by
adding a colon followed by a format specifier.  For example:

@example
>>> # Field 0: left justify, pad to 15 characters
>>> # Field 1: right justify, pad to 6 characters
>>> fmt = '@{0:15@} $@{1:>6@}'
>>> fmt.format('Registration', 35)
'Registration    $    35'
>>> fmt.format('Tutorial', 50)
'Tutorial        $    50'
>>> fmt.format('Banquet', 125)
'Banquet         $   125'
@end example

Format specifiers can reference other fields through nesting:

@example
>>> fmt = '@{0:@{1@}@}'
>>> width = 15
>>> fmt.format('Invoice #1234', width)
'Invoice #1234  '
>>> width = 35
>>> fmt.format('Invoice #1234', width)
'Invoice #1234                      '
@end example

The alignment of a field within the desired width can be specified:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Caractère

@tab

Effect

@item

< (par défaut)

@tab

Left-align

@item

>

@tab

Right-align

@item

^

@tab

Center

@item

=

@tab

(For numeric types only) Pad after the sign.

@end multitable


Format specifiers can also include a presentation type, which
controls how the value is formatted.  For example, floating-point numbers
can be formatted as a general number or in exponential notation:

@example
>>> '@{0:g@}'.format(3.75)
'3.75'
>>> '@{0:e@}'.format(3.75)
'3.750000e+00'
@end example

A variety of presentation types are available.  Consult the 2.6
documentation for a @ref{1367,,complete list}; here's a sample:


@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{b}

@tab

Format binaire. Affiche le nombre en base 2.

@item

@code{c}

@tab

Caractère. Convertit l'entier en le caractère Unicode associé avant de l'afficher.

@item

@code{d}

@tab

Entier décimal. Affiche le nombre en base 10.

@item

@code{o}

@tab

Format octal. Affiche le nombre en base 8.

@item

@code{x}

@tab

Format hexadécimal. Affiche le nombre en base 16 en utilisant les lettres minuscules pour les chiffres au-dessus de 9.

@item

@code{e}

@tab

Exponent notation. Prints the number in scientific notation using the
letter 'e' to indicate the exponent.

@item

@code{g}

@tab

General format. This prints the number as a fixed-point number, unless
the number is too large, in which case it switches to 'e' exponent
notation.

@item

@code{n}

@tab

Number. This is the same as 'g' (for floats) or 'd' (for integers),
except that it uses the current locale setting to insert the appropriate
number separator characters.

@item

@code{%}

@tab

Pourcentage. Multiplie le nombre par 100 et l'affiche en virgule fixe ('f'), suivi d'un symbole pourcent @code{'%'}.

@end multitable


Classes and types can define a @code{__format__()} method to control how they're
formatted.  It receives a single argument, the format specifier:

@example
def __format__(self, format_spec):
    if isinstance(format_spec, unicode):
        return unicode(str(self))
    else:
        return str(self)
@end example

There's also a @ref{60a,,format()} builtin that will format a single
value.  It calls the type's @code{__format__()} method with the
provided specifier:

@example
>>> format(75.6564, '.2f')
'75.66'
@end example


@subsubheading Voir aussi



@table @asis

@item @ref{1367,,Syntaxe de formatage de chaîne}

The reference documentation for format fields.

@geindex Python Enhancement Proposals; PEP 3101

@item PEP 3101@footnote{https://peps.python.org/pep-3101/} - Advanced String Formatting

PEP written by Talin. Implemented by Eric Smith.
@end table


@c ======================================================================

@node PEP 3105 print As a Function,PEP 3110 Exception-Handling Changes,PEP 3101 Advanced String Formatting,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3105}@anchor{1293}@anchor{whatsnew/2 6 pep-3105-print-as-a-function}@anchor{1368}
@subsection PEP 3105: @code{print} As a Function


The @code{print} statement becomes the @ref{f60,,print()} function in Python 3.0.
Making @ref{f60,,print()} a function makes it possible to replace the function
by doing @code{def print(...)} or importing a new function from somewhere else.

Python 2.6 has a @code{__future__} import that removes @code{print} as language
syntax, letting you use the functional form instead.  For example:

@example
>>> from __future__ import print_function
>>> print('# of entries', len(dictionary), file=sys.stderr)
@end example

The signature of the new function is:

@example
def print(*args, sep=' ', end='\n', file=None)
@end example

The parameters are:


@itemize *

@item 
`args': positional arguments whose values will be printed out.

@item 
`sep': the separator, which will be printed between arguments.

@item 
`end': the ending text, which will be printed after all of the
arguments have been output.

@item 
`file': the file object to which the output will be sent.
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3105

@item PEP 3105@footnote{https://peps.python.org/pep-3105/} - Make print a function

PEP written by Georg Brandl.
@end table


@c ======================================================================

@node PEP 3110 Exception-Handling Changes,PEP 3112 Byte Literals,PEP 3105 print As a Function,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3110}@anchor{1294}@anchor{whatsnew/2 6 pep-3110-exception-handling-changes}@anchor{1369}
@subsection PEP 3110: Exception-Handling Changes


One error that Python programmers occasionally make
is writing the following code:

@example
try:
    ...
except TypeError, ValueError:  # Wrong!
    ...
@end example

The author is probably trying to catch both @ref{522,,TypeError} and
@ref{1ff,,ValueError} exceptions, but this code actually does something
different: it will catch @ref{522,,TypeError} and bind the resulting
exception object to the local name @code{"ValueError"}.  The
@ref{1ff,,ValueError} exception will not be caught at all.  The correct
code specifies a tuple of exceptions:

@example
try:
    ...
except (TypeError, ValueError):
    ...
@end example

This error happens because the use of the comma here is ambiguous:
does it indicate two different nodes in the parse tree, or a single
node that's a tuple?

Python 3.0 makes this unambiguous by replacing the comma with the word
"as".  To catch an exception and store the exception object in the
variable @code{exc}, you must write:

@example
try:
    ...
except TypeError as exc:
    ...
@end example

Python 3.0 will only support the use of "as", and therefore interprets
the first example as catching two different exceptions.  Python 2.6
supports both the comma and "as", so existing code will continue to
work.  We therefore suggest using "as" when writing new Python code
that will only be executed with 2.6.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3110

@item PEP 3110@footnote{https://peps.python.org/pep-3110/} - Catching Exceptions in Python 3000

PEP written and implemented by Collin Winter.
@end table


@c ======================================================================

@node PEP 3112 Byte Literals,PEP 3116 New I/O Library,PEP 3110 Exception-Handling Changes,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3112}@anchor{1295}@anchor{whatsnew/2 6 pep-3112-byte-literals}@anchor{136a}
@subsection PEP 3112: Byte Literals


Python 3.0 adopts Unicode as the language's fundamental string type and
denotes 8-bit literals differently, either as @code{b'string'}
or using a @ref{1bd,,bytes} constructor.  For future compatibility,
Python 2.6 adds @ref{1bd,,bytes} as a synonym for the @ref{435,,str} type,
and it also supports the @code{b'@w{'}} notation.

The 2.6 @ref{435,,str} differs from 3.0's @ref{1bd,,bytes} type in various
ways; most notably, the constructor is completely different.  In 3.0,
@code{bytes([65, 66, 67])} is 3 elements long, containing the bytes
representing @code{ABC}; in 2.6, @code{bytes([65, 66, 67])} returns the
12-byte string representing the @ref{435,,str()} of the list.

The primary use of @ref{1bd,,bytes} in 2.6 will be to write tests of
object type such as @code{isinstance(x, bytes)}.  This will help the 2to3
converter, which can't tell whether 2.x code intends strings to
contain either characters or 8-bit bytes; you can now
use either @ref{1bd,,bytes} or @ref{435,,str} to represent your intention
exactly, and the resulting code will also be correct in Python 3.0.

There's also a @code{__future__} import that causes all string literals
to become Unicode strings.  This means that @code{\u} escape sequences
can be used to include Unicode characters:

@example
from __future__ import unicode_literals

s = ('\u751f\u3080\u304e\u3000\u751f\u3054'
     '\u3081\u3000\u751f\u305f\u307e\u3054')

print len(s)               # 12 Unicode characters
@end example

At the C level, Python 3.0 will rename the existing 8-bit
string type, called @code{PyStringObject} in Python 2.x,
to @ref{77c,,PyBytesObject}.  Python 2.6 uses @code{#define}
to support using the names @ref{77c,,PyBytesObject()},
@ref{136b,,PyBytes_Check()}, @ref{136c,,PyBytes_FromStringAndSize()},
and all the other functions and macros used with strings.

Instances of the @ref{1bd,,bytes} type are immutable just
as strings are.  A new @ref{528,,bytearray} type stores a mutable
sequence of bytes:

@example
>>> bytearray([65, 66, 67])
bytearray(b'ABC')
>>> b = bytearray(u'\u21ef\u3244', 'utf-8')
>>> b
bytearray(b'\xe2\x87\xaf\xe3\x89\x84')
>>> b[0] = '\xe3'
>>> b
bytearray(b'\xe3\x87\xaf\xe3\x89\x84')
>>> unicode(str(b), 'utf-8')
u'\u31ef \u3244'
@end example

Byte arrays support most of the methods of string types, such as
@code{startswith()}/@code{endswith()}, @code{find()}/@code{rfind()},
and some of the methods of lists, such as @code{append()},
@code{pop()},  and @code{reverse()}.

@example
>>> b = bytearray('ABC')
>>> b.append('d')
>>> b.append(ord('e'))
>>> b
bytearray(b'ABCde')
@end example

There's also a corresponding C API, with
@ref{136d,,PyByteArray_FromObject()},
@ref{136e,,PyByteArray_FromStringAndSize()},
and various other functions.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3112

@item PEP 3112@footnote{https://peps.python.org/pep-3112/} - Bytes literals in Python 3000

PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes.
@end table


@c ======================================================================

@node PEP 3116 New I/O Library,PEP 3118 Revised Buffer Protocol,PEP 3112 Byte Literals,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3116}@anchor{1296}@anchor{whatsnew/2 6 pep-3116-new-i-o-library}@anchor{136f}
@subsection PEP 3116: New I/O Library


Python's built-in file objects support a number of methods, but
file-like objects don't necessarily support all of them.  Objects that
imitate files usually support @code{read()} and @code{write()}, but they
may not support @ref{b9,,readline()}, for example.  Python 3.0 introduces
a layered I/O library in the @ref{7e,,io} module that separates buffering
and text-handling features from the fundamental read and write
operations.

There are three levels of abstract base classes provided by
the @ref{7e,,io} module:


@itemize *

@item 
@code{RawIOBase} defines raw I/O operations: @code{read()},
@code{readinto()},
@code{write()}, @code{seek()}, @code{tell()}, @code{truncate()},
and @code{close()}.
Most of the methods of this class will often map to a single system call.
There are also @code{readable()}, @code{writable()}, and @code{seekable()}
methods for determining what operations a given object will allow.

Python 3.0 has concrete implementations of this class for files and
sockets, but Python 2.6 hasn't restructured its file and socket objects
in this way.

@item 
@code{BufferedIOBase} is an abstract base class that
buffers data in memory to reduce the number of
system calls used, making I/O processing more efficient.
It supports all of the methods of @code{RawIOBase},
and adds a @code{raw} attribute holding the underlying raw object.

There are five concrete classes implementing this ABC.
@code{BufferedWriter} and @code{BufferedReader} are for objects
that support write-only or read-only usage that have a @code{seek()}
method for random access.  @code{BufferedRandom} objects support
read and write access upon the same underlying stream, and
@code{BufferedRWPair} is for objects such as TTYs that have both
read and write operations acting upon unconnected streams of data.
The @code{BytesIO} class supports reading, writing, and seeking
over an in-memory buffer.

@geindex universal newlines;What's new

@item 
@code{TextIOBase}: Provides functions for reading and writing
strings (remember, strings will be Unicode in Python 3.0),
and supporting @ref{d28,,universal newlines}.  @code{TextIOBase} defines
the @ref{b9,,readline()} method and supports iteration upon
objects.

There are two concrete implementations.  @code{TextIOWrapper}
wraps a buffered I/O object, supporting all of the methods for
text I/O and adding a @code{buffer} attribute for access
to the underlying object.  @code{StringIO} simply buffers
everything in memory without ever writing anything to disk.

(In Python 2.6, @ref{f12,,io.StringIO} is implemented in
pure Python, so it's pretty slow.   You should therefore stick with the
existing @code{StringIO} module or @code{cStringIO} for now.  At some
point Python 3.0's @ref{7e,,io} module will be rewritten into C for speed,
and perhaps the C implementation will be  backported to the 2.x releases.)
@end itemize

In Python 2.6, the underlying implementations haven't been
restructured to build on top of the @ref{7e,,io} module's classes.  The
module is being provided to make it easier to write code that's
forward-compatible with 3.0, and to save developers the effort of writing
their own implementations of buffering and text I/O.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3116

@item PEP 3116@footnote{https://peps.python.org/pep-3116/} - New I/O

PEP written by Daniel Stutzbach, Mike Verdone, and Guido van Rossum.
Code by Guido van Rossum, Georg Brandl, Walter Doerwald,
Jeremy Hylton, Martin von Löwis, Tony Lownds, and others.
@end table


@c ======================================================================

@node PEP 3118 Revised Buffer Protocol,PEP 3119 Abstract Base Classes,PEP 3116 New I/O Library,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3118}@anchor{1297}@anchor{whatsnew/2 6 pep-3118-revised-buffer-protocol}@anchor{1370}
@subsection PEP 3118: Revised Buffer Protocol


The buffer protocol is a C-level API that lets Python types
exchange pointers into their internal representations.  A
memory-mapped file can be viewed as a buffer of characters, for
example, and this lets another module such as @ref{b8,,re}
treat memory-mapped files as a string of characters to be searched.

The primary users of the buffer protocol are numeric-processing
packages such as NumPy, which expose the internal representation
of arrays so that callers can write data directly into an array instead
of going through a slower API.  This PEP updates the buffer protocol in light of experience
from NumPy development, adding a number of new features
such as indicating the shape of an array or locking a memory region.

The most important new C API function is
@code{PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)}, which
takes an object and a set of flags, and fills in the
@code{Py_buffer} structure with information
about the object's memory representation.  Objects
can use this operation to lock memory in place
while an external caller could be modifying the contents,
so there's a corresponding @code{PyBuffer_Release(Py_buffer *view)} to
indicate that the external caller is done.

The `flags' argument to @ref{390,,PyObject_GetBuffer()} specifies
constraints upon the memory returned.  Some examples are:


@itemize *

@item 
@ref{1371,,PyBUF_WRITABLE} indicates that the memory must be writable.

@item 
@code{PyBUF_LOCK} requests a read-only or exclusive lock on the memory.

@item 
@ref{1372,,PyBUF_C_CONTIGUOUS} and @ref{1373,,PyBUF_F_CONTIGUOUS}
requests a C-contiguous (last dimension varies the fastest) or
Fortran-contiguous (first dimension varies the fastest) array layout.
@end itemize

Two new argument codes for @ref{55d,,PyArg_ParseTuple()},
@code{s*} and @code{z*}, return locked buffer objects for a parameter.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3118

@item PEP 3118@footnote{https://peps.python.org/pep-3118/} - Revising the buffer protocol

PEP written by Travis Oliphant and Carl Banks; implemented by
Travis Oliphant.
@end table


@c ======================================================================

@node PEP 3119 Abstract Base Classes,PEP 3127 Integer Literal Support and Syntax,PEP 3118 Revised Buffer Protocol,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3119}@anchor{1298}@anchor{whatsnew/2 6 pep-3119-abstract-base-classes}@anchor{1374}
@subsection PEP 3119: Abstract Base Classes


Some object-oriented languages such as Java support interfaces,
declaring that a class has a given set of methods or supports a given
access protocol.  Abstract Base Classes (or ABCs) are an equivalent
feature for Python. The ABC support consists of an @ref{4,,abc} module
containing a metaclass called @code{ABCMeta}, special handling of
this metaclass by the @ref{42b,,isinstance()} and @ref{7ab,,issubclass()}
builtins, and a collection of basic ABCs that the Python developers
think will be widely useful.  Future versions of Python will probably
add more ABCs.

Let's say you have a particular class and wish to know whether it supports
dictionary-style access.  The phrase "dictionary-style" is vague, however.
It probably means that accessing items with @code{obj[1]} works.
Does it imply that setting items with @code{obj[2] = value} works?
Or that the object will have @code{keys()}, @code{values()}, and @code{items()}
methods?  What about the iterative variants  such as @code{iterkeys()}?  @ref{25,,copy()}
and @code{update()}?  Iterating over the object with @ref{7c1,,iter()}?

The Python 2.6 @ref{1d,,collections} module includes a number of
different ABCs that represent these distinctions.  @code{Iterable}
indicates that a class defines @code{__iter__()}, and
@code{Container} means the class defines a @code{__contains__()}
method and therefore supports @code{x in y} expressions.  The basic
dictionary interface of getting items, setting items, and
@code{keys()}, @code{values()}, and @code{items()}, is defined by the
@code{MutableMapping} ABC.

You can derive your own classes from a particular ABC
to indicate they support that ABC's interface:

@example
import collections

class Storage(collections.MutableMapping):
    ...
@end example

Alternatively, you could write the class without deriving from
the desired ABC and instead register the class by
calling the ABC's @code{register()} method:

@example
import collections

class Storage:
    ...

collections.MutableMapping.register(Storage)
@end example

For classes that you write, deriving from the ABC is probably clearer.
The @code{register()}  method is useful when you've written a new
ABC that can describe an existing type or class, or if you want
to declare that some third-party class implements an ABC.
For example, if you defined a @code{PrintableType} ABC,
it's legal to do:

@example
# Register Python's types
PrintableType.register(int)
PrintableType.register(float)
PrintableType.register(str)
@end example

Classes should obey the semantics specified by an ABC, but
Python can't check this; it's up to the class author to
understand the ABC's requirements and to implement the code accordingly.

To check whether an object supports a particular interface, you can
now write:

@example
def func(d):
    if not isinstance(d, collections.MutableMapping):
        raise ValueError("Mapping object expected, not %r" % d)
@end example

Don't feel that you must now begin writing lots of checks as in the
above example.  Python has a strong tradition of duck-typing, where
explicit type-checking is never done and code simply calls methods on
an object, trusting that those methods will be there and raising an
exception if they aren't.  Be judicious in checking for ABCs and only
do it where it's absolutely necessary.

You can write your own ABCs by using @code{abc.ABCMeta} as the
metaclass in a class definition:

@example
from abc import ABCMeta, abstractmethod

class Drawable():
    __metaclass__ = ABCMeta

    @@abstractmethod
    def draw(self, x, y, scale=1.0):
        pass

    def draw_doubled(self, x, y):
        self.draw(x, y, scale=2.0)


class Square(Drawable):
    def draw(self, x, y, scale):
        ...
@end example

In the @code{Drawable} ABC above, the @code{draw_doubled()} method
renders the object at twice its size and can be implemented in terms
of other methods described in @code{Drawable}.  Classes implementing
this ABC therefore don't need to provide their own implementation
of @code{draw_doubled()}, though they can do so.  An implementation
of @code{draw()} is necessary, though; the ABC can't provide
a useful generic implementation.

You can apply the @code{@@abstractmethod} decorator to methods such as
@code{draw()} that must be implemented; Python will then raise an
exception for classes that don't define the method.
Note that the exception is only raised when you actually
try to create an instance of a subclass lacking the method:

@example
>>> class Circle(Drawable):
...     pass
...
>>> c = Circle()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Can't instantiate abstract class Circle with abstract methods draw
>>>
@end example

Abstract data attributes can be declared using the
@code{@@abstractproperty} decorator:

@example
from abc import abstractproperty
...

@@abstractproperty
def readonly(self):
   return self._x
@end example

Subclasses must then define a @code{readonly()} property.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3119

@item PEP 3119@footnote{https://peps.python.org/pep-3119/} -- Introduction aux classes de bases abstraites

PEP written by Guido van Rossum and Talin.
Implemented by Guido van Rossum.
Backported to 2.6 by Benjamin Aranguren, with Alex Martelli.
@end table


@c ======================================================================

@node PEP 3127 Integer Literal Support and Syntax,PEP 3129 Class Decorators,PEP 3119 Abstract Base Classes,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3127}@anchor{1299}@anchor{whatsnew/2 6 pep-3127-integer-literal-support-and-syntax}@anchor{1375}
@subsection PEP 3127: Integer Literal Support and Syntax


Python 3.0 changes the syntax for octal (base-8) integer literals,
prefixing them with "0o" or "0O" instead of a leading zero, and adds
support for binary (base-2) integer literals, signalled by a "0b" or
"0B" prefix.

Python 2.6 doesn't drop support for a leading 0 signalling
an octal number, but it does add support for "0o" and "0b":

@example
>>> 0o21, 2*8 + 1
(17, 17)
>>> 0b101111
47
@end example

The @ref{12ac,,oct()} builtin still returns numbers
prefixed with a leading zero, and a new @ref{1286,,bin()}
builtin returns the binary representation for a number:

@example
>>> oct(42)
'052'
>>> future_builtins.oct(42)
'0o52'
>>> bin(173)
'0b10101101'
@end example

The @ref{254,,int()} and @code{long()} builtins will now accept the "0o"
and "0b" prefixes when base-8 or base-2 are requested, or when the
`base' argument is zero (signalling that the base used should be
determined from the string):

@example
>>> int ('0o52', 0)
42
>>> int('1101', 2)
13
>>> int('0b1101', 2)
13
>>> int('0b1101', 0)
13
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3127

@item PEP 3127@footnote{https://peps.python.org/pep-3127/} - Integer Literal Support and Syntax

PEP written by Patrick Maupin; backported to 2.6 by
Eric Smith.
@end table


@c ======================================================================

@node PEP 3129 Class Decorators,PEP 3141 A Type Hierarchy for Numbers,PEP 3127 Integer Literal Support and Syntax,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3129}@anchor{129a}@anchor{whatsnew/2 6 pep-3129-class-decorators}@anchor{1376}
@subsection PEP 3129: Class Decorators


Decorators have been extended from functions to classes.  It's now legal to
write:

@example
@@foo
@@bar
class A:
  pass
@end example

C’est équivalent à :

@example
class A:
  pass

A = foo(bar(A))
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3129

@item PEP 3129@footnote{https://peps.python.org/pep-3129/} -- Décorateurs de classes

PEP written by Collin Winter.
@end table


@c ======================================================================

@node PEP 3141 A Type Hierarchy for Numbers,Autres changements au langage<15>,PEP 3129 Class Decorators,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 pep-3141}@anchor{129b}@anchor{whatsnew/2 6 pep-3141-a-type-hierarchy-for-numbers}@anchor{1377}
@subsection PEP 3141: A Type Hierarchy for Numbers


Python 3.0 adds several abstract base classes for numeric types
inspired by Scheme's numeric tower.  These classes were backported to
2.6 as the @ref{9d,,numbers} module.

The most general ABC is @code{Number}.  It defines no operations at
all, and only exists to allow checking if an object is a number by
doing @code{isinstance(obj, Number)}.

@code{Complex} is a subclass of @code{Number}.  Complex numbers
can undergo the basic operations of addition, subtraction,
multiplication, division, and exponentiation, and you can retrieve the
real and imaginary parts and obtain a number's conjugate.  Python's built-in
complex type is an implementation of @code{Complex}.

@code{Real} further derives from @code{Complex}, and adds
operations that only work on real numbers: @code{floor()}, @code{trunc()},
rounding, taking the remainder mod N, floor division,
and comparisons.

@code{Rational} numbers derive from @code{Real}, have
@code{numerator} and @code{denominator} properties, and can be
converted to floats.  Python 2.6 adds a simple rational-number class,
@code{Fraction}, in the @ref{5c,,fractions} module.  (It's called
@code{Fraction} instead of @code{Rational} to avoid
a name clash with @ref{129c,,numbers.Rational}.)

@code{Integral} numbers derive from @code{Rational}, and
can be shifted left and right with @code{<<} and @code{>>},
combined using bitwise operations such as @code{&} and @code{|},
and can be used as array indexes and slice boundaries.

In Python 3.0, the PEP slightly redefines the existing builtins
@ref{12b8,,round()}, @ref{1378,,math.floor()}, @ref{1379,,math.ceil()}, and adds a new
one, @ref{137a,,math.trunc()}, that's been backported to Python 2.6.
@ref{137a,,math.trunc()} rounds toward zero, returning the closest
@code{Integral} that's between the function's argument and zero.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3141

@item PEP 3141@footnote{https://peps.python.org/pep-3141/} - A Type Hierarchy for Numbers

PEP written by Jeffrey Yasskin.
@end table

Scheme's numerical tower@footnote{https://www.gnu.org/software/guile/manual/html_node/Numerical-Tower.html#Numerical-Tower}, from the Guile manual.

Scheme's number datatypes@footnote{https://conservatory.scheme.org/schemers/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_sec_6.2} from the R5RS Scheme specification.


@menu
* The fractions Module:: 

@end menu

@node The fractions Module,,,PEP 3141 A Type Hierarchy for Numbers
@anchor{whatsnew/2 6 the-fractions-module}@anchor{137b}
@subsubsection The @code{fractions} Module


To fill out the hierarchy of numeric types, the @ref{5c,,fractions}
module provides a rational-number class.  Rational numbers store their
values as a numerator and denominator forming a fraction, and can
exactly represent numbers such as @code{2/3} that floating-point numbers
can only approximate.

The @code{Fraction} constructor takes two @code{Integral} values
that will be the numerator and denominator of the resulting fraction.

@example
>>> from fractions import Fraction
>>> a = Fraction(2, 3)
>>> b = Fraction(2, 5)
>>> float(a), float(b)
(0.66666666666666663, 0.40000000000000002)
>>> a+b
Fraction(16, 15)
>>> a/b
Fraction(5, 3)
@end example

For converting floating-point numbers to rationals,
the float type now has an @code{as_integer_ratio()} method that returns
the numerator and denominator for a fraction that evaluates to the same
floating-point value:

@example
>>> (2.5) .as_integer_ratio()
(5, 2)
>>> (3.1415) .as_integer_ratio()
(7074029114692207L, 2251799813685248L)
>>> (1./3) .as_integer_ratio()
(6004799503160661L, 18014398509481984L)
@end example

Note that values that can only be approximated by floating-point
numbers, such as 1./3, are not simplified to the number being
approximated; the fraction attempts to match the floating-point value
`exactly'.

The @ref{5c,,fractions} module is based upon an implementation by Sjoerd
Mullender that was in Python's @code{Demo/classes/} directory for a
long time.  This implementation was significantly updated by Jeffrey
Yasskin.

@node Autres changements au langage<15>,New and Improved Modules<2>,PEP 3141 A Type Hierarchy for Numbers,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 other-language-changes}@anchor{137c}
@subsection Autres changements au langage


Some smaller changes made to the core Python language are:


@itemize *

@item 
Directories and zip archives containing a @code{__main__.py} file
can now be executed directly by passing their name to the
interpreter. The directory or zip archive is automatically inserted
as the first entry in sys.path.  (Suggestion and initial patch by
Andy Chu, subsequently revised by Phillip J. Eby and Nick Coghlan;
bpo-1739468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1739468}.)

@item 
The @ref{4bb,,hasattr()} function was catching and ignoring all errors,
under the assumption that they meant a @code{__getattr__()} method
was failing somehow and the return value of @ref{4bb,,hasattr()} would
therefore be @code{False}.  This logic shouldn't be applied to
@ref{9bf,,KeyboardInterrupt} and @ref{d2e,,SystemExit}, however; Python 2.6
will no longer discard such exceptions when @ref{4bb,,hasattr()}
encounters them.  (Fixed by Benjamin Peterson; bpo-2196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2196}.)

@item 
When calling a function using the @code{**} syntax to provide keyword
arguments, you are no longer required to use a Python dictionary;
any mapping will now work:

@example
>>> def f(**kw):
...    print sorted(kw)
...
>>> ud=UserDict.UserDict()
>>> ud['a'] = 1
>>> ud['b'] = 'string'
>>> f(**ud)
['a', 'b']
@end example

(Contribution par Alexander Belopolsky; bpo-1686487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1686487}.)

It's also become legal to provide keyword arguments after a @code{*args} argument
to a function call.

@example
>>> def f(*args, **kw):
...     print args, kw
...
>>> f(1,2,3, *(4,5,6), keyword=13)
(1, 2, 3, 4, 5, 6) @{'keyword': 13@}
@end example

Previously this would have been a syntax error.
(Contributed by Amaury Forgeot d'Arc; bpo-3473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3473}.)

@item 
A new builtin, @code{next(iterator, [default])} returns the next item
from the specified iterator.  If the `default' argument is supplied,
it will be returned if `iterator' has been exhausted; otherwise,
the @ref{be8,,StopIteration} exception will be raised.  (Backported
in bpo-2719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2719}.)

@item 
Tuples now have @code{index()} and @code{count()} methods matching the
list type's @code{index()} and @code{count()} methods:

@example
>>> t = (0,1,2,3,4,0,1,2)
>>> t.index(3)
3
>>> t.count(0)
2
@end example

(Contributed by Raymond Hettinger)

@item 
The built-in types now have improved support for extended slicing syntax,
accepting various combinations of @code{(start, stop, step)}.
Previously, the support was partial and certain corner cases wouldn't work.
(Implemented by Thomas Wouters.)

@c Revision 57619

@item 
Properties now have three attributes, @code{getter}, @code{setter}
and @code{deleter}, that are decorators providing useful shortcuts
for adding a getter, setter or deleter function to an existing
property. You would use them like this:

@example
class C(object):
    @@property
    def x(self):
        return self._x

    @@x.setter
    def x(self, value):
        self._x = value

    @@x.deleter
    def x(self):
        del self._x

class D(C):
    @@C.x.getter
    def x(self):
        return self._x * 2

    @@x.setter
    def x(self, value):
        self._x = value / 2
@end example

@item 
Several methods of the built-in set types now accept multiple iterables:
@code{intersection()},
@code{intersection_update()},
@code{union()}, @code{update()},
@code{difference()} and @code{difference_update()}.

@example
>>> s=set('1234567890')
>>> s.intersection('abc123', 'cdf246')  # Intersection between all inputs
set(['2'])
>>> s.difference('246', '789')
set(['1', '0', '3', '5'])
@end example

(Contributed by Raymond Hettinger.)

@item 
Many floating-point features were added.  The @ref{2eb,,float()} function
will now turn the string @code{nan} into an
IEEE 754 Not A Number value, and @code{+inf} and @code{-inf} into
positive or negative infinity.  This works on any platform with
IEEE 754 semantics.  (Contributed by Christian Heimes; bpo-1635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635}.)

Other functions in the @ref{8d,,math} module, @code{isinf()} and
@code{isnan()}, return true if their floating-point argument is
infinite or Not A Number.  (bpo-1640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1640})

Conversion functions were added to convert floating-point numbers
into hexadecimal strings (bpo-3008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3008}).  These functions
convert floats to and from a string representation without
introducing rounding errors from the conversion between decimal and
binary.  Floats have a @ref{12ad,,hex()} method that returns a string
representation, and the @code{float.fromhex()} method converts a string
back into a number:

@example
>>> a = 3.75
>>> a.hex()
'0x1.e000000000000p+1'
>>> float.fromhex('0x1.e000000000000p+1')
3.75
>>> b=1./3
>>> b.hex()
'0x1.5555555555555p-2'
@end example

@item 
A numerical nicety: when creating a complex number from two floats
on systems that support signed zeros (-0 and +0), the
@ref{2ec,,complex()} constructor will now preserve the sign
of the zero.  (Fixed by Mark T. Dickinson; bpo-1507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1507}.)

@item 
Classes that inherit a @code{__hash__()} method from a parent class
can set @code{__hash__ = None} to indicate that the class isn't
hashable.  This will make @code{hash(obj)} raise a @ref{522,,TypeError}
and the class will not be indicated as implementing the
@code{Hashable} ABC.

You should do this when you've defined a @code{__cmp__()} or
@code{__eq__()} method that compares objects by their value rather
than by identity.  All objects have a default hash method that uses
@code{id(obj)} as the hash value.  There's no tidy way to remove the
@code{__hash__()} method inherited from a parent class, so
assigning @code{None} was implemented as an override.  At the
C level, extensions can set @code{tp_hash} to
@ref{137d,,PyObject_HashNotImplemented()}.
(Fixed by Nick Coghlan and Amaury Forgeot d'Arc; bpo-2235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2235}.)

@item 
The @ref{137e,,GeneratorExit} exception now subclasses
@ref{5a5,,BaseException} instead of @ref{9c7,,Exception}.  This means
that an exception handler that does @code{except Exception:}
will not inadvertently catch @ref{137e,,GeneratorExit}.
(Contributed by Chad Austin; bpo-1537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1537}.)

@item 
Generator objects now have a @code{gi_code} attribute that refers to
the original code object backing the generator.
(Contributed by Collin Winter; bpo-1473257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1473257}.)

@item 
The @ref{190,,compile()} built-in function now accepts keyword arguments
as well as positional parameters.  (Contributed by Thomas Wouters;
bpo-1444529@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1444529}.)

@item 
The @ref{2ec,,complex()} constructor now accepts strings containing
parenthesized complex numbers, meaning that @code{complex(repr(cplx))}
will now round-trip values.  For example, @code{complex('(3+4j)')}
now returns the value (3+4j).  (bpo-1491866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1491866})

@item 
The string @code{translate()} method now accepts @code{None} as the
translation table parameter, which is treated as the identity
transformation.   This makes it easier to carry out operations
that only delete characters.  (Contributed by Bengt Richter and
implemented by Raymond Hettinger; bpo-1193128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1193128}.)

@item 
The built-in @ref{61d,,dir()} function now checks for a @code{__dir__()}
method on the objects it receives.  This method must return a list
of strings containing the names of valid attributes for the object,
and lets the object control the value that @ref{61d,,dir()} produces.
Objects that have @code{__getattr__()} or @code{__getattribute__()}
methods can use this to advertise pseudo-attributes they will honor.
(bpo-1591665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1591665})

@item 
Instance method objects have new attributes for the object and function
comprising the method; the new synonym for @code{im_self} is
@ref{137f,,__self__}, and @code{im_func} is also available as
@ref{12da,,__func__}.
The old names are still supported in Python 2.6, but are gone in 3.0.

@item 
An obscure change: when you use the @ref{140,,locals()} function inside a
@ref{12b5,,class} statement, the resulting dictionary no longer returns free
variables.  (Free variables, in this case, are variables referenced in the
@code{class} statement  that aren't attributes of the class.)
@end itemize

@c ======================================================================

@menu
* Optimizations: Optimizations<9>. 
* Interpreter Changes: Interpreter Changes<2>. 

@end menu

@node Optimizations<9>,Interpreter Changes<2>,,Autres changements au langage<15>
@anchor{whatsnew/2 6 optimizations}@anchor{1380}
@subsubsection Optimizations



@itemize *

@item 
The @ref{111,,warnings} module has been rewritten in C.  This makes
it possible to invoke warnings from the parser, and may also
make the interpreter's startup faster.
(Contributed by Neal Norwitz and Brett Cannon; bpo-1631171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1631171}.)

@item 
Type objects now have a cache of methods that can reduce
the work required to find the correct method implementation
for a particular class; once cached, the interpreter doesn't need to
traverse base classes to figure out the right method to call.
The cache is cleared if a base class or the class itself is modified,
so the cache should remain correct even in the face of Python's dynamic
nature.
(Original optimization implemented by Armin Rigo, updated for
Python 2.6 by Kevin Jacobs; bpo-1700288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1700288}.)

By default, this change is only applied to types that are included with
the Python core.  Extension modules may not necessarily be compatible with
this cache,
so they must explicitly add @code{Py_TPFLAGS_HAVE_VERSION_TAG}
to the module's @code{tp_flags} field to enable the method cache.
(To be compatible with the method cache, the extension module's code
must not directly access and modify the @code{tp_dict} member of
any of the types it implements.  Most modules don't do this,
but it's impossible for the Python interpreter to determine that.
See bpo-1878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1878} for some discussion.)

@item 
Function calls that use keyword arguments are significantly faster
by doing a quick pointer comparison, usually saving the time of a
full string comparison.  (Contributed by Raymond Hettinger, after an
initial implementation by Antoine Pitrou; bpo-1819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1819}.)

@item 
All of the functions in the @ref{d4,,struct} module have been rewritten in
C, thanks to work at the Need For Speed sprint.
(Contributed by Raymond Hettinger.)

@item 
Some of the standard built-in types now set a bit in their type
objects.  This speeds up checking whether an object is a subclass of
one of these types.  (Contributed by Neal Norwitz.)

@item 
Unicode strings now use faster code for detecting
whitespace and line breaks; this speeds up the @code{split()} method
by about 25% and @code{splitlines()} by 35%.
(Contributed by Antoine Pitrou.)  Memory usage is reduced
by using pymalloc for the Unicode string's data.

@item 
The @code{with} statement now stores the @ref{12de,,__exit__()} method on the stack,
producing a small speedup.  (Implemented by Jeffrey Yasskin.)

@item 
To reduce memory usage, the garbage collector will now clear internal
free lists when garbage-collecting the highest generation of objects.
This may return memory to the operating system sooner.
@end itemize

@c ======================================================================

@node Interpreter Changes<2>,,Optimizations<9>,Autres changements au langage<15>
@anchor{whatsnew/2 6 interpreter-changes}@anchor{1381}@anchor{whatsnew/2 6 new-26-interpreter}@anchor{1382}
@subsubsection Interpreter Changes


Two command-line options have been reserved for use by other Python
implementations.  The @ref{1383,,-J} switch has been reserved for use by
Jython for Jython-specific options, such as switches that are passed to
the underlying JVM.  @ref{175,,-X} has been reserved for options
specific to a particular implementation of Python such as CPython,
Jython, or IronPython.  If either option is used with Python 2.6, the
interpreter will report that the option isn't currently used.

Python can now be prevented from writing @code{.pyc} or @code{.pyo}
files by supplying the @ref{1384,,-B} switch to the Python interpreter,
or by setting the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@ref{1385,,PYTHONDONTWRITEBYTECODE} environment
variable before running the interpreter.  This setting is available to
Python programs as the @code{sys.dont_write_bytecode} variable, and
Python code can change the value to modify the interpreter's
behaviour.  (Contributed by Neal Norwitz and Georg Brandl.)

The encoding used for standard input, output, and standard error can
be specified by setting the 
@geindex PYTHONIOENCODING
@geindex variable d'environnement; PYTHONIOENCODING
@ref{ff3,,PYTHONIOENCODING} environment
variable before running the interpreter.  The value should be a string
in the form @code{<encoding>} or @code{<encoding>:<errorhandler>}.
The `encoding' part specifies the encoding's name, e.g. @code{utf-8} or
@code{latin-1}; the optional `errorhandler' part specifies
what to do with characters that can't be handled by the encoding,
and  should be one of "error", "ignore", or "replace".   (Contributed
by Martin von Löwis.)

@c ======================================================================

@node New and Improved Modules<2>,Deprecations and Removals,Autres changements au langage<15>,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 new-and-improved-modules}@anchor{1386}
@subsection New and Improved Modules


As in every release, Python's standard library received a number of
enhancements and bug fixes.  Here's a partial list of the most notable
changes, sorted alphabetically by module name. Consult the
@code{Misc/NEWS} file in the source tree for a more complete list of
changes, or look through the Subversion logs for all the details.


@itemize *

@item 
The @code{asyncore} and @code{asynchat} modules are
being actively maintained again, and a number of patches and bugfixes
were applied.  (Maintained by Josiah Carlson; see bpo-1736190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1736190} for
one patch.)

@item 
The @code{bsddb} module also has a new maintainer, Jesús Cea Avión, and the package
is now available as a standalone package.  The web page for the package is
www.jcea.es/programacion/pybsddb.htm@footnote{https://www.jcea.es/programacion/pybsddb.htm}.
The plan is to remove the package from the standard library
in Python 3.0, because its pace of releases is much more frequent than
Python's.

The @code{bsddb.dbshelve} module now uses the highest pickling protocol
available, instead of restricting itself to protocol 1.
(Contributed by W. Barnes.)

@item 
The @code{cgi} module will now read variables from the query string
of an HTTP POST request.  This makes it possible to use form actions
with URLs that include query strings such as
"/cgi-bin/add.py?category=1".  (Contributed by Alexandre Fiori and
Nubis; bpo-1817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1817}.)

The @code{parse_qs()} and @code{parse_qsl()} functions have been
relocated from the @code{cgi} module to the @ref{109,,urlparse} module.
The versions still available in the @code{cgi} module will
trigger @ref{8b5,,PendingDeprecationWarning} messages in 2.6
(bpo-600362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=600362}).

@item 
The @ref{18,,cmath} module underwent extensive revision,
contributed by Mark Dickinson and Christian Heimes.
Five new functions were added:


@itemize *

@item 
@code{polar()} converts a complex number to polar form, returning
the modulus and argument of the complex number.

@item 
@code{rect()} does the opposite, turning a modulus, argument pair
back into the corresponding complex number.

@item 
@code{phase()} returns the argument (also called the angle) of a complex
number.

@item 
@code{isnan()} returns True if either
the real or imaginary part of its argument is a NaN.

@item 
@code{isinf()} returns True if either the real or imaginary part of
its argument is infinite.
@end itemize

The revisions also improved the numerical soundness of the
@ref{18,,cmath} module.  For all functions, the real and imaginary
parts of the results are accurate to within a few units of least
precision (ulps) whenever possible.  See bpo-1381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1381} for the
details.  The branch cuts for @code{asinh()}, @code{atanh()}: and
@code{atan()} have also been corrected.

The tests for the module have been greatly expanded; nearly 2000 new
test cases exercise the algebraic functions.

On IEEE 754 platforms, the @ref{18,,cmath} module now handles IEEE 754
special values and floating-point exceptions in a manner consistent
with Annex 'G' of the C99 standard.

@item 
A new data type in the @ref{1d,,collections} module: @code{namedtuple(typename, fieldnames)}
is a factory function that creates subclasses of the standard tuple
whose fields are accessible by name as well as index.  For example:

@example
>>> var_type = collections.namedtuple('variable',
...             'id name type size')
>>> # Names are separated by spaces or commas.
>>> # 'id, name, type, size' would also work.
>>> var_type._fields
('id', 'name', 'type', 'size')

>>> var = var_type(1, 'frequency', 'int', 4)
>>> print var[0], var.id    # Equivalent
1 1
>>> print var[2], var.type  # Equivalent
int int
>>> var._asdict()
@{'size': 4, 'type': 'int', 'id': 1, 'name': 'frequency'@}
>>> v2 = var._replace(name='amplitude')
>>> v2
variable(id=1, name='amplitude', type='int', size=4)
@end example

Several places in the standard library that returned tuples have
been modified to return @code{namedtuple()} instances.  For example,
the @code{Decimal.as_tuple()} method now returns a named tuple with
@code{sign}, @code{digits}, and @code{exponent} fields.

(Contributed by Raymond Hettinger.)

@item 
Another change to the @ref{1d,,collections} module is that the
@code{deque} type now supports an optional `maxlen' parameter;
if supplied, the deque's size will be restricted to no more
than `maxlen' items.  Adding more items to a full deque causes
old items to be discarded.

@example
>>> from collections import deque
>>> dq=deque(maxlen=3)
>>> dq
deque([], maxlen=3)
>>> dq.append(1); dq.append(2); dq.append(3)
>>> dq
deque([1, 2, 3], maxlen=3)
>>> dq.append(4)
>>> dq
deque([2, 3, 4], maxlen=3)
@end example

(Contributed by Raymond Hettinger.)

@item 
The @ref{70,,Cookie} module's @ref{bf2,,Morsel} objects now support an
@ref{1387,,httponly} attribute.  In some browsers. cookies with this attribute
set cannot be accessed or manipulated by JavaScript code.
(Contributed by Arvin Schnell; bpo-1638033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1638033}.)

@item 
A new window method in the @ref{2b,,curses} module,
@code{chgat()}, changes the display attributes for a certain number of
characters on a single line.  (Contributed by Fabian Kreutz.)

@example
# Boldface text starting at y=0,x=21
# and affecting the rest of the line.
stdscr.chgat(0, 21, curses.A_BOLD)
@end example

The @code{Textbox} class in the @ref{2e,,curses.textpad} module
now supports editing in insert mode as well as overwrite mode.
Insert mode is enabled by supplying a true value for the `insert_mode'
parameter when creating the @code{Textbox} instance.

@item 
The @ref{30,,datetime} module's @code{strftime()} methods now support a
@code{%f} format code that expands to the number of microseconds in the
object, zero-padded on
the left to six places.  (Contributed by Skip Montanaro; bpo-1158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1158}.)

@item 
The @ref{36,,decimal} module was updated to version 1.66 of
the General Decimal Specification@footnote{https://speleotrove.com/decimal/decarith.html}.  New features
include some methods for some basic mathematical functions such as
@code{exp()} and @code{log10()}:

@example
>>> Decimal(1).exp()
Decimal("2.718281828459045235360287471")
>>> Decimal("2.7182818").ln()
Decimal("0.9999999895305022877376682436")
>>> Decimal(1000).log10()
Decimal("3")
@end example

The @code{as_tuple()} method of @code{Decimal} objects now returns a
named tuple with @code{sign}, @code{digits}, and @code{exponent} fields.

(Implemented by Facundo Batista and Mark Dickinson.  Named tuple
support added by Raymond Hettinger.)

@item 
The @ref{37,,difflib} module's @code{SequenceMatcher} class
now returns named tuples representing matches,
with @code{a}, @code{b}, and @code{size} attributes.
(Contributed by Raymond Hettinger.)

@item 
An optional @code{timeout} parameter, specifying a timeout measured in
seconds, was added to the @ref{8e7,,ftplib.FTP} class constructor as
well as the @code{connect()} method.  (Added by Facundo Batista.)
Also, the @code{FTP} class's @code{storbinary()} and
@code{storlines()} now take an optional `callback' parameter that
will be called with each block of data after the data has been sent.
(Contributed by Phil Schwartz; bpo-1221598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1221598}.)

@item 
The @code{reduce()} built-in function is also available in the
@ref{5e,,functools} module.  In Python 3.0, the builtin has been
dropped and @code{reduce()} is only available from @ref{5e,,functools};
currently there are no plans to drop the builtin in the 2.x series.
(Patched by Christian Heimes; bpo-1739906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1739906}.)

@item 
When possible, the @ref{61,,getpass} module will now use
@code{/dev/tty} to print a prompt message and read the password,
falling back to standard error and standard input.  If the
password may be echoed to the terminal, a warning is printed before
the prompt is displayed.  (Contributed by Gregory P. Smith.)

@item 
The @ref{29c,,glob.glob()} function can now return Unicode filenames if
a Unicode path was used and Unicode filenames are matched within the
directory.  (bpo-1001604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1001604})

@item 
A new function in the @ref{68,,heapq} module, @code{merge(iter1, iter2, ...)},
takes any number of iterables returning data in sorted
order, and returns a new generator that returns the contents of all
the iterators, also in sorted order.  For example:

@example
>>> list(heapq.merge([1, 3, 5, 9], [2, 8, 16]))
[1, 2, 3, 5, 8, 9, 16]
@end example

Another new function, @code{heappushpop(heap, item)},
pushes `item' onto `heap', then pops off and returns the smallest item.
This is more efficient than making a call to @code{heappush()} and then
@code{heappop()}.

@ref{68,,heapq} is now implemented to only use less-than comparison,
instead of the less-than-or-equal comparison it previously used.
This makes @ref{68,,heapq}'s usage of a type match the
@ref{bbd,,list.sort()} method.
(Contributed by Raymond Hettinger.)

@item 
An optional @code{timeout} parameter, specifying a timeout measured in
seconds, was added to the @ref{b2e,,httplib.HTTPConnection} and
@ref{b2f,,HTTPSConnection} class constructors.  (Added by Facundo
Batista.)

@item 
Most of the @ref{7d,,inspect} module's functions, such as
@code{getmoduleinfo()} and @code{getargs()}, now return named tuples.
In addition to behaving like tuples, the elements of the  return value
can also be accessed as attributes.
(Contributed by Raymond Hettinger.)

Some new functions in the module include
@code{isgenerator()}, @code{isgeneratorfunction()},
and @code{isabstract()}.

@item 
The @ref{80,,itertools} module gained several new functions.

@code{izip_longest(iter1, iter2, ...[, fillvalue])} makes tuples from
each of the elements; if some of the iterables are shorter than
others, the missing values are set to `fillvalue'.  For example:

@example
>>> tuple(itertools.izip_longest([1,2,3], [1,2,3,4,5]))
((1, 1), (2, 2), (3, 3), (None, 4), (None, 5))
@end example

@code{product(iter1, iter2, ..., [repeat=N])} returns the Cartesian product
of the supplied iterables, a set of tuples containing
every possible combination of the elements returned from each iterable.

@example
>>> list(itertools.product([1,2,3], [4,5,6]))
[(1, 4), (1, 5), (1, 6),
 (2, 4), (2, 5), (2, 6),
 (3, 4), (3, 5), (3, 6)]
@end example

The optional `repeat' keyword argument is used for taking the
product of an iterable or a set of iterables with themselves,
repeated `N' times.  With a single iterable argument, `N'-tuples
are returned:

@example
>>> list(itertools.product([1,2], repeat=3))
[(1, 1, 1), (1, 1, 2), (1, 2, 1), (1, 2, 2),
 (2, 1, 1), (2, 1, 2), (2, 2, 1), (2, 2, 2)]
@end example

With two iterables, `2N'-tuples are returned.

@example
>>> list(itertools.product([1,2], [3,4], repeat=2))
[(1, 3, 1, 3), (1, 3, 1, 4), (1, 3, 2, 3), (1, 3, 2, 4),
 (1, 4, 1, 3), (1, 4, 1, 4), (1, 4, 2, 3), (1, 4, 2, 4),
 (2, 3, 1, 3), (2, 3, 1, 4), (2, 3, 2, 3), (2, 3, 2, 4),
 (2, 4, 1, 3), (2, 4, 1, 4), (2, 4, 2, 3), (2, 4, 2, 4)]
@end example

@code{combinations(iterable, r)} returns sub-sequences of length `r' from
the elements of `iterable'.

@example
>>> list(itertools.combinations('123', 2))
[('1', '2'), ('1', '3'), ('2', '3')]
>>> list(itertools.combinations('123', 3))
[('1', '2', '3')]
>>> list(itertools.combinations('1234', 3))
[('1', '2', '3'), ('1', '2', '4'),
 ('1', '3', '4'), ('2', '3', '4')]
@end example

@code{permutations(iter[, r])} returns all the permutations of length `r' of
the iterable's elements.  If `r' is not specified, it will default to the
number of elements produced by the iterable.

@example
>>> list(itertools.permutations([1,2,3,4], 2))
[(1, 2), (1, 3), (1, 4),
 (2, 1), (2, 3), (2, 4),
 (3, 1), (3, 2), (3, 4),
 (4, 1), (4, 2), (4, 3)]
@end example

@code{itertools.chain(*iterables)} is an existing function in
@ref{80,,itertools} that gained a new constructor in Python 2.6.
@code{itertools.chain.from_iterable(iterable)} takes a single
iterable that should return other iterables.  @code{chain()} will
then return all the elements of the first iterable, then
all the elements of the second, and so on.

@example
>>> list(itertools.chain.from_iterable([[1,2,3], [4,5,6]]))
[1, 2, 3, 4, 5, 6]
@end example

(All contributed by Raymond Hettinger.)

@item 
The @ref{86,,logging} module's @code{FileHandler} class
and its subclasses @code{WatchedFileHandler}, @code{RotatingFileHandler},
and @code{TimedRotatingFileHandler} now
have an optional `delay' parameter to their constructors.  If `delay'
is true, opening of the log file is deferred until the first
@code{emit()} call is made.  (Contributed by Vinay Sajip.)

@code{TimedRotatingFileHandler} also has a `utc' constructor
parameter.  If the argument is true, UTC time will be used
in determining when midnight occurs and in generating filenames;
otherwise local time will be used.

@item 
Several new functions were added to the @ref{8d,,math} module:


@itemize *

@item 
@ref{1388,,isinf()} and @ref{1389,,isnan()} determine whether a given float
is a (positive or negative) infinity or a NaN (Not a Number), respectively.

@item 
@ref{138a,,copysign()} copies the sign bit of an IEEE 754 number,
returning the absolute value of `x' combined with the sign bit of
`y'.  For example, @code{math.copysign(1, -0.0)} returns -1.0.
(Contributed by Christian Heimes.)

@item 
@ref{934,,factorial()} computes the factorial of a number.
(Contributed by Raymond Hettinger; bpo-2138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2138}.)

@item 
@ref{138b,,fsum()} adds up the stream of numbers from an iterable,
and is careful to avoid loss of precision through using partial sums.
(Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson;
bpo-2819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2819}.)

@item 
@ref{138c,,acosh()}, @ref{138d,,asinh()}
and @ref{138e,,atanh()} compute the inverse hyperbolic functions.

@item 
@ref{138f,,log1p()} returns the natural logarithm of `1+x'
(base `e').

@item 
@code{trunc()} rounds a number toward zero, returning the closest
@code{Integral} that's between the function's argument and zero.
Added as part of the backport of
@ref{129b,,PEP 3141's type hierarchy for numbers}.
@end itemize

@item 
The @ref{8d,,math} module has been improved to give more consistent
behaviour across platforms, especially with respect to handling of
floating-point exceptions and IEEE 754 special values.

Whenever possible, the module follows the recommendations of the C99
standard about 754's special values.  For example, @code{sqrt(-1.)}
should now give a @ref{1ff,,ValueError} across almost all platforms,
while @code{sqrt(float('NaN'))} should return a NaN on all IEEE 754
platforms.  Where Annex 'F' of the C99 standard recommends signaling
'divide-by-zero' or 'invalid', Python will raise @ref{1ff,,ValueError}.
Where Annex 'F' of the C99 standard recommends signaling 'overflow',
Python will raise @ref{86d,,OverflowError}.  (See bpo-711019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=711019} and
bpo-1640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1640}.)

(Contributed by Christian Heimes and Mark Dickinson.)

@item 
@ref{208,,mmap} objects now have a @code{rfind()} method that searches for a
substring beginning at the end of the string and searching
backwards.  The @code{find()} method also gained an `end' parameter
giving an index at which to stop searching.
(Contributed by John Lenton.)

@item 
The @ref{9e,,operator} module gained a
@code{methodcaller()} function that takes a name and an optional
set of arguments, returning a callable that will call
the named function on any arguments passed to it.  For example:

@example
>>> # Equivalent to lambda s: s.replace('old', 'new')
>>> replacer = operator.methodcaller('replace', 'old', 'new')
>>> replacer('old wine in old bottles')
'new wine in new bottles'
@end example

(Contributed by Georg Brandl, after a suggestion by Gregory Petrosyan.)

The @code{attrgetter()} function now accepts dotted names and performs
the corresponding attribute lookups:

@example
>>> inst_name = operator.attrgetter(
...        '__class__.__name__')
>>> inst_name('@w{'})
'str'
>>> inst_name(help)
'_Helper'
@end example

(Contributed by Georg Brandl, after a suggestion by Barry Warsaw.)

@item 
The @ref{a0,,os} module now wraps several new system calls.
@code{fchmod(fd, mode)} and @code{fchown(fd, uid, gid)} change the mode
and ownership of an opened file, and @code{lchmod(path, mode)} changes
the mode of a symlink.  (Contributed by Georg Brandl and Christian
Heimes.)

@code{chflags()} and @code{lchflags()} are wrappers for the
corresponding system calls (where they're available), changing the
flags set on a file.  Constants for the flag values are defined in
the @ref{d0,,stat} module; some possible values include
@code{UF_IMMUTABLE} to signal the file may not be changed and
@code{UF_APPEND} to indicate that data can only be appended to the
file.  (Contributed by M. Levinson.)

@code{os.closerange(low, high)} efficiently closes all file descriptors
from `low' to `high', ignoring any errors and not including `high' itself.
This function is now used by the @ref{d5,,subprocess} module to make starting
processes faster.  (Contributed by Georg Brandl; bpo-1663329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1663329}.)

@item 
The @code{os.environ} object's @code{clear()} method will now unset the
environment variables using @ref{908,,os.unsetenv()} in addition to clearing
the object's keys.  (Contributed by Martin Horcicka; bpo-1181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1181}.)

@item 
The @ref{493,,os.walk()} function now has a @code{followlinks} parameter. If
set to True, it will follow symlinks pointing to directories and
visit the directory's contents.  For backward compatibility, the
parameter's default value is false.  Note that the function can fall
into an infinite recursion if there's a symlink that points to a
parent directory.  (bpo-1273829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1273829})

@item 
In the @ref{a1,,os.path} module, the @code{splitext()} function
has been changed to not split on leading period characters.
This produces better results when operating on Unix's dot-files.
For example, @code{os.path.splitext('.ipython')}
now returns @code{('.ipython', '@w{'})} instead of @code{('@w{'}, '.ipython')}.
(bpo-1115886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1115886})

A new function, @code{os.path.relpath(path, start='.')}, returns a relative path
from the @code{start} path, if it's supplied, or from the current
working directory to the destination @code{path}.  (Contributed by
Richard Barran; bpo-1339796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1339796}.)

On Windows, @ref{1390,,os.path.expandvars()} will now expand environment variables
given in the form "%var%", and "~user" will be expanded into the
user's home directory path.  (Contributed by Josiah Carlson;
bpo-957650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=957650}.)

@item 
The Python debugger provided by the @ref{a4,,pdb} module
gained a new command: "run" restarts the Python program being debugged
and can optionally take new command-line arguments for the program.
(Contributed by Rocky Bernstein; bpo-1393667@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1393667}.)

@item 
The @ref{1391,,pdb.post_mortem()} function, used to begin debugging a
traceback, will now use the traceback returned by @ref{675,,sys.exc_info()}
if no traceback is supplied.   (Contributed by Facundo Batista;
bpo-1106316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1106316}.)

@item 
The @ref{a6,,pickletools} module now has an @code{optimize()} function
that takes a string containing a pickle and removes some unused
opcodes, returning a shorter pickle that contains the same data structure.
(Contributed by Raymond Hettinger.)

@item 
A @code{get_data()} function was added to the @ref{a8,,pkgutil}
module that returns the contents of resource files included
with an installed Python package.  For example:

@example
>>> import pkgutil
>>> print pkgutil.get_data('test', 'exception_hierarchy.txt')
BaseException
 +-- SystemExit
 +-- KeyboardInterrupt
 +-- GeneratorExit
 +-- Exception
      +-- StopIteration
      +-- StandardError
 ...
@end example

(Contributed by Paul Moore; bpo-2439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2439}.)

@item 
The @code{pyexpat} module's @code{Parser} objects now allow setting
their @code{buffer_size} attribute to change the size of the buffer
used to hold character data.
(Contributed by Achim Gaedke; bpo-1137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1137}.)

@item 
The @code{Queue} module now provides queue variants that retrieve entries
in different orders.  The @code{PriorityQueue} class stores
queued items in a heap and retrieves them in priority order,
and @code{LifoQueue} retrieves the most recently added entries first,
meaning that it behaves like a stack.
(Contributed by Raymond Hettinger.)

@item 
The @ref{b7,,random} module's @code{Random} objects can
now be pickled on a 32-bit system and unpickled on a 64-bit
system, and vice versa.  Unfortunately, this change also means
that Python 2.6's @code{Random} objects can't be unpickled correctly
on earlier versions of Python.
(Contributed by Shawn Ligocki; bpo-1727780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1727780}.)

The new @code{triangular(low, high, mode)} function returns random
numbers following a triangular distribution.   The returned values
are between `low' and `high', not including `high' itself, and
with `mode' as the most frequently occurring value
in the distribution.  (Contributed by Wladmir van der Laan and
Raymond Hettinger; bpo-1681432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1681432}.)

@item 
Long regular expression searches carried out by the  @ref{b8,,re}
module will check for signals being delivered, so
time-consuming searches can now be interrupted.
(Contributed by Josh Hoyt and Ralf Schmitt; bpo-846388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=846388}.)

The regular expression module is implemented by compiling bytecodes
for a tiny regex-specific virtual machine.  Untrusted code
could create malicious strings of bytecode directly and cause crashes,
so Python 2.6 includes a verifier for the regex bytecode.
(Contributed by Guido van Rossum from work for Google App Engine;
bpo-3487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3487}.)

@item 
The @ref{bc,,rlcompleter} module's @code{Completer.complete()} method
will now ignore exceptions triggered while evaluating a name.
(Fixed by Lorenz Quack; bpo-2250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2250}.)

@item 
The @ref{be,,sched} module's @code{scheduler} instances now
have a read-only @ref{b5,,queue} attribute that returns the
contents of the scheduler's queue, represented as a list of
named tuples with the fields @code{(time, priority, action, argument)}.
(Contributed by Raymond Hettinger; bpo-1861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1861}.)

@item 
The @ref{c0,,select} module now has wrapper functions
for the Linux @code{epoll()} and BSD @code{kqueue()} system calls.
@code{modify()} method was added to the existing @code{poll}
objects; @code{pollobj.modify(fd, eventmask)} takes a file descriptor
or file object and an event mask, modifying the recorded event mask
for that file.
(Contributed by Christian Heimes; bpo-1657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1657}.)

@item 
The @ref{a17,,shutil.copytree()} function now has an optional `ignore' argument
that takes a callable object.  This callable will receive each directory path
and a list of the directory's contents, and returns a list of names that
will be ignored, not copied.

The @ref{c4,,shutil} module also provides an @code{ignore_patterns()}
function for use with this new parameter.  @code{ignore_patterns()}
takes an arbitrary number of glob-style patterns and returns a
callable that will ignore any files and directories that match any
of these patterns.  The following example copies a directory tree,
but skips both @code{.svn} directories and Emacs backup files,
which have names ending with '~':

@example
shutil.copytree('Doc/library', '/tmp/library',
                ignore=shutil.ignore_patterns('*~', '.svn'))
@end example

(Contribution par Tarek Ziadé; bpo-2663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2663}.)

@item 
Integrating signal handling with GUI handling event loops
like those used by Tkinter or GTk+ has long been a problem; most
software ends up polling, waking up every fraction of a second to check
if any GUI events have occurred.
The @ref{c5,,signal} module can now make this more efficient.
Calling @code{signal.set_wakeup_fd(fd)} sets a file descriptor
to be used; when a signal is received, a byte is written to that
file descriptor.  There's also a C-level function,
@ref{1392,,PySignal_SetWakeupFd()}, for setting the descriptor.

Event loops will use this by opening a pipe to create two descriptors,
one for reading and one for writing.  The writable descriptor
will be passed to @code{set_wakeup_fd()}, and the readable descriptor
will be added to the list of descriptors monitored by the event loop via
@code{select()} or @code{poll()}.
On receiving a signal, a byte will be written and the main event loop
will be woken up, avoiding the need to poll.

(Contributed by Adam Olsen; bpo-1583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1583}.)

The @code{siginterrupt()} function is now available from Python code,
and allows changing whether signals can interrupt system calls or not.
(Contributed by Ralf Schmitt.)

The @code{setitimer()} and @code{getitimer()} functions have also been
added (where they're available).  @code{setitimer()}
allows setting interval timers that will cause a signal to be
delivered to the process after a specified time, measured in
wall-clock time, consumed process time, or combined process+system
time.  (Contributed by Guilherme Polo; bpo-2240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2240}.)

@item 
The @ref{c9,,smtplib} module now supports SMTP over SSL thanks to the
addition of the @code{SMTP_SSL} class. This class supports an
interface identical to the existing @code{SMTP} class.
(Contributed by Monty Taylor.)  Both class constructors also have an
optional @code{timeout} parameter that specifies a timeout for the
initial connection attempt, measured in seconds.  (Contributed by
Facundo Batista.)

An implementation of the LMTP protocol (
@geindex RFC; RFC 2033
RFC 2033@footnote{https://datatracker.ietf.org/doc/html/rfc2033.html}) was also added
to the module.  LMTP is used in place of SMTP when transferring
e-mail between agents that don't manage a mail queue.  (LMTP
implemented by Leif Hedstrom; bpo-957003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=957003}.)

@code{SMTP.starttls()} now complies with 
@geindex RFC; RFC 3207
RFC 3207@footnote{https://datatracker.ietf.org/doc/html/rfc3207.html} and forgets any
knowledge obtained from the server not obtained from the TLS
negotiation itself.  (Patch contributed by Bill Fenner;
bpo-829951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=829951}.)

@item 
The @ref{cb,,socket} module now supports TIPC (@indicateurl{https://tipc.sourceforge.net/}),
a high-performance non-IP-based protocol designed for use in clustered
environments.  TIPC addresses are 4- or 5-tuples.
(Contributed by Alberto Bertogli; bpo-1646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1646}.)

A new function, @code{create_connection()}, takes an address and
connects to it using an optional timeout value, returning the
connected socket object.  This function also looks up the address's
type and connects to it using IPv4 or IPv6 as appropriate.  Changing
your code to use @code{create_connection()} instead of
@code{socket(socket.AF_INET, ...)} may be all that's required to make
your code work with IPv6.

@item 
The base classes in the @ref{cc,,SocketServer} module now support
calling a @ref{12ff,,handle_timeout()} method after a span of inactivity
specified by the server's @ref{12fe,,timeout} attribute.  (Contributed
by Michael Pomraning.)  The @ref{111f,,serve_forever()} method
now takes an optional poll interval measured in seconds,
controlling how often the server will check for a shutdown request.
(Contributed by Pedro Werneck and Jeffrey Yasskin;
bpo-742598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=742598}, bpo-1193577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1193577}.)

@item 
The @ref{ce,,sqlite3} module, maintained by Gerhard Häring,
has been updated from version 2.3.2 in Python 2.5 to
version 2.4.1.

@item 
The @ref{d4,,struct} module now supports the C99 _Bool type,
using the format character @code{'?'}.
(Contributed by David Remahl.)

@item 
The @ref{197,,Popen} objects provided by the @ref{d5,,subprocess} module
now have @ref{1393,,terminate()}, @ref{1394,,kill()}, and @ref{1395,,send_signal()} methods.
On Windows, @code{send_signal()} only supports the @ref{1396,,SIGTERM}
signal, and all these methods are aliases for the Win32 API function
@code{TerminateProcess()}.
(Contributed by Christian Heimes.)

@item 
A new variable in the @ref{d8,,sys} module, @code{float_info}, is an
object containing information derived from the @code{float.h} file
about the platform's floating-point support.  Attributes of this
object include @code{mant_dig} (number of digits in the mantissa),
@code{epsilon} (smallest difference between 1.0 and the next
largest value representable), and several others.  (Contributed by
Christian Heimes; bpo-1534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1534}.)

Another new variable, @code{dont_write_bytecode}, controls whether Python
writes any @code{.pyc} or @code{.pyo} files on importing a module.
If this variable is true, the compiled files are not written.  The
variable is initially set on start-up by supplying the @ref{1384,,-B}
switch to the Python interpreter, or by setting the
@geindex PYTHONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@ref{1385,,PYTHONDONTWRITEBYTECODE} environment variable before
running the interpreter.  Python code can subsequently
change the value of this variable to control whether bytecode files
are written or not.
(Contributed by Neal Norwitz and Georg Brandl.)

Information about the command-line arguments supplied to the Python
interpreter is available by reading attributes of a named
tuple available as @code{sys.flags}.  For example, the @code{verbose}
attribute is true if Python
was executed in verbose mode, @code{debug} is true in debugging mode, etc.
These attributes are all read-only.
(Contributed by Christian Heimes.)

A new function, @code{getsizeof()}, takes a Python object and returns
the amount of memory used by the object, measured in bytes.  Built-in
objects return correct results; third-party extensions may not,
but can define a @code{__sizeof__()} method to return the
object's size.
(Contributed by Robert Schuppenies; bpo-2898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2898}.)

It's now possible to determine the current profiler and tracer functions
by calling @ref{1397,,sys.getprofile()} and @ref{1398,,sys.gettrace()}.
(Contributed by Georg Brandl; bpo-1648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1648}.)

@item 
The @ref{dd,,tarfile} module now supports POSIX.1-2001 (pax) tarfiles in
addition to the POSIX.1-1988 (ustar) and GNU tar formats that were
already supported.  The default format is GNU tar; specify the
@code{format} parameter to open a file using a different format:

@example
tar = tarfile.open("output.tar", "w",
                   format=tarfile.PAX_FORMAT)
@end example

The new @code{encoding} and @code{errors} parameters specify an encoding and
an error handling scheme for character conversions.  @code{'strict'},
@code{'ignore'}, and @code{'replace'} are the three standard ways Python can
handle errors,;
@code{'utf-8'} is a special value that replaces bad characters with
their UTF-8 representation.  (Character conversions occur because the
PAX format supports Unicode filenames, defaulting to UTF-8 encoding.)

The @code{TarFile.add()} method now accepts an @code{exclude} argument that's
a function that can be used to exclude certain filenames from
an archive.
The function must take a filename and return true if the file
should be excluded or false if it should be archived.
The function is applied to both the name initially passed to @code{add()}
and to the names of files in recursively added directories.

(All changes contributed by Lars Gustäbel).

@item 
An optional @code{timeout} parameter was added to the
@code{telnetlib.Telnet} class constructor, specifying a timeout
measured in seconds.  (Added by Facundo Batista.)

@item 
The @ref{4af,,tempfile.NamedTemporaryFile} class usually deletes
the temporary file it created when the file is closed.  This
behaviour can now be changed by passing @code{delete=False} to the
constructor.  (Contributed by Damien Miller; bpo-1537850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1537850}.)

A new class, @code{SpooledTemporaryFile}, behaves like
a temporary file but stores its data in memory until a maximum size is
exceeded.  On reaching that limit, the contents will be written to
an on-disk temporary file.  (Contributed by Dustin J. Mitchell.)

The @code{NamedTemporaryFile} and @code{SpooledTemporaryFile} classes
both work as context managers, so you can write
@code{with tempfile.NamedTemporaryFile() as tmp: ...}.
(Contributed by Alexander Belopolsky; bpo-2021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2021}.)

@item 
The @ref{e3,,test.test_support} module gained a number
of context managers useful for writing tests.
@ref{1399,,EnvironmentVarGuard()} is a
context manager that temporarily changes environment variables and
automatically restores them to their old values.

Another context manager, @code{TransientResource}, can surround calls
to resources that may or may not be available; it will catch and
ignore a specified list of exceptions.  For example,
a network test may ignore certain failures when connecting to an
external web site:

@example
with test_support.TransientResource(IOError,
                                errno=errno.ETIMEDOUT):
    f = urllib.urlopen('https://sf.net')
    ...
@end example

Finally, @code{check_warnings()} resets the @code{warning} module's
warning filters and returns an object that will record all warning
messages triggered (bpo-3781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3781}):

@example
with test_support.check_warnings() as wrec:
    warnings.simplefilter("always")
    # ... code that triggers a warning ...
    assert str(wrec.message) == "function is outdated"
    assert len(wrec.warnings) == 1, "Multiple warnings raised"
@end example

(Contributed by Brett Cannon.)

@item 
The @ref{eb,,textwrap} module can now preserve existing whitespace
at the beginnings and ends of the newly created lines
by specifying @code{drop_whitespace=False}
as an argument:

@example
>>> S = """This  sentence  has a bunch   of
...   extra   whitespace."""
>>> print textwrap.fill(S, width=15)
This  sentence
has a bunch
of    extra
whitespace.
>>> print textwrap.fill(S, drop_whitespace=False, width=15)
This  sentence
  has a bunch
   of    extra
   whitespace.
>>>
@end example

(Contributed by Dwayne Bailey; bpo-1581073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1581073}.)

@item 
The @ref{ec,,threading} module API is being changed to use properties
such as @code{daemon} instead of @code{setDaemon()} and
@code{isDaemon()} methods, and some methods have been renamed to use
underscores instead of camel-case; for example, the
@code{activeCount()} method is renamed to @code{active_count()}.  Both
the 2.6 and 3.0 versions of the module support the same properties
and renamed methods, but don't remove the old methods.  No date has been set
for the deprecation of the old APIs in Python 3.x; the old APIs won't
be removed in any 2.x version.
(Carried out by several people, most notably Benjamin Peterson.)

The @ref{ec,,threading} module's @code{Thread} objects
gained an @code{ident} property that returns the thread's
identifier, a nonzero integer.  (Contributed by Gregory P. Smith;
bpo-2871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2871}.)

@item 
The @ref{ee,,timeit} module now accepts callables as well as strings
for the statement being timed and for the setup code.
Two convenience functions were added for creating
@code{Timer} instances:
@code{repeat(stmt, setup, time, repeat, number)} and
@code{timeit(stmt, setup, time, number)} create an instance and call
the corresponding method. (Contributed by Erik Demaine;
bpo-1533909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1533909}.)

@item 
The @code{Tkinter} module now accepts lists and tuples for options,
separating the elements by spaces before passing the resulting value to
Tcl/Tk.
(Contributed by Guilherme Polo; bpo-2906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2906}.)

@item 
The @ref{100,,turtle} module for turtle graphics was greatly enhanced by
Gregor Lingl.  New features in the module include:


@itemize *

@item 
Better animation of turtle movement and rotation.

@item 
Control over turtle movement using the new @code{delay()},
@code{tracer()}, and @code{speed()} methods.

@item 
The ability to set new shapes for the turtle, and to
define a new coordinate system.

@item 
Turtles now have an @code{undo()} method that can roll back actions.

@item 
Simple support for reacting to input events such as mouse and keyboard
activity, making it possible to write simple games.

@item 
A @code{turtle.cfg} file can be used to customize the starting appearance
of the turtle's screen.

@item 
The module's docstrings can be replaced by new docstrings that have been
translated into another language.
@end itemize

(bpo-1513695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1513695})

@item 
An optional @code{timeout} parameter was added to the
@ref{290,,urllib.urlopen} function and the
@code{urllib.ftpwrapper} class constructor, as well as the
@ref{290,,urllib2.urlopen} function.  The parameter specifies a timeout
measured in seconds.   For example:

@example
>>> u = urllib2.urlopen("http://slow.example.com",
                        timeout=3)
Traceback (most recent call last):
  ...
urllib2.URLError: <urlopen error timed out>
>>>
@end example

(Added by Facundo Batista.)

@item 
The Unicode database provided by the @ref{104,,unicodedata} module
has been updated to version 5.1.0.  (Updated by
Martin von Löwis; bpo-3811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3811}.)

@item 
The @ref{111,,warnings} module's @code{formatwarning()} and @code{showwarning()}
gained an optional `line' argument that can be used to supply the
line of source code.  (Added as part of bpo-1631171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1631171}, which re-implemented
part of the @ref{111,,warnings} module in C code.)

A new function, @code{catch_warnings()}, is a context manager
intended for testing purposes that lets you temporarily modify the
warning filters and then restore their original values (bpo-3781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3781}).

@item 
The XML-RPC @ref{12e,,SimpleXMLRPCServer} and @ref{12e,,DocXMLRPCServer}
classes can now be prevented from immediately opening and binding to
their socket by passing @code{False} as the `bind_and_activate'
constructor parameter.  This can be used to modify the instance's
@code{allow_reuse_address} attribute before calling the
@code{server_bind()} and @code{server_activate()} methods to
open the socket and begin listening for connections.
(Contributed by Peter Parente; bpo-1599845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1599845}.)

@code{SimpleXMLRPCServer} also has a @code{_send_traceback_header}
attribute; if true, the exception and formatted traceback are returned
as HTTP headers "X-Exception" and "X-Traceback".  This feature is
for debugging purposes only and should not be used on production servers
because the tracebacks might reveal passwords or other sensitive
information.  (Contributed by Alan McIntyre as part of his
project for Google's Summer of Code 2007.)

@item 
The @ref{12d,,xmlrpclib} module no longer automatically converts
@ref{1c8,,datetime.date} and @ref{1c9,,datetime.time} to the
@ref{139a,,xmlrpclib.DateTime} type; the conversion semantics were
not necessarily correct for all applications.  Code using
@code{xmlrpclib} should convert @code{date} and @ref{1c9,,time}
instances. (bpo-1330538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1330538})  The code can also handle
dates before 1900 (contributed by Ralf Schmitt; bpo-2014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2014})
and 64-bit integers represented by using @code{<i8>} in XML-RPC responses
(contributed by Riku Lindblad; bpo-2985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2985}).

@item 
The @ref{130,,zipfile} module's @code{ZipFile} class now has
@code{extract()} and @code{extractall()} methods that will unpack
a single file or all the files in the archive to the current directory, or
to a specified directory:

@example
z = zipfile.ZipFile('python-251.zip')

# Unpack a single file, writing it relative
# to the /tmp directory.
z.extract('Python/sysmodule.c', '/tmp')

# Unpack all the files in the archive.
z.extractall()
@end example

(Contributed by Alan McIntyre; bpo-467924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=467924}.)

The @ref{505,,open()}, @code{read()} and @code{extract()} methods can now
take either a filename or a @code{ZipInfo} object.  This is useful when an
archive accidentally contains a duplicated filename.
(Contributed by Graham Horler; bpo-1775025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1775025}.)

Finally, @ref{130,,zipfile} now supports using Unicode filenames
for archived files.  (Contributed by Alexey Borzenkov; bpo-1734346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1734346}.)
@end itemize

@c ======================================================================

@c whole new modules get described in subsections here

@menu
* The ast module:: 
* The future_builtins module:: 
* The json module; JavaScript Object Notation: The json module JavaScript Object Notation. 
* The plistlib module; A Property-List Parser: The plistlib module A Property-List Parser. 
* ctypes Enhancements:: 
* Improved SSL Support:: 

@end menu

@node The ast module,The future_builtins module,,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-ast-module}@anchor{139b}
@subsubsection The @code{ast} module


The @ref{8,,ast} module provides an Abstract Syntax Tree
representation of Python code, and Armin Ronacher
contributed a set of helper functions that perform a variety of
common tasks.  These will be useful for HTML templating
packages, code analyzers, and similar tools that process
Python code.

The @code{parse()} function takes an expression and returns an AST.
The @code{dump()} function outputs a representation of a tree, suitable
for debugging:

@example
import ast

t = ast.parse("""
d = @{@}
for i in 'abcdefghijklm':
    d[i + i] = ord(i) - ord('a') + 1
print d
""")
print ast.dump(t)
@end example

This outputs a deeply nested tree:

@example
Module(body=[
  Assign(targets=[
    Name(id='d', ctx=Store())
   ], value=Dict(keys=[], values=[]))
  For(target=Name(id='i', ctx=Store()),
      iter=Str(s='abcdefghijklm'), body=[
    Assign(targets=[
      Subscript(value=
        Name(id='d', ctx=Load()),
          slice=
          Index(value=
            BinOp(left=Name(id='i', ctx=Load()), op=Add(),
             right=Name(id='i', ctx=Load()))), ctx=Store())
     ], value=
     BinOp(left=
      BinOp(left=
       Call(func=
        Name(id='ord', ctx=Load()), args=[
          Name(id='i', ctx=Load())
         ], keywords=[], starargs=None, kwargs=None),
       op=Sub(), right=Call(func=
        Name(id='ord', ctx=Load()), args=[
          Str(s='a')
         ], keywords=[], starargs=None, kwargs=None)),
       op=Add(), right=Num(n=1)))
    ], orelse=[])
   Print(dest=None, values=[
     Name(id='d', ctx=Load())
   ], nl=True)
 ])
@end example

The @code{literal_eval()} method takes a string or an AST
representing a literal expression, parses and evaluates it, and
returns the resulting value.  A literal expression is a Python
expression containing only strings, numbers, dictionaries,
etc. but no statements or function calls.  If you need to
evaluate an expression but cannot accept the security risk of using an
@ref{17e,,eval()} call, @code{literal_eval()} will handle it safely:

@example
>>> literal = '("a", "b", @{2:4, 3:8, 1:2@})'
>>> print ast.literal_eval(literal)
('a', 'b', @{1: 2, 2: 4, 3: 8@})
>>> print ast.literal_eval('"a" + "b"')
Traceback (most recent call last):
  ...
ValueError: malformed string
@end example

The module also includes @code{NodeVisitor} and
@code{NodeTransformer} classes for traversing and modifying an AST,
and functions for common transformations such as changing line
numbers.

@c ======================================================================

@node The future_builtins module,The json module JavaScript Object Notation,The ast module,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-future-builtins-module}@anchor{139c}
@subsubsection The @code{future_builtins} module


Python 3.0 makes many changes to the repertoire of built-in
functions, and most of the changes can't be introduced in the Python
2.x series because they would break compatibility.
The @code{future_builtins} module provides versions
of these built-in functions that can be imported when writing
3.0-compatible code.

The functions in this module currently include:


@itemize *

@item 
@code{ascii(obj)}: equivalent to @ref{7e7,,repr()}.  In Python 3.0,
@ref{7e7,,repr()} will return a Unicode string, while @ref{139d,,ascii()} will
return a pure ASCII bytestring.

@item 
@code{filter(predicate, iterable)},
@code{map(func, iterable1, ...)}: the 3.0 versions
return iterators, unlike the 2.x builtins which return lists.

@item 
@code{hex(value)}, @code{oct(value)}: instead of calling the
@code{__hex__()} or @code{__oct__()} methods, these versions will
call the @code{__index__()} method and convert the result to hexadecimal
or octal.  @ref{12ac,,oct()} will use the new @code{0o} notation for its
result.
@end itemize

@c ======================================================================

@node The json module JavaScript Object Notation,The plistlib module A Property-List Parser,The future_builtins module,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-json-module-javascript-object-notation}@anchor{139e}
@subsubsection The @code{json} module: JavaScript Object Notation


The new @ref{81,,json} module supports the encoding and decoding of Python types in
JSON (Javascript Object Notation). JSON is a lightweight interchange format
often used in web applications. For more information about JSON, see
@indicateurl{http://www.json.org}.

@ref{81,,json} comes with support for decoding and encoding most built-in Python
types. The following example encodes and decodes a dictionary:

@example
>>> import json
>>> data = @{"spam": "foo", "parrot": 42@}
>>> in_json = json.dumps(data) # Encode the data
>>> in_json
'@{"parrot": 42, "spam": "foo"@}'
>>> json.loads(in_json) # Decode into a Python object
@{"spam": "foo", "parrot": 42@}
@end example

It's also possible to write your own decoders and encoders to support
more types. Pretty-printing of the JSON strings is also supported.

@ref{81,,json} (originally called simplejson) was written by Bob
Ippolito.

@c ======================================================================

@node The plistlib module A Property-List Parser,ctypes Enhancements,The json module JavaScript Object Notation,New and Improved Modules<2>
@anchor{whatsnew/2 6 the-plistlib-module-a-property-list-parser}@anchor{139f}
@subsubsection The @code{plistlib} module: A Property-List Parser


The @code{.plist} format is commonly used on Mac OS X to
store basic data types (numbers, strings, lists,
and dictionaries) by serializing them into an XML-based format.
It resembles the XML-RPC serialization of data types.

Despite being primarily used on Mac OS X, the format
has nothing Mac-specific about it and the Python implementation works
on any platform that Python supports, so the @ref{aa,,plistlib} module
has been promoted to the standard library.

Using the module is simple:

@example
import sys
import plistlib
import datetime

# Create data structure
data_struct = dict(lastAccessed=datetime.datetime.now(),
                   version=1,
                   categories=('Personal','Shared','Private'))

# Create string containing XML.
plist_str = plistlib.writePlistToString(data_struct)
new_struct = plistlib.readPlistFromString(plist_str)
print data_struct
print new_struct

# Write data structure to a file and read it back.
plistlib.writePlist(data_struct, '/tmp/customizations.plist')
new_struct = plistlib.readPlist('/tmp/customizations.plist')

# read/writePlist accepts file-like objects as well as paths.
plistlib.writePlist(data_struct, sys.stdout)
@end example

@c ======================================================================

@node ctypes Enhancements,Improved SSL Support,The plistlib module A Property-List Parser,New and Improved Modules<2>
@anchor{whatsnew/2 6 ctypes-enhancements}@anchor{13a0}
@subsubsection ctypes Enhancements


Thomas Heller continued to maintain and enhance the
@ref{2a,,ctypes} module.

@ref{2a,,ctypes} now supports a @code{c_bool} datatype
that represents the C99 @code{bool} type.  (Contributed by David Remahl;
bpo-1649190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1649190}.)

The @ref{2a,,ctypes} string, buffer and array types have improved
support for extended slicing syntax,
where various combinations of @code{(start, stop, step)} are supplied.
(Implemented by Thomas Wouters.)

@c Revision 57769

All @ref{2a,,ctypes} data types now support
@code{from_buffer()} and @code{from_buffer_copy()}
methods that create a ctypes instance based on a
provided buffer object.  @code{from_buffer_copy()} copies
the contents of the object,
while @code{from_buffer()} will share the same memory area.

A new calling convention tells @ref{2a,,ctypes} to clear the @code{errno} or
Win32 LastError variables at the outset of each wrapped call.
(Implemented by Thomas Heller; bpo-1798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1798}.)

You can now retrieve the Unix @code{errno} variable after a function
call.  When creating a wrapped function, you can supply
@code{use_errno=True} as a keyword parameter to the @code{DLL()} function
and then call the module-level methods @code{set_errno()} and
@code{get_errno()} to set and retrieve the error value.

The Win32 LastError variable is similarly supported by
the @code{DLL()}, @code{OleDLL()}, and @code{WinDLL()} functions.
You supply @code{use_last_error=True} as a keyword parameter
and then call the module-level methods @code{set_last_error()}
and @code{get_last_error()}.

The @code{byref()} function, used to retrieve a pointer to a ctypes
instance, now has an optional `offset' parameter that is a byte
count that will be added to the returned pointer.

@c ======================================================================

@node Improved SSL Support,,ctypes Enhancements,New and Improved Modules<2>
@anchor{whatsnew/2 6 improved-ssl-support}@anchor{13a1}
@subsubsection Improved SSL Support


Bill Janssen made extensive improvements to Python 2.6's support for
the Secure Sockets Layer by adding a new module, @ref{cf,,ssl}, that's
built atop the OpenSSL@footnote{https://www.openssl.org/} library.
This new module provides more control over the protocol negotiated,
the X.509 certificates used, and has better support for writing SSL
servers (as opposed to clients) in Python.  The existing SSL support
in the @ref{cb,,socket} module hasn't been removed and continues to work,
though it will be removed in Python 3.0.

To use the new module, you must first create a TCP connection in the
usual way and then pass it to the @code{ssl.wrap_socket()} function.
It's possible to specify whether a certificate is required, and to
obtain certificate info by calling the @code{getpeercert()} method.


@subsubheading Voir aussi


The documentation for the @ref{cf,,ssl} module.


@c ======================================================================

@node Deprecations and Removals,Build and C API Changes<9>,New and Improved Modules<2>,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 deprecations-and-removals}@anchor{13a2}
@subsection Deprecations and Removals



@itemize *

@item 
String exceptions have been removed.  Attempting to use them raises a
@ref{522,,TypeError}.

@item 
Changes to the @ref{9c7,,Exception} interface
as dictated by 
@geindex Python Enhancement Proposals; PEP 352
PEP 352@footnote{https://peps.python.org/pep-0352/} continue to be made.  For 2.6,
the @code{message} attribute is being deprecated in favor of the
@ref{558,,args} attribute.

@item 
(3.0-warning mode) Python 3.0 will feature a reorganized standard
library that will drop many outdated modules and rename others.
Python 2.6 running in 3.0-warning mode will warn about these modules
when they are imported.

The list of deprecated modules is:
@code{audiodev},
@code{bgenlocations},
@code{buildtools},
@code{bundlebuilder},
@code{Canvas},
@code{compiler},
@code{dircache},
@code{dl},
@code{fpformat},
@code{gensuitemodule},
@code{ihooks},
@code{imageop},
@code{imgfile},
@code{linuxaudiodev},
@code{mhlib},
@code{mimetools},
@code{multifile},
@code{new},
@code{pure},
@code{statvfs},
@code{sunaudiodev},
@code{test.testall}, and
@code{toaiff}.

@item 
The @code{gopherlib} module has been removed.

@item 
The @code{MimeWriter} module and @code{mimify} module
have been deprecated; use the @ref{3b,,email}
package instead.

@item 
The @code{md5} module has been deprecated; use the @ref{67,,hashlib} module
instead.

@item 
The @code{posixfile} module has been deprecated; @ref{13a3,,fcntl.lockf()}
provides better locking.

@item 
The @code{popen2} module has been deprecated; use the @ref{d5,,subprocess}
module.

@item 
The @code{rgbimg} module has been removed.

@item 
The @code{sets} module has been deprecated; it's better to
use the built-in @ref{5c3,,set} and @ref{5c4,,frozenset} types.

@item 
The @code{sha} module has been deprecated; use the @ref{67,,hashlib} module
instead.
@end itemize

@c ======================================================================

@node Build and C API Changes<9>,Portage vers Python 2 6,Deprecations and Removals,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 build-and-c-api-changes}@anchor{13a4}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
Python now must be compiled with C89 compilers (after 19
years!).  This means that the Python source tree has dropped its
own implementations of @code{memmove()} and @code{strerror()}, which
are in the C89 standard library.

@item 
Python 2.6 can be built with Microsoft Visual Studio 2008 (version
9.0), and this is the new default compiler.  See the
@code{PCbuild} directory for the build files.  (Implemented by
Christian Heimes.)

@item 
On Mac OS X, Python 2.6 can be compiled as a 4-way universal build.
The @code{configure} script
can take a @code{--with-universal-archs=[32-bit|64-bit|all]}
switch, controlling whether the binaries are built for 32-bit
architectures (x86, PowerPC), 64-bit (x86-64 and PPC-64), or both.
(Contributed by Ronald Oussoren.)

@item 
A new function added in Python 2.6.6, @code{PySys_SetArgvEx()}, sets
the value of @code{sys.argv} and can optionally update @code{sys.path} to
include the directory containing the script named by @code{sys.argv[0]}
depending on the value of an `updatepath' parameter.

This function was added to close a security hole for applications
that embed Python.  The old function, @code{PySys_SetArgv()}, would
always update @code{sys.path}, and sometimes it would add the current
directory.  This meant that, if you ran an application embedding
Python in a directory controlled by someone else, attackers could
put a Trojan-horse module in the directory (say, a file named
@code{os.py}) that your application would then import and run.

If you maintain a C/C++ application that embeds Python, check
whether you're calling @code{PySys_SetArgv()} and carefully consider
whether the application should be using @code{PySys_SetArgvEx()}
with `updatepath' set to false.  Note that using this function will
break compatibility with Python versions 2.6.5 and earlier; if you
have to continue working with earlier versions, you can leave
the call to @code{PySys_SetArgv()} alone and call
@code{PyRun_SimpleString("sys.path.pop(0)\n")} afterwards to discard
the first @code{sys.path} component.

Security issue reported as 
@geindex Common Vulnerabilities and Exposures; CVE 2008-5983
CVE 2008-5983@footnote{https://www.cve.org/CVERecord?id=CVE-2008-5983};
discussed in gh-50003@footnote{https://github.com/python/cpython/issues/50003}, and fixed by Antoine Pitrou.

@item 
The BerkeleyDB module now has a C API object, available as
@code{bsddb.db.api}.   This object can be used by other C extensions
that wish to use the @code{bsddb} module for their own purposes.
(Contributed by Duncan Grisby.)

@item 
The new buffer interface, previously described in
@ref{1370,,the PEP 3118 section},
adds @ref{390,,PyObject_GetBuffer()} and @ref{391,,PyBuffer_Release()},
as well as a few other functions.

@item 
Python's use of the C stdio library is now thread-safe, or at least
as thread-safe as the underlying library is.  A long-standing potential
bug occurred if one thread closed a file object while another thread
was reading from or writing to the object.  In 2.6 file objects
have a reference count, manipulated by the
@code{PyFile_IncUseCount()} and @code{PyFile_DecUseCount()}
functions.  File objects can't be closed unless the reference count
is zero.  @code{PyFile_IncUseCount()} should be called while the GIL
is still held, before carrying out an I/O operation using the
@code{FILE *} pointer, and @code{PyFile_DecUseCount()} should be called
immediately after the GIL is re-acquired.
(Contributed by Antoine Pitrou and Gregory P. Smith.)

@item 
Importing modules simultaneously in two different threads no longer
deadlocks; it will now raise an @ref{40f,,ImportError}.  A new API
function, @ref{3b4,,PyImport_ImportModuleNoBlock()}, will look for a
module in @code{sys.modules} first, then try to import it after
acquiring an import lock.  If the import lock is held by another
thread, an @ref{40f,,ImportError} is raised.
(Contributed by Christian Heimes.)

@item 
Several functions return information about the platform's
floating-point support.  @ref{13a5,,PyFloat_GetMax()} returns
the maximum representable floating-point value,
and @ref{13a6,,PyFloat_GetMin()} returns the minimum
positive value.  @ref{13a7,,PyFloat_GetInfo()} returns an object
containing more information from the @code{float.h} file, such as
@code{"mant_dig"} (number of digits in the mantissa), @code{"epsilon"}
(smallest difference between 1.0 and the next largest value
representable), and several others.
(Contributed by Christian Heimes; bpo-1534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1534}.)

@item 
C functions and methods that use
@ref{13a8,,PyComplex_AsCComplex()} will now accept arguments that
have a @code{__complex__()} method.  In particular, the functions in the
@ref{18,,cmath} module will now accept objects with this method.
This is a backport of a Python 3.0 change.
(Contributed by Mark Dickinson; bpo-1675423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1675423}.)

@item 
Python's C API now includes two functions for case-insensitive string
comparisons, @code{PyOS_stricmp(char*, char*)}
and @code{PyOS_strnicmp(char*, char*, Py_ssize_t)}.
(Contributed by Christian Heimes; bpo-1635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635}.)

@item 
Many C extensions define their own little macro for adding
integers and strings to the module's dictionary in the
@code{init*} function.  Python 2.6 finally defines standard macros
for adding values to a module, @ref{13a9,,PyModule_AddStringMacro}
and @ref{13aa,,PyModule_AddIntMacro()}.  (Contributed by
Christian Heimes.)

@item 
Some macros were renamed in both 3.0 and 2.6 to make it clearer that
they are macros,
not functions.  @code{Py_Size()} became @ref{76c,,Py_SIZE()},
@code{Py_Type()} became @ref{76a,,Py_TYPE()}, and
@code{Py_Refcnt()} became @ref{896,,Py_REFCNT()}.
The mixed-case macros are still available
in Python 2.6 for backward compatibility.
(bpo-1629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1629})

@item 
Distutils now places C extensions it builds in a
different directory when running on a debug version of Python.
(Contributed by Collin Winter; bpo-1530959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1530959}.)

@item 
Several basic data types, such as integers and strings, maintain
internal free lists of objects that can be re-used.  The data
structures for these free lists now follow a naming convention: the
variable is always named @code{free_list}, the counter is always named
@code{numfree}, and a macro @code{Py<typename>_MAXFREELIST} is
always defined.

@item 
A new Makefile target, "make patchcheck", prepares the Python source tree
for making a patch: it fixes trailing whitespace in all modified
@code{.py} files, checks whether the documentation has been changed,
and reports whether the @code{Misc/ACKS} and @code{Misc/NEWS} files
have been updated.
(Contributed by Brett Cannon.)

Another new target, "make profile-opt", compiles a Python binary
using GCC's profile-guided optimization.  It compiles Python with
profiling enabled, runs the test suite to obtain a set of profiling
results, and then compiles using these results for optimization.
(Contributed by Gregory P. Smith.)
@end itemize

@c ======================================================================

@menu
* Port-Specific Changes; Windows: Port-Specific Changes Windows<2>. 
* Port-Specific Changes; Mac OS X: Port-Specific Changes Mac OS X<2>. 
* Port-Specific Changes; IRIX: Port-Specific Changes IRIX. 

@end menu

@node Port-Specific Changes Windows<2>,Port-Specific Changes Mac OS X<2>,,Build and C API Changes<9>
@anchor{whatsnew/2 6 port-specific-changes-windows}@anchor{13ab}
@subsubsection Port-Specific Changes: Windows



@itemize *

@item 
The support for Windows 95, 98, ME and NT4 has been dropped.
Python 2.6 requires at least Windows 2000 SP4.

@item 
The new default compiler on Windows is Visual Studio 2008 (version
9.0). The build directories for Visual Studio 2003 (version 7.1) and
2005 (version 8.0) were moved into the PC/ directory. The new
@code{PCbuild} directory supports cross compilation for X64, debug
builds and Profile Guided Optimization (PGO). PGO builds are roughly
10% faster than normal builds.  (Contributed by Christian Heimes
with help from Amaury Forgeot d'Arc and Martin von Löwis.)

@item 
The @ref{92,,msvcrt} module now supports
both the normal and wide char variants of the console I/O
API.  The @ref{13ac,,getwch()} function reads a keypress and returns a Unicode
value, as does the @ref{13ad,,getwche()} function.  The @ref{13ae,,putwch()} function
takes a Unicode character and writes it to the console.
(Contributed by Christian Heimes.)

@item 
@ref{1390,,os.path.expandvars()} will now expand environment variables in
the form "%var%", and "~user" will be expanded into the user's home
directory path.  (Contributed by Josiah Carlson; bpo-957650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=957650}.)

@item 
The @ref{cb,,socket} module's socket objects now have an
@ref{cc1,,ioctl()} method that provides a limited interface to the
@code{WSAIoctl()} system interface.

@item 
The @ref{115,,_winreg} module now has a function,
@ref{13af,,ExpandEnvironmentStrings()},
that expands environment variable references such as @code{%NAME%}
in an input string.  The handle objects provided by this
module now support the context protocol, so they can be used
in @ref{5bc,,with} statements. (Contributed by Christian Heimes.)

@ref{115,,_winreg} also has better support for x64 systems,
exposing the @ref{133b,,DisableReflectionKey()}, @ref{133c,,EnableReflectionKey()},
and @ref{133d,,QueryReflectionKey()} functions, which enable and disable
registry reflection for 32-bit processes running on 64-bit systems.
(bpo-1753245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1753245})

@item 
The @code{msilib} module's @code{Record} object
gained @code{GetInteger()} and @code{GetString()} methods that
return field values as an integer or a string.
(Contributed by Floris Bruynooghe; bpo-2125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2125}.)
@end itemize

@c ======================================================================

@node Port-Specific Changes Mac OS X<2>,Port-Specific Changes IRIX,Port-Specific Changes Windows<2>,Build and C API Changes<9>
@anchor{whatsnew/2 6 port-specific-changes-mac-os-x}@anchor{13b0}
@subsubsection Port-Specific Changes: Mac OS X



@itemize *

@item 
When compiling a framework build of Python, you can now specify the
framework name to be used by providing the
@code{--with-framework-name=} option to the
@code{configure} script.

@item 
The @code{macfs} module has been removed.  This in turn required the
@code{macostools.touched()} function to be removed because it depended on the
@code{macfs} module.  (bpo-1490190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1490190})

@item 
Many other Mac OS modules have been deprecated and will be removed in
Python 3.0:
@code{_builtinSuites},
@code{aepack},
@code{aetools},
@code{aetypes},
@code{applesingle},
@code{appletrawmain},
@code{appletrunner},
@code{argvemulator},
@code{Audio_mac},
@code{autoGIL},
@code{Carbon},
@code{cfmfile},
@code{CodeWarrior},
@code{ColorPicker},
@code{EasyDialogs},
@code{Explorer},
@code{Finder},
@code{FrameWork},
@code{findertools},
@code{ic},
@code{icglue},
@code{icopen},
@code{macerrors},
@code{MacOS},
@code{macfs},
@code{macostools},
@code{macresource},
@code{MiniAEFrame},
@code{Nav},
@code{Netscape},
@code{OSATerminology},
@code{pimp},
@code{PixMapWrapper},
@code{StdSuites},
@code{SystemEvents},
@code{Terminal}, and
@code{terminalcommand}.
@end itemize

@c ======================================================================

@node Port-Specific Changes IRIX,,Port-Specific Changes Mac OS X<2>,Build and C API Changes<9>
@anchor{whatsnew/2 6 port-specific-changes-irix}@anchor{13b1}
@subsubsection Port-Specific Changes: IRIX


A number of old IRIX-specific modules were deprecated and will
be removed in Python 3.0:
@code{al} and @code{AL},
@code{cd},
@code{cddb},
@code{cdplayer},
@code{CL} and @code{cl},
@code{DEVICE},
@code{ERRNO},
@code{FILE},
@code{FL} and @code{fl},
@code{flp},
@code{fm},
@code{GET},
@code{GLWS},
@code{GL} and @code{gl},
@code{IN},
@code{IOCTL},
@code{jpeg},
@code{panelparser},
@code{readcd},
@code{SV} and @code{sv},
@code{torgb},
@code{videoreader}, and
@code{WAIT}.

@c ======================================================================

@node Portage vers Python 2 6,Remerciements<2>,Build and C API Changes<9>,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 porting-to-python-2-6}@anchor{13b2}
@subsection Portage vers Python 2.6


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


@itemize *

@item 
Classes that aren't supposed to be hashable should
set @code{__hash__ = None} in their definitions to indicate
the fact.

@item 
String exceptions have been removed.  Attempting to use them raises a
@ref{522,,TypeError}.

@item 
The @code{__init__()} method of @ref{5c6,,collections.deque}
now clears any existing contents of the deque
before adding elements from the iterable.  This change makes the
behavior match @code{list.__init__()}.

@item 
@ref{69b,,object.__init__()} previously accepted arbitrary arguments and
keyword arguments, ignoring them.  In Python 2.6, this is no longer
allowed and will result in a @ref{522,,TypeError}.  This will affect
@code{__init__()} methods that end up calling the corresponding
method on @ref{a7a,,object} (perhaps through using @ref{4c5,,super()}).
See bpo-1683368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1683368} for discussion.

@item 
The @code{Decimal} constructor now accepts leading and trailing
whitespace when passed a string.  Previously it would raise an
@code{InvalidOperation} exception.  On the other hand, the
@code{create_decimal()} method of @code{Context} objects now
explicitly disallows extra whitespace, raising a
@code{ConversionSyntax} exception.

@item 
Due to an implementation accident, if you passed a file path to
the built-in  @ref{8c1,,__import__()} function, it would actually import
the specified file.  This was never intended to work, however, and
the implementation now explicitly checks for this case and raises
an @ref{40f,,ImportError}.

@item 
C API: the @ref{13b3,,PyImport_Import()} and @ref{3b5,,PyImport_ImportModule()}
functions now default to absolute imports, not relative imports.
This will affect C extensions that import other modules.

@item 
C API: extension data types that shouldn't be hashable
should define their @code{tp_hash} slot to
@ref{137d,,PyObject_HashNotImplemented()}.

@item 
The @ref{cb,,socket} module exception @ref{103e,,socket.error} now inherits
from @ref{103b,,IOError}.  Previously it wasn't a subclass of
@code{StandardError} but now it is, through @ref{103b,,IOError}.
(Implemented by Gregory P. Smith; bpo-1706815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1706815}.)

@item 
The @ref{12d,,xmlrpclib} module no longer automatically converts
@ref{1c8,,datetime.date} and @ref{1c9,,datetime.time} to the
@ref{139a,,xmlrpclib.DateTime} type; the conversion semantics were
not necessarily correct for all applications.  Code using
@code{xmlrpclib} should convert @code{date} and @ref{1c9,,time}
instances. (bpo-1330538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1330538})

@item 
(3.0-warning mode) The @ref{9c7,,Exception} class now warns
when accessed using slicing or index access; having
@ref{9c7,,Exception} behave like a tuple is being phased out.

@item 
(3.0-warning mode) inequality comparisons between two dictionaries
or two objects that don't implement comparison methods are reported
as warnings.  @code{dict1 == dict2} still works, but @code{dict1 < dict2}
is being phased out.

Comparisons between cells, which are an implementation detail of Python's
scoping rules, also cause warnings because such comparisons are forbidden
entirely in 3.0.
@end itemize

For applications that embed Python:


@itemize *

@item 
The @code{PySys_SetArgvEx()} function was added in Python 2.6.6,
letting applications close a security hole when the existing
@code{PySys_SetArgv()} function was used.  Check whether you're
calling @code{PySys_SetArgv()} and carefully consider whether the
application should be using @code{PySys_SetArgvEx()} with
`updatepath' set to false.
@end itemize

@c ======================================================================

@node Remerciements<2>,,Portage vers Python 2 6,Nouveautés de Python 2 6
@anchor{whatsnew/2 6 acknowledgements}@anchor{13b4}@anchor{whatsnew/2 6 acks}@anchor{13b5}
@subsection Remerciements


The author would like to thank the following people for offering
suggestions, corrections and assistance with various drafts of this
article: Georg Brandl, Steve Brown, Nick Coghlan, Ralph Corderoy,
Jim Jewett, Kent Johnson, Chris Lambacher,  Martin Michlmayr,
Antoine Pitrou, Brian Warner.

@node Nouveautés de Python 2 5,Nouveautés de Python 2 4,Nouveautés de Python 2 6,Nouveautés de Python
@anchor{whatsnew/2 5 doc}@anchor{13b6}@anchor{whatsnew/2 5 what-s-new-in-python-2-5}@anchor{13b7}
@section Nouveautés de Python 2.5


@*Auteur: 
A.M. Kuchling


@c $Id: whatsnew25.tex 56611 2007-07-29 08:26:10Z georg.brandl $

@c Fix XXX comments

This article explains the new features in Python 2.5.  The final release of
Python 2.5 is scheduled for August 2006; 
@geindex Python Enhancement Proposals; PEP 356
PEP 356@footnote{https://peps.python.org/pep-0356/} describes the planned
release schedule.  Python 2.5 was released on September 19, 2006.

The changes in Python 2.5 are an interesting mix of language and library
improvements. The library enhancements will be more important to Python's user
community, I think, because several widely useful packages were added.  New
modules include ElementTree for XML processing (@code{xml.etree}),
the SQLite database module (@code{sqlite}), and the @ref{2a,,ctypes}
module for calling C functions.

The language changes are of middling significance.  Some pleasant new features
were added, but most of them aren't features that you'll use every day.
Conditional expressions were finally added to the language using a novel syntax;
see section @ref{13b8,,PEP 308 ; Expressions conditionnelles}.  The new '@ref{5bc,,with}' statement will make
writing cleanup code easier (section @ref{13b9,,PEP 343; The 'with' statement}).  Values can now be passed
into generators (section @ref{13ba,,PEP 342; New Generator Features}).  Imports are now visible as either
absolute or relative (section @ref{13bb,,PEP 328; Absolute and Relative Imports}).  Some corner cases of exception
handling are handled better (section @ref{13bc,,PEP 341; Unified try/except/finally}).  All these improvements
are worthwhile, but they're improvements to one specific language feature or
another; none of them are broad modifications to Python's semantics.

As well as the language and library additions, other improvements and bugfixes
were made throughout the source tree.  A search through the SVN change logs
finds there were 353 patches applied and 458 bugs fixed between Python 2.4 and
2.5.  (Both figures are likely to be underestimates.)

This article doesn't try to be a complete specification of the new features;
instead changes are briefly introduced using helpful examples.  For full
details, you should always refer to the documentation for Python 2.5 at
@indicateurl{https://docs.python.org}. If you want to understand the complete implementation
and design rationale, refer to the PEP for a particular new feature.

Comments, suggestions, and error reports for this document are welcome; please
e-mail them to the author or open a bug in the Python bug tracker.

@c ======================================================================

@menu
* PEP 308 ; Expressions conditionnelles: PEP 308 Expressions conditionnelles. 
* PEP 309 ; Application partielle de fonction: PEP 309 Application partielle de fonction. 
* PEP 314; Metadata for Python Software Packages v1.1: PEP 314 Metadata for Python Software Packages v1 1. 
* PEP 328; Absolute and Relative Imports: PEP 328 Absolute and Relative Imports. 
* PEP 338; Executing Modules as Scripts: PEP 338 Executing Modules as Scripts. 
* PEP 341; Unified try/except/finally: PEP 341 Unified try/except/finally. 
* PEP 342; New Generator Features: PEP 342 New Generator Features. 
* PEP 343; The 'with' statement: PEP 343 The 'with' statement<2>. 
* PEP 352; Exceptions as New-Style Classes: PEP 352 Exceptions as New-Style Classes. 
* PEP 353; Using ssize_t as the index type: PEP 353 Using ssize_t as the index type. 
* PEP 357; The '__index__' method: PEP 357 The '__index__' method. 
* Autres changements au langage: Autres changements au langage<16>. 
* Modules ajoutés@comma{} modifiés@comma{} et supprimés: Modules ajoutés modifiés et supprimés. 
* Build and C API Changes: Build and C API Changes<10>. 
* Portage vers Python 2.5: Portage vers Python 2 5. 
* Remerciements: Remerciements<3>. 

@end menu

@node PEP 308 Expressions conditionnelles,PEP 309 Application partielle de fonction,,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-308}@anchor{13b8}@anchor{whatsnew/2 5 pep-308-conditional-expressions}@anchor{13bd}
@subsection PEP 308 : Expressions conditionnelles


For a long time, people have been requesting a way to write conditional
expressions, which are expressions that return value A or value B depending on
whether a Boolean value is true or false.  A conditional expression lets you
write a single assignment statement that has the same effect as the following:

@example
if condition:
    x = true_value
else:
    x = false_value
@end example

There have been endless tedious discussions of syntax on both python-dev and
comp.lang.python.  A vote was even held that found the majority of voters wanted
conditional expressions in some form, but there was no syntax that was preferred
by a clear majority. Candidates included C's @code{cond ? true_v : false_v}, @code{if
cond then true_v else false_v}, and 16 other variations.

Guido van Rossum a finalement choisi une syntaxe surprenante :

@example
x = true_value if condition else false_value
@end example

Evaluation is still lazy as in existing Boolean expressions, so the order of
evaluation jumps around a bit.  The `condition' expression in the middle is
evaluated first, and the `true_value' expression is evaluated only if the
condition was true.  Similarly, the `false_value' expression is only evaluated
when the condition is false.

This syntax may seem strange and backwards; why does the condition go in the
`middle' of the expression, and not in the front as in C's @code{c ? x : y}?  The
decision was checked by applying the new syntax to the modules in the standard
library and seeing how the resulting code read.  In many cases where a
conditional expression is used, one value seems to be the 'common case' and one
value is an 'exceptional case', used only on rarer occasions when the condition
isn't met.  The conditional syntax makes this pattern a bit more obvious:

@example
contents = ((doc + '\n') if doc else '@w{'})
@end example

I read the above statement as meaning "here `contents' is  usually assigned a
value of @code{doc+'\n'}; sometimes  `doc' is empty, in which special case an empty
string is returned."   I doubt I will use conditional expressions very often
where there  isn't a clear common and uncommon case.

There was some discussion of whether the language should require surrounding
conditional expressions with parentheses.  The decision was made to `not'
require parentheses in the Python language's grammar, but as a matter of style I
think you should always use them. Consider these two statements:

@example
# First version -- no parens
level = 1 if logging else 0

# Second version -- with parens
level = (1 if logging else 0)
@end example

In the first version, I think a reader's eye might group the statement into
'level = 1', 'if logging', 'else 0', and think that the condition decides
whether the assignment to `level' is performed.  The second version reads
better, in my opinion, because it makes it clear that the assignment is always
performed and the choice is being made between two values.

Another reason for including the brackets: a few odd combinations of list
comprehensions and lambdas could look like incorrect conditional expressions.
See 
@geindex Python Enhancement Proposals; PEP 308
PEP 308@footnote{https://peps.python.org/pep-0308/} for some examples.  If you put parentheses around your
conditional expressions, you won't run into this case.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 308

@item PEP 308@footnote{https://peps.python.org/pep-0308/} -- Expressions conditionnelles

PEP écrite par Guido van Rossum et Raymond D. Hettinger; implémentée par Thomas Wouters.
@end table


@c ======================================================================

@node PEP 309 Application partielle de fonction,PEP 314 Metadata for Python Software Packages v1 1,PEP 308 Expressions conditionnelles,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-309}@anchor{13be}@anchor{whatsnew/2 5 pep-309-partial-function-application}@anchor{13bf}
@subsection PEP 309 : Application partielle de fonction


The @ref{5e,,functools} module is intended to contain tools for functional-style
programming.

One useful tool in this module is the @code{partial()} function. For programs
written in a functional style, you'll sometimes want to construct variants of
existing functions that have some of the parameters filled in.  Consider a
Python function @code{f(a, b, c)}; you could create a new function @code{g(b, c)} that
was equivalent to @code{f(1, b, c)}.  This is called "partial function
application".

@code{partial()} takes the arguments @code{(function, arg1, arg2, ... kwarg1=value1,
kwarg2=value2)}.  The resulting object is callable, so you can just call it to
invoke `function' with the filled-in arguments.

Voici un exemple court mais réaliste :

@example
import functools

def log (message, subsystem):
    "Write the contents of 'message' to the specified subsystem."
    print '%s: %s' % (subsystem, message)
    ...

server_log = functools.partial(log, subsystem='server')
server_log('Unable to open socket')
@end example

Here's another example, from a program that uses PyGTK.  Here a context-sensitive
pop-up menu is being constructed dynamically.  The callback provided
for the menu option is a partially applied version of the @code{open_item()}
method, where the first argument has been provided.

@example
...
class Application:
    def open_item(self, path):
       ...
    def init (self):
        open_func = functools.partial(self.open_item, item_path)
        popup_menu.append( ("Open", open_func, 1) )
@end example

Another function in the @ref{5e,,functools} module is the
@code{update_wrapper(wrapper, wrapped)} function that helps you write
well-behaved decorators.  @code{update_wrapper()} copies the name, module, and
docstring attribute to a wrapper function so that tracebacks inside the wrapped
function are easier to understand.  For example, you might write:

@example
def my_decorator(f):
    def wrapper(*args, **kwds):
        print 'Calling decorated function'
        return f(*args, **kwds)
    functools.update_wrapper(wrapper, f)
    return wrapper
@end example

@code{wraps()} is a decorator that can be used inside your own decorators to copy
the wrapped function's information.  An alternate  version of the previous
example would be:

@example
def my_decorator(f):
    @@functools.wraps(f)
    def wrapper(*args, **kwds):
        print 'Calling decorated function'
        return f(*args, **kwds)
    return wrapper
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 309

@item PEP 309@footnote{https://peps.python.org/pep-0309/} -- Application partielle de fonction

PEP proposed and written by Peter Harris; implemented by Hye-Shik Chang and Nick
Coghlan, with adaptations by Raymond Hettinger.
@end table


@c ======================================================================

@node PEP 314 Metadata for Python Software Packages v1 1,PEP 328 Absolute and Relative Imports,PEP 309 Application partielle de fonction,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-314}@anchor{13c0}@anchor{whatsnew/2 5 pep-314-metadata-for-python-software-packages-v1-1}@anchor{13c1}
@subsection PEP 314: Metadata for Python Software Packages v1.1


Some simple dependency support was added to Distutils.  The @code{setup()}
function now has @code{requires}, @code{provides}, and @code{obsoletes} keyword
parameters.  When you build a source distribution using the @code{sdist} command,
the dependency information will be recorded in the @code{PKG-INFO} file.

Another new keyword parameter is @code{download_url}, which should be set to a URL
for the package's source code.  This means it's now possible to look up an entry
in the package index, determine the dependencies for a package, and download the
required packages.

@example
VERSION = '1.0'
setup(name='PyPackage',
      version=VERSION,
      requires=['numarray', 'zlib (>=1.1.4)'],
      obsoletes=['OldPackage']
      download_url=('http://www.example.com/pypackage/dist/pkg-%s.tar.gz'
                    % VERSION),
     )
@end example

Another new enhancement to the Python package index at
@indicateurl{https://pypi.org} is storing source and binary archives for a
package.  The new @code{upload} Distutils command will upload a package to
the repository.

Before a package can be uploaded, you must be able to build a distribution using
the @code{sdist} Distutils command.  Once that works, you can run @code{python
setup.py upload} to add your package to the PyPI archive.  Optionally you can
GPG-sign the package by supplying the @code{--sign} and @code{--identity}
options.

Package uploading was implemented by Martin von Löwis and Richard Jones.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 314

@item PEP 314@footnote{https://peps.python.org/pep-0314/} - Metadata for Python Software Packages v1.1

PEP proposed and written by A.M. Kuchling, Richard Jones, and Fred Drake;
implemented by Richard Jones and Fred Drake.
@end table


@c ======================================================================

@node PEP 328 Absolute and Relative Imports,PEP 338 Executing Modules as Scripts,PEP 314 Metadata for Python Software Packages v1 1,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-328}@anchor{13bb}@anchor{whatsnew/2 5 pep-328-absolute-and-relative-imports}@anchor{13c2}
@subsection PEP 328: Absolute and Relative Imports


The simpler part of 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} was implemented in Python 2.4: parentheses could now
be used to enclose the names imported from a module using the @code{from ... import
...} statement, making it easier to import many different names.

The more complicated part has been implemented in Python 2.5: importing a module
can be specified to use absolute or package-relative imports.  The plan is to
move toward making absolute imports the default in future versions of Python.

Let's say you have a package directory like this:

@example
pkg/
pkg/__init__.py
pkg/main.py
pkg/string.py
@end example

This defines a package named @code{pkg} containing the @code{pkg.main} and
@code{pkg.string} submodules.

Consider the code in the @code{main.py} module.  What happens if it executes
the statement @code{import string}?  In Python 2.4 and earlier, it will first look
in the package's directory to perform a relative import, finds
@code{pkg/string.py}, imports the contents of that file as the
@code{pkg.string} module, and that module is bound to the name @code{string} in the
@code{pkg.main} module's namespace.

That's fine if @code{pkg.string} was what you wanted.  But what if you wanted
Python's standard @ref{d2,,string} module?  There's no clean way to ignore
@code{pkg.string} and look for the standard module; generally you had to look at
the contents of @code{sys.modules}, which is slightly unclean.    Holger Krekel's
@code{py.std} package provides a tidier way to perform imports from the standard
library, @code{import py; py.std.string.join()}, but that package isn't available
on all Python installations.

Reading code which relies on relative imports is also less clear, because a
reader may be confused about which module, @ref{d2,,string} or @code{pkg.string},
is intended to be used.  Python users soon learned not to duplicate the names of
standard library modules in the names of their packages' submodules, but you
can't protect against having your submodule's name being used for a new module
added in a future version of Python.

In Python 2.5, you can switch @ref{5cc,,import}'s behaviour to  absolute imports
using a @code{from __future__ import absolute_import} directive.  This absolute-import
behaviour will become the default in a future version (probably Python
2.7).  Once absolute imports  are the default, @code{import string} will always
find the standard library's version. It's suggested that users should begin
using absolute imports as much as possible, so it's preferable to begin writing
@code{from pkg import string} in your code.

Relative imports are still possible by adding a leading period  to the module
name when using the @code{from ... import} form:

@example
# Import names from pkg.string
from .string import name1, name2
# Import pkg.string
from . import string
@end example

This imports the @ref{d2,,string} module relative to the current package, so in
@code{pkg.main} this will import `name1' and `name2' from @code{pkg.string}.
Additional leading periods perform the relative import starting from the parent
of the current package.  For example, code in the @code{A.B.C} module can do:

@example
from . import D                 # Imports A.B.D
from .. import E                # Imports A.E
from ..F import G               # Imports A.F.G
@end example

Leading periods cannot be used with the @code{import modname}  form of the import
statement, only the @code{from ... import} form.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 328

@item PEP 328@footnote{https://peps.python.org/pep-0328/} - Imports: Multi-Line and Absolute/Relative

PEP écrite par Aahz; implémentée par Thomas Wouters.

@item @indicateurl{https://pylib.readthedocs.io/}

The py library by Holger Krekel, which contains the @code{py.std} package.
@end table


@c ======================================================================

@node PEP 338 Executing Modules as Scripts,PEP 341 Unified try/except/finally,PEP 328 Absolute and Relative Imports,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-338}@anchor{13c3}@anchor{whatsnew/2 5 pep-338-executing-modules-as-scripts}@anchor{13c4}
@subsection PEP 338: Executing Modules as Scripts


The @ref{5cb,,-m} switch added in Python 2.4 to execute a module as a script
gained a few more abilities.  Instead of being implemented in C code inside the
Python interpreter, the switch now uses an implementation in a new module,
@ref{bd,,runpy}.

The @ref{bd,,runpy} module implements a more sophisticated import mechanism so that
it's now possible to run modules in a package such as @code{pychecker.checker}.
The module also supports alternative import mechanisms such as the
@ref{131,,zipimport} module.  This means you can add a .zip archive's path to
@code{sys.path} and then use the @ref{5cb,,-m} switch to execute code from the
archive.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 338

@item PEP 338@footnote{https://peps.python.org/pep-0338/} - Executing modules as scripts

PEP written and  implemented by Nick Coghlan.
@end table


@c ======================================================================

@node PEP 341 Unified try/except/finally,PEP 342 New Generator Features,PEP 338 Executing Modules as Scripts,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-341}@anchor{13bc}@anchor{whatsnew/2 5 pep-341-unified-try-except-finally}@anchor{13c5}
@subsection PEP 341: Unified try/except/finally


Until Python 2.5, the @ref{6d3,,try} statement came in two flavours. You could
use a @ref{9b8,,finally} block to ensure that code is always executed, or one or
more @ref{189,,except} blocks to catch  specific exceptions.  You couldn't
combine both @code{except} blocks and a @code{finally} block, because
generating the right bytecode for the combined version was complicated and it
wasn't clear what the semantics of the combined statement should be.

Guido van Rossum spent some time working with Java, which does support the
equivalent of combining @ref{189,,except} blocks and a @ref{9b8,,finally} block,
and this clarified what the statement should mean.  In Python 2.5, you can now
write:

@example
try:
    block-1 ...
except Exception1:
    handler-1 ...
except Exception2:
    handler-2 ...
else:
    else-block
finally:
    final-block
@end example

The code in `block-1' is executed.  If the code raises an exception, the various
@ref{189,,except} blocks are tested: if the exception is of class
@code{Exception1}, `handler-1' is executed; otherwise if it's of class
@code{Exception2}, `handler-2' is executed, and so forth.  If no exception is
raised, the `else-block' is executed.

No matter what happened previously, the `final-block' is executed once the code
block is complete and any raised exceptions handled. Even if there's an error in
an exception handler or the `else-block' and a new exception is raised, the code
in the `final-block' is still run.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 341

@item PEP 341@footnote{https://peps.python.org/pep-0341/} - Unifying try-except and try-finally

PEP written by Georg Brandl;  implementation by Thomas Lee.
@end table


@c ======================================================================

@node PEP 342 New Generator Features,PEP 343 The 'with' statement<2>,PEP 341 Unified try/except/finally,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-342}@anchor{13ba}@anchor{whatsnew/2 5 pep-342-new-generator-features}@anchor{13c6}
@subsection PEP 342: New Generator Features


Python 2.5 adds a simple way to pass values `into' a generator. As introduced in
Python 2.3, generators only produce output; once a generator's code was invoked
to create an iterator, there was no way to pass any new information into the
function when its execution is resumed.  Sometimes the ability to pass in some
information would be useful.  Hackish solutions to this include making the
generator's code look at a global variable and then changing the global
variable's value, or passing in some mutable object that callers then modify.

To refresh your memory of basic generators, here's a simple example:

@example
def counter (maximum):
    i = 0
    while i < maximum:
        yield i
        i += 1
@end example

When you call @code{counter(10)}, the result is an iterator that returns the values
from 0 up to 9.  On encountering the @ref{9bb,,yield} statement, the iterator
returns the provided value and suspends the function's execution, preserving the
local variables. Execution resumes on the following call to the iterator's
@ref{7c2,,next()} method, picking up after the @code{yield} statement.

In Python 2.3, @ref{9bb,,yield} was a statement; it didn't return any value.  In
2.5, @code{yield} is now an expression, returning a value that can be
assigned to a variable or otherwise operated on:

@example
val = (yield i)
@end example

I recommend that you always put parentheses around a @ref{9bb,,yield} expression
when you're doing something with the returned value, as in the above example.
The parentheses aren't always necessary, but it's easier to always add them
instead of having to remember when they're needed.

(
@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/} explains the exact rules, which are that a
@ref{9bb,,yield}-expression must always be parenthesized except when it
occurs at the top-level
expression on the right-hand side of an assignment.  This means you can write
@code{val = yield i} but have to use parentheses when there's an operation, as in
@code{val = (yield i) + 12}.)

Values are sent into a generator by calling its @code{send(value)} method.  The
generator's code is then resumed and the @ref{9bb,,yield} expression returns the
specified `value'.  If the regular @ref{7c2,,next()} method is called, the
@code{yield} returns @ref{660,,None}.

Here's the previous example, modified to allow changing the value of the
internal counter.

@example
def counter (maximum):
    i = 0
    while i < maximum:
        val = (yield i)
        # If value provided, change counter
        if val is not None:
            i = val
        else:
            i += 1
@end example

And here's an example of changing the counter:

@example
>>> it = counter(10)
>>> print it.next()
0
>>> print it.next()
1
>>> print it.send(8)
8
>>> print it.next()
9
>>> print it.next()
Traceback (most recent call last):
  File "t.py", line 15, in ?
    print it.next()
StopIteration
@end example

@ref{9bb,,yield} will usually return @ref{660,,None}, so you should always check
for this case.  Don't just use its value in expressions unless you're sure that
the @code{send()} method will be the only method used to resume your generator
function.

In addition to @code{send()}, there are two other new methods on generators:


@itemize *

@item 
@code{throw(type, value=None, traceback=None)} is used to raise an exception
inside the generator; the exception is raised by the @ref{9bb,,yield} expression
where the generator's execution is paused.

@item 
@code{close()} raises a new @ref{137e,,GeneratorExit} exception inside the generator
to terminate the iteration.  On receiving this exception, the generator's code
must either raise @ref{137e,,GeneratorExit} or @ref{be8,,StopIteration}.  Catching the
@ref{137e,,GeneratorExit} exception and returning a value is illegal and will trigger
a @ref{193,,RuntimeError}; if the function raises some other exception, that
exception is propagated to the caller.  @code{close()} will also be called by
Python's garbage collector when the generator is garbage-collected.

If you need to run cleanup code when a @ref{137e,,GeneratorExit} occurs, I suggest
using a @code{try: ... finally:} suite instead of  catching @ref{137e,,GeneratorExit}.
@end itemize

Ces changements cumulés transforment les générateurs de producteurs unidirectionnels d'information vers un statut hybride à la fois producteur et consommateur.

Generators also become `coroutines', a more generalized form of subroutines.
Subroutines are entered at one point and exited at another point (the top of the
function, and a @ref{9bc,,return} statement), but coroutines can be entered,
exited, and resumed at many different points (the @ref{9bb,,yield} statements).
We'll have to figure out patterns for using coroutines effectively in Python.

The addition of the @code{close()} method has one side effect that isn't obvious.
@code{close()} is called when a generator is garbage-collected, so this means the
generator's code gets one last chance to run before the generator is destroyed.
This last chance means that @code{try...finally} statements in generators can now
be guaranteed to work; the @ref{9b8,,finally} clause will now always get a
chance to run.  The syntactic restriction that you couldn't mix @ref{9bb,,yield}
statements with a @code{try...finally} suite has therefore been removed.  This
seems like a minor bit of language trivia, but using generators and
@code{try...finally} is actually necessary in order to implement the
@ref{5bc,,with} statement described by 
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}.  I'll look at this new statement
in the following  section.

Another even more esoteric effect of this change: previously, the
@code{gi_frame} attribute of a generator was always a frame object. It's now
possible for @code{gi_frame} to be @code{None} once the generator has been
exhausted.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 342

@item PEP 342@footnote{https://peps.python.org/pep-0342/} -- Coroutines `via' des générateurs améliorés

PEP written by  Guido van Rossum and Phillip J. Eby; implemented by Phillip J.
Eby.  Includes examples of  some fancier uses of generators as coroutines.

Earlier versions of these features were proposed in  
@geindex Python Enhancement Proposals; PEP 288
PEP 288@footnote{https://peps.python.org/pep-0288/} by Raymond
Hettinger and 
@geindex Python Enhancement Proposals; PEP 325
PEP 325@footnote{https://peps.python.org/pep-0325/} by Samuele Pedroni.

@item @indicateurl{https://en.wikipedia.org/wiki/Coroutine}

L’article de Wikipédia sur les coroutines.

@item @indicateurl{https://web.archive.org/web/20160321211320/http://www.sidhe.org/~dan/blog/archives/000178.html}

An explanation of coroutines from a Perl point of view, written by Dan Sugalski.
@end table


@c ======================================================================

@node PEP 343 The 'with' statement<2>,PEP 352 Exceptions as New-Style Classes,PEP 342 New Generator Features,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-343}@anchor{13b9}@anchor{whatsnew/2 5 pep-343-the-with-statement}@anchor{13c7}
@subsection PEP 343: The 'with' statement


The '@ref{5bc,,with}' statement clarifies code that previously would use
@code{try...finally} blocks to ensure that clean-up code is executed.  In this
section, I'll discuss the statement as it will commonly be used.  In the next
section, I'll examine the implementation details and show how to write objects
for use with this statement.

The '@ref{5bc,,with}' statement is a new control-flow structure whose basic
structure is:

@example
with expression [as variable]:
    with-block
@end example

The expression is evaluated, and it should result in an object that supports the
context management protocol (that is, has @ref{5b2,,__enter__()} and @ref{12de,,__exit__()}
methods.

The object's @ref{5b2,,__enter__()} is called before `with-block' is executed and
therefore can run set-up code. It also may return a value that is bound to the
name `variable', if given.  (Note carefully that `variable' is `not' assigned
the result of `expression'.)

After execution of the `with-block' is finished, the object's @ref{12de,,__exit__()}
method is called, even if the block raised an exception, and can therefore run
clean-up code.

To enable the statement in Python 2.5, you need to add the following directive
to your module:

@example
from __future__ import with_statement
@end example

The statement will always be enabled in Python 2.6.

Some standard Python objects now support the context management protocol and can
be used with the '@ref{5bc,,with}' statement. File objects are one example:

@example
with open('/etc/passwd', 'r') as f:
    for line in f:
        print line
        ... more processing code ...
@end example

After this statement has executed, the file object in `f' will have been
automatically closed, even if the @ref{2e6,,for} loop raised an exception
part-way through the block.

@cartouche
@quotation Note 
In this case, `f' is the same object created by @ref{505,,open()}, because
@ref{5b2,,__enter__()} returns `self'.
@end quotation
@end cartouche

The @ref{ec,,threading} module's locks and condition variables  also support the
'@ref{5bc,,with}' statement:

@example
lock = threading.Lock()
with lock:
    # Critical section of code
    ...
@end example

The lock is acquired before the block is executed and always released once  the
block is complete.

The new @code{localcontext()} function in the @ref{36,,decimal} module makes it easy
to save and restore the current decimal context, which encapsulates the desired
precision and rounding characteristics for computations:

@example
from decimal import Decimal, Context, localcontext

# Displays with default precision of 28 digits
v = Decimal('578')
print v.sqrt()

with localcontext(Context(prec=16)):
    # All code in this block uses a precision of 16 digits.
    # The original context is restored on exiting the block.
    print v.sqrt()
@end example

@menu
* Écrire des gestionnaires de contexte: Écrire des gestionnaires de contexte<2>. 
* Le module contextlib: Le module contextlib<2>. 

@end menu

@node Écrire des gestionnaires de contexte<2>,Le module contextlib<2>,,PEP 343 The 'with' statement<2>
@anchor{whatsnew/2 5 new-25-context-managers}@anchor{13c8}@anchor{whatsnew/2 5 writing-context-managers}@anchor{13c9}
@subsubsection Écrire des gestionnaires de contexte


Under the hood, the '@ref{5bc,,with}' statement is fairly complicated. Most
people will only use '@code{with}' in company with existing objects and
don't need to know these details, so you can skip the rest of this section if
you like.  Authors of new objects will need to understand the details of the
underlying implementation and should keep reading.

A high-level explanation of the context management protocol is:


@itemize *

@item 
The expression is evaluated and should result in an object called a "context
manager".  The context manager must have @ref{5b2,,__enter__()} and @ref{12de,,__exit__()}
methods.

@item 
The context manager's @ref{5b2,,__enter__()} method is called.  The value returned
is assigned to `VAR'.  If no @code{'as VAR'} clause is present, the value is simply
discarded.

@item 
Le code dans `BLOCK' est exécuté.

@item 
If `BLOCK' raises an exception, the @code{__exit__(type, value, traceback)}
is called with the exception details, the same values returned by
@ref{675,,sys.exc_info()}.  The method's return value controls whether the exception
is re-raised: any false value re-raises the exception, and @code{True} will result
in suppressing it.  You'll only rarely want to suppress the exception, because
if you do the author of the code containing the '@ref{5bc,,with}' statement will
never realize anything went wrong.

@item 
If `BLOCK' didn't raise an exception,  the @ref{12de,,__exit__()} method is still
called, but `type', `value', and `traceback' are all @code{None}.
@end itemize

Let's think through an example.  I won't present detailed code but will only
sketch the methods necessary for a database that supports transactions.

(For people unfamiliar with database terminology: a set of changes to the
database are grouped into a transaction.  Transactions can be either committed,
meaning that all the changes are written into the database, or rolled back,
meaning that the changes are all discarded and the database is unchanged.  See
any database textbook for more information.)

Let's assume there's an object representing a database connection. Our goal will
be to let the user write code like this:

@example
db_connection = DatabaseConnection()
with db_connection as cursor:
    cursor.execute('insert into ...')
    cursor.execute('delete from ...')
    # ... more operations ...
@end example

The transaction should be committed if the code in the block runs flawlessly or
rolled back if there's an exception. Here's the basic interface for
@code{DatabaseConnection} that I'll assume:

@example
class DatabaseConnection:
    # Database interface
    def cursor (self):
        "Returns a cursor object and starts a new transaction"
    def commit (self):
        "Commits current transaction"
    def rollback (self):
        "Rolls back current transaction"
@end example

The @ref{5b2,,__enter__()} method is pretty easy, having only to start a new
transaction.  For this application the resulting cursor object would be a useful
result, so the method will return it.  The user can then add @code{as cursor} to
their '@ref{5bc,,with}' statement to bind the cursor to a variable name.

@example
class DatabaseConnection:
    ...
    def __enter__ (self):
        # Code to start a new transaction
        cursor = self.cursor()
        return cursor
@end example

The @ref{12de,,__exit__()} method is the most complicated because it's where most of
the work has to be done.  The method has to check if an exception occurred.  If
there was no exception, the transaction is committed.  The transaction is rolled
back if there was an exception.

In the code below, execution will just fall off the end of the function,
returning the default value of @code{None}.  @code{None} is false, so the exception
will be re-raised automatically.  If you wished, you could be more explicit and
add a @ref{9bc,,return} statement at the marked location.

@example
class DatabaseConnection:
    ...
    def __exit__ (self, type, value, tb):
        if tb is None:
            # No exception, so commit
            self.commit()
        else:
            # Exception occurred, so rollback.
            self.rollback()
            # return False
@end example

@node Le module contextlib<2>,,Écrire des gestionnaires de contexte<2>,PEP 343 The 'with' statement<2>
@anchor{whatsnew/2 5 contextlibmod}@anchor{13ca}@anchor{whatsnew/2 5 the-contextlib-module}@anchor{13cb}
@subsubsection Le module `contextlib'


The new @ref{23,,contextlib} module provides some functions and a decorator that
are useful for writing objects for use with the '@ref{5bc,,with}' statement.

The decorator is called @code{contextmanager()}, and lets you write a single
generator function instead of defining a new class.  The generator should yield
exactly one value.  The code up to the @ref{9bb,,yield} will be executed as the
@ref{5b2,,__enter__()} method, and the value yielded will be the method's return
value that will get bound to the variable in the '@ref{5bc,,with}' statement's
@code{as} clause, if any.  The code after the @ref{9bb,,yield} will be
executed in the @ref{12de,,__exit__()} method.  Any exception raised in the block will
be raised by the @code{yield} statement.

Our database example from the previous section could be written  using this
decorator as:

@example
from contextlib import contextmanager

@@contextmanager
def db_transaction (connection):
    cursor = connection.cursor()
    try:
        yield cursor
    except:
        connection.rollback()
        raise
    else:
        connection.commit()

db = DatabaseConnection()
with db_transaction(db) as cursor:
    ...
@end example

The @ref{23,,contextlib} module also has a @code{nested(mgr1, mgr2, ...)} function
that combines a number of context managers so you don't need to write nested
'@ref{5bc,,with}' statements.  In this example, the single '@code{with}'
statement both starts a database transaction and acquires a thread lock:

@example
lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
    ...
@end example

Finally, the @code{closing(object)} function returns `object' so that it can be
bound to a variable, and calls @code{object.close} at the end of the block.

@example
import urllib, sys
from contextlib import closing

with closing(urllib.urlopen('http://www.yahoo.com')) as f:
    for line in f:
        sys.stdout.write(line)
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - The "with" statement

PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland,
Guido van Rossum, and Neal Norwitz.  The PEP shows the code generated for a
'@ref{5bc,,with}' statement, which can be helpful in learning how the statement
works.
@end table

The documentation  for the @ref{23,,contextlib} module.


@c ======================================================================

@node PEP 352 Exceptions as New-Style Classes,PEP 353 Using ssize_t as the index type,PEP 343 The 'with' statement<2>,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-352}@anchor{13cc}@anchor{whatsnew/2 5 pep-352-exceptions-as-new-style-classes}@anchor{13cd}
@subsection PEP 352: Exceptions as New-Style Classes


Exception classes can now be new-style classes, not just classic classes, and
the built-in @ref{9c7,,Exception} class and all the standard built-in exceptions
(@ref{428,,NameError}, @ref{1ff,,ValueError}, etc.) are now new-style classes.

The inheritance hierarchy for exceptions has been rearranged a bit. In 2.5, the
inheritance relationships are:

@example
BaseException       # New in Python 2.5
|- KeyboardInterrupt
|- SystemExit
|- Exception
   |- (all other current built-in exceptions)
@end example

This rearrangement was done because people often want to catch all exceptions
that indicate program errors.  @ref{9bf,,KeyboardInterrupt} and @ref{d2e,,SystemExit}
aren't errors, though, and usually represent an explicit action such as the user
hitting @code{Control-C} or code calling @ref{1327,,sys.exit()}.  A bare @code{except:} will
catch all exceptions, so you commonly need to list @ref{9bf,,KeyboardInterrupt} and
@ref{d2e,,SystemExit} in order to re-raise them.  The usual pattern is:

@example
try:
    ...
except (KeyboardInterrupt, SystemExit):
    raise
except:
    # Log error...
    # Continue running program...
@end example

In Python 2.5, you can now write @code{except Exception} to achieve the same
result, catching all the exceptions that usually indicate errors  but leaving
@ref{9bf,,KeyboardInterrupt} and @ref{d2e,,SystemExit} alone.  As in previous versions,
a bare @code{except:} still catches all exceptions.

The goal for Python 3.0 is to require any class raised as an exception to derive
from @ref{5a5,,BaseException} or some descendant of @ref{5a5,,BaseException}, and future
releases in the Python 2.x series may begin to enforce this constraint.
Therefore, I suggest you begin making all your exception classes derive from
@ref{9c7,,Exception} now.  It's been suggested that the bare @code{except:} form should
be removed in Python 3.0, but Guido van Rossum hasn't decided whether to do this
or not.

Raising of strings as exceptions, as in the statement @code{raise "Error
occurred"}, is deprecated in Python 2.5 and will trigger a warning.  The aim is
to be able to remove the string-exception feature in a few releases.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 352

@item PEP 352@footnote{https://peps.python.org/pep-0352/} - Required Superclass for Exceptions

PEP written by  Brett Cannon and Guido van Rossum; implemented by Brett Cannon.
@end table


@c ======================================================================

@node PEP 353 Using ssize_t as the index type,PEP 357 The '__index__' method,PEP 352 Exceptions as New-Style Classes,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-353}@anchor{13ce}@anchor{whatsnew/2 5 pep-353-using-ssize-t-as-the-index-type}@anchor{13cf}
@subsection PEP 353: Using ssize_t as the index type


A wide-ranging change to Python's C API, using a new  @ref{a4e,,Py_ssize_t} type
definition instead of int,  will permit the interpreter to handle more
data on 64-bit platforms. This change doesn't affect Python's capacity on 32-bit
platforms.

Various pieces of the Python interpreter used C's int type to store
sizes or counts; for example, the number of items in a list or tuple were stored
in an int.  The C compilers for most 64-bit platforms still define
int as a 32-bit type, so that meant that lists could only hold up to
@code{2**31 - 1} = 2147483647 items. (There are actually a few different
programming models that 64-bit C compilers can use -- see
@indicateurl{https://unix.org/version2/whatsnew/lp64_wp.html} for a discussion -- but the
most commonly available model leaves int as 32 bits.)

A limit of 2147483647 items doesn't really matter on a 32-bit platform because
you'll run out of memory before hitting the length limit. Each list item
requires space for a pointer, which is 4 bytes, plus space for a
@ref{32f,,PyObject} representing the item.  2147483647*4 is already more bytes
than a 32-bit address space can contain.

It's possible to address that much memory on a 64-bit platform, however.  The
pointers for a list that size would only require 16 GiB of space, so it's not
unreasonable that Python programmers might construct lists that large.
Therefore, the Python interpreter had to be changed to use some type other than
int, and this will be a 64-bit type on 64-bit platforms.  The change
will cause incompatibilities on 64-bit machines, so it was deemed worth making
the transition now, while the number of 64-bit users is still relatively small.
(In 5 or 10 years, we may `all' be on 64-bit machines, and the transition would
be more painful then.)

This change most strongly affects authors of C extension modules.   Python
strings and container types such as lists and tuples  now use
@ref{a4e,,Py_ssize_t} to store their size.   Functions such as
@ref{13d0,,PyList_Size()}  now return @ref{a4e,,Py_ssize_t}.  Code in extension modules
may therefore need to have some variables changed to @ref{a4e,,Py_ssize_t}.

The @ref{55d,,PyArg_ParseTuple()} and @ref{894,,Py_BuildValue()} functions have a new
conversion code, @code{n}, for @ref{a4e,,Py_ssize_t}.   @ref{55d,,PyArg_ParseTuple()}'s
@code{s#} and @code{t#} still output int by default, but you can define the
macro  @code{PY_SSIZE_T_CLEAN} before including @code{Python.h}  to make
them return @ref{a4e,,Py_ssize_t}.

@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/} has a section on conversion guidelines that  extension authors should
read to learn about supporting 64-bit platforms.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 353

@item PEP 353@footnote{https://peps.python.org/pep-0353/} - Using ssize_t as the index type

PEP written and implemented by Martin von Löwis.
@end table


@c ======================================================================

@node PEP 357 The '__index__' method,Autres changements au langage<16>,PEP 353 Using ssize_t as the index type,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 pep-357}@anchor{13d1}@anchor{whatsnew/2 5 pep-357-the-index-method}@anchor{13d2}
@subsection PEP 357: The '__index__' method


The NumPy developers had a problem that could only be solved by adding a new
special method, @code{__index__()}.  When using slice notation, as in
@code{[start:stop:step]}, the values of the `start', `stop', and `step' indexes
must all be either integers or long integers.  NumPy defines a variety of
specialized integer types corresponding to unsigned and signed integers of 8,
16, 32, and 64 bits, but there was no way to signal that these types could be
used as slice indexes.

Slicing can't just use the existing @code{__int__()} method because that method
is also used to implement coercion to integers.  If slicing used
@code{__int__()}, floating-point numbers would also become legal slice indexes
and that's clearly an undesirable behaviour.

Instead, a new special method called @code{__index__()} was added.  It takes no
arguments and returns an integer giving the slice index to use.  For example:

@example
class C:
    def __index__ (self):
        return self.value
@end example

The return value must be either a Python integer or long integer. The
interpreter will check that the type returned is correct, and raises a
@ref{522,,TypeError} if this requirement isn't met.

A corresponding @ref{13d3,,nb_index} slot was added to the C-level
@ref{13d4,,PyNumberMethods} structure to let C extensions implement this protocol.
@code{PyNumber_Index(obj)} can be used in extension code to call the
@code{__index__()} function and retrieve its result.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 357

@item PEP 357@footnote{https://peps.python.org/pep-0357/} - Allowing Any Object to be Used for Slicing

PEP written  and implemented by Travis Oliphant.
@end table


@c ======================================================================

@node Autres changements au langage<16>,Modules ajoutés modifiés et supprimés,PEP 357 The '__index__' method,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 other-lang}@anchor{13d5}@anchor{whatsnew/2 5 other-language-changes}@anchor{13d6}
@subsection Autres changements au langage


Here are all of the changes that Python 2.5 makes to the core Python language.


@itemize *

@item 
The @ref{253,,dict} type has a new hook for letting subclasses provide a default
value when a key isn't contained in the dictionary. When a key isn't found, the
dictionary's @code{__missing__(key)} method will be called.  This hook is used
to implement the new @code{defaultdict} class in the @ref{1d,,collections}
module.  The following example defines a dictionary  that returns zero for any
missing key:

@example
class zerodict (dict):
    def __missing__ (self, key):
        return 0

d = zerodict(@{1:1, 2:2@})
print d[1], d[2]   # Prints 1, 2
print d[3], d[4]   # Prints 0, 0
@end example

@item 
Both 8-bit and Unicode strings have new @code{partition(sep)}  and
@code{rpartition(sep)} methods that simplify a common use case.

The @code{find(S)} method is often used to get an index which is then used to
slice the string and obtain the pieces that are before and after the separator.
@code{partition(sep)} condenses this pattern into a single method call that
returns a 3-tuple containing the substring before the separator, the separator
itself, and the substring after the separator.  If the separator isn't found,
the first element of the tuple is the entire string and the other two elements
are empty.  @code{rpartition(sep)} also returns a 3-tuple but starts searching
from the end of the string; the @code{r} stands for 'reverse'.

Quelques exemples :

@example
>>> ('http://www.python.org').partition('://')
('http', '://', 'www.python.org')
>>> ('file:/usr/share/doc/index.html').partition('://')
('file:/usr/share/doc/index.html', '@w{'}, '@w{'})
>>> (u'Subject: a quick question').partition(':')
(u'Subject', u':', u' a quick question')
>>> 'www.python.org'.rpartition('.')
('www.python', '.', 'org')
>>> 'www.python.org'.rpartition(':')
('@w{'}, '@w{'}, 'www.python.org')
@end example

(Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.)

@item 
The @code{startswith()} and @code{endswith()} methods of string types now accept
tuples of strings to check for.

@example
def is_image_file (filename):
    return filename.endswith(('.gif', '.jpg', '.tiff'))
@end example

(Implemented by Georg Brandl following a suggestion by Tom Lynn.)

@c RFE #1491485

@item 
The @ref{ef3,,min()} and @ref{ef4,,max()} built-in functions gained a @code{key} keyword
parameter analogous to the @code{key} argument for @code{sort()}.  This parameter
supplies a function that takes a single argument and is called for every value
in the list; @ref{ef3,,min()}/@ref{ef4,,max()} will return the element with the
smallest/largest return value from this function. For example, to find the
longest string in a list, you can do:

@example
L = ['medium', 'longest', 'short']
# Prints 'longest'
print max(L, key=len)
# Prints 'short', because lexicographically 'short' has the largest value
print max(L)
@end example

(Contributed by Steven Bethard and Raymond Hettinger.)

@item 
Two new built-in functions, @ref{13d7,,any()} and @ref{13d8,,all()}, evaluate whether an
iterator contains any true or false values.  @ref{13d7,,any()} returns @ref{bfb,,True}
if any value returned by the iterator is true; otherwise it will return
@ref{b25,,False}.  @ref{13d8,,all()} returns @ref{bfb,,True} only if all of the values
returned by the iterator evaluate as true. (Suggested by Guido van Rossum, and
implemented by Raymond Hettinger.)

@item 
The result of a class's @code{__hash__()} method can now be either a long
integer or a regular integer.  If a long integer is returned, the hash of that
value is taken.  In earlier versions the hash value was required to be a
regular integer, but in 2.5 the @ref{13d9,,id()} built-in was changed to always
return non-negative numbers, and users often seem to use @code{id(self)} in
@code{__hash__()} methods (though this is discouraged).

@c Bug #1536021

@item 
ASCII is now the default encoding for modules.  It's now  a syntax error if a
module contains string literals with 8-bit characters but doesn't have an
encoding declaration.  In Python 2.4 this triggered a warning, not a syntax
error.  See 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/}  for how to declare a module's encoding; for example, you
might add  a line like this near the top of the source file:

@example
# -*- coding: latin1 -*-
@end example

@item 
A new warning, @ref{13da,,UnicodeWarning}, is triggered when  you attempt to
compare a Unicode string and an 8-bit string  that can't be converted to Unicode
using the default ASCII encoding.   The result of the comparison is false:

@example
>>> chr(128) == unichr(128)   # Can't convert chr(128) to Unicode
__main__:1: UnicodeWarning: Unicode equal comparison failed
  to convert both arguments to Unicode - interpreting them
  as being unequal
False
>>> chr(127) == unichr(127)   # chr(127) can be converted
True
@end example

Previously this would raise a @ref{a01,,UnicodeDecodeError} exception, but in 2.5
this could result in puzzling problems when accessing a dictionary.  If you
looked up @code{unichr(128)} and @code{chr(128)} was being used as a key, you'd get a
@ref{a01,,UnicodeDecodeError} exception.  Other changes in 2.5 resulted in this
exception being raised instead of suppressed by the code in @code{dictobject.c}
that implements dictionaries.

Raising an exception for such a comparison is strictly correct, but the change
might have broken code, so instead  @ref{13da,,UnicodeWarning} was introduced.

(Implemented by Marc-André Lemburg.)

@item 
One error that Python programmers sometimes make is forgetting to include an
@code{__init__.py} module in a package directory. Debugging this mistake can be
confusing, and usually requires running Python with the @ref{13db,,-v} switch to
log all the paths searched. In Python 2.5, a new @ref{4e4,,ImportWarning} warning is
triggered when an import would have picked up a directory as a package but no
@code{__init__.py} was found.  This warning is silently ignored by default;
provide the @ref{8b4,,-Wd} option when running the Python executable to display
the warning message. (Implemented by Thomas Wouters.)

@item 
The list of base classes in a class definition can now be empty.   As an
example, this is now legal:

@example
class C():
    pass
@end example

(Implemented by Brett Cannon.)
@end itemize

@c ======================================================================

@menu
* Changements de l’interpréteur interactif:: 
* Optimizations: Optimizations<10>. 

@end menu

@node Changements de l’interpréteur interactif,Optimizations<10>,,Autres changements au langage<16>
@anchor{whatsnew/2 5 interactive}@anchor{13dc}@anchor{whatsnew/2 5 interactive-interpreter-changes}@anchor{13dd}
@subsubsection Changements de l’interpréteur interactif


In the interactive interpreter, @code{quit} and @code{exit}  have long been strings so
that new users get a somewhat helpful message when they try to quit:

@example
>>> quit
'Use Ctrl-D (i.e. EOF) to exit.'
@end example

In Python 2.5, @code{quit} and @code{exit} are now objects that still produce string
representations of themselves, but are also callable. Newbies who try @code{quit()}
or @code{exit()} will now exit the interpreter as they expect.  (Implemented by
Georg Brandl.)

The Python executable now accepts the standard long options  @ref{5da,,--help}
and @ref{d09,,--version}; on Windows,  it also accepts the @ref{13de,,/?} option
for displaying a help message. (Implemented by Georg Brandl.)

@c ======================================================================

@node Optimizations<10>,,Changements de l’interpréteur interactif,Autres changements au langage<16>
@anchor{whatsnew/2 5 optimizations}@anchor{13df}@anchor{whatsnew/2 5 opts}@anchor{13e0}
@subsubsection Optimizations


Several of the optimizations were developed at the NeedForSpeed sprint, an event
held in Reykjavik, Iceland, from May 21--28 2006. The sprint focused on speed
enhancements to the CPython implementation and was funded by EWT LLC with local
support from CCP Games.  Those optimizations added at this sprint are specially
marked in the following list.


@itemize *

@item 
When they were introduced  in Python 2.4, the built-in @ref{5c3,,set} and
@ref{5c4,,frozenset} types were built on top of Python's dictionary type.   In 2.5
the internal data structure has been customized for implementing sets, and as a
result sets will use a third less memory and are somewhat faster. (Implemented
by Raymond Hettinger.)

@item 
The speed of some Unicode operations, such as finding substrings, string
splitting, and character map encoding and decoding, has been improved.
(Substring search and splitting improvements were added by Fredrik Lundh and
Andrew Dalke at the NeedForSpeed sprint. Character maps were improved by Walter
Dörwald and Martin von Löwis.)

@c Patch 1313939, 1359618

@item 
The @code{long(str, base)} function is now faster on long digit strings
because fewer intermediate results are calculated.  The peak is for strings of
around 800--1000 digits where  the function is 6 times faster. (Contributed by
Alan McIntyre and committed at the NeedForSpeed sprint.)

@c Patch 1442927

@item 
It's now illegal to mix iterating over a file  with @code{for line in file} and
calling  the file object's @code{read()}/@ref{b9,,readline()}/@code{readlines()}
methods.  Iteration uses an internal buffer and the  @code{read*()} methods
don't use that buffer.   Instead they would return the data following the
buffer, causing the data to appear out of order.  Mixing iteration and these
methods will now trigger a @ref{1ff,,ValueError} from the @code{read*()} method.
(Implemented by Thomas Wouters.)

@c Patch 1397960

@item 
The @ref{d4,,struct} module now compiles structure format  strings into an
internal representation and caches this representation, yielding a 20% speedup.
(Contributed by Bob Ippolito at the NeedForSpeed sprint.)

@item 
The @ref{b8,,re} module got a 1 or 2% speedup by switching to  Python's allocator
functions instead of the system's  @code{malloc()} and @code{free()}.
(Contributed by Jack Diederich at the NeedForSpeed sprint.)

@item 
The code generator's peephole optimizer now performs simple constant folding
in expressions.  If you write something like @code{a = 2+3}, the code generator
will do the arithmetic and produce code corresponding to @code{a = 5}.  (Proposed
and implemented  by Raymond Hettinger.)

@item 
Function calls are now faster because code objects now keep  the most recently
finished frame (a "zombie frame") in an internal field of the code object,
reusing it the next time the code object is invoked.  (Original patch by Michael
Hudson, modified by Armin Rigo and Richard Jones; committed at the NeedForSpeed
sprint.)  Frame objects are also slightly smaller, which may improve cache
locality and reduce memory usage a bit.  (Contributed by Neal Norwitz.)

@c Patch 876206

@c Patch 1337051

@item 
Python's built-in exceptions are now new-style classes, a change that speeds
up instantiation considerably.  Exception handling in Python 2.5 is therefore
about 30% faster than in 2.4. (Contributed by Richard Jones, Georg Brandl and
Sean Reifschneider at the NeedForSpeed sprint.)

@item 
Importing now caches the paths tried, recording whether  they exist or not so
that the interpreter makes fewer  @code{open()} and @code{stat()} calls on
startup. (Contributed by Martin von Löwis and Georg Brandl.)

@c Patch 921466
@end itemize

@c ======================================================================

@node Modules ajoutés modifiés et supprimés,Build and C API Changes<10>,Autres changements au langage<16>,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 modules}@anchor{13e1}@anchor{whatsnew/2 5 new-improved-and-removed-modules}@anchor{13e2}
@subsection Modules ajoutés, modifiés, et supprimés


The standard library received many enhancements and bug fixes in Python 2.5.
Here's a partial list of the most notable changes, sorted alphabetically by
module name. Consult the @code{Misc/NEWS} file in the source tree for a more
complete list of changes, or look through the SVN logs for all the details.


@itemize *

@item 
The @code{audioop} module now supports the a-LAW encoding, and the code for
u-LAW encoding has been improved.  (Contributed by Lars Immisch.)

@item 
The @ref{1b,,codecs} module gained support for incremental codecs.  The
@code{codec.lookup()} function now returns a @code{CodecInfo} instance instead
of a tuple. @code{CodecInfo} instances behave like a 4-tuple to preserve
backward compatibility but also have the attributes @code{encode},
@code{decode}, @code{incrementalencoder}, @code{incrementaldecoder},
@code{streamwriter}, and @code{streamreader}.  Incremental codecs  can receive
input and produce output in multiple chunks; the output is the same as if the
entire input was fed to the non-incremental codec. See the @ref{1b,,codecs} module
documentation for details. (Designed and implemented by Walter Dörwald.)

@c Patch  1436130

@item 
The @ref{1d,,collections} module gained a new type, @code{defaultdict}, that
subclasses the standard @ref{253,,dict} type.  The new type mostly behaves like a
dictionary but constructs a default value when a key isn't present,
automatically adding it to the dictionary for the requested key value.

The first argument to @code{defaultdict}'s constructor is a factory function
that gets called whenever a key is requested but not found. This factory
function receives no arguments, so you can use built-in type constructors such
as @ref{5fc,,list()} or @ref{254,,int()}.  For example,  you can make an index of words
based on their initial letter like this:

@example
words = """Nel mezzo del cammin di nostra vita
mi ritrovai per una selva oscura
che la diritta via era smarrita""".lower().split()

index = defaultdict(list)

for w in words:
    init_letter = w[0]
    index[init_letter].append(w)
@end example

Printing @code{index} results in the following output:

@example
defaultdict(<type 'list'>, @{'c': ['cammin', 'che'], 'e': ['era'],
        'd': ['del', 'di', 'diritta'], 'm': ['mezzo', 'mi'],
        'l': ['la'], 'o': ['oscura'], 'n': ['nel', 'nostra'],
        'p': ['per'], 's': ['selva', 'smarrita'],
        'r': ['ritrovai'], 'u': ['una'], 'v': ['vita', 'via']@}
@end example

(Contribution par Guido van Rossum.)

@item 
The @code{deque} double-ended queue type supplied by the @ref{1d,,collections}
module now has a @code{remove(value)} method that removes the first occurrence
of `value' in the queue, raising @ref{1ff,,ValueError} if the value isn't found.
(Contributed by Raymond Hettinger.)

@item 
New module: The @ref{23,,contextlib} module contains helper functions for use
with the new '@ref{5bc,,with}' statement.  See section @ref{13ca,,Le module contextlib}
for more about this module.

@item 
New module: The @ref{27,,cProfile} module is a C implementation of  the existing
@ref{ae,,profile} module that has much lower overhead. The module's interface is
the same as @ref{ae,,profile}: you run @code{cProfile.run('main()')} to profile a
function, can save profile data to a file, etc.  It's not yet known if the
Hotshot profiler, which is also written in C but doesn't match the
@ref{ae,,profile} module's interface, will continue to be maintained in future
versions of Python.  (Contributed by Armin Rigo.)

Also, the @ref{af,,pstats} module for analyzing the data measured by the profiler
now supports directing the output to any file object by supplying a `stream'
argument to the @code{Stats} constructor. (Contributed by Skip Montanaro.)

@item 
The @ref{29,,csv} module, which parses files in comma-separated value format,
received several enhancements and a number of bugfixes.  You can now set the
maximum size in bytes of a field by calling the
@code{csv.field_size_limit(new_limit)} function; omitting the `new_limit'
argument will return the currently set limit.  The @code{reader} class now has
a @code{line_num} attribute that counts the number of physical lines read from
the source; records can span multiple physical lines, so @code{line_num} is not
the same as the number of records read.

The CSV parser is now stricter about multi-line quoted fields. Previously, if a
line ended within a quoted field without a terminating newline character, a
newline would be inserted into the returned field. This behavior caused problems
when reading files that contained carriage return characters within fields, so
the code was changed to return the field without inserting newlines. As a
consequence, if newlines embedded within fields are important, the input should
be split into lines in a manner that preserves the newline characters.

(Contributed by Skip Montanaro and Andrew McNamara.)

@item 
The @ref{1c7,,datetime} class in the @ref{30,,datetime}  module now has a
@code{strptime(string, format)}  method for parsing date strings, contributed
by Josh Spoerri. It uses the same format characters as @ref{13e3,,time.strptime()} and
@ref{11c6,,time.strftime()}:

@example
from datetime import datetime

ts = datetime.strptime('10:13:15 2006-03-07',
                       '%H:%M:%S %Y-%m-%d')
@end example

@item 
The @code{SequenceMatcher.get_matching_blocks()} method in the @ref{37,,difflib}
module now guarantees to return a minimal list of blocks describing matching
subsequences.  Previously, the algorithm would occasionally break a block of
matching elements into two list entries. (Enhancement by Tim Peters.)

@item 
The @ref{3a,,doctest} module gained a @code{SKIP} option that keeps an example from
being executed at all.  This is intended for code snippets that are usage
examples intended for the reader and aren't actually test cases.

An `encoding' parameter was added to the @code{testfile()} function and the
@code{DocFileSuite} class to specify the file's encoding.  This makes it
easier to use non-ASCII characters in  tests contained within a docstring.
(Contributed by Bjorn Tillenius.)

@c Patch 1080727

@item 
The @ref{3b,,email} package has been updated to version 4.0. (Contributed by
Barry Warsaw.)

@c XXX need to provide some more detail here

@geindex universal newlines;What's new

@item 
The @ref{5a,,fileinput} module was made more flexible. Unicode filenames are now
supported, and a `mode' parameter that defaults to @code{"r"} was added to the
@ref{12b6,,input()} function to allow opening files in binary or @ref{d28,,universal newlines} mode.  Another new parameter, `openhook', lets you use a function
other than @ref{505,,open()}  to open the input files.  Once you're iterating over
the set of files, the @code{FileInput} object's new @ref{13e4,,fileno()} returns
the file descriptor for the currently opened file. (Contributed by Georg
Brandl.)

@item 
In the @ref{5f,,gc} module, the new @code{get_count()} function returns a 3-tuple
containing the current collection counts for the three GC generations.  This is
accounting information for the garbage collector; when these counts reach a
specified threshold, a garbage collection sweep will be made.  The existing
@ref{a28,,gc.collect()} function now takes an optional `generation' argument of 0, 1,
or 2 to specify which generation to collect. (Contributed by Barry Warsaw.)

@item 
The @code{nsmallest()} and  @code{nlargest()} functions in the @ref{68,,heapq}
module  now support a @code{key} keyword parameter similar to the one provided by
the @ref{ef3,,min()}/@ref{ef4,,max()} functions and the @code{sort()} methods.  For
example:

@example
>>> import heapq
>>> L = ["short", 'medium', 'longest', 'longer still']
>>> heapq.nsmallest(2, L)  # Return two lowest elements, lexicographically
['longer still', 'longest']
>>> heapq.nsmallest(2, L, key=len)   # Return two shortest elements
['short', 'medium']
@end example

(Contributed by Raymond Hettinger.)

@item 
The @ref{b3a,,itertools.islice()} function now accepts @code{None} for the start and
step arguments.  This makes it more compatible with the attributes of slice
objects, so that you can now write the following:

@example
s = slice(5)     # Create slice object
itertools.islice(iterable, s.start, s.stop, s.step)
@end example

(Contributed by Raymond Hettinger.)

@item 
The @ref{60a,,format()} function in the @ref{85,,locale} module has been modified and
two new functions were added, @code{format_string()} and @code{currency()}.

The @ref{60a,,format()} function's `val' parameter could previously be a string as
long as no more than one %char specifier appeared; now the parameter must be
exactly one %char specifier with no surrounding text.  An optional `monetary'
parameter was also added which, if @code{True}, will use the locale's rules for
formatting currency in placing a separator between groups of three digits.

To format strings with multiple %char specifiers, use the new
@code{format_string()} function that works like @ref{60a,,format()} but also supports
mixing %char specifiers with arbitrary text.

A new @code{currency()} function was also added that formats a number according
to the current locale's settings.

(Contributed by Georg Brandl.)

@c Patch 1180296

@item 
The @ref{8a,,mailbox} module underwent a massive rewrite to add the capability to
modify mailboxes in addition to reading them.  A new set of classes that include
@code{mbox}, @code{MH}, and @code{Maildir} are used to read mailboxes, and
have an @code{add(message)} method to add messages, @code{remove(key)} to
remove messages, and @code{lock()}/@code{unlock()} to lock/unlock the mailbox.
The following example converts a maildir-format mailbox into an mbox-format
one:

@example
import mailbox

# 'factory=None' uses email.Message.Message as the class representing
# individual messages.
src = mailbox.Maildir('maildir', factory=None)
dest = mailbox.mbox('/tmp/mbox')

for msg in src:
    dest.add(msg)
@end example

(Contributed by Gregory K. Johnson.  Funding was provided by Google's 2005
Summer of Code.)

@item 
New module: the @code{msilib} module allows creating Microsoft Installer
@code{.msi} files and CAB files.  Some support for reading the @code{.msi}
database is also included. (Contributed by Martin von Löwis.)

@item 
The @code{nis} module now supports accessing domains other than the system
default domain by supplying a `domain' argument to the @code{nis.match()} and
@code{nis.maps()} functions. (Contributed by Ben Bell.)

@item 
The @ref{9e,,operator} module's @code{itemgetter()}  and @code{attrgetter()}
functions now support multiple fields.   A call such as
@code{operator.attrgetter('a', 'b')} will return a function  that retrieves the
@code{a} and @code{b} attributes.  Combining  this new feature with the
@code{sort()} method's @code{key} parameter  lets you easily sort lists using
multiple fields. (Contributed by Raymond Hettinger.)

@item 
The @ref{9f,,optparse} module was updated to version 1.5.1 of the Optik library.
The @code{OptionParser} class gained an @code{epilog} attribute, a string
that will be printed after the help message, and a @code{destroy()} method to
break reference cycles created by the object. (Contributed by Greg Ward.)

@item 
The @ref{a0,,os} module underwent several changes.  The @code{stat_float_times}
variable now defaults to true, meaning that @ref{48a,,os.stat()} will now return time
values as floats.  (This doesn't necessarily mean that @ref{48a,,os.stat()} will
return times that are precise to fractions of a second; not all systems support
such precision.)

Constants named @ref{126b,,os.SEEK_SET}, @ref{126c,,os.SEEK_CUR}, and
@ref{126d,,os.SEEK_END} have been added; these are the parameters to the
@ref{10f7,,os.lseek()} function.  Two new constants for locking are
@ref{13e5,,os.O_SHLOCK} and @ref{13e6,,os.O_EXLOCK}.

Two new functions, @code{wait3()} and @code{wait4()}, were added.  They're similar
the @code{waitpid()} function which waits for a child process to exit and returns
a tuple of the process ID and its exit status, but @code{wait3()} and
@code{wait4()} return additional information.  @code{wait3()} doesn't take a
process ID as input, so it waits for any child process to exit and returns a
3-tuple of `process-id', `exit-status', `resource-usage' as returned from the
@ref{13e7,,resource.getrusage()} function. @code{wait4(pid)} does take a process ID.
(Contributed by Chad J. Schroeder.)

On FreeBSD, the @ref{48a,,os.stat()} function now returns  times with nanosecond
resolution, and the returned object now has @code{st_gen} and
@code{st_birthtime}. The @code{st_flags} attribute is also available, if the
platform supports it. (Contributed by Antti Louko and  Diego Pettenò.)

@c (Patch 1180695, 1212117)

@item 
The Python debugger provided by the @ref{a4,,pdb} module can now store lists of
commands to execute when a breakpoint is reached and execution stops.  Once
breakpoint #1 has been created, enter @code{commands 1} and enter a series of
commands to be executed, finishing the list with @code{end}.  The command list can
include commands that resume execution, such as @code{continue} or @code{next}.
(Contributed by Grégoire Dooms.)

@c Patch 790710

@item 
The @ref{a5,,pickle} and @code{cPickle} modules no longer accept a return value
of @code{None} from the @ref{9c1,,__reduce__()} method; the method must return a tuple
of arguments instead.  The ability to return @code{None} was deprecated in Python
2.4, so this completes the removal of the feature.

@item 
The @ref{a8,,pkgutil} module, containing various utility functions for finding
packages, was enhanced to support 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}'s import hooks and now also works for
packages stored in ZIP-format archives. (Contributed by Phillip J. Eby.)

@item 
The pybench benchmark suite by Marc-André Lemburg is now included in the
@code{Tools/pybench} directory.  The pybench suite is an improvement on the
commonly used @code{pystone.py} program because pybench provides a more
detailed measurement of the interpreter's speed.  It times particular operations
such as function calls, tuple slicing, method lookups, and numeric operations,
instead of performing many different operations and reducing the result to a
single number as @code{pystone.py} does.

@item 
The @code{pyexpat} module now uses version 2.0 of the Expat parser.
(Contributed by Trent Mick.)

@item 
The @ref{1365,,Queue} class provided by the @code{Queue} module gained two new
methods.  @code{join()} blocks until all items in the queue have been retrieved
and all processing work on the items  have been completed.  Worker threads call
the other new method,  @code{task_done()}, to signal that processing for an item
has been completed.  (Contributed by Raymond Hettinger.)

@item 
The old @code{regex} and @code{regsub} modules, which have been  deprecated
ever since Python 2.0, have finally been deleted.   Other deleted modules:
@code{statcache}, @code{tzparse}, @code{whrandom}.

@item 
Also deleted: the @code{lib-old} directory, which includes ancient modules
such as @code{dircmp} and @code{ni}, was removed.  @code{lib-old} wasn't on the
default @code{sys.path}, so unless your programs explicitly added the directory to
@code{sys.path}, this removal shouldn't affect your code.

@item 
The @ref{bc,,rlcompleter} module is no longer  dependent on importing the
@ref{b9,,readline} module and therefore now works on non-Unix platforms. (Patch
from Robert Kiendl.)

@c Patch #1472854

@item 
The @ref{12e,,SimpleXMLRPCServer} and @ref{12e,,DocXMLRPCServer}  classes now have a
@code{rpc_paths} attribute that constrains XML-RPC operations to a limited set
of URL paths; the default is to allow only @code{'/'} and @code{'/RPC2'}.  Setting
@code{rpc_paths} to @code{None} or an empty tuple disables  this path checking.

@c Bug #1473048

@item 
The @ref{cb,,socket} module now supports @code{AF_NETLINK} sockets on Linux,
thanks to a patch from Philippe Biondi.   Netlink sockets are a Linux-specific
mechanism for communications between a user-space process and kernel code; an
introductory  article about them is at @indicateurl{https://www.linuxjournal.com/article/7356}.
In Python code, netlink addresses are represented as a tuple of 2 integers,
@code{(pid, group_mask)}.

Two new methods on socket objects, @code{recv_into(buffer)} and
@code{recvfrom_into(buffer)}, store the received data in an object  that
supports the buffer protocol instead of returning the data as a string.  This
means you can put the data directly into an array or a memory-mapped file.

Socket objects also gained @code{getfamily()}, @code{gettype()}, and
@code{getproto()} accessor methods to retrieve the family, type, and protocol
values for the socket.

@item 
New module: the @code{spwd} module provides functions for accessing the shadow
password database on systems that support  shadow passwords.

@item 
The @ref{d4,,struct} is now faster because it  compiles format strings into
@code{Struct} objects with @code{pack()} and @code{unpack()} methods.  This is
similar to how the @ref{b8,,re} module lets you create compiled regular expression
objects.  You can still use the module-level  @code{pack()} and @code{unpack()}
functions; they'll create  @code{Struct} objects and cache them.  Or you can
use  @code{Struct} instances directly:

@example
s = struct.Struct('ih3s')

data = s.pack(1972, 187, 'abc')
year, number, name = s.unpack(data)
@end example

You can also pack and unpack data to and from buffer objects directly using the
@code{pack_into(buffer, offset, v1, v2, ...)} and @code{unpack_from(buffer,
offset)} methods.  This lets you store data directly into an array or a
memory-mapped file.

(@code{Struct} objects were implemented by Bob Ippolito at the NeedForSpeed
sprint.  Support for buffer objects was added by Martin Blais, also at the
NeedForSpeed sprint.)

@item 
The Python developers switched from CVS to Subversion during the 2.5
development process.  Information about the exact build version is available as
the @code{sys.subversion} variable, a 3-tuple of @code{(interpreter-name, branch-name,
revision-range)}.  For example, at the time of writing my copy of 2.5 was
reporting @code{('CPython', 'trunk', '45313:45315')}.

This information is also available to C extensions via the
@ref{13e8,,Py_GetBuildInfo()} function that returns a  string of build information
like this: @code{"trunk:45355:45356M, Apr 13 2006, 07:42:19"}.   (Contributed by
Barry Warsaw.)

@item 
Another new function, @ref{13e9,,sys._current_frames()}, returns the current stack
frames for all running threads as a dictionary mapping thread identifiers to the
topmost stack frame currently active in that thread at the time the function is
called.  (Contributed by Tim Peters.)

@item 
The @code{TarFile} class in the @ref{dd,,tarfile} module now has an
@code{extractall()} method that extracts all members from the archive into the
current working directory.  It's also possible to set a different directory as
the extraction target, and to unpack only a subset of the archive's members.

The compression used for a tarfile opened in stream mode can now be autodetected
using the mode @code{'r|*'}. (Contributed by Lars Gustäbel.)

@c patch 918101

@item 
The @ref{ec,,threading} module now lets you set the stack size used when new
threads are created. The @code{stack_size([*size*])} function returns the
currently configured stack size, and supplying the optional `size' parameter
sets a new value.  Not all platforms support changing the stack size, but
Windows, POSIX threading, and OS/2 all do. (Contributed by Andrew MacIntyre.)

@c Patch 1454481

@item 
The @ref{104,,unicodedata} module has been updated to use version 4.1.0 of the
Unicode character database.  Version 3.2.0 is required  by some specifications,
so it's still available as  @ref{13ea,,unicodedata.ucd_3_2_0}.

@item 
New module: the  @ref{10f,,uuid} module generates  universally unique identifiers
(UUIDs) according to 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}.  The RFC defines several different UUID
versions that are generated from a starting string, from system properties, or
purely randomly.  This module contains a @code{UUID} class and  functions
named @code{uuid1()}, @code{uuid3()}, @code{uuid4()},  and  @code{uuid5()} to
generate different versions of UUID.  (Version 2 UUIDs  are not specified in
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html} and are not supported by this module.)

@example
>>> import uuid
>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
@end example

(Contributed by Ka-Ping Yee.)

@item 
The @ref{113,,weakref} module's @code{WeakKeyDictionary} and
@code{WeakValueDictionary} types gained new methods for iterating over the
weak references contained in the dictionary.  @code{iterkeyrefs()} and
@code{keyrefs()} methods were added to @code{WeakKeyDictionary}, and
@code{itervaluerefs()} and @code{valuerefs()} were added to
@code{WeakValueDictionary}.  (Contributed by Fred L. Drake, Jr.)

@item 
The @ref{114,,webbrowser} module received a number of enhancements. It's now
usable as a script with @code{python -m webbrowser}, taking a URL as the argument;
there are a number of switches  to control the behaviour (@code{-n} for a new
browser window,  @code{-t} for a new tab).  New module-level functions,
@code{open_new()} and @code{open_new_tab()}, were added  to support this.  The
module's @ref{505,,open()} function supports an additional feature, an `autoraise'
parameter that signals whether to raise the open window when possible. A number
of additional browsers were added to the supported list such as Firefox, Opera,
Konqueror, and elinks.  (Contributed by Oleg Broytmann and Georg Brandl.)

@c Patch #754022

@item 
The @ref{12d,,xmlrpclib} module now supports returning  @ref{1c7,,datetime} objects
for the XML-RPC date type.  Supply  @code{use_datetime=True} to the @ref{13eb,,loads()}
function or the @code{Unmarshaller} class to enable this feature. (Contributed
by Skip Montanaro.)

@c Patch 1120353

@item 
The @ref{130,,zipfile} module now supports the ZIP64 version of the  format,
meaning that a .zip archive can now be larger than 4 GiB and can contain
individual files larger than 4 GiB.  (Contributed by Ronald Oussoren.)

@c Patch 1446489

@item 
The @ref{132,,zlib} module's @code{Compress} and @code{Decompress} objects now
support a @ref{25,,copy()} method that makes a copy of the  object's internal state
and returns a new  @code{Compress} or @code{Decompress} object.
(Contributed by Chris AtLee.)

@c Patch 1435422
@end itemize

@c ======================================================================

@menu
* The ctypes package:: 
* The ElementTree package:: 
* The hashlib package:: 
* The sqlite3 package:: 
* The wsgiref package:: 

@end menu

@node The ctypes package,The ElementTree package,,Modules ajoutés modifiés et supprimés
@anchor{whatsnew/2 5 module-ctypes}@anchor{13ec}@anchor{whatsnew/2 5 the-ctypes-package}@anchor{13ed}
@subsubsection The ctypes package


The @ref{2a,,ctypes} package, written by Thomas Heller, has been added  to the
standard library.  @ref{2a,,ctypes} lets you call arbitrary functions  in shared
libraries or DLLs.  Long-time users may remember the @code{dl} module, which
provides functions for loading shared libraries and calling functions in them.
The @ref{2a,,ctypes} package is much fancier.

To load a shared library or DLL, you must create an instance of the
@code{CDLL} class and provide the name or path of the shared library or DLL.
Once that's done, you can call arbitrary functions by accessing them as
attributes of the @code{CDLL} object.

@example
import ctypes

libc = ctypes.CDLL('libc.so.6')
result = libc.printf("Line of output\n")
@end example

Type constructors for the various C types are provided: @code{c_int()},
@code{c_float()}, @code{c_double()}, @code{c_char_p()} (equivalent to char*), and so forth.  Unlike Python's types, the C versions are all mutable; you
can assign to their @code{value} attribute to change the wrapped value.  Python
integers and strings will be automatically converted to the corresponding C
types, but for other types you  must call the correct type constructor.  (And I
mean `must';  getting it wrong will often result in the interpreter crashing
with a segmentation fault.)

You shouldn't use @code{c_char_p()} with a Python string when the C function will
be modifying the memory area, because Python strings are  supposed to be
immutable; breaking this rule will cause puzzling bugs.  When you need a
modifiable memory area, use @code{create_string_buffer()}:

@example
s = "this is a string"
buf = ctypes.create_string_buffer(s)
libc.strfry(buf)
@end example

C functions are assumed to return integers, but you can set the @code{restype}
attribute of the function object to  change this:

@example
>>> libc.atof('2.71828')
-1783957616
>>> libc.atof.restype = ctypes.c_double
>>> libc.atof('2.71828')
2.71828
@end example

@ref{2a,,ctypes} also provides a wrapper for Python's C API  as the
@code{ctypes.pythonapi} object.  This object does `not'  release the global
interpreter lock before calling a function, because the lock must be held when
calling into the interpreter's code.   There's a @ref{13ee,,py_object} type
constructor that will create a  @ref{32f,,PyObject}* pointer.  A simple usage:

@example
import ctypes

d = @{@}
ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d),
          ctypes.py_object("abc"),  ctypes.py_object(1))
# d is now @{'abc', 1@}.
@end example

Don't forget to use @ref{13ee,,py_object()}; if it's omitted you end  up with a
segmentation fault.

@ref{2a,,ctypes} has been around for a while, but people still write  and
distribution hand-coded extension modules because you can't rely on
@ref{2a,,ctypes} being present. Perhaps developers will begin to write  Python
wrappers atop a library accessed through @ref{2a,,ctypes} instead of extension
modules, now that @ref{2a,,ctypes} is included with core Python.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://web.archive.org/web/20180410025338/http://starship.python.net/crew/theller/ctypes/}

The pre-stdlib ctypes web page, with a tutorial, reference, and FAQ.
@end table

The documentation  for the @ref{2a,,ctypes} module.


@c ======================================================================

@node The ElementTree package,The hashlib package,The ctypes package,Modules ajoutés modifiés et supprimés
@anchor{whatsnew/2 5 module-etree}@anchor{13ef}@anchor{whatsnew/2 5 the-elementtree-package}@anchor{13f0}
@subsubsection The ElementTree package


A subset of Fredrik Lundh's ElementTree library for processing XML has been
added to the standard library as @code{xml.etree}.  The available modules are
@code{ElementTree}, @code{ElementPath}, and @code{ElementInclude} from
ElementTree 1.2.6.    The @code{cElementTree} accelerator module is also
included.

The rest of this section will provide a brief overview of using ElementTree.
Full documentation for ElementTree is available at
@indicateurl{https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm}.

ElementTree represents an XML document as a tree of element nodes. The text
content of the document is stored as the @code{text} and @code{tail}
attributes of  (This is one of the major differences between ElementTree and
the Document Object Model; in the DOM there are many different types of node,
including @code{TextNode}.)

The most commonly used parsing function is @code{parse()}, that takes either a
string (assumed to contain a filename) or a file-like object and returns an
@code{ElementTree} instance:

@example
from xml.etree import ElementTree as ET

tree = ET.parse('ex-1.xml')

feed = urllib.urlopen(
          'http://planet.python.org/rss10.xml')
tree = ET.parse(feed)
@end example

Once you have an @code{ElementTree} instance, you can call its @code{getroot()}
method to get the root @code{Element} node.

There's also an @code{XML()} function that takes a string literal and returns an
@code{Element} node (not an @code{ElementTree}).   This function provides a
tidy way to incorporate XML fragments, approaching the convenience of an XML
literal:

@example
svg = ET.XML("""<svg width="10px" version="1.0">
             </svg>""")
svg.set('height', '320px')
svg.append(elem1)
@end example

Each XML element supports some dictionary-like and some list-like access
methods.  Dictionary-like operations are used to access attribute values, and
list-like operations are used to access child nodes.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@item

@code{elem[n]}

@tab

Returns n'th child element.

@item

@code{elem[m:n]}

@tab

Returns list of m'th through n'th child
elements.

@item

@code{len(elem)}

@tab

Returns number of child elements.

@item

@code{list(elem)}

@tab

Returns list of child elements.

@item

@code{elem.append(elem2)}

@tab

Adds `elem2' as a child.

@item

@code{elem.insert(index, elem2)}

@tab

Inserts `elem2' at the specified location.

@item

@code{del elem[n]}

@tab

Deletes n'th child element.

@item

@code{elem.keys()}

@tab

Returns list of attribute names.

@item

@code{elem.get(name)}

@tab

Returns value of attribute `name'.

@item

@code{elem.set(name, value)}

@tab

Sets new value for attribute `name'.

@item

@code{elem.attrib}

@tab

Retrieves the dictionary containing
attributes.

@item

@code{del elem.attrib[name]}

@tab

Supprime l’attribut `name'.

@end multitable


Comments and processing instructions are also represented as @code{Element}
nodes.  To check if a node is a comment or processing instructions:

@example
if elem.tag is ET.Comment:
    ...
elif elem.tag is ET.ProcessingInstruction:
    ...
@end example

To generate XML output, you should call the @code{ElementTree.write()} method.
Like @code{parse()}, it can take either a string or a file-like object:

@example
# Encoding is US-ASCII
tree.write('output.xml')

# Encoding is UTF-8
f = open('output.xml', 'w')
tree.write(f, encoding='utf-8')
@end example

(Caution: the default encoding used for output is ASCII.  For general XML work,
where an element's name may contain arbitrary Unicode characters, ASCII isn't a
very useful encoding because it will raise an exception if an element's name
contains any characters with values greater than 127.  Therefore, it's best to
specify a different encoding such as UTF-8 that can handle any Unicode
character.)

This section is only a partial description of the ElementTree interfaces. Please
read the package's official documentation for more details.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://web.archive.org/web/20201124024954/http://effbot.org/zone/element-index.htm}

Official documentation for ElementTree.
@end table


@c ======================================================================

@node The hashlib package,The sqlite3 package,The ElementTree package,Modules ajoutés modifiés et supprimés
@anchor{whatsnew/2 5 module-hashlib}@anchor{13f1}@anchor{whatsnew/2 5 the-hashlib-package}@anchor{13f2}
@subsubsection The hashlib package


A new @ref{67,,hashlib} module, written by Gregory P. Smith,  has been added to
replace the @code{md5} and @code{sha} modules.  @ref{67,,hashlib} adds support for
additional secure hashes (SHA-224, SHA-256, SHA-384, and SHA-512). When
available, the module uses OpenSSL for fast platform optimized implementations
of algorithms.

The old @code{md5} and @code{sha} modules still exist as wrappers around hashlib
to preserve backwards compatibility.  The new module's interface is very close
to that of the old modules, but not identical. The most significant difference
is that the constructor functions for creating new hashing objects are named
differently.

@example
# Old versions
h = md5.md5()
h = md5.new()

# New version
h = hashlib.md5()

# Old versions
h = sha.sha()
h = sha.new()

# New version
h = hashlib.sha1()

# Hash that weren't previously available
h = hashlib.sha224()
h = hashlib.sha256()
h = hashlib.sha384()
h = hashlib.sha512()

# Alternative form
h = hashlib.new('md5')          # Provide algorithm as a string
@end example

Once a hash object has been created, its methods are the same as before:
@code{update(string)} hashes the specified string into the  current digest
state, @code{digest()} and @code{hexdigest()} return the digest value as a binary
string or a string of hex digits, and @ref{25,,copy()} returns a new hashing object
with the same digest state.


@subsubheading Voir aussi


The documentation  for the @ref{67,,hashlib} module.


@c ======================================================================

@node The sqlite3 package,The wsgiref package,The hashlib package,Modules ajoutés modifiés et supprimés
@anchor{whatsnew/2 5 module-sqlite}@anchor{13f3}@anchor{whatsnew/2 5 the-sqlite3-package}@anchor{13f4}
@subsubsection The sqlite3 package


The pysqlite module (@indicateurl{https://www.pysqlite.org}), a wrapper for the SQLite embedded
database, has been added to the standard library under the package name
@ref{ce,,sqlite3}.

SQLite est une bibliothèque C qui fournit une base de données légère sur disque ne nécessitant pas de processus serveur et qui utilise une variante (non standard) du langage de requête SQL pour accéder aux données. Certaines applications peuvent utiliser SQLite pour le stockage de données internes. Il est également possible de créer une application prototype utilisant SQLite, puis de modifier le code pour utiliser une base de données plus robuste telle que PostgreSQL ou Oracle.

pysqlite was written by Gerhard Häring and provides a SQL interface compliant
with the DB-API 2.0 specification described by 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}.

If you're compiling the Python source yourself, note that the source tree
doesn't include the SQLite code, only the wrapper module. You'll need to have
the SQLite libraries and headers installed before compiling Python, and the
build process will compile the module when the necessary headers are available.

To use the module, you must first create a @code{Connection} object that
represents the database.  Here the data will be stored in the
@code{/tmp/example} file:

@example
conn = sqlite3.connect('/tmp/example')
@end example

Vous pouvez également fournir le nom spécial @code{:memory:} pour créer une base de données dans la mémoire vive.

Once you have a @code{Connection}, you can create a @code{Cursor}  object
and call its @code{execute()} method to perform SQL commands:

@example
c = conn.cursor()

# Create table
c.execute('@w{'}'create table stocks
(date text, trans text, symbol text,
 qty real, price real)'@w{'}')

# Insert a row of data
c.execute("""insert into stocks
          values ('2006-01-05','BUY','RHAT',100,35.14)""")
@end example

Usually your SQL operations will need to use values from Python variables.  You
shouldn't assemble your query using Python's string operations because doing so
is insecure; it makes your program vulnerable to an SQL injection attack.

Instead, use the DB-API's parameter substitution.  Put @code{?} as a placeholder
wherever you want to use a value, and then provide a tuple of values as the
second argument to the cursor's @code{execute()} method.  (Other database modules
may use a different placeholder, such as @code{%s} or @code{:1}.) For example:

@example
# Never do this -- insecure!
symbol = 'IBM'
c.execute("... where symbol = '%s'" % symbol)

# Do this instead
t = (symbol,)
c.execute('select * from stocks where symbol=?', t)

# Larger example
for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
          ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
          ('2006-04-06', 'SELL', 'IBM', 500, 53.00),
         ):
    c.execute('insert into stocks values (?,?,?,?,?)', t)
@end example

To retrieve data after executing a SELECT statement, you can either  treat the
cursor as an iterator, call the cursor's @code{fetchone()} method to retrieve a
single matching row,  or call @code{fetchall()} to get a list of the matching
rows.

Cet exemple utilise la forme itérateur :

@example
>>> c = conn.cursor()
>>> c.execute('select * from stocks order by price')
>>> for row in c:
...    print row
...
(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001)
(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0)
>>>
@end example

For more information about the SQL dialect supported by SQLite, see
@indicateurl{https://www.sqlite.org}.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://www.pysqlite.org}

The pysqlite web page.

@item @indicateurl{https://www.sqlite.org}

Dans la page Web de SQLite, la documentation décrit la syntaxe et les types de données disponibles qui sont pris en charge par cette variante SQL.
@end table

The documentation  for the @ref{ce,,sqlite3} module.


@table @asis

@geindex Python Enhancement Proposals; PEP 249

@item PEP 249@footnote{https://peps.python.org/pep-0249/} — Spécifications de l'API 2.0 pour la base de données

PEP écrite par Marc-André Lemburg.
@end table


@c ======================================================================

@node The wsgiref package,,The sqlite3 package,Modules ajoutés modifiés et supprimés
@anchor{whatsnew/2 5 module-wsgiref}@anchor{13f5}@anchor{whatsnew/2 5 the-wsgiref-package}@anchor{13f6}
@subsubsection The wsgiref package


The Web Server Gateway Interface (WSGI) v1.0 defines a standard interface
between web servers and Python web applications and is described in 
@geindex Python Enhancement Proposals; PEP 333
PEP 333@footnote{https://peps.python.org/pep-0333/}.
The @ref{117,,wsgiref} package is a reference implementation of the WSGI
specification.

@c XXX should this be in a :pep:`333` section instead?

The package includes a basic HTTP server that will run a WSGI application; this
server is useful for debugging but isn't intended for  production use.  Setting
up a server takes only a few lines of code:

@example
from wsgiref import simple_server

wsgi_app = ...

host = '@w{'}
port = 8000
httpd = simple_server.make_server(host, port, wsgi_app)
httpd.serve_forever()
@end example

@c XXX discuss structure of WSGI applications?

@c XXX provide an example using Django or some other framework?


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://web.archive.org/web/20160331090247/http://wsgi.readthedocs.org/en/latest/}

A central web site for WSGI-related resources.

@geindex Python Enhancement Proposals; PEP 333

@item PEP 333@footnote{https://peps.python.org/pep-0333/} - Python Web Server Gateway Interface v1.0

PEP written by Phillip J. Eby.
@end table


@c ======================================================================

@node Build and C API Changes<10>,Portage vers Python 2 5,Modules ajoutés modifiés et supprimés,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 build-and-c-api-changes}@anchor{13f7}@anchor{whatsnew/2 5 build-api}@anchor{13f8}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
The Python source tree was converted from CVS to Subversion,  in a complex
migration procedure that was supervised and flawlessly carried out by Martin von
Löwis.  The procedure was developed as 
@geindex Python Enhancement Proposals; PEP 347
PEP 347@footnote{https://peps.python.org/pep-0347/}.

@item 
Coverity, a company that markets a source code analysis tool called Prevent,
provided the results of their examination of the Python source code.  The
analysis found about 60 bugs that  were quickly fixed.  Many of the bugs were
refcounting problems, often occurring in error-handling code.  See
@indicateurl{https://scan.coverity.com} for the statistics.

@item 
The largest change to the C API came from 
@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/}, which modifies the
interpreter to use a @ref{a4e,,Py_ssize_t} type definition instead of
int.  See the earlier section @ref{13ce,,PEP 353; Using ssize_t as the index type} for a discussion of this
change.

@item 
The design of the bytecode compiler has changed a great deal,  no longer
generating bytecode by traversing the parse tree.  Instead the parse tree is
converted to an abstract syntax tree (or AST), and it is  the abstract syntax
tree that's traversed to produce the bytecode.

It's possible for Python code to obtain AST objects by using the
@ref{190,,compile()} built-in and specifying @code{_ast.PyCF_ONLY_AST} as the value of
the  `flags' parameter:

@example
from _ast import PyCF_ONLY_AST
ast = compile("""a=0
for i in range(10):
    a += i
""", "<string>", 'exec', PyCF_ONLY_AST)

assignment = ast.body[0]
for_loop = ast.body[1]
@end example

No official documentation has been written for the AST code yet, but 
@geindex Python Enhancement Proposals; PEP 339
PEP 339@footnote{https://peps.python.org/pep-0339/}
discusses the design.  To start learning about the code, read the definition of
the various AST nodes in @code{Parser/Python.asdl}.  A Python script reads this
file and generates a set of C structure definitions in
@code{Include/Python-ast.h}.  The @code{PyParser_ASTFromString()} and
@code{PyParser_ASTFromFile()}, defined in @code{Include/pythonrun.h}, take
Python source as input and return the root of an AST representing the contents.
This AST can then be turned into a code object by @code{PyAST_Compile()}.  For
more information, read the source code, and then ask questions on python-dev.

The AST code was developed under Jeremy Hylton's management, and implemented by
(in alphabetical order) Brett Cannon, Nick Coghlan, Grant Edwards, John
Ehresman, Kurt Kaiser, Neal Norwitz, Tim Peters, Armin Rigo, and Neil
Schemenauer, plus the participants in a number of AST sprints at conferences
such as PyCon.

@c List of names taken from Jeremy's python-dev post at

@c https://mail.python.org/pipermail/python-dev/2005-October/057500.html

@item 
Evan Jones's patch to obmalloc, first described in a talk at PyCon DC 2005,
was applied.  Python 2.4 allocated small objects in 256K-sized arenas, but never
freed arenas.  With this patch, Python will free arenas when they're empty.  The
net effect is that on some platforms, when you allocate many objects, Python's
memory usage may actually drop when you delete them and the memory may be
returned to the operating system.  (Implemented by Evan Jones, and reworked by
Tim Peters.)

Note that this change means extension modules must be more careful when
allocating memory.  Python's API has many different functions for allocating
memory that are grouped into families.  For example, @ref{c54,,PyMem_Malloc()},
@ref{101b,,PyMem_Realloc()}, and @ref{13f9,,PyMem_Free()} are one family that allocates
raw memory, while @ref{c56,,PyObject_Malloc()}, @ref{13fa,,PyObject_Realloc()}, and
@ref{c53,,PyObject_Free()} are another family that's supposed to be used for
creating Python objects.

Previously these different families all reduced to the platform's
@code{malloc()} and @code{free()} functions.  This meant  it didn't matter if
you got things wrong and allocated memory with the @code{PyMem} function but
freed it with the @code{PyObject} function.  With 2.5's changes to obmalloc,
these families now do different things and mismatches will probably result in a
segfault.  You should carefully test your C extension modules with Python 2.5.

@item 
The built-in set types now have an official C API.  Call @ref{13fb,,PySet_New()}
and @ref{13fc,,PyFrozenSet_New()} to create a new set, @ref{13fd,,PySet_Add()} and
@ref{13fe,,PySet_Discard()} to add and remove elements, and @ref{13ff,,PySet_Contains()}
and @ref{1400,,PySet_Size()} to examine the set's state. (Contributed by Raymond
Hettinger.)

@item 
C code can now obtain information about the exact revision of the Python
interpreter by calling the  @ref{13e8,,Py_GetBuildInfo()} function that returns a
string of build information like this: @code{"trunk:45355:45356M, Apr 13 2006,
07:42:19"}.   (Contributed by Barry Warsaw.)

@item 
Two new macros can be used to indicate C functions that are local to the
current file so that a faster calling convention can be used.
@code{Py_LOCAL(type)} declares the function as returning a value of the
specified `type' and uses a fast-calling qualifier.
@code{Py_LOCAL_INLINE(type)} does the same thing and also requests the
function be inlined.  If macro @code{PY_LOCAL_AGGRESSIVE} is defined before
@code{python.h} is included, a set of more aggressive optimizations are enabled
for the module; you should benchmark the results to find out if these
optimizations actually make the code faster.  (Contributed by Fredrik Lundh at
the NeedForSpeed sprint.)

@item 
@code{PyErr_NewException(name, base, dict)} can now accept a tuple of base
classes as its `base' argument.  (Contributed by Georg Brandl.)

@item 
The @code{PyErr_Warn()} function for issuing warnings is now deprecated in
favour of @code{PyErr_WarnEx(category, message, stacklevel)} which lets you
specify the number of stack frames separating this function and the caller.  A
`stacklevel' of 1 is the function calling @ref{1401,,PyErr_WarnEx()}, 2 is the
function above that, and so forth.  (Added by Neal Norwitz.)

@item 
The CPython interpreter is still written in C, but  the code can now be
compiled with a C++ compiler without errors.   (Implemented by Anthony Baxter,
Martin von Löwis, Skip Montanaro.)

@item 
The @code{PyRange_New()} function was removed.  It was never documented, never
used in the core code, and had dangerously lax error checking.  In the unlikely
case that your extensions were using it, you can replace it by something like
the following:

@example
range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll",
                              start, stop, step);
@end example
@end itemize

@c ======================================================================

@menu
* Port-Specific Changes:: 

@end menu

@node Port-Specific Changes,,,Build and C API Changes<10>
@anchor{whatsnew/2 5 port-specific-changes}@anchor{1402}@anchor{whatsnew/2 5 ports}@anchor{1403}
@subsubsection Port-Specific Changes



@itemize *

@item 
MacOS X (10.3 and higher): dynamic loading of modules now uses the
@code{dlopen()} function instead of MacOS-specific functions.

@item 
MacOS X: an @code{--enable-universalsdk} switch was added to the
@code{configure} script that compiles the interpreter as a universal binary
able to run on both PowerPC and Intel processors. (Contributed by Ronald
Oussoren; bpo-2573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2573}.)

@item 
Windows: @code{.dll} is no longer supported as a filename extension for
extension modules.  @code{.pyd} is now the only filename extension that will be
searched for.
@end itemize

@c ======================================================================

@node Portage vers Python 2 5,Remerciements<3>,Build and C API Changes<10>,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 porting}@anchor{1404}@anchor{whatsnew/2 5 porting-to-python-2-5}@anchor{1405}
@subsection Portage vers Python 2.5


This section lists previously described changes that may require changes to your
code:


@itemize *

@item 
ASCII is now the default encoding for modules.  It's now  a syntax error if a
module contains string literals with 8-bit characters but doesn't have an
encoding declaration.  In Python 2.4 this triggered a warning, not a syntax
error.

@item 
Previously, the @code{gi_frame} attribute of a generator was always a frame
object.  Because of the 
@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/} changes described in section @ref{13ba,,PEP 342; New Generator Features},
it's now possible for @code{gi_frame} to be @code{None}.

@item 
A new warning, @ref{13da,,UnicodeWarning}, is triggered when  you attempt to
compare a Unicode string and an 8-bit string that can't be converted to Unicode
using the default ASCII encoding.  Previously such comparisons would raise a
@ref{a01,,UnicodeDecodeError} exception.

@item 
Library: the @ref{29,,csv} module is now stricter about multi-line quoted fields.
If your files contain newlines embedded within fields, the input should be split
into lines in a manner which preserves the newline characters.

@item 
Library: the @ref{85,,locale} module's  @ref{60a,,format()} function's would
previously  accept any string as long as no more than one %char specifier
appeared.  In Python 2.5, the argument must be exactly one %char specifier with
no surrounding text.

@item 
Library: The @ref{a5,,pickle} and @code{cPickle} modules no longer accept a
return value of @code{None} from the @ref{9c1,,__reduce__()} method; the method must
return a tuple of arguments instead.  The modules also no longer accept the
deprecated `bin' keyword parameter.

@item 
Library: The @ref{12e,,SimpleXMLRPCServer} and @ref{12e,,DocXMLRPCServer}  classes now
have a @code{rpc_paths} attribute that constrains XML-RPC operations to a
limited set of URL paths; the default is to allow only @code{'/'} and @code{'/RPC2'}.
Setting  @code{rpc_paths} to @code{None} or an empty tuple disables  this path
checking.

@item 
C API: Many functions now use @ref{a4e,,Py_ssize_t}  instead of int to
allow processing more data on 64-bit machines.  Extension code may need to make
the same change to avoid warnings and to support 64-bit machines.  See the
earlier section @ref{13ce,,PEP 353; Using ssize_t as the index type} for a discussion of this change.

@item 
C API:  The obmalloc changes mean that  you must be careful to not mix usage
of the @code{PyMem_*} and @code{PyObject_*} families of functions. Memory
allocated with  one family's @code{*_Malloc} must be  freed with the
corresponding family's @code{*_Free} function.
@end itemize

@c ======================================================================

@node Remerciements<3>,,Portage vers Python 2 5,Nouveautés de Python 2 5
@anchor{whatsnew/2 5 acknowledgements}@anchor{1406}
@subsection Remerciements


The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Georg Brandl,
Nick Coghlan, Phillip J. Eby, Lars Gustäbel, Raymond Hettinger, Ralf W.
Grosse-Kunstleve, Kent Johnson, Iain Lowe, Martin von Löwis, Fredrik Lundh, Andrew
McNamara, Skip Montanaro, Gustavo Niemeyer, Paul Prescod, James Pryor, Mike
Rovner, Scott Weikart, Barry Warsaw, Thomas Wouters.

@node Nouveautés de Python 2 4,Nouveautés de Python 2 3,Nouveautés de Python 2 5,Nouveautés de Python
@anchor{whatsnew/2 4 doc}@anchor{1407}@anchor{whatsnew/2 4 what-s-new-in-python-2-4}@anchor{1408}
@section Nouveautés de Python 2.4


@*Auteur: 
A.M. Kuchling


@c $Id: whatsnew24.tex 54632 2007-03-31 11:59:54Z georg.brandl $

@c Don't write extensive text for new sections; I'll do that.

@c Feel free to add commented-out reminders of things that need

@c to be covered.  --amk

This article explains the new features in Python 2.4.1, released on March 30,
2005.

Python 2.4 is a medium-sized release.  It doesn't introduce as many changes as
the radical Python 2.2, but introduces more features than the conservative 2.3
release.  The most significant new language features are function decorators and
generator expressions; most other changes are to the standard library.

According to the CVS change logs, there were 481 patches applied and 502 bugs
fixed between Python 2.3 and 2.4.  Both figures are likely to be underestimates.

This article doesn't attempt to provide a complete specification of every single
new feature, but instead provides a brief introduction to each feature.  For
full details, you should refer to the documentation for Python 2.4, such as the
Python Library Reference and the Python Reference Manual.  Often you will be
referred to the PEP for a particular new feature for explanations of the
implementation and design rationale.

@c ======================================================================

@menu
* PEP 218; Built-In Set Objects: PEP 218 Built-In Set Objects. 
* PEP 237; Unifying Long Integers and Integers: PEP 237 Unifying Long Integers and Integers. 
* PEP 289; Generator Expressions: PEP 289 Generator Expressions. 
* PEP 292; Simpler String Substitutions: PEP 292 Simpler String Substitutions. 
* PEP 318; Decorators for Functions and Methods: PEP 318 Decorators for Functions and Methods. 
* PEP 322; Reverse Iteration: PEP 322 Reverse Iteration. 
* PEP 324; New subprocess Module: PEP 324 New subprocess Module. 
* PEP 327; Decimal Data Type: PEP 327 Decimal Data Type. 
* PEP 328; Multi-line Imports: PEP 328 Multi-line Imports. 
* PEP 331; Locale-Independent Float/String Conversions: PEP 331 Locale-Independent Float/String Conversions. 
* Autres changements au langage: Autres changements au langage<17>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<3>. 
* Build and C API Changes: Build and C API Changes<11>. 
* Portage vers Python 2.4: Portage vers Python 2 4. 
* Remerciements: Remerciements<4>. 

@end menu

@node PEP 218 Built-In Set Objects,PEP 237 Unifying Long Integers and Integers,,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-218-built-in-set-objects}@anchor{1409}
@subsection PEP 218: Built-In Set Objects


Python 2.3 introduced the @code{sets} module.  C implementations of set data
types have now been added to the Python core as two new built-in types,
@code{set(iterable)} and @code{frozenset(iterable)}.  They provide high speed
operations for membership testing, for eliminating duplicates from sequences,
and for mathematical operations like unions, intersections, differences, and
symmetric differences.

@example
>>> a = set('abracadabra')              # form a set from a string
>>> 'z' in a                            # fast membership testing
False
>>> a                                   # unique letters in a
set(['a', 'r', 'b', 'c', 'd'])
>>> '@w{'}.join(a)                          # convert back into a string
'arbcd'

>>> b = set('alacazam')                 # form a second set
>>> a - b                               # letters in a but not in b
set(['r', 'd', 'b'])
>>> a | b                               # letters in either a or b
set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
>>> a & b                               # letters in both a and b
set(['a', 'c'])
>>> a ^ b                               # letters in a or b but not both
set(['r', 'd', 'b', 'm', 'z', 'l'])

>>> a.add('z')                          # add a new element
>>> a.update('wxy')                     # add multiple new elements
>>> a
set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'x', 'z'])
>>> a.remove('x')                       # take one element out
>>> a
set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'z'])
@end example

The @ref{5c4,,frozenset()} type is an immutable version of @ref{5c3,,set()}. Since it is
immutable and hashable, it may be used as a dictionary key or as a member of
another set.

The @code{sets} module remains in the standard library, and may be useful if you
wish to subclass the @code{Set} or @code{ImmutableSet} classes.  There are
currently no plans to deprecate the module.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 218

@item PEP 218@footnote{https://peps.python.org/pep-0218/} - Adding a Built-In Set Object Type

Originally proposed by Greg Wilson and ultimately implemented by Raymond
Hettinger.
@end table


@c ======================================================================

@node PEP 237 Unifying Long Integers and Integers,PEP 289 Generator Expressions,PEP 218 Built-In Set Objects,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-237-unifying-long-integers-and-integers}@anchor{140a}
@subsection PEP 237: Unifying Long Integers and Integers


The lengthy transition process for this PEP, begun in Python 2.2, takes another
step forward in Python 2.4.  In 2.3, certain integer operations that would
behave differently after int/long unification triggered @ref{40b,,FutureWarning}
warnings and returned values limited to 32 or 64 bits (depending on your
platform).  In 2.4, these expressions no longer produce a warning and instead
produce a different result that's usually a long integer.

The problematic expressions are primarily left shifts and lengthy hexadecimal
and octal constants.  For example, @code{2 << 32} results in a warning in 2.3,
evaluating to 0 on 32-bit platforms.  In Python 2.4, this expression now returns
the correct answer, 8589934592.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 237

@item PEP 237@footnote{https://peps.python.org/pep-0237/} - Unifying Long Integers and Integers

Original PEP written by Moshe Zadka and GvR.  The changes for 2.4 were
implemented by  Kalle Svensson.
@end table


@c ======================================================================

@node PEP 289 Generator Expressions,PEP 292 Simpler String Substitutions,PEP 237 Unifying Long Integers and Integers,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-289-generator-expressions}@anchor{140b}
@subsection PEP 289: Generator Expressions


The iterator feature introduced in Python 2.2 and the @ref{80,,itertools} module
make it easier to write programs that loop through large data sets without
having the entire data set in memory at one time.  List comprehensions don't fit
into this picture very well because they produce a Python list object containing
all of the items.  This unavoidably pulls all of the objects into memory, which
can be a problem if your data set is very large.  When trying to write a
functionally styled program, it would be natural to write something like:

@example
links = [link for link in get_all_links() if not link.followed]
for link in links:
    ...
@end example

instead of

@example
for link in get_all_links():
    if link.followed:
        continue
    ...
@end example

The first form is more concise and perhaps more readable, but if you're dealing
with a large number of link objects you'd have to write the second form to avoid
having all link objects in memory at the same time.

Generator expressions work similarly to list comprehensions but don't
materialize the entire list; instead they create a generator that will return
elements one by one.  The above example could be written as:

@example
links = (link for link in get_all_links() if not link.followed)
for link in links:
    ...
@end example

Generator expressions always have to be written inside parentheses, as in the
above example.  The parentheses signalling a function call also count, so if you
want to create an iterator that will be immediately passed to a function you
could write:

@example
print sum(obj.count for obj in list_all_objects())
@end example

Generator expressions differ from list comprehensions in various small ways.
Most notably, the loop variable (`obj' in the above example) is not accessible
outside of the generator expression.  List comprehensions leave the variable
assigned to its last value; future versions of Python will change this, making
list comprehensions match generator expressions in this respect.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 289

@item PEP 289@footnote{https://peps.python.org/pep-0289/} - Generator Expressions

Proposed by Raymond Hettinger and implemented by Jiwon Seo with early efforts
steered by Hye-Shik Chang.
@end table


@c ======================================================================

@node PEP 292 Simpler String Substitutions,PEP 318 Decorators for Functions and Methods,PEP 289 Generator Expressions,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-292-simpler-string-substitutions}@anchor{140c}
@subsection PEP 292: Simpler String Substitutions


Some new classes in the standard library provide an alternative mechanism for
substituting variables into strings; this style of substitution may be better
for applications where untrained users need to edit templates.

The usual way of substituting variables by name is the @code{%} operator:

@example
>>> '%(page)i: %(title)s' % @{'page':2, 'title': 'The Best of Times'@}
'2: The Best of Times'
@end example

When writing the template string, it can be easy to forget the @code{i} or @code{s}
after the closing parenthesis.  This isn't a big problem if the template is in a
Python module, because you run the code, get an "Unsupported format character"
@ref{1ff,,ValueError}, and fix the problem.  However, consider an application such
as Mailman where template strings or translations are being edited by users who
aren't aware of the Python language.  The format string's syntax is complicated
to explain to such users, and if they make a mistake, it's difficult to provide
helpful feedback to them.

PEP 292 adds a @code{Template} class to the @ref{d2,,string} module that uses
@code{$} to indicate a substitution:

@example
>>> import string
>>> t = string.Template('$page: $title')
>>> t.substitute(@{'page':2, 'title': 'The Best of Times'@})
'2: The Best of Times'
@end example

If a key is missing from the dictionary, the @code{substitute()} method will
raise a @ref{33a,,KeyError}.  There's also a @code{safe_substitute()} method that
ignores missing keys:

@example
>>> t = string.Template('$page: $title')
>>> t.safe_substitute(@{'page':3@})
'3: $title'
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 292

@item PEP 292@footnote{https://peps.python.org/pep-0292/} - Simpler String Substitutions

Écrit et implémenté par Barry Warsaw.
@end table


@c ======================================================================

@node PEP 318 Decorators for Functions and Methods,PEP 322 Reverse Iteration,PEP 292 Simpler String Substitutions,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-318-decorators-for-functions-and-methods}@anchor{140d}
@subsection PEP 318: Decorators for Functions and Methods


Python 2.2 extended Python's object model by adding static methods and class
methods, but it didn't extend Python's syntax to provide any new way of defining
static or class methods.  Instead, you had to write a @ref{140e,,def} statement
in the usual way, and pass the resulting method to a @ref{40c,,staticmethod()} or
@ref{165,,classmethod()} function that would wrap up the function as a method of the
new type. Your code would look like this:

@example
class C:
   def meth (cls):
       ...

   meth = classmethod(meth)   # Rebind name to wrapped-up class method
@end example

If the method was very long, it would be easy to miss or forget the
@ref{165,,classmethod()} invocation after the function body.

The intention was always to add some syntax to make such definitions more
readable, but at the time of 2.2's release a good syntax was not obvious.  Today
a good syntax `still' isn't obvious but users are asking for easier access to
the feature; a new syntactic feature has been added to meet this need.

The new feature is called "function decorators".  The name comes from the idea
that @ref{165,,classmethod()}, @ref{40c,,staticmethod()}, and friends are storing
additional information on a function object; they're `decorating' functions with
more details.

The notation borrows from Java and uses the @code{'@@'} character as an indicator.
Using the new syntax, the example above would be written:

@example
class C:

   @@classmethod
   def meth (cls):
       ...
@end example

The @code{@@classmethod} is shorthand for the @code{meth=classmethod(meth)} assignment.
More generally, if you have the following:

@example
@@A
@@B
@@C
def f ():
    ...
@end example

It's equivalent to the following pre-decorator code:

@example
def f(): ...
f = A(B(C(f)))
@end example

Decorators must come on the line before a function definition, one decorator per
line, and can't be on the same line as the def statement, meaning that @code{@@A def
f(): ...} is illegal.  You can only decorate function definitions, either at
the module level or inside a class; you can't decorate class definitions.

A decorator is just a function that takes the function to be decorated as an
argument and returns either the same function or some new object.  The return
value of the decorator need not be callable (though it typically is), unless
further decorators will be applied to the result.  It's easy to write your own
decorators.  The following simple example just sets an attribute on the function
object:

@example
>>> def deco(func):
...    func.attr = 'decorated'
...    return func
...
>>> @@deco
... def f(): pass
...
>>> f
<function f at 0x402ef0d4>
>>> f.attr
'decorated'
>>>
@end example

As a slightly more realistic example, the following decorator checks that the
supplied argument is an integer:

@example
def require_int (func):
    def wrapper (arg):
        assert isinstance(arg, int)
        return func(arg)

    return wrapper

@@require_int
def p1 (arg):
    print arg

@@require_int
def p2(arg):
    print arg*2
@end example

An example in 
@geindex Python Enhancement Proposals; PEP 318
PEP 318@footnote{https://peps.python.org/pep-0318/} contains a fancier version of this idea that lets you
both specify the required type and check the returned type.

Decorator functions can take arguments.  If arguments are supplied, your
decorator function is called with only those arguments and must return a new
decorator function; this function must take a single function and return a
function, as previously described.  In other words, @code{@@A @@B @@C(args)} becomes:

@example
def f(): ...
_deco = C(args)
f = A(B(_deco(f)))
@end example

Getting this right can be slightly brain-bending, but it's not too difficult.

A small related change makes the @ref{12b2,,func_name}
attribute of functions
writable.  This attribute is used to display function names in tracebacks, so
decorators should change the name of any new function that's constructed and
returned.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 318

@item PEP 318@footnote{https://peps.python.org/pep-0318/} - Decorators for Functions, Methods and Classes

Written  by Kevin D. Smith, Jim Jewett, and Skip Montanaro.  Several people
wrote patches implementing function decorators, but the one that was actually
checked in was patch #979728, written by Mark Russell.

@item @indicateurl{https://wiki.python.org/moin/PythonDecoratorLibrary}

This Wiki page contains several examples of decorators.
@end table


@c ======================================================================

@node PEP 322 Reverse Iteration,PEP 324 New subprocess Module,PEP 318 Decorators for Functions and Methods,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-322-reverse-iteration}@anchor{140f}
@subsection PEP 322: Reverse Iteration


A new built-in function, @code{reversed(seq)}, takes a sequence and returns an
iterator that loops over the elements of the sequence  in reverse order.

@example
>>> for i in reversed(xrange(1,4)):
...    print i
...
3
2
1
@end example

Compared to extended slicing, such as @code{range(1,4)[::-1]}, @ref{850,,reversed()} is
easier to read, runs faster, and uses substantially less memory.

Note that @ref{850,,reversed()} only accepts sequences, not arbitrary iterators.  If
you want to reverse an iterator, first convert it to  a list with @ref{5fc,,list()}.

@example
>>> input = open('/etc/passwd', 'r')
>>> for line in reversed(list(input)):
...   print line
...
root:*:0:0:System Administrator:/var/root:/bin/tcsh
  ...
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 322

@item PEP 322@footnote{https://peps.python.org/pep-0322/} - Reverse Iteration

Written and implemented by Raymond Hettinger.
@end table


@c ======================================================================

@node PEP 324 New subprocess Module,PEP 327 Decimal Data Type,PEP 322 Reverse Iteration,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-324-new-subprocess-module}@anchor{1410}
@subsection PEP 324: New subprocess Module


The standard library provides a number of ways to execute a subprocess, offering
different features and different levels of complexity.
@code{os.system(command)} is easy to use, but slow (it runs a shell process
which executes the command) and dangerous (you have to be careful about escaping
the shell's metacharacters).  The @code{popen2} module offers classes that can
capture standard output and standard error from the subprocess, but the naming
is confusing.  The @ref{d5,,subprocess} module cleans  this up, providing a unified
interface that offers all the features you might need.

Instead of @code{popen2}'s collection of classes, @ref{d5,,subprocess} contains a
single class called @ref{197,,subprocess.Popen}  whose constructor supports a number of
different keyword arguments.

@example
class Popen(args, bufsize=0, executable=None,
            stdin=None, stdout=None, stderr=None,
            preexec_fn=None, close_fds=False, shell=False,
            cwd=None, env=None, universal_newlines=False,
            startupinfo=None, creationflags=0):
@end example

`args' is commonly a sequence of strings that will be the arguments to the
program executed as the subprocess.  (If the `shell' argument is true, `args'
can be a string which will then be passed on to the shell for interpretation,
just as @ref{1411,,os.system()} does.)

`stdin', `stdout', and `stderr' specify what the subprocess's input, output, and
error streams will be.  You can provide a file object or a file descriptor, or
you can use the constant @code{subprocess.PIPE} to create a pipe between the
subprocess and the parent.

@geindex universal newlines;What's new

The constructor has a number of handy options:


@itemize *

@item 
`close_fds' requests that all file descriptors be closed before running the
subprocess.

@item 
`cwd' specifies the working directory in which the subprocess will be executed
(defaulting to whatever the parent's working directory is).

@item 
`env' is a dictionary specifying environment variables.

@item 
`preexec_fn' is a function that gets called before the child is started.

@item 
`universal_newlines' opens the child's input and output using Python's
@ref{d28,,universal newlines} feature.
@end itemize

Once you've created the @code{Popen} instance,  you can call its @code{wait()}
method to pause until the subprocess has exited, @code{poll()} to check if it's
exited without pausing,  or @code{communicate(data)} to send the string `data'
to the subprocess's standard input.   @code{communicate(data)}  then reads any
data that the subprocess has sent to its standard output  or standard error,
returning a tuple @code{(stdout_data, stderr_data)}.

@code{call()} is a shortcut that passes its arguments along to the @code{Popen}
constructor, waits for the command to complete, and returns the status code of
the subprocess.  It can serve as a safer analog to @ref{1411,,os.system()}:

@example
sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
if sts == 0:
    # Success
    ...
else:
    # dpkg returned an error
    ...
@end example

The command is invoked without use of the shell.  If you really do want to  use
the shell, you can add @code{shell=True} as a keyword argument and provide a string
instead of a sequence:

@example
sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True)
@end example

The PEP takes various examples of shell and Python code and shows how they'd be
translated into Python code that uses @ref{d5,,subprocess}.  Reading this section
of the PEP is highly recommended.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 324

@item PEP 324@footnote{https://peps.python.org/pep-0324/} - subprocess - New process module

Written and implemented by Peter Åstrand, with assistance from Fredrik Lundh and
others.
@end table


@c ======================================================================

@node PEP 327 Decimal Data Type,PEP 328 Multi-line Imports,PEP 324 New subprocess Module,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-327-decimal-data-type}@anchor{1412}
@subsection PEP 327: Decimal Data Type


Python has always supported floating-point (FP) numbers, based on the underlying
C double type, as a data type.  However, while most programming
languages provide a floating-point type, many people (even programmers) are
unaware that floating-point numbers don't represent certain decimal fractions
accurately.  The new @code{Decimal} type can represent these fractions
accurately, up to a user-specified precision limit.

@menu
* Why is Decimal needed?:: 
* The Decimal type:: 
* The Context type:: 

@end menu

@node Why is Decimal needed?,The Decimal type,,PEP 327 Decimal Data Type
@anchor{whatsnew/2 4 why-is-decimal-needed}@anchor{1413}
@subsubsection Why is Decimal needed?


The limitations arise from the representation used for floating-point numbers.
FP numbers are made up of three components:


@itemize *

@item 
The sign, which is positive or negative.

@item 
The mantissa, which is a single-digit binary number   followed by a fractional
part.  For example, @code{1.01} in base-2 notation is @code{1 + 0/2 + 1/4}, or 1.25 in
decimal notation.

@item 
The exponent, which tells where the decimal point is located in the number
represented.
@end itemize

For example, the number 1.25 has positive sign, a mantissa value of 1.01 (in
binary), and an exponent of 0 (the decimal point doesn't need to be shifted).
The number 5 has the same sign and mantissa, but the exponent is 2 because the
mantissa is multiplied by 4 (2 to the power of the exponent 2); 1.25 * 4 equals
5.

Modern systems usually provide floating-point support that conforms to a
standard called IEEE 754.  C's double type is usually implemented as a
64-bit IEEE 754 number, which uses 52 bits of space for the mantissa.  This
means that numbers can only be specified to 52 bits of precision.  If you're
trying to represent numbers whose expansion repeats endlessly, the expansion is
cut off after 52 bits. Unfortunately, most software needs to produce output in
base 10, and common fractions in base 10 are often repeating decimals in binary.
For example, 1.1 decimal is binary @code{1.0001100110011 ...}; .1 = 1/16 + 1/32 +
1/256 plus an infinite number of additional terms.  IEEE 754 has to chop off
that infinitely repeated decimal after 52 digits, so the representation is
slightly inaccurate.

Sometimes you can see this inaccuracy when the number is printed:

@example
>>> 1.1
1.1000000000000001
@end example

The inaccuracy isn't always visible when you print the number because the
FP-to-decimal-string conversion is provided by the C library, and most C libraries try
to produce sensible output.  Even if it's not displayed, however, the inaccuracy
is still there and subsequent operations can magnify the error.

For many applications this doesn't matter.  If I'm plotting points and
displaying them on my monitor, the difference between 1.1 and 1.1000000000000001
is too small to be visible.  Reports often limit output to a certain number of
decimal places, and if you round the number to two or three or even eight
decimal places, the error is never apparent.  However, for applications where it
does matter,  it's a lot of work to implement your own custom arithmetic
routines.

Hence, the @code{Decimal} type was created.

@node The Decimal type,The Context type,Why is Decimal needed?,PEP 327 Decimal Data Type
@anchor{whatsnew/2 4 the-decimal-type}@anchor{1414}
@subsubsection The @code{Decimal} type


A new module, @ref{36,,decimal}, was added to Python's standard library.  It
contains two classes, @code{Decimal} and @code{Context}.  @code{Decimal}
instances represent numbers, and @code{Context} instances are used to wrap up
various settings such as the precision and default rounding mode.

@code{Decimal} instances are immutable, like regular Python integers and FP
numbers; once it's been created, you can't change the value an instance
represents.  @code{Decimal} instances can be created from integers or
strings:

@example
>>> import decimal
>>> decimal.Decimal(1972)
Decimal("1972")
>>> decimal.Decimal("1.1")
Decimal("1.1")
@end example

You can also provide tuples containing the sign, the mantissa represented  as a
tuple of decimal digits, and the exponent:

@example
>>> decimal.Decimal((1, (1, 4, 7, 5), -2))
Decimal("-14.75")
@end example

Cautionary note: the sign bit is a Boolean value, so 0 is positive and 1 is
negative.

Converting from floating-point numbers poses a bit of a problem: should the FP
number representing 1.1 turn into the decimal number for exactly 1.1, or for 1.1
plus whatever inaccuracies are introduced? The decision was to dodge the issue
and leave such a conversion out of the API.  Instead, you should convert the
floating-point number into a string using the desired precision and pass the
string to the @code{Decimal} constructor:

@example
>>> f = 1.1
>>> decimal.Decimal(str(f))
Decimal("1.1")
>>> decimal.Decimal('%.12f' % f)
Decimal("1.100000000000")
@end example

Once you have @code{Decimal} instances, you can perform the usual mathematical
operations on them.  One limitation: exponentiation requires an integer
exponent:

@example
>>> a = decimal.Decimal('35.72')
>>> b = decimal.Decimal('1.73')
>>> a+b
Decimal("37.45")
>>> a-b
Decimal("33.99")
>>> a*b
Decimal("61.7956")
>>> a/b
Decimal("20.64739884393063583815028902")
>>> a ** 2
Decimal("1275.9184")
>>> a**b
Traceback (most recent call last):
  ...
decimal.InvalidOperation: x ** (non-integer)
@end example

You can combine @code{Decimal} instances with integers, but not with
floating-point numbers:

@example
>>> a + 4
Decimal("39.72")
>>> a + 4.5
Traceback (most recent call last):
  ...
TypeError: You can interact Decimal only with int, long or Decimal data types.
>>>
@end example

@code{Decimal} numbers can be used with the @ref{8d,,math} and @ref{18,,cmath}
modules, but note that they'll be immediately converted to  floating-point
numbers before the operation is performed, resulting in a possible loss of
precision and accuracy.  You'll also get back a regular floating-point number
and not a @code{Decimal}.

@example
>>> import math, cmath
>>> d = decimal.Decimal('123456789012.345')
>>> math.sqrt(d)
351364.18288201344
>>> cmath.sqrt(-d)
351364.18288201344j
@end example

@code{Decimal} instances have a @code{sqrt()} method that returns a
@code{Decimal}, but if you need other things such as trigonometric functions
you'll have to implement them.

@example
>>> d.sqrt()
Decimal("351364.1828820134592177245001")
@end example

@node The Context type,,The Decimal type,PEP 327 Decimal Data Type
@anchor{whatsnew/2 4 the-context-type}@anchor{1415}
@subsubsection The @code{Context} type


Instances of the @code{Context} class encapsulate several settings for
decimal operations:


@itemize *

@item 
@code{prec} is the precision, the number of decimal places.

@item 
@code{rounding} specifies the rounding mode.  The @ref{36,,decimal} module has
constants for the various possibilities: @code{ROUND_DOWN},
@code{ROUND_CEILING},  @code{ROUND_HALF_EVEN}, and various others.

@item 
@code{traps} is a dictionary specifying what happens on encountering certain
error conditions: either  an exception is raised or  a value is returned.  Some
examples of error conditions are division by zero, loss of precision, and
overflow.
@end itemize

There's a thread-local default context available by calling @code{getcontext()};
you can change the properties of this context to alter the default precision,
rounding, or trap handling.  The following example shows the effect of changing
the precision of the default context:

@example
>>> decimal.getcontext().prec
28
>>> decimal.Decimal(1) / decimal.Decimal(7)
Decimal("0.1428571428571428571428571429")
>>> decimal.getcontext().prec = 9
>>> decimal.Decimal(1) / decimal.Decimal(7)
Decimal("0.142857143")
@end example

The default action for error conditions is selectable; the module can either
return a special value such as infinity or not-a-number, or exceptions can be
raised:

@example
>>> decimal.Decimal(1) / decimal.Decimal(0)
Traceback (most recent call last):
  ...
decimal.DivisionByZero: x / 0
>>> decimal.getcontext().traps[decimal.DivisionByZero] = False
>>> decimal.Decimal(1) / decimal.Decimal(0)
Decimal("Infinity")
>>>
@end example

The @code{Context} instance also has various methods for formatting  numbers
such as @code{to_eng_string()} and @code{to_sci_string()}.

For more information, see the documentation for the @ref{36,,decimal} module, which
includes a quick-start tutorial and a reference.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 327

@item PEP 327@footnote{https://peps.python.org/pep-0327/} - Decimal Data Type

Written by Facundo Batista and implemented by Facundo Batista, Eric Price,
Raymond Hettinger, Aahz, and Tim Peters.

@item http://www.lahey.com/float.htm@footnote{https://web.archive.org/web/20230604072523/http://www.lahey.com/float.htm}

The article uses Fortran code to illustrate many of the problems that
floating-point inaccuracy can cause.

@item @indicateurl{https://speleotrove.com/decimal/}

A description of a decimal-based representation.  This representation is being
proposed as a standard, and underlies the new Python decimal type.  Much of this
material was written by Mike Cowlishaw, designer of the Rexx language.
@end table


@c ======================================================================

@node PEP 328 Multi-line Imports,PEP 331 Locale-Independent Float/String Conversions,PEP 327 Decimal Data Type,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-328-multi-line-imports}@anchor{1416}
@subsection PEP 328: Multi-line Imports


One language change is a small syntactic tweak aimed at making it easier to
import many names from a module.  In a @code{from module import names} statement,
`names' is a sequence of names separated by commas.  If the sequence is  very
long, you can either write multiple imports from the same module, or you can use
backslashes to escape the line endings like this:

@example
from SimpleXMLRPCServer import SimpleXMLRPCServer,\
            SimpleXMLRPCRequestHandler,\
            CGIXMLRPCRequestHandler,\
            resolve_dotted_attribute
@end example

The syntactic change in Python 2.4 simply allows putting the names within
parentheses.  Python ignores newlines within a parenthesized expression, so the
backslashes are no longer needed:

@example
from SimpleXMLRPCServer import (SimpleXMLRPCServer,
                                SimpleXMLRPCRequestHandler,
                                CGIXMLRPCRequestHandler,
                                resolve_dotted_attribute)
@end example

The PEP also proposes that all @ref{5cc,,import} statements be absolute imports,
with a leading @code{.} character to indicate a relative import.  This part of the
PEP was not implemented for Python 2.4, but was completed for Python 2.5.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 328

@item PEP 328@footnote{https://peps.python.org/pep-0328/} - Imports: Multi-Line and Absolute/Relative

Written by Aahz.  Multi-line imports were implemented by Dima Dorfman.
@end table


@c ======================================================================

@node PEP 331 Locale-Independent Float/String Conversions,Autres changements au langage<17>,PEP 328 Multi-line Imports,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 pep-331-locale-independent-float-string-conversions}@anchor{1417}
@subsection PEP 331: Locale-Independent Float/String Conversions


The @ref{85,,locale} modules lets Python software select various conversions and
display conventions that are localized to a particular country or language.
However, the module was careful to not change the numeric locale because various
functions in Python's implementation required that the numeric locale remain set
to the @code{'C'} locale.  Often this was because the code was using the C
library's @code{atof()} function.

Not setting the numeric locale caused trouble for extensions that used third-party
C libraries, however, because they wouldn't have the correct locale set.
The motivating example was GTK+, whose user interface widgets weren't displaying
numbers in the current locale.

The solution described in the PEP is to add three new functions to the Python
API that perform ASCII-only conversions, ignoring the locale setting:


@itemize *

@item 
@code{PyOS_ascii_strtod(str, ptr)}  and @code{PyOS_ascii_atof(str, ptr)}
both convert a string to a C double.

@item 
@code{PyOS_ascii_formatd(buffer, buf_len, format, d)} converts a
double to an ASCII string.
@end itemize

The code for these functions came from the GLib library
(https://developer-old.gnome.org/glib/2.26/@footnote{http://web.archive.org/web/20210306104320/https://developer.gnome.org/glib/2.26/}), whose developers kindly
relicensed the relevant functions and donated them to the Python Software
Foundation.  The @ref{85,,locale} module  can now change the numeric locale,
letting extensions such as GTK+  produce the correct results.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 331

@item PEP 331@footnote{https://peps.python.org/pep-0331/} - Locale-Independent Float/String Conversions

Written by Christian R. Reis, and implemented by Gustavo Carneiro.
@end table


@c ======================================================================

@node Autres changements au langage<17>,New Improved and Deprecated Modules<3>,PEP 331 Locale-Independent Float/String Conversions,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 other-language-changes}@anchor{1418}
@subsection Autres changements au langage


Here are all of the changes that Python 2.4 makes to the core Python language.


@itemize *

@item 
Decorators for functions and methods were added (
@geindex Python Enhancement Proposals; PEP 318
PEP 318@footnote{https://peps.python.org/pep-0318/}).

@item 
Built-in @ref{5c3,,set()} and @ref{5c4,,frozenset()} types were  added (
@geindex Python Enhancement Proposals; PEP 218
PEP 218@footnote{https://peps.python.org/pep-0218/}).
Other new built-ins include the @code{reversed(seq)} function (
@geindex Python Enhancement Proposals; PEP 322
PEP 322@footnote{https://peps.python.org/pep-0322/}).

@item 
Generator expressions were added (
@geindex Python Enhancement Proposals; PEP 289
PEP 289@footnote{https://peps.python.org/pep-0289/}).

@item 
Certain numeric expressions no longer return values restricted to 32 or 64
bits (
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}).

@item 
You can now put parentheses around the list of names in a @code{from module import
names} statement (
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/}).

@item 
The @ref{1419,,dict.update()} method now accepts the same argument forms as the
@ref{253,,dict} constructor.  This includes any mapping, any iterable of key/value
pairs, and keyword arguments. (Contributed by Raymond Hettinger.)

@item 
The string methods @code{ljust()}, @code{rjust()}, and @code{center()} now take
an optional argument for specifying a fill character other than a space.
(Contributed by Raymond Hettinger.)

@item 
Strings also gained an @code{rsplit()} method that works like the @code{split()}
method but splits from the end of the string.   (Contributed by Sean
Reifschneider.)

@example
>>> 'www.python.org'.split('.', 1)
['www', 'python.org']
'www.python.org'.rsplit('.', 1)
['www.python', 'org']
@end example

@item 
Three keyword parameters, `cmp', `key', and `reverse', were added to the
@code{sort()} method of lists. These parameters make some common usages of
@code{sort()} simpler. All of these parameters are optional.

For the `cmp' parameter, the value should be a comparison function that takes
two parameters and returns -1, 0, or +1 depending on how the parameters compare.
This function will then be used to sort the list.  Previously this was the only
parameter that could be provided to @code{sort()}.

`key' should be a single-parameter function that takes a list element and
returns a comparison key for the element.  The list is then sorted using the
comparison keys.  The following example sorts a list case-insensitively:

@example
>>> L = ['A', 'b', 'c', 'D']
>>> L.sort()                 # Case-sensitive sort
>>> L
['A', 'D', 'b', 'c']
>>> # Using 'key' parameter to sort list
>>> L.sort(key=lambda x: x.lower())
>>> L
['A', 'b', 'c', 'D']
>>> # Old-fashioned way
>>> L.sort(cmp=lambda x,y: cmp(x.lower(), y.lower()))
>>> L
['A', 'b', 'c', 'D']
@end example

The last example, which uses the `cmp' parameter, is the old way to perform a
case-insensitive sort.  It works but is slower than using a `key' parameter.
Using `key' calls @code{lower()} method once for each element in the list while
using `cmp' will call it twice for each comparison, so using `key' saves on
invocations of the @code{lower()} method.

For simple key functions and comparison functions, it is often possible to avoid
a @ref{127a,,lambda} expression by using an unbound method instead.  For example,
the above case-insensitive sort is best written as:

@example
>>> L.sort(key=str.lower)
>>> L
['A', 'b', 'c', 'D']
@end example

Finally, the `reverse' parameter takes a Boolean value.  If the value is true,
the list will be sorted into reverse order. Instead of @code{L.sort();
L.reverse()}, you can now write @code{L.sort(reverse=True)}.

The results of sorting are now guaranteed to be stable.  This means that two
entries with equal keys will be returned in the same order as they were input.
For example, you can sort a list of people by name, and then sort the list by
age, resulting in a list sorted by age where people with the same age are in
name-sorted order.

(All changes to @code{sort()} contributed by Raymond Hettinger.)

@item 
There is a new built-in function @code{sorted(iterable)} that works like the
in-place @ref{bbd,,list.sort()} method but can be used in expressions.  The
differences are:

@item 
the input may be any iterable;

@item 
a newly formed copy is sorted, leaving the original intact; and

@item 
the expression returns the new sorted copy

@example
>>> L = [9,7,8,3,2,4,1,6,5]
>>> [10+i for i in sorted(L)]       # usable in a list comprehension
[11, 12, 13, 14, 15, 16, 17, 18, 19]
>>> L                               # original is left unchanged
[9,7,8,3,2,4,1,6,5]
>>> sorted('Monty Python')          # any iterable may be an input
[' ', 'M', 'P', 'h', 'n', 'n', 'o', 'o', 't', 't', 'y', 'y']

>>> # List the contents of a dict sorted by key values
>>> colormap = dict(red=1, blue=2, green=3, black=4, yellow=5)
>>> for k, v in sorted(colormap.iteritems()):
...     print k, v
...
black 4
blue 2
green 3
red 1
yellow 5
@end example

(Contributed by Raymond Hettinger.)

@item 
Integer operations will no longer trigger an @code{OverflowWarning}. The
@code{OverflowWarning} warning will disappear in Python 2.5.

@item 
The interpreter gained a new switch, @ref{5cb,,-m}, that takes a name, searches
for the corresponding  module on @code{sys.path}, and runs the module as a script.
For example,  you can now run the Python profiler with @code{python -m profile}.
(Contributed by Nick Coghlan.)

@item 
The @code{eval(expr, globals, locals)} and @code{execfile(filename, globals,
locals)} functions and the @code{exec} statement now accept any mapping type
for the `locals' parameter.  Previously this had to be a regular Python
dictionary.  (Contributed by Raymond Hettinger.)

@item 
The @ref{7ba,,zip()} built-in function and @code{itertools.izip()} now return an
empty list if called with no arguments. Previously they raised a
@ref{522,,TypeError} exception.  This makes them more suitable for use with variable
length argument lists:

@example
>>> def transpose(array):
...    return zip(*array)
...
>>> transpose([(1,2,3), (4,5,6)])
[(1, 4), (2, 5), (3, 6)]
>>> transpose([])
[]
@end example

(Contributed by Raymond Hettinger.)

@item 
Encountering a failure while importing a module no longer leaves a partially initialized
module object in @code{sys.modules}.  The incomplete module object left
behind would fool further imports of the same module into succeeding, leading to
confusing errors.   (Fixed by Tim Peters.)

@item 
@ref{660,,None} is now a constant; code that binds a new value to  the name
@code{None} is now a syntax error. (Contributed by Raymond Hettinger.)
@end itemize

@c ======================================================================

@menu
* Optimizations: Optimizations<11>. 

@end menu

@node Optimizations<11>,,,Autres changements au langage<17>
@anchor{whatsnew/2 4 optimizations}@anchor{141a}
@subsubsection Optimizations



@itemize *

@item 
The inner loops for list and tuple slicing were optimized and now run about
one-third faster.  The inner loops for dictionaries were also optimized,
resulting in performance boosts for @code{keys()}, @code{values()}, @code{items()},
@code{iterkeys()}, @code{itervalues()}, and @code{iteritems()}. (Contributed by
Raymond Hettinger.)

@item 
The machinery for growing and shrinking lists was optimized for speed and for
space efficiency.  Appending and popping from lists now runs faster due to more
efficient code paths and less frequent use of the underlying system
@code{realloc()}.  List comprehensions also benefit.   @code{list.extend()} was
also optimized and no longer converts its argument into a temporary list before
extending the base list.  (Contributed by Raymond Hettinger.)

@item 
@ref{5fc,,list()}, @ref{366,,tuple()}, @ref{84e,,map()}, @ref{84f,,filter()}, and @ref{7ba,,zip()} now
run several times faster with non-sequence arguments that supply a
@code{__len__()} method.  (Contributed by Raymond Hettinger.)

@item 
The methods @code{list.__getitem__()}, @code{dict.__getitem__()}, and
@code{dict.__contains__()} are now implemented as @code{method_descriptor}
objects rather than @code{wrapper_descriptor} objects.  This form of  access
doubles their performance and makes them more suitable for use as arguments to
functionals: @code{map(mydict.__getitem__, keylist)}. (Contributed by Raymond
Hettinger.)

@item 
Added a new opcode, @code{LIST_APPEND}, that simplifies the generated bytecode
for list comprehensions and speeds them up by about a third.  (Contributed by
Raymond Hettinger.)

@item 
The peephole bytecode optimizer has been improved to  produce shorter, faster
bytecode; remarkably, the resulting bytecode is  more readable.  (Enhanced by
Raymond Hettinger.)

@item 
String concatenations in statements of the form @code{s = s + "abc"} and @code{s +=
"abc"} are now performed more efficiently in certain circumstances.  This
optimization won't be present in other Python implementations such as Jython, so
you shouldn't rely on it; using the @code{join()} method of strings is still
recommended when you want to efficiently glue a large number of strings
together. (Contributed by Armin Rigo.)
@end itemize

The net result of the 2.4 optimizations is that Python 2.4 runs the pystone
benchmark around 5% faster than Python 2.3 and 35% faster than Python 2.2.
(pystone is not a particularly good benchmark, but it's the most commonly used
measurement of Python's performance.  Your own applications may show greater or
smaller benefits from Python 2.4.)

@c pystone is almost useless for comparing different versions of Python;
@c instead, it excels at predicting relative Python performance on different
@c machines.  So, this section would be more informative if it used other tools
@c such as pybench and parrotbench.  For a more application oriented benchmark,
@c try comparing the timings of test_decimal.py under 2.3 and 2.4.

@c ======================================================================

@node New Improved and Deprecated Modules<3>,Build and C API Changes<11>,Autres changements au langage<17>,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 new-improved-and-deprecated-modules}@anchor{141b}
@subsection New, Improved, and Deprecated Modules


As usual, Python's standard library received a number of enhancements and bug
fixes.  Here's a partial list of the most notable changes, sorted alphabetically
by module name. Consult the @code{Misc/NEWS} file in the source tree for a more
complete list of changes, or look through the CVS logs for all the details.


@itemize *

@item 
The @code{asyncore} module's @code{loop()} function now has a `count' parameter
that lets you perform a limited number of passes through the polling loop.  The
default is still to loop forever.

@item 
The @ref{e,,base64} module now has more complete 
@geindex RFC; RFC 3548
RFC 3548@footnote{https://datatracker.ietf.org/doc/html/rfc3548.html} support for Base64,
Base32, and Base16 encoding and decoding, including optional case folding and
optional alternative alphabets. (Contributed by Barry Warsaw.)

@item 
The @ref{11,,bisect} module now has an underlying C implementation for improved
performance. (Contributed by Dmitry Vasiliev.)

@item 
The CJKCodecs collections of East Asian codecs, maintained by Hye-Shik Chang,
was integrated into 2.4.   The new encodings are:

@item 
Chinois (PRC) : `gb2312', `gbk', `gb18030', `big5hkscs', `hz'

@item 
Chinois (ROC) : `big5', `cp950'

@item 

@table @asis

@item Japonais : `cp932', `euc-jis-2004', `euc-jp', `euc-jisx0213', `iso-2022-jp',

`iso-2022-jp-1', `iso-2022-jp-2', `iso-2022-jp-3', `iso-2022-jp-ext', `iso-2022-jp-2004', `shift-jis', `shift-jisx0213', `shift-jis-2004'
@end table

@item 
Coréen : `cp949', `euc-kr', `johab', `iso-2022-kr'

@item 
D’autres encodages ont été ajoutés : HP Roman8,  ISO_8859-11, ISO_8859-16, PCTP-154, et TIS-620.

@item 
The UTF-8 and UTF-16 codecs now cope better with receiving partial input.
Previously the @code{StreamReader} class would try to read more data, making
it impossible to resume decoding from the stream.  The @code{read()} method will
now return as much data as it can and future calls will resume decoding where
previous ones left off.  (Implemented by Walter Dörwald.)

@item 
There is a new @ref{1d,,collections} module for  various specialized collection
datatypes.  Currently it contains just one type, @code{deque}, a double-ended
queue that supports efficiently adding and removing elements from either
end:

@example
>>> from collections import deque
>>> d = deque('ghi')        # make a new deque with three items
>>> d.append('j')           # add a new entry to the right side
>>> d.appendleft('f')       # add a new entry to the left side
>>> d                       # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])
>>> d.pop()                 # return and remove the rightmost item
'j'
>>> d.popleft()             # return and remove the leftmost item
'f'
>>> list(d)                 # list the contents of the deque
['g', 'h', 'i']
>>> 'h' in d                # search the deque
True
@end example

Several modules, such as the @code{Queue} and @ref{ec,,threading} modules, now take
advantage of @ref{5c6,,collections.deque} for improved performance.  (Contributed
by Raymond Hettinger.)

@item 
The @ref{22,,ConfigParser} classes have been enhanced slightly. The @ref{141c,,read()}
method now returns a list of the files that were successfully parsed, and the
@ref{124b,,set()} method raises @ref{522,,TypeError} if passed a `value' argument that
isn't a string.   (Contributed by John Belmonte and David Goodger.)

@item 
The @ref{2b,,curses} module now supports the ncurses extension
@code{use_default_colors()}.  On platforms where the terminal supports
transparency, this makes it possible to use a transparent background.
(Contributed by Jörg Lehmann.)

@item 
The @ref{37,,difflib} module now includes an @code{HtmlDiff} class that creates
an HTML table showing a side by side comparison of two versions of a text.
(Contributed by Dan Gass.)

@item 
The @ref{3b,,email} package was updated to version 3.0,  which dropped various
deprecated APIs and removes support for Python versions earlier than 2.3.  The
3.0 version of the package uses a new incremental parser for MIME messages,
available in the @code{email.FeedParser} module.  The new parser doesn't require
reading the entire message into memory, and doesn't raise exceptions if a
message is malformed; instead it records any problems in the  @code{defect}
attribute of the message.  (Developed by Anthony Baxter, Barry Warsaw, Thomas
Wouters, and others.)

@item 
The @ref{68,,heapq} module has been converted to C.  The resulting tenfold
improvement in speed makes the module suitable for handling high volumes of
data.  In addition, the module has two new functions @code{nlargest()} and
@code{nsmallest()} that use heaps to find the N largest or smallest values in a
dataset without the expense of a full sort.  (Contributed by Raymond Hettinger.)

@item 
The @ref{6d,,httplib} module now contains constants for HTTP status codes defined
in various HTTP-related RFC documents.  Constants have names such as
@code{OK}, @code{CREATED}, @code{CONTINUE}, and
@code{MOVED_PERMANENTLY}; use pydoc to get a full list.  (Contributed by
Andrew Eland.)

@item 
The @ref{73,,imaplib} module now supports IMAP's THREAD command (contributed by
Yves Dionne) and new @code{deleteacl()} and @code{myrights()} methods (contributed
by Arnaud Mazin).

@item 
The @ref{80,,itertools} module gained a @code{groupby(iterable[, *func*])}
function. `iterable' is something that can be iterated over to return a stream
of elements, and the optional `func' parameter is a function that takes an
element and returns a key value; if omitted, the key is simply the element
itself.  @code{groupby()} then groups the elements into subsequences which have
matching values of the key, and returns a series of 2-tuples containing the key
value and an iterator over the subsequence.

Here's an example to make this clearer.  The `key' function simply returns
whether a number is even or odd, so the result of @code{groupby()} is to return
consecutive runs of odd or even numbers.

@example
>>> import itertools
>>> L = [2, 4, 6, 7, 8, 9, 11, 12, 14]
>>> for key_val, it in itertools.groupby(L, lambda x: x % 2):
...    print key_val, list(it)
...
0 [2, 4, 6]
1 [7]
0 [8]
1 [9, 11]
0 [12, 14]
>>>
@end example

@code{groupby()} is typically used with sorted input.  The logic for
@code{groupby()} is similar to the Unix @code{uniq} filter which makes it handy for
eliminating, counting, or identifying duplicate elements:

@example
>>> word = 'abracadabra'
>>> letters = sorted(word)   # Turn string into a sorted list of letters
>>> letters
['a', 'a', 'a', 'a', 'a', 'b', 'b', 'c', 'd', 'r', 'r']
>>> for k, g in itertools.groupby(letters):
...    print k, list(g)
...
a ['a', 'a', 'a', 'a', 'a']
b ['b', 'b']
c ['c']
d ['d']
r ['r', 'r']
>>> # List unique letters
>>> [k for k, g in groupby(letters)]
['a', 'b', 'c', 'd', 'r']
>>> # Count letter occurrences
>>> [(k, len(list(g))) for k, g in groupby(letters)]
[('a', 5), ('b', 2), ('c', 1), ('d', 1), ('r', 2)]
@end example

(Contribution par Hye-Shik Chang.)

@item 
@ref{80,,itertools} also gained a function named @code{tee(iterator, N)} that
returns `N' independent iterators that replicate `iterator'.  If `N' is omitted,
the default is 2.

@example
>>> L = [1,2,3]
>>> i1, i2 = itertools.tee(L)
>>> i1,i2
(<itertools.tee object at 0x402c2080>, <itertools.tee object at 0x402c2090>)
>>> list(i1)               # Run the first iterator to exhaustion
[1, 2, 3]
>>> list(i2)               # Run the second iterator to exhaustion
[1, 2, 3]
@end example

Note that @code{tee()} has to keep copies of the values returned  by the
iterator; in the worst case, it may need to keep all of them.   This should
therefore be used carefully if the leading iterator can run far ahead of the
trailing iterator in a long stream of inputs. If the separation is large, then
you might as well use  @ref{5fc,,list()} instead.  When the iterators track closely
with one another, @code{tee()} is ideal.  Possible applications include
bookmarking, windowing, or lookahead iterators. (Contributed by Raymond
Hettinger.)

@item 
A number of functions were added to the @ref{85,,locale}  module, such as
@code{bind_textdomain_codeset()} to specify a particular encoding and a family of
@code{l*gettext()} functions that return messages in the chosen encoding.
(Contributed by Gustavo Niemeyer.)

@item 
Some keyword arguments were added to the @ref{86,,logging} package's
@code{basicConfig()} function to simplify log configuration.  The default
behavior is to log messages to standard error, but various keyword arguments can
be specified to log to a particular file, change the logging format, or set the
logging level. For example:

@example
import logging
logging.basicConfig(filename='/var/log/application.log',
    level=0,  # Log all messages
    format='%(levelname):%(process):%(thread):%(message)')
@end example

Other additions to the @ref{86,,logging} package include a @code{log(level, msg)}
convenience method, as well as a @code{TimedRotatingFileHandler} class that
rotates its log files at a timed interval.  The module already had
@code{RotatingFileHandler}, which rotated logs once the file exceeded a
certain size.  Both classes derive from a new @code{BaseRotatingHandler} class
that can be used to implement other rotating handlers.

(Changements implémentés par Vinay Sajip.)

@item 
The @ref{8c,,marshal} module now shares interned strings on unpacking a  data
structure.  This may shrink the size of certain pickle strings, but the primary
effect is to make @code{.pyc} files significantly smaller. (Contributed by
Martin von Löwis.)

@item 
The @code{nntplib} module's @code{NNTP} class gained @code{description()} and
@code{descriptions()} methods to retrieve  newsgroup descriptions for a single
group or for a range of groups. (Contributed by Jürgen A. Erhard.)

@item 
Two new functions were added to the @ref{9e,,operator} module,
@code{attrgetter(attr)} and @code{itemgetter(index)}. Both functions return
callables that take a single argument and return the corresponding attribute or
item; these callables make excellent data extractors when used with @ref{84e,,map()}
or @ref{bbc,,sorted()}.  For example:

@example
>>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
>>> map(operator.itemgetter(0), L)
['c', 'd', 'a', 'b']
>>> map(operator.itemgetter(1), L)
[2, 1, 4, 3]
>>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
[('d', 1), ('c', 2), ('b', 3), ('a', 4)]
@end example

(Contributed by Raymond Hettinger.)

@item 
The @ref{9f,,optparse} module was updated in various ways.  The module now passes
its messages through @ref{141d,,gettext.gettext()}, making it possible to
internationalize Optik's help and error messages.  Help messages for options can
now include the string @code{'%default'}, which will be replaced by the option's
default value.  (Contributed by Greg Ward.)

@item 
The long-term plan is to deprecate the @code{rfc822} module in some future
Python release in favor of the @ref{3b,,email} package. To this end, the
@ref{141e,,email.Utils.formatdate} function has been changed to make it usable as a
replacement for @code{rfc822.formatdate()}.  You may want to write new e-mail
processing code with this in mind.  (Change implemented by Anthony Baxter.)

@item 
A new @code{urandom(n)} function was added to the @ref{a0,,os} module, returning
a string containing `n' bytes of random data.  This function provides access to
platform-specific sources of randomness such as @code{/dev/urandom} on Linux or
the Windows CryptoAPI.  (Contributed by Trevor Perrin.)

@item 
Another new function: @code{os.path.lexists(path)}  returns true if the file
specified by `path' exists, whether or not it's a symbolic link.  This differs
from the existing @code{os.path.exists(path)} function, which returns false if
`path' is a symlink that points to a destination that doesn't exist.
(Contributed by Beni Cherniavsky.)

@item 
A new @code{getsid()} function was added to the @ref{ac,,posix} module that
underlies the @ref{a0,,os} module. (Contributed by J. Raynor.)

@item 
Le module @ref{ab,,poplib} supporte maintenant POP sur SSL.  (Contribution par Hector Urtubia.)

@item 
The @ref{ae,,profile} module can now profile C extension functions. (Contributed
by Nick Bastin.)

@item 
The @ref{b7,,random} module has a new method called @code{getrandbits(N)} that
returns a long integer `N' bits in length.  The existing @code{randrange()}
method now uses @code{getrandbits()} where appropriate, making generation of
arbitrarily large random numbers more efficient.  (Contributed by Raymond
Hettinger.)

@item 
The regular expression language accepted by the @ref{b8,,re} module was extended
with simple conditional expressions, written as @code{(?(group)A|B)}.  `group' is
either a numeric group ID or a group name defined with @code{(?P<group>...)}
earlier in the expression.  If the specified group matched, the regular
expression pattern `A' will be tested against the string; if the group didn't
match, the pattern `B' will be used instead. (Contributed by Gustavo Niemeyer.)

@item 
The @ref{b8,,re} module is also no longer recursive, thanks to a massive amount
of work by Gustavo Niemeyer.  In a recursive regular expression engine, certain
patterns result in a large amount of C stack space being consumed, and it was
possible to overflow the stack. For example, if you matched a 30000-byte string
of @code{a} characters against the expression @code{(a|b)+}, one stack frame was
consumed per character.  Python 2.3 tried to check for stack overflow and raise
a @ref{193,,RuntimeError} exception, but certain patterns could sidestep the
checking and if you were unlucky Python could segfault. Python 2.4's regular
expression engine can match this pattern without problems.

@item 
The @ref{c5,,signal} module now performs tighter error-checking on the parameters
to the @ref{1114,,signal.signal()} function.  For example, you can't set a handler on
the @code{SIGKILL} signal; previous versions of Python would quietly accept
this, but 2.4 will raise a @ref{193,,RuntimeError} exception.

@item 
Two new functions were added to the @ref{cb,,socket} module. @code{socketpair()}
returns a pair of connected sockets and @code{getservbyport(port)} looks up the
service name for a given port number. (Contributed by Dave Cole and Barry
Warsaw.)

@item 
The @code{sys.exitfunc()} function has been deprecated.  Code should be using
the existing @ref{c,,atexit} module, which correctly handles calling multiple exit
functions.  Eventually @code{sys.exitfunc()} will become a purely internal
interface, accessed only by @ref{c,,atexit}.

@item 
The @ref{dd,,tarfile} module now generates GNU-format tar files by default.
(Contributed by Lars Gustäbel.)

@item 
The @ref{ec,,threading} module now has an elegantly simple way to support
thread-local data.  The module contains a @code{local} class whose attribute
values are local to different threads.

@example
import threading

data = threading.local()
data.number = 42
data.url = ('www.python.org', 80)
@end example

Other threads can assign and retrieve their own values for the @code{number}
and @code{url} attributes.  You can subclass @code{local} to initialize
attributes or to add methods. (Contributed by Jim Fulton.)

@item 
The @ref{ee,,timeit} module now automatically disables periodic garbage
collection during the timing loop.  This change makes consecutive timings more
comparable.  (Contributed by Raymond Hettinger.)

@item 
The @ref{113,,weakref} module now supports a wider variety of objects including
Python functions, class instances, sets, frozensets, deques, arrays, files,
sockets, and regular expression pattern objects. (Contributed by Raymond
Hettinger.)

@item 
The @ref{12d,,xmlrpclib} module now supports a multi-call extension for
transmitting multiple XML-RPC calls in a single HTTP operation. (Contributed by
Brian Quinlan.)

@item 
The @code{mpz}, @code{rotor}, and @code{xreadlines} modules have  been
removed.
@end itemize

@c ======================================================================

@c whole new modules get described in subsections here

@c =====================

@menu
* cookielib:: 
* doctest: doctest<5>. 

@end menu

@node cookielib,doctest<5>,,New Improved and Deprecated Modules<3>
@anchor{whatsnew/2 4 cookielib}@anchor{141f}
@subsubsection cookielib


The @ref{6f,,cookielib} library supports client-side handling for HTTP cookies,
mirroring the @ref{70,,Cookie} module's server-side cookie support. Cookies are
stored in cookie jars; the library transparently stores cookies offered by the
web server in the cookie jar, and fetches the cookie from the jar when
connecting to the server. As in web browsers, policy objects control whether
cookies are accepted or not.

In order to store cookies across sessions, two implementations of cookie jars
are provided: one that stores cookies in the Netscape format so applications can
use the Mozilla or Lynx cookie files, and one that stores cookies in the same
format as the Perl libwww library.

@ref{10a,,urllib2} has been changed to interact with @ref{6f,,cookielib}:
@code{HTTPCookieProcessor} manages a cookie jar that is used when accessing
URLs.

This module was contributed by John J. Lee.

@c ==================

@node doctest<5>,,cookielib,New Improved and Deprecated Modules<3>
@anchor{whatsnew/2 4 doctest}@anchor{1420}
@subsubsection doctest


The @ref{3a,,doctest} module underwent considerable refactoring thanks to Edward
Loper and Tim Peters.  Testing can still be as simple as running
@ref{1421,,doctest.testmod()}, but the refactorings allow customizing the module's
operation in various ways

The new @code{DocTestFinder} class extracts the tests from a given  object's
docstrings:

@example
def f (x, y):
    """>>> f(2,2)
4
>>> f(3,2)
6
    """
    return x*y

finder = doctest.DocTestFinder()

# Get list of DocTest instances
tests = finder.find(f)
@end example

The new @code{DocTestRunner} class then runs individual tests and can produce
a summary of the results:

@example
runner = doctest.DocTestRunner()
for t in tests:
    tried, failed = runner.run(t)

runner.summarize(verbose=1)
@end example

The above example produces the following output:

@example
1 items passed all tests:
   2 tests in f
2 tests in 1 items.
2 passed and 0 failed.
Test passed.
@end example

@code{DocTestRunner} uses an instance of the @code{OutputChecker} class to
compare the expected output with the actual output.  This class takes a number
of different flags that customize its behaviour; ambitious users can also write
a completely new subclass of @code{OutputChecker}.

The default output checker provides a number of handy features. For example,
with the @ref{1422,,doctest.ELLIPSIS} option flag, an ellipsis (@code{...}) in the
expected output matches any substring,  making it easier to accommodate outputs
that vary in minor ways:

@example
def o (n):
    """>>> o(1)
<__main__.C instance at 0x...>
>>>
"""
@end example

Another special string, @code{<BLANKLINE>}, matches a blank line:

@example
def p (n):
    """>>> p(1)
<BLANKLINE>
>>>
"""
@end example

Another new capability is producing a diff-style display of the output by
specifying the @ref{1423,,doctest.REPORT_UDIFF} (unified diffs),
@ref{1424,,doctest.REPORT_CDIFF} (context diffs), or @ref{1425,,doctest.REPORT_NDIFF}
(delta-style) option flags.  For example:

@example
def g (n):
    """>>> g(4)
here
is
a
lengthy
>>>"""
    L = 'here is a rather lengthy list of words'.split()
    for word in L[:n]:
        print word
@end example

Running the above function's tests with @ref{1423,,doctest.REPORT_UDIFF} specified,
you get the following output:

@example
**********************************************************************
File "t.py", line 15, in g
Failed example:
    g(4)
Differences (unified diff with -expected +actual):
    @@@@ -2,3 +2,3 @@@@
     is
     a
    -lengthy
    +rather
**********************************************************************
@end example

@c ======================================================================

@node Build and C API Changes<11>,Portage vers Python 2 4,New Improved and Deprecated Modules<3>,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 build-and-c-api-changes}@anchor{1426}
@subsection Build and C API Changes


Some of the changes to Python's build process and to the C API are:


@itemize *

@item 
Three new convenience macros were added for common return values from
extension functions: @ref{1427,,Py_RETURN_NONE}, @ref{1428,,Py_RETURN_TRUE}, and
@ref{1429,,Py_RETURN_FALSE}. (Contributed by Brett Cannon.)

@item 
Another new macro, @ref{564,,Py_CLEAR},  decreases the reference count of
`obj' and sets `obj' to the null pointer.  (Contributed by Jim Fulton.)

@item 
A new function, @code{PyTuple_Pack(N, obj1, obj2, ..., objN)}, constructs
tuples from a variable length argument list of Python objects.  (Contributed by
Raymond Hettinger.)

@item 
A new function, @code{PyDict_Contains(d, k)}, implements fast dictionary
lookups without masking exceptions raised during the look-up process.
(Contributed by Raymond Hettinger.)

@item 
The Py_IS_NAN(X) macro returns 1 if  its float or double argument
`X' is a NaN.   (Contributed by Tim Peters.)

@item 
C code can avoid unnecessary locking by using the new
@code{PyEval_ThreadsInitialized()} function to tell  if any thread operations
have been performed.  If this function  returns false, no lock operations are
needed. (Contributed by Nick Coghlan.)

@item 
A new function, @ref{37a,,PyArg_VaParseTupleAndKeywords()}, is the same as
@ref{379,,PyArg_ParseTupleAndKeywords()} but takes a  @code{va_list} instead of a
number of arguments. (Contributed by Greg Chapman.)

@item 
A new method flag, @ref{142a,,METH_COEXIST}, allows a function defined in slots
to co-exist with a @ref{142b,,PyCFunction} having the same name.  This can halve
the access time for a method such as @code{set.__contains__()}.  (Contributed by
Raymond Hettinger.)

@item 
Python can now be built with additional profiling for the interpreter itself,
intended as an aid to people developing the Python core.  Providing
@code{--enable-profiling} to the @code{configure} script will let you
profile the interpreter with @code{gprof}, and providing the
@code{--with-tsc} switch enables profiling using the Pentium's
Time-Stamp-Counter register.  Note that the @code{--with-tsc} switch is slightly
misnamed, because the profiling feature also works on the PowerPC platform,
though that processor architecture doesn't call that register "the TSC
register".  (Contributed by Jeremy Hylton.)

@item 
The @code{tracebackobject} type has been renamed to
@code{PyTracebackObject}.
@end itemize

@c ======================================================================

@menu
* Port-Specific Changes: Port-Specific Changes<2>. 

@end menu

@node Port-Specific Changes<2>,,,Build and C API Changes<11>
@anchor{whatsnew/2 4 port-specific-changes}@anchor{142c}
@subsubsection Port-Specific Changes



@itemize *

@item 
The Windows port now builds under MSVC++ 7.1 as well as version 6.
(Contributed by Martin von Löwis.)
@end itemize

@c ======================================================================

@node Portage vers Python 2 4,Remerciements<4>,Build and C API Changes<11>,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 porting-to-python-2-4}@anchor{142d}
@subsection Portage vers Python 2.4


This section lists previously described changes that may require changes to your
code:


@itemize *

@item 
Left shifts and hexadecimal/octal constants that are too  large no longer
trigger a @ref{40b,,FutureWarning} and return  a value limited to 32 or 64 bits;
instead they return a long integer.

@item 
Integer operations will no longer trigger an @code{OverflowWarning}. The
@code{OverflowWarning} warning will disappear in Python 2.5.

@item 
The @ref{7ba,,zip()} built-in function and @code{itertools.izip()} now return  an
empty list instead of raising a @ref{522,,TypeError} exception if called with no
arguments.

@item 
You can no longer compare the @code{date} and @ref{1c7,,datetime} instances
provided by the @ref{30,,datetime} module.  Two  instances of different classes
will now always be unequal, and  relative comparisons (@code{<}, @code{>}) will raise
a @ref{522,,TypeError}.

@item 
@code{dircache.listdir()} now passes exceptions to the caller instead of
returning empty lists.

@item 
@code{LexicalHandler.startDTD()} used to receive the public and system IDs in
the wrong order.  This has been corrected; applications relying on the wrong
order need to be fixed.

@item 
@ref{142e,,fcntl.ioctl()} now warns if the `mutate'  argument is omitted and
relevant.

@item 
The @ref{dd,,tarfile} module now generates GNU-format tar files by default.

@item 
Encountering a failure while importing a module no longer leaves a
partially initialized module object in @code{sys.modules}.

@item 
@ref{660,,None} is now a constant; code that binds a new value to  the name
@code{None} is now a syntax error.

@item 
The @code{signals.signal()} function now raises a @ref{193,,RuntimeError} exception
for certain illegal values; previously these errors would pass silently.  For
example, you can no longer set a handler on the @code{SIGKILL} signal.
@end itemize

@c ======================================================================

@node Remerciements<4>,,Portage vers Python 2 4,Nouveautés de Python 2 4
@anchor{whatsnew/2 4 acknowledgements}@anchor{142f}@anchor{whatsnew/2 4 acks}@anchor{1430}
@subsection Remerciements


The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Koray Can,
Hye-Shik Chang, Michael Dyck, Raymond Hettinger, Brian Hurt, Hamish Lawson,
Fredrik Lundh, Sean Reifschneider, Sadruddin Rejeb.

@node Nouveautés de Python 2 3,Nouveautés de Python 2 2,Nouveautés de Python 2 4,Nouveautés de Python
@anchor{whatsnew/2 3 doc}@anchor{1431}@anchor{whatsnew/2 3 what-s-new-in-python-2-3}@anchor{1432}
@section Nouveautés de Python 2.3


@*Auteur: 
A.M. Kuchling


@c $Id: whatsnew23.tex 54631 2007-03-31 11:58:36Z georg.brandl $

This article explains the new features in Python 2.3.  Python 2.3 was released
on July 29, 2003.

The main themes for Python 2.3 are polishing some of the features added in 2.2,
adding various small but useful enhancements to the core language, and expanding
the standard library.  The new object model introduced in the previous version
has benefited from 18 months of bugfixes and from optimization efforts that have
improved the performance of new-style classes.  A few new built-in functions
have been added such as @ref{454,,sum()} and @ref{1433,,enumerate()}.  The @ref{2e8,,in}
operator can now be used for substring searches (e.g. @code{"ab" in "abc"} returns
@ref{bfb,,True}).

Some of the many new library features include Boolean, set, heap, and date/time
data types, the ability to import modules from ZIP-format archives, metadata
support for the long-awaited Python catalog, an updated version of IDLE, and
modules for logging messages, wrapping text, parsing CSV files, processing
command-line options, using BerkeleyDB databases...  the list of new and
enhanced modules is lengthy.

This article doesn't attempt to provide a complete specification of the new
features, but instead provides a convenient overview.  For full details, you
should refer to the documentation for Python 2.3, such as the Python Library
Reference and the Python Reference Manual.  If you want to understand the
complete implementation and design rationale, refer to the PEP for a particular
new feature.

@c ======================================================================

@menu
* PEP 218; A Standard Set Datatype: PEP 218 A Standard Set Datatype. 
* PEP 255 ; Générateurs simples: PEP 255 Générateurs simples. 
* PEP 263; Source Code Encodings: PEP 263 Source Code Encodings. 
* PEP 273; Importing Modules from ZIP Archives: PEP 273 Importing Modules from ZIP Archives. 
* PEP 277; Unicode file name support for Windows NT: PEP 277 Unicode file name support for Windows NT. 
* PEP 278; Universal Newline Support: PEP 278 Universal Newline Support. 
* PEP 279; enumerate(): PEP 279 enumerate. 
* PEP 282; The logging Package: PEP 282 The logging Package. 
* PEP 285 ; Un type booléen: PEP 285 Un type booléen. 
* PEP 293; Codec Error Handling Callbacks: PEP 293 Codec Error Handling Callbacks. 
* PEP 301; Package Index and Metadata for Distutils: PEP 301 Package Index and Metadata for Distutils. 
* PEP 302; New Import Hooks: PEP 302 New Import Hooks. 
* PEP 305; Comma-separated Files: PEP 305 Comma-separated Files. 
* PEP 307; Pickle Enhancements: PEP 307 Pickle Enhancements. 
* Extended Slices:: 
* Autres changements au langage: Autres changements au langage<18>. 
* New@comma{} Improved@comma{} and Deprecated Modules: New Improved and Deprecated Modules<4>. 
* Pymalloc; A Specialized Object Allocator: Pymalloc A Specialized Object Allocator. 
* Build and C API Changes: Build and C API Changes<12>. 
* Autres changements et corrections: Autres changements et corrections<2>. 
* Portage vers Python 2.3: Portage vers Python 2 3. 
* Remerciements: Remerciements<5>. 

@end menu

@node PEP 218 A Standard Set Datatype,PEP 255 Générateurs simples,,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-218-a-standard-set-datatype}@anchor{1434}
@subsection PEP 218: A Standard Set Datatype


The new @code{sets} module contains an implementation of a set datatype.  The
@code{Set} class is for mutable sets, sets that can have members added and
removed.  The @code{ImmutableSet} class is for sets that can't be modified,
and instances of @code{ImmutableSet} can therefore be used as dictionary keys.
Sets are built on top of dictionaries, so the elements within a set must be
hashable.

Here's a simple example:

@example
>>> import sets
>>> S = sets.Set([1,2,3])
>>> S
Set([1, 2, 3])
>>> 1 in S
True
>>> 0 in S
False
>>> S.add(5)
>>> S.remove(3)
>>> S
Set([1, 2, 5])
>>>
@end example

The union and intersection of sets can be computed with the @ref{1435,,union()} and
@ref{1436,,intersection()} methods; an alternative notation uses the bitwise operators
@code{&} and @code{|}. Mutable sets also have in-place versions of these methods,
@code{union_update()} and @ref{1437,,intersection_update()}.

@example
>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([4,5,6])
>>> S1.union(S2)
Set([1, 2, 3, 4, 5, 6])
>>> S1 | S2                  # Alternative notation
Set([1, 2, 3, 4, 5, 6])
>>> S1.intersection(S2)
Set([])
>>> S1 & S2                  # Alternative notation
Set([])
>>> S1.union_update(S2)
>>> S1
Set([1, 2, 3, 4, 5, 6])
>>>
@end example

It's also possible to take the symmetric difference of two sets.  This is the
set of all elements in the union that aren't in the intersection.  Another way
of putting it is that the symmetric difference contains all elements that are in
exactly one set.  Again, there's an alternative notation (@code{^}), and an
in-place version with the ungainly name @ref{1438,,symmetric_difference_update()}.

@example
>>> S1 = sets.Set([1,2,3,4])
>>> S2 = sets.Set([3,4,5,6])
>>> S1.symmetric_difference(S2)
Set([1, 2, 5, 6])
>>> S1 ^ S2
Set([1, 2, 5, 6])
>>>
@end example

There are also @code{issubset()} and @code{issuperset()} methods for checking
whether one set is a subset or superset of another:

@example
>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([2,3])
>>> S2.issubset(S1)
True
>>> S1.issubset(S2)
False
>>> S1.issuperset(S2)
True
>>>
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 218

@item PEP 218@footnote{https://peps.python.org/pep-0218/} - Adding a Built-In Set Object Type

PEP written by Greg V. Wilson. Implemented by Greg V. Wilson, Alex Martelli, and
GvR.
@end table


@c ======================================================================

@node PEP 255 Générateurs simples,PEP 263 Source Code Encodings,PEP 218 A Standard Set Datatype,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-255-simple-generators}@anchor{1439}@anchor{whatsnew/2 3 section-generators}@anchor{143a}
@subsection PEP 255 : Générateurs simples


In Python 2.2, generators were added as an optional feature, to be enabled by a
@code{from __future__ import generators} directive.  In 2.3 generators no longer
need to be specially enabled, and are now always present; this means that
@ref{9bb,,yield} is now always a keyword.  The rest of this section is a copy of
the description of generators from the "What's New in Python 2.2" document; if
you read it back when Python 2.2 came out, you can skip the rest of this
section.

You're doubtless familiar with how function calls work in Python or C. When you
call a function, it gets a private namespace where its local variables are
created.  When the function reaches a @ref{9bc,,return} statement, the local
variables are destroyed and the resulting value is returned to the caller.  A
later call to the same function will get a fresh new set of local variables.
But, what if the local variables weren't thrown away on exiting a function?
What if you could later resume the function where it left off?  This is what
generators provide; they can be thought of as resumable functions.

Here's the simplest example of a generator function:

@example
def generate_ints(N):
    for i in range(N):
        yield i
@end example

A new keyword, @ref{9bb,,yield}, was introduced for generators.  Any function
containing a @code{yield} statement is a generator function; this is
detected by Python's bytecode compiler which compiles the function specially as
a result.

When you call a generator function, it doesn't return a single value; instead it
returns a generator object that supports the iterator protocol.  On executing
the @ref{9bb,,yield} statement, the generator outputs the value of @code{i},
similar to a @ref{9bc,,return} statement.  The big difference between
@code{yield} and a @code{return} statement is that on reaching a
@code{yield} the generator's state of execution is suspended and local
variables are preserved.  On the next call to the generator's @code{.next()}
method, the function will resume executing immediately after the
@code{yield} statement.  (For complicated reasons, the @code{yield}
statement isn't allowed inside the @ref{6d3,,try} block of a
@code{try}...@code{finally} statement; read 
@geindex Python Enhancement Proposals; PEP 255
PEP 255@footnote{https://peps.python.org/pep-0255/} for a full
explanation of the interaction between @code{yield} and exceptions.)

Here's a sample usage of the @code{generate_ints()} generator:

@example
>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
  File "stdin", line 1, in ?
  File "stdin", line 2, in generate_ints
StopIteration
@end example

You could equally write @code{for i in generate_ints(5)}, or @code{a,b,c =
generate_ints(3)}.

Inside a generator function, the @ref{9bc,,return} statement can only be used
without a value, and signals the end of the procession of values; afterwards the
generator cannot return any further values. @code{return} with a value, such
as @code{return 5}, is a syntax error inside a generator function.  The end of the
generator's results can also be indicated by raising @ref{be8,,StopIteration}
manually, or by just letting the flow of execution fall off the bottom of the
function.

You could achieve the effect of generators manually by writing your own class
and storing all the local variables of the generator as instance variables.  For
example, returning a list of integers could be done by setting @code{self.count} to
0, and having the @ref{7c2,,next()} method increment @code{self.count} and return it.
However, for a moderately complicated generator, writing a corresponding class
would be much messier. @code{Lib/test/test_generators.py} contains a number of
more interesting examples.  The simplest one implements an in-order traversal of
a tree using generators recursively.

@example
# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x
        yield t.label
        for x in inorder(t.right):
            yield x
@end example

Two other examples in @code{Lib/test/test_generators.py} produce solutions for
the N-Queens problem (placing $N$ queens on an $NxN$ chess board so that no
queen threatens another) and the Knight's Tour (a route that takes a knight to
every square of an $NxN$ chessboard without visiting any square twice).

The idea of generators comes from other programming languages, especially Icon
(@indicateurl{https://www2.cs.arizona.edu/icon/}), where the idea of generators is central.  In
Icon, every expression and function call behaves like a generator.  One example
from "An Overview of the Icon Programming Language" at
@indicateurl{https://www2.cs.arizona.edu/icon/docs/ipd266.htm} gives an idea of what this looks
like:

@example
sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)
@end example

In Icon the @code{find()} function returns the indexes at which the substring
"or" is found: 3, 23, 33.  In the @ref{2e7,,if} statement, @code{i} is first
assigned a value of 3, but 3 is less than 5, so the comparison fails, and Icon
retries it with the second value of 23.  23 is greater than 5, so the comparison
now succeeds, and the code prints the value 23 to the screen.

Python doesn't go nearly as far as Icon in adopting generators as a central
concept.  Generators are considered part of the core Python language, but
learning or using them isn't compulsory; if they don't solve any problems that
you have, feel free to ignore them. One novel feature of Python's interface as
compared to Icon's is that a generator's state is represented as a concrete
object (the iterator) that can be passed around to other functions or stored in
a data structure.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 255

@item PEP 255@footnote{https://peps.python.org/pep-0255/}: Générateurs simples

Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland.  Implemented mostly
by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew.
@end table


@c ======================================================================

@node PEP 263 Source Code Encodings,PEP 273 Importing Modules from ZIP Archives,PEP 255 Générateurs simples,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-263-source-code-encodings}@anchor{143b}@anchor{whatsnew/2 3 section-encodings}@anchor{143c}
@subsection PEP 263: Source Code Encodings


Python source files can now be declared as being in different character set
encodings.  Encodings are declared by including a specially formatted comment in
the first or second line of the source file.  For example, a UTF-8 file can be
declared with:

@example
#!/usr/bin/env python
# -*- coding: UTF-8 -*-
@end example

Without such an encoding declaration, the default encoding used is 7-bit ASCII.
Executing or importing modules that contain string literals with 8-bit
characters and have no encoding declaration will result in a
@ref{1a3,,DeprecationWarning} being signalled by Python 2.3; in 2.4 this will be a
syntax error.

The encoding declaration only affects Unicode string literals, which will be
converted to Unicode using the specified encoding.  Note that Python identifiers
are still restricted to ASCII characters, so you can't have variable names that
use characters outside of the usual alphanumerics.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 263

@item PEP 263@footnote{https://peps.python.org/pep-0263/} - Defining Python Source Code Encodings

Written by Marc-André Lemburg and Martin von Löwis; implemented by Suzuki Hisao
and Martin von Löwis.
@end table


@c ======================================================================

@node PEP 273 Importing Modules from ZIP Archives,PEP 277 Unicode file name support for Windows NT,PEP 263 Source Code Encodings,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-273-importing-modules-from-zip-archives}@anchor{143d}
@subsection PEP 273: Importing Modules from ZIP Archives


The new @ref{131,,zipimport} module adds support for importing modules from a
ZIP-format archive.  You don't need to import the module explicitly; it will be
automatically imported if a ZIP archive's filename is added to @code{sys.path}.
For example:

@example
amk@@nyman:~/src/python$ unzip -l /tmp/example.zip
Archive:  /tmp/example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
amk@@nyman:~/src/python$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'/tmp/example.zip/jwzthreading.py'
>>>
@end example

An entry in @code{sys.path} can now be the filename of a ZIP archive. The ZIP
archive can contain any kind of files, but only files named @code{*.py},
@code{*.pyc}, or @code{*.pyo} can be imported.  If an archive only contains
@code{*.py} files, Python will not attempt to modify the archive by adding the
corresponding @code{*.pyc} file, meaning that if a ZIP archive doesn't contain
@code{*.pyc} files, importing may be rather slow.

A path within the archive can also be specified to only import from a
subdirectory; for example, the path @code{/tmp/example.zip/lib/} would only
import from the @code{lib/} subdirectory within the archive.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 273

@item PEP 273@footnote{https://peps.python.org/pep-0273/} - Import Modules from Zip Archives

Written by James C. Ahlstrom,  who also provided an implementation. Python 2.3
follows the specification in 
@geindex Python Enhancement Proposals; PEP 273
PEP 273@footnote{https://peps.python.org/pep-0273/},  but uses an implementation written by
Just van Rossum  that uses the import hooks described in 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}. See section
@ref{143e,,PEP 302; New Import Hooks} for a description of the new import hooks.
@end table


@c ======================================================================

@node PEP 277 Unicode file name support for Windows NT,PEP 278 Universal Newline Support,PEP 273 Importing Modules from ZIP Archives,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-277-unicode-file-name-support-for-windows-nt}@anchor{143f}
@subsection PEP 277: Unicode file name support for Windows NT


On Windows NT, 2000, and XP, the system stores file names as Unicode strings.
Traditionally, Python has represented file names as byte strings, which is
inadequate because it renders some file names inaccessible.

Python now allows using arbitrary Unicode strings (within the limitations of the
file system) for all functions that expect file names, most notably the
@ref{505,,open()} built-in function. If a Unicode string is passed to
@ref{10da,,os.listdir()}, Python now returns a list of Unicode strings.  A new
function, @code{os.getcwdu()}, returns the current directory as a Unicode string.

Byte strings still work as file names, and on Windows Python will transparently
convert them to Unicode using the @code{mbcs} encoding.

Other systems also allow Unicode strings as file names but convert them to byte
strings before passing them to the system, which can cause a @ref{1281,,UnicodeError}
to be raised. Applications can test whether arbitrary Unicode strings are
supported as file names by checking @ref{1440,,os.path.supports_unicode_filenames},
a Boolean value.

Under MacOS, @ref{10da,,os.listdir()} may now return Unicode filenames.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 277

@item PEP 277@footnote{https://peps.python.org/pep-0277/} - Unicode file name support for Windows NT

Written by Neil Hodgson; implemented by Neil Hodgson, Martin von Löwis, and Mark
Hammond.
@end table


@c ======================================================================

@geindex universal newlines;What's new

@node PEP 278 Universal Newline Support,PEP 279 enumerate,PEP 277 Unicode file name support for Windows NT,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-278-universal-newline-support}@anchor{1441}
@subsection PEP 278: Universal Newline Support


The three major operating systems used today are Microsoft Windows, Apple's
Macintosh OS, and the various Unix derivatives.  A minor irritation of
cross-platform work  is that these three platforms all use different characters to
mark the ends of lines in text files.  Unix uses the linefeed (ASCII character
10), MacOS uses the carriage return (ASCII character 13), and Windows uses a
two-character sequence of a carriage return plus a newline.

Python's file objects can now support end of line conventions other than the
one followed by the platform on which Python is running. Opening a file with
the mode @code{'U'} or @code{'rU'} will open a file for reading in @ref{d28,,universal newlines} mode.  All three line ending conventions will be translated to a
@code{'\n'} in the strings returned by the various file methods such as
@code{read()} and @code{readline()}.

Universal newline support is also used when importing modules and when executing
a file with the @code{execfile()} function.  This means that Python modules can
be shared between all three operating systems without needing to convert the
line-endings.

This feature can be disabled when compiling Python by specifying the
@code{--without-universal-newlines} switch when running Python's
@code{configure} script.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 278

@item PEP 278@footnote{https://peps.python.org/pep-0278/} - Universal Newline Support

Written and implemented by Jack Jansen.
@end table


@c ======================================================================

@node PEP 279 enumerate,PEP 282 The logging Package,PEP 278 Universal Newline Support,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-279-enumerate}@anchor{1442}@anchor{whatsnew/2 3 section-enumerate}@anchor{1443}
@subsection PEP 279: enumerate()


A new built-in function, @ref{1433,,enumerate()}, will make certain loops a bit
clearer.  @code{enumerate(thing)}, where `thing' is either an iterator or a
sequence, returns an iterator that will return @code{(0, thing[0])}, @code{(1,
thing[1])}, @code{(2, thing[2])}, and so forth.

A common idiom to change every element of a list looks like this:

@example
for i in range(len(L)):
    item = L[i]
    # ... compute some result based on item ...
    L[i] = result
@end example

This can be rewritten using @ref{1433,,enumerate()} as:

@example
for i, item in enumerate(L):
    # ... compute some result based on item ...
    L[i] = result
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 279

@item PEP 279@footnote{https://peps.python.org/pep-0279/} - The enumerate() built-in function

Written and implemented by Raymond D. Hettinger.
@end table


@c ======================================================================

@node PEP 282 The logging Package,PEP 285 Un type booléen,PEP 279 enumerate,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-282-the-logging-package}@anchor{1444}
@subsection PEP 282: The logging Package


A standard package for writing logs, @ref{86,,logging}, has been added to Python
2.3.  It provides a powerful and flexible mechanism for generating logging
output which can then be filtered and processed in various ways.  A
configuration file written in a standard format can be used to control the
logging behavior of a program.  Python includes handlers that will write log
records to standard error or to a file or socket, send them to the system log,
or even e-mail them to a particular address; of course, it's also possible to
write your own handler classes.

The @ref{b3d,,Logger} class is the primary class. Most application code will deal
with one or more @ref{b3d,,Logger} objects, each one used by a particular
subsystem of the application. Each @ref{b3d,,Logger} is identified by a name, and
names are organized into a hierarchy using @code{.}  as the component separator.
For example, you might have @ref{b3d,,Logger} instances named @code{server},
@code{server.auth} and @code{server.network}.  The latter two instances are below
@code{server} in the hierarchy.  This means that if you turn up the verbosity for
@code{server} or direct @code{server} messages to a different handler, the changes
will also apply to records logged to @code{server.auth} and @code{server.network}.
There's also a root @ref{b3d,,Logger} that's the parent of all other loggers.

For simple uses, the @ref{86,,logging} package contains some convenience functions
that always use the root log:

@example
import logging

logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')
@end example

Ceci produit l’affichage suivant :

@example
WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down
@end example

In the default configuration, informational and debugging messages are
suppressed and the output is sent to standard error.  You can enable the display
of informational and debugging messages by calling the @ref{1445,,setLevel()} method
on the root logger.

Notice the @ref{2f3,,warning()} call's use of string formatting operators; all of the
functions for logging messages take the arguments @code{(msg, arg1, arg2, ...)} and
log the string resulting from @code{msg % (arg1, arg2, ...)}.

There's also an @ref{1446,,exception()} function that records the most recent
traceback.  Any of the other functions will also record the traceback if you
specify a true value for the keyword argument `exc_info'.

@example
def f():
    try:    1/0
    except: logging.exception('Problem recorded')

f()
@end example

Ceci produit l’affichage suivant :

@example
ERROR:root:Problem recorded
Traceback (most recent call last):
  File "t.py", line 6, in f
    1/0
ZeroDivisionError: integer division or modulo by zero
@end example

Slightly more advanced programs will use a logger other than the root logger.
The @code{getLogger(name)} function is used to get a particular log, creating
it if it doesn't exist yet. @code{getLogger(None)} returns the root logger.

@example
log = logging.getLogger('server')
 ...
log.info('Listening on port %i', port)
 ...
log.critical('Disk full')
 ...
@end example

Log records are usually propagated up the hierarchy, so a message logged to
@code{server.auth} is also seen by @code{server} and @code{root}, but a @ref{b3d,,Logger}
can prevent this by setting its @ref{1447,,propagate} attribute to @ref{b25,,False}.

There are more classes provided by the @ref{86,,logging} package that can be
customized.  When a @ref{b3d,,Logger} instance is told to log a message, it
creates a @ref{fd1,,LogRecord} instance that is sent to any number of different
@ref{1448,,Handler} instances.  Loggers and handlers can also have an attached list
of filters, and each filter can cause the @ref{fd1,,LogRecord} to be ignored or
can modify the record before passing it along.  When they're finally output,
@ref{fd1,,LogRecord} instances are converted to text by a @ref{1449,,Formatter}
class.  All of these classes can be replaced by your own specially written
classes.

With all of these features the @ref{86,,logging} package should provide enough
flexibility for even the most complicated applications.  This is only an
incomplete overview of its features, so please see the package's reference
documentation for all of the details.  Reading 
@geindex Python Enhancement Proposals; PEP 282
PEP 282@footnote{https://peps.python.org/pep-0282/} will also be helpful.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 282

@item PEP 282@footnote{https://peps.python.org/pep-0282/} - A Logging System

Written by Vinay Sajip and Trent Mick; implemented by Vinay Sajip.
@end table


@c ======================================================================

@node PEP 285 Un type booléen,PEP 293 Codec Error Handling Callbacks,PEP 282 The logging Package,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-285-a-boolean-type}@anchor{144a}@anchor{whatsnew/2 3 section-bool}@anchor{144b}
@subsection PEP 285 : Un type booléen


A Boolean type was added to Python 2.3.  Two new constants were added to the
@code{__builtin__} module, @ref{bfb,,True} and @ref{b25,,False}.  (@ref{bfb,,True} and
@ref{b25,,False} constants were added to the built-ins in Python 2.2.1, but the
2.2.1 versions are simply set to integer values of 1 and 0 and aren't a
different type.)

The type object for this new type is named @ref{451,,bool}; the constructor for it
takes any Python value and converts it to @ref{bfb,,True} or @ref{b25,,False}.

@example
>>> bool(1)
True
>>> bool(0)
False
>>> bool([])
False
>>> bool( (1,) )
True
@end example

Most of the standard library modules and built-in functions have been changed to
return Booleans.

@example
>>> obj = []
>>> hasattr(obj, 'append')
True
>>> isinstance(obj, list)
True
>>> isinstance(obj, tuple)
False
@end example

Python's Booleans were added with the primary goal of making code clearer.  For
example, if you're reading a function and encounter the statement @code{return 1},
you might wonder whether the @code{1} represents a Boolean truth value, an index,
or a coefficient that multiplies some other quantity.  If the statement is
@code{return True}, however, the meaning of the return value is quite clear.

Python's Booleans were `not' added for the sake of strict type-checking.  A very
strict language such as Pascal would also prevent you performing arithmetic with
Booleans, and would require that the expression in an @ref{2e7,,if} statement
always evaluate to a Boolean result.  Python is not this strict and never will
be, as 
@geindex Python Enhancement Proposals; PEP 285
PEP 285@footnote{https://peps.python.org/pep-0285/} explicitly says.  This means you can still use any expression
in an @code{if} statement, even ones that evaluate to a list or tuple or
some random object.  The Boolean type is a subclass of the @ref{254,,int} class so
that arithmetic using a Boolean still works.

@example
>>> True + 1
2
>>> False + 1
1
>>> False * 75
0
>>> True * 75
75
@end example

To sum up @ref{bfb,,True} and @ref{b25,,False} in a sentence: they're alternative
ways to spell the integer values 1 and 0, with the single difference that
@ref{435,,str()} and @ref{7e7,,repr()} return the strings @code{'True'} and @code{'False'}
instead of @code{'1'} and @code{'0'}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 285

@item PEP 285@footnote{https://peps.python.org/pep-0285/} -- Ajout d'un type `bool'

Written and implemented by GvR.
@end table


@c ======================================================================

@node PEP 293 Codec Error Handling Callbacks,PEP 301 Package Index and Metadata for Distutils,PEP 285 Un type booléen,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-293-codec-error-handling-callbacks}@anchor{144c}
@subsection PEP 293: Codec Error Handling Callbacks


When encoding a Unicode string into a byte string, unencodable characters may be
encountered.  So far, Python has allowed specifying the error processing as
either "strict" (raising @ref{1281,,UnicodeError}), "ignore" (skipping the
character), or "replace" (using a question mark in the output string), with
"strict" being the default behavior. It may be desirable to specify alternative
processing of such errors, such as inserting an XML character reference or HTML
entity reference into the converted string.

Python now has a flexible framework to add different processing strategies.  New
error handlers can be added with @ref{144d,,codecs.register_error()}, and codecs then
can access the error handler with @ref{144e,,codecs.lookup_error()}. An equivalent C
API has been added for codecs written in C. The error handler gets the necessary
state information such as the string being converted, the position in the string
where the error was detected, and the target encoding.  The handler can then
either raise an exception or return a replacement string.

Two additional error handlers have been implemented using this framework:
"backslashreplace" uses Python backslash quoting to represent unencodable
characters and "xmlcharrefreplace" emits XML character references.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 293

@item PEP 293@footnote{https://peps.python.org/pep-0293/} - Codec Error Handling Callbacks

Written and implemented by Walter Dörwald.
@end table


@c ======================================================================

@node PEP 301 Package Index and Metadata for Distutils,PEP 302 New Import Hooks,PEP 293 Codec Error Handling Callbacks,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-301-package-index-and-metadata-for-distutils}@anchor{144f}@anchor{whatsnew/2 3 section-pep301}@anchor{1450}
@subsection PEP 301: Package Index and Metadata for Distutils


Support for the long-requested Python catalog makes its first appearance in 2.3.

The heart of the catalog is the new Distutils @code{register} command.
Running @code{python setup.py register} will collect the metadata describing a
package, such as its name, version, maintainer, description, &c., and send it to
a central catalog server.  The resulting catalog is available from
@indicateurl{https://pypi.org}.

To make the catalog a bit more useful, a new optional `classifiers' keyword
argument has been added to the Distutils @code{setup()} function.  A list of
Trove@footnote{http://catb.org/~esr/trove/}-style strings can be supplied to help
classify the software.

Here's an example @code{setup.py} with classifiers, written to be compatible
with older versions of the Distutils:

@example
from distutils import core
kw = @{'name': "Quixote",
      'version': "0.5.1",
      'description': "A highly Pythonic Web application framework",
      # ...
      @}

if (hasattr(core, 'setup_keywords') and
    'classifiers' in core.setup_keywords):
    kw['classifiers'] = \
        ['Topic :: Internet :: WWW/HTTP :: Dynamic Content',
         'Environment :: No Input/Output (Daemon)',
         'Intended Audience :: Developers'],

core.setup(**kw)
@end example

The full list of classifiers can be obtained by running  @code{python setup.py
register --list-classifiers}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 301

@item PEP 301@footnote{https://peps.python.org/pep-0301/} - Package Index and Metadata for Distutils

Written and implemented by Richard Jones.
@end table


@c ======================================================================

@node PEP 302 New Import Hooks,PEP 305 Comma-separated Files,PEP 301 Package Index and Metadata for Distutils,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-302-new-import-hooks}@anchor{1451}@anchor{whatsnew/2 3 section-pep302}@anchor{143e}
@subsection PEP 302: New Import Hooks


While it's been possible to write custom import hooks ever since the
@code{ihooks} module was introduced in Python 1.3, no one has ever been really
happy with it because writing new import hooks is difficult and messy.  There
have been various proposed alternatives such as the @code{imputil} and @code{iu}
modules, but none of them has ever gained much acceptance, and none of them were
easily usable from C code.

@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} borrows ideas from its predecessors, especially from Gordon
McMillan's @code{iu} module.  Three new items  are added to the @ref{d8,,sys}
module:


@itemize *

@item 
@code{sys.path_hooks} is a list of callable objects; most  often they'll be
classes.  Each callable takes a string containing a path and either returns an
importer object that will handle imports from this path or raises an
@ref{40f,,ImportError} exception if it can't handle this path.

@item 
@code{sys.path_importer_cache} caches importer objects for each path, so
@code{sys.path_hooks} will only need to be traversed once for each path.

@item 
@code{sys.meta_path} is a list of importer objects that will be traversed before
@code{sys.path} is checked.  This list is initially empty, but user code can add
objects to it.  Additional built-in and frozen modules can be imported by an
object added to this list.
@end itemize

Importer objects must have a single method, @code{find_module(fullname,
path=None)}.  `fullname' will be a module or package name, e.g. @code{string} or
@code{distutils.core}.  @code{find_module()} must return a loader object that has a
single method, @code{load_module(fullname)}, that creates and returns the
corresponding module object.

Pseudo-code for Python's new import logic, therefore, looks something like this
(simplified a bit; see 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} for the full details):

@example
for mp in sys.meta_path:
    loader = mp(fullname)
    if loader is not None:
        <module> = loader.load_module(fullname)

for path in sys.path:
    for hook in sys.path_hooks:
        try:
            importer = hook(path)
        except ImportError:
            # ImportError, so try the other path hooks
            pass
        else:
            loader = importer.find_module(fullname)
            <module> = loader.load_module(fullname)

# Not found!
raise ImportError
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 302

@item PEP 302@footnote{https://peps.python.org/pep-0302/} — Nouveaux crochets d'importation

Written by Just van Rossum and Paul Moore. Implemented by Just van Rossum.
@end table


@c ======================================================================

@node PEP 305 Comma-separated Files,PEP 307 Pickle Enhancements,PEP 302 New Import Hooks,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-305-comma-separated-files}@anchor{1452}@anchor{whatsnew/2 3 section-pep305}@anchor{1453}
@subsection PEP 305: Comma-separated Files


Comma-separated files are a format frequently used for exporting data from
databases and spreadsheets.  Python 2.3 adds a parser for comma-separated files.

Comma-separated format is deceptively simple at first glance:

@example
Costs,150,200,3.95
@end example

Read a line and call @code{line.split(',')}: what could be simpler? But toss in
string data that can contain commas, and things get more complicated:

@example
"Costs",150,200,3.95,"Includes taxes, shipping, and sundry items"
@end example

A big ugly regular expression can parse this, but using the new  @ref{29,,csv}
package is much simpler:

@example
import csv

input = open('datafile', 'rb')
reader = csv.reader(input)
for line in reader:
    print line
@end example

The @ref{470,,reader()} function takes a number of different options. The field
separator isn't limited to the comma and can be changed to any character, and so
can the quoting and line-ending characters.

Different dialects of comma-separated files can be defined and registered;
currently there are two dialects, both used by Microsoft Excel. A separate
@ref{471,,csv.writer} class will generate comma-separated files from a succession
of tuples or lists, quoting strings that contain the delimiter.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 305

@item PEP 305@footnote{https://peps.python.org/pep-0305/} -- Interface des fichiers CSV

Written and implemented  by Kevin Altis, Dave Cole, Andrew McNamara, Skip
Montanaro, Cliff Wells.
@end table


@c ======================================================================

@node PEP 307 Pickle Enhancements,Extended Slices,PEP 305 Comma-separated Files,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pep-307-pickle-enhancements}@anchor{1454}@anchor{whatsnew/2 3 section-pep307}@anchor{1455}
@subsection PEP 307: Pickle Enhancements


The @ref{a5,,pickle} and @code{cPickle} modules received some attention during the
2.3 development cycle.  In 2.2, new-style classes could be pickled without
difficulty, but they weren't pickled very compactly; 
@geindex Python Enhancement Proposals; PEP 307
PEP 307@footnote{https://peps.python.org/pep-0307/} quotes a trivial
example where a new-style class results in a pickled string three times longer
than that for a classic class.

The solution was to invent a new pickle protocol.  The @ref{1456,,pickle.dumps()}
function has supported a text-or-binary flag  for a long time.  In 2.3, this
flag is redefined from a Boolean to an integer: 0 is the old text-mode pickle
format, 1 is the old binary format, and now 2 is a new 2.3-specific format.  A
new constant, @ref{1457,,pickle.HIGHEST_PROTOCOL}, can be used to select the
fanciest protocol available.

Unpickling is no longer considered a safe operation.  2.2's @ref{a5,,pickle}
provided hooks for trying to prevent unsafe classes from being unpickled
(specifically, a @code{__safe_for_unpickling__} attribute), but none of this
code was ever audited and therefore it's all been ripped out in 2.3.  You should
not unpickle untrusted data in any version of Python.

To reduce the pickling overhead for new-style classes, a new interface for
customizing pickling was added using three special methods:
@ref{5c2,,__getstate__()}, @ref{1458,,__setstate__()}, and @ref{1459,,__getnewargs__()}.  Consult
@geindex Python Enhancement Proposals; PEP 307
PEP 307@footnote{https://peps.python.org/pep-0307/} for the full semantics  of these methods.

As a way to compress pickles yet further, it's now possible to use integer codes
instead of long strings to identify pickled classes. The Python Software
Foundation will maintain a list of standardized codes; there's also a range of
codes for private use.  Currently no codes have been specified.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 307

@item PEP 307@footnote{https://peps.python.org/pep-0307/} - Extensions to the pickle protocol

Written and implemented  by Guido van Rossum and Tim Peters.
@end table


@c ======================================================================

@node Extended Slices,Autres changements au langage<18>,PEP 307 Pickle Enhancements,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 extended-slices}@anchor{145a}@anchor{whatsnew/2 3 section-slices}@anchor{145b}
@subsection Extended Slices


Ever since Python 1.4, the slicing syntax has supported an optional third "step"
or "stride" argument.  For example, these are all legal Python syntax:
@code{L[1:10:2]}, @code{L[:-1:1]}, @code{L[::-1]}.  This was added to Python at the
request of the developers of Numerical Python, which uses the third argument
extensively.  However, Python's built-in list, tuple, and string sequence types
have never supported this feature, raising a @ref{522,,TypeError} if you tried it.
Michael Hudson contributed a patch to fix this shortcoming.

For example, you can now easily extract the elements of a list that have even
indexes:

@example
>>> L = range(10)
>>> L[::2]
[0, 2, 4, 6, 8]
@end example

Negative values also work to make a copy of the same list in reverse order:

@example
>>> L[::-1]
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
@end example

This also works for tuples, arrays, and strings:

@example
>>> s='abcd'
>>> s[::2]
'ac'
>>> s[::-1]
'dcba'
@end example

If you have a mutable sequence such as a list or an array you can assign to or
delete an extended slice, but there are some differences between assignment to
extended and regular slices.  Assignment to a regular slice can be used to
change the length of the sequence:

@example
>>> a = range(3)
>>> a
[0, 1, 2]
>>> a[1:3] = [4, 5, 6]
>>> a
[0, 4, 5, 6]
@end example

Extended slices aren't this flexible.  When assigning to an extended slice, the
list on the right hand side of the statement must contain the same number of
items as the slice it is replacing:

@example
>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> a[::2] = [0, -1]
>>> a
[0, 1, -1, 3]
>>> a[::2] = [0,1,2]
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ValueError: attempt to assign sequence of size 3 to extended slice of size 2
@end example

Deletion is more straightforward:

@example
>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> del a[::2]
>>> a
[1, 3]
@end example

One can also now pass slice objects to the @ref{280,,__getitem__()} methods of the
built-in sequences:

@example
>>> range(10).__getitem__(slice(0, 5, 2))
[0, 2, 4]
@end example

Or use slice objects directly in subscripts:

@example
>>> range(10)[slice(0, 5, 2)]
[0, 2, 4]
@end example

To simplify implementing sequences that support extended slicing, slice objects
now have a method @code{indices(length)} which, given the length of a sequence,
returns a @code{(start, stop, step)} tuple that can be passed directly to
@ref{930,,range()}. @code{indices()} handles omitted and out-of-bounds indices in a
manner consistent with regular slices (and this innocuous phrase hides a welter
of confusing details!).  The method is intended to be used like this:

@example
class FakeSeq:
    ...
    def calc_item(self, i):
        ...
    def __getitem__(self, item):
        if isinstance(item, slice):
            indices = item.indices(len(self))
            return FakeSeq([self.calc_item(i) for i in range(*indices)])
        else:
            return self.calc_item(i)
@end example

From this example you can also see that the built-in @ref{453,,slice} object is
now the type object for the slice type, and is no longer a function.  This is
consistent with Python 2.2, where @ref{254,,int}, @ref{435,,str}, etc., underwent
the same change.

@c ======================================================================

@node Autres changements au langage<18>,New Improved and Deprecated Modules<4>,Extended Slices,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 other-language-changes}@anchor{145c}
@subsection Autres changements au langage


Here are all of the changes that Python 2.3 makes to the core Python language.


@itemize *

@item 
The @ref{9bb,,yield} statement is now always a keyword, as described in
section @ref{143a,,PEP 255 ; Générateurs simples} of this document.

@item 
A new built-in function @ref{1433,,enumerate()} was added, as described in section
@ref{1443,,PEP 279; enumerate()} of this document.

@item 
Two new constants, @ref{bfb,,True} and @ref{b25,,False} were added along with the
built-in @ref{451,,bool} type, as described in section @ref{144b,,PEP 285 ; Un type booléen} of this
document.

@item 
The @ref{254,,int()} type constructor will now return a long integer instead of
raising an @ref{86d,,OverflowError} when a string or floating-point number is too
large to fit into an integer.  This can lead to the paradoxical result that
@code{isinstance(int(expression), int)} is false, but that seems unlikely to cause
problems in practice.

@item 
Built-in types now support the extended slicing syntax, as described in
section @ref{145b,,Extended Slices} of this document.

@item 
A new built-in function, @code{sum(iterable, start=0)},  adds up the numeric
items in the iterable object and returns their sum.  @ref{454,,sum()} only accepts
numbers, meaning that you can't use it to concatenate a bunch of strings.
(Contributed by Alex Martelli.)

@item 
@code{list.insert(pos, value)} used to  insert `value' at the front of the list
when `pos' was negative.  The behaviour has now been changed to be consistent
with slice indexing, so when `pos' is -1 the value will be inserted before the
last element, and so forth.

@item 
@code{list.index(value)}, which searches for `value'  within the list and returns
its index, now takes optional  `start' and `stop' arguments to limit the search
to  only part of the list.

@item 
Dictionaries have a new method, @code{pop(key[, *default*])}, that returns
the value corresponding to `key' and removes that key/value pair from the
dictionary.  If the requested key isn't present in the dictionary, `default' is
returned if it's specified and @ref{33a,,KeyError} raised if it isn't.

@example
>>> d = @{1:2@}
>>> d
@{1: 2@}
>>> d.pop(4)
Traceback (most recent call last):
  File "stdin", line 1, in ?
KeyError: 4
>>> d.pop(1)
2
>>> d.pop(1)
Traceback (most recent call last):
  File "stdin", line 1, in ?
KeyError: 'pop(): dictionary is empty'
>>> d
@{@}
>>>
@end example

There's also a new class method,  @code{dict.fromkeys(iterable, value)}, that
creates a dictionary with keys taken from the supplied iterator `iterable' and
all values set to `value', defaulting to @code{None}.

(Patches contributed by Raymond Hettinger.)

Also, the @ref{253,,dict()} constructor now accepts keyword arguments to simplify
creating small dictionaries:

@example
>>> dict(red=1, blue=2, green=3, black=4)
@{'blue': 2, 'black': 4, 'green': 3, 'red': 1@}
@end example

(Contributed by Just van Rossum.)

@item 
The @ref{955,,assert} statement no longer checks the @code{__debug__} flag, so
you can no longer disable assertions by assigning to @code{__debug__}. Running
Python with the @ref{da2,,-O} switch will still generate code that doesn't
execute any assertions.

@item 
Most type objects are now callable, so you can use them to create new objects
such as functions, classes, and modules.  (This means that the @code{new} module
can be deprecated in a future Python version, because you can now use the type
objects available in the @ref{102,,types} module.) For example, you can create a new
module object with the following code:

@example
>>> import types
>>> m = types.ModuleType('abc','docstring')
>>> m
<module 'abc' (built-in)>
>>> m.__doc__
'docstring'
@end example

@item 
A new warning, @ref{8b5,,PendingDeprecationWarning} was added to indicate features
which are in the process of being deprecated.  The warning will `not' be printed
by default.  To check for use of features that will be deprecated in the future,
supply @ref{8b4,,-Walways;;PendingDeprecationWarning;;} on the command line or
use @ref{145d,,warnings.filterwarnings()}.

@item 
The process of deprecating string-based exceptions, as in @code{raise "Error
occurred"}, has begun.  Raising a string will now trigger
@ref{8b5,,PendingDeprecationWarning}.

@item 
Using @code{None} as a variable name will now result in a @ref{44f,,SyntaxWarning}
warning.  In a future version of Python, @code{None} may finally become a keyword.

@item 
The @code{xreadlines()} method of file objects, introduced in Python 2.1, is no
longer necessary because files now behave as their own iterator.
@code{xreadlines()} was originally introduced as a faster way to loop over all
the lines in a file, but now you can simply write @code{for line in file_obj}.
File objects also have a new read-only @code{encoding} attribute that gives the
encoding used by the file; Unicode strings written to the file will be
automatically  converted to bytes using the given encoding.

@item 
The method resolution order used by new-style classes has changed, though
you'll only notice the difference if you have a really complicated inheritance
hierarchy.  Classic classes are unaffected by this change.  Python 2.2
originally used a topological sort of a class's ancestors, but 2.3 now uses the
C3 algorithm as described in the paper "A Monotonic Superclass Linearization for Dylan"@footnote{https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.19.3910}. To
understand the motivation for this change,  read Michele Simionato's article
@ref{145e,,The Python 2.3 Method Resolution Order}, or
read the thread on python-dev starting with the message at
@indicateurl{https://mail.python.org/pipermail/python-dev/2002-October/029035.html}. Samuele
Pedroni first pointed out the problem and also implemented the fix by coding the
C3 algorithm.

@item 
Python runs multithreaded programs by switching between threads after
executing N bytecodes.  The default value for N has been increased from 10 to
100 bytecodes, speeding up single-threaded applications by reducing the
switching overhead.  Some multithreaded applications may suffer slower response
time, but that's easily fixed by setting the limit back to a lower number using
@code{sys.setcheckinterval(N)}. The limit can be retrieved with the new
@code{sys.getcheckinterval()} function.

@item 
One minor but far-reaching change is that the names of extension types defined
by the modules included with Python now contain the module and a @code{'.'} in
front of the type name.  For example, in Python 2.2, if you created a socket and
printed its @code{__class__}, you'd get this output:

@example
>>> s = socket.socket()
>>> s.__class__
<type 'socket'>
@end example

In 2.3, you get this:

@example
>>> s.__class__
<type '_socket.socket'>
@end example

@item 
One of the noted incompatibilities between old- and new-style classes has been
removed: you can now assign to the @ref{145f,,__name__} and @ref{1460,,__bases__}
attributes of new-style classes.  There are some restrictions on what can be
assigned to @code{__bases__} along the lines of those relating to assigning to
an instance's @ref{1461,,__class__} attribute.
@end itemize

@c ======================================================================

@menu
* String Changes:: 
* Optimizations: Optimizations<12>. 

@end menu

@node String Changes,Optimizations<12>,,Autres changements au langage<18>
@anchor{whatsnew/2 3 string-changes}@anchor{1462}
@subsubsection String Changes



@itemize *

@item 
The @ref{2e8,,in} operator now works differently for strings. Previously, when
evaluating @code{X in Y} where `X' and `Y' are strings, `X' could only be a single
character. That's now changed; `X' can be a string of any length, and @code{X in Y}
will return @ref{bfb,,True} if `X' is a substring of `Y'.  If `X' is the empty
string, the result is always @ref{bfb,,True}.

@example
>>> 'ab' in 'abcd'
True
>>> 'ad' in 'abcd'
False
>>> '@w{'} in 'abcd'
True
@end example

Note that this doesn't tell you where the substring starts; if you need that
information, use the @ref{e91,,find()} string method.

@item 
The @ref{1463,,strip()}, @ref{1464,,lstrip()}, and @ref{1465,,rstrip()} string methods now have
an optional argument for specifying the characters to strip.  The default is
still to remove all whitespace characters:

@example
>>> '   abc '.strip()
'abc'
>>> '><><abc<><><>'.strip('<>')
'abc'
>>> '><><abc<><><>\n'.strip('<>')
'abc<><><>\n'
>>> u'\u4000\u4001abc\u4000'.strip(u'\u4000')
u'\u4001abc'
>>>
@end example

(Suggested by Simon Brunning and implemented by Walter Dörwald.)

@item 
The @ref{eb4,,startswith()} and @ref{eb5,,endswith()} string methods now accept negative
numbers for the `start' and `end' parameters.

@item 
Another new string method is @ref{1466,,zfill()}, originally a function in the
@ref{d2,,string} module.  @ref{1466,,zfill()} pads a numeric string with zeros on the
left until it's the specified width. Note that the @code{%} operator is still more
flexible and powerful than @ref{1466,,zfill()}.

@example
>>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'
@end example

(Contributed by Walter Dörwald.)

@item 
A new type object, @code{basestring}, has been added. Both 8-bit strings and
Unicode strings inherit from this type, so @code{isinstance(obj, basestring)} will
return @ref{bfb,,True} for either kind of string.  It's a completely abstract
type, so you can't create @code{basestring} instances.

@item 
Interned strings are no longer immortal and will now be garbage-collected in
the usual way when the only reference to them is from the internal dictionary of
interned strings.  (Implemented by Oren Tirosh.)
@end itemize

@c ======================================================================

@node Optimizations<12>,,String Changes,Autres changements au langage<18>
@anchor{whatsnew/2 3 optimizations}@anchor{1467}
@subsubsection Optimizations



@itemize *

@item 
The creation of new-style class instances has been made much faster; they're
now faster than classic classes!

@item 
The @ref{bbd,,sort()} method of list objects has been extensively rewritten by Tim
Peters, and the implementation is significantly faster.

@item 
Multiplication of large long integers is now much faster thanks to an
implementation of Karatsuba multiplication, an algorithm that scales better than
the `O'(`n'@w{^2}) required for the grade-school multiplication algorithm.  (Original
patch by Christopher A. Craig, and significantly reworked by Tim Peters.)

@item 
The @code{SET_LINENO} opcode is now gone.  This may provide a small speed
increase, depending on your compiler's idiosyncrasies. See section
@ref{1468,,Autres changements et corrections} for a longer explanation. (Removed by Michael Hudson.)

@item 
@code{xrange()} objects now have their own iterator, making @code{for i in
xrange(n)} slightly faster than @code{for i in range(n)}.  (Patch by Raymond
Hettinger.)

@item 
A number of small rearrangements have been made in various hotspots to improve
performance, such as inlining a function or removing some code.  (Implemented
mostly by GvR, but lots of people have contributed single changes.)
@end itemize

The net result of the 2.3 optimizations is that Python 2.3 runs the  pystone
benchmark around 25% faster than Python 2.2.

@c ======================================================================

@node New Improved and Deprecated Modules<4>,Pymalloc A Specialized Object Allocator,Autres changements au langage<18>,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 new-improved-and-deprecated-modules}@anchor{1469}
@subsection New, Improved, and Deprecated Modules


As usual, Python's standard library received a number of enhancements and bug
fixes.  Here's a partial list of the most notable changes, sorted alphabetically
by module name. Consult the @code{Misc/NEWS} file in the source tree for a more
complete list of changes, or look through the CVS logs for all the details.


@itemize *

@item 
The @ref{7,,array} module now supports arrays of Unicode characters using the
@code{'u'} format character.  Arrays also now support using the @code{+=} assignment
operator to add another array's contents, and the @code{*=} assignment operator to
repeat an array. (Contributed by Jason Orendorff.)

@item 
The @code{bsddb} module has been replaced by version 4.1.6 of the PyBSDDB@footnote{https://pybsddb.sourceforge.net} package, providing a more complete interface
to the transactional features of the BerkeleyDB library.

The old version of the module has been renamed to  @code{bsddb185} and is no
longer built automatically; you'll  have to edit @code{Modules/Setup} to enable
it.  Note that the new @code{bsddb} package is intended to be compatible with
the  old module, so be sure to file bugs if you discover any incompatibilities.
When upgrading to Python 2.3, if the new interpreter is compiled with a new
version of  the underlying BerkeleyDB library, you will almost certainly have to
convert your database files to the new version.  You can do this fairly easily
with the new scripts @code{db2pickle.py} and @code{pickle2db.py} which you
will find in the distribution's @code{Tools/scripts} directory.  If you've
already been using the PyBSDDB package and importing it as @code{bsddb3}, you
will have to change your @code{import} statements to import it as @code{bsddb}.

@item 
The new @ref{13,,bz2} module is an interface to the bz2 data compression library.
bz2-compressed data is usually smaller than  corresponding
@ref{132,,zlib}-compressed data. (Contributed by Gustavo Niemeyer.)

@item 
A set of standard date/time types has been added in the new @ref{30,,datetime}
module.  See the following section for more details.

@item 
The Distutils @code{Extension} class now supports an extra constructor
argument named `depends' for listing additional source files that an extension
depends on.  This lets Distutils recompile the module if any of the dependency
files are modified.  For example, if @code{sampmodule.c} includes the header
file @code{sample.h}, you would create the @code{Extension} object like
this:

@example
ext = Extension("samp",
                sources=["sampmodule.c"],
                depends=["sample.h"])
@end example

Modifying @code{sample.h} would then cause the module to be recompiled.
(Contributed by Jeremy Hylton.)

@item 
Other minor changes to Distutils: it now checks for the 
@geindex CC
@geindex variable d'environnement; CC
@ref{146a,,CC},
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS}, @code{CPP}, 
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS}, and 
@geindex CPPFLAGS
@geindex variable d'environnement; CPPFLAGS
@ref{146d,,CPPFLAGS}
environment variables, using them to override the settings in Python's
configuration (contributed by Robert Weber).

@item 
Previously the @ref{3a,,doctest} module would only search the docstrings of
public methods and functions for test cases, but it now also examines private
ones as well.  The @ref{de0,,DocTestSuite()} function creates a
@ref{de1,,unittest.TestSuite} object from a set of @ref{3a,,doctest} tests.

@item 
The new @code{gc.get_referents(object)} function returns a list of all the
objects referenced by `object'.

@item 
The @ref{60,,getopt} module gained a new function, @ref{146e,,gnu_getopt()}, that
supports the same arguments as the existing @ref{146f,,getopt()} function but uses
GNU-style scanning mode. The existing @ref{146f,,getopt()} stops processing options as
soon as a non-option argument is encountered, but in GNU-style mode processing
continues, meaning that options and arguments can be mixed.  For example:

@example
>>> getopt.getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename')], ['output', '-v'])
>>> getopt.gnu_getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename'), ('-v', '@w{'})], ['output'])
@end example

(Contributed by Peter Åstrand.)

@item 
The @ref{65,,grp}, @ref{b1,,pwd}, and @ref{bb,,resource} modules now return enhanced
tuples:

@example
>>> import grp
>>> g = grp.getgrnam('amk')
>>> g.gr_name, g.gr_gid
('amk', 500)
@end example

@item 
The @ref{66,,gzip} module can now handle files exceeding 2 GiB.

@item 
The new @ref{68,,heapq} module contains an implementation of a heap queue
algorithm.  A heap is an array-like data structure that keeps items in a
partially sorted order such that, for every index `k', @code{heap[k] <=
heap[2*k+1]} and @code{heap[k] <= heap[2*k+2]}.  This makes it quick to remove the
smallest item, and inserting a new item while maintaining the heap property is
`O'(log `n').  (See @indicateurl{https://xlinux.nist.gov/dads//HTML/priorityque.html} for more
information about the priority queue data structure.)

The @ref{68,,heapq} module provides @ref{1470,,heappush()} and @ref{1471,,heappop()} functions
for adding and removing items while maintaining the heap property on top of some
other mutable Python sequence type.  Here's an example that uses a Python list:

@example
>>> import heapq
>>> heap = []
>>> for item in [3, 7, 5, 11, 1]:
...    heapq.heappush(heap, item)
...
>>> heap
[1, 3, 5, 11, 7]
>>> heapq.heappop(heap)
1
>>> heapq.heappop(heap)
3
>>> heap
[5, 7, 11]
@end example

(Contributed by Kevin O'Connor.)

@item 
The IDLE integrated development environment has been updated using the code
from the IDLEfork project (@indicateurl{https://idlefork.sourceforge.net}).  The most notable feature is
that the code being developed is now executed in a subprocess, meaning that
there's no longer any need for manual @code{reload()} operations. IDLE's core code
has been incorporated into the standard library as the @ref{72,,idlelib} package.

@item 
The @ref{73,,imaplib} module now supports IMAP over SSL. (Contributed by Piers
Lauder and Tino Lange.)

@item 
The @ref{80,,itertools} contains a number of useful functions for use with
iterators, inspired by various functions provided by the ML and Haskell
languages.  For example, @code{itertools.ifilter(predicate, iterator)} returns all
elements in the iterator for which the function @code{predicate()} returns
@ref{bfb,,True}, and @code{itertools.repeat(obj, N)} returns @code{obj} `N' times.
There are a number of other functions in the module; see the package's reference
documentation for details.
(Contributed by Raymond Hettinger.)

@item 
Two new functions in the @ref{8d,,math} module, @code{degrees(rads)} and
@code{radians(degs)}, convert between radians and degrees.  Other functions in
the @ref{8d,,math} module such as @ref{1472,,math.sin()} and @ref{1473,,math.cos()} have always
required input values measured in radians.  Also, an optional `base' argument
was added to @ref{1474,,math.log()} to make it easier to compute logarithms for bases
other than @code{e} and @code{10}.  (Contributed by Raymond Hettinger.)

@item 
Several new POSIX functions (@code{getpgid()}, @code{killpg()}, @code{lchown()},
@code{loadavg()}, @code{major()}, @code{makedev()}, @code{minor()}, and
@code{mknod()}) were added to the @ref{ac,,posix} module that underlies the
@ref{a0,,os} module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S.
Otkidach.)

@item 
In the @ref{a0,,os} module, the @code{*stat()} family of functions can now report
fractions of a second in a timestamp.  Such time stamps are represented as
floats, similar to the value returned by @ref{251,,time.time()}.

During testing, it was found that some applications will break if time stamps
are floats.  For compatibility, when using the tuple interface of the
@ref{1475,,stat_result} time stamps will be represented as integers. When using
named fields (a feature first introduced in Python 2.2), time stamps are still
represented as integers, unless @code{os.stat_float_times()} is invoked to enable
float return values:

@example
>>> os.stat("/tmp").st_mtime
1034791200
>>> os.stat_float_times(True)
>>> os.stat("/tmp").st_mtime
1034791200.6335014
@end example

In Python 2.4, the default will change to always returning floats.

Application developers should enable this feature only if all their libraries
work properly when confronted with floating-point time stamps, or if they use
the tuple API. If used, the feature should be activated on an application level
instead of trying to enable it on a per-use basis.

@item 
The @ref{9f,,optparse} module contains a new parser for command-line arguments
that can convert option values to a particular Python type  and will
automatically generate a usage message.  See the following section for  more
details.

@item 
The old and never-documented @code{linuxaudiodev} module has been deprecated,
and a new version named @code{ossaudiodev} has been added.  The module was
renamed because the OSS sound drivers can be used on platforms other than Linux,
and the interface has also been tidied and brought up to date in various ways.
(Contributed by Greg Ward and Nicholas FitzRoy-Dale.)

@item 
The new @ref{a9,,platform} module contains a number of functions that try to
determine various properties of the platform you're running on.  There are
functions for getting the architecture, CPU type, the Windows OS version, and
even the Linux distribution version. (Contributed by Marc-André Lemburg.)

@item 
The parser objects provided by the @ref{125,,pyexpat} module can now optionally
buffer character data, resulting in fewer calls to your character data handler
and therefore faster performance.  Setting the parser object's
@ref{1476,,buffer_text} attribute to @ref{bfb,,True} will enable buffering.

@item 
The @code{sample(population, k)} function was added to the @ref{b7,,random}
module.  `population' is a sequence or @code{xrange} object containing the
elements of a population, and @ref{730,,sample()} chooses `k' elements from the
population without replacing chosen elements.  `k' can be any value up to
@code{len(population)}. For example:

@example
>>> days = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'St', 'Sn']
>>> random.sample(days, 3)      # Choose 3 elements
['St', 'Sn', 'Th']
>>> random.sample(days, 7)      # Choose 7 elements
['Tu', 'Th', 'Mo', 'We', 'St', 'Fr', 'Sn']
>>> random.sample(days, 7)      # Choose 7 again
['We', 'Mo', 'Sn', 'Fr', 'Tu', 'St', 'Th']
>>> random.sample(days, 8)      # Can't choose eight
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "random.py", line 414, in sample
      raise ValueError, "sample larger than population"
ValueError: sample larger than population
>>> random.sample(xrange(1,10000,2), 10)   # Choose ten odd nos. under 10000
[3407, 3805, 1505, 7023, 2401, 2267, 9733, 3151, 8083, 9195]
@end example

The @ref{b7,,random} module now uses a new algorithm, the Mersenne Twister,
implemented in C.  It's faster and more extensively studied than the previous
algorithm.

(All changes contributed by Raymond Hettinger.)

@item 
The @ref{b9,,readline} module also gained a number of new functions:
@ref{1477,,get_history_item()}, @ref{1478,,get_current_history_length()}, and
@ref{1479,,redisplay()}.

@item 
The @code{rexec} and @code{Bastion} modules have been declared dead, and
attempts to import them will fail with a @ref{193,,RuntimeError}.  New-style classes
provide new ways to break out of the restricted execution environment provided
by @code{rexec}, and no one has interest in fixing them or time to do so.  If
you have applications using @code{rexec}, rewrite them to use something else.

(Sticking with Python 2.2 or 2.1 will not make your applications any safer
because there are known bugs in the @code{rexec} module in those versions.  To
repeat: if you're using @code{rexec}, stop using it immediately.)

@item 
The @code{rotor} module has been deprecated because the  algorithm it uses for
encryption is not believed to be secure.  If you need encryption, use one of the
several AES Python modules that are available separately.

@item 
The @ref{c4,,shutil} module gained a @code{move(src, dest)} function that
recursively moves a file or directory to a new location.

@item 
Support for more advanced POSIX signal handling was added to the @ref{c5,,signal}
but then removed again as it proved impossible to make it work reliably across
platforms.

@item 
The @ref{cb,,socket} module now supports timeouts.  You can call the
@code{settimeout(t)} method on a socket object to set a timeout of `t' seconds.
Subsequent socket operations that take longer than `t' seconds to complete will
abort and raise a @ref{81e,,socket.timeout} exception.

The original timeout implementation was by Tim O'Malley.  Michael Gilfix
integrated it into the Python @ref{cb,,socket} module and shepherded it through a
lengthy review.  After the code was checked in, Guido van Rossum rewrote parts
of it.  (This is a good example of a collaborative development process in
action.)

@item 
On Windows, the @ref{cb,,socket} module now ships with Secure  Sockets Layer
(SSL) support.

@item 
The value of the C @code{PYTHON_API_VERSION} macro is now exposed at the
Python level as @code{sys.api_version}.  The current exception can be cleared by
calling the new @code{sys.exc_clear()} function.

@item 
The new @ref{dd,,tarfile} module  allows reading from and writing to
@code{tar}-format archive files. (Contributed by Lars Gustäbel.)

@item 
The new @ref{eb,,textwrap} module contains functions for wrapping strings
containing paragraphs of text.  The @code{wrap(text, width)} function takes a
string and returns a list containing the text split into lines of no more than
the chosen width.  The @code{fill(text, width)} function returns a single
string, reformatted to fit into lines no longer than the chosen width. (As you
can guess, @ref{147a,,fill()} is built on top of @ref{147b,,wrap()}.  For example:

@example
>>> import textwrap
>>> paragraph = "Not a whit, we defy augury: ... more text ..."
>>> textwrap.wrap(paragraph, 60)
["Not a whit, we defy augury: there's a special providence in",
 "the fall of a sparrow. If it be now, 'tis not to come; if it",
 ...]
>>> print textwrap.fill(paragraph, 35)
Not a whit, we defy augury: there's
a special providence in the fall of
a sparrow. If it be now, 'tis not
to come; if it be not to come, it
will be now; if it be not now, yet
it will come: the readiness is all.
>>>
@end example

The module also contains a @ref{fb8,,TextWrapper} class that actually implements
the text wrapping strategy.   Both the @ref{fb8,,TextWrapper} class and the
@ref{147b,,wrap()} and @ref{147a,,fill()} functions support a number of additional keyword
arguments for fine-tuning the formatting; consult the module's documentation
for details. (Contributed by Greg Ward.)

@item 
The @code{thread} and @ref{ec,,threading} modules now have companion modules,
@code{dummy_thread} and @code{dummy_threading}, that provide a do-nothing
implementation of the @code{thread} module's interface for platforms where
threads are not supported.  The intention is to simplify thread-aware modules
(ones that `don't' rely on threads to run) by putting the following code at the
top:

@example
try:
    import threading as _threading
except ImportError:
    import dummy_threading as _threading
@end example

In this example, @code{_threading} is used as the module name to make it clear
that the module being used is not necessarily the actual @ref{ec,,threading}
module. Code can call functions and use classes in @code{_threading} whether or
not threads are supported, avoiding an @ref{2e7,,if} statement and making the
code slightly clearer.  This module will not magically make multithreaded code
run without threads; code that waits for another thread to return or to do
something will simply hang forever.

@item 
The @ref{ed,,time} module's @ref{13e3,,strptime()} function has long been an annoyance
because it uses the platform C library's @ref{13e3,,strptime()} implementation, and
different platforms sometimes have odd bugs.  Brett Cannon contributed a
portable implementation that's written in pure Python and should behave
identically on all platforms.

@item 
The new @ref{ee,,timeit} module helps measure how long snippets of Python code
take to execute.  The @code{timeit.py} file can be run directly from the
command line, or the module's @ref{147c,,Timer} class can be imported and used
directly.  Here's a short example that figures out whether it's faster to
convert an 8-bit string to Unicode by appending an empty Unicode string to it or
by using the @code{unicode()} function:

@example
import timeit

timer1 = timeit.Timer('unicode("abc")')
timer2 = timeit.Timer('"abc" + u""')

# Run three trials
print timer1.repeat(repeat=3, number=100000)
print timer2.repeat(repeat=3, number=100000)

# On my laptop this outputs:
# [0.36831796169281006, 0.37441694736480713, 0.35304892063140869]
# [0.17574405670166016, 0.18193507194519043, 0.17565798759460449]
@end example

@item 
The @code{Tix} module has received various bug fixes and updates for the
current version of the Tix package.

@item 
The @code{Tkinter} module now works with a thread-enabled  version of Tcl.
Tcl's threading model requires that widgets only be accessed from the thread in
which they're created; accesses from another thread can cause Tcl to panic.  For
certain Tcl interfaces, @code{Tkinter} will now automatically avoid this  when a
widget is accessed from a different thread by marshalling a command, passing it
to the correct thread, and waiting for the results.  Other interfaces can't be
handled automatically but @code{Tkinter} will now raise an exception on such an
access so that you can at least find out about the problem.  See
@indicateurl{https://mail.python.org/pipermail/python-dev/2002-December/031107.html} for a more
detailed explanation of this change.  (Implemented by Martin von Löwis.)

@item 
Calling Tcl methods through @code{_tkinter} no longer  returns only strings.
Instead, if Tcl returns other objects those objects are converted to their
Python equivalent, if one exists, or wrapped with a @code{_tkinter.Tcl_Obj}
object if no Python equivalent exists. This behavior can be controlled through
the @code{wantobjects()} method of @code{tkapp} objects.

When using @code{_tkinter} through the @code{Tkinter} module (as most Tkinter
applications will), this feature is always activated. It should not cause
compatibility problems, since Tkinter would always convert string results to
Python types where possible.

If any incompatibilities are found, the old behavior can be restored by setting
the @code{wantobjects} variable in the @code{Tkinter} module to false before
creating the first @code{tkapp} object.

@example
import Tkinter
Tkinter.wantobjects = 0
@end example

Any breakage caused by this change should be reported as a bug.

@item 
The @code{UserDict} module has a new @code{DictMixin} class which defines
all dictionary methods for classes that already have a minimum mapping
interface.  This greatly simplifies writing classes that need to be
substitutable for dictionaries, such as the classes in  the @ref{c2,,shelve}
module.

Adding the mix-in as a superclass provides the full dictionary interface
whenever the class defines @ref{280,,__getitem__()}, @ref{12a9,,__setitem__()},
@ref{12aa,,__delitem__()}, and @code{keys()}. For example:

@example
>>> import UserDict
>>> class SeqDict(UserDict.DictMixin):
...     """Dictionary lookalike implemented with lists."""
...     def __init__(self):
...         self.keylist = []
...         self.valuelist = []
...     def __getitem__(self, key):
...         try:
...             i = self.keylist.index(key)
...         except ValueError:
...             raise KeyError
...         return self.valuelist[i]
...     def __setitem__(self, key, value):
...         try:
...             i = self.keylist.index(key)
...             self.valuelist[i] = value
...         except ValueError:
...             self.keylist.append(key)
...             self.valuelist.append(value)
...     def __delitem__(self, key):
...         try:
...             i = self.keylist.index(key)
...         except ValueError:
...             raise KeyError
...         self.keylist.pop(i)
...         self.valuelist.pop(i)
...     def keys(self):
...         return list(self.keylist)
...
>>> s = SeqDict()
>>> dir(s)      # See that other dictionary methods are implemented
['__cmp__', '__contains__', '__delitem__', '__doc__', '__getitem__',
 '__init__', '__iter__', '__len__', '__module__', '__repr__',
 '__setitem__', 'clear', 'get', 'has_key', 'items', 'iteritems',
 'iterkeys', 'itervalues', 'keylist', 'keys', 'pop', 'popitem',
 'setdefault', 'update', 'valuelist', 'values']
@end example

(Contributed by Raymond Hettinger.)

@item 
The DOM implementation in @ref{121,,xml.dom.minidom} can now generate XML output
in a particular encoding by providing an optional encoding argument to the
@ref{147d,,toxml()} and @ref{147e,,toprettyxml()} methods of DOM nodes.

@item 
The @code{xmlrpclib} module now supports an XML-RPC extension for handling nil
data values such as Python's @code{None}.  Nil values are always supported on
unmarshalling an XML-RPC response.  To generate requests containing @code{None},
you must supply a true value for the `allow_none' parameter when creating a
@code{Marshaller} instance.

@item 
The new @code{DocXMLRPCServer} module allows writing self-documenting XML-RPC
servers. Run it in demo mode (as a program) to see it in action.   Pointing the
web browser to the RPC server produces pydoc-style documentation; pointing
xmlrpclib to the server allows invoking the actual methods. (Contributed by
Brian Quinlan.)

@item 
Support for internationalized domain names (RFCs 3454, 3490, 3491, and 3492)
has been added. The "idna" encoding can be used to convert between a Unicode
domain name and the ASCII-compatible encoding (ACE) of that name.

@example
>@{@}>@{@}> u"www.Alliancefrançaise.nu".encode("idna")
'www.xn--alliancefranaise-npb.nu'
@end example

The @ref{cb,,socket} module has also been extended to transparently convert
Unicode hostnames to the ACE version before passing them to the C library.
Modules that deal with hostnames such as @code{httplib} and @ref{5d,,ftplib})
also support Unicode host names; @code{httplib} also sends HTTP @code{Host}
headers using the ACE version of the domain name.  @ref{107,,urllib} supports
Unicode URLs with non-ASCII host names as long as the @code{path} part of the URL
is ASCII only.

To implement this change, the @ref{d3,,stringprep} module, the  @code{mkstringprep}
tool and the @code{punycode} encoding have been added.
@end itemize

@c ======================================================================

@menu
* Date/Time Type:: 
* The optparse Module:: 

@end menu

@node Date/Time Type,The optparse Module,,New Improved and Deprecated Modules<4>
@anchor{whatsnew/2 3 date-time-type}@anchor{147f}
@subsubsection Date/Time Type


Date and time types suitable for expressing timestamps were added as the
@ref{30,,datetime} module.  The types don't support different calendars or many
fancy features, and just stick to the basics of representing time.

The three primary types are: @ref{1c8,,date}, representing a day, month, and year;
@ref{1c9,,time}, consisting of hour, minute, and second; and @ref{1c7,,datetime},
which contains all the attributes of both @ref{1c8,,date} and @ref{1c9,,time}.
There's also a @ref{9bd,,timedelta} class representing differences between two
points in time, and time zone logic is implemented by classes inheriting from
the abstract @ref{5c8,,tzinfo} class.

You can create instances of @ref{1c8,,date} and @ref{1c9,,time} by either supplying
keyword arguments to the appropriate constructor, e.g.
@code{datetime.date(year=1972, month=10, day=15)}, or by using one of a number of
class methods.  For example, the @ref{1480,,today()} class method returns the
current local date.

Once created, instances of the date/time classes are all immutable. There are a
number of methods for producing formatted strings from objects:

@example
>>> import datetime
>>> now = datetime.datetime.now()
>>> now.isoformat()
'2002-12-30T21:27:03.994956'
>>> now.ctime()  # Only available on date, datetime
'Mon Dec 30 21:27:03 2002'
>>> now.strftime('%Y %d %b')
'2002 30 Dec'
@end example

The @ref{1481,,replace()} method allows modifying one or more fields  of a
@ref{1c8,,date} or @ref{1c7,,datetime} instance, returning a new instance:

@example
>>> d = datetime.datetime.now()
>>> d
datetime.datetime(2002, 12, 30, 22, 15, 38, 827738)
>>> d.replace(year=2001, hour = 12)
datetime.datetime(2001, 12, 30, 12, 15, 38, 827738)
>>>
@end example

Instances can be compared, hashed, and converted to strings (the result is the
same as that of @ref{b1e,,isoformat()}).  @ref{1c8,,date} and @ref{1c7,,datetime}
instances can be subtracted from each other, and added to @ref{9bd,,timedelta}
instances.  The largest missing feature is that there's no standard library
support for parsing strings and getting back a @ref{1c8,,date} or
@ref{1c7,,datetime}.

For more information, refer to the module's reference documentation.
(Contributed by Tim Peters.)

@c ======================================================================

@node The optparse Module,,Date/Time Type,New Improved and Deprecated Modules<4>
@anchor{whatsnew/2 3 the-optparse-module}@anchor{1482}
@subsubsection The optparse Module


The @ref{60,,getopt} module provides simple parsing of command-line arguments.  The
new @ref{9f,,optparse} module (originally named Optik) provides more elaborate
command-line parsing that follows the Unix conventions, automatically creates
the output for @code{--help}, and can perform different actions for different
options.

You start by creating an instance of @ref{1483,,OptionParser} and telling it what
your program's options are.

@example
import sys
from optparse import OptionParser

op = OptionParser()
op.add_option('-i', '--input',
              action='store', type='string', dest='input',
              help='set input filename')
op.add_option('-l', '--length',
              action='store', type='int', dest='length',
              help='set maximum length of output')
@end example

Parsing a command line is then done by calling the @ref{1484,,parse_args()} method.

@example
options, args = op.parse_args(sys.argv[1:])
print options
print args
@end example

This returns an object containing all of the option values, and a list of
strings containing the remaining arguments.

Invoking the script with the various arguments now works as you'd expect it to.
Note that the length argument is automatically converted to an integer.

@example
$ ./python opt.py -i data arg1
<Values at 0x400cad4c: @{'input': 'data', 'length': None@}>
['arg1']
$ ./python opt.py --input=data --length=4
<Values at 0x400cad2c: @{'input': 'data', 'length': 4@}>
[]
$
@end example

The help message is automatically generated for you:

@example
$ ./python opt.py --help
usage: opt.py [options]

options:
  -h, --help            show this help message and exit
  -iINPUT, --input=INPUT
                        set input filename
  -lLENGTH, --length=LENGTH
                        set maximum length of output
$
@end example

See the module's documentation for more details.

Optik was written by Greg Ward, with suggestions from the readers of the Getopt
SIG.

@c ======================================================================

@node Pymalloc A Specialized Object Allocator,Build and C API Changes<12>,New Improved and Deprecated Modules<4>,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 pymalloc-a-specialized-object-allocator}@anchor{1485}@anchor{whatsnew/2 3 section-pymalloc}@anchor{1486}
@subsection Pymalloc: A Specialized Object Allocator


Pymalloc, a specialized object allocator written by Vladimir Marangozov, was a
feature added to Python 2.1.  Pymalloc is intended to be faster than the system
@code{malloc()} and to have less memory overhead for allocation patterns typical
of Python programs. The allocator uses C's @code{malloc()} function to get large
pools of memory and then fulfills smaller memory requests from these pools.

In 2.1 and 2.2, pymalloc was an experimental feature and wasn't enabled by
default; you had to explicitly enable it when compiling Python by providing the
@code{--with-pymalloc} option to the @code{configure} script.  In 2.3,
pymalloc has had further enhancements and is now enabled by default; you'll have
to supply @code{--without-pymalloc} to disable it.

This change is transparent to code written in Python; however, pymalloc may
expose bugs in C extensions.  Authors of C extension modules should test their
code with pymalloc enabled, because some incorrect code may cause core dumps at
runtime.

There's one particularly common error that causes problems.  There are a number
of memory allocation functions in Python's C API that have previously just been
aliases for the C library's @code{malloc()} and @code{free()}, meaning that if
you accidentally called mismatched functions the error wouldn't be noticeable.
When the object allocator is enabled, these functions aren't aliases of
@code{malloc()} and @code{free()} any more, and calling the wrong function to
free memory may get you a core dump.  For example, if memory was allocated using
@ref{c56,,PyObject_Malloc()}, it has to be freed using @ref{c53,,PyObject_Free()}, not
@code{free()}.  A few modules included with Python fell afoul of this and had to
be fixed; doubtless there are more third-party modules that will have the same
problem.

As part of this change, the confusing multiple interfaces for allocating memory
have been consolidated down into two API families. Memory allocated with one
family must not be manipulated with functions from the other family.  There is
one family for allocating chunks of memory and another family of functions
specifically for allocating Python objects.


@itemize *

@item 
To allocate and free an undistinguished chunk of memory use the "raw memory"
family: @ref{c54,,PyMem_Malloc()}, @ref{101b,,PyMem_Realloc()}, and @ref{13f9,,PyMem_Free()}.

@item 
The "object memory" family is the interface to the pymalloc facility described
above and is biased towards a large number of "small" allocations:
@ref{c56,,PyObject_Malloc()}, @ref{13fa,,PyObject_Realloc()}, and @ref{c53,,PyObject_Free()}.

@item 
To allocate and free Python objects, use the "object" family
@ref{972,,PyObject_New}, @ref{973,,PyObject_NewVar}, and @ref{1487,,PyObject_Del()}.
@end itemize

Thanks to lots of work by Tim Peters, pymalloc in 2.3 also provides debugging
features to catch memory overwrites and doubled frees in both extension modules
and in the interpreter itself.  To enable this support, compile a debugging
version of the Python interpreter by running @code{configure} with
@code{--with-pydebug}.

To aid extension writers, a header file @code{Misc/pymemcompat.h} is
distributed with the source to Python 2.3 that allows Python extensions to use
the 2.3 interfaces to memory allocation while compiling against any version of
Python since 1.5.2.  You would copy the file from Python's source distribution
and bundle it with the source of your extension.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://hg.python.org/cpython/file/default/Objects/obmalloc.c}

For the full details of the pymalloc implementation, see the comments at
the top of the file @code{Objects/obmalloc.c} in the Python source code.
The above link points to the file within the python.org SVN browser.
@end table


@c ======================================================================

@node Build and C API Changes<12>,Autres changements et corrections<2>,Pymalloc A Specialized Object Allocator,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 build-and-c-api-changes}@anchor{1488}
@subsection Build and C API Changes


Changes to Python's build process and to the C API include:


@itemize *

@item 
The cycle detection implementation used by the garbage collection has proven
to be stable, so it's now been made mandatory.  You can no longer compile Python
without it, and the @code{--with-cycle-gc} switch to @code{configure} has
been removed.

@item 
Python can now optionally be built as a shared library
(@code{libpython2.3.so}) by supplying @code{--enable-shared} when running
Python's @code{configure} script.  (Contributed by Ondrej Palkovsky.)

@item 
The @code{DL_EXPORT} and @code{DL_IMPORT} macros are now deprecated.
Initialization functions for Python extension modules should now be declared
using the new macro @ref{1489,,PyMODINIT_FUNC}, while the Python core will
generally use the @code{PyAPI_FUNC} and @code{PyAPI_DATA} macros.

@item 
The interpreter can be compiled without any docstrings for the built-in
functions and modules by supplying @code{--without-doc-strings} to the
@code{configure} script. This makes the Python executable about 10% smaller,
but will also mean that you can't get help for Python's built-ins.  (Contributed
by Gustavo Niemeyer.)

@item 
The @code{PyArg_NoArgs()} macro is now deprecated, and code that uses it
should be changed.  For Python 2.2 and later, the method definition table can
specify the @ref{148a,,METH_NOARGS} flag, signalling that there are no arguments,
and the argument checking can then be removed.  If compatibility with pre-2.2
versions of Python is important, the code could use @code{PyArg_ParseTuple(args,
"")} instead, but this will be slower than using @ref{148a,,METH_NOARGS}.

@item 
@ref{55d,,PyArg_ParseTuple()} accepts new format characters for various sizes of
unsigned integers: @code{B} for unsigned char, @code{H} for unsigned short int,  @code{I} for unsigned int,  and @code{K} for unsigned long long.

@item 
A new function, @code{PyObject_DelItemString(mapping, char *key)} was added
as shorthand for @code{PyObject_DelItem(mapping, PyString_New(key))}.

@item 
File objects now manage their internal string buffer differently, increasing
it exponentially when needed.  This results in the benchmark tests in
@code{Lib/test/test_bufio.py} speeding up considerably (from 57 seconds to 1.7
seconds, according to one measurement).

@item 
It's now possible to define class and static methods for a C extension type by
setting either the @ref{148b,,METH_CLASS} or @ref{148c,,METH_STATIC} flags in a
method's @ref{148d,,PyMethodDef} structure.

@item 
Python now includes a copy of the Expat XML parser's source code, removing any
dependence on a system version or local installation of Expat.

@item 
If you dynamically allocate type objects in your extension, you should be
aware of a change in the rules relating to the @ref{36a,,__module__} and
@ref{145f,,__name__} attributes.  In summary, you will want to ensure the type's
dictionary contains a @code{'__module__'} key; making the module name the part of
the type name leading up to the final period will no longer have the desired
effect.  For more detail, read the API reference documentation or the  source.
@end itemize

@c ======================================================================

@menu
* Port-Specific Changes: Port-Specific Changes<3>. 

@end menu

@node Port-Specific Changes<3>,,,Build and C API Changes<12>
@anchor{whatsnew/2 3 port-specific-changes}@anchor{148e}
@subsubsection Port-Specific Changes


Support for a port to IBM's OS/2 using the EMX runtime environment was merged
into the main Python source tree.  EMX is a POSIX emulation layer over the OS/2
system APIs.  The Python port for EMX tries to support all the POSIX-like
capability exposed by the EMX runtime, and mostly succeeds; @code{fork()} and
@ref{58,,fcntl()} are restricted by the limitations of the underlying emulation
layer.  The standard OS/2 port, which uses IBM's Visual Age compiler, also
gained support for case-sensitive import semantics as part of the integration of
the EMX port into CVS.  (Contributed by Andrew MacIntyre.)

On MacOS, most toolbox modules have been weaklinked to improve backward
compatibility.  This means that modules will no longer fail to load if a single
routine is missing on the current OS version. Instead calling the missing
routine will raise an exception. (Contributed by Jack Jansen.)

The RPM spec files, found in the @code{Misc/RPM/} directory in the Python
source distribution, were updated for 2.3.  (Contributed by Sean Reifschneider.)

Other new platforms now supported by Python include AtheOS
(@indicateurl{http://www.atheos.cx/}), GNU/Hurd, and OpenVMS.

@c ======================================================================

@node Autres changements et corrections<2>,Portage vers Python 2 3,Build and C API Changes<12>,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 other-changes-and-fixes}@anchor{148f}@anchor{whatsnew/2 3 section-other}@anchor{1468}
@subsection Autres changements et corrections


As usual, there were a bunch of other improvements and bugfixes scattered
throughout the source tree.  A search through the CVS change logs finds there
were 523 patches applied and 514 bugs fixed between Python 2.2 and 2.3.  Both
figures are likely to be underestimates.

Some of the more notable changes are:


@itemize *

@item 
If the 
@geindex PYTHONINSPECT
@geindex variable d'environnement; PYTHONINSPECT
@ref{1490,,PYTHONINSPECT} environment variable is set, the Python
interpreter will enter the interactive prompt after running a Python program, as
if Python had been invoked with the @ref{1491,,-i} option. The environment
variable can be set before running the Python interpreter, or it can be set by
the Python program as part of its execution.

@item 
The @code{regrtest.py} script now provides a way to allow "all resources
except `foo'."  A resource name passed to the @code{-u} option can now be
prefixed with a hyphen (@code{'-'}) to mean "remove this resource."  For example,
the option '@code{-uall,-bsddb}' could be used to enable the use of all resources
except @code{bsddb}.

@item 
The tools used to build the documentation now work under Cygwin as well as
Unix.

@item 
The @code{SET_LINENO} opcode has been removed.  Back in the mists of time, this
opcode was needed to produce line numbers in tracebacks and support trace
functions (for, e.g., @ref{a4,,pdb}). Since Python 1.5, the line numbers in
tracebacks have been computed using a different mechanism that works with
"python -O".  For Python 2.3 Michael Hudson implemented a similar scheme to
determine when to call the trace function, removing the need for @code{SET_LINENO}
entirely.

It would be difficult to detect any resulting difference from Python code, apart
from a slight speed up when Python is run without @ref{da2,,-O}.

C extensions that access the @ref{796,,f_lineno} field of frame objects should
instead call @code{PyCode_Addr2Line(f->f_code, f->f_lasti)}. This will have the
added effect of making the code work as desired under "python -O" in earlier
versions of Python.

A nifty new feature is that trace functions can now assign to the
@ref{796,,f_lineno} attribute of frame objects, changing the line that will be
executed next.  A @code{jump} command has been added to the @ref{a4,,pdb} debugger
taking advantage of this new feature. (Implemented by Richie Hindle.)
@end itemize

@c ======================================================================

@node Portage vers Python 2 3,Remerciements<5>,Autres changements et corrections<2>,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 porting-to-python-2-3}@anchor{1492}
@subsection Portage vers Python 2.3


This section lists previously described changes that may require changes to your
code:


@itemize *

@item 
@ref{9bb,,yield} is now always a keyword; if it's used as a variable name in
your code, a different name must be chosen.

@item 
For strings `X' and `Y', @code{X in Y} now works if `X' is more than one
character long.

@item 
The @ref{254,,int()} type constructor will now return a long integer instead of
raising an @ref{86d,,OverflowError} when a string or floating-point number is too
large to fit into an integer.

@item 
If you have Unicode strings that contain 8-bit characters, you must declare
the file's encoding (UTF-8, Latin-1, or whatever) by adding a comment to the top
of the file.  See section @ref{143c,,PEP 263; Source Code Encodings} for more information.

@item 
Calling Tcl methods through @code{_tkinter} no longer  returns only strings.
Instead, if Tcl returns other objects those objects are converted to their
Python equivalent, if one exists, or wrapped with a @code{_tkinter.Tcl_Obj}
object if no Python equivalent exists.

@item 
Large octal and hex literals such as @code{0xffffffff} now trigger a
@ref{40b,,FutureWarning}. Currently they're stored as 32-bit numbers and result in a
negative value, but in Python 2.4 they'll become positive long integers.

There are a few ways to fix this warning.  If you really need a positive number,
just add an @code{L} to the end of the literal.  If you're trying to get a 32-bit
integer with low bits set and have previously used an expression such as @code{~(1
<< 31)}, it's probably clearest to start with all bits set and clear the
desired upper bits. For example, to clear just the top bit (bit 31), you could
write @code{0xffffffffL &~(1L<<31)}.

@item 
You can no longer disable assertions by assigning to @code{__debug__}.

@item 
The Distutils @code{setup()} function has gained various new keyword arguments
such as `depends'.  Old versions of the Distutils will abort if passed unknown
keywords.  A solution is to check for the presence of the new
@code{get_distutil_options()} function in your @code{setup.py} and only uses the
new keywords with a version of the Distutils that supports them:

@example
from distutils import core

kw = @{'sources': 'foo.c', ...@}
if hasattr(core, 'get_distutil_options'):
    kw['depends'] = ['foo.h']
ext = Extension(**kw)
@end example

@item 
Using @code{None} as a variable name will now result in a @ref{44f,,SyntaxWarning}
warning.

@item 
Names of extension types defined by the modules included with Python now
contain the module and a @code{'.'} in front of the type name.
@end itemize

@c ======================================================================

@node Remerciements<5>,,Portage vers Python 2 3,Nouveautés de Python 2 3
@anchor{whatsnew/2 3 acknowledgements}@anchor{1493}@anchor{whatsnew/2 3 acks}@anchor{1494}
@subsection Remerciements


The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Jeff Bauer,
Simon Brunning, Brett Cannon, Michael Chermside, Andrew Dalke, Scott David
Daniels, Fred L. Drake, Jr., David Fraser,  Kelly Gerber, Raymond Hettinger,
Michael Hudson, Chris Lambert, Detlef Lannert, Martin von Löwis, Andrew
MacIntyre, Lalo Martins, Chad Netzer, Gustavo Niemeyer, Neal Norwitz, Hans
Nowak, Chris Reedy, Francesco Ricciardi, Vinay Sajip, Neil Schemenauer, Roman
Suzi, Jason Tishler, Just van Rossum.

@node Nouveautés de Python 2 2,Nouveautés de Python 2 1,Nouveautés de Python 2 3,Nouveautés de Python
@anchor{whatsnew/2 2 doc}@anchor{1495}@anchor{whatsnew/2 2 what-s-new-in-python-2-2}@anchor{1496}
@section Nouveautés de Python 2.2


@*Auteur: 
A.M. Kuchling


@c $Id: whatsnew22.tex 37315 2004-09-10 19:33:00Z akuchling $

@menu
* Introduction:: 
* PEP 252 et 253 ; Changements concernant les types et classes: PEP 252 et 253 Changements concernant les types et classes. 
* PEP 234 ; Itérateurs: PEP 234 Itérateurs. 
* PEP 255 ; Générateurs simples: PEP 255 Générateurs simples<2>. 
* PEP 237; Unifying Long Integers and Integers: PEP 237 Unifying Long Integers and Integers<2>. 
* PEP 238; Changing the Division Operator: PEP 238 Changing the Division Operator. 
* Unicode Changes:: 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes. 
* New and Improved Modules: New and Improved Modules<3>. 
* Interpreter Changes and Fixes:: 
* Autres changements et corrections: Autres changements et corrections<3>. 
* Remerciements: Remerciements<6>. 

@end menu

@node Introduction,PEP 252 et 253 Changements concernant les types et classes,,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 introduction}@anchor{1497}
@subsection Introduction


This article explains the new features in Python 2.2.2, released on October 14,
2002.  Python 2.2.2 is a bugfix release of Python 2.2, originally released on
December 21, 2001.

Python 2.2 can be thought of as the "cleanup release".  There are some features
such as generators and iterators that are completely new, but most of the
changes, significant and far-reaching though they may be, are aimed at cleaning
up irregularities and dark corners of the language design.

This article doesn't attempt to provide a complete specification of the new
features, but instead provides a convenient overview.  For full details, you
should refer to the documentation for Python 2.2, such as the Python Library Reference@footnote{https://docs.python.org/2.2/lib/lib.html} and the Python Reference Manual@footnote{https://docs.python.org/2.2/ref/ref.html}.  If you want to
understand the complete implementation and design rationale for a change, refer
to the PEP for a particular new feature.

@c see also, now defunct
@c 
@c http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm
@c    "What's So Special About Python 2.2?" is also about the new 2.2 features, and
@c    was written by Cameron Laird and Kathryn Soraiz.

@c ======================================================================

@node PEP 252 et 253 Changements concernant les types et classes,PEP 234 Itérateurs,Introduction,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 peps-252-and-253-type-and-class-changes}@anchor{1498}
@subsection PEP 252 et 253 : Changements concernant les types et classes


The largest and most far-reaching changes in Python 2.2 are to Python's model of
objects and classes.  The changes should be backward compatible, so it's likely
that your code will continue to run unchanged, but the changes provide some
amazing new capabilities. Before beginning this, the longest and most
complicated section of this article, I'll provide an overview of the changes and
offer some comments.

A long time ago I wrote a web page listing flaws in Python's design.  One of the
most significant flaws was that it's impossible to subclass Python types
implemented in C.  In particular, it's not possible to subclass built-in types,
so you can't just subclass, say, lists in order to add a single useful method to
them. The @code{UserList} module provides a class that supports all of the
methods of lists and that can be subclassed further, but there's lots of C code
that expects a regular Python list and won't accept a @ref{1499,,UserList}
instance.

Python 2.2 fixes this, and in the process adds some exciting new capabilities.
A brief summary:


@itemize *

@item 
You can subclass built-in types such as lists and even integers, and your
subclasses should work in every place that requires the original type.

@item 
It's now possible to define static and class methods, in addition to the
instance methods available in previous versions of Python.

@item 
It's also possible to automatically call methods on accessing or setting an
instance attribute by using a new mechanism called `properties'.  Many uses
of @ref{4bc,,__getattr__()} can be rewritten to use properties instead, making the
resulting code simpler and faster.  As a small side benefit, attributes can now
have docstrings, too.

@item 
The list of legal attributes for an instance can be limited to a particular
set using `slots', making it possible to safeguard against typos and
perhaps make more optimizations possible in future versions of Python.
@end itemize

Some users have voiced concern about all these changes.  Sure, they say, the new
features are neat and lend themselves to all sorts of tricks that weren't
possible in previous versions of Python, but they also make the language more
complicated.  Some people have said that they've always recommended Python for
its simplicity, and feel that its simplicity is being lost.

Personally, I think there's no need to worry.  Many of the new features are
quite esoteric, and you can write a lot of Python code without ever needed to be
aware of them.  Writing a simple class is no more difficult than it ever was, so
you don't need to bother learning or teaching them unless they're actually
needed.  Some very complicated tasks that were previously only possible from C
will now be possible in pure Python, and to my mind that's all for the better.

I'm not going to attempt to cover every single corner case and small change that
were required to make the new features work.  Instead this section will paint
only the broad strokes.  See section @ref{149a,,Related Links}, "Related Links", for
further sources of information about Python 2.2's new object model.

@menu
* Anciennes et nouvelles classes:: 
* Descripteurs:: 
* Héritage multiple ; la règle du diamant: Héritage multiple la règle du diamant. 
* Attribute Access:: 
* Related Links:: 

@end menu

@node Anciennes et nouvelles classes,Descripteurs,,PEP 252 et 253 Changements concernant les types et classes
@anchor{whatsnew/2 2 old-and-new-classes}@anchor{149b}
@subsubsection Anciennes et nouvelles classes


First, you should know that Python 2.2 really has two kinds of classes: classic
or old-style classes, and new-style classes.  The old-style class model is
exactly the same as the class model in earlier versions of Python.  All the new
features described in this section apply only to new-style classes. This
divergence isn't intended to last forever; eventually old-style classes will be
dropped, possibly in Python 3.0.

So how do you define a new-style class?  You do it by subclassing an existing
new-style class.  Most of Python's built-in types, such as integers, lists,
dictionaries, and even files, are new-style classes now.  A new-style class
named @ref{a7a,,object}, the base class for all built-in types, has also been
added so if no built-in type is suitable, you can just subclass
@ref{a7a,,object}:

@example
class C(object):
    def __init__ (self):
        ...
    ...
@end example

This means that @ref{12b5,,class} statements that don't have any base classes are
always classic classes in Python 2.2.  (Actually you can also change this by
setting a module-level variable named @code{__metaclass__} --- see 
@geindex Python Enhancement Proposals; PEP 253
PEP 253@footnote{https://peps.python.org/pep-0253/}
for the details --- but it's easier to just subclass @ref{a7a,,object}.)

The type objects for the built-in types are available as built-ins, named using
a clever trick.  Python has always had built-in functions named @ref{254,,int()},
@ref{2eb,,float()}, and @ref{435,,str()}.  In 2.2, they aren't functions any more, but
type objects that behave as factories when called.

@example
>>> int
<type 'int'>
>>> int('123')
123
@end example

To make the set of types complete, new type objects such as @ref{253,,dict()} and
@code{file()} have been added.  Here's a more interesting example, adding a
@code{lock()} method to file objects:

@example
class LockableFile(file):
    def lock (self, operation, length=0, start=0, whence=0):
        import fcntl
        return fcntl.lockf(self.fileno(), operation,
                           length, start, whence)
@end example

The now-obsolete @code{posixfile} module contained a class that emulated all of
a file object's methods and also added a @code{lock()} method, but this class
couldn't be passed to internal functions that expected a built-in file,
something which is possible with our new @code{LockableFile}.

@node Descripteurs,Héritage multiple la règle du diamant,Anciennes et nouvelles classes,PEP 252 et 253 Changements concernant les types et classes
@anchor{whatsnew/2 2 descriptors}@anchor{149c}
@subsubsection Descripteurs


In previous versions of Python, there was no consistent way to discover what
attributes and methods were supported by an object. There were some informal
conventions, such as defining @code{__members__} and @code{__methods__}
attributes that were lists of names, but often the author of an extension type
or a class wouldn't bother to define them.  You could fall back on inspecting
the @ref{546,,__dict__} of an object, but when class inheritance or an arbitrary
@code{__getattr__()} hook were in use this could still be inaccurate.

The one big idea underlying the new class model is that an API for describing
the attributes of an object using `descriptors' has been formalized.
Descriptors specify the value of an attribute, stating whether it's a method or
a field.  With the descriptor API, static methods and class methods become
possible, as well as more exotic constructs.

Attribute descriptors are objects that live inside class objects, and have a few
attributes of their own:


@itemize *

@item 
@ref{104f,,__name__} is the attribute's name.

@item 
@ref{915,,__doc__} is the attribute's docstring.

@item 
@code{__get__(object)} is a method that retrieves the attribute value from
`object'.

@item 
@code{__set__(object, value)} sets the attribute on `object' to `value'.

@item 
@code{__delete__(object, value)} deletes the `value'  attribute of `object'.
@end itemize

For example, when you write @code{obj.x}, the steps that Python actually performs
are:

@example
descriptor = obj.__class__.x
descriptor.__get__(obj)
@end example

For methods, @ref{149d,,descriptor.__get__} returns a temporary
object that's
callable, and wraps up the instance and the method to be called on it. This is
also why static methods and class methods are now possible; they have
descriptors that wrap up just the method, or the method and the class.  As a
brief explanation of these new kinds of methods, static methods aren't passed
the instance, and therefore resemble regular functions.  Class methods are
passed the class of the object, but not the object itself.  Static and class
methods are defined like this:

@example
class C(object):
    def f(arg1, arg2):
        ...
    f = staticmethod(f)

    def g(cls, arg1, arg2):
        ...
    g = classmethod(g)
@end example

The @ref{40c,,staticmethod()} function takes the function @code{f()}, and returns it
wrapped up in a descriptor so it can be stored in the class object.  You might
expect there to be special syntax for creating such methods (@code{def static f},
@code{defstatic f()}, or something like that) but no such syntax has been defined
yet; that's been left for future versions of Python.

More new features, such as slots and properties, are also implemented as new
kinds of descriptors, and it's not difficult to write a descriptor class that
does something novel.  For example, it would be possible to write a descriptor
class that made it possible to write Eiffel-style preconditions and
postconditions for a method.  A class that used this feature might be defined
like this:

@example
from eiffel import eiffelmethod

class C(object):
    def f(self, arg1, arg2):
        # The actual function
        ...
    def pre_f(self):
        # Check preconditions
        ...
    def post_f(self):
        # Check postconditions
        ...

    f = eiffelmethod(f, pre_f, post_f)
@end example

Note that a person using the new @code{eiffelmethod()} doesn't have to understand
anything about descriptors.  This is why I think the new features don't increase
the basic complexity of the language. There will be a few wizards who need to
know about it in order to write @code{eiffelmethod()} or the ZODB or whatever,
but most users will just write code on top of the resulting libraries and ignore
the implementation details.

@node Héritage multiple la règle du diamant,Attribute Access,Descripteurs,PEP 252 et 253 Changements concernant les types et classes
@anchor{whatsnew/2 2 multiple-inheritance-the-diamond-rule}@anchor{149e}
@subsubsection Héritage multiple : la règle du diamant


Multiple inheritance has also been made more useful through changing the rules
under which names are resolved.  Consider this set of classes (diagram taken
from 
@geindex Python Enhancement Proposals; PEP 253
PEP 253@footnote{https://peps.python.org/pep-0253/} by Guido van Rossum):

@example
      class A:
        ^ ^  def save(self): ...
       /   \
      /     \
     /       \
    /         \
class B     class C:
    ^         ^  def save(self): ...
     \       /
      \     /
       \   /
        \ /
      class D
@end example

The lookup rule for classic classes is simple but not very smart; the base
classes are searched depth-first, going from left to right.  A reference to
@code{D.save()} will search the classes @code{D}, @code{B}, and then
@code{A}, where @code{save()} would be found and returned.  @code{C.save()}
would never be found at all.  This is bad, because if @code{C}'s @code{save()}
method is saving some internal state specific to @code{C}, not calling it will
result in that state never getting saved.

New-style classes follow a different algorithm that's a bit more complicated to
explain, but does the right thing in this situation. (Note that Python 2.3
changes this algorithm to one that produces the same results in most cases, but
produces more useful results for really complicated inheritance graphs.)


@enumerate 

@item 
List all the base classes, following the classic lookup rule and include a
class multiple times if it's visited repeatedly.  In the above example, the list
of visited classes is [@code{D}, @code{B}, @code{A}, @code{C},
@code{A}].

@item 
Scan the list for duplicated classes.  If any are found, remove all but one
occurrence, leaving the `last' one in the list.  In the above example, the list
becomes [@code{D}, @code{B}, @code{C}, @code{A}] after dropping
duplicates.
@end enumerate

Following this rule, referring to @code{D.save()} will return @code{C.save()},
which is the behaviour we're after.  This lookup rule is the same as the one
followed by Common Lisp.  A new built-in function, @ref{4c5,,super()}, provides a way
to get at a class's superclasses without having to reimplement Python's
algorithm. The most commonly used form will be  @code{super(class, obj)}, which
returns  a bound superclass object (not the actual class object).  This form
will be used in methods to call a method in the superclass; for example,
@code{D}'s @code{save()} method would look like this:

@example
class D (B,C):
    def save (self):
        # Call superclass .save()
        super(D, self).save()
        # Save D's private information here
        ...
@end example

@ref{4c5,,super()} can also return unbound superclass objects when called as
@code{super(class)} or @code{super(class1, class2)}, but this probably won't
often be useful.

@node Attribute Access,Related Links,Héritage multiple la règle du diamant,PEP 252 et 253 Changements concernant les types et classes
@anchor{whatsnew/2 2 attribute-access}@anchor{149f}
@subsubsection Attribute Access


A fair number of sophisticated Python classes define hooks for attribute access
using @ref{4bc,,__getattr__()}; most commonly this is done for convenience, to make
code more readable by automatically mapping an attribute access such as
@code{obj.parent} into a method call such as @code{obj.get_parent}.  Python 2.2 adds
some new ways of controlling attribute access.

First, @code{__getattr__(attr_name)} is still supported by new-style classes,
and nothing about it has changed.  As before, it will be called when an attempt
is made to access @code{obj.foo} and no attribute named @code{foo} is found in the
instance's dictionary.

New-style classes also support a new method,
@code{__getattribute__(attr_name)}.  The difference between the two methods is
that @ref{bc0,,__getattribute__()} is `always' called whenever any attribute is
accessed, while the old @ref{4bc,,__getattr__()} is only called if @code{foo} isn't
found in the instance's dictionary.

However, Python 2.2's support for `properties' will often be a simpler way
to trap attribute references.  Writing a @code{__getattr__()} method is
complicated because to avoid recursion you can't use regular attribute accesses
inside them, and instead have to mess around with the contents of
@ref{546,,__dict__}. @ref{4bc,,__getattr__()} methods also end up being called by Python
when it checks for other methods such as @ref{607,,__repr__()} or @code{__coerce__()},
and so have to be written with this in mind. Finally, calling a function on
every attribute access results in a sizable performance loss.

@ref{192,,property} is a new built-in type that packages up three functions that
get, set, or delete an attribute, and a docstring.  For example, if you want to
define a @code{size} attribute that's computed, but also settable, you could
write:

@example
class C(object):
    def get_size (self):
        result = ... computation ...
        return result
    def set_size (self, size):
        ... compute something based on the size
        and set internal state appropriately ...

    # Define a property.  The 'delete this attribute'
    # method is defined as None, so the attribute
    # can't be deleted.
    size = property(get_size, set_size,
                    None,
                    "Storage size of this instance")
@end example

That is certainly clearer and easier to write than a pair of
@code{__getattr__()}/@code{__setattr__()} methods that check for the @code{size}
attribute and handle it specially while retrieving all other attributes from the
instance's @ref{546,,__dict__}.  Accesses to @code{size} are also the only ones
which have to perform the work of calling a function, so references to other
attributes run at their usual speed.

Finally, it's possible to constrain the list of attributes that can be
referenced on an object using the new @ref{14a0,,__slots__} class attribute. Python
objects are usually very dynamic; at any time it's possible to define a new
attribute on an instance by just doing @code{obj.new_attr=1}.   A new-style class
can define a class attribute named @ref{14a0,,__slots__} to limit the legal
attributes  to a particular set of names.  An example will make this clear:

@example
>>> class C(object):
...     __slots__ = ('template', 'name')
...
>>> obj = C()
>>> print obj.template
None
>>> obj.template = 'Test'
>>> print obj.template
Test
>>> obj.newattr = None
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'C' object has no attribute 'newattr'
@end example

Note how you get an @ref{343,,AttributeError} on the attempt to assign to an
attribute not listed in @ref{14a0,,__slots__}.

@node Related Links,,Attribute Access,PEP 252 et 253 Changements concernant les types et classes
@anchor{whatsnew/2 2 related-links}@anchor{14a1}@anchor{whatsnew/2 2 sect-rellinks}@anchor{149a}
@subsubsection Related Links


This section has just been a quick overview of the new features, giving enough
of an explanation to start you programming, but many details have been
simplified or ignored.  Where should you go to get a more complete picture?

The @ref{14a2,,Descriptor Guide} is a lengthy tutorial introduction to
the descriptor features, written by Guido van Rossum. If my description has
whetted your appetite, go read this tutorial next, because it goes into much
more detail about the new features while still remaining quite easy to read.

Next, there are two relevant PEPs, 
@geindex Python Enhancement Proposals; PEP 252
PEP 252@footnote{https://peps.python.org/pep-0252/} and 
@geindex Python Enhancement Proposals; PEP 253
PEP 253@footnote{https://peps.python.org/pep-0253/}.  
@geindex Python Enhancement Proposals; PEP 252
PEP 252@footnote{https://peps.python.org/pep-0252/} is
titled "Making Types Look More Like Classes", and covers the descriptor API.
@geindex Python Enhancement Proposals; PEP 253
PEP 253@footnote{https://peps.python.org/pep-0253/} is titled "Subtyping Built-in Types", and describes the changes to
type objects that make it possible to subtype built-in objects.  
@geindex Python Enhancement Proposals; PEP 253
PEP 253@footnote{https://peps.python.org/pep-0253/} is
the more complicated PEP of the two, and at a few points the necessary
explanations of types and meta-types may cause your head to explode.  Both PEPs
were written and implemented by Guido van Rossum, with substantial assistance
from the rest of the Zope Corp. team.

Finally, there's the ultimate authority: the source code.  Most of the machinery
for the type handling is in @code{Objects/typeobject.c}, but you should only
resort to it after all other avenues have been exhausted, including posting a
question to python-list or python-dev.

@c ======================================================================

@node PEP 234 Itérateurs,PEP 255 Générateurs simples<2>,PEP 252 et 253 Changements concernant les types et classes,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 pep-234-iterators}@anchor{14a3}
@subsection PEP 234 : Itérateurs


Another significant addition to 2.2 is an iteration interface at both the C and
Python levels.  Objects can define how they can be looped over by callers.

In Python versions up to 2.1, the usual way to make @code{for item in obj} work is
to define a @ref{280,,__getitem__()} method that looks something like this:

@example
def __getitem__(self, index):
    return <next item>
@end example

@ref{280,,__getitem__()} is more properly used to define an indexing operation on an
object so that you can write @code{obj[5]} to retrieve the sixth element.  It's a
bit misleading when you're using this only to support @ref{2e6,,for} loops.
Consider some file-like object that wants to be looped over; the `index'
parameter is essentially meaningless, as the class probably assumes that a
series of @ref{280,,__getitem__()} calls will be made with `index' incrementing by
one each time.  In other words, the presence of the @ref{280,,__getitem__()} method
doesn't mean that using @code{file[5]}  to randomly access the sixth element will
work, though it really should.

In Python 2.2, iteration can be implemented separately, and @ref{280,,__getitem__()}
methods can be limited to classes that really do support random access.  The
basic idea of iterators is  simple.  A new built-in function, @code{iter(obj)}
or @code{iter(C, sentinel)}, is used to get an iterator. @code{iter(obj)} returns
an iterator for the object `obj', while @code{iter(C, sentinel)} returns an
iterator that will invoke the callable object `C' until it returns `sentinel' to
signal that the iterator is done.

Python classes can define an @code{__iter__()} method, which should create and
return a new iterator for the object; if the object is its own iterator, this
method can just return @code{self}.  In particular, iterators will usually be their
own iterators.  Extension types implemented in C can implement a @ref{14a4,,tp_iter}
function in order to return an iterator, and extension types that want to behave
as iterators can define a @ref{14a5,,tp_iternext} function.

So, after all this, what do iterators actually do?  They have one required
method, @ref{7c2,,next()}, which takes no arguments and returns the next value.  When
there are no more values to be returned, calling @ref{7c2,,next()} should raise the
@ref{be8,,StopIteration} exception.

@example
>>> L = [1,2,3]
>>> i = iter(L)
>>> print i
<iterator object at 0x8116870>
>>> i.next()
1
>>> i.next()
2
>>> i.next()
3
>>> i.next()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
StopIteration
>>>
@end example

In 2.2, Python's @ref{2e6,,for} statement no longer expects a sequence; it
expects something for which @ref{7c1,,iter()} will return an iterator. For backward
compatibility and convenience, an iterator is automatically constructed for
sequences that don't implement @code{__iter__()} or a @ref{14a4,,tp_iter} slot, so
@code{for i in [1,2,3]} will still work.  Wherever the Python interpreter loops
over a sequence, it's been changed to use the iterator protocol.  This means you
can do things like this:

@example
>>> L = [1,2,3]
>>> i = iter(L)
>>> a,b,c = i
>>> a,b,c
(1, 2, 3)
@end example

Iterator support has been added to some of Python's basic types.   Calling
@ref{7c1,,iter()} on a dictionary will return an iterator which loops over its keys:

@example
>>> m = @{'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
...      'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12@}
>>> for key in m: print key, m[key]
...
Mar 3
Feb 2
Aug 8
Sep 9
May 5
Jun 6
Jul 7
Jan 1
Apr 4
Nov 11
Dec 12
Oct 10
@end example

That's just the default behaviour.  If you want to iterate over keys, values, or
key/value pairs, you can explicitly call the @code{iterkeys()},
@code{itervalues()}, or @code{iteritems()} methods to get an appropriate iterator.
In a minor related change, the @ref{2e8,,in} operator now works on dictionaries,
so @code{key in dict} is now equivalent to @code{dict.has_key(key)}.

Files also provide an iterator, which calls the @ref{b9,,readline()} method until
there are no more lines in the file.  This means you can now read each line of a
file using code like this:

@example
for line in file:
    # do something for each line
    ...
@end example

Note that you can only go forward in an iterator; there's no way to get the
previous element, reset the iterator, or make a copy of it. An iterator object
could provide such additional capabilities, but the iterator protocol only
requires a @ref{7c2,,next()} method.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 234

@item PEP 234@footnote{https://peps.python.org/pep-0234/} -- Itérateurs

Written by Ka-Ping Yee and GvR; implemented  by the Python Labs crew, mostly by
GvR and Tim Peters.
@end table


@c ======================================================================

@node PEP 255 Générateurs simples<2>,PEP 237 Unifying Long Integers and Integers<2>,PEP 234 Itérateurs,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 pep-255-simple-generators}@anchor{14a6}
@subsection PEP 255 : Générateurs simples


Generators are another new feature, one that interacts with the introduction of
iterators.

You're doubtless familiar with how function calls work in Python or C.  When you
call a function, it gets a private namespace where its local variables are
created.  When the function reaches a @ref{9bc,,return} statement, the local
variables are destroyed and the resulting value is returned to the caller.  A
later call to the same function will get a fresh new set of local variables.
But, what if the local variables weren't thrown away on exiting a function?
What if you could later resume the function where it left off?  This is what
generators provide; they can be thought of as resumable functions.

Here's the simplest example of a generator function:

@example
def generate_ints(N):
    for i in range(N):
        yield i
@end example

A new keyword, @ref{9bb,,yield}, was introduced for generators.  Any function
containing a @code{yield} statement is a generator function; this is
detected by Python's bytecode compiler which compiles the function specially as
a result.  Because a new keyword was introduced, generators must be explicitly
enabled in a module by including a @code{from __future__ import generators}
statement near the top of the module's source code.  In Python 2.3 this
statement will become unnecessary.

When you call a generator function, it doesn't return a single value; instead it
returns a generator object that supports the iterator protocol.  On executing
the @ref{9bb,,yield} statement, the generator outputs the value of @code{i},
similar to a @ref{9bc,,return} statement.  The big difference between
@code{yield} and a @code{return} statement is that on reaching a
@code{yield} the generator's state of execution is suspended and local
variables are preserved.  On the next call to the generator's @code{next()} method,
the function will resume executing immediately after the @code{yield}
statement.  (For complicated reasons, the @code{yield} statement isn't
allowed inside the @code{try} block of a
@ref{6d3,,try}...@ref{9b8,,finally} statement; read 
@geindex Python Enhancement Proposals; PEP 255
PEP 255@footnote{https://peps.python.org/pep-0255/} for a full
explanation of the interaction between @code{yield} and exceptions.)

Here's a sample usage of the @code{generate_ints()} generator:

@example
>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "<stdin>", line 2, in generate_ints
StopIteration
@end example

You could equally write @code{for i in generate_ints(5)}, or @code{a,b,c =
generate_ints(3)}.

Inside a generator function, the @ref{9bc,,return} statement can only be used
without a value, and signals the end of the procession of values; afterwards the
generator cannot return any further values. @code{return} with a value, such
as @code{return 5}, is a syntax error inside a generator function.  The end of the
generator's results can also be indicated by raising @ref{be8,,StopIteration}
manually, or by just letting the flow of execution fall off the bottom of the
function.

You could achieve the effect of generators manually by writing your own class
and storing all the local variables of the generator as instance variables.  For
example, returning a list of integers could be done by setting @code{self.count} to
0, and having the @ref{7c2,,next()} method increment @code{self.count} and return it.
However, for a moderately complicated generator, writing a corresponding class
would be much messier. @code{Lib/test/test_generators.py} contains a number of
more interesting examples.  The simplest one implements an in-order traversal of
a tree using generators recursively.

@example
# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x
        yield t.label
        for x in inorder(t.right):
            yield x
@end example

Two other examples in @code{Lib/test/test_generators.py} produce solutions for
the N-Queens problem (placing $N$ queens on an $NxN$ chess board so that no
queen threatens another) and the Knight's Tour (a route that takes a knight to
every square of an $NxN$ chessboard without visiting any square twice).

The idea of generators comes from other programming languages, especially Icon
(@indicateurl{https://www2.cs.arizona.edu/icon/}), where the idea of generators is central.  In
Icon, every expression and function call behaves like a generator.  One example
from "An Overview of the Icon Programming Language" at
@indicateurl{https://www2.cs.arizona.edu/icon/docs/ipd266.htm} gives an idea of what this looks
like:

@example
sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)
@end example

In Icon the @code{find()} function returns the indexes at which the substring
"or" is found: 3, 23, 33.  In the @ref{2e7,,if} statement, @code{i} is first
assigned a value of 3, but 3 is less than 5, so the comparison fails, and Icon
retries it with the second value of 23.  23 is greater than 5, so the comparison
now succeeds, and the code prints the value 23 to the screen.

Python doesn't go nearly as far as Icon in adopting generators as a central
concept.  Generators are considered a new part of the core Python language, but
learning or using them isn't compulsory; if they don't solve any problems that
you have, feel free to ignore them. One novel feature of Python's interface as
compared to Icon's is that a generator's state is represented as a concrete
object (the iterator) that can be passed around to other functions or stored in
a data structure.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 255

@item PEP 255@footnote{https://peps.python.org/pep-0255/}: Générateurs simples

Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland.  Implemented mostly
by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew.
@end table


@c ======================================================================

@node PEP 237 Unifying Long Integers and Integers<2>,PEP 238 Changing the Division Operator,PEP 255 Générateurs simples<2>,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 pep-237-unifying-long-integers-and-integers}@anchor{14a7}
@subsection PEP 237: Unifying Long Integers and Integers


In recent versions, the distinction between regular integers, which are 32-bit
values on most machines, and long integers, which can be of arbitrary size, was
becoming an annoyance.  For example, on platforms that support files larger than
@code{2**32} bytes, the @code{tell()} method of file objects has to return a long
integer. However, there were various bits of Python that expected plain integers
and would raise an error if a long integer was provided instead.  For example,
in Python 1.5, only regular integers could be used as a slice index, and
@code{'abc'[1L:]} would raise a @ref{522,,TypeError} exception with the message 'slice
index must be int'.

Python 2.2 will shift values from short to long integers as required. The 'L'
suffix is no longer needed to indicate a long integer literal, as now the
compiler will choose the appropriate type.  (Using the 'L' suffix will be
discouraged in future 2.x versions of Python, triggering a warning in Python
2.4, and probably dropped in Python 3.0.)  Many operations that used to raise an
@ref{86d,,OverflowError} will now return a long integer as their result.  For
example:

@example
>>> 1234567890123
1234567890123L
>>> 2 ** 64
18446744073709551616L
@end example

In most cases, integers and long integers will now be treated identically.  You
can still distinguish them with the @ref{d36,,type()} built-in function, but that's
rarely needed.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 237

@item PEP 237@footnote{https://peps.python.org/pep-0237/} - Unifying Long Integers and Integers

Written by Moshe Zadka and Guido van Rossum.  Implemented mostly by Guido van
Rossum.
@end table


@c ======================================================================

@node PEP 238 Changing the Division Operator,Unicode Changes,PEP 237 Unifying Long Integers and Integers<2>,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 pep-238-changing-the-division-operator}@anchor{14a8}
@subsection PEP 238: Changing the Division Operator


The most controversial change in Python 2.2 heralds the start of an effort to
fix an old design flaw that's been in Python from the beginning. Currently
Python's division operator, @code{/}, behaves like C's division operator when
presented with two integer arguments: it returns an integer result that's
truncated down when there would be a fractional part.  For example, @code{3/2} is
1, not 1.5, and @code{(-1)/2} is -1, not -0.5.  This means that the results of
division can vary unexpectedly depending on the type of the two operands and
because Python is dynamically typed, it can be difficult to determine the
possible types of the operands.

(The controversy is over whether this is `really' a design flaw, and whether
it's worth breaking existing code to fix this.  It's caused endless discussions
on python-dev, and in July 2001 erupted into a storm of acidly sarcastic
postings on @code{comp.lang.python}. I won't argue for either side here
and will stick to describing what's  implemented in 2.2.  Read 
@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/} for a
summary of arguments and counter-arguments.)

Because this change might break code, it's being introduced very gradually.
Python 2.2 begins the transition, but the switch won't be complete until Python
3.0.

First, I'll borrow some terminology from 
@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/}.  "True division" is the
division that most non-programmers are familiar with: 3/2 is 1.5, 1/4 is 0.25,
and so forth.  "Floor division" is what Python's @code{/} operator currently does
when given integer operands; the result is the floor of the value returned by
true division.  "Classic division" is the current mixed behaviour of @code{/}; it
returns the result of floor division when the operands are integers, and returns
the result of true division when one of the operands is a floating-point number.

Here are the changes 2.2 introduces:


@itemize *

@item 
A new operator, @code{//}, is the floor division operator. (Yes, we know it looks
like C++'s comment symbol.)  @code{//} `always' performs floor division no matter
what the types of its operands are, so @code{1 // 2} is 0 and @code{1.0 // 2.0} is
also 0.0.

@code{//} is always available in Python 2.2; you don't need to enable it using a
@code{__future__} statement.

@item 
By including a @code{from __future__ import division} in a module, the @code{/}
operator will be changed to return the result of true division, so @code{1/2} is
0.5.  Without the @code{__future__} statement, @code{/} still means classic division.
The default meaning of @code{/} will not change until Python 3.0.

@item 
Classes can define methods called @ref{14a9,,__truediv__()} and @ref{14aa,,__floordiv__()}
to overload the two division operators.  At the C level, there are also slots in
the @ref{13d4,,PyNumberMethods} structure so extension types can define the two
operators.

@item 
Python 2.2 supports some command-line arguments for testing whether code will
work with the changed division semantics.  Running python with @code{-Q
warn} will cause a warning to be issued whenever division is applied to two
integers.  You can use this to find code that's affected by the change and fix
it.  By default, Python 2.2 will simply perform classic division without a
warning; the warning will be turned on by default in Python 2.3.
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 238

@item PEP 238@footnote{https://peps.python.org/pep-0238/} - Changing the Division Operator

Written by Moshe Zadka and  Guido van Rossum.  Implemented by Guido van Rossum..
@end table


@c ======================================================================

@node Unicode Changes,PEP 227 Nested Scopes,PEP 238 Changing the Division Operator,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 unicode-changes}@anchor{14ab}
@subsection Unicode Changes


Python's Unicode support has been enhanced a bit in 2.2.  Unicode strings are
usually stored as UCS-2, as 16-bit unsigned integers. Python 2.2 can also be
compiled to use UCS-4, 32-bit unsigned integers, as its internal encoding by
supplying @code{--enable-unicode=ucs4} to the configure script.   (It's also
possible to specify @code{--disable-unicode} to completely disable Unicode
support.)

When built to use UCS-4 (a "wide Python"), the interpreter can natively handle
Unicode characters from U+000000 to U+110000, so the range of legal values for
the @code{unichr()} function is expanded accordingly.  Using an interpreter
compiled to use UCS-2 (a "narrow Python"), values greater than 65535 will still
cause @code{unichr()} to raise a @ref{1ff,,ValueError} exception. This is all
described in 
@geindex Python Enhancement Proposals; PEP 261
PEP 261@footnote{https://peps.python.org/pep-0261/}, "Support for 'wide' Unicode characters"; consult it for
further details.

Another change is simpler to explain. Since their introduction, Unicode strings
have supported an @code{encode()} method to convert the string to a selected
encoding such as UTF-8 or Latin-1.  A symmetric @code{decode([*encoding*])}
method has been added to 8-bit strings (though not to Unicode strings) in 2.2.
@code{decode()} assumes that the string is in the specified encoding and decodes
it, returning whatever is returned by the codec.

Using this new feature, codecs have been added for tasks not directly related to
Unicode.  For example, codecs have been added for uu-encoding, MIME's base64
encoding, and compression with the @ref{132,,zlib} module:

@example
>>> s = """Here is a lengthy piece of redundant, overly verbose,
... and repetitive text.
... """
>>> data = s.encode('zlib')
>>> data
'x\x9c\r\xc9\xc1\r\x80 \x10\x04\xc0?Ul...'
>>> data.decode('zlib')
'Here is a lengthy piece of redundant, overly verbose,\nand repetitive text.\n'
>>> print s.encode('uu')
begin 666 <data>
M2&5R92!I<R!A(&QE;F=T:'D@@<&EE8V4@@;V8@@<F5D=6YD86YT+"!O=F5R;'D@@
>=F5R8F]S92P*86YD(')E<&5T:71I=F4@@=&5X="X*

end
>>> "sheesh".encode('rot-13')
'furrfu'
@end example

To convert a class instance to Unicode, a @code{__unicode__()} method can be
defined by a class, analogous to @code{__str__()}.

@code{encode()}, @code{decode()}, and @code{__unicode__()} were implemented by
Marc-André Lemburg.  The changes to support using UCS-4 internally were
implemented by Fredrik Lundh and Martin von Löwis.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 261

@item PEP 261@footnote{https://peps.python.org/pep-0261/} - Support for 'wide' Unicode characters

Written by Paul Prescod.
@end table


@c ======================================================================

@node PEP 227 Nested Scopes,New and Improved Modules<3>,Unicode Changes,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 pep-227-nested-scopes}@anchor{14ac}
@subsection PEP 227: Nested Scopes


In Python 2.1, statically nested scopes were added as an optional feature, to be
enabled by a @code{from __future__ import nested_scopes} directive.  In 2.2 nested
scopes no longer need to be specially enabled, and are now always present.  The
rest of this section is a copy of the description of nested scopes from my
"What's New in Python 2.1" document; if you read it when 2.1 came out, you can
skip the rest of this section.

The largest change introduced in Python 2.1, and made complete in 2.2, is to
Python's scoping rules.  In Python 2.0, at any given time there are at most
three namespaces used to look up variable names: local, module-level, and the
built-in namespace.  This often surprised people because it didn't match their
intuitive expectations.  For example, a nested recursive function definition
doesn't work:

@example
def f():
    ...
    def g(value):
        ...
        return g(value-1) + 1
    ...
@end example

The function @code{g()} will always raise a @ref{428,,NameError} exception, because
the binding of the name @code{g} isn't in either its local namespace or in the
module-level namespace.  This isn't much of a problem in practice (how often do
you recursively define interior functions like this?), but this also made using
the @ref{127a,,lambda} expression clumsier, and this was a problem in practice.
In code which uses @code{lambda} you can often find local variables being
copied by passing them as the default values of arguments.

@example
def find(self, name):
    "Return list of any entries equal to 'name'"
    L = filter(lambda x, name=name: x == name,
               self.list_attribute)
    return L
@end example

The readability of Python code written in a strongly functional style suffers
greatly as a result.

The most significant change to Python 2.2 is that static scoping has been added
to the language to fix this problem.  As a first effect, the @code{name=name}
default argument is now unnecessary in the above example.  Put simply, when a
given variable name is not assigned a value within a function (by an assignment,
or the @ref{140e,,def}, @ref{12b5,,class}, or @ref{5cc,,import} statements),
references to the variable will be looked up in the local namespace of the
enclosing scope.  A more detailed explanation of the rules, and a dissection of
the implementation, can be found in the PEP.

This change may cause some compatibility problems for code where the same
variable name is used both at the module level and as a local variable within a
function that contains further function definitions. This seems rather unlikely
though, since such code would have been pretty confusing to read in the first
place.

One side effect of the change is that the @code{from module import *} and
@code{exec} statements have been made illegal inside a function scope under
certain conditions.  The Python reference manual has said all along that @code{from
module import *} is only legal at the top level of a module, but the CPython
interpreter has never enforced this before.  As part of the implementation of
nested scopes, the compiler which turns Python source into bytecodes has to
generate different code to access variables in a containing scope.  @code{from
module import *} and @code{exec} make it impossible for the compiler to
figure this out, because they add names to the local namespace that are
unknowable at compile time. Therefore, if a function contains function
definitions or @ref{127a,,lambda} expressions with free variables, the compiler
will flag this by raising a @ref{18b,,SyntaxError} exception.

To make the preceding explanation a bit clearer, here's an example:

@example
x = 1
def f():
    # The next line is a syntax error
    exec 'x=2'
    def g():
        return x
@end example

Line 4 containing the @code{exec} statement is a syntax error, since
@code{exec} would define a new local variable named @code{x} whose value should
be accessed by @code{g()}.

This shouldn't be much of a limitation, since @code{exec} is rarely used in
most Python code (and when it is used, it's often a sign of a poor design
anyway).


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 227

@item PEP 227@footnote{https://peps.python.org/pep-0227/} - Statically Nested Scopes

Écrit et implémenté par Jeremy Hylton.
@end table


@c ======================================================================

@node New and Improved Modules<3>,Interpreter Changes and Fixes,PEP 227 Nested Scopes,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 new-and-improved-modules}@anchor{14ad}
@subsection New and Improved Modules



@itemize *

@item 
The @ref{12d,,xmlrpclib} module was contributed to the standard library by Fredrik
Lundh, providing support for writing XML-RPC clients.  XML-RPC is a simple
remote procedure call protocol built on top of HTTP and XML. For example, the
following snippet retrieves a list of RSS channels from the O'Reilly Network,
and then  lists the recent headlines for one channel:

@example
import xmlrpclib
s = xmlrpclib.Server(
      'http://www.oreillynet.com/meerkat/xml-rpc/server.php')
channels = s.meerkat.getChannels()
# channels is a list of dictionaries, like this:
# [@{'id': 4, 'title': 'Freshmeat Daily News'@}
#  @{'id': 190, 'title': '32Bits Online'@},
#  @{'id': 4549, 'title': '3DGamers'@}, ... ]

# Get the items for one channel
items = s.meerkat.getItems( @{'channel': 4@} )

# 'items' is another list of dictionaries, like this:
# [@{'link': 'http://freshmeat.net/releases/52719/',
#   'description': 'A utility which converts HTML to XSL FO.',
#   'title': 'html2fo 0.3 (Default)'@}, ... ]
@end example

The @ref{12e,,SimpleXMLRPCServer} module makes it easy to create straightforward
XML-RPC servers.  See @indicateurl{http://xmlrpc.scripting.com/} for more information about XML-RPC.

@item 
The new @ref{69,,hmac} module implements the HMAC algorithm described by
@geindex RFC; RFC 2104
RFC 2104@footnote{https://datatracker.ietf.org/doc/html/rfc2104.html}. (Contributed by Gerhard Häring.)

@item 
Several functions that originally returned lengthy tuples now return
pseudo-sequences that still behave like tuples but also have mnemonic attributes such
as @code{memberst_mtime} or @ref{14ae,,tm_year}. The enhanced functions include
@ref{48a,,stat()}, @ref{d79,,fstat()}, @ref{10dc,,statvfs()}, and @ref{d7a,,fstatvfs()} in the
@ref{a0,,os} module, and @ref{14af,,localtime()}, @ref{119d,,gmtime()}, and @ref{13e3,,strptime()} in
the @ref{ed,,time} module.

For example, to obtain a file's size using the old tuples, you'd end up writing
something like @code{file_size = os.stat(filename)[stat.ST_SIZE]}, but now this can
be written more clearly as @code{file_size = os.stat(filename).st_size}.

The original patch for this feature was contributed by Nick Mathewson.

@item 
The Python profiler has been extensively reworked and various errors in its
output have been corrected.  (Contributed by Fred L. Drake, Jr. and Tim Peters.)

@item 
The @ref{cb,,socket} module can be compiled to support IPv6; specify the
@code{--enable-ipv6} option to Python's configure script.  (Contributed by
Jun-ichiro "itojun" Hagino.)

@item 
Two new format characters were added to the @ref{d4,,struct} module for 64-bit
integers on platforms that support the C long long type.  @code{q} is for
a signed 64-bit integer, and @code{Q} is for an unsigned one.  The value is
returned in Python's long integer type.  (Contributed by Tim Peters.)

@item 
In the interpreter's interactive mode, there's a new built-in function
@ref{8c4,,help()} that uses the @ref{b4,,pydoc} module introduced in Python 2.1 to
provide interactive help. @code{help(object)} displays any available help text
about `object'.  @ref{8c4,,help()} with no argument puts you in an online help
utility, where you can enter the names of functions, classes, or modules to read
their help text. (Contributed by Guido van Rossum, using Ka-Ping Yee's
@ref{b4,,pydoc} module.)

@item 
Various bugfixes and performance improvements have been made to the SRE engine
underlying the @ref{b8,,re} module.  For example, the @ref{2a0,,re.sub()} and
@ref{29f,,re.split()} functions have been rewritten in C.  Another contributed patch
speeds up certain Unicode character ranges by a factor of two, and a new
@ref{14b0,,finditer()}  method that returns an iterator over all the non-overlapping
matches in  a given string.  (SRE is maintained by Fredrik Lundh.  The
BIGCHARSET patch was contributed by Martin von Löwis.)

@item 
The @ref{c9,,smtplib} module now supports 
@geindex RFC; RFC 2487
RFC 2487@footnote{https://datatracker.ietf.org/doc/html/rfc2487.html}, "Secure SMTP over TLS", so
it's now possible to encrypt the SMTP traffic between a Python program and the
mail transport agent being handed a message.  @ref{c9,,smtplib} also supports SMTP
authentication.  (Contributed by Gerhard Häring.)

@item 
The @ref{73,,imaplib} module, maintained by Piers Lauder, has support for several
new extensions: the NAMESPACE extension defined in 
@geindex RFC; RFC 2342
RFC 2342@footnote{https://datatracker.ietf.org/doc/html/rfc2342.html}, SORT, GETACL and
SETACL.  (Contributed by Anthony Baxter and Michel Pelletier.)

@item 
The @code{rfc822} module's parsing of email addresses is now compliant with
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}, an update to 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html}.  (The module's name is `not' going to be
changed to @code{rfc2822}.)  A new package, @ref{3b,,email}, has also been added for
parsing and generating e-mail messages.  (Contributed by Barry Warsaw, and
arising out of his work on Mailman.)

@item 
The @ref{37,,difflib} module now contains a new @code{Differ} class for
producing human-readable lists of changes (a "delta") between two sequences of
lines of text.  There are also two generator functions, @code{ndiff()} and
@code{restore()}, which respectively return a delta from two sequences, or one of
the original sequences from a delta. (Grunt work contributed by David Goodger,
from ndiff.py code by Tim Peters who then did the generatorization.)

@item 
New constants @code{ascii_letters}, @code{ascii_lowercase}, and
@code{ascii_uppercase} were added to the @ref{d2,,string} module.  There were
several modules in the standard library that used @code{string.letters} to
mean the ranges A-Za-z, but that assumption is incorrect when locales are in
use, because @code{string.letters} varies depending on the set of legal
characters defined by the current locale.  The buggy modules have all been fixed
to use @code{ascii_letters} instead. (Reported by an unknown person; fixed by
Fred L. Drake, Jr.)

@item 
The @ref{8e,,mimetypes} module now makes it easier to use alternative MIME-type
databases by the addition of a @ref{14b1,,MimeTypes} class, which takes a list of
filenames to be parsed.  (Contributed by Fred L. Drake, Jr.)

@item 
A @ref{1139,,Timer} class was added to the @ref{ec,,threading} module that allows
scheduling an activity to happen at some future time.  (Contributed by Itamar
Shtull-Trauring.)
@end itemize

@c ======================================================================

@node Interpreter Changes and Fixes,Autres changements et corrections<3>,New and Improved Modules<3>,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 interpreter-changes-and-fixes}@anchor{14b2}
@subsection Interpreter Changes and Fixes


Some of the changes only affect people who deal with the Python interpreter at
the C level because they're writing Python extension modules, embedding the
interpreter, or just hacking on the interpreter itself. If you only write Python
code, none of the changes described here will affect you very much.


@itemize *

@item 
Profiling and tracing functions can now be implemented in C, which can operate
at much higher speeds than Python-based functions and should reduce the overhead
of profiling and tracing.  This  will be of interest to authors of development
environments for Python.  Two new C functions were added to Python's API,
@ref{14b3,,PyEval_SetProfile()} and @ref{14b4,,PyEval_SetTrace()}. The existing
@ref{14b5,,sys.setprofile()} and @ref{14b6,,sys.settrace()} functions still exist, and have
simply been changed to use the new C-level interface.  (Contributed by Fred L.
Drake, Jr.)

@item 
Another low-level API, primarily of interest to implementers of Python
debuggers and development tools, was added. @ref{14b7,,PyInterpreterState_Head()} and
@ref{14b8,,PyInterpreterState_Next()} let a caller walk through all the existing
interpreter objects; @ref{14b9,,PyInterpreterState_ThreadHead()} and
@ref{14ba,,PyThreadState_Next()} allow looping over all the thread states for a given
interpreter.  (Contributed by David Beazley.)

@item 
The C-level interface to the garbage collector has been changed to make it
easier to write extension types that support garbage collection and to debug
misuses of the functions. Various functions have slightly different semantics,
so a bunch of functions had to be renamed.  Extensions that use the old API will
still compile but will `not' participate in garbage collection, so updating them
for 2.2 should be considered fairly high priority.

To upgrade an extension module to the new API, perform the following steps:

@item 
Rename @code{Py_TPFLAGS_GC} to @ref{767,,Py_TPFLAGS_HAVE_GC}.

@item 

@table @asis

@item Use @ref{a90,,PyObject_GC_New()} or @ref{a91,,PyObject_GC_NewVar()} to allocate

objects, and @ref{14bb,,PyObject_GC_Del()} to deallocate them.
@end table

@item 
Rename @code{PyObject_GC_Init()} to @ref{14bc,,PyObject_GC_Track()} and
@code{PyObject_GC_Fini()} to @ref{14bd,,PyObject_GC_UnTrack()}.

@item 
Remove @code{PyGC_HEAD_SIZE} from object size calculations.

@item 
Remove calls to @code{PyObject_AS_GC()} and @code{PyObject_FROM_GC()}.

@item 
A new @code{et} format sequence was added to @ref{55d,,PyArg_ParseTuple()}; @code{et}
takes both a parameter and an encoding name, and converts the parameter to the
given encoding if the parameter turns out to be a Unicode string, or leaves it
alone if it's an 8-bit string, assuming it to already be in the desired
encoding.  This differs from the @code{es} format character, which assumes that
8-bit strings are in Python's default ASCII encoding and converts them to the
specified new encoding. (Contributed by M.-A. Lemburg, and used for the MBCS
support on Windows described in the following section.)

@item 
A different argument parsing function, @ref{14be,,PyArg_UnpackTuple()}, has been
added that's simpler and presumably faster.  Instead of specifying a format
string, the caller simply gives the minimum and maximum number of arguments
expected, and a set of pointers to @ref{32f,,PyObject}* variables that will be
filled in with argument values.

@item 
Two new flags @ref{148a,,METH_NOARGS} and @ref{14bf,,METH_O} are available in method
definition tables to simplify implementation of methods with no arguments or a
single untyped argument. Calling such methods is more efficient than calling a
corresponding method that uses @ref{14c0,,METH_VARARGS}.  Also, the old
@code{METH_OLDARGS} style of writing C methods is  now officially deprecated.

@item 
Two new wrapper functions, @ref{14c1,,PyOS_snprintf()} and @ref{14c2,,PyOS_vsnprintf()}
were added to provide  cross-platform implementations for the relatively new
@code{snprintf()} and @code{vsnprintf()} C lib APIs. In contrast to the standard
@code{sprintf()} and @code{vsprintf()} functions, the Python versions check the
bounds of the buffer used to protect against buffer overruns. (Contributed by
M.-A. Lemburg.)

@item 
The @ref{14c3,,_PyTuple_Resize()} function has lost an unused parameter, so now it
takes 2 parameters instead of 3.  The third argument was never used, and can
simply be discarded when porting code from earlier versions to Python 2.2.
@end itemize

@c ======================================================================

@node Autres changements et corrections<3>,Remerciements<6>,Interpreter Changes and Fixes,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 other-changes-and-fixes}@anchor{14c4}
@subsection Autres changements et corrections


As usual there were a bunch of other improvements and bugfixes scattered
throughout the source tree.  A search through the CVS change logs finds there
were 527 patches applied and 683 bugs fixed between Python 2.1 and 2.2; 2.2.1
applied 139 patches and fixed 143 bugs; 2.2.2 applied 106 patches and fixed 82
bugs.  These figures are likely to be underestimates.

Some of the more notable changes are:


@itemize *

@item 
The code for the MacOS port for Python, maintained by Jack Jansen, is now kept
in the main Python CVS tree, and many changes have been made to support MacOS X.

The most significant change is the ability to build Python as a framework,
enabled by supplying the @code{--enable-framework} option to the configure
script when compiling Python.  According to Jack Jansen, "This installs a
self-contained Python installation plus the OS X framework "glue" into
@code{/Library/Frameworks/Python.framework} (or another location of choice).
For now there is little immediate added benefit to this (actually, there is the
disadvantage that you have to change your PATH to be able to find Python), but
it is the basis for creating a full-blown Python application, porting the
MacPython IDE, possibly using Python as a standard OSA scripting language and
much more."

Most of the MacPython toolbox modules, which interface to MacOS APIs such as
windowing, QuickTime, scripting, etc. have been ported to OS X, but they've been
left commented out in @code{setup.py}.  People who want to experiment with
these modules can uncomment them manually.

@c Jack's original comments:
@c The main change is the possibility to build Python as a
@c framework. This installs a self-contained Python installation plus the
@c OSX framework "glue" into /Library/Frameworks/Python.framework (or
@c another location of choice). For now there is little immediate added
@c benefit to this (actually, there is the disadvantage that you have to
@c change your PATH to be able to find Python), but it is the basis for
@c creating a fullblown Python application, porting the MacPython IDE,
@c possibly using Python as a standard OSA scripting language and much
@c more. You enable this with "configure --enable-framework".
@c The other change is that most MacPython toolbox modules, which
@c interface to all the MacOS APIs such as windowing, quicktime,
@c scripting, etc. have been ported. Again, most of these are not of
@c immediate use, as they need a full application to be really useful, so
@c they have been commented out in setup.py. People wanting to experiment
@c can uncomment them. Gestalt and Internet Config modules are enabled by
@c default.

@item 
Keyword arguments passed to built-in functions that don't take them now cause a
@ref{522,,TypeError} exception to be raised, with the message "`function' takes no
keyword arguments".

@item 
Weak references, added in Python 2.1 as an extension module, are now part of
the core because they're used in the implementation of new-style classes.  The
@ref{14c5,,ReferenceError} exception has therefore moved from the @ref{113,,weakref}
module to become a built-in exception.

@item 
A new script, @code{Tools/scripts/cleanfuture.py} by Tim Peters,
automatically removes obsolete @code{__future__} statements from Python source
code.

@item 
An additional `flags' argument has been added to the built-in function
@ref{190,,compile()}, so the behaviour of @code{__future__} statements can now be
correctly observed in simulated shells, such as those presented by IDLE and
other development environments.  This is described in 
@geindex Python Enhancement Proposals; PEP 264
PEP 264@footnote{https://peps.python.org/pep-0264/}. (Contributed
by Michael Hudson.)

@item 
The new license introduced with Python 1.6 wasn't GPL-compatible.  This is
fixed by some minor textual changes to the 2.2 license, so it's now legal to
embed Python inside a GPLed program again.  Note that Python itself is not
GPLed, but instead is under a license that's essentially equivalent to the BSD
license, same as it always was.  The license changes were also applied to the
Python 2.0.1 and 2.1.1 releases.

@item 
When presented with a Unicode filename on Windows, Python will now convert it
to an MBCS encoded string, as used by the Microsoft file APIs.  As MBCS is
explicitly used by the file APIs, Python's choice of ASCII as the default
encoding turns out to be an annoyance.  On Unix, the locale's character set is
used if @code{locale.nl_langinfo(CODESET)} is available.  (Windows support was
contributed by Mark Hammond with assistance from Marc-André Lemburg. Unix
support was added by Martin von Löwis.)

@item 
Large file support is now enabled on Windows.  (Contributed by Tim Peters.)

@item 
The @code{Tools/scripts/ftpmirror.py} script now parses a @code{.netrc}
file, if you have one. (Contributed by Mike Romberg.)

@item 
Some features of the object returned by the @code{xrange()} function are now
deprecated, and trigger warnings when they're accessed; they'll disappear in
Python 2.3. @code{xrange} objects tried to pretend they were full sequence
types by supporting slicing, sequence multiplication, and the @ref{2e8,,in}
operator, but these features were rarely used and therefore buggy.  The
@code{tolist()} method and the @code{start}, @code{stop}, and @code{step}
attributes are also being deprecated.  At the C level, the fourth argument to
the @code{PyRange_New()} function, @code{repeat}, has also been deprecated.

@item 
There were a bunch of patches to the dictionary implementation, mostly to fix
potential core dumps if a dictionary contains objects that sneakily changed
their hash value, or mutated the dictionary they were contained in. For a while
python-dev fell into a gentle rhythm of Michael Hudson finding a case that
dumped core, Tim Peters fixing the bug, Michael finding another case, and round
and round it went.

@item 
On Windows, Python can now be compiled with Borland C thanks to a number of
patches contributed by Stephen Hansen, though the result isn't fully functional
yet.  (But this `is' progress...)

@item 
Another Windows enhancement: Wise Solutions generously offered PythonLabs use
of their InstallerMaster 8.1 system.  Earlier PythonLabs Windows installers used
Wise 5.0a, which was beginning to show its age.  (Packaged up by Tim Peters.)

@item 
Files ending in @code{.pyw} can now be imported on Windows. @code{.pyw} is a
Windows-only thing, used to indicate that a script needs to be run using
PYTHONW.EXE instead of PYTHON.EXE in order to prevent a DOS console from popping
up to display the output.  This patch makes it possible to import such scripts,
in case they're also usable as modules.  (Implemented by David Bolen.)

@item 
On platforms where Python uses the C @code{dlopen()} function  to load
extension modules, it's now possible to set the flags used  by @code{dlopen()}
using the @ref{14c6,,sys.getdlopenflags()} and @ref{10ff,,sys.setdlopenflags()} functions.
(Contributed by Bram Stolk.)

@item 
The @ref{9c0,,pow()} built-in function no longer supports 3 arguments when
floating-point numbers are supplied. @code{pow(x, y, z)} returns @code{(x**y) % z},
but this is never useful for floating-point numbers, and the final result varies
unpredictably depending on the platform.  A call such as @code{pow(2.0, 8.0, 7.0)}
will now raise a @ref{522,,TypeError} exception.
@end itemize

@c ======================================================================

@node Remerciements<6>,,Autres changements et corrections<3>,Nouveautés de Python 2 2
@anchor{whatsnew/2 2 acknowledgements}@anchor{14c7}
@subsection Remerciements


The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Fred Bremmer,
Keith Briggs, Andrew Dalke, Fred L. Drake, Jr., Carel Fellinger, David Goodger,
Mark Hammond, Stephen Hansen, Michael Hudson, Jack Jansen, Marc-André Lemburg,
Martin von Löwis, Fredrik Lundh, Michael McLay, Nick Mathewson, Paul Moore,
Gustavo Niemeyer, Don O'Donnell, Joonas Paalasma, Tim Peters, Jens Quade, Tom
Reinhardt, Neil Schemenauer, Guido van Rossum, Greg Ward, Edward Welbourne.

@node Nouveautés de Python 2 1,Nouveautés de Python 2 0,Nouveautés de Python 2 2,Nouveautés de Python
@anchor{whatsnew/2 1 doc}@anchor{14c8}@anchor{whatsnew/2 1 what-s-new-in-python-2-1}@anchor{14c9}
@section Nouveautés de Python 2.1


@*Auteur: 
A.M. Kuchling


@c $Id: whatsnew21.tex 50964 2006-07-30 03:03:43Z fred.drake $

@menu
* Introduction: Introduction<2>. 
* PEP 227; Nested Scopes: PEP 227 Nested Scopes<2>. 
* PEP 236 ; Directives __future__: PEP 236 Directives __future__. 
* PEP 207; Rich Comparisons: PEP 207 Rich Comparisons. 
* PEP 230; Warning Framework: PEP 230 Warning Framework. 
* PEP 229; New Build System: PEP 229 New Build System. 
* PEP 205; Weak References: PEP 205 Weak References. 
* PEP 232 ; Attributs de fonctions: PEP 232 Attributs de fonctions. 
* PEP 235; Importing Modules on Case-Insensitive Platforms: PEP 235 Importing Modules on Case-Insensitive Platforms. 
* PEP 217; Interactive Display Hook: PEP 217 Interactive Display Hook. 
* PEP 208; New Coercion Model: PEP 208 New Coercion Model. 
* PEP 241; Metadata in Python Packages: PEP 241 Metadata in Python Packages. 
* New and Improved Modules: New and Improved Modules<4>. 
* Autres changements et corrections: Autres changements et corrections<4>. 
* Remerciements: Remerciements<7>. 

@end menu

@node Introduction<2>,PEP 227 Nested Scopes<2>,,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 introduction}@anchor{14ca}
@subsection Introduction


This article explains the new features in Python 2.1.  While there aren't as
many changes in 2.1 as there were in Python 2.0, there are still some pleasant
surprises in store.  2.1 is the first release to be steered through the use of
Python Enhancement Proposals, or PEPs, so most of the sizable changes have
accompanying PEPs that provide more complete documentation and a design
rationale for the change.  This article doesn't attempt to document the new
features completely, but simply provides an overview of the new features for
Python programmers. Refer to the Python 2.1 documentation, or to the specific
PEP, for more details about any new feature that particularly interests you.

One recent goal of the Python development team has been to accelerate the pace
of new releases, with a new release coming every 6 to 9 months. 2.1 is the first
release to come out at this faster pace, with the first alpha appearing in
January, 3 months after the final version of 2.0 was released.

The final release of Python 2.1 was made on April 17, 2001.

@c ======================================================================

@node PEP 227 Nested Scopes<2>,PEP 236 Directives __future__,Introduction<2>,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-227-nested-scopes}@anchor{14cb}
@subsection PEP 227: Nested Scopes


The largest change in Python 2.1 is to Python's scoping rules.  In Python 2.0,
at any given time there are at most three namespaces used to look up variable
names: local, module-level, and the built-in namespace.  This often surprised
people because it didn't match their intuitive expectations.  For example, a
nested recursive function definition doesn't work:

@example
def f():
    ...
    def g(value):
        ...
        return g(value-1) + 1
    ...
@end example

The function @code{g()} will always raise a @ref{428,,NameError} exception, because
the binding of the name @code{g} isn't in either its local namespace or in the
module-level namespace.  This isn't much of a problem in practice (how often do
you recursively define interior functions like this?), but this also made using
the @ref{127a,,lambda} expression clumsier, and this was a problem in practice.
In code which uses @ref{127a,,lambda} you can often find local variables being
copied by passing them as the default values of arguments.

@example
def find(self, name):
    "Return list of any entries equal to 'name'"
    L = filter(lambda x, name=name: x == name,
               self.list_attribute)
    return L
@end example

The readability of Python code written in a strongly functional style suffers
greatly as a result.

The most significant change to Python 2.1 is that static scoping has been added
to the language to fix this problem.  As a first effect, the @code{name=name}
default argument is now unnecessary in the above example.  Put simply, when a
given variable name is not assigned a value within a function (by an assignment,
or the @ref{140e,,def}, @ref{12b5,,class}, or @ref{5cc,,import} statements),
references to the variable will be looked up in the local namespace of the
enclosing scope.  A more detailed explanation of the rules, and a dissection of
the implementation, can be found in the PEP.

This change may cause some compatibility problems for code where the same
variable name is used both at the module level and as a local variable within a
function that contains further function definitions. This seems rather unlikely
though, since such code would have been pretty confusing to read in the first
place.

One side effect of the change is that the @code{from module import *} and
@code{exec} statements have been made illegal inside a function scope under
certain conditions.  The Python reference manual has said all along that @code{from
module import *} is only legal at the top level of a module, but the CPython
interpreter has never enforced this before.  As part of the implementation of
nested scopes, the compiler which turns Python source into bytecodes has to
generate different code to access variables in a containing scope.  @code{from
module import *} and @code{exec} make it impossible for the compiler to
figure this out, because they add names to the local namespace that are
unknowable at compile time. Therefore, if a function contains function
definitions or @ref{127a,,lambda} expressions with free variables, the compiler
will flag this by raising a @ref{18b,,SyntaxError} exception.

To make the preceding explanation a bit clearer, here's an example:

@example
x = 1
def f():
    # The next line is a syntax error
    exec 'x=2'
    def g():
        return x
@end example

Line 4 containing the @code{exec} statement is a syntax error, since
@code{exec} would define a new local variable named @code{x} whose value should
be accessed by @code{g()}.

This shouldn't be much of a limitation, since @code{exec} is rarely used in
most Python code (and when it is used, it's often a sign of a poor design
anyway).

Compatibility concerns have led to nested scopes being introduced gradually; in
Python 2.1, they aren't enabled by default, but can be turned on within a module
by using a future statement as described in 
@geindex Python Enhancement Proposals; PEP 236
PEP 236@footnote{https://peps.python.org/pep-0236/}.  (See the following section
for further discussion of 
@geindex Python Enhancement Proposals; PEP 236
PEP 236@footnote{https://peps.python.org/pep-0236/}.)  In Python 2.2, nested scopes will become
the default and there will be no way to turn them off, but users will have had
all of 2.1's lifetime to fix any breakage resulting from their introduction.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 227

@item PEP 227@footnote{https://peps.python.org/pep-0227/} - Statically Nested Scopes

Écrit et implémenté par Jeremy Hylton.
@end table


@c ======================================================================

@node PEP 236 Directives __future__,PEP 207 Rich Comparisons,PEP 227 Nested Scopes<2>,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-236-future-directives}@anchor{14cc}
@subsection PEP 236 : Directives @code{__future__}


The reaction to nested scopes was widespread concern about the dangers of
breaking code with the 2.1 release, and it was strong enough to make the
Pythoneers take a more conservative approach.  This approach consists of
introducing a convention for enabling optional functionality in release N that
will become compulsory in release N+1.

The syntax uses a @code{from...import} statement using the reserved module name
@ref{0,,__future__}.  Nested scopes can be enabled by the following statement:

@example
from __future__ import nested_scopes
@end example

While it looks like a normal @ref{5cc,,import} statement, it's not; there are
strict rules on where such a future statement can be put. They can only be at
the top of a module, and must precede any Python code or regular
@code{import} statements.  This is because such statements can affect how
the Python bytecode compiler parses code and generates bytecode, so they must
precede any statement that will result in bytecodes being produced.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} -- Retour vers le @ref{0,,__future__}

Écrit par Tim Peters, et implémenté principalement par Jeremy Hylton.
@end table


@c ======================================================================

@node PEP 207 Rich Comparisons,PEP 230 Warning Framework,PEP 236 Directives __future__,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-207-rich-comparisons}@anchor{14cd}
@subsection PEP 207: Rich Comparisons


In earlier versions, Python's support for implementing comparisons on user-defined
classes and extension types was quite simple. Classes could implement a
@code{__cmp__()} method that was given two instances of a class, and could only
return 0 if they were equal or +1 or -1 if they weren't; the method couldn't
raise an exception or return anything other than a Boolean value.  Users of
Numeric Python often found this model too weak and restrictive, because in the
number-crunching programs that numeric Python is used for, it would be more
useful to be able to perform elementwise comparisons of two matrices, returning
a matrix containing the results of a given comparison for each element.  If the
two matrices are of different sizes, then the compare has to be able to raise an
exception to signal the error.

In Python 2.1, rich comparisons were added in order to support this need.
Python classes can now individually overload each of the @code{<}, @code{<=}, @code{>},
@code{>=}, @code{==}, and @code{!=} operations.  The new magic method names are:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Nom de méthode

@item

@code{<}

@tab

@ref{127d,,__lt__()}

@item

@code{<=}

@tab

@ref{12e9,,__le__()}

@item

@code{>}

@tab

@ref{12ea,,__gt__()}

@item

@code{>=}

@tab

@ref{12eb,,__ge__()}

@item

@code{==}

@tab

@ref{ae8,,__eq__()}

@item

@code{!=}

@tab

@ref{14ce,,__ne__()}

@end multitable


(The magic methods are named after the corresponding Fortran operators @code{.LT.}.
@code{.LE.}, &c.  Numeric programmers are almost certainly quite familiar with
these names and will find them easy to remember.)

Each of these magic methods is of the form @code{method(self, other)}, where
@code{self} will be the object on the left-hand side of the operator, while
@code{other} will be the object on the right-hand side.  For example, the
expression @code{A < B} will cause @code{A.__lt__(B)} to be called.

Each of these magic methods can return anything at all: a Boolean, a matrix, a
list, or any other Python object.  Alternatively they can raise an exception if
the comparison is impossible, inconsistent, or otherwise meaningless.

The built-in @code{cmp(A,B)} function can use the rich comparison machinery,
and now accepts an optional argument specifying which comparison operation to
use; this is given as one of the strings @code{"<"}, @code{"<="}, @code{">"}, @code{">="},
@code{"=="}, or @code{"!="}.  If called without the optional third argument,
@code{cmp()} will only return -1, 0, or +1 as in previous versions of Python;
otherwise it will call the appropriate method and can return any Python object.

There are also corresponding changes of interest to C programmers; there's a new
slot @code{tp_richcmp} in type objects and an API for performing a given rich
comparison.  I won't cover the C API here, but will refer you to 
@geindex Python Enhancement Proposals; PEP 207
PEP 207@footnote{https://peps.python.org/pep-0207/}, or to
2.1's C API documentation, for the full list of related functions.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 207

@item PEP 207@footnote{https://peps.python.org/pep-0207/} - Rich Comparisons

Written by Guido van Rossum, heavily based on earlier work by David Ascher, and
implemented by Guido van Rossum.
@end table


@c ======================================================================

@node PEP 230 Warning Framework,PEP 229 New Build System,PEP 207 Rich Comparisons,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-230-warning-framework}@anchor{14cf}
@subsection PEP 230: Warning Framework


Over its 10 years of existence, Python has accumulated a certain number of
obsolete modules and features along the way.  It's difficult to know when a
feature is safe to remove, since there's no way of knowing how much code uses it
--- perhaps no programs depend on the feature, or perhaps many do.  To enable
removing old features in a more structured way, a warning framework was added.
When the Python developers want to get rid of a feature, it will first trigger a
warning in the next version of Python.  The following Python version can then
drop the feature, and users will have had a full release cycle to remove uses of
the old feature.

Python 2.1 adds the warning framework to be used in this scheme.  It adds a
@ref{111,,warnings} module that provide functions to issue warnings, and to filter
out warnings that you don't want to be displayed. Third-party modules can also
use this framework to deprecate old features that they no longer wish to
support.

For example, in Python 2.1 the @code{regex} module is deprecated, so importing
it causes a warning to be printed:

@example
>>> import regex
__main__:1: DeprecationWarning: the regex module
         is deprecated; please use the re module
>>>
@end example

Warnings can be issued by calling the @ref{14d0,,warnings.warn()} function:

@example
warnings.warn("feature X no longer supported")
@end example

The first parameter is the warning message; an additional optional parameters
can be used to specify a particular warning category.

Filters can be added to disable certain warnings; a regular expression pattern
can be applied to the message or to the module name in order to suppress a
warning.  For example, you may have a program that uses the @code{regex} module
and not want to spare the time to convert it to use the @ref{b8,,re} module right
now.  The warning can be suppressed by calling

@example
import warnings
warnings.filterwarnings(action = 'ignore',
                        message='.*regex module is deprecated',
                        category=DeprecationWarning,
                        module = '__main__')
@end example

This adds a filter that will apply only to warnings of the class
@ref{1a3,,DeprecationWarning} triggered in the @ref{1,,__main__} module, and applies
a regular expression to only match the message about the @code{regex} module
being deprecated, and will cause such warnings to be ignored.  Warnings can also
be printed only once, printed every time the offending code is executed, or
turned into exceptions that will cause the program to stop (unless the
exceptions are caught in the usual way, of course).

Functions were also added to Python's C API for issuing warnings; refer to PEP
230 or to Python's API documentation for the details.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 5

@item PEP 5@footnote{https://peps.python.org/pep-0005/} - Guidelines for Language Evolution

Written by Paul Prescod, to specify procedures to be followed when removing old
features from Python.  The policy described in this PEP hasn't been officially
adopted, but the eventual policy probably won't be too different from Prescod's
proposal.

@geindex Python Enhancement Proposals; PEP 230

@item PEP 230@footnote{https://peps.python.org/pep-0230/} - Warning Framework

Written and implemented by Guido van Rossum.
@end table


@c ======================================================================

@node PEP 229 New Build System,PEP 205 Weak References,PEP 230 Warning Framework,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-229-new-build-system}@anchor{14d1}
@subsection PEP 229: New Build System


When compiling Python, the user had to go in and edit the @code{Modules/Setup}
file in order to enable various additional modules; the default set is
relatively small and limited to modules that compile on most Unix platforms.
This means that on Unix platforms with many more features, most notably Linux,
Python installations often don't contain all useful modules they could.

Python 2.0 added the Distutils, a set of modules for distributing and installing
extensions.  In Python 2.1, the Distutils are used to compile much of the
standard library of extension modules, autodetecting which ones are supported on
the current machine.  It's hoped that this will make Python installations easier
and more featureful.

Instead of having to edit the @code{Modules/Setup} file in order to enable
modules, a @code{setup.py} script in the top directory of the Python source
distribution is run at build time, and attempts to discover which modules can be
enabled by examining the modules and header files on the system.  If a module is
configured in @code{Modules/Setup}, the @code{setup.py} script won't attempt
to compile that module and will defer to the @code{Modules/Setup} file's
contents.  This provides a way to specific any strange command-line flags or
libraries that are required for a specific platform.

In another far-reaching change to the build mechanism, Neil Schemenauer
restructured things so Python now uses a single makefile that isn't recursive,
instead of makefiles in the top directory and in each of the @code{Python/},
@code{Parser/}, @code{Objects/}, and @code{Modules/} subdirectories.  This
makes building Python faster and also makes hacking the Makefiles clearer and
simpler.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 229

@item PEP 229@footnote{https://peps.python.org/pep-0229/} - Using Distutils to Build Python

Written and implemented by A.M. Kuchling.
@end table


@c ======================================================================

@node PEP 205 Weak References,PEP 232 Attributs de fonctions,PEP 229 New Build System,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-205-weak-references}@anchor{14d2}
@subsection PEP 205: Weak References


Weak references, available through the @ref{113,,weakref} module, are a minor but
useful new data type in the Python programmer's toolbox.

Storing a reference to an object (say, in a dictionary or a list) has the side
effect of keeping that object alive forever.  There are a few specific cases
where this behaviour is undesirable, object caches being the most common one,
and another being circular references in data structures such as trees.

For example, consider a memoizing function that caches the results of another
function @code{f(x)} by storing the function's argument and its result in a
dictionary:

@example
_cache = @{@}
def memoize(x):
    if _cache.has_key(x):
        return _cache[x]

    retval = f(x)

    # Cache the returned object
    _cache[x] = retval

    return retval
@end example

This version works for simple things such as integers, but it has a side effect;
the @code{_cache} dictionary holds a reference to the return values, so they'll
never be deallocated until the Python process exits and cleans up. This isn't
very noticeable for integers, but if @code{f()} returns an object, or a data
structure that takes up a lot of memory, this can be a problem.

Weak references provide a way to implement a cache that won't keep objects alive
beyond their time.  If an object is only accessible through weak references, the
object will be deallocated and the weak references will now indicate that the
object it referred to no longer exists.  A weak reference to an object `obj' is
created by calling @code{wr = weakref.ref(obj)}.  The object being referred to is
returned by calling the weak reference as if it were a function: @code{wr()}.  It
will return the referenced object, or @code{None} if the object no longer exists.

This makes it possible to write a @code{memoize()} function whose cache doesn't
keep objects alive, by storing weak references in the cache.

@example
_cache = @{@}
def memoize(x):
    if _cache.has_key(x):
        obj = _cache[x]()
        # If weak reference object still exists,
        # return it
        if obj is not None: return obj

    retval = f(x)

    # Cache a weak reference
    _cache[x] = weakref.ref(retval)

    return retval
@end example

The @ref{113,,weakref} module also allows creating proxy objects which behave like
weak references --- an object referenced only by proxy objects is deallocated --
but instead of requiring an explicit call to retrieve the object, the proxy
transparently forwards all operations to the object as long as the object still
exists.  If the object is deallocated, attempting to use a proxy will cause a
@code{weakref.ReferenceError} exception to be raised.

@example
proxy = weakref.proxy(obj)
proxy.attr   # Equivalent to obj.attr
proxy.meth() # Equivalent to obj.meth()
del obj
proxy.attr   # raises weakref.ReferenceError
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 205

@item PEP 205@footnote{https://peps.python.org/pep-0205/} - Weak References

Écrit et implémenté par Fred L. Drake, Jr.
@end table


@c ======================================================================

@node PEP 232 Attributs de fonctions,PEP 235 Importing Modules on Case-Insensitive Platforms,PEP 205 Weak References,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-232-function-attributes}@anchor{14d3}
@subsection PEP 232 : Attributs de fonctions


In Python 2.1, functions can now have arbitrary information attached to them.
People were often using docstrings to hold information about functions and
methods, because the @ref{11b6,,__doc__} attribute was the only way of
attaching any
information to a function.  For example, in the Zope web application server,
functions are marked as safe for public access by having a docstring, and in
John Aycock's SPARK parsing framework, docstrings hold parts of the BNF grammar
to be parsed.  This overloading is unfortunate, since docstrings are really
intended to hold a function's documentation; for example, it means you can't
properly document functions intended for private use in Zope.

Arbitrary attributes can now be set and retrieved on functions using the regular
Python syntax:

@example
def f(): pass

f.publish = 1
f.secure = 1
f.grammar = "A ::= B (C D)*"
@end example

The dictionary containing attributes can be accessed as the function's
@ref{12b0,,__dict__}. Unlike the @ref{c4b,,__dict__} attribute of class instances, in
functions you can actually assign a new dictionary to @ref{12b0,,__dict__}, though
the new value is restricted to a regular Python dictionary; you `can't' be
tricky and set it to a @code{UserDict} instance, or any other random object
that behaves like a mapping.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 232

@item PEP 232@footnote{https://peps.python.org/pep-0232/} -- Attributs de fonctions

Écrit et implémenté par Barry Warsaw.
@end table


@c ======================================================================

@node PEP 235 Importing Modules on Case-Insensitive Platforms,PEP 217 Interactive Display Hook,PEP 232 Attributs de fonctions,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-235-importing-modules-on-case-insensitive-platforms}@anchor{14d4}
@subsection PEP 235: Importing Modules on Case-Insensitive Platforms


Some operating systems have filesystems that are case-insensitive, MacOS and
Windows being the primary examples; on these systems, it's impossible to
distinguish the filenames @code{FILE.PY} and @code{file.py}, even though they do store
the file's name  in its original case (they're case-preserving, too).

In Python 2.1, the @ref{5cc,,import} statement will work to simulate case-sensitivity
on case-insensitive platforms.  Python will now search for the first
case-sensitive match by default, raising an @ref{40f,,ImportError} if no such file
is found, so @code{import file} will not import a module named @code{FILE.PY}.
Case-insensitive matching can be requested by setting the 
@geindex PYTHONCASEOK
@geindex variable d'environnement; PYTHONCASEOK
@ref{949,,PYTHONCASEOK}
environment variable before starting the Python interpreter.

@c ======================================================================

@node PEP 217 Interactive Display Hook,PEP 208 New Coercion Model,PEP 235 Importing Modules on Case-Insensitive Platforms,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-217-interactive-display-hook}@anchor{14d5}
@subsection PEP 217: Interactive Display Hook


When using the Python interpreter interactively, the output of commands is
displayed using the built-in @ref{7e7,,repr()} function. In Python 2.1, the variable
@ref{14d6,,sys.displayhook()} can be set to a callable object which will be called
instead of @ref{7e7,,repr()}. For example, you can set it to a special
pretty-printing function:

@example
>>> # Create a recursive data structure
... L = [1,2,3]
>>> L.append(L)
>>> L # Show Python's default output
[1, 2, 3, [...]]
>>> # Use pprint.pprint() as the display function
... import sys, pprint
>>> sys.displayhook = pprint.pprint
>>> L
[1, 2, 3,  <Recursion on list with id=135143996>]
>>>
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 217

@item PEP 217@footnote{https://peps.python.org/pep-0217/} - Display Hook for Interactive Use

Written and implemented by Moshe Zadka.
@end table


@c ======================================================================

@node PEP 208 New Coercion Model,PEP 241 Metadata in Python Packages,PEP 217 Interactive Display Hook,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-208-new-coercion-model}@anchor{14d7}
@subsection PEP 208: New Coercion Model


How numeric coercion is done at the C level was significantly modified.  This
will only affect the authors of C extensions to Python, allowing them more
flexibility in writing extension types that support numeric operations.

Extension types can now set the type flag @code{Py_TPFLAGS_CHECKTYPES} in their
@code{PyTypeObject} structure to indicate that they support the new coercion model.
In such extension types, the numeric slot functions can no longer assume that
they'll be passed two arguments of the same type; instead they may be passed two
arguments of differing types, and can then perform their own internal coercion.
If the slot function is passed a type it can't handle, it can indicate the
failure by returning a reference to the @code{Py_NotImplemented} singleton value.
The numeric functions of the other type will then be tried, and perhaps they can
handle the operation; if the other type also returns @code{Py_NotImplemented}, then
a @ref{522,,TypeError} will be raised.  Numeric methods written in Python can also
return @code{Py_NotImplemented}, causing the interpreter to act as if the method
did not exist (perhaps raising a @ref{522,,TypeError}, perhaps trying another
object's numeric methods).


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 208

@item PEP 208@footnote{https://peps.python.org/pep-0208/} - Reworking the Coercion Model

Written and implemented by Neil Schemenauer, heavily based upon earlier work by
Marc-André Lemburg.  Read this to understand the fine points of how numeric
operations will now be processed at the C level.
@end table


@c ======================================================================

@node PEP 241 Metadata in Python Packages,New and Improved Modules<4>,PEP 208 New Coercion Model,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 pep-241-metadata-in-python-packages}@anchor{14d8}
@subsection PEP 241: Metadata in Python Packages


A common complaint from Python users is that there's no single catalog of all
the Python modules in existence.  T. Middleton's Vaults of Parnassus at
@code{www.vex.net/parnassus/} (retired in February 2009, available in the Internet Archive Wayback Machine@footnote{https://web.archive.org/web/20090130140102/http://www.vex.net/parnassus/})
was the largest catalog of Python modules, but
registering software at the Vaults is optional, and many people did not bother.

As a first small step toward fixing the problem, Python software packaged using
the Distutils @code{sdist} command will include a file named
@code{PKG-INFO} containing information about the package such as its name,
version, and author (metadata, in cataloguing terminology).  
@geindex Python Enhancement Proposals; PEP 241
PEP 241@footnote{https://peps.python.org/pep-0241/} contains
the full list of fields that can be present in the @code{PKG-INFO} file.  As
people began to package their software using Python 2.1, more and more packages
will include metadata, making it possible to build automated cataloguing systems
and experiment with them.  With the result experience, perhaps it'll be possible
to design a really good catalog and then build support for it into Python 2.2.
For example, the Distutils @code{sdist} and @code{bdist_*} commands
could support an @code{upload} option that would automatically upload your
package to a catalog server.

You can start creating packages containing @code{PKG-INFO} even if you're not
using Python 2.1, since a new release of the Distutils will be made for users of
earlier Python versions.  Version 1.0.2 of the Distutils includes the changes
described in 
@geindex Python Enhancement Proposals; PEP 241
PEP 241@footnote{https://peps.python.org/pep-0241/}, as well as various bugfixes and enhancements.  It will be
available from the Distutils SIG at @indicateurl{https://www.python.org/community/sigs/current/distutils-sig/}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 241

@item PEP 241@footnote{https://peps.python.org/pep-0241/} - Metadata for Python Software Packages

Written and implemented by A.M. Kuchling.

@geindex Python Enhancement Proposals; PEP 243

@item PEP 243@footnote{https://peps.python.org/pep-0243/} - Module Repository Upload Mechanism

Written by Sean Reifschneider, this draft PEP describes a proposed mechanism for
uploading  Python packages to a central server.
@end table


@c ======================================================================

@node New and Improved Modules<4>,Autres changements et corrections<4>,PEP 241 Metadata in Python Packages,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 new-and-improved-modules}@anchor{14d9}
@subsection New and Improved Modules



@itemize *

@item 
Ka-Ping Yee contributed two new modules: @code{inspect.py}, a module for
getting information about live Python code, and @code{pydoc.py}, a module for
interactively converting docstrings to HTML or text.  As a bonus,
@code{Tools/scripts/pydoc}, which is now automatically installed, uses
@code{pydoc.py} to display documentation given a Python module, package, or
class name.  For example, @code{pydoc xml.dom} displays the following:

@example
Python Library Documentation: package xml.dom in xml

NAME
    xml.dom - W3C Document Object Model implementation for Python.

FILE
    /usr/local/lib/python2.1/xml/dom/__init__.pyc

DESCRIPTION
    The Python mapping of the Document Object Model is documented in the
    Python Library Reference in the section on the xml.dom package.

    This package contains the following modules:
      ...
@end example

@code{pydoc} also includes a Tk-based interactive help browser.   @code{pydoc}
quickly becomes addictive; try it out!

@item 
Two different modules for unit testing were added to the standard library.
The @ref{3a,,doctest} module, contributed by Tim Peters, provides a testing
framework based on running embedded examples in docstrings and comparing the
results against the expected output.  PyUnit, contributed by Steve Purcell, is a
unit testing framework inspired by JUnit, which was in turn an adaptation of
Kent Beck's Smalltalk testing framework.  See @indicateurl{https://pyunit.sourceforge.net/} for
more information about PyUnit.

@item 
The @ref{37,,difflib} module contains a class, @ref{1002,,SequenceMatcher}, which
compares two sequences and computes the changes required to transform one
sequence into the other.  For example, this module can be used to write a tool
similar to the Unix @code{diff} program, and in fact the sample program
@code{Tools/scripts/ndiff.py} demonstrates how to write such a script.

@item 
@ref{2d,,curses.panel}, a wrapper for the panel library, part of ncurses and of
SYSV curses, was contributed by Thomas Gellekum.  The panel library provides
windows with the additional feature of depth. Windows can be moved higher or
lower in the depth ordering, and the panel library figures out where panels
overlap and which sections are visible.

@item 
The PyXML package has gone through a few releases since Python 2.0, and Python
2.1 includes an updated version of the @ref{11f,,xml} package.  Some of the
noteworthy changes include support for Expat 1.2 and later versions, the ability
for Expat parsers to handle files in any encoding supported by Python, and
various bugfixes for SAX, DOM, and the @code{minidom} module.

@item 
Ping also contributed another hook for handling uncaught exceptions.
@ref{7f5,,sys.excepthook()} can be set to a callable object.  When an exception isn't
caught by any @ref{6d3,,try}...@ref{189,,except} blocks, the exception will be
passed to @ref{7f5,,sys.excepthook()}, which can then do whatever it likes.  At the
Ninth Python Conference, Ping demonstrated an application for this hook:
printing an extended traceback that not only lists the stack frames, but also
lists the function arguments and the local variables for each frame.

@item 
Various functions in the @ref{ed,,time} module, such as @ref{11c4,,asctime()} and
@ref{14af,,localtime()}, require a floating-point argument containing the time in
seconds since the epoch.  The most common use of these functions is to work with
the current time, so the floating-point argument has been made optional; when a
value isn't provided, the current time will be used.  For example, log file
entries usually need a string containing the current time; in Python 2.1,
@code{time.asctime()} can be used, instead of the lengthier
@code{time.asctime(time.localtime(time.time()))} that was previously required.

This change was proposed and implemented by Thomas Wouters.

@item 
The @ref{5d,,ftplib} module now defaults to retrieving files in passive mode,
because passive mode is more likely to work from behind a firewall.  This
request came from the Debian bug tracking system, since other Debian packages
use @ref{5d,,ftplib} to retrieve files and then don't work from behind a firewall.
It's deemed unlikely that this will cause problems for anyone, because Netscape
defaults to passive mode and few people complain, but if passive mode is
unsuitable for your application or network setup, call @code{set_pasv(0)} on
FTP objects to disable passive mode.

@item 
Support for raw socket access has been added to the @ref{cb,,socket} module,
contributed by Grant Edwards.

@item 
The @ref{af,,pstats} module now contains a simple interactive statistics browser
for displaying timing profiles for Python programs, invoked when the module is
run as a script.  Contributed by  Eric S. Raymond.

@item 
A new implementation-dependent function, @code{sys._getframe([depth])}, has
been added to return a given frame object from the current call stack.
@ref{6cb,,sys._getframe()} returns the frame at the top of the call stack;  if the
optional integer argument `depth' is supplied, the function returns the frame
that is `depth' calls below the top of the stack.  For example,
@code{sys._getframe(1)} returns the caller's frame object.

This function is only present in CPython, not in Jython or the .NET
implementation.  Use it for debugging, and resist the temptation to put it into
production code.
@end itemize

@c ======================================================================

@node Autres changements et corrections<4>,Remerciements<7>,New and Improved Modules<4>,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 other-changes-and-fixes}@anchor{14da}
@subsection Autres changements et corrections


There were relatively few smaller changes made in Python 2.1 due to the shorter
release cycle.  A search through the CVS change logs turns up 117 patches
applied, and 136 bugs fixed; both figures are likely to be underestimates.  Some
of the more notable changes are:


@itemize *

@item 
A specialized object allocator is now optionally available, that should be
faster than the system @code{malloc()} and have less memory overhead.  The
allocator uses C's @code{malloc()} function to get large pools of memory, and
then fulfills smaller memory requests from these pools.  It can be enabled by
providing the @code{--with-pymalloc} option to the @code{configure}
script; see @code{Objects/obmalloc.c} for the implementation details.

Authors of C extension modules should test their code with the object allocator
enabled, because some incorrect code may break, causing core dumps at runtime.
There are a bunch of memory allocation functions in Python's C API that have
previously been just aliases for the C library's @code{malloc()} and
@code{free()}, meaning that if you accidentally called mismatched functions, the
error wouldn't be noticeable.  When the object allocator is enabled, these
functions aren't aliases of @code{malloc()} and @code{free()} any more, and
calling the wrong function to free memory will get you a core dump.  For
example, if memory was allocated using @ref{14db,,PyMem_New}, it has to be freed
using @ref{14dc,,PyMem_Del()}, not @code{free()}.  A few modules included with Python
fell afoul of this and had to be fixed; doubtless there are more third-party
modules that will have the same problem.

The object allocator was contributed by Vladimir Marangozov.

@item 
The speed of line-oriented file I/O has been improved because people often
complain about its lack of speed, and because it's often been used as a naïve
benchmark.  The @ref{b9,,readline()} method of file objects has therefore been
rewritten to be much faster.  The exact amount of the speedup will vary from
platform to platform depending on how slow the C library's @code{getc()} was, but
is around 66%, and potentially much faster on some particular operating systems.
Tim Peters did much of the benchmarking and coding for this change, motivated by
a discussion in comp.lang.python.

A new module and method for file objects was also added, contributed by Jeff
Epler. The new method, @code{xreadlines()}, is similar to the existing
@code{xrange()} built-in.  @code{xreadlines()} returns an opaque sequence object
that only supports being iterated over, reading a line on every iteration but
not reading the entire file into memory as the existing @code{readlines()} method
does. You'd use it like this:

@example
for line in sys.stdin.xreadlines():
    # ... do something for each line ...
    ...
@end example

For a fuller discussion of the line I/O changes, see the python-dev summary for
January 1--15, 2001 at @indicateurl{https://mail.python.org/pipermail/python-dev/2001-January/}.

@item 
A new method, @ref{14dd,,popitem()}, was added to dictionaries to enable
destructively iterating through the contents of a dictionary; this can be faster
for large dictionaries because there's no need to construct a list containing
all the keys or values. @code{D.popitem()} removes a random @code{(key, value)} pair
from the dictionary @code{D} and returns it as a 2-tuple.  This was implemented
mostly by Tim Peters and Guido van Rossum, after a suggestion and preliminary
patch by Moshe Zadka.

@item 
Modules can now control which names are imported when @code{from module import *}
is used, by defining an @code{__all__} attribute containing a list of names that
will be imported.  One common complaint is that if the module imports other
modules such as @ref{d8,,sys} or @ref{d2,,string}, @code{from module import *} will add
them to the importing module's namespace.  To fix this, simply list the public
names in @code{__all__}:

@example
# List public names
__all__ = ['Database', 'open']
@end example

A stricter version of this patch was first suggested and implemented by Ben
Wolfson, but after some python-dev discussion, a weaker final version was
checked in.

@item 
Applying @ref{7e7,,repr()} to strings previously used octal escapes for
non-printable characters; for example, a newline was @code{'\012'}.  This was a
vestigial trace of Python's C ancestry, but today octal is of very little
practical use.  Ka-Ping Yee suggested using hex escapes instead of octal ones,
and using the @code{\n}, @code{\t}, @code{\r} escapes for the appropriate characters,
and implemented this new formatting.

@item 
Syntax errors detected at compile-time can now raise exceptions containing the
filename and line number of the error, a pleasant side effect of the compiler
reorganization done by Jeremy Hylton.

@item 
C extensions which import other modules have been changed to use
@ref{3b5,,PyImport_ImportModule()}, which means that they will use any import hooks
that have been installed.  This is also encouraged for third-party extensions
that need to import some other module from C code.

@item 
The size of the Unicode character database was shrunk by another 340K thanks
to Fredrik Lundh.

@item 
Some new ports were contributed: MacOS X (by Steven Majewski), Cygwin (by
Jason Tishler); RISCOS (by Dietmar Schwertberger); Unixware 7  (by Billy G.
Allie).
@end itemize

And there's the usual list of minor bugfixes, minor memory leaks, docstring
edits, and other tweaks, too lengthy to be worth itemizing; see the CVS logs for
the full details if you want them.

@c ======================================================================

@node Remerciements<7>,,Autres changements et corrections<4>,Nouveautés de Python 2 1
@anchor{whatsnew/2 1 acknowledgements}@anchor{14de}
@subsection Remerciements


The author would like to thank the following people for offering suggestions on
various drafts of this article: Graeme Cross, David Goodger, Jay Graves, Michael
Hudson, Marc-André Lemburg, Fredrik Lundh, Neil Schemenauer, Thomas Wouters.

@node Nouveautés de Python 2 0,Changelog,Nouveautés de Python 2 1,Nouveautés de Python
@anchor{whatsnew/2 0 doc}@anchor{14df}@anchor{whatsnew/2 0 what-s-new-in-python-2-0}@anchor{14e0}
@section Nouveautés de Python 2.0


@*Auteur: 
A.M. Kuchling et Moshe Zadka


@c $Id: whatsnew20.tex 50964 2006-07-30 03:03:43Z fred.drake $

@menu
* Introduction: Introduction<3>. 
* À propos de Python 1.6.: À propos de Python 1 6. 
* Nouveau processus de développement:: 
* Unicode: Unicode<2>. 
* Compréhensions de listes:: 
* Opérateurs d’affectation augmentées:: 
* Méthodes de chaînes de caractères:: 
* Garbage Collection of Cycles:: 
* Other Core Changes:: 
* Porting to 2.0: Porting to 2 0. 
* Extending/Embedding Changes:: 
* Distutils; Making Modules Easy to Install: Distutils Making Modules Easy to Install. 
* Modules XML:: 
* Module changes:: 
* Nouveaux modules: Nouveaux modules<12>. 
* IDLE Improvements:: 
* Deleted and Deprecated Modules:: 
* Remerciements: Remerciements<8>. 

@end menu

@node Introduction<3>,À propos de Python 1 6,,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 introduction}@anchor{14e1}
@subsection Introduction


Une nouvelle version de Python, la version 2.0, est sortie le 16 octobre 2000. Cet article traite des nouvelles fonctionnalités intéressantes de cette version, met en évidence d'autres changements utiles, et souligne quelques incompatibilités qui peuvent nécessiter la réécriture du code.

Python's development never completely stops between releases, and a steady flow
of bug fixes and improvements are always being submitted. A host of minor fixes,
a few optimizations, additional docstrings, and better error messages went into
2.0; to list them all would be impossible, but they're certainly significant.
Consult the publicly available CVS logs if you want to see the full list.  This
progress is due to the five developers working for  PythonLabs are now getting
paid to spend their days fixing bugs, and also due to the improved communication
resulting  from moving to SourceForge.

@c ======================================================================

@node À propos de Python 1 6,Nouveau processus de développement,Introduction<3>,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 what-about-python-1-6}@anchor{14e2}
@subsection À propos de Python 1.6.


Python 1.6 peut être vu comme la version des obligations contractuelles. Après que l’équipe de développement eût quitté le CNRI en mai 2000, celui-ci a demandé la création d’une version 1.6, contenant tout le travail sur Python réalisé au CNRI. Python 1.6 représente de ce fait l’état de l’arbre `CVS' tel qu’il était en mai 2000, la nouvelle fonctionnalité la plus remarquable étant le support d’Unicode. Le développement a continué après mai bien sûr, donc la branche 1.6 a reçu quelques corrections pour être sûr qu’elle soit compatible avec Python 2.0. La version 1.6 fait donc partie de l’évolution de Python, ce n’est pas une branche séparée.

Alors, devriez-vous vous intéresser à Python 1.6 ? Probablement pas. Les versions `1.6final' et `2.0beta1' sont sorties le même jour (5 septembre 2000), le plan étant de finaliser Python 2.0 environ un mois plus tard. Si vous avez des applications à maintenir, il n’y a pas vraiment d’intérêt à casser des choses en migrant sur la version 1.6, les réparer, puis avoir de nouveau des choses cassées à peine un mois plus tard en passant à la 2.0; il vaut mieux partir directement de la 2.0. La plupart des fonctionnalités vraiment intéressantes décrites dans ce document sont seulement dans la 2.0, parce que beaucoup de travail a été réalisé entre mai et septembre.

@c ======================================================================

@node Nouveau processus de développement,Unicode<2>,À propos de Python 1 6,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 new-development-process}@anchor{14e3}
@subsection Nouveau processus de développement


Le changement le plus important dans Python 2.0 ne concerne peut-être pas le code, mais le développement de Python : en mai 2000, les développeurs Python ont commencé à utiliser les outils mis à disposition par SourceForge pour stocker le code source, suivre les rapports de bogues et gérer la file d’attente des soumissions de correctifs. Pour signaler des bogues ou soumettre des correctifs pour Python 2.0, utilisez les outils de suivi des bogues et de gestion des correctifs disponibles sur la page du projet Python, à l’adresse @indicateurl{https://sourceforge.net/projects/python/}.

Le plus important des services maintenant hébergé chez SourceForge est l’arborescence CVS Python, le référentiel sous contrôle de version contenant le code source de Python. Auparavant, environ 7 personnes avaient un accès en écriture à l’arborescence CVS et tous les correctifs devaient être inspectés et archivés par l’une des personnes figurant sur cette liste restreinte. Évidemment, ce n’était pas très évolutif. En déplaçant l’arborescence CVS vers SourceForge, il est devenu possible d’accorder un accès en écriture à davantage de personnes ; en septembre 2000, 27 personnes pouvaient enregistrer les modifications, soit quatre fois plus. Cela rend possible des modifications à grande échelle qui ne seraient pas tentées si elles devaient être filtrées par le petit groupe de développeurs principaux. Par exemple, un jour, Peter Schneider-Kamp a eu l’idée de supprimer la compatibilité K&R C et de convertir le code source C de Python en ANSI C. Après avoir obtenu l’approbation de la liste de diffusion `python-dev', il s’est lancé dans une série d’archives qui ont duré environ une semaine, d’autres développeurs l'ont rejoint et le travail a été fait. S’il n’y avait eut que 5 personnes ayant un accès en écriture, cette tâche aurait probablement été considérée comme « agréable, mais ne valant pas le temps ni les efforts nécessaires » et cela ne se serait jamais fait.

Le passage à l’utilisation des services de SourceForge a entraîné une augmentation remarquable du rythme de développement. Les correctifs sont maintenant soumis, commentés, révisés par des personnes autres que l’auteur d’origine et échangés entre les personnes jusqu’à ce que le correctif soit jugé utile. Les bogues sont suivis dans un emplacement central et peuvent être attribués à une personne spécifique pour être corrigés. , et nous pouvons compter le nombre de bogues ouverts pour mesurer les progrès. Cela n’a pas coûté cher: les développeurs ont désormais plus de courrier électronique à traiter, davantage de listes de diffusion à suivre et des outils spéciaux ont dû être créés pour le nouvel environnement. Par exemple, SourceForge envoie des messages électroniques de correctif et de notification de bogues par défaut qui ne sont d’aucune utilité, Ka-Ping Yee a donc créé un `scraper' HTML qui envoie des messages plus utiles.

La facilité d’ajout de code a provoqué quelques problèmes de croissance initiaux, tels que le code a été archivé avant qu’il ne soit prêt ou sans l’accord clair du groupe de développeurs. Le processus d’approbation qui a émergé est quelque peu similaire à celui utilisé par le groupe Apache. Les développeurs peuvent voter `+1', `+0', `-0' ou `-1' sur un patch; `+1' et `-1' indiquent une acceptation ou un rejet, tandis que `+0' et `-0' signifient que le développeur est généralement indifférent au changement, bien qu’il présente une légère inclinaison positive ou négative. Le changement le plus important par rapport au modèle Apache est que le vote est essentiellement consultatif, permettant à Guido van Rossum, détenteur du statut de « dictateur bienveillant à vie », de connaître l’opinion générale. Il peut toujours ignorer le résultat d’un vote et approuver ou rejeter un changement même si la communauté n’est pas d’accord avec lui.

Producing an actual patch is the last step in adding a new feature, and is
usually easy compared to the earlier task of coming up with a good design.
Discussions of new features can often explode into lengthy mailing list threads,
making the discussion hard to follow, and no one can read every posting to
python-dev.  Therefore, a relatively formal process has been set up to write
Python Enhancement Proposals (PEPs), modelled on the internet RFC process.  PEPs
are draft documents that describe a proposed new feature, and are continually
revised until the community reaches a consensus, either accepting or rejecting
the proposal.  Quoting from the introduction to 
@geindex Python Enhancement Proposals; PEP 1
PEP 1@footnote{https://peps.python.org/pep-0001/}, "PEP Purpose and
Guidelines":

@quotation

PEP signifie `Python Enhancement Proposition'. Une PEP est un document de conception fournissant des informations à la communauté Python ou décrivant une nouvelle fonctionnalité de Python. La PEP devrait fournir une spécification technique concise de la fonctionnalité et une justification de celle-ci.

Nous souhaitons que les PEP soient les principaux mécanismes permettant de proposer de nouvelles fonctionnalités, de recueillir les commentaires de la communauté sur un problème et de documenter les décisions de conception prises dans Python. L’auteur du PPE est chargé de créer un consensus au sein de la communauté et de documenter les opinions divergentes.
@end quotation

Read the rest of 
@geindex Python Enhancement Proposals; PEP 1
PEP 1@footnote{https://peps.python.org/pep-0001/} for the details of the PEP editorial process, style, and
format.  PEPs are kept in the Python CVS tree on SourceForge, though they're not
part of the Python 2.0 distribution, and are also available in HTML form from
@indicateurl{https://peps.python.org/}.  As of September 2000, there are 25 PEPs, ranging
from 
@geindex Python Enhancement Proposals; PEP 201
PEP 201@footnote{https://peps.python.org/pep-0201/}, "Lockstep Iteration", to PEP 225, "Elementwise/Objectwise
Operators".

@c ======================================================================

@node Unicode<2>,Compréhensions de listes,Nouveau processus de développement,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 unicode}@anchor{14e4}
@subsection Unicode


La plus grande nouveauté de Python 2.0 est un nouveau type de données fondamental: les chaînes Unicode. Unicode utilise des nombres à 16 bits pour représenter des caractères au lieu du nombre à 8 bits utilisé par ASCII, ce qui signifie que 65 536 caractères distincts peuvent être pris en charge.

La dernière interface de prise en charge Unicode a été mise au point après de nombreuses discussions souvent houleuses sur la liste de diffusion `python-dev', et principalement implémentée par Marc-André Lemburg, basée sur une implémentation de type chaîne Unicode de Fredrik Lundh. Une explication détaillée de l’interface a été écrite ainsi 
@geindex Python Enhancement Proposals; PEP 100
PEP 100@footnote{https://peps.python.org/pep-0100/}, "Intégration Python Unicode". Cet article couvrira simplement les points les plus significatifs sur les interfaces Unicode.

In Python source code, Unicode strings are written as @code{u"string"}.  Arbitrary
Unicode characters can be written using a new escape sequence, @code{\u@var{HHHH}}, where
`HHHH' is a 4-digit hexadecimal number from 0000 to FFFF.  The existing
@code{\x@var{HH}} escape sequence can also be used, and octal escapes can be used for
characters up to U+01FF, which is represented by @code{\777}.

Les chaînes Unicode, tout comme les chaînes ordinaires, sont un type de séquence immuable. Ils peuvent être indexés et tranchés, mais pas modifiés en place. Les chaînes Unicode ont une méthode @code{encoder([encoding])} qui renvoie une chaîne de 8 bits dans l’encodage souhaité. Les codages sont nommés par des chaînes, telles que @code{’ascii’}, @code{’utf-8’}, @code{’iso-8859-1’}, ou autre chose. Une API de codec est définie pour l’implémentation et l’enregistrement de nouveaux codages disponibles dans tout un programme Python. Si aucun codage n’est spécifié, le codage par défaut est généralement du code ASCII 7-bits, bien qu’il puisse être modifié pour votre installation Python en appelant la fonction @code{sys.setdefaultencoding (encoding)} dans une version personnalisée de @code{site.py}.

La combinaison de chaînes 8 bits et Unicode est toujours forcée en Unicode, à l’aide du codage ASCII par défaut; le résultat de @code{’a’ + u’bc’} est @code{u’abc’}.

De nouvelles fonctions primitives ont été ajoutées, et des fonctions existantes ont été modifiées pour supporter Unicode :


@itemize *

@item 
@code{unichr(ch)} renvoie une chaîne Unicode de longueur 1, contenant le caractère `ch'.

@item 
@code{ord(u)}, quand `u' est une chaîne normale ou Unicode de longueur 1, renvoie un entier représentant le nombre de caractères.

@item 
@code{unicode(string [, encoding]  [, errors] )} crée une chaîne Unicode à partir d’une chaîne de 8 bits. @code{encoding} est une chaîne nommant le codage à utiliser. Le paramètre @code{errors} spécifie le traitement des caractères non valides pour l’ encodage en cours; en passant @code{’strict’} comme valeur, une exception est générée pour toute erreur de codage, alors que @code{’ignore’} fait en sorte que les erreurs soient ignorées en silence et que @code{’replace’} utilise U+FFFD, caractère de remplacement officiel, en cas de problème.

@item 
L’instruction @code{exec} et divers éléments intégrés tels que @code{eval()}, @code{getattr()} et @code{setattr()} accepteront également les chaînes Unicode ainsi que les chaînes ordinaires. (Il est possible que le processus de résolution de ce problème ait échappé à certaines fonctions intégrées ; si vous trouvez une fonction intégrée qui accepte les chaînes mais n’accepte pas les chaînes Unicode, signalez-la comme un bogue.)
@end itemize

Un nouveau module, @ref{104,,unicodedata}, fournit une interface aux propriétés de caractère Unicode. Par exemple, @code{unicodedata.category(u'A')} renvoie la chaîne de 2 caractères « Lu », le « L » désignant une lettre et « u » signifiant qu’il s’agit d’une majuscule. @code{unicodedata.bidirectional(u'\u0660')} renvoie « AN », ce qui signifie que U+0660 est un nombre arabe.

Le module @ref{1b,,codecs} contient des fonctions pour rechercher les codages existants et en enregistrer de nouveaux. À moins que vous ne souhaitiez implémenter un nouvel encodage, vous utiliserez le plus souvent la fonction  @code{codecs.lookup(encoding)}, qui renvoie un quadruplet : @code{(encode_func, decode_func, stream_reader, stream_writer)}.


@itemize *

@item 
`encode_func' est une fonction qui prend une chaîne Unicode, et renvoie un n-uplet de longueur 2 @code{(string, length)}.  `string' est une chaîne de caractères à 8 bits contenant une partie (ou la totalité) de la chaîne Unicode convertie en codage donné, et `length' vous indique le nombre de caractères de la chaîne qui ont été convertis.

@item 
`decode_func' est l’opposé de `encode_func', en prenant une chaîne de caractères à 8 bits et le retour d’une paire @code{(ustring, longueur)}, composé de la chaîne Unicode résultante `ustring' et l’entier `length' indiquant combien de caractères de la chaîne de caractères à 8 bits ont été consommés.

@item 
`stream_reader' is a class that supports decoding input from a stream.
`stream_reader(file_obj)' returns an object that supports the @code{read()},
@code{readline()}, and @code{readlines()} methods.  These methods will all
translate from the given encoding and return Unicode strings.

@item 
`stream_writer', similarly, is a class that supports encoding output to a
stream.  `stream_writer(file_obj)' returns an object that supports the
@code{write()} and @code{writelines()} methods.  These methods expect Unicode
strings, translating them to the given encoding on output.
@end itemize

Par exemple, le code suivant écrit une chaîne Unicode dans un fichier, en l’encodant en UTF-8 :

@example
import codecs

unistr = u'\u0660\u2000ab ...'

(UTF8_encode, UTF8_decode,
 UTF8_streamreader, UTF8_streamwriter) = codecs.lookup('UTF-8')

output = UTF8_streamwriter( open( '/tmp/output', 'wb') )
output.write( unistr )
output.close()
@end example

Le code suivant lirait ensuite le texte UTF-8 du fichier :

@example
input = UTF8_streamreader( open( '/tmp/output', 'rb') )
print repr(input.read())
input.close()
@end example

Des expressions rationnelles supportant l’Unicode sont disponibles dans le module @ref{b8,,re}, qui a une implémentation sous-jacente appelée SRE écrite par Fredrik Lundh de Secret Labs AB.

Une option de ligne de commande @code{-U} a été ajoutée, ce qui fait que le compilateur Python interprète toutes les chaînes de caractères comme des chaînes de caractères Unicode. Ceci est destiné à être utilisé dans les tests et rendre votre code Python compatible avec les versions futures, car une version future de Python peut abandonner la prise en charge des chaînes de caractères 8-bits et fournir uniquement des chaînes de caractères Unicode.

@c ======================================================================

@node Compréhensions de listes,Opérateurs d’affectation augmentées,Unicode<2>,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 list-comprehensions}@anchor{14e5}
@subsection Compréhensions de listes


Les listes sont un type de données crucial dans Python, et de nombreux programmes manipulent une liste à un moment donné.  Deux opérations communes sur les listes sont de boucler sur elles, soit de choisir les éléments qui répondent à un certain critère, ou d’appliquer une certaine fonction à chaque élément. Par exemple, à partir d’une liste de chaînes de caractères, vous pouvez retirer toutes les chaînes contenant une sous-chaîne donnée, ou enlever les espaces de chaque ligne.

Les fonctions existantes @ref{84e,,map()} et @ref{84f,,filter()} peuvent être utilisées à cette fin, mais elles nécessitent une fonction en leurs arguments.  C’est très bien s’il y a une fonction intégrée existante qui peut être passé directement, mais s’il n’y a pas, vous devez créer une petite fonction pour faire le travail requis, et les règles de portée de Python rendent le résultat laid si la petite fonction a besoin d’informations supplémentaires.  Prenons le premier exemple du paragraphe précédent, en trouvant toutes les chaînes de la liste contenant une sous-chaîne donnée.  Vous pouvez écrire ce qui suit pour le faire :

@example
# Given the list L, make a list of all strings
# containing the substring S.
sublist = filter( lambda s, substring=S:
                     string.find(s, substring) != -1,
                  L)
@end example

En raison des règles de portée de Python, un argument par défaut est utilisé de sorte que la fonction anonyme créée par l’expression @ref{127a,,lambda} sait quelle sous-chaîne est recherchée.  Les listes en compréhension rendent ceci plus propre :

@example
sublist = [ s for s in L if string.find(s, S) != -1 ]
@end example

Les compréhensions de liste sont de la forme suivante :

@example
[ expression for expr in sequence1
             for expr2 in sequence2 ...
             for exprN in sequenceN
             if condition ]
@end example

Le @code{for}…@code{in} clauses contiennent les séquences à itérer.  Les séquences n’ont pas à être de la même longueur, parce qu’elles ne sont `pas' itérées en parallèle, mais de gauche à droite; cela est expliqué plus clairement dans les paragraphes suivants.  Les éléments de la liste générée seront les valeurs successives de l’expression.  La clause finale @code{if} clause est facultative ; si présent, l’`expression' n’est évaluée et ajoutée au résultat que si la `condition' est vraie.

Pour que la sémantique soit très claire, une compréhension de liste est équivalente au code Python suivant :

@example
for expr1 in sequence1:
    for expr2 in sequence2:
    ...
        for exprN in sequenceN:
             if (condition):
                  # Append the value of
                  # the expression to the
                  # resulting list.
@end example

Cela signifie que lorsqu’il y a plusieurs @code{for}…@code{in} clauses, la liste résultante sera égale au produit des longueurs de toutes les séquences.  Si vous avez deux listes de longueur 3, la liste de sortie est de longueur 9 :

@example
seq1 = 'abc'
seq2 = (1,2,3)
>>> [ (x,y) for x in seq1 for y in seq2]
[('a', 1), ('a', 2), ('a', 3), ('b', 1), ('b', 2), ('b', 3), ('c', 1),
('c', 2), ('c', 3)]
@end example

Afin de ne pas introduire une ambiguïté dans la grammaire de Python, `expression' doit être encadrée par des parenthèses si elle produit un n-uplet. La première compréhension de liste ci-dessous n'est pas valide syntaxiquement, tandis que la seconde l'est :

@example
# Syntax error
[ x,y for x in seq1 for y in seq2]
# Correct
[ (x,y) for x in seq1 for y in seq2]
@end example

Le concept des liste en compréhension provient à l’origine du langage de programmation fonctionnelle Haskell (@indicateurl{https://www.haskell.org}).  Greg Ewing a plaidé le plus efficacement pour les ajouter à Python et a écrit le patch de compréhension de liste initiale, qui a ensuite été discuté pendant un temps apparemment sans fin sur la liste de diffusion `python-dev' et maintenu à jour par Skip Montanaro.

@c ======================================================================

@node Opérateurs d’affectation augmentées,Méthodes de chaînes de caractères,Compréhensions de listes,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 augmented-assignment}@anchor{14e6}
@subsection Opérateurs d’affectation augmentées


Les opérateurs d’affectation soudées, une autre fonctionnalité demandée depuis longtemps, ont été ajoutés à Python 2.0.  Les opérateurs d’affectations augmentées comprennent  @code{+=}, @code{-=}, @code{*=} et ainsi de suite. Par exemple, l’instruction @code{a += 2} incrémente la valeur de la variable @code{a} par 2, équivalente à l’opération @code{a = a + 2} .

The full list of supported assignment operators is @code{+=}, @code{-=}, @code{*=},
@code{/=}, @code{%=}, @code{**=}, @code{&=}, @code{|=}, @code{^=}, @code{>>=}, and @code{<<=}.  Python
classes can override the augmented assignment operators by defining methods
named @code{__iadd__()}, @code{__isub__()}, etc.  For example, the following
@code{Number} class stores a number and supports using += to create a new
instance with an incremented value.

@c The empty groups below prevent conversion to guillemets.

@example
class Number:
    def __init__(self, value):
        self.value = value
    def __iadd__(self, increment):
        return Number( self.value + increment)

n = Number(5)
n += 3
print n.value
@end example

The @code{__iadd__()} special method is called with the value of the increment,
and should return a new instance with an appropriately modified value; this
return value is bound as the new value of the variable on the left-hand side.

Augmented assignment operators were first introduced in the C programming
language, and most C-derived languages, such as @code{awk}, C++, Java, Perl,
and PHP also support them.  The augmented assignment patch was implemented by
Thomas Wouters.

@c ======================================================================

@node Méthodes de chaînes de caractères,Garbage Collection of Cycles,Opérateurs d’affectation augmentées,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 string-methods}@anchor{14e7}
@subsection Méthodes de chaînes de caractères


Until now string-manipulation functionality was in the @ref{d2,,string} module,
which was usually a front-end for the @code{strop} module written in C.  The
addition of Unicode posed a difficulty for the @code{strop} module, because the
functions would all need to be rewritten in order to accept either 8-bit or
Unicode strings.  For functions such as @code{string.replace()}, which takes 3
string arguments, that means eight possible permutations, and correspondingly
complicated code.

Instead, Python 2.0 pushes the problem onto the string type, making string
manipulation functionality available through methods on both 8-bit strings and
Unicode strings.

@example
>>> 'andrew'.capitalize()
'Andrew'
>>> 'hostname'.replace('os', 'linux')
'hlinuxtname'
>>> 'moshe'.find('sh')
2
@end example

One thing that hasn't changed, a noteworthy April Fools' joke notwithstanding,
is that Python strings are immutable. Thus, the string methods return new
strings, and do not modify the string on which they operate.

The old @ref{d2,,string} module is still around for backwards compatibility, but it
mostly acts as a front-end to the new string methods.

Two methods which have no parallel in pre-2.0 versions, although they did exist
in JPython for quite some time, are @code{startswith()} and @code{endswith()}.
@code{s.startswith(t)} is equivalent to @code{s[:len(t)] == t}, while
@code{s.endswith(t)} is equivalent to @code{s[-len(t):] == t}.

One other method which deserves special mention is @code{join()}.  The
@code{join()} method of a string receives one parameter, a sequence of strings,
and is equivalent to the @code{string.join()} function from the old @ref{d2,,string}
module, with the arguments reversed. In other words, @code{s.join(seq)} is
equivalent to the old @code{string.join(seq, s)}.

@c ======================================================================

@node Garbage Collection of Cycles,Other Core Changes,Méthodes de chaînes de caractères,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 garbage-collection-of-cycles}@anchor{14e8}
@subsection Garbage Collection of Cycles


The C implementation of Python uses reference counting to implement garbage
collection.  Every Python object maintains a count of the number of references
pointing to itself, and adjusts the count as references are created or
destroyed.  Once the reference count reaches zero, the object is no longer
accessible, since you need to have a reference to an object to access it, and if
the count is zero, no references exist any longer.

Reference counting has some pleasant properties: it's easy to understand and
implement, and the resulting implementation is portable, fairly fast, and reacts
well with other libraries that implement their own memory handling schemes.  The
major problem with reference counting is that it sometimes doesn't realise that
objects are no longer accessible, resulting in a memory leak.  This happens when
there are cycles of references.

Consider the simplest possible cycle,  a class instance which has a reference to
itself:

@example
instance = SomeClass()
instance.myself = instance
@end example

After the above two lines of code have been executed, the reference count of
@code{instance} is 2; one reference is from the variable named @code{'instance'}, and
the other is from the @code{myself} attribute of the instance.

If the next line of code is @code{del instance}, what happens?  The reference count
of @code{instance} is decreased by 1, so it has a reference count of 1; the
reference in the @code{myself} attribute still exists.  Yet the instance is no
longer accessible through Python code, and it could be deleted.  Several objects
can participate in a cycle if they have references to each other, causing all of
the objects to be leaked.

Python 2.0 fixes this problem by periodically executing a cycle detection
algorithm which looks for inaccessible cycles and deletes the objects involved.
A new @ref{5f,,gc} module provides functions to perform a garbage collection,
obtain debugging statistics, and tuning the collector's parameters.

Running the cycle detection algorithm takes some time, and therefore will result
in some additional overhead.  It is hoped that after we've gotten experience
with the cycle collection from using 2.0, Python 2.1 will be able to minimize
the overhead with careful tuning.  It's not yet obvious how much performance is
lost, because benchmarking this is tricky and depends crucially on how often the
program creates and destroys objects.  The detection of cycles can be disabled
when Python is compiled, if you can't afford even a tiny speed penalty or
suspect that the cycle collection is buggy, by specifying the
@code{--without-cycle-gc} switch when running the @code{configure}
script.

Several people tackled this problem and contributed to a solution.  An early
implementation of the cycle detection approach was written by Toby Kelsey.  The
current algorithm was suggested by Eric Tiedemann during a visit to CNRI, and
Guido van Rossum and Neil Schemenauer wrote two different implementations, which
were later integrated by Neil.  Lots of other people offered suggestions along
the way; the March 2000 archives of the python-dev mailing list contain most of
the relevant discussion, especially in the threads titled "Reference cycle
collection for Python" and "Finalization again".

@c ======================================================================

@node Other Core Changes,Porting to 2 0,Garbage Collection of Cycles,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 other-core-changes}@anchor{14e9}
@subsection Other Core Changes


Various minor changes have been made to Python's syntax and built-in functions.
None of the changes are very far-reaching, but they're handy conveniences.

@menu
* Changements mineurs du langage:: 
* Changements concernant les fonctions primitives:: 

@end menu

@node Changements mineurs du langage,Changements concernant les fonctions primitives,,Other Core Changes
@anchor{whatsnew/2 0 minor-language-changes}@anchor{14ea}
@subsubsection Changements mineurs du langage


A new syntax makes it more convenient to call a given function with a tuple of
arguments and/or a dictionary of keyword arguments. In Python 1.5 and earlier,
you'd use the @code{apply()} built-in function: @code{apply(f, args, kw)} calls the
function @code{f()} with the argument tuple `args' and the keyword arguments in
the dictionary `kw'.  @code{apply()}  is the same in 2.0, but thanks to a patch
from Greg Ewing, @code{f(*args, **kw)} is a shorter and clearer way to achieve the
same effect.  This syntax is symmetrical with the syntax for defining
functions:

@example
def f(*args, **kw):
    # args is a tuple of positional args,
    # kw is a dictionary of keyword args
    ...
@end example

The @code{print} statement can now have its output directed to a file-like
object by following the @code{print} with  @code{>> file}, similar to the
redirection operator in Unix shells. Previously you'd either have to use the
@code{write()} method of the file-like object, which lacks the convenience and
simplicity of @code{print}, or you could assign a new value to
@code{sys.stdout} and then restore the old value.  For sending output to standard
error, it's much easier to write this:

@example
print >> sys.stderr, "Warning: action field not supplied"
@end example

Modules can now be renamed on importing them, using the syntax @code{import module
as name} or @code{from module import name as othername}.  The patch was submitted
by Thomas Wouters.

A new format style is available when using the @code{%} operator; '%r' will insert
the @ref{7e7,,repr()} of its argument.  This was also added from symmetry
considerations, this time for symmetry with the existing '%s' format style,
which inserts the @ref{435,,str()} of its argument.  For example, @code{'%r %s' % ('abc',
'abc')} returns a string containing @code{'abc' abc}.

Previously there was no way to implement a class that overrode Python's built-in
@ref{2e8,,in} operator and implemented a custom version.  @code{obj in seq} returns
true if `obj' is present in the sequence `seq'; Python computes this by simply
trying every index of the sequence until either `obj' is found or an
@ref{14eb,,IndexError} is encountered.  Moshe Zadka contributed a patch which adds a
@code{__contains__()} magic method for providing a custom implementation for
@code{in}. Additionally, new built-in objects written in C can define what
@code{in} means for them via a new slot in the sequence protocol.

Earlier versions of Python used a recursive algorithm for deleting objects.
Deeply nested data structures could cause the interpreter to fill up the C stack
and crash; Christian Tismer rewrote the deletion logic to fix this problem.  On
a related note, comparing recursive objects recursed infinitely and crashed;
Jeremy Hylton rewrote the code to no longer crash, producing a useful result
instead.  For example, after this code:

@example
a = []
b = []
a.append(a)
b.append(b)
@end example

The comparison @code{a==b} returns true, because the two recursive data structures
are isomorphic. See the thread "trashcan and PR#7" in the April 2000 archives of
the python-dev mailing list for the discussion leading up to this
implementation, and some useful relevant links.    Note that comparisons can now
also raise exceptions. In earlier versions of Python, a comparison operation
such as @code{cmp(a,b)} would always produce an answer, even if a user-defined
@code{__cmp__()} method encountered an error, since the resulting exception would
simply be silently swallowed.

@c Starting URL:

@c https://www.python.org/pipermail/python-dev/2000-April/004834.html

Work has been done on porting Python to 64-bit Windows on the Itanium processor,
mostly by Trent Mick of ActiveState.  (Confusingly, @code{sys.platform} is still
@code{'win32'} on Win64 because it seems that for ease of porting, MS Visual C++
treats code as 32 bit on Itanium.) PythonWin also supports Windows CE; see the
Python CE page at @indicateurl{https://pythonce.sourceforge.net/} for more information.

Another new platform is Darwin/MacOS X; initial support for it is in Python 2.0.
Dynamic loading works, if you specify "configure --with-dyld --with-suffix=.x".
Consult the README in the Python source distribution for more instructions.

An attempt has been made to alleviate one of Python's warts, the often-confusing
@ref{428,,NameError} exception when code refers to a local variable before the
variable has been assigned a value.  For example, the following code raises an
exception on the @code{print} statement in both 1.5.2 and 2.0; in 1.5.2 a
@ref{428,,NameError} exception is raised, while 2.0 raises a new
@ref{14ec,,UnboundLocalError} exception. @ref{14ec,,UnboundLocalError} is a subclass of
@ref{428,,NameError}, so any existing code that expects @ref{428,,NameError} to be
raised should still work.

@example
def f():
    print "i=",i
    i = i + 1
f()
@end example

Two new exceptions, @ref{52e,,TabError} and @ref{792,,IndentationError}, have been
introduced.  They're both subclasses of @ref{18b,,SyntaxError}, and are raised when
Python code is found to be improperly indented.

@node Changements concernant les fonctions primitives,,Changements mineurs du langage,Other Core Changes
@anchor{whatsnew/2 0 changes-to-built-in-functions}@anchor{14ed}
@subsubsection Changements concernant les fonctions primitives


A new built-in, @code{zip(seq1, seq2, ...)}, has been added.  @ref{7ba,,zip()}
returns a list of tuples where each tuple contains the i-th element from each of
the argument sequences.  The difference between @ref{7ba,,zip()} and @code{map(None,
seq1, seq2)} is that @ref{84e,,map()} pads the sequences with @code{None} if the
sequences aren't all of the same length, while @ref{7ba,,zip()} truncates the
returned list to the length of the shortest argument sequence.

The @ref{254,,int()} and @code{long()} functions now accept an optional "base"
parameter when the first argument is a string. @code{int('123', 10)} returns 123,
while @code{int('123', 16)} returns 291.  @code{int(123, 16)} raises a
@ref{522,,TypeError} exception with the message "can't convert non-string with
explicit base".

A new variable holding more detailed version information has been added to the
@ref{d8,,sys} module.  @code{sys.version_info} is a tuple @code{(major, minor, micro,
level, serial)} For example, in a hypothetical 2.0.1beta1, @code{sys.version_info}
would be @code{(2, 0, 1, 'beta', 1)}. `level' is a string such as @code{"alpha"},
@code{"beta"}, or @code{"final"} for a final release.

Dictionaries have an odd new method, @code{setdefault(key, default)}, which
behaves similarly to the existing @code{get()} method.  However, if the key is
missing, @code{setdefault()} both returns the value of `default' as @code{get()}
would do, and also inserts it into the dictionary as the value for `key'.  Thus,
the following lines of code:

@example
if dict.has_key( key ): return dict[key]
else:
    dict[key] = []
    return dict[key]
@end example

can be reduced to a single @code{return dict.setdefault(key, [])} statement.

The interpreter sets a maximum recursion depth in order to catch runaway
recursion before filling the C stack and causing a core dump or GPF..
Previously this limit was fixed when you compiled Python, but in 2.0 the maximum
recursion depth can be read and modified using @ref{4ad,,sys.getrecursionlimit()} and
@ref{4ac,,sys.setrecursionlimit()}. The default value is 1000, and a rough maximum
value for a given platform can be found by running a new script,
@code{Misc/find_recursionlimit.py}.

@c ======================================================================

@node Porting to 2 0,Extending/Embedding Changes,Other Core Changes,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 porting-to-2-0}@anchor{14ee}
@subsection Porting to 2.0


New Python releases try hard to be compatible with previous releases, and the
record has been pretty good.  However, some changes are considered useful
enough, usually because they fix initial design decisions that turned out to be
actively mistaken, that breaking backward compatibility can't always be avoided.
This section lists the changes in Python 2.0 that may cause old Python code to
break.

The change which will probably break the most code is tightening up the
arguments accepted by some methods.  Some methods would take multiple arguments
and treat them as a tuple, particularly various list methods such as
@code{append()} and @code{insert()}. In earlier versions of Python, if @code{L} is
a list, @code{L.append( 1,2 )} appends the tuple @code{(1,2)} to the list.  In Python
2.0 this causes a @ref{522,,TypeError} exception to be raised, with the message:
'append requires exactly 1 argument; 2 given'.  The fix is to simply add an
extra set of parentheses to pass both values as a tuple:  @code{L.append( (1,2) )}.

The earlier versions of these methods were more forgiving because they used an
old function in Python's C interface to parse their arguments; 2.0 modernizes
them to use @ref{55d,,PyArg_ParseTuple()}, the current argument parsing function,
which provides more helpful error messages and treats multi-argument calls as
errors.  If you absolutely must use 2.0 but can't fix your code, you can edit
@code{Objects/listobject.c} and define the preprocessor symbol
@code{NO_STRICT_LIST_APPEND} to preserve the old behaviour; this isn't recommended.

Some of the functions in the @ref{cb,,socket} module are still forgiving in this
way.  For example, @code{socket.connect( ('hostname', 25) )} is the correct
form, passing a tuple representing an IP address, but @code{socket.connect('hostname', 25)}
also works. @ref{14ef,,socket.connect_ex} and @ref{14f0,,socket.bind}
are similarly easy-going.  2.0alpha1 tightened these functions up, but because
the documentation actually used the erroneous multiple argument form, many
people wrote code which would break with the stricter checking.  GvR backed out
the changes in the face of public reaction, so for the @ref{cb,,socket} module, the
documentation was fixed and the multiple argument form is simply marked as
deprecated; it `will' be tightened up again in a future Python version.

The @code{\x} escape in string literals now takes exactly 2 hex digits.  Previously
it would consume all the hex digits following the 'x' and take the lowest 8 bits
of the result, so @code{\x123456} was equivalent to @code{\x56}.

The @ref{343,,AttributeError} and @ref{428,,NameError} exceptions have a more friendly
error message, whose text will be something like @code{'Spam' instance has no
attribute 'eggs'} or @code{name 'eggs' is not defined}.  Previously the error
message was just the missing attribute name @code{eggs}, and code written to take
advantage of this fact will break in 2.0.

Some work has been done to make integers and long integers a bit more
interchangeable.  In 1.5.2, large-file support was added for Solaris, to allow
reading files larger than 2 GiB; this made the @code{tell()} method of file
objects return a long integer instead of a regular integer.  Some code would
subtract two file offsets and attempt to use the result to multiply a sequence
or slice a string, but this raised a @ref{522,,TypeError}.  In 2.0, long integers
can be used to multiply or slice a sequence, and it'll behave as you'd
intuitively expect it to; @code{3L * 'abc'} produces 'abcabcabc', and
@code{(0,1,2,3)[2L:4L]} produces (2,3). Long integers can also be used in various
contexts where previously only integers were accepted, such as in the
@code{seek()} method of file objects, and in the formats supported by the @code{%}
operator (@code{%d}, @code{%i}, @code{%x}, etc.).  For example, @code{"%d" % 2L**64} will
produce the string @code{18446744073709551616}.

The subtlest long integer change of all is that the @ref{435,,str()} of a long
integer no longer has a trailing 'L' character, though @ref{7e7,,repr()} still
includes it.  The 'L' annoyed many people who wanted to print long integers that
looked just like regular integers, since they had to go out of their way to chop
off the character.  This is no longer a problem in 2.0, but code which does
@code{str(longval)[:-1]} and assumes the 'L' is there, will now lose the final
digit.

Taking the @ref{7e7,,repr()} of a float now uses a different formatting precision
than @ref{435,,str()}.  @ref{7e7,,repr()} uses @code{%.17g} format string for C's
@code{sprintf()}, while @ref{435,,str()} uses @code{%.12g} as before.  The effect is that
@ref{7e7,,repr()} may occasionally show more decimal places than  @ref{435,,str()}, for
certain numbers.  For example, the number 8.1 can't be represented exactly in
binary, so @code{repr(8.1)} is @code{'8.0999999999999996'}, while str(8.1) is
@code{'8.1'}.

The @code{-X} command-line option, which turned all standard exceptions into
strings instead of classes, has been removed; the standard exceptions will now
always be classes.  The @code{exceptions} module containing the standard
exceptions was translated from Python to a built-in C module, written by Barry
Warsaw and Fredrik Lundh.

@c Commented out for now -- I don't think anyone will care.
@c The pattern and match objects provided by SRE are C types, not Python
@c class instances as in 1.5.  This means you can no longer inherit from
@c \class{RegexObject} or \class{MatchObject}, but that shouldn't be much
@c of a problem since no one should have been doing that in the first
@c place.

@c ======================================================================

@node Extending/Embedding Changes,Distutils Making Modules Easy to Install,Porting to 2 0,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 extending-embedding-changes}@anchor{14f1}
@subsection Extending/Embedding Changes


Some of the changes are under the covers, and will only be apparent to people
writing C extension modules or embedding a Python interpreter in a larger
application.  If you aren't dealing with Python's C API, you can safely skip
this section.

The version number of the Python C API was incremented, so C extensions compiled
for 1.5.2 must be recompiled in order to work with 2.0.  On Windows, it's not
possible for Python 2.0 to import a third party extension built for Python 1.5.x
due to how Windows DLLs work, so Python will raise an exception and the import
will fail.

Users of Jim Fulton's ExtensionClass module will be pleased to find out that
hooks have been added so that ExtensionClasses are now supported by
@ref{42b,,isinstance()} and @ref{7ab,,issubclass()}. This means you no longer have to
remember to write code such as @code{if type(obj) == myExtensionClass}, but can use
the more natural @code{if isinstance(obj, myExtensionClass)}.

The @code{Python/importdl.c} file, which was a mass of #ifdefs to support
dynamic loading on many different platforms, was cleaned up and reorganised by
Greg Stein.  @code{importdl.c} is now quite small, and platform-specific code
has been moved into a bunch of @code{Python/dynload_*.c} files.  Another
cleanup: there were also a number of @code{my*.h} files in the Include/
directory that held various portability hacks; they've been merged into a single
file, @code{Include/pyport.h}.

Vladimir Marangozov's long-awaited malloc restructuring was completed, to make
it easy to have the Python interpreter use a custom allocator instead of C's
standard @code{malloc()}.  For documentation, read the comments in
@code{Include/pymem.h} and @code{Include/objimpl.h}.  For the lengthy
discussions during which the interface was hammered out, see the web archives of
the 'patches' and 'python-dev' lists at python.org.

Recent versions of the GUSI development environment for MacOS support POSIX
threads.  Therefore, Python's POSIX threading support now works on the
Macintosh.  Threading support using the user-space GNU @code{pth} library was also
contributed.

Threading support on Windows was enhanced, too.  Windows supports thread locks
that use kernel objects only in case of contention; in the common case when
there's no contention, they use simpler functions which are an order of
magnitude faster.  A threaded version of Python 1.5.2 on NT is twice as slow as
an unthreaded version; with the 2.0 changes, the difference is only 10%.  These
improvements were contributed by Yakov Markovitch.

Python 2.0's source now uses only ANSI C prototypes, so compiling Python now
requires an ANSI C compiler, and can no longer be done using a compiler that
only supports K&R C.

Previously the Python virtual machine used 16-bit numbers in its bytecode,
limiting the size of source files.  In particular, this affected the maximum
size of literal lists and dictionaries in Python source; occasionally people who
are generating Python code would run into this limit.  A patch by Charles G.
Waldman raises the limit from @code{2**16} to @code{2**32}.

Three new convenience functions intended for adding constants to a module's
dictionary at module initialization time were added: @ref{35c,,PyModule_AddObject()},
@ref{14f2,,PyModule_AddIntConstant()}, and @ref{14f3,,PyModule_AddStringConstant()}.  Each
of these functions takes a module object, a null-terminated C string containing
the name to be added, and a third argument for the value to be assigned to the
name.  This third argument is, respectively, a Python object, a C long, or a C
string.

A wrapper API was added for Unix-style signal handlers. @ref{14f4,,PyOS_getsig()} gets
a signal handler and @ref{14f5,,PyOS_setsig()} will set a new handler.

@c ======================================================================

@node Distutils Making Modules Easy to Install,Modules XML,Extending/Embedding Changes,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 distutils-making-modules-easy-to-install}@anchor{14f6}
@subsection Distutils: Making Modules Easy to Install


Before Python 2.0, installing modules was a tedious affair -- there was no way
to figure out automatically where Python is installed, or what compiler options
to use for extension modules.  Software authors had to go through an arduous
ritual of editing Makefiles and configuration files, which only really work on
Unix and leave Windows and MacOS unsupported.  Python users faced wildly
differing installation instructions which varied between different extension
packages, which made administering a Python installation something of  a chore.

The SIG for distribution utilities, shepherded by Greg Ward, has created the
Distutils, a system to make package installation much easier.  They form the
@code{distutils} package, a new part of Python's standard library. In the best
case, installing a Python module from source will require the same steps: first
you simply mean unpack the tarball or zip archive, and the run "@code{python
setup.py install}".  The platform will be automatically detected, the compiler
will be recognized, C extension modules will be compiled, and the distribution
installed into the proper directory.  Optional command-line arguments provide
more control over the installation process, the distutils package offers many
places to override defaults -- separating the build from the install, building
or installing in non-default directories, and more.

In order to use the Distutils, you need to write a @code{setup.py} script.  For
the simple case, when the software contains only .py files, a minimal
@code{setup.py} can be just a few lines long:

@example
from distutils.core import setup
setup (name = "foo", version = "1.0",
       py_modules = ["module1", "module2"])
@end example

The @code{setup.py} file isn't much more complicated if the software consists
of a few packages:

@example
from distutils.core import setup
setup (name = "foo", version = "1.0",
       packages = ["package", "package.subpackage"])
@end example

A C extension can be the most complicated case; here's an example taken from
the PyXML package:

@example
from distutils.core import setup, Extension

expat_extension = Extension('xml.parsers.pyexpat',
     define_macros = [('XML_NS', None)],
     include_dirs = [ 'extensions/expat/xmltok',
                      'extensions/expat/xmlparse' ],
     sources = [ 'extensions/pyexpat.c',
                 'extensions/expat/xmltok/xmltok.c',
                 'extensions/expat/xmltok/xmlrole.c', ]
       )
setup (name = "PyXML", version = "0.5.4",
       ext_modules =[ expat_extension ] )
@end example

The Distutils can also take care of creating source and binary distributions.
The "sdist" command, run by "@code{python setup.py sdist}', builds a source
distribution such as @code{foo-1.0.tar.gz}. Adding new commands isn't
difficult, "bdist_rpm" and "bdist_wininst" commands have already been
contributed to create an RPM distribution and a Windows installer for the
software, respectively.  Commands to create other distribution formats such as
Debian packages and Solaris @code{.pkg} files are in various stages of
development.

All this is documented in a new manual, `Distributing Python Modules', that
joins the basic set of Python documentation.

@c ======================================================================

@node Modules XML,Module changes,Distutils Making Modules Easy to Install,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 xml-modules}@anchor{14f7}
@subsection Modules XML


Python 1.5.2 included a simple XML parser in the form of the @code{xmllib}
module, contributed by Sjoerd Mullender.  Since 1.5.2's release, two different
interfaces for processing XML have become common: SAX2 (version 2 of the Simple
API for XML) provides an event-driven interface with some similarities to
@code{xmllib}, and the DOM (Document Object Model) provides a tree-based
interface, transforming an XML document into a tree of nodes that can be
traversed and modified.  Python 2.0 includes a SAX2 interface and a stripped-down
DOM interface as part of the @ref{11f,,xml} package. Here we will give a brief
overview of these new interfaces; consult the Python documentation or the source
code for complete details. The Python XML SIG is also working on improved
documentation.

@menu
* Support de SAX2:: 
* Support du DOM:: 
* Relationship to PyXML:: 

@end menu

@node Support de SAX2,Support du DOM,,Modules XML
@anchor{whatsnew/2 0 sax2-support}@anchor{14f8}
@subsubsection Support de SAX2


SAX defines an event-driven interface for parsing XML.  To use SAX, you must
write a SAX handler class.  Handler classes inherit from various classes
provided by SAX, and override various methods that will then be called by the
XML parser.  For example, the @ref{14f9,,startElement()} and @ref{14fa,,endElement()}
methods are called for every starting and end tag encountered by the parser, the
@ref{14fb,,characters()} method is called for every chunk of character data, and so
forth.

The advantage of the event-driven approach is that the whole document doesn't
have to be resident in memory at any one time, which matters if you are
processing really huge documents.  However, writing the SAX handler class can
get very complicated if you're trying to modify the document structure in some
elaborate way.

For example, this little example program defines a handler that prints a message
for every starting and ending tag, and then parses the file @code{hamlet.xml}
using it:

@example
from xml import sax

class SimpleHandler(sax.ContentHandler):
    def startElement(self, name, attrs):
        print 'Start of element:', name, attrs.keys()

    def endElement(self, name):
        print 'End of element:', name

# Create a parser object
parser = sax.make_parser()

# Tell it what handler to use
handler = SimpleHandler()
parser.setContentHandler( handler )

# Parse a file!
parser.parse( 'hamlet.xml' )
@end example

For more information, consult the Python documentation, or the XML HOWTO at
@indicateurl{https://pyxml.sourceforge.net/topics/howto/xml-howto.html}.

@node Support du DOM,Relationship to PyXML,Support de SAX2,Modules XML
@anchor{whatsnew/2 0 dom-support}@anchor{14fc}
@subsubsection Support du DOM


The Document Object Model is a tree-based representation for an XML document.  A
top-level @code{Document} instance is the root of the tree, and has a single
child which is the top-level @code{Element} instance. This @code{Element}
has children nodes representing character data and any sub-elements, which may
have further children of their own, and so forth.  Using the DOM you can
traverse the resulting tree any way you like, access element and attribute
values, insert and delete nodes, and convert the tree back into XML.

The DOM is useful for modifying XML documents, because you can create a DOM
tree, modify it by adding new nodes or rearranging subtrees, and then produce a
new XML document as output.  You can also construct a DOM tree manually and
convert it to XML, which can be a more flexible way of producing XML output than
simply writing @code{<tag1>}...@code{</tag1>} to a file.

The DOM implementation included with Python lives in the @ref{121,,xml.dom.minidom}
module.  It's a lightweight implementation of the Level 1 DOM with support for
XML namespaces.  The  @code{parse()} and @code{parseString()} convenience
functions are provided for generating a DOM tree:

@example
from xml.dom import minidom
doc = minidom.parse('hamlet.xml')
@end example

@code{doc} is a @code{Document} instance.  @code{Document}, like all the other
DOM classes such as @code{Element} and @code{Text}, is a subclass of the
@code{Node} base class.  All the nodes in a DOM tree therefore support certain
common methods, such as @code{toxml()} which returns a string containing the XML
representation of the node and its children.  Each class also has special
methods of its own; for example, @code{Element} and @code{Document}
instances have a method to find all child elements with a given tag name.
Continuing from the previous 2-line example:

@example
perslist = doc.getElementsByTagName( 'PERSONA' )
print perslist[0].toxml()
print perslist[1].toxml()
@end example

For the `Hamlet' XML file, the above few lines output:

@example
<PERSONA>CLAUDIUS, king of Denmark. </PERSONA>
<PERSONA>HAMLET, son to the late, and nephew to the present king.</PERSONA>
@end example

The root element of the document is available as @code{doc.documentElement}, and
its children can be easily modified by deleting, adding, or removing nodes:

@example
root = doc.documentElement

# Remove the first child
root.removeChild( root.childNodes[0] )

# Move the new first child to the end
root.appendChild( root.childNodes[0] )

# Insert the new first child (originally,
# the third child) before the 20th child.
root.insertBefore( root.childNodes[0], root.childNodes[20] )
@end example

Again, I will refer you to the Python documentation for a complete listing of
the different @code{Node} classes and their various methods.

@node Relationship to PyXML,,Support du DOM,Modules XML
@anchor{whatsnew/2 0 relationship-to-pyxml}@anchor{14fd}
@subsubsection Relationship to PyXML


The XML Special Interest Group has been working on XML-related Python code for a
while.  Its code distribution, called PyXML, is available from the SIG's web
pages at @indicateurl{https://www.python.org/community/sigs/current/xml-sig}. The PyXML distribution also used
the package name @code{xml}.  If you've written programs that used PyXML, you're
probably wondering about its compatibility with the 2.0 @ref{11f,,xml} package.

The answer is that Python 2.0's @ref{11f,,xml} package isn't compatible with PyXML,
but can be made compatible by installing a recent version PyXML.  Many
applications can get by with the XML support that is included with Python 2.0,
but more complicated applications will require that the full PyXML package will
be installed.  When installed, PyXML versions 0.6.0 or greater will replace the
@ref{11f,,xml} package shipped with Python, and will be a strict superset of the
standard package, adding a bunch of additional features.  Some of the additional
features in PyXML include:


@itemize *

@item 
4DOM, a full DOM implementation from FourThought, Inc.

@item 
The xmlproc validating parser, written by Lars Marius Garshol.

@item 
The @code{sgmlop} parser accelerator module, written by Fredrik Lundh.
@end itemize

@c ======================================================================

@node Module changes,Nouveaux modules<12>,Modules XML,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 module-changes}@anchor{14fe}
@subsection Module changes


Lots of improvements and bugfixes were made to Python's extensive standard
library; some of the affected modules include @ref{b9,,readline},
@ref{22,,ConfigParser}, @code{cgi}, @ref{14,,calendar}, @ref{ac,,posix}, @ref{b9,,readline},
@code{xmllib}, @code{aifc}, @code{chunk}, @ref{112,,wave}, @ref{b7,,random}, @ref{c2,,shelve},
and @code{nntplib}.  Consult the CVS logs for the exact patch-by-patch details.

Brian Gallew contributed OpenSSL support for the @ref{cb,,socket} module.  OpenSSL
is an implementation of the Secure Socket Layer, which encrypts the data being
sent over a socket.  When compiling Python, you can edit @code{Modules/Setup}
to include SSL support, which adds an additional function to the @ref{cb,,socket}
module: @code{socket.ssl(socket, keyfile, certfile)}, which takes a socket
object and returns an SSL socket.  The @ref{6d,,httplib} and @ref{107,,urllib} modules
were also changed to support @code{https://} URLs, though no one has implemented
FTP or SMTP over SSL.

The @ref{6d,,httplib} module has been rewritten by Greg Stein to support HTTP/1.1.

Backward compatibility with the 1.5 version of @code{httplib} is provided,
though using HTTP/1.1 features such as pipelining will require rewriting code to
use a different set of interfaces.

The @code{Tkinter} module now supports Tcl/Tk version 8.1, 8.2, or 8.3, and
support for the older 7.x versions has been dropped.  The Tkinter module now
supports displaying Unicode strings in Tk widgets. Also, Fredrik Lundh
contributed an optimization which makes operations like @code{create_line} and
@code{create_polygon} much faster, especially when using lots of coordinates.

The @ref{2b,,curses} module has been greatly extended, starting from Oliver
Andrich's enhanced version, to provide many additional functions from ncurses
and SYSV curses, such as colour, alternative character set support, pads, and
mouse support.  This means the module is no longer compatible with operating
systems that only have BSD curses, but there don't seem to be any currently
maintained OSes that fall into this category.

As mentioned in the earlier discussion of 2.0's Unicode support, the underlying
implementation of the regular expressions provided by the @ref{b8,,re} module has
been changed.  SRE, a new regular expression engine written by Fredrik Lundh and
partially funded by Hewlett Packard, supports matching against both 8-bit
strings and Unicode strings.

@c ======================================================================

@node Nouveaux modules<12>,IDLE Improvements,Module changes,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 new-modules}@anchor{14ff}
@subsection Nouveaux modules


A number of new modules were added.  We'll simply list them with brief
descriptions; consult the 2.0 documentation for the details of a particular
module.


@itemize *

@item 
@ref{c,,atexit}:  For registering functions to be called before the Python
interpreter exits. Code that currently sets @code{sys.exitfunc} directly should be
changed to  use the @ref{c,,atexit} module instead, importing @ref{c,,atexit} and
calling @ref{869,,atexit.register()} with  the function to be called on exit.
(Contributed by Skip Montanaro.)

@item 
@ref{1b,,codecs}, @code{encodings}, @ref{104,,unicodedata}:  Added as part of the new
Unicode support.

@item 
@ref{59,,filecmp}: Supersedes the old @code{cmp}, @code{cmpcache} and
@code{dircmp} modules, which have now become deprecated. (Contributed by Gordon
MacMillan and Moshe Zadka.)

@item 
@ref{62,,gettext}: This module provides internationalization (I18N) and
localization (L10N) support for Python programs by providing an interface to the
GNU gettext message catalog library. (Integrated by Barry Warsaw, from separate
contributions by Martin  von Löwis, Peter Funk, and James Henstridge.)

@item 
@code{linuxaudiodev}: Support for the @code{/dev/audio} device on Linux, a
twin to the existing @code{sunaudiodev} module. (Contributed by Peter Bosch,
with fixes by Jeremy Hylton.)

@item 
@ref{8f,,mmap}: An interface to memory-mapped files on both Windows and Unix.  A
file's contents can be mapped directly into memory, at which point it behaves
like a mutable string, so its contents can be read and modified.  They can even
be passed to functions that expect ordinary strings, such as the @ref{b8,,re}
module. (Contributed by Sam Rushing, with some extensions by A.M. Kuchling.)

@item 
@code{pyexpat}: An interface to the Expat XML parser. (Contributed by Paul
Prescod.)

@item 
@ref{10c,,robotparser}: Parse a @code{robots.txt} file, which is used for writing
web spiders that politely avoid certain areas of a web site.  The parser accepts
the contents of a @code{robots.txt} file, builds a set of rules from it, and
can then answer questions about the fetchability of a given URL.  (Contributed
by Skip Montanaro.)

@item 
@ref{dc,,tabnanny}: A module/script to  check Python source code for ambiguous
indentation. (Contributed by Tim Peters.)

@item 
@code{UserString}: A base class useful for deriving objects that behave like
strings.

@item 
@ref{114,,webbrowser}: A module that provides a platform independent way to launch
a web browser on a specific URL. For each platform, various browsers are tried
in a specific order. The user can alter which browser is launched by setting the
`BROWSER' environment variable.  (Originally inspired by Eric S. Raymond's patch
to @ref{107,,urllib} which added similar functionality, but the final module comes
from code originally  implemented by Fred Drake as
@code{Tools/idle/BrowserControl.py}, and adapted for the standard library by
Fred.)

@item 
@ref{115,,_winreg}: An interface to the Windows registry.  @code{_winreg} is an
adaptation of functions that have been part of PythonWin since 1995, but has now
been added to the core  distribution, and enhanced to support Unicode.
@code{_winreg} was written by Bill Tutt and Mark Hammond.

@item 
@ref{130,,zipfile}: A module for reading and writing ZIP-format archives.  These
are archives produced by @code{PKZIP} on DOS/Windows or @code{zip} on
Unix, not to be confused with @code{gzip}-format files (which are
supported by the @ref{66,,gzip} module) (Contributed by James C. Ahlstrom.)

@item 
@code{imputil}: A module that provides a simpler way for writing customized
import hooks, in comparison to the existing @code{ihooks} module.  (Implemented
by Greg Stein, with much discussion on python-dev along the way.)
@end itemize

@c ======================================================================

@node IDLE Improvements,Deleted and Deprecated Modules,Nouveaux modules<12>,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 idle-improvements}@anchor{1500}
@subsection IDLE Improvements


IDLE is the official Python cross-platform IDE, written using Tkinter. Python
2.0 includes IDLE 0.6, which adds a number of new features and improvements.  A
partial list:


@itemize *

@item 
UI improvements and optimizations, especially in the area of syntax
highlighting and auto-indentation.

@item 
The class browser now shows more information, such as the top level functions
in a module.

@item 
Tab width is now a user settable option. When opening an existing Python file,
IDLE automatically detects the indentation conventions, and adapts.

@item 
There is now support for calling browsers on various platforms, used to open
the Python documentation in a browser.

@item 
IDLE now has a command line, which is largely similar to  the vanilla Python
interpreter.

@item 
Call tips were added in many places.

@item 
IDLE can now be installed as a package.

@item 
In the editor window, there is now a line/column bar at the bottom.

@item 
Three new keystroke commands: Check module (@code{Alt-F5}), Import module (@code{F5}) and
Run script (@code{Ctrl-F5}).
@end itemize

@c ======================================================================

@node Deleted and Deprecated Modules,Remerciements<8>,IDLE Improvements,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 deleted-and-deprecated-modules}@anchor{1501}
@subsection Deleted and Deprecated Modules


A few modules have been dropped because they're obsolete, or because there are
now better ways to do the same thing.  The @code{stdwin} module is gone; it was
for a platform-independent windowing toolkit that's no longer developed.

A number of modules have been moved to the @code{lib-old} subdirectory:
@code{cmp}, @code{cmpcache}, @code{dircmp}, @code{dump},  @code{find},
@code{grep}, @code{packmail},  @code{poly}, @code{util}, @code{whatsound},
@code{zmod}.  If you have code which relies on a module  that's been moved to
@code{lib-old}, you can simply add that directory to @code{sys.path}   to get them
back, but you're encouraged to update any code that uses these modules.

@node Remerciements<8>,,Deleted and Deprecated Modules,Nouveautés de Python 2 0
@anchor{whatsnew/2 0 acknowledgements}@anchor{1502}
@subsection Remerciements


The authors would like to thank the following people for offering suggestions on
various drafts of this article: David Bolen, Mark Hammond, Gregg Hauser, Jeremy
Hylton, Fredrik Lundh, Detlef Lannert, Aahz Maruch, Skip Montanaro, Vladimir
Marangozov, Tobias Polzin, Guido van Rossum, Neil Schemenauer, and Russ Schmidt.

The "Changelog" is an HTML version of the file built@footnote{https://pypi.org/project/blurb/}
from the contents of the
Misc/NEWS.d@footnote{https://github.com/python/cpython/tree/3.13/Misc/NEWS.d} directory tree, which contains `all' nontrivial changes
to Python for the current version.

@node Changelog,,Nouveautés de Python 2 0,Nouveautés de Python
@anchor{whatsnew/changelog doc}@anchor{1503}@anchor{whatsnew/changelog changelog}@anchor{13b}@anchor{whatsnew/changelog id1}@anchor{1504}
@section Changelog


@menu
* Python next:: 
* Python 3.13.1 final: Python 3 13 1 final. 
* Python 3.13.0 final: Python 3 13 0 final. 
* Python 3.13.0 release candidate 3: Python 3 13 0 release candidate 3. 
* Python 3.13.0 release candidate 2: Python 3 13 0 release candidate 2. 
* Python 3.13.0 release candidate 1: Python 3 13 0 release candidate 1. 
* Python 3.13.0 beta 4: Python 3 13 0 beta 4. 
* Python 3.13.0 beta 3: Python 3 13 0 beta 3. 
* Python 3.13.0 beta 2: Python 3 13 0 beta 2. 
* Python 3.13.0 beta 1: Python 3 13 0 beta 1. 
* Python 3.13.0 alpha 6: Python 3 13 0 alpha 6. 
* Python 3.13.0 alpha 5: Python 3 13 0 alpha 5. 
* Python 3.13.0 alpha 4: Python 3 13 0 alpha 4. 
* Python 3.13.0 alpha 3: Python 3 13 0 alpha 3. 
* Python 3.13.0 alpha 2: Python 3 13 0 alpha 2. 
* Python 3.13.0 alpha 1: Python 3 13 0 alpha 1. 
* Python 3.12.0 beta 1: Python 3 12 0 beta 1. 
* Python 3.12.0 alpha 7: Python 3 12 0 alpha 7. 
* Python 3.12.0 alpha 6: Python 3 12 0 alpha 6. 
* Python 3.12.0 alpha 5: Python 3 12 0 alpha 5. 
* Python 3.12.0 alpha 4: Python 3 12 0 alpha 4. 
* Python 3.12.0 alpha 3: Python 3 12 0 alpha 3. 
* Python 3.12.0 alpha 2: Python 3 12 0 alpha 2. 
* Python 3.12.0 alpha 1: Python 3 12 0 alpha 1. 
* Python 3.11.0 beta 1: Python 3 11 0 beta 1. 
* Python 3.11.0 alpha 7: Python 3 11 0 alpha 7. 
* Python 3.11.0 alpha 6: Python 3 11 0 alpha 6. 
* Python 3.11.0 alpha 5: Python 3 11 0 alpha 5. 
* Python 3.11.0 alpha 4: Python 3 11 0 alpha 4. 
* Python 3.11.0 alpha 3: Python 3 11 0 alpha 3. 
* Python 3.11.0 alpha 2: Python 3 11 0 alpha 2. 
* Python 3.11.0 alpha 1: Python 3 11 0 alpha 1. 
* Python 3.10.0 beta 1: Python 3 10 0 beta 1. 
* Python 3.10.0 alpha 7: Python 3 10 0 alpha 7. 
* Python 3.10.0 alpha 6: Python 3 10 0 alpha 6. 
* Python 3.10.0 alpha 5: Python 3 10 0 alpha 5. 
* Python 3.10.0 alpha 4: Python 3 10 0 alpha 4. 
* Python 3.10.0 alpha 3: Python 3 10 0 alpha 3. 
* Python 3.10.0 alpha 2: Python 3 10 0 alpha 2. 
* Python 3.10.0 alpha 1: Python 3 10 0 alpha 1. 
* Python 3.9.0 beta 1: Python 3 9 0 beta 1. 
* Python 3.9.0 alpha 6: Python 3 9 0 alpha 6. 
* Python 3.9.0 alpha 5: Python 3 9 0 alpha 5. 
* Python 3.9.0 alpha 4: Python 3 9 0 alpha 4. 
* Python 3.9.0 alpha 3: Python 3 9 0 alpha 3. 
* Python 3.9.0 alpha 2: Python 3 9 0 alpha 2. 
* Python 3.9.0 alpha 1: Python 3 9 0 alpha 1. 
* Python 3.8.0 beta 1: Python 3 8 0 beta 1. 
* Python 3.8.0 alpha 4: Python 3 8 0 alpha 4. 
* Python 3.8.0 alpha 3: Python 3 8 0 alpha 3. 
* Python 3.8.0 alpha 2: Python 3 8 0 alpha 2. 
* Python 3.8.0 alpha 1: Python 3 8 0 alpha 1. 
* Python 3.7.0 final: Python 3 7 0 final. 
* Python 3.7.0 release candidate 1: Python 3 7 0 release candidate 1. 
* Python 3.7.0 beta 5: Python 3 7 0 beta 5. 
* Python 3.7.0 beta 4: Python 3 7 0 beta 4. 
* Python 3.7.0 beta 3: Python 3 7 0 beta 3. 
* Python 3.7.0 beta 2: Python 3 7 0 beta 2. 
* Python 3.7.0 beta 1: Python 3 7 0 beta 1. 
* Python 3.7.0 alpha 4: Python 3 7 0 alpha 4. 
* Python 3.7.0 alpha 3: Python 3 7 0 alpha 3. 
* Python 3.7.0 alpha 2: Python 3 7 0 alpha 2. 
* Python 3.7.0 alpha 1: Python 3 7 0 alpha 1. 
* Python 3.6.6 final: Python 3 6 6 final. 
* Python 3.6.6 release candidate 1: Python 3 6 6 release candidate 1. 
* Python 3.6.5 final: Python 3 6 5 final. 
* Python 3.6.5 release candidate 1: Python 3 6 5 release candidate 1. 
* Python 3.6.4 final: Python 3 6 4 final. 
* Python 3.6.4 release candidate 1: Python 3 6 4 release candidate 1. 
* Python 3.6.3 final: Python 3 6 3 final. 
* Python 3.6.3 release candidate 1: Python 3 6 3 release candidate 1. 
* Python 3.6.2 final: Python 3 6 2 final. 
* Python 3.6.2 release candidate 2: Python 3 6 2 release candidate 2. 
* Python 3.6.2 release candidate 1: Python 3 6 2 release candidate 1. 
* Python 3.6.1 final: Python 3 6 1 final. 
* Python 3.6.1 release candidate 1: Python 3 6 1 release candidate 1. 
* Python 3.6.0 final: Python 3 6 0 final. 
* Python 3.6.0 release candidate 2: Python 3 6 0 release candidate 2. 
* Python 3.6.0 release candidate 1: Python 3 6 0 release candidate 1. 
* Python 3.6.0 beta 4: Python 3 6 0 beta 4. 
* Python 3.6.0 beta 3: Python 3 6 0 beta 3. 
* Python 3.6.0 beta 2: Python 3 6 0 beta 2. 
* Python 3.6.0 beta 1: Python 3 6 0 beta 1. 
* Python 3.6.0 alpha 4: Python 3 6 0 alpha 4. 
* Python 3.6.0 alpha 3: Python 3 6 0 alpha 3. 
* Python 3.6.0 alpha 2: Python 3 6 0 alpha 2. 
* Python 3.6.0 alpha 1: Python 3 6 0 alpha 1. 
* Python 3.5.5 final: Python 3 5 5 final. 
* Python 3.5.5 release candidate 1: Python 3 5 5 release candidate 1. 
* Python 3.5.4 final: Python 3 5 4 final. 
* Python 3.5.4 release candidate 1: Python 3 5 4 release candidate 1. 
* Python 3.5.3 final: Python 3 5 3 final. 
* Python 3.5.3 release candidate 1: Python 3 5 3 release candidate 1. 
* Python 3.5.2 final: Python 3 5 2 final. 
* Python 3.5.2 release candidate 1: Python 3 5 2 release candidate 1. 
* Python 3.5.1 final: Python 3 5 1 final. 
* Python 3.5.1 release candidate 1: Python 3 5 1 release candidate 1. 
* Python 3.5.0 final: Python 3 5 0 final. 
* Python 3.5.0 release candidate 4: Python 3 5 0 release candidate 4. 
* Python 3.5.0 release candidate 3: Python 3 5 0 release candidate 3. 
* Python 3.5.0 release candidate 2: Python 3 5 0 release candidate 2. 
* Python 3.5.0 release candidate 1: Python 3 5 0 release candidate 1. 
* Python 3.5.0 beta 4: Python 3 5 0 beta 4. 
* Python 3.5.0 beta 3: Python 3 5 0 beta 3. 
* Python 3.5.0 beta 2: Python 3 5 0 beta 2. 
* Python 3.5.0 beta 1: Python 3 5 0 beta 1. 
* Python 3.5.0 alpha 4: Python 3 5 0 alpha 4. 
* Python 3.5.0 alpha 3: Python 3 5 0 alpha 3. 
* Python 3.5.0 alpha 2: Python 3 5 0 alpha 2. 
* Python 3.5.0 alpha 1: Python 3 5 0 alpha 1. 

@end menu

@node Python next,Python 3 13 1 final,,Changelog
@anchor{whatsnew/changelog python-next}@anchor{1505}
@subsection Python next


`Release date: XXXX-XX-XX'

@menu
* Windows:: 
* Tools/Demos:: 
* Tests:: 
* Security:: 
* Library:: 
* Core and Builtins:: 
* C API:: 
* Build:: 

@end menu

@node Windows,Tools/Demos,,Python next
@anchor{whatsnew/changelog windows}@anchor{1506}
@subsubsection Windows



@itemize -

@item 
gh-127353@footnote{https://github.com/python/cpython/issues/127353}: Allow to force color output on Windows using environment
variables. Patch by Andrey Efremov.
@end itemize

@node Tools/Demos,Tests,Windows,Python next
@anchor{whatsnew/changelog tools-demos}@anchor{1507}
@subsubsection Tools/Demos



@itemize -

@item 
gh-128152@footnote{https://github.com/python/cpython/issues/128152}: Fix a bug where Argument Clinic's C pre-processor parser tried
to parse pre-processor directives inside C comments. Patch by Erlend
Aasland.
@end itemize

@node Tests,Security,Tools/Demos,Python next
@anchor{whatsnew/changelog tests}@anchor{1508}
@subsubsection Tests



@itemize -

@item 
gh-127906@footnote{https://github.com/python/cpython/issues/127906}: Test the limited C API in test_cppext. Patch by Victor Stinner.

@item 
gh-127637@footnote{https://github.com/python/cpython/issues/127637}: Add tests for the @ref{38,,dis} command-line interface. Patch by
Bénédikt Tran.

@item 
gh-126925@footnote{https://github.com/python/cpython/issues/126925}: iOS test results are now streamed during test execution, and
the deprecated xcresulttool is no longer used.
@end itemize

@node Security,Library,Tests,Python next
@anchor{whatsnew/changelog security}@anchor{1509}
@subsubsection Security



@itemize -

@item 
gh-127655@footnote{https://github.com/python/cpython/issues/127655}: Fixed the
@code{asyncio.selector_events._SelectorSocketTransport} transport not
pausing writes for the protocol when the buffer reaches the high water
mark when using @ref{150a,,asyncio.WriteTransport.writelines()}.
@end itemize

@node Library,Core and Builtins,Security,Python next
@anchor{whatsnew/changelog library}@anchor{150b}
@subsubsection Library



@itemize -

@item 
gh-128400@footnote{https://github.com/python/cpython/issues/128400}: Fix crash when using @ref{deb,,faulthandler.dump_traceback()} while
other threads are active on the @ref{150c,,free threaded}
build.

@item 
gh-88834@footnote{https://github.com/python/cpython/issues/88834}: Unify the instance check for @ref{626,,typing.Union} and
@ref{625,,types.UnionType}: @code{Union} now uses the instance checks
against its parameters instead of the subclass checks.

@item 
gh-112328@footnote{https://github.com/python/cpython/issues/112328}: @ref{1e1,,enum.EnumDict} can now be used without resorting to
private API.

@item 
gh-128062@footnote{https://github.com/python/cpython/issues/128062}: Revert the font of @ref{101,,turtledemo}'s menu bar to its default
value and display the shortcut keys in the correct position.

@item 
gh-128014@footnote{https://github.com/python/cpython/issues/128014}: Fix resetting the default window icon by passing @code{default='@w{'}}
to the @ref{ef,,tkinter} method @code{wm_iconbitmap()}.

@item 
gh-127060@footnote{https://github.com/python/cpython/issues/127060}: Set TERM environment variable to "dumb" to disable traceback
colors in IDLE, since IDLE doesn't understand ANSI escape sequences. Patch
by Victor Stinner.

@item 
gh-126742@footnote{https://github.com/python/cpython/issues/126742}: Fix support of localized error messages reported by
@code{dlerror(3)@footnote{https://manpages.debian.org/dlerror(3)}} and @code{gdbm_strerror@footnote{https://manpages.debian.org/gdbm(3)}} in
@ref{2a,,ctypes} and @ref{33,,dbm.gnu} functions respectively. Patch by Bénédikt
Tran.

@item 
gh-127870@footnote{https://github.com/python/cpython/issues/127870}: Detect recursive calls in ctypes @code{_as_parameter_} handling.
Patch by Victor Stinner.

@item 
gh-127847@footnote{https://github.com/python/cpython/issues/127847}: Fix the position when doing interleaved seeks and reads in
uncompressed, unencrypted zip files returned by
@ref{411,,zipfile.ZipFile.open()}.

@item 
gh-127732@footnote{https://github.com/python/cpython/issues/127732}: The @ref{a9,,platform} module now correctly detects Windows Server
2025.

@item 
gh-126821@footnote{https://github.com/python/cpython/issues/126821}: macOS and iOS apps can now choose to redirect stdout and stderr
to the system log during interpreter configuration.

@item 
gh-93312@footnote{https://github.com/python/cpython/issues/93312}: Include @code{<sys/pidfd.h>} to get @code{os.PIDFD_NONBLOCK} constant.
Patch by Victor Stinner.

@item 
gh-83662@footnote{https://github.com/python/cpython/issues/83662}: Add missing @code{__class_getitem__} method to the Python
implementation of @ref{40a,,functools.partial()}, to make it compatible with
the C version. This is mainly relevant for alternative Python
implementations like PyPy and GraalPy, because CPython will usually use
the C-implementation of that function.

@item 
gh-127586@footnote{https://github.com/python/cpython/issues/127586}: @ref{f56,,multiprocessing.pool.Pool} now properly restores
blocked signal handlers of the parent thread when creating processes via
either `spawn' or `forkserver'.

@item 
gh-127257@footnote{https://github.com/python/cpython/issues/127257}: In @ref{cf,,ssl}, system call failures that OpenSSL reports using
@code{ERR_LIB_SYS} are now raised as @ref{40d,,OSError}.

@item 
gh-126775@footnote{https://github.com/python/cpython/issues/126775}: Make @ref{150d,,linecache.checkcache()} thread safe and GC
re-entrancy safe.

@item 
gh-126225@footnote{https://github.com/python/cpython/issues/126225}: @ref{60,,getopt} and @ref{9f,,optparse} are no longer marked as
deprecated. There are legitimate reasons to use one of these modules in
preference to @ref{6,,argparse}, and none of these modules are at risk of
being removed from the standard library. Of the three, @code{argparse}
remains the recommended default choice, `unless' one of the concerns noted
at the top of the @code{optparse} module documentation applies.

@item 
gh-123401@footnote{https://github.com/python/cpython/issues/123401}: The @ref{70,,http.cookies} module now supports parsing obsolete
@geindex RFC; RFC 850
RFC 850@footnote{https://datatracker.ietf.org/doc/html/rfc850.html} date formats, in accordance with 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html} requirements.
Patch by Nano Zheng.

@item 
gh-122431@footnote{https://github.com/python/cpython/issues/122431}: @ref{e3a,,readline.append_history_file()} now raises a
@ref{1ff,,ValueError} when given a negative value.
@end itemize

@node Core and Builtins,C API,Library,Python next
@anchor{whatsnew/changelog core-and-builtins}@anchor{150e}
@subsubsection Core and Builtins



@itemize -

@item 
gh-128079@footnote{https://github.com/python/cpython/issues/128079}: Fix a bug where @ref{5a2,,except*} does not
properly check the return value of an @ref{1b4,,ExceptionGroup}'s
@ref{150f,,split()} function, leading to a crash in some
cases. Now when @ref{150f,,split()} returns an invalid
object, @ref{5a2,,except*} raises a @ref{522,,TypeError} with
the original raised @ref{1b4,,ExceptionGroup} object chained to it.

@item 
gh-128030@footnote{https://github.com/python/cpython/issues/128030}: Avoid error from calling @code{PyModule_GetFilenameObject} on a
non-module object when importing a non-existent symbol from a non-module
object.

@item 
gh-127903@footnote{https://github.com/python/cpython/issues/127903}: @code{Objects/unicodeobject.c}: fix a crash on DEBUG builds in
@code{_copy_characters} when there is nothing to copy.

@item 
gh-127651@footnote{https://github.com/python/cpython/issues/127651}: When raising @ref{40f,,ImportError} for missing symbols in @code{from}
imports, use @code{__file__} in the error message if @code{__spec__.origin} is
not a location

@item 
gh-127582@footnote{https://github.com/python/cpython/issues/127582}: Fix non-thread-safe object resurrection when calling finalizers
and watcher callbacks in the free threading build.

@item 
gh-127434@footnote{https://github.com/python/cpython/issues/127434}: The iOS compiler shims can now accept arguments with spaces.

@item 
gh-127536@footnote{https://github.com/python/cpython/issues/127536}: Add missing locks around some list assignment operations in the
free threading build.

@item 
gh-126076@footnote{https://github.com/python/cpython/issues/126076}: Relocated objects such as @code{tuple}, @code{bytes} and @code{str}
objects are properly tracked by @ref{fe,,tracemalloc} and its associated
hooks. Patch by Pablo Galindo.
@end itemize

@node C API,Build,Core and Builtins,Python next
@anchor{whatsnew/changelog c-api}@anchor{1510}
@subsubsection C API



@itemize -

@item 
gh-127791@footnote{https://github.com/python/cpython/issues/127791}: Fix loss of callbacks after more than one call to
@ref{1511,,PyUnstable_AtExit()}.
@end itemize

@node Build,,C API,Python next
@anchor{whatsnew/changelog build}@anchor{1512}
@subsubsection Build



@itemize -

@item 
gh-123925@footnote{https://github.com/python/cpython/issues/123925}: Fix building the @ref{2b,,curses} module on platforms with
libncurses but without libncursesw.

@item 
gh-128321@footnote{https://github.com/python/cpython/issues/128321}: Set @code{LIBS} instead of @code{LDFLAGS} when checking if
@ref{ce,,sqlite3} library functions are available. This fixes the ordering of
linked libraries during checks, which was incorrect when using a
statically linked @code{libsqlite3}.

@item 
gh-127865@footnote{https://github.com/python/cpython/issues/127865}: Fix build failure on systems without thread-locals support.
@end itemize

@node Python 3 13 1 final,Python 3 13 0 final,Python next,Changelog
@anchor{whatsnew/changelog python-3-13-1-final}@anchor{1513}
@subsection Python 3.13.1 final


`Release date: 2024-12-03'

@menu
* macOS:: 
* Windows: Windows<2>. 
* Tools/Demos: Tools/Demos<2>. 
* Tests: Tests<2>. 
* Security: Security<2>. 
* Library: Library<2>. 
* IDLE: IDLE<3>. 
* Documentation: Documentation<2>. 
* Core and Builtins: Core and Builtins<2>. 
* C API: C API<2>. 
* Build: Build<2>. 

@end menu

@node macOS,Windows<2>,,Python 3 13 1 final
@anchor{whatsnew/changelog macos}@anchor{1514}
@subsubsection macOS



@itemize -

@item 
gh-124448@footnote{https://github.com/python/cpython/issues/124448}: Update bundled Tcl/Tk in macOS installer to 8.6.15.
@end itemize

@node Windows<2>,Tools/Demos<2>,macOS,Python 3 13 1 final
@anchor{whatsnew/changelog id2}@anchor{1515}
@subsubsection Windows



@itemize -

@item 
gh-126911@footnote{https://github.com/python/cpython/issues/126911}: Update credits command output.

@item 
gh-118973@footnote{https://github.com/python/cpython/issues/118973}: Ensures the experimental free-threaded install includes the
@code{_tkinter} module. The optional Tcl/Tk component must also be installed
in order for the module to work.

@item 
gh-126497@footnote{https://github.com/python/cpython/issues/126497}: Fixes venv failure due to missing redirector executables in
experimental free-threaded installs.

@item 
gh-126074@footnote{https://github.com/python/cpython/issues/126074}: Removed unnecessary DLLs from Windows embeddable package

@item 
gh-125315@footnote{https://github.com/python/cpython/issues/125315}: Avoid crashing in @ref{a9,,platform} due to slow WMI calls on some
Windows machines.

@item 
gh-126084@footnote{https://github.com/python/cpython/issues/126084}: Fix venvwlauncher to launch pythonw instead of python so no
extra console window is created.

@item 
gh-125842@footnote{https://github.com/python/cpython/issues/125842}: Fix a @ref{561,,SystemError} when @ref{1327,,sys.exit()} is called with
@code{0xffffffff} on Windows.

@item 
gh-125550@footnote{https://github.com/python/cpython/issues/125550}: Enable the @ref{5a8,,Lanceur Python pour Windows} to detect Python 3.14 installs from
the Windows Store.

@item 
gh-124448@footnote{https://github.com/python/cpython/issues/124448}: Updated bundled Tcl/Tk to 8.6.15.
@end itemize

@node Tools/Demos<2>,Tests<2>,Windows<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id3}@anchor{1516}
@subsubsection Tools/Demos



@itemize -

@item 
gh-126807@footnote{https://github.com/python/cpython/issues/126807}: Fix extraction warnings in @code{pygettext.py} caused by
mistaking function definitions for function calls.

@item 
gh-126167@footnote{https://github.com/python/cpython/issues/126167}: The iOS testbed was modified so that it can be used by
third-party projects for testing purposes.
@end itemize

@node Tests<2>,Security<2>,Tools/Demos<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id4}@anchor{1517}
@subsubsection Tests



@itemize -

@item 
gh-126909@footnote{https://github.com/python/cpython/issues/126909}: Fix test_os extended attribute tests to work on filesystems
with 1 KiB xattr size limit.

@item 
gh-125041@footnote{https://github.com/python/cpython/issues/125041}: Re-enable skipped tests for @ref{132,,zlib} on the s390x
architecture: only skip checks of the compressed bytes, which can be
different between zlib's software implementation and the
hardware-accelerated implementation.

@item 
gh-124295@footnote{https://github.com/python/cpython/issues/124295}: Add translation tests to the @ref{6,,argparse} module.
@end itemize

@node Security<2>,Library<2>,Tests<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id5}@anchor{1518}
@subsubsection Security



@itemize -

@item 
gh-126623@footnote{https://github.com/python/cpython/issues/126623}: Upgrade libexpat to 2.6.4

@item 
gh-125140@footnote{https://github.com/python/cpython/issues/125140}: Remove the current directory from @code{sys.path} when using
PyREPL.

@item 
gh-122792@footnote{https://github.com/python/cpython/issues/122792}: Changed IPv4-mapped @code{ipaddress.IPv6Address} to consistently
use the mapped IPv4 address value for deciding properties. Properties
which have their behavior fixed are @code{is_multicast}, @code{is_reserved},
@code{is_link_local}, @code{is_global}, and @code{is_unspecified}.
@end itemize

@node Library<2>,IDLE<3>,Security<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id6}@anchor{1519}
@subsubsection Library



@itemize -

@item 
gh-127321@footnote{https://github.com/python/cpython/issues/127321}: @ref{232,,pdb.set_trace()} will not stop at an opcode that does not
have an associated line number anymore.

@item 
gh-127303@footnote{https://github.com/python/cpython/issues/127303}: Publicly expose @ref{151a,,EXACT_TOKEN_TYPES} in
@code{token.__all__}.

@item 
gh-123967@footnote{https://github.com/python/cpython/issues/123967}: Fix faulthandler for trampoline frames. If the top-most frame
is a trampoline frame, skip it. Patch by Victor Stinner.

@item 
gh-127182@footnote{https://github.com/python/cpython/issues/127182}: Fix @code{io.StringIO.__setstate__()} crash, when @ref{660,,None}
was passed as the first value.

@item 
gh-127217@footnote{https://github.com/python/cpython/issues/127217}: Fix @ref{151b,,urllib.request.pathname2url()} for paths starting with
multiple slashes on Posix.

@item 
gh-127035@footnote{https://github.com/python/cpython/issues/127035}: Fix @ref{49d,,shutil.which} on Windows. Now it looks at direct
match if and only if the command ends with a PATHEXT extension or X_OK is
not in mode. Support extensionless files if "." is in PATHEXT. Support
PATHEXT extensions that end with a dot.

@item 
gh-122273@footnote{https://github.com/python/cpython/issues/122273}: Support PyREPL history on Windows. Patch by devdanzin and
Victor Stinner.

@item 
gh-127078@footnote{https://github.com/python/cpython/issues/127078}: Fix issue where @ref{151c,,urllib.request.url2pathname()} failed to
discard an extra slash before a UNC drive in the URL path on Windows.

@item 
gh-126766@footnote{https://github.com/python/cpython/issues/126766}: Fix issue where @ref{151c,,urllib.request.url2pathname()} failed to
discard any 'localhost' authority present in the URL.

@item 
gh-127065@footnote{https://github.com/python/cpython/issues/127065}: Fix crash when calling a @ref{e21,,operator.methodcaller()} instance
from multiple threads in the free threading build.

@item 
gh-126997@footnote{https://github.com/python/cpython/issues/126997}: Fix support of STRING and GLOBAL opcodes with non-ASCII
arguments in @ref{a6,,pickletools}. @ref{cb1,,pickletools.dis()} now outputs
non-ASCII bytes in STRING, BINSTRING and SHORT_BINSTRING arguments as
escaped (@code{\xXX}).

@item 
gh-126316@footnote{https://github.com/python/cpython/issues/126316}: @ref{65,,grp}: Make @ref{151d,,grp.getgrall()} thread-safe by adding a
mutex. Patch by Victor Stinner.

@item 
gh-126618@footnote{https://github.com/python/cpython/issues/126618}: Fix the representation of @ref{1261,,itertools.count} objects when
the count value is @ref{11a2,,sys.maxsize}.

@item 
gh-85168@footnote{https://github.com/python/cpython/issues/85168}: Fix issue where @ref{151c,,urllib.request.url2pathname()} and
@ref{151b,,pathname2url()} always used UTF-8 when quoting and
unquoting file URIs. They now use the @ref{525,,filesystem encoding and error handler}.

@item 
gh-67877@footnote{https://github.com/python/cpython/issues/67877}: Fix memory leaks when @ref{b8,,regular expression} matching
terminates abruptly, either because of a signal or because memory
allocation fails.

@item 
gh-126789@footnote{https://github.com/python/cpython/issues/126789}: Fixed the values of @ref{1015,,sysconfig.get_config_vars()},
@ref{1222,,sysconfig.get_paths()}, and their siblings when the @ref{c6,,site}
initialization happens after @ref{da,,sysconfig} has built a cache for
@ref{1015,,sysconfig.get_config_vars()}.

@item 
gh-126188@footnote{https://github.com/python/cpython/issues/126188}: Update bundled pip to 24.3.1

@item 
gh-126780@footnote{https://github.com/python/cpython/issues/126780}: Fix @ref{12f8,,os.path.normpath()} for drive-relative paths on
Windows.

@item 
gh-126766@footnote{https://github.com/python/cpython/issues/126766}: Fix issue where @ref{151c,,urllib.request.url2pathname()} failed to
discard two leading slashes introducing an empty authority section.

@item 
gh-126727@footnote{https://github.com/python/cpython/issues/126727}: @code{locale.nl_langinfo(locale.ERA)} now returns multiple era
description segments separated by semicolons. Previously it only returned
the first segment on platforms with Glibc.

@item 
gh-126699@footnote{https://github.com/python/cpython/issues/126699}: Allow @ref{dcb,,collections.abc.AsyncIterator} to be a base for
Protocols.

@item 
gh-126654@footnote{https://github.com/python/cpython/issues/126654}: Fix crash when non-dict was passed to several functions in
@code{_interpreters} module.

@item 
gh-104745@footnote{https://github.com/python/cpython/issues/104745}: Limit starting a patcher (from @ref{e7b,,unittest.mock.patch()} or
@ref{151e,,unittest.mock.patch.object()}) more than once without stopping it

@item 
gh-126595@footnote{https://github.com/python/cpython/issues/126595}: Fix a crash when instantiating @ref{1261,,itertools.count} with an
initial count of @ref{11a2,,sys.maxsize} on debug builds. Patch by Bénédikt
Tran.

@item 
gh-120423@footnote{https://github.com/python/cpython/issues/120423}: Fix issue where @ref{151b,,urllib.request.pathname2url()} mishandled
Windows paths with embedded forward slashes.

@item 
gh-126565@footnote{https://github.com/python/cpython/issues/126565}: Improve performances of @ref{151f,,zipfile.Path.open()} for
non-reading modes.

@item 
gh-126505@footnote{https://github.com/python/cpython/issues/126505}: Fix bugs in compiling case-insensitive @ref{b8,,regular expressions} with character classes containing non-BMP characters:
upper-case non-BMP character did was ignored and the ASCII flag was
ignored when matching a character range whose upper bound is beyond the
BMP region.

@item 
gh-117378@footnote{https://github.com/python/cpython/issues/117378}: Fixed the @ref{93,,multiprocessing} @code{"forkserver"} start method
forkserver process to correctly inherit the parent's @ref{3ab,,sys.path}
during the importing of @ref{1520,,multiprocessing.set_forkserver_preload()}
modules in the same manner as @ref{3ab,,sys.path} is configured in workers
before executing work items.

This bug caused some forkserver module preloading to silently fail to
preload. This manifested as a performance degration in child processes
when the @code{sys.path} was required due to additional repeated work in
every worker.

It could also have a side effect of @code{""} remaining in @ref{3ab,,sys.path}
during forkserver preload imports instead of the absolute path from
@ref{1521,,os.getcwd()} at multiprocessing import time used in the worker
@code{sys.path}.

The @code{sys.path} differences between phases in the child process could
potentially have caused preload to import incorrect things from the wrong
location.  We are unaware of that actually having happened in practice.

@item 
gh-125679@footnote{https://github.com/python/cpython/issues/125679}: The @ref{1522,,multiprocessing.Lock} and
@ref{1523,,multiprocessing.RLock} @code{repr} values no longer say "unknown" on
macOS.

@item 
gh-126476@footnote{https://github.com/python/cpython/issues/126476}: Raise @ref{1524,,calendar.IllegalMonthError} (now a subclass of
@ref{14eb,,IndexError}) for @ref{1525,,calendar.month()} when the input month is
not correct.

@item 
gh-126489@footnote{https://github.com/python/cpython/issues/126489}: The Python implementation of @ref{a5,,pickle} no longer calls
@ref{1526,,pickle.Pickler.persistent_id()} for the result of
@code{persistent_id()}.

@item 
gh-126313@footnote{https://github.com/python/cpython/issues/126313}: Fix an issue in @ref{1527,,curses.napms()} when
@ref{1528,,curses.initscr()} has not yet been called. Patch by Bénédikt Tran.

@item 
gh-126303@footnote{https://github.com/python/cpython/issues/126303}: Fix pickling and copying of @ref{1529,,os.sched_param} objects.

@item 
gh-126138@footnote{https://github.com/python/cpython/issues/126138}: Fix a use-after-free crash on @ref{4c2,,asyncio.Task} objects
whose underlying coroutine yields an object that implements an evil
@ref{bc0,,__getattribute__()}. Patch by Nico Posada.

@item 
gh-126220@footnote{https://github.com/python/cpython/issues/126220}: Fix crash in @code{cProfile.Profile} and
@code{_lsprof.Profiler} when their callbacks were directly called with
0 arguments.

@item 
gh-126212@footnote{https://github.com/python/cpython/issues/126212}: Fix issue where @ref{151b,,urllib.request.pathname2url()} and
@ref{151c,,url2pathname()} removed slashes from Windows DOS
drive paths and URLs.

@item 
gh-126223@footnote{https://github.com/python/cpython/issues/126223}: Raise a @ref{662,,UnicodeEncodeError} instead of a
@ref{561,,SystemError} upon calling @code{_interpreters.create()} with an
invalid Unicode character.

@item 
gh-126205@footnote{https://github.com/python/cpython/issues/126205}: Fix issue where @ref{151b,,urllib.request.pathname2url()} generated
URLs beginning with four slashes (rather than two) when given a Windows
UNC path.

@item 
gh-126105@footnote{https://github.com/python/cpython/issues/126105}: Fix a crash in @ref{8,,ast} when the @ref{152a,,ast.AST._fields}
attribute is deleted.

@item 
gh-126106@footnote{https://github.com/python/cpython/issues/126106}: Fixes a possible @code{NULL} pointer dereference in @ref{cf,,ssl}.

@item 
gh-126080@footnote{https://github.com/python/cpython/issues/126080}: Fix a use-after-free crash on @ref{4c2,,asyncio.Task} objects for
which the underlying event loop implements an evil
@ref{bc0,,__getattribute__()}. Reported by Nico-Posada. Patch by
Bénédikt Tran.

@item 
gh-126083@footnote{https://github.com/python/cpython/issues/126083}: Fixed a reference leak in @ref{4c2,,asyncio.Task} objects when
reinitializing the same object with a non-@code{None} context. Patch by Nico
Posada.

@item 
gh-125984@footnote{https://github.com/python/cpython/issues/125984}: Fix use-after-free crashes on @ref{bbb,,asyncio.Future} objects
for which the underlying event loop implements an evil
@ref{bc0,,__getattribute__()}. Reported by Nico-Posada. Patch by
Bénédikt Tran.

@item 
gh-125969@footnote{https://github.com/python/cpython/issues/125969}: Fix an out-of-bounds crash when an evil
@ref{af2,,asyncio.loop.call_soon()} mutates the length of the internal
callbacks list. Patch by Bénédikt Tran.

@item 
gh-125966@footnote{https://github.com/python/cpython/issues/125966}: Fix a use-after-free crash in
@ref{152b,,asyncio.Future.remove_done_callback()}. Patch by Bénédikt Tran.

@item 
gh-125789@footnote{https://github.com/python/cpython/issues/125789}: Fix possible crash when mutating list of callbacks returned by
@code{asyncio.Future._callbacks}. It now always returns a new copy in C
implementation @code{_asyncio}. Patch by Kumar Aditya.

@item 
gh-124452@footnote{https://github.com/python/cpython/issues/124452}: Fix an issue in
@ref{152c,,email.policy.EmailPolicy.header_source_parse()} and
@ref{152d,,email.policy.Compat32.header_source_parse()} that introduced spurious
leading whitespaces into header values when the header includes a newline
character after the header name delimiter (@code{:}) and before the value.

@item 
gh-125884@footnote{https://github.com/python/cpython/issues/125884}: Fixed the bug for @ref{a4,,pdb} where it can't set breakpoints on
functions with certain annotations.

@item 
gh-125355@footnote{https://github.com/python/cpython/issues/125355}: Fix several bugs in
@ref{aee,,argparse.ArgumentParser.parse_intermixed_args()}.


@itemize *

@item 
The parser no longer changes temporarily during parsing.

@item 
Default values are not processed twice.

@item 
Required mutually exclusive groups containing positional arguments are now supported.

@item 
The missing arguments report now includes the names of all required optional and positional arguments.

@item 
Unknown options can be intermixed with positional arguments in parse_known_intermixed_args().
@end itemize

@item 
gh-125666@footnote{https://github.com/python/cpython/issues/125666}: Avoid the exiting the interpreter if a null byte is given as
input in the new REPL.

@item 
gh-125710@footnote{https://github.com/python/cpython/issues/125710}: [Enum] fix hashable<->nonhashable comparisons for member values

@item 
gh-125631@footnote{https://github.com/python/cpython/issues/125631}: Restore ability to set @ref{1526,,persistent_id}
and @ref{152e,,persistent_load} attributes of instances of
the @code{Pickler} and @code{Unpickler} classes in the @ref{a5,,pickle}
module.

@item 
gh-125378@footnote{https://github.com/python/cpython/issues/125378}: Fixed the bug in @ref{a4,,pdb} where after a multi-line command,
an empty line repeats the first line of the multi-line command, instead of
the full command.

@item 
gh-125682@footnote{https://github.com/python/cpython/issues/125682}: Reject non-ASCII digits in the Python implementation of
@ref{942,,json.loads()} conforming to the JSON specification.

@item 
gh-125660@footnote{https://github.com/python/cpython/issues/125660}: Reject invalid unicode escapes for Python implementation of
@ref{942,,json.loads()}.

@item 
gh-125259@footnote{https://github.com/python/cpython/issues/125259}: Fix the notes removal logic for errors thrown in enum
initialization.

@item 
gh-125590@footnote{https://github.com/python/cpython/issues/125590}: Allow @code{FrameLocalsProxy} to delete and pop if the key is not
a fast variable.

@item 
gh-125519@footnote{https://github.com/python/cpython/issues/125519}: Improve traceback if @ref{502,,importlib.reload()} is called with an
object that is not a module. Patch by Alex Waygood.

@item 
gh-125451@footnote{https://github.com/python/cpython/issues/125451}: Fix deadlock when
@ref{8db,,concurrent.futures.ProcessPoolExecutor} shuts down concurrently
with an error when feeding a job to a worker process.

@item 
gh-125422@footnote{https://github.com/python/cpython/issues/125422}: Fixed the bug where @ref{a4,,pdb} and @ref{f,,bdb} can step into the
bottom caller frame.

@item 
gh-100141@footnote{https://github.com/python/cpython/issues/100141}: Fixed the bug where @ref{a4,,pdb} will be stuck in an infinite
loop when debugging an empty file.

@item 
gh-125115@footnote{https://github.com/python/cpython/issues/125115}: Fixed a bug in @ref{a4,,pdb} where arguments starting with @code{-}
can't be passed to the debugged script.

@item 
gh-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{13e3,,time.strptime()} for @code{%c}, @code{%x} and @code{%X} formats
in many locales that use non-ASCII digits, like Persian, Burmese, Odia and
Shan.

@item 
gh-125398@footnote{https://github.com/python/cpython/issues/125398}: Fix the conversion of the @code{VIRTUAL_ENV} path in the
activate script in @ref{110,,venv} when running in Git Bash for Windows.

@item 
gh-125316@footnote{https://github.com/python/cpython/issues/125316}: Fix using @ref{40a,,functools.partial()} as @ref{61b,,enum.Enum}
member. A FutureWarning with suggestion to use @ref{612,,enum.member()} is now
emitted when the @code{partial} instance is used as an enum member.

@item 
gh-125245@footnote{https://github.com/python/cpython/issues/125245}: Fix race condition when importing @ref{1e,,collections.abc}, which
could incorrectly return an empty module.

@item 
gh-125243@footnote{https://github.com/python/cpython/issues/125243}: Fix data race when creating @ref{8cc,,zoneinfo.ZoneInfo} objects
in the free threading build.

@item 
gh-125254@footnote{https://github.com/python/cpython/issues/125254}: Fix a bug where ArgumentError includes the incorrect ambiguous
option in @ref{6,,argparse}.

@item 
gh-125235@footnote{https://github.com/python/cpython/issues/125235}: Keep @ref{ef,,tkinter} TCL paths in venv pointing to base
installation on Windows.

@item 
gh-61011@footnote{https://github.com/python/cpython/issues/61011}: Fix inheritance of nested mutually exclusive groups from parent
parser in @ref{523,,argparse.ArgumentParser}. Previously, all nested
mutually exclusive groups lost their connection to the group containing
them and were displayed as belonging directly to the parser.

@item 
gh-52551@footnote{https://github.com/python/cpython/issues/52551}: Fix encoding issues in @ref{11c6,,time.strftime()}, the
@ref{c7e,,strftime()} method of the @ref{30,,datetime} classes
@ref{1c7,,datetime}, @ref{1c8,,date} and
@ref{1c9,,time} and formatting of these classes. Characters not
encodable in the current locale are now acceptable in the format string.
Surrogate pairs and sequence of surrogatescape-encoded bytes are no longer
recombinated. Embedded null character no longer terminates the format
string.

@item 
gh-125118@footnote{https://github.com/python/cpython/issues/125118}: Don't copy arbitrary values to _Bool in the
@ref{d4,,struct} module.

@item 
gh-125069@footnote{https://github.com/python/cpython/issues/125069}: Fix an issue where providing a @ref{490,,pathlib.PurePath} object
as an initializer argument to a second @ref{490,,PurePath} object
with a different @ref{229,,parser} resulted in arguments to
the former object's initializer being joined by the latter object's
parser.

@item 
gh-125096@footnote{https://github.com/python/cpython/issues/125096}: If the 
@geindex PYTHON_BASIC_REPL
@geindex variable d'environnement; PYTHON_BASIC_REPL
@ref{16d,,PYTHON_BASIC_REPL} environment variable is set,
the @ref{c6,,site} module no longer imports the @code{_pyrepl} module.
Moreover, the @ref{c6,,site} module now respects @ref{94a,,-E} and
@ref{94b,,-I} command line options: ignore 
@geindex PYTHON_BASIC_REPL
@geindex variable d'environnement; PYTHON_BASIC_REPL
@ref{16d,,PYTHON_BASIC_REPL} in
this case. Patch by Victor Stinner.

@item 
gh-124969@footnote{https://github.com/python/cpython/issues/124969}: Fix @code{locale.nl_langinfo(locale.ALT_DIGITS)} on platforms with
glibc. Now it returns a string consisting of up to 100 semicolon-separated
symbols (an empty string in most locales) on all Posix platforms.
Previously it only returned the first symbol or an empty string.

@item 
gh-124960@footnote{https://github.com/python/cpython/issues/124960}: Fix support for the @code{barry_as_FLUFL} future flag in the new
REPL.

@item 
gh-124984@footnote{https://github.com/python/cpython/issues/124984}: Fixed thread safety in @ref{cf,,ssl} in the free-threaded build.
OpenSSL operations are now protected by a per-object lock.

@item 
gh-124958@footnote{https://github.com/python/cpython/issues/124958}: Fix refcycles in exceptions raised from
@ref{1b3,,asyncio.TaskGroup} and the python implementation of
@ref{bbb,,asyncio.Future}

@item 
gh-53203@footnote{https://github.com/python/cpython/issues/53203}: Fix @ref{13e3,,time.strptime()} for @code{%c} and @code{%x} formats in many
locales: Arabic, Bislama, Breton, Bodo, Kashubian, Chuvash, Estonian,
French, Irish, Ge'ez, Gurajati, Manx Gaelic, Hebrew, Hindi, Chhattisgarhi,
Haitian Kreyol, Japanese, Kannada, Korean, Marathi, Malay, Norwegian,
Nynorsk, Punjabi, Rajasthani, Tok Pisin, Yoruba, Yue Chinese, Yau/Nungon
and Chinese.

@item 
gh-124917@footnote{https://github.com/python/cpython/issues/124917}: Allow calling @ref{9fc,,os.path.exists()} and
@ref{9fd,,os.path.lexists()} with keyword arguments on Windows. Fixes a
regression in 3.13.0.

@item 
gh-124653@footnote{https://github.com/python/cpython/issues/124653}: Fix detection of the minimal Queue API needed by the
@ref{86,,logging} module. Patch by Bénédikt Tran.

@item 
gh-124858@footnote{https://github.com/python/cpython/issues/124858}: Fix reference cycles left in tracebacks in
@ref{b06,,asyncio.open_connection()} when used with @code{happy_eyeballs_delay}

@item 
gh-124390@footnote{https://github.com/python/cpython/issues/124390}: Fixed @ref{694,,AssertionError} when using
@code{asyncio.staggered.staggered_race()} with
@ref{461,,asyncio.eager_task_factory}.

@item 
gh-124651@footnote{https://github.com/python/cpython/issues/124651}: Properly quote template strings in @ref{110,,venv} activation
scripts.

@item 
gh-116850@footnote{https://github.com/python/cpython/issues/116850}: Fix @ref{6,,argparse} for namespaces with not directly writable
dict (e.g. classes).

@item 
gh-58573@footnote{https://github.com/python/cpython/issues/58573}: Fix conflicts between abbreviated long options in the parent
parser and subparsers in @ref{6,,argparse}.

@item 
gh-124594@footnote{https://github.com/python/cpython/issues/124594}: All @ref{a,,asyncio} REPL prompts run in the same @ref{152f,,context}. Contributed by Bartosz Sławecki.

@item 
gh-61181@footnote{https://github.com/python/cpython/issues/61181}: Fix support of @ref{1530,,Le paramètre choices} with string value in
@ref{6,,argparse}. Substrings of the specified string no longer considered
valid values.

@item 
gh-80259@footnote{https://github.com/python/cpython/issues/80259}: Fix @ref{6,,argparse} support of positional arguments with
@code{nargs='?'}, @code{default=argparse.SUPPRESS} and specified @code{type}.

@item 
gh-120378@footnote{https://github.com/python/cpython/issues/120378}: Fix a crash related to an integer overflow in
@ref{1531,,curses.resizeterm()} and @ref{1532,,curses.resize_term()}.

@item 
gh-123884@footnote{https://github.com/python/cpython/issues/123884}: Fixed bug in itertools.tee() handling of other tee inputs (a
tee in a tee). The output now has the promised `n' independent new
iterators.  Formerly, the first iterator was identical (not independent)
to the input iterator. This would sometimes give surprising results.

@item 
gh-58956@footnote{https://github.com/python/cpython/issues/58956}: Fixed a bug in @ref{a4,,pdb} where sometimes the breakpoint won't
trigger if it was set on a function which is already in the call stack.

@item 
gh-124345@footnote{https://github.com/python/cpython/issues/124345}: @ref{6,,argparse} vim supports abbreviated single-dash long
options separated by @code{=} from its value.

@item 
gh-104860@footnote{https://github.com/python/cpython/issues/104860}: Fix disallowing abbreviation of single-dash long options in
@ref{6,,argparse} with @code{allow_abbrev=False}.

@item 
gh-63143@footnote{https://github.com/python/cpython/issues/63143}: Fix parsing mutually exclusive arguments in @ref{6,,argparse}.
Arguments with the value identical to the default value (e.g. booleans,
small integers, empty or 1-character strings) are no longer considered
"not present".

@item 
gh-72795@footnote{https://github.com/python/cpython/issues/72795}: Positional arguments with @ref{1533,,Le paramètre nargs} equal to @code{'*'} or
@code{argparse.REMAINDER} are no longer required. This allows to use
positional argument with @code{nargs='*'} and without @code{default} in mutually
exclusive group and improves error message about required arguments.

@item 
gh-59317@footnote{https://github.com/python/cpython/issues/59317}: Fix parsing positional argument with @ref{1533,,Le paramètre nargs} equal to
@code{'?'} or @code{'*'} if it is preceded by an option and another positional
argument.

@item 
gh-53780@footnote{https://github.com/python/cpython/issues/53780}: @ref{6,,argparse} now ignores the first @code{"--"} (double dash)
between an option and command.

@item 
gh-124217@footnote{https://github.com/python/cpython/issues/124217}: Add RFC 9637 reserved IPv6 block @code{3fff::/20} in
@ref{7f,,ipaddress} module.

@item 
gh-81691@footnote{https://github.com/python/cpython/issues/81691}: Fix handling of multiple @code{"--"} (double dashes) in
@ref{6,,argparse}. Only the first one has now been removed, all subsequent
ones are now taken literally.

@item 
gh-123978@footnote{https://github.com/python/cpython/issues/123978}: Remove broken @ref{923,,time.thread_time()} and
@ref{b7f,,time.thread_time_ns()} on NetBSD.

@item 
gh-124008@footnote{https://github.com/python/cpython/issues/124008}: Fix possible crash (in debug build), incorrect output or
returning incorrect value from raw binary @code{write()} when writing to
console on Windows.

@item 
gh-123935@footnote{https://github.com/python/cpython/issues/123935}: Fix parent slots detection for dataclasses that inherit from
classes with @code{__dictoffset__}.

@item 
gh-122765@footnote{https://github.com/python/cpython/issues/122765}: Fix unbalanced quote errors occurring when activate.csh in
@ref{110,,venv} was sourced with a custom prompt containing unpaired quotes or
newlines.

@item 
gh-123370@footnote{https://github.com/python/cpython/issues/123370}: Fix the canvas not clearing after running turtledemo clock.

@item 
gh-116810@footnote{https://github.com/python/cpython/issues/116810}: Resolve a memory leak introduced in CPython 3.10's @ref{cf,,ssl}
when the @ref{1534,,ssl.SSLSocket.session} property was accessed.  Speeds up
read and write access to said property by no longer unnecessarily cloning
session objects via serialization.

@item 
gh-120754@footnote{https://github.com/python/cpython/issues/120754}: Update unbounded @code{read} calls in @ref{130,,zipfile} to specify an
explicit @code{size} putting a limit on how much data they may read. This
also updates handling around ZIP max comment size to match the standard
instead of reading comments that are one byte too long.

@item 
gh-70764@footnote{https://github.com/python/cpython/issues/70764}: Fixed an issue where @ref{10b7,,inspect.getclosurevars()} would
incorrectly classify an attribute name as a global variable when the name
exists both as an attribute name and a global variable.

@item 
gh-118289@footnote{https://github.com/python/cpython/issues/118289}: @code{posixpath.realpath()} now raises
@ref{1043,,NotADirectoryError} when `strict' mode is enabled and a
non-directory path with a trailing slash is supplied.

@item 
gh-119826@footnote{https://github.com/python/cpython/issues/119826}: Always return an absolute path for @ref{12f9,,os.path.abspath()} on
Windows.

@item 
gh-117766@footnote{https://github.com/python/cpython/issues/117766}: Always use @ref{435,,str()} to print @code{choices} in @ref{6,,argparse}.

@item 
gh-101955@footnote{https://github.com/python/cpython/issues/101955}: Fix SystemError when match regular expression pattern
containing some combination of possessive quantifier, alternative and
capture group.

@item 
gh-88110@footnote{https://github.com/python/cpython/issues/88110}: Fixed @ref{b47,,multiprocessing.Process} reporting a @code{.exitcode}
of 1 even on success when using the @code{"fork"} start method while using a
@ref{72c,,concurrent.futures.ThreadPoolExecutor}.

@item 
gh-71936@footnote{https://github.com/python/cpython/issues/71936}: Fix a race condition in @ref{f56,,multiprocessing.pool.Pool}.

@item 
bpo-46128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46128}: Strip @ref{301,,unittest.IsolatedAsyncioTestCase} stack frames
from reported stacktraces.

@item 
bpo-14074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14074}: Fix @ref{6,,argparse} metavar processing to allow positional
arguments to have a tuple metavar.
@end itemize

@node IDLE<3>,Documentation<2>,Library<2>,Python 3 13 1 final
@anchor{whatsnew/changelog idle}@anchor{1535}
@subsubsection IDLE



@itemize -

@item 
gh-122392@footnote{https://github.com/python/cpython/issues/122392}: Increase currently inadequate vertical spacing for the IDLE
browsers (path, module, and stack) on high-resolution monitors.
@end itemize

@node Documentation<2>,Core and Builtins<2>,IDLE<3>,Python 3 13 1 final
@anchor{whatsnew/changelog documentation}@anchor{1536}
@subsubsection Documentation



@itemize -

@item 
gh-126622@footnote{https://github.com/python/cpython/issues/126622}: Added stub pages for removed modules explaining their removal,
where to find replacements, and linking to the last Python version that
supported them. Contributed by Ned Batchelder.

@item 
gh-125277@footnote{https://github.com/python/cpython/issues/125277}: Require Sphinx 7.2.6 or later to build the Python
documentation. Patch by Adam Turner.

@item 
gh-124872@footnote{https://github.com/python/cpython/issues/124872}: Added definitions for @ref{1537,,context}, @ref{1538,,current context},
and @ref{1539,,context management protocol}, updated related definitions to be
consistent, and expanded the documentation for
@ref{152f,,contextvars.Context}.

@item 
gh-125018@footnote{https://github.com/python/cpython/issues/125018}: The @ref{79,,importlib.metadata} documentation now includes
semantic cross-reference targets for the significant documented APIs. This
means intersphinx references like @ref{153a,,importlib.metadata.version()} will
now work as expected.

@item 
gh-70870@footnote{https://github.com/python/cpython/issues/70870}: Clarified the dual usage of the term "free variable" (both the
formal meaning of any reference to names defined outside the local scope,
and the narrower pragmatic meaning of nonlocal variables named in
@code{co_freevars}).

@item 
gh-121277@footnote{https://github.com/python/cpython/issues/121277}: Writers of CPython's documentation can now use @code{next} as the
version for the @code{versionchanged}, @code{versionadded}, @code{deprecated}
directives.

@item 
gh-60712@footnote{https://github.com/python/cpython/issues/60712}: Include the @ref{a7a,,object} type in the lists of documented
types. Change by Furkan Onder and Martin Panter.

@item 
bpo-34008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34008}: The @ref{c13,,Py_Main()} documentation moved from the "Very High
Level API" section to the "Initialization and Finalization" section.

Also make it explicit that we expect @code{Py_Main} to typically be called
instead of @code{Py_Initialize} rather than after it (since @code{Py_Main} makes
its own call to @code{Py_Initialize}). Document that calling both is
supported but is version dependent on which settings will be applied
correctly.
@end itemize

@node Core and Builtins<2>,C API<2>,Documentation<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id7}@anchor{153b}
@subsubsection Core and Builtins



@itemize -

@item 
gh-113841@footnote{https://github.com/python/cpython/issues/113841}: Fix possible undefined behavior division by zero in
@ref{2ec,,complex}'s @ref{153c,,_Py_c_pow()}.

@item 
gh-127020@footnote{https://github.com/python/cpython/issues/127020}: Fix a crash in the free threading build when
@ref{762,,PyCode_GetCode()}, @ref{763,,PyCode_GetVarnames()},
@ref{764,,PyCode_GetCellvars()}, or @ref{765,,PyCode_GetFreevars()} were called
from multiple threads at the same time.

@item 
gh-126980@footnote{https://github.com/python/cpython/issues/126980}: Fix @ref{448,,__buffer__()} of @ref{528,,bytearray} crashing
when @ref{153d,,READ} or
@ref{153e,,WRITE} are passed as flags.

@item 
gh-126881@footnote{https://github.com/python/cpython/issues/126881}: Fix crash in finalization of dtoa state. Patch by Kumar Aditya.

@item 
gh-126341@footnote{https://github.com/python/cpython/issues/126341}: Now @ref{1ff,,ValueError} is raised instead of @ref{561,,SystemError}
when trying to iterate over a released @ref{452,,memoryview} object.

@item 
gh-126688@footnote{https://github.com/python/cpython/issues/126688}: Fix a crash when calling @ref{195,,os.fork()} on some operating
systems, including SerenityOS.

@item 
gh-126066@footnote{https://github.com/python/cpython/issues/126066}: Fix @ref{76,,importlib} to not write an incomplete .pyc files when
a ulimit or some other operating system mechanism is preventing the write
to go through fully.

@item 
gh-126312@footnote{https://github.com/python/cpython/issues/126312}: Fix crash during garbage collection on an object frozen by
@ref{b28,,gc.freeze()} on the free-threaded build.

@item 
gh-126139@footnote{https://github.com/python/cpython/issues/126139}: Provide better error location when attempting to use a
@ref{d9a,,future statement} with an unknown future feature.

@item 
gh-126018@footnote{https://github.com/python/cpython/issues/126018}: Fix a crash in @ref{153f,,sys.audit()} when passing a non-string as
first argument and Python was compiled in debug mode.

@item 
gh-125942@footnote{https://github.com/python/cpython/issues/125942}: On Android, the @code{errors} setting of @ref{ac4,,sys.stdout} was
changed from @code{surrogateescape} to @code{backslashreplace}.

@item 
gh-125859@footnote{https://github.com/python/cpython/issues/125859}: Fix a crash in the free threading build when
@ref{7ed,,gc.get_objects()} or @ref{7ee,,gc.get_referrers()} is called during an
in-progress garbage collection.

@item 
gh-125703@footnote{https://github.com/python/cpython/issues/125703}: Correctly honour @ref{fe,,tracemalloc} hooks in specialized
@code{Py_DECREF} paths. Patch by Pablo Galindo

@item 
gh-125593@footnote{https://github.com/python/cpython/issues/125593}: Use color to highlight error locations in traceback from
exception group

@item 
gh-125444@footnote{https://github.com/python/cpython/issues/125444}: Fix illegal instruction for older Arm architectures. Patch by
Diego Russo, testing by Ross Burton.

@item 
gh-124375@footnote{https://github.com/python/cpython/issues/124375}: Fix a crash in the free threading build when the GC runs
concurrently with a new thread starting.

@item 
gh-125221@footnote{https://github.com/python/cpython/issues/125221}: Fix possible race condition when calling
@ref{1540,,__reduce_ex__()} for the first time in the free threading
build.

@item 
gh-125038@footnote{https://github.com/python/cpython/issues/125038}: Fix crash when iterating over a generator expression after
direct changes on @code{gi_frame.f_locals}. Patch by Mikhail Efimov.

@item 
gh-123378@footnote{https://github.com/python/cpython/issues/123378}: Fix a crash in the @ref{608,,__str__()} method of
@ref{1281,,UnicodeError} objects when the @ref{1541,,UnicodeError.start} and
@ref{1542,,UnicodeError.end} values are invalid or out-of-range. Patch by
Bénédikt Tran.

@item 
gh-116510@footnote{https://github.com/python/cpython/issues/116510}: Fix a crash caused by immortal interned strings being shared
between sub-interpreters that use basic single-phase init.  In that case,
the string can be used by an interpreter that outlives the interpreter
that created and interned it.  For interpreters that share obmalloc state,
also share the interned dict with the main interpreter.

@item 
gh-122878@footnote{https://github.com/python/cpython/issues/122878}: Use the @code{pager} binary, if available (e.g. on Debian and
derivatives), to display REPL @code{help()}.

@item 
gh-124188@footnote{https://github.com/python/cpython/issues/124188}: Fix reading and decoding a line from the source file witn
non-UTF-8 encoding for syntax errors raised in the compiler.

@item 
gh-123930@footnote{https://github.com/python/cpython/issues/123930}: Improve the error message when a script shadowing a module from
the standard library causes @ref{40f,,ImportError} to be raised during a
"from" import. Similarly, improve the error message when a script
shadowing a third party module attempts to "from" import an attribute from
that third party module while still initialising.

@item 
gh-122907@footnote{https://github.com/python/cpython/issues/122907}: Building with @code{HAVE_DYNAMIC_LOADING} now works as well as it
did in 3.12. Existing deficiences will be addressed separately. (See
@indicateurl{https://github.com/python/cpython/issues/122950}.)

@item 
gh-118950@footnote{https://github.com/python/cpython/issues/118950}: Fix bug where SSLProtocol.connection_lost wasn't getting called
when OSError was thrown on writing to socket.

@item 
gh-113570@footnote{https://github.com/python/cpython/issues/113570}: Fixed a bug in @code{reprlib.repr} where it incorrectly called the
repr method on shadowed Python built-in types.

@item 
gh-109746@footnote{https://github.com/python/cpython/issues/109746}: If @code{_thread.start_new_thread()} fails to start a new
thread, it deletes its state from interpreter and thus avoids its repeated
cleanup on finalization.
@end itemize

@node C API<2>,Build<2>,Core and Builtins<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id8}@anchor{1543}
@subsubsection C API



@itemize -

@item 
gh-126554@footnote{https://github.com/python/cpython/issues/126554}: Fix error handling in @ref{9d7,,ctypes.CDLL} objects which could
result in a crash in rare situations.

@item 
gh-125608@footnote{https://github.com/python/cpython/issues/125608}: Fix a bug where dictionary watchers (e.g.,
@ref{54f,,PyDict_Watch()}) on an object's attribute dictionary
(@ref{546,,__dict__}) were not triggered when the object's attributes
were modified.

@item 
bpo-34008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34008}: Added @code{Py_IsInitialized} to the list of APIs that are safe to
call before the interpreter is initialized, and updated the embedding
tests to cover it.
@end itemize

@node Build<2>,,C API<2>,Python 3 13 1 final
@anchor{whatsnew/changelog id9}@anchor{1544}
@subsubsection Build



@itemize -

@item 
gh-123877@footnote{https://github.com/python/cpython/issues/123877}: Set @code{wasm32-wasip1} as the WASI target. The old
@code{wasm32-wasi} target is deprecated so it can be used for an eventual
WASI 1.0.

@item 
gh-89640@footnote{https://github.com/python/cpython/issues/89640}: Hard-code float word ordering as little endian on WASM.

@item 
gh-125940@footnote{https://github.com/python/cpython/issues/125940}: The Android build now supports 16 KB page sizes@footnote{https://developer.android.com/guide/practices/page-sizes}.

@item 
gh-89640@footnote{https://github.com/python/cpython/issues/89640}: Improve detection of float word ordering on Linux when link-time
optimizations are enabled.

@item 
gh-125269@footnote{https://github.com/python/cpython/issues/125269}: Fix detection of whether @code{-latomic} is needed when
cross-compiling CPython using the configure script.

@item 
gh-121634@footnote{https://github.com/python/cpython/issues/121634}: Allow for specifying the target compile triple for WASI.

@item 
gh-122578@footnote{https://github.com/python/cpython/issues/122578}: Use WASI SDK 24 for testing.

@item 
gh-115382@footnote{https://github.com/python/cpython/issues/115382}: Fix cross compile failures when the host and target SOABIs
match.
@end itemize

@node Python 3 13 0 final,Python 3 13 0 release candidate 3,Python 3 13 1 final,Changelog
@anchor{whatsnew/changelog python-3-13-0-final}@anchor{1545}
@subsection Python 3.13.0 final


`Release date: 2024-10-07'

@menu
* Core and Builtins: Core and Builtins<3>. 

@end menu

@node Core and Builtins<3>,,,Python 3 13 0 final
@anchor{whatsnew/changelog id10}@anchor{1546}
@subsubsection Core and Builtins



@itemize -

@item 
gh-125008@footnote{https://github.com/python/cpython/issues/125008}: Fix @ref{1547,,tokenize.untokenize()} producing invalid syntax for
double braces preceded by certain escape characters.

@item 
gh-124871@footnote{https://github.com/python/cpython/issues/124871}: Fix compiler bug (in some versions of 3.13) where an assertion
fails during reachability analysis.
@end itemize

@node Python 3 13 0 release candidate 3,Python 3 13 0 release candidate 2,Python 3 13 0 final,Changelog
@anchor{whatsnew/changelog python-3-13-0-release-candidate-3}@anchor{1548}
@subsection Python 3.13.0 release candidate 3


`Release date: 2024-10-01'

@menu
* macOS: macOS<2>. 
* Windows: Windows<3>. 
* Tests: Tests<3>. 
* Library: Library<3>. 
* IDLE: IDLE<4>. 
* Documentation: Documentation<3>. 
* Core and Builtins: Core and Builtins<4>. 
* C API: C API<3>. 
* Build: Build<3>. 

@end menu

@node macOS<2>,Windows<3>,,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id11}@anchor{1549}
@subsubsection macOS



@itemize -

@item 
gh-123797@footnote{https://github.com/python/cpython/issues/123797}: Check for runtime availability of @code{ptsname_r} function on
macos.
@end itemize

@node Windows<3>,Tests<3>,macOS<2>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id12}@anchor{154a}
@subsubsection Windows



@itemize -

@item 
gh-124609@footnote{https://github.com/python/cpython/issues/124609}: Fix @code{_Py_ThreadId} for Windows builds using MinGW. Patch by
Tony Roberts.

@item 
gh-124254@footnote{https://github.com/python/cpython/issues/124254}: Ensures experimental free-threaded binaries remain installed
when updating.

@item 
gh-123915@footnote{https://github.com/python/cpython/issues/123915}: Ensure that @code{Tools\msi\buildrelease.bat} uses different
directories for AMD64 and ARM64 builds.
@end itemize

@node Tests<3>,Library<3>,Windows<3>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id13}@anchor{154b}
@subsubsection Tests



@itemize -

@item 
gh-124378@footnote{https://github.com/python/cpython/issues/124378}: Updated @code{test_ttk} to pass with Tcl/Tk 8.6.15.
@end itemize

@node Library<3>,IDLE<4>,Tests<3>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id14}@anchor{154c}
@subsubsection Library



@itemize -

@item 
gh-124538@footnote{https://github.com/python/cpython/issues/124538}: Fixed crash when using @ref{7ef,,gc.get_referents()} on a capsule
object.

@item 
gh-124498@footnote{https://github.com/python/cpython/issues/124498}: Fix @ref{43e,,typing.TypeAliasType} not to be generic, when
@code{type_params} is an empty tuple.

@item 
gh-123017@footnote{https://github.com/python/cpython/issues/123017}: Due to unreliable results on some devices,
@ref{11c6,,time.strftime()} no longer accepts negative years on Android.

@item 
gh-123014@footnote{https://github.com/python/cpython/issues/123014}: @ref{464,,os.pidfd_open()} and @ref{918,,signal.pidfd_send_signal()} are
now unavailable when building against Android API levels older than 31,
since the underlying system calls may cause a crash.

@item 
gh-124248@footnote{https://github.com/python/cpython/issues/124248}: Fixed potential crash when using @ref{d4,,struct} to process
zero-width 'Pascal string' fields (@code{0p}).

@item 
gh-87041@footnote{https://github.com/python/cpython/issues/87041}: Fix a bug in @ref{6,,argparse} where lengthy subparser argument
help is incorrectly indented.

@item 
gh-124212@footnote{https://github.com/python/cpython/issues/124212}: Fix invalid variable in @ref{110,,venv} handling of failed symlink
on Windows

@item 
gh-124171@footnote{https://github.com/python/cpython/issues/124171}: Add workaround for broken @code{fmod()} implementations on
Windows, that loose zero sign (e.g. @code{fmod(-10, 1)} returns @code{0.0}).
Patch by Sergey B Kirpichev.

@item 
gh-123934@footnote{https://github.com/python/cpython/issues/123934}: Fix @ref{e7a,,unittest.mock.MagicMock} reseting magic methods
return values after @code{.reset_mock(return_value=True)} was called.

@item 
gh-123968@footnote{https://github.com/python/cpython/issues/123968}: Fix the command-line interface for the @ref{b7,,random} module to
select floats between 0 and N, not 1 and N.

@item 
gh-123892@footnote{https://github.com/python/cpython/issues/123892}: Add @code{"_wmi"} to @ref{82b,,sys.stdlib_module_names}. Patch by
Victor Stinner.

@item 
gh-123339@footnote{https://github.com/python/cpython/issues/123339}: Fix @ref{154d,,inspect.getsource()} for classes in
@ref{1e,,collections.abc} and @ref{36,,decimal} (for pure Python implementation)
modules. @ref{154e,,inspect.getcomments()} now raises OSError instead of
IndexError if the @code{__firstlineno__} value for a class is out of bound.

@item 
gh-121735@footnote{https://github.com/python/cpython/issues/121735}: When working with zip archives, importlib.resources now
properly honors module-adjacent references (e.g. @code{files(pkg.mod)} and
not just @code{files(pkg)}).

@item 
gh-122145@footnote{https://github.com/python/cpython/issues/122145}: Fix an issue when reporting tracebacks corresponding to Python
code emitting an empty AST body. Patch by Nikita Sobolev and Bénédikt
Tran.

@item 
gh-119004@footnote{https://github.com/python/cpython/issues/119004}: Fix a crash in @ref{154f,,OrderedDict.__eq__} when operands are mutated during the
check. Patch by Bénédikt Tran.

@item 
bpo-44864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44864}: Do not translate user-provided strings in
@ref{523,,argparse.ArgumentParser}.
@end itemize

@node IDLE<4>,Documentation<3>,Library<3>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id15}@anchor{1550}
@subsubsection IDLE



@itemize -

@item 
gh-112938@footnote{https://github.com/python/cpython/issues/112938}: Fix uninteruptable hang when Shell gets rapid continuous
output.

@item 
gh-120104@footnote{https://github.com/python/cpython/issues/120104}: Fix padding in config and search dialog windows in IDLE.
@end itemize

@node Documentation<3>,Core and Builtins<4>,IDLE<4>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id16}@anchor{1551}
@subsubsection Documentation



@itemize -

@item 
gh-124720@footnote{https://github.com/python/cpython/issues/124720}: Update "Using Python on a Mac" section of the "Python Setup and
Usage" document and include information on installing free-threading
support.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Add an Android platform guide, and flag modules not available
on Android.
@end itemize

@node Core and Builtins<4>,C API<3>,Documentation<3>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id17}@anchor{1552}
@subsubsection Core and Builtins



@itemize -

@item 
gh-124567@footnote{https://github.com/python/cpython/issues/124567}: Revert the incremental GC (in 3.13), since it's not clear the
benefits outweigh the costs at this point.

@item 
gh-124642@footnote{https://github.com/python/cpython/issues/124642}: Fixed scalability issue in free-threaded builds for lock-free
reads from dictionaries in multi-threaded scenarios

@item 
gh-116510@footnote{https://github.com/python/cpython/issues/116510}: Fix a bug that can cause a crash when sub-interpreters use
"basic" single-phase extension modules.  Shared objects could refer to
PyGC_Head nodes that had been freed as part of interpreter cleanup.

@item 
gh-124547@footnote{https://github.com/python/cpython/issues/124547}: When deallocating an object with inline values whose
@code{__dict__} is still live: if memory allocation for the inline values
fails, clear the dictionary. Prevents an interpreter crash.

@item 
gh-124513@footnote{https://github.com/python/cpython/issues/124513}: Fix a crash in FrameLocalsProxy constructor: check the number
of arguments. Patch by Victor Stinner.

@item 
gh-124442@footnote{https://github.com/python/cpython/issues/124442}: Fix nondeterminism in compilation by sorting the value of
@ref{14a,,__static_attributes__}. Patch by kp2pml30.

@item 
gh-123856@footnote{https://github.com/python/cpython/issues/123856}: Fix PyREPL failure when a keyboard interrupt is triggered after
using a history search

@item 
gh-65961@footnote{https://github.com/python/cpython/issues/65961}: Document the deprecation of setting and using @code{__package__}
and @code{__cached__}.

@item 
gh-124027@footnote{https://github.com/python/cpython/issues/124027}: Support @code{<page up>}, @code{<page down>}, and @code{<delete>} keys
in the Python REPL when @code{$TERM} is set to @code{vt100}.

@item 
gh-77894@footnote{https://github.com/python/cpython/issues/77894}: Fix possible crash in the garbage collector when it tries to
break a reference loop containing a @ref{452,,memoryview} object. Now a
@code{memoryview} object can only be cleared if there are no buffers
that refer it.

@item 
gh-123339@footnote{https://github.com/python/cpython/issues/123339}: Setting the @code{__module__} attribute for a class now
removes the @code{__firstlineno__} item from the type's dict, so they will no
longer be inconsistent.
@end itemize

@node C API<3>,Build<3>,Core and Builtins<4>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id18}@anchor{1553}
@subsubsection C API



@itemize -

@item 
gh-124160@footnote{https://github.com/python/cpython/issues/124160}: Fix crash when importing modules containing state and
single-phase initialization in a subinterpreter.

@item 
gh-123880@footnote{https://github.com/python/cpython/issues/123880}: Fixed a bug that prevented circular imports of extension
modules that use single-phase initialization.
@end itemize

@node Build<3>,,C API<3>,Python 3 13 0 release candidate 3
@anchor{whatsnew/changelog id19}@anchor{1554}
@subsubsection Build



@itemize -

@item 
gh-124487@footnote{https://github.com/python/cpython/issues/124487}: Windows builds now use Windows 8.1 as their API baseline
(installation already required Windows 8.1).

@item 
gh-124043@footnote{https://github.com/python/cpython/issues/124043}: Building using @ref{38b,,--with-trace-refs} is (temporarily)
disallowed when the GIL is disabled.
@end itemize

@node Python 3 13 0 release candidate 2,Python 3 13 0 release candidate 1,Python 3 13 0 release candidate 3,Changelog
@anchor{whatsnew/changelog python-3-13-0-release-candidate-2}@anchor{1555}
@subsection Python 3.13.0 release candidate 2


`Release date: 2024-09-06'

@menu
* macOS: macOS<3>. 
* Windows: Windows<4>. 
* Tools/Demos: Tools/Demos<3>. 
* Tests: Tests<4>. 
* Security: Security<3>. 
* Library: Library<4>. 
* IDLE: IDLE<5>. 
* Core and Builtins: Core and Builtins<5>. 
* C API: C API<4>. 
* Build: Build<4>. 

@end menu

@node macOS<3>,Windows<4>,,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id20}@anchor{1556}
@subsubsection macOS



@itemize -

@item 
gh-123418@footnote{https://github.com/python/cpython/issues/123418}: Updated macOS installer build to use OpenSSL 3.0.15.
@end itemize

@node Windows<4>,Tools/Demos<3>,macOS<3>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id21}@anchor{1557}
@subsubsection Windows



@itemize -

@item 
gh-123418@footnote{https://github.com/python/cpython/issues/123418}: Updated Windows build to use OpenSSL 3.0.15.

@item 
gh-122573@footnote{https://github.com/python/cpython/issues/122573}: The Windows build of CPython now requires 3.10 or newer.

@item 
gh-100256@footnote{https://github.com/python/cpython/issues/100256}: @ref{8e,,mimetypes} no longer fails when it encounters an
inaccessible registry key.

@item 
gh-79846@footnote{https://github.com/python/cpython/issues/79846}: Makes @code{ssl.create_default_context()} ignore invalid
certificates in the Windows certificate store
@end itemize

@node Tools/Demos<3>,Tests<4>,Windows<4>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id22}@anchor{1558}
@subsubsection Tools/Demos



@itemize -

@item 
gh-123418@footnote{https://github.com/python/cpython/issues/123418}: Update GitHub CI workflows to use OpenSSL 3.0.15 and
multissltests to use 3.0.15, 3.1.7, and 3.2.3.
@end itemize

@node Tests<4>,Security<3>,Tools/Demos<3>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id23}@anchor{1559}
@subsubsection Tests



@itemize -

@item 
gh-119727@footnote{https://github.com/python/cpython/issues/119727}: Add @code{--single-process} command line option to Python test
runner (regrtest). Patch by Victor Stinner.

@item 
gh-101525@footnote{https://github.com/python/cpython/issues/101525}: Skip @code{test_gdb} if the binary is relocated by BOLT. Patch by
Donghee Na.
@end itemize

@node Security<3>,Library<4>,Tests<4>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id24}@anchor{155a}
@subsubsection Security



@itemize -

@item 
gh-123678@footnote{https://github.com/python/cpython/issues/123678}: Upgrade libexpat to 2.6.3

@item 
gh-121285@footnote{https://github.com/python/cpython/issues/121285}: Remove backtracking from tarfile header parsing for
@code{hdrcharset}, PAX, and GNU sparse headers.
@end itemize

@node Library<4>,IDLE<5>,Security<3>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id25}@anchor{155b}
@subsubsection Library



@itemize -

@item 
gh-123657@footnote{https://github.com/python/cpython/issues/123657}: Fix crash and memory leak in @ref{155c,,decimal.getcontext()}. It
crashed when using a thread-local context by
@code{--with-decimal-contextvar=no}.

@item 
gh-123448@footnote{https://github.com/python/cpython/issues/123448}: Fixed memory leak of @ref{25f,,typing.NoDefault} by moving it to
the static types array.

@item 
gh-123409@footnote{https://github.com/python/cpython/issues/123409}: Fix @ref{155d,,ipaddress.IPv6Address.reverse_pointer} output
according to 
@geindex RFC; RFC 3596 Section 2.5
RFC 3596@comma{} §2.5@footnote{https://datatracker.ietf.org/doc/html/rfc3596.html#section-2.5}.  Patch by Bénédikt
Tran.

@item 
gh-123270@footnote{https://github.com/python/cpython/issues/123270}: Applied a more surgical fix for malformed payloads in
@ref{6b4,,zipfile.Path} causing infinite loops (gh-122905@footnote{https://github.com/python/cpython/issues/122905}) without breaking
contents using legitimate characters.

@item 
gh-123228@footnote{https://github.com/python/cpython/issues/123228}: Fix return type for
@code{_pyrepl.readline._ReadlineWrapper.get_line_buffer()} to be
@ref{435,,str()}.  Patch by Sergey B Kirpichev.

@item 
gh-123240@footnote{https://github.com/python/cpython/issues/123240}: Raise audit events for the @ref{12b6,,input()} in the new REPL.

@item 
gh-123243@footnote{https://github.com/python/cpython/issues/123243}: Fix memory leak in @code{_decimal}.

@item 
gh-122546@footnote{https://github.com/python/cpython/issues/122546}: Consistently use same file name for different exceptions in the
new repl. Patch by Sergey B Kirpichev.

@item 
gh-123213@footnote{https://github.com/python/cpython/issues/123213}: @ref{11b0,,xml.etree.ElementTree.Element.extend()} and
@ref{305,,Element} assignment no longer hide the
internal exception if an erronous generator is passed. Patch by Bar Harel.

@item 
gh-85110@footnote{https://github.com/python/cpython/issues/85110}: Preserve relative path in URL without netloc in
@ref{155e,,urllib.parse.urlunsplit()} and @ref{155f,,urllib.parse.urlunparse()}.

@item 
gh-123067@footnote{https://github.com/python/cpython/issues/123067}: Fix quadratic complexity in parsing @code{"}-quoted cookie values
with backslashes by @ref{70,,http.cookies}.

@item 
gh-122981@footnote{https://github.com/python/cpython/issues/122981}: Fix @ref{154d,,inspect.getsource()} for generated classes with Python
base classes (e.g. enums).

@item 
gh-122903@footnote{https://github.com/python/cpython/issues/122903}: @code{zipfile.Path.glob} now correctly matches directories instead
of silently omitting them.

@item 
gh-122905@footnote{https://github.com/python/cpython/issues/122905}: @ref{6b4,,zipfile.Path} objects now sanitize names from the
zipfile.

@item 
gh-122695@footnote{https://github.com/python/cpython/issues/122695}: Fixed double-free when using @ref{7ef,,gc.get_referents()} with a
freed @ref{bbb,,asyncio.Future} iterator.

@item 
gh-116263@footnote{https://github.com/python/cpython/issues/116263}: @ref{1560,,logging.handlers.RotatingFileHandler} no longer rolls
over empty log files.

@item 
gh-105376@footnote{https://github.com/python/cpython/issues/105376}: Restore the deprecated @ref{86,,logging} @code{warn()} method. It was
removed in Python 3.13 alpha 1. Keep the deprecated @code{warn()} method in
Python 3.13. Patch by Victor Stinner.

@item 
gh-122744@footnote{https://github.com/python/cpython/issues/122744}: Bump the version of pip bundled in ensurepip to version 24.2.

@item 
gh-118814@footnote{https://github.com/python/cpython/issues/118814}: Fix the @ref{15c,,typing.TypeVar} constructor when name is passed
by keyword.

@item 
gh-122478@footnote{https://github.com/python/cpython/issues/122478}: Remove internal frames from tracebacks shown in
@ref{1561,,code.InteractiveInterpreter} with non-default
@ref{7f5,,sys.excepthook()}. Save correct tracebacks in
@ref{4aa,,sys.last_traceback} and update @code{__traceback__} attribute of
@ref{4a9,,sys.last_value} and @ref{4a7,,sys.last_exc}.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: On Android, the @code{FICLONE} and @code{FICLONERANGE} constants are
no longer exposed by @ref{58,,fcntl}, as these ioctls are blocked by SELinux.

@item 
gh-82378@footnote{https://github.com/python/cpython/issues/82378}: Make sure that the new @ref{169,,REPL} interprets
@ref{1562,,sys.tracebacklimit} in the same way that the classic REPL did.

@item 
gh-122334@footnote{https://github.com/python/cpython/issues/122334}: Fix crash when importing @ref{cf,,ssl} after the main interpreter
restarts.

@item 
gh-87320@footnote{https://github.com/python/cpython/issues/87320}: In @ref{1561,,code.InteractiveInterpreter}, handle exceptions
caused by calling a non-default @ref{7f5,,sys.excepthook()}. Before, the
exception bubbled up to the caller, ending the @ref{169,,REPL}.

@item 
gh-121650@footnote{https://github.com/python/cpython/issues/121650}: @ref{3b,,email} headers with embedded newlines are now quoted on
output. The @ref{40,,generator} will now refuse to serialize (write)
headers that are unsafely folded or delimited; see
@ref{1dd,,verify_generated_headers}. (Contributed by Bas
Bloemsaat and Petr Viktorin in gh-121650@footnote{https://github.com/python/cpython/issues/121650}.)

@item 
gh-121723@footnote{https://github.com/python/cpython/issues/121723}: Make @ref{118d,,logging.config.dictConfig()} accept any object
implementing the Queue public API. See the @ref{1563,,queue configuration} section for details. Patch by Bénédikt Tran.

@item 
gh-122081@footnote{https://github.com/python/cpython/issues/122081}: Fix a crash in the @code{decimal.IEEEContext()} optional
function available via the @code{EXTRA_FUNCTIONALITY} configuration flag.

@item 
gh-121804@footnote{https://github.com/python/cpython/issues/121804}: Correctly show error locations, when @ref{18b,,SyntaxError} raised
in new repl. Patch by Sergey B Kirpichev.

@item 
gh-121151@footnote{https://github.com/python/cpython/issues/121151}: Fix wrapping of long usage text of arguments inside a mutually
exclusive group in @ref{6,,argparse}.

@item 
gh-108172@footnote{https://github.com/python/cpython/issues/108172}: @code{webbrowser} honors OS preferred browser on Linux when its
desktop entry name contains the text of a known browser name.

@item 
gh-109109@footnote{https://github.com/python/cpython/issues/109109}: You can now get the raw TLS certificate chains from TLS
connections via @ref{1564,,ssl.SSLSocket.get_verified_chain()} and
@ref{1565,,ssl.SSLSocket.get_unverified_chain()} methods.

Contributed by Mateusz Nowak.
@end itemize

@node IDLE<5>,Core and Builtins<5>,Library<4>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id26}@anchor{1566}
@subsubsection IDLE



@itemize -

@item 
gh-120083@footnote{https://github.com/python/cpython/issues/120083}: Add explicit black IDLE Hovertip foreground color needed for
recent macOS. Fixes Sonoma showing unreadable white on pale yellow.  Patch
by John Riggles.
@end itemize

@node Core and Builtins<5>,C API<4>,IDLE<5>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id27}@anchor{1567}
@subsubsection Core and Builtins



@itemize -

@item 
gh-120221@footnote{https://github.com/python/cpython/issues/120221}: asyncio REPL is now again properly recognizing
KeyboardInterrupts. Display of exceptions raised in secondary threads is
fixed.

@item 
gh-119310@footnote{https://github.com/python/cpython/issues/119310}: Allow the new interactive shell to read history files written
with the editline library that use unicode-escaped entries.  Patch by
aorcajo and Łukasz Langa.

@item 
gh-123572@footnote{https://github.com/python/cpython/issues/123572}: Fix key mappings for various F-keys in Windows for the new
REPL. Patch by devdanzin

@item 
gh-119034@footnote{https://github.com/python/cpython/issues/119034}: Change @code{<page up>} and @code{<page down>} keys of the Python
REPL to history search forward/backward. Patch by Victor Stinner.

@item 
gh-123545@footnote{https://github.com/python/cpython/issues/123545}: Fix a double decref in rare cases on experimental JIT builds.

@item 
gh-123484@footnote{https://github.com/python/cpython/issues/123484}: Fix @code{_Py_DebugOffsets} for long objects to be relative to the
start of the object rather than the start of a subobject.

@item 
gh-123344@footnote{https://github.com/python/cpython/issues/123344}: Add AST optimizations for type parameter defaults.

@item 
gh-123321@footnote{https://github.com/python/cpython/issues/123321}: Prevent Parser/myreadline race condition from segfaulting on
multi-threaded use. Patch by Bar Harel and Amit Wienner.

@item 
gh-123177@footnote{https://github.com/python/cpython/issues/123177}: Fix a bug causing stray prompts to appear in the middle of
wrapped lines in the new REPL.

@item 
gh-122982@footnote{https://github.com/python/cpython/issues/122982}: Extend the deprecation period for bool inversion (@code{~}) by two
years.

@item 
gh-123275@footnote{https://github.com/python/cpython/issues/123275}: Support @ref{175,,-X gil=1} and 
@geindex PYTHON_GIL
@geindex variable d'environnement; PYTHON_GIL
@ref{174,,PYTHON_GIL=1} on non-free-threaded builds.

@item 
gh-123177@footnote{https://github.com/python/cpython/issues/123177}: Deactivate line wrap in the Apple Terminal via a ANSI escape
code. Patch by Pablo Galindo

@item 
gh-123229@footnote{https://github.com/python/cpython/issues/123229}: Fix valgrind warning by initializing the f-string buffers to 0
in the tokenizer. Patch by Pablo Galindo

@item 
gh-122298@footnote{https://github.com/python/cpython/issues/122298}: Restore printout of GC stats when
@code{gc.set_debug(gc.DEBUG_STATS)} is called. This featue was accidentally
removed when implementing incremental GC.

@item 
gh-121804@footnote{https://github.com/python/cpython/issues/121804}: Correctly show error locations when a @ref{18b,,SyntaxError} is
raised in the basic REPL. Patch by Sergey B Kirpichev.

@item 
gh-123142@footnote{https://github.com/python/cpython/issues/123142}: Fix too-wide source location in exception tracebacks coming
from broken iterables in comprehensions.

@item 
gh-123048@footnote{https://github.com/python/cpython/issues/123048}: Fix a bug where pattern matching code could emit a
@ref{1568,,JUMP_FORWARD} with no source location.

@item 
gh-123123@footnote{https://github.com/python/cpython/issues/123123}: Fix displaying @ref{18b,,SyntaxError} exceptions covering multiple
lines. Patch by Pablo Galindo

@item 
gh-123083@footnote{https://github.com/python/cpython/issues/123083}: Fix a potential use-after-free in @code{STORE_ATTR_WITH_HINT}.

@item 
gh-123022@footnote{https://github.com/python/cpython/issues/123022}: Fix crash in free-threaded build when calling
@ref{899,,Py_Initialize()} from a non-main thread.

@item 
gh-122888@footnote{https://github.com/python/cpython/issues/122888}: Fix crash on certain calls to @code{str()} with positional
arguments of the wrong type. Patch by Jelle Zijlstra.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Fix Android stdout and stderr messages being truncated or lost.

@item 
gh-122527@footnote{https://github.com/python/cpython/issues/122527}: Fix a crash that occurred when a @code{PyStructSequence} was
deallocated after its type's dictionary was cleared by the GC.  The type's
@ref{974,,tp_basicsize} now accounts for non-sequence
fields that aren't included in the @ref{76c,,Py_SIZE} of the sequence.

@item 
gh-122445@footnote{https://github.com/python/cpython/issues/122445}: Add only fields which are modified via self.* to
@ref{14a,,__static_attributes__}.

@item 
gh-98442@footnote{https://github.com/python/cpython/issues/98442}: Fix too wide source locations of the cleanup instructions of a
with statement.

@item 
gh-93691@footnote{https://github.com/python/cpython/issues/93691}: Fix source locations of instructions generated for with
statements.

@item 
gh-120097@footnote{https://github.com/python/cpython/issues/120097}: @code{FrameLocalsProxy} now subclasses @code{collections.abc.Mapping}
and can be matched as a mapping in @code{match} statements
@end itemize

@node C API<4>,Build<4>,Core and Builtins<5>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id28}@anchor{1569}
@subsubsection C API



@itemize -

@item 
gh-122728@footnote{https://github.com/python/cpython/issues/122728}: Fix @ref{34b,,PyEval_GetLocals()} to avoid @ref{561,,SystemError}
("bad argument to internal function"). Patch by Victor Stinner.
@end itemize

@node Build<4>,,C API<4>,Python 3 13 0 release candidate 2
@anchor{whatsnew/changelog id29}@anchor{156a}
@subsubsection Build



@itemize -

@item 
gh-123418@footnote{https://github.com/python/cpython/issues/123418}: Updated Android build to use OpenSSL 3.0.15.

@item 
gh-123297@footnote{https://github.com/python/cpython/issues/123297}: Propagate the value of @code{LDFLAGS} to @code{LDCXXSHARED} in
@ref{da,,sysconfig}. Patch by Pablo Galindo

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Rename build variable @code{MODULE_LDFLAGS} back to @code{LIBPYTHON},
as it's used by package build systems (e.g. Meson).

@item 
gh-118943@footnote{https://github.com/python/cpython/issues/118943}: Fix an issue where the experimental JIT could be built several
times by the @code{make regen-all} target, leading to possible race
conditions on heavily parallelized builds.

@item 
gh-118943@footnote{https://github.com/python/cpython/issues/118943}: Fix a possible race condition affecting parallel builds
configured with @code{--enable-experimental-jit}, in which
@ref{eae,,FileNotFoundError} could be caused by another process already moving
@code{jit_stencils.h.new} to @code{jit_stencils.h}.
@end itemize

@node Python 3 13 0 release candidate 1,Python 3 13 0 beta 4,Python 3 13 0 release candidate 2,Changelog
@anchor{whatsnew/changelog python-3-13-0-release-candidate-1}@anchor{156b}
@subsection Python 3.13.0 release candidate 1


`Release date: 2024-07-31'

@menu
* Tests: Tests<5>. 
* Security: Security<4>. 
* Library: Library<5>. 
* IDLE: IDLE<6>. 
* Core and Builtins: Core and Builtins<6>. 
* C API: C API<5>. 
* Build: Build<5>. 

@end menu

@node Tests<5>,Security<4>,,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id30}@anchor{156c}
@subsubsection Tests



@itemize -

@item 
gh-59022@footnote{https://github.com/python/cpython/issues/59022}: Add tests for @ref{156d,,pkgutil.extend_path()}. Patch by Andreas
Stocker.

@item 
gh-99242@footnote{https://github.com/python/cpython/issues/99242}: @ref{156e,,os.getloadavg()} may throw @ref{40d,,OSError} when running
regression tests under certain conditions (e.g. chroot). This error is now
caught and ignored, since reporting load average is optional.
@end itemize

@node Security<4>,Library<5>,Tests<5>,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id31}@anchor{156f}
@subsubsection Security



@itemize -

@item 
gh-122133@footnote{https://github.com/python/cpython/issues/122133}: Authenticate the socket connection for the
@code{socket.socketpair()} fallback on platforms where @code{AF_UNIX} is not
available like Windows.

Patch by Gregory P. Smith <@email{greg@@krypto.org}> and Seth Larson
<@email{seth@@python.org}>. Reported by Ellie <@email{el@@horse64.org}>

@item 
gh-121957@footnote{https://github.com/python/cpython/issues/121957}: Fixed missing audit events around interactive use of Python,
now also properly firing for @code{python -i}, as well as for @code{python -m
asyncio}. The events in question are @code{cpython.run_stdin} and
@code{cpython.run_startup}.
@end itemize

@node Library<5>,IDLE<6>,Security<4>,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id32}@anchor{1570}
@subsubsection Library



@itemize -

@item 
gh-122400@footnote{https://github.com/python/cpython/issues/122400}: Handle @ref{1ff,,ValueError}s raised by @ref{48a,,os.stat()} in
@ref{f2b,,filecmp.dircmp} and @ref{1571,,filecmp.cmpfiles()}. Patch by Bénédikt
Tran.

@item 
gh-122311@footnote{https://github.com/python/cpython/issues/122311}: Fix some error messages in @ref{a5,,pickle}.

@item 
gh-122332@footnote{https://github.com/python/cpython/issues/122332}: Fixed segfault with @ref{9c9,,asyncio.Task.get_coro()} when using an
eager task factory.

@item 
gh-105733@footnote{https://github.com/python/cpython/issues/105733}: @ref{299,,ctypes.ARRAY()} is now @ref{206,,soft deprecated}: it no
longer emits deprecation warnings and is not scheduled for removal.

@item 
gh-122087@footnote{https://github.com/python/cpython/issues/122087}: Restore @ref{1572,,inspect.ismethoddescriptor()} and
@ref{1573,,inspect.isroutine()} returning @code{False} for
@ref{40a,,functools.partial} objects.

@item 
gh-122170@footnote{https://github.com/python/cpython/issues/122170}: Handle @ref{1ff,,ValueError}s raised by @ref{48a,,os.stat()} in
@ref{84,,linecache}. Patch by Bénédikt Tran.

@item 
gh-82951@footnote{https://github.com/python/cpython/issues/82951}: Serializing objects with complex @code{__qualname__} (such as
unbound methods and nested classes) by name no longer involves serializing
parent objects by value in pickle protocols < 4.

@item 
gh-113785@footnote{https://github.com/python/cpython/issues/113785}: @ref{29,,csv} now correctly parses numeric fields (when used with
@ref{1574,,csv.QUOTE_NONNUMERIC} or @ref{46f,,csv.QUOTE_STRINGS}) which start
with an escape character.

@item 
gh-122088@footnote{https://github.com/python/cpython/issues/122088}: @ref{15f,,@@warnings.deprecated} now copies
the coroutine status of functions and methods so that
@ref{2e2,,inspect.iscoroutinefunction()} returns the correct result.

@item 
gh-120930@footnote{https://github.com/python/cpython/issues/120930}: Fixed a bug introduced by gh-92081@footnote{https://github.com/python/cpython/issues/92081} that added an incorrect
extra blank to encoded words occurring in wrapped headers.

@item 
gh-121474@footnote{https://github.com/python/cpython/issues/121474}: Fix missing sanity check for @code{parties} arg in
@ref{11c0,,threading.Barrier} constructor. Patch by Clinton Christian
(pygeek).

@item 
gh-120289@footnote{https://github.com/python/cpython/issues/120289}: Fixed the use-after-free issue in @ref{27,,cProfile} by
disallowing @code{disable()} and @code{clear()} in external timers.
@end itemize

@node IDLE<6>,Core and Builtins<6>,Library<5>,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id33}@anchor{1575}
@subsubsection IDLE



@itemize -

@item 
gh-122482@footnote{https://github.com/python/cpython/issues/122482}: Change About IDLE to direct users to discuss.python.org instead
of the now unused idle-dev email and mailing list.
@end itemize

@node Core and Builtins<6>,C API<5>,IDLE<6>,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id34}@anchor{1576}
@subsubsection Core and Builtins



@itemize -

@item 
gh-116090@footnote{https://github.com/python/cpython/issues/116090}: Fix an issue in JIT builds that prevented some @ref{2e6,,for}
loops from correctly firing @ref{1577,,RAISE} monitoring events.

@item 
gh-122208@footnote{https://github.com/python/cpython/issues/122208}: Dictionary watchers now only deliver the PyDict_EVENT_ADDED
event when the insertion is in a known good state to succeed.

@item 
gh-122300@footnote{https://github.com/python/cpython/issues/122300}: Preserve AST nodes for f-string with single-element format
specifiers. Patch by Pablo Galindo

@item 
gh-120906@footnote{https://github.com/python/cpython/issues/120906}: @ref{180,,frame.f_locals} now supports arbitrary hashable objects
as keys.

@item 
gh-122029@footnote{https://github.com/python/cpython/issues/122029}: Emit @code{c_call} events in @ref{14b5,,sys.setprofile()} when a
@code{PyMethodObject} pointing to a @code{PyCFunction} is called.

@item 
gh-122026@footnote{https://github.com/python/cpython/issues/122026}: Fix a bug that caused the tokenizer to not correctly identify
mismatched parentheses inside f-strings in some situations. Patch by Pablo
Galindo

@item 
gh-118934@footnote{https://github.com/python/cpython/issues/118934}: Make @code{PyEval_GetLocals} return borrowed reference
@end itemize

@node C API<5>,Build<5>,Core and Builtins<6>,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id35}@anchor{1578}
@subsubsection C API



@itemize -

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Make @ref{1579,,PyObject_Print} work around a bug in Android and
OpenBSD which prevented it from throwing an exception when trying to write
to a read-only stream.

@item 
gh-121489@footnote{https://github.com/python/cpython/issues/121489}: Export private @code{_PyBytes_Join()} again.
@end itemize

@node Build<5>,,C API<5>,Python 3 13 0 release candidate 1
@anchor{whatsnew/changelog id36}@anchor{157a}
@subsubsection Build



@itemize -

@item 
gh-120522@footnote{https://github.com/python/cpython/issues/120522}: Added a @ref{157b,,--with-app-store-compliance} option to patch
out known issues with macOS/iOS App Store review processes.
@end itemize

@node Python 3 13 0 beta 4,Python 3 13 0 beta 3,Python 3 13 0 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-13-0-beta-4}@anchor{157c}
@subsection Python 3.13.0 beta 4


`Release date: 2024-07-18'

@menu
* Tests: Tests<6>. 
* Library: Library<6>. 
* IDLE: IDLE<7>. 
* Documentation: Documentation<4>. 
* Core and Builtins: Core and Builtins<7>. 
* C API: C API<6>. 
* Build: Build<6>. 

@end menu

@node Tests<6>,Library<6>,,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id37}@anchor{157d}
@subsubsection Tests



@itemize -

@item 
gh-121084@footnote{https://github.com/python/cpython/issues/121084}: Fix test_typing random leaks. Clear typing ABC caches when
running tests for refleaks (@code{-R} option): call @code{_abc_caches_clear()}
on typing abstract classes and their subclasses. Patch by Victor Stinner.

@item 
gh-121160@footnote{https://github.com/python/cpython/issues/121160}: Add a test for @ref{157e,,readline.set_history_length()}. Note that
this test may fail on readline libraries.

@item 
gh-121200@footnote{https://github.com/python/cpython/issues/121200}: Fix @code{test_expanduser_pwd2()} of @code{test_posixpath}.  Call
@code{getpwnam()} to get @code{pw_dir}, since it can be different than
@code{getpwall()} @code{pw_dir}. Patch by Victor Stinner.

@item 
gh-121188@footnote{https://github.com/python/cpython/issues/121188}: When creating the JUnit XML file, regrtest now escapes
characters which are invalid in XML, such as the chr(27) control character
used in ANSI escape sequences. Patch by Victor Stinner.
@end itemize

@node Library<6>,IDLE<7>,Tests<6>,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id38}@anchor{157f}
@subsubsection Library



@itemize -

@item 
gh-57141@footnote{https://github.com/python/cpython/issues/57141}: The `shallow' argument to @ref{f2b,,filecmp.dircmp} (new in Python
3.13) is now keyword-only.

@item 
gh-121245@footnote{https://github.com/python/cpython/issues/121245}: Simplify handling of the history file in
@code{site.register_readline()} helper. The @code{CAN_USE_PYREPL} variable now
will be initialized, when imported.  Patch by Sergey B Kirpichev.

@item 
gh-121332@footnote{https://github.com/python/cpython/issues/121332}: Fix constructor of @ref{8,,ast} nodes with custom
@code{_attributes}. Previously, passing custom attributes would raise a
@ref{1a3,,DeprecationWarning}. Passing arguments to the constructor that
are not in @code{_fields} or @code{_attributes} remains deprecated. Patch by
Jelle Zijlstra.

@item 
gh-121279@footnote{https://github.com/python/cpython/issues/121279}: Avoid @ref{428,,NameError} for the @ref{111,,warnings} module when
accessing the depracated atributes of the @ref{77,,importlib.abc} module.

@item 
gh-121245@footnote{https://github.com/python/cpython/issues/121245}: Fix a bug in the handling of the command history of the new
@ref{169,,REPL} that caused the history file to be wiped at REPL exit.

@item 
gh-87744@footnote{https://github.com/python/cpython/issues/87744}: Fix waitpid race while calling
@ref{1580,,send_signal()} in asyncio. Patch by Kumar
Aditya.

@item 
gh-121018@footnote{https://github.com/python/cpython/issues/121018}: Fixed other issues where @ref{523,,argparse.ArgumentParser} did
not honor @code{exit_on_error=False}.

@item 
gh-120678@footnote{https://github.com/python/cpython/issues/120678}: Fix regression in the new REPL that meant that globals from
files passed using the @code{-i} argument would not be included in the REPL's
global namespace. Patch by Alex Waygood.

@item 
gh-120782@footnote{https://github.com/python/cpython/issues/120782}: Fix wrong references of the @ref{30,,datetime} types after
reloading the module.

@item 
gh-120713@footnote{https://github.com/python/cpython/issues/120713}: @ref{c7e,,datetime.datetime.strftime()} now 0-pads years with less
than four digits for the format specifiers @code{%Y} and @code{%G} on Linux.
Patch by Ben Hsing

@item 
gh-117983@footnote{https://github.com/python/cpython/issues/117983}: Defer the @code{threading} import in @code{importlib.util} until lazy
loading is used.

@item 
gh-119189@footnote{https://github.com/python/cpython/issues/119189}: When using the @code{**} operator or @ref{9c0,,pow()} with
@ref{1e4,,Fraction} as the base and an exponent that is not
rational, a float, or a complex, the fraction is no longer converted to a
float.

@item 
gh-118714@footnote{https://github.com/python/cpython/issues/118714}: Allow @code{restart} in post-mortem debugging of @ref{a4,,pdb}.
Removed restart message when the user quits pdb from post-mortem mode.

@item 
gh-105623@footnote{https://github.com/python/cpython/issues/105623}: Fix performance degradation in
@ref{1560,,logging.handlers.RotatingFileHandler}. Patch by Craig Robson.
@end itemize

@node IDLE<7>,Documentation<4>,Library<6>,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id39}@anchor{1581}
@subsubsection IDLE



@itemize -

@item 
gh-78889@footnote{https://github.com/python/cpython/issues/78889}: Stop Shell freezes by blocking user access to non-method
sys.stdout.shell attributes, which are all private.
@end itemize

@node Documentation<4>,Core and Builtins<7>,IDLE<7>,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id40}@anchor{1582}
@subsubsection Documentation



@itemize -

@item 
gh-121749@footnote{https://github.com/python/cpython/issues/121749}: Fix documentation for @ref{35b,,PyModule_AddObjectRef()}.

@item 
gh-120012@footnote{https://github.com/python/cpython/issues/120012}: Clarify the behaviours of @ref{1583,,multiprocessing.Queue.empty()}
and @ref{1584,,multiprocessing.SimpleQueue.empty()} on closed queues. Patch by
Bénédikt Tran.
@end itemize

@node Core and Builtins<7>,C API<6>,Documentation<4>,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id41}@anchor{1585}
@subsubsection Core and Builtins



@itemize -

@item 
gh-121860@footnote{https://github.com/python/cpython/issues/121860}: Fix crash when rematerializing a managed dictionary after it
was deleted.

@item 
gh-121814@footnote{https://github.com/python/cpython/issues/121814}: Fixed the SegFault when @ref{14b4,,PyEval_SetTrace()} is used with
no Python frame on stack.

@item 
gh-121295@footnote{https://github.com/python/cpython/issues/121295}: Fix PyREPL console getting into a blocked state after
interrupting a long paste

@item 
gh-121794@footnote{https://github.com/python/cpython/issues/121794}: Fix bug in free-threaded Python where a resurrected object
could lead to a negative ref count assertion failure.

@item 
gh-121657@footnote{https://github.com/python/cpython/issues/121657}: Improve the @ref{18b,,SyntaxError} message if the user tries to use
@ref{9bb,,yield from} outside a function.

@item 
gh-121609@footnote{https://github.com/python/cpython/issues/121609}: Fix pasting of characters containing unicode character joiners
in the new REPL. Patch by Marta Gomez Macias

@item 
gh-117482@footnote{https://github.com/python/cpython/issues/117482}: Unexpected slot wrappers are no longer created for builtin
static types in subinterpreters.

@item 
gh-121499@footnote{https://github.com/python/cpython/issues/121499}: Fix a bug affecting how multi-line history was being rendered
in the new REPL after interacting with the new screen cache. Patch by
Pablo Galindo

@item 
gh-121497@footnote{https://github.com/python/cpython/issues/121497}: Fix a bug that was preventing the REPL to correctly respect the
history when an input hook was set. Patch by Pablo Galindo

@item 
gh-121012@footnote{https://github.com/python/cpython/issues/121012}: Tier 2 execution now ensures that list iterators remain
exhausted, once they become exhausted.

@item 
gh-121439@footnote{https://github.com/python/cpython/issues/121439}: Allow tuples of length 20 in the freelist to be reused.

@item 
gh-121368@footnote{https://github.com/python/cpython/issues/121368}: Fix race condition in @code{_PyType_Lookup} in the free-threaded
build due to a missing memory fence.  This could lead to
@code{_PyType_Lookup} returning incorrect results on arm64.

@item 
gh-121130@footnote{https://github.com/python/cpython/issues/121130}: Fix f-strings with debug expressions in format specifiers.
Patch by Pablo Galindo

@item 
gh-121115@footnote{https://github.com/python/cpython/issues/121115}: @ref{357,,PyLong_AsNativeBytes()} no longer uses
@ref{707,,__index__()} methods by default. The
@code{Py_ASNATIVEBYTES_ALLOW_INDEX} flag has been added to allow it.
@end itemize

@node C API<6>,Build<6>,Core and Builtins<7>,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id42}@anchor{1586}
@subsubsection C API



@itemize -

@item 
gh-89364@footnote{https://github.com/python/cpython/issues/89364}: Export the @ref{1392,,PySignal_SetWakeupFd()} function. Previously,
the function was documented but it couldn't be used in 3rd party code.
Patch by Victor Stinner.

@item 
gh-113993@footnote{https://github.com/python/cpython/issues/113993}: @ref{89e,,PyUnicode_InternInPlace()} no longer prevents its
argument from being garbage collected.

Several functions that take @code{char *} are now documented as possibly
preventing string objects from being garbage collected; refer to their
documentation for details: @ref{1587,,PyUnicode_InternFromString()},
@ref{1588,,PyDict_SetItemString()}, @ref{1589,,PyObject_SetAttrString()},
@ref{158a,,PyObject_DelAttrString()}, @ref{1587,,PyUnicode_InternFromString()},
and @code{PyModule_Add*} convenience functions.

@item 
gh-113601@footnote{https://github.com/python/cpython/issues/113601}: Removed debug build assertions related to interning strings,
which were falsely triggered by stable ABI extensions.

@item 
gh-112136@footnote{https://github.com/python/cpython/issues/112136}: Restore the private @code{_PyArg_Parser} structure and the private
@code{_PyArg_ParseTupleAndKeywordsFast()} function, previously removed in
Python 3.13 alpha 1. Patch by Victor Stinner.
@end itemize

@node Build<6>,,C API<6>,Python 3 13 0 beta 4
@anchor{whatsnew/changelog id43}@anchor{158b}
@subsubsection Build



@itemize -

@item 
gh-120371@footnote{https://github.com/python/cpython/issues/120371}: Support WASI SDK 22 by explicitly skipping functions that are
just stubs in wasi-libc.

@item 
gh-121731@footnote{https://github.com/python/cpython/issues/121731}: Fix mimalloc compile error on GNU/Hurd

@item 
gh-121487@footnote{https://github.com/python/cpython/issues/121487}: Fix deprecation warning for ATOMIC_VAR_INIT in mimalloc.

@item 
gh-121467@footnote{https://github.com/python/cpython/issues/121467}: Fix a Makefile bug that prevented mimalloc header files from
being installed.

@item 
gh-121103@footnote{https://github.com/python/cpython/issues/121103}: On POSIX systems, excluding macOS framework installs, the lib
directory for the free-threaded build now includes a "t" suffix to avoid
conflicts with a co-located default build installation.

@item 
gh-120831@footnote{https://github.com/python/cpython/issues/120831}: The default minimum iOS version was increased to 13.0.

@item 
gh-113565@footnote{https://github.com/python/cpython/issues/113565}: Improve @ref{2b,,curses} and @ref{2d,,curses.panel} dependency checks
in @code{configure}.
@end itemize

@node Python 3 13 0 beta 3,Python 3 13 0 beta 2,Python 3 13 0 beta 4,Changelog
@anchor{whatsnew/changelog python-3-13-0-beta-3}@anchor{158c}
@subsection Python 3.13.0 beta 3


`Release date: 2024-06-27'

@menu
* Core and Builtins: Core and Builtins<8>. 
* Library: Library<7>. 
* Build: Build<7>. 
* C API: C API<7>. 

@end menu

@node Core and Builtins<8>,Library<7>,,Python 3 13 0 beta 3
@anchor{whatsnew/changelog id44}@anchor{158d}
@subsubsection Core and Builtins



@itemize -

@item 
gh-120838@footnote{https://github.com/python/cpython/issues/120838}: @ref{1330,,Py_Finalize()} and @ref{d03,,Py_FinalizeEx()} now
always run with the main interpreter active.

@item 
gh-113433@footnote{https://github.com/python/cpython/issues/113433}: Subinterpreters now get cleaned up automatically during runtime
finalization.

@item 
gh-119462@footnote{https://github.com/python/cpython/issues/119462}: Make sure that invariants of type versioning are maintained: *
Superclasses always have their version number assigned before subclasses *
The version tag is always zero if the tag is not valid. * The version tag
is always non-zero if the tag is valid.

@item 
gh-120437@footnote{https://github.com/python/cpython/issues/120437}: Fix @code{_CHECK_STACK_SPACE} optimization problems introduced in
gh-118322@footnote{https://github.com/python/cpython/issues/118322}.

@item 
gh-120722@footnote{https://github.com/python/cpython/issues/120722}: Correctly set the bytecode position on return instructions
within lambdas. Patch by Jelle Zijlstra.

@item 
gh-120367@footnote{https://github.com/python/cpython/issues/120367}: Fix bug where compiler creates a redundant jump during
pseudo-op replacement. Can only happen with a synthetic AST that has a try
on the same line as the instruction following the exception handler.

@item 
gh-113993@footnote{https://github.com/python/cpython/issues/113993}: Strings interned with @ref{12b9,,sys.intern()} are again
garbage-collected when no longer used, as per the documentation. Strings
interned with the C function @ref{89e,,PyUnicode_InternInPlace()} are still
immortal. Internals of the string interning mechanism have been changed.
This may affect performance and identities of @ref{435,,str} objects.

@item 
gh-120384@footnote{https://github.com/python/cpython/issues/120384}: Fix an array out of bounds crash in @code{list_ass_subscript},
which could be invoked via some specificly tailored input: including
concurrent modification of a list object, where one thread assigns a slice
and another clears it.

@item 
gh-120367@footnote{https://github.com/python/cpython/issues/120367}: Fix crash in compiler on code with redundant NOPs and JUMPs
which show up after exception handlers are moved to the end of the code.

@item 
gh-120380@footnote{https://github.com/python/cpython/issues/120380}: Fix Python implementation of @ref{a0c,,pickle.Pickler} for
@ref{1bd,,bytes} and @ref{528,,bytearray} objects when using protocol version
5. Patch by Bénédikt Tran.

@item 
gh-120400@footnote{https://github.com/python/cpython/issues/120400}: Support Linux perf profiler to see Python calls on RISC-V
architecture.

@item 
gh-120221@footnote{https://github.com/python/cpython/issues/120221}: Deliver real signals on Ctrl-C and Ctrl-Z in the new REPL.
Patch by Pablo Galindo

@item 
gh-120346@footnote{https://github.com/python/cpython/issues/120346}: Respect 
@geindex PYTHON_BASIC_REPL
@geindex variable d'environnement; PYTHON_BASIC_REPL
@ref{16d,,PYTHON_BASIC_REPL} when running in interative
inspect mode (@code{python -i}). Patch by Pablo Galindo

@item 
gh-93691@footnote{https://github.com/python/cpython/issues/93691}: Fix source locations of instructions generated for the iterator
of a for statement.

@item 
gh-120198@footnote{https://github.com/python/cpython/issues/120198}: Fix a crash when multiple threads read and write to the same
@code{__class__} of an object concurrently.

@item 
gh-120298@footnote{https://github.com/python/cpython/issues/120298}: Fix use-after free in @code{list_richcompare_impl} which can be
invoked via some specificly tailored evil input.

@item 
gh-119666@footnote{https://github.com/python/cpython/issues/119666}: Fix a compiler crash in the case where two comprehensions in
class scope both reference @code{__class__}.

@item 
gh-120225@footnote{https://github.com/python/cpython/issues/120225}: Fix crash in compiler on empty block at end of exception
handler.

@item 
gh-119933@footnote{https://github.com/python/cpython/issues/119933}: Improve @ref{18b,,SyntaxError} messages for invalid expressions in
a type parameters bound, a type parameter constraint tuple or a default
type parameter. Patch by Bénédikt Tran.

@item 
bpo-24766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24766}: Fix handling of @code{doc} argument to subclasses of @code{property}.
@end itemize

@node Library<7>,Build<7>,Core and Builtins<8>,Python 3 13 0 beta 3
@anchor{whatsnew/changelog id45}@anchor{158e}
@subsubsection Library



@itemize -

@item 
gh-121027@footnote{https://github.com/python/cpython/issues/121027}: Add a future warning in @code{functools.partial.__get__()}. In
future Python versions @ref{40a,,functools.partial} will be a method
descriptor.

@item 
gh-121025@footnote{https://github.com/python/cpython/issues/121025}: Improve the @ref{607,,__repr__()} of
@ref{a69,,functools.partialmethod}. Patch by Bénédikt Tran.

@item 
gh-121018@footnote{https://github.com/python/cpython/issues/121018}: Fixed an issue where
@code{argparse.ArgumentParser.parses_args()} did not honor
@code{exit_on_error=False} when given unrecognized arguments. Patch by Ben
Hsing.

@item 
gh-119614@footnote{https://github.com/python/cpython/issues/119614}: Fix truncation of strings with embedded null characters in some
internal operations in @ref{ef,,tkinter}.

@item 
gh-120910@footnote{https://github.com/python/cpython/issues/120910}: When reading installed files from an egg, use
@code{relative_to(walk_up=True)} to honor files installed outside of the
installation root.

@item 
gh-120888@footnote{https://github.com/python/cpython/issues/120888}: Upgrade pip wheel bundled with ensurepip (pip 24.1.1)

@item 
gh-101830@footnote{https://github.com/python/cpython/issues/101830}: Accessing the @ref{ef,,tkinter} object's string representation no
longer converts the underlying Tcl object to a string on Windows.

@item 
gh-120811@footnote{https://github.com/python/cpython/issues/120811}: Fix possible memory leak in @ref{158f,,contextvars.Context.run()}.

@item 
gh-120769@footnote{https://github.com/python/cpython/issues/120769}: Make empty line in @ref{a4,,pdb} repeats the last command even
when the command is from @code{cmdqueue}.

@item 
gh-120732@footnote{https://github.com/python/cpython/issues/120732}: Fix @code{name} passing to @ref{a3a,,unittest.mock.Mock} object when
using @ref{1590,,unittest.mock.create_autospec()}.

@item 
gh-120683@footnote{https://github.com/python/cpython/issues/120683}: Fix an error in @ref{fd1,,logging.LogRecord}, when the integer
part of the timestamp is rounded up, while the millisecond calculation
truncates, causing the log timestamp to be wrong by up to 999 ms (affected
roughly 1 in 8 million timestamps).

@item 
gh-120633@footnote{https://github.com/python/cpython/issues/120633}: Move scrollbar and remove tear-off menus in turtledemo.

@item 
gh-120541@footnote{https://github.com/python/cpython/issues/120541}: Improve the prompt in the "less" pager when @ref{8c4,,help()} is
called with non-string argument.

@item 
gh-120495@footnote{https://github.com/python/cpython/issues/120495}: Fix incorrect exception handling in Tab Nanny. Patch by
Wulian233.

@item 
gh-120381@footnote{https://github.com/python/cpython/issues/120381}: Correct @ref{1572,,inspect.ismethoddescriptor()} to check also for
the lack of @ref{1591,,__delete__()}.  Patch by Jan Kaliszewski.

@item 
gh-90425@footnote{https://github.com/python/cpython/issues/90425}: The OS byte in gzip headers is now always set to 255 when using
@ref{629,,gzip.compress()}.

@item 
gh-120343@footnote{https://github.com/python/cpython/issues/120343}: Fix column offset reporting for tokens that come after
multiline f-strings in the @ref{fa,,tokenize} module.

@item 
gh-119600@footnote{https://github.com/python/cpython/issues/119600}: Fix @ref{e7b,,unittest.mock.patch()} to not read attributes of the
target when @code{new_callable} is set. Patch by Robert Collins.

@item 
gh-114053@footnote{https://github.com/python/cpython/issues/114053}: Fix edge-case bug where @ref{69c,,typing.get_type_hints()} would
produce incorrect results if type parameters in a class scope were
overridden by assignments in a class scope and @code{from __future__ import
annotations} semantics were enabled. Patch by Alex Waygood.

@item 
gh-114053@footnote{https://github.com/python/cpython/issues/114053}: Fix erroneous @ref{428,,NameError} when calling
@ref{7fd,,inspect.get_annotations()} with @code{eval_str=True`} on a class that
made use of 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} type parameters in a module that had @code{from
__future__ import annotations} at the top of the file. Patch by Alex
Waygood.

@item 
gh-120268@footnote{https://github.com/python/cpython/issues/120268}: Prohibit passing @code{None} to pure-Python
@ref{1592,,datetime.date.fromtimestamp()} to achieve consistency with
C-extension implementation.

@item 
gh-120244@footnote{https://github.com/python/cpython/issues/120244}: Fix memory leak in @ref{2a0,,re.sub()} when the replacement string
contains backreferences.

@item 
gh-120211@footnote{https://github.com/python/cpython/issues/120211}: Fix @ref{f8,,tkinter.ttk} with Tcl/Tk 9.0.

@item 
gh-71587@footnote{https://github.com/python/cpython/issues/71587}: Fix crash in C version of @ref{1593,,datetime.datetime.strptime()}
when called again on the restarted interpreter.

@item 
gh-120161@footnote{https://github.com/python/cpython/issues/120161}: @ref{30,,datetime} no longer crashes in certain complex reference
cycle situations.

@item 
gh-119698@footnote{https://github.com/python/cpython/issues/119698}: Fix @ref{2e3,,symtable.Class.get_methods()} and document its
behaviour. Patch by Bénédikt Tran.

@item 
gh-120121@footnote{https://github.com/python/cpython/issues/120121}: Add @ref{1594,,concurrent.futures.InvalidStateError} to module's
@code{__all__}.

@item 
gh-119933@footnote{https://github.com/python/cpython/issues/119933}: Add the @ref{1595,,symtable.SymbolTableType} enumeration to
represent the possible outputs of the
@ref{1596,,symtable.SymbolTable.get_type} method. Patch by Bénédikt Tran.

@item 
gh-120108@footnote{https://github.com/python/cpython/issues/120108}: Fix calling @ref{b5c,,copy.deepcopy()} on @ref{8,,ast} trees that have
been modified to have references to parent nodes. Patch by Jelle Zijlstra.

@item 
gh-112672@footnote{https://github.com/python/cpython/issues/112672}: Support building @ref{ef,,tkinter} with Tcl 9.0.

@item 
gh-65454@footnote{https://github.com/python/cpython/issues/65454}: @ref{1597,,unittest.mock.Mock.attach_mock()} no longer triggers a call
to a @code{PropertyMock} being attached.

@item 
gh-81936@footnote{https://github.com/python/cpython/issues/81936}: @code{help()} and @code{showtopic()} methods now respect a
configured `output' argument to @code{pydoc.Helper} and not use the
pager in such cases. Patch by Enrico Tröger.

@item 
gh-119577@footnote{https://github.com/python/cpython/issues/119577}: The @ref{1a3,,DeprecationWarning} emitted when testing the truth
value of an @ref{305,,xml.etree.ElementTree.Element} now describes
unconditionally returning @code{True} in a future version rather than raising
an exception in Python 3.14.

@item 
gh-118908@footnote{https://github.com/python/cpython/issues/118908}: Limit exposed globals from internal imports and definitions on
new REPL startup. Patch by Eugene Triguba and Pablo Galindo.

@item 
gh-119506@footnote{https://github.com/python/cpython/issues/119506}: Fix @code{io.TextIOWrapper.write()} method breaks internal
buffer when the method is called again during flushing internal buffer.
@end itemize

@node Build<7>,C API<7>,Library<7>,Python 3 13 0 beta 3
@anchor{whatsnew/changelog id46}@anchor{1598}
@subsubsection Build



@itemize -

@item 
gh-120671@footnote{https://github.com/python/cpython/issues/120671}: Fix failing configure tests due to a missing space when
appending to CFLAGS.

@item 
gh-120602@footnote{https://github.com/python/cpython/issues/120602}: Correctly handle LLVM installs with @code{LLVM_VERSION_SUFFIX}
when building with @code{--enable-experimental-jit}.

@item 
gh-120326@footnote{https://github.com/python/cpython/issues/120326}: On Windows, fix build error when @code{--disable-gil} and
@code{--experimental-jit} options are combined.

@item 
gh-120291@footnote{https://github.com/python/cpython/issues/120291}: Make the @code{python-config} shell script compatible with
non-bash shells.
@end itemize

@node C API<7>,,Build<7>,Python 3 13 0 beta 3
@anchor{whatsnew/changelog id47}@anchor{1599}
@subsubsection C API



@itemize -

@item 
gh-120642@footnote{https://github.com/python/cpython/issues/120642}: Remove the private @code{_Py_CODEUNIT} type from the public C API.
The internal @code{pycore_code.h} header should now be used to get this
internal type. Patch by Victor Stinner.

@item 
gh-120858@footnote{https://github.com/python/cpython/issues/120858}: @ref{159a,,PyDict_Next()} no longer locks the dictionary in the
free-threaded build.  The locking needs to be done by the caller around
the entire iteration loop.

@item 
gh-120642@footnote{https://github.com/python/cpython/issues/120642}: Remove the following unstable functions:


@itemize *

@item 
@code{PyUnstable_Replace_Executor()}

@item 
@code{PyUnstable_SetOptimizer()}

@item 
@code{PyUnstable_GetOptimizer()}

@item 
@code{PyUnstable_GetExecutor()}

@item 
@code{PyUnstable_Optimizer_NewCounter()}

@item 
@code{PyUnstable_Optimizer_NewUOpOptimizer()}
@end itemize

Patch by Victor Stinner.

@item 
gh-119344@footnote{https://github.com/python/cpython/issues/119344}: The critical section API is now public as part of the
non-limited C API.

@item 
gh-118789@footnote{https://github.com/python/cpython/issues/118789}: Add @ref{159b,,PyUnstable_Object_ClearWeakRefsNoCallbacks()}, which
clears weakrefs without calling their callbacks.

@item 
gh-117511@footnote{https://github.com/python/cpython/issues/117511}: Make the @ref{15a,,PyMutex} public in the non-limited C API.
@end itemize

@node Python 3 13 0 beta 2,Python 3 13 0 beta 1,Python 3 13 0 beta 3,Changelog
@anchor{whatsnew/changelog python-3-13-0-beta-2}@anchor{159c}
@subsection Python 3.13.0 beta 2


`Release date: 2024-06-05'

@menu
* Security: Security<5>. 
* Core and Builtins: Core and Builtins<9>. 
* Library: Library<8>. 
* Tests: Tests<7>. 
* Build: Build<8>. 
* Windows: Windows<5>. 
* C API: C API<8>. 

@end menu

@node Security<5>,Core and Builtins<9>,,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id48}@anchor{159d}
@subsubsection Security



@itemize -

@item 
gh-118773@footnote{https://github.com/python/cpython/issues/118773}: Fixes creation of ACLs in @ref{21a,,os.mkdir()} on Windows to work
correctly on non-English machines.

@item 
gh-118486@footnote{https://github.com/python/cpython/issues/118486}: @ref{21a,,os.mkdir()} on Windows now accepts `mode' of @code{0o700} to
restrict the new directory to the current user. This fixes
@geindex Common Vulnerabilities and Exposures; CVE 2024-4030
CVE 2024-4030@footnote{https://www.cve.org/CVERecord?id=CVE-2024-4030} affecting @ref{21c,,tempfile.mkdtemp()} in scenarios where the
base temporary directory is more permissive than the default.
@end itemize

@node Core and Builtins<9>,Library<8>,Security<5>,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id49}@anchor{159e}
@subsubsection Core and Builtins



@itemize -

@item 
gh-119724@footnote{https://github.com/python/cpython/issues/119724}: Reverted improvements to error messages for @code{elif}/@code{else}
statements not matching any valid statements, which made in hard to locate
the syntax errors inside those @code{elif}/@code{else} blocks.

@item 
gh-119842@footnote{https://github.com/python/cpython/issues/119842}: Honor @ref{571,,PyOS_InputHook()} in the new REPL. Patch by Pablo
Galindo

@item 
gh-119821@footnote{https://github.com/python/cpython/issues/119821}: Fix execution of @ref{186,,annotation scopes}
within classes when @code{globals} is set to a non-dict. Patch by Jelle
Zijlstra.

@item 
gh-119548@footnote{https://github.com/python/cpython/issues/119548}: Add a @code{clear} command to the REPL. Patch by Pablo Galindo

@item 
gh-111999@footnote{https://github.com/python/cpython/issues/111999}: Fix the signature of @ref{dc4,,str.format_map()}.

@item 
gh-119560@footnote{https://github.com/python/cpython/issues/119560}: An invalid assert in beta 1 has been removed.  The assert would
fail if @code{PyState_FindModule()} was used in an extension module's init
function before the module def had been initialized.

@item 
gh-119369@footnote{https://github.com/python/cpython/issues/119369}: Fix deadlock during thread deletion in free-threaded build,
which could occur when the GIL was enabled at runtime.

@item 
gh-119525@footnote{https://github.com/python/cpython/issues/119525}: Fix deadlock involving @code{_PyType_Lookup()} cache in the
free-threaded build when the GIL is dynamically enabled at runtime.

@item 
gh-119311@footnote{https://github.com/python/cpython/issues/119311}: Fix bug where names are unexpectedly mangled in the bases of
generic classes.

@item 
gh-119395@footnote{https://github.com/python/cpython/issues/119395}: Fix bug where names appearing after a generic class are mangled
as if they are in the generic class.

@item 
gh-119213@footnote{https://github.com/python/cpython/issues/119213}: Non-builtin modules built with argument clinic were crashing if
used in a subinterpreter before the main interpreter.  The objects that
were causing the problem by leaking between interpreters carelessly have
been fixed.

@item 
gh-119011@footnote{https://github.com/python/cpython/issues/119011}: Fixes @code{type.__type_params__} to return an empty tuple instead
of a descriptor.

@item 
gh-118692@footnote{https://github.com/python/cpython/issues/118692}: Avoid creating unnecessary @ref{be8,,StopIteration} instances for
monitoring.

@item 
gh-119049@footnote{https://github.com/python/cpython/issues/119049}: Fix displaying the source line for warnings created by the C
API if the @ref{111,,warnings} module had not yet been imported.

@item 
gh-118844@footnote{https://github.com/python/cpython/issues/118844}: Fix build failures when configuring with both @code{--disable-gil}
and @code{--enable-experimental-jit}.

@item 
gh-118921@footnote{https://github.com/python/cpython/issues/118921}: Add @code{copy()} method for @code{FrameLocalsProxy} which returns a
snapshot @code{dict} for local variables.

@item 
gh-117657@footnote{https://github.com/python/cpython/issues/117657}: Fix data races on the field that stores a pointer to the
interpreter's main thread that occur in free-threaded builds.

@item 
gh-118561@footnote{https://github.com/python/cpython/issues/118561}: Fix race condition in free-threaded build where
@code{list.extend()} could expose uninitialised memory to concurrent
readers.

@item 
gh-117195@footnote{https://github.com/python/cpython/issues/117195}: Avoid assertion failure for debug builds when calling
@code{object.__sizeof__(1)}
@end itemize

@node Library<8>,Tests<7>,Core and Builtins<9>,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id50}@anchor{159f}
@subsubsection Library



@itemize -

@item 
gh-119819@footnote{https://github.com/python/cpython/issues/119819}: Fix regression to allow logging configuration with
multiprocessing queue types.

@item 
gh-117142@footnote{https://github.com/python/cpython/issues/117142}: The @ref{2a,,ctypes} module may now be imported in all
subinterpreters, including those that have their own GIL.

@item 
gh-118835@footnote{https://github.com/python/cpython/issues/118835}: Fix _pyrepl crash when using custom prompt with ANSI escape
codes.

@item 
gh-117398@footnote{https://github.com/python/cpython/issues/117398}: The @code{_datetime} module (C implementation for @ref{30,,datetime})
now supports being imported in multiple interpreters.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Fix issue with @ref{2f5,,shutil.rmtree()} where a
@ref{d59,,RecursionError} is raised on deep directory trees.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Partially fix issue with @ref{2f5,,shutil.rmtree()} where a
@ref{d59,,RecursionError} is raised on deep directory trees. A recursion error
is no longer raised when @code{rmtree.avoids_symlink_attacks} is false.

@item 
gh-119118@footnote{https://github.com/python/cpython/issues/119118}: Fix performance regression in the @ref{fa,,tokenize} module by
caching the @code{line} token attribute and calculating the column offset
more efficiently.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Fix issue with @ref{b49,,os.fwalk()} where a @ref{d59,,RecursionError}
was raised on deep directory trees by adjusting the implementation to be
iterative instead of recursive.

@item 
gh-119588@footnote{https://github.com/python/cpython/issues/119588}: @code{zipfile.Path.is_symlink} now assesses if the given path is a
symlink.

@item 
gh-119555@footnote{https://github.com/python/cpython/issues/119555}: Catch @ref{18b,,SyntaxError} from @ref{190,,compile()} in the
runsource() method of the InteractiveColoredConsole.  Patch by Sergey B
Kirpichev.

@item 
gh-113892@footnote{https://github.com/python/cpython/issues/113892}: Now, the method @code{sock_connect} of
@ref{5f4,,asyncio.ProactorEventLoop} raises a @ref{1ff,,ValueError} if given
socket is not in non-blocking mode, as well as in other loop
implementations.

@item 
gh-119443@footnote{https://github.com/python/cpython/issues/119443}: The interactive REPL no longer runs with @code{from __future__
import annotations} enabled. Patch by Jelle Zijlstra.

@item 
gh-117398@footnote{https://github.com/python/cpython/issues/117398}: Objects in the datetime C-API are now all statically allocated,
which means better memory safety, especially when the module is reloaded.
This should be transparent to users.

@item 
gh-118894@footnote{https://github.com/python/cpython/issues/118894}: @ref{a,,asyncio} REPL now has the same capabilities as PyREPL.

@item 
gh-118911@footnote{https://github.com/python/cpython/issues/118911}: In PyREPL, updated @code{maybe-accept}'s logic so that if the user
hits @code{Enter} twice, they are able to terminate the block even if
there's trailing whitespace. Also, now when the user hits arrow up, the
cursor is on the last functional line. This matches IPython's behavior.
Patch by Aya Elsayed.

@item 
gh-111201@footnote{https://github.com/python/cpython/issues/111201}: Remove dependency to @ref{b9,,readline} from the new Python REPL.

@item 
gh-119174@footnote{https://github.com/python/cpython/issues/119174}: Fix high DPI causes turtledemo(turtle-graphics examples)
windows blurry Patch by Wulian233 and Terry Jan Reedy

@item 
gh-119121@footnote{https://github.com/python/cpython/issues/119121}: Fix a NameError happening in
@code{asyncio.staggered.staggered_race}. This function is now tested.

@item 
gh-119113@footnote{https://github.com/python/cpython/issues/119113}: Fix issue where @ref{15a0,,pathlib.PurePath.with_suffix()} didn't
raise @ref{522,,TypeError} when given @code{None} as a suffix.

@item 
gh-118643@footnote{https://github.com/python/cpython/issues/118643}: Fix an AttributeError in the @ref{3b,,email} module when re-fold a
long address list. Also fix more cases of incorrect encoding of the
address separator in the address list.

@item 
gh-58933@footnote{https://github.com/python/cpython/issues/58933}: Make @ref{a4,,pdb} return to caller frame correctly when
@code{f_trace} of the caller frame is not set

@item 
gh-118895@footnote{https://github.com/python/cpython/issues/118895}: Setting attributes on @ref{25f,,typing.NoDefault} now raises
@ref{343,,AttributeError} instead of @ref{522,,TypeError}.

@item 
gh-118868@footnote{https://github.com/python/cpython/issues/118868}: Fixed issue where kwargs were no longer passed to the logging
handler QueueHandler

@item 
gh-118851@footnote{https://github.com/python/cpython/issues/118851}: @code{ctx} arguments to the constructors of @ref{8,,ast} node
classes now default to @ref{1a2,,ast.Load()}. Patch by Jelle
Zijlstra.

@item 
gh-118760@footnote{https://github.com/python/cpython/issues/118760}: Restore the default value of @code{tkiter.wantobjects} to @code{1}.

@item 
gh-118760@footnote{https://github.com/python/cpython/issues/118760}: Fix errors in calling Tkinter bindings on Windows.

@item 
gh-118507@footnote{https://github.com/python/cpython/issues/118507}: Fix @ref{9ff,,os.path.isfile()} on Windows for pipes. Speedup
@ref{48d,,os.path.isjunction()} and @ref{9fd,,os.path.lexists()} on Windows with a
native implementation.

@item 
gh-118772@footnote{https://github.com/python/cpython/issues/118772}: Allow @ref{15c,,typing.TypeVar} instances without a default to
follow instances without a default in some cases. Patch by Jelle Zijlstra.

@item 
gh-110863@footnote{https://github.com/python/cpython/issues/110863}: @ref{222,,os.path.realpath()} now suppresses any @ref{40d,,OSError} from
@ref{90d,,os.readlink()} when `strict' mode is disabled (the default).

@item 
gh-118263@footnote{https://github.com/python/cpython/issues/118263}: Speed up @ref{48e,,os.path.splitroot()} & @ref{12f8,,os.path.normpath()}
with a direct C call.

@item 
gh-118033@footnote{https://github.com/python/cpython/issues/118033}: Fix @ref{1c6,,dataclasses.dataclass()} not creating a
@code{__weakref__} slot when subclassing @ref{15a1,,typing.Generic}.

@item 
gh-106531@footnote{https://github.com/python/cpython/issues/106531}: In @ref{7a,,importlib.resources}, sync with importlib_resources 6.3.2@footnote{https://importlib-resources.readthedocs.io/en/latest/history.html#v6-3-2},
including: @code{MultiplexedPath} now expects @code{Traversable} paths,
deprecating string arguments to @code{MultiplexedPath}; Enabled support for
resources in namespace packages in zip files; Fixed @code{NotADirectoryError}
when calling files on a subdirectory of a namespace package.

@item 
gh-113978@footnote{https://github.com/python/cpython/issues/113978}: Ignore warnings on text completion inside REPL.

@item 
gh-103956@footnote{https://github.com/python/cpython/issues/103956}: Fix lack of newline characters in @ref{fc,,trace} module output
when line tracing is enabled but source code line for current frame is not
available.

@item 
gh-92081@footnote{https://github.com/python/cpython/issues/92081}: Fix missing spaces in email headers when the spaces are mixed
with encoded 8-bit characters.

@item 
gh-103194@footnote{https://github.com/python/cpython/issues/103194}: Prepare Tkinter for C API changes in Tcl 8.7/9.0 to avoid
@code{_tkinter.Tcl_Obj} being unexpectedly returned instead of
@ref{451,,bool}, @ref{435,,str}, @ref{528,,bytearray}, or @ref{254,,int}.

@item 
gh-87106@footnote{https://github.com/python/cpython/issues/87106}: Fixed handling in @ref{15a2,,inspect.Signature.bind()} of keyword
arguments having the same name as positional-only arguments when a
variadic keyword argument (e.g. @code{**kwargs}) is present.

@item 
bpo-45767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45767}: Fix integer conversion in @ref{15a3,,os.major()}, @ref{15a4,,os.minor()},
and @ref{15a5,,os.makedev()}. Support device numbers larger than @code{2**63-1}.
Support non-existent device number (@code{NODEV}).

@item 
gh-67693@footnote{https://github.com/python/cpython/issues/67693}: Fix @ref{155f,,urllib.parse.urlunparse()} and
@ref{155e,,urllib.parse.urlunsplit()} for URIs with path starting with multiple
slashes and no authority. Based on patch by Ashwin Ramaswami.
@end itemize

@node Tests<7>,Build<8>,Library<8>,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id51}@anchor{15a6}
@subsubsection Tests



@itemize -

@item 
gh-119050@footnote{https://github.com/python/cpython/issues/119050}: regrtest test runner: Add XML support to the refleak checker
(-R option). Patch by Victor Stinner.
@end itemize

@node Build<8>,Windows<5>,Tests<7>,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id52}@anchor{15a7}
@subsubsection Build



@itemize -

@item 
gh-119729@footnote{https://github.com/python/cpython/issues/119729}: On POSIX systems, the pkg-config (@code{.pc}) filenames now
include the ABI flags, which may include debug ("d") and free-threaded
("t").  For example: * @code{python-3.14.pc} (default, non-debug build) *
@code{python-3.14d.pc} (default, debug build) * @code{python-3.14t.pc}
(free-threaded build)

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: Fall back to the bundled libmpdec if a system version cannot be
found.

@item 
gh-119132@footnote{https://github.com/python/cpython/issues/119132}: Update @ref{177,,sys.version} to identify whether the build is
default build or free-threading build. Patch By Donghee Na.

@item 
gh-118836@footnote{https://github.com/python/cpython/issues/118836}: Fix an @code{AssertionError} when building with
@code{--enable-experimental-jit} and the compiler emits a @code{SHT_NOTE}
section.

@item 
gh-118943@footnote{https://github.com/python/cpython/issues/118943}: Fix a possible race condition affecting parallel builds
configured with @code{--enable-experimental-jit}, in which compilation errors
could be caused by an incompletely-generated header file.
@end itemize

@node Windows<5>,C API<8>,Build<8>,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id53}@anchor{15a8}
@subsubsection Windows



@itemize -

@item 
gh-119679@footnote{https://github.com/python/cpython/issues/119679}: Ensures correct import libraries are included in Windows
installs.

@item 
gh-119690@footnote{https://github.com/python/cpython/issues/119690}: Adds Unicode support and fixes audit events for
@code{_winapi.CreateNamedPipe}.

@item 
gh-111201@footnote{https://github.com/python/cpython/issues/111201}: Add support for new pyrepl on Windows

@item 
gh-119070@footnote{https://github.com/python/cpython/issues/119070}: Fixes @code{py.exe} handling of shebangs like @code{/usr/bin/env
python3.12}, which were previously interpreted as @code{python3.exe} instead
of @code{python3.12.exe}.

@item 
gh-117505@footnote{https://github.com/python/cpython/issues/117505}: Fixes an issue with the Windows installer not running ensurepip
in a fully isolated environment. This could cause unexpected interactions
with the user site-packages.

@item 
gh-118209@footnote{https://github.com/python/cpython/issues/118209}: Avoid crashing in @ref{8f,,mmap} on Windows when the mapped memory
is inaccessible due to file system errors or access violations.

@item 
gh-116145@footnote{https://github.com/python/cpython/issues/116145}: Updated bundled Tcl/Tk to 8.6.14.
@end itemize

@node C API<8>,,Windows<5>,Python 3 13 0 beta 2
@anchor{whatsnew/changelog id54}@anchor{15a9}
@subsubsection C API



@itemize -

@item 
gh-119585@footnote{https://github.com/python/cpython/issues/119585}: Fix crash when a thread state that was created by
@ref{3a2,,PyGILState_Ensure()} calls a destructor that during
@ref{15aa,,PyThreadState_Clear()} that calls back into
@ref{3a2,,PyGILState_Ensure()} and @ref{3a3,,PyGILState_Release()}. This might
occur when in the free-threaded build or when using thread-local variables
whose destructors call @ref{3a2,,PyGILState_Ensure()}.

@item 
gh-119336@footnote{https://github.com/python/cpython/issues/119336}: Restore the removed @code{_PyLong_NumBits()} function. It is used
by the pywin32 project. Patch by Ethan Smith

@item 
gh-119247@footnote{https://github.com/python/cpython/issues/119247}: Added @code{Py_BEGIN_CRITICAL_SECTION_SEQUENCE_FAST} and
@code{Py_END_CRITICAL_SECTION_SEQUENCE_FAST} macros to make it possible to
use PySequence_Fast APIs safely when free-threaded, and update str.join to
work without the GIL using them.

@item 
gh-111389@footnote{https://github.com/python/cpython/issues/111389}: Add @ref{15ab,,PyHASH_MULTIPLIER} constant: prime multiplier
used in string and various other hashes. Patch by Victor Stinner.

@item 
gh-116984@footnote{https://github.com/python/cpython/issues/116984}: Make mimalloc includes relative to the current file to avoid
embedders or extensions needing to include @code{Internal/mimalloc} if they
are already including internal CPython headers.

@item 
gh-118789@footnote{https://github.com/python/cpython/issues/118789}: Restore @code{_PyWeakref_ClearRef} that was previously removed in
Python 3.13 alpha 1.
@end itemize

@node Python 3 13 0 beta 1,Python 3 13 0 alpha 6,Python 3 13 0 beta 2,Changelog
@anchor{whatsnew/changelog python-3-13-0-beta-1}@anchor{15ac}
@subsection Python 3.13.0 beta 1


`Release date: 2024-05-08'

@menu
* Security: Security<6>. 
* Core and Builtins: Core and Builtins<10>. 
* Library: Library<9>. 
* Documentation: Documentation<5>. 
* Build: Build<9>. 
* Windows: Windows<6>. 
* macOS: macOS<4>. 
* IDLE: IDLE<8>. 
* C API: C API<9>. 

@end menu

@node Security<6>,Core and Builtins<10>,,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id55}@anchor{15ad}
@subsubsection Security



@itemize -

@item 
gh-116741@footnote{https://github.com/python/cpython/issues/116741}: Update bundled libexpat to 2.6.2

@item 
gh-117233@footnote{https://github.com/python/cpython/issues/117233}: Detect BLAKE2, SHA3, Shake, & truncated SHA512 support in the
OpenSSL-ish libcrypto library at build time.  This allows @ref{67,,hashlib}
to be used with libraries that do not to support every algorithm that
upstream OpenSSL does.
@end itemize

@node Core and Builtins<10>,Library<9>,Security<6>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id56}@anchor{15ae}
@subsubsection Core and Builtins



@itemize -

@item 
gh-118414@footnote{https://github.com/python/cpython/issues/118414}: Add instrumented opcodes to YIELD_VALUE assertion for tracing
cases.

@item 
gh-117953@footnote{https://github.com/python/cpython/issues/117953}: When a builtin or extension module is imported for the first
time, while a subinterpreter is active, the module's init function is now
run by the main interpreter first before import continues in the
subinterpreter. Consequently, single-phase init modules now fail in an
isolated subinterpreter without the init function running under that
interpreter, whereas before it would run under the subinterpreter `before'
failing, potentially leaving behind global state and callbacks and
otherwise leaving the module in an inconsistent state.

@item 
gh-117549@footnote{https://github.com/python/cpython/issues/117549}: Don't use designated initializer syntax in inline functions in
internal headers. They cause problems for C++ or MSVC users who aren't yet
using the latest C++ standard (C++20). While internal, pycore_backoff.h,
is included (indirectly, via pycore_code.h) by some key 3rd party software
that does so for speed.

@item 
gh-95382@footnote{https://github.com/python/cpython/issues/95382}: Improve performance of @ref{d33,,json.dumps()} and @ref{d32,,json.dump()}
when using the argument `indent'. Depending on the data the encoding using
@ref{d33,,json.dumps()} with `indent' can be up to 2 to 3 times faster.

@item 
gh-116322@footnote{https://github.com/python/cpython/issues/116322}: In @code{--disable-gil} builds, the GIL will be enabled while
loading C extension modules. If the module indicates that it supports
running without the GIL, the GIL will be disabled once loading is
complete. Otherwise, the GIL will remain enabled for the remainder of the
interpreter's lifetime. This behavior does not apply if the GIL has been
explicitly enabled or disabled with @code{PYTHON_GIL} or @code{-Xgil}.

@item 
gh-118513@footnote{https://github.com/python/cpython/issues/118513}: Fix incorrect @ref{14ec,,UnboundLocalError} when two comprehensions
in the same function both reference the same name, and in one
comprehension the name is bound while in the other it's an implicit
global.

@item 
gh-118518@footnote{https://github.com/python/cpython/issues/118518}: Allow the Linux perf support to work without frame pointers
using perf's advanced JIT support. The feature is activated when using the
@code{PYTHON_PERF_JIT_SUPPORT} environment variable or when running Python
with @code{-Xperf_jit}. Patch by Pablo Galindo.

@item 
gh-117514@footnote{https://github.com/python/cpython/issues/117514}: Add @code{sys._is_gil_enabled()} function that returns whether the
GIL is currently enabled.  In the default build it always returns @code{True}
because the GIL is always enabled.  In the free-threaded build, it may
return @code{True} or @code{False}.

@item 
gh-118164@footnote{https://github.com/python/cpython/issues/118164}: Break a loop between the Python implementation of the
@ref{36,,decimal} module and the Python code for integer to string
conversion. Also optimize integer to string conversion for values in the
range from 9_000 to 135_000 decimal digits.

@item 
gh-118473@footnote{https://github.com/python/cpython/issues/118473}: Fix @ref{15af,,sys.set_asyncgen_hooks()} not to be partially set when
raising @ref{522,,TypeError}.

@item 
gh-118465@footnote{https://github.com/python/cpython/issues/118465}: Compiler populates the new @code{__firstlineno__} field on a class
with the line number of the first line of the class definition.

@item 
gh-118492@footnote{https://github.com/python/cpython/issues/118492}: Fix an issue where the type cache can expose a previously
accessed attribute when a finalizer is run.

@item 
gh-117714@footnote{https://github.com/python/cpython/issues/117714}: update @code{async_generator.athrow().close()} and
@code{async_generator.asend().close()} to close their section of the
underlying async generator

@item 
gh-111201@footnote{https://github.com/python/cpython/issues/111201}: The @ref{168,,interactive} interpreter is now implemented in
Python, which allows for a number of new features like colors, multiline
input, history viewing, and paste mode. Contributed by Pablo Galindo,
Łukasz Langa and Lysandros Nikolaou based on code from the PyPy project.

@item 
gh-74929@footnote{https://github.com/python/cpython/issues/74929}: Implement PEP 667: converted @ref{180,,FrameType.f_locals} and @ref{415,,PyFrame_GetLocals()} to return a
write-through proxy object when the frame refers to a function or
comprehension.

@item 
gh-116767@footnote{https://github.com/python/cpython/issues/116767}: Fix crash in compiler on 'async with' that has many context
managers.

@item 
gh-118335@footnote{https://github.com/python/cpython/issues/118335}: Change how to use the tier 2 interpreter. Instead of running
Python with @code{-X uops} or setting the environment variable
@code{PYTHON_UOPS=1}, this choice is now made at build time by configuring
with @code{--enable-experimental-jit=interpreter}.

`Beware!' This changes the environment variable to enable or disable
micro-ops to @code{PYTHON_JIT}. The old @code{PYTHON_UOPS} is no longer used.

@item 
gh-118306@footnote{https://github.com/python/cpython/issues/118306}: Update JIT compilation to use LLVM 18

@item 
gh-118160@footnote{https://github.com/python/cpython/issues/118160}: @ref{186,,Annotation scopes} within classes can
now contain comprehensions. However, such comprehensions are not inlined
into their parent scope at runtime. Patch by Jelle Zijlstra.

@item 
gh-118272@footnote{https://github.com/python/cpython/issues/118272}: Fix bug where @code{generator.close} does not free the generator
frame's locals.

@item 
gh-118216@footnote{https://github.com/python/cpython/issues/118216}: Don't consider @ref{0,,__future__} imports with dots before the
module name.

@item 
gh-118074@footnote{https://github.com/python/cpython/issues/118074}: Make sure that the Executor objects in the COLD_EXITS array
aren't assumed to be GC-able (which would access bytes outside the
object).

@item 
gh-107674@footnote{https://github.com/python/cpython/issues/107674}: Lazy load frame line number to improve performance of tracing

@item 
gh-118082@footnote{https://github.com/python/cpython/issues/118082}: Improve @ref{18b,,SyntaxError} message for imports without names,
like in @code{from x import} and @code{import} cases. It now points out to users
that @ref{5cc,,import} expects at least one name after it.

@item 
gh-118090@footnote{https://github.com/python/cpython/issues/118090}: Improve @ref{18b,,SyntaxError} message for empty type param
brackets.

@item 
gh-117958@footnote{https://github.com/python/cpython/issues/117958}: Added a @code{get_jit_code()} method to access JIT compiled
machine code from the UOp Executor when the experimental JIT is enabled.
Patch by Anthony Shaw.

@item 
gh-117901@footnote{https://github.com/python/cpython/issues/117901}: Add option for compiler's codegen to save nested instruction
sequences for introspection.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: Redirect stdout and stderr to system log when embedded in an
Android app.

@item 
gh-109118@footnote{https://github.com/python/cpython/issues/109118}: @ref{186,,annotation scope} within class scopes
can now contain lambdas.

@item 
gh-117894@footnote{https://github.com/python/cpython/issues/117894}: Prevent @code{agen.aclose()} objects being re-used after
@code{.throw()}.

@item 
gh-117881@footnote{https://github.com/python/cpython/issues/117881}: prevent concurrent access to an async generator via
athrow().throw() or asend().throw()

@item 
gh-117536@footnote{https://github.com/python/cpython/issues/117536}: Fix a @ref{1bb,,RuntimeWarning} when calling
@code{agen.aclose().throw(Exception)}.

@item 
gh-117755@footnote{https://github.com/python/cpython/issues/117755}: Fix mimalloc allocator for huge memory allocation (around
8,589,934,592 GiB) on s390x. Patch by Victor Stinner.

@item 
gh-117750@footnote{https://github.com/python/cpython/issues/117750}: Fix issue where an object's dict would get out of sync with the
object's internal values when being cleared. @code{obj.__dict__.clear()} now
clears the internal values, but leaves the dict attached to the object.

@item 
gh-117431@footnote{https://github.com/python/cpython/issues/117431}: Improve the performance of the following @ref{1bd,,bytes} and
@ref{528,,bytearray} methods by adapting them to the
@ref{15b0,,METH_FASTCALL} calling convention:


@itemize *

@item 
@code{count()}

@item 
@code{find()}

@item 
@code{index()}

@item 
@code{rfind()}

@item 
@code{rindex()}
@end itemize

@item 
gh-117709@footnote{https://github.com/python/cpython/issues/117709}: Speed up calls to @ref{435,,str()} with positional-only argument, by
using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} @code{vectorcall} calling convention. Patch by Erlend
Aasland.

@item 
gh-117680@footnote{https://github.com/python/cpython/issues/117680}: Give @code{_PyInstructionSequence} a Python interface and use it
in tests.

@item 
gh-115776@footnote{https://github.com/python/cpython/issues/115776}: Statically allocated objects are, by definition, immortal so
must be marked as such regardless of whether they are in extension modules
or not.

@item 
gh-117385@footnote{https://github.com/python/cpython/issues/117385}: Remove unhandled @code{PY_MONITORING_EVENT_BRANCH} and
@code{PY_MONITORING_EVENT_EXCEPTION_HANDLED} events from
@ref{14b6,,sys.settrace()}.

@item 
gh-116322@footnote{https://github.com/python/cpython/issues/116322}: Extension modules may indicate to the runtime that they can run
without the GIL. Multi-phase init modules do so by calling providing
@code{Py_MOD_GIL_NOT_USED} for the @code{Py_mod_gil} slot, while single-phase
init modules call @code{PyUnstable_Module_SetGIL(mod, Py_MOD_GIL_NOT_USED)}
from their init function.

@item 
gh-116129@footnote{https://github.com/python/cpython/issues/116129}: Implement 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}, adding support for defaults on type
parameters. Patch by Jelle Zijlstra.

@item 
gh-93502@footnote{https://github.com/python/cpython/issues/93502}: Add two new functions to the C-API,
@ref{362,,PyRefTracer_SetTracer()} and @ref{363,,PyRefTracer_GetTracer()}, that
allows to track object creation and destruction the same way the
@ref{fe,,tracemalloc} module does. Patch by Pablo Galindo

@item 
gh-107674@footnote{https://github.com/python/cpython/issues/107674}: Improved the performance of @ref{14b6,,sys.settrace()} significantly

@item 
gh-95754@footnote{https://github.com/python/cpython/issues/95754}: Improve the error message when a script shadowing a module from
the standard library causes @ref{343,,AttributeError} to be raised. Similarly,
improve the error message when a script shadowing a third party module
attempts to access an attribute from that third party module while still
initialising.

@item 
gh-99180@footnote{https://github.com/python/cpython/issues/99180}: Elide uninformative traceback indicators in @code{return} and
simple @code{assignment} statements. Patch by Pablo Galindo.

@item 
gh-105879@footnote{https://github.com/python/cpython/issues/105879}: Allow the `globals' and `locals' arguments to @ref{17d,,exec()} and
@ref{17e,,eval()} to be passed as keywords.
@end itemize

@node Library<9>,Documentation<5>,Core and Builtins<10>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id57}@anchor{15b1}
@subsubsection Library



@itemize -

@item 
gh-118418@footnote{https://github.com/python/cpython/issues/118418}: A @ref{1a3,,DeprecationWarning} is now emitted if you fail to pass
a value to the new `type_params' parameter of @code{typing._eval_type()} or
@code{typing.ForwardRef._evaluate()}. (Using either of these private and
undocumented functions is discouraged to begin with, but failing to pass a
value to the @code{type_params} parameter may lead to incorrect behaviour on
Python 3.12 or newer.)

@item 
gh-118660@footnote{https://github.com/python/cpython/issues/118660}: Add an optional second type parameter to
@ref{c7c,,typing.ContextManager} and @ref{15b2,,typing.AsyncContextManager},
representing the return types of @ref{12de,,__exit__()} and
@ref{15b3,,__aexit__()} respectively. This parameter defaults to @code{bool
| None}.

@item 
gh-118650@footnote{https://github.com/python/cpython/issues/118650}: The @code{enum} module allows method named @code{_repr_*} to be
defined on @code{Enum} types.

@item 
gh-118648@footnote{https://github.com/python/cpython/issues/118648}: Add type parameter defaults to @ref{15b4,,typing.Generator} and
@ref{15b5,,typing.AsyncGenerator}.

@item 
gh-101137@footnote{https://github.com/python/cpython/issues/101137}: Mime type @code{text/x-rst} is now supported by @ref{8e,,mimetypes}.

@item 
gh-118164@footnote{https://github.com/python/cpython/issues/118164}: The Python implementation of the @code{decimal} module could
appear to hang in relatively small power cases (like @code{2**117}) if
context precision was set to a very high value. A different method to
check for exactly representable results is used now that doesn't rely on
computing @code{10**precision} (which could be effectively too large to
compute).

@item 
gh-111744@footnote{https://github.com/python/cpython/issues/111744}: @code{breakpoint()} and @code{pdb.set_trace()} now enter the debugger
immediately after the call rather than before the next line is executed.

@item 
gh-118500@footnote{https://github.com/python/cpython/issues/118500}: Add @ref{a4,,pdb} support for zipapps

@item 
gh-118406@footnote{https://github.com/python/cpython/issues/118406}: Add signature for @ref{242,,sqlite3.Connection} objects.

@item 
gh-101732@footnote{https://github.com/python/cpython/issues/101732}: Use a Y2038 compatible openssl time function when available.

@item 
gh-118404@footnote{https://github.com/python/cpython/issues/118404}: Fix @ref{722,,inspect.signature()} for non-comparable callables.

@item 
gh-118402@footnote{https://github.com/python/cpython/issues/118402}: Fix @ref{722,,inspect.signature()} for the result of the
@ref{11b7,,functools.cmp_to_key()} call.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: On Android, @ref{1220,,sysconfig.get_platform} now returns the
format specified by 
@geindex Python Enhancement Proposals; PEP 738
PEP 738@footnote{https://peps.python.org/pep-0738/}.

@item 
gh-118285@footnote{https://github.com/python/cpython/issues/118285}: Allow to specify the signature of custom callable instances of
extension type by the @code{__text_signature__} attribute. Specify signatures
of @ref{e20,,operator.attrgetter}, @ref{a50,,operator.itemgetter}, and
@ref{e21,,operator.methodcaller} instances.

@item 
gh-118314@footnote{https://github.com/python/cpython/issues/118314}: Fix an edge case in @ref{15b6,,binascii.a2b_base64()} strict mode,
where excessive padding is not detected when no padding is necessary.

@item 
gh-118271@footnote{https://github.com/python/cpython/issues/118271}: Add the @code{PhotoImage} methods @code{read()} to read an
image from a file and @code{data()} to get the image data. Add
`background' and `grayscale' parameters to @code{PhotoImage} method
@code{write()}.

@item 
gh-118225@footnote{https://github.com/python/cpython/issues/118225}: Add the @code{PhotoImage} method @code{copy_replace()} to
copy a region from one image to other image, possibly with pixel zooming
and/or subsampling. Add `from_coords' parameter to @code{PhotoImage}
methods @code{copy()}, @code{zoom()} and @code{subsample()}. Add `zoom'
and `subsample' parameters to @code{PhotoImage} method @code{copy()}.

@item 
gh-118221@footnote{https://github.com/python/cpython/issues/118221}: Fix a bug where @ref{244,,sqlite3.Connection.iterdump()} could fail
if a custom @ref{15b7,,row factory} was used.
Patch by Erlend Aasland.

@item 
gh-118013@footnote{https://github.com/python/cpython/issues/118013}: Fix regression introduced in gh-103193@footnote{https://github.com/python/cpython/issues/103193} that meant that calling
@ref{47e,,inspect.getattr_static()} on an instance would cause a strong
reference to that instance's class to persist in an internal cache in the
@ref{7d,,inspect} module. This caused unexpected memory consumption if the
class was dynamically created, the class held strong references to other
objects which took up a significant amount of memory, and the cache
contained the sole strong reference to the class. The fix for the
regression leads to a slowdown in @code{getattr_static()}, but the
function should still be significantly faster than it was in Python 3.11.
Patch by Alex Waygood.

@item 
gh-118218@footnote{https://github.com/python/cpython/issues/118218}: Speed up @ref{7ff,,itertools.pairwise()} in the common case by up to
1.8x.

@item 
gh-117486@footnote{https://github.com/python/cpython/issues/117486}: Improve the behavior of user-defined subclasses of
@ref{1a4,,ast.AST}. Such classes will now require no changes in the usual
case to conform with the behavior changes of the @ref{8,,ast} module in
Python 3.13. Patch by Jelle Zijlstra.

@item 
gh-90848@footnote{https://github.com/python/cpython/issues/90848}: Fixed @ref{1590,,unittest.mock.create_autospec()} to configure parent
mock with keyword arguments.

@item 
gh-118168@footnote{https://github.com/python/cpython/issues/118168}: Fix incorrect argument substitution when @ref{15b8,,typing.Unpack}
is used with the builtin @ref{366,,tuple}. @code{typing.Unpack} now raises
@ref{522,,TypeError} when used with certain invalid types. Patch by Jelle
Zijlstra.

@item 
gh-118131@footnote{https://github.com/python/cpython/issues/118131}: Add command-line interface for the @ref{b7,,random} module. Patch
by Hugo van Kemenade.

@item 
gh-118107@footnote{https://github.com/python/cpython/issues/118107}: Fix @ref{131,,zipimport} reading of ZIP64 files with file entries
that are too big or offset too far.

@item 
gh-102511@footnote{https://github.com/python/cpython/issues/102511}: Fix @ref{12f8,,os.path.normpath()} for UNC paths on Windows. Speed up
@ref{48e,,os.path.splitroot()} with a native implementation.

@item 
gh-117535@footnote{https://github.com/python/cpython/issues/117535}: Change the unknown filename of @ref{111,,warnings} from @code{sys} to
@code{<sys>} to clarify that it's not a real filename.

@item 
gh-114053@footnote{https://github.com/python/cpython/issues/114053}: Fix erroneous @ref{428,,NameError} when calling
@ref{69c,,typing.get_type_hints()} on a class that made use of 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} type
parameters in a module that had @code{from __future__ import annotations} at
the top of the file. Patch by Alex Waygood.

@item 
gh-116931@footnote{https://github.com/python/cpython/issues/116931}: Add parameter `fileobj' check for
@ref{15b9,,tarfile.TarFile.addfile()}

@item 
gh-117995@footnote{https://github.com/python/cpython/issues/117995}: Don't raise @ref{1a3,,DeprecationWarning} when a @ref{4db,,sequence}
of parameters is used to bind indexed, nameless placeholders. See also
gh-100668@footnote{https://github.com/python/cpython/issues/100668}.

@item 
gh-80361@footnote{https://github.com/python/cpython/issues/80361}: Fix TypeError in @ref{11aa,,email.message.Message.get_payload()} when
the charset is 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} encoded.

@item 
gh-86650@footnote{https://github.com/python/cpython/issues/86650}: Fix IndexError when parse some emails with invalid Message-ID
(including one-off addresses generated by Microsoft Outlook).

@item 
gh-117691@footnote{https://github.com/python/cpython/issues/117691}: Improve the error messages emitted by @ref{dd,,tarfile}
deprecation warnings relating to PEP 706. If a @code{filter} argument is not
provided to @code{extract()} or @code{extractall}, the deprecation warning now
points to the line in the user's code where the relevant function was
called. Patch by Alex Waygood.

@item 
gh-115874@footnote{https://github.com/python/cpython/issues/115874}: Fixed a possible segfault during garbage collection of
@code{_asyncio.FutureIter} objects. Patch by Savannah Ostrowski.

@item 
gh-115060@footnote{https://github.com/python/cpython/issues/115060}: Speed up @ref{22a,,pathlib.Path.glob()} by omitting an initial
@ref{22d,,is_dir()} call. As a result of this change,
@ref{22a,,glob()} can no longer raise @ref{40d,,OSError}.

@item 
gh-77102@footnote{https://github.com/python/cpython/issues/77102}: @ref{c6,,site} module now parses @code{.pth} file with UTF-8 first,
and @ref{23f,,locale encoding} if @code{UnicodeDecodeError} happened. It
supported only locale encoding before.

@item 
gh-76785@footnote{https://github.com/python/cpython/issues/76785}: We've exposed the low-level @code{_interpreters} module for the
sake of the PyPI implementation of 
@geindex Python Enhancement Proposals; PEP 734
PEP 734@footnote{https://peps.python.org/pep-0734/}.  It was sometimes available
as the @code{_xxsubinterpreters} module and was formerly used only for
testing. For the most part, it should be considered an internal module,
like @code{_thread} and @code{_imp}. See
@indicateurl{https://discuss.python.org/t/pep-734-multiple-interpreters-in-the-stdlib/41147/26}.

@item 
gh-115060@footnote{https://github.com/python/cpython/issues/115060}: Speed up @ref{22a,,pathlib.Path.glob()} by not scanning directories
for non-wildcard pattern segments.

@item 
gh-117727@footnote{https://github.com/python/cpython/issues/117727}: Speed up @ref{15ba,,pathlib.Path.iterdir()} by using
@ref{a4d,,os.scandir()} internally.

@item 
gh-117586@footnote{https://github.com/python/cpython/issues/117586}: Speed up @ref{492,,pathlib.Path.walk()} by working with strings
internally.

@item 
gh-117722@footnote{https://github.com/python/cpython/issues/117722}: Change the new multi-separator support in
@ref{1b2,,asyncio.StreamReader.readuntil()} to only accept tuples of separators
rather than arbitrary iterables.

@item 
gh-117692@footnote{https://github.com/python/cpython/issues/117692}: Fixes a bug when @ref{15bb,,doctest.DocTestFinder} was failing on
wrapped @code{builtin_function_or_method}.

@item 
gh-117348@footnote{https://github.com/python/cpython/issues/117348}: Largely restored import time performance of configparser by
avoiding dataclasses.

@item 
gh-117641@footnote{https://github.com/python/cpython/issues/117641}: Speedup @ref{e2a,,os.path.commonpath()} on Unix.

@item 
gh-117663@footnote{https://github.com/python/cpython/issues/117663}: Fix @code{_simple_enum} to detect aliases when multiple arguments
are present but only one is the member value.

@item 
gh-117636@footnote{https://github.com/python/cpython/issues/117636}: Speedup @ref{15bc,,os.path.join()}.

@item 
gh-117618@footnote{https://github.com/python/cpython/issues/117618}: Support @code{package.module} as @code{filename} for @code{break}
command of @ref{a4,,pdb}

@item 
gh-102247@footnote{https://github.com/python/cpython/issues/102247}: the status codes enum with constants in http.HTTPStatus are
updated to include the names from RFC9110. This RFC includes some HTTP
statuses previously only used for WEBDAV and assigns more generic names to
them.

The old constants are preserved for backwards compatibility.

@item 
gh-117607@footnote{https://github.com/python/cpython/issues/117607}: Speedup @ref{494,,os.path.relpath()}.

@item 
gh-117586@footnote{https://github.com/python/cpython/issues/117586}: Speed up @ref{22a,,pathlib.Path.glob()} by working with strings
internally.

@item 
gh-117225@footnote{https://github.com/python/cpython/issues/117225}: Add colour to doctest output. Patch by Hugo van Kemenade.

@item 
gh-117566@footnote{https://github.com/python/cpython/issues/117566}: @ref{15bd,,ipaddress.IPv6Address.is_loopback()} will now return
@code{True} for IPv4-mapped loopback addresses, i.e. addresses in the
@code{::ffff:127.0.0.0/104} address space.

@item 
gh-117546@footnote{https://github.com/python/cpython/issues/117546}: Fix issue where @ref{222,,os.path.realpath()} stopped resolving
symlinks after encountering a symlink loop on POSIX.

@item 
gh-116720@footnote{https://github.com/python/cpython/issues/116720}: Improved behavior of @ref{1b3,,asyncio.TaskGroup} when an
external cancellation collides with an internal cancellation. For example,
when two task groups are nested and both experience an exception in a
child task simultaneously, it was possible that the outer task group would
misbehave, because its internal cancellation was swallowed by the inner
task group.

In the case where a task group is cancelled externally and also must raise
an @ref{1b4,,ExceptionGroup}, it will now call the parent task's
@ref{1b5,,cancel()} method. This ensures that a
@ref{1b6,,asyncio.CancelledError} will be raised at the next @ref{1b7,,await},
so the cancellation is not lost.

An added benefit of these changes is that task groups now preserve the
cancellation count (@ref{1b8,,asyncio.Task.cancelling()}).

In order to handle some corner cases, @ref{1b9,,asyncio.Task.uncancel()} may
now reset the undocumented @code{_must_cancel} flag when the cancellation
count reaches zero.

@item 
gh-117516@footnote{https://github.com/python/cpython/issues/117516}: Add @ref{162,,typing.TypeIs}, implementing 
@geindex Python Enhancement Proposals; PEP 742
PEP 742@footnote{https://peps.python.org/pep-0742/}. Patch by
Jelle Zijlstra.

@item 
gh-117503@footnote{https://github.com/python/cpython/issues/117503}: Fix support of non-ASCII user names in bytes paths in
@ref{a02,,os.path.expanduser()} on Posix.

@item 
gh-117394@footnote{https://github.com/python/cpython/issues/117394}: @ref{a00,,os.path.ismount()} is now 2-3 times faster if the user has
permissions.

@item 
gh-117313@footnote{https://github.com/python/cpython/issues/117313}: Only treat @code{'\n'}, @code{'\r'} and @code{'\r\n'} as line separators
in re-folding the @ref{3b,,email} messages. Preserve control characters
@code{'\v'}, @code{'\f'}, @code{'\x1c'}, @code{'\x1d'} and @code{'\x1e'} and Unicode line
separators @code{'\x85'}, @code{'\u2028'} and @code{'\u2029'} as is.

@item 
gh-117142@footnote{https://github.com/python/cpython/issues/117142}: Convert @code{_ctypes} to multi-phase initialisation
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
gh-66543@footnote{https://github.com/python/cpython/issues/66543}: Add the @ref{204,,mimetypes.guess_file_type()} function which works
with file path. Passing file path instead of URL in
@ref{205,,guess_type()} is @ref{206,,soft deprecated}.

@item 
gh-68583@footnote{https://github.com/python/cpython/issues/68583}: webbrowser CLI: replace getopt with argparse, add long options.
Patch by Hugo van Kemenade.

@item 
gh-116871@footnote{https://github.com/python/cpython/issues/116871}: Name suggestions for @ref{343,,AttributeError} and
@ref{40f,,ImportError} now only include underscored names if the original name
was underscored.

@item 
gh-116023@footnote{https://github.com/python/cpython/issues/116023}: Don't show empty fields (value @code{None} or @code{[]}) in
@ref{8d1,,ast.dump()} by default. Add @code{show_empty=False} parameter to
optionally show them.

@item 
gh-115961@footnote{https://github.com/python/cpython/issues/115961}: Added @code{name} and @code{mode} attributes for compressed
and archived file-like objects in modules @ref{13,,bz2}, @ref{89,,lzma},
@ref{dd,,tarfile} and @ref{130,,zipfile}. The value of the @code{mode}
attribute of @ref{410,,gzip.GzipFile} was changed from integer (@code{1} or
@code{2}) to string (@code{'rb'} or @code{'wb'}). The value of the @code{mode}
attribute of the readable file-like object returned by
@ref{411,,zipfile.ZipFile.open()} was changed from @code{'r'} to @code{'rb'}.

@item 
gh-82062@footnote{https://github.com/python/cpython/issues/82062}: Fix @ref{722,,inspect.signature()} to correctly handle parameter
defaults on methods in extension modules that use names defined in the
module namespace.

@item 
gh-83856@footnote{https://github.com/python/cpython/issues/83856}: Honor @ref{c,,atexit} for all @ref{93,,multiprocessing} start methods

@item 
gh-113081@footnote{https://github.com/python/cpython/issues/113081}: Print colorized exception just like built-in traceback in
@ref{a4,,pdb}

@item 
gh-112855@footnote{https://github.com/python/cpython/issues/112855}: Speed up pickling of @ref{490,,pathlib.PurePath} objects. Patch
by Barney Gale.

@item 
gh-111744@footnote{https://github.com/python/cpython/issues/111744}: Support opcode events in @ref{f,,bdb}

@item 
gh-109617@footnote{https://github.com/python/cpython/issues/109617}: @code{ncurses}: fixed a crash that could occur on macOS 13 or
earlier when Python was built with Apple Xcode 15's SDK.

@item 
gh-83151@footnote{https://github.com/python/cpython/issues/83151}: Enabled arbitrary statements and evaluations in @ref{a4,,pdb} shell
to access the local variables of the current frame, which made it possible
for multi-scope code like generators or nested function to work.

@item 
gh-110209@footnote{https://github.com/python/cpython/issues/110209}: Add @ref{725,,__class_getitem__()} to
@ref{15be,,types.GeneratorType} and @ref{e74,,types.CoroutineType} for type
hinting purposes. Patch by James Hilton-Balfe.

@item 
gh-108191@footnote{https://github.com/python/cpython/issues/108191}: The @ref{1cc,,types.SimpleNamespace} now accepts an optional
positional argument which specifies initial values of attributes as a dict
or an iterable of key-value pairs.

@item 
gh-62090@footnote{https://github.com/python/cpython/issues/62090}: Fix assertion errors caused by whitespace in metavars or
@code{SUPPRESS}-ed groups in @ref{6,,argparse} by simplifying usage formatting.
Patch by Ali Hamdan.

@item 
gh-102402@footnote{https://github.com/python/cpython/issues/102402}: Adjust @code{logging.LogRecord} to use @code{time.time_ns()} and fix
minor bug related to floating-point math.

@item 
gh-100242@footnote{https://github.com/python/cpython/issues/100242}: Bring pure Python implementation @code{functools.partial.__new__}
more in line with the C-implementation by not just always checking for the
presence of the attribute @code{'func'} on the first argument of @code{partial}.
Instead, both the Python version and the C version perform an
@code{isinstance(func, partial)} check on the first argument of @code{partial}.

@item 
gh-99730@footnote{https://github.com/python/cpython/issues/99730}: HEAD requests are no longer upgraded to GET request during
redirects in urllib.

@item 
gh-66410@footnote{https://github.com/python/cpython/issues/66410}: Setting the @code{tkinter} module global @code{wantobjects}
to @code{2} before creating the @ref{15bf,,Tk} object or call the
@code{wantobjects()} method of the @code{Tk} object with argument @code{2}
makes now arguments to callbacks registered in the @ref{ef,,tkinter} module
to be passed as various Python objects (@code{int}, @code{float}, @code{bytes},
@code{tuple}), depending on their internal representation in Tcl, instead of
always @code{str}. @code{tkinter.wantobjects} is now set to @code{2} by
default.

@item 
bpo-40943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40943}: Fix several IndexError when parse emails with truncated
Message-ID, address, routes, etc, e.g. @code{example@@}.

@item 
bpo-39324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39324}: Add mime type mapping for .md <-> text/markdown

@item 
bpo-18108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18108}: @ref{23d,,shutil.chown()} now supports `dir_fd' and
`follow_symlinks' keyword arguments.

@item 
bpo-30988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30988}: Fix parsing of emails with invalid address headers having a
leading or trailing dot. Patch by tsufeki.

@item 
bpo-32839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32839}: Add the @code{after_info()} method for Tkinter widgets.
@end itemize

@node Documentation<5>,Build<9>,Library<9>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id58}@anchor{15c0}
@subsubsection Documentation



@itemize -

@item 
gh-117928@footnote{https://github.com/python/cpython/issues/117928}: The minimum Sphinx version required for the documentation is
now 6.2.1.
@end itemize

@node Build<9>,Windows<6>,Documentation<5>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id59}@anchor{15c1}
@subsubsection Build



@itemize -

@item 
gh-118734@footnote{https://github.com/python/cpython/issues/118734}: Fixes Windows build when invoked directly (not through the
@code{build.bat} script) without specifying a value for @code{UseTIER2}.

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: The @code{configure} option @ref{408,,--with-system-libmpdec}
now defaults to @code{yes}. The bundled copy of @code{libmpdecimal} will be
removed in Python 3.15.

@item 
gh-117845@footnote{https://github.com/python/cpython/issues/117845}: Fix building against recent libedit versions by detecting
readline hook signatures in @code{configure}.

@item 
gh-116622@footnote{https://github.com/python/cpython/issues/116622}: A testbed project was added to run the test suite on Android.

@item 
gh-117645@footnote{https://github.com/python/cpython/issues/117645}: Increase WASI stack size from 512 KiB to 8 MiB and the initial
memory from 10 MiB to 20 MiB. Patch by Victor Stinner.

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: @code{configure} now uses @code{pkg-config} to detect
@ref{36,,decimal} dependencies if the @ref{408,,--with-system-libmpdec} option
is given.
@end itemize

@node Windows<6>,macOS<4>,Build<9>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id60}@anchor{15c2}
@subsubsection Windows



@itemize -

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: Update Windows installer to use libmpdecimal 4.0.0.

@item 
gh-118486@footnote{https://github.com/python/cpython/issues/118486}: @ref{21a,,os.mkdir()} now accepts `mode' of @code{0o700} to restrict
the new directory to the current user.

@item 
gh-118347@footnote{https://github.com/python/cpython/issues/118347}: Fixes launcher updates not being installed.

@item 
gh-118293@footnote{https://github.com/python/cpython/issues/118293}: The @code{multiprocessing} module now passes the
@code{STARTF_FORCEOFFFEEDBACK} flag when spawning processes to tell Windows
not to change the mouse cursor.

@item 
gh-115009@footnote{https://github.com/python/cpython/issues/115009}: Update Windows installer to use SQLite 3.45.3.

@item 
gh-90329@footnote{https://github.com/python/cpython/issues/90329}: Suppress the warning displayed on virtual environment creation
when the requested and created paths differ only by a short (8.3 style)
name. Warnings will continue to be shown if a junction or symlink in the
path caused the venv to be created in a different location than originally
requested.

@item 
gh-117786@footnote{https://github.com/python/cpython/issues/117786}: Fixes virtual environments not correctly launching when created
from a Store install.
@end itemize

@node macOS<4>,IDLE<8>,Windows<6>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id61}@anchor{15c3}
@subsubsection macOS



@itemize -

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: Update macOS installer to use libmpdecimal 4.0.0.

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: iOS preprocessor symbol usage was made compatible with older
macOS SDKs.

@item 
gh-115009@footnote{https://github.com/python/cpython/issues/115009}: Update macOS installer to use SQLite 3.45.3.

@item 
gh-91629@footnote{https://github.com/python/cpython/issues/91629}: Use @code{~/.config/fish/conf.d} configs and
@code{fish_add_path} to set 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} when installing for the
Fish shell.
@end itemize

@node IDLE<8>,C API<9>,macOS<4>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id62}@anchor{15c4}
@subsubsection IDLE



@itemize -

@item 
bpo-34774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34774}: Use user-selected color theme for Help => IDLE Doc.
@end itemize

@node C API<9>,,IDLE<8>,Python 3 13 0 beta 1
@anchor{whatsnew/changelog id63}@anchor{15c5}
@subsubsection C API



@itemize -

@item 
gh-118124@footnote{https://github.com/python/cpython/issues/118124}: Fix @code{Py_BUILD_ASSERT} and
@code{Py_BUILD_ASSERT_EXPR} for non-constant expressions: use
@code{static_assert()} on C11 and newer. Patch by Victor Stinner.

@item 
gh-110850@footnote{https://github.com/python/cpython/issues/110850}: Add "Raw" variant of PyTime functions


@itemize *

@item 
@ref{328,,PyTime_MonotonicRaw()}

@item 
@ref{32a,,PyTime_PerfCounterRaw()}

@item 
@ref{32c,,PyTime_TimeRaw()}
@end itemize

Patch by Victor Stinner.

@item 
gh-117987@footnote{https://github.com/python/cpython/issues/117987}: Restore functions removed in Python 3.13 alpha 1:


@itemize *

@item 
@ref{15c6,,Py_SetPythonHome()}

@item 
@ref{15c7,,Py_SetProgramName()}

@item 
@ref{15c8,,PySys_SetArgvEx()}

@item 
@ref{15c9,,PySys_SetArgv()}
@end itemize

Patch by Victor Stinner.

@item 
gh-117929@footnote{https://github.com/python/cpython/issues/117929}: Restore removed @ref{15ca,,PyEval_InitThreads()} function. Patch by
Victor Stinner.

@item 
gh-117534@footnote{https://github.com/python/cpython/issues/117534}: Improve validation logic in the C implementation of
@ref{602,,datetime.datetime.fromisoformat()} to better handle invalid years.
Patch by Vlad Efanov.

@item 
gh-68114@footnote{https://github.com/python/cpython/issues/68114}: Fixed skipitem()'s handling of the old 'w' and 'w#' formatters.
These are no longer supported and now raise an exception if used.

@item 
gh-111997@footnote{https://github.com/python/cpython/issues/111997}: Add a C-API for firing monitoring events.
@end itemize

@node Python 3 13 0 alpha 6,Python 3 13 0 alpha 5,Python 3 13 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-13-0-alpha-6}@anchor{15cb}
@subsection Python 3.13.0 alpha 6


`Release date: 2024-04-09'

@menu
* Core and Builtins: Core and Builtins<11>. 
* Library: Library<10>. 
* Documentation: Documentation<6>. 
* Tests: Tests<8>. 
* Build: Build<10>. 
* Windows: Windows<7>. 
* C API: C API<10>. 

@end menu

@node Core and Builtins<11>,Library<10>,,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id64}@anchor{15cc}
@subsubsection Core and Builtins



@itemize -

@item 
gh-117494@footnote{https://github.com/python/cpython/issues/117494}: Refactored the instruction sequence data structure out of
compile.c into instruction_sequence.c.

@item 
gh-116968@footnote{https://github.com/python/cpython/issues/116968}: Introduce a unified 16-bit backoff counter type
(@code{_Py_BackoffCounter}), shared between the Tier 1 adaptive specializer
and the Tier 2 optimizer. The API used for adaptive specialization
counters is changed but the behavior is (supposed to be) identical.

The behavior of the Tier 2 counters is changed:


@itemize *

@item 
There are no longer dynamic thresholds (we never varied these).

@item 
All counters now use the same exponential backoff.

@item 
The counter for @code{JUMP_BACKWARD} starts counting down from 16.

@item 
The @code{temperature} in side exits starts counting down from 64.
@end itemize

@item 
gh-117431@footnote{https://github.com/python/cpython/issues/117431}: Improve the performance of the following @ref{1bd,,bytes} and
@ref{528,,bytearray} methods by adapting them to the
@ref{15b0,,METH_FASTCALL} calling convention:


@itemize *

@item 
@code{endswith()}

@item 
@code{startswith()}
@end itemize

@item 
gh-117431@footnote{https://github.com/python/cpython/issues/117431}: Improve the performance of the following @ref{435,,str} methods
by adapting them to the @ref{15b0,,METH_FASTCALL} calling convention:


@itemize *

@item 
@ref{15cd,,count()}

@item 
@ref{eb5,,endswith()}

@item 
@ref{e91,,find()}

@item 
@ref{15ce,,index()}

@item 
@ref{e92,,rfind()}

@item 
@ref{1236,,rindex()}

@item 
@ref{eb4,,startswith()}
@end itemize

@item 
gh-117411@footnote{https://github.com/python/cpython/issues/117411}: Move @code{PyFutureFeatures} to an internal header and make it
private.

@item 
gh-109120@footnote{https://github.com/python/cpython/issues/109120}: Added handle of incorrect star expressions, e.g @code{f(3, *)}.
Patch by Grigoryev Semyon

@item 
gh-117266@footnote{https://github.com/python/cpython/issues/117266}: Fix crashes for certain user-created subclasses of
@ref{1a4,,ast.AST}. Such classes are now expected to set the
@code{_field_types} attribute.

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Updated the @ref{67,,hashlib} built-in HACL* project@footnote{https://github.com/hacl-star/hacl-star} C code
from upstream that we use for many implementations when they are not
present via OpenSSL in a given build.  This also avoids the rare potential
for a C symbol name one definition rule linking issue.

@item 
gh-117108@footnote{https://github.com/python/cpython/issues/117108}: Change the old space bit of objects in the young generation
from 0 to gcstate->visited, so that any objects created during GC will
have the old bit set correctly if they get moved into the old generation.

@item 
gh-117108@footnote{https://github.com/python/cpython/issues/117108}: The cycle GC now chooses the size of increments based on the
total heap size, instead of the rate of object creation. This ensures that
it can keep up with growing heaps.

@item 
gh-116735@footnote{https://github.com/python/cpython/issues/116735}: For @code{INSTRUMENTED_CALL_FUNCTION_EX}, set @code{arg0} to
@code{sys.monitoring.MISSING} instead of @code{None} for
@ref{15cf,,CALL} event.

@item 
gh-113964@footnote{https://github.com/python/cpython/issues/113964}: Starting new threads and process creation through
@ref{195,,os.fork()} are now only prevented once all non-daemon threads exit.

@item 
gh-116626@footnote{https://github.com/python/cpython/issues/116626}: Ensure @code{INSTRUMENTED_CALL_FUNCTION_EX} always emits
@ref{15cf,,CALL}

@item 
gh-116554@footnote{https://github.com/python/cpython/issues/116554}: @code{list.sort()} now exploits more cases of partial ordering,
particularly those with long descending runs with sub-runs of equal
values. Those are recognized as single runs now (previously, each block of
repeated values caused a new run to be created).

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: Added a Loader that can discover extension modules in an
iOS-style Frameworks folder.

@item 
gh-115775@footnote{https://github.com/python/cpython/issues/115775}: Compiler populates the new @code{__static_attributes__} field on a
class with the names of attributes of this class which are accessed
through self.X from any function in its body.

@item 
gh-115776@footnote{https://github.com/python/cpython/issues/115776}: The array of values, the @code{PyDictValues} struct is now
embedded in the object during allocation. This provides better performance
in the common case, and does not degrade as much when the object's
@code{__dict__} is materialized.

@item 
gh-108362@footnote{https://github.com/python/cpython/issues/108362}: Implement an incremental cyclic garbage collector. By
collecting the old generation in increments, there is no need for a full
heap scan. This can hugely reduce maximum pause time for programs with
large heaps.

Reduce the number of generations from three to two. The old generation is
split into two spaces, "visited" and "pending".

Collection happens in two steps:: * An increment is formed from the young
generation and a small part of the pending space. * This increment is
scanned and the survivors moved to the end of the visited space.

When the collecting space becomes empty, the two spaces are swapped.

@item 
gh-109870@footnote{https://github.com/python/cpython/issues/109870}: Dataclasses now calls @ref{17d,,exec()} once per dataclass, instead
of once per method being added.  This can speed up dataclass creation by
up to 20%.

@item 
gh-97901@footnote{https://github.com/python/cpython/issues/97901}: Mime type @code{text/rtf} is now supported by @ref{8e,,mimetypes}.

@item 
bpo-24612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24612}: Improve the @ref{18b,,SyntaxError} that happens when 'not' appears
after an operator. Patch by Pablo Galindo
@end itemize

@node Library<10>,Documentation<6>,Core and Builtins<11>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id65}@anchor{15d0}
@subsubsection Library



@itemize -

@item 
gh-117648@footnote{https://github.com/python/cpython/issues/117648}: Improve performance of @ref{15bc,,os.path.join()} and
@ref{a02,,os.path.expanduser()}.

@item 
gh-117584@footnote{https://github.com/python/cpython/issues/117584}: Raise @ref{522,,TypeError} for non-paths in
@code{posixpath.relpath()}.

@item 
gh-117467@footnote{https://github.com/python/cpython/issues/117467}: Preserve mailbox ownership when rewriting in
@code{mailbox.mbox.flush()}. Patch by Tony Mountifield.

@item 
gh-114848@footnote{https://github.com/python/cpython/issues/114848}: Raise @ref{eae,,FileNotFoundError} when @code{getcwd()} returns
'(unreachable)', which can happen on Linux >= 2.6.36 with glibc < 2.27.

@item 
gh-117459@footnote{https://github.com/python/cpython/issues/117459}: @code{asyncio.asyncio.run_coroutine_threadsafe()} now keeps the
traceback of @code{CancelledError}, @ref{81f,,TimeoutError} and
@code{InvalidStateError} which are raised in the coroutine.

@item 
gh-117381@footnote{https://github.com/python/cpython/issues/117381}: Fix error message for @code{ntpath.commonpath()}.

@item 
gh-117337@footnote{https://github.com/python/cpython/issues/117337}: Deprecate undocumented @code{glob.glob0()} and
@code{glob.glob1()} functions. Use @ref{29c,,glob.glob()} and pass a directory
to its `root_dir' argument instead.

@item 
gh-117349@footnote{https://github.com/python/cpython/issues/117349}: Optimise several functions in @ref{a1,,os.path}.

@item 
gh-117348@footnote{https://github.com/python/cpython/issues/117348}: Refactored @code{configparser.RawConfigParser._read()} to reduce
cyclometric complexity and improve comprehensibility.

@item 
gh-117335@footnote{https://github.com/python/cpython/issues/117335}: Raise TypeError for non-sequences for
@code{ntpath.commonpath()}.

@item 
gh-66449@footnote{https://github.com/python/cpython/issues/66449}: @ref{1c3,,configparser.ConfigParser} now accepts unnamed sections
before named ones, if configured to do so.

@item 
gh-88014@footnote{https://github.com/python/cpython/issues/88014}: In documentation of @ref{410,,gzip.GzipFile} in module gzip,
explain data type of optional constructor argument `mtime', and recommend
@code{mtime = 0} for generating deterministic streams.

@item 
gh-117310@footnote{https://github.com/python/cpython/issues/117310}: Fixed an unlikely early & extra @code{Py_DECREF} triggered crash
in @ref{cf,,ssl} when creating a new @code{_ssl._SSLContext} if CPython was
built implausibly such that the default cipher list is empty `or' the
SSL library it was linked against reports a failure from its C
@code{SSL_CTX_set_cipher_list()} API.

@item 
gh-117294@footnote{https://github.com/python/cpython/issues/117294}: A @code{DocTestCase} now reports as skipped if all examples in the
doctest are skipped.

@item 
gh-98966@footnote{https://github.com/python/cpython/issues/98966}: In @ref{d5,,subprocess}, raise a more informative message when
@code{stdout=STDOUT}.

@item 
gh-117225@footnote{https://github.com/python/cpython/issues/117225}: doctest: only print "and X failed" when non-zero, don't
pluralise "1 items". Patch by Hugo van Kemenade.

@item 
gh-117205@footnote{https://github.com/python/cpython/issues/117205}: Speed up @ref{b14,,compileall.compile_dir()} by 20% when using
multiprocessing by increasing @code{chunksize}.

@item 
gh-117178@footnote{https://github.com/python/cpython/issues/117178}: Fix regression in lazy loading of self-referential modules,
introduced in gh-114781@footnote{https://github.com/python/cpython/issues/114781}.

@item 
gh-112383@footnote{https://github.com/python/cpython/issues/112383}: Fix @ref{38,,dis} module's handling of @code{ENTER_EXECUTOR}
instructions.

@item 
gh-117182@footnote{https://github.com/python/cpython/issues/117182}: Lazy-loading of modules that modify their own @code{__class__} no
longer reverts the @code{__class__} to @ref{e00,,types.ModuleType}.

@item 
gh-117084@footnote{https://github.com/python/cpython/issues/117084}: Fix @ref{130,,zipfile} extraction for directory entries with the
name containing backslashes on Windows.

@item 
gh-117114@footnote{https://github.com/python/cpython/issues/117114}: Make @ref{15d1,,os.path.isdevdrive()} available on all platforms. For
those that do not offer Dev Drives, it will always return @code{False}.

@item 
gh-117110@footnote{https://github.com/python/cpython/issues/117110}: Fix a bug that prevents subclasses of @ref{697,,typing.Any} to be
instantiated with arguments. Patch by Chris Fu.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Deferred select imports in importlib.metadata and
importlib.resources for a 14% speedup.

@item 
gh-70647@footnote{https://github.com/python/cpython/issues/70647}: Start the deprecation period for the current behavior of
@ref{1593,,datetime.datetime.strptime()} and @ref{13e3,,time.strptime()} which always
fails to parse a date string with a @ref{1ff,,ValueError} involving a day of
month such as @code{strptime("02-29", "%m-%d")} when a year is `not'
specified and the date happen to be February 29th.  This should help avoid
users finding new bugs every four years due to a natural mistaken
assumption about the API when parsing partial date values.

@item 
gh-116987@footnote{https://github.com/python/cpython/issues/116987}: Fixed @code{inspect.findsource()} for class code objects.

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: Modify standard library to allow for iOS platform differences.

@item 
gh-90872@footnote{https://github.com/python/cpython/issues/90872}: On Windows, @ref{cd2,,subprocess.Popen.wait()} no longer calls
@code{WaitForSingleObject()} with a negative timeout: pass @code{0} ms if the
timeout is negative. Patch by Victor Stinner.

@item 
gh-116957@footnote{https://github.com/python/cpython/issues/116957}: configparser: Don't leave ConfigParser values in an invalid
state (stored as a list instead of a str) after an earlier read raised
DuplicateSectionError or DuplicateOptionError.

@item 
gh-115538@footnote{https://github.com/python/cpython/issues/115538}: @code{_io.WindowsConsoleIO} now emit a warning if a boolean
value is passed as a filedescriptor argument.

@item 
gh-90095@footnote{https://github.com/python/cpython/issues/90095}: Ignore empty lines and comments in @code{.pdbrc}

@item 
gh-106531@footnote{https://github.com/python/cpython/issues/106531}: Refreshed zipfile._path from zipp 3.18@footnote{https://zipp.readthedocs.io/en/latest/history.html#v3-18-0}, providing
better compatibility for PyPy, better glob performance for deeply nested
zipfiles, and providing internal access to @code{CompleteDirs.inject} for use
in other tests (like importlib.resources).

@item 
gh-63207@footnote{https://github.com/python/cpython/issues/63207}: On Windows, @ref{251,,time.time()} now uses the
@code{GetSystemTimePreciseAsFileTime()} clock to have a resolution better
than 1 us, instead of the @code{GetSystemTimeAsFileTime()} clock which has a
resolution of 15.6 ms. Patch by Victor Stinner.

@item 
gh-116764@footnote{https://github.com/python/cpython/issues/116764}: Restore support of @code{None} and other false values in
@ref{109,,urllib.parse} functions @ref{277,,parse_qs()} and
@ref{276,,parse_qsl()}. Also, they now raise a TypeError for
non-zero integers and non-empty sequences.

@item 
gh-116811@footnote{https://github.com/python/cpython/issues/116811}: In @code{PathFinder.invalidate_caches}, delegate to
@code{MetadataPathFinder.invalidate_caches}.

@item 
gh-116647@footnote{https://github.com/python/cpython/issues/116647}: Fix recursive child in dataclasses

@item 
gh-113171@footnote{https://github.com/python/cpython/issues/113171}: Fixed various false positives and false negatives in


@itemize *

@item 
@ref{15d2,,ipaddress.IPv4Address.is_private} (see these docs for details)

@item 
@ref{f4a,,ipaddress.IPv4Address.is_global}

@item 
@ref{15d3,,ipaddress.IPv6Address.is_private}

@item 
@ref{15d4,,ipaddress.IPv6Address.is_global}
@end itemize

Also in the corresponding @ref{1fb,,ipaddress.IPv4Network} and
@ref{1fc,,ipaddress.IPv6Network} attributes.

@item 
gh-63283@footnote{https://github.com/python/cpython/issues/63283}: In @ref{51,,encodings.idna}, any capitalization of the ACE prefix
(@code{xn--}) is now acceptable. Patch by Pepijn de Vos and Zackery Spytz.

@item 
gh-71042@footnote{https://github.com/python/cpython/issues/71042}: Add @ref{15d5,,platform.android_ver()}, which provides device and OS
information on Android.

@item 
gh-73468@footnote{https://github.com/python/cpython/issues/73468}: Added new @ref{202,,math.fma()} function, wrapping C99's @code{fma()}
operation: fused multiply-add function. Patch by Mark Dickinson and Victor
Stinner.

@item 
gh-116608@footnote{https://github.com/python/cpython/issues/116608}: The @ref{7a,,importlib.resources} functions
@ref{1e9,,is_resource()},
@ref{1ea,,open_binary()},
@ref{1eb,,open_text()}, @ref{1ec,,path()},
@ref{1ed,,read_binary()}, and
@ref{1ee,,read_text()} are un-deprecated, and support
subdirectories via multiple positional arguments. The
@ref{1ef,,contents()} function also allows subdirectories,
but remains deprecated.

@item 
gh-116484@footnote{https://github.com/python/cpython/issues/116484}: Change automatically generated @code{tkinter.Checkbutton}
widget names to avoid collisions with automatically generated
@code{tkinter.ttk.Checkbutton} widget names within the same parent
widget.

@item 
gh-114314@footnote{https://github.com/python/cpython/issues/114314}: In @ref{2a,,ctypes}, ctype data is now stored in type objects
directly rather than in a dict subclass. This is an internal change that
should not affect usage.

@item 
gh-116401@footnote{https://github.com/python/cpython/issues/116401}: Fix blocking @ref{b49,,os.fwalk()} and @ref{2f5,,shutil.rmtree()} on
opening named pipe.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Implement @ref{d37,,ctypes.util.find_library()} on Android.

@item 
gh-90535@footnote{https://github.com/python/cpython/issues/90535}: Fix support of `interval' values > 1 in
@code{logging.TimedRotatingFileHandler} for @code{when='MIDNIGHT'} and
@code{when='Wx'}.

@item 
gh-113308@footnote{https://github.com/python/cpython/issues/113308}: Remove some internal protected parts from @ref{10f,,uuid}:
@code{_has_uuid_generate_time_safe}, @code{_netbios_getnode},
@code{_ipconfig_getnode}, and @code{_load_system_functions}. They were unused.

@item 
gh-115627@footnote{https://github.com/python/cpython/issues/115627}: Fix the @ref{cf,,ssl} module error handling of connection
terminate by peer. It now throws an OSError with the appropriate error
code instead of an EOFError.

@item 
gh-114847@footnote{https://github.com/python/cpython/issues/114847}: Speed up @ref{222,,os.path.realpath()} on non-Windows platforms.

@item 
gh-114271@footnote{https://github.com/python/cpython/issues/114271}: Fix a race in @code{threading.Thread.join()}.

@code{threading._MainThread} now always represents the main thread of the
main interpreter.

@code{PyThreadState.on_delete} and @code{PyThreadState.on_delete_data} have been
removed.

@item 
gh-113538@footnote{https://github.com/python/cpython/issues/113538}: Add @ref{1b0,,asyncio.Server.close_clients()} and
@ref{1b1,,asyncio.Server.abort_clients()} methods which allow to more
forcefully close an asyncio server.

@item 
gh-85287@footnote{https://github.com/python/cpython/issues/85287}: Changes Unicode codecs to return UnicodeEncodeError or
UnicodeDecodeError, rather than just UnicodeError.

@item 
gh-113548@footnote{https://github.com/python/cpython/issues/113548}: @ref{a4,,pdb} now allows CLI arguments to @code{pdb -m}.

@item 
gh-112948@footnote{https://github.com/python/cpython/issues/112948}: Make completion of @ref{a4,,pdb} similar to Python REPL

@item 
gh-105866@footnote{https://github.com/python/cpython/issues/105866}: Fixed @code{_get_slots} bug which caused error when defining
dataclasses with slots and a weakref_slot.

@item 
gh-96471@footnote{https://github.com/python/cpython/issues/96471}: Add @ref{a64,,asyncio.Queue} termination with
@ref{1ae,,shutdown()} method.

@item 
gh-89739@footnote{https://github.com/python/cpython/issues/89739}: The @ref{131,,zipimport} module can now read ZIP64 files.

@item 
bpo-33533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33533}: @ref{1a8,,asyncio.as_completed()} now returns an object that is both
an asynchronous iterator and plain iterator. The new asynchronous
iteration pattern allows for easier correlation between prior tasks and
their completed results. This is a closer match to
@ref{15d6,,concurrent.futures.as_completed()}'s iteration pattern. Patch by
Justin Arthur.

@item 
bpo-27578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27578}: @ref{154d,,inspect.getsource()} (and related functions) work with
empty module files, returning @code{'\n'} (or reasonable equivalent) instead
of raising @code{OSError}. Patch by Kernc.

@item 
bpo-37141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37141}: Accept an iterable of separators in
@ref{1b2,,asyncio.StreamReader.readuntil()}, stopping when one of them is
encountered.

@item 
gh-66543@footnote{https://github.com/python/cpython/issues/66543}: Make @ref{205,,mimetypes.guess_type()} properly parsing of URLs with
only a host name, URLs containing fragment or query, and filenames with
only a UNC sharepoint on Windows. Based on patch by Dong-hee Na.

@item 
bpo-15010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15010}: @ref{fd0,,unittest.TestLoader.discover()} now saves the original
value of @code{unittest.TestLoader._top_level_dir} and restores it at the end
of the call.
@end itemize

@node Documentation<6>,Tests<8>,Library<10>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id66}@anchor{15d7}
@subsubsection Documentation



@itemize -

@item 
gh-115977@footnote{https://github.com/python/cpython/issues/115977}: Remove compatibility references to Emscripten.

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: Add an iOS platform guide, and flag modules not available on
iOS.

@item 
gh-91565@footnote{https://github.com/python/cpython/issues/91565}: Changes to documentation files and config outputs to reflect the
new location for reporting bugs - i.e. GitHub rather than bugs.python.org.
@end itemize

@node Tests<8>,Build<10>,Documentation<6>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id67}@anchor{15d8}
@subsubsection Tests



@itemize -

@item 
gh-83434@footnote{https://github.com/python/cpython/issues/83434}: Disable JUnit XML output (@code{--junit-xml=FILE} command line
option) in regrtest when hunting for reference leaks (@code{-R} option).
Patch by Victor Stinner.

@item 
gh-117187@footnote{https://github.com/python/cpython/issues/117187}: Fix XML tests for vanilla Expat <2.6.0.

@item 
gh-116333@footnote{https://github.com/python/cpython/issues/116333}: Tests of TLS related things (error codes, etc) were updated to
be more lenient about specific error message strings and behaviors as seen
in the BoringSSL and AWS-LC forks of OpenSSL.

@item 
gh-117089@footnote{https://github.com/python/cpython/issues/117089}: Consolidated tests for importlib.metadata in their own
@code{metadata} package.

@item 
gh-115979@footnote{https://github.com/python/cpython/issues/115979}: Update test_importlib so that it passes under WASI SDK 21.

@item 
gh-112536@footnote{https://github.com/python/cpython/issues/112536}: Add --tsan to test.regrtest for running TSAN tests in
reasonable execution times. Patch by Donghee Na.

@item 
gh-116307@footnote{https://github.com/python/cpython/issues/116307}: Added import helper @code{isolated_modules} as @code{CleanImport}
does not remove modules imported during the context. Use it in
importlib.resources tests to avoid leaving @code{mod} around to impede
importlib.metadata tests.
@end itemize

@node Build<10>,Windows<7>,Tests<8>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id68}@anchor{15d9}
@subsubsection Build



@itemize -

@item 
gh-114736@footnote{https://github.com/python/cpython/issues/114736}: Have WASI builds use WASI SDK 21.

@item 
gh-115983@footnote{https://github.com/python/cpython/issues/115983}: Skip building test modules that must be built as shared under
WASI.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Add Android build script and instructions.
@end itemize

@node Windows<7>,C API<10>,Build<10>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id69}@anchor{15da}
@subsubsection Windows



@itemize -

@item 
gh-117267@footnote{https://github.com/python/cpython/issues/117267}: Ensure @code{DirEntry.stat().st_ctime} behaves consistently with
@ref{48a,,os.stat()} during the deprecation period of @code{st_ctime} by
containing the same value as @code{st_birthtime}. After the deprecation
period, @code{st_ctime} will be the metadata change time (or unavailable
through @code{DirEntry}), and only @code{st_birthtime} will contain the creation
time.

@item 
gh-116195@footnote{https://github.com/python/cpython/issues/116195}: Improves performance of @ref{15db,,os.getppid()} by using an
alternate system API when available. Contributed by vxiiduu.

@item 
gh-88494@footnote{https://github.com/python/cpython/issues/88494}: On Windows, @ref{250,,time.monotonic()} now uses the
@code{QueryPerformanceCounter()} clock to have a resolution better than 1 us,
instead of the @code{GetTickCount64()} clock which has a resolution of 15.6
ms. Patch by Victor Stinner.

@item 
gh-116773@footnote{https://github.com/python/cpython/issues/116773}: Fix instances of @code{<_overlapped.Overlapped object at 0xXXX>
still has pending operation at deallocation, the process may crash}.

@item 
gh-91227@footnote{https://github.com/python/cpython/issues/91227}: Fix the asyncio ProactorEventLoop implementation so that sending
a datagram to an address that is not listening does not prevent receiving
any more datagrams.

@item 
gh-115119@footnote{https://github.com/python/cpython/issues/115119}: Switched from vendored @code{libmpdecimal} code to a
separately-hosted external package in the @code{cpython-source-deps}
repository when building the @code{_decimal} module.
@end itemize

@node C API<10>,,Windows<7>,Python 3 13 0 alpha 6
@anchor{whatsnew/changelog id70}@anchor{15dc}
@subsubsection C API



@itemize -

@item 
gh-117642@footnote{https://github.com/python/cpython/issues/117642}: Fix 
@geindex Python Enhancement Proposals; PEP 737
PEP 737@footnote{https://peps.python.org/pep-0737/} implementation for @code{%#T} and @code{%#N}.

@item 
gh-87193@footnote{https://github.com/python/cpython/issues/87193}: @ref{15dd,,_PyBytes_Resize()} can now be called for bytes objects
with reference count > 1, including 1-byte bytes objects. It creates a new
bytes object and destroys the old one if it has reference count > 1.

@item 
gh-117021@footnote{https://github.com/python/cpython/issues/117021}: Fix integer overflow in @code{PyLong_AsPid()} on non-Windows
64-bit platforms.

@item 
gh-115756@footnote{https://github.com/python/cpython/issues/115756}: @code{PyCode_GetFirstFree()} is an ustable API now and has
been renamed to @ref{37c,,PyUnstable_Code_GetFirstFree()}. (Contributed by
Bogdan Romanyuk in gh-115781@footnote{https://github.com/python/cpython/issues/115781})

@item 
gh-116869@footnote{https://github.com/python/cpython/issues/116869}: Add @code{test_cext} test: build a C extension to check if the
Python C API emits C compiler warnings. Patch by Victor Stinner.

@item 
gh-116869@footnote{https://github.com/python/cpython/issues/116869}: Make the C API compatible with
@code{-Werror=declaration-after-statement} compiler flag again. Patch by
Victor Stinner.

@item 
gh-116936@footnote{https://github.com/python/cpython/issues/116936}: Add @ref{38a,,PyType_GetModuleByDef()} to the limited C API. Patch
by Victor Stinner.

@item 
gh-116809@footnote{https://github.com/python/cpython/issues/116809}: Restore removed private @code{_PyErr_ChainExceptions1()} function.
Patch by Victor Stinner.

@item 
gh-115754@footnote{https://github.com/python/cpython/issues/115754}: In the limited C API version 3.13, getting @code{Py_None},
@code{Py_False}, @code{Py_True}, @code{Py_Ellipsis} and @code{Py_NotImplemented}
singletons is now implemented as function calls at the stable ABI level to
hide implementation details. Getting these constants still return borrowed
references. Patch by Victor Stinner.

@item 
gh-115754@footnote{https://github.com/python/cpython/issues/115754}: Add @ref{34c,,Py_GetConstant()} and
@ref{34d,,Py_GetConstantBorrowed()} functions to get constants. For example,
@code{Py_GetConstant(Py_CONSTANT_ZERO)} returns a @ref{333,,strong reference} to
the constant zero. Patch by Victor Stinner.

@item 
gh-111696@footnote{https://github.com/python/cpython/issues/111696}: Add support for @code{%T}, @code{%T#}, @code{%N} and @code{%N#} formats to
@ref{380,,PyUnicode_FromFormat()}: format the fully qualified name of an
object type and of a type: call @ref{36b,,PyType_GetModuleName()}. See
@geindex Python Enhancement Proposals; PEP 737
PEP 737@footnote{https://peps.python.org/pep-0737/} for more information. Patch by Victor Stinner.

@item 
gh-111696@footnote{https://github.com/python/cpython/issues/111696}: Add @ref{36b,,PyType_GetModuleName()} function to get the type's
module name. Equivalent to getting the @code{type.__module__} attribute.
Patch by Eric Snow and Victor Stinner.

@item 
gh-111696@footnote{https://github.com/python/cpython/issues/111696}: Add @ref{369,,PyType_GetFullyQualifiedName()} function to get the
type's fully qualified name. Equivalent to
@code{f"@{type.__module__@}.@{type.__qualname__@}"}, or @code{type.__qualname__} if
@code{type.__module__} is not a string or is equal to @code{"builtins"}. Patch
by Victor Stinner.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: The @code{fcntl}, @code{grp}, @code{pwd}, @code{termios}, @code{_statistics}
and @code{_testconsole} C extensions are now built with the @ref{38c,,limited C API}. Patch by Victor Stinner.

@item 
gh-111140@footnote{https://github.com/python/cpython/issues/111140}: Add additional flags to @ref{357,,PyLong_AsNativeBytes()} and
@ref{358,,PyLong_FromNativeBytes()} to allow the caller to determine how to
handle edge cases around values that fill the entire buffer.

@item 
gh-113024@footnote{https://github.com/python/cpython/issues/113024}: Add @ref{35d,,PyObject_GenericHash()} function.
@end itemize

@node Python 3 13 0 alpha 5,Python 3 13 0 alpha 4,Python 3 13 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-13-0-alpha-5}@anchor{15de}
@subsection Python 3.13.0 alpha 5


`Release date: 2024-03-12'

@menu
* Security: Security<7>. 
* Core and Builtins: Core and Builtins<12>. 
* Library: Library<11>. 
* Documentation: Documentation<7>. 
* Tests: Tests<9>. 
* Build: Build<11>. 
* Windows: Windows<8>. 
* macOS: macOS<5>. 
* IDLE: IDLE<9>. 
* Tools/Demos: Tools/Demos<4>. 
* C API: C API<11>. 

@end menu

@node Security<7>,Core and Builtins<12>,,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id71}@anchor{15df}
@subsubsection Security



@itemize -

@item 
gh-115398@footnote{https://github.com/python/cpython/issues/115398}: Allow controlling Expat >=2.6.0 reparse deferral
(
@geindex Common Vulnerabilities and Exposures; CVE 2023-52425
CVE 2023-52425@footnote{https://www.cve.org/CVERecord?id=CVE-2023-52425}) by adding five new methods:


@itemize *

@item 
@ref{26c,,xml.etree.ElementTree.XMLParser.flush()}

@item 
@ref{26d,,xml.etree.ElementTree.XMLPullParser.flush()}

@item 
@ref{26e,,xml.parsers.expat.xmlparser.GetReparseDeferralEnabled()}

@item 
@ref{26f,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()}

@item 
@code{xml.sax.expatreader.ExpatParser.flush()}
@end itemize

@item 
gh-114572@footnote{https://github.com/python/cpython/issues/114572}: @ref{f96,,ssl.SSLContext.cert_store_stats()} and
@ref{f97,,ssl.SSLContext.get_ca_certs()} now correctly lock access to the
certificate store, when the @ref{291,,ssl.SSLContext} is shared across
multiple threads.
@end itemize

@node Core and Builtins<12>,Library<11>,Security<7>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id72}@anchor{15e0}
@subsubsection Core and Builtins



@itemize -

@item 
gh-116604@footnote{https://github.com/python/cpython/issues/116604}: Respect the status of the garbage collector when indirect calls
are made via @ref{450,,PyErr_CheckSignals()} and the evaluation breaker.
Patch by Pablo Galindo

@item 
gh-112087@footnote{https://github.com/python/cpython/issues/112087}: @ref{5fc,,list} is now compatible with the implementation of
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}.

@item 
gh-116381@footnote{https://github.com/python/cpython/issues/116381}: Add specialization for @code{CONTAINS_OP}.

@item 
gh-116296@footnote{https://github.com/python/cpython/issues/116296}: Fix possible refleak in @code{object.__reduce__()} internal
error handling.

@item 
gh-115823@footnote{https://github.com/python/cpython/issues/115823}: Properly calculate error ranges in the parser when raising
@ref{18b,,SyntaxError} exceptions caused by invalid byte sequences. Patch by
Pablo Galindo

@item 
gh-115778@footnote{https://github.com/python/cpython/issues/115778}: Add @code{tierN} annotation for instruction definition in
interpreter DSL.

@item 
gh-115733@footnote{https://github.com/python/cpython/issues/115733}: Fix crash when calling @code{next()} on exhausted list iterators.

@item 
gh-115700@footnote{https://github.com/python/cpython/issues/115700}: The regen-cases build stage now works on Windows.

@item 
gh-115347@footnote{https://github.com/python/cpython/issues/115347}: Fix bug where docstring was replaced by a redundant NOP when
Python is run with @code{-OO}.

@item 
gh-115323@footnote{https://github.com/python/cpython/issues/115323}: Make error message more meaningful for when
@code{bytearray.extend()} is called with a @ref{435,,str} object.

@item 
gh-112175@footnote{https://github.com/python/cpython/issues/112175}: Every @code{PyThreadState} now has its own @code{eval_breaker},
allowing specific threads to be interrupted.

@item 
gh-115154@footnote{https://github.com/python/cpython/issues/115154}: Fix a bug that was causing the @ref{1547,,tokenize.untokenize()}
function to handle unicode named literals incorrectly. Patch by Pablo
Galindo

@item 
gh-112433@footnote{https://github.com/python/cpython/issues/112433}: Add ability to force alignment of @ref{1cf,,ctypes.Structure} by
way of the new @code{_align_} attribute on the class.

@item 
gh-104090@footnote{https://github.com/python/cpython/issues/104090}: The multiprocessing resource tracker now exits with non-zero
status code if a resource leak was detected. It still exits with status
code 0 otherwise.

@item 
gh-105858@footnote{https://github.com/python/cpython/issues/105858}: Improve the constructors for @ref{8,,ast} nodes. Arguments of
list types now default to an empty list if omitted, and optional fields
default to @code{None}. AST nodes now have an @code{__annotations__} attribute
with the expected types of their attributes. Passing unrecognized extra
arguments to AST nodes is deprecated and will become an error in Python
3.15. Omitting a required argument to an AST node is deprecated and will
become an error in Python 3.15. Patch by Jelle Zijlstra.

@item 
gh-101860@footnote{https://github.com/python/cpython/issues/101860}: Expose @code{__name__} attribute on property.

@item 
gh-96497@footnote{https://github.com/python/cpython/issues/96497}: Fix incorrect resolution of mangled class variables used in
assignment expressions in comprehensions.
@end itemize

@node Library<11>,Documentation<7>,Core and Builtins<12>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id73}@anchor{15e1}
@subsubsection Library



@itemize -

@item 
gh-116600@footnote{https://github.com/python/cpython/issues/116600}: Fix @ref{7e7,,repr()} for global @ref{60e,,Flag} members.

@item 
gh-116349@footnote{https://github.com/python/cpython/issues/116349}: @ref{2a4,,platform.java_ver()} is deprecated and will be removed in
3.15. It was largely untested, had a confusing API, and was only useful
for Jython support.

@item 
gh-116143@footnote{https://github.com/python/cpython/issues/116143}: Fix a race in pydoc @code{_start_server}, eliminating a window in
which @code{_start_server} can return a thread that is "serving" but without
a @code{docserver} set.

@item 
gh-116127@footnote{https://github.com/python/cpython/issues/116127}: @ref{103,,typing}: implement 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/} which adds
@ref{160,,typing.ReadOnly} support to @ref{161,,typing.TypedDict}.

@item 
gh-116325@footnote{https://github.com/python/cpython/issues/116325}: @ref{103,,typing}: raise @ref{18b,,SyntaxError} instead of
@ref{343,,AttributeError} on forward references as empty strings.

@item 
gh-115957@footnote{https://github.com/python/cpython/issues/115957}: When @code{asyncio.TaskGroup.create_task} is called on an inactive
@code{asyncio.TaskGroup}, the given coroutine will be closed (which prevents
a @code{RuntimeWarning}).

@item 
gh-115978@footnote{https://github.com/python/cpython/issues/115978}: Disable preadv(), readv(), pwritev(), and writev() on WASI.

Under wasmtime for WASI 0.2, these functions don't pass test_posix
(@indicateurl{https://github.com/bytecodealliance/wasmtime/issues/7830}).

@item 
gh-88352@footnote{https://github.com/python/cpython/issues/88352}: Fix the computation of the next rollover time in the
@code{logging.TimedRotatingFileHandler} handler.
@code{computeRollover()} now always returns a timestamp larger than the
specified time and works correctly during the DST change.
@code{doRollover()} no longer overwrite the already rolled over file,
saving from data loss when run at midnight or during repeated time at the
DST change.

@item 
gh-87115@footnote{https://github.com/python/cpython/issues/87115}: Set @code{__main__.__spec__} to @code{None} when running a script with
@ref{a4,,pdb}

@item 
gh-76511@footnote{https://github.com/python/cpython/issues/76511}: Fix UnicodeEncodeError in @code{email.Message.as_string()} that
results when a message that claims to be in the ascii character set
actually has non-ascii characters. Non-ascii characters are now replaced
with the U+FFFD replacement character, like in the @code{replace} error
handler.

@item 
gh-89547@footnote{https://github.com/python/cpython/issues/89547}: Add support for nested typing special forms like
Final[ClassVar[int]].

@item 
gh-65824@footnote{https://github.com/python/cpython/issues/65824}: Improve the @code{less} prompt in @ref{b4,,pydoc}.

@item 
gh-116040@footnote{https://github.com/python/cpython/issues/116040}: [Enum] fix by-value calls when second value is falsey; e.g.
Cardinal(1, 0)

@item 
gh-115821@footnote{https://github.com/python/cpython/issues/115821}: [Enum] Improve error message when calling super().__new__() in
custom __new__.

@item 
gh-85644@footnote{https://github.com/python/cpython/issues/85644}: Use the @code{XDG_CURRENT_DESKTOP} environment variable in
@ref{114,,webbrowser} to check desktop. Prefer it to the deprecated
@code{GNOME_DESKTOP_SESSION_ID} for GNOME detection.

@item 
gh-75988@footnote{https://github.com/python/cpython/issues/75988}: Fixed @ref{1590,,unittest.mock.create_autospec()} to pass the call
through to the wrapped object to return the real result.

@item 
gh-115881@footnote{https://github.com/python/cpython/issues/115881}: Fix issue where @ref{1a6,,ast.parse()} would incorrectly flag
conditional context managers (such as @code{with (x() if y else z()): ...})
as invalid syntax if @code{feature_version=(3, 8)} was passed. This reverts
changes to the grammar made as part of gh-94949@footnote{https://github.com/python/cpython/issues/94949}.

@item 
gh-115886@footnote{https://github.com/python/cpython/issues/115886}: Fix silent truncation of the name with an embedded null
character in @ref{15e2,,multiprocessing.shared_memory.SharedMemory}.

@item 
gh-115532@footnote{https://github.com/python/cpython/issues/115532}: Add kernel density estimation to the statistics module.

@item 
gh-115714@footnote{https://github.com/python/cpython/issues/115714}: On WASI, the @ref{ed,,time} module no longer get process time
using @code{times()} or @code{CLOCK_PROCESS_CPUTIME_ID}, system API is that is
unreliable and is likely to be removed from WASI. The affected clock
functions fall back to calling @code{clock()}.

@item 
gh-115809@footnote{https://github.com/python/cpython/issues/115809}: Improve algorithm for computing which rolled-over log files to
delete in @code{logging.TimedRotatingFileHandler}. It is now reliable
for handlers without @code{namer} and with arbitrary deterministic @code{namer}
that leaves the datetime part in the file name unmodified.

@item 
gh-74668@footnote{https://github.com/python/cpython/issues/74668}: @ref{109,,urllib.parse} functions @ref{277,,parse_qs()} and
@ref{276,,parse_qsl()} now support bytes arguments containing raw
and percent-encoded non-ASCII data.

@item 
gh-67044@footnote{https://github.com/python/cpython/issues/67044}: @ref{471,,csv.writer()} now always quotes or escapes @code{'\r'} and
@code{'\n'}, regardless of `lineterminator' value.

@item 
gh-115712@footnote{https://github.com/python/cpython/issues/115712}: Restore support of space delimiter with
@code{skipinitialspace=True} in @ref{29,,csv}. @ref{471,,csv.writer()} now quotes
empty fields if delimiter is a space and skipinitialspace is true and
raises exception if quoting is not possible.

@item 
gh-112364@footnote{https://github.com/python/cpython/issues/112364}: Fixed @ref{8d2,,ast.unparse()} to handle format_spec with @code{"},
@code{'} or @code{\\}. Patched by Frank Hoffmann.

@item 
gh-112997@footnote{https://github.com/python/cpython/issues/112997}: Stop logging potentially sensitive callback arguments in
@ref{a,,asyncio} unless debug mode is active.

@item 
gh-114914@footnote{https://github.com/python/cpython/issues/114914}: Fix an issue where an abandoned @code{StreamWriter} would not
be garbage collected.

@item 
gh-111358@footnote{https://github.com/python/cpython/issues/111358}: Fix a bug in
@code{asyncio.BaseEventLoop.shutdown_default_executor()} to ensure the
timeout passed to the coroutine behaves as expected.

@item 
gh-115618@footnote{https://github.com/python/cpython/issues/115618}: Fix improper decreasing the reference count for @code{None}
argument in @ref{192,,property} methods @ref{15e3,,getter()},
@ref{15e4,,setter()} and @ref{15e5,,deleter()}.

@item 
gh-112720@footnote{https://github.com/python/cpython/issues/112720}: Refactor @code{dis.ArgResolver} to make it possible to
subclass and change the way jump args are interpreted.

@item 
gh-112006@footnote{https://github.com/python/cpython/issues/112006}: Fix @ref{f47,,inspect.unwrap()} for types with the @code{__wrapper__}
data descriptor. Fix @ref{724,,inspect.Signature.from_callable()} for builtins
@ref{165,,classmethod()} and @ref{40c,,staticmethod()}.

@item 
gh-101293@footnote{https://github.com/python/cpython/issues/101293}: Support callables with the @code{__call__()} method and types with
@code{__new__()} and @code{__init__()} methods set to class methods, static
methods, bound methods, partial functions, and other types of methods and
descriptors in @ref{724,,inspect.Signature.from_callable()}.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Isolate @code{_lsprof} (apply 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}).

@item 
gh-113942@footnote{https://github.com/python/cpython/issues/113942}: @ref{b4,,pydoc} no longer skips global functions implemented as
builtin methods, such as @code{MethodDescriptorType} and
@code{WrapperDescriptorType}.

@item 
gh-115256@footnote{https://github.com/python/cpython/issues/115256}: Added DeprecationWarning when accessing the tarfile attribute
of TarInfo objects. The attribute is never used internally and is only
attached to TarInfos when the tarfile is opened in write-mode, not
read-mode. The attribute creates an unnecessary reference cycle which may
cause corruption when not closing the handle after writing a tarfile.

@item 
gh-115197@footnote{https://github.com/python/cpython/issues/115197}: @code{urllib.request} no longer resolves the hostname before
checking it against the system's proxy bypass list on macOS and Windows.

@item 
gh-113812@footnote{https://github.com/python/cpython/issues/113812}: @code{DatagramTransport.sendto()} will now send zero-length
datagrams if called with an empty bytes object. The transport flow control
also now accounts for the datagram header when calculating the buffer
size.

@item 
gh-114763@footnote{https://github.com/python/cpython/issues/114763}: Protect modules loaded with @ref{c9b,,importlib.util.LazyLoader}
from race conditions when multiple threads try to access attributes before
the loading is complete.

@item 
gh-114709@footnote{https://github.com/python/cpython/issues/114709}: @code{posixpath.commonpath()} now raises a @ref{1ff,,ValueError}
exception when passed an empty iterable. Previously, @ref{14eb,,IndexError} was
raised.

@code{posixpath.commonpath()} now raises a @ref{522,,TypeError} exception when
passed @code{None}. Previously, @ref{1ff,,ValueError} was raised.

@item 
gh-114610@footnote{https://github.com/python/cpython/issues/114610}: Fix bug where @ref{15e6,,pathlib.PurePath.with_stem()} converted a
non-empty path suffix to a stem when given an empty `stem' argument. It
now raises @ref{1ff,,ValueError}, just like
@ref{15a0,,pathlib.PurePath.with_suffix()} does when called on a path with an
empty stem, given a non-empty `suffix' argument.

@item 
gh-107361@footnote{https://github.com/python/cpython/issues/107361}: Add @ref{155,,ssl.VERIFY_X509_PARTIAL_CHAIN} and
@code{VERIFY_X509_STRICT} to the default SSL context created with
@ref{154,,ssl.create_default_context()}.

@item 
gh-112281@footnote{https://github.com/python/cpython/issues/112281}: Allow creating @ref{7ac,,union of types} for
@ref{92a,,typing.Annotated} with unhashable metadata.

@item 
gh-111775@footnote{https://github.com/python/cpython/issues/111775}: Fix @code{importlib.resources.simple.ResourceHandle.open()} for
text mode, added missed @code{stream} argument.

@item 
gh-90095@footnote{https://github.com/python/cpython/issues/90095}: Make .pdbrc and -c work with any valid pdb commands.

@item 
gh-107625@footnote{https://github.com/python/cpython/issues/107625}: Raise @ref{4ee,,configparser.ParsingError} from
@ref{141c,,read()} and
@ref{4ef,,read_file()} methods of
@ref{1c3,,configparser.ConfigParser} if a key without a corresponding value
is continued (that is, followed by an indented line).

@item 
gh-107155@footnote{https://github.com/python/cpython/issues/107155}: Fix incorrect output of @code{help(x)} where @code{x} is a
@ref{127a,,lambda} function, which has an @code{__annotations__} dictionary
attribute with a @code{"return"} key.

@item 
gh-57141@footnote{https://github.com/python/cpython/issues/57141}: Add option for `non-shallow' comparisons to
@ref{f2b,,filecmp.dircmp} like @ref{15e7,,filecmp.cmp()}. Original patch by Steven
Ward. Enhanced by Tobias Rautenkranz

@item 
gh-69990@footnote{https://github.com/python/cpython/issues/69990}: @code{Profile.print_stats()} has been improved to accept multiple
sort arguments. Patched by Chiu-Hsiang Hsu and Furkan Onder.

@item 
gh-104061@footnote{https://github.com/python/cpython/issues/104061}: Add @code{socket.SO_BINDTOIFINDEX} constant.

@item 
gh-60346@footnote{https://github.com/python/cpython/issues/60346}: Fix ArgumentParser inconsistent with parse_known_args.

@item 
gh-102389@footnote{https://github.com/python/cpython/issues/102389}: Add @code{windows_31j} to aliases for @code{cp932} codec

@item 
gh-72249@footnote{https://github.com/python/cpython/issues/72249}: @code{functools.partial`s of :func:`repr()} has been improved to
include the @ref{15e8,,module} name. Patched by Furkan Onder and Anilyka
Barry.

@item 
gh-100985@footnote{https://github.com/python/cpython/issues/100985}: Update HTTPSConnection to consistently wrap IPv6 Addresses when
using a proxy.

@item 
gh-100884@footnote{https://github.com/python/cpython/issues/100884}: email: fix misfolding of comma in address-lists over multiple
lines in combination with unicode encoding.

@item 
gh-95782@footnote{https://github.com/python/cpython/issues/95782}: Fix @code{io.BufferedReader.tell()},
@code{io.BufferedReader.seek()}, @code{_pyio.BufferedReader.tell()},
@code{io.BufferedRandom.tell()}, @code{io.BufferedRandom.seek()} and
@code{_pyio.BufferedRandom.tell()} being able to return negative offsets.

@item 
gh-96310@footnote{https://github.com/python/cpython/issues/96310}: Fix a traceback in @ref{6,,argparse} when all options in a
mutually exclusive group are suppressed.

@item 
gh-93205@footnote{https://github.com/python/cpython/issues/93205}: Fixed a bug in
@ref{f4c,,logging.handlers.TimedRotatingFileHandler} where multiple rotating
handler instances pointing to files with the same name but different
extensions would conflict and not delete the correct files.

@item 
bpo-31116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31116}: Add Z85 encoding to @code{base64}.

@item 
bpo-44865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44865}: Add missing call to localization function in @ref{6,,argparse}.

@item 
bpo-43952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43952}: Fix @ref{15e9,,multiprocessing.connection.Listener.accept()} to
accept empty bytes as authkey. Not accepting empty bytes as key causes it
to hang indefinitely.

@item 
bpo-42125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42125}: linecache: get module name from @code{__spec__} if available. This
allows getting source code for the @code{__main__} module when a custom
loader is used.

@item 
bpo-41122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41122}: Failing to pass arguments properly to
@ref{9de,,functools.singledispatchmethod()} now throws a TypeError instead of
hitting an index out of bounds internally.

@item 
bpo-40818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40818}: The asyncio REPL now runs @ref{fb2,,sys.__interactivehook__} on
startup. The default implementation of @ref{fb2,,sys.__interactivehook__}
provides auto-completion to the asyncio REPL. Patch contributed by Rémi
Lapeyre.

@item 
bpo-33775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33775}: Add 'default' and 'version' help text for localization in
argparse.
@end itemize

@node Documentation<7>,Tests<9>,Library<11>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id74}@anchor{15ea}
@subsubsection Documentation



@itemize -

@item 
gh-115399@footnote{https://github.com/python/cpython/issues/115399}: Document 
@geindex Common Vulnerabilities and Exposures; CVE 2023-52425
CVE 2023-52425@footnote{https://www.cve.org/CVERecord?id=CVE-2023-52425} of Expat <2.6.0 under "XML
vulnerabilities".

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Improve import time of @ref{10f,,uuid} on Linux.
@end itemize

@node Tests<9>,Build<11>,Documentation<7>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id75}@anchor{15eb}
@subsubsection Tests



@itemize -

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Add test exclusions to support running the test suite on
Android.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Enable @code{test_concurrent_futures} on platforms that support
threading but not multiprocessing.

@item 
gh-115796@footnote{https://github.com/python/cpython/issues/115796}: Make '_testinternalcapi.assemble_code_object' construct the
exception table for the code object.

@item 
gh-115720@footnote{https://github.com/python/cpython/issues/115720}: Leak tests (@code{-R}, @code{--huntrleaks}) now show a summary of the
number of leaks found in each iteration.

@item 
gh-115122@footnote{https://github.com/python/cpython/issues/115122}: Add @code{--bisect} option to regrtest test runner: run failed
tests with @code{test.bisect_cmd} to identify failing tests. Patch by Victor
Stinner.

@item 
gh-115596@footnote{https://github.com/python/cpython/issues/115596}: Fix @code{ProgramPriorityTests} in @code{test_os} permanently
changing the process priority.

@item 
gh-115556@footnote{https://github.com/python/cpython/issues/115556}: On Windows, commas passed in arguments to
@code{Tools\buildbot\test.bat} and @code{PCbuild\\rt.bat} are now properly
handled.

@item 
gh-115420@footnote{https://github.com/python/cpython/issues/115420}: Fix translation of exception handler targets by
@code{_testinternalcapi.optimize_cfg}.

@item 
gh-115376@footnote{https://github.com/python/cpython/issues/115376}: Fix segfault in @code{_testinternalcapi.compiler_codegen} on bad
input.
@end itemize

@node Build<11>,Windows<8>,Tests<9>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id76}@anchor{15ec}
@subsubsection Build



@itemize -

@item 
gh-116313@footnote{https://github.com/python/cpython/issues/116313}: Get WASI builds to work under wasmtime 18 w/ WASI 0.2/preview2
primitives.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Change Android's @ref{a7b,,sys.platform} from @code{"linux"} to
@code{"android"}.

@item 
gh-116117@footnote{https://github.com/python/cpython/issues/116117}: Backport @code{libb2}'s PR #42 to fix compiling CPython on 32-bit
Windows with @code{clang-cl}.

@item 
gh-71052@footnote{https://github.com/python/cpython/issues/71052}: Fix several Android build issues

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: A testbed project was added to run the test suite on iOS.

@item 
gh-115350@footnote{https://github.com/python/cpython/issues/115350}: Fix building ctypes module with -DWIN32_LEAN_AND_MEAN defined

@item 
gh-111225@footnote{https://github.com/python/cpython/issues/111225}: Link extension modules against libpython on Android.

@item 
gh-115737@footnote{https://github.com/python/cpython/issues/115737}: The install name for libPython is now correctly set for
non-framework macOS builds.

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: Makefile targets were added to support compiling an
iOS-compatible framework build.
@end itemize

@node Windows<8>,macOS<5>,Build<11>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id77}@anchor{15ed}
@subsubsection Windows



@itemize -

@item 
gh-116012@footnote{https://github.com/python/cpython/issues/116012}: Ensure the value of @code{GetLastError()} is preserved across GIL
operations.

@item 
gh-115582@footnote{https://github.com/python/cpython/issues/115582}: Building extensions intended for free-threaded builds of
CPython now require compiling with @code{/DPy_GIL_DISABLED} manually when
using a regular install. This is expected to change in future releases.

@item 
gh-115554@footnote{https://github.com/python/cpython/issues/115554}: The installer now has more strict rules about updating the
@ref{5a8,,Lanceur Python pour Windows}. In general, most users only have a single launcher
installed and will see no difference. When multiple launchers have been
installed, the option to install the launcher is disabled until all but
one have been removed. Downgrading the launcher (which was never allowed)
is now more obviously blocked.

@item 
gh-115543@footnote{https://github.com/python/cpython/issues/115543}: @ref{5a8,,Lanceur Python pour Windows} can now detect Python 3.13 when installed from
the Microsoft Store, and will install Python 3.12 by default when
@geindex PYLAUNCHER_ALLOW_INSTALL
@geindex variable d'environnement; PYLAUNCHER_ALLOW_INSTALL
@code{PYLAUNCHER_ALLOW_INSTALL} is set.
@end itemize

@node macOS<5>,IDLE<9>,Windows<8>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id78}@anchor{15ee}
@subsubsection macOS



@itemize -

@item 
gh-116145@footnote{https://github.com/python/cpython/issues/116145}: Update macOS installer to Tcl/Tk 8.6.14.
@end itemize

@node IDLE<9>,Tools/Demos<4>,macOS<5>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id79}@anchor{15ef}
@subsubsection IDLE



@itemize -

@item 
gh-88516@footnote{https://github.com/python/cpython/issues/88516}: On macOS show a proxy icon in the title bar of editor windows to
match platform behaviour.
@end itemize

@node Tools/Demos<4>,C API<11>,IDLE<9>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id80}@anchor{15f0}
@subsubsection Tools/Demos



@itemize -

@item 
gh-100176@footnote{https://github.com/python/cpython/issues/100176}: Remove outdated Tools/@{io,cc,string@}bench

@item 
bpo-45101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45101}: Add consistency in usage message IO between 2 versions of
python-config.
@end itemize

@node C API<11>,,Tools/Demos<4>,Python 3 13 0 alpha 5
@anchor{whatsnew/changelog id81}@anchor{15f1}
@subsubsection C API



@itemize -

@item 
gh-114626@footnote{https://github.com/python/cpython/issues/114626}: Add again @code{_PyCFunctionFastWithKeywords} name, removed in
Python 3.13 alpha 4 by mistake.  Keep the old private
@code{_PyCFunctionFastWithKeywords} name (Python 3.7) as an alias to the new
public name @code{PyCFunctionFastWithKeywords} (Python 3.13a4). Patch by
Victor Stinner.

@item 
gh-111418@footnote{https://github.com/python/cpython/issues/111418}: Add @ref{15f2,,PyHASH_MODULUS}, @ref{15f3,,PyHASH_BITS},
@ref{15f4,,PyHASH_INF} and @ref{15f5,,PyHASH_IMAG} C macros.  Patch by
Sergey B Kirpichev.
@end itemize

@node Python 3 13 0 alpha 4,Python 3 13 0 alpha 3,Python 3 13 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-13-0-alpha-4}@anchor{15f6}
@subsection Python 3.13.0 alpha 4


`Release date: 2024-02-15'

@menu
* Security: Security<8>. 
* Core and Builtins: Core and Builtins<13>. 
* Library: Library<12>. 
* Documentation: Documentation<8>. 
* Tests: Tests<10>. 
* Build: Build<12>. 
* Windows: Windows<9>. 
* macOS: macOS<6>. 
* IDLE: IDLE<10>. 
* Tools/Demos: Tools/Demos<5>. 
* C API: C API<12>. 

@end menu

@node Security<8>,Core and Builtins<13>,,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id82}@anchor{15f7}
@subsubsection Security



@itemize -

@item 
gh-115399@footnote{https://github.com/python/cpython/issues/115399}: Update bundled libexpat to 2.6.0

@item 
gh-115243@footnote{https://github.com/python/cpython/issues/115243}: Fix possible crashes in @ref{dbf,,collections.deque.index()} when
the deque is concurrently modified.
@end itemize

@node Core and Builtins<13>,Library<12>,Security<8>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id83}@anchor{15f8}
@subsubsection Core and Builtins



@itemize -

@item 
gh-112087@footnote{https://github.com/python/cpython/issues/112087}: For an empty reverse iterator for list will be reduced to
@ref{850,,reversed()}. Patch by Donghee Na

@item 
gh-114570@footnote{https://github.com/python/cpython/issues/114570}: Add @ref{14c,,PythonFinalizationError} exception. This exception
derived from @ref{193,,RuntimeError} is raised when an operation is blocked
during the @ref{14d,,Python finalization}. Patch by
Victor Stinner.

@item 
gh-114695@footnote{https://github.com/python/cpython/issues/114695}: Add @ref{15f9,,sys._clear_internal_caches()}, which clears all
internal performance-related caches (and deprecate the less-general
@ref{15fa,,sys._clear_type_cache()} function).

@item 
gh-114828@footnote{https://github.com/python/cpython/issues/114828}: Fix compilation crashes in uncommon code examples using
@ref{4c5,,super()} inside a comprehension in a class body.

@item 
gh-112069@footnote{https://github.com/python/cpython/issues/112069}: Adapt @ref{5c3,,set} and @ref{5c4,,frozenset} methods to Argument
Clinic.

@item 
gh-115011@footnote{https://github.com/python/cpython/issues/115011}: Setters for members with an unsigned integer type now support
the same range of valid values for objects that has a
@ref{707,,__index__()} method as for @ref{254,,int}.

@item 
gh-114887@footnote{https://github.com/python/cpython/issues/114887}: Changed socket type validation in
@ref{71d,,create_datagram_endpoint()} to accept all non-stream
sockets. This fixes a regression in compatibility with raw sockets.

@item 
gh-114944@footnote{https://github.com/python/cpython/issues/114944}: Fixes a race between @code{PyParkingLot_Park} and
@code{_PyParkingLot_UnparkAll}.

@item 
gh-113462@footnote{https://github.com/python/cpython/issues/113462}: Limit the number of versions that a single class can use.
Prevents a few wayward classes using up all the version numbers.

@item 
gh-76763@footnote{https://github.com/python/cpython/issues/76763}: The @ref{15fb,,chr()} builtin function now always raises
@ref{1ff,,ValueError} for values outside the valid range. Previously it raised
@ref{86d,,OverflowError} for very large or small values.

@item 
gh-114806@footnote{https://github.com/python/cpython/issues/114806}: No longer specialize calls to classes, if those classes have
metaclasses. Fixes bug where the @code{__call__} method of the metaclass was
not being called.

@item 
gh-107944@footnote{https://github.com/python/cpython/issues/107944}: Improve error message for function calls with bad keyword
arguments via getargs

@item 
gh-112529@footnote{https://github.com/python/cpython/issues/112529}: The free-threaded build no longer allocates space for the
@code{PyGC_Head} structure in objects that support cyclic garbage collection.
A number of other fields and data structures are used as replacements,
including @code{ob_gc_bits}, @code{ob_tid}, and mimalloc internal data
structures.

@item 
gh-114456@footnote{https://github.com/python/cpython/issues/114456}: Lower the recursion limit under a debug build of WASI.

@item 
gh-114083@footnote{https://github.com/python/cpython/issues/114083}: Compiler applies folding of LOAD_CONST with following
instruction in a separate pass before other optimisations. This enables
jump threading in certain circumstances.

@item 
gh-114388@footnote{https://github.com/python/cpython/issues/114388}: Fix a @ref{1bb,,RuntimeWarning} emitted when assign an integer-like
value that is not an instance of @ref{254,,int} to an attribute that
corresponds to a C struct member of @ref{15fc,,type} T_UINT
and T_ULONG. Fix a double @ref{1bb,,RuntimeWarning} emitted when assign a
negative integer value to an attribute that corresponds to a C struct
member of type T_UINT.

@item 
gh-114265@footnote{https://github.com/python/cpython/issues/114265}: Compiler propagates line numbers before optimization, leading
to more optimization opportunities and removing the need for the
@code{guarantee_lineno_for_exits} hack.

@item 
gh-112529@footnote{https://github.com/python/cpython/issues/112529}: The free-threaded build now has its own thread-safe GC
implementation that uses mimalloc to find GC tracked objects. It is
non-generational, unlike the existing GC implementation.

@item 
gh-114050@footnote{https://github.com/python/cpython/issues/114050}: Fix segmentation fault caused by an incorrect format string in
@code{TypeError} exception when more than two arguments are passed to
@code{int}.

@item 
gh-112354@footnote{https://github.com/python/cpython/issues/112354}: The @code{END_FOR} instruction now pops only one value. This is to
better support side exits in loops.

@item 
gh-113884@footnote{https://github.com/python/cpython/issues/113884}: Make @ref{b58,,queue.SimpleQueue} thread safe when the GIL is
disabled.

@item 
gh-114058@footnote{https://github.com/python/cpython/issues/114058}: Implement the foundations of the Tier 2 redundancy eliminator.

@item 
gh-113939@footnote{https://github.com/python/cpython/issues/113939}: frame.clear(): Clear frame.f_locals as well, and not only the
fast locals. This is relevant once frame.f_locals was accessed, which
would contain also references to all the locals.

@item 
gh-112050@footnote{https://github.com/python/cpython/issues/112050}: Convert @ref{5c6,,collections.deque} to use Argument Clinic.

@item 
gh-112050@footnote{https://github.com/python/cpython/issues/112050}: Make methods on @ref{5c6,,collections.deque} thread-safe when the
GIL is disabled.

@item 
gh-113464@footnote{https://github.com/python/cpython/issues/113464}: Add an option (@code{--enable-experimental-jit} for
@code{configure}-based builds or @code{--experimental-jit} for @code{PCbuild}-based
ones) to build an `experimental' just-in-time compiler, based on
copy-and-patch@footnote{https://fredrikbk.com/publications/copy-and-patch.pdf}

@item 
gh-113055@footnote{https://github.com/python/cpython/issues/113055}: Make interp->obmalloc a pointer. For interpreters that share
state with the main interpreter, this points to the same static memory
structure. For interpreters with their own obmalloc state, it is heap
allocated. Add free_obmalloc_arenas() which will free the obmalloc arenas
and radix tree structures for interpreters with their own obmalloc state.

@item 
gh-55664@footnote{https://github.com/python/cpython/issues/55664}: Add warning when creating @ref{d36,,type} using a namespace
dictionary with non-string keys. Patched by Daniel Urban and Furkan Onder.

@item 
gh-104530@footnote{https://github.com/python/cpython/issues/104530}: Use native Win32 condition variables.
@end itemize

@node Library<12>,Documentation<8>,Core and Builtins<13>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id84}@anchor{15fd}
@subsubsection Library



@itemize -

@item 
gh-115392@footnote{https://github.com/python/cpython/issues/115392}: Fix a bug in @ref{3a,,doctest} where incorrect line numbers would
be reported for decorated functions.

@item 
gh-114563@footnote{https://github.com/python/cpython/issues/114563}: Fix several @ref{60a,,format()} bugs when using the C implementation
of @ref{29a,,Decimal}: * memory leak in some rare cases when using
the @code{z} format option (coerce negative 0) * incorrect output when
applying the @code{z} format option to type @code{F} (fixed-point with capital
@code{NAN} / @code{INF}) * incorrect output when applying the @code{#} format
option (alternate form)

@item 
gh-102840@footnote{https://github.com/python/cpython/issues/102840}: Fix confused traceback when floordiv, mod, or divmod operations
happens between instances of @ref{1e4,,fractions.Fraction} and
@ref{2ec,,complex}.

@item 
gh-115165@footnote{https://github.com/python/cpython/issues/115165}: Most exceptions are now ignored when attempting to set the
@code{__orig_class__} attribute on objects returned when calling
@ref{103,,typing} generic aliases (including generic aliases created using
@ref{92a,,typing.Annotated}). Previously only @ref{343,,AttributeError} was
ignored. Patch by Dave Shawley.

@item 
gh-112903@footnote{https://github.com/python/cpython/issues/112903}: Fix "issubclass() arg 1 must be a class" errors in certain
cases of multiple inheritance with generic aliases (regression in early
3.13 alpha releases).

@item 
gh-115133@footnote{https://github.com/python/cpython/issues/115133}: Fix tests for @ref{fdc,,XMLPullParser}
with Expat 2.6.0.

@item 
gh-115059@footnote{https://github.com/python/cpython/issues/115059}: @code{io.BufferedRandom.read1()} now flushes the underlying
write buffer.

@item 
gh-79382@footnote{https://github.com/python/cpython/issues/79382}: Trailing @code{**} no longer allows to match files and non-existing
paths in recursive @ref{29c,,glob()}.

@item 
gh-67837@footnote{https://github.com/python/cpython/issues/67837}: Avoid race conditions in the creation of directories during
concurrent extraction in @ref{dd,,tarfile} and @ref{130,,zipfile}.

@item 
gh-115060@footnote{https://github.com/python/cpython/issues/115060}: Speed up @ref{22a,,pathlib.Path.glob()} by removing redundant regex
matching.

@item 
gh-97928@footnote{https://github.com/python/cpython/issues/97928}: Partially revert the behavior of @code{tkinter.Text.count()}. By
default it preserves the behavior of older Python versions, except that
setting @code{wantobjects} to 0 no longer has effect. Add a new parameter
`return_ints': specifying @code{return_ints=True} makes @code{Text.count()}
always returning the single count as an integer instead of a 1-tuple or
@code{None}.

@item 
gh-114628@footnote{https://github.com/python/cpython/issues/114628}: When csv.Error is raised when handling TypeError, do not print
the TypeError traceback.

@item 
gh-85984@footnote{https://github.com/python/cpython/issues/85984}: Added @code{_POSIX_VDISABLE} from C's @code{<unistd.h>} to
@ref{e0,,termios}.

@item 
gh-114965@footnote{https://github.com/python/cpython/issues/114965}: Update bundled pip to 24.0

@item 
gh-114959@footnote{https://github.com/python/cpython/issues/114959}: @ref{dd,,tarfile} no longer ignores errors when trying to extract
a directory on top of a file.

@item 
gh-114894@footnote{https://github.com/python/cpython/issues/114894}: Add @ref{1a0,,array.array.clear()}.

@item 
gh-114071@footnote{https://github.com/python/cpython/issues/114071}: Support tuple subclasses using auto() for enum member value.

@item 
gh-109475@footnote{https://github.com/python/cpython/issues/109475}: Fix support of explicit option value "--" in @ref{6,,argparse}
(e.g. @code{--option=--}).

@item 
gh-49766@footnote{https://github.com/python/cpython/issues/49766}: Fix @ref{1c8,,date}-@ref{1c7,,datetime}
comparison. Now the special comparison methods like @code{__eq__} and
@code{__lt__} return @ref{7bc,,NotImplemented} if one of comparands is
@code{date} and other is @code{datetime} instead of ignoring the
time part and the time zone or forcefully return "not equal" or raise
@ref{522,,TypeError}. It makes comparison of @code{date} and
@code{datetime} subclasses more symmetric and allows to change the
default behavior by overriding the special comparison methods in
subclasses.

@item 
gh-110190@footnote{https://github.com/python/cpython/issues/110190}: Fix ctypes structs with array on Windows ARM64 platform by
setting @code{MAX_STRUCT_SIZE} to 32 in stgdict. Patch by Diego Russo

@item 
gh-114678@footnote{https://github.com/python/cpython/issues/114678}: Ensure that deprecation warning for 'N' specifier in
@ref{29a,,Decimal} format is not raised for cases where 'N' appears
in other places in the format specifier. Based on patch by Stefan Krah.

@item 
gh-70303@footnote{https://github.com/python/cpython/issues/70303}: Return both files and directories from @ref{22a,,pathlib.Path.glob()}
if a pattern ends with "@code{**}". Previously only directories were
returned.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Improve import time of @ref{79,,importlib.metadata} and
@ref{50,,email.utils}.

@item 
gh-113280@footnote{https://github.com/python/cpython/issues/113280}: Fix a leak of open socket in rare cases when error occurred in
@ref{8d7,,ssl.SSLSocket} creation.

@item 
gh-77749@footnote{https://github.com/python/cpython/issues/77749}: @ref{15fe,,email.policy.EmailPolicy.fold()} now always encodes
non-ASCII characters in headers if @ref{de5,,utf8}
is false.

@item 
gh-83383@footnote{https://github.com/python/cpython/issues/83383}: Synchronization of the @ref{32,,dbm.dumb} database is now no-op if
there was no modification since opening or last synchronization. The
directory file for a newly created empty @ref{32,,dbm.dumb} database is now
created immediately after opening instead of deferring this until
synchronizing or closing.

@item 
gh-91602@footnote{https://github.com/python/cpython/issues/91602}: Add `filter' keyword-only parameter to
@ref{244,,sqlite3.Connection.iterdump()} for filtering database objects to
dump. Patch by Mariusz Felisiak.

@item 
gh-112451@footnote{https://github.com/python/cpython/issues/112451}: Prohibit subclassing pure-Python @ref{10a1,,datetime.timezone}.
This is consistent with C-extension implementation. Patch by Mariusz
Felisiak.

@item 
gh-69893@footnote{https://github.com/python/cpython/issues/69893}: Add the @code{close()} method for the iterator returned by
@ref{270,,xml.etree.ElementTree.iterparse()}.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Reduce the import time of @ref{ec,,threading} module by ~50%.
Patch by Daniel Hollas.

@item 
gh-114492@footnote{https://github.com/python/cpython/issues/114492}: Make the result of @ref{15ff,,termios.tcgetattr()} reproducible on
Alpine Linux. Previously it could leave a random garbage in some fields.

@item 
gh-114315@footnote{https://github.com/python/cpython/issues/114315}: Make @ref{1600,,threading.Lock} a real class, not a factory
function. Add @code{__new__} to @code{_thread.lock} type.

@item 
gh-100414@footnote{https://github.com/python/cpython/issues/100414}: Add @ref{35,,dbm.sqlite3} as a backend to @ref{31,,dbm}, and make it
the new default @code{dbm} backend. Patch by Raymond Hettinger and Erlend
E. Aasland.

@item 
gh-113267@footnote{https://github.com/python/cpython/issues/113267}: Revert changes in gh-106584@footnote{https://github.com/python/cpython/issues/106584} which made calls of
@code{TestResult} methods @code{startTest()} and @code{stopTest()} unbalanced.

@item 
gh-75128@footnote{https://github.com/python/cpython/issues/75128}: Ignore an @ref{40d,,OSError} in
@code{asyncio.BaseEventLoop.create_server()} when IPv6 is available but the
interface cannot actually support it.

@item 
gh-114423@footnote{https://github.com/python/cpython/issues/114423}: @code{_DummyThread} entries in @code{threading._active} are now
automatically removed when the related thread dies.

@item 
gh-114257@footnote{https://github.com/python/cpython/issues/114257}: Dismiss the @code{FileNotFound} error in
@ref{d37,,ctypes.util.find_library()} and just return @code{None} on Linux.

@item 
gh-114321@footnote{https://github.com/python/cpython/issues/114321}: Expose more platform specific constants in the @ref{58,,fcntl}
module on Linux, macOS, FreeBSD and NetBSD.

@item 
gh-114328@footnote{https://github.com/python/cpython/issues/114328}: The @ref{1601,,tty.setcbreak()} and new @ref{1602,,tty.cfmakecbreak()} no
longer clears the terminal input ICRLF flag. This fixes a regression
introduced in 3.12 that no longer matched how OSes define cbreak mode in
their @code{stty(1)} manual pages.

@item 
gh-114281@footnote{https://github.com/python/cpython/issues/114281}: Remove type hints from @code{Lib/asyncio/staggered.py}. The
annotations in the typeshed@footnote{https://github.com/python/typeshed}
project should be used instead.

@item 
gh-101438@footnote{https://github.com/python/cpython/issues/101438}: Avoid reference cycle in ElementTree.iterparse. The iterator
returned by @code{ElementTree.iterparse} may hold on to a file descriptor.
The reference cycle prevented prompt clean-up of the file descriptor if
the returned iterator was not exhausted.

@item 
gh-114198@footnote{https://github.com/python/cpython/issues/114198}: The signature for the @code{__replace__} method on
@ref{2f,,dataclasses} now has the first argument named @code{self}, rather than
@code{obj}.

@item 
gh-104522@footnote{https://github.com/python/cpython/issues/104522}: @ref{40d,,OSError} raised when run a subprocess now only has
`filename' attribute set to `cwd' if the error was caused by a failed
attempt to change the current directory.

@item 
gh-114149@footnote{https://github.com/python/cpython/issues/114149}: Enum: correctly handle tuple subclasses in custom @code{__new__}.

@item 
gh-83648@footnote{https://github.com/python/cpython/issues/83648}: Support deprecation of options, positional arguments and
subcommands in @ref{6,,argparse}.

@item 
gh-114087@footnote{https://github.com/python/cpython/issues/114087}: Speed up @code{dataclasses.asdict} up to 1.35x.

@item 
gh-109534@footnote{https://github.com/python/cpython/issues/109534}: Fix a reference leak in
@code{asyncio.selector_events.BaseSelectorEventLoop} when SSL handshakes
fail. Patch contributed by Jamie Phan.

@item 
gh-79634@footnote{https://github.com/python/cpython/issues/79634}: Accept @ref{29d,,path-like objects} as patterns
in @ref{22a,,pathlib.Path.glob()} and @ref{22b,,rglob()}.

@item 
gh-112202@footnote{https://github.com/python/cpython/issues/112202}: Ensure that a @ref{1603,,asyncio.Condition.notify()} call does not
get lost if the awakened @code{Task} is simultaneously cancelled or
encounters any other error.

@item 
gh-113951@footnote{https://github.com/python/cpython/issues/113951}: Fix the behavior of @code{tag_unbind()} methods of
@code{tkinter.Text} and @code{tkinter.Canvas} classes with three
arguments. Previously, @code{widget.tag_unbind(tag, sequence, funcid)}
destroyed the current binding for `sequence', leaving `sequence' unbound,
and deleted the `funcid' command. Now it removes only `funcid' from the
binding for `sequence', keeping other commands, and deletes the `funcid'
command. It leaves `sequence' unbound only if `funcid' was the last bound
command.

@item 
gh-97959@footnote{https://github.com/python/cpython/issues/97959}: Fix rendering class methods, bound methods, method and function
aliases in @ref{b4,,pydoc}. Class methods no longer have "method of
builtins.type instance" note. Corresponding notes are now added for class
and unbound methods. Method and function aliases now have references to
the module or the class where the origin was defined if it differs from
the current. Bound methods are now listed in the static methods section.
Methods of builtin classes are now supported as well as methods of Python
classes.

@item 
gh-113796@footnote{https://github.com/python/cpython/issues/113796}: Add more validation checks in the @ref{1604,,csv.Dialect}
constructor. @ref{1ff,,ValueError} is now raised if the same character is used
in different roles.

@item 
gh-113732@footnote{https://github.com/python/cpython/issues/113732}: Fix support of @ref{46e,,QUOTE_NOTNULL} and
@ref{46f,,QUOTE_STRINGS} in @ref{470,,csv.reader()}.

@item 
gh-113225@footnote{https://github.com/python/cpython/issues/113225}: Speed up @ref{492,,pathlib.Path.walk()} by using
@ref{1605,,os.DirEntry.path} where possible.

@item 
gh-89039@footnote{https://github.com/python/cpython/issues/89039}: When replace() method is called on a subclass of datetime, date
or time, properly call derived constructor. Previously, only the base
class's constructor was called.

Also, make sure to pass non-zero fold values when creating subclasses in
various methods. Previously, fold was silently ignored.

@item 
gh-112919@footnote{https://github.com/python/cpython/issues/112919}: Speed-up @ref{1481,,datetime.datetime.replace()},
@ref{1606,,datetime.date.replace()} and @ref{1607,,datetime.time.replace()}.

@item 
gh-59013@footnote{https://github.com/python/cpython/issues/59013}: Set breakpoint on the first executable line of the function,
instead of the line of function definition when the user do @code{break func}
using @ref{a4,,pdb}

@item 
gh-112343@footnote{https://github.com/python/cpython/issues/112343}: Improve handling of pdb convenience variables to avoid
replacing string contents.

@item 
gh-112240@footnote{https://github.com/python/cpython/issues/112240}: Add option to calendar module CLI to specify the weekday to
start each week. Patch by Steven Ward.

@item 
gh-111741@footnote{https://github.com/python/cpython/issues/111741}: Recognise @code{image/webp} as a standard format in the
@ref{8e,,mimetypes} module.

@item 
gh-43457@footnote{https://github.com/python/cpython/issues/43457}: Fix the @ref{ef,,tkinter} widget method @code{wm_attributes()}. It
now accepts the attribute name without the minus prefix to get window
attributes and allows to specify attributes and values to set as keyword
arguments. Add new optional keyword argument `return_python_dict': calling
@code{w.wm_attributes(return_python_dict=True)} returns the attributes as a
dict instead of a tuple. Calling @code{w.wm_attributes()} now returns a tuple
instead of string if `wantobjects' was set to 0.

@item 
gh-82626@footnote{https://github.com/python/cpython/issues/82626}: Many functions now emit a warning if a boolean value is passed
as a file descriptor argument.

@item 
gh-111051@footnote{https://github.com/python/cpython/issues/111051}: Added check for file modification during debugging with
@ref{a4,,pdb}

@item 
gh-110345@footnote{https://github.com/python/cpython/issues/110345}: Show the Tcl/Tk patchlevel (rather than version) in
@code{tkinter._test()}.

@item 
gh-38807@footnote{https://github.com/python/cpython/issues/38807}: Fix race condition in @ref{fc,,trace}. Instead of checking if a
directory exists and creating it, directly call @ref{21b,,os.makedirs()} with
the kwarg @code{exist_ok=True}.

@item 
gh-75705@footnote{https://github.com/python/cpython/issues/75705}: Set unixfrom envelope in @ref{1608,,mailbox.mbox} and
@ref{1609,,mailbox.MMDF}.

@item 
gh-106233@footnote{https://github.com/python/cpython/issues/106233}: Fix stacklevel in @code{InvalidTZPathWarning} during
@ref{133,,zoneinfo} module import.

@item 
gh-105102@footnote{https://github.com/python/cpython/issues/105102}: Allow @ref{160a,,ctypes.Union} to be nested in
@ref{1cf,,ctypes.Structure} when the system endianness is the opposite of
the classes.

@item 
gh-104282@footnote{https://github.com/python/cpython/issues/104282}: Fix null pointer dereference in
@code{lzma._decode_filter_properties()} due to improper handling of BCJ
filters with properties of zero length. Patch by Radislav Chugunov.

@item 
gh-96471@footnote{https://github.com/python/cpython/issues/96471}: Add @ref{1365,,queue.Queue} termination with
@ref{237,,shutdown()}.

@item 
gh-101599@footnote{https://github.com/python/cpython/issues/101599}: Changed argparse flag options formatting to remove redundancy.

@item 
gh-85984@footnote{https://github.com/python/cpython/issues/85984}: Add POSIX pseudo-terminal functions @ref{160b,,os.posix_openpt()},
@ref{160c,,os.grantpt()}, @ref{160d,,os.unlockpt()}, and @ref{160e,,os.ptsname()}.

@item 
gh-102512@footnote{https://github.com/python/cpython/issues/102512}: When @ref{195,,os.fork()} is called from a foreign thread (aka
@code{_DummyThread}), the type of the thread in a child process is changed to
@code{_MainThread}. Also changed its name and daemonic status, it can be now
joined.

@item 
gh-88569@footnote{https://github.com/python/cpython/issues/88569}: Add @ref{220,,os.path.isreserved()}, which identifies reserved
pathnames such as "NUL", "AUX" and "CON". This function is only available
on Windows.

Deprecate @ref{2a3,,pathlib.PurePath.is_reserved()}.

@item 
bpo-38364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38364}: The @code{inspect} functions @code{isgeneratorfunction},
@code{iscoroutinefunction}, @code{isasyncgenfunction} now support
@code{functools.partialmethod} wrapped functions the same way they support
@code{functools.partial}.
@end itemize

@node Documentation<8>,Tests<10>,Library<12>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id85}@anchor{160f}
@subsubsection Documentation



@itemize -

@item 
gh-115233@footnote{https://github.com/python/cpython/issues/115233}: Fix an example for @ref{12d3,,LoggerAdapter} in the
Logging Cookbook.

@item 
gh-114123@footnote{https://github.com/python/cpython/issues/114123}: Move the @ref{29,,csv} module docstring to the @code{csv} module
instead of reexporting it from the internal @code{_csv} module, and
remove @code{__doc__} from @code{csv.__all__}.

Move @code{csv.__version__} to the @code{csv} module instead of
reexporting it from the internal @code{_csv} module, and remove
@code{__version__} from @code{csv.__all__}.
@end itemize

@node Tests<10>,Build<12>,Documentation<8>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id86}@anchor{1610}
@subsubsection Tests



@itemize -

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: Added test exclusions required to run the test suite on iOS.

@item 
gh-105089@footnote{https://github.com/python/cpython/issues/105089}: Fix
@code{test.test_zipfile.test_core.TestWithDirectory.test_create_directory_with_write}
test in AIX by doing a bitwise AND of 0xFFFF on mode , so that it will be
in sync with @code{zinfo.external_attr}
@end itemize

@node Build<12>,Windows<9>,Tests<10>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id87}@anchor{1611}
@subsubsection Build



@itemize -

@item 
gh-115167@footnote{https://github.com/python/cpython/issues/115167}: Avoid vendoring @code{vcruntime140_threads.dll} when building with
Visual Studio 2022 version 17.8.

@item 
gh-113632@footnote{https://github.com/python/cpython/issues/113632}: Promote WASI to a tier 2 platform and drop Emscripten from tier
3 in configure.ac.

@item 
gh-114099@footnote{https://github.com/python/cpython/issues/114099}: configure and Makefile were refactored to accommodate framework
builds on Apple platforms other than macOS.

@item 
gh-114875@footnote{https://github.com/python/cpython/issues/114875}: Add @code{getgrent()} as a prerequisite for building the
@ref{65,,grp} module.
@end itemize

@node Windows<9>,macOS<6>,Build<12>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id88}@anchor{1612}
@subsubsection Windows



@itemize -

@item 
gh-115049@footnote{https://github.com/python/cpython/issues/115049}: Fixes @code{py.exe} launcher failing when run as users without
user profiles.

@item 
gh-115009@footnote{https://github.com/python/cpython/issues/115009}: Update Windows installer to use SQLite 3.45.1.

@item 
gh-109991@footnote{https://github.com/python/cpython/issues/109991}: Update Windows build to use OpenSSL 3.0.13.

@item 
gh-111239@footnote{https://github.com/python/cpython/issues/111239}: Update Windows builds to use zlib v1.3.1.

@item 
gh-100107@footnote{https://github.com/python/cpython/issues/100107}: The @code{py.exe} launcher will no longer attempt to run the
Microsoft Store redirector when launching a script containing a
@code{/usr/bin/env} shebang

@item 
gh-112984@footnote{https://github.com/python/cpython/issues/112984}: Adds free-threaded binaries to Windows installer as an optional
component.

@item 
gh-89240@footnote{https://github.com/python/cpython/issues/89240}: Allows @ref{93,,multiprocessing} to create pools of greater than 62
processes.
@end itemize

@node macOS<6>,IDLE<10>,Windows<9>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id89}@anchor{1613}
@subsubsection macOS



@itemize -

@item 
gh-115009@footnote{https://github.com/python/cpython/issues/115009}: Update macOS installer to use SQLite 3.45.1.

@item 
gh-109991@footnote{https://github.com/python/cpython/issues/109991}: Update macOS installer to use OpenSSL 3.0.13.

@item 
gh-114490@footnote{https://github.com/python/cpython/issues/114490}: Add Mach-O linkage support for @ref{1614,,platform.architecture()}.

@item 
gh-87804@footnote{https://github.com/python/cpython/issues/87804}: On macOS the result of @code{os.statvfs} and @code{os.fstatvfs} now
correctly report the size of very large disks, in previous versions the
reported number of blocks was wrong for disks with at least 2**32 blocks.
@end itemize

@node IDLE<10>,Tools/Demos<5>,macOS<6>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id90}@anchor{1615}
@subsubsection IDLE



@itemize -

@item 
gh-96905@footnote{https://github.com/python/cpython/issues/96905}: In idlelib code, stop redefining built-ins 'dict' and 'object'.

@item 
gh-103820@footnote{https://github.com/python/cpython/issues/103820}: Revise IDLE bindings so that events from mouse button 4/5 on
non-X11 windowing systems (i.e. Win32 and Aqua) are not mistaken for
scrolling.
@end itemize

@node Tools/Demos<5>,C API<12>,IDLE<10>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id91}@anchor{1616}
@subsubsection Tools/Demos



@itemize -

@item 
gh-113516@footnote{https://github.com/python/cpython/issues/113516}: Don't set @code{LDSHARED} when building for WASI.

@item 
gh-109991@footnote{https://github.com/python/cpython/issues/109991}: Update GitHub CI workflows to use OpenSSL 3.0.13 and
multissltests to use 1.1.1w, 3.0.13, 3.1.5, and 3.2.1.

@item 
gh-115015@footnote{https://github.com/python/cpython/issues/115015}: Fix a bug in Argument Clinic that generated incorrect code for
methods with no parameters that use the @ref{1617,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS} calling
convention. Only the positional parameter count was checked; any keyword
argument passed would be silently accepted.
@end itemize

@node C API<12>,,Tools/Demos<5>,Python 3 13 0 alpha 4
@anchor{whatsnew/changelog id92}@anchor{1618}
@subsubsection C API



@itemize -

@item 
gh-111140@footnote{https://github.com/python/cpython/issues/111140}: Adds @ref{357,,PyLong_AsNativeBytes()},
@ref{358,,PyLong_FromNativeBytes()} and
@ref{359,,PyLong_FromUnsignedNativeBytes()} functions.

@item 
gh-114685@footnote{https://github.com/python/cpython/issues/114685}: @ref{74a,,PyBuffer_FillInfo()} now raises a @ref{561,,SystemError} if
called with @ref{1619,,PyBUF_READ} or @ref{161a,,PyBUF_WRITE} as flags.
These flags should only be used with the @code{PyMemoryView_*} C API.

@item 
gh-114685@footnote{https://github.com/python/cpython/issues/114685}: @ref{390,,PyObject_GetBuffer()} now raises a @ref{561,,SystemError} if
called with @ref{1619,,PyBUF_READ} or @ref{161a,,PyBUF_WRITE} as flags.
These flags should only be used with the @code{PyMemoryView_*} C API.

@item 
gh-114626@footnote{https://github.com/python/cpython/issues/114626}: Add @code{PyCFunctionFast} and @code{PyCFunctionFastWithKeywords}
typedefs (identical to the existing @code{_PyCFunctionFast} and
@code{_PyCFunctionFastWithKeywords} typedefs, just without a leading @code{_}
prefix).

@item 
gh-114329@footnote{https://github.com/python/cpython/issues/114329}: Add @ref{351,,PyList_GetItemRef()}, which is similar to
@ref{352,,PyList_GetItem()} but returns a @ref{333,,strong reference} instead of
a @ref{334,,borrowed reference}.

@item 
gh-110850@footnote{https://github.com/python/cpython/issues/110850}: Add PyTime C API:


@itemize *

@item 
@ref{323,,PyTime_t} type.

@item 
@ref{324,,PyTime_MIN} and @ref{325,,PyTime_MAX} constants.

@item 
@ref{326,,PyTime_AsSecondsDouble()},
@ref{327,,PyTime_Monotonic()}, @ref{329,,PyTime_PerfCounter()}, and
@ref{32b,,PyTime_Time()} functions.
@end itemize

Patch by Victor Stinner.

@item 
gh-112066@footnote{https://github.com/python/cpython/issues/112066}: Add @ref{335,,PyDict_SetDefaultRef()}: insert a key and value into
a dictionary if the key is not already present. This is similar to
@ref{1062,,dict.setdefault()}, but returns an integer value indicating if the
key was already present. It is also similar to
@ref{336,,PyDict_SetDefault()}, but returns a strong reference instead of a
borrowed reference.
@end itemize

@node Python 3 13 0 alpha 3,Python 3 13 0 alpha 2,Python 3 13 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-13-0-alpha-3}@anchor{161b}
@subsection Python 3.13.0 alpha 3


`Release date: 2024-01-17'

@menu
* Security: Security<9>. 
* Core and Builtins: Core and Builtins<14>. 
* Library: Library<13>. 
* Documentation: Documentation<9>. 
* Tests: Tests<11>. 
* Build: Build<13>. 
* Windows: Windows<10>. 
* macOS: macOS<7>. 
* IDLE: IDLE<11>. 
* C API: C API<13>. 

@end menu

@node Security<9>,Core and Builtins<14>,,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id93}@anchor{161c}
@subsubsection Security



@itemize -

@item 
gh-113659@footnote{https://github.com/python/cpython/issues/113659}: Skip @code{.pth} files with names starting with a dot or hidden
file attribute.

@item 
gh-112302@footnote{https://github.com/python/cpython/issues/112302}: Created a Software Bill-of-Materials document and tooling for
tracking dependencies.
@end itemize

@node Core and Builtins<14>,Library<13>,Security<9>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id94}@anchor{161d}
@subsubsection Core and Builtins



@itemize -

@item 
gh-107901@footnote{https://github.com/python/cpython/issues/107901}: Compiler duplicates basic blocks that have an eval breaker
check, no line number, and multiple predecessors.

@item 
gh-107901@footnote{https://github.com/python/cpython/issues/107901}: A jump leaving an exception handler back to normal code no
longer checks the eval breaker.

@item 
gh-113655@footnote{https://github.com/python/cpython/issues/113655}: Set the C recursion limit to 4000 on Windows, and 10000 on
Linux/OSX. This seems to be near the sweet spot to maintain safety, but
not compromise backwards compatibility.

@item 
gh-113710@footnote{https://github.com/python/cpython/issues/113710}: Add typed stack effects to the interpreter DSL, along with
various instruction annotations.

@item 
gh-77046@footnote{https://github.com/python/cpython/issues/77046}: On Windows, file descriptors wrapping Windows handles are now
created non inheritable by default (
@geindex Python Enhancement Proposals; PEP 446
PEP 446@footnote{https://peps.python.org/pep-0446/}). Patch by Zackery Spytz
and Victor Stinner.

@item 
gh-113853@footnote{https://github.com/python/cpython/issues/113853}: Guarantee that all executors make progress. This then
guarantees that tier 2 execution always makes progress.

@item 
gh-113753@footnote{https://github.com/python/cpython/issues/113753}: Fix an issue where the finalizer of @code{PyAsyncGenASend} objects
might not be called if they were allocated from a free list.

@item 
gh-107901@footnote{https://github.com/python/cpython/issues/107901}: Compiler changed so that synthetic jumps which are not at loop
end no longer check the eval breaker.

@item 
gh-113703@footnote{https://github.com/python/cpython/issues/113703}: Fix a regression in the @ref{1c,,codeop} module that was causing
it to incorrectly identify incomplete f-strings. Patch by Pablo Galindo

@item 
gh-89811@footnote{https://github.com/python/cpython/issues/89811}: Check for a valid @code{tp_version_tag} before performing bytecode
specializations that rely on this value being usable.

@item 
gh-111488@footnote{https://github.com/python/cpython/issues/111488}: Changed error message in case of no 'in' keyword after 'for' in
list comprehensions

@item 
gh-113657@footnote{https://github.com/python/cpython/issues/113657}: Fix an issue that caused important instruction pointer updates
to be optimized out of tier two traces.

@item 
gh-113603@footnote{https://github.com/python/cpython/issues/113603}: Fixed bug where a redundant NOP is not removed, causing an
assertion to fail in the compiler in debug mode.

@item 
gh-113602@footnote{https://github.com/python/cpython/issues/113602}: Fix an error that was causing the parser to try to overwrite
existing errors and crashing in the process. Patch by Pablo Galindo

@item 
gh-113486@footnote{https://github.com/python/cpython/issues/113486}: No longer issue spurious @code{PY_UNWIND} events for optimized
calls to classes.

@item 
gh-113297@footnote{https://github.com/python/cpython/issues/113297}: Fix segfault in the compiler on with statement with 19 context
managers.

@item 
gh-113212@footnote{https://github.com/python/cpython/issues/113212}: Improve @ref{4c5,,super} error messages.

@item 
gh-111375@footnote{https://github.com/python/cpython/issues/111375}: Only use @code{NULL} in the exception stack to indicate an
exception was handled. Patch by Carey Metcalfe.

@item 
gh-112215@footnote{https://github.com/python/cpython/issues/112215}: Increase the C recursion limit by a factor of 3 for non-debug
builds, except for webassembly and s390 platforms which are unchanged.
This mitigates some regressions in 3.12 with deep recursion mixing builtin
(C) and Python code.

@item 
gh-113054@footnote{https://github.com/python/cpython/issues/113054}: Fixed bug where a redundant NOP is not removed, causing an
assertion to fail in the compiler in debug mode.

@item 
gh-106905@footnote{https://github.com/python/cpython/issues/106905}: Use per AST-parser state rather than global state to track
recursion depth within the AST parser to prevent potential race condition
due to simultaneous parsing.

The issue primarily showed up in 3.11 by multithreaded users of
@ref{1a6,,ast.parse()}.  In 3.12 a change to when garbage collection can be
triggered prevented the race condition from occurring.

@item 
gh-108866@footnote{https://github.com/python/cpython/issues/108866}: Change the API and contract of @code{_PyExecutorObject} to return
the next_instr pointer, instead of the frame, and to always execute at
least one instruction.

@item 
gh-90350@footnote{https://github.com/python/cpython/issues/90350}: Optimize builtin functions @ref{ef3,,min()} and @ref{ef4,,max()}.

@item 
gh-112943@footnote{https://github.com/python/cpython/issues/112943}: Correctly compute end column offsets for multiline tokens in
the @ref{fa,,tokenize} module. Patch by Pablo Galindo

@item 
gh-112125@footnote{https://github.com/python/cpython/issues/112125}: Fix @code{None.__ne__(None)} returning @code{NotImplemented} instead
of @code{False}.

@item 
gh-74616@footnote{https://github.com/python/cpython/issues/74616}: @ref{12b6,,input()} now raises a ValueError when output on the
terminal if the prompt contains embedded null characters instead of
silently truncating it.

@item 
gh-112716@footnote{https://github.com/python/cpython/issues/112716}: Fix SystemError in the @code{import} statement and in
@code{__reduce__()} methods of builtin types when @code{__builtins__} is not a
dict.

@item 
gh-112730@footnote{https://github.com/python/cpython/issues/112730}: Use color to highlight error locations in tracebacks. Patch by
Pablo Galindo

@item 
gh-112625@footnote{https://github.com/python/cpython/issues/112625}: Fixes a bug where a bytearray object could be cleared while
iterating over an argument in the @code{bytearray.join()} method that could
result in reading memory after it was freed.

@item 
gh-112660@footnote{https://github.com/python/cpython/issues/112660}: Do not clear unexpected errors during formatting error messages
for ImportError and AttributeError for modules.

@item 
gh-105967@footnote{https://github.com/python/cpython/issues/105967}: Workaround a bug in Apple's macOS platform zlib library where
@ref{161e,,zlib.crc32()} and @ref{161f,,binascii.crc32()} could produce incorrect
results on multi-gigabyte inputs. Including when using @ref{130,,zipfile} on
zips containing large data.

@item 
gh-95754@footnote{https://github.com/python/cpython/issues/95754}: Provide a better error message when accessing invalid attributes
on partially initialized modules. The origin of the module being accessed
is now included in the message to help with the common issue of shadowing
other modules.

@item 
gh-112217@footnote{https://github.com/python/cpython/issues/112217}: Add check for the type of @code{__cause__} returned from calling
the type @code{T} in @code{raise from T}.

@item 
gh-111058@footnote{https://github.com/python/cpython/issues/111058}: Change coro.cr_frame/gen.gi_frame to return @code{None} after the
coroutine/generator has been closed. This fixes a bug where
@ref{e06,,getcoroutinestate()} and @ref{1214,,getgeneratorstate()}
return the wrong state for a closed coroutine/generator.

@item 
gh-112388@footnote{https://github.com/python/cpython/issues/112388}: Fix an error that was causing the parser to try to overwrite
tokenizer errors. Patch by pablo Galindo

@item 
gh-112387@footnote{https://github.com/python/cpython/issues/112387}: Fix error positions for decoded strings with backwards tokenize
errors. Patch by Pablo Galindo

@item 
gh-99606@footnote{https://github.com/python/cpython/issues/99606}: Make code generated for an empty f-string identical to the code
of an empty normal string.

@item 
gh-112367@footnote{https://github.com/python/cpython/issues/112367}: Avoid undefined behaviour when using the perf trampolines by
not freeing the code arenas until shutdown. Patch by Pablo Galindo

@item 
gh-112320@footnote{https://github.com/python/cpython/issues/112320}: The Tier 2 translator now tracks the confidence level for
staying "on trace" (i.e. not exiting back to the Tier 1 interpreter) for
branch instructions based on the number of bits set in the branch
"counter". Trace translation ends when the confidence drops below 1/3rd.

@item 
gh-109598@footnote{https://github.com/python/cpython/issues/109598}:
@ref{1620,,PyComplex_RealAsDouble()}/@ref{1621,,PyComplex_ImagAsDouble()} now
tries to convert an object to a @ref{2ec,,complex} instance using its
@code{__complex__()} method before falling back to the @code{__float__()}
method. Patch by Sergey B Kirpichev.

@item 
gh-94606@footnote{https://github.com/python/cpython/issues/94606}: Fix UnicodeEncodeError when @code{email.message.get_payload()}
reads a message with a Unicode surrogate character and the message content
is not well-formed for surrogateescape encoding. Patch by Sidney
Markowitz.

@item 
bpo-21861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21861}: Use the object's actual class name in
@code{_io.FileIO.__repr__()}, @code{_io._WindowsConsoleIO()} and
@code{_io.TextIOWrapper.__repr__()}, to make these methods subclass
friendly.

@item 
bpo-45369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45369}: Remove LibreSSL workarounds as per 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}.

@item 
bpo-34392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34392}: Added @ref{24d,,sys._is_interned()}.
@end itemize

@node Library<13>,Documentation<9>,Core and Builtins<14>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id95}@anchor{1622}
@subsubsection Library



@itemize -

@item 
gh-114077@footnote{https://github.com/python/cpython/issues/114077}: Fix possible @ref{86d,,OverflowError} in
@ref{e46,,socket.socket.sendfile()} when pass `count' larger than 2 GiB on
32-bit platform.

@item 
gh-111803@footnote{https://github.com/python/cpython/issues/111803}: @ref{aa,,plistlib} now supports loading more deeply nested lists
in binary format.

@item 
gh-114014@footnote{https://github.com/python/cpython/issues/114014}: Fixed a bug in @ref{1e4,,fractions.Fraction} where an invalid
string using @code{d} in the decimals part creates a different error compared
to other invalid letters/characters. Patch by Jeremiah Gabriel Pascual.

@item 
gh-108364@footnote{https://github.com/python/cpython/issues/108364}: @ref{244,,sqlite3.Connection.iterdump()} now ensures that foreign
key support is disabled before dumping the database schema, if there is
any foreign key violation. Patch by Erlend E. Aasland and Mariusz
Felisiak.

@item 
gh-113971@footnote{https://github.com/python/cpython/issues/113971}: The @ref{cf8,,zipfile.ZipInfo} previously protected
@code{._compresslevel} attribute has been made public as @code{.compress_level}
with the old @code{_compresslevel} name remaining available as a property to
retain compatibility.

@item 
gh-113877@footnote{https://github.com/python/cpython/issues/113877}: Fix @ref{ef,,tkinter} method @code{winfo_pathname()} on 64-bit
Windows.

@item 
gh-113868@footnote{https://github.com/python/cpython/issues/113868}: Added @ref{1623,,mmap.MAP_NORESERVE}, @ref{1624,,mmap.MAP_NOEXTEND},
@ref{1625,,mmap.MAP_HASSEMAPHORE}, @ref{1626,,mmap.MAP_NOCACHE},
@ref{1627,,mmap.MAP_JIT}, @ref{1628,,mmap.MAP_RESILIENT_CODESIGN},
@ref{1629,,mmap.MAP_RESILIENT_MEDIA}, @ref{162a,,mmap.MAP_32BIT},
@ref{162b,,mmap.MAP_TRANSLATED_ALLOW_EXECUTE}, @ref{162c,,mmap.MAP_UNIX03} and
@ref{162d,,mmap.MAP_TPRO}. All of them are @code{mmap(2)} flags on macOS.

@item 
gh-113848@footnote{https://github.com/python/cpython/issues/113848}: @ref{1b3,,asyncio.TaskGroup()} and @ref{5e9,,asyncio.timeout()} context
managers now handle @ref{1b6,,CancelledError} subclasses as well as
exact @code{CancelledError}.

@item 
gh-113661@footnote{https://github.com/python/cpython/issues/113661}: unittest runner: Don't exit 5 if tests were skipped. The
intention of exiting 5 was to detect issues where the test suite wasn't
discovered at all. If we skipped tests, it was correctly discovered.

@item 
gh-96037@footnote{https://github.com/python/cpython/issues/96037}: Insert @ref{81f,,TimeoutError} in the context of the exception that
was raised during exiting an expired @ref{5e9,,asyncio.timeout()} block.

@item 
gh-113781@footnote{https://github.com/python/cpython/issues/113781}: Silence unraisable AttributeError when warnings are emitted
during Python finalization.

@item 
gh-113238@footnote{https://github.com/python/cpython/issues/113238}: Add @code{Anchor} to @code{importlib.resources} (in order for the
code to comply with the documentation)

@item 
gh-111693@footnote{https://github.com/python/cpython/issues/111693}: @ref{162e,,asyncio.Condition.wait()} now re-raises the same
@code{CancelledError} instance that may have caused it to be interrupted.
Fixed race condition in @ref{162f,,asyncio.Semaphore.acquire()} when interrupted
with a @code{CancelledError}.

@item 
gh-113791@footnote{https://github.com/python/cpython/issues/113791}: Add @code{CLOCK_MONOTONIC_RAW_APPROX} and
@code{CLOCK_UPTIME_RAW_APPROX} to @ref{ed,,time} on macOS. These are clocks
available on macOS 10.12 or later.

@item 
gh-112932@footnote{https://github.com/python/cpython/issues/112932}: Restore the ability for @ref{130,,zipfile} to @code{extractall} from
zip files with a "/" directory entry in them as is commonly added to zips
by some wiki or bug tracker data exporters.

@item 
gh-113568@footnote{https://github.com/python/cpython/issues/113568}: Raise deprecation warnings from @ref{490,,pathlib.PurePath} and
not its private base class @code{PurePathBase}.

@item 
gh-113594@footnote{https://github.com/python/cpython/issues/113594}: Fix @ref{662,,UnicodeEncodeError} in @ref{3b,,email} when re-fold
lines that contain unknown-8bit encoded part followed by non-unknown-8bit
encoded part.

@item 
gh-113538@footnote{https://github.com/python/cpython/issues/113538}: In @code{asyncio.StreamReaderProtocol.connection_made()}, there
is callback that logs an error if the task wrapping the "connected
callback" fails. This callback would itself fail if the task was
cancelled. Prevent this by checking whether the task was cancelled first.
If so, close the transport but don't log an error.

@item 
gh-113626@footnote{https://github.com/python/cpython/issues/113626}: Add support for the `allow_code' argument in the @ref{8c,,marshal}
module. Passing @code{allow_code=False} prevents serialization and
de-serialization of code objects which is incompatible between Python
versions.

@item 
gh-85567@footnote{https://github.com/python/cpython/issues/85567}: Fix resource warnings for unclosed files in @ref{a5,,pickle} and
@ref{a6,,pickletools} command line interfaces.

@item 
gh-113537@footnote{https://github.com/python/cpython/issues/113537}: Support loads @code{str} in @ref{93d,,plistlib.loads()}.

@item 
gh-89850@footnote{https://github.com/python/cpython/issues/89850}: Add default implementations of
@ref{1526,,pickle.Pickler.persistent_id()} and
@ref{152e,,pickle.Unpickler.persistent_load()} methods in the C implementation.
Calling @code{super().persistent_id()} and @code{super().persistent_load()} in
subclasses of the C implementation of @ref{a0c,,pickle.Pickler} and
@ref{1630,,pickle.Unpickler} classes no longer causes infinite recursion.

@item 
gh-113569@footnote{https://github.com/python/cpython/issues/113569}: Indicate if there were no actual calls in unittest
@ref{1631,,assert_has_calls()} failure.

@item 
gh-101225@footnote{https://github.com/python/cpython/issues/101225}: Increase the backlog for
@ref{1632,,multiprocessing.connection.Listener} objects created by
@code{multiprocessing.manager} and @code{multiprocessing.resource_sharer}
to significantly reduce the risk of getting a connection refused error
when creating a @ref{1633,,multiprocessing.connection.Connection} to them.

@item 
gh-113568@footnote{https://github.com/python/cpython/issues/113568}: Raise audit events from @ref{226,,pathlib.Path} and not its
private base class @code{PathBase}.

@item 
gh-113543@footnote{https://github.com/python/cpython/issues/113543}: Make sure that @code{webbrowser.MacOSXOSAScript} sends
@code{webbrowser.open} audit event.

@item 
gh-113028@footnote{https://github.com/python/cpython/issues/113028}: When a second reference to a string appears in the input to
@ref{a5,,pickle}, and the Python implementation is in use, we are guaranteed
that a single copy gets pickled and a single object is shared when
reloaded. Previously, in protocol 0, when a string contained certain
characters (e.g. newline) it resulted in duplicate objects.

@item 
gh-113421@footnote{https://github.com/python/cpython/issues/113421}: Fix multiprocessing logger for @code{%(filename)s}.

@item 
gh-111784@footnote{https://github.com/python/cpython/issues/111784}: Fix segfaults in the @code{_elementtree} module. Fix first
segfault during deallocation of @code{_elementtree.XMLParser} instances by
keeping strong reference to @code{pyexpat} module in module state for capsule
lifetime. Fix second segfault which happens in the same deallocation
process  by keeping strong reference to @code{_elementtree} module in
@code{XMLParser} structure for @code{_elementtree} module lifetime.

@item 
gh-113407@footnote{https://github.com/python/cpython/issues/113407}: Fix import of @ref{106,,unittest.mock} when CPython is built
without docstrings.

@item 
gh-113320@footnote{https://github.com/python/cpython/issues/113320}: Fix regression in Python 3.12 where @ref{261,,Protocol}
classes that were not marked as @ref{42c,,runtime-checkable} would be unnecessarily introspected,
potentially causing exceptions to be raised if the protocol had
problematic members. Patch by Alex Waygood.

@item 
gh-53502@footnote{https://github.com/python/cpython/issues/53502}: Add a new option @code{aware_datetime} in @ref{aa,,plistlib} to loads
or dumps aware datetime.

@item 
gh-113358@footnote{https://github.com/python/cpython/issues/113358}: Fix rendering tracebacks with exceptions with a broken
__getattr__

@item 
gh-113214@footnote{https://github.com/python/cpython/issues/113214}: Fix an @code{AttributeError} during asyncio SSL protocol aborts in
SSL-over-SSL scenarios.

@item 
gh-113246@footnote{https://github.com/python/cpython/issues/113246}: Update bundled pip to 23.3.2.

@item 
gh-87264@footnote{https://github.com/python/cpython/issues/87264}: Fixed tarfile list() method to show file type.

@item 
gh-112182@footnote{https://github.com/python/cpython/issues/112182}: @code{asyncio.futures.Future.set_exception()} now transforms
@ref{be8,,StopIteration} into @ref{193,,RuntimeError} instead of hanging or other
misbehavior. Patch contributed by Jamie Phan.

@item 
gh-113225@footnote{https://github.com/python/cpython/issues/113225}: Speed up @ref{22a,,pathlib.Path.glob()} by using
@ref{1605,,os.DirEntry.path} where possible.

@item 
gh-113149@footnote{https://github.com/python/cpython/issues/113149}: Improve error message when a JSON array or object contains a
trailing comma. Patch by Carson Radtke.

@item 
gh-113117@footnote{https://github.com/python/cpython/issues/113117}: The @ref{d5,,subprocess} module can now use the
@ref{21d,,os.posix_spawn()} function with @code{close_fds=True} on platforms where
@code{posix_spawn_file_actions_addclosefrom_np} is available. Patch by Jakub
Kulik.

@item 
gh-113199@footnote{https://github.com/python/cpython/issues/113199}: Make @code{http.client.HTTPResponse.read1} and
@code{http.client.HTTPResponse.readline} close IO after reading all data when
content length is known. Patch by Illia Volochii.

@item 
gh-113191@footnote{https://github.com/python/cpython/issues/113191}: Add support of @ref{219,,os.fchmod()} and a file descriptor in
@ref{218,,os.chmod()} on Windows.

@item 
gh-113188@footnote{https://github.com/python/cpython/issues/113188}: Fix @ref{1634,,shutil.copymode()} and @ref{110e,,shutil.copystat()} on
Windows. Previously they worked differently if `dst' is a symbolic link:
they modified the permission bits of `dst' itself rather than the file it
points to if `follow_symlinks' is true or `src' is not a symbolic link,
and did not modify the permission bits if `follow_symlinks' is false and
`src' is a symbolic link.

@item 
gh-113119@footnote{https://github.com/python/cpython/issues/113119}: @ref{21d,,os.posix_spawn()} now accepts @code{env=None}, which makes
the newly spawned process use the current process environment. Patch by
Jakub Kulik.

@item 
gh-113202@footnote{https://github.com/python/cpython/issues/113202}: Add a @code{strict} option to @code{batched()} in the @code{itertools}
module.

@item 
gh-61648@footnote{https://github.com/python/cpython/issues/61648}: Detect line numbers of properties in doctests.

@item 
gh-113175@footnote{https://github.com/python/cpython/issues/113175}: Sync with importlib_metadata 7.0, including improved type
annotations, fixed issue with symlinked packages in
@code{package_distributions}, added @code{EntryPoints.__repr__}, introduced the
@code{diagnose} script, added @code{Distribution.origin} property, and removed
deprecated @code{EntryPoint} access by numeric index (tuple behavior).

@item 
gh-59616@footnote{https://github.com/python/cpython/issues/59616}: Add support of @ref{217,,os.lchmod()} and the `follow_symlinks'
argument in @ref{218,,os.chmod()} on Windows. Note that the default value of
`follow_symlinks' in @code{os.lchmod()} is @code{False} on Windows.

@item 
gh-112559@footnote{https://github.com/python/cpython/issues/112559}: @ref{1114,,signal.signal()} and @ref{1635,,signal.getsignal()} no longer
call @code{repr} on callable handlers. @ref{466,,asyncio.run()} and
@ref{1636,,asyncio.Runner.run()} no longer call @code{repr} on the task results.
Patch by Yilei Yang.

@item 
gh-112962@footnote{https://github.com/python/cpython/issues/112962}: @ref{38,,dis} module functions add cache information to the
@ref{1d7,,Instruction} instance rather than creating fake
@ref{1d7,,Instruction} instances to represent the cache entries.

@item 
gh-112989@footnote{https://github.com/python/cpython/issues/112989}: Reduce overhead to connect sockets with @ref{a,,asyncio}
SelectorEventLoop.

@item 
gh-112970@footnote{https://github.com/python/cpython/issues/112970}: Use @code{closefrom()} on Linux where available (e.g.
glibc-2.34), rather than only FreeBSD.

@item 
gh-110190@footnote{https://github.com/python/cpython/issues/110190}: Fix ctypes structs with array on PPC64LE platform by setting
@code{MAX_STRUCT_SIZE} to 64 in stgdict. Patch by Diego Russo.

@item 
gh-112540@footnote{https://github.com/python/cpython/issues/112540}: The statistics.geometric_mean() function now returns zero for
datasets containing a zero.  Formerly, it would raise an exception.

@item 
gh-87286@footnote{https://github.com/python/cpython/issues/87286}: Added @code{LOG_FTP}, @code{LOG_NETINFO},
@code{LOG_REMOTEAUTH}, @code{LOG_INSTALL}, @code{LOG_RAS}, and
@code{LOG_LAUNCHD} tot the @ref{db,,syslog} module, all of them constants
on used on macOS.

@item 
gh-112800@footnote{https://github.com/python/cpython/issues/112800}: Fix @ref{a,,asyncio} @code{SubprocessTransport.close()} not to throw
@code{PermissionError} when used with setuid executables.

@item 
gh-51944@footnote{https://github.com/python/cpython/issues/51944}: Add the following constants to the @ref{e0,,termios} module. These
values are present in macOS system headers: @code{ALTWERASE}, @code{B14400},
@code{B28800}, @code{B7200}, @code{B76800}, @code{CCAR_OFLOW}, @code{CCTS_OFLOW},
@code{CDSR_OFLOW}, @code{CDTR_IFLOW}, @code{CIGNORE}, @code{CRTS_IFLOW}, @code{EXTPROC},
@code{IUTF8}, @code{MDMBUF}, @code{NL2}, @code{NL3}, @code{NOKERNINFO}, @code{ONOEOT},
@code{OXTABS}, @code{VDSUSP}, @code{VSTATUS}.

@item 
gh-79325@footnote{https://github.com/python/cpython/issues/79325}: Fix an infinite recursion error in
@ref{1212,,tempfile.TemporaryDirectory()} cleanup on Windows.

@item 
gh-94692@footnote{https://github.com/python/cpython/issues/94692}: @ref{2f5,,shutil.rmtree()} now only catches OSError exceptions.
Previously a symlink attack resistant version of @code{shutil.rmtree()} could
ignore or pass to the error handler arbitrary exception when invalid
arguments were provided.

@item 
gh-112736@footnote{https://github.com/python/cpython/issues/112736}: The use of del-safe symbols in @code{subprocess} was refactored to
allow for use in cross-platform build environments.

@item 
gh-112727@footnote{https://github.com/python/cpython/issues/112727}: Speed up @ref{1637,,pathlib.Path.absolute()}. Patch by Barney Gale.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: Speedup @ref{7ab,,issubclass()} checks against simple
@ref{42c,,runtime-checkable protocols} by around
6%. Patch by Alex Waygood.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: Speedup @ref{42b,,isinstance()} checks by roughly 20% for
@ref{42c,,runtime-checkable protocols} that only
have one callable member. Speedup @ref{7ab,,issubclass()} checks for these
protocols by roughly 10%. Patch by Alex Waygood.

@item 
gh-112645@footnote{https://github.com/python/cpython/issues/112645}: Remove deprecation error on passing @code{onerror} to
@ref{2f5,,shutil.rmtree()}.

@item 
gh-112640@footnote{https://github.com/python/cpython/issues/112640}: Add @code{kwdefaults} parameter to @ref{86f,,types.FunctionType} to
set default keyword argument values.

@item 
gh-112622@footnote{https://github.com/python/cpython/issues/112622}: Ensure @code{name} parameter is passed to event loop in
@ref{5e7,,asyncio.create_task()}.

@item 
gh-112618@footnote{https://github.com/python/cpython/issues/112618}: Fix a caching bug relating to @ref{92a,,typing.Annotated}.
@code{Annotated[str, True]} is no longer identical to @code{Annotated[str, 1]}.

@item 
gh-112334@footnote{https://github.com/python/cpython/issues/112334}: Fixed a performance regression in 3.12's @ref{d5,,subprocess} on
Linux where it would no longer use the fast-path @code{vfork()} system call
when it could have due to a logic bug, instead falling back to the safe
but slower @code{fork()}.

Also fixed a second 3.12.0 potential security bug.  If a value of
@code{extra_groups=[]} was passed to @ref{197,,subprocess.Popen} or related APIs,
the underlying @code{setgroups(0, NULL)} system call to clear the groups list
would not be made in the child process prior to @code{exec()}.

This was identified via code inspection in the process of fixing the first
bug.

@item 
gh-110190@footnote{https://github.com/python/cpython/issues/110190}: Fix ctypes structs with array on Arm platform by setting
@code{MAX_STRUCT_SIZE} to 32 in stgdict. Patch by Diego Russo.

@item 
gh-81194@footnote{https://github.com/python/cpython/issues/81194}: Fix a crash in @ref{a1d,,socket.if_indextoname()} with specific value
(UINT_MAX). Fix an integer overflow in @ref{a1d,,socket.if_indextoname()} on
64-bit non-Windows platforms.

@item 
gh-112578@footnote{https://github.com/python/cpython/issues/112578}: Fix a spurious @ref{1bb,,RuntimeWarning} when executing the
@ref{130,,zipfile} module.

@item 
gh-112516@footnote{https://github.com/python/cpython/issues/112516}: Update the bundled copy of pip to version 23.3.1.

@item 
gh-112510@footnote{https://github.com/python/cpython/issues/112510}: Add @ref{1638,,readline.backend} for the backend readline uses
(@code{editline} or @code{readline})

@item 
gh-112328@footnote{https://github.com/python/cpython/issues/112328}: [Enum] Make @code{EnumDict}, @code{EnumDict.member_names},
@code{EnumType._add_alias_} and @code{EnumType._add_value_alias_} public.

@item 
gh-112509@footnote{https://github.com/python/cpython/issues/112509}: Fix edge cases that could cause a key to be present in both the
@code{__required_keys__} and @code{__optional_keys__} attributes of a
@ref{161,,typing.TypedDict}. Patch by Jelle Zijlstra.

@item 
gh-101336@footnote{https://github.com/python/cpython/issues/101336}: Add @code{keep_alive} keyword parameter for
@code{AbstractEventLoop.create_server()} and
@code{BaseEventLoop.create_server()}.

@item 
gh-63284@footnote{https://github.com/python/cpython/issues/63284}: Added support for TLS-PSK (pre-shared key) mode to the
@ref{cf,,ssl} module.

@item 
gh-112414@footnote{https://github.com/python/cpython/issues/112414}: Fix regression in Python 3.12 where calling @ref{7e7,,repr()} on a
module that had been imported using a custom @ref{1639,,loader} could fail
with @ref{343,,AttributeError}. Patch by Alex Waygood.

@item 
gh-112358@footnote{https://github.com/python/cpython/issues/112358}: Revert change to @ref{163a,,struct.Struct} initialization that
broke some cases of subclassing.

@item 
gh-112405@footnote{https://github.com/python/cpython/issues/112405}: Optimize @ref{2c8,,pathlib.PurePath.relative_to()}. Patch by Alex
Waygood.

@item 
gh-94722@footnote{https://github.com/python/cpython/issues/94722}: Fix bug where comparison between instances of
@ref{163b,,DocTest} fails if one of them has @code{None} as its lineno.

@item 
gh-112361@footnote{https://github.com/python/cpython/issues/112361}: Speed up a small handful of @ref{a3,,pathlib} methods by removing
some temporary objects.

@item 
gh-112345@footnote{https://github.com/python/cpython/issues/112345}: Improve error message when trying to call @ref{7ab,,issubclass()}
against a @ref{261,,typing.Protocol} that has non-method members. Patch by
Randolf Scholz.

@item 
gh-112137@footnote{https://github.com/python/cpython/issues/112137}: Change @ref{38,,dis} output to display no-lineno as "--" instead
of "None".

@item 
gh-112332@footnote{https://github.com/python/cpython/issues/112332}: Deprecate the @code{exc_type} field of
@ref{259,,traceback.TracebackException}. Add @code{exc_type_str} to replace it.

@item 
gh-81620@footnote{https://github.com/python/cpython/issues/81620}: Add extra tests for @ref{499,,random.binomialvariate()}

@item 
gh-112292@footnote{https://github.com/python/cpython/issues/112292}: Fix a crash in @ref{b9,,readline} when imported from a sub
interpreter. Patch by Anthony Shaw

@item 
gh-77621@footnote{https://github.com/python/cpython/issues/77621}: Slightly improve the import time of the @ref{a3,,pathlib} module by
deferring some imports. Patch by Barney Gale.

@item 
gh-112137@footnote{https://github.com/python/cpython/issues/112137}: Change @ref{38,,dis} output to display logical labels for jump
targets instead of offsets.

@item 
gh-112139@footnote{https://github.com/python/cpython/issues/112139}: Add @code{Signature.format()} to format signatures to string
with extra options. And use it in @ref{b4,,pydoc} to render more readable
signatures that have new lines between parameters.

@item 
gh-112105@footnote{https://github.com/python/cpython/issues/112105}: Make @ref{163c,,readline.set_completer_delims()} work with libedit

@item 
gh-106922@footnote{https://github.com/python/cpython/issues/106922}: Display multiple lines with @code{traceback} when errors span
multiple lines.

@item 
gh-111874@footnote{https://github.com/python/cpython/issues/111874}: When creating a @ref{2ad,,typing.NamedTuple} class, ensure
@ref{c3c,,__set_name__()} is called on all objects that define
@code{__set_name__} and exist in the values of the @code{NamedTuple} class's
class dictionary. Patch by Alex Waygood.

@item 
gh-68166@footnote{https://github.com/python/cpython/issues/68166}: Add support of the "vsapi" element type in
@ref{255,,tkinter.ttk.Style.element_create()}.

@item 
gh-110275@footnote{https://github.com/python/cpython/issues/110275}: Named tuple's methods @code{_replace()} and @code{__replace__()} now
raise TypeError instead of ValueError for invalid keyword arguments.

@item 
gh-99367@footnote{https://github.com/python/cpython/issues/99367}: Do not mangle @code{sys.path[0]} in @ref{a4,,pdb} if safe_path is set

@item 
gh-111615@footnote{https://github.com/python/cpython/issues/111615}: Fix a regression caused by a fix to gh-93162@footnote{https://github.com/python/cpython/issues/93162} whereby you
couldn't configure a @code{QueueHandler} without specifying handlers.

@item 
gh-75666@footnote{https://github.com/python/cpython/issues/75666}: Fix the behavior of @ref{ef,,tkinter} widget's @code{unbind()} method
with two arguments. Previously, @code{widget.unbind(sequence, funcid)}
destroyed the current binding for `sequence', leaving `sequence' unbound,
and deleted the `funcid' command. Now it removes only `funcid' from the
binding for `sequence', keeping other commands, and deletes the `funcid'
command. It leaves `sequence' unbound only if `funcid' was the last bound
command.

@item 
gh-67790@footnote{https://github.com/python/cpython/issues/67790}: Implement basic formatting support (minimum width, alignment,
fill) for @ref{1e4,,fractions.Fraction}.

@item 
gh-111049@footnote{https://github.com/python/cpython/issues/111049}: Fix crash during garbage collection of the @ref{e8d,,io.BytesIO}
buffer object.

@item 
gh-102980@footnote{https://github.com/python/cpython/issues/102980}: Redirect the output of @code{interact} command of @ref{a4,,pdb} to
the same channel as the debugger. Add tests and improve docs.

@item 
gh-102988@footnote{https://github.com/python/cpython/issues/102988}: @ref{1de,,email.utils.getaddresses()} and
@ref{1df,,email.utils.parseaddr()} now return @code{('@w{'}, '@w{'})} 2-tuples in more
situations where invalid email addresses are encountered instead of
potentially inaccurate values. Add optional `strict' parameter to these
two functions: use @code{strict=False} to get the old behavior, accept
malformed inputs. @code{getattr(email.utils, 'supports_strict_parsing',
False)} can be use to check if the `strict' parameter is available. Patch
by Thomas Dwyer and Victor Stinner to improve the 
@geindex Common Vulnerabilities and Exposures; CVE 2023-27043
CVE 2023-27043@footnote{https://www.cve.org/CVERecord?id=CVE-2023-27043} fix.

@item 
gh-52161@footnote{https://github.com/python/cpython/issues/52161}: @ref{163d,,cmd.Cmd.do_help()} now cleans docstrings with
@ref{163e,,inspect.cleandoc()} before writing them. Patch by Filip Łapkiewicz.

@item 
gh-82300@footnote{https://github.com/python/cpython/issues/82300}: Add @code{track} parameter to
@ref{15e2,,multiprocessing.shared_memory.SharedMemory} that allows using
shared memory blocks without having to register with the POSIX resource
tracker that automatically releases them upon process exit.

@item 
gh-110109@footnote{https://github.com/python/cpython/issues/110109}: Add private @code{pathlib._PurePathBase} class: a base class for
@ref{490,,pathlib.PurePath} that omits certain magic methods. It may be made
public (along with @code{_PathBase}) in future.

@item 
gh-109858@footnote{https://github.com/python/cpython/issues/109858}: Protect @ref{130,,zipfile} from "quoted-overlap" zipbomb. It now
raises BadZipFile when try to read an entry that overlaps with other entry
or central directory.

@item 
gh-109786@footnote{https://github.com/python/cpython/issues/109786}: Fix possible reference leaks and crash when re-enter the
@code{__next__()} method of @ref{7ff,,itertools.pairwise}.

@item 
gh-91539@footnote{https://github.com/python/cpython/issues/91539}: Small (10 - 20%) and trivial performance improvement of
@code{urllib.request.getproxies_environment()}, typically useful when there
are many environment variables to go over.

@item 
gh-103363@footnote{https://github.com/python/cpython/issues/103363}: Add `follow_symlinks' keyword-only argument to
@ref{22e,,pathlib.Path.owner()} and @ref{22f,,group()}, defaulting to
@code{True}.

@item 
gh-102130@footnote{https://github.com/python/cpython/issues/102130}: Support tab completion in @ref{19,,cmd} for @code{editline}.

@item 
gh-99437@footnote{https://github.com/python/cpython/issues/99437}: @ref{17f,,runpy.run_path()} now decodes path-like objects, making
sure __file__ and sys.argv[0] of the module being run are always strings.

@item 
gh-104003@footnote{https://github.com/python/cpython/issues/104003}: Add @ref{15f,,warnings.deprecated()}, a decorator to mark deprecated
functions to static type checkers and to warn on usage of deprecated
classes and functions. See 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}. Patch by Jelle Zijlstra.

@item 
gh-103708@footnote{https://github.com/python/cpython/issues/103708}: Make hardcoded python name, a configurable parameter so that
different implementations of python can override it instead of making huge
diffs in sysconfig.py

@item 
gh-66515@footnote{https://github.com/python/cpython/issues/66515}: @ref{163f,,mailbox.MH} now supports folders that do not contain a
@code{.mh_sequences} file (e.g. Claws Mail IMAP-cache folders). Patch by
Serhiy Storchaka.

@item 
gh-83162@footnote{https://github.com/python/cpython/issues/83162}: Renamed @code{re.error} to @code{PatternError} for clarity, and
kept @code{re.error} for backward compatibility. Patch by Matthias
Bussonnier and Adam Chhina.

@item 
gh-91133@footnote{https://github.com/python/cpython/issues/91133}: Fix a bug in @ref{1212,,tempfile.TemporaryDirectory} cleanup, which
now no longer dereferences symlinks when working around file system
permission errors.

@item 
bpo-43153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43153}: On Windows, @code{tempfile.TemporaryDirectory} previously masked a
@code{PermissionError} with @code{NotADirectoryError} during directory cleanup.
It now correctly raises @code{PermissionError} if errors are not ignored.
Patch by Andrei Kulakov and Ken Jin.

@item 
bpo-32731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32731}: @ref{40e,,getpass.getuser()} now raises @ref{40d,,OSError} for all
failures rather than @ref{40f,,ImportError} on systems lacking the @ref{b1,,pwd}
module or @ref{33a,,KeyError} if the password database is empty.

@item 
bpo-34321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34321}: @ref{208,,mmap.mmap} now has a `trackfd' parameter on Unix; if it
is @code{False}, the file descriptor specified by `fileno' will not be
duplicated.

@item 
bpo-35332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35332}: The @ref{2f5,,shutil.rmtree()} function now ignores errors when
calling @ref{b62,,os.close()} when `ignore_errors' is @code{True}, and
@ref{b62,,os.close()} no longer retried after error.

@item 
bpo-35928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35928}: @ref{7a5,,io.TextIOWrapper} now correctly handles the decoding
buffer after @code{read()} and @code{write()}.

@item 
bpo-26791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26791}: @ref{a4a,,shutil.move()} now moves a symlink into a directory when
that directory is the target of the symlink.  This provides the same
behavior as the mv shell command.  The previous behavior raised an
exception.  Patch by Jeffrey Kintscher.

@item 
bpo-41422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41422}: Fixed memory leaks of @ref{a0c,,pickle.Pickler} and
@ref{1630,,pickle.Unpickler} involving cyclic references via the internal
memo mapping.

@item 
bpo-19821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19821}: The @code{pydoc.ispackage()} function has been deprecated.

@item 
bpo-40262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40262}: The @code{ssl.SSLSocket.recv_into()} method no longer requires
the `buffer' argument to implement @code{__len__} and supports buffers with
arbitrary item size.

@item 
bpo-39912@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39912}: @ref{145d,,warnings.filterwarnings()} and
@ref{6ac,,warnings.simplefilter()} now raise appropriate exceptions instead of
@code{AssertionError}. Patch contributed by Rémi Lapeyre.

@item 
bpo-37260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37260}: Fixed a race condition in @ref{2f5,,shutil.rmtree()} in which
directory entries removed by another process or thread while
@code{shutil.rmtree()} is running can cause it to raise FileNotFoundError.
Patch by Jeffrey Kintscher.

@item 
bpo-36959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36959}: Fix some error messages for invalid ISO format string
combinations in @code{strptime()} that referred to directives not contained
in the format string. Patch by Gordon P. Hemsley.

@item 
bpo-18060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18060}: Fixed a class inheritance issue that can cause segfaults when
deriving two or more levels of subclasses from a base class of Structure
or Union.

@item 
bpo-29779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29779}: Add a new 
@geindex PYTHON_HISTORY
@geindex variable d'environnement; PYTHON_HISTORY
@ref{18f,,PYTHON_HISTORY} environment variable to set
the location of a @code{.python_history} file.

@item 
bpo-21360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21360}: @ref{412,,mailbox.Maildir} now ignores files with a leading dot.
@end itemize

@node Documentation<9>,Tests<11>,Library<13>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id96}@anchor{1640}
@subsubsection Documentation



@itemize -

@item 
gh-111699@footnote{https://github.com/python/cpython/issues/111699}: Relocate @code{smtpd} deprecation notice to its own section rather
than under @code{locale} in What's New in Python 3.12 document

@item 
gh-110746@footnote{https://github.com/python/cpython/issues/110746}: Improved markup for valid options/values for methods
ttk.treeview.column and ttk.treeview.heading, and for Layouts.

@item 
gh-95649@footnote{https://github.com/python/cpython/issues/95649}: Document that the @ref{a,,asyncio} module contains code taken from
v0.16.0 of the uvloop project@footnote{https://github.com/MagicStack/uvloop/tree/v0.16.0}, as well as the
required MIT licensing information.
@end itemize

@node Tests<11>,Build<13>,Documentation<9>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id97}@anchor{1641}
@subsubsection Tests



@itemize -

@item 
gh-111798@footnote{https://github.com/python/cpython/issues/111798}: Disable @code{test_super_deep()} from @code{test_call} under pydebug
builds on WASI; the stack depth is too small to make the test useful.

@item 
gh-111801@footnote{https://github.com/python/cpython/issues/111801}: Lower the recursion limit in @code{test_isinstance} for
@code{test_infinitely_many_bases()}. This prevents a stack overflow on a
pydebug build of WASI.

@item 
gh-111802@footnote{https://github.com/python/cpython/issues/111802}: Specify a low recursion depth for @code{test_bad_getattr()} in
@code{test.pickletester} to avoid exhausting the stack under a pydebug build
for WASI.

@item 
gh-44626@footnote{https://github.com/python/cpython/issues/44626}: Fix @ref{221,,os.path.isabs()} incorrectly returning @code{True} when
given a path that starts with exactly one (back)slash on Windows.

Fix @code{pathlib.PureWindowsPath.is_absolute()} incorrectly returning
@code{False} for some paths beginning with two (back)slashes.

@item 
gh-113633@footnote{https://github.com/python/cpython/issues/113633}: Use module state for the _testcapi extension module.

@item 
gh-109980@footnote{https://github.com/python/cpython/issues/109980}: Fix @code{test_tarfile_vs_tar} in @code{test_shutil} for macOS, where
system tar can include more information in the archive than
@ref{49c,,shutil.make_archive}.

@item 
gh-112769@footnote{https://github.com/python/cpython/issues/112769}: The tests now correctly compare zlib version when
@ref{114e,,zlib.ZLIB_RUNTIME_VERSION} contains non-integer suffixes. For
example zlib-ng defines the version as @code{1.3.0.zlib-ng}.

@item 
gh-112334@footnote{https://github.com/python/cpython/issues/112334}: Adds a regression test to verify that @code{vfork()} is used when
expected by @ref{d5,,subprocess} on vfork enabled POSIX systems (Linux).

@item 
gh-108927@footnote{https://github.com/python/cpython/issues/108927}: Fixed order dependence in running tests in the same process
when a test that has submodules (e.g. test_importlib) follows a test that
imports its submodule (e.g. test_importlib.util) and precedes a test (e.g.
test_unittest or test_compileall) that uses that submodule.

@item 
bpo-40648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40648}: Test modes that file can get with chmod() on Windows.
@end itemize

@node Build<13>,Windows<10>,Tests<11>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id98}@anchor{1642}
@subsubsection Build



@itemize -

@item 
gh-114013@footnote{https://github.com/python/cpython/issues/114013}: Fix @code{Tools/wasm/wasi.py} to not include the path to
@code{python.wasm} as part of @code{HOSTRUNNER}. The environment variable is
meant to specify how to run the WASI host only, having @code{python.wasm} and
relevant flags appended to the @code{HOSTRUNNER}. This fixes @code{make test}
work.

@item 
gh-113258@footnote{https://github.com/python/cpython/issues/113258}: Changed the Windows build to write out generated frozen modules
into the build tree instead of the source tree.

@item 
gh-112305@footnote{https://github.com/python/cpython/issues/112305}: Fixed the @code{check-clean-src} step performed on out of tree
builds to detect errant @code{$(srcdir)/Python/frozen_modules/*.h} files and
recommend appropriate source tree cleanup steps to get a working build
again.

@item 
gh-112536@footnote{https://github.com/python/cpython/issues/112536}: Add support for thread sanitizer (TSAN)

@item 
gh-112867@footnote{https://github.com/python/cpython/issues/112867}: Fix the build for the case that WITH_PYMALLOC_RADIX_TREE=0 set.

@item 
gh-103065@footnote{https://github.com/python/cpython/issues/103065}: Introduce @code{Tools/wasm/wasi.py} to simplify doing a WASI
build.

@item 
bpo-11102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11102}: The @ref{15a3,,os.major()}, @ref{15a5,,os.makedev()}, and @ref{15a4,,os.minor()}
functions are now available on HP-UX v3.

@item 
bpo-36351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36351}: Do not set ipv6type when cross-compiling.
@end itemize

@node Windows<10>,macOS<7>,Build<13>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id99}@anchor{1643}
@subsubsection Windows



@itemize -

@item 
gh-114096@footnote{https://github.com/python/cpython/issues/114096}: Process privileges that are activated for creating directory
junctions are now restored afterwards, avoiding behaviour changes in other
parts of the program.

@item 
gh-111877@footnote{https://github.com/python/cpython/issues/111877}: @ref{48a,,os.stat()} calls were returning incorrect time values for
files that could not be accessed directly.

@item 
gh-111973@footnote{https://github.com/python/cpython/issues/111973}: Update Windows installer to use SQLite 3.44.2.

@item 
gh-113009@footnote{https://github.com/python/cpython/issues/113009}: @ref{93,,multiprocessing}: On Windows, fix a race condition in
@code{Process.terminate()}: no longer set the @code{returncode} attribute to
always call @code{WaitForSingleObject()} in @code{Process.wait()}.  Previously,
sometimes the process was still running after @code{TerminateProcess()} even
if @code{GetExitCodeProcess()} is not @code{STILL_ACTIVE}. Patch by Victor
Stinner.

@item 
gh-86179@footnote{https://github.com/python/cpython/issues/86179}: Fixes path calculations when launching Python on Windows through
a symlink.

@item 
gh-71383@footnote{https://github.com/python/cpython/issues/71383}: Update Tcl/Tk in Windows installer to 8.6.13 with a patch to
suppress incorrect ThemeChanged warnings.

@item 
gh-111650@footnote{https://github.com/python/cpython/issues/111650}: Ensures the @code{Py_GIL_DISABLED} preprocessor variable is
defined in @code{pyconfig.h} so that extension modules written in C are
able to use it.

@item 
gh-112278@footnote{https://github.com/python/cpython/issues/112278}: Reduce the time cost for some functions in @ref{a9,,platform} on
Windows if current user has no permission to the WMI.

@item 
gh-73427@footnote{https://github.com/python/cpython/issues/73427}: Deprecate @ref{2ab,,sys._enablelegacywindowsfsencoding()}. Use
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} instead. Patch by Inada Naoki.

@item 
gh-87868@footnote{https://github.com/python/cpython/issues/87868}: Correctly sort and remove duplicate environment variables in
@code{_winapi.CreateProcess()}.

@item 
bpo-37308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37308}: Fix mojibake in @ref{208,,mmap.mmap} when using a non-ASCII
`tagname' argument on Windows.
@end itemize

@node macOS<7>,IDLE<11>,Windows<10>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id100}@anchor{1644}
@subsubsection macOS



@itemize -

@item 
gh-113666@footnote{https://github.com/python/cpython/issues/113666}: Add the following constants to module @ref{d0,,stat}:
@code{UF_SETTABLE}, @code{UF_TRACKED}, @code{UF_DATAVAULT}, @code{SF_SUPPORTED},
@code{SF_SETTABLE}, @code{SF_SYNTHETIC}, @code{SF_RESTRICTED}, @code{SF_FIRMLINK} and
@code{SF_DATALESS}. The values @code{UF_SETTABLE}, @code{SF_SUPPORTED},
@code{SF_SETTABLE} and @code{SF_SYNTHETIC} are only available on macOS.

@item 
gh-113536@footnote{https://github.com/python/cpython/issues/113536}: @ref{d86,,os.waitid()} is now available on macOS

@item 
gh-110459@footnote{https://github.com/python/cpython/issues/110459}: Running @code{configure ... --with-openssl-rpath=X/Y/Z} no longer
fails to detect OpenSSL on macOS.

@item 
gh-74573@footnote{https://github.com/python/cpython/issues/74573}: Document that @ref{34,,dbm.ndbm} can silently corrupt DBM files on
updates when exceeding undocumented platform limits, and can crash
(segmentation fault) when reading such a corrupted file. (FB8919203)

@item 
gh-65701@footnote{https://github.com/python/cpython/issues/65701}: The @code{freeze} tool doesn't work with framework builds of
Python. Document this and bail out early when running the tool with such a
build.

@item 
gh-87277@footnote{https://github.com/python/cpython/issues/87277}: webbrowser: Don't look for X11 browsers on macOS. Those are
generally not used and probing for them can result in starting XQuartz
even if it isn't used otherwise.

@item 
gh-111973@footnote{https://github.com/python/cpython/issues/111973}: Update macOS installer to use SQLite 3.44.2.

@item 
gh-108269@footnote{https://github.com/python/cpython/issues/108269}: Set @code{CFBundleAllowMixedLocalizations} to true in the
Info.plist for the framework, embedded Python.app and IDLE.app with
framework installs on macOS.  This allows applications to pick up the
user's preferred locale when that's different from english.

@item 
gh-102362@footnote{https://github.com/python/cpython/issues/102362}: Make sure the result of @code{sysconfig.get_plaform()} includes
at least a major and minor versions, even if @code{MACOSX_DEPLOYMENT_TARGET}
is set to only a major version during build to match the format expected
by pip.

@item 
gh-110017@footnote{https://github.com/python/cpython/issues/110017}: Disable a signal handling stress test on macOS due to a bug in
macOS (FB13453490).

@item 
gh-110820@footnote{https://github.com/python/cpython/issues/110820}: Make sure the preprocessor definitions for
@code{ALIGNOF_MAX_ALIGN_T}, @code{SIZEOF_LONG_DOUBLE} and
@code{HAVE_GCC_ASM_FOR_X64} are correct for Universal 2 builds on macOS.

@item 
gh-109981@footnote{https://github.com/python/cpython/issues/109981}: Use @code{/dev/fd} on macOS to determine the number of open files
in @code{test.support.os_helper.fd_count} to avoid a crash with "guarded"
file descriptors when probing for open files.
@end itemize

@node IDLE<11>,C API<13>,macOS<7>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id101}@anchor{1645}
@subsubsection IDLE



@itemize -

@item 
gh-72284@footnote{https://github.com/python/cpython/issues/72284}: Improve the lists of features, editor key bindings, and shell
key bingings in the IDLE doc.

@item 
gh-113903@footnote{https://github.com/python/cpython/issues/113903}: Fix rare failure of test.test_idle, in test_configdialog.

@item 
gh-113729@footnote{https://github.com/python/cpython/issues/113729}: Fix the "Help -> IDLE Doc" menu bug in 3.11.7 and 3.12.1.

@item 
gh-113269@footnote{https://github.com/python/cpython/issues/113269}: Fix test_editor hang on macOS Catalina.

@item 
gh-112898@footnote{https://github.com/python/cpython/issues/112898}: Fix processing unsaved files when quitting IDLE on macOS.

@item 
bpo-13586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13586}: Enter the selected text when opening the "Replace" dialog.
@end itemize

@node C API<13>,,IDLE<11>,Python 3 13 0 alpha 3
@anchor{whatsnew/changelog id102}@anchor{1646}
@subsubsection C API



@itemize -

@item 
gh-106560@footnote{https://github.com/python/cpython/issues/106560}: Fix redundant declarations in the public C API. Declare
PyBool_Type, PyLong_Type and PySys_Audit() only once. Patch by Victor
Stinner.

@item 
gh-112438@footnote{https://github.com/python/cpython/issues/112438}: Fix support of format units "es", "et", "es#", and "et#" in
nested tuples in @ref{55d,,PyArg_ParseTuple()}-like functions.

@item 
gh-111545@footnote{https://github.com/python/cpython/issues/111545}: Add @ref{35e,,Py_HashPointer()} function to hash a pointer. Patch
by Victor Stinner.

@item 
gh-65210@footnote{https://github.com/python/cpython/issues/65210}: Change the declaration of the `keywords' parameter of
@ref{379,,PyArg_ParseTupleAndKeywords()} and
@ref{37a,,PyArg_VaParseTupleAndKeywords()} for better compatibility with C++.
@end itemize

@node Python 3 13 0 alpha 2,Python 3 13 0 alpha 1,Python 3 13 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-13-0-alpha-2}@anchor{1647}
@subsection Python 3.13.0 alpha 2


`Release date: 2023-11-22'

@menu
* Core and Builtins: Core and Builtins<15>. 
* Library: Library<14>. 
* Tests: Tests<12>. 
* Build: Build<14>. 
* Windows: Windows<11>. 
* macOS: macOS<8>. 
* IDLE: IDLE<12>. 
* Tools/Demos: Tools/Demos<6>. 
* C API: C API<14>. 

@end menu

@node Core and Builtins<15>,Library<14>,,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id103}@anchor{1648}
@subsubsection Core and Builtins



@itemize -

@item 
gh-112243@footnote{https://github.com/python/cpython/issues/112243}: Don't include comments in f-string debug expressions. Patch by
Pablo Galindo

@item 
gh-112287@footnote{https://github.com/python/cpython/issues/112287}: Slightly optimize the Tier 2 (uop) interpreter by only loading
@code{oparg} and @code{operand} when needed. Also double the trace size limit
again, to 512 this time.

@item 
gh-112266@footnote{https://github.com/python/cpython/issues/112266}: Change docstrings of @ref{546,,__dict__} and
@code{__weakref__}.

@item 
gh-111807@footnote{https://github.com/python/cpython/issues/111807}: Lower the max parser stack depth to 1000 under WASI debug
builds.

@item 
gh-111798@footnote{https://github.com/python/cpython/issues/111798}: When Python is built in debug mode, set the C recursion limit
to 500 instead of 1500. A debug build is likely built with low
optimization level which implies higher stack memory usage than a release
build. Patch by Victor Stinner.

@item 
gh-106529@footnote{https://github.com/python/cpython/issues/106529}: Enable translating unspecialized @code{FOR_ITER} to Tier 2.

@item 
gh-111916@footnote{https://github.com/python/cpython/issues/111916}: Make hashlib related modules thread-safe without the GIL

@item 
gh-81137@footnote{https://github.com/python/cpython/issues/81137}: Deprecate assignment to a function's @code{__code__} field when the
new code object is of a mismatched type (e.g., from a generator to a plain
function).

@item 
gh-79932@footnote{https://github.com/python/cpython/issues/79932}: Raise exception if @ref{27d,,frame.clear()} is called on a suspended
frame.

@item 
gh-81925@footnote{https://github.com/python/cpython/issues/81925}: Implement native thread ids for GNU KFreeBSD.

@item 
gh-111843@footnote{https://github.com/python/cpython/issues/111843}: Use exponential backoff to reduce the number of failed tier 2
optimization attempts by over 99%.

@item 
gh-110829@footnote{https://github.com/python/cpython/issues/110829}: Joining a thread now ensures the underlying OS thread has
exited. This is required for safer fork() in multi-threaded processes.

@item 
gh-109369@footnote{https://github.com/python/cpython/issues/109369}: Make sure that tier 2 traces are de-optimized if the code is
instrumented

@item 
gh-111772@footnote{https://github.com/python/cpython/issues/111772}: Specialize slot loads and stores for _Py_T_OBJECT as well as
Py_T_OBJECT_EX

@item 
gh-111666@footnote{https://github.com/python/cpython/issues/111666}: Speed up @ref{1649,,BaseExceptionGroup.derive()},
@ref{164a,,BaseExceptionGroup.subgroup()}, and @ref{150f,,BaseExceptionGroup.split()}
by changing how they parse passed arguments.

@item 
gh-111654@footnote{https://github.com/python/cpython/issues/111654}: Fix runtime crash when some error happens in opcode
@code{LOAD_FROM_DICT_OR_DEREF}.

@item 
gh-111623@footnote{https://github.com/python/cpython/issues/111623}: Add support for sharing tuples between interpreters using the
cross-interpreter API.  Patch by Anthony Shaw.

@item 
gh-111354@footnote{https://github.com/python/cpython/issues/111354}: The oparg of @ref{309,,YIELD_VALUE} is now @code{1} if the
instruction is part of a yield-from or await, and @code{0} otherwise.

The SUSPENDED frame state is now split into @code{SUSPENDED} and
@code{SUSPENDED_YIELD_FROM}. This simplifies the code in @code{_PyGen_yf}.

@item 
gh-111520@footnote{https://github.com/python/cpython/issues/111520}: Merge the Tier 1 (bytecode) and Tier 2 (micro-ops) interpreters
together, moving the Tier 2 interpreter loop and switch into
@code{_PyEval_EvalFrameDefault()} in @code{Python/ceval.c}. The
@code{Python/executor.c} file is gone. Also the @code{TIER_ONE} and @code{TIER_TWO}
macros are now handled by the code generator.

`Beware!' This changes the environment variables to enable micro-ops and
their debugging to @code{PYTHON_UOPS} and @code{PYTHON_LLTRACE}.

@item 
gh-109181@footnote{https://github.com/python/cpython/issues/109181}: Speed up @code{Traceback} object creation by lazily compute
the line number. Patch by Pablo Galindo

@item 
gh-111420@footnote{https://github.com/python/cpython/issues/111420}: Allow type comments in parenthesized @code{with} statements

@item 
gh-111438@footnote{https://github.com/python/cpython/issues/111438}: Add support for sharing floats between interpreters using the
cross-interpreter API.  Patch by Anthony Shaw.

@item 
gh-111435@footnote{https://github.com/python/cpython/issues/111435}: Add support for sharing of @code{True} and @code{False} between
interpreters using the cross-interpreter API.  Patch by Anthony Shaw.

@item 
gh-102388@footnote{https://github.com/python/cpython/issues/102388}: Fix a bug where @code{iso2022_jp_3} and @code{iso2022_jp_2004} codecs
read out of bounds

@item 
gh-111366@footnote{https://github.com/python/cpython/issues/111366}: Fix an issue in the @ref{1c,,codeop} that was causing
@ref{18b,,SyntaxError} exceptions raised in the presence of invalid syntax to
not contain precise error messages. Patch by Pablo Galindo

@item 
gh-111380@footnote{https://github.com/python/cpython/issues/111380}: Fix a bug that was causing @ref{44f,,SyntaxWarning} to appear twice
when parsing if invalid syntax is encountered later. Patch by Pablo
galindo

@item 
gh-111374@footnote{https://github.com/python/cpython/issues/111374}: Added a new environment variable
@geindex PYTHON_FROZEN_MODULES
@geindex variable d'environnement; PYTHON_FROZEN_MODULES
@ref{18c,,PYTHON_FROZEN_MODULES}. It determines whether or not frozen
modules are ignored by the import machinery, equivalent of the @ref{175,,-X frozen_modules} command-line option.

@item 
gh-111354@footnote{https://github.com/python/cpython/issues/111354}: Remove @code{oparg} from @ref{309,,YIELD_VALUE}. Change @code{oparg}
of @ref{30a,,RESUME} to include information about the except-depth. These
changes make it possible to simplify the code in generator close.

@item 
gh-94438@footnote{https://github.com/python/cpython/issues/94438}: Fix a regression that prevented jumping across @code{is None} and
@code{is not None} when debugging. Patch by Savannah Ostrowski.

@item 
gh-67224@footnote{https://github.com/python/cpython/issues/67224}: Show source lines in tracebacks when using the @code{-c} option
when running Python. Patch by Pablo Galindo

@item 
gh-111123@footnote{https://github.com/python/cpython/issues/111123}: Fix a bug where a @ref{188,,global} declaration in an
@ref{189,,except} block is rejected when the global is used in the
@ref{18a,,else} block.

@item 
gh-110938@footnote{https://github.com/python/cpython/issues/110938}: Fix error messages for indented blocks with functions and
classes with generic type parameters. Patch by Pablo Galindo

@item 
gh-109214@footnote{https://github.com/python/cpython/issues/109214}: Remove unnecessary instruction pointer updates before returning
from frames.

@item 
gh-110912@footnote{https://github.com/python/cpython/issues/110912}: Correctly display the traceback for @ref{164b,,MemoryError}
exceptions using the @ref{fd,,traceback} module. Patch by Pablo Galindo

@item 
gh-109894@footnote{https://github.com/python/cpython/issues/109894}: Fixed crash due to improperly initialized static
@ref{164b,,MemoryError} in subinterpreter.

@item 
gh-110892@footnote{https://github.com/python/cpython/issues/110892}: Return @code{NULL} for @code{PyTrace_RETURN} events caused by an
exception

@item 
gh-110864@footnote{https://github.com/python/cpython/issues/110864}: Fix argument parsing by @code{_PyArg_UnpackKeywordsWithVararg} for
functions defining pos-or-keyword, vararg, and kw-only parameters.

@item 
gh-109094@footnote{https://github.com/python/cpython/issues/109094}: Replace @code{prev_instr} on the interpreter frame by
@code{instr_ptr} which points to the beginning of the instruction that is
currently executing (or will execute once the frame resumes).

@item 
gh-110805@footnote{https://github.com/python/cpython/issues/110805}: Allow the repl to show source code and complete tracebacks.
Patch by Pablo Galindo

@item 
gh-110722@footnote{https://github.com/python/cpython/issues/110722}: Add 
@geindex PYTHON_PRESITE=package.module
@geindex variable d'environnement; PYTHON_PRESITE=package.module
@code{PYTHON_PRESITE=package.module} to import a module
early in the interpreter lifecycle before @code{site.py} is executed.  Python
needs to be @ref{1f6,,built in debug mode} for this option to
exist.

@item 
gh-110481@footnote{https://github.com/python/cpython/issues/110481}: Implement biased reference counting in @code{--disable-gil}
builds.

@item 
gh-110543@footnote{https://github.com/python/cpython/issues/110543}: Fix regression in Python 3.12 where
@code{types.CodeType.replace()} would produce a broken code object if
called on a module or class code object that contains a comprehension.
Patch by Jelle Zijlstra.

@item 
gh-89519@footnote{https://github.com/python/cpython/issues/89519}: Removed chained @ref{165,,classmethod} descriptors (introduced in
bpo-19072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19072}).  This can no longer be used to wrap other descriptors
such as @ref{192,,property}.  The core design of this feature was flawed and
caused a number of downstream problems.  To "pass-through" a
@ref{165,,classmethod}, consider using the @code{__wrapped__} attribute
that was added in Python 3.10.

@item 
gh-103615@footnote{https://github.com/python/cpython/issues/103615}: Use local events for opcode tracing

@item 
bpo-46657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46657}: Add mimalloc memory allocator support.

@item 
gh-106718@footnote{https://github.com/python/cpython/issues/106718}: When PyConfig.stdlib_dir is explicitly set, it's now respected
and won't be overridden by PyConfig.home.

@item 
gh-106905@footnote{https://github.com/python/cpython/issues/106905}: Fix incorrect SystemError about AST constructor recursion depth
mismatch.

@item 
gh-100445@footnote{https://github.com/python/cpython/issues/100445}: Improve error message for unterminated strings with escapes.

@item 
bpo-45759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45759}: Improved error messages for @code{elif}/@code{else} statements not
matching any valid statements. Patch by Jeremiah Vivian.
@end itemize

@node Library<14>,Tests<12>,Core and Builtins<15>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id104}@anchor{164c}
@subsubsection Library



@itemize -

@item 
gh-111942@footnote{https://github.com/python/cpython/issues/111942}: Fix SystemError in the TextIOWrapper constructor with
non-encodable "errors" argument in non-debug mode.

@item 
gh-111995@footnote{https://github.com/python/cpython/issues/111995}: Added the @code{NI_IDN} constant to the @ref{cb,,socket} module when
present in C at build time for use with @ref{164d,,socket.getnameinfo()}.

@item 
gh-109538@footnote{https://github.com/python/cpython/issues/109538}: Issue warning message instead of having @ref{193,,RuntimeError}
be displayed when event loop has already been closed at
@code{StreamWriter.__del__()}.

@item 
gh-111942@footnote{https://github.com/python/cpython/issues/111942}: Fix crashes in @ref{b37,,io.TextIOWrapper.reconfigure()} when pass
invalid arguments, e.g. non-string encoding.

@item 
gh-111460@footnote{https://github.com/python/cpython/issues/111460}: @ref{2b,,curses}: restore wide character support (including
@ref{1081,,curses.unget_wch()} and @ref{1080,,get_wch()}) on macOS,
which was unavailable due to a regression in Python 3.12.

@item 
gh-103791@footnote{https://github.com/python/cpython/issues/103791}: @ref{f11,,contextlib.suppress} now supports suppressing
exceptions raised as part of a @ref{25c,,BaseExceptionGroup}, in addition to
the recent support for @ref{1b4,,ExceptionGroup}.

@item 
gh-111835@footnote{https://github.com/python/cpython/issues/111835}: The @ref{208,,mmap.mmap} class now has an
@ref{209,,seekable()} method that can be used when a seekable
file-like object is required. The @ref{20a,,seek()} method now
returns the new absolute position. Patch by Donghee Na.

@item 
gh-111804@footnote{https://github.com/python/cpython/issues/111804}: Remove posix.fallocate() under WASI as the underlying
posix_fallocate() is not available in WASI preview2.

@item 
gh-111841@footnote{https://github.com/python/cpython/issues/111841}: Fix truncating arguments on an embedded null character in
@ref{909,,os.putenv()} and @ref{908,,os.unsetenv()} on Windows.

@item 
gh-111768@footnote{https://github.com/python/cpython/issues/111768}: @ref{164e,,wsgiref.util.is_hop_by_hop()} is now exposed correctly in
@code{__all__}.

@item 
gh-80731@footnote{https://github.com/python/cpython/issues/80731}: Avoid executing the default function in @ref{164f,,cmd.Cmd} in an
except block

@item 
gh-111541@footnote{https://github.com/python/cpython/issues/111541}: Fix @ref{3a,,doctest} for @ref{18b,,SyntaxError} not-builtin
subclasses.

@item 
gh-111719@footnote{https://github.com/python/cpython/issues/111719}: Add extra argument validation for @code{alias} command in
@ref{a4,,pdb}

@item 
gh-111482@footnote{https://github.com/python/cpython/issues/111482}: @ref{ed,,time}: Make @ref{113e,,time.clock_gettime()} and
@ref{ad0,,time.clock_gettime_ns()} functions up to 2x faster by faster calling
convention. Patch by Victor Stinner.

@item 
gh-110894@footnote{https://github.com/python/cpython/issues/110894}: Call loop exception handler for exceptions in
@code{client_connected_cb} of @ref{b07,,asyncio.start_server()} so that
applications can handle it. Patch by Kumar Aditya.

@item 
gh-111531@footnote{https://github.com/python/cpython/issues/111531}: Fix reference leaks in @code{bind_class()} and @code{bind_all()}
methods of @ref{ef,,tkinter} widgets.

@item 
gh-111246@footnote{https://github.com/python/cpython/issues/111246}: @ref{1ac,,asyncio.loop.create_unix_server()} will now automatically
remove the Unix socket when the server is closed.

@item 
gh-111356@footnote{https://github.com/python/cpython/issues/111356}: Added @ref{1650,,io.text_encoding()}, @ref{1651,,io.DEFAULT_BUFFER_SIZE},
and @ref{1652,,io.IncrementalNewlineDecoder} to @code{io.__all__}.

@item 
gh-66425@footnote{https://github.com/python/cpython/issues/66425}: Remove the code to set the REMOTE_HOST header from wsgiref
module, as it is unreachable. This header is used for performance reasons,
which is not necessary in the wsgiref module.

@item 
gh-111429@footnote{https://github.com/python/cpython/issues/111429}: Speed up @ref{2c8,,pathlib.PurePath.relative_to()} and
@ref{2c7,,is_relative_to()}.

@item 
gh-111342@footnote{https://github.com/python/cpython/issues/111342}: Fixed typo in @ref{481,,math.sumprod()}.

@item 
gh-68166@footnote{https://github.com/python/cpython/issues/68166}: Remove mention of not supported "vsapi" element type in
@ref{255,,tkinter.ttk.Style.element_create()}. Add tests for
@code{element_create()} and other @code{ttk.Style} methods. Add examples for
@code{element_create()} in the documentation.

@item 
gh-111388@footnote{https://github.com/python/cpython/issues/111388}: Add @code{show_group} parameter to
@ref{838,,traceback.format_exception_only()}, which allows to format
@ref{1b4,,ExceptionGroup} instances.

@item 
gh-79033@footnote{https://github.com/python/cpython/issues/79033}: Another attempt at fixing @ref{1653,,asyncio.Server.wait_closed()}. It
now blocks until both conditions are true: the server is closed, `and'
there are no more active connections. (This means that in some cases where
in 3.12.0 this function would `incorrectly' have returned immediately, it
will now block; in particular, when there are no active connections but
the server hasn't been closed yet.)

@item 
gh-111259@footnote{https://github.com/python/cpython/issues/111259}: Optimize recursive wildcards in @ref{a3,,pathlib}.

@item 
gh-111295@footnote{https://github.com/python/cpython/issues/111295}: Fix @ref{ed,,time} not checking for errors when initializing.

@item 
gh-111253@footnote{https://github.com/python/cpython/issues/111253}: Add error checking during @code{_socket} module init.

@item 
gh-111251@footnote{https://github.com/python/cpython/issues/111251}: Fix @code{_blake2} not checking for errors when initializing.

@item 
gh-111233@footnote{https://github.com/python/cpython/issues/111233}: Fix @ref{c0,,select} not checking for errors when initializing.

@item 
gh-111230@footnote{https://github.com/python/cpython/issues/111230}: Fix @ref{cf,,ssl} not checking for errors when initializing.

@item 
gh-111174@footnote{https://github.com/python/cpython/issues/111174}: Fix crash in @ref{11ce,,io.BytesIO.getbuffer()} called repeatedly for
empty BytesIO.

@item 
gh-111187@footnote{https://github.com/python/cpython/issues/111187}: Postpone removal version for locale.getdefaultlocale() to
Python 3.15.

@item 
gh-111159@footnote{https://github.com/python/cpython/issues/111159}: Fix @ref{3a,,doctest} output comparison for exceptions with notes.

@item 
gh-110910@footnote{https://github.com/python/cpython/issues/110910}: Fix invalid state handling in @ref{1b3,,asyncio.TaskGroup} and
@ref{1654,,asyncio.Timeout}. They now raise proper RuntimeError if they are
improperly used and are left in consistent state after this.

@item 
gh-111092@footnote{https://github.com/python/cpython/issues/111092}: Make turtledemo run without default root enabled.

@item 
gh-110944@footnote{https://github.com/python/cpython/issues/110944}: Support alias and convenience vars for @ref{a4,,pdb} completion

@item 
gh-110745@footnote{https://github.com/python/cpython/issues/110745}: Added `newline' parameter to @ref{e32,,pathlib.Path.read_text()}.
Patch by Junya Okabe.

@item 
gh-84583@footnote{https://github.com/python/cpython/issues/84583}: Make @ref{a4,,pdb} enter post-mortem mode even for
@ref{18b,,SyntaxError}

@item 
gh-80675@footnote{https://github.com/python/cpython/issues/80675}: Set @code{f_trace_lines = True} on all frames upon
@ref{232,,pdb.set_trace()}

@item 
gh-110771@footnote{https://github.com/python/cpython/issues/110771}: Expose the setup and cleanup portions of
@code{asyncio.run_forever()} as the standalone methods
@code{asyncio.run_forever_setup()} and @code{asyncio.run_forever_cleanup()}.
This allows for tighter integration with GUI event loops.

@item 
gh-110774@footnote{https://github.com/python/cpython/issues/110774}: Support setting the @ref{5eb,,asyncio.Runner} loop_factory kwarg
in @ref{301,,unittest.IsolatedAsyncioTestCase}

@item 
gh-110392@footnote{https://github.com/python/cpython/issues/110392}: Fix @ref{1655,,tty.setraw()} and @ref{1601,,tty.setcbreak()}: previously
they returned partially modified list of the original tty attributes.
@ref{1656,,tty.cfmakeraw()} and @ref{1602,,tty.cfmakecbreak()} now make a copy of the
list of special characters before modifying it.

@item 
gh-59013@footnote{https://github.com/python/cpython/issues/59013}: Make line number of function breakpoint more precise in
@ref{a4,,pdb}

@item 
gh-88434@footnote{https://github.com/python/cpython/issues/88434}: Emit deprecation warning for non-integer numbers in
@ref{62,,gettext} functions and methods that consider plural forms even if
the translation was not found.

@item 
gh-110395@footnote{https://github.com/python/cpython/issues/110395}: Ensure that @ref{1657,,select.kqueue()} objects correctly appear as
closed in forked children, to prevent operations on an invalid file
descriptor.

@item 
gh-110196@footnote{https://github.com/python/cpython/issues/110196}: Add @code{__reduce__} method to @code{IPv6Address} in order to
keep @code{scope_id}

@item 
gh-109747@footnote{https://github.com/python/cpython/issues/109747}: Improve errors for unsupported look-behind patterns. Now
re.error is raised instead of OverflowError or RuntimeError for too large
width of look-behind pattern.

@item 
gh-109466@footnote{https://github.com/python/cpython/issues/109466}: Add the @ref{1f8,,ipaddress.IPv4Address.ipv6_mapped} property,
which returns the IPv4-mapped IPv6 address.

@item 
gh-85098@footnote{https://github.com/python/cpython/issues/85098}: Implement the CLI of the @ref{d7,,symtable} module and improve the
repr of @ref{1658,,Symbol}.

@item 
gh-108791@footnote{https://github.com/python/cpython/issues/108791}: Improved error handling in @ref{a4,,pdb} command line interface,
making it produce more concise error messages.

@item 
gh-105931@footnote{https://github.com/python/cpython/issues/105931}: Change @ref{20,,compileall} to only strip the stripdir prefix from
the full path recorded in the compiled @code{.pyc} file, when the prefix
matches the start of the full path in its entirety. When the prefix does
not match, no stripping is performed and a warning to this effect is
displayed.

Previously all path components of the stripdir prefix that matched the
full path were removed, while those that did not match were left alone
(including ones interspersed between matching components).

@item 
gh-107431@footnote{https://github.com/python/cpython/issues/107431}: Make the @code{DictProxy} and @code{ListProxy} types in
@ref{96,,multiprocessing.managers} @ref{69d,,Generic Alias Types} for @code{[]} use in typing contexts.

@item 
gh-72904@footnote{https://github.com/python/cpython/issues/72904}: Add @ref{1e7,,glob.translate()}. This function converts a pathname
with shell-style wildcards to a regular expression.

@item 
gh-90026@footnote{https://github.com/python/cpython/issues/90026}: Define @code{USE_XATTRS} on Cygwin so that XATTR-related functions
in the @ref{a0,,os} module become available.

@item 
gh-90890@footnote{https://github.com/python/cpython/issues/90890}: New methods @ref{1659,,mailbox.Maildir.get_info()},
@ref{165a,,mailbox.Maildir.set_info()}, @ref{165b,,mailbox.Maildir.get_flags()},
@ref{165c,,mailbox.Maildir.set_flags()}, @ref{165d,,mailbox.Maildir.add_flag()},
@ref{165e,,mailbox.Maildir.remove_flag()}. These methods speed up accessing a
message's info and/or flags and are useful when it is not necessary to
access the message's contents, as when iterating over a Maildir to find
messages with specific flags.

@item 
gh-102956@footnote{https://github.com/python/cpython/issues/102956}: Fix returning of empty byte strings after seek in zipfile
module

@item 
gh-102895@footnote{https://github.com/python/cpython/issues/102895}: Added a parameter @code{local_exit} for @ref{165f,,code.interact()} to
prevent @code{exit()} and @code{quit} from closing @code{sys.stdin} and raise
@code{SystemExit}.

@item 
gh-97928@footnote{https://github.com/python/cpython/issues/97928}: Change the behavior of @code{tkinter.Text.count()}. It now always
returns an integer if one or less counting options are specified.
Previously it could return a single count as a 1-tuple, an integer (only
if option @code{"update"} was specified) or @code{None} if no items found. The
result is now the same if @code{wantobjects} is set to @code{0}.

@item 
gh-96954@footnote{https://github.com/python/cpython/issues/96954}: Switch the storage of the unicode codepoint names to use a
different data-structure, a directed acyclic word graph@footnote{https://en.wikipedia.org/wiki/Deterministic_acyclic_finite_state_automaton}.
This makes the unicodedata shared library about 440 KiB smaller.
Contributed by Carl Friedrich Bolz-Tereick using code from the PyPy
project.

@item 
gh-73561@footnote{https://github.com/python/cpython/issues/73561}: Omit the interface scope from an IPv6 address when used as Host
header by @ref{6e,,http.client}.

@item 
gh-86826@footnote{https://github.com/python/cpython/issues/86826}: @code{zipinfo} now supports the full range of values in the TZ
string determined by RFC 8536 and detects all invalid formats. Both Python
and C implementations now raise exceptions of the same type on invalid
data.
@end itemize

@node Tests<12>,Build<14>,Library<14>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id105}@anchor{1660}
@subsubsection Tests



@itemize -

@item 
gh-111808@footnote{https://github.com/python/cpython/issues/111808}: Make the default value of @code{test.support.infinite_recursion()}
to be conditional based on whether optimizations were used when compiling
the interpreter. This helps with platforms like WASI whose stack size is
greatly restricted in debug builds.

@item 
gh-110722@footnote{https://github.com/python/cpython/issues/110722}: Gathering line coverage of standard libraries within the
regression test suite is now precise, as well as much faster. Patch by
Łukasz Langa.

@item 
gh-110367@footnote{https://github.com/python/cpython/issues/110367}: Make regrtest @code{--verbose3} option compatible with
@code{--huntrleaks -jN} options. The @code{./python -m test -j1 -R 3:3
--verbose3} command now works as expected. Patch by Victor Stinner.

@item 
gh-111165@footnote{https://github.com/python/cpython/issues/111165}: Remove no longer used functions @code{run_unittest()} and
@code{run_doctest()} from the @ref{e3,,test.support} module.

@item 
gh-110932@footnote{https://github.com/python/cpython/issues/110932}: Fix regrtest if the @code{SOURCE_DATE_EPOCH} environment variable
is defined: use the variable value as the random seed. Patch by Victor
Stinner.

@item 
gh-110995@footnote{https://github.com/python/cpython/issues/110995}: test_gdb: Fix detection of gdb built without Python scripting
support. Patch by Victor Stinner.

@item 
gh-110918@footnote{https://github.com/python/cpython/issues/110918}: Test case matching patterns specified by options @code{--match},
@code{--ignore}, @code{--matchfile} and @code{--ignorefile} are now tested in the
order of specification, and the last match determines whether the test
case be run or ignored.

@item 
gh-108747@footnote{https://github.com/python/cpython/issues/108747}: Add unit test for @code{usercustomize} and @code{sitecustomize} hooks
from @ref{c6,,site}.
@end itemize

@node Build<14>,Windows<11>,Tests<12>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id106}@anchor{1661}
@subsubsection Build



@itemize -

@item 
gh-96954@footnote{https://github.com/python/cpython/issues/96954}: Make @code{make regen-unicodedata} work for out-of-tree builds of
CPython.

@item 
gh-112088@footnote{https://github.com/python/cpython/issues/112088}: Add @code{Tools/build/regen-configure.sh} script to regenerate the
@code{configure} with an Ubuntu container image. The
@code{quay.io/tiran/cpython_autoconf:271} container image
(tiran/cpython_autoconf@footnote{https://github.com/tiran/cpython_autoconf}) is
no longer used. Patch by Victor Stinner.

@item 
gh-111046@footnote{https://github.com/python/cpython/issues/111046}: For wasi-threads, memory is now exported to fix compatibility
issues with some wasm runtimes.

@item 
gh-110828@footnote{https://github.com/python/cpython/issues/110828}: AIX 32bit needs @code{-latomic} to build the @code{_testcapi}
extension module.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: The @code{errno}, @code{md5}, @code{resource}, @code{winsound},
@code{_ctypes_test}, @code{_multiprocessing.posixshmem}, @code{_scproxy},
@code{_stat}, @code{_testimportmultiple} and @code{_uuid} C extensions are now
built with the @ref{38c,,limited C API}. Patch by Victor
Stinner.
@end itemize

@node Windows<11>,macOS<8>,Build<14>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id107}@anchor{1662}
@subsubsection Windows



@itemize -

@item 
gh-111856@footnote{https://github.com/python/cpython/issues/111856}: Fixes @ref{d79,,fstat()} on file systems that do not support
file ID requests. This includes FAT32 and exFAT.

@item 
gh-111293@footnote{https://github.com/python/cpython/issues/111293}: Fix @ref{1663,,os.DirEntry.inode} dropping higher 64 bits of a file
id on some filesystems on Windows.

@item 
gh-110913@footnote{https://github.com/python/cpython/issues/110913}: WindowsConsoleIO now correctly chunks large buffers without
splitting up UTF-8 sequences.
@end itemize

@node macOS<8>,IDLE<12>,Windows<11>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id108}@anchor{1664}
@subsubsection macOS



@itemize -

@item 
gh-59703@footnote{https://github.com/python/cpython/issues/59703}: For macOS framework builds, in @code{getpath.c} use the system
@code{dladdr} function to find the path to the shared library rather than
depending on deprecated macOS APIs.

@item 
gh-110950@footnote{https://github.com/python/cpython/issues/110950}: Update macOS installer to include an upstream Tcl/Tk fix for
the @code{Secure coding is not enabled for restorable state!} warning
encountered in Tkinter on macOS 14 Sonoma.

@item 
gh-111015@footnote{https://github.com/python/cpython/issues/111015}: Ensure that IDLE.app and Python Launcher.app are installed with
appropriate permissions on macOS builds.

@item 
gh-71383@footnote{https://github.com/python/cpython/issues/71383}: Update macOS installer to include an upstream Tcl/Tk fix for the
@code{ttk::ThemeChanged} error encountered in Tkinter.

@item 
gh-92603@footnote{https://github.com/python/cpython/issues/92603}: Update macOS installer to include a fix accepted by upstream
Tcl/Tk for a crash encountered after the first @ref{15bf,,tkinter.Tk()} instance
is destroyed.
@end itemize

@node IDLE<12>,Tools/Demos<6>,macOS<8>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id109}@anchor{1665}
@subsubsection IDLE



@itemize -

@item 
bpo-35668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35668}: Add docstrings to the IDLE debugger module. Fix two bugs:
initialize @code{Idb.botframe} (should be in Bdb); in @code{Idb.in_rpc_code},
check whether @code{prev_frame} is @code{None} before trying to use it. Greatly
expand test_debugger.
@end itemize

@node Tools/Demos<6>,C API<14>,IDLE<12>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id110}@anchor{1666}
@subsubsection Tools/Demos



@itemize -

@item 
gh-111903@footnote{https://github.com/python/cpython/issues/111903}: Argument Clinic now supports the @code{@@critical_section}
directive that instructs Argument Clinic to generate a critical section
around the function call, which locks the @code{self} object in
@code{--disable-gil} builds. Patch by Sam Gross.
@end itemize

@node C API<14>,,Tools/Demos<6>,Python 3 13 0 alpha 2
@anchor{whatsnew/changelog id111}@anchor{1667}
@subsubsection C API



@itemize -

@item 
gh-112026@footnote{https://github.com/python/cpython/issues/112026}: Add again the private @code{_PyThreadState_UncheckedGet()}
function as an alias to the new public
@ref{367,,PyThreadState_GetUnchecked()} function. Patch by Victor Stinner.

@item 
gh-112026@footnote{https://github.com/python/cpython/issues/112026}: Restore the removed @code{_PyDict_GetItemStringWithError()}
function. It is used by numpy. Patch by Victor Stinner.

@item 
gh-112026@footnote{https://github.com/python/cpython/issues/112026}: Restore removed private C API functions, macros and structures
which have no simple replacement for now:


@itemize *

@item 
_PyDict_GetItem_KnownHash()

@item 
_PyDict_NewPresized()

@item 
_PyHASH_BITS

@item 
_PyHASH_IMAG

@item 
_PyHASH_INF

@item 
_PyHASH_MODULUS

@item 
_PyHASH_MULTIPLIER

@item 
_PyLong_Copy()

@item 
_PyLong_FromDigits()

@item 
_PyLong_New()

@item 
_PyLong_Sign()

@item 
_PyObject_CallMethodId()

@item 
_PyObject_CallMethodNoArgs()

@item 
_PyObject_CallMethodOneArg()

@item 
_PyObject_CallOneArg()

@item 
_PyObject_EXTRA_INIT

@item 
_PyObject_FastCallDict()

@item 
_PyObject_GetAttrId()

@item 
_PyObject_Vectorcall()

@item 
_PyObject_VectorcallMethod()

@item 
_PyStack_AsDict()

@item 
_PyThread_CurrentFrames()

@item 
_PyUnicodeWriter structure

@item 
_PyUnicodeWriter_Dealloc()

@item 
_PyUnicodeWriter_Finish()

@item 
_PyUnicodeWriter_Init()

@item 
_PyUnicodeWriter_Prepare()

@item 
_PyUnicodeWriter_PrepareKind()

@item 
_PyUnicodeWriter_WriteASCIIString()

@item 
_PyUnicodeWriter_WriteChar()

@item 
_PyUnicodeWriter_WriteLatin1String()

@item 
_PyUnicodeWriter_WriteStr()

@item 
_PyUnicodeWriter_WriteSubstring()

@item 
_PyUnicode_AsString()

@item 
_PyUnicode_FromId()

@item 
_PyVectorcall_Function()

@item 
_Py_IDENTIFIER()

@item 
_Py_c_abs()

@item 
_Py_c_diff()

@item 
_Py_c_neg()

@item 
_Py_c_pow()

@item 
_Py_c_prod()

@item 
_Py_c_quot()

@item 
_Py_c_sum()

@item 
_Py_static_string()

@item 
_Py_static_string_init()
@end itemize

Patch by Victor Stinner.

@item 
gh-112026@footnote{https://github.com/python/cpython/issues/112026}: Add again @code{<ctype.h>} and @code{<unistd.h>} includes in
@code{Python.h}, but don't include them in the limited C API version 3.13 and
newer. Patch by Victor Stinner.

@item 
gh-111956@footnote{https://github.com/python/cpython/issues/111956}: Add internal-only one-time initialization API: @code{_PyOnceFlag}
and @code{_PyOnceFlag_CallOnce}.

@item 
gh-111262@footnote{https://github.com/python/cpython/issues/111262}: Add @ref{337,,PyDict_Pop()} and @ref{338,,PyDict_PopString()}
functions: remove a key from a dictionary and optionally return the
removed value. This is similar to @ref{339,,dict.pop()}, but without the
default value and not raising @ref{33a,,KeyError} if the key missing. Patch by
Stefan Behnel and Victor Stinner.

@item 
gh-111863@footnote{https://github.com/python/cpython/issues/111863}: Rename @code{Py_NOGIL} to @code{Py_GIL_DISABLED}. Patch by Hugo van
Kemenade.

@item 
gh-111138@footnote{https://github.com/python/cpython/issues/111138}: Add @ref{353,,PyList_Extend()} and @ref{354,,PyList_Clear()}
functions: similar to Python @code{list.extend()} and @code{list.clear()}
methods. Patch by Victor Stinner.

@item 
gh-108765@footnote{https://github.com/python/cpython/issues/108765}: On Windows, @code{Python.h} no longer includes the @code{<stddef.h>}
standard header file. If needed, it should now be included explicitly.
Patch by Victor Stinner.

@item 
gh-111569@footnote{https://github.com/python/cpython/issues/111569}: Implement "Python Critical Sections" from 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}. These are
macros to help replace the GIL with per-object locks in the
@code{--disable-gil} build of CPython. The macros are no-ops in the default
build.

@item 
gh-111506@footnote{https://github.com/python/cpython/issues/111506}: In the limited C API version 3.13, @ref{897,,Py_SET_REFCNT()}
function is now implemented as an opaque function call. Patch by Victor
Stinner.

@item 
gh-108082@footnote{https://github.com/python/cpython/issues/108082}: Add @ref{344,,PyErr_FormatUnraisable()} function.

@item 
gh-110964@footnote{https://github.com/python/cpython/issues/110964}: Move the undocumented private _PyArg functions and
_PyArg_Parser structure to internal C API (@code{pycore_modsupport.h}). Patch
by Victor Stinner.

@item 
gh-110815@footnote{https://github.com/python/cpython/issues/110815}: Support non-ASCII keyword names in
@ref{379,,PyArg_ParseTupleAndKeywords()}.

@item 
gh-109587@footnote{https://github.com/python/cpython/issues/109587}: Introduced @code{PyUnstable_PerfTrampoline_CompileCode()},
@code{PyUnstable_PerfTrampoline_SetPersistAfterFork()} and
@code{PyUnstable_CopyPerfMapFile()}. These functions allow extension
modules to initialize trampolines eagerly, after the application is
"warmed up". This makes it possible to have perf-trampolines running in an
always-enabled fashion.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: Add the @ref{365,,PySys_Audit()} function to the limited C API.
Patch by Victor Stinner.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: Add @ref{386,,PyMem_RawMalloc()}, @ref{387,,PyMem_RawCalloc()},
@ref{388,,PyMem_RawRealloc()} and @ref{389,,PyMem_RawFree()} to the limited C
API. Patch by Victor Stinner.

@item 
gh-106672@footnote{https://github.com/python/cpython/issues/106672}: Functions @ref{37d,,PyDict_GetItem()},
@ref{37e,,PyDict_GetItemString()}, @ref{375,,PyMapping_HasKey()},
@ref{377,,PyMapping_HasKeyString()}, @ref{371,,PyObject_HasAttr()},
@ref{373,,PyObject_HasAttrString()}, and @ref{37f,,PySys_GetObject()}, which
clear all errors occurred during calling the function, report now them
using @ref{1f4,,sys.unraisablehook()}.

@item 
gh-67565@footnote{https://github.com/python/cpython/issues/67565}: Remove redundant C-contiguity check in @code{getargs.c},
@ref{10,,binascii}, @ref{cf,,ssl} and Argument Clinic. Patched by Stefan Krah
and Furkan Onder
@end itemize

@node Python 3 13 0 alpha 1,Python 3 12 0 beta 1,Python 3 13 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-13-0-alpha-1}@anchor{1668}
@subsection Python 3.13.0 alpha 1


`Release date: 2023-10-13'

@menu
* Security: Security<10>. 
* Core and Builtins: Core and Builtins<16>. 
* Library: Library<15>. 
* Documentation: Documentation<10>. 
* Tests: Tests<13>. 
* Build: Build<15>. 
* Windows: Windows<12>. 
* macOS: macOS<9>. 
* IDLE: IDLE<13>. 
* Tools/Demos: Tools/Demos<7>. 
* C API: C API<15>. 

@end menu

@node Security<10>,Core and Builtins<16>,,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id112}@anchor{1669}
@subsubsection Security



@itemize -

@item 
gh-108310@footnote{https://github.com/python/cpython/issues/108310}: Fixed an issue where instances of @ref{8d7,,ssl.SSLSocket} were
vulnerable to a bypass of the TLS handshake and included protections (like
certificate verification) and treating sent unencrypted data as if it were
post-handshake TLS encrypted data.  Security issue reported as
@geindex Common Vulnerabilities and Exposures; CVE 2023-40217
CVE 2023-40217@footnote{https://www.cve.org/CVERecord?id=CVE-2023-40217} by Aapo Oksman. Patch by Gregory P. Smith.

@item 
gh-107774@footnote{https://github.com/python/cpython/issues/107774}: PEP 669 specifies that @code{sys.monitoring.register_callback}
will generate an audit event. Pre-releases of Python 3.12 did not generate
the audit event. This is now fixed.

@item 
gh-102988@footnote{https://github.com/python/cpython/issues/102988}: Reverted the @ref{50,,email.utils} security improvement change
released in 3.12beta4 that unintentionally caused
@ref{1de,,email.utils.getaddresses} to fail to parse email addresses with a
comma in the quoted name field. See gh-106669@footnote{https://github.com/python/cpython/issues/106669}.

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Refresh our new HACL* built-in @ref{67,,hashlib} code from
upstream. Built-in SHA2 should be faster and an issue with SHA3 on 32-bit
platforms is fixed.

@item 
gh-102509@footnote{https://github.com/python/cpython/issues/102509}: Start initializing @code{ob_digit} during creation of
@ref{574,,PyLongObject} objects. Patch by Illia Volochii.
@end itemize

@node Core and Builtins<16>,Library<15>,Security<10>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id113}@anchor{166a}
@subsubsection Core and Builtins



@itemize -

@item 
gh-110782@footnote{https://github.com/python/cpython/issues/110782}: Fix crash when @ref{15c,,typing.TypeVar} is constructed with a
keyword argument. Patch by Jelle Zijlstra.

@item 
gh-110752@footnote{https://github.com/python/cpython/issues/110752}: Reset @code{ceval.eval_breaker} in @code{interpreter_clear()}

@item 
gh-110721@footnote{https://github.com/python/cpython/issues/110721}: Use the @ref{fd,,traceback} implementation for the default
@code{PyErr_Display()} functionality. Patch by Pablo Galindo

@item 
gh-110696@footnote{https://github.com/python/cpython/issues/110696}: Fix incorrect error message for invalid argument unpacking.
Patch by Pablo Galindo

@item 
gh-104169@footnote{https://github.com/python/cpython/issues/104169}: Split the tokenizer into two separate directories: - One part
includes the actual lexeme producing logic and lives in @code{Parser/lexer}.
- The second part wraps the lexer according to the different tokenization
modes   we have (string, utf-8, file, interactive, readline) and lives in
@code{Parser/tokenizer}.

@item 
gh-110688@footnote{https://github.com/python/cpython/issues/110688}: Remove undocumented @code{test_c_api} method from @ref{5c3,,set},
which was only defined for testing purposes under @code{Py_DEBUG}. Now we
have proper CAPI tests.

@item 
gh-104584@footnote{https://github.com/python/cpython/issues/104584}: Fix a reference leak when running with 
@geindex PYTHONUOPS
@geindex variable d'environnement; PYTHONUOPS
@code{PYTHONUOPS} or
@ref{175,,-X uops} enabled.

@item 
gh-110514@footnote{https://github.com/python/cpython/issues/110514}: Add @code{PY_THROW} to @ref{14b5,,sys.setprofile()} events

@item 
gh-110489@footnote{https://github.com/python/cpython/issues/110489}: Optimise @ref{1379,,math.ceil()} when the input is exactly a float,
resulting in about a 10% improvement.

@item 
gh-110455@footnote{https://github.com/python/cpython/issues/110455}: Guard @code{assert(tstate->thread_id > 0)} with @code{#ifndef
HAVE_PTHREAD_STUBS}. This allows for for pydebug builds to work under
WASI which (currently) lacks thread support.

@item 
gh-110309@footnote{https://github.com/python/cpython/issues/110309}: Remove unnecessary empty constant nodes in the ast of f-string
specs.

@item 
gh-110259@footnote{https://github.com/python/cpython/issues/110259}: Correctly identify the format spec in f-strings (with single or
triple quotes) that have multiple lines in the expression part and include
a formatting spec. Patch by Pablo Galindo

@item 
gh-110237@footnote{https://github.com/python/cpython/issues/110237}: Fix missing error checks for calls to @code{PyList_Append} in
@code{_PyEval_MatchClass}.

@item 
gh-110164@footnote{https://github.com/python/cpython/issues/110164}: regrtest: If the @code{SOURCE_DATE_EPOCH} environment variable is
defined, regrtest now disables tests randomization. Patch by Victor
Stinner.

@item 
gh-109889@footnote{https://github.com/python/cpython/issues/109889}: Fix the compiler's redundant NOP detection algorithm to skip
over NOPs with no line number when looking for the next instruction's
lineno.

@item 
gh-109853@footnote{https://github.com/python/cpython/issues/109853}: @code{sys.path[0]} is now set correctly for subinterpreters.

@item 
gh-109923@footnote{https://github.com/python/cpython/issues/109923}: Set line number on the @code{POP_TOP} that follows a
@code{RETURN_GENERATOR}.

@item 
gh-105716@footnote{https://github.com/python/cpython/issues/105716}: Subinterpreters now correctly handle the case where they have
threads running in the background.  Before, such threads would interfere
with cleaning up and destroying them, as well as prevent running another
script.

@item 
gh-109369@footnote{https://github.com/python/cpython/issues/109369}: The internal eval_breaker and supporting flags, plus the
monitoring version have been merged into a single atomic integer to speed
up checks.

@item 
gh-109823@footnote{https://github.com/python/cpython/issues/109823}: Fix bug where compiler does not adjust labels when removing an
empty basic block which is a jump target.

@item 
gh-109793@footnote{https://github.com/python/cpython/issues/109793}: The main thread no longer exits prematurely when a
subinterpreter is cleaned up during runtime finalization.  The bug was a
problem particularly because, when triggered, the Python process would
always return with a 0 exitcode, even if it failed.

@item 
gh-109719@footnote{https://github.com/python/cpython/issues/109719}: Fix missing jump target labels when compiler reorders cold/warm
blocks.

@item 
gh-109595@footnote{https://github.com/python/cpython/issues/109595}: Add @ref{175,,-X cpu_count}  command line option to
override return results of @ref{1c0,,os.cpu_count()} and
@ref{1bf,,os.process_cpu_count()}. This option is useful for users who need to
limit CPU resources of a container system without having to modify the
container (application code). Patch by Donghee Na.

@item 
gh-109627@footnote{https://github.com/python/cpython/issues/109627}: Fix bug where the compiler does not assign a new jump target
label to a duplicated small exit block.

@item 
gh-109596@footnote{https://github.com/python/cpython/issues/109596}: Fix some tokens in the grammar that were incorrectly marked as
soft keywords. Also fix some repeated rule names and ensure that repeated
rules are not allowed. Patch by Pablo Galindo

@item 
gh-109496@footnote{https://github.com/python/cpython/issues/109496}: On a Python built in debug mode, @ref{55b,,Py_DECREF()} now
calls @code{_Py_NegativeRefcount()} if the object is a dangling pointer to
deallocated memory: memory filled with @code{0xDD} "dead byte" by the debug
hook on memory allocators. The fix is to check the reference count
`before' checking for @code{_Py_IsImmortal()}. Patch by Victor Stinner.

@item 
gh-107265@footnote{https://github.com/python/cpython/issues/107265}: Deopt opcodes hidden by the executor when base opcode is needed

@item 
gh-109371@footnote{https://github.com/python/cpython/issues/109371}: Deopted instructions correctly for tool initialization and
modified the incorrect assertion in instrumentation, when a previous tool
already sets INSTRUCTION events

@item 
gh-105658@footnote{https://github.com/python/cpython/issues/105658}: Fix bug where the line trace of an except block ending with a
conditional includes an excess event with the line of the conditional
expression.

@item 
gh-109219@footnote{https://github.com/python/cpython/issues/109219}: Fix compiling type param scopes that use a name which is also
free in an inner scope.

@item 
gh-109351@footnote{https://github.com/python/cpython/issues/109351}: Fix crash when compiling an invalid AST involving a named
(walrus) expression.

@item 
gh-109341@footnote{https://github.com/python/cpython/issues/109341}: Fix crash when compiling an invalid AST involving a
@ref{166b,,ast.TypeAlias}.

@item 
gh-109195@footnote{https://github.com/python/cpython/issues/109195}: Fix source location for the @code{LOAD_*} instruction preceding a
@code{LOAD_SUPER_ATTR} to load the @code{super} global (or shadowing variable)
so that it encompasses only the name @code{super} and not the following
parentheses.

@item 
gh-109256@footnote{https://github.com/python/cpython/issues/109256}: Opcode IDs for specialized opcodes are allocated in their own
range to improve stability of the IDs for the 'real' opcodes.

@item 
gh-109216@footnote{https://github.com/python/cpython/issues/109216}: Fix possible memory leak in @ref{166c,,BUILD_MAP}.

@item 
gh-109207@footnote{https://github.com/python/cpython/issues/109207}: Fix a SystemError in @code{__repr__} of symtable entry object.

@item 
gh-109179@footnote{https://github.com/python/cpython/issues/109179}: Fix bug where the C traceback display drops notes from
@ref{18b,,SyntaxError}.

@item 
gh-109118@footnote{https://github.com/python/cpython/issues/109118}: Disallow nested scopes (lambdas, generator expressions, and
comprehensions) within PEP 695 annotation scopes that are nested within
classes.

@item 
gh-109156@footnote{https://github.com/python/cpython/issues/109156}: Add tests for de-instrumenting instructions while keeping the
instrumentation for lines

@item 
gh-109114@footnote{https://github.com/python/cpython/issues/109114}: Relax the detection of the error message for invalid lambdas
inside f-strings to not search for arbitrary replacement fields to avoid
false positives. Patch by Pablo Galindo

@item 
gh-105848@footnote{https://github.com/python/cpython/issues/105848}: Add a new @ref{166d,,CALL_KW} opcode, used for calls containing
keyword arguments. Also, fix a possible crash when jumping over method
calls in a debugger.

@item 
gh-109052@footnote{https://github.com/python/cpython/issues/109052}: Use the base opcode when comparing code objects to avoid
interference from instrumentation

@item 
gh-109118@footnote{https://github.com/python/cpython/issues/109118}: Fix interpreter crash when a NameError is raised inside the
type parameters of a generic class.

@item 
gh-88943@footnote{https://github.com/python/cpython/issues/88943}: Improve syntax error for non-ASCII character that follows a
numerical literal. It now points on the invalid non-ASCII character, not
on the valid numerical literal.

@item 
gh-108976@footnote{https://github.com/python/cpython/issues/108976}: Fix crash that occurs after de-instrumenting a code object in a
monitoring callback.

@item 
gh-108732@footnote{https://github.com/python/cpython/issues/108732}: Make iteration variables of module- and class-scoped
comprehensions visible to pdb and other tools that use @code{frame.f_locals}
again.

@item 
gh-108959@footnote{https://github.com/python/cpython/issues/108959}: Fix caret placement for error locations for subscript and
binary operations that involve non-semantic parentheses and spaces. Patch
by Pablo Galindo

@item 
gh-104584@footnote{https://github.com/python/cpython/issues/104584}: Fix a crash when running with 
@geindex PYTHONUOPS
@geindex variable d'environnement; PYTHONUOPS
@code{PYTHONUOPS} or
@ref{175,,-X uops} enabled and an error occurs during optimization.

@item 
gh-108727@footnote{https://github.com/python/cpython/issues/108727}: Define @code{tp_dealloc} for @code{CounterOptimizer_Type}. This fixes
a segfault on deallocation.

@item 
gh-108520@footnote{https://github.com/python/cpython/issues/108520}: Fix @code{multiprocessing.synchronize.SemLock.__setstate__()} to
properly initialize
@code{multiprocessing.synchronize.SemLock._is_fork_ctx}. This fixes a
regression when passing a SemLock across nested processes.

Rename @code{multiprocessing.synchronize.SemLock.is_fork_ctx} to
@code{multiprocessing.synchronize.SemLock._is_fork_ctx} to avoid exposing
it as public API.

@item 
gh-108654@footnote{https://github.com/python/cpython/issues/108654}: Restore locals shadowed by an inlined comprehension if the
comprehension raises an exception.

@item 
gh-108488@footnote{https://github.com/python/cpython/issues/108488}: Change the initialization of inline cache entries so that the
cache entry for @code{JUMP_BACKWARD} is initialized to zero, instead of the
@code{adaptive_counter_warmup()} value used for all other instructions. This
counter, unique among instructions, counts up from zero.

@item 
gh-108716@footnote{https://github.com/python/cpython/issues/108716}: Turn off deep-freezing of code objects. Modules are still
frozen, so that a file system search is not needed for common modules.

@item 
gh-108614@footnote{https://github.com/python/cpython/issues/108614}: Add RESUME_CHECK instruction, to avoid having to handle
instrumentation, signals, and contexts switches in the tier 2 execution
engine.

@item 
gh-108487@footnote{https://github.com/python/cpython/issues/108487}: Move an assert that would cause a spurious crash in a devious
case that should only trigger deoptimization.

@item 
gh-106176@footnote{https://github.com/python/cpython/issues/106176}: Use a @code{WeakValueDictionary} to track the lists containing the
modules each thread is currently importing. This helps avoid a reference
leak from keeping the list around longer than necessary. Weakrefs are used
as GC can't interrupt the cleanup.

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: The regen-opcode build stage was removed and its work is now
done in regen-cases.

@item 
gh-107901@footnote{https://github.com/python/cpython/issues/107901}: Fix missing line number on @ref{6f6,,JUMP_BACKWARD} at the end
of a for loop.

@item 
gh-108113@footnote{https://github.com/python/cpython/issues/108113}: The @ref{190,,compile()} built-in can now accept a new flag,
@code{ast.PyCF_OPTIMIZED_AST}, which is similar to @code{ast.PyCF_ONLY_AST}
except that the returned @code{AST} is optimized according to the value of
the @code{optimize} argument.

@ref{1a6,,ast.parse()} now accepts an optional argument @code{optimize} which is
passed on to the @ref{190,,compile()} built-in. This makes it possible to
obtain an optimized @code{AST}.

@item 
gh-107971@footnote{https://github.com/python/cpython/issues/107971}: Opcode IDs are generated from bytecodes.c instead of being hard
coded in opcode.py.

@item 
gh-107944@footnote{https://github.com/python/cpython/issues/107944}: Improve error message for function calls with bad keyword
arguments. Patch by Pablo Galindo

@item 
gh-108390@footnote{https://github.com/python/cpython/issues/108390}: Raise an exception when setting a non-local event (@code{RAISE},
@code{EXCEPTION_HANDLED}, etc.) in @code{sys.monitoring.set_local_events}.

Fixes crash when tracing in recursive calls to Python classes.

@item 
gh-108035@footnote{https://github.com/python/cpython/issues/108035}: Remove the @code{_PyCFrame} struct, moving the pointer to the
current interpreter frame back to the threadstate, as it was for 3.10 and
earlier. The @code{_PyCFrame} existed as a performance optimization for
tracing. Since PEP 669 has been implemented, this optimization no longer
applies.

@item 
gh-91051@footnote{https://github.com/python/cpython/issues/91051}: Fix abort / segfault when using all eight type watcher slots, on
platforms where @code{char} is signed by default.

@item 
gh-106581@footnote{https://github.com/python/cpython/issues/106581}: Fix possible assertion failures and missing instrumentation
events when 
@geindex PYTHONUOPS
@geindex variable d'environnement; PYTHONUOPS
@code{PYTHONUOPS} or @ref{175,,-X uops} is enabled.

@item 
gh-107526@footnote{https://github.com/python/cpython/issues/107526}: Revert converting @code{vars}, @code{dir}, @code{next}, @code{getattr}, and
@code{iter} to argument clinic.

@item 
gh-84805@footnote{https://github.com/python/cpython/issues/84805}: Autogenerate signature for @ref{148a,,METH_NOARGS} and
@ref{14bf,,METH_O} extension functions.

@item 
gh-107758@footnote{https://github.com/python/cpython/issues/107758}: Make the @code{dump_stack()} routine used by the @code{lltrace}
feature (low-level interpreter debugging) robust against recursion by
ensuring that it never calls a @code{__repr__} method implemented in Python.
Also make the similar output for Tier-2 uops appear on @code{stdout} (instead
of @code{stderr}), to match the @code{lltrace} code in ceval.c.

@item 
gh-107659@footnote{https://github.com/python/cpython/issues/107659}: Add docstrings for @ref{166e,,ctypes.pointer()} and
@ref{166f,,ctypes.POINTER()}.

@item 
gh-105848@footnote{https://github.com/python/cpython/issues/105848}: Modify the bytecode so that the actual callable for a
@ref{6f1,,CALL} is at a consistent position on the stack (regardless of
whether or not bound-method-calling optimizations are active).

@item 
gh-107674@footnote{https://github.com/python/cpython/issues/107674}: Fixed performance regression in @code{sys.settrace}.

@item 
gh-107724@footnote{https://github.com/python/cpython/issues/107724}: In pre-release versions of 3.12, up to rc1, the sys.monitoring
callback function for the @code{PY_THROW} event was missing the third,
exception argument. That is now fixed.

@item 
gh-84436@footnote{https://github.com/python/cpython/issues/84436}: Skip reference count modifications for many known immortal
objects.

@item 
gh-107596@footnote{https://github.com/python/cpython/issues/107596}: Specialize subscripting @ref{435,,str} objects by @ref{254,,int}
indexes.

@item 
gh-107080@footnote{https://github.com/python/cpython/issues/107080}: Trace refs builds (@code{--with-trace-refs}) were crashing when
used with isolated subinterpreters.  The problematic global state has been
isolated to each interpreter.  Other fixing the crashes, this change does
not affect users.

@item 
gh-107557@footnote{https://github.com/python/cpython/issues/107557}: Generate the cases needed for the barebones tier 2 abstract
interpreter for optimization passes in CPython.

@item 
gh-106608@footnote{https://github.com/python/cpython/issues/106608}: Make @code{_PyUOpExecutorObject} variable length.

@item 
gh-100964@footnote{https://github.com/python/cpython/issues/100964}: Clear generators' exception state after @code{return} to break
reference cycles.

@item 
gh-107455@footnote{https://github.com/python/cpython/issues/107455}: Improve error messages when converting an incompatible type to
@ref{1670,,ctypes.c_char_p}, @ref{1671,,ctypes.c_wchar_p} and
@ref{1672,,ctypes.c_void_p}.

@item 
gh-107263@footnote{https://github.com/python/cpython/issues/107263}: Increase C recursion limit for functions other than the main
interpreter from 800 to 1500. This should allow functions like
@code{list.__repr__} and @code{json.dumps} to handle all the inputs that they
could prior to 3.12

@item 
gh-104584@footnote{https://github.com/python/cpython/issues/104584}: Fix an issue which caused incorrect inline caches to be read
when running with 
@geindex PYTHONUOPS
@geindex variable d'environnement; PYTHONUOPS
@code{PYTHONUOPS} or @ref{175,,-X uops} enabled.

@item 
gh-104432@footnote{https://github.com/python/cpython/issues/104432}: Fix potential unaligned memory access on C APIs involving
returned sequences of @code{char *} pointers within the @ref{65,,grp} and
@ref{cb,,socket} modules. These were revealed using a
@code{-fsaniziter=alignment} build on ARM macOS. Patch by Christopher Chavez.

@item 
gh-106078@footnote{https://github.com/python/cpython/issues/106078}: Isolate @code{_decimal} (apply 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}). Patch by Charlie
Zhao.

@item 
gh-106898@footnote{https://github.com/python/cpython/issues/106898}: Add the exception as the third argument to @code{PY_UNIND}
callbacks in @code{sys.monitoring}. This makes the @code{PY_UNWIND} callback
consistent with the other exception handling callbacks.

@item 
gh-106895@footnote{https://github.com/python/cpython/issues/106895}: Raise a @code{ValueError} when a monitoring callback function
returns @code{DISABLE} for events that cannot be disabled locally.

@item 
gh-106897@footnote{https://github.com/python/cpython/issues/106897}: Add a @code{RERAISE} event to @code{sys.monitoring}, which occurs
when an exception is reraise, either explicitly by a plain @code{raise}
statement, or implicitly in an @code{except} or @code{finally} block.

@item 
gh-77377@footnote{https://github.com/python/cpython/issues/77377}: Ensure that multiprocessing synchronization objects created in a
fork context are not sent to a different process created in a spawn
context. This changes a segfault into an actionable RuntimeError in the
parent process.

@item 
gh-106931@footnote{https://github.com/python/cpython/issues/106931}: Statically allocated string objects are now interned globally
instead of per-interpreter.  This fixes a situation where such a string
would only be interned in a single interpreter. Normal string objects are
unaffected.

@item 
gh-104621@footnote{https://github.com/python/cpython/issues/104621}: Unsupported modules now always fail to be imported.

@item 
gh-107122@footnote{https://github.com/python/cpython/issues/107122}: Add @ref{1d3,,dbm.ndbm.ndbm.clear()} to @ref{34,,dbm.ndbm}. Patch By
Donghee Na.

@item 
gh-107122@footnote{https://github.com/python/cpython/issues/107122}: Add @ref{1d2,,dbm.gnu.gdbm.clear()} to @ref{33,,dbm.gnu}. Patch By
Donghee Na.

@item 
gh-107015@footnote{https://github.com/python/cpython/issues/107015}: The ASYNC and AWAIT tokens are removed from the Grammar, which
removes the possibility of making @code{async} and @code{await} soft keywords
when using @code{feature_version<7} in @ref{1a6,,ast.parse()}.

@item 
gh-106917@footnote{https://github.com/python/cpython/issues/106917}: Fix classmethod-style @ref{4c5,,super()} method calls (i.e., where
the second argument to @ref{4c5,,super()}, or the implied second argument drawn
from @code{self/cls} in the case of zero-arg super, is a type) when the
target of the call is not a classmethod.

@item 
gh-105699@footnote{https://github.com/python/cpython/issues/105699}: Python no longer crashes due an infrequent race when
initializing per-interpreter interned strings.  The crash would manifest
when the interpreter was finalized.

@item 
gh-105699@footnote{https://github.com/python/cpython/issues/105699}: Python no longer crashes due to an infrequent race in setting
@code{Py_FileSystemDefaultEncoding} and @code{Py_FileSystemDefaultEncodeErrors}
(both deprecated), when simultaneously initializing two isolated
subinterpreters.  Now they are only set during runtime initialization.

@item 
gh-106908@footnote{https://github.com/python/cpython/issues/106908}: Fix various hangs, reference leaks, test failures, and
tracing/introspection bugs when running with 
@geindex PYTHONUOPS
@geindex variable d'environnement; PYTHONUOPS
@code{PYTHONUOPS} or
@ref{175,,-X uops} enabled.

@item 
gh-106092@footnote{https://github.com/python/cpython/issues/106092}: Fix a segmentation fault caused by a use-after-free bug in
@code{frame_dealloc} when the trashcan delays the deallocation of a
@code{PyFrameObject}.

@item 
gh-106485@footnote{https://github.com/python/cpython/issues/106485}: Reduce the number of materialized instances dictionaries by
dematerializing them when possible.

@item 
gh-106719@footnote{https://github.com/python/cpython/issues/106719}: No longer suppress arbitrary errors in the @code{__annotations__}
getter and setter in the type and module types.

@item 
gh-106723@footnote{https://github.com/python/cpython/issues/106723}: Propagate @code{frozen_modules} to multiprocessing spawned process
interpreters.

@item 
gh-104909@footnote{https://github.com/python/cpython/issues/104909}: Split @code{LOAD_ATTR_INSTANCE_VALUE} into micro-ops.

@item 
gh-104909@footnote{https://github.com/python/cpython/issues/104909}: Split @ref{1673,,LOAD_GLOBAL} specializations into micro-ops.

@item 
gh-106597@footnote{https://github.com/python/cpython/issues/106597}: A new debug structure of offsets has been added to the
@code{_PyRuntimeState} that will help out-of-process debuggers and profilers
to obtain the offsets to relevant interpreter structures in a way that is
agnostic of how Python was compiled and that doesn't require copying the
headers. Patch by Pablo Galindo

@item 
gh-106487@footnote{https://github.com/python/cpython/issues/106487}: Allow the `count' argument of @ref{198,,str.replace()} to be a
keyword. Patch by Hugo van Kemenade.

@item 
gh-96844@footnote{https://github.com/python/cpython/issues/96844}: Improve error message of @code{list.remove()}. Patch by Donghee
Na.

@item 
gh-81283@footnote{https://github.com/python/cpython/issues/81283}: Compiler now strips indents from docstrings. It reduces @code{pyc}
file size 5% when the module is heavily documented. This change affects to
@code{__doc__} so tools like doctest will be affected.

@item 
gh-106396@footnote{https://github.com/python/cpython/issues/106396}: When the format specification of an f-string expression is
empty, the parser now generates an empty @ref{1674,,ast.JoinedStr} node for
it instead of an one-element @ref{1674,,ast.JoinedStr} with an empty string
@ref{2b6,,ast.Constant}.

@item 
gh-100288@footnote{https://github.com/python/cpython/issues/100288}: Specialize @ref{4c8,,LOAD_ATTR} for non-descriptors on the
class. Adds @code{LOAD_ATTR_NONDESCRIPTOR_WITH_VALUES} and
@code{LOAD_ATTR_NONDESCRIPTOR_NO_DICT}.

@item 
gh-106008@footnote{https://github.com/python/cpython/issues/106008}: Fix possible reference leaks when failing to optimize
comparisons with @ref{660,,None} in the bytecode compiler.

@item 
gh-106145@footnote{https://github.com/python/cpython/issues/106145}: Make @code{end_lineno} and @code{end_col_offset} required on
@code{type_param} ast nodes.

@item 
gh-106213@footnote{https://github.com/python/cpython/issues/106213}: Changed the way that Emscripten call trampolines work for
compatibility with Wasm/JS Promise integration.

@item 
gh-106182@footnote{https://github.com/python/cpython/issues/106182}: @ref{c47,,sys.getfilesystemencoding()} and
@ref{cd4,,sys.getfilesystemencodeerrors} now return interned Unicode object.

@item 
gh-106210@footnote{https://github.com/python/cpython/issues/106210}: Removed Emscripten import trampoline as it was no longer
necessary for Pyodide.

@item 
gh-104584@footnote{https://github.com/python/cpython/issues/104584}: Added a new, experimental, tracing optimizer and interpreter
(a.k.a. "tier 2"). This currently pessimizes, so don't use yet -- this is
infrastructure so we can experiment with optimizing passes. To enable it,
pass @code{-Xuops} or set @code{PYTHONUOPS=1}. To get debug output, set
@code{PYTHONUOPSDEBUG=N} where @code{N} is a debug level (0-4, where 0 is no
debug output and 4 is excessively verbose).

@item 
gh-105775@footnote{https://github.com/python/cpython/issues/105775}: @ref{1675,,LOAD_CLOSURE} is now a pseudo-op.

@item 
gh-105730@footnote{https://github.com/python/cpython/issues/105730}: Allow any callable other than type objects as the condition
predicate in @ref{150f,,BaseExceptionGroup.split()} and
@ref{164a,,BaseExceptionGroup.subgroup()}.

@item 
gh-105979@footnote{https://github.com/python/cpython/issues/105979}: Fix crash in @code{_imp.get_frozen_object()} due to improper
exception handling.

@item 
gh-106003@footnote{https://github.com/python/cpython/issues/106003}: Add a new @ref{1676,,TO_BOOL} instruction, which performs boolean
conversions for @ref{1677,,POP_JUMP_IF_TRUE}, @ref{1678,,POP_JUMP_IF_FALSE},
and @ref{1679,,UNARY_NOT} (which all expect exact @ref{451,,bool} values now).
Also, modify the oparg of @ref{956,,COMPARE_OP} to include an optional
"boolean conversion" flag.

@item 
gh-98931@footnote{https://github.com/python/cpython/issues/98931}: Ensure custom @ref{18b,,SyntaxError} error messages are raised for
invalid imports with multiple targets. Patch by Pablo Galindo

@item 
gh-105724@footnote{https://github.com/python/cpython/issues/105724}: Improve @code{assert} error messages by providing exact error
range.

@item 
gh-105908@footnote{https://github.com/python/cpython/issues/105908}: Fixed bug where gh-99111@footnote{https://github.com/python/cpython/issues/99111} breaks future import
@code{barry_as_FLUFL} in the Python REPL.

@item 
gh-105840@footnote{https://github.com/python/cpython/issues/105840}: Fix possible crashes when specializing function calls with too
many @code{__defaults__}.

@item 
gh-105831@footnote{https://github.com/python/cpython/issues/105831}: Fix an f-string bug, where using a debug expression (the @code{=}
sign) that appears in the last line of a file results to the debug buffer
that holds the expression text being one character too small.

@item 
gh-105800@footnote{https://github.com/python/cpython/issues/105800}: Correctly issue @ref{44f,,SyntaxWarning} in f-strings if invalid
sequences are used. Patch by Pablo Galindo

@item 
gh-105340@footnote{https://github.com/python/cpython/issues/105340}: Include the comprehension iteration variable in @code{locals()}
inside a module- or class-scope comprehension.

@item 
gh-105331@footnote{https://github.com/python/cpython/issues/105331}: Raise @ref{1ff,,ValueError} if the @code{delay} argument to
@ref{a5d,,asyncio.sleep()} is a NaN (matching @ref{688,,time.sleep()}).

@item 
gh-105587@footnote{https://github.com/python/cpython/issues/105587}: The runtime can't guarantee that immortal objects will not be
mutated by Extensions. Thus, this modifies _PyStaticObject_CheckRefcnt to
warn instead of asserting.

@item 
gh-105564@footnote{https://github.com/python/cpython/issues/105564}: Don't include artificil newlines in the @code{line} attribute of
tokens in the APIs of the @ref{fa,,tokenize} module. Patch by Pablo Galindo

@item 
gh-105549@footnote{https://github.com/python/cpython/issues/105549}: Tokenize separately @code{NUMBER} and @code{NAME} tokens that are not
ambiguous. Patch by Pablo Galindo.

@item 
gh-105588@footnote{https://github.com/python/cpython/issues/105588}: Fix an issue that could result in crashes when compiling
malformed @ref{8,,ast} nodes.

@item 
gh-100987@footnote{https://github.com/python/cpython/issues/100987}: Allow objects other than code objects as the "executable" in
internal frames. In the long term, this can help tools like Cython and
PySpy interact more efficiently. In the shorter term, it allows us to
perform some optimizations more simply.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in the @ref{12,,builtins} module where exceptions could
end up being overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bug in the compiler where an exception could end up being
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Improve error handling in @code{PyUnicode_BuildEncodingMap()}
where an exception could end up being overwritten.

@item 
gh-105486@footnote{https://github.com/python/cpython/issues/105486}: Change the repr of @code{ParamSpec} list of args in
@code{types.GenericAlias}.

@item 
gh-105678@footnote{https://github.com/python/cpython/issues/105678}: Break the @code{MAKE_FUNCTION} instruction into two parts,
@code{MAKE_FUNCTION} which makes the function and @code{SET_FUNCTION_ATTRIBUTE}
which sets the attributes on the function. This makes the stack effect of
@code{MAKE_FUNCTION} regular to ease optimization and code generation.

@item 
gh-105435@footnote{https://github.com/python/cpython/issues/105435}: Fix spurious newline character if file ends on a comment
without a newline. Patch by Pablo Galindo

@item 
gh-105390@footnote{https://github.com/python/cpython/issues/105390}: Correctly raise @ref{52d,,tokenize.TokenError} exceptions instead
of @ref{18b,,SyntaxError} for tokenize errors such as incomplete input. Patch
by Pablo Galindo

@item 
gh-105259@footnote{https://github.com/python/cpython/issues/105259}: Don't include newline character for trailing @code{NEWLINE} tokens
emitted in the @ref{fa,,tokenize} module. Patch by Pablo Galindo

@item 
gh-104635@footnote{https://github.com/python/cpython/issues/104635}: Eliminate redundant @ref{167a,,STORE_FAST} instructions in the
compiler. Patch by Donghee Na and Carl Meyer.

@item 
gh-105324@footnote{https://github.com/python/cpython/issues/105324}: Fix the main function of the @ref{fa,,tokenize} module when
reading from @code{sys.stdin}. Patch by Pablo Galindo

@item 
gh-33092@footnote{https://github.com/python/cpython/issues/33092}: Simplify and speed up interpreter for f-strings. Removes
@code{FORMAT_VALUE} opcode. Add @code{CONVERT_VALUE}, @code{FORMAT_SIMPLE} and
@code{FORMAT_WITH_SPEC} opcode. Compiler emits more efficient sequence for
each format expression.

@item 
gh-105229@footnote{https://github.com/python/cpython/issues/105229}: Remove remaining two-codeunit superinstructions. All remaining
superinstructions only take a single codeunit, simplifying instrumentation
and quickening.

@item 
gh-105235@footnote{https://github.com/python/cpython/issues/105235}: Prevent out-of-bounds memory access during @code{mmap.find()}
calls.

@item 
gh-98963@footnote{https://github.com/python/cpython/issues/98963}: Restore the ability for a subclass of @ref{192,,property} to
define @code{__slots__} or otherwise be dict-less by ignoring failures to set
a docstring on such a class.  This behavior had regressed in 3.12beta1.
An @ref{343,,AttributeError} where there had not previously been one was
disruptive to existing code.

@item 
gh-104812@footnote{https://github.com/python/cpython/issues/104812}: The "pending call" machinery now works for all interpreters,
not just the main interpreter, and runs in all threads, not just the main
thread. Some calls are still only done in the main thread, ergo in the
main interpreter. This change does not affect signal handling nor the
existing public C-API (@code{Py_AddPendingCall()}), which both still only
target the main thread. The new functionality is meant strictly for
internal use for now, since consequences of its use are not well
understood yet outside some very restricted cases.  This change brings the
capability in line with the intention when the state was made
per-interpreter several years ago.

@item 
gh-105194@footnote{https://github.com/python/cpython/issues/105194}: Do not escape with backslashes f-string format specifiers.
Patch by Pablo Galindo

@item 
gh-105229@footnote{https://github.com/python/cpython/issues/105229}: Replace some dynamic superinstructions with single instruction
equivalents.

@item 
gh-105162@footnote{https://github.com/python/cpython/issues/105162}: Fixed bug in generator.close()/throw() where an inner iterator
would be ignored when the outer iterator was instrumented.

@item 
gh-105164@footnote{https://github.com/python/cpython/issues/105164}: Ensure annotations are set up correctly if the only annotation
in a block is within a @ref{7f7,,match} block. Patch by Jelle Zijlstra.

@item 
gh-105148@footnote{https://github.com/python/cpython/issues/105148}: Make @code{_PyASTOptimizeState} internal to ast_opt.c. Make
@code{_PyAST_Optimize} take two integers instead of a pointer to this struct.
This avoids the need to include pycore_compile.h in ast_opt.c.

@item 
gh-104799@footnote{https://github.com/python/cpython/issues/104799}: Attributes of @ref{8,,ast} nodes that are lists now default to
the empty list if omitted. This means that some code that previously
raised @ref{522,,TypeError} when the AST node was used will now proceed with
the empty list instead. Patch by Jelle Zijlstra.

@item 
gh-105111@footnote{https://github.com/python/cpython/issues/105111}: Remove the old trashcan macros @code{Py_TRASHCAN_SAFE_BEGIN} and
@code{Py_TRASHCAN_SAFE_END}. They should be replaced by the new macros
@code{Py_TRASHCAN_BEGIN} and @code{Py_TRASHCAN_END}.

@item 
gh-105035@footnote{https://github.com/python/cpython/issues/105035}: Fix @ref{4c5,,super()} calls on types with custom
@ref{167b,,tp_getattro} implementation (e.g. meta-types.)

@item 
gh-105017@footnote{https://github.com/python/cpython/issues/105017}: Show CRLF lines in the tokenize string attribute in both NL and
NEWLINE tokens. Patch by Marta Gómez.

@item 
gh-105013@footnote{https://github.com/python/cpython/issues/105013}: Fix handling of multiline parenthesized lambdas in
@ref{154d,,inspect.getsource()}. Patch by Pablo Galindo

@item 
gh-105017@footnote{https://github.com/python/cpython/issues/105017}: Do not include an additional final @code{NL} token when parsing
files having CRLF lines. Patch by Marta Gómez.

@item 
gh-104976@footnote{https://github.com/python/cpython/issues/104976}: Ensure that trailing @code{DEDENT} @code{tokenize.TokenInfo}
objects emitted by the @ref{fa,,tokenize} module are reported as in Python
3.11. Patch by Pablo Galindo

@item 
gh-104972@footnote{https://github.com/python/cpython/issues/104972}: Ensure that the @code{line} attribute in
@code{tokenize.TokenInfo} objects in the @ref{fa,,tokenize} module are
always correct. Patch by Pablo Galindo

@item 
gh-104955@footnote{https://github.com/python/cpython/issues/104955}: Fix signature for the new @ref{167c,,__release_buffer__()}
slot. Patch by Jelle Zijlstra.

@item 
gh-104690@footnote{https://github.com/python/cpython/issues/104690}: Starting new threads and process creation through
@ref{195,,os.fork()} during interpreter shutdown (such as from @ref{c,,atexit}
handlers) is no longer supported.  It can lead to race condition between
the main Python runtime thread freeing thread states while internal
@ref{ec,,threading} routines are trying to allocate and use the state of just
created threads. Or forked children trying to use the mid-shutdown runtime
and thread state in the child process.

@item 
gh-104879@footnote{https://github.com/python/cpython/issues/104879}: Fix crash when accessing the @code{__module__} attribute of type
aliases defined outside a module. Patch by Jelle Zijlstra.

@item 
gh-104825@footnote{https://github.com/python/cpython/issues/104825}: Tokens emitted by the @ref{fa,,tokenize} module do not include an
implicit @code{\n} character in the @code{line} attribute anymore. Patch by
Pablo Galindo

@item 
gh-104770@footnote{https://github.com/python/cpython/issues/104770}: If a generator returns a value upon being closed, the value is
now returned by @ref{167d,,generator.close()}.

@item 
gh-89091@footnote{https://github.com/python/cpython/issues/89091}: Raise @ref{1bb,,RuntimeWarning} for unawaited async generator
methods like @ref{8c6,,asend()}, @ref{4e3,,athrow()} and
@ref{8c5,,aclose()}. Patch by Kumar Aditya.

@item 
gh-96663@footnote{https://github.com/python/cpython/issues/96663}: Add a better, more introspect-able error message when setting
attributes on classes without a @code{__dict__} and no slot member for the
attribute.

@item 
gh-93627@footnote{https://github.com/python/cpython/issues/93627}: Update the Python pickle module implementation to match the C
implementation of the pickle module. For objects setting reduction methods
like @ref{1540,,__reduce_ex__()} or @ref{9c1,,__reduce__()} to
@code{None}, pickling will result in a @ref{522,,TypeError}.

@item 
gh-101006@footnote{https://github.com/python/cpython/issues/101006}: Improve error handling when read @ref{8c,,marshal} data.

@item 
gh-91095@footnote{https://github.com/python/cpython/issues/91095}: Specializes calls to most Python classes. Specifically, any
class that inherits from @code{object}, or another Python class, and does not
override @code{__new__}.

The specialized instruction does the following:


@enumerate 

@item 
Creates the object (by calling @code{object.__new__})

@item 
Pushes a shim frame to the frame stack (to cleanup after @code{__init__})

@item 
Pushes the frame for @code{__init__} to the frame stack
@end enumerate

Speeds up the instantiation of most Python classes.
@end itemize

@node Library<15>,Documentation<10>,Core and Builtins<16>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id114}@anchor{167e}
@subsubsection Library



@itemize -

@item 
gh-110786@footnote{https://github.com/python/cpython/issues/110786}: @ref{da,,sysconfig}'s CLI now ignores @ref{1045,,BrokenPipeError},
making it exit normally if its output is being piped and the pipe closes.

@item 
gh-103480@footnote{https://github.com/python/cpython/issues/103480}: The @ref{da,,sysconfig} module is now a package, instead of a
single-file module.

@item 
gh-110733@footnote{https://github.com/python/cpython/issues/110733}: Micro-optimization: Avoid calling @code{min()}, @code{max()} in
@code{BaseEventLoop._run_once()}.

@item 
gh-94597@footnote{https://github.com/python/cpython/issues/94597}: Added @ref{167f,,asyncio.EventLoop} for use with the
@ref{466,,asyncio.run()} `loop_factory' kwarg to avoid calling the asyncio
policy system.

@item 
gh-110682@footnote{https://github.com/python/cpython/issues/110682}: @ref{42c,,runtime-checkable protocols}
used to consider @code{__match_args__} a protocol member in
@code{__instancecheck__} if it was present on the protocol. Now, this
attribute is ignored if it is present.

@item 
gh-110488@footnote{https://github.com/python/cpython/issues/110488}: Fix a couple of issues in @ref{1680,,pathlib.PurePath.with_name()}: a
single dot was incorrectly considered a valid name, and in
@code{PureWindowsPath}, a name with an NTFS alternate data stream, like
@code{a:b}, was incorrectly considered invalid.

@item 
gh-110590@footnote{https://github.com/python/cpython/issues/110590}: Fix a bug in @code{_sre.compile()} where @ref{522,,TypeError} would
be overwritten by @ref{86d,,OverflowError} when the `code' argument was a list
of non-ints.

@item 
gh-65052@footnote{https://github.com/python/cpython/issues/65052}: Prevent @ref{a4,,pdb} from crashing when trying to display
undisplayable objects

@item 
gh-110519@footnote{https://github.com/python/cpython/issues/110519}: Deprecation warning about non-integer number in @ref{62,,gettext}
now always refers to the line in the user code where gettext function or
method is used. Previously it could refer to a line in @code{gettext} code.

@item 
gh-89902@footnote{https://github.com/python/cpython/issues/89902}: Deprecate non-standard format specifier "N" for
@ref{29a,,decimal.Decimal}. It was not documented and only supported in the
C implementation.

@item 
gh-110378@footnote{https://github.com/python/cpython/issues/110378}: @ref{11df,,contextmanager()} and
@ref{b18,,asynccontextmanager()} context managers now close an
invalid underlying generator object that yields more then one value.

@item 
gh-106670@footnote{https://github.com/python/cpython/issues/106670}: In @ref{a4,,pdb}, set convenience variable @code{$_exception} for
post mortem debugging.

@item 
gh-110365@footnote{https://github.com/python/cpython/issues/110365}: Fix @ref{1681,,termios.tcsetattr()} bug that was overwriting existing
errors during parsing integers from @code{term} list.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Slightly improve the import time of several standard-library
modules by deferring imports of @ref{111,,warnings} within those modules.
Patch by Alex Waygood.

@item 
gh-110273@footnote{https://github.com/python/cpython/issues/110273}: @ref{1682,,dataclasses.replace()} now raises TypeError instead of
ValueError if specify keyword argument for a field declared with
init=False or miss keyword argument for required InitVar field.

@item 
gh-110249@footnote{https://github.com/python/cpython/issues/110249}: Add @code{--inline-caches} flag to @code{dis} command line.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Fix a Python 3.12 regression in the import time of
@ref{b7,,random}. Patch by Alex Waygood.

@item 
gh-110222@footnote{https://github.com/python/cpython/issues/110222}: Add support of struct sequence objects in @ref{150,,copy.replace()}.
Patched by Xuehai Pan.

@item 
gh-109649@footnote{https://github.com/python/cpython/issues/109649}: @ref{93,,multiprocessing}, @ref{21,,concurrent.futures},
@ref{20,,compileall}: Replace @ref{1c0,,os.cpu_count()} with
@ref{1bf,,os.process_cpu_count()} to select the default number of worker
threads and processes. Get the CPU affinity if supported. Patch by Victor
Stinner.

@item 
gh-110150@footnote{https://github.com/python/cpython/issues/110150}: Fix base case handling in statistics.quantiles.  Now allows a
single data point.

@item 
gh-110036@footnote{https://github.com/python/cpython/issues/110036}: On Windows, multiprocessing @code{Popen.terminate()} now catches
@ref{d30,,PermissionError} and get the process exit code. If the process is
still running, raise again the @ref{d30,,PermissionError}. Otherwise, the
process terminated as expected: store its exit code. Patch by Victor
Stinner.

@item 
gh-110038@footnote{https://github.com/python/cpython/issues/110038}: Fixed an issue that caused @code{KqueueSelector.select()} to not
return all the ready events in some cases when a file descriptor is
registered for both read and write.

@item 
gh-110045@footnote{https://github.com/python/cpython/issues/110045}: Update the @ref{d7,,symtable} module to support the new scopes
introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.

@item 
gh-88402@footnote{https://github.com/python/cpython/issues/88402}: Add new variables to @ref{1015,,sysconfig.get_config_vars()} on
Windows: @code{LIBRARY}, @code{LDLIBRARY}, @code{LIBDIR}, @code{SOABI}, and
@code{Py_NOGIL}.

@item 
gh-109631@footnote{https://github.com/python/cpython/issues/109631}: @ref{b8,,re} functions such as @ref{1013,,re.findall()},
@ref{29f,,re.split()}, @ref{120a,,re.search()} and @ref{2a0,,re.sub()} which perform short
repeated matches can now be interrupted by user.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Reduce the import time of @ref{50,,email.utils} by around 43%.
This results in the import time of @ref{44,,email.message} falling by around
18%, which in turn reduces the import time of @ref{79,,importlib.metadata} by
around 6%. Patch by Alex Waygood.

@item 
gh-109818@footnote{https://github.com/python/cpython/issues/109818}: Fix @ref{11d0,,reprlib.recursive_repr()} not copying
@code{__type_params__} from decorated function.

@item 
gh-109047@footnote{https://github.com/python/cpython/issues/109047}: @ref{21,,concurrent.futures}: The `executor manager thread' now
catches exceptions when adding an item to the `call queue'. During Python
finalization, creating a new thread can now raise @ref{193,,RuntimeError}.
Catch the exception and call @code{terminate_broken()} in this case. Patch by
Victor Stinner.

@item 
gh-109782@footnote{https://github.com/python/cpython/issues/109782}: Ensure the signature of @ref{9fe,,os.path.isdir()} is identical on
all platforms. Patch by Amin Alaee.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Improve import time of @ref{5e,,functools} by around 13%. Patch by
Alex Waygood.

@item 
gh-109590@footnote{https://github.com/python/cpython/issues/109590}: @ref{49d,,shutil.which()} will prefer files with an extension in
@code{PATHEXT} if the given mode includes @code{os.X_OK} on win32. If no
@code{PATHEXT} match is found, a file without an extension in @code{PATHEXT} can
be returned. This change will have @ref{49d,,shutil.which()} act more similarly
to previous behavior in Python 3.11.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Reduce the import time of @ref{55,,enum} by over 50%. Patch by
Alex Waygood.

@item 
gh-109593@footnote{https://github.com/python/cpython/issues/109593}: Avoid deadlocking on a reentrant call to the multiprocessing
resource tracker. Such a reentrant call, though unlikely, can happen if a
GC pass invokes the finalizer for a multiprocessing object such as
SemLock.

@item 
gh-109653@footnote{https://github.com/python/cpython/issues/109653}: Reduce the import time of @ref{103,,typing} by around a third.
Patch by Alex Waygood.

@item 
gh-109649@footnote{https://github.com/python/cpython/issues/109649}: Add @ref{1bf,,os.process_cpu_count()} function to get the number of
logical CPUs usable by the calling thread of the current process. Patch by
Victor Stinner.

@item 
gh-74481@footnote{https://github.com/python/cpython/issues/74481}: Add @code{set_error_mode} related constants in @code{msvcrt} module in
Python debug build.

@item 
gh-109613@footnote{https://github.com/python/cpython/issues/109613}: Fix @ref{48a,,os.stat()} and @ref{1683,,os.DirEntry.stat()}: check for
exceptions. Previously, on Python built in debug mode, these functions
could trigger a fatal Python error (and abort the process) when a function
succeeded with an exception set. Patch by Victor Stinner.

@item 
gh-109599@footnote{https://github.com/python/cpython/issues/109599}: Expose the type of PyCapsule objects as @code{types.CapsuleType}.

@item 
gh-109109@footnote{https://github.com/python/cpython/issues/109109}: You can now get the raw TLS certificate chains from TLS
connections via @ref{1564,,ssl.SSLSocket.get_verified_chain()} and
@ref{1565,,ssl.SSLSocket.get_unverified_chain()} methods.

Contributed by Mateusz Nowak.

@item 
gh-109559@footnote{https://github.com/python/cpython/issues/109559}: Update @ref{104,,unicodedata} database to Unicode 15.1.0.

@item 
gh-109543@footnote{https://github.com/python/cpython/issues/109543}: Remove unnecessary @ref{4bb,,hasattr()} check during
@ref{161,,typing.TypedDict} creation.

@item 
gh-109495@footnote{https://github.com/python/cpython/issues/109495}: Remove unnecessary extra @code{__slots__} in
@ref{1c7,,datetime}'s pure python implementation to reduce memory
size, as they are defined in the superclass. Patch by James Hilton-Balfe

@item 
gh-109461@footnote{https://github.com/python/cpython/issues/109461}: @ref{86,,logging}: Use a context manager for lock acquisition.

@item 
gh-109096@footnote{https://github.com/python/cpython/issues/109096}: @ref{29e,,http.server.CGIHTTPRequestHandler} has been deprecated
for removal in 3.15.  Its design is old and the web world has long since
moved beyond CGI.

@item 
gh-109409@footnote{https://github.com/python/cpython/issues/109409}: Fix error when it was possible to inherit a frozen dataclass
from multiple parents some of which were possibly not frozen.

@item 
gh-109375@footnote{https://github.com/python/cpython/issues/109375}: The @ref{a4,,pdb} @code{alias} command now prevents registering
aliases without arguments.

@item 
gh-109319@footnote{https://github.com/python/cpython/issues/109319}: Deprecate the @code{dis.HAVE_ARGUMENT} field in favour of
@code{dis.hasarg}.

@item 
gh-107219@footnote{https://github.com/python/cpython/issues/107219}: Fix a race condition in @code{concurrent.futures}. When a process
in the process pool was terminated abruptly (while the future was running
or pending), close the connection write end. If the call queue is blocked
on sending bytes to a worker process, closing the connection write end
interrupts the send, so the queue can be closed. Patch by Victor Stinner.

@item 
gh-66143@footnote{https://github.com/python/cpython/issues/66143}: The @ref{1684,,codecs.CodecInfo} object has been made copyable and
pickleable. Patched by Robert Lehmann and Furkan Onder.

@item 
gh-109187@footnote{https://github.com/python/cpython/issues/109187}: @ref{1685,,pathlib.Path.resolve()} now treats symlink loops like
other errors: in strict mode, @ref{40d,,OSError} is raised, and in non-strict
mode, no exception is raised.

@item 
gh-50644@footnote{https://github.com/python/cpython/issues/50644}: Attempts to pickle or create a shallow or deep copy of
@ref{1b,,codecs} streams now raise a TypeError. Previously, copying failed
with a RecursionError, while pickling produced wrong results that
eventually caused unpickling to fail with a RecursionError.

@item 
gh-109174@footnote{https://github.com/python/cpython/issues/109174}: Add support of @ref{1cc,,types.SimpleNamespace} in
@ref{150,,copy.replace()}.

@item 
gh-109164@footnote{https://github.com/python/cpython/issues/109164}: @ref{a4,,pdb}: Replace @ref{60,,getopt} with @ref{6,,argparse} for
parsing command line arguments.

@item 
gh-109151@footnote{https://github.com/python/cpython/issues/109151}: Enable @code{readline} editing features in the @ref{42a,,sqlite3 command-line interface} (@code{python -m sqlite3}).

@item 
gh-108987@footnote{https://github.com/python/cpython/issues/108987}: Fix @ref{194,,_thread.start_new_thread()} race condition. If a
thread is created during Python finalization, the newly spawned thread now
exits immediately instead of trying to access freed memory and lead to a
crash. Patch by Victor Stinner.

@item 
gh-108682@footnote{https://github.com/python/cpython/issues/108682}: Enum: require @code{names=()} or @code{type=...} to create an empty
enum using the functional syntax.

@item 
gh-109033@footnote{https://github.com/python/cpython/issues/109033}: Exceptions raised by os.utime builtin function now include the
related filename

@item 
gh-108843@footnote{https://github.com/python/cpython/issues/108843}: Fix an issue in @ref{8d2,,ast.unparse()} when unparsing f-strings
containing many quote types.

@item 
gh-108469@footnote{https://github.com/python/cpython/issues/108469}: @ref{8d2,,ast.unparse()} now supports new @ref{41f,,f-string} syntax
introduced in Python 3.12. Note that the @ref{41f,,f-string} quotes are
reselected for simplicity under the new syntax. (Patch by Steven Sun)

@item 
gh-108751@footnote{https://github.com/python/cpython/issues/108751}: Add @ref{150,,copy.replace()} function which allows to create a
modified copy of an object. It supports named tuples, dataclasses, and
many other objects.

@item 
gh-108682@footnote{https://github.com/python/cpython/issues/108682}: Enum: raise @ref{522,,TypeError} if @code{super().__new__()} is called
from a custom @code{__new__}.

@item 
gh-108278@footnote{https://github.com/python/cpython/issues/108278}: Deprecate passing the callback callable by keyword for the
following @ref{242,,sqlite3.Connection} APIs:


@itemize *

@item 
@ref{2a8,,set_authorizer()}

@item 
@ref{2a9,,set_progress_handler()}

@item 
@ref{2aa,,set_trace_callback()}
@end itemize

The affected parameters will become positional-only in Python 3.15.

Patch by Erlend E. Aasland.

@item 
gh-105829@footnote{https://github.com/python/cpython/issues/105829}: Fix concurrent.futures.ProcessPoolExecutor deadlock

@item 
gh-108295@footnote{https://github.com/python/cpython/issues/108295}: Fix crashes related to use of weakrefs on
@ref{15c,,typing.TypeVar}.

@item 
gh-108463@footnote{https://github.com/python/cpython/issues/108463}: Make expressions/statements work as expected in pdb

@item 
gh-108277@footnote{https://github.com/python/cpython/issues/108277}: Add @ref{20e,,os.timerfd_create()}, @ref{20f,,os.timerfd_settime()},
@ref{211,,os.timerfd_gettime()}, @ref{210,,os.timerfd_settime_ns()}, and
@ref{212,,os.timerfd_gettime_ns()} to provide a low level interface for Linux's
timer notification file descriptor.

@item 
gh-107811@footnote{https://github.com/python/cpython/issues/107811}: @ref{dd,,tarfile}: extraction of members with overly large UID or
GID (e.g. on an OS with 32-bit @code{id_t}) now fails in the same way
as failing to set the ID.

@item 
gh-64662@footnote{https://github.com/python/cpython/issues/64662}: Fix support for virtual tables in
@ref{244,,sqlite3.Connection.iterdump()}. Patch by Aviv Palivoda.

@item 
gh-108111@footnote{https://github.com/python/cpython/issues/108111}: Fix a regression introduced in gh-101251@footnote{https://github.com/python/cpython/issues/101251} for 3.12, resulting in
an incorrect offset calculation in @code{gzip.GzipFile.seek()}.

@item 
gh-108294@footnote{https://github.com/python/cpython/issues/108294}: @ref{688,,time.sleep()} now raises an auditing event.

@item 
gh-108278@footnote{https://github.com/python/cpython/issues/108278}: Deprecate passing name, number of arguments, and the callable
as keyword arguments, for the following @ref{242,,sqlite3.Connection} APIs:


@itemize *

@item 
@ref{2a6,,create_function()}

@item 
@ref{2a7,,create_aggregate()}
@end itemize

The affected parameters will become positional-only in Python 3.15.

Patch by Erlend E. Aasland.

@item 
gh-108322@footnote{https://github.com/python/cpython/issues/108322}: Speed-up NormalDist.samples() by using the inverse CDF method
instead of calling random.gauss().

@item 
gh-83417@footnote{https://github.com/python/cpython/issues/83417}: Add the ability for venv to create a @code{.gitignore} file which
causes the created environment to be ignored by Git. It is on by default
when venv is called via its CLI.

@item 
gh-105736@footnote{https://github.com/python/cpython/issues/105736}: Harmonized the pure Python version of
@ref{5c5,,OrderedDict} with the C version. Now, both versions
set up their internal state in @code{__new__}.  Formerly, the pure Python
version did the set up in @code{__init__}.

@item 
gh-108083@footnote{https://github.com/python/cpython/issues/108083}: Fix bugs in the constructor of @ref{242,,sqlite3.Connection} and
@ref{243,,sqlite3.Connection.close()} where exceptions could be leaked. Patch
by Erlend E. Aasland.

@item 
gh-107932@footnote{https://github.com/python/cpython/issues/107932}: Fix @code{dis} module to properly report and display bytecode that
do not have source lines.

@item 
gh-105539@footnote{https://github.com/python/cpython/issues/105539}: @ref{ce,,sqlite3} now emits an @ref{241,,ResourceWarning} if a
@ref{242,,sqlite3.Connection} object is not @code{closed} explicitly. Patch by Erlend E. Aasland.

@item 
gh-107995@footnote{https://github.com/python/cpython/issues/107995}: The @code{__module__} attribute on instances of
@ref{52c,,functools.cached_property} is now set to the name of the module in
which the cached_property is defined, rather than "functools". This means
that doctests in @code{cached_property} docstrings are now properly collected
by the @ref{3a,,doctest} module. Patch by Tyler Smart.

@item 
gh-107963@footnote{https://github.com/python/cpython/issues/107963}: Fix @ref{1520,,multiprocessing.set_forkserver_preload()} to check the
given list of modules names. Patch by Donghee Na.

@item 
gh-106242@footnote{https://github.com/python/cpython/issues/106242}: Fixes @ref{12f8,,os.path.normpath()} to handle embedded null
characters without truncating the path.

@item 
gh-81555@footnote{https://github.com/python/cpython/issues/81555}: @ref{121,,xml.dom.minidom} now only quotes @code{"} in attributes.

@item 
gh-50002@footnote{https://github.com/python/cpython/issues/50002}: @ref{121,,xml.dom.minidom} now preserves whitespaces in attributes.

@item 
gh-93057@footnote{https://github.com/python/cpython/issues/93057}: Passing more than one positional argument to
@ref{2a5,,sqlite3.connect()} and the @ref{242,,sqlite3.Connection} constructor is
deprecated. The remaining parameters will become keyword-only in Python
3.15. Patch by Erlend E. Aasland.

@item 
gh-76913@footnote{https://github.com/python/cpython/issues/76913}: Add `merge_extra' parameter/feature to
@ref{12d3,,logging.LoggerAdapter}

@item 
gh-107913@footnote{https://github.com/python/cpython/issues/107913}: Fix possible losses of @code{errno} and @code{winerror} values in
@ref{40d,,OSError} exceptions if they were cleared or modified by the cleanup
code before creating the exception object.

@item 
gh-107845@footnote{https://github.com/python/cpython/issues/107845}: @ref{1686,,tarfile.data_filter()} now takes the location of symlinks
into account when determining their target, so it will no longer reject
some valid tarballs with @code{LinkOutsideDestinationError}.

@item 
gh-107812@footnote{https://github.com/python/cpython/issues/107812}: Extend socket's netlink support to the FreeBSD platform.

@item 
gh-107805@footnote{https://github.com/python/cpython/issues/107805}: Fix signatures of module-level generated functions in
@ref{100,,turtle}.

@item 
gh-107782@footnote{https://github.com/python/cpython/issues/107782}: @ref{b4,,pydoc} is now able to show signatures which are not
representable in Python, e.g. for @code{getattr} and @code{dict.pop}.

@item 
gh-56166@footnote{https://github.com/python/cpython/issues/56166}: Deprecate passing optional arguments `maxsplit', `count' and
`flags' in module-level functions @ref{29f,,re.split()}, @ref{2a0,,re.sub()} and
@ref{2a1,,re.subn()} as positional. They should only be passed by keyword.

@item 
gh-107710@footnote{https://github.com/python/cpython/issues/107710}: Speed up @ref{1687,,logging.getHandlerNames()}.

@item 
gh-107715@footnote{https://github.com/python/cpython/issues/107715}: Fix @ref{1688,,doctest.DocTestFinder.find()} in presence of class
names with special characters. Patch by Gertjan van Zwieten.

@item 
gh-100814@footnote{https://github.com/python/cpython/issues/100814}: Passing a callable object as an option value to a Tkinter image
now raises the expected TclError instead of an AttributeError.

@item 
gh-72684@footnote{https://github.com/python/cpython/issues/72684}: Add @ref{ef,,tkinter} widget methods: @code{tk_busy_hold()},
@code{tk_busy_configure()}, @code{tk_busy_cget()},
@code{tk_busy_forget()}, @code{tk_busy_current()}, and
@code{tk_busy_status()}.

@item 
gh-106684@footnote{https://github.com/python/cpython/issues/106684}: Raise @ref{241,,ResourceWarning} when @ref{1689,,asyncio.StreamWriter}
is not closed leading to memory leaks. Patch by Kumar Aditya.

@item 
gh-107465@footnote{https://github.com/python/cpython/issues/107465}: Add @ref{227,,pathlib.Path.from_uri()} classmethod.

@item 
gh-107077@footnote{https://github.com/python/cpython/issues/107077}: Seems that in some conditions, OpenSSL will return
@code{SSL_ERROR_SYSCALL} instead of @code{SSL_ERROR_SSL} when a certification
verification has failed, but the error parameters will still contain
@code{ERR_LIB_SSL} and @code{SSL_R_CERTIFICATE_VERIFY_FAILED}. We are now
detecting this situation and raising the appropriate
@code{ssl.SSLCertVerificationError}. Patch by Pablo Galindo

@item 
gh-107576@footnote{https://github.com/python/cpython/issues/107576}: Fix @ref{4b7,,types.get_original_bases()} to only return
@code{__orig_bases__} if it is present on @code{cls} directly. Patch by
James Hilton-Balfe.

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: Remove @code{opcode.is_pseudo}, @code{opcode.MIN_PSEUDO_OPCODE} and
@code{opcode.MAX_PSEUDO_OPCODE}, which were added in 3.12, were never
documented and were not intended to be used externally.

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: @code{opcode.ENABLE_SPECIALIZATION} (which was added in 3.12
but never documented or intended for external usage) is moved to
@code{_opcode.ENABLE_SPECIALIZATION} where tests can access it.

@item 
gh-107396@footnote{https://github.com/python/cpython/issues/107396}: tarfiles; Fixed use before assignment of self.exception for
gzip decompression

@item 
gh-107409@footnote{https://github.com/python/cpython/issues/107409}: Set @code{__wrapped__} attribute in
@ref{11d0,,reprlib.recursive_repr()}.

@item 
gh-107406@footnote{https://github.com/python/cpython/issues/107406}: Implement new @code{__repr__()} method for
@ref{163a,,struct.Struct}. Now it returns @code{Struct(<format repr>)}.

@item 
gh-107369@footnote{https://github.com/python/cpython/issues/107369}: Optimize @ref{273,,textwrap.indent()}. It is ~30% faster for large
input. Patch by Inada Naoki.

@item 
gh-78722@footnote{https://github.com/python/cpython/issues/78722}: Fix issue where @ref{15ba,,pathlib.Path.iterdir()} did not raise
@ref{40d,,OSError} until iterated.

@item 
gh-105578@footnote{https://github.com/python/cpython/issues/105578}: Deprecate @ref{2af,,typing.AnyStr} in favor of the new Type
Parameter syntax. See PEP 695.

@item 
gh-62519@footnote{https://github.com/python/cpython/issues/62519}: Make @ref{9e3,,gettext.pgettext()} search plural definitions when
translation is not found.

@item 
gh-107089@footnote{https://github.com/python/cpython/issues/107089}: Shelves opened with @ref{168a,,shelve.open()} have a much faster
@code{clear()} method. Patch by James Cave.

@item 
gh-82500@footnote{https://github.com/python/cpython/issues/82500}: Fix overflow on 32-bit systems with @ref{a,,asyncio}
@ref{afd,,os.sendfile()} implementation.

@item 
gh-83006@footnote{https://github.com/python/cpython/issues/83006}: Document behavior of @ref{110d,,shutil.disk_usage()} for non-mounted
filesystems on Unix.

@item 
gh-65495@footnote{https://github.com/python/cpython/issues/65495}: Use lowercase @code{mail from} and @code{rcpt to} in
@code{smptlib.SMTP}.

@item 
gh-106186@footnote{https://github.com/python/cpython/issues/106186}: Do not report @code{MultipartInvariantViolationDefect} defect when
the @ref{117c,,email.parser.Parser} class is used to parse emails with
@code{headersonly=True}.

@item 
gh-105002@footnote{https://github.com/python/cpython/issues/105002}: Fix invalid result from @code{PurePath.relative_to()} method
when attempting to walk a "@code{..}" segment in `other' with `walk_up'
enabled. A @ref{1ff,,ValueError} exception is now raised in this case.

@item 
gh-106739@footnote{https://github.com/python/cpython/issues/106739}: Add the @code{rtype_cache} to the warning message (as an addition
to the type of leaked objects and the number of leaked objects already
included in the message) to make debugging leaked objects easier when the
multiprocessing resource tracker process finds leaked objects at shutdown.
This helps more quickly identify what was leaked and/or why the leaked
object was not properly cleaned up.

@item 
gh-106751@footnote{https://github.com/python/cpython/issues/106751}: Optimize @code{SelectSelector.select()} for many iteration case.
Patch By Donghee Na.

@item 
gh-106751@footnote{https://github.com/python/cpython/issues/106751}: Optimize @code{_PollLikeSelector.select()} for many iteration
case.

@item 
gh-106751@footnote{https://github.com/python/cpython/issues/106751}: Optimize @code{KqueueSelector.select()} for many iteration case.
Patch By Donghee Na.

@item 
gh-106831@footnote{https://github.com/python/cpython/issues/106831}: Fix potential missing @code{NULL} check of @code{d2i_SSL_SESSION}
result in @code{_ssl.c}.

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: The various opcode lists in the @ref{38,,dis} module are now
generated from bytecodes.c instead of explicitly constructed in opcode.py.

@item 
gh-106727@footnote{https://github.com/python/cpython/issues/106727}: Make @ref{154d,,inspect.getsource()} smarter for class for same name
definitions

@item 
gh-106789@footnote{https://github.com/python/cpython/issues/106789}: Remove import of @ref{ad,,pprint} from @ref{da,,sysconfig}.

@item 
gh-105726@footnote{https://github.com/python/cpython/issues/105726}: Added @code{__slots__} to
@ref{c7b,,contextlib.AbstractContextManager} and
@ref{b19,,contextlib.AbstractAsyncContextManager} so that child classes can
use @code{__slots__}.

@item 
gh-106774@footnote{https://github.com/python/cpython/issues/106774}: Update the bundled copy of pip to version 23.2.1.

@item 
gh-106751@footnote{https://github.com/python/cpython/issues/106751}: @ref{c1,,selectors}: Optimize @code{EpollSelector.select()} code by
moving some code outside of the loop.

@item 
gh-106752@footnote{https://github.com/python/cpython/issues/106752}: Fixed several bugs in zipfile.Path, including: in
@code{zipfile.Path.match()}, Windows separators are no longer honored (and
never were meant to be); Fixed @code{name}/@code{suffix}/@code{suffixes}/@code{stem}
operations when no filename is present and the Path is not at the root of
the zipfile; Reworked glob for performance and more correct matching
behavior.

@item 
gh-105293@footnote{https://github.com/python/cpython/issues/105293}: Remove call to @code{SSL_CTX_set_session_id_context} during client
side context creation in the @ref{cf,,ssl} module.

@item 
gh-106734@footnote{https://github.com/python/cpython/issues/106734}: Disable tab completion in multiline mode of @ref{a4,,pdb}

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: Expose opcode metadata through @code{_opcode}.

@item 
gh-106670@footnote{https://github.com/python/cpython/issues/106670}: Add the new @code{exceptions} command to the Pdb debugger. It
makes it possible to move between chained exceptions when using post
mortem debugging.

@item 
gh-106602@footnote{https://github.com/python/cpython/issues/106602}: Add __copy__ and __deepcopy__ in @ref{55,,enum}

@item 
gh-106664@footnote{https://github.com/python/cpython/issues/106664}: @ref{c1,,selectors}: Add @code{_SelectorMapping.get()} method and
optimize @code{_SelectorMapping.__getitem__()}.

@item 
gh-106628@footnote{https://github.com/python/cpython/issues/106628}: Speed up parsing of emails by about 20% by not compiling a new
regular expression for every single email.

@item 
gh-89427@footnote{https://github.com/python/cpython/issues/89427}: Set the environment variable @code{VIRTUAL_ENV_PROMPT} at
@ref{110,,venv} activation, even when @code{VIRTUAL_ENV_DISABLE_PROMPT} is set.

@item 
gh-106530@footnote{https://github.com/python/cpython/issues/106530}: Revert a change to @ref{168b,,colorsys.rgb_to_hls()} that caused
division by zero for certain almost-white inputs.  Patch by Terry Jan
Reedy.

@item 
gh-106584@footnote{https://github.com/python/cpython/issues/106584}: Fix exit code for @code{unittest} if all tests are skipped. Patch
by Egor Eliseev.

@item 
gh-106566@footnote{https://github.com/python/cpython/issues/106566}: Optimize @code{(?!)} (pattern which always fails) in regular
expressions.

@item 
gh-106554@footnote{https://github.com/python/cpython/issues/106554}: @ref{c1,,selectors}: Reduce Selector overhead by using a
@code{dict.get()} to lookup file descriptors.

@item 
gh-106558@footnote{https://github.com/python/cpython/issues/106558}: Remove ref cycle in callers of
@code{convert_to_error()} by deleting @code{result}
from scope in a @code{finally} block.

@item 
gh-100502@footnote{https://github.com/python/cpython/issues/100502}: Add @code{pathlib.PurePath.pathmod} class attribute that
stores the implementation of @ref{a1,,os.path} used for low-level path
operations: either @code{posixpath} or @code{ntpath}.

@item 
gh-106527@footnote{https://github.com/python/cpython/issues/106527}: Reduce overhead to add and remove @ref{a,,asyncio} readers and
writers.

@item 
gh-106524@footnote{https://github.com/python/cpython/issues/106524}: Fix crash in @code{_sre.template()} with templates containing
invalid group indices.

@item 
gh-106531@footnote{https://github.com/python/cpython/issues/106531}: Removed @code{_legacy} and the names it provided from
@code{importlib.resources}: @code{Resource}, @code{contents}, @code{is_resource},
@code{open_binary}, @code{open_text}, @code{path}, @code{read_binary}, and
@code{read_text}.

@item 
gh-106052@footnote{https://github.com/python/cpython/issues/106052}: @ref{b8,,re} module: fix the matching of possessive quantifiers in
the case of a subpattern containing backtracking.

@item 
gh-106510@footnote{https://github.com/python/cpython/issues/106510}: Improve debug output for atomic groups in regular expressions.

@item 
gh-106503@footnote{https://github.com/python/cpython/issues/106503}: Fix ref cycle in @code{asyncio._SelectorSocketTransport} by
removing @code{_write_ready} in @code{close}.

@item 
gh-105497@footnote{https://github.com/python/cpython/issues/105497}: Fix flag mask inversion when unnamed flags exist.

@item 
gh-90876@footnote{https://github.com/python/cpython/issues/90876}: Prevent @code{multiprocessing.spawn} from failing to `import' in
environments where @code{sys.executable} is @code{None}.  This regressed in 3.11
with the addition of support for path-like objects in multiprocessing.

@item 
gh-106403@footnote{https://github.com/python/cpython/issues/106403}: Instances of @ref{15c,,typing.TypeVar},
@ref{15d,,typing.ParamSpec}, @ref{7b0,,typing.ParamSpecArgs},
@ref{7b1,,typing.ParamSpecKwargs}, and @ref{15e,,typing.TypeVarTuple} once
again support weak references, fixing a regression introduced in Python
3.12.0 beta 1. Patch by Jelle Zijlstra.

@item 
gh-89812@footnote{https://github.com/python/cpython/issues/89812}: Add private @code{pathlib._PathBase} class, which provides
experimental support for virtual filesystems, and may be made public in a
future version of Python.

@item 
gh-106292@footnote{https://github.com/python/cpython/issues/106292}: Check for an instance-dict cached value in the @code{__get__()}
method of @ref{52c,,functools.cached_property()}. This better matches the
pre-3.12 behavior and improves compatibility for users subclassing
@ref{52c,,functools.cached_property()} and adding a @code{__set__()} method.

@item 
gh-106350@footnote{https://github.com/python/cpython/issues/106350}: Detect possible memory allocation failure in the libtommath
function @code{mp_init()} used by the @code{_tkinter} module.

@item 
gh-106330@footnote{https://github.com/python/cpython/issues/106330}: Fix incorrect matching of empty paths in
@ref{496,,pathlib.PurePath.match()}. This bug was introduced in Python 3.12.0
beta 1.

@item 
gh-106309@footnote{https://github.com/python/cpython/issues/106309}: Deprecate @ref{2ae,,typing.no_type_check_decorator()}. No major type
checker ever added support for this decorator. Patch by Alex Waygood.

@item 
gh-102541@footnote{https://github.com/python/cpython/issues/102541}: Make @code{pydoc.doc()} catch bad module @ref{40f,,ImportError} when
output stream is not @code{None}.

@item 
gh-106263@footnote{https://github.com/python/cpython/issues/106263}: Fix crash when calling @code{repr} with a manually constructed
SignalDict object. Patch by Charlie Zhao.

@item 
gh-106236@footnote{https://github.com/python/cpython/issues/106236}: Replace @code{assert} statements with @code{raise RuntimeError} in
@ref{ec,,threading}, so that @code{_DummyThread} cannot be joined even with
@code{-OO}.

@item 
gh-106238@footnote{https://github.com/python/cpython/issues/106238}: Fix rare concurrency bug in lock acquisition by the logging
package.

@item 
gh-106152@footnote{https://github.com/python/cpython/issues/106152}: Added PY_THROW event hook for @ref{27,,cProfile} for generators

@item 
gh-106075@footnote{https://github.com/python/cpython/issues/106075}: Added @code{asyncio.taskgroups.__all__} to @code{asyncio.__all__} for
export in star imports.

@item 
gh-104527@footnote{https://github.com/python/cpython/issues/104527}: Zipapp will now skip over appending an archive to itself.

@item 
gh-106046@footnote{https://github.com/python/cpython/issues/106046}: Improve the error message from @ref{c41,,os.fspath()} if called on
an object where @code{__fspath__} is set to @code{None}. Patch by Alex Waygood.

@item 
gh-105987@footnote{https://github.com/python/cpython/issues/105987}: Fix crash due to improper reference counting in @ref{a,,asyncio}
eager task factory internal routines.

@item 
gh-105974@footnote{https://github.com/python/cpython/issues/105974}: Fix bug where a @ref{261,,typing.Protocol} class that had one or
more non-callable members would raise @ref{522,,TypeError} when
@ref{7ab,,issubclass()} was called against it, even if it defined a custom
@code{__subclasshook__} method. The behaviour in Python 3.11 and lower --
which has now been restored -- was not to raise @ref{522,,TypeError} in these
situations if a custom @code{__subclasshook__} method was defined. Patch by
Alex Waygood.

@item 
gh-96145@footnote{https://github.com/python/cpython/issues/96145}: Reverted addition of @code{json.AttrDict}.

@item 
gh-89812@footnote{https://github.com/python/cpython/issues/89812}: Add @ref{224,,pathlib.UnsupportedOperation}, which is raised instead
of @ref{225,,NotImplementedError} when a path operation isn't supported.

@item 
gh-105808@footnote{https://github.com/python/cpython/issues/105808}: Fix a regression introduced in gh-101251@footnote{https://github.com/python/cpython/issues/101251} for 3.12, causing
@code{gzip.GzipFile.flush()} to not flush the compressor (nor pass along
the @code{zip_mode} argument).

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: @ref{f1c,,stack_effect()} no longer raises an exception if an
@code{oparg} is provided for an @code{opcode} that doesn't use its arg, or when
it is not provided for an @code{opcode} that does use it. In the latter case,
the stack effect is returned for @code{oparg=0}.

@item 
gh-104799@footnote{https://github.com/python/cpython/issues/104799}: Enable @ref{8d2,,ast.unparse()} to unparse function and class
definitions created without the new @code{type_params} field from 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.
Patch by Jelle Zijlstra.

@item 
gh-105793@footnote{https://github.com/python/cpython/issues/105793}: Add `follow_symlinks' keyword-only argument to
@ref{22d,,pathlib.Path.is_dir()} and @ref{22c,,is_file()}, defaulting
to @code{True}.

@item 
gh-105570@footnote{https://github.com/python/cpython/issues/105570}: Deprecate two methods of creating @ref{161,,typing.TypedDict}
classes with 0 fields using the functional syntax: @code{TD =
TypedDict("TD")} and @code{TD = TypedDict("TD", None)}. Both will be
disallowed in Python 3.15. To create a @code{TypedDict} class with 0 fields,
either use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}.

@item 
gh-105745@footnote{https://github.com/python/cpython/issues/105745}: Fix @code{webbrowser.Konqueror.open} method.

@item 
gh-105733@footnote{https://github.com/python/cpython/issues/105733}: @ref{2a,,ctypes}: Deprecate undocumented
@code{ctypes.SetPointerType()} and @code{ctypes.ARRAY()} functions. Patch
by Victor Stinner.

@item 
gh-105687@footnote{https://github.com/python/cpython/issues/105687}: Remove deprecated @code{re.template}, @code{re.T}, @code{re.TEMPLATE},
@code{sre_constans.SRE_FLAG_TEMPLATE}.

@item 
gh-105684@footnote{https://github.com/python/cpython/issues/105684}: Supporting @ref{9cb,,asyncio.Task.set_name()} is now mandatory for
third party task implementations. The undocumented @code{_set_task_name()}
function (deprecated since 3.8) has been removed. Patch by Kumar Aditya.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix a bug in @code{_Unpickler_SetInputStream()} where an
exception could end up being overwritten in case of failure.

@item 
gh-105626@footnote{https://github.com/python/cpython/issues/105626}: Change the default return value of
@ref{168c,,http.client.HTTPConnection.get_proxy_response_headers()} to be
@code{None} and not @code{@{@}}.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{d8,,sys} where exceptions could end up being
overwritten because of deferred error handling.

@item 
gh-105605@footnote{https://github.com/python/cpython/issues/105605}: Harden @code{pyexpat} error handling during module
initialisation to prevent exceptions from possibly being overwritten, and
objects from being dereferenced twice.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bug in @ref{36,,decimal} where an exception could end up being
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @code{_datetime} where exceptions could be
overwritten in case of module initialisation failure.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @code{_ssl} initialisation which could lead to
leaked references and overwritten exceptions.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix a bug in @ref{19e,,array.array} where an exception could end
up being overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @code{_ctypes} where exceptions could end up being
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix a bug in the @ref{ac,,posix} module where an exception could
be overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @code{_elementtree} where exceptions could be
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{133,,zoneinfo} where exceptions could be
overwritten.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{56,,errno} where exceptions could be overwritten.

@item 
gh-105566@footnote{https://github.com/python/cpython/issues/105566}: Deprecate creating a @ref{2ad,,typing.NamedTuple} class using
keyword arguments to denote the fields (@code{NT = NamedTuple("NT", x=int,
y=str)}). This will be disallowed in Python 3.15. Use the class-based
syntax or the functional syntax instead.

Two methods of creating @code{NamedTuple} classes with 0 fields using the
functional syntax are also deprecated, and will be disallowed in Python
3.15: @code{NT = NamedTuple("NT")} and @code{NT = NamedTuple("NT", None)}. To
create a @code{NamedTuple} class with 0 fields, either use @code{class
NT(NamedTuple): pass} or @code{NT = NamedTuple("NT", [])}.

@item 
gh-105545@footnote{https://github.com/python/cpython/issues/105545}: Remove deprecated in 3.11 @code{webbrowser.MacOSXOSAScript._name}
attribute.

@item 
gh-105497@footnote{https://github.com/python/cpython/issues/105497}: Fix flag inversion when alias/mask members exist.

@item 
gh-105509@footnote{https://github.com/python/cpython/issues/105509}: @ref{92a,,typing.Annotated} is now implemented as an instance of
@code{typing._SpecialForm} rather than a class. This should have no
user-facing impact for users of the @ref{103,,typing} module public API.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix bugs in @ref{a5,,pickle} where exceptions could be
overwritten.

@item 
gh-70303@footnote{https://github.com/python/cpython/issues/70303}: Emit @ref{40b,,FutureWarning} from @ref{22a,,pathlib.Path.glob()} and
@ref{22b,,rglob()} if the given pattern ends with "@code{**}". In a
future Python release, patterns with this ending will match both files and
directories. Add a trailing slash to only match directories.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix a bug in @ref{ce,,sqlite3} where an exception could be
overwritten in the @ref{661,,collation}
callback.

@item 
gh-105382@footnote{https://github.com/python/cpython/issues/105382}: Remove `cafile', `capath' and `cadefault' parameters of the
@ref{290,,urllib.request.urlopen()} function, deprecated in Python 3.6. Patch
by Victor Stinner.

@item 
gh-105376@footnote{https://github.com/python/cpython/issues/105376}: @ref{86,,logging}: Remove undocumented and untested
@code{Logger.warn()} and @code{LoggerAdapter.warn()} methods and
@code{logging.warn()} function. Deprecated since Python 3.3, they were
aliases to the @ref{168d,,logging.Logger.warning()} method,
@code{logging.LoggerAdapter.warning()} method and @ref{2f3,,logging.warning()}
function. Patch by Victor Stinner.

@item 
gh-105332@footnote{https://github.com/python/cpython/issues/105332}: Revert pickling method from by-name back to by-value.

@item 
gh-104554@footnote{https://github.com/python/cpython/issues/104554}: Add RTSPS scheme support in urllib.parse

@item 
gh-105292@footnote{https://github.com/python/cpython/issues/105292}: Add option to @ref{838,,traceback.format_exception_only()} to
recurse into the nested exception of a @ref{25c,,BaseExceptionGroup}.

@item 
gh-105280@footnote{https://github.com/python/cpython/issues/105280}: Fix bug where @code{isinstance([], collections.abc.Mapping)} could
evaluate to @code{True} if garbage collection happened at the wrong time. The
bug was caused by changes to the implementation of
@ref{261,,typing.Protocol} in Python 3.12.

@item 
gh-80480@footnote{https://github.com/python/cpython/issues/80480}: @ref{7,,array}: Add @code{'w'} typecode that represents @code{Py_UCS4}.

@item 
gh-105239@footnote{https://github.com/python/cpython/issues/105239}: Fix longstanding bug where @code{issubclass(object,
typing.Protocol)} would evaluate to @code{True} in some edge cases. Patch by
Alex Waygood.

@item 
gh-104310@footnote{https://github.com/python/cpython/issues/104310}: In the beta 1 release we added a utility function for extension
module authors, to use when testing their module for support in multiple
interpreters or under a per-interpreter GIL.  The name of that function
has changed from @code{allowing_all_extensions} to
@code{_incompatible_extension_module_restrictions}.  The default for the
"disable_check" argument has change from @code{True} to @code{False}, to better
match the new function name.

@item 
gh-105080@footnote{https://github.com/python/cpython/issues/105080}: Fixed inconsistent signature on derived classes for
@ref{722,,inspect.signature()}

@item 
gh-105144@footnote{https://github.com/python/cpython/issues/105144}: Fix a recent regression in the @ref{103,,typing} module. The
regression meant that doing @code{class Foo(X, typing.Protocol)}, where @code{X}
was a class that had @ref{f03,,abc.ABCMeta} as its metaclass, would then
cause subsequent @code{isinstance(1, X)} calls to erroneously raise
@ref{522,,TypeError}. Patch by Alex Waygood.

@item 
gh-62948@footnote{https://github.com/python/cpython/issues/62948}: The @ref{1f2,,io.IOBase} finalizer now logs the @code{close()} method
errors with @ref{1f4,,sys.unraisablehook}. Previously, errors were ignored
silently by default, and only logged in @ref{1f5,,Python Development Mode} or on @ref{1f6,,Python built on debug mode}.  Patch
by Victor Stinner.

@item 
gh-105096@footnote{https://github.com/python/cpython/issues/105096}: @ref{112,,wave}: Deprecate the @code{getmark()}, @code{setmark()} and
@code{getmarkers()} methods of the @ref{2b3,,wave.Wave_read} and
@ref{2b4,,wave.Wave_write} classes. They will be removed in Python 3.15.
Patch by Victor Stinner.

@item 
gh-104992@footnote{https://github.com/python/cpython/issues/104992}: Remove the untested and undocumented
@code{unittest.TestProgram.usageExit()} method, deprecated in Python 3.11.
Patch by Hugo van Kemenade.

@item 
gh-104996@footnote{https://github.com/python/cpython/issues/104996}: Improve performance of @ref{490,,pathlib.PurePath} initialisation
by deferring joining of paths when multiple arguments are given.

@item 
gh-101588@footnote{https://github.com/python/cpython/issues/101588}: Deprecate undocumented copy/deepcopy/pickle support for
itertools.

@item 
gh-103631@footnote{https://github.com/python/cpython/issues/103631}: Fix @code{pathlib.PurePosixPath(pathlib.PureWindowsPath(...))} not
converting path separators to restore 3.11 compatible behavior.

@item 
gh-104947@footnote{https://github.com/python/cpython/issues/104947}: Make comparisons between @ref{168e,,pathlib.PureWindowsPath}
objects consistent across Windows and Posix to match 3.11 behavior.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{audioop} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{aifc} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{uu} module, deprecated in Python
3.11. Patch by Victor Stinner.

@item 
gh-104935@footnote{https://github.com/python/cpython/issues/104935}: Fix bugs with the interaction between
@ref{42c,,typing.runtime_checkable()} and @ref{15a1,,typing.Generic} that were
introduced by the 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} implementation. Patch by Jelle Zijlstra.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{crypt} module and its private
@code{_crypt} extension, deprecated in Python 3.11. Patch by Victor
Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{nis} module, deprecated in Python
3.11. Patch by Victor Stinner.

@item 
gh-104898@footnote{https://github.com/python/cpython/issues/104898}: Add missing @ref{14a0,,__slots__} to @ref{c3f,,os.PathLike}.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{xdrlib} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{nntplib} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104886@footnote{https://github.com/python/cpython/issues/104886}: Remove the undocumented
@code{configparser.LegacyInterpolation} class, deprecated in the
docstring since Python 3.2, and with a deprecation warning since Python
3.11. Patch by Hugo van Kemenade.

@item 
gh-104786@footnote{https://github.com/python/cpython/issues/104786}: Remove kwargs-based @ref{161,,typing.TypedDict} creation

@item 
gh-104876@footnote{https://github.com/python/cpython/issues/104876}: Remove the @code{turtle.RawTurtle.settiltangle()} method,
deprecated in docs since Python 3.1 and with a deprecation warning since
Python 3.11. Patch by Hugo van Kemenade.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Removed the @code{msilib} package, deprecated in
Python 3.11.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{spwd} module, deprecated in
Python 3.11: the python-pam@footnote{https://pypi.org/project/python-pam/} project can be used instead. Patch by
Victor Stinner.

@item 
gh-75552@footnote{https://github.com/python/cpython/issues/75552}: Removed the @code{tkinter.tix} module, deprecated since Python 3.6.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{chunk} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{mailcap} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{sunau} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104780@footnote{https://github.com/python/cpython/issues/104780}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{ossaudiodev} module, deprecated
in Python 3.11. Patch Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{pipes} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104873@footnote{https://github.com/python/cpython/issues/104873}: Add @ref{260,,typing.get_protocol_members()} to return the set of
members defining a @ref{261,,typing.Protocol}.  Add
@ref{262,,typing.is_protocol()} to check whether a class is a
@ref{261,,typing.Protocol}. Patch by Jelle Zijlstra.

@item 
gh-104874@footnote{https://github.com/python/cpython/issues/104874}: Document the @code{__name__} and @code{__supertype__} attributes of
@ref{ce3,,typing.NewType}. Patch by Jelle Zijlstra.

@item 
gh-104835@footnote{https://github.com/python/cpython/issues/104835}: Removed the following @ref{105,,unittest} functions, deprecated in
Python 3.11:


@itemize *

@item 
@code{unittest.findTestCases()}

@item 
@code{unittest.makeSuite()}

@item 
@code{unittest.getTestCaseNames()}
@end itemize

Use @ref{28b,,TestLoader} methods instead:


@itemize *

@item 
@ref{28c,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{28d,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{28e,,unittest.TestLoader.getTestCaseNames()}
@end itemize

Patch by Hugo van Kemenade.

@item 
gh-104804@footnote{https://github.com/python/cpython/issues/104804}: Remove the untested and undocumented @ref{114,,webbrowser}
@code{MacOSX} class, deprecated in Python 3.11. Patch by Hugo van
Kemenade.

@item 
gh-83863@footnote{https://github.com/python/cpython/issues/83863}: Support for using @ref{226,,pathlib.Path} objects as context
managers has been removed. Before Python 3.9, exiting the context manager
marked a path as "closed", which caused some (but not all!) methods to
raise when called. Since Python 3.9, using a path as a context manager
does nothing.

@item 
gh-104799@footnote{https://github.com/python/cpython/issues/104799}: Adjust the location of the (see 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}) @code{type_params}
field on @ref{168f,,ast.ClassDef}, @ref{1690,,ast.AsyncFunctionDef}, and
@ref{1691,,ast.FunctionDef} to better preserve backward compatibility. Patch
by Jelle Zijlstra

@item 
gh-104797@footnote{https://github.com/python/cpython/issues/104797}: Allow @ref{261,,typing.Protocol} classes to inherit from
@ref{2c1,,collections.abc.Buffer}. Patch by Jelle Zijlstra.

@item 
gh-104783@footnote{https://github.com/python/cpython/issues/104783}: Remove @code{locale.resetlocale()} function deprecated in Python
3.11. Patch by Victor Stinner.

@item 
gh-104780@footnote{https://github.com/python/cpython/issues/104780}: Remove the @code{2to3} program and the @code{lib2to3} module,
deprecated in Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{telnetlib} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{imghdr} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{cgi} and @code{cgitb} modules,
deprecated in Python 3.11. Patch by Victor Stinner.

@item 
gh-104773@footnote{https://github.com/python/cpython/issues/104773}: 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}: Remove the @code{sndhdr} module, deprecated in
Python 3.11. Patch by Victor Stinner.

@item 
gh-104372@footnote{https://github.com/python/cpython/issues/104372}: On Linux where @ref{d5,,subprocess} can use the @code{vfork()}
syscall for faster spawning, prevent the parent process from blocking
other threads by dropping the GIL while it waits for the vfork'ed child
process @code{exec()} outcome. This prevents spawning a binary from a slow
filesystem from blocking the rest of the application.

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: We now release the GIL around built-in @ref{67,,hashlib}
computations of reasonable size for the SHA families and MD5 hash
functions, matching what our OpenSSL backed hash computations already
does.

@item 
gh-102613@footnote{https://github.com/python/cpython/issues/102613}: Improve performance of @ref{22a,,pathlib.Path.glob()} when expanding
a pattern with a non-terminal "@code{**}" component by filtering walked paths
through a regular expression, rather than calling @ref{a4d,,os.scandir()} more
than once on each directory.

@item 
gh-104399@footnote{https://github.com/python/cpython/issues/104399}: Prepare the @code{_tkinter} module for building with Tcl 9.0 and
future libtommath by replacing usage of deprecated functions
@code{mp_to_unsigned_bin_n()} and @code{mp_unsigned_bin_size()} when
necessary.

@item 
gh-102676@footnote{https://github.com/python/cpython/issues/102676}: Add fields @code{start_offset}, @code{cache_offset}, @code{end_offset},
@code{baseopname}, @code{baseopcode}, @code{jump_target} and @code{oparg} to
@ref{1d7,,dis.Instruction}.

@item 
gh-103558@footnote{https://github.com/python/cpython/issues/103558}: Fixed @code{parent} argument validation mechanism of
@ref{6,,argparse}. Improved test coverage.

@item 
gh-103464@footnote{https://github.com/python/cpython/issues/103464}: Provide helpful usage messages when parsing incorrect
@ref{a4,,pdb} commands.

@item 
gh-103384@footnote{https://github.com/python/cpython/issues/103384}: Generalize the regex pattern @code{BaseConfigurator.INDEX_PATTERN}
to allow spaces and non-alphanumeric characters in keys.

@item 
gh-103124@footnote{https://github.com/python/cpython/issues/103124}: Added multiline statement support for @ref{a4,,pdb}

@item 
gh-101162@footnote{https://github.com/python/cpython/issues/101162}: Forbid using @code{builtins.issubclass()} with
@ref{7d5,,types.GenericAlias} as the first argument.

@item 
gh-103200@footnote{https://github.com/python/cpython/issues/103200}: Fix cache repopulation semantics of
zipimport.invalidate_caches(). The cache is now repopulated upon
retrieving files with an invalid cache, not when the cache is invalidated.

@item 
gh-100061@footnote{https://github.com/python/cpython/issues/100061}: Fix a bug that causes wrong matches for regular expressions
with possessive qualifier.

@item 
gh-77609@footnote{https://github.com/python/cpython/issues/77609}: Add `follow_symlinks' argument to @ref{22a,,pathlib.Path.glob()} and
@ref{22b,,rglob()}, defaulting to false.

@item 
gh-102541@footnote{https://github.com/python/cpython/issues/102541}: Hide traceback in @ref{8c4,,help()} prompt, when import failed.

@item 
gh-102120@footnote{https://github.com/python/cpython/issues/102120}: Added a stream mode to @code{tarfile} that allows for reading
archives without caching info about the inner files.

@item 
gh-102029@footnote{https://github.com/python/cpython/issues/102029}: Deprecate passing any arguments to @ref{2dc,,threading.RLock()}.

@item 
gh-88233@footnote{https://github.com/python/cpython/issues/88233}: Refactored @code{zipfile._strip_extra} to use higher level
abstractions for extras instead of a heavy-state loop.

@item 
gh-102024@footnote{https://github.com/python/cpython/issues/102024}: Reduce calls of @code{_idle_semaphore.release()} in
@code{concurrent.futures.thread._worker()}.

@item 
gh-73435@footnote{https://github.com/python/cpython/issues/73435}: Add support for recursive wildcards in
@ref{496,,pathlib.PurePath.match()}.

@item 
gh-84867@footnote{https://github.com/python/cpython/issues/84867}: @ref{28b,,unittest.TestLoader} no longer loads test cases from
exact @ref{437,,unittest.TestCase} and @ref{1692,,unittest.FunctionTestCase}
classes.

@item 
gh-99203@footnote{https://github.com/python/cpython/issues/99203}: Restore following CPython <= 3.10.5 behavior of
@ref{49c,,shutil.make_archive()}: do not create an empty archive if
@code{root_dir} is not a directory, and, in that case, raise
@ref{eae,,FileNotFoundError} or @ref{1043,,NotADirectoryError} regardless of
@code{format} choice. Beyond the brought-back behavior, the function may now
also raise these exceptions in @code{dry_run} mode.

@item 
gh-80480@footnote{https://github.com/python/cpython/issues/80480}: Emit @ref{1a3,,DeprecationWarning} for @ref{7,,array}'s @code{'u'} type
code, deprecated in docs since Python 3.3.

@item 
gh-94924@footnote{https://github.com/python/cpython/issues/94924}: @ref{1590,,unittest.mock.create_autospec()} now properly returns
coroutine functions compatible with @ref{2e2,,inspect.iscoroutinefunction()}

@item 
gh-94777@footnote{https://github.com/python/cpython/issues/94777}: Fix hanging @ref{93,,multiprocessing} @code{ProcessPoolExecutor} when
a child process crashes while data is being written in the call queue.

@item 
gh-92871@footnote{https://github.com/python/cpython/issues/92871}: Remove the @code{typing.io} and @code{typing.re} namespaces,
deprecated since Python 3.8. All items are still available from the main
@ref{103,,typing} module.

@item 
bpo-43633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43633}: Improve the textual representation of IPv4-mapped IPv6
addresses (
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html} Sections 2.2, 2.5.5.2) in @ref{7f,,ipaddress}. Patch
by Oleksandr Pavliuk.

@item 
bpo-44850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44850}: Improve performance of @ref{e21,,operator.methodcaller()} using the
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} @code{vectorcall} convention. Patch by Anthony Lee and Pieter
Eendebak.

@item 
bpo-44185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44185}: @ref{1693,,unittest.mock.mock_open()} will call the @code{close()}
method of the file handle mock when it is exiting from the context
manager. Patch by Samet Yaslan.

@item 
bpo-40988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40988}: Improve performance of @ref{9de,,functools.singledispatchmethod}
by caching the generated dispatch wrapper. Optimization suggested by
frederico. Patch by @@mental32, Alex Waygood and Pieter Eendebak.

@item 
bpo-41768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41768}: @ref{106,,unittest.mock} speccing no longer calls class properties.
Patch by Melanie Witt.

@item 
bpo-18319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18319}: Ensure @code{gettext(msg)} retrieve translations even if a plural
form exists. In other words: @code{gettext(msg) == ngettext(msg, '@w{'}, 1)}.

@item 
bpo-17013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17013}: Add @code{ThreadingMock} to @ref{106,,unittest.mock} that can be used
to create Mock objects that can wait until they are called. Patch by
Karthikeyan Singaravelan and Mario Corchero.
@end itemize

@node Documentation<10>,Tests<13>,Library<15>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id115}@anchor{1694}
@subsubsection Documentation



@itemize -

@item 
gh-109209@footnote{https://github.com/python/cpython/issues/109209}: The minimum Sphinx version required for the documentation is
now 4.2.

@item 
gh-108826@footnote{https://github.com/python/cpython/issues/108826}: @ref{38,,dis} module command-line interface is now mentioned in
documentation.

@item 
gh-107305@footnote{https://github.com/python/cpython/issues/107305}: Add documentation for @ref{559,,PyInterpreterConfig} and
@ref{445,,Py_NewInterpreterFromConfig()}.  Also clarify some of the nearby
docs relative to per-interpreter GIL.

@item 
gh-107008@footnote{https://github.com/python/cpython/issues/107008}: Document the @ref{2b,,curses} module variables
@ref{1695,,LINES} and @ref{1696,,COLS}.

@item 
gh-106948@footnote{https://github.com/python/cpython/issues/106948}: Add a number of standard external names to @code{nitpick_ignore}.

@item 
gh-106232@footnote{https://github.com/python/cpython/issues/106232}: Make timeit doc command lines compatible with Windows by using
double quotes for arguments.  This works on linux and macOS also.

@item 
gh-105172@footnote{https://github.com/python/cpython/issues/105172}: Fixed @ref{9dd,,functools.lru_cache()} docstring accounting for
@code{typed} argument's different handling of str and int. Patch by Bar
Harel.

@item 
gh-105052@footnote{https://github.com/python/cpython/issues/105052}: Update @code{timeit} doc to specify that time in seconds is just
the default.

@item 
gh-89455@footnote{https://github.com/python/cpython/issues/89455}: Add missing documentation for the @code{max_group_depth} and
@code{max_group_width} parameters and the @code{exceptions} attribute of the
@ref{259,,traceback.TracebackException} class.

@item 
gh-89412@footnote{https://github.com/python/cpython/issues/89412}: Add missing documentation for the @code{end_lineno} and
@code{end_offset} attributes of the @ref{259,,traceback.TracebackException}
class.

@item 
gh-104943@footnote{https://github.com/python/cpython/issues/104943}: Remove mentions of old Python versions in
@ref{2ad,,typing.NamedTuple}.

@item 
gh-54738@footnote{https://github.com/python/cpython/issues/54738}: Add documentation on how to localize the @ref{6,,argparse} module.

@item 
gh-102823@footnote{https://github.com/python/cpython/issues/102823}: Document the return type of @code{x // y} when @code{x} and @code{y}
have type @ref{2eb,,float}.

@item 
gh-102759@footnote{https://github.com/python/cpython/issues/102759}: Align function signature for @code{functools.reduce} in
documentation and docstring with the C implementation.
@end itemize

@node Tests<13>,Build<15>,Documentation<10>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id116}@anchor{1697}
@subsubsection Tests



@itemize -

@item 
gh-110647@footnote{https://github.com/python/cpython/issues/110647}: Fix test_stress_modifying_handlers() of test_signal. Patch by
Victor Stinner.

@item 
gh-103053@footnote{https://github.com/python/cpython/issues/103053}: Fix test_tools.test_freeze on FreeBSD: run "make distclean"
instead of "make clean" in the copied source directory to remove also the
"python" program. Patch by Victor Stinner.

@item 
gh-110167@footnote{https://github.com/python/cpython/issues/110167}: Fix a deadlock in test_socket when server fails with a timeout
but the client is still running in its thread. Don't hold a lock to call
cleanup functions in doCleanups(). One of the cleanup function waits until
the client completes, whereas the client could deadlock if it called
addCleanup() in such situation. Patch by Victor Stinner.

@item 
gh-110388@footnote{https://github.com/python/cpython/issues/110388}: Add tests for @ref{ff,,tty}.

@item 
gh-81002@footnote{https://github.com/python/cpython/issues/81002}: Add tests for @ref{e0,,termios}.

@item 
gh-110367@footnote{https://github.com/python/cpython/issues/110367}: regrtest: When using worker processes (-jN) with --verbose3
option, regrtest can now display the worker output even if a worker
process does crash. Previously, sys.stdout and sys.stderr were replaced
and so the worker output was lost on a crash. Patch by Victor Stinner.

@item 
gh-110267@footnote{https://github.com/python/cpython/issues/110267}: Add tests for pickling and copying PyStructSequence objects.
Patched by Xuehai Pan.

@item 
gh-110171@footnote{https://github.com/python/cpython/issues/110171}: @code{libregrtest} now always sets and shows @code{random.seed}, so
tests are more reproducible. Use @code{--randseed} flag to pass the explicit
random seed for tests.

@item 
gh-110152@footnote{https://github.com/python/cpython/issues/110152}: Remove @code{Tools/scripts/run_tests.py} and @code{make
hostrunnertest}. Just run @code{./python -m test --slow-ci}, @code{make
buildbottest} or @code{make test} instead. Python test runner (regrtest) now
handles cross-compilation and HOSTRUNNER. It also adds options to Python
such fast @code{-u -E -W default -bb} when @code{--fast-ci} or @code{--slow-ci}
option is used. Patch by Victor Stinner.

@item 
gh-110031@footnote{https://github.com/python/cpython/issues/110031}: Skip test_threading tests using thread+fork if Python is built
with Address Sanitizer (ASAN). Patch by Victor Stinner.

@item 
gh-110088@footnote{https://github.com/python/cpython/issues/110088}: Fix test_asyncio timeouts: don't measure the maximum duration,
a test should not measure a CI performance. Only measure the minimum
duration when a task has a timeout or delay. Add @code{CLOCK_RES} to
@code{test_asyncio.utils}. Patch by Victor Stinner.

@item 
gh-109974@footnote{https://github.com/python/cpython/issues/109974}: Fix race conditions in test_threading lock tests. Wait until a
condition is met rather than using @ref{688,,time.sleep()} with a hardcoded
number of seconds. Patch by Victor Stinner.

@item 
gh-110033@footnote{https://github.com/python/cpython/issues/110033}: Fix @code{test_interprocess_signal()} of @code{test_signal}. Make
sure that the @code{subprocess.Popen} object is deleted before the test
raising an exception in a signal handler. Otherwise, @code{Popen.__del__()}
can get the exception which is logged as @code{Exception ignored in: ...} and
the test fails. Patch by Victor Stinner.

@item 
gh-109594@footnote{https://github.com/python/cpython/issues/109594}: Fix test_timeout() of test_concurrent_futures.test_wait. Remove
the future which may or may not complete depending if it takes longer than
the timeout or not. Keep the second future which does not complete before
wait() timeout. Patch by Victor Stinner.

@item 
gh-109972@footnote{https://github.com/python/cpython/issues/109972}: Split test_gdb.py file into a test_gdb package made of multiple
tests, so tests can now be run in parallel. Patch by Victor Stinner.

@item 
gh-109566@footnote{https://github.com/python/cpython/issues/109566}: regrtest: When @code{--fast-ci} or @code{--slow-ci} option is used,
regrtest now replaces the current process with a new process to add @code{-u
-W default -bb -E} options to Python. Patch by Victor Stinner.

@item 
gh-109748@footnote{https://github.com/python/cpython/issues/109748}: Fix @code{test_zippath_from_non_installed_posix()} of test_venv:
don't copy @code{__pycache__/} sub-directories, because they can be modified
by other Python tests running in parallel. Patch by Victor Stinner.

@item 
gh-109739@footnote{https://github.com/python/cpython/issues/109739}: regrtest: Fix reference leak check on Windows. Disable the load
tracker on Windows in the reference leak check mode (-R option). Patch by
Victor Stinner.

@item 
gh-109276@footnote{https://github.com/python/cpython/issues/109276}: regrtest: When a test fails with "env changed" and the --rerun
option is used, the test is now re-run in verbose mode in a fresh process.
Patch by Victor Stinner.

@item 
gh-103053@footnote{https://github.com/python/cpython/issues/103053}: Skip test_freeze_simple_script() of test_tools.test_freeze if
Python is built with @code{./configure --enable-optimizations}, which means
with Profile Guided Optimization (PGO): it just makes the test too slow.
The freeze tool is tested by many other CIs with other (faster) compiler
flags. Patch by Victor Stinner.

@item 
gh-109580@footnote{https://github.com/python/cpython/issues/109580}: Skip @code{test_perf_profiler} if Python is built with ASAN, MSAN
or UBSAN sanitizer. Python does crash randomly in this test on such build.
Patch by Victor Stinner.

@item 
gh-109566@footnote{https://github.com/python/cpython/issues/109566}: regrtest: Add @code{--fast-ci} and @code{--slow-ci} options.
@code{--fast-ci} uses a default timeout of 10 minutes and @code{-u all,-cpu}
(skip slowest tests). @code{--slow-ci} uses a default timeout of 20 minutes
and @code{-u all} (run all tests). Patch by Victor Stinner.

@item 
gh-109425@footnote{https://github.com/python/cpython/issues/109425}: libregrtest now decodes stdout of test worker processes with
the "backslashreplace" error handler to log corrupted stdout, instead of
failing with an error and not logging the stdout. Patch by Victor Stinner.

@item 
gh-109396@footnote{https://github.com/python/cpython/issues/109396}: Fix @code{test_socket.test_hmac_sha1()} in FIPS mode. Use a longer
key: FIPS mode requires at least of at least 112 bits. The previous key
was only 32 bits. Patch by Victor Stinner.

@item 
gh-104736@footnote{https://github.com/python/cpython/issues/104736}: Fix test_gdb on Python built with LLVM clang 16 on Linux
ppc64le (ex: Fedora 38). Search patterns in gdb "bt" command output to
detect when gdb fails to retrieve the traceback. For example, skip a test
if @code{Backtrace stopped: frame did not save the PC} is found. Patch by
Victor Stinner.

@item 
gh-109276@footnote{https://github.com/python/cpython/issues/109276}: libregrtest now calls @ref{1252,,random.seed()} before running each
test file when @code{-r/--randomize} command line option is used. Moreover,
it's also called in worker processes.  It should help to make tests more
deterministic. Previously, it was only called once in the main process
before running all test files and it was not called in worker processes.
Patch by Victor Stinner.

@item 
gh-109276@footnote{https://github.com/python/cpython/issues/109276}: libregrtest now uses a separated file descriptor to write test
result as JSON. Previously, if a test wrote debug messages late around the
JSON, the main test process failed to parse JSON. Patch by Victor Stinner.

@item 
gh-108996@footnote{https://github.com/python/cpython/issues/108996}: Fix and enable @code{test_msvcrt}.

@item 
gh-109237@footnote{https://github.com/python/cpython/issues/109237}: Fix @code{test_site.test_underpth_basic()} when the working
directory contains at least one non-ASCII character: encode the @code{._pth}
file to UTF-8 and enable the UTF-8 Mode to use UTF-8 for the child process
stdout. Patch by Victor Stinner.

@item 
gh-109230@footnote{https://github.com/python/cpython/issues/109230}: Fix @code{test_pyexpat.test_exception()}: it can now be run from a
directory different than Python source code directory. Before, the test
failed in this case.  Skip the test if Modules/pyexpat.c source is not
available. Skip also the test on Python implementations other than
CPython. Patch by Victor Stinner.

@item 
gh-108996@footnote{https://github.com/python/cpython/issues/108996}: Add tests for @code{msvcrt}.

@item 
gh-109015@footnote{https://github.com/python/cpython/issues/109015}: Fix test_asyncio, test_imaplib and test_socket tests on FreeBSD
if the TCP blackhole is enabled (@code{sysctl net.inet.tcp.blackhole}). Skip
the few tests which failed with @code{ETIMEDOUT} which such non standard
configuration. Currently, the FreeBSD GCP image enables TCP and UDP blackhole@footnote{https://reviews.freebsd.org/D41751} (@code{sysctl
net.inet.tcp.blackhole=2} and @code{sysctl net.inet.udp.blackhole=1}).
Patch by Victor Stinner.

@item 
gh-91960@footnote{https://github.com/python/cpython/issues/91960}: Skip @code{test_gdb} if gdb is unable to retrieve Python frame
objects: if a frame is @code{<optimized out>}. When Python is built with
"clang -Og", gdb can fail to retrieve the `frame' parameter of
@code{_PyEval_EvalFrameDefault()}. In this case, tests like @code{py_bt()} are
likely to fail. Without getting access to Python frames, @code{python-gdb.py}
is mostly clueless on retrieving the Python traceback. Moreover,
@code{test_gdb} is no longer skipped on macOS if Python is built with Clang.
Patch by Victor Stinner.

@item 
gh-108962@footnote{https://github.com/python/cpython/issues/108962}: Skip @code{test_tempfile.test_flags()} if @code{chflags()} fails with
"OSError: [Errno 45] Operation not supported" (ex: on FreeBSD 13). Patch
by Victor Stinner.

@item 
gh-91960@footnote{https://github.com/python/cpython/issues/91960}: FreeBSD 13.2 CI coverage for pull requests is now provided by
Cirrus-CI (a hosted CI service that supports Linux, macOS, Windows, and
FreeBSD).

@item 
gh-89392@footnote{https://github.com/python/cpython/issues/89392}: Removed support of @code{test_main()} function in tests. They now
always use normal unittest test runner.

@item 
gh-108851@footnote{https://github.com/python/cpython/issues/108851}: Fix @code{test_tomllib} recursion tests for WASI buildbots: reduce
the recursion limit and compute the maximum nested array/dict depending on
the current available recursion limit. Patch by Victor Stinner.

@item 
gh-108851@footnote{https://github.com/python/cpython/issues/108851}: Add @code{get_recursion_available()} and @code{get_recursion_depth()}
functions to the @ref{e3,,test.support} module. Patch by Victor Stinner.

@item 
gh-108834@footnote{https://github.com/python/cpython/issues/108834}: Add @code{--fail-rerun option} option to regrtest: if a test
failed when then passed when rerun in verbose mode, exit the process with
exit code 2 (error), instead of exit code 0 (success). Patch by Victor
Stinner.

@item 
gh-108834@footnote{https://github.com/python/cpython/issues/108834}: Rename regrtest @code{--verbose2} option (@code{-w}) to @code{--rerun}.
Keep @code{--verbose2} as a deprecated alias. Patch by Victor Stinner.

@item 
gh-108834@footnote{https://github.com/python/cpython/issues/108834}: When regrtest reruns failed tests in verbose mode (@code{./python
-m test --rerun}), tests are now rerun in fresh worker processes rather
than being executed in the main process. If a test does crash or is killed
by a timeout, the main process can detect and handle the killed worker
process. Tests are rerun in parallel if the @code{-jN} option is used to run
tests in parallel. Patch by Victor Stinner.

@item 
gh-108822@footnote{https://github.com/python/cpython/issues/108822}: @code{regrtest} now computes statistics on all tests: successes,
failures and skipped. @code{test_netrc}, @code{test_pep646_syntax} and
@code{test_xml_etree} now return results in their @code{test_main()} function.
Patch by Victor Stinner and Alex Waygood.

@item 
gh-108794@footnote{https://github.com/python/cpython/issues/108794}: The @ref{1d9,,doctest.DocTestRunner.run()} method now counts the
number of skipped tests. Add @ref{1da,,doctest.DocTestRunner.skips} and
@ref{1db,,doctest.TestResults.skipped} attributes. Patch by Victor Stinner.

@item 
gh-108388@footnote{https://github.com/python/cpython/issues/108388}: Convert test_concurrent_futures to a package of 7 sub-tests.
Patch by Victor Stinner.

@item 
gh-108388@footnote{https://github.com/python/cpython/issues/108388}: Split test_multiprocessing_fork,
test_multiprocessing_forkserver and test_multiprocessing_spawn into test
packages. Each package is made of 4 sub-tests: processes, threads, manager
and misc. It allows running more tests in parallel and so reduce the total
test duration. Patch by Victor Stinner.

@item 
gh-105776@footnote{https://github.com/python/cpython/issues/105776}: Fix test_cppext when the C compiler command @code{-std=c11}
option: remove @code{-std=} options from the compiler command. Patch by
Victor Stinner.

@item 
gh-107652@footnote{https://github.com/python/cpython/issues/107652}: Set up CIFuzz to run fuzz targets in GitHub Actions. Patch by
Illia Volochii.

@item 
gh-107237@footnote{https://github.com/python/cpython/issues/107237}: @code{test_logging}: Fix @code{test_udp_reconnection()} by increasing
the timeout from 100 ms to 5 minutes (LONG_TIMEOUT). Patch by Victor
Stinner.

@item 
gh-107178@footnote{https://github.com/python/cpython/issues/107178}: Add the C API test for functions in the Mapping Protocol, the
Sequence Protocol and some functions in the Object Protocol.

@item 
gh-106714@footnote{https://github.com/python/cpython/issues/106714}: test_capi: Fix test_no_FatalError_infinite_loop() to no longer
write a coredump, by using test.support.SuppressCrashReport. Patch by
Victor Stinner.

@item 
gh-104090@footnote{https://github.com/python/cpython/issues/104090}: Avoid creating a reference to the test object in
@ref{1698,,collectedDurations()}.

@item 
gh-106752@footnote{https://github.com/python/cpython/issues/106752}: Moved tests for @code{zipfile.Path} into
@code{Lib/test/test_zipfile/_path}. Made @code{zipfile._path} a package.

@item 
gh-106690@footnote{https://github.com/python/cpython/issues/106690}: Add .coveragerc to cpython repository for use with coverage
package.

@item 
gh-101634@footnote{https://github.com/python/cpython/issues/101634}: When running the Python test suite with @code{-jN} option, if a
worker stdout cannot be decoded from the locale encoding report a failed
testn so the exitcode is non-zero. Patch by Victor Stinner.

@item 
gh-105084@footnote{https://github.com/python/cpython/issues/105084}: When the Python build is configured @code{--with-wheel-pkg-dir},
tests requiring the @code{setuptools} and @code{wheel} wheels will search for
the wheels in @code{WHEEL_PKG_DIR}.

@item 
gh-81005@footnote{https://github.com/python/cpython/issues/81005}: String tests are modified to reflect that @code{str} and
@code{unicode} are merged in Python 3. Patch by Daniel Fortunov.

@item 
gh-103186@footnote{https://github.com/python/cpython/issues/103186}: Suppress and assert expected RuntimeWarnings in
test_sys_settrace.py

@item 
gh-69714@footnote{https://github.com/python/cpython/issues/69714}: Add additional tests to @ref{14,,calendar} to achieve full test
coverage.
@end itemize

@node Build<15>,Windows<12>,Tests<13>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id117}@anchor{1699}
@subsubsection Build



@itemize -

@item 
gh-103053@footnote{https://github.com/python/cpython/issues/103053}: "make check-clean-src" now also checks if the "python" program
is found in the source directory: fail with an error if it does exist.
Patch by Victor Stinner.

@item 
gh-109191@footnote{https://github.com/python/cpython/issues/109191}: Fix compile error when building with recent versions of
libedit.

@item 
gh-110276@footnote{https://github.com/python/cpython/issues/110276}: No longer ignore 
@geindex PROFILE_TASK
@geindex variable d'environnement; PROFILE_TASK
@ref{169a,,PROFILE_TASK} failure silently:
command used by Profile Guided Optimization (PGO). Patch by Victor
Stinner.

@item 
gh-109566@footnote{https://github.com/python/cpython/issues/109566}: Remove @code{make testall} target: use @code{make buildbottest}
instead. Patch by Victor Stinner.

@item 
gh-109740@footnote{https://github.com/python/cpython/issues/109740}: The experimental @code{--disable-gil} configure flag now includes
"t" (for "threaded") in extension ABI tags.

@item 
gh-109054@footnote{https://github.com/python/cpython/issues/109054}: Fix building the @code{_testcapi} extension on Linux AArch64 which
requires linking to libatomic when @code{<cpython/pyatomic.h>} is used: the
@code{_Py_atomic_or_uint64()} function requires libatomic
@code{__atomic_fetch_or_8()} on this platform. The configure script now
checks if linking to libatomic is needed and generates a new LIBATOMIC
variable used to build the _testcapi extension. Patch by Victor Stinner.

@item 
gh-63760@footnote{https://github.com/python/cpython/issues/63760}: Fix Solaris build: no longer redefine the @code{gethostname()}
function. Solaris defines the function since 2005. Patch by Victor
Stinner, original patch by Jakub Kulík.

@item 
gh-108740@footnote{https://github.com/python/cpython/issues/108740}: Fix a race condition in @code{make regen-all}. The
@code{deepfreeze.c} source and files generated by Argument Clinic are now
generated or updated before generating "global objects". Previously, some
identifiers may miss depending on the order in which these files were
generated. Patch by Victor Stinner.

@item 
gh-108634@footnote{https://github.com/python/cpython/issues/108634}: Python built with @code{configure} @ref{38b,,--with-trace-refs}
(tracing references) is now ABI compatible with Python release build and
@ref{1f6,,debug build}. Patch by Victor Stinner.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: The @code{_stat} C extension is now built with the @ref{38c,,limited C API}. Patch by Victor Stinner.

@item 
gh-108447@footnote{https://github.com/python/cpython/issues/108447}: Fix x86_64 GNU/Hurd build

@item 
gh-107814@footnote{https://github.com/python/cpython/issues/107814}: When calling @code{find_python.bat} with @code{-q} it did not
properly silence the output of nuget. That is now fixed.

@item 
gh-105481@footnote{https://github.com/python/cpython/issues/105481}: Remove the make target @code{regen-opcode-targets}, merge its work
into @code{regen-opcode} which repeats most of the calculation. This
simplifies the code for the build and reduces code duplication.

@item 
gh-106881@footnote{https://github.com/python/cpython/issues/106881}: Check for @code{linux/limits.h} before including it in
@code{Modules/posixmodule.c}.

@item 
gh-95855@footnote{https://github.com/python/cpython/issues/95855}: Refactor platform triplet detection code and add detection for
MIPS soft float and musl libc.

@item 
gh-106962@footnote{https://github.com/python/cpython/issues/106962}: Detect MPI compilers in @code{configure}.

@item 
gh-106118@footnote{https://github.com/python/cpython/issues/106118}: Fix compilation for platforms without @code{O_CLOEXEC}. The
issue was introduced with Python 3.12b1 in gh-103295@footnote{https://github.com/python/cpython/issues/103295}. Patch by Erlend
Aasland.

@item 
gh-105875@footnote{https://github.com/python/cpython/issues/105875}: SQLite 3.15.2 or newer is required to build the @ref{ce,,sqlite3}
extension module. Patch by Erlend Aasland.

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: Fix a regression in @code{configure} where we could end up
unintentionally linking with @code{libbsd}.

@item 
gh-102404@footnote{https://github.com/python/cpython/issues/102404}: Document how to perform a WASI build on Linux. Also add
Tools/wasm/build_wasi.sh as a reference implementation of the docs.

@item 
gh-89886@footnote{https://github.com/python/cpython/issues/89886}: Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate
@code{!configure}.

@item 
gh-104692@footnote{https://github.com/python/cpython/issues/104692}: Include @code{commoninstall} as a prerequisite for @code{bininstall}

This ensures that @code{commoninstall} is completed before @code{bininstall} is
started when parallel builds are used (@code{make -j install}), and so the
@code{python3} symlink is only installed after all standard library modules
are installed.

@item 
gh-101538@footnote{https://github.com/python/cpython/issues/101538}: Add experimental wasi-threads support. Patch by Takashi
Yamamoto.
@end itemize

@node Windows<12>,macOS<9>,Build<15>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id118}@anchor{169b}
@subsubsection Windows



@itemize -

@item 
gh-110437@footnote{https://github.com/python/cpython/issues/110437}: Allows overriding the source of VC redistributables so that
releases can be guaranteed to never downgrade between updates.

@item 
gh-109286@footnote{https://github.com/python/cpython/issues/109286}: Update Windows installer to use SQLite 3.43.1.

@item 
gh-82367@footnote{https://github.com/python/cpython/issues/82367}: @ref{222,,os.path.realpath()} now resolves MS-DOS style file names
even if the file is not accessible. Patch by Moonsik Park.

@item 
gh-109991@footnote{https://github.com/python/cpython/issues/109991}: Update Windows build to use OpenSSL 3.0.11.

@item 
gh-106242@footnote{https://github.com/python/cpython/issues/106242}: Fixes @ref{222,,realpath()} to behave consistently when
passed a path containing an embedded null character on Windows. In strict
mode, it now raises @ref{40d,,OSError} instead of the unexpected
@ref{1ff,,ValueError}, and in non-strict mode will make the path absolute.

@item 
gh-83180@footnote{https://github.com/python/cpython/issues/83180}: Changes the @ref{5a8,,Lanceur Python pour Windows} to prefer an active virtual
environment when the launched script has a shebang line using a Unix-like
virtual command, even if the command requests a specific version of
Python.

@item 
gh-106844@footnote{https://github.com/python/cpython/issues/106844}: Fix integer overflow and truncating by the null character in
@code{_winapi.LCMapStringEx()} which affects @code{ntpath.normcase()}.

@item 
gh-105436@footnote{https://github.com/python/cpython/issues/105436}: Ensure that an empty environment block is terminated by two
null characters, as is required by Windows.

@item 
gh-105146@footnote{https://github.com/python/cpython/issues/105146}: Updated the links at the end of the installer to point to
Discourse rather than the mailing lists.

@item 
gh-103646@footnote{https://github.com/python/cpython/issues/103646}: When installed from the Microsoft Store, @code{pip} no longer
defaults to per-user installs. However, as the install directory is
unwritable, it should automatically decide to do a per-user install
anyway. This should resolve issues when @code{pip} is passed an option that
conflicts with @code{--user}.

@item 
gh-88745@footnote{https://github.com/python/cpython/issues/88745}: Improve performance of @ref{a49,,shutil.copy2()} by using the
operating system's @code{CopyFile2} function. This may result in subtle
changes to metadata copied along with some files, bringing them in line
with normal OS behavior.

@item 
gh-104820@footnote{https://github.com/python/cpython/issues/104820}: Fixes @ref{48a,,stat()} and related functions on file systems
that do not support file ID requests. This includes FAT32 and exFAT.

@item 
gh-104803@footnote{https://github.com/python/cpython/issues/104803}: Add @ref{15d1,,os.path.isdevdrive()} to detect whether a path is on a
Windows Dev Drive. Returns @code{False} on platforms that do not support Dev
Drive, and is absent on non-Windows platforms.
@end itemize

@node macOS<9>,IDLE<13>,Windows<12>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id119}@anchor{169c}
@subsubsection macOS



@itemize -

@item 
gh-109286@footnote{https://github.com/python/cpython/issues/109286}: Update macOS installer to use SQLite 3.43.1.

@item 
gh-109991@footnote{https://github.com/python/cpython/issues/109991}: Update macOS installer to use OpenSSL 3.0.11.

@item 
gh-99079@footnote{https://github.com/python/cpython/issues/99079}: Update macOS installer to use OpenSSL 3.0.9.
@end itemize

@node IDLE<13>,Tools/Demos<7>,macOS<9>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id120}@anchor{169d}
@subsubsection IDLE



@itemize -

@item 
gh-104719@footnote{https://github.com/python/cpython/issues/104719}: Remove IDLE's modification of tokenize.tabsize and test other
uses of tokenize data and methods.
@end itemize

@node Tools/Demos<7>,C API<15>,IDLE<13>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id121}@anchor{169e}
@subsubsection Tools/Demos



@itemize -

@item 
gh-109991@footnote{https://github.com/python/cpython/issues/109991}: Update GitHub CI workflows to use OpenSSL 3.0.11 and
multissltests to use 1.1.1w, 3.0.11, and 3.1.3.

@item 
gh-108494@footnote{https://github.com/python/cpython/issues/108494}: Argument Clinic@footnote{https://devguide.python.org/development-tools/clinic/} now has a
partial support of the @ref{38c,,Limited API}: see
documentation in the Python Developer's Guide@footnote{https://devguide.python.org/development-tools/clinic/#clinic-howto-limited-capi}
Patch by Victor Stinner.

@item 
gh-107704@footnote{https://github.com/python/cpython/issues/107704}: It is now possible to deprecate passing keyword arguments for
keyword-or-positional parameters with Argument Clinic, using the new @code{/
[from X.Y]} syntax. (To be read as `"positional-only from Python version
X.Y"'.) See documentation in the Python Developer's Guide@footnote{https://devguide.python.org/development-tools/clinic/#clinic-howto-deprecate-keyword}
for more information.

@item 
gh-107880@footnote{https://github.com/python/cpython/issues/107880}: Argument Clinic can now clone @code{__init__()} and
@code{__new__()} methods.

@item 
gh-104683@footnote{https://github.com/python/cpython/issues/104683}: Add @code{--exclude} option to Argument Clinic CLI.

@item 
gh-95065@footnote{https://github.com/python/cpython/issues/95065}: Argument Clinic now supports overriding automatically generated
signature by using directive @code{@@text_signature}. See documentation in the Python Developer's Guide@footnote{https://devguide.python.org/development-tools/clinic/#clinic-howto-override-signature}

@item 
gh-107609@footnote{https://github.com/python/cpython/issues/107609}: Fix duplicate module check in Argument Clinic. Previously, a
duplicate definition would incorrectly be silently accepted. Patch by
Erlend E. Aasland.

@item 
gh-107467@footnote{https://github.com/python/cpython/issues/107467}: The Argument Clinic command-line tool now prints to stderr
instead of stdout on failure.

@item 
gh-106970@footnote{https://github.com/python/cpython/issues/106970}: Fix bugs in the Argument Clinic @code{destination <name> clear}
command; the destination buffers would never be cleared, and the
@code{destination} directive parser would simply continue to the fault
handler after processing the command. Patch by Erlend E. Aasland.

@item 
gh-106706@footnote{https://github.com/python/cpython/issues/106706}: Change bytecode syntax for families to remove redundant name
matching pseudo syntax.

@item 
gh-106359@footnote{https://github.com/python/cpython/issues/106359}: Argument Clinic now explicitly forbids "kwarg splats" in
function calls used as annotations.

@item 
gh-103186@footnote{https://github.com/python/cpython/issues/103186}: @code{freeze} now fetches @code{CONFIG_ARGS} from the original
CPython instance the Makefile uses to call utility scripts. Patch by
Ijtaba Hussain.

@item 
gh-95065@footnote{https://github.com/python/cpython/issues/95065}: It is now possible to deprecate passing parameters positionally
with Argument Clinic, using the new @code{* [from X.Y]} syntax. (To be read
as `"keyword-only from Python version X.Y"'.) See documentation in the Python Developer's Guide@footnote{https://devguide.python.org/development-tools/clinic/#clinic-howto-deprecate-positional}
for more information. Patch by Erlend E. Aasland with help from Alex
Waygood, Nikita Sobolev, and Serhiy Storchaka.
@end itemize

@node C API<15>,,Tools/Demos<7>,Python 3 13 0 alpha 1
@anchor{whatsnew/changelog id122}@anchor{169f}
@subsubsection C API



@itemize -

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: If the @ref{414,,Py_LIMITED_API} macro is defined,
@code{Py_BUILD_CORE}, @code{Py_BUILD_CORE_BUILTIN} and
@code{Py_BUILD_CORE_MODULE} macros are now undefined by
@code{<Python.h>}. Patch by Victor Stinner.

@item 
gh-110289@footnote{https://github.com/python/cpython/issues/110289}: Add @ref{36c,,PyUnicode_EqualToUTF8AndSize()} and
@ref{36d,,PyUnicode_EqualToUTF8()} functions.

@item 
gh-110235@footnote{https://github.com/python/cpython/issues/110235}: Raise @ref{522,,TypeError} for duplicate/unknown fields in
@code{PyStructSequence} constructor. Patched by Xuehai Pan.

@item 
gh-110014@footnote{https://github.com/python/cpython/issues/110014}: Remove undocumented @code{PY_TIMEOUT_MAX} constant from the
limited C API. Patch by Victor Stinner.

@item 
gh-109521@footnote{https://github.com/python/cpython/issues/109521}: @ref{16a0,,PyImport_GetImporter()} now sets RuntimeError if it
fails to get @ref{100d,,sys.path_hooks} or @ref{5ce,,sys.path_importer_cache} or
they are not list and dict correspondingly. Previously it could return
NULL without setting error in obscure cases, crash or raise SystemError if
these attributes have wrong type.

@item 
gh-108724@footnote{https://github.com/python/cpython/issues/108724}: Add @ref{15a,,PyMutex} internal-only lightweight locking API.

@item 
gh-85283@footnote{https://github.com/python/cpython/issues/85283}: Add @ref{364,,PySys_AuditTuple()} function: similar to
@ref{365,,PySys_Audit()}, but pass event arguments as a Python @ref{366,,tuple}
object.  Patch by Victor Stinner.

@item 
gh-108867@footnote{https://github.com/python/cpython/issues/108867}: Add @ref{367,,PyThreadState_GetUnchecked()} function: similar to
@ref{368,,PyThreadState_Get()}, but don't kill the process with a fatal
error if it is NULL. The caller is responsible to check if the result is
NULL. Previously, the function was private and known as
@code{_PyThreadState_UncheckedGet()}. Patch by Victor Stinner.

@item 
gh-108765@footnote{https://github.com/python/cpython/issues/108765}: @code{Python.h} no longer includes the @code{<ctype.h>} standard
header file. If needed, it should now be included explicitly. For example,
it provides @code{isalpha()} and @code{tolower()} functions which are locale
dependent. Python provides locale independent functions, like
@code{Py_ISALPHA()} and @code{Py_TOLOWER()}. Patch by Victor Stinner.

@item 
gh-108765@footnote{https://github.com/python/cpython/issues/108765}: @code{Python.h} no longer includes the @code{<unistd.h>} standard
header file. If needed, it should now be included explicitly. For example,
it provides the functions: @code{close()}, @code{getpagesize()}, @code{getpid()}
and @code{sysconf()}. Patch by Victor Stinner.

@item 
gh-108765@footnote{https://github.com/python/cpython/issues/108765}: @code{Python.h} no longer includes the @code{<ieeefp.h>} standard
header. It was included for the @code{finite()} function which is now
provided by the @code{<math.h>} header. It should now be included explicitly
if needed. Remove also the @code{HAVE_IEEEFP_H} macro. Patch by Victor
Stinner.

@item 
gh-108765@footnote{https://github.com/python/cpython/issues/108765}: @code{Python.h} no longer includes these standard header files:
@code{<time.h>}, @code{<sys/select.h>} and @code{<sys/time.h>}. If needed, they
should now be included explicitly. For example, @code{<time.h>} provides the
@code{clock()} and @code{gmtime()} functions, @code{<sys/select.h>} provides the
@code{select()} function, and @code{<sys/time.h>} provides the @code{futimes()},
@code{gettimeofday()} and @code{setitimer()} functions. Patch by Victor Stinner.

@item 
gh-108511@footnote{https://github.com/python/cpython/issues/108511}: Add functions @ref{370,,PyObject_HasAttrWithError()},
@ref{372,,PyObject_HasAttrStringWithError()},
@ref{374,,PyMapping_HasKeyWithError()} and
@ref{376,,PyMapping_HasKeyStringWithError()}.

@item 
gh-107073@footnote{https://github.com/python/cpython/issues/107073}: Add @ref{35f,,PyObject_VisitManagedDict()} and
@ref{360,,PyObject_ClearManagedDict()} functions which must be called by the
traverse and clear functions of a type using
@ref{361,,Py_TPFLAGS_MANAGED_DICT} flag. Patch by Victor Stinner.

@item 
gh-108634@footnote{https://github.com/python/cpython/issues/108634}: Python built with @code{configure} @ref{38b,,--with-trace-refs}
(tracing references) now supports the @ref{38c,,Limited API}.
Patch by Victor Stinner.

@item 
gh-108014@footnote{https://github.com/python/cpython/issues/108014}: Add @ref{355,,PyLong_AsInt()} function: similar to
@ref{356,,PyLong_AsLong()}, but store the result in a C int instead
of a C long. Previously, it was known as the private function
@code{_PyLong_AsInt()} (with an underscore prefix). Patch by Victor
Stinner.

@item 
gh-108314@footnote{https://github.com/python/cpython/issues/108314}: Add @ref{32d,,PyDict_ContainsString()} function: same as
@ref{32e,,PyDict_Contains()}, but `key' is specified as a const char* UTF-8 encoded bytes string, rather than a @ref{32f,,PyObject}*.
Patch by Victor Stinner.

@item 
gh-108337@footnote{https://github.com/python/cpython/issues/108337}: Add atomic operations on additional data types in pyatomic.h.

@item 
gh-108014@footnote{https://github.com/python/cpython/issues/108014}: Add @ref{350,,Py_IsFinalizing()} function: check if the main
Python interpreter is @ref{14d,,shutting down}. Patch
by Victor Stinner.

@item 
gh-107916@footnote{https://github.com/python/cpython/issues/107916}: C API functions @ref{16a1,,PyErr_SetFromErrnoWithFilename()},
@ref{16a2,,PyErr_SetExcFromWindowsErrWithFilename()} and
@ref{16a3,,PyErr_SetFromWindowsErrWithFilename()} save now the error code
before calling @ref{16a4,,PyUnicode_DecodeFSDefault()}.

@item 
gh-107915@footnote{https://github.com/python/cpython/issues/107915}: Such C API functions as @code{PyErr_SetString()},
@code{PyErr_Format()}, @code{PyErr_SetFromErrnoWithFilename()} and many others
no longer crash or ignore errors if it failed to format the error message
or decode the filename. Instead, they keep a corresponding error.

@item 
gh-107810@footnote{https://github.com/python/cpython/issues/107810}: Improve @ref{1a3,,DeprecationWarning} for uses of
@ref{16a5,,PyType_Spec} with metaclasses that have custom @code{tp_new}.

@item 
gh-107249@footnote{https://github.com/python/cpython/issues/107249}: Implement the @ref{16a6,,Py_UNUSED} macro for Windows MSVC
compiler. Patch by Victor Stinner.

@item 
gh-107226@footnote{https://github.com/python/cpython/issues/107226}: @ref{35b,,PyModule_AddObjectRef()} is now only available in the
limited API version 3.10 or later.

@item 
gh-106320@footnote{https://github.com/python/cpython/issues/106320}: Remove private @code{_PyUnicode_AsString()} alias to
@ref{ba9,,PyUnicode_AsUTF8()}. It was kept for backward compatibility with
Python 3.0 - 3.2. The @ref{ba9,,PyUnicode_AsUTF8()} is available since Python
3.3. The @ref{116e,,PyUnicode_AsUTF8String()} function can be used to keep
compatibility with Python 3.2 and older. Patch by Victor Stinner.

@item 
gh-106572@footnote{https://github.com/python/cpython/issues/106572}: Convert @ref{16a7,,PyObject_DelAttr()} and
@ref{158a,,PyObject_DelAttrString()} macros to functions. Patch by Victor
Stinner.

@item 
gh-106307@footnote{https://github.com/python/cpython/issues/106307}: Add @ref{33b,,PyMapping_GetOptionalItem()} function.

@item 
gh-106521@footnote{https://github.com/python/cpython/issues/106521}: Add @ref{33f,,PyObject_GetOptionalAttr()} and
@ref{340,,PyObject_GetOptionalAttrString()} functions.

@item 
gh-106320@footnote{https://github.com/python/cpython/issues/106320}: Remove @code{_PyInterpreterState_Get()} alias to
@ref{3a4,,PyInterpreterState_Get()} which was kept for backward
compatibility with Python 3.8. Patch by Victor Stinner.

@item 
gh-106316@footnote{https://github.com/python/cpython/issues/106316}: Remove @code{cpython/pytime.h} header file: it only contained
private functions. Patch by Victor Stinner.

@item 
gh-106023@footnote{https://github.com/python/cpython/issues/106023}: Remove private @code{_PyObject_FastCall()} function: use
@code{PyObject_Vectorcall()} which is available since Python 3.8
(
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}). Patch by Victor Stinner.

@item 
gh-106168@footnote{https://github.com/python/cpython/issues/106168}: If Python is built in @ref{1f6,,debug mode} or
@ref{382,,with assertions}, @ref{383,,PyTuple_SET_ITEM()}
and @ref{384,,PyList_SET_ITEM()} now check the index argument with an
assertion. If the assertion fails, make sure that the size is set before.
Patch by Victor Stinner.

@item 
gh-106084@footnote{https://github.com/python/cpython/issues/106084}: Remove the old aliases to functions calling functions which
were kept for backward compatibility with Python 3.8 provisional API:


@itemize *

@item 
@code{_PyObject_CallMethodNoArgs()}: use @code{PyObject_CallMethodNoArgs()}

@item 
@code{_PyObject_CallMethodOneArg()}: use @code{PyObject_CallMethodOneArg()}

@item 
@code{_PyObject_CallOneArg()}: use @code{PyObject_CallOneArg()}

@item 
@code{_PyObject_FastCallDict()}: use @code{PyObject_VectorcallDict()}

@item 
@code{_PyObject_Vectorcall()}: use @code{PyObject_Vectorcall()}

@item 
@code{_PyObject_VectorcallMethod()}: use @code{PyObject_VectorcallMethod()}

@item 
@code{_PyVectorcall_Function()}: use @code{PyVectorcall_Function()}
@end itemize

Just remove the underscore prefix to update your code. Patch by Victor
Stinner.

@item 
gh-106004@footnote{https://github.com/python/cpython/issues/106004}: Adds @ref{330,,PyDict_GetItemRef()} and
@ref{331,,PyDict_GetItemStringRef()} functions: similar to
@ref{332,,PyDict_GetItemWithError()} but returning a @ref{333,,strong reference}
instead of a @ref{334,,borrowed reference}. Patch by Victor Stinner.

@item 
gh-105927@footnote{https://github.com/python/cpython/issues/105927}: Deprecate the @ref{36f,,PyWeakref_GetObject()} and
@ref{3b6,,PyWeakref_GET_OBJECT()} functions: use the new
@ref{36e,,PyWeakref_GetRef()} function instead. Patch by Victor Stinner.

@item 
gh-105927@footnote{https://github.com/python/cpython/issues/105927}: Add @ref{36e,,PyWeakref_GetRef()} function: similar to
@ref{36f,,PyWeakref_GetObject()} but returns a @ref{333,,strong reference}, or
@code{NULL} if the referent is no longer live. Patch by Victor Stinner.

@item 
gh-105922@footnote{https://github.com/python/cpython/issues/105922}: Add @ref{34e,,PyImport_AddModuleRef()}: similar to
@ref{34f,,PyImport_AddModule()}, but return a @ref{333,,strong reference}
instead of a @ref{334,,borrowed reference}. Patch by Victor Stinner.

@item 
gh-105227@footnote{https://github.com/python/cpython/issues/105227}: The new @ref{16a8,,PyType_GetDict()} provides the dictionary for
the given type object that is normally exposed by @code{cls.__dict__}.
Normally it's sufficient to use @ref{16a9,,tp_dict}, but for
the static builtin types @code{tp_dict} is now always @code{NULL}.
@code{PyType_GetDict()} provides the correct dict object instead.

@item 
gh-105375@footnote{https://github.com/python/cpython/issues/105375}: Fix a bug in @ref{16aa,,PyErr_WarnExplicit()} where an exception
could end up being overwritten if the API failed internally.

@item 
gh-105603@footnote{https://github.com/python/cpython/issues/105603}: We've renamed the new (in 3.12) @code{PyInterpreterConfig.own_gil}
to @code{PyInterpreterConfig.gil} and changed the meaning of the value from
"bool" to an integer with supported values of
@code{PyInterpreterConfig_DEFAULT_GIL}, @code{PyInterpreterConfig_SHARED_GIL},
and @code{PyInterpreterConfig_OWN_GIL}. The default is "shared".

@item 
gh-105387@footnote{https://github.com/python/cpython/issues/105387}: In the limited C API version 3.12, @ref{55a,,Py_INCREF()} and
@ref{55b,,Py_DECREF()} functions are now implemented as opaque function calls
to hide implementation details. Patch by Victor Stinner.

@item 
gh-105396@footnote{https://github.com/python/cpython/issues/105396}: Deprecate the @ref{3b4,,PyImport_ImportModuleNoBlock()} function
which is just an alias to @ref{3b5,,PyImport_ImportModule()} since Python
3.3. Patch by Victor Stinner.

@item 
gh-103968@footnote{https://github.com/python/cpython/issues/103968}: @ref{53b,,PyType_FromMetaclass()} now allows metaclasses with
@code{tp_new} set to @code{NULL}.

@item 
gh-105268@footnote{https://github.com/python/cpython/issues/105268}: Remove the old private, undocumented and untested
@code{_PyGC_FINALIZED()} macro which was kept for backward compatibility with
Python 3.8 and older. Patch by Victor Stinner.

@item 
gh-105182@footnote{https://github.com/python/cpython/issues/105182}: Remove @code{PyEval_AcquireLock()} and @code{PyEval_ReleaseLock()}
functions, deprecated in Python 3.2. Patch by Victor Stinner.

@item 
gh-105182@footnote{https://github.com/python/cpython/issues/105182}: Remove @code{PyEval_InitThreads()} and
@code{PyEval_ThreadsInitialized()} functions, deprecated in Python 3.9. Patch
by Victor Stinner.

@item 
gh-105145@footnote{https://github.com/python/cpython/issues/105145}: Deprecate old Python initialization functions:


@itemize *

@item 
@ref{3a6,,PySys_ResetWarnOptions()}

@item 
@ref{3a8,,Py_GetExecPrefix()}

@item 
@ref{3aa,,Py_GetPath()}

@item 
@ref{3ac,,Py_GetPrefix()}

@item 
@ref{3ae,,Py_GetProgramFullPath()}

@item 
@ref{3b0,,Py_GetProgramName()}

@item 
@ref{3b1,,Py_GetPythonHome()}
@end itemize

Patch by Victor Stinner.

@item 
gh-85275@footnote{https://github.com/python/cpython/issues/85275}: @code{PyObject_AsCharBuffer()}, @code{PyObject_AsReadBuffer()},
@code{PyObject_CheckReadBuffer()}, and @code{PyObject_AsWriteBuffer()} are
removed. Please migrate to new buffer protocol;
@ref{390,,PyObject_GetBuffer()} and @ref{391,,PyBuffer_Release()}.

@item 
gh-105156@footnote{https://github.com/python/cpython/issues/105156}: Deprecate the old @code{Py_UNICODE} and @code{PY_UNICODE_TYPE} types:
use directly the @code{wchar_t} type instead. Since Python 3.3,
@code{Py_UNICODE} and @code{PY_UNICODE_TYPE} are just aliases to
@code{wchar_t}. Patch by Victor Stinner.

@item 
gh-105145@footnote{https://github.com/python/cpython/issues/105145}: Remove the following old functions to configure the Python
initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_AddWarnOptionUnicode()}

@item 
@code{PySys_AddWarnOption()}

@item 
@code{PySys_AddXOption()}

@item 
@code{PySys_HasWarnOptions()}

@item 
@code{PySys_SetArgvEx()}

@item 
@code{PySys_SetArgv()}

@item 
@code{PySys_SetPath()}

@item 
@code{Py_SetPath()}

@item 
@code{Py_SetProgramName()}

@item 
@code{Py_SetPythonHome()}

@item 
@code{Py_SetStandardStreamEncoding()}

@item 
@code{_Py_SetProgramFullPath()}
@end itemize

Patch by Victor Stinner.

@item 
gh-105107@footnote{https://github.com/python/cpython/issues/105107}: Remove functions deprecated in Python 3.9.


@itemize *

@item 
@code{PyEval_CallObject()}, @code{PyEval_CallObjectWithKeywords()}: use
@ref{392,,PyObject_CallNoArgs()} and @ref{393,,PyObject_Call()} (positional
arguments must not be `NULL') instead.

@item 
@code{PyEval_CallFunction()}: use @ref{395,,PyObject_CallFunction()} instead.

@item 
@code{PyEval_CallMethod()}: use @ref{396,,PyObject_CallMethod()} instead.

@item 
@code{PyCFunction_Call()}: use @ref{393,,PyObject_Call()} instead.
@end itemize

Patch by Victor Stinner.

@item 
gh-105115@footnote{https://github.com/python/cpython/issues/105115}: @code{PyTypeObject.tp_bases} (and @code{tp_mro}) for builtin static
types are now shared by all interpreters, whereas in 3.12-beta1 they were
stored on @code{PyInterpreterState}.  Also note that now the tuples are
immortal objects.

@item 
gh-105071@footnote{https://github.com/python/cpython/issues/105071}: Add @code{PyUnstable_Exc_PrepReraiseStar} to the unstable C api to
expose the implementation of @ref{5a2,,except*}.

@item 
gh-104922@footnote{https://github.com/python/cpython/issues/104922}: @code{PY_SSIZE_T_CLEAN} is no longer required to use @code{'#'}
formats in APIs like @ref{55d,,PyArg_ParseTuple()} and
@ref{894,,Py_BuildValue()}. They uses @code{Py_ssize_t} for @code{'#'} regardless
@code{PY_SSIZE_T_CLEAN}.

@item 
gh-104584@footnote{https://github.com/python/cpython/issues/104584}: Add an unstable C API for hooking in an optimizer. This is
mainly internal, but marked "unstable" to allow third-party
experimentation.

@item 
gh-104668@footnote{https://github.com/python/cpython/issues/104668}: Don't call @ref{571,,PyOS_InputHook} or
@ref{572,,PyOS_ReadlineFunctionPointer} in subinterpreters, since it's
generally difficult to avoid using global state in their registered
callbacks. This also avoids situations where extensions may find
themselves running in a subinterpreter they don't support (or haven't yet
been loaded in).

@item 
bpo-42327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42327}: Add @ref{35a,,PyModule_Add()} function: similar to
@ref{35b,,PyModule_AddObjectRef()} and @ref{35c,,PyModule_AddObject()}, but
always steals a reference to the value.

@item 
bpo-40309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40309}: Properly handle trailing spaces before closing parenthesis in
@ref{894,,Py_BuildValue()} format strings.
@end itemize

@node Python 3 12 0 beta 1,Python 3 12 0 alpha 7,Python 3 13 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-12-0-beta-1}@anchor{16ab}
@subsection Python 3.12.0 beta 1


`Release date: 2023-05-22'

@menu
* Security: Security<11>. 
* Core and Builtins: Core and Builtins<17>. 
* Library: Library<16>. 
* Documentation: Documentation<11>. 
* Tests: Tests<14>. 
* Build: Build<16>. 
* Windows: Windows<13>. 
* macOS: macOS<10>. 
* IDLE: IDLE<14>. 
* Tools/Demos: Tools/Demos<8>. 
* C API: C API<16>. 

@end menu

@node Security<11>,Core and Builtins<17>,,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id123}@anchor{16ac}
@subsubsection Security



@itemize -

@item 
gh-99889@footnote{https://github.com/python/cpython/issues/99889}: Fixed a security in flaw in @code{uu.decode()} that could allow
for directory traversal based on the input if no @code{out_file} was
specified.

@item 
gh-104049@footnote{https://github.com/python/cpython/issues/104049}: Do not expose the local on-disk location in directory indexes
produced by @code{http.client.SimpleHTTPRequestHandler}.

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Upgrade built-in @ref{67,,hashlib} SHA3 implementation to a
verified implementation from the @code{HACL*} project.  Used when OpenSSL is
not present or lacks SHA3.

@item 
gh-102153@footnote{https://github.com/python/cpython/issues/102153}: @ref{d2d,,urllib.parse.urlsplit()} now strips leading C0 control and
space characters following the specification for URLs defined by WHATWG in
response to 
@geindex Common Vulnerabilities and Exposures; CVE 2023-24329
CVE 2023-24329@footnote{https://www.cve.org/CVERecord?id=CVE-2023-24329}. Patch by Illia Volochii.
@end itemize

@node Core and Builtins<17>,Library<16>,Security<11>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id124}@anchor{16ad}
@subsubsection Core and Builtins



@itemize -

@item 
gh-102856@footnote{https://github.com/python/cpython/issues/102856}: Implement PEP 701 changes in the @ref{fa,,tokenize} module. Patch
by Marta Gómez Macías and Pablo Galindo Salgado

@item 
gh-104615@footnote{https://github.com/python/cpython/issues/104615}: Fix wrong ordering of assignments in code like @code{a, a = x, y}.
Contributed by Carl Meyer.

@item 
gh-104572@footnote{https://github.com/python/cpython/issues/104572}: Improve syntax error message for invalid constructs in
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} contexts and in annotations when @code{from __future__ import
annotations} is active.

@item 
gh-104482@footnote{https://github.com/python/cpython/issues/104482}: Fix three error handling bugs in ast.c's validation of pattern
matching statements.

@item 
gh-102818@footnote{https://github.com/python/cpython/issues/102818}: Do not add a frame to the traceback in the @code{sys.setprofile}
and @code{sys.settrace} trampoline functions. This ensures that frames are
not duplicated if an exception is raised in the callback function, and
ensures that frames are not omitted if a C callback is used and that does
not add the frame.

@item 
gh-104405@footnote{https://github.com/python/cpython/issues/104405}: Fix an issue where some @ref{185,,bytecode} instructions could
ignore 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} when "inlining" calls.

@item 
gh-103082@footnote{https://github.com/python/cpython/issues/103082}: Change behavior of @code{sys.monitoring.events.LINE} events in
@code{sys.monitoring}: Line events now occur when a new line is reached
dynamically, instead of using a static approximation, as before. This
makes the behavior very similar to that of "line" events in
@code{sys.settrace}. This should ease porting of tools from 3.11 to 3.12.

@item 
gh-104263@footnote{https://github.com/python/cpython/issues/104263}: Fix @code{float("nan")} to produce a quiet NaN on platforms (like
MIPS) where the meaning of the signalling / quiet bit is inverted from its
usual meaning. Also introduce a new macro @code{Py_INFINITY} matching C99's
@code{INFINITY}, and refactor internals to rely on C99's @code{NAN} and
@code{INFINITY} macros instead of hard-coding bit patterns for infinities and
NaNs. Thanks Sebastian Berg.

@item 
gh-99113@footnote{https://github.com/python/cpython/issues/99113}: Multi-phase init extension modules may now indicate that they
support running in subinterpreters that have their own GIL.  This is done
by using @code{Py_MOD_PER_INTERPRETER_GIL_SUPPORTED} as the value for the
@code{Py_mod_multiple_interpreters} module def slot.  Otherwise the module,
by default, cannot be imported in such subinterpreters.  (This does not
affect the main interpreter or subinterpreters that do not have their own
GIL.)  In addition to the isolation that multi-phase init already normally
requires, support for per-interpreter GIL involves one additional
constraint: thread-safety.  If the module has external (linked)
dependencies and those libraries have any state that isn't thread-safe
then the module must do the additional work to add thread-safety.  This
should be an uncommon case.

@item 
gh-99113@footnote{https://github.com/python/cpython/issues/99113}: The GIL is now (optionally) per-interpreter.  This is the
fundamental change for PEP 684.  This is all made possible by virtue of
the isolated state of each interpreter in the process.  The behavior of
the main interpreter remains unchanged.  Likewise, interpreters created
using @code{Py_NewInterpreter()} are not affected.  To get an interpreter
with its own GIL, call @code{Py_NewInterpreterFromConfig()}.

@item 
gh-104108@footnote{https://github.com/python/cpython/issues/104108}: Multi-phase init extension modules may now indicate whether or
not they actually support multiple interpreters.  By default such modules
are expected to support use in multiple interpreters.  In the uncommon
case that one does not, it may use the new
@code{Py_mod_multiple_interpreters} module def slot.  A value of @code{0} means
the module does not support them. @code{1} means it does.  The default is
@code{1}.

@item 
gh-104142@footnote{https://github.com/python/cpython/issues/104142}: Fix an issue where @ref{5fc,,list} or @ref{366,,tuple} repetition
could fail to respect 
@geindex Python Enhancement Proposals; PEP 683
PEP 683@footnote{https://peps.python.org/pep-0683/}.

@item 
gh-104078@footnote{https://github.com/python/cpython/issues/104078}: Improve the performance of @ref{373,,PyObject_HasAttrString()}

@item 
gh-104066@footnote{https://github.com/python/cpython/issues/104066}: Improve the performance of @ref{4bb,,hasattr()} for module objects
with a missing attribute.

@item 
gh-104028@footnote{https://github.com/python/cpython/issues/104028}: Reduce object creation while calling callback function from gc.
Patch by Donghee Na.

@item 
gh-104018@footnote{https://github.com/python/cpython/issues/104018}: Disallow the "z" format specifier in %-format of bytes objects.

@item 
gh-102213@footnote{https://github.com/python/cpython/issues/102213}: Fix performance loss when accessing an object's attributes with
@code{__getattr__}  defined.

@item 
gh-103895@footnote{https://github.com/python/cpython/issues/103895}: Improve handling of edge cases in showing
@code{Exception.__notes__}. Ensures that the messages always end with a
newline and that string/bytes are not exploded over multiple lines. Patch
by Carey Metcalfe.

@item 
gh-103907@footnote{https://github.com/python/cpython/issues/103907}: Don't modify the refcounts of known immortal objects
(@ref{bfb,,True}, @ref{b25,,False}, and @ref{660,,None}) in the main interpreter
loop.

@item 
gh-103899@footnote{https://github.com/python/cpython/issues/103899}: Provide a helpful hint in the @ref{522,,TypeError} message when
accidentally calling a @ref{15e8,,module} object that has a callable attribute
of the same name (such as @ref{b22,,dis.dis()} or @ref{1c7,,datetime.datetime}).

@item 
gh-103845@footnote{https://github.com/python/cpython/issues/103845}: Remove both line and instruction instrumentation before adding
new ones for monitoring, to avoid newly added instrumentation being
removed immediately.

@item 
gh-103763@footnote{https://github.com/python/cpython/issues/103763}: Implement 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}, adding syntactic support for generic
classes, generic functions, and type aliases.

A new @code{type X = ...} syntax is added for type aliases, which resolves at
runtime to an instance of the new class @code{typing.TypeAliasType}. The
value is lazily evaluated and is accessible through the @code{.__value__}
attribute. This is implemented as a new AST node @code{ast.TypeAlias}.

New syntax (@code{class X[T]: ...}, @code{def func[T](): ...}) is added for
defining generic functions and classes. This is implemented as a new
@code{type_params} attribute on the AST nodes for classes and functions. This
node holds instances of the new AST classes @code{ast.TypeVar},
@code{ast.ParamSpec}, and @code{ast.TypeVarTuple}.

@code{typing.TypeVar}, @code{typing.ParamSpec}, @code{typing.ParamSpecArgs},
@code{typing.ParamSpecKwargs}, @code{typing.TypeVarTuple}, and
@code{typing.Generic} are now implemented in C rather than Python.

There are new bytecode instructions @code{LOAD_LOCALS},
@code{LOAD_CLASSDICT_OR_GLOBAL}, and @code{LOAD_CLASSDICT_OR_DEREF} to support
correct resolution of names in class namespaces.

Patch by Eric Traut, Larry Hastings, and Jelle Zijlstra.

@item 
gh-103801@footnote{https://github.com/python/cpython/issues/103801}: Adds three minor linting fixes to the wasm module caught that
were caught by ruff.

@item 
gh-103793@footnote{https://github.com/python/cpython/issues/103793}: Optimized asyncio Task creation by deferring expensive string
formatting (task name generation) from Task creation to the first time
@code{get_name} is called. This makes asyncio benchmarks up to 5% faster.

@item 
gh-102310@footnote{https://github.com/python/cpython/issues/102310}: Change the error range for invalid bytes literals.

@item 
gh-103590@footnote{https://github.com/python/cpython/issues/103590}: Do not wrap a single exception raised from a @code{try-except*}
construct in an @ref{1b4,,ExceptionGroup}.

@item 
gh-103650@footnote{https://github.com/python/cpython/issues/103650}: Change the perf map format to remove the '0x' prefix from the
addresses

@item 
gh-102856@footnote{https://github.com/python/cpython/issues/102856}: Implement the required C tokenizer changes for PEP 701. Patch
by Pablo Galindo Salgado, Lysandros Nikolaou, Batuhan Taskaya, Marta Gómez
Macías and sunmy2019.

@item 
gh-100530@footnote{https://github.com/python/cpython/issues/100530}: Clarify the error message raised when the called part of a
class pattern isn't actually a class.

@item 
gh-101517@footnote{https://github.com/python/cpython/issues/101517}: Fix bug in line numbers of instructions emitted for
@ref{5a2,,except*}.

@item 
gh-103492@footnote{https://github.com/python/cpython/issues/103492}: Clarify @ref{44f,,SyntaxWarning} with literal @code{is} comparison by
specifying which literal is problematic, since comparisons using @code{is}
with e.g. @code{None} and bool literals are idiomatic.

@item 
gh-87729@footnote{https://github.com/python/cpython/issues/87729}: Add @ref{4c6,,LOAD_SUPER_ATTR} (and a specialization for
@code{super().method()}) to speed up @code{super().method()} and
@code{super().attr}. This makes @code{super().method()} roughly 2.3x faster and
brings it within 20% of the performance of a simple method call. Patch by
Vladimir Matveev and Carl Meyer.

@item 
gh-103488@footnote{https://github.com/python/cpython/issues/103488}: Change the internal offset distinguishing yield and return
target addresses, so that the instruction pointer is correct for exception
handling and other stack unwinding.

@item 
gh-82012@footnote{https://github.com/python/cpython/issues/82012}: The bitwise inversion operator (@code{~}) on bool is deprecated. It
returns the bitwise inversion of the underlying @code{int} representation
such that @code{bool(~True) == True}, which can be confusing. Use @code{not} for
logical negation of bools. In the rare case that you really need the
bitwise inversion of the underlying @code{int}, convert to int explicitly
@code{~int(x)}.

@item 
gh-77757@footnote{https://github.com/python/cpython/issues/77757}: Exceptions raised in a typeobject's @code{__set_name__} method are
no longer wrapped by a @ref{193,,RuntimeError}. Context information is added
to the exception as a 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/} note.

@item 
gh-103333@footnote{https://github.com/python/cpython/issues/103333}: @ref{343,,AttributeError} now retains the @code{name} attribute when
pickled and unpickled.

@item 
gh-103242@footnote{https://github.com/python/cpython/issues/103242}: Migrate @ref{1123,,set_ecdh_curve()} method not to
use deprecated OpenSSL APIs. Patch by Donghee Na.

@item 
gh-103323@footnote{https://github.com/python/cpython/issues/103323}: We've replaced our use of @code{_PyRuntime.tstate_current} with a
thread-local variable.  This is a fairly low-level implementation detail,
and there should be no change in behavior.

@item 
gh-84436@footnote{https://github.com/python/cpython/issues/84436}: The implementation of PEP-683 which adds Immortal Objects by
using a fixed reference count that skips reference counting to make
objects truly immutable.

@item 
gh-102700@footnote{https://github.com/python/cpython/issues/102700}: Allow built-in modules to be submodules. This allows submodules
to be statically linked into a CPython binary.

@item 
gh-103082@footnote{https://github.com/python/cpython/issues/103082}: Implement 
@geindex Python Enhancement Proposals; PEP 669
PEP 669@footnote{https://peps.python.org/pep-0669/} Low Impact Monitoring for CPython.

@item 
gh-88691@footnote{https://github.com/python/cpython/issues/88691}: Reduce the number of inline @ref{6e3,,CACHE} entries for
@ref{6f1,,CALL}.

@item 
gh-102500@footnote{https://github.com/python/cpython/issues/102500}: Make the buffer protocol accessible in Python code using the
new @code{__buffer__} and @code{__release_buffer__} magic methods. See
@geindex Python Enhancement Proposals; PEP 688
PEP 688@footnote{https://peps.python.org/pep-0688/} for details. Patch by Jelle Zijlstra.

@item 
gh-97933@footnote{https://github.com/python/cpython/issues/97933}: 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}: inline list, dict and set comprehensions to improve
performance and reduce bytecode size.

@item 
gh-99184@footnote{https://github.com/python/cpython/issues/99184}: Bypass instance attribute access of @code{__name__} in @code{repr} of
@ref{fd9,,weakref.ref}.

@item 
gh-98003@footnote{https://github.com/python/cpython/issues/98003}: Complex function calls are now faster and consume no C stack
space.

@item 
bpo-39610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39610}: @code{len()} for 0-dimensional @ref{452,,memoryview} objects (such
as @code{memoryview(ctypes.c_uint8(42))}) now raises a @ref{522,,TypeError}.
Previously this returned @code{1}, which was not consistent with
@code{mem_0d[0]} raising an @ref{14eb,,IndexError}.

@item 
bpo-31821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31821}: Fix @code{pause_reading()} to work when called from
@code{connection_made()} in @ref{a,,asyncio}.
@end itemize

@node Library<16>,Documentation<11>,Core and Builtins<17>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id125}@anchor{16ae}
@subsubsection Library



@itemize -

@item 
gh-104600@footnote{https://github.com/python/cpython/issues/104600}: @ref{100b,,functools.update_wrapper()} now sets the
@code{__type_params__} attribute (added by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}).

@item 
gh-104340@footnote{https://github.com/python/cpython/issues/104340}: When an @code{asyncio} pipe protocol loses its connection due to
an error, and the caller doesn't await @code{wait_closed()} on the
corresponding @code{StreamWriter}, don't log a warning about an exception
that was never retrieved. After all, according to the
@code{StreamWriter.close()} docs, the @code{wait_closed()} call is optional
("not mandatory").

@item 
gh-104555@footnote{https://github.com/python/cpython/issues/104555}: Fix issue where an @ref{7ab,,issubclass()} check comparing a class
@code{X} against a @ref{42c,,runtime-checkable protocol} @code{Y} with non-callable members would not
cause @ref{522,,TypeError} to be raised if an @ref{42b,,isinstance()} call had
previously been made comparing an instance of @code{X} to @code{Y}. This issue
was present in edge cases on Python 3.11, but became more prominent in
3.12 due to some unrelated changes that were made to runtime-checkable
protocols. Patch by Alex Waygood.

@item 
gh-104372@footnote{https://github.com/python/cpython/issues/104372}: Refactored the @code{_posixsubprocess} internals to avoid Python C
API usage between fork and exec when marking @code{pass_fds=} file
descriptors inheritable.

@item 
gh-104484@footnote{https://github.com/python/cpython/issues/104484}: Added `case_sensitive' argument to
@ref{496,,pathlib.PurePath.match()}

@item 
gh-75367@footnote{https://github.com/python/cpython/issues/75367}: Fix data descriptor detection in
@ref{47e,,inspect.getattr_static()}.

@item 
gh-104536@footnote{https://github.com/python/cpython/issues/104536}: Fix a race condition in the internal
@code{multiprocessing.process} cleanup logic that could manifest as an
unintended @code{AttributeError} when calling @code{process.close()}.

@item 
gh-103857@footnote{https://github.com/python/cpython/issues/103857}: Update datetime deprecations' stracktrace to point to the
calling line

@item 
gh-101520@footnote{https://github.com/python/cpython/issues/101520}: Move the core functionality of the @code{tracemalloc} module in
the @code{Python/} folder, leaving just the module wrapper in @code{Modules/}.

@item 
gh-104392@footnote{https://github.com/python/cpython/issues/104392}: Remove undocumented and unused @code{_paramspec_tvars} attribute
from some classes in @ref{103,,typing}.

@item 
gh-102613@footnote{https://github.com/python/cpython/issues/102613}: Fix issue where @ref{22a,,pathlib.Path.glob()} raised
@ref{d59,,RecursionError} when walking deep directory trees.

@item 
gh-103000@footnote{https://github.com/python/cpython/issues/103000}: Improve performance of @ref{16af,,dataclasses.asdict()} for the
common case where `dict_factory' is @code{dict}. Patch by David C Ellis.

@item 
gh-104301@footnote{https://github.com/python/cpython/issues/104301}: Allow leading whitespace in disambiguated statements in
@ref{a4,,pdb}.

@item 
gh-104139@footnote{https://github.com/python/cpython/issues/104139}: Teach @code{urllib.parse.unsplit()} to retain the @code{"//"} when
assembling @code{itms-services://?action=generate-bugs} style Apple Platform Deployment@footnote{https://support.apple.com/en-gb/guide/deployment/depce7cefc4d/web}
URLs.

@item 
gh-104307@footnote{https://github.com/python/cpython/issues/104307}: @ref{164d,,socket.getnameinfo()} now releases the GIL while
contacting the DNS server

@item 
gh-104310@footnote{https://github.com/python/cpython/issues/104310}: Users may now use @code{importlib.util.allowing_all_extensions()}
(a context manager) to temporarily disable the strict compatibility checks
for importing extension modules in subinterpreters.

@item 
gh-87695@footnote{https://github.com/python/cpython/issues/87695}: Fix issue where @ref{22a,,pathlib.Path.glob()} raised @ref{40d,,OSError}
when it encountered a symlink to an overly long path.

@item 
gh-104265@footnote{https://github.com/python/cpython/issues/104265}: Prevent possible crash by disallowing instantiation of the
@code{_csv.Reader} and @code{_csv.Writer} types. The regression was
introduced in 3.10.0a4 with PR 23224 (bpo-14935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14935}). Patch by Radislav
Chugunov.

@item 
gh-102613@footnote{https://github.com/python/cpython/issues/102613}: Improve performance of @ref{22a,,pathlib.Path.glob()} when expanding
recursive wildcards ("@code{**}") by merging adjacent wildcards and
de-duplicating results only when necessary.

@item 
gh-65772@footnote{https://github.com/python/cpython/issues/65772}: Remove unneeded comments and code in turtle.py.

@item 
gh-90208@footnote{https://github.com/python/cpython/issues/90208}: Fixed issue where @ref{22a,,pathlib.Path.glob()} returned incomplete
results when it encountered a @ref{d30,,PermissionError}. This method now
suppresses all @ref{40d,,OSError} exceptions, except those raised from calling
@ref{22d,,is_dir()} on the top-level path.

@item 
gh-104144@footnote{https://github.com/python/cpython/issues/104144}: Optimize @ref{1b3,,asyncio.TaskGroup} when using
@ref{461,,asyncio.eager_task_factory()}. Skip scheduling a done callback if a
TaskGroup task completes eagerly.

@item 
gh-104144@footnote{https://github.com/python/cpython/issues/104144}: Optimize @ref{5e8,,asyncio.gather()} when using
@ref{461,,asyncio.eager_task_factory()} to complete eagerly if all fututres
completed eagerly. Avoid scheduling done callbacks for futures that
complete eagerly.

@item 
gh-104114@footnote{https://github.com/python/cpython/issues/104114}: Fix issue where @ref{22a,,pathlib.Path.glob()} returns paths using
the case of non-wildcard segments for corresponding path segments, rather
than the real filesystem case.

@item 
gh-104104@footnote{https://github.com/python/cpython/issues/104104}: Improve performance of @ref{22a,,pathlib.Path.glob()} by using
@ref{16b0,,re.IGNORECASE} to implement case-insensitive matching.

@item 
gh-104102@footnote{https://github.com/python/cpython/issues/104102}: Improve performance of @ref{22a,,pathlib.Path.glob()} when
evaluating patterns that contain @code{'../'} segments.

@item 
gh-103822@footnote{https://github.com/python/cpython/issues/103822}: Update the return type of @code{weekday} to the newly added Day
attribute

@item 
gh-103629@footnote{https://github.com/python/cpython/issues/103629}: Update the @code{repr} of @ref{15b8,,typing.Unpack} according to
@geindex Python Enhancement Proposals; PEP 692
PEP 692@footnote{https://peps.python.org/pep-0692/}.

@item 
gh-103963@footnote{https://github.com/python/cpython/issues/103963}: Make @ref{38,,dis} display the names of the args for
@code{CALL_INTRINSIC_*}.

@item 
gh-104035@footnote{https://github.com/python/cpython/issues/104035}: Do not ignore user-defined @code{__getstate__} and
@code{__setstate__} methods for slotted frozen dataclasses.

@item 
gh-103987@footnote{https://github.com/python/cpython/issues/103987}: In @ref{8f,,mmap}, fix several bugs that could lead to access to
memory-mapped files after they have been invalidated.

@item 
gh-103977@footnote{https://github.com/python/cpython/issues/103977}: Improve import time of @ref{a9,,platform} module.

@item 
gh-88773@footnote{https://github.com/python/cpython/issues/88773}: Added @ref{16b1,,turtle.teleport()} to the @ref{100,,turtle} module to
move a turtle to a new point without tracing a line, visible or invisible.
Patch by Liam Gersten.

@item 
gh-103935@footnote{https://github.com/python/cpython/issues/103935}: Use @ref{16b2,,io.open_code()} for files to be executed instead of
raw @ref{505,,open()}

@item 
gh-68968@footnote{https://github.com/python/cpython/issues/68968}: Fixed garbled output of @ref{512,,assertEqual()}
when an input lacks final newline.

@item 
gh-100370@footnote{https://github.com/python/cpython/issues/100370}: Fix potential @ref{86d,,OverflowError} in
@ref{66c,,sqlite3.Connection.blobopen()} for 32-bit builds. Patch by Erlend E.
Aasland.

@item 
gh-102628@footnote{https://github.com/python/cpython/issues/102628}: Substitute CTRL-D with CTRL-Z in @ref{ce,,sqlite3} CLI banner when
running on Windows.

@item 
gh-103636@footnote{https://github.com/python/cpython/issues/103636}: Module-level attributes @code{January} and @code{February} are
deprecated from @ref{14,,calendar}.

@item 
gh-103583@footnote{https://github.com/python/cpython/issues/103583}: Isolate @code{_multibytecodec} and codecs extension modules.
Patches by Erlend E. Aasland.

@item 
gh-103848@footnote{https://github.com/python/cpython/issues/103848}: Add checks to ensure that @code{[} bracketed @code{]} hosts found by
@ref{d2d,,urllib.parse.urlsplit()} are of IPv6 or IPvFuture format.

@item 
gh-103872@footnote{https://github.com/python/cpython/issues/103872}: Update the bundled copy of pip to version 23.1.2.

@item 
gh-99944@footnote{https://github.com/python/cpython/issues/99944}: Make @ref{38,,dis} display the value of oparg of
@code{KW_NAMES}.

@item 
gh-74940@footnote{https://github.com/python/cpython/issues/74940}: The C.UTF-8 locale is no longer converted to en_US.UTF-8,
enabling the use of UTF-8 encoding on systems which have no locales
installed.

@item 
gh-103861@footnote{https://github.com/python/cpython/issues/103861}: Fix @code{zipfile.Zipfile} creating invalid zip files when
@code{force_zip64} was used to add files to them. Patch by Carey Metcalfe.

@item 
gh-103857@footnote{https://github.com/python/cpython/issues/103857}: Deprecated @ref{2f0,,datetime.datetime.utcnow()} and
@ref{2f1,,datetime.datetime.utcfromtimestamp()}. (Patch by Paul Ganssle)

@item 
gh-103839@footnote{https://github.com/python/cpython/issues/103839}: Avoid compilation error due to tommath.h not being found when
building Tkinter against Tcl 8.7 built with bundled libtommath.

@item 
gh-103791@footnote{https://github.com/python/cpython/issues/103791}: @ref{f11,,contextlib.suppress} now supports suppressing
exceptions raised as part of an @ref{1b4,,ExceptionGroup}. If other exceptions
exist on the group, they are re-raised in a group that does not contain
the suppressed exceptions.

@item 
gh-90750@footnote{https://github.com/python/cpython/issues/90750}: Use @ref{9db,,datetime.datetime.fromisocalendar()} in the
implementation of @ref{1593,,datetime.datetime.strptime()}, which should now
accept only valid ISO dates. (Patch by Paul Ganssle)

@item 
gh-103685@footnote{https://github.com/python/cpython/issues/103685}: Prepare @code{tkinter.Menu.index()} for Tk 8.7 so that it does
not raise @code{TclError: expected integer but got ""} when it should return
@code{None}.

@item 
gh-81403@footnote{https://github.com/python/cpython/issues/81403}: @ref{16b3,,urllib.request.CacheFTPHandler} no longer raises
@code{URLError} if a cached FTP instance is reused. ftplib's endtransfer
method calls voidresp to drain the connection to handle FTP instance reuse
properly.

@item 
gh-103699@footnote{https://github.com/python/cpython/issues/103699}: Add @code{__orig_bases__} to non-generic TypedDicts, call-based
TypedDicts, and call-based NamedTuples. Other TypedDicts and NamedTuples
already had the attribute.

@item 
gh-103693@footnote{https://github.com/python/cpython/issues/103693}: Add convenience variable feature to @ref{a4,,pdb}

@item 
gh-92248@footnote{https://github.com/python/cpython/issues/92248}: Deprecate @code{type}, @code{choices}, and @code{metavar} parameters of
@code{argparse.BooleanOptionalAction}.

@item 
gh-89415@footnote{https://github.com/python/cpython/issues/89415}: Add @ref{cb,,socket} constants for source-specific multicast. Patch
by Reese Hyde.

@item 
gh-103673@footnote{https://github.com/python/cpython/issues/103673}: @ref{cc,,socketserver} gains @code{ForkingUnixStreamServer} and
@code{ForkingUnixDatagramServer} classes. Patch by Jay Berry.

@item 
gh-103636@footnote{https://github.com/python/cpython/issues/103636}: Added Enum for months and days in the calendar module.

@item 
gh-84976@footnote{https://github.com/python/cpython/issues/84976}: Create a new @code{Lib/_pydatetime.py} file that defines the Python
version of the @code{datetime} module, and make @code{datetime} import the
contents of the new library only if the C implementation is missing.
Currently, the full Python implementation is defined and then deleted if
the C implementation is not available, slowing down @code{import datetime}
unnecessarily.

@item 
gh-103596@footnote{https://github.com/python/cpython/issues/103596}: Attributes/methods are no longer shadowed by same-named enum
members, although they may be shadowed by enum.property's.

@item 
gh-103584@footnote{https://github.com/python/cpython/issues/103584}: Updated @code{importlib.metadata} with changes from
@code{importlib_metadata} 5.2 through 6.5.0, including: Support
@code{installed-files.txt} for @code{Distribution.files} when present.
@code{PackageMetadata} now stipulates an additional @code{get} method allowing
for easy querying of metadata keys that may not be present.
@code{packages_distributions} now honors packages and modules with Python
modules that not @code{.py} sources (e.g. @code{.pyc}, @code{.so}). Expand protocol
for @code{PackageMetadata.get_all} to match the upstream implementation of
@code{email.message.Message.get_all} in python/typeshed#9620. Deprecated use
of @code{Distribution} without defining abstract methods. Deprecated
expectation that @code{PackageMetadata.__getitem__} will return @code{None} for
missing keys. In the future, it will raise a @code{KeyError}.

@item 
gh-103578@footnote{https://github.com/python/cpython/issues/103578}: Fixed a bug where @ref{a4,,pdb} crashes when reading source file
with different encoding by replacing @ref{506,,io.open()} with
@ref{16b2,,io.open_code()}. The new method would also call into the hook set by
@ref{16b4,,PyFile_SetOpenCodeHook()}.

@item 
gh-103556@footnote{https://github.com/python/cpython/issues/103556}: Now creating @ref{1ca,,inspect.Signature} objects with
positional-only parameter with a default followed by a
positional-or-keyword parameter without one is impossible.

@item 
gh-103559@footnote{https://github.com/python/cpython/issues/103559}: Update the bundled copy of pip to version 23.1.1.

@item 
gh-103548@footnote{https://github.com/python/cpython/issues/103548}: Improve performance of @ref{1637,,pathlib.Path.absolute()} and
@ref{16b5,,cwd()} by joining paths only when necessary. Also
improve performance of @ref{16b6,,pathlib.PurePath.is_absolute()} on Posix by
skipping path parsing and normalization.

@item 
gh-103538@footnote{https://github.com/python/cpython/issues/103538}: Remove @code{_tkinter} module code guarded by definition of the
@code{TK_AQUA} macro which was only needed for Tk 8.4.7 or earlier and was
never actually defined by any build system or documented for manual use.

@item 
gh-103533@footnote{https://github.com/python/cpython/issues/103533}: Update @ref{27,,cProfile} to use PEP 669 API

@item 
gh-103525@footnote{https://github.com/python/cpython/issues/103525}: Fix misleading exception message when mixed @code{str} and
@code{bytes} arguments are supplied to @ref{490,,pathlib.PurePath} and
@ref{226,,Path}.

@item 
gh-103489@footnote{https://github.com/python/cpython/issues/103489}: Add @ref{4a2,,getconfig()} and
@ref{4a3,,setconfig()} to @ref{242,,Connection} to
make configuration changes to a database connection. Patch by Erlend E.
Aasland.

@item 
gh-103365@footnote{https://github.com/python/cpython/issues/103365}: Set default Flag boundary to @code{STRICT} and fix bitwise
operations.

@item 
gh-103472@footnote{https://github.com/python/cpython/issues/103472}: Avoid a potential @ref{241,,ResourceWarning} in
@ref{b2e,,http.client.HTTPConnection} by closing the proxy / tunnel's
CONNECT response explicitly.

@item 
gh-103462@footnote{https://github.com/python/cpython/issues/103462}: Fixed an issue with using
@ref{150a,,writelines()} in @ref{a,,asyncio} to send very
large payloads that exceed the amount of data that can be written in one
call to @ref{d94,,socket.socket.send()} or @ref{460,,socket.socket.sendmsg()},
resulting in the remaining buffer being left unwritten.

@item 
gh-103449@footnote{https://github.com/python/cpython/issues/103449}: Fix a bug in doc string generation in
@ref{1c6,,dataclasses.dataclass()}.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Isolate @code{_collections} (apply 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}). Patch by
Erlend E. Aasland.

@item 
gh-103357@footnote{https://github.com/python/cpython/issues/103357}: Added support for @ref{1449,,logging.Formatter} @code{defaults}
parameter to @ref{118d,,logging.config.dictConfig()} and
@ref{b3f,,logging.config.fileConfig()}. Patch by Bar Harel.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Adapt the @ref{115,,winreg} extension module to 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: The performance of @ref{42b,,isinstance()} checks against
@ref{42c,,runtime-checkable protocols} has been
considerably improved for protocols that only have a few members. To
achieve this improvement, several internal implementation details of the
@ref{103,,typing} module have been refactored, including
@code{typing._ProtocolMeta.__instancecheck__},
@code{typing._is_callable_members_only}, and @code{typing._get_protocol_attrs}.
Patches by Alex Waygood.

@item 
gh-74690@footnote{https://github.com/python/cpython/issues/74690}: The members of a runtime-checkable protocol are now considered
"frozen" at runtime as soon as the class has been created. See
@ref{4ba,,"What's new in Python 3.12"} for more
details.

@item 
gh-103256@footnote{https://github.com/python/cpython/issues/103256}: Fixed a bug that caused @ref{69,,hmac} to raise an exception when
the requested hash algorithm was not available in OpenSSL despite being
available separately as part of @code{hashlib} itself.  It now falls back
properly to the built-in. This could happen when, for example, your
OpenSSL does not include SHA3 support and you want to compute
@code{hmac.digest(b'K', b'M', 'sha3_256')}.

@item 
gh-102778@footnote{https://github.com/python/cpython/issues/102778}: Support @code{sys.last_exc} in @ref{72,,idlelib}.

@item 
gh-103285@footnote{https://github.com/python/cpython/issues/103285}: Improve performance of @ref{9c5,,ast.get_source_segment()}.

@item 
gh-103225@footnote{https://github.com/python/cpython/issues/103225}: Fix a bug in @ref{a4,,pdb} when displaying line numbers of
module-level source code.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Adapt the @ref{92,,msvcrt} extension module to 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Adapt the @ref{116,,winsound} extension module to 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}.

@item 
gh-93910@footnote{https://github.com/python/cpython/issues/93910}: Remove deprecation of enum @code{member.member} access.

@item 
gh-102978@footnote{https://github.com/python/cpython/issues/102978}: Fixes @ref{e7b,,unittest.mock.patch()} not enforcing function
signatures for methods decorated with @code{@@classmethod} or
@code{@@staticmethod} when patch is called with @code{autospec=True}.

@item 
gh-103092@footnote{https://github.com/python/cpython/issues/103092}: Isolate @code{_socket} (apply 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}). Patch by Erlend E.
Aasland.

@item 
gh-100479@footnote{https://github.com/python/cpython/issues/100479}: Add @ref{491,,pathlib.PurePath.with_segments()}, which creates a
path object from arguments. This method is called whenever a derivative
path is created, such as from @ref{16b7,,pathlib.PurePath.parent}. Subclasses
may override this method to share information between path objects.

@item 
gh-103220@footnote{https://github.com/python/cpython/issues/103220}: Fix issue where @ref{15bc,,os.path.join()} added a slash when joining
onto an incomplete UNC drive with a trailing slash on Windows.

@item 
gh-103204@footnote{https://github.com/python/cpython/issues/103204}: Fixes @ref{71,,http.server} accepting HTTP requests with HTTP
version numbers preceded by '+', or '-', or with digit-separating '_'
characters.  The length of the version numbers is also constrained.

@item 
gh-75586@footnote{https://github.com/python/cpython/issues/75586}: Fix various Windows-specific issues with @code{shutil.which}.

@item 
gh-103193@footnote{https://github.com/python/cpython/issues/103193}: Improve performance of @ref{47e,,inspect.getattr_static()}. Patch by
Alex Waygood.

@item 
gh-103176@footnote{https://github.com/python/cpython/issues/103176}: @ref{4ab,,sys._current_exceptions()} now returns a mapping from
thread-id to an exception instance, rather than to a @code{(typ, exc, tb)}
tuple.

@item 
gh-103143@footnote{https://github.com/python/cpython/issues/103143}: Polish the help messages and docstrings of @ref{a4,,pdb}.

@item 
gh-103015@footnote{https://github.com/python/cpython/issues/103015}: Add `entrypoint' keyword-only parameter to
@ref{4a1,,sqlite3.Connection.load_extension()}, for overriding the SQLite
extension entry point. Patch by Erlend E. Aasland.

@item 
gh-103000@footnote{https://github.com/python/cpython/issues/103000}: Improve performance of @ref{16b8,,dataclasses.astuple()} and
@ref{16af,,dataclasses.asdict()} in cases where the contents are common Python
types.

@item 
gh-102953@footnote{https://github.com/python/cpython/issues/102953}: The extraction methods in @ref{dd,,tarfile}, and
@ref{455,,shutil.unpack_archive()}, have a new a `filter' argument that allows
limiting tar features than may be surprising or dangerous, such as
creating files outside the destination directory. See
@ref{456,,Extraction filters} for details.

@item 
gh-97696@footnote{https://github.com/python/cpython/issues/97696}: Implemented an eager task factory in asyncio. When used as a
task factory on an event loop, it performs eager execution of coroutines.
Coroutines that are able to complete synchronously (e.g. return or raise
without blocking) are returned immediately as a finished task, and the
task is never scheduled to the event loop. If the coroutine blocks, the
(pending) task is scheduled and returned.

@item 
gh-81079@footnote{https://github.com/python/cpython/issues/81079}: Add `case_sensitive' keyword-only argument to
@ref{22a,,pathlib.Path.glob()} and @ref{22b,,rglob()}.

@item 
gh-101819@footnote{https://github.com/python/cpython/issues/101819}: Isolate the @ref{7e,,io} extension module by applying 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}.
Patch by Kumar Aditya, Victor Stinner, and Erlend E. Aasland.

@item 
gh-91896@footnote{https://github.com/python/cpython/issues/91896}: Deprecate @ref{2c0,,collections.abc.ByteString}

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{226,,pathlib.Path} construction by omitting the
path anchor from the internal list of path parts.

@item 
gh-102114@footnote{https://github.com/python/cpython/issues/102114}: Functions in the @ref{38,,dis} module that accept a source code
string as argument now print a more concise traceback when the string
contains a syntax or indentation error.

@item 
gh-62432@footnote{https://github.com/python/cpython/issues/62432}: The @ref{105,,unittest} runner will now exit with status code 5 if
no tests were run. It is common for test runner misconfiguration to fail
to find any tests, this should be an error.

@item 
gh-78079@footnote{https://github.com/python/cpython/issues/78079}: Fix incorrect normalization of UNC device path roots, and
partial UNC share path roots, in @ref{490,,pathlib.PurePath}. Pathlib no
longer appends a trailing slash to such paths.

@item 
gh-85984@footnote{https://github.com/python/cpython/issues/85984}: Add @ref{1656,,tty.cfmakeraw()} and @ref{1602,,tty.cfmakecbreak()} to
@ref{ff,,tty} and modernize, the behavior of @ref{1655,,tty.setraw()} and
@ref{1601,,tty.setcbreak()} to use POSIX.1-2017 Chapter 11 "General Terminal
Interface" flag masks by default.

@item 
gh-101688@footnote{https://github.com/python/cpython/issues/101688}: Implement @ref{4b7,,types.get_original_bases()} to provide further
introspection for types.

@item 
gh-101640@footnote{https://github.com/python/cpython/issues/101640}: @ref{523,,argparse.ArgumentParser} now catches errors when
writing messages, such as when @ref{926,,sys.stderr} is @code{None}. Patch by
Oleg Iarygin.

@item 
gh-83861@footnote{https://github.com/python/cpython/issues/83861}: Fix datetime.astimezone method return value when invoked on a
naive datetime instance that represents local time falling in a timezone
transition gap. PEP 495 requires that instances with fold=1 produce
earlier times than those with fold=0 in this case.

@item 
gh-89550@footnote{https://github.com/python/cpython/issues/89550}: Decrease execution time of some @ref{66,,gzip} file writes by 15%
by adding more appropriate buffering.

@item 
gh-95299@footnote{https://github.com/python/cpython/issues/95299}: Remove the bundled setuptools wheel from @code{ensurepip}, and stop
installing setuptools in environments created by @code{venv}.

@item 
gh-99353@footnote{https://github.com/python/cpython/issues/99353}: Respect the @ref{b2e,,http.client.HTTPConnection} @code{.debuglevel}
flag in @code{urllib.request.AbstractHTTPHandler} when its constructor
parameter @code{debuglevel} is not set. And do the same for @code{*HTTPS*}.

@item 
gh-98040@footnote{https://github.com/python/cpython/issues/98040}: Remove the long-deprecated @code{imp} module.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Deprecate @ref{2c9,,pkgutil.find_loader()} and
@ref{2ca,,pkgutil.get_loader()} in favor of @ref{2cb,,importlib.util.find_spec()}.

@item 
gh-94473@footnote{https://github.com/python/cpython/issues/94473}: Flatten arguments in @code{tkinter.Canvas.coords()}. It now
accepts not only @code{x1, y1, x2, y2, ...} and @code{[x1, y1, x2, y2, ...]},
but also @code{(x1, y1), (x2, y2), ...} and @code{[(x1, y1), (x2, y2), ...]}.

@item 
gh-98040@footnote{https://github.com/python/cpython/issues/98040}: Remove more deprecated importlib APIs: @code{find_loader()},
@code{find_module()}, @code{importlib.abc.Finder}, @code{pkgutil.ImpImporter},
@code{pkgutil.ImpLoader}.

@item 
gh-96522@footnote{https://github.com/python/cpython/issues/96522}: Fix potential deadlock in pty.spawn()

@item 
gh-96534@footnote{https://github.com/python/cpython/issues/96534}: Support divert(4) added in FreeBSD 14.

@item 
gh-87474@footnote{https://github.com/python/cpython/issues/87474}: Fix potential file descriptor leaks in
@ref{197,,subprocess.Popen}.

@item 
gh-94906@footnote{https://github.com/python/cpython/issues/94906}: Support multiple steps in @ref{482,,math.nextafter()}. Patch by
Shantanu Jain and Matthias Gorgens.

@item 
gh-51574@footnote{https://github.com/python/cpython/issues/51574}: Make @ref{21c,,tempfile.mkdtemp()} return absolute paths when its
`dir' parameter is relative.

@item 
gh-94518@footnote{https://github.com/python/cpython/issues/94518}: Convert private @code{_posixsubprocess.fork_exec()} to use
Argument Clinic.

@item 
gh-92184@footnote{https://github.com/python/cpython/issues/92184}: When creating zip files using @ref{130,,zipfile}, @code{os.altsep}, if
not @code{None}, will always be treated as a path separator even when it is
not @code{/}. Patch by Carey Metcalfe.

@item 
bpo-46797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46797}: Deprecation warnings are now emitted for @code{ast.Num},
@code{ast.Bytes}, @code{ast.Str}, @code{ast.NameConstant} and
@code{ast.Ellipsis}. These have been documented as deprecated since
Python 3.8, and will be removed in Python 3.14.

@item 
bpo-44844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44844}: Enables @ref{114,,webbrowser} to detect and launch Microsoft Edge
browser.

@item 
bpo-45606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45606}: Fixed the bug in @ref{22a,,pathlib.Path.glob()} -- previously a
dangling symlink would not be found by this method when the pattern is an
exact match, but would be found when the pattern contains a wildcard or
the recursive wildcard (@code{**}). With this change, a dangling symlink will
be found in both cases.

@item 
bpo-23041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23041}: Add @ref{46f,,QUOTE_STRINGS} and @ref{46e,,QUOTE_NOTNULL}
to the suite of @ref{29,,csv} module quoting styles.

@item 
bpo-24964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24964}: Added
@ref{168c,,http.client.HTTPConnection.get_proxy_response_headers()} that
provides access to the HTTP headers on a proxy server response to the
@code{CONNECT} request.

@item 
bpo-17258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17258}: @ref{93,,multiprocessing} now supports stronger HMAC algorithms
for inter-process connection authentication rather than only HMAC-MD5.

@item 
bpo-39744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39744}: Make @ref{16b9,,asyncio.subprocess.Process.communicate()} close the
subprocess's stdin even when called with @code{input=None}.

@item 
bpo-22708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22708}: http.client CONNECT method tunnel improvements: Use HTTP 1.1
protocol; send a matching Host: header with CONNECT, if one is not
provided; convert IDN domain names to Punycode. Patch by Michael Handler.
@end itemize

@node Documentation<11>,Tests<14>,Library<16>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id126}@anchor{16ba}
@subsubsection Documentation



@itemize -

@item 
gh-67056@footnote{https://github.com/python/cpython/issues/67056}: Document that the effect of registering or unregistering an
@ref{c,,atexit} cleanup function from within a registered cleanup function
is undefined.

@item 
gh-103629@footnote{https://github.com/python/cpython/issues/103629}: Mention the new way of typing @code{**kwargs} with @code{Unpack} and
@code{TypedDict} introduced in 
@geindex Python Enhancement Proposals; PEP 692
PEP 692@footnote{https://peps.python.org/pep-0692/}.

@item 
gh-48241@footnote{https://github.com/python/cpython/issues/48241}: Clarifying documentation about the url parameter to
urllib.request.urlopen and urllib.request.Request needing to be encoded
properly.

@item 
gh-86094@footnote{https://github.com/python/cpython/issues/86094}: Add support for Unicode Path Extra Field in ZipFile. Patch by
Yeojin Kim and Andrea Giudiceandrea

@item 
gh-99202@footnote{https://github.com/python/cpython/issues/99202}: Fix extension type from documentation for compiling in C++20
mode
@end itemize

@node Tests<14>,Build<16>,Documentation<11>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id127}@anchor{16bb}
@subsubsection Tests



@itemize -

@item 
gh-104494@footnote{https://github.com/python/cpython/issues/104494}: Update @code{test_pack_configure_in} and
@code{test_place_configure_in} for changes to error message formatting in Tk
8.7.

@item 
gh-104461@footnote{https://github.com/python/cpython/issues/104461}: Run test_configure_screen on X11 only, since the @code{DISPLAY}
environment variable and @code{-screen} option for toplevels are not useful
on Tk for Win32 or Aqua.

@item 
gh-86275@footnote{https://github.com/python/cpython/issues/86275}: Added property-based tests to the @ref{133,,zoneinfo} tests, along
with stubs for the @code{hypothesis} interface. (Patch by Paul Ganssle)

@item 
gh-103329@footnote{https://github.com/python/cpython/issues/103329}: Regression tests for the behaviour of
@code{unittest.mock.PropertyMock} were added.

@item 
gh-102795@footnote{https://github.com/python/cpython/issues/102795}: fix use of poll in test_epoll's test_control_and_wait

@item 
gh-75729@footnote{https://github.com/python/cpython/issues/75729}: Fix the @ref{16bc,,os.spawn*} tests failing on Windows
when the working directory or interpreter path contains spaces.
@end itemize

@node Build<16>,Windows<13>,Tests<14>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id128}@anchor{16bd}
@subsubsection Build



@itemize -

@item 
gh-101282@footnote{https://github.com/python/cpython/issues/101282}: BOLT optimization is now applied to the libpython shared
library if building a shared library. BOLT instrumentation and application
settings can now be influenced via the @code{BOLT_INSTRUMENT_FLAGS} and
@code{BOLT_APPLY_FLAGS} configure variables.

@item 
gh-99017@footnote{https://github.com/python/cpython/issues/99017}: @code{PYTHON_FOR_REGEN} now require Python 3.10 or newer.

@item 
gh-104490@footnote{https://github.com/python/cpython/issues/104490}: Define @code{.PHONY} / virtual make targets consistently and
properly.

@item 
gh-104106@footnote{https://github.com/python/cpython/issues/104106}: Add gcc fallback of mkfifoat/mknodat for macOS. Patch by
Donghee Na.

@item 
gh-103532@footnote{https://github.com/python/cpython/issues/103532}: The @code{TKINTER_PROTECT_LOADTK} macro is no longer defined or
used in the @code{_tkinter} module.  It was previously only defined when
building against Tk 8.4.13 and older, but Tk older than 8.5.12 has been
unsupported since gh-91152@footnote{https://github.com/python/cpython/issues/91152}.

@item 
gh-99069@footnote{https://github.com/python/cpython/issues/99069}: Extended workaround defining @code{static_assert} when missing from
the libc headers to all clang and gcc builds. In particular, this fixes
building on macOS <= 10.10.

@item 
gh-100220@footnote{https://github.com/python/cpython/issues/100220}: Changed the default value of the @code{SHELL} Makefile variable
from @code{/bin/sh} to @code{/bin/sh -e} to ensure that complex recipes
correctly fail after an error. Previously, @code{make install} could fail to
install some files and yet return a successful result.

@item 
gh-90656@footnote{https://github.com/python/cpython/issues/90656}: Add platform triplets for 64-bit LoongArch:


@itemize *

@item 
loongarch64-linux-gnusf

@item 
loongarch64-linux-gnuf32

@item 
loongarch64-linux-gnu
@end itemize

Patch by Zhang Na.
@end itemize

@node Windows<13>,macOS<10>,Build<16>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id129}@anchor{16be}
@subsubsection Windows



@itemize -

@item 
gh-104623@footnote{https://github.com/python/cpython/issues/104623}: Update Windows installer to use SQLite 3.42.0.

@item 
gh-82814@footnote{https://github.com/python/cpython/issues/82814}: Fix a potential @code{[Errno 13] Permission denied} when using
@ref{110e,,shutil.copystat()} within Windows Subsystem for Linux (WSL) on a
mounted filesystem by adding @code{errno.EACCES} to the list of ignored
errors within the internal implementation.

@item 
gh-103088@footnote{https://github.com/python/cpython/issues/103088}: Fix virtual environment @code{activate} script having
incorrect line endings for Cygwin.

@item 
gh-103088@footnote{https://github.com/python/cpython/issues/103088}: Fixes venvs not working in bash on Windows across different
disks

@item 
gh-102997@footnote{https://github.com/python/cpython/issues/102997}: Update Windows installer to use SQLite 3.41.2.

@item 
gh-88013@footnote{https://github.com/python/cpython/issues/88013}: Fixed a bug where @ref{522,,TypeError} was raised when calling
@code{ntpath.realpath()} with a bytes parameter in some cases.
@end itemize

@node macOS<10>,IDLE<14>,Windows<13>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id130}@anchor{16bf}
@subsubsection macOS



@itemize -

@item 
gh-99834@footnote{https://github.com/python/cpython/issues/99834}: Update macOS installer to Tcl/Tk 8.6.13.

@item 
gh-104623@footnote{https://github.com/python/cpython/issues/104623}: Update macOS installer to SQLite 3.42.0.

@item 
gh-103545@footnote{https://github.com/python/cpython/issues/103545}: Add @code{os.PRIO_DARWIN_THREAD}, @code{os.PRIO_DARWIN_PROCESS},
@code{os.PRIO_DARWIN_BG} and @code{os.PRIO_DARWIN_NONUI}. These can be used with
@code{os.setpriority} to run the process at a lower priority and make use of
the efficiency cores on Apple Silicon systems.

@item 
gh-104180@footnote{https://github.com/python/cpython/issues/104180}: Support reading SOCKS proxy configuration from macOS System
Configuration. Patch by Sam Schott.

@item 
gh-60436@footnote{https://github.com/python/cpython/issues/60436}: update curses textbox to additionally handle backspace using the
@code{curses.ascii.DEL} key press.

@item 
gh-102997@footnote{https://github.com/python/cpython/issues/102997}: Update macOS installer to SQLite 3.41.2.
@end itemize

@node IDLE<14>,Tools/Demos<8>,macOS<10>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id131}@anchor{16c0}
@subsubsection IDLE



@itemize -

@item 
gh-104499@footnote{https://github.com/python/cpython/issues/104499}: Fix completions for Tk Aqua 8.7 (currently blank).

@item 
gh-104496@footnote{https://github.com/python/cpython/issues/104496}: About prints both tcl and tk versions if different (expected
someday).

@item 
gh-88496@footnote{https://github.com/python/cpython/issues/88496}: Fix IDLE test hang on macOS.
@end itemize

@node Tools/Demos<8>,C API<16>,IDLE<14>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id132}@anchor{16c1}
@subsubsection Tools/Demos



@itemize -

@item 
gh-104389@footnote{https://github.com/python/cpython/issues/104389}: Argument Clinic C converters now accept the @code{unused} keyword,
for wrapping a parameter with @ref{16a6,,Py_UNUSED}. Patch by Erlend E.
Aasland.
@end itemize

@node C API<16>,,Tools/Demos<8>,Python 3 12 0 beta 1
@anchor{whatsnew/changelog id133}@anchor{16c2}
@subsubsection C API



@itemize -

@item 
gh-101291@footnote{https://github.com/python/cpython/issues/101291}: Added unstable C API for extracting the value of "compact"
integers: @ref{575,,PyUnstable_Long_IsCompact()} and
@ref{576,,PyUnstable_Long_CompactValue()}.

@item 
gh-104109@footnote{https://github.com/python/cpython/issues/104109}: We've added @code{Py_NewInterpreterFromConfig()} and
@code{PyInterpreterConfig} to the public C-API (but not the stable ABI; not
yet at least).  The new function may be used to create a new interpreter
with various features configured.  The function was added to support PEP
684 (per-interpreter GIL).

@item 
gh-103968@footnote{https://github.com/python/cpython/issues/103968}: @ref{569,,PyType_FromSpec()} and its variants now allow creating
classes whose metaclass overrides @ref{56b,,tp_new}. The
@code{tp_new} is ignored. This behavior is deprecated and will be disallowed
in 3.14+. The new @ref{53b,,PyType_FromMetaclass()} already disallows it.

@item 
gh-103743@footnote{https://github.com/python/cpython/issues/103743}: Add @ref{16c3,,PyUnstable_Object_GC_NewWithExtraData()} function
that can be used to allocate additional memory after an object for data
not managed by Python.

@item 
gh-103295@footnote{https://github.com/python/cpython/issues/103295}: Introduced @ref{16c4,,PyUnstable_WritePerfMapEntry()},
@ref{16c5,,PyUnstable_PerfMapState_Init()} and
@ref{16c6,,PyUnstable_PerfMapState_Fini()}. These allow extension modules (JIT
compilers in particular) to write to perf-map files in a thread safe
manner. The @ref{16c7,,Python support for the Linux perf profiler} also uses these APIs to write
entries in the perf-map file.

@item 
gh-103509@footnote{https://github.com/python/cpython/issues/103509}: Added C API for extending types whose instance memory layout is
opaque: @ref{533,,PyType_Spec.basicsize} can now be zero or negative,
@ref{534,,PyObject_GetTypeData()} can be used to get subclass-specific data,
and @ref{536,,Py_TPFLAGS_ITEMS_AT_END} can be used to safely extend
variable-size objects. See 
@geindex Python Enhancement Proposals; PEP 697
PEP 697@footnote{https://peps.python.org/pep-0697/} for details.

@item 
gh-103091@footnote{https://github.com/python/cpython/issues/103091}: Add a new C-API function to eagerly assign a version tag to a
PyTypeObject: @code{PyUnstable_Type_AssignVersionTag()}.

@item 
gh-101408@footnote{https://github.com/python/cpython/issues/101408}: @ref{16c8,,PyObject_GC_Resize} should calculate preheader size
if needed. Patch by Donghee Na.

@item 
gh-98836@footnote{https://github.com/python/cpython/issues/98836}: Add support of more formatting options (left aligning, octals,
uppercase hexadecimals, @code{intmax_t}, @code{ptrdiff_t},
@code{wchar_t} C strings, variable width and precision) in
@ref{380,,PyUnicode_FromFormat()} and @ref{560,,PyUnicode_FromFormatV()}.

@item 
gh-96803@footnote{https://github.com/python/cpython/issues/96803}: Add unstable C-API functions to get the code object, lasti and
line number from the internal @code{_PyInterpreterFrame} in the limited API.
The functions are:


@itemize *

@item 
@code{PyCodeObject * PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame)}

@item 
@code{int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame)}

@item 
@code{int PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame)}
@end itemize
@end itemize

@node Python 3 12 0 alpha 7,Python 3 12 0 alpha 6,Python 3 12 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-7}@anchor{16c9}
@subsection Python 3.12.0 alpha 7


`Release date: 2023-04-04'

@menu
* Core and Builtins: Core and Builtins<18>. 
* Library: Library<17>. 
* Documentation: Documentation<12>. 
* Tests: Tests<15>. 
* Build: Build<17>. 
* Windows: Windows<14>. 
* Tools/Demos: Tools/Demos<9>. 
* C API: C API<17>. 

@end menu

@node Core and Builtins<18>,Library<17>,,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id134}@anchor{16ca}
@subsubsection Core and Builtins



@itemize -

@item 
gh-102192@footnote{https://github.com/python/cpython/issues/102192}: Deprecated @code{_PyErr_ChainExceptions} in favour of
@code{_PyErr_ChainExceptions1}.

@item 
gh-89987@footnote{https://github.com/python/cpython/issues/89987}: Reduce the number of inline @ref{6e3,,CACHE} entries for
@ref{16cb,,BINARY_SUBSCR}.

@item 
gh-102859@footnote{https://github.com/python/cpython/issues/102859}: Removed @code{JUMP_IF_FALSE_OR_POP} and
@code{JUMP_IF_TRUE_OR_POP} instructions.

@item 
gh-101975@footnote{https://github.com/python/cpython/issues/101975}: Fixed @code{stacktop} value on tracing entries to avoid corruption
on garbage collection.

@item 
gh-102778@footnote{https://github.com/python/cpython/issues/102778}: Add @ref{4a7,,sys.last_exc} and deprecate @ref{4a8,,sys.last_type},
@ref{4a9,,sys.last_value} and @ref{4aa,,sys.last_traceback}, which hold the same
information in its legacy form.

@item 
gh-100982@footnote{https://github.com/python/cpython/issues/100982}: Replace all occurrences of @code{COMPARE_AND_BRANCH} with
@ref{956,,COMPARE_OP}.

@item 
gh-102701@footnote{https://github.com/python/cpython/issues/102701}: Fix overflow when creating very large dict.

@item 
gh-102755@footnote{https://github.com/python/cpython/issues/102755}: Add @ref{3f8,,PyErr_DisplayException()} which takes just an
exception instance, to replace the legacy @code{PyErr_Display()} which
takes the @code{(typ, exc, tb)} triplet.

@item 
gh-102594@footnote{https://github.com/python/cpython/issues/102594}: Add note to exception raised in @code{PyErr_SetObject} when
normalization fails.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Shrink the number of inline @ref{6e3,,CACHE} entries used by
@ref{1673,,LOAD_GLOBAL}.

@item 
gh-102491@footnote{https://github.com/python/cpython/issues/102491}: Improve import time of @code{platform} by removing IronPython
version parsing. The IronPython version parsing was not functional (see
@indicateurl{https://github.com/IronLanguages/ironpython3/issues/1667}).

@item 
gh-101291@footnote{https://github.com/python/cpython/issues/101291}: Rearrage bits in first field (after header) of PyLongObject. *
Bits 0 and 1: 1 - sign. I.e. 0 for positive numbers, 1 for zero and 2 for
negative numbers. * Bit 2 reserved (probably for the immortal bit) * Bits
3+ the unsigned size.

This makes a few operations slightly more efficient, and will enable a
more compact and faster 2s-complement representation of most ints in
future.

@item 
gh-102397@footnote{https://github.com/python/cpython/issues/102397}: Fix segfault from race condition in signal handling during
garbage collection. Patch by Kumar Aditya.

@item 
gh-102406@footnote{https://github.com/python/cpython/issues/102406}: @ref{1b,,codecs} encoding/decoding errors now get the context
information (which operation and which codecs) attached as 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/}
notes instead of through chaining a new instance of the exception.

@item 
gh-102281@footnote{https://github.com/python/cpython/issues/102281}: Fix potential nullptr dereference and use of uninitialized
memory in fileutils. Patch by Max Bachmann.

@item 
gh-102300@footnote{https://github.com/python/cpython/issues/102300}: Reuse operands with refcount of 1 in float specializations of
BINARY_OP.

@item 
gh-102213@footnote{https://github.com/python/cpython/issues/102213}: Fix performance loss when accessing an object's attributes with
@code{__getattr__}  defined.

@item 
gh-102255@footnote{https://github.com/python/cpython/issues/102255}: Improve build support for the Xbox. Patch by Max Bachmann.

@item 
gh-102027@footnote{https://github.com/python/cpython/issues/102027}: Fix SSE2 and SSE3 detection in @code{_blake2} internal module.
Patch by Max Bachmann.

@item 
gh-101865@footnote{https://github.com/python/cpython/issues/101865}: Deprecate @code{co_lnotab} in code objects, schedule it for
removal in Python 3.14

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Adapt @code{_pickle} to 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}. Patch by Mohamed Koubaa
and Erlend Aasland.
@end itemize

@node Library<17>,Documentation<12>,Core and Builtins<18>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id135}@anchor{16cc}
@subsubsection Library



@itemize -

@item 
gh-103085@footnote{https://github.com/python/cpython/issues/103085}: Pure python @ref{2db,,locale.getencoding()} will not warn
deprecation.

@item 
gh-103068@footnote{https://github.com/python/cpython/issues/103068}: It's no longer possible to register conditional breakpoints in
@ref{90f,,Pdb} that raise @ref{18b,,SyntaxError}. Patch by Tian Gao.

@item 
gh-102549@footnote{https://github.com/python/cpython/issues/102549}: Don't ignore exceptions in member type creation.

@item 
gh-103056@footnote{https://github.com/python/cpython/issues/103056}: Ensure final @code{_generate_next_value_} is a @code{staticmethod}.

@item 
gh-103046@footnote{https://github.com/python/cpython/issues/103046}: Display current line label correctly in @ref{38,,dis} when
@code{show_caches} is False and @code{lasti} points to a CACHE entry.

@item 
gh-102433@footnote{https://github.com/python/cpython/issues/102433}: @ref{42b,,isinstance()} checks against @ref{42c,,runtime-checkable protocols} now use
@ref{47e,,inspect.getattr_static()} rather than @ref{4bb,,hasattr()} to lookup
whether attributes exist. This means that descriptors and
@ref{4bc,,__getattr__()} methods are no longer unexpectedly evaluated
during @code{isinstance()} 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. Patch by Alex Waygood.

@item 
gh-103023@footnote{https://github.com/python/cpython/issues/103023}: It's no longer possible to register expressions to display in
@ref{90f,,Pdb} that raise @ref{18b,,SyntaxError}. Patch by Tian Gao.

@item 
gh-102947@footnote{https://github.com/python/cpython/issues/102947}: Improve traceback when @ref{16cd,,dataclasses.fields()} is called on
a non-dataclass. Patch by Alex Waygood

@item 
gh-102780@footnote{https://github.com/python/cpython/issues/102780}: The @ref{1654,,asyncio.Timeout} context manager now works reliably
even when performing cleanup due to task cancellation.  Previously it
could raise a @ref{1b6,,CancelledError} instead of an
@ref{16ce,,TimeoutError} in such cases.

@item 
gh-102871@footnote{https://github.com/python/cpython/issues/102871}: Remove support for obsolete browsers from @ref{114,,webbrowser}.
Removed browsers include Grail, Mosaic, Netscape, Galeon, Skipstone,
Iceape, Firebird, and Firefox versions 35 and below.

@item 
gh-102839@footnote{https://github.com/python/cpython/issues/102839}: Improve performance of @ref{1474,,math.log()} arguments handling by
removing the argument clinic.

@item 
gh-102828@footnote{https://github.com/python/cpython/issues/102828}: Add the @code{onexc} arg to @ref{2f5,,shutil.rmtree()}, which is like
@code{onerror} but expects an exception instance rather than an exc_info
tuple. Deprecate @code{onerror}.

@item 
gh-88965@footnote{https://github.com/python/cpython/issues/88965}: typing: Fix a bug relating to substitution in custom classes
generic over a @ref{15d,,ParamSpec}. Previously, if the
@code{ParamSpec} was substituted with a parameters list that itself contained
a @ref{15c,,TypeVar}, the @code{TypeVar} in the parameters list could
not be subsequently substituted. This is now fixed.

Patch by Nikita Sobolev.

@item 
gh-76846@footnote{https://github.com/python/cpython/issues/76846}: Fix issue where @code{__new__()} and @code{__init__()} methods of
@ref{490,,pathlib.PurePath} and @ref{226,,Path} subclasses were not
called in some circumstances.

@item 
gh-78530@footnote{https://github.com/python/cpython/issues/78530}: @ref{469,,asyncio.wait()} now accepts generators yielding tasks.
Patch by Kumar Aditya.

@item 
gh-102748@footnote{https://github.com/python/cpython/issues/102748}: @ref{468,,asyncio.iscoroutine()} now returns @code{False} for
generators as @ref{a,,asyncio} does not support legacy generator-based
coroutines. Patch by Kumar Aditya.

@item 
gh-102670@footnote{https://github.com/python/cpython/issues/102670}: Optimized fmean(), correlation(), covariance(), and
linear_regression() using the new math.sumprod() function.

@item 
gh-102615@footnote{https://github.com/python/cpython/issues/102615}: Typing: Improve the @code{repr} of generic aliases for classes
generic over a @ref{15d,,ParamSpec}. (Use square brackets to
represent a parameter list.)

@item 
gh-100112@footnote{https://github.com/python/cpython/issues/100112}: @ref{9c9,,asyncio.Task.get_coro()} now always returns a coroutine
when wrapping an awaitable object. Patch by Kumar Aditya.

@item 
gh-102578@footnote{https://github.com/python/cpython/issues/102578}: Speed up setting or deleting mutable attributes on
non-dataclass subclasses of frozen dataclasses. Due to the implementation
of @code{__setattr__} and @code{__delattr__} for frozen dataclasses, this
previously had a time complexity of `O'(`n'). It now has a time
complexity of `O'(1).

@item 
gh-102519@footnote{https://github.com/python/cpython/issues/102519}: Add @ref{487,,os.listdrives()}, @ref{488,,os.listvolumes()} and
@ref{489,,os.listmounts()} functions on Windows for enumerating drives, volumes
and mount points

@item 
gh-74468@footnote{https://github.com/python/cpython/issues/74468}: Attribute name of the extracted @ref{dd,,tarfile} file object now
holds filename of itself rather than of the archive it is contained in.
Patch by Oleg Iarygin.

@item 
gh-102378@footnote{https://github.com/python/cpython/issues/102378}: Private helper method
@code{inspect._signature_strip_non_python_syntax} will no longer strip @code{/}
from the input string.

@item 
gh-79940@footnote{https://github.com/python/cpython/issues/79940}: Add @ref{47c,,inspect.getasyncgenstate()} and
@ref{47d,,inspect.getasyncgenlocals()}. Patch by Thomas Krennwallner.

@item 
gh-102103@footnote{https://github.com/python/cpython/issues/102103}: Add @code{module} argument to @ref{16cf,,dataclasses.make_dataclass()}
and make classes produced by it pickleable.

@item 
gh-102069@footnote{https://github.com/python/cpython/issues/102069}: Fix @code{__weakref__} descriptor generation for custom
dataclasses.

@item 
gh-102038@footnote{https://github.com/python/cpython/issues/102038}: Skip a @code{stat} in @ref{c6,,site} if we have already found a
@code{pyvenv.cfg}

@item 
gh-98886@footnote{https://github.com/python/cpython/issues/98886}: Fix issues when defining dataclasses that have fields with
specific underscore names that aren't clearly reserved by
@ref{2f,,dataclasses}.

@item 
gh-101673@footnote{https://github.com/python/cpython/issues/101673}: Fix a @ref{a4,,pdb} bug where @code{ll} clears the changes to local
variables.

@item 
gh-101313@footnote{https://github.com/python/cpython/issues/101313}: Added -h and --help arguments to the webbrowser CLI

@item 
gh-100372@footnote{https://github.com/python/cpython/issues/100372}: @ref{ed6,,ssl.SSLContext.load_verify_locations()} no longer
incorrectly accepts some cases of trailing data when parsing DER.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Fix pathlib.Path.walk RecursionError on deep directory trees by
rewriting it using iteration instead of recursion.

@item 
gh-100131@footnote{https://github.com/python/cpython/issues/100131}: Added an optional @code{delete} keyword argument to
@ref{1212,,tempfile.TemporaryDirectory}.

@item 
gh-48330@footnote{https://github.com/python/cpython/issues/48330}: Added @code{--durations} command line option, showing the N slowest
test cases. @ref{16d0,,unittest.TextTestRunner} and
@ref{51a,,unittest.TextTestResult} constructors accept a new `durations'
keyword argument. Subclasses should take this into account or accept
@code{**kwargs}. Added @ref{16d1,,unittest.TestResult.addDuration()} method and
@ref{1698,,unittest.TestResult.collectedDurations} attribute.

(Contributed by Giampaolo Rodola)

@item 
gh-98169@footnote{https://github.com/python/cpython/issues/98169}: Fix @ref{16b8,,dataclasses.astuple()} crash when
@ref{119a,,collections.defaultdict} is present in the attributes.

@item 
gh-96931@footnote{https://github.com/python/cpython/issues/96931}: Fix incorrect results from @ref{e55,,ssl.SSLSocket.shared_ciphers()}

@item 
gh-95495@footnote{https://github.com/python/cpython/issues/95495}: When built against OpenSSL 3.0, the @ref{cf,,ssl} module had a bug
where it reported unauthenticated EOFs (i.e. without close_notify) as a
clean TLS-level EOF. It now raises @ref{16d2,,SSLEOFError}, matching the
behavior in previous versions of OpenSSL. The
@ref{822,,options} attribute on @ref{291,,SSLContext} also
no longer includes @ref{821,,OP_IGNORE_UNEXPECTED_EOF} by default. This
option may be set to specify the previous OpenSSL 3.0 behavior.

@item 
gh-94684@footnote{https://github.com/python/cpython/issues/94684}: Now @ref{16d3,,uuid.uuid3()} and @ref{16d4,,uuid.uuid5()} functions support
@ref{1bd,,bytes} objects as their `name' argument.

@item 
gh-94440@footnote{https://github.com/python/cpython/issues/94440}: Fix a @code{concurrent.futures.process} bug where
@code{ProcessPoolExecutor} shutdown could hang after a future has been
quickly submitted and canceled.

@item 
gh-72346@footnote{https://github.com/python/cpython/issues/72346}: Added deprecation warning to `isdst' parameter of
@ref{2c2,,email.utils.localtime()}.

@item 
bpo-36305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36305}: Fix handling of Windows filenames that resemble drives, such as
@code{./a:b}, in @ref{a3,,pathlib}.
@end itemize

@node Documentation<12>,Tests<15>,Library<17>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id136}@anchor{16d5}
@subsubsection Documentation



@itemize -

@item 
gh-103112@footnote{https://github.com/python/cpython/issues/103112}: Add docstring to @ref{16d6,,http.client.HTTPResponse.read()} to fix
@code{pydoc} output.
@end itemize

@node Tests<15>,Build<17>,Documentation<12>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id137}@anchor{16d7}
@subsubsection Tests



@itemize -

@item 
gh-102980@footnote{https://github.com/python/cpython/issues/102980}: Improve test coverage on @ref{a4,,pdb}.

@item 
gh-102537@footnote{https://github.com/python/cpython/issues/102537}: Adjust the error handling strategy in
@code{test_zoneinfo.TzPathTest.python_tzpath_context}. Patch by Paul Ganssle.

@item 
gh-101377@footnote{https://github.com/python/cpython/issues/101377}: Improved test_locale_calendar_formatweekday of calendar.
@end itemize

@node Build<17>,Windows<14>,Tests<15>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id138}@anchor{16d8}
@subsubsection Build



@itemize -

@item 
gh-102973@footnote{https://github.com/python/cpython/issues/102973}: Add a dev container (along with accompanying Dockerfile) for
development purposes.

@item 
gh-102711@footnote{https://github.com/python/cpython/issues/102711}: Fix @code{-Wstrict-prototypes} compiler warnings.
@end itemize

@node Windows<14>,Tools/Demos<9>,Build<17>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id139}@anchor{16d9}
@subsubsection Windows



@itemize -

@item 
gh-102690@footnote{https://github.com/python/cpython/issues/102690}: Update @ref{114,,webbrowser} to fall back to Microsoft Edge instead
of Internet Explorer.

@item 
gh-99726@footnote{https://github.com/python/cpython/issues/99726}: Improves correctness of stat results for Windows, and uses
faster API when available
@end itemize

@node Tools/Demos<9>,C API<17>,Windows<14>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id140}@anchor{16da}
@subsubsection Tools/Demos



@itemize -

@item 
gh-102809@footnote{https://github.com/python/cpython/issues/102809}: @code{Misc/gdbinit} was removed.
@end itemize

@node C API<17>,,Tools/Demos<9>,Python 3 12 0 alpha 7
@anchor{whatsnew/changelog id141}@anchor{16db}
@subsubsection C API



@itemize -

@item 
gh-102013@footnote{https://github.com/python/cpython/issues/102013}: Add a new (unstable) C-API function for iterating over GC'able
objects using a callback: @code{PyUnstable_VisitObjects}.
@end itemize

@node Python 3 12 0 alpha 6,Python 3 12 0 alpha 5,Python 3 12 0 alpha 7,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-6}@anchor{16dc}
@subsection Python 3.12.0 alpha 6


`Release date: 2023-03-07'

@menu
* Security: Security<12>. 
* Core and Builtins: Core and Builtins<19>. 
* Library: Library<18>. 
* Documentation: Documentation<13>. 
* Tests: Tests<16>. 
* Build: Build<18>. 
* Windows: Windows<15>. 
* macOS: macOS<11>. 
* C API: C API<18>. 

@end menu

@node Security<12>,Core and Builtins<19>,,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id142}@anchor{16dd}
@subsubsection Security



@itemize -

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Replace builtin hashlib implementations of MD5 and SHA1 with
verified ones from the HACL* project.

@item 
gh-101727@footnote{https://github.com/python/cpython/issues/101727}: Updated the OpenSSL version used in Windows and macOS binary
release builds to 1.1.1t to address 
@geindex Common Vulnerabilities and Exposures; CVE 2023-0286
CVE 2023-0286@footnote{https://www.cve.org/CVERecord?id=CVE-2023-0286}, 
@geindex Common Vulnerabilities and Exposures; CVE 2022-4303
CVE 2022-4303@footnote{https://www.cve.org/CVERecord?id=CVE-2022-4303},
and 
@geindex Common Vulnerabilities and Exposures; CVE 2022-4303
CVE 2022-4303@footnote{https://www.cve.org/CVERecord?id=CVE-2022-4303} per the OpenSSL 2023-02-07 security advisory@footnote{https://openssl-library.org/news/secadv/20230207.txt}.

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Replace the builtin @ref{67,,hashlib} implementations of SHA2-384
and SHA2-512 originally from LibTomCrypt with formally verified,
side-channel resistant code from the HACL*@footnote{https://github.com/hacl-star/hacl-star/} project. The builtins remain a
fallback only used when OpenSSL does not provide them.

@item 
gh-101283@footnote{https://github.com/python/cpython/issues/101283}: @ref{197,,subprocess.Popen} now uses a safer approach to find
@code{cmd.exe} when launching with @code{shell=True}. Patch by Eryk Sun, based
on a patch by Oleg Iarygin.
@end itemize

@node Core and Builtins<19>,Library<18>,Security<12>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id143}@anchor{16de}
@subsubsection Core and Builtins



@itemize -

@item 
gh-102493@footnote{https://github.com/python/cpython/issues/102493}: Fix regression in semantics of normalisation in
@code{PyErr_SetObject}.

@item 
gh-102416@footnote{https://github.com/python/cpython/issues/102416}: Do not memoize incorrectly automatically generated loop rules
in the parser. Patch by Pablo Galindo.

@item 
gh-102356@footnote{https://github.com/python/cpython/issues/102356}: Fix a bug that caused a crash when deallocating deeply nested
filter objects. Patch by Marta Gómez Macías.

@item 
gh-102336@footnote{https://github.com/python/cpython/issues/102336}: Cleanup Windows 7 specific special handling. Patch by Max
Bachmann.

@item 
gh-102250@footnote{https://github.com/python/cpython/issues/102250}: Fixed a segfault occurring when the interpreter calls a
@code{__bool__} method that raises.

@item 
gh-102126@footnote{https://github.com/python/cpython/issues/102126}: Fix deadlock at shutdown when clearing thread states if any
finalizer tries to acquire the runtime head lock. Patch by Kumar Aditya.

@item 
gh-102027@footnote{https://github.com/python/cpython/issues/102027}: Use @code{GetCurrentProcessId} on Windows when @code{getpid} is
unavailable. Patch by Max Bachmann.

@item 
gh-102056@footnote{https://github.com/python/cpython/issues/102056}: Fix error handling bugs in interpreter's exception printing
code, which could cause a crash on infinite recursion.

@item 
gh-100982@footnote{https://github.com/python/cpython/issues/100982}: Restrict the scope of the @code{FOR_ITER_RANGE} instruction
to the scope of the original @ref{16df,,FOR_ITER} instruction, to allow
instrumentation.

@item 
gh-101967@footnote{https://github.com/python/cpython/issues/101967}: Fix possible segfault in @code{positional_only_passed_as_keyword}
function, when new list created.

@item 
gh-101952@footnote{https://github.com/python/cpython/issues/101952}: Fix possible segfault in @code{BUILD_SET} opcode, when new set
created.

@item 
gh-74895@footnote{https://github.com/python/cpython/issues/74895}: @ref{16e0,,socket.getaddrinfo} no longer raises
@ref{86d,,OverflowError} for @ref{254,,int} `port' values outside of the C
long range. Out of range values are left up to the underlying string based
C library API to report. A @ref{16e1,,socket.gaierror} @code{SAI_SERVICE} may
occur instead, or no error at all as not all platform C libraries generate
an error.

@item 
gh-101799@footnote{https://github.com/python/cpython/issues/101799}: Add @ref{4cc,,CALL_INTRINSIC_2} and use it instead of
@code{PREP_RERAISE_STAR}.

@item 
gh-101857@footnote{https://github.com/python/cpython/issues/101857}: Fix xattr support detection on Linux systems by widening the
check to linux, not just glibc. This fixes support for musl.

@item 
gh-84783@footnote{https://github.com/python/cpython/issues/84783}: Make the slice object hashable. Patch by Will Bradshaw and
Furkan Onder.

@item 
gh-87849@footnote{https://github.com/python/cpython/issues/87849}: Change the @code{SEND} instruction to leave the receiver on the
stack. This allows the specialized form of @code{SEND} to skip the chain of C
calls and jump directly to the @code{RESUME} in the generator or coroutine.

@item 
gh-101765@footnote{https://github.com/python/cpython/issues/101765}: Fix SystemError / segmentation fault in iter @code{__reduce__}
when internal access of @code{builtins.__dict__} keys mutates the iter
object.

@item 
gh-101430@footnote{https://github.com/python/cpython/issues/101430}: Update @ref{fe,,tracemalloc} to handle presize of object properly.
Patch by Donghee Na.

@item 
gh-101696@footnote{https://github.com/python/cpython/issues/101696}: Invalidate type version tag in @code{_PyStaticType_Dealloc} for
static types, avoiding bug where a false cache hit could crash the
interpreter. Patch by Kumar Aditya.

@item 
gh-101632@footnote{https://github.com/python/cpython/issues/101632}: Adds a new @ref{4d3,,RETURN_CONST} instruction.

@item 
gh-100719@footnote{https://github.com/python/cpython/issues/100719}: Remove gi_code field from generator (and coroutine and async
generator) objects as it is redundant. The frame already includes a
reference to the code object.

@item 
gh-98627@footnote{https://github.com/python/cpython/issues/98627}: When an interpreter is configured to check (and only then),
importing an extension module will now fail when the extension does not
support multiple interpreters (i.e. doesn't implement PEP 489 multi-phase
init). This does not apply to the main interpreter, nor to subinterpreters
created with @code{Py_NewInterpreter()}.
@end itemize

@node Library<18>,Documentation<13>,Core and Builtins<19>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id144}@anchor{16e2}
@subsubsection Library



@itemize -

@item 
gh-102302@footnote{https://github.com/python/cpython/issues/102302}: Micro-optimise hashing of @ref{1cb,,inspect.Parameter}, reducing
the time it takes to hash an instance by around 40%.

@item 
gh-101979@footnote{https://github.com/python/cpython/issues/101979}: Fix a bug where parentheses in the @code{metavar} argument to
@ref{19c,,argparse.ArgumentParser.add_argument()} were dropped. Patch by Yeojin
Kim.

@item 
gh-91038@footnote{https://github.com/python/cpython/issues/91038}: @ref{16e3,,platform.platform()} now has boolean default arguments.

@item 
gh-81652@footnote{https://github.com/python/cpython/issues/81652}: Add @ref{16e4,,mmap.MAP_ALIGNED_SUPER} FreeBSD and
@ref{16e5,,mmap.MAP_CONCEAL} OpenBSD constants to @ref{8f,,mmap}. Patch by
Yeojin Kim.

@item 
gh-102179@footnote{https://github.com/python/cpython/issues/102179}: Fix @ref{b51,,os.dup2()} error message for negative fds.

@item 
gh-101961@footnote{https://github.com/python/cpython/issues/101961}: For the binary mode, @code{fileinput.hookcompressed()} doesn't
set the @code{encoding} value even if the value is @code{None}. Patch by Gihwan
Kim.

@item 
gh-101936@footnote{https://github.com/python/cpython/issues/101936}: The default value of @code{fp} becomes @ref{e8d,,io.BytesIO} if
@ref{fc9,,HTTPError} is initialized without a designated @code{fp}
parameter. Patch by Long Vo.

@item 
gh-101566@footnote{https://github.com/python/cpython/issues/101566}: In zipfile, sync Path with zipp 3.14@footnote{https://zipp.readthedocs.io/en/latest/history.html#v3-14-0}, including
fix for extractall on the underlying zipfile after being wrapped in
@code{Path}.

@item 
gh-97930@footnote{https://github.com/python/cpython/issues/97930}: Apply changes from importlib_resources 5.12@footnote{https://importlib-resources.readthedocs.io/en/latest/history.html#v5-12-0},
including fix for @code{MultiplexedPath} to support directories in multiple
namespaces (python/importlib_resources#265).

@item 
gh-101997@footnote{https://github.com/python/cpython/issues/101997}: Upgrade pip wheel bundled with ensurepip (pip 23.0.1)

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: The built-in extension modules for @ref{67,,hashlib} SHA2
algorithms, used when OpenSSL does not provide them, now live in a single
internal @code{_sha2} module instead of separate @code{_sha256} and @code{_sha512}
modules.

@item 
gh-101892@footnote{https://github.com/python/cpython/issues/101892}: Callable iterators no longer raise @ref{561,,SystemError} when
the callable object exhausts the iterator but forgets to either return a
sentinel value or raise @ref{be8,,StopIteration}.

@item 
gh-87634@footnote{https://github.com/python/cpython/issues/87634}: Remove locking behavior from @ref{52c,,functools.cached_property()}.

@item 
gh-97786@footnote{https://github.com/python/cpython/issues/97786}: Fix potential undefined behaviour in corner cases of
floating-point-to-time conversions.

@item 
gh-101517@footnote{https://github.com/python/cpython/issues/101517}: Fixed bug where @ref{f,,bdb} looks up the source line with
@ref{84,,linecache} with a @code{lineno=None}, which causes it to fail with an
unhandled exception.

@item 
gh-101773@footnote{https://github.com/python/cpython/issues/101773}: Optimize @ref{1e4,,fractions.Fraction} for small components. The
private argument @code{_normalize} of the @ref{1e4,,fractions.Fraction}
constructor has been removed.

@item 
gh-101693@footnote{https://github.com/python/cpython/issues/101693}: In @ref{2cf,,sqlite3.Cursor.execute()}, @ref{1a3,,DeprecationWarning} is
now emitted when @ref{2d1,,named placeholders} are used
together with parameters supplied as a @ref{4db,,sequence} instead of as a
@ref{253,,dict}. Starting from Python 3.14, using named placeholders with
parameters supplied as a sequence will raise a
@ref{4dc,,ProgrammingError}. Patch by Erlend E. Aasland.

@item 
gh-101446@footnote{https://github.com/python/cpython/issues/101446}: Change repr of @ref{5c5,,collections.OrderedDict} to use regular
dictionary formatting instead of pairs of keys and values.

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{490,,pathlib.PurePath} construction by handling
arguments more uniformly. When a @ref{226,,pathlib.Path} argument is
supplied, we use its string representation rather than joining its parts
with @ref{15bc,,os.path.join()}.

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{490,,pathlib.PurePath} construction by calling
@ref{15bc,,os.path.join()} only when two or more arguments are given.

@item 
gh-101362@footnote{https://github.com/python/cpython/issues/101362}: Speed up @ref{226,,pathlib.Path} construction by running the path
flavour compatibility check only when pathlib is imported.

@item 
gh-85984@footnote{https://github.com/python/cpython/issues/85984}: Refactored the implementation of @ref{16e6,,pty.fork()} to use
@ref{16e7,,os.login_tty()}.

A @ref{1a3,,DeprecationWarning} is now raised by @code{pty.master_open()} and
@code{pty.slave_open()}. They were undocumented and deprecated long long ago
in the docstring in favor of @ref{2cc,,pty.openpty()}.

@item 
gh-101561@footnote{https://github.com/python/cpython/issues/101561}: Add a new decorator @ref{434,,typing.override()}. See 
@geindex Python Enhancement Proposals; PEP 698
PEP 698@footnote{https://peps.python.org/pep-0698/} for
details. Patch by Steven Troxler.

@item 
gh-63301@footnote{https://github.com/python/cpython/issues/63301}: Set exit code when @ref{dc,,tabnanny} CLI exits on error.

@item 
gh-101360@footnote{https://github.com/python/cpython/issues/101360}: Fix anchor matching in @code{pathlib.PureWindowsPath.match()}.
Path and pattern anchors are now matched with @ref{5b,,fnmatch}, just like
other path parts. This allows patterns such as @code{"*:/Users/*"} to be
matched.

@item 
gh-101277@footnote{https://github.com/python/cpython/issues/101277}: Remove global state from @ref{80,,itertools} module (
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/}).
Patches by Erlend E. Aasland.

@item 
gh-100809@footnote{https://github.com/python/cpython/issues/100809}: Fix handling of drive-relative paths (like 'C:' and 'C:foo') in
@ref{1637,,pathlib.Path.absolute()}. This method now uses the OS API to retrieve
the correct current working directory for the drive.

@item 
gh-99138@footnote{https://github.com/python/cpython/issues/99138}: Apply 
@geindex Python Enhancement Proposals; PEP 687
PEP 687@footnote{https://peps.python.org/pep-0687/} to @ref{133,,zoneinfo}. Patch by Erlend E. Aasland.

@item 
gh-96764@footnote{https://github.com/python/cpython/issues/96764}: @ref{5ea,,asyncio.wait_for()} now uses @ref{5e9,,asyncio.timeout()} as its
underlying implementation. Patch by Kumar Aditya.

@item 
gh-88233@footnote{https://github.com/python/cpython/issues/88233}: Correctly preserve "extra" fields in @code{zipfile} regardless of
their ordering relative to a zip64 "extra."

@item 
bpo-23224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23224}: Fix segfaults when creating @ref{16e8,,lzma.LZMADecompressor} and
@ref{16e9,,bz2.BZ2Decompressor} objects without calling @code{__init__()}, and
fix leakage of locks and internal buffers when calling the @code{__init__()}
methods of @ref{16e8,,lzma.LZMADecompressor}, @ref{16ea,,lzma.LZMACompressor},
@ref{16eb,,bz2.BZ2Compressor}, and @ref{16e9,,bz2.BZ2Decompressor} objects
multiple times.
@end itemize

@node Documentation<13>,Tests<16>,Library<18>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id145}@anchor{16ec}
@subsubsection Documentation



@itemize -

@item 
gh-85417@footnote{https://github.com/python/cpython/issues/85417}: Update @ref{18,,cmath} documentation to clarify behaviour on branch
cuts.

@item 
gh-97725@footnote{https://github.com/python/cpython/issues/97725}: Fix @ref{16ed,,asyncio.Task.print_stack()} description for
@code{file=None}. Patch by Oleg Iarygin.
@end itemize

@node Tests<16>,Build<18>,Documentation<13>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id146}@anchor{16ee}
@subsubsection Tests



@itemize -

@item 
gh-102019@footnote{https://github.com/python/cpython/issues/102019}: Fix deadlock on shutdown if @code{test_current_@{exception,frames@}}
fails. Patch by Jacob Bower.

@item 
gh-85984@footnote{https://github.com/python/cpython/issues/85984}: Utilize new "winsize" functions from termios in pty tests.

@item 
gh-89792@footnote{https://github.com/python/cpython/issues/89792}: @code{test_tools} now copies up to 10x less source data to a
temporary directory during the @code{freeze} test by ignoring git metadata
and other artifacts.  It also limits its python build parallelism based on
os.cpu_count instead of hard coding it as 8 cores.
@end itemize

@node Build<18>,Windows<15>,Tests<16>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id147}@anchor{16ef}
@subsubsection Build



@itemize -

@item 
gh-99942@footnote{https://github.com/python/cpython/issues/99942}: On Android, in a static build, python-config in embed mode no
longer incorrectly reports a library to link to.

@item 
gh-99942@footnote{https://github.com/python/cpython/issues/99942}: On Android, python.pc now correctly reports the library to link
to, the same as python-config.sh.

@item 
gh-100221@footnote{https://github.com/python/cpython/issues/100221}: Fix creating install directories in @code{make sharedinstall} if
they exist outside @code{DESTDIR} already.

@item 
gh-96821@footnote{https://github.com/python/cpython/issues/96821}: Explicitly mark C extension modules that need defined signed
integer overflow, and add a configure option
@ref{16f0,,--with-strict-overflow}. Patch by Matthias Görgens and Shantanu
Jain.
@end itemize

@node Windows<15>,macOS<11>,Build<18>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id148}@anchor{16f1}
@subsubsection Windows



@itemize -

@item 
gh-102344@footnote{https://github.com/python/cpython/issues/102344}: Implement @code{winreg.QueryValue} using @code{QueryValueEx} and
@code{winreg.SetValue} using @code{SetValueEx}. Patch by Max Bachmann.

@item 
gh-101881@footnote{https://github.com/python/cpython/issues/101881}: Handle read and write operations on non-blocking pipes properly
on Windows.

@item 
gh-101881@footnote{https://github.com/python/cpython/issues/101881}: Add support for the os.get_blocking() and os.set_blocking()
functions on Windows.

@item 
gh-101849@footnote{https://github.com/python/cpython/issues/101849}: Ensures installer will correctly upgrade existing @code{py.exe}
launcher installs.

@item 
gh-101763@footnote{https://github.com/python/cpython/issues/101763}: Updates copy of libffi bundled with Windows installs to 3.4.4.

@item 
gh-101759@footnote{https://github.com/python/cpython/issues/101759}: Update Windows installer to SQLite 3.40.1.

@item 
gh-101614@footnote{https://github.com/python/cpython/issues/101614}: Correctly handle extensions built against debug binaries that
reference @code{python3_d.dll}.

@item 
gh-101196@footnote{https://github.com/python/cpython/issues/101196}: The functions @code{os.path.isdir}, @code{os.path.isfile},
@code{os.path.islink} and @code{os.path.exists} are now 13% to 28% faster on
Windows, by making fewer Win32 API calls.
@end itemize

@node macOS<11>,C API<18>,Windows<15>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id149}@anchor{16f2}
@subsubsection macOS



@itemize -

@item 
gh-101759@footnote{https://github.com/python/cpython/issues/101759}: Update macOS installer to SQLite 3.40.1.
@end itemize

@node C API<18>,,macOS<11>,Python 3 12 0 alpha 6
@anchor{whatsnew/changelog id150}@anchor{16f3}
@subsubsection C API



@itemize -

@item 
gh-101907@footnote{https://github.com/python/cpython/issues/101907}: Removes use of non-standard C++ extension in public header
files.

@item 
gh-99293@footnote{https://github.com/python/cpython/issues/99293}: Document that the Py_TPFLAGS_VALID_VERSION_TAG is an internal
feature, should not be used, and will be removed.

@item 
gh-101578@footnote{https://github.com/python/cpython/issues/101578}: Add @ref{3ea,,PyErr_GetRaisedException()} and
@ref{3ed,,PyErr_SetRaisedException()} for saving and restoring the current
exception. These functions return and accept a single exception object,
rather than the triple arguments of the now-deprecated
@ref{3e9,,PyErr_Fetch()} and @ref{3ec,,PyErr_Restore()}. This is less error
prone and a bit more efficient.

Add @ref{556,,PyException_GetArgs()} and @ref{557,,PyException_SetArgs()} as
convenience functions for retrieving and modifying the
@ref{558,,args} passed to the exception's constructor.

@item 
gh-91744@footnote{https://github.com/python/cpython/issues/91744}: Introduced the `Unstable C API tier', marking APi that is
allowed to change in minor releases without a deprecation period. See
@geindex Python Enhancement Proposals; PEP 689
PEP 689@footnote{https://peps.python.org/pep-0689/} for details.
@end itemize

@node Python 3 12 0 alpha 5,Python 3 12 0 alpha 4,Python 3 12 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-5}@anchor{16f4}
@subsection Python 3.12.0 alpha 5


`Release date: 2023-02-07'

@menu
* Security: Security<13>. 
* Core and Builtins: Core and Builtins<20>. 
* Library: Library<19>. 
* Documentation: Documentation<14>. 
* Tests: Tests<17>. 
* Build: Build<19>. 
* Windows: Windows<16>. 

@end menu

@node Security<13>,Core and Builtins<20>,,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id151}@anchor{16f5}
@subsubsection Security



@itemize -

@item 
gh-99108@footnote{https://github.com/python/cpython/issues/99108}: Replace the builtin @ref{67,,hashlib} implementations of SHA2-224
and SHA2-256 originally from LibTomCrypt with formally verified,
side-channel resistant code from the HACL*@footnote{https://github.com/hacl-star/hacl-star/} project. The builtins remain a
fallback only used when OpenSSL does not provide them.
@end itemize

@node Core and Builtins<20>,Library<19>,Security<13>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id153}@anchor{16f6}
@subsubsection Core and Builtins



@itemize -

@item 
gh-92173@footnote{https://github.com/python/cpython/issues/92173}: Fix the @code{defs} and @code{kwdefs} arguments to
@ref{16f7,,PyEval_EvalCodeEx()} and a reference leak in that function.

@item 
gh-59956@footnote{https://github.com/python/cpython/issues/59956}: The GILState API is now partially compatible with
subinterpreters. Previously, @code{PyThreadState_GET()} and
@code{PyGILState_GetThisThreadState()} would get out of sync, causing
inconsistent behavior and crashes.

@item 
gh-101400@footnote{https://github.com/python/cpython/issues/101400}: Fix wrong lineno in exception message on @ref{9b7,,continue} or
@ref{a97,,break} which are not in a loop. Patch by Donghee Na.

@item 
gh-101372@footnote{https://github.com/python/cpython/issues/101372}: Fix @ref{a37,,is_normalized()} to properly handle the
UCD 3.2.0 cases. Patch by Donghee Na.

@item 
gh-101266@footnote{https://github.com/python/cpython/issues/101266}: Fix @ref{16f8,,sys.getsizeof()} reporting for @ref{254,,int}
subclasses.

@item 
gh-101291@footnote{https://github.com/python/cpython/issues/101291}: Refactor the @code{PyLongObject} struct into a normal Python
object header and a @code{PyLongValue} struct.

@item 
gh-101046@footnote{https://github.com/python/cpython/issues/101046}: Fix a possible memory leak in the parser when raising
@ref{164b,,MemoryError}. Patch by Pablo Galindo

@item 
gh-101037@footnote{https://github.com/python/cpython/issues/101037}: Fix potential memory underallocation issue for instances of
@ref{254,,int} subclasses with value zero.

@item 
gh-100762@footnote{https://github.com/python/cpython/issues/100762}: Record the (virtual) exception block depth in the oparg of
@ref{309,,YIELD_VALUE}. Use this to avoid the expensive @code{throw()} when
closing generators (and coroutines) that can be closed trivially.

@item 
gh-100982@footnote{https://github.com/python/cpython/issues/100982}: Adds a new @code{COMPARE_AND_BRANCH} instruction. This is a
bit more efficient when performing a comparison immediately followed by a
branch, and restores the design intent of PEP 659 that specializations are
local to a single instruction.

@item 
gh-100942@footnote{https://github.com/python/cpython/issues/100942}: Fixed segfault in property.getter/setter/deleter that occurred
when a property subclass overrode the @code{__new__} method to return a
non-property instance.

@item 
gh-100923@footnote{https://github.com/python/cpython/issues/100923}: Remove the @code{mask} cache entry for the @ref{956,,COMPARE_OP}
instruction and embed the mask into the oparg.

@item 
gh-100892@footnote{https://github.com/python/cpython/issues/100892}: Fix race while iterating over thread states in clearing
@ref{16f9,,threading.local}. Patch by Kumar Aditya.

@item 
gh-91351@footnote{https://github.com/python/cpython/issues/91351}: Fix a case where re-entrant imports could corrupt the import
deadlock detection code and cause a @ref{33a,,KeyError} to be raised out of
@code{importlib/_bootstrap}.  In addition to the straightforward cases,
this could also happen when garbage collection leads to a warning being
emitted -- as happens when it collects an open socket or file)

@item 
gh-100726@footnote{https://github.com/python/cpython/issues/100726}: Optimize construction of @code{range} object for medium size
integers.

@item 
gh-100712@footnote{https://github.com/python/cpython/issues/100712}: Added option to build cpython with specialization disabled, by
setting @code{ENABLE_SPECIALIZATION=False} in @code{opcode}, followed by
@code{make regen-all}.

@item 
bpo-32780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32780}: Inter-field padding is now inserted into the PEP3118 format
strings obtained from @ref{1cf,,ctypes.Structure} objects, reflecting their
true representation in memory.
@end itemize

@node Library<19>,Documentation<14>,Core and Builtins<20>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id154}@anchor{16fa}
@subsubsection Library



@itemize -

@item 
gh-101541@footnote{https://github.com/python/cpython/issues/101541}: [Enum] - fix psuedo-flag creation

@item 
gh-101570@footnote{https://github.com/python/cpython/issues/101570}: Upgrade pip wheel bundled with ensurepip (pip 23.0)

@item 
gh-101323@footnote{https://github.com/python/cpython/issues/101323}: Fix a bug where errors where not thrown by
zlib._ZlibDecompressor if encountered during decompressing.

@item 
gh-101317@footnote{https://github.com/python/cpython/issues/101317}: Add `ssl_shutdown_timeout' parameter for
@ref{5ef,,asyncio.StreamWriter.start_tls()}.

@item 
gh-101326@footnote{https://github.com/python/cpython/issues/101326}: Fix regression when passing @code{None} as second or third
argument to @code{FutureIter.throw}.

@item 
gh-92123@footnote{https://github.com/python/cpython/issues/92123}: Adapt the @code{_elementtree} extension module to multi-phase init
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}). Patches by Erlend E. Aasland.

@item 
gh-100795@footnote{https://github.com/python/cpython/issues/100795}: Avoid potential unexpected @code{freeaddrinfo} call (double free)
in @ref{cb,,socket} when when a libc @code{getaddrinfo()} implementation leaves
garbage in an output pointer when returning an error. Original patch by
Sergey G. Brester.

@item 
gh-101143@footnote{https://github.com/python/cpython/issues/101143}: Remove unused references to @ref{16fb,,TimerHandle} in
@code{asyncio.base_events.BaseEventLoop._add_callback}.

@item 
gh-101144@footnote{https://github.com/python/cpython/issues/101144}: Make @ref{151f,,zipfile.Path.open()} and
@ref{16fc,,zipfile.Path.read_text()} also accept @code{encoding} as a positional
argument. This was the behavior in Python 3.9 and earlier.  3.10
introduced a regression where supplying it as a positional argument would
lead to a @ref{522,,TypeError}.

@item 
gh-94518@footnote{https://github.com/python/cpython/issues/94518}: Group-related variables of @code{_posixsubprocess} module are
renamed to stress that supplementary group affinity is added to a fork,
not replace the inherited ones. Patch by Oleg Iarygin.

@item 
gh-101015@footnote{https://github.com/python/cpython/issues/101015}: Fix @ref{69c,,typing.get_type_hints()} on @code{'*tuple[...]'} and
@code{*tuple[...]}. It must not drop the @code{Unpack} part.

@item 
gh-101000@footnote{https://github.com/python/cpython/issues/101000}: Add @ref{48e,,os.path.splitroot()}, which splits a path into a
3-item tuple @code{(drive, root, tail)}. This new function is used by
@ref{a3,,pathlib} to improve the performance of path construction by up to a
third.

@item 
gh-100573@footnote{https://github.com/python/cpython/issues/100573}: Fix a Windows @ref{a,,asyncio} bug with named pipes where a
client doing @code{os.stat()} on the pipe would cause an error in the server
that disabled serving future requests.

@item 
gh-39615@footnote{https://github.com/python/cpython/issues/39615}: @ref{14d0,,warnings.warn()} now has the ability to skip stack frames
based on code filename prefix rather than only a numeric @code{stacklevel}
via the new @code{skip_file_prefixes} keyword argument.

@item 
gh-100750@footnote{https://github.com/python/cpython/issues/100750}: pass encoding kwarg to subprocess in platform

@item 
gh-100160@footnote{https://github.com/python/cpython/issues/100160}: Emit a deprecation warning in
@code{asyncio.DefaultEventLoopPolicy.get_event_loop()} if there is no
current event loop set and it decides to create one.

@item 
gh-96290@footnote{https://github.com/python/cpython/issues/96290}: Fix handling of partial and invalid UNC drives in
@code{ntpath.splitdrive()}, and in @code{ntpath.normpath()} on non-Windows
systems. Paths such as '\server' and '\' are now considered by
@code{splitdrive()} to contain only a drive, and consequently are not
modified by @code{normpath()} on non-Windows systems. The behaviour of
@code{normpath()} on Windows systems is unaffected, as native OS APIs are
used. Patch by Eryk Sun, with contributions by Barney Gale.

@item 
gh-99952@footnote{https://github.com/python/cpython/issues/99952}: Fix a reference undercounting issue in @ref{1cf,,ctypes.Structure}
with @code{from_param()} results larger than a C pointer.

@item 
gh-67790@footnote{https://github.com/python/cpython/issues/67790}: Add float-style formatting support for
@ref{1e4,,fractions.Fraction} instances.

@item 
gh-99266@footnote{https://github.com/python/cpython/issues/99266}: Preserve more detailed error messages in @ref{2a,,ctypes}.

@item 
gh-86682@footnote{https://github.com/python/cpython/issues/86682}: Ensure runtime-created collections have the correct module name
using the newly added (internal) @ref{16fd,,sys._getframemodulename()}.

@item 
gh-88597@footnote{https://github.com/python/cpython/issues/88597}: @ref{10f,,uuid} now has a command line interface. Try @code{python -m
uuid -h}.

@item 
gh-60580@footnote{https://github.com/python/cpython/issues/60580}: @code{ctypes.wintypes.BYTE} definition changed from
@ref{16fe,,c_byte} to @ref{16ff,,c_ubyte} to match Windows SDK.
Patch by Anatoly Techtonik and Oleg Iarygin.

@item 
gh-94518@footnote{https://github.com/python/cpython/issues/94518}: @code{_posixsubprocess} now initializes all UID and GID variables
using a reserved @code{-1} value instead of a separate flag. Patch by Oleg
Iarygin.

@item 
bpo-38941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38941}: The @ref{124,,xml.etree.ElementTree} module now emits
@ref{1a3,,DeprecationWarning} when testing the truth value of an
@ref{305,,xml.etree.ElementTree.Element}. Before, the Python implementation
emitted @ref{40b,,FutureWarning}, and the C implementation emitted nothing.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{elementtree} types to heap types. Patch by Erlend
E. Aasland.

@item 
bpo-29847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29847}: Fix a bug where @ref{226,,pathlib.Path} accepted and ignored
keyword arguments. Patch provided by Yurii Karabas.

@item 
gh-77772@footnote{https://github.com/python/cpython/issues/77772}: @ref{9d7,,ctypes.CDLL}, @ref{1700,,ctypes.OleDLL},
@ref{1701,,ctypes.WinDLL}, and @ref{1702,,ctypes.PyDLL} now accept
@ref{29d,,path-like objects} as their @code{name} argument.
Patch by Robert Hoelzl.
@end itemize

@node Documentation<14>,Tests<17>,Library<19>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id155}@anchor{1703}
@subsubsection Documentation



@itemize -

@item 
gh-88324@footnote{https://github.com/python/cpython/issues/88324}: Reword @ref{d5,,subprocess} to emphasize default behavior of
`stdin', `stdout', and `stderr' arguments. Remove inaccurate statement
about child file handle inheritance.
@end itemize

@node Tests<17>,Build<19>,Documentation<14>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id156}@anchor{1704}
@subsubsection Tests



@itemize -

@item 
gh-101334@footnote{https://github.com/python/cpython/issues/101334}: @code{test_tarfile} has been updated to pass when run as a high
UID.
@end itemize

@node Build<19>,Windows<16>,Tests<17>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id157}@anchor{1705}
@subsubsection Build



@itemize -

@item 
gh-101282@footnote{https://github.com/python/cpython/issues/101282}: Update BOLT configuration not to use deprecated usage of
@code{--split functions}. Patch by Donghee Na.

@item 
gh-101522@footnote{https://github.com/python/cpython/issues/101522}: Allow overriding Windows dependencies versions and paths using
MSBuild properties.

@item 
gh-77532@footnote{https://github.com/python/cpython/issues/77532}: Minor fixes to allow building with @code{PlatformToolset=ClangCL}
on Windows.

@item 
gh-101152@footnote{https://github.com/python/cpython/issues/101152}: In accordance with 
@geindex Python Enhancement Proposals; PEP 699
PEP 699@footnote{https://peps.python.org/pep-0699/}, the @code{ma_version_tag} field in
@ref{3b8,,PyDictObject} is deprecated for extension modules. Accessing this
field will generate a compiler warning at compile time. This field will be
removed in Python 3.14.

@item 
gh-100340@footnote{https://github.com/python/cpython/issues/100340}: Allows -Wno-int-conversion for wasm-sdk 17 and onwards, thus
enables building WASI builds once against the latest sdk.

@item 
gh-101060@footnote{https://github.com/python/cpython/issues/101060}: Conditionally add @code{-fno-reorder-blocks-and-partition} in
configure. Effectively fixes @code{--enable-bolt} when using Clang, as this
appears to be a GCC-only flag.

@item 
gh-98705@footnote{https://github.com/python/cpython/issues/98705}: @code{__bool__} is defined in AIX system header files which breaks
the build in AIX, so undefine it.

@item 
gh-98636@footnote{https://github.com/python/cpython/issues/98636}: Fix a regression in detecting @code{gdbm_compat} library for the
@code{_gdbm} module build.

@item 
gh-96305@footnote{https://github.com/python/cpython/issues/96305}: @code{_aix_support} now uses a simple code to get platform details
rather than the now non-existent @code{_bootsubprocess} during bootstrap.
@end itemize

@node Windows<16>,,Build<19>,Python 3 12 0 alpha 5
@anchor{whatsnew/changelog id158}@anchor{1706}
@subsubsection Windows



@itemize -

@item 
gh-101543@footnote{https://github.com/python/cpython/issues/101543}: Ensure the install path in the registry is only used when the
standard library hasn't been located in any other way.

@item 
gh-101467@footnote{https://github.com/python/cpython/issues/101467}: The @code{py.exe} launcher now correctly filters when only a
single runtime is installed. It also correctly handles prefix matches on
tags so that @code{-3.1} does not match @code{3.11}, but would still match
@code{3.1-32}.

@item 
gh-99834@footnote{https://github.com/python/cpython/issues/99834}: Updates bundled copy of Tcl/Tk to 8.6.13.0

@item 
gh-101135@footnote{https://github.com/python/cpython/issues/101135}: Restore ability to launch older 32-bit versions from the
@code{py.exe} launcher when both 32-bit and 64-bit installs of the same
version are available.

@item 
gh-82052@footnote{https://github.com/python/cpython/issues/82052}: Fixed an issue where writing more than 32K of Unicode output to
the console screen in one go can result in mojibake.

@item 
gh-100320@footnote{https://github.com/python/cpython/issues/100320}: Ensures the @code{PythonPath} registry key from an install is used
when launching from a different copy of Python that relies on an existing
install to provide a copy of its modules and standard library.

@item 
gh-100247@footnote{https://github.com/python/cpython/issues/100247}: Restores support for the @code{py.exe} launcher finding
shebang commands in its configuration file using the full command name.
@end itemize

@node Python 3 12 0 alpha 4,Python 3 12 0 alpha 3,Python 3 12 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-4}@anchor{1707}
@subsection Python 3.12.0 alpha 4


`Release date: 2023-01-10'

@menu
* Core and Builtins: Core and Builtins<21>. 
* Library: Library<20>. 
* Documentation: Documentation<15>. 
* Tests: Tests<18>. 
* Build: Build<20>. 
* Windows: Windows<17>. 
* macOS: macOS<12>. 
* Tools/Demos: Tools/Demos<10>. 
* C API: C API<19>. 

@end menu

@node Core and Builtins<21>,Library<20>,,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id159}@anchor{1708}
@subsubsection Core and Builtins



@itemize -

@item 
gh-100776@footnote{https://github.com/python/cpython/issues/100776}: Fix misleading default value in @ref{12b6,,input()}'s
@code{__text_signature__}.

@item 
gh-99005@footnote{https://github.com/python/cpython/issues/99005}: Remove @code{UNARY_POSITIVE}, @code{ASYNC_GEN_WRAP} and
@code{LIST_TO_TUPLE}, replacing them with intrinsics.

@item 
gh-99005@footnote{https://github.com/python/cpython/issues/99005}: Add new @ref{4cb,,CALL_INTRINSIC_1} instruction. Remove
@code{IMPORT_STAR}, @code{PRINT_EXPR} and
@code{STOPITERATION_ERROR}, replacing them with the
@ref{4cb,,CALL_INTRINSIC_1} instruction.

@item 
gh-100288@footnote{https://github.com/python/cpython/issues/100288}: Remove the LOAD_ATTR_METHOD_WITH_DICT specialized instruction.
Stats show it is not useful.

@item 
gh-100720@footnote{https://github.com/python/cpython/issues/100720}: Added @code{_PyFrame_NumSlotsForCodeObject}, which returns the
number of slots needed in a frame for a given code object.

@item 
gh-100719@footnote{https://github.com/python/cpython/issues/100719}: Removed the co_nplaincellvars field from the code object, as it
is redundant.

@item 
gh-100637@footnote{https://github.com/python/cpython/issues/100637}: Fix @code{int.__sizeof__()} calculation to include the 1-element
@code{ob_digit} array for @code{0} and @code{False}.

@item 
gh-100649@footnote{https://github.com/python/cpython/issues/100649}: Update the native_thread_id field of PyThreadState after fork.

@item 
gh-100126@footnote{https://github.com/python/cpython/issues/100126}: Fix an issue where "incomplete" frames could be briefly visible
to C code while other frames are being torn down, possibly resulting in
corruption or hard crashes of the interpreter while running finalizers.

@item 
gh-87447@footnote{https://github.com/python/cpython/issues/87447}: Fix @ref{18b,,SyntaxError} on comprehension rebind checking with
names that are not actually redefined.

Now reassigning @code{b} in @code{[(b := 1) for a, b.prop in some_iter]} is
allowed. Reassigning @code{a} is still disallowed as per 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}.

@item 
gh-100268@footnote{https://github.com/python/cpython/issues/100268}: Add @ref{1709,,int.is_integer()} to improve duck type compatibility
between @ref{254,,int} and @ref{2eb,,float}.

@item 
gh-100425@footnote{https://github.com/python/cpython/issues/100425}: Improve the accuracy of @code{sum()} with compensated summation.

@item 
gh-100374@footnote{https://github.com/python/cpython/issues/100374}: Fix incorrect result and delay in @ref{170a,,socket.getfqdn()}. Patch
by Dominic Socular.

@item 
gh-100357@footnote{https://github.com/python/cpython/issues/100357}: Convert @code{vars}, @code{dir}, @code{next}, @code{getattr}, and @code{iter}
to argument clinic.

@item 
gh-100117@footnote{https://github.com/python/cpython/issues/100117}: Improve the output of @ref{2ef,,codeobject.co_lines()} by emitting
only one entry for each line range.

@item 
gh-90043@footnote{https://github.com/python/cpython/issues/90043}: Handle NaNs when specializing @ref{956,,COMPARE_OP} for
@ref{2eb,,float} values.

@item 
gh-100222@footnote{https://github.com/python/cpython/issues/100222}: Redefine the @code{_Py_CODEUNIT} typedef as a union to describe
its layout to the C compiler, avoiding type punning and improving clarity.

@item 
gh-99955@footnote{https://github.com/python/cpython/issues/99955}: Internal compiler functions (in compile.c) now consistently
return -1 on error and 0 on success.

@item 
gh-100188@footnote{https://github.com/python/cpython/issues/100188}: The @code{BINARY_SUBSCR_LIST_INT} and @code{BINARY_SUBSCR_TUPLE_INT}
instructions are no longer used for negative integers because those
instructions always miss when encountering negative integers.

@item 
gh-99110@footnote{https://github.com/python/cpython/issues/99110}: Initialize frame->previous in frameobject.c to fix a
segmentation fault when accessing frames created by @code{PyFrame_New()}.

@item 
gh-94155@footnote{https://github.com/python/cpython/issues/94155}: Improved the hashing algorithm for code objects, mitigating some
hash collisions.

@item 
gh-99540@footnote{https://github.com/python/cpython/issues/99540}: @code{None} now hashes to a constant value. This is not a
requirements change.

@item 
gh-100143@footnote{https://github.com/python/cpython/issues/100143}: When built with @code{--enable-pystats}, stats collection is now
off by default. To enable it early at startup, pass the @code{-Xpystats}
flag.  Stats are now always dumped, even if switched off.

@item 
gh-100146@footnote{https://github.com/python/cpython/issues/100146}: Improve @code{BUILD_LIST} opcode so that it works similarly to the
@code{BUILD_TUPLE} opcode, by stealing references from the stack rather than
repeatedly using stack operations to set list elements.  Implementation
details are in a new private API @code{_PyList_FromArraySteal()}.

@item 
gh-100110@footnote{https://github.com/python/cpython/issues/100110}: Specialize @code{FOR_ITER} for tuples.

@item 
gh-100050@footnote{https://github.com/python/cpython/issues/100050}: Honor existing errors obtained when searching for mismatching
parentheses in the tokenizer. Patch by Pablo Galindo

@item 
gh-92216@footnote{https://github.com/python/cpython/issues/92216}: Improve the performance of @ref{4bb,,hasattr()} for type objects with
a missing attribute.

@item 
gh-99582@footnote{https://github.com/python/cpython/issues/99582}: Freeze @ref{131,,zipimport} module into @code{_bootstrap_python}.

@item 
gh-99554@footnote{https://github.com/python/cpython/issues/99554}: Pack debugging location tables more efficiently during bytecode
compilation.

@item 
gh-98522@footnote{https://github.com/python/cpython/issues/98522}: Add an internal version number to code objects, to give better
versioning of inner functions and comprehensions, and thus better
specialization of those functions. This change is invisible to both Python
and C extensions.

@item 
gh-94603@footnote{https://github.com/python/cpython/issues/94603}: Improve performance of @code{list.pop} for small lists.

@item 
gh-89051@footnote{https://github.com/python/cpython/issues/89051}: Add @ref{170b,,ssl.OP_LEGACY_SERVER_CONNECT}

@item 
bpo-32782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32782}: @code{ctypes} arrays of length 0 now report a correct itemsize
when a @code{memoryview} is constructed from them, rather than always giving
a value of 0.
@end itemize

@node Library<20>,Documentation<15>,Core and Builtins<21>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id160}@anchor{170c}
@subsubsection Library



@itemize -

@item 
gh-100833@footnote{https://github.com/python/cpython/issues/100833}: Speed up @ref{138b,,math.fsum()} by removing defensive @code{volatile}
qualifiers.

@item 
gh-100805@footnote{https://github.com/python/cpython/issues/100805}: Modify @ref{120e,,random.choice()} implementation to once again work
with NumPy arrays.

@item 
gh-100813@footnote{https://github.com/python/cpython/issues/100813}: Add @code{socket.IP_PKTINFO} constant.

@item 
gh-100792@footnote{https://github.com/python/cpython/issues/100792}: Make @ref{170d,,email.message.Message.__contains__()} twice as fast.

@item 
gh-91851@footnote{https://github.com/python/cpython/issues/91851}: Microoptimizations for @ref{170e,,fractions.Fraction.__round__()},
@ref{170f,,fractions.Fraction.__ceil__()} and
@ref{1710,,fractions.Fraction.__floor__()}.

@item 
gh-90104@footnote{https://github.com/python/cpython/issues/90104}: Avoid RecursionError on @code{repr} if a dataclass field definition
has a cyclic reference.

@item 
gh-100689@footnote{https://github.com/python/cpython/issues/100689}: Fix crash in @code{pyexpat} by statically allocating
@code{PyExpat_CAPI} capsule.

@item 
gh-100740@footnote{https://github.com/python/cpython/issues/100740}: Fix @code{unittest.mock.Mock} not respecting the spec for
attribute names prefixed with @code{assert}.

@item 
gh-91219@footnote{https://github.com/python/cpython/issues/91219}: Change @code{SimpleHTTPRequestHandler} to support subclassing to
provide a different set of index file names instead of using @code{__init__}
parameters.

@item 
gh-100690@footnote{https://github.com/python/cpython/issues/100690}: @code{Mock} objects which are not unsafe will now raise an
@code{AttributeError} when accessing an attribute that matches the name of an
assertion but without the prefix @code{assert_}, e.g. accessing
@code{called_once} instead of @code{assert_called_once}. This is in addition to
this already happening for accessing attributes with prefixes @code{assert},
@code{assret}, @code{asert}, @code{aseert}, and @code{assrt}.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Simplify and optimize @ref{493,,os.walk()} by using
@ref{42b,,isinstance()} checks to check the top of the stack.

@item 
gh-100485@footnote{https://github.com/python/cpython/issues/100485}: Add math.sumprod() to compute the sum of products.

@item 
gh-86508@footnote{https://github.com/python/cpython/issues/86508}: Fix @ref{b06,,asyncio.open_connection()} to skip binding to local
addresses of different family. Patch by Kumar Aditya.

@item 
gh-97930@footnote{https://github.com/python/cpython/issues/97930}: @code{importlib.resources.files} now accepts a module as an anchor
instead of only accepting packages. If a module is passed, resources are
resolved adjacent to that module (in the same package or at the package
root). The parameter was renamed from @code{package} to @code{anchor} with a
compatibility shim for those passing by keyword. Additionally, the new
@code{anchor} parameter is now optional and will default to the caller's
module.

@item 
gh-100585@footnote{https://github.com/python/cpython/issues/100585}: Fixed a bug where importlib.resources.as_file was leaving file
pointers open

@item 
gh-100562@footnote{https://github.com/python/cpython/issues/100562}: Improve performance of @ref{1637,,pathlib.Path.absolute()} by nearly
2x. This comes at the cost of a performance regression in
@ref{16b5,,pathlib.Path.cwd()}, which is generally used less frequently in user
code.

@item 
gh-100519@footnote{https://github.com/python/cpython/issues/100519}: Small simplification of @code{http.cookiejar.eff_request_host()}
that improves readability and better matches the RFC wording.

@item 
gh-100287@footnote{https://github.com/python/cpython/issues/100287}: Fix the interaction of @ref{b8f,,unittest.mock.seal()} with
@ref{a39,,unittest.mock.AsyncMock}.

@item 
gh-100488@footnote{https://github.com/python/cpython/issues/100488}: Add @code{Fraction.is_integer()} to check whether a
@ref{1e4,,fractions.Fraction} is an integer. This improves duck type
compatibility with @ref{2eb,,float} and @ref{254,,int}.

@item 
gh-100474@footnote{https://github.com/python/cpython/issues/100474}: @ref{71,,http.server} now checks that an index page is actually a
regular file before trying to serve it.  This avoids issues with
directories named @code{index.html}.

@item 
gh-100363@footnote{https://github.com/python/cpython/issues/100363}: Speed up @ref{af9,,asyncio.get_running_loop()} by removing redundant
@code{getpid} checks. Patch by Kumar Aditya.

@item 
gh-78878@footnote{https://github.com/python/cpython/issues/78878}: Fix crash when creating an instance of @code{_ctypes.CField}.

@item 
gh-100348@footnote{https://github.com/python/cpython/issues/100348}: Fix ref cycle in @code{asyncio._SelectorSocketTransport} by
removing @code{_read_ready_cb} in @code{close}.

@item 
gh-100344@footnote{https://github.com/python/cpython/issues/100344}: Provide C implementation for @ref{467,,asyncio.current_task()} for a
4x-6x speedup.

@item 
gh-100272@footnote{https://github.com/python/cpython/issues/100272}: Fix JSON serialization of OrderedDict.  It now preserves the
order of keys.

@item 
gh-83076@footnote{https://github.com/python/cpython/issues/83076}: Instantiation of @code{Mock()} and @code{AsyncMock()} is now 3.8x
faster.

@item 
gh-100234@footnote{https://github.com/python/cpython/issues/100234}: Set a default value of 1.0 for the @code{lambd} parameter in
random.expovariate().

@item 
gh-100228@footnote{https://github.com/python/cpython/issues/100228}: A @ref{1a3,,DeprecationWarning} may be raised when @ref{195,,os.fork()}
or @ref{196,,os.forkpty()} is called from multi-threaded processes.  Forking
with threads is unsafe and can cause deadlocks, crashes and subtle
problems. Lack of a warning does not indicate that the fork call was
actually safe, as Python may not be aware of all threads.

@item 
gh-100039@footnote{https://github.com/python/cpython/issues/100039}: Improve signatures for enums and flags.

@item 
gh-100133@footnote{https://github.com/python/cpython/issues/100133}: Fix regression in @ref{a,,asyncio} where a subprocess would
sometimes lose data received from pipe.

@item 
bpo-44592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44592}: Fixes inconsistent handling of case sensitivity of
`extrasaction' arg in @ref{11db,,csv.DictWriter}.

@item 
gh-100098@footnote{https://github.com/python/cpython/issues/100098}: Fix @code{tuple} subclasses being cast to @code{tuple} when used as
enum values.

@item 
gh-85432@footnote{https://github.com/python/cpython/issues/85432}: Rename the `fmt' parameter of the pure-Python implementation of
@ref{1711,,datetime.time.strftime()} to `format'. Rename the `t' parameter of
@ref{4d7,,datetime.datetime.fromtimestamp()} to `timestamp'. These changes mean
the parameter names in the pure-Python implementation now match the
parameter names in the C implementation. Patch by Alex Waygood.

@item 
gh-98778@footnote{https://github.com/python/cpython/issues/98778}: Update @ref{fc9,,HTTPError} to be initialized
properly, even if the @code{fp} is @code{None}. Patch by Donghee Na.

@item 
gh-99925@footnote{https://github.com/python/cpython/issues/99925}: Unify error messages in JSON serialization between
@code{json.dumps(float('nan'), allow_nan=False)} and
@code{json.dumps(float('nan'), allow_nan=False, indent=<SOMETHING>)}. Now
both include the representation of the value that could not be serialized.

@item 
gh-89727@footnote{https://github.com/python/cpython/issues/89727}: Fix issue with @ref{493,,os.walk()} where a @ref{d59,,RecursionError}
would occur on deep directory structures by adjusting the implementation
of @ref{493,,os.walk()} to be iterative instead of recursive.

@item 
gh-94943@footnote{https://github.com/python/cpython/issues/94943}: Add @ref{1712,,Dataclass support} to the @ref{61b,,Enum}
@ref{1713,,__repr__()}. When inheriting from a
@ref{1c6,,dataclass}, only show the field names in the value
section of the member @ref{7e7,,repr()}, and not the dataclass' class name.

@item 
gh-83035@footnote{https://github.com/python/cpython/issues/83035}: Fix @ref{154d,,inspect.getsource()} handling of decorator calls with
nested parentheses.

@item 
gh-99576@footnote{https://github.com/python/cpython/issues/99576}: Fix @code{.save()} method for @code{LWPCookieJar} and
@code{MozillaCookieJar}: saved file was not truncated on repeated save.

@item 
gh-94912@footnote{https://github.com/python/cpython/issues/94912}: Add @ref{47a,,inspect.markcoroutinefunction()} decorator which
manually marks a function as a coroutine for the benefit of
@code{iscoroutinefunction()}.

@item 
gh-99509@footnote{https://github.com/python/cpython/issues/99509}: Add 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} support for
@code{multiprocessing.queues.Queue}.

@item 
gh-99482@footnote{https://github.com/python/cpython/issues/99482}: Remove @code{Jython} partial compatibility code from several stdlib
modules.

@item 
gh-99433@footnote{https://github.com/python/cpython/issues/99433}: Fix @ref{3a,,doctest} failure on @ref{636,,types.MethodWrapperType}
in modules.

@item 
gh-85267@footnote{https://github.com/python/cpython/issues/85267}: Several improvements to @ref{722,,inspect.signature()}'s handling of
@code{__text_signature}. - Fixes a case where @ref{722,,inspect.signature()}
dropped parameters - Fixes a case where @ref{722,,inspect.signature()} raised
@ref{52d,,tokenize.TokenError} - Allows @ref{722,,inspect.signature()} to
understand defaults involving binary operations of constants -
@ref{722,,inspect.signature()} is documented as only raising @ref{522,,TypeError}
or @ref{1ff,,ValueError}, but sometimes raised @ref{193,,RuntimeError}. These
cases now raise @ref{1ff,,ValueError} - Removed a dead code path

@item 
gh-91166@footnote{https://github.com/python/cpython/issues/91166}: @ref{a,,asyncio} is optimized to avoid excessive copying when
writing to socket and use @ref{460,,sendmsg()} if the platform
supports it. Patch by Kumar Aditya.

@item 
gh-98030@footnote{https://github.com/python/cpython/issues/98030}: Add missing TCP socket options from Linux: @code{TCP_MD5SIG},
@code{TCP_THIN_LINEAR_TIMEOUTS}, @code{TCP_THIN_DUPACK}, @code{TCP_REPAIR},
@code{TCP_REPAIR_QUEUE}, @code{TCP_QUEUE_SEQ}, @code{TCP_REPAIR_OPTIONS},
@code{TCP_TIMESTAMP}, @code{TCP_CC_INFO}, @code{TCP_SAVE_SYN}, @code{TCP_SAVED_SYN},
@code{TCP_REPAIR_WINDOW}, @code{TCP_FASTOPEN_CONNECT}, @code{TCP_ULP},
@code{TCP_MD5SIG_EXT}, @code{TCP_FASTOPEN_KEY}, @code{TCP_FASTOPEN_NO_COOKIE},
@code{TCP_ZEROCOPY_RECEIVE}, @code{TCP_INQ}, @code{TCP_TX_DELAY}.

@item 
gh-88500@footnote{https://github.com/python/cpython/issues/88500}: Reduced the memory usage of @ref{1714,,urllib.parse.unquote()} and
@ref{1715,,urllib.parse.unquote_to_bytes()} on large values.

@item 
gh-96127@footnote{https://github.com/python/cpython/issues/96127}: @code{inspect.signature} was raising @code{TypeError} on call with
mock objects. Now it correctly returns @code{(*args, **kwargs)} as inferred
signature.

@item 
gh-95882@footnote{https://github.com/python/cpython/issues/95882}: Fix a 3.11 regression in
@ref{b18,,asynccontextmanager()}, which caused it to propagate
exceptions with incorrect tracebacks and fix a 3.11 regression in
@ref{11df,,contextmanager()}, which caused it to propagate
exceptions with incorrect tracebacks for @ref{be8,,StopIteration}.

@item 
gh-78707@footnote{https://github.com/python/cpython/issues/78707}: Deprecate passing more than one positional argument to
@ref{2c8,,pathlib.PurePath.relative_to()} and
@ref{2c7,,is_relative_to()}.

@item 
gh-92122@footnote{https://github.com/python/cpython/issues/92122}: Fix reStructuredText syntax errors in docstrings in the
@ref{55,,enum} module.

@item 
gh-91851@footnote{https://github.com/python/cpython/issues/91851}: Optimize the @ref{1e4,,Fraction} arithmetics for small
components.

@item 
bpo-24132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24132}: Make @ref{490,,pathlib.PurePath} and @ref{226,,Path}
subclassable (private to start). Previously, attempting to instantiate a
subclass resulted in an @ref{343,,AttributeError} being raised. Patch by
Barney Gale.

@item 
bpo-40447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40447}: Accept @ref{c3f,,os.PathLike} (such as @ref{226,,pathlib.Path}) in
the @code{stripdir} arguments of @ref{dce,,compileall.compile_file()} and
@ref{b14,,compileall.compile_dir()}.

@item 
bpo-36880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36880}: Fix a reference counting issue when a @ref{2a,,ctypes} callback
with return type @ref{13ee,,py_object} returns @code{None}, which could
cause crashes.
@end itemize

@node Documentation<15>,Tests<18>,Library<20>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id161}@anchor{1716}
@subsubsection Documentation



@itemize -

@item 
gh-100616@footnote{https://github.com/python/cpython/issues/100616}: Document existing @code{attr} parameter to
@ref{1717,,curses.window.vline()} function in @ref{2b,,curses}.

@item 
gh-100472@footnote{https://github.com/python/cpython/issues/100472}: Remove claim in documentation that the @code{stripdir},
@code{prependdir} and @code{limit_sl_dest} parameters of
@ref{b14,,compileall.compile_dir()} and @ref{dce,,compileall.compile_file()} could
be @ref{1bd,,bytes}.

@item 
bpo-25377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25377}: Clarify use of octal format of mode argument in help(os.chmod)
as well as help(os.fchmod)
@end itemize

@node Tests<18>,Build<20>,Documentation<15>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id162}@anchor{1718}
@subsubsection Tests



@itemize -

@item 
gh-100454@footnote{https://github.com/python/cpython/issues/100454}: Start running SSL tests with OpenSSL 3.1.0-beta1.

@item 
gh-100086@footnote{https://github.com/python/cpython/issues/100086}: The Python test runner (libregrtest) now logs Python build
information like "debug" vs "release" build, or LTO and PGO optimizations.
Patch by Victor Stinner.

@item 
gh-93018@footnote{https://github.com/python/cpython/issues/93018}: Make two tests forgiving towards host system libexpat with
backported security fixes applied.
@end itemize

@node Build<20>,Windows<17>,Tests<18>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id163}@anchor{1719}
@subsubsection Build



@itemize -

@item 
gh-100540@footnote{https://github.com/python/cpython/issues/100540}: Removed the @code{--with-system-ffi} @code{configure} option;
@code{libffi} must now always be supplied by the system on all non-Windows
platforms.  The option has had no effect on non-Darwin platforms for
several releases, and in 3.11 only had the non-obvious effect of invoking
@code{pkg-config} to find @code{libffi} and never setting
@code{-DUSING_APPLE_OS_LIBFFI}.  Now on Darwin platforms @code{configure} will
first check for the OS @code{libffi} and then fall back to the same
processing as other platforms if it is not found.

@item 
gh-88267@footnote{https://github.com/python/cpython/issues/88267}: Avoid exporting Python symbols in linked Windows applications
when the core is built as static.

@item 
bpo-41916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41916}: Allow override of ac_cv_cxx_thread so that cross compiled
python can set -pthread for CXX.
@end itemize

@node Windows<17>,macOS<12>,Build<20>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id164}@anchor{171a}
@subsubsection Windows



@itemize -

@item 
gh-100180@footnote{https://github.com/python/cpython/issues/100180}: Update Windows installer to OpenSSL 1.1.1s

@item 
gh-99191@footnote{https://github.com/python/cpython/issues/99191}: Use @code{_MSVC_LANG >= 202002L} instead of less-precise @code{_MSC_VER
>=1929} to more accurately test for C++20 support in
@code{PC/_wmimodule.cpp}.

@item 
gh-79218@footnote{https://github.com/python/cpython/issues/79218}: Define @code{MS_WIN64} for Mingw-w64 64bit, fix cython compilation
failure.

@item 
gh-99941@footnote{https://github.com/python/cpython/issues/99941}: Ensure that @ref{171b,,asyncio.Protocol.data_received()} receives an
immutable @ref{1bd,,bytes} object (as documented), instead of
@ref{528,,bytearray}.

@item 
bpo-43984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43984}: @ref{171c,,winreg.SetValueEx()} now leaves the target value untouched
in the case of conversion errors. Previously, @code{-1} would be written in
case of such errors.

@item 
bpo-34816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34816}: @code{hasattr(ctypes.windll, 'nonexistant')} now returns @code{False}
instead of raising @ref{40d,,OSError}.
@end itemize

@node macOS<12>,Tools/Demos<10>,Windows<17>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id165}@anchor{171d}
@subsubsection macOS



@itemize -

@item 
gh-100180@footnote{https://github.com/python/cpython/issues/100180}: Update macOS installer to OpenSSL 1.1.1s

@item 
gh-100540@footnote{https://github.com/python/cpython/issues/100540}: Removed obsolete @code{dlfcn.h} shim from the @code{_ctypes}
extension module, which has not been necessary since Mac OS X 10.2.
@end itemize

@node Tools/Demos<10>,C API<19>,macOS<12>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id166}@anchor{171e}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-45256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45256}: Fix a bug that caused an @ref{343,,AttributeError} to be raised in
@code{python-gdb.py} when @code{py-locals} is used without a frame.

@item 
gh-100342@footnote{https://github.com/python/cpython/issues/100342}: Add missing @code{NULL} check for possible allocation failure in
@code{*args} parsing in Argument Clinic.
@end itemize

@node C API<19>,,Tools/Demos<10>,Python 3 12 0 alpha 4
@anchor{whatsnew/changelog id167}@anchor{171f}
@subsubsection C API



@itemize -

@item 
gh-99947@footnote{https://github.com/python/cpython/issues/99947}: Raising SystemError on import will now have its cause be set to
the original unexpected exception.

@item 
gh-99240@footnote{https://github.com/python/cpython/issues/99240}: In argument parsing, after deallocating newly allocated memory,
reset its pointer to NULL.

@item 
gh-98724@footnote{https://github.com/python/cpython/issues/98724}: The @ref{564,,Py_CLEAR}, @ref{565,,Py_SETREF} and
@ref{566,,Py_XSETREF} macros now only evaluate their arguments once. If an
argument has side effects, these side effects are no longer duplicated.
Patch by Victor Stinner.
@end itemize

@node Python 3 12 0 alpha 3,Python 3 12 0 alpha 2,Python 3 12 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-3}@anchor{1720}
@subsection Python 3.12.0 alpha 3


`Release date: 2022-12-06'

@menu
* Security: Security<14>. 
* Core and Builtins: Core and Builtins<22>. 
* Library: Library<21>. 
* Documentation: Documentation<16>. 
* Tests: Tests<19>. 
* Build: Build<21>. 
* Windows: Windows<18>. 
* macOS: macOS<13>. 
* Tools/Demos: Tools/Demos<11>. 
* C API: C API<20>. 

@end menu

@node Security<14>,Core and Builtins<22>,,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id168}@anchor{1721}
@subsubsection Security



@itemize -

@item 
gh-100001@footnote{https://github.com/python/cpython/issues/100001}: @code{python -m http.server} no longer allows terminal control
characters sent within a garbage request to be printed to the stderr
server log.

This is done by changing the @ref{71,,http.server}
@code{BaseHTTPRequestHandler} @code{.log_message} method to replace control
characters with a @code{\x@var{HH}} hex escape before printing.

@item 
gh-87604@footnote{https://github.com/python/cpython/issues/87604}: Avoid publishing list of active per-interpreter audit hooks via
the @ref{5f,,gc} module
@end itemize

@node Core and Builtins<22>,Library<21>,Security<14>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id169}@anchor{1722}
@subsubsection Core and Builtins



@itemize -

@item 
gh-99891@footnote{https://github.com/python/cpython/issues/99891}: Fix a bug in the tokenizer that could cause infinite recursion
when showing syntax warnings that happen in the first line of the source.
Patch by Pablo Galindo

@item 
gh-91054@footnote{https://github.com/python/cpython/issues/91054}: Add @ref{552,,PyCode_AddWatcher()} and
@ref{553,,PyCode_ClearWatcher()} APIs to register callbacks to receive
notification on creation and destruction of code objects.

@item 
gh-99729@footnote{https://github.com/python/cpython/issues/99729}: Fix an issue that could cause frames to be visible to Python
code as they are being torn down, possibly leading to memory corruption or
hard crashes of the interpreter.

@item 
gh-99708@footnote{https://github.com/python/cpython/issues/99708}: Fix bug where compiler crashes on an if expression with an empty
body block.

@item 
gh-99578@footnote{https://github.com/python/cpython/issues/99578}: Fix a reference bug in @code{_imp.create_builtin()} after the
creation of the first sub-interpreter for modules @code{builtins} and
@code{sys}. Patch by Victor Stinner.

@item 
gh-99581@footnote{https://github.com/python/cpython/issues/99581}: Fixed a bug that was causing a buffer overflow if the tokenizer
copies a line missing the newline character from a file that is as long as
the available tokenizer buffer. Patch by Pablo galindo

@item 
gh-99553@footnote{https://github.com/python/cpython/issues/99553}: Fix bug where an @ref{1b4,,ExceptionGroup} subclass can wrap a
@ref{5a5,,BaseException}.

@item 
gh-99547@footnote{https://github.com/python/cpython/issues/99547}: Add a function to os.path to check if a path is a junction:
isjunction. Add similar functionality to pathlib.Path as is_junction.

@item 
gh-99370@footnote{https://github.com/python/cpython/issues/99370}: Fix zip path for venv created from a non-installed python on
POSIX platforms.

@item 
gh-99377@footnote{https://github.com/python/cpython/issues/99377}: Add audit events for thread creation and clear operations.

@item 
gh-98686@footnote{https://github.com/python/cpython/issues/98686}: Remove the @code{BINARY_OP_GENERIC} and @code{COMPARE_OP_GENERIC}
"specializations".

@item 
gh-99298@footnote{https://github.com/python/cpython/issues/99298}: Remove the remaining error paths for attribute specializations,
and refuse to specialize attribute accesses on types that haven't had
@ref{766,,PyType_Ready()} called on them yet.

@item 
gh-99127@footnote{https://github.com/python/cpython/issues/99127}: Allow some features of @ref{db,,syslog} to the main interpreter
only. Patch by Donghee Na.

@item 
gh-91053@footnote{https://github.com/python/cpython/issues/91053}: Optimizing interpreters and JIT compilers may need to invalidate
internal metadata when functions are modified. This change adds the
ability to provide a callback that will be invoked each time a function is
created, modified, or destroyed.

@item 
gh-90994@footnote{https://github.com/python/cpython/issues/90994}: Improve error messages when there's a syntax error with call
arguments. The following three cases are covered: - No value is assigned
to a named argument, eg @code{foo(a=)}. - A value is assigned to a star
argument, eg @code{foo(*args=[0])}. - A value is assigned to a double-star
keyword argument, eg @code{foo(**kwarg=@{'a': 0@})}.

@item 
bpo-45026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45026}: Optimize the @ref{930,,range} object iterator. It is now smaller,
faster iteration of ranges containing large numbers. Smaller pickles,
faster unpickling.

@item 
bpo-31718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31718}: Raise @ref{1ff,,ValueError} instead of @ref{561,,SystemError} when
methods of uninitialized @ref{1652,,io.IncrementalNewlineDecoder} objects are
called. Patch by Oren Milman.

@item 
bpo-38031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38031}: Fix a possible assertion failure in @ref{12ee,,io.FileIO} when the
opener returns an invalid file descriptor.
@end itemize

@node Library<21>,Documentation<16>,Core and Builtins<22>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id170}@anchor{1723}
@subsubsection Library



@itemize -

@item 
gh-100001@footnote{https://github.com/python/cpython/issues/100001}: Also escape s in the http.server
BaseHTTPRequestHandler.log_message so that it is technically possible to
parse the line and reconstruct what the original data was.  Without this a
xHH is ambiguous as to if it is a hex replacement we put in or the
characters r"x" came through in the original request line.

@item 
gh-99957@footnote{https://github.com/python/cpython/issues/99957}: Add @code{frozen_default} parameter to
@ref{4bd,,typing.dataclass_transform()}.

@item 
gh-79033@footnote{https://github.com/python/cpython/issues/79033}: Fix @ref{1653,,asyncio.Server.wait_closed()} to actually do what the
docs promise -- wait for all existing connections to complete, after
closing the server.

@item 
gh-51524@footnote{https://github.com/python/cpython/issues/51524}: Fix bug when calling trace.CoverageResults with valid infile.

@item 
gh-99645@footnote{https://github.com/python/cpython/issues/99645}: Fix a bug in handling class cleanups in
@ref{437,,unittest.TestCase}.  Now @code{addClassCleanup()} uses separate lists
for different @code{TestCase} subclasses, and @code{doClassCleanups()} only
cleans up the particular class.

@item 
gh-99508@footnote{https://github.com/python/cpython/issues/99508}: Fix @code{TypeError} in @code{Lib/importlib/_bootstrap_external.py}
while calling @code{_imp.source_hash()}.

@item 
gh-66285@footnote{https://github.com/python/cpython/issues/66285}: Fix @ref{a,,asyncio} to not share event loop and signal wakeupfd
in forked processes. Patch by Kumar Aditya.

@item 
gh-97001@footnote{https://github.com/python/cpython/issues/97001}: Release the GIL when calling termios APIs to avoid blocking
threads.

@item 
gh-92647@footnote{https://github.com/python/cpython/issues/92647}: Use final status of an enum to determine lookup or creation
branch of functional API.

@item 
gh-99388@footnote{https://github.com/python/cpython/issues/99388}: Add `loop_factory' parameter to @ref{466,,asyncio.run()} to allow
specifying a custom event loop factory. Patch by Kumar Aditya.

@item 
gh-99341@footnote{https://github.com/python/cpython/issues/99341}: Fix @ref{1724,,ast.increment_lineno()} to also cover
@code{ast.TypeIgnore} when changing line numbers.

@item 
gh-99382@footnote{https://github.com/python/cpython/issues/99382}: Check the number of arguments in substitution in user generics
containing a @ref{15e,,TypeVarTuple} and one or more
@ref{15c,,TypeVar}.

@item 
gh-99379@footnote{https://github.com/python/cpython/issues/99379}: Fix substitution of @ref{15d,,ParamSpec} followed by
@ref{15e,,TypeVarTuple} in generic aliases.

@item 
gh-99344@footnote{https://github.com/python/cpython/issues/99344}: Fix substitution of @ref{15e,,TypeVarTuple} and
@ref{15d,,ParamSpec} together in user generics.

@item 
gh-99284@footnote{https://github.com/python/cpython/issues/99284}: Remove @code{_use_broken_old_ctypes_structure_semantics_} old
untested and undocumented hack from @ref{2a,,ctypes}.

@item 
gh-99201@footnote{https://github.com/python/cpython/issues/99201}: Fix @ref{14eb,,IndexError} when initializing the config variables on
Windows if @code{HAVE_DYNAMIC_LOADING} is not set.

@item 
gh-99240@footnote{https://github.com/python/cpython/issues/99240}: Fix double-free bug in Argument Clinic @code{str_converter} by
extracting memory clean up to a new @code{post_parsing} section.

@item 
gh-64490@footnote{https://github.com/python/cpython/issues/64490}: Fix refcount error when arguments are packed to tuple in
Argument Clinic.

@item 
gh-99029@footnote{https://github.com/python/cpython/issues/99029}: @ref{2c8,,pathlib.PurePath.relative_to()} now treats naked Windows
drive paths as relative. This brings its behaviour in line with other
parts of pathlib.

@item 
gh-98253@footnote{https://github.com/python/cpython/issues/98253}: The implementation of the typing module is now more resilient to
reference leaks in binary extension modules.

Previously, a reference leak in a typed C API-based extension module could
leak internals of the typing module, which could in turn introduce leaks
in essentially any other package with typed function signatures. Although
the typing package is not the original source of the problem, such
non-local dependences exacerbate debugging of large-scale projects, and
the implementation was therefore changed to reduce harm by providing
better isolation.

@item 
gh-98458@footnote{https://github.com/python/cpython/issues/98458}: Fix infinite loop in unittest when a self-referencing chained
exception is raised

@item 
gh-93453@footnote{https://github.com/python/cpython/issues/93453}: @ref{2bf,,asyncio.get_event_loop()} and many other @ref{a,,asyncio}
functions like @ref{c64,,asyncio.ensure_future()}, @ref{a5e,,asyncio.shield()} or
@ref{5e8,,asyncio.gather()}, and also the
@code{get_event_loop()} method of
@code{asyncio.BaseDefaultEventLoopPolicy} now raise a
@ref{193,,RuntimeError} if called when there is no running event loop and the
current event loop was not set. Previously they implicitly created and set
a new current event loop. @ref{1a3,,DeprecationWarning} is no longer emitted
if there is no running event loop but the current event loop was set.

@item 
gh-97966@footnote{https://github.com/python/cpython/issues/97966}: On @code{uname_result}, restored expectation that @code{_fields} and
@code{_asdict} would include all six properties including @code{processor}.

@item 
gh-98248@footnote{https://github.com/python/cpython/issues/98248}: Provide informative error messages in @ref{1255,,struct.pack()} when
its integral arguments are not in range.

@item 
gh-98108@footnote{https://github.com/python/cpython/issues/98108}: @code{zipfile.Path} is now pickleable if its initialization
parameters were pickleable (e.g. for file system paths).

@item 
gh-98098@footnote{https://github.com/python/cpython/issues/98098}: Created packages from zipfile and test_zipfile modules,
separating @code{zipfile.Path} functionality.

@item 
gh-82836@footnote{https://github.com/python/cpython/issues/82836}: Fix @ref{15d2,,is_private} properties in the
@ref{7f,,ipaddress} module. Previously non-private networks (0.0.0.0/0) would
return @code{True} from this method; now they correctly return @code{False}.

@item 
gh-96828@footnote{https://github.com/python/cpython/issues/96828}: Add an @ref{1725,,OP_ENABLE_KTLS} option for enabling the use
of the kernel TLS (kTLS). Patch by Illia Volochii.

@item 
gh-88863@footnote{https://github.com/python/cpython/issues/88863}: To avoid apparent memory leaks when
@ref{b06,,asyncio.open_connection()} raises, break reference cycles generated
by local exception and future instances (which has exception instance as
its member var). Patch by Dong Uk, Kang.

@item 
gh-91078@footnote{https://github.com/python/cpython/issues/91078}: @code{TarFile.next()} now returns @code{None} when called on an
empty tarfile.

@item 
bpo-47220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47220}: Document the optional `callback' parameter of
@code{WeakMethod}. Patch by Géry Ogam.

@item 
bpo-44817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44817}: Ignore WinError 53 (ERROR_BAD_NETPATH), 65
(ERROR_NETWORK_ACCESS_DENIED) and 161 (ERROR_BAD_PATHNAME) when using
ntpath.realpath().

@item 
bpo-41260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41260}: Rename the `fmt' parameter of the pure Python implementation of
@ref{c7f,,datetime.date.strftime()} to `format'.

@item 
bpo-15999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15999}: All built-in functions now accept arguments of any type instead
of just @code{bool} and @code{int} for boolean parameters.
@end itemize

@node Documentation<16>,Tests<19>,Library<21>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id171}@anchor{1726}
@subsubsection Documentation



@itemize -

@item 
gh-99931@footnote{https://github.com/python/cpython/issues/99931}: Use sphinxext-opengraph@footnote{https://sphinxext-opengraph.readthedocs.io/} to generate OpenGraph metadata@footnote{https://ogp.me/}.

@item 
gh-89682@footnote{https://github.com/python/cpython/issues/89682}: Reworded docstring of the default @code{__contains__} to clarify
that it returns a @ref{451,,bool}.

@item 
gh-88330@footnote{https://github.com/python/cpython/issues/88330}: Improved the description of what a resource is in
importlib.resources docs.

@item 
gh-92892@footnote{https://github.com/python/cpython/issues/92892}: Document that calling variadic functions with ctypes requires
special care on macOS/arm64 (and possibly other platforms).

@item 
bpo-41825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41825}: Restructured the documentation for the @ref{d85,,os.wait*} family of functions, and improved the docs for
@ref{d86,,os.waitid()} with more explanation of the possible argument
constants.
@end itemize

@node Tests<19>,Build<21>,Documentation<16>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id172}@anchor{1727}
@subsubsection Tests



@itemize -

@item 
gh-99892@footnote{https://github.com/python/cpython/issues/99892}: Skip test_normalization() of test_unicodedata if it fails to
download NormalizationTest.txt file from pythontest.net. Patch by Victor
Stinner.

@item 
gh-99934@footnote{https://github.com/python/cpython/issues/99934}: Correct test_marsh on (32 bit) x86: test_deterministic sets was
failing.

@item 
gh-99741@footnote{https://github.com/python/cpython/issues/99741}: We've implemented multi-phase init (PEP 489/630/687) for the
internal (for testing) _xxsubinterpreters module.

@item 
gh-99659@footnote{https://github.com/python/cpython/issues/99659}: Optional big memory tests in @code{test_sqlite3} now catch the
correct @code{sqlite.DataError} exception type in case of too large
strings and/or blobs passed.

@item 
gh-99593@footnote{https://github.com/python/cpython/issues/99593}: Cover the Unicode C API with tests.

@item 
gh-96002@footnote{https://github.com/python/cpython/issues/96002}: Add functional test for Argument Clinic.
@end itemize

@node Build<21>,Windows<18>,Tests<19>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id173}@anchor{1728}
@subsubsection Build



@itemize -

@item 
gh-99086@footnote{https://github.com/python/cpython/issues/99086}: Fix @code{-Wimplicit-int}, @code{-Wstrict-prototypes}, and
@code{-Wimplicit-function-declaration} compiler warnings in
@code{configure} checks.

@item 
gh-99337@footnote{https://github.com/python/cpython/issues/99337}: Fix a compilation issue with GCC 12 on macOS.

@item 
gh-99289@footnote{https://github.com/python/cpython/issues/99289}: Add a @code{COMPILEALL_OPTS} variable in Makefile to override
@ref{20,,compileall} options (default: @code{-j0}) in @code{make install}. Also
merged the @code{compileall} commands into a single command building .pyc
files for the all optimization levels (0, 1, 2) at once. Patch by Victor
Stinner.

@item 
gh-98872@footnote{https://github.com/python/cpython/issues/98872}: Fix a possible fd leak in @code{Programs/_freeze_module.c}
introduced in Python 3.11.

@item 
gh-88226@footnote{https://github.com/python/cpython/issues/88226}: Always define @code{TARGET_*} labels in @code{Python/ceval.c}, even if
@code{USE_COMPUTED_GOTOS} is disabled.  This allows breakpoints to be set at
those labels in (for instance) @code{gdb}.
@end itemize

@node Windows<18>,macOS<13>,Build<21>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id174}@anchor{1729}
@subsubsection Windows



@itemize -

@item 
gh-99345@footnote{https://github.com/python/cpython/issues/99345}: Use faster initialization functions to detect install location
for Windows Store package

@item 
gh-98629@footnote{https://github.com/python/cpython/issues/98629}: Fix initialization of @ref{177,,sys.version} and @code{sys._git} on
Windows

@item 
gh-99442@footnote{https://github.com/python/cpython/issues/99442}: Fix handling in @ref{5a8,,Lanceur Python pour Windows} when @code{argv[0]} does not
include a file extension.

@item 
bpo-40882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40882}: Fix a memory leak in
@ref{15e2,,multiprocessing.shared_memory.SharedMemory} on Windows.
@end itemize

@node macOS<13>,Tools/Demos<11>,Windows<18>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id175}@anchor{172a}
@subsubsection macOS



@itemize -

@item 
gh-87235@footnote{https://github.com/python/cpython/issues/87235}: On macOS @code{python3 /dev/fd/9 9</path/to/script.py} failed for
any script longer than a couple of bytes.

@item 
gh-98940@footnote{https://github.com/python/cpython/issues/98940}: Fix @code{Mac/Extras.install.py} file filter bug.
@end itemize

@node Tools/Demos<11>,C API<20>,macOS<13>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id176}@anchor{172b}
@subsubsection Tools/Demos



@itemize -

@item 
gh-64490@footnote{https://github.com/python/cpython/issues/64490}: Argument Clinic varargs bugfixes


@itemize *

@item 
Fix out-of-bounds error in @code{_PyArg_UnpackKeywordsWithVararg()}.

@item 
Fix incorrect check which allowed more than one varargs in clinic.py.

@item 
Fix miscalculation of @code{noptargs} in generated code.

@item 
Do not generate @code{noptargs} when there is a vararg argument and no optional argument.
@end itemize
@end itemize

@node C API<20>,,Tools/Demos<11>,Python 3 12 0 alpha 3
@anchor{whatsnew/changelog id177}@anchor{172c}
@subsubsection C API



@itemize -

@item 
gh-98680@footnote{https://github.com/python/cpython/issues/98680}: @code{PyBUF_*} constants were marked as part of Limited API of
Python 3.11+. These were available in 3.11.0 with
@ref{414,,Py_LIMITED_API} defined for 3.11, and are necessary to use the
buffer API.

@item 
gh-99612@footnote{https://github.com/python/cpython/issues/99612}: Fix @ref{172d,,PyUnicode_DecodeUTF8Stateful()} for ASCII-only data:
@code{*consumed} was not set.

@item 
gh-47146@footnote{https://github.com/python/cpython/issues/47146}: The @code{structmember.h} header is deprecated. Its non-deprecated
contents are now available just by including @code{Python.h}, with a @code{Py_}
prefix added if it was missing. (Deprecated contents are
@ref{57f,,T_OBJECT}, @ref{581,,T_NONE}, and no-op flags.) Patch by Petr
Viktorin, based on earlier work by Alexander Belopolsky and Matthias
Braun.
@end itemize

@node Python 3 12 0 alpha 2,Python 3 12 0 alpha 1,Python 3 12 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-2}@anchor{172e}
@subsection Python 3.12.0 alpha 2


`Release date: 2022-11-14'

@menu
* Security: Security<15>. 
* Core and Builtins: Core and Builtins<23>. 
* Library: Library<22>. 
* Documentation: Documentation<17>. 
* Tests: Tests<20>. 
* Build: Build<22>. 
* Windows: Windows<19>. 
* macOS: macOS<14>. 
* C API: C API<21>. 

@end menu

@node Security<15>,Core and Builtins<23>,,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id178}@anchor{172f}
@subsubsection Security



@itemize -

@item 
gh-98433@footnote{https://github.com/python/cpython/issues/98433}: The IDNA codec decoder used on DNS hostnames by @ref{cb,,socket} or
@ref{a,,asyncio} related name resolution functions no longer involves a
quadratic algorithm. This prevents a potential CPU denial of service if an
out-of-spec excessive length hostname involving bidirectional characters
were decoded. Some protocols such as @ref{107,,urllib} http @code{3@var{xx}}
redirects potentially allow for an attacker to supply such a name.

Individual labels within an IDNA encoded DNS name will now raise an error
early during IDNA decoding if they are longer than 1024 unicode characters
given that each decoded DNS label must be 63 or fewer characters and the
entire decoded DNS name is limited to 255. Only an application presenting
a hostname or label consisting primarily of 
@geindex RFC; RFC 3454
RFC 3454@footnote{https://datatracker.ietf.org/doc/html/rfc3454.html} section 3.1
"Nothing" characters to be removed would run into of this new limit. See
also 
@geindex RFC; RFC 5894
RFC 5894@footnote{https://datatracker.ietf.org/doc/html/rfc5894.html} section 6 and 
@geindex RFC; RFC 3491
RFC 3491@footnote{https://datatracker.ietf.org/doc/html/rfc3491.html}.

@item 
gh-98739@footnote{https://github.com/python/cpython/issues/98739}: Update bundled libexpat to 2.5.0
@end itemize

@node Core and Builtins<23>,Library<22>,Security<15>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id179}@anchor{1730}
@subsubsection Core and Builtins



@itemize -

@item 
gh-81057@footnote{https://github.com/python/cpython/issues/81057}: The docs clearly say that @code{PyImport_Inittab},
@ref{1731,,PyImport_AppendInittab()}, and @ref{1732,,PyImport_ExtendInittab()}
should not be used after @ref{899,,Py_Initialize()} has been called. We now
enforce this for the two functions.  Additionally, the runtime now uses an
internal copy of @code{PyImport_Inittab}, to guard against modification.

@item 
gh-99298@footnote{https://github.com/python/cpython/issues/99298}: Fix an issue that could potentially cause incorrect error
handling for some bytecode instructions.

@item 
gh-99254@footnote{https://github.com/python/cpython/issues/99254}: The compiler now removes all unused constants from code objects
(except the first one, which may be a docstring).

@item 
gh-99205@footnote{https://github.com/python/cpython/issues/99205}: Fix an issue that prevented @ref{777,,PyThreadState} and
@ref{8aa,,PyInterpreterState} memory from being freed properly.

@item 
gh-81057@footnote{https://github.com/python/cpython/issues/81057}: The 18 global C variables holding the state of the allocators
have been moved to @code{_PyRuntimeState}.  This is a strictly internal
change with no change in behavior.

@item 
gh-99181@footnote{https://github.com/python/cpython/issues/99181}: Fix failure in @ref{5a2,,except*} with unhashable
exceptions.

@item 
gh-99204@footnote{https://github.com/python/cpython/issues/99204}: Fix calculation of @code{sys._base_executable} when inside a
POSIX virtual environment using copies of the python binary when the base
installation does not provide the executable name used by the venv.
Calculation will fall back to alternative names ("python<MAJOR>",
"python<MAJOR>.<MINOR>").

@item 
gh-96055@footnote{https://github.com/python/cpython/issues/96055}: Update @ref{57,,faulthandler} to emit an error message with the
proper unexpected signal number. Patch by Donghee Na.

@item 
gh-99153@footnote{https://github.com/python/cpython/issues/99153}: Fix location of @ref{18b,,SyntaxError} for a @ref{6d3,,try} block
with both @ref{189,,except} and @ref{5a2,,except*}.

@item 
gh-98686@footnote{https://github.com/python/cpython/issues/98686}: Merge the adaptive opcode logic into each instruction's
unquickened variant, and merge the logic in @code{EXTENDED_ARG_QUICK} into
@ref{1733,,EXTENDED_ARG}. With these changes, the quickening that happens at
code object creation is now only responsible for initializing warmup
counters and inserting superinstructions.

@item 
gh-99103@footnote{https://github.com/python/cpython/issues/99103}: Fix the error reporting positions of specialized traceback
anchors when the source line contains Unicode characters.

@item 
gh-99139@footnote{https://github.com/python/cpython/issues/99139}: Improve the error suggestion for @ref{428,,NameError} exceptions for
instances. Now if a @ref{428,,NameError} is raised in a method and the
instance has an attribute that's exactly equal to the name in the
exception, the suggestion will include @code{self.<NAME>} instead of the
closest match in the method scope. Patch by Pablo Galindo

@item 
gh-98401@footnote{https://github.com/python/cpython/issues/98401}: Octal escapes with value larger than @code{0o377} (ex: @code{"\477"}),
deprecated in Python 3.11, now produce a @ref{44f,,SyntaxWarning}, instead of
@ref{1a3,,DeprecationWarning}. In a future Python version they will be
eventually a @ref{18b,,SyntaxError}. Patch by Victor Stinner.

@item 
gh-98401@footnote{https://github.com/python/cpython/issues/98401}: A backslash-character pair that is not a valid escape sequence
now generates a @ref{44f,,SyntaxWarning}, instead of
@ref{1a3,,DeprecationWarning}.  For example, @code{re.compile("\d+\.\d+")} now
emits a @ref{44f,,SyntaxWarning} (@code{"\d"} is an invalid escape sequence), use
raw strings for regular expression: @code{re.compile(r"\d+\.\d+")}. In a
future Python version, @ref{18b,,SyntaxError} will eventually be raised,
instead of @ref{44f,,SyntaxWarning}. Patch by Victor Stinner.

@item 
gh-96793@footnote{https://github.com/python/cpython/issues/96793}: Handle StopIteration and StopAsyncIteration raised in generator
or coroutines in the bytecode, rather than in wrapping C code.

@item 
gh-98931@footnote{https://github.com/python/cpython/issues/98931}: Improve the @ref{18b,,SyntaxError} error message when the user types
@code{import x from y} instead of @code{from y import x}. Patch by Pablo Galindo

@item 
gh-98852@footnote{https://github.com/python/cpython/issues/98852}: Fix subscription of type aliases containing bare generic types
or types like @ref{15c,,TypeVar}: for example @code{tuple[A, T][int]}
and @code{tuple[TypeVar, T][int]}, where @code{A} is a generic type, and @code{T}
is a type variable.

@item 
gh-98925@footnote{https://github.com/python/cpython/issues/98925}: Lower the recursion depth for marshal on WASI to support
(in-development) wasmtime 2.0.

@item 
gh-98783@footnote{https://github.com/python/cpython/issues/98783}: Fix multiple crashes in debug mode when @code{str} subclasses are
used instead of @code{str} itself.

@item 
gh-98811@footnote{https://github.com/python/cpython/issues/98811}: Use complete source locations to simplify detection of
@code{__future__} imports which are not at the beginning of the file. Also
corrects the offset in the exception raised in one case, which was off by
one and impeded highlighting.

@item 
gh-96793@footnote{https://github.com/python/cpython/issues/96793}: Add specialization of @ref{16df,,FOR_ITER} for generators. Saves
multiple layers of dispatch and checking to get from the
@ref{16df,,FOR_ITER} instruction in the caller to the @ref{30a,,RESUME} in
the generator.

@item 
gh-98762@footnote{https://github.com/python/cpython/issues/98762}: Fix source locations of @ref{7f7,,match} sub-patterns.

@item 
gh-98586@footnote{https://github.com/python/cpython/issues/98586}: Added the methods @ref{547,,PyObject_Vectorcall()} and
@ref{548,,PyObject_VectorcallMethod()} to the @ref{53e,,Limited API}
along with the auxiliary macro constant
@ref{549,,PY_VECTORCALL_ARGUMENTS_OFFSET}.

The availability of these functions enables more efficient 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
vector calls from binary extension modules that avoid argument
boxing/unboxing overheads.

@item 
gh-99257@footnote{https://github.com/python/cpython/issues/99257}: Fix an issue where member descriptors (such as those for
@ref{14a0,,__slots__}) could behave incorrectly or crash instead of
raising a @ref{522,,TypeError} when accessed via an instance of an invalid
type.

@item 
gh-93143@footnote{https://github.com/python/cpython/issues/93143}: Rather than changing @code{co_code}, the
interpreter will now display a @ref{1bb,,RuntimeWarning} and assign
@ref{660,,None} to any fast locals that are left unbound after jumps or
@ref{1734,,del} statements executed while tracing.

@item 
gh-96421@footnote{https://github.com/python/cpython/issues/96421}: When calling into Python code from C code, through
@ref{1017,,PyEval_EvalFrameEx()} or a related C-API function, a shim frame in
inserted into the call stack. This occurs in the
@code{_PyEval_EvalFrameDefault()} function. The extra frame should be
invisible to all Python and most C extensions, but out-of-process
profilers and debuggers need to be aware of it. These shim frames can be
detected by checking @code{frame->owner == FRAME_OWNED_BY_CSTACK}.

Extensions implementing their own interpreters using PEP 523 need to be
aware of this shim frame and the changes to the semantics of
@ref{1735,,RETURN_VALUE}, @ref{309,,YIELD_VALUE}, and
@ref{6e6,,RETURN_GENERATOR}, which now clear the frame.

@item 
gh-98415@footnote{https://github.com/python/cpython/issues/98415}: Fix detection of MAC addresses for @ref{10f,,uuid} on certain OSs.
Patch by Chaim Sanders

@item 
gh-98686@footnote{https://github.com/python/cpython/issues/98686}: Quicken all code objects, and specialize adaptive bytecode
instructions more aggressively.

@item 
gh-92119@footnote{https://github.com/python/cpython/issues/92119}: Print exception class name instead of its string representation
when raising errors from @ref{2a,,ctypes} calls.

@item 
gh-91058@footnote{https://github.com/python/cpython/issues/91058}: @ref{40f,,ImportError} raised from failed @code{from <module> import
<name>} now include suggestions for the value of @code{<name>} based on the
available names in @code{<module>}. Patch by Pablo Galindo

@item 
gh-96793@footnote{https://github.com/python/cpython/issues/96793}: The @ref{16df,,FOR_ITER} now leaves the iterator on the stack on
termination of the loop. This is to assist specialization of loops for
generators.

@item 
gh-90716@footnote{https://github.com/python/cpython/issues/90716}: Add _pylong.py module.  It includes asymptotically faster
algorithms that can be used for operations on integers with many digits.
It is used by longobject.c to speed up some operations.

@item 
gh-95389@footnote{https://github.com/python/cpython/issues/95389}: Expose @ref{1736,,ETH_P_ALL} and some of the
@ref{1737,,ETHERTYPE_* constants} in @ref{cb,,socket}.
Patch by Noam Cohen.

@item 
gh-93696@footnote{https://github.com/python/cpython/issues/93696}: Allow @ref{a4,,pdb} to locate source for frozen modules in the
standard library.
@end itemize

@node Library<22>,Documentation<17>,Core and Builtins<23>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id180}@anchor{1738}
@subsubsection Library



@itemize -

@item 
gh-99418@footnote{https://github.com/python/cpython/issues/99418}: Fix bug in @ref{302,,urllib.parse.urlparse()} that causes URL schemes
that begin with a digit, a plus sign, or a minus sign to be parsed
incorrectly.

@item 
gh-94597@footnote{https://github.com/python/cpython/issues/94597}: Deprecate @ref{2b9,,asyncio.AbstractChildWatcher} to be removed in
Python 3.14. Patch by Kumar Aditya.

@item 
gh-99305@footnote{https://github.com/python/cpython/issues/99305}: Improve performance of @ref{1739,,secrets.token_hex()}.

@item 
gh-74044@footnote{https://github.com/python/cpython/issues/74044}: Fixed bug where @ref{722,,inspect.signature()} reported incorrect
arguments for decorated methods.

@item 
gh-99275@footnote{https://github.com/python/cpython/issues/99275}: Fix @code{SystemError} in @ref{2a,,ctypes} when exception was not set
during @code{__initsubclass__}.

@item 
gh-99277@footnote{https://github.com/python/cpython/issues/99277}: Remove older version of
@code{_SSLProtocolTransport.get_write_buffer_limits} in
@code{asyncio.sslproto}

@item 
gh-99248@footnote{https://github.com/python/cpython/issues/99248}: fix negative numbers failing in verify()

@item 
gh-99155@footnote{https://github.com/python/cpython/issues/99155}: Fix @ref{a26,,statistics.NormalDist} pickle with @code{0} and @code{1}
protocols.

@item 
gh-93464@footnote{https://github.com/python/cpython/issues/93464}: @code{enum.auto()} is now correctly activated when combined with
other assignment values.  E.g. @code{ONE = auto(), 'some text'} will now
evaluate as @code{(1, 'some text')}.

@item 
gh-99134@footnote{https://github.com/python/cpython/issues/99134}: Update the bundled copy of pip to version 22.3.1.

@item 
gh-92584@footnote{https://github.com/python/cpython/issues/92584}: Remove the @code{distutils} package. It was deprecated in Python
3.10 by 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/} "Deprecate distutils module". For projects still using
@code{distutils} and cannot be updated to something else, the @code{setuptools}
project can be installed: it still provides @code{distutils}. Patch by Victor
Stinner.

@item 
gh-98999@footnote{https://github.com/python/cpython/issues/98999}: Now @code{_pyio} is consistent with @code{_io} in raising
@code{ValueError} when executing methods over closed buffers.

@item 
gh-83004@footnote{https://github.com/python/cpython/issues/83004}: Clean up refleak on failed module initialisation in
@code{_zoneinfo}

@item 
gh-83004@footnote{https://github.com/python/cpython/issues/83004}: Clean up refleaks on failed module initialisation in
@code{_pickle}

@item 
gh-83004@footnote{https://github.com/python/cpython/issues/83004}: Clean up refleak on failed module initialisation in @code{_io}.

@item 
gh-98897@footnote{https://github.com/python/cpython/issues/98897}: Fix memory leak in @ref{9f0,,math.dist()} when both points don't have
the same dimension. Patch by Kumar Aditya.

@item 
gh-98878@footnote{https://github.com/python/cpython/issues/98878}: Use the frame bound builtins when offering a name suggestion in
@ref{fd,,traceback} to prevent crashing when @code{__builtins__} is not a dict.

@item 
gh-98139@footnote{https://github.com/python/cpython/issues/98139}: In @code{importlib._bootstrap}, enhance namespace package repr
to @code{<module 'x' (namespace) from ['path']>}.

@item 
gh-90352@footnote{https://github.com/python/cpython/issues/90352}: Fix @code{_SelectorDatagramTransport} to inherit from
@ref{173a,,DatagramTransport} in @ref{a,,asyncio}. Patch by Kumar
Aditya.

@item 
gh-98793@footnote{https://github.com/python/cpython/issues/98793}: Fix argument typechecks in @code{_overlapped.WSAConnect()} and
@code{_overlapped.Overlapped.WSASendTo()} functions.

@item 
gh-98744@footnote{https://github.com/python/cpython/issues/98744}: Prevent crashing in @ref{fd,,traceback} when retrieving the
byte-offset for some source files that contain certain unicode characters.

@item 
gh-98740@footnote{https://github.com/python/cpython/issues/98740}: Fix internal error in the @ref{b8,,re} module which in very rare
circumstances prevented compilation of a regular expression containing a
@ref{173b,,conditional expression} without the
"else" branch.

@item 
gh-98703@footnote{https://github.com/python/cpython/issues/98703}: Fix @ref{173c,,asyncio.StreamWriter.drain()} to call
@code{protocol.connection_lost} callback only once on Windows.

@item 
gh-98624@footnote{https://github.com/python/cpython/issues/98624}: Add a mutex to unittest.mock.NonCallableMock to protect
concurrent access to mock attributes.

@item 
gh-98658@footnote{https://github.com/python/cpython/issues/98658}: The @ref{19e,,array.array} class now supports subscripting, making
it a @ref{422,,generic type}.

@item 
gh-98284@footnote{https://github.com/python/cpython/issues/98284}: Improved @ref{522,,TypeError} message for undefined abstract
methods of a @ref{f02,,abc.ABC} instance. The names of the missing methods
are surrounded by single-quotes to highlight them.

@item 
gh-96151@footnote{https://github.com/python/cpython/issues/96151}: Allow @code{BUILTINS} to be a valid field name for frozen
dataclasses.

@item 
gh-98086@footnote{https://github.com/python/cpython/issues/98086}: Make sure @code{patch.dict()} can be applied on async functions.

@item 
gh-72719@footnote{https://github.com/python/cpython/issues/72719}: Remove modules @code{asyncore} and @code{asynchat}, which were
deprecated by 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

@item 
gh-96192@footnote{https://github.com/python/cpython/issues/96192}: Fix handling of @code{bytes} @ref{29d,,path-like objects} in @code{os.ismount()}.

@item 
gh-94172@footnote{https://github.com/python/cpython/issues/94172}: @ref{5d,,ftplib}: Remove the @code{FTP_TLS.ssl_version} class
attribute: use the `context' parameter instead. Patch by Victor Stinner

@item 
gh-94172@footnote{https://github.com/python/cpython/issues/94172}: Remove the `keyfile' and `certfile' parameters from the
@ref{5d,,ftplib}, @ref{73,,imaplib}, @ref{ab,,poplib} and @ref{c9,,smtplib} modules,
and the `key_file', `cert_file' and `check_hostname' parameters from the
@ref{6e,,http.client} module, all deprecated since Python 3.6. Use the
`context' parameter (`ssl_context' in @ref{73,,imaplib}) instead. Patch by
Victor Stinner.

@item 
gh-83638@footnote{https://github.com/python/cpython/issues/83638}: Add the @ref{49f,,autocommit} attribute to
@ref{242,,sqlite3.Connection} and the `autocommit' parameter to
@ref{2a5,,sqlite3.connect()} to control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant @ref{4a0,,transaction handling}. Patch by Erlend E.
Aasland.

@item 
gh-92452@footnote{https://github.com/python/cpython/issues/92452}: Fixed a race condition that could cause
@ref{1014,,sysconfig.get_config_var()} to incorrectly return @ref{660,,None} in
multi-threaded programs.

@item 
gh-91803@footnote{https://github.com/python/cpython/issues/91803}: Fix an error when using a method of objects mocked with
@ref{1590,,unittest.mock.create_autospec()} after it was sealed with
@ref{b8f,,unittest.mock.seal()} function.

@item 
bpo-38523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38523}: @ref{a17,,shutil.copytree()} now applies the
`ignore_dangling_symlinks' argument recursively.

@item 
bpo-40358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40358}: Add walk_up argument in @ref{2c8,,pathlib.PurePath.relative_to()}.

@item 
bpo-36267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36267}: Fix IndexError in @ref{523,,argparse.ArgumentParser} when a
@code{store_true} action is given an explicit argument.
@end itemize

@node Documentation<17>,Tests<20>,Library<22>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id181}@anchor{173d}
@subsubsection Documentation



@itemize -

@item 
gh-98832@footnote{https://github.com/python/cpython/issues/98832}: Changes wording of docstring for @ref{15ba,,pathlib.Path.iterdir()}.

@item 
gh-97966@footnote{https://github.com/python/cpython/issues/97966}: Update uname docs to clarify the special nature of the platform
attribute and to indicate when it became late-bound.
@end itemize

@node Tests<20>,Build<22>,Documentation<17>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id182}@anchor{173e}
@subsubsection Tests



@itemize -

@item 
gh-98903@footnote{https://github.com/python/cpython/issues/98903}: The Python test suite now fails with exit code 4 if no tests
ran. It should help detecting typos in test names and test methods.

@item 
gh-98713@footnote{https://github.com/python/cpython/issues/98713}: Fix a bug in the @ref{103,,typing} tests where a test relying on
CPython-specific implementation details was not decorated with
@code{@@cpython_only} and was not skipped on other implementations.

@item 
gh-87390@footnote{https://github.com/python/cpython/issues/87390}: Add tests for star-unpacking with PEP 646, and some other
miscellaneous PEP 646 tests.

@item 
gh-96853@footnote{https://github.com/python/cpython/issues/96853}: Added explicit coverage of @code{Py_Initialize} (and hence
@code{Py_InitializeEx}) back to the embedding tests (all other embedding
tests migrated to @code{Py_InitializeFromConfig} in Python 3.11)

@item 
bpo-34272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34272}: Some C API tests were moved into the new Lib/test/test_capi/
directory.
@end itemize

@node Build<22>,Windows<19>,Tests<20>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id183}@anchor{173f}
@subsubsection Build



@itemize -

@item 
gh-99086@footnote{https://github.com/python/cpython/issues/99086}: Fix @code{-Wimplicit-int} compiler warning in @code{configure}
check for @code{PTHREAD_SCOPE_SYSTEM}.

@item 
gh-99016@footnote{https://github.com/python/cpython/issues/99016}: Fix build with @code{PYTHON_FOR_REGEN=python3.8}.

@item 
gh-97731@footnote{https://github.com/python/cpython/issues/97731}: Specify the full path to the source location for @code{make
docclean} (needed for cross-builds).

@item 
gh-98949@footnote{https://github.com/python/cpython/issues/98949}: Drop unused build dependency on @code{readelf}.

@item 
gh-98989@footnote{https://github.com/python/cpython/issues/98989}: Use @code{python3.11}, if available, for regeneration and freezing.

@item 
gh-98831@footnote{https://github.com/python/cpython/issues/98831}: Add new tooling, in @code{Tools/cases_generator}, to generate the
interpreter switch statement from a list of opcode definitions. This only
affects adding, modifying or removing instruction definitions. The
instruction definitions now live in @code{Python/bytecodes.c}, in the form of
a custom DSL (under development)@footnote{https://github.com/faster-cpython/ideas/blob/main/3.12/interpreter_definition.md}.
The tooling reads this file and writes @code{Python/generated_cases.c.h},
which is then included by @code{Python/ceval.c} to provide most of the cases
of the main interpreter switch.

@item 
gh-98817@footnote{https://github.com/python/cpython/issues/98817}: Remove PCbuild/lib.pyproj: it's not used for anything, is only a
minor convenience for Visual Studio users (who probably mostly don't even
know about it), and it takes a lot of maintenance effort to keep updated.

@item 
gh-98776@footnote{https://github.com/python/cpython/issues/98776}: Fix @code{make regen-test-levenshtein} for out-of-tree builds.

@item 
gh-98707@footnote{https://github.com/python/cpython/issues/98707}: Don't use vendored @code{libmpdec} headers if
@ref{408,,--with-system-libmpdec} is passed to @code{configure}. Don't
use vendored @code{libexpat} headers if @ref{1740,,--with-system-expat} is
passed to @code{configure}.
@end itemize

@node Windows<19>,macOS<14>,Build<22>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id184}@anchor{1741}
@subsubsection Windows



@itemize -

@item 
gh-98689@footnote{https://github.com/python/cpython/issues/98689}: Update Windows builds to zlib v1.2.13.  v1.2.12 has
@geindex Common Vulnerabilities and Exposures; CVE 2022-37434
CVE 2022-37434@footnote{https://www.cve.org/CVERecord?id=CVE-2022-37434}, but the vulnerable @code{inflateGetHeader} API is not used
by Python.

@item 
gh-98790@footnote{https://github.com/python/cpython/issues/98790}: Assumes that a missing @code{DLLs} directory means that standard
extension modules are in the executable's directory.

@item 
gh-98745@footnote{https://github.com/python/cpython/issues/98745}: Update @code{py.exe} launcher to install 3.11 by default and
3.12 on request.

@item 
gh-98692@footnote{https://github.com/python/cpython/issues/98692}: Fix the @ref{5a8,,Lanceur Python pour Windows} ignoring unrecognized shebang lines
instead of treating them as local paths

@item 
gh-94328@footnote{https://github.com/python/cpython/issues/94328}: Update Windows installer to use SQLite 3.39.4.
@end itemize

@node macOS<14>,C API<21>,Windows<19>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id185}@anchor{1742}
@subsubsection macOS



@itemize -

@item 
gh-94328@footnote{https://github.com/python/cpython/issues/94328}: Update macOS installer to SQLite 3.39.4.
@end itemize

@node C API<21>,,macOS<14>,Python 3 12 0 alpha 2
@anchor{whatsnew/changelog id186}@anchor{1743}
@subsubsection C API



@itemize -

@item 
gh-98724@footnote{https://github.com/python/cpython/issues/98724}: The @ref{564,,Py_CLEAR}, @ref{565,,Py_SETREF} and
@ref{566,,Py_XSETREF} macros now only evaluate their argument once. If the
argument has side effects, these side effects are no longer duplicated.
Patch by Victor Stinner.

@item 
gh-98978@footnote{https://github.com/python/cpython/issues/98978}: Fix use-after-free in @code{Py_SetPythonHome(NULL)},
@code{Py_SetProgramName(NULL)} and @code{_Py_SetProgramFullPath(NULL)} function
calls. Issue reported by Benedikt Reinartz. Patch by Victor Stinner.

@item 
gh-98410@footnote{https://github.com/python/cpython/issues/98410}: Add @code{getbufferproc} and @code{releasebufferproc} to the stable
API.

@item 
gh-98610@footnote{https://github.com/python/cpython/issues/98610}: Some configurable capabilities of sub-interpreters have changed.
They always allow subprocesses (@ref{d5,,subprocess}) now, whereas before
subprocesses could be optionally disallowed for a sub-interpreter. Instead
@code{os.exec()} can now be disallowed. Disallowing daemon threads is now
supported.  Disallowing all threads is still allowed, but is never done by
default. Note that the optional restrictions are only available through
@code{_Py_NewInterpreterFromConfig()}, which isn't a public API. They do not
affect the main interpreter, nor @ref{1744,,Py_NewInterpreter()}.

@item 
gh-98608@footnote{https://github.com/python/cpython/issues/98608}: A @code{_PyInterpreterConfig} has been added and
@code{_Py_NewInterpreter()} has been renamed to
@code{_Py_NewInterpreterFromConfig()}.  The "isolated_subinterpreters"
argument is now a granular config that captures the previous behavior.
Note that this is all "private" API.

@item 
gh-96853@footnote{https://github.com/python/cpython/issues/96853}: @code{Py_InitializeEx} now correctly calls @code{PyConfig_Clear} after
initializing the interpreter (the omission didn't cause a memory leak only
because none of the dynamically allocated config fields are populated by
the wrapper function)

@item 
gh-91248@footnote{https://github.com/python/cpython/issues/91248}: Add @ref{554,,PyFrame_GetVar()} and @ref{555,,PyFrame_GetVarString()}
functions to get a frame variable by its name. Patch by Victor Stinner.
@end itemize

@node Python 3 12 0 alpha 1,Python 3 11 0 beta 1,Python 3 12 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-12-0-alpha-1}@anchor{1745}
@subsection Python 3.12.0 alpha 1


`Release date: 2022-10-25'

@menu
* Security: Security<16>. 
* Core and Builtins: Core and Builtins<24>. 
* Library: Library<23>. 
* Documentation: Documentation<18>. 
* Tests: Tests<21>. 
* Build: Build<23>. 
* Windows: Windows<20>. 
* macOS: macOS<15>. 
* IDLE: IDLE<15>. 
* Tools/Demos: Tools/Demos<12>. 
* C API: C API<22>. 

@end menu

@node Security<16>,Core and Builtins<24>,,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id187}@anchor{1746}
@subsubsection Security



@itemize -

@item 
gh-97616@footnote{https://github.com/python/cpython/issues/97616}: Fix multiplying a list by an integer (@code{list *= int}): detect
the integer overflow when the new allocated length is close to the maximum
size. Issue reported by Jordan Limor.  Patch by Victor Stinner.

@item 
gh-97514@footnote{https://github.com/python/cpython/issues/97514}: On Linux the @ref{93,,multiprocessing} module returns to using
filesystem backed unix domain sockets for communication with the
`forkserver' process instead of the Linux abstract socket namespace.  Only
code that chooses to use the @ref{2c6,,"forkserver" start method} is affected.

Abstract sockets have no permissions and could allow any user on the
system in the same network namespace@footnote{https://man7.org/linux/man-pages/man7/network_namespaces.7.html} (often
the whole system) to inject code into the multiprocessing `forkserver'
process. This was a potential privilege escalation. Filesystem based
socket permissions restrict this to the `forkserver' process user as was
the default in Python 3.8 and earlier.

This prevents Linux 
@geindex Common Vulnerabilities and Exposures; CVE 2022-42919
CVE 2022-42919@footnote{https://www.cve.org/CVERecord?id=CVE-2022-42919}.

@item 
gh-87389@footnote{https://github.com/python/cpython/issues/87389}: @ref{71,,http.server}: Fix an open redirection vulnerability in the
HTTP server when an URI path starts with @code{//}.  Vulnerability
discovered, and initial fix proposed, by Hamza Avvan.

@item 
gh-79096@footnote{https://github.com/python/cpython/issues/79096}: LWPCookieJar and MozillaCookieJar create files with file mode
600 instead of 644 (Microsoft Windows is not affected)

@item 
gh-92888@footnote{https://github.com/python/cpython/issues/92888}: Fix @code{memoryview} use after free when accessing the backing
buffer in certain cases.

@item 
gh-68966@footnote{https://github.com/python/cpython/issues/68966}: The deprecated mailcap module now refuses to inject unsafe text
(filenames, MIME types, parameters) into shell commands. Instead of using
such text, it will warn and act as if a match was not found (or for test
commands, as if the test failed).
@end itemize

@node Core and Builtins<24>,Library<23>,Security<16>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id188}@anchor{1747}
@subsubsection Core and Builtins



@itemize -

@item 
gh-98374@footnote{https://github.com/python/cpython/issues/98374}: Suppress ImportError for invalid query for help() command. Patch
by Donghee Na.

@item 
gh-98461@footnote{https://github.com/python/cpython/issues/98461}: Fix source location in bytecode for list, set and dict
comprehensions as well as generator expressions.

@item 
gh-98354@footnote{https://github.com/python/cpython/issues/98354}: Added unicode check for @code{name} attribute of @code{spec} argument
passed in @code{_imp.create_builtin()} function.

@item 
gh-98398@footnote{https://github.com/python/cpython/issues/98398}: Fix source location of 'assert' bytecodes.

@item 
gh-98390@footnote{https://github.com/python/cpython/issues/98390}: Fix location of sub-expressions of boolean expressions, by
reducing their scope to that of the sub-expression.

@item 
gh-98254@footnote{https://github.com/python/cpython/issues/98254}: Modules from the standard library are now potentially suggested
as part of the error messages displayed by the interpreter when an
@ref{428,,NameError} is raised to the top level. Patch by Pablo Galindo

@item 
gh-97997@footnote{https://github.com/python/cpython/issues/97997}: Add running column offset to the tokenizer state to avoid
calculating AST column information with pointer arithmetic.

@item 
gh-97973@footnote{https://github.com/python/cpython/issues/97973}: Modify the tokenizer to return all necessary information the
parser needs to set location information in the AST nodes, so that the
parser does not have to calculate those doing pointer arithmetic.

@item 
gh-96078@footnote{https://github.com/python/cpython/issues/96078}: @ref{10f1,,os.sched_yield()} now release the GIL while calling
sched_yield(2). Patch by Donghee Na.

@item 
gh-97955@footnote{https://github.com/python/cpython/issues/97955}: Migrate @ref{133,,zoneinfo} to Argument Clinic.

@item 
gh-97912@footnote{https://github.com/python/cpython/issues/97912}: The compiler now avoids quadratic behavior when finding which
instructions should use the @ref{4cf,,LOAD_FAST_CHECK} opcode.

@item 
gh-97002@footnote{https://github.com/python/cpython/issues/97002}: Fix an issue where several frame objects could be backed by the
same interpreter frame, possibly leading to corrupted memory and hard
crashes of the interpreter.

@item 
gh-97943@footnote{https://github.com/python/cpython/issues/97943}: Bugfix: @ref{1748,,PyFunction_GetAnnotations()} should return a
borrowed reference. It was returning a new reference.

@item 
gh-97922@footnote{https://github.com/python/cpython/issues/97922}: The Garbage Collector now runs only on the eval breaker
mechanism of the Python bytecode evaluation loop instead on object
allocations. The GC can also run when @ref{450,,PyErr_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.

@item 
gh-65961@footnote{https://github.com/python/cpython/issues/65961}: When @code{__package__} is different than @code{__spec__.parent},
raise a @code{DeprecationWarning} instead of @code{ImportWarning}.

Also remove @code{importlib.util.set_package()} which was scheduled for
removal.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Long deprecated, @code{module_repr()} should now be completely
eradicated.

@item 
gh-86298@footnote{https://github.com/python/cpython/issues/86298}: In cases where @code{warnings.warn_explicit()} consults the
module's loader, an @code{DeprecationWarning} is issued when @code{m.__loader__}
differs from @code{m.__spec__.loader}.

@item 
gh-97779@footnote{https://github.com/python/cpython/issues/97779}: Ensure that all Python frame objects are backed by "complete"
frames.

@item 
gh-91052@footnote{https://github.com/python/cpython/issues/91052}: Add API for subscribing to modification events on selected
dictionaries.

@item 
gh-97752@footnote{https://github.com/python/cpython/issues/97752}: Fix possible data corruption or crashes when accessing the
@code{f_back} member of newly-created generator or coroutine frames.

@item 
gh-97591@footnote{https://github.com/python/cpython/issues/97591}: Fixed a missing incref/decref pair in
@code{Exception.__setstate__()}. Patch by Ofey Chan.

@item 
gh-97670@footnote{https://github.com/python/cpython/issues/97670}: Remove the @code{sys.getdxp()} function and the
@code{Tools/scripts/analyze_dxp.py} script. DXP stands for "dynamic execution
pairs". They were related to @code{DYNAMIC_EXECUTION_PROFILE} and @code{DXPAIRS}
macros which have been removed in Python 3.11. Python can now be built
with @ref{1749,,./configure --enable-pystats} to gather
statistics on Python opcodes.  Patch by Victor Stinner.

@item 
gh-94526@footnote{https://github.com/python/cpython/issues/94526}: Fix the Python path configuration used to initialized
@ref{3ab,,sys.path} at Python startup. Paths are no longer encoded to
UTF-8/strict to avoid encoding errors if it contains surrogate characters
(bytes paths are decoded with the surrogateescape error handler). Patch by
Victor Stinner.

@item 
gh-96670@footnote{https://github.com/python/cpython/issues/96670}: The parser now raises @ref{18b,,SyntaxError} when parsing source
code containing null bytes. Patch by Pablo Galindo

@item 
gh-96975@footnote{https://github.com/python/cpython/issues/96975}: Fix a crash occurring when @ref{174a,,PyEval_GetFrame()} is called
while the topmost Python frame is in a partially-initialized state.

@item 
gh-96848@footnote{https://github.com/python/cpython/issues/96848}: Fix command line parsing: reject @ref{175,,-X int_max_str_digits} option with no value (invalid) when the
@geindex PYTHONINTMAXSTRDIGITS
@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@ref{174b,,PYTHONINTMAXSTRDIGITS} environment variable is set to a valid
limit. Patch by Victor Stinner.

@item 
gh-95921@footnote{https://github.com/python/cpython/issues/95921}: Fix overly-broad source position information for chained
comparisons used as branching conditions.

@item 
gh-96821@footnote{https://github.com/python/cpython/issues/96821}: Fix undefined behaviour in @code{audioop.c}.

@item 
gh-96821@footnote{https://github.com/python/cpython/issues/96821}: Fix undefined behaviour in @code{_testcapimodule.c}.

@item 
gh-95778@footnote{https://github.com/python/cpython/issues/95778}: When @ref{1ff,,ValueError} is raised if an integer is larger than
the limit, mention the @ref{174c,,sys.set_int_max_str_digits()} function in the
error message. Patch by Victor Stinner.

@item 
gh-96387@footnote{https://github.com/python/cpython/issues/96387}: At Python exit, sometimes a thread holding the GIL can wait
forever for a thread (usually a daemon thread) which requested to drop the
GIL, whereas the thread already exited. To fix the race condition, the
thread which requested the GIL drop now resets its request before exiting.
Issue discovered and analyzed by Mingliang ZHAO. Patch by Victor Stinner.

@item 
gh-96864@footnote{https://github.com/python/cpython/issues/96864}: Fix a possible assertion failure, fatal error, or
@ref{561,,SystemError} if a line tracing event raises an exception while
opcode tracing is enabled.

@item 
gh-95778@footnote{https://github.com/python/cpython/issues/95778}: The @code{PyLong_FromString} function was refactored to make it
more maintainable and extensible.

@item 
gh-96678@footnote{https://github.com/python/cpython/issues/96678}: Fix undefined behaviour in C code of null pointer arithmetic.

@item 
gh-96754@footnote{https://github.com/python/cpython/issues/96754}: Make sure that all frame objects created are created from valid
interpreter frames. Prevents the possibility of invalid frames in
backtraces and signal handlers.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Improve the performance of reading and writing inline bytecode
caches on some platforms.

@item 
gh-96751@footnote{https://github.com/python/cpython/issues/96751}: Remove dead code from @code{CALL_FUNCTION_EX} opcode.

@item 
gh-90751@footnote{https://github.com/python/cpython/issues/90751}: @ref{452,,memoryview} now supports half-floats. Patch by Donghee
Na and Antoine Pitrou.

@item 
gh-96678@footnote{https://github.com/python/cpython/issues/96678}: Fix case of undefined behavior in ceval.c

@item 
gh-64373@footnote{https://github.com/python/cpython/issues/64373}: Convert @code{_functools} to argument clinic.

@item 
gh-96641@footnote{https://github.com/python/cpython/issues/96641}: Do not expose @code{KeyWrapper} in @code{_functools}.

@item 
gh-96636@footnote{https://github.com/python/cpython/issues/96636}: Ensure that tracing, @code{sys.setrace()}, is turned on
immediately. In pre-release versions of 3.11, some tracing events might
have been lost when turning on tracing in a @code{__del__} method or
interrupt.

@item 
gh-96572@footnote{https://github.com/python/cpython/issues/96572}: Fix use after free in trace refs build mode. Patch by Kumar
Aditya.

@item 
gh-96611@footnote{https://github.com/python/cpython/issues/96611}: When loading a file with invalid UTF-8 inside a multi-line
string, a correct SyntaxError is emitted.

@item 
gh-96612@footnote{https://github.com/python/cpython/issues/96612}: Make sure that incomplete frames do not show up in tracemalloc
traces.

@item 
gh-90230@footnote{https://github.com/python/cpython/issues/90230}: Fix compiler warnings and test failures when building with
@code{--enable-pystats}.

@item 
gh-96587@footnote{https://github.com/python/cpython/issues/96587}: Correctly raise @code{SyntaxError} on exception groups (
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/})
on python versions prior to 3.11

@item 
gh-96569@footnote{https://github.com/python/cpython/issues/96569}: Remove two cases of undefined behavior, by adding NULL checks.

@item 
gh-96582@footnote{https://github.com/python/cpython/issues/96582}: Fix possible @code{NULL} pointer dereference in
@code{_PyThread_CurrentFrames}. Patch by Kumar Aditya.

@item 
gh-91079@footnote{https://github.com/python/cpython/issues/91079}: Separate Python recursion checking from C recursion checking
which reduces the chance of C stack overflow and allows the recursion
limit to be increased safely.

@item 
gh-93911@footnote{https://github.com/python/cpython/issues/93911}: Fix an issue that could prevent @ref{4c8,,LOAD_ATTR} from
specializing properly when accessing properties.

@item 
gh-96348@footnote{https://github.com/python/cpython/issues/96348}: Emit a DeprecationWarning when @ref{4e2,,throw()},
@ref{4e1,,throw()} or @ref{4e3,,athrow()} are called with more than
one argument.

@item 
gh-95196@footnote{https://github.com/python/cpython/issues/95196}: Disable incorrect pickling of the C implemented classmethod
descriptors.

@item 
gh-96364@footnote{https://github.com/python/cpython/issues/96364}: Fix text signatures of @code{list.__getitem__} and
@code{dict.__getitem__}.

@item 
gh-96352@footnote{https://github.com/python/cpython/issues/96352}: Fix @ref{343,,AttributeError} missing @code{name} and @code{obj}
attributes in @ref{bc0,,object.__getattribute__()}. Patch by Philip Georgi.

@item 
gh-93554@footnote{https://github.com/python/cpython/issues/93554}: Change the jump opcodes so that all conditional jumps are
forward jumps. Backward jumps are converted by the assembler into a
conditional forward jump whose target is the fallthrough block (and with a
reversed condition), followed by an unconditional backward jump. For
example:

@code{POP_JUMP_IF_TRUE BACKWARD_TARGET} becomes @code{POP_JUMP_IF_FALSE
NEXT_BLOCK; JUMP BACKWARD_TARGET}.

All the directed conditional jump opcodes were removed:
@code{POP_JUMP_FORWARD_IF_TRUE}, @code{POP_JUMP_BACKWARD_IF_TRUE},
@code{POP_JUMP_FORWARD_IF_FALSE}, @code{POP_JUMP_BACKWARD_IF_FALSE},
@code{POP_JUMP_FORWARD_IF_NONE}, @code{POP_JUMP_BACKWARD_IF_NONE},
@code{POP_JUMP_FORWARD_IF_NOT_NONE}, @code{POP_JUMP_BACKWARD_IF_NOT_NONE}.

The corresponding opcodes without direction are no longer
pseudo-instructions, and they implement the forward conditional jumps.

@item 
gh-96268@footnote{https://github.com/python/cpython/issues/96268}: Loading a file with invalid UTF-8 will now report the broken
character at the correct location.

@item 
gh-96237@footnote{https://github.com/python/cpython/issues/96237}: The internal field @code{_PyInterpreterFrame.f_func} is renamed to
@code{_PyInterpreterFrame.f_funcobj} and may be any object. The @code{f_globals}
and @code{f_builtin} fields may hold junk values.

It is safest to treat the @code{_PyInterpreterFrame} struct as opaque.

@item 
gh-96187@footnote{https://github.com/python/cpython/issues/96187}: Fixed a bug that caused @code{_PyCode_GetExtra} to return garbage
for negative indexes. Patch by Pablo Galindo

@item 
gh-96143@footnote{https://github.com/python/cpython/issues/96143}: Add a new @code{-X perf} Python command line option as well as
@ref{459,,sys.activate_stack_trampoline()} and
@ref{45a,,sys.deactivate_stack_trampoline()} function in the @ref{d8,,sys} module
that allows to set/unset the interpreter in a way that the Linux @code{perf}
profiler can detect Python calls. The new
@ref{45b,,sys.is_stack_trampoline_active()} function allows to query the state
of the perf trampoline. Design by Pablo Galindo. Patch by Pablo Galindo
and Christian Heimes with contributions from Gregory P. Smith [Google] and
Mark Shannon.

@item 
gh-96071@footnote{https://github.com/python/cpython/issues/96071}: Fix a deadlock in @ref{3a2,,PyGILState_Ensure()} when allocating
new thread state. Patch by Kumar Aditya.

@item 
gh-96046@footnote{https://github.com/python/cpython/issues/96046}: @ref{766,,PyType_Ready()} now initializes @code{ht_cached_keys} and
performs additional checks to ensure that type objects are properly
configured. This avoids crashes in 3rd party packages that don't use
regular API to create new types.

@item 
gh-96005@footnote{https://github.com/python/cpython/issues/96005}: On WASI @ref{174d,,ENOTCAPABLE} is now mapped to
@ref{d30,,PermissionError}. The @ref{56,,errno} modules exposes the new error
number. @code{getpath.py} now ignores @ref{d30,,PermissionError} when it cannot
open landmark files @code{pybuilddir.txt} and @code{pyenv.cfg}.

@item 
gh-93678@footnote{https://github.com/python/cpython/issues/93678}: Added test a harness for direct unit tests of the compiler's
optimization stage. The @code{_testinternalcapi.optimize_cfg()} function runs
the optimiser on a sequence of instructions. The
@code{CfgOptimizationTestCase} class in @code{test.support} has utilities for
invoking the optimizer and checking the output.

@item 
gh-95245@footnote{https://github.com/python/cpython/issues/95245}: Reduces the size of a "simple" Python object from 8 to 6 words
by moving the weakreflist pointer into the pre-header directly before the
object's dict/values pointer.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Compile virtual @ref{6d3,,try}/@ref{189,,except} blocks to
handle exceptions raised during @ref{167d,,close()} or
@ref{4e2,,throw()} calls through a suspended frame.

@item 
gh-95977@footnote{https://github.com/python/cpython/issues/95977}: Optimized calling @ref{149d,,__get__()} with vectorcall. Patch
by Kumar Aditya.

@item 
gh-91210@footnote{https://github.com/python/cpython/issues/91210}: Improve error message when a parameter without a default value
follows one with a default value, and show the same message, even when the
non-default/default sequence is preceded by positional-only parameters.

@item 
gh-95922@footnote{https://github.com/python/cpython/issues/95922}: Fixed bug where the compiler's @code{eliminate_empty_basic_blocks}
function ignores the last block of the code unit.

@item 
gh-95818@footnote{https://github.com/python/cpython/issues/95818}: Skip over incomplete frames in @ref{778,,PyThreadState_GetFrame()}.

@item 
gh-95876@footnote{https://github.com/python/cpython/issues/95876}: Fix format string in @code{_PyPegen_raise_error_known_location}
that can lead to memory corruption on some 64bit systems. The function was
building a tuple with @code{i} (int) instead of @code{n} (Py_ssize_t) for
Py_ssize_t arguments.

@item 
gh-95605@footnote{https://github.com/python/cpython/issues/95605}: Fix misleading contents of error message when converting an
all-whitespace string to @ref{2eb,,float}.

@item 
gh-95150@footnote{https://github.com/python/cpython/issues/95150}: Update code object hashing and equality to consider all
debugging and exception handling tables. This fixes an issue where certain
non-identical code objects could be "deduplicated" during compilation.

@item 
gh-91146@footnote{https://github.com/python/cpython/issues/91146}: Reduce allocation size of @ref{5fc,,list} from @ref{e93,,str.split()}
and @ref{1234,,str.rsplit()}. Patch by Donghee Na and Inada Naoki.

@item 
gh-87092@footnote{https://github.com/python/cpython/issues/87092}: Create a 'jump target label' abstraction in the compiler so that
the compiler's codegen stage does not work directly with basic blocks.
This prepares the code for changes to the underlying CFG generation
mechanism.

@item 
gh-95355@footnote{https://github.com/python/cpython/issues/95355}: @code{_PyPegen_Parser_New} now properly detects token memory
allocation errors. Patch by Honglin Zhu.

@item 
gh-90081@footnote{https://github.com/python/cpython/issues/90081}: Run Python code in tracer/profiler function at full speed. Fixes
slowdown in earlier versions of 3.11.

@item 
gh-95324@footnote{https://github.com/python/cpython/issues/95324}: Emit a warning in debug mode if an object does not call
@ref{14bd,,PyObject_GC_UnTrack()} before deallocation. Patch by Pablo Galindo.

@item 
gh-95245@footnote{https://github.com/python/cpython/issues/95245}: Merge managed dict and values pointer into a single tagged
pointer to save one word in the pre-header.

@item 
gh-93678@footnote{https://github.com/python/cpython/issues/93678}: Add cfg_builder struct and refactor the relevant code so that a
cfg can be constructed without an instance of the compiler struct.

@item 
gh-95185@footnote{https://github.com/python/cpython/issues/95185}: Prevented crashes in the AST constructor when compiling some
absurdly long expressions like @code{"+0"*1000000}. @ref{d59,,RecursionError} is
now raised instead. Patch by Pablo Galindo

@item 
gh-93351@footnote{https://github.com/python/cpython/issues/93351}: @ref{1a4,,ast.AST} node positions are now validated when provided
to @ref{190,,compile()} and other related functions. If invalid positions are
detected, a @ref{1ff,,ValueError} will be raised.

@item 
gh-94438@footnote{https://github.com/python/cpython/issues/94438}: Fix an issue that caused extended opcode arguments and some
conditional pops to be ignored when calculating valid jump targets for
assignments to the @code{f_lineno} attribute of frame objects. In some cases,
this could cause inconsistent internal state, resulting in a hard crash of
the interpreter.

@item 
gh-95060@footnote{https://github.com/python/cpython/issues/95060}: Undocumented @code{PyCode_Addr2Location} function now properly
returns when @code{addrq} argument is less than zero.

@item 
gh-95113@footnote{https://github.com/python/cpython/issues/95113}: Replace all @code{EXTENDED_ARG_QUICK} instructions with basic
@ref{1733,,EXTENDED_ARG} instructions in unquickened code. Consumers of
non-adaptive bytecode should be able to handle extended arguments the same
way they were handled in CPython 3.10 and older.

@item 
gh-91409@footnote{https://github.com/python/cpython/issues/91409}: Fix incorrect source location info caused by certain
optimizations in the bytecode compiler.

@item 
gh-95023@footnote{https://github.com/python/cpython/issues/95023}: Implement @ref{174e,,os.setns()} and  @ref{174f,,os.unshare()} for Linux.
Patch by Noam Cohen.

@item 
gh-94036@footnote{https://github.com/python/cpython/issues/94036}: Fix incorrect source location info for some multi-line attribute
accesses and method calls.

@item 
gh-94938@footnote{https://github.com/python/cpython/issues/94938}: Fix error detection in some builtin functions when keyword
argument name is an instance of a str subclass with overloaded @code{__eq__}
and @code{__hash__}. Previously it could cause SystemError or other undesired
behavior.

@item 
gh-94996@footnote{https://github.com/python/cpython/issues/94996}: @ref{1a6,,ast.parse()} will no longer parse function definitions with
positional-only params when passed @code{feature_version} less than @code{(3,
8)}. Patch by Shantanu Jain.

@item 
gh-94739@footnote{https://github.com/python/cpython/issues/94739}: Allow jumping within, out of, and across exception handlers in
the debugger.

@item 
gh-94949@footnote{https://github.com/python/cpython/issues/94949}: @ref{1a6,,ast.parse()} will no longer parse parenthesized context
managers when passed @code{feature_version} less than @code{(3, 9)}. Patch by
Shantanu Jain.

@item 
gh-94947@footnote{https://github.com/python/cpython/issues/94947}: @ref{1a6,,ast.parse()} will no longer parse assignment expressions
when passed @code{feature_version} less than @code{(3, 8)}. Patch by Shantanu
Jain.

@item 
gh-91256@footnote{https://github.com/python/cpython/issues/91256}: Ensures the program name is known for help text during
interpreter startup.

@item 
gh-94869@footnote{https://github.com/python/cpython/issues/94869}: Fix the column offsets for some expressions in multi-line
f-strings @ref{8,,ast} nodes. Patch by Pablo Galindo.

@item 
gh-94893@footnote{https://github.com/python/cpython/issues/94893}: Fix an issue where frame object manipulations could corrupt
inline bytecode caches.

@item 
gh-94822@footnote{https://github.com/python/cpython/issues/94822}: Fix an issue where lookups of metaclass descriptors may be
ignored when an identically-named attribute also exists on the class
itself.

@item 
gh-91153@footnote{https://github.com/python/cpython/issues/91153}: Fix an issue where a @ref{528,,bytearray} item assignment could
crash if it's resized by the new value's @code{__index__()} method.

@item 
gh-90699@footnote{https://github.com/python/cpython/issues/90699}: Fix reference counting bug in @code{bool.__repr__()}. Patch by
Kumar Aditya.

@item 
gh-94694@footnote{https://github.com/python/cpython/issues/94694}: Fix an issue that could cause code with multi-line method
lookups to have misleading or incorrect column offset information. In some
cases (when compiling a hand-built AST) this could have resulted in a hard
crash of the interpreter.

@item 
gh-93252@footnote{https://github.com/python/cpython/issues/93252}: Fix an issue that caused internal frames to outlive failed
Python function calls, possibly resulting in memory leaks or hard
interpreter crashes.

@item 
gh-94215@footnote{https://github.com/python/cpython/issues/94215}: Fix an issue where exceptions raised by line-tracing events
would cause frames to be left in an invalid state, possibly resulting in a
hard crash of the interpreter.

@item 
gh-92228@footnote{https://github.com/python/cpython/issues/92228}: Disable the compiler's inline-small-exit-blocks optimization for
exit blocks that are associated with source code lines. This fixes a bug
where the debugger cannot tell where an exception handler ends and the
following code block begins.

@item 
gh-94485@footnote{https://github.com/python/cpython/issues/94485}: Line number of a module's @code{RESUME} instruction is set to 0 as
specified in 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}.

@item 
gh-94438@footnote{https://github.com/python/cpython/issues/94438}: Account for instructions that can push NULL to the stack when
setting line number in a frame. Prevents some (unlikely) crashes.

@item 
gh-91719@footnote{https://github.com/python/cpython/issues/91719}: Reload @code{opcode} when raising @code{unknown opcode error} in the
interpreter main loop, for C compilers to generate dispatching code
independently.

@item 
gh-94329@footnote{https://github.com/python/cpython/issues/94329}: Compile and run code with unpacking of extremely large sequences
(1000s of elements). Such code failed to compile. It now compiles and runs
correctly.

@item 
gh-94360@footnote{https://github.com/python/cpython/issues/94360}: Fixed a tokenizer crash when reading encoded files with syntax
errors from @code{stdin} with non utf-8 encoded text. Patch by Pablo Galindo

@item 
gh-88116@footnote{https://github.com/python/cpython/issues/88116}: Fix an issue when reading line numbers from code objects if the
encoded line numbers are close to @code{INT_MIN}. Patch by Pablo Galindo

@item 
gh-94262@footnote{https://github.com/python/cpython/issues/94262}: Don't create frame objects for incomplete frames. Prevents the
creation of generators and closures from being observable to Python and C
extensions, restoring the behavior of 3.10 and earlier.

@item 
gh-94192@footnote{https://github.com/python/cpython/issues/94192}: Fix error for dictionary literals with invalid expression as
value.

@item 
gh-87995@footnote{https://github.com/python/cpython/issues/87995}: @ref{457,,types.MappingProxyType} instances are now hashable if
the underlying mapping is hashable.

@item 
gh-93883@footnote{https://github.com/python/cpython/issues/93883}: Revise the display strategy of traceback enhanced error
locations.  The indicators are only shown when the location doesn't span
the whole line.

@item 
gh-94163@footnote{https://github.com/python/cpython/issues/94163}: Add @ref{4c9,,BINARY_SLICE} and @ref{4ca,,STORE_SLICE}
instructions for more efficient handling and better specialization of
slicing operations, where the slice is explicit in the source code.

@item 
gh-94021@footnote{https://github.com/python/cpython/issues/94021}: Fix unreachable code warning in @code{Python/specialize.c}.

@item 
gh-93911@footnote{https://github.com/python/cpython/issues/93911}: Specialize @code{LOAD_ATTR} for objects with custom
@code{__getattribute__}.

@item 
gh-93955@footnote{https://github.com/python/cpython/issues/93955}: Improve performance of attribute lookups on objects with custom
@code{__getattribute__} and @code{__getattr__}. Patch by Ken Jin.

@item 
gh-93911@footnote{https://github.com/python/cpython/issues/93911}: Specialize @code{LOAD_ATTR} for @code{property()} attributes.

@item 
gh-93678@footnote{https://github.com/python/cpython/issues/93678}: Refactor compiler optimisation code so that it no longer needs
the @code{struct assembler} and @code{struct compiler} passed around. Instead,
each function takes the CFG and other data that it actually needs. This
will make it possible to test this code directly.

@item 
gh-93841@footnote{https://github.com/python/cpython/issues/93841}: When built with @code{-enable-pystats}, @code{sys._stats_on()},
@code{sys._stats_off()}, @code{sys._stats_clear()} and @code{sys._stats_dump()}
functions have been added to enable gathering stats for parts of programs.

@item 
gh-93516@footnote{https://github.com/python/cpython/issues/93516}: Store offset of first traceable instruction in code object to
avoid having to recompute it for each instruction when tracing.

@item 
gh-93516@footnote{https://github.com/python/cpython/issues/93516}: Lazily create a table mapping bytecode offsets to line numbers
to speed up calculation of line numbers when tracing.

@item 
gh-89828@footnote{https://github.com/python/cpython/issues/89828}: @ref{7d5,,types.GenericAlias} no longer relays the @code{__class__}
attribute. For example, @code{isinstance(list[int], type)} no longer returns
@code{True}.

@item 
gh-93678@footnote{https://github.com/python/cpython/issues/93678}: Refactor the compiler to reduce boilerplate and repetition.

@item 
gh-93671@footnote{https://github.com/python/cpython/issues/93671}: Fix some exponential backtrace case happening with deeply nested
sequence patterns in match statements. Patch by Pablo Galindo

@item 
gh-93662@footnote{https://github.com/python/cpython/issues/93662}: Make sure that the end column offsets are correct in multi-line
method calls. Previously, the end column could precede the column offset.

@item 
gh-93461@footnote{https://github.com/python/cpython/issues/93461}: @ref{bfe,,importlib.invalidate_caches()} now drops entries from
@ref{5ce,,sys.path_importer_cache} with a relative path as name. This solves
a caching issue when a process changes its current working directory.

@code{FileFinder} no longer inserts a dot in the path, e.g. @code{/egg/./spam}
is now @code{/egg/spam}.

@item 
gh-93621@footnote{https://github.com/python/cpython/issues/93621}: Change order of bytecode instructions emitted for
@ref{5bc,,with} and @ref{5bf,,async with} to reduce the number of entries
in the exception table.

@item 
gh-93533@footnote{https://github.com/python/cpython/issues/93533}: Reduce the size of the inline cache for @code{LOAD_METHOD} by 2
bytes.

@item 
gh-93444@footnote{https://github.com/python/cpython/issues/93444}: Removed redundant fields from the compiler's basicblock struct:
@code{b_nofallthrough}, @code{b_exit}, @code{b_return}. They can be easily
calculated from the opcode of the last instruction of the block.

@item 
gh-93429@footnote{https://github.com/python/cpython/issues/93429}: @code{LOAD_METHOD} instruction has been removed. It was merged back
into @code{LOAD_ATTR}.

@item 
gh-93418@footnote{https://github.com/python/cpython/issues/93418}: Fixed an assert where an f-string has an equal sign '='
following an expression, but there's no trailing brace. For example,
f"@{i=".

@item 
gh-93382@footnote{https://github.com/python/cpython/issues/93382}: Cache the result of @ref{762,,PyCode_GetCode()} function to restore
the `O'(1) lookup of the @code{co_code} attribute.

@item 
gh-93359@footnote{https://github.com/python/cpython/issues/93359}: Ensure that custom @ref{8,,ast} nodes without explicit end
positions can be compiled. Patch by Pablo Galindo.

@item 
gh-93356@footnote{https://github.com/python/cpython/issues/93356}: Code for exception handlers is emitted at the end of the code
unit's bytecode. This avoids one jump when no exception is raised.

@item 
gh-93354@footnote{https://github.com/python/cpython/issues/93354}: Use exponential backoff for specialization counters in the
interpreter. Can reduce the number of failed specializations significantly
and avoid slowdown for those parts of a program that are not suitable for
specialization.

@item 
gh-93283@footnote{https://github.com/python/cpython/issues/93283}: Improve error message for invalid syntax of conversion character
in f-string expressions.

@item 
gh-93345@footnote{https://github.com/python/cpython/issues/93345}: Fix a crash in substitution of a @code{TypeVar} in nested generic
alias after @code{TypeVarTuple}.

@item 
gh-93223@footnote{https://github.com/python/cpython/issues/93223}: When a bytecode instruction jumps to an unconditional jump
instruction, the first instruction can often be optimized to target the
unconditional jump's target directly. For tracing reasons, this would
previously only occur if both instructions have the same line number. This
also now occurs if the unconditional jump is artificial, i.e., if it has
no associated line number.

@item 
gh-84694@footnote{https://github.com/python/cpython/issues/84694}: The @code{--experimental-isolated-subinterpreters} configure option
and @code{EXPERIMENTAL_ISOLATED_SUBINTERPRETERS} macro have been removed.

@item 
gh-91924@footnote{https://github.com/python/cpython/issues/91924}: Fix @code{__lltrace__} debug feature if the stdout encoding is not
UTF-8. Patch by Victor Stinner.

@item 
gh-93040@footnote{https://github.com/python/cpython/issues/93040}: Wraps unused parameters in @code{Objects/obmalloc.c} with
@code{Py_UNUSED}.

@item 
gh-93143@footnote{https://github.com/python/cpython/issues/93143}: Avoid @code{NULL} checks for uninitialized local variables by
determining at compile time which variables must be initialized.

@item 
gh-93061@footnote{https://github.com/python/cpython/issues/93061}: Backward jumps after @code{async for} loops are no longer given
dubious line numbers.

@item 
gh-93065@footnote{https://github.com/python/cpython/issues/93065}: Fix contextvars HAMT implementation to handle iteration over
deep trees.

The bug was discovered and fixed by Eli Libman. See
MagicStack/immutables#84@footnote{https://github.com/MagicStack/immutables/issues/84} for more details.

@item 
gh-93012@footnote{https://github.com/python/cpython/issues/93012}: Added the new function @ref{53b,,PyType_FromMetaclass()}, which
generalizes the existing @ref{53c,,PyType_FromModuleAndSpec()} using an
additional metaclass argument. This is useful for language binding tools,
where it can be used to intercept type-related operations like subclassing
or static attribute access by specifying a metaclass with custom slots.

Importantly, @ref{53b,,PyType_FromMetaclass()} is available in the Limited
API, which provides a path towards migrating more binding tools onto the
Stable ABI.

@item 
gh-93021@footnote{https://github.com/python/cpython/issues/93021}: Fix the @code{__text_signature__} for @code{__get__()} methods
implemented in C. Patch by Jelle Zijlstra.

@item 
gh-89914@footnote{https://github.com/python/cpython/issues/89914}: The operand of the @code{YIELD_VALUE} instruction is set to the
stack depth. This is done to help frame handling on @code{yield} and may
assist debuggers.

@item 
gh-92955@footnote{https://github.com/python/cpython/issues/92955}: Fix memory leak in code object's lines and positions iterators
as they were not finalized at exit. Patch by Kumar Aditya.

@item 
gh-92930@footnote{https://github.com/python/cpython/issues/92930}: Fixed a crash in @code{_pickle.c} from mutating collections during
@code{__reduce__} or @code{persistent_id}.

@item 
gh-90690@footnote{https://github.com/python/cpython/issues/90690}: The PRECALL instruction has been removed. It offered only a
small advantage for specialization and is not needed in the vast majority
of cases.

@item 
gh-92914@footnote{https://github.com/python/cpython/issues/92914}: Always round the allocated size for lists up to the nearest even
number.

@item 
gh-92858@footnote{https://github.com/python/cpython/issues/92858}: Improve error message for some suites with syntax error before
':'

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: Decrease default recursion limit on WASI to address limited call
stack size.

@item 
gh-92804@footnote{https://github.com/python/cpython/issues/92804}: Fix memory leak in @code{memoryview} iterator as it was not
finalized at exit. Patch by Kumar Aditya.

@item 
gh-92777@footnote{https://github.com/python/cpython/issues/92777}: Specialize @code{LOAD_METHOD} for objects with lazy dictionaries.
Patch by Ken Jin.

@item 
gh-92658@footnote{https://github.com/python/cpython/issues/92658}: Add support for connecting and binding to Hyper-V sockets on
Windows Hyper-V hosts and guests.

@item 
gh-92236@footnote{https://github.com/python/cpython/issues/92236}: Remove spurious "LINE" event when starting a generator or
coroutine, visible tracing functions implemented in C.

@item 
gh-91102@footnote{https://github.com/python/cpython/issues/91102}: @code{_warnings.warn_explicit()} is ported to Argument Clinic.

@item 
gh-92619@footnote{https://github.com/python/cpython/issues/92619}: Make the compiler duplicate an exit block only if none of its
instructions have a lineno (previously only the first instruction in the
block was checked, leading to unnecessarily duplicated blocks).

@item 
gh-88750@footnote{https://github.com/python/cpython/issues/88750}: The deprecated debug build only @code{PYTHONTHREADDEBUG}
environment variable no longer does anything.

@item 
gh-92261@footnote{https://github.com/python/cpython/issues/92261}: Fix hang when trying to iterate over a @code{typing.Union}.

@item 
gh-91432@footnote{https://github.com/python/cpython/issues/91432}: Specialized the @ref{16df,,FOR_ITER} opcode using the PEP 659
machinery

@item 
gh-91399@footnote{https://github.com/python/cpython/issues/91399}: Removed duplicate '@{0, 0, 0, 0, 0, 0@}' entry in
'Objects/unicodetype_db.h'.

@item 
gh-91578@footnote{https://github.com/python/cpython/issues/91578}: Updates the error message for abstract class.

@item 
bpo-47091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47091}: Improve performance of repetition of @ref{5fc,,list} and
@ref{366,,tuple} by using @code{memcpy} to copy data and performing the
reference increments in one step.

@item 
bpo-46142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46142}: Make @code{--help} output shorter by moving some info to the new
@code{--help-env} and @code{--help-xoptions} command-line options. Also add
@code{--help-all} option to print complete usage.

@item 
bpo-42316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42316}: Document some places where an assignment expression needs
parentheses.
@end itemize

@node Library<23>,Documentation<18>,Core and Builtins<24>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id189}@anchor{1750}
@subsubsection Library



@itemize -

@item 
gh-89237@footnote{https://github.com/python/cpython/issues/89237}: Fix hang on Windows in @code{subprocess.wait_closed()} in
@ref{a,,asyncio} with @ref{5f4,,ProactorEventLoop}. Patch by Kumar
Aditya.

@item 
gh-97928@footnote{https://github.com/python/cpython/issues/97928}: @code{tkinter.Text.count()} raises now an exception for options
starting with "-" instead of silently ignoring them.

@item 
gh-98393@footnote{https://github.com/python/cpython/issues/98393}: The @ref{a0,,os} module no longer accepts bytes-like paths, like
@ref{528,,bytearray} and @ref{452,,memoryview} types: only the exact
@ref{1bd,,bytes} type is accepted for bytes strings. Patch by Victor
Stinner.

@item 
gh-98363@footnote{https://github.com/python/cpython/issues/98363}: Added itertools.batched() to batch data into lists of a given
length with the last list possibly being shorter than the others.

@item 
gh-98331@footnote{https://github.com/python/cpython/issues/98331}: Update the bundled copies of pip and setuptools to versions 22.3
and 65.5.0 respectively.

@item 
gh-98307@footnote{https://github.com/python/cpython/issues/98307}: A @ref{646,,createSocket()} method
was added to @ref{647,,SysLogHandler}.

@item 
gh-96035@footnote{https://github.com/python/cpython/issues/96035}: Fix bug in @ref{302,,urllib.parse.urlparse()} that causes certain
port numbers containing whitespace, underscores, plus and minus signs, or
non-ASCII digits to be incorrectly accepted.

@item 
gh-98257@footnote{https://github.com/python/cpython/issues/98257}: Make @ref{14b5,,sys.setprofile()} and @ref{14b6,,sys.settrace()} functions
reentrant. They can no long fail with: @code{RuntimeError("Cannot install a
trace function while another trace function is being installed")}. Patch
by Victor Stinner.

@item 
gh-98251@footnote{https://github.com/python/cpython/issues/98251}: Allow @ref{110,,venv} to pass along @code{PYTHON*} variables to
@code{ensurepip} and @code{pip} when they do not impact path resolution

@item 
gh-94597@footnote{https://github.com/python/cpython/issues/94597}: Deprecated
@ref{2be,,asyncio.AbstractEventLoopPolicy.get_child_watcher()} and
@ref{2bd,,asyncio.AbstractEventLoopPolicy.set_child_watcher()} methods to be
removed in Python 3.14. Patch by Kumar Aditya.

@item 
gh-98178@footnote{https://github.com/python/cpython/issues/98178}: On macOS, fix a crash in @ref{52b,,syslog.syslog()} in multi-threaded
applications. On macOS, the libc @code{syslog()} function is not thread-safe,
so @ref{52b,,syslog.syslog()} no longer releases the GIL to call it. Patch by
Victor Stinner.

@item 
gh-44098@footnote{https://github.com/python/cpython/issues/44098}: Release the GIL when creating @ref{208,,mmap.mmap} objects on
Unix.

@item 
gh-87730@footnote{https://github.com/python/cpython/issues/87730}: Wrap network errors consistently in urllib FTP support, so the
test suite doesn't fail when a network is available but the public
internet is not reachable.

@item 
gh-94597@footnote{https://github.com/python/cpython/issues/94597}: The child watcher classes
@ref{2b7,,MultiLoopChildWatcher},
@ref{2b8,,FastChildWatcher} and @ref{2ba,,SafeChildWatcher}
are deprecated and will be removed in Python 3.14. Patch by Kumar Aditya.

@item 
gh-98023@footnote{https://github.com/python/cpython/issues/98023}: Change default child watcher to
@ref{463,,PidfdChildWatcher} on Linux systems which supports it.
Patch by Kumar Aditya.

@item 
gh-90985@footnote{https://github.com/python/cpython/issues/90985}: Earlier in 3.11 we deprecated
@code{asyncio.Task.cancel("message")}. We realized we were too harsh, and
have undeprecated it.

@item 
gh-65961@footnote{https://github.com/python/cpython/issues/65961}: Do not rely solely on @code{__cached__} on modules; code will also
support @code{__spec__.cached}.

@item 
gh-97646@footnote{https://github.com/python/cpython/issues/97646}: Replace deprecated @code{application/javascript} with
@code{text/javascript} in @ref{8e,,mimetypes}. See 
@geindex RFC; RFC 9239
RFC 9239@footnote{https://datatracker.ietf.org/doc/html/rfc9239.html}. Patch by Noam
Cohen.

@item 
gh-97930@footnote{https://github.com/python/cpython/issues/97930}: Apply changes from importlib_resources 5.8 and 5.9:
@code{Traversable.joinpath} provides a concrete implementation. @code{as_file}
now supports directories of resources.

@item 
gh-97850@footnote{https://github.com/python/cpython/issues/97850}: Remove deprecated @code{importlib.util.set_loader()} and
@code{importlib.util.module_for_loader()} from @ref{7c,,importlib.util}.

@item 
gh-97837@footnote{https://github.com/python/cpython/issues/97837}: Change deprecate warning message in @ref{105,,unittest} from

@code{It is deprecated to return a value!=None}

to

@code{It is deprecated to return a value that is not None from a test case}

@item 
gh-97825@footnote{https://github.com/python/cpython/issues/97825}: Fixes @ref{343,,AttributeError} when @ref{fac,,subprocess.check_output()}
is used with argument @code{input=None} and either of the arguments
`encoding' or `errors' are used.

@item 
gh-97008@footnote{https://github.com/python/cpython/issues/97008}: @ref{428,,NameError} and @ref{343,,AttributeError} spelling suggestions
provided since gh-82711@footnote{https://github.com/python/cpython/issues/82711} are now also emitted by the pure Python
@ref{fd,,traceback} module. Tests for those suggestions now exercise both
implementations to ensure they are equivalent. Patch by Carl Friedrich
Bolz-Tereick and Łukasz Langa.

@item 
gh-97799@footnote{https://github.com/python/cpython/issues/97799}: @code{dataclass} now uses @ref{7fd,,inspect.get_annotations()} to
examine the annotations on class objects.

@item 
gh-97781@footnote{https://github.com/python/cpython/issues/97781}: Removed deprecated interfaces in @code{importlib.metadata} (entry
points accessed as dictionary, implicit dictionary construction of
sequence of @code{EntryPoint} objects, mutablility of @code{EntryPoints} result,
access of entry point by index). @code{entry_points} now has a simpler, more
straightforward API (returning @code{EntryPoints}).

@item 
gh-96827@footnote{https://github.com/python/cpython/issues/96827}: Avoid spurious tracebacks from @ref{a,,asyncio} when default
executor cleanup is delayed until after the event loop is closed (e.g. as
the result of a keyboard interrupt).

@item 
gh-95534@footnote{https://github.com/python/cpython/issues/95534}: @code{gzip.GzipFile.read()} reads 10% faster.

@item 
gh-97592@footnote{https://github.com/python/cpython/issues/97592}: Avoid a crash in the C version of
@ref{152b,,asyncio.Future.remove_done_callback()} when an evil argument is
passed.

@item 
gh-97639@footnote{https://github.com/python/cpython/issues/97639}: Remove @code{tokenize.NL} check from @ref{dc,,tabnanny}.

@item 
gh-97545@footnote{https://github.com/python/cpython/issues/97545}: Make Semaphore run faster.

@item 
gh-73588@footnote{https://github.com/python/cpython/issues/73588}: Fix generation of the default name of
@code{tkinter.Checkbutton}. Previously, checkbuttons in different parent
widgets could have the same short name and share the same state if
arguments "name" and "variable" are not specified. Now they are globally
unique.

@item 
gh-96865@footnote{https://github.com/python/cpython/issues/96865}: fix Flag to use boundary CONFORM

This restores previous Flag behavior of allowing flags with non-sequential
values to be combined; e.g.

class Skip(Flag):         TWO = 2         EIGHT = 8

Skip.TWO | Skip.EIGHT -> <Skip.TWO|EIGHT: 10>

@item 
gh-97005@footnote{https://github.com/python/cpython/issues/97005}: Update bundled libexpat to 2.4.9

@item 
gh-85760@footnote{https://github.com/python/cpython/issues/85760}: Fix race condition in @ref{a,,asyncio} where
@ref{1751,,process_exited()} called before the
@ref{1752,,pipe_data_received()} leading to
inconsistent output. Patch by Kumar Aditya.

@item 
gh-96704@footnote{https://github.com/python/cpython/issues/96704}: Pass the correct @code{contextvars.Context} when a @code{asyncio}
exception handler is called on behalf of a task or callback handle. This
adds a new @code{Task} method, @code{get_context}, and also a new @code{Handle}
method with the same name. If this method is not found on a task object
(perhaps because it is a third-party library that does not yet provide
this method), the context prevailing at the time the exception handler is
called is used.

@item 
gh-96819@footnote{https://github.com/python/cpython/issues/96819}: Fixed check in @code{multiprocessing.resource_tracker} that
guarantees that the length of a write to a pipe is not greater than
@code{PIPE_BUF}.

@item 
gh-95865@footnote{https://github.com/python/cpython/issues/95865}: Reduce @ref{1753,,urllib.parse.quote_from_bytes()} memory use on large
values.

Contributed by Dennis Sweeney.

@item 
gh-96741@footnote{https://github.com/python/cpython/issues/96741}: Corrected type annotation for dataclass attribute
@code{pstats.FunctionProfile.ncalls} to be @code{str}.

@item 
gh-96734@footnote{https://github.com/python/cpython/issues/96734}: Update @ref{104,,unicodedata} database to Unicode 15.0.0.

@item 
gh-96735@footnote{https://github.com/python/cpython/issues/96735}: Fix undefined behaviour in @ref{1754,,struct.unpack()}.

@item 
gh-46412@footnote{https://github.com/python/cpython/issues/46412}: Improve performance of @code{bool(db)} for large ndb/gdb databases.
Previously this would call @code{len(db)} which would iterate over all keys
-- the answer (empty or not) is known after the first key.

@item 
gh-96652@footnote{https://github.com/python/cpython/issues/96652}: Fix the faulthandler implementation of
@code{faulthandler.register(signal, chain=True)} if the @code{sigaction()}
function is not available: don't call the previous signal handler if it's
NULL. Patch by Victor Stinner.

@item 
gh-68163@footnote{https://github.com/python/cpython/issues/68163}: Correct conversion of @ref{129c,,numbers.Rational}'s to
@ref{2eb,,float}.

@item 
gh-96538@footnote{https://github.com/python/cpython/issues/96538}: Speed up @code{bisect.bisect()} functions by taking advantage of
type-stability.

@item 
gh-96465@footnote{https://github.com/python/cpython/issues/96465}: Fraction hashes are now cached.

@item 
gh-96079@footnote{https://github.com/python/cpython/issues/96079}: In @ref{103,,typing}, fix missing field @code{name} and incorrect
@code{__module__} in _AnnotatedAlias.

@item 
gh-96415@footnote{https://github.com/python/cpython/issues/96415}: Remove @code{types._cell_factory} from module namespace.

@item 
gh-95987@footnote{https://github.com/python/cpython/issues/95987}: Fix @code{repr} of @code{Any} subclasses.

@item 
gh-96388@footnote{https://github.com/python/cpython/issues/96388}: Work around missing socket functions in
@ref{d8e,,socket}'s @code{__repr__}.

@item 
gh-96385@footnote{https://github.com/python/cpython/issues/96385}: Fix @code{TypeVarTuple.__typing_prepare_subst__}. @code{TypeError} was
not raised when using more than one @code{TypeVarTuple}, like @code{[*T, *V]} in
type alias substitutions.

@item 
gh-96142@footnote{https://github.com/python/cpython/issues/96142}: Add @code{match_args}, @code{kw_only}, @code{slots}, and @code{weakref_slot}
to @code{_DataclassParams}.

@item 
gh-96073@footnote{https://github.com/python/cpython/issues/96073}: In @ref{7d,,inspect}, fix overeager replacement of "@code{typing.}" in
formatting annotations.

@item 
gh-89258@footnote{https://github.com/python/cpython/issues/89258}: Added a @ref{1755,,getChildren()} method to
@ref{b3d,,logging.Logger}, to get the immediate child loggers of a logger.

@item 
gh-96346@footnote{https://github.com/python/cpython/issues/96346}: Use double caching for compiled RE patterns.

@item 
gh-96349@footnote{https://github.com/python/cpython/issues/96349}: Fixed a minor performance regression in
@code{threading.Event.__init__()}

@item 
gh-90467@footnote{https://github.com/python/cpython/issues/90467}: Fix @code{asyncio.streams.StreamReaderProtocol} to keep a
strong reference to the created task, so that it's not garbage collected

@item 
gh-96172@footnote{https://github.com/python/cpython/issues/96172}: Fix a bug in @code{unicodedata}: @code{east_asian_width} used to
return the wrong value for unassigned characters; and for yet unassigned,
but reserved characters.

@item 
gh-96159@footnote{https://github.com/python/cpython/issues/96159}: Fix a performance regression in logging
TimedRotatingFileHandler. Only check for special files when the rollover
time has passed.

@item 
gh-96175@footnote{https://github.com/python/cpython/issues/96175}: Fix unused @code{localName} parameter in the @code{Attr} class in
@ref{121,,xml.dom.minidom}.

@item 
gh-96145@footnote{https://github.com/python/cpython/issues/96145}: Add AttrDict to JSON module for use with object_hook.

@item 
gh-96052@footnote{https://github.com/python/cpython/issues/96052}: Fix handling compiler warnings (SyntaxWarning and
DeprecationWarning) in @ref{1756,,codeop.compile_command()} when checking for
incomplete input. Previously it emitted warnings and raised a SyntaxError.
Now it always returns @code{None} for incomplete input without emitting any
warnings.

@item 
gh-96125@footnote{https://github.com/python/cpython/issues/96125}: Fix incorrect condition that causes @code{sys.thread_info.name} to
be wrong on pthread platforms.

@item 
gh-96019@footnote{https://github.com/python/cpython/issues/96019}: Fix a bug in the @code{makeunicodedata.py} script leading to about
13 KiB of space saving in the @code{unicodedata} module, specifically the
character decomposition data.

@item 
gh-95463@footnote{https://github.com/python/cpython/issues/95463}: Remove an incompatible change from bpo-28080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28080} that caused a
regression that ignored the utf8 in @code{ZipInfo.flag_bits}. Patch by Pablo
Galindo.

@item 
gh-69142@footnote{https://github.com/python/cpython/issues/69142}: Add @code{%:z} strftime format code (generates tzoffset with colons
as separator), see @ref{1757,,strftime() and strptime() Behavior}.

@item 
gh-95899@footnote{https://github.com/python/cpython/issues/95899}: Fix @ref{5eb,,asyncio.Runner} to call
@ref{1758,,asyncio.set_event_loop()} only once to avoid calling
@ref{1759,,attach_loop()} multiple times on child
watchers. Patch by Kumar Aditya.

@item 
gh-95736@footnote{https://github.com/python/cpython/issues/95736}: Fix @ref{301,,unittest.IsolatedAsyncioTestCase} to set event loop
before calling setup functions. Patch by Kumar Aditya.

@item 
gh-95865@footnote{https://github.com/python/cpython/issues/95865}: Speed up @ref{1753,,urllib.parse.quote_from_bytes()} by replacing a
list comprehension with @code{map()}.

@item 
gh-95861@footnote{https://github.com/python/cpython/issues/95861}: Add support for computing Spearman's correlation coefficient to
the existing statistics.correlation() function.

@item 
gh-95804@footnote{https://github.com/python/cpython/issues/95804}: Fix @code{logging} shutdown handler so it respects
@code{MemoryHandler.flushOnClose}.

@item 
gh-95704@footnote{https://github.com/python/cpython/issues/95704}: When a task catches @ref{1b6,,asyncio.CancelledError} and raises
some other error, the other error should generally not silently be
suppressed.

@item 
gh-95149@footnote{https://github.com/python/cpython/issues/95149}: The @ref{8ed,,HTTPStatus} enum offers a couple
of properties to indicate the HTTP status category e.g.
@code{HTTPStatus.OK.is_success}.

@item 
gh-95609@footnote{https://github.com/python/cpython/issues/95609}: Update bundled pip to 22.2.2.

@item 
gh-95289@footnote{https://github.com/python/cpython/issues/95289}: Fix @ref{1b3,,asyncio.TaskGroup} to propagate exception when
@ref{1b6,,asyncio.CancelledError} was replaced with another exception by a
context manager. Patch by Kumar Aditya and Guido van Rossum.

@item 
gh-94909@footnote{https://github.com/python/cpython/issues/94909}: Fix incorrect joining of relative Windows paths with drives in
@ref{490,,pathlib.PurePath} initializer.

@item 
gh-95385@footnote{https://github.com/python/cpython/issues/95385}: Faster @code{json.dumps()} when sorting of keys is not requested
(default).

@item 
gh-83901@footnote{https://github.com/python/cpython/issues/83901}: Improve @ref{15a2,,Signature.bind} error
message for missing keyword-only arguments.

@item 
gh-95339@footnote{https://github.com/python/cpython/issues/95339}: Update bundled pip to 22.2.1.

@item 
gh-95045@footnote{https://github.com/python/cpython/issues/95045}: Fix GC crash when deallocating @code{_lsprof.Profiler} by
untracking it before calling any callbacks. Patch by Kumar Aditya.

@item 
gh-95231@footnote{https://github.com/python/cpython/issues/95231}: Fail gracefully if @ref{175a,,EPERM} or
@ref{175b,,ENOSYS} is raised when loading @code{crypt} methods. This
may happen when trying to load @code{MD5} on a Linux kernel with @abbr{FIPS,Federal Information Processing Standard} enabled.

@item 
gh-95097@footnote{https://github.com/python/cpython/issues/95097}: Fix @ref{466,,asyncio.run()} for @ref{4c2,,asyncio.Task}
implementations without @ref{1b9,,uncancel()} method. Patch by
Kumar Aditya.

@item 
gh-95087@footnote{https://github.com/python/cpython/issues/95087}: Fix IndexError in parsing invalid date in the @ref{3b,,email}
module.

@item 
gh-95199@footnote{https://github.com/python/cpython/issues/95199}: Upgrade bundled setuptools to 63.2.0.

@item 
gh-95194@footnote{https://github.com/python/cpython/issues/95194}: Upgrade bundled pip to 22.2.

@item 
gh-93899@footnote{https://github.com/python/cpython/issues/93899}: Fix check for existence of @ref{175c,,os.EFD_CLOEXEC},
@ref{175d,,os.EFD_NONBLOCK} and @ref{175e,,os.EFD_SEMAPHORE} flags on older
kernel versions where these flags are not present. Patch by Kumar Aditya.

@item 
gh-95166@footnote{https://github.com/python/cpython/issues/95166}: Fix @ref{dd1,,concurrent.futures.Executor.map()} to cancel the
currently waiting on future on an error - e.g. TimeoutError or
KeyboardInterrupt.

@item 
gh-95132@footnote{https://github.com/python/cpython/issues/95132}: Fix a @ref{ce,,sqlite3} regression where @code{*args} and @code{**kwds}
were incorrectly relayed from @ref{2a5,,connect()} to the
@ref{242,,Connection} factory. The regression was introduced in
3.11a1 with PR 24421 (gh-85128@footnote{https://github.com/python/cpython/issues/85128}). Patch by Erlend E. Aasland.

@item 
gh-93157@footnote{https://github.com/python/cpython/issues/93157}: Fix @ref{5a,,fileinput} module didn't support @code{errors} option
when @code{inplace} is true.

@item 
gh-91212@footnote{https://github.com/python/cpython/issues/91212}: Fixed flickering of the turtle window when the tracer is turned
off. Patch by Shin-myoung-serp.

@item 
gh-95077@footnote{https://github.com/python/cpython/issues/95077}: Add deprecation warning for enum @code{member.member} access (e.g.
@code{Color.RED.BLUE}). Remove @code{EnumMeta.__getattr__}.

@item 
gh-95109@footnote{https://github.com/python/cpython/issues/95109}: Ensure that timeouts scheduled with @ref{1654,,asyncio.Timeout}
that have already expired are delivered promptly.

@item 
gh-95105@footnote{https://github.com/python/cpython/issues/95105}: @code{wsgiref.types.InputStream.__iter__()} should return
@code{Iterator[bytes]}, not @code{Iterable[bytes]}. Patch by Shantanu Jain.

@item 
gh-95066@footnote{https://github.com/python/cpython/issues/95066}: Replaced assert with exception in @ref{1a6,,ast.parse()}, when
@code{feature_version} has an invalid major version. Patch by Shantanu Jain.

@item 
gh-77617@footnote{https://github.com/python/cpython/issues/77617}: Add @ref{ce,,sqlite3} @ref{42a,,command-line interface}.
Patch by Erlend Aasland.

@item 
gh-95005@footnote{https://github.com/python/cpython/issues/95005}: Replace _PyAccu with _PyUnicodeWriter in
JSON encoder and StringIO and remove the _PyAccu implementation.

@item 
gh-90085@footnote{https://github.com/python/cpython/issues/90085}: Remove @code{-c/--clock} and @code{-t/--time} CLI options of
@ref{ee,,timeit}. The options had been deprecated since Python 3.3 and the
functionality was removed in Python 3.7. Patch by Shantanu Jain.

@item 
gh-94857@footnote{https://github.com/python/cpython/issues/94857}: Fix refleak in @code{_io.TextIOWrapper.reconfigure}. Patch by Kumar
Aditya.

@item 
gh-94821@footnote{https://github.com/python/cpython/issues/94821}: Fix binding of unix socket to empty address on Linux to use an
available address from the abstract namespace, instead of "0".

@item 
gh-94736@footnote{https://github.com/python/cpython/issues/94736}: Fix crash when deallocating an instance of a subclass of
@code{_multiprocessing.SemLock}. Patch by Kumar Aditya.

@item 
gh-81620@footnote{https://github.com/python/cpython/issues/81620}: Add random.binomialvariate().

@item 
gh-74116@footnote{https://github.com/python/cpython/issues/74116}: Allow @ref{173c,,asyncio.StreamWriter.drain()} to be awaited
concurrently by multiple tasks. Patch by Kumar Aditya.

@item 
gh-87822@footnote{https://github.com/python/cpython/issues/87822}: When called with @code{capture_locals=True}, the @ref{fd,,traceback}
module functions swallow exceptions raised from calls to @code{repr()} on
local variables of frames. This is in order to prioritize the original
exception over rendering errors.  An indication of the failure is printed
in place of the missing value.  (Patch by Simon-Martin Schroeder).

@item 
gh-88050@footnote{https://github.com/python/cpython/issues/88050}: Fix @ref{a,,asyncio} subprocess transport to kill process cleanly
when process is blocked and avoid @code{RuntimeError} when loop is closed.
Patch by Kumar Aditya.

@item 
gh-94637@footnote{https://github.com/python/cpython/issues/94637}: @code{SSLContext.set_default_verify_paths()} now releases the GIL
around @code{SSL_CTX_set_default_verify_paths} call. The function call
performs I/O and CPU intensive work.

@item 
gh-94309@footnote{https://github.com/python/cpython/issues/94309}: Deprecate aliases @ref{4dd,,typing.Hashable} and
@ref{4de,,typing.Sized}

@item 
gh-92546@footnote{https://github.com/python/cpython/issues/92546}: An undocumented @code{python -m pprint} benchmark is moved into
@code{pprint} suite of pyperformance. Patch by Oleg Iarygin.

@item 
gh-94607@footnote{https://github.com/python/cpython/issues/94607}: Fix subclassing complex generics with type variables in
@ref{103,,typing}. Previously an error message saying @code{Some type variables
... are not listed in Generic[...]} was shown. @ref{103,,typing} no longer
populates @code{__parameters__} with the @code{__parameters__} of a Python
class.

@item 
gh-94619@footnote{https://github.com/python/cpython/issues/94619}: Remove the long-deprecated @code{module_repr()} from
@ref{76,,importlib}.

@item 
gh-93910@footnote{https://github.com/python/cpython/issues/93910}: The ability to access the other values of an enum on an enum
(e.g. @code{Color.RED.BLUE}) has been restored in order to fix a performance
regression.

@item 
gh-93896@footnote{https://github.com/python/cpython/issues/93896}: Fix @ref{466,,asyncio.run()} and
@ref{301,,unittest.IsolatedAsyncioTestCase} to always the set event loop as
it was done in Python 3.10 and earlier. Patch by Kumar Aditya.

@item 
gh-94343@footnote{https://github.com/python/cpython/issues/94343}: Allow setting the attributes of @code{reprlib.Repr} during object
initialization

@item 
gh-94382@footnote{https://github.com/python/cpython/issues/94382}: Port static types of @code{_multiprocessing} module to heap types.
Patch by Kumar Aditya.

@item 
gh-78724@footnote{https://github.com/python/cpython/issues/78724}: Fix crash in @ref{163a,,struct.Struct} when it was not completely
initialized by initializing it in @ref{56c,,__new__()}.  Patch by Kumar
Aditya.

@item 
gh-94510@footnote{https://github.com/python/cpython/issues/94510}: Re-entrant calls to @ref{14b5,,sys.setprofile()} and
@ref{14b6,,sys.settrace()} now raise @ref{193,,RuntimeError}. Patch by Pablo
Galindo.

@item 
gh-92336@footnote{https://github.com/python/cpython/issues/92336}: Fix bug where @ref{e10,,linecache.getline()} fails on bad files with
@ref{a01,,UnicodeDecodeError} or @ref{18b,,SyntaxError}. It now returns an empty
string as per the documentation.

@item 
gh-94398@footnote{https://github.com/python/cpython/issues/94398}: Once a @ref{1b3,,asyncio.TaskGroup} has started shutting down
(i.e., at least one task has failed and the task group has started
cancelling the remaining tasks), it should not be possible to add new
tasks to the task group.

@item 
gh-94383@footnote{https://github.com/python/cpython/issues/94383}: @code{xml.etree}: Remove the @code{ElementTree.Element.copy()}
method of the pure Python implementation, deprecated in Python 3.10, use
the @ref{51d,,copy.copy()} function instead. The C implementation of
@code{xml.etree} has no @code{copy()} method, only a @code{__copy__()} method.
Patch by Victor Stinner.

@item 
gh-94379@footnote{https://github.com/python/cpython/issues/94379}: @ref{131,,zipimport}: Remove @code{find_loader()} and @code{find_module()}
methods, deprecated in Python 3.10: use the @code{find_spec()} method
instead. See 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} for the rationale. Patch by Victor Stinner.

@item 
gh-94352@footnote{https://github.com/python/cpython/issues/94352}: @ref{526,,shlex.split()}: Passing @code{None} for `s' argument now
raises an exception, rather than reading @ref{527,,sys.stdin}. The feature
was deprecated in Python 3.9. Patch by Victor Stinner.

@item 
gh-94318@footnote{https://github.com/python/cpython/issues/94318}: Strip trailing spaces in @ref{b4,,pydoc} text output.

@item 
gh-89988@footnote{https://github.com/python/cpython/issues/89988}: Fix memory leak in @ref{a0c,,pickle.Pickler} when looking up
@code{dispatch_table}. Patch by Kumar Aditya.

@item 
gh-90016@footnote{https://github.com/python/cpython/issues/90016}: Deprecate @ref{ce,,sqlite3} @ref{4d9,,default adapters and converters}. Patch by Erlend E. Aasland.

@item 
gh-94254@footnote{https://github.com/python/cpython/issues/94254}: Fixed types of @ref{d4,,struct} module to be immutable. Patch by
Kumar Aditya.

@item 
gh-93259@footnote{https://github.com/python/cpython/issues/93259}: Now raise @code{ValueError} when @code{None} or an empty string are
passed to @code{Distribution.from_name} (and other callers).

@item 
gh-74696@footnote{https://github.com/python/cpython/issues/74696}: @ref{49c,,shutil.make_archive()} now passes the `root_dir' argument
to custom archivers which support it.

@item 
gh-94216@footnote{https://github.com/python/cpython/issues/94216}: The @ref{38,,dis} module now has the opcodes for pseudo
instructions (those which are used by the compiler during code generation
but then removed or replaced by real opcodes before the final bytecode is
emitted).

@item 
gh-93096@footnote{https://github.com/python/cpython/issues/93096}: Removed undocumented @code{python -m codecs}. Use @code{python -m
unittest test.test_codecs.EncodedFileTest} instead.

@item 
gh-94207@footnote{https://github.com/python/cpython/issues/94207}: Made @code{_struct.Struct} GC-tracked in order to fix a
reference leak in the @code{_struct} module.

@item 
gh-93096@footnote{https://github.com/python/cpython/issues/93096}: Removed undocumented @code{-t} argument of @code{python -m base64}.
Use @code{python -m unittest
test.test_base64.LegacyBase64TestCase.test_encodebytes} instead.

@item 
gh-94226@footnote{https://github.com/python/cpython/issues/94226}: Remove the @code{locale.format()} function, deprecated in Python
3.7: use @ref{508,,locale.format_string()} instead. Patch by Victor Stinner.

@item 
gh-94199@footnote{https://github.com/python/cpython/issues/94199}: Remove the @code{ssl.match_hostname()} function. The
@code{ssl.match_hostname()} was deprecated in Python 3.7. OpenSSL performs
hostname matching since Python 3.7, Python no longer uses the
@code{ssl.match_hostname()} function. Patch by Victor Stinner.

@item 
gh-94214@footnote{https://github.com/python/cpython/issues/94214}: Document the @code{context} object used in the @code{venv.EnvBuilder}
class, and add the new environment's library path to it.

@item 
gh-94199@footnote{https://github.com/python/cpython/issues/94199}: Remove the @code{ssl.wrap_socket()} function, deprecated in
Python 3.7: instead, create a @ref{291,,ssl.SSLContext} object and call its
@ref{50e,,ssl.SSLContext.wrap_socket} method. Any package that still uses
@code{ssl.wrap_socket()} is broken and insecure. The function neither sends
a SNI TLS extension nor validates server hostname. Code is subject to
@geindex Common Weakness Enumeration; CWE 295
CWE 295@footnote{https://cwe.mitre.org/data/definitions/295.html} Improper Certificate Validation. Patch by Victor Stinner.

@item 
gh-94199@footnote{https://github.com/python/cpython/issues/94199}: Remove the @code{ssl.RAND_pseudo_bytes()} function, deprecated in
Python 3.6: use @ref{50c,,os.urandom()} or @ref{50d,,ssl.RAND_bytes()} instead.
Patch by Victor Stinner.

@item 
gh-94199@footnote{https://github.com/python/cpython/issues/94199}: @ref{67,,hashlib}: Remove the pure Python implementation of
@ref{4f8,,hashlib.pbkdf2_hmac()}, deprecated in Python 3.10. Python 3.10 and
newer requires OpenSSL 1.1.1 (
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}): this OpenSSL version provides a
C implementation of @ref{4f8,,pbkdf2_hmac()} which is faster. Patch by
Victor Stinner.

@item 
gh-94196@footnote{https://github.com/python/cpython/issues/94196}: @ref{66,,gzip}: Remove the @code{filename} attribute of
@ref{410,,gzip.GzipFile}, deprecated since Python 2.6, use the
@ref{4f6,,name} attribute instead. In write mode, the
@code{filename} attribute added @code{'.gz'} file extension if it was not
present. Patch by Victor Stinner.

@item 
gh-94182@footnote{https://github.com/python/cpython/issues/94182}: run the @ref{463,,asyncio.PidfdChildWatcher} on the running loop,
this allows event loops to run subprocesses when there is no default event
loop running on the main thread

@item 
gh-94169@footnote{https://github.com/python/cpython/issues/94169}: Remove @code{io.OpenWrapper} and @code{_pyio.OpenWrapper}, deprecated
in Python 3.10: just use @ref{505,,open()} instead. The @ref{505,,open()}
(@ref{506,,io.open()}) function is a built-in function. Since Python 3.10,
@code{_pyio.open()} is also a static method. Patch by Victor Stinner.

@item 
gh-91742@footnote{https://github.com/python/cpython/issues/91742}: Fix @ref{a4,,pdb} crash after jump caused by a null pointer
dereference. Patch by Kumar Aditya.

@item 
gh-94101@footnote{https://github.com/python/cpython/issues/94101}: Manual instantiation of @ref{ccb,,ssl.SSLSession} objects is no
longer allowed as it lead to misconfigured instances that crashed the
interpreter when attributes where accessed on them.

@item 
gh-84753@footnote{https://github.com/python/cpython/issues/84753}: @ref{2e2,,inspect.iscoroutinefunction()},
@ref{175f,,inspect.isgeneratorfunction()}, and
@ref{1760,,inspect.isasyncgenfunction()} now properly return @code{True} for
duck-typed function-like objects like instances of
@ref{a39,,unittest.mock.AsyncMock}.

This makes @ref{2e2,,inspect.iscoroutinefunction()} consistent with the
behavior of @code{asyncio.iscoroutinefunction()}.  Patch by Mehdi ABAAKOUK.

@item 
gh-94028@footnote{https://github.com/python/cpython/issues/94028}: Fix a regression in the @ref{ce,,sqlite3} where statement objects
were not properly cleared and reset after use in cursor iters. The
regression was introduced by PR 27884 in Python 3.11a1. Patch by Erlend E.
Aasland.

@item 
gh-93973@footnote{https://github.com/python/cpython/issues/93973}: Add keyword argument @code{all_errors} to
@code{asyncio.create_connection} so that multiple connection errors can be
raised as an @code{ExceptionGroup}.

@item 
gh-93963@footnote{https://github.com/python/cpython/issues/93963}: Officially deprecate from @code{importlib.abc} classes moved to
@code{importlib.resources.abc}.

@item 
gh-93858@footnote{https://github.com/python/cpython/issues/93858}: Prevent error when activating venv in nested fish instances.

@item 
gh-93820@footnote{https://github.com/python/cpython/issues/93820}: Pickle @ref{60e,,enum.Flag} by name.

@item 
gh-93847@footnote{https://github.com/python/cpython/issues/93847}: Fix repr of enum of generic aliases.

@item 
gh-91404@footnote{https://github.com/python/cpython/issues/91404}: Revert the @ref{b8,,re} memory leak when a match is terminated by a
signal or memory allocation failure as the implemented fix caused a major
performance regression.

@item 
gh-83499@footnote{https://github.com/python/cpython/issues/83499}: Fix double closing of file description in @ref{df,,tempfile}.

@item 
gh-93820@footnote{https://github.com/python/cpython/issues/93820}: Fixed a regression when @ref{51d,,copy.copy()}-ing @ref{60e,,enum.Flag}
with multiple flag members.

@item 
gh-79512@footnote{https://github.com/python/cpython/issues/79512}: Fixed names and @code{__module__} value of @ref{113,,weakref} classes
@ref{1761,,ReferenceType}, @ref{1762,,ProxyType},
@ref{1763,,CallableProxyType}. It makes them pickleable.

@item 
gh-91389@footnote{https://github.com/python/cpython/issues/91389}: Fix an issue where @ref{38,,dis} utilities could report missing or
incorrect position information in the presence of @code{CACHE} entries.

@item 
gh-93626@footnote{https://github.com/python/cpython/issues/93626}: Set @code{__future__.annotations} to have a @code{None}
mandatoryRelease to indicate that it is currently 'TBD'.

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: Emscripten and WASI have no home directory and cannot provide
@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} user site directory.

@item 
gh-90494@footnote{https://github.com/python/cpython/issues/90494}: @ref{51d,,copy.copy()} and @ref{b5c,,copy.deepcopy()} now always raise a
TypeError if @code{__reduce__()} returns a tuple with length 6 instead of
silently ignore the 6th item or produce incorrect result.

@item 
gh-90549@footnote{https://github.com/python/cpython/issues/90549}: Fix a multiprocessing bug where a global named resource (such as
a semaphore) could leak when a child process is spawned (as opposed to
forked).

@item 
gh-93521@footnote{https://github.com/python/cpython/issues/93521}: Fixed a case where dataclasses would try to add @code{__weakref__}
into the @code{__slots__} for a dataclass that specified
@code{weakref_slot=True} when it was already defined in one of its bases.
This resulted in a @code{TypeError} upon the new class being created.

@item 
gh-79579@footnote{https://github.com/python/cpython/issues/79579}: @ref{ce,,sqlite3} now correctly detects DML queries with leading
comments. Patch by Erlend E. Aasland.

@item 
gh-93421@footnote{https://github.com/python/cpython/issues/93421}: Update @ref{1764,,sqlite3.Cursor.rowcount} when a DML statement has
run to completion. This fixes the row count for SQL queries like @code{UPDATE
... RETURNING}. Patch by Erlend E. Aasland.

@item 
gh-93475@footnote{https://github.com/python/cpython/issues/93475}: Expose @code{FICLONE} and @code{FICLONERANGE} constants in
@ref{58,,fcntl}. Patch by Illia Volochii.

@item 
gh-93370@footnote{https://github.com/python/cpython/issues/93370}: Deprecate @ref{2cd,,sqlite3.version} and
@ref{2ce,,sqlite3.version_info}.

@item 
gh-91810@footnote{https://github.com/python/cpython/issues/91810}: Suppress writing an XML declaration in open files in
@code{ElementTree.write()} with @code{encoding='unicode'} and
@code{xml_declaration=None}.

@item 
gh-91162@footnote{https://github.com/python/cpython/issues/91162}: Support splitting of unpacked arbitrary-length tuple over
@code{TypeVar} and @code{TypeVarTuple} parameters. For example:


@itemize *

@item 
@code{A[T, *Ts][*tuple[int, ...]]} -> @code{A[int, *tuple[int, ...]]}

@item 
@code{A[*Ts, T][*tuple[int, ...]]} -> @code{A[*tuple[int, ...], int]}
@end itemize

@item 
gh-93353@footnote{https://github.com/python/cpython/issues/93353}: Fix the @ref{477,,importlib.resources.as_file()} context manager to
remove the temporary file if destroyed late during Python finalization:
keep a local reference to the @ref{10d1,,os.remove()} function. Patch by Victor
Stinner.

@item 
gh-83658@footnote{https://github.com/python/cpython/issues/83658}: Make @code{multiprocessing.Pool} raise an exception if
@code{maxtasksperchild} is not @code{None} or a positive int.

@item 
gh-93312@footnote{https://github.com/python/cpython/issues/93312}: Add @ref{484,,os.PIDFD_NONBLOCK} flag to open a file descriptor
for a process with @ref{464,,os.pidfd_open()} in non-blocking mode. Patch by
Kumar Aditya.

@item 
gh-88123@footnote{https://github.com/python/cpython/issues/88123}: Implement @code{Enum.__contains__} that returns @code{True} or
@code{False} to replace the deprecated behaviour that would sometimes raise a
@ref{522,,TypeError}.

@item 
gh-93297@footnote{https://github.com/python/cpython/issues/93297}: Make asyncio task groups prevent child tasks from being GCed

@item 
gh-85308@footnote{https://github.com/python/cpython/issues/85308}: Changed @ref{523,,argparse.ArgumentParser} to use
@ref{525,,filesystem encoding and error handler} instead of default text
encoding to read arguments from file (e.g. @code{fromfile_prefix_chars}
option). This change affects Windows; argument file should be encoded with
UTF-8 instead of ANSI Codepage.

@item 
gh-93156@footnote{https://github.com/python/cpython/issues/93156}: Accessing the @ref{80a,,pathlib.PurePath.parents} sequence of an
absolute path using negative index values produced incorrect results.

@item 
gh-93162@footnote{https://github.com/python/cpython/issues/93162}: Add the ability for @ref{118d,,logging.config.dictConfig()} to
usefully configure @ref{1765,,QueueHandler} and
@ref{e19,,QueueListener} as a pair, and add
@ref{1766,,logging.getHandlerByName()} and @ref{1687,,logging.getHandlerNames()} APIs
to allow access to handlers by name.

@item 
gh-93243@footnote{https://github.com/python/cpython/issues/93243}: The @code{smtpd} module was removed per the schedule in
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

@item 
gh-92886@footnote{https://github.com/python/cpython/issues/92886}: Replace @code{assert} statements with @code{raise AssertionError()} in
@code{BaseHandler} so that the tested behaviour is maintained
running with optimizations @code{(-O)}.

@item 
gh-90155@footnote{https://github.com/python/cpython/issues/90155}: Fix broken @ref{a62,,asyncio.Semaphore} when acquire is cancelled.

@item 
gh-90817@footnote{https://github.com/python/cpython/issues/90817}: The @code{locale.resetlocale()} function is deprecated and will
be removed in Python 3.13. Use @code{locale.setlocale(locale.LC_ALL, "")}
instead. Patch by Victor Stinner.

@item 
gh-91513@footnote{https://github.com/python/cpython/issues/91513}: Added @code{taskName} attribute to @ref{86,,logging} module for use
with @ref{a,,asyncio} tasks.

@item 
gh-74696@footnote{https://github.com/python/cpython/issues/74696}: @ref{49c,,shutil.make_archive()} no longer temporarily changes the
current working directory during creation of standard @code{.zip} or tar
archives.

@item 
gh-92728@footnote{https://github.com/python/cpython/issues/92728}: The @code{re.template()} function and the corresponding
@code{re.TEMPLATE} and @code{re.T} flags are restored after they were
removed in 3.11.0b1, but they are now deprecated, so they might be removed
from Python 3.13.

@item 
gh-93033@footnote{https://github.com/python/cpython/issues/93033}: Search in some strings (platform dependent i.e [U+0xFFFF,
U+0x0100] on Windows or [U+0xFFFFFFFF, U+0x00010000] on Linux 64-bit) are
now up to 10 times faster.

@item 
gh-89973@footnote{https://github.com/python/cpython/issues/89973}: Fix @code{re.error} raised in @ref{5b,,fnmatch} if the pattern
contains a character range with upper bound lower than lower bound (e.g.
@code{[c-a]}). Now such ranges are interpreted as empty ranges.

@item 
gh-93044@footnote{https://github.com/python/cpython/issues/93044}: No longer convert the database argument of
@ref{2a5,,sqlite3.connect()} to bytes before passing it to the factory.

@item 
gh-93010@footnote{https://github.com/python/cpython/issues/93010}: In a very special case, the email package tried to append the
nonexistent @code{InvalidHeaderError} to the defect list. It should have been
@code{InvalidHeaderDefect}.

@item 
gh-92986@footnote{https://github.com/python/cpython/issues/92986}: Fix @ref{8d2,,ast.unparse()} when @code{ImportFrom.level} is @code{None}

@item 
gh-92932@footnote{https://github.com/python/cpython/issues/92932}: Now @ref{b22,,dis()} and @ref{1d6,,get_instructions()} handle
operand values for instructions prefixed by @code{EXTENDED_ARG_QUICK}. Patch
by Sam Gross and Donghee Na.

@item 
gh-92675@footnote{https://github.com/python/cpython/issues/92675}: Fix @code{venv.ensure_directories()} to accept
@ref{226,,pathlib.Path} arguments in addition to @ref{435,,str} paths. Patch
by David Foster.

@item 
gh-87901@footnote{https://github.com/python/cpython/issues/87901}: Removed the @code{encoding} argument from @ref{a75,,os.popen()} that was
added in 3.11b1.

@item 
gh-91922@footnote{https://github.com/python/cpython/issues/91922}: Fix function @code{sqlite.connect()} and the
@code{sqlite.Connection} constructor on non-UTF-8 locales. Also, they
now support bytes paths non-decodable with the current FS encoding.

@item 
gh-92869@footnote{https://github.com/python/cpython/issues/92869}: Added @ref{1767,,c_time_t} to @ref{2a,,ctypes}, which has the
same size as the @code{time_t} type in C.

@item 
gh-92839@footnote{https://github.com/python/cpython/issues/92839}: Fixed crash resulting from calling bisect.insort() or
bisect.insort_left() with the key argument not equal to @code{None}.

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: @ref{d5,,subprocess} now fails early on Emscripten and WASI
platforms to work around missing @ref{1768,,os.pipe()} on WASI.

@item 
gh-89325@footnote{https://github.com/python/cpython/issues/89325}: Removed many old deprecated @ref{105,,unittest} features:
@ref{437,,TestCase} method aliases, undocumented and broken
@ref{437,,TestCase} method @code{assertDictContainsSubset},
undocumented @ref{28c,,TestLoader.loadTestsFromModule} parameter `use_load_tests', and
an underscored alias of the @ref{51a,,TextTestResult} class.

@item 
gh-92734@footnote{https://github.com/python/cpython/issues/92734}: Allow multi-element reprs emitted by @ref{ba,,reprlib} to be
pretty-printed using configurable indentation.

@item 
gh-92671@footnote{https://github.com/python/cpython/issues/92671}: Fixed @ref{8d2,,ast.unparse()} for empty tuples in the assignment
target context.

@item 
gh-91581@footnote{https://github.com/python/cpython/issues/91581}: @ref{2f1,,utcfromtimestamp()} no longer attempts
to resolve @code{fold} in the pure Python implementation, since the fold is
never 1 in UTC. In addition to being slightly faster in the common case,
this also prevents some errors when the timestamp is close to
@ref{1769,,datetime.min}.  Patch by Paul Ganssle.

@item 
gh-86388@footnote{https://github.com/python/cpython/issues/86388}: Removed randrange() functionality deprecated since Python 3.10.
Formerly, randrange(10.0) losslessly converted to randrange(10). Now, it
raises a TypeError. Also, the exception raised for non-integral values
such as randrange(10.5) or randrange('10') has been changed from
ValueError to TypeError.

@item 
gh-90385@footnote{https://github.com/python/cpython/issues/90385}: Add @ref{492,,pathlib.Path.walk()} as an alternative to
@ref{493,,os.walk()}.

@item 
gh-92550@footnote{https://github.com/python/cpython/issues/92550}: Fix @ref{22b,,pathlib.Path.rglob()} for empty pattern.

@item 
gh-92591@footnote{https://github.com/python/cpython/issues/92591}: Allow @ref{86,,logging} filters to return a
@ref{fd1,,logging.LogRecord} instance so that filters attached to
@ref{1448,,logging.Handler}s can enrich records without side effects on
other handlers.

@item 
gh-92445@footnote{https://github.com/python/cpython/issues/92445}: Fix a bug in @ref{6,,argparse} where @code{nargs="*"} would raise an
error instead of returning an empty list when 0 arguments were supplied if
choice was also defined in @code{parser.add_argument}.

@item 
gh-92547@footnote{https://github.com/python/cpython/issues/92547}: Remove undocumented @ref{ce,,sqlite3} features deprecated in Python
3.10:


@itemize *

@item 
@code{sqlite3.enable_shared_cache()}

@item 
@code{sqlite3.OptimizedUnicode}
@end itemize

Patch by Erlend E. Aasland.

@item 
gh-92530@footnote{https://github.com/python/cpython/issues/92530}: Fix an issue that occurred after interrupting
@ref{176a,,threading.Condition.notify()}.

@item 
gh-92531@footnote{https://github.com/python/cpython/issues/92531}: The statistics.median_grouped() function now always return a
float. Formerly, it did not convert the input type when for sequences of
length one.

@item 
gh-84131@footnote{https://github.com/python/cpython/issues/84131}: The @ref{226,,pathlib.Path} deprecated method @code{link_to} has been
removed. Use 3.10's @ref{80b,,hardlink_to()} method instead as
its semantics are consistent with that of
@ref{80c,,symlink_to()}.

@item 
gh-89336@footnote{https://github.com/python/cpython/issues/89336}: Removed @ref{22,,configparser} module APIs: the
@code{SafeConfigParser} class alias, the @code{ParsingError.filename} property
and parameter, and the @code{ConfigParser.readfp} method, all of which were
deprecated since Python 3.2.

@item 
gh-92391@footnote{https://github.com/python/cpython/issues/92391}: Add @ref{725,,__class_getitem__()} to
@ref{9d3,,csv.DictReader} and @ref{11db,,csv.DictWriter}, allowing them to be
parameterized at runtime. Patch by Marc Mueller.

@item 
gh-91968@footnote{https://github.com/python/cpython/issues/91968}: Add @code{SO_RTABLE} and @code{SO_USER_COOKIE} constants to
@ref{cb,,socket}.

@item 
gh-91810@footnote{https://github.com/python/cpython/issues/91810}: @ref{93b,,ElementTree} method
@ref{fe0,,write()} and function
@ref{fde,,tostring()} now use the text file's encoding
("UTF-8" if not available) instead of locale encoding in XML declaration
when @code{encoding="unicode"} is specified.

@item 
gh-81790@footnote{https://github.com/python/cpython/issues/81790}: @ref{be2,,os.path.splitdrive()} now understands DOS device paths with
UNC links (beginning @code{\\?\UNC\}). Contributed by Barney Gale.

@item 
gh-91760@footnote{https://github.com/python/cpython/issues/91760}: Apply more strict rules 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.

@item 
gh-90622@footnote{https://github.com/python/cpython/issues/90622}: Worker processes for
@ref{8db,,concurrent.futures.ProcessPoolExecutor} are no longer spawned on
demand (a feature added in 3.9) when the multiprocessing context start
method is @code{"fork"} as that can lead to deadlocks in the child processes
due to a fork happening while threads are running.

@item 
gh-91577@footnote{https://github.com/python/cpython/issues/91577}: Move imports in @code{SharedMemory} methods
to module level so that they can be executed late in python finalization.

@item 
gh-91581@footnote{https://github.com/python/cpython/issues/91581}: Remove an unhandled error case in the C implementation of calls
to @ref{4d7,,datetime.fromtimestamp} with
no time zone (i.e. getting a local time from an epoch timestamp). This
should have no user-facing effect other than giving a possibly more
accurate error message when called with timestamps that fall on
10000-01-01 in the local time. Patch by Paul Ganssle.

@item 
gh-91539@footnote{https://github.com/python/cpython/issues/91539}: Improve performance of @code{urllib.request.getproxies_environment}
when there are many environment variables

@item 
gh-91524@footnote{https://github.com/python/cpython/issues/91524}: Speed up the regular expression substitution (functions
@ref{2a0,,re.sub()} and @ref{2a1,,re.subn()} and corresponding @ref{176b,,re.Pattern}
methods) for replacement strings containing group references by 2--3
times.

@item 
gh-91447@footnote{https://github.com/python/cpython/issues/91447}: Fix findtext in the xml module to only give an empty string when
the text attribute is set to @code{None}.

@item 
gh-91456@footnote{https://github.com/python/cpython/issues/91456}: Deprecate current default auto() behavior:  In 3.13 the default
will be for for auto() to always return the largest member value
incremented by 1, and to raise if incompatible value types are used.

@item 
bpo-47231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47231}: Fixed an issue with inconsistent trailing slashes in tarfile
longname directories.

@item 
bpo-39064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39064}: @ref{6af,,zipfile.ZipFile} now raises @ref{176c,,zipfile.BadZipFile}
instead of @code{ValueError} when reading a corrupt zip file in which the
central directory offset is negative.

@item 
bpo-41287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41287}: Fix handling of the @code{doc} argument in subclasses of
@ref{192,,property()}.

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: @ref{2a,,ctypes} dependency @code{libffi} is now detected with
@code{pkg-config}.

@item 
bpo-32547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32547}: The constructors for @ref{11db,,DictWriter} and
@ref{9d3,,DictReader} now coerce the @code{fieldnames} argument to a
@ref{5fc,,list} if it is an iterator.

@item 
bpo-35540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35540}: Fix @ref{16af,,dataclasses.asdict()} crash when
@ref{119a,,collections.defaultdict} is present in the attributes.

@item 
bpo-47063@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47063}: Add an index_pages parameter to support using non-default index
page names.

@item 
bpo-47025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47025}: Drop support for @ref{1bd,,bytes} on @ref{3ab,,sys.path}.

@item 
bpo-46951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46951}: Order the contents of zipapp archives, to make builds more
reproducible.

@item 
bpo-42777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42777}: Implement @ref{a05,,pathlib.Path.is_mount()} for Windows paths.

@item 
bpo-46755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46755}: In @code{QueueHandler}, clear @code{stack_info} from
@code{LogRecord} to prevent stack trace from being written twice.

@item 
bpo-45393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45393}: Fix the formatting for @code{await x} and @code{not x} in the
operator precedence table when using the @ref{8c4,,help()} system.

@item 
bpo-46642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46642}: Improve error message when trying to subclass an instance of
@ref{15c,,typing.TypeVar}, @ref{15d,,typing.ParamSpec},
@ref{15e,,typing.TypeVarTuple}, etc. Based on patch by Gregory Beauregard.

@item 
bpo-46364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46364}: Restrict use of sockets instead of pipes for stdin of
subprocesses created by @ref{a,,asyncio} to AIX platform only.

@item 
bpo-28249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28249}: Set @ref{176d,,doctest.DocTest.lineno} to @code{None} when an object
does not have @ref{915,,__doc__}.

@item 
bpo-46197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46197}: Fix @ref{54,,ensurepip} environment isolation for subprocess
running @code{pip}.

@item 
bpo-45924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45924}: Fix @ref{a,,asyncio} incorrect traceback when future's exception
is raised multiple times. Patch by Kumar Aditya.

@item 
bpo-45046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45046}: Add support of context managers in @ref{105,,unittest}: methods
@ref{6a4,,enterContext()} and
@ref{6a5,,enterClassContext()} of class
@ref{437,,TestCase}, method
@ref{6a6,,enterAsyncContext()} of class
@ref{301,,IsolatedAsyncioTestCase} and function
@ref{6a7,,unittest.enterModuleContext()}.

@item 
bpo-44173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44173}: Enable fast seeking of uncompressed unencrypted
@code{zipfile.ZipExtFile}

@item 
bpo-42627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42627}: Fix incorrect parsing of Windows registry proxy settings

@item 
bpo-42047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42047}: Add @ref{a2c,,threading.get_native_id()} support for DragonFly BSD.
Patch by David Carlier.

@item 
bpo-14243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14243}: The @ref{4af,,tempfile.NamedTemporaryFile} function has a new
optional parameter `delete_on_close'

@item 
bpo-41246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41246}: Give the same callback function for when the overlapped
operation is done to the functions @code{recv}, @code{recv_into}, @code{recvfrom},
@code{sendto}, @code{send} and @code{sendfile} inside @code{IocpProactor}.

@item 
bpo-39264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39264}: Fixed @code{collections.UserDict.get()} to not call
@code{__missing__()} when a value is not found. This matches the behavior
of @ref{253,,dict}. Patch by Bar Harel.

@item 
bpo-38693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38693}: @ref{76,,importlib} now uses f-strings internally instead of
@code{str.format}.

@item 
bpo-38267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38267}: Add `timeout' parameter to
@ref{8d4,,asyncio.loop.shutdown_default_executor()}. The default value is
@code{None}, which means the executor will be given an unlimited amount of
time. When called from @ref{5eb,,asyncio.Runner} or @ref{466,,asyncio.run()}, the
default timeout is 5 minutes.

@item 
bpo-34828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34828}: @ref{244,,sqlite3.Connection.iterdump()} now handles databases that
use @code{AUTOINCREMENT} in one or more tables.

@item 
bpo-32990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32990}: Support reading wave files with the @code{WAVE_FORMAT_EXTENSIBLE}
format in the @ref{112,,wave} module.

@item 
bpo-26253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26253}: Allow adjustable compression level for tarfile streams in
@ref{e60,,tarfile.open()}.
@end itemize

@node Documentation<18>,Tests<21>,Library<23>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id190}@anchor{176e}
@subsubsection Documentation



@itemize -

@item 
gh-85525@footnote{https://github.com/python/cpython/issues/85525}: Remove extra row

@item 
gh-86404@footnote{https://github.com/python/cpython/issues/86404}: Deprecated tools @code{make suspicious} and @code{rstlint.py} are now
removed. They have been replaced by sphinx-lint@footnote{https://pypi.org/project/sphinx-lint/}.

@item 
gh-97741@footnote{https://github.com/python/cpython/issues/97741}: Fix @code{!} in c domain ref target syntax via a @code{conf.py} patch,
so it works as intended to disable ref target resolution.

@item 
gh-96432@footnote{https://github.com/python/cpython/issues/96432}: Fraction literals now support whitespace around the forward
slash, @code{Fraction('2 / 3')}.

@item 
gh-96098@footnote{https://github.com/python/cpython/issues/96098}: Improve discoverability of the higher level concurrent.futures
module by providing clearer links from the lower level threading and
multiprocessing modules.

@item 
gh-95957@footnote{https://github.com/python/cpython/issues/95957}: What's New 3.11 now has instructions for how to provide compiler
and linker flags for Tcl/Tk and OpenSSL on RHEL 7 and CentOS 7.

@item 
gh-95588@footnote{https://github.com/python/cpython/issues/95588}: Clarified the conflicting advice given in the @ref{8,,ast}
documentation about @ref{c06,,ast.literal_eval()} being "safe" for use on
untrusted input while at the same time warning that it can crash the
process. The latter statement is true and is deemed unfixable without a
large amount of work unsuitable for a bugfix. So we keep the warning and
no longer claim that @code{literal_eval} is safe.

@item 
gh-91207@footnote{https://github.com/python/cpython/issues/91207}: Fix stylesheet not working in Windows CHM htmlhelp docs and add
warning that they are deprecated. Contributed by C.A.M. Gerlach.

@item 
gh-95454@footnote{https://github.com/python/cpython/issues/95454}: Replaced incorrectly written true/false values in documentation.
Patch by Robert O'Shea

@item 
gh-95451@footnote{https://github.com/python/cpython/issues/95451}: Update library documentation with @ref{176f,,availability information} on WebAssembly platforms @code{wasm32-emscripten} and
@code{wasm32-wasi}.

@item 
gh-95415@footnote{https://github.com/python/cpython/issues/95415}: Use consistent syntax for platform availability. The directive
now supports a content body and emits a warning when it encounters an
unknown platform.

@item 
gh-94321@footnote{https://github.com/python/cpython/issues/94321}: Document the 
@geindex Python Enhancement Proposals; PEP 246
PEP 246@footnote{https://peps.python.org/pep-0246/} style protocol type
@ref{1770,,sqlite3.PrepareProtocol}.

@item 
gh-86128@footnote{https://github.com/python/cpython/issues/86128}: Document a limitation in ThreadPoolExecutor where its exit
handler is executed before any handlers in atexit.

@item 
gh-61162@footnote{https://github.com/python/cpython/issues/61162}: Clarify @ref{ce,,sqlite3} behavior when
@ref{1771,,How to use the connection context manager}.

@item 
gh-87260@footnote{https://github.com/python/cpython/issues/87260}: Align @ref{ce,,sqlite3} argument specs with the actual
implementation.

@item 
gh-86986@footnote{https://github.com/python/cpython/issues/86986}: The minimum Sphinx version required to build the documentation
is now 3.2.

@item 
gh-88831@footnote{https://github.com/python/cpython/issues/88831}: Augmented documentation of asyncio.create_task(). Clarified the
need to keep strong references to tasks and added a code snippet detailing
how to do this.

@item 
gh-86438@footnote{https://github.com/python/cpython/issues/86438}: Clarify that @ref{8b4,,-W} and 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS} are
matched literally and case-insensitively, rather than as regular
expressions, in @ref{111,,warnings}.

@item 
gh-93031@footnote{https://github.com/python/cpython/issues/93031}: Update tutorial introduction output to use 3.10+ SyntaxError
invalid range.

@item 
gh-92240@footnote{https://github.com/python/cpython/issues/92240}: Added release dates for "What's New in Python 3.X" for 3.0, 3.1,
3.2, 3.8 and 3.10

@item 
bpo-47161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47161}: Document that @ref{490,,pathlib.PurePath} does not collapse
initial double slashes because they denote UNC paths.

@item 
bpo-40838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40838}: Document that @ref{9e8,,inspect.getdoc()},
@ref{1772,,inspect.getmodule()}, and @ref{1773,,inspect.getsourcefile()} might return
@code{None}.

@item 
bpo-43689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43689}: The @code{Differ} documentation now also mentions other whitespace
characters, which make it harder to understand the diff output.

@item 
bpo-38056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38056}: Overhaul the @ref{1774,,Gestionnaires d'erreurs} documentation in
@ref{1b,,codecs}.

@item 
bpo-13553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13553}: Document tkinter.Tk args.
@end itemize

@node Tests<21>,Build<23>,Documentation<18>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id191}@anchor{1775}
@subsubsection Tests



@itemize -

@item 
gh-95027@footnote{https://github.com/python/cpython/issues/95027}: On Windows, when the Python test suite is run with the @code{-jN}
option, the ANSI code page is now used as the encoding for the stdout
temporary file, rather than using UTF-8 which can lead to decoding errors.
Patch by Victor Stinner.

@item 
gh-96624@footnote{https://github.com/python/cpython/issues/96624}: Fixed the failure of repeated runs of @code{test.test_unittest}
caused by side effects in @code{test_dotted_but_module_not_loaded}.

@item 
gh-95243@footnote{https://github.com/python/cpython/issues/95243}: Mitigate the inherent race condition from using
find_unused_port() in testSockName() by trying to find an unused port a
few times before failing. Patch by Ross Burton.

@item 
gh-95573@footnote{https://github.com/python/cpython/issues/95573}: Lib/test/test_asyncio/test_ssl.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/test/test_asyncio/test_ssl.py} exposed a bug in the
macOS kernel where intense concurrent load on non-blocking sockets
occasionally causes @ref{1776,,errno.ENOBUFS} ("No buffer space available")
to be emitted. FB11063974 filed with Apple, in the mean time as a
workaround buffer size used in tests on macOS is decreased to avoid
intermittent failures.  Patch by Fantix King.

@item 
gh-95280@footnote{https://github.com/python/cpython/issues/95280}: Fix problem with @code{test_ssl} @code{test_get_ciphers} on systems
that require perfect forward secrecy (PFS) ciphers.

@item 
gh-95212@footnote{https://github.com/python/cpython/issues/95212}: Make multiprocessing test case @code{test_shared_memory_recreate}
parallel-safe.

@item 
gh-95218@footnote{https://github.com/python/cpython/issues/95218}: Move tests for importlib.resources into
test_importlib.resources.

@item 
gh-93963@footnote{https://github.com/python/cpython/issues/93963}: Updated tests to use preferred location for
@code{importlib.resources} ABCs.

@item 
gh-94675@footnote{https://github.com/python/cpython/issues/94675}: Add a regression test for @ref{b8,,re} exponentional slowdown when
using rjsmin.

@item 
gh-91330@footnote{https://github.com/python/cpython/issues/91330}: Added more tests for @ref{2f,,dataclasses} to cover behavior with
data descriptor-based fields.

@item 
gh-94208@footnote{https://github.com/python/cpython/issues/94208}: @code{test_ssl} is now checking for supported TLS version and
protocols in more tests.

@item 
gh-94315@footnote{https://github.com/python/cpython/issues/94315}: Tests now check for DAC override capability instead of relying
on @ref{1777,,os.geteuid()}.

@item 
gh-54781@footnote{https://github.com/python/cpython/issues/54781}: Rename test_tk to test_tkinter, and rename test_ttk_guionly to
test_ttk. Patch by Victor Stinner.

@item 
gh-93839@footnote{https://github.com/python/cpython/issues/93839}: Move @code{Lib/ctypes/test/} to @code{Lib/test/test_ctypes/}. Patch by
Victor Stinner.

@item 
gh-93951@footnote{https://github.com/python/cpython/issues/93951}: In test_bdb.StateTestCase.test_skip, avoid including auxiliary
importers.

@item 
gh-93957@footnote{https://github.com/python/cpython/issues/93957}: Provide nicer error reporting from subprocesses in
test_venv.EnsurePipTest.test_with_pip.

@item 
gh-93884@footnote{https://github.com/python/cpython/issues/93884}: Add test cases for @ref{1778,,PyNumber_ToBase()} that take a large
number or a non-int object as parameter.

@item 
gh-93852@footnote{https://github.com/python/cpython/issues/93852}: test_asyncio, test_logging, test_socket and test_socketserver
now create AF_UNIX domains in the current directory to no longer fail with
@code{OSError("AF_UNIX path too long")} if the temporary directory (the
@geindex TMPDIR
@geindex variable d'environnement; TMPDIR
@code{TMPDIR} environment variable) is too long. Patch by Victor
Stinner.

@item 
gh-93353@footnote{https://github.com/python/cpython/issues/93353}: regrtest now checks if a test leaks temporary files or
directories if run with -jN option. Patch by Victor Stinner.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: @code{run_tests.py} now handles cross compiling env vars correctly
and pass @code{HOSTRUNNER} to regression tests.

@item 
gh-93616@footnote{https://github.com/python/cpython/issues/93616}: @code{test_modulefinder} now creates a temporary directory in
@code{ModuleFinderTest.setUp()} instead of module scope.

@item 
gh-93575@footnote{https://github.com/python/cpython/issues/93575}: Fix issue with test_unicode test_raiseMemError. The test case
now use @code{test.support.calcobjsize} to calculate size of PyUnicode
structs. @ref{16f8,,sys.getsizeof()} may return different size when string has
UTF-8 memory.

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: WASI does not have a @code{chmod(2)} syscall. @ref{218,,os.chmod()} is
now a dummy function on WASI. Skip all tests that depend on working
@ref{218,,os.chmod()}.

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: Skip tests on WASI that require symlinks with absolute paths.

@item 
gh-57539@footnote{https://github.com/python/cpython/issues/57539}: Increase calendar test coverage for
@code{calendar.LocaleTextCalendar.formatweekday()}.

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: Skip symlink tests on WASI. wasmtime uses @code{openat2(2)} with
@code{RESOLVE_BENEATH} flag, which prevents symlinks with absolute paths.

@item 
gh-89858@footnote{https://github.com/python/cpython/issues/89858}: Fix @code{test_embed} for out-of-tree builds. Patch by Kumar
Aditya.

@item 
gh-92886@footnote{https://github.com/python/cpython/issues/92886}: Fixing tests that fail when running with optimizations (@code{-O})
in @code{test_imaplib.py}.

@item 
gh-92886@footnote{https://github.com/python/cpython/issues/92886}: Fixing tests that fail when running with optimizations (@code{-O})
in @code{test_zipimport.py}

@item 
gh-92886@footnote{https://github.com/python/cpython/issues/92886}: Fixing tests that fail when running with optimizations (@code{-O})
in @code{test_py_compile.py}

@item 
gh-92886@footnote{https://github.com/python/cpython/issues/92886}: Fixing tests that fail when running with optimizations (@code{-O})
in @code{test_sys_settrace.py}.

@item 
gh-92886@footnote{https://github.com/python/cpython/issues/92886}: Fixing tests that fail when running with optimizations (@code{-O})
in @code{_test_multiprocessing.py}

@item 
gh-92670@footnote{https://github.com/python/cpython/issues/92670}: Skip @code{test_shutil.TestCopy.test_copyfile_nonexistent_dir} test
on AIX as the test uses a trailing slash to force the OS consider the path
as a directory, but on AIX the trailing slash has no effect and is
considered as a file.

@item 
gh-92514@footnote{https://github.com/python/cpython/issues/92514}: Remove unused @code{test.support.BasicTestRunner}. Patch by Jelle
Zijlstra.

@item 
bpo-47016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47016}: Create a GitHub Actions workflow for verifying bundled pip and
setuptools. Patch by Illia Volochii and Adam Turner.
@end itemize

@node Build<23>,Windows<20>,Tests<21>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id192}@anchor{1779}
@subsubsection Build



@itemize -

@item 
gh-96761@footnote{https://github.com/python/cpython/issues/96761}: Fix the build process of clang compiler for
@code{_bootstrap_python} if LTO optimization is applied. Patch by
Matthias Görgens and Donghee Na.

@item 
gh-96883@footnote{https://github.com/python/cpython/issues/96883}: @code{wasm32-emscripten} builds for browsers now include
@ref{21,,concurrent.futures} for @ref{a,,asyncio} and @ref{106,,unittest.mock}.

@item 
gh-85936@footnote{https://github.com/python/cpython/issues/85936}: CPython now uses the ThinLTO option as the default policy if the
Clang compiler accepts the flag. Patch by Donghee Na.

@item 
gh-96729@footnote{https://github.com/python/cpython/issues/96729}: Ensure that Windows releases built with
@code{Tools\msi\buildrelease.bat} are upgradable to and from official Python
releases.

@item 
gh-96269@footnote{https://github.com/python/cpython/issues/96269}: Shared module targets now depend on new @code{MODULE_DEPS}
variable, which includes @code{EXPORTSYMS}. This fixes a build order issue on
unsupported AIX platform.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: @code{wasm32-emscripten} platform no longer builds @ref{bb,,resource}
module, @ref{12f4,,getresuid()}, @ref{12f3,,getresgid()}, and their setters.
The APIs are stubs and not functional.

@item 
gh-95973@footnote{https://github.com/python/cpython/issues/95973}: Add a new @code{--with-dsymutil} configure option to link debug
information in macOS. Patch by Pablo Galindo.

@item 
gh-90536@footnote{https://github.com/python/cpython/issues/90536}: Use the BOLT post-link optimizer to improve performance,
particularly on medium-to-large applications.

@item 
gh-93744@footnote{https://github.com/python/cpython/issues/93744}: Remove the @code{configure --with-cxx-main} build option: it didn't
work for many years. Remove the @code{MAINCC} variable from @code{configure} and
@code{Makefile}. Patch by Victor Stinner.

@item 
gh-94801@footnote{https://github.com/python/cpython/issues/94801}: Fix a regression in @code{configure} script that caused some header
checks to ignore custom @code{CPPFLAGS}. The regression was introduced in
gh-94802@footnote{https://github.com/python/cpython/issues/94802}.

@item 
gh-95145@footnote{https://github.com/python/cpython/issues/95145}: wasm32-wasi builds no longer depend on WASIX's pthread stubs.
Python now has its own stubbed pthread API.

@item 
gh-95174@footnote{https://github.com/python/cpython/issues/95174}: Python now detects missing @code{dup} function in WASI and works
around some missing @ref{56,,errno}, @ref{c0,,select}, and @ref{cb,,socket}
constants.

@item 
gh-95174@footnote{https://github.com/python/cpython/issues/95174}: Python now skips missing @ref{cb,,socket} functions and methods on
WASI. WASI can only create sockets from existing fd / accept and has no
netdb.

@item 
gh-95085@footnote{https://github.com/python/cpython/issues/95085}: Platforms @code{wasm32-unknown-emscripten} and
@code{wasm32-unknown-wasi} have been promoted to 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} tier 3 platform
support.

@item 
gh-94847@footnote{https://github.com/python/cpython/issues/94847}: Fixed @code{_decimal} module build issue on GCC when compiling with
LTO and pydebug. Debug builds no longer force inlining of functions.

@item 
gh-94841@footnote{https://github.com/python/cpython/issues/94841}: Fix the possible performance regression of
@ref{c53,,PyObject_Free()} compiled with MSVC version 1932.

@item 
gh-94801@footnote{https://github.com/python/cpython/issues/94801}: @code{configure} now uses custom flags like @code{ZLIB_CFLAGS} and
@code{ZLIB_LIBS} when searching for headers and libraries.

@item 
gh-94773@footnote{https://github.com/python/cpython/issues/94773}: @code{deepfreeze.py} now supports code object with frozensets that
contain incompatible, unsortable types.

@item 
gh-94682@footnote{https://github.com/python/cpython/issues/94682}: Build and test with OpenSSL 1.1.1q

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: Dependencies of @ref{b9,,readline} and @ref{2b,,curses} module are now
detected in @code{configure} script with @code{pkg-config}. Only @code{ncurses} /
@code{ncursesw} are detected automatically. The old @code{curses} library is not
configured automatically. Workaround for missing @code{termcap} or @code{tinfo}
library has been removed.

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: Fix building @code{_ctypes} extension without @code{pkg-config}.

@item 
gh-90005@footnote{https://github.com/python/cpython/issues/90005}: @code{_dbm} module dependencies are now detected by configure.

@item 
gh-94404@footnote{https://github.com/python/cpython/issues/94404}: @code{makesetup} now works around an issue with sed on macOS and
uses correct CFLAGS for object files that end up in a shared extension.
Module CFLAGS are used before PY_STDMODULE_CFLAGS to avoid clashes with
system headers.

@item 
gh-93939@footnote{https://github.com/python/cpython/issues/93939}: C extension modules are now built by @code{configure} and @code{make}
instead of @code{distutils} and @code{setup.py}.

@item 
gh-93939@footnote{https://github.com/python/cpython/issues/93939}: The @code{2to3}, @code{idle}, and @code{pydoc} scripts are now generated
and installed by @code{Makefile} instead of @code{setup.py}.

@item 
gh-94280@footnote{https://github.com/python/cpython/issues/94280}: Updated pegen regeneration script on Windows to find and use
Python 3.9 or higher.  Prior to this, pegen regeneration already required
3.9 or higher, but the script may have used lower versions of Python.

@item 
gh-93584@footnote{https://github.com/python/cpython/issues/93584}: Address race condition in @code{Makefile} when installing a PGO
build. All @code{test} and @code{install} targets now depend on @code{all} target.

@item 
gh-93491@footnote{https://github.com/python/cpython/issues/93491}: @code{configure} now detects and reports 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} support tiers.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Fix @code{Modules/Setup.stdlib.in} rule for @code{_sqlite3} extension.

@item 
gh-93207@footnote{https://github.com/python/cpython/issues/93207}: @code{va_start()} with two parameters, like @code{va_start(args,
format),} is now required to build Python. @code{va_start()} is no longer
called with a single parameter. Patch by Kumar Aditya.

@item 
gh-93202@footnote{https://github.com/python/cpython/issues/93202}: Python now always use the @code{%zu} and @code{%zd} printf formats to
format a @code{size_t} or @code{Py_ssize_t} number. Building Python 3.12
requires a C11 compiler, so these printf formats are now always supported.
Patch by Victor Stinner.

@item 
gh-90473@footnote{https://github.com/python/cpython/issues/90473}: Disable pymalloc and increase stack size on @code{wasm32-wasi}.

@item 
bpo-34449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34449}: Drop invalid compiler switch @code{-fPIC} for HP aCC on HP-UX.
Patch by Michael Osipov.
@end itemize

@node Windows<20>,macOS<15>,Build<23>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id193}@anchor{177a}
@subsubsection Windows



@itemize -

@item 
gh-98360@footnote{https://github.com/python/cpython/issues/98360}: Fixes @ref{93,,multiprocessing} spawning child processes on Windows
from a virtual environment to ensure that child processes that also use
@ref{93,,multiprocessing} to spawn more children will recognize that they are
in a virtual environment.

@item 
gh-98414@footnote{https://github.com/python/cpython/issues/98414}: Fix @code{py.exe} launcher handling of @code{-V:@var{<company>}/}
option when default preferences have been set in environment variables or
configuration files.

@item 
gh-97728@footnote{https://github.com/python/cpython/issues/97728}: Fix possible crashes caused by the use of uninitialized
variables when pass invalid arguments in @ref{1411,,os.system()} on Windows and
in Windows-specific modules (like @code{winreg}).

@item 
gh-90989@footnote{https://github.com/python/cpython/issues/90989}: Made @ref{5a8,,Lanceur Python pour Windows} install per-user by default (unless an all
users install already exists), and clarify some text in the installer.

@item 
gh-97649@footnote{https://github.com/python/cpython/issues/97649}: The @code{Tools} directory is no longer installed on Windows

@item 
gh-96965@footnote{https://github.com/python/cpython/issues/96965}: Update libffi to 3.4.3

@item 
gh-96577@footnote{https://github.com/python/cpython/issues/96577}: Fixes a potential buffer overrun in @code{msilib}.

@item 
gh-96559@footnote{https://github.com/python/cpython/issues/96559}: Fixes the Windows launcher not using the compatible
interpretation of default tags found in configuration files when no tag
was passed to the command.

@item 
gh-94781@footnote{https://github.com/python/cpython/issues/94781}: Fix @code{pcbuild.proj} to clean previous instances of output
files in @code{Python\deepfreeze} and @code{Python\frozen_modules} directories
on Windows. Patch by Charlie Zhao.

@item 
gh-89545@footnote{https://github.com/python/cpython/issues/89545}: Updates @ref{a9,,platform} code getting the Windows version to use
native Windows Management Instrumentation (WMI) queries to determine OS
version, type, and architecture.

@item 
gh-95733@footnote{https://github.com/python/cpython/issues/95733}: Make certain requirements of the Windows Store package optional
to allow installing on earlier updates of Windows.

@item 
gh-95656@footnote{https://github.com/python/cpython/issues/95656}: Enable the @ref{828,,enable_load_extension()}
@ref{ce,,sqlite3} API.

@item 
gh-95587@footnote{https://github.com/python/cpython/issues/95587}: Fixes some issues where the Windows installer would incorrectly
detect certain features of an existing install when upgrading.

@item 
gh-94399@footnote{https://github.com/python/cpython/issues/94399}: Restores the behaviour of @ref{5a8,,Lanceur Python pour Windows} for @code{/usr/bin/env}
shebang lines, which will now search 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} for an executable
matching the given command. If none is found, the usual search process is
used.

@item 
gh-95445@footnote{https://github.com/python/cpython/issues/95445}: Fixes the unsuccessful removal of the HTML document directory
when uninstalling with Windows msi.

@item 
gh-95359@footnote{https://github.com/python/cpython/issues/95359}: Fix @ref{5a8,,Lanceur Python pour Windows} handling of @code{py.ini} commands (it was
incorrectly expecting a @code{py_} prefix on keys) and crashes when reading
per-user configuration file.

@item 
gh-95285@footnote{https://github.com/python/cpython/issues/95285}: Fix @ref{5a8,,Lanceur Python pour Windows} handling of command lines where it is only
passed a short executable name.

@item 
gh-90844@footnote{https://github.com/python/cpython/issues/90844}: Allow virtual environments to correctly launch when they have
spaces in the path.

@item 
gh-94772@footnote{https://github.com/python/cpython/issues/94772}: Fix incorrect handling of shebang lines in py.exe launcher

@item 
gh-94018@footnote{https://github.com/python/cpython/issues/94018}: @ref{130,,zipfile} will now remove trailing spaces from path
components when extracting files on Windows.

@item 
gh-93824@footnote{https://github.com/python/cpython/issues/93824}: Drag and drop of files onto Python files in Windows Explorer has
been enabled for Windows ARM64.

@item 
gh-43414@footnote{https://github.com/python/cpython/issues/43414}: @ref{10e2,,os.get_terminal_size()} now attempts to read the size from
any provided handle, rather than only supporting file descriptors 0, 1 and
2.

@item 
gh-92817@footnote{https://github.com/python/cpython/issues/92817}: Ensures that @code{py.exe} will prefer an active virtual
environment over default tags specified with environment variables or
through a @code{py.ini} file.

@item 
gh-92984@footnote{https://github.com/python/cpython/issues/92984}: Explicitly disable incremental linking for non-Debug builds

@item 
gh-92841@footnote{https://github.com/python/cpython/issues/92841}: @ref{a,,asyncio} no longer throws @code{RuntimeError: Event loop is
closed} on interpreter exit after asynchronous socket activity. Patch by
Oleg Iarygin.

@item 
bpo-46907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46907}: Update Windows installer to use SQLite 3.38.4.

@item 
gh-91061@footnote{https://github.com/python/cpython/issues/91061}: Accept os.PathLike for the argument to winsound.PlaySound

@item 
bpo-42658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42658}: Support native Windows case-insensitive path comparisons by
using @code{LCMapStringEx} instead of @ref{177b,,str.lower()} in
@code{ntpath.normcase()}. Add @code{LCMapStringEx} to the @code{_winapi}
module.

@item 
bpo-38704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38704}: Prevent installation on unsupported Windows versions.
@end itemize

@node macOS<15>,IDLE<15>,Windows<20>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id194}@anchor{177c}
@subsubsection macOS



@itemize -

@item 
gh-97897@footnote{https://github.com/python/cpython/issues/97897}: The macOS 13 SDK includes support for the @code{mkfifoat} and
@code{mknodat} system calls. Using the @code{dir_fd} option with either
@ref{d7d,,os.mkfifo()} or @ref{d7e,,os.mknod()} could result in a segfault if
cpython is built with the macOS 13 SDK but run on an earlier version of
macOS. Prevent this by adding runtime support for detection of these
system calls ("weaklinking") as is done for other newer syscalls on macOS.
@end itemize

@node IDLE<15>,Tools/Demos<12>,macOS<15>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id195}@anchor{177d}
@subsubsection IDLE



@itemize -

@item 
gh-97527@footnote{https://github.com/python/cpython/issues/97527}: Fix a bug in the previous bugfix that caused IDLE to not start
when run with 3.10.8, 3.12.0a1, and at least Microsoft Python 3.10.2288.0
installed without the Lib/test package.  3.11.0 was never affected.

@item 
gh-65802@footnote{https://github.com/python/cpython/issues/65802}: Document handling of extensions in Save As dialogs.

@item 
gh-95191@footnote{https://github.com/python/cpython/issues/95191}: Include prompts when saving Shell (interactive input and
output).

@item 
gh-95511@footnote{https://github.com/python/cpython/issues/95511}: Fix the Shell context menu copy-with-prompts bug of copying an
extra line when one selects whole lines.

@item 
gh-95471@footnote{https://github.com/python/cpython/issues/95471}: In the Edit menu, move @code{Select All} and add a new separator.

@item 
gh-95411@footnote{https://github.com/python/cpython/issues/95411}: Enable using IDLE's module browser with .pyw files.

@item 
gh-89610@footnote{https://github.com/python/cpython/issues/89610}: Add .pyi as a recognized extension for IDLE on macOS.    This
allows opening stub files by double clicking on them in the Finder.
@end itemize

@node Tools/Demos<12>,C API<22>,IDLE<15>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id196}@anchor{177e}
@subsubsection Tools/Demos



@itemize -

@item 
gh-68686@footnote{https://github.com/python/cpython/issues/68686}: Remove ptags and eptags scripts.

@item 
gh-97681@footnote{https://github.com/python/cpython/issues/97681}: Remove the @code{Tools/demo/} directory which contained old demo
scripts. A copy can be found in the old-demos project@footnote{https://github.com/gvanrossum/old-demos}.  Patch by Victor Stinner.

@item 
gh-97669@footnote{https://github.com/python/cpython/issues/97669}: Remove outdated example scripts of the @code{Tools/scripts/}
directory. A copy can be found in the old-demos project@footnote{https://github.com/gvanrossum/old-demos}. Patch by Victor Stinner.

@item 
gh-95853@footnote{https://github.com/python/cpython/issues/95853}: The @code{wasm_build.py} script now pre-builds Emscripten ports,
checks for broken EMSDK versions, and warns about pkg-config env vars.

@item 
gh-95853@footnote{https://github.com/python/cpython/issues/95853}: The new tool @code{Tools/wasm/wasm_builder.py} automates configure,
compile, and test steps for building CPython on WebAssembly platforms.

@item 
gh-95731@footnote{https://github.com/python/cpython/issues/95731}: Fix handling of module docstrings in
@code{Tools/i18n/pygettext.py}.

@item 
gh-93939@footnote{https://github.com/python/cpython/issues/93939}: Add script @code{Tools/scripts/check_modules.py} to check and
validate builtin and shared extension modules. The script also handles
@code{Modules/Setup} and will eventually replace @code{setup.py}.

@item 
gh-94538@footnote{https://github.com/python/cpython/issues/94538}: Fix Argument Clinic output to custom file destinations. Patch by
Erlend E. Aasland.

@item 
gh-94430@footnote{https://github.com/python/cpython/issues/94430}: Allow parameters named @code{module} and @code{self} with custom C
names in Argument Clinic. Patch by Erlend E. Aasland

@item 
gh-86087@footnote{https://github.com/python/cpython/issues/86087}: The @code{Tools/scripts/parseentities.py} script used to parse
HTML4 entities has been removed.
@end itemize

@node C API<22>,,Tools/Demos<12>,Python 3 12 0 alpha 1
@anchor{whatsnew/changelog id198}@anchor{177f}
@subsubsection C API



@itemize -

@item 
gh-98393@footnote{https://github.com/python/cpython/issues/98393}: The @ref{563,,PyUnicode_FSDecoder()} function no longer accepts
bytes-like paths, like @ref{528,,bytearray} and @ref{452,,memoryview} types:
only the exact @ref{1bd,,bytes} type is accepted for bytes strings. Patch by
Victor Stinner.

@item 
gh-91051@footnote{https://github.com/python/cpython/issues/91051}: Add @ref{551,,PyType_Watch()} and related APIs to allow callbacks
on @ref{1780,,PyType_Modified()}.

@item 
gh-95756@footnote{https://github.com/python/cpython/issues/95756}: Lazily create and cache @code{co_} attributes for better
performance for code getters.

@item 
gh-96512@footnote{https://github.com/python/cpython/issues/96512}: Configuration for the @ref{5df,,integer string conversion length limitation} now lives in the PyConfig C API struct.

@item 
gh-95589@footnote{https://github.com/python/cpython/issues/95589}: Extensions classes that set @code{tp_dictoffset} and
@code{tp_weaklistoffset} lose the support for multiple inheritance, but are
now safe. Extension classes should use @ref{361,,Py_TPFLAGS_MANAGED_DICT}
and @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} instead.

@item 
gh-95781@footnote{https://github.com/python/cpython/issues/95781}: An unrecognized format character in
@ref{380,,PyUnicode_FromFormat()} and @ref{560,,PyUnicode_FromFormatV()} now
sets a @ref{561,,SystemError}. 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.

@item 
gh-92678@footnote{https://github.com/python/cpython/issues/92678}: Restore the 3.10 behavior for multiple inheritance of C
extension classes that store their dictionary at the end of the struct.

@item 
gh-92678@footnote{https://github.com/python/cpython/issues/92678}: Support C extensions using managed dictionaries by setting the
@code{Py_TPFLAGS_MANAGED_DICT} flag.

@item 
gh-93274@footnote{https://github.com/python/cpython/issues/93274}: API for implementing vectorcall
(@ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL}, @ref{540,,PyVectorcall_NARGS()} and
@ref{541,,PyVectorcall_Call()}) was added to the limited API and stable ABI.

@item 
gh-95504@footnote{https://github.com/python/cpython/issues/95504}: Fix sign placement when specifying width or precision in
@ref{380,,PyUnicode_FromFormat()} and @ref{560,,PyUnicode_FromFormatV()}. Patch
by Philip Georgi.

@item 
gh-93012@footnote{https://github.com/python/cpython/issues/93012}: The @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed
from a class when the class's @ref{543,,__call__()} method is
reassigned. This makes vectorcall safe to use with mutable types (i.e.
heap types without the @code{immutable}
flag). Mutable types that do not override
@ref{544,,tp_call} now inherit the
@ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag.

@item 
gh-95388@footnote{https://github.com/python/cpython/issues/95388}: Creating @ref{3b9,,immutable types}
with mutable bases is deprecated and is planned to be disabled in Python
3.14.

@item 
gh-92678@footnote{https://github.com/python/cpython/issues/92678}: Adds unstable C-API functions @code{_PyObject_VisitManagedDict} and
@code{_PyObject_ClearManagedDict} to allow C extensions to allow the VM to
manage their object's dictionaries.

@item 
gh-94936@footnote{https://github.com/python/cpython/issues/94936}: Added @ref{763,,PyCode_GetVarnames()}, @ref{764,,PyCode_GetCellvars()}
and @ref{765,,PyCode_GetFreevars()} for accessing @code{co_varnames},
@code{co_cellvars} and @code{co_freevars} respectively via the C API.

@item 
gh-94930@footnote{https://github.com/python/cpython/issues/94930}: Fix @code{SystemError} raised when
@ref{379,,PyArg_ParseTupleAndKeywords()} is used with @code{#} in @code{(...)} but
without @code{PY_SSIZE_T_CLEAN} defined.

@item 
gh-94731@footnote{https://github.com/python/cpython/issues/94731}: Python again uses C-style casts for most casting operations when
compiled with C++. This may trigger compiler warnings, if they are enabled
with e.g. @code{-Wold-style-cast} or @code{-Wzero-as-null-pointer-constant}
options for @code{g++}.

@item 
gh-93937@footnote{https://github.com/python/cpython/issues/93937}: The following frame functions and type are now directly
available with @code{#include <Python.h>}, it's no longer needed to add
@code{#include <frameobject.h>}:


@itemize *

@item 
@ref{76f,,PyFrame_Check()}

@item 
@ref{770,,PyFrame_GetBack()}

@item 
@ref{755,,PyFrame_GetBuiltins()}

@item 
@ref{756,,PyFrame_GetGenerator()}

@item 
@ref{757,,PyFrame_GetGlobals()}

@item 
@ref{758,,PyFrame_GetLasti()}

@item 
@ref{415,,PyFrame_GetLocals()}

@item 
@ref{771,,PyFrame_Type}
@end itemize

Patch by Victor Stinner.

@item 
gh-91321@footnote{https://github.com/python/cpython/issues/91321}: Fix the compatibility of the Python C API with C++ older than
C++11. Patch by Victor Stinner.

@item 
gh-91731@footnote{https://github.com/python/cpython/issues/91731}: Avoid defining the @code{static_assert} when compiling with C++ 11,
where this is a keyword and redefining it can lead to undefined behavior.
Patch by Pablo Galindo

@item 
gh-89546@footnote{https://github.com/python/cpython/issues/89546}: @ref{53b,,PyType_FromMetaclass()} (and other @code{PyType_From*}
functions) now check that offsets and the base class's
@ref{974,,tp_basicsize} fit in the new class's
@code{tp_basicsize}.

@item 
gh-93503@footnote{https://github.com/python/cpython/issues/93503}: Add two new public functions to the public C-API,
@ref{54a,,PyEval_SetProfileAllThreads()} and
@ref{54b,,PyEval_SetTraceAllThreads()}, that allow to set tracing and
profiling functions in all running threads in addition to the calling one.
Also, two analogous functions to the @ref{ec,,threading} module
(@ref{4b2,,threading.setprofile_all_threads()} and
@ref{4b1,,threading.settrace_all_threads()}) that allow to do the same from
Python. Patch by Pablo Galindo

@item 
gh-93442@footnote{https://github.com/python/cpython/issues/93442}: Add C++ overloads for _Py_CAST_impl() to handle 0/NULL.  This
will allow C++ extensions that pass 0 or NULL to macros using _Py_CAST()
to continue to compile.

@item 
gh-93466@footnote{https://github.com/python/cpython/issues/93466}: Slot IDs in PyType_Spec may not be repeated. The documentation
was updated to mention this. For some cases of repeated slots,
PyType_FromSpec and related functions will now raise an exception.

@item 
gh-92898@footnote{https://github.com/python/cpython/issues/92898}: Fix C++ compiler warnings when casting function arguments to
@code{PyObject*}. Patch by Serge Guelton.

@item 
gh-93103@footnote{https://github.com/python/cpython/issues/93103}: Deprecate global configuration variables, like
@ref{3cf,,Py_IgnoreEnvironmentFlag}, in the documentation: the
@ref{3bc,,Py_InitializeFromConfig()} API should be instead. Patch by Victor
Stinner.

@item 
gh-77782@footnote{https://github.com/python/cpython/issues/77782}: Deprecate global configuration variable like
@ref{3cf,,Py_IgnoreEnvironmentFlag}: the @ref{3bc,,Py_InitializeFromConfig()}
API should be instead. Patch by Victor Stinner.

@item 
gh-92913@footnote{https://github.com/python/cpython/issues/92913}: Ensures changes to @ref{399,,PyConfig.module_search_paths} are
ignored unless @ref{5d9,,PyConfig.module_search_paths_set} is set

@item 
gh-92781@footnote{https://github.com/python/cpython/issues/92781}: Avoid mixing declarations and code in the C API to fix the
compiler warning: "ISO C90 forbids mixed declarations and code"
[-Werror=declaration-after-statement]. Patch by Victor Stinner.

@item 
gh-92651@footnote{https://github.com/python/cpython/issues/92651}: Remove the @code{token.h} header file. There was never any public
tokenizer C API. The @code{token.h} header file was only designed to be used
by Python internals. Patch by Victor Stinner.

@item 
gh-92536@footnote{https://github.com/python/cpython/issues/92536}: Remove legacy Unicode APIs based on @code{Py_UNICODE*}.

@item 
gh-85858@footnote{https://github.com/python/cpython/issues/85858}: Remove the @code{PyUnicode_InternImmortal()} function and the
@code{SSTATE_INTERNED_IMMORTAL} macro. Patch by Victor Stinner.

@item 
gh-92193@footnote{https://github.com/python/cpython/issues/92193}: Add new function @ref{54c,,PyFunction_SetVectorcall()} to the C API
which sets the vectorcall field of a given @ref{54d,,PyFunctionObject}.

Warning: extensions using this API must preserve the behavior of the
unaltered function!

@item 
gh-59121@footnote{https://github.com/python/cpython/issues/59121}: Fixed an assert that prevented @code{PyRun_InteractiveOne} from
providing tracebacks when parsing from the provided FD.

@item 
bpo-45383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45383}: The @ref{569,,PyType_FromSpec()} API will now find and use a
metaclass based on the provided bases. An error will be raised if there is
a metaclass conflict.
@end itemize

@node Python 3 11 0 beta 1,Python 3 11 0 alpha 7,Python 3 12 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-11-0-beta-1}@anchor{1781}
@subsection Python 3.11.0 beta 1


`Release date: 2022-05-06'

@menu
* Security: Security<17>. 
* Core and Builtins: Core and Builtins<25>. 
* Library: Library<24>. 
* Documentation: Documentation<19>. 
* Tests: Tests<22>. 
* Build: Build<24>. 
* Windows: Windows<21>. 
* macOS: macOS<16>. 
* Tools/Demos: Tools/Demos<13>. 
* C API: C API<23>. 

@end menu

@node Security<17>,Core and Builtins<25>,,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id199}@anchor{1782}
@subsubsection Security



@itemize -

@item 
gh-57684@footnote{https://github.com/python/cpython/issues/57684}: Add the @ref{58e,,-P} command line option and the
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} environment variable to not prepend a potentially
unsafe path to @ref{3ab,,sys.path}. Patch by Victor Stinner.
@end itemize

@node Core and Builtins<25>,Library<24>,Security<17>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id200}@anchor{1783}
@subsubsection Core and Builtins



@itemize -

@item 
gh-89519@footnote{https://github.com/python/cpython/issues/89519}: Chaining classmethod descriptors (introduced in bpo-19072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19072}) is
deprecated. It can no longer be used to wrap other descriptors such as
property().  The core design of this feature was flawed, and it caused a
number of downstream problems.

@item 
gh-92345@footnote{https://github.com/python/cpython/issues/92345}: @code{pymain_run_python()} now imports @code{readline} and
@code{rlcompleter} before sys.path is extended to include the current working
directory of an interactive interpreter. Non-interactive interpreters are
not affected.

@item 
bpo-43857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43857}: Improve the @ref{343,,AttributeError} message when deleting a
missing attribute. Patch by Géry Ogam.

@item 
gh-92245@footnote{https://github.com/python/cpython/issues/92245}: Make sure that PEP 523 is respected in all cases. In 3.11a7,
specialization may have prevented Python-to-Python calls respecting PEP
523.

@item 
gh-92203@footnote{https://github.com/python/cpython/issues/92203}: Add a closure keyword-only parameter to @ref{17d,,exec()}. It can
only be specified when exec-ing a code object that uses free variables.
When specified, it must be a tuple, with exactly the number of cell
variables referenced by the code object. closure has a default value of
@code{None}, and it must be @code{None} if the code object doesn't refer to any
free variables.

@item 
gh-91173@footnote{https://github.com/python/cpython/issues/91173}: Disable frozen modules in debug builds. Patch by Kumar Aditya.

@item 
gh-92114@footnote{https://github.com/python/cpython/issues/92114}: Improve error message when subscript a type with
@code{__class_getitem__} set to @code{None}.

@item 
gh-92112@footnote{https://github.com/python/cpython/issues/92112}: Fix crash triggered by an evil custom @code{mro()} on a metaclass.

@item 
gh-92063@footnote{https://github.com/python/cpython/issues/92063}: The @code{PRECALL_METHOD_DESCRIPTOR_FAST_WITH_KEYWORDS} instruction
now ensures methods are called only on objects of the correct type.

@item 
gh-92031@footnote{https://github.com/python/cpython/issues/92031}: Deoptimize statically allocated code objects during
@code{Py_FINALIZE()} so that future @code{_PyCode_Quicken} calls always start
with unquickened code.

@item 
gh-92036@footnote{https://github.com/python/cpython/issues/92036}: Fix a crash in subinterpreters related to the garbage collector.
When a subinterpreter is deleted, untrack all objects tracked by its GC.
To prevent a crash in deallocator functions expecting objects to be
tracked by the GC, leak a strong reference to these objects on purpose, so
they are never deleted and their deallocator functions are not called.
Patch by Victor Stinner.

@item 
gh-92032@footnote{https://github.com/python/cpython/issues/92032}: The interpreter can now autocomplete soft keywords, as of now
@code{match}, @code{case}, and @code{_} (wildcard pattern) from 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}.

@item 
gh-87999@footnote{https://github.com/python/cpython/issues/87999}: The warning emitted by the Python parser for a numeric literal
immediately followed by keyword has been changed from deprecation warning
to syntax warning.

@item 
gh-91869@footnote{https://github.com/python/cpython/issues/91869}: Fix an issue where specialized opcodes with extended arguments
could produce incorrect tracing output or lead to assertion failures.

@item 
gh-91603@footnote{https://github.com/python/cpython/issues/91603}: Speed up @ref{625,,types.UnionType} instantiation. Based on patch
provided by Yurii Karabas.

@item 
gh-89373@footnote{https://github.com/python/cpython/issues/89373}: If Python is built in debug mode, Python now ensures that
deallocator functions leave the current exception unchanged. Patch by
Victor Stinner.

@item 
gh-91632@footnote{https://github.com/python/cpython/issues/91632}: Fix a minor memory leak at exit: release the memory of the
@code{generic_alias_iterator} type. Patch by Donghee Na.

@item 
gh-81548@footnote{https://github.com/python/cpython/issues/81548}: Octal escapes with value larger than @code{0o377} now produce a
@ref{1a3,,DeprecationWarning}. In a future Python version they will be a
@ref{44f,,SyntaxWarning} and eventually a @ref{18b,,SyntaxError}.

@item 
bpo-43950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43950}: Use a single compact table for line starts, ends and column
offsets. Reduces memory consumption for location info by half

@item 
gh-91102@footnote{https://github.com/python/cpython/issues/91102}: Use Argument Clinic for @code{EncodingMap}.  Patch by Oleg
Iarygin.

@item 
gh-91636@footnote{https://github.com/python/cpython/issues/91636}: Fixed a crash in a garbage-collection edge-case, in which a
@code{PyFunction_Type.tp_clear} function could leave a python function object
in an inconsistent state.

@item 
gh-91603@footnote{https://github.com/python/cpython/issues/91603}: Speed up @ref{42b,,isinstance()} and @ref{7ab,,issubclass()} checks for
@ref{625,,types.UnionType}. Patch by Yurii Karabas.

@item 
gh-91625@footnote{https://github.com/python/cpython/issues/91625}: Fixed a bug in which adaptive opcodes ignored any preceding
@code{EXTENDED_ARG}s on specialization failure.

@item 
gh-78607@footnote{https://github.com/python/cpython/issues/78607}: The LLTRACE special build now looks for the name @code{__lltrace__}
defined in module globals, rather than the name @code{__ltrace__}, which had
been introduced as a typo.

@item 
gh-91576@footnote{https://github.com/python/cpython/issues/91576}: Speed up iteration of ascii strings by 50%. Patch by Kumar
Aditya.

@item 
gh-89279@footnote{https://github.com/python/cpython/issues/89279}: Improve interpreter performance on Windows by inlining a few
specific macros.

@item 
gh-91502@footnote{https://github.com/python/cpython/issues/91502}: Add a new @code{_PyFrame_IsEntryFrame()} API function, to
check if a @ref{773,,PyFrameObject} is an entry frame. Patch by Pablo
Galindo.

@item 
gh-91266@footnote{https://github.com/python/cpython/issues/91266}: Refactor the @code{bytearray} strip methods @code{strip}, @code{lstrip}
and @code{rstrip} to use a common implementation.

@item 
gh-91479@footnote{https://github.com/python/cpython/issues/91479}: Replaced the @code{__note__} field of @ref{5a5,,BaseException} (added
in an earlier version of 3.11) with the final design of 
@geindex Python Enhancement Proposals; PEP 678
PEP 678@footnote{https://peps.python.org/pep-0678/}.
Namely, @ref{5a5,,BaseException} gets an @code{add_note()} method, and its
@code{__notes__} field is created when necessary.

@item 
gh-46055@footnote{https://github.com/python/cpython/issues/46055}: Speed up right shift of negative integers, by removing
unnecessary creation of temporaries. Original patch by Xinhang Xu,
reworked by Mark Dickinson.

@item 
gh-91462@footnote{https://github.com/python/cpython/issues/91462}: Make the interpreter's low-level tracing (lltrace) feature
output more readable by displaying opcode names (rather than just
numbers), and by displaying stack contents before each opcode.

@item 
gh-89455@footnote{https://github.com/python/cpython/issues/89455}: Fixed an uninitialized bool value in the traceback printing code
path that was introduced by the initial bpo-45292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45292} exception groups work.

@item 
gh-91421@footnote{https://github.com/python/cpython/issues/91421}: Fix a potential integer overflow in _Py_DecodeUTF8Ex.

@item 
gh-91428@footnote{https://github.com/python/cpython/issues/91428}: Add @code{static const char *const _PyOpcode_OpName[256] = @{...@};}
to @code{opcode.h} for debug builds to assist in debugging the Python
interpreter. It is now more convenient to make various forms of debugging
output more human-readable by including opcode names rather than just the
corresponding decimal digits.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Make @ref{1677,,POP_JUMP_IF_TRUE}, @ref{1678,,POP_JUMP_IF_FALSE},
@ref{1784,,POP_JUMP_IF_NONE} and @ref{1785,,POP_JUMP_IF_NOT_NONE} virtual,
mapping to new relative jump opcodes.

@item 
bpo-45317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45317}: Add internal documentation explaining design of new (for 3.11)
frame stack.

@item 
bpo-47197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47197}: ctypes used to mishandle @code{void} return types, so that for
instance a function declared like @code{ctypes.CFUNCTYPE(None, ctypes.c_int)}
would be called with signature @code{int f(int)} instead of @code{void f(int)}.
Wasm targets require function pointers to be called with the correct
signatures so this led to crashes. The problem is now fixed.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Make opcodes @code{JUMP_IF_TRUE_OR_POP} and
@code{JUMP_IF_FALSE_OR_POP} relative rather than absolute.

@item 
bpo-47177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47177}: Replace the @code{f_lasti} member of the internal
@code{_PyInterpreterFrame} structure with a @code{prev_instr} pointer, which
reduces overhead in the main interpreter loop. The @code{f_lasti} attribute
of Python-layer frame objects is preserved for backward-compatibility.

@item 
bpo-46961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46961}: Integer mod/remainder operations, including the three-argument
form of @ref{9c0,,pow()}, now consistently return ints from the global small
integer cache when applicable.

@item 
bpo-46962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46962}: Classes and functions that unconditionally declared their
docstrings ignoring the @code{--without-doc-strings} compilation flag no
longer do so.

The classes affected are @code{ctypes.UnionType},
@ref{1786,,pickle.PickleBuffer}, @code{testcapi.RecursingInfinitelyError},
and @ref{7d5,,types.GenericAlias}.

The functions affected are 24 methods in @ref{2a,,ctypes}.

Patch by Oleg Iarygin.

@item 
bpo-46942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46942}: Use Argument Clinic for the @ref{1787,,types.MethodType}
constructor.  Patch by Oleg Iarygin.

@item 
bpo-46764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46764}: Fix wrapping bound methods with @@classmethod

@item 
bpo-43464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43464}: Optimize @code{set.intersection()} for non-set arguments.

@item 
bpo-46721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46721}: Optimize @code{set.issuperset()} for non-set argument.

@item 
bpo-46509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46509}: Add type-specialized versions of the @code{Py_DECREF()}, and use
them for @code{float}, @code{int}, @code{str}, @code{bool}, and @code{None} to avoid
pointer-chasing at runtime where types are known at C compile time.

@item 
bpo-46045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46045}: Do not use POSIX semaphores on NetBSD

@item 
bpo-36819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36819}: Fix crashes in built-in encoders with error handlers that
return position less or equal than the starting position of non-encodable
characters.

@item 
bpo-34093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34093}: @code{marshal.dumps()} uses @code{FLAG_REF} for all interned strings.
This makes output more deterministic and helps reproducible build.

@item 
bpo-26579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26579}: Added @code{object.__getstate__} which provides the default
implementation of the @code{__getstate__()} method.

Copying and pickling instances of subclasses of builtin types bytearray,
set, frozenset, collections.OrderedDict, collections.deque,
weakref.WeakSet, and datetime.tzinfo now copies and pickles instance
attributes implemented as slots.
@end itemize

@node Library<24>,Documentation<19>,Core and Builtins<25>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id201}@anchor{1788}
@subsubsection Library



@itemize -

@item 
gh-87901@footnote{https://github.com/python/cpython/issues/87901}: Add the `encoding' parameter to @ref{a75,,os.popen()}.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Fix an issue where @ref{38,,dis} utilities may interpret populated
inline cache entries as valid instructions.

@item 
gh-92332@footnote{https://github.com/python/cpython/issues/92332}: Deprecate @ref{300,,typing.Text} (removal of the class is
currently not planned). Patch by Alex Waygood.

@item 
Deprecate nested classes in enum definitions becoming members -- in 3.13
they will be normal classes; add @code{member} and @code{nonmember} functions to
allow control over results now.

@item 
gh-92356@footnote{https://github.com/python/cpython/issues/92356}: Fixed a performance regression in ctypes function calls.

@item 
gh-90997@footnote{https://github.com/python/cpython/issues/90997}: Show the actual named values stored in inline caches when
@code{show_caches=True} is passed to @ref{38,,dis} utilities.

@item 
gh-92301@footnote{https://github.com/python/cpython/issues/92301}: Prefer @code{close_range()} to iterating over procfs for file
descriptor closing in @ref{d5,,subprocess} for better performance.

@item 
gh-67248@footnote{https://github.com/python/cpython/issues/67248}: Sort the miscellaneous topics in Cmd.do_help()

@item 
gh-92210@footnote{https://github.com/python/cpython/issues/92210}: Port @code{socket.__init__} to Argument Clinic. Patch by Cinder.

@item 
gh-80010@footnote{https://github.com/python/cpython/issues/80010}: Add support for generalized ISO 8601 parsing to
@ref{602,,datetime.datetime.fromisoformat()},
@ref{600,,datetime.date.fromisoformat()} and
@ref{601,,datetime.time.fromisoformat()}. Patch by Paul Ganssle.

@item 
gh-92118@footnote{https://github.com/python/cpython/issues/92118}: Fix a 3.11 regression in @ref{11df,,contextmanager()},
which caused it to propagate exceptions with incorrect tracebacks.

@item 
gh-90887@footnote{https://github.com/python/cpython/issues/90887}: Adding @code{COPYFILE_STAT}, @code{COPYFILE_ACL} and
@code{COPYFILE_XATTR} constants for @code{os.fcopyfile()} available in macOs.

@item 
gh-91215@footnote{https://github.com/python/cpython/issues/91215}: For @ref{1c6,,@@dataclass}, add
`weakref_slot'. The new parameter defaults to @code{False}. If true, and if
@code{slots=True}, add a slot named @code{"__weakref__"}, which will allow
instances to be weakref'd. Contributed by Eric V. Smith

@item 
gh-85984@footnote{https://github.com/python/cpython/issues/85984}: New function os.login_tty() for Unix.

@item 
gh-92128@footnote{https://github.com/python/cpython/issues/92128}: Add @ref{725,,__class_getitem__()} to
@ref{12d3,,logging.LoggerAdapter} and @ref{11d5,,logging.StreamHandler},
allowing them to be parameterized at runtime. Patch by Alex Waygood.

@item 
gh-92049@footnote{https://github.com/python/cpython/issues/92049}: Forbid pickling constants @code{re._constants.SUCCESS} etc.
Previously, pickling did not fail, but the result could not be unpickled.

@item 
gh-92062@footnote{https://github.com/python/cpython/issues/92062}: @ref{1cb,,inspect.Parameter} now raises @ref{1ff,,ValueError} if
@code{name} is a keyword, in addition to the existing check that it is an
identifier.

@item 
gh-87390@footnote{https://github.com/python/cpython/issues/87390}: Add an @code{__unpacked__} attribute to
@ref{7d5,,types.GenericAlias}. Patch by Jelle Zijlstra.

@item 
gh-88089@footnote{https://github.com/python/cpython/issues/88089}: Add support for generic @ref{2ad,,typing.NamedTuple}.

@item 
gh-91996@footnote{https://github.com/python/cpython/issues/91996}: New http.HTTPMethod enum to represent all the available HTTP
request methods in a convenient way

@item 
gh-91984@footnote{https://github.com/python/cpython/issues/91984}: Modified test strings in test_argparse.py to not contain
trailing spaces before end of line.

@item 
gh-91952@footnote{https://github.com/python/cpython/issues/91952}: Add @code{encoding="locale"} support to
@code{TextIOWrapper.reconfigure()}.

@item 
gh-91954@footnote{https://github.com/python/cpython/issues/91954}: Add `encoding' and `errors' arguments to
@ref{1789,,subprocess.getoutput()} and @ref{fad,,subprocess.getstatusoutput()}.

@item 
bpo-47029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47029}: Always close the read end of the pipe used by
@ref{178a,,multiprocessing.Queue} `after' the last write of buffered data to
the write end of the pipe to avoid @ref{1045,,BrokenPipeError} at garbage
collection and at @ref{178b,,multiprocessing.Queue.close()} calls. Patch by Géry
Ogam.

@item 
gh-91928@footnote{https://github.com/python/cpython/issues/91928}: Add @code{datetime.UTC} alias for @code{datetime.timezone.utc}.

Patch by Kabir Kwatra.

@item 
gh-68966@footnote{https://github.com/python/cpython/issues/68966}: The @code{mailcap} module is now deprecated and will be removed
in Python 3.13. See 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/} for the rationale and the @ref{8e,,mimetypes}
module for an alternative. Patch by Victor Stinner.

@item 
gh-91401@footnote{https://github.com/python/cpython/issues/91401}: Provide a way to disable @ref{d5,,subprocess} use of @code{vfork()}
just in case it is ever needed and document the existing mechanism for
@code{posix_spawn()}.

@item 
gh-64783@footnote{https://github.com/python/cpython/issues/64783}: Fix @ref{178c,,signal.NSIG} value on FreeBSD to accept signal
numbers greater than 32, like @code{signal.SIGRTMIN} and
@code{signal.SIGRTMAX}. Patch by Victor Stinner.

@item 
gh-91910@footnote{https://github.com/python/cpython/issues/91910}: Add missing f prefix to f-strings in error messages from the
@ref{93,,multiprocessing} and @ref{a,,asyncio} modules.

@item 
gh-91860@footnote{https://github.com/python/cpython/issues/91860}: Add @ref{4bd,,typing.dataclass_transform()}, implementing 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/}.
Patch by Jelle Zijlstra.

@item 
gh-91832@footnote{https://github.com/python/cpython/issues/91832}: Add @code{required} attribute to @ref{178d,,argparse.Action} repr
output.

@item 
gh-91827@footnote{https://github.com/python/cpython/issues/91827}: In the @ref{ef,,tkinter} module add method @code{info_patchlevel()}
which returns the exact version of the Tcl library as a named tuple
similar to @ref{68b,,sys.version_info}.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: Add @ref{178e,,--enable-wasm-pthreads} to enable pthreads support
for WASM builds. @code{Emscripten/node} no longer has threading enabled by
default. Include additional file systems.

@item 
gh-91821@footnote{https://github.com/python/cpython/issues/91821}: Fix unstable @code{test_from_tuple} test in @code{test_decimal.py}.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the xdrlib module.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the uu module.

@item 
gh-91760@footnote{https://github.com/python/cpython/issues/91760}: More strict rules will be applied for numerical group references
and group names in regular expressions. For now, a deprecation warning is
emitted for group references and group names which will be errors in
future Python versions.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: Add provisional @ref{178f,,sys._emscripten_info} named tuple with
build-time and run-time information about Emscripten platform.

@item 
gh-90623@footnote{https://github.com/python/cpython/issues/90623}: @ref{1790,,signal.raise_signal()} and @ref{133e,,os.kill()} now check
immediately for pending signals. Patch by Victor Stinner.

@item 
gh-91734@footnote{https://github.com/python/cpython/issues/91734}: Fix OSS audio support on Solaris.

@item 
gh-90633@footnote{https://github.com/python/cpython/issues/90633}: Include the passed value in the exception thrown by
@ref{692,,typing.assert_never()}. Patch by Jelle Zijlstra.

@item 
gh-91700@footnote{https://github.com/python/cpython/issues/91700}: Compilation of regular expression containing a conditional
expression @code{(?(group)...)} now raises an appropriate @code{re.error} if
the group number refers to not defined group. Previously an internal
RuntimeError was raised.

@item 
gh-91231@footnote{https://github.com/python/cpython/issues/91231}: Add an optional keyword `shutdown_timeout' parameter to the
@code{multiprocessing.BaseManager} constructor. Kill the process if
terminate() takes longer than the timeout. Patch by Victor Stinner.

@item 
gh-91621@footnote{https://github.com/python/cpython/issues/91621}: Fix @ref{69c,,typing.get_type_hints()} for
@ref{7d4,,collections.abc.Callable}. Patch by Shantanu Jain.

@item 
gh-90568@footnote{https://github.com/python/cpython/issues/90568}: Parsing @code{\N} escapes of Unicode Named Character Sequences in a
@ref{b8,,regular expression} raises now @code{re.error} instead of
@code{TypeError}.

@item 
gh-91670@footnote{https://github.com/python/cpython/issues/91670}: Remove deprecated @code{SO} config variable in @ref{da,,sysconfig}.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the telnetlib module.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the sunau module.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the spwd module.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the sndhdr module, as well as inline needed
functionality for @code{email.mime.MIMEAudio}.

@item 
gh-91616@footnote{https://github.com/python/cpython/issues/91616}: @ref{b8,,re} module, fix @ref{1791,,fullmatch()} mismatch
when using Atomic Grouping or Possessive Quantifiers.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the 'pipes' module.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the ossaudiodev module.

@item 
bpo-47256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47256}: @ref{b8,,re} module, limit the maximum capturing group to
1,073,741,823 in 64-bit build, this increases the depth of backtracking.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the nis module.

@item 
gh-91595@footnote{https://github.com/python/cpython/issues/91595}: Fix the comparison of character and integer inside
@code{Tools.gdb.libpython.write_repr()}. Patch by Yu Liu.

@item 
gh-74166@footnote{https://github.com/python/cpython/issues/74166}: Add option to raise all errors from
@ref{65d,,create_connection()} in an @ref{1b4,,ExceptionGroup} when it
fails to create a connection. The default remains to raise only the last
error that had occurred when multiple addresses were tried.

@item 
gh-91487@footnote{https://github.com/python/cpython/issues/91487}: Optimize asyncio UDP speed, over 100 times faster when
transferring a large file.

@item 
gh-91575@footnote{https://github.com/python/cpython/issues/91575}: Update case-insensitive matching in the @ref{b8,,re} module to the
latest Unicode version.

@item 
gh-90622@footnote{https://github.com/python/cpython/issues/90622}: In @code{concurrent.futures.process.ProcessPoolExecutor} disallow
the "fork" multiprocessing start method when the new
@code{max_tasks_per_child} feature is used as the mix of threads+fork can
hang the child processes. Default to using the safe "spawn" start method
in that circumstance if no @code{mp_context} was supplied.

@item 
gh-89022@footnote{https://github.com/python/cpython/issues/89022}: In @ref{ce,,sqlite3}, @code{SQLITE_MISUSE} result codes are now mapped
to @ref{668,,InterfaceError} instead of
@ref{4dc,,ProgrammingError}. Also, more accurate exceptions are
raised when binding parameters fail. Patch by Erlend E. Aasland.

@item 
gh-91526@footnote{https://github.com/python/cpython/issues/91526}: Stop calling @code{os.device_encoding(file.fileno())} in
@code{TextIOWrapper}. It was complex, never documented, and didn't work
for most cases. (Patch by Inada Naoki.)

@item 
gh-88116@footnote{https://github.com/python/cpython/issues/88116}: Change the frame-related functions in the @ref{7d,,inspect} module
to return a regular object (that is backwards compatible with the old
tuple-like interface) that include the extended 
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/} position
information (end line number, column and end column). The affected
functions are: @ref{63a,,inspect.getframeinfo()},
@ref{63b,,inspect.getouterframes()}, @ref{63c,,inspect.getinnerframes()},
@ref{63d,,inspect.stack()} and @ref{63e,,inspect.trace()}. Patch by Pablo Galindo.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Add indexing and slicing support to @ref{66d,,sqlite3.Blob}. Patch
by Aviv Palivoda and Erlend E. Aasland.

@item 
gh-69093@footnote{https://github.com/python/cpython/issues/69093}: Add @ref{5be,,context manager} support to @ref{66d,,sqlite3.Blob}.
Patch by Aviv Palivoda and Erlend E. Aasland.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate nntplib.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate msilib.

@item 
gh-91404@footnote{https://github.com/python/cpython/issues/91404}: Improve the performance of @ref{b8,,re} matching by using computed
gotos (or "threaded code") on supported platforms and removing expensive
pointer indirections.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the imghdr module.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the crypt module.

@item 
gh-91276@footnote{https://github.com/python/cpython/issues/91276}: Make space for longer opcodes in @ref{38,,dis} output.

@item 
bpo-47000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47000}: Make @code{TextIOWrapper} uses locale encoding when
@code{encoding="locale"} is specified even in UTF-8 mode.

@item 
gh-91230@footnote{https://github.com/python/cpython/issues/91230}: @ref{570,,warnings.catch_warnings()} now accepts arguments for
@ref{6ac,,warnings.simplefilter()}, providing a more concise way to locally
ignore warnings or convert them to errors.

@item 
gh-91217@footnote{https://github.com/python/cpython/issues/91217}: Deprecate the chunk module.

@item 
Add the @code{TCP_CONNECTION_INFO} option (available on macOS) to
@ref{cb,,socket}.

@item 
bpo-47260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47260}: Fix @code{os.closerange()} potentially being a no-op in a Linux
seccomp sandbox.

@item 
bpo-47087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47087}: Implement @code{typing.Required} and @code{typing.NotRequired}
(
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/}). Patch by David Foster and Jelle Zijlstra.

@item 
bpo-47061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47061}: Deprecate cgi and cgitb.

@item 
bpo-47061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47061}: Deprecate audioop.

@item 
bpo-47000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47000}: Add @ref{2db,,locale.getencoding()} to get the current locale
encoding. It is similar to @code{locale.getpreferredencoding(False)} but
ignores the @ref{641,,Python UTF-8 Mode}.

@item 
bpo-42012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42012}: Add @ref{11b,,wsgiref.types}, containing WSGI-specific types for
static type checking.

@item 
bpo-47227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47227}: Suppress expression chaining for more @ref{b8,,re} parsing errors.

@item 
bpo-47211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47211}: Remove undocumented and never working function
@code{re.template()} and flag @code{re.TEMPLATE}. This was later reverted in
3.11.0b2 and deprecated instead.

@item 
bpo-47135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47135}: @ref{1792,,decimal.localcontext()} now accepts context attributes via
keyword arguments

@item 
bpo-43323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43323}: Fix errors in the @ref{3b,,email} module if the charset itself
contains undecodable/unencodable characters.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Disassembly of quickened code.

@item 
bpo-46681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46681}: Forward gzip.compress() compresslevel to zlib.

@item 
bpo-45100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45100}: Add @ref{699,,typing.get_overloads()} and
@ref{69a,,typing.clear_overloads()}. Patch by Jelle Zijlstra.

@item 
bpo-44807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44807}: @ref{261,,typing.Protocol} no longer silently replaces
@code{__init__()} methods defined on subclasses. Patch by Adrian Garcia
Badaracco.

@item 
bpo-46787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46787}: Fix @ref{8db,,concurrent.futures.ProcessPoolExecutor} exception
memory leak

@item 
bpo-46720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46720}: Add support for path-like objects to
@ref{1793,,multiprocessing.set_executable()} for Windows to be on a par with
Unix-like systems. Patch by Géry Ogam.

@item 
bpo-46696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46696}: Add @code{SO_INCOMING_CPU} constant to @ref{cb,,socket}.

@item 
bpo-46053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46053}: Fix OSS audio support on NetBSD.

@item 
bpo-45639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45639}: @code{image/avif} and @code{image/webp} were added to
@ref{8e,,mimetypes}.

@item 
bpo-46285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46285}: Add command-line option @code{-p}/@code{--protocol} to module
@ref{71,,http.server} which specifies the HTTP version to which the server is
conformant (HTTP/1.1 conformant servers can now be run from the
command-line interface of module @ref{71,,http.server}). Patch by Géry Ogam.

@item 
bpo-44791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44791}: Accept ellipsis as the last argument of
@ref{7ae,,typing.Concatenate}.

@item 
bpo-46547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46547}: Remove variables leaking into @code{pydoc.Helper} class namespace.

@item 
bpo-46415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46415}: Fix ipaddress.ip_@{address,interface,network@} raising TypeError
instead of ValueError if given invalid tuple as address parameter.

@item 
bpo-46075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46075}: @code{CookieJar} with @code{DefaultCookiePolicy} now can process
cookies from localhost with domain=localhost explicitly specified in
Set-Cookie header.

@item 
bpo-45995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45995}: Add a "z" option to the string formatting specification that
coerces negative zero floating-point values to positive zero after
rounding to the format precision.  Contributed by John Belmonte.

@item 
bpo-26175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26175}: Fully implement the @ref{67f,,io.BufferedIOBase} or
@ref{680,,io.TextIOBase} interface for
@ref{67e,,tempfile.SpooledTemporaryFile} objects. This lets them work
correctly with higher-level layers (like compression modules). Patch by
Carey Metcalfe.

@item 
bpo-45138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45138}: Fix a regression in the @ref{ce,,sqlite3} trace callback where
bound parameters were not expanded in the passed statement string. The
regression was introduced in Python 3.10 by bpo-40318@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40318}. Patch by
Erlend E. Aasland.

@item 
bpo-44863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44863}: Allow @ref{161,,TypedDict} subclasses to also include
@ref{15a1,,Generic} as a base class in class based syntax. Thereby
allowing the user to define a generic @code{TypedDict}, just like a
user-defined generic but with @code{TypedDict} semantics.

@item 
bpo-44587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44587}: Fix BooleanOptionalAction to not automatically add a default
string.  If a default string is desired, use a formatter to add it.

@item 
bpo-43827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43827}: All positional-or-keyword parameters to @code{ABCMeta.__new__} are
now positional-only to avoid conflicts with keyword arguments to be passed
to @code{__init_subclass__()}.

@item 
bpo-43218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43218}: Prevent creation of a venv whose path contains the PATH
separator. This could affect the usage of the activate script. Patch by
Dustin Rodrigues.

@item 
bpo-38435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38435}: Add a @code{process_group} parameter to @ref{197,,subprocess.Popen}
to help move more things off of the unsafe @code{preexec_fn} parameter.

@item 
bpo-42066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42066}: Fix cookies getting sorted in @code{CookieJar.__iter__()} which
is an extra behavior and not mentioned in RFC 2965 or Netscape cookie
protocol. Now the cookies in @code{CookieJar} follows the order of the
@code{Set-Cookie} header. Patch by Iman Kermani.

@item 
bpo-40617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40617}: Add @ref{66b,,create_window_function()} to
@ref{242,,sqlite3.Connection} for creating aggregate window functions. Patch
by Erlend E. Aasland.

@item 
bpo-40676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40676}: Convert @ref{29,,csv} to use Argument Clinic for
@ref{1794,,csv.field_size_limit()}, @ref{1795,,csv.get_dialect()},
@ref{1796,,csv.unregister_dialect()} and @ref{1797,,csv.list_dialects()}.

@item 
bpo-39716@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39716}: Raise an @code{ArgumentError} when the same subparser name is
added twice to an @code{argparse.ArgumentParser}.  This is consistent with
the (default) behavior when the same option string is added twice to an
@code{ArgumentParser}.

@item 
bpo-36073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36073}: Raise @ref{4dc,,ProgrammingError} instead of segfaulting
on recursive usage of cursors in @ref{ce,,sqlite3} converters. Patch by
Sergey Fedoseev.

@item 
bpo-34975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34975}: Adds a @code{start_tls()} method to
@code{StreamWriter}, which upgrades the connection with
TLS using the given @ref{291,,SSLContext}.

@item 
bpo-22276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22276}: @ref{226,,Path} methods @ref{22a,,glob()} and
@ref{22b,,rglob()} return only directories if `pattern' ends with
a pathname components separator (@code{/} or @ref{655,,sep}). Patch by
Eisuke Kawashima.

@item 
bpo-24905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24905}: Add @ref{66c,,blobopen()} to
@ref{242,,sqlite3.Connection}. @ref{66d,,sqlite3.Blob} allows incremental I/O
operations on blobs. Patch by Aviv Palivoda and Erlend E. Aasland.
@end itemize

@node Documentation<19>,Tests<22>,Library<24>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id202}@anchor{1798}
@subsubsection Documentation



@itemize -

@item 
gh-91888@footnote{https://github.com/python/cpython/issues/91888}: Add a new @code{gh} role to the documentation to link to GitHub
issues.

@item 
gh-91783@footnote{https://github.com/python/cpython/issues/91783}: Document security issues concerning the use of the function
@ref{455,,shutil.unpack_archive()}

@item 
gh-91547@footnote{https://github.com/python/cpython/issues/91547}: Remove "Undocumented modules" page.

@item 
gh-91298@footnote{https://github.com/python/cpython/issues/91298}: In @code{importlib.resources.abc}, refined the documentation of the
Traversable Protocol, applying changes from importlib_resources 5.7.1.

@item 
bpo-44347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44347}: Clarify the meaning of `dirs_exist_ok', a kwarg of
@ref{a17,,shutil.copytree()}.

@item 
bpo-36329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36329}: Remove 'make -C Doc serve' in favour of 'make -C Doc htmlview'

@item 
bpo-47189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47189}: Add a What's New in Python 3.11 entry for the Faster CPython
project. Documentation by Ken Jin and Kumar Aditya.

@item 
bpo-38668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38668}: Update the introduction to documentation for @ref{a1,,os.path} to
remove warnings that became irrelevant after the implementations of
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/} and 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/}.

@item 
bpo-47115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47115}: The documentation now lists which members of C structs are part
of the @ref{53e,,Limited API/Stable ABI}.

@item 
bpo-46962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46962}: All docstrings in code snippets are now wrapped into
@ref{1799,,PyDoc_STR} to follow the guideline of 
@geindex Python Enhancement Proposals; PEP 0007#documentation-strings
PEP 7's Documentation Strings paragraph@footnote{https://peps.python.org/pep-0007/#documentation-strings}. Patch by
Oleg Iarygin.

@item 
bpo-26792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26792}: Improve the docstrings of @ref{179a,,runpy.run_module()} and
@ref{17f,,runpy.run_path()}. Original patch by Andrew Brezovsky.
@end itemize

@node Tests<22>,Build<24>,Documentation<19>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id203}@anchor{179b}
@subsubsection Tests



@itemize -

@item 
gh-92169@footnote{https://github.com/python/cpython/issues/92169}: Use @code{warnings_helper.import_deprecated()} to import deprecated
modules uniformly in tests. Patch by Hugo van Kemenade.

@item 
gh-84461@footnote{https://github.com/python/cpython/issues/84461}: When multiprocessing is enabled, libregrtest can now use a
Python executable other than @code{sys.executable} via the @code{--python}
flag.

@item 
gh-91904@footnote{https://github.com/python/cpython/issues/91904}: Fix initialization of 
@geindex PYTHONREGRTEST_UNICODE_GUARD
@geindex variable d'environnement; PYTHONREGRTEST_UNICODE_GUARD
@code{PYTHONREGRTEST_UNICODE_GUARD}
which prevented running regression tests on non-UTF-8 locale.

@item 
gh-91752@footnote{https://github.com/python/cpython/issues/91752}: Added @@requires_zlib to test.test_tools.test_freeze.TestFreeze.

@item 
gh-91607@footnote{https://github.com/python/cpython/issues/91607}: Fix @code{test_concurrent_futures} to test the correct
multiprocessing start method context in several cases where the test logic
mixed this up.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Threading tests are now skipped on WASM targets without pthread
support.

@item 
bpo-47109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47109}: Test for @code{ctypes.macholib.dyld},
@code{ctypes.macholib.dylib}, and @code{ctypes.macholib.framework} are
brought from manual pre-@ref{105,,unittest} times to @code{ctypes.test}
location and structure. Patch by Oleg Iarygin.

@item 
bpo-29890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29890}: Add tests for @ref{179c,,ipaddress.IPv4Interface} and
@ref{179d,,ipaddress.IPv6Interface} construction with tuple arguments.
Original patch and tests by louisom.
@end itemize

@node Build<24>,Windows<21>,Tests<22>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id204}@anchor{179e}
@subsubsection Build



@itemize -

@item 
gh-89452@footnote{https://github.com/python/cpython/issues/89452}: gdbm-compat is now preferred over ndbm if both are available on
the system. This allows avoiding the problematic ndbm.h on macOS.

@item 
gh-91731@footnote{https://github.com/python/cpython/issues/91731}: Python is now built with @code{-std=c11} compiler option, rather
than @code{-std=c99}. Patch by Victor Stinner.

@item 
bpo-47152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47152}: Add script and make target for generating @code{sre_constants.h}.

@item 
bpo-47103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47103}: Windows @code{PGInstrument} builds now copy a required DLL into
the output directory, making it easier to run the profile stage of a PGO
build.
@end itemize

@node Windows<21>,macOS<16>,Build<24>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id205}@anchor{179f}
@subsubsection Windows



@itemize -

@item 
bpo-46907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46907}: Update Windows installer to use SQLite 3.38.3.

@item 
bpo-47239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47239}: Fixed --list and --list-paths output for @ref{5a8,,Lanceur Python pour Windows} when
used in an active virtual environment.

@item 
bpo-46907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46907}: Update Windows installer to use SQLite 3.38.2.

@item 
bpo-46785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46785}: Fix race condition between @ref{48a,,os.stat()} and unlinking a file
on Windows, by using errors codes returned by @code{FindFirstFileW()} when
appropriate in @code{win32_xstat_impl}.

@item 
bpo-40859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40859}: Update Windows build to use xz-5.2.5
@end itemize

@node macOS<16>,Tools/Demos<13>,Windows<21>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id206}@anchor{17a0}
@subsubsection macOS



@itemize -

@item 
bpo-46907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46907}: Update macOS installer to SQLite 3.38.4.
@end itemize

@node Tools/Demos<13>,C API<23>,macOS<16>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id207}@anchor{17a1}
@subsubsection Tools/Demos



@itemize -

@item 
gh-91583@footnote{https://github.com/python/cpython/issues/91583}: Fix regression in the code generated by Argument Clinic for
functions with the @code{defining_class} parameter.

@item 
gh-91575@footnote{https://github.com/python/cpython/issues/91575}: Add script @code{Tools/scripts/generate_re_casefix.py} and the make
target @code{regen-re} for generating additional data for case-insensitive
matching according to the current Unicode version.

@item 
gh-91551@footnote{https://github.com/python/cpython/issues/91551}: Remove the ancient Pynche color editor.  It has moved to
@indicateurl{https://gitlab.com/warsaw/pynche}
@end itemize

@node C API<23>,,Tools/Demos<13>,Python 3 11 0 beta 1
@anchor{whatsnew/changelog id208}@anchor{17a2}
@subsubsection C API



@itemize -

@item 
gh-88279@footnote{https://github.com/python/cpython/issues/88279}: Deprecate the C functions: @code{PySys_SetArgv()},
@code{PySys_SetArgvEx()}, @code{PySys_SetPath()}. Patch by Victor
Stinner.

@item 
gh-92154@footnote{https://github.com/python/cpython/issues/92154}: Added the @ref{762,,PyCode_GetCode()} function. This function does
the equivalent of the Python code @code{getattr(code_object, 'co_code')}.

@item 
gh-92173@footnote{https://github.com/python/cpython/issues/92173}: Fix the @code{closure} argument to @ref{16f7,,PyEval_EvalCodeEx()}.

@item 
gh-91320@footnote{https://github.com/python/cpython/issues/91320}: Fix C++ compiler warnings about "old-style cast" (@code{g++
-Wold-style-cast}) in the Python C API. Use C++ @code{reinterpret_cast<>}
and @code{static_cast<>} casts when the Python C API is used in C++. Patch by
Victor Stinner.

@item 
gh-80527@footnote{https://github.com/python/cpython/issues/80527}: Mark functions as deprecated by 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/}:
@code{PyUnicode_AS_DATA()}, @code{PyUnicode_AS_UNICODE()},
@code{PyUnicode_GET_DATA_SIZE()}, @code{PyUnicode_GET_SIZE()}. Patch
by Victor Stinner.

@item 
gh-91768@footnote{https://github.com/python/cpython/issues/91768}: @ref{896,,Py_REFCNT()}, @ref{76a,,Py_TYPE()}, @ref{76c,,Py_SIZE()} and
@ref{17a3,,Py_IS_TYPE()} functions argument type is now @code{PyObject*}, rather
than @code{const PyObject*}. Patch by Victor Stinner.

@item 
gh-91020@footnote{https://github.com/python/cpython/issues/91020}: Add @code{PyBytes_Type.tp_alloc} to initialize
@code{PyBytesObject.ob_shash} for bytes subclasses.

@item 
bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}: Add @code{PyFrame_GetLasti} C-API function to access frame
object's @code{f_lasti} attribute safely from C code.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: Remove the @code{Include/code.h} header file. C extensions should
only include the main @code{<Python.h>} header file. Patch by Victor Stinner.

@item 
bpo-47169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47169}: @ref{17a4,,PyOS_CheckStack()} is now exported in the Stable ABI on
Windows.

@item 
bpo-47169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47169}: @code{PyThread_get_thread_native_id()} is excluded from the
stable ABI on platforms where it doesn't exist (like Solaris).

@item 
bpo-46343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46343}: Added @ref{759,,PyErr_GetHandledException()} and
@ref{75a,,PyErr_SetHandledException()} as simpler alternatives to
@ref{75c,,PyErr_GetExcInfo()} and @ref{75b,,PyErr_SetExcInfo()}.

They are included in the stable ABI.
@end itemize

@node Python 3 11 0 alpha 7,Python 3 11 0 alpha 6,Python 3 11 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-7}@anchor{17a5}
@subsection Python 3.11.0 alpha 7


`Release date: 2022-04-05'

@menu
* Core and Builtins: Core and Builtins<26>. 
* Library: Library<25>. 
* Documentation: Documentation<20>. 
* Tests: Tests<23>. 
* Build: Build<25>. 
* Windows: Windows<22>. 
* macOS: macOS<17>. 
* Tools/Demos: Tools/Demos<14>. 
* C API: C API<24>. 

@end menu

@node Core and Builtins<26>,Library<25>,,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id209}@anchor{17a6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-47212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47212}: Raise @ref{792,,IndentationError} instead of @ref{18b,,SyntaxError} for
a bare @code{except} with no following indent. Improve @ref{18b,,SyntaxError}
locations for an un-parenthesized generator used as arguments. Patch by
Matthieu Dartiailh.

@item 
bpo-47186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47186}: Replace @code{JUMP_IF_NOT_EG_MATCH} by
@ref{6ec,,CHECK_EG_MATCH} + jump.

@item 
bpo-47176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47176}: Emscripten builds cannot handle signals in the usual way due to
platform limitations. Python can now handle signals. To use, set
Module.Py_EmscriptenSignalBuffer to be a single byte SharedArrayBuffer and
set Py_EMSCRIPTEN_SIGNAL_HANDLING to 1. Writing a number into the
SharedArrayBuffer will cause the corresponding signal to be raised into
the Python thread.

@item 
bpo-47186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47186}: Replace @code{JUMP_IF_NOT_EXC_MATCH} by
@ref{6f5,,CHECK_EXC_MATCH} + jump.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Replace the absolute jump opcode @ref{17a7,,JUMP_NO_INTERRUPT} by
the relative @ref{6e9,,JUMP_BACKWARD_NO_INTERRUPT}.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Avoid unnecessary allocations when comparing code objects.

@item 
bpo-47182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47182}: Fix a crash when using a named unicode character like
@code{"\N@{digit nine@}"} after the main interpreter has been initialized a
second time.

@item 
bpo-47162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47162}: WebAssembly cannot deal with bad function pointer casts
(different count or types of arguments). Python can now use call
trampolines to mitigate the problem. Define @code{PY_CALL_TRAMPOLINE}
to enable call trampolines.

@item 
bpo-46775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46775}: Some Windows system error codes(>= 10000) are now mapped into
the correct errno and may now raise a subclass of @ref{40d,,OSError}. Patch by
Donghee Na.

@item 
bpo-47129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47129}: Improve error messages in f-string syntax errors concerning
empty expressions.

@item 
bpo-47117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47117}: Fix a crash if we fail to decode characters in interactive mode
if the tokenizer buffers are uninitialized. Patch by Pablo Galindo.

@item 
bpo-47127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47127}: Speed up calls to c functions with keyword arguments by 25%
with specialization. Patch by Kumar Aditya.

@item 
bpo-47120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47120}: Replaced @code{JUMP_ABSOLUTE} by the relative jump
@ref{6f6,,JUMP_BACKWARD}.

@item 
bpo-42197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42197}: @code{PyFrame_FastToLocalsWithError()} and
@code{PyFrame_LocalsToFast()} are no longer called during profiling nor
tracing. C code can access the @code{f_locals} attribute of
@ref{773,,PyFrameObject} by calling @ref{415,,PyFrame_GetLocals()}.

@item 
bpo-47070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47070}: Improve performance of @code{array_inplace_repeat} by reducing the
number of invocations of @code{memcpy}. Refactor the @code{repeat} and inplace
@code{repeat} methods of @code{array}, @code{bytes}, @code{bytearray} and
@code{unicodeobject} to use the common @code{_PyBytes_Repeat}.

@item 
bpo-47053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47053}: Reduce de-optimization in the specialized
@code{BINARY_OP_INPLACE_ADD_UNICODE} opcode.

@item 
bpo-47045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47045}: Remove the @code{f_state} field from the _PyInterpreterFrame
struct. Add the @code{owner} field to the _PyInterpreterFrame struct to make
ownership explicit to simplify clearing and deallocing frames and
generators.

@item 
bpo-46968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46968}: Check for the existence of the "sys/auxv.h" header in
@ref{57,,faulthandler} to avoid compilation problems in systems where this
header doesn't exist. Patch by Pablo Galindo

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Use low bit of @code{LOAD_GLOBAL} to indicate whether to push a
@code{NULL} before the global. Helps streamline the call sequence a bit.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Quicken bytecode in-place by storing it as part of the
corresponding @code{PyCodeObject}.

@item 
bpo-47012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47012}: Speed up iteration of @ref{1bd,,bytes} and @ref{528,,bytearray} by
30%. Patch by Kumar Aditya.

@item 
bpo-47009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47009}: Improved the performance of @code{list.append()} and list
comprehensions by optimizing for the common case, where no resize is
needed. Patch by Dennis Sweeney.

@item 
bpo-47005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47005}: Improve performance of @code{bytearray_repeat} and
@code{bytearray_irepeat} by reducing the number of invocations of @code{memcpy}.

@item 
bpo-46829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46829}: Deprecate passing a message into @ref{17a8,,asyncio.Future.cancel()}
and @ref{1b5,,asyncio.Task.cancel()}

@item 
bpo-46993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46993}: Speed up @ref{528,,bytearray} creation from @ref{5fc,,list} and
@ref{366,,tuple} by 40%. Patch by Kumar Aditya.

@item 
bpo-39829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39829}: Removed the @code{__len__()} call when initializing a list and
moved initializing to @code{list_extend}. Patch by Jeremiah Pascual.

@item 
bpo-46944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46944}: Speed up throwing exception in generator with
@ref{15b0,,METH_FASTCALL} calling convention. Patch by Kumar Aditya.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Modify @ref{17a9,,STORE_SUBSCR} to use an inline cache entry
(rather than its oparg) as an adaptive counter.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline caching for @code{PRECALL} and @ref{6f1,,CALL},
and remove the internal machinery for managing the (now unused) non-inline
caches.

@item 
bpo-46881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46881}: Statically allocate and initialize the latin1 characters.

@item 
bpo-46838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46838}: Improve syntax errors for incorrect function definitions. Patch
by Pablo Galindo

@item 
bpo-43721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43721}: Fix docstrings of @ref{15e3,,getter},
@ref{15e4,,setter}, and @ref{15e5,,deleter} to clarify that
they create a new copy of the property.

@item 
bpo-43224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43224}: Make grammar changes required for PEP 646.
@end itemize

@node Library<25>,Documentation<20>,Core and Builtins<26>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id210}@anchor{17aa}
@subsubsection Library



@itemize -

@item 
bpo-47208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47208}: Allow vendors to override @code{CTYPES_MAX_ARGCOUNT}.

@item 
bpo-23689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23689}: @ref{b8,,re} module: fix memory leak when a match is terminated by
a signal or memory allocation failure. Patch by Ma Lin.

@item 
bpo-47167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47167}: Allow overriding a future compliance check in
@ref{4c2,,asyncio.Task}.

@item 
bpo-47151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47151}: When subprocess tries to use vfork, it now falls back to fork
if vfork returns an error. This allows use in situations where vfork isn't
allowed by the OS kernel.

@item 
bpo-47152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47152}: Convert the @ref{b8,,re} module into a package. Deprecate modules
@code{sre_compile}, @code{sre_constants} and @code{sre_parse}.

@item 
bpo-4833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4833}: Add @code{ZipFile.mkdir()}

@item 
bpo-27929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27929}: Fix @ref{db7,,asyncio.loop.sock_connect()} to only resolve names for
@ref{17ab,,socket.AF_INET} or @ref{17ac,,socket.AF_INET6} families. Resolution
may not make sense for other families, like @code{socket.AF_BLUETOOTH}
and @ref{17ad,,socket.AF_UNIX}.

@item 
bpo-14265@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14265}: Adds the fully qualified test name to unittest output

@item 
bpo-47061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47061}: Deprecate the aifc module.

@item 
bpo-39622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39622}: Handle Ctrl+C in asyncio programs to interrupt the main task.

@item 
bpo-47101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47101}: @ref{134b,,hashlib.algorithms_available} now lists only algorithms
that are provided by activated crypto providers on OpenSSL 3.0. Legacy
algorithms are not listed unless the legacy provider has been loaded into
the default OSSL context.

@item 
bpo-47099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47099}: All @code{URLError} exception messages raised in
@ref{303,,urllib.request.URLopener} now contain a colon between @code{ftp
error} and the rest of the message. Previously,
@code{open_ftp()} missed the colon. Patch by Oleg
Iarygin.

@item 
bpo-47099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47099}: Exception chaining is changed from
@code{Exception.with_traceback()}/@ref{675,,sys.exc_info()} to 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/}.
Patch by Oleg Iarygin.

@item 
bpo-47095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47095}: @ref{67,,hashlib}'s internal @code{_blake2} module now prefers
@code{libb2} from @indicateurl{https://www.blake2.net/} over Python's vendored copy of
blake2.

@item 
bpo-47098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47098}: The Keccak Code Package for @ref{67,,hashlib}'s internal @code{_sha3}
module has been replaced with tiny_sha3. The module is used as fallback
when Python is built without OpenSSL.

@item 
bpo-47088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47088}: Implement @ref{5b4,,typing.LiteralString}, part of 
@geindex Python Enhancement Proposals; PEP 675
PEP 675@footnote{https://peps.python.org/pep-0675/}.
Patch by Jelle Zijlstra.

@item 
bpo-42885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42885}: Optimize @ref{120a,,re.search()}, @ref{29f,,re.split()},
@ref{1013,,re.findall()}, @ref{14b0,,re.finditer()} and @ref{2a0,,re.sub()} for regular
expressions starting with @code{\A} or @code{^}.

@item 
bpo-23691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23691}: Protect the @ref{14b0,,re.finditer()} iterator from re-entering.

@item 
bpo-47067@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47067}: Optimize calling @code{GenericAlias} objects by using 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} and by replacing @code{PyObject_SetAttrString} with
@code{PyObject_SetAttr}.

@item 
bpo-28080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28080}: Add the `metadata_encoding' parameter in the
@ref{6af,,zipfile.ZipFile} constructor and the @code{--metadata-encoding}
option in the @ref{130,,zipfile} CLI to allow reading zipfiles using
non-standard codecs to encode the filenames within the archive.

@item 
bpo-47000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47000}: Make @ref{1650,,io.text_encoding()} returns "utf-8" when UTF-8 mode
is enabled.

@item 
bpo-42369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42369}: Fix thread safety of @code{zipfile._SharedFile.tell()} to avoid
a "zipfile.BadZipFile: Bad CRC-32 for file" exception when reading a
@code{ZipFile} from multiple threads.

@item 
bpo-38256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38256}: Fix @ref{161f,,binascii.crc32()} when it is compiled to use zlib'c
crc32 to work properly on inputs 4+GiB in length instead of returning the
wrong result. The workaround prior to this was to always feed the function
data in increments smaller than 4GiB or to just call the zlib module
function.

We also have @ref{161f,,binascii.crc32()} release the GIL when computing on
larger inputs as @ref{161e,,zlib.crc32()} and @ref{67,,hashlib} do.

This also boosts performance on Windows as it now uses the zlib crc32
implementation for @ref{161f,,binascii.crc32()} for a 2-3x speedup.

That the stdlib has a crc32 API in two modules is a known historical
oddity. This moves us closer to a single implementation behind them.

@item 
bpo-47066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47066}: Global inline flags (e.g. @code{(?i)}) can now only be used at the
start of the regular expressions.  Using them not at the start of
expression was deprecated since Python 3.6.

@item 
bpo-39394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39394}: A warning about inline flags not at the start of the regular
expression now contains the position of the flag.

@item 
bpo-433030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=433030}: Add support of atomic grouping (@code{(?>...)}) and possessive
quantifiers (@code{*+}, @code{++}, @code{?+}, @code{@{m,n@}+}) in @ref{b8,,regular expressions}.

@item 
bpo-47062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47062}: Implement @ref{5eb,,asyncio.Runner} context manager.

@item 
bpo-46382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46382}: @ref{1c6,,dataclass()} @code{slots=True} now correctly
omits slots already defined in base classes. Patch by Arie Bovenberg.

@item 
bpo-47057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47057}: Use FASTCALL convention for @code{FutureIter.throw()}

@item 
bpo-47061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47061}: Deprecate the various modules listed by 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}:

aifc, asynchat, asyncore, audioop, cgi, cgitb, chunk, crypt, imghdr,
msilib, nntplib, nis, ossaudiodev, pipes, smtpd, sndhdr, spwd, sunau,
telnetlib, uu, xdrlib

@item 
bpo-34790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34790}: Remove passing coroutine objects to @ref{469,,asyncio.wait()}.

@item 
bpo-47039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47039}: Normalize @code{repr()} of asyncio future and task objects.

@item 
bpo-2604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2604}: Fix bug where doctests using globals would fail when run
multiple times.

@item 
bpo-45150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45150}: Add @ref{62f,,hashlib.file_digest()} helper for efficient hashing of
file object.

@item 
bpo-34861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34861}: Made cumtime the default sorting key for cProfile

@item 
bpo-45997@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45997}: Fix @ref{a62,,asyncio.Semaphore} re-aquiring FIFO order.

@item 
bpo-47022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47022}: The @code{asynchat}, @code{asyncore} and  @code{smtpd}
modules have been deprecated since at least Python 3.6. Their
documentation and deprecation warnings and have now been updated to note
they will removed in Python 3.12 (
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}).

@item 
bpo-43253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43253}: Fix a crash when closing transports where the underlying socket
handle is already invalid on the Proactor event loop.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @ref{d8d,,select.select()} now passes @code{NULL} to @code{select} for
each empty fdset.

@item 
bpo-47004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47004}: Apply bugfixes from importlib_metadata 4.11.3, including bugfix
for EntryPoint.extras, which was returning match objects and not the
extras strings.

@item 
bpo-46998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46998}: Allow subclassing of @ref{697,,typing.Any}. Patch by Shantanu
Jain.

@item 
bpo-46995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46995}: Deprecate missing @ref{9cb,,asyncio.Task.set_name()} for third-party
task implementations, schedule making it mandatory in Python 3.13.

@item 
bpo-46994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46994}: Accept explicit contextvars.Context in
@ref{5e7,,asyncio.create_task()} and @ref{9ca,,asyncio.loop.create_task()}.

@item 
bpo-46981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46981}: @code{typing.get_args(typing.Tuple[()])} now returns @code{()}
instead of @code{((),)}.

@item 
bpo-46968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46968}: Add @code{os.sysconf_names['SC_MINSIGSTKSZ']}.

@item 
bpo-46985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46985}: Upgrade pip wheel bundled with ensurepip (pip 22.0.4)

@item 
bpo-46968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46968}: @ref{57,,faulthandler}: On Linux 5.14 and newer, dynamically
determine size of signal handler stack size CPython allocates using
@code{getauxval(AT_MINSIGSTKSZ)}. This changes allows for Python extension's
request to Linux kernel to use AMX_TILE instruction set on Sapphire Rapids
Xeon processor to succeed, unblocking use of the ISA in frameworks.

@item 
bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917}: The @ref{64e,,math.nan} value is now always available. Patch by
Victor Stinner.

@item 
bpo-46955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46955}: Expose @code{asyncio.base_events.Server} as
@ref{b00,,asyncio.Server}. Patch by Stefan Zabka.

@item 
bpo-23325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23325}: The @ref{c5,,signal} module no longer assumes that
@ref{17ae,,SIG_IGN} and @ref{17af,,SIG_DFL} are small int
singletons.

@item 
bpo-46932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46932}: Update bundled libexpat to 2.4.7

@item 
bpo-46933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46933}: The @ref{b1,,pwd} module is now optional.
@ref{a02,,os.path.expanduser()} returns the path when the @ref{b1,,pwd} module is
not available.

@item 
bpo-40059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40059}: 
@geindex Python Enhancement Proposals; PEP 680
PEP 680@footnote{https://peps.python.org/pep-0680/}, the @ref{fb,,tomllib} module. Adds support for parsing
TOML.

@item 
bpo-464471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=464471}: @ref{5e9,,asyncio.timeout()} and @ref{17b0,,asyncio.timeout_at()} context
managers added. Patch by Tin Tvrtković and Andrew Svetlov.

@item 
bpo-46805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46805}: Added raw datagram socket functions for asyncio:
@code{sock_sendto()},
@code{sock_recvfrom()} and
@code{sock_recvfrom_into()}.

@item 
bpo-46644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46644}: No longer require valid typeforms to be callable. This allows
@ref{92a,,typing.Annotated} to wrap @ref{7b0,,typing.ParamSpecArgs} and
@code{dataclasses.InitVar}. Patch by Gregory Beauregard.

@item 
bpo-46581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46581}: Brings @code{ParamSpec} propagation for @code{GenericAlias}
in line with @code{Concatenate} (and others).

@item 
bpo-45413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45413}: Define `posix_venv' and `nt_venv' @ref{67a,,sysconfig installation schemes} to be used for bootstrapping new virtual
environments. Add `venv' sysconfig installation scheme to get the
appropriate one of the above. The schemes are identical to the
pre-existing `posix_prefix' and `nt' install schemes. The @ref{110,,venv}
module now uses the `venv' scheme to create new virtual environments
instead of hardcoding the paths depending only on the platform. Downstream
Python distributors customizing the `posix_prefix' or `nt' install scheme
in a way that is not compatible with the install scheme used in virtual
environments are encouraged not to customize the `venv' schemes. When
Python itself runs in a virtual environment,
@ref{17b1,,sysconfig.get_default_scheme()} and
@ref{67b,,sysconfig.get_preferred_scheme()} with @code{key="prefix"} returns
`venv'.

@item 
bpo-43224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43224}: Implement support for PEP 646 in typing.py.

@item 
bpo-43224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43224}: Allow unpacking types.GenericAlias objects, e.g. @code{*tuple[int,
str]}.

@item 
bpo-46557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46557}: Warnings captured by the logging module are now logged without
a format string to prevent systems that group logs by the msg argument
from grouping captured warnings together.

@item 
bpo-41370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41370}: @ref{69c,,typing.get_type_hints()} now supports evaluating strings
as forward references in @ref{69d,,PEP 585 generic aliases}.

@item 
bpo-46607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46607}: Add @ref{1a3,,DeprecationWarning} to @code{LegacyInterpolation},
deprecated in the docstring since Python 3.2. Will be removed in Python
3.13. Use @code{BasicInterpolation} or @code{ExtendedInterpolation}
instead.

@item 
bpo-26120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26120}: @ref{b4,,pydoc} now excludes __future__ imports from the module's
data items.

@item 
bpo-46480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46480}: Add @ref{696,,typing.assert_type()}. Patch by Jelle Zijlstra.

@item 
bpo-46421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46421}: Fix a unittest issue where if the command was invoked as
@code{python -m unittest} and the filename(s) began with a dot (.), a
@code{ValueError} is returned.

@item 
bpo-46245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46245}: Add optional parameter `dir_fd' in @ref{2f5,,shutil.rmtree()}.

@item 
bpo-22859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22859}: @code{unittest.TestProgram.usageExit()} is marked as
deprecated, to be removed in Python 3.13.

@item 
bpo-46170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46170}: Improve the error message when you try to subclass an instance
of @ref{ce3,,typing.NewType}.

@item 
bpo-40296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40296}: Fix supporting generic aliases in @ref{b4,,pydoc}.

@item 
bpo-20392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20392}: Fix inconsistency with uppercase file extensions in
@code{MimeTypes.guess_type()}. Patch by Kumar Aditya.

@item 
bpo-46030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46030}: Add @code{LOCAL_CREDS}, @code{LOCAL_CREDS_PERSISTENT} and
@code{SCM_CREDS2} FreeBSD constants to the socket module.

@item 
bpo-44439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44439}: Fix @code{.write()} method of a member file in @code{ZipFile}, when
the input data is an object that supports the buffer protocol, the file
length may be wrong.

@item 
bpo-45171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45171}: Fix handling of the @code{stacklevel} argument to logging
functions in the @ref{86,,logging} module so that it is consistent across all
logging functions and, as advertised, similar to the @code{stacklevel}
argument used in @ref{14d0,,warn()}.

@item 
bpo-24959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24959}: Fix bug where @ref{105,,unittest} sometimes drops frames from
tracebacks of exceptions raised in tests.

@item 
bpo-44859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44859}: Raise more accurate and 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/} compatible exceptions in
@ref{ce,,sqlite3}.


@itemize *

@item 
Raise @ref{668,,InterfaceError} instead of
@ref{4dc,,ProgrammingError} for @code{SQLITE_MISUSE} errors.

@item 
Don't overwrite @ref{17b2,,BufferError} with @ref{1ff,,ValueError} when conversion to
BLOB fails.

@item 
Raise @ref{4dc,,ProgrammingError} instead of @ref{17b3,,Warning} if
user tries to @ref{2cf,,execute()} more than one SQL statement.

@item 
Raise @ref{4dc,,ProgrammingError} instead of @ref{1ff,,ValueError} if an SQL
query contains null characters.
@end itemize

@item 
bpo-44493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44493}: Add missing terminated NUL in sockaddr_un's length

This was potentially observable when using non-abstract AF_UNIX datagram
sockets to processes written in another programming language.

@item 
bpo-41930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41930}: Add @ref{669,,serialize()} and
@ref{66a,,deserialize()} support to @ref{ce,,sqlite3}. Patch
by Erlend E. Aasland.

@item 
bpo-33178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33178}: Added @ref{17b4,,ctypes.BigEndianUnion} and
@ref{17b5,,ctypes.LittleEndianUnion} classes, as originally documented in the
library docs but not yet implemented.

@item 
bpo-43352@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43352}: Add an Barrier object in synchronization primitives of
`asyncio' Lib in order to be consistent with Barrier from `threading' and
`multiprocessing' libs*

@item 
bpo-35859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35859}: @ref{b8,,re} module, fix a few bugs about capturing group. In rare
cases, capturing group gets an incorrect string. Patch by Ma Lin.
@end itemize

@node Documentation<20>,Tests<23>,Library<25>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id211}@anchor{17b6}
@subsubsection Documentation



@itemize -

@item 
bpo-45099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45099}: Document internal @ref{a,,asyncio} API.

@item 
bpo-47126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47126}: Update PEP URLs to 
@geindex Python Enhancement Proposals; PEP 676
PEP 676@footnote{https://peps.python.org/pep-0676/}'s new canonical form.

@item 
bpo-47040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47040}: Clarified the old Python versions compatibility note of
@ref{161f,,binascii.crc32()} / @ref{17b7,,zlib.adler32()} / @ref{161e,,zlib.crc32()}
functions.

@item 
bpo-46033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46033}: Clarify @code{for} statement execution in its doc.

@item 
bpo-45790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45790}: Adjust inaccurate phrasing in
@ref{17b8,,Tutoriel ; définir des types dans des extensions} about the @code{ob_base} field and the
macros used to access its contents.

@item 
bpo-42340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42340}: Document that in some circumstances @ref{9bf,,KeyboardInterrupt}
may cause the code to enter an inconsistent state. Provided a sample
workaround to avoid it if needed.

@item 
bpo-41233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41233}: Link the errnos referenced in @code{Doc/library/exceptions.rst} to
their respective section in @code{Doc/library/errno.rst}, and vice versa.
Previously this was only done for EINTR and InterruptedError. Patch by Yan
"yyyyyyyan" Orestes.
@end itemize

@node Tests<23>,Build<25>,Documentation<20>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id212}@anchor{17b9}
@subsubsection Tests



@itemize -

@item 
bpo-47205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47205}: Skip test for @ref{10ea,,sched_getaffinity()} and
@ref{10ee,,sched_setaffinity()} error case on FreeBSD.

@item 
bpo-46126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46126}: Restore 'descriptions' when running tests internally.

@item 
bpo-47104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47104}: Rewrite @ref{8d5,,asyncio.to_thread()} tests to use
@ref{301,,unittest.IsolatedAsyncioTestCase}.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: The test suite is now passing on the Emscripten platform. All
fork, socket, and subprocess-based tests are skipped.

@item 
bpo-47037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47037}: Skip @code{strftime("%4Y")} feature test on Windows. It can cause
an assertion error in debug builds.

@item 
bpo-46587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46587}: Skip tests if platform's @code{strftime} does not support
non-portable glibc extensions.

@item 
bpo-47015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47015}: A test case for @ref{afd,,os.sendfile()} is converted from
deprecated @code{asyncore} (see 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}) to @ref{a,,asyncio}. Patch by
Oleg Iarygin.
@end itemize

@node Build<25>,Windows<22>,Tests<23>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id213}@anchor{17ba}
@subsubsection Build



@itemize -

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Add configure option @ref{17bb,,--enable-wasm-dynamic-linking} to
enable @code{dlopen} and MAIN_MODULE / SIDE_MODULE on @code{wasm32-emscripten}.

@item 
bpo-46023@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46023}: @code{makesetup} now detects and skips all duplicated module
definitions. The first entry wins.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Add SOABI @code{wasm32-emscripten} for Emscripten and
@code{wasm32-wasi} for WASI on 32bit WASM as well as @code{wasm64} counter
parts.

@item 
bpo-47032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47032}: Ensure Windows install builds fail correctly with a non-zero
exit code when part of the build fails.

@item 
bpo-47024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47024}: Update OpenSSL to 1.1.1n for macOS installers and all Windows
builds.

@item 
bpo-46996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46996}: The @ref{ef,,tkinter} package now requires Tcl/Tk version 8.5.12
or newer.

@item 
bpo-46973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46973}: Add @code{regen-configure} make target to regenerate configure
script with Christian's container image
@code{quay.io/tiran/cpython_autoconf:269}.

@item 
bpo-46917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46917}: Building Python now requires support of IEEE 754 floating-point
numbers. Patch by Victor Stinner.

@item 
bpo-45774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45774}: @code{configure} now verifies that all SQLite C APIs needed for
the @ref{ce,,sqlite3} extension module are found.
@end itemize

@node Windows<22>,macOS<17>,Build<25>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id214}@anchor{17bc}
@subsubsection Windows



@itemize -

@item 
bpo-47194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47194}: Update @code{zlib} to v1.2.12 to resolve 
@geindex Common Vulnerabilities and Exposures; CVE 2018-25032
CVE 2018-25032@footnote{https://www.cve.org/CVERecord?id=CVE-2018-25032}.

@item 
bpo-47171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47171}: Enables installing the @code{py.exe} launcher on Windows
ARM64.

@item 
bpo-46566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46566}: Upgraded @ref{5a8,,Lanceur Python pour Windows} to support a new @code{-V:company/tag}
argument for full 
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} support and to detect ARM64 installs. The
@code{-64} suffix on arguments is deprecated, but still selects any
non-32-bit install. Setting 
@geindex PYLAUNCHER_ALLOW_INSTALL
@geindex variable d'environnement; PYLAUNCHER_ALLOW_INSTALL
@code{PYLAUNCHER_ALLOW_INSTALL} and
specifying a version that is not installed will attempt to install the
requested version from the Microsoft Store.

@item 
bpo-47086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=47086}: The installer for Windows now includes documentation as loose
HTML files rather than a single compiled @code{.chm} file.

@item 
bpo-46907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46907}: Update Windows installer to use SQLite 3.38.1.

@item 
bpo-44549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44549}: Update bzip2 to 1.0.8 in Windows builds to mitigate
@geindex Common Vulnerabilities and Exposures; CVE 2016-3189
CVE 2016-3189@footnote{https://www.cve.org/CVERecord?id=CVE-2016-3189} and 
@geindex Common Vulnerabilities and Exposures; CVE 2019-12900
CVE 2019-12900@footnote{https://www.cve.org/CVERecord?id=CVE-2019-12900}.

@item 
bpo-46948@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46948}: Prevent 
@geindex Common Vulnerabilities and Exposures; CVE 2022-26488
CVE 2022-26488@footnote{https://www.cve.org/CVERecord?id=CVE-2022-26488} by ensuring the Add to PATH option in
the Windows installer uses the correct path when being repaired.
@end itemize

@node macOS<17>,Tools/Demos<14>,Windows<22>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id215}@anchor{17bd}
@subsubsection macOS



@itemize -

@item 
bpo-46890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46890}: Fix a regression in the setting of @code{sys._base_executable} in
framework builds, and thereby fix a regression in @ref{110,,venv} virtual
environments with such builds.

@item 
bpo-46907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46907}: Update macOS installer to SQLite 3.38.1.
@end itemize

@node Tools/Demos<14>,C API<24>,macOS<17>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id216}@anchor{17be}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Replace Emscripten's limited shell with Katie Bell's browser-ui
REPL from python-wasm project.
@end itemize

@node C API<24>,,Tools/Demos<14>,Python 3 11 0 alpha 7
@anchor{whatsnew/changelog id217}@anchor{17bf}
@subsubsection C API



@itemize -

@item 
bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}: Add @code{PyFrame_GetBuiltins}, @code{PyFrame_GetGenerator} and
@code{PyFrame_GetGlobals} C-API functions to access frame object attributes
safely from C code.

@item 
bpo-46850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46850}: Move the private @code{_PyFrameEvalFunction} type, and private
@code{_PyInterpreterState_GetEvalFrameFunc()} and
@code{_PyInterpreterState_SetEvalFrameFunc()} functions to the internal C
API. The @code{_PyFrameEvalFunction} callback function type now uses the
@code{_PyInterpreterFrame} type which is part of the internal C API. Patch by
Victor Stinner.

@item 
bpo-46850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46850}: Move the private undocumented @code{_PyEval_EvalFrameDefault()}
function to the internal C API. The function now uses the
@code{_PyInterpreterFrame} type which is part of the internal C API. Patch by
Victor Stinner.

@item 
bpo-46850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46850}: Remove the private undocumented function
@code{_PyEval_CallTracing()} from the C API. Call the public
@ref{17c0,,sys.call_tracing()} function instead. Patch by Victor Stinner.

@item 
bpo-46850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46850}: Remove the private undocumented function
@code{_PyEval_GetCoroutineOriginTrackingDepth()} from the C API. Call the
public @ref{b79,,sys.get_coroutine_origin_tracking_depth()} function instead.
Patch by Victor Stinner.

@item 
bpo-46850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46850}: Remove the following private undocumented functions from the C
API:


@itemize *

@item 
@code{_PyEval_GetAsyncGenFirstiter()}

@item 
@code{_PyEval_GetAsyncGenFinalizer()}

@item 
@code{_PyEval_SetAsyncGenFirstiter()}

@item 
@code{_PyEval_SetAsyncGenFinalizer()}
@end itemize

Call the public @ref{17c1,,sys.get_asyncgen_hooks()} and
@ref{15af,,sys.set_asyncgen_hooks()} functions instead. Patch by Victor Stinner.

@item 
bpo-46987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46987}: Remove private functions @code{_PySys_GetObjectId()} and
@code{_PySys_SetObjectId()}. Patch by Donghee Na.

@item 
bpo-46906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46906}: Add new functions to pack and unpack C double (serialize and
deserialize): @ref{74f,,PyFloat_Pack2()}, @ref{750,,PyFloat_Pack4()},
@ref{751,,PyFloat_Pack8()}, @ref{752,,PyFloat_Unpack2()},
@ref{753,,PyFloat_Unpack4()} and @ref{754,,PyFloat_Unpack8()}. Patch by Victor
Stinner.
@end itemize

@node Python 3 11 0 alpha 6,Python 3 11 0 alpha 5,Python 3 11 0 alpha 7,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-6}@anchor{17c2}
@subsection Python 3.11.0 alpha 6


`Release date: 2022-03-07'

@menu
* Core and Builtins: Core and Builtins<27>. 
* Library: Library<26>. 
* Documentation: Documentation<21>. 
* Tests: Tests<24>. 
* Build: Build<26>. 
* Windows: Windows<23>. 
* IDLE: IDLE<16>. 
* C API: C API<25>. 

@end menu

@node Core and Builtins<27>,Library<26>,,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id218}@anchor{17c3}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46940}: Avoid overriding @ref{343,,AttributeError} metadata information for
nested attribute access calls. Patch by Pablo Galindo.

@item 
bpo-46927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46927}: Include the type's name in the error message for subscripting
non-generic types.

@item 
bpo-46921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46921}: Support vectorcall for @code{super()}. Patch by Ken Jin.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Fix incorrect handling of inline cache entries when
specializing @ref{6f0,,BINARY_OP}.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use an oparg to simplify the construction of helpful error
messages in @ref{17c4,,GET_AWAITABLE}.

@item 
bpo-46903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46903}: Make sure that str subclasses can be used as attribute names
for instances with virtual dictionaries. Fixes regression in 3.11alpha

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Add more detailed specialization failure stats for
@ref{956,,COMPARE_OP} followed by @ref{1733,,EXTENDED_ARG}.

@item 
bpo-46891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46891}: Fix bug introduced during 3.11alpha where subclasses of
@code{types.ModuleType} with @code{__slots__} were not initialized correctly,
resulting in an interpreter crash.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline caching for @ref{4c8,,LOAD_ATTR},
@ref{c0d,,LOAD_METHOD}, and @ref{17c5,,STORE_ATTR}.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline cache for @ref{16cb,,BINARY_SUBSCR}.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline caching for @ref{956,,COMPARE_OP}.

@item 
bpo-46864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46864}: Deprecate @code{PyBytesObject.ob_shash}. It will be removed in
Python 3.13.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline caching for @ref{17c6,,UNPACK_SEQUENCE}.

@item 
bpo-46845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46845}: Reduces dict size by removing hash value from hash table when
all inserted keys are Unicode. For example,
@code{sys.getsizeof(dict.fromkeys("abcdefg"))} becomes 272 bytes from 352
bytes on 64bit platform.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Use inline cache for @ref{1673,,LOAD_GLOBAL}.

@item 
bpo-46852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46852}: Rename the private undocumented @code{float.__set_format__()}
method to @code{float.__setformat__()} to fix a typo introduced in Python
3.7. The method is only used by test_float. Patch by Victor Stinner.

@item 
bpo-46852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46852}: Remove the undocumented private @code{float.__set_format__()}
method, previously known as @code{float.__setformat__()} in Python 3.7. Its
docstring said: "You probably don't want to use this function. It exists
mainly to be used in Python's test suite." Patch by Victor Stinner.

@item 
bpo-40116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40116}: Fix regression that dict.update(other) may don't respect
iterate order of other when other is key sharing dict.

@item 
bpo-46712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46712}: Share global string identifiers in deep-frozen modules.

@item 
bpo-46430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46430}: Fix memory leak in interned strings of deep-frozen modules.

@item 
bpo-46841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46841}: Store @ref{6f0,,BINARY_OP} caches inline using a new
@ref{6e3,,CACHE} instruction.

@item 
bpo-45107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45107}: Specialize @code{LOAD_METHOD} for instances with a dict.

@item 
bpo-44337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44337}: Reduce the memory usage of specialized @ref{4c8,,LOAD_ATTR} and
@ref{17c5,,STORE_ATTR} instructions.

@item 
bpo-46729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46729}: Add number of sub-exceptions to @code{BaseException.__str__()}.

@item 
bpo-45885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45885}: Don't un-adapt @ref{956,,COMPARE_OP} when collecting
specialization stats.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Fix specialization stats gathering for @code{PRECALL}
instructions.

@item 
bpo-46794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46794}: Bump up the libexpat version into 2.4.6

@item 
bpo-46823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46823}: Implement a specialized combined opcode
@code{LOAD_FAST__LOAD_ATTR_INSTANCE_VALUE}.  Patch by Dennis Sweeney.

@item 
bpo-46820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46820}: Fix parsing a numeric literal immediately (without spaces)
followed by "not in" keywords, like in @code{1not in x}. Now the parser only
emits a warning, not a syntax error.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Move @code{KW_NAMES} before @code{PRECALL} instruction in call
sequence. Change @code{operand} of @code{CALL} to match @code{PRECALL} for easier
specialization.

@item 
bpo-46808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46808}: Remove the @code{NEXT_BLOCK} macro from compile.c, and make the
compiler automatically generate implicit blocks when they are needed.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Add @code{PUSH_NULL} instruction. This is used as a prefix when
evaluating a callable, so that the stack has the same shape for methods
and other calls. @code{PRECALL_FUNCTION} and @code{PRECALL_METHOD} are merged
into a single @code{PRECALL} instruction.

There is no change in semantics.

@item 
bpo-46762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46762}: Fix an assert failure in debug builds when a '<', '>', or '='
is the last character in an f-string that's missing a closing right brace.

@item 
bpo-46730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46730}: Message of AttributeError caused by getting, setting or
deleting a property without the corresponding function now mentions that
the attribute is in fact a property and also specifies type of the class
that it belongs to.

@item 
bpo-46724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46724}: Make sure that all backwards jumps use the @code{JUMP_ABSOLUTE}
instruction, rather than @code{JUMP_FORWARD} with an argument of
@code{(2**32)+offset}.

@item 
bpo-46732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46732}: Correct the docstring for the @ref{12b3,,__bool__()} method.
Patch by Jelle Zijlstra.

@item 
bpo-46072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46072}: Add more detailed specialization failure statistics for
@ref{6f0,,BINARY_OP}.

@item 
bpo-46707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46707}: Avoid potential exponential backtracking when producing some
syntax errors involving lots of brackets. Patch by Pablo Galindo.

@item 
bpo-46323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46323}: @ref{2a,,ctypes} now allocates memory on the stack instead of on
the heap to pass arguments while calling a Python callback function. Patch
by Donghee Na.

@item 
bpo-45923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45923}: Add a quickened form of @ref{30a,,RESUME} that skips quickening
checks.

@item 
bpo-46702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46702}: Specialize @ref{17c6,,UNPACK_SEQUENCE} for @ref{366,,tuple} and
@ref{5fc,,list} unpackings.

@item 
bpo-46072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46072}: Opcode pair stats are now gathered with @code{--enable-pystats}.
Defining @code{DYNAMIC_EXECUTION_PROFILE} or  @code{DXPAIRS} no longer has any
effect.

@item 
bpo-46675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46675}: Allow more than 16 items in a split dict before it is combined.
The limit is now 254.

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: Add a missing call to @code{va_end()} in
@code{Modules/_hashopenssl.c}.

@item 
bpo-46323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46323}: Use @ref{547,,PyObject_Vectorcall()} while calling ctypes callback
function. Patch by Donghee Na.

@item 
bpo-46615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46615}: When iterating over sets internally in @code{setobject.c}, acquire
strong references to the resulting items from the set.  This prevents
crashes in corner-cases of various set operations where the set gets
mutated.

@item 
bpo-45828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45828}: The bytecode compiler now attempts to apply runtime stack
manipulations at compile-time (whenever it is feasible to do so).

@item 
bpo-30496@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30496}: Fixed a minor portability issue in the implementation of
@ref{17c7,,PyLong_FromLong()}, and added a fast path for single-digit integers
to @ref{17c8,,PyLong_FromLongLong()}.
@end itemize

@node Library<26>,Documentation<21>,Core and Builtins<27>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id219}@anchor{17c9}
@subsubsection Library



@itemize -

@item 
bpo-25707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25707}: Fixed a file leak in @ref{270,,xml.etree.ElementTree.iterparse()}
when the iterator is not exhausted. Patch by Jacob Walls.

@item 
bpo-46877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46877}: Export @ref{17ca,,unittest.doModuleCleanups()} in @ref{105,,unittest}.
Patch by Kumar Aditya.

@item 
bpo-46848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46848}: For performance, use the optimized string-searching
implementations from @ref{17cb,,find()} and @ref{17cc,,rfind()} for
@code{find()} and @code{rfind()}.

@item 
bpo-46736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46736}: @ref{b31,,SimpleHTTPRequestHandler} now uses HTML5
grammar. Patch by Donghee Na.

@item 
bpo-44886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44886}: Inherit asyncio proactor datagram transport from
@ref{173a,,asyncio.DatagramTransport}.

@item 
bpo-46827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46827}: Support UDP sockets in  @ref{db7,,asyncio.loop.sock_connect()} for
selector-based event loops.  Patch by Thomas Grainger.

@item 
bpo-46811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46811}: Make test suite support Expat >=2.4.5

@item 
bpo-46252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46252}: Raise @ref{522,,TypeError} if @ref{8d7,,ssl.SSLSocket} is passed to
transport-based APIs.

@item 
bpo-46784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46784}: Fix libexpat symbols collisions with user dynamically loaded or
statically linked libexpat in embedded Python.

@item 
bpo-46786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46786}: The HTML serialisation in xml.etree.ElementTree now writes
@code{embed}, @code{source}, @code{track} and @code{wbr} as empty tags, as defined in
HTML 5.

@item 
bpo-39327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39327}: @ref{2f5,,shutil.rmtree()} can now work with VirtualBox shared
folders when running from the guest operating-system.

@item 
bpo-45390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45390}: Propagate @ref{1b6,,asyncio.CancelledError} message from inner task
to outer awaiter.

@item 
bpo-46756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46756}: Fix a bug in
@ref{17cd,,urllib.request.HTTPPasswordMgr.find_user_password()} and
@ref{17ce,,urllib.request.HTTPPasswordMgrWithPriorAuth.is_authenticated()} which
allowed to bypass authorization. For example, access to URI
@code{example.org/foobar} was allowed if the user was authorized for URI
@code{example.org/foo}.

@item 
bpo-46737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46737}: @ref{17cf,,random.gauss()} and @ref{17d0,,random.normalvariate()} now have
default arguments.

@item 
bpo-46752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46752}: Add task groups to asyncio (structured concurrency, inspired by
Trio's nurseries). This also introduces a change to task cancellation,
where a cancelled task can't be cancelled again until it calls
.uncancel().

@item 
bpo-46724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46724}: Fix @ref{38,,dis} behavior on negative jump offsets.

@item 
bpo-46333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46333}: The @code{__repr__()} method of @ref{17d1,,typing.ForwardRef} now
includes the @code{module} parameter of @ref{17d1,,typing.ForwardRef} when it is
set.

@item 
bpo-46643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46643}: In @ref{69c,,typing.get_type_hints()}, support evaluating
stringified @code{ParamSpecArgs} and @code{ParamSpecKwargs} annotations. Patch
by Gregory Beauregard.

@item 
bpo-45863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45863}: When the @ref{dd,,tarfile} module creates a pax format archive, it
will put an integer representation of timestamps in the ustar header (if
possible) for the benefit of older unarchivers, in addition to the
existing full-precision timestamps in the pax extended header.

@item 
bpo-46066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46066}: Deprecate kwargs-based syntax for @ref{161,,typing.TypedDict}
definitions. It had confusing semantics when specifying totality, and was
largely unused. Patch by Jingchen Ye.

@item 
bpo-46676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46676}: Make @ref{15d,,typing.ParamSpec} args and kwargs equal to
themselves. Patch by Gregory Beauregard.

@item 
bpo-46323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46323}: @code{ctypes.CFUNCTYPE()} and @code{ctypes.WINFUNCTYPE()} now fail to
create the type if its @code{_argtypes_} member contains too many arguments.
Previously, the error was only raised when calling a function. Patch by
Victor Stinner.

@item 
bpo-46672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46672}: Fix @code{NameError} in @ref{5e8,,asyncio.gather()} when initial type
check fails.

@item 
bpo-46659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46659}: The @ref{72e,,calendar.LocaleTextCalendar} and
@ref{72f,,calendar.LocaleHTMLCalendar} classes now use
@ref{2d9,,locale.getlocale()}, instead of using
@ref{2d8,,locale.getdefaultlocale()}, if no locale is specified. Patch by
Victor Stinner.

@item 
bpo-46659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46659}: The @ref{2d8,,locale.getdefaultlocale()} function is deprecated and
will be removed in Python 3.13. Use @ref{2da,,locale.setlocale()},
@ref{524,,locale.getpreferredencoding(False)}
and @ref{2d9,,locale.getlocale()} functions instead.  Patch by Victor Stinner.

@item 
bpo-46655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46655}: In @ref{69c,,typing.get_type_hints()}, support evaluating bare
stringified @code{TypeAlias} annotations. Patch by Gregory Beauregard.

@item 
bpo-45948@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45948}: Fixed a discrepancy in the C implementation of the
@ref{124,,xml.etree.ElementTree} module. Now, instantiating an
@ref{a42,,xml.etree.ElementTree.XMLParser} with a @code{target=None} keyword
provides a default @ref{a43,,xml.etree.ElementTree.TreeBuilder} target as
the Python implementation does.

@item 
bpo-46626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46626}: Expose Linux's @code{IP_BIND_ADDRESS_NO_PORT} option in
@ref{cb,,socket}.

@item 
bpo-46521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46521}: Fix a bug in the @ref{1c,,codeop} module that was incorrectly
identifying invalid code involving string quotes as valid code.

@item 
bpo-46571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46571}: Improve @ref{69f,,typing.no_type_check()}.

Now it does not modify external classes and functions. We also now
correctly mark classmethods as not to be type checked.

@item 
bpo-46400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46400}: expat: Update libexpat from 2.4.1 to 2.4.4

@item 
bpo-46556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46556}: Deprecate undocumented support for using a
@ref{226,,pathlib.Path} object as a context manager.

@item 
bpo-46534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46534}: Implement 
@geindex Python Enhancement Proposals; PEP 673
PEP 673@footnote{https://peps.python.org/pep-0673/} @ref{5b1,,typing.Self}. Patch by James
Hilton-Balfe.

@item 
bpo-46522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46522}: Make various module @code{__getattr__} AttributeErrors more
closely match a typical AttributeError

@item 
bpo-46475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46475}: Add @ref{693,,typing.Never} and @ref{692,,typing.assert_never()}. Patch
by Jelle Zijlstra.

@item 
bpo-46333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46333}: The @code{__eq__()} and @code{__hash__()} methods of
@ref{17d1,,typing.ForwardRef} now honor the @code{module} parameter of
@ref{17d1,,typing.ForwardRef}. Forward references from different modules are
now differentiated.

@item 
bpo-46246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46246}: Add missing @code{__slots__} to
@code{importlib.metadata.DeprecatedList}. Patch by Arie Bovenberg.

@item 
bpo-46232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46232}: The @ref{cf,,ssl} module now handles certificates with bit strings
in DN correctly.

@item 
bpo-46195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46195}: @ref{69c,,typing.get_type_hints()} no longer adds @code{Optional} to
parameters with @code{None} as a default. This aligns to changes to PEP 484
in @indicateurl{https://github.com/python/peps/pull/689}

@item 
bpo-31369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31369}: Add @ref{618,,RegexFlag} to @code{re.__all__} and documented it.
Add @code{NOFLAG} to indicate no flags being set.

@item 
bpo-45898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45898}: @ref{2a,,ctypes} no longer defines @code{ffi_type_*} symbols in
@code{cfield.c}. The symbols have been provided by libffi for over a decade.

@item 
bpo-44953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44953}: Calling @code{operator.itemgetter} objects and
@code{operator.attrgetter} objects is now faster due to use of the vectorcall
calling convention.

@item 
bpo-44289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44289}: Fix an issue with @ref{17d2,,is_tarfile()} method when using
`fileobj' argument: position in the `fileobj' was advanced forward which
made it unreadable with @ref{17d3,,tarfile.TarFile.open()}.

@item 
bpo-44011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44011}: Reimplement SSL/TLS support in asyncio, borrow the
implementation from uvloop library.

@item 
bpo-41086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41086}: Make the @ref{1c3,,configparser.ConfigParser} constructor raise
@ref{522,,TypeError} if the @code{interpolation} parameter is not of type
@code{configparser.Interpolation}

@item 
bpo-29418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29418}: Implement @ref{635,,inspect.ismethodwrapper()} and fix
@ref{1573,,inspect.isroutine()} for cases where methodwrapper is given. Patch by
Hakan Çelik.

@item 
bpo-14156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14156}: argparse.FileType now supports an argument of '-' in binary
mode, returning the .buffer attribute of sys.stdin/sys.stdout as
appropriate. Modes including 'x' and 'a' are treated equivalently to 'w'
when argument is '-'. Patch contributed by Josh Rosenberg
@end itemize

@node Documentation<21>,Tests<24>,Library<26>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id220}@anchor{17d4}
@subsubsection Documentation



@itemize -

@item 
bpo-42238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42238}: @code{Doc/tools/rstlint.py} has moved to its own repository and is
now packaged on PyPI as @code{sphinx-lint}.
@end itemize

@node Tests<24>,Build<26>,Documentation<21>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id221}@anchor{17d5}
@subsubsection Tests



@itemize -

@item 
bpo-46913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46913}: Fix test_faulthandler.test_sigfpe() if Python is built with
undefined behavior sanitizer (UBSAN): disable UBSAN on the
faulthandler_sigfpe() function. Patch by Victor Stinner.

@item 
bpo-46760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46760}: Remove bytecode offsets from expected values in test.test_dis
module. Reduces the obstacles to modifying the VM or compiler.

@item 
bpo-46708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46708}: Prevent default asyncio event loop policy modification warning
after @code{test_asyncio} execution.

@item 
bpo-46678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46678}: The function @code{make_legacy_pyc} in
@code{Lib/test/support/import_helper.py} no longer fails when
@code{PYTHONPYCACHEPREFIX} is set to a directory on a different device from
where tempfiles are stored.

@item 
bpo-46623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46623}: Skip test_pair() and test_speech128() of test_zlib on s390x
since they fail if zlib uses the s390x hardware accelerator. Patch by
Victor Stinner.
@end itemize

@node Build<26>,Windows<23>,Tests<24>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id222}@anchor{17d6}
@subsubsection Build



@itemize -

@item 
bpo-46860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46860}: Respect @code{--with-suffix} when building on case-insensitive
file systems.

@item 
bpo-46656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46656}: Building Python now requires a C11 compiler. Optional C11
features are not required. Patch by Victor Stinner.

@item 
bpo-46656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46656}: Building Python now requires support for floating-point
Not-a-Number (NaN): remove the @code{Py_NO_NAN} macro. Patch by Victor
Stinner.

@item 
bpo-46640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46640}: Building Python now requires a C99 @code{<math.h>} header file
providing a @code{NAN} constant, or the @code{__builtin_nan()} built-in
function. Patch by Victor Stinner.

@item 
bpo-46608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46608}: Exclude marshalled-frozen data if deep-freezing to save 300 KB
disk space. This includes adding a new @code{is_package} field to
@ref{75f,,_frozen}. Patch by Kumar Aditya.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Fix wasm32-emscripten test failures and platform issues. -
Disable syscalls that are not supported or don't work, e.g.   wait,
getrusage, prlimit, mkfifo, mknod, setres[gu]id, setgroups. - Use fd_count
to count open fds. - Add more checks for subprocess and fork. - Add
workarounds for missing _multiprocessing and failing socket.accept(). -
Enable bzip2. - Disable large file support. - Disable signal.alarm.

@item 
bpo-46430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46430}: Intern strings in deep-frozen modules. Patch by Kumar Aditya.
@end itemize

@node Windows<23>,IDLE<16>,Build<26>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id223}@anchor{17d7}
@subsubsection Windows



@itemize -

@item 
bpo-46744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46744}: The default all users install directory for ARM64 is now under
the native @code{Program Files} folder, rather than @code{Program Files (Arm)}
which is intended for ARM (32-bit) files.

@item 
bpo-46567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46567}: Adds Tcl and Tk support for Windows ARM64. This also adds IDLE
to the installation.

@item 
bpo-46638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46638}: Ensures registry virtualization is consistently disabled. For
3.10 and earlier, it remains enabled (some registry writes are protected),
while for 3.11 and later it is disabled (registry modifications affect all
applications).
@end itemize

@node IDLE<16>,C API<25>,Windows<23>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id224}@anchor{17d8}
@subsubsection IDLE



@itemize -

@item 
bpo-46630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46630}: Make query dialogs on Windows start with a cursor in the entry
box.

@item 
bpo-45447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45447}: Apply IDLE syntax highlighting to @code{.pyi} files. Patch by Alex
Waygood and Terry Jan Reedy.
@end itemize

@node C API<25>,,IDLE<16>,Python 3 11 0 alpha 6
@anchor{whatsnew/changelog id225}@anchor{17d9}
@subsubsection C API



@itemize -

@item 
bpo-46748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46748}: Python's public headers no longer import @code{<stdbool.h>},
leaving code that embeds/extends Python free to define @code{bool}, @code{true}
and @code{false}.

@item 
bpo-46836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46836}: Move the @ref{773,,PyFrameObject} type definition (@code{struct
_frame}) to the internal C API @code{pycore_frame.h} header file. Patch by
Victor Stinner.

@item 
bpo-45459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45459}: Rename @code{Include/buffer.h} header file to
@code{Include/pybuffer.h} to avoid conflicts with projects having an existing
@code{buffer.h} header file. Patch by Victor Stinner.

@item 
bpo-45412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45412}: Remove the @code{HAVE_PY_SET_53BIT_PRECISION} macro (moved to the
internal C API). Patch by Victor Stinner.

@item 
bpo-46613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46613}: Added function @ref{38a,,PyType_GetModuleByDef()}, which allows
access to module state when a method's defining class is not available.
@end itemize

@node Python 3 11 0 alpha 5,Python 3 11 0 alpha 4,Python 3 11 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-5}@anchor{17da}
@subsection Python 3.11.0 alpha 5


`Release date: 2022-02-03'

@menu
* Core and Builtins: Core and Builtins<28>. 
* Library: Library<27>. 
* Documentation: Documentation<22>. 
* Tests: Tests<25>. 
* Build: Build<27>. 
* Windows: Windows<24>. 
* macOS: macOS<18>. 
* IDLE: IDLE<17>. 
* C API: C API<26>. 

@end menu

@node Core and Builtins<28>,Library<27>,,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id226}@anchor{17db}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-45773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45773}: Remove two invalid "peephole" optimizations from the bytecode
compiler.

@item 
bpo-46564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46564}: Do not create frame objects when creating @ref{4c5,,super}
object. Patch by Kumar Aditya.

@item 
bpo-45885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45885}: Added more fined-grained specialization failure stats regarding
the @code{COMPARE_OP} bytecode.

@item 
bpo-44977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44977}: The delegation of @ref{254,,int()} to @code{__trunc__()} is now
deprecated. Calling @code{int(a)} when @code{type(a)} implements
@code{__trunc__()} but not @code{__int__()} or @code{__index__()} now raises
a @ref{1a3,,DeprecationWarning}.

@item 
bpo-46458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46458}: Reorder code emitted by the compiler for a
@ref{6d3,,try}-@ref{189,,except} block so that the @ref{18a,,else} block's
code immediately follows the @ref{6d3,,try} body (without a jump). This is
more optimal for the happy path.

@item 
bpo-46527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46527}: Allow passing @code{iterable} as a keyword argument to
@ref{1433,,enumerate()} again. Patch by Jelle Zijlstra.

@item 
bpo-46528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46528}: Replace several stack manipulation instructions (@code{DUP_TOP},
@code{DUP_TOP_TWO}, @code{ROT_TWO}, @code{ROT_THREE}, @code{ROT_FOUR}, and @code{ROT_N})
with new @ref{6f3,,COPY} and @ref{6f4,,SWAP} instructions.

@item 
bpo-46329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46329}: Use two or three bytecodes to implement most calls.

Calls without named arguments are implemented as a sequence of two
instructions: @code{PRECALL; CALL}. Calls with named arguments are
implemented as a sequence of three instructions: @code{PRECALL; KW_NAMES;
CALL}. There are two different @code{PRECALL} instructions:
@code{PRECALL_FUNTION} and @code{PRECALL_METHOD}. The latter pairs with
@code{LOAD_METHOD}.

This partition into pre-call and call allows better specialization, and
thus better performance ultimately.

There is no change in semantics.

@item 
bpo-46503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46503}: Fix an assert when parsing some invalid N escape sequences in
f-strings.

@item 
bpo-46431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46431}: Improve error message on invalid calls to
@code{BaseExceptionGroup.__new__()}.

@item 
bpo-46476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46476}: Fix memory leak in code objects generated by deepfreeze. Patch
by Kumar Aditya.

@item 
bpo-46481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46481}: Speed up calls to @code{weakref.ref.__call__()} by using the
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} @code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-46417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46417}: Fix a race condition on setting a type @code{__bases__} attribute:
the internal function @code{add_subclass()} now gets the
@code{PyTypeObject.tp_subclasses} member after calling
@ref{17dc,,PyWeakref_NewRef()} which can trigger a garbage collection which
can indirectly modify @code{PyTypeObject.tp_subclasses}. Patch by Victor
Stinner.

@item 
bpo-46417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46417}: @code{python -X showrefcount} now shows the total reference count
after clearing and destroyed the main Python interpreter. Previously, it
was shown before. Patch by Victor Stinner.

@item 
bpo-43683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43683}: Add ASYNC_GEN_WRAP opcode to wrap the value to be yielded in
async generators. Removes the need to special case async generators in the
@code{YIELD_VALUE} instruction.

@item 
bpo-46407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46407}: Optimize some modulo operations in @code{Objects/longobject.c}.
Patch by Jeremiah Vivian.

@item 
bpo-46409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46409}: Add new @code{RETURN_GENERATOR} bytecode to make generators.
Simplifies calling Python functions in the VM, as they no longer any need
to special case generator functions.

Also add @code{JUMP_NO_INTERRUPT} bytecode that acts like @code{JUMP_ABSOLUTE},
but does not check for interrupts.

@item 
bpo-46406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46406}: The integer division @code{//} implementation has been optimized
to better let the compiler understand its constraints. It can be 20%
faster on the amd64 platform when dividing an int by a value smaller than
@code{2**30}.

@item 
bpo-46383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46383}: Fix invalid signature of @code{_zoneinfo}'s @code{module_free}
function to resolve a crash on wasm32-emscripten platform.

@item 
bpo-46361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46361}: Ensure that "small" integers created by @ref{17dd,,int.from_bytes()}
and @ref{29a,,decimal.Decimal} are properly cached.

@item 
bpo-46161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46161}: Fix the class building error when the arguments are constants
and CALL_FUNCTION_EX is used.

@item 
bpo-46028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46028}: Fixes calculation of @code{sys._base_executable} when inside a
virtual environment that uses symlinks with different binary names than
the base environment provides.

@item 
bpo-46091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46091}: Correctly calculate indentation levels for lines with
whitespace character that are ended by line continuation characters. Patch
by Pablo Galindo

@item 
bpo-30512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30512}: Add CAN Socket support for NetBSD.

@item 
bpo-46045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46045}: Do not use POSIX semaphores on NetBSD

@item 
bpo-44024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44024}: Improve the @ref{522,,TypeError} message for non-string second
arguments passed to the built-in functions @ref{bbf,,getattr()} and
@ref{4bb,,hasattr()}. Patch by Géry Ogam.
@end itemize

@node Library<27>,Documentation<22>,Core and Builtins<28>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id227}@anchor{17de}
@subsubsection Library



@itemize -

@item 
bpo-46624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46624}: Restore support for non-integer arguments of
@ref{856,,random.randrange()} and @ref{120d,,random.randint()}.

@item 
bpo-46591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46591}: Make the IDLE doc URL on the About IDLE dialog clickable.

@item 
bpo-46565@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46565}: Remove loop variables that are leaking into modules'
namespaces.

@item 
bpo-46553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46553}: In @ref{69c,,typing.get_type_hints()}, support evaluating bare
stringified @code{ClassVar} annotations. Patch by Gregory Beauregard.

@item 
bpo-46544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46544}: Don't leak @code{x} & @code{uspace} intermediate vars in
@ref{fb8,,textwrap.TextWrapper}.

@item 
bpo-46487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46487}: Add the @code{get_write_buffer_limits} method to
@code{asyncio.transports.WriteTransport} and to the SSL transport.

@item 
bpo-45173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45173}: Note the configparser deprecations will be removed in Python
3.12.

@item 
bpo-45162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45162}: The deprecated @ref{105,,unittest} APIs removed in 3.11a1 have been
temporarily restored to be removed in 3.12 while cleanups in external
projects go in.

@item 
bpo-46539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46539}: In @ref{69c,,typing.get_type_hints()}, support evaluating
stringified @code{ClassVar} and @code{Final} annotations inside @code{Annotated}.
Patch by Gregory Beauregard.

@item 
bpo-46510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46510}: Add missing test for @ref{ae0,,types.TracebackType} and
@ref{17df,,types.FrameType}. Calculate them directly from the caught
exception without calling @ref{675,,sys.exc_info()}.

@item 
bpo-46491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46491}: Allow @ref{92a,,typing.Annotated} to wrap @ref{264,,typing.Final} and
@ref{263,,typing.ClassVar}. Patch by Gregory Beauregard.

@item 
bpo-46483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46483}: Remove @ref{725,,__class_getitem__()} from
@ref{490,,pathlib.PurePath} as this class was not supposed to be generic.

@item 
bpo-46436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46436}: Fix command-line option @code{-d}/@code{--directory} in module
@ref{71,,http.server} which is ignored when combined with command-line option
@code{--cgi}. Patch by Géry Ogam.

@item 
bpo-41403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41403}: Make @code{mock.patch()} raise a @ref{522,,TypeError} with a
relevant error message on invalid arg. Previously it allowed a cryptic
@ref{343,,AttributeError} to escape.

@item 
bpo-46474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46474}: In @code{importlib.metadata.EntryPoint.pattern}, avoid potential
REDoS by limiting ambiguity in consecutive whitespace.

@item 
bpo-46474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46474}: Removed private method from @code{importlib.metadata.Path}. Sync
with importlib_metadata 4.10.0.

@item 
bpo-46470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46470}: Remove unused branch from @code{typing._remove_dups_flatten}

@item 
bpo-46469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46469}: @ref{a,,asyncio} generic classes now return
@ref{7d5,,types.GenericAlias} in @code{__class_getitem__} instead of the same
class.

@item 
bpo-41906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41906}: Support passing filter instances in the @code{filters} values of
@code{handlers} and @code{loggers} in the dictionary passed to
@ref{118d,,logging.config.dictConfig()}.

@item 
bpo-46422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46422}: Use @code{dis.Positions} in @code{dis.Instruction} instead of a
regular @code{tuple}.

@item 
bpo-46434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46434}: @ref{a4,,pdb} now gracefully handles @code{help} when
@ref{17e0,,__doc__} is missing, for example when run with pregenerated
optimized @code{.pyc} files.

@item 
bpo-43869@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43869}: Python uses the same time Epoch on all platforms. Add an
explicit unit test to ensure that it's the case. Patch by Victor Stinner.

@item 
bpo-46414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46414}: Add @ref{695,,typing.reveal_type()}. Patch by Jelle Zijlstra.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @ref{d5,,subprocess} now imports Windows-specific imports when
@code{msvcrt} module is available, and POSIX-specific imports on all other
platforms. This gives a clean exception when @code{_posixsubprocess} is not
available (e.g. Emscripten browser target).

@item 
bpo-40066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40066}: @code{IntEnum}, @code{IntFlag}, and @code{StrEnum} use the mixed-in type
for their @code{str()} and @code{format()} output.

@item 
bpo-46316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46316}: Optimize @ref{15ba,,pathlib.Path.iterdir()} by removing an
unnecessary check for special entries.

@item 
bpo-29688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29688}: Document @ref{1637,,pathlib.Path.absolute()} (which has always
existed).

@item 
bpo-43012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43012}: The pathlib module's obsolete and internal @code{_Accessor} class
has been removed to prepare the terrain for upcoming enhancements to the
module.

@item 
bpo-46258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46258}: Speed up @ref{9f3,,math.isqrt()} for small positive integers by
replacing two division steps with a lookup table.

@item 
bpo-46242@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46242}: Improve error message when creating a new @ref{61b,,enum.Enum}
type subclassing an existing @code{Enum} with @code{_member_names_} using
@code{enum.Enum.__call__()}.

@item 
bpo-43118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43118}: Fix a bug in @ref{722,,inspect.signature()} that was causing it to
fail on some subclasses of classes with a @code{__text_signature__}
referencing module globals. Patch by Weipeng Hong.

@item 
bpo-26552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26552}: Fixed case where failing @ref{c64,,asyncio.ensure_future()} did not
close the coroutine. Patch by Kumar Aditya.

@item 
bpo-21987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21987}: Fix an issue with @ref{17e1,,tarfile.TarFile.getmember()} getting a
directory name with a trailing slash.

@item 
bpo-46124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46124}: Update @ref{133,,zoneinfo} to rely on importlib.resources
traversable API.

@item 
bpo-46103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46103}: Now @ref{17e2,,inspect.getmembers()} only gets @code{__bases__}
attribute from class type. Patch by Weipeng Hong.

@item 
bpo-46080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46080}: Fix exception in argparse help text generation if a
@ref{17e3,,argparse.BooleanOptionalAction} argument's default is
@code{argparse.SUPPRESS} and it has @code{help} specified.  Patch by Felix
Fontein.

@item 
bpo-44791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44791}: Fix substitution of @ref{15d,,ParamSpec} in
@ref{7ae,,Concatenate} with different parameter expressions.
Substitution with a list of types returns now a tuple of types.
Substitution with @code{Concatenate} returns now a @code{Concatenate} with
concatenated lists of arguments.
@end itemize

@node Documentation<22>,Tests<25>,Library<27>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id228}@anchor{17e4}
@subsubsection Documentation



@itemize -

@item 
bpo-46463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46463}: Fixes @code{escape4chm.py} script used when building the CHM
documentation file
@end itemize

@node Tests<25>,Build<27>,Documentation<22>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id229}@anchor{17e5}
@subsubsection Tests



@itemize -

@item 
bpo-43478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43478}: Mocks can no longer be provided as the specs for other Mocks.
As a result, an already-mocked object cannot be passed to @code{mock.Mock()}.
This can uncover bugs in tests since these Mock-derived Mocks will always
pass certain tests (e.g. isinstance) and builtin assert functions (e.g.
assert_called_once_with) will unconditionally pass.

@item 
bpo-46616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46616}: Ensures @code{test_importlib.test_windows} cleans up registry keys
after completion.

@item 
bpo-44359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44359}: test_ftplib now silently ignores socket errors to prevent
logging unhandled threading exceptions. Patch by Victor Stinner.

@item 
bpo-46600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46600}: Fix test_gdb.test_pycfunction() for Python built with @code{clang
-Og}. Tolerate inlined functions in the gdb traceback. Patch by Victor
Stinner.

@item 
bpo-46542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46542}: Fix a Python crash in test_lib2to3 when using Python built in
debug mode: limit the recursion limit. Patch by Victor Stinner.

@item 
bpo-46576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46576}: test_peg_generator now disables compiler optimization when
testing compilation of its own C extensions to significantly speed up the
testing on non-debug builds of CPython.

@item 
bpo-46542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46542}: Fix @code{test_json} tests checking for @ref{d59,,RecursionError}:
modify these tests to use @code{support.infinite_recursion()}. Patch by
Victor Stinner.

@item 
bpo-13886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13886}: Skip test_builtin PTY tests on non-ASCII characters if the
readline module is loaded. The readline module changes input() behavior,
but test_builtin is not intended to test the readline module. Patch by
Victor Stinner.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Add @code{test.support.requires_fork()} decorators to mark tests
that require a working @ref{195,,os.fork()}.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Add @code{test.support.requires_subprocess()} decorator to mark
tests which require working @ref{d5,,subprocess} module or @code{os.spawn*}. The
wasm32-emscripten platform has no support for processes.

@item 
bpo-46126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46126}: Disable 'descriptions' when running tests internally.
@end itemize

@node Build<27>,Windows<24>,Tests<25>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id230}@anchor{17e6}
@subsubsection Build



@itemize -

@item 
bpo-46602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46602}: Tidied up configure.ac so that conftest.c is truncated rather
than appended. This assists in the case where the 'rm' of conftest.c fails
to happen between tests.  Downstream issues such as a clobbered SOABI can
result.

@item 
bpo-46600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46600}: Fix the test checking if the C compiler supports @code{-Og} option
in the @code{./configure} script to also use @code{-Og} on clang which supports
it. Patch by Victor Stinner.

@item 
bpo-38472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38472}: Fix GCC detection in setup.py when cross-compiling. The C
compiler is now run with LC_ALL=C. Previously, the detection failed with a
German locale.

@item 
bpo-46513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46513}: @code{configure} no longer uses @code{AC_C_CHAR_UNSIGNED}
macro and @code{pyconfig.h} no longer defines reserved symbol
@code{__CHAR_UNSIGNED__}.

@item 
bpo-46471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46471}: Use global singletons for single byte bytes objects in
deepfreeze.

@item 
bpo-46443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46443}: Deepfreeze now uses cached small integers as it saves some
space for common small integers.

@item 
bpo-46429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46429}: Merge all deep-frozen files into one for space savings. Patch
by Kumar Aditya.

@item 
bpo-45569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45569}: The build now defaults to using 30-bit digits for Python
integers. Previously either 15-bit or 30-bit digits would be selected,
depending on the platform. 15-bit digits may still be selected using the
@code{--enable-big-digits=15} option to the @code{configure} script, or by
defining @code{PYLONG_BITS_IN_DIGIT} in @code{pyconfig.h}.

@item 
bpo-45925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45925}: Update Windows installer to use SQLite 3.37.2.

@item 
bpo-43112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43112}: Detect musl libc as a separate SOABI (tagged as
@code{linux-musl}).
@end itemize

@node Windows<24>,macOS<18>,Build<27>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id231}@anchor{17e7}
@subsubsection Windows



@itemize -

@item 
bpo-33125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33125}: The traditional EXE/MSI based installer for Windows is now
available for ARM64

@item 
bpo-46362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46362}: os.path.abspath("C:CON") is now fixed to return "\.CON", not
the same path. The regression was true of all legacy DOS devices such as
COM1, LPT1, or NUL.

@item 
bpo-44934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44934}: The installer now offers a command-line only option to add the
installation directory to the end of 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} instead of at the
start.
@end itemize

@node macOS<18>,IDLE<17>,Windows<24>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id232}@anchor{17e8}
@subsubsection macOS



@itemize -

@item 
bpo-45925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45925}: Update macOS installer to SQLite 3.37.2.
@end itemize

@node IDLE<17>,C API<26>,macOS<18>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id233}@anchor{17e9}
@subsubsection IDLE



@itemize -

@item 
bpo-45296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45296}: Clarify close, quit, and exit in IDLE.  In the File menu,
'Close' and 'Exit' are now 'Close Window' (the current one) and 'Exit' is
now 'Exit IDLE' (by closing all windows).  In Shell, 'quit()' and 'exit()'
mean 'close Shell'. If there are no other windows, this also exits IDLE.
@end itemize

@node C API<26>,,IDLE<17>,Python 3 11 0 alpha 5
@anchor{whatsnew/changelog id234}@anchor{17ea}
@subsubsection C API



@itemize -

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Remove the @code{PyHeapType_GET_MEMBERS()} macro. It was exposed
in the public C API by mistake, it must only be used by Python internally.
Use the @code{PyTypeObject.tp_members} member instead. Patch by Victor
Stinner.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Move _Py_GetAllocatedBlocks() and _PyObject_DebugMallocStats()
private functions to the internal C API. Patch by Victor Stinner.

@item 
bpo-46433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46433}: The internal function _PyType_GetModuleByDef now correctly
handles inheritance patterns involving static types.

@item 
bpo-45459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45459}: @ref{742,,Py_buffer} and various @code{Py_buffer} related functions
are now part of the limited API and stable ABI.

@item 
bpo-14916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14916}: Fixed bug in the tokenizer that prevented
@code{PyRun_InteractiveOne} from parsing from the provided FD.
@end itemize

@node Python 3 11 0 alpha 4,Python 3 11 0 alpha 3,Python 3 11 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-4}@anchor{17eb}
@subsection Python 3.11.0 alpha 4


`Release date: 2022-01-13'

@menu
* Core and Builtins: Core and Builtins<29>. 
* Library: Library<28>. 
* Documentation: Documentation<23>. 
* Tests: Tests<26>. 
* Build: Build<28>. 
* Windows: Windows<25>. 
* macOS: macOS<19>. 
* C API: C API<27>. 

@end menu

@node Core and Builtins<29>,Library<28>,,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id235}@anchor{17ec}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46070}: @ref{17ed,,Py_EndInterpreter()} now explicitly untracks all objects
currently tracked by the GC. Previously, if an object was used later by
another interpreter, calling @ref{14bd,,PyObject_GC_UnTrack()} on the object
crashed if the previous or the next object of the @code{PyGC_Head}
structure became a dangling pointer. Patch by Victor Stinner.

@item 
bpo-46347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46347}: Fix memory leak in PyEval_EvalCodeEx.

@item 
bpo-46339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46339}: Fix a crash in the parser when retrieving the error text for
multi-line f-strings expressions that do not start in the first line of
the string. Patch by Pablo Galindo

@item 
bpo-46331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46331}: Do not set line number of instruction storing doc-string. Fixes
regression introduced in 3.11 alpha.

@item 
bpo-46314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46314}: Remove spurious "call" event when creating a lambda function
that was accidentally introduced in 3.11a4.

@item 
bpo-46289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46289}: ASDL declaration of @code{FormattedValue} has changed to reflect
@code{conversion} field is not optional.

@item 
bpo-46297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46297}: Fixed an interpreter crash on bootup with multiple PythonPaths
set in the Windows registry. Patch by Derzsi Dániel.

@item 
bpo-46237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46237}: Fix the line number of tokenizer errors inside f-strings. Patch
by Pablo Galindo.

@item 
bpo-46263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46263}: We always expect the "use_frozen_modules" config to be set, now
that getpath.c was rewritten in pure Python and the logic improved.

@item 
bpo-46006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46006}: Fix a regression when a type method like @code{__init__()} is
modified in a subinterpreter. Fix a regression in
@code{_PyUnicode_EqualToASCIIId()} and type @code{update_slot()}. Revert the
change which made the Unicode dictionary of interned strings compatible
with subinterpreters: the internal interned dictionary is shared again by
all interpreters. Patch by Victor Stinner.

@item 
bpo-45923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45923}: Add RESUME opcode. This is a logical no-op. It is emitted by
the compiler anywhere a Python function can be entered. It is used by the
interpreter to perform tracing and optimizer checks.

@item 
bpo-46208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46208}: Fix the regression of os.path.normpath("A/../../B") not
returning expected "../B" but "B".

@item 
bpo-46240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46240}: Correct the error message for unclosed parentheses when the
tokenizer doesn't reach the end of the source when the error is reported.
Patch by Pablo Galindo

@item 
bpo-46009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46009}: Remove the @code{GEN_START} opcode.

@item 
bpo-46235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46235}: Certain sequence multiplication operations like @code{[0] * 1_000}
are now faster due to reference-counting optimizations. Patch by Dennis
Sweeney.

@item 
bpo-46221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46221}: @code{PREP_RERAISE_STAR} no longer pushes @code{lasti} to the
stack.

@item 
bpo-46202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46202}: Remove @code{POP_EXCEPT_AND_RERAISE} and replace it by an
equivalent sequence of other opcodes.

@item 
bpo-46085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46085}: Fix iterator cache mechanism of @code{OrderedDict}.

@item 
bpo-46055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46055}: Speed up shifting operation involving integers less than
@code{PyLong_BASE}. Patch by Xinhang Xu.

@item 
bpo-46110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46110}: Add a maximum recursion check to the PEG parser to avoid stack
overflow. Patch by Pablo Galindo

@item 
bpo-46107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46107}: Fix bug where @code{ExceptionGroup.split()} and
@code{ExceptionGroup.subgroup()} did not copy the exception group's
@code{__note__} field to the parts.

@item 
bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}: The interpreter state's representation of handled exceptions
(a.k.a exc_info, or _PyErr_StackItem) now has only the @code{exc_value}
field, @code{exc_type} and @code{exc_traceback} have been removed as their
values can be derived from @code{exc_value}.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Replace the four call bytecode instructions which one pre-call
instruction and two call instructions.

Removes @code{CALL_FUNCTION}, @code{CALL_FUNCTION_KW}, @code{CALL_METHOD} and
@code{CALL_METHOD_KW}.

Adds @code{CALL_NO_KW} and @code{CALL_KW} call instructions, and
@code{PRECALL_METHOD} prefix for pairing with @code{LOAD_METHOD}.

@item 
bpo-46039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46039}: Remove the @code{YIELD_FROM} instruction and replace it with the
@code{SEND} instruction which performs the same operation, but without the
loop.

@item 
bpo-45635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45635}: The code called from @code{_PyErr_Display()} was refactored
to improve error handling. It now exits immediately upon an unrecoverable
error.

@item 
bpo-46054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46054}: Fix parser error when parsing non-utf8 characters in source
files. Patch by Pablo Galindo.

@item 
bpo-46042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46042}: Improve the location of the caret in @ref{18b,,SyntaxError}
exceptions emitted by the symbol table. Patch by Pablo Galindo.

@item 
bpo-46049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46049}: Ensure @code{._pth} files work as intended on platforms other
than Windows.

@item 
bpo-46048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46048}: Fixes parsing of @code{._pth} files on startup so that
single-character paths are correctly read.

@item 
bpo-37971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37971}: Fix a bug where the line numbers given in a traceback when a
decorator application raised an exception were wrong.

@item 
bpo-46031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46031}: Add @ref{1785,,POP_JUMP_IF_NOT_NONE} and
@ref{1784,,POP_JUMP_IF_NONE} opcodes to speed up conditional jumps.

@item 
bpo-45654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45654}: Deepfreeze @ref{bd,,runpy}, patch by Kumar Aditya.

@item 
bpo-46025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46025}: Fix a crash in the @ref{c,,atexit} module involving functions
that unregister themselves before raising exceptions. Patch by Pablo
Galindo.

@item 
bpo-46000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46000}: Improve compatibility of the @ref{2b,,curses} module with NetBSD
curses.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Specialize the CALL_FUNCTION instruction for calls to builtin
types with a single argument. Speeds up @code{range(x)}, @code{list(x)}, and
specifically @code{type(obj)}.

@item 
bpo-42918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42918}: Fix bug where the built-in @ref{190,,compile()} function did not
always raise a @ref{18b,,SyntaxError} when passed multiple statements in
'single' mode. Patch by Weipeng Hong.

@item 
bpo-45953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45953}: The main interpreter in _PyRuntimeState.interpreters is now
statically allocated (as part of _PyRuntime).  Likewise for the initial
thread state of each interpreter.  This means less allocation during
runtime init, as well as better memory locality for these key state
objects.

@item 
bpo-45292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45292}: Complete the 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/} implementation: add @code{except*}.

@item 
bpo-43413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43413}: Revert changes in @code{set.__init__}. Subclass of @ref{5c3,,set}
needs to define a @code{__init__()} method if it defines a @code{__new__()}
method with additional keyword parameters.

@item 
bpo-43931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43931}: Added the @ref{740,,Py_Version} constant which bears the same
value as @ref{741,,PY_VERSION_HEX}. Patch by Gabriele N. Tornetta.
@end itemize

@node Library<28>,Documentation<23>,Core and Builtins<29>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id236}@anchor{17ee}
@subsubsection Library



@itemize -

@item 
bpo-46342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46342}: The @code{@@typing.final} decorator now sets the @code{__final__}
attribute on the decorated object to allow runtime introspection. Patch by
Jelle Zijlstra.

@item 
bpo-46328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46328}: Added the @ref{676,,sys.exception()} method which returns the active
exception instance.

@item 
bpo-46307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46307}: Add @ref{671,,string.Template.is_valid()} and
@ref{670,,string.Template.get_identifiers()} methods.

@item 
bpo-46306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46306}: Assume that @ref{2dd,,types.CodeType} always has
@code{types.CodeType.co_firstlineno} in @ref{3a,,doctest}.

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: Fix @ref{67,,hashlib} `usedforsecurity' option to work correctly
with OpenSSL 3.0.0 in FIPS mode.

@item 
bpo-46070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46070}: Fix possible segfault when importing the @ref{a,,asyncio} module
from different sub-interpreters in parallel. Patch by Erlend E. Aasland.

@item 
bpo-46244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46244}: Removed @code{__slots__} from @ref{15d,,typing.ParamSpec} and
@ref{15c,,typing.TypeVar}. They served no purpose. Patch by Arie Bovenberg.

@item 
bpo-46278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46278}: Reflect @code{context} argument in @code{AbstractEventLoop.call_*()}
methods. Loop implementations already support it.

@item 
bpo-46269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46269}: Remove special-casing of @code{__new__} in
@ref{17ef,,enum.Enum.__dir__()}.

@item 
bpo-46266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46266}: Improve day constants in @ref{14,,calendar}.

Now all constants (@code{MONDAY} ... @code{SUNDAY}) are documented, tested, and
added to @code{__all__}.

@item 
bpo-46257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46257}: Optimized the mean, variance, and stdev functions in the
statistics module. If the input is an iterator, it is consumed in a single
pass rather than eating memory by conversion to a list.  The single pass
algorithm is about twice as fast as the previous two pass code.

@item 
bpo-41011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41011}: Added two new variables to `pyvenv.cfg' which is generated by
@ref{110,,venv} module: `executable' for the executable and `command' for the
command line used to create the environment.

@item 
bpo-46239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46239}: Improve error message when importing
@code{asyncio.windows_events} on non-Windows.

@item 
bpo-46238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46238}: Reuse @code{_winapi} constants in @code{asyncio.windows_events}.

@item 
bpo-46222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46222}: Adding @code{SF_NOCACHE} sendfile constant for FreeBSD for the
posixmodule.

@item 
bpo-37295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37295}: Add fast path for @code{0 <= k <= n <= 67} for @ref{6ba,,math.comb()}.

@item 
bpo-46176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46176}: Adding the @code{MAP_STACK} constant for the mmap module.

@item 
bpo-43424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43424}: Deprecate @code{webbrowser.MacOSXOSAScript._name} and use
@code{name} instead.

@item 
bpo-45321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45321}: Added missing error codes to module
@code{xml.parsers.expat.errors}.

@item 
bpo-46125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46125}: Refactor tests to test traversable API directly. Includes
changes from importlib 5.4.0.

@item 
bpo-46118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46118}: Moved importlib.resources and its related functionality to a
package.

@item 
bpo-37578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37578}: Add `include_hidden' parameter to @ref{29c,,glob()} and
@ref{7f1,,iglob()} to match hidden files and directories when using
special characters like @code{*}, @code{**}, @code{?} and @code{[]}.

@item 
bpo-20369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20369}: @ref{17f0,,concurrent.futures.wait()} no longer blocks forever when
given duplicate Futures. Patch by Kumar Aditya.

@item 
bpo-46105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46105}: Honor spec when generating requirement specs with urls and
extras (importlib_metadata 4.8.3).

@item 
bpo-44893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44893}: EntryPoint objects are no longer tuples. Recommended means to
access is by attribute ('.name', '.group') or accessor ('.load()'). Access
by index is deprecated and will raise deprecation warning.

@item 
bpo-22815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22815}: Print unexpected successes together with failures and errors in
summary in @ref{51a,,unittest.TextTestResult}.

@item 
bpo-22047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22047}: Calling @code{add_argument_group()} on an argument group is
deprecated. Calling @code{add_argument_group()} or
@code{add_mutually_exclusive_group()} on a mutually exclusive group is
deprecated.

These features were never supported and do not always work correctly. The
functions exist on the API by accident through inheritance and will be
removed in the future.

@item 
bpo-26952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26952}: @ref{6,,argparse} raises @ref{1ff,,ValueError} with clear message
when trying to render usage for an empty mutually exclusive group.
Previously it raised a cryptic @ref{14eb,,IndexError}.

@item 
bpo-45615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45615}: Functions in the @ref{fd,,traceback} module raise @ref{522,,TypeError}
rather than @ref{343,,AttributeError} when an exception argument is not of
type @ref{5a5,,BaseException}.

@item 
bpo-16594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16594}: Add allow allow_reuse_port flag in socketserver.

@item 
bpo-27718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27718}: Fix help for the @ref{c5,,signal} module. Some functions (e.g.
@code{signal()} and @code{getsignal()}) were omitted.

@item 
bpo-46032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46032}: The @code{registry()} method of @ref{624,,functools.singledispatch()}
functions checks now the first argument or the first parameter annotation
and raises a TypeError if it is not supported. Previously unsupported
"types" were ignored (e.g. @code{typing.List[int]}) or caused an error at
calling time (e.g. @code{list[int]}).

@item 
bpo-46014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46014}: Add ability to use @code{typing.Union} and @code{types.UnionType} as
dispatch argument to @code{functools.singledispatch}. Patch provided by Yurii
Karabas.

@item 
bpo-27062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27062}: Add @code{__all__} to @ref{7d,,inspect}, patch by Kumar Aditya.

@item 
bpo-46018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46018}: Ensure that @ref{11c9,,math.expm1()} does not raise on underflow.

@item 
bpo-46016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46016}: Adding @code{F_DUP2FD} and @code{F_DUP2FD_CLOEXEC} constants
from FreeBSD into the fcntl module.

@item 
bpo-45755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45755}: @ref{103,,typing} generic aliases now reveal the class attributes
of the original generic class when passed to @code{dir()}. This was the
behavior up to Python 3.6, but was changed in 3.7-3.9.

@item 
bpo-45874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45874}: The empty query string, consisting of no query arguments, is
now handled correctly in @code{urllib.parse.parse_qsl}. This caused problems
before when strict parsing was enabled.

@item 
bpo-44674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44674}: Change how dataclasses disallows mutable default values.  It
used to use a list of known types (list, dict, set).  Now it disallows
unhashable objects to be defaults.  It's using unhashability as a proxy
for mutability.  Patch by Eric V. Smith, idea by Raymond Hettinger.

@item 
bpo-23882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23882}: Remove namespace package (PEP 420) support from unittest
discovery. It was introduced in Python 3.4 but has been broken since
Python 3.7.

@item 
bpo-25066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25066}: Added a @code{__repr__()} method to
@ref{17f1,,multiprocessing.Event} objects, patch by Kumar Aditya.

@item 
bpo-45643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45643}: Added @ref{17f2,,signal.SIGSTKFLT} on platforms where this signal
is defined.

@item 
bpo-44092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44092}: Fetch across rollback no longer raises
@ref{668,,InterfaceError}. Instead we leave it to the SQLite library
to handle these cases. Patch by Erlend E. Aasland.

@item 
bpo-42413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42413}: Replace @code{concurrent.futures.TimeoutError} and
@code{asyncio.TimeoutError} with builtin @ref{81f,,TimeoutError}, keep these
names as deprecated aliases.
@end itemize

@node Documentation<23>,Tests<26>,Library<28>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id237}@anchor{17f3}
@subsubsection Documentation



@itemize -

@item 
bpo-46196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46196}: Document method @ref{17f4,,cmd.Cmd.columnize()}.

@item 
bpo-46120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46120}: State that @code{|} is preferred for readability over @code{Union} in
the @ref{103,,typing} docs.

@item 
bpo-46109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46109}: Extracted @code{importlib.resources} and
@code{importlib.resources.abc} documentation into separate files.

@item 
bpo-19737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19737}: Update the documentation for the @ref{17f5,,globals()} function.
@end itemize

@node Tests<26>,Build<28>,Documentation<23>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id238}@anchor{17f6}
@subsubsection Tests



@itemize -

@item 
bpo-46296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46296}: Add a test case for @ref{55,,enum} with @code{_use_args_ == True} and
@code{_member_type_ == object}.

@item 
bpo-46205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46205}: Fix hang in runtest_mp due to race condition

@item 
bpo-46263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46263}: Fix test_capi on FreeBSD 14-dev: instruct jemalloc to not fill
freed memory with junk byte.

@item 
bpo-46262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46262}: Cover @code{ValueError} path in tests for
@code{enum.Flag._missing_()}.

@item 
bpo-46150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46150}: Now @code{fakename} in
@code{test_pathlib.PosixPathTest.test_expanduser} is checked to be
non-existent.

@item 
bpo-46129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46129}: Rewrite @code{asyncio.locks} tests with
@ref{301,,unittest.IsolatedAsyncioTestCase} usage.

@item 
bpo-23819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23819}: Fixed @ref{a,,asyncio} tests in python optimized mode. Patch by
Kumar Aditya.

@item 
bpo-46114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46114}: Fix test case for OpenSSL 3.0.1 version. OpenSSL 3.0 uses
@code{0xMNN00PP0L}.
@end itemize

@node Build<28>,Windows<25>,Tests<26>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id239}@anchor{17f7}
@subsubsection Build



@itemize -

@item 
bpo-44133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44133}: When Python is configured with
@ref{87a,,--without-static-libpython}, the Python static library
(libpython.a) is no longer built. Patch by Victor Stinner.

@item 
bpo-44133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44133}: When Python is built without @ref{84d,,--enable-shared}, the
@code{python} program is now linked to object files, rather than being linked
to the Python static library (libpython.a), to make sure that all symbols
are exported. Previously, the linker omitted some symbols like the
@code{Py_FrozenMain()} function. Patch by Victor Stinner.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: The @code{configure} script has a new option
@code{--with-emscripten-target} to select browser or node as Emscripten build
target.

@item 
bpo-46315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46315}: Added and fixed @code{#ifdef HAVE_FEATURE} checks for
functionality that is not available on WASI platform.

@item 
bpo-45723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45723}: Fixed a regression in @code{configure} check for
@ref{f7e,,select.epoll()}.

@item 
bpo-46263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46263}: @code{configure} no longer sets @code{MULTIARCH} on FreeBSD
platforms.

@item 
bpo-46106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46106}: Updated OpenSSL to 1.1.1m in Windows builds, macOS installer
builds, and CI. Patch by Kumar Aditya.

@item 
bpo-46088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46088}: Automatically detect or install bootstrap Python runtime when
building from Visual Studio.

@item 
bpo-46072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46072}: Add a --with-pystats configure option to turn on internal
statistics gathering.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: A new directory @code{Tools/wasm} contains WebAssembly-related
helpers like @code{config.site} override for wasm32-emscripten, wasm assets
generator to bundle the stdlib, and a README.

@item 
bpo-46023@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46023}: @code{makesetup} no longer builds extensions that have been
marked as `disabled'. This allows users to disable modules in
@code{Modules/Setup.local}.

@item 
bpo-45949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45949}: Use pure Python @code{freeze_module} for all but importlib
bootstrap files. @code{--with-freeze-module} @code{configure} option is
no longer needed for cross builds.
@end itemize

@node Windows<25>,macOS<19>,Build<28>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id240}@anchor{17f8}
@subsubsection Windows



@itemize -

@item 
bpo-46217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46217}: Removed parameter that is unsupported on Windows 8.1 and early
Windows 10 and may have caused build or runtime failures.
@end itemize

@node macOS<19>,C API<27>,Windows<25>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id241}@anchor{17f9}
@subsubsection macOS



@itemize -

@item 
bpo-40477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40477}: The Python Launcher app for macOS now properly launches scripts
and, if necessary, the Terminal app when running on recent macOS releases.
@end itemize

@node C API<27>,,macOS<19>,Python 3 11 0 alpha 4
@anchor{whatsnew/changelog id242}@anchor{17fa}
@subsubsection C API



@itemize -

@item 
bpo-46236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46236}: Fix a bug in @ref{1748,,PyFunction_GetAnnotations()} that caused it
to return a @code{tuple} instead of a @code{dict}.

@item 
bpo-46140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46140}: @ref{743,,PyBuffer_GetPointer()},
@ref{746,,PyBuffer_FromContiguous()}, @ref{745,,PyBuffer_ToContiguous()} and
@ref{74b,,PyMemoryView_FromBuffer()} now take buffer info by @code{const
Py_buffer *} instead of @code{Py_buffer *}, as they do not need mutability.
@ref{746,,PyBuffer_FromContiguous()} also now takes the source buffer as
@code{const void *}, and similarly @ref{743,,PyBuffer_GetPointer()} takes the
strides as @code{const Py_ssize_t *}.

@item 
bpo-45855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45855}: Document that the `no_block' argument to
@ref{17fb,,PyCapsule_Import()} is a no-op now.

@item 
bpo-45855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45855}: Replaced deprecated usage of
@ref{3b4,,PyImport_ImportModuleNoBlock()} with
@ref{3b5,,PyImport_ImportModule()} in stdlib modules. Patch by Kumar Aditya.

@item 
bpo-46007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46007}: The @code{PyUnicode_CHECK_INTERNED()} macro has been excluded
from the limited C API. It was never usable there, because it used
internal structures which are not available in the limited C API. Patch by
Victor Stinner.
@end itemize

@node Python 3 11 0 alpha 3,Python 3 11 0 alpha 2,Python 3 11 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-3}@anchor{17fc}
@subsection Python 3.11.0 alpha 3


`Release date: 2021-12-08'

@menu
* Core and Builtins: Core and Builtins<30>. 
* Library: Library<29>. 
* Documentation: Documentation<24>. 
* Tests: Tests<27>. 
* Build: Build<29>. 
* Windows: Windows<26>. 
* macOS: macOS<20>. 
* C API: C API<28>. 

@end menu

@node Core and Builtins<30>,Library<29>,,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id243}@anchor{17fd}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-46009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46009}: Restore behavior from 3.9 and earlier when sending non-None to
newly started generator. In 3.9 this did not affect the state of the
generator. In 3.10.0 and 3.10.1 @code{gen_func().send(0)} is equivalent to
@code{gen_func().throw(TypeError(...)} which exhausts the generator. In
3.10.2 onward, the behavior has been reverted to that of 3.9.

@item 
bpo-46004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46004}: Fix the @ref{18b,,SyntaxError} location for errors involving for
loops with invalid targets. Patch by Pablo Galindo

@item 
bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}: @code{_PyErr_ChainStackItem()} no longer normalizes
@code{exc_info} (including setting the traceback on the exception instance)
because @code{exc_info} is always normalized.

@item 
bpo-45607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45607}: The @code{__note__} field was added to @ref{5a5,,BaseException}. It is
@code{None} by default but can be set to a string which is added to the
exception's traceback.

@item 
bpo-45947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45947}: Place pointers to dict and values immediately before GC header.
This reduces number of dependent memory loads to access either dict or
values from 3 to 1.

@item 
bpo-45915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45915}: @code{is_valid_fd} now uses faster @code{fcntl(fd, F_GETFD)} on
Linux, macOS, and Windows.

@item 
bpo-44530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44530}: Reverts a change to the @code{code.__new__} @ref{17fe,,audit event} from an earlier prerelease.

@item 
bpo-42268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42268}: Fail the configure step if the selected compiler doesn't
support memory sanitizer. Patch by Pablo Galindo

@item 
bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}: The three values of @code{exc_info} are now always consistent with
each other. In particular, the @code{type} and @code{traceback} fields are now
derived from the exception instance. This impacts the return values of
@ref{675,,sys.exc_info()} and @ref{75c,,PyErr_GetExcInfo()} if the exception
instance is modified while the exception is handled, as well as
@ref{75b,,PyErr_SetExcInfo()}, which now ignores the @code{type} and
@code{traceback} arguments provided to it.

@item 
bpo-45727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45727}: Refine the custom syntax error that suggests that a comma may
be missing to trigger only when the expressions are detected between
parentheses or brackets. Patch by Pablo Galindo

@item 
bpo-45885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45885}: Specialized the @code{COMPARE_OP} opcode using the PEP 659
machinery.

@item 
bpo-45786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45786}: Allocate space for the interpreter frame in the frame object,
to avoid an additional allocation when the frame object outlives the frame
activation.

@item 
bpo-45614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45614}: Fix @ref{fd,,traceback} display for exceptions with invalid module
name.

@item 
bpo-45813@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45813}: Fix crash when calling coro.cr_frame.clear() after coroutine
has been freed.

@item 
bpo-45811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45811}: Improve the tokenizer errors when encountering invisible
control characters in the parser. Patch by Pablo Galindo

@item 
bpo-45848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45848}: Allow the parser to obtain error lines directly from encoded
files. Patch by Pablo Galindo

@item 
bpo-45709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45709}: Restore behavior from 3.10 when tracing an exception raised
within a with statement.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Adds new @ref{6e8,,COPY_FREE_VARS} opcode, to make copying of
free variables from function to frame explicit. Helps optimization of
calls to Python function.

@item 
bpo-45829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45829}: Specialize @ref{16cb,,BINARY_SUBSCR} for classes with a
@code{__getitem__} method implemented in Python

@item 
bpo-45826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45826}: Fixed a crash when calling @code{.with_traceback(None)} on
@code{NameError}. This occurs internally in
@code{unittest.TestCase.assertRaises()}.

@item 
bpo-45822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45822}: Fixed a bug in the parser that was causing it to not respect
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/} coding cookies when no flags are provided. Patch by Pablo
Galindo

@item 
bpo-45820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45820}: Fix a segfault when the parser fails without reading any input.
Patch by Pablo Galindo

@item 
bpo-45636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45636}: Simplify the implementation of @ref{6f0,,BINARY_OP} by indexing
into an array of function pointers (rather than switching on the oparg).

@item 
bpo-42540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42540}: Fix crash when @ref{195,,os.fork()} is called with an active
non-default memory allocator.

@item 
bpo-45738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45738}: Fix computation of error location for invalid continuation
characters in the parser. Patch by Pablo Galindo.

@item 
bpo-45636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45636}: Remove an existing "fast path" for old-style string formatting,
since it no longer appears to have any measurable impact.

@item 
bpo-45753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45753}: Make recursion checks a bit more efficient by tracking amount
of calls left before overflow.

@item 
bpo-45773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45773}: Fix a compiler hang when attempting to optimize certain jump
patterns.

@item 
bpo-45764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45764}: The parser now gives a better error message when leaving out
the opening parenthesis @code{(} after a @code{def}-statement:

@example
>>> def f:
  File "<stdin>", line 1
    def f:
         ^
SyntaxError: expected '('
@end example

@item 
bpo-45609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45609}: Specialized the @code{STORE_SUBSCR} opcode using the PEP 659
machinery.

@item 
bpo-45636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45636}: Replace all numeric @code{BINARY_*} and @code{INPLACE_*} instructions
with a single @ref{6f0,,BINARY_OP} implementation.

@item 
bpo-45582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45582}: Path calculation (known as @code{getpath}) has been reimplemented
as a frozen Python module. This should have no visible impact, but may
affect calculation of all paths referenced in @ref{d8,,sys} and
@ref{da,,sysconfig}.

@item 
bpo-45450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45450}: Improve the syntax error message for parenthesized arguments.
Patch by Pablo Galindo.
@end itemize

@node Library<29>,Documentation<24>,Core and Builtins<30>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id244}@anchor{17ff}
@subsubsection Library



@itemize -

@item 
bpo-27946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27946}: Fix possible crash when getting an attribute of
@ref{305,,xml.etree.ElementTree.Element} simultaneously with replacing the
@code{attrib} dict.

@item 
bpo-45711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45711}: Make @ref{a,,asyncio} normalize exceptions as soon as they are
captured with @ref{3e9,,PyErr_Fetch()}, and before they are stored as an
exc_info triplet. This brings @ref{a,,asyncio} in line with the rest of the
codebase, where an exc_info triplet is always normalized.

@item 
bpo-23819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23819}: Replaced asserts with exceptions in asyncio, patch by Kumar
Aditya.

@item 
bpo-13236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13236}: @ref{51a,,unittest.TextTestResult} and
@ref{16d0,,unittest.TextTestRunner} flush now the output stream more often.

@item 
bpo-45917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45917}: Added @ref{64b,,math.exp2()}:, which returns 2 raised to the power
of x.

@item 
bpo-37658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37658}: Fix issue when on certain conditions @code{asyncio.wait_for()} may
allow a coroutine to complete successfully, but fail to return the result,
potentially causing memory leaks or other issues.

@item 
bpo-45876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45876}: Improve the accuracy of stdev() and pstdev() in the statistics
module.  When the inputs are floats or fractions, the output is a
correctly rounded float

@item 
bpo-44649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44649}: Handle dataclass(slots=True) with a field that has default a
default value, but for which init=False.

@item 
bpo-45803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45803}: Added missing kw_only parameter to
dataclasses.make_dataclass().

@item 
bpo-45837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45837}: The @code{turtle.RawTurtle.settiltangle()} is deprecated since
Python 3.1, it now emits a deprecation warning and will be removed in
Python 3.13.

Use @code{turtle.RawTurtle.tiltangle()} instead.

@code{turtle.RawTurtle.tiltangle()} was earlier incorrectly marked as
deprecated, its docstring has been corrected.

Patch by Hugo van Kemenade.

@item 
bpo-45831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45831}: @ref{57,,faulthandler} can now write ASCII-only strings (like
filenames and function names) with a single write() syscall when dumping a
traceback. It reduces the risk of getting an unreadable dump when two
threads or two processes dump a traceback to the same file (like stderr)
at the same time. Patch by Victor Stinner.

@item 
bpo-45828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45828}: @code{sqlite} C callbacks now use unraisable exceptions if
callback tracebacks are enabled. Patch by Erlend E. Aasland.

@item 
bpo-41735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41735}: Fix thread lock in @code{zlib.Decompress.flush()} method before
@code{PyObject_GetBuffer}.

@item 
bpo-45235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45235}: Reverted an argparse bugfix that caused regression in the
handling of default arguments for subparsers.  This prevented leaf level
arguments from taking precedence over root level arguments.

@item 
bpo-45754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45754}: Fix a regression in Python 3.11a1 and 3.11a2 where
@ref{ce,,sqlite3} incorrectly would use @code{SQLITE_LIMIT_LENGTH} when checking
SQL statement lengths. Now, @code{SQLITE_LIMIT_SQL_LENGTH} is used. Patch by
Erlend E. Aasland.

@item 
bpo-45766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45766}: Added `proportional' option to
@ref{81b,,statistics.linear_regression()}.

@item 
bpo-45765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45765}: In importlib.metadata, fix distribution discovery for an empty
path.

@item 
bpo-45757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45757}: Fix bug where @ref{38,,dis} produced an incorrect oparg when
@ref{1733,,EXTENDED_ARG} is followed by an opcode that does not use its
argument.

@item 
bpo-45644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45644}: In-place JSON file formatting using @code{python3 -m json.tool
infile infile} now works correctly, previously it left the file empty.
Patch by Chris Wesseling.

@item 
bpo-45703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45703}: When a namespace package is imported before another module from
the same namespace is created/installed in a different @ref{3ab,,sys.path}
location while the program is running, calling the
@ref{bfe,,importlib.invalidate_caches()} function will now also guarantee the
new module is noticed.

@item 
bpo-45535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45535}: Improve output of @code{dir()} with Enums.

@item 
bpo-45664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45664}: Fix @ref{b8a,,types.resolve_bases()} and @ref{1141,,types.new_class()} for
@ref{7d5,,types.GenericAlias} instance as a base.

@item 
bpo-45663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45663}: Fix @ref{1800,,dataclasses.is_dataclass()} for dataclasses which are
subclasses of @ref{7d5,,types.GenericAlias}.

@item 
bpo-45662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45662}: Fix the repr of @code{dataclasses.InitVar} with a type alias
to the built-in class, e.g. @code{InitVar[list[int]]}.

@item 
bpo-43137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43137}: Launch GNOME web browsers via gio tool instead of obsolete
gvfs-open

@item 
bpo-45429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45429}: On Windows, @ref{688,,time.sleep()} now uses a waitable timer which
supports high-resolution timers. Patch by Donghee Na and Eryk Sun.

@item 
bpo-37295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37295}: Optimize @ref{6ba,,math.comb()} and @ref{6bb,,math.perm()}.

@item 
bpo-45514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45514}: Deprecated legacy functions in @ref{7a,,importlib.resources}.

@item 
bpo-45507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45507}: Add tests for truncated/missing trailers in gzip.decompress
implementation.

@item 
bpo-45359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45359}: Implement 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} for @ref{8ce,,graphlib.TopologicalSorter}.

@item 
bpo-44733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44733}: Add @code{max_tasks_per_child} to
@ref{8db,,concurrent.futures.ProcessPoolExecutor}. This allows users to
specify the maximum number of tasks a single process should execute before
the process needs to be restarted.

@item 
bpo-28806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28806}: Improve netrc library. netrc file no longer needs to contain
all tokens. And if the login name is anonymous, security check is no
longer need.

@item 
bpo-43498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43498}: Avoid a possible `"RuntimeError: dictionary changed size during
iteration"' when adjusting the process count of
@code{ProcessPoolExecutor}.

@item 
bpo-42158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42158}: Add MIME types for N-quads, N-triples, Notation3 and TriG to
@code{mimetypes}.

@item 
bpo-30533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30533}: Add @ref{634,,inspect.getmembers_static()} , it return all members
without triggering dynamic lookup via the descriptor protocol. Patch by
Weipeng Hong.
@end itemize

@node Documentation<24>,Tests<27>,Library<29>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id245}@anchor{1801}
@subsubsection Documentation



@itemize -

@item 
bpo-42238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42238}: @code{make -C Doc suspicious} will be removed soon in favor of
@code{make -C Doc check}, mark it as deprecated.

@item 
bpo-45840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45840}: Improve cross-references in the documentation for the data
model.

@item 
bpo-45640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45640}: Properly marked-up grammar tokens in the documentation are now
clickable and take you to the definition of a given piece of grammar.
Patch by Arthur Milchior.

@item 
bpo-45788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45788}: Link doc for sys.prefix to sysconfig doc on installation paths.

@item 
bpo-45772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45772}: @code{socket.socket} documentation is corrected to a class from a
function.

@item 
bpo-45392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45392}: Update the docstring of the @ref{d36,,type} built-in to remove a
redundant line and to mention keyword arguments for the constructor.

@item 
bpo-45250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45250}: Update the documentation to note that CPython does not
consistently require iterators to define @code{__iter__}.

@item 
bpo-25381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25381}: In the extending chapter of the extending doc, update a
paragraph about the global variables containing exception information.

@item 
bpo-43905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43905}: Expanded @ref{16b8,,astuple()} and
@ref{16af,,asdict()} docs, warning about deepcopy being applied and
providing a workaround.
@end itemize

@node Tests<27>,Build<29>,Documentation<24>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id246}@anchor{1802}
@subsubsection Tests



@itemize -

@item 
bpo-45695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45695}: Out-of-tree builds with a read-only source directory are now
tested by CI.

@item 
bpo-19460@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19460}: Add new Test for
@code{Lib/email/mime/nonmultipart.py::MIMENonMultipart}.

@item 
bpo-45835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45835}: Fix race condition in test_queue tests with multiple "feeder"
threads.

@item 
bpo-45783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45783}: The test for the freeze tool now handles file moves and
deletions.

@item 
bpo-45745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45745}: Remove the @code{--findleaks} command line option of regrtest: use
the @code{--fail-env-changed} option instead. Since Python 3.7, it was a
deprecated alias to the @code{--fail-env-changed} option.

@item 
bpo-45701@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45701}: Add tests with @code{tuple} type with @ref{9dd,,functools.lru_cache()}
to @code{test_functools}.
@end itemize

@node Build<29>,Windows<26>,Tests<27>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id247}@anchor{1803}
@subsubsection Build



@itemize -

@item 
bpo-44035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44035}: CI now verifies that autoconf files have been regenerated with
a current and unpatched autoconf package.

@item 
bpo-45950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45950}: The build system now uses a @code{_bootstrap_python}
interpreter for freezing and deepfreezing again. To speed up build process
the build tools @code{_bootstrap_python} and @code{_freeze_module}
are no longer build with LTO.

@item 
bpo-45881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45881}: The @code{configure} script now accepts
@code{--with-build-python} and @code{--with-freeze-module} options to make cross
compiling easier.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Emscripten platform now uses @code{.wasm} suffix by default.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: Disable unusable core extension modules on WASM/Emscripten
targets.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @code{configure} now checks for socket @code{shutdown} function. The
check makes it possible to disable @code{SYS_shutdown} with
@code{ac_cv_func_shutdown=no} in CONFIG_SITE.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @code{configure} now checks for functions @code{fork1, getegid,
geteuid, getgid, getppid, getuid, opendir, pipe, system, wait, ttyname}.

@item 
bpo-33393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33393}: Update @code{config.guess} to 2021-06-03 and @code{config.sub} to
2021-08-14. @code{Makefile} now has an @code{update-config} target to make
updating more convenient.

@item 
bpo-45866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45866}: @code{make regen-all} now produces the same output when run from a
directory other than the source tree: when building Python out of the
source tree. pegen now strips directory of the "generated by pygen from
<FILENAME>" header Patch by Victor Stinner.

@item 
bpo-40280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40280}: @code{configure} now accepts machine @code{wasm32} or @code{wasm64} and
OS @code{wasi} or @code{emscripten} for cross building, e.g.
@code{wasm32-unknown-emscripten}, @code{wasm32-wasi}, or
@code{wasm32-unknown-wasi}.

@item 
bpo-41498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41498}: Python now compiles on platforms without @code{sigset_t}. Several
functions in @ref{c5,,signal} are not available when @code{sigset_t} is missing.

Based on patch by Roman Yurchak for pyodide.

@item 
bpo-45881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45881}: @code{setup.py} now uses @code{CC} from environment first to discover
multiarch and cross compile paths.

@item 
bpo-45886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45886}: The @code{_freeze_module} program path can now be overridden on
the command line, e.g. @code{make
FREEZE_MODULE=../x86_64/Program/_freeze_module}.

@item 
bpo-45873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45873}: Get rid of the @code{_bootstrap_python} build step. The
deepfreeze.py script is now run using @code{$(PYTHON_FOR_REGEN)} which can be
Python 3.7 or newer (on Windows, 3.8 or newer).

@item 
bpo-45847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45847}: Port builtin hashlib extensions to @code{PY_STDLIB_MOD} macro and
@code{addext()}.

@item 
bpo-45723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45723}: Add @code{autoconf} helpers for saving and restoring environment
variables:


@itemize *

@item 
@code{SAVE_ENV}: Save @code{$CFLAGS}, @code{$LDFLAGS}, @code{$LIBS}, and
@code{$CPPFLAGS}.

@item 
@code{RESTORE_ENV}: Restore @code{$CFLAGS}, @code{$LDFLAGS}, @code{$LIBS}, and
@code{$CPPFLAGS}.

@item 
@code{WITH_SAVE_ENV([SCRIPT])}: Run @code{SCRIPT} wrapped with @code{SAVE_ENV} and
@code{RESTORE_ENV}.
@end itemize

Patch by Erlend E. Aasland.

@item 
bpo-45573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45573}: Mandatory core modules, that are required to bootstrap Python,
are now in @code{Modules/Setup.bootstrap}.

@item 
bpo-45573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45573}: @code{configure} now creates @code{Modules/Setup.stdlib} with
conditionally enabled/disabled extension module lines. The file is not
used, yet.

@item 
bpo-45573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45573}: @code{configure} now uses a unified format to set state, compiler
flags, and linker flags in Makefile. The new macro @code{PY_STDLIB_MOD} sets
three variables that are consumed by @code{Modules/Setup} and @code{setup.py}.

@item 
bpo-45816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45816}: Python now supports building with Visual Studio 2022 (MSVC
v143, VS Version 17.0). Patch by Jeremiah Vivian.

@item 
bpo-45800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45800}: Settings for @code{pyexpat} C extension are now detected by
@code{configure}. The bundled @code{expat} library is built in @code{Makefile}.

@item 
bpo-45798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45798}: Settings for @ref{36,,decimal} internal C extension are now
detected by @code{configure}. The bundled @code{libmpdec} library is built in
@code{Makefile}.

@item 
bpo-45723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45723}: @code{configure} has a new option @code{--with-pkg-config} to
disable or require pkg-config.

@item 
bpo-45774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45774}: The build dependencies for @ref{ce,,sqlite3} are now detected by
@code{configure} and @code{pkg-config}. Patch by Erlend E. Aasland.

@item 
bpo-45763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45763}: The build dependencies for @ref{132,,zlib}, @ref{13,,bz2}, and
@ref{89,,lzma} are now detected by @code{configure}.

@item 
bpo-45747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45747}: gdbm and dbm build dependencies are now detected by
@code{configure}.

@item 
bpo-45743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45743}: On macOS, the build system no longer passes
@code{search_paths_first} to the linker. The flag has been the default since
Xcode 4 / macOS 10.6.

@item 
bpo-45723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45723}: @code{configure.ac} is now compatible with autoconf 2.71.
Deprecated checks @code{STDC_HEADERS} and @code{AC_HEADER_TIME} have been
removed.

@item 
bpo-45723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45723}: @code{configure} now prints a warning when pkg-config is missing.

@item 
bpo-45731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45731}: @code{configure --enable-loadable-sqlite-extensions} is now
handled by new @code{PY_SQLITE_ENABLE_LOAD_EXTENSION} macro instead of logic
in setup.py.

@item 
bpo-45723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45723}: configure.ac now uses custom helper macros and
@code{AC_CACHE_CHECK} to simplify and speed up configure runs.

@item 
bpo-45696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45696}: Skip the marshal step for frozen modules by generating C code
that produces a set of ready-to-use code objects. This speeds up startup
time by another 10% or more.

@item 
bpo-45561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45561}: Run smelly.py tool from $(srcdir).
@end itemize

@node Windows<26>,macOS<20>,Build<29>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id248}@anchor{1804}
@subsubsection Windows



@itemize -

@item 
bpo-46105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=46105}: Fixed calculation of @ref{3ab,,sys.path} in a venv on Windows.

@item 
bpo-45901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45901}: When installed through the Microsoft Store and set as the
default app for @code{*.py} files, command line arguments will now be
passed to Python when invoking a script without explicitly launching
Python (that is, @code{script.py args} rather than @code{python script.py
args}).

@item 
bpo-45616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45616}: Fix Python Launcher's ability to distinguish between versions
3.1 and 3.10 when either one is explicitly requested.  Previously, 3.1
would be used if 3.10 was requested but not installed, and 3.10 would be
used if 3.1 was requested but 3.10 was installed.

@item 
bpo-45850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45850}: Implement changes to build with deep-frozen modules on Windows.
Note that we now require Python 3.10 as the "bootstrap" or "host" Python.

@item 
bpo-45732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45732}: Updates bundled Tcl/Tk to 8.6.12.

@item 
bpo-45720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45720}: Internal reference to @code{shlwapi.dll} was dropped to help
improve startup time. This DLL will no longer be loaded at the start of
every Python process.
@end itemize

@node macOS<20>,C API<28>,Windows<26>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id249}@anchor{1805}
@subsubsection macOS



@itemize -

@item 
bpo-45732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45732}: Update python.org macOS installer to use Tcl/Tk 8.6.12.
@end itemize

@node C API<28>,,macOS<20>,Python 3 11 0 alpha 3
@anchor{whatsnew/changelog id250}@anchor{1806}
@subsubsection C API



@itemize -

@item 
bpo-39026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39026}: Fix Python.h to build C extensions with Xcode: remove a
relative include from @code{Include/cpython/pystate.h}.
@end itemize

@node Python 3 11 0 alpha 2,Python 3 11 0 alpha 1,Python 3 11 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-2}@anchor{1807}
@subsection Python 3.11.0 alpha 2


`Release date: 2021-11-05'

@menu
* Core and Builtins: Core and Builtins<31>. 
* Library: Library<30>. 
* Documentation: Documentation<25>. 
* Tests: Tests<28>. 
* Build: Build<30>. 
* Windows: Windows<27>. 
* macOS: macOS<21>. 
* IDLE: IDLE<18>. 
* C API: C API<29>. 

@end menu

@node Core and Builtins<31>,Library<30>,,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id251}@anchor{1808}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-45716@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45716}: Improve the @ref{18b,,SyntaxError} message when using @code{True},
@code{None} or @code{False} as keywords in a function call. Patch by Pablo
Galindo.

@item 
bpo-45688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45688}: @ref{82b,,sys.stdlib_module_names} now contains the macOS-specific
module @code{_scproxy}.

@item 
bpo-45379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45379}: Clarify @ref{40f,,ImportError} message when we try to explicitly
import a frozen module but frozen modules are disabled.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Specialize simple calls to Python functions (no starargs,
keyword dict, or closure)

@item 
bpo-45530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45530}: Cases of sorting using tuples as keys may now be significantly
faster in some cases. Patch by Tim Peters.

The order of the result may differ from earlier releases if the tuple
elements don't define a total ordering (see
@ref{1809,,Comparaisons de valeurs} for information on total ordering).
It's generally true that the result of sorting simply isn't well-defined
in the absence of a total ordering on list elements.

@item 
bpo-45526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45526}: In obmalloc, set ADDRESS_BITS to not ignore any bits (ignored
16 before). That is safer in the case that the kernel gives user-space
virtual addresses that span a range greater than 48 bits.

@item 
bpo-30570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30570}: Fixed a crash in @code{issubclass()} from infinite recursion when
searching pathological @code{__bases__} tuples.

@item 
bpo-45521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45521}: Fix a bug in the obmalloc radix tree code.  On 64-bit machines,
the bug causes the tree to hold 46-bits of virtual addresses, rather than
the intended 48-bits.

@item 
bpo-45494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45494}: Fix parser crash when reporting errors involving invalid
continuation characters. Patch by Pablo Galindo.

@item 
bpo-45445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45445}: Python now fails to initialize if it finds an invalid
@ref{175,,-X} option in the command line. Patch by Pablo Galindo.

@item 
bpo-45340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45340}: Object attributes are held in an array instead of a dictionary.
An object's dictionary are created lazily, only when needed. Reduces the
memory consumption of a typical Python object by about 30%. Patch by Mark
Shannon.

@item 
bpo-45408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45408}: Fix a crash in the parser when reporting tokenizer errors that
occur at the same time unclosed parentheses are detected. Patch by Pablo
Galindo.

@item 
bpo-29410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29410}: Add SipHash13 for string hash algorithm and use it by default.

@item 
bpo-45385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45385}: Fix reference leak from descr_check. Patch by Donghee Na.

@item 
bpo-45367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45367}: Specialized the @code{BINARY_MULTIPLY} opcode to
@code{BINARY_MULTIPLY_INT} and @code{BINARY_MULTIPLY_FLOAT} using the PEP 659
machinery.

@item 
bpo-21736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21736}: Frozen stdlib modules now have @code{__file__} to the .py file
they would otherwise be loaded from, if possible.  For packages,
@code{__path__} now has the correct entry instead of being an empty list,
which allows unfrozen submodules to be imported.  These are set only if
the stdlib directory is known when the runtime is initialized.  Note that
the file at @code{__file__} is not guaranteed to exist.  None of this affects
non-stdlib frozen modules nor, for now, frozen modules imported using
@code{PyImport_ImportFrozenModule()}.  Also, at the moment @code{co_filename} is
not updated for the module.

@item 
bpo-45020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45020}: For frozen stdlib modules, record the original module name as
@code{module.__spec__.loader_state.origname}.  If the value is different than
@code{module.__spec__.name} then the module was defined as an alias in
Tools/scripts/freeze_modules.py.  If it is @code{None} then the module comes
from a source file outside the stdlib.

@item 
bpo-45324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45324}: In FrozenImporter.find_spec(), we now preserve the information
needed in exec_module() to load the module.  This change mostly impacts
internal details, rather than changing the importer's behavior.

@item 
bpo-45292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45292}: Implement 
@geindex Python Enhancement Proposals; PEP 654
PEP 654@footnote{https://peps.python.org/pep-0654/}. Add @ref{1b4,,ExceptionGroup} and
@ref{25c,,BaseExceptionGroup}. Update traceback display code.

@item 
bpo-40116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40116}: Change to the implementation of split dictionaries. Classes
where the instances differ either in the exact set of attributes, or in
the order in which those attributes are set, can still share keys. This
should have no observable effect on users of Python or the C-API. Patch by
Mark Shannon.

@item 
bpo-44050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44050}: Extensions that indicate they use global state (by setting
@code{m_size} to -1) can again be used in multiple interpreters. This reverts
to behavior of Python 3.8.

@item 
bpo-44525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44525}: Setup initial specialization infrastructure for the
@code{CALL_FUNCTION} opcode. Implemented initial specializations for C
function calls:


@itemize *

@item 
@code{CALL_FUNCTION_BUILTIN_O} for @code{METH_O} flag.

@item 
@code{CALL_FUNCTION_BUILTIN_FAST} for @code{METH_FASTCALL} flag without keywords.

@item 
@code{CALL_FUNCTION_LEN} for @code{len(o)}.

@item 
@code{CALL_FUNCTION_ISINSTANCE} for @code{isinstance(o, t)}.
@end itemize

@item 
bpo-44511@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44511}: Improve the generated bytecode for class and mapping patterns.

@item 
bpo-43706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43706}: Speed up calls to @code{enumerate()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.
@end itemize

@node Library<30>,Documentation<25>,Core and Builtins<31>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id252}@anchor{180a}
@subsubsection Library



@itemize -

@item 
bpo-45679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45679}: Fix caching of multi-value @ref{83f,,typing.Literal}.
@code{Literal[True, 2]} is no longer equal to @code{Literal[1, 2]}.

@item 
bpo-42064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42064}: Convert @ref{ce,,sqlite3} to multi-phase initialisation (PEP 489).
Patches by Erlend E. Aasland.

@item 
bpo-45438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45438}: Fix typing.Signature string representation for generic builtin
types.

@item 
bpo-45613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45613}: @ref{ce,,sqlite3} now sets @ref{667,,sqlite3.threadsafety} based on
the default threading mode the underlying SQLite library has been compiled
with. Patch by Erlend E. Aasland.

@item 
bpo-45574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45574}: Fix warning about @code{print_escape} being unused.

@item 
bpo-45581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45581}: @ref{2a5,,sqlite3.connect()} now correctly raises @ref{164b,,MemoryError}
if the underlying SQLite API signals memory error. Patch by Erlend E.
Aasland.

@item 
bpo-45557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45557}: @ref{812,,pprint.pprint()} now handles `underscore_numbers'
correctly. Previously it was always setting it to @code{False}.

@item 
bpo-44019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44019}: Add @ref{180b,,operator.call()} to @code{operator.__all__}. Patch by
Kreusada.

@item 
bpo-42174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42174}: @ref{10e3,,shutil.get_terminal_size()} now falls back to sane values
if the column or line count are 0.

@item 
bpo-35673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35673}: Improve the introspectability of the @code{__loader__} attribute
for namespace packages.  @ref{f41,,importlib.machinery.NamespaceLoader} is
now public, and implements the @ref{f3f,,importlib.abc.InspectLoader}
interface. @code{_NamespaceLoader} is kept for backward compatibility.

@item 
bpo-45515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45515}: Add references to @ref{133,,zoneinfo} in the @ref{30,,datetime}
documentation, mostly replacing outdated references to @code{dateutil.tz}.
Change by Paul Ganssle.

@item 
bpo-45475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45475}: Reverted optimization of iterating @ref{410,,gzip.GzipFile},
@ref{851,,bz2.BZ2File}, and @ref{ff5,,lzma.LZMAFile} (see bpo-43787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43787}) because
it caused regression when user iterate them without having reference of
them. Patch by Inada Naoki.

@item 
bpo-45489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45489}: Update @ref{17d1,,ForwardRef} to support @code{|} operator.
Patch by Donghee Na.

@item 
bpo-42222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42222}: Removed deprecated support for float arguments in
`randrange()'.

@item 
bpo-45428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45428}: Fix a regression in py_compile when reading filenames from
standard input.

@item 
bpo-45467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45467}: Fix incremental decoder and stream reader in the
"raw-unicode-escape" codec. Previously they failed if the escape sequence
was split.

@item 
bpo-45461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45461}: Fix incremental decoder and stream reader in the
"unicode-escape" codec. Previously they failed if the escape sequence was
split.

@item 
bpo-45239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45239}: Fixed @ref{180c,,email.utils.parsedate_tz()} crashing with
@ref{14ec,,UnboundLocalError} on certain invalid input instead of returning
@code{None}. Patch by Ben Hoyt.

@item 
bpo-45417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45417}: Fix quadratic behaviour in the enum module: Creation of enum
classes with a lot of entries was quadratic.

@item 
bpo-45249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45249}: Fix the behaviour of @ref{180d,,traceback.print_exc()} when
displaying the caret when the @code{end_offset} in the exception is set to 0.
Patch by Pablo Galindo

@item 
bpo-45416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45416}: Fix use of @ref{a61,,asyncio.Condition} with explicit
@ref{a5f,,asyncio.Lock} objects, which was a regression due to removal of
explicit loop arguments. Patch by Joongi Kim.

@item 
bpo-20028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20028}: Empty escapechar/quotechar is not allowed when initializing
@ref{1604,,csv.Dialect}. Patch by Vajrasky Kok and Donghee Na.

@item 
bpo-44904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44904}: Fix bug in the @ref{3a,,doctest} module that caused it to fail if
a docstring included an example with a @code{classmethod} @code{property}. Patch
by Alex Waygood.

@item 
bpo-45406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45406}: Make @ref{1772,,inspect.getmodule()} catch @code{FileNotFoundError}
raised by @code{inspect.getabsfile()}, and return @code{None} to indicate that
the module could not be determined.

@item 
bpo-45411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45411}: Add extensions for files containing subtitles - .srt & .vtt -
to the mimetypes.py module.

@item 
bpo-10716@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10716}: Migrated pydoc to HTML5 (without changing the look of it). Side
effect is to update xmlrpc's @code{ServerHTMLDoc} which now uses the CSS too.
cgitb now relies less on pydoc (as it can't use the CSS file).

@item 
bpo-27580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27580}: Add support of null characters in @ref{29,,csv}.

@item 
bpo-45262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45262}: Prevent use-after-free in asyncio. Make sure the cached running
loop holder gets cleared on dealloc to prevent use-after-free in
get_running_loop

@item 
bpo-45386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45386}: Make @ref{12d,,xmlrpc.client} more robust to C runtimes where the
underlying C @code{strftime} function results in a @code{ValueError} when
testing for year formatting options.

@item 
bpo-20028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20028}: Improve error message of @ref{1604,,csv.Dialect} when
initializing. Patch by Vajrasky Kok and Donghee Na.

@item 
bpo-45343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45343}: Update bundled pip to 21.2.4 and setuptools to 58.1.0

@item 
bpo-45328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45328}: Fixed @ref{b2e,,http.client.HTTPConnection} to work properly in
OSs that don't support the @code{TCP_NODELAY} socket option.

@item 
bpo-45243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45243}: Add @ref{665,,setlimit()} and
@ref{666,,getlimit()} to @ref{242,,sqlite3.Connection} for
setting and getting SQLite limits by connection basis. Patch by Erlend E.
Aasland.

@item 
bpo-45320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45320}: Removed from the @ref{7d,,inspect} module:


@itemize *

@item 

@table @asis

@item the @code{getargspec} function, deprecated since Python 3.0;

use @ref{722,,inspect.signature()} or @ref{723,,inspect.getfullargspec()} instead.
@end table

@item 
the @code{formatargspec} function, deprecated since Python 3.5;
use the @ref{722,,inspect.signature()} function and @code{Signature} object
directly.

@item 
the undocumented @code{Signature.from_builtin} and @code{Signature.from_function}
functions, deprecated since Python 3.5; use the
@ref{724,,Signature.from_callable()} method
instead.
@end itemize

Patch by Hugo van Kemenade.

@item 
bpo-45192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45192}: Fix the @code{tempfile._infer_return_type} function so that the
@code{dir} argument of the @ref{df,,tempfile} functions accepts an object
implementing the @code{os.PathLike} protocol.

Patch by Kyungmin Lee.

@item 
bpo-45160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45160}: When tracing a tkinter variable used by a ttk OptionMenu,
callbacks are no longer made twice.

@item 
bpo-25625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25625}: Added non parallel-safe @ref{5f7,,chdir()} context
manager to change the current working directory and then restore it on
exit. Simple wrapper around @ref{5f8,,chdir()}.

@item 
bpo-24139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24139}: Add support for SQLite extended result codes in
@ref{180e,,sqlite3.Error}. Patch by Erlend E. Aasland.

@item 
bpo-24444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24444}: Fixed an error raised in @ref{6,,argparse} help display when help
for an option is set to 1+ blank spaces or when `choices' arg is an empty
container.

@item 
bpo-44547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44547}: Implement @code{Fraction.__int__}, so that a
@ref{1e4,,fractions.Fraction} instance @code{f} passes an @code{isinstance(f,
typing.SupportsInt)} check.

@item 
bpo-40321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40321}: Adds support for HTTP 308 redirects to @ref{107,,urllib}. See
@geindex RFC; RFC 7538
RFC 7538@footnote{https://datatracker.ietf.org/doc/html/rfc7538.html} for details. Patch by Jochem Schulenklopper.

@item 
bpo-41374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41374}: Ensure that @code{socket.TCP_*} constants are exposed on Cygwin
3.1.6 and greater.

@item 
bpo-35970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35970}: Add help flag to the base64 module's command line interface.
Patch contributed by Robert Kuska.
@end itemize

@node Documentation<25>,Tests<28>,Library<30>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id253}@anchor{180f}
@subsubsection Documentation



@itemize -

@item 
bpo-45726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45726}: Improve documentation for @ref{624,,functools.singledispatch()} and
@ref{9de,,functools.singledispatchmethod}.

@item 
bpo-45680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45680}: Amend the docs on @code{GenericAlias} objects to clarify that
non-container classes can also implement @code{__class_getitem__}. Patch
contributed by Alex Waygood.

@item 
bpo-45618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45618}: Update Sphinx version used to build the documentation to 4.2.0.
Patch by Maciej Olko.

@item 
bpo-45655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45655}: Add a new "relevant PEPs" section to the top of the
documentation for the @code{typing} module. Patch by Alex Waygood.

@item 
bpo-45604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45604}: Add @code{level} argument to @code{multiprocessing.log_to_stderr}
function docs.

@item 
bpo-45516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45516}: Add protocol description to the
@ref{1810,,importlib.abc.TraversableResources} documentation.

@item 
bpo-45464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45464}: Mention in the documentation of @ref{1811,,Built-in Exceptions} that inheriting from multiple exception types in a
single subclass is not recommended due to possible memory layout
incompatibility.

@item 
bpo-45449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45449}: Add note about 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} in @ref{1e,,collections.abc}.

@item 
bpo-45516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45516}: Add protocol description to the
@ref{1812,,importlib.abc.Traversable} documentation.

@item 
bpo-20692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20692}: Add Programming FAQ entry explaining that int literal attribute
access requires either a space after or parentheses around the literal.
@end itemize

@node Tests<28>,Build<30>,Documentation<25>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id254}@anchor{1813}
@subsubsection Tests



@itemize -

@item 
bpo-45678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45678}: Add tests for scenarios in which
@ref{9de,,functools.singledispatchmethod} is stacked on top of a method that
has already been wrapped by two other decorators. Patch by Alex Waygood.

@item 
bpo-45578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45578}: Add tests for @code{dis.distb()}

@item 
bpo-45678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45678}: Add tests to ensure that @code{functools.singledispatchmethod}
correctly wraps the attributes of the target function.

@item 
bpo-45668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45668}: PGO tests now pass when Python is built without test extension
modules.

@item 
bpo-45577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45577}: Add subtests for all @code{pickle} protocols in @code{test_zoneinfo}.

@item 
bpo-45566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45566}: Fix @code{test_frozen_pickle} in @code{test_dataclasses} to check all
@code{pickle} versions.

@item 
bpo-43592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43592}: @code{test.libregrtest} now raises the soft resource limit for
the maximum number of file descriptors when the default is too low for our
test suite as was often the case on macOS.

@item 
bpo-39679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39679}: Add more test cases for @code{@@functools.singledispatchmethod}
when combined with @code{@@classmethod} or @code{@@staticmethod}.

@item 
bpo-45410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45410}: When libregrtest spawns a worker process, stderr is now written
into stdout to keep messages order. Use a single pipe for stdout and
stderr, rather than two pipes. Previously, messages were out of order
which made analysis of buildbot logs harder Patch by Victor Stinner.

@item 
bpo-45402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45402}: Fix test_tools.test_sundry() when Python is built out of tree:
fix how the freeze_modules.py tool locates the _freeze_module program.
Patch by Victor Stinner.

@item 
bpo-45403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45403}: Fix test_sys.test_stdlib_dir() when Python is built outside the
source tree: compare normalized paths. Patch by Victor Stinner.

@item 
bpo-45400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45400}: Fix
test_name_error_suggestions_do_not_trigger_for_too_many_locals() of
test_exceptions if a directory name contains "a1" (like
"Python-3.11.0a1"): use a stricter regular expression. Patch by Victor
Stinner.

@item 
bpo-10572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10572}: Rename @ref{ce,,sqlite3} tests from @code{test_sqlite} to
@code{test_sqlite3}, and relocate them to @code{Lib/test/test_sqlite3}. Patch by
Erlend E. Aasland.
@end itemize

@node Build<30>,Windows<27>,Tests<28>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id255}@anchor{1814}
@subsubsection Build



@itemize -

@item 
bpo-43158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43158}: @code{setup.py} now uses values from configure script to build the
@code{_uuid} extension module. Configure now detects util-linux's
@code{libuuid}, too.

@item 
bpo-45666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45666}: Fix warning of @code{swprintf} and @code{%s} usage in
@code{_testembed.c}

@item 
bpo-45548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45548}: @code{Modules/Setup} and @code{Modules/makesetup} have been improved.
The @code{Setup} file now contains working rules for all extensions. Outdated
comments have been removed. Rules defined by @code{makesetup} track
dependencies correctly.

@item 
bpo-45548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45548}: The @ref{8d,,math} and @ref{18,,cmath} implementation now require a
C99 compatible @code{libm} and no longer ship with workarounds for missing
acosh, asinh, atanh, expm1, and log1p functions.

@item 
bpo-45595@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45595}: @code{setup.py} and @code{makesetup} now track build dependencies on
all Python header files and module specific header files.

@item 
bpo-45571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45571}: @code{Modules/Setup} now use @code{PY_CFLAGS_NODIST} instead of
@code{PY_CFLAGS} to compile shared modules.

@item 
bpo-45570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45570}: @code{pyexpat} and @code{_elementtree} no longer define
obsolete macros @code{HAVE_EXPAT_CONFIG_H} and @code{USE_PYEXPAT_CAPI}.
@code{XML_POOR_ENTROPY} is now defined in @code{expat_config.h}.

@item 
bpo-43974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43974}: @code{setup.py} no longer defines @code{Py_BUILD_CORE_MODULE}.
Instead every module, that uses the internal API, defines the macro.

@item 
bpo-45548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45548}: Fill in missing entries in Modules/Setup.

@item 
bpo-45532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45532}: Update @ref{177,,sys.version} to use @code{main} as fallback
information. Patch by Jeong YunWon.

@item 
bpo-45536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45536}: The @code{configure} script now checks whether OpenSSL headers and
libraries provide required APIs. Most common APIs are verified. The check
detects outdated or missing OpenSSL. Failures do not stop configure.

@item 
bpo-45221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45221}: Fixed regression in handling of @code{LDFLAGS} and @code{CPPFLAGS}
options where @code{argparse.parse_known_args()} could interpret an option
as one of the built-in command line argument, for example @code{-h} for help.

@item 
bpo-45440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45440}: Building Python now requires a C99 @code{<math.h>} header file
providing the following functions: @code{copysign()}, @code{hypot()},
@code{isfinite()}, @code{isinf()}, @code{isnan()}, @code{round()}. Patch by Victor
Stinner.

@item 
bpo-45405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45405}: Prevent @code{internal configure error} when running @code{configure}
with recent versions of non-Apple clang.  Patch by David Bohman.

@item 
bpo-45433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45433}: Avoid linking libpython with libcrypt.
@end itemize

@node Windows<27>,macOS<21>,Build<30>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id256}@anchor{1815}
@subsubsection Windows



@itemize -

@item 
bpo-43652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43652}: Update Tcl/Tk to 8.6.11, actually this time. The previous
update incorrectly included 8.6.10.

@item 
bpo-45337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45337}: venv now warns when the created environment may need to be
accessed at a different path, due to redirections, links or junctions. It
also now correctly installs or upgrades components when the alternate path
is required.

@item 
bpo-43851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43851}: Build SQLite @code{SQLITE_OMIT_AUTOINIT} on Windows. Patch by
Erlend E. Aasland.
@end itemize

@node macOS<21>,IDLE<18>,Windows<27>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id257}@anchor{1816}
@subsubsection macOS



@itemize -

@item 
bpo-44828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44828}: Avoid tkinter file dialog failure on macOS 12 Monterey when
using the Tk 8.6.11 provided by python.org macOS installers. Patch by Marc
Culler of the Tk project.
@end itemize

@node IDLE<18>,C API<29>,macOS<21>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id258}@anchor{1817}
@subsubsection IDLE



@itemize -

@item 
bpo-45495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45495}: Add context keywords 'case' and 'match' to completions list.
@end itemize

@node C API<29>,,IDLE<18>,Python 3 11 0 alpha 2
@anchor{whatsnew/changelog id259}@anchor{1818}
@subsubsection C API



@itemize -

@item 
bpo-29103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29103}: @ref{53c,,PyType_FromSpec*} now
copies the class name from the spec to a buffer owned by the class, so the
original can be safely deallocated. Patch by Petr Viktorin.

@item 
bpo-45522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45522}: The internal freelists for frame, float, list, dict, async
generators, and context objects can now be disabled.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: Exclude @ref{3b6,,PyWeakref_GET_OBJECT()} from the limited C API.
It never worked since the @code{PyWeakReference} structure is opaque
in the limited C API.

@item 
bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081}: Move the @code{interpreteridobject.h} header file from
@code{Include/} to @code{Include/internal/}. It only provides private functions.
Patch by Victor Stinner.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: The non-limited API files @code{cellobject.h}, @code{classobject.h},
@code{context.h}, @code{funcobject.h}, @code{genobject.h} and @code{longintrepr.h}
have been moved to the @code{Include/cpython} directory. Moreover, the
@code{eval.h} header file was removed. These files must not be included
directly, as they are already included in @code{Python.h}: @ref{76e,,Include Files}. If they have been included directly, consider
including @code{Python.h} instead. Patch by Victor Stinner.

@item 
bpo-45474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45474}: The following items are no longer available when
@code{Py_LIMITED_API} is defined:


@itemize *

@item 
@ref{780,,PyMarshal_WriteLongToFile()}

@item 
@ref{781,,PyMarshal_WriteObjectToFile()}

@item 
@ref{782,,PyMarshal_ReadObjectFromString()}

@item 
@ref{783,,PyMarshal_WriteObjectToString()}

@item 
the @code{Py_MARSHAL_VERSION} macro
@end itemize

These are not part of the @ref{784,,limited API}.

Patch by Victor Stinner.

@item 
bpo-45434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45434}: Remove the @code{pystrhex.h} header file. It only contains private
functions. C extensions should only include the main @code{<Python.h>} header
file. Patch by Victor Stinner.

@item 
bpo-45440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45440}: Remove the @code{Py_FORCE_DOUBLE()} macro. It was used by the
@code{Py_IS_INFINITY()} macro. Patch by Victor Stinner.

@item 
bpo-45434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45434}: @code{<Python.h>} no longer includes the header files
@code{<stdlib.h>}, @code{<stdio.h>}, @code{<errno.h>} and @code{<string.h>} when the
@code{Py_LIMITED_API} macro is set to @code{0x030b0000} (Python 3.11) or higher.
C extensions should explicitly include the header files after @code{#include
<Python.h>}. Patch by Victor Stinner.

@item 
bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}: Remove @code{Py_UNICODE_COPY()} and @code{Py_UNICODE_FILL()} macros,
deprecated since Python 3.3. Use @code{PyUnicode_CopyCharacters()} or
@code{memcpy()} (@code{wchar_t*} string), and @code{PyUnicode_Fill()} functions
instead. Patch by Victor Stinner.

@item 
bpo-45412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45412}: Remove the following math macros using the @code{errno} variable:


@itemize *

@item 
@code{Py_ADJUST_ERANGE1()}

@item 
@code{Py_ADJUST_ERANGE2()}

@item 
@code{Py_OVERFLOWED()}

@item 
@code{Py_SET_ERANGE_IF_OVERFLOW()}

@item 
@code{Py_SET_ERRNO_ON_MATH_ERROR()}
@end itemize

Patch by Victor Stinner.

@item 
bpo-45395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45395}: Custom frozen modules (the array set to
@code{PyImport_FrozenModules}) are now treated as additions, rather than
replacing all the default frozen modules. Frozen stdlib modules can still
be disabled by setting the "code" field of the custom array entry to NULL.

@item 
bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760}: Add new @ref{73e,,PyThreadState_EnterTracing()}, and
@ref{73f,,PyThreadState_LeaveTracing()} functions to the limited C API to
suspend and resume tracing and profiling. Patch by Victor Stinner.

@item 
bpo-44220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44220}: @ref{96f,,PyStructSequence_UnnamedField} is added to the Stable
ABI.
@end itemize

@node Python 3 11 0 alpha 1,Python 3 10 0 beta 1,Python 3 11 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-11-0-alpha-1}@anchor{1819}
@subsection Python 3.11.0 alpha 1


`Release date: 2021-10-05'

@menu
* Security: Security<18>. 
* Core and Builtins: Core and Builtins<32>. 
* Library: Library<31>. 
* Documentation: Documentation<26>. 
* Tests: Tests<29>. 
* Build: Build<31>. 
* Windows: Windows<28>. 
* macOS: macOS<22>. 
* IDLE: IDLE<19>. 
* Tools/Demos: Tools/Demos<15>. 
* C API: C API<30>. 

@end menu

@node Security<18>,Core and Builtins<32>,,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id260}@anchor{181a}
@subsubsection Security



@itemize -

@item 
bpo-42278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42278}: Replaced usage of @ref{181b,,tempfile.mktemp()} with
@ref{1212,,TemporaryDirectory} to avoid a potential race condition.

@item 
bpo-44600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44600}: Fix incorrect line numbers while tracing some failed patterns
in @ref{7f7,,match} statements. Patch by Charles Burkland.

@item 
bpo-41180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41180}: Add auditing events to the @ref{8c,,marshal} module, and stop
raising @code{code.__init__} events for every unmarshalled code object.
Directly instantiated code objects will continue to raise an event, and
audit event handlers should inspect or collect the raw marshal data. This
reduces a significant performance overhead when loading from @code{.pyc}
files.

@item 
bpo-44394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44394}: Update the vendored copy of libexpat to 2.4.1 (from 2.2.8) to
get the fix for the 
@geindex Common Vulnerabilities and Exposures; CVE 2013-0340
CVE 2013-0340@footnote{https://www.cve.org/CVERecord?id=CVE-2013-0340} "Billion Laughs" vulnerability. This
copy is most used on Windows and macOS.

@item 
bpo-43124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43124}: Made the internal @code{putcmd} function in @ref{c9,,smtplib}
sanitize input for presence of @code{\r} and @code{\n} characters to avoid
(unlikely) command injection.

@item 
bpo-44022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44022}: @ref{6e,,http.client} now avoids infinitely reading potential HTTP
headers after a @code{100 Continue} status response from the server.
@end itemize

@node Core and Builtins<32>,Library<31>,Security<18>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id261}@anchor{181c}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760}: The number of hardware branches per instruction dispatch is
reduced from two to one by adding a special instruction for tracing. Patch
by Mark Shannon.

@item 
bpo-45061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45061}: Add a deallocator to the bool type to detect refcount bugs in C
extensions which call Py_DECREF(Py_True) or Py_DECREF(Py_False) by
mistake. Detect also refcount bugs when the empty tuple singleton or the
Unicode empty string singleton is destroyed by mistake. Patch by Victor
Stinner.

@item 
bpo-24076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24076}: sum() was further optimised for summing up single digit
integers.

@item 
bpo-45190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45190}: Update Unicode databases to Unicode 14.0.0.

@item 
bpo-45167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45167}: Fix deepcopying of @ref{7d5,,types.GenericAlias} objects.

@item 
bpo-45155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45155}: @ref{181d,,int.to_bytes()} and @ref{17dd,,int.from_bytes()} now take a
default value of @code{"big"} for the @code{byteorder} argument.
@ref{181d,,int.to_bytes()} also takes a default value of @code{1} for the
@code{length} argument.

@item 
bpo-44219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44219}: Release the GIL while performing @code{isatty} system calls on
arbitrary file descriptors. In particular, this affects @ref{181e,,os.isatty()},
@ref{181f,,os.device_encoding()} and @ref{7a5,,io.TextIOWrapper}. By extension,
@ref{506,,io.open()} in text mode is also affected. This change solves a
deadlock in @ref{181e,,os.isatty()}. Patch by Vincent Michel in bpo-44219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44219}.

@item 
bpo-44959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44959}: Added fallback to extension modules with '.sl' suffix on HP-UX

@item 
bpo-45121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45121}: Fix issue where @code{Protocol.__init__} raises @code{RecursionError}
when it's called directly or via @code{super()}. Patch provided by Yurii
Karabas.

@item 
bpo-44348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44348}: The deallocator function of the @ref{5a5,,BaseException} type now
uses the trashcan mechanism to prevent stack overflow. For example, when a
@ref{d59,,RecursionError} instance is raised, it can be linked to another
RecursionError through the @code{__context__} attribute or the
@code{__traceback__} attribute, and then a chain of exceptions is created.
When the chain is destroyed, nested deallocator function calls can crash
with a stack overflow if the chain is too long compared to the available
stack memory. Patch by Victor Stinner.

@item 
bpo-45123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45123}: Fix PyAiter_Check to only check for the __anext__ presence (not
for __aiter__). Rename PyAiter_Check to PyAIter_Check, PyObject_GetAiter
-> PyObject_GetAIter.

@item 
bpo-1514420@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1514420}: Interpreter no longer attempts to open files with names in
angle brackets (like "<string>" or "<stdin>") when formatting an
exception.

@item 
bpo-41031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41031}: Match C and Python code formatting of unprintable exceptions
and exceptions in the @ref{1,,__main__} module.

@item 
bpo-37330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37330}: @ref{505,,open()}, @ref{506,,io.open()}, @ref{72a,,codecs.open()} and
@ref{721,,fileinput.FileInput} no longer accept @code{'U'} ("universal
newline") in the file mode. This flag was deprecated since Python 3.3.
Patch by Victor Stinner.

@item 
bpo-45083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45083}: When the interpreter renders an exception, its name now has a
complete qualname. Previously only the class name was concatenated to the
module name, which sometimes resulted in an incorrect full name being
displayed.

(This issue impacted only the C code exception rendering, the
@ref{fd,,traceback} module was using qualname already).

@item 
bpo-34561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34561}: List sorting now uses the merge-ordering strategy from Munro
and Wild's @code{powersort()}. Unlike the former strategy, this is provably
near-optimal in the entropy of the distribution of run lengths. Most uses
of @code{list.sort()} probably won't see a significant time difference, but
may see significant improvements in cases where the former strategy was
exceptionally poor. However, as these are all fast linear-time
approximations to a problem that's inherently at best quadratic-time to
solve truly optimally, it's also possible to contrive cases where the
former strategy did better.

@item 
bpo-45056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45056}: Compiler now removes trailing unused constants from co_consts.

@item 
bpo-45020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45020}: Add a new command line option, "-X frozen_modules=[on|off]" to
opt out of (or into) using optional frozen modules.  This defaults to "on"
(or "off" if it's running out of the source tree).

@item 
bpo-45012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45012}: In @ref{ac,,posix}, release GIL during @code{stat()}, @code{lstat()},
and @code{fstatat()} syscalls made by @ref{1683,,os.DirEntry.stat()}. Patch by
Stanisław Skonieczny.

@item 
bpo-45018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45018}: Fixed pickling of range iterators that iterated for over
@code{2**32} times.

@item 
bpo-45000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45000}: A @ref{18b,,SyntaxError} is now raised when trying to delete
@ref{7c4,,__debug__}. Patch by Donghee Na.

@item 
bpo-44963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44963}: Implement @code{send()} and @code{throw()} methods for
@code{anext_awaitable} objects. Patch by Pablo Galindo.

@item 
bpo-44962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44962}: Fix a race in WeakKeyDictionary, WeakValueDictionary and
WeakSet when two threads attempt to commit the last pending removal. This
fixes asyncio.create_task and fixes a data loss in asyncio.run where
shutdown_asyncgens is not run

@item 
bpo-24234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24234}: Implement the @code{__bytes__()} special method on the
@ref{1bd,,bytes} type, so a bytes object @code{b}  passes an @code{isinstance(b,
typing.SupportsBytes)} check.

@item 
bpo-24234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24234}: Implement the @code{__complex__()} special method on the
@ref{2ec,,complex} type, so a complex number @code{z} passes an @code{isinstance(z,
typing.SupportsComplex)} check.

@item 
bpo-44954@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44954}: Fixed a corner case bug where the result of
@code{float.fromhex('0x.8p-1074')} was rounded the wrong way.

@item 
bpo-44947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44947}: Refine the syntax error for trailing commas in import
statements. Patch by Pablo Galindo.

@item 
bpo-44945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44945}: Specialize the BINARY_ADD instruction using the PEP 659
machinery. Adds five new instructions:


@itemize *

@item 
BINARY_ADD_ADAPTIVE

@item 
BINARY_ADD_FLOAT

@item 
BINARY_ADD_INT

@item 
BINARY_ADD_UNICODE

@item 
BINARY_ADD_UNICODE_INPLACE_FAST
@end itemize

@item 
bpo-44929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44929}: Fix some edge cases of @code{enum.Flag} string representation in
the REPL. Patch by Pablo Galindo.

@item 
bpo-44914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44914}: Class version tags are no longer recycled.

This means that a version tag serves as a unique identifier for the state
of a class. We rely on this for effective specialization of the LOAD_ATTR
and other instructions.

@item 
bpo-44698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44698}: Restore behaviour of complex exponentiation with integer-valued
exponent of type @ref{2eb,,float} or @ref{2ec,,complex}.

@item 
bpo-44895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44895}: A debug variable 
@geindex PYTHONDUMPREFSFILE
@geindex variable d'environnement; PYTHONDUMPREFSFILE
@ref{1820,,PYTHONDUMPREFSFILE} is added for
creating a dump file which is generated by @ref{38b,,--with-trace-refs}.
Patch by Donghee Na.

@item 
bpo-44900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44900}: Add five superinstructions for PEP 659 quickening:


@itemize *

@item 
LOAD_FAST LOAD_FAST

@item 
STORE_FAST LOAD_FAST

@item 
LOAD_FAST LOAD_CONST

@item 
LOAD_CONST LOAD_FAST

@item 
STORE_FAST STORE_FAST
@end itemize

@item 
bpo-44889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44889}: Initial implementation of adaptive specialization of
@code{LOAD_METHOD}. The following specialized forms were added:


@itemize *

@item 
@code{LOAD_METHOD_CACHED}

@item 
@code{LOAD_METHOD_MODULE}

@item 
@code{LOAD_METHOD_CLASS}
@end itemize

@item 
bpo-44890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44890}: Specialization stats are always collected in debug builds.

@item 
bpo-44885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44885}: Correct the ast locations of f-strings with format specs and
repeated expressions. Patch by Pablo Galindo

@item 
bpo-44878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44878}: Remove the loop from the bytecode interpreter. All instructions
end with a DISPATCH macro, so the loop is now redundant.

@item 
bpo-44878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44878}: Remove switch statement for interpreter loop when using
computed gotos. This makes sure that we only have one dispatch table in
the interpreter.

@item 
bpo-44874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44874}: Deprecate the old trashcan macros
(@code{Py_TRASHCAN_SAFE_BEGIN}/@code{Py_TRASHCAN_SAFE_END}). They should be
replaced by the new macros @code{Py_TRASHCAN_BEGIN} and @code{Py_TRASHCAN_END}.

@item 
bpo-44872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44872}: Use new trashcan macros (Py_TRASHCAN_BEGIN/END) in
frameobject.c instead of the old ones (Py_TRASHCAN_SAFE_BEGIN/END).

@item 
bpo-33930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33930}: Fix segmentation fault with deep recursion when cleaning method
objects. Patch by Augusto Goulart and Pablo Galindo.

@item 
bpo-25782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25782}: Fix bug where @code{PyErr_SetObject} hangs when the current
exception has a cycle in its context chain.

@item 
bpo-44856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44856}: Fix reference leaks in the error paths of @code{update_bases()}
and @code{__build_class__}. Patch by Pablo Galindo.

@item 
bpo-44826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44826}: Initial implementation of adaptive specialization of STORE_ATTR

Three specialized forms of STORE_ATTR are added:


@itemize *

@item 
STORE_ATTR_SLOT

@item 
STORE_ATTR_SPLIT_KEYS

@item 
STORE_ATTR_WITH_HINT
@end itemize

@item 
bpo-44838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44838}: Fixed a bug that was causing the parser to raise an incorrect
custom @ref{18b,,SyntaxError} for invalid 'if' expressions. Patch by Pablo
Galindo.

@item 
bpo-44821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44821}: Create instance dictionaries (__dict__) eagerly, to improve
regularity of object layout and assist specialization.

@item 
bpo-44792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44792}: Improve syntax errors for if expressions. Patch by Miguel Brito

@item 
bpo-34013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34013}: Generalize the invalid legacy statement custom error message
(like the one generated when "print" is called without parentheses) to
include more generic expressions. Patch by Pablo Galindo

@item 
bpo-44732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44732}: Rename @code{types.Union} to @code{types.UnionType}.

@item 
bpo-44725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44725}: Expose specialization stats in python via
@code{_opcode.get_specialization_stats()}.

@item 
bpo-44717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44717}: Improve AttributeError on circular imports of submodules.

@item 
bpo-44698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44698}: Fix undefined behaviour in complex object exponentiation.

@item 
bpo-44653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44653}: Support @ref{103,,typing} types in parameter substitution in the
union type.

@item 
bpo-44676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44676}: Add ability to serialise @code{types.Union} objects. Patch
provided by Yurii Karabas.

@item 
bpo-44633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44633}: Parameter substitution of the union type with wrong types now
raises @code{TypeError} instead of returning @ref{7bc,,NotImplemented}.

@item 
bpo-44661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44661}: Update @code{property_descr_set} to use vectorcall if possible.
Patch by Donghee Na.

@item 
bpo-44662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44662}: Add @code{__module__} to @code{types.Union}. This also fixes
@code{types.Union} issues with @code{typing.Annotated}. Patch provided by Yurii
Karabas.

@item 
bpo-44655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44655}: Include the name of the type in unset __slots__ attribute
errors. Patch by Pablo Galindo

@item 
bpo-44655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44655}: Don't include a missing attribute with the same name as the
failing one when offering suggestions for missing attributes. Patch by
Pablo Galindo

@item 
bpo-44646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44646}: Fix the hash of the union type: it no longer depends on the
order of arguments.

@item 
bpo-44636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44636}: Collapse union of equal types. E.g. the result of @code{int | int}
is now @code{int}. Fix comparison of the union type with non-hashable
objects. E.g. @code{int | str == @{@}} no longer raises a TypeError.

@item 
bpo-44611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44611}: On Windows, @ref{50c,,os.urandom()}: uses BCryptGenRandom API
instead of CryptGenRandom API which is deprecated from Microsoft Windows
API. Patch by Donghee Na.

@item 
bpo-44635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44635}: Convert @code{None} to @code{type(None)} in the union type
constructor.

@item 
bpo-26280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26280}: Implement adaptive specialization for BINARY_SUBSCR

Three specialized forms of BINARY_SUBSCR are added:


@itemize *

@item 
BINARY_SUBSCR_LIST_INT

@item 
BINARY_SUBSCR_TUPLE_INT

@item 
BINARY_SUBSCR_DICT
@end itemize

@item 
bpo-44589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44589}: Mapping patterns in @code{match} statements with two or more equal
literal keys will now raise a @ref{18b,,SyntaxError} at compile-time.

@item 
bpo-44606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44606}: Fix @code{__instancecheck__} and @code{__subclasscheck__} for the
union type.

@item 
bpo-42073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42073}: The @code{@@classmethod} decorator can now wrap other
classmethod-like descriptors.

@item 
bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972}: Tuned the string-searching algorithm of fastsearch.h to have a
shorter inner loop for most cases.

@item 
bpo-44590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44590}: All necessary data for executing a Python function (local
variables, stack, etc) is now kept in a per-thread stack. Frame objects
are lazily allocated on demand. This increases performance by about 7% on
the standard benchmark suite. Introspection and debugging are unaffected
as frame objects are always available when needed. Patch by Mark Shannon.

@item 
bpo-44584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44584}: The threading debug (@code{PYTHONTHREADDEBUG} environment
variable) is deprecated in Python 3.10 and will be removed in Python 3.12.
This feature requires a debug build of Python. Patch by Victor Stinner.

@item 
bpo-43895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43895}: An obsolete internal cache of shared object file handles added
in 1995 that attempted, but did not guarantee, that a .so would not be
dlopen'ed twice to work around flaws in mid-1990s posix-ish operating
systems has been removed from dynload_shlib.c.

@item 
bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490}: @ref{103,,typing} now searches for type parameters in
@code{types.Union} objects. @code{get_type_hints} will also properly resolve
annotations with nested @code{types.Union} objects. Patch provided by Yurii
Karabas.

@item 
bpo-43950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43950}: Code objects can now provide the column information for
instructions when available. This is levaraged during traceback printing
to show the expressions responsible for errors.

Contributed by Pablo Galindo, Batuhan Taskaya and Ammar Askar as part of
@geindex Python Enhancement Proposals; PEP 657
PEP 657@footnote{https://peps.python.org/pep-0657/}.

@item 
bpo-44562@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44562}: Remove uses of @ref{14bb,,PyObject_GC_Del()} in error path when
initializing @ref{7d5,,types.GenericAlias}.

@item 
bpo-41486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41486}: Fix a memory consumption and copying performance regression in
earlier 3.10 beta releases if someone used an output buffer larger than
4GiB with zlib.decompress on input data that expands that large.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Heap types with the @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} flag
can now inherit the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} vectorcall protocol.  Previously, this was
only possible for @ref{769,,static types}.  Patch by Erlend E.
Aasland.

@item 
bpo-44553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44553}: Implement GC methods for @code{types.Union} to break reference
cycles and prevent memory leaks.

@item 
bpo-44490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44490}: Add @code{__parameters__} attribute and @code{__getitem__} operator
to @code{types.Union}. Patch provided by Yurii Karabas.

@item 
bpo-44523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44523}: Remove the pass-through for @ref{5d5,,hash()} of
@ref{a40,,weakref.proxy} objects to prevent unintended consequences when the
original referred object dies while the proxy is part of a hashable
object. Patch by Pablo Galindo.

@item 
bpo-44483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44483}: Fix a crash in @code{types.Union} objects when creating a union of
an object with bad @code{__module__} field.

@item 
bpo-44486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44486}: Modules will always have a dictionary, even when created by
@code{types.ModuleType.__new__()}

@item 
bpo-44472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44472}: Fix ltrace functionality when exceptions are raised. Patch by
Pablo Galindo

@item 
bpo-12022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12022}: A @ref{522,,TypeError} is now raised instead of an
@ref{343,,AttributeError} in @ref{5bc,,with} and @ref{5bf,,async with}
statements for objects which do not support the @ref{5be,,context manager} or
@ref{5c1,,asynchronous context manager} protocols correspondingly.

@item 
bpo-44297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44297}: Make sure that the line number is set when entering a
comprehension scope. This ensures that backtraces including generator
expressions show the correct line number.

@item 
bpo-44456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44456}: Improve the syntax error when mixing positional and keyword
patterns. Patch by Pablo Galindo.

@item 
bpo-44409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44409}: Fix error location information for tokenizer errors raised on
initialization of the tokenizer. Patch by Pablo Galindo.

@item 
bpo-44396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44396}: Fix a possible crash in the tokenizer when raising syntax
errors for unclosed strings. Patch by Pablo Galindo.

@item 
bpo-44376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44376}: Exact integer exponentiation (like @code{i**2} or @code{pow(i, 2)})
with a small exponent is much faster, due to reducing overhead in such
cases.

@item 
bpo-44313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44313}: Directly imported objects and modules (through import and from
import statements) don't generate @code{LOAD_METHOD}/@code{CALL_METHOD} for
directly accessed objects on their namespace. They now use the regular
@code{LOAD_ATTR}/@code{CALL_FUNCTION}.

@item 
bpo-44338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44338}: Implement adaptive specialization for LOAD_GLOBAL

Two specialized forms of LOAD_GLOBAL are added:


@itemize *

@item 
LOAD_GLOBAL_MODULE

@item 
LOAD_GLOBAL_BUILTIN
@end itemize

@item 
bpo-44368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44368}: Improve syntax errors for invalid "as" targets. Patch by Pablo
Galindo

@item 
bpo-44349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44349}: Fix an edge case when displaying text from files with encoding
in syntax errors. Patch by Pablo Galindo.

@item 
bpo-44337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44337}: Initial implementation of adaptive specialization of LOAD_ATTR

Four specialized forms of LOAD_ATTR are added:


@itemize *

@item 
LOAD_ATTR_SLOT

@item 
LOAD_ATTR_SPLIT_KEYS

@item 
LOAD_ATTR_WITH_HINT

@item 
LOAD_ATTR_MODULE
@end itemize

@item 
bpo-44335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44335}: Fix a regression when identifying incorrect characters in
syntax errors. Patch by Pablo Galindo

@item 
bpo-43693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43693}: Computation of the offsets of cell variables is done in the
compiler instead of at runtime. This reduces the overhead of handling cell
and free variables, especially in the case where a variable is both an
argument and cell variable.

@item 
bpo-44317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44317}: Improve tokenizer error with improved locations. Patch by Pablo
Galindo.

@item 
bpo-44304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44304}: Fix a crash in the @ref{ce,,sqlite3} module that happened when the
garbage collector clears @code{sqlite.Statement} objects. Patch by Pablo
Galindo

@item 
bpo-44305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44305}: Improve error message for @code{try} blocks without @code{except} or
@code{finally} blocks. Patch by Pablo Galindo.

@item 
bpo-43413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43413}: Constructors of subclasses of some builtin classes (e.g.
@ref{366,,tuple}, @ref{5fc,,list}, @ref{5c4,,frozenset}) no longer accept
arbitrary keyword arguments. [reverted in 3.11a4] Subclass of @ref{5c3,,set}
can now define a @code{__new__()} method with additional keyword parameters
without overriding also @code{__init__()}.

@item 
bpo-43667@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43667}: Improve Unicode support in non-UTF locales on Oracle Solaris.
This issue does not affect other Solaris systems.

@item 
bpo-43693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43693}: A new opcode MAKE_CELL has been added that effectively moves
some of the work done on function entry into the compiler and into the
eval loop.  In addition to creating the required cell objects, the new
opcode converts relevant arguments (and other locals) to cell variables on
function entry.

@item 
bpo-44232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44232}: Fix a regression in @ref{d36,,type()} when a metaclass raises an
exception. The C function @code{type_new()} must properly report the
exception when a metaclass constructor raises an exception and the winner
class is not the metaclass. Patch by Victor Stinner.

@item 
bpo-44201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44201}: Avoid side effects of checking for specialized syntax errors in
the REPL that was causing it to ask for extra tokens after a syntax error
had been detected. Patch by Pablo Galindo

@item 
bpo-43693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43693}: @code{PyCodeObject} gained @code{co_fastlocalnames} and
@code{co_fastlocalkinds} as the authoritative source of fast locals info.
Marshaled code objects have changed accordingly.

@item 
bpo-44184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44184}: Fix a crash at Python exit when a deallocator function removes
the last strong reference to a heap type. Patch by Victor Stinner.

@item 
bpo-44187@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44187}: Implement quickening in the interpreter. This offers no
advantages as yet, but is an enabler of future optimizations. See PEP 659
for full explanation.

@item 
bpo-44180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44180}: The parser doesn't report generic syntax errors that happen in
a position further away that the one it reached in the first pass. Patch
by Pablo Galindo

@item 
bpo-44168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44168}: Fix error message in the parser involving keyword arguments
with invalid expressions. Patch by Pablo Galindo

@item 
bpo-44156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44156}: String caches in @code{compile.c} are now subinterpreter
compatible.

@item 
bpo-44143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44143}: Fixed a crash in the parser that manifest when raising
tokenizer errors when an existing exception was present. Patch by Pablo
Galindo.

@item 
bpo-44032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44032}: Move 'fast' locals and other variables from the frame object to
a per-thread datastack.

@item 
bpo-44114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44114}: Fix incorrect dictkeys_reversed and dictitems_reversed function
signatures in C code, which broke webassembly builds.

@item 
bpo-44110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44110}: Improve @code{str.__getitem__()} error message

@item 
bpo-26110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26110}: Add @code{CALL_METHOD_KW} opcode to speed up method calls with
keyword arguments.  Idea originated from PyPy.  A side effect is executing
@code{CALL_METHOD} is now branchless in the evaluation loop.

@item 
bpo-28307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28307}: Compiler now optimizes simple C-style formatting with literal
format containing only format codes %s, %r and %a by converting them to
f-string expressions.

@item 
bpo-43149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43149}: Correct the syntax error message regarding multiple exception
types to not refer to "exception groups". Patch by Pablo Galindo

@item 
bpo-43822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43822}: The parser will prioritize tokenizer errors over custom syntax
errors when raising exceptions. Patch by Pablo Galindo.

@item 
bpo-40222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40222}: "Zero cost" exception handling.


@itemize *

@item 
Uses a lookup table to determine how to handle exceptions.

@item 
Removes SETUP_FINALLY and POP_TOP block instructions, eliminating the runtime overhead of try statements.

@item 
Reduces the size of the frame object by about 60%.
@end itemize

Patch by Mark Shannon

@item 
bpo-43918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43918}: Document the signature and @code{default} argument in the
docstring of the new @code{anext} builtin.

@item 
bpo-43833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43833}: Emit a deprecation warning if the numeric literal is
immediately followed by one of keywords: and, else, for, if, in, is, or.
Raise a syntax error with more informative message if it is immediately
followed by other keyword or identifier.

@item 
bpo-43879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43879}: Add native_thread_id to PyThreadState. Patch by Gabriele N.
Tornetta.

@item 
bpo-43693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43693}: Compute cell offsets relative to locals in compiler. Allows the
interpreter to treats locals and cells a single array, which is slightly
more efficient. Also make the LOAD_CLOSURE opcode an alias for LOAD_FAST.
Preserving LOAD_CLOSURE helps keep bytecode a bit more readable.

@item 
bpo-17792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17792}: More accurate error messages for access of unbound locals or
free vars.

@item 
bpo-28146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28146}: Fix a confusing error message in @ref{60c,,str.format()}.

@item 
bpo-11105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11105}: When compiling @ref{1a4,,ast.AST} objects with recursive
references through @ref{190,,compile()}, the interpreter doesn't crash anymore
instead it raises a @ref{d59,,RecursionError}.

@item 
bpo-39091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39091}: Fix crash when using passing a non-exception to a generator's
@code{throw()} method. Patch by Noah Oxer

@item 
bpo-33346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33346}: Asynchronous comprehensions are now allowed inside
comprehensions in asynchronous functions.  Outer comprehensions implicitly
become asynchronous.
@end itemize

@node Library<31>,Documentation<26>,Core and Builtins<32>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id262}@anchor{1821}
@subsubsection Library



@itemize -

@item 
bpo-45371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45371}: Fix clang rpath issue in @code{distutils}. The UnixCCompiler now
uses correct clang option to add a runtime library directory (rpath) to a
shared library.

@item 
bpo-45329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45329}: Fix freed memory access in @code{pyexpat.xmlparser} when
building it with an installed expat library <= 2.2.0.

@item 
bpo-41710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41710}: On Unix, if the @code{sem_clockwait()} function is available in
the C library (glibc 2.30 and newer), the @ref{683,,threading.Lock.acquire()}
method now uses the monotonic clock (@ref{684,,time.CLOCK_MONOTONIC}) for
the timeout, rather than using the system clock
(@ref{685,,time.CLOCK_REALTIME}), to not be affected by system clock
changes. Patch by Victor Stinner.

@item 
bpo-1596321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1596321}: Fix the @code{threading._shutdown()} function when the
@ref{ec,,threading} module was imported first from a thread different than
the main thread: no longer log an error at Python exit.

@item 
bpo-45274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45274}: Fix a race condition in the @ref{11c1,,Thread.join()} method of the @ref{ec,,threading} module. If the
function is interrupted by a signal and the signal handler raises an
exception, make sure that the thread remains in a consistent state to
prevent a deadlock. Patch by Victor Stinner.

@item 
bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302}: In Unix operating systems, @ref{688,,time.sleep()} now uses the
@code{nanosleep()} function, if @code{clock_nanosleep()} is not available but
@code{nanosleep()} is available. @code{nanosleep()} allows to sleep with
nanosecond precision.

@item 
bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302}: On Windows, @ref{688,,time.sleep()} now uses a waitable timer which
has a resolution of 100 nanoseconds (10@w{^-7} seconds). Previously,
it had a resolution of 1 millisecond (10@w{^-3} seconds). Patch by
Benjamin Szőke and Victor Stinner.

@item 
bpo-45238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45238}: Fix @code{unittest.IsolatedAsyncioTestCase.debug()}: it runs now
asynchronous methods and callbacks.

@item 
bpo-36674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36674}: @ref{1822,,unittest.TestCase.debug()} raises now a
@ref{fcf,,unittest.SkipTest} if the class or the test method are decorated
with the skipping decorator.

@item 
bpo-45235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45235}: Fix an issue where argparse would not preserve values in a
provided namespace when using a subparser with defaults.

@item 
bpo-45183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45183}: Have zipimport.zipimporter.find_spec() not raise an exception
when the underlying zip file has been deleted and the internal cache has
been reset via invalidate_cache().

@item 
bpo-45234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45234}: Fixed a regression in @ref{a47,,copyfile()},
@ref{a48,,copy()}, @ref{a49,,copy2()} raising
@ref{eae,,FileNotFoundError} when source is a directory, which should raise
@ref{1042,,IsADirectoryError}

@item 
bpo-45228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45228}: Fix stack buffer overflow in parsing J1939 network address.

@item 
bpo-45225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45225}: use map function instead of genexpr in capwords.

@item 
bpo-42135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42135}: Fix typo: @code{importlib.find_loader} is really slated for
removal in Python 3.12 not 3.10, like the others in PR 25169.

Patch by Hugo van Kemenade.

@item 
bpo-20524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20524}: Improves error messages on @code{.format()} operation for @code{str},
@code{float}, @code{int}, and @code{complex}. New format now shows the problematic
pattern and the object type.

@item 
bpo-45168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45168}: Change @ref{b22,,dis.dis()} output to omit op arg values that cannot
be resolved due to @code{co_consts}, @code{co_names} etc not being provided.
Previously the oparg itself was repeated in the value field, which is not
useful and can be confusing.

@item 
bpo-21302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21302}: In Unix operating systems, @ref{688,,time.sleep()} now uses the
@code{clock_nanosleep()} function, if available, which allows to sleep for an
interval specified with nanosecond precision.

@item 
bpo-45173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45173}: Remove from the @ref{22,,configparser} module: the
@code{SafeConfigParser} class, the @code{filename} property of the
@ref{4ee,,ParsingError} class, the @code{readfp()} method of
the @ref{1c3,,ConfigParser} class, deprecated since Python
3.2.

Patch by Hugo van Kemenade.

@item 
bpo-44987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44987}: Pure ASCII strings are now normalized in constant time by
@ref{6bf,,unicodedata.normalize()}. Patch by Donghee Na.

@item 
bpo-35474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35474}: Calling @ref{1823,,mimetypes.guess_all_extensions()} with
@code{strict=False} no longer affects the result of the following call with
@code{strict=True}. Also, mutating the returned list no longer affects the
global state.

@item 
bpo-45166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45166}: @ref{69c,,typing.get_type_hints()} now works with
@ref{264,,Final} wrapped in @ref{17d1,,ForwardRef}.

@item 
bpo-45162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45162}: Remove many old deprecated @ref{105,,unittest} features:


@itemize *

@item 
"@code{fail*}" and "@code{assert*}" aliases of @ref{437,,TestCase} methods.

@item 
Broken from start @ref{437,,TestCase} method @code{assertDictContainsSubset()}.

@item 
Ignored @code{<unittest.TestLoader.loadTestsFromModule> TestLoader.loadTestsFromModule()} parameter `use_load_tests'.

@item 
Old alias @code{_TextTestResult} of @ref{51a,,TextTestResult}.
@end itemize

@item 
bpo-38371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38371}: Remove the deprecated @code{split()} method of
@code{_tkinter.TkappType}. Patch by Erlend E. Aasland.

@item 
bpo-20499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20499}: Improve the speed and accuracy of statistics.pvariance().

@item 
bpo-45132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45132}: Remove @ref{280,,__getitem__()} methods of
@ref{71f,,xml.dom.pulldom.DOMEventStream}, @ref{720,,wsgiref.util.FileWrapper}
and @ref{721,,fileinput.FileInput}, deprecated since Python 3.9.

Patch by Hugo van Kemenade.

@item 
bpo-45129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45129}: Due to significant security concerns, the `reuse_address'
parameter of @ref{71d,,asyncio.loop.create_datagram_endpoint()}, disabled in
Python 3.9, is now entirely removed. This is because of the behavior of
the socket option @code{SO_REUSEADDR} in UDP.

Patch by Hugo van Kemenade.

@item 
bpo-45124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45124}: The @code{bdist_msi} command, deprecated in Python 3.9, is now
removed.

Use @code{bdist_wheel} (wheel packages) instead.

Patch by Hugo van Kemenade.

@item 
bpo-30856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30856}: @ref{1147,,unittest.TestResult} methods
@ref{1824,,addFailure()},
@ref{1825,,addError()},
@ref{1826,,addSkip()} and
@ref{1827,,addSubTest()} are now called immediately after
raising an exception in test or finishing a subtest. Previously they were
called only after finishing the test clean up.

@item 
bpo-45034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45034}: Changes how error is formatted for @code{struct.pack} with @code{'H'}
and @code{'h'} modes and too large / small numbers. Now it shows the actual
numeric limits, while previously it was showing arithmetic expressions.

@item 
bpo-25894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25894}: @ref{105,,unittest} now always reports skipped and failed subtests
separately: separate characters in default mode and separate lines in
verbose mode. Also the test description is now output for errors in test
method, class and module cleanups.

@item 
bpo-45081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45081}: Fix issue when dataclasses that inherit from
@code{typing.Protocol} subclasses have wrong @code{__init__}. Patch provided by
Yurii Karabas.

@item 
bpo-45085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45085}: The @code{binhex} module, deprecated in Python 3.9, is now
removed. The following @ref{10,,binascii} functions, deprecated in Python
3.9, are now also removed:


@itemize *

@item 
@code{a2b_hqx()}, @code{b2a_hqx()};

@item 
@code{rlecode_hqx()}, @code{rledecode_hqx()}.
@end itemize

The @ref{71e,,binascii.crc_hqx()} function remains available.

Patch by Victor Stinner.

@item 
bpo-40360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40360}: The @code{lib2to3} package is now deprecated and may not be
able to parse Python 3.10 or newer. See the 
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} (New PEG parser for
CPython). Patch by Victor Stinner.

@item 
bpo-45075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45075}: Rename @code{traceback.StackSummary.format_frame()} to
@ref{68e,,traceback.StackSummary.format_frame_summary()}. This method was added
for 3.11 so it was not released yet.

Updated code and docs to better distinguish frame and FrameSummary.

@item 
bpo-31299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31299}: Add option to completely drop frames from a traceback by
returning @code{None} from a @code{format_frame()}
override.

@item 
bpo-41620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41620}: @ref{1146,,run()} now always return a
@ref{1147,,TestResult} instance. Previously it returned @code{None} if
the test class or method was decorated with a skipping decorator.

@item 
bpo-45021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45021}: Fix a potential deadlock at shutdown of forked children when
using @ref{21,,concurrent.futures} module

@item 
bpo-43913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43913}: Fix bugs in cleaning up classes and modules in @ref{105,,unittest}:


@itemize *

@item 
Functions registered with @ref{a3b,,addModuleCleanup()} were not called unless the user defines @code{tearDownModule()} in their test module.

@item 
Functions registered with @ref{a3c,,addClassCleanup()} were not called if @code{tearDownClass} is set to @code{None}.

@item 
Buffering in @ref{1147,,TestResult} did not work with functions registered with @code{addClassCleanup()} and @code{addModuleCleanup()}.

@item 
Errors in functions registered with @code{addClassCleanup()} and @code{addModuleCleanup()} were not handled correctly in buffered and debug modes.

@item 
Errors in @code{setUpModule()} and functions registered with @code{addModuleCleanup()} were reported in wrong order.

@item 
And several lesser bugs.
@end itemize

@item 
bpo-45030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45030}: Fix integer overflow in pickling and copying the range
iterator.

@item 
bpo-45001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45001}: Made email date parsing more robust against malformed input,
namely a whitespace-only @code{Date:} header. Patch by Wouter Bolsterlee.

@item 
bpo-45010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45010}: Remove support of special method @code{__div__} in
@ref{106,,unittest.mock}. It is not used in Python 3.

@item 
bpo-39218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39218}: Improve accuracy of variance calculations by using @code{x*x}
instead of @code{x**2}.

@item 
bpo-43613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43613}: Improve the speed of @ref{629,,gzip.compress()} and
@ref{11ea,,gzip.decompress()} by compressing and decompressing at once in memory
instead of in a streamed fashion.

@item 
bpo-37596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37596}: Ensure that @ref{5c3,,set} and @ref{5c4,,frozenset} objects are
always @ref{8c,,marshalled} reproducibly.

@item 
bpo-44019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44019}: A new function @code{operator.call} has been added, such that
@code{operator.call(obj, *args, **kwargs) == obj(*args, **kwargs)}.

@item 
bpo-42255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42255}: @code{webbrowser.MacOSX} is deprecated and will be removed
in Python 3.13. It is untested and undocumented and also not used by
@ref{114,,webbrowser} itself. Patch by Donghee Na.

@item 
bpo-44955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44955}: Method @ref{1329,,stopTestRun()} is now always
called in pair with method @ref{1328,,startTestRun()} for
@ref{1147,,TestResult} objects implicitly created in
@ref{1146,,run()}. Previously it was not called for test
methods and classes decorated with a skipping decorator.

@item 
bpo-39039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39039}: tarfile.open raises @ref{1828,,ReadError} when a zlib error
occurs during file extraction.

@item 
bpo-44935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44935}: @ref{d5,,subprocess} on Solaris now also uses
@ref{21d,,os.posix_spawn()} for better performance.

@item 
bpo-44911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44911}: @ref{301,,IsolatedAsyncioTestCase} will no longer throw
an exception while cancelling leaked tasks. Patch by Bar Harel.

@item 
bpo-41322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41322}: Added @code{DeprecationWarning} for tests and async tests that
return a value!=None (as this may indicate an improperly written test, for
example a test written as a generator function).

@item 
bpo-44524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44524}: Make exception message more useful when subclass from typing
special form alias. Patch provided by Yurii Karabas.

@item 
bpo-38956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38956}: @ref{17e3,,argparse.BooleanOptionalAction}'s default value is no
longer printed twice when used with
@ref{1829,,argparse.ArgumentDefaultsHelpFormatter}.

@item 
bpo-44860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44860}: Fix the @code{posix_user} scheme in @ref{da,,sysconfig} to not depend
on @ref{925,,sys.platlibdir}.

@item 
bpo-44859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44859}: Improve error handling in @ref{ce,,sqlite3} and raise more
accurate exceptions.


@itemize *

@item 
@ref{164b,,MemoryError} is now raised instead of @ref{17b3,,sqlite3.Warning} when memory is not enough for encoding a statement to UTF-8 in @code{Connection.__call__()} and @code{Cursor.execute()}.

@item 
@code{UnicodEncodeError} is now raised instead of @ref{17b3,,sqlite3.Warning} when the statement contains surrogate characters in @code{Connection.__call__()} and @code{Cursor.execute()}.

@item 
@ref{522,,TypeError} is now raised instead of @ref{1ff,,ValueError} for non-string script argument in @code{Cursor.executescript()}.

@item 
@ref{1ff,,ValueError} is now raised for script containing the null character instead of truncating it in @code{Cursor.executescript()}.

@item 
Correctly handle exceptions raised when getting boolean value of the result of the progress handler.

@item 
Add many tests covering different corner cases.
@end itemize

@item 
bpo-44581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44581}: Upgrade bundled pip to 21.2.3 and setuptools to 57.4.0

@item 
bpo-44849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44849}: Fix the @ref{ee6,,os.set_inheritable()} function on FreeBSD 14 for
file descriptor opened with the @ref{f5d,,O_PATH} flag: ignore the
@ref{948,,EBADF} error on @code{ioctl()}, fallback on the @code{fcntl()}
implementation. Patch by Victor Stinner.

@item 
bpo-44605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44605}: The @@functools.total_ordering() decorator now works with
metaclasses.

@item 
bpo-44524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44524}: Fixed an issue wherein the @code{__name__} and @code{__qualname__}
attributes of subscribed specialforms could be @code{None}.

@item 
bpo-44839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44839}: @ref{164b,,MemoryError} raised in user-defined functions will now
produce a @code{MemoryError} in @ref{ce,,sqlite3}. @ref{86d,,OverflowError} will
now be converted to @ref{182a,,DataError}. Previously
@ref{182b,,OperationalError} was produced in these cases.

@item 
bpo-44822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44822}: @ref{ce,,sqlite3} user-defined functions and aggregators returning
@ref{435,,strings} with embedded NUL characters are no longer
truncated. Patch by Erlend E. Aasland.

@item 
bpo-44801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44801}: Ensure that the @ref{15d,,ParamSpec} variable in Callable
can only be substituted with a parameters expression (a list of types, an
ellipsis, ParamSpec or Concatenate).

@item 
bpo-44806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44806}: Non-protocol subclasses of @ref{261,,typing.Protocol} ignore now
the @code{__init__} method inherited from protocol base classes.

@item 
bpo-27275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27275}: @ref{12cb,,collections.OrderedDict.popitem()} and
@code{collections.OrderedDict.pop()} no longer call @code{__getitem__} and
@code{__delitem__} methods of the OrderedDict subclasses.

@item 
bpo-44793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44793}: Fix checking the number of arguments when subscribe a generic
type with @code{ParamSpec} parameter.

@item 
bpo-44784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44784}: In importlib.metadata tests, override warnings behavior under
expected DeprecationWarnings (importlib_metadata 4.6.3).

@item 
bpo-44667@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44667}: The @ref{4c3,,tokenize.tokenize()} doesn't incorrectly generate a
@code{NEWLINE} token if the source doesn't end with a new line character but
the last line is a comment, as the function is already generating a @code{NL}
token. Patch by Pablo Galindo

@item 
bpo-44771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44771}: Added @code{importlib.simple} module implementing adapters from a
low-level resources reader interface to a @code{TraversableResources}
interface. Legacy API (@code{path}, @code{contents}, ...) is now supported
entirely by the @code{.files()} API with a compatibility shim supplied for
resource loaders without that functionality. Feature parity with
@code{importlib_resources} 5.2.

@item 
bpo-44752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44752}: @code{rcompleter} does not call @ref{bbf,,getattr()} on
@ref{192,,property} objects to avoid the side-effect of  evaluating the
corresponding method.

@item 
bpo-44747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44747}: Refactor usage of @code{sys._getframe} in @code{typing} module. Patch
provided by Yurii Karabas.

@item 
bpo-42378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42378}: Fixes the issue with log file being overwritten when
@ref{182c,,logging.FileHandler} is used in @ref{c,,atexit} with `filemode' set
to @code{'w'}. Note this will cause the message in `atexit' not being logged
if the log stream is already closed due to shutdown of logging.

@item 
bpo-44720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44720}: @code{weakref.proxy} objects referencing non-iterators now raise
@code{TypeError} rather than dereferencing the null @code{tp_iternext} slot and
crashing.

@item 
bpo-44704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44704}: The implementation of @code{collections.abc.Set._hash()} now
matches that of @code{frozenset.__hash__()}.

@item 
bpo-44666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44666}: Fixed issue in @ref{dce,,compileall.compile_file()} when
@code{sys.stdout} is redirected. Patch by Stefan Hölzl.

@item 
bpo-44688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44688}: @ref{661,,sqlite3.Connection.create_collation()} now accepts
non-ASCII collation names. Patch by Erlend E. Aasland.

@item 
bpo-44690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44690}: Adopt `binacii.a2b_base64''s strict mode in `base64.b64decode'.

@item 
bpo-42854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42854}: Fixed a bug in the @code{_ssl} module that was throwing
@ref{86d,,OverflowError} when using @code{_ssl._SSLSocket.write()} and
@code{_ssl._SSLSocket.read()} for a big value of the @code{len} parameter.
Patch by Pablo Galindo.

@item 
bpo-44686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44686}: Replace @code{unittest.mock._importer} with
@code{pkgutil.resolve_name}.

@item 
bpo-44353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44353}: Make @code{NewType.__call__} faster by implementing it in C. Patch
provided by Yurii Karabas.

@item 
bpo-44682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44682}: Change the @ref{a4,,pdb} `commands' directive to disallow setting
commands for an invalid breakpoint and to display an appropriate error.

@item 
bpo-44353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44353}: Refactor @code{typing.NewType} from function into callable class.
Patch provided by Yurii Karabas.

@item 
bpo-44678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44678}: Added a separate error message for discontinuous padding in
`binascii.a2b_base64' strict mode.

@item 
bpo-44524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44524}: Add missing @code{__name__} and @code{__qualname__} attributes to
@code{typing} module classes. Patch provided by Yurii Karabas.

@item 
bpo-40897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40897}: Give priority to using the current class constructor in
@ref{722,,inspect.signature()}. Patch by Weipeng Hong.

@item 
bpo-44638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44638}: Add a reference to the zipp project and hint as to how to use
it.

@item 
bpo-44648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44648}: Fixed wrong error being thrown by @ref{154d,,inspect.getsource()}
when examining a class in the interactive session. Instead of
@ref{522,,TypeError}, it should be @ref{40d,,OSError} with appropriate error
message.

@item 
bpo-44608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44608}: Fix memory leak in @code{_tkinter._flatten()} if it is called
with a sequence or set, but not list or tuple.

@item 
bpo-44594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44594}: Fix an edge case of @code{ExitStack} and
@code{AsyncExitStack} exception chaining.  They will now match @code{with}
block behavior when @code{__context__} is explicitly set to @code{None} when the
exception is in flight.

@item 
bpo-42799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42799}: In @ref{5b,,fnmatch}, the cache size for compiled regex patterns
(@ref{9dd,,functools.lru_cache()}) was bumped up from 256 to 32768, affecting
functions: @ref{182d,,fnmatch.fnmatch()}, @ref{182e,,fnmatch.fnmatchcase()},
@ref{182f,,fnmatch.filter()}.

@item 
bpo-41928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41928}: Update @ref{a47,,shutil.copyfile()} to raise
@ref{eae,,FileNotFoundError} instead of confusing @ref{1042,,IsADirectoryError}
when a path ending with a @code{os.path.sep} does not exist;
@ref{a48,,shutil.copy()} and @ref{a49,,shutil.copy2()} are also affected.

@item 
bpo-44569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44569}: Added the @code{StackSummary.format_frame()} function in
@ref{fd,,traceback}. This allows users to customize the way individual lines
are formatted in tracebacks without re-implementing logic to handle
recursive tracebacks.

@item 
bpo-44566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44566}: handle StopIteration subclass raised from
@@contextlib.contextmanager generator

@item 
bpo-44558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44558}: Make the implementation consistency of
@ref{8c8,,indexOf()} between C and Python versions. Patch by Donghee
Na.

@item 
bpo-41249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41249}: Fixes @code{TypedDict} to work with @code{typing.get_type_hints()}
and postponed evaluation of annotations across modules.

@item 
bpo-44554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44554}: Refactor argument processing in @code{pdb.main()} to simplify
detection of errors in input loading and clarify behavior around module or
script invocation.

@item 
bpo-34798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34798}: Break up paragraph about @ref{f6a,,pprint.PrettyPrinter}
construction parameters to make it easier to read.

@item 
bpo-44539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44539}: Added support for recognizing JPEG files without JFIF or Exif
markers.

@item 
bpo-44461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44461}: Fix bug with @ref{a4,,pdb}'s handling of import error due to a
package which does not have a @code{__main__} module

@item 
bpo-43625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43625}: Fix a bug in the detection of CSV file headers by
@ref{1830,,csv.Sniffer.has_header()} and improve documentation of same.

@item 
bpo-44516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44516}: Update vendored pip to 21.1.3

@item 
bpo-42892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42892}: Fixed an exception thrown while parsing a malformed multipart
email by @ref{278,,email.message.EmailMessage}.

@item 
bpo-44468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44468}: @ref{69c,,typing.get_type_hints()} now finds annotations in classes
and base classes with unexpected @code{__module__}. Previously, it skipped
those MRO elements.

@item 
bpo-44491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44491}: Allow clearing the @ref{ce,,sqlite3} authorizer callback by
passing @ref{660,,None} to @ref{2a8,,set_authorizer()}. Patch
by Erlend E. Aasland.

@item 
bpo-43977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43977}: Set the proper @ref{1831,,Py_TPFLAGS_MAPPING} and
@ref{1832,,Py_TPFLAGS_SEQUENCE} flags for subclasses created before a
parent has been registered as a @ref{8b7,,collections.abc.Mapping} or
@ref{11a1,,collections.abc.Sequence}.

@item 
bpo-44482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44482}: Fix very unlikely resource leak in @ref{63,,glob} in alternate
Python implementations.

@item 
bpo-44466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44466}: The @ref{57,,faulthandler} module now detects if a fatal error
occurs during a garbage collector collection. Patch by Victor Stinner.

@item 
bpo-44471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44471}: A @ref{522,,TypeError} is now raised instead of an
@ref{343,,AttributeError} in @ref{5bd,,contextlib.ExitStack.enter_context()} and
@ref{5c0,,contextlib.AsyncExitStack.enter_async_context()} for objects which do
not support the @ref{5be,,context manager} or @ref{5c1,,asynchronous context manager} protocols correspondingly.

@item 
bpo-44404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44404}: @ref{ef,,tkinter}'s @code{after()} method now supports callables
without the @code{__name__} attribute.

@item 
bpo-41546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41546}: Make @ref{ad,,pprint} (like the builtin @code{print}) not attempt to
write to @code{stdout} when it is @code{None}.

@item 
bpo-44458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44458}: @code{BUFFER_BLOCK_SIZE} is now declared static, to avoid linking
collisions when bz2, lmza or zlib are statically linked.

@item 
bpo-44464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44464}: Remove exception for flake8 in deprecated importlib.metadata
interfaces. Sync with importlib_metadata 4.6.

@item 
bpo-44446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44446}: Take into account that @code{lineno} might be @code{None} in
@ref{e6f,,traceback.FrameSummary}.

@item 
bpo-44439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44439}: Fix in @code{bz2.BZ2File.write()} / @code{lzma.LZMAFile.write()}
methods, when the input data is an object that supports the buffer
protocol, the file length may be wrong.

@item 
bpo-44434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44434}: _thread.start_new_thread() no longer calls
PyThread_exit_thread() explicitly at the thread exit, the call was
redundant. On Linux with the glibc, pthread_exit() aborts the whole
process if dlopen() fails to open libgcc_s.so file (ex: EMFILE error).
Patch by Victor Stinner.

@item 
bpo-42972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42972}: The _thread.RLock type now fully implement the GC protocol: add
a traverse function and the @ref{767,,Py_TPFLAGS_HAVE_GC} flag. Patch by
Victor Stinner.

@item 
bpo-44422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44422}: The @ref{1833,,threading.enumerate()} function now uses a reentrant
lock to prevent a hang on reentrant call. Patch by Victor Stinner.

@item 
bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291}: Importing typing.io or typing.re now prints a
@code{DeprecationWarning}.

@item 
bpo-37880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37880}: argparse actions store_const and append_const each receive a
default value of @code{None} when the @code{const} kwarg is not provided.
Previously, this raised a @ref{522,,TypeError}.

@item 
bpo-44389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44389}: Fix deprecation of @ref{1834,,ssl.OP_NO_TLSv1_3}

@item 
bpo-27827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27827}: @code{pathlib.PureWindowsPath.is_reserved()} now identifies a
greater range of reserved filenames, including those with trailing spaces
or colons.

@item 
bpo-44395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44395}: Fix @code{as_string()} to pass unixfrom
properly. Patch by Donghee Na.

@item 
bpo-34266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34266}: Handle exceptions from parsing the arg of @ref{a4,,pdb}'s
run/restart command.

@item 
bpo-44362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44362}: Improve @ref{cf,,ssl} module's deprecation messages, error
reporting, and documentation for deprecations.

@item 
bpo-44342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44342}: [Enum] Change pickling from by-value to by-name.

@item 
bpo-44356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44356}: [Enum] Allow multiple data-type mixins if they are all the
same.

@item 
bpo-44351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44351}: Restore back @code{parse_makefile()} in @code{distutils.sysconfig}
because it behaves differently than the similar implementation in
@ref{da,,sysconfig}.

@item 
bpo-35800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35800}: @code{smtpd.MailmanProxy} is now removed as it is unusable
without an external module, @code{mailman}. Patch by Donghee Na.

@item 
bpo-44357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44357}: Added a function that returns cube root of the given number
@ref{64c,,math.cbrt()}

@item 
bpo-44339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44339}: Change @code{math.pow(±0.0, -math.inf)} to return @code{inf} instead
of raising @code{ValueError}. This brings the special-case handling of
@code{math.pow} into compliance with the IEEE 754 standard.

@item 
bpo-44242@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44242}: Remove missing flag check from Enum creation and move into a
@code{verify} decorator.

@item 
bpo-44246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44246}: In @code{importlib.metadata}, restore compatibility in the result
from @code{Distribution.entry_points} (@code{EntryPoints}) to honor expectations
in older implementations and issuing deprecation warnings for these cases:
A. @code{EntryPoints} objects are once again mutable, allowing   for
@code{sort()} and other list-based mutation operations.   Avoid deprecation
warnings by casting to a   mutable sequence (e.g.
@code{list(dist.entry_points).sort()}). B. @code{EntryPoints} results once again
allow   for access by index. To avoid deprecation warnings,   cast the
result to a Sequence first   (e.g. @code{tuple(dist.entry_points)[0]}).

@item 
bpo-44246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44246}: In importlib.metadata.entry_points, de-duplication of
distributions no longer requires loading the full metadata for
PathDistribution objects, improving entry point loading performance by
~10x.

@item 
bpo-43858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43858}: Added a function that returns a copy of a dict of logging
levels: @ref{644,,logging.getLevelNamesMapping()}

@item 
bpo-44260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44260}: The @ref{1835,,random.Random} constructor no longer reads system
entropy without need.

@item 
bpo-44254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44254}: On Mac, give turtledemo button text a color that works on both
light or dark background.  Programmers cannot control the latter.

@item 
bpo-44258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44258}: Support PEP 515 for Fraction's initialization from string.

@item 
bpo-44235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44235}: Remove deprecated functions in the @ref{62,,gettext}. Patch by
Donghee Na.

@item 
bpo-38693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38693}: Prefer f-strings to @code{.format} in importlib.resources.

@item 
bpo-33693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33693}: Importlib.metadata now prefers f-strings to .format.

@item 
bpo-44241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44241}: Incorporate minor tweaks from importlib_metadata 4.1:
SimplePath protocol, support for Metadata 2.2.

@item 
bpo-43216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43216}: Remove the @code{@@asyncio.coroutine}
@ref{71b,,decorator} enabling legacy generator-based coroutines to be
compatible with async/await code; remove
@code{asyncio.coroutines.CoroWrapper} used for wrapping legacy coroutine
objects in the debug mode. The decorator has been deprecated since Python
3.8 and the removal was initially scheduled for Python 3.10. Patch by
Illia Volochii.

@item 
bpo-44210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44210}: Make importlib.metadata._meta.PackageMetadata public.

@item 
bpo-43643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43643}: Declare readers.MultiplexedPath.name as a property per the
spec.

@item 
bpo-27334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27334}: The @ref{ce,,sqlite3} context manager now performs a rollback
(thus releasing the database lock) if commit failed.  Patch by Luca Citi
and Erlend E. Aasland.

@item 
bpo-4928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4928}: Documented existing behavior on POSIX: NamedTemporaryFiles are
not deleted when creating process is killed with SIGKILL

@item 
bpo-44154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44154}: Optimize @ref{1e4,,fractions.Fraction} pickling for large
components.

@item 
bpo-33433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33433}: For IPv4 mapped IPv6 addresses (
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html} Section 2.5.5.2),
the @ref{15d3,,ipaddress.IPv6Address.is_private} check is deferred to the
mapped IPv4 address. This solves a bug where public mapped IPv4 addresses
were considered private by the IPv6 check.

@item 
bpo-44150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44150}: Add optional `weights' argument to statistics.fmean().

@item 
bpo-44142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44142}: @ref{8d2,,ast.unparse()} will now drop the redundant parentheses
when tuples used as assignment targets (e.g in for loops).

@item 
bpo-44145@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44145}: @ref{69,,hmac} computations were not releasing the GIL while
calling the OpenSSL @code{HMAC_Update} C API (a new feature in 3.9).  This
unintentionally prevented parallel computation as other @ref{67,,hashlib}
algorithms support.

@item 
bpo-44095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44095}: @ref{6b4,,zipfile.Path} now supports @ref{6b1,,zipfile.Path.stem},
@ref{6b3,,zipfile.Path.suffixes}, and @ref{6b2,,zipfile.Path.suffix} attributes.

@item 
bpo-44077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44077}: It's now possible to receive the type of service (ToS), a.k.a.
differentiated services (DS), a.k.a. differentiated services code point
(DSCP) and explicit congestion notification (ECN) IP header fields with
@code{socket.IP_RECVTOS}.

@item 
bpo-37788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37788}: Fix a reference leak when a Thread object is never joined.

@item 
bpo-38908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38908}: Subclasses of @code{typing.Protocol} which only have data
variables declared will now raise a @code{TypeError} when checked with
@code{isinstance} unless they are decorated with @code{runtime_checkable()}.
Previously, these checks passed silently. Patch provided by Yurii Karabas.

@item 
bpo-44098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44098}: @code{typing.ParamSpec} will no longer be found in the
@code{__parameters__} of most @ref{103,,typing} generics except in valid use
locations specified by 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/}. This prevents incorrect usage like
@code{typing.List[P][int]}. This change means incorrect usage which may have
passed silently in 3.10 beta 1 and earlier will now error.

@item 
bpo-44089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44089}: Allow subclassing @code{csv.Error} in 3.10 (it was allowed in 3.9
and earlier but was disallowed in early versions of 3.10).

@item 
bpo-44081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44081}: @ref{8d2,,ast.unparse()} now doesn't use redundant spaces to
separate @code{lambda} and the @code{:} if there are no parameters.

@item 
bpo-44061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44061}: Fix regression in previous release when calling
@ref{d38,,pkgutil.iter_modules()} with a list of @ref{226,,pathlib.Path} objects

@item 
bpo-44059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44059}: Register the SerenityOS Browser in the @ref{114,,webbrowser}
module.

@item 
bpo-36515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36515}: The @ref{67,,hashlib} module no longer does unaligned memory
accesses when compiled for ARM platforms.

@item 
bpo-40465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40465}: Remove random module features deprecated in Python 3.9.

@item 
bpo-44018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44018}: random.seed() no longer mutates bytearray inputs.

@item 
bpo-38352@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38352}: Add @code{IO}, @code{BinaryIO}, @code{TextIO}, @code{Match}, and
@code{Pattern} to @code{typing.__all__}. Patch by Jelle Zijlstra.

@item 
bpo-44002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44002}: @ref{109,,urllib.parse} now uses @code{functool.lru_cache()} for its
internal URL splitting and quoting caches instead of rolling its own like
its the '90s.

The undocumented internal @ref{109,,urllib.parse} @code{Quoted} class API is now
deprecated, for removal in 3.14.

@item 
bpo-43972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43972}: When @ref{b31,,http.server.SimpleHTTPRequestHandler} sends a
@code{301 (Moved Permanently)} for a directory path not ending with @code{/},
add a @code{Content-Length: 0} header. This improves the behavior for certain
clients.

@item 
bpo-28528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28528}: Fix a bug in @ref{a4,,pdb} where @code{checkline()} raises
@ref{343,,AttributeError} if it is called after @code{reset()}.

@item 
bpo-43853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43853}: Improved string handling for @ref{ce,,sqlite3} user-defined
functions and aggregates:


@itemize *

@item 
It is now possible to pass strings with embedded null characters to UDFs

@item 
Conversion failures now correctly raise @ref{164b,,MemoryError}
@end itemize

Patch by Erlend E. Aasland.

@item 
bpo-43666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43666}: AIX: @code{Lib/_aix_support.get_platform()} may fail in an AIX
WPAR. The fileset bos.rte appears to have a builddate in both LPAR and
WPAR so this fileset is queried rather than bos.mp64. To prevent a similar
situation (no builddate in ODM) a value (9988) sufficient for completing a
build is provided. Patch by M Felt.

@item 
bpo-43650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43650}: Fix @ref{164b,,MemoryError} in @ref{455,,shutil.unpack_archive()} which
fails inside @code{shutil._unpack_zipfile()} on large files. Patch by Igor
Bolshakov.

@item 
bpo-43612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43612}: @ref{62a,,zlib.compress()} now accepts a wbits parameter which
allows users to compress data as a raw deflate block without zlib headers
and trailers in one go. Previously this required instantiating a
@code{zlib.compressobj}. It also provides a faster alternative to
@code{gzip.compress} when wbits=31 is used.

@item 
bpo-43392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43392}: @code{importlib._bootstrap._find_and_load()} now implements a
two-step check to avoid locking when modules have been already imported
and are ready. This improves performance of repeated calls to
@ref{501,,importlib.import_module()} and @ref{1056,,importlib.__import__()}.

@item 
bpo-43318@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43318}: Fix a bug where @ref{a4,,pdb} does not always echo cleared
breakpoints.

@item 
bpo-43234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43234}: Prohibit passing
non-@ref{72c,,concurrent.futures.ThreadPoolExecutor} executors to
@code{loop.set_default_executor()} following a deprecation in Python 3.8.
Patch by Illia Volochii.

@item 
bpo-43232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43232}: Prohibit previously deprecated potentially disruptive
operations on @code{asyncio.trsock.TransportSocket}. Patch by Illia
Volochii.

@item 
bpo-30077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30077}: Added support for Apple's aifc/sowt pseudo-compression

@item 
bpo-42971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42971}: Add definition of @code{errno.EQFULL} for platforms that define
this constant (such as macOS).

@item 
bpo-43086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43086}: Added a new optional @code{strict_mode} parameter to
`binascii.a2b_base64'. When @code{scrict_mode} is set to @code{True},
the `a2b_base64' function will accept only valid base64 content. More
details about what "valid base64 content" is, can be found in the
function's documentation.

@item 
bpo-43024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43024}: Improve the help signature of
@ref{839,,traceback.print_exception()}, @ref{837,,traceback.format_exception()} and
@ref{838,,traceback.format_exception_only()}.

@item 
bpo-33809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33809}: Add the @ref{68f,,traceback.TracebackException.print()} method which
prints the formatted exception information.

@item 
bpo-42862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42862}: @ref{ce,,sqlite3} now utilizes @ref{9dd,,functools.lru_cache()} to
implement the connection statement cache. As a small optimisation, the
default statement cache size has been increased from 100 to 128. Patch by
Erlend E. Aasland.

@item 
bpo-41818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41818}: Soumendra Ganguly: add termios.tcgetwinsize(),
termios.tcsetwinsize().

@item 
bpo-40497@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40497}: @ref{fac,,subprocess.check_output()} now raises @ref{1ff,,ValueError}
when the invalid keyword argument `check' is passed by user code.
Previously such use would fail later with a @ref{522,,TypeError}. Patch by
Rémi Lapeyre.

@item 
bpo-37449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37449}: @code{ensurepip} now uses @code{importlib.resources.files()}
traversable APIs

@item 
bpo-40956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40956}: Use Argument Clinic in @ref{ce,,sqlite3}.  Patches by Erlend E.
Aasland.

@item 
bpo-41730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41730}: @code{DeprecationWarning} is now raised when importing
@code{tkinter.tix}, which has been deprecated in documentation since
Python 3.6.

@item 
bpo-20684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20684}: Remove unused @code{_signature_get_bound_param} function from
@ref{7d,,inspect} - by Anthony Sottile.

@item 
bpo-41402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41402}: Fix @ref{1836,,email.message.EmailMessage.set_content()} when called
with binary data and @code{7bit} content transfer encoding.

@item 
bpo-32695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32695}: The `compresslevel' and `preset' keyword arguments of
@ref{e60,,tarfile.open()} are now both documented and tested.

@item 
bpo-41137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41137}: Use utf-8 encoding while reading .pdbrc files. Patch by
Srinivas Reddy Thatiparthy

@item 
bpo-24391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24391}: Improved reprs of @ref{ec,,threading} synchronization objects:
@ref{1136,,Semaphore}, @ref{1137,,BoundedSemaphore},
@ref{1138,,Event} and @ref{11c0,,Barrier}.

@item 
bpo-5846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5846}: Deprecated the following @ref{105,,unittest} functions, scheduled
for removal in Python 3.13:


@itemize *

@item 
@code{findTestCases()}

@item 
@code{makeSuite()}

@item 
@code{getTestCaseNames()}
@end itemize

Use @ref{28b,,TestLoader} methods instead:


@itemize *

@item 
@ref{28c,,unittest.TestLoader.loadTestsFromModule()}

@item 
@ref{28d,,unittest.TestLoader.loadTestsFromTestCase()}

@item 
@ref{28e,,unittest.TestLoader.getTestCaseNames()}
@end itemize

Patch by Erlend E. Aasland.

@item 
bpo-40563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40563}: Support pathlike objects on dbm/shelve. Patch by Hakan Çelik
and Henry-Joseph Audéoud.

@item 
bpo-34990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34990}: Fixed a Y2k38 bug in the compileall module where it would fail
to compile files with a modification time after the year 2038.

@item 
bpo-39549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39549}: Whereas the code for reprlib.Repr had previously used a
hardcoded string value of '...', this PR updates it to use of a
“fillvalue” attribute, whose value defaults to '...' and can be reset in
either individual reprlib.Repr instances or in subclasses thereof.

@item 
bpo-37022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37022}: @ref{a4,,pdb} now displays exceptions from @code{repr()} with its
@code{p} and @code{pp} commands.

@item 
bpo-38840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38840}: Fix @code{test___all__} on platforms lacking a shared memory
implementation.

@item 
bpo-39359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39359}: Add one missing check that the password is a bytes object for
an encrypted zipfile.

@item 
bpo-38741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38741}: @ref{22,,configparser}: using ']' inside a section header will no
longer cut the section name short at the ']'

@item 
bpo-38415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38415}: Added missing behavior to
@ref{b18,,contextlib.asynccontextmanager()} to match
@ref{11df,,contextlib.contextmanager()} so decorated functions can themselves be
decorators.

@item 
bpo-30256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30256}: Pass multiprocessing BaseProxy argument @code{manager_owned}
through AutoProxy.

@item 
bpo-27513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27513}: @ref{1de,,email.utils.getaddresses()} now accepts
@ref{1837,,email.header.Header} objects along with string values. Patch by
Zackery Spytz.

@item 
bpo-16379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16379}: Add SQLite error code and name to @ref{ce,,sqlite3} exceptions.
Patch by Aviv Palivoda, Daniel Shahaf, and Erlend E. Aasland.

@item 
bpo-26228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26228}: pty.spawn no longer hangs on FreeBSD, macOS, and Solaris.

@item 
bpo-33349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33349}: lib2to3 now recognizes async generators everywhere.

@item 
bpo-29298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29298}: Fix @code{TypeError} when required subparsers without @code{dest} do
not receive arguments. Patch by Anthony Sottile.
@end itemize

@node Documentation<26>,Tests<29>,Library<31>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id263}@anchor{1838}
@subsubsection Documentation



@itemize -

@item 
bpo-45216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45216}: Remove extra documentation listing methods in @code{difflib}. It
was rendering twice in pydoc and was outdated in some places.

@item 
bpo-45024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45024}: @ref{1e,,collections.abc} documentation has been expanded to
explicitly cover how instance and subclass checks work, with additional
doctest examples and an exhaustive list of ABCs which test membership
purely by presence of the right @ref{1839,,special method}s. Patch by Raymond
Hettinger.

@item 
bpo-44957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44957}: Promote PEP 604 union syntax by using it where possible. Also,
mention @code{X | Y} more prominently in section about @code{Union} and mention
@code{X | None} at all in section about @code{Optional}.

@item 
bpo-16580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16580}: Added code equivalents for the @ref{181d,,int.to_bytes()} and
@ref{17dd,,int.from_bytes()} methods, as well as tests ensuring that these code
equivalents are valid.

@item 
bpo-44903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44903}: Removed the @code{othergui.rst} file, any references to it, and
the list of GUI frameworks in the FAQ. In their place I've added links to
the Python Wiki page on GUI frameworks@footnote{https://wiki.python.org/moin/GuiProgramming}.

@item 
bpo-33479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33479}: Tkinter documentation has been greatly expanded with new
"Architecture" and "Threading model" sections.

@item 
bpo-36700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36700}: @ref{e,,base64} RFC references were updated to point to
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}; a section was added to point users to the new "security
considerations" section of the RFC.

@item 
bpo-44740@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44740}: Replaced occurrences of uppercase "Web" and "Internet" with
lowercase versions per the 2016 revised Associated Press Style Book.

@item 
bpo-44693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44693}: Update the definition of __future__ in the glossary by
replacing the confusing word "pseudo-module" with a more accurate
description.

@item 
bpo-35183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35183}: Add typical examples to os.path.splitext docs

@item 
bpo-30511@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30511}: Clarify that @ref{49c,,shutil.make_archive()} is not thread-safe due
to reliance on changing the current working directory.

@item 
bpo-44561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44561}: Update of three expired hyperlinks in
Doc/distributing/index.rst: "Project structure", "Building and packaging
the project", and "Uploading the project to the Python Packaging Index".

@item 
bpo-44651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44651}: Delete entry "coercion" in Doc/glossary.rst for its outdated
definition.

@item 
bpo-42958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42958}: Updated the docstring and docs of @ref{15e7,,filecmp.cmp()} to be
more accurate and less confusing especially in respect to `shallow' arg.

@item 
bpo-44631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44631}: Refactored the @code{repr()} code of the @code{_Environ} (os module).

@item 
bpo-44613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44613}: importlib.metadata is no longer provisional.

@item 
bpo-44558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44558}: Match the docstring and python implementation of
@ref{8c9,,countOf()} to the behavior of its c implementation.

@item 
bpo-44544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44544}: List all kwargs for @ref{147b,,textwrap.wrap()},
@ref{147a,,textwrap.fill()}, and @ref{fbb,,textwrap.shorten()}. Now, there are nav
links to attributes of @code{TextWrap}, which makes navigation much
easier while minimizing duplication in the documentation.

@item 
bpo-38062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38062}: Clarify that atexit uses equality comparisons internally.

@item 
bpo-40620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40620}: Convert examples in tutorial controlflow.rst section 4.3 to be
interpreter-demo style.

@item 
bpo-43066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43066}: Added a warning to @ref{130,,zipfile} docs: filename arg with a
leading slash may cause archive to be un-openable on Windows systems.

@item 
bpo-39452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39452}: Rewrote @code{Doc/library/__main__.rst}. Broadened scope of the
document to explicitly discuss and differentiate between @code{__main__.py}
in packages versus the @code{__name__ == '__main__'} expression (and the
idioms that surround it).

@item 
bpo-13814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13814}: In the Design FAQ, answer "Why don't generators support the
with statement?"

@item 
bpo-27752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27752}: Documentation of csv.Dialect is more descriptive.

@item 
bpo-44453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44453}: Fix documentation for the return type of
@ref{130c,,sysconfig.get_path()}.

@item 
bpo-44392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44392}: Added a new section in the C API documentation for types used
in type hinting.  Documented @code{Py_GenericAlias} and
@code{Py_GenericAliasType}.

@item 
bpo-38291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38291}: Mark @code{typing.io} and @code{typing.re} as deprecated since Python
3.8 in the documentation. They were never properly supported by type
checkers.

@item 
bpo-44322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44322}: Document that SyntaxError args have a details tuple and that
details are adjusted for errors in f-string field replacement expressions.

@item 
bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}: Document the deprecation and removal of the @code{loop} parameter
for many functions and classes in @ref{a,,asyncio}.

@item 
bpo-44195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44195}: Corrected references to @code{TraversableResources} in docs. There
is no @code{TraversableReader}.

@item 
bpo-41963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41963}: Document that @code{ConfigParser} strips off comments when reading
configuration files.

@item 
bpo-44072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44072}: Correct where in the numeric ABC hierarchy @code{**} support is
added, i.e., in numbers.Complex, not numbers.Integral.

@item 
bpo-43558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43558}: Add the remark to @ref{2f,,dataclasses} documentation that the
@code{__init__()} of any base class has to be called in
@code{__post_init__()}, along with a code example.

@item 
bpo-44025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44025}: Clarify when '_' in match statements is a keyword, and when
not.

@item 
bpo-41706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41706}: Fix docs about how methods like @code{__add__} are invoked when
evaluating operator expressions.

@item 
bpo-41621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41621}: Document that @ref{119a,,collections.defaultdict} parameter
@code{default_factory} defaults to @code{None} and is positional-only.

@item 
bpo-41576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41576}: document BaseException in favor of bare except

@item 
bpo-21760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21760}: The description for __file__ fixed. Patch by Furkan Onder

@item 
bpo-39498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39498}: Add a "Security Considerations" index which links to standard
library modules that have explicitly documented security considerations.

@item 
bpo-33479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33479}: Remove the unqualified claim that tkinter is threadsafe. It has
not been true for several years and likely never was. An explanation of
what is true may be added later, after more discussion, and possibly after
patching _tkinter.c,
@end itemize

@node Tests<29>,Build<31>,Documentation<26>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id264}@anchor{183a}
@subsubsection Tests



@itemize -

@item 
bpo-40173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40173}: Fix @ref{183b,,test.support.import_helper.import_fresh_module()}.

@item 
bpo-45280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45280}: Add a test case for empty @ref{2ad,,typing.NamedTuple}.

@item 
bpo-45269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45269}: Cover case when invalid @code{markers} type is supplied to
@code{c_make_encoder}.

@item 
bpo-45128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45128}: Fix @code{test_multiprocessing_fork} failure due to
@code{test_logging} and @code{sys.modules} manipulation.

@item 
bpo-45209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45209}: Fix @code{UserWarning: resource_tracker} warning in
@code{_test_multiprocessing._TestSharedMemory.test_shared_memory_cleaned_after_process_termination}

@item 
bpo-45185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45185}: Enables @code{TestEnumerations} test cases in @code{test_ssl} suite.

@item 
bpo-45195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45195}: Fix test_readline.test_nonascii(): sometimes, the newline
character is not written at the end, so don't expect it in the output.
Patch by Victor Stinner.

@item 
bpo-45156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45156}: Fixes infinite loop on @ref{b8f,,unittest.mock.seal()} of mocks
created by @code{create_autospec()}.

@item 
bpo-45125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45125}: Improves pickling tests and docs of @code{SharedMemory} and
@code{SharableList} objects.

@item 
bpo-44860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44860}: Update @code{test_sysconfig.test_user_similar()} for the
posix_user scheme: @code{platlib} doesn't use @ref{925,,sys.platlibdir}. Patch
by Victor Stinner.

@item 
bpo-45052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45052}: @code{WithProcessesTestSharedMemory.test_shared_memory_basics}
test was ignored, because @code{self.assertEqual(sms.size, sms2.size)} line
was failing. It is now removed and test is unskipped.

The main motivation for this line to be removed from the test is that the
@code{size} of @code{SharedMemory} is not ever guaranteed to be the same. It is
decided by the platform.

@item 
bpo-44895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44895}: libregrtest now clears the type cache later to reduce the risk
of false alarm when checking for reference leaks. Previously, the type
cache was cleared too early and libregrtest raised a false alarm about
reference leaks under very specific conditions. Patch by Irit Katriel and
Victor Stinner.

@item 
bpo-45042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45042}: Fixes that test classes decorated with
@code{@@hashlib_helper.requires_hashdigest} were skipped all the time.

@item 
bpo-25130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25130}: Add calls of @ref{a28,,gc.collect()} in tests to support PyPy.

@item 
bpo-45011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45011}: Made tests relying on the @code{_asyncio} C extension module
optional to allow running on alternative Python implementations. Patch by
Serhiy Storchaka.

@item 
bpo-44949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44949}: Fix auto history tests of test_readline: sometimes, the newline
character is not written at the end, so don't expect it in the output.

@item 
bpo-44891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44891}: Tests were added to clarify @ref{13d9,,id()} is preserved when @code{obj
* 1} is used on @ref{435,,str} and @ref{1bd,,bytes} objects. Patch by Nikita
Sobolev.

@item 
bpo-44852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44852}: Add ability to wholesale silence DeprecationWarnings while
running the regression test suite.

@item 
bpo-40928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40928}: Notify users running test_decimal regression tests on macOS of
potential harmless "malloc can't allocate region" messages spewed by
test_decimal.

@item 
bpo-44734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44734}: Fixed floating-point precision issue in turtle tests.

@item 
bpo-44708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44708}: Regression tests, when run with -w, are now re-running only the
affected test methods instead of re-running the entire test file.

@item 
bpo-42095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42095}: Added interop tests for Apple plists: generate plist files with
Python plistlib and parse with Apple plutil; and the other way round.

@item 
bpo-44647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44647}: Added a permanent Unicode-valued environment variable to
regression tests to ensure they handle this use case in the future. If
your test environment breaks because of that, report a bug to us, and
temporarily set PYTHONREGRTEST_UNICODE_GUARD=0 in your test environment.

@item 
bpo-44515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44515}: Adjust recently added contextlib tests to avoid assuming the
use of a refcounted GC

@item 
bpo-44287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44287}: Fix asyncio test_popen() of test_windows_utils by using a
longer timeout. Use military grade battle-tested
@ref{183c,,test.support.SHORT_TIMEOUT} timeout rather than a hardcoded timeout
of 10 seconds: it's 30 seconds by default, but it is made longer on slow
buildbots. Patch by Victor Stinner.

@item 
bpo-44451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44451}: Reset @code{DeprecationWarning} filters in
@code{test.test_importlib.test_metadata_api.APITests.test_entry_points_by_index}
to avoid @code{StopIteration} error if @code{DeprecationWarnings} are ignored.

@item 
bpo-44363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44363}: Account for address sanitizer in test_capi. test_capi now
passes when run GCC address sanitizer.

@item 
bpo-44364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44364}: Add non integral tests for @ref{9f4,,math.sqrt()} function.

@item 
bpo-43921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43921}: Fix test_ssl.test_wrong_cert_tls13(): use
@code{suppress_ragged_eofs=False}, since @code{read()} can raise
@ref{16d2,,ssl.SSLEOFError} on Windows. Patch by Victor Stinner.

@item 
bpo-43921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43921}: Fix test_pha_required_nocert() of test_ssl: catch two more EOF
cases (when the @code{recv()} method returns an empty string). Patch by
Victor Stinner.

@item 
bpo-44131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44131}: Add test_frozenmain to test_embed to test the
@code{Py_FrozenMain()} C function. Patch by Victor Stinner.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Ignore error string case in test_file_not_exists().

@item 
bpo-42083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42083}: Add test to check that @code{PyStructSequence_NewType} accepts a
@code{PyStructSequence_Desc} with @code{doc} field set to @code{NULL}.

@item 
bpo-35753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35753}: Fix crash in doctest when doctest parses modules that include
unwrappable functions by skipping those functions.

@item 
bpo-30256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30256}: Add test for nested queues when using @code{multiprocessing}
shared objects @code{AutoProxy[Queue]} inside @code{ListProxy} and @code{DictProxy}
@end itemize

@node Build<31>,Windows<28>,Tests<29>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id265}@anchor{183d}
@subsubsection Build



@itemize -

@item 
bpo-45220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45220}: Avoid building with the Windows 11 SDK previews automatically.
This may be overridden by setting the @code{DefaultWindowsSDKVersion}
environment variable before building.

@item 
bpo-45020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45020}: Freeze stdlib modules that are imported during startup.  This
provides significant performance improvements to startup.  If necessary,
use the previously added "-X frozen_modules=off" commandline option to
force importing the source modules.

@item 
bpo-45188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45188}: Windows builds now regenerate frozen modules as the first part
of the build. Previously the regeneration was later in the build, which
would require it to be restarted if any modules had changed.

@item 
bpo-45163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45163}: Fixes Haiku platform build.

@item 
bpo-45067@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45067}: The ncurses function extended_color_content was introduced in
2017

(@indicateurl{https://invisible-island.net/ncurses/NEWS.html#index-t20170401}).  The

ncurses-devel package in CentOS 7 had a older version ncurses resulted in
compilation error.  For compiling ncurses with extended color support, we
verify the version of the ncurses library >= 20170401.

@item 
bpo-45019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45019}: Generate lines in relevant files for frozen modules.  Up until
now each of the files had to be edited manually.  This change makes it
easier to add to and modify the frozen modules.

@item 
bpo-44340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44340}: Add support for building with clang thin lto via
--with-lto=thin/full. Patch by Donghee Na and Brett Holman.

@item 
bpo-44535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44535}: Enable building using a Visual Studio 2022 install on Windows.

@item 
bpo-43298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43298}: Improved error message when building without a Windows SDK
installed.

@item 
bpo-44381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44381}: The Windows build now accepts 
@geindex EnableControlFlowGuard
@geindex variable d'environnement; EnableControlFlowGuard
@code{EnableControlFlowGuard}
set to @code{guard} to enable CFG.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: Fix broken @code{make install} that caused standard library
extension modules to be unnecessarily and incorrectly rebuilt during the
install phase of cpython.
@end itemize

@node Windows<28>,macOS<22>,Build<31>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id266}@anchor{183e}
@subsubsection Windows



@itemize -

@item 
bpo-45375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45375}: Fixes an assertion failure due to searching for the standard
library in unnormalised paths.

@item 
bpo-45022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45022}: Update Windows release to include libffi 3.4.2

@item 
bpo-45007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45007}: Update to OpenSSL 1.1.1l in Windows build

@item 
bpo-44848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44848}: Upgrade Windows installer to use SQLite 3.36.0.

@item 
bpo-44572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44572}: Avoid consuming standard input in the @ref{a9,,platform} module

@item 
bpo-44582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44582}: Accelerate speed of @ref{8e,,mimetypes} initialization using a
native implementation of the registry scan.

@item 
bpo-41299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41299}: Fix 16 milliseconds jitter when using timeouts in
@ref{ec,,threading}, such as with @ref{683,,threading.Lock.acquire()} or
@ref{183f,,threading.Condition.wait()}.

@item 
bpo-42686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42686}: Build @ref{ce,,sqlite3} with math functions enabled. Patch by
Erlend E. Aasland.

@item 
bpo-40263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40263}: This is a follow-on bug from
@indicateurl{https://bugs.python.org/issue26903}. Once that is applied we run into an
off-by-one assertion problem. The assert was not correct.
@end itemize

@node macOS<22>,IDLE<19>,Windows<28>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id267}@anchor{1840}
@subsubsection macOS



@itemize -

@item 
bpo-45007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45007}: Update macOS installer builds to use OpenSSL 1.1.1l.

@item 
bpo-34602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34602}: When building CPython on macOS with @code{./configure
--with-undefined-behavior-sanitizer --with-pydebug}, the stack size is
now quadrupled to allow for the entire test suite to pass.

@item 
bpo-44848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44848}: Update macOS installer to use SQLite 3.36.0.

@item 
bpo-44689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44689}: @ref{d37,,ctypes.util.find_library()} now works correctly on macOS
11 Big Sur even if Python is built on an older version of macOS.
Previously, when built on older macOS systems, @code{find_library} was not
able to find  macOS system libraries when running on Big Sur due to
changes in  how system libraries are stored.

@item 
bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972}: The framework build's user header path in sysconfig is changed
to add a 'pythonX.Y' component to match distutils's behavior.

@item 
bpo-43109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43109}: Allow --with-lto configure option to work with Apple-supplied
Xcode or Command Line Tools.

@item 
bpo-34932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34932}: Add socket.TCP_KEEPALIVE support for macOS. Patch by Shane
Harvey.
@end itemize

@node IDLE<19>,Tools/Demos<15>,macOS<22>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id268}@anchor{1841}
@subsubsection IDLE



@itemize -

@item 
bpo-45296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45296}: On Windows, change exit/quit message to suggest Ctrl-D, which
works, instead of <Ctrl-Z Return>, which does not work in IDLE.

@item 
bpo-45193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45193}: Make completion boxes appear on Ubuntu again.

@item 
bpo-40128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40128}: Mostly fix completions on macOS when not using tcl/tk 8.6.11
(as with 3.9). The added update_idletask call should be harmless and
possibly helpful otherwise.

@item 
bpo-33962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33962}: Move the indent space setting from the Font tab to the new
Windows tab. Patch by Mark Roseman and Terry Jan Reedy.

@item 
bpo-40468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40468}: Split the settings dialog General tab into Windows and Shell/ED
tabs. Move help sources, which extend the Help menu, to the Extensions
tab. Make space for new options and shorten the dialog. The latter makes
the dialog better fit small screens.

@item 
bpo-41611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41611}: Avoid uncaught exceptions in
@code{AutoCompleteWindow.winconfig_event()}.

@item 
bpo-41611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41611}: Fix IDLE sometimes freezing upon tab-completion on macOS.

@item 
bpo-44010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44010}: Highlight the new @ref{7f7,,match} statement's @ref{7f6,,soft keywords}: @ref{7f7,,match}, @ref{7f7,,case}, and
@ref{7f8,,_}. However, this highlighting is not
perfect and will be incorrect in some rare cases, including some @code{_}-s
in @code{case} patterns.

@item 
bpo-44026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44026}: Include interpreter's typo fix suggestions in message line for
NameErrors and AttributeErrors.  Patch by E. Paine.
@end itemize

@node Tools/Demos<15>,C API<30>,IDLE<19>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id269}@anchor{1842}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-44786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44786}: Fix a warning in regular expression in the c-analyzer script.

@item 
bpo-44967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44967}: pydoc now returns a non-zero status code when a module cannot
be found.

@item 
bpo-44978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44978}: Allow the Argument Clinic tool to handle @code{__complex__}
special methods.

@item 
bpo-43425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43425}: Removed the 'test2to3' demo project that demonstrated using
lib2to3 to support Python 2.x and Python 3.x from a single source in a
distutils package. Patch by Donghee Na

@item 
bpo-44074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44074}: Make patchcheck automatically detect the correct base branch
name (previously it was hardcoded to 'master')

@item 
bpo-20291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20291}: Added support for variadic positional parameters in Argument
Clinic.
@end itemize

@node C API<30>,,Tools/Demos<15>,Python 3 11 0 alpha 1
@anchor{whatsnew/changelog id270}@anchor{1843}
@subsubsection C API



@itemize -

@item 
bpo-41710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41710}: The PyThread_acquire_lock_timed() function now clamps the
timeout if it is too large, rather than aborting the process. Patch by
Victor Stinner.

@item 
bpo-44687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44687}: @code{BufferedReader.peek()} no longer raises @ref{1ff,,ValueError}
when the entire file has already been buffered.

@item 
bpo-45116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45116}: Add the @ref{1844,,Py_ALWAYS_INLINE} macro to ask the compiler
to always inline a static inline function. The compiler can ignore it and
decides to not inline the function. Patch by Victor Stinner.

@item 
bpo-45094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45094}: Add the @ref{1845,,Py_NO_INLINE} macro to disable inlining on a
function. Patch by Victor Stinner.

@item 
bpo-45061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=45061}: Add a deallocator to the @ref{451,,bool} type to detect refcount
bugs in C extensions which call @code{Py_DECREF(Py_True);} or
@code{Py_DECREF(Py_False);} by mistake. Patch by Victor Stinner.

@item 
bpo-42035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42035}: Add a new @ref{73d,,PyType_GetQualName()} function to get type's
qualified name.

@item 
bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}: Reverts removal of the old buffer protocol because they are
part of stable ABI.

@item 
bpo-44751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44751}: Remove @code{crypt.h} include from the public @code{Python.h} header.

@item 
bpo-42747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42747}: The @code{Py_TPFLAGS_HAVE_VERSION_TAG} type flag now does nothing.
The @code{Py_TPFLAGS_HAVE_AM_SEND} flag (which was added in 3.10) is removed.
Both were unnecessary because it is not possible to have type objects with
the relevant fields missing.

@item 
bpo-44530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44530}: Added the @code{co_qualname} to the @code{PyCodeObject} structure to
propagate the qualified name from the compiler to code objects.

Patch by Gabriele N. Tornetta

@item 
bpo-44441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44441}: @ref{9b3,,Py_RunMain()} now resets @code{PyImport_Inittab} to
its initial value at exit. It must be possible to call
@ref{1731,,PyImport_AppendInittab()} or @ref{1732,,PyImport_ExtendInittab()} at
each Python initialization. Patch by Victor Stinner.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Remove 4 private trashcan C API functions which were only kept
for the backward compatibility of the stable ABI with Python 3.8 and
older, since the trashcan API was not usable with the limited C API on
Python 3.8 and older. The trashcan API was excluded from the limited C API
in Python 3.9.

Removed functions:


@itemize *

@item 
_PyTrash_deposit_object()

@item 
_PyTrash_destroy_chain()

@item 
_PyTrash_thread_deposit_object()

@item 
_PyTrash_thread_destroy_chain()
@end itemize

The trashcan C API was never usable with the limited C API, since old
trashcan macros accessed directly @ref{777,,PyThreadState} members like
@code{_tstate->trash_delete_nesting}, whereas the @ref{777,,PyThreadState}
structure is opaque in the limited C API.

Exclude also the @code{PyTrash_UNWIND_LEVEL} constant from the C API.

Patch by Victor Stinner.

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Removed documentation for the removed @code{PyParser_*} C API.

@item 
bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}: The list in @ref{784,,Contenu de l’API restreinte} now shows the public name
@ref{773,,PyFrameObject} rather than @code{_frame}. The non-existing entry
@code{_node} no longer appears in the list.

@item 
bpo-44378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44378}: @ref{17a3,,Py_IS_TYPE()} no longer uses @ref{76a,,Py_TYPE()} to avoid
a compiler warning: no longer cast @code{const PyObject*} to @code{PyObject*}.
Patch by Victor Stinner.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Convert the @ref{76a,,Py_TYPE()} and @ref{76c,,Py_SIZE()} macros to
static inline functions. The @ref{76b,,Py_SET_TYPE()} and
@ref{76d,,Py_SET_SIZE()} functions must now be used to set an object type and
size. Patch by Victor Stinner.

@item 
bpo-44263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44263}: The @ref{766,,PyType_Ready()} function now raises an error if a
type is defined with the @ref{767,,Py_TPFLAGS_HAVE_GC} flag set but has no
traverse function (@ref{768,,PyTypeObject.tp_traverse}). Patch by Victor
Stinner.

@item 
bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}: The undocumented function @code{Py_FrozenMain()} is removed
from the Limited API.

@item 
bpo-44113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44113}: Deprecate the following functions to configure the Python
initialization:


@itemize *

@item 
@code{PySys_AddWarnOptionUnicode()}

@item 
@code{PySys_AddWarnOption()}

@item 
@code{PySys_AddXOption()}

@item 
@code{PySys_HasWarnOptions()}

@item 
@code{Py_SetPath()}

@item 
@code{Py_SetProgramName()}

@item 
@code{Py_SetPythonHome()}

@item 
@code{Py_SetStandardStreamEncoding()}

@item 
@code{_Py_SetProgramFullPath()}
@end itemize

Use the new @ref{39d,,PyConfig} API of the @ref{39e,,Python Initialization Configuration} instead (
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}).

@item 
bpo-44094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44094}: Remove @code{PyErr_SetFromErrnoWithUnicodeFilename()},
@code{PyErr_SetFromWindowsErrWithUnicodeFilename()}, and
@code{PyErr_SetExcFromWindowsErrWithUnicodeFilename()}. They are not
documented and have been deprecated since Python 3.3.

@item 
bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}: @ref{883,,PyCodec_Unregister()} is now properly exported as a
function in the Windows Stable ABI DLL.

@item 
bpo-44029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44029}: Remove deprecated @code{Py_UNICODE} APIs: @code{PyUnicode_Encode},
@code{PyUnicode_EncodeUTF7}, @code{PyUnicode_EncodeUTF8},
@code{PyUnicode_EncodeUTF16}, @code{PyUnicode_EncodeUTF32},
@code{PyUnicode_EncodeLatin1}, @code{PyUnicode_EncodeMBCS},
@code{PyUnicode_EncodeDecimal}, @code{PyUnicode_EncodeRawUnicodeEscape},
@code{PyUnicode_EncodeCharmap}, @code{PyUnicode_EncodeUnicodeEscape},
@code{PyUnicode_TransformDecimalToASCII}, @code{PyUnicode_TranslateCharmap},
@code{PyUnicodeEncodeError_Create}, @code{PyUnicodeTranslateError_Create}. See
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} and 
@geindex Python Enhancement Proposals; PEP 624
PEP 624@footnote{https://peps.python.org/pep-0624/} for reference.

@item 
bpo-42035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42035}: Add a new @ref{73c,,PyType_GetName()} function to get type's short
name.
@end itemize

@node Python 3 10 0 beta 1,Python 3 10 0 alpha 7,Python 3 11 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-10-0-beta-1}@anchor{1846}
@subsection Python 3.10.0 beta 1


`Release date: 2021-05-03'

@menu
* Security: Security<19>. 
* Core and Builtins: Core and Builtins<33>. 
* Library: Library<32>. 
* Documentation: Documentation<27>. 
* Tests: Tests<30>. 
* Build: Build<32>. 
* Windows: Windows<29>. 
* macOS: macOS<23>. 
* IDLE: IDLE<20>. 
* C API: C API<31>. 

@end menu

@node Security<19>,Core and Builtins<33>,,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id271}@anchor{1847}
@subsubsection Security



@itemize -

@item 
bpo-43434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43434}: Creating @ref{242,,sqlite3.Connection} objects now also produces
@code{sqlite3.connect} and @code{sqlite3.connect/handle} @ref{1848,,auditing events}. Previously these events were only produced by
@ref{2a5,,sqlite3.connect()} calls. Patch by Erlend E. Aasland.

@item 
bpo-43998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43998}: The @ref{cf,,ssl} module sets more secure cipher suites defaults.
Ciphers without forward secrecy and with SHA-1 MAC are disabled by
default. Security level 2 prohibits weak RSA, DH, and ECC keys with less
than 112 bits of security. @ref{291,,SSLContext} defaults to minimum
protocol version TLS 1.2. Settings are based on Hynek Schlawack's
research.

@item 
bpo-43882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43882}: The presence of newline or tab characters in parts of a URL
could allow some forms of attacks.

Following the controlling specification for URLs defined by WHATWG
@ref{109,,urllib.parse()} now removes ASCII newlines and tabs from URLs,
preventing such attacks.

@item 
bpo-43472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43472}: Ensures interpreter-level audit hooks receive the
@code{cpython.PyInterpreterState_New} event when called through the
@code{_xxsubinterpreters} module.

@item 
bpo-43362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43362}: Fix invalid free in _sha3 module. The issue was introduced in
3.10.0a1. Python 3.9 and earlier are not affected.

@item 
bpo-43762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43762}: Add audit events for @code{sqlite3.connect/handle()},
@ref{828,,sqlite3.Connection.enable_load_extension()}, and
@ref{4a1,,sqlite3.Connection.load_extension()}. Patch by Erlend E. Aasland.

@item 
bpo-43756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43756}: Add new audit event @code{glob.glob/2} to incorporate the new
`root_dir' and `dir_fd' arguments added to @ref{29c,,glob.glob()} and
@ref{7f1,,glob.iglob()}.

@item 
bpo-36384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36384}: @ref{7f,,ipaddress} module no longer accepts any leading zeros in
IPv4 address strings. Leading zeros are ambiguous and interpreted as octal
notation by some libraries. For example the legacy function
@ref{94e,,socket.inet_aton()} treats leading zeros as octal notation. glibc
implementation of modern @ref{94f,,inet_pton()} does not accept any
leading zeros. For a while the @ref{7f,,ipaddress} module used to accept
ambiguous leading zeros.

@item 
bpo-43075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43075}: Fix Regular Expression Denial of Service (ReDoS) vulnerability
in @ref{1849,,urllib.request.AbstractBasicAuthHandler}.  The ReDoS-vulnerable
regex has quadratic worst-case complexity and it allows cause a denial of
service when identifying crafted invalid RFCs. This ReDoS issue is on the
client side and needs remote attackers to control the HTTP server.

@item 
bpo-42800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42800}: Audit hooks are now fired for frame.f_code, traceback.tb_frame,
and generator code/frame attribute access.

@item 
bpo-37363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37363}: Add audit events to the @ref{6e,,http.client} module.
@end itemize

@node Core and Builtins<33>,Library<32>,Security<19>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id272}@anchor{184a}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-43977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43977}: Prevent classes being both a sequence and a mapping when
pattern matching.

@item 
bpo-43977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43977}: Use @ref{184b,,tp_flags} on the class object to
determine if the subject is a sequence or mapping when pattern matching.
Avoids the need to import @ref{1e,,collections.abc} when pattern matching.

@item 
bpo-43892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43892}: Restore proper validation of complex literal value patterns
when parsing @code{match} blocks.

@item 
bpo-43933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43933}: Set frame.f_lineno to the line number of the 'with' kweyword
when executing the call to @code{__exit__}.

@item 
bpo-43933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43933}: If the current position in a frame has no line number then set
the f_lineno attribute to None, instead of -1, to conform to PEP 626. This
should not normally be possible, but might occur in some unusual
circumstances.

@item 
bpo-43963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43963}: Importing the @code{_signal} module in a subinterpreter has no
longer side effects.

@item 
bpo-42739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42739}: The internal representation of line number tables is changed to
not use sentinels, and an explicit length parameter is added to the out of
process API function @code{PyLineTable_InitAddressRange}. This makes the
handling of line number tables more robust in some circumstances.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Make @ref{b8,,re} types immutable. Patch by Erlend E. Aasland.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Make the @ref{19e,,array.array} type immutable. Patch by Erlend
E. Aasland.

@item 
bpo-43901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43901}: Change class and module objects to lazy-create empty
annotations dicts on demand.  The annotations dicts are stored in the
object's __dict__ for backwards compatibility.

@item 
bpo-43892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43892}: Match patterns now use new dedicated AST nodes (@code{MatchValue},
@code{MatchSingleton}, @code{MatchSequence}, @code{MatchStar}, @code{MatchMapping},
@code{MatchClass}) rather than reusing expression AST nodes. @code{MatchAs} and
@code{MatchOr} are now defined as pattern nodes rather than as expression
nodes. Patch by Nick Coghlan.

@item 
bpo-42725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42725}: Usage of @code{await}/@code{yield}/@code{yield from} and named
expressions within an annotation is now forbidden when PEP 563 is
activated.

@item 
bpo-43754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43754}: When performing structural pattern matching (
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/}),
captured names are now left unbound until the `entire' pattern has matched
successfully.

@item 
bpo-42737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42737}: Annotations for complex targets (everything beside simple
names) no longer cause any runtime effects with @code{from __future__ import
annotations}.

@item 
bpo-43914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43914}: @ref{18b,,SyntaxError} exceptions raised by the interpreter will
highlight the full error range of the expression that constitutes the
syntax error itself, instead of just where the problem is detected. Patch
by Pablo Galindo.

@item 
bpo-38605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38605}: Revert making @code{from __future__ import annotations} the
default. This follows the Steering Council decision to postpone PEP 563
changes to at least Python 3.11. See the original email for more
information regarding the decision:
@indicateurl{https://mail.python.org/archives/list/python-dev@@python.org/thread/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/}.
Patch by Pablo Galindo.

@item 
bpo-43475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43475}: Hashes of NaN values now depend on object identity.  Formerly,
they always hashed to 0 even though NaN values are not equal to one
another.  Having the same hash for unequal values caused pile-ups in hash
tables.

@item 
bpo-43859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43859}: Improve the error message for @ref{792,,IndentationError}
exceptions. Patch by Pablo Galindo

@item 
bpo-41323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41323}: Constant tuple folding in bytecode optimizer now reuses tuple
in constant table.

@item 
bpo-43846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43846}: Data stack usage is much reduced for large literal and call
expressions.

@item 
bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}: When printing @ref{428,,NameError} raised by the interpreter,
@code{PyErr_Display()} will offer suggestions of similar variable names
in the function that the exception was raised from. Patch by Pablo Galindo

@item 
bpo-43823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43823}: Improve syntax errors for invalid dictionary literals. Patch by
Pablo Galindo.

@item 
bpo-43822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43822}: Improve syntax errors in the parser for missing commas between
expressions. Patch by Pablo Galindo.

@item 
bpo-43798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43798}: @ref{184c,,ast.alias} nodes now include source location metadata
attributes e.g. lineno, col_offset.

@item 
bpo-43797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43797}: Improve @code{SyntaxError} error messages for invalid comparisons.
Patch by Pablo Galindo.

@item 
bpo-43760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43760}: Move the flag for checking whether tracing is enabled to the C
stack, from the heap. Should speed up dispatch in the interpreter.

@item 
bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682}: Static methods (@ref{40c,,@@staticmethod}) and class
methods (@ref{165,,@@classmethod}) now inherit the method
attributes (@code{__module__}, @code{__name__}, @code{__qualname__}, @code{__doc__},
@code{__annotations__}) and have a new @code{__wrapped__} attribute. Patch by
Victor Stinner.

@item 
bpo-43751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43751}: Fixed a bug where @code{anext(ait, default)} would erroneously
return None.

@item 
bpo-42128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42128}: @ref{184d,,__match_args__} is no longer allowed to be a
list.

@item 
bpo-43683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43683}: Add GEN_START opcode. Marks start of generator, including
async, or coroutine and handles sending values to a newly created
generator or coroutine.

@item 
bpo-43105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43105}: Importlib now resolves relative paths when creating module spec
objects from file locations.

@item 
bpo-43682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43682}: Static methods (@ref{40c,,@@staticmethod}) are now
callable as regular functions. Patch by Victor Stinner.

@item 
bpo-42609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42609}: Prevented crashes in the AST validator and optimizer when
compiling some absurdly long expressions like @code{"+0"*1000000}.
@ref{d59,,RecursionError} is now raised instead.

@item 
bpo-38530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38530}: When printing @ref{343,,AttributeError}, @code{PyErr_Display()}
will offer suggestions of similar attribute names in the object that the
exception was raised from. Patch by Pablo Galindo
@end itemize

@node Library<32>,Documentation<27>,Core and Builtins<33>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id273}@anchor{184e}
@subsubsection Library



@itemize -

@item 
bpo-44015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44015}: In @@dataclass(), raise a TypeError if KW_ONLY is specified more
than once.

@item 
bpo-25478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25478}: Added a `total()' method to collections.Counter() to compute
the sum of the counts.

@item 
bpo-43733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43733}: Change @ref{184f,,netrc.netrc} to use UTF-8 encoding before using
locale encoding.

@item 
bpo-43979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43979}: Removed an unnecessary list comprehension before looping from
@ref{276,,urllib.parse.parse_qsl()}.  Patch by Christoph Zwerschke and Donghee
Na.

@item 
bpo-43993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43993}: Update bundled pip to 21.1.1.

@item 
bpo-43957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43957}: [Enum] Deprecate @code{TypeError} when non-member is used in a
containment check; In 3.12 @code{True} or @code{False} will be returned instead,
and containment will return @code{True} if the value is either a member of
that enum or one of its members' value.

@item 
bpo-42904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42904}: For backwards compatibility with previous minor versions of
Python, if @ref{69c,,typing.get_type_hints()} receives no namespace dictionary
arguments, @ref{69c,,typing.get_type_hints()} will search through the global
then local namespaces during evaluation of stringized type annotations
(string forward references) inside a class.

@item 
bpo-43945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43945}: [Enum] Deprecate non-standard mixin format() behavior: in 3.12
the enum member, not the member's value, will be used for format() calls.

@item 
bpo-41139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41139}: Deprecate undocumented @code{cgi.log()} API.

@item 
bpo-43937@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43937}: Fixed the @ref{100,,turtle} module working with non-default root
window.

@item 
bpo-43930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43930}: Update bundled pip to 21.1 and setuptools to 56.0.0

@item 
bpo-43907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43907}: Fix a bug in the pure-Python pickle implementation when using
protocol 5, where bytearray instances that occur several time in the
pickled object graph would incorrectly unpickle into repeated copies of
the bytearray object.

@item 
bpo-43926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43926}: In @code{importlib.metadata}, provide a uniform interface to
@code{Description}, allow for any field to be encoded with multiline values,
remove continuation lines from multiline values, and add a @code{.json}
property for easy access to the PEP 566 JSON-compatible form. Sync with
@code{importlib_metadata 4.0}.

@item 
bpo-43920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43920}: OpenSSL 3.0.0: @ref{ed6,,load_verify_locations()}
now returns a consistent error message when cadata contains no valid
certificate.

@item 
bpo-43607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43607}: @ref{107,,urllib} can now convert Windows paths with @code{\\?\}
prefixes into URL paths.

@item 
bpo-43817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43817}: Add @ref{7fd,,inspect.get_annotations()}, which safely computes the
annotations defined on an object.  It works around the quirks of accessing
the annotations from various types of objects, and makes very few
assumptions about the object passed in. @ref{7fd,,inspect.get_annotations()}
can also correctly un-stringize stringized annotations.

@ref{722,,inspect.signature()}, @code{inspect.from_callable()}, and
@code{inspect.from_function()} now call @ref{7fd,,inspect.get_annotations()} to
retrieve annotations.  This means @ref{722,,inspect.signature()} and
@code{inspect.from_callable()} can now un-stringize stringized annotations,
too.

@item 
bpo-43284@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43284}: platform.win32_ver derives the windows version from
sys.getwindowsversion().platform_version which in turn derives the version
from kernel32.dll (which can be of a different version than Windows
itself). Therefore change the platform.win32_ver to determine the version
using the platform module's _syscmd_ver private function to return an
accurate version.

@item 
bpo-42854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42854}: The @ref{cf,,ssl} module now uses @code{SSL_read_ex} and
@code{SSL_write_ex} internally. The functions support reading and writing of
data larger than 2 GB. Writing zero-length data no longer fails with a
protocol violation error.

@item 
bpo-42333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42333}: Port @code{_ssl} extension module to multiphase initialization.

@item 
bpo-43880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43880}: @ref{cf,,ssl} now raises DeprecationWarning for OP_NO_SSL/TLS*
options, old TLS versions, old protocols, and other features that have
been deprecated since Python 3.6, 3.7, or OpenSSL 1.1.0.

@item 
bpo-41559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41559}: 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} is now implemented purely in Python; builtin
@code{types.GenericAlias} objects no longer include @code{typing.ParamSpec} in
@code{__parameters__} (with the exception of @code{collections.abc.Callable}'s
@code{GenericAlias}). This means previously invalid uses of @code{ParamSpec}
(such as @code{list[P]}) which worked in earlier versions of Python 3.10
alpha, will now raise @code{TypeError} during substitution.

@item 
bpo-43867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43867}: The @ref{93,,multiprocessing} @code{Server} class now explicitly
catches @ref{d2e,,SystemExit} and closes the client connection in this case.
It happens when the @code{Server.serve_client()} method reaches the end of
file (EOF).

@item 
bpo-40443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40443}: Remove unused imports: pyclbr no longer uses copy, and typing
no longer uses ast. Patch by Victor Stinner.

@item 
bpo-43820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43820}: Remove an unneeded copy of the namespace passed to
dataclasses.make_dataclass().

@item 
bpo-43787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43787}: Add @code{__iter__()} method to @ref{851,,bz2.BZ2File},
@ref{410,,gzip.GzipFile}, and @ref{ff5,,lzma.LZMAFile}. It makes iterating
them about 2x faster. Patch by Inada Naoki.

@item 
bpo-43680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43680}: Deprecate io.OpenWrapper and _pyio.OpenWrapper: use io.open and
_pyio.open instead. Until Python 3.9, _pyio.open was not a static method
and builtins.open was set to OpenWrapper to not become a bound method when
set to a class variable. _io.open is a built-in function whereas
_pyio.open is a Python function. In Python 3.10, _pyio.open() is now a
static method, and builtins.open() is now io.open().

@item 
bpo-43680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43680}: The Python @code{_pyio.open()} function becomes a static method
to behave as @ref{506,,io.open()} built-in function: don't become a bound
method when stored as a class variable. It becomes possible since static
methods are now callable in Python 3.10. Moreover,
@code{_pyio.OpenWrapper()} becomes a simple alias to @code{_pyio.open()}.
Patch by Victor Stinner.

@item 
bpo-41515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41515}: Fix @ref{33a,,KeyError} raised in @ref{69c,,typing.get_type_hints()} due
to synthetic modules that don't appear in @code{sys.modules}.

@item 
bpo-43776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43776}: When @ref{197,,subprocess.Popen} args are provided as a string or
as @ref{226,,pathlib.Path}, the Popen instance repr now shows the right
thing.

@item 
bpo-42248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42248}: [Enum] ensure exceptions raised in @code{_missing__} are released

@item 
bpo-43744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43744}: fix issue with enum member name matching the start of a private
variable name

@item 
bpo-43772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43772}: Fixed the return value of @code{TypeVar.__ror__}. Patch by Jelle
Zijlstra.

@item 
bpo-43764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43764}: Add match_args parameter to @@dataclass decorator to allow
suppression of __match_args__ generation.

@item 
bpo-43799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43799}: OpenSSL 3.0.0: define @code{OPENSSL_API_COMPAT} 1.1.1 to suppress
deprecation warnings. Python requires OpenSSL 1.1.1 APIs.

@item 
bpo-43478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43478}: Mocks can no longer be used as the specs for other Mocks. As a
result, an already-mocked object cannot have an attribute mocked using
@code{autospec=True} or be the subject of a @code{create_autospec(...)} call.
This can uncover bugs in tests since these Mock-derived Mocks will always
pass certain tests (e.g. @ref{42b,,isinstance()}) and builtin assert functions
(e.g. assert_called_once_with) will unconditionally pass.

@item 
bpo-43794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43794}: Add @ref{821,,ssl.OP_IGNORE_UNEXPECTED_EOF} constants (OpenSSL
3.0.0)

@item 
bpo-43785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43785}: Improve @code{bz2.BZ2File} performance by removing the RLock from
BZ2File. This makes BZ2File thread unsafe in the face of multiple
simultaneous readers or writers, just like its equivalent classes in
@ref{66,,gzip} and @ref{89,,lzma} have always been.  Patch by Inada Naoki.

@item 
bpo-43789@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43789}: OpenSSL 3.0.0: Don't call the password callback function a
second time when first call has signaled an error condition.

@item 
bpo-43788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43788}: The header files for @ref{cf,,ssl} error codes are now OpenSSL
version-specific. Exceptions will now show correct reason and library
codes. The @code{make_ssl_data.py} script has been rewritten to use OpenSSL's
text file with error codes.

@item 
bpo-43766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43766}: Implement 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/} in the @ref{103,,typing} module by adding
@code{TypeGuard}.

@item 
bpo-25264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25264}: @ref{222,,os.path.realpath()} now accepts a `strict' keyword-only
argument. When set to @code{True}, @ref{40d,,OSError} is raised if a path doesn't
exist or a symlink loop is encountered.

@item 
bpo-43780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43780}: In @code{importlib.metadata}, incorporate changes from
importlib_metadata 3.10: Add mtime-based caching during distribution
discovery. Flagged use of dict result from @code{entry_points()} as
deprecated.

@item 
The @code{P.args} and @code{P.kwargs} attributes of @ref{15d,,typing.ParamSpec}
are now instances of the new classes @ref{7b0,,typing.ParamSpecArgs} and
@ref{7b1,,typing.ParamSpecKwargs}, which enables a more useful @code{repr()}.
Patch by Jelle Zijlstra.

@item 
bpo-43731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43731}: Add an @code{encoding} parameter @code{logging.fileConfig()}.

@item 
bpo-43712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43712}: Add @code{encoding} and @code{errors} parameters to
@ref{7e9,,fileinput.input()} and @ref{721,,fileinput.FileInput}.

@item 
bpo-38659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38659}: A @code{simple_enum} decorator is added to the @code{enum} module to
convert a normal class into an Enum. @code{test_simple_enum} added to test
simple enums against a corresponding normal Enum.  Standard library
modules updated to use @code{simple_enum}.

@item 
bpo-43764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43764}: Fix an issue where @ref{184d,,__match_args__} generation
could fail for some @ref{2f,,dataclasses}.

@item 
bpo-43752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43752}: Fix @ref{ce,,sqlite3} regression for zero-sized blobs with
converters, where @code{b""} was returned instead of @code{None}. The regression
was introduced by PR 24723. Patch by Erlend E. Aasland.

@item 
bpo-43655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43655}: @ref{ef,,tkinter} dialog windows are now recognized as dialogs by
window managers on macOS and X Window.

@item 
bpo-43723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43723}: The following @code{threading} methods are now deprecated and
should be replaced:


@itemize -

@item 
@code{currentThread} => @ref{2fe,,threading.current_thread()}

@item 
@code{activeCount} => @ref{2ff,,threading.active_count()}

@item 
@code{Condition.notifyAll} => @ref{2f8,,threading.Condition.notify_all()}

@item 
@code{Event.isSet} => @ref{2f9,,threading.Event.is_set()}

@item 
@code{Thread.setName} => @ref{2fd,,threading.Thread.name}

@item 
@code{thread.getName} => @ref{2fd,,threading.Thread.name}

@item 
@code{Thread.isDaemon} => @ref{2fb,,threading.Thread.daemon}

@item 
@code{Thread.setDaemon} => @ref{2fb,,threading.Thread.daemon}
@end itemize

Patch by Jelle Zijlstra.

@item 
bpo-2135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2135}: Deprecate find_module() and find_loader() implementations in
importlib and zipimport.

@item 
bpo-43534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43534}: @ref{1850,,turtle.textinput()} and @ref{1851,,turtle.numinput()} create now
a transient window working on behalf of the canvas window.

@item 
bpo-43532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43532}: Add the ability to specify keyword-only fields to dataclasses.
These fields will become keyword-only arguments to the generated __init__.

@item 
bpo-43522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43522}: Fix problem with
@ref{b6b,,hostname_checks_common_name}. OpenSSL does not copy
hostflags from `struct SSL_CTX' to `struct SSL'.

@item 
bpo-8978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8978}: Improve error message for @ref{e60,,tarfile.open()} when @ref{89,,lzma}
/ @ref{13,,bz2} are unavailable.  Patch by Anthony Sottile.

@item 
bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}: Allow @ref{1bd,,bytes} @code{separator} argument in
@code{urllib.parse.parse_qs} and @code{urllib.parse.parse_qsl} when parsing
@ref{435,,str} query strings. Previously, this raised a @code{TypeError}.

@item 
bpo-43296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43296}: Improve @ref{ce,,sqlite3} error handling: @code{sqlite3_value_blob()}
errors that set @code{SQLITE_NOMEM} now raise @ref{164b,,MemoryError}. Patch by
Erlend E. Aasland.

@item 
bpo-43312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43312}: New functions @ref{67b,,sysconfig.get_preferred_scheme()} and
@ref{17b1,,sysconfig.get_default_scheme()} are added to query a platform for its
preferred "user", "home", and "prefix" (default) scheme names.

@item 
bpo-43265@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43265}: Improve @ref{b68,,sqlite3.Connection.backup()} error handling. The
error message for non-existent target database names is now @code{unknown
database <database name>} instead of @code{SQL logic error}. Patch by Erlend
E. Aasland.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: Install schemes in @code{distutils.command.install} are now loaded
from @ref{da,,sysconfig}.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: @code{distutils.sysconfig} has been merged to @ref{da,,sysconfig}.

@item 
bpo-43176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43176}: Fixed processing of a dataclass that inherits from a frozen
dataclass with no fields.  It is now correctly detected as an error.

@item 
bpo-43080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43080}: @ref{ad,,pprint} now has support for
@ref{1c6,,dataclasses.dataclass}. Patch by Lewis Gaul.

@item 
bpo-39950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39950}: Add @code{pathlib.Path.hardlink_to()} method that supersedes
@code{link_to()}. The new method has the same argument order as
@code{symlink_to()}.

@item 
bpo-42904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42904}: @ref{69c,,typing.get_type_hints()} now checks the local namespace of
a class when evaluating 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/} annotations inside said class.

@item 
bpo-42269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42269}: Add @code{slots} parameter to @code{dataclasses.dataclass} decorator
to automatically generate @code{__slots__} for class. Patch provided by Yurii
Karabas.

@item 
bpo-39529@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39529}: Deprecated use of @ref{2bf,,asyncio.get_event_loop()} without
running event loop. Emit deprecation warning for @ref{a,,asyncio} functions
which implicitly create a @ref{bbb,,Future} or
@ref{4c2,,Task} objects if there is no running event loop and no
explicit `loop' argument is passed: @ref{c64,,ensure_future()},
@ref{1852,,wrap_future()}, @ref{5e8,,gather()},
@ref{a5e,,shield()}, @ref{1a8,,as_completed()} and constructors of
@ref{bbb,,Future}, @ref{4c2,,Task},
@ref{1853,,StreamReader}, @code{StreamReaderProtocol}.

@item 
bpo-18369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18369}: Certificate and PrivateKey classes were added to the ssl
module. Certificates and keys can now be loaded from memory buffer, too.

@item 
bpo-41486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41486}: Use a new output buffer management code for @ref{13,,bz2} /
@ref{89,,lzma} / @ref{132,,zlib} modules, and add @code{.readall()} function to
@code{_compression.DecompressReader} class. These bring some performance
improvements. Patch by Ma Lin.

@item 
bpo-31870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31870}: The @ref{826,,ssl.get_server_certificate()} function now has a
`timeout' parameter.

@item 
bpo-41735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41735}: Fix thread locks in zlib module may go wrong in rare case.
Patch by Ma Lin.

@item 
bpo-36470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36470}: Fix dataclasses with @code{InitVar}s and
@ref{1682,,replace()}. Patch by Claudiu Popa.

@item 
bpo-40849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40849}: Expose X509_V_FLAG_PARTIAL_CHAIN ssl flag

@item 
bpo-35114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35114}: @ref{1854,,ssl.RAND_status()} now returns a boolean value (as
documented) instead of @code{1} or @code{0}.

@item 
bpo-39906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39906}: @ref{80d,,pathlib.Path.stat()} and @ref{80e,,chmod()} now
accept a `follow_symlinks' keyword-only argument for consistency with
corresponding functions in the @ref{a0,,os} module.

@item 
bpo-39899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39899}: @ref{a02,,os.path.expanduser()} now refuses to guess Windows home
directories if the basename of current user's home directory does not
match their username.

@ref{e2f,,pathlib.Path.expanduser()} and @ref{e30,,home()} now
consistently raise @ref{193,,RuntimeError} exception when a home directory
cannot be resolved. Previously a @ref{33a,,KeyError} exception could be raised
on Windows when the @code{"USERNAME"}  environment variable was unset.

@item 
bpo-36076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36076}: Added SNI support to @ref{826,,ssl.get_server_certificate()}.

@item 
bpo-38490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38490}: Covariance, Pearson's correlation, and simple linear regression
functionality was added to statistics module. Patch by Tymoteusz Wołodźko.

@item 
bpo-33731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33731}: Provide a locale.localize() function, which converts a
normalized number string into a locale format.

@item 
bpo-32745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32745}: Fix a regression in the handling of ctypes'
@ref{1671,,ctypes.c_wchar_p} type: embedded null characters would cause a
@ref{1ff,,ValueError} to be raised. Patch by Zackery Spytz.
@end itemize

@node Documentation<27>,Tests<30>,Library<32>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id274}@anchor{1855}
@subsubsection Documentation



@itemize -

@item 
bpo-43987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43987}: Add "Annotations Best Practices" document as a new HOWTO.

@item 
bpo-43977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43977}: Document the new @ref{1831,,Py_TPFLAGS_MAPPING} and
@ref{1832,,Py_TPFLAGS_SEQUENCE} type flags.

@item 
bpo-43959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43959}: The documentation on the PyContextVar C-API was clarified.

@item 
bpo-43938@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43938}: Update dataclasses documentation to express that
FrozenInstanceError is derived from AttributeError.

@item 
bpo-43778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43778}: Fix the Sphinx glossary_search extension: create the _static/
sub-directory if it doesn't exist.

@item 
bpo-43755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43755}: Update documentation to reflect that unparenthesized lambda
expressions can no longer be the expression part in an @code{if} clause in
comprehensions and generator expressions since Python 3.9.

@item 
bpo-43739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43739}: Fixing the example code in Doc/extending/extending.rst to
declare and initialize the pmodule variable to be of the right type.
@end itemize

@node Tests<30>,Build<32>,Documentation<27>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id275}@anchor{1856}
@subsubsection Tests



@itemize -

@item 
bpo-43961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43961}: Fix test_logging.test_namer_rotator_inheritance() on Windows:
use @ref{10d3,,os.replace()} rather than @ref{10d2,,os.rename()}. Patch by Victor
Stinner.

@item 
bpo-43842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43842}: Fix a race condition in the SMTP test of test_logging. Don't
close a file descriptor (socket) from a different thread while
asyncore.loop() is polling the file descriptor. Patch by Victor Stinner.

@item 
bpo-43843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43843}: @code{test.libregrtest} now marks a test as ENV_CHANGED
(altered the execution environment) if a thread raises an exception but
does not catch it. It sets a hook on @ref{835,,threading.excepthook()}. Use
@code{--fail-env-changed} option to mark the test as failed. Patch by Victor
Stinner.

@item 
bpo-43811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43811}: Tests multiple OpenSSL versions on GitHub Actions. Use ccache
to speed up testing.

@item 
bpo-43791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43791}: OpenSSL 3.0.0: Disable testing of legacy protocols TLS 1.0 and
1.1. Tests are failing with TLSV1_ALERT_INTERNAL_ERROR.
@end itemize

@node Build<32>,Windows<29>,Tests<30>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id276}@anchor{1857}
@subsubsection Build



@itemize -

@item 
bpo-43567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43567}: Improved generated code refresh (AST/tokens/opcodes/keywords)
on Windows.

@item 
bpo-43669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43669}: Implement 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/}. Python now requires OpenSSL 1.1.1 or
newer.
@end itemize

@node Windows<29>,macOS<23>,Build<32>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id277}@anchor{1858}
@subsubsection Windows



@itemize -

@item 
bpo-35306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35306}: Adds additional arguments to @ref{1859,,os.startfile()} function.

@item 
bpo-43538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43538}: Avoid raising errors from @ref{a04,,pathlib.Path.exists()} when
passed an invalid filename.

@item 
bpo-38822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38822}: Fixed @ref{48a,,os.stat()} failing on inaccessible directories with
a trailing slash, rather than falling back to the parent directory's
metadata. This implicitly affected @ref{9fc,,os.path.exists()} and
@ref{9fe,,os.path.isdir()}.

@item 
bpo-26227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26227}: Fixed decoding of host names in @ref{185a,,socket.gethostbyaddr()}
and @ref{185b,,socket.gethostbyname_ex()}.

@item 
bpo-40432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40432}: Updated pegen regeneration script on Windows to find and use
Python 3.8 or higher.  Prior to this, pegen regeneration already required
3.8 or higher, but the script may have used lower versions of Python.

@item 
bpo-43745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43745}: Actually updates Windows release to OpenSSL 1.1.1k. Earlier
releases were mislabelled and actually included 1.1.1i again.

@item 
bpo-43652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43652}: Update Tcl and Tk to 8.6.11 in Windows installer.

@item 
bpo-43492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43492}: Upgrade Windows installer to use SQLite 3.35.5.

@item 
bpo-30555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30555}: Fix @code{WindowsConsoleIO} errors in the presence of fd
redirection. Patch by Segev Finer.
@end itemize

@node macOS<23>,IDLE<20>,Windows<29>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id278}@anchor{185c}
@subsubsection macOS



@itemize -

@item 
bpo-42119@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42119}: Fix check for macOS SDK paths when building Python. Narrow
search to match contents of SDKs, namely only files in
@code{/System/Library}, @code{/System/IOSSupport}, and @code{/usr} other than
@code{/usr/local}. Previously, anything under @code{/System} was assumed to be
in an SDK which causes problems with the new file system layout in 10.15+
where user file systems may appear to be mounted under @code{/System}.  Paths
in @code{/Library} were also incorrectly treated as SDK locations.

@item 
bpo-43568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43568}: Drop support for MACOSX_DEPLOYMENT_TARGET < 10.3

@item 
bpo-44009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=44009}: Provide "python3.x-intel64" executable to allow reliably
forcing macOS universal2 framework builds to run under Rosetta 2 Intel-64
emulation on Apple Silicon Macs.  This can be useful for testing or when
universal2 wheels are not yet available.

@item 
bpo-43851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43851}: Build SQLite with @code{SQLITE_OMIT_AUTOINIT} on macOS. Patch by
Erlend E. Aasland.

@item 
bpo-43492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43492}: Update macOS installer to use SQLite 3.35.4.

@item 
bpo-42235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42235}: @code{Mac/BuildScript/build-installer.py} will now use
"--enable-optimizations" and @code{--with-lto} when building on macOS 10.15
or later.
@end itemize

@node IDLE<20>,C API<31>,macOS<23>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id279}@anchor{185d}
@subsubsection IDLE



@itemize -

@item 
bpo-37903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37903}: Add mouse actions to the shell sidebar.  Left click and
optional drag selects one or more lines, as with the editor line number
sidebar.  Right click after selecting raises a context menu with 'copy
with prompts'.  This zips together prompts from the sidebar with lines
from the selected text.

@item 
bpo-43981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43981}: Fix reference leak in test_sidebar and test_squeezer. Patches
by Terry Jan Reedy and Pablo Galindo

@item 
bpo-37892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37892}: Indent IDLE Shell input with spaces instead of tabs

@item 
bpo-43655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43655}: IDLE dialog windows are now recognized as dialogs by window
managers on macOS and X Window.

@item 
bpo-37903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37903}: IDLE's shell now shows prompts in a separate side-bar.
@end itemize

@node C API<31>,,IDLE<20>,Python 3 10 0 beta 1
@anchor{whatsnew/changelog id280}@anchor{185e}
@subsubsection C API



@itemize -

@item 
bpo-43916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43916}: Add a new @ref{56e,,Py_TPFLAGS_DISALLOW_INSTANTIATION} type
flag to disallow creating type instances. Patch by Victor Stinner.

@item 
bpo-43774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43774}: Remove the now unused @code{PYMALLOC_DEBUG} macro. Debug hooks on
memory allocators are now installed by default if Python is built in debug
mode (if @code{Py_DEBUG} macro is defined). Moreover, they can now be used on
Python build in release mode (ex: using @code{PYTHONMALLOC=debug} environment
variable).

@item 
bpo-43962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43962}: _PyInterpreterState_IDIncref() now calls
_PyInterpreterState_IDInitref() and always increments id_refcount.
Previously, calling _xxsubinterpreters.get_current() could create an
id_refcount inconsistency when a _xxsubinterpreters.InterpreterID object
was deallocated. Patch by Victor Stinner.

@item 
bpo-28254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28254}: Add new C-API functions to control the state of the garbage
collector: @ref{890,,PyGC_Enable()}, @ref{891,,PyGC_Disable()},
@ref{892,,PyGC_IsEnabled()}, corresponding to the functions in the
@ref{5f,,gc} module.

@item 
bpo-43908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43908}: Introduce @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} flag for
immutable type objects, and modify @ref{766,,PyType_Ready()} to set it for
static types. Patch by Erlend E. Aasland.

@item 
bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}: @ref{e96,,PyMem_Calloc()} is now available in the limited C API
(@code{Py_LIMITED_API}).

@item 
bpo-43868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43868}: @ref{572,,PyOS_ReadlineFunctionPointer()} is no longer exported by
limited C API headers and by @code{python3.dll} on Windows. Like any function
that takes @code{FILE*}, it is not part of the stable ABI.

@item 
bpo-43795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43795}: Stable ABI and limited API definitions are generated from a
central manifest (
@geindex Python Enhancement Proposals; PEP 652
PEP 652@footnote{https://peps.python.org/pep-0652/}).

@item 
bpo-43753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43753}: Add the @ref{88c,,Py_Is(x@comma{} y)} function to test if the
`x' object is the `y' object, the same as @code{x is y} in Python. Add also
the @ref{88d,,Py_IsNone()}, @ref{88e,,Py_IsTrue()}, @ref{88f,,Py_IsFalse()}
functions to test if an object is, respectively, the @code{None} singleton,
the @code{True} singleton or the @code{False} singleton. Patch by Victor
Stinner.
@end itemize

@node Python 3 10 0 alpha 7,Python 3 10 0 alpha 6,Python 3 10 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-7}@anchor{185f}
@subsection Python 3.10.0 alpha 7


`Release date: 2021-04-05'

@menu
* Security: Security<20>. 
* Core and Builtins: Core and Builtins<34>. 
* Library: Library<33>. 
* Documentation: Documentation<28>. 
* Tests: Tests<31>. 
* Build: Build<33>. 
* Windows: Windows<30>. 
* IDLE: IDLE<21>. 
* C API: C API<32>. 

@end menu

@node Security<20>,Core and Builtins<34>,,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id281}@anchor{1860}
@subsubsection Security



@itemize -

@item 
bpo-42988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42988}: 
@geindex Common Vulnerabilities and Exposures; CVE 2021-3426
CVE 2021-3426@footnote{https://www.cve.org/CVERecord?id=CVE-2021-3426}: Remove the @code{getfile} feature of the
@ref{b4,,pydoc} module which could be abused to read arbitrary files on the
disk (directory traversal vulnerability). Moreover, even source code of
Python modules can contain sensitive data like passwords. Vulnerability
reported by David Schwörer.

@item 
bpo-43285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43285}: @ref{5d,,ftplib} no longer trusts the IP address value returned
from the server in response to the PASV command by default.  This prevents
a malicious FTP server from using the response to probe IPv4 address and
port combinations on the client network.

Code that requires the former vulnerable behavior may set a
@code{trust_server_pasv_ipv4_address} attribute on their @ref{8e7,,ftplib.FTP}
instances to @code{True} to re-enable it.

@item 
bpo-43439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43439}: Add audit hooks for @ref{7ed,,gc.get_objects()},
@ref{7ee,,gc.get_referrers()} and @ref{7ef,,gc.get_referents()}. Patch by Pablo
Galindo.
@end itemize

@node Core and Builtins<34>,Library<33>,Security<20>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id282}@anchor{1861}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-27129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27129}: Update CPython bytecode magic number.

@item 
bpo-43672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43672}: Raise ImportWarning when calling find_loader().

@item 
bpo-43660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43660}: Fix crash that happens when replacing @code{sys.stderr} with a
callable that can remove the object while an exception is being printed.
Patch by Pablo Galindo.

@item 
bpo-27129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27129}: The bytecode interpreter uses instruction, rather byte, offsets
internally. This reduces the number of EXTENDED_ARG instructions needed
and streamlines instruction dispatch a bit.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: Fix reference leak in the @code{_hashopenssl} extension. Patch
by Pablo Galindo.

@item 
bpo-42134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42134}: Calls to find_module() by the import system now raise
ImportWarning.

@item 
bpo-41064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41064}: Improve the syntax error for invalid usage of double starred
elements ('**') in f-strings. Patch by Pablo Galindo.

@item 
bpo-43575@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43575}: Speed up calls to @code{map()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-42137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42137}: The import system now prefers using @code{__spec__} for
@code{ModuleType.__repr__} over @code{module_repr()}.

@item 
bpo-43452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43452}: Added micro-optimizations to @code{_PyType_Lookup()} to improve
cache lookup performance in the common case of cache hits.

@item 
bpo-43555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43555}: Report the column offset for @ref{18b,,SyntaxError} for invalid
line continuation characters. Patch by Pablo Galindo.

@item 
bpo-43517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43517}: Fix misdetection of circular imports when using @code{from pkg.mod
import attr}, which caused false positives in non-trivial multi-threaded
code.

@item 
bpo-43497@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43497}: Emit SyntaxWarnings for assertions with tuple constants, this
is a regression introduced in python3.7

@item 
bpo-39316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39316}: Tracing now has correct line numbers for attribute accesses
when the attribute is on a different line from the object. Improves
debugging and profiling for multi-line method chains.

@item 
bpo-35883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35883}: Python no longer fails at startup with a fatal error if a
command line argument contains an invalid Unicode character. The
@ref{bb5,,Py_DecodeLocale()} function now escapes byte sequences which would
be decoded as Unicode characters outside the [U+0000; U+10ffff] range.

@item 
bpo-43410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43410}: Fix a bug that was causing the parser to crash when emitting
syntax errors when reading input from stdin. Patch by Pablo Galindo

@item 
bpo-43406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43406}: Fix a possible race condition where @code{PyErr_CheckSignals}
tries to execute a non-Python signal handler.

@item 
bpo-42128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42128}: Add @code{__match_args__} to @ref{119c,,struct sequence objects}. Patch by Pablo Galindo.

@item 
bpo-43390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43390}: CPython now sets the @code{SA_ONSTACK} flag in @code{PyOS_setsig} for
the VM's default signal handlers.  This is friendlier to other in-process
code that an extension module or embedding use could pull in (such as
Golang's cgo) where tiny thread stacks are the norm and @code{sigaltstack()}
has been used to provide for signal handlers.  This is a no-op change for
the vast majority of processes that don't use sigaltstack.

@item 
bpo-43287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43287}: Speed up calls to @code{filter()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-37448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37448}: Add a radix tree based memory map to track in-use obmalloc
arenas. Use to replace the old implementation of address_in_range(). The
radix tree approach makes it easy to increase pool sizes beyond the OS
page size. Boosting the pool and arena size allows obmalloc to handle a
significantly higher percentage of requests from its ultra-fast paths.

It also has the advantage of eliminating the memory unsanitary behavior of
the previous address_in_range(). The old address_in_range() was marked
with the annotations _Py_NO_SANITIZE_ADDRESS, _Py_NO_SANITIZE_THREAD, and
_Py_NO_SANITIZE_MEMORY. Those annotations are no longer needed.

To disable the radix tree map, set a preprocessor flag as follows:
@code{-DWITH_PYMALLOC_RADIX_TREE=0}.

Co-authored-by: Tim Peters <@email{tim.peters@@gmail.com}>

@item 
bpo-29988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29988}: Only handle asynchronous exceptions and requests to drop the
GIL when returning from a call or on the back edges of loops. Makes sure
that @ref{12de,,__exit__()} is always called in with statements, even
for interrupts.
@end itemize

@node Library<33>,Documentation<28>,Core and Builtins<34>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id283}@anchor{1862}
@subsubsection Library



@itemize -

@item 
bpo-43720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43720}: Document various stdlib deprecations in imp, pkgutil, and
importlib.util for removal in Python 3.12.

@item 
bpo-43433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43433}: @ref{a45,,xmlrpc.client.ServerProxy} no longer ignores query and
fragment in the URL of the server.

@item 
bpo-31956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31956}: The @ref{7ca,,index()} method of @ref{19e,,array.array}
now has optional `start' and `stop' parameters.

@item 
bpo-40066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40066}: Enum: adjust @code{repr()} to show only enum and member name (not
value, nor angle brackets) and @code{str()} to show only member name.  Update
and improve documentation to match.

@item 
bpo-42136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42136}: Deprecate all module_repr() methods found in importlib as their
use is being phased out by Python 3.12.

@item 
bpo-35930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35930}: Raising an exception raised in a "future" instance will create
reference cycles.

@item 
bpo-41369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41369}: Finish updating the vendored libmpdec to version 2.5.1.  Patch
by Stefan Krah.

@item 
bpo-43422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43422}: Revert the _decimal C API which was added in bpo-41324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41324}.

@item 
bpo-43577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43577}: Fix deadlock when using @ref{291,,ssl.SSLContext} debug callback
with @ref{1863,,ssl.SSLContext.sni_callback()}.

@item 
bpo-43571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43571}: It's now possible to create MPTCP sockets with IPPROTO_MPTCP

@item 
bpo-43542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43542}: @code{image/heic} and @code{image/heif} were added to
@ref{8e,,mimetypes}.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: The @ref{69,,hmac} module now uses OpenSSL's HMAC implementation
when digestmod argument is a hash name or builtin hash function.

@item 
bpo-43510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43510}: Implement 
@geindex Python Enhancement Proposals; PEP 597
PEP 597@footnote{https://peps.python.org/pep-0597/}: Add @code{EncodingWarning} warning, @code{-X
warn_default_encoding} option, 
@geindex PYTHONWARNDEFAULTENCODING
@geindex variable d'environnement; PYTHONWARNDEFAULTENCODING
@ref{7a6,,PYTHONWARNDEFAULTENCODING}
environment variable and @code{encoding="locale"} argument value.

@item 
bpo-43521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43521}: @code{ast.unparse} can now render NaNs and empty sets.

@item 
bpo-42914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42914}: @ref{812,,pprint.pprint()} gains a new boolean
@code{underscore_numbers} optional argument to emit integers with thousands
separated by an underscore character for improved readability (for example
@code{1_000_000} instead of @code{1000000}).

@item 
bpo-41361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41361}: @ref{1864,,rotate()} calls are now slightly faster
due to faster argument parsing.

@item 
bpo-43423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43423}: @code{subprocess.communicate()} no longer raises an IndexError
when there is an empty stdout or stderr IO buffer during a timeout on
Windows.

@item 
bpo-27820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27820}: Fixed long-standing bug of smtplib.SMTP where doing AUTH LOGIN
with initial_response_ok=False will fail.

The cause is that SMTP.auth_login _always_ returns a password if provided
with a challenge string, thus non-compliant with the standard for AUTH
LOGIN.

Also fixes bug with the test for smtpd.

@item 
bpo-43445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43445}: Add frozen modules to @ref{82b,,sys.stdlib_module_names}. For
example, add @code{"_frozen_importlib"} and @code{"_frozen_importlib_external"}
names.

@item 
bpo-43245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43245}: Add keyword arguments support to @code{ChainMap.new_child()}.

@item 
bpo-29982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29982}: Add optional parameter `ignore_cleanup_errors' to
@ref{1212,,tempfile.TemporaryDirectory()} and allow multiple @code{cleanup()}
attempts. Contributed by C.A.M. Gerlach.

@item 
bpo-43428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43428}: Include changes from importlib_metadata 3.7@footnote{https://importlib-metadata.readthedocs.io/en/latest/history.html#v3-7-0}:

Performance enhancements to distribution discovery.

@code{entry_points} only returns unique distributions.

Introduces new @code{EntryPoints} object for containing a set of entry points
with convenience methods for selecting entry points by group or name.
@code{entry_points} now returns this object if selection parameters are
supplied but continues to return a dict object for compatibility. Users
are encouraged to rely on the selection interface. The dict object result
is likely to be deprecated in the future.

Added packages_distributions function to return a mapping of packages to
the distributions that provide them.

@item 
bpo-43332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43332}: Improves the networking efficiency of @ref{6e,,http.client} when
using a proxy via @code{set_tunnel()}.  Fewer small send
calls are made during connection setup.

@item 
bpo-43420@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43420}: Improve performance of @ref{1e4,,fractions.Fraction} arithmetics
for large components.  Contributed by Sergey B. Kirpichev.

@item 
bpo-43356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43356}: Allow passing a signal number to @code{_thread.interrupt_main()}.

@item 
bpo-43399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43399}: Fix @code{ElementTree.extend} not working on iterators when using
the Python implementation

@item 
bpo-43369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43369}: Improve @ref{ce,,sqlite3} error handling: If
@code{sqlite3_column_text()} and @code{sqlite3_column_blob()} set
@code{SQLITE_NOMEM}, @ref{164b,,MemoryError} is now raised. Patch by Erlend E.
Aasland.

@item 
bpo-43368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43368}: Fix a regression introduced in PR 24562, where an empty
bytestring was fetched as @code{None} instead of @code{b'@w{'}} in @ref{ce,,sqlite3}.
Patch by Mariusz Felisiak.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: Fixed stacklevel of @code{DeprecationWarning} emitted from
@code{import distutils}.

@item 
bpo-42129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42129}: @code{importlib.resources} now honors namespace packages, merging
resources from each location in the namespace as introduced in
@code{importlib_resources} 3.2 and including incidental changes through
5.0.3.

@item 
bpo-43295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43295}: @ref{1593,,datetime.datetime.strptime()} now raises @code{ValueError}
instead of @code{IndexError} when matching @code{'z'} with the @code{%z} format
specifier.

@item 
bpo-43125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43125}: Return empty string if base64mime.body_encode receive empty
bytes

@item 
bpo-43084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43084}: @ref{1865,,curses.window.enclose()} returns now @code{True} or @code{False}
(as was documented) instead of @code{1} or @code{0}.

@item 
bpo-42994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42994}: Add MIME types for opus, AAC, 3gpp and 3gpp2

@item 
bpo-14678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14678}: Add an invalidate_caches() method to the zipimport.zipimporter
class to support importlib.invalidate_caches(). Patch by Desmond Cheong.

@item 
bpo-42782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42782}: Fail fast in @ref{a4a,,shutil.move()} to avoid creating destination
directories on failure.

@item 
bpo-40066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40066}: Enum's @code{repr()} and @code{str()} have changed: @code{repr()} is now
`EnumClass.MemberName' and @code{str()} is `MemberName'.  Additionally,
stdlib Enum's whose contents are available as module attributes, such as
@code{RegexFlag.IGNORECASE}, have their @code{repr()} as `module.name', e.g.
@code{re.IGNORECASE}.

@item 
bpo-26053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26053}: Fixed bug where the @ref{a4,,pdb} interactive run command echoed
the args from the shell command line, even if those have been overridden
at the pdb prompt.

@item 
bpo-24160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24160}: Fixed bug where breakpoints did not persist across multiple
debugger sessions in @ref{a4,,pdb}'s interactive mode.

@item 
bpo-40701@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40701}: When the @ref{1866,,tempfile.tempdir} global variable is set to a
value of type bytes, it is now handled consistently.  Previously
exceptions could be raised from some tempfile APIs when the directory did
not already exist in this situation.  Also ensures that the
@ref{1867,,tempfile.gettempdir()} and @ref{1868,,tempfile.gettempdirb()} functions
`always' return @code{str} and @code{bytes} respectively.

@item 
bpo-39342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39342}: Expose @code{X509_V_FLAG_ALLOW_PROXY_CERTS} as
@ref{1869,,VERIFY_ALLOW_PROXY_CERTS} to allow proxy certificate
validation as explained in
@indicateurl{https://docs.openssl.org/1.1.1/man7/proxy-certificates/}.

@item 
bpo-31861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31861}: Add builtins.aiter and builtins.anext. Patch by Joshua Bronson
(@@jab), Daniel Pope (@@lordmauve), and Justin Wang (@@justin39).
@end itemize

@node Documentation<28>,Tests<31>,Library<33>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id284}@anchor{186a}
@subsubsection Documentation



@itemize -

@item 
bpo-43199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43199}: Answer "Why is there no goto?" in the Design and History FAQ.

@item 
bpo-43407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43407}: Clarified that a result from @ref{250,,time.monotonic()},
@ref{a76,,time.perf_counter()}, @ref{a77,,time.process_time()}, or
@ref{923,,time.thread_time()} can be compared with the result from any
following call to the same function - not just the next immediate call.

@item 
bpo-43354@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43354}: Fix type documentation for @code{Fault.faultCode}; the type has to
be @code{int} instead of @code{str}.

@item 
bpo-41933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41933}: Clarified wording of s * n in the Common Sequence Operations
@end itemize

@node Tests<31>,Build<33>,Documentation<28>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id285}@anchor{186b}
@subsubsection Tests



@itemize -

@item 
bpo-37945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37945}: Fix test_getsetlocale_issue1813() of test_locale: skip the test
if @code{setlocale()} fails. Patch by Victor Stinner.

@item 
bpo-41561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41561}: Add workaround for Ubuntu's custom OpenSSL security level
policy.
@end itemize

@node Build<33>,Windows<30>,Tests<31>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id286}@anchor{186c}
@subsubsection Build



@itemize -

@item 
bpo-43179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43179}: Introduce and correctly use ALIGNOF_X in place of SIZEOF_X for
alignment-related code in optimized string routines. Patch by Jessica
Clarke.

@item 
bpo-43631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43631}: Update macOS, Windows, and CI to OpenSSL 1.1.1k.

@item 
bpo-43617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43617}: Improve configure.ac: Check for presence of autoconf-archive
package and remove our copies of M4 macros.

@item 
bpo-43466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43466}: The @code{configure} script now supports @code{--with-openssl-rpath}
option.

@item 
bpo-43372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43372}: Use @code{_freeze_importlib} to generate code for the
@code{__hello__} module. This approach ensures the code matches the
interpreter version.  Previously, PYTHON_FOR_REGEN was used to generate
the code, which might be wrong.  The marshal format for code objects has
changed with bpo-42246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42246}, commit 877df851. Update the code and the expected
code sizes in ctypes test_frozentable.
@end itemize

@node Windows<30>,IDLE<21>,Build<33>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id287}@anchor{186d}
@subsubsection Windows



@itemize -

@item 
bpo-43440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43440}: Build @ref{ce,,sqlite3} with the @code{R*Tree} module enabled. Patch
by Erlend E. Aasland.
@end itemize

@node IDLE<21>,C API<32>,Windows<30>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id288}@anchor{186e}
@subsubsection IDLE



@itemize -

@item 
bpo-42225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42225}: Document that IDLE can fail on Unix either from misconfigured
IP masquerade rules or failure displaying complex colored (non-ascii)
characters.
@end itemize

@node C API<32>,,IDLE<21>,Python 3 10 0 alpha 7
@anchor{whatsnew/changelog id289}@anchor{186f}
@subsubsection C API



@itemize -

@item 
bpo-43688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43688}: The limited C API is now supported if Python is built in debug
mode (if the @code{Py_DEBUG} macro is defined). In the limited C API, the
@ref{55a,,Py_INCREF()} and @ref{55b,,Py_DECREF()} functions are now implemented
as opaque function calls, rather than accessing directly the
@ref{88b,,PyObject.ob_refcnt} member, if Python is built in debug mode
and the @code{Py_LIMITED_API} macro targets Python 3.10 or newer. It became
possible to support the limited C API in debug mode because the
@ref{32f,,PyObject} structure is the same in release and debug mode since
Python 3.8 (see bpo-36465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36465}).

The limited C API is still not supported in the @code{--with-trace-refs}
special build (@code{Py_TRACE_REFS} macro).

Patch by Victor Stinner.

@item 
bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}: Remove the @code{pyarena.h} header file with functions:


@itemize *

@item 
@code{PyArena_New()}

@item 
@code{PyArena_Free()}

@item 
@code{PyArena_Malloc()}

@item 
@code{PyArena_AddPyObject()}
@end itemize

These functions were undocumented, excluded from the limited C API, and
were only used internally by the compiler. Patch by Victor Stinner.

@item 
bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}: Remove the compiler and parser functions using @code{struct _mod}
type, because the public AST C API was removed:


@itemize *

@item 
@code{PyAST_Compile()}

@item 
@code{PyAST_CompileEx()}

@item 
@code{PyAST_CompileObject()}

@item 
@code{PyFuture_FromAST()}

@item 
@code{PyFuture_FromASTObject()}

@item 
@code{PyParser_ASTFromFile()}

@item 
@code{PyParser_ASTFromFileObject()}

@item 
@code{PyParser_ASTFromFilename()}

@item 
@code{PyParser_ASTFromString()}

@item 
@code{PyParser_ASTFromStringObject()}
@end itemize

These functions were undocumented and excluded from the limited C API.
Patch by Victor Stinner.

@item 
bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}: Remove @code{ast.h}, @code{asdl.h}, and @code{Python-ast.h} header
files. These functions were undocumented and excluded from the limited C
API. Most names defined by these header files were not prefixed by @code{Py}
and so could create names conflicts. For example, @code{Python-ast.h} defined
a @code{Yield} macro which was conflict with the @code{Yield} name used by the
Windows @code{<winbase.h>} header. Use the Python @ref{8,,ast} module instead.
Patch by Victor Stinner.

@item 
bpo-43541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43541}: Fix a @code{PyEval_EvalCodeEx()} regression: fix reference
counting on builtins. Patch by Victor Stinner.

@item 
bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}: Remove the @code{symtable.h} header file and the undocumented
functions:


@itemize *

@item 
@code{PyST_GetScope()}

@item 
@code{PySymtable_Build()}

@item 
@code{PySymtable_BuildObject()}

@item 
@code{PySymtable_Free()}

@item 
@code{Py_SymtableString()}

@item 
@code{Py_SymtableStringObject()}
@end itemize

The @code{Py_SymtableString()} function was part the stable ABI by mistake
but it could not be used, because the @code{symtable.h} header file was
excluded from the limited C API.

The Python @ref{d7,,symtable} module remains available and is unchanged.

Patch by Victor Stinner.

@item 
bpo-43244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43244}: Remove the @code{PyAST_Validate()} function. It is no longer
possible to build a AST object (@code{mod_ty} type) with the public C API.
The function was already excluded from the limited C API (
@geindex Python Enhancement Proposals; PEP 384
PEP 384@footnote{https://peps.python.org/pep-0384/}).
Patch by Victor Stinner.
@end itemize

@node Python 3 10 0 alpha 6,Python 3 10 0 alpha 5,Python 3 10 0 alpha 7,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-6}@anchor{1870}
@subsection Python 3.10.0 alpha 6


`Release date: 2021-03-01'

@menu
* Security: Security<21>. 
* Core and Builtins: Core and Builtins<35>. 
* Library: Library<34>. 
* Documentation: Documentation<29>. 
* Tests: Tests<32>. 
* Build: Build<34>. 
* Windows: Windows<31>. 
* macOS: macOS<24>. 
* IDLE: IDLE<22>. 
* C API: C API<33>. 

@end menu

@node Security<21>,Core and Builtins<35>,,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id290}@anchor{1871}
@subsubsection Security



@itemize -

@item 
bpo-42967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42967}: Fix web cache poisoning vulnerability by defaulting the query
args separator to @code{&}, and allowing the user to choose a custom
separator.
@end itemize

@node Core and Builtins<35>,Library<34>,Security<21>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id291}@anchor{1872}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-43321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43321}: Fix @code{SystemError} raised when @code{PyArg_Parse*()} is used with
@code{#} but without @code{PY_SSIZE_T_CLEAN} defined.

@item 
bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}: @code{PyArg_Parse*()} functions now emits @code{DeprecationWarning}
when @code{u} or @code{Z} format is used. See 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/} for detail.

@item 
bpo-43277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43277}: Add a new @ref{889,,PySet_CheckExact()} function to the C-API to
check if an object is an instance of @ref{5c3,,set} but not an instance of a
subtype. Patch by Pablo Galindo.

@item 
bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}: The @ref{86f,,types.FunctionType} constructor now inherits the
current builtins if the `globals' dictionary has no @code{"__builtins__"}
key, rather than using @code{@{"None": None@}} as builtins: same behavior as
@ref{17e,,eval()} and @ref{17d,,exec()} functions. Defining a function with @code{def
function(...): ...} in Python is not affected, globals cannot be
overridden with this syntax: it also inherits the current builtins. Patch
by Victor Stinner.

@item 
bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}: Functions have a new @code{__builtins__} attribute which is used
to look for builtin symbols when a function is executed, instead of
looking into @code{__globals__['__builtins__']}. Patch by Mark Shannon and
Victor Stinner.

@item 
bpo-43149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43149}: Improve the error message in the parser for exception groups
without parentheses. Patch by Pablo Galindo.

@item 
bpo-43121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43121}: Fixed an incorrect @ref{18b,,SyntaxError} message for missing comma
in literals. Patch by Pablo Galindo.

@item 
bpo-42819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42819}: @ref{b9,,readline}: Explicitly disable bracketed paste in the
interactive interpreter, even if it's set in the inputrc, is enabled by
default (eg GNU Readline 8.1), or a user calls
@code{readline.read_init_file()}. The Python REPL has not implemented
bracketed paste support. Also, bracketed mode writes the @code{"\x1b[?2004h"}
escape sequence into stdout which causes test failures in applications
that don't support it. It can still be explicitly enabled by calling
@code{readline.parse_and_bind("set enable-bracketed-paste on")}. Patch by
Dustin Rodrigues.

@item 
bpo-42808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42808}: Simple calls to @code{type(object)} are now faster due to the
@code{vectorcall} calling convention. Patch by Dennis Sweeney.

@item 
bpo-42217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42217}: Make the compiler merges same co_code and co_linetable objects
in a module like already did for co_consts.

@item 
bpo-41972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41972}: Substring search functions such as @code{str1 in str2} and
@code{str2.find(str1)} now sometimes use the "Two-Way" string comparison
algorithm to avoid quadratic behavior on long strings.

@item 
bpo-42128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42128}: Implement 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} (structural pattern matching). Patch by
Brandt Bucher.

@item 
bpo-40692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40692}: In the @ref{8db,,concurrent.futures.ProcessPoolExecutor},
validate that @code{multiprocess.synchronize()} is available on a given
platform and rely on that check in the @ref{21,,concurrent.futures} test
suite so we can run tests that are unrelated to
@code{ProcessPoolExecutor} on those platforms.

@item 
bpo-38302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38302}: If @ref{7bb,,object.__ipow__()} returns @ref{7bc,,NotImplemented}, the
operator will correctly fall back to @ref{7bd,,object.__pow__()} and
@ref{7be,,object.__rpow__()} as expected.
@end itemize

@node Library<34>,Documentation<29>,Core and Builtins<35>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id292}@anchor{1873}
@subsubsection Library



@itemize -

@item 
bpo-43316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43316}: The @code{python -m gzip} command line application now properly
fails when detecting an unsupported extension. It exits with a non-zero
exit code and prints an error message to stderr.

@item 
bpo-43317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43317}: Set the chunk size for the @code{gzip} module main function to
io.DEFAULT_BUFFER_SIZE. This is slightly faster than the 1024 bytes
constant that was used previously.

@item 
bpo-43146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43146}: Handle None in single-arg versions of
@ref{839,,print_exception()} and
@ref{837,,format_exception()}.

@item 
bpo-43260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43260}: Fix TextIOWrapper can not flush internal buffer forever after
very large text is written.

@item 
bpo-43258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43258}: Prevent needless allocation of @ref{ce,,sqlite3} aggregate
function context when no rows match an aggregate query. Patch by Erlend E.
Aasland.

@item 
bpo-43251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43251}: Improve @ref{ce,,sqlite3} error handling:
@code{sqlite3_column_name()} failures now result in @ref{164b,,MemoryError}. Patch
by Erlend E. Aasland.

@item 
bpo-40956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40956}: Fix segfault in @ref{b68,,sqlite3.Connection.backup()} if no
argument was provided. The regression was introduced by PR 23838. Patch by
Erlend E. Aasland.

@item 
bpo-43172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43172}: The readline module now passes its tests when built directly
against libedit. Existing irreconcilable API differences remain in
@ref{1874,,readline.get_begidx()} and @ref{1875,,readline.get_endidx()} behavior based
on libreadline vs libedit use.

@item 
bpo-43163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43163}: Fix a bug in @ref{1c,,codeop} that was causing it to not ask for
more input when multi-line snippets have unclosed parentheses. Patch by
Pablo Galindo

@item 
bpo-43162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43162}: deprecate unsupported ability to access enum members as
attributes of other enum members

@item 
bpo-43146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43146}: Fix recent regression in None argument handling in
@ref{fd,,traceback} module functions.

@item 
bpo-43102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43102}: The namedtuple __new__ method had its __builtins__ set to None
instead of an actual dictionary.  This created problems for introspection
tools.

@item 
bpo-43106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43106}: Added @ref{804,,O_EVTONLY}, @ref{805,,O_FSYNC},
@ref{806,,O_SYMLINK} and @ref{807,,O_NOFOLLOW_ANY} for macOS. Patch by
Donghee Na.

@item 
bpo-42960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42960}: Adds @ref{1876,,resource.RLIMIT_KQUEUES} constant from FreeBSD to
the @ref{bb,,resource} module.

@item 
bpo-42151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42151}: Make the pure Python implementation of
@ref{124,,xml.etree.ElementTree} behave the same as the C implementation
(@code{_elementree}) regarding default attribute values (by not setting
@code{specified_attributes=1}).

@item 
bpo-29753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29753}: In ctypes, now packed bitfields are calculated properly and the
first item of packed bitfields is now shrank correctly.
@end itemize

@node Documentation<29>,Tests<32>,Library<34>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id293}@anchor{1877}
@subsubsection Documentation



@itemize -

@item 
bpo-27646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27646}: Clarify that 'yield from <expr>' works with any iterable, not
just iterators.

@item 
bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}: Update some deprecated unicode APIs which are documented as
"will be removed in 4.0" to "3.12". See 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/} for detail.
@end itemize

@node Tests<32>,Build<34>,Documentation<29>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id294}@anchor{1878}
@subsubsection Tests



@itemize -

@item 
bpo-43288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43288}: Fix test_importlib to correctly skip Unicode file tests if the
filesystem does not support them.
@end itemize

@node Build<34>,Windows<31>,Tests<32>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id295}@anchor{1879}
@subsubsection Build



@itemize -

@item 
bpo-43174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43174}: Windows build now uses @code{/utf-8} compiler option.

@item 
bpo-43103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43103}: Add a new configure @code{--without-static-libpython} option to
not build the @code{libpythonMAJOR.MINOR.a} static library and not install
the @code{python.o} object file.

@item 
bpo-13501@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13501}: The configure script can now use `libedit' instead of
`readline' with the command line option @code{--with-readline=editline}.

@item 
bpo-42603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42603}: Make configure script use pkg-config to detect the location of
Tcl/Tk headers and libraries, used to build tkinter.

On macOS, a Tcl/Tk configuration provided by pkg-config will be preferred
over Tcl/Tk frameworks installed in @code{/@{System/,@}Library/Frameworks}. If
both exist and the latter is preferred, the appropriate @code{--with-tcltk-*}
configuration options need to be explicitly set.

@item 
bpo-39448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39448}: Add the "regen-frozen" makefile target that regenerates the
code for the frozen @code{__hello__} module.
@end itemize

@node Windows<31>,macOS<24>,Build<34>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id296}@anchor{187a}
@subsubsection Windows



@itemize -

@item 
bpo-43155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43155}: @ref{187b,,PyCMethod_New()} is now present in @code{python3.lib}.
@end itemize

@node macOS<24>,IDLE<22>,Windows<31>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id297}@anchor{187c}
@subsubsection macOS



@itemize -

@item 
bpo-41837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41837}: Update macOS installer build to use OpenSSL 1.1.1j.
@end itemize

@node IDLE<22>,C API<33>,macOS<24>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id298}@anchor{187d}
@subsubsection IDLE



@itemize -

@item 
bpo-43283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43283}: Document why printing to IDLE's Shell is often slower than
printing to a system terminal and that it can be made faster by
pre-formatting a single string before printing.
@end itemize

@node C API<33>,,IDLE<22>,Python 3 10 0 alpha 6
@anchor{whatsnew/changelog id299}@anchor{187e}
@subsubsection C API



@itemize -

@item 
bpo-43278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43278}: Always put compiler and system information on the first line of
the REPL welcome message.

@item 
bpo-43270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43270}: Remove the private @code{_PyErr_OCCURRED()} macro: use the public
@ref{187f,,PyErr_Occurred()} function instead.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: Move odictobject.h, parser_interface.h, picklebufobject.h,
pydebug.h, and pyfpe.h into the cpython/ directory. They must not be
included directly, as they are already included by Python.h: @ref{76e,,Include Files}.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: Move pyarena.h, pyctype.h, and pytime.h into the cpython/
directory. They must not be included directly, as they are already
included by Python.h: @ref{76e,,Include Files}.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @code{PyExceptionClass_Name()} is now always declared as a
function, in order to hide implementation details. The macro accessed
@ref{1880,,PyTypeObject.tp_name} directly.  Patch by Erlend E. Aasland.

@item 
bpo-43239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43239}: The @ref{1881,,PyCFunction_New()} function is now exported in the
ABI when compiled with @code{-fvisibility=hidden}.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @ref{1882,,PyIter_Check()} is now always declared as a function, in
order to hide implementation details. The macro accessed
@ref{14a5,,PyTypeObject.tp_iternext} directly. Patch by Erlend E. Aasland.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{1883,,PyDescr_IsData()} macro to a function to hide
implementation details: The macro accessed
@ref{1884,,PyTypeObject.tp_descr_set} directly. Patch by Erlend E.
Aasland.

@item 
bpo-43181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43181}: Convert @ref{1885,,PyObject_TypeCheck()} macro to a static inline
function. Patch by Erlend E. Aasland.
@end itemize

@node Python 3 10 0 alpha 5,Python 3 10 0 alpha 4,Python 3 10 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-5}@anchor{1886}
@subsection Python 3.10.0 alpha 5


`Release date: 2021-02-02'

@menu
* Security: Security<22>. 
* Core and Builtins: Core and Builtins<36>. 
* Library: Library<35>. 
* Documentation: Documentation<30>. 
* Tests: Tests<33>. 
* Build: Build<35>. 
* Windows: Windows<32>. 
* macOS: macOS<25>. 
* IDLE: IDLE<23>. 
* C API: C API<34>. 

@end menu

@node Security<22>,Core and Builtins<36>,,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id300}@anchor{1887}
@subsubsection Security



@itemize -

@item 
bpo-42938@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42938}: Avoid static buffers when computing the repr of
@ref{1888,,ctypes.c_double} and @ref{1889,,ctypes.c_longdouble} values.
@end itemize

@node Core and Builtins<36>,Library<35>,Security<22>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id301}@anchor{188a}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-42990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42990}: Refactor the @code{PyEval_} family of functions.


@itemize *

@item 
An new function @code{_PyEval_Vector} is added to simplify calls to Python from C.

@item 
@code{_PyEval_EvalCodeWithName} is removed

@item 
@code{PyEval_EvalCodeEx} is retained as part of the API, but is not used internally
@end itemize

@item 
bpo-38631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38631}: Replace @ref{970,,Py_FatalError()} calls in the compiler with
regular @ref{561,,SystemError} exceptions. Patch by Victor Stinner.

@item 
bpo-42997@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42997}: Improve error message for missing ":" before blocks. Patch by
Pablo Galindo.

@item 
bpo-43017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43017}: Improve error message in the parser when using un-parenthesised
tuples in comprehensions. Patch by Pablo Galindo.

@item 
bpo-42986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42986}: Fix parser crash when reporting syntax errors in f-string with
newlines. Patch by Pablo Galindo.

@item 
bpo-40176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40176}: Syntax errors for unterminated string literals now point to the
start of the string instead of reporting EOF/EOL.

@item 
bpo-42927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42927}: The inline cache for @code{LOAD_ATTR} now also optimizes access to
attributes defined by @code{__slots__}. This makes reading such attribute up
to 30% faster.

@item 
bpo-42864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42864}: Improve error messages in the parser when parentheses are not
closed. Patch by Pablo Galindo.

@item 
bpo-42924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42924}: Fix @code{bytearray} repetition incorrectly copying data from the
start of the buffer, even if the data is offset within the buffer (e.g.
after reassigning a slice at the start of the @code{bytearray} to a shorter
byte string).

@item 
bpo-42882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42882}: Fix the @code{_PyUnicode_FromId()} function
(_Py_IDENTIFIER(var) API) when @ref{899,,Py_Initialize()} /
@ref{1330,,Py_Finalize()} is called multiple times: preserve
@code{_PyRuntime.unicode_ids.next_index} value.

@item 
bpo-42827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42827}: Fix a crash when working out the error line of a
@ref{18b,,SyntaxError} in some multi-line expressions.

@item 
bpo-42823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42823}: frame.f_lineno is correct even if frame.f_trace is set to True

@item 
bpo-37324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37324}: Remove deprecated aliases to
@ref{863,,Classes de base abstraites de collections} from the @ref{1d,,collections}
module.

@item 
bpo-41994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41994}: Fixed possible leak in @code{import} when @code{sys.modules} is not a
@code{dict}.

@item 
bpo-27772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27772}: In string formatting, preceding the `width' field by @code{'0'} no
longer affects the default alignment for strings.
@end itemize

@node Library<35>,Documentation<30>,Core and Builtins<36>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id302}@anchor{188b}
@subsubsection Library



@itemize -

@item 
bpo-43108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43108}: Fixed a reference leak in the @ref{2b,,curses} module. Patch by
Pablo Galindo

@item 
bpo-43077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43077}: Update the bundled pip to 21.0.1 and setuptools to 52.0.0.

@item 
bpo-41282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41282}: Deprecate @code{distutils} in documentation and add warning on
import.

@item 
bpo-43014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43014}: Improve performance of @ref{fa,,tokenize} by 20-30%.  Patch by
Anthony Sottile.

@item 
bpo-42323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42323}: Fix @ref{482,,math.nextafter()} for NaN on AIX.

@item 
bpo-42955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42955}: Add @ref{82b,,sys.stdlib_module_names}, containing the list of the
standard library module names. Patch by Victor Stinner.

@item 
bpo-42944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42944}: Fix @code{random.Random.sample} when @code{counts} argument is not
@code{None}.

@item 
bpo-42934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42934}: Use @ref{259,,TracebackException}'s new @code{compact}
param in @ref{1147,,TestResult} to reduce time and memory consumed
by traceback formatting.

@item 
bpo-42931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42931}: Add @code{randbytes()} to @code{random.__all__}.

@item 
bpo-38250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38250}: [Enum] Flags consisting of a single bit are now considered
canonical, and will be the only flags returned from listing and iterating
over a Flag class or a Flag member.  Multi-bit flags are considered
aliases; they will be returned from lookups and operations that result in
their value. Iteration for both Flag and Flag members is in definition
order.

@item 
bpo-42877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42877}: Added the @code{compact} parameter to the constructor of
@ref{259,,traceback.TracebackException} to reduce time and memory for use
cases that only need to call @code{TracebackException.format()} and
@code{TracebackException.format_exception_only()}.

@item 
bpo-42923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42923}: The @ref{970,,Py_FatalError()} function and the
@ref{57,,faulthandler} module now dump the list of extension modules on a
fatal error.

@item 
bpo-42848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42848}: Removed recursion from @ref{259,,TracebackException}
to allow it to handle long exception chains.

@item 
bpo-42901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42901}: [Enum] move member creation from @code{EnumMeta.__new__} to
@code{_proto_member.__set_name__}, allowing members to be created and visible
in @code{__init_subclass__}.

@item 
bpo-42780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42780}: Fix os.set_inheritable() for O_PATH file descriptors on Linux.

@item 
bpo-42866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42866}: Fix a reference leak in the @code{getcodec()} function of CJK
codecs. Patch by Victor Stinner.

@item 
bpo-42846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42846}: Convert the 6 CJK codec extension modules (_codecs_cn,
_codecs_hk, _codecs_iso2022, _codecs_jp, _codecs_kr and _codecs_tw) to the
multiphase initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}). Patch by Victor Stinner.

@item 
bpo-42851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42851}: remove __init_subclass__ support for Enum members

@item 
bpo-42834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42834}: Make internal caches of the @code{_json} module compatible with
subinterpreters.

@item 
bpo-41748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41748}: Fix HTMLParser parsing rules for element attributes containing
commas with spaces. Patch by Karl Dubost.

@item 
bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}: Require SQLite 3.7.15 or newer. Patch by Erlend E. Aasland.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Convert the _multibytecodec extension module (CJK codecs) to
multi-phase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).  Patch by Erlend E. Aasland.

@item 
bpo-42802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42802}: The distutils @code{bdist_wininst} command deprecated in Python
3.8 has been removed. The distutils @code{bdist_wheel} command is now
recommended to distribute binary packages on Windows.

@item 
bpo-24464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24464}: The undocumented built-in function
@code{sqlite3.enable_shared_cache} is now deprecated, scheduled for removal
in Python 3.12.  Its use is strongly discouraged by the SQLite3
documentation.  Patch by Erlend E. Aasland.

@item 
bpo-42384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42384}: Make pdb populate sys.path[0] exactly the same as regular
python execution.

@item 
bpo-42383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42383}: Fix pdb: previously pdb would fail to restart the debugging
target if it was specified using a relative path and the current directory
changed.

@item 
bpo-42005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42005}: Fix CLI of @ref{27,,cProfile} and @ref{ae,,profile} to catch
@ref{1045,,BrokenPipeError}.

@item 
bpo-41604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41604}: Don't decrement the reference count of the previous user_ptr
when set_panel_userptr fails.

@item 
bpo-41149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41149}: Allow executing callables that have a boolean value of
@code{False} when passed to @code{Threading.thread} as the target. Patch
contributed by Barney Stratford.

@item 
bpo-38307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38307}: Add an 'end_lineno' attribute to the Class and Function objects
that appear in the tree returned by pyclbr functions.  This and the
existing 'lineno' attribute define the extent of class and def statements.
Patch by Aviral Srivastava.

@item 
bpo-39273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39273}: The @code{BUTTON5_*} constants are now exposed in the
@ref{2b,,curses} module if available.

@item 
bpo-33289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33289}: Correct call to @ref{f0,,tkinter.colorchooser} to return RGB
triplet of ints instead of floats.  Patch by Cheryl Sabella.
@end itemize

@node Documentation<30>,Tests<33>,Library<35>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id303}@anchor{188c}
@subsubsection Documentation



@itemize -

@item 
bpo-40304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40304}: Fix doc for type(name, bases, dict).  Patch by Boris
Verkhovskiy and Éric Araujo.

@item 
bpo-42811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42811}: Updated importlib.util.resolve_name() doc to use
__spec__.parent instead of __package__. (Thanks Yair Frid.)
@end itemize

@node Tests<33>,Build<35>,Documentation<30>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id304}@anchor{188d}
@subsubsection Tests



@itemize -

@item 
bpo-40823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40823}: Use @code{unittest.TestLoader().loadTestsFromTestCase()} instead
of @code{unittest.makeSuite()} in @ref{ce,,sqlite3} tests. Patch by Erlend E.
Aasland.

@item 
bpo-40810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40810}: In @ref{ce,,sqlite3}, fix @code{CheckTraceCallbackContent} for SQLite
pre 3.7.15.
@end itemize

@node Build<35>,Windows<32>,Tests<33>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id305}@anchor{188e}
@subsubsection Build



@itemize -

@item 
bpo-43031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43031}: Pass @code{--timeout=$(TESTTIMEOUT)} option to the default profile
task @code{./python -m test --pgo} command.

@item 
bpo-36143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36143}: @code{make regen-all} now also runs @code{regen-keyword}. Patch by
Victor Stinner.

@item 
bpo-42874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42874}: Removed the grep -q and -E flags in the tzpath validation
section of the configure script to better accommodate users of some
platforms (specifically Solaris 10).

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Add library search path by wr-cc in add_cross_compiling_paths()
for VxWorks.

@item 
bpo-42856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42856}: Add @code{--with-wheel-pkg-dir=PATH} option to the @code{./configure}
script. If specified, the @ref{54,,ensurepip} module looks for @code{setuptools}
and @code{pip} wheel packages in this directory: if both are present, these
wheel packages are used instead of ensurepip bundled wheel packages.

Some Linux distribution packaging policies recommend against bundling
dependencies. For example, Fedora installs wheel packages in the
@code{/usr/share/python-wheels/} directory and don't install the
@code{ensurepip._bundled} package.
@end itemize

@node Windows<32>,macOS<25>,Build<35>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id306}@anchor{188f}
@subsubsection Windows



@itemize -

@item 
bpo-41837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41837}: Updated Windows installer to include OpenSSL 1.1.1i

@item 
bpo-42584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42584}: Upgrade Windows installer to use SQLite 3.34.0.
@end itemize

@node macOS<25>,IDLE<23>,Windows<32>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id307}@anchor{1890}
@subsubsection macOS



@itemize -

@item 
bpo-42504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42504}: Ensure that the value of
sysconfig.get_config_var('MACOSX_DEPLOYMENT_TARGET') is always a string,
even in when the value is parsable as an integer.
@end itemize

@node IDLE<23>,C API<34>,macOS<25>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id308}@anchor{1891}
@subsubsection IDLE



@itemize -

@item 
bpo-43008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43008}: Make IDLE invoke @ref{7f5,,sys.excepthook()} in normal, 2-process
mode. Patch by Ken Hilton.

@item 
bpo-33065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33065}: Fix problem debugging user classes with __repr__ method.

@item 
bpo-23544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23544}: Disable Debug=>Stack Viewer when user code is running or
Debugger is active, to prevent hang or crash.  Patch by Zackery Spytz.

@item 
bpo-32631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32631}: Finish zzdummy example extension module: make menu entries
work; add docstrings and tests with 100% coverage.
@end itemize

@node C API<34>,,IDLE<23>,Python 3 10 0 alpha 5
@anchor{whatsnew/changelog id309}@anchor{1892}
@subsubsection C API



@itemize -

@item 
bpo-42979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42979}: When Python is built in debug mode (with C assertions), calling
a type slot like @code{sq_length} (@code{__len__()} in Python) now fails with a
fatal error if the slot succeeded with an exception set, or failed with no
exception set. The error message contains the slot, the type name, and the
current exception (if an exception is set). Patch by Victor Stinner.

@item 
bpo-43030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=43030}: Fixed a compiler warning in @ref{1893,,Py_UNICODE_ISSPACE()} on
platforms with signed @code{wchar_t}.
@end itemize

@node Python 3 10 0 alpha 4,Python 3 10 0 alpha 3,Python 3 10 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-4}@anchor{1894}
@subsection Python 3.10.0 alpha 4


`Release date: 2021-01-04'

@menu
* Core and Builtins: Core and Builtins<37>. 
* Library: Library<36>. 
* Documentation: Documentation<31>. 
* Tests: Tests<34>. 
* Build: Build<36>. 
* macOS: macOS<26>. 
* Tools/Demos: Tools/Demos<16>. 
* C API: C API<35>. 

@end menu

@node Core and Builtins<37>,Library<36>,,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id310}@anchor{1895}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-42814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42814}: Fix undefined behavior in @code{Objects/genericaliasobject.c}.

@item 
bpo-42806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42806}: Fix the column offsets for f-strings @ref{8,,ast} nodes
surrounded by parentheses and for nodes that spawn multiple lines. Patch
by Pablo Galindo.

@item 
bpo-40631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40631}: Fix regression where a single parenthesized starred expression
was a valid assignment target.

@item 
bpo-27794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27794}: Improve the error message for failed writes/deletes to property
objects. When possible, the attribute name is now shown. Patch provided by
Yurii Karabas.

@item 
bpo-42745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42745}: Make the type attribute lookup cache per-interpreter. Patch by
Victor Stinner.

@item 
bpo-42246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42246}: Jumps to jumps are not eliminated when it would break PEP 626.

@item 
bpo-42246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42246}: Make sure that the @code{f_lasti} and @code{f_lineno} attributes of a
frame are set correctly when an exception is raised or re-raised. Required
for PEP 626.

@item 
bpo-32381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32381}: The coding cookie (ex: @code{# coding: latin1}) is now ignored in
the command passed to the @ref{5ca,,-c} command line option. Patch by
Victor Stinner.

@item 
bpo-30858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30858}: Improve error location in expressions that contain assignments.
Patch by Pablo Galindo and Lysandros Nikolaou.

@item 
bpo-42615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42615}: Remove jump commands made redundant by the deletion of
unreachable bytecode blocks

@item 
bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}: Make the @ref{c,,atexit} module state per-interpreter. It is now
safe have more than one @ref{c,,atexit} module instance. Patch by Donghee Na
and Victor Stinner.

@item 
bpo-32381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32381}: Fix encoding name when running a @code{.pyc} file on Windows:
@ref{1896,,PyRun_SimpleFileExFlags()} now uses the correct encoding to
decode the filename.

@item 
bpo-42195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42195}: The @code{__args__} of the parameterized generics for
@ref{7af,,typing.Callable} and @ref{7d4,,collections.abc.Callable} are now
consistent.  The @code{__args__} for @ref{7d4,,collections.abc.Callable} are
now flattened while @ref{7af,,typing.Callable}'s have not changed.  To allow
this change, @ref{7d5,,types.GenericAlias} can now be subclassed and
@code{collections.abc.Callable}'s @code{__class_getitem__} will now return a
subclass of @code{types.GenericAlias}.  Tests for typing were also updated to
not subclass things like @code{Callable[..., T]} as that is not a valid base
class.  Finally, both @code{Callable}s no longer validate their
@code{argtypes}, in @code{Callable[[argtypes], resulttype]} to prepare for
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/}.  Patch by Ken Jin.

@item 
bpo-40137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40137}: Convert functools module to use
@ref{53c,,PyType_FromModuleAndSpec()}.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{7,,array} to use heap types, and establish module
state for these.

@item 
bpo-42008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42008}: Fix _random.Random() seeding.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{pyexpat} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-40521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40521}: Make the Unicode dictionary of interned strings compatible with
subinterpreters. Patch by Victor Stinner.

@item 
bpo-39465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39465}: Make @code{_PyUnicode_FromId()} function compatible with
subinterpreters. Each interpreter now has an array of identifier objects
(interned strings decoded from UTF-8). Patch by Victor Stinner.
@end itemize

@node Library<36>,Documentation<31>,Core and Builtins<37>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id311}@anchor{1897}
@subsubsection Library



@itemize -

@item 
bpo-42257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42257}: Handle empty string in variable executable in
platform.libc_ver()

@item 
bpo-42772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42772}: randrange() now raises a TypeError when step is specified
without a stop argument.  Formerly, it silently ignored the step argument.

@item 
bpo-42759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42759}: Fixed equality comparison of @code{tkinter.Variable} and
@ref{1898,,tkinter.font.Font}. Objects which belong to different Tcl
interpreters are now always different, even if they have the same name.

@item 
bpo-42756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42756}: Configure LMTP Unix-domain socket to use socket global default
timeout when a timeout is not explicitly provided.

@item 
bpo-23328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23328}: Allow / character in username, password fields on _PROXY
envars.

@item 
bpo-42740@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42740}: @ref{86a,,typing.get_args()} and @ref{a35,,typing.get_origin()} now
support 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} union types and 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} additions to @code{Callable}.

@item 
bpo-42655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42655}: @ref{d5,,subprocess} `extra_groups' is now correctly passed into
setgroups() system call.

@item 
bpo-42727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42727}: @code{EnumMeta.__prepare__} now accepts @code{**kwds} to properly
support @code{__init_subclass__}

@item 
bpo-38308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38308}: Add optional `weights' to `statistics.harmonic_mean()'.

@item 
bpo-42721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42721}: When simple query dialogs (@ref{f7,,tkinter.simpledialog}),
message boxes (@ref{f5,,tkinter.messagebox}) or color choose dialog
(@ref{f0,,tkinter.colorchooser}) are created without arguments `master' and
`parent', and the default root window is not yet created, and
@code{NoDefaultRoot()} was not called, a new temporal hidden root
window will be created automatically. It will not be set as the default
root window and will be destroyed right after closing the dialog window.
It will help to use these simple dialog windows in programs which do not
need other GUI.

@item 
bpo-25246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25246}: Optimized @ref{1899,,collections.deque.remove()}.

@item 
bpo-35728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35728}: Added a root parameter to @ref{189a,,tkinter.font.nametofont()}.

@item 
bpo-15303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15303}: @ref{ef,,tkinter} supports now widgets with boolean value False.

@item 
bpo-42681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42681}: Fixed range checks for color and pair numbers in @ref{2b,,curses}.

@item 
bpo-42685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42685}: Improved placing of simple query windows in Tkinter (such as
@ref{189b,,tkinter.simpledialog.askinteger()}). They are now centered at the
center of the parent window if it is specified and shown, otherwise at the
center of the screen.

@item 
bpo-9694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9694}: Argparse help no longer uses the confusing phrase, "optional
arguments". It uses "options" instead.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_thread} extension module to the multiphase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}) and convert its static types to heap
types.

@item 
bpo-37961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37961}: Fix crash in @code{tracemalloc.Traceback.__repr__()} (regressed
in Python 3.9).

@item 
bpo-42630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42630}: @ref{ef,,tkinter} functions and constructors which need a default
root window raise now @ref{193,,RuntimeError} with descriptive message instead
of obscure @ref{343,,AttributeError} or @ref{428,,NameError} if it is not created
yet or cannot be created automatically.

@item 
bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}: @code{atexit._run_exitfuncs()} now logs callback exceptions
using @ref{1f4,,sys.unraisablehook}, rather than logging them directly into
@ref{926,,sys.stderr} and raise the last exception.

@item 
bpo-42644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42644}: @code{logging.disable} will now validate the types and value of
its parameter. It also now accepts strings representing the levels (as
does @code{logging.setLevel}) instead of only the numerical values.

@item 
bpo-42639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42639}: At Python exit, if a callback registered with
@ref{869,,atexit.register()} fails, its exception is now logged. Previously,
only some exceptions were logged, and the last exception was always
silently ignored.

@item 
bpo-36541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36541}: Fixed lib2to3.pgen2 to be able to parse PEP-570 positional only
argument syntax.

@item 
bpo-42382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42382}: In @code{importlib.metadata}: -  @code{EntryPoint} objects now expose
a @code{.dist} object referencing the @code{Distribution} when constructed from
a @code{Distribution}. - Add support for package discovery under package
normalization rules. - The object returned by @code{metadata()} now has a
formally defined protocol called @code{PackageMetadata} with declared support
for the @code{.get_all()} method. - Synced with importlib_metadata 3.3.

@item 
bpo-41877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41877}: A check is added against misspellings of autospect, auto_spec
and set_spec being passed as arguments to patch, patch.object and
create_autospec.

@item 
bpo-39717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39717}: [tarfile] update nested exception raising to use @code{from None}
or @code{from e}

@item 
bpo-41877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41877}: AttributeError for suspected misspellings of assertions on
mocks are now pointing out that the cause are misspelled assertions and
also what to do if the misspelling is actually an intended attribute name.
The unittest.mock document is also updated to reflect the current set of
recognised misspellings.

@item 
bpo-41559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41559}: Implemented 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/}: added @code{ParamSpec} and @code{Concatenate}
to @ref{103,,typing}.  Patch by Ken Jin.

@item 
bpo-42385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42385}: StrEnum: fix _generate_next_value_ to return a str

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Define THREAD_STACK_SIZE for VxWorks.

@item 
bpo-34750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34750}: [Enum] @code{_EnumDict.update()} is now supported.

@item 
bpo-42517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42517}: Enum: private names do not become members / do not generate
errors -- they remain normal attributes

@item 
bpo-42678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42678}: @code{Enum}: call @code{__init_subclass__} after members have been
added

@item 
bpo-28964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28964}: @ref{c06,,ast.literal_eval()} adds line number information (if
available) in error message for malformed nodes.

@item 
bpo-42470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42470}: @ref{730,,random.sample()} no longer warns on a sequence which is
also a set.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: @code{posixpath.expanduser()} returns the input `path' unchanged
if user home directory is None on VxWorks.

@item 
bpo-42388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42388}: Fix subprocess.check_output(..., input=None) behavior when
text=True to be consistent with that of the documentation and
universal_newlines=True.

@item 
bpo-34463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34463}: Fixed discrepancy between @ref{fd,,traceback} and the interpreter
in formatting of SyntaxError with lineno not set (@ref{fd,,traceback} was
changed to match interpreter).

@item 
bpo-42393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42393}: Raise @ref{86d,,OverflowError} instead of silent truncation in
@ref{86c,,socket.ntohs()} and @ref{86b,,socket.htons()}.  Silent truncation was
deprecated in Python 3.7. Patch by Erlend E. Aasland

@item 
bpo-42222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42222}: Harmonized @ref{856,,random.randrange()} argument handling to match
@ref{930,,range()}.


@itemize *

@item 
The integer test and conversion in @code{randrange()} now uses
@ref{189c,,operator.index()}.

@item 
Non-integer arguments to @code{randrange()} are deprecated.

@item 
The @code{ValueError} is deprecated in favor of a @code{TypeError}.

@item 
It now runs a little faster than before.
@end itemize

(Contributed by Raymond Hettinger and Serhiy Storchaka.)

@item 
bpo-42163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42163}: Restore compatibility for @code{uname_result} around deepcopy and
_replace.

@item 
bpo-42090@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42090}: @code{zipfile.Path.joinpath} now accepts arbitrary arguments, same
as @code{pathlib.Path.joinpath}.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the _csv module to the multi-phase initialization API
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-42059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42059}: @ref{161,,typing.TypedDict} types created using the alternative
call-style syntax now correctly respect the @code{total} keyword argument
when setting their @code{__required_keys__} and @code{__optional_keys__} class
attributes.

@item 
bpo-41960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41960}: Add @code{globalns} and @code{localns} parameters to the
@ref{722,,inspect.signature()} and @ref{724,,inspect.Signature.from_callable()}.

@item 
bpo-41907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41907}: fix @code{format()} behavior for @code{IntFlag}

@item 
bpo-41891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41891}: Ensure asyncio.wait_for waits for task completion

@item 
bpo-24792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24792}: Fixed bug where @code{zipimporter} sometimes reports an
incorrect cause of import errors.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix site and sysconfig modules for VxWorks RTOS which has no
home directories.

@item 
bpo-41462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41462}: Add @ref{e27,,os.set_blocking()} support for VxWorks RTOS.

@item 
bpo-40219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40219}: Lowered @code{tkinter.ttk.LabeledScale} dummy widget to
prevent hiding part of the content label.

@item 
bpo-37193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37193}: Fixed memory leak in @code{socketserver.ThreadingMixIn} introduced
in Python 3.7.

@item 
bpo-39068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39068}: Fix initialization race condition in @code{a85encode()} and
@code{b85encode()} in @ref{e,,base64}. Patch by Brandon Stansbury.
@end itemize

@node Documentation<31>,Tests<34>,Library<36>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id312}@anchor{189d}
@subsubsection Documentation



@itemize -

@item 
bpo-17140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17140}: Add documentation for the
@ref{189e,,multiprocessing.pool.ThreadPool} class.

@item 
bpo-34398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34398}: Prominently feature listings from the glossary in documentation
search results. Patch by Ammar Askar.
@end itemize

@node Tests<34>,Build<36>,Documentation<31>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id313}@anchor{189f}
@subsubsection Tests



@itemize -

@item 
bpo-42794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42794}: Update test_nntplib to use official group name of news.aioe.org
for testing. Patch by Donghee Na.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Skip some asyncio tests on VxWorks.

@item 
bpo-42641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42641}: Enhance @code{test_select.test_select()}: it now takes 500
milliseconds rather than 10 seconds. Use Python rather than a shell to
make the test more portable.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Skip some tests in _test_all_chown_common() on VxWorks.

@item 
bpo-42199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42199}: Fix bytecode helper assertNotInBytecode.

@item 
bpo-41443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41443}: Add more attribute checking in test_posix.py

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Disable os.popen and impacted tests on VxWorks

@item 
bpo-41439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41439}: Port test_ssl and test_uuid to VxWorks RTOS.
@end itemize

@node Build<36>,macOS<26>,Tests<34>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id314}@anchor{18a0}
@subsubsection Build



@itemize -

@item 
bpo-42692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42692}: Fix __builtin_available check on older compilers. Patch by
Joshua Root.

@item 
bpo-27640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27640}: Added @code{--disable-test-modules} option to the @code{configure}
script: don't build nor install test modules. Patch by Xavier de Gaye,
Thomas Petazzoni and Peixing Xin.

@item 
bpo-42604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42604}: Now all platforms use a value for the "EXT_SUFFIX" build
variable derived from SOABI (for instance in freeBSD, "EXT_SUFFIX" is now
".cpython-310d.so" instead of ".so"). Previously only Linux, Mac and
VxWorks were using a value for "EXT_SUFFIX" that included "SOABI".

@item 
bpo-42598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42598}: Fix implicit function declarations in configure which could
have resulted in incorrect configuration checks.  Patch contributed by
Joshua Root.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Enable libpython3.so for VxWorks.

@item 
bpo-29076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29076}: Add fish shell support to macOS installer.
@end itemize

@node macOS<26>,Tools/Demos<16>,Build<36>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id315}@anchor{18a1}
@subsubsection macOS



@itemize -

@item 
bpo-42361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42361}: Update macOS installer build to use Tcl/Tk 8.6.11 (rc2,
expected to be final release).

@item 
bpo-41837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41837}: Update macOS installer build to use OpenSSL 1.1.1i.

@item 
bpo-42584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42584}: Update macOS installer to use SQLite 3.34.0.
@end itemize

@node Tools/Demos<16>,C API<35>,macOS<26>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id316}@anchor{18a2}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-42726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42726}: Fixed Python 3 compatibility issue with gdb/libpython.py
handling of attribute dictionaries.

@item 
bpo-42613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42613}: Fix @code{freeze.py} tool to use the prope config and library
directories. Patch by Victor Stinner.
@end itemize

@node C API<35>,,Tools/Demos<16>,Python 3 10 0 alpha 4
@anchor{whatsnew/changelog id317}@anchor{18a3}
@subsubsection C API



@itemize -

@item 
bpo-42591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42591}: Export the @code{Py_FrozenMain()} function: fix a Python 3.9.0
regression. Python 3.9 uses @code{-fvisibility=hidden} and the function was
not exported explicitly and so not exported.

@item 
bpo-32381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32381}: Remove the private @code{_Py_fopen()} function which is no
longer needed. Use @code{_Py_wfopen()} or @code{_Py_fopen_obj()}
instead. Patch by Victor Stinner.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{bb,,resource} extension module to module state

@item 
bpo-42111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42111}: Update the @code{xxlimited} module to be a better example of how
to use the limited C API.

@item 
bpo-40052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40052}: Fix an alignment build warning/error in function
@code{PyVectorcall_Function()}. Patch by Andreas Schneider, Antoine Pitrou
and Petr Viktorin.
@end itemize

@node Python 3 10 0 alpha 3,Python 3 10 0 alpha 2,Python 3 10 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-3}@anchor{18a4}
@subsection Python 3.10.0 alpha 3


`Release date: 2020-12-07'

@menu
* Security: Security<23>. 
* Core and Builtins: Core and Builtins<38>. 
* Library: Library<37>. 
* Documentation: Documentation<32>. 
* Tests: Tests<35>. 
* Build: Build<37>. 
* Windows: Windows<33>. 
* macOS: macOS<27>. 
* IDLE: IDLE<24>. 
* Tools/Demos: Tools/Demos<17>. 
* C API: C API<36>. 

@end menu

@node Security<23>,Core and Builtins<38>,,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id318}@anchor{18a5}
@subsubsection Security



@itemize -

@item 
bpo-40791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40791}: Add @code{volatile} to the accumulator variable in
@code{hmac.compare_digest}, making constant-time-defeating optimizations less
likely.
@end itemize

@node Core and Builtins<38>,Library<37>,Security<23>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id319}@anchor{18a6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-42576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42576}: @code{types.GenericAlias} will now raise a @code{TypeError} when
attempting to initialize with a keyword argument.  Previously, this would
cause the interpreter to crash if the interpreter was compiled with debug
symbols. This does not affect interpreters compiled for release.  Patch by
Ken Jin.

@item 
bpo-42536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42536}: Several built-in and standard library types now ensure that
their internal result tuples are always tracked by the @ref{18a7,,garbage collector}:


@itemize -

@item 
@ref{5c5,,collections.OrderedDict.items()}

@item 
@ref{7b9,,dict.items()}

@item 
@ref{1433,,enumerate()}

@item 
@ref{12ba,,functools.reduce()}

@item 
@ref{12f0,,itertools.combinations()}

@item 
@ref{125f,,itertools.combinations_with_replacement()}

@item 
@ref{18a8,,itertools.permutations()}

@item 
@ref{12f1,,itertools.product()}

@item 
@ref{127b,,itertools.zip_longest()}

@item 
@ref{7ba,,zip()}
@end itemize

Previously, they could have become untracked by a prior garbage
collection. Patch by Brandt Bucher.

@item 
bpo-42500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42500}: Improve handling of exceptions near recursion limit. Converts a
number of Fatal Errors in RecursionErrors.

@item 
bpo-42246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42246}: PEP 626: After a return, the f_lineno attribute of a frame is
always the last line executed.

@item 
bpo-42435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42435}: Speed up comparison of bytes objects with non-bytes objects
when option @ref{5cd,,-b} is specified. Speed up comparison of bytarray
objects with non-buffer object.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_warnings} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}). Patch by Victor Stinner.

@item 
bpo-41686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41686}: On Windows, the @code{SIGINT} event, @code{_PyOS_SigintEvent()}, is
now created even if Python is configured to not install signal handlers
(if @ref{8ab,,PyConfig.install_signal_handlers} equals to 0, or
@code{Py_InitializeEx(0)}).

@item 
bpo-42381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42381}: Allow assignment expressions in set literals and set
comprehensions as per PEP 572. Patch by Pablo Galindo.

@item 
bpo-42202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42202}: Change function parameters annotations internal representation
to tuple of strings. Patch provided by Yurii Karabas.

@item 
bpo-42374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42374}: Fix a regression introduced by the new parser, where an
unparenthesized walrus operator was not allowed within generator
expressions.

@item 
bpo-42316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42316}: Allow an unparenthesized walrus in subscript indexes.

@item 
bpo-42349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42349}: Make sure that the compiler front-end produces a well-formed
control flow graph. Be more aggressive in the compiler back-end, as it is
now safe to do so.

@item 
bpo-42296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42296}: On Windows, fix a regression in signal handling which prevented
to interrupt a program using CTRL+C. The signal handler can be run in a
thread different than the Python thread, in which case the test deciding
if the thread can handle signals is wrong.

@item 
bpo-42332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42332}: @ref{7d5,,types.GenericAlias} objects can now be the targets of
weakrefs.

@item 
bpo-42282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42282}: Optimise constant subexpressions that appear as part of named
expressions (previously the AST optimiser did not descend into named
expressions). Patch by Nick Coghlan.

@item 
bpo-42266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42266}: Fixed a bug with the LOAD_ATTR opcode cache that was not
respecting monkey-patching a class-level attribute to make it a
descriptor. Patch by Pablo Galindo.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{b5,,queue} to use heap types.

@item 
bpo-42246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42246}: Improved accuracy of line tracing events and f_lineno attribute
of Frame objects. See PEP 626 for details.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @ref{8f,,mmap} to use heap types.

@item 
bpo-42233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42233}: Allow @code{GenericAlias} objects to use @ref{7ac,,union type expressions}. This allows expressions like @code{list[int] |
dict[float, str]} where previously a @code{TypeError} would have been
thrown.  This also fixes union type expressions not de-duplicating
@code{GenericAlias} objects. (Contributed by Ken Jin in bpo-42233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42233}.)

@item 
bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}: The import system triggers a @code{ImportWarning} when it falls
back to using @code{load_module()}.
@end itemize

@node Library<37>,Documentation<32>,Core and Builtins<38>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id320}@anchor{18a9}
@subsubsection Library



@itemize -

@item 
bpo-5054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5054}: CGIHTTPRequestHandler.run_cgi() HTTP_ACCEPT improperly parsed.
Replace the special purpose getallmatchingheaders with generic get_all
method and add relevant tests.

Original Patch by Martin Panter. Modified by Senthil Kumaran.

@item 
bpo-42562@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42562}: Fix issue when dis failed to parse function that has no line
numbers. Patch provided by Yurii Karabas.

@item 
bpo-17735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17735}: @code{inspect.findsource()} now raises @ref{40d,,OSError} instead of
@ref{14eb,,IndexError} when @code{co_lineno} of a code object is greater than
the file length. This can happen, for example, when a file is edited after
it was imported.  PR by Irit Katriel.

@item 
bpo-42116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42116}: Fix handling of trailing comments by @ref{154d,,inspect.getsource()}.

@item 
bpo-42532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42532}: Remove unexpected call of @code{__bool__} when passing a
@code{spec_arg} argument to a Mock.

@item 
bpo-38200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38200}: Added itertools.pairwise()

@item 
bpo-41818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41818}: Fix test_master_read() so that it succeeds on all platforms
that either raise OSError or return b"" upon reading from master.

@item 
bpo-42487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42487}: ChainMap.__iter__ no longer calls __getitem__ on underlying
maps

@item 
bpo-42482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42482}: @ref{259,,TracebackException} no longer holds a
reference to the exception's traceback object. Consequently, instances of
TracebackException for equivalent but non-equal exceptions now compare as
equal.

@item 
bpo-41818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41818}: Make test_openpty() avoid unexpected success due to number of
rows and/or number of columns being == 0.

@item 
bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}: Remove loop parameter from @code{asyncio.subprocess} and
@code{asyncio.tasks} functions. Patch provided by Yurii Karabas.

@item 
bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}: Remove loop parameter from @code{asyncio.open_connection} and
@code{asyncio.start_server} functions. Patch provided by Yurii Karabas.

@item 
bpo-28468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28468}: Add @ref{810,,platform.freedesktop_os_release()} function to parse
freedesktop.org @code{os-release} files.

@item 
bpo-42299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42299}: Removed the @code{formatter} module, which was deprecated in
Python 3.4. It is somewhat obsolete, little used, and not tested. It was
originally scheduled to be removed in Python 3.6, but such removals were
delayed until after Python 2.7 EOL. Existing users should copy whatever
classes they use into their code. Patch by Donghee Na and and Terry J.
Reedy.

@item 
bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}: Deprecate zipimport.zipimporter.load_module() in favour of
exec_module().

@item 
bpo-41818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41818}: Updated tests for the pty library. test_basic() has been
changed to test_openpty(); this additionally checks if slave termios and
slave winsize are being set properly by pty.openpty(). In order to add
support for FreeBSD, NetBSD, OpenBSD, and Darwin, this also adds
test_master_read(), which demonstrates that pty.spawn() should not depend
on an OSError to exit from its copy loop.

@item 
bpo-42392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42392}: Remove loop parameter from @code{__init__} in all
@code{asyncio.locks} and @code{asyncio.Queue} classes. Patch provided by Yurii
Karabas.

@item 
bpo-15450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15450}: Make @ref{f2b,,filecmp.dircmp} respect subclassing. Now the
@ref{18aa,,filecmp.dircmp.subdirs} behaves as expected when subclassing
dircmp.

@item 
bpo-42413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42413}: The exception @ref{81e,,socket.timeout} is now an alias of
@ref{81f,,TimeoutError}.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Support signal module on VxWorks.

@item 
bpo-42406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42406}: We fixed an issue in @code{pickle.whichmodule} in which importing
@code{multiprocessing} could change the how pickle identifies which module an
object belongs to, potentially breaking the unpickling of those objects.

@item 
bpo-42403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42403}: Simplify the @ref{76,,importlib} external bootstrap code:
@code{importlib._bootstrap_external} now uses regular imports to import
builtin modules. When it is imported, the builtin @ref{8c1,,__import__()}
function is already fully working and so can be used to import builtin
modules like @ref{d8,,sys}. Patch by Victor Stinner.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Convert _sre module types to heap types (PEP 384). Patch by
Erlend E. Aasland.

@item 
bpo-42375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42375}: subprocess module update for DragonFlyBSD support.

@item 
bpo-41713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41713}: Port the @code{_signal} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}). Patch by Victor Stinner and Mohamed
Koubaa.

@item 
bpo-37205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37205}: @ref{251,,time.time()}, @ref{a76,,time.perf_counter()} and
@ref{250,,time.monotonic()} functions can no longer fail with a Python fatal
error, instead raise a regular Python exception on failure.

@item 
bpo-42328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42328}: Fixed @ref{18ab,,tkinter.ttk.Style.map()}. The function accepts now
the representation of the default state as empty sequence (as returned by
@code{Style.map()}). The structure of the result is now the same on all
platform and does not depend on the value of @code{wantobjects}.

@item 
bpo-42345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42345}: Fix various issues with @code{typing.Literal} parameter handling
(flatten, deduplicate, use type to cache key). Patch provided by Yurii
Karabas.

@item 
bpo-37205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37205}: @ref{a76,,time.perf_counter()} on Windows and @ref{250,,time.monotonic()}
on macOS are now system-wide. Previously, they used an offset computed at
startup to reduce the precision loss caused by the float type. Use
@ref{ad3,,time.perf_counter_ns()} and @ref{ad2,,time.monotonic_ns()} added in Python
3.7 to avoid this precision loss.

@item 
bpo-42318@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42318}: Fixed support of non-BMP characters in @ref{ef,,tkinter} on macOS.

@item 
bpo-42350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42350}: Fix the @ref{939,,threading.Thread} class at fork: do nothing if
the thread is already stopped (ex: fork called at Python exit).
Previously, an error was logged in the child process.

@item 
bpo-42333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42333}: Port _ssl extension module to heap types.

@item 
bpo-42014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42014}: The @code{onerror} callback from @code{shutil.rmtree} now receives
correct function when @code{os.open} fails.

@item 
bpo-42237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42237}: Fix @code{os.sendfile()} on illumos.

@item 
bpo-42308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42308}: Add @ref{834,,threading.__excepthook__} to allow retrieving the
original value of @ref{835,,threading.excepthook()} in case it is set to a
broken or a different value. Patch by Mario Corchero.

@item 
bpo-42131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42131}: Implement PEP 451/spec methods on zipimport.zipimporter:
find_spec(), create_module(), and exec_module().

This also allows for the documented deprecation of find_loader(),
find_module(), and load_module().

@item 
bpo-41877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41877}: Mock objects which are not unsafe will now raise an
AttributeError if an attribute with the prefix asert, aseert, or assrt is
accessed, in addition to this already happening for the prefixes assert or
assret.

@item 
bpo-42264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42264}: @code{sqlite3.OptimizedUnicode} has been undocumented and obsolete
since Python 3.3, when it was made an alias to @ref{435,,str}.  It is now
deprecated, scheduled for removal in Python 3.12.

@item 
bpo-42251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42251}: Added @ref{830,,threading.gettrace()} and
@ref{831,,threading.getprofile()} to retrieve the functions set by
@ref{832,,threading.settrace()} and @ref{833,,threading.setprofile()} respectively.
Patch by Mario Corchero.

@item 
bpo-42249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42249}: Fixed writing binary Plist files larger than 4 GiB.

@item 
bpo-42236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42236}: On Unix, the @ref{181f,,os.device_encoding()} function now returns
@code{'UTF-8'} rather than the device encoding if the @ref{641,,Python UTF-8 Mode} is enabled.

@item 
bpo-41754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41754}: webbrowser: Ignore `NotADirectoryError' when calling
@code{xdg-settings}.

@item 
bpo-42183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42183}: Fix a stack overflow error for asyncio Task or Future repr().

The overflow occurs under some circumstances when a Task or Future
recursively returns itself.

@item 
bpo-42140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42140}: Improve asyncio.wait function to create the futures set just
one time.

@item 
bpo-42133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42133}: Update various modules in the stdlib to fall back on
@code{__spec__.loader} when @code{__loader__} isn't defined on a module.

@item 
bpo-26131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26131}: The @code{load_module()} methods found in @code{importlib} now
trigger a @code{DeprecationWarning}.

@item 
bpo-39825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39825}: Windows: Change @code{sysconfig.get_config_var('EXT_SUFFIX')} to
the expected full @code{platform_tag.extension} format. Previously it was
hard-coded to @code{.pyd}, now it is compatible with @code{distutils.sysconfig}
and will result in something like @code{.cp38-win_amd64.pyd}. This brings
windows into conformance with the other platforms.

@item 
bpo-26389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26389}: The @ref{837,,traceback.format_exception()},
@ref{838,,traceback.format_exception_only()}, and
@ref{839,,traceback.print_exception()} functions can now take an exception
object as a positional-only argument.

@item 
bpo-41889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41889}: Enum: fix regression involving inheriting a multiply inherited
enum

@item 
bpo-41861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41861}: Convert @ref{ce,,sqlite3} to use heap types (PEP 384). Patch by
Erlend E. Aasland.

@item 
bpo-40624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40624}: Added support for the XPath @code{!=} operator in xml.etree

@item 
bpo-28850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28850}: Fix @ref{18ac,,pprint.PrettyPrinter.format()} overrides being ignored
for contents of small containers. The @code{pprint._safe_repr()} function
was removed.

@item 
bpo-41625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41625}: Expose the @code{splice()} as @ref{803,,os.splice()} in the
@ref{a0,,os} module. Patch by Pablo Galindo

@item 
bpo-34215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34215}: Clarify the error message for
@ref{18ad,,asyncio.IncompleteReadError} when @code{expected} is @code{None}.

@item 
bpo-41543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41543}: Add async context manager support for contextlib.nullcontext.

@item 
bpo-21041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21041}: @ref{80a,,pathlib.PurePath.parents} now supports negative
indexing. Patch contributed by Yaroslav Pankovych.

@item 
bpo-41332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41332}: Added missing connect_accepted_socket() method to
@code{asyncio.AbstractEventLoop}.

@item 
bpo-12800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12800}: Extracting a symlink from a tarball should succeed and
overwrite the symlink if it already exists. The fix is to remove the
existing file or symlink before extraction. Based on patch by Chris AtLee,
Jeffrey Kintscher, and Senthil Kumaran.

@item 
bpo-40968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40968}: @ref{10a,,urllib.request} and @ref{6e,,http.client} now send
@code{http/1.1} ALPN extension during TLS handshake when no custom context is
supplied.

@item 
bpo-41001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41001}: Add @ref{802,,os.eventfd()} to provide a low level interface for
Linux's event notification file descriptor.

@item 
bpo-40816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40816}: Add AsyncContextDecorator to contextlib to support async
context manager as a decorator.

@item 
bpo-40550@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40550}: Fix time-of-check/time-of-action issue in
subprocess.Popen.send_signal.

@item 
bpo-39411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39411}: Add an @code{is_async} identifier to @ref{b3,,pyclbr}'s @code{Function}
objects. Patch by Batuhan Taskaya

@item 
bpo-35498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35498}: Add slice support to @ref{80a,,pathlib.PurePath.parents}.
@end itemize

@node Documentation<32>,Tests<35>,Library<37>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id321}@anchor{18ae}
@subsubsection Documentation



@itemize -

@item 
bpo-42238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42238}: Tentative to deprecate @code{make suspicious} by first removing it
from the CI and documentation builds, but keeping it around for manual
uses.

@item 
bpo-42153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42153}: Fix the URL for the IMAP protocol documents.

@item 
bpo-41028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41028}: Language and version switchers, previously maintained in every
cpython branches, are now handled by docsbuild-script.
@end itemize

@node Tests<35>,Build<37>,Documentation<32>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id322}@anchor{18af}
@subsubsection Tests



@itemize -

@item 
bpo-41473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41473}: Re-enable test_gdb on gdb 9.2 and newer:
@indicateurl{https://bugzilla.redhat.com/show_bug.cgi?id=1866884} bug is fixed in gdb
10.1.

@item 
bpo-42553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42553}: Fix @code{test_asyncio.test_call_later()} race condition: don't
measure asyncio performance in the @code{call_later()} unit test. The test
failed randomly on the CI.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix test_netrc on VxWorks: create temporary directories using
temp_cwd().

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: skip test_getaddrinfo_ipv6_scopeid_symbolic and
test_getnameinfo_ipv6_scopeid_symbolic on VxWorks

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: skip test_test of test_mailcap on VxWorks

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: add shell requirement for test_pipes

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: skip some tests related to fifo on VxWorks

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix test_doctest.py failures for VxWorks.

@item 
bpo-40754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40754}: Include @code{_testinternalcapi} module in Windows installer for
test suite

@item 
bpo-41561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41561}: test_ssl: skip test_min_max_version_mismatch when TLS 1.0 is
not available

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix os module failures for VxWorks RTOS.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix fifo test cases for VxWorks RTOS.
@end itemize

@node Build<37>,Windows<33>,Tests<35>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id323}@anchor{18b0}
@subsubsection Build



@itemize -

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: remove libnet dependency from detect_socket() for VxWorks

@item 
bpo-42398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42398}: Fix a race condition in "make regen-all" when make -jN option
is used to run jobs in parallel. The clinic.py script now only use atomic
write to write files. Moveover, generated files are now left unchanged if
the content does not change, to not change the file modification time.

@item 
bpo-41617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41617}: Fix building @code{pycore_bitutils.h} internal header on old clang
version without @code{__builtin_bswap16()} (ex: Xcode 4.6.3 on Mac OS X
10.7). Patch by Joshua Root and Victor Stinner.

@item 
bpo-38823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38823}: It is no longer possible to build the @code{_ctypes} extension
module without @code{wchar_t} type: remove @code{CTYPES_UNICODE} macro.
Anyway, the @code{wchar_t} type is required to build Python. Patch by
Victor Stinner.

@item 
bpo-42087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42087}: Support was removed for AIX 5.3 and below. See bpo-40680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40680}.

@item 
bpo-40998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40998}: Addressed three compiler warnings found by undefined behavior
sanitizer (ubsan).
@end itemize

@node Windows<33>,macOS<27>,Build<37>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id324}@anchor{18b1}
@subsubsection Windows



@itemize -

@item 
bpo-42120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42120}: Remove macro definition of @code{copysign} (to @code{_copysign}) in
headers.

@item 
bpo-38506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38506}: The Windows launcher now properly handles Python 3.10 when
listing installed Python versions.
@end itemize

@node macOS<27>,IDLE<24>,Windows<33>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id325}@anchor{18b2}
@subsubsection macOS



@itemize -

@item 
bpo-42504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42504}: Fix build on macOS Big Sur when MACOSX_DEPLOYMENT_TARGET=11

@item 
bpo-41116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41116}: Ensure distutils.unixxcompiler.find_library_file can find
system provided libraries on macOS 11.

@item 
bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100}: Add support for macOS 11 and Apple Silicon systems.

It is now possible to build "Universal 2" binaries using
"--enable-universalsdk --with-universal-archs=universal2".

Binaries build on later macOS versions can be deployed back to older
versions (tested up to macOS 10.9), when using the correct deployment
target. This is tested using Xcode 11 and later.

@item 
bpo-42232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42232}: Added Darwin specific madvise options to mmap module.

@item 
bpo-38443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38443}: The @code{--enable-universalsdk} and @code{--with-universal-archs}
options for the configure script now check that the specified
architectures can be used.
@end itemize

@node IDLE<24>,Tools/Demos<17>,macOS<27>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id326}@anchor{18b3}
@subsubsection IDLE



@itemize -

@item 
bpo-42508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42508}: Keep IDLE running on macOS.  Remove obsolete workaround that
prevented running files with shortcuts when using new universal2
installers built on macOS 11.

@item 
bpo-42426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42426}: Fix reporting offset of the RE error in searchengine.

@item 
bpo-42415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42415}: Get docstrings for IDLE calltips more often by using
inspect.getdoc.
@end itemize

@node Tools/Demos<17>,C API<36>,IDLE<24>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id327}@anchor{18b4}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-42212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42212}: The smelly.py script now also checks the Python dynamic library
and extension modules, not only the Python static library. Make also the
script more verbose: explain what it does.

@item 
bpo-36310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36310}: Allow @code{Tools/i18n/pygettext.py} to detect calls to
@code{gettext} in f-strings.
@end itemize

@node C API<36>,,Tools/Demos<17>,Python 3 10 0 alpha 3
@anchor{whatsnew/changelog id328}@anchor{18b5}
@subsubsection C API



@itemize -

@item 
bpo-42423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42423}: The @ref{56a,,PyType_FromSpecWithBases()} and
@ref{53c,,PyType_FromModuleAndSpec()} functions now accept a single class as
the `bases' argument.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{c0,,select} extension module to multiphase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _posixsubprocess extension module to multiphase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _posixshmem extension module to multiphase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _struct extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{spwd} extension module to multiphase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{5f,,gc} extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _queue extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Convert @ref{76a,,Py_TYPE()} and @ref{76c,,Py_SIZE()} back to macros
to allow using them as an l-value. Many third party C extension modules
rely on the ability of using Py_TYPE() and Py_SIZE() to set an object type
and size: @code{Py_TYPE(obj) = type;} and @code{Py_SIZE(obj) = size;}.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{d7,,symtable} extension module to multiphase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{65,,grp} and @ref{b1,,pwd} extension modules to
multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _random extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _hashlib extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/})

@item 
bpo-41713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41713}: Removed the undocumented @code{PyOS_InitInterrupts()} function.
Initializing Python already implicitly installs signal handlers: see
@ref{8ab,,PyConfig.install_signal_handlers}. Patch by Victor Stinner.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: The @code{Py_TRASHCAN_BEGIN} macro no longer accesses PyTypeObject
attributes, but now can get the condition by calling the new private
@code{_PyTrash_cond()} function which hides implementation details.

@item 
bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}: @ref{3aa,,Py_GetPath()}, @ref{3ac,,Py_GetPrefix()},
@ref{3a8,,Py_GetExecPrefix()}, @ref{3ae,,Py_GetProgramFullPath()},
@ref{3b1,,Py_GetPythonHome()} and @ref{3b0,,Py_GetProgramName()} functions now
return @code{NULL} if called before @ref{899,,Py_Initialize()} (before Python is
initialized). Use the new @ref{39e,,Python Initialization Configuration API} to get the @ref{89a,,Python Path Configuration.}. Patch by Victor Stinner.

@item 
bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}: The @ref{77a,,PyConfig_Read()} function now only parses
@ref{3ba,,PyConfig.argv} arguments once: @ref{18b6,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
strippped from @ref{3ba,,PyConfig.argv}, parsing arguments twice would
parse the application options as Python options.

@item 
bpo-42262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42262}: Added @ref{886,,Py_NewRef()} and @ref{887,,Py_XNewRef()} functions to
increment the reference count of an object and return the object. Patch by
Victor Stinner.

@item 
bpo-42260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42260}: When @ref{899,,Py_Initialize()} is called twice, the second call
now updates more @ref{d8,,sys} attributes for the configuration, rather than
only @ref{1243,,sys.argv}. Patch by Victor Stinner.

@item 
bpo-41832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41832}: The @ref{53c,,PyType_FromModuleAndSpec()} function now accepts
NULL @code{tp_doc} slot.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Added @ref{35b,,PyModule_AddObjectRef()} function: similar to
@ref{35c,,PyModule_AddObject()} but don't steal a reference to the value on
success. Patch by Victor Stinner.

@item 
bpo-42171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42171}: The @ref{15b0,,METH_FASTCALL} calling convention is added to the
limited API. The functions  @ref{962,,PyModule_AddType()},
@ref{53c,,PyType_FromModuleAndSpec()}, @ref{95b,,PyType_GetModule()} and
@ref{95c,,PyType_GetModuleState()} are added to the limited API on Windows.

@item 
bpo-42085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42085}: Add dedicated entry to PyAsyncMethods for sending values

@item 
bpo-41073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41073}: @ref{888,,PyType_GetSlot()} can now accept static types.

@item 
bpo-30459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30459}: @ref{384,,PyList_SET_ITEM()}, @ref{383,,PyTuple_SET_ITEM()} and
@ref{89b,,PyCell_SET()} macros can no longer be used as l-value or r-value.
For example, @code{x = PyList_SET_ITEM(a, b, c)} and @code{PyList_SET_ITEM(a, b,
c) = x} now fail with a compiler error. It prevents bugs like @code{if
(PyList_SET_ITEM (a, b, c) < 0) ...} test. Patch by Zackery Spytz and
Victor Stinner.
@end itemize

@node Python 3 10 0 alpha 2,Python 3 10 0 alpha 1,Python 3 10 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-2}@anchor{18b7}
@subsection Python 3.10.0 alpha 2


`Release date: 2020-11-03'

@menu
* Security: Security<24>. 
* Core and Builtins: Core and Builtins<39>. 
* Library: Library<38>. 
* Documentation: Documentation<33>. 
* Tests: Tests<36>. 
* Build: Build<38>. 
* Windows: Windows<34>. 
* macOS: macOS<28>. 
* IDLE: IDLE<25>. 
* C API: C API<37>. 

@end menu

@node Security<24>,Core and Builtins<39>,,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id329}@anchor{18b8}
@subsubsection Security



@itemize -

@item 
bpo-42103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42103}: Prevented potential DoS attack via CPU and RAM exhaustion when
processing malformed Apple Property List files in binary format.

@item 
bpo-42051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42051}: The @ref{aa,,plistlib} module no longer accepts entity
declarations in XML plist files to avoid XML vulnerabilities. This should
not affect users as entity declarations are not used in regular plist
files.
@end itemize

@node Core and Builtins<39>,Library<38>,Security<24>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id330}@anchor{18b9}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-42236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42236}: If the @code{nl_langinfo(CODESET)} function returns an empty
string, Python now uses UTF-8 as the filesystem encoding. Patch by Victor
Stinner.

@item 
bpo-42218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42218}: Fixed a bug in the PEG parser that was causing crashes in debug
mode. Now errors are checked in left-recursive rules to avoid cases where
such errors do not get handled in time and appear as long-distance crashes
in other places.

@item 
bpo-42214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42214}: Fixed a possible crash in the PEG parser when checking for the
'!=' token in the @code{barry_as_flufl} rule. Patch by Pablo Galindo.

@item 
bpo-42206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42206}: Propagate and raise the errors caused by
@code{PyAST_Validate()} in the parser.

@item 
bpo-41796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41796}: The @ref{8,,ast} module internal state is now per interpreter.
Patch by Victor Stinner.

@item 
bpo-42143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42143}: Fix handling of errors during creation of @code{PyFunctionObject},
which resulted in operations on uninitialized memory. Patch by Yonatan
Goldschmidt.

@item 
bpo-41659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41659}: Fix a bug in the parser, where a curly brace following a
@code{primary} didn't fail immediately. This led to invalid expressions like
@code{a @{b@}} to throw a @ref{18b,,SyntaxError} with a wrong offset, or invalid
expressions ending with a curly brace like @code{a @{} to not fail immediately
in the REPL.

@item 
bpo-42150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42150}: Fix possible buffer overflow in the new parser when checking
for continuation lines. Patch by Pablo Galindo.

@item 
bpo-42123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42123}: Run the parser two times. On the first run, disable all the
rules that only generate better error messages to gain performance. If
there's a parse failure, run the parser a second time with those enabled.

@item 
bpo-42093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42093}: The @code{LOAD_ATTR} instruction now uses new "per opcode cache"
mechanism and it is about 36% faster now. Patch by Pablo Galindo and Yury
Selivanov.

@item 
bpo-42030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42030}: Support for the legacy AIX-specific shared library loading
support has been removed. All versions of AIX since 4.3 have supported and
defaulted to using the common Unix mechanism instead.

@item 
bpo-41984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41984}: The garbage collector now tracks all user-defined classes.
Patch by Brandt Bucher.

@item 
bpo-41993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41993}: Fixed potential issues with removing not completely initialized
module from @code{sys.modules} when import fails.

@item 
bpo-41979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41979}: Star-unpacking is now allowed for with item's targets in the
PEG parser.

@item 
bpo-41974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41974}: Removed special methods @code{__int__}, @code{__float__},
@code{__floordiv__}, @code{__mod__}, @code{__divmod__}, @code{__rfloordiv__},
@code{__rmod__} and @code{__rdivmod__} of the @ref{2ec,,complex} class.  They
always raised a @ref{522,,TypeError}.

@item 
bpo-41902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41902}: Micro optimization when compute
@ref{18ba,,sq_item} and
@ref{18bb,,mp_subscript} of @ref{930,,range}. Patch by
Donghee Na.

@item 
bpo-41894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41894}: When loading a native module and a load failure occurs, prevent
a possible UnicodeDecodeError when not running in a UTF-8 locale by
decoding the load error message using the current locale's encoding.

@item 
bpo-41902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41902}: Micro optimization for range.index if step is 1. Patch by
Donghee Na.

@item 
bpo-41435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41435}: Add @code{sys._current_exceptions()} function to retrieve a
dictionary mapping each thread's identifier to the topmost exception
currently active in that thread at the time the function is called.

@item 
bpo-38605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38605}: Enable @code{from __future__ import annotations} (
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}) by
default. The values found in @code{__annotations__} dicts are now
strings, for example @code{@{"x": "int"@}} instead of @code{@{"x": int@}}.
@end itemize

@node Library<38>,Documentation<33>,Core and Builtins<39>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id331}@anchor{18bc}
@subsubsection Library



@itemize -

@item 
bpo-35455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35455}: On Solaris, @ref{923,,thread_time()} is now implemented with
@code{gethrvtime()} because @code{clock_gettime(CLOCK_THREAD_CPUTIME_ID)} is not
always available. Patch by Jakub Kulik.

@item 
bpo-42233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42233}: The @ref{7e7,,repr()} of @ref{103,,typing} types containing
@ref{69d,,Generic Alias Types} previously did not show
the parameterized types in the @code{GenericAlias}.  They have now been
changed to do so.

@item 
bpo-29566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29566}: @code{binhex.binhex()} consistently writes macOS 9 line endings.

@item 
bpo-26789@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26789}: The @ref{182c,,logging.FileHandler} class now keeps a reference to
the builtin @ref{505,,open()} function to be able to open or reopen the file
during Python finalization. Fix errors like: @code{NameError: name 'open' is
not defined}. Patch by Victor Stinner.

@item 
bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}: Removed the @code{unicodedata.ucnhash_CAPI} attribute which was an
internal PyCapsule object. The related private @code{_PyUnicode_Name_CAPI}
structure was moved to the internal C API. Patch by Victor Stinner.

@item 
bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}: Convert the @ref{104,,unicodedata} extension module to the
multiphase initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}) and convert the
@code{unicodedata.UCD} static type to a heap type. Patch by Mohamed Koubaa
and Victor Stinner.

@item 
bpo-42146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42146}: Fix memory leak in @ref{197,,subprocess.Popen()} in case an uid
(gid) specified in @code{user} (@code{group}, @code{extra_groups}) overflows
@code{uid_t} (@code{gid_t}).

@item 
bpo-42103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42103}: @code{InvalidFileException} and @ref{d59,,RecursionError}
are now the only errors caused by loading malformed binary Plist file
(previously ValueError and TypeError could be raised in some specific
cases).

@item 
bpo-41490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41490}: In @code{importlib.resources}, @code{.path} method is more aggressive
about releasing handles to zipfile objects early, enabling use-cases like
certifi to leave the context open but delete the underlying zip file.

@item 
bpo-41052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41052}: Pickling heap types implemented in C with protocols 0 and 1
raises now an error instead of producing incorrect data.

@item 
bpo-42089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42089}: In @code{importlib.metadata.PackageNotFoundError}, make reference
to the package metadata being missing to improve the user experience.

@item 
bpo-41491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41491}: plistlib: fix parsing XML plists with hexadecimal integer
values

@item 
bpo-42065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42065}: Fix an incorrectly formatted error from
@code{_codecs.charmap_decode()} when called with a mapped value outside
the range of valid Unicode code points. PR by Max Bernstein.

@item 
bpo-41966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41966}: Fix pickling pure Python @ref{1c9,,datetime.time} subclasses.
Patch by Dean Inwood.

@item 
bpo-19270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19270}: @ref{18bd,,sched.scheduler.cancel()} will now cancel the correct
event, if two events with same priority are scheduled for the same time.
Patch by Bar Harel.

@item 
bpo-28660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28660}: @ref{147b,,textwrap.wrap()} now attempts to break long words after
hyphens when @code{break_long_words=True} and @code{break_on_hyphens=True}.

@item 
bpo-35823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35823}: Use @code{vfork()} instead of @code{fork()} for
@ref{197,,subprocess.Popen()} on Linux to improve performance in cases where it
is deemed safe.

@item 
bpo-42043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42043}: Add support for @code{zipfile.Path} inheritance.
@code{zipfile.Path.is_file()} now returns False for non-existent names.
@code{zipfile.Path} objects now expose a @code{.filename} attribute and rely on
that to resolve @code{.name} and @code{.parent} when the @code{Path} object is at
the root of the zipfile.

@item 
bpo-42021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42021}: Fix possible ref leaks in @ref{ce,,sqlite3} module init.

@item 
bpo-39101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39101}: Fixed tests using IsolatedAsyncioTestCase from hanging on
BaseExceptions.

@item 
bpo-41976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41976}: Fixed a bug that was causing @ref{d37,,ctypes.util.find_library()}
to return @code{None} when triying to locate a library in an environment when
gcc>=9 is available and @code{ldconfig} is not. Patch by Pablo Galindo

@item 
bpo-41943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41943}: Fix bug where TestCase.assertLogs doesn't correctly filter
messages by level.

@item 
bpo-41923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41923}: Implement 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/}, introducing @ref{7b3,,typing.TypeAlias}
annotation.

@item 
bpo-41905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41905}: A new function in abc: `update_abstractmethods' to re-calculate
an abstract class's abstract status. In addition, `dataclass' has been
changed to call this function.

@item 
bpo-23706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23706}: Added `newline' parameter to @code{pathlib.Path.write_text()}.

@item 
bpo-41876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41876}: Tkinter font class repr uses font name

@item 
bpo-41831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41831}: @code{str()} for the @code{type} attribute of the @code{tkinter.Event}
object always returns now the numeric code returned by Tk instead of the
name of the event type.

@item 
bpo-39337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39337}: @code{encodings.normalize_encoding()} now ignores non-ASCII
characters.

@item 
bpo-41747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41747}: Ensure all methods that generated from
@ref{1c6,,dataclasses.dataclass()} objects now have the proper @code{__qualname__}
attribute referring to the class they belong to. Patch by Batuhan Taskaya.

@item 
bpo-30681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30681}: Handle exceptions caused by unparsable date headers when using
email "default" policy.  Patch by Tim Bell, Georges Toth

@item 
bpo-41586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41586}: Add F_SETPIPE_SZ and F_GETPIPE_SZ to fcntl module. Allow
setting pipesize on subprocess.Popen.

@item 
bpo-41229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41229}: Add @code{contextlib.aclosing} for deterministic cleanup of async
generators which is analogous to @code{contextlib.closing} for non-async
generators. Patch by Joongi Kim and John Belmonte.

@item 
bpo-16396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16396}: Allow @code{ctypes.wintypes} to be imported on non-Windows
systems.

@item 
bpo-4356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4356}: Add a key function to the bisect module.

@item 
bpo-40592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40592}: @ref{49d,,shutil.which()} now ignores empty entries in
@geindex PATHEXT
@geindex variable d'environnement; PATHEXT
@code{PATHEXT} instead of treating them as a match.

@item 
bpo-40492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40492}: Fix @code{--outfile} for @ref{27,,cProfile} / @ref{ae,,profile} not
writing the output file in the original directory when the program being
profiled changes the working directory.  PR by Anthony Sottile.

@item 
bpo-34204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34204}: The @ref{c2,,shelve} module now uses
@ref{818,,pickle.DEFAULT_PROTOCOL} by default instead of @ref{a5,,pickle}
protocol @code{3}.

@item 
bpo-27321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27321}: Fixed KeyError exception when flattening an email to a string
attempts to replace a non-existent Content-Transfer-Encoding header.

@item 
bpo-38976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38976}: The @ref{6f,,http.cookiejar} module now supports the parsing of
cookies in CURL-style cookiejar files through MozillaCookieJar on all
platforms. Previously, such cookie entries would be silently ignored when
loading a cookiejar with such entries.

Additionally, the HTTP Only attribute is persisted in the object, and will
be correctly written to file if the MozillaCookieJar object is
subsequently dumped.
@end itemize

@node Documentation<33>,Tests<36>,Library<38>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id332}@anchor{18be}
@subsubsection Documentation



@itemize -

@item 
bpo-42061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42061}: Document __format__ functionality for IP addresses.

@item 
bpo-41910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41910}: Document the default implementation of @code{object.__eq__}.

@item 
bpo-42010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42010}: Clarify that subscription expressions are also valid for
certain @ref{18bf,,classes} and @ref{18c0,,types} in the standard
library, and for user-defined classes and types if the classmethod
@code{__class_getitem__()} is provided.

@item 
bpo-41805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41805}: Documented @ref{69d,,generic alias type} and
@ref{7d5,,types.GenericAlias}. Also added an entry in glossary for
@ref{422,,generic types}.

@item 
bpo-39693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39693}: Fix tarfile's extractfile documentation

@item 
bpo-39416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39416}: Document some restrictions on the default string
representations of numeric classes.
@end itemize

@node Tests<36>,Build<38>,Documentation<33>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id333}@anchor{18c1}
@subsubsection Tests



@itemize -

@item 
bpo-41739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41739}: Fix test_logging.test_race_between_set_target_and_flush(): the
test now waits until all threads complete to avoid leaking running
threads.

@item 
bpo-41970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41970}: Avoid a test failure in @code{test_lib2to3} if the module has
already imported at the time the test executes. Patch by Pablo Galindo.

@item 
bpo-41944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41944}: Tests for CJK codecs no longer call @code{eval()} on content
received via HTTP.

@item 
bpo-41306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41306}: Fixed a failure in @code{test_tk.test_widgets.ScaleTest} happening
when executing the test with Tk 8.6.10.
@end itemize

@node Build<38>,Windows<34>,Tests<36>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id334}@anchor{18c2}
@subsubsection Build



@itemize -

@item 
bpo-38980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38980}: Add @code{-fno-semantic-interposition} to both the compile and
link line when building with @code{--enable-optimizations}. Patch by Victor
Stinner and Pablo Galindo.
@end itemize

@node Windows<34>,macOS<28>,Build<38>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id335}@anchor{18c3}
@subsubsection Windows



@itemize -

@item 
bpo-38439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38439}: Updates the icons for IDLE in the Windows Store package.

@item 
bpo-38252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38252}: Use 8-byte step to detect ASCII sequence in 64-bit Windows
build.

@item 
bpo-39107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39107}: Update Tcl and Tk to 8.6.10 in Windows installer.

@item 
bpo-41557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41557}: Update Windows installer to use SQLite 3.33.0.

@item 
bpo-38324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38324}: Avoid Unicode errors when accessing certain locale data on
Windows.
@end itemize

@node macOS<28>,IDLE<25>,Windows<34>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id336}@anchor{18c4}
@subsubsection macOS



@itemize -

@item 
bpo-41471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41471}: Ignore invalid prefix lengths in system proxy excludes.
@end itemize

@node IDLE<25>,C API<37>,macOS<28>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id337}@anchor{18c5}
@subsubsection IDLE



@itemize -

@item 
bpo-33987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33987}: Mostly finish using ttk widgets, mainly for editor, settings,
and searches. Some patches by Mark Roseman.

@item 
bpo-40511@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40511}: Typing opening and closing parentheses inside the parentheses
of a function call will no longer cause unnecessary "flashing" off and on
of an existing open call-tip, e.g. when typed in a string literal.

@item 
bpo-38439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38439}: Add a 256×256 pixel IDLE icon to the Windows .ico file. Created
by Andrew Clover. Remove the low-color gif variations from the .ico file.
@end itemize

@node C API<37>,,IDLE<25>,Python 3 10 0 alpha 2
@anchor{whatsnew/changelog id338}@anchor{18c6}
@subsubsection C API



@itemize -

@item 
bpo-42157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42157}: The private @code{_PyUnicode_Name_CAPI} structure of the PyCapsule
API @code{unicodedata.ucnhash_CAPI} has been moved to the internal C API.
Patch by Victor Stinner.

@item 
bpo-42015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42015}: Fix potential crash in deallocating method objects when
dynamically allocated @ref{148d,,PyMethodDef}'s lifetime is managed through
the @code{self} argument of a @ref{142b,,PyCFunction}.

@item 
bpo-40423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40423}: The @ref{d5,,subprocess} module and @code{os.closerange} will now use
the @code{close_range(low, high, flags)} syscall when it is available for
more efficient closing of ranges of descriptors.

@item 
bpo-41845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41845}: @ref{18c7,,PyObject_GenericGetDict()} is available again in the
limited API when targeting 3.10 or later.

@item 
bpo-40422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40422}: Add @code{_Py_closerange} function to provide performant closing
of a range of file descriptors.

@item 
bpo-41986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41986}: @code{Py_FileSystemDefaultEncodeErrors} and
@code{Py_UTF8Mode} are available again in limited API.

@item 
bpo-41756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41756}: Add @code{PyIter_Send} function to allow sending value into
generator/coroutine/iterator without raising StopIteration exception to
signal return.

@item 
bpo-41784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41784}: Added @code{PyUnicode_AsUTF8AndSize} to the limited C API.
@end itemize

@node Python 3 10 0 alpha 1,Python 3 9 0 beta 1,Python 3 10 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-10-0-alpha-1}@anchor{18c8}
@subsection Python 3.10.0 alpha 1


`Release date: 2020-10-05'

@menu
* Security: Security<25>. 
* Core and Builtins: Core and Builtins<40>. 
* Library: Library<39>. 
* Documentation: Documentation<34>. 
* Tests: Tests<37>. 
* Build: Build<39>. 
* Windows: Windows<35>. 
* macOS: macOS<29>. 
* IDLE: IDLE<26>. 
* C API: C API<38>. 

@end menu

@node Security<25>,Core and Builtins<40>,,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id339}@anchor{18c9}
@subsubsection Security



@itemize -

@item 
bpo-41304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41304}: Fixes @code{python3x._pth} being ignored on Windows, caused by the
fix for bpo-29778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29778} (
@geindex Common Vulnerabilities and Exposures; CVE 2020-15801
CVE 2020-15801@footnote{https://www.cve.org/CVERecord?id=CVE-2020-15801}).

@item 
bpo-41162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41162}: Audit hooks are now cleared later during finalization to avoid
missing events.

@item 
bpo-29778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29778}: Ensure @code{python3.dll} is loaded from correct locations
when Python is embedded (
@geindex Common Vulnerabilities and Exposures; CVE 2020-15523
CVE 2020-15523@footnote{https://www.cve.org/CVERecord?id=CVE-2020-15523}).

@item 
bpo-41004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41004}: The __hash__() methods of  ipaddress.IPv4Interface and
ipaddress.IPv6Interface incorrectly generated constant hash values of 32
and 128 respectively. This resulted in always causing hash collisions. The
fix uses hash() to generate hash values for the tuple of (address, mask
length, network address).

@item 
bpo-39603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39603}: Prevent http header injection by rejecting control characters
in http.client.putrequest(...).
@end itemize

@node Core and Builtins<40>,Library<39>,Security<25>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id340}@anchor{18ca}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-41909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41909}: Fixed stack overflow in @ref{7ab,,issubclass()} and
@ref{42b,,isinstance()} when getting the @code{__bases__} attribute leads to
infinite recursion.

@item 
bpo-41922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41922}: Speed up calls to @code{reversed()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-41873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41873}: Calls to @code{float()} are now faster due to the @code{vectorcall}
calling convention. Patch by Dennis Sweeney.

@item 
bpo-41870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41870}: Speed up calls to @code{bool()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_bisect} module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39934}: Correctly count control blocks in 'except' in compiler. Ensures
that a syntax error, rather a fatal error, occurs for deeply nested, named
exception handlers.

@item 
bpo-41780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41780}: Fix @code{__dir__()} of @ref{7d5,,types.GenericAlias}. Patch by
Batuhan Taskaya.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_lsprof} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @ref{18,,cmath} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_scproxy} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @ref{e0,,termios} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Convert the @code{_sha256} extension module types to heap
types.

@item 
bpo-41690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41690}: Fix a possible stack overflow in the parser when parsing
functions and classes with a huge amount of arguments. Patch by Pablo
Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_overlapped} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_curses_panel} extension module to
multi-phase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_opcode} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41681}: Fixes the wrong error description in the error raised by using
2 @code{,} in format string in f-string and @ref{60c,,str.format()}.

@item 
bpo-41675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41675}: The implementation of @ref{1115,,signal.siginterrupt()} now uses
@code{sigaction()} (if it is available in the system) instead of the
deprecated @code{siginterrupt()}. Patch by Pablo Galindo.

@item 
bpo-41670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41670}: Prevent line trace being skipped on platforms not compiled with
@code{USE_COMPUTED_GOTOS}. Fixes issue where some lines nested within a
try-except block were not being traced on Windows.

@item 
bpo-41654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41654}: Fix a crash that occurred when destroying subclasses of
@ref{164b,,MemoryError}. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @ref{132,,zlib} extension module to multi-phase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41631}: The @code{_ast} module uses again a global state. Using a module
state per module instance is causing subtle practical problems. For
example, the Mercurial project replaces the @code{__import__()} function to
implement lazy import, whereas Python expected that @code{import _ast} always
return a fully initialized @code{_ast} module.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{_operator} to use @ref{569,,PyType_FromSpec()}.

@item 
bpo-1653741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1653741}: Port @code{_sha3} to multi-phase init.  Convert static types
to heap types.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_blake2} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41533}: Free the stack allocated in @code{va_build_stack} if
@code{do_mkstack} fails and the stack is not a @code{small_stack}.

@item 
bpo-41531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41531}: Fix a bug that was dropping keys when compiling dict literals
with more than 0xFFFF elements. Patch by Pablo Galindo.

@item 
bpo-41525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41525}: The output of @code{python --help} contains now only ASCII
characters.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_sha1}, @code{_sha512}, and @code{_md5}
extension modules to multi-phase initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41431}: Optimize @code{dict_merge()} for copying dict (e.g. @code{dict(d)}
and @code{@{@}.update(d)}).

@item 
bpo-41428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41428}: Implement PEP 604. This supports (int | str) etc. in place of
Union[str, int].

@item 
bpo-41340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41340}: Removed fallback implementation for @code{strdup}.

@item 
bpo-38156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38156}: Handle interrupts that come after EOF correctly in
@code{PyOS_StdioReadline}.

@item 
bpo-41342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41342}: @ref{12b8,,round()} with integer argument is now faster (9--60%).

@item 
bpo-41334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41334}: Constructors @ref{435,,str()}, @ref{1bd,,bytes()} and @ref{528,,bytearray()}
are now faster (around 30--40% for small objects).

@item 
bpo-41295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41295}: Resolve a regression in CPython 3.8.4 where defining
"__setattr__" in a multi-inheritance setup and calling up the hierarchy
chain could fail if builtins/extension types were involved in the base
types.

@item 
bpo-41323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41323}: Bytecode optimizations are performed directly on the control
flow graph. This will result in slightly more compact code objects in some
circumstances.

@item 
bpo-41247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41247}: Always cache the running loop holder when running
@code{asyncio.set_running_loop}.

@item 
bpo-41252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41252}: Fix incorrect refcounting in _ssl.c's
@code{_servername_callback()}.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{93,,multiprocessing} to multi-phase initialization

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{winapi} to multiphase initialization

@item 
bpo-41215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41215}: Use non-NULL default values in the PEG parser keyword list to
overcome a bug that was preventing Python from being properly compiled
when using the XLC compiler. Patch by Pablo Galindo.

@item 
bpo-41218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41218}: Python 3.8.3 had a regression where compiling with
ast.PyCF_ALLOW_TOP_LEVEL_AWAIT would aggressively mark list comprehension
with CO_COROUTINE. Now only list comprehension making use of async/await
will tagged as so.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{57,,faulthandler} to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{sha256} to multiphase initialization

@item 
bpo-41175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41175}: Guard against a NULL pointer dereference within bytearrayobject
triggered by the @code{bytearray() + bytearray()} operation.

@item 
bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100}: add arm64 to the allowable Mac OS arches in mpdecimal.h

@item 
bpo-41094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41094}: Fix decoding errors with audit when open files with non-ASCII
names on non-UTF-8 locale.

@item 
bpo-39960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39960}: The "hackcheck" that prevents sneaking around a type's
__setattr__() by calling the superclass method was rewritten to allow C
implemented heap types.

@item 
bpo-41084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41084}: Prefix the error message with 'f-string: ', when parsing an
f-string expression which throws a @ref{18b,,SyntaxError}.

@item 
bpo-40521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40521}: Empty frozensets are no longer singletons.

@item 
bpo-41076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41076}: Pre-feed the parser with the location of the f-string
expression, not the f-string itself, which allows us to skip the shifting
of the AST node locations after the parsing is completed.

@item 
bpo-41056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41056}: Fixes a reference to deallocated stack space during startup
when constructing sys.path involving a relative symlink when code was
supplied via -c.  (discovered via Coverity)

@item 
bpo-41061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41061}: Fix incorrect expressions and asserts in hashtable code and
tests.

@item 
bpo-41052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41052}: Opt out serialization/deserialization for _random.Random

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Rename @code{PyPegen*} functions to @code{PyParser*}, so that we can
remove the old set of @code{PyParser*} functions that were using the old
parser, but keep everything backwards-compatible.

@item 
bpo-35975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35975}: Stefan Behnel reported that cf_feature_version is used even
when PyCF_ONLY_AST is not set. This is against the intention and against
the documented behavior, so it's been fixed.

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Remove the remaining files from the old parser and the
@code{symbol} module.

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert @code{_bz2} to use @ref{569,,PyType_FromSpec()}.

@item 
bpo-41006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41006}: The @code{encodings.latin_1} module is no longer imported at
startup. Now it is only imported when it is the filesystem encoding or the
stdio encoding.

@item 
bpo-40636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40636}: @ref{7ba,,zip()} now supports 
@geindex Python Enhancement Proposals; PEP 618
PEP 618@footnote{https://peps.python.org/pep-0618/}'s @code{strict} parameter,
which raises a @ref{1ff,,ValueError} if the arguments are exhausted at
different lengths. Patch by Brandt Bucher.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{_gdbm} to multiphase initialization.

@item 
bpo-40985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40985}: Fix a bug that caused the @ref{18b,,SyntaxError} text to be empty
when a file ends with a line ending in a line continuation character (i.e.
backslash). The error text should contain the text of the last line.

@item 
bpo-40958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40958}: Fix a possible buffer overflow in the PEG parser when gathering
information for emitting syntax errors. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{_dbm} to multiphase initialization.

@item 
bpo-40957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40957}: Fix refleak in _Py_fopen_obj() when PySys_Audit() fails

@item 
bpo-40950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40950}: Add a state to the @code{nis} module (
@geindex Python Enhancement Proposals; PEP 3121
PEP 3121@footnote{https://peps.python.org/pep-3121/}) and apply
the multiphase initialization. Patch by Donghee Na.

@item 
bpo-40947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40947}: The Python @ref{89a,,Path Configuration} now
takes @ref{18cb,,PyConfig.platlibdir} in account.

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Remove the old parser, the @code{parser} module and all
associated support code, command-line options and environment variables.
Patch by Pablo Galindo.

@item 
bpo-40847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40847}: Fix a bug where a line with only a line continuation character
is not considered a blank line at tokenizer level. In such cases, more
than a single @code{NEWLINE} token was emitted. The old parser was working
around the issue, but the new parser threw a @ref{18b,,SyntaxError} for valid
input due to this. For example, an empty line following a line
continuation character was interpreted as a @ref{18b,,SyntaxError}.

@item 
bpo-40890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40890}: Each dictionary view now has a @code{mapping} attribute that
provides a @ref{457,,types.MappingProxyType} wrapping the original
dictionary.  Patch contributed by Dennis Sweeney.

@item 
bpo-40889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40889}: Improved the performance of symmetric difference operations on
dictionary item views.  Patch by Dennis Sweeney.

@item 
bpo-40904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40904}: Fix possible segfault in the new PEG parser when parsing
f-string containing yield statements with no value (@code{f"@{yield@}"}).
Patch by Pablo Galindo

@item 
bpo-40903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40903}: Fixed a possible segfault in the new PEG parser when producing
error messages for invalid assignments of the form @code{p=p=}. Patch by
Pablo Galindo

@item 
bpo-40880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40880}: Fix invalid memory read in the new parser when checking
newlines in string literals. Patch by Pablo Galindo.

@item 
bpo-40883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40883}: Fix memory leak in when parsing f-strings in the new parser.
Patch by Pablo Galindo

@item 
bpo-40870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40870}: Raise @ref{1ff,,ValueError} when validating custom AST's where the
constants @code{True}, @code{False} and @code{None} are used within a
@ref{18cc,,ast.Name} node.

@item 
bpo-40854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40854}: Allow overriding @ref{925,,sys.platlibdir} via a new
@geindex PYTHONPLATLIBDIR
@geindex variable d'environnement; PYTHONPLATLIBDIR
@ref{18cd,,PYTHONPLATLIBDIR} environment variable.

@item 
bpo-40826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40826}: Fix GIL usage in @code{PyOS_Readline()}: lock the GIL to set
an exception and pass the Python thread state when checking if there is a
pending signal.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{58,,fcntl} to multiphase initialization.

@item 
bpo-19468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19468}: Delete unnecessary instance check in importlib.reload(). Patch
by Furkan Önder.

@item 
bpo-40824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40824}: Unexpected errors in calling the @code{__iter__} method are no
longer masked by @code{TypeError} in the @ref{2e8,,in} operator and functions
@ref{8c7,,contains()}, @ref{8c8,,indexOf()} and
@ref{8c9,,countOf()} of the @ref{9e,,operator} module.

@item 
bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792}: Attributes @code{start}, @code{stop} and @code{step} of the
@ref{930,,range} object now always has exact type @ref{254,,int}.  Previously,
they could have been an instance of a subclass of @code{int}.

@item 
bpo-40780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40780}: Fix a corner case where g-style string formatting of a float
failed to remove trailing zeros.

@item 
bpo-38964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38964}: When there's a @ref{18b,,SyntaxError} in the expression part of an
fstring, the filename attribute of the @ref{18b,,SyntaxError} gets correctly
set to the name of the file the fstring resides in.

@item 
bpo-40750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40750}: Support the "-d" debug flag in the new PEG parser. Patch by
Pablo Galindo

@item 
bpo-40217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40217}: Instances of types created with
@ref{56a,,PyType_FromSpecWithBases()} will no longer automatically visit
their class object when traversing references in the garbage collector.
The user is expected to manually visit the object's class. Patch by Pablo
Galindo.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: @ref{76a,,Py_TYPE()} is changed to the inline static function.
Patch by Donghee Na.

@item 
bpo-40696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40696}: Fix a hang that can arise after @ref{4e2,,generator.throw()} due to
a cycle in the exception context chain.

@item 
bpo-40521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40521}: Each interpreter now its has own free lists, singletons and
caches:


@itemize *

@item 
Free lists: float, tuple, list, dict, frame, context,
asynchronous generator, MemoryError.

@item 
Singletons: empty tuple, empty bytes string, empty Unicode string,
single byte character, single Unicode (latin1) character.

@item 
Slice cache.
@end itemize

They are no longer shared by all interpreters.

@item 
bpo-40679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40679}: Certain @ref{522,,TypeError} messages about missing or extra
arguments now include the function's @ref{18ce,,qualified name}.  Patch by
Dennis Sweeney.

@item 
bpo-29590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29590}: Make the stack trace correct after calling
@ref{4e2,,generator.throw()} on a generator that has yielded from a @code{yield
from}.

@item 
bpo-4022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4022}: Improve performance of generators by not raising internal
StopIteration.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{8f,,mmap} to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @code{_lzma} to multiphase initialization.

@item 
bpo-37999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37999}: Builtin and extension functions that take integer arguments no
longer accept @ref{29a,,Decimal}s, @ref{1e4,,Fraction}s and other objects that can be converted to integers only with a loss
(e.g. that have the @ref{706,,__int__()} method but do not have the
@ref{707,,__index__()} method).

@item 
bpo-29882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29882}: Add @ref{7b6,,int.bit_count()}, counting the number of ones in the
binary representation of an integer. Patch by Niklas Fiekas.

@item 
bpo-36982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36982}: Use ncurses extended color functions when available to support
terminals with 256 colors, and add the new function
@ref{7df,,curses.has_extended_color_support()} to indicate whether extended
color support is provided by the underlying ncurses library.

@item 
bpo-19569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19569}: Add the private macros @code{_Py_COMP_DIAG_PUSH},
@code{_Py_COMP_DIAG_IGNORE_DEPR_DECLS}, and @code{_Py_COMP_DIAG_POP}.

@item 
bpo-26680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26680}: The int type now supports the x.is_integer() method for
compatibility with float.
@end itemize

@node Library<39>,Documentation<34>,Core and Builtins<40>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id341}@anchor{18cf}
@subsubsection Library



@itemize -

@item 
bpo-41900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41900}: C14N 2.0 serialisation in xml.etree.ElementTree failed for
unprefixed attributes when a default namespace was defined.

@item 
bpo-41887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41887}: Strip leading spaces and tabs on @ref{c06,,ast.literal_eval()}. Also
document stripping of spaces and tabs for @ref{17e,,eval()}.

@item 
bpo-41773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41773}: Note in documentation that @ref{cb4,,random.choices()} doesn't
support non-finite weights, raise @ref{1ff,,ValueError} when given non-finite
weights.

@item 
bpo-41840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41840}: Fix a bug in the @ref{d7,,symtable} module that was causing
module-scope global variables to not be reported as both local and global.
Patch by Pablo Galindo.

@item 
bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}: Add @ref{7d2,,codecs.unregister()} function to unregister a codec
search function.

@item 
bpo-40564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40564}: In @code{zipfile.Path}, mutate the passed ZipFile object type
instead of making a copy. Prevents issues when both the local copy and the
caller’s copy attempt to close the same file handle.

@item 
bpo-40670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40670}: More reliable validation of statements in
@ref{147c,,timeit.Timer}. It now accepts "empty" statements (only whitespaces
and comments) and rejects misindentent statements.

@item 
bpo-41833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41833}: The @ref{939,,threading.Thread} constructor now uses the target
name if the `target' argument is specified but the `name' argument is
omitted.

@item 
bpo-41817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41817}: fix @code{tkinter.EventType} Enum so all members are strings, and
none are tuples

@item 
bpo-41810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41810}: @ref{83b,,types.EllipsisType}, @ref{83d,,types.NotImplementedType}
and @ref{83c,,types.NoneType} have been reintroduced, providing a new set of
types readily interpretable by static type checkers.

@item 
bpo-41815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41815}: Fix SQLite3 segfault when backing up closed database. Patch
contributed by Peter David McCormick.

@item 
bpo-41816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41816}: StrEnum added: it ensures that all members are already strings
or string candidates

@item 
bpo-41517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41517}: fix bug allowing Enums to be extended via multiple inheritance

@item 
bpo-39587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39587}: use the correct mix-in data type when constructing Enums

@item 
bpo-41792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41792}: Add is_typeddict function to typing.py to check if a type is a
TypedDict class

Previously there was no way to check that without using private API. See
the relevant issue in python/typing@footnote{https://github.com/python/typing/issues/751}.

@item 
bpo-41789@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41789}: Honor @code{object} overrides in @code{Enum} class creation
(specifically, @code{__str__}, @code{__repr__}, @code{__format__}, and
@code{__reduce_ex__}).

@item 
bpo-32218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32218}: @code{enum.Flag} and @code{enum.IntFlag} members are now iterable.

@item 
bpo-39651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39651}: Fix a race condition in the @code{call_soon_threadsafe()} method
of @code{asyncio.ProactorEventLoop}: do nothing if the self-pipe socket has
been closed.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{mashal} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port the @code{_string} extension module to the multi-phase
initialization API (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-41732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41732}: Added an @ref{1aa,,iterator} to @ref{452,,memoryview}.

@item 
bpo-41720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41720}: Fixed @code{turtle.Vec2D.__rmul__()} for arguments which are not
int or float.

@item 
bpo-41696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41696}: Fix handling of debug mode in @ref{466,,asyncio.run()}. This allows
setting @code{PYTHONASYNCIODEBUG} or @code{-X dev} to enable asyncio debug mode
when using @ref{466,,asyncio.run()}.

@item 
bpo-41687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41687}: Fix implementation of sendfile to be compatible with Solaris.

@item 
bpo-41662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41662}: No longer override exceptions raised in @code{__len__()} of a
sequence of parameters in @ref{ce,,sqlite3} with
@ref{4dc,,ProgrammingError}.

@item 
bpo-39010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39010}: Restarting a @code{ProactorEventLoop} on Windows no longer logs
spurious @code{ConnectionResetErrors}.

@item 
bpo-41638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41638}: @ref{4dc,,ProgrammingError} message for absent parameter
in @ref{ce,,sqlite3} contains now the name of the parameter instead of its
index when parameters are supplied as a dict.

@item 
bpo-41662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41662}: Fixed crash when mutate list of parameters during iteration in
@ref{ce,,sqlite3}.

@item 
bpo-41513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41513}: Improved the accuracy of math.hypot().  Internally, each step
is computed with extra precision so that the result is now almost always
correctly rounded.

@item 
bpo-41609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41609}: The pdb whatis command correctly reports instance methods as
'Method' rather than 'Function'.

@item 
bpo-39994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39994}: Fixed pprint's handling of dict subclasses that override
__repr__.

@item 
bpo-32751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32751}: When cancelling the task due to a timeout,
@ref{5ea,,asyncio.wait_for()} will now wait until the cancellation is complete
also in the case when `timeout' is <= 0, like it does with positive
timeouts.

@item 
bpo-37658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37658}: @ref{5ea,,asyncio.wait_for()} now properly handles races between
cancellation of itself and the completion of the wrapped awaitable.

@item 
bpo-40782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40782}: Change the method asyncio.AbstractEventLoop.run_in_executor to
not be a coroutine.

@item 
bpo-41520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41520}: Fix @ref{1c,,codeop} regression that prevented turning compile
warnings into errors.

@item 
bpo-41528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41528}: turtle uses math module functions to convert degrees to radians
and vice versa and to calculate vector norm

@item 
bpo-41513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41513}: Minor algorithmic improvement to math.hypot() and math.dist()
giving small gains in speed and accuracy.

@item 
bpo-41503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41503}: Fixed a race between setTarget and flush in
logging.handlers.MemoryHandler.

@item 
bpo-41497@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41497}: Fix potential UnicodeDecodeError in dis module.

@item 
bpo-41467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41467}: On Windows, fix asyncio @code{recv_into()} return value when the
socket/pipe is closed (@ref{1045,,BrokenPipeError}): return @code{0} rather than
an empty byte string (@code{b'@w{'}}).

@item 
bpo-41425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41425}: Make tkinter doc example runnable.

@item 
bpo-41421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41421}: Make an algebraic simplification to random.paretovariate().  It
now is slightly less subject to round-off error and is slightly faster.
Inputs that used to cause ZeroDivisionError now cause an OverflowError
instead.

@item 
bpo-41440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41440}: Add @ref{1c0,,os.cpu_count()} support for VxWorks RTOS.

@item 
bpo-41316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41316}: Fix the @ref{dd,,tarfile} module to write only basename of TAR
file to GZIP compression header.

@item 
bpo-41384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41384}: Raise TclError instead of TypeError when an unknown option is
passed to tkinter.OptionMenu.

@item 
bpo-41317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41317}: Use add_done_callback() in asyncio.loop.sock_accept() to
unsubscribe reader early on cancellation.

@item 
bpo-41364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41364}: Reduce import overhead of @ref{10f,,uuid}.

@item 
bpo-35328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35328}: Set the environment variable @code{VIRTUAL_ENV_PROMPT} at
@ref{110,,venv} activation.

@item 
bpo-41341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41341}: Recursive evaluation of @code{typing.ForwardRef} in
@code{get_type_hints}.

@item 
bpo-41344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41344}: Prevent creating @code{shared_memory.SharedMemory} objects
with @code{size=0}.

@item 
bpo-41333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41333}: @code{collections.OrderedDict.pop()} is now 2 times faster.

@item 
bpo-41288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41288}: Unpickling invalid NEWOBJ_EX opcode with the C implementation
raises now UnpicklingError instead of crashing.

@item 
bpo-39017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39017}: Avoid infinite loop when reading specially crafted TAR files
using the tarfile module (
@geindex Common Vulnerabilities and Exposures; CVE 2019-20907
CVE 2019-20907@footnote{https://www.cve.org/CVERecord?id=CVE-2019-20907}).

@item 
bpo-41273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41273}: Speed up any transport using @code{_ProactorReadPipeTransport} by
calling @code{recv_into} instead of @code{recv}, thus not creating a new buffer
for each @code{recv} call in the transport's read loop.

@item 
bpo-41235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41235}: Fix the error handling in
@ref{1122,,ssl.SSLContext.load_dh_params()}.

@item 
bpo-41207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41207}: In distutils.spawn, restore expectation that DistutilsExecError
is raised when the command is not found.

@item 
bpo-29727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29727}: Register @ref{19e,,array.array} as a
@ref{19f,,MutableSequence}. Patch by Pablo Galindo.

@item 
bpo-39168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39168}: Remove the @code{__new__} method of @ref{15a1,,typing.Generic}.

@item 
bpo-41194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41194}: Fix a crash in the @code{_ast} module: it can no longer be loaded
more than once. It now uses a global state rather than a module state.

@item 
bpo-41195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41195}: Add read-only ssl.SSLContext.security_level attribute to
retrieve the context's security level.

@item 
bpo-41193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41193}: The @code{write_history()} atexit function of the readline
completer now ignores any @ref{40d,,OSError} to ignore error if the filesystem
is read-only, instead of only ignoring @ref{eae,,FileNotFoundError} and
@ref{d30,,PermissionError}.

@item 
bpo-41182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41182}: selector: use DefaultSelector based upon implementation

@item 
bpo-41161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41161}: The decimal module now requires libmpdec-2.5.0. Users of
--with-system-libmpdec should update their system library.

@item 
bpo-40874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40874}: The decimal module now requires libmpdec-2.5.0.

@item 
bpo-41138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41138}: Fixed the @ref{fc,,trace} module CLI for Python source files with
non-UTF-8 encoding.

@item 
bpo-31082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31082}: Use the term "iterable" in the docstring for
@ref{12ba,,functools.reduce()}.

@item 
bpo-40521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40521}: Remove freelist from collections.deque().

@item 
bpo-31938@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31938}: Fix default-value signatures of several functions in the
@ref{c0,,select} module - by Anthony Sottile.

@item 
bpo-41068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41068}: Fixed reading files with non-ASCII names from ZIP archive
directly after writing them.

@item 
bpo-41058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41058}: @code{pdb.find_function()} now correctly determines the source
file encoding.

@item 
bpo-41056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41056}: Invalid file descriptor values are now prevented from being
passed to os.fpathconf. (discovered by Coverity)

@item 
bpo-41056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41056}: Fix a NULL pointer dereference within the ssl module during a
MemoryError in the keylog callback. (discovered by Coverity)

@item 
bpo-41056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41056}: Fixed an instance where a MemoryError within the zoneinfo
module might not be reported or not reported at its source. (found by
Coverity)

@item 
bpo-41048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41048}: @ref{18d0,,mimetypes.read_mime_types()} function reads the rule file
using UTF-8 encoding, not the locale encoding. Patch by Srinivas Reddy
Thatiparthy.

@item 
bpo-41043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41043}: Fixed the use of @ref{29c,,glob()} in the stdlib: literal part
of the path is now always correctly escaped.

@item 
bpo-41025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41025}: Fixed an issue preventing the C implementation of
@ref{8cc,,zoneinfo.ZoneInfo} from being subclassed.

@item 
bpo-35018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35018}: Add the @ref{846,,xml.sax.handler.LexicalHandler} class that is
present in other SAX XML implementations.

@item 
bpo-41002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41002}: Improve performance of HTTPResponse.read with a given amount.
Patch by Bruce Merry.

@item 
bpo-40448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40448}: @ref{54,,ensurepip} now disables the use of @code{pip} cache when
installing the bundled versions of @code{pip} and @code{setuptools}.  Patch by
Krzysztof Konopko.

@item 
bpo-40967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40967}: Removed @code{asyncio.Task.current_task()} and
@code{asyncio.Task.all_tasks()}. Patch contributed by Rémi Lapeyre.

@item 
bpo-40924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40924}: Ensure @code{importlib.resources.path} returns an extant path for
the SourceFileLoader's resource reader. Avoids the regression identified
in master while a long-term solution is devised.

@item 
bpo-40955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40955}: Fix a minor memory leak in @ref{d5,,subprocess} module when
extra_groups was specified.

@item 
bpo-40855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40855}: The standard deviation and variance functions in the statistics
module were ignoring their mu and xbar arguments.

@item 
bpo-40939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40939}: Use the new PEG parser when generating the stdlib
@ref{83,,keyword} module.

@item 
bpo-23427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23427}: Add @ref{82a,,sys.orig_argv} attribute: the list of the original
command line arguments passed to the Python executable.

@item 
bpo-33689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33689}: Ignore empty or whitespace-only lines in .pth files. This
matches the documentated behavior. Before, empty lines caused the
site-packages dir to appear multiple times in sys.path. By Ido Michael,
contributors Malcolm Smith and Tal Einat.

@item 
bpo-40884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40884}: Added a @code{defaults} parameter to @ref{1449,,logging.Formatter},
to allow specifying default values for custom fields. Patch by Asaf Alon
and Bar Harel.

@item 
bpo-40876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40876}: Clarify error message in the @ref{29,,csv} module.

@item 
bpo-39791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39791}: Refresh importlib.metadata from importlib_metadata 1.6.1.

@item 
bpo-40807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40807}: Stop codeop._maybe_compile, used by code.InteractiveInterpreter
(and IDLE). from emitting each warning three times.

@item 
bpo-32604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32604}: Fix reference leak in the @ref{c0,,select} module when the module
is imported in a subinterpreter.

@item 
bpo-39791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39791}: Built-in loaders (SourceFileLoader and ZipImporter) now supply
@code{TraversableResources} implementations for @code{ResourceReader}, and the
fallback function has been removed.

@item 
bpo-39314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39314}: @ref{18d1,,rlcompleter.Completer} and the standard Python shell
now close the parenthesis for functions that take no arguments. Patch
contributed by Rémi Lapeyre.

@item 
bpo-17005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17005}: The topological sort functionality that was introduced
initially in the @ref{5e,,functools} module has been moved to a new
@ref{64,,graphlib} module to better accommodate the new tools and keep the
original scope of the @ref{5e,,functools} module. Patch by Pablo Galindo

@item 
bpo-40834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40834}: Fix truncate when sending str object
with_xxsubinterpreters.channel_send.

@item 
bpo-40755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40755}: Add rich comparisons to collections.Counter().

@item 
bpo-26407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26407}: Unexpected errors in calling the @code{__iter__} method are no
longer masked by @code{TypeError} in @ref{470,,csv.reader()},
@code{csv.writer.writerow()} and @code{csv.writer.writerows()}.

@item 
bpo-39384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39384}: Fixed email.contentmanager to allow set_content() to set a null
string.

@item 
bpo-40744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40744}: The @ref{ce,,sqlite3} module uses SQLite API functions that
require SQLite v3.7.3 or higher.  This patch removes support for older
SQLite versions, and explicitly requires SQLite 3.7.3 both at build,
compile and runtime.  Patch by Sergey Fedoseev and Erlend E. Aasland.

@item 
bpo-40777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40777}: Initialize PyDateTime_IsoCalendarDateType.tp_base at run-time
to avoid errors on some compilers.

@item 
bpo-38488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38488}: Update ensurepip to install pip 20.1.1 and setuptools 47.1.0.

@item 
bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792}: The result of @ref{189c,,operator.index()} now always has exact type
@ref{254,,int}. Previously, the result could have been an instance of a
subclass of @code{int}.

@item 
bpo-40767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40767}: @ref{114,,webbrowser} now properly finds the default browser in
pure Wayland systems by checking the WAYLAND_DISPLAY environment variable.
Patch contributed by Jérémy Attali.

@item 
bpo-40791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40791}: @code{hashlib.compare_digest()} uses OpenSSL's
@code{CRYPTO_memcmp()} function when OpenSSL is available.

@item 
bpo-40795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40795}: @ref{2a,,ctypes} module: If ctypes fails to convert the result of
a callback or if a ctypes callback function raises an exception,
sys.unraisablehook is now called with an exception set. Previously, the
error was logged into stderr by @ref{18d2,,PyErr_Print()}.

@item 
bpo-16995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16995}: Add @ref{7cd,,base64.b32hexencode()} and @ref{7ce,,base64.b32hexdecode()}
to support the Base32 Encoding with Extended Hex Alphabet.

@item 
bpo-30008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30008}: Fix @ref{cf,,ssl} code to be compatible with OpenSSL 1.1.x builds
that use @code{no-deprecated} and @code{--api=1.1.0}.

@item 
bpo-30064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30064}: Fix asyncio @code{loop.sock_*} race condition issue

@item 
bpo-40759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40759}: Deprecate the @code{symbol} module.

@item 
bpo-40756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40756}: The second argument (extra) of @code{LoggerAdapter.__init__} now
defaults to None.

@item 
bpo-37129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37129}: Add a new @ref{18d3,,os.RWF_APPEND} flag for @ref{b4e,,os.pwritev()}.

@item 
bpo-40737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40737}: Fix possible reference leak for @ref{ce,,sqlite3} initialization.

@item 
bpo-40726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40726}: Handle cases where the @code{end_lineno} is @code{None} on
@ref{1724,,ast.increment_lineno()}.

@item 
bpo-40698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40698}: @code{distutils} upload creates SHA2-256 and Blake2b-256 digests.
MD5 digests is skipped if platform blocks MD5.

@item 
bpo-40695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40695}: @ref{67,,hashlib} no longer falls back to builtin hash
implementations when OpenSSL provides a hash digest and the algorithm is
blocked by security policy.

@item 
bpo-9216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9216}: @ref{18d4,,hashlib.new()} passed @code{usedforsecurity} to OpenSSL EVP
constructor @code{_hashlib.new()}. test_hashlib and test_smtplib handle
strict security policy better.

@item 
bpo-40614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40614}: @ref{1a6,,ast.parse()} will not parse self documenting expressions
in f-strings when passed @code{feature_version} is less than @code{(3, 8)}.

@item 
bpo-40626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40626}: Add h5 file extension as MIME Type application/x-hdf5, as per
HDF Group recommendation for HDF5 formatted data files. Patch contributed
by Mark Schwab.

@item 
bpo-25920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25920}: On macOS, when building Python for macOS 10.4 and older, which
wasn't the case for python.org macOS installer, @ref{16e0,,socket.getaddrinfo()}
no longer uses an internal lock to prevent race conditions when calling
@code{getaddrinfo()} which is thread-safe since macOS 10.5. Python 3.9
requires macOS 10.6 or newer. The internal lock caused random hang on fork
when another thread was calling @ref{16e0,,socket.getaddrinfo()}. The lock was
also used on FreeBSD older than 5.3, OpenBSD older than 201311 and NetBSD
older than 4.

@item 
bpo-40671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40671}: Prepare @code{_hashlib} for 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} and use
@ref{962,,PyModule_AddType()}.

@item 
bpo-32309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32309}: Added a new @ref{47b,,coroutine} @ref{8d5,,asyncio.to_thread()}. It is
mainly used for running IO-bound functions in a separate thread to avoid
blocking the event loop, and essentially works as a high-level version of
@ref{8d6,,run_in_executor()} that can directly take keyword
arguments.

@item 
bpo-36543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36543}: Restored the deprecated @code{xml.etree.cElementTree} module.

@item 
bpo-40611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40611}: @ref{18d5,,MAP_POPULATE} constant has now been added to the
list of exported @ref{8f,,mmap} module flags.

@item 
bpo-39881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39881}: PEP 554 for use in the test suite. (Patch By Joannah Nanjekye)

@item 
bpo-13097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13097}: @code{ctypes} now raises an @code{ArgumentError} when a callback is
invoked with more than 1024 arguments.

@item 
bpo-39385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39385}: A new test assertion context-manager,
@code{unittest.assertNoLogs()} will ensure a given block of code emits no
log messages using the logging module. Contributed by Kit Yan Choi.

@item 
bpo-23082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23082}: Updated the error message and docs of PurePath.relative_to() to
better reflect the function behaviour.

@item 
bpo-40318@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40318}: Use SQLite3 trace v2 API, if it is available.

@item 
bpo-40105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40105}: ZipFile truncates files to avoid corruption when a shorter
comment is provided in append ("a") mode. Patch by Jan Mazur.

@item 
bpo-40084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40084}: Fix @code{Enum.__dir__}: dir(Enum.member) now includes attributes
as well as methods.

@item 
bpo-31122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31122}: ssl.wrap_socket() now raises ssl.SSLEOFError rather than
OSError when peer closes connection during TLS negotiation

@item 
bpo-39728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39728}: fix default @code{_missing_} so a duplicate @code{ValueError} is not
set as the @code{__context__} of the original @code{ValueError}.

@item 
bpo-39244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39244}: Fixed @code{multiprocessing.context.get_all_start_methods} to
properly return the default method first on macOS.

@item 
bpo-39040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39040}: Fix parsing of invalid mime headers parameters by collapsing
whitespace between encoded words in a bare-quote-string.

@item 
bpo-38731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38731}: Add @code{--quiet} option to command-line interface of
@ref{b2,,py_compile}. Patch by Gregory Schevchenko.

@item 
bpo-35714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35714}: @ref{1301,,struct.error} is now raised if there is a null character
in a @ref{d4,,struct} format string.

@item 
bpo-38144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38144}: Added the `root_dir' and `dir_fd' parameters in
@ref{29c,,glob.glob()}.

@item 
bpo-26543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26543}: Fix @code{IMAP4.noop()} when debug mode is enabled (ex:
@code{imaplib.Debug = 3}).

@item 
bpo-12178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12178}: @ref{471,,csv.writer()} now correctly escapes `escapechar' when
input contains `escapechar'.  Patch by Catalin Iacob, Berker Peksag, and
Itay Elbirt.

@item 
bpo-36290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36290}: AST nodes are now raising @ref{522,,TypeError} on conflicting
keyword arguments. Patch contributed by Rémi Lapeyre.

@item 
bpo-33944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33944}: Added site.py site-packages tracing in verbose mode.

@item 
bpo-35078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35078}: Refactor formatweekday, formatmonthname methods in
LocaleHTMLCalendar and LocaleTextCalendar classes in calendar module to
call the base class methods.This enables customizable CSS classes for
LocaleHTMLCalendar. Patch by Srinivas Reddy Thatiparthy

@item 
bpo-29620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29620}: @ref{1144,,assertWarns()} no longer raises a
@code{RuntimeException} when accessing a module's @code{__warningregistry__}
causes importation of a new module, or when a new module is imported in
another thread. Patch by Kernc.

@item 
bpo-31844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31844}: Remove @code{ParserBase.error()} method from the private and
undocumented @code{_markupbase} module.  @ref{862,,html.parser.HTMLParser} is
the only subclass of @code{ParserBase} and its @code{error()} implementation was
deprecated in Python 3.4 and removed in Python 3.5.

@item 
bpo-34226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34226}: Fix @code{cgi.parse_multipart} without content_length. Patch by
Roger Duran

@item 
bpo-33660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33660}: Fix pathlib.PosixPath to resolve a relative path located on the
root directory properly.

@item 
bpo-28557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28557}: Improve the error message for a misbehaving @code{rawio.readinto}

@item 
bpo-26680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26680}: The d.is_integer() method is added to the Decimal type, for
compatibility with other number types.

@item 
bpo-26680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26680}: The x.is_integer() method is incorporated into the abstract
types of the numeric tower, Real, Rational and Integral, with appropriate
default implementations.
@end itemize

@node Documentation<34>,Tests<37>,Library<39>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id342}@anchor{18d6}
@subsubsection Documentation



@itemize -

@item 
bpo-41428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41428}: Add documentation for 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} (Allow writing union types as
@code{X | Y}).

@item 
bpo-41774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41774}: In Programming FAQ "Sequences (Tuples/Lists)" section, add "How
do you remove multiple items from a list".

@item 
bpo-35293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35293}: Fix RemovedInSphinx40Warning when building the documentation.
Patch by Donghee Na.

@item 
bpo-37149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37149}: Change Shipman tkinter doc link from archive.org to TkDocs.
(The doc has been removed from the NMT server.)  The new link responds
much faster and includes a short explanatory note.

@item 
bpo-41726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41726}: Update the refcounts info of @code{PyType_FromModuleAndSpec}.

@item 
bpo-41624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41624}: Fix the signature of @ref{18d7,,typing.Coroutine}.

@item 
bpo-40204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40204}: Enable Sphinx 3.2 @code{c_allow_pre_v3} option and disable
@code{c_warn_on_allowed_pre_v3} option to make the documentation compatible
with Sphinx 2 and Sphinx 3.

@item 
bpo-41045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41045}: Add documentation for debug feature of f-strings.

@item 
bpo-41314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41314}: Changed the release when @code{from __future__ import annotations}
becomes the default from @code{4.0} to @code{3.10} (following a change in PEP
563).

@item 
bpo-40979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40979}: Refactored typing.rst, arranging more than 70 classes,
functions, and decorators into new sub-sections.

@item 
bpo-40552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40552}: Fix in tutorial section 4.2. Code snippet is now correct.

@item 
bpo-39883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39883}: Make code, examples, and recipes in the Python documentation be
licensed under the more permissive BSD0 license in addition to the
existing Python 2.0 license.

@item 
bpo-37703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37703}: Updated Documentation to comprehensively elaborate on the
behaviour of gather.cancel()
@end itemize

@node Tests<37>,Build<39>,Documentation<34>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id343}@anchor{18d8}
@subsubsection Tests



@itemize -

@item 
bpo-41939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41939}: Fix test_site.test_license_exists_at_url(): call
@code{urllib.request.urlcleanup()} to reset the global
@code{urllib.request._opener}. Patch by Victor Stinner.

@item 
bpo-41731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41731}: Make test_cmd_line_script pass with option '-vv'.

@item 
bpo-41602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41602}: Add tests for SIGINT handling in the runpy module.

@item 
bpo-41521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41521}: @ref{e3,,test.support}: Rename @code{blacklist} parameter of
@ref{18d9,,check__all__()} to @code{not_exported}.

@item 
bpo-41477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41477}: Make ctypes optional in test_genericalias.

@item 
bpo-41085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41085}: Fix integer overflow in the @ref{7ca,,array.array.index()} method on
64-bit Windows for index larger than @code{2**31}.

@item 
bpo-41069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41069}: @code{test.support.TESTFN} and the current directory for tests
when run via @code{test.regrtest} contain now non-ascii characters if
possible.

@item 
bpo-38377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38377}: On Linux, skip tests using multiprocessing if the current user
cannot create a file in @code{/dev/shm/} directory. Add the
@ref{18da,,skip_if_broken_multiprocessing_synchronize()} function
to the @ref{e3,,test.support} module.

@item 
bpo-41009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41009}: Fix use of @code{support.require_@{linux|mac|freebsd@}_version()}
decorators as class decorator.

@item 
bpo-41003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41003}: Fix @code{test_copyreg} when @code{numpy} is installed:
@code{test.pickletester} now saves/restores warnings filters when importing
@code{numpy}, to ignore filters installed by @code{numpy}.

@item 
bpo-40964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40964}: Disable remote @ref{73,,imaplib} tests, host cyrus.andrew.cmu.edu
is blocking incoming connections.

@item 
bpo-40927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40927}: Fix test_binhex when run twice: it now uses
import_fresh_module() to ensure that it raises DeprecationWarning each
time.

@item 
bpo-17258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17258}: Skip some @ref{93,,multiprocessing} tests when MD5 hash digest is
blocked.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Increase LOOPBACK_TIMEOUT to 10 for VxWorks RTOS.

@item 
bpo-38169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38169}: Increase code coverage for SharedMemory and ShareableList

@item 
bpo-34401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34401}: Make test_gdb properly run on HP-UX. Patch by Michael Osipov.
@end itemize

@node Build<39>,Windows<35>,Tests<37>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id344}@anchor{18db}
@subsubsection Build



@itemize -

@item 
bpo-38249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38249}: Update @ref{ba3,,Py_UNREACHABLE} to use __builtin_unreachable()
if only the compiler is able to use it. Patch by Donghee Na.

@item 
bpo-41617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41617}: Fix @code{pycore_bitutils.h} header file to support old clang
versions: @code{__builtin_bswap16()} is not available in LLVM clang 3.0.

@item 
bpo-40204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40204}: Pin Sphinx version to 2.3.1 in @code{Doc/Makefile}.

@item 
bpo-36020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36020}: The C99 functions @code{snprintf()} and @code{vsnprintf()}
are now required to build Python.

@item 
bpo-40684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40684}: @code{make install} now uses the @code{PLATLIBDIR} variable for the
destination @code{lib-dynload/} directory when @code{./configure
--with-platlibdir} is used.

@item 
bpo-40683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40683}: Fixed an issue where the @ref{133,,zoneinfo} module and its tests
were not included when Python is installed with @code{make}.
@end itemize

@node Windows<35>,macOS<29>,Build<39>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id345}@anchor{18dc}
@subsubsection Windows



@itemize -

@item 
bpo-41744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41744}: Fixes automatic import of props file when using the Nuget
package.

@item 
bpo-41627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41627}: The user site directory for 32-bit now includes a @code{-32}
suffix to distinguish it from the 64-bit interpreter's directory.

@item 
bpo-41526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41526}: Fixed layout of final page of the installer by removing the
special thanks to Mark Hammond (with his permission).

@item 
bpo-41492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41492}: Fixes the description that appears in UAC prompts.

@item 
bpo-40948@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40948}: Improve post-install message to direct people to the "py"
command.

@item 
bpo-41412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41412}: The installer will now fail to install on Windows 7 and Windows
8. Further, the UCRT dependency is now always downloaded on demand.

@item 
bpo-40741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40741}: Update Windows release to include SQLite 3.32.3.

@item 
bpo-41142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41142}: @code{msilib} now supports creating CAB files with non-ASCII
file path and adding files with non-ASCII file path to them.

@item 
bpo-41074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41074}: Fixed support of non-ASCII names in functions
@code{msilib.OpenDatabase()} and @code{msilib.init_database()} and
non-ASCII SQL in method @code{msilib.Database.OpenView()}.

@item 
bpo-41039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41039}: Stable ABI redirection DLL (python3.dll) now uses @code{#pragma
comment(linker)} for re-exporting.

@item 
bpo-40164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40164}: Updates Windows OpenSSL to 1.1.1g

@item 
bpo-39631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39631}: Changes the registered MIME type for @code{.py} files on Windows
to @code{text/x-python} instead of @code{text/plain}.

@item 
bpo-40677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40677}: Manually define IO_REPARSE_TAG_APPEXECLINK in case some old
Windows SDK doesn't have it.

@item 
bpo-37556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37556}: Extend py.exe help to mention overrides via venv, shebang,
environmental variables & ini files.
@end itemize

@node macOS<29>,IDLE<26>,Windows<35>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id346}@anchor{18dd}
@subsubsection macOS



@itemize -

@item 
bpo-41557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41557}: Update macOS installer to use SQLite 3.33.0.

@item 
bpo-39580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39580}: Avoid opening Finder window if running installer from the
command line. Patch contributed by Rick Heil.

@item 
bpo-41100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41100}: Fix configure error when building on macOS 11. Note that the
current Python release was released shortly after the first developer
preview of macOS 11 (Big Sur); there are other known issues with building
and running on the developer preview. Big Sur is expected to be fully
supported in a future bugfix release of Python 3.8.x and with 3.9.0.

@item 
bpo-40741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40741}: Update macOS installer to use SQLite 3.32.3.

@item 
bpo-41005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41005}: fixed an XDG settings issue not allowing macos to open browser
in webbrowser.py

@item 
bpo-40741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40741}: Update macOS installer to use SQLite 3.32.2.
@end itemize

@node IDLE<26>,C API<38>,macOS<29>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id347}@anchor{18de}
@subsubsection IDLE



@itemize -

@item 
bpo-41775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41775}: Use 'IDLE Shell' as shell title

@item 
bpo-35764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35764}: Rewrite the Calltips doc section.

@item 
bpo-40181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40181}: In calltips, stop reminding that '/' marks the end of
positional-only arguments.

@item 
bpo-41468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41468}: Improve IDLE run crash error message (which users should never
see).

@item 
bpo-41373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41373}: Save files loaded with no line ending, as when blank, or
different line endings, by setting its line ending to the system default.
Fix regression in 3.8.4 and 3.9.0b4.

@item 
bpo-41300@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41300}: Save files with non-ascii chars. Fix regression released in
3.9.0b4 and 3.8.4.

@item 
bpo-37765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37765}: Add keywords to module name completion list.  Rewrite
Completions section of IDLE doc.

@item 
bpo-41152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41152}: The encoding of @code{stdin}, @code{stdout} and @code{stderr} in IDLE is
now always UTF-8.

@item 
bpo-41144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41144}: Make Open Module open a special module such as os.path.

@item 
bpo-39885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39885}: Make context menu Cut and Copy work again when right-clicking
within a selection.

@item 
bpo-40723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40723}: Make test_idle pass when run after import.
@end itemize

@node C API<38>,,IDLE<26>,Python 3 10 0 alpha 1
@anchor{whatsnew/changelog id348}@anchor{18df}
@subsubsection C API



@itemize -

@item 
bpo-41936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41936}: Removed undocumented macros @code{Py_ALLOW_RECURSION} and
@code{Py_END_ALLOW_RECURSION} and the @code{recursion_critical} field of the
@ref{8aa,,PyInterpreterState} structure.

@item 
bpo-41692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41692}: The @code{PyUnicode_InternImmortal()} function is now deprecated
and will be removed in Python 3.12: use @ref{89e,,PyUnicode_InternInPlace()}
instead. Patch by Victor Stinner.

@item 
bpo-41842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41842}: Add @ref{883,,PyCodec_Unregister()} function to unregister a codec
search function.

@item 
bpo-41834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41834}: Remove the @code{_Py_CheckRecursionLimit} variable: it has been
replaced by @code{ceval.recursion_limit} of the @ref{8aa,,PyInterpreterState}
structure. Patch by Victor Stinner.

@item 
bpo-41689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41689}: Types created with @ref{569,,PyType_FromSpec()} now make any
signature in their @code{tp_doc} slot accessible from @code{__text_signature__}.

@item 
bpo-41524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41524}: Fix bug in PyOS_mystrnicmp and PyOS_mystricmp that incremented
pointers beyond the end of a string.

@item 
bpo-41324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41324}: Add a minimal decimal capsule API.  The API supports fast
conversions between Decimals up to 38 digits and their triple
representation as a C struct.

@item 
bpo-30155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30155}: Add @ref{881,,PyDateTime_DATE_GET_TZINFO()} and
@ref{882,,PyDateTime_TIME_GET_TZINFO()} macros for accessing the @code{tzinfo}
attributes of @ref{1c7,,datetime.datetime} and @ref{1c9,,datetime.time}
objects.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Revert @ref{18e0,,PyType_HasFeature()} change: it reads again
directly the @ref{184b,,PyTypeObject.tp_flags} member when the limited C
API is not used, rather than always calling @ref{18e1,,PyType_GetFlags()}
which hides implementation details.

@item 
bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}: Remove @code{PyUnicode_AsUnicodeCopy}.

@item 
bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}: Removed @code{PyLong_FromUnicode()}.

@item 
bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}: Removed @code{PyUnicode_GetMax()}.

@item 
bpo-41123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41123}: Removed @code{Py_UNICODE_str*} functions manipulating
@code{Py_UNICODE*} strings.

@item 
bpo-41103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=41103}: @code{PyObject_AsCharBuffer()}, @code{PyObject_AsReadBuffer()},
@code{PyObject_CheckReadBuffer()}, and @code{PyObject_AsWriteBuffer()} are
removed. Please migrate to new buffer protocol;
@ref{390,,PyObject_GetBuffer()} and @ref{391,,PyBuffer_Release()}.

@item 
bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}: Raises DeprecationWarning for @code{PyUnicode_FromUnicode(NULL,
size)} and @code{PyUnicode_FromStringAndSize(NULL, size)} with @code{size > 0}.

@item 
bpo-36346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36346}: Mark @code{Py_UNICODE_COPY}, @code{Py_UNICODE_FILL},
@code{PyUnicode_WSTR_LENGTH}, @code{PyUnicode_FromUnicode},
@code{PyUnicode_AsUnicode}, and @code{PyUnicode_AsUnicodeAndSize} as deprecated
in C. Remove @code{Py_UNICODE_MATCH} which was deprecated and broken since
Python 3.3.

@item 
bpo-40989@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40989}: The @code{PyObject_INIT()} and @code{PyObject_INIT_VAR()}
macros become aliases to, respectively, @ref{a58,,PyObject_Init()} and
@ref{18e2,,PyObject_InitVar()} functions.

@item 
bpo-36020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36020}: On Windows, @code{#include "pyerrors.h"} no longer defines
@code{snprintf} and @code{vsnprintf} macros.

@item 
bpo-40943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40943}: The @code{PY_SSIZE_T_CLEAN} macro must now be defined to use
@ref{55d,,PyArg_ParseTuple()} and @ref{894,,Py_BuildValue()} formats which use
@code{#}: @code{es#}, @code{et#}, @code{s#}, @code{u#}, @code{y#}, @code{z#}, @code{U#} and
@code{Z#}. See @ref{895,,Parsing arguments and building values} and
the 
@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/}.

@item 
bpo-40910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40910}: Export explicitly the @ref{18e3,,Py_GetArgcArgv()} function to the
C API and document the function. Previously, it was exported implicitly
which no longer works since Python is built with @code{-fvisibility=hidden}.

@item 
bpo-40724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40724}: Allow defining buffer slots in type specs.

@item 
bpo-40679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40679}: Fix a @code{_PyEval_EvalCode()} crash if `qualname' argument is
NULL.

@item 
bpo-40839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40839}: Calling @ref{37d,,PyDict_GetItem()} without @ref{158,,GIL} held had
been allowed for historical reason. It is no longer allowed.

@item 
bpo-40826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40826}: @code{PyOS_InterruptOccurred()} now fails with a fatal error
if it is called with the GIL released.

@item 
bpo-40792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40792}: The result of @ref{87f,,PyNumber_Index()} now always has exact
type @ref{254,,int}. Previously, the result could have been an instance of a
subclass of @code{int}.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Convert @ref{896,,Py_REFCNT()} and @ref{76c,,Py_SIZE()} macros to
static inline functions. They cannot be used as l-value anymore: use
@ref{897,,Py_SET_REFCNT()} and @ref{76d,,Py_SET_SIZE()} to set an object
reference count and size. This change is backward incompatible on purpose,
to prepare the C API for an opaque @ref{32f,,PyObject} structure.

@item 
bpo-40703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40703}: The PyType_FromSpec*() functions no longer overwrite the type's
"__module__" attribute if it is set via "Py_tp_members" or "Py_tp_getset".

@item 
bpo-39583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39583}: Remove superfluous "extern C" declarations from
@code{Include/cpython/*.h}.
@end itemize

@node Python 3 9 0 beta 1,Python 3 9 0 alpha 6,Python 3 10 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-9-0-beta-1}@anchor{18e4}
@subsection Python 3.9.0 beta 1


`Release date: 2020-05-19'

@menu
* Security: Security<26>. 
* Core and Builtins: Core and Builtins<41>. 
* Library: Library<40>. 
* Documentation: Documentation<35>. 
* Tests: Tests<38>. 
* Build: Build<40>. 
* Windows: Windows<36>. 
* macOS: macOS<30>. 
* Tools/Demos: Tools/Demos<18>. 
* C API: C API<39>. 

@end menu

@node Security<26>,Core and Builtins<41>,,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id349}@anchor{18e5}
@subsubsection Security



@itemize -

@item 
bpo-40501@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40501}: @ref{10f,,uuid} no longer uses @ref{2a,,ctypes} to load
@code{libuuid} or @code{rpcrt4.dll} at runtime.
@end itemize

@node Core and Builtins<41>,Library<40>,Security<26>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id350}@anchor{18e6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-40663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40663}: Correctly generate annotations where parentheses are omitted
but required (e.g: @code{Type[(str, int, *other))]}.

@item 
bpo-40596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40596}: Fixed @ref{18e7,,str.isidentifier()} for non-canonicalized strings
containing non-BMP characters on Windows.

@item 
bpo-40593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40593}: Improved syntax errors for invalid characters in source code.

@item 
bpo-40585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40585}: Fixed a bug when using @ref{1756,,codeop.compile_command()} that was
causing exceptions to be swallowed with the new parser. Patch by Pablo
Galindo

@item 
bpo-40566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40566}: Apply 
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/} to @ref{4,,abc}.

@item 
bpo-40502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40502}: Initialize @code{n->n_col_offset}. (Patch by Joannah Nanjekye)

@item 
bpo-40527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40527}: Fix command line argument parsing: no longer write errors
multiple times into stderr.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{56,,errno} to multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-40523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40523}: Add pass-throughs for @ref{5d5,,hash()} and @ref{850,,reversed()} to
@ref{a40,,weakref.proxy} objects. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{db,,syslog} to multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-40246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40246}: Reporting a specialised error message for invalid string
prefixes, which was introduced in bpo-40246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40246}, is being reverted due to
backwards compatibility concerns for strings that immediately follow a
reserved keyword without whitespace between them. Constructs like
@code{bg="#d00" if clear else"#fca"} were failing to parse, which is not an
acceptable breakage on such short notice.

@item 
bpo-40417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40417}: Fix imp module deprecation warning when PyImport_ReloadModule
is called. Patch by Robert Rouhani.

@item 
bpo-40408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40408}: Fixed support of nested type variables in GenericAlias (e.g.
@code{list[list[T]]}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _stat module to multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-29587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29587}: Enable implicit exception chaining when calling
@ref{4e2,,generator.throw()}.

@item 
bpo-40328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40328}: Add tools for generating mappings headers for CJKCodecs.

@item 
bpo-40228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40228}: Setting frame.f_lineno is now robust w.r.t. changes in the
source-to-bytecode compiler

@item 
bpo-38880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38880}: Added the ability to list interpreters associated with channel
ends in the internal subinterpreters module.

@item 
bpo-37986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37986}: Improve performance of @ref{92f,,PyLong_FromDouble()} for values
that fit into long.
@end itemize

@node Library<40>,Documentation<35>,Core and Builtins<41>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id351}@anchor{18e8}
@subsubsection Library



@itemize -

@item 
bpo-40662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40662}: Fixed @ref{9c5,,ast.get_source_segment()} for ast nodes that have
incomplete location information. Patch by Irit Katriel.

@item 
bpo-40665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40665}: Convert @ref{11,,bisect} to use Argument Clinic.

@item 
bpo-40536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40536}: Added the @ref{18e9,,available_timezones()} function to the
@ref{133,,zoneinfo} module. Patch by Paul Ganssle.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: The @code{hmac.HMAC} exposes internal implementation details.
The attributes @code{digest_cons}, @code{inner}, and @code{outer} are deprecated
and will be removed in the future.

@item 
bpo-40645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40645}: The internal module @code{_hashlib} wraps and exposes OpenSSL's
HMAC API. The new code will be used in Python 3.10 after the internal
implementation details of the pure Python HMAC module are no longer part
of the public API.

@item 
bpo-40637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40637}: Builtin hash modules can now be disabled or selectively enabled
with @code{configure --with-builtin-hashlib-hashes=sha3,blake1} or
@code{--without-builtin-hashlib-hashes}.

@item 
bpo-37630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37630}: The @ref{67,,hashlib} module can now use SHA3 hashes and SHAKE XOF
from OpenSSL when available.

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: The @ref{67,,hashlib} now compiles with OpenSSL 3.0.0-alpha2.

@item 
bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}: Revert changes to @ref{9e8,,inspect.getdoc()}.

@item 
bpo-40607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40607}: When cancelling a task due to timeout, @ref{5ea,,asyncio.wait_for()}
will now propagate the exception if an error happens during cancellation.
Patch by Roman Skurikhin.

@item 
bpo-40612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40612}: Fix edge cases in SyntaxError formatting. If the offset is <=
0, no caret is printed. If the offset is > line length, the caret is
printed pointing just after the last character.

@item 
bpo-40597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40597}: If text content lines are longer than policy.max_line_length,
always use a content-encoding to make sure they are wrapped.

@item 
bpo-40571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40571}: Added functools.cache() as a simpler, more discoverable way to
access the unbounded cache variant of lru_cache(maxsize=None).

@item 
bpo-40503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40503}: 
@geindex Python Enhancement Proposals; PEP 615
PEP 615@footnote{https://peps.python.org/pep-0615/}, the @ref{133,,zoneinfo} module. Adds support for the
IANA time zone database.

@item 
bpo-40397@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40397}: Removed attributes @code{__args__} and @code{__parameters__} from
special generic aliases like @code{typing.List} (not subscripted).

@item 
bpo-40549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40549}: Convert posixmodule.c ("posix" or "nt" module) to the
multiphase initialization (PEP 489).

@item 
bpo-31033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31033}: Add a @code{msg} argument to @code{Future.cancel()} and
@code{Task.cancel()}.

@item 
bpo-40541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40541}: Added an optional `counts' parameter to random.sample().

@item 
bpo-40515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40515}: The @ref{cf,,ssl} and @ref{67,,hashlib} modules now actively check
that OpenSSL is build with thread support. Python 3.7.0 made thread
support mandatory and no longer works safely with a no-thread builds.

@item 
bpo-31033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31033}: When a @ref{4c2,,asyncio.Task} is cancelled, the exception
traceback now chains all the way back to where the task was first
interrupted.

@item 
bpo-40504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40504}: @ref{9dd,,functools.lru_cache()} objects can now be the targets of
weakrefs.

@item 
bpo-40559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40559}: Fix possible memory leak in the C implementation of
@ref{4c2,,asyncio.Task}.

@item 
bpo-40480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40480}: @code{fnmatch.fnmatch()} could take exponential time in the
presence of multiple @code{*} pattern characters.  This was repaired by
generating more elaborate regular expressions to avoid futile
backtracking.

@item 
bpo-40495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40495}: @ref{20,,compileall} is now able to use hardlinks to prevent
duplicates in a case when @code{.pyc} files for different optimization levels
have the same content.

@item 
bpo-40457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40457}: The ssl module now support OpenSSL builds without TLS 1.0 and
1.1 methods.

@item 
bpo-40355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40355}: Improve error reporting in @ref{c06,,ast.literal_eval()} in the
presence of malformed @ref{18ea,,ast.Dict} nodes instead of silently ignoring
any non-conforming elements. Patch by Curtis Bucher.

@item 
bpo-40465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40465}: Deprecated the optional `random' argument to
`random.shuffle()'.

@item 
bpo-40459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40459}: @ref{18eb,,platform.win32_ver()} now produces correct `ptype' strings
instead of empty strings.

@item 
bpo-39435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39435}: The first argument of @ref{cff,,pickle.loads()} is now
positional-only.

@item 
bpo-39305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39305}: Update @code{nntplib} to merge @code{nntplib.NNTP} and
@code{nntplib._NNTPBase}. Patch by Donghee Na.

@item 
bpo-32494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32494}: Update @ref{33,,dbm.gnu} to use gdbm_count if possible when
calling @ref{619,,len()}. Patch by Donghee Na.

@item 
bpo-40453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40453}: Add @code{isolated=True} keyword-only parameter to
@code{_xxsubinterpreters.create()}. An isolated subinterpreter cannot spawn
threads, spawn a child process or call @code{os.fork()}.

@item 
bpo-40286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40286}: Remove @code{_random.Random.randbytes()}: the C implementation of
@code{randbytes()}. Implement the method in Python to ease subclassing:
@code{randbytes()} now directly reuses @code{getrandbits()}.

@item 
bpo-40394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40394}: Added default arguments to
@ref{18ec,,difflib.SequenceMatcher.find_longest_match()}.

@item 
bpo-39995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39995}: Fix a race condition in concurrent.futures._ThreadWakeup:
access to _ThreadWakeup is now protected with the shutdown lock.

@item 
bpo-30966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30966}: @code{Process.shutdown(wait=True)} of @ref{21,,concurrent.futures}
now closes explicitly the result queue.

@item 
bpo-30966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30966}: Add a new @ref{902,,close()} method to
the @ref{901,,SimpleQueue} class to explicitly close the
queue.

@item 
bpo-39966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39966}: Revert bpo-25597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25597}. @ref{e7a,,unittest.mock.MagicMock} with wraps'
set uses default return values for magic methods.

@item 
bpo-39791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39791}: Added @code{files()} function to importlib.resources with support
for subdirectories in package data, matching backport in
importlib_resources 1.5.

@item 
bpo-40375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40375}: @ref{8f4,,imaplib.IMAP4.unselect()} is added. Patch by Donghee Na.

@item 
bpo-40389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40389}: @code{repr()} now returns @code{typing.Optional[T]} when called for
@code{typing.Union} of two types, one of which is @code{NoneType}.

@item 
bpo-40291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40291}: Add support for CAN_J1939 sockets (available on Linux 5.4+)

@item 
bpo-40273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40273}: @ref{457,,types.MappingProxyType} is now reversible.

@item 
bpo-39075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39075}: The repr for @ref{1cc,,types.SimpleNamespace} is now insertion
ordered rather than alphabetical.

@item 
bpo-40192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40192}: On AIX, @ref{923,,thread_time()} is now implemented with
@code{thread_cputime()} which has nanosecond resolution, rather than
@code{clock_gettime(CLOCK_THREAD_CPUTIME_ID)} which has a resolution of 10
milliseconds. Patch by Batuhan Taskaya.

@item 
bpo-40025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40025}: Raise TypeError when _generate_next_value_ is defined after
members. Patch by Ethan Onstott.

@item 
bpo-39058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39058}: In the argparse module, the repr for Namespace() and other
argument holders now displayed in the order attributes were added.
Formerly, it displayed in alphabetical order even though argument order is
preserved the user visible parts of the module.

@item 
bpo-24416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24416}: The @code{isocalendar()} methods of @ref{1c8,,datetime.date} and
@ref{1c7,,datetime.datetime} now return a @ref{639,,named tuple} instead of a
@ref{366,,tuple}.
@end itemize

@node Documentation<35>,Tests<38>,Library<40>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id352}@anchor{18ed}
@subsubsection Documentation



@itemize -

@item 
bpo-34790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34790}: Add version of removal for explicit passing of coros to
@code{asyncio.wait()}'s documentation

@item 
bpo-40561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40561}: Provide docstrings for webbrowser open functions.

@item 
bpo-40499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40499}: Mention that @ref{469,,asyncio.wait()} requires a non-empty set of
awaitables.

@item 
bpo-39705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39705}: Tutorial example for sorted() in the Loop Techniques section is
given a better explanation. Also a new example is included to explain
sorted()'s basic behavior.

@item 
bpo-39435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39435}: Fix an incorrect signature for @ref{cff,,pickle.loads()} in the docs
@end itemize

@node Tests<38>,Build<40>,Documentation<35>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id353}@anchor{18ee}
@subsubsection Tests



@itemize -

@item 
bpo-40055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40055}: distutils.tests now saves/restores warnings filters to leave
them unchanged. Importing tests imports docutils which imports
pkg_resources which adds a warnings filter.

@item 
bpo-40436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40436}: test_gdb and test.pythoninfo now check gdb command exit code.
@end itemize

@node Build<40>,Windows<36>,Tests<38>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id354}@anchor{18ef}
@subsubsection Build



@itemize -

@item 
bpo-40653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40653}: Move _dirnameW out of HAVE_SYMLINK to fix a potential compiling
issue.

@item 
bpo-40514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40514}: Add @code{--with-experimental-isolated-subinterpreters} build
option to @code{configure}: better isolate subinterpreters, experimental
build mode.
@end itemize

@node Windows<36>,macOS<30>,Build<40>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id355}@anchor{18f0}
@subsubsection Windows



@itemize -

@item 
bpo-40650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40650}: Include winsock2.h in pytime.c for timeval.

@item 
bpo-40458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40458}: Increase reserved stack space to prevent overflow crash on
Windows.

@item 
bpo-39148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39148}: Add IPv6 support to @ref{a,,asyncio} datagram endpoints in
ProactorEventLoop. Change the raised exception for unknown address
families to ValueError as it's not coming from Windows API.
@end itemize

@node macOS<30>,Tools/Demos<18>,Windows<36>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id356}@anchor{18f1}
@subsubsection macOS



@itemize -

@item 
bpo-34956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34956}: When building Python on macOS from source, @code{_tkinter} now
links with non-system Tcl and Tk frameworks if they are installed in
@code{/Library/Frameworks}, as had been the case on older releases of macOS.
If a macOS SDK is explicitly configured, by using
@code{--enable-universalsdk=} or @code{-isysroot}, only the SDK itself is
searched. The default behavior can still be overridden with
@code{--with-tcltk-includes} and @code{--with-tcltk-libs}.

@item 
bpo-35569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35569}: Expose RFC 3542 IPv6 socket options.
@end itemize

@node Tools/Demos<18>,C API<39>,macOS<30>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id357}@anchor{18f2}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-40479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40479}: Update multissltest helper to test with latest OpenSSL 1.0.2,
1.1.0, 1.1.1, and 3.0.0-alpha.

@item 
bpo-40431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40431}: Fix a syntax typo in @code{turtledemo} that now raises a
@code{SyntaxError}.

@item 
bpo-40163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40163}: Fix multissltest tool. OpenSSL has changed download URL for old
releases. The multissltest tool now tries to download from current and old
download URLs.
@end itemize

@node C API<39>,,Tools/Demos<18>,Python 3 9 0 beta 1
@anchor{whatsnew/changelog id358}@anchor{18f3}
@subsubsection C API



@itemize -

@item 
bpo-39465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39465}: Remove the @code{_PyUnicode_ClearStaticStrings()} function from
the C API.

@item 
bpo-38787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38787}: Add PyCFunction_CheckExact() macro for exact type checks now
that we allow subtypes of PyCFunction, as well as PyCMethod_CheckExact()
and PyCMethod_Check() for the new PyCMethod subtype.

@item 
bpo-40545@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40545}: Declare @code{_PyErr_GetTopmostException()} with @code{PyAPI_FUNC()}
to properly export the function in the C API. The function remains private
(@code{_Py}) prefix.

@item 
bpo-40412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40412}: Nullify inittab_copy during finalization, preventing future
interpreter initializations in an embedded situation from crashing. Patch
by Gregory Szorc.

@item 
bpo-40429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40429}: The @ref{778,,PyThreadState_GetFrame()} function now returns a
strong reference to the frame.

@item 
bpo-40428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40428}: Remove the following functions from the C API. Call
@ref{97b,,PyGC_Collect()} explicitly to free all free lists.


@itemize *

@item 
@code{PyAsyncGen_ClearFreeLists()}

@item 
@code{PyContext_ClearFreeList()}

@item 
@code{PyDict_ClearFreeList()}

@item 
@code{PyFloat_ClearFreeList()}

@item 
@code{PyFrame_ClearFreeList()}

@item 
@code{PyList_ClearFreeList()}

@item 
@code{PySet_ClearFreeList()}

@item 
@code{PyTuple_ClearFreeList()}
@end itemize

@item 
bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}: New @ref{770,,PyFrame_GetBack()} function: get the frame next
outer frame.

@item 
bpo-40421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40421}: New @ref{774,,PyFrame_GetCode()} function: return a borrowed
reference to the frame code.

@item 
bpo-40217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40217}: Ensure that instances of types created with
@ref{56a,,PyType_FromSpecWithBases()} will visit its class object when
traversing references in the garbage collector (implemented as an
extension of the provided @ref{768,,tp_traverse}). Patch by
Pablo Galindo.

@item 
bpo-38787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38787}: Module C state is now accessible from C-defined heap type
methods (
@geindex Python Enhancement Proposals; PEP 573
PEP 573@footnote{https://peps.python.org/pep-0573/}). Patch by Marcel Plch and Petr Viktorin.
@end itemize

@node Python 3 9 0 alpha 6,Python 3 9 0 alpha 5,Python 3 9 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-9-0-alpha-6}@anchor{18f4}
@subsection Python 3.9.0 alpha 6


`Release date: 2020-04-27'

@menu
* Security: Security<27>. 
* Core and Builtins: Core and Builtins<42>. 
* Library: Library<41>. 
* Documentation: Documentation<36>. 
* Tests: Tests<39>. 
* Build: Build<41>. 
* Windows: Windows<37>. 
* macOS: macOS<31>. 
* IDLE: IDLE<27>. 
* Tools/Demos: Tools/Demos<19>. 
* C API: C API<40>. 

@end menu

@node Security<27>,Core and Builtins<42>,,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id359}@anchor{18f5}
@subsubsection Security



@itemize -

@item 
bpo-40121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40121}: Fixes audit events raised on creating a new socket.

@item 
bpo-39073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39073}: Disallow CR or LF in email.headerregistry.Address arguments to
guard against header injection attacks.

@item 
bpo-39503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39503}: 
@geindex Common Vulnerabilities and Exposures; CVE 2020-8492
CVE 2020-8492@footnote{https://www.cve.org/CVERecord?id=CVE-2020-8492}: The
@ref{1849,,AbstractBasicAuthHandler} class of the
@ref{10a,,urllib.request} module uses an inefficient regular expression which
can be exploited by an attacker to cause a denial of service. Fix the
regex to prevent the catastrophic backtracking. Vulnerability reported by
Ben Caller and Matt Schwager.
@end itemize

@node Core and Builtins<42>,Library<41>,Security<27>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id360}@anchor{18f6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-40313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40313}: Improve the performance of bytes.hex().

@item 
bpo-40334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40334}: Switch to a new parser, based on PEG.  For more details see PEP
617. To temporarily switch back to the old parser, use @code{-X oldparser} or
@code{PYTHONOLDPARSER=1}.  In Python 3.10 we will remove the old parser
completely, including the @code{parser} module (already deprecated) and
anything that depends on it.

@item 
bpo-40267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40267}: Fix the tokenizer to display the correct error message, when
there is a @code{SyntaxError} on the last input character and no newline
follows. It used to be @code{unexpected EOF while parsing}, while it should
be @code{invalid syntax}.

@item 
bpo-39522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39522}: Correctly unparse explicit @code{u} prefix for strings when
postponed evaluation for annotations activated. Patch by Batuhan Taskaya.

@item 
bpo-40246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40246}: Report a specialized error message, @code{invalid string prefix},
when the tokenizer encounters a string with an invalid prefix.

@item 
bpo-40082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40082}: Fix the signal handler: it now always uses the main
interpreter, rather than trying to get the current Python thread state.

@item 
bpo-37388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37388}: str.encode() and str.decode() no longer check the encoding and
errors in development mode or in debug mode during Python finalization.
The codecs machinery can no longer work on very late calls to str.encode()
and str.decode().

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Fix possible refleaks in @code{_json}, memo of PyScannerObject
should be traversed.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Speed up calls to @code{dict()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention.

@item 
bpo-40141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40141}: Add column and line information to @code{ast.keyword} nodes. Patch
by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{bb,,resource} to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port @ref{8d,,math} to multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _uuid module to multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-40077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40077}: Convert json module to use @ref{569,,PyType_FromSpec()}.

@item 
bpo-40067@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40067}: Improve the error message for multiple star expressions in an
assignment. Patch by Furkan Onder

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _functools module to multiphase initialization (PEP
489). Patch by Paulo Henrique Silva.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port operator module to multiphase initialization (PEP 489).
Patch by Paulo Henrique Silva.

@item 
bpo-20526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20526}: Fix @ref{15aa,,PyThreadState_Clear()}. @code{PyThreadState.frame} is
a borrowed reference, not a strong reference: @code{PyThreadState_Clear()}
must not call @code{Py_CLEAR(tstate->frame)}.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port time module to multiphase initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).
Patch by Paulo Henrique Silva.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _weakref extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-40020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40020}: Fix a leak and subsequent crash in parsetok.c caused by realloc
misuse on a rare codepath.

@item 
bpo-39939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39939}: Added str.removeprefix and str.removesuffix methods and
corresponding bytes, bytearray, and collections.UserString methods to
remove affixes from a string if present. See 
@geindex Python Enhancement Proposals; PEP 616
PEP 616@footnote{https://peps.python.org/pep-0616/} for a full
description. Patch by Dennis Sweeney.

@item 
bpo-39481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39481}: Implement PEP 585. This supports list[int], tuple[str, ...]
etc.

@item 
bpo-32894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32894}: Support unparsing of infinity numbers in postponed annotations.
Patch by Batuhan Taşkaya.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Speed up calls to @code{list()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Mark Shannon.
@end itemize

@node Library<41>,Documentation<36>,Core and Builtins<42>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id361}@anchor{18f7}
@subsubsection Library



@itemize -

@item 
bpo-40398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40398}: @ref{86a,,typing.get_args()} now always returns an empty tuple for
special generic aliases.

@item 
bpo-40396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40396}: Functions @ref{a35,,typing.get_origin()}, @ref{86a,,typing.get_args()}
and @ref{69c,,typing.get_type_hints()} support now generic aliases like
@code{list[int]}.

@item 
bpo-38061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38061}: Optimize the @ref{d5,,subprocess} module on FreeBSD using
@code{closefrom()}. A single @code{close(fd)} syscall is cheap, but when
@code{sysconf(_SC_OPEN_MAX)} is high, the loop calling @code{close(fd)} on each
file descriptor can take several milliseconds.

The workaround on FreeBSD to improve performance was to load and mount the
fdescfs kernel module, but this is not enabled by default.

Initial patch by Ed Maste (emaste), Conrad Meyer (cem), Kyle Evans
(kevans) and Kubilay Kocak (koobs):
@indicateurl{https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242274}

@item 
bpo-38061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38061}: On FreeBSD, @code{os.closerange(fd_low, fd_high)} now calls
@code{closefrom(fd_low)} if `fd_high' is greater than or equal to
@code{sysconf(_SC_OPEN_MAX)}.

Initial patch by Ed Maste (emaste), Conrad Meyer (cem), Kyle Evans
(kevans) and Kubilay Kocak (koobs):
@indicateurl{https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=242274}

@item 
bpo-40360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40360}: The @code{lib2to3} module is pending deprecation due to
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/}.

@item 
bpo-40138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40138}: Fix the Windows implementation of @ref{d87,,os.waitpid()} for exit
code larger than @code{INT_MAX >> 8}. The exit status is now interpreted as
an unsigned number.

@item 
bpo-39942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39942}: Set "__main__" as the default module name when "__name__" is
missing in @ref{15c,,typing.TypeVar}. Patch by Weipeng Hong.

@item 
bpo-40275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40275}: The @ref{86,,logging} package is now imported lazily in
@ref{105,,unittest} only when the @ref{843,,assertLogs()}
assertion is used.

@item 
bpo-40275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40275}: The @ref{a,,asyncio} package is now imported lazily in
@ref{105,,unittest} only when the @ref{301,,IsolatedAsyncioTestCase}
class is used.

@item 
bpo-40330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40330}: In @code{ShareableList.__setitem__()}, check the size of a new
string item after encoding it to utf-8, not before.

@item 
bpo-40148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40148}: Added @code{pathlib.Path.with_stem()} to create a new Path with
the stem replaced.

@item 
bpo-40325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40325}: Deprecated support for set objects in random.sample().

@item 
bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}: Improved help for the @ref{103,,typing} module. Docstrings are now
shown for all special forms and special generic aliases (like @code{Union}
and @code{List}). Using @code{help()} with generic alias like @code{List[int]} will
show the help for the correspondent concrete type (@code{list} in this case).

@item 
bpo-40257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40257}: @ref{9e8,,inspect.getdoc()} no longer returns docstring inherited
from the type of the object or from parent class if it is a class if it is
not defined in the object itself. In @ref{b4,,pydoc} the documentation string
is now shown not only for class, function, method etc, but for any object
that has its own @code{__doc__} attribute.

@item 
bpo-40287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40287}: Fixed @code{SpooledTemporaryFile.seek()} to return the position.

@item 
bpo-40290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40290}: Added zscore() to statistics.NormalDist().

@item 
bpo-40282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40282}: Allow @code{random.getrandbits(0)} to succeed and to return 0.

@item 
bpo-40286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40286}: Add @ref{18f8,,random.randbytes()} function and
@code{random.Random.randbytes()} method to generate random bytes.

@item 
bpo-40277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40277}: @ref{1c5,,collections.namedtuple()} now provides a human-readable
repr for its field accessors.

@item 
bpo-40270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40270}: The included copy of sqlite3 on Windows is now compiled with
the json extension. This allows the use of functions such as
@code{json_object}.

@item 
bpo-29255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29255}: Wait in @code{KqueueSelector.select} when no fds are registered

@item 
bpo-40260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40260}: Ensure @ref{90,,modulefinder} uses @ref{16b2,,io.open_code()} and
respects coding comments.

@item 
bpo-40234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40234}: Allow again to spawn daemon threads in subinterpreters (revert
change which denied them).

@item 
bpo-39207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39207}: Workers in @ref{8db,,ProcessPoolExecutor} are
now spawned on demand, only when there are no available idle workers to
reuse. This optimizes startup overhead and reduces the amount of lost CPU
time to idle workers. Patch by Kyle Stanley.

@item 
bpo-40091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40091}: Fix a hang at fork in the logging module: the new private
_at_fork_reinit() method is now used to reinitialize locks at fork in the
child process.

@item 
bpo-40149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40149}: Implement traverse and clear slots in _abc._abc_data type.

@item 
bpo-40208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40208}: Remove deprecated @code{symtable.SymbolTable.has_exec()}.

@item 
bpo-40196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40196}: Fix a bug in the @ref{d7,,symtable} module that was causing
incorrectly report global variables as local. Patch by Pablo Galindo.

@item 
bpo-40190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40190}: Add support for @code{_SC_AIX_REALMEM} to @code{posix.sysconf()}.

@item 
bpo-40182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40182}: Removed the @code{_field_types} attribute of the
@ref{2ad,,typing.NamedTuple} class.

@item 
bpo-36517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36517}: Multiple inheritance with @ref{2ad,,typing.NamedTuple} now raises
an error instead of silently ignoring other types.

@item 
bpo-40126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40126}: Fixed reverting multiple patches in unittest.mock. Patcher's
@code{__exit__()} is now never called if its @code{__enter__()} is failed.
Returning true from @code{__exit__()} silences now the exception.

@item 
bpo-40094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40094}: CGIHTTPRequestHandler of http.server now logs the CGI script
exit code, rather than the CGI script exit status of os.waitpid(). For
example, if the script is killed by signal 11, it now logs: "CGI script
exit code -11."

@item 
bpo-40108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40108}: Improve the error message when triying to import a module using
@ref{bd,,runpy} and incorrectly using the ".py" extension at the end of the
module name. Patch by Pablo Galindo.

@item 
bpo-40094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40094}: Add @ref{90a,,os.waitstatus_to_exitcode()} function: convert a wait
status to an exit code.

@item 
bpo-40089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40089}: Fix threading._after_fork(): if fork was not called by a thread
spawned by threading.Thread, threading._after_fork() now creates a
_MainThread instance for _main_thread, instead of a _DummyThread instance.

@item 
bpo-40089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40089}: Add a private @code{_at_fork_reinit()} method to
@code{_thread.Lock}, @code{_thread.RLock}, @ref{2dc,,threading.RLock}
and @ref{1135,,threading.Condition} classes: reinitialize the lock at fork in
the child process, reset the lock to the unlocked state. Rename also the
private @code{_reset_internal_locks()} method of @ref{1138,,threading.Event} to
@code{_at_fork_reinit()}.

@item 
bpo-25780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25780}: Expose @ref{91e,,CAN_RAW_JOIN_FILTERS} in the
@ref{cb,,socket} module.

@item 
bpo-39503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39503}: @ref{1849,,AbstractBasicAuthHandler} of
@ref{10a,,urllib.request} now parses all WWW-Authenticate HTTP headers and
accepts multiple challenges per header: use the realm of the first Basic
challenge.

@item 
bpo-39812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39812}: Removed daemon threads from @ref{21,,concurrent.futures} by adding
an internal @code{threading._register_atexit()}, which calls registered
functions prior to joining all non-daemon threads. This allows for
compatibility with subinterpreters, which don't support daemon threads.

@item 
bpo-40050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40050}: Fix @code{importlib._bootstrap_external}: avoid creating a new
@code{winreg} builtin module if it's already available in
@ref{18f9,,sys.modules}, and remove redundant imports.

@item 
bpo-40014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40014}: Fix @code{os.getgrouplist()}: if @code{getgrouplist()} function fails
because the group list is too small, retry with a larger group list. On
failure, the glibc implementation of @code{getgrouplist()} sets @code{ngroups}
to the total number of groups. For other implementations, double the group
list size.

@item 
bpo-40017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40017}: Add @ref{18fa,,time.CLOCK_TAI} constant if the operating system
support it.

@item 
bpo-40016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40016}: In re docstring, clarify the relationship between inline and
argument compile flags.

@item 
bpo-39953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39953}: Update internal table of OpenSSL error codes in the @code{ssl}
module.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: Added 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} operators to
@ref{18fb,,weakref.WeakValueDictionary}.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: Added 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} operators to
@ref{18fc,,weakref.WeakKeyDictionary}.

@item 
bpo-38891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38891}: Fix linear runtime behaviour of the @code{__getitem__} and
@code{__setitem__} methods in
@ref{18fd,,multiprocessing.shared_memory.ShareableList}. This avoids
quadratic performance when iterating a @code{ShareableList}. Patch by Thomas
Krennwallner.

@item 
bpo-39682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39682}: Remove undocumented support for `closing' a @code{pathlib.Path}
object via its context manager. The context manager magic methods remain,
but they are now a no-op, making @code{Path} objects immutable.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: Added 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/} operators (@code{|} and @code{|=}) to
@ref{c0a,,collections.ChainMap}.

@item 
bpo-39011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39011}: Normalization of line endings in ElementTree attributes was
removed, as line endings which were replaced by entity numbers should be
preserved in original form.

@item 
bpo-38410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38410}: Properly handle @ref{153f,,sys.audit()} failures in
@ref{15af,,sys.set_asyncgen_hooks()}.

@item 
bpo-36541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36541}: lib2to3 now recognizes named assignment expressions (the walrus
operator, @code{:=})

@item 
bpo-35967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35967}: In platform, delay the invocation of 'uname -p' until the
processor attribute is requested.

@item 
bpo-35113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35113}: @ref{154d,,inspect.getsource()} now returns correct source code for
inner class with same name as module level class. Decorators are also
returned as part of source of the class. Patch by Karthikeyan
Singaravelan.

@item 
bpo-33262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33262}: Deprecate passing None as an argument for @ref{526,,shlex.split()}'s
@code{s} parameter.  Patch by Zackery Spytz.

@item 
bpo-31758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31758}: Prevent crashes when using an uninitialized
@code{_elementtree.XMLParser} object. Patch by Oren Milman.
@end itemize

@node Documentation<36>,Tests<39>,Library<41>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id362}@anchor{18fe}
@subsubsection Documentation



@itemize -

@item 
bpo-27635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27635}: The pickle documentation incorrectly claimed that @code{__new__}
isn't called by default when unpickling.

@item 
bpo-39879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39879}: Updated @ref{18ff,,Modèle de données} docs to include @ref{253,,dict()} insertion
order preservation. Patch by Furkan Onder and Samy Lahfa.

@item 
bpo-38387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38387}: Document @ref{1900,,PyDoc_STRVAR} macro in the C-API reference.

@item 
bpo-13743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13743}: Some methods within xml.dom.minidom.Element class are now
better documented.
@end itemize

@node Tests<39>,Build<41>,Documentation<36>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id363}@anchor{1901}
@subsubsection Tests



@itemize -

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Set expected default encoding in test_c_locale_coercion.py for
VxWorks RTOS.

@item 
bpo-40162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40162}: Update Travis CI configuration to OpenSSL 1.1.1f.

@item 
bpo-40146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40146}: Update OpenSSL to 1.1.1f in Azure Pipelines.

@item 
bpo-40094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40094}: Add @ref{1902,,test.support.wait_process()} function.

@item 
bpo-40003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40003}: @code{test.bisect_cmd} now copies Python command line options like
@code{-O} or @code{-W}. Moreover, emit a warning if @code{test.bisect_cmd} is used
with @code{-w}/@code{--verbose2} option.

@item 
bpo-39380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39380}: Add the encoding in @ref{8e7,,ftplib.FTP} and
@ref{8e8,,ftplib.FTP_TLS} to the constructor as keyword-only and change the
default from @code{latin-1} to @code{utf-8} to follow 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}.

@item 
bpo-39793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39793}: Use the same domain when testing @code{make_msgid}. Patch by
Batuhan Taskaya.

@item 
bpo-1812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1812}: Fix newline handling in doctest.testfile when loading from a
package whose loader has a get_data method. Patch by Peter Donis.
@end itemize

@node Build<41>,Windows<37>,Tests<39>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id364}@anchor{1903}
@subsubsection Build



@itemize -

@item 
bpo-38360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38360}: Support single-argument form of macOS -isysroot flag.

@item 
bpo-40158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40158}: Fix CPython MSBuild Properties in NuGet Package
(build/native/python.props)

@item 
bpo-38527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38527}: Fix configure check on Solaris for "float word ordering":
sometimes, the correct "grep" command was not being used. Patch by Arnon
Yaari.
@end itemize

@node Windows<37>,macOS<31>,Build<41>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id365}@anchor{1904}
@subsubsection Windows



@itemize -

@item 
bpo-40164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40164}: Updates Windows to OpenSSL 1.1.1f

@item 
bpo-8901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8901}: Ignore the Windows registry when the @code{-E} option is used.
@end itemize

@node macOS<31>,IDLE<27>,Windows<37>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id366}@anchor{1905}
@subsubsection macOS



@itemize -

@item 
bpo-38329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38329}: python.org macOS installers now update the Current version
symlink of /Library/Frameworks/Python.framework/Versions for 3.9 installs.
Previously, Current was only updated for Python 2.x installs. This should
make it easier to embed Python 3 into other macOS applications.

@item 
bpo-40164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40164}: Update macOS installer builds to use OpenSSL 1.1.1g.
@end itemize

@node IDLE<27>,Tools/Demos<19>,macOS<31>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id367}@anchor{1906}
@subsubsection IDLE



@itemize -

@item 
bpo-38439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38439}: Add a 256×256 pixel IDLE icon to support more modern
environments. Created by Andrew Clover. Delete the unused macOS idle.icns
icon file.

@item 
bpo-38689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38689}: IDLE will no longer freeze when inspect.signature fails when
fetching a calltip.
@end itemize

@node Tools/Demos<19>,C API<40>,IDLE<27>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id368}@anchor{1907}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-40385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40385}: Removed the checkpyc.py tool. Please see compileall without
force mode as a potential alternative.

@item 
bpo-40179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40179}: Fixed translation of @code{#elif} in Argument Clinic.

@item 
bpo-40094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40094}: Fix @code{which.py} script exit code: it now uses
@ref{90a,,os.waitstatus_to_exitcode()} to convert @ref{1411,,os.system()} exit status
into an exit code.
@end itemize

@node C API<40>,,Tools/Demos<19>,Python 3 9 0 alpha 6
@anchor{whatsnew/changelog id369}@anchor{1908}
@subsubsection C API



@itemize -

@item 
bpo-40241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40241}: Move the @code{PyGC_Head} structure to the internal C API.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{971,,PyObject_IS_GC()} macro to a function to hide
implementation details.

@item 
bpo-40241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40241}: Add the functions @ref{963,,PyObject_GC_IsTracked()} and
@ref{964,,PyObject_GC_IsFinalized()} to the public API to allow to query if
Python objects are being currently tracked or have been already finalized
by the garbage collector respectively. Patch by Pablo Galindo.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: The @code{PyObject_NEW()} macro becomes an alias to the
@ref{972,,PyObject_New()} macro, and the @code{PyObject_NEW_VAR()} macro
becomes an alias to the @ref{973,,PyObject_NewVar()} macro, to hide
implementation details. They no longer access directly the
@ref{974,,PyTypeObject.tp_basicsize} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: @ref{18e0,,PyType_HasFeature()} now always calls
@ref{18e1,,PyType_GetFlags()} to hide implementation details. Previously, it
accessed directly the @ref{184b,,PyTypeObject.tp_flags} member when the
limited C API was not used.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert the @code{PyObject_GET_WEAKREFS_LISTPTR()} macro to a
function to hide implementation details: the macro accessed directly to
the @ref{975,,PyTypeObject.tp_weaklistoffset} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Convert @ref{38f,,PyObject_CheckBuffer()} macro to a function to
hide implementation details: the macro accessed directly the
@ref{976,,PyTypeObject.tp_as_buffer} member.

@item 
bpo-40170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40170}: Always declare @ref{977,,PyIndex_Check()} as an opaque function to
hide implementation details: remove @code{PyIndex_Check()} macro. The macro
accessed directly the @ref{978,,PyTypeObject.tp_as_number} member.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Add @ref{95f,,PyThreadState_GetID()} function: get the unique
identifier of a Python thread state.
@end itemize

@node Python 3 9 0 alpha 5,Python 3 9 0 alpha 4,Python 3 9 0 alpha 6,Changelog
@anchor{whatsnew/changelog python-3-9-0-alpha-5}@anchor{1909}
@subsection Python 3.9.0 alpha 5


`Release date: 2020-03-23'

@menu
* Security: Security<28>. 
* Core and Builtins: Core and Builtins<43>. 
* Library: Library<42>. 
* Documentation: Documentation<37>. 
* Tests: Tests<40>. 
* Build: Build<42>. 
* Windows: Windows<38>. 
* macOS: macOS<32>. 
* IDLE: IDLE<28>. 
* Tools/Demos: Tools/Demos<20>. 
* C API: C API<41>. 

@end menu

@node Security<28>,Core and Builtins<43>,,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id370}@anchor{190a}
@subsubsection Security



@itemize -

@item 
bpo-38576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38576}: Disallow control characters in hostnames in http.client,
addressing 
@geindex Common Vulnerabilities and Exposures; CVE 2019-18348
CVE 2019-18348@footnote{https://www.cve.org/CVERecord?id=CVE-2019-18348}. Such potentially malicious header injection
URLs now cause a InvalidURL to be raised.
@end itemize

@node Core and Builtins<43>,Library<42>,Security<28>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id371}@anchor{190b}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-40010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40010}: Optimize pending calls in multithreaded applications. If a
thread different than the main thread schedules a pending call
(@ref{96e,,Py_AddPendingCall()}), the bytecode evaluation loop is no longer
interrupted at each bytecode instruction to check for pending calls which
cannot be executed. Only the main thread can execute pending calls.

Previously, the bytecode evaluation loop was interrupted at each
instruction until the main thread executes pending calls.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _weakref extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _collections module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-40010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40010}: Optimize signal handling in multithreaded applications. If a
thread different than the main thread gets a signal, the bytecode
evaluation loop is no longer interrupted at each bytecode instruction to
check for pending signals which cannot be handled. Only the main thread of
the main interpreter can handle signals.

Previously, the bytecode evaluation loop was interrupted at each
instruction until the main thread handles signals.

@item 
bpo-39984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39984}: If @ref{96e,,Py_AddPendingCall()} is called in a subinterpreter,
the function is now scheduled to be called from the subinterpreter, rather
than being called from the main interpreter. Each subinterpreter now has
its own list of scheduled calls.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _heapq module to multiphase initialization.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port itertools module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Speed up calls to @code{frozenset()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-39984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39984}: subinterpreters: Move
@code{_PyRuntimeState.ceval.tracing_possible} to
@code{PyInterpreterState.ceval.tracing_possible}: each interpreter now has
its own variable.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Speed up calls to @code{set()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _statistics module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39968}: Use inline function to replace extension modules'
get_module_state macros.

@item 
bpo-39965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39965}: Correctly raise @code{SyntaxError} if `await' is used inside
non-async functions and @code{PyCF_ALLOW_TOP_LEVEL_AWAIT} is set (like in the
asyncio REPL). Patch by Pablo Galindo.

@item 
bpo-39562@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39562}: Allow executing asynchronous comprehensions on the top level
when the @code{PyCF_ALLOW_TOP_LEVEL_AWAIT} flag is given. Patch by Batuhan
Taskaya.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Speed up calls to @code{tuple()} by using the 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}
@code{vectorcall} calling convention. Patch by Donghee Na.

@item 
bpo-38373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38373}: Changed list overallocation strategy. It no longer
overallocates if the new size is closer to overallocated size than to the
old size and adds padding.

@item 
bpo-39926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39926}: Update Unicode database to Unicode version 13.0.0.

@item 
bpo-19466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19466}: Clear the frames of daemon threads earlier during the Python
shutdown to call objects destructors. So "unclosed file" resource warnings
are now emitted for daemon threads in a more reliable way.

@item 
bpo-38894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38894}: Fix a bug that was causing incomplete results when calling
@code{pathlib.Path.glob} in the presence of symlinks that point to files
where the user does not have read access. Patch by Pablo Galindo and Matt
Wozniski.

@item 
bpo-39877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39877}: Fix @ref{3a0,,PyEval_RestoreThread()} random crash at exit with
daemon threads. It now accesses the @code{_PyRuntime} variable directly
instead of using @code{tstate->interp->runtime}, since @code{tstate} can be a
dangling pointer after @ref{1330,,Py_Finalize()} has been called. Moreover,
the daemon thread now exits before trying to take the GIL.

@item 
bpo-39871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39871}: Fix a possible @ref{561,,SystemError} in
@code{math.@{atan2,copysign,remainder@}()} when the first argument cannot be
converted to a @ref{2eb,,float}. Patch by Zackery Spytz.

@item 
bpo-39776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39776}: Fix race condition where threads created by PyGILState_Ensure()
could get a duplicate id.

This affects consumers of tstate->id like the contextvar caching
machinery, which could return invalid cached objects under heavy thread
load (observed in embedded scenarios).

@item 
bpo-39778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39778}: Fixed a crash due to incorrect handling of weak references in
@code{collections.OrderedDict} classes. Patch by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port audioop extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39702}: Relax @ref{71b,,decorator} grammar restrictions to allow any valid
expression (
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/}).

@item 
bpo-38091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38091}: Tweak import deadlock detection code to not deadlock itself.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _locale extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39087}: Optimize @ref{ba9,,PyUnicode_AsUTF8()} and
@ref{885,,PyUnicode_AsUTF8AndSize()} slightly when they need to create
internal UTF-8 cache.

@item 
bpo-39520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39520}: Fix unparsing of ext slices with no items (@code{foo[:,]}). Patch
by Batuhan Taskaya.

@item 
bpo-39220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39220}: Do not optimize annotations if 'from __future__ import
annotations' is used. Patch by Pablo Galindo.

@item 
bpo-35712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35712}: Using @ref{7bc,,NotImplemented} in a boolean context has been
deprecated. Patch contributed by Josh Rosenberg.

@item 
bpo-22490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22490}: Don't leak environment variable @code{__PYVENV_LAUNCHER__} into
the interpreter session on macOS.
@end itemize

@node Library<42>,Documentation<37>,Core and Builtins<43>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id372}@anchor{190c}
@subsubsection Library



@itemize -

@item 
bpo-39830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39830}: Add @ref{6b4,,zipfile.Path} to @code{__all__} in the @ref{130,,zipfile}
module.

@item 
bpo-40000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40000}: Improved error messages for validation of @code{ast.Constant}
nodes. Patch by Batuhan Taskaya.

@item 
bpo-39999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39999}: @code{__module__} of the AST node classes is now set to "ast"
instead of "_ast". Added docstrings for dummy AST node classes and
deprecated attributes.

@item 
bpo-39991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39991}: @ref{b95,,uuid.getnode()} now skips IPv6 addresses with the same
string length than a MAC address (17 characters): only use MAC addresses.

@item 
bpo-39988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39988}: Deprecated @code{ast.AugLoad} and @code{ast.AugStore} node classes
because they are no longer used.

@item 
bpo-39656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39656}: Ensure @code{bin/python3.#} is always present in virtual
environments on POSIX platforms - by Anthony Sottile.

@item 
bpo-39969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39969}: Deprecated @code{ast.Param} node class because it's no longer
used. Patch by Batuhan Taskaya.

@item 
bpo-39360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39360}: Ensure all workers exit when finalizing a
@code{multiprocessing.Pool} implicitly via the module finalization
handlers of multiprocessing. This fixes a deadlock situation that can be
experienced when the Pool is not properly finalized via the context
manager or a call to @code{multiprocessing.Pool.terminate}. Patch by Batuhan
Taskaya and Pablo Galindo.

@item 
bpo-35370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35370}: sys.settrace(), sys.setprofile() and _lsprof.Profiler.enable()
now properly report @ref{365,,PySys_Audit()} error if "sys.setprofile" or
"sys.settrace" audit event is denied.

@item 
bpo-39936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39936}: AIX: Fix _aix_support module when the subprocess is not
available, when building Python from scratch. It now uses new private
_bootsubprocess module, rather than having two implementations depending
if subprocess is available or not. So _aix_support.aix_platform() result
is now the same if subprocess is available or not.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: @ref{5c5,,collections.OrderedDict} now implements @code{|} and
@code{|=} (
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}).

@item 
bpo-39652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39652}: The column name found in @code{sqlite3.Cursor.description} is now
truncated on the first '[' only if the PARSE_COLNAMES option is set.

@item 
bpo-39915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39915}: Ensure @ref{190d,,unittest.mock.AsyncMock.await_args_list} has call
objects in the order of awaited arguments instead of using
@ref{190e,,unittest.mock.Mock.call_args} which has the last value of the call.
Patch by Karthikeyan Singaravelan.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: Updated @ref{1197,,os.environ} and @ref{11f4,,os.environb} to support
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}'s merge (@code{|}) and update (@code{|=}) operators.

@item 
bpo-38662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38662}: The @code{ensurepip} module now invokes @code{pip} via the @code{runpy}
module. Hence it is no longer tightly coupled with the internal API of the
bundled @code{pip} version, allowing easier updates to a newer @code{pip}
version both internally and for distributors.

@item 
bpo-38075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38075}: Fix the @ref{190f,,random.Random.seed()} method when a @ref{451,,bool}
is passed as the seed.

@item 
bpo-39916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39916}: More reliable use of @code{os.scandir()} in @code{Path.glob()}. It no
longer emits a ResourceWarning when interrupted.

@item 
bpo-39850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39850}: @ref{93,,multiprocessing} now supports abstract socket addresses
(if abstract sockets are supported in the running platform). When creating
arbitrary addresses (like when default-constructing
@ref{1632,,multiprocessing.connection.Listener} objects) abstract sockets are
preferred to avoid the case when the temporary-file-generated address is
too large for an AF_UNIX socket address. Patch by Pablo Galindo.

@item 
bpo-36287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36287}: @ref{8d1,,ast.dump()} no longer outputs optional fields and
attributes with default values. The default values for optional fields and
attributes of AST nodes are now set as class attributes (e.g.
@code{Constant.kind} is set to @code{None}).

@item 
bpo-39889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39889}: Fixed @ref{8d2,,ast.unparse()} for extended slices containing a
single element (e.g. @code{a[i:j,]}). Remove redundant tuples when index with
a tuple (e.g. @code{a[i, j]}).

@item 
bpo-39828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39828}: Fix @ref{82,,json.tool} to catch @ref{1045,,BrokenPipeError}. Patch by
Donghee Na.

@item 
bpo-13487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13487}: Avoid a possible `"RuntimeError: dictionary changed size during
iteration"' from @ref{1772,,inspect.getmodule()} when it tried to loop through
@ref{18f9,,sys.modules}.

@item 
bpo-39674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39674}: Revert "bpo-37330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37330}: open() no longer accept 'U' in file mode".
The "U" mode of open() is kept in Python 3.9 to ease transition from
Python 2.7, but will be removed in Python 3.10.

@item 
bpo-28577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28577}: The hosts method on 32-bit prefix length IPv4Networks and
128-bit prefix IPv6Networks now returns a list containing the single
Address instead of an empty list.

@item 
bpo-39826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39826}: Add getConnection method to logging HTTPHandler to enable
custom connections.

@item 
bpo-39763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39763}: Reimplement @code{distutils.spawn.spawn} function with the
@ref{d5,,subprocess} module.

@item 
bpo-39794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39794}: Add --without-decimal-contextvar build option.  This enables a
thread-local rather than a coroutine local context.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: @ref{119a,,collections.defaultdict} now implements @code{|}
(
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}).

@item 
bpo-39517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39517}: Fix runpy.run_path() when using pathlike objects

@item 
bpo-39775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39775}: Change @code{inspect.Signature.parameters} back to
@code{collections.OrderedDict}. This was changed to @code{dict} in Python
3.9.0a4.

@item 
bpo-39678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39678}: Refactor queue_manager in
@ref{8db,,concurrent.futures.ProcessPoolExecutor} to make it easier to
maintain.

@item 
bpo-39764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39764}: Fix AttributeError when calling get_stack on a PyAsyncGenObject
Task

@item 
bpo-39769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39769}: The @ref{b14,,compileall.compile_dir()} function's `ddir' parameter
and the compileall command line flag @code{-d} no longer write the wrong
pathname to the generated pyc file for submodules beneath the root of the
directory tree being compiled.  This fixes a regression introduced with
Python 3.5.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: @ref{457,,types.MappingProxyType} objects now support the merge
(@code{|}) operator from 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@item 
bpo-38691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38691}: The @ref{76,,importlib} module now ignores the
@geindex PYTHONCASEOK
@geindex variable d'environnement; PYTHONCASEOK
@ref{949,,PYTHONCASEOK} environment variable when the @ref{94a,,-E} or
@ref{94b,,-I} command line options are being used.

@item 
bpo-39719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39719}: Remove @code{tempfile.SpooledTemporaryFile.softspace()} as files
no longer have the @code{softspace} attribute in Python 3. Patch by Shantanu.

@item 
bpo-39667@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39667}: Improve pathlib.Path compatibility on zipfile.Path and correct
performance degradation as found in zipp 3.0.

@item 
bpo-39638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39638}: Keep ASDL signatures in the docstrings for @code{AST} nodes. Patch
by Batuhan Taskaya

@item 
bpo-39639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39639}: Deprecated @code{ast.Suite} node class because it's no longer
used. Patch by Batuhan Taskaya.

@item 
bpo-39609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39609}: Add thread_name_prefix to default asyncio executor

@item 
bpo-39548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39548}: Fix handling of header in
@ref{1910,,urllib.request.AbstractDigestAuthHandler} when the optional
@code{qop} parameter is not present.

@item 
bpo-39509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39509}: HTTP status codes @code{103 EARLY_HINTS} and @code{425 TOO_EARLY} are
added to @ref{8ed,,http.HTTPStatus}. Patch by Donghee Na.

@item 
bpo-39507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39507}: Adding HTTP status 418 "I'm a Teapot" to HTTPStatus in http
library. Patch by Ross Rhodes.

@item 
bpo-39495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39495}: Remove default value from `attrs' parameter of
@ref{1911,,xml.etree.ElementTree.TreeBuilder.start()} for consistency between
Python and C implementations.

@item 
bpo-38971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38971}: Open issue in the BPO indicated a desire to make the
implementation of codecs.open() at parity with io.open(), which implements
a try/except to assure file stream gets closed before an exception is
raised.

@item 
bpo-38641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38641}: Added starred expressions support to @code{return} and @code{yield}
statements for @code{lib2to3}. Patch by Vlad Emelianov.

@item 
bpo-37534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37534}: When using minidom module to generate XML documents the ability
to add Standalone Document Declaration is added. All the changes are made
to generate a document in compliance with Extensible Markup Language (XML)
1.0 (Fifth Edition) W3C Recommendation (available here:
@indicateurl{https://www.w3.org/TR/xml/#sec-prolog-dtd}).

@item 
bpo-34788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34788}: Add support for scoped IPv6 addresses to @ref{7f,,ipaddress}.
Patch by Oleksandr Pavliuk.

@item 
bpo-34822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34822}: Simplified AST for subscription. Simple indices are now
represented by their value, extended slices are represented as tuples.
@ref{8,,ast} classes @code{Index} and @code{ExtSlice} are considered deprecated
and will be removed in future Python versions. In the meantime,
@code{Index(value)} now returns a @code{value} itself, @code{ExtSlice(slices)}
returns @code{Tuple(slices, Load())}.
@end itemize

@node Documentation<37>,Tests<40>,Library<42>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id373}@anchor{1912}
@subsubsection Documentation



@itemize -

@item 
bpo-39868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39868}: Updated the Language Reference for 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}.

@item 
bpo-13790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13790}: Change 'string' to 'specification' in format doc.

@item 
bpo-17422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17422}: The language reference no longer restricts default class
namespaces to dicts only.

@item 
bpo-39530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39530}: Fix misleading documentation about mixed-type numeric
comparisons.

@item 
bpo-39718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39718}: Update @ref{f9,,token} documentation to reflect additions in
Python 3.8

@item 
bpo-39677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39677}: Changed operand name of `MAKE_FUNCTION' from `argc' to
`flags' for module @ref{38,,dis}
@end itemize

@node Tests<40>,Build<42>,Documentation<37>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id374}@anchor{1913}
@subsubsection Tests



@itemize -

@item 
bpo-40019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40019}: test_gdb now skips tests if it detects that gdb failed to read
debug information because the Python binary is optimized.

@item 
bpo-27807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27807}: @code{test_site.test_startup_imports()} is now skipped if a path
of @ref{3ab,,sys.path} contains a @code{.pth} file.

@item 
bpo-26067@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26067}: Do not fail test_shutil test_chown test when uid or gid of user
cannot be resolved to a name.

@item 
bpo-39855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39855}: test_subprocess.test_user() now skips the test on an user name
if the user name doesn't exist. For example, skip the test if the user
"nobody" doesn't exist on Linux.
@end itemize

@node Build<42>,Windows<38>,Tests<40>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id375}@anchor{1914}
@subsubsection Build



@itemize -

@item 
bpo-39761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39761}: Fix build with DTrace but without additional DFLAGS.

@item 
bpo-39763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39763}: setup.py now uses a basic implementation of the
@ref{d5,,subprocess} module if the @ref{d5,,subprocess} module is not available:
before required C extension modules are built.

@item 
bpo-1294959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1294959}: Add @code{--with-platlibdir} option to the configure script:
name of the platform-specific library directory, stored in the new
@ref{925,,sys.platlibdir} attribute. It is used to build the path of
platform-specific extension modules and the path of the standard library.
It is equal to @code{"lib"} on most platforms. On Fedora and SuSE, it is
equal to @code{"lib64"} on 64-bit platforms. Patch by Jan Matějek, Matěj
Cepl, Charalampos Stratakis and Victor Stinner.
@end itemize

@node Windows<38>,macOS<32>,Build<42>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id376}@anchor{1915}
@subsubsection Windows



@itemize -

@item 
bpo-39930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39930}: Ensures the required @code{vcruntime140.dll} is included in
install packages.

@item 
bpo-39847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39847}: Avoid hang when computer is hibernated whilst waiting for a
mutex (for lock-related objects from @ref{ec,,threading}) around 49-day
uptime.

@item 
bpo-38597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38597}: @code{distutils} will no longer statically link
@code{vcruntime140.dll} when a redistributable version is unavailable.
All future releases of CPython will include a copy of this DLL to ensure
distributed extensions can continue to load.

@item 
bpo-38380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38380}: Update Windows builds to use SQLite 3.31.1

@item 
bpo-39789@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39789}: Update Windows release build machines to Visual Studio 2019
(MSVC 14.2).

@item 
bpo-34803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34803}: Package for nuget.org now includes repository reference and
bundled icon image.
@end itemize

@node macOS<32>,IDLE<28>,Windows<38>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id377}@anchor{1916}
@subsubsection macOS



@itemize -

@item 
bpo-38380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38380}: Update macOS builds to use SQLite 3.31.1
@end itemize

@node IDLE<28>,Tools/Demos<20>,macOS<32>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id378}@anchor{1917}
@subsubsection IDLE



@itemize -

@item 
bpo-27115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27115}: For 'Go to Line', use a Query box subclass with IDLE standard
behavior and improved error checking.

@item 
bpo-39885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39885}: Since clicking to get an IDLE context menu moves the cursor,
any text selection should be and now is cleared.

@item 
bpo-39852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39852}: Edit "Go to line" now clears any selection, preventing
accidental deletion. It also updates Ln and Col on the status bar.

@item 
bpo-39781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39781}: Selecting code context lines no longer causes a jump.
@end itemize

@node Tools/Demos<20>,C API<41>,IDLE<28>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id379}@anchor{1918}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-36184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36184}: Port python-gdb.py to FreeBSD. python-gdb.py now checks for
"take_gil" function name to check if a frame tries to acquire the GIL,
instead of checking for "pthread_cond_timedwait" which is specific to
Linux and can be a different condition than the GIL.

@item 
bpo-38080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38080}: Added support to fix @code{getproxies} in the
@code{lib2to3.fixes.fix_urllib} module. Patch by José Roberto Meza
Cabrera.
@end itemize

@node C API<41>,,Tools/Demos<20>,Python 3 9 0 alpha 5
@anchor{whatsnew/changelog id380}@anchor{1919}
@subsubsection C API



@itemize -

@item 
bpo-40024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=40024}: Add @ref{962,,PyModule_AddType()} helper function: add a type to a
module. Patch by Donghee Na.

@item 
bpo-39946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39946}: Remove @code{_PyRuntime.getframe} hook and remove
@code{_PyThreadState_GetFrame} macro which was an alias to
@code{_PyRuntime.getframe}. They were only exposed by the internal C API.
Remove also @code{PyThreadFrameGetter} type.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Add @ref{778,,PyThreadState_GetFrame()} function: get the current
frame of a Python thread state.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Add _PyArg_NoKwnames helper function. Patch by Donghee Na.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Add @ref{95e,,PyThreadState_GetInterpreter()}: get the interpreter
of a Python thread state.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Add @ref{3a4,,PyInterpreterState_Get()} function to the limited C
API.

@item 
bpo-35370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35370}: If @ref{365,,PySys_Audit()} fails in @ref{14b3,,PyEval_SetProfile()}
or @ref{14b4,,PyEval_SetTrace()}, log the error as an unraisable exception.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Move the static inline function flavor of
Py_EnterRecursiveCall() and Py_LeaveRecursiveCall() to the internal C API:
they access PyThreadState attributes. The limited C API provides regular
functions which hide implementation details.

@item 
bpo-39947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39947}: Py_TRASHCAN_BEGIN_CONDITION and Py_TRASHCAN_END macro no longer
access PyThreadState attributes, but call new private _PyTrash_begin() and
_PyTrash_end() functions which hide implementation details.

@item 
bpo-39884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39884}: @ref{191a,,PyDescr_NewMethod()} and @ref{191b,,PyCFunction_NewEx()} now
include the method name in the SystemError "bad call flags" error message
to ease debug.

@item 
bpo-39877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39877}: Deprecated @code{PyEval_InitThreads()} and
@code{PyEval_ThreadsInitialized()}. Calling
@code{PyEval_InitThreads()} now does nothing.

@item 
bpo-38249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38249}: @ref{ba3,,Py_UNREACHABLE} is now implemented with
@code{__builtin_unreachable()} and analogs in release mode.

@item 
bpo-38643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38643}: @ref{1778,,PyNumber_ToBase()} now raises a @ref{561,,SystemError}
instead of crashing when called with invalid base.

@item 
bpo-39882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39882}: The @ref{970,,Py_FatalError()} function is replaced with a macro
which logs automatically the name of the current function, unless the
@code{Py_LIMITED_API} macro is defined.

@item 
bpo-39824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39824}: Extension modules: @ref{967,,m_traverse},
@ref{968,,m_clear} and @ref{969,,m_free}
functions of @ref{96a,,PyModuleDef} are no longer called if the module
state was requested but is not allocated yet. This is the case immediately
after the module is created and before the module is executed
(@ref{96b,,Py_mod_exec} function). More precisely, these functions are not
called if @ref{96c,,m_size} is greater than 0 and the module
state (as returned by @ref{96d,,PyModule_GetState()}) is @code{NULL}.

Extension modules without module state (@code{m_size <= 0}) are not affected.

@item 
bpo-38913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38913}: Fixed segfault in @code{Py_BuildValue()} called with a format
containing "#" and undefined PY_SSIZE_T_CLEAN whwn an exception is set.

@item 
bpo-38500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38500}: Add a private API to get and set the frame evaluation function:
add @ref{191c,,_PyInterpreterState_GetEvalFrameFunc()} and
@ref{191d,,_PyInterpreterState_SetEvalFrameFunc()} C functions. The
@ref{760,,_PyFrameEvalFunction} function type now takes a `tstate'
parameter.
@end itemize

@node Python 3 9 0 alpha 4,Python 3 9 0 alpha 3,Python 3 9 0 alpha 5,Changelog
@anchor{whatsnew/changelog python-3-9-0-alpha-4}@anchor{191e}
@subsection Python 3.9.0 alpha 4


`Release date: 2020-02-25'

@menu
* Security: Security<29>. 
* Core and Builtins: Core and Builtins<44>. 
* Library: Library<43>. 
* Documentation: Documentation<38>. 
* Tests: Tests<41>. 
* Build: Build<43>. 
* Windows: Windows<39>. 
* IDLE: IDLE<29>. 
* C API: C API<42>. 

@end menu

@node Security<29>,Core and Builtins<44>,,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id381}@anchor{191f}
@subsubsection Security



@itemize -

@item 
bpo-39184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39184}: Add audit events to functions in @code{fcntl}, @code{msvcrt}, @code{os},
@code{resource}, @code{shutil}, @code{signal} and @code{syslog}.

@item 
bpo-39401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39401}: Avoid unsafe DLL load at startup on Windows 7 and earlier.

@item 
bpo-39184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39184}: Add audit events to command execution functions in os and pty
modules.
@end itemize

@node Core and Builtins<44>,Library<43>,Security<29>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id382}@anchor{1920}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-39382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39382}: Fix a use-after-free in the single inheritance path of
@code{issubclass()}, when the @code{__bases__} of an object has a single
reference, and so does its first item. Patch by Yonatan Goldschmidt.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Update clinic tool to use @ref{17a3,,Py_IS_TYPE()}. Patch by
Donghee Na.

@item 
bpo-39619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39619}: Enable use of @ref{1921,,os.chroot()} on HP-UX systems.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{17a3,,Py_IS_TYPE()} static inline function to check
whether the object `o' type is `type'.

@item 
bpo-39606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39606}: Fix regression caused by fix for bpo-39386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39386}, that prevented
calling @code{aclose} on an async generator that had already been closed or
exhausted.

@item 
bpo-39579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39579}: Change the ending column offset of @code{Attribute} nodes
constructed in @code{ast_for_dotted_name} to point at the end of the current
node and not at the end of the last @code{NAME} node.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _crypt extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _contextvars extension module to multiphase
initialization (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39510}: Fix segfault in @code{readinto()} method on closed BufferedReader.

@item 
bpo-39502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39502}: Fix @ref{14af,,time.localtime()} on 64-bit AIX  to support years
before 1902 and after 2038. Patch by M Felt.

@item 
bpo-39492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39492}: Fix a reference cycle in the C Pickler that was preventing the
garbage collection of deleted, pickled objects.

@item 
bpo-39453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39453}: Fixed a possible crash in @code{list.__contains__()} when a list
is changed during comparing items. Patch by Donghee Na.

@item 
bpo-39434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39434}: @ref{931,,floor division} of float operation now has a better
performance. Also the message of @ref{932,,ZeroDivisionError} for this
operation is updated. Patch by Donghee Na.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _codecs extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _bz2 extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _abc extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39320}: Replace two complex bytecodes for building dicts with two
simpler ones. The new bytecodes @code{DICT_MERGE} and @code{DICT_UPDATE} have
been added The old bytecodes @code{BUILD_MAP_UNPACK} and
@code{BUILD_MAP_UNPACK_WITH_CALL} have been removed.

@item 
bpo-39219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39219}: Syntax errors raised in the tokenizer now always set correct
"text" and "offset" attributes.

@item 
bpo-36051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36051}: Drop the GIL during large @code{bytes.join} operations. Patch by
Bruce Merry.

@item 
bpo-38960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38960}: Fix DTrace build issues on FreeBSD. Patch by David Carlier.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: Speed up calls to @code{range()} by about 30%, by using the PEP
590 @code{vectorcall} calling convention. Patch by Mark Shannon.

@item 
bpo-36144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36144}: @ref{253,,dict} (and @ref{1922,,collections.UserDict}) objects now
support PEP 584's merge (@code{|}) and update (@code{|=}) operators. Patch by
Brandt Bucher.

@item 
bpo-32856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32856}: Optimized the idiom for assignment a temporary variable in
comprehensions. Now @code{for y in [expr]} in comprehensions is as fast as a
simple assignment @code{y = expr}.
@end itemize

@node Library<43>,Documentation<38>,Core and Builtins<44>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id383}@anchor{1923}
@subsubsection Library



@itemize -

@item 
bpo-30566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30566}: Fix @ref{14eb,,IndexError} when trying to decode an invalid string
with punycode codec.

@item 
bpo-39649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39649}: Remove obsolete check for @code{__args__} in
@code{bdb.Bdb.format_stack_entry}.

@item 
bpo-39648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39648}: Expanded @ref{8fd,,math.gcd()} and @ref{8fe,,math.lcm()} to handle
multiple arguments.

@item 
bpo-39681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39681}: Fix a regression where the C pickle module wouldn't allow
unpickling from a file-like object that doesn't expose a readinto()
method.

@item 
bpo-35950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35950}: Raise @ref{1924,,io.UnsupportedOperation} in
@code{io.BufferedReader.truncate()} when it is called on a read-only
@ref{11eb,,io.BufferedReader} instance.

@item 
bpo-39479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39479}: Add @ref{8fe,,math.lcm()} function: least common multiple.

@item 
bpo-39674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39674}: Revert "Do not expose abstract collection classes in the
collections module" change (bpo-25988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25988}). Aliases to ABC like
collections.Mapping are kept in Python 3.9 to ease transition from Python
2.7, but will be removed in Python 3.10.

@item 
bpo-39104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39104}: Fix hanging ProcessPoolExcutor on @code{shutdown(wait=False)} when
a task has failed pickling.

@item 
bpo-39627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39627}: Fixed TypedDict totality check for inherited keys.

@item 
bpo-39474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39474}: Fixed starting position of AST for expressions like @code{(a)(b)},
@code{(a)[b]} and @code{(a).b}.

@item 
bpo-21016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21016}: The @ref{b4,,pydoc} and @ref{fc,,trace} modules now use the
@ref{da,,sysconfig} module to get the path to the Python standard library, to
support uncommon installation path like @code{/usr/lib64/python3.9/} on
Fedora. Patch by Jan Matějek.

@item 
bpo-39590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39590}: Collections.deque now holds strong references during
deque.__contains__ and deque.count, fixing crashes.

@item 
bpo-39586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39586}: The distutils @code{bdist_msi} command is deprecated in Python
3.9, use @code{bdist_wheel} (wheel packages) instead.

@item 
bpo-39595@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39595}: Improved performance of zipfile.Path for files with a large
number of entries. Also improved performance and fixed minor issue as
published with importlib_metadata 1.5@footnote{https://importlib-metadata.readthedocs.io/en/latest/history.html#v1-5-0}.

@item 
bpo-39350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39350}: Fix regression in @ref{1e4,,fractions.Fraction} if the numerator
and/or the denominator is an @ref{254,,int} subclass. The @ref{8fd,,math.gcd()}
function is now used to normalize the `numerator' and `denominator'.
@ref{8fd,,math.gcd()} always return a @ref{254,,int} type. Previously, the GCD
type depended on `numerator' and `denominator'.

@item 
bpo-39567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39567}: Added audit for @ref{493,,os.walk()}, @ref{b49,,os.fwalk()},
@ref{22a,,pathlib.Path.glob()} and @ref{22b,,pathlib.Path.rglob()}.

@item 
bpo-39559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39559}: Remove unused, undocumented argument @code{getters} from
@ref{b95,,uuid.getnode()}

@item 
bpo-38149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38149}: @ref{153f,,sys.audit()} is now called only once per call of
@ref{29c,,glob.glob()} and @ref{7f1,,glob.iglob()}.

@item 
bpo-39546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39546}: Fix a regression in @ref{523,,ArgumentParser} where
@code{allow_abbrev=False} was ignored for long options that used a prefix
character other than "-".

@item 
bpo-39450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39450}: Striped whitespace from docstring before returning it from
@code{unittest.case.shortDescription()}.

@item 
bpo-12915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12915}: A new function @code{resolve_name} has been added to the
@code{pkgutil} module. This resolves a string of the form @code{'a.b.c.d'} or
@code{'a.b:c.d'} to an object. In the example, @code{a.b} is a package/module
and @code{c.d} is an object within that package/module reached via recursive
attribute access.

@item 
bpo-39353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39353}: The @ref{71e,,binascii.crc_hqx()} function is no longer deprecated.

@item 
bpo-39493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39493}: Mark @code{typing.IO.closed} as a property

@item 
bpo-39491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39491}: Add @ref{92a,,typing.Annotated} and @code{include_extras} parameter
to @ref{69c,,typing.get_type_hints()} as part of 
@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/}. Patch by Till
Varoquaux, documentation by Till Varoquaux and Konstantin Kashin.

@item 
bpo-39485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39485}: Fix a bug in @ref{1590,,unittest.mock.create_autospec()} that would
complain about the wrong number of arguments for custom descriptors
defined in an extension module returning functions.

@item 
bpo-38932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38932}: Mock fully resets child objects on reset_mock(). Patch by
Vegard Stikbakke

@item 
bpo-39082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39082}: Allow AsyncMock to correctly patch static/class methods

@item 
bpo-39432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39432}: Implement PEP-489 algorithm for non-ascii "PyInit_..." symbol
names in distutils to make it export the correct init symbol also on
Windows.

@item 
bpo-18819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18819}: Omit @code{devmajor} and @code{devminor} fields for non-device files
in @ref{dd,,tarfile} archives, enabling bit-for-bit compatibility with GNU
@code{tar(1)}.

@item 
bpo-39349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39349}: Added a new `cancel_futures' parameter to
@ref{8da,,concurrent.futures.Executor.shutdown()} that cancels all pending
futures which have not started running, instead of waiting for them to
complete before shutting down the executor.

@item 
bpo-39274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39274}: @code{bool(fraction.Fraction)} now returns a boolean even if
(numerator != 0) does not return a boolean (ex: numpy number).

@item 
bpo-34793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34793}: Remove support for @code{with (await asyncio.lock):} and @code{with
(yield from asyncio.lock):}.  The same is correct for
@code{asyncio.Condition} and @code{asyncio.Semaphore}.

@item 
bpo-25597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25597}: Ensure, if @code{wraps} is supplied to
@ref{e7a,,unittest.mock.MagicMock}, it is used to calculate return values
for the magic methods instead of using the default return values. Patch by
Karthikeyan Singaravelan.

@item 
bpo-36350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36350}: @code{inspect.Signature.parameters} and
@code{inspect.BoundArguments.arguments} are now dicts instead of
OrderedDicts. Patch contributed by Rémi Lapeyre.

@item 
bpo-35727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35727}: Fix sys.exit() and sys.exit(None) exit code propagation when
used in multiprocessing.Process.

@item 
bpo-32173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32173}: * Add @code{lazycache} function to @code{__all__}. * Use
@code{dict.clear} to clear the cache. * Refactoring @code{getline} function and
@code{checkcache} function.
@end itemize

@node Documentation<38>,Tests<41>,Library<43>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id384}@anchor{1925}
@subsubsection Documentation



@itemize -

@item 
bpo-17422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17422}: The language reference now specifies restrictions on class
namespaces. Adapted from a patch by Ethan Furman.

@item 
bpo-39572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39572}: Updated documentation of @code{total} flag of @code{TypedDict}.

@item 
bpo-39654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39654}: In pyclbr doc, update 'class' to 'module' where appropriate and
add readmodule comment. Patch by Hakan Çelik.

@item 
bpo-39153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39153}: Clarify refcounting semantics for the following functions: -
PyObject_SetItem - PyMapping_SetItemString - PyDict_SetItem -
PyDict_SetItemString

@item 
bpo-39392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39392}: Explain that when filling with turtle, overlap regions may be
left unfilled.

@item 
bpo-39369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39369}: Update mmap readline method description. The fact that the
readline method does update the file position should not be ignored since
this might give the impression for the programmer that it doesn't update
it.

@item 
bpo-9056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9056}: Include subsection in TOC for PDF version of docs.
@end itemize

@node Tests<41>,Build<43>,Documentation<38>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id385}@anchor{1926}
@subsubsection Tests



@itemize -

@item 
bpo-38325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38325}: Skip tests on non-BMP characters of test_winconsoleio.

@item 
bpo-39502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39502}: Skip test_zipfile.test_add_file_after_2107() if
@ref{14af,,time.localtime()} fails with @ref{86d,,OverflowError}. It is the case on
AIX 6.1 for example.
@end itemize

@node Build<43>,Windows<39>,Tests<41>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id386}@anchor{1927}
@subsubsection Build



@itemize -

@item 
bpo-39489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39489}: Remove @code{COUNT_ALLOCS} special build.
@end itemize

@node Windows<39>,IDLE<29>,Build<43>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id387}@anchor{1928}
@subsubsection Windows



@itemize -

@item 
bpo-39553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39553}: Delete unused code related to SxS manifests.

@item 
bpo-39439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39439}: Honor the Python path when a virtualenv is active on Windows.

@item 
bpo-39393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39393}: Improve the error message when attempting to load a DLL with
unresolved dependencies.

@item 
bpo-38883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38883}: @ref{e30,,home()} and @ref{e2f,,expanduser()}
on Windows now prefer 
@geindex USERPROFILE
@geindex variable d'environnement; USERPROFILE
@code{USERPROFILE} and no longer use
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME}, which is not normally set for regular user accounts. This
makes them again behave like @ref{a02,,os.path.expanduser()}, which was changed
to ignore 
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME} in 3.8, see bpo-36264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36264}.

@item 
bpo-39185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39185}: The build.bat script has additional options for very-quiet
output (-q) and very-verbose output (-vv)
@end itemize

@node IDLE<29>,C API<42>,Windows<39>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id388}@anchor{1929}
@subsubsection IDLE



@itemize -

@item 
bpo-39663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39663}: Add tests for pyparse find_good_parse_start().

@item 
bpo-39600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39600}: In the font configuration window, remove duplicated font names.

@item 
bpo-30780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30780}: Add remaining configdialog tests for buttons and highlights and
keys tabs.

@item 
bpo-39388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39388}: IDLE Settings Cancel button now cancels pending changes

@item 
bpo-38792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38792}: Close an IDLE shell calltip if a @ref{9bf,,KeyboardInterrupt} or
shell restart occurs.  Patch by Zackery Spytz.
@end itemize

@node C API<42>,,IDLE<29>,Python 3 9 0 alpha 4
@anchor{whatsnew/changelog id389}@anchor{192a}
@subsubsection C API



@itemize -

@item 
bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081}: Move the @code{bytes_methods.h} header file to the internal C API
as @code{pycore_bytes_methods.h}: it only contains private symbols (prefixed
by @code{_Py}), except of the @code{PyDoc_STRVAR_shared()} macro.

@item 
bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081}: Move the @code{dtoa.h} header file to the internal C API as
@code{pycore_dtoa.h}: it only contains private functions (prefixed by
@code{_Py}). The @ref{8d,,math} and @ref{18,,cmath} modules must now be compiled
with the @code{Py_BUILD_CORE} macro defined.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{76d,,Py_SET_SIZE()} function to set the size of an
object.

@item 
bpo-39500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39500}: @ref{192b,,PyUnicode_IsIdentifier()} does not call
@ref{970,,Py_FatalError()} anymore if the string is not ready.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add @ref{76b,,Py_SET_TYPE()} function to set the type of an
object.

@item 
bpo-39573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39573}: Add a @ref{897,,Py_SET_REFCNT()} function to set the reference
counter of an object.

@item 
bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}: Convert @ref{18e0,,PyType_HasFeature()}, @ref{192c,,PyType_Check()} and
@ref{192d,,PyType_CheckExact()} macros to static inline functions.

@item 
bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}: In the limited C API, @code{PyObject_INIT()} and
@code{PyObject_INIT_VAR()} are now defined as aliases to
@ref{a58,,PyObject_Init()} and @ref{18e2,,PyObject_InitVar()} to make their
implementation opaque. It avoids to leak implementation details in the
limited C API. Exclude the following functions from the limited C API:
@code{_Py_NewReference()}, @code{_Py_ForgetReference()},
@code{_PyTraceMalloc_NewReference()} and @code{_Py_GetRefTotal()}.

@item 
bpo-39542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39542}: Exclude trashcan mechanism from the limited C API: it requires
access to PyTypeObject and PyThreadState structure fields, whereas these
structures are opaque in the limited C API.

@item 
bpo-39511@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39511}: The @ref{15aa,,PyThreadState_Clear()} function now calls the
@code{PyThreadState.on_delete} callback. Previously, that happened in
@ref{192e,,PyThreadState_Delete()}.

@item 
bpo-38076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38076}: Fix to clear the interpreter state only after clearing module
globals to guarantee module state access from C Extensions during runtime
destruction

@item 
bpo-39245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39245}: The Vectorcall API (PEP 590) was made public, adding the
functions @code{PyObject_Vectorcall}, @code{PyObject_VectorcallMethod},
@code{PyVectorcall_Function}, @code{PyObject_CallOneArg},
@code{PyObject_CallMethodNoArgs}, @code{PyObject_CallMethodOneArg},
@code{PyObject_FastCallDict}, and the flag @code{Py_TPFLAGS_HAVE_VECTORCALL}.
@end itemize

@node Python 3 9 0 alpha 3,Python 3 9 0 alpha 2,Python 3 9 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-9-0-alpha-3}@anchor{192f}
@subsection Python 3.9.0 alpha 3


`Release date: 2020-01-24'

@menu
* Core and Builtins: Core and Builtins<45>. 
* Library: Library<44>. 
* Documentation: Documentation<39>. 
* Build: Build<44>. 
* IDLE: IDLE<30>. 
* C API: C API<43>. 

@end menu

@node Core and Builtins<45>,Library<44>,,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id390}@anchor{1930}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-39427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39427}: Document all possibilities for the @code{-X} options in the
command line help section. Patch by Pablo Galindo.

@item 
bpo-39421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39421}: Fix possible crashes when operating with the functions in the
@ref{68,,heapq} module and custom comparison operators.

@item 
bpo-39386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39386}: Prevent double awaiting of async iterator.

@item 
bpo-17005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17005}: Add @code{functools.TopologicalSorter} to the
@ref{5e,,functools} module to offers functionality to perform topological
sorting of graphs. Patch by Pablo Galindo, Tim Peters and Larry Hastings.

@item 
bpo-39320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39320}: Replace four complex bytecodes for building sequences with
three simpler ones.

The following four bytecodes have been removed:


@itemize *

@item 
BUILD_LIST_UNPACK

@item 
BUILD_TUPLE_UNPACK

@item 
BUILD_SET_UNPACK

@item 
BUILD_TUPLE_UNPACK_WITH_CALL
@end itemize

The following three bytecodes have been added:


@itemize *

@item 
LIST_TO_TUPLE

@item 
LIST_EXTEND

@item 
SET_UPDATE
@end itemize

@item 
bpo-39336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39336}: Import loaders which publish immutable module objects can now
publish immutable packages in addition to individual modules.

@item 
bpo-39322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39322}: Added a new function @ref{8ea,,gc.is_finalized()} to check if an
object has been finalized by the garbage collector. Patch by Pablo
Galindo.

@item 
bpo-39048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39048}: Improve the displayed error message when incorrect types are
passed to @code{async with} statements by looking up the @code{__aenter__()}
special method before the @code{__aexit__()} special method when entering
an asynchronous context manager. Patch by Géry Ogam.

@item 
bpo-39235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39235}: Fix AST end location for lone generator expression in function
call, e.g. f(i for i in a).

@item 
bpo-39209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39209}: Correctly handle multi-line tokens in interactive mode. Patch
by Pablo Galindo.

@item 
bpo-1635741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1635741}: Port _json extension module to multiphase initialization
(
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}).

@item 
bpo-39216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39216}: Fix constant folding optimization for positional only arguments
- by Anthony Sottile.

@item 
bpo-39215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39215}: Fix @code{SystemError} when nested function has annotation on
positional-only argument - by Anthony Sottile.

@item 
bpo-39200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39200}: Correct the error message when calling the @ref{ef3,,min()} or
@ref{ef4,,max()} with no arguments. Patch by Donghee Na.

@item 
bpo-39200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39200}: Correct the error message when trying to construct
@ref{930,,range} objects with no arguments. Patch by Pablo Galindo.

@item 
bpo-39166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39166}: Fix incorrect line execution reporting in trace functions when
tracing the last iteration of asynchronous for loops. Patch by Pablo
Galindo.

@item 
bpo-39114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39114}: Fix incorrect line execution reporting in trace functions when
tracing exception handlers with name binding. Patch by Pablo Galindo.

@item 
bpo-39156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39156}: Split the COMPARE_OP bytecode instruction into four distinct
instructions.


@itemize *

@item 
COMPARE_OP for rich comparisons

@item 
IS_OP for 'is' and 'is not' tests

@item 
CONTAINS_OP for 'in' and 'is not' tests

@item 
JUMP_IF_NOT_EXC_MATCH for checking exceptions in 'try-except' statements.
@end itemize

This improves the clarity of the interpreter and should provide a modest
speedup.

@item 
bpo-38588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38588}: Fix possible crashes in dict and list when calling
@ref{1931,,PyObject_RichCompareBool()}.

@item 
bpo-13601@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13601}: By default, @code{sys.stderr} is line-buffered now, even if
@code{stderr} is redirected to a file. You can still make @code{sys.stderr}
unbuffered by passing the @ref{1932,,-u} command-line option or setting the
@geindex PYTHONUNBUFFERED
@geindex variable d'environnement; PYTHONUNBUFFERED
@ref{1933,,PYTHONUNBUFFERED} environment variable.

(Contributed by Jendrik Seipp in bpo-13601@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13601}.)

@item 
bpo-38610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38610}: Fix possible crashes in several list methods by holding strong
references to list elements when calling
@ref{1931,,PyObject_RichCompareBool()}.

@item 
bpo-32021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32021}: Include brotli .br encoding in mimetypes encodings_map
@end itemize

@node Library<44>,Documentation<39>,Core and Builtins<45>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id391}@anchor{1934}
@subsubsection Library



@itemize -

@item 
bpo-39430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39430}: Fixed race condition in lazy imports in @ref{dd,,tarfile}.

@item 
bpo-39413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39413}: The @ref{908,,os.unsetenv()} function is now also available on
Windows.

@item 
bpo-39390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39390}: Fixed a regression with the @code{ignore} callback of
@ref{a17,,shutil.copytree()}. The argument types are now @code{str} and
@code{List[str]} again.

@item 
bpo-39395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39395}: The @ref{909,,os.putenv()} and @ref{908,,os.unsetenv()} functions are now
always available.

@item 
bpo-39406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39406}: If @code{setenv()} C function is available, @ref{909,,os.putenv()} is
now implemented with @code{setenv()} instead of @code{putenv()}, so Python
doesn't have to handle the environment variable memory.

@item 
bpo-39396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39396}: Fix @code{math.nextafter(-0.0, +0.0)} on AIX 7.1.

@item 
bpo-29435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29435}: Allow @ref{17d2,,tarfile.is_tarfile()} to be used with file and
file-like objects, like @ref{1308,,zipfile.is_zipfile()}. Patch by William
Woodruff.

@item 
bpo-39377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39377}: Removed @code{encoding} option from @ref{942,,json.loads()}.  It has
been deprecated since Python 3.1.

@item 
bpo-39389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39389}: Write accurate compression level metadata in @ref{66,,gzip}
archives, rather than always signaling maximum compression.

@item 
bpo-39366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39366}: The previously deprecated @code{xpath()} and @code{xgtitle()} methods
of @code{nntplib.NNTP} have been removed.

@item 
bpo-39357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39357}: Remove the `buffering' parameter of @ref{851,,bz2.BZ2File}. Since
Python 3.0, it was ignored and using it was emitting
@ref{1a3,,DeprecationWarning}. Pass an open file object, to control how the
file is opened. The `compresslevel' parameter becomes keyword-only.

@item 
bpo-39353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39353}: Deprecate binhex4 and hexbin4 standards. Deprecate the
@code{binhex} module and the following @ref{10,,binascii} functions:
@code{b2a_hqx()}, @code{a2b_hqx()},
@code{rlecode_hqx()}, @code{rledecode_hqx()},
@ref{71e,,crc_hqx()}.

@item 
bpo-39351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39351}: Remove @code{base64.encodestring()} and @code{base64.decodestring()},
aliases deprecated since Python 3.1: use @ref{940,,base64.encodebytes()} and
@ref{941,,base64.decodebytes()} instead.

@item 
bpo-39350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39350}: Remove @code{fractions.gcd()} function, deprecated since Python
3.5 (bpo-22486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22486}): use @ref{8fd,,math.gcd()} instead.

@item 
bpo-39329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39329}: @ref{91c,,LMTP} constructor now has an optional
`timeout' parameter. Patch by Donghee Na.

@item 
bpo-39313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39313}: Add a new @code{exec_function} option (`--exec-function' in the
CLI) to @code{RefactoringTool} for making @code{exec} a function. Patch by
Batuhan Taskaya.

@item 
bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}: @ref{8e8,,FTP_TLS} and @ref{8e8,,FTP_TLS} now raise
a @ref{1ff,,ValueError} if the given timeout for their constructor is zero
to prevent the creation of a non-blocking socket. Patch by Donghee Na.

@item 
bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}: @ref{91a,,SMTP} and @ref{91b,,SMTP_SSL} now raise
a @ref{1ff,,ValueError} if the given timeout for their constructor is zero
to prevent the creation of a non-blocking socket. Patch by Donghee Na.

@item 
bpo-39310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39310}: Add @ref{8ff,,math.ulp()}: return the value of the least significant
bit of a float.

@item 
bpo-39297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39297}: Improved performance of importlib.metadata distribution
discovery and resilients to inaccessible sys.path entries
(importlib_metadata v1.4.0).

@item 
bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}: @code{NNTP} and @code{NNTP_SSL} now raise a
@ref{1ff,,ValueError} if the given timeout for their constructor is zero to
prevent the creation of a non-blocking socket. Patch by Donghee Na.

@item 
bpo-38901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38901}: When you specify prompt='.' or equivalently python -m venv
--prompt . ... the basename of the current directory is used to set the
created venv's prompt when it's activated.

@item 
bpo-39288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39288}: Add @ref{482,,math.nextafter()}: return the next floating-point
value after `x' towards `y'.

@item 
bpo-39259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39259}: @ref{911,,POP3} and @ref{912,,POP3_SSL} now raise a
@ref{1ff,,ValueError} if the given timeout for their constructor is zero to
prevent the creation of a non-blocking socket. Patch by Donghee Na.

@item 
bpo-39242@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39242}: Updated the Gmane domain from news.gmane.org to news.gmane.io
which is used for examples of @code{NNTP} news reader server and
nntplib tests.

@item 
bpo-35292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35292}: Proxy the @code{SimpleHTTPRequestHandler.guess_type} to
@code{mimetypes.guess_type} so the @code{mimetypes.init} is called lazily to
avoid unnecessary costs when @ref{71,,http.server} module is imported.

@item 
bpo-39239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39239}: The @ref{947,,select.epoll.unregister()} method no longer ignores
the @ref{948,,EBADF} error.

@item 
bpo-38907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38907}: In http.server script, restore binding to IPv4 on Windows.

@item 
bpo-39152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39152}: Fix ttk.Scale.configure([name]) to return configuration tuple
for name or all options.  Giovanni Lombardo contributed part of the patch.

@item 
bpo-39198@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39198}: If an exception were to be thrown in @code{Logger.isEnabledFor}
(say, by asyncio timeouts or stopit) , the @code{logging} global lock may not
be released appropriately, resulting in deadlock.  This change wraps that
block of code with @code{try...finally} to ensure the lock is released.

@item 
bpo-39191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39191}: Perform a check for running loop before starting a new task in
@code{loop.run_until_complete()} to fail fast; it prevents the side effect of
new task spawning before exception raising.

@item 
bpo-38871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38871}: Correctly parenthesize filter-based statements that contain
lambda expressions in @code{lib2to3}. Patch by Donghee Na.

@item 
bpo-39142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39142}: A change was made to logging.config.dictConfig to avoid
converting instances of named tuples to ConvertingTuple. It's assumed that
named tuples are too specialised to be treated like ordinary tuples; if a
user of named tuples requires ConvertingTuple functionality, they will
have to implement that themselves in their named tuple class.

@item 
bpo-39158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39158}: ast.literal_eval() now supports empty sets.

@item 
bpo-39129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39129}: Fix import path for @code{asyncio.TimeoutError}

@item 
bpo-39057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39057}: @code{urllib.request.proxy_bypass_environment()} now ignores
leading dots and no longer ignores a trailing newline.

@item 
bpo-39056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39056}: Fixed handling invalid warning category in the -W option.  No
longer import the re module if it is not needed.

@item 
bpo-39055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39055}: @ref{1935,,base64.b64decode()} with @code{validate=True} raises now a
binascii.Error if the input ends with a single @code{\n}.

@item 
bpo-21600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21600}: Fix @code{mock.patch.stopall()} to stop active patches that were
created with @code{mock.patch.dict()}.

@item 
bpo-39019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39019}: Implement dummy @code{__class_getitem__} for
@ref{67e,,tempfile.SpooledTemporaryFile}.

@item 
bpo-39019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39019}: Implement dummy @code{__class_getitem__} for @code{subprocess.Popen},
@code{subprocess.CompletedProcess}

@item 
bpo-38914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38914}: Adjusted the wording of the warning issued by distutils'
@code{check} command when the @code{author} and @code{maintainer} fields are
supplied but no corresponding e-mail field (@code{author_email} or
@code{maintainer_email}) is found. The wording now reflects the fact that
these fields are suggested, but not required. Patch by Juergen Gmach.

@item 
bpo-38878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38878}: Fixed __subclasshook__ of @ref{c3f,,os.PathLike} to return a
correct result upon inheritance. Patch by Bar Harel.

@item 
bpo-38615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38615}: @ref{8f0,,IMAP4} and @ref{8f1,,IMAP4_SSL} now
have an optional `timeout' parameter for their constructors. Also, the
@ref{8f2,,open()} method now has an optional `timeout' parameter
with this change. The overridden methods of @ref{8f1,,IMAP4_SSL}
and @ref{8f3,,IMAP4_stream} were applied to this change. Patch by
Donghee Na.

@item 
bpo-35182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35182}: Fixed @code{Popen.communicate()} subsequent call crash when the
child process has already closed any piped standard stream, but still
continues to be running. Patch by Andriy Maletsky.

@item 
bpo-38630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38630}: On Unix, @ref{1395,,subprocess.Popen.send_signal()} now polls the
process status. Polling reduces the risk of sending a signal to the wrong
process if the process completed, the @ref{1936,,subprocess.Popen.returncode}
attribute is still @code{None}, and the pid has been reassigned (recycled) to
a new different process.

@item 
bpo-38536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38536}: Removes trailing space in formatted currency with
@code{international=True} and a locale with symbol following value. E.g.
@code{locale.currency(12.34, international=True)} returned @code{'12,34 EUR '}
instead of @code{'12,34 EUR'}.

@item 
bpo-38473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38473}: Use signature from inner mock for autospecced methods attached
with @code{unittest.mock.attach_mock()}. Patch by Karthikeyan Singaravelan.

@item 
bpo-38361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38361}: Fixed an issue where @code{ident} could include a leading path
separator when @ref{529,,syslog.openlog()} was called without arguments.

@item 
bpo-38293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38293}: Add @ref{51d,,copy.copy()} and @ref{b5c,,copy.deepcopy()} support to
@ref{192,,property()} objects.

@item 
bpo-37958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37958}: Added the pstats.Stats.get_profile_dict() method to return the
profile data as a StatsProfile instance.

@item 
bpo-28367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28367}: Termios magic constants for the following baud rates:   -
B500000   - B576000   - B921600   - B1000000   - B1152000   - B1500000   -
B2000000   - B2500000   - B3000000   - B3500000   - B4000000 Patch by
Andrey Smirnov
@end itemize

@node Documentation<39>,Build<44>,Library<44>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id392}@anchor{1937}
@subsubsection Documentation



@itemize -

@item 
bpo-39381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39381}: Mention in docs that @ref{2bf,,asyncio.get_event_loop()} implicitly
creates new event loop only if called from the main thread.

@item 
bpo-38918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38918}: Add an entry for @code{__module__} in the "function" & "method"
sections of the @ref{7d,,inspect} docs' @ref{1938,,Types et membres} table.

@item 
bpo-3530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3530}: In the @ref{8,,ast} module documentation, fix a misleading
@code{NodeTransformer} example and add advice on when to use the
@code{fix_missing_locations} function.
@end itemize

@node Build<44>,IDLE<30>,Documentation<39>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id393}@anchor{1939}
@subsubsection Build



@itemize -

@item 
bpo-39395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39395}: On non-Windows platforms, the @code{setenv()} and
@code{unsetenv()} functions are now required to build Python.

@item 
bpo-39160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39160}: Updated the documentation in @code{./configure --help} to show
default values, reference documentation where required and add additional
explanation where needed.

@item 
bpo-39144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39144}: The ctags and etags build targets both include Modules/_ctypes
and Python standard library source files.
@end itemize

@node IDLE<30>,C API<43>,Build<44>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id394}@anchor{193a}
@subsubsection IDLE



@itemize -

@item 
bpo-39050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39050}: Make IDLE Settings dialog Help button work again.

@item 
bpo-34118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34118}: Tag memoryview, range, and tuple as classes, the same as list,
etcetera, in the library manual built-in functions list.

@item 
bpo-32989@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32989}: Add tests for editor newline_and_indent_event method. Remove
dead code from pyparse find_good_parse_start method.
@end itemize

@node C API<43>,,IDLE<30>,Python 3 9 0 alpha 3
@anchor{whatsnew/changelog id395}@anchor{193b}
@subsubsection C API



@itemize -

@item 
bpo-39372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39372}: Clean header files of interfaces defined but with no
implementation. The public API symbols being removed are:
@code{_PyBytes_InsertThousandsGroupingLocale},
@code{_PyBytes_InsertThousandsGrouping}, @code{_Py_InitializeFromArgs},
@code{_Py_InitializeFromWideArgs}, @code{_PyFloat_Repr}, @code{_PyFloat_Digits},
@code{_PyFloat_DigitsInit}, @code{PyFrame_ExtendStack},
@code{_PyAIterWrapper_Type}, @code{PyNullImporter_Type}, @code{PyCmpWrapper_Type},
@code{PySortWrapper_Type}, @code{PyNoArgsFunction}.

@item 
bpo-39164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39164}: Add a private @code{_PyErr_GetExcInfo()} function to retrieve
exception information of the specified Python thread state.
@end itemize

@node Python 3 9 0 alpha 2,Python 3 9 0 alpha 1,Python 3 9 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-9-0-alpha-2}@anchor{193c}
@subsection Python 3.9.0 alpha 2


`Release date: 2019-12-18'

@menu
* Security: Security<30>. 
* Core and Builtins: Core and Builtins<46>. 
* Library: Library<45>. 
* Documentation: Documentation<40>. 
* Tests: Tests<42>. 
* Build: Build<45>. 
* Windows: Windows<40>. 
* macOS: macOS<33>. 
* IDLE: IDLE<31>. 
* C API: C API<44>. 

@end menu

@node Security<30>,Core and Builtins<46>,,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id396}@anchor{193d}
@subsubsection Security



@itemize -

@item 
bpo-38945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38945}: Newline characters have been escaped when performing uu
encoding to prevent them from overflowing into to content section of the
encoded file. This prevents malicious or accidental modification of data
during the decoding process.

@item 
bpo-37228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37228}: Due to significant security concerns, the `reuse_address'
parameter of @ref{71d,,asyncio.loop.create_datagram_endpoint()} is no longer
supported. This is because of the behavior of @code{SO_REUSEADDR} in UDP. For
more details, see the documentation for
@code{loop.create_datagram_endpoint()}. (Contributed by Kyle Stanley, Antoine
Pitrou, and Yury Selivanov in bpo-37228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37228}.)

@item 
bpo-38804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38804}: Fixes a ReDoS vulnerability in @ref{6f,,http.cookiejar}. Patch by
Ben Caller.
@end itemize

@node Core and Builtins<46>,Library<45>,Security<30>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id397}@anchor{193e}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-39028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39028}: Slightly improve the speed of keyword argument parsing with
many kwargs by strengthening the assumption that kwargs are interned
strings.

@item 
bpo-39080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39080}: Fix the value of `end_col_offset' for Starred Expression AST
nodes when they are among the elements in the `args' attribute of Call AST
nodes.

@item 
bpo-39031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39031}: When parsing an "elif" node, lineno and col_offset of the node
now point to the "elif" keyword and not to its condition, making it
consistent with the "if" node. Patch by Lysandros Nikolaou.

@item 
bpo-20443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20443}: In Python 3.9.0a1, sys.argv[0] was made an absolute path if a
filename was specified on the command line. Revert this change, since most
users expect sys.argv to be unmodified.

@item 
bpo-39008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39008}: @ref{365,,PySys_Audit()} now requires @code{Py_ssize_t} to be used
for size arguments in the format string, regardless of whether
@code{PY_SSIZE_T_CLEAN} was defined at include time.

@item 
bpo-38673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38673}: In REPL mode, don't switch to PS2 if the line starts with
comment or whitespace. Based on work by Batuhan Taşkaya.

@item 
bpo-38922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38922}: Calling @code{replace} on a code object now raises the
@code{code.__new__} audit event.

@item 
bpo-38920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38920}: Add audit hooks for when @ref{7f5,,sys.excepthook()} and
@ref{1f4,,sys.unraisablehook()} are invoked.

@item 
bpo-38892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38892}: Improve documentation for audit events table and functions.

@item 
bpo-38852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38852}: Set the thread stack size to 8 Mb for debug builds on android
platforms.

@item 
bpo-38858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38858}: Each Python subinterpreter now has its own "small integer
singletons": numbers in [-5; 257] range. It is no longer possible to
change the number of small integers at build time by overriding
@code{NSMALLNEGINTS} and @code{NSMALLPOSINTS} macros: macros should now be
modified manually in @code{pycore_pystate.h} header file.

@item 
bpo-36854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36854}: The garbage collector state becomes per interpreter
(@code{PyInterpreterState.gc}), rather than being global
(@code{_PyRuntimeState.gc}).

@item 
bpo-38835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38835}: The @code{PyFPE_START_PROTECT()} and @code{PyFPE_END_PROTECT()}
macros are empty: they have been doing nothing for the last year, so stop
using them.

@item 
bpo-38328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38328}: Sped up the creation time of constant @ref{5fc,,list} and
@ref{5c3,,set} displays. Patch by Brandt Bucher.

@item 
bpo-38707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38707}: @code{MainThread.native_id} is now correctly reset in child
processes spawned using @ref{b47,,multiprocessing.Process}, instead of
retaining the parent's value.

@item 
bpo-38629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38629}: Added @code{__floor__} and @code{__ceil__} methods to float object.
Patch by Batuhan Taşkaya.

@item 
bpo-27145@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27145}: int + int and int - int operators can now return small integer
singletons. Patch by hongweipeng.

@item 
bpo-38021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38021}: Provide a platform tag for AIX that is sufficient for PEP425
binary distribution identification. Patch by Michael Felt.

@item 
bpo-35409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35409}: Ignore GeneratorExit exceptions when throwing an exception into
the aclose coroutine of an asynchronous generator.

@item 
bpo-33387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33387}: Removed WITH_CLEANUP_START, WITH_CLEANUP_FINISH, BEGIN_FINALLY,
END_FINALLY, CALL_FINALLY and POP_FINALLY bytecodes. Replaced with RERAISE
and WITH_EXCEPT_START bytecodes. The compiler now generates different code
for exceptional and non-exceptional branches for 'with' and 'try-except'
statements. For 'try-finally' statements the 'finally' block is replicated
for each exit from the 'try' body.
@end itemize

@node Library<45>,Documentation<40>,Core and Builtins<46>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id398}@anchor{193f}
@subsubsection Library



@itemize -

@item 
bpo-39033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39033}: Fix @ref{428,,NameError} in @ref{131,,zipimport}. Patch by Karthikeyan
Singaravelan.

@item 
bpo-39022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39022}: Update importlib.metadata to include improvements from
importlib_metadata 1.3 including better serialization of EntryPoints and
improved documentation for custom finders.

@item 
bpo-39006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39006}: Fix asyncio when the ssl module is missing: only check for
ssl.SSLSocket instance if the ssl module is available.

@item 
bpo-38708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38708}: Fix a potential IndexError in email parser when parsing an
empty msg-id.

@item 
bpo-38698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38698}: Add a new @code{InvalidMessageID} token to email parser to
represent invalid Message-ID headers.  Also, add defects when there is
remaining value after parsing the header.

@item 
bpo-38994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38994}: Implement @code{__class_getitem__} for @code{os.PathLike},
@code{pathlib.Path}.

@item 
bpo-38979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38979}: Return class from @code{ContextVar.__class_getitem__} to simplify
subclassing.

@item 
bpo-38978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38978}: Implement @code{__class_getitem__} on asyncio objects (Future,
Task, Queue). Patch by Batuhan Taskaya.

@item 
bpo-38916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38916}: @ref{19e,,array.array}: Remove @code{tostring()} and
@code{fromstring()} methods. They were aliases to @code{tobytes()} and
@code{frombytes()}, deprecated since Python 3.2.

@item 
bpo-38986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38986}: Make repr of C accelerated TaskWakeupMethWrapper the same as of
pure Python version.

@item 
bpo-38982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38982}: Fix asyncio @code{PidfdChildWatcher}: handle @code{waitpid()} error.
If @code{waitpid()} is called elsewhere, @code{waitpid()} call fails with
@ref{1041,,ChildProcessError}: use return code 255 in this case, and log a
warning. It ensures that the pidfd file descriptor is closed if this error
occurs.

@item 
bpo-38529@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38529}: Drop too noisy asyncio warning about deletion of a stream
without explicit @code{.close()} call.

@item 
bpo-27413@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27413}: Added ability to pass through @code{ensure_ascii} options to
json.dumps in the @code{json.tool} command-line interface.

@item 
bpo-38634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38634}: The @ref{b9,,readline} module now detects if Python is linked to
libedit at runtime on all platforms.  Previously, the check was only done
on macOS.

@item 
bpo-33684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33684}: Fix @code{json.tool} failed to read a JSON file with non-ASCII
characters when locale encoding is not UTF-8.

@item 
bpo-38698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38698}: Prevent UnboundLocalError to pop up in parse_message_id.

parse_message_id() was improperly using a token defined inside an
exception handler, which was raising @code{UnboundLocalError} on parsing an
invalid value. Patch by Claudiu Popa.

@item 
bpo-38927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38927}: Use @code{python -m pip} instead of @code{pip} to upgrade
dependencies in venv.

@item 
bpo-26730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26730}: Fix @code{SpooledTemporaryFile.rollover()} might corrupt the file
when it is in text mode. Patch by Serhiy Storchaka.

@item 
bpo-38881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38881}: random.choices() now raises a ValueError when all the weights
are zero.

@item 
bpo-38876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38876}: Raise pickle.UnpicklingError when loading an item from memo for
invalid input.

The previous code was raising a @code{KeyError} for both the Python and C
implementation. This was caused by the specified index of an invalid input
which did not exist in the memo structure, where the pickle stores what
objects it has seen. The malformed input would have caused either a
@code{BINGET} or @code{LONG_BINGET} load from the memo, leading to a
@code{KeyError} as the determined index was bogus. Patch by Claudiu Popa.

@item 
bpo-38688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38688}: Calling func:@code{shutil.copytree} to copy a directory tree from
one directory to another subdirectory resulted in an endless loop and a
RecursionError. A fix was added to consume an iterator and create the list
of the entries to be copied, avoiding the recursion for newly created
directories. Patch by Bruno P. Kinoshita.

@item 
bpo-38863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38863}: Improve @code{is_cgi()} function in @ref{71,,http.server}, which
enables processing the case that cgi directory is a child of another
directory other than root.

@item 
bpo-37838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37838}: @ref{69c,,typing.get_type_hints()} properly handles functions
decorated with @ref{f48,,functools.wraps()}.

@item 
bpo-38870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38870}: Expose @ref{8d2,,ast.unparse()} as a function of the @ref{8,,ast}
module that can be used to unparse an @ref{1a4,,ast.AST} object and produce
a string with code that would produce an equivalent @ref{1a4,,ast.AST}
object when parsed. Patch by Pablo Galindo and Batuhan Taskaya.

@item 
bpo-38859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38859}: AsyncMock now returns StopAsyncIteration on the exhaustion of a
side_effects iterable. Since PEP-479 its Impossible to raise a
StopIteration exception from a coroutine.

@item 
bpo-38857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38857}: AsyncMock fix for return values that are awaitable types.  This
also covers side_effect iterable values that happened to be awaitable, and
wraps callables that return an awaitable type. Before these awaitables
were being awaited instead of being returned as is.

@item 
bpo-38834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38834}: @ref{161,,typing.TypedDict} subclasses now track which keys are
optional using the @code{__required_keys__} and @code{__optional_keys__}
attributes, to enable runtime validation by downstream projects.  Patch by
Zac Hatfield-Dodds.

@item 
bpo-38821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38821}: Fix unhandled exceptions in @ref{6,,argparse} when
internationalizing error messages for arguments with @code{nargs} set to
special (non-integer) values. Patch by Federico Bond.

@item 
bpo-38820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38820}: Make Python compatible with OpenSSL 3.0.0.
@ref{fa2,,ssl.SSLSocket.getpeercert()} no longer returns IPv6 addresses with a
trailing new line.

@item 
bpo-38811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38811}: Fix an unhandled exception in @ref{a3,,pathlib} when
@ref{10d0,,os.link()} is missing. Patch by Toke Høiland-Jørgensen.

@item 
bpo-38686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38686}: Added support for multiple @code{qop} values in
@ref{1910,,urllib.request.AbstractDigestAuthHandler}.

@item 
bpo-38712@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38712}: Add the Linux-specific @ref{918,,signal.pidfd_send_signal()}
function, which allows sending a signal to a process identified by a file
descriptor rather than a pid.

@item 
bpo-38348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38348}: Add @code{-i} and @code{--indent} (indentation level), and
@code{--no-type-comments} (type comments) command line options to ast parsing
tool.

@item 
bpo-37523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37523}: Change @code{zipfile.ZipExtFile} to raise @code{ValueError} when
trying to access the underlying file object after it has been closed. This
new behavior is consistent with how accessing closed files is handled in
other parts of Python.

@item 
bpo-38045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38045}: Improve the performance of @code{enum._decompose()} in
@ref{55,,enum}. Patch by hongweipeng.

@item 
bpo-36820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36820}: Break cycle generated when saving an exception in socket.py,
codeop.py and dyld.py as they keep alive not only the exception but user
objects through the @code{__traceback__} attribute. Patch by Mario Corchero.

@item 
bpo-36406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36406}: Handle namespace packages in @ref{3a,,doctest}. Patch by
Karthikeyan Singaravelan.

@item 
bpo-34776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34776}: Fix dataclasses to support forward references in type
annotations

@item 
bpo-20928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20928}: ElementTree supports recursive XInclude processing.  Patch by
Stefan Behnel.

@item 
bpo-29636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29636}: Add whitespace options for formatting JSON with the
@code{json.tool} CLI. The following mutually exclusive options are now
supported: @code{--indent} for setting the indent level in spaces; @code{--tab}
for indenting with tabs; @code{--no-indent} for suppressing newlines; and
@code{--compact} for suppressing all whitespace. The default behavior remains
the same as @code{--indent=4}.
@end itemize

@node Documentation<40>,Tests<42>,Library<45>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id399}@anchor{1940}
@subsubsection Documentation



@itemize -

@item 
bpo-38928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38928}: Correct when venv's @code{upgrade_dependencies()} and
@code{--upgrade-deps} are added.

@item 
bpo-38899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38899}: Update documentation to state that to activate virtual
environments under fish one should use @code{source}, not @code{.} as documented
at @indicateurl{https://fishshell.com/docs/current/cmds/source.html}.

@item 
bpo-22377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22377}: Improves documentation of the values that
@ref{1593,,datetime.datetime.strptime()} accepts for @code{%Z}. Patch by Karl
Dubost.
@end itemize

@node Tests<42>,Build<45>,Documentation<40>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id400}@anchor{1941}
@subsubsection Tests



@itemize -

@item 
bpo-38546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38546}: Fix test_ressources_gced_in_workers() of
test_concurrent_futures: explicitly stop the manager to prevent leaking a
child process running in the background after the test completes.

@item 
bpo-38546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38546}: Multiprocessing and concurrent.futures tests now stop the
resource tracker process when tests complete.

@item 
bpo-38614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38614}: Replace hardcoded timeout constants in tests with new
@ref{e3,,test.support} constants: @ref{1942,,LOOPBACK_TIMEOUT},
@ref{1943,,INTERNET_TIMEOUT},
@ref{183c,,SHORT_TIMEOUT} and
@ref{1944,,LONG_TIMEOUT}. It becomes easier to adjust these four
timeout constants for all tests at once, rather than having to adjust
every single test file.

@item 
bpo-38547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38547}: Fix test_pty: if the process is the session leader, closing the
master file descriptor raises a SIGHUP signal: simply ignore SIGHUP when
running the tests.

@item 
bpo-38992@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38992}: Fix a test for @ref{138b,,math.fsum()} that was failing due to
constant folding.

@item 
bpo-38991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38991}: @ref{e3,,test.support}:
@code{run_python_until_end()},
@code{assert_python_ok()} and
@code{assert_python_failure()} functions no longer strip
whitespaces from stderr. Remove @code{test.support.strip_python_stderr()}
function.

@item 
bpo-38965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38965}: Fix test_faulthandler on GCC 10. Use the "volatile" keyword in
@code{faulthandler._stack_overflow()} to prevent tail call optimization on
any compiler, rather than relying on compiler specific pragma.

@item 
bpo-38875@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38875}: test_capi: trashcan tests now require the test "cpu" resource.

@item 
bpo-38841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38841}: Skip asyncio test_create_datagram_endpoint_existing_sock_unix
on platforms lacking a functional bind() for named unix domain sockets.

@item 
bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}: Skip the test_posix.test_pidfd_open() test if
@code{os.pidfd_open()} fails with a @ref{d30,,PermissionError}. This situation
can happen in a Linux sandbox using a syscall whitelist which doesn't
allow the @code{pidfd_open()} syscall yet.

@item 
bpo-38839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38839}: Fix some unused functions in tests. Patch by Adam Johnson.

@item 
bpo-38669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38669}: Raise @ref{522,,TypeError} when passing target as a string with
@ref{151e,,unittest.mock.patch.object()}.

@item 
bpo-37957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37957}: test.regrtest now can receive a list of test patterns to ignore
(using the -i/--ignore argument) or a file with a list of patterns to
ignore (using the --ignore-file argument). Patch by Pablo Galindo.
@end itemize

@node Build<45>,Windows<40>,Tests<42>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id401}@anchor{1945}
@subsubsection Build



@itemize -

@item 
bpo-37404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37404}: @ref{a,,asyncio} now raises @ref{522,,TypeError} when calling
incompatible methods with an @ref{8d7,,ssl.SSLSocket} socket.  Patch by Ido
Michael.

@item 
bpo-36500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36500}: Added an optional "regen" project to the Visual Studio solution
that will regenerate all grammar, tokens, and opcodes.
@end itemize

@node Windows<40>,macOS<33>,Build<45>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id402}@anchor{1946}
@subsubsection Windows



@itemize -

@item 
bpo-39007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=39007}: Add auditing events to functions in @ref{115,,winreg}.

@item 
bpo-33125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33125}: Add support for building and releasing Windows ARM64 packages.
@end itemize

@node macOS<33>,IDLE<31>,Windows<40>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id403}@anchor{1947}
@subsubsection macOS



@itemize -

@item 
bpo-37931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37931}: Fixed a crash on OSX dynamic builds that occurred when
re-initializing the posix module after a Py_Finalize if the environment
had changed since the previous @code{import posix}. Patch by Benoît Hudson.
@end itemize

@node IDLE<31>,C API<44>,macOS<33>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id404}@anchor{1948}
@subsubsection IDLE



@itemize -

@item 
bpo-38944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38944}: Escape key now closes IDLE completion windows.  Patch by Johnny
Najera.

@item 
bpo-38943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38943}: Fix IDLE autocomplete windows not always appearing on some
systems. Patch by Johnny Najera.

@item 
bpo-38862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38862}: 'Strip Trailing Whitespace' on the Format menu removes extra
newlines at the end of non-shell files.

@item 
bpo-38636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38636}: Fix IDLE Format menu tab toggle and file indent width. These
functions (default shortcuts Alt-T and Alt-U) were mistakenly disabled in
3.7.5 and 3.8.0.
@end itemize

@node C API<44>,,IDLE<31>,Python 3 9 0 alpha 2
@anchor{whatsnew/changelog id405}@anchor{1949}
@subsubsection C API



@itemize -

@item 
bpo-38896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38896}: Remove @code{PyUnicode_ClearFreeList()} function: the Unicode free
list has been removed in Python 3.3.

@item 
bpo-37340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37340}: Remove @code{PyMethod_ClearFreeList()} and
@code{PyCFunction_ClearFreeList()} functions: the free lists of bound method
objects have been removed.

@item 
bpo-38835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38835}: Exclude @code{PyFPE_START_PROTECT()} and @code{PyFPE_END_PROTECT()}
macros of @code{pyfpe.h} from @code{Py_LIMITED_API} (stable API).
@end itemize

@node Python 3 9 0 alpha 1,Python 3 8 0 beta 1,Python 3 9 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-9-0-alpha-1}@anchor{194a}
@subsection Python 3.9.0 alpha 1


`Release date: 2019-11-19'

@menu
* Security: Security<31>. 
* Core and Builtins: Core and Builtins<47>. 
* Library: Library<46>. 
* Documentation: Documentation<41>. 
* Tests: Tests<43>. 
* Build: Build<46>. 
* Windows: Windows<41>. 
* macOS: macOS<34>. 
* IDLE: IDLE<32>. 
* Tools/Demos: Tools/Demos<21>. 
* C API: C API<45>. 

@end menu

@node Security<31>,Core and Builtins<47>,,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id406}@anchor{194b}
@subsubsection Security



@itemize -

@item 
bpo-38722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38722}: @ref{bd,,runpy} now uses @ref{16b2,,io.open_code()} to open code files.
Patch by Jason Killen.

@item 
bpo-38622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38622}: Add additional audit events for the @ref{2a,,ctypes} module.

@item 
bpo-38418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38418}: Fixes audit event for @ref{1411,,os.system()} to be named
@code{os.system}.

@item 
bpo-38243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38243}: Escape the server title of
@ref{194c,,xmlrpc.server.DocXMLRPCServer} when rendering the document page as
HTML. (Contributed by Donghee Na in bpo-38243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38243}.)

@item 
bpo-38174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38174}: Update vendorized expat library version to 2.2.8, which
resolves 
@geindex Common Vulnerabilities and Exposures; CVE 2019-15903
CVE 2019-15903@footnote{https://www.cve.org/CVERecord?id=CVE-2019-15903}.

@item 
bpo-37764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37764}: Fixes email._header_value_parser.get_unstructured going into an
infinite loop for a specific case in which the email header does not have
trailing whitespace, and the case in which it contains an invalid encoded
word. Patch by Ashwin Ramaswami.

@item 
bpo-37461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37461}: Fix an infinite loop when parsing specially crafted email
headers. Patch by Abhilash Raj.

@item 
bpo-37363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37363}: Adds audit events for the range of supported run commands (see
@ref{194d,,Ligne de commande et environnement}).

@item 
bpo-37463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37463}: ssl.match_hostname() no longer accepts IPv4 addresses with
additional text after the address and only quad-dotted notation without
trailing whitespaces. Some inet_aton() implementations ignore whitespace
and all data after whitespace, e.g. '127.0.0.1 whatever'.

@item 
bpo-37363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37363}: Adds audit events for @ref{54,,ensurepip}, @ref{5d,,ftplib},
@ref{63,,glob}, @ref{73,,imaplib}, @code{nntplib}, @ref{a4,,pdb}, @ref{ab,,poplib},
@ref{c4,,shutil}, @ref{c9,,smtplib}, @ref{ce,,sqlite3}, @ref{d5,,subprocess},
@code{telnetlib}, @ref{df,,tempfile} and @ref{114,,webbrowser}, as well as
@ref{10da,,os.listdir()}, @ref{a4d,,os.scandir()} and @ref{231,,breakpoint()}.

@item 
bpo-37364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37364}: @ref{16b2,,io.open_code()} is now used when reading @code{.pth}
files.

@item 
bpo-34631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34631}: Updated OpenSSL to 1.1.1c in Windows installer

@item 
bpo-34155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34155}: Fix parsing of invalid email addresses with more than one @code{@@}
(e.g. a@@b@@c.com.) to not return the part before 2nd @code{@@} as valid email
address. Patch by maxking & jpic.
@end itemize

@node Core and Builtins<47>,Library<46>,Security<31>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id407}@anchor{194e}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-38631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38631}: Replace @code{Py_FatalError()} call with a regular
@ref{193,,RuntimeError} exception in @code{float.__getformat__()}.

@item 
bpo-38639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38639}: Optimized @ref{1378,,math.floor()}, @ref{1379,,math.ceil()} and
@ref{137a,,math.trunc()} for floats.

@item 
bpo-38640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38640}: Fixed a bug in the compiler that was causing to raise in the
presence of break statements and continue statements inside always false
while loops. Patch by Pablo Galindo.

@item 
bpo-38613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38613}: Optimized some set operations (e.g. @code{|}, @code{^}, and @code{-}) of
@code{dict_keys}. @code{d.keys() | other} was slower than @code{set(d) | other} but
they are almost same performance for now.

@item 
bpo-28029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28029}: @code{"".replace("", s, n)} now returns @code{s} instead of an empty
string for all non-zero @code{n}.  There are similar changes for
@ref{1bd,,bytes} and @ref{528,,bytearray} objects.

@item 
bpo-38535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38535}: Fixed line numbers and column offsets for AST nodes for calls
without arguments in decorators.

@item 
bpo-38525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38525}: Fix a segmentation fault when using reverse iterators of empty
@code{dict} objects. Patch by Donghee Na and Inada Naoki.

@item 
bpo-38465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38465}: @ref{528,,bytearray}, @ref{19e,,array} and
@ref{208,,mmap} objects allow now to export more than @code{2**31}
buffers at a time.

@item 
bpo-38469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38469}: Fixed a bug where the scope of named expressions was not being
resolved correctly in the presence of the `global' keyword. Patch by Pablo
Galindo.

@item 
bpo-38437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38437}: Activate the @code{GC_DEBUG} macro for debug builds of the
interpreter (when @code{Py_DEBUG} is set). Patch by Pablo Galindo.

@item 
bpo-38379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38379}: When the garbage collector makes a collection in which some
objects resurrect (they are reachable from outside the isolated cycles
after the finalizers have been executed), do not block the collection of
all objects that are still unreachable. Patch by Pablo Galindo and Tim
Peters.

@item 
bpo-38379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38379}: When cyclic garbage collection (gc) runs finalizers that
resurrect unreachable objects, the current gc run ends, without collecting
any cyclic trash.  However, the statistics reported by @code{collect()} and
@code{get_stats()} claimed that all cyclic trash found was collected, and
that the resurrected objects were collected.   Changed the stats to report
that none were collected.

@item 
bpo-38392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38392}: In debug mode, @ref{14bc,,PyObject_GC_Track()} now calls
@code{tp_traverse()} of the object type to ensure that the object is valid:
test that objects visited by @code{tp_traverse()} are valid.

@item 
bpo-38210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38210}: Remove unnecessary intersection and update set operation in
dictview with empty set. (Contributed by Donghee Na in bpo-38210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38210}.)

@item 
bpo-38402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38402}: Check the error from the system's underlying @code{crypt} or
@code{crypt_r}.

@item 
bpo-37474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37474}: On FreeBSD, Python no longer calls @code{fedisableexcept()} at
startup to control the floating-point control mode. The call became
useless since FreeBSD 6: it became the default mode.

@item 
bpo-38006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38006}: Fix a bug due to the interaction of weakrefs and the cyclic
garbage collector. We must clear any weakrefs in garbage in order to
prevent their callbacks from executing and causing a crash.

@item 
bpo-38317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38317}: Fix warnings options priority: @code{PyConfig.warnoptions} has the
highest priority, as stated in the 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/}.

@item 
bpo-38310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38310}: Predict @code{BUILD_MAP_UNPACK_WITH_CALL} -> @code{CALL_FUNCTION_EX}
opcode pairs in the main interpreter loop. Patch by Brandt Bucher.

@item 
bpo-36871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36871}: Improve error handling for the assert_has_calls and
assert_has_awaits methods of mocks. Fixed a bug where any errors
encountered while binding the expected calls to the mock's spec were
silently swallowed, leading to misleading error output.

@item 
bpo-11410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11410}: Better control over symbol visibility is provided through use
of the visibility attributes available in gcc >= 4.0, provided in a
uniform way across POSIX and Windows. The POSIX build files have been
updated to compile with -fvisibility=hidden, minimising exported symbols.

@item 
bpo-38219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38219}: Optimized the @ref{253,,dict} constructor and the
@ref{1419,,update()} method for the case when the argument is a dict.

@item 
bpo-38236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38236}: Python now dumps path configuration if it fails to import the
Python codecs of the filesystem and stdio encodings.

@item 
bpo-38013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38013}: Allow to call @code{async_generator_athrow().throw(...)} even for
non-started async generator helper. It fixes annoying warning at the end
of @ref{466,,asyncio.run()} call.

@item 
bpo-38124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38124}: Fix an off-by-one error in PyState_AddModule that could cause
out-of-bounds memory access.

@item 
bpo-38116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38116}: The select module is now PEP-384 compliant and no longer has
static state

@item 
bpo-38113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38113}: ast module updated to PEP-384 and all statics removed

@item 
bpo-38076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38076}: The struct module is now PEP-384 compatible

@item 
bpo-38075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38075}: The random module is now PEP-384 compatible

@item 
bpo-38074@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38074}: zlib module made PEP-384 compatible

@item 
bpo-38073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38073}: Make pwd extension module PEP-384 compatible

@item 
bpo-38072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38072}: grp module made PEP-384 compatible

@item 
bpo-38069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38069}: Make _posixsubprocess PEP-384 compatible

@item 
bpo-38071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38071}: Make termios extension module PEP-384 compatible

@item 
bpo-38005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38005}: Fixed comparing and creating of InterpreterID and ChannelID.

@item 
bpo-36946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36946}: Fix possible signed integer overflow when handling slices.
Patch by hongweipeng.

@item 
bpo-37994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37994}: Fixed silencing arbitrary errors if an attribute lookup fails
in several sites. Only AttributeError should be silenced.

@item 
bpo-8425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8425}: Optimize set difference_update for the case when the other set
is much larger than the base set.  (Suggested by Evgeny Kapun with code
contributed by Michele Orrù).

@item 
bpo-37966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37966}: The implementation of @ref{a37,,is_normalized()} has
been greatly sped up on strings that aren't normalized, by implementing
the full normalization-quick-check algorithm from the Unicode standard.

@item 
bpo-37947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37947}: Adjust correctly the recursion level in the symtable generation
for named expressions. Patch by Pablo Galindo.

@item 
bpo-37812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37812}: The @code{CHECK_SMALL_INT} macro used inside
@code{Object/longobject.c} has been replaced with an explicit @code{return}
at each call site.

@item 
bpo-37751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37751}: Fix @ref{950,,codecs.lookup()} to normalize the encoding name the
same way than @code{encodings.normalize_encoding()}, except that
@ref{950,,codecs.lookup()} also converts the name to lower case.

@item 
bpo-37830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37830}: Fixed compilation of @ref{a97,,break} and @ref{9b7,,continue}
in the @ref{9b8,,finally} block when the corresponding @ref{6d3,,try}
block contains @ref{9bc,,return} with a non-constant value.

@item 
bpo-20490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20490}: Improve import error message for partially initialized module
on circular @code{from} imports - by Anthony Sottile.

@item 
bpo-37840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37840}: Fix handling of negative indices in
@ref{18ba,,sq_item} of @ref{528,,bytearray}. Patch by
Sergey Fedoseev.

@item 
bpo-37802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37802}: Slightly improve performance of
@ref{194f,,PyLong_FromUnsignedLong()}, @ref{1950,,PyLong_FromUnsignedLongLong()}
and @ref{1951,,PyLong_FromSize_t()}. Patch by Sergey Fedoseev.

@item 
bpo-37409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37409}: Ensure explicit relative imports from interactive sessions and
scripts (having no parent package) always raise ImportError, rather than
treating the current module as the package. Patch by Ben Lewis.

@item 
bpo-32912@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32912}: Reverted bpo-32912@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32912}: emitting @ref{44f,,SyntaxWarning} instead
of @ref{1a3,,DeprecationWarning} for invalid escape sequences in string and
bytes literals.

@item 
bpo-37757@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37757}: 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}: As described in the PEP, assignment expressions now
raise @ref{18b,,SyntaxError} when their interaction with comprehension scoping
results in an ambiguous target scope.

The @code{TargetScopeError} subclass originally proposed by the PEP has been
removed in favour of just raising regular syntax errors for the disallowed
cases.

@item 
bpo-36279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36279}: Fix potential use of uninitialized memory in @ref{d83,,os.wait3()}.

@item 
bpo-36311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36311}: Decoding bytes objects larger than 2GiB is faster and no longer
fails when a multibyte characters spans a chunk boundary.

@item 
bpo-34880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34880}: The @ref{955,,assert} statement now works properly if the
@ref{694,,AssertionError} exception is being shadowed. Patch by Zackery Spytz.

@item 
bpo-37340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37340}: Removed object cache (@code{free_list}) for bound method objects.
Temporary bound method objects are less used than before thanks to the
@code{LOAD_METHOD} opcode and the @code{_PyObject_VectorcallMethod} C API.

@item 
bpo-37648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37648}: Fixed minor inconsistency in @code{list.__contains__()},
@code{tuple.__contains__()} and a few other places. The collection's item
is now always at the left and the needle is on the right of @code{==}.

@item 
bpo-37444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37444}: Update differing exception between @code{builtins.__import__()}
and @ref{1056,,importlib.__import__()}.

@item 
bpo-37619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37619}: When adding a wrapper descriptor from one class to a different
class (for example, setting @code{__add__ = str.__add__} on an @code{int}
subclass), an exception is correctly raised when the operator is called.

@item 
bpo-37593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37593}: Swap the positions of the `posonlyargs' and `args' parameters
in the constructor of @code{ast.parameters} nodes.

@item 
bpo-37543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37543}: Optimized pymalloc for non PGO build.

@item 
bpo-37537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37537}: Compute allocated pymalloc blocks inside
_Py_GetAllocatedBlocks().  This slows down _Py_GetAllocatedBlocks() but
gives a small speedup to _PyObject_Malloc() and _PyObject_Free().

@item 
bpo-37467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37467}: Fix @ref{7f5,,sys.excepthook()} and @code{PyErr_Display()} if a
filename is a bytes string. For example, for a SyntaxError exception where
the filename attribute is a bytes string.

@item 
bpo-37433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37433}: Fix @code{SyntaxError} indicator printing too many spaces for
multi-line strings - by Anthony Sottile.

@item 
bpo-37417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37417}: @code{bytearray.extend()} now correctly handles errors that
arise during iteration. Patch by Brandt Bucher.

@item 
bpo-37414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37414}: The undocumented @code{sys.callstats()} function has been removed.
Since Python 3.7, it was deprecated and always returned @code{None}. It
required a special build option @code{CALL_PROFILE} which was already removed
in Python 3.7.

@item 
bpo-37392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37392}: Remove @code{sys.getcheckinterval()} and
@code{sys.setcheckinterval()} functions. They were deprecated since Python
3.2. Use @ref{936,,sys.getswitchinterval()} and @ref{937,,sys.setswitchinterval()}
instead. Remove also @code{check_interval} field of the
@code{PyInterpreterState} structure.

@item 
bpo-37388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37388}: In development mode and in debug build, `encoding' and `errors'
arguments are now checked on string encoding and decoding operations.
Examples: @ref{505,,open()}, @ref{8c2,,str.encode()} and @ref{8c3,,bytes.decode()}.

By default, for best performances, the `errors' argument is only checked
at the first encoding/decoding error, and the `encoding' argument is
sometimes ignored for empty strings.

@item 
bpo-37348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37348}: Optimized decoding short ASCII string with UTF-8 and ascii
codecs. @code{b"foo".decode()} is about 15% faster.  Patch by Inada Naoki.

@item 
bpo-24214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24214}: Improved support of the surrogatepass error handler in the
UTF-8 and UTF-16 incremental decoders.

@item 
bpo-37330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37330}: @ref{505,,open()}, @ref{506,,io.open()}, @ref{72a,,codecs.open()} and
@ref{721,,fileinput.FileInput} no longer accept @code{'U'} ("universal
newline") in the file mode. This flag was deprecated since Python 3.3.

@item 
bpo-35224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35224}: Reverse evaluation order of key: value in dict comprehensions
as proposed in PEP 572. I.e. in @code{@{k: v for ...@}}, @code{k} will be
evaluated before @code{v}.

@item 
bpo-37316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37316}: Fix the @ref{365,,PySys_Audit()} call in @ref{208,,mmap.mmap}.

@item 
bpo-37300@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37300}: Remove an unnecessary Py_XINCREF in classobject.c.

@item 
bpo-37269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37269}: Fix a bug in the peephole optimizer that was not treating
correctly constant conditions with binary operators. Patch by Pablo
Galindo.

@item 
bpo-20443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20443}: Python now gets the absolute path of the script filename
specified on the command line (ex: "python3 script.py"): the __file__
attribute of the __main__ module and sys.path[0] become an absolute path,
rather than a relative path.

@item 
bpo-37257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37257}: Python's small object allocator (@code{obmalloc.c}) now allows (no
more than) one empty arena to remain available for immediate reuse,
without returning it to the OS.  This prevents thrashing in simple loops
where an arena could be created and destroyed anew on each iteration.

@item 
bpo-37231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37231}: The dispatching of type slots to special methods (for example
calling @code{__mul__} when doing @code{x * y}) has been made faster.

@item 
bpo-36974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36974}: Implemented separate vectorcall functions for every calling
convention of builtin functions and methods. This improves performance for
calls.

@item 
bpo-37213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37213}: Handle correctly negative line offsets in the peephole
optimizer. Patch by Pablo Galindo.

@item 
bpo-37219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37219}: Remove erroneous optimization for empty set differences.

@item 
bpo-15913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15913}: Implement @ref{744,,PyBuffer_SizeFromFormat()} function
(previously documented but not implemented): call @ref{1952,,struct.calcsize()}.
Patch by Joannah Nanjekye.

@item 
bpo-36922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36922}: Slot functions optimize any callable with
@code{Py_TPFLAGS_METHOD_DESCRIPTOR} instead of only instances of
@code{function}.

@item 
bpo-36974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36974}: The slot @code{tp_vectorcall_offset} is inherited unconditionally
to support @code{super().__call__()} when the base class uses vectorcall.

@item 
bpo-37160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37160}: @ref{a2c,,threading.get_native_id()} now also supports NetBSD.

@item 
bpo-37077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37077}: Add @ref{a2c,,threading.get_native_id()} support for AIX. Patch by
M. Felt

@item 
bpo-36781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36781}: @ref{454,,sum()} has been optimized for boolean values.

@item 
bpo-34556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34556}: Add @code{--upgrade-deps} to venv module. Patch by Cooper Ry Lees

@item 
bpo-20523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20523}: @code{pdb.Pdb} supports ~/.pdbrc in Windows 7. Patch by Tim Hopper
and Dan Lidral-Porter.

@item 
bpo-35551@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35551}: Updated encodings: - Removed the "tis260" encoding, which was
an alias for the nonexistent "tactis" codec. - Added "mac_centeuro" as an
alias for the mac_latin2 encoding.

@item 
bpo-19072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19072}: The @ref{165,,classmethod} decorator can now wrap other
descriptors such as property objects.  Adapted from a patch written by
Graham Dumpleton.

@item 
bpo-27575@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27575}: Improve speed of dictview intersection by directly using set
intersection logic. Patch by David Su.

@item 
bpo-30773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30773}: Prohibit parallel running of aclose() / asend() / athrow(). Fix
ag_running to reflect the actual running status of the AG.
@end itemize

@node Library<46>,Documentation<41>,Core and Builtins<47>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id408}@anchor{1953}
@subsubsection Library



@itemize -

@item 
bpo-36589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36589}: The @ref{dd9,,curses.update_lines_cols()} function now returns
@code{None} instead of @code{1} on success.

@item 
bpo-38807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38807}: Update @ref{522,,TypeError} messages for @ref{15bc,,os.path.join()} to
include @ref{c3f,,os.PathLike} objects as acceptable input types.

@item 
bpo-38724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38724}: Add a repr for @code{subprocess.Popen} objects. Patch by Andrey
Doroschenko.

@item 
bpo-38786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38786}: pydoc now recognizes and parses HTTPS URLs. Patch by python273.

@item 
bpo-38785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38785}: Prevent asyncio from crashing if parent @code{__init__} is not
called from a constructor of object derived from @code{asyncio.Future}.

@item 
bpo-38723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38723}: @ref{a4,,pdb} now uses @ref{16b2,,io.open_code()} to trigger auditing
events.

@item 
bpo-27805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27805}: Allow opening pipes and other non-seekable files in append mode
with @ref{505,,open()}.

@item 
bpo-38438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38438}: Simplify the @ref{6,,argparse} usage message for @code{nargs="*"}.

@item 
bpo-38761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38761}: WeakSet is now registered as a collections.abc.MutableSet.

@item 
bpo-38716@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38716}: logging: change RotatingHandler namer and rotator to
class-level attributes. This stops __init__ from setting them to None in
the case where a subclass defines them with eponymous methods.

@item 
bpo-38713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38713}: Add @ref{907,,os.P_PIDFD} constant, which may be passed to
@ref{d86,,os.waitid()} to wait on a Linux process file descriptor.

@item 
bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}: Add @ref{463,,asyncio.PidfdChildWatcher}, a Linux-specific child
watcher implementation that polls process file descriptors.

@item 
bpo-38692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38692}: Expose the Linux @code{pidfd_open} syscall as
@ref{464,,os.pidfd_open()}.

@item 
bpo-38602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38602}: Added constants @code{F_OFD_GETLK},
@code{F_OFD_SETLK} and @code{F_OFD_SETLKW} to the
@ref{58,,fcntl} module. Patch by Donghee Na.

@item 
bpo-38334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38334}: Fixed seeking backward on an encrypted
@code{zipfile.ZipExtFile}.

@item 
bpo-38312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38312}: Add @ref{8dd,,curses.get_escdelay()}, @ref{8de,,curses.set_escdelay()},
@ref{8df,,curses.get_tabsize()}, and @ref{8e0,,curses.set_tabsize()} functions - by
Anthony Sottile.

@item 
bpo-38586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38586}: Now @ref{b3f,,fileConfig()} correctly sets the .name
of handlers loaded.

@item 
bpo-38565@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38565}: Add new cache_parameters() method for functools.lru_cache() to
better support pickling.

@item 
bpo-34679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34679}: asynci.ProactorEventLoop.close() now only calls
signal.set_wakeup_fd() in the main thread.

@item 
bpo-31202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31202}: The case the result of @code{pathlib.WindowsPath.glob()} matches
now the case of the pattern for literal parts.

@item 
bpo-36321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36321}: Remove misspelled attribute.  The 3.8 changelog noted that this
would be removed in 3.9.

@item 
bpo-38521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38521}: Fixed erroneous equality comparison in statistics.NormalDist().

@item 
bpo-38493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38493}: Added @ref{905,,CLD_KILLED} and @ref{906,,CLD_STOPPED} for
@code{si_code}. Patch by Donghee Na.

@item 
bpo-38478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38478}: Fixed a bug in @code{inspect.signature.bind()} that was causing
it to fail when handling a keyword argument with same name as
positional-only parameter. Patch by Pablo Galindo.

@item 
bpo-33604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33604}: Fixed @code{hmac.new} and @code{hmac.HMAC} to raise TypeError instead
of ValueError when the digestmod parameter, now required in 3.8, is
omitted. Also clarified the hmac module documentation and docstrings.

@item 
bpo-38378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38378}: Parameters `out' and `in' of @ref{afd,,os.sendfile()} was renamed to
`out_fd' and `in_fd'.

@item 
bpo-38417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38417}: Added support for setting the umask in the child process to the
subprocess module on POSIX systems.

@item 
bpo-38449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38449}: Revert PR 15522, which introduces a regression in
@ref{205,,mimetypes.guess_type()} due to improper handling of filenames as
urls.

@item 
bpo-38431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38431}: Fix @code{__repr__} method for @code{dataclasses.InitVar} to
support typing objects, patch by Samuel Colvin.

@item 
bpo-38109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38109}: Add missing @ref{fa5,,stat.S_IFDOOR}, @ref{fa6,,stat.S_IFPORT},
@ref{fa7,,stat.S_IFWHT}, @ref{1954,,stat.S_ISDOOR()}, @ref{1955,,stat.S_ISPORT()}, and
@ref{1956,,stat.S_ISWHT()} values to the Python implementation of @ref{d0,,stat}.

@item 
bpo-38422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38422}: Clarify docstrings of pathlib suffix(es)

@item 
bpo-38405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38405}: Nested subclasses of @ref{2ad,,typing.NamedTuple} are now
pickleable.

@item 
bpo-38332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38332}: Prevent @ref{33a,,KeyError} thrown by
@code{_encoded_words.decode()} when given an encoded-word with invalid
content-type encoding from propagating all the way to
@code{email.message.get()}.

@item 
bpo-38371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38371}: Deprecated the @code{split()} method in
@code{_tkinter.TkappType} in favour of the @code{splitlist()} method which
has more consistent and predictable behavior.

@item 
bpo-38341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38341}: Add @ref{1957,,smtplib.SMTPNotSupportedError} to the @ref{c9,,smtplib}
exported names.

@item 
bpo-38319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38319}: sendfile() used in socket and shutil modules was raising
OverflowError for files >= 2GiB on 32-bit architectures.  (patch by
Giampaolo Rodola)

@item 
bpo-38242@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38242}: Revert the new asyncio Streams API

@item 
bpo-13153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13153}: OS native encoding is now used for converting between Python
strings and Tcl objects.  This allows to display, copy and paste to
clipboard emoji and other non-BMP characters.  Converting strings from Tcl
to Python and back now never fails (except MemoryError).

@item 
bpo-38019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38019}: Correctly handle pause/resume reading of closed asyncio unix
pipe.

@item 
bpo-38163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38163}: Child mocks will now detect their type as either synchronous or
asynchronous, asynchronous child mocks will be AsyncMocks and synchronous
child mocks will be either MagicMock or Mock (depending on their parent
type).

@item 
bpo-38161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38161}: Removes _AwaitEvent from AsyncMock.

@item 
bpo-38216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38216}: Allow the rare code that wants to send invalid http requests
from the @code{http.client} library a way to do so.  The fixes for bpo-30458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30458}
led to breakage for some projects that were relying on this ability to
test their own behavior in the face of bad requests.

@item 
bpo-28286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28286}: Deprecate opening @ref{410,,GzipFile} for writing
implicitly.  Always specify the `mode' argument for writing.

@item 
bpo-38108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38108}: Any synchronous magic methods on an AsyncMock now return a
MagicMock. Any asynchronous magic methods on a MagicMock now return an
AsyncMock.

@item 
bpo-38265@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38265}: Update the `length' parameter of @ref{b4d,,os.pread()} to accept
@ref{a4e,,Py_ssize_t} instead of int.

@item 
bpo-38112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38112}: @ref{20,,compileall} has a higher default recursion limit and new
command-line arguments for path manipulation, symlinks handling, and
multiple optimization levels.

@item 
bpo-38248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38248}: asyncio: Fix inconsistent immediate Task cancellation

@item 
bpo-38237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38237}: The arguments for the builtin pow function are more
descriptive. They can now also be passed in as keywords.

@item 
bpo-34002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34002}: Improve efficiency in parts of email package by changing
while-pop to a for loop, using isdisjoint instead of set intersections.

@item 
bpo-38191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38191}: Constructors of @ref{2ad,,NamedTuple} and
@ref{161,,TypedDict} types now accept arbitrary keyword argument
names, including "cls", "self", "typename", "_typename", "fields" and
"_fields".

@item 
bpo-38155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38155}: Add @code{__all__} to  @ref{30,,datetime}. Patch by Tahia Khan.

@item 
bpo-38185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38185}: Fixed case-insensitive string comparison in
@ref{e5a,,sqlite3.Row} indexing.

@item 
bpo-38136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38136}: Changes AsyncMock call count and await count to be two
different counters. Now await count only counts when a coroutine has been
awaited, not when it has been called, and vice-versa. Update the
documentation around this.

@item 
bpo-37828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37828}: Fix default mock name in
@ref{ce6,,unittest.mock.Mock.assert_called()} exceptions. Patch by Abraham
Toriz Cruz.

@item 
bpo-38175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38175}: Fix a memory leak in comparison of @ref{e5a,,sqlite3.Row}
objects.

@item 
bpo-33936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33936}: _hashlib no longer calls obsolete OpenSSL initialization
function with OpenSSL 1.1.0+.

@item 
bpo-34706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34706}: Preserve subclassing in inspect.Signature.from_callable.

@item 
bpo-38153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38153}: Names of hashing algorithms from OpenSSL are now normalized to
follow Python's naming conventions. For example OpenSSL uses sha3-512
instead of sha3_512 or blake2b512 instead of blake2b.

@item 
bpo-38115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38115}: Fix a bug in dis.findlinestarts() where it would return invalid
bytecode offsets. Document that a code object's co_lnotab can contain
invalid bytecode offsets.

@item 
bpo-38148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38148}: Add slots to @ref{a,,asyncio} transport classes, which can reduce
memory usage.

@item 
bpo-38142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38142}: The _hashlib OpenSSL wrapper extension module is now PEP-384
compliant.

@item 
bpo-9216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9216}: hashlib constructors now support usedforsecurity flag to signal
that a hashing algorithm is not used in a security context.

@item 
bpo-36991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36991}: Fixes a potential incorrect AttributeError exception escaping
ZipFile.extract() in some unsupported input error situations.

@item 
bpo-38134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38134}: Remove obsolete copy of PBKDF2_HMAC_fast. All supported OpenSSL
versions contain a fast implementation.

@item 
bpo-38132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38132}: The OpenSSL hashlib wrapper uses a simpler implementation.
Several Macros and pointless caches are gone. The hash name now comes from
OpenSSL's EVP. The algorithm name stays the same, except it is now always
lower case.

@item 
bpo-38008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38008}: Fix parent class check in protocols to correctly identify the
module that provides a builtin protocol, instead of assuming they all come
from the @ref{1e,,collections.abc} module

@item 
bpo-34037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34037}: For @ref{a,,asyncio}, add a new coroutine
@code{loop.shutdown_default_executor()}. The new coroutine provides an API
to schedule an executor shutdown that waits on the threadpool to finish
closing. Also, @ref{466,,asyncio.run()} has been updated to utilize the new
coroutine. Patch by Kyle Stanley.

@item 
bpo-37405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37405}: Fixed regression bug for socket.getsockname() for non-CAN_ISOTP
AF_CAN address family sockets by returning a 1-tuple instead of string.

@item 
bpo-38121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38121}: Update parameter names on functions in importlib.metadata
matching the changes in the 0.22 release of importlib_metadata.

@item 
bpo-38110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38110}: The os.closewalk() implementation now uses the libc fdwalk()
API on platforms where it is available.

@item 
bpo-38093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38093}: Fixes AsyncMock so it doesn't crash when used with
AsyncContextManagers or AsyncIterators.

@item 
bpo-37488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37488}: Add warning to @code{datetime.utctimetuple()},
@code{datetime.utcnow()} and @code{datetime.utcfromtimestamp()} .

@item 
bpo-35640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35640}: Allow passing a @ref{29d,,path-like object} as @code{directory}
argument to the @ref{b31,,http.server.SimpleHTTPRequestHandler} class. Patch
by Géry Ogam.

@item 
bpo-38086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38086}: Update importlib.metadata with changes from importlib_metadata 0.21@footnote{https://gitlab.com/python-devs/importlib_metadata/blob/0.21/importlib_metadata/docs/changelog.rst}.

@item 
bpo-37251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37251}: Remove @code{__code__} check in AsyncMock that incorrectly
evaluated function specs as async objects but failed to evaluate classes
with @code{__await__} but no @code{__code__} attribute defined as async objects.

@item 
bpo-38037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38037}: Fix reference counters in the @ref{c5,,signal} module.

@item 
bpo-38066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38066}: Hide internal asyncio.Stream methods: feed_eof(), feed_data(),
set_exception() and set_transport().

@item 
bpo-38059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38059}: inspect.py now uses sys.exit() instead of exit()

@item 
bpo-38049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38049}: Added command-line interface for the @ref{8,,ast} module.

@item 
bpo-37953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37953}: In @ref{103,,typing}, improved the @code{__hash__} and @code{__eq__}
methods for @code{ForwardReferences}.

@item 
bpo-38026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38026}: Fixed @ref{47e,,inspect.getattr_static()} used @code{isinstance} while
it should avoid dynamic lookup.

@item 
bpo-35923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35923}: Update @ref{c9d,,importlib.machinery.BuiltinImporter} to use
@code{loader._ORIGIN} instead of a hardcoded value. Patch by Donghee Na.

@item 
bpo-38010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38010}: In @code{importlib.metadata} sync with @code{importlib_metadata}
0.20, clarifying behavior of @code{files()} and fixing issue where only one
requirement was returned for @code{requires()} on @code{dist-info} packages.

@item 
bpo-38006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38006}: weakref.WeakValueDictionary defines a local remove() function
used as callback for weak references. This function was created with a
closure. Modify the implementation to avoid the closure.

@item 
bpo-37995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37995}: Added the `indent' option to @ref{8d1,,ast.dump()} which allows it
to produce a multiline indented output.

@item 
bpo-34410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34410}: Fixed a crash in the @code{tee()} iterator when re-enter it.
RuntimeError is now raised in this case.

@item 
bpo-37140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37140}: Fix a ctypes regression of Python 3.8. When a ctypes.Structure
is passed by copy to a function, ctypes internals created a temporary
object which had the side effect of calling the structure finalizer
(__del__) twice. The Python semantics requires a finalizer to be called
exactly once. Fix ctypes internals to no longer call the finalizer twice.

@item 
bpo-37587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37587}: @code{_json.scanstring} is now up to 3x faster when there are many
backslash escaped characters in the JSON string.

@item 
bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834}: Prevent shutil.rmtree exception when built on non-Windows
system without fd system call support, like older versions of macOS.

@item 
bpo-10978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10978}: Semaphores and BoundedSemaphores can now release more than one
waiting thread at a time.

@item 
bpo-37972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37972}: Subscripts to the @code{unittest.mock.call} objects now receive
the same chaining mechanism as any other custom attributes, so that the
following usage no longer raises a @code{TypeError}:

@code{call().foo().__getitem__('bar')}

Patch by blhsing

@item 
bpo-37965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37965}: Fix C compiler warning caused by
distutils.ccompiler.CCompiler.has_function.

@item 
bpo-37964@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37964}: Add @code{F_GETPATH} command to @ref{58,,fcntl}.

@item 
bpo-37960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37960}: @code{repr()} of buffered and text streams now silences only
expected exceptions when get the value of "name" and "mode" attributes.

@item 
bpo-37961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37961}: Add a @code{total_nframe} field to the traces collected by the
tracemalloc module. This field indicates the original number of frames
before it was truncated.

@item 
bpo-37951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37951}: Most features of the subprocess module now work again in
subinterpreters. Only `preexec_fn' is restricted in subinterpreters.

@item 
bpo-36205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36205}: Fix the rusage implementation of time.process_time() to
correctly report the sum of the system and user CPU time.

@item 
bpo-37950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37950}: Fix @ref{8d1,,ast.dump()} when call with incompletely initialized
node.

@item 
bpo-34679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34679}: Restores instantiation of Windows IOCP event loops from the
non-main thread.

@item 
bpo-36917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36917}: Add default implementation of the
@ref{a5c,,ast.NodeVisitor.visit_Constant()} method which emits a deprecation
warning and calls corresponding methods @code{visit_Num()}, @code{visit_Str()},
etc.

@item 
bpo-37798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37798}: Update test_statistics.py to verify that the statistics module
works well for both C and Python implementations. Patch by Donghee Na

@item 
bpo-26589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26589}: Added a new status code to the http module: 451
UNAVAILABLE_FOR_LEGAL_REASONS

@item 
bpo-37915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37915}: Fix a segmentation fault that appeared when comparing instances
of @code{datetime.timezone} and @code{datetime.tzinfo} objects. Patch by Pablo
Galindo.

@item 
bpo-32554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32554}: Deprecate having random.seed() call hash on arbitrary types.

@item 
bpo-9938@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9938}: Add optional keyword argument @code{exit_on_error} for
@code{ArgumentParser}.

@item 
bpo-37851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37851}: The @ref{57,,faulthandler} module no longer allocates its
alternative stack at Python startup. Now the stack is only allocated at
the first faulthandler usage.

@item 
bpo-32793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32793}: Fix a duplicated debug message when
@ref{1958,,smtplib.SMTP.connect()} is called.

@item 
bpo-37885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37885}: venv: Don't generate unset variable warning on deactivate.

@item 
bpo-37868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37868}: Fix dataclasses.is_dataclass when given an instance that never
raises AttributeError in __getattr__.  That is, an object that returns
something for __dataclass_fields__ even if it's not a dataclass.

@item 
bpo-37811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37811}: Fix @code{socket} module's @code{socket.connect(address)} function
being unable to establish connection in case of interrupted system call.
The problem was observed on all OSes which @code{poll(2)} system call can
take only non-negative integers and -1 as a timeout value.

@item 
bpo-37863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37863}: Optimizations for Fraction.__hash__ suggested by Tim Peters.

@item 
bpo-21131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21131}: Fix @code{faulthandler.register(chain=True)} stack. faulthandler
now allocates a dedicated stack of @code{SIGSTKSZ*2} bytes, instead of just
@code{SIGSTKSZ} bytes. Calling the previous signal handler in faulthandler
signal handler uses more than @code{SIGSTKSZ} bytes of stack memory on some
platforms.

@item 
bpo-37798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37798}: Add C fastpath for statistics.NormalDist.inv_cdf() Patch by
Donghee Na

@item 
bpo-37804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37804}: Remove the deprecated method @code{threading.Thread.isAlive()}.
Patch by Donghee Na.

@item 
bpo-37819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37819}: Add Fraction.as_integer_ratio() to match the corresponding
methods in bool, int, float, and decimal.

@item 
bpo-14465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14465}: Add an xml.etree.ElementTree.indent() function for
pretty-printing XML trees. Contributed by Stefan Behnel.

@item 
bpo-37810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37810}: Fix @ref{37,,difflib} @code{?} hint in diff output when dealing with
tabs.  Patch by Anthony Sottile.

@item 
bpo-37772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37772}: In @code{zipfile.Path}, when adding implicit dirs, ensure that
ancestral directories are added and that duplicates are excluded.

@item 
bpo-18578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18578}: Renamed and documented @code{test.bytecode_helper} as
@code{test.support.bytecode_helper}. Patch by Joannah Nanjekye.

@item 
bpo-37785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37785}: Fix xgettext warnings in @ref{6,,argparse}.

@item 
bpo-34488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34488}: @code{writelines()} method of @ref{e8d,,io.BytesIO} is now
slightly faster when many small lines are passed. Patch by Sergey
Fedoseev.

@item 
bpo-37449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37449}: @code{ensurepip} now uses @code{importlib.resources.read_binary()} to
read data instead of @code{pkgutil.get_data()}. Patch by Joannah Nanjekye.

@item 
bpo-28292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28292}: Mark calendar.py helper functions as being private.  The
follows PEP 8 guidance to maintain the style conventions in the module and
it addresses a known case of user confusion.

@item 
bpo-18049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18049}: Add definition of THREAD_STACK_SIZE for AIX in
Python/thread_pthread.h The default thread stacksize caused crashes with
the default recursion limit Patch by M Felt

@item 
bpo-37742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37742}: The logging.getLogger() API now returns the root logger when
passed the name 'root', whereas previously it returned a non-root logger
named 'root'. This could affect cases where user code explicitly wants a
non-root logger named 'root', or instantiates a logger using
logging.getLogger(__name__) in some top-level module called 'root.py'.

@item 
bpo-37738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37738}: Fix the implementation of curses @code{addch(str, color_pair)}:
pass the color pair to @code{setcchar()}, instead of always passing 0 as the
color pair.

@item 
bpo-37723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37723}: Fix performance regression on regular expression parsing with
huge character sets. Patch by Yann Vaginay.

@item 
bpo-35943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35943}: The function @ref{ba1,,PyImport_GetModule()} now ensures any
module it returns is fully initialized. Patch by Joannah Nanjekye.

@item 
bpo-32178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32178}: Fix IndexError in @ref{3b,,email} package when trying to parse
invalid address fields starting with @code{:}.

@item 
bpo-37268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37268}: The @code{parser} module is deprecated and will be removed in
future versions of Python.

@item 
bpo-11953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11953}: Completing WSA* error codes in @ref{cb,,socket}.

@item 
bpo-37685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37685}: Fixed comparisons of @ref{9bd,,datetime.timedelta} and
@ref{10a1,,datetime.timezone}.

@item 
bpo-37697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37697}: Synchronize @code{importlib.metadata} with importlib_metadata 0.19@footnote{https://gitlab.com/python-devs/importlib_metadata/-/milestones/20},
improving handling of EGG-INFO files and fixing a crash when entry point
names contained colons.

@item 
bpo-37695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37695}: Correct @ref{1081,,curses.unget_wch()} error message.  Patch by
Anthony Sottile.

@item 
bpo-37689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37689}: Add @code{is_relative_to()} in @code{PurePath} to determine
whether or not one path is relative to another.

@item 
bpo-29553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29553}: Fixed @ref{1959,,argparse.ArgumentParser.format_usage()} for mutually
exclusive groups. Patch by Andrew Nester.

@item 
bpo-37691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37691}: Let math.dist() accept coordinates as sequences (or iterables)
rather than just tuples.

@item 
bpo-37685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37685}: Fixed @code{__eq__}, @code{__lt__} etc implementations in some
classes. They now return @ref{7bc,,NotImplemented} for unsupported type of
the other operand. This allows the other operand to play role (for example
the equality comparison with @ref{195a,,ANY} will return
@code{True}).

@item 
bpo-37354@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37354}: Make Activate.ps1 Powershell script static to allow for signing
it.

@item 
bpo-37664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37664}: Update wheels bundled with ensurepip (pip 19.2.3 and setuptools
41.2.0)

@item 
bpo-37663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37663}: Bring consistency to venv shell activation scripts by always
using __VENV_PROMPT__.

@item 
bpo-37642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37642}: Allowed the pure Python implementation of
@ref{10a1,,datetime.timezone} to represent sub-minute offsets close to
minimum and maximum boundaries, specifically in the ranges (23:59, 24:00)
and (-23:59, 24:00). Patch by Ngalim Siregar

@item 
bpo-36161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36161}: In @ref{ac,,posix}, use @code{ttyname_r} instead of @code{ttyname} for
thread safety.

@item 
bpo-36324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36324}: Make internal attributes for statistics.NormalDist() private.

@item 
bpo-37555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37555}: Fix @code{NonCallableMock._call_matcher} returning tuple instead
of @code{_Call} object when @code{self._spec_signature} exists. Patch by
Elizabeth Uselton

@item 
bpo-29446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29446}: Make @code{from tkinter import *} import only the expected
objects.

@item 
bpo-16970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16970}: Adding a value error when an invalid value in passed to nargs
Patch by Robert Leenders

@item 
bpo-34443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34443}: Exceptions from @ref{55,,enum} now use the @code{__qualname} of the
enum class in the exception message instead of the @code{__name__}.

@item 
bpo-37491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37491}: Fix @code{IndexError} when parsing email headers with unexpectedly
ending bare-quoted string value. Patch by Abhilash Raj.

@item 
bpo-37587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37587}: Make json.loads faster for long strings. (Patch by Marco
Paolini)

@item 
bpo-18378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18378}: Recognize "UTF-8" as a valid value for LC_CTYPE in
locale._parse_localename.

@item 
bpo-37579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37579}: Return @ref{7bc,,NotImplemented} in Python implementation of
@code{__eq__} for @ref{9bd,,timedelta} and @ref{1c9,,time}
when the other object being compared is not of the same type to match C
implementation. Patch by Karthikeyan Singaravelan.

@item 
bpo-21478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21478}: Record calls to parent when autospecced object is attached to a
mock using @code{unittest.mock.attach_mock()}. Patch by Karthikeyan
Singaravelan.

@item 
bpo-37531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37531}: "python3 -m test -jN --timeout=TIMEOUT" now kills a worker
process if it runs longer than `TIMEOUT' seconds.

@item 
bpo-37482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37482}: Fix serialization of display name in originator or destination
address fields with both encoded words and special chars.

@item 
bpo-36993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36993}: Improve error reporting for corrupt zip files with bad zip64
extra data. Patch by Daniel Hillier.

@item 
bpo-37502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37502}: pickle.loads() no longer raises TypeError when the buffers
argument is set to None

@item 
bpo-37520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37520}: Correct behavior for zipfile.Path.parent when the path object
identifies a subdirectory.

@item 
bpo-18374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18374}: Fix the @code{.col_offset} attribute of nested @ref{195b,,ast.BinOp}
instances which had a too large value in some situations.

@item 
bpo-37424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37424}: Fixes a possible hang when using a timeout on
@code{subprocess.run()} while capturing output.  If the child process spawned
its own children or otherwise connected its stdout or stderr handles with
another process, we could hang after the timeout was reached and our child
was killed when attempting to read final output from the pipes.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: Fix @code{multiprocessing.util.get_temp_dir()} finalizer: clear
also the 'tempdir' configuration of the current process, so next call to
@code{get_temp_dir()} will create a new temporary directory, rather than
reusing the removed temporary directory.

@item 
bpo-37481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37481}: The distutils @code{bdist_wininst} command is deprecated in Python
3.8, use @code{bdist_wheel} (wheel packages) instead.

@item 
bpo-37479@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37479}: When @code{Enum.__str__} is overridden in a derived class, the
override will be used by @code{Enum.__format__} regardless of whether mixin
classes are present.

@item 
bpo-37440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37440}: http.client now enables TLS 1.3 post-handshake authentication
for default context or if a cert_file is passed to HTTPSConnection.

@item 
bpo-37437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37437}: Update vendorized expat version to 2.2.7.

@item 
bpo-37428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37428}: SSLContext.post_handshake_auth = True no longer sets
SSL_VERIFY_POST_HANDSHAKE verify flag for client connections. Although the
option is documented as ignored for clients, OpenSSL implicitly enables
cert chain validation when the flag is set.

@item 
bpo-37420@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37420}: @ref{10ee,,os.sched_setaffinity()} now correctly handles errors that
arise during iteration over its @code{mask} argument. Patch by Brandt Bucher.

@item 
bpo-37412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37412}: The @ref{a7f,,os.getcwdb()} function now uses the UTF-8 encoding on
Windows, rather than the ANSI code page: see 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for the rationale.
The function is no longer deprecated on Windows.

@item 
bpo-37406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37406}: The sqlite3 module now raises TypeError, rather than
ValueError, if operation argument type is not str: execute(),
executemany() and calling a connection.

@item 
bpo-29412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29412}: Fix IndexError in parsing a header value ending unexpectedly.
Patch by Abhilash Raj.

@item 
bpo-36546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36546}: The `dist' argument for statistics.quantiles() is now
positional only. The current name doesn't reflect that the argument can be
either a dataset or a distribution.  Marking the parameter as positional
avoids confusion and makes it possible to change the name later.

@item 
bpo-37394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37394}: Fix a bug that was causing the @ref{b5,,queue} module to fail if
the accelerator module was not available. Patch by Pablo Galindo.

@item 
bpo-37376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37376}: @ref{ad,,pprint} now has support for
@ref{1cc,,types.SimpleNamespace}. Patch by Carl Bordum Hansen.

@item 
bpo-26967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26967}: An @ref{523,,ArgumentParser} with
@code{allow_abbrev=False} no longer disables grouping of short flags, such as
@code{-vv}, but only disables abbreviation of long flags as documented. Patch
by Zac Hatfield-Dodds.

@item 
bpo-37212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37212}: @ref{195c,,unittest.mock.call()} now preserves the order of keyword
arguments in repr output. Patch by Karthikeyan Singaravelan.

@item 
bpo-37372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37372}: Fix error unpickling datetime.time objects from Python 2 with
seconds>=24. Patch by Justin Blanchard.

@item 
bpo-37345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37345}: Add formal support for UDPLITE sockets. Support was present
before, but it is now easier to detect support with @code{hasattr(socket,
'IPPROTO_UDPLITE')} and there are constants defined for each of the
values needed: @code{socket.IPPROTO_UDPLITE}, @code{UDPLITE_SEND_CSCOV}, and
@code{UDPLITE_RECV_CSCOV}. Patch by Gabe Appleton.

@item 
bpo-37358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37358}: Optimized @code{functools.partial} by using vectorcall.

@item 
bpo-37347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37347}: @ref{2a7,,sqlite3.Connection.create_aggregate()},
@ref{2a6,,sqlite3.Connection.create_function()},
@ref{2a8,,sqlite3.Connection.set_authorizer()},
@ref{2a9,,sqlite3.Connection.set_progress_handler()}
@ref{2aa,,sqlite3.Connection.set_trace_callback()} methods lead to segfaults if
some of these methods are called twice with an equal object but not the
same. Now callbacks are stored more carefully. Patch by Aleksandr Balezin.

@item 
bpo-37163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37163}: The `obj' argument of @ref{1682,,dataclasses.replace()} is
positional-only now.

@item 
bpo-37085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37085}: Add the optional Linux SocketCAN Broadcast Manager constants,
used as flags to configure the BCM behaviour, in the socket module.  Patch
by Karl Ding.

@item 
bpo-37328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37328}: @code{HTMLParser.unescape} is removed.  It was undocumented and
deprecated since Python 3.4.

@item 
bpo-37305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37305}: Add .webmanifest -> application/manifest+json to list of
recognized file types and content type headers

@item 
bpo-37320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37320}: @code{aifc.openfp()} alias to @code{aifc.open()}, @code{sunau.openfp()}
alias to @code{sunau.open()}, and @code{wave.openfp()} alias to @code{wave.open()}
have been removed. They were deprecated since Python 3.7.

@item 
bpo-37315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37315}: Deprecated accepting floats with integral value (like @code{5.0})
in @ref{934,,math.factorial()}.

@item 
bpo-37312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37312}: @code{_dummy_thread} and @code{dummy_threading} modules have been
removed. These modules were deprecated since Python 3.7 which requires
threading support.

@item 
bpo-33972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33972}: Email with single part but content-type set to @code{multipart/*}
doesn't raise AttributeError anymore.

@item 
bpo-37280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37280}: Use threadpool for reading from file for sendfile fallback
mode.

@item 
bpo-37279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37279}: Fix asyncio sendfile support when sendfile sends extra data in
fallback mode.

@item 
bpo-19865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19865}: @ref{195d,,ctypes.create_unicode_buffer()} now also supports non-BMP
characters on platforms with 16-bit @code{wchar_t} (for example,
Windows and AIX).

@item 
bpo-37266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37266}: In a subinterpreter, spawning a daemon thread now raises an
exception. Daemon threads were never supported in subinterpreters.
Previously, the subinterpreter finalization crashed with a Python fatal
error if a daemon thread was still running.

@item 
bpo-37210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37210}: Allow pure Python implementation of @ref{a5,,pickle} to work even
when the C @code{_pickle} module is unavailable.

@item 
bpo-21872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21872}: Fix @ref{89,,lzma}: module decompresses data incompletely. When
decompressing a FORMAT_ALONE format file, and it doesn't have the end
marker, sometimes the last one to dozens bytes can't be output. Patch by
Ma Lin.

@item 
bpo-35922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35922}: Fix @code{RobotFileParser.crawl_delay()} and
@code{RobotFileParser.request_rate()} to return @code{None} rather than raise
@ref{343,,AttributeError} when no relevant rule is defined in the robots.txt
file.  Patch by Rémi Lapeyre.

@item 
bpo-35766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35766}: Change the format of feature_version to be a (major, minor)
tuple.

@item 
bpo-36607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36607}: Eliminate @ref{193,,RuntimeError} raised by
@ref{943,,asyncio.all_tasks()} if internal tasks weak set is changed by another
thread during iteration.

@item 
bpo-18748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18748}: @code{_pyio.IOBase} destructor now does nothing if getting
the @code{closed} attribute fails to better mimic @code{_io.IOBase}
finalizer.

@item 
bpo-36402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36402}: Fix a race condition at Python shutdown when waiting for
threads. Wait until the Python thread state of all non-daemon threads get
deleted (join all non-daemon threads), rather than just wait until
non-daemon Python threads complete.

@item 
bpo-37206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37206}: Default values which cannot be represented as Python objects no
longer improperly represented as @code{None} in function signatures.

@item 
bpo-37111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37111}: Added @code{encoding} and @code{errors} keyword parameters to
@code{logging.basicConfig}.

@item 
bpo-12144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12144}: Ensure cookies with @code{expires} attribute are handled in
@code{CookieJar.make_cookies()}.

@item 
bpo-34886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34886}: Fix an unintended ValueError from @ref{b74,,subprocess.run()} when
checking for conflicting `input' and `stdin' or `capture_output' and
`stdout' or `stderr' args when they were explicitly provided but with
@code{None} values within a passed in @code{**kwargs} dict rather than as passed
directly by name. Patch contributed by Rémi Lapeyre.

@item 
bpo-37173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37173}: The exception message for @code{inspect.getfile()} now correctly
reports the passed class rather than the builtins module.

@item 
bpo-37178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37178}: Give math.perm() a one argument form that means the same as
math.factorial().

@item 
bpo-37178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37178}: For math.perm(n, k), let k default to n, giving the same result
as factorial.

@item 
bpo-37165@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37165}: Converted _collections._count_elements to use the Argument
Clinic.

@item 
bpo-34767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34767}: Do not always create a @ref{5c6,,collections.deque} in
@ref{a5f,,asyncio.Lock}.

@item 
bpo-37158@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37158}: Speed-up statistics.fmean() by switching from a function to a
generator.

@item 
bpo-34282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34282}: Remove @code{Enum._convert} method, deprecated in 3.8.

@item 
bpo-37150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37150}: @code{argparse._ActionsContainer.add_argument} now throws error,
if someone accidentally pass FileType class object instead of instance of
FileType as @code{type} argument.

@item 
bpo-28724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28724}: The socket module now has the @ref{920,,socket.send_fds()} and
@code{socket.recv.fds()} methods. Contributed by Joannah Nanjekye, Shinya
Okano and Victor Stinner.

@item 
bpo-35621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35621}: Support running asyncio subprocesses when execution event loop
in a thread on UNIX.

@item 
bpo-36520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36520}: Lengthy email headers with UTF-8 characters are now properly
encoded when they are folded. Patch by Jeffrey Kintscher.

@item 
bpo-30835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30835}: Fixed a bug in email parsing where a message with invalid bytes
in content-transfer-encoding of a multipart message can cause an
AttributeError. Patch by Andrew Donnellan.

@item 
bpo-31163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31163}: pathlib.Path instance's rename and replace methods now return
the new Path instance.

@item 
bpo-25068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25068}: @ref{195e,,urllib.request.ProxyHandler} now lowercases the keys of
the passed dictionary.

@item 
bpo-26185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26185}: Fix @ref{7e7,,repr()} on empty @code{ZipInfo} object. Patch by
Mickaël Schoentgen.

@item 
bpo-21315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21315}: Email headers containing RFC2047 encoded words are parsed
despite the missing whitespace, and a defect registered. Also missing
trailing whitespace after encoded words is now registered as a defect.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Port test_datetime to VxWorks: skip zoneinfo tests on VxWorks

@item 
bpo-35805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35805}: Add parser for Message-ID header and add it to default
HeaderRegistry. This should prevent folding of Message-ID using RFC 2048
encoded words.

@item 
bpo-36871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36871}: Ensure method signature is used instead of constructor
signature of a class while asserting mock object against method calls.
Patch by Karthikeyan Singaravelan.

@item 
bpo-35070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35070}: posix.getgrouplist() now works correctly when the user belongs
to NGROUPS_MAX supplemental groups. Patch by Jeffrey Kintscher.

@item 
bpo-31783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31783}: Fix race condition in ThreadPoolExecutor when worker threads
are created during interpreter shutdown.

@item 
bpo-36582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36582}: Fix @code{UserString.encode()} to correctly return @code{bytes}
rather than a @code{UserString} instance.

@item 
bpo-32424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32424}: Deprecate xml.etree.ElementTree.Element.copy() in favor of
copy.copy().

Patch by Gordon P. Hemsley

@item 
bpo-36564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36564}: Fix infinite loop in email header folding logic that would be
triggered when an email policy's max_line_length is not long enough to
include the required markup and any values in the message. Patch by Paul
Ganssle

@item 
bpo-36543@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36543}: Removed methods Element.getchildren(), Element.getiterator()
and ElementTree.getiterator() and the xml.etree.cElementTree module.

@item 
bpo-36409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36409}: Remove the old plistlib API deprecated in Python 3.4

@item 
bpo-36302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36302}: distutils sorts source file lists so that Extension .so files
build more reproducibly by default

@item 
bpo-36250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36250}: Ignore @code{ValueError} from @code{signal} with @code{interaction} in
non-main thread.

@item 
bpo-36046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36046}: Added @code{user}, @code{group} and @code{extra_groups} parameters to
the subprocess.Popen constructor. Patch by Patrick McLean.

@item 
bpo-32627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32627}: Fix compile error when @code{_uuid} headers conflicting included.

@item 
bpo-35800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35800}: Deprecate @code{smtpd.MailmanProxy} ready for future removal.

@item 
bpo-35168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35168}: @ref{195f,,shlex.shlex.punctuation_chars} is now a read-only
property.

@item 
bpo-8538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8538}: Add support for boolean actions like @code{--foo} and @code{--no-foo}
to argparse. Patch contributed by Rémi Lapeyre.

@item 
bpo-20504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20504}: Fixes a bug in @code{cgi} module when a multipart/form-data
request has no @code{Content-Length} header.

@item 
bpo-25988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25988}: The abstract base classes in @ref{1e,,collections.abc} no longer
are exposed in the regular @ref{1d,,collections} module.

@item 
bpo-11122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11122}: Distutils won't check for rpmbuild in specified paths only.

@item 
bpo-34775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34775}: Division handling of PurePath now returns NotImplemented
instead of raising a TypeError when passed something other than an
instance of str or PurePath. Patch by Roger Aiudi.

@item 
bpo-34749@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34749}: @ref{15b6,,binascii.a2b_base64()} is now up to 2 times faster. Patch
by Sergey Fedoseev.

@item 
bpo-34519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34519}: Add additional aliases for HP Roman 8. Patch by Michael Osipov.

@item 
bpo-28009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28009}: Fix uuid.getnode() on platforms with '.' as MAC Addr delimiter
as well fix for MAC Addr format that omits a leading 0 in MAC Addr values.
Currently, AIX is the only know platform with these settings. Patch by
Michael Felt.

@item 
bpo-30618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30618}: Add @ref{90c,,readlink()}. Patch by Girts Folkmanis.

@item 
bpo-32498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32498}: Made @ref{1714,,urllib.parse.unquote()} accept bytes in addition to
strings. Patch by Stein Karlsen.

@item 
bpo-33348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33348}: lib2to3 now recognizes expressions after @code{*} and @code{**} like
in @code{f(*[] or [])}.

@item 
bpo-32689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32689}: Update @ref{a4a,,shutil.move()} function to allow for Path objects
to be used as source argument. Patch by Emily Morehouse and Maxwell
"5.13b" McKinnon.

@item 
bpo-32820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32820}: Added @code{__format__} to IPv4 and IPv6 classes.  Always outputs
a fully zero-padded string. Supports b/x/n modifiers (bin/hex/native
format). Native format for IPv4 is bin, native format for IPv6 is hex.
Also supports '#' and '_' modifiers.

@item 
bpo-27657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27657}: Fix urllib.parse.urlparse() with numeric paths. A string like
"path:80" is no longer parsed as a path but as a scheme ("path") and a
path ("80").

@item 
bpo-4963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4963}: Fixed non-deterministic behavior related to mimetypes extension
mapping and module reinitialization.
@end itemize

@node Documentation<41>,Tests<43>,Library<46>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id409}@anchor{1960}
@subsubsection Documentation



@itemize -

@item 
bpo-21767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21767}: Explicitly mention abc support in functools.singledispatch

@item 
bpo-38816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38816}: Provides more details about the interaction between
@code{fork()} and CPython's runtime, focusing just on the C-API.  This
includes cautions about where @code{fork()} should and shouldn't be
called.

@item 
bpo-38351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38351}: Modernize @ref{3b,,email} examples from %-formatting to f-strings.

@item 
bpo-38778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38778}: Document the fact that @ref{193,,RuntimeError} is raised if
@ref{195,,os.fork()} is called in a subinterpreter.

@item 
bpo-38592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38592}: Add Brazilian Portuguese to the language switcher at Python
Documentation website.

@item 
bpo-38294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38294}: Add list of no-longer-escaped chars to re.escape documentation

@item 
bpo-38053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38053}: Modernized the plistlib documentation

@item 
bpo-26868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26868}: Fix example usage of @ref{35c,,PyModule_AddObject()} to properly
handle errors.

@item 
bpo-36797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36797}: Fix a dead link in the distutils API Reference.

@item 
bpo-37977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37977}: Warn more strongly and clearly about pickle insecurity

@item 
bpo-37979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37979}: Added a link to dateutil.parser.isoparse in the
datetime.fromisoformat documentation. Patch by Paul Ganssle

@item 
bpo-12707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12707}: Deprecate info(), geturl(), getcode() methods in favor of the
headers, url, and status properties, respectively, for HTTPResponse and
addinfourl. Also deprecate the code attribute of addinfourl in favor of
the status attribute. Patch by Ashwin Ramaswami

@item 
bpo-37937@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37937}: Mention @code{frame.f_trace} in @ref{14b6,,sys.settrace()} docs.

@item 
bpo-37878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37878}: Make @ref{1961,,PyThreadState_DeleteCurrent()} Internal.

@item 
bpo-37759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37759}: Beginning edits to Whatsnew 3.8

@item 
bpo-37726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37726}: Stop recommending getopt in the tutorial for command line
argument parsing and promote argparse.

@item 
bpo-32910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32910}: Remove implementation-specific behaviour of how venv's
Deactivate works.

@item 
bpo-37256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37256}: Fix wording of arguments for @code{Request} in
@ref{10a,,urllib.request}

@item 
bpo-37284@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37284}: Add a brief note to indicate that any new
@code{sys.implementation} required attributes must go through the PEP
process.

@item 
bpo-30088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30088}: Documented that @ref{412,,mailbox.Maildir} constructor doesn't
attempt to verify the maildir folder layout correctness. Patch by
Sviatoslav Sydorenko.

@item 
bpo-37521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37521}: Fix @code{importlib} examples to insert any newly created modules
via importlib.util.module_from_spec() immediately into sys.modules instead
of after calling loader.exec_module().

Thanks to Benjamin Mintz for finding the bug.

@item 
bpo-37456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37456}: Slash ('/') is now part of syntax.

@item 
bpo-37487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37487}: Fix PyList_GetItem index description to include 0.

@item 
bpo-37149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37149}: Replace the dead link to the Tkinter 8.5 reference by John
Shipman, New Mexico Tech, with a link to the archive.org copy.

@item 
bpo-37478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37478}: Added possible exceptions to the description of os.chdir().

@item 
bpo-34903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34903}: Documented that in @ref{1593,,datetime.datetime.strptime()}, the
leading zero in some two-digit formats is optional. Patch by Mike Gleen.

@item 
bpo-36260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36260}: Add decompression pitfalls to zipfile module documentation.

@item 
bpo-37004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37004}: In the documentation for difflib, a note was added explicitly
warning that the results of SequenceMatcher's ratio method may depend on
the order of the input strings.

@item 
bpo-36960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36960}: Restructured the @ref{30,,datetime} docs in the interest of making
them more user-friendly and improving readability. Patch by Brad Solomon.

@item 
bpo-36487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36487}: Make C-API docs clear about what the "main" interpreter is.

@item 
bpo-23460@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23460}: The documentation for decimal string formatting using the
@code{:g} specifier has been updated to reflect the correct exponential
notation cutoff point. Original patch contributed by Tuomas Suutari.

@item 
bpo-35803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35803}: Document and test that @code{tempfile} functions may accept a
@ref{29d,,path-like object} for the @code{dir} argument.  Patch by Anthony
Sottile.

@item 
bpo-33944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33944}: Added a note about the intended use of code in .pth files.

@item 
bpo-34293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34293}: Fix the Doc/Makefile regarding PAPER environment variable and
PDF builds

@item 
bpo-25237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25237}: Add documentation for tkinter modules
@end itemize

@node Tests<43>,Build<46>,Documentation<41>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id410}@anchor{1962}
@subsubsection Tests



@itemize -

@item 
bpo-38614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38614}: Fix test_communicate() of test_asyncio.test_subprocess: use
@code{support.LONG_TIMEOUT} (5 minutes), instead of just 1 minute.

@item 
bpo-38614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38614}: Add timeout constants to @ref{e3,,test.support}:
@ref{1942,,LOOPBACK_TIMEOUT},
@ref{1943,,INTERNET_TIMEOUT},
@ref{183c,,SHORT_TIMEOUT} and
@ref{1944,,LONG_TIMEOUT}.

@item 
bpo-38502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38502}: test.regrtest now uses process groups in the multiprocessing
mode (-jN command line option) if process groups are available: if
@ref{1963,,os.setsid()} and @ref{1964,,os.killpg()} functions are available.

@item 
bpo-35998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35998}: Fix a race condition in test_asyncio.test_start_tls_server_1().
Previously, there was a race condition between the test main() function
which replaces the protocol and the test ServerProto protocol which sends
ANSWER once it gets HELLO. Now, only the test main() function is
responsible to send data, ServerProto no longer sends data.

@item 
bpo-38470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38470}: Fix @code{test_compileall.test_compile_dir_maxlevels()} on Windows
without long path support: only create 3 subdirectories instead of between
20 and 100 subdirectories.

@item 
bpo-37531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37531}: On timeout, regrtest no longer attempts to call
@code{popen.communicate()} again: it can hang until all child processes using
stdout and stderr pipes completes. Kill the worker process and ignores its
output. Change also the faulthandler timeout of the main process from 1
minute to 5 minutes, for Python slowest buildbots.

@item 
bpo-38239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38239}: Fix test_gdb for Link Time Optimization (LTO) builds.

@item 
bpo-38275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38275}: test_ssl now handles disabled TLS/SSL versions better.
OpenSSL's crypto policy and run-time settings are recognized and tests for
disabled versions are skipped. Tests also accept more TLS minimum_versions
for platforms that override OpenSSL's default with strict settings.

@item 
bpo-38271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38271}: The private keys for test_ssl were encrypted with 3DES in
traditional PKCS#5 format. 3DES and the digest algorithm of PKCS#5 are
blocked by some strict crypto policies. Use PKCS#8 format with AES256
encryption instead.

@item 
bpo-38270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38270}: test.support now has a helper function to check for
availability of a hash digest function. Several tests are refactored avoid
MD5 and use SHA256 instead. Other tests are marked to use MD5 and skipped
when MD5 is disabled.

@item 
bpo-37123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37123}: Multiprocessing test test_mymanager() now also expects
-SIGTERM, not only exitcode 0. BaseManager._finalize_manager() sends
SIGTERM to the manager process if it takes longer than 1 second to stop,
which happens on slow buildbots.

@item 
bpo-38212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38212}: Multiprocessing tests: increase
test_queue_feeder_donot_stop_onexc() timeout from 1 to 60 seconds.

@item 
bpo-38117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38117}: Test with OpenSSL 1.1.1d

@item 
bpo-38018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38018}: Increase code coverage for multiprocessing.shared_memory.

@item 
bpo-37805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37805}: Add tests for json.dump(..., skipkeys=True). Patch by Donghee
Na.

@item 
bpo-37531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37531}: Enhance regrtest multiprocess timeout: write a message when
killing a worker process, catch popen.kill() and popen.wait() exceptions,
put a timeout on the second call to popen.communicate().

@item 
bpo-37876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37876}: Add tests for ROT-13 codec.

@item 
bpo-36833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36833}: Added tests for @code{PyDateTime_@var{xxx}_GET_@var{xxx}()} macros of
the C API of the @ref{30,,datetime} module. Patch by Joannah Nanjekye.

@item 
bpo-37558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37558}: Fix test_shared_memory_cleaned_after_process_termination name
handling

@item 
bpo-37526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37526}: Add @code{test.support.catch_threading_exception()}: context
manager catching @ref{939,,threading.Thread} exception using
@ref{835,,threading.excepthook()}.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: test_concurrent_futures now explicitly stops the ForkServer
instance if it's running.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: multiprocessing tests now stop the ForkServer instance if it's
running: close the "alive" file descriptor to ask the server to stop and
then remove its UNIX address.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: test_distutils.test_build_ext() is now able to remove the
temporary directory on Windows: don't import the newly built C extension
("xx") in the current process, but test it in a separated process.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: test_concurrent_futures now cleans up multiprocessing to remove
immediately temporary directories created by
multiprocessing.util.get_temp_dir().

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: test_winconsoleio doesn't leak a temporary file anymore: use
tempfile.TemporaryFile() to remove it when the test completes.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: multiprocessing tests now explicitly call @code{_run_finalizers()}
to immediately remove temporary directories created by tests.

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: urllib.request tests now call
@ref{1965,,urlcleanup()} to remove temporary files created by
@code{urlretrieve()} tests and to clear the @code{_opener} global variable set
by @code{urlopen()} and functions calling indirectly @code{urlopen()}.

@item 
bpo-37472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37472}: Remove @code{Lib/test/outstanding_bugs.py}.

@item 
bpo-37199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37199}: Fix test failures when IPv6 is unavailable or disabled.

@item 
bpo-19696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19696}: Replace deprecated method "random.choose" with "random.choice"
in "test_pkg_import.py".

@item 
bpo-37335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37335}: Remove no longer necessary code from c locale coercion tests

@item 
bpo-37421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37421}: Fix test_shutil to no longer leak temporary files.

@item 
bpo-37411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37411}: Fix test_wsgiref.testEnviron() to no longer depend on the
environment variables (don't fail if "X" variable is set).

@item 
bpo-37400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37400}: Fix test_os.test_chown(): use os.getgroups() rather than
grp.getgrall() to get groups. Rename also the test to test_chown_gid().

@item 
bpo-37359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37359}: Add --cleanup option to python3 -m test to remove
@code{test_python_*} directories of previous failed jobs. Add "make
cleantest" to run @code{python3 -m test --cleanup}.

@item 
bpo-37362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37362}: test_gdb no longer fails if it gets an "unexpected" message on
stderr: it now ignores stderr. The purpose of test_gdb is to test that
python-gdb.py commands work as expected, not to test gdb.

@item 
bpo-35998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35998}: Avoid TimeoutError in test_asyncio: test_start_tls_server_1()

@item 
bpo-37278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37278}: Fix test_asyncio ProactorLoopCtrlC: join the thread to prevent
leaking a running thread and leaking a reference.

@item 
bpo-37261@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37261}: Fix @ref{1966,,test.support.catch_unraisable_exception()}: its
__exit__() method now ignores unraisable exception raised when clearing
its @code{unraisable} attribute.

@item 
bpo-37069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37069}: regrtest now uses @ref{1f4,,sys.unraisablehook()} to mark a test as
"environment altered" (ENV_CHANGED) if it emits an "unraisable exception".
Moreover, regrtest logs a warning in this case.

Use @code{python3 -m test --fail-env-changed} to catch unraisable exceptions
in tests.

@item 
bpo-37252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37252}: Fix assertions in @code{test_close} and
@code{test_events_mask_overflow} devpoll tests.

@item 
bpo-37169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37169}: Rewrite @code{_PyObject_IsFreed()} unit tests.

@item 
bpo-37153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37153}: @code{test_venv.test_multiprocessing()} now explicitly calls
@code{pool.terminate()} to wait until the pool completes.

@item 
bpo-34001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34001}: Make test_ssl pass with LibreSSL. LibreSSL handles minimum and
maximum TLS version differently than OpenSSL.

@item 
bpo-36919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36919}: Make @code{test_source_encoding.test_issue2301} implementation
independent. The test will work now for both CPython and IronPython.

@item 
bpo-30202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30202}: Update @code{test.test_importlib.test_abc} to test
@code{find_spec()}.

@item 
bpo-28009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28009}: Modify the test_uuid logic to test when a program is available
AND can be used to obtain a MACADDR as basis for an UUID. Patch by M. Felt

@item 
bpo-34596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34596}: Fallback to a default reason when @ref{1967,,unittest.skip()} is
uncalled. Patch by Naitree Zhu.
@end itemize

@node Build<46>,Windows<41>,Tests<43>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id411}@anchor{1968}
@subsubsection Build



@itemize -

@item 
bpo-38809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38809}: On Windows, build scripts will now recognize and use python.exe
from an active virtual env.

@item 
bpo-38684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38684}: Fix _hashlib build when Blake2 is disabled, but OpenSSL
supports it.

@item 
bpo-38468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38468}: Misc/python-config.in now uses @code{getvar()} for all still
existing @code{sysconfig.get_config_var()} calls. Patch by Joannah Nanjekye.

@item 
bpo-37415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37415}: Fix stdatomic.h header check for ICC compiler: the ICC
implementation lacks atomic_uintptr_t type which is needed by Python.

@item 
bpo-38301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38301}: In Solaris family, we must be sure to use @code{-D_REENTRANT}.
Patch by Jesús Cea Avión.

@item 
bpo-36002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36002}: Locate @code{llvm-profdata} and @code{llvm-ar} binaries using
@code{AC_PATH_TOOL} rather than @code{AC_PATH_TARGET_TOOL}.

@item 
bpo-37936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37936}: The @code{.gitignore} file systematically keeps "rooted", with
a non-trailing slash, all the rules that are meant to apply to files in a
specific place in the repo.  Previously, when the intended file to ignore
happened to be at the root of the repo, we'd most often accidentally also
ignore files and directories with the same name anywhere in the tree.

@item 
bpo-37760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37760}: The @code{Tools/unicode/makeunicodedata.py} script, which is
used for converting information from the Unicode Character Database into
generated code and data used by the methods of @ref{435,,str} and by the
@ref{104,,unicodedata} module, now handles each character's data as a
@code{dataclass} with named attributes, rather than a length-18 list of
different fields.

@item 
bpo-37936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37936}: The @code{.gitignore} file no longer applies to any files that
are in fact tracked in the Git repository.  Patch by Greg Price.

@item 
bpo-37725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37725}: Change "clean" makefile target to also clean the program guided
optimization (PGO) data.  Previously you would have to use "make clean"
and "make profile-removal", or "make clobber".

@item 
bpo-37707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37707}: Mark some individual tests to skip when --pgo is used.  The
tests marked increase the PGO task time significantly and likely don't
help improve optimization of the final executable.

@item 
bpo-36044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36044}: Reduce the number of unit tests run for the PGO generation
task.  This speeds up the task by a factor of about 15x.  Running the full
unit test suite is slow.  This change may result in a slightly less
optimized build since not as many code branches will be executed.  If you
are willing to wait for the much slower build, the old behavior can be
restored using './configure [..] PROFILE_TASK="-m test --pgo-extended"'.
We make no guarantees as to which PGO task set produces a faster build.
Users who care should run their own relevant benchmarks as results can
depend on the environment, workload, and compiler tool chain.

@item 
bpo-37468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37468}: @code{make install} no longer installs @code{wininst-*.exe} files
used by distutils bdist_wininst: bdist_wininst only works on Windows.

@item 
bpo-37189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37189}: Many @code{PyRun_@var{XXX}()} functions like
@ref{1969,,PyRun_String()} were no longer exported in @code{libpython38.dll} by
mistake. Export them again to fix the ABI compatibility.

@item 
bpo-25361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25361}: Enables use of SSE2 instructions in Windows 32-bit build.

@item 
bpo-36210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36210}: Update optional extension module detection for AIX. ossaudiodev
and spwd are not applicable for AIX, and are no longer reported as
missing. 3rd-party packaging of ncurses (with ASIS support) conflicts with
officially supported AIX curses library, so configure AIX to use
libcurses.a. However, skip trying to build _curses_panel.

patch by M Felt
@end itemize

@node Windows<41>,macOS<34>,Build<46>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id412}@anchor{196a}
@subsubsection Windows



@itemize -

@item 
bpo-38589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38589}: Fixes HTML Help shortcut when Windows is not installed to C
drive

@item 
bpo-38453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38453}: Ensure ntpath.realpath() correctly resolves relative paths.

@item 
bpo-38519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38519}: Restores the internal C headers that were missing from the
nuget.org and Microsoft Store packages.

@item 
bpo-38492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38492}: Remove @code{pythonw.exe} dependency on the Microsoft C++ runtime.

@item 
bpo-38344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38344}: Fix error message in activate.bat

@item 
bpo-38359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38359}: Ensures @code{pyw.exe} launcher reads correct registry key.

@item 
bpo-38355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38355}: Fixes @code{ntpath.realpath} failing on @code{sys.executable}.

@item 
bpo-38117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38117}: Update bundled OpenSSL to 1.1.1d

@item 
bpo-38092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38092}: Reduce overhead when using multiprocessing in a Windows virtual
environment.

@item 
bpo-38133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38133}: Allow py.exe launcher to locate installations from the
Microsoft Store and improve display of active virtual environments.

@item 
bpo-38114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38114}: The @code{pip.ini} is no longer included in the Nuget package.

@item 
bpo-32592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32592}: Set Windows 8 as the minimum required version for API support

@item 
bpo-36634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36634}: @ref{1c0,,os.cpu_count()} now returns active processors rather than
maximum processors.

@item 
bpo-36634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36634}: venv activate.bat now works when the existing variables contain
double quote characters.

@item 
bpo-38081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38081}: Prevent error calling @ref{222,,os.path.realpath()} on @code{'NUL'}.

@item 
bpo-38087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38087}: Fix case sensitivity in test_pathlib and test_ntpath.

@item 
bpo-38088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38088}: Fixes distutils not finding vcruntime140.dll with only the v142
toolset installed.

@item 
bpo-37283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37283}: Ensure command-line and unattend.xml setting override
previously detected states in Windows installer.

@item 
bpo-38030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38030}: Fixes @ref{48a,,os.stat()} failing for block devices on Windows

@item 
bpo-38020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38020}: Fixes potential crash when calling @ref{90d,,os.readlink()} (or
indirectly through @ref{222,,realpath()}) on a file that is not a
supported link.

@item 
bpo-37705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37705}: Improve the implementation of @code{winerror_to_errno()}.

@item 
bpo-37549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37549}: @ref{196b,,os.dup()} no longer fails for standard streams on Windows
7.

@item 
bpo-1311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1311}: The @code{nul} file on Windows now returns True from
@ref{9fc,,exists()} and a valid result from @ref{48a,,os.stat()} with
@code{S_IFCHR} set.

@item 
bpo-9949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9949}: Enable support for following symlinks in @code{os.realpath()}.

@item 
bpo-37834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37834}: Treat all name surrogate reparse points on Windows in
@ref{48b,,os.lstat()} and other reparse points as regular files in
@ref{48a,,os.stat()}.

@item 
bpo-36266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36266}: Add the module name in the formatted error message when DLL
load fail happens during module import in
@code{_PyImport_FindSharedFuncptrWindows()}. Patch by Srinivas Nyayapati.

@item 
bpo-25172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25172}: Trying to import the @code{crypt} module on Windows will
result in an @ref{40f,,ImportError} with a message explaining that the module
isn't supported on Windows. On other platforms, if the underlying
@code{_crypt} module is not available, the ImportError will include a message
explaining the problem.

@item 
bpo-37778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37778}: Fixes the icons used for file associations to the Microsoft
Store package.

@item 
bpo-37734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37734}: Fix use of registry values to launch Python from Microsoft
Store app.

@item 
bpo-37702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37702}: Fix memory leak on Windows in creating an SSLContext object or
running @code{urllib.request.urlopen('https://...')}.

@item 
bpo-37672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37672}: Switch Windows Store package's pip to use bundled
@code{pip.ini} instead of 
@geindex PIP_USER
@geindex variable d'environnement; PIP_USER
@code{PIP_USER} variable.

@item 
bpo-10945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10945}: Officially drop support for creating bdist_wininst installers
on non-Windows systems.

@item 
bpo-37445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37445}: Include the @code{FORMAT_MESSAGE_IGNORE_INSERTS} flag in
@code{FormatMessageW()} calls.

@item 
bpo-37369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37369}: Fixes path for @ref{3af,,sys.executable} when running from the
Microsoft Store.

@item 
bpo-37380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37380}: Don't collect unfinished processes with @code{subprocess._active}
on Windows to cleanup later. Patch by Ruslan Kuprieiev.

@item 
bpo-37351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37351}: Removes libpython38.a from standard Windows distribution.

@item 
bpo-35360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35360}: Update Windows builds to use SQLite 3.28.0.

@item 
bpo-37267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37267}: On Windows, @ref{196b,,os.dup()} no longer creates an inheritable fd
when handling a character file.

@item 
bpo-36779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36779}: Ensure @code{time.tzname} is correct on Windows when the active
code page is set to CP_UTF7 or CP_UTF8.

@item 
bpo-32587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32587}: Make @ref{196c,,winreg.REG_MULTI_SZ} support zero-length strings.

@item 
bpo-28269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28269}: Replace use of @code{strcasecmp()} for the system function
@code{_stricmp()}. Patch by Minmin Gong.

@item 
bpo-36590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36590}: Add native Bluetooth RFCOMM support to socket module.
@end itemize

@node macOS<34>,IDLE<32>,Windows<41>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id413}@anchor{196d}
@subsubsection macOS



@itemize -

@item 
bpo-38117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38117}: Updated OpenSSL to 1.1.1d in macOS installer.

@item 
bpo-38089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38089}: Move Azure Pipelines to latest VM versions and make macOS tests
optional

@item 
bpo-18049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18049}: Increase the default stack size of threads from 5MB to 16MB on
macOS, to match the stack size of the main thread. This avoids crashes on
deep recursion in threads.

@item 
bpo-34602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34602}: Avoid test suite failures on macOS by no longer calling
resource.setrlimit to increase the process stack size limit at runtime.
The runtime change is no longer needed since the interpreter is being
built with a larger default stack size.

@item 
bpo-35360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35360}: Update macOS installer to use SQLite 3.28.0.

@item 
bpo-34631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34631}: Updated OpenSSL to 1.1.1c in macOS installer.
@end itemize

@node IDLE<32>,Tools/Demos<21>,macOS<34>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id414}@anchor{196e}
@subsubsection IDLE



@itemize -

@item 
bpo-26353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26353}: Stop adding newline when saving an IDLE shell window.

@item 
bpo-4630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4630}: Add an option to toggle IDLE's cursor blink for shell, editor,
and output windows.  See Settings, General, Window Preferences, Cursor
Blink. Patch by Zackery Spytz.

@item 
bpo-38598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38598}: Do not try to compile IDLE shell or output windows

@item 
bpo-36698@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36698}: IDLE no longer fails when write non-encodable characters to
stderr.  It now escapes them with a backslash, as the regular Python
interpreter. Added the @code{errors} field to the standard streams.

@item 
bpo-35379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35379}: When exiting IDLE, catch any AttributeError.  One happens when
EditorWindow.close is called twice.  Printing a traceback, when IDLE is
run from a terminal, is useless and annoying.

@item 
bpo-38183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38183}: To avoid problems, test_idle ignores the user config directory.
It no longer tries to create or access .idlerc or any files within. Users
must run IDLE to discover problems with saving settings.

@item 
bpo-38077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38077}: IDLE no longer adds 'argv' to the user namespace when
initializing it.  This bug only affected 3.7.4 and 3.8.0b2 to 3.8.0b4.

@item 
bpo-38041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38041}: Shell restart lines now fill the window width, always start
with '=', and avoid wrapping unnecessarily. The line will still wrap if
the included file name is long relative to the width.

@item 
bpo-35771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35771}: To avoid occasional spurious test_idle failures on slower
machines, increase the @code{hover_delay} in test_tooltip.

@item 
bpo-37824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37824}: Properly handle user input warnings in IDLE shell. Cease
turning SyntaxWarnings into SyntaxErrors.

@item 
bpo-37929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37929}: IDLE Settings dialog now closes properly when there is no shell
window.

@item 
bpo-37902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37902}: Add mousewheel scrolling for IDLE module, path, and stack
browsers. Patch by George Zhang.

@item 
bpo-37849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37849}: Fixed completions list appearing too high or low when shown
above the current line.

@item 
bpo-36419@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36419}: Refactor IDLE autocomplete and improve testing.

@item 
bpo-37748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37748}: Reorder the Run menu.  Put the most common choice, Run Module,
at the top.

@item 
bpo-37692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37692}: Improve highlight config sample with example shell interaction
and better labels for shell elements.

@item 
bpo-37628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37628}: Settings dialog no longer expands with font size.

@item 
bpo-37627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37627}: Initialize the Customize Run dialog with the command line
arguments most recently entered before.  The user can optionally edit
before submitting them.

@item 
bpo-33610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33610}: Fix code context not showing the correct context when first
toggled on.

@item 
bpo-37530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37530}: Optimize code context to reduce unneeded background activity.
Font and highlight changes now occur along with text changes instead of
after a random delay.

@item 
bpo-27452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27452}: Cleanup @code{config.py} by inlining @code{RemoveFile} and
simplifying the handling of @code{file} in @code{CreateConfigHandlers}.

@item 
bpo-37325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37325}: Fix tab focus traversal order for help source and custom run
dialogs.

@item 
bpo-37321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37321}: Both subprocess connection error messages now refer to the
'Startup failure' section of the IDLE doc.

@item 
bpo-17535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17535}: Add optional line numbers for IDLE editor windows.  Windows
open without line numbers unless set otherwise in the General tab of the
configuration dialog.

@item 
bpo-26806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26806}: To compensate for stack frames added by IDLE and avoid possible
problems with low recursion limits, add 30 to limits in the user code
execution process.  Subtract 30 when reporting recursion limits to make
this addition mostly transparent.

@item 
bpo-37177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37177}: Properly 'attach' search dialogs to their main window so that
they behave like other dialogs and do not get hidden behind their main
window.

@item 
bpo-37039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37039}: Adjust "Zoom Height" to individual screens by momentarily
maximizing the window on first use with a particular screen.  Changing
screen settings may invalidate the saved height.  While a window is
maximized, "Zoom Height" has no effect.

@item 
bpo-35763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35763}: Make calltip reminder about '/' meaning positional-only less
obtrusive by only adding it when there is room on the first line.

@item 
bpo-5680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5680}: Add 'Run... Customized' to the Run menu to run a module with
customized settings.  Any 'command line arguments' entered are added to
sys.argv. One can suppress the normal Shell main module restart.

@item 
bpo-36390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36390}: Gather Format menu functions into format.py.  Combine
paragraph.py, rstrip.py, and format methods from editor.py.
@end itemize

@node Tools/Demos<21>,C API<45>,IDLE<32>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id415}@anchor{196f}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-38118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38118}: Update Valgrind suppression file to ignore a false alarm in
@ref{1970,,PyUnicode_Decode()} when using GCC builtin strcmp().

@item 
bpo-38347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38347}: pathfix.py: Assume all files that end on '.py' are Python
scripts when working recursively.

@item 
bpo-37803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37803}: pdb's @code{--help} and @code{--version} long options now work.

@item 
bpo-37942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37942}: Improve ArgumentClinic converter for floats.

@item 
bpo-37704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37704}: Remove @code{Tools/scripts/h2py.py}: use cffi to access a C API in
Python.

@item 
bpo-37675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37675}: 2to3 now works when run from a zipped standard library.

@item 
bpo-37034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37034}: Argument Clinic now uses the argument name on errors with
keyword-only argument instead of their position. Patch contributed by Rémi
Lapeyre.

@item 
bpo-37064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37064}: Add option -k to pathscript.py script: preserve shebang flags.
Add option -a to pathscript.py script: add flags.
@end itemize

@node C API<45>,,Tools/Demos<21>,Python 3 9 0 alpha 1
@anchor{whatsnew/changelog id416}@anchor{1971}
@subsubsection C API



@itemize -

@item 
bpo-37633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37633}: Re-export some function compatibility wrappers for macros in
@code{pythonrun.h}.

@item 
bpo-38644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38644}: Provide @ref{960,,Py_EnterRecursiveCall()} and
@ref{961,,Py_LeaveRecursiveCall()} as regular functions for the limited API.
Previously, there were defined as macros, but these macros didn't work
with the limited API which cannot access @code{PyThreadState.recursion_depth}
field. Remove @code{_Py_CheckRecursionLimit} from the stable ABI.

@item 
bpo-38650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38650}: The global variable @ref{96f,,PyStructSequence_UnnamedField} is
now a constant and refers to a constant string.

@item 
bpo-38540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38540}: Fixed possible leak in @ref{1972,,PyArg_Parse()} and similar
functions for format units @code{"es#"} and @code{"et#"} when the macro
@code{PY_SSIZE_T_CLEAN} is not defined.

@item 
bpo-38395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38395}: Fix a crash in @ref{a40,,weakref.proxy} objects due to incorrect
lifetime management when calling some associated methods that may delete
the last reference to object being referenced by the proxy. Patch by Pablo
Galindo.

@item 
bpo-36389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36389}: The @code{_PyObject_CheckConsistency()} function is now also
available in release mode. For example, it can be used to debug a crash in
the @code{visit_decref()} function of the GC.

@item 
bpo-38266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38266}: Revert the removal of PyThreadState_DeleteCurrent() with
documentation.

@item 
bpo-38303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38303}: Update audioop extension module to use the stable ABI
(PEP-384). Patch by Tyler Kieft.

@item 
bpo-38234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38234}: @code{Py_SetPath()} now sets @ref{3af,,sys.executable} to the
program full path (@ref{3ae,,Py_GetProgramFullPath()}) rather than to the
program name (@ref{3b0,,Py_GetProgramName()}).

@item 
bpo-38234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38234}: Python ignored arguments passed to @code{Py_SetPath()},
@code{Py_SetPythonHome()} and @code{Py_SetProgramName()}: fix Python
initialization to use specified arguments.

@item 
bpo-38205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38205}: The @ref{ba3,,Py_UNREACHABLE()} macro now calls
@ref{970,,Py_FatalError()}.

@item 
bpo-38140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=38140}: Make dict and weakref offsets opaque for C heap types by
passing the offsets through PyMemberDef

@item 
bpo-15088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15088}: The C function @code{PyGen_NeedsFinalizing} has been removed. It
was not documented, tested or used anywhere within CPython after the
implementation of 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}. Patch by Joannah Nanjekye. (Patch by Joannah
Nanjekye)

@item 
bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}: Options added by @code{PySys_AddXOption()} are now handled the
same way than @code{PyConfig.xoptions} and command line @code{-X} options.

@item 
bpo-37926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37926}: Fix a crash in @code{PySys_SetArgvEx(0, NULL, 0)}.

@item 
bpo-37879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37879}: Fix subtype_dealloc to suppress the type decref when the base
type is a C heap type

@item 
bpo-37645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37645}: Add @code{_PyObject_FunctionStr()} to get a user-friendly
string representation of a function-like object. Patch by Jeroen Demeyer.

@item 
bpo-29548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29548}: The functions @code{PyEval_CallObject}, @code{PyEval_CallFunction},
@code{PyEval_CallMethod} and @code{PyEval_CallObjectWithKeywords} are
deprecated. Use @ref{393,,PyObject_Call()} and its variants instead.

@item 
bpo-37151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37151}: @code{PyCFunction_Call} is now a deprecated alias of
@ref{393,,PyObject_Call()}.

@item 
bpo-37540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37540}: The vectorcall protocol now requires that the caller passes
only strings as keyword names.

@item 
bpo-37207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37207}: The vectorcall protocol is now enabled for @code{type} objects:
set @code{tp_vectorcall} to a vectorcall function to be used instead of
@code{tp_new} and @code{tp_init} when calling the class itself.

@item 
bpo-21120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21120}: Exclude Python-ast.h, ast.h and asdl.h from the limited API.

@item 
bpo-37483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37483}: Add new function @code{_PyObject_CallOneArg} for calling an object
with one positional argument.

@item 
bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}: Add @ref{1973,,PyConfig_SetWideStringList()} function.

@item 
bpo-37337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37337}: Add fast functions for calling methods:
@code{_PyObject_VectorcallMethod()},
@code{_PyObject_CallMethodNoArgs()} and
@code{_PyObject_CallMethodOneArg()}.

@item 
bpo-28805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28805}: The @ref{15b0,,METH_FASTCALL} calling convention has been
documented.

@item 
bpo-37221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37221}: The new function @code{PyCode_NewWithPosOnlyArgs()} allows to
create code objects like @code{PyCode_New()}, but with an extra
`posonlyargcount' parameter for indicating the number of positonal-only
arguments.

@item 
bpo-37215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37215}: Fix dtrace issue introduce by bpo-36842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36842}

@item 
bpo-37194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37194}: Add a new public @ref{392,,PyObject_CallNoArgs()} function to the
C API: call a callable Python object without any arguments. It is the most
efficient way to call a callback without any argument. On x86-64, for
example, @code{PyObject_CallFunctionObjArgs(func, NULL)} allocates 960 bytes
on the stack per call, whereas @code{PyObject_CallNoArgs(func)} only
allocates 624 bytes per call.

@item 
bpo-37170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37170}: Fix the cast on error in
@ref{1974,,PyLong_AsUnsignedLongLongMask()}.

@item 
bpo-35381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35381}: Convert posixmodule.c statically allocated types
@code{DirEntryType} and @code{ScandirIteratorType} to heap-allocated types.

@item 
bpo-34331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34331}: Use singular/plural noun in error message when instantiating an
abstract class with non-overridden abstract method(s).
@end itemize

@node Python 3 8 0 beta 1,Python 3 8 0 alpha 4,Python 3 9 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-8-0-beta-1}@anchor{1975}
@subsection Python 3.8.0 beta 1


`Release date: 2019-06-04'

@menu
* Security: Security<32>. 
* Core and Builtins: Core and Builtins<48>. 
* Library: Library<47>. 
* Documentation: Documentation<42>. 
* Tests: Tests<44>. 
* Build: Build<47>. 
* Windows: Windows<42>. 
* macOS: macOS<35>. 
* IDLE: IDLE<33>. 
* Tools/Demos: Tools/Demos<22>. 
* C API: C API<46>. 

@end menu

@node Security<32>,Core and Builtins<48>,,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id417}@anchor{1976}
@subsubsection Security



@itemize -

@item 
bpo-35907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35907}: 
@geindex Common Vulnerabilities and Exposures; CVE 2019-9948
CVE 2019-9948@footnote{https://www.cve.org/CVERecord?id=CVE-2019-9948}: Avoid file reading by disallowing
@code{local-file://} and @code{local_file://} URL schemes in
@code{URLopener().open()} and @code{URLopener().retrieve()} of
@ref{10a,,urllib.request}.

@item 
bpo-33529@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33529}: Prevent fold function used in email header encoding from
entering infinite loop when there are too many non-ASCII characters in a
header.

@item 
bpo-33164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33164}: Updated blake2 implementation which uses secure memset
implementation provided by platform.
@end itemize

@node Core and Builtins<48>,Library<47>,Security<32>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id418}@anchor{1977}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-35814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35814}: Allow unpacking in the right hand side of annotated
assignments. In particular, @code{t: Tuple[int, ...] = x, y, *z} is now
allowed.

@item 
bpo-37126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37126}: All structseq objects are now tracked by the garbage collector.
Patch by Pablo Galindo.

@item 
bpo-37122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37122}: Make the `co_argcount' attribute of code objects represent the
total number of positional arguments (including positional-only
arguments). The value of `co_posonlyargcount' can be used to distinguish
which arguments are positional only, and the difference (`co_argcount' -
`co_posonlyargcount') is the number of positional-or-keyword arguments.
Patch by Pablo Galindo.

@item 
bpo-20092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20092}: Constructors of @ref{254,,int}, @ref{2eb,,float} and
@ref{2ec,,complex} will now use the @ref{707,,__index__()} special
method, if available and the corresponding method @ref{706,,__int__()},
@ref{9ba,,__float__()} or @ref{5d1,,__complex__()} is not available.

@item 
bpo-37087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37087}: Add native thread ID (TID) support to OpenBSD.

@item 
bpo-26219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26219}: Implemented per opcode cache mechanism and @code{LOAD_GLOBAL}
instruction use it. @code{LOAD_GLOBAL} is now about 40% faster. Contributed
by Yury Selivanov, and Inada Naoki.

@item 
bpo-37072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37072}: Fix crash in PyAST_FromNodeObject() when flags is NULL.

@item 
bpo-37029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37029}: Freeing a great many small objects could take time quadratic in
the number of arenas, due to using linear search to keep @code{obmalloc.c}'s
list of usable arenas sorted by order of number of free memory pools.
This is accomplished without search now, leaving the worst-case time
linear in the number of arenas.  For programs where this quite visibly
matters (typically with more than 100 thousand small objects alive
simultaneously), this can greatly reduce the time needed to release their
memory.

@item 
bpo-26423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26423}: Fix possible overflow in @code{wrap_lenfunc()} when @code{sizeof(long)
< sizeof(Py_ssize_t)} (e.g., 64-bit Windows).

@item 
bpo-37050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37050}: Improve the AST for "debug" f-strings, which use '=' to print
out the source of the expression being evaluated.  Delete expr_text from
the FormattedValue node, and instead use a Constant string node (possibly
merged with adjacent constant expressions inside the f-string).

@item 
bpo-22385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22385}: The @code{bytes.hex}, @code{bytearray.hex}, and @code{memoryview.hex}
methods as well as the @code{binascii.hexlify} and @code{b2a_hex} functions now
have the ability to include an optional separator between hex bytes.  This
functionality was inspired by MicroPython's hexlify implementation.

@item 
bpo-26836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26836}: Add @ref{9f9,,os.memfd_create()}.

@item 
bpo-37032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37032}: Added new @code{replace()} method to the code type
(@ref{2dd,,types.CodeType}).

@item 
bpo-37007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37007}: Implement @ref{a1b,,socket.if_nameindex()},
@ref{a1c,,socket.if_nametoindex()}, and @ref{a1d,,socket.if_indextoname()} on
Windows.

@item 
bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}: @ref{345,,PyErr_WriteUnraisable()} now creates a traceback object
if there is no current traceback. Moreover, call
@ref{3eb,,PyErr_NormalizeException()} and @ref{1978,,PyException_SetTraceback()}
to normalize the exception value. Ignore any error.

@item 
bpo-36878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36878}: Only accept text after @code{# type: ignore} if the first
character is ASCII. This is to disallow things like @code{# type: ignoreé}.

@item 
bpo-36878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36878}: Store text appearing after a @code{# type: ignore} comment in the
AST. For example a type ignore like @code{# type: ignore[E1000]} will have
the string @code{"[E1000]"} stored in its AST node.

@item 
bpo-2180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2180}: Treat line continuation at EOF as a @code{SyntaxError} by Anthony
Sottile.

@item 
bpo-36907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36907}: Fix a crash when calling a C function with a keyword dict
(@code{f(**kwargs)}) and changing the dict @code{kwargs} while that function is
running.

@item 
bpo-36946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36946}: Fix possible signed integer overflow when handling slices.

@item 
bpo-36826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36826}: Add NamedExpression kind support to ast_unparse.c

@item 
bpo-1875@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1875}: A @ref{18b,,SyntaxError} is now raised if a code blocks that will be
optimized away (e.g. if conditions that are always false) contains syntax
errors. Patch by Pablo Galindo.

@item 
bpo-36027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36027}: Allow computation of modular inverses via three-argument
@code{pow}: the second argument is now permitted to be negative in the case
where the first and third arguments are relatively prime.

@item 
bpo-36861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36861}: Update the Unicode database to version 12.1.0.

@item 
bpo-28866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28866}: Avoid caching attributes of classes which type defines mro() to
avoid a hard cache invalidation problem.

@item 
bpo-36851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36851}: The @code{FrameType} stack is now correctly cleaned up if the
execution ends with a return and the stack is not empty.

@item 
bpo-34616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34616}: The @code{compile()} builtin functions now support the
@code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} flag,  which allow to compile sources
that  contains top-level @code{await}, @code{async with} or @code{async for}. This
is useful to evaluate async-code from with an already async functions; for
example in a custom REPL.

@item 
bpo-36842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36842}: Implement PEP 578, adding sys.audit, io.open_code and related
APIs.

@item 
bpo-27639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27639}: Correct return type for UserList slicing operations. Patch by
Michael Blahay, Erick Cervantes, and vaultah

@item 
bpo-36737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36737}: Move PyRuntimeState.warnings into per-interpreter state (via
"module state").

@item 
bpo-36793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36793}: Removed @code{__str__} implementations from builtin types
@ref{451,,bool}, @ref{254,,int}, @ref{2eb,,float}, @ref{2ec,,complex} and few
classes from the standard library. They now inherit @code{__str__()} from
@ref{a7a,,object}.

@item 
bpo-36817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36817}: Add a @code{=} feature f-strings for debugging. This can precede
@code{!s}, @code{!r}, or @code{!a}. It produces the text of the expression,
followed by an equal sign, followed by the repr of the value of the
expression. So @code{f'@{3*9+15=@}'} would be equal to the string
@code{'3*9+15=42'}.  If @code{=} is specified, the default conversion is set to
@code{!r}, unless a format spec is given, in which case the formatting
behavior is unchanged, and __format__ will be used.

@item 
bpo-24048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24048}: Save the live exception during import.c's @code{remove_module()}.

@item 
bpo-27987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27987}: pymalloc returns memory blocks aligned by 16 bytes, instead of
8 bytes, on 64-bit platforms to conform x86-64 ABI. Recent compilers
assume this alignment more often. Patch by Inada Naoki.

@item 
bpo-36601@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36601}: A long-since-meaningless check for @code{getpid() == main_pid} was
removed from Python's internal C signal handler.

@item 
bpo-36594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36594}: Fix incorrect use of @code{%p} in format strings. Patch by Zackery
Spytz.

@item 
bpo-36045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36045}: @code{builtins.help()} now prefixes @code{async} for async functions.

@item 
bpo-36084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36084}: Add native thread ID (TID) to threading.Thread objects
(supported platforms: Windows, FreeBSD, Linux, macOS)

@item 
bpo-36035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36035}: Added fix for broken symlinks in combination with pathlib

@item 
bpo-35983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35983}: Added new trashcan macros to deal with a double deallocation
that could occur when the @code{tp_dealloc} of a subclass calls the
@code{tp_dealloc} of a base class and that base class uses the trashcan
mechanism. Patch by Jeroen Demeyer.

@item 
bpo-20602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20602}: Do not clear @ref{677,,sys.flags} and @ref{1979,,sys.float_info}
during shutdown. Patch by Zackery Spytz.

@item 
bpo-26826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26826}: Expose @code{copy_file_range()} as a low level API in the
@ref{a0,,os} module.

@item 
bpo-32388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32388}: Remove cross-version binary compatibility requirement in
tp_flags.

@item 
bpo-31862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31862}: Port binascii to PEP 489 multiphase initialization. Patch by
Marcel Plch.
@end itemize

@node Library<47>,Documentation<42>,Core and Builtins<48>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id419}@anchor{197a}
@subsubsection Library



@itemize -

@item 
bpo-37128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37128}: Added @ref{6bb,,math.perm()}.

@item 
bpo-37120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37120}: Add SSLContext.num_tickets to control the number of TLSv1.3
session tickets.

@item 
bpo-12202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12202}: Fix the error handling in
@code{msilib.SummaryInformation.GetProperty()}. Patch by Zackery Spytz.

@item 
bpo-26835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26835}: The fcntl module now contains file sealing constants for
sealing of memfds.

@item 
bpo-29262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29262}: Add @code{get_origin()} and @code{get_args()} introspection helpers
to @code{typing} module.

@item 
bpo-12639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12639}: @code{msilib.Directory.start_component()} no longer fails if
`keyfile' is not @code{None}.

@item 
bpo-36999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36999}: Add the @code{asyncio.Task.get_coro()} method to publicly expose
the tasks's coroutine object.

@item 
bpo-35246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35246}: Make @ref{a65,,asyncio.create_subprocess_exec()} accept path-like
arguments.

@item 
bpo-35279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35279}: Change default `max_workers' of @code{ThreadPoolExecutor} from
@code{cpu_count() * 5} to @code{min(32, cpu_count() + 4)}.  Previous value was
unreasonably large on many cores machines.

@item 
bpo-37076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37076}: @ref{194,,_thread.start_new_thread()} now logs uncaught exception
raised by the function using @ref{1f4,,sys.unraisablehook()}, rather than
@ref{7f5,,sys.excepthook()}, so the hook gets access to the function which
raised the exception.

@item 
bpo-33725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33725}: On macOS, the @ref{93,,multiprocessing} module now uses `spawn'
start method by default.

@item 
bpo-37054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37054}: Fix destructor @code{_pyio.BytesIO} and
@code{_pyio.TextIOWrapper}: initialize their @code{_buffer} attribute as
soon as possible (in the class body), because it's used by @code{__del__()}
which calls @code{close()}.

@item 
bpo-37058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37058}: PEP 544: Add @code{Protocol} and @code{@@runtime_checkable} to the
@code{typing} module.

@item 
bpo-36933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36933}: The functions @code{sys.set_coroutine_wrapper} and
@code{sys.get_coroutine_wrapper} that were deprecated and marked for removal
in 3.8 have been removed.

@item 
bpo-37047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37047}: Handle late binding and attribute access in
@ref{a39,,unittest.mock.AsyncMock} setup for autospeccing. Document newly
implemented async methods in @ref{e7a,,unittest.mock.MagicMock}.

@item 
bpo-37049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37049}: PEP 589: Add @code{TypedDict} to the @code{typing} module.

@item 
bpo-37046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37046}: PEP 586: Add @code{Literal} to the @code{typing} module.

@item 
bpo-37045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37045}: PEP 591: Add @code{Final} qualifier and @code{@@final} decorator to
the @code{typing} module.

@item 
bpo-37035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37035}: Don't log OSError based exceptions if a fatal error has
occurred in asyncio transport. Peer can generate almost any OSError, user
cannot avoid these exceptions by fixing own code. Errors are still
propagated to user code, it's just logging them is pointless and pollute
asyncio logs.

@item 
bpo-37001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37001}: @ref{197b,,symtable.symtable()} now accepts the same input types for
source code as the built-in @ref{190,,compile()} function. Patch by Dino
Viehland.

@item 
bpo-37028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37028}: Implement asyncio REPL

@item 
bpo-37027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37027}: Return safe to use proxy socket object from
transport.get_extra_info('socket')

@item 
bpo-32528@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32528}: Make asyncio.CancelledError a BaseException.

This will address the common mistake many asyncio users make: an "except
Exception" clause breaking Tasks cancellation.

In addition to this change, we stop inheriting asyncio.TimeoutError and
asyncio.InvalidStateError from their concurrent.futures.* counterparts.
There's no point for these exceptions to share the inheritance chain.

@item 
bpo-1230540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1230540}: Add a new @ref{835,,threading.excepthook()} function which handles
uncaught @ref{a2b,,threading.Thread.run()} exception. It can be overridden to
control how uncaught @ref{a2b,,threading.Thread.run()} exceptions are handled.

@item 
bpo-36996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36996}: Handle @ref{e7b,,unittest.mock.patch()} used as a decorator on async
functions.

@item 
bpo-37008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37008}: Add support for calling @ref{7c2,,next()} with the mock resulting
from @ref{1693,,unittest.mock.mock_open()}

@item 
bpo-27737@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27737}: Allow whitespace only header encoding in @code{email.header} - by
Batuhan Taskaya

@item 
bpo-36969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36969}: PDB command @code{args} now  display positional only arguments.
Patch contributed by Rémi Lapeyre.

@item 
bpo-36969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36969}: PDB command @code{args} now  display keyword only arguments. Patch
contributed by Rémi Lapeyre.

@item 
bpo-36983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36983}: Add missing names to @code{typing.__all__}: @code{ChainMap},
@code{ForwardRef}, @code{OrderedDict} - by Anthony Sottile.

@item 
bpo-36972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36972}: Add SupportsIndex protocol to the typing module to allow type
checking to detect classes that can be passed to @code{hex()}, @code{oct()} and
@code{bin()}.

@item 
bpo-32972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32972}: Implement @code{unittest.IsolatedAsyncioTestCase} to help testing
asyncio-based code.

@item 
bpo-36952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36952}: @ref{7e9,,fileinput.input()} and @ref{721,,fileinput.FileInput}
`bufsize' argument has been removed (was deprecated and ignored since
Python 3.6), and as a result the `mode' and `openhook' arguments have
been made keyword-only.

@item 
bpo-36952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36952}: Starting with Python 3.3, importing ABCs from
@ref{1d,,collections} is deprecated, and import should be done from
@ref{1e,,collections.abc}. Still being able to import from @ref{1d,,collections}
was marked for removal in 3.8, but has been delayed to 3.9; documentation
and @code{DeprecationWarning} clarified.

@item 
bpo-36949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36949}: Implement __repr__ for WeakSet objects.

@item 
bpo-36948@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36948}: Fix @ref{428,,NameError} in
@ref{197c,,urllib.request.URLopener.retrieve()}. Patch by Karthikeyan
Singaravelan.

@item 
bpo-33524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33524}: Fix the folding of email header when the max_line_length is 0
or None and the header contains non-ascii characters.  Contributed by
Licht Takeuchi (@@Licht-T).

@item 
bpo-24564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24564}: @ref{110e,,shutil.copystat()} now ignores @ref{197d,,errno.EINVAL} on
@ref{10e7,,os.setxattr()} which may occur when copying files on filesystems
without extended attributes support.

Original patch by Giampaolo Rodola, updated by Ying Wang.

@item 
bpo-36888@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36888}: Python child processes can now access the status of their
parent process using multiprocessing.process.parent_process

@item 
bpo-36921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36921}: Deprecate @code{@@coroutine} for sake of @code{async def}.

@item 
bpo-25652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25652}: Fix bug in @code{__rmod__} of @code{UserString} - by Batuhan Taskaya.

@item 
bpo-36916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36916}: Remove a message about an unhandled exception in a task when
writer.write() is used without await and writer.drain() fails with an
exception.

@item 
bpo-36889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36889}: Introduce @code{asyncio.Stream} class that merges
@ref{1853,,asyncio.StreamReader} and @ref{1689,,asyncio.StreamWriter}
functionality. @code{asyncio.Stream} can work in readonly, writeonly and
readwrite modes. Provide @code{asyncio.connect()},
@code{asyncio.connect_unix()}, @code{asyncio.connect_read_pipe()} and
@code{asyncio.connect_write_pipe()} factories to open
@code{asyncio.Stream} connections. Provide @code{asyncio.StreamServer}
and @code{UnixStreamServer} to serve servers with asyncio.Stream API.
Modify @ref{a66,,asyncio.create_subprocess_shell()} and
@ref{a65,,asyncio.create_subprocess_exec()} to use @code{asyncio.Stream}
instead of deprecated @code{StreamReader} and @code{StreamWriter}.
Deprecate @ref{1853,,asyncio.StreamReader} and @ref{1689,,asyncio.StreamWriter}.
Deprecate usage of private classes, e.g.
@code{asyncio.FlowControlMixing} and
@code{asyncio.StreamReaderProtocol} outside of asyncio package.

@item 
bpo-36845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36845}: Added validation of integer prefixes to the construction of IP
networks and interfaces in the ipaddress module.

@item 
bpo-23378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23378}: Add an extend action to argparser.

@item 
bpo-36867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36867}: Fix a bug making a SharedMemoryManager instance and its parent
process use two separate resource_tracker processes.

@item 
bpo-23896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23896}: Adds a grammar to lib2to3.pygram that contains exec as a
function not as statement.

@item 
bpo-36895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36895}: The function @code{time.clock()} was deprecated in 3.3 in favor of
@code{time.perf_counter()} and marked for removal in 3.8, it has removed.

@item 
bpo-35545@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35545}: Fix asyncio discarding IPv6 scopes when ensuring hostname
resolutions internally

@item 
bpo-36887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36887}: Add new function @ref{9f3,,math.isqrt()} to compute integer square
roots.

@item 
bpo-34632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34632}: Introduce the @code{importlib.metadata} module with (provisional)
support for reading metadata from third-party packages.

@item 
bpo-36878@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36878}: When using @code{type_comments=True} in @code{ast.parse}, treat @code{#
type: ignore} followed by a non-alphanumeric character and then arbitrary
text as a type ignore, instead of requiring nothing but whitespace or
another comment. This is to permit formations such as @code{# type:
ignore[E1000]}.

@item 
bpo-36778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36778}: @code{cp65001} encoding (Windows code page 65001) becomes an alias
to @code{utf_8} encoding.

@item 
bpo-36867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36867}: The multiprocessing.resource_tracker replaces the
multiprocessing.semaphore_tracker module. Other than semaphores,
resource_tracker also tracks shared_memory segments.

@item 
bpo-30262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30262}: The @code{Cache} and @code{Statement} objects of the @ref{ce,,sqlite3}
module are not exposed to the user.  Patch by Aviv Palivoda.

@item 
bpo-24538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24538}: In @code{shutil.copystat()}, first copy extended file attributes
and then file permissions, since extended attributes can only be set on
the destination while it is still writeable.

@item 
bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}: Add new @ref{1f4,,sys.unraisablehook()} function which can be
overridden to control how "unraisable exceptions" are handled. It is
called when an exception has occurred but there is no way for Python to
handle it. For example, when a destructor raises an exception or during
garbage collection (@ref{a28,,gc.collect()}).

@item 
bpo-36832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36832}: Introducing @code{zipfile.Path}, a pathlib-compatible wrapper for
traversing zip files.

@item 
bpo-36814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36814}: Fix an issue where os.posix_spawnp() would incorrectly raise a
TypeError when file_actions is None.

@item 
bpo-33110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33110}: Handle exceptions raised by functions added by
concurrent.futures add_done_callback correctly when the Future has already
completed.

@item 
bpo-26903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26903}: Limit @code{max_workers} in @code{ProcessPoolExecutor} to 61 to work
around a WaitForMultipleObjects limitation.

@item 
bpo-36813@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36813}: Fix @ref{e19,,QueueListener} to call
@code{queue.task_done()} upon stopping. Patch by Bar Harel.

@item 
bpo-36806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36806}: Forbid creation of asyncio stream objects like StreamReader,
StreamWriter, Process, and their protocols outside of asyncio package.

@item 
bpo-36802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36802}: Provide both sync and async calls for StreamWriter.write() and
StreamWriter.close()

@item 
bpo-36801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36801}: Properly handle SSL connection closing in asyncio
StreamWriter.drain() call.

@item 
bpo-36785@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36785}: Implement PEP 574 (pickle protocol 5 with out-of-band buffers).

@item 
bpo-36772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36772}: functools.lru_cache() can now be used as a straight decorator
in addition to its existing usage as a function that returns a decorator.

@item 
bpo-6584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6584}: Add a @ref{9e5,,BadGzipFile} exception to the @ref{66,,gzip}
module.

@item 
bpo-36748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36748}: Optimized write buffering in C implementation of
@code{TextIOWrapper}. Writing ASCII string to @code{TextIOWrapper} with ascii,
latin1, or utf-8 encoding is about 20% faster.  Patch by Inada Naoki.

@item 
bpo-8138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8138}: Don't mark @code{wsgiref.simple_server.SimpleServer} as
multi-threaded since @code{wsgiref.simple_server.WSGIServer} is
single-threaded.

@item 
bpo-22640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22640}: @ref{a13,,py_compile.compile()} now supports silent mode. Patch by
Joannah Nanjekye

@item 
bpo-29183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29183}: Fix double exceptions in @ref{197e,,wsgiref.handlers.BaseHandler}
by calling its @code{close()} method only
when no exception is raised.

@item 
bpo-36548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36548}: Improved the repr of regular expression flags.

@item 
bpo-36542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36542}: The signature of Python functions can now be overridden by
specifying the @code{__text_signature__} attribute.

@item 
bpo-36533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36533}: Reinitialize logging.Handler locks in forked child processes
instead of attempting to acquire them all in the parent before forking
only to be released in the child process.  The acquire/release pattern was
leading to deadlocks in code that has implemented any form of chained
logging handlers that depend upon one another as the lock acquisition
order cannot be guaranteed.

@item 
bpo-35252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35252}: Throw a TypeError instead of an AssertionError when using an
invalid type annotation with singledispatch.

@item 
bpo-35900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35900}: Allow reduction methods to return a 6-item tuple where the 6th
item specifies a custom state-setting method that's called instead of the
regular @code{__setstate__} method.

@item 
bpo-35900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35900}: enable custom reduction callback registration for functions and
classes in _pickle.c, using the new Pickler's attribute
@code{reducer_override}

@item 
bpo-36368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36368}: Fix a bug crashing SharedMemoryManager instances in interactive
sessions after a ctrl-c (KeyboardInterrupt) was sent

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix mmap fail for VxWorks

@item 
bpo-27497@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27497}: @ref{11dc,,csv.DictWriter.writeheader()} now returns the return value
of the underlying @code{csv.Writer.writerow()} method. Patch contributed by
Ashish Nitin Patil.

@item 
bpo-36239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36239}: Parsing .mo files now ignores comments starting and ending with
#-#-#-#-#.

@item 
bpo-26707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26707}: Enable plistlib to read and write binary plist files that were
created as a KeyedArchive file. Specifically, this allows the plistlib to
process 0x80 tokens as UID objects.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Add posix module support for VxWorks.

@item 
bpo-35125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35125}: Asyncio: Remove inner callback on outer cancellation in shield

@item 
bpo-35721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35721}: Fix @code{asyncio.SelectorEventLoop.subprocess_exec()} leaks
file descriptors if @code{Popen} fails and called with
@code{stdin=subprocess.PIPE}. Patch by Niklas Fiekas.

@item 
bpo-31855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31855}: @ref{1693,,unittest.mock.mock_open()} results now respects the
argument of read([size]). Patch contributed by Rémi Lapeyre.

@item 
bpo-35431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35431}: Implement @ref{6ba,,math.comb()} that returns binomial coefficient,
that computes the number of ways to choose k items from n items without
repetition and without order. Patch by Yash Aggarwal and Keller Fuchs.

@item 
bpo-26660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26660}: Fixed permission errors in
@ref{1212,,TemporaryDirectory} clean up. Previously
@code{TemporaryDirectory.cleanup()} failed when non-writeable or
non-searchable files or directories were created inside a temporary
directory.

@item 
bpo-34271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34271}: Add debugging helpers to ssl module. It's now possible to dump
key material and to trace TLS protocol. The default and stdlib contexts
also support SSLKEYLOGFILE env var.

@item 
bpo-26467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26467}: Added AsyncMock to support using unittest to mock asyncio
coroutines. Patch by Lisa Roach.

@item 
bpo-33569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33569}: dataclasses.InitVar: Exposes the type used to create the init
var.

@item 
bpo-34424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34424}: Fix serialization of messages containing encoded strings when
the policy.linesep is set to a multi-character string. Patch by Jens
Troeger.

@item 
bpo-34303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34303}: Performance of @ref{12ba,,functools.reduce()} is slightly improved.
Patch by Sergey Fedoseev.

@item 
bpo-33361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33361}: Fix a bug in @ref{197f,,codecs.StreamRecoder} where seeking might
leave old data in a buffer and break subsequent read calls. Patch by Ammar
Askar.

@item 
bpo-22454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22454}: The @ref{c3,,shlex} module now exposes @ref{a15,,shlex.join()}, the
inverse of @ref{526,,shlex.split()}. Patch by Bo Bayles.

@item 
bpo-31922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31922}: @code{asyncio.AbstractEventLoop.create_datagram_endpoint()}: Do
not connect UDP socket when broadcast is allowed. This allows to receive
replies after a UDP broadcast.

@item 
bpo-24882@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24882}: Change ThreadPoolExecutor to use existing idle threads before
spinning up new ones.

@item 
bpo-31961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31961}: Added support for bytes and path-like objects in
@ref{197,,subprocess.Popen()} on Windows.  The `args' parameter now accepts a
@ref{29d,,path-like object} if `shell' is @code{False} and a sequence containing
bytes and path-like objects. The `executable' parameter now accepts a
bytes and @ref{29d,,path-like object}. The `cwd' parameter now accepts a
bytes object. Based on patch by Anders Lorentsen.

@item 
bpo-33123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33123}: @ref{1980,,pathlib.Path.unlink} now accepts a `missing_ok'
parameter to avoid a @ref{eae,,FileNotFoundError} from being raised. Patch by
Robert Buchholz.

@item 
bpo-32941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32941}: Allow @ref{208,,mmap.mmap} objects to access the madvise() system
call (through @ref{9f6,,mmap.mmap.madvise()}).

@item 
bpo-22102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22102}: Added support for ZIP files with disks set to 0. Such files are
commonly created by builtin tools on Windows when use ZIP64 extension.
Patch by Francisco Facioni.

@item 
bpo-32515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32515}: trace.py can now run modules via python3 -m trace -t --module
module_name

@item 
bpo-32299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32299}: Changed @ref{1981,,unittest.mock.patch.dict()} to return the patched
dictionary when used as context manager. Patch by Vadim Tsander.

@item 
bpo-27141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27141}: Added a @code{__copy__()} to @code{collections.UserList} and
@code{collections.UserDict} in order to correctly implement shallow copying
of the objects. Patch by Bar Harel.

@item 
bpo-31829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31829}: @code{\r}, @code{\0} and @code{\x1a} (end-of-file on Windows) are now
escaped in protocol 0 pickles of Unicode strings. This allows to load them
without loss from files open in text mode in Python 2.

@item 
bpo-23395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23395}: @code{_thread.interrupt_main()} now avoids setting the Python
error status if the @code{SIGINT} signal is ignored or not handled by Python.
@end itemize

@node Documentation<42>,Tests<44>,Library<47>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id420}@anchor{1982}
@subsubsection Documentation



@itemize -

@item 
bpo-36896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36896}: Clarify that some types have unstable constructor signature
between Python versions.

@item 
bpo-36686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36686}: Improve documentation of the stdin, stdout, and stderr
arguments of the @code{asyncio.subprocess_exec} function to specify which
values are supported. Also mention that decoding as text is not supported.

Add a few tests to verify that the various values passed to the std*
arguments actually work.

@item 
bpo-36984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36984}: Improve version added references in @code{typing} module - by
Anthony Sottile.

@item 
bpo-36868@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36868}: What's new now mentions SSLContext.hostname_checks_common_name
instead of SSLContext.host_flags.

@item 
bpo-35924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35924}: Add a note to the @code{curses.addstr()} documentation to warn
that multiline strings can cause segfaults because of an ncurses bug.

@item 
bpo-36783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36783}: Added C API Documentation for Time_FromTimeAndFold and
PyDateTime_FromDateAndTimeAndFold as per PEP 495. Patch by Edison
Abahurire.

@item 
bpo-36797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36797}: More of the legacy distutils documentation has been either
pruned, or else more clearly marked as being retained solely until the
setuptools documentation covers it independently.

@item 
bpo-22865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22865}: Add detail to the documentation on the @code{pty.spawn} function.

@item 
bpo-35397@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35397}: Remove deprecation and document urllib.parse.unwrap(). Patch
contributed by Rémi Lapeyre.

@item 
bpo-32995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32995}: Added the context variable in glossary.

@item 
bpo-33519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33519}: Clarify that @code{copy()} is not part of the @code{MutableSequence}
ABC.

@item 
bpo-33482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33482}: Make @code{codecs.StreamRecoder.writelines} take a list of bytes.

@item 
bpo-25735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25735}: Added documentation for func factorial to indicate that returns
integer values

@item 
bpo-20285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20285}: Expand object.__doc__ (docstring) to make it clearer. Modify
pydoc.py so that help(object) lists object methods (for other classes,
help omits methods of the object base class.)
@end itemize

@node Tests<44>,Build<47>,Documentation<42>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id421}@anchor{1983}
@subsubsection Tests



@itemize -

@item 
bpo-37069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37069}: Modify test_coroutines, test_cprofile, test_generators,
test_raise, test_ssl and test_yield_from to use
@ref{1966,,test.support.catch_unraisable_exception()} rather than
@ref{1984,,test.support.captured_stderr()}.

@item 
bpo-37098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37098}: Fix test_memfd_create on older Linux Kernels.

@item 
bpo-37081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37081}: Test with OpenSSL 1.1.1c

@item 
bpo-36829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36829}: Add @ref{1966,,test.support.catch_unraisable_exception()}: context
manager catching unraisable exception using @ref{1f4,,sys.unraisablehook()}.

@item 
bpo-36915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36915}: The main regrtest process now always removes all temporary
directories of worker processes even if they crash or if they are killed
on KeyboardInterrupt (CTRL+c).

@item 
bpo-36719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36719}: "python3 -m test -jN ..." now continues the execution of next
tests when a worker process crash (CHILD_ERROR state). Previously, the
test suite stopped immediately. Use --failfast to stop at the first error.

@item 
bpo-36816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36816}: Update Lib/test/selfsigned_pythontestdotnet.pem to match
self-signed.pythontest.net's new TLS certificate.

@item 
bpo-35925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35925}: Skip httplib and nntplib networking tests when they would
otherwise fail due to a modern OS or distro with a default OpenSSL policy
of rejecting connections to servers with weak certificates.

@item 
bpo-36782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36782}: Add tests for several C API functions in the @ref{30,,datetime}
module. Patch by Edison Abahurire.

@item 
bpo-36342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36342}: Fix test_multiprocessing in test_venv if platform lacks
functioning sem_open.
@end itemize

@node Build<47>,Windows<42>,Tests<44>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id422}@anchor{1985}
@subsubsection Build



@itemize -

@item 
bpo-36721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36721}: To embed Python into an application, a new @code{--embed} option
must be passed to @code{python3-config --libs --embed} to get @code{-lpython3.8}
(link the application to libpython). To support both 3.8 and older, try
@code{python3-config --libs --embed} first and fallback to @code{python3-config
--libs} (without @code{--embed}) if the previous command fails.

Add a pkg-config @code{python-3.8-embed} module to embed Python into an
application: @code{pkg-config python-3.8-embed --libs} includes
@code{-lpython3.8}. To support both 3.8 and older, try @code{pkg-config
python-X.Y-embed --libs} first and fallback to @code{pkg-config python-X.Y
--libs} (without @code{--embed}) if the previous command fails (replace
@code{X.Y} with the Python version).

On the other hand, @code{pkg-config python3.8 --libs} no longer contains
@code{-lpython3.8}. C extensions must not be linked to libpython (except on
Android, case handled by the script); this change is backward incompatible
on purpose.

@item 
bpo-36786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36786}: "make install" now runs compileall in parallel.
@end itemize

@node Windows<42>,macOS<35>,Build<47>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id423}@anchor{1986}
@subsubsection Windows



@itemize -

@item 
bpo-36965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36965}: include of STATUS_CONTROL_C_EXIT without depending on MSC
compiler

@item 
bpo-35926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35926}: Update to OpenSSL 1.1.1b for Windows.

@item 
bpo-29883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29883}: Add Windows support for UDP transports for the Proactor Event
Loop. Patch by Adam Meily.

@item 
bpo-33407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33407}: The @ref{a92,,Py_DEPRECATED()} macro has been implemented for
MSVC.
@end itemize

@node macOS<35>,IDLE<33>,Windows<42>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id424}@anchor{1987}
@subsubsection macOS



@itemize -

@item 
bpo-36231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36231}: Support building Python on macOS without /usr/include
installed. As of macOS 10.14, system header files are only available
within an SDK provided by either the Command Line Tools or the Xcode app.
@end itemize

@node IDLE<33>,Tools/Demos<22>,macOS<35>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id425}@anchor{1988}
@subsubsection IDLE



@itemize -

@item 
bpo-35610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35610}: Replace now redundant .context_use_ps1 with .prompt_last_line.
This finishes change started in bpo-31858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31858}.

@item 
bpo-37038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37038}: Make idlelib.run runnable; add test clause.

@item 
bpo-36958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36958}: Print any argument other than None or int passed to SystemExit
or sys.exit().

@item 
bpo-36807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36807}: When saving a file, call os.fsync() so bits are flushed to e.g.
USB drive.

@item 
bpo-32411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32411}: In browser.py, remove extraneous sorting by line number since
dictionary was created in line number order.
@end itemize

@node Tools/Demos<22>,C API<46>,IDLE<33>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id426}@anchor{1989}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-37053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37053}: Handle strings like u"bar" correctly in
Tools/parser/unparse.py. Patch by Chih-Hsuan Yen.
@end itemize

@node C API<46>,,Tools/Demos<22>,Python 3 8 0 beta 1
@anchor{whatsnew/changelog id427}@anchor{198a}
@subsubsection C API



@itemize -

@item 
bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}: Implement the 
@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} "Python Initialization Configuration".

@item 
bpo-36379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36379}: Fix crashes when attempting to use the `modulo' parameter when
@code{__ipow__} is implemented in C.

@item 
bpo-37107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=37107}: Update @ref{198b,,PyObject_CallMethodObjArgs()} and
@code{_PyObject_CallMethodIdObjArgs} to use @code{_PyObject_GetMethod} to avoid
creating a bound method object in many cases. Patch by Michael J.
Sullivan.

@item 
bpo-36974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36974}: Implement 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/}: Vectorcall: a fast calling protocol for
CPython. This is a new protocol to optimize calls of custom callable
objects.

@item 
bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}: @code{Py_Main()} now returns the exitcode rather than calling
@code{Py_Exit(exitcode)} when calling @code{PyErr_Print()} if the current
exception type is @code{SystemExit}.

@item 
bpo-36922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36922}: Add new type flag @code{Py_TPFLAGS_METHOD_DESCRIPTOR} for objects
behaving like unbound methods. These are objects supporting the
optimization given by the @code{LOAD_METHOD}/@code{CALL_METHOD} opcodes. See PEP
590.

@item 
bpo-36728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36728}: The @code{PyEval_ReInitThreads()} function has been removed
from the C API. It should not be called explicitly: use
@ref{3f1,,PyOS_AfterFork_Child()} instead.
@end itemize

@node Python 3 8 0 alpha 4,Python 3 8 0 alpha 3,Python 3 8 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-8-0-alpha-4}@anchor{198c}
@subsection Python 3.8.0 alpha 4


`Release date: 2019-05-06'

@menu
* Security: Security<33>. 
* Core and Builtins: Core and Builtins<49>. 
* Library: Library<48>. 
* Documentation: Documentation<43>. 
* Tests: Tests<45>. 
* Build: Build<48>. 
* Windows: Windows<43>. 
* macOS: macOS<36>. 
* IDLE: IDLE<34>. 
* Tools/Demos: Tools/Demos<23>. 
* C API: C API<47>. 

@end menu

@node Security<33>,Core and Builtins<49>,,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id428}@anchor{198d}
@subsubsection Security



@itemize -

@item 
bpo-36742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36742}: Fixes mishandling of pre-normalization characters in
urlsplit().

@item 
bpo-30458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30458}: Address 
@geindex Common Vulnerabilities and Exposures; CVE 2019-9740
CVE 2019-9740@footnote{https://www.cve.org/CVERecord?id=CVE-2019-9740} by disallowing URL paths with embedded
whitespace or control characters through into the underlying http client
request.  Such potentially malicious header injection URLs now cause an
http.client.InvalidURL exception to be raised.

@item 
bpo-35755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35755}: @ref{49d,,shutil.which()} now uses @code{os.confstr("CS_PATH")} if
available and if the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment variable is not set.
Remove also the current directory from @code{posixpath.defpath}. On Unix,
@ref{49d,,shutil.which()} and the @ref{d5,,subprocess} module no longer search the
executable in the current directory if the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment
variable is not set.
@end itemize

@node Core and Builtins<49>,Library<48>,Security<33>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id429}@anchor{198e}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-36722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36722}: In debug build, import now also looks for C extensions compiled
in release mode and for C extensions compiled in the stable ABI.

@item 
bpo-32849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32849}: Fix Python Initialization code on FreeBSD to detect properly
when stdin file descriptor (fd 0) is invalid.

@item 
bpo-36623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36623}: Remove parser headers and related function declarations that
lack implementations after the removal of pgen.

@item 
bpo-20180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20180}: @code{dict.pop()} is now up to 33% faster thanks to Argument
Clinic. Patch by Inada Naoki.

@item 
bpo-36611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36611}: Debug memory allocators: disable serialno field by default from
debug hooks on Python memory allocators to reduce the memory footprint by
5%. Enable @ref{fe,,tracemalloc} to get the traceback where a memory block
has been allocated when a fatal memory error is logged to decide where to
put a breakpoint. Compile Python with @code{PYMEM_DEBUG_SERIALNO} defined to
get back the field.

@item 
bpo-36588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36588}: On AIX, @ref{a7b,,sys.platform} doesn't contain the major version
anymore. Always return @code{'aix'}, instead of @code{'aix3'} .. @code{'aix7'}.
Since older Python versions include the version number, it is recommended
to always use @code{sys.platform.startswith('aix')}. Contributed by M. Felt.

@item 
bpo-36549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36549}: Change str.capitalize to use titlecase for the first character
instead of uppercase.

@item 
bpo-36540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36540}: Implement 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/} (Python positional-only parameters). Patch
by Pablo Galindo.

@item 
bpo-36475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36475}: @code{PyEval_AcquireLock()} and
@code{PyEval_AcquireThread()} now terminate the current thread if called
while the interpreter is finalizing, making them consistent with
@ref{3a0,,PyEval_RestoreThread()}, @ref{a7c,,Py_END_ALLOW_THREADS()}, and
@ref{3a2,,PyGILState_Ensure()}.

@item 
bpo-36504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36504}: Fix signed integer overflow in _ctypes.c's
@code{PyCArrayType_new()}.

@item 
bpo-20844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20844}: Fix running script with encoding cookie and LF line ending may
fail on Windows.

@item 
bpo-24214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24214}: Fixed support of the surrogatepass error handler in the UTF-8
incremental decoder.

@item 
bpo-36452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36452}: Changing @code{dict} keys during iteration of the dict itself,
@code{keys()}, @code{values()}, or @code{items()} will now be detected in certain
corner cases where keys are deleted/added so that the number of keys isn't
changed. A @code{RuntimeError} will be raised after @code{len(dict)} iterations.
Contributed by Thomas Perl.

@item 
bpo-36459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36459}: Fix a possible double @code{PyMem_FREE()} due to tokenizer.c's
@code{tok_nextc()}.

@item 
bpo-36433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36433}: Fixed TypeError message in classmethoddescr_call.

@item 
bpo-36430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36430}: Fix a possible reference leak in @ref{1261,,itertools.count()}.

@item 
bpo-36440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36440}: Include node names in @code{ParserError} messages, instead of
numeric IDs. Patch by A. Skrobov.

@item 
bpo-36143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36143}: Regenerate @ref{83,,keyword} from the Grammar and Tokens file
using pgen. Patch by Pablo Galindo.

@item 
bpo-18372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18372}: Add missing @ref{14bc,,PyObject_GC_Track()} calls in the
@ref{a5,,pickle} module. Patch by Zackery Spytz.
@end itemize

@node Library<48>,Documentation<43>,Core and Builtins<49>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id430}@anchor{198f}
@subsubsection Library



@itemize -

@item 
bpo-35952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35952}: Fix pythoninfo when the compiler is missing.

@item 
bpo-28238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28238}: The @code{.find*()} methods of xml.etree.ElementTree can now
search for wildcards like @code{@{*@}tag} and @code{@{ns@}*} that match a tag in any
namespace or all tags in a namespace.  Patch by Stefan Behnel.

@item 
bpo-26978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26978}: @code{pathlib.path.link_to()} is now implemented. It creates a
hard link pointing to a path.

@item 
bpo-1613500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1613500}: @ref{721,,fileinput.FileInput} now uses the input file mode to
correctly set the output file mode (previously it was hardcoded to
@code{'w'})  when @code{inplace=True} is passed to its constructor.

@item 
bpo-36734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36734}: Fix compilation of @code{faulthandler.c} on HP-UX. Initialize
@code{stack_t current_stack} to zero using @code{memset()}.

@item 
bpo-13611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13611}: The xml.etree.ElementTree packages gained support for C14N 2.0
serialisation. Patch by Stefan Behnel.

@item 
bpo-36669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36669}: Add missing matrix multiplication operator support to
weakref.proxy.

@item 
bpo-36676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36676}: The XMLParser() in xml.etree.ElementTree provides namespace
prefix context to the parser target if it defines the callback methods
"start_ns()" and/or "end_ns()". Patch by Stefan Behnel.

@item 
bpo-36673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36673}: The TreeBuilder and XMLPullParser in xml.etree.ElementTree
gained support for parsing comments and processing instructions. Patch by
Stefan Behnel.

@item 
bpo-36650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36650}: The C version of functools.lru_cache() was treating calls with
an empty @code{**kwargs} dictionary as being distinct from calls with no
keywords at all. This did not result in an incorrect answer, but it did
trigger an unexpected cache miss.

@item 
bpo-28552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28552}: Fix @code{distutils.sysconfig} if @ref{3af,,sys.executable} is
@code{None} or an empty string: use @ref{1521,,os.getcwd()} to initialize
@code{project_base}.  Fix also the distutils build command: don't use
@ref{3af,,sys.executable} if it is @code{None} or an empty string.

@item 
bpo-35755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35755}: @ref{49d,,shutil.which()} and @code{distutils.spawn.find_executable}
now use @code{os.confstr("CS_PATH")} if available instead of
@ref{1990,,os.defpath}, if the @code{PATH} environment variable is not set.
Moreover, don't use @code{os.confstr("CS_PATH")} nor @ref{1990,,os.defpath} if
the @code{PATH} environment variable is set to an empty string.

@item 
bpo-25430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25430}: improve performance of @code{IPNetwork.__contains__()}

@item 
bpo-30485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30485}: Path expressions in xml.etree.ElementTree can now avoid
explicit namespace prefixes for tags (or the "@{namespace@}tag" notation) by
passing a default namespace with an empty string prefix.

@item 
bpo-36613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36613}: Fix @ref{a,,asyncio} wait() not removing callback if exception

@item 
bpo-36598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36598}: Fix @code{isinstance} check for Mock objects with spec when the
code is executed under tracing. Patch by Karthikeyan Singaravelan.

@item 
bpo-18748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18748}: In development mode (@ref{175,,-X} @code{dev}) and in debug build,
the @ref{1f2,,io.IOBase} destructor now logs @code{close()} exceptions. These
exceptions are silent by default in release mode.

@item 
bpo-36575@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36575}: The @code{_lsprof} module now uses internal timer same to
@code{time.perf_counter()} by default. @code{gettimeofday(2)} was used on Unix.
New timer has better resolution on most Unix platforms and timings are no
longer impacted by system clock updates since @code{perf_counter()} is
monotonic. Patch by Inada Naoki.

@item 
bpo-33461@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33461}: @code{json.loads} now emits @code{DeprecationWarning} when
@code{encoding} option is specified.  Patch by Matthias Bussonnier.

@item 
bpo-36559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36559}: The random module now prefers the lean internal _sha512 module
over hashlib for seed(version=2) to optimize import time.

@item 
bpo-17561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17561}: Set backlog=None as the default for socket.create_server.

@item 
bpo-34373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34373}: Fix @ref{11c5,,time.mktime()} error handling on AIX for year before
1970.

@item 
bpo-36232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36232}: Improve error message when trying to open existing DBM database
that actually doesn't exist. Patch by Marco Rougeth.

@item 
bpo-36546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36546}: Add statistics.quantiles()

@item 
bpo-36050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36050}: Optimized @code{http.client.HTTPResponse.read()} for large
response. Patch by Inada Naoki.

@item 
bpo-36522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36522}: If `debuglevel' is set to >0 in @ref{6e,,http.client}, print all
values for headers with multiple values for the same header name. Patch by
Matt Houglum.

@item 
bpo-36492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36492}: Deprecated passing required arguments like `func' as keyword
arguments in functions which should accept arbitrary keyword arguments and
pass them to other function. Arbitrary keyword arguments (even with names
"self" and "func") can now be passed to these functions if the required
arguments are passed as positional arguments.

@item 
bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181}: Add statistics.geometric_mean().

@item 
bpo-30427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30427}: @code{os.path.normcase()} relies on @code{os.fspath()} to check the
type of its argument. Redundant checks have been removed from its
@code{posixpath.normcase()} and @code{ntpath.normcase()} implementations. Patch
by Wolfgang Maier.

@item 
bpo-36385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36385}: Stop rejecting IPv4 octets for being ambiguously octal. Leading
zeros are ignored, and no longer are assumed to specify octal octets.
Octets are always decimal numbers. Octets must still be no more than three
digits, including leading zeroes.

@item 
bpo-36434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36434}: Errors during writing to a ZIP file no longer prevent to
properly close it.

@item 
bpo-36407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36407}: Fixed wrong indentation writing for CDATA section in
xml.dom.minidom. Patch by Vladimir Surjaninov.

@item 
bpo-36326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36326}: inspect.getdoc() can now find docstrings for member objects
when __slots__ is a dictionary.

@item 
bpo-36366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36366}: Calling @code{stop()} on an unstarted or stopped
@ref{e7b,,unittest.mock.patch()} object will now return @code{None} instead of
raising @ref{193,,RuntimeError}, making the method idempotent. Patch by
Karthikeyan Singaravelan.

@item 
bpo-36348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36348}: The @code{imap.IMAP4.logout()} method no longer ignores silently
arbitrary exceptions.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Add time module support and fix test_time failures for VxWorks.

@item 
bpo-36227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36227}: Added support for keyword arguments @code{default_namespace} and
@code{xml_declaration} in functions @code{ElementTree.tostring()} and
@code{ElementTree.tostringlist()}.

@item 
bpo-36004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36004}: Added new alternate constructors
@ref{9da,,datetime.date.fromisocalendar()} and
@ref{9db,,datetime.datetime.fromisocalendar()}, which construct date objects
from ISO year, week number and weekday; these are the inverse of each
class's @code{isocalendar} method. Patch by Paul Ganssle.

@item 
bpo-35936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35936}: @ref{90,,modulefinder} no longer depends on the deprecated
@ref{75,,imp} module, and the initializer for
@ref{1991,,modulefinder.ModuleFinder} now has immutable default arguments.
Patch by Brandt Bucher.

@item 
bpo-35376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35376}: @ref{90,,modulefinder} correctly handles modules that have the
same name as a bad package. Patch by Brandt Bucher.

@item 
bpo-17396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17396}: @ref{90,,modulefinder} no longer crashes when encountering syntax
errors in followed imports. Patch by Brandt Bucher.

@item 
bpo-35934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35934}: Added @ref{a19,,create_server()} and
@ref{a1a,,has_dualstack_ipv6()} convenience functions to automate the
necessary tasks usually involved when creating a server socket, including
accepting both IPv4 and IPv6 connections on the same socket.  (Contributed
by Giampaolo Rodola in bpo-17561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17561}.)

@item 
bpo-23078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23078}: Add support for @ref{165,,classmethod()} and @ref{40c,,staticmethod()} to
@ref{1590,,unittest.mock.create_autospec()}.  Initial patch by Felipe Ochoa.

@item 
bpo-35416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35416}: Fix potential resource warnings in distutils. Patch by Mickaël
Schoentgen.

@item 
bpo-25451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25451}: Add transparency methods to @code{tkinter.PhotoImage}.  Patch
by Zackery Spytz.

@item 
bpo-35082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35082}: Don't return deleted attributes when calling dir on a
@ref{a3a,,unittest.mock.Mock}.

@item 
bpo-34547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34547}: @ref{197e,,wsgiref.handlers.BaseHandler} now handles abrupt client
connection terminations gracefully. Patch by Petter Strandmark.

@item 
bpo-31658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31658}: @ref{1992,,xml.sax.parse()} now supports @ref{29d,,path-like}. Patch by Mickaël Schoentgen.

@item 
bpo-34139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34139}: Remove stale unix datagram socket before binding

@item 
bpo-33530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33530}: Implemented Happy Eyeballs in @code{asyncio.create_connection()}.
Added two new arguments, `happy_eyeballs_delay' and `interleave', to
specify Happy Eyeballs behavior.

@item 
bpo-33291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33291}: Do not raise AttributeError when calling the inspect functions
isgeneratorfunction, iscoroutinefunction, isasyncgenfunction on a method
created from an arbitrary callable. Instead, return False.

@item 
bpo-31310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31310}: Fix the multiprocessing.semaphore_tracker so it is reused by
child processes

@item 
bpo-31292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31292}: Fix @code{setup.py check --restructuredtext} for files containing
@code{include} directives.
@end itemize

@node Documentation<43>,Tests<45>,Library<48>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id431}@anchor{1993}
@subsubsection Documentation



@itemize -

@item 
bpo-36625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36625}: Remove obsolete comments from docstrings in fractions.Fraction

@item 
bpo-30840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30840}: Document relative imports

@item 
bpo-36523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36523}: Add docstring for io.IOBase.writelines().

@item 
bpo-36425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36425}: New documentation translation: Simplified Chinese@footnote{https://docs.python.org/zh-cn/}.

@item 
bpo-36345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36345}: Avoid the duplication of code from @code{Tools/scripts/serve.py}
in using the @code{literalinclude} directive for the basic
wsgiref-based web server in the documentation of @ref{117,,wsgiref}.
Contributed by Stéphane Wirtel.

@item 
bpo-36345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36345}: Using the code of the @code{Tools/scripts/serve.py} script as an
example in the @ref{117,,wsgiref} documentation.  Contributed by Stéphane
Wirtel.

@item 
bpo-36157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36157}: Added documentation for PyInterpreterState_Main().

@item 
bpo-33043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33043}: Updates the docs.python.org page with the addition of a
'Contributing to Docs' link at the end of the page (between 'Reporting
Bugs' and 'About Documentation'). Updates the 'Found a Bug' page with
additional links and information in the Documentation Bugs section.

@item 
bpo-35581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35581}: @@typing.type_check_only now allows type stubs to mark functions
and classes not available during runtime.

@item 
bpo-33832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33832}: Add glossary entry for 'magic method'.

@item 
bpo-32913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32913}: Added re.Match.groupdict example to regex HOWTO.
@end itemize

@node Tests<45>,Build<48>,Documentation<43>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id432}@anchor{1994}
@subsubsection Tests



@itemize -

@item 
bpo-36719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36719}: regrtest now always detects uncollectable objects. Previously,
the check was only enabled by @code{--findleaks}. The check now also works
with @code{-jN/--multiprocess N}. @code{--findleaks} becomes a deprecated alias
to @code{--fail-env-changed}.

@item 
bpo-36725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36725}: When using multiprocessing mode (-jN), regrtest now better
reports errors if a worker process fails, and it exits immediately on a
worker thread failure or when interrupted.

@item 
bpo-36454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36454}: Change test_time.test_monotonic() to test only the lower bound
of elapsed time after a sleep command rather than the upper bound. This
prevents unnecessary test failures on slow buildbots. Patch by Victor
Stinner.

@item 
bpo-32424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32424}: Improve test coverage for xml.etree.ElementTree. Patch by
Gordon P. Hemsley.

@item 
bpo-32424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32424}: Fix typo in test_cyclic_gc() test for xml.etree.ElementTree.
Patch by Gordon P. Hemsley.

@item 
bpo-36635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36635}: Add a new @code{_testinternalcapi} module to test the internal
C API.

@item 
bpo-36629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36629}: Fix @code{test_imap4_host_default_value()} of @code{test_imaplib}:
catch also @ref{1995,,errno.ENETUNREACH} error.

@item 
bpo-36611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36611}: Fix @code{test_sys.test_getallocatedblocks()} when
@ref{fe,,tracemalloc} is enabled.

@item 
bpo-36560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36560}: Fix reference leak hunting in regrtest: compute also deltas (of
reference count, allocated memory blocks, file descriptor count) during
warmup, to ensure that everything is initialized before starting to hunt
reference leaks.

@item 
bpo-36565@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36565}: Fix reference hunting (@code{python3 -m test -R 3:3}) when Python
has no built-in abc module.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Port test_resource to VxWorks: skip tests cases setting
RLIMIT_FSIZE and RLIMIT_CPU.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix test_tabnanny on VxWorks: adjust ENOENT error message.

@item 
bpo-36436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36436}: Fix @code{_testcapi.pymem_buffer_overflow()}: handle memory
allocation failure.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Fix test_utf8_mode on VxWorks: Python always use UTF-8 on
VxWorks.

@item 
bpo-36341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36341}: Fix tests that may fail with PermissionError upon calling
bind() on AF_UNIX sockets.
@end itemize

@node Build<48>,Windows<43>,Tests<45>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id433}@anchor{1996}
@subsubsection Build



@itemize -

@item 
bpo-36747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36747}: Remove the stale scriptsinstall Makefile target.

@item 
bpo-21536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21536}: On Unix, C extensions are no longer linked to libpython except
on Android and Cygwin.

It is now possible for a statically linked Python to load a C extension
built using a shared library Python.

When Python is embedded, @code{libpython} must not be loaded with
@code{RTLD_LOCAL}, but @code{RTLD_GLOBAL} instead. Previously, using
@code{RTLD_LOCAL}, it was already not possible to load C extensions which
were not linked to @code{libpython}, such as C extensions of the standard
library built by the @code{*shared*} section of @code{Modules/Setup}.

distutils, python-config and python-config.py have been modified.

@item 
bpo-36707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36707}: @code{./configure --with-pymalloc} no longer adds the @code{m} flag
to SOABI (sys.implementation.cache_tag). Enabling or disabling pymalloc
has no impact on the ABI.

@item 
bpo-36635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36635}: Change @code{PyAPI_FUNC(type)}, @code{PyAPI_DATA(type)} and
@code{PyMODINIT_FUNC} macros of @code{pyport.h} when @code{Py_BUILD_CORE_MODULE} is
defined. The @code{Py_BUILD_CORE_MODULE} define must be now be used to build
a C extension as a dynamic library accessing Python internals: export the
@code{PyInit_@var{xxx}()} function in DLL exports on Windows.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Don't build the @code{_crypt} extension on VxWorks.

@item 
bpo-36618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36618}: Add @code{-fmax-type-align=8} to CFLAGS when clang compiler is
detected. The pymalloc memory allocator aligns memory on 8 bytes. On
x86-64, clang expects alignment on 16 bytes by default and so uses MOVAPS
instruction which can lead to segmentation fault. Instruct clang that
Python is limited to alignment on 8 bytes to use MOVUPS instruction
instead: slower but don't trigger a SIGSEGV if the memory is not aligned
on 16 bytes. Sadly, the flag must be added to @code{CFLAGS} and not just
@code{CFLAGS_NODIST}, since third party C extensions can have the same issue.

@item 
bpo-36605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36605}: @code{make tags} and @code{make TAGS} now also parse
@code{Modules/_io/*.c} and @code{Modules/_io/*.h}.

@item 
bpo-36465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36465}: Release builds and debug builds are now ABI compatible:
defining the @code{Py_DEBUG} macro no longer implies the @code{Py_TRACE_REFS}
macro, which introduces the only ABI incompatibility. The
@code{Py_TRACE_REFS} macro, which adds the @ref{41b,,sys.getobjects()} function
and the 
@geindex PYTHONDUMPREFS
@geindex variable d'environnement; PYTHONDUMPREFS
@ref{994,,PYTHONDUMPREFS} environment variable, can be set using
the new @code{./configure --with-trace-refs} build option.

@item 
bpo-36577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36577}: setup.py now correctly reports missing OpenSSL headers and
libraries again.

@item 
bpo-36544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36544}: Fix regression introduced in bpo-36146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36146} refactoring setup.py

@item 
bpo-36508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36508}: @code{python-config --ldflags} no longer includes flags of the
@code{LINKFORSHARED} variable. The @code{LINKFORSHARED} variable must only be
used to build executables.

@item 
bpo-36503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36503}: Remove references to "aix3" and "aix4". Patch by M. Felt.
@end itemize

@node Windows<43>,macOS<36>,Build<48>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id434}@anchor{1997}
@subsubsection Windows



@itemize -

@item 
bpo-35920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35920}: Added platform.win32_edition() and platform.win32_is_iot().
Added support for cross-compiling packages for Windows ARM32. Skip tests
that are not expected to work on Windows IoT Core ARM32.

@item 
bpo-36649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36649}: Remove trailing spaces for registry keys when installed via the
Store.

@item 
bpo-34144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34144}: Fixed activate.bat to correctly update codepage when chcp.com
returns dots in output. Patch by Lorenz Mende.

@item 
bpo-36509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36509}: Added preset-iot layout for Windows IoT ARM containers. This
layout doesn't contain UI components like tkinter or IDLE. It also doesn't
contain files to support on-target builds since Windows ARM32 builds must
be cross-compiled when using MSVC.

@item 
bpo-35941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35941}: enum_certificates function of the ssl module now returns
certificates from all available certificate stores inside windows in a
query instead of returning only certificates from the system wide
certificate store. This includes certificates from these certificate
stores: local machine, local machine enterprise, local machine group
policy, current user, current user group policy, services, users.
ssl.enum_crls() function is changed in the same way to return all
certificate revocation lists inside the windows certificate revocation
list stores.

@item 
bpo-36441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36441}: Fixes creating a venv when debug binaries are installed.

@item 
bpo-36085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36085}: Enable better DLL resolution on Windows by using safe DLL
search paths and adding @ref{9d8,,os.add_dll_directory()}.

@item 
bpo-36010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36010}: Add the venv standard library module to the nuget distribution
for Windows.

@item 
bpo-29515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29515}: Add the following socket module constants on Windows:
IPPROTO_AH IPPROTO_CBT IPPROTO_DSTOPTS IPPROTO_EGP IPPROTO_ESP
IPPROTO_FRAGMENT IPPROTO_GGP IPPROTO_HOPOPTS IPPROTO_ICLFXBM
IPPROTO_ICMPV6 IPPROTO_IDP IPPROTO_IGMP IPPROTO_IGP IPPROTO_IPV4
IPPROTO_IPV6 IPPROTO_L2TP IPPROTO_MAX IPPROTO_ND IPPROTO_NONE IPPROTO_PGM
IPPROTO_PIM IPPROTO_PUP IPPROTO_RDP IPPROTO_ROUTING IPPROTO_SCTP
IPPROTO_ST

@item 
bpo-35947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35947}: Added current version of libffi to cpython-source-deps. Change
_ctypes to use current version of libffi on Windows.

@item 
bpo-34060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34060}: Report system load when running test suite on Windows. Patch by
Ammar Askar. Based on prior work by Jeremy Kloth.

@item 
bpo-31512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31512}: With the Windows 10 Creators Update, non-elevated users can now
create symlinks as long as the computer has Developer Mode enabled.
@end itemize

@node macOS<36>,IDLE<34>,Windows<43>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id435}@anchor{1998}
@subsubsection macOS



@itemize -

@item 
bpo-34602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34602}: Avoid failures setting macOS stack resource limit with
resource.setrlimit. This reverts an earlier fix for bpo-18075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18075} which forced
a non-default stack size when building the interpreter executable on
macOS.
@end itemize

@node IDLE<34>,Tools/Demos<23>,macOS<36>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id436}@anchor{1999}
@subsubsection IDLE



@itemize -

@item 
bpo-36429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36429}: Fix starting IDLE with pyshell. Add idlelib.pyshell alias at
top; remove pyshell alias at bottom. Remove obsolete __name__=='__main__'
command.
@end itemize

@node Tools/Demos<23>,C API<47>,IDLE<34>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id437}@anchor{199a}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-14546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14546}: Fix the argument handling in Tools/scripts/lll.py.
@end itemize

@node C API<47>,,Tools/Demos<23>,Python 3 8 0 alpha 4
@anchor{whatsnew/changelog id438}@anchor{199b}
@subsubsection C API



@itemize -

@item 
bpo-36763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36763}: Fix memory leak in @code{Py_SetStandardStreamEncoding()}:
release memory if the function is called twice.

@item 
bpo-36641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36641}: PyDoc_VAR(name) and @ref{1900,,PyDoc_STRVAR}(name, str)
now create @code{static const char name[]} instead of @code{static char name[]}.
Patch by Inada Naoki.

@item 
bpo-36389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36389}: Change the value of @code{CLEANBYTE}, @code{DEADDYTE} and
@code{FORBIDDENBYTE} internal constants used by debug hooks on Python memory
allocators (@ref{c58,,PyMem_SetupDebugHooks()} function). Byte patterns
@code{0xCB}, @code{0xDB} and @code{0xFB} have been replaced with @code{0xCD}, @code{0xDD}
and @code{0xFD} to use the same values than Windows CRT debug @code{malloc()}
and @code{free()}.

@item 
bpo-36443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36443}: Since Python 3.7.0, calling @ref{bb5,,Py_DecodeLocale()} before
@ref{899,,Py_Initialize()} produces mojibake if the @code{LC_CTYPE} locale is
coerced and/or if the UTF-8 Mode is enabled by the user configuration. The
LC_CTYPE coercion and UTF-8 Mode are now disabled by default to fix the
mojibake issue. They must now be enabled explicitly (opt-in) using the new
@code{_Py_PreInitialize()} API with @code{_PyPreConfig}.

@item 
bpo-36025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36025}: Fixed an accidental change to the datetime C API where the
arguments to the @ref{199c,,PyDate_FromTimestamp()} function were incorrectly
interpreted as a single timestamp rather than an arguments tuple, which
causes existing code to start raising @ref{522,,TypeError}. The
backwards-incompatible change was only present in alpha releases of Python
3.8. Patch by Paul Ganssle.

@item 
bpo-35810@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35810}: Modify @code{PyObject_Init} to correctly increase the refcount of
heap-allocated Type objects. Also fix the refcounts of the heap-allocated
types that were either doing this manually or not decreasing the type's
refcount in tp_dealloc
@end itemize

@node Python 3 8 0 alpha 3,Python 3 8 0 alpha 2,Python 3 8 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-8-0-alpha-3}@anchor{199d}
@subsection Python 3.8.0 alpha 3


`Release date: 2019-03-25'

@menu
* Security: Security<34>. 
* Core and Builtins: Core and Builtins<50>. 
* Library: Library<49>. 
* Documentation: Documentation<44>. 
* Tests: Tests<46>. 
* Build: Build<49>. 
* Windows: Windows<44>. 
* IDLE: IDLE<35>. 
* Tools/Demos: Tools/Demos<24>. 
* C API: C API<48>. 

@end menu

@node Security<34>,Core and Builtins<50>,,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id439}@anchor{199e}
@subsubsection Security



@itemize -

@item 
bpo-36216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36216}: Changes urlsplit() to raise ValueError when the URL contains
characters that decompose under IDNA encoding (NFKC-normalization) into
characters that affect how the URL is parsed.

@item 
bpo-35121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35121}: Don't send cookies of domain A without Domain attribute to
domain B when domain A is a suffix match of domain B while using a
cookiejar with @ref{199f,,http.cookiejar.DefaultCookiePolicy} policy. Patch
by Karthikeyan Singaravelan.
@end itemize

@node Core and Builtins<50>,Library<49>,Security<34>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id440}@anchor{19a0}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-36421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36421}: Fix a possible double decref in _ctypes.c's
@code{PyCArrayType_new()}.

@item 
bpo-36412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36412}: Fix a possible crash when creating a new dictionary.

@item 
bpo-36398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36398}: Fix a possible crash in @code{structseq_repr()}.

@item 
bpo-36256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36256}: Fix bug in parsermodule when parsing a state in a DFA that has
two or more arcs with labels of the same type. Patch by Pablo Galindo.

@item 
bpo-36365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36365}: repr(structseq) is no longer limited to 512 bytes.

@item 
bpo-36374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36374}: Fix a possible null pointer dereference in
@code{merge_consts_recursive()}. Patch by Zackery Spytz.

@item 
bpo-36236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36236}: At Python initialization, the current directory is no longer
prepended to @ref{3ab,,sys.path} if it has been removed.

@item 
bpo-36352@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36352}: Python initialization now fails with an error, rather than
silently truncating paths, if a path is too long.

@item 
bpo-36301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36301}: Python initialization now fails if decoding @code{pybuilddir.txt}
configuration file fails at startup.

@item 
bpo-36333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36333}: Fix leak in _PyRuntimeState_Fini. Contributed by Stéphane
Wirtel.

@item 
bpo-36332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36332}: The builtin @ref{190,,compile()} can now handle AST objects that
contain assignment expressions. Patch by Pablo Galindo.

@item 
bpo-36282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36282}: Improved error message for too much positional arguments in
some builtin functions.

@item 
bpo-30040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30040}: New empty dict uses fewer memory for now.  It used more memory
than empty dict created by @code{dict.clear()}.  And empty dict creation and
deletion is about 2x faster.  Patch by Inada Naoki.

@item 
bpo-36262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36262}: Fix an unlikely memory leak on conversion from string to float
in the function @code{_Py_dg_strtod()} used by @code{float(str)},
@code{complex(str)}, @ref{cfe,,pickle.load()}, @ref{19a1,,marshal.load()}, etc.

@item 
bpo-36252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36252}: Update Unicode databases to version 12.0.0.

@item 
bpo-36218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36218}: Fix a segfault occurring when sorting a list of heterogeneous
values. Patch contributed by Rémi Lapeyre and Elliot Gorokhovsky.

@item 
bpo-36188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36188}: Cleaned up left-over vestiges of Python 2 unbound method
handling in method objects and documentation. Patch by Martijn Pieters

@item 
bpo-36124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36124}: Add a new interpreter-specific dict and expose it in the C-API
via PyInterpreterState_GetDict().  This parallels PyThreadState_GetDict().
However, extension modules should continue using PyModule_GetState() for
their own internal per-interpreter state.

@item 
bpo-35975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35975}: Add a @code{feature_version} flag to @code{ast.parse()} (documented)
and @code{compile()} (hidden) that allows tweaking the parser to support
older versions of the grammar. In particular, if @code{feature_version} is 5
or 6, the hacks for the @code{async} and @code{await} keyword from PEP 492 are
reinstated. (For 7 or higher, these are unconditionally treated as
keywords, but they are still special tokens rather than @code{NAME} tokens
that the parser driver recognizes.)

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Use UTF-8 as the system encoding on VxWorks.

@item 
bpo-36048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36048}: The @ref{707,,__index__()} special method will be used
instead of @ref{706,,__int__()} for implicit conversion of Python
numbers to C integers.  Using the @code{__int__()} method in implicit
conversions has been deprecated.

@item 
bpo-35808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35808}: Retire pgen and use a modified version of pgen2 to generate the
parser. Patch by Pablo Galindo.
@end itemize

@node Library<49>,Documentation<44>,Core and Builtins<50>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id441}@anchor{19a2}
@subsubsection Library



@itemize -

@item 
bpo-36401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36401}: The class documentation created by pydoc now has a separate
section for readonly properties.

@item 
bpo-36320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36320}: The typing.NamedTuple() class has deprecated the _field_types
attribute in favor of the __annotations__ attribute which carried the same
information. Also, both attributes were converted from OrderedDict to a
regular dict.

@item 
bpo-34745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34745}: Fix @ref{a,,asyncio} ssl memory issues caused by circular
references

@item 
bpo-36324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36324}: Add method to statistics.NormalDist for computing the inverse
cumulative normal distribution.

@item 
bpo-36321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36321}: collections.namedtuple() misspelled the name of an attribute.
To be consistent with typing.NamedTuple, the attribute name should have
been "_field_defaults" instead of "_fields_defaults".  For backwards
compatibility, both spellings are now created.  The misspelled version may
be removed in the future.

@item 
bpo-36297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36297}: "unicode_internal" codec is removed.  It was deprecated since
Python 3.3. Patch by Inada Naoki.

@item 
bpo-36298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36298}: Raise ModuleNotFoundError in pyclbr when a module can't be
found. Thanks to 'mental' for the bug report.

@item 
bpo-36268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36268}: Switch the default format used for writing tars with
@ref{dd,,tarfile} to the modern POSIX.1-2001 pax standard, from the
vendor-specific GNU. Contributed by C.A.M. Gerlach.

@item 
bpo-36285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36285}: Fix integer overflows in the array module. Patch by Stephan
Hohe.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Add _signal module support for VxWorks.

@item 
bpo-36272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36272}: @ref{86,,logging} does not silently ignore RecursionError anymore.
Patch contributed by Rémi Lapeyre.

@item 
bpo-36280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36280}: Add a kind field to ast.Constant. It is 'u' if the literal has
a 'u' prefix (i.e. a Python 2 style unicode literal), else None.

@item 
bpo-35931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35931}: The @ref{a4,,pdb} @code{debug} command now gracefully handles all
exceptions.

@item 
bpo-36251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36251}: Fix format strings used for stderrprinter and re.Match reprs.
Patch by Stephan Hohe.

@item 
bpo-36235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36235}: Fix @code{CFLAGS} in @code{customize_compiler()} of
@code{distutils.sysconfig}: when the @code{CFLAGS} environment variable is
defined, don't override @code{CFLAGS} variable with the @code{OPT} variable
anymore. Initial patch written by David Malcolm.

@item 
bpo-35807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35807}: Update ensurepip to install pip 19.0.3 and setuptools 40.8.0.

@item 
bpo-36139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36139}: Release GIL when closing @ref{208,,mmap} objects.

@item 
bpo-36179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36179}: Fix two unlikely reference leaks in _hashopenssl. The leaks
only occur in out-of-memory cases.

@item 
bpo-36169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36169}: Add overlap() method to statistics.NormalDist.  Computes the
overlapping coefficient for two normal distributions.

@item 
bpo-36103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36103}: Default buffer size used by @code{shutil.copyfileobj()} is changed
from 16 KiB to 64 KiB on non-Windows platform to reduce system call
overhead. Contributed by Inada Naoki.

@item 
bpo-36130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36130}: Fix @code{pdb} with @code{skip=...} when stepping into a frame
without a @code{__name__} global.  Patch by Anthony Sottile.

@item 
bpo-35652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35652}: shutil.copytree(copy_function=...) erroneously pass DirEntry
instead of a path string.

@item 
bpo-35178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35178}: Ensure custom @ref{19a3,,warnings.formatwarning()} function can
receive @code{line} as positional argument. Based on patch by Tashrif Billah.

@item 
bpo-36106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36106}: Resolve potential name clash with libm's sinpi(). Patch by
Dmitrii Pasechnik.

@item 
bpo-36091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36091}: Clean up reference to async generator in Lib/types. Patch by
Henry Chen.

@item 
bpo-36043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36043}: @code{FileCookieJar} supports @ref{29d,,path-like object}.
Contributed by Stéphane Wirtel

@item 
bpo-35899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35899}: Enum has been fixed to correctly handle empty strings and
strings with non-Latin characters (ie. 'α', 'א') without crashing.
Original patch contributed by Maxwell. Assisted by Stéphane Wirtel.

@item 
bpo-21269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21269}: Add @code{args} and @code{kwargs} properties to mock call objects.
Contributed by Kumar Akshay.

@item 
bpo-30670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30670}: @code{pprint.pp} has been added to pretty-print objects with
dictionary keys being sorted with their insertion order by default.
Parameter `sort_dicts' has been added to @code{pprint.pprint},
@code{pprint.pformat} and @code{pprint.PrettyPrinter}. Contributed by Rémi
Lapeyre.

@item 
bpo-35843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35843}: Implement @code{__getitem__} for @code{_NamespacePath}.  Patch by
Anthony Sottile.

@item 
bpo-35802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35802}: Clean up code which checked presence of @code{os.stat} /
@code{os.lstat} / @code{os.chmod} which are always present.  Patch by Anthony
Sottile.

@item 
bpo-35715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35715}: Librates the return value of a ProcessPoolExecutor
_process_worker after it's no longer needed to free memory

@item 
bpo-35493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35493}: Use @ref{10c1,,multiprocessing.connection.wait()} instead of polling
each 0.2 seconds for worker updates in @code{multiprocessing.Pool}.
Patch by Pablo Galindo.

@item 
bpo-35661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35661}: Store the venv prompt in pyvenv.cfg.

@item 
bpo-35121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35121}: Don't set cookie for a request when the request path is a
prefix match of the cookie's path attribute but doesn't end with "/".
Patch by Karthikeyan Singaravelan.

@item 
bpo-21478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21478}: Calls to a child function created with
@ref{1590,,unittest.mock.create_autospec()} should propagate to the parent.
Patch by Karthikeyan Singaravelan.

@item 
bpo-35198@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35198}: Fix C++ extension compilation on AIX
@end itemize

@node Documentation<44>,Tests<46>,Library<49>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id442}@anchor{19a4}
@subsubsection Documentation



@itemize -

@item 
bpo-36329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36329}: Declare the path of the Python binary for the usage of
@code{Tools/scripts/serve.py} when executing @code{make -C Doc/ serve}.
Contributed by Stéphane Wirtel

@item 
bpo-36138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36138}: Improve documentation about converting datetime.timedelta to
scalars.

@item 
bpo-21314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21314}: A new entry was added to the Core Language Section of the
Programming FAQ, which explaines the usage of slash(/) in the signature of
a function. Patch by Lysandros Nikolaou
@end itemize

@node Tests<46>,Build<49>,Documentation<44>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id443}@anchor{19a5}
@subsubsection Tests



@itemize -

@item 
bpo-36234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36234}: test_posix.PosixUidGidTests: add tests for invalid uid/gid type
(str). Initial patch written by David Malcolm.

@item 
bpo-29571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29571}: Fix @code{test_re.test_locale_flag()}:  use
@code{locale.getpreferredencoding()} rather than @code{locale.getlocale()} to
get the locale encoding. With some locales, @code{locale.getlocale()} returns
the wrong encoding.

@item 
bpo-36123@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36123}: Fix race condition in test_socket.
@end itemize

@node Build<49>,Windows<44>,Tests<46>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id444}@anchor{19a6}
@subsubsection Build



@itemize -

@item 
bpo-36356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36356}: Fix leaks that led to build failure when configured with
address sanitizer.

@item 
bpo-36146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36146}: Add @code{TEST_EXTENSIONS} constant to @code{setup.py} to allow to
not build test extensions like @code{_testcapi}.

@item 
bpo-36146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36146}: Fix setup.py on macOS: only add @code{/usr/include/ffi} to include
directories of _ctypes, not for all extensions.

@item 
bpo-31904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31904}: Enable build system to cross-build for VxWorks RTOS.
@end itemize

@node Windows<44>,IDLE<35>,Build<49>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id445}@anchor{19a7}
@subsubsection Windows



@itemize -

@item 
bpo-36312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36312}: Fixed decoders for the following code pages: 50220, 50221,
50222, 50225, 50227, 50229, 57002 through 57011, 65000 and 42.

@item 
bpo-36264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36264}: Don't honor POSIX @code{HOME} in @code{os.path.expanduser} on
windows.  Patch by Anthony Sottile.

@item 
bpo-24643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24643}: Fix name collisions due to @code{#define timezone _timezone} in
PC/pyconfig.h.
@end itemize

@node IDLE<35>,Tools/Demos<24>,Windows<44>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id446}@anchor{19a8}
@subsubsection IDLE



@itemize -

@item 
bpo-36405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36405}: Use dict unpacking in idlelib.

@item 
bpo-36396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36396}: Remove fgBg param of idlelib.config.GetHighlight(). This param
was only used twice and changed the return type.

@item 
bpo-36176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36176}: Fix IDLE autocomplete & calltip popup colors. Prevent conflicts
with Linux dark themes (and slightly darken calltip background).

@item 
bpo-23205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23205}: For the grep module, add tests for findfiles, refactor
findfiles to be a module-level function, and refactor findfiles to use
os.walk.

@item 
bpo-23216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23216}: Add docstrings to IDLE search modules.

@item 
bpo-36152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36152}: Remove colorizer.ColorDelegator.close_when_done and the
corresponding argument of .close().  In IDLE, both have always been None
or False since 2007.

@item 
bpo-32129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32129}: Avoid blurry IDLE application icon on macOS with Tk 8.6. Patch
by Kevin Walzer.

@item 
bpo-36096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36096}: Refactor class variables to instance variables in colorizer.

@item 
bpo-30348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30348}: Increase test coverage of idlelib.autocomplete by 30%. Patch by
Louie Lu
@end itemize

@node Tools/Demos<24>,C API<48>,IDLE<35>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id447}@anchor{19a9}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-35132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35132}: Fix py-list and py-bt commands of python-gdb.py on gdb7.

@item 
bpo-32217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32217}: Fix freeze script on Windows.
@end itemize

@node C API<48>,,Tools/Demos<24>,Python 3 8 0 alpha 3
@anchor{whatsnew/changelog id448}@anchor{19aa}
@subsubsection C API



@itemize -

@item 
bpo-36381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36381}: Raise @code{DeprecationWarning} when '#' formats are used for
building or parsing values without @code{PY_SSIZE_T_CLEAN}.

@item 
bpo-36142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36142}: The whole coreconfig.h header is now excluded from
Py_LIMITED_API. Move functions definitions into a new internal
pycore_coreconfig.h header.
@end itemize

@node Python 3 8 0 alpha 2,Python 3 8 0 alpha 1,Python 3 8 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-8-0-alpha-2}@anchor{19ab}
@subsection Python 3.8.0 alpha 2


`Release date: 2019-02-25'

@menu
* Core and Builtins: Core and Builtins<51>. 
* Library: Library<50>. 
* Documentation: Documentation<45>. 
* Tests: Tests<47>. 
* Windows: Windows<45>. 
* IDLE: IDLE<36>. 

@end menu

@node Core and Builtins<51>,Library<50>,,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id449}@anchor{19ac}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-36052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36052}: Raise a @ref{18b,,SyntaxError} when assigning a value to
@code{__debug__} with the Assignment Operator. Contributed by Stéphane Wirtel
and Pablo Galindo.

@item 
bpo-36012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36012}: Doubled the speed of class variable writes.  When a non-dunder
attribute was updated, there was an unnecessary call to update slots.

@item 
bpo-35942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35942}: The error message emitted when returning invalid types from
@code{__fspath__} in interfaces that allow passing @ref{c3f,,PathLike}
objects has been improved and now it does explain the origin of the error.

@item 
bpo-36016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36016}: @code{gc.get_objects} can now receive an optional parameter
indicating a generation to get objects from. Patch by Pablo Galindo.

@item 
bpo-1054041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1054041}: When the main interpreter exits due to an uncaught
KeyboardInterrupt, the process now exits in the appropriate manner for its
parent process to detect that a SIGINT or ^C terminated the process.  This
allows shells and batch scripts to understand that the user has asked them
to stop.

@item 
bpo-35992@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35992}: Fix @code{__class_getitem__()} not being called on a class with a
custom non-subscriptable metaclass.

@item 
bpo-35993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35993}: Fix a crash on fork when using subinterpreters. Contributed by
Stéphane Wirtel

@item 
bpo-35991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35991}: Fix a potential double free in Modules/_randommodule.c.

@item 
bpo-35961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35961}: Fix a crash in slice_richcompare(): use strong references
rather than stolen references for the two temporary internal tuples.

@item 
bpo-35911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35911}: Enable the creation of cell objects by adding a
@code{cell.__new__} method, and expose the type @code{cell} in @code{Lib/types.py}
under the name CellType. Patch by Pierre Glaser.

@item 
bpo-12822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12822}: Use monotonic clock for @code{pthread_cond_timedwait} when
@code{pthread_condattr_setclock} and @code{CLOCK_MONOTONIC} are available.

@item 
bpo-15248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15248}: The compiler emits now syntax warnings in the case when a comma
is likely missed before tuple or list.

@item 
bpo-35886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35886}: The implementation of PyInterpreterState has been moved into
the internal header files (guarded by Py_BUILD_CORE).

@item 
bpo-31506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31506}: Clarify the errors reported when @code{object.__new__} and
@code{object.__init__} receive more than one argument. Contributed by Sanyam
Khurana.

@item 
bpo-35724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35724}: Signal-handling is now guaranteed to happen relative to the
main interpreter.

@item 
bpo-33608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33608}: We added a new internal _Py_AddPendingCall() that operates
relative to the provided interpreter.  This allows us to use the existing
implementation to ask another interpreter to do work that cannot be done
in the current interpreter, like decref an object the other interpreter
owns.  The existing Py_AddPendingCall() only operates relative to the main
interpreter.

@item 
bpo-33989@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33989}: Fix a possible crash in @ref{bbd,,list.sort()} when sorting objects
with @code{ob_type->tp_richcompare == NULL}.  Patch by Zackery Spytz.
@end itemize

@node Library<50>,Documentation<45>,Core and Builtins<51>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id450}@anchor{19ad}
@subsubsection Library



@itemize -

@item 
bpo-35512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35512}: @ref{1981,,unittest.mock.patch.dict()} used as a decorator with
string target resolves the target during function call instead of during
decorator construction. Patch by Karthikeyan Singaravelan.

@item 
bpo-36018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36018}: Add statistics.NormalDist, a tool for creating and manipulating
normal distributions of random variable.  Features a composite class that
treats the mean and standard deviation of measurement data as single
entity.

@item 
bpo-35904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35904}: Added statistics.fmean() as a faster, floating-point variant of
the existing mean() function.

@item 
bpo-35918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35918}: Removed broken @code{has_key} method from
multiprocessing.managers.SyncManager.dict. Contributed by Rémi Lapeyre.

@item 
bpo-18283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18283}: Add support for bytes to @ref{49d,,shutil.which()}.

@item 
bpo-35960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35960}: Fix @ref{19ae,,dataclasses.field()} throwing away empty mapping
objects passed as metadata.

@item 
bpo-35500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35500}: Write expected and actual call parameters on separate lines in
@ref{19af,,unittest.mock.Mock.assert_called_with()} assertion errors.
Contributed by Susan Su.

@item 
bpo-35931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35931}: The @ref{a4,,pdb} @code{debug} command now gracefully handles syntax
errors.

@item 
bpo-24209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24209}: In http.server script, rely on getaddrinfo to bind to preferred
address based on the bind parameter. Now default bind or binding to a name
may bind to IPv6 or dual-stack, depending on the environment.

@item 
bpo-35321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35321}: Set @code{__spec__.origin} of  @code{_frozen_importlib} to frozen so
that it matches the behavior of @code{_frozen_importlib_external}.  Patch by
Nina Zakharenko.

@item 
bpo-35378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35378}: Fix a reference issue inside @code{multiprocessing.Pool} that
caused the pool to remain alive if it was deleted without being closed or
terminated explicitly. A new strong reference is added to the pool
iterators to link the lifetime of the pool to the lifetime of its
iterators so the pool does not get destroyed if a pool iterator is still
alive.

@item 
bpo-34294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34294}: re module, fix wrong capturing groups in rare cases.
@ref{120a,,re.search()}, @ref{1013,,re.findall()}, @ref{2a0,,re.sub()} and other functions
that scan through string looking for a match, should reset capturing
groups between two match attempts. Patch by Ma Lin.

@item 
bpo-35615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35615}: @ref{113,,weakref}: Fix a RuntimeError when copying a
WeakKeyDictionary or a WeakValueDictionary, due to some keys or values
disappearing while iterating.

@item 
bpo-35606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35606}: Implement @ref{9f2,,math.prod()} as analogous function to
@ref{454,,sum()} that returns the product of a 'start' value (default: 1) times
an iterable of numbers. Patch by Pablo Galindo.

@item 
bpo-32417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32417}: Performing arithmetic between @ref{1c7,,datetime.datetime}
subclasses and @ref{9bd,,datetime.timedelta} now returns an object of the
same type as the @ref{1c7,,datetime.datetime} subclass. As a result,
@ref{9be,,datetime.datetime.astimezone()} and alternate constructors like
@ref{4d6,,datetime.datetime.now()} and @code{datetime.fromtimestamp()} called
with a @code{tz} argument now `also' retain their subclass.

@item 
bpo-35153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35153}: Add `headers' optional keyword-only parameter to
@ref{a45,,xmlrpc.client.ServerProxy}, @code{xmlrpc.client.Transport} and
@code{xmlrpc.client.SafeTransport}.  Patch by Cédric Krier.

@item 
bpo-34572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34572}: Fix C implementation of pickle.loads to use importlib's locking
mechanisms, and thereby avoid using partially loaded modules. Patch by Tim
Burgess.
@end itemize

@node Documentation<45>,Tests<47>,Library<50>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id451}@anchor{19b0}
@subsubsection Documentation



@itemize -

@item 
bpo-36083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36083}: Fix formatting of --check-hash-based-pycs options in the
manpage Synopsis.

@item 
bpo-36007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36007}: Bump minimum sphinx version to 1.8.  Patch by Anthony Sottile.

@item 
bpo-22062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22062}: Update documentation and docstrings for pathlib. Original patch
by Mike Short.
@end itemize

@node Tests<47>,Windows<45>,Documentation<45>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id452}@anchor{19b1}
@subsubsection Tests



@itemize -

@item 
bpo-27313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27313}: Avoid test_ttk_guionly ComboboxTest failure with macOS Cocoa
Tk.

@item 
bpo-36019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36019}: Add test.support.TEST_HTTP_URL and replace references of
@indicateurl{http://www.example.com} by this new constant. Contributed by Stéphane
Wirtel.

@item 
bpo-36037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=36037}: Fix test_ssl for strict OpenSSL configuration like RHEL8 strict
crypto policy. Use older TLS version for minimum TLS version of the server
SSL context if needed, to test TLS version older than default minimum TLS
version.

@item 
bpo-35798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35798}: Added @code{test.support.check_syntax_warning()}.

@item 
bpo-35505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35505}: Make test_imap4_host_default_value independent on whether the
local IMAP server is running.

@item 
bpo-35917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35917}: multiprocessing: provide unit tests for SyncManager and
SharedMemoryManager classes + all the shareable types which are supposed
to be supported by them.  (patch by Giampaolo Rodola)

@item 
bpo-35704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35704}: Skip @code{test_shutil.test_unpack_archive_xztar} to prevent a
MemoryError on 32-bit AIX when MAXDATA setting is less than 0x20000000.

Patch by Michael Felt (aixtools)

@item 
bpo-34720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34720}: Assert m_state != NULL to mimic GC traversal functions that do
not correctly handle module creation when the module state has not been
created.
@end itemize

@node Windows<45>,IDLE<36>,Tests<47>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id453}@anchor{19b2}
@subsubsection Windows



@itemize -

@item 
bpo-35976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35976}: Added ARM build support to Windows build files in PCBuild.

@item 
bpo-35692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35692}: @code{pathlib} no longer raises when checking file and directory
existence on drives that are not ready

@item 
bpo-35872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35872}: Uses the base Python executable when invoking venv in a virtual
environment

@item 
bpo-35873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35873}: Prevents venv paths being inherited by child processes

@item 
bpo-35299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35299}: Fix sysconfig detection of the source directory and distutils
handling of pyconfig.h during PGO profiling
@end itemize

@node IDLE<36>,,Windows<45>,Python 3 8 0 alpha 2
@anchor{whatsnew/changelog id454}@anchor{19b3}
@subsubsection IDLE



@itemize -

@item 
bpo-24310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24310}: IDLE -- Document settings dialog font tab sample.

@item 
bpo-35833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35833}: Revise IDLE doc for control codes sent to Shell. Add a code
example block.

@item 
bpo-35689@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35689}: Add docstrings and unittests for colorizer.py.
@end itemize

@node Python 3 8 0 alpha 1,Python 3 7 0 final,Python 3 8 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-8-0-alpha-1}@anchor{19b4}
@subsection Python 3.8.0 alpha 1


`Release date: 2019-02-03'

@menu
* Security: Security<35>. 
* Core and Builtins: Core and Builtins<52>. 
* Library: Library<51>. 
* Documentation: Documentation<46>. 
* Tests: Tests<48>. 
* Build: Build<50>. 
* Windows: Windows<46>. 
* macOS: macOS<37>. 
* IDLE: IDLE<37>. 
* Tools/Demos: Tools/Demos<25>. 
* C API: C API<49>. 

@end menu

@node Security<35>,Core and Builtins<52>,,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id455}@anchor{19b5}
@subsubsection Security



@itemize -

@item 
bpo-35746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35746}: 
@geindex Common Vulnerabilities and Exposures; CVE 2019-5010
CVE 2019-5010@footnote{https://www.cve.org/CVERecord?id=CVE-2019-5010}: Fix a NULL pointer deref in ssl module. The
cert parser did not handle CRL distribution points with empty DP or URI
correctly. A malicious or buggy certificate can result into segfault.
Vulnerability (TALOS-2018-0758) reported by Colin Read and Nicolas Edet of
Cisco.

@item 
bpo-34812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34812}: The @ref{94b,,-I} command line option (run Python in isolated
mode) is now also copied by the @ref{93,,multiprocessing} and @code{distutils}
modules when spawning child processes. Previously, only @ref{94a,,-E} and
@ref{1362,,-s} options (enabled by @ref{94b,,-I}) were copied.

@item 
bpo-34791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34791}: The xml.sax and xml.dom.domreg no longer use environment
variables to override parser implementations when
sys.flags.ignore_environment is set by -E or -I arguments.

@item 
bpo-17239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17239}: The xml.sax and xml.dom.minidom parsers no longer processes
external entities by default. External DTD and ENTITY declarations no
longer load files or create network connections.

@item 
bpo-34623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34623}: 
@geindex Common Vulnerabilities and Exposures; CVE 2018-14647
CVE 2018-14647@footnote{https://www.cve.org/CVERecord?id=CVE-2018-14647}: The C accelerated _elementtree module now
initializes hash randomization salt from _Py_HashSecret instead of
libexpat's default CSPRNG.

@item 
bpo-34405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34405}: Updated to OpenSSL 1.1.0i for Windows builds.

@item 
bpo-33871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33871}: Fixed sending the part of the file in @ref{afd,,os.sendfile()} on
macOS.  Using the `trailers' argument could cause sending more bytes from
the input file than was specified.

@item 
bpo-32533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32533}: Fixed thread-safety of error handling in _ssl.

@item 
bpo-33136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33136}: Harden ssl module against LibreSSL 
@geindex Common Vulnerabilities and Exposures; CVE 2018-8970
CVE 2018-8970@footnote{https://www.cve.org/CVERecord?id=CVE-2018-8970}.
X509_VERIFY_PARAM_set1_host() is called with an explicit namelen. A new
test ensures that NULL bytes are not allowed.

@item 
bpo-33001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33001}: Minimal fix to prevent buffer overrun in os.symlink on Windows

@item 
bpo-32981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32981}: Regexes in difflib and poplib were vulnerable to catastrophic
backtracking. These regexes formed potential DOS vectors (REDOS). They
have been refactored. This resolves 
@geindex Common Vulnerabilities and Exposures; CVE 2018-1060
CVE 2018-1060@footnote{https://www.cve.org/CVERecord?id=CVE-2018-1060} and 
@geindex Common Vulnerabilities and Exposures; CVE 2018-1061
CVE 2018-1061@footnote{https://www.cve.org/CVERecord?id=CVE-2018-1061}.
Patch by Jamie Davis.

@item 
bpo-28414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28414}: The ssl module now allows users to perform their own IDN
en/decoding when using SNI.
@end itemize

@node Core and Builtins<52>,Library<51>,Security<35>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id456}@anchor{19b6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-35877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35877}: Make parenthesis optional for named expressions in while
statement. Patch by Karthikeyan Singaravelan.

@item 
bpo-35814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35814}: Allow same right hand side expressions in annotated assignments
as in normal ones. In particular, @code{x: Tuple[int, int] = 1, 2} (without
parentheses on the right) is now allowed.

@item 
bpo-35766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35766}: Add the option to parse PEP 484 type comments in the ast
module. (Off by default.) This is merging the key functionality of the
third party fork thereof,
[typed_ast](@indicateurl{https://github.com/python/typed_ast}).

@item 
bpo-35713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35713}: Reorganize Python initialization to get working exceptions and
sys.stderr earlier.

@item 
bpo-33416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33416}: Add end line and end column position information to the Python
AST nodes. This is a C-level backwards incompatible change.

@item 
bpo-35720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35720}: Fixed a minor memory leak in pymain_parse_cmdline_impl function
in Modules/main.c

@item 
bpo-35634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35634}: @code{func(**kwargs)} will now raise an error when @code{kwargs} is a
mapping containing multiple entries with the same key. An error was
already raised when other keyword arguments are passed before @code{**kwargs}
since Python 3.6.

@item 
bpo-35623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35623}: Fix a crash when sorting very long lists. Patch by Stephan
Hohe.

@item 
bpo-35214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35214}: clang Memory Sanitizer build instrumentation was added to work
around false positives from posix, socket, time, test_io, and
test_faulthandler.

@item 
bpo-35560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35560}: Fix an assertion error in @ref{60a,,format()} in debug build for
floating-point formatting with "n" format, zero padding and small width.
Release build is not impacted. Patch by Karthikeyan Singaravelan.

@item 
bpo-35552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35552}: Format characters @code{%s} and @code{%V} in
@ref{380,,PyUnicode_FromFormat()} and @code{%s} in @ref{19b7,,PyBytes_FromFormat()}
no longer read memory past the limit if `precision' is specified.

@item 
bpo-35504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35504}: Fix segfaults and @ref{561,,SystemError}s when deleting certain
attributes. Patch by Zackery Spytz.

@item 
bpo-35504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35504}: Fixed a SystemError when delete the characters_written
attribute of an OSError.

@item 
bpo-35494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35494}: Improved syntax error messages for unbalanced parentheses in
f-string.

@item 
bpo-35444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35444}: Fixed error handling in pickling methods when fail to look up
builtin "getattr". Sped up pickling iterators.

@item 
bpo-35436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35436}: Fix various issues with memory allocation error handling.
Patch by Zackery Spytz.

@item 
bpo-35423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35423}: Separate the signal handling trigger in the eval loop from the
"pending calls" machinery. There is no semantic change and the difference
in performance is insignificant.

@item 
bpo-35357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35357}: Internal attributes' names of unittest.mock._Call and
unittest.mock.MagicProxy (name, parent & from_kall) are now prefixed with
_mock_ in order to prevent clashes with widely used object attributes.
Fixed minor typo in test function name.

@item 
bpo-35372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35372}: Fixed the code page decoder for input longer than 2 GiB
containing undecodable bytes.

@item 
bpo-35336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35336}: Fix PYTHONCOERCECLOCALE=1 environment variable: only coerce the
C locale if the LC_CTYPE locale is "C".

@item 
bpo-31241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31241}: The `lineno' and `col_offset' attributes of AST nodes for list
comprehensions, generator expressions and tuples are now point to the
opening parenthesis or square brace. For tuples without parenthesis they
point to the position of the first item.

@item 
bpo-33954@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33954}: For @ref{60c,,str.format()}, @code{float.__format__()} and
@code{complex.__format__()} methods for non-ASCII decimal point when using
the "n" formatter.

@item 
bpo-35269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35269}: Fix a possible segfault involving a newly created coroutine.
Patch by Zackery Spytz.

@item 
bpo-35224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35224}: Implement 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} (assignment expressions). Patch by Emily
Morehouse.

@item 
bpo-32492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32492}: Speed up @code{namedtuple()} attribute access by 1.6x using a C
fast-path for the name descriptors. Patch by Pablo Galindo.

@item 
bpo-35214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35214}: Fixed an out of bounds memory access when parsing a truncated
unicode escape sequence at the end of a string such as @code{'\N'}.  It would
read one byte beyond the end of the memory allocation.

@item 
bpo-35214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35214}: The interpreter and extension modules have had annotations
added so that they work properly under clang's Memory Sanitizer.  A new
configure flag --with-memory-sanitizer has been added to make test builds
of this nature easier to perform.

@item 
bpo-35193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35193}: Fix an off by one error in the bytecode peephole optimizer
where it could read bytes beyond the end of bounds of an array when
removing unreachable code. This bug was present in every release of Python
3.6 and 3.7 until now.

@item 
bpo-35169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35169}: Improved error messages for forbidden assignments.

@item 
bpo-34022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34022}: Fix handling of hash-based bytecode files in @ref{131,,zipimport}.
Patch by Elvis Pranskevichus.

@item 
bpo-28401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28401}: Debug builds will no longer to attempt to import extension
modules built for the ABI as they were never compatible to begin with.
Patch by Stefano Rivera.

@item 
bpo-29341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29341}: Clarify in the docstrings of @ref{a0,,os} methods that path-like
objects are also accepted as input parameters.

@item 
bpo-35050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35050}: @ref{cb,,socket}: Fix off-by-one bug in length check for
@code{AF_ALG} name and type.

@item 
bpo-29743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29743}: Raise @ref{1ff,,ValueError} instead of @ref{86d,,OverflowError} in case
of a negative @code{_length_} in a @ref{19b8,,ctypes.Array} subclass.  Also
raise @ref{522,,TypeError} instead of @ref{343,,AttributeError} for non-integer
@code{_length_}. Original patch by Oren Milman.

@item 
bpo-16806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16806}: Fix @code{lineno} and @code{col_offset} for multi-line string tokens.

@item 
bpo-35029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35029}: @ref{44f,,SyntaxWarning} raised as an exception at code generation
time will be now replaced with a @ref{18b,,SyntaxError} for better error
reporting.

@item 
bpo-34983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34983}: Expose @ref{19b9,,symtable.Symbol.is_nonlocal()} in the symtable
module. Patch by Pablo Galindo.

@item 
bpo-34974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34974}: @ref{1bd,,bytes} and @ref{528,,bytearray} constructors no longer
convert unexpected exceptions (e.g. @ref{164b,,MemoryError} and
@ref{9bf,,KeyboardInterrupt}) to @ref{522,,TypeError}.

@item 
bpo-34939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34939}: Allow annotated names in module namespace that are declared
global before the annotation happens. Patch by Pablo Galindo.

@item 
bpo-34973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34973}: Fixed crash in @ref{1bd,,bytes()} when the @ref{5fc,,list} argument is
mutated while it is iterated.

@item 
bpo-34876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34876}: The `lineno' and `col_offset' attributes of the AST for
decorated function and class refer now to the position of the
corresponding @code{def}, @code{async def} and @code{class} instead of the position
of the first decorator. This leads to more correct line reporting in
tracing. This is the only case when the position of child AST nodes can
precede the position of the parent AST node.

@item 
bpo-34879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34879}: Fix a possible null pointer dereference in bytesobject.c.
Patch by Zackery Spytz.

@item 
bpo-34784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34784}: Fix the implementation of PyStructSequence_NewType in order to
create heap allocated StructSequences.

@item 
bpo-32912@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32912}: A @ref{44f,,SyntaxWarning} is now emitted instead of a
@ref{1a3,,DeprecationWarning} for invalid escape sequences in string and bytes
literals.

@item 
bpo-34854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34854}: Fixed a crash in compiling string annotations containing a
lambda with a keyword-only argument that doesn't have a default value.

@item 
bpo-34850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34850}: The compiler now produces a @ref{44f,,SyntaxWarning} when identity
checks (@code{is} and @code{is not}) are used with certain types of literals
(e.g. strings, ints).  These can often work by accident in CPython, but
are not guaranteed by the language spec.  The warning advises users to use
equality tests (@code{==} and @code{!=}) instead.

@item 
bpo-34824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34824}: Fix a possible null pointer dereference in Modules/_ssl.c.
Patch by Zackery Spytz.

@item 
bpo-30156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30156}: The C function @code{property_descr_get()} uses a "cached" tuple
to optimize function calls. But this tuple can be discovered in debug mode
with @ref{41b,,sys.getobjects()}. Remove the optimization, it's not really
worth it and it causes 3 different crashes last years.

@item 
bpo-34762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34762}: Fix contextvars C API to use PyObject* pointer types.

@item 
bpo-34751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34751}: The hash function for tuples is now based on xxHash which gives
better collision results on (formerly) pathological cases. Additionally,
on 64-bit systems it improves tuple hashes in general. Patch by Jeroen
Demeyer with substantial contributions by Tim Peters.

@item 
bpo-34735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34735}: Fix a memory leak in Modules/timemodule.c.  Patch by Zackery
Spytz.

@item 
bpo-34683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34683}: Fixed a bug where some SyntaxError error pointed to locations
that were off-by-one.

@item 
bpo-34651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34651}: Only allow the main interpreter to fork.  The avoids the
possibility of affecting the main interpreter, which is critical to
operation of the runtime.

@item 
bpo-34653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34653}: Remove unused function PyParser_SimpleParseStringFilename.

@item 
bpo-32236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32236}: Warn that line buffering is not supported if @ref{505,,open()} is
called with binary mode and @code{buffering=1}.

@item 
bpo-34641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34641}: Further restrict the syntax of the left-hand side of keyword
arguments in function calls. In particular, @code{f((keyword)=arg)} is now
disallowed.

@item 
bpo-34637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34637}: Make the `start' argument to `sum()' visible as a keyword
argument.

@item 
bpo-1621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1621}: Do not assume signed integer overflow behavior (C undefined
behavior) when performing set hash table resizing.

@item 
bpo-34588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34588}: Fix an off-by-one in the recursive call pruning feature of
traceback formatting.

@item 
bpo-34485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34485}: On Windows, the LC_CTYPE is now set to the user preferred
locale at startup. Previously, the LC_CTYPE locale was "C" at startup, but
changed when calling setlocale(LC_CTYPE, "") or setlocale(LC_ALL, "").

@item 
bpo-34485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34485}: Standard streams like sys.stdout now use the "surrogateescape"
error handler, instead of "strict", on the POSIX locale (when the C locale
is not coerced and the UTF-8 Mode is disabled).

@item 
bpo-34485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34485}: Fix the error handler of standard streams like sys.stdout:
PYTHONIOENCODING=":" is now ignored instead of setting the error handler
to "strict".

@item 
bpo-34485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34485}: Python now gets the locale encoding with C code to initialize
the encoding of standard streams like sys.stdout. Moreover, the encoding
is now initialized to the Python codec name to get a normalized encoding
name and to ensure that the codec is loaded. The change avoids importing
_bootlocale and _locale modules at startup by default.

@item 
bpo-34527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34527}: On FreeBSD, Py_DecodeLocale() and Py_EncodeLocale() now also
forces the ASCII encoding if the LC_CTYPE locale is "POSIX", not only if
the LC_CTYPE locale is "C".

@item 
bpo-34527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34527}: The UTF-8 Mode is now also enabled by the "POSIX" locale, not
only by the "C" locale.

@item 
bpo-34403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34403}: On HP-UX with C or POSIX locale, sys.getfilesystemencoding()
now returns "ascii" instead of "roman8" (when the UTF-8 Mode is disabled
and the C locale is not coerced).

@item 
bpo-34523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34523}: The Python filesystem encoding is now read earlier during the
Python initialization.

@item 
bpo-12458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12458}: Tracebacks show now correct line number for subexpressions in
multiline expressions. Tracebacks show now the line number of the first
line for multiline expressions instead of the line number of the last
subexpression.

@item 
bpo-34408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34408}: Prevent a null pointer dereference and resource leakage in
@code{PyInterpreterState_New()}.

@item 
bpo-34400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34400}: Fix undefined behavior in parsetok.c.  Patch by Zackery Spytz.

@item 
bpo-33073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33073}: Added as_integer_ratio to ints to make them more interoperable
with floats.

@item 
bpo-34377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34377}: Update valgrind suppression list to use
@code{_PyObject_Free}/@code{_PyObject_Realloc} instead of
@code{PyObject_Free}/@code{PyObject_Realloc}.

@item 
bpo-34353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34353}: Added the "socket" option in the @code{stat.filemode()} Python
implementation to match the C implementation.

@item 
bpo-34320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34320}: Fix @code{dict(od)} didn't copy iteration order of OrderedDict.

@item 
bpo-34113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34113}: Fixed crash on debug builds when opcode stack was adjusted with
negative numbers. Patch by Constantin Petrisor.

@item 
bpo-34100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34100}: Compiler now merges constants in tuples and frozensets
recursively. Code attributes like @code{co_names} are merged too.

@item 
bpo-34151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34151}: Performance of list concatenation, repetition and slicing
operations is slightly improved. Patch by Sergey Fedoseev.

@item 
bpo-34170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34170}: -X dev: it is now possible to override the memory allocator
using PYTHONMALLOC even if the developer mode is enabled.

@item 
bpo-33237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33237}: Improved @ref{343,,AttributeError} message for partially
initialized module.

@item 
bpo-34149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34149}: Fix min and max functions to get default behavior when key is
None.

@item 
bpo-34125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34125}: Profiling of unbound built-in methods now works when
@code{**kwargs} is given.

@item 
bpo-34141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34141}: Optimized pickling atomic types (None, bool, int, float, bytes,
str).

@item 
bpo-34126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34126}: Fix crashes when profiling certain invalid calls of unbound
methods. Patch by Jeroen Demeyer.

@item 
bpo-24618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24618}: Fixed reading invalid memory when create the code object with
too small varnames tuple or too large argument counts.

@item 
bpo-34068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34068}: In @ref{1f3,,io.IOBase.close()}, ensure that the
@ref{19ba,,closed} attribute is not set with a live exception.
Patch by Zackery Spytz and Serhiy Storchaka.

@item 
bpo-34087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34087}: Fix buffer overflow while converting unicode to numeric values.

@item 
bpo-34080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34080}: Fixed a memory leak in the compiler when it raised some
uncommon errors during tokenizing.

@item 
bpo-34066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34066}: Disabled interruption by Ctrl-C between calling @code{open()} and
entering a `with' block in @code{with open()}.

@item 
bpo-34042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34042}: Fix dict.copy() to maintain correct total refcount (as reported
by sys.gettotalrefcount()).

@item 
bpo-33418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33418}: Fix potential memory leak in function object when it creates
reference cycle.

@item 
bpo-33985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33985}: Implement contextvars.ContextVar.name attribute.

@item 
bpo-33956@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33956}: Update vendored Expat library copy to version 2.2.5.

@item 
bpo-24596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24596}: Decref the module object in @ref{1896,,PyRun_SimpleFileExFlags()}
before calling @ref{18d2,,PyErr_Print()}.  Patch by Zackery Spytz.

@item 
bpo-33451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33451}: Close directly executed pyc files before calling
@code{PyEval_EvalCode()}.

@item 
bpo-1617161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1617161}: The hash of @code{BuiltinMethodType} instances (methods of
built-in classes) now depends on the hash of the identity of `__self__'
instead of its value. The hash and equality of @code{ModuleType} and
@code{MethodWrapperType} instances (methods of user-defined classes and
some methods of built-in classes like @code{str.__add__}) now depend on the
hash and equality of the identity of `__self__' instead of its value.
@code{MethodWrapperType} instances no longer support ordering.

@item 
bpo-33824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33824}: Fix "LC_ALL=C python3.7 -V": reset properly the command line
parser when the encoding changes after reading the Python configuration.

@item 
bpo-33803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33803}: Fix a crash in hamt.c caused by enabling GC tracking for an
object that hadn't all of its fields set to NULL.

@item 
bpo-33738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33738}: Seven macro incompatibilities with the Limited API were fixed,
and the macros @ref{1882,,PyIter_Check()}, @ref{977,,PyIndex_Check()} and
@code{PyExceptionClass_Name()} were added as functions. A script for
automatic macro checks was added.

@item 
bpo-33786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33786}: Fix asynchronous generators to handle GeneratorExit in athrow()
correctly

@item 
bpo-30167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30167}: @code{PyRun_SimpleFileExFlags} removes @code{__cached__} from module
in addition to @code{__file__}.

@item 
bpo-33706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33706}: Fix a crash in Python initialization when parsing the command
line options. Thanks Christoph Gohlke for the bug report and the fix!

@item 
bpo-33597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33597}: Reduce @code{PyGC_Head} size from 3 words to 2 words.

@item 
bpo-30654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30654}: Fixed reset of the SIGINT handler to SIG_DFL on interpreter
shutdown even when there was a custom handler set previously. Patch by
Philipp Kerling.

@item 
bpo-33622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33622}: Fixed a leak when the garbage collector fails to add an object
with the @code{__del__} method or referenced by it into the
@ref{119e,,gc.garbage} list. @ref{97b,,PyGC_Collect()} can now be called when an
exception is set and preserves it.

@item 
bpo-33462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33462}: Make dict and dict views reversible. Patch by Rémi Lapeyre.

@item 
bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}: A @ref{193,,RuntimeError} is now raised when the custom metaclass
doesn't provide the @code{__classcell__} entry in the namespace passed to
@code{type.__new__}.  A @ref{1a3,,DeprecationWarning} was emitted in Python
3.6--3.7.

@item 
bpo-33499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33499}: Add 
@geindex PYTHONPYCACHEPREFIX
@geindex variable d'environnement; PYTHONPYCACHEPREFIX
@ref{991,,PYTHONPYCACHEPREFIX} environment variable and
@ref{175,,-X} @code{pycache_prefix} command-line option to set an alternate
root directory for writing module bytecode cache files.

@item 
bpo-25711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25711}: The @ref{131,,zipimport} module has been rewritten in pure Python.

@item 
bpo-33509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33509}: Fix module_globals parameter of warnings.warn_explicit(): don't
crash if module_globals is not a dict.

@item 
bpo-31849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31849}: Fix signed/unsigned comparison warning in pyhash.c.

@item 
bpo-33475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33475}: Fixed miscellaneous bugs in converting annotations to strings
and optimized parentheses in the string representation.

@item 
bpo-20104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20104}: Added support for the @code{setpgroup}, @code{resetids},
@code{setsigmask}, @code{setsigdef} and @code{scheduler} parameters of
@code{posix_spawn}. Patch by Pablo Galindo.

@item 
bpo-33391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33391}: Fix a leak in set_symmetric_difference().

@item 
bpo-33363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33363}: Raise a SyntaxError for @code{async with} and @code{async for}
statements outside of async functions.

@item 
bpo-28055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28055}: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

@item 
bpo-33128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33128}: Fix a bug that causes PathFinder to appear twice on
sys.meta_path. Patch by Pablo Galindo Salgado.

@item 
bpo-33331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33331}: Modules imported last are now cleared first at interpreter
shutdown.

@item 
bpo-33312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33312}: Fixed clang ubsan (undefined behavior sanitizer) warnings in
dictobject.c by adjusting how the internal struct _dictkeysobject shared
keys structure is declared.

@item 
bpo-33305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33305}: Improved syntax error messages for invalid numerical literals.

@item 
bpo-33306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33306}: Improved syntax error messages for unbalanced parentheses.

@item 
bpo-33234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33234}: The list constructor will pre-size and not over-allocate when
the input length is known.

@item 
bpo-33270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33270}: Intern the names for all anonymous code objects.  Patch by
Zackery Spytz.

@item 
bpo-30455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30455}: The C and Python code and the documentation related to tokens
are now generated from a single source file @code{Grammar/Tokens}.

@item 
bpo-33176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33176}: Add a @code{toreadonly()} method to memoryviews.

@item 
bpo-33231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33231}: Fix potential memory leak in @code{normalizestring()}.

@item 
bpo-33205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33205}: Change dict growth function from
@code{round_up_to_power_2(used*2+hashtable_size/2)} to
@code{round_up_to_power_2(used*3)}.  Previously, dict is shrinked only when
@code{used == 0}. Now dict has more chance to be shrinked.

@item 
bpo-29922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29922}: Improved error messages in 'async with' when @code{__aenter__()}
or @code{__aexit__()} return non-awaitable object.

@item 
bpo-33199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33199}: Fix @code{ma_version_tag} in dict implementation is uninitialized
when copying from key-sharing dict.

@item 
bpo-33053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33053}: When using the -m switch, sys.path[0] is now explicitly
expanded as the `starting' working directory, rather than being left as
the empty path (which allows imports from the current working directory at
the time of the import)

@item 
bpo-33138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33138}: Changed standard error message for non-pickleable and
non-copyable types. It now says "cannot pickle" instead of "can't pickle"
or "cannot serialize".

@item 
bpo-33018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33018}: Improve consistency of errors raised by @code{issubclass()} when
called with a non-class and an abstract base class as the first and second
arguments, respectively. Patch by Josh Bronson.

@item 
bpo-33083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33083}: @code{math.factorial} no longer accepts arguments that are not
int-like. Patch by Pablo Galindo.

@item 
bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}: Added new opcode @ref{a98,,END_ASYNC_FOR} and fixes the
following issues:


@itemize *

@item 
Setting global @ref{19bb,,StopAsyncIteration} no longer breaks @code{async for}
loops.

@item 
Jumping into an @code{async for} loop is now disabled.

@item 
Jumping out of an @code{async for} loop no longer corrupts the stack.
@end itemize

@item 
bpo-25750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25750}: Fix rare Python crash due to bad refcounting in
@code{type_getattro()} if a descriptor deletes itself from the class. Patch
by Jeroen Demeyer.

@item 
bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}: Fixed bytecode generation for "async for" with a complex
target. A StopAsyncIteration raised on assigning or unpacking will be now
propagated instead of stopping the iteration.

@item 
bpo-33026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33026}: Fixed jumping out of "with" block by setting f_lineno.

@item 
bpo-33005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33005}: Fix a crash on fork when using a custom memory allocator (ex:
using PYTHONMALLOC env var). _PyGILState_Reinit() and
_PyInterpreterState_Enable() now use the default RAW memory allocator to
allocate a new interpreters mutex on fork.

@item 
bpo-32911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32911}: Due to unexpected compatibility issues discovered during
downstream beta testing, reverted bpo-29463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29463}. @code{docstring} field is
removed from Module, ClassDef, FunctionDef, and AsyncFunctionDef ast nodes
which was added in 3.7a1.  Docstring expression is restored as a first
statement in their body. Based on patch by Inada Naoki.

@item 
bpo-17288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17288}: Prevent jumps from 'return' and 'exception' trace events.

@item 
bpo-32946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32946}: Importing names from already imported module with "from ...
import ..." is now 30% faster if the module is not a package.

@item 
bpo-32932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32932}: Make error message more revealing when there are non-str
objects in @code{__all__}.

@item 
bpo-32925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32925}: Optimized iterating and containing test for literal lists
consisting of non-constants: @code{x in [a, b]} and @code{for x in [a, b]}. The
case of all constant elements already was optimized.

@item 
bpo-32889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32889}: Update Valgrind suppression list to account for the rename of
@code{Py_ADDRESS_IN_RANG} to @code{address_in_range}.

@item 
bpo-32836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32836}: Don't use temporary variables in cases of list/dict/set
comprehensions

@item 
bpo-31356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31356}: Remove the new API added in bpo-31356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31356} (gc.ensure_disabled()
context manager).

@item 
bpo-32305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32305}: For namespace packages, ensure that both @code{__file__} and
@code{__spec__.origin} are set to None.

@item 
bpo-32303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32303}: Make sure @code{__spec__.loader} matches @code{__loader__} for
namespace packages.

@item 
bpo-32711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32711}: Fix the warning messages for Python/ast_unparse.c. Patch by
Stéphane Wirtel

@item 
bpo-32583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32583}: Fix possible crashing in builtin Unicode decoders caused by
write out-of-bound errors when using customized decode error handlers.

@item 
bpo-32489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32489}: A @ref{9b7,,continue} statement is now allowed in the
@ref{9b8,,finally} clause.

@item 
bpo-17611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17611}: Simplified the interpreter loop by moving the logic of
unrolling the stack of blocks into the compiler. The compiler emits now
explicit instructions for adjusting the stack of values and calling the
cleaning up code for @ref{a97,,break}, @ref{9b7,,continue} and
@ref{9bc,,return}.

Removed opcodes @code{BREAK_LOOP}, @code{CONTINUE_LOOP},
@code{SETUP_LOOP} and @code{SETUP_EXCEPT}. Added new opcodes
@code{ROT_FOUR}, @code{BEGIN_FINALLY} and @code{CALL_FINALLY} and
@code{POP_FINALLY}. Changed the behavior of @code{END_FINALLY} and
@code{WITH_CLEANUP_START}.

@item 
bpo-32285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32285}: New function unicodedata.is_normalized, which can check whether
a string is in a specific normal form.

@item 
bpo-10544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10544}: Yield expressions are now disallowed in comprehensions and
generator expressions except the expression for the outermost iterable.

@item 
bpo-32117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32117}: Iterable unpacking is now allowed without parentheses in yield
and return statements, e.g. @code{yield 1, 2, 3, *rest}. Thanks to David
Cuthbert for the change and Jordan Chapman for added tests.

@item 
bpo-31902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31902}: Fix the @code{col_offset} attribute for ast nodes
@code{ast.AsyncFor}, @code{ast.AsyncFunctionDef}, and @code{ast.AsyncWith}.
Previously, @code{col_offset} pointed to the keyword after @code{async}.

@item 
bpo-25862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25862}: Fix assertion failures in the @code{tell()} method of
@code{io.TextIOWrapper}. Patch by Zackery Spytz.

@item 
bpo-21983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21983}: Fix a crash in @code{ctypes.cast()} in case the type argument is a
ctypes structured data type. Patch by Eryk Sun and Oren Milman.

@item 
bpo-31577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31577}: Fix a crash in @code{os.utime()} in case of a bad ns argument.
Patch by Oren Milman.

@item 
bpo-29832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29832}: Remove references to 'getsockaddrarg' from various socket error
messages. Patch by Oren Milman.
@end itemize

@node Library<51>,Documentation<46>,Core and Builtins<52>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id457}@anchor{19bc}
@subsubsection Library



@itemize -

@item 
bpo-35845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35845}: Add 'order' parameter to memoryview.tobytes().

@item 
bpo-35864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35864}: The _asdict() method for collections.namedtuple now returns a
regular dict instead of an OrderedDict.

@item 
bpo-35537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35537}: An ExitStack is now used internally within subprocess.Popen to
clean up pipe file handles. No behavior change in normal operation. But if
closing one handle were ever to cause an exception, the others will now be
closed instead of leaked.  (patch by Giampaolo Rodola)

@item 
bpo-35847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35847}: RISC-V needed the CTYPES_PASS_BY_REF_HACK.  Fixes ctypes
Structure test_pass_by_value.

@item 
bpo-35813@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35813}: Shared memory submodule added to multiprocessing to avoid need
for serialization between processes

@item 
bpo-35780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35780}: Fix lru_cache() errors arising in recursive, reentrant, or
multi-threaded code. These errors could result in orphan links and in the
cache being trapped in a state with fewer than the specified maximum
number of links. Fix handling of negative maxsize which should have been
treated as zero. Fix errors in toggling the "full" status flag. Fix
misordering of links when errors are encountered.  Sync-up the C code and
pure Python code for the space saving path in functions with a single
positional argument. In this common case, the space overhead of an lru
cache entry is reduced by almost half.  Fix counting of cache misses. In
error cases, the miss count was out of sync with the actual number of
times the underlying user function was called.

@item 
bpo-35537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35537}: @ref{21d,,os.posix_spawn()} and @ref{19bd,,os.posix_spawnp()} now have a
`setsid' parameter.

@item 
bpo-23846@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23846}: @ref{5f4,,asyncio.ProactorEventLoop} now catches and logs send
errors when the self-pipe is full.

@item 
bpo-34323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34323}: @ref{a,,asyncio}: Enhance @code{IocpProactor.close()} log: wait 1
second before the first log, then log every second. Log also the number of
seconds since @code{close()} was called.

@item 
bpo-35674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35674}: Add a new @ref{19bd,,os.posix_spawnp()} function. Patch by Joannah
Nanjekye.

@item 
bpo-35733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35733}: @code{ast.Constant(boolean)} no longer an instance of
@code{ast.Num}.  Patch by Anthony Sottile.

@item 
bpo-35726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35726}: QueueHandler.prepare() now makes a copy of the record before
modifying and enqueueing it, to avoid affecting other handlers in the
chain.

@item 
bpo-35719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35719}: Sped up multi-argument @ref{8d,,math} functions atan2(),
copysign(), remainder() and hypot() by 1.3--2.5 times.

@item 
bpo-35717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35717}: Fix KeyError exception raised when using enums and compile.
Patch contributed by Rémi Lapeyre.

@item 
bpo-35699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35699}: Fixed detection of Visual Studio Build Tools 2017 in distutils

@item 
bpo-32710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32710}: Fix memory leaks in asyncio ProactorEventLoop on overlapped
operation failure.

@item 
bpo-35702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35702}: The @ref{a31,,time.CLOCK_UPTIME_RAW} constant is now available
for macOS 10.12.

@item 
bpo-32710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32710}: Fix a memory leak in asyncio in the ProactorEventLoop when
@code{ReadFile()} or @code{WSASend()} overlapped operation fail immediately:
release the internal buffer.

@item 
bpo-35682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35682}: Fix @code{asyncio.ProactorEventLoop.sendfile()}: don't attempt to
set the result of an internal future if it's already done.

@item 
bpo-35283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35283}: Add a deprecated warning for the
@code{threading.Thread.isAlive()} method. Patch by Donghee Na.

@item 
bpo-35664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35664}: Improve operator.itemgetter() performance by 33% with optimized
argument handling and with adding a fast path for the common case of a
single non-negative integer index into a tuple (which is the typical use
case in the standard library).

@item 
bpo-35643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35643}: Fixed a SyntaxWarning: invalid escape sequence in
Modules/_sha3/cleanup.py. Patch by Mickaël Schoentgen.

@item 
bpo-35619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35619}: Improved support of custom data descriptors in @ref{8c4,,help()} and
@ref{b4,,pydoc}.

@item 
bpo-28503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28503}: The @code{crypt} module now internally uses the @code{crypt_r()}
library function instead of @code{crypt()} when available.

@item 
bpo-35614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35614}: Fixed help() on metaclasses. Patch by Sanyam Khurana.

@item 
bpo-35568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35568}: Expose @code{raise(signum)} as @code{raise_signal}

@item 
bpo-35588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35588}: The floor division and modulo operations and the @ref{98f,,divmod()}
function on @ref{1e4,,fractions.Fraction} types are 2--4x faster. Patch by
Stefan Behnel.

@item 
bpo-35585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35585}: Speed-up building enums by value, e.g. http.HTTPStatus(200).

@item 
bpo-30561@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30561}: random.gammavariate(1.0, beta) now computes the same result as
random.expovariate(1.0 / beta).  This synchronizes the two algorithms and
eliminates some idiosyncrasies in the old implementation.  It does however
produce a difference stream of random variables than it used to.

@item 
bpo-35537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35537}: The @ref{d5,,subprocess} module can now use the
@ref{21d,,os.posix_spawn()} function in some cases for better performance.

@item 
bpo-35526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35526}: Delaying the 'joke' of barry_as_FLUFL.mandatory to Python
version 4.0

@item 
bpo-35523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35523}: Remove @ref{2a,,ctypes} callback workaround: no longer create a
callback at startup. Avoid SELinux alert on @code{import ctypes} and @code{import
uuid}.

@item 
bpo-31784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31784}: @ref{b96,,uuid.uuid1()} now calls @ref{ad5,,time.time_ns()} rather than
@code{int(time.time() * 1e9)}.

@item 
bpo-35513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35513}: @code{TextTestRunner} of
@code{unittest.runner} now uses @ref{a76,,time.perf_counter()} rather than
@ref{251,,time.time()} to measure the execution time of a test:
@ref{251,,time.time()} can go backwards, whereas @ref{a76,,time.perf_counter()} is
monotonic.

@item 
bpo-35502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35502}: Fixed reference leaks in
@ref{a43,,xml.etree.ElementTree.TreeBuilder} in case of unfinished building
of the tree (in particular when an error was raised during parsing XML).

@item 
bpo-35348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35348}: Make @ref{1614,,platform.architecture()} parsing of @code{file} command
output more reliable: add the @code{-b} option to the @code{file} command to
omit the filename, force the usage of the C locale, and search also the
"shared object" pattern.

@item 
bpo-35491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35491}: @ref{93,,multiprocessing}: Add @code{Pool.__repr__()} and enhance
@code{BaseProcess.__repr__()} (add pid and parent pid) to ease debugging.
Pool state constant values are now strings instead of integers, for
example @code{RUN} value becomes @code{'RUN'} instead of @code{0}.

@item 
bpo-35477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35477}: @code{multiprocessing.Pool.__enter__()} now fails if the pool is
not running: @code{with pool:} fails if used more than once.

@item 
bpo-31446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31446}: Copy command line that was passed to CreateProcessW since this
function can change the content of the input buffer.

@item 
bpo-35471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35471}: Python 2.4 dropped MacOS 9 support. The macpath module was
deprecated in Python 3.7. The module is now removed.

@item 
bpo-23057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23057}: Unblock Proactor event loop when keyboard interrupt is received
on Windows

@item 
bpo-35052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35052}: Fix xml.dom.minidom cloneNode() on a document with an entity:
pass the correct arguments to the user data handler of an entity.

@item 
bpo-20239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20239}: Allow repeated assignment deletion of
@ref{a3a,,unittest.mock.Mock} attributes. Patch by Pablo Galindo.

@item 
bpo-17185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17185}: Set @code{__signature__} on mock for @ref{7d,,inspect} to get
signature. Patch by Karthikeyan Singaravelan.

@item 
bpo-35445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35445}: Memory errors during creating posix.environ no longer ignored.

@item 
bpo-35415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35415}: Validate fileno= argument to socket.socket().

@item 
bpo-35424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35424}: @code{multiprocessing.Pool} destructor now emits
@ref{241,,ResourceWarning} if the pool is still running.

@item 
bpo-35330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35330}: When a @code{Mock} instance was used to wrap an object, if
@code{side_effect} is used in one of the mocks of it methods, don't call the
original implementation and return the result of using the side effect the
same way that it is done with return_value.

@item 
bpo-35346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35346}: Drop Mac OS 9 and Rhapsody support from the @ref{a9,,platform}
module. Rhapsody last release was in 2000. Mac OS 9 last release was in
2001.

@item 
bpo-10496@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10496}: @code{check_environ()} of @code{distutils.utils}
now catches @ref{33a,,KeyError} on calling @ref{19be,,pwd.getpwuid()}: don't create
the @code{HOME} environment variable in this case.

@item 
bpo-10496@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10496}: @code{posixpath.expanduser()} now returns the input `path'
unchanged if the @code{HOME} environment variable is not set and the current
user has no home directory (if the current user identifier doesn't exist
in the password database). This change fix the @ref{c6,,site} module if the
current user doesn't exist in the password database (if the user has no
home directory).

@item 
bpo-35389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35389}: @ref{19bf,,platform.libc_ver()} now uses
@code{os.confstr('CS_GNU_LIBC_VERSION')} if available and the `executable'
parameter is not set.

@item 
bpo-35394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35394}: Add empty slots to asyncio abstract protocols.

@item 
bpo-35310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35310}: Fix a bug in @ref{d8d,,select.select()} where, in some cases, the
file descriptor sequences were returned unmodified after a signal
interruption, even though the file descriptors might not be ready yet.
@ref{d8d,,select.select()} will now always return empty lists if a timeout has
occurred.  Patch by Oran Avraham.

@item 
bpo-35380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35380}: Enable TCP_NODELAY on Windows for proactor asyncio event loop.

@item 
bpo-35341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35341}: Add generic version of @code{collections.OrderedDict} to the
@code{typing} module. Patch by Ismo Toijala.

@item 
bpo-35371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35371}: Fixed possible crash in @code{os.utime()} on Windows when pass
incorrect arguments.

@item 
bpo-35346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35346}: @ref{19c0,,platform.uname()} now redirects @code{stderr} to
@ref{19c1,,os.devnull} when running external programs like @code{cmd /c ver}.

@item 
bpo-35066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35066}: Previously, calling the strftime() method on a datetime object
with a trailing '%' in the format string would result in an exception.
However, this only occurred when the datetime C module was being used; the
python implementation did not match this behavior. Datetime is now PEP-399
compliant, and will not throw an exception on a trailing '%'.

@item 
bpo-35345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35345}: The function @code{platform.popen} has been removed, it was
deprecated since Python 3.3: use @ref{a75,,os.popen()} instead.

@item 
bpo-35344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35344}: On macOS, @ref{16e3,,platform.platform()} now uses
@ref{19c2,,platform.mac_ver()}, if it returns a non-empty release string, to get
the macOS version rather than the darwin version.

@item 
bpo-35312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35312}: Make @code{lib2to3.pgen2.parse.ParseError} round-trip pickle-able.
Patch by Anthony Sottile.

@item 
bpo-35308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35308}: Fix regression in @code{webbrowser} where default browsers may be
preferred over browsers in the @code{BROWSER} environment variable.

@item 
bpo-24746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24746}: Avoid stripping trailing whitespace in doctest fancy diff.
Original patch by R. David Murray & Jairo Trad. Enhanced by Sanyam
Khurana.

@item 
bpo-28604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28604}: @ref{bec,,locale.localeconv()} now sets temporarily the @code{LC_CTYPE}
locale to the @code{LC_MONETARY} locale if the two locales are different and
monetary strings are non-ASCII. This temporary change affects other
threads.

@item 
bpo-35277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35277}: Update ensurepip to install pip 18.1 and setuptools 40.6.2.

@item 
bpo-24209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24209}: Adds IPv6 support when invoking http.server directly.

@item 
bpo-35226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35226}: Recursively check arguments when testing for equality of
@ref{195c,,unittest.mock.call} objects and add note that tracking of
parameters used to create ancestors of mocks in @code{mock_calls} is not
possible.

@item 
bpo-29564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29564}: The warnings module now suggests to enable tracemalloc if the
source is specified, the tracemalloc module is available, but tracemalloc
is not tracing memory allocations.

@item 
bpo-35189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35189}: Modify the following fnctl function to retry if interrupted by
a signal (EINTR): flock, lockf, fnctl

@item 
bpo-30064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30064}: Use add_done_callback() in sock_* asyncio API to unsubscribe
reader/writer early on calcellation.

@item 
bpo-35186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35186}: Removed the "built with" comment added when @code{setup.py upload}
is used with either @code{bdist_rpm} or @code{bdist_dumb}.

@item 
bpo-35152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35152}: Allow sending more than 2 GB at once on a multiprocessing
connection on non-Windows systems.

@item 
bpo-35062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35062}: Fix incorrect parsing of
@ref{1652,,io.IncrementalNewlineDecoder}'s `translate' argument.

@item 
bpo-35065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35065}: Remove @code{StreamReaderProtocol._untrack_reader}. The call to
@code{_untrack_reader} is currently performed too soon, causing the protocol
to forget about the reader before @code{connection_lost} can run and feed the
EOF to the reader.

@item 
bpo-34160@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34160}: ElementTree and minidom now preserve the attribute order
specified by the user.

@item 
bpo-35079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35079}: Improve difflib.SequenceManager.get_matching_blocks doc by
adding 'non-overlapping' and changing '!=' to '<'.

@item 
bpo-33710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33710}: Deprecated @code{l*gettext()} functions and methods in the
@ref{62,,gettext} module. They return encoded bytes instead of Unicode
strings and are artifacts from Python 2 times. Also deprecated functions
and methods related to setting the charset for @code{l*gettext()} functions
and methods.

@item 
bpo-35017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35017}: @ref{111f,,socketserver.BaseServer.serve_forever()} now exits
immediately if it's @ref{19c3,,shutdown()} method is
called while it is polling for new events.

@item 
bpo-35024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35024}: @code{importlib} no longer logs @code{wrote <bytecode path>}
redundantly after @code{(created|could not create) <bytecode path>} is
already logged. Patch by Quentin Agren.

@item 
bpo-35047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35047}: @code{unittest.mock} now includes mock calls in exception messages
if @code{assert_not_called}, @code{assert_called_once}, or
@code{assert_called_once_with} fails. Patch by Petter Strandmark.

@item 
bpo-31047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31047}: Fix @code{ntpath.abspath} regression where it didn't remove a
trailing separator on Windows. Patch by Tim Graham.

@item 
bpo-35053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35053}: tracemalloc now tries to update the traceback when an object is
reused from a "free list" (optimization for faster object creation, used
by the builtin list type for example).

@item 
bpo-31553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31553}: Add the --json-lines option to json.tool. Patch by hongweipeng.

@item 
bpo-34794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34794}: Fixed a leak in Tkinter when pass the Python wrapper around
Tcl_Obj back to Tcl/Tk.

@item 
bpo-34909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34909}: Enum: fix grandchildren subclassing when parent mixed with
concrete data types.

@item 
bpo-35022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35022}: @ref{e7a,,unittest.mock.MagicMock} now supports the
@code{__fspath__} method (from @ref{c3f,,os.PathLike}).

@item 
bpo-35008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35008}: Fixed references leaks when call the @code{__setstate__()} method
of @ref{305,,xml.etree.ElementTree.Element} in the C implementation for
already initialized element.

@item 
bpo-23420@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23420}: Verify the value for the parameter '-s' of the cProfile CLI.
Patch by Robert Kuska

@item 
bpo-33947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33947}: dataclasses now handle recursive reprs without raising
RecursionError.

@item 
bpo-34890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34890}: Make @ref{2e2,,inspect.iscoroutinefunction()},
@ref{175f,,inspect.isgeneratorfunction()} and @ref{1760,,inspect.isasyncgenfunction()}
work with @ref{40a,,functools.partial()}. Patch by Pablo Galindo.

@item 
bpo-34521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34521}: Use @ref{19c4,,socket.CMSG_SPACE()} to calculate ancillary data size
instead of @ref{19c5,,socket.CMSG_LEN()} in
@code{multiprocessing.reduction.recvfds()} as 
@geindex RFC; RFC 3542
RFC 3542@footnote{https://datatracker.ietf.org/doc/html/rfc3542.html} requires the use
of the former for portable applications.

@item 
bpo-31522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31522}: The @code{mailbox.mbox.get_string} function `from_' parameter can
now successfully be set to a non-default value.

@item 
bpo-34970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34970}: Protect tasks weak set manipulation in @code{asyncio.all_tasks()}

@item 
bpo-34969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34969}: gzip: Add --fast, --best on the gzip CLI, these parameters will
be used for the fast compression method (quick) or the best method
compress (slower, but smaller file). Also, change the default compression
level to 6 (tradeoff).

@item 
bpo-16965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16965}: The 2to3 @code{execfile} fixer now opens the file with mode
@code{'rb'}.  Patch by Zackery Spytz.

@item 
bpo-34966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34966}: @ref{b4,,pydoc} now supports aliases not only to methods defined
in the end class, but also to inherited methods.  The docstring is not
duplicated for aliases.

@item 
bpo-34926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34926}: @ref{19c6,,mimetypes.MimeTypes.guess_type()} now accepts
@ref{29d,,path-like object} in addition to url strings. Patch by Mayank
Asthana.

@item 
bpo-23831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23831}: Add @code{moveto()} method to the @code{tkinter.Canvas} widget. Patch
by Juliette Monsel.

@item 
bpo-34941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34941}: Methods @code{find()}, @code{findtext()} and @code{findall()} of the
@code{Element} class in the @ref{124,,xml.etree.ElementTree} module are now able
to find children which are instances of @code{Element} subclasses.

@item 
bpo-32680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32680}: @ref{91a,,smtplib.SMTP} objects now always have a @code{sock}
attribute present

@item 
bpo-34769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34769}: Fix for async generators not finalizing when event loop is in
debug mode and garbage collector runs in another thread.

@item 
bpo-34936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34936}: Fix @code{TclError} in @code{tkinter.Spinbox.selection_element()}.
Patch by Juliette Monsel.

@item 
bpo-34829@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34829}: Add methods @code{selection_from}, @code{selection_range},
@code{selection_present} and @code{selection_to} to the @code{tkinter.Spinbox} for
consistency with the @code{tkinter.Entry} widget. Patch by Juliette Monsel.

@item 
bpo-34911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34911}: Added `secure_protocols' argument to
`http.cookiejar.DefaultCookiePolicy' to allow for tweaking of protocols
and also to add support by default for `wss', the secure websocket
protocol.

@item 
bpo-34922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34922}: Fixed integer overflow in the @ref{19c7,,digest()} and
@ref{19c8,,hexdigest()} methods for the SHAKE algorithm in the
@ref{67,,hashlib} module.

@item 
bpo-34925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34925}: 25% speedup in argument parsing for the functions in the bisect
module.

@item 
bpo-34900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34900}: Fixed @ref{1822,,unittest.TestCase.debug()} when used to call test
methods with subtests.  Patch by Bruno Oliveira.

@item 
bpo-34844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34844}: logging.Formatter enhancement - Ensure styles and fmt matches
in logging.Formatter - Added validate method in each format style class:
StrFormatStyle, PercentStyle, StringTemplateStyle. - This method is called
in the constructor of logging.Formatter class - Also re-raise the KeyError
in the format method of each style class, so it would a bit clear that
it's an error with the invalid format fields.

@item 
bpo-34897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34897}: Adjust test.support.missing_compiler_executable check so that a
nominal command name of "" is ignored. Patch by Michael Felt.

@item 
bpo-34871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34871}: Fix inspect module polluted @code{sys.modules} when parsing
@code{__text_signature__} of callable.

@item 
bpo-34898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34898}: Add @code{mtime} argument to @code{gzip.compress} for reproducible
output. Patch by Guo Ci Teo.

@item 
bpo-28441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28441}: On Cygwin and MinGW, ensure that @code{sys.executable} always
includes the full filename in the path, including the @code{.exe} suffix
(unless it is a symbolic link).

@item 
bpo-34866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34866}: Adding @code{max_num_fields} to @code{cgi.FieldStorage} to make DOS
attacks harder by limiting the number of @code{MiniFieldStorage} objects
created by @code{FieldStorage}.

@item 
bpo-34711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34711}: http.server ensures it reports HTTPStatus.NOT_FOUND when the
local path ends with "/" and is not a directory, even if the underlying OS
(e.g. AIX) accepts such paths as a valid file reference. Patch by Michael
Felt.

@item 
bpo-34872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34872}: Fix self-cancellation in C implementation of asyncio.Task

@item 
bpo-34849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34849}: Don't log waiting for @code{selector.select} in asyncio loop
iteration. The waiting is pretty normal for any asyncio program, logging
its time just adds a noise to logs without any useful information
provided.

@item 
bpo-34022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34022}: The 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable no longer
overrides the value of the `invalidation_mode' argument to
@ref{a13,,py_compile.compile()}, and determines its default value instead.

@item 
bpo-34819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34819}: Use a monotonic clock to compute timeouts in
@code{Executor.map()} and @code{as_completed()}, in order to prevent
timeouts from deviating when the system clock is adjusted.

@item 
bpo-34758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34758}: Add .wasm -> application/wasm to list of recognized file types
and content type headers

@item 
bpo-34789@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34789}: @ref{19c9,,xml.sax.make_parser()} now accepts any iterable as its
`parser_list' argument.  Patch by Andrés Delfino.

@item 
bpo-34334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34334}: In @code{QueueHandler}, clear @code{exc_text} from
@code{LogRecord} to prevent traceback from being written twice.

@item 
bpo-34687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34687}: On Windows, asyncio now uses ProactorEventLoop, instead of
SelectorEventLoop, by default.

@item 
bpo-5950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5950}: Support reading zip files with archive comments in
@ref{131,,zipimport}.

@item 
bpo-32892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32892}: The parser now represents all constants as
@ref{2b6,,ast.Constant} instead of using specific constant AST types
(@code{Num}, @code{Str}, @code{Bytes}, @code{NameConstant} and @code{Ellipsis}). These
classes are considered deprecated and will be removed in future Python
versions.

@item 
bpo-34728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34728}: Add deprecation warning when @code{loop} is used in methods:
@code{asyncio.sleep}, @code{asyncio.wait} and @code{asyncio.wait_for}.

@item 
bpo-34738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34738}: ZIP files created by @code{distutils} will now include entries for
directories.

@item 
bpo-34659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34659}: Add an optional `initial' argument to itertools.accumulate().

@item 
bpo-29577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29577}: Support multiple mixin classes when creating Enums.

@item 
bpo-34670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34670}: Add SSLContext.post_handshake_auth and
SSLSocket.verify_client_post_handshake for TLS 1.3's post handshake
authentication feature.

@item 
bpo-32718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32718}: The Activate.ps1 script from venv works with PowerShell Core
6.1 and is now available under all operating systems.

@item 
bpo-31177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31177}: Fix bug that prevented using @ref{ce8,,reset_mock} on mock instances with deleted attributes

@item 
bpo-34672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34672}: Add a workaround, so the @code{'Z'} @ref{11c6,,time.strftime()}
specifier on the musl C library can work in some cases.

@item 
bpo-34666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34666}: Implement @code{asyncio.StreamWriter.awrite} and
@code{asyncio.StreamWriter.aclose()} coroutines.  Methods are needed for
providing a consistent stream API with control flow switched on by
default.

@item 
bpo-6721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6721}: Acquire the logging module's commonly used internal locks while
fork()ing to avoid deadlocks in the child process.

@item 
bpo-34658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34658}: Fix a rare interpreter unhandled exception state SystemError
only seen when using subprocess with a preexec_fn while an after_parent
handler has been registered with os.register_at_fork and the fork system
call fails.

@item 
bpo-34652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34652}: Ensure @ref{217,,os.lchmod()} is never defined on Linux.

@item 
bpo-34638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34638}: Store a weak reference to stream reader to break strong
references loop between reader and protocol.  It allows to detect and
close the socket if the stream is deleted (garbage collected) without
@code{close()} call.

@item 
bpo-34536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34536}: @code{Enum._missing_}:  raise @code{ValueError} if None returned and
@code{TypeError} if non-member is returned.

@item 
bpo-34636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34636}: Speed up re scanning of many non-matching characters for s w
and d within bytes objects. (microoptimization)

@item 
bpo-24412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24412}: Add @ref{a3b,,addModuleCleanup()} and
@ref{a3c,,addClassCleanup()} to unittest to support cleanups
for @code{setUpModule()} and
@ref{a3d,,setUpClass()}. Patch by Lisa Roach.

@item 
bpo-34630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34630}: Don't log SSL certificate errors in asyncio code (connection
error logging is skipped already).

@item 
bpo-32490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32490}: Prevent filename duplication in @ref{d5,,subprocess} exception
messages.  Patch by Zackery Spytz.

@item 
bpo-34363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34363}: dataclasses.asdict() and .astuple() now handle namedtuples
correctly.

@item 
bpo-34625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34625}: Update vendorized expat library version to 2.2.6.

@item 
bpo-32270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32270}: The subprocess module no longer mistakenly closes redirected
fds even when they were in pass_fds when outside of the default @{0, 1, 2@}
set.

@item 
bpo-34622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34622}: Create a dedicated @code{asyncio.CancelledError},
@code{asyncio.InvalidStateError} and @code{asyncio.TimeoutError} exception
classes.  Inherit them from corresponding exceptions from
@code{concurrent.futures} package. Extract @code{asyncio} exceptions into a
separate file.

@item 
bpo-34610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34610}: Fixed iterator of @code{multiprocessing.managers.DictProxy}.

@item 
bpo-34421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34421}: Fix distutils logging for non-ASCII strings.  This caused
installation issues on Windows.

@item 
bpo-34604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34604}: Fix possible mojibake in the error message of @code{pwd.getpwnam}
and @code{grp.getgrnam} using string representation because of invisible
characters or trailing whitespaces. Patch by William Grzybowski.

@item 
bpo-30977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30977}: Make uuid.UUID use @code{__slots__} to reduce its memory
footprint. Based on original patch by Wouter Bolsterlee.

@item 
bpo-34574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34574}: OrderedDict iterators are not exhausted during pickling
anymore. Patch by Sergey Fedoseev.

@item 
bpo-8110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8110}: Refactored @ref{d5,,subprocess} to check for Windows-specific
modules rather than @code{sys.platform == 'win32'}.

@item 
bpo-34530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34530}: @code{distutils.spawn.find_executable()} now falls back on
@ref{1990,,os.defpath} if the @code{PATH} environment variable is not set.

@item 
bpo-34563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34563}: On Windows, fix multiprocessing.Connection for very large read:
fix _winapi.PeekNamedPipe() and _winapi.ReadFile() for read larger than
INT_MAX (usually @code{2**31-1}).

@item 
bpo-34558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34558}: Correct typo in Lib/ctypes/_aix.py

@item 
bpo-34282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34282}: Move @code{Enum._convert} to @code{EnumMeta._convert_} and fix enum
members getting shadowed by parent attributes.

@item 
bpo-22872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22872}: When the queue is closed, @ref{1ff,,ValueError} is now raised by
@ref{19ca,,multiprocessing.Queue.put()} and @ref{19cb,,multiprocessing.Queue.get()}
instead of @ref{694,,AssertionError} and @ref{40d,,OSError}, respectively. Patch
by Zackery Spytz.

@item 
bpo-34515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34515}: Fix parsing non-ASCII identifiers in
@code{lib2to3.pgen2.tokenize} (
@geindex Python Enhancement Proposals; PEP 3131
PEP 3131@footnote{https://peps.python.org/pep-3131/}).

@item 
bpo-13312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13312}: Avoids a possible integer underflow (undefined behavior) in the
time module's year handling code when passed a very low negative year
value.

@item 
bpo-34472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34472}: Improved compatibility for streamed files in @ref{130,,zipfile}.
Previously an optional signature was not being written and certain ZIP
applications were not supported. Patch by Silas Sewell.

@item 
bpo-34454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34454}: Fix the .fromisoformat() methods of datetime types crashing
when given unicode with non-UTF-8-encodable code points.  Specifically,
datetime.fromisoformat() now accepts surrogate unicode code points used as
the separator. Report and tests by Alexey Izbyshev, patch by Paul Ganssle.

@item 
bpo-6700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6700}: Fix inspect.getsourcelines for module level frames/tracebacks.
Patch by Vladimir Matveev.

@item 
bpo-34171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34171}: Running the @ref{fc,,trace} module no longer creates the
@code{trace.cover} file.

@item 
bpo-34441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34441}: Fix crash when an @code{ABC}-derived class with invalid
@code{__subclasses__} is passed as the second argument to @ref{7ab,,issubclass()}.
Patch by Alexey Izbyshev.

@item 
bpo-34427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34427}: Fix infinite loop in @code{a.extend(a)} for @code{MutableSequence}
subclasses.

@item 
bpo-34412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34412}: Make @ref{19cc,,signal.strsignal()} work on HP-UX. Patch by Michael
Osipov.

@item 
bpo-20849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20849}: shutil.copytree now accepts a new @code{dirs_exist_ok} keyword
argument. Patch by Josh Bronson.

@item 
bpo-31715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31715}: Associate @code{.mjs} file extension with
@code{application/javascript} MIME Type.

@item 
bpo-34384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34384}: @ref{90d,,os.readlink()} now accepts @ref{29d,,path-like} and @ref{1bd,,bytes} objects on Windows.

@item 
bpo-22602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22602}: The UTF-7 decoder now raises @ref{a01,,UnicodeDecodeError} for
ill-formed sequences starting with "+" (as specified in RFC 2152).  Patch
by Zackery Spytz.

@item 
bpo-2122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2122}: The @ref{a86,,mmap.flush()} method now returns
@code{None} on success, raises an exception on error under all platforms.

@item 
bpo-34341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34341}: Appending to the ZIP archive with the ZIP64 extension no longer
grows the size of extra fields of existing entries.

@item 
bpo-34333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34333}: Fix %-formatting in @ref{15a0,,pathlib.PurePath.with_suffix()} when
formatting an error message.

@item 
bpo-18540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18540}: The @ref{8f0,,imaplib.IMAP4} and @ref{8f1,,imaplib.IMAP4_SSL}
classes now resolve to the local host IP correctly when the default value
of `host' parameter (@code{'@w{'}}) is used.

@item 
bpo-26502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26502}: Implement @code{traceback.FrameSummary.__len__()} method to
preserve compatibility with the old tuple API.

@item 
bpo-34318@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34318}: @ref{516,,assertRaises()},
@ref{518,,assertRaisesRegex()},
@ref{1144,,assertWarns()} and
@ref{1145,,assertWarnsRegex()} no longer success if the
passed callable is None. They no longer ignore unknown keyword arguments
in the context manager mode. A DeprecationWarning was raised in these
cases since Python 3.5.

@item 
bpo-9372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9372}: Deprecate @ref{280,,__getitem__()} methods of
@ref{71f,,xml.dom.pulldom.DOMEventStream}, @ref{720,,wsgiref.util.FileWrapper}
and @ref{721,,fileinput.FileInput}.

@item 
bpo-33613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33613}: Fix a race condition in @code{multiprocessing.semaphore_tracker}
when the tracker receives SIGINT before it can register signal handlers
for ignoring it.

@item 
bpo-34248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34248}: Report filename in the exception raised when the database file
cannot be opened by @ref{19cd,,dbm.gnu.open()} and @ref{19ce,,dbm.ndbm.open()} due to
OS-related error. Patch by Zsolt Cserna.

@item 
bpo-33089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33089}: Add math.dist() to compute the Euclidean distance between two
points.

@item 
bpo-34246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34246}: @ref{e43,,smtplib.SMTP.send_message()} no longer modifies the
content of the `mail_options' argument. Patch by Pablo S. Blum de Aguiar.

@item 
bpo-31047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31047}: Fix @code{ntpath.abspath} for invalid paths on windows. Patch by
Franz Woellert.

@item 
bpo-32321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32321}: Add pure Python fallback for functools.reduce. Patch by Robert
Wright.

@item 
bpo-34270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34270}: The default asyncio task class now always has a name which can
be get or set using two new methods (@ref{9cc,,get_name()} and
@ref{9cb,,set_name()}) and is visible in the @ref{7e7,,repr()} output.
An initial name can also be set using the new @code{name} keyword argument to
@ref{5e7,,asyncio.create_task()} or the
@code{create_task()} method of the event loop.
If no initial name is set, the default Task implementation generates a
name like @code{Task-1} using a monotonic counter.

@item 
bpo-34263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34263}: asyncio's event loop will not pass timeouts longer than one day
to epoll/select etc.

@item 
bpo-34035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34035}: Fix several AttributeError in zipfile seek() methods. Patch by
Mickaël Schoentgen.

@item 
bpo-32215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32215}: Fix performance regression in @ref{ce,,sqlite3} when a DML
statement appeared in a different line than the rest of the SQL query.

@item 
bpo-34075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34075}: Deprecate passing non-ThreadPoolExecutor instances to
@code{AbstractEventLoop.set_default_executor()}.

@item 
bpo-34251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34251}: Restore @code{msilib.Win64} to preserve backwards compatibility
since it's already used by @code{distutils}' @code{bdist_msi} command.

@item 
bpo-19891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19891}: Ignore errors caused by missing / non-writable homedir while
writing history during exit of an interactive session.  Patch by Anthony
Sottile.

@item 
bpo-33089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33089}: Enhanced math.hypot() to support more than two dimensions.

@item 
bpo-34228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34228}: tracemalloc: PYTHONTRACEMALLOC=0 environment variable and -X
tracemalloc=0 command line option are now allowed to disable explicitly
tracemalloc at startup.

@item 
bpo-13041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13041}: Use @ref{10e3,,shutil.get_terminal_size()} to calculate the terminal
width correctly in the @code{argparse.HelpFormatter} class.  Initial patch by
Zbyszek Jędrzejewski-Szmek.

@item 
bpo-34213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34213}: Allow frozen dataclasses to have a field named "object".
Previously this conflicted with an internal use of "object".

@item 
bpo-34052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34052}: @ref{2a7,,sqlite3.Connection.create_aggregate()},
@ref{2a6,,sqlite3.Connection.create_function()},
@ref{2a8,,sqlite3.Connection.set_authorizer()},
@ref{2a9,,sqlite3.Connection.set_progress_handler()} methods raises TypeError
when unhashable objects are passed as callable. These methods now don't
pass such objects to SQLite API. Previous behavior could lead to
segfaults. Patch by Sergey Fedoseev.

@item 
bpo-34197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34197}: Attributes `skipinitialspace', `doublequote' and `strict' of
the `dialect' attribute of the @ref{29,,csv} reader are now @ref{451,,bool}
instances instead of integers 0 or 1.

@item 
bpo-32788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32788}: Errors other than @ref{522,,TypeError} raised in methods
@code{__adapt__()} and @code{__conform__()} in the @ref{ce,,sqlite3} module are now
propagated to the user.

@item 
bpo-21446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21446}: The @code{reload} fixer now uses @ref{502,,importlib.reload()} instead
of deprecated @code{imp.reload()}.

@item 
bpo-940286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=940286}: pydoc's @code{Helper.showtopic()} method now prints the cross
references of a topic correctly.

@item 
bpo-34164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34164}: @ref{100e,,base64.b32decode()} could raise UnboundLocalError or
OverflowError for incorrect padding.  Now it always raises
@code{base64.Error} in these cases.

@item 
bpo-33729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33729}: Fixed issues with arguments parsing in @ref{67,,hashlib}.

@item 
bpo-34097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34097}: ZipFile can zip files older than 1980-01-01 and newer than
2107-12-31 using a new @code{strict_timestamps} parameter at the cost of
setting the timestamp to the limit.

@item 
bpo-34108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34108}: Remove extraneous CR in 2to3 refactor.

@item 
bpo-34070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34070}: Make sure to only check if the handle is a tty, when opening a
file with @code{buffering=-1}.

@item 
bpo-27494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27494}: Reverted bpo-27494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27494}. 2to3 rejects now a trailing comma in
generator expressions.

@item 
bpo-33967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33967}: functools.singledispatch now raises TypeError instead of
IndexError when no positional arguments are passed.

@item 
bpo-34041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34041}: Add the parameter `deterministic' to the
@ref{2a6,,sqlite3.Connection.create_function()} method. Patch by Sergey
Fedoseev.

@item 
bpo-34056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34056}: Ensure the loader shim created by @code{imp.load_module} always
returns bytes from its @code{get_data()} function. This fixes using
@code{imp.load_module} with 
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} hash-based pycs.

@item 
bpo-34054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34054}: The multiprocessing module now uses the monotonic clock
@ref{250,,time.monotonic()} instead of the system clock @ref{251,,time.time()} to
implement timeout.

@item 
bpo-34043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34043}: Optimize tarfile uncompress performance about 15% when gzip is
used.

@item 
bpo-34044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34044}: @code{subprocess.Popen} now copies the `startupinfo' argument to
leave it unchanged: it will modify the copy, so that the same
@code{STARTUPINFO} object can be used multiple times.

@item 
bpo-34010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34010}: Fixed a performance regression for reading streams with
tarfile. The buffered read should use a list, instead of appending to a
bytes object.

@item 
bpo-34019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34019}: webbrowser: Correct the arguments passed to Opera Browser when
opening a new URL using the @code{webbrowser} module. Patch by Bumsik Kim.

@item 
bpo-34003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34003}: csv.DictReader now creates dicts instead of OrderedDicts. Patch
by Michael Selik.

@item 
bpo-33978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33978}: Closed existing logging handlers before reconfiguration via
fileConfig and dictConfig. Patch by Karthikeyan Singaravelan.

@item 
bpo-14117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14117}: Make minor tweaks to turtledemo. The 'wikipedia' example is now
'rosette', describing what it draws.  The 'penrose' print output is
reduced. The'1024' output of 'tree' is eliminated.

@item 
bpo-33974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33974}: Fixed passing lists and tuples of strings containing special
characters @code{"}, @code{\}, @code{@{}, @code{@}} and @code{\n} as options to
@ref{f8,,ttk} widgets.

@item 
bpo-27500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27500}: Fix getaddrinfo to resolve IPv6 addresses correctly.

@item 
bpo-24567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24567}: Improve random.choices() to handle subnormal input weights that
could occasionally trigger an IndexError.

@item 
bpo-33871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33871}: Fixed integer overflow in @ref{b4c,,os.readv()}, @ref{b4f,,os.writev()},
@ref{b4b,,os.preadv()} and @ref{b4e,,os.pwritev()} and in @ref{afd,,os.sendfile()} with
`headers' or `trailers' arguments (on BSD-based OSes and macOS).

@item 
bpo-25007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25007}: Add @ref{51d,,copy.copy()} and @ref{b5c,,copy.deepcopy()} support to zlib
compressors and decompressors.  Patch by Zackery Spytz.

@item 
bpo-33929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33929}: multiprocessing: Fix a race condition in Popen of
multiprocessing.popen_spawn_win32. The child process now duplicates the
read end of pipe instead of "stealing" it. Previously, the read end of
pipe was "stolen" by the child process, but it leaked a handle if the
child process had been terminated before it could steal the handle from
the parent process.

@item 
bpo-33899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33899}: Tokenize module now implicitly emits a NEWLINE when provided
with input that does not have a trailing new line.  This behavior now
matches what the C tokenizer does internally.  Contributed by Ammar Askar.

@item 
bpo-33897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33897}: Added a 'force' keyword argument to logging.basicConfig().

@item 
bpo-33695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33695}: @ref{a17,,shutil.copytree()} uses @ref{a4d,,os.scandir()} function and
all copy functions depending from it use cached @ref{48a,,os.stat()} values.
The speedup for copying a directory with 8000 files is around +9% on
Linux, +20% on Windows and + 30% on a Windows SMB share. Also the number
of @ref{48a,,os.stat()} syscalls is reduced by 38% making
@ref{a17,,shutil.copytree()} especially faster on network filesystems.
(Contributed by Giampaolo Rodola' in bpo-33695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33695}.)

@item 
bpo-33916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33916}: bz2 and lzma: When Decompressor.__init__() is called twice,
free the old lock to not leak memory.

@item 
bpo-32568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32568}: Make select.epoll() and its documentation consistent regarding
`sizehint' and `flags'.

@item 
bpo-33833@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33833}: Fixed bug in asyncio where ProactorSocketTransport logs
AssertionError if force closed during write.

@item 
bpo-33663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33663}: Convert content length to string before putting to header.

@item 
bpo-33721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33721}: @ref{a1,,os.path} functions that return a boolean result like
@ref{9fc,,exists()}, @ref{9fd,,lexists()}, @ref{9fe,,isdir()},
@ref{9ff,,isfile()}, @ref{9fa,,islink()}, and
@ref{a00,,ismount()}, and @ref{226,,pathlib.Path} methods that return a
boolean result like @ref{a04,,exists()},
@ref{22d,,is_dir()}, @ref{22c,,is_file()},
@ref{a05,,is_mount()}, @ref{a06,,is_symlink()},
@ref{a07,,is_block_device()},
@ref{a08,,is_char_device()}, @ref{a09,,is_fifo()},
@ref{a0a,,is_socket()} now return @code{False} instead of raising
@ref{1ff,,ValueError} or its subclasses @ref{662,,UnicodeEncodeError} and
@ref{a01,,UnicodeDecodeError} for paths that contain characters or bytes
unrepresentable at the OS level.

@item 
bpo-26544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26544}: Fixed implementation of @ref{19bf,,platform.libc_ver()}. It almost
always returned version '2.9' for glibc.

@item 
bpo-33843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33843}: Remove deprecated @code{cgi.escape}, @code{cgi.parse_qs} and
@code{cgi.parse_qsl}.

@item 
bpo-33842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33842}: Remove @code{tarfile.filemode} which is deprecated since Python
3.3.

@item 
bpo-30167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30167}: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by
Steve Weber.

@item 
bpo-33805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33805}: Improve error message of dataclasses.replace() when an InitVar
is not specified

@item 
bpo-33687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33687}: Fix the call to @code{os.chmod()} for @code{uu.decode()} if a mode is
given or decoded. Patch by Timo Furrer.

@item 
bpo-33812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33812}: Datetime instance d with non-None tzinfo, but with
d.tzinfo.utcoffset(d) returning None is now treated as naive by the
astimezone() method.

@item 
bpo-32108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32108}: In configparser, don't clear section when it is assigned to
itself.

@item 
bpo-27397@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27397}: Make email module properly handle invalid-length base64
strings.

@item 
bpo-33578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33578}: Implement multibyte encoder/decoder state methods

@item 
bpo-30805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30805}: Avoid race condition with debug logging

@item 
bpo-33476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33476}: Fix _header_value_parser.py when address group is missing final
';'. Contributed by Enrique Perez-Terron

@item 
bpo-33694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33694}: asyncio: Fix a race condition causing data loss on
pause_reading()/resume_reading() when using the ProactorEventLoop.

@item 
bpo-32493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32493}: Correct test for @code{uuid_enc_be} availability in
@code{configure.ac}. Patch by Michael Felt.

@item 
bpo-33792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33792}: Add asyncio.WindowsSelectorEventLoopPolicy and
asyncio.WindowsProactorEventLoopPolicy.

@item 
bpo-33274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33274}: W3C DOM Level 1 specifies return value of
Element.removeAttributeNode() as "The Attr node that was removed."
xml.dom.minidom now complies with this requirement.

@item 
bpo-33778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33778}: Update @code{unicodedata}'s database to Unicode version 11.0.0.

@item 
bpo-33165@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33165}: Added a stacklevel parameter to logging calls to allow use of
wrapper/helper functions for logging APIs.

@item 
bpo-33770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33770}: improve base64 exception message for encoded inputs of invalid
length

@item 
bpo-33769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33769}: asyncio/start_tls: Fix error message; cancel callbacks in case
of an unhandled error; mark SSLTransport as closed if it is aborted.

@item 
bpo-33767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33767}: The concatenation (@code{+}) and repetition (@code{*}) sequence
operations now raise @ref{522,,TypeError} instead of @ref{561,,SystemError} when
performed on @ref{208,,mmap.mmap} objects.  Patch by Zackery Spytz.

@item 
bpo-33734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33734}: asyncio/ssl: Fix AttributeError, increase default handshake
timeout

@item 
bpo-31014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31014}: Fixed creating a controller for @ref{114,,webbrowser} when a user
specifies a path to an entry in the BROWSER environment variable.  Based
on patch by John Still.

@item 
bpo-2504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2504}: Add gettext.pgettext() and variants.

@item 
bpo-33197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33197}: Add description property for _ParameterKind

@item 
bpo-32751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32751}: When cancelling the task due to a timeout,
@ref{5ea,,asyncio.wait_for()} will now wait until the cancellation is complete.

@item 
bpo-32684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32684}: Fix gather to propagate cancellation of itself even with
return_exceptions.

@item 
bpo-33654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33654}: Support protocol type switching in SSLTransport.set_protocol().

@item 
bpo-33674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33674}: Pause the transport as early as possible to further reduce the
risk of data_received() being called before connection_made().

@item 
bpo-33671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33671}: @ref{a47,,shutil.copyfile()}, @ref{a48,,shutil.copy()},
@ref{a49,,shutil.copy2()}, @ref{a17,,shutil.copytree()} and @ref{a4a,,shutil.move()} use
platform-specific fast-copy syscalls on Linux and macOS in order to copy
the file more efficiently. On Windows @ref{a47,,shutil.copyfile()} uses a
bigger default buffer size (1 MiB instead of 16 KiB) and a
@ref{452,,memoryview()}-based variant of @ref{a4b,,shutil.copyfileobj()} is used.
The speedup for copying a 512MiB file is about +26% on Linux, +50% on
macOS and +40% on Windows. Also, much less CPU cycles are consumed.
(Contributed by Giampaolo Rodola' in bpo-25427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25427}.)

@item 
bpo-33674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33674}: Fix a race condition in SSLProtocol.connection_made() of
asyncio.sslproto: start immediately the handshake instead of using
call_soon(). Previously, data_received() could be called before the
handshake started, causing the handshake to hang or fail.

@item 
bpo-31647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31647}: Fixed bug where calling write_eof() on a
_SelectorSocketTransport after it's already closed raises AttributeError.

@item 
bpo-32610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32610}: Make asyncio.all_tasks() return only pending tasks.

@item 
bpo-32410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32410}: Avoid blocking on file IO in sendfile fallback code

@item 
bpo-33469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33469}: Fix RuntimeError after closing loop that used run_in_executor

@item 
bpo-33672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33672}: Fix Task.__repr__ crash with Cython's bogus coroutines

@item 
bpo-33654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33654}: Fix transport.set_protocol() to support switching between
asyncio.Protocol and asyncio.BufferedProtocol.  Fix loop.start_tls() to
work with asyncio.BufferedProtocols.

@item 
bpo-33652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33652}: Pickles of type variables and subscripted generics are now
future-proof and compatible with older Python versions.

@item 
bpo-32493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32493}: Fixed @ref{b96,,uuid.uuid1()} on FreeBSD.

@item 
bpo-33238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33238}: Add @code{InvalidStateError} to @ref{21,,concurrent.futures}.
@code{Future.set_result} and @code{Future.set_exception} now raise
@code{InvalidStateError} if the futures are not pending or running. Patch by
Jason Haydaman.

@item 
bpo-33618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33618}: Finalize and document preliminary and experimental TLS 1.3
support with OpenSSL 1.1.1

@item 
bpo-33625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33625}: Release GIL on @code{grp.getgrnam}, @code{grp.getgrgid},
@code{pwd.getpwnam} and @code{pwd.getpwuid} if reentrant variants of these
functions are available. Patch by William Grzybowski.

@item 
bpo-33623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33623}: Fix possible SIGSGV when asyncio.Future is created in __del__

@item 
bpo-11874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11874}: Use a better regex when breaking usage into wrappable parts.
Avoids bogus assertion errors from custom metavar strings.

@item 
bpo-30877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30877}: Fixed a bug in the Python implementation of the JSON decoder
that prevented the cache of parsed strings from clearing after finishing
the decoding. Based on patch by c-fos.

@item 
bpo-33604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33604}: Remove HMAC default to md5 marked for removal in 3.8 (removal
originally planned in 3.6, bump to 3.8 in PR 7062).

@item 
bpo-33582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33582}: Emit a deprecation warning for inspect.formatargspec

@item 
bpo-21145@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21145}: Add @code{functools.cached_property} decorator, for computed
properties cached for the life of the instance.

@item 
bpo-33570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33570}: Change TLS 1.3 cipher suite settings for compatibility with
OpenSSL 1.1.1-pre6 and newer. OpenSSL 1.1.1 will have TLS 1.3 ciphers
enabled by default.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Do not simplify arguments to @code{typing.Union}. Now
@code{Union[Manager, Employee]} is not simplified to @code{Employee} at runtime.
Such simplification previously caused several bugs and limited
possibilities for introspection.

@item 
bpo-12486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12486}: @ref{4c4,,tokenize.generate_tokens()} is now documented as a public
API to tokenize unicode strings. It was previously present but
undocumented.

@item 
bpo-33540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33540}: Add a new @code{block_on_close} class attribute to
@code{ForkingMixIn} and @code{ThreadingMixIn} classes of @ref{cc,,socketserver}.

@item 
bpo-33548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33548}: tempfile._candidate_tempdir_list should consider common TEMP
locations

@item 
bpo-33109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33109}: argparse subparsers are once again not required by default,
reverting the change in behavior introduced by bpo-26510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26510} in 3.7.0a2.

@item 
bpo-33541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33541}: Remove unused private method @code{_strptime.LocaleTime.__pad}
(a.k.a. @code{_LocaleTime__pad}).

@item 
bpo-33536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33536}: dataclasses.make_dataclass now checks for invalid field names
and duplicate fields. Also, added a check for invalid field
specifications.

@item 
bpo-33542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33542}: Prevent @code{uuid.get_node} from using a DUID instead of a MAC on
Windows. Patch by Zvi Effron

@item 
bpo-26819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26819}: Fix race condition with @code{ReadTransport.resume_reading} in
Windows proactor event loop.

@item 
Fix failure in @code{typing.get_type_hints()} when ClassVar was provided as a
string forward reference.

@item 
bpo-33516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33516}: @ref{e7a,,unittest.mock.MagicMock} now supports the @code{__round__}
magic method.

@item 
bpo-28612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28612}: Added support for Site Maps to urllib's @code{RobotFileParser} as
@ref{19cf,,RobotFileParser.site_maps()}. Patch by Lady Red, based
on patch by Peter Wirtz.

@item 
bpo-28167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28167}: Remove platform.linux_distribution, which was deprecated since
3.5.

@item 
bpo-33504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33504}: Switch the default dictionary implementation for
@ref{22,,configparser} from @ref{5c5,,collections.OrderedDict} to the standard
@ref{253,,dict} type.

@item 
bpo-33505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33505}: Optimize asyncio.ensure_future() by reordering if checks: 1.17x
faster.

@item 
bpo-33497@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33497}: Add errors param to cgi.parse_multipart and make an encoding in
FieldStorage use the given errors (needed for Twisted).  Patch by Amber
Brown.

@item 
bpo-29235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29235}: The @code{cProfile.Profile} class can now be used as a
context manager. Patch by Scott Sanderson.

@item 
bpo-33495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33495}: Change dataclasses.Fields repr to use the repr of each of its
members, instead of str.  This makes it more clear what each field
actually represents.  This is especially true for the 'type' member.

@item 
bpo-26103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26103}: Correct @code{inspect.isdatadescriptor} to look for @code{__set__} or
@code{__delete__}.  Patch by Aaron Hall.

@item 
bpo-29209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29209}: Removed the @code{doctype()} method and the `html' parameter of
the constructor of @ref{a42,,XMLParser}.  The
@code{doctype()} method defined in a subclass will no longer be called.
Deprecated methods @code{getchildren()} and @code{getiterator()} in the
@ref{124,,ElementTree} module emit now a @ref{1a3,,DeprecationWarning}
instead of @ref{8b5,,PendingDeprecationWarning}.

@item 
bpo-33453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33453}: Fix dataclasses to work if using literal string type
annotations or if using PEP 563 "Postponed Evaluation of Annotations".
Only specific string prefixes are detected for both ClassVar ("ClassVar"
and "typing.ClassVar") and InitVar ("InitVar" and "dataclasses.InitVar").

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Minor fixes in typing module: add annotations to
@code{NamedTuple.__new__}, pass @code{*args} and @code{**kwds} in
@code{Generic.__new__}.  Original PRs by Paulius Šarka and Chad Dombrova.

@item 
bpo-33365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33365}: Print the header values besides the header keys instead just
the header keys if `debuglevel' is set to >0 in @ref{6e,,http.client}. Patch
by Marco Strigl.

@item 
bpo-20087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20087}: Updated alias mapping with glibc 2.27 supported locales.

@item 
bpo-33422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33422}: Fix trailing quotation marks getting deleted when looking up
byte/string literals on pydoc. Patch by Andrés Delfino.

@item 
bpo-28167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28167}: The function @code{platform.linux_distribution} and
@code{platform.dist} now trigger a @code{DeprecationWarning} and have been
marked for removal in Python 3.8

@item 
bpo-33281@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33281}: Fix ctypes.util.find_library regression on macOS.

@item 
bpo-33311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33311}: Text and html output generated by cgitb does not display
parentheses if the current call is done directly in the module. Patch by
Stéphane Blondon.

@item 
bpo-27300@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27300}: The file classes in `tempfile' now accept an `errors' parameter
that complements the already existing `encoding'.  Patch by Stephan Hohe.

@item 
bpo-32933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32933}: @ref{1693,,unittest.mock.mock_open()} now supports iteration over the
file contents. Patch by Tony Flury.

@item 
bpo-33217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33217}: Raise @ref{522,,TypeError} when looking up non-Enum objects in Enum
classes and Enum members.

@item 
bpo-33197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33197}: Update error message when constructing invalid
inspect.Parameters Patch by Donghee Na.

@item 
bpo-33383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33383}: Fixed crash in the get() method of the @ref{34,,dbm.ndbm} database
object when it is called with a single argument.

@item 
bpo-33375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33375}: The warnings module now finds the Python file associated with a
warning from the code object, rather than the frame's global namespace.
This is consistent with how tracebacks and pdb find filenames, and should
work better for dynamically executed code.

@item 
bpo-33336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33336}: @code{imaplib} now allows @code{MOVE} command in @code{IMAP4.uid()} (RFC
6851: IMAP MOVE Extension) and potentially as a name of supported method
of @code{IMAP4} object.

@item 
bpo-32455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32455}: Added `jump' parameter to @ref{f1c,,dis.stack_effect()}.

@item 
bpo-27485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27485}: Rename and deprecate undocumented functions in
@ref{109,,urllib.parse()}.

@item 
bpo-33332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33332}: Add @code{signal.valid_signals()} to expose the POSIX sigfillset()
functionality.

@item 
bpo-33251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33251}: @code{ConfigParser.items()} was fixed so that key-value pairs
passed in via @ref{19d0,,vars()} are not included in the resulting output.

@item 
bpo-33329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33329}: Fix multiprocessing regression on newer glibcs

@item 
bpo-33334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33334}: @ref{f1c,,dis.stack_effect()} now supports all defined opcodes
including NOP and EXTENDED_ARG.

@item 
bpo-991266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=991266}: Fix quoting of the @code{Comment} attribute of
@ref{19d1,,http.cookies.SimpleCookie}.

@item 
bpo-33131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33131}: Upgrade bundled version of pip to 10.0.1.

@item 
bpo-33308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33308}: Fixed a crash in the @code{parser} module when converting an ST
object to a tree of tuples or lists with @code{line_info=False} and
@code{col_info=True}.

@item 
bpo-23403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23403}: lib2to3 now uses pickle protocol 4 for pre-computed grammars.

@item 
bpo-33266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33266}: lib2to3 now recognizes @code{rf'...'} strings.

@item 
bpo-11594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11594}: Ensure line-endings are respected when using lib2to3.

@item 
bpo-33254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33254}: Have @ref{1ef,,importlib.resources.contents()} and
@ref{19d2,,importlib.abc.ResourceReader.contents()} return an @ref{1205,,iterable}
instead of an @ref{1aa,,iterator}.

@item 
bpo-33265@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33265}: @code{contextlib.ExitStack} and @code{contextlib.AsyncExitStack} now
use a method instead of a wrapper function for exit callbacks.

@item 
bpo-33263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33263}: Fix FD leak in @code{_SelectorSocketTransport}  Patch by Vlad
Starostin.

@item 
bpo-33256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33256}: Fix display of @code{<module>} call in the html produced by
@code{cgitb.html()}. Patch by Stéphane Blondon.

@item 
bpo-33144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33144}: @code{random.Random()} and its subclassing mechanism got optimized
to check only once at class/subclass instantiation time whether its
@code{getrandbits()} method can be relied on by other methods, including
@code{randrange()}, for the generation of arbitrarily large random integers.
Patch by Wolfgang Maier.

@item 
bpo-33185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33185}: Fixed regression when running pydoc with the @ref{5cb,,-m}
switch. (The regression was introduced in 3.7.0b3 by the resolution of
bpo-33053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33053})

This fix also changed pydoc to add @code{os.getcwd()} to @ref{3ab,,sys.path}
when necessary, rather than adding @code{"."}.

@item 
bpo-29613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29613}: Added support for the @code{SameSite} cookie flag to the
@code{http.cookies} module.

@item 
bpo-33169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33169}: Delete entries of @code{None} in @ref{5ce,,sys.path_importer_cache}
when @code{importlib.machinery.invalidate_caches()} is called.

@item 
bpo-33203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33203}: @code{random.Random.choice()} now raises @code{IndexError} for empty
sequences consistently even when called from subclasses without a
@code{getrandbits()} implementation.

@item 
bpo-33224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33224}: Update difflib.mdiff() for 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}.  Convert an uncaught
StopIteration in a generator into a return-statement.

@item 
bpo-33209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33209}: End framing at the end of C implementation of
@ref{19d3,,pickle.Pickler.dump()}.

@item 
bpo-32861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32861}: The urllib.robotparser's @code{__str__} representation now
includes wildcard entries and the "Crawl-delay" and "Request-rate" fields.
Also removes extra newlines that were being appended to the end of the
string. Patch by Michael Lazar.

@item 
bpo-23403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23403}: @code{DEFAULT_PROTOCOL} in @ref{a5,,pickle} was bumped to 4. Protocol
4 is described in 
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/} and available since Python 3.4. It offers
better performance and smaller size compared to protocol 3 introduced in
Python 3.0.

@item 
bpo-20104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20104}: Improved error handling and fixed a reference leak in
@ref{21d,,os.posix_spawn()}.

@item 
bpo-33106@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33106}: Deleting a key from a read-only dbm database raises module
specific error instead of KeyError.

@item 
bpo-33175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33175}: In dataclasses, Field.__set_name__ now looks up the
__set_name__ special method on the class, not the instance, of the default
value.

@item 
bpo-32380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32380}: Create functools.singledispatchmethod to support generic single
dispatch on descriptors and methods.

@item 
bpo-33141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33141}: Have Field objects pass through __set_name__ to their default
values, if they have their own __set_name__.

@item 
bpo-33096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33096}: Allow ttk.Treeview.insert to insert iid that has a false
boolean value. Note iid=0 and iid=False would be same. Patch by Garvit
Khatri.

@item 
bpo-32873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32873}: Treat type variables and special typing forms as immutable by
copy and pickle.  This fixes several minor issues and inconsistencies, and
improves backwards compatibility with Python 3.6.

@item 
bpo-33134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33134}: When computing dataclass's __hash__, use the lookup table to
contain the function which returns the __hash__ value.  This is an
improvement over looking up a string, and then testing that string to see
what to do.

@item 
bpo-33127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33127}: The ssl module now compiles with LibreSSL 2.7.1.

@item 
bpo-32505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32505}: Raise TypeError if a member variable of a dataclass is of type
Field, but doesn't have a type annotation.

@item 
bpo-33078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33078}: Fix the failure on OSX caused by the tests relying on
sem_getvalue

@item 
bpo-33116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33116}: Add 'Field' to dataclasses.__all__.

@item 
bpo-32896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32896}: Fix an error where subclassing a dataclass with a field that
uses a default_factory would generate an incorrect class.

@item 
bpo-33100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33100}: Dataclasses: If a field has a default value that's a
MemberDescriptorType, then it's from that field being in __slots__, not an
actual default value.

@item 
bpo-32953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32953}: If a non-dataclass inherits from a frozen dataclass, allow
attributes to be added to the derived class.  Only attributes from the
frozen dataclass cannot be assigned to.  Require all dataclasses in a
hierarchy to be either all frozen or all non-frozen.

@item 
bpo-33097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33097}: Raise RuntimeError when @code{executor.submit} is called during
interpreter shutdown.

@item 
bpo-32968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32968}: Modulo and floor division involving Fraction and float should
return float.

@item 
bpo-33061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33061}: Add missing @code{NoReturn} to @code{__all__} in typing.py

@item 
bpo-33078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33078}: Fix the size handling in multiprocessing.Queue when a pickling
error occurs.

@item 
bpo-33064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33064}: lib2to3 now properly supports trailing commas after @code{*args}
and @code{**kwargs} in function signatures.

@item 
bpo-33056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33056}: FIX properly close leaking fds in
concurrent.futures.ProcessPoolExecutor.

@item 
bpo-33021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33021}: Release the GIL during fstat() calls, avoiding hang of all
threads when calling mmap.mmap(), os.urandom(), and random.seed().  Patch
by Nir Soffer.

@item 
bpo-31804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31804}: Avoid failing in multiprocessing.Process if the standard
streams are closed or None at exit.

@item 
bpo-33034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33034}: Providing an explicit error message when casting the port
property to anything that is not an integer value using @code{urlparse()} and
@code{urlsplit()}. Patch by Matt Eaton.

@item 
bpo-30249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30249}: Improve struct.unpack_from() exception messages for problems
with the buffer size and offset.

@item 
bpo-33037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33037}: Skip sending/receiving data after SSL transport closing.

@item 
bpo-27683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27683}: Fix a regression in @ref{7f,,ipaddress} that result of
@code{hosts()} is empty when the network is constructed by a tuple
containing an integer mask and only 1 bit left for addresses.

@item 
bpo-22674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22674}: Add the strsignal() function in the signal module that returns
the system description of the given signal, as returned by strsignal(3).

@item 
bpo-32999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32999}: Fix C implementation of @code{ABC.__subclasscheck__(cls,
subclass)} crashed when @code{subclass} is not a type object.

@item 
bpo-33009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33009}: Fix inspect.signature() for single-parameter partialmethods.

@item 
bpo-32969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32969}: Expose several missing constants in zlib and fix corresponding
documentation.

@item 
bpo-32056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32056}: Improved exceptions raised for invalid number of channels and
sample width when read an audio file in modules @code{aifc}, @ref{112,,wave}
and @code{sunau}.

@item 
bpo-32970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32970}: Improved disassembly of the MAKE_FUNCTION instruction.

@item 
bpo-32844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32844}: Fix wrong redirection of a low descriptor (0 or 1) to stderr in
subprocess if another low descriptor is closed.

@item 
bpo-32960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32960}: For dataclasses, disallow inheriting frozen from non-frozen
classes, and also disallow inheriting non-frozen from frozen classes. This
restriction will be relaxed at a future date.

@item 
bpo-32713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32713}: Fixed tarfile.itn handling of out-of-bounds float values. Patch
by Joffrey Fuhrer.

@item 
bpo-32257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32257}: The ssl module now contains OP_NO_RENEGOTIATION constant,
available with OpenSSL 1.1.0h or 1.1.1.

@item 
bpo-32951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32951}: Direct instantiation of SSLSocket and SSLObject objects is now
prohibited. The constructors were never documented, tested, or designed as
public constructors. Users were suppose to use ssl.wrap_socket() or
SSLContext.

@item 
bpo-32929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32929}: Remove the tri-state parameter "hash", and add the boolean
"unsafe_hash". If unsafe_hash is True, add a __hash__ function, but if a
__hash__ exists, raise TypeError.  If unsafe_hash is False, add a __hash__
based on the values of eq= and frozen=.  The unsafe_hash=False behavior is
the same as the old hash=None behavior.  unsafe_hash=False is the default,
just as hash=None used to be.

@item 
bpo-32947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32947}: Add OP_ENABLE_MIDDLEBOX_COMPAT and test workaround for TLSv1.3
for future compatibility with OpenSSL 1.1.1.

@item 
bpo-32146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32146}: Document the interaction between frozen executables and the
spawn and forkserver start methods in multiprocessing.

@item 
bpo-30622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30622}: The ssl module now detects missing NPN support in LibreSSL.

@item 
bpo-32922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32922}: dbm.open() now encodes filename with the filesystem encoding
rather than default encoding.

@item 
bpo-32759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32759}: Free unused arenas in multiprocessing.heap.

@item 
bpo-32859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32859}: In @code{os.dup2}, don't check every call whether the @code{dup3}
syscall exists or not.

@item 
bpo-32556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32556}: nt._getfinalpathname, nt._getvolumepathname and
nt._getdiskusage now correctly convert from bytes.

@item 
bpo-21060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21060}: Rewrite confusing message from setup.py upload from "No dist
file created in earlier command" to the more helpful "Must create and
upload files in one command".

@item 
bpo-32857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32857}: In @ref{ef,,tkinter}, @code{after_cancel(None)} now raises a
@ref{1ff,,ValueError} instead of canceling the first scheduled function.
Patch by Cheryl Sabella.

@item 
bpo-32852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32852}: Make sure sys.argv remains as a list when running trace.

@item 
bpo-31333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31333}: @code{_abc} module is added.  It is a speedup module with C
implementations for various functions and methods in @code{abc}.  Creating an
ABC subclass and calling @code{isinstance} or @code{issubclass} with an ABC
subclass are up to 1.5x faster. In addition, this makes Python start-up up
to 10% faster.

Note that the new implementation hides internal registry and caches,
previously accessible via private attributes @code{_abc_registry},
@code{_abc_cache}, and @code{_abc_negative_cache}.  There are three debugging
helper methods that can be used instead @code{_dump_registry},
@code{_abc_registry_clear}, and @code{_abc_caches_clear}.

@item 
bpo-32841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32841}: Fixed @code{asyncio.Condition} issue which silently ignored
cancellation after notifying and cancelling a conditional lock. Patch by
Bar Harel.

@item 
bpo-32819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32819}: ssl.match_hostname() has been simplified and no longer depends
on re and ipaddress module for wildcard and IP addresses. Error reporting
for invalid wildcards has been improved.

@item 
bpo-19675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19675}: @code{multiprocessing.Pool} no longer leaks processes if its
initialization fails.

@item 
bpo-32394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32394}: socket: Remove
TCP_FASTOPEN,TCP_KEEPCNT,TCP_KEEPIDLE,TCP_KEEPINTVL flags on older version
Windows during run-time.

@item 
bpo-31787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31787}: Fixed refleaks of @code{__init__()} methods in various modules.
(Contributed by Oren Milman)

@item 
bpo-30157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30157}: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when
only the last field is quoted.  Patch by Jake Davis.

@item 
bpo-30688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30688}: Added support of @code{\N@{name@}} escapes in regular expressions.
Based on patch by Jonathan Eunice.

@item 
bpo-32792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32792}: collections.ChainMap() preserves the order of the underlying
mappings.

@item 
bpo-32775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32775}: @ref{19d4,,fnmatch.translate()} no longer produces patterns which
contain set operations. Sets starting with '[' or containing '--', '&&',
'~~' or '||' will be interpreted differently in regular expressions in
future versions. Currently they emit warnings. fnmatch.translate() now
avoids producing patterns containing such sets by accident.

@item 
bpo-32622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32622}: Implement native fast sendfile for Windows proactor event loop.

@item 
bpo-32777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32777}: Fix a rare but potential pre-exec child process deadlock in
subprocess on POSIX systems when marking file descriptors inheritable on
exec in the child process.  This bug appears to have been introduced in
3.4.

@item 
bpo-32647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32647}: The ctypes module used to depend on indirect linking for
dlopen. The shared extension is now explicitly linked against libdl on
platforms with dl.

@item 
bpo-32749@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32749}: A @ref{32,,dbm.dumb} database opened with flags 'r' is now
read-only. @ref{a84,,dbm.dumb.open()} with flags 'r' and 'w' no longer creates
a database if it does not exist.

@item 
bpo-32741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32741}: Implement @code{asyncio.TimerHandle.when()} method.

@item 
bpo-32691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32691}: Use mod_spec.parent when running modules with pdb

@item 
bpo-32734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32734}: Fixed @code{asyncio.Lock()} safety issue which allowed acquiring
and locking the same lock multiple times, without it being free. Patch by
Bar Harel.

@item 
bpo-32727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32727}: Do not include name field in SMTP envelope from address. Patch
by Stéphane Wirtel

@item 
bpo-31453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31453}: Add TLSVersion constants and SSLContext.maximum_version /
minimum_version attributes. The new API wraps OpenSSL 1.1
@indicateurl{https://web.archive.org/web/20180309043602/https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html}
feature.

@item 
bpo-24334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24334}: Internal implementation details of ssl module were cleaned up.
The SSLSocket has one less layer of indirection. Owner and session
information are now handled by the SSLSocket and SSLObject constructor.
Channel binding implementation has been simplified.

@item 
bpo-31848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31848}: Fix the error handling in Aifc_read.initfp() when the SSND
chunk is not found. Patch by Zackery Spytz.

@item 
bpo-32585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32585}: Add Ttk spinbox widget to @ref{f8,,tkinter.ttk}.  Patch by Alan D
Moore.

@item 
bpo-32512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32512}: @ref{ae,,profile} CLI accepts @code{-m module_name} as an alternative
to script path.

@item 
bpo-8525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8525}: help() on a type now displays builtin subclasses. This is
intended primarily to help with notification of more specific exception
subclasses.

Patch by Sanyam Khurana.

@item 
bpo-31639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31639}: http.server now exposes a ThreadingHTTPServer class and uses it
when the module is run with @code{-m} to cope with web browsers pre-opening
sockets.

@item 
bpo-29877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29877}: compileall: import ProcessPoolExecutor only when needed,
preventing hangs on low resource platforms

@item 
bpo-32221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32221}: Various functions returning tuple containing IPv6 addresses now
omit @code{%scope} part since the same information is already encoded in
`scopeid' tuple item. Especially this speeds up @code{socket.recvfrom()}
when it receives multicast packet since useless resolving of network
interface name is omitted.

@item 
bpo-32147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32147}: @ref{19d5,,binascii.unhexlify()} is now up to 2 times faster. Patch
by Sergey Fedoseev.

@item 
bpo-30693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30693}: The TarFile class now recurses directories in a reproducible
way.

@item 
bpo-30693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30693}: The ZipFile class now recurses directories in a reproducible
way.

@item 
bpo-31680@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31680}: Added @ref{9d5,,curses.ncurses_version}.

@item 
bpo-31908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31908}: Fix output of cover files for @code{trace} module command-line
tool. Previously emitted cover files only when @code{--missing} option was
used. Patch by Michael Selik.

@item 
bpo-31608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31608}: Raise a @code{TypeError} instead of crashing if a
@code{collections.deque} subclass returns a non-deque from @code{__new__}. Patch
by Oren Milman.

@item 
bpo-31425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31425}: Add support for sockets of the AF_QIPCRTR address family,
supported by the Linux kernel. This is used to communicate with services,
such as GPS or radio, running on Qualcomm devices. Patch by Bjorn
Andersson.

@item 
bpo-22005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22005}: Implemented unpickling instances of
@ref{1c7,,datetime}, @ref{1c8,,date} and
@ref{1c9,,time} pickled by Python 2. @code{encoding='latin1'} should
be used for successful decoding.

@item 
bpo-27645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27645}: @ref{242,,sqlite3.Connection} now exposes a
@ref{b68,,backup} method, if the underlying SQLite
library is at version 3.6.11 or higher.  Patch by Lele Gaifax.

@item 
bpo-16865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16865}: Support arrays >=2GiB in @ref{2a,,ctypes}.  Patch by Segev Finer.

@item 
bpo-31508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31508}: Removed support of arguments in
@code{tkinter.ttk.Treeview.selection}. It was deprecated in 3.6.  Use
specialized methods like @code{selection_set} for changing the selection.

@item 
bpo-29456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29456}: Fix bugs in hangul normalization: u1176, u11a7 and u11c3
@end itemize

@node Documentation<46>,Tests<48>,Library<51>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id458}@anchor{19d6}
@subsubsection Documentation



@itemize -

@item 
bpo-21257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21257}: Document @ref{19d7,,http.client.parse_headers()}.

@item 
bpo-34764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34764}: Improve example of iter() with 2nd sentinel argument.

@item 
bpo-35564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35564}: Explicitly set master_doc variable in conf.py for compliance
with Sphinx 2.0

@item 
bpo-35511@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35511}: Specified that profile.Profile class doesn't not support enable
or disable methods. Also, elaborated that Profile object as a context
manager is only supported in cProfile module.

@item 
bpo-10536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10536}: Enhance the gettext docs. Patch by Éric Araujo

@item 
bpo-35089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35089}: Remove mention of @code{typing.io} and @code{typing.re}. Their types
should be imported from @code{typing} directly.

@item 
bpo-35038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35038}: Fix the documentation about an unexisting @code{f_restricted}
attribute in the frame object. Patch by Stéphane Wirtel

@item 
bpo-35042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35042}: Replace PEP XYZ by the pep role and allow to use the direct
links to the PEPs.

@item 
bpo-35044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35044}: Fix the documentation with the role @code{exc} for the
appropriated exception. Patch by Stéphane Wirtel

@item 
bpo-35035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35035}: Rename documentation for @ref{50,,email.utils} to
@code{email.utils.rst}.

@item 
bpo-34967@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34967}: Use app.add_object_type() instead of the deprecated Sphinx
function app.description_unit()

@item 
bpo-34913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34913}: Add documentation about the new command line interface of the
gzip module.

@item 
bpo-32174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32174}: chm document displays non-ASCII characters properly on some
MBCS Windows systems.

@item 
bpo-11233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11233}: Create availability directive for documentation.  Original
patch by Georg Brandl.

@item 
bpo-34790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34790}: Document how passing coroutines to asyncio.wait() can be
confusing.

@item 
bpo-34552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34552}: Make clear that @code{==} operator sometimes is equivalent to
@code{is}. The @code{<}, @code{<=}, @code{>} and @code{>=} operators are only defined
where they make sense.

@item 
bpo-28617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28617}: Fixed info in the stdtypes docs concerning the types that
support membership tests.

@item 
bpo-20177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20177}: Migrate datetime.date.fromtimestamp to Argument Clinic. Patch
by Tim Hoffmann.

@item 
bpo-34065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34065}: Fix wrongly written basicConfig documentation markup syntax

@item 
bpo-33460@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33460}: replaced ellipsis with correct error codes in tutorial chapter
3.

@item 
bpo-33847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33847}: Add '@@' operator entry to index.

@item 
bpo-33409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33409}: Clarified the relationship between 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}'s
PYTHONCOERCECLOCALE and PEP 540's PYTHONUTF8 mode.

@item 
bpo-33197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33197}: Add versionadded tag to the documentation of
ParameterKind.description

@item 
bpo-17045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17045}: Improve the C-API doc for PyTypeObject.  This includes adding
several quick-reference tables and a lot of missing slot/typedef entries.
The existing entries were also cleaned up with a slightly more consistent
format.

@item 
bpo-33736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33736}: Improve the documentation of @ref{b06,,asyncio.open_connection()},
@ref{b07,,asyncio.start_server()} and their UNIX socket counterparts.

@item 
bpo-23859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23859}: Document that @code{asyncio.wait()} does not cancel its futures on
timeout.

@item 
bpo-32436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32436}: Document 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} changes to asyncio.

@item 
bpo-33604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33604}: Update HMAC md5 default to a DeprecationWarning, bump removal
to 3.8.

@item 
bpo-33594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33594}: Document @code{getargspec}, @code{from_function} and @code{from_builtin}
as deprecated in their respective docstring, and include version since
deprecation in DeprecationWarning message.

@item 
bpo-33503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33503}: Fix broken pypi link

@item 
bpo-33421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33421}: Add missing documentation for @code{typing.AsyncContextManager}.

@item 
bpo-33487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33487}: BZ2file now emit a DeprecationWarning when buffering=None is
passed, the deprecation message and documentation also now explicitly
state it is deprecated since 3.0.

@item 
bpo-33378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33378}: Add Korean language switcher for @indicateurl{https://docs.python.org/3/}

@item 
bpo-33276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33276}: Clarify that the @code{__path__} attribute on modules cannot be
just any value.

@item 
bpo-33201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33201}: Modernize documentation for writing C extension types.

@item 
bpo-33195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33195}: Deprecate @code{Py_UNICODE} usage in @code{c-api/arg} document.
@code{Py_UNICODE} related APIs are deprecated since Python 3.3, but it is
missed in the document.

@item 
bpo-33126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33126}: Document PyBuffer_ToContiguous().

@item 
bpo-27212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27212}: Modify documentation for the @code{islice()} recipe to consume
initial values up to the start index.

@item 
bpo-28247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28247}: Update @ref{12f,,zipapp} documentation to describe how to make
standalone applications.

@item 
bpo-18802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18802}: Documentation changes for ipaddress.  Patch by Jon Foster and
Berker Peksag.

@item 
bpo-27428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27428}: Update documentation to clarify that @code{WindowsRegistryFinder}
implements @code{MetaPathFinder}. (Patch by Himanshu Lakhara)

@item 
bpo-28124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28124}: The ssl module function ssl.wrap_socket() has been
de-emphasized and deprecated in favor of the more secure and efficient
SSLContext.wrap_socket() method.

@item 
bpo-17232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17232}: Clarify docs for -O and -OO.  Patch by Terry Reedy.

@item 
bpo-32436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32436}: Add documentation for the contextvars module (PEP 567).

@item 
bpo-32800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32800}: Update link to w3c doc for xml default namespaces.

@item 
bpo-11015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11015}: Update @ref{e3,,test.support} documentation.

@item 
bpo-32613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32613}: Update the faq/windows.html to use the py command from PEP 397
instead of python.

@item 
bpo-8722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8722}: Document @code{__getattr__()} behavior when property @code{get()}
method raises @ref{343,,AttributeError}.

@item 
bpo-32614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32614}: Modify RE examples in documentation to use raw strings to
prevent @ref{1a3,,DeprecationWarning} and add text to REGEX HOWTO to highlight
the deprecation.

@item 
bpo-20709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20709}: Remove the paragraph where we explain that os.utime() does not
support a directory as path under Windows. Patch by Jan-Philip Gehrcke

@item 
bpo-32722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32722}: Remove the bad example in the tutorial of the Generator
Expression. Patch by Stéphane Wirtel

@item 
bpo-31972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31972}: Improve docstrings for @code{pathlib.PurePath} subclasses.

@item 
bpo-30607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30607}: Use the externalized @code{python-docs-theme} package when
building the documentation.

@item 
bpo-8243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8243}: Add a note about curses.addch and curses.addstr exception
behavior when writing outside a window, or pad.

@item 
bpo-32337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32337}: Update documentation related with @code{dict} order.

@item 
bpo-25041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25041}: Document @code{AF_PACKET} in the @ref{cb,,socket} module.

@item 
bpo-31432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31432}: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED
flags for ssl.SSLContext.verify_mode.
@end itemize

@node Tests<48>,Build<50>,Documentation<46>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id459}@anchor{19d8}
@subsubsection Tests



@itemize -

@item 
bpo-35772@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35772}: Fix sparse file tests of test_tarfile on ppc64 with the tmpfs
filesystem. Fix the function testing if the filesystem supports sparse
files: create a file which contains data and "holes", instead of creating
a file which contains no data. tmpfs effective block size is a page size
(tmpfs lives in the page cache). RHEL uses 64 KiB pages on aarch64, ppc64,
ppc64le, only s390x and x86_64 use 4 KiB pages, whereas the test punch
holes of 4 KiB.

@item 
bpo-35045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35045}: Make ssl tests less strict and also accept TLSv1 as system
default. The changes unbreaks test_min_max_version on Fedora 29.

@item 
bpo-32710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32710}: @code{test_asyncio/test_sendfile.py} now resets the event loop
policy using @code{tearDownModule()} as done in other tests, to prevent a
warning when running tests on Windows.

@item 
bpo-33717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33717}: test.pythoninfo now logs information of all clocks, not only
time.time() and time.perf_counter().

@item 
bpo-35488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35488}: Add a test to pathlib's Path.match() to verify it does not
support glob-style ** recursive pattern matching.

@item 
bpo-31731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31731}: Fix a race condition in @code{check_interrupted_write()} of
test_io: create directly the thread with SIGALRM signal blocked, rather
than blocking the signal later from the thread. Previously, it was
possible that the thread gets the signal before the signal is blocked.

@item 
bpo-35424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35424}: Fix test_multiprocessing_main_handling: use
@code{multiprocessing.Pool} with a context manager and then explicitly
join the pool.

@item 
bpo-35519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35519}: Rename @code{test.bisect} module to @code{test.bisect_cmd} to
avoid conflict with @ref{11,,bisect} module when running directly a test like
@code{./python Lib/test/test_xmlrpc.py}.

@item 
bpo-35513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35513}: Replace @ref{251,,time.time()} with @ref{250,,time.monotonic()} in tests
to measure time delta.

@item 
bpo-34279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34279}: @code{test.support.run_unittest()} no longer raise
@code{TestDidNotRun} if the test result contains skipped tests. The
exception is now only raised if no test have been run and no test have
been skipped.

@item 
bpo-35412@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35412}: Add testcase to @code{test_future4}: check unicode literal.

@item 
bpo-26704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26704}: Added test demonstrating double-patching of an instance method.
Patch by Anthony Sottile.

@item 
bpo-33725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33725}: test_multiprocessing_fork may crash on recent versions of
macOS.  Until the issue is resolved, skip the test on macOS.

@item 
bpo-35352@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35352}: Modify test_asyncio to use the certificate set from the test
directory.

@item 
bpo-35317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35317}: Fix @code{mktime()} overflow error in @code{test_email}: run
@code{test_localtime_daylight_true_dst_true()} and
@code{test_localtime_daylight_false_dst_true()} with a specific timezone.

@item 
bpo-21263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21263}: After several reports that test_gdb does not work properly on
macOS and since gdb is not shipped by default anymore, test_gdb is now
skipped on macOS when LLVM Clang has been used to compile Python. Patch by
Lysandros Nikolaou

@item 
bpo-34279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34279}: regrtest issue a warning when no tests have been executed in a
particular test file. Also, a new final result state is issued if no test
have been executed across all test files. Patch by Pablo Galindo.

@item 
bpo-34962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34962}: make docstest in Doc now passes., and is enforced in CI

@item 
bpo-23596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23596}: Use argparse for the command line of the gzip module. Patch by
Antony Lee

@item 
bpo-34537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34537}: Fix @code{test_gdb.test_strings()} when @code{LC_ALL=C} and GDB was
compiled with Python 3.6 or earlier.

@item 
bpo-34587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34587}: test_socket: Remove RDSTest.testCongestion(). The test tries to
fill the receiver's socket buffer and expects an error. But the RDS
protocol doesn't require that. Moreover, the Linux implementation of RDS
expects that the producer of the messages reduces its rate, it's not the
role of the receiver to trigger an error. The test fails on Fedora 28 by
design, so just remove it.

@item 
bpo-34661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34661}: Fix test_shutil if unzip doesn't support -t.

@item 
bpo-34200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34200}: Fixed non-deterministic flakiness of test_pkg by not using the
scary test.support.module_cleanup() logic to save and restore sys.modules
contents between test cases.

@item 
bpo-34569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34569}: The experimental PEP 554 data channels now correctly pass
negative PyLong objects between subinterpreters on 32-bit systems. Patch
by Michael Felt.

@item 
bpo-34594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34594}: Fix usage of hardcoded @code{errno} values in the tests.

@item 
bpo-34579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34579}: Fix test_embed for AIX Patch by Michael Felt

@item 
bpo-34542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34542}: Use 3072 RSA keys and SHA-256 signature for test certs and
keys.

@item 
bpo-11193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11193}: Remove special condition for AIX in
@code{test_subprocess.test_undecodable_env}

@item 
bpo-34347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34347}: Fix @code{test_utf8_mode.test_cmd_line} for AIX

@item 
bpo-34490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34490}: On AIX with AF_UNIX family sockets getsockname() does not
provide 'sockname', so skip calls to transport.get_extra_info('sockname')

@item 
bpo-34391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34391}: Fix ftplib test for TLS 1.3 by reading from data socket.

@item 
bpo-11192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11192}: Fix @code{test_socket} on AIX 6.1 and later IPv6 zone id supports
only supported by @code{inet_pton6_zone()}. Switch to runtime-based
@code{platform.system()} to establish current platform rather than build-time
based @code{sys.platform()}

@item 
bpo-34399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34399}: Update all RSA keys and DH params to use at least 2048 bits.

@item 
bpo-34373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34373}: Fix @code{test_mktime} and @code{test_pthread_getcpuclickid} tests
for AIX Add range checking for @code{_PyTime_localtime} for AIX Patch by
Michael Felt

@item 
bpo-11191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11191}: Skip the distutils test 'test_search_cpp' when using XLC as
compiler patch by aixtools (Michael Felt)

@item 
Improved an error message when mock assert_has_calls fails.

@item 
bpo-33746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33746}: Fix test_unittest when run in verbose mode.

@item 
bpo-33901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33901}: Fix test_dbm_gnu on macOS with gdbm 1.15: add a larger value to
make sure that the file size changes.

@item 
bpo-33873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33873}: Fix a bug in @code{regrtest} that caused an extra test to run if
--huntrleaks/-R was used. Exit with error in case that invalid parameters
are specified to --huntrleaks/-R (at least one warmup run and one
repetition must be used).

@item 
bpo-33562@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33562}: Check that a global asyncio event loop policy is not left
behind by any tests.

@item 
bpo-33655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33655}: Ignore test_posix_fallocate failures on BSD platforms that
might be due to running on ZFS.

@item 
bpo-32962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32962}: Fixed test_gdb when Python is compiled with flags -mcet
-fcf-protection -O0.

@item 
bpo-33358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33358}: Fix @code{test_embed.test_pre_initialization_sys_options()} when
the interpreter is built with @code{--enable-shared}.

@item 
bpo-32872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32872}: Avoid regrtest compatibility issue with namespace packages.

@item 
bpo-32517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32517}: Fix failing @code{test_asyncio} on macOS 10.12.2+ due to transport
of @code{KqueueSelector} loop was not being closed.

@item 
bpo-32663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32663}: Making sure the @code{SMTPUTF8SimTests} class of tests gets run in
@code{test_smtplib.py}.

@item 
bpo-27643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27643}: Test_C test case needs "signed short" bitfields, but the IBM
XLC compiler (on AIX) does not support this Skip the code and test when
AIX and XLC are used

Applicable to Python2-2.7 and later

@item 
bpo-19417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19417}: Add test_bdb.py.

@item 
bpo-31809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31809}: Add tests to verify connection with secp ECDH curves.
@end itemize

@node Build<50>,Windows<46>,Tests<48>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id460}@anchor{19d9}
@subsubsection Build



@itemize -

@item 
bpo-34691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34691}: The _contextvars module is now built into the core Python
library on Windows.

@item 
bpo-35683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35683}: Improved Azure Pipelines build steps and now verifying layouts
correctly

@item 
bpo-35642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35642}: Remove asynciomodule.c from pythoncore.vcxproj

@item 
bpo-35550@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35550}: Fix incorrect Solaris #ifdef checks to look for __sun && __SVR4
instead of sun when compiling.

@item 
bpo-35499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35499}: @code{make profile-opt} no longer replaces @code{CFLAGS_NODIST} with
@code{CFLAGS}. It now adds profile-guided optimization (PGO) flags to
@code{CFLAGS_NODIST}: existing @code{CFLAGS_NODIST} flags are kept.

@item 
bpo-35257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35257}: Avoid leaking the linker flags from Link Time Optimizations
(LTO) into distutils when compiling C extensions.

@item 
bpo-35351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35351}: When building Python with clang and LTO, LTO flags are no
longer passed into CFLAGS to build third-party C extensions through
distutils.

@item 
bpo-35139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35139}: Fix a compiler error when statically linking @code{pyexpat} in
@code{Modules/Setup}.

@item 
bpo-35059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35059}: PCbuild: Set InlineFunctionExpansion to OnlyExplicitInline
("/Ob1" option) in pyproject.props in Debug mode to expand functions
marked as inline. This change should make Python compiled in Debug mode a
little bit faster on Windows.

@item 
bpo-35011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35011}: Restores the use of pyexpatns.h to isolate our embedded copy of
the expat C library so that its symbols do not conflict at link or dynamic
loading time with an embedding application or other extension modules with
their own version of libexpat.

@item 
bpo-28015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28015}: Have --with-lto works correctly with clang.

@item 
bpo-34765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34765}: Update the outdated install-sh file to the latest revision from
automake v1.16.1

@item 
bpo-34585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34585}: Check for floating-point byte order in configure.ac using
compilation tests instead of executing code, so that these checks work in
cross-compiled builds.

@item 
bpo-34710@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34710}: Fixed SSL module build with OpenSSL & pedantic CFLAGS.

@item 
bpo-34582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34582}: Add JUnit XML output for regression tests and update Azure
DevOps builds.

@item 
bpo-34081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34081}: Make Sphinx warnings as errors in the Docs Makefile.

@item 
bpo-34555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34555}: Fix for case where it was not possible to have both
@code{HAVE_LINUX_VM_SOCKETS_H} and @code{HAVE_SOCKADDR_ALG} be undefined.

@item 
bpo-33015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33015}: Fix an undefined behaviour in the pthread implementation of
@code{PyThread_start_new_thread()}: add a function wrapper to always
return @code{NULL}.

@item 
bpo-34245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34245}: The Python shared library is now installed with write
permission (mode 0755), which is the standard way of installing such
libraries.

@item 
bpo-34121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34121}: Fix detection of C11 atomic support on clang.

@item 
bpo-32430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32430}: Rename Modules/Setup.dist to Modules/Setup, and remove the
necessity to copy the former manually to the latter when updating the
local source tree.

@item 
bpo-30345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30345}: Add -g to LDFLAGS when compiling with LTO to get debug symbols.

@item 
bpo-5755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5755}: Move @code{-Wstrict-prototypes} option to @code{CFLAGS_NODIST} from
@code{OPT}. This option emitted annoying warnings when building extension
modules written in C++.

@item 
bpo-33614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33614}: Ensures module definition files for the stable ABI on Windows
are correctly regenerated.

@item 
bpo-33648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33648}: The --with-c-locale-warning configuration flag has been
removed. It has had no effect for about a year.

@item 
bpo-33522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33522}: Enable CI builds on Visual Studio Team Services at
@indicateurl{https://python.visualstudio.com/cpython}

@item 
bpo-33512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33512}: configure's check for "long double" has been simplified

@item 
bpo-33483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33483}: C compiler is now correctly detected from the standard
environment variables. --without-gcc and --with-icc options have been
removed.

@item 
bpo-33394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33394}: Enable the verbose build for extension modules, when GNU make
is passed macros on the command line.

@item 
bpo-33393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33393}: Update config.guess and config.sub files.

@item 
bpo-33377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33377}: Add new triplets for mips r6 and riscv variants (used in
extension suffixes).

@item 
bpo-32232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32232}: By default, modules configured in @code{Modules/Setup} are no
longer built with @code{-DPy_BUILD_CORE}. Instead, modules that specifically
need that preprocessor definition include it in their individual entries.

@item 
bpo-33182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33182}: The embedding tests can once again be built with clang 6.0

@item 
bpo-33163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33163}: Upgrade pip to 9.0.3 and setuptools to v39.0.1.

@item 
bpo-33012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33012}: gcc 8 has added a new warning heuristic to detect invalid
function casts and a stock python build seems to hit that warning quite
often.  The most common is the cast of a METH_NOARGS function (that uses
just one argument) to a PyCFunction. Fix this by adding a dummy argument
to all functions that implement METH_NOARGS.

@item 
bpo-32898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32898}: Fix the python debug build when using COUNT_ALLOCS.

@item 
bpo-29442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29442}: Replace optparse with argparse in setup.py
@end itemize

@node Windows<46>,macOS<37>,Build<50>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id461}@anchor{19da}
@subsubsection Windows



@itemize -

@item 
bpo-35890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35890}: Fix API calling consistency of GetVersionEx and wcstok.

@item 
bpo-32560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32560}: The @code{py} launcher now forwards its @code{STARTUPINFO} structure
to child processes.

@item 
bpo-35854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35854}: Fix EnvBuilder and --symlinks in venv on Windows

@item 
bpo-35811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35811}: Avoid propagating venv settings when launching via py.exe

@item 
bpo-35797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35797}: Fix default executable used by the multiprocessing module

@item 
bpo-35758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35758}: Allow building on ARM with MSVC.

@item 
bpo-29734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29734}: Fix handle leaks in os.stat on Windows.

@item 
bpo-35596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35596}: Use unchecked PYCs for the embeddable distro to avoid zipimport
restrictions.

@item 
bpo-35596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35596}: Fix vcruntime140.dll being added to embeddable distro multiple
times.

@item 
bpo-35402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35402}: Update Windows build to use Tcl and Tk 8.6.9

@item 
bpo-35401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35401}: Updates Windows build to OpenSSL 1.1.0j

@item 
bpo-34977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34977}: venv on Windows will now use a python.exe redirector rather
than copying the actual binaries from the base environment.

@item 
bpo-34977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34977}: Adds support for building a Windows App Store package

@item 
bpo-35067@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35067}: Remove _distutils_findvs module and use vswhere.exe instead.

@item 
bpo-32557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32557}: Allow shutil.disk_usage to take a file path on Windows

@item 
bpo-34770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34770}: Fix a possible null pointer dereference in pyshellext.cpp.

@item 
bpo-34603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34603}: Fix returning structs from functions produced by MSVC

@item 
bpo-34581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34581}: Guard MSVC-specific code in socketmodule.c with @code{#ifdef
_MSC_VER}.

@item 
bpo-34532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34532}: Fixes exit code of list version arguments for py.exe.

@item 
bpo-34062@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34062}: Fixed the '--list' and '--list-paths' arguments for the py.exe
launcher

@item 
bpo-34225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34225}: Ensure INCLUDE and LIB directories do not end with a backslash.

@item 
bpo-34011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34011}: A suite of code has been changed which copied across DLLs and
init.tcl from the running Python location into a venv being created. These
copies are needed only when running from a Python source build, and the
copying code is now only run when that is the case, rather than whenever a
venv is created.

@item 
bpo-34006@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34006}: Revert line length limit for Windows help docs. The line-length
limit is not needed because the pages appear in a separate app rather than
on a browser tab.  It can also interact badly with the DPI setting.

@item 
bpo-31546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31546}: Restore running PyOS_InputHook while waiting for user input at
the prompt. The restores integration of interactive GUI windows (such as
Matplotlib figures) with the prompt on Windows.

@item 
bpo-30237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30237}: Output error when ReadConsole is canceled by
CancelSynchronousIo instead of crashing.

@item 
bpo-33895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33895}: GIL is released while calling functions that acquire Windows
loader lock.

@item 
bpo-33720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33720}: Reduces maximum marshal recursion depth on release builds.

@item 
bpo-29097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29097}: Fix bug where @code{datetime.fromtimestamp()} erroneously throws
an @ref{40d,,OSError} on Windows for values between 0 and 86400. Patch by
Ammar Askar.

@item 
bpo-33316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33316}: PyThread_release_lock always fails

@item 
bpo-33184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33184}: Update Windows installer to use OpenSSL 1.1.0h.

@item 
bpo-32890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32890}: Fix usage of GetLastError() instead of errno in os.execve() and
os.truncate().

@item 
bpo-33016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33016}: Fix potential use of uninitialized memory in
nt._getfinalpathname

@item 
bpo-32903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32903}: Fix a memory leak in os.chdir() on Windows if the current
directory is set to a UNC path.

@item 
bpo-32901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32901}: Update Tcl and Tk versions to 8.6.8

@item 
bpo-31966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31966}: Fixed WindowsConsoleIO.write() for writing empty data.

@item 
bpo-32409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32409}: Ensures activate.bat can handle Unicode contents.

@item 
bpo-32457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32457}: Improves handling of denormalized executable path when
launching Python.

@item 
bpo-32370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32370}: Use the correct encoding for ipconfig output in the uuid
module. Patch by Segev Finer.

@item 
bpo-29248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29248}: Fix @ref{90d,,os.readlink()} on Windows, which was mistakenly
treating the @code{PrintNameOffset} field of the reparse data buffer as a
number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

@item 
bpo-1104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1104}: Correctly handle string length in
@code{msilib.SummaryInfo.GetProperty()} to prevent it from truncating the
last character.
@end itemize

@node macOS<37>,IDLE<37>,Windows<46>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id462}@anchor{19db}
@subsubsection macOS



@itemize -

@item 
bpo-35401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35401}: Update macOS installer to use OpenSSL 1.1.0j.

@item 
bpo-35025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35025}: Properly guard the use of the @code{CLOCK_GETTIME} et al. macros
in @code{timemodule} on macOS.

@item 
bpo-24658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24658}: On macOS, fix reading from and writing into a file with a size
larger than 2 GiB.

@item 
bpo-34405@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34405}: Update to OpenSSL 1.1.0i for macOS installer builds.

@item 
bpo-33635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33635}: In macOS stat on some file descriptors (/dev/fd/3 f.e) will
result in bad file descriptor OSError. Guard against this exception was
added in is_dir, is_file and similar methods. DirEntry.is_dir can also
throw this exception so _RecursiveWildcardSelector._iterate_directories
was also extended with the same error ignoring pattern.

@item 
bpo-13631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13631}: The .editrc file in user's home directory is now processed
correctly during the readline initialization through editline emulation on
macOS.

@item 
bpo-33184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33184}: Update macOS installer build to use OpenSSL 1.1.0h.

@item 
bpo-32726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32726}: Build and link with private copy of Tcl/Tk 8.6 for the macOS
10.6+ installer. The 10.9+ installer variant already does this.  This
means that the Python 3.7 provided by the python.org macOS installers no
longer need or use any external versions of Tcl/Tk, either system-provided
or user-installed, such as ActiveTcl.

@item 
bpo-32901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32901}: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.

@item 
bpo-31903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31903}: In @code{_scproxy}, drop the GIL when calling into
@code{SystemConfiguration} to avoid deadlocks.
@end itemize

@node IDLE<37>,Tools/Demos<25>,macOS<37>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id463}@anchor{19dc}
@subsubsection IDLE



@itemize -

@item 
bpo-35770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35770}: IDLE macosx deletes Options => Configure IDLE. It previously
deleted Window => Zoom Height by mistake. (Zoom Height is now on the
Options menu).  On Mac, the settings dialog is accessed via Preferences on
the IDLE menu.

@item 
bpo-35769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35769}: Change IDLE's new file name from 'Untitled' to 'untitled'

@item 
bpo-35660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35660}: Fix imports in idlelib.window.

@item 
bpo-35641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35641}: Proper format @code{calltip} when the function has no docstring.

@item 
bpo-33987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33987}: Use ttk Frame for ttk widgets.

@item 
bpo-34055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34055}: Fix erroneous 'smart' indents and newlines in IDLE Shell.

@item 
bpo-35591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35591}: Find Selection now works when selection not found.

@item 
bpo-35196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35196}: Speed up squeezer line counting.

@item 
bpo-35598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35598}: Update config_key: use PEP 8 names and ttk widgets, make some
objects global, and add tests.

@item 
bpo-28097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28097}: Add Previous/Next History entries to Shell menu.

@item 
bpo-35208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35208}: Squeezer now properly counts wrapped lines before newlines.

@item 
bpo-35555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35555}: Gray out Code Context menu entry when it's not applicable.

@item 
bpo-35521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35521}: Document the IDLE editor code context feature. Add some
internal references within the IDLE doc.

@item 
bpo-22703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22703}: The Code Context menu label now toggles between Show/Hide Code
Context. The Zoom Height menu now toggles between Zoom/Restore Height.
Zoom Height has moved from the Window menu to the Options menu.

@item 
bpo-35213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35213}: Where appropriate, use 'macOS' in idlelib.

@item 
bpo-34864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34864}: On macOS, warn if the system preference "Prefer tabs when
opening documents" is set to "Always".

@item 
bpo-34864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34864}: Document two IDLE on MacOS issues. The System Preferences Dock
"prefer tabs always" setting disables some IDLE features.  Menus are a bit
different than as described for Windows and Linux.

@item 
bpo-35202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35202}: Remove unused imports from lib/idlelib

@item 
bpo-33000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33000}: Document that IDLE's shell has no line limit. A program that
runs indefinitely can overfill memory.

@item 
bpo-23220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23220}: Explain how IDLE's Shell displays output.

@item 
bpo-35099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35099}: Improve the doc about IDLE running user code.   The section is
renamed from "IDLE -- console differences" is renamed "Running user code".
It mostly covers the implications of using custom @code{sys.std@var{xxx}}
objects.

@item 
bpo-35097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35097}: Add IDLE doc subsection explaining editor windows. Topics
include opening, title and status bar, .py* extension, and running.

@item 
bpo-35093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35093}: Document the IDLE document viewer in the IDLE doc. Add a
paragraph in "Help and preferences", "Help sources" subsection.

@item 
bpo-35088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35088}: Update idlelib.help.copy_string docstring. We now use git and
backporting instead of hg and forward merging.

@item 
bpo-35087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35087}: Update idlelib help files for the current doc build. The main
change is the elimination of chapter-section numbers.

@item 
bpo-34548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34548}: Use configured color theme for read-only text views.

@item 
bpo-1529353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1529353}: Enable "squeezing" of long outputs in the shell, to avoid
performance degradation and to clean up the history without losing it.
Squeezed outputs may be copied, viewed in a separate window, and
"unsqueezed".

@item 
bpo-34047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34047}: Fixed mousewheel scrolling direction on macOS.

@item 
bpo-34275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34275}: Make IDLE calltips always visible on Mac. Some MacOS-tk
combinations need .update_idletasks(). Patch by Kevin Walzer.

@item 
bpo-34120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34120}: Fix unresponsiveness after closing certain windows and dialogs.

@item 
bpo-33975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33975}: Avoid small type when running htests. Since part of the purpose
of human-viewed tests is to determine that widgets look right, it is
important that they look the same for testing as when running IDLE.

@item 
bpo-33905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33905}: Add test for idlelib.stackview.StackBrowser.

@item 
bpo-33924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33924}: Change mainmenu.menudefs key 'windows' to 'window'. Every other
menudef key is lowercase version of main menu entry.

@item 
bpo-33906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33906}: Rename idlelib.windows as window Match Window on the main menu
and remove last plural module name.

@item 
bpo-33917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33917}: Fix and document idlelib/idle_test/template.py. The revised
file compiles, runs, and tests OK.  idle_test/README.txt explains how to
use it to create new IDLE test files.

@item 
bpo-33904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33904}: IDLE: In rstrip, rename class RstripExtension as Rstrip

@item 
bpo-33907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33907}: For consistency and clarity, rename an IDLE module and classes.
Module calltips and its class CallTips are now calltip and Calltip. In
module calltip_w, class CallTip is now CalltipWindow.

@item 
bpo-33856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33856}: Add "help" in the welcome message of IDLE

@item 
bpo-33839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33839}: IDLE: refactor ToolTip and CallTip and add documentation and
tests

@item 
bpo-33855@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33855}: Minimally test all IDLE modules. Add missing files, import
module, instantiate classes, and check coverage. Check existing files.

@item 
bpo-33656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33656}: On Windows, add API call saying that tk scales for DPI. On
Windows 8.1+ or 10, with DPI compatibility properties of the Python binary
unchanged, and a monitor resolution greater than 96 DPI, this should make
text and lines sharper.  It should otherwise have no effect.

@item 
bpo-33768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33768}: Clicking on a context line moves that line to the top of the
editor window.

@item 
bpo-33763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33763}: IDLE: Use read-only text widget for code context instead of
label widget.

@item 
bpo-33664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33664}: Scroll IDLE editor text by lines. Previously, the mouse wheel
and scrollbar slider moved text by a fixed number of pixels, resulting in
partial lines at the top of the editor box.  The change also applies to
the shell and grep output windows, but not to read-only text views.

@item 
bpo-33679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33679}: Enable theme-specific color configuration for Code Context. Use
the Highlights tab to see the setting for built-in themes or add settings
to custom themes.

@item 
bpo-33642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33642}: Display up to maxlines non-blank lines for Code Context. If
there is no current context, show a single blank line.

@item 
bpo-33628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33628}: IDLE: Cleanup codecontext.py and its test.

@item 
bpo-33564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33564}: IDLE's code context now recognizes async as a block opener.

@item 
bpo-21474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21474}: Update word/identifier definition from ascii to unicode. In
text and entry boxes, this affects selection by double-click, movement
left/right by control-left/right, and deletion left/right by
control-BACKSPACE/DEL.

@item 
bpo-33204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33204}: IDLE: consistently color invalid string prefixes. A 'u' string
prefix cannot be paired with either 'r' or 'f'. Consistently color as much
of the prefix, starting at the right, as is valid. Revise and extend
colorizer test.

@item 
bpo-32984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32984}: Set @code{__file__} while running a startup file.  Like Python,
IDLE optionally runs one startup file in the Shell window before
presenting the first interactive input prompt.  For IDLE, @code{-s} runs a
file named in environmental variable  
@geindex IDLESTARTUP
@geindex variable d'environnement; IDLESTARTUP
@code{IDLESTARTUP} or
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP}; @code{-r file} runs @code{file}.  Python sets
@code{__file__} to the startup file name before running the file and unsets
it before the first prompt.  IDLE now does the same when run normally,
without the @code{-n} option.

@item 
bpo-32940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32940}: Simplify and rename StringTranslatePseudoMapping in pyparse.

@item 
bpo-32916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32916}: Change @code{str} to @code{code} in pyparse.

@item 
bpo-32905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32905}: Remove unused code in pyparse module.

@item 
bpo-32874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32874}: Add tests for pyparse.

@item 
bpo-32837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32837}: Using the system and place-dependent default encoding for
open() is a bad idea for IDLE's system and location-independent files.

@item 
bpo-32826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32826}: Add "encoding=utf-8" to open() in IDLE's test_help_about. GUI
test test_file_buttons() only looks at initial ascii-only lines, but
failed on systems where open() defaults to 'ascii' because readline()
internally reads and decodes far enough ahead to encounter a non-ascii
character in CREDITS.txt.

@item 
bpo-32831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32831}: Add docstrings and tests for codecontext.

@item 
bpo-32765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32765}: Update configdialog General tab docstring to add new widgets to
the widget list.
@end itemize

@node Tools/Demos<25>,C API<49>,IDLE<37>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id464}@anchor{19dd}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-35884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35884}: Add a benchmark script for timing various ways to access
variables: @code{Tools/scripts/var_access_benchmark.py}.

@item 
bpo-34989@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34989}: python-gdb.py now handles errors on computing the line number
of a Python frame.

@item 
bpo-20260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20260}: Argument Clinic now has non-bitwise unsigned int converters.

@item 
bpo-32962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32962}: python-gdb now catches @code{UnicodeDecodeError} exceptions when
calling @code{string()}.

@item 
bpo-32962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32962}: python-gdb now catches ValueError on read_var(): when Python
has no debug symbols for example.

@item 
bpo-33189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33189}: @code{pygettext.py} now recognizes only literal strings as
docstrings and translatable strings, and rejects bytes literals and
f-string expressions.

@item 
bpo-31920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31920}: Fixed handling directories as arguments in the @code{pygettext}
script. Based on patch by Oleg Krasnikov.

@item 
bpo-29673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29673}: Fix pystackv and pystack gdbinit macros.

@item 
bpo-25427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25427}: Remove the pyvenv script in favor of @code{python3 -m venv} in
order to lower confusion as to what Python interpreter a virtual
environment will be created for.

@item 
bpo-32885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32885}: Add an @code{-n} flag for @code{Tools/scripts/pathfix.py} to disable
automatic backup creation (files with @code{~} suffix).

@item 
bpo-32222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32222}: Fix pygettext not extracting docstrings for functions with type
annotated arguments. Patch by Toby Harradine.

@item 
bpo-31583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31583}: Fix 2to3 for using with --add-suffix option but without
--output-dir option for relative path to files in current directory.
@end itemize

@node C API<49>,,Tools/Demos<25>,Python 3 8 0 alpha 1
@anchor{whatsnew/changelog id465}@anchor{19de}
@subsubsection C API



@itemize -

@item 
bpo-35713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35713}: The @code{PyByteArray_Init()} and @code{PyByteArray_Fini()}
functions have been removed. They did nothing since Python 2.7.4 and
Python 3.2.0, were excluded from the limited API (stable ABI), and were
not documented.

@item 
bpo-33817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33817}: Fixed @ref{15dd,,_PyBytes_Resize()} for empty bytes objects.

@item 
bpo-35322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35322}: Fix memory leak in @ref{bb8,,PyUnicode_EncodeLocale()} and
@ref{19df,,PyUnicode_EncodeFSDefault()} on error handling.

@item 
bpo-35059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35059}: The following C macros have been converted to static inline
functions: @ref{55a,,Py_INCREF()}, @ref{55b,,Py_DECREF()}, @ref{a53,,Py_XINCREF()},
@ref{779,,Py_XDECREF()}, @code{PyObject_INIT()},
@code{PyObject_INIT_VAR()}.

@item 
bpo-35296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35296}: @code{make install} now also installs the internal API:
@code{Include/internal/*.h} header files.

@item 
bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081}: Internal APIs surrounded by @code{#ifdef Py_BUILD_CORE} have been
moved from @code{Include/*.h} headers to new header files
@code{Include/internal/pycore_*.h}.

@item 
bpo-35259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35259}: Conditionally declare @ref{d03,,Py_FinalizeEx()} (new in 3.6)
based on Py_LIMITED_API. Patch by Arthur Neufeld.

@item 
bpo-35081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35081}: The @code{_PyObject_GC_TRACK()} and
@code{_PyObject_GC_UNTRACK()} macros have been removed from the public C
API.

@item 
bpo-35134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=35134}: Creation of a new @code{Include/cpython/} subdirectory.

@item 
bpo-34725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34725}: Adds _Py_SetProgramFullPath so embedders may override
sys.executable

@item 
bpo-34910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34910}: Ensure that @ref{1579,,PyObject_Print()} always returns @code{-1} on
error.  Patch by Zackery Spytz.

@item 
bpo-34523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34523}: Py_DecodeLocale() and Py_EncodeLocale() now use the UTF-8
encoding on Windows if Py_LegacyWindowsFSEncodingFlag is zero.

@item 
bpo-34193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34193}: Fix pluralization in TypeError messages in getargs.c and
typeobject.c: '1 argument' instead of '1 arguments' and '1 element'
instead of '1 elements'.

@item 
bpo-34127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34127}: Return grammatically correct error message based on argument
count. Patch by Karthikeyan Singaravelan.

@item 
bpo-23927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23927}: Fixed @ref{561,,SystemError} in
@ref{379,,PyArg_ParseTupleAndKeywords()} when the @code{w*} format unit is used
for optional parameter.

@item 
bpo-32455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32455}: Added @code{PyCompile_OpcodeStackEffectWithJump()}.

@item 
bpo-34008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34008}: Py_Main() can again be called after Py_Initialize(), as in
Python 3.6.

@item 
bpo-32500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32500}: Fixed error messages for @ref{19e0,,PySequence_Size()},
@ref{19e1,,PySequence_GetItem()}, @ref{19e2,,PySequence_SetItem()} and
@ref{19e3,,PySequence_DelItem()} called with a mapping and
@ref{19e4,,PyMapping_Size()} called with a sequence.

@item 
bpo-33818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33818}: @code{PyExceptionClass_Name()} will now return @code{const char
*} instead of @code{char *}.

@item 
bpo-33042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33042}: Embedding applications may once again call
PySys_ResetWarnOptions, PySys_AddWarnOption, and PySys_AddXOption prior to
calling Py_Initialize.

@item 
bpo-32374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32374}: Document that m_traverse for multi-phase initialized modules
can be called with m_state=NULL, and add a sanity check

@item 
bpo-30863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30863}: @ref{19e5,,PyUnicode_AsWideChar()} and
@ref{8a9,,PyUnicode_AsWideCharString()} no longer cache the @code{wchar_t*}
representation of string objects.
@end itemize

@node Python 3 7 0 final,Python 3 7 0 release candidate 1,Python 3 8 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-7-0-final}@anchor{19e6}
@subsection Python 3.7.0 final


`Release date: 2018-06-27'

@menu
* Library: Library<52>. 
* C API: C API<50>. 

@end menu

@node Library<52>,C API<50>,,Python 3 7 0 final
@anchor{whatsnew/changelog id466}@anchor{19e7}
@subsubsection Library



@itemize -

@item 
bpo-33851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33851}: Fix @ref{19e8,,ast.get_docstring()} for a node that lacks a
docstring.
@end itemize

@node C API<50>,,Library<52>,Python 3 7 0 final
@anchor{whatsnew/changelog id467}@anchor{19e9}
@subsubsection C API



@itemize -

@item 
bpo-33932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33932}: Calling Py_Initialize() twice does nothing, instead of failing
with a fatal error: restore the Python 3.6 behaviour.
@end itemize

@node Python 3 7 0 release candidate 1,Python 3 7 0 beta 5,Python 3 7 0 final,Changelog
@anchor{whatsnew/changelog python-3-7-0-release-candidate-1}@anchor{19ea}
@subsection Python 3.7.0 release candidate 1


`Release date: 2018-06-12'

@menu
* Core and Builtins: Core and Builtins<53>. 
* Library: Library<53>. 
* Documentation: Documentation<47>. 
* Build: Build<51>. 
* Windows: Windows<47>. 
* IDLE: IDLE<38>. 

@end menu

@node Core and Builtins<53>,Library<53>,,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id468}@anchor{19eb}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-33803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33803}: Fix a crash in hamt.c caused by enabling GC tracking for an
object that hadn't all of its fields set to NULL.

@item 
bpo-33706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33706}: Fix a crash in Python initialization when parsing the command
line options. Thanks Christoph Gohlke for the bug report and the fix!

@item 
bpo-30654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30654}: Fixed reset of the SIGINT handler to SIG_DFL on interpreter
shutdown even when there was a custom handler set previously. Patch by
Philipp Kerling.

@item 
bpo-31849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31849}: Fix signed/unsigned comparison warning in pyhash.c.
@end itemize

@node Library<53>,Documentation<47>,Core and Builtins<53>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id469}@anchor{19ec}
@subsubsection Library



@itemize -

@item 
bpo-30167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30167}: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by
Steve Weber.

@item 
bpo-33812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33812}: Datetime instance d with non-None tzinfo, but with
d.tzinfo.utcoffset(d) returning None is now treated as naive by the
astimezone() method.

@item 
bpo-30805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30805}: Avoid race condition with debug logging

@item 
bpo-33694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33694}: asyncio: Fix a race condition causing data loss on
pause_reading()/resume_reading() when using the ProactorEventLoop.

@item 
bpo-32493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32493}: Correct test for @code{uuid_enc_be} availability in
@code{configure.ac}. Patch by Michael Felt.

@item 
bpo-33792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33792}: Add asyncio.WindowsSelectorEventLoopPolicy and
asyncio.WindowsProactorEventLoopPolicy.

@item 
bpo-33778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33778}: Update @code{unicodedata}'s database to Unicode version 11.0.0.

@item 
bpo-33770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33770}: improve base64 exception message for encoded inputs of invalid
length

@item 
bpo-33769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33769}: asyncio/start_tls: Fix error message; cancel callbacks in case
of an unhandled error; mark SSLTransport as closed if it is aborted.

@item 
bpo-33767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33767}: The concatenation (@code{+}) and repetition (@code{*}) sequence
operations now raise @ref{522,,TypeError} instead of @ref{561,,SystemError} when
performed on @ref{208,,mmap.mmap} objects.  Patch by Zackery Spytz.

@item 
bpo-33734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33734}: asyncio/ssl: Fix AttributeError, increase default handshake
timeout

@item 
bpo-11874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11874}: Use a better regex when breaking usage into wrappable parts.
Avoids bogus assertion errors from custom metavar strings.

@item 
bpo-33582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33582}: Emit a deprecation warning for inspect.formatargspec
@end itemize

@node Documentation<47>,Build<51>,Library<53>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id470}@anchor{19ed}
@subsubsection Documentation



@itemize -

@item 
bpo-33409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33409}: Clarified the relationship between 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}'s
PYTHONCOERCECLOCALE and PEP 540's PYTHONUTF8 mode.

@item 
bpo-33736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33736}: Improve the documentation of @ref{b06,,asyncio.open_connection()},
@ref{b07,,asyncio.start_server()} and their UNIX socket counterparts.

@item 
bpo-31432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31432}: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED
flags for ssl.SSLContext.verify_mode.
@end itemize

@node Build<51>,Windows<47>,Documentation<47>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id471}@anchor{19ee}
@subsubsection Build



@itemize -

@item 
bpo-5755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5755}: Move @code{-Wstrict-prototypes} option to @code{CFLAGS_NODIST} from
@code{OPT}. This option emitted annoying warnings when building extension
modules written in C++.
@end itemize

@node Windows<47>,IDLE<38>,Build<51>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id472}@anchor{19ef}
@subsubsection Windows



@itemize -

@item 
bpo-33720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33720}: Reduces maximum marshal recursion depth on release builds.
@end itemize

@node IDLE<38>,,Windows<47>,Python 3 7 0 release candidate 1
@anchor{whatsnew/changelog id473}@anchor{19f0}
@subsubsection IDLE



@itemize -

@item 
bpo-33656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33656}: On Windows, add API call saying that tk scales for DPI. On
Windows 8.1+ or 10, with DPI compatibility properties of the Python binary
unchanged, and a monitor resolution greater than 96 DPI, this should make
text and lines sharper.  It should otherwise have no effect.

@item 
bpo-33768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33768}: Clicking on a context line moves that line to the top of the
editor window.

@item 
bpo-33763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33763}: IDLE: Use read-only text widget for code context instead of
label widget.

@item 
bpo-33664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33664}: Scroll IDLE editor text by lines. Previously, the mouse wheel
and scrollbar slider moved text by a fixed number of pixels, resulting in
partial lines at the top of the editor box.  The change also applies to
the shell and grep output windows, but not to read-only text views.

@item 
bpo-33679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33679}: Enable theme-specific color configuration for Code Context. Use
the Highlights tab to see the setting for built-in themes or add settings
to custom themes.

@item 
bpo-33642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33642}: Display up to maxlines non-blank lines for Code Context. If
there is no current context, show a single blank line.
@end itemize

@node Python 3 7 0 beta 5,Python 3 7 0 beta 4,Python 3 7 0 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-7-0-beta-5}@anchor{19f1}
@subsection Python 3.7.0 beta 5


`Release date: 2018-05-30'

@menu
* Core and Builtins: Core and Builtins<54>. 
* Library: Library<54>. 
* Documentation: Documentation<48>. 
* Tests: Tests<49>. 
* Build: Build<52>. 
* macOS: macOS<38>. 
* IDLE: IDLE<39>. 

@end menu

@node Core and Builtins<54>,Library<54>,,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id474}@anchor{19f2}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-33622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33622}: Fixed a leak when the garbage collector fails to add an object
with the @code{__del__} method or referenced by it into the
@ref{119e,,gc.garbage} list. @ref{97b,,PyGC_Collect()} can now be called when an
exception is set and preserves it.

@item 
bpo-33509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33509}: Fix module_globals parameter of warnings.warn_explicit(): don't
crash if module_globals is not a dict.

@item 
bpo-20104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20104}: The new @code{os.posix_spawn} added in 3.7.0b1 was removed as we
are still working on what the API should look like.  Expect this in 3.8
instead.

@item 
bpo-33475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33475}: Fixed miscellaneous bugs in converting annotations to strings
and optimized parentheses in the string representation.

@item 
bpo-33391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33391}: Fix a leak in set_symmetric_difference().

@item 
bpo-28055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28055}: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

@item 
bpo-32911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32911}: Due to unexpected compatibility issues discovered during
downstream beta testing, reverted bpo-29463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29463}. @code{docstring} field is
removed from Module, ClassDef, FunctionDef, and AsyncFunctionDef ast nodes
which was added in 3.7a1.  Docstring expression is restored as a first
statement in their body. Based on patch by Inada Naoki.

@item 
bpo-21983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21983}: Fix a crash in @code{ctypes.cast()} in case the type argument is a
ctypes structured data type. Patch by Eryk Sun and Oren Milman.
@end itemize

@node Library<54>,Documentation<48>,Core and Builtins<54>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id475}@anchor{19f3}
@subsubsection Library



@itemize -

@item 
bpo-32751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32751}: When cancelling the task due to a timeout,
@ref{5ea,,asyncio.wait_for()} will now wait until the cancellation is complete.

@item 
bpo-32684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32684}: Fix gather to propagate cancellation of itself even with
return_exceptions.

@item 
bpo-33654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33654}: Support protocol type switching in SSLTransport.set_protocol().

@item 
bpo-33674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33674}: Pause the transport as early as possible to further reduce the
risk of data_received() being called before connection_made().

@item 
bpo-33674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33674}: Fix a race condition in SSLProtocol.connection_made() of
asyncio.sslproto: start immediately the handshake instead of using
call_soon(). Previously, data_received() could be called before the
handshake started, causing the handshake to hang or fail.

@item 
bpo-31647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31647}: Fixed bug where calling write_eof() on a
_SelectorSocketTransport after it's already closed raises AttributeError.

@item 
bpo-32610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32610}: Make asyncio.all_tasks() return only pending tasks.

@item 
bpo-32410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32410}: Avoid blocking on file IO in sendfile fallback code

@item 
bpo-33469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33469}: Fix RuntimeError after closing loop that used run_in_executor

@item 
bpo-33672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33672}: Fix Task.__repr__ crash with Cython's bogus coroutines

@item 
bpo-33654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33654}: Fix transport.set_protocol() to support switching between
asyncio.Protocol and asyncio.BufferedProtocol.  Fix loop.start_tls() to
work with asyncio.BufferedProtocols.

@item 
bpo-33652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33652}: Pickles of type variables and subscripted generics are now
future-proof and compatible with older Python versions.

@item 
bpo-32493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32493}: Fixed @ref{b96,,uuid.uuid1()} on FreeBSD.

@item 
bpo-33618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33618}: Finalize and document preliminary and experimental TLS 1.3
support with OpenSSL 1.1.1

@item 
bpo-33623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33623}: Fix possible SIGSGV when asyncio.Future is created in __del__

@item 
bpo-30877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30877}: Fixed a bug in the Python implementation of the JSON decoder
that prevented the cache of parsed strings from clearing after finishing
the decoding. Based on patch by c-fos.

@item 
bpo-33570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33570}: Change TLS 1.3 cipher suite settings for compatibility with
OpenSSL 1.1.1-pre6 and newer. OpenSSL 1.1.1 will have TLS 1.3 ciphers
enabled by default.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Do not simplify arguments to @code{typing.Union}. Now
@code{Union[Manager, Employee]} is not simplified to @code{Employee} at runtime.
Such simplification previously caused several bugs and limited
possibilities for introspection.

@item 
bpo-33540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33540}: Add a new @code{block_on_close} class attribute to
@code{ForkingMixIn} and @code{ThreadingMixIn} classes of @ref{cc,,socketserver}.

@item 
bpo-33548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33548}: tempfile._candidate_tempdir_list should consider common TEMP
locations

@item 
bpo-33109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33109}: argparse subparsers are once again not required by default,
reverting the change in behavior introduced by bpo-26510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26510} in 3.7.0a2.

@item 
bpo-33536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33536}: dataclasses.make_dataclass now checks for invalid field names
and duplicate fields. Also, added a check for invalid field
specifications.

@item 
bpo-33542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33542}: Prevent @code{uuid.get_node} from using a DUID instead of a MAC on
Windows. Patch by Zvi Effron

@item 
bpo-26819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26819}: Fix race condition with @code{ReadTransport.resume_reading} in
Windows proactor event loop.

@item 
Fix failure in @code{typing.get_type_hints()} when ClassVar was provided as a
string forward reference.

@item 
bpo-33505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33505}: Optimize asyncio.ensure_future() by reordering if checks: 1.17x
faster.

@item 
bpo-33497@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33497}: Add errors param to cgi.parse_multipart and make an encoding in
FieldStorage use the given errors (needed for Twisted).  Patch by Amber
Brown.

@item 
bpo-33495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33495}: Change dataclasses.Fields repr to use the repr of each of its
members, instead of str.  This makes it more clear what each field
actually represents.  This is especially true for the 'type' member.

@item 
bpo-33453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33453}: Fix dataclasses to work if using literal string type
annotations or if using PEP 563 "Postponed Evaluation of Annotations".
Only specific string prefixes are detected for both ClassVar ("ClassVar"
and "typing.ClassVar") and InitVar ("InitVar" and "dataclasses.InitVar").

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Minor fixes in typing module: add annotations to
@code{NamedTuple.__new__}, pass @code{*args} and @code{**kwds} in
@code{Generic.__new__}.  Original PRs by Paulius Šarka and Chad Dombrova.

@item 
bpo-20087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20087}: Updated alias mapping with glibc 2.27 supported locales.

@item 
bpo-33422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33422}: Fix trailing quotation marks getting deleted when looking up
byte/string literals on pydoc. Patch by Andrés Delfino.

@item 
bpo-28167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28167}: The function @code{platform.linux_distribution} and
@code{platform.dist} now trigger a @code{DeprecationWarning} and have been
marked for removal in Python 3.8

@item 
bpo-33197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33197}: Update error message when constructing invalid
inspect.Parameters Patch by Donghee Na.

@item 
bpo-33263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33263}: Fix FD leak in @code{_SelectorSocketTransport}  Patch by Vlad
Starostin.

@item 
bpo-32861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32861}: The urllib.robotparser's @code{__str__} representation now
includes wildcard entries and the "Crawl-delay" and "Request-rate" fields.
Patch by Michael Lazar.

@item 
bpo-32257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32257}: The ssl module now contains OP_NO_RENEGOTIATION constant,
available with OpenSSL 1.1.0h or 1.1.1.

@item 
bpo-16865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16865}: Support arrays >=2GiB in @ref{2a,,ctypes}.  Patch by Segev Finer.
@end itemize

@node Documentation<48>,Tests<49>,Library<54>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id476}@anchor{19f4}
@subsubsection Documentation



@itemize -

@item 
bpo-23859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23859}: Document that @code{asyncio.wait()} does not cancel its futures on
timeout.

@item 
bpo-32436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32436}: Document 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} changes to asyncio.

@item 
bpo-33604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33604}: Update HMAC md5 default to a DeprecationWarning, bump removal
to 3.8.

@item 
bpo-33503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33503}: Fix broken pypi link

@item 
bpo-33421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33421}: Add missing documentation for @code{typing.AsyncContextManager}.
@end itemize

@node Tests<49>,Build<52>,Documentation<48>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id477}@anchor{19f5}
@subsubsection Tests



@itemize -

@item 
bpo-33655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33655}: Ignore test_posix_fallocate failures on BSD platforms that
might be due to running on ZFS.

@item 
bpo-32604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32604}: Remove the _xxsubinterpreters module (meant for testing) and
associated helpers.  This module was originally added recently in 3.7b1.
@end itemize

@node Build<52>,macOS<38>,Tests<49>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id478}@anchor{19f6}
@subsubsection Build



@itemize -

@item 
bpo-33614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33614}: Ensures module definition files for the stable ABI on Windows
are correctly regenerated.

@item 
bpo-33522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33522}: Enable CI builds on Visual Studio Team Services at
@indicateurl{https://python.visualstudio.com/cpython}

@item 
bpo-33012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33012}: Add @code{-Wno-cast-function-type} for gcc 8 for silencing
warnings about function casts like casting to PyCFunction in method
definition lists.
@end itemize

@node macOS<38>,IDLE<39>,Build<52>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id479}@anchor{19f7}
@subsubsection macOS



@itemize -

@item 
bpo-13631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13631}: The .editrc file in user's home directory is now processed
correctly during the readline initialization through editline emulation on
macOS.
@end itemize

@node IDLE<39>,,macOS<38>,Python 3 7 0 beta 5
@anchor{whatsnew/changelog id480}@anchor{19f8}
@subsubsection IDLE



@itemize -

@item 
bpo-33628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33628}: IDLE: Cleanup codecontext.py and its test.

@item 
bpo-33564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33564}: IDLE's code context now recognizes async as a block opener.

@item 
bpo-32831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32831}: Add docstrings and tests for codecontext.
@end itemize

@node Python 3 7 0 beta 4,Python 3 7 0 beta 3,Python 3 7 0 beta 5,Changelog
@anchor{whatsnew/changelog python-3-7-0-beta-4}@anchor{19f9}
@subsection Python 3.7.0 beta 4


`Release date: 2018-05-02'

@menu
* Core and Builtins: Core and Builtins<55>. 
* Library: Library<55>. 
* Documentation: Documentation<49>. 
* Tests: Tests<50>. 
* Build: Build<53>. 
* Windows: Windows<48>. 
* macOS: macOS<39>. 
* IDLE: IDLE<40>. 
* Tools/Demos: Tools/Demos<26>. 

@end menu

@node Core and Builtins<55>,Library<55>,,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id481}@anchor{19fa}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-33363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33363}: Raise a SyntaxError for @code{async with} and @code{async for}
statements outside of async functions.

@item 
bpo-33128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33128}: Fix a bug that causes PathFinder to appear twice on
sys.meta_path. Patch by Pablo Galindo Salgado.

@item 
bpo-33312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33312}: Fixed clang ubsan (undefined behavior sanitizer) warnings in
dictobject.c by adjusting how the internal struct _dictkeysobject shared
keys structure is declared.

@item 
bpo-33231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33231}: Fix potential memory leak in @code{normalizestring()}.

@item 
bpo-33205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33205}: Change dict growth function from
@code{round_up_to_power_2(used*2+hashtable_size/2)} to
@code{round_up_to_power_2(used*3)}.  Previously, dict is shrinked only when
@code{used == 0}. Now dict has more chance to be shrinked.

@item 
bpo-29922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29922}: Improved error messages in 'async with' when @code{__aenter__()}
or @code{__aexit__()} return non-awaitable object.

@item 
bpo-33199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33199}: Fix @code{ma_version_tag} in dict implementation is uninitialized
when copying from key-sharing dict.
@end itemize

@node Library<55>,Documentation<49>,Core and Builtins<55>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id482}@anchor{19fb}
@subsubsection Library



@itemize -

@item 
bpo-33281@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33281}: Fix ctypes.util.find_library regression on macOS.

@item 
bpo-33383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33383}: Fixed crash in the get() method of the @ref{34,,dbm.ndbm} database
object when it is called with a single argument.

@item 
bpo-33329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33329}: Fix multiprocessing regression on newer glibcs

@item 
bpo-991266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=991266}: Fix quoting of the @code{Comment} attribute of
@ref{19d1,,http.cookies.SimpleCookie}.

@item 
bpo-33131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33131}: Upgrade bundled version of pip to 10.0.1.

@item 
bpo-33308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33308}: Fixed a crash in the @code{parser} module when converting an ST
object to a tree of tuples or lists with @code{line_info=False} and
@code{col_info=True}.

@item 
bpo-33266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33266}: lib2to3 now recognizes @code{rf'...'} strings.

@item 
bpo-11594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11594}: Ensure line-endings are respected when using lib2to3.

@item 
bpo-33254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33254}: Have @ref{1ef,,importlib.resources.contents()} and
@ref{19d2,,importlib.abc.ResourceReader.contents()} return an @ref{1205,,iterable}
instead of an @ref{1aa,,iterator}.

@item 
bpo-33256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33256}: Fix display of @code{<module>} call in the html produced by
@code{cgitb.html()}. Patch by Stéphane Blondon.

@item 
bpo-33185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33185}: Fixed regression when running pydoc with the @ref{5cb,,-m}
switch. (The regression was introduced in 3.7.0b3 by the resolution of
bpo-33053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33053}) This fix also changed pydoc to add @code{os.getcwd()} to
@ref{3ab,,sys.path} when necessary, rather than adding @code{"."}.

@item 
bpo-33169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33169}: Delete entries of @code{None} in @ref{5ce,,sys.path_importer_cache}
when @code{importlib.machinery.invalidate_caches()} is called.

@item 
bpo-33217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33217}: Deprecate looking up non-Enum objects in Enum classes and Enum
members (will raise @ref{522,,TypeError} in 3.8+).

@item 
bpo-33203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33203}: @code{random.Random.choice()} now raises @code{IndexError} for empty
sequences consistently even when called from subclasses without a
@code{getrandbits()} implementation.

@item 
bpo-33224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33224}: Update difflib.mdiff() for 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}.  Convert an uncaught
StopIteration in a generator into a return-statement.

@item 
bpo-33209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33209}: End framing at the end of C implementation of
@ref{19d3,,pickle.Pickler.dump()}.

@item 
bpo-20104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20104}: Improved error handling and fixed a reference leak in
@ref{21d,,os.posix_spawn()}.

@item 
bpo-33175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33175}: In dataclasses, Field.__set_name__ now looks up the
__set_name__ special method on the class, not the instance, of the default
value.

@item 
bpo-33097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33097}: Raise RuntimeError when @code{executor.submit} is called during
interpreter shutdown.

@item 
bpo-31908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31908}: Fix output of cover files for @code{trace} module command-line
tool. Previously emitted cover files only when @code{--missing} option was
used. Patch by Michael Selik.
@end itemize

@node Documentation<49>,Tests<50>,Library<55>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id483}@anchor{19fc}
@subsubsection Documentation



@itemize -

@item 
bpo-33378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33378}: Add Korean language switcher for @indicateurl{https://docs.python.org/3/}

@item 
bpo-33276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33276}: Clarify that the @code{__path__} attribute on modules cannot be
just any value.

@item 
bpo-33201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33201}: Modernize documentation for writing C extension types.

@item 
bpo-33195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33195}: Deprecate @code{Py_UNICODE} usage in @code{c-api/arg} document.
@code{Py_UNICODE} related APIs are deprecated since Python 3.3, but it is
missed in the document.

@item 
bpo-8243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8243}: Add a note about curses.addch and curses.addstr exception
behavior when writing outside a window, or pad.

@item 
bpo-32337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32337}: Update documentation related with @code{dict} order.
@end itemize

@node Tests<50>,Build<53>,Documentation<49>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id484}@anchor{19fd}
@subsubsection Tests



@itemize -

@item 
bpo-33358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33358}: Fix @code{test_embed.test_pre_initialization_sys_options()} when
the interpreter is built with @code{--enable-shared}.
@end itemize

@node Build<53>,Windows<48>,Tests<50>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id485}@anchor{19fe}
@subsubsection Build



@itemize -

@item 
bpo-33394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33394}: Enable the verbose build for extension modules, when GNU make
is passed macros on the command line.

@item 
bpo-33393@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33393}: Update config.guess and config.sub files.

@item 
bpo-33377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33377}: Add new triplets for mips r6 and riscv variants (used in
extension suffixes).

@item 
bpo-32232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32232}: By default, modules configured in @code{Modules/Setup} are no
longer built with @code{-DPy_BUILD_CORE}. Instead, modules that specifically
need that preprocessor definition include it in their individual entries.

@item 
bpo-33182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33182}: The embedding tests can once again be built with clang 6.0
@end itemize

@node Windows<48>,macOS<39>,Build<53>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id486}@anchor{19ff}
@subsubsection Windows



@itemize -

@item 
bpo-33184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33184}: Update Windows installer to use OpenSSL 1.1.0h.
@end itemize

@node macOS<39>,IDLE<40>,Windows<48>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id487}@anchor{1a00}
@subsubsection macOS



@itemize -

@item 
bpo-33184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33184}: Update macOS installer build to use OpenSSL 1.1.0h.
@end itemize

@node IDLE<40>,Tools/Demos<26>,macOS<39>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id488}@anchor{1a01}
@subsubsection IDLE



@itemize -

@item 
bpo-21474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21474}: Update word/identifier definition from ascii to unicode. In
text and entry boxes, this affects selection by double-click, movement
left/right by control-left/right, and deletion left/right by
control-BACKSPACE/DEL.

@item 
bpo-33204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33204}: IDLE: consistently color invalid string prefixes. A 'u' string
prefix cannot be paired with either 'r' or 'f'. Consistently color as much
of the prefix, starting at the right, as is valid. Revise and extend
colorizer test.
@end itemize

@node Tools/Demos<26>,,IDLE<40>,Python 3 7 0 beta 4
@anchor{whatsnew/changelog id489}@anchor{1a02}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-33189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33189}: @code{pygettext.py} now recognizes only literal strings as
docstrings and translatable strings, and rejects bytes literals and
f-string expressions.

@item 
bpo-31920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31920}: Fixed handling directories as arguments in the @code{pygettext}
script. Based on patch by Oleg Krasnikov.

@item 
bpo-29673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29673}: Fix pystackv and pystack gdbinit macros.

@item 
bpo-31583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31583}: Fix 2to3 for using with --add-suffix option but without
--output-dir option for relative path to files in current directory.
@end itemize

@node Python 3 7 0 beta 3,Python 3 7 0 beta 2,Python 3 7 0 beta 4,Changelog
@anchor{whatsnew/changelog python-3-7-0-beta-3}@anchor{1a03}
@subsection Python 3.7.0 beta 3


`Release date: 2018-03-29'

@menu
* Security: Security<36>. 
* Core and Builtins: Core and Builtins<56>. 
* Library: Library<56>. 
* Documentation: Documentation<50>. 
* Tests: Tests<51>. 
* Build: Build<54>. 
* Windows: Windows<49>. 
* macOS: macOS<40>. 
* IDLE: IDLE<41>. 
* Tools/Demos: Tools/Demos<27>. 
* C API: C API<51>. 

@end menu

@node Security<36>,Core and Builtins<56>,,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id490}@anchor{1a04}
@subsubsection Security



@itemize -

@item 
bpo-33136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33136}: Harden ssl module against LibreSSL 
@geindex Common Vulnerabilities and Exposures; CVE 2018-8970
CVE 2018-8970@footnote{https://www.cve.org/CVERecord?id=CVE-2018-8970}.
X509_VERIFY_PARAM_set1_host() is called with an explicit namelen. A new
test ensures that NULL bytes are not allowed.

@item 
bpo-33001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33001}: Minimal fix to prevent buffer overrun in os.symlink on Windows

@item 
bpo-32981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32981}: Regexes in difflib and poplib were vulnerable to catastrophic
backtracking. These regexes formed potential DOS vectors (REDOS). They
have been refactored. This resolves 
@geindex Common Vulnerabilities and Exposures; CVE 2018-1060
CVE 2018-1060@footnote{https://www.cve.org/CVERecord?id=CVE-2018-1060} and 
@geindex Common Vulnerabilities and Exposures; CVE 2018-1061
CVE 2018-1061@footnote{https://www.cve.org/CVERecord?id=CVE-2018-1061}.
Patch by Jamie Davis.
@end itemize

@node Core and Builtins<56>,Library<56>,Security<36>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id491}@anchor{1a05}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-33053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33053}: When using the -m switch, sys.path[0] is now explicitly
expanded as the `starting' working directory, rather than being left as
the empty path (which allows imports from the current working directory at
the time of the import)

@item 
bpo-33018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33018}: Improve consistency of errors raised by @code{issubclass()} when
called with a non-class and an abstract base class as the first and second
arguments, respectively. Patch by Josh Bronson.

@item 
bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}: Fixed jumping when the function contains an @code{async for} loop.

@item 
bpo-33026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33026}: Fixed jumping out of "with" block by setting f_lineno.

@item 
bpo-33005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33005}: Fix a crash on fork when using a custom memory allocator (ex:
using PYTHONMALLOC env var). _PyGILState_Reinit() and
_PyInterpreterState_Enable() now use the default RAW memory allocator to
allocate a new interpreters mutex on fork.

@item 
bpo-17288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17288}: Prevent jumps from 'return' and 'exception' trace events.

@item 
bpo-32836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32836}: Don't use temporary variables in cases of list/dict/set
comprehensions
@end itemize

@node Library<56>,Documentation<50>,Core and Builtins<56>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id492}@anchor{1a06}
@subsubsection Library



@itemize -

@item 
bpo-33141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33141}: Have Field objects pass through __set_name__ to their default
values, if they have their own __set_name__.

@item 
bpo-33096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33096}: Allow ttk.Treeview.insert to insert iid that has a false
boolean value. Note iid=0 and iid=False would be same. Patch by Garvit
Khatri.

@item 
bpo-32873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32873}: Treat type variables and special typing forms as immutable by
copy and pickle.  This fixes several minor issues and inconsistencies, and
improves backwards compatibility with Python 3.6.

@item 
bpo-33134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33134}: When computing dataclass's __hash__, use the lookup table to
contain the function which returns the __hash__ value.  This is an
improvement over looking up a string, and then testing that string to see
what to do.

@item 
bpo-33127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33127}: The ssl module now compiles with LibreSSL 2.7.1.

@item 
bpo-32505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32505}: Raise TypeError if a member variable of a dataclass is of type
Field, but doesn't have a type annotation.

@item 
bpo-33078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33078}: Fix the failure on OSX caused by the tests relying on
sem_getvalue

@item 
bpo-33116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33116}: Add 'Field' to dataclasses.__all__.

@item 
bpo-32896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32896}: Fix an error where subclassing a dataclass with a field that
uses a default_factory would generate an incorrect class.

@item 
bpo-33100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33100}: Dataclasses: If a field has a default value that's a
MemberDescriptorType, then it's from that field being in __slots__, not an
actual default value.

@item 
bpo-32953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32953}: If a non-dataclass inherits from a frozen dataclass, allow
attributes to be added to the derived class.  Only attributes from the
frozen dataclass cannot be assigned to.  Require all dataclasses in a
hierarchy to be either all frozen or all non-frozen.

@item 
bpo-33061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33061}: Add missing @code{NoReturn} to @code{__all__} in typing.py

@item 
bpo-33078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33078}: Fix the size handling in multiprocessing.Queue when a pickling
error occurs.

@item 
bpo-33064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33064}: lib2to3 now properly supports trailing commas after @code{*args}
and @code{**kwargs} in function signatures.

@item 
bpo-33056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33056}: FIX properly close leaking fds in
concurrent.futures.ProcessPoolExecutor.

@item 
bpo-33021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33021}: Release the GIL during fstat() calls, avoiding hang of all
threads when calling mmap.mmap(), os.urandom(), and random.seed().  Patch
by Nir Soffer.

@item 
bpo-31804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31804}: Avoid failing in multiprocessing.Process if the standard
streams are closed or None at exit.

@item 
bpo-33037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33037}: Skip sending/receiving data after SSL transport closing.

@item 
bpo-27683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27683}: Fix a regression in @ref{7f,,ipaddress} that result of
@code{hosts()} is empty when the network is constructed by a tuple
containing an integer mask and only 1 bit left for addresses.

@item 
bpo-32999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32999}: Fix C implementation of @code{ABC.__subclasscheck__(cls,
subclass)} crashed when @code{subclass} is not a type object.

@item 
bpo-33009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33009}: Fix inspect.signature() for single-parameter partialmethods.

@item 
bpo-32969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32969}: Expose several missing constants in zlib and fix corresponding
documentation.

@item 
bpo-32056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32056}: Improved exceptions raised for invalid number of channels and
sample width when read an audio file in modules @code{aifc}, @ref{112,,wave}
and @code{sunau}.

@item 
bpo-32844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32844}: Fix wrong redirection of a low descriptor (0 or 1) to stderr in
subprocess if another low descriptor is closed.

@item 
bpo-32857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32857}: In @ref{ef,,tkinter}, @code{after_cancel(None)} now raises a
@ref{1ff,,ValueError} instead of canceling the first scheduled function.
Patch by Cheryl Sabella.

@item 
bpo-31639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31639}: http.server now exposes a ThreadedHTTPServer class and uses it
when the module is run with @code{-m} to cope with web browsers pre-opening
sockets.

@item 
bpo-27645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27645}: @ref{242,,sqlite3.Connection} now exposes a
@ref{b68,,backup} method, if the underlying SQLite
library is at version 3.6.11 or higher.  Patch by Lele Gaifax.
@end itemize

@node Documentation<50>,Tests<51>,Library<56>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id493}@anchor{1a07}
@subsubsection Documentation



@itemize -

@item 
bpo-33126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33126}: Document PyBuffer_ToContiguous().

@item 
bpo-27212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27212}: Modify documentation for the @code{islice()} recipe to consume
initial values up to the start index.

@item 
bpo-28247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28247}: Update @ref{12f,,zipapp} documentation to describe how to make
standalone applications.

@item 
bpo-18802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18802}: Documentation changes for ipaddress.  Patch by Jon Foster and
Berker Peksag.

@item 
bpo-27428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27428}: Update documentation to clarify that @code{WindowsRegistryFinder}
implements @code{MetaPathFinder}. (Patch by Himanshu Lakhara)
@end itemize

@node Tests<51>,Build<54>,Documentation<50>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id494}@anchor{1a08}
@subsubsection Tests



@itemize -

@item 
bpo-32872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32872}: Avoid regrtest compatibility issue with namespace packages.

@item 
bpo-32517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32517}: Fix failing @code{test_asyncio} on macOS 10.12.2+ due to transport
of @code{KqueueSelector} loop was not being closed.

@item 
bpo-19417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19417}: Add test_bdb.py.
@end itemize

@node Build<54>,Windows<49>,Tests<51>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id495}@anchor{1a09}
@subsubsection Build



@itemize -

@item 
bpo-33163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33163}: Upgrade pip to 9.0.3 and setuptools to v39.0.1.
@end itemize

@node Windows<49>,macOS<40>,Build<54>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id496}@anchor{1a0a}
@subsubsection Windows



@itemize -

@item 
bpo-33016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33016}: Fix potential use of uninitialized memory in
nt._getfinalpathname

@item 
bpo-32903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32903}: Fix a memory leak in os.chdir() on Windows if the current
directory is set to a UNC path.
@end itemize

@node macOS<40>,IDLE<41>,Windows<49>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id497}@anchor{1a0b}
@subsubsection macOS



@itemize -

@item 
bpo-32726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32726}: Build and link with private copy of Tcl/Tk 8.6 for the macOS
10.6+ installer. The 10.9+ installer variant already does this.  This
means that the Python 3.7 provided by the python.org macOS installers no
longer need or use any external versions of Tcl/Tk, either system-provided
or user-installed, such as ActiveTcl.
@end itemize

@node IDLE<41>,Tools/Demos<27>,macOS<40>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id498}@anchor{1a0c}
@subsubsection IDLE



@itemize -

@item 
bpo-32984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32984}: Set @code{__file__} while running a startup file.  Like Python,
IDLE optionally runs one startup file in the Shell window before
presenting the first interactive input prompt.  For IDLE, @code{-s} runs a
file named in environmental variable  
@geindex IDLESTARTUP
@geindex variable d'environnement; IDLESTARTUP
@code{IDLESTARTUP} or
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP}; @code{-r file} runs @code{file}.  Python sets
@code{__file__} to the startup file name before running the file and unsets
it before the first prompt.  IDLE now does the same when run normally,
without the @code{-n} option.

@item 
bpo-32940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32940}: Simplify and rename StringTranslatePseudoMapping in pyparse.
@end itemize

@node Tools/Demos<27>,C API<51>,IDLE<41>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id499}@anchor{1a0d}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-32885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32885}: Add an @code{-n} flag for @code{Tools/scripts/pathfix.py} to disable
automatic backup creation (files with @code{~} suffix).
@end itemize

@node C API<51>,,Tools/Demos<27>,Python 3 7 0 beta 3
@anchor{whatsnew/changelog id500}@anchor{1a0e}
@subsubsection C API



@itemize -

@item 
bpo-33042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33042}: Embedding applications may once again call
PySys_ResetWarnOptions, PySys_AddWarnOption, and PySys_AddXOption prior to
calling Py_Initialize.

@item 
bpo-32374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32374}: Document that m_traverse for multi-phase initialized modules
can be called with m_state=NULL, and add a sanity check
@end itemize

@node Python 3 7 0 beta 2,Python 3 7 0 beta 1,Python 3 7 0 beta 3,Changelog
@anchor{whatsnew/changelog python-3-7-0-beta-2}@anchor{1a0f}
@subsection Python 3.7.0 beta 2


`Release date: 2018-02-27'

@menu
* Security: Security<37>. 
* Core and Builtins: Core and Builtins<57>. 
* Library: Library<57>. 
* Documentation: Documentation<51>. 
* Tests: Tests<52>. 
* Build: Build<55>. 
* Windows: Windows<50>. 
* macOS: macOS<41>. 
* IDLE: IDLE<42>. 
* Tools/Demos: Tools/Demos<28>. 

@end menu

@node Security<37>,Core and Builtins<57>,,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id501}@anchor{1a10}
@subsubsection Security



@itemize -

@item 
bpo-28414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28414}: The ssl module now allows users to perform their own IDN
en/decoding when using SNI.
@end itemize

@node Core and Builtins<57>,Library<57>,Security<37>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id502}@anchor{1a11}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-32889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32889}: Update Valgrind suppression list to account for the rename of
@code{Py_ADDRESS_IN_RANG} to @code{address_in_range}.

@item 
bpo-31356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31356}: Remove the new API added in bpo-31356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31356} (gc.ensure_disabled()
context manager).

@item 
bpo-32305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32305}: For namespace packages, ensure that both @code{__file__} and
@code{__spec__.origin} are set to None.

@item 
bpo-32303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32303}: Make sure @code{__spec__.loader} matches @code{__loader__} for
namespace packages.

@item 
bpo-32711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32711}: Fix the warning messages for Python/ast_unparse.c. Patch by
Stéphane Wirtel

@item 
bpo-32583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32583}: Fix possible crashing in builtin Unicode decoders caused by
write out-of-bound errors when using customized decode error handlers.
@end itemize

@node Library<57>,Documentation<51>,Core and Builtins<57>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id503}@anchor{1a12}
@subsubsection Library



@itemize -

@item 
bpo-32960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32960}: For dataclasses, disallow inheriting frozen from non-frozen
classes, and also disallow inheriting non-frozen from frozen classes. This
restriction will be relaxed at a future date.

@item 
bpo-32713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32713}: Fixed tarfile.itn handling of out-of-bounds float values. Patch
by Joffrey Fuhrer.

@item 
bpo-32951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32951}: Direct instantiation of SSLSocket and SSLObject objects is now
prohibited. The constructors were never documented, tested, or designed as
public constructors. Users were suppose to use ssl.wrap_socket() or
SSLContext.

@item 
bpo-32929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32929}: Remove the tri-state parameter "hash", and add the boolean
"unsafe_hash". If unsafe_hash is True, add a __hash__ function, but if a
__hash__ exists, raise TypeError.  If unsafe_hash is False, add a __hash__
based on the values of eq= and frozen=.  The unsafe_hash=False behavior is
the same as the old hash=None behavior.  unsafe_hash=False is the default,
just as hash=None used to be.

@item 
bpo-32947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32947}: Add OP_ENABLE_MIDDLEBOX_COMPAT and test workaround for TLSv1.3
for future compatibility with OpenSSL 1.1.1.

@item 
bpo-30622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30622}: The ssl module now detects missing NPN support in LibreSSL.

@item 
bpo-32922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32922}: dbm.open() now encodes filename with the filesystem encoding
rather than default encoding.

@item 
bpo-32859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32859}: In @code{os.dup2}, don't check every call whether the @code{dup3}
syscall exists or not.

@item 
bpo-32556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32556}: nt._getfinalpathname, nt._getvolumepathname and
nt._getdiskusage now correctly convert from bytes.

@item 
bpo-25988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25988}: Emit a @ref{1a3,,DeprecationWarning} when using or importing an ABC
directly from @ref{1d,,collections} rather than from @ref{1e,,collections.abc}.

@item 
bpo-21060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21060}: Rewrite confusing message from setup.py upload from "No dist
file created in earlier command" to the more helpful "Must create and
upload files in one command".

@item 
bpo-32852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32852}: Make sure sys.argv remains as a list when running trace.

@item 
bpo-31333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31333}: @code{_abc} module is added.  It is a speedup module with C
implementations for various functions and methods in @code{abc}.  Creating an
ABC subclass and calling @code{isinstance} or @code{issubclass} with an ABC
subclass are up to 1.5x faster. In addition, this makes Python start-up up
to 10% faster. Note that the new implementation hides internal registry
and caches, previously accessible via private attributes
@code{_abc_registry}, @code{_abc_cache}, and @code{_abc_negative_cache}.  There are
three debugging helper methods that can be used instead
@code{_dump_registry}, @code{_abc_registry_clear}, and @code{_abc_caches_clear}.

@item 
bpo-32841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32841}: Fixed @code{asyncio.Condition} issue which silently ignored
cancellation after notifying and cancelling a conditional lock. Patch by
Bar Harel.

@item 
bpo-32819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32819}: ssl.match_hostname() has been simplified and no longer depends
on re and ipaddress module for wildcard and IP addresses. Error reporting
for invalid wildcards has been improved.

@item 
bpo-32394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32394}: socket: Remove
TCP_FASTOPEN,TCP_KEEPCNT,TCP_KEEPIDLE,TCP_KEEPINTVL flags on older version
Windows during run-time.

@item 
bpo-31787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31787}: Fixed refleaks of @code{__init__()} methods in various modules.
(Contributed by Oren Milman)

@item 
bpo-30157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30157}: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when
only the last field is quoted.  Patch by Jake Davis.

@item 
bpo-32792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32792}: collections.ChainMap() preserves the order of the underlying
mappings.

@item 
bpo-32775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32775}: @ref{19d4,,fnmatch.translate()} no longer produces patterns which
contain set operations. Sets starting with '[' or containing '--', '&&',
'~~' or '||' will be interpreted differently in regular expressions in
future versions. Currently they emit warnings. fnmatch.translate() now
avoids producing patterns containing such sets by accident.

@item 
bpo-32622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32622}: Implement native fast sendfile for Windows proactor event loop.

@item 
bpo-32777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32777}: Fix a rare but potential pre-exec child process deadlock in
subprocess on POSIX systems when marking file descriptors inheritable on
exec in the child process.  This bug appears to have been introduced in
3.4.

@item 
bpo-32647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32647}: The ctypes module used to depend on indirect linking for
dlopen. The shared extension is now explicitly linked against libdl on
platforms with dl.

@item 
bpo-32741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32741}: Implement @code{asyncio.TimerHandle.when()} method.

@item 
bpo-32691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32691}: Use mod_spec.parent when running modules with pdb

@item 
bpo-32734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32734}: Fixed @code{asyncio.Lock()} safety issue which allowed acquiring
and locking the same lock multiple times, without it being free. Patch by
Bar Harel.

@item 
bpo-32727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32727}: Do not include name field in SMTP envelope from address. Patch
by Stéphane Wirtel

@item 
bpo-31453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31453}: Add TLSVersion constants and SSLContext.maximum_version /
minimum_version attributes. The new API wraps OpenSSL 1.1
@indicateurl{https://web.archive.org/web/20180309043602/https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_set_min_proto_version.html}
feature.

@item 
bpo-24334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24334}: Internal implementation details of ssl module were cleaned up.
The SSLSocket has one less layer of indirection. Owner and session
information are now handled by the SSLSocket and SSLObject constructor.
Channel binding implementation has been simplified.

@item 
bpo-31848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31848}: Fix the error handling in Aifc_read.initfp() when the SSND
chunk is not found. Patch by Zackery Spytz.

@item 
bpo-32585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32585}: Add Ttk spinbox widget to @ref{f8,,tkinter.ttk}.  Patch by Alan D
Moore.

@item 
bpo-32221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32221}: Various functions returning tuple containing IPv6 addresses now
omit @code{%scope} part since the same information is already encoded in
`scopeid' tuple item. Especially this speeds up @code{socket.recvfrom()}
when it receives multicast packet since useless resolving of network
interface name is omitted.

@item 
bpo-30693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30693}: The TarFile class now recurses directories in a reproducible
way.

@item 
bpo-30693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30693}: The ZipFile class now recurses directories in a reproducible
way.
@end itemize

@node Documentation<51>,Tests<52>,Library<57>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id504}@anchor{1a13}
@subsubsection Documentation



@itemize -

@item 
bpo-28124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28124}: The ssl module function ssl.wrap_socket() has been
de-emphasized and deprecated in favor of the more secure and efficient
SSLContext.wrap_socket() method.

@item 
bpo-17232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17232}: Clarify docs for -O and -OO.  Patch by Terry Reedy.

@item 
bpo-32436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32436}: Add documentation for the contextvars module (PEP 567).

@item 
bpo-32800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32800}: Update link to w3c doc for xml default namespaces.

@item 
bpo-11015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11015}: Update @ref{e3,,test.support} documentation.

@item 
bpo-8722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8722}: Document @code{__getattr__()} behavior when property @code{get()}
method raises @ref{343,,AttributeError}.

@item 
bpo-32614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32614}: Modify RE examples in documentation to use raw strings to
prevent @ref{1a3,,DeprecationWarning} and add text to REGEX HOWTO to highlight
the deprecation.

@item 
bpo-31972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31972}: Improve docstrings for @code{pathlib.PurePath} subclasses.
@end itemize

@node Tests<52>,Build<55>,Documentation<51>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id505}@anchor{1a14}
@subsubsection Tests



@itemize -

@item 
bpo-31809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31809}: Add tests to verify connection with secp ECDH curves.
@end itemize

@node Build<55>,Windows<50>,Tests<52>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id506}@anchor{1a15}
@subsubsection Build



@itemize -

@item 
bpo-32898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32898}: Fix the python debug build when using COUNT_ALLOCS.
@end itemize

@node Windows<50>,macOS<41>,Build<55>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id507}@anchor{1a16}
@subsubsection Windows



@itemize -

@item 
bpo-32901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32901}: Update Tcl and Tk versions to 8.6.8

@item 
bpo-31966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31966}: Fixed WindowsConsoleIO.write() for writing empty data.

@item 
bpo-32409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32409}: Ensures activate.bat can handle Unicode contents.

@item 
bpo-32457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32457}: Improves handling of denormalized executable path when
launching Python.

@item 
bpo-32370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32370}: Use the correct encoding for ipconfig output in the uuid
module. Patch by Segev Finer.

@item 
bpo-29248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29248}: Fix @ref{90d,,os.readlink()} on Windows, which was mistakenly
treating the @code{PrintNameOffset} field of the reparse data buffer as a
number of characters instead of bytes. Patch by Craig Holmquist and SSE4.
@end itemize

@node macOS<41>,IDLE<42>,Windows<50>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id508}@anchor{1a17}
@subsubsection macOS



@itemize -

@item 
bpo-32901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32901}: Update macOS 10.9+ installer to Tcl/Tk 8.6.8.
@end itemize

@node IDLE<42>,Tools/Demos<28>,macOS<41>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id509}@anchor{1a18}
@subsubsection IDLE



@itemize -

@item 
bpo-32916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32916}: Change @code{str} to @code{code} in pyparse.

@item 
bpo-32905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32905}: Remove unused code in pyparse module.

@item 
bpo-32874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32874}: Add tests for pyparse.

@item 
bpo-32837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32837}: Using the system and place-dependent default encoding for
open() is a bad idea for IDLE's system and location-independent files.

@item 
bpo-32826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32826}: Add "encoding=utf-8" to open() in IDLE's test_help_about. GUI
test test_file_buttons() only looks at initial ascii-only lines, but
failed on systems where open() defaults to 'ascii' because readline()
internally reads and decodes far enough ahead to encounter a non-ascii
character in CREDITS.txt.

@item 
bpo-32765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32765}: Update configdialog General tab docstring to add new widgets to
the widget list.
@end itemize

@node Tools/Demos<28>,,IDLE<42>,Python 3 7 0 beta 2
@anchor{whatsnew/changelog id510}@anchor{1a19}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-32222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32222}: Fix pygettext not extracting docstrings for functions with type
annotated arguments. Patch by Toby Harradine.
@end itemize

@node Python 3 7 0 beta 1,Python 3 7 0 alpha 4,Python 3 7 0 beta 2,Changelog
@anchor{whatsnew/changelog python-3-7-0-beta-1}@anchor{1a1a}
@subsection Python 3.7.0 beta 1


`Release date: 2018-01-30'

@menu
* Core and Builtins: Core and Builtins<58>. 
* Library: Library<58>. 
* Documentation: Documentation<52>. 
* Tests: Tests<53>. 
* Build: Build<56>. 
* Windows: Windows<51>. 
* macOS: macOS<42>. 
* C API: C API<52>. 

@end menu

@node Core and Builtins<58>,Library<58>,,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id511}@anchor{1a1b}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-32703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32703}: Fix coroutine's ResourceWarning when there's an active error
set when it's being finalized.

@item 
bpo-32650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32650}: Pdb and other debuggers dependent on bdb.py will correctly step
over (next command) native coroutines. Patch by Pablo Galindo.

@item 
bpo-28685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28685}: Optimize list.sort() and sorted() by using type specialized
comparisons when possible.

@item 
bpo-32685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32685}: Improve suggestion when the Python 2 form of print statement is
either present on the same line as the header of a compound statement or
else terminated by a semi-colon instead of a newline. Patch by Nitish
Chandra.

@item 
bpo-32697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32697}: Python now explicitly preserves the definition order of
keyword-only parameters.  It's always preserved their order, but this
behavior was never guaranteed before; this behavior is now guaranteed and
tested.

@item 
bpo-32690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32690}: The locals() dictionary now displays in the lexical order that
variables were defined.  Previously, the order was reversed.

@item 
bpo-32677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32677}: Add @code{.isascii()} method to @code{str}, @code{bytes} and
@code{bytearray}. It can be used to test that string contains only ASCII
characters.

@item 
bpo-32670@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32670}: Enforce 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} for all code. This means that manually
raising a StopIteration exception from a generator is prohibited for all
code, regardless of whether 'from __future__ import generator_stop' was
used or not.

@item 
bpo-32591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32591}: Added built-in support for tracking the origin of coroutine
objects; see sys.set_coroutine_origin_tracking_depth and
CoroutineType.cr_origin. This replaces the asyncio debug mode's use of
coroutine wrapping for native coroutine objects.

@item 
bpo-31368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31368}: Expose preadv and pwritev system calls in the os module. Patch
by Pablo Galindo

@item 
bpo-32544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32544}: @code{hasattr(obj, name)} and @code{getattr(obj, name, default)} are
about 4 times faster than before when @code{name} is not found and @code{obj}
doesn't override @code{__getattr__} or @code{__getattribute__}.

@item 
bpo-26163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26163}: Improved frozenset() hash to create more distinct hash values
when faced with datasets containing many similar values.

@item 
bpo-32550@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32550}: Remove the STORE_ANNOTATION bytecode.

@item 
bpo-20104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20104}: Expose posix_spawn as a low level API in the os module.
(removed before 3.7.0rc1)

@item 
bpo-24340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24340}: Fixed estimation of the code stack size.

@item 
bpo-32436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32436}: Implement 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} Context Variables.

@item 
bpo-18533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18533}: @code{repr()} on a dict containing its own @code{values()} or
@code{items()} no longer raises @code{RecursionError}; OrderedDict similarly.
Instead, use @code{...}, as for other recursive structures.  Patch by Ben
North.

@item 
bpo-20891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20891}: Py_Initialize() now creates the GIL. The GIL is no longer
created "on demand" to fix a race condition when PyGILState_Ensure() is
called in a non-Python thread.

@item 
bpo-32028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32028}: Leading whitespace is now correctly ignored when generating
suggestions for converting Py2 print statements to Py3 builtin print
function calls. Patch by Sanyam Khurana.

@item 
bpo-31179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31179}: Make dict.copy() up to 5.5 times faster.

@item 
bpo-31113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31113}: Get rid of recursion in the compiler for normal control flow.
@end itemize

@node Library<58>,Documentation<52>,Core and Builtins<58>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id512}@anchor{1a1c}
@subsubsection Library



@itemize -

@item 
bpo-25988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25988}: Deprecate exposing the contents of collections.abc in the
regular collections module.

@item 
bpo-31429@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31429}: The default cipher suite selection of the ssl module now uses a
blacklist approach rather than a hard-coded whitelist. Python no longer
re-enables ciphers that have been blocked by OpenSSL security update.
Default cipher suite selection can be configured on compile time.

@item 
bpo-30306@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30306}: contextlib.contextmanager now releases the arguments passed to
the underlying generator as soon as the context manager is entered.
Previously it would keep them alive for as long as the context manager was
alive, even when not being used as a function decorator. Patch by Martin
Teichmann.

@item 
bpo-21417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21417}: Added support for setting the compression level for
zipfile.ZipFile.

@item 
bpo-32251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32251}: Implement asyncio.BufferedProtocol (provisional API).

@item 
bpo-32513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32513}: In dataclasses, allow easier overriding of dunder methods
without specifying decorator parameters.

@item 
bpo-32660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32660}: @ref{e0,,termios} makes available @code{FIONREAD}, @code{FIONCLEX},
@code{FIOCLEX}, @code{FIOASYNC} and @code{FIONBIO} also under Solaris/derivatives.

@item 
bpo-27931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27931}: Fix email address header parsing error when the username is an
empty quoted string. Patch by Xiang Zhang.

@item 
bpo-32659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32659}: Under Solaris and derivatives, @ref{1475,,os.stat_result} provides
a st_fstype attribute.

@item 
bpo-32662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32662}: Implement Server.start_serving(), Server.serve_forever(), and
Server.is_serving() methods.  Add 'start_serving' keyword parameter to
loop.create_server() and loop.create_unix_server().

@item 
bpo-32391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32391}: Implement @ref{afa,,asyncio.StreamWriter.wait_closed()} and
@ref{afb,,asyncio.StreamWriter.is_closing()} methods

@item 
bpo-32643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32643}: Make Task._step, Task._wakeup and Future._schedule_callbacks
methods private.

@item 
bpo-32630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32630}: Refactor decimal module to use contextvars to store decimal
context.

@item 
bpo-32622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32622}: Add @code{asyncio.AbstractEventLoop.sendfile()} method.

@item 
bpo-32304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32304}: distutils' upload command no longer corrupts tar files ending
with a CR byte, and no longer tries to convert CR to CRLF in any of the
upload text fields.

@item 
bpo-32502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32502}: uuid.uuid1 no longer raises an exception if a 64-bit hardware
address is encountered.

@item 
bpo-32596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32596}: @code{concurrent.futures} imports @code{ThreadPoolExecutor} and
@code{ProcessPoolExecutor} lazily (using 
@geindex Python Enhancement Proposals; PEP 562
PEP 562@footnote{https://peps.python.org/pep-0562/}). It makes @code{import
asyncio} about 15% faster because asyncio uses only
@code{ThreadPoolExecutor} by default.

@item 
bpo-31801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31801}: Add @code{_ignore_} to @code{Enum} so temporary variables can be used
during class construction without being turned into members.

@item 
bpo-32576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32576}: Use queue.SimpleQueue() in places where it can be invoked from
a weakref callback.

@item 
bpo-32574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32574}: Fix memory leak in asyncio.Queue, when the queue has limited
size and it is full, the cancelation of queue.put() can cause a memory
leak. Patch by: José Melero.

@item 
bpo-32521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32521}: The nis module is now compatible with new libnsl and headers
location.

@item 
bpo-32467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32467}: collections.abc.ValuesView now inherits from
collections.abc.Collection.

@item 
bpo-32473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32473}: Improve ABCMeta._dump_registry() output readability

@item 
bpo-32102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32102}: New argument @code{capture_output} for subprocess.run

@item 
bpo-32521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32521}: glibc has removed Sun RPC. Use replacement libtirpc headers and
library in nis module.

@item 
bpo-32493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32493}: UUID module fixes build for FreeBSD/OpenBSD

@item 
bpo-32503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32503}: Pickling with protocol 4 no longer creates too small frames.

@item 
bpo-29237@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29237}: Create enum for pstats sorting options

@item 
bpo-32454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32454}: Add close(fd) function to the socket module.

@item 
bpo-25942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25942}: The subprocess module is now more graceful when handling a
Ctrl-C KeyboardInterrupt during subprocess.call, subprocess.run, or a
Popen context manager.  It now waits a short amount of time for the child
(presumed to have also gotten the SIGINT) to exit, before continuing the
KeyboardInterrupt exception handling.  This still includes a SIGKILL in
the call() and run() APIs, but at least the child had a chance first.

@item 
bpo-32433@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32433}: The hmac module now has hmac.digest(), which provides an
optimized HMAC digest.

@item 
bpo-28134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28134}: Sockets now auto-detect family, type and protocol from file
descriptor by default.

@item 
bpo-32404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32404}: Fix bug where @ref{4d7,,datetime.datetime.fromtimestamp()} did not
call __new__ in @ref{1c7,,datetime.datetime} subclasses.

@item 
bpo-32403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32403}: Improved speed of @ref{1c8,,datetime.date} and
@ref{1c7,,datetime.datetime} alternate constructors.

@item 
bpo-32228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32228}: Ensure that @code{truncate()} preserves the file position (as
reported by @code{tell()}) after writes longer than the buffer size.

@item 
bpo-32410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32410}: Implement @code{loop.sock_sendfile} for asyncio event loop.

@item 
bpo-22908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22908}: Added seek and tell to the ZipExtFile class. This only works if
the file object used to open the zipfile is seekable.

@item 
bpo-32373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32373}: Add socket.getblocking() method.

@item 
bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}: Add @ref{7a,,importlib.resources} and
@ref{aeb,,importlib.abc.ResourceReader} as the unified API for reading
resources contained within packages.  Loaders wishing to support resource
reading must implement the @code{get_resource_reader()} method.  File-based
and zipimport-based loaders both implement these APIs.
@ref{bd5,,importlib.abc.ResourceLoader} is deprecated in favor of these new
APIs.

@item 
bpo-32320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32320}: collections.namedtuple() now supports default values.

@item 
bpo-29302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29302}: Add contextlib.AsyncExitStack. Patch by Alexander Mohr and Ilya
Kulakov.

@item 
bpo-31961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31961}: `Removed in Python 3.7.0b2.' The `args' argument of
subprocess.Popen can now be a @ref{29d,,path-like object}. If `args' is given
as a sequence, it's first element can now be a @ref{29d,,path-like object} as
well.

@item 
bpo-31900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31900}: The @ref{bec,,locale.localeconv()} function now sets temporarily the
@code{LC_CTYPE} locale to the @code{LC_NUMERIC} locale to decode
@code{decimal_point} and @code{thousands_sep} byte strings if they are non-ASCII
or longer than 1 byte, and the @code{LC_NUMERIC} locale is different than the
@code{LC_CTYPE} locale. This temporary change affects other threads. Same
change for the @ref{60c,,str.format()} method when formatting a number
(@ref{254,,int}, @ref{2eb,,float}, @ref{2eb,,float} and subclasses) with the
@code{n} type (ex: @code{'@{:n@}'.format(1234)}).

@item 
bpo-31853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31853}: Use super().method instead of socket.method in SSLSocket.  They
were there most likely for legacy reasons.

@item 
bpo-31399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31399}: The ssl module now uses OpenSSL's X509_VERIFY_PARAM_set1_host()
and X509_VERIFY_PARAM_set1_ip() API to verify hostname and IP addresses.
Subject common name fallback can be disabled with
SSLContext.hostname_checks_common_name.

@item 
bpo-14976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14976}: Add a queue.SimpleQueue class, an unbounded FIFO queue with a
reentrant C implementation of put().
@end itemize

@node Documentation<52>,Tests<53>,Library<58>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id513}@anchor{1a1d}
@subsubsection Documentation



@itemize -

@item 
bpo-32724@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32724}: Add references to some commands in the documentation of Pdb.
Patch by Stéphane Wirtel

@item 
bpo-32649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32649}: Complete the C API documentation, profiling and tracing part
with the newly added per-opcode events.

@item 
bpo-17799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17799}: Explain real behaviour of sys.settrace and sys.setprofile and
their C-API counterparts regarding which type of events are received in
each function. Patch by Pablo Galindo Salgado.
@end itemize

@node Tests<53>,Build<56>,Documentation<52>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id514}@anchor{1a1e}
@subsubsection Tests



@itemize -

@item 
bpo-32721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32721}: Fix test_hashlib to not fail if the _md5 module is not built.

@item 
bpo-28414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28414}: Add test cases for IDNA 2003 and 2008 host names. IDNA 2003
internationalized host names are working since bpo-31399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31399} has landed. IDNA
2008 are still broken.

@item 
bpo-32604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32604}: Add a new "_xxsubinterpreters" extension module that exposes
the existing subinterpreter C-API and a new cross-interpreter data sharing
mechanism. The module is primarily intended for more thorough testing of
the existing subinterpreter support. Note that the _xxsubinterpreters
module has been removed in 3.7.0rc1.

@item 
bpo-32602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32602}: Add test certs and test for ECDSA cert and EC/RSA dual mode.

@item 
bpo-32549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32549}: On Travis CI, Python now Compiles and uses a local copy of
OpenSSL 1.1.0g for testing.
@end itemize

@node Build<56>,Windows<51>,Tests<53>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id515}@anchor{1a1f}
@subsubsection Build



@itemize -

@item 
bpo-32635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32635}: Fix segfault of the crypt module when libxcrypt is provided
instead of libcrypt at the system.

@item 
bpo-32598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32598}: Use autoconf to detect OpenSSL libs, headers and supported
features. The ax_check_openssl M4 macro uses pkg-config to locate OpenSSL
and falls back to manual search.

@item 
bpo-32593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32593}: Drop support of FreeBSD 9 and older.

@item 
bpo-29708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29708}: If the 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} environment variable is set,
@ref{b2,,py_compile} will always create hash-based @code{.pyc} files.
@end itemize

@node Windows<51>,macOS<42>,Build<56>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id516}@anchor{1a20}
@subsubsection Windows



@itemize -

@item 
bpo-32588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32588}: Create standalone _distutils_findvs module and add missing
_queue module to installer.

@item 
bpo-29911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29911}: Ensure separate Modify and Uninstall buttons are displayed.

@item 
bpo-32507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32507}: Use app-local UCRT install rather than the proper update for
old versions of Windows.
@end itemize

@node macOS<42>,C API<52>,Windows<51>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id517}@anchor{1a21}
@subsubsection macOS



@itemize -

@item 
bpo-32726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32726}: Provide an additional, more modern macOS installer variant that
supports macOS 10.9+ systems in 64-bit mode only.  Upgrade the supplied
third-party libraries to OpenSSL 1.1.0g and to SQLite 3.22.0.  The 10.9+
installer now links with and supplies its own copy of Tcl/Tk 8.6.

@item 
bpo-28440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28440}: No longer add /Library/Python/3.x/site-packages to sys.path for
macOS framework builds to avoid future conflicts.
@end itemize

@node C API<52>,,macOS<42>,Python 3 7 0 beta 1
@anchor{whatsnew/changelog id518}@anchor{1a22}
@subsubsection C API



@itemize -

@item 
bpo-32681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32681}: Fix uninitialized variable 'res' in the C implementation of
os.dup2. Patch by Stéphane Wirtel

@item 
bpo-10381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10381}: Add C API access to the @code{datetime.timezone} constructor and
@code{datetime.timzone.UTC} singleton.
@end itemize

@node Python 3 7 0 alpha 4,Python 3 7 0 alpha 3,Python 3 7 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-7-0-alpha-4}@anchor{1a23}
@subsection Python 3.7.0 alpha 4


`Release date: 2018-01-08'

@menu
* Core and Builtins: Core and Builtins<59>. 
* Library: Library<59>. 
* Documentation: Documentation<53>. 
* Tests: Tests<54>. 
* Windows: Windows<52>. 
* Tools/Demos: Tools/Demos<29>. 
* C API: C API<53>. 

@end menu

@node Core and Builtins<59>,Library<59>,,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id519}@anchor{1a24}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-31975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31975}: The default warning filter list now starts with a
"default::DeprecationWarning:__main__" entry, so deprecation warnings are
once again shown by default in single-file scripts and at the interactive
prompt.

@item 
bpo-32226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32226}: @code{__class_getitem__} is now an automatic class method.

@item 
bpo-32399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32399}: Add AIX uuid library support for RFC4122 using uuid_create() in
libc.a

@item 
bpo-32390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32390}: Fix the compilation failure on AIX after the f_fsid field has
been added to the object returned by os.statvfs() (bpo-32143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32143}). Original
patch by Michael Felt.

@item 
bpo-32379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32379}: Make MRO computation faster when a class inherits from a single
base.

@item 
bpo-32259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32259}: The error message of a TypeError raised when unpack
non-iterable is now more specific.

@item 
bpo-27169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27169}: The @code{__debug__} constant is now optimized out at compile
time. This fixes also bpo-22091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22091}.

@item 
bpo-32329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32329}: The @ref{1a25,,-R} option now turns on hash randomization when
the 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} environment variable is set to @code{0}.
Previously, the option was ignored. Moreover,
@code{sys.flags.hash_randomization} is now properly set to 0 when hash
randomization is turned off by @code{PYTHONHASHSEED=0}.

@item 
bpo-30416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30416}: The optimizer is now protected from spending much time doing
complex calculations and consuming much memory for creating large
constants in constant folding. Increased limits for constants that can be
produced in constant folding.

@item 
bpo-32282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32282}: Fix an unnecessary ifdef in the include of VersionHelpers.h in
socketmodule on Windows.

@item 
bpo-30579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30579}: Implement TracebackType.__new__ to allow Python-level creation
of traceback objects, and make TracebackType.tb_next mutable.

@item 
bpo-32260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32260}: Don't byte swap the input keys to the SipHash algorithm on
big-endian platforms. This should ensure siphash gives consistent results
across platforms.

@item 
bpo-31506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31506}: Improve the error message logic for object.__new__ and
object.__init__. Patch by Sanyam Khurana.

@item 
bpo-20361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20361}: @code{-b} and @code{-bb} now inject @code{'default::BytesWarning'} and
@code{error::BytesWarning} entries into @code{sys.warnoptions}, ensuring that
they take precedence over any other warning filters configured via the
@code{-W} option or the @code{PYTHONWARNINGS} environment variable.

@item 
bpo-32230@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32230}: @code{-X dev} now injects a @code{'default'} entry into
sys.warnoptions, ensuring that it behaves identically to actually passing
@code{-Wdefault} at the command line.

@item 
bpo-29240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29240}: Add a new UTF-8 mode: implementation of the 
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/}.

@item 
bpo-32226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32226}: 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}: Add support for @code{__mro_entries__} and
@code{__class_getitem__}. Implemented by Ivan Levkivskyi.

@item 
bpo-32225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32225}: 
@geindex Python Enhancement Proposals; PEP 562
PEP 562@footnote{https://peps.python.org/pep-0562/}: Add support for module @code{__getattr__} and
@code{__dir__}. Implemented by Ivan Levkivskyi.

@item 
bpo-31901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31901}: The @code{atexit} module now has its callback stored per
interpreter.

@item 
bpo-31650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31650}: Implement 
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} (Deterministic pycs). Python now supports
invalidating bytecode cache files bashed on a source content hash rather
than source last-modified time.

@item 
bpo-29469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29469}: Move constant folding from bytecode layer to AST layer.
Original patch by Eugene Toder.
@end itemize

@node Library<59>,Documentation<53>,Core and Builtins<59>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id520}@anchor{1a26}
@subsubsection Library



@itemize -

@item 
bpo-32506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32506}: Now that dict is defined as keeping insertion order, drop
OrderedDict and just use plain dict.

@item 
bpo-32279@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32279}: Add params to dataclasses.make_dataclasses(): init, repr, eq,
order, hash, and frozen.  Pass them through to dataclass().

@item 
bpo-32278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32278}: Make type information optional on dataclasses.make_dataclass().
If omitted, the string 'typing.Any' is used.

@item 
bpo-32499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32499}: Add dataclasses.is_dataclass(obj), which returns True if obj is
a dataclass or an instance of one.

@item 
bpo-32468@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32468}: Improve frame repr() to mention filename, code name and current
line number.

@item 
bpo-23749@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23749}: asyncio: Implement loop.start_tls()

@item 
bpo-32441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32441}: Return the new file descriptor (i.e., the second argument) from
@code{os.dup2}. Previously, @code{None} was always returned.

@item 
bpo-32422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32422}: @code{functools.lru_cache} uses less memory (3 words for each
cached key) and takes about 1/3 time for cyclic GC.

@item 
bpo-31721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31721}: Prevent Python crash from happening when Future._log_traceback
is set to True manually.  Now it can only be set to False, or a ValueError
is raised.

@item 
bpo-32415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32415}: asyncio: Add Task.get_loop() and Future.get_loop()

@item 
bpo-26133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26133}: Don't unsubscribe signals in asyncio UNIX event loop on
interpreter shutdown.

@item 
bpo-32363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32363}: Make asyncio.Task.set_exception() and set_result() raise
NotImplementedError. Task._step() and Future.__await__() raise proper
exceptions when they are in an invalid state, instead of raising an
AssertionError.

@item 
bpo-32357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32357}: Optimize asyncio.iscoroutine() and loop.create_task() for
non-native coroutines (e.g. async/await compiled with Cython).
'loop.create_task(python_coroutine)' used to be 20% faster than
'loop.create_task(cython_coroutine)'.  Now, the latter is as fast.

@item 
bpo-32356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32356}: asyncio.transport.resume_reading() and pause_reading() are now
idempotent. New transport.is_reading() method is added.

@item 
bpo-32355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32355}: Optimize asyncio.gather(); now up to 15% faster.

@item 
bpo-32351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32351}: Use fastpath in asyncio.sleep if delay<0 (2x boost)

@item 
bpo-32348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32348}: Optimize asyncio.Future schedule/add/remove callback.  The
optimization shows 3-6% performance improvements of async/await code.

@item 
bpo-32331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32331}: Fix socket.settimeout() and socket.setblocking() to keep
socket.type as is. Fix socket.socket() constructor to reset any bit flags
applied to socket's type.  This change only affects OSes that have
SOCK_NONBLOCK and/or SOCK_CLOEXEC.

@item 
bpo-32248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32248}: Add @ref{aeb,,importlib.abc.ResourceReader} as an ABC for loaders
to provide a unified API for reading resources contained within packages.
Also add @ref{7a,,importlib.resources} as the port of
@code{importlib_resources}.

@item 
bpo-32311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32311}: Implement asyncio.create_task(coro) shortcut

@item 
bpo-32327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32327}: Convert asyncio functions that were documented as coroutines to
coroutines. Affected functions: loop.sock_sendall, loop.sock_recv,
loop.sock_accept, loop.getaddrinfo, loop.getnameinfo.

@item 
bpo-32323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32323}: @ref{d2d,,urllib.parse.urlsplit()} does not convert zone-id (scope)
to lower case for scoped IPv6 addresses in hostnames now.

@item 
bpo-32302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32302}: Fix bdist_wininst of distutils for CRT v142: it binary
compatible with CRT v140.

@item 
bpo-29711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29711}: Fix @code{stop_serving} in asyncio proactor loop kill all
listening servers

@item 
bpo-32308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32308}: @ref{2a0,,re.sub()} now replaces empty matches adjacent to a
previous non-empty match.

@item 
bpo-29970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29970}: Abort asyncio SSLProtocol connection if handshake not complete
within 10 seconds.

@item 
bpo-32314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32314}: Implement asyncio.run().

@item 
bpo-17852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17852}: Revert incorrect fix based on misunderstanding of
_Py_PyAtExit() semantics.

@item 
bpo-32296@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32296}: Implement asyncio._get_running_loop() and get_event_loop() in
C. This makes them 4x faster.

@item 
bpo-32250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32250}: Implement @code{asyncio.current_task()} and
@code{asyncio.all_tasks()}. Add helpers intended to be used by alternative
task implementations: @code{asyncio._register_task}, @code{asyncio._enter_task},
@code{asyncio._leave_task} and @code{asyncio._unregister_task}. Deprecate
@code{asyncio.Task.current_task()} and @code{asyncio.Task.all_tasks()}.

@item 
bpo-32255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32255}: A single empty field is now always quoted when written into a
CSV file. This allows to distinguish an empty row from a row consisting of
a single empty field. Patch by Licht Takeuchi.

@item 
bpo-32277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32277}: Raise @code{NotImplementedError} instead of @code{SystemError} on
platforms where @code{chmod(..., follow_symlinks=False)} is not supported.
Patch by Anthony Sottile.

@item 
bpo-30050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30050}: New argument warn_on_full_buffer to signal.set_wakeup_fd lets
you control whether Python prints a warning on stderr when the wakeup fd
buffer overflows.

@item 
bpo-29137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29137}: The @code{fpectl} library has been removed. It was never enabled
by default, never worked correctly on x86-64, and it changed the Python
ABI in ways that caused unexpected breakage of C extensions.

@item 
bpo-32273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32273}: Move asyncio.test_utils to test.test_asyncio.

@item 
bpo-32272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32272}: Remove asyncio.async() function.

@item 
bpo-32269@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32269}: Add asyncio.get_running_loop() function.

@item 
bpo-32265@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32265}: All class and static methods of builtin types now are correctly
classified by inspect.classify_class_attrs() and grouped in pydoc ouput.
Added types.ClassMethodDescriptorType for unbound class methods of builtin
types.

@item 
bpo-32253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32253}: Deprecate @code{yield from lock}, @code{await lock}, @code{with (yield
from lock)} and @code{with await lock} for asyncio synchronization
primitives.

@item 
bpo-22589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22589}: Changed MIME type of .bmp from 'image/x-ms-bmp' to 'image/bmp'

@item 
bpo-32193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32193}: Convert asyncio to use `async/await' syntax. Old styled @code{yield
from} is still supported too.

@item 
bpo-32206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32206}: Add support to run modules with pdb

@item 
bpo-32227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32227}: @code{functools.singledispatch} now supports registering
implementations using type annotations.

@item 
bpo-15873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15873}: Added new alternate constructors
@ref{602,,datetime.datetime.fromisoformat()},
@ref{601,,datetime.time.fromisoformat()} and
@ref{600,,datetime.date.fromisoformat()} as the inverse operation of each
classes's respective @code{isoformat} methods.

@item 
bpo-32199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32199}: The getnode() ip getter now uses 'ip link' instead of 'ip link
list'.

@item 
bpo-32143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32143}: os.statvfs() includes the f_fsid field from statvfs(2)

@item 
bpo-26439@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26439}: Fix ctypes.util.find_library() for AIX by implementing
ctypes._aix.find_library() Patch by: Michael Felt

@item 
bpo-31993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31993}: The pickler now uses less memory when serializing large bytes
and str objects into a file.  Pickles created with protocol 4 will require
less memory for unpickling large bytes and str objects.

@item 
bpo-27456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27456}: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

@item 
bpo-31778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31778}: ast.literal_eval() is now more strict. Addition and subtraction
of arbitrary numbers no longer allowed.

@item 
bpo-31802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31802}: Importing native path module (@code{posixpath}, @code{ntpath}) now
works even if the @code{os} module still is not imported.

@item 
bpo-30241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30241}: Add contextlib.AbstractAsyncContextManager. Patch by Jelle
Zijlstra.

@item 
bpo-31699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31699}: Fix deadlocks in
@ref{8db,,concurrent.futures.ProcessPoolExecutor} when task arguments or
results cause pickling or unpickling errors. This should make sure that
calls to the @code{ProcessPoolExecutor} API always eventually return.

@item 
bpo-15216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15216}: @code{TextIOWrapper.reconfigure()} supports changing `encoding',
`errors', and `newline'.
@end itemize

@node Documentation<53>,Tests<54>,Library<59>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id521}@anchor{1a27}
@subsubsection Documentation



@itemize -

@item 
bpo-32418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32418}: Add get_loop() method to Server and AbstractServer classes.
@end itemize

@node Tests<54>,Windows<52>,Documentation<53>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id522}@anchor{1a28}
@subsubsection Tests



@itemize -

@item 
bpo-32252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32252}: Fix faulthandler_suppress_crash_report() used to prevent core
dump files when testing crashes. getrlimit() returns zero on success.

@item 
bpo-32002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32002}: Adjust C locale coercion testing for the empty locale and POSIX
locale cases to more readily adjust to platform dependent behaviour.
@end itemize

@node Windows<52>,Tools/Demos<29>,Tests<54>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id523}@anchor{1a29}
@subsubsection Windows



@itemize -

@item 
bpo-19764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19764}: Implement support for @code{subprocess.Popen(close_fds=True)} on
Windows. Patch by Segev Finer.
@end itemize

@node Tools/Demos<29>,C API<53>,Windows<52>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id524}@anchor{1a2a}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-24960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24960}: 2to3 and lib2to3 can now read pickled grammar files using
pkgutil.get_data() rather than probing the filesystem. This lets 2to3 and
lib2to3 work when run from a zipfile.
@end itemize

@node C API<53>,,Tools/Demos<29>,Python 3 7 0 alpha 4
@anchor{whatsnew/changelog id525}@anchor{1a2b}
@subsubsection C API



@itemize -

@item 
bpo-32030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32030}: Py_Initialize() doesn't reset the memory allocators to default
if the @code{PYTHONMALLOC} environment variable is not set.

@item 
bpo-29084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29084}: Undocumented C API for OrderedDict has been excluded from the
limited C API. It was added by mistake and actually never worked in the
limited C API.

@item 
bpo-32264@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32264}: Moved the pygetopt.h header into internal/, since it has no
public APIs.

@item 
bpo-32241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32241}: @code{Py_SetProgramName()} and @code{Py_SetPythonHome()}
now take the @code{const wchar *} arguments instead of @code{wchar *}.
@end itemize

@node Python 3 7 0 alpha 3,Python 3 7 0 alpha 2,Python 3 7 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-7-0-alpha-3}@anchor{1a2c}
@subsection Python 3.7.0 alpha 3


`Release date: 2017-12-05'

@menu
* Core and Builtins: Core and Builtins<60>. 
* Library: Library<60>. 
* Documentation: Documentation<54>. 
* Tests: Tests<55>. 
* Build: Build<57>. 
* Windows: Windows<53>. 
* macOS: macOS<43>. 
* IDLE: IDLE<43>. 
* Tools/Demos: Tools/Demos<30>. 
* C API: C API<54>. 

@end menu

@node Core and Builtins<60>,Library<60>,,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id526}@anchor{1a2d}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-32176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32176}: co_flags.CO_NOFREE is now always set correctly by the code
object constructor based on freevars and cellvars, rather than needing to
be set correctly by the caller. This ensures it will be cleared
automatically when additional cell references are injected into a modified
code object and function.

@item 
bpo-10544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10544}: Yield expressions are now deprecated in comprehensions and
generator expressions. They are still permitted in the definition of the
outermost iterable, as that is evaluated directly in the enclosing scope.

@item 
bpo-32137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32137}: The repr of deeply nested dict now raises a RecursionError
instead of crashing due to a stack overflow.

@item 
bpo-32096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32096}: Revert memory allocator changes in the C API: move structures
back from _PyRuntime to Objects/obmalloc.c. The memory allocators are once
again initialized statically, and so PyMem_RawMalloc() and
Py_DecodeLocale() can be called before _PyRuntime_Initialize().

@item 
bpo-32043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32043}: Add a new "developer mode": new "-X dev" command line option to
enable debug checks at runtime.

@item 
bpo-32023@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32023}: SyntaxError is now correctly raised when a generator expression
without parenthesis is used instead of an inheritance list in a class
definition. The duplication of the parentheses can be omitted only on
calls.

@item 
bpo-32012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32012}: SyntaxError is now correctly raised when a generator expression
without parenthesis is passed as an argument, but followed by a trailing
comma. A generator expression always needs to be directly inside a set of
parentheses and cannot have a comma on either side.

@item 
bpo-28180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28180}: A new internal @code{_Py_SetLocaleFromEnv(category)} helper
function has been added in order to improve the consistency of behaviour
across different @code{libc} implementations (e.g. Android doesn't support
setting the locale from the environment by default).

@item 
bpo-31949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31949}: Fixed several issues in printing tracebacks
(PyTraceBack_Print()). Setting sys.tracebacklimit to 0 or less now
suppresses printing tracebacks. Setting sys.tracebacklimit to None now
causes using the default limit. Setting sys.tracebacklimit to an integer
larger than LONG_MAX now means using the limit LONG_MAX rather than the
default limit. Fixed integer overflows in the case of more than @code{2**31}
traceback items on Windows. Fixed output errors handling.

@item 
bpo-30696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30696}: Fix the interactive interpreter looping endlessly when no
memory.

@item 
bpo-20047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20047}: Bytearray methods partition() and rpartition() now accept only
bytes-like objects as separator, as documented.  In particular they now
raise TypeError rather of returning a bogus result when an integer is
passed as a separator.

@item 
bpo-21720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21720}: BytesWarning no longer emitted when the `fromlist' argument of
@code{__import__()} or the @code{__all__} attribute of the module contain bytes
instances.

@item 
bpo-31845@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31845}: Environment variables are once more read correctly at
interpreter startup.

@item 
bpo-28936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28936}: Ensure that lexically first syntax error involving a parameter
and @code{global} or @code{nonlocal} is detected first at a given scope. Patch
by Ivan Levkivskyi.

@item 
bpo-31825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31825}: Fixed OverflowError in the 'unicode-escape' codec and in
codecs.escape_decode() when decode an escaped non-ascii byte.

@item 
bpo-31618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31618}: The per-frame tracing logic added in 3.7a1 has been altered so
that @code{frame->f_lineno} is updated before either @code{"line"} or
@code{"opcode"} events are emitted. Previously, opcode events were emitted
first, and therefore would occasionally see stale line numbers on the
frame. The behavior of this feature has changed slightly as a result: when
both @code{f_trace_lines} and @code{f_trace_opcodes} are enabled, line events
now occur first.

@item 
bpo-28603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28603}: Print the full context/cause chain of exceptions on interpreter
exit, even if an exception in the chain is unhashable or compares equal to
later ones. Patch by Zane Bitter.

@item 
bpo-31786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31786}: Fix timeout rounding in the select module to round correctly
negative timeouts between -1.0 and 0.0. The functions now block waiting
for events as expected. Previously, the call was incorrectly non-blocking.
Patch by Pablo Galindo.

@item 
bpo-31781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31781}: Prevent crashes when calling methods of an uninitialized
@code{zipimport.zipimporter} object. Patch by Oren Milman.

@item 
bpo-30399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30399}: Standard repr() of BaseException with a single argument no
longer contains redundant trailing comma.

@item 
bpo-31626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31626}: Fixed a bug in debug memory allocator.  There was a write to
freed memory after shrinking a memory block.

@item 
bpo-30817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30817}: @code{PyErr_PrintEx()} clears now the ignored exception that may
be raised by @code{_PySys_SetObjectId()}, for example when no memory.
@end itemize

@node Library<60>,Documentation<54>,Core and Builtins<60>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id527}@anchor{1a2e}
@subsubsection Library



@itemize -

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Two minor fixes for @code{typing} module: allow shallow copying
instances of generic classes, improve interaction of @code{__init_subclass__}
with generics. Original PRs by Ivan Levkivskyi.

@item 
bpo-32214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32214}: PEP 557, Data Classes. Provides a decorator which adds
boilerplate methods to classes which use type annotations so specify
fields.

@item 
bpo-27240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27240}: The header folding algorithm for the new email policies has
been rewritten, which also fixes bpo-30788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30788}, bpo-31831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31831}, and bpo-32182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32182}.  In
particular, RFC2231 folding is now done correctly.

@item 
bpo-32186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32186}: io.FileIO.readall() and io.FileIO.read() now release the GIL
when getting the file size. Fixed hang of all threads with inaccessible
NFS server. Patch by Nir Soffer.

@item 
bpo-32101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32101}: Add @ref{1a2f,,sys.flags.dev_mode} flag

@item 
bpo-32154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32154}: The @code{asyncio.windows_utils.socketpair()} function has been
removed: use directly @ref{be3,,socket.socketpair()} which is available on all
platforms since Python 3.5 (before, it wasn't available on Windows).
@code{asyncio.windows_utils.socketpair()} was just an alias to
@code{socket.socketpair} on Python 3.5 and newer.

@item 
bpo-32089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32089}: warnings: In development (-X dev) and debug mode (pydebug
build), use the "default" action for ResourceWarning, rather than the
"always" action, in the default warnings filters.

@item 
bpo-32107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32107}: @code{uuid.getnode()} now preferentially returns universally
administered MAC addresses if available, over locally administered MAC
addresses.  This makes a better guarantee for global uniqueness of UUIDs
returned from @code{uuid.uuid1()}.  If only locally administered MAC
addresses are available, the first such one found is returned.

@item 
bpo-23033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23033}: Wildcard is now supported in hostname when it is one and only
character in the left most segment of hostname in second argument of
@code{ssl.match_hostname()}.  Patch by Mandeep Singh.

@item 
bpo-12239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12239}: Make @code{msilib.SummaryInformation.GetProperty()} return
@code{None} when the value of property is @code{VT_EMPTY}.  Initial patch by
Mark Mc Mahon.

@item 
bpo-28334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28334}: Use @ref{a02,,os.path.expanduser()} to find the @code{~/.netrc} file in
@ref{184f,,netrc.netrc}.  If it does not exist, @ref{eae,,FileNotFoundError} is
raised.  Patch by Dimitri Merejkowsky.

@item 
bpo-32121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32121}: Made @code{tracemalloc.Traceback} behave more like the traceback
module, sorting the frames from oldest to most recent.
@code{Traceback.format()} now accepts negative `limit', truncating the result
to the @code{abs(limit)} oldest frames. To get the old behaviour, one can use
the new `most_recent_first' argument to @code{Traceback.format()}. (Patch by
Jesse Bakker.)

@item 
bpo-31325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31325}: Fix wrong usage of @ref{1c5,,collections.namedtuple()} in the
@ref{1a30,,RobotFileParser.parse()}
method. Initial patch by Robin Wellner.

@item 
bpo-12382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12382}: @code{msilib.OpenDatabase()} now raises a better exception
message when it couldn't open or create an MSI file.  Initial patch by
William Tisäter.

@item 
bpo-19610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19610}: @code{setup()} now warns about invalid types for some fields. The
@code{distutils.dist.Distribution} class now warns when @code{classifiers},
@code{keywords} and @code{platforms} fields are not specified as a list or a
string.

@item 
bpo-32071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32071}: Added the @code{-k} command-line option to @code{python -m unittest}
to run only tests that match the given pattern(s).

@item 
bpo-10049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10049}: Added `nullcontext' no-op context manager to contextlib. This
provides a simpler and faster alternative to ExitStack() when handling
optional context managers.

@item 
bpo-28684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28684}: The new test.support.skip_unless_bind_unix_socket() decorator
is used here to skip asyncio tests that fail because the platform lacks a
functional bind() function for unix domain sockets (as it is the case for
non root users on the recent Android versions that run now SELinux in
enforcing mode).

@item 
bpo-32110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32110}: @code{codecs.StreamReader.read(n)} now returns not more than `n'
characters/bytes for non-negative `n'. This makes it compatible with
@code{read()} methods of other file-like objects.

@item 
bpo-27535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27535}: The warnings module doesn't leak memory anymore in the hidden
warnings registry for the "ignore" action of warnings filters.
warn_explicit() function doesn't add the warning key to the registry
anymore for the "ignore" action.

@item 
bpo-32088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32088}: warnings:  When Python is build is debug mode (@code{Py_DEBUG}),
@ref{1a3,,DeprecationWarning}, @ref{8b5,,PendingDeprecationWarning} and
@ref{4e4,,ImportWarning} warnings are now displayed by default.

@item 
bpo-1647489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1647489}: Fixed searching regular expression patterns that could match
an empty string. Non-empty string can now be correctly found after
matching an empty string.

@item 
bpo-25054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25054}: Added support of splitting on a pattern that could match an
empty string.

@item 
bpo-32072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32072}: Fixed issues with binary plists: Fixed saving bytearrays.
Identical objects will be saved only once. Equal references will be load
as identical objects. Added support for saving and loading recursive data
structures.

@item 
bpo-32069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32069}: Drop legacy SSL transport from asyncio, ssl.MemoryBIO is always
used anyway.

@item 
bpo-32066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32066}: asyncio: Support pathlib.Path in create_unix_connection; sock
arg should be optional

@item 
bpo-32046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32046}: Updates 2to3 to convert from operator.isCallable(obj) to
callable(obj). Patch by Donghee Na.

@item 
bpo-32018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32018}: inspect.signature should follow 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}, if the parameter has
an annotation and a default value. Patch by Donghee Na.

@item 
bpo-32025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32025}: Add time.thread_time() and time.thread_time_ns()

@item 
bpo-32037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32037}: Integers that fit in a signed 32-bit integer will be now
pickled with protocol 0 using the INT opcode.  This will decrease the size
of a pickle, speed up pickling and unpickling, and make these integers be
unpickled as int instances in Python 2.

@item 
bpo-32034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32034}: Make asyncio.IncompleteReadError and LimitOverrunError
pickleable.

@item 
bpo-32015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32015}: Fixed the looping of asyncio in the case of reconnection the
socket during waiting async read/write from/to the socket.

@item 
bpo-32011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32011}: Restored support of loading marshal files with the TYPE_INT64
code. These files can be produced in Python 2.7.

@item 
bpo-28369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28369}: Enhance add_reader/writer check that socket is not used by some
transport. Before, only cases when add_reader/writer were called with an
int FD were supported.  Now the check is implemented correctly for all
file-like objects.

@item 
bpo-31976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31976}: Fix race condition when flushing a file is slow, which can
cause a segfault if closing the file from another thread.

@item 
bpo-31985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31985}: Formally deprecated aifc.openfp, sunau.openfp, and wave.openfp.
Since change 7bc817d5ba917528e8bd07ec461c635291e7b06a in 1993, openfp in
each of the three modules had been pointing to that module's open function
as a matter of backwards compatibility, though it had been both untested
and undocumented.

@item 
bpo-21862@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21862}: cProfile command line now accepts @code{-m module_name} as an
alternative to script path. Patch by Sanyam Khurana.

@item 
bpo-31970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31970}: Reduce performance overhead of asyncio debug mode.

@item 
bpo-31843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31843}: `database' argument of sqlite3.connect() now accepts a
@ref{29d,,path-like object}, instead of just a string.

@item 
bpo-31945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31945}: Add Configurable `blocksize' to @code{HTTPConnection} and
@code{HTTPSConnection} for improved upload throughput.  Patch by Nir Soffer.

@item 
bpo-31943@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31943}: Add a @code{cancelled()} method to @ref{1a31,,asyncio.Handle}.  Patch
by Marat Sharafutdinov.

@item 
bpo-9678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9678}: Fixed determining the MAC address in the uuid module: Using
ifconfig on NetBSD and OpenBSD. Using arp on Linux, FreeBSD, NetBSD and
OpenBSD. Based on patch by Takayuki Shimizukawa.

@item 
bpo-30057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30057}: Fix potential missed signal in signal.signal().

@item 
bpo-31933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31933}: Fix Blake2 params leaf_size and node_offset on big endian
platforms. Patch by Jack O'Connor.

@item 
bpo-21423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21423}: Add an initializer argument to @{Process,Thread@}PoolExecutor

@item 
bpo-31927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31927}: Fixed compilation of the socket module on NetBSD 8.  Fixed
assertion failure or reading arbitrary data when parse a AF_BLUETOOTH
address on NetBSD and DragonFly BSD.

@item 
bpo-27666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27666}: Fixed stack corruption in curses.box() and curses.ungetmouse()
when the size of types chtype or mmask_t is less than the size of C long.
curses.box() now accepts characters as arguments.  Based on patch by Steve
Fink.

@item 
bpo-31917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31917}: Add 3 new clock identifiers: @ref{b7c,,time.CLOCK_BOOTTIME},
@ref{b7d,,time.CLOCK_PROF} and @ref{b7e,,time.CLOCK_UPTIME}.

@item 
bpo-31897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31897}: plistlib now catches more errors when read binary plists and
raises InvalidFileException instead of unexpected exceptions.

@item 
bpo-25720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25720}: Fix the method for checking pad state of curses WINDOW. Patch
by Masayuki Yamamoto.

@item 
bpo-31893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31893}: Fixed the layout of the kqueue_event structure on OpenBSD and
NetBSD. Fixed the comparison of the kqueue_event objects.

@item 
bpo-31891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31891}: Fixed building the curses module on NetBSD.

@item 
bpo-31884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31884}: added required constants to subprocess module for setting
priority on windows

@item 
bpo-28281@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28281}: Remove year (1-9999) limits on the Calendar.weekday() function.
Patch by Mark Gollahon.

@item 
bpo-31702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31702}: crypt.mksalt() now allows to specify the number of rounds for
SHA-256 and SHA-512 hashing.

@item 
bpo-30639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30639}: @ref{1a32,,inspect.getfile()} no longer computes the repr of unknown
objects to display in an error message, to protect against badly behaved
custom reprs.

@item 
bpo-30768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30768}: Fix the pthread+semaphore implementation of
PyThread_acquire_lock_timed() when called with timeout > 0 and
intr_flag=0: recompute the timeout if sem_timedwait() is interrupted by a
signal (EINTR). See also the 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}.

@item 
bpo-31854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31854}: Add @code{mmap.ACCESS_DEFAULT} constant.

@item 
bpo-31834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31834}: Use optimized code for BLAKE2 only with SSSE3+. The pure SSE2
implementation is slower than the pure C reference implementation.

@item 
bpo-28292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28292}: Calendar.itermonthdates() will now consistently raise an
exception when a date falls outside of the 0001-01-01 through 9999-12-31
range.  To support applications that cannot tolerate such exceptions, the
new methods itermonthdays3() and itermonthdays4() are added.  The new
methods return tuples and are not restricted by the range supported by
datetime.date.

@item 
bpo-28564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28564}: The shutil.rmtree() function has been sped up to 20--40%. This
was done using the os.scandir() function.

@item 
bpo-28416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28416}: Instances of pickle.Pickler subclass with the persistent_id()
method and pickle.Unpickler subclass with the persistent_load() method no
longer create reference cycles.

@item 
bpo-31653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31653}: Don't release the GIL if we can acquire a multiprocessing
semaphore immediately.

@item 
bpo-28326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28326}: Fix multiprocessing.Process when stdout and/or stderr is closed
or None.

@item 
bpo-20825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20825}: Add @code{subnet_of} and @code{superset_of} containment tests to
@ref{1fc,,ipaddress.IPv6Network} and @ref{1fb,,ipaddress.IPv4Network}. Patch
by Michel Albert and Cheryl Sabella.

@item 
bpo-31827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31827}: Remove the os.stat_float_times() function. It was introduced in
Python 2.3 for backward compatibility with Python 2.2, and was deprecated
since Python 3.1.

@item 
bpo-31756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31756}: Add a @code{subprocess.Popen(text=False)} keyword argument to
@code{subprocess} functions to be more explicit about when the library should
attempt to decode outputs into text. Patch by Andrew Clegg.

@item 
bpo-31819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31819}: Add AbstractEventLoop.sock_recv_into().

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: If nested log adapters are used, the inner @code{process()}
methods are no longer omitted.

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: The @code{manager} property on LoggerAdapter objects is now
properly settable.

@item 
bpo-31806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31806}: Fix timeout rounding in time.sleep(), threading.Lock.acquire()
and socket.socket.settimeout() to round correctly negative timeouts
between -1.0 and 0.0. The functions now block waiting for events as
expected. Previously, the call was incorrectly non-blocking. Patch by
Pablo Galindo.

@item 
bpo-31803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31803}: time.clock() and time.get_clock_info('clock') now emit a
DeprecationWarning warning.

@item 
bpo-31800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31800}: Extended support for parsing UTC offsets. strptime '%z' can now
parse the output generated by datetime.isoformat, including seconds and
microseconds.

@item 
bpo-28603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28603}: traceback: Fix a TypeError that occurred during printing of
exception tracebacks when either the current exception or an exception in
its context/cause chain is unhashable. Patch by Zane Bitter.

@item 
bpo-30541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30541}: Add new function to seal a mock and prevent the automatically
creation of child mocks. Patch by Mario Corchero.

@item 
bpo-31784@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31784}: Implement the 
@geindex Python Enhancement Proposals; PEP 564
PEP 564@footnote{https://peps.python.org/pep-0564/}, add new 6 new functions with
nanosecond resolution to the @ref{ed,,time} module:
@ref{ad0,,clock_gettime_ns()}, @ref{ad1,,clock_settime_ns()},
@ref{ad2,,monotonic_ns()}, @ref{ad3,,perf_counter_ns()},
@ref{ad4,,process_time_ns()}, @ref{ad5,,time_ns()}.

@item 
bpo-30143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30143}: 2to3 now generates a code that uses abstract collection classes
from collections.abc rather than collections.

@item 
bpo-31770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31770}: Prevent a crash when calling the @code{__init__()} method of a
@code{sqlite3.Cursor} object more than once. Patch by Oren Milman.

@item 
bpo-31764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31764}: Prevent a crash in @code{sqlite3.Cursor.close()} in case the
@code{Cursor} object is uninitialized. Patch by Oren Milman.

@item 
bpo-31752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31752}: Fix possible crash in timedelta constructor called with custom
integers.

@item 
bpo-31620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31620}: an empty asyncio.Queue now doesn't leak memory when queue.get
pollers timeout

@item 
bpo-31690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31690}: Allow the flags re.ASCII, re.LOCALE, and re.UNICODE to be used
as group flags for regular expressions.

@item 
bpo-30349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30349}: FutureWarning is now emitted if a regular expression contains
character set constructs that will change semantically in the future
(nested sets and set operations).

@item 
bpo-31664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31664}: Added support for the Blowfish hashing in the crypt module.

@item 
bpo-31632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31632}: Fix method set_protocol() of class _SSLProtocolTransport in
asyncio module. This method was previously modifying a wrong reference to
the protocol.

@item 
bpo-15037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15037}: Added a workaround for getkey() in curses for ncurses 5.7 and
earlier.

@item 
bpo-31307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31307}: Allow use of bytes objects for arguments to
@ref{141c,,configparser.ConfigParser.read()}. Patch by Vincent Michel.

@item 
bpo-31334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31334}: Fix @code{poll.poll([timeout])} in the @code{select} module for
arbitrary negative timeouts on all OSes where it can only be a
non-negative integer or -1. Patch by Riccardo Coccioli.

@item 
bpo-31310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31310}: multiprocessing's semaphore tracker should be launched again if
crashed.

@item 
bpo-31308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31308}: Make multiprocessing's forkserver process immune to Ctrl-C and
other user interruptions. If it crashes, restart it when necessary.

@item 
bpo-31245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31245}: Added support for AF_UNIX socket in asyncio
@code{create_datagram_endpoint}.

@item 
bpo-30553@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30553}: Add HTTP/2 status code 421 (Misdirected Request) to
@ref{8ed,,http.HTTPStatus}. Patch by Vitor Pereira.
@end itemize

@node Documentation<54>,Tests<55>,Library<60>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id528}@anchor{1a33}
@subsubsection Documentation



@itemize -

@item 
bpo-32105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32105}: Added asyncio.BaseEventLoop.connect_accepted_socket
versionadded marker.
@end itemize

@node Tests<55>,Build<57>,Documentation<54>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id529}@anchor{1a34}
@subsubsection Tests



@itemize -

@item 
bpo-31380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31380}: Skip test_httpservers test_undecodable_file on macOS: fails on
APFS.

@item 
bpo-31705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31705}: Skip test_socket.test_sha256() on Linux kernel older than 4.5.
The test fails with ENOKEY on kernel 3.10 (on ppc64le). A fix was merged
into the kernel 4.5.

@item 
bpo-32138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32138}: Skip on Android test_faulthandler tests that raise SIGSEGV and
remove the test.support.requires_android_level decorator.

@item 
bpo-32136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32136}: The runtime embedding tests have been split out from
@code{Lib/test/test_capi.py} into a new @code{Lib/test/test_embed.py} file.

@item 
bpo-28668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28668}: test.support.requires_multiprocessing_queue is removed. Skip
tests with test.support.import_module('multiprocessing.synchronize')
instead when the semaphore implementation is broken or missing.

@item 
bpo-32126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32126}: Skip test_get_event_loop_new_process in
test.test_asyncio.test_events when sem_open() is not functional.

@item 
bpo-31174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31174}: Fix test_tools.test_unparse: DirectoryTestCase now stores the
names sample to always test the same files. It prevents false alarms when
hunting reference leaks.
@end itemize

@node Build<57>,Windows<53>,Tests<55>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id530}@anchor{1a35}
@subsubsection Build



@itemize -

@item 
bpo-28538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28538}: Revert the previous changes, the if_nameindex structure is
defined by Unified Headers.

@item 
bpo-28762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28762}: Revert the last commit, the F_LOCK macro is defined by Android
Unified Headers.

@item 
bpo-29040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29040}: Support building Android with Unified Headers. The first NDK
release to support Unified Headers is android-ndk-r14.

@item 
bpo-32059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32059}: @code{detect_modules()} in @code{setup.py} now also searches the
sysroot paths when cross-compiling.

@item 
bpo-31957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31957}: Fixes Windows SDK version detection when building for Windows.

@item 
bpo-31609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31609}: Fixes quotes in PCbuild/clean.bat

@item 
bpo-31934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31934}: Abort the build when building out of a not clean source tree.

@item 
bpo-31926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31926}: Fixed Argument Clinic sometimes causing compilation errors when
there was more than one function and/or method in a .c file with the same
name.

@item 
bpo-28791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28791}: Update Windows builds to use SQLite 3.21.0.

@item 
bpo-28791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28791}: Update OS X installer to use SQLite 3.21.0.

@item 
bpo-28643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28643}: Record profile-opt build progress with stamp files.

@item 
bpo-31866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31866}: Finish removing support for AtheOS.
@end itemize

@node Windows<53>,macOS<43>,Build<57>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id531}@anchor{1a36}
@subsubsection Windows



@itemize -

@item 
bpo-1102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1102}: Return @code{None} when @code{View.Fetch()} returns
@code{ERROR_NO_MORE_ITEMS} instead of raising @code{MSIError}. Initial patch by
Anthony Tuininga.

@item 
bpo-31944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31944}: Fixes Modify button in Apps and Features dialog.

@item 
bpo-20486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20486}: Implement the @code{Database.Close()} method to help closing MSI
database objects.

@item 
bpo-31857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31857}: Make the behavior of USE_STACKCHECK deterministic in a
multi-threaded environment.
@end itemize

@node macOS<43>,IDLE<43>,Windows<53>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id532}@anchor{1a37}
@subsubsection macOS



@itemize -

@item 
bpo-31392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31392}: Update macOS installer to use OpenSSL 1.0.2m
@end itemize

@node IDLE<43>,Tools/Demos<30>,macOS<43>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id533}@anchor{1a38}
@subsubsection IDLE



@itemize -

@item 
bpo-32207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32207}: Improve tk event exception tracebacks in IDLE. When tk event
handling is driven by IDLE's run loop, a confusing and distracting
queue.EMPTY traceback context is no longer added to tk event exception
tracebacks.  The traceback is now the same as when event handling is
driven by user code.  Patch based on a suggestion by Serhiy Storchaka.

@item 
bpo-32164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32164}: Delete unused file idlelib/tabbedpages.py. Use of TabbedPageSet
in configdialog was replaced by ttk.Notebook.

@item 
bpo-32100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32100}: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch
mostly by Cheryl Sabella.

@item 
bpo-31858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31858}: IDLE -- Restrict shell prompt manipulation to the shell. Editor
and output windows only see an empty last prompt line.  This simplifies
the code and fixes a minor bug when newline is inserted. Sys.ps1, if
present, is read on Shell start-up, but is not set or changed.

@item 
bpo-31860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31860}: The font sample in the IDLE configuration dialog is now
editable. Changes persist while IDLE remains open

@item 
bpo-31836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31836}: Test_code_module now passes if run after test_idle, which sets
ps1. The code module uses sys.ps1 if present or sets it to '>>> ' if not.
Test_code_module now properly tests both behaviors.  Ditto for ps2.

@item 
bpo-28603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28603}: Fix a TypeError that caused a shell restart when printing a
traceback that includes an exception that is unhashable. Patch by Zane
Bitter.

@item 
bpo-13802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13802}: Use non-Latin characters in the IDLE's Font settings sample.
Even if one selects a font that defines a limited subset of the unicode
Basic Multilingual Plane, tcl/tk will use other fonts that define a
character. The expanded example give users of non-Latin characters a
better idea of what they might see in IDLE's shell and editors. To make
room for the expanded sample, frames on the Font tab are re-arranged.  The
Font/Tabs help explains a bit about the additions.
@end itemize

@node Tools/Demos<30>,C API<54>,IDLE<43>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id534}@anchor{1a39}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-32159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32159}: Remove CVS and Subversion tools: remove svneol.py and
treesync.py scripts. CPython migrated from CVS to Subversion, to
Mercurial, and then to Git. CVS and Subversion are no longer used to
develop CPython.

@item 
bpo-30722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30722}: Make redemo work with Python 3.6 and newer versions. Also,
remove the @code{LOCALE} option since it doesn't work with string patterns in
Python 3. Patch by Christoph Sarnowski.
@end itemize

@node C API<54>,,Tools/Demos<30>,Python 3 7 0 alpha 3
@anchor{whatsnew/changelog id535}@anchor{1a3a}
@subsubsection C API



@itemize -

@item 
bpo-20891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20891}: Fix PyGILState_Ensure(). When PyGILState_Ensure() is called in
a non-Python thread before PyEval_InitThreads(), only call
PyEval_InitThreads() after calling PyThreadState_New() to fix a crash.

@item 
bpo-32125@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32125}: The @code{Py_UseClassExceptionsFlag} flag has been removed. It was
deprecated and wasn't used anymore since Python 2.0.

@item 
bpo-25612@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25612}: Move the current exception state from the frame object to the
co-routine. This simplifies the interpreter and fixes a couple of obscure
bugs caused by having swap exception state when entering or exiting a
generator.

@item 
bpo-23699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23699}: Add Py_RETURN_RICHCOMPARE macro to reduce boilerplate code in
rich comparison functions.

@item 
bpo-30697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30697}: The @code{PyExc_RecursionErrorInst} singleton is removed and
@code{PyErr_NormalizeException()} does not use it anymore. This singleton is
persistent and its members being never cleared may cause a segfault during
finalization of the interpreter. See also bpo-22898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22898}.
@end itemize

@node Python 3 7 0 alpha 2,Python 3 7 0 alpha 1,Python 3 7 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-7-0-alpha-2}@anchor{1a3b}
@subsection Python 3.7.0 alpha 2


`Release date: 2017-10-16'

@menu
* Core and Builtins: Core and Builtins<61>. 
* Library: Library<61>. 
* Documentation: Documentation<55>. 
* Build: Build<58>. 
* IDLE: IDLE<44>. 
* C API: C API<55>. 

@end menu

@node Core and Builtins<61>,Library<61>,,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id536}@anchor{1a3c}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-31558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31558}: @code{gc.freeze()} is a new API that allows for moving all objects
currently tracked by the garbage collector to a permanent generation,
effectively removing them from future collection events. This can be used
to protect those objects from having their PyGC_Head mutated. In effect,
this enables great copy-on-write stability at fork().

@item 
bpo-31642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31642}: Restored blocking "from package import module" by setting
sys.modules["package.module"] to None.

@item 
bpo-31708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31708}: Allow use of asynchronous generator expressions in synchronous
functions.

@item 
bpo-31709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31709}: Drop support of asynchronous __aiter__.

@item 
bpo-30404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30404}: The -u option now makes the stdout and stderr streams
unbuffered rather than line-buffered.

@item 
bpo-31619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31619}: Fixed a ValueError when convert a string with large number of
underscores to integer with binary base.

@item 
bpo-31602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31602}: Fix an assertion failure in @code{zipimporter.get_source()} in
case of a bad @code{zlib.decompress()}. Patch by Oren Milman.

@item 
bpo-31592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31592}: Fixed an assertion failure in Python parser in case of a bad
@code{unicodedata.normalize()}. Patch by Oren Milman.

@item 
bpo-31588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31588}: Raise a @code{TypeError} with a helpful error message when class
creation fails due to a metaclass with a bad @code{__prepare__()} method.
Patch by Oren Milman.

@item 
bpo-31574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31574}: Importlib was instrumented with two dtrace probes to profile
import timing.

@item 
bpo-31566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31566}: Fix an assertion failure in @code{_warnings.warn()} in case of a
bad @code{__name__} global. Patch by Oren Milman.

@item 
bpo-31506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31506}: Improved the error message logic for @code{object.__new__} and
@code{object.__init__}.

@item 
bpo-31505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31505}: Fix an assertion failure in @code{json}, in case
@code{_json.make_encoder()} received a bad @code{encoder()} argument. Patch by
Oren Milman.

@item 
bpo-31492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31492}: Fix assertion failures in case of failing to import from a
module with a bad @code{__name__} attribute, and in case of failing to access
an attribute of such a module. Patch by Oren Milman.

@item 
bpo-31478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31478}: Fix an assertion failure in @code{_random.Random.seed()} in case
the argument has a bad @code{__abs__()} method. Patch by Oren Milman.

@item 
bpo-31336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31336}: Speed up class creation by 10-20% by reducing the overhead in
the necessary special method lookups.  Patch by Stefan Behnel.

@item 
bpo-31415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31415}: Add @code{-X importtime} option to show how long each import
takes. It can be used to optimize application's startup time.  Support the
@geindex PYTHONPROFILEIMPORTTIME
@geindex variable d'environnement; PYTHONPROFILEIMPORTTIME
@ref{ae3,,PYTHONPROFILEIMPORTTIME} as an equivalent way to enable this.

@item 
bpo-31410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31410}: Optimized calling wrapper and classmethod descriptors.

@item 
bpo-31353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31353}: 
@geindex Python Enhancement Proposals; PEP 553
PEP 553@footnote{https://peps.python.org/pep-0553/} - Add a new built-in called @code{breakpoint()} which
calls @code{sys.breakpointhook()}.  By default this imports @code{pdb} and calls
@code{pdb.set_trace()}, but users may override @code{sys.breakpointhook()} to
call whatever debugger they want.  The original value of the hook is saved
in @code{sys.__breakpointhook__}.

@item 
bpo-17852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17852}: Maintain a list of open buffered files, flush them before
exiting the interpreter.  Based on a patch from Armin Rigo.

@item 
bpo-31315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31315}: Fix an assertion failure in imp.create_dynamic(), when
spec.name is not a string. Patch by Oren Milman.

@item 
bpo-31311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31311}: Fix a crash in the @code{__setstate__()} method of
@code{ctypes._CData}, in case of a bad @code{__dict__}. Patch by Oren Milman.

@item 
bpo-31293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31293}: Fix crashes in true division and multiplication of a timedelta
object by a float with a bad as_integer_ratio() method. Patch by Oren
Milman.

@item 
bpo-31285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31285}: Fix an assertion failure in @code{warnings.warn_explicit}, when
the return value of the received loader's @code{get_source()} has a bad
@code{splitlines()} method. Patch by Oren Milman.

@item 
bpo-30406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30406}: Make @code{async} and @code{await} proper keywords, as specified in
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@end itemize

@node Library<61>,Documentation<55>,Core and Builtins<61>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id537}@anchor{1a3d}
@subsubsection Library



@itemize -

@item 
bpo-30058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30058}: Fixed buffer overflow in select.kqueue.control().

@item 
bpo-31672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31672}: @code{idpattern} in @code{string.Template} matched some non-ASCII
characters. Now it uses @code{-i} regular expression local flag to avoid
non-ASCII characters.

@item 
bpo-31701@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31701}: On Windows, faulthandler.enable() now ignores MSC and COM
exceptions.

@item 
bpo-31728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31728}: Prevent crashes in @code{_elementtree} due to unsafe cleanup of
@code{Element.text} and @code{Element.tail}. Patch by Oren Milman.

@item 
bpo-31671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31671}: Now @code{re.compile()} converts passed RegexFlag to normal int
object before compiling. bm_regex_compile benchmark shows 14% performance
improvements.

@item 
bpo-30397@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30397}: The types of compiled regular objects and match objects are now
exposed as @code{re.Pattern} and @code{re.Match}.  This adds information in
pydoc output for the @code{re} module.

@item 
bpo-31675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31675}: Fixed memory leaks in Tkinter's methods splitlist() and split()
when pass a string larger than 2 GiB.

@item 
bpo-31673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31673}: Fixed typo in the name of Tkinter's method adderrorinfo().

@item 
bpo-31648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31648}: Improvements to path predicates in ElementTree: Allow
whitespace around predicate parts, i.e. "[a = 'text']" instead of
requiring the less readable "[a='text']". Add support for text comparison
of the current node, like "[.='text']". Patch by Stefan Behnel.

@item 
bpo-30806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30806}: Fix the string representation of a netrc object.

@item 
bpo-31638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31638}: Add optional argument @code{compressed} to
@code{zipapp.create_archive}, and add option @code{--compress} to the command
line interface of @code{zipapp}.

@item 
bpo-25351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25351}: Avoid venv activate failures with undefined variables

@item 
bpo-20519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20519}: Avoid ctypes use (if possible) and improve import time for
uuid.

@item 
bpo-28293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28293}: The regular expression cache is no longer completely dumped
when it is full.

@item 
bpo-31596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31596}: Added pthread_getcpuclockid() to the time module

@item 
bpo-27494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27494}: Make 2to3 accept a trailing comma in generator expressions. For
example, @code{set(x for x in [],)} is now allowed.

@item 
bpo-30347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30347}: Stop crashes when concurrently iterate over itertools.groupby()
iterators.

@item 
bpo-30346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30346}: An iterator produced by itertools.groupby() iterator now
becomes exhausted after advancing the groupby iterator.

@item 
bpo-31556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31556}: Cancel asyncio.wait_for future faster if timeout <= 0

@item 
bpo-31540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31540}: Allow passing a context object in
@ref{8db,,concurrent.futures.ProcessPoolExecutor} constructor. Also, free
job resources in @ref{8db,,concurrent.futures.ProcessPoolExecutor} earlier
to improve memory usage when a worker waits for new jobs.

@item 
bpo-31516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31516}: @code{threading.current_thread()} should not return a dummy thread
at shutdown.

@item 
bpo-31525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31525}: In the sqlite module, require the sqlite3_prepare_v2 API. Thus,
the sqlite module now requires sqlite version at least 3.3.9.

@item 
bpo-26510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26510}: argparse subparsers are now required by default.  This matches
behaviour in Python 2. For optional subparsers, use the new parameter
@code{add_subparsers(required=False)}. Patch by Anthony Sottile. (As of
3.7.0rc1, the default was changed to not required as had been the case
since Python 3.3.)

@item 
bpo-27541@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27541}: Reprs of subclasses of some collection and iterator classes
(@code{bytearray}, @code{array.array}, @code{collections.deque},
@code{collections.defaultdict}, @code{itertools.count}, @code{itertools.repeat})
now contain actual type name instead of hardcoded names of the base class.

@item 
bpo-31351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31351}: python -m ensurepip now exits with non-zero exit code if pip
bootstrapping has failed.

@item 
bpo-31389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31389}: @code{pdb.set_trace()} now takes an optional keyword-only argument
@code{header}. If given, this is printed to the console just before debugging
begins.
@end itemize

@node Documentation<55>,Build<58>,Library<61>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id538}@anchor{1a3e}
@subsubsection Documentation



@itemize -

@item 
bpo-31537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31537}: Fix incorrect usage of @code{get_history_length} in readline
documentation example code. Patch by Brad Smith.

@item 
bpo-30085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30085}: The operator functions without double underscores are preferred
for clarity. The one with underscores are only kept for
back-compatibility.
@end itemize

@node Build<58>,IDLE<44>,Documentation<55>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id539}@anchor{1a3f}
@subsubsection Build



@itemize -

@item 
bpo-31696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31696}: Improve compiler version information in @ref{177,,sys.version}
when Python is built with Clang.

@item 
bpo-31625@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31625}: Stop using ranlib on static libraries. Instead, we assume ar
supports the 's' flag.

@item 
bpo-31624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31624}: Remove support for BSD/OS.

@item 
bpo-22140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22140}: Prevent double substitution of prefix in python-config.sh.

@item 
bpo-31569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31569}: Correct PCBuild/ case to PCbuild/ in build scripts and
documentation.

@item 
bpo-31536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31536}: Avoid wholesale rebuild after @code{make regen-all} if nothing
changed.
@end itemize

@node IDLE<44>,C API<55>,Build<58>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id540}@anchor{1a40}
@subsubsection IDLE



@itemize -

@item 
bpo-31460@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31460}: Simplify the API of IDLE's Module Browser. Passing a widget
instead of an flist with a root widget opens the option of creating a
browser frame that is only part of a window.  Passing a full file name
instead of pieces assumed to come from a .py file opens the possibility of
browsing python files that do not end in .py.

@item 
bpo-31649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31649}: IDLE - Make _htest, _utest parameters keyword only.

@item 
bpo-31559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31559}: Remove test order dependence in idle_test.test_browser.

@item 
bpo-31459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31459}: Rename IDLE's module browser from Class Browser to Module
Browser. The original module-level class and method browser became a
module browser, with the addition of module-level functions, years ago.
Nested classes and functions were added yesterday.  For
back-compatibility, the virtual event <<open-class-browser>>, which
appears on the Keys tab of the Settings dialog, is not changed. Patch by
Cheryl Sabella.

@item 
bpo-31500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31500}: Default fonts now are scaled on HiDPI displays.

@item 
bpo-1612262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1612262}: IDLE module browser now shows nested classes and functions.
Original patches for code and tests by Guilherme Polo and Cheryl Sabella,
respectively.
@end itemize

@node C API<55>,,IDLE<44>,Python 3 7 0 alpha 2
@anchor{whatsnew/changelog id541}@anchor{1a41}
@subsubsection C API



@itemize -

@item 
bpo-28280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28280}: Make @code{PyMapping_Keys()}, @code{PyMapping_Values()} and
@code{PyMapping_Items()} always return a @code{list} (rather than a @code{list} or
a @code{tuple}). Patch by Oren Milman.

@item 
bpo-31532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31532}: Fix memory corruption due to allocator mix in getpath.c between
Py_GetPath() and Py_SetPath()

@item 
bpo-25658@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25658}: Implement 
@geindex Python Enhancement Proposals; PEP 539
PEP 539@footnote{https://peps.python.org/pep-0539/} for Thread Specific Storage (TSS) API: it
is a new Thread Local Storage (TLS) API to CPython which would supersede
use of the existing TLS API within the CPython interpreter, while
deprecating the existing API. PEP written by Erik M. Bray, patch by
Masayuki Yamamoto.
@end itemize

@node Python 3 7 0 alpha 1,Python 3 6 6 final,Python 3 7 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-7-0-alpha-1}@anchor{1a42}
@subsection Python 3.7.0 alpha 1


`Release date: 2017-09-19'

@menu
* Security: Security<38>. 
* Core and Builtins: Core and Builtins<62>. 
* Library: Library<62>. 
* Documentation: Documentation<56>. 
* Tests: Tests<56>. 
* Build: Build<59>. 
* Windows: Windows<54>. 
* IDLE: IDLE<45>. 
* Tools/Demos: Tools/Demos<31>. 
* C API: C API<56>. 

@end menu

@node Security<38>,Core and Builtins<62>,,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id542}@anchor{1a43}
@subsubsection Security



@itemize -

@item 
bpo-29781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29781}: SSLObject.version() now correctly returns None when handshake
over BIO has not been performed yet.

@item 
bpo-29505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29505}: Add fuzz tests for float(str), int(str), unicode(str); for
oss-fuzz.

@item 
bpo-30947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30947}: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to
get security fixes.

@item 
bpo-30730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30730}: Prevent environment variables injection in subprocess on
Windows.  Prevent passing other environment variables and command
arguments.

@item 
bpo-30694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30694}: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple
security vulnerabilities including: 
@geindex Common Vulnerabilities and Exposures; CVE 2017-9233
CVE 2017-9233@footnote{https://www.cve.org/CVERecord?id=CVE-2017-9233} (External entity
infinite loop DoS), 
@geindex Common Vulnerabilities and Exposures; CVE 2016-9063
CVE 2016-9063@footnote{https://www.cve.org/CVERecord?id=CVE-2016-9063} (Integer overflow, re-fix),
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718} (Fix regression bugs from 2.2.0's fix to
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718}) and 
@geindex Common Vulnerabilities and Exposures; CVE 2012-0876
CVE 2012-0876@footnote{https://www.cve.org/CVERecord?id=CVE-2012-0876} (Counter hash flooding with
SipHash). Note: the 
@geindex Common Vulnerabilities and Exposures; CVE 2016-5300
CVE 2016-5300@footnote{https://www.cve.org/CVERecord?id=CVE-2016-5300} (Use os-specific entropy sources like
getrandom) doesn't impact Python, since Python already gets entropy from
the OS to set the expat secret using @code{XML_SetHashSalt()}.

@item 
bpo-30500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30500}: Fix urllib.parse.splithost() to correctly parse fragments. For
example, @code{splithost('//127.0.0.1#@@evil.com/')} now correctly returns the
@code{127.0.0.1} host, instead of treating @code{@@evil.com} as the host in an
authentication (@code{login@@host}).

@item 
bpo-29591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29591}: Update expat copy from 2.1.1 to 2.2.0 to get fixes of
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718} and 
@geindex Common Vulnerabilities and Exposures; CVE 2016-4472
CVE 2016-4472@footnote{https://www.cve.org/CVERecord?id=CVE-2016-4472}. See
@indicateurl{https://sourceforge.net/p/expat/bugs/537/} for more information.
@end itemize

@node Core and Builtins<62>,Library<62>,Security<38>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id543}@anchor{1a44}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-31490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31490}: Fix an assertion failure in @code{ctypes} class definition, in
case the class has an attribute whose name is specified in @code{_anonymous_}
but not in @code{_fields_}. Patch by Oren Milman.

@item 
bpo-31471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31471}: Fix an assertion failure in @code{subprocess.Popen()} on Windows,
in case the env argument has a bad @code{keys()} method. Patch by Oren
Milman.

@item 
bpo-31418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31418}: Fix an assertion failure in @code{PyErr_WriteUnraisable()} in case
of an exception with a bad @code{__module__} attribute. Patch by Oren Milman.

@item 
bpo-31416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31416}: Fix assertion failures in case of a bad warnings.filters or
warnings.defaultaction. Patch by Oren Milman.

@item 
bpo-28411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28411}: Change direct usage of PyInterpreterState.modules to
PyImport_GetModuleDict(). Also introduce more uniformity in other code
that deals with sys.modules. This helps reduce complications when working
on sys.modules.

@item 
bpo-28411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28411}: Switch to the abstract API when dealing with
@code{PyInterpreterState.modules}. This allows later support for all dict
subclasses and other Mapping implementations.  Also add a
@code{PyImport_GetModule()} function to reduce a bunch of duplicated code.

@item 
bpo-31411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31411}: Raise a TypeError instead of SystemError in case
warnings.onceregistry is not a dictionary. Patch by Oren Milman.

@item 
bpo-31344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31344}: For finer control of tracing behaviour when testing the
interpreter, two new frame attributes have been added to control the
emission of particular trace events: @code{f_trace_lines} (@code{True} by
default) to turn off per-line trace events; and @code{f_trace_opcodes}
(@code{False} by default) to turn on per-opcode trace events.

@item 
bpo-31373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31373}: Fix several possible instances of undefined behavior due to
floating-point demotions.

@item 
bpo-30465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30465}: Location information (@code{lineno} and @code{col_offset}) in
f-strings is now (mostly) correct.  This fixes tools like flake8 from
showing warnings on the wrong line (typically the first line of the file).

@item 
bpo-30860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30860}: Consolidate CPython's global runtime state under a single
struct.  This improves discoverability of the runtime state.

@item 
bpo-31347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31347}: Fix possible undefined behavior in _PyObject_FastCall_Prepend.

@item 
bpo-31343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31343}: Include sys/sysmacros.h for major(), minor(), and makedev().
GNU C libray plans to remove the functions from sys/types.h.

@item 
bpo-31291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31291}: Fix an assertion failure in @code{zipimport.zipimporter.get_data}
on Windows, when the return value of @code{pathname.replace('/','\\')} isn't
a string. Patch by Oren Milman.

@item 
bpo-31271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31271}: Fix an assertion failure in the @code{write()} method of
@code{io.TextIOWrapper}, when the encoder doesn't return a bytes object.
Patch by Oren Milman.

@item 
bpo-31243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31243}: Fix a crash in some methods of @code{io.TextIOWrapper}, when the
decoder's state is invalid. Patch by Oren Milman.

@item 
bpo-30721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30721}: @code{print} now shows correct usage hint for using Python 2
redirection syntax.  Patch by Sanyam Khurana.

@item 
bpo-31070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31070}: Fix a race condition in importlib _get_module_lock().

@item 
bpo-30747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30747}: Add a non-dummy implementation of _Py_atomic_store and
_Py_atomic_load on MSVC.

@item 
bpo-31095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31095}: Fix potential crash during GC caused by @code{tp_dealloc} which
doesn't call @code{PyObject_GC_UnTrack()}.

@item 
bpo-31071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31071}: Avoid masking original TypeError in call with * unpacking when
other arguments are passed.

@item 
bpo-30978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30978}: str.format_map() now passes key lookup exceptions through.
Previously any exception was replaced with a KeyError exception.

@item 
bpo-30808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30808}: Use _Py_atomic API for concurrency-sensitive signal state.

@item 
bpo-30876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30876}: Relative import from unloaded package now reimports the package
instead of failing with SystemError.  Relative import from non-package now
fails with ImportError rather than SystemError.

@item 
bpo-30703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30703}: Improve signal delivery. Avoid using Py_AddPendingCall from
signal handler, to avoid calling signal-unsafe functions. The tests I'm
adding here fail without the rest of the patch, on Linux and OS X. This
means our signal delivery logic had defects (some signals could be lost).

@item 
bpo-30765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30765}: Avoid blocking in pthread_mutex_lock() when
PyThread_acquire_lock() is asked not to block.

@item 
bpo-31161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31161}: Make sure the 'Missing parentheses' syntax error message is
only applied to SyntaxError, not to subclasses. Patch by Martijn Pieters.

@item 
bpo-30814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30814}: Fixed a race condition when import a submodule from a package.

@item 
bpo-30736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30736}: The internal unicodedata database has been upgraded to Unicode
10.0.

@item 
bpo-30604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30604}: Move co_extra_freefuncs from per-thread to per-interpreter to
avoid crashes.

@item 
bpo-30597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30597}: @code{print} now shows expected input in custom error message when
used as a Python 2 statement. Patch by Sanyam Khurana.

@item 
bpo-30682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30682}: Removed a too-strict assertion that failed for certain
f-strings, such as eval("f'\n'") and eval("f'\r'").

@item 
bpo-30501@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30501}: The compiler now produces more optimal code for complex
condition expressions in the "if", "while" and "assert" statement, the
"if" expression, and generator expressions and comprehensions.

@item 
bpo-28180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28180}: Implement 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/} (legacy C locale coercion). This means
that when a suitable coercion target locale is available, both the core
interpreter and locale-aware C extensions will assume the use of UTF-8 as
the default text encoding, rather than ASCII.

@item 
bpo-30486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30486}: Allows setting cell values for __closure__. Patch by Lisa
Roach.

@item 
bpo-30537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30537}: itertools.islice now accepts integer-like objects (having an
__index__ method) as start, stop, and slice arguments

@item 
bpo-25324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25324}: Tokens needed for parsing in Python moved to C. @code{COMMENT},
@code{NL} and @code{ENCODING}. This way the tokens and tok_names in the token
module don't get changed when you import the tokenize module.

@item 
bpo-29104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29104}: Fixed parsing backslashes in f-strings.

@item 
bpo-27945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27945}: Fixed various segfaults with dict when input collections are
mutated during searching, inserting or comparing.  Based on patches by
Duane Griffin and Tim Mitchell.

@item 
bpo-25794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25794}: Fixed type.__setattr__() and type.__delattr__() for
non-interned attribute names.  Based on patch by Eryk Sun.

@item 
bpo-30039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30039}: If a KeyboardInterrupt happens when the interpreter is in the
middle of resuming a chain of nested 'yield from' or 'await' calls, it's
now correctly delivered to the innermost frame.

@item 
bpo-28974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28974}: @code{object.__format__(x, '@w{'})} is now equivalent to @code{str(x)}
rather than @code{format(str(self), '@w{'})}.

@item 
bpo-30024@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30024}: Circular imports involving absolute imports with binding a
submodule to a name are now supported.

@item 
bpo-12414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12414}: sys.getsizeof() on a code object now returns the sizes which
includes the code struct and sizes of objects which it references. Patch
by Donghee Na.

@item 
bpo-29839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29839}: len() now raises ValueError rather than OverflowError if
__len__() returned a large negative integer.

@item 
bpo-11913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11913}: README.rst is now included in the list of distutils standard
READMEs and therefore included in source distributions.

@item 
bpo-29914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29914}: Fixed default implementations of __reduce__ and
__reduce_ex__(). object.__reduce__() no longer takes arguments,
object.__reduce_ex__() now requires one argument.

@item 
bpo-29949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29949}: Fix memory usage regression of set and frozenset object.

@item 
bpo-29935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29935}: Fixed error messages in the index() method of tuple, list and
deque when pass indices of wrong type.

@item 
bpo-29816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29816}: Shift operation now has less opportunity to raise
OverflowError. ValueError always is raised rather than OverflowError for
negative counts. Shifting zero with non-negative count always returns
zero.

@item 
bpo-24821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24821}: Fixed the slowing down to 25 times in the searching of some
unlucky Unicode characters.

@item 
bpo-29102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29102}: Add a unique ID to PyInterpreterState.  This makes it easier to
identify each subinterpreter.

@item 
bpo-29894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29894}: The deprecation warning is emitted if __complex__ returns an
instance of a strict subclass of complex.  In a future versions of Python
this can be an error.

@item 
bpo-29859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29859}: Show correct error messages when any of the pthread_* calls in
thread_pthread.h fails.

@item 
bpo-29849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29849}: Fix a memory leak when an ImportError is raised during from
import.

@item 
bpo-28856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28856}: Fix an oversight that %b format for bytes should support
objects follow the buffer protocol.

@item 
bpo-29723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29723}: The @code{sys.path[0]} initialization change for bpo-29139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29139} caused
a regression by revealing an inconsistency in how sys.path is initialized
when executing @code{__main__} from a zipfile, directory, or other import
location. The interpreter now consistently avoids ever adding the import
location's parent directory to @code{sys.path}, and ensures no other
@code{sys.path} entries are inadvertently modified when inserting the import
location named on the command line.

@item 
bpo-29568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29568}: Escaped percent "%%" in the format string for classic string
formatting no longer allows any characters between two percents.

@item 
bpo-29714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29714}: Fix a regression that bytes format may fail when containing
zero bytes inside.

@item 
bpo-29695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29695}: bool(), float(), list() and tuple() no longer take keyword
arguments. The first argument of int() can now be passes only as
positional argument.

@item 
bpo-28893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28893}: Set correct __cause__ for errors about invalid awaitables
returned from __aiter__ and __anext__.

@item 
bpo-28876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28876}: @code{bool(range)} works even if @code{len(range)} raises
@ref{86d,,OverflowError}.

@item 
bpo-29683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29683}: Fixes to memory allocation in _PyCode_SetExtra.  Patch by Brian
Coleman.

@item 
bpo-29684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29684}: Fix minor regression of PyEval_CallObjectWithKeywords. It
should raise TypeError when kwargs is not a dict.  But it might cause segv
when args=NULL and kwargs is not a dict.

@item 
bpo-28598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28598}: Support __rmod__ for subclasses of str being called before
str.__mod__. Patch by Martijn Pieters.

@item 
bpo-29607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29607}: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by
Matthieu Dartiailh.

@item 
bpo-29602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29602}: Fix incorrect handling of signed zeros in complex constructor
for complex subclasses and for inputs having a __complex__ method. Patch
by Serhiy Storchaka.

@item 
bpo-29347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29347}: Fixed possibly dereferencing undefined pointers when creating
weakref objects.

@item 
bpo-29463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29463}: Add @code{docstring} field to Module, ClassDef, FunctionDef, and
AsyncFunctionDef ast nodes.  docstring is not first stmt in their body
anymore.  It affects @code{co_firstlineno} and @code{co_lnotab} of code object
for module and class. (Reverted in bpo-32911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32911}.)

@item 
bpo-29438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29438}: Fixed use-after-free problem in key sharing dict.

@item 
bpo-29546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29546}: Set the 'path' and 'name' attribute on ImportError for @code{from
... import ...}.

@item 
bpo-29546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29546}: Improve from-import error message with location

@item 
bpo-29478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29478}: If max_line_length=None is specified while using the Compat32
policy, it is no longer ignored.  Patch by Mircea Cosbuc.

@item 
bpo-29319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29319}: Prevent RunMainFromImporter overwriting sys.path[0].

@item 
bpo-29337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29337}: Fixed possible BytesWarning when compare the code objects.
Warnings could be emitted at compile time.

@item 
bpo-29327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29327}: Fixed a crash when pass the iterable keyword argument to
sorted().

@item 
bpo-29034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29034}: Fix memory leak and use-after-free in os module
(path_converter).

@item 
bpo-29159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29159}: Fix regression in bytes(x) when x.__index__() raises Exception.

@item 
bpo-29049@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29049}: Call _PyObject_GC_TRACK() lazily when calling Python function.
Calling function is up to 5% faster.

@item 
bpo-28927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28927}: bytes.fromhex() and bytearray.fromhex() now ignore all ASCII
whitespace, not only spaces.  Patch by Robert Xiao.

@item 
bpo-28932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28932}: Do not include <sys/random.h> if it does not exist.

@item 
bpo-25677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25677}: Correct the positioning of the syntax error caret for indented
blocks. Based on patch by Michael Layzell.

@item 
bpo-29000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29000}: Fixed bytes formatting of octals with zero padding in alternate
form.

@item 
bpo-18896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18896}: Python function can now have more than 255 parameters.
collections.namedtuple() now supports tuples with more than 255 elements.

@item 
bpo-28596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28596}: The preferred encoding is UTF-8 on Android. Patch written by
Chi Hsuan Yen.

@item 
bpo-22257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22257}: Clean up interpreter startup (see 
@geindex Python Enhancement Proposals; PEP 432
PEP 432@footnote{https://peps.python.org/pep-0432/}).

@item 
bpo-26919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26919}: On Android, operating system data is now always encoded/decoded
to/from UTF-8, instead of the locale encoding to avoid inconsistencies
with os.fsencode() and os.fsdecode() which are already using UTF-8.

@item 
bpo-28991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28991}: functools.lru_cache() was susceptible to an obscure reentrancy
bug triggerable by a monkey-patched len() function.

@item 
bpo-28147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28147}: Fix a memory leak in split-table dictionaries: setattr() must
not convert combined table into split table. Patch written by INADA Naoki.

@item 
bpo-28739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28739}: f-string expressions are no longer accepted as docstrings and
by ast.literal_eval() even if they do not include expressions.

@item 
bpo-28512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28512}: Fixed setting the offset attribute of SyntaxError by
PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

@item 
bpo-28918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28918}: Fix the cross compilation of xxlimited when Python has been
built with Py_DEBUG defined.

@item 
bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}: Rather than silently producing a class that doesn't support
zero-argument @code{super()} in methods, failing to pass the new
@code{__classcell__} namespace entry up to @code{type.__new__} now results in a
@code{DeprecationWarning} and a class that supports zero-argument
@code{super()}.

@item 
bpo-28797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28797}: Modifying the class __dict__ inside the __set_name__ method of
a descriptor that is used inside that class no longer prevents calling the
__set_name__ method of other descriptors.

@item 
bpo-28799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28799}: Remove the @code{PyEval_GetCallStats()} function and deprecate the
untested and undocumented @code{sys.callstats()} function. Remove the
@code{CALL_PROFILE} special build: use the @ref{14b5,,sys.setprofile()} function,
@ref{27,,cProfile} or @ref{ae,,profile} to profile function calls.

@item 
bpo-12844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12844}: More than 255 arguments can now be passed to a function.

@item 
bpo-28782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28782}: Fix a bug in the implementation @code{yield from} when checking if
the next instruction is YIELD_FROM. Regression introduced by WORDCODE
(bpo-26647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26647}).

@item 
bpo-28774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28774}: Fix error position of the unicode error in ASCII and Latin1
encoders when a string returned by the error handler contains multiple
non-encodable characters (non-ASCII for the ASCII codec, characters out of
the U+0000-U+00FF range for Latin1).

@item 
bpo-28731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28731}: Optimize _PyDict_NewPresized() to create correct size dict.
Improve speed of dict literal with constant keys up to 30%.

@item 
bpo-28532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28532}: Show sys.version when -V option is supplied twice.

@item 
bpo-27100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27100}: The with-statement now checks for __enter__ before it checks
for __exit__. This gives less confusing error messages when both methods
are missing. Patch by Jonathan Ellington.

@item 
bpo-28746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28746}: Fix the set_inheritable() file descriptor method on platforms
that do not have the ioctl FIOCLEX and FIONCLEX commands.

@item 
bpo-26920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26920}: Fix not getting the locale's charset upon initializing the
interpreter, on platforms that do not have langinfo.

@item 
bpo-28648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28648}: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X
when decode astral characters.  Patch by Xiang Zhang.

@item 
bpo-28665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28665}: Improve speed of the STORE_DEREF opcode by 40%.

@item 
bpo-19398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19398}: Extra slash no longer added to sys.path components in case of
empty compile-time PYTHONPATH components.

@item 
bpo-28621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28621}: Sped up converting int to float by reusing faster bits counting
implementation.  Patch by Adrian Wielgosik.

@item 
bpo-28580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28580}: Optimize iterating split table values. Patch by Xiang Zhang.

@item 
bpo-28583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28583}: PyDict_SetDefault didn't combine split table when needed. Patch
by Xiang Zhang.

@item 
bpo-28128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28128}: Deprecation warning for invalid str and byte escape sequences
now prints better information about where the error occurs. Patch by
Serhiy Storchaka and Eric Smith.

@item 
bpo-28509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28509}: dict.update() no longer allocate unnecessary large memory.

@item 
bpo-28426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28426}: Fixed potential crash in PyUnicode_AsDecodedObject() in debug
build.

@item 
bpo-28517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28517}: Fixed of-by-one error in the peephole optimizer that caused
keeping unreachable code.

@item 
bpo-28214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28214}: Improved exception reporting for problematic __set_name__
attributes.

@item 
bpo-23782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23782}: Fixed possible memory leak in _PyTraceback_Add() and exception
loss in PyTraceBack_Here().

@item 
bpo-28183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28183}: Optimize and cleanup dict iteration.

@item 
bpo-26081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26081}: Added C implementation of asyncio.Future. Original patch by
Yury Selivanov.

@item 
bpo-28379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28379}: Added sanity checks and tests for PyUnicode_CopyCharacters().
Patch by Xiang Zhang.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: The type of long range iterator is now registered as Iterator.
Patch by Oren Milman.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: Creating instances of range_iterator by calling range_iterator
type now is disallowed.  Calling iter() on range instance is the only way.
Patch by Oren Milman.

@item 
bpo-26906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26906}: Resolving special methods of uninitialized type now causes
implicit initialization of the type instead of a fail.

@item 
bpo-18287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18287}: PyType_Ready() now checks that tp_name is not NULL. Original
patch by Niklas Koep.

@item 
bpo-24098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24098}: Fixed possible crash when AST is changed in process of
compiling it.

@item 
bpo-28201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28201}: Dict reduces possibility of 2nd conflict in hash table when
hashes have same lower bits.

@item 
bpo-28350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28350}: String constants with null character no longer interned.

@item 
bpo-26617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26617}: Fix crash when GC runs during weakref callbacks.

@item 
bpo-27942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27942}: String constants now interned recursively in tuples and
frozensets.

@item 
bpo-28289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28289}: ImportError.__init__ now resets not specified attributes.

@item 
bpo-21578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21578}: Fixed misleading error message when ImportError called with
invalid keyword args.

@item 
bpo-28203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28203}: Fix incorrect type in complex(1.0, @{2:3@}) error message. Patch
by Soumya Sharma.

@item 
bpo-28086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28086}: Single var-positional argument of tuple subtype was passed
unscathed to the C-defined function.  Now it is converted to exact tuple.

@item 
bpo-28214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28214}: Now __set_name__ is looked up on the class instead of the
instance.

@item 
bpo-27955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27955}: Fallback on reading /dev/urandom device when the getrandom()
syscall fails with EPERM, for example when blocked by SECCOMP.

@item 
bpo-28192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28192}: Don't import readline in isolated mode.

@item 
bpo-27441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27441}: Remove some redundant assignments to ob_size in longobject.c.
Thanks Oren Milman.

@item 
bpo-27222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27222}: Clean up redundant code in long_rshift function. Thanks Oren
Milman.

@item 
Upgrade internal unicode databases to Unicode version 9.0.0.

@item 
bpo-28131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28131}: Fix a regression in zipimport's compile_source().  zipimport
should use the same optimization level as the interpreter.

@item 
bpo-28126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28126}: Replace Py_MEMCPY with memcpy(). Visual Studio can properly
optimize memcpy().

@item 
bpo-28120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28120}: Fix dict.pop() for splitted dictionary when trying to remove a
"pending key" (Not yet inserted in split-table). Patch by Xiang Zhang.

@item 
bpo-26182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26182}: Raise DeprecationWarning when async and await keywords are used
as variable/attribute/class/function name.

@item 
bpo-26182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26182}: Fix a refleak in code that raises DeprecationWarning.

@item 
bpo-28721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28721}: Fix asynchronous generators aclose() and athrow() to handle
StopAsyncIteration propagation properly.

@item 
bpo-26110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26110}: Speed-up method calls: add LOAD_METHOD and CALL_METHOD opcodes.
@end itemize

@node Library<62>,Documentation<56>,Core and Builtins<62>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id544}@anchor{1a45}
@subsubsection Library



@itemize -

@item 
bpo-31499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31499}: xml.etree: Fix a crash when a parser is part of a reference
cycle.

@item 
bpo-31482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31482}: @code{random.seed()} now works with bytes in version=1

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: typing.get_type_hints now finds the right globalns for classes
and modules by default (when no @code{globalns} was specified by the caller).

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Speed improvements to the @code{typing} module.  Original PRs by
Ivan Levkivskyi and Mitar.

@item 
bpo-31544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31544}: The C accelerator module of ElementTree ignored exceptions
raised when looking up TreeBuilder target methods in XMLParser().

@item 
bpo-31234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31234}: socket.create_connection() now fixes manually a reference
cycle: clear the variable storing the last exception on success.

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: LoggerAdapter objects can now be nested.

@item 
bpo-31431@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31431}: SSLContext.check_hostname now automatically sets
SSLContext.verify_mode to ssl.CERT_REQUIRED instead of failing with a
ValueError.

@item 
bpo-31233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31233}: socketserver.ThreadingMixIn now keeps a list of non-daemonic
threads to wait until all these threads complete in server_close().

@item 
bpo-28638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28638}: Changed the implementation strategy for
collections.namedtuple() to substantially reduce the use of exec() in
favor of precomputed methods. As a result, the `verbose' parameter and
`_source' attribute are no longer supported.  The benefits include 1)
having a smaller memory footprint for applications using multiple named
tuples, 2) faster creation of the named tuple class (approx 4x to 6x
depending on how it is measured), and 3) minor speed-ups for instance
creation using __new__, _make, and _replace.  (The primary patch
contributor is Jelle Zijlstra with further improvements by INADA Naoki,
Serhiy Storchaka, and Raymond Hettinger.)

@item 
bpo-31400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31400}: Improves SSL error handling to avoid losing error numbers.

@item 
bpo-27629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27629}: Make return types of SSLContext.wrap_bio() and
SSLContext.wrap_socket() customizable.

@item 
bpo-28958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28958}: ssl.SSLContext() now uses OpenSSL error information when a
context cannot be instantiated.

@item 
bpo-28182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28182}: The SSL module now raises SSLCertVerificationError when OpenSSL
fails to verify the peer's certificate. The exception contains more
information about the error.

@item 
bpo-27340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27340}: SSLSocket.sendall() now uses memoryview to create slices of
data. This fixes support for all bytes-like object. It is also more
efficient and avoids costly copies.

@item 
bpo-14191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14191}: A new function
@code{argparse.ArgumentParser.parse_intermixed_args} provides the ability to
parse command lines where there user intermixes options and positional
arguments.

@item 
bpo-31178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31178}: Fix string concatenation bug in rare error path in the
subprocess module

@item 
bpo-31350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31350}: Micro-optimize @code{asyncio._get_running_loop()} to become up
to 10% faster.

@item 
bpo-31170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31170}: expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of
partial characters for UTF-8 input (libexpat bug 115):
@indicateurl{https://github.com/libexpat/libexpat/issues/115}

@item 
bpo-29136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29136}: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

@item 
bpo-1198569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1198569}: @code{string.Template} subclasses can optionally define
@code{braceidpattern} if they want to specify different placeholder patterns
inside and outside the braces.  If None (the default) it falls back to
@code{idpattern}.

@item 
bpo-31326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31326}: concurrent.futures.ProcessPoolExecutor.shutdown() now
explicitly closes the call queue. Moreover, shutdown(wait=True) now also
join the call queue thread, to prevent leaking a dangling thread.

@item 
bpo-27144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27144}: The @code{map()} and @code{as_completed()} iterators in
@code{concurrent.futures} now avoid keeping a reference to yielded objects.

@item 
bpo-31281@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31281}: Fix @code{fileinput.FileInput(files, inplace=True)} when @code{files}
contain @code{pathlib.Path} objects.

@item 
bpo-10746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10746}: Fix ctypes producing wrong 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} type codes for integer
types.

@item 
bpo-27584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27584}: @code{AF_VSOCK} has been added to the socket interface which
allows communication between virtual machines and their host.

@item 
bpo-22536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22536}: The subprocess module now sets the filename when
FileNotFoundError is raised on POSIX systems due to the executable or cwd
not being found.

@item 
bpo-29741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29741}: Update some methods in the _pyio module to also accept integer
types. Patch by Oren Milman.

@item 
bpo-31249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31249}: concurrent.futures: WorkItem.run() used by ThreadPoolExecutor
now breaks a reference cycle between an exception object and the WorkItem
object.

@item 
bpo-31247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31247}: xmlrpc.server now explicitly breaks reference cycles when using
sys.exc_info() in code handling exceptions.

@item 
bpo-23835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23835}: configparser: reading defaults in the @code{ConfigParser()}
constructor is now using @code{read_dict()}, making its behavior consistent
with the rest of the parser.  Non-string keys and values in the defaults
dictionary are now being implicitly converted to strings.  Patch by James
Tocknell.

@item 
bpo-31238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31238}: pydoc: the stop() method of the private ServerThread class now
waits until DocServer.serve_until_quit() completes and then explicitly
sets its docserver attribute to None to break a reference cycle.

@item 
bpo-5001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5001}: Many asserts in @code{multiprocessing} are now more informative,
and some error types have been changed to more specific ones.

@item 
bpo-31109@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31109}: Convert zipimport to use Argument Clinic.

@item 
bpo-30102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30102}: The ssl and hashlib modules now call
OPENSSL_add_all_algorithms_noconf() on OpenSSL < 1.1.0. The function
detects CPU features and enables optimizations on some CPU architectures
such as POWER8. Patch is based on research from Gustavo Serra Scalet.

@item 
bpo-18966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18966}: Non-daemonic threads created by a multiprocessing.Process are
now joined on child exit.

@item 
bpo-31183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31183}: @code{dis} now works with asynchronous generator and coroutine
objects. Patch by George Collins based on diagnosis by Luciano Ramalho.

@item 
bpo-5001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5001}: There are a number of uninformative asserts in the
@code{multiprocessing} module, as noted in issue 5001. This change fixes two
of the most potentially problematic ones, since they are in
error-reporting code, in the @code{multiprocessing.managers.convert_to_error}
function. (It also makes more informative a ValueError message.) The only
potentially problematic change is that the AssertionError is now a
TypeError; however, this should also help distinguish it from an
AssertionError being `reported' by the function/its caller (such as in
issue 31169). - Patch by Allen W. Smith (drallensmith on github).

@item 
bpo-31185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31185}: Fixed miscellaneous errors in asyncio speedup module.

@item 
bpo-31151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31151}: socketserver.ForkingMixIn.server_close() now waits until all
child processes completed to prevent leaking zombie processes.

@item 
bpo-31072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31072}: Add an @code{include_file} parameter to
@code{zipapp.create_archive()}

@item 
bpo-24700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24700}: Optimize array.array comparison. It is now from 10x up to 70x
faster when comparing arrays holding values of the same integer type.

@item 
bpo-31135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31135}: ttk: fix the destroy() method of LabeledScale and OptionMenu
classes. Call the parent destroy() method even if the used attribute
doesn't exist. The LabeledScale.destroy() method now also explicitly
clears label and scale attributes to help the garbage collector to destroy
all widgets.

@item 
bpo-31107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31107}: Fix @code{copyreg._slotnames()} mangled attribute calculation for
classes whose name begins with an underscore. Patch by Shane Harvey.

@item 
bpo-31080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31080}: Allow @code{logging.config.fileConfig} to accept kwargs and/or
args.

@item 
bpo-30897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30897}: @code{pathlib.Path} objects now include an @code{is_mount()} method
(only implemented on POSIX).  This is similar to @code{os.path.ismount(p)}.
Patch by Cooper Ry Lees.

@item 
bpo-31061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31061}: Fixed a crash when using asyncio and threads.

@item 
bpo-30987@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30987}: Added support for CAN ISO-TP protocol in the socket module.

@item 
bpo-30522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30522}: Added a @code{setStream} method to @code{logging.StreamHandler} to
allow the stream to be set after creation.

@item 
bpo-30502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30502}: Fix handling of long oids in ssl.  Based on patch by Christian
Heimes.

@item 
bpo-5288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5288}: Support tzinfo objects with sub-minute offsets.

@item 
bpo-30919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30919}: Fix shared memory performance regression in multiprocessing in
3.x. Shared memory used anonymous memory mappings in 2.x, while 3.x mmaps
actual files. Try to be careful to do as little disk I/O as possible.

@item 
bpo-26732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26732}: Fix too many fds in processes started with the "forkserver"
method. A child process would inherit as many fds as the number of
still-running children.

@item 
bpo-29403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29403}: Fix @code{unittest.mock}'s autospec to not fail on method-bound
builtin functions.  Patch by Aaron Gallagher.

@item 
bpo-30961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30961}: Fix decrementing a borrowed reference in tracemalloc.

@item 
bpo-19896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19896}: Fix multiprocessing.sharedctypes to recognize typecodes @code{'q'}
and @code{'Q'}.

@item 
bpo-30946@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30946}: Remove obsolete code in readline module for platforms where GNU
readline is older than 2.1 or where select() is not available.

@item 
bpo-25684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25684}: Change @code{ttk.OptionMenu} radiobuttons to be unique across
instances of @code{OptionMenu}.

@item 
bpo-30886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30886}: Fix multiprocessing.Queue.join_thread(): it now waits until the
thread completes, even if the thread was started by the same process which
created the queue.

@item 
bpo-29854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29854}: Fix segfault in readline when using readline's history-size
option.  Patch by Nir Soffer.

@item 
bpo-30794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30794}: Added multiprocessing.Process.kill method to terminate using
the SIGKILL signal on Unix.

@item 
bpo-30319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30319}: socket.close() now ignores ECONNRESET error.

@item 
bpo-30828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30828}: Fix out of bounds write in
@code{asyncio.CFuture.remove_done_callback()}.

@item 
bpo-30302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30302}: Use keywords in the @code{repr} of @code{datetime.timedelta}.

@item 
bpo-30807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30807}: signal.setitimer() may disable the timer when passed a tiny
value. Tiny values (such as 1e-6) are valid non-zero values for
setitimer(), which is specified as taking microsecond-resolution
intervals. However, on some platform, our conversion routine could convert
1e-6 into a zero interval, therefore disabling the timer instead of
(re-)scheduling it.

@item 
bpo-30441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30441}: Fix bug when modifying os.environ while iterating over it

@item 
bpo-29585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29585}: Avoid importing @code{sysconfig} from @code{site} to improve startup
speed. Python startup is about 5% faster on Linux and 30% faster on macOS.

@item 
bpo-29293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29293}: Add missing parameter "n" on
multiprocessing.Condition.notify(). The doc claims
multiprocessing.Condition behaves like threading.Condition, but its
notify() method lacked the optional "n" argument (to specify the number of
sleepers to wake up) that threading.Condition.notify() accepts.

@item 
bpo-30532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30532}: Fix email header value parser dropping folding white space in
certain cases.

@item 
bpo-30596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30596}: Add a @code{close()} method to @code{multiprocessing.Process}.

@item 
bpo-9146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9146}: Fix a segmentation fault in _hashopenssl when standard hash
functions such as md5 are not available in the linked OpenSSL library.  As
in some special FIPS-140 build environments.

@item 
bpo-29169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29169}: Update zlib to 1.2.11.

@item 
bpo-30119@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30119}: ftplib.FTP.putline() now throws ValueError on commands that
contains CR or LF. Patch by Donghee Na.

@item 
bpo-30879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30879}: os.listdir() and os.scandir() now emit bytes names when called
with bytes-like argument.

@item 
bpo-30746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30746}: Prohibited the '=' character in environment variable names in
@code{os.putenv()} and @code{os.spawn*()}.

@item 
bpo-30664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30664}: The description of a unittest subtest now preserves the order
of keyword arguments of TestCase.subTest().

@item 
bpo-21071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21071}: struct.Struct.format type is now @ref{435,,str} instead of
@ref{1bd,,bytes}.

@item 
bpo-29212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29212}: Fix concurrent.futures.thread.ThreadPoolExecutor threads to
have a non repr() based thread name by default when no thread_name_prefix
is supplied. They will now identify themselves as
"ThreadPoolExecutor-y_n".

@item 
bpo-29755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29755}: Fixed the lgettext() family of functions in the gettext module.
They now always return bytes.

@item 
bpo-30616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30616}: Functional API of enum allows to create empty enums. Patched by
Donghee Na

@item 
bpo-30038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30038}: Fix race condition between signal delivery and wakeup file
descriptor. Patch by Nathaniel Smith.

@item 
bpo-23894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23894}: lib2to3 now recognizes @code{rb'...'} and @code{f'...'} strings.

@item 
bpo-24744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24744}: pkgutil.walk_packages function now raises ValueError if `path'
is a string. Patch by Sanyam Khurana.

@item 
bpo-24484@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24484}: Avoid race condition in multiprocessing cleanup.

@item 
bpo-30589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30589}: Fix multiprocessing.Process.exitcode to return the opposite of
the signal number when the process is killed by a signal (instead of 255)
when using the "forkserver" method.

@item 
bpo-28994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28994}: The traceback no longer displayed for SystemExit raised in a
callback registered by atexit.

@item 
bpo-30508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30508}: Don't log exceptions if Task/Future "cancel()" method was
called.

@item 
bpo-30645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30645}: Fix path calculation in @code{imp.load_package()}, fixing it for
cases when a package is only shipped with bytecodes. Patch by Alexandru
Ardelean.

@item 
bpo-11822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11822}: The dis.dis() function now is able to disassemble nested code
objects.

@item 
bpo-30624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30624}: selectors does not take KeyboardInterrupt and SystemExit into
account, leaving a fd in a bad state in case of error. Patch by Giampaolo
Rodola'.

@item 
bpo-30595@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30595}: multiprocessing.Queue.get() with a timeout now polls its reader
in non-blocking mode if it succeeded to acquire the lock but the acquire
took longer than the timeout.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Updates to typing module: Add generic AsyncContextManager, add
support for ContextManager on all versions. Original PRs by Jelle Zijlstra
and Ivan Levkivskyi

@item 
bpo-30605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30605}: re.compile() no longer raises a BytesWarning when compiling a
bytes instance with misplaced inline modifier.  Patch by Roy Williams.

@item 
bpo-29870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29870}: Fix ssl sockets leaks when connection is aborted in asyncio/ssl
implementation. Patch by Michaël Sghaïer.

@item 
bpo-29743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29743}: Closing transport during handshake process leaks open socket.
Patch by Nikolay Kim

@item 
bpo-27585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27585}: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu
Sornay.

@item 
bpo-30014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30014}: modify() method of poll(), epoll() and devpoll() based classes
of selectors module is around 10% faster.  Patch by Giampaolo Rodola'.

@item 
bpo-30418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30418}: On Windows, subprocess.Popen.communicate() now also ignore
EINVAL on stdin.write() if the child process is still running but closed
the pipe.

@item 
bpo-30463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30463}: Addded empty __slots__ to abc.ABC.  This allows subclassers to
deny __dict__ and __weakref__ creation.  Patch by Aaron Hall.

@item 
bpo-30520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30520}: Loggers are now pickleable.

@item 
bpo-30557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30557}: faulthandler now correctly filters and displays exception codes
on Windows

@item 
bpo-30526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30526}: Add TextIOWrapper.reconfigure() and a
TextIOWrapper.write_through attribute.

@item 
bpo-30245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30245}: Fix possible overflow when organize struct.pack_into error
message.  Patch by Yuan Liu.

@item 
bpo-30378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30378}: Fix the problem that logging.handlers.SysLogHandler cannot
handle IPv6 addresses.

@item 
bpo-16500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16500}: Allow registering at-fork handlers.

@item 
bpo-30470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30470}: Deprecate invalid ctypes call protection on Windows.  Patch by
Mariatta Wijaya.

@item 
bpo-30414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30414}: multiprocessing.Queue._feed background running thread do not
break from main loop on exception.

@item 
bpo-30003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30003}: Fix handling escape characters in HZ codec.  Based on patch by
Ma Lin.

@item 
bpo-30149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30149}: inspect.signature() now supports callables with
variable-argument parameters wrapped with partialmethod. Patch by Donghee
Na.

@item 
bpo-30436@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30436}: importlib.find_spec() raises ModuleNotFoundError instead of
AttributeError if the specified parent module is not a package (i.e. lacks
a __path__ attribute).

@item 
bpo-30301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30301}: Fix AttributeError when using SimpleQueue.empty() under `spawn'
and `forkserver' start methods.

@item 
bpo-30375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30375}: Warnings emitted when compile a regular expression now always
point to the line in the user code.  Previously they could point into
inners of the re module if emitted from inside of groups or conditionals.

@item 
bpo-30329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30329}: imaplib and poplib now catch the Windows socket WSAEINVAL error
(code 10022) on shutdown(SHUT_RDWR): An invalid operation was attempted.
This error occurs sometimes on SSL connections.

@item 
bpo-29196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29196}: Removed previously deprecated in Python 2.4 classes Plist, Dict
and _InternalDict in the plistlib module.  Dict values in the result of
functions readPlist() and readPlistFromBytes() are now normal dicts.  You
no longer can use attribute access to access items of these dictionaries.

@item 
bpo-9850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9850}: The @code{macpath} is now deprecated and will be removed in
Python 3.8.

@item 
bpo-30299@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30299}: Compiling regular expression in debug mode on CPython now
displays the compiled bytecode in human readable form.

@item 
bpo-30048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30048}: Fixed @code{Task.cancel()} can be ignored when the task is running
coroutine and the coroutine returned without any more @code{await}.

@item 
bpo-30266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30266}: contextlib.AbstractContextManager now supports
anti-registration by setting __enter__ = None or __exit__ = None,
following the pattern introduced in bpo-25958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25958}. Patch by Jelle Zijlstra.

@item 
bpo-30340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30340}: Enhanced regular expressions optimization. This increased the
performance of matching some patterns up to 25 times.

@item 
bpo-30298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30298}: Weaken the condition of deprecation warnings for inline
modifiers. Now allowed several subsequential inline modifiers at the start
of the pattern (e.g. @code{'(?i)(?s)...'}).  In verbose mode whitespaces and
comments now are allowed before and between inline modifiers (e.g. @code{'(?x)
(?i) (?s)...'}).

@item 
bpo-30285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30285}: Optimized case-insensitive matching and searching of regular
expressions.

@item 
bpo-29990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29990}: Fix range checking in GB18030 decoder.  Original patch by Ma
Lin.

@item 
bpo-29979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29979}: rewrite cgi.parse_multipart, reusing the FieldStorage class and
making its results consistent with those of FieldStorage for
multipart/form-data requests. Patch by Pierre Quentel.

@item 
bpo-30243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30243}: Removed the __init__ methods of _json's scanner and encoder.
Misusing them could cause memory leaks or crashes.  Now scanner and
encoder objects are completely initialized in the __new__ methods.

@item 
bpo-30215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30215}: Compiled regular expression objects with the re.LOCALE flag no
longer depend on the locale at compile time.  Only the locale at matching
time affects the result of matching.

@item 
bpo-30185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30185}: Avoid KeyboardInterrupt tracebacks in forkserver helper process
when Ctrl-C is received.

@item 
bpo-30103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30103}: binascii.b2a_uu() and uu.encode() now support using @code{'`'} as
zero instead of space.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Various updates to typing module: add typing.NoReturn type, use
WrapperDescriptorType, minor bug-fixes.  Original PRs by Jim
Fasarakis-Hilliard and Ivan Levkivskyi.

@item 
bpo-30205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30205}: Fix getsockname() for unbound AF_UNIX sockets on Linux.

@item 
bpo-30228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30228}: The seek() and tell() methods of io.FileIO now set the internal
seekable attribute to avoid one syscall on open() (in buffered or text
mode).

@item 
bpo-30190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30190}: unittest's assertAlmostEqual and assertNotAlmostEqual provide a
better message in case of failure which includes the difference between
left and right arguments.  (patch by Giampaolo Rodola')

@item 
bpo-30101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30101}: Add support for curses.A_ITALIC.

@item 
bpo-29822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29822}: inspect.isabstract() now works during __init_subclass__.  Patch
by Nate Soares.

@item 
bpo-29960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29960}: Preserve generator state when _random.Random.setstate() raises
an exception. Patch by Bryan Olson.

@item 
bpo-30070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30070}: Fixed leaks and crashes in errors handling in the parser
module.

@item 
bpo-22352@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22352}: Column widths in the output of dis.dis() are now adjusted for
large line numbers and instruction offsets.

@item 
bpo-30061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30061}: Fixed crashes in IOBase methods __next__() and readlines() when
readline() or __next__() respectively return non-sizeable object. Fixed
possible other errors caused by not checking results of PyObject_Size(),
PySequence_Size(), or PyMapping_Size().

@item 
bpo-30218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30218}: Fix PathLike support for shutil.unpack_archive. Patch by Jelle
Zijlstra.

@item 
bpo-10076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10076}: Compiled regular expression and match objects in the re module
now support copy.copy() and copy.deepcopy() (they are considered atomic).

@item 
bpo-30068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30068}: _io._IOBase.readlines will check if it's closed first when hint
is present.

@item 
bpo-29694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29694}: Fixed race condition in pathlib mkdir with flags parents=True.
Patch by Armin Rigo.

@item 
bpo-29692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29692}: Fixed arbitrary unchaining of RuntimeError exceptions in
contextlib.contextmanager.  Patch by Siddharth Velankar.

@item 
bpo-26187@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26187}: Test that sqlite3 trace callback is not called multiple times
when schema is changing.  Indirectly fixed by switching to use
sqlite3_prepare_v2() in bpo-9303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9303}.  Patch by Aviv Palivoda.

@item 
bpo-30017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30017}: Allowed calling the close() method of the zip entry writer
object multiple times.  Writing to a closed writer now always produces a
ValueError.

@item 
bpo-29998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29998}: Pickling and copying ImportError now preserves name and path
attributes.

@item 
bpo-29995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29995}: re.escape() now escapes only regex special characters.

@item 
bpo-29962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29962}: Add math.remainder operation, implementing remainder as
specified in IEEE 754.

@item 
bpo-29649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29649}: Improve struct.pack_into() exception messages for problems with
the buffer size and offset.  Patch by Andrew Nester.

@item 
bpo-29654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29654}: Support If-Modified-Since HTTP header (browser cache).  Patch
by Pierre Quentel.

@item 
bpo-29931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29931}: Fixed comparison check for ipaddress.ip_interface objects.
Patch by Sanjay Sundaresan.

@item 
bpo-29953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29953}: Fixed memory leaks in the replace() method of datetime and time
objects when pass out of bound fold argument.

@item 
bpo-29942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29942}: Fix a crash in itertools.chain.from_iterable when encountering
long runs of empty iterables.

@item 
bpo-10030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10030}: Sped up reading encrypted ZIP files by 2 times.

@item 
bpo-29204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29204}: Element.getiterator() and the html parameter of XMLParser()
were deprecated only in the documentation (since Python 3.2 and 3.4
correspondingly). Now using them emits a deprecation warning.

@item 
bpo-27863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27863}: Fixed multiple crashes in ElementTree caused by race conditions
and wrong types.

@item 
bpo-25996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25996}: Added support of file descriptors in os.scandir() on Unix.
os.fwalk() is sped up by 2 times by using os.scandir().

@item 
bpo-28699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28699}: Fixed a bug in pools in multiprocessing.pool that raising an
exception at the very first of an iterable may swallow the exception or
make the program hang. Patch by Davin Potts and Xiang Zhang.

@item 
bpo-23890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23890}: unittest.TestCase.assertRaises() now manually breaks a
reference cycle to not keep objects alive longer than expected.

@item 
bpo-29901@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29901}: The zipapp module now supports general path-like objects, not
just pathlib.Path.

@item 
bpo-25803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25803}: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when
the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-29861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29861}: Release references to tasks, their arguments and their results
as soon as they are finished in multiprocessing.Pool.

@item 
bpo-19930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19930}: The mode argument of os.makedirs() no longer affects the file
permission bits of newly created intermediate-level directories.

@item 
bpo-29884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29884}: faulthandler: Restore the old sigaltstack during teardown.
Patch by Christophe Zeitouny.

@item 
bpo-25455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25455}: Fixed crashes in repr of recursive buffered file-like objects.

@item 
bpo-29800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29800}: Fix crashes in partial.__repr__ if the keys of partial.keywords
are not strings.  Patch by Michael Seifert.

@item 
bpo-8256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8256}: Fixed possible failing or crashing input() if attributes
"encoding" or "errors" of sys.stdin or sys.stdout are not set or are not
strings.

@item 
bpo-28692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28692}: Using non-integer value for selecting a plural form in gettext
is now deprecated.

@item 
bpo-26121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26121}: Use C library implementation for math functions erf() and
erfc().

@item 
bpo-29619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29619}: os.stat() and os.DirEntry.inode() now convert inode (st_ino)
using unsigned integers.

@item 
bpo-28298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28298}: Fix a bug that prevented array 'Q', 'L' and 'I' from accepting
big intables (objects that have __int__) as elements.

@item 
bpo-29645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29645}: Speed up importing the webbrowser module.
webbrowser.register() is now thread-safe.

@item 
bpo-28231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28231}: The zipfile module now accepts path-like objects for external
paths.

@item 
bpo-26915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26915}: index() and count() methods of collections.abc.Sequence now
check identity before checking equality when do comparisons.

@item 
bpo-28682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28682}: Added support for bytes paths in os.fwalk().

@item 
bpo-29728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29728}: Add new @code{socket.TCP_NOTSENT_LOWAT} (Linux 3.12)
constant. Patch by Nathaniel J. Smith.

@item 
bpo-29623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29623}: Allow use of path-like object as a single argument in
ConfigParser.read(). Patch by David Ellis.

@item 
bpo-9303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9303}: Migrate sqlite3 module to _v2 API.  Patch by Aviv Palivoda.

@item 
bpo-28963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28963}: Fix out of bound iteration in
asyncio.Future.remove_done_callback implemented in C.

@item 
bpo-29704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29704}: asyncio.subprocess.SubprocessStreamProtocol no longer closes
before all pipes are closed.

@item 
bpo-29271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29271}: Fix Task.current_task and Task.all_tasks implemented in C to
accept None argument as their pure Python implementation.

@item 
bpo-29703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29703}: Fix asyncio to support instantiation of new event loops in
child processes.

@item 
bpo-29615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29615}: SimpleXMLRPCDispatcher no longer chains KeyError (or any other
exception) to exception(s) raised in the dispatched methods. Patch by Petr
Motejlek.

@item 
bpo-7769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7769}: Method register_function() of
xmlrpc.server.SimpleXMLRPCDispatcher and its subclasses can now be used as
a decorator.

@item 
bpo-29376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29376}: Fix assertion error in threading._DummyThread.is_alive().

@item 
bpo-28624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28624}: Add a test that checks that cwd parameter of Popen() accepts
PathLike objects.  Patch by Sayan Chowdhury.

@item 
bpo-28518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28518}: Start a transaction implicitly before a DML statement. Patch by
Aviv Palivoda.

@item 
bpo-29742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29742}: get_extra_info() raises exception if get called on closed ssl
transport. Patch by Nikolay Kim.

@item 
bpo-16285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16285}: urllib.parse.quote is now based on RFC 3986 and hence includes
'~' in the set of characters that is not quoted by default. Patch by
Christian Theune and Ratnadeep Debnath.

@item 
bpo-29532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29532}: Altering a kwarg dictionary passed to functools.partial() no
longer affects a partial object after creation.

@item 
bpo-29110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29110}: Fix file object leak in aifc.open() when file is given as a
filesystem path and is not in valid AIFF format. Patch by Anthony Zhang.

@item 
bpo-22807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22807}: Add uuid.SafeUUID and uuid.UUID.is_safe to relay information
from the platform about whether generated UUIDs are generated with a
multiprocessing safe method.

@item 
bpo-29576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29576}: Improve some deprecations in importlib. Some deprecated methods
now emit DeprecationWarnings and have better descriptive messages.

@item 
bpo-29534@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29534}: Fixed different behaviour of Decimal.from_float() for _decimal
and _pydecimal. Thanks Andrew Nester.

@item 
bpo-10379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10379}: locale.format_string now supports the 'monetary' keyword
argument, and locale.format is deprecated.

@item 
bpo-29851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29851}: importlib.reload() now raises ModuleNotFoundError if the module
lacks a spec.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Various updates to typing module: typing.Counter,
typing.ChainMap, improved ABC caching, etc. Original PRs by Jelle
Zijlstra, Ivan Levkivskyi, Manuel Krebber, and Łukasz Langa.

@item 
bpo-29100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29100}: Fix datetime.fromtimestamp() regression introduced in Python
3.6.0: check minimum and maximum years.

@item 
bpo-29416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29416}: Prevent infinite loop in pathlib.Path.mkdir

@item 
bpo-29444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29444}: Fixed out-of-bounds buffer access in the group() method of the
match object. Based on patch by WGH.

@item 
bpo-29377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29377}: Add WrapperDescriptorType, MethodWrapperType, and
MethodDescriptorType built-in types to types module. Original patch by
Manuel Krebber.

@item 
bpo-29218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29218}: Unused install_misc command is now removed.  It has been
documented as unused since 2000.  Patch by Eric N. Vander Weele.

@item 
bpo-29368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29368}: The extend() method is now called instead of the append()
method when unpickle collections.deque and other list-like objects. This
can speed up unpickling to 2 times.

@item 
bpo-29338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29338}: The help of a builtin or extension class now includes the
constructor signature if __text_signature__ is provided for the class.

@item 
bpo-29335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29335}: Fix subprocess.Popen.wait() when the child process has exited
to a stopped instead of terminated state (ex: when under ptrace).

@item 
bpo-29290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29290}: Fix a regression in argparse that help messages would wrap at
non-breaking spaces.

@item 
bpo-28735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28735}: Fixed the comparison of mock.MagickMock with mock.ANY.

@item 
bpo-29197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29197}: Removed deprecated function ntpath.splitunc().

@item 
bpo-29210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29210}: Removed support of deprecated argument "exclude" in
tarfile.TarFile.add().

@item 
bpo-29219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29219}: Fixed infinite recursion in the repr of uninitialized
ctypes.CDLL instances.

@item 
bpo-29192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29192}: Removed deprecated features in the http.cookies module.

@item 
bpo-29193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29193}: A format string argument for string.Formatter.format() is now
positional-only.

@item 
bpo-29195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29195}: Removed support of deprecated undocumented keyword arguments in
methods of regular expression objects.

@item 
bpo-28969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28969}: Fixed race condition in C implementation of
functools.lru_cache. KeyError could be raised when cached function with
full cache was simultaneously called from different threads with the same
uncached arguments.

@item 
bpo-20804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20804}: The unittest.mock.sentinel attributes now preserve their
identity when they are copied or pickled.

@item 
bpo-29142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29142}: In urllib.request, suffixes in no_proxy environment variable
with leading dots could match related hostnames again (e.g. .b.c matches
a.b.c). Patch by Milan Oberkirch.

@item 
bpo-28961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28961}: Fix unittest.mock._Call helper: don't ignore the name parameter
anymore. Patch written by Jiajun Huang.

@item 
bpo-15812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15812}: inspect.getframeinfo() now correctly shows the first line of a
context. Patch by Sam Breese.

@item 
bpo-28985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28985}: Update authorizer constants in sqlite3 module. Patch by
Dingyuan Wang.

@item 
bpo-29079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29079}: Prevent infinite loop in pathlib.resolve() on Windows

@item 
bpo-13051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13051}: Fixed recursion errors in large or resized
curses.textpad.Textbox.  Based on patch by Tycho Andersen.

@item 
bpo-9770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9770}: curses.ascii predicates now work correctly with negative
integers.

@item 
bpo-28427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28427}: old keys should not remove new values from WeakValueDictionary
when collecting from another thread.

@item 
bpo-28923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28923}: Remove editor artifacts from Tix.py.

@item 
bpo-28871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28871}: Fixed a crash when deallocate deep ElementTree.

@item 
bpo-19542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19542}: Fix bugs in WeakValueDictionary.setdefault() and
WeakValueDictionary.pop() when a GC collection happens in another thread.

@item 
bpo-20191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20191}: Fixed a crash in resource.prlimit() when passing a sequence
that doesn't own its elements as limits.

@item 
bpo-16255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16255}: subprocess.Popen uses /system/bin/sh on Android as the shell,
instead of /bin/sh.

@item 
bpo-28779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28779}: multiprocessing.set_forkserver_preload() would crash the
forkserver process if a preloaded module instantiated some multiprocessing
objects such as locks.

@item 
bpo-26937@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26937}: The chown() method of the tarfile.TarFile class does not fail
now when the grp module cannot be imported, as for example on Android
platforms.

@item 
bpo-28847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28847}: dbm.dumb now supports reading read-only files and no longer
writes the index file when it is not changed.  A deprecation warning is
now emitted if the index file is missed and recreated in the 'r' and 'w'
modes (will be an error in future Python releases).

@item 
bpo-27030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27030}: Unknown escapes consisting of @code{'\'} and an ASCII letter in
re.sub() replacement templates regular expressions now are errors.

@item 
bpo-28835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28835}: Fix a regression introduced in warnings.catch_warnings(): call
warnings.showwarning() if it was overridden inside the context manager.

@item 
bpo-27172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27172}: To assist with upgrades from 2.7, the previously documented
deprecation of @code{inspect.getfullargspec()} has been reversed. This
decision may be revisited again after the Python 2.7 branch is no longer
officially supported.

@item 
bpo-28740@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28740}: Add sys.getandroidapilevel(): return the build time API version
of Android as an integer. Function only available on Android.

@item 
bpo-26273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26273}: Add new @code{socket.TCP_CONGESTION} (Linux 2.6.13) and
@code{socket.TCP_USER_TIMEOUT} (Linux 2.6.37) constants. Patch written
by Omar Sandoval.

@item 
bpo-28752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28752}: Restored the __reduce__() methods of datetime objects.

@item 
bpo-28727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28727}: Regular expression patterns, _sre.SRE_Pattern objects created
by re.compile(), become comparable (only x==y and x!=y operators). This
change should fix the bpo-18383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18383}: don't duplicate warning filters when
the warnings module is reloaded (thing usually only done in unit tests).

@item 
bpo-20572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20572}: Remove the subprocess.Popen.wait endtime parameter.  It was
deprecated in 3.4 and undocumented prior to that.

@item 
bpo-25659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25659}: In ctypes, prevent a crash calling the from_buffer() and
from_buffer_copy() methods on abstract classes like Array.

@item 
bpo-28548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28548}: In the "http.server" module, parse the protocol version if
possible, to avoid using HTTP 0.9 in some error responses.

@item 
bpo-19717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19717}: Makes Path.resolve() succeed on paths that do not exist. Patch
by Vajrasky Kok

@item 
bpo-28563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28563}: Fixed possible DoS and arbitrary code execution when handle
plural form selections in the gettext module.  The expression parser now
supports exact syntax supported by GNU gettext.

@item 
bpo-28387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28387}: Fixed possible crash in _io.TextIOWrapper deallocator when the
garbage collector is invoked in other thread.  Based on patch by Sebastian
Cufre.

@item 
bpo-27517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27517}: LZMA compressor and decompressor no longer raise exceptions if
given empty data twice.  Patch by Benjamin Fogle.

@item 
bpo-28549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28549}: Fixed segfault in curses's addch() with ncurses6.

@item 
bpo-28449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28449}: tarfile.open() with mode "r" or "r:" now tries to open a tar
file with compression before trying to open it without compression.
Otherwise it had 50% chance failed with ignore_zeros=True.

@item 
bpo-23262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23262}: The webbrowser module now supports Firefox 36+ and derived
browsers.  Based on patch by Oleg Broytman.

@item 
bpo-24241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24241}: The webbrowser in an X environment now prefers using the
default browser directly. Also, the webbrowser register() function now has
a documented 'preferred' argument, to specify browsers to be returned by
get() with no arguments. Patch by David Steele

@item 
bpo-27939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27939}: Fixed bugs in tkinter.ttk.LabeledScale and tkinter.Scale caused
by representing the scale as float value internally in Tk.  tkinter.IntVar
now works if float value is set to underlying Tk variable.

@item 
bpo-28255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28255}: calendar.TextCalendar.prweek() no longer prints a space after a
weeks's calendar.  calendar.TextCalendar.pryear() no longer prints
redundant newline after a year's calendar.  Based on patch by Xiang Zhang.

@item 
bpo-28255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28255}: calendar.TextCalendar.prmonth() no longer prints a space at the
start of new line after printing a month's calendar.  Patch by Xiang
Zhang.

@item 
bpo-20491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20491}: The textwrap.TextWrapper class now honors non-breaking spaces.
Based on patch by Kaarle Ritvanen.

@item 
bpo-28353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28353}: os.fwalk() no longer fails on broken links.

@item 
bpo-28430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28430}: Fix iterator of C implemented asyncio.Future doesn't accept
non-None value is passed to it.send(val).

@item 
bpo-27025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27025}: Generated names for Tkinter widgets now start by the "!" prefix
for readability.

@item 
bpo-25464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25464}: Fixed HList.header_exists() in tkinter.tix module by addin a
workaround to Tix library bug.

@item 
bpo-28488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28488}: shutil.make_archive() no longer adds entry "./" to ZIP archive.

@item 
bpo-25953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25953}: re.sub() now raises an error for invalid numerical group
reference in replacement template even if the pattern is not found in the
string.  Error message for invalid group reference now includes the group
index and the position of the reference. Based on patch by SilentGhost.

@item 
bpo-28469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28469}: timeit now uses the sequence 1, 2, 5, 10, 20, 50,... instead of
1, 10, 100,... for autoranging.

@item 
bpo-28115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28115}: Command-line interface of the zipfile module now uses argparse.
Added support of long options.

@item 
bpo-18219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18219}: Optimize csv.DictWriter for large number of columns. Patch by
Mariatta Wijaya.

@item 
bpo-28448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28448}: Fix C implemented asyncio.Future didn't work on Windows.

@item 
bpo-23214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23214}: In the "io" module, the argument to BufferedReader and
BytesIO's read1() methods is now optional and can be -1, matching the
BufferedIOBase specification.

@item 
bpo-28480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28480}: Fix error building socket module when multithreading is
disabled.

@item 
bpo-28240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28240}: timeit: remove @code{-c/--clock} and @code{-t/--time} command line
options which were deprecated since Python 3.3.

@item 
bpo-28240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28240}: timeit now repeats the benchmarks 5 times instead of only 3 to
make benchmarks more reliable.

@item 
bpo-28240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28240}: timeit autorange now uses a single loop iteration if the
benchmark takes less than 10 seconds, instead of 10 iterations. "python3
-m timeit -s 'import time' 'time.sleep(1)'" now takes 4 seconds instead of
40 seconds.

@item 
Distutils.sdist now looks for README and setup.py files with case
sensitivity. This behavior matches that found in Setuptools 6.0 and later.
See setuptools 100@footnote{https://github.com/pypa/setuptools/issues/100} for
rationale.

@item 
bpo-24452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24452}: Make webbrowser support Chrome on Mac OS X. Patch by Ned
Batchelder.

@item 
bpo-20766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20766}: Fix references leaked by pdb in the handling of SIGINT
handlers.

@item 
bpo-27998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27998}: Fixed bytes path support in os.scandir() on Windows. Patch by
Eryk Sun.

@item 
bpo-28317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28317}: The disassembler now decodes FORMAT_VALUE argument.

@item 
bpo-28380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28380}: unittest.mock Mock autospec functions now properly support
assert_called, assert_not_called, and assert_called_once.

@item 
bpo-28229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28229}: lzma module now supports pathlib.

@item 
bpo-28321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28321}: Fixed writing non-BMP characters with binary format in
plistlib.

@item 
bpo-28225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28225}: bz2 module now supports pathlib.  Initial patch by Ethan
Furman.

@item 
bpo-28227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28227}: gzip now supports pathlib.  Patch by Ethan Furman.

@item 
bpo-28332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28332}: Deprecated silent truncations in socket.htons and socket.ntohs.
Original patch by Oren Milman.

@item 
bpo-27358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27358}: Optimized merging var-keyword arguments and improved error
message when passing a non-mapping as a var-keyword argument.

@item 
bpo-28257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28257}: Improved error message when passing a non-iterable as a
var-positional argument.  Added opcode BUILD_TUPLE_UNPACK_WITH_CALL.

@item 
bpo-28322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28322}: Fixed possible crashes when unpickle itertools objects from
incorrect pickle data.  Based on patch by John Leitch.

@item 
bpo-28228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28228}: imghdr now supports pathlib.

@item 
bpo-28226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28226}: compileall now supports pathlib.

@item 
bpo-28314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28314}: Fix function declaration (C flags) for the getiterator() method
of xml.etree.ElementTree.Element.

@item 
bpo-28148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28148}: Stop using localtime() and gmtime() in the time module.
Introduced platform independent _PyTime_localtime API that is similar to
POSIX localtime_r, but available on all platforms.  Patch by Ed Schouten.

@item 
bpo-28253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28253}: Fixed calendar functions for extreme months: 0001-01 and
9999-12. Methods itermonthdays() and itermonthdays2() are reimplemented so
that they don't call itermonthdates() which can cause datetime.date
under/overflow.

@item 
bpo-28275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28275}: Fixed possible use after free in the decompress() methods of
the LZMADecompressor and BZ2Decompressor classes. Original patch by John
Leitch.

@item 
bpo-27897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27897}: Fixed possible crash in sqlite3.Connection.create_collation()
if pass invalid string-like object as a name.  Patch by Xiang Zhang.

@item 
bpo-18844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18844}: random.choices() now has k as a keyword-only argument to
improve the readability of common cases and come into line with the
signature used in other languages.

@item 
bpo-18893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18893}: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py.
Patch by Madison May.

@item 
bpo-27611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27611}: Fixed support of default root window in the tkinter.tix module.
Added the master parameter in the DisplayStyle constructor.

@item 
bpo-27348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27348}: In the traceback module, restore the formatting of exception
messages like "Exception: None".  This fixes a regression introduced in
3.5a2.

@item 
bpo-25651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25651}: Allow false values to be used for msg parameter of subTest().

@item 
bpo-27778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27778}: Fix a memory leak in os.getrandom() when the getrandom() is
interrupted by a signal and a signal handler raises a Python exception.

@item 
bpo-28200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28200}: Fix memory leak on Windows in the os module (fix
path_converter() function).

@item 
bpo-25400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25400}: RobotFileParser now correctly returns default values for
crawl_delay and request_rate.  Initial patch by Peter Wirtz.

@item 
bpo-27932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27932}: Prevent memory leak in win32_ver().

@item 
Fix UnboundLocalError in socket._sendfile_use_sendfile.

@item 
bpo-28075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28075}: Check for ERROR_ACCESS_DENIED in Windows implementation of
os.stat().  Patch by Eryk Sun.

@item 
bpo-22493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22493}: Warning message emitted by using inline flags in the middle of
regular expression now contains a (truncated) regex pattern. Patch by Tim
Graham.

@item 
bpo-25270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25270}: Prevent codecs.escape_encode() from raising SystemError when an
empty bytestring is passed.

@item 
bpo-28181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28181}: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

@item 
bpo-25895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25895}: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by
Gergely Imreh and Markus Holtermann.

@item 
bpo-28114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28114}: Fix a crash in parse_envlist() when env contains byte strings.
Patch by Eryk Sun.

@item 
bpo-27599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27599}: Fixed buffer overrun in binascii.b2a_qp() and
binascii.a2b_qp().

@item 
bpo-27906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27906}: Fix socket accept exhaustion during high TCP traffic. Patch by
Kevin Conway.

@item 
bpo-28174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28174}: Handle when SO_REUSEPORT isn't properly supported. Patch by
Seth Michael Larson.

@item 
bpo-26654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26654}: Inspect functools.partial in asyncio.Handle.__repr__. Patch by
iceboy.

@item 
bpo-26909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26909}: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

@item 
bpo-28176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28176}: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

@item 
bpo-27759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27759}: Fix selectors incorrectly retain invalid file descriptors.
Patch by Mark Williams.

@item 
bpo-28325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28325}: Remove vestigial MacOS 9 macurl2path module and its tests.

@item 
bpo-28368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28368}: Refuse monitoring processes if the child watcher has no loop
attached. Patch by Vincent Michel.

@item 
bpo-28369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28369}: Raise RuntimeError when transport's FD is used with add_reader,
add_writer, etc.

@item 
bpo-28370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28370}: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг
Марк.

@item 
bpo-28371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28371}: Deprecate passing asyncio.Handles to run_in_executor.

@item 
bpo-28372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28372}: Fix asyncio to support formatting of non-python coroutines.

@item 
bpo-28399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28399}: Remove UNIX socket from FS before binding. Patch by Коренберг
Марк.

@item 
bpo-27972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27972}: Prohibit Tasks to await on themselves.

@item 
bpo-24142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24142}: Reading a corrupt config file left configparser in an invalid
state. Original patch by Florian Höch.

@item 
bpo-29581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29581}: ABCMeta.__new__ now accepts @code{**kwargs}, allowing abstract
base classes to use keyword parameters in __init_subclass__. Patch by Nate
Soares.

@item 
bpo-25532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25532}: inspect.unwrap() will now only try to unwrap an object
sys.getrecursionlimit() times, to protect against objects which create a
new object on every attribute access.

@item 
bpo-30177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30177}: path.resolve(strict=False) no longer cuts the path after the
first element not present in the filesystem.  Patch by Antoine Pietri.
@end itemize

@node Documentation<56>,Tests<56>,Library<62>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id545}@anchor{1a46}
@subsubsection Documentation



@itemize -

@item 
bpo-31294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31294}: Fix incomplete code snippet in the ZeroMQSocketListener and
ZeroMQSocketHandler examples and adapt them to Python 3.

@item 
bpo-21649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21649}: Add RFC 7525 and Mozilla server side TLS links to SSL
documentation.

@item 
bpo-31128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31128}: Allow the pydoc server to bind to arbitrary hostnames.

@item 
bpo-30803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30803}: Clarify doc on truth value testing. Original patch by Peter
Thomassen.

@item 
bpo-30176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30176}: Add missing attribute related constants in curses
documentation.

@item 
bpo-30052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30052}: the link targets for @ref{1bd,,bytes()} and @ref{528,,bytearray()} are
now their respective type definitions, rather than the corresponding
builtin function entries. Use @ref{1a47,,bytes} and
@ref{1a48,,bytearray} to reference the latter. In order to
ensure this and future cross-reference updates are applied automatically,
the daily documentation builds now disable the default output caching
features in Sphinx.

@item 
bpo-26985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26985}: Add missing info of code object in inspect documentation.

@item 
bpo-19824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19824}: Improve the documentation for, and links to, template strings
by emphasizing their utility for internationalization, and by clarifying
some usage constraints. (See also: bpo-20314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20314}, bpo-12518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12518})

@item 
bpo-28929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28929}: Link the documentation to its source file on GitHub.

@item 
bpo-25008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25008}: Document smtpd.py as effectively deprecated and add a pointer
to aiosmtpd, a third-party asyncio-based replacement.

@item 
bpo-26355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26355}: Add canonical header link on each page to corresponding major
version of the documentation. Patch by Matthias Bussonnier.

@item 
bpo-29349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29349}: Fix Python 2 syntax in code for building the documentation.

@item 
bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}: The data model reference and the porting section in the 3.6
What's New guide now cover the additional @code{__classcell__} handling
needed for custom metaclasses to fully support 
@geindex Python Enhancement Proposals; PEP 487
PEP 487@footnote{https://peps.python.org/pep-0487/} and
zero-argument @code{super()}.

@item 
bpo-28513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28513}: Documented command-line interface of zipfile.
@end itemize

@node Tests<56>,Build<59>,Documentation<56>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id546}@anchor{1a49}
@subsubsection Tests



@itemize -

@item 
bpo-29639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29639}: test.support.HOST is now "localhost", a new HOSTv4 constant has
been added for your @code{127.0.0.1} needs, similar to the existing HOSTv6
constant.

@item 
bpo-31320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31320}: Silence traceback in test_ssl

@item 
bpo-31346@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31346}: Prefer PROTOCOL_TLS_CLIENT and PROTOCOL_TLS_SERVER protocols
for SSLContext.

@item 
bpo-25674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25674}: Remove sha256.tbs-internet.com ssl test

@item 
bpo-30715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30715}: Address ALPN callback changes for OpenSSL 1.1.0f. The latest
version behaves like OpenSSL 1.0.2 and no longer aborts handshake.

@item 
bpo-30822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30822}: regrtest: Exclude tzdata from regrtest --all. When running the
test suite using --use=all / -u all, exclude tzdata since it makes
test_datetime too slow (15-20 min on some buildbots) which then times out
on some buildbots. Fix also regrtest command line parser to allow passing
-u extralargefile to run test_zipfile64.

@item 
bpo-30695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30695}: Add the @code{set_nomemory(start, stop)} and
@code{remove_mem_hooks()} functions to the @code{_testcapi} module.

@item 
bpo-30357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30357}: test_thread: setUp() now uses support.threading_setup() and
support.threading_cleanup() to wait until threads complete to avoid random
side effects on following tests. Initial patch written by Grzegorz
Grzywacz.

@item 
bpo-30197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30197}: Enhanced functions swap_attr() and swap_item() in the
test.support module. They now work when delete replaced attribute or item
inside the with statement.  The old value of the attribute or item (or
None if it doesn't exist) now will be assigned to the target of the "as"
clause, if there is one.

@item 
bpo-24932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24932}: Use proper command line parsing in _testembed

@item 
bpo-28950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28950}: Disallow -j0 to be combined with -T/-l in regrtest command line
arguments.

@item 
bpo-28683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28683}: Fix the tests that bind() a unix socket and raise
PermissionError on Android for a non-root user.

@item 
bpo-26936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26936}: Fix the test_socket failures on Android - getservbyname(),
getservbyport() and getaddrinfo() are broken on some Android API levels.

@item 
bpo-28666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28666}: Now test.support.rmtree is able to remove unwritable or
unreadable directories.

@item 
bpo-23839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23839}: Various caches now are cleared before running every test file.

@item 
bpo-26944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26944}: Fix test_posix for Android where 'id -G' is entirely wrong or
missing the effective gid.

@item 
bpo-28409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28409}: regrtest: fix the parser of command line arguments.

@item 
bpo-28217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28217}: Adds _testconsole module to test console input.

@item 
bpo-26939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26939}: Add the support.setswitchinterval() function to fix
test_functools hanging on the Android armv7 qemu emulator.
@end itemize

@node Build<59>,Windows<54>,Tests<56>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id547}@anchor{1a4a}
@subsubsection Build



@itemize -

@item 
bpo-31354@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31354}: Allow @code{--with-lto} to be used on all builds, not just @code{make
profile-opt}.

@item 
bpo-31370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31370}: Remove support for building --without-threads. This option is
not really useful anymore in the 21st century. Removing lots of
conditional paths allows us to simplify the code base, including in
difficult to maintain low-level internal code.

@item 
bpo-31341@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31341}: Per 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}, support for the IRIX operating system was
removed.

@item 
bpo-30854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30854}: Fix compile error when compiling --without-threads. Patch by
Masayuki Yamamoto.

@item 
bpo-30687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30687}: Locate msbuild.exe on Windows when building rather than
vcvarsall.bat

@item 
bpo-20210@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20210}: Support the `disabled' marker in Setup files. Extension modules
listed after this marker are not built at all, neither by the Makefile nor
by setup.py.

@item 
bpo-29941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29941}: Add @code{--with-assertions} configure flag to explicitly enable C
@code{assert()} checks. Defaults to off. @code{--with-pydebug} implies
@code{--with-assertions}.

@item 
bpo-28787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28787}: Fix out-of-tree builds of Python when configured with
@code{--with--dtrace}.

@item 
bpo-29243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29243}: Prevent unnecessary rebuilding of Python during @code{make test},
@code{make install} and some other make targets when configured with
@code{--enable-optimizations}.

@item 
bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}: Don't regenerate generated files based on file modification
time anymore: the action is now explicit. Replace @code{make touch} with
@code{make regen-all}.

@item 
bpo-29643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29643}: Fix @code{--enable-optimization} didn't work.

@item 
bpo-27593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27593}: sys.version and the platform module python_build(),
python_branch(), and python_revision() functions now use git information
rather than hg when building from a repo.

@item 
bpo-29572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29572}: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

@item 
bpo-27659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27659}: Prohibit implicit C function declarations: use
@code{-Werror=implicit-function-declaration} when possible (GCC and Clang,
but it depends on the compiler version). Patch written by Chi Hsuan Yen.

@item 
bpo-29384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29384}: Remove old Be OS helper scripts.

@item 
bpo-26851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26851}: Set Android compilation and link flags.

@item 
bpo-28768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28768}: Fix implicit declaration of function _setmode. Patch by
Masayuki Yamamoto

@item 
bpo-29080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29080}: Removes hard dependency on hg.exe from PCBuild/build.bat

@item 
bpo-23903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23903}: Added missed names to PC/python3.def.

@item 
bpo-28762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28762}: lockf() is available on Android API level 24, but the F_LOCK
macro is not defined in android-ndk-r13.

@item 
bpo-28538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28538}: Fix the compilation error that occurs because if_nameindex() is
available on Android API level 24, but the if_nameindex structure is not
defined.

@item 
bpo-20211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20211}: Do not add the directory for installing C header files and the
directory for installing object code libraries to the cross compilation
search paths. Original patch by Thomas Petazzoni.

@item 
bpo-28849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28849}: Do not define sys.implementation._multiarch on Android.

@item 
bpo-10656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10656}: Fix out-of-tree building on AIX.  Patch by Tristan Carel and
Michael Haubenwallner.

@item 
bpo-26359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26359}: Rename --with-optimiations to --enable-optimizations.

@item 
bpo-28444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28444}: Fix missing extensions modules when cross compiling.

@item 
bpo-28208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28208}: Update Windows build and OS X installers to use SQLite 3.14.2.

@item 
bpo-28248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28248}: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

@item 
bpo-21124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21124}: Fix building the _struct module on Cygwin by passing @code{NULL}
instead of @code{&PyType_Type} to PyVarObject_HEAD_INIT.  Patch by Masayuki
Yamamoto.

@item 
bpo-13756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13756}: Fix building extensions modules on Cygwin.  Patch by Roumen
Petrov, based on original patch by Jason Tishler.

@item 
bpo-21085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21085}: Add configure check for siginfo_t.si_band, which Cygwin does
not provide. Patch by Masayuki Yamamoto with review and rebase by Erik
Bray.

@item 
bpo-28258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28258}: Fixed build with Estonian locale (python-config and distclean
targets in Makefile).  Patch by Arfrever Frehtes Taifersar Arahesis.

@item 
bpo-26661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26661}: setup.py now detects system libffi with multiarch wrapper.

@item 
bpo-27979@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27979}: A full copy of libffi is no longer bundled for use when
building _ctypes on non-OSX UNIX platforms.  An installed copy of libffi
is now required when building _ctypes on such platforms.

@item 
bpo-15819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15819}: Remove redundant include search directory option for building
outside the source tree.

@item 
bpo-28676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28676}: Prevent missing 'getentropy' declaration warning on macOS.
Patch by Gareth Rees.
@end itemize

@node Windows<54>,IDLE<45>,Build<59>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id548}@anchor{1a4b}
@subsubsection Windows



@itemize -

@item 
bpo-31392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31392}: Update Windows build to use OpenSSL 1.1.0f

@item 
bpo-30389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30389}: Adds detection of Visual Studio 2017 to distutils on Windows.

@item 
bpo-31358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31358}: zlib is no longer bundled in the CPython source, instead it is
downloaded on demand just like bz2, lzma, OpenSSL, Tcl/Tk, and SQLite.

@item 
bpo-31340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31340}: Change to building with MSVC v141 (included with Visual Studio
2017)

@item 
bpo-30581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30581}: os.cpu_count() now returns the correct number of processors on
Windows when the number of logical processors is greater than 64.

@item 
bpo-30916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30916}: Pre-build OpenSSL, Tcl and Tk and include the binaries in the
build.

@item 
bpo-30731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30731}: Add a missing xmlns to python.manifest so that it matches the
schema.

@item 
bpo-30291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30291}: Allow requiring 64-bit interpreters from py.exe using -64
suffix. Contributed by Steve (Gadget) Barnes.

@item 
bpo-30362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30362}: Adds list options (-0, -0p) to py.exe launcher. Contributed by
Steve Barnes.

@item 
bpo-23451@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23451}: Fix socket deprecation warnings in socketmodule.c. Patch by
Segev Finer.

@item 
bpo-30450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30450}: The build process on Windows no longer depends on Subversion,
instead pulling external code from GitHub via a Python script.  If Python
3.6 is not found on the system (via @code{py -3.6}), NuGet is used to
download a copy of 32-bit Python.

@item 
bpo-29579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29579}: Removes readme.txt from the installer.

@item 
bpo-25778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25778}: winreg does not truncate string correctly (Patch by Eryk Sun)

@item 
bpo-28896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28896}: Deprecate WindowsRegistryFinder and disable it by default

@item 
bpo-28522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28522}: Fixes mishandled buffer reallocation in getpathp.c

@item 
bpo-28402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28402}: Adds signed catalog files for stdlib on Windows.

@item 
bpo-28333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28333}: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk
Sun)

@item 
bpo-28251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28251}: Improvements to help manuals on Windows.

@item 
bpo-28110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28110}: launcher.msi has different product codes between 32-bit and
64-bit

@item 
bpo-28161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28161}: Opening CON for write access fails

@item 
bpo-28162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28162}: WindowsConsoleIO readall() fails if first line starts with
Ctrl+Z

@item 
bpo-28163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28163}: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle

@item 
bpo-28164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28164}: _PyIO_get_console_type fails for various paths

@item 
bpo-28137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28137}: Renames Windows path file to ._pth

@item 
bpo-28138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28138}: Windows ._pth file should allow import site
@end itemize

@node IDLE<45>,Tools/Demos<31>,Windows<54>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id549}@anchor{1a4c}
@subsubsection IDLE



@itemize -

@item 
bpo-31493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31493}: IDLE code context -- fix code update and font update timers.
Canceling timers prevents a warning message when test_idle completes.

@item 
bpo-31488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31488}: IDLE - Update non-key options in former extension classes. When
applying configdialog changes, call .reload for each feature class. Change
ParenMatch so updated options affect existing instances attached to
existing editor windows.

@item 
bpo-31477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31477}: IDLE - Improve rstrip entry in doc. Strip trailing whitespace
strips more than blank spaces.  Multiline string literals are not skipped.

@item 
bpo-31480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31480}: IDLE - make tests pass with zzdummy extension disabled by
default.

@item 
bpo-31421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31421}: Document how IDLE runs tkinter programs. IDLE calls tcl/tk
update in the background in order to make live interaction and
experimentation with tkinter applications much easier.

@item 
bpo-31414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31414}: IDLE -- fix tk entry box tests by deleting first. Adding to an
int entry is not the same as deleting and inserting because int('@w{'}) will
fail.

@item 
bpo-31051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31051}: Rearrange IDLE configdialog GenPage into Window, Editor, and
Help sections.

@item 
bpo-30617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30617}: IDLE - Add docstrings and tests for outwin subclass of editor.
Move some data and functions from the class to module level. Patch by
Cheryl Sabella.

@item 
bpo-31287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31287}: IDLE - Do not modify tkinter.message in test_configdialog.

@item 
bpo-27099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27099}: Convert IDLE's built-in 'extensions' to regular features. About
10 IDLE features were implemented as supposedly optional extensions. Their
different behavior could be confusing or worse for users and not good for
maintenance. Hence the conversion. The main difference for users is that
user configurable key bindings for builtin features are now handled
uniformly. Now, editing a binding in a keyset only affects its value in
the keyset. All bindings are defined together in the system-specific
default keysets in config-extensions.def. All custom keysets are saved as
a whole in config-extension.cfg.  All take effect as soon as one clicks
Apply or Ok. The affected events are '<<force-open-completions>>',
'<<expand-word>>', '<<force-open-calltip>>', '<<flash-paren>>',
'<<format-paragraph>>', '<<run-module>>', '<<check-module>>', and
'<<zoom-height>>'.  Any (global) customizations made before 3.6.3 will not
affect their keyset-specific customization after 3.6.3. and vice versa.
Initial patch by Charles Wohlganger.

@item 
bpo-31206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31206}: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by
Cheryl Sabella.

@item 
bpo-31001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31001}: Add tests for configdialog highlight tab.  Patch by Cheryl
Sabella.

@item 
bpo-31205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31205}: IDLE: Factor KeysPage(Frame) class from ConfigDialog.  The
slightly modified tests continue to pass.  Patch by Cheryl Sabella.

@item 
bpo-31130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31130}: IDLE -- stop leaks in test_configdialog. Initial patch by
Victor Stinner.

@item 
bpo-31002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31002}: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

@item 
bpo-19903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19903}: IDLE: Calltips use @code{inspect.signature} instead of
@code{inspect.getfullargspec}. This improves calltips for builtins converted
to use Argument Clinic. Patch by Louie Lu.

@item 
bpo-31083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31083}: IDLE - Add an outline of a TabPage class in configdialog.
Update existing classes to match outline. Initial patch by Cheryl Sabella.

@item 
bpo-31050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31050}: Factor GenPage(Frame) class from ConfigDialog. The slightly
modified tests continue to pass. Patch by Cheryl Sabella.

@item 
bpo-31004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31004}: IDLE - Factor FontPage(Frame) class from ConfigDialog. Slightly
modified tests continue to pass. Fix General tests. Patch mostly by Cheryl
Sabella.

@item 
bpo-30781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30781}: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan
Reedy and Cheryl Sabella.

@item 
bpo-31060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31060}: IDLE - Finish rearranging methods of ConfigDialog Grouping
methods pertaining to each tab and the buttons will aid writing tests and
improving the tabs and will enable splitting the groups into classes.

@item 
bpo-30853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30853}: IDLE -- Factor a VarTrace class out of ConfigDialog. Instance
tracers manages pairs consisting of a tk variable and a callback function.
When tracing is turned on, setting the variable calls the function.  Test
coverage for the new class is 100%.

@item 
bpo-31003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31003}: IDLE: Add more tests for General tab.

@item 
bpo-30993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30993}: IDLE - Improve configdialog font page and tests. In
configdialog: Document causal pathways in create_font_tab docstring.
Simplify some attribute names. Move set_samples calls to var_changed_font
(idea from Cheryl Sabella).  Move related functions to positions after the
create widgets function. In test_configdialog: Fix test_font_set so not
order dependent.  Fix renamed test_indent_scale so it tests the widget.
Adjust tests for movement of set_samples call.  Add tests for load
functions.  Put all font tests in one class and tab indent tests in
another.  Except for two lines, these tests completely cover the related
functions.

@item 
bpo-30981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30981}: IDLE -- Add more configdialog font page tests.

@item 
bpo-28523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28523}: IDLE: replace 'colour' with 'color' in configdialog.

@item 
bpo-30917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30917}: Add tests for idlelib.config.IdleConf. Increase coverage from
46% to 96%. Patch by Louie Lu.

@item 
bpo-30934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30934}: Document coverage details for idlelib tests. Add section to
idlelib/idle-test/README.txt. Include check that branches are taken both
ways. Exclude IDLE-specific code that does not run during unit tests.

@item 
bpo-30913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30913}: IDLE: Document ConfigDialog tk Vars, methods, and widgets in
docstrings This will facilitate improving the dialog and splitting up the
class. Original patch by Cheryl Sabella.

@item 
bpo-30899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30899}: IDLE: Add tests for ConfigParser subclasses in config. Patch by
Louie Lu.

@item 
bpo-30881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30881}: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

@item 
bpo-30851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30851}: IDLE: Remove unused variables in configdialog.  One is a
duplicate, one is set but cannot be altered by users. Patch by Cheryl
Sabella.

@item 
bpo-30870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30870}: IDLE: In Settings dialog, select font with Up, Down keys as
well as mouse. Initial patch by Louie Lu.

@item 
bpo-8231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8231}: IDLE: call config.IdleConf.GetUserCfgDir only once.

@item 
bpo-30779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30779}: IDLE: Factor ConfigChanges class from configdialog, put in
config; test. * In config, put dump test code in a function; run it and
unittest in   'if __name__ == '__main__'. * Add class config.ConfigChanges
based on changes_class_v4.py on bpo issue. * Add class
test_config.ChangesTest, partly using configdialog_tests_v1.py. * Revise
configdialog to use ConfigChanges; see tracker msg297804. * Revise
test_configdialog to match configdialog changes. * Remove configdialog
functions unused or moved to ConfigChanges. Cheryl Sabella contributed
parts of the patch.

@item 
bpo-30777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30777}: IDLE: configdialog - Add docstrings and fix comments. Patch by
Cheryl Sabella.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: IDLE: Improve textview with docstrings, PEP8 names, and more
tests. Patch by Cheryl Sabella.

@item 
bpo-30723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30723}: IDLE: Make several improvements to parenmatch. Add 'parens'
style to highlight both opener and closer. Make 'default' style, which is
not default, a synonym for 'opener'. Make time-delay work the same with
all styles. Add help for config dialog extensions tab, including help for
parenmatch. Add new tests.  Original patch by Charles Wohlganger.

@item 
bpo-30674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30674}: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

@item 
bpo-21519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21519}: IDLE's basic custom key entry dialog now detects duplicates
properly. Original patch by Saimadhav Heblikar.

@item 
bpo-29910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29910}: IDLE no longer deletes a character after commenting out a
region by a key shortcut.  Add @code{return 'break'} for this and other
potential conflicts between IDLE and default key bindings.

@item 
bpo-30728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30728}: Review and change idlelib.configdialog names. Lowercase method
and attribute names. Replace 'colour' with 'color', expand overly cryptic
names, delete unneeded underscores. Replace @code{import *} with specific
imports. Patches by Cheryl Sabella.

@item 
bpo-6739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6739}: IDLE: Verify user-entered key sequences by trying to bind them
with tk. Add tests for all 3 validation functions. Original patch by G
Polo.  Tests added by Cheryl Sabella.

@item 
bpo-15786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15786}: Fix several problems with IDLE's autocompletion box. The
following should now work: clicking on selection box items; using the
scrollbar; selecting an item by hitting Return. Hangs on MacOSX should no
longer happen. Patch by Louie Lu.

@item 
bpo-25514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25514}: Add doc subsubsection about IDLE failure to start. Popup
no-connection message directs users to this section.

@item 
bpo-30642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30642}: Fix reference leaks in IDLE tests. Patches by Louie Lu and
Terry Jan Reedy.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: Add docstrings for textview.py and use PEP8 names. Patches by
Cheryl Sabella and Terry Jan Reedy.

@item 
bpo-30290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30290}: Help-about: use pep8 names and add tests. Increase coverage to
100%. Patches by Louie Lu, Cheryl Sabella, and Terry Jan Reedy.

@item 
bpo-30303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30303}: Add _utest option to textview; add new tests. Increase coverage
to 100%. Patches by Louie Lu and Terry Jan Reedy.

@item 
bpo-29071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29071}: IDLE colors f-string prefixes (but not invalid ur prefixes).

@item 
bpo-28572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28572}: Add 10% to coverage of IDLE's test_configdialog. Update and
augment description of the configuration system.
@end itemize

@node Tools/Demos<31>,C API<56>,IDLE<45>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id550}@anchor{1a4d}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-30983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30983}: gdb integration commands (py-bt, etc.) work on optimized shared
builds now, too.  
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} introduced _PyEval_EvalFrameDefault which
inlines PyEval_EvalFrameEx on non-debug shared builds.  This broke the
ability to use py-bt, py-up, and a few other Python-specific gdb
integrations. The problem is fixed by only looking for
_PyEval_EvalFrameDefault frames in python-gdb.py.  Original patch by Bruno
"Polaco" Penteado.

@item 
bpo-29748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29748}: Added the slice index converter in Argument Clinic.

@item 
bpo-24037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24037}: Argument Clinic now uses the converter @code{bool(accept=@{int@})}
rather than @code{int} for semantical booleans.  This avoids repeating the
default value for Python and C and will help in converting to @code{bool} in
future.

@item 
bpo-29367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29367}: python-gdb.py now supports also @code{method-wrapper}
(@code{wrapperobject}) objects.

@item 
bpo-28023@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28023}: Fix python-gdb.py didn't support new dict implementation.

@item 
bpo-15369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15369}: The pybench and pystone microbenchmark have been removed from
Tools. Please use the new Python benchmark suite
@indicateurl{https://github.com/python/pyperformance} which is more reliable and
includes a portable version of pybench working on Python 2 and Python 3.

@item 
bpo-28102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28102}: The zipfile module CLI now prints usage to stderr. Patch by
Stephen J. Turnbull.
@end itemize

@node C API<56>,,Tools/Demos<31>,Python 3 7 0 alpha 1
@anchor{whatsnew/changelog id551}@anchor{1a4e}
@subsubsection C API



@itemize -

@item 
bpo-31338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31338}: Added the @code{Py_UNREACHABLE()} macro for code paths which are
never expected to be reached.  This and a few other useful macros are now
documented in the C API manual.

@item 
bpo-30832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30832}: Remove own implementation for thread-local storage. CPython has
provided the own implementation for thread-local storage (TLS) on
Python/thread.c, it's used in the case which a platform has not supplied
native TLS.  However, currently all supported platforms (Windows and
pthreads) have provided native TLS and defined the Py_HAVE_NATIVE_TLS
macro with unconditional in any case.

@item 
bpo-30708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30708}: PyUnicode_AsWideCharString() now raises a ValueError if the
second argument is NULL and the wchar_t* string contains null characters.

@item 
bpo-16500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16500}: Deprecate PyOS_AfterFork() and add PyOS_BeforeFork(),
PyOS_AfterFork_Parent() and PyOS_AfterFork_Child().

@item 
bpo-6532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6532}: The type of results of PyThread_start_new_thread() and
PyThread_get_thread_ident(), and the id parameter of
PyThreadState_SetAsyncExc() changed from "long" to "unsigned long".

@item 
bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}: Function PySlice_GetIndicesEx() is deprecated and replaced with
a macro if Py_LIMITED_API is not set or set to the value between
0x03050400 and 0x03060000 (not including) or 0x03060100 or higher.  Added
functions PySlice_Unpack() and PySlice_AdjustIndices().

@item 
bpo-29083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29083}: Fixed the declaration of some public API functions.
PyArg_VaParse() and PyArg_VaParseTupleAndKeywords() were not available in
limited API. PyArg_ValidateKeywordArguments(), PyArg_UnpackTuple() and
Py_BuildValue() were not available in limited API of version < 3.3 when
PY_SSIZE_T_CLEAN is defined.

@item 
bpo-28769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28769}: The result of PyUnicode_AsUTF8AndSize() and PyUnicode_AsUTF8()
is now of type @code{const char *} rather of @code{char *}.

@item 
bpo-29058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29058}: All stable API extensions added after Python 3.2 are now
available only when Py_LIMITED_API is set to the PY_VERSION_HEX value of
the minimum Python version supporting this API.

@item 
bpo-28822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28822}: The index parameters `start' and `end' of PyUnicode_FindChar()
are now adjusted to behave like @code{str[start:end]}.

@item 
bpo-28808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28808}: PyUnicode_CompareWithASCIIString() now never raises exceptions.

@item 
bpo-28761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28761}: The fields name and doc of structures PyMemberDef, PyGetSetDef,
PyStructSequence_Field, PyStructSequence_Desc, and wrapperbase are now of
type @code{const char *} rather of @code{char *}.

@item 
bpo-28748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28748}: Private variable _Py_PackageContext is now of type @code{const char
*} rather of @code{char *}.

@item 
bpo-19569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19569}: Compiler warnings are now emitted if use most of deprecated
functions.

@item 
bpo-28426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28426}: Deprecated undocumented functions PyUnicode_AsEncodedObject(),
PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and
PyUnicode_AsEncodedUnicode().
@end itemize

@node Python 3 6 6 final,Python 3 6 6 release candidate 1,Python 3 7 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-6-6-final}@anchor{1a4f}
@subsection Python 3.6.6 final


`Release date: 2018-06-27'

There were no new changes in version 3.6.6.

@node Python 3 6 6 release candidate 1,Python 3 6 5 final,Python 3 6 6 final,Changelog
@anchor{whatsnew/changelog python-3-6-6-release-candidate-1}@anchor{1a50}
@subsection Python 3.6.6 release candidate 1


`Release date: 2018-06-11'

@menu
* Core and Builtins: Core and Builtins<63>. 
* Library: Library<63>. 
* Documentation: Documentation<57>. 
* Tests: Tests<57>. 
* Build: Build<60>. 
* Windows: Windows<55>. 
* macOS: macOS<44>. 
* IDLE: IDLE<46>. 
* Tools/Demos: Tools/Demos<32>. 
* C API: C API<57>. 

@end menu

@node Core and Builtins<63>,Library<63>,,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id552}@anchor{1a51}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-33786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33786}: Fix asynchronous generators to handle GeneratorExit in athrow()
correctly

@item 
bpo-30654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30654}: Fixed reset of the SIGINT handler to SIG_DFL on interpreter
shutdown even when there was a custom handler set previously. Patch by
Philipp Kerling.

@item 
bpo-33622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33622}: Fixed a leak when the garbage collector fails to add an object
with the @code{__del__} method or referenced by it into the
@ref{119e,,gc.garbage} list. @ref{97b,,PyGC_Collect()} can now be called when an
exception is set and preserves it.

@item 
bpo-31849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31849}: Fix signed/unsigned comparison warning in pyhash.c.

@item 
bpo-33391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33391}: Fix a leak in set_symmetric_difference().

@item 
bpo-28055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28055}: Fix unaligned accesses in siphash24(). Patch by Rolf Eike Beer.

@item 
bpo-33231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33231}: Fix potential memory leak in @code{normalizestring()}.

@item 
bpo-29922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29922}: Improved error messages in 'async with' when @code{__aenter__()}
or @code{__aexit__()} return non-awaitable object.

@item 
bpo-33199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33199}: Fix @code{ma_version_tag} in dict implementation is uninitialized
when copying from key-sharing dict.

@item 
bpo-33041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33041}: Fixed jumping when the function contains an @code{async for} loop.

@item 
bpo-32282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32282}: Fix an unnecessary ifdef in the include of VersionHelpers.h in
socketmodule on Windows.

@item 
bpo-21983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21983}: Fix a crash in @code{ctypes.cast()} in case the type argument is a
ctypes structured data type. Patch by Eryk Sun and Oren Milman.
@end itemize

@node Library<63>,Documentation<57>,Core and Builtins<63>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id553}@anchor{1a52}
@subsubsection Library



@itemize -

@item 
bpo-30167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30167}: Prevent site.main() exception if PYTHONSTARTUP is set. Patch by
Steve Weber.

@item 
bpo-33812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33812}: Datetime instance d with non-None tzinfo, but with
d.tzinfo.utcoffset(d) returning None is now treated as naive by the
astimezone() method.

@item 
bpo-30805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30805}: Avoid race condition with debug logging

@item 
bpo-33767@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33767}: The concatenation (@code{+}) and repetition (@code{*}) sequence
operations now raise @ref{522,,TypeError} instead of @ref{561,,SystemError} when
performed on @ref{208,,mmap.mmap} objects.  Patch by Zackery Spytz.

@item 
bpo-32684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32684}: Fix gather to propagate cancellation of itself even with
return_exceptions.

@item 
bpo-33674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33674}: Fix a race condition in SSLProtocol.connection_made() of
asyncio.sslproto: start immediately the handshake instead of using
call_soon(). Previously, data_received() could be called before the
handshake started, causing the handshake to hang or fail.

@item 
bpo-31647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31647}: Fixed bug where calling write_eof() on a
_SelectorSocketTransport after it's already closed raises AttributeError.

@item 
bpo-33672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33672}: Fix Task.__repr__ crash with Cython's bogus coroutines

@item 
bpo-33469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33469}: Fix RuntimeError after closing loop that used run_in_executor

@item 
bpo-11874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11874}: Use a better regex when breaking usage into wrappable parts.
Avoids bogus assertion errors from custom metavar strings.

@item 
bpo-30877@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30877}: Fixed a bug in the Python implementation of the JSON decoder
that prevented the cache of parsed strings from clearing after finishing
the decoding. Based on patch by c-fos.

@item 
bpo-33548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33548}: tempfile._candidate_tempdir_list should consider common TEMP
locations

@item 
bpo-33542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33542}: Prevent @code{uuid.get_node} from using a DUID instead of a MAC on
Windows. Patch by Zvi Effron

@item 
bpo-26819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26819}: Fix race condition with @code{ReadTransport.resume_reading} in
Windows proactor event loop.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Minor fixes in typing module: add annotations to
@code{NamedTuple.__new__}, pass @code{*args} and @code{**kwds} in
@code{Generic.__new__}.  Original PRs by Paulius Šarka and Chad Dombrova.

@item 
bpo-20087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20087}: Updated alias mapping with glibc 2.27 supported locales.

@item 
bpo-33422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33422}: Fix trailing quotation marks getting deleted when looking up
byte/string literals on pydoc. Patch by Andrés Delfino.

@item 
bpo-33197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33197}: Update error message when constructing invalid
inspect.Parameters Patch by Donghee Na.

@item 
bpo-33383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33383}: Fixed crash in the get() method of the @ref{34,,dbm.ndbm} database
object when it is called with a single argument.

@item 
bpo-33329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33329}: Fix multiprocessing regression on newer glibcs

@item 
bpo-991266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=991266}: Fix quoting of the @code{Comment} attribute of
@ref{19d1,,http.cookies.SimpleCookie}.

@item 
bpo-33131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33131}: Upgrade bundled version of pip to 10.0.1.

@item 
bpo-33308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33308}: Fixed a crash in the @code{parser} module when converting an ST
object to a tree of tuples or lists with @code{line_info=False} and
@code{col_info=True}.

@item 
bpo-33263@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33263}: Fix FD leak in @code{_SelectorSocketTransport}  Patch by Vlad
Starostin.

@item 
bpo-33256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33256}: Fix display of @code{<module>} call in the html produced by
@code{cgitb.html()}. Patch by Stéphane Blondon.

@item 
bpo-33203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33203}: @code{random.Random.choice()} now raises @code{IndexError} for empty
sequences consistently even when called from subclasses without a
@code{getrandbits()} implementation.

@item 
bpo-33224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33224}: Update difflib.mdiff() for 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}.  Convert an uncaught
StopIteration in a generator into a return-statement.

@item 
bpo-33209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33209}: End framing at the end of C implementation of
@ref{19d3,,pickle.Pickler.dump()}.

@item 
bpo-32861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32861}: The urllib.robotparser's @code{__str__} representation now
includes wildcard entries and the "Crawl-delay" and "Request-rate" fields.
Patch by Michael Lazar.

@item 
bpo-33096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33096}: Allow ttk.Treeview.insert to insert iid that has a false
boolean value. Note iid=0 and iid=False would be same. Patch by Garvit
Khatri.

@item 
bpo-33127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33127}: The ssl module now compiles with LibreSSL 2.7.1.

@item 
bpo-33021@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33021}: Release the GIL during fstat() calls, avoiding hang of all
threads when calling mmap.mmap(), os.urandom(), and random.seed().  Patch
by Nir Soffer.

@item 
bpo-27683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27683}: Fix a regression in @ref{7f,,ipaddress} that result of
@code{hosts()} is empty when the network is constructed by a tuple
containing an integer mask and only 1 bit left for addresses.

@item 
bpo-32844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32844}: Fix wrong redirection of a low descriptor (0 or 1) to stderr in
subprocess if another low descriptor is closed.

@item 
bpo-31908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31908}: Fix output of cover files for @code{trace} module command-line
tool. Previously emitted cover files only when @code{--missing} option was
used. Patch by Michael Selik.

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: If nested log adapters are used, the inner @code{process()}
methods are no longer omitted.

@item 
bpo-16865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16865}: Support arrays >=2GiB in @ref{2a,,ctypes}.  Patch by Segev Finer.

@item 
bpo-31238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31238}: pydoc: the stop() method of the private ServerThread class now
waits until DocServer.serve_until_quit() completes and then explicitly
sets its docserver attribute to None to break a reference cycle.
@end itemize

@node Documentation<57>,Tests<57>,Library<63>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id554}@anchor{1a53}
@subsubsection Documentation



@itemize -

@item 
bpo-33503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33503}: Fix broken pypi link

@item 
bpo-33421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33421}: Add missing documentation for @code{typing.AsyncContextManager}.

@item 
bpo-33378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33378}: Add Korean language switcher for @indicateurl{https://docs.python.org/3/}

@item 
bpo-33276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33276}: Clarify that the @code{__path__} attribute on modules cannot be
just any value.

@item 
bpo-33201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33201}: Modernize documentation for writing C extension types.

@item 
bpo-33195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33195}: Deprecate @code{Py_UNICODE} usage in @code{c-api/arg} document.
@code{Py_UNICODE} related APIs are deprecated since Python 3.3, but it is
missed in the document.

@item 
bpo-33126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33126}: Document PyBuffer_ToContiguous().

@item 
bpo-27212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27212}: Modify documentation for the @code{islice()} recipe to consume
initial values up to the start index.

@item 
bpo-28247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28247}: Update @ref{12f,,zipapp} documentation to describe how to make
standalone applications.

@item 
bpo-18802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18802}: Documentation changes for ipaddress.  Patch by Jon Foster and
Berker Peksag.

@item 
bpo-27428@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27428}: Update documentation to clarify that @code{WindowsRegistryFinder}
implements @code{MetaPathFinder}. (Patch by Himanshu Lakhara)

@item 
bpo-8243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8243}: Add a note about curses.addch and curses.addstr exception
behavior when writing outside a window, or pad.

@item 
bpo-31432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31432}: Clarify meaning of CERT_NONE, CERT_OPTIONAL, and CERT_REQUIRED
flags for ssl.SSLContext.verify_mode.
@end itemize

@node Tests<57>,Build<60>,Documentation<57>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id555}@anchor{1a54}
@subsubsection Tests



@itemize -

@item 
bpo-33655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33655}: Ignore test_posix_fallocate failures on BSD platforms that
might be due to running on ZFS.

@item 
bpo-19417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19417}: Add test_bdb.py.
@end itemize

@node Build<60>,Windows<55>,Tests<57>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id556}@anchor{1a55}
@subsubsection Build



@itemize -

@item 
bpo-5755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5755}: Move @code{-Wstrict-prototypes} option to @code{CFLAGS_NODIST} from
@code{OPT}. This option emitted annoying warnings when building extension
modules written in C++.

@item 
bpo-33614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33614}: Ensures module definition files for the stable ABI on Windows
are correctly regenerated.

@item 
bpo-33522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33522}: Enable CI builds on Visual Studio Team Services at
@indicateurl{https://python.visualstudio.com/cpython}

@item 
bpo-33012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33012}: Add @code{-Wno-cast-function-type} for gcc 8 for silencing
warnings about function casts like casting to PyCFunction in method
definition lists.

@item 
bpo-33394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33394}: Enable the verbose build for extension modules, when GNU make
is passed macros on the command line.
@end itemize

@node Windows<55>,macOS<44>,Build<60>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id557}@anchor{1a56}
@subsubsection Windows



@itemize -

@item 
bpo-33184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33184}: Update Windows installer to OpenSSL 1.0.2o.
@end itemize

@node macOS<44>,IDLE<46>,Windows<55>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id558}@anchor{1a57}
@subsubsection macOS



@itemize -

@item 
bpo-33184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33184}: Update macOS installer build to use OpenSSL 1.0.2o.
@end itemize

@node IDLE<46>,Tools/Demos<32>,macOS<44>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id559}@anchor{1a58}
@subsubsection IDLE



@itemize -

@item 
bpo-33656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33656}: On Windows, add API call saying that tk scales for DPI. On
Windows 8.1+ or 10, with DPI compatibility properties of the Python binary
unchanged, and a monitor resolution greater than 96 DPI, this should make
text and lines sharper.  It should otherwise have no effect.

@item 
bpo-33768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33768}: Clicking on a context line moves that line to the top of the
editor window.

@item 
bpo-33763@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33763}: IDLE: Use read-only text widget for code context instead of
label widget.

@item 
bpo-33664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33664}: Scroll IDLE editor text by lines. Previously, the mouse wheel
and scrollbar slider moved text by a fixed number of pixels, resulting in
partial lines at the top of the editor box.  The change also applies to
the shell and grep output windows, but not to read-only text views.

@item 
bpo-33679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33679}: Enable theme-specific color configuration for Code Context. Use
the Highlights tab to see the setting for built-in themes or add settings
to custom themes.

@item 
bpo-33642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33642}: Display up to maxlines non-blank lines for Code Context. If
there is no current context, show a single blank line.

@item 
bpo-33628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33628}: IDLE: Cleanup codecontext.py and its test.

@item 
bpo-33564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33564}: IDLE's code context now recognizes async as a block opener.

@item 
bpo-29706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29706}: IDLE now colors async and await as keywords in 3.6. They become
full keywords in 3.7.

@item 
bpo-21474@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21474}: Update word/identifier definition from ascii to unicode. In
text and entry boxes, this affects selection by double-click, movement
left/right by control-left/right, and deletion left/right by
control-BACKSPACE/DEL.

@item 
bpo-33204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33204}: IDLE: consistently color invalid string prefixes. A 'u' string
prefix cannot be paired with either 'r' or 'f'. Consistently color as much
of the prefix, starting at the right, as is valid. Revise and extend
colorizer test.

@item 
bpo-32831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32831}: Add docstrings and tests for codecontext.
@end itemize

@node Tools/Demos<32>,C API<57>,IDLE<46>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id560}@anchor{1a59}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-33189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33189}: @code{pygettext.py} now recognizes only literal strings as
docstrings and translatable strings, and rejects bytes literals and
f-string expressions.

@item 
bpo-31920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31920}: Fixed handling directories as arguments in the @code{pygettext}
script. Based on patch by Oleg Krasnikov.

@item 
bpo-29673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29673}: Fix pystackv and pystack gdbinit macros.

@item 
bpo-32885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32885}: Add an @code{-n} flag for @code{Tools/scripts/pathfix.py} to disable
automatic backup creation (files with @code{~} suffix).

@item 
bpo-31583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31583}: Fix 2to3 for using with --add-suffix option but without
--output-dir option for relative path to files in current directory.
@end itemize

@node C API<57>,,Tools/Demos<32>,Python 3 6 6 release candidate 1
@anchor{whatsnew/changelog id561}@anchor{1a5a}
@subsubsection C API



@itemize -

@item 
bpo-32374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32374}: Document that m_traverse for multi-phase initialized modules
can be called with m_state=NULL, and add a sanity check
@end itemize

@node Python 3 6 5 final,Python 3 6 5 release candidate 1,Python 3 6 6 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-5-final}@anchor{1a5b}
@subsection Python 3.6.5 final


`Release date: 2018-03-28'

@menu
* Tests: Tests<58>. 
* Build: Build<61>. 

@end menu

@node Tests<58>,Build<61>,,Python 3 6 5 final
@anchor{whatsnew/changelog id562}@anchor{1a5c}
@subsubsection Tests



@itemize -

@item 
bpo-32872@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32872}: Avoid regrtest compatibility issue with namespace packages.
@end itemize

@node Build<61>,,Tests<58>,Python 3 6 5 final
@anchor{whatsnew/changelog id563}@anchor{1a5d}
@subsubsection Build



@itemize -

@item 
bpo-33163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33163}: Upgrade pip to 9.0.3 and setuptools to v39.0.1.
@end itemize

@node Python 3 6 5 release candidate 1,Python 3 6 4 final,Python 3 6 5 final,Changelog
@anchor{whatsnew/changelog python-3-6-5-release-candidate-1}@anchor{1a5e}
@subsection Python 3.6.5 release candidate 1


`Release date: 2018-03-13'

@menu
* Security: Security<39>. 
* Core and Builtins: Core and Builtins<64>. 
* Library: Library<64>. 
* Documentation: Documentation<58>. 
* Tests: Tests<59>. 
* Build: Build<62>. 
* Windows: Windows<56>. 
* macOS: macOS<45>. 
* IDLE: IDLE<47>. 
* Tools/Demos: Tools/Demos<33>. 
* C API: C API<58>. 

@end menu

@node Security<39>,Core and Builtins<64>,,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id564}@anchor{1a5f}
@subsubsection Security



@itemize -

@item 
bpo-33001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33001}: Minimal fix to prevent buffer overrun in os.symlink on Windows

@item 
bpo-32981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32981}: Regexes in difflib and poplib were vulnerable to catastrophic
backtracking. These regexes formed potential DOS vectors (REDOS). They
have been refactored. This resolves 
@geindex Common Vulnerabilities and Exposures; CVE 2018-1060
CVE 2018-1060@footnote{https://www.cve.org/CVERecord?id=CVE-2018-1060} and 
@geindex Common Vulnerabilities and Exposures; CVE 2018-1061
CVE 2018-1061@footnote{https://www.cve.org/CVERecord?id=CVE-2018-1061}.
Patch by Jamie Davis.
@end itemize

@node Core and Builtins<64>,Library<64>,Security<39>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id565}@anchor{1a60}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-33026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33026}: Fixed jumping out of "with" block by setting f_lineno.

@item 
bpo-17288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17288}: Prevent jumps from 'return' and 'exception' trace events.

@item 
bpo-32889@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32889}: Update Valgrind suppression list to account for the rename of
@code{Py_ADDRESS_IN_RANG} to @code{address_in_range}.

@item 
bpo-32650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32650}: Pdb and other debuggers dependent on bdb.py will correctly step
over (next command) native coroutines. Patch by Pablo Galindo.

@item 
bpo-32685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32685}: Improve suggestion when the Python 2 form of print statement is
either present on the same line as the header of a compound statement or
else terminated by a semi-colon instead of a newline. Patch by Nitish
Chandra.

@item 
bpo-32583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32583}: Fix possible crashing in builtin Unicode decoders caused by
write out-of-bound errors when using customized decode error handlers.

@item 
bpo-26163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26163}: Improved frozenset() hash to create more distinct hash values
when faced with datasets containing many similar values.

@item 
bpo-27169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27169}: The @code{__debug__} constant is now optimized out at compile
time. This fixes also bpo-22091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22091}.

@item 
bpo-32329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32329}: @code{sys.flags.hash_randomization} is now properly set to 0 when
hash randomization is turned off by @code{PYTHONHASHSEED=0}.

@item 
bpo-30416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30416}: The optimizer is now protected from spending much time doing
complex calculations and consuming much memory for creating large
constants in constant folding.

@item 
bpo-18533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18533}: @code{repr()} on a dict containing its own @code{values()} or
@code{items()} no longer raises @code{RecursionError}; OrderedDict similarly.
Instead, use @code{...}, as for other recursive structures.  Patch by Ben
North.

@item 
bpo-32028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32028}: Leading whitespace is now correctly ignored when generating
suggestions for converting Py2 print statements to Py3 builtin print
function calls. Patch by Sanyam Khurana.

@item 
bpo-32137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32137}: The repr of deeply nested dict now raises a RecursionError
instead of crashing due to a stack overflow.
@end itemize

@node Library<64>,Documentation<58>,Core and Builtins<64>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id566}@anchor{1a61}
@subsubsection Library



@itemize -

@item 
bpo-33064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33064}: lib2to3 now properly supports trailing commas after @code{*args}
and @code{**kwargs} in function signatures.

@item 
bpo-31804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31804}: Avoid failing in multiprocessing.Process if the standard
streams are closed or None at exit.

@item 
bpo-33037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33037}: Skip sending/receiving data after SSL transport closing.

@item 
bpo-30353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30353}: Fix ctypes pass-by-value for structs on 64-bit Cygwin/MinGW.

@item 
bpo-33009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33009}: Fix inspect.signature() for single-parameter partialmethods.

@item 
bpo-32969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32969}: Expose several missing constants in zlib and fix corresponding
documentation.

@item 
bpo-32713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32713}: Fixed tarfile.itn handling of out-of-bounds float values. Patch
by Joffrey Fuhrer.

@item 
bpo-30622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30622}: The ssl module now detects missing NPN support in LibreSSL.

@item 
bpo-32922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32922}: dbm.open() now encodes filename with the filesystem encoding
rather than default encoding.

@item 
bpo-32859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32859}: In @code{os.dup2}, don't check every call whether the @code{dup3}
syscall exists or not.

@item 
bpo-21060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21060}: Rewrite confusing message from setup.py upload from "No dist
file created in earlier command" to the more helpful "Must create and
upload files in one command".

@item 
bpo-32857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32857}: In @ref{ef,,tkinter}, @code{after_cancel(None)} now raises a
@ref{1ff,,ValueError} instead of canceling the first scheduled function.
Patch by Cheryl Sabella.

@item 
bpo-32852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32852}: Make sure sys.argv remains as a list when running trace.

@item 
bpo-32841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32841}: Fixed @code{asyncio.Condition} issue which silently ignored
cancellation after notifying and cancelling a conditional lock. Patch by
Bar Harel.

@item 
bpo-31787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31787}: Fixed refleaks of @code{__init__()} methods in various modules.
(Contributed by Oren Milman)

@item 
bpo-30157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30157}: Fixed guessing quote and delimiter in csv.Sniffer.sniff() when
only the last field is quoted.  Patch by Jake Davis.

@item 
bpo-32394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32394}: socket: Remove TCP_FASTOPEN, TCP_KEEPCNT flags on older version
Windows during run-time.

@item 
bpo-32777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32777}: Fix a rare but potential pre-exec child process deadlock in
subprocess on POSIX systems when marking file descriptors inheritable on
exec in the child process.  This bug appears to have been introduced in
3.4.

@item 
bpo-32647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32647}: The ctypes module used to depend on indirect linking for
dlopen. The shared extension is now explicitly linked against libdl on
platforms with dl.

@item 
bpo-32734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32734}: Fixed @code{asyncio.Lock()} safety issue which allowed acquiring
and locking the same lock multiple times, without it being free. Patch by
Bar Harel.

@item 
bpo-32727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32727}: Do not include name field in SMTP envelope from address. Patch
by Stéphane Wirtel

@item 
bpo-27931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27931}: Fix email address header parsing error when the username is an
empty quoted string. Patch by Xiang Zhang.

@item 
bpo-32304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32304}: distutils' upload command no longer corrupts tar files ending
with a CR byte, and no longer tries to convert CR to CRLF in any of the
upload text fields.

@item 
bpo-32502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32502}: uuid.uuid1 no longer raises an exception if a 64-bit hardware
address is encountered.

@item 
bpo-31848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31848}: Fix the error handling in Aifc_read.initfp() when the SSND
chunk is not found. Patch by Zackery Spytz.

@item 
bpo-32555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32555}: On FreeBSD and Solaris, os.strerror() now always decode the
byte string from the current locale encoding, rather than using
ASCII/surrogateescape in some cases.

@item 
bpo-32521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32521}: The nis module is now compatible with new libnsl and headers
location.

@item 
bpo-32473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32473}: Improve ABCMeta._dump_registry() output readability

@item 
bpo-32521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32521}: glibc has removed Sun RPC. Use replacement libtirpc headers and
library in nis module.

@item 
bpo-32228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32228}: Ensure that @code{truncate()} preserves the file position (as
reported by @code{tell()}) after writes longer than the buffer size.

@item 
bpo-26133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26133}: Don't unsubscribe signals in asyncio UNIX event loop on
interpreter shutdown.

@item 
bpo-32185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32185}: The SSL module no longer sends IP addresses in SNI TLS
extension on platforms with OpenSSL 1.0.2+ or inet_pton.

@item 
bpo-32323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32323}: @ref{d2d,,urllib.parse.urlsplit()} does not convert zone-id (scope)
to lower case for scoped IPv6 addresses in hostnames now.

@item 
bpo-32302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32302}: Fix bdist_wininst of distutils for CRT v142: it binary
compatible with CRT v140.

@item 
bpo-32255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32255}: A single empty field is now always quoted when written into a
CSV file. This allows to distinguish an empty row from a row consisting of
a single empty field. Patch by Licht Takeuchi.

@item 
bpo-32277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32277}: Raise @code{NotImplementedError} instead of @code{SystemError} on
platforms where @code{chmod(..., follow_symlinks=False)} is not supported.
Patch by Anthony Sottile.

@item 
bpo-32199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32199}: The getnode() ip getter now uses 'ip link' instead of 'ip link
list'.

@item 
bpo-27456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27456}: Ensure TCP_NODELAY is set on Linux. Tests by Victor Stinner.

@item 
bpo-31900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31900}: The @ref{bec,,locale.localeconv()} function now sets temporarily the
@code{LC_CTYPE} locale to the @code{LC_NUMERIC} locale to decode
@code{decimal_point} and @code{thousands_sep} byte strings if they are non-ASCII
or longer than 1 byte, and the @code{LC_NUMERIC} locale is different than the
@code{LC_CTYPE} locale. This temporary change affects other threads. Same
change for the @ref{60c,,str.format()} method when formatting a number
(@ref{254,,int}, @ref{2eb,,float}, @ref{2eb,,float} and subclasses) with the
@code{n} type (ex: @code{'@{:n@}'.format(1234)}).

@item 
bpo-31802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31802}: Importing native path module (@code{posixpath}, @code{ntpath}) now
works even if the @code{os} module still is not imported.
@end itemize

@node Documentation<58>,Tests<59>,Library<64>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id567}@anchor{1a62}
@subsubsection Documentation



@itemize -

@item 
bpo-17232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17232}: Clarify docs for -O and -OO.  Patch by Terry Reedy.

@item 
bpo-32800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32800}: Update link to w3c doc for xml default namespaces.

@item 
bpo-8722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8722}: Document @code{__getattr__()} behavior when property @code{get()}
method raises @ref{343,,AttributeError}.

@item 
bpo-32614@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32614}: Modify RE examples in documentation to use raw strings to
prevent @ref{1a3,,DeprecationWarning} and add text to REGEX HOWTO to highlight
the deprecation.

@item 
bpo-31972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31972}: Improve docstrings for @code{pathlib.PurePath} subclasses.

@item 
bpo-17799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17799}: Explain real behaviour of sys.settrace and sys.setprofile and
their C-API counterparts regarding which type of events are received in
each function. Patch by Pablo Galindo Salgado.
@end itemize

@node Tests<59>,Build<62>,Documentation<58>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id568}@anchor{1a63}
@subsubsection Tests



@itemize -

@item 
bpo-32517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32517}: Fix failing @code{test_asyncio} on macOS 10.12.2+ due to transport
of @code{KqueueSelector} loop was not being closed.

@item 
bpo-32721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32721}: Fix test_hashlib to not fail if the _md5 module is not built.

@item 
bpo-32252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32252}: Fix faulthandler_suppress_crash_report() used to prevent core
dump files when testing crashes. getrlimit() returns zero on success.

@item 
bpo-31518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31518}: Debian Unstable has disabled TLS 1.0 and 1.1 for
SSLv23_METHOD(). Change TLS/SSL protocol of some tests to PROTOCOL_TLS or
PROTOCOL_TLSv1_2 to make them pass on Debian.
@end itemize

@node Build<62>,Windows<56>,Tests<59>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id569}@anchor{1a64}
@subsubsection Build



@itemize -

@item 
bpo-32635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32635}: Fix segfault of the crypt module when libxcrypt is provided
instead of libcrypt at the system.
@end itemize

@node Windows<56>,macOS<45>,Build<62>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id570}@anchor{1a65}
@subsubsection Windows



@itemize -

@item 
bpo-33016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33016}: Fix potential use of uninitialized memory in
nt._getfinalpathname

@item 
bpo-32903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32903}: Fix a memory leak in os.chdir() on Windows if the current
directory is set to a UNC path.

@item 
bpo-31966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31966}: Fixed WindowsConsoleIO.write() for writing empty data.

@item 
bpo-32409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32409}: Ensures activate.bat can handle Unicode contents.

@item 
bpo-32457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32457}: Improves handling of denormalized executable path when
launching Python.

@item 
bpo-32370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32370}: Use the correct encoding for ipconfig output in the uuid
module. Patch by Segev Finer.

@item 
bpo-29248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29248}: Fix @ref{90d,,os.readlink()} on Windows, which was mistakenly
treating the @code{PrintNameOffset} field of the reparse data buffer as a
number of characters instead of bytes. Patch by Craig Holmquist and SSE4.

@item 
bpo-32588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32588}: Create standalone _distutils_findvs module.
@end itemize

@node macOS<45>,IDLE<47>,Windows<56>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id571}@anchor{1a66}
@subsubsection macOS



@itemize -

@item 
bpo-32726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32726}: Provide an additional, more modern macOS installer variant that
supports macOS 10.9+ systems in 64-bit mode only. Upgrade the supplied
third-party libraries to OpenSSL 1.0.2n, XZ 5.2.3, and SQLite 3.22.0. The
10.9+ installer now links with and supplies its own copy of Tcl/Tk 8.6.8.
@end itemize

@node IDLE<47>,Tools/Demos<33>,macOS<45>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id572}@anchor{1a67}
@subsubsection IDLE



@itemize -

@item 
bpo-32984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32984}: Set @code{__file__} while running a startup file.  Like Python,
IDLE optionally runs one startup file in the Shell window before
presenting the first interactive input prompt.  For IDLE, @code{-s} runs a
file named in environmental variable  
@geindex IDLESTARTUP
@geindex variable d'environnement; IDLESTARTUP
@code{IDLESTARTUP} or
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP}; @code{-r file} runs @code{file}.  Python sets
@code{__file__} to the startup file name before running the file and unsets
it before the first prompt.  IDLE now does the same when run normally,
without the @code{-n} option.

@item 
bpo-32940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32940}: Simplify and rename StringTranslatePseudoMapping in pyparse.

@item 
bpo-32916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32916}: Change @code{str} to @code{code} in pyparse.

@item 
bpo-32905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32905}: Remove unused code in pyparse module.

@item 
bpo-32874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32874}: Add tests for pyparse.

@item 
bpo-32837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32837}: Using the system and place-dependent default encoding for
open() is a bad idea for IDLE's system and location-independent files.

@item 
bpo-32826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32826}: Add "encoding=utf-8" to open() in IDLE's test_help_about. GUI
test test_file_buttons() only looks at initial ascii-only lines, but
failed on systems where open() defaults to 'ascii' because readline()
internally reads and decodes far enough ahead to encounter a non-ascii
character in CREDITS.txt.

@item 
bpo-32765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32765}: Update configdialog General tab docstring to add new widgets to
the widget list.
@end itemize

@node Tools/Demos<33>,C API<58>,IDLE<47>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id573}@anchor{1a68}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-24960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24960}: 2to3 and lib2to3 can now read pickled grammar files using
pkgutil.get_data() rather than probing the filesystem. This lets 2to3 and
lib2to3 work when run from a zipfile.

@item 
bpo-32222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32222}: Fix pygettext not extracting docstrings for functions with type
annotated arguments. Patch by Toby Harradine.
@end itemize

@node C API<58>,,Tools/Demos<33>,Python 3 6 5 release candidate 1
@anchor{whatsnew/changelog id574}@anchor{1a69}
@subsubsection C API



@itemize -

@item 
bpo-29084@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29084}: Undocumented C API for OrderedDict has been excluded from the
limited C API. It was added by mistake and actually never worked in the
limited C API.
@end itemize

@node Python 3 6 4 final,Python 3 6 4 release candidate 1,Python 3 6 5 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-4-final}@anchor{1a6a}
@subsection Python 3.6.4 final


`Release date: 2017-12-18'

There were no new code changes in version 3.6.4 since v3.6.4rc1.

@node Python 3 6 4 release candidate 1,Python 3 6 3 final,Python 3 6 4 final,Changelog
@anchor{whatsnew/changelog python-3-6-4-release-candidate-1}@anchor{1a6b}
@subsection Python 3.6.4 release candidate 1


`Release date: 2017-12-05'

@menu
* Core and Builtins: Core and Builtins<65>. 
* Library: Library<65>. 
* Documentation: Documentation<59>. 
* Tests: Tests<60>. 
* Build: Build<63>. 
* Windows: Windows<57>. 
* macOS: macOS<46>. 
* IDLE: IDLE<48>. 
* Tools/Demos: Tools/Demos<34>. 
* C API: C API<59>. 

@end menu

@node Core and Builtins<65>,Library<65>,,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id575}@anchor{1a6c}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-32176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32176}: co_flags.CO_NOFREE is now always set correctly by the code
object constructor based on freevars and cellvars, rather than needing to
be set correctly by the caller. This ensures it will be cleared
automatically when additional cell references are injected into a modified
code object and function.

@item 
bpo-31949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31949}: Fixed several issues in printing tracebacks
(PyTraceBack_Print()). Setting sys.tracebacklimit to 0 or less now
suppresses printing tracebacks. Setting sys.tracebacklimit to None now
causes using the default limit. Setting sys.tracebacklimit to an integer
larger than LONG_MAX now means using the limit LONG_MAX rather than the
default limit. Fixed integer overflows in the case of more than @code{2**31}
traceback items on Windows. Fixed output errors handling.

@item 
bpo-30696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30696}: Fix the interactive interpreter looping endlessly when no
memory.

@item 
bpo-20047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20047}: Bytearray methods partition() and rpartition() now accept only
bytes-like objects as separator, as documented.  In particular they now
raise TypeError rather of returning a bogus result when an integer is
passed as a separator.

@item 
bpo-31852@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31852}: Fix a segmentation fault caused by a combination of the async
soft keyword and continuation lines.

@item 
bpo-21720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21720}: BytesWarning no longer emitted when the `fromlist' argument of
@code{__import__()} or the @code{__all__} attribute of the module contain bytes
instances.

@item 
bpo-31825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31825}: Fixed OverflowError in the 'unicode-escape' codec and in
codecs.escape_decode() when decode an escaped non-ascii byte.

@item 
bpo-28603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28603}: Print the full context/cause chain of exceptions on interpreter
exit, even if an exception in the chain is unhashable or compares equal to
later ones. Patch by Zane Bitter.

@item 
bpo-31786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31786}: Fix timeout rounding in the select module to round correctly
negative timeouts between -1.0 and 0.0. The functions now block waiting
for events as expected. Previously, the call was incorrectly non-blocking.
Patch by Pablo Galindo.

@item 
bpo-31642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31642}: Restored blocking "from package import module" by setting
sys.modules["package.module"] to None.

@item 
bpo-31626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31626}: Fixed a bug in debug memory allocator.  There was a write to
freed memory after shrinking a memory block.

@item 
bpo-31619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31619}: Fixed a ValueError when convert a string with large number of
underscores to integer with binary base.

@item 
bpo-31592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31592}: Fixed an assertion failure in Python parser in case of a bad
@code{unicodedata.normalize()}. Patch by Oren Milman.

@item 
bpo-31588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31588}: Raise a @code{TypeError} with a helpful error message when class
creation fails due to a metaclass with a bad @code{__prepare__()} method.
Patch by Oren Milman.

@item 
bpo-31566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31566}: Fix an assertion failure in @code{_warnings.warn()} in case of a
bad @code{__name__} global. Patch by Oren Milman.

@item 
bpo-31505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31505}: Fix an assertion failure in @code{json}, in case
@code{_json.make_encoder()} received a bad @code{encoder()} argument. Patch by
Oren Milman.

@item 
bpo-31492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31492}: Fix assertion failures in case of failing to import from a
module with a bad @code{__name__} attribute, and in case of failing to access
an attribute of such a module. Patch by Oren Milman.

@item 
bpo-31490@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31490}: Fix an assertion failure in @code{ctypes} class definition, in
case the class has an attribute whose name is specified in @code{_anonymous_}
but not in @code{_fields_}. Patch by Oren Milman.

@item 
bpo-31478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31478}: Fix an assertion failure in @code{_random.Random.seed()} in case
the argument has a bad @code{__abs__()} method. Patch by Oren Milman.

@item 
bpo-31315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31315}: Fix an assertion failure in imp.create_dynamic(), when
spec.name is not a string. Patch by Oren Milman.

@item 
bpo-31311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31311}: Fix a crash in the @code{__setstate__()} method of
@code{ctypes._CData}, in case of a bad @code{__dict__}. Patch by Oren Milman.

@item 
bpo-31293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31293}: Fix crashes in true division and multiplication of a timedelta
object by a float with a bad as_integer_ratio() method. Patch by Oren
Milman.

@item 
bpo-31285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31285}: Fix an assertion failure in @code{warnings.warn_explicit}, when
the return value of the received loader's @code{get_source()} has a bad
@code{splitlines()} method. Patch by Oren Milman.

@item 
bpo-30817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30817}: @code{PyErr_PrintEx()} clears now the ignored exception that may
be raised by @code{_PySys_SetObjectId()}, for example when no memory.
@end itemize

@node Library<65>,Documentation<59>,Core and Builtins<65>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id576}@anchor{1a6d}
@subsubsection Library



@itemize -

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Two minor fixes for @code{typing} module: allow shallow copying
instances of generic classes, improve interaction of @code{__init_subclass__}
with generics. Original PRs by Ivan Levkivskyi.

@item 
bpo-27240@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27240}: The header folding algorithm for the new email policies has
been rewritten, which also fixes bpo-30788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30788}, bpo-31831@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31831}, and bpo-32182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32182}.  In
particular, RFC2231 folding is now done correctly.

@item 
bpo-32186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32186}: io.FileIO.readall() and io.FileIO.read() now release the GIL
when getting the file size. Fixed hang of all threads with inaccessible
NFS server. Patch by Nir Soffer.

@item 
bpo-12239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12239}: Make @code{msilib.SummaryInformation.GetProperty()} return
@code{None} when the value of property is @code{VT_EMPTY}.  Initial patch by
Mark Mc Mahon.

@item 
bpo-31325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31325}: Fix wrong usage of @ref{1c5,,collections.namedtuple()} in the
@ref{1a30,,RobotFileParser.parse()}
method. Initial patch by Robin Wellner.

@item 
bpo-12382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12382}: @code{msilib.OpenDatabase()} now raises a better exception
message when it couldn't open or create an MSI file.  Initial patch by
William Tisäter.

@item 
bpo-32110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32110}: @code{codecs.StreamReader.read(n)} now returns not more than `n'
characters/bytes for non-negative `n'. This makes it compatible with
@code{read()} methods of other file-like objects.

@item 
bpo-32072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32072}: Fixed issues with binary plists: Fixed saving bytearrays.
Identical objects will be saved only once. Equal references will be load
as identical objects. Added support for saving and loading recursive data
structures.

@item 
bpo-32034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32034}: Make asyncio.IncompleteReadError and LimitOverrunError
pickleable.

@item 
bpo-32015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32015}: Fixed the looping of asyncio in the case of reconnection the
socket during waiting async read/write from/to the socket.

@item 
bpo-32011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32011}: Restored support of loading marshal files with the TYPE_INT64
code. These files can be produced in Python 2.7.

@item 
bpo-31970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31970}: Reduce performance overhead of asyncio debug mode.

@item 
bpo-9678@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9678}: Fixed determining the MAC address in the uuid module: Using
ifconfig on NetBSD and OpenBSD. Using arp on Linux, FreeBSD, NetBSD and
OpenBSD. Based on patch by Takayuki Shimizukawa.

@item 
bpo-30057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30057}: Fix potential missed signal in signal.signal().

@item 
bpo-31933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31933}: Fix Blake2 params leaf_size and node_offset on big endian
platforms. Patch by Jack O'Connor.

@item 
bpo-31927@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31927}: Fixed compilation of the socket module on NetBSD 8.  Fixed
assertion failure or reading arbitrary data when parse a AF_BLUETOOTH
address on NetBSD and DragonFly BSD.

@item 
bpo-27666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27666}: Fixed stack corruption in curses.box() and curses.ungetmouse()
when the size of types chtype or mmask_t is less than the size of C long.
curses.box() now accepts characters as arguments.  Based on patch by Steve
Fink.

@item 
bpo-31897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31897}: plistlib now catches more errors when read binary plists and
raises InvalidFileException instead of unexpected exceptions.

@item 
bpo-25720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25720}: Fix the method for checking pad state of curses WINDOW. Patch
by Masayuki Yamamoto.

@item 
bpo-31893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31893}: Fixed the layout of the kqueue_event structure on OpenBSD and
NetBSD. Fixed the comparison of the kqueue_event objects.

@item 
bpo-31891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31891}: Fixed building the curses module on NetBSD.

@item 
bpo-28416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28416}: Instances of pickle.Pickler subclass with the persistent_id()
method and pickle.Unpickler subclass with the persistent_load() method no
longer create reference cycles.

@item 
bpo-28326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28326}: Fix multiprocessing.Process when stdout and/or stderr is closed
or None.

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: If nested log adapters are used, the inner @code{process()}
methods are no longer omitted.

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: The @code{manager} property on LoggerAdapter objects is now
properly settable.

@item 
bpo-31806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31806}: Fix timeout rounding in time.sleep(), threading.Lock.acquire()
and socket.socket.settimeout() to round correctly negative timeouts
between -1.0 and 0.0. The functions now block waiting for events as
expected. Previously, the call was incorrectly non-blocking. Patch by
Pablo Galindo.

@item 
bpo-28603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28603}: traceback: Fix a TypeError that occurred during printing of
exception tracebacks when either the current exception or an exception in
its context/cause chain is unhashable. Patch by Zane Bitter.

@item 
bpo-30058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30058}: Fixed buffer overflow in select.kqueue.control().

@item 
bpo-31770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31770}: Prevent a crash when calling the @code{__init__()} method of a
@code{sqlite3.Cursor} object more than once. Patch by Oren Milman.

@item 
bpo-31672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31672}: @code{idpattern} in @code{string.Template} matched some non-ASCII
characters. Now it uses @code{-i} regular expression local flag to avoid
non-ASCII characters.

@item 
bpo-31764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31764}: Prevent a crash in @code{sqlite3.Cursor.close()} in case the
@code{Cursor} object is uninitialized. Patch by Oren Milman.

@item 
bpo-31752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31752}: Fix possible crash in timedelta constructor called with custom
integers.

@item 
bpo-31701@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31701}: On Windows, faulthandler.enable() now ignores MSC and COM
exceptions.

@item 
bpo-31728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31728}: Prevent crashes in @code{_elementtree} due to unsafe cleanup of
@code{Element.text} and @code{Element.tail}. Patch by Oren Milman.

@item 
bpo-31620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31620}: an empty asyncio.Queue now doesn't leak memory when queue.get
pollers timeout

@item 
bpo-31632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31632}: Fix method set_protocol() of class _SSLProtocolTransport in
asyncio module. This method was previously modifying a wrong reference to
the protocol.

@item 
bpo-31675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31675}: Fixed memory leaks in Tkinter's methods splitlist() and split()
when pass a string larger than 2 GiB.

@item 
bpo-31673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31673}: Fixed typo in the name of Tkinter's method adderrorinfo().

@item 
bpo-30806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30806}: Fix the string representation of a netrc object.

@item 
bpo-15037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15037}: Added a workaround for getkey() in curses for ncurses 5.7 and
earlier.

@item 
bpo-25351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25351}: Avoid venv activate failures with undefined variables

@item 
bpo-25532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25532}: inspect.unwrap() will now only try to unwrap an object
sys.getrecursionlimit() times, to protect against objects which create a
new object on every attribute access.

@item 
bpo-30347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30347}: Stop crashes when concurrently iterate over itertools.groupby()
iterators.

@item 
bpo-31516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31516}: @code{threading.current_thread()} should not return a dummy thread
at shutdown.

@item 
bpo-31351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31351}: python -m ensurepip now exits with non-zero exit code if pip
bootstrapping has failed.

@item 
bpo-31482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31482}: @code{random.seed()} now works with bytes in version=1

@item 
bpo-31334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31334}: Fix @code{poll.poll([timeout])} in the @code{select} module for
arbitrary negative timeouts on all OSes where it can only be a
non-negative integer or -1. Patch by Riccardo Coccioli.

@item 
bpo-31310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31310}: multiprocessing's semaphore tracker should be launched again if
crashed.

@item 
bpo-31308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31308}: Make multiprocessing's forkserver process immune to Ctrl-C and
other user interruptions. If it crashes, restart it when necessary.
@end itemize

@node Documentation<59>,Tests<60>,Library<65>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id577}@anchor{1a6e}
@subsubsection Documentation



@itemize -

@item 
bpo-32105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32105}: Added asyncio.BaseEventLoop.connect_accepted_socket
versionadded marker.

@item 
bpo-31537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31537}: Fix incorrect usage of @code{get_history_length} in readline
documentation example code. Patch by Brad Smith.

@item 
bpo-30085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30085}: The operator functions without double underscores are preferred
for clarity. The one with underscores are only kept for
back-compatibility.
@end itemize

@node Tests<60>,Build<63>,Documentation<59>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id578}@anchor{1a6f}
@subsubsection Tests



@itemize -

@item 
bpo-31380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31380}: Skip test_httpservers test_undecodable_file on macOS: fails on
APFS.

@item 
bpo-31705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31705}: Skip test_socket.test_sha256() on Linux kernel older than 4.5.
The test fails with ENOKEY on kernel 3.10 (on ppc64le). A fix was merged
into the kernel 4.5.

@item 
bpo-31174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31174}: Fix test_tools.test_unparse: DirectoryTestCase now stores the
names sample to always test the same files. It prevents false alarms when
hunting reference leaks.

@item 
bpo-30695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30695}: Add the @code{set_nomemory(start, stop)} and
@code{remove_mem_hooks()} functions to the @code{_testcapi} module.
@end itemize

@node Build<63>,Windows<57>,Tests<60>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id579}@anchor{1a70}
@subsubsection Build



@itemize -

@item 
bpo-32059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32059}: @code{detect_modules()} in @code{setup.py} now also searches the
sysroot paths when cross-compiling.

@item 
bpo-31957@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31957}: Fixes Windows SDK version detection when building for Windows.

@item 
bpo-31609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31609}: Fixes quotes in PCbuild/clean.bat

@item 
bpo-31934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31934}: Abort the build when building out of a not clean source tree.

@item 
bpo-31926@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31926}: Fixed Argument Clinic sometimes causing compilation errors when
there was more than one function and/or method in a .c file with the same
name.

@item 
bpo-28791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28791}: Update Windows builds to use SQLite 3.21.0.

@item 
bpo-28791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28791}: Update OS X installer to use SQLite 3.21.0.

@item 
bpo-22140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22140}: Prevent double substitution of prefix in python-config.sh.

@item 
bpo-31536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31536}: Avoid wholesale rebuild after @code{make regen-all} if nothing
changed.
@end itemize

@node Windows<57>,macOS<46>,Build<63>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id580}@anchor{1a71}
@subsubsection Windows



@itemize -

@item 
bpo-1102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1102}: Return @code{None} when @code{View.Fetch()} returns
@code{ERROR_NO_MORE_ITEMS} instead of raising @code{MSIError}. Initial patch by
Anthony Tuininga.

@item 
bpo-31944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31944}: Fixes Modify button in Apps and Features dialog.
@end itemize

@node macOS<46>,IDLE<48>,Windows<57>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id581}@anchor{1a72}
@subsubsection macOS



@itemize -

@item 
bpo-31392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31392}: Update macOS installer to use OpenSSL 1.0.2m
@end itemize

@node IDLE<48>,Tools/Demos<34>,macOS<46>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id582}@anchor{1a73}
@subsubsection IDLE



@itemize -

@item 
bpo-32207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32207}: Improve tk event exception tracebacks in IDLE. When tk event
handling is driven by IDLE's run loop, a confusing and distracting
queue.EMPTY traceback context is no longer added to tk event exception
tracebacks.  The traceback is now the same as when event handling is
driven by user code.  Patch based on a suggestion by Serhiy Storchaka.

@item 
bpo-32164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32164}: Delete unused file idlelib/tabbedpages.py. Use of TabbedPageSet
in configdialog was replaced by ttk.Notebook.

@item 
bpo-32100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32100}: IDLE: Fix old and new bugs in pathbrowser; improve tests. Patch
mostly by Cheryl Sabella.

@item 
bpo-31858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31858}: IDLE -- Restrict shell prompt manipulation to the shell. Editor
and output windows only see an empty last prompt line.  This simplifies
the code and fixes a minor bug when newline is inserted. Sys.ps1, if
present, is read on Shell start-up, but is not set or changed.

@item 
bpo-31860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31860}: The font sample in the IDLE configuration dialog is now
editable. Changes persist while IDLE remains open

@item 
bpo-31836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31836}: Test_code_module now passes if run after test_idle, which sets
ps1. The code module uses sys.ps1 if present or sets it to '>>> ' if not.
Test_code_module now properly tests both behaviors.  Ditto for ps2.

@item 
bpo-28603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28603}: Fix a TypeError that caused a shell restart when printing a
traceback that includes an exception that is unhashable. Patch by Zane
Bitter.

@item 
bpo-13802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13802}: Use non-Latin characters in the IDLE's Font settings sample.
Even if one selects a font that defines a limited subset of the unicode
Basic Multilingual Plane, tcl/tk will use other fonts that define a
character. The expanded example give users of non-Latin characters a
better idea of what they might see in IDLE's shell and editors. To make
room for the expanded sample, frames on the Font tab are re-arranged. The
Font/Tabs help explains a bit about the additions.

@item 
bpo-31460@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31460}: Simplify the API of IDLE's Module Browser. Passing a widget
instead of an flist with a root widget opens the option of creating a
browser frame that is only part of a window.  Passing a full file name
instead of pieces assumed to come from a .py file opens the possibility of
browsing python files that do not end in .py.

@item 
bpo-31649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31649}: IDLE - Make _htest, _utest parameters keyword only.

@item 
bpo-31559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31559}: Remove test order dependence in idle_test.test_browser.

@item 
bpo-31459@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31459}: Rename IDLE's module browser from Class Browser to Module
Browser. The original module-level class and method browser became a
module browser, with the addition of module-level functions, years ago.
Nested classes and functions were added yesterday.  For
back-compatibility, the virtual event <<open-class-browser>>, which
appears on the Keys tab of the Settings dialog, is not changed. Patch by
Cheryl Sabella.

@item 
bpo-31500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31500}: Default fonts now are scaled on HiDPI displays.

@item 
bpo-1612262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1612262}: IDLE module browser now shows nested classes and functions.
Original patches for code and tests by Guilherme Polo and Cheryl Sabella,
respectively.
@end itemize

@node Tools/Demos<34>,C API<59>,IDLE<48>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id583}@anchor{1a74}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-30722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30722}: Make redemo work with Python 3.6 and newer versions. Also,
remove the @code{LOCALE} option since it doesn't work with string patterns in
Python 3. Patch by Christoph Sarnowski.
@end itemize

@node C API<59>,,Tools/Demos<34>,Python 3 6 4 release candidate 1
@anchor{whatsnew/changelog id584}@anchor{1a75}
@subsubsection C API



@itemize -

@item 
bpo-20891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20891}: Fix PyGILState_Ensure(). When PyGILState_Ensure() is called in
a non-Python thread before PyEval_InitThreads(), only call
PyEval_InitThreads() after calling PyThreadState_New() to fix a crash.

@item 
bpo-31532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31532}: Fix memory corruption due to allocator mix in getpath.c between
Py_GetPath() and Py_SetPath()

@item 
bpo-30697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30697}: The @code{PyExc_RecursionErrorInst} singleton is removed and
@code{PyErr_NormalizeException()} does not use it anymore. This singleton is
persistent and its members being never cleared may cause a segfault during
finalization of the interpreter. See also bpo-22898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22898}.
@end itemize

@node Python 3 6 3 final,Python 3 6 3 release candidate 1,Python 3 6 4 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-3-final}@anchor{1a76}
@subsection Python 3.6.3 final


`Release date: 2017-10-03'

@menu
* Library: Library<66>. 
* Build: Build<64>. 

@end menu

@node Library<66>,Build<64>,,Python 3 6 3 final
@anchor{whatsnew/changelog id585}@anchor{1a77}
@subsubsection Library



@itemize -

@item 
bpo-31641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31641}: Re-allow arbitrary iterables in
@code{concurrent.futures.as_completed()}. Fixes regression in 3.6.3rc1.
@end itemize

@node Build<64>,,Library<66>,Python 3 6 3 final
@anchor{whatsnew/changelog id586}@anchor{1a78}
@subsubsection Build



@itemize -

@item 
bpo-31662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31662}: Fix typos in Windows @code{uploadrelease.bat} script. Fix Windows
Doc build issues in @code{Doc/make.bat}.

@item 
bpo-31423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31423}: Fix building the PDF documentation with newer versions of
Sphinx.
@end itemize

@node Python 3 6 3 release candidate 1,Python 3 6 2 final,Python 3 6 3 final,Changelog
@anchor{whatsnew/changelog python-3-6-3-release-candidate-1}@anchor{1a79}
@subsection Python 3.6.3 release candidate 1


`Release date: 2017-09-18'

@menu
* Security: Security<40>. 
* Core and Builtins: Core and Builtins<66>. 
* Library: Library<67>. 
* Documentation: Documentation<60>. 
* Tests: Tests<61>. 
* Build: Build<65>. 
* Windows: Windows<58>. 
* IDLE: IDLE<49>. 
* Tools/Demos: Tools/Demos<35>. 

@end menu

@node Security<40>,Core and Builtins<66>,,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id587}@anchor{1a7a}
@subsubsection Security



@itemize -

@item 
bpo-29781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29781}: SSLObject.version() now correctly returns None when handshake
over BIO has not been performed yet.

@item 
bpo-30947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30947}: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to
get security fixes.
@end itemize

@node Core and Builtins<66>,Library<67>,Security<40>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id588}@anchor{1a7b}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-31471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31471}: Fix an assertion failure in @code{subprocess.Popen()} on Windows,
in case the env argument has a bad @code{keys()} method. Patch by Oren
Milman.

@item 
bpo-31418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31418}: Fix an assertion failure in @code{PyErr_WriteUnraisable()} in case
of an exception with a bad @code{__module__} attribute. Patch by Oren Milman.

@item 
bpo-31416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31416}: Fix assertion failures in case of a bad warnings.filters or
warnings.defaultaction. Patch by Oren Milman.

@item 
bpo-31411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31411}: Raise a TypeError instead of SystemError in case
warnings.onceregistry is not a dictionary. Patch by Oren Milman.

@item 
bpo-31373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31373}: Fix several possible instances of undefined behavior due to
floating-point demotions.

@item 
bpo-30465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30465}: Location information (@code{lineno} and @code{col_offset}) in
f-strings is now (mostly) correct.  This fixes tools like flake8 from
showing warnings on the wrong line (typically the first line of the file).

@item 
bpo-31343@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31343}: Include sys/sysmacros.h for major(), minor(), and makedev().
GNU C libray plans to remove the functions from sys/types.h.

@item 
bpo-31291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31291}: Fix an assertion failure in @code{zipimport.zipimporter.get_data}
on Windows, when the return value of @code{pathname.replace('/','\\')} isn't
a string. Patch by Oren Milman.

@item 
bpo-31271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31271}: Fix an assertion failure in the @code{write()} method of
@code{io.TextIOWrapper}, when the encoder doesn't return a bytes object.
Patch by Oren Milman.

@item 
bpo-31243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31243}: Fix a crash in some methods of @code{io.TextIOWrapper}, when the
decoder's state is invalid. Patch by Oren Milman.

@item 
bpo-30721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30721}: @code{print} now shows correct usage hint for using Python 2
redirection syntax.  Patch by Sanyam Khurana.

@item 
bpo-31070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31070}: Fix a race condition in importlib _get_module_lock().

@item 
bpo-31095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31095}: Fix potential crash during GC caused by @code{tp_dealloc} which
doesn't call @code{PyObject_GC_UnTrack()}.

@item 
bpo-31071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31071}: Avoid masking original TypeError in call with * unpacking when
other arguments are passed.

@item 
bpo-30978@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30978}: str.format_map() now passes key lookup exceptions through.
Previously any exception was replaced with a KeyError exception.

@item 
bpo-30808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30808}: Use _Py_atomic API for concurrency-sensitive signal state.

@item 
bpo-30876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30876}: Relative import from unloaded package now reimports the package
instead of failing with SystemError.  Relative import from non-package now
fails with ImportError rather than SystemError.

@item 
bpo-30703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30703}: Improve signal delivery. Avoid using Py_AddPendingCall from
signal handler, to avoid calling signal-unsafe functions. The tests I'm
adding here fail without the rest of the patch, on Linux and OS X. This
means our signal delivery logic had defects (some signals could be lost).

@item 
bpo-30765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30765}: Avoid blocking in pthread_mutex_lock() when
PyThread_acquire_lock() is asked not to block.

@item 
bpo-31161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31161}: Make sure the 'Missing parentheses' syntax error message is
only applied to SyntaxError, not to subclasses. Patch by Martijn Pieters.

@item 
bpo-30814@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30814}: Fixed a race condition when import a submodule from a package.

@item 
bpo-30597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30597}: @code{print} now shows expected input in custom error message when
used as a Python 2 statement. Patch by Sanyam Khurana.
@end itemize

@node Library<67>,Documentation<60>,Core and Builtins<66>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id589}@anchor{1a7c}
@subsubsection Library



@itemize -

@item 
bpo-31499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31499}: xml.etree: Fix a crash when a parser is part of a reference
cycle.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: typing.get_type_hints now finds the right globalns for classes
and modules by default (when no @code{globalns} was specified by the caller).

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Speed improvements to the @code{typing} module.  Original PRs by
Ivan Levkivskyi and Mitar.

@item 
bpo-31544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31544}: The C accelerator module of ElementTree ignored exceptions
raised when looking up TreeBuilder target methods in XMLParser().

@item 
bpo-31234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31234}: socket.create_connection() now fixes manually a reference
cycle: clear the variable storing the last exception on success.

@item 
bpo-31457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31457}: LoggerAdapter objects can now be nested.

@item 
bpo-31400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31400}: Improves SSL error handling to avoid losing error numbers.

@item 
bpo-28958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28958}: ssl.SSLContext() now uses OpenSSL error information when a
context cannot be instantiated.

@item 
bpo-27340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27340}: SSLSocket.sendall() now uses memoryview to create slices of
data. This fixes support for all bytes-like object. It is also more
efficient and avoids costly copies.

@item 
bpo-31178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31178}: Fix string concatenation bug in rare error path in the
subprocess module

@item 
bpo-31350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31350}: Micro-optimize @code{asyncio._get_running_loop()} to become up
to 10% faster.

@item 
bpo-31170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31170}: expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of
partial characters for UTF-8 input (libexpat bug 115):
@indicateurl{https://github.com/libexpat/libexpat/issues/115}

@item 
bpo-29136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29136}: Add TLS 1.3 cipher suites and OP_NO_TLSv1_3.

@item 
bpo-29212@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29212}: Fix concurrent.futures.thread.ThreadPoolExecutor threads to
have a non repr() based thread name by default when no thread_name_prefix
is supplied. They will now identify themselves as
"ThreadPoolExecutor-y_n".

@item 
bpo-9146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9146}: Fix a segmentation fault in _hashopenssl when standard hash
functions such as md5 are not available in the linked OpenSSL library.  As
in some special FIPS-140 build environments.

@item 
bpo-27144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27144}: The @code{map()} and @code{as_completed()} iterators in
@code{concurrent.futures} now avoid keeping a reference to yielded objects.

@item 
bpo-10746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10746}: Fix ctypes producing wrong 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} type codes for integer
types.

@item 
bpo-22536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22536}: The subprocess module now sets the filename when
FileNotFoundError is raised on POSIX systems due to the executable or cwd
not being found.

@item 
bpo-31249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31249}: concurrent.futures: WorkItem.run() used by ThreadPoolExecutor
now breaks a reference cycle between an exception object and the WorkItem
object.

@item 
bpo-31247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31247}: xmlrpc.server now explicitly breaks reference cycles when using
sys.exc_info() in code handling exceptions.

@item 
bpo-30102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30102}: The ssl and hashlib modules now call
OPENSSL_add_all_algorithms_noconf() on OpenSSL < 1.1.0. The function
detects CPU features and enables optimizations on some CPU architectures
such as POWER8. Patch is based on research from Gustavo Serra Scalet.

@item 
bpo-31185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31185}: Fixed miscellaneous errors in asyncio speedup module.

@item 
bpo-31135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31135}: ttk: fix the destroy() method of LabeledScale and OptionMenu
classes. Call the parent destroy() method even if the used attribute
doesn't exist. The LabeledScale.destroy() method now also explicitly
clears label and scale attributes to help the garbage collector to destroy
all widgets.

@item 
bpo-31107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31107}: Fix @code{copyreg._slotnames()} mangled attribute calculation for
classes whose name begins with an underscore. Patch by Shane Harvey.

@item 
bpo-31061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31061}: Fixed a crash when using asyncio and threads.

@item 
bpo-30502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30502}: Fix handling of long oids in ssl.  Based on patch by Christian
Heimes.

@item 
bpo-30119@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30119}: ftplib.FTP.putline() now throws ValueError on commands that
contains CR or LF. Patch by Donghee Na.

@item 
bpo-30595@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30595}: multiprocessing.Queue.get() with a timeout now polls its reader
in non-blocking mode if it succeeded to acquire the lock but the acquire
took longer than the timeout.

@item 
bpo-29403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29403}: Fix @code{unittest.mock}'s autospec to not fail on method-bound
builtin functions.  Patch by Aaron Gallagher.

@item 
bpo-30961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30961}: Fix decrementing a borrowed reference in tracemalloc.

@item 
bpo-25684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25684}: Change @code{ttk.OptionMenu} radiobuttons to be unique across
instances of @code{OptionMenu}.

@item 
bpo-30886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30886}: Fix multiprocessing.Queue.join_thread(): it now waits until the
thread completes, even if the thread was started by the same process which
created the queue.

@item 
bpo-29854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29854}: Fix segfault in readline when using readline's history-size
option.  Patch by Nir Soffer.

@item 
bpo-30319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30319}: socket.close() now ignores ECONNRESET error.

@item 
bpo-30828@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30828}: Fix out of bounds write in
@code{asyncio.CFuture.remove_done_callback()}.

@item 
bpo-30807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30807}: signal.setitimer() may disable the timer when passed a tiny
value. Tiny values (such as 1e-6) are valid non-zero values for
setitimer(), which is specified as taking microsecond-resolution
intervals. However, on some platform, our conversion routine could convert
1e-6 into a zero interval, therefore disabling the timer instead of
(re-)scheduling it.

@item 
bpo-30441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30441}: Fix bug when modifying os.environ while iterating over it

@item 
bpo-30532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30532}: Fix email header value parser dropping folding white space in
certain cases.

@item 
bpo-30879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30879}: os.listdir() and os.scandir() now emit bytes names when called
with bytes-like argument.

@item 
bpo-30746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30746}: Prohibited the '=' character in environment variable names in
@code{os.putenv()} and @code{os.spawn*()}.

@item 
bpo-29755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29755}: Fixed the lgettext() family of functions in the gettext module.
They now always return bytes.
@end itemize

@node Documentation<60>,Tests<61>,Library<67>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id590}@anchor{1a7d}
@subsubsection Documentation



@itemize -

@item 
bpo-31294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31294}: Fix incomplete code snippet in the ZeroMQSocketListener and
ZeroMQSocketHandler examples and adapt them to Python 3.

@item 
bpo-21649@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21649}: Add RFC 7525 and Mozilla server side TLS links to SSL
documentation.

@item 
bpo-30803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30803}: Clarify doc on truth value testing. Original patch by Peter
Thomassen.
@end itemize

@node Tests<61>,Build<65>,Documentation<60>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id591}@anchor{1a7e}
@subsubsection Tests



@itemize -

@item 
bpo-31320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31320}: Silence traceback in test_ssl

@item 
bpo-25674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25674}: Remove sha256.tbs-internet.com ssl test

@item 
bpo-30715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30715}: Address ALPN callback changes for OpenSSL 1.1.0f. The latest
version behaves like OpenSSL 1.0.2 and no longer aborts handshake.

@item 
bpo-30822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30822}: regrtest: Exclude tzdata from regrtest --all. When running the
test suite using --use=all / -u all, exclude tzdata since it makes
test_datetime too slow (15-20 min on some buildbots) which then times out
on some buildbots. Fix also regrtest command line parser to allow passing
-u extralargefile to run test_zipfile64.
@end itemize

@node Build<65>,Windows<58>,Tests<61>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id592}@anchor{1a7f}
@subsubsection Build



@itemize -

@item 
bpo-30854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30854}: Fix compile error when compiling --without-threads. Patch by
Masayuki Yamamoto.
@end itemize

@node Windows<58>,IDLE<49>,Build<65>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id593}@anchor{1a80}
@subsubsection Windows



@itemize -

@item 
bpo-30389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30389}: Adds detection of Visual Studio 2017 to distutils on Windows.

@item 
bpo-31340@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31340}: Change to building with MSVC v141 (included with Visual Studio
2017)

@item 
bpo-30581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30581}: os.cpu_count() now returns the correct number of processors on
Windows when the number of logical processors is greater than 64.

@item 
bpo-30731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30731}: Add a missing xmlns to python.manifest so that it matches the
schema.
@end itemize

@node IDLE<49>,Tools/Demos<35>,Windows<58>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id594}@anchor{1a81}
@subsubsection IDLE



@itemize -

@item 
bpo-31493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31493}: IDLE code context -- fix code update and font update timers.
Canceling timers prevents a warning message when test_idle completes.

@item 
bpo-31488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31488}: IDLE - Update non-key options in former extension classes. When
applying configdialog changes, call .reload for each feature class. Change
ParenMatch so updated options affect existing instances attached to
existing editor windows.

@item 
bpo-31477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31477}: IDLE - Improve rstrip entry in doc. Strip trailing whitespace
strips more than blank spaces.  Multiline string literals are not skipped.

@item 
bpo-31480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31480}: IDLE - make tests pass with zzdummy extension disabled by
default.

@item 
bpo-31421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31421}: Document how IDLE runs tkinter programs. IDLE calls tcl/tk
update in the background in order to make live interaction and
experimentation with tkinter applications much easier.

@item 
bpo-31414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31414}: IDLE -- fix tk entry box tests by deleting first. Adding to an
int entry is not the same as deleting and inserting because int('@w{'}) will
fail.

@item 
bpo-31051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31051}: Rearrange IDLE configdialog GenPage into Window, Editor, and
Help sections.

@item 
bpo-30617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30617}: IDLE - Add docstrings and tests for outwin subclass of editor.
Move some data and functions from the class to module level. Patch by
Cheryl Sabella.

@item 
bpo-31287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31287}: IDLE - Do not modify tkinter.message in test_configdialog.

@item 
bpo-27099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27099}: Convert IDLE's built-in 'extensions' to regular features. About
10 IDLE features were implemented as supposedly optional extensions. Their
different behavior could be confusing or worse for users and not good for
maintenance. Hence the conversion. The main difference for users is that
user configurable key bindings for builtin features are now handled
uniformly. Now, editing a binding in a keyset only affects its value in
the keyset. All bindings are defined together in the system-specific
default keysets in config-extensions.def. All custom keysets are saved as
a whole in config-extension.cfg.  All take effect as soon as one clicks
Apply or Ok. The affected events are '<<force-open-completions>>',
'<<expand-word>>', '<<force-open-calltip>>', '<<flash-paren>>',
'<<format-paragraph>>', '<<run-module>>', '<<check-module>>', and
'<<zoom-height>>'.  Any (global) customizations made before 3.6.3 will not
affect their keyset-specific customization after 3.6.3. and vice versa.
Initial patch by Charles Wohlganger.

@item 
bpo-31206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31206}: IDLE: Factor HighPage(Frame) class from ConfigDialog. Patch by
Cheryl Sabella.

@item 
bpo-31001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31001}: Add tests for configdialog highlight tab.  Patch by Cheryl
Sabella.

@item 
bpo-31205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31205}: IDLE: Factor KeysPage(Frame) class from ConfigDialog.  The
slightly modified tests continue to pass.  Patch by Cheryl Sabella.

@item 
bpo-31130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31130}: IDLE -- stop leaks in test_configdialog. Initial patch by
Victor Stinner.

@item 
bpo-31002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31002}: Add tests for configdialog keys tab. Patch by Cheryl Sabella.

@item 
bpo-19903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19903}: IDLE: Calltips use @code{inspect.signature} instead of
@code{inspect.getfullargspec}. This improves calltips for builtins converted
to use Argument Clinic. Patch by Louie Lu.

@item 
bpo-31083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31083}: IDLE - Add an outline of a TabPage class in configdialog.
Update existing classes to match outline. Initial patch by Cheryl Sabella.

@item 
bpo-31050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31050}: Factor GenPage(Frame) class from ConfigDialog. The slightly
modified tests continue to pass. Patch by Cheryl Sabella.

@item 
bpo-31004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31004}: IDLE - Factor FontPage(Frame) class from ConfigDialog. Slightly
modified tests continue to pass. Fix General tests. Patch mostly by Cheryl
Sabella.

@item 
bpo-30781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30781}: IDLE - Use ttk widgets in ConfigDialog. Patches by Terry Jan
Reedy and Cheryl Sabella.

@item 
bpo-31060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31060}: IDLE - Finish rearranging methods of ConfigDialog Grouping
methods pertaining to each tab and the buttons will aid writing tests and
improving the tabs and will enable splitting the groups into classes.

@item 
bpo-30853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30853}: IDLE -- Factor a VarTrace class out of ConfigDialog. Instance
tracers manages pairs consisting of a tk variable and a callback function.
When tracing is turned on, setting the variable calls the function.  Test
coverage for the new class is 100%.

@item 
bpo-31003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31003}: IDLE: Add more tests for General tab.

@item 
bpo-30993@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30993}: IDLE - Improve configdialog font page and tests. In
configdialog: Document causal pathways in create_font_tab docstring.
Simplify some attribute names. Move set_samples calls to var_changed_font
(idea from Cheryl Sabella).  Move related functions to positions after the
create widgets function. In test_configdialog: Fix test_font_set so not
order dependent.  Fix renamed test_indent_scale so it tests the widget.
Adjust tests for movement of set_samples call.  Add tests for load
functions.  Put all font tests in one class and tab indent tests in
another.  Except for two lines, these tests completely cover the related
functions.

@item 
bpo-30981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30981}: IDLE -- Add more configdialog font page tests.

@item 
bpo-28523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28523}: IDLE: replace 'colour' with 'color' in configdialog.

@item 
bpo-30917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30917}: Add tests for idlelib.config.IdleConf. Increase coverage from
46% to 96%. Patch by Louie Lu.

@item 
bpo-30934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30934}: Document coverage details for idlelib tests. Add section to
idlelib/idle-test/README.txt. Include check that branches are taken both
ways. Exclude IDLE-specific code that does not run during unit tests.

@item 
bpo-30913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30913}: IDLE: Document ConfigDialog tk Vars, methods, and widgets in
docstrings This will facilitate improving the dialog and splitting up the
class. Original patch by Cheryl Sabella.

@item 
bpo-30899@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30899}: IDLE: Add tests for ConfigParser subclasses in config. Patch by
Louie Lu.

@item 
bpo-30881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30881}: IDLE: Add docstrings to browser.py. Patch by Cheryl Sabella.

@item 
bpo-30851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30851}: IDLE: Remove unused variables in configdialog.  One is a
duplicate, one is set but cannot be altered by users. Patch by Cheryl
Sabella.

@item 
bpo-30870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30870}: IDLE: In Settings dialog, select font with Up, Down keys as
well as mouse. Initial patch by Louie Lu.

@item 
bpo-8231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8231}: IDLE: call config.IdleConf.GetUserCfgDir only once.

@item 
bpo-30779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30779}: IDLE: Factor ConfigChanges class from configdialog, put in
config; test. * In config, put dump test code in a function; run it and
unittest in   'if __name__ == '__main__'. * Add class config.ConfigChanges
based on changes_class_v4.py on bpo issue. * Add class
test_config.ChangesTest, partly using configdialog_tests_v1.py. * Revise
configdialog to use ConfigChanges; see tracker msg297804. * Revise
test_configdialog to match configdialog changes. * Remove configdialog
functions unused or moved to ConfigChanges. Cheryl Sabella contributed
parts of the patch.

@item 
bpo-30777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30777}: IDLE: configdialog - Add docstrings and fix comments. Patch by
Cheryl Sabella.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: IDLE: Improve textview with docstrings, PEP8 names, and more
tests. Patch by Cheryl Sabella.

@item 
bpo-30723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30723}: IDLE: Make several improvements to parenmatch. Add 'parens'
style to highlight both opener and closer. Make 'default' style, which is
not default, a synonym for 'opener'. Make time-delay work the same with
all styles. Add help for config dialog extensions tab, including help for
parenmatch. Add new tests.  Original patch by Charles Wohlganger.

@item 
bpo-30674@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30674}: IDLE: add docstrings to grep module. Patch by Cheryl Sabella

@item 
bpo-21519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21519}: IDLE's basic custom key entry dialog now detects duplicates
properly. Original patch by Saimadhav Heblikar.

@item 
bpo-29910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29910}: IDLE no longer deletes a character after commenting out a
region by a key shortcut.  Add @code{return 'break'} for this and other
potential conflicts between IDLE and default key bindings.

@item 
bpo-30728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30728}: Review and change idlelib.configdialog names. Lowercase method
and attribute names. Replace 'colour' with 'color', expand overly cryptic
names, delete unneeded underscores. Replace @code{import *} with specific
imports. Patches by Cheryl Sabella.

@item 
bpo-6739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6739}: IDLE: Verify user-entered key sequences by trying to bind them
with tk. Add tests for all 3 validation functions. Original patch by G
Polo.  Tests added by Cheryl Sabella.
@end itemize

@node Tools/Demos<35>,,IDLE<49>,Python 3 6 3 release candidate 1
@anchor{whatsnew/changelog id595}@anchor{1a82}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-30983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30983}: gdb integration commands (py-bt, etc.) work on optimized shared
builds now, too.  
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} introduced _PyEval_EvalFrameDefault which
inlines PyEval_EvalFrameEx on non-debug shared builds.  This broke the
ability to use py-bt, py-up, and a few other Python-specific gdb
integrations. The problem is fixed by only looking for
_PyEval_EvalFrameDefault frames in python-gdb.py.  Original patch by Bruno
"Polaco" Penteado.
@end itemize

@node Python 3 6 2 final,Python 3 6 2 release candidate 2,Python 3 6 3 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-2-final}@anchor{1a83}
@subsection Python 3.6.2 final


`Release date: 2017-07-17'

No changes since release candidate 2

@node Python 3 6 2 release candidate 2,Python 3 6 2 release candidate 1,Python 3 6 2 final,Changelog
@anchor{whatsnew/changelog python-3-6-2-release-candidate-2}@anchor{1a84}
@subsection Python 3.6.2 release candidate 2


`Release date: 2017-07-07'

@menu
* Security: Security<41>. 

@end menu

@node Security<41>,,,Python 3 6 2 release candidate 2
@anchor{whatsnew/changelog id596}@anchor{1a85}
@subsubsection Security



@itemize -

@item 
bpo-30730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30730}: Prevent environment variables injection in subprocess on
Windows.  Prevent passing other environment variables and command
arguments.

@item 
bpo-30694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30694}: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple
security vulnerabilities including: 
@geindex Common Vulnerabilities and Exposures; CVE 2017-9233
CVE 2017-9233@footnote{https://www.cve.org/CVERecord?id=CVE-2017-9233} (External entity
infinite loop DoS), 
@geindex Common Vulnerabilities and Exposures; CVE 2016-9063
CVE 2016-9063@footnote{https://www.cve.org/CVERecord?id=CVE-2016-9063} (Integer overflow, re-fix),
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718} (Fix regression bugs from 2.2.0's fix to
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718}) and 
@geindex Common Vulnerabilities and Exposures; CVE 2012-0876
CVE 2012-0876@footnote{https://www.cve.org/CVERecord?id=CVE-2012-0876} (Counter hash flooding with
SipHash). Note: the 
@geindex Common Vulnerabilities and Exposures; CVE 2016-5300
CVE 2016-5300@footnote{https://www.cve.org/CVERecord?id=CVE-2016-5300} (Use os-specific entropy sources like
getrandom) doesn't impact Python, since Python already gets entropy from
the OS to set the expat secret using @code{XML_SetHashSalt()}.

@item 
bpo-30500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30500}: Fix urllib.parse.splithost() to correctly parse fragments. For
example, @code{splithost('//127.0.0.1#@@evil.com/')} now correctly returns the
@code{127.0.0.1} host, instead of treating @code{@@evil.com} as the host in an
authentication (@code{login@@host}).
@end itemize

@node Python 3 6 2 release candidate 1,Python 3 6 1 final,Python 3 6 2 release candidate 2,Changelog
@anchor{whatsnew/changelog python-3-6-2-release-candidate-1}@anchor{1a86}
@subsection Python 3.6.2 release candidate 1


`Release date: 2017-06-17'

@menu
* Security: Security<42>. 
* Core and Builtins: Core and Builtins<67>. 
* Library: Library<68>. 
* IDLE: IDLE<50>. 
* C API: C API<60>. 
* Build: Build<66>. 
* Documentation: Documentation<61>. 
* Tools/Demos: Tools/Demos<36>. 
* Tests: Tests<62>. 
* Windows: Windows<59>. 

@end menu

@node Security<42>,Core and Builtins<67>,,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id597}@anchor{1a87}
@subsubsection Security



@itemize -

@item 
bpo-29591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29591}: Update expat copy from 2.1.1 to 2.2.0 to get fixes of
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718} and 
@geindex Common Vulnerabilities and Exposures; CVE 2016-4472
CVE 2016-4472@footnote{https://www.cve.org/CVERecord?id=CVE-2016-4472}. See
@indicateurl{https://sourceforge.net/p/expat/bugs/537/} for more information.
@end itemize

@node Core and Builtins<67>,Library<68>,Security<42>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id598}@anchor{1a88}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-30682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30682}: Removed a too-strict assertion that failed for certain
f-strings, such as eval("f'\n'") and eval("f'\r'").

@item 
bpo-30604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30604}: Move co_extra_freefuncs to not be per-thread to avoid crashes

@item 
bpo-29104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29104}: Fixed parsing backslashes in f-strings.

@item 
bpo-27945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27945}: Fixed various segfaults with dict when input collections are
mutated during searching, inserting or comparing.  Based on patches by
Duane Griffin and Tim Mitchell.

@item 
bpo-25794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25794}: Fixed type.__setattr__() and type.__delattr__() for
non-interned attribute names.  Based on patch by Eryk Sun.

@item 
bpo-30039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30039}: If a KeyboardInterrupt happens when the interpreter is in the
middle of resuming a chain of nested 'yield from' or 'await' calls, it's
now correctly delivered to the innermost frame.

@item 
bpo-12414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12414}: sys.getsizeof() on a code object now returns the sizes which
includes the code struct and sizes of objects which it references. Patch
by Donghee Na.

@item 
bpo-29949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29949}: Fix memory usage regression of set and frozenset object.

@item 
bpo-29935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29935}: Fixed error messages in the index() method of tuple, list and
deque when pass indices of wrong type.

@item 
bpo-29859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29859}: Show correct error messages when any of the pthread_* calls in
thread_pthread.h fails.

@item 
bpo-28876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28876}: @code{bool(range)} works even if @code{len(range)} raises
@ref{86d,,OverflowError}.

@item 
bpo-29600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29600}: Fix wrapping coroutine return values in StopIteration.

@item 
bpo-28856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28856}: Fix an oversight that %b format for bytes should support
objects follow the buffer protocol.

@item 
bpo-29714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29714}: Fix a regression that bytes format may fail when containing
zero bytes inside.

@item 
bpo-29478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29478}: If max_line_length=None is specified while using the Compat32
policy, it is no longer ignored.  Patch by Mircea Cosbuc.
@end itemize

@node Library<68>,IDLE<50>,Core and Builtins<67>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id599}@anchor{1a89}
@subsubsection Library



@itemize -

@item 
bpo-30616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30616}: Functional API of enum allows to create empty enums. Patched by
Donghee Na

@item 
bpo-30038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30038}: Fix race condition between signal delivery and wakeup file
descriptor. Patch by Nathaniel Smith.

@item 
bpo-23894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23894}: lib2to3 now recognizes @code{rb'...'} and @code{f'...'} strings.

@item 
bpo-23890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23890}: unittest.TestCase.assertRaises() now manually breaks a
reference cycle to not keep objects alive longer than expected.

@item 
bpo-30149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30149}: inspect.signature() now supports callables with
variable-argument parameters wrapped with partialmethod. Patch by Donghee
Na.

@item 
bpo-30645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30645}: Fix path calculation in imp.load_package(), fixing it for cases
when a package is only shipped with bytecodes. Patch by Alexandru
Ardelean.

@item 
bpo-29931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29931}: Fixed comparison check for ipaddress.ip_interface objects.
Patch by Sanjay Sundaresan.

@item 
bpo-30605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30605}: re.compile() no longer raises a BytesWarning when compiling a
bytes instance with misplaced inline modifier.  Patch by Roy Williams.

@item 
bpo-24484@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24484}: Avoid race condition in multiprocessing cleanup (#2159)

@item 
bpo-28994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28994}: The traceback no longer displayed for SystemExit raised in a
callback registered by atexit.

@item 
bpo-30508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30508}: Don't log exceptions if Task/Future "cancel()" method was
called.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Updates to typing module: Add generic AsyncContextManager, add
support for ContextManager on all versions. Original PRs by Jelle Zijlstra
and Ivan Levkivskyi

@item 
bpo-29870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29870}: Fix ssl sockets leaks when connection is aborted in asyncio/ssl
implementation. Patch by Michaël Sghaïer.

@item 
bpo-29743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29743}: Closing transport during handshake process leaks open socket.
Patch by Nikolay Kim

@item 
bpo-27585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27585}: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu
Sornay.

@item 
bpo-30418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30418}: On Windows, subprocess.Popen.communicate() now also ignore
EINVAL on stdin.write() if the child process is still running but closed
the pipe.

@item 
bpo-29822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29822}: inspect.isabstract() now works during __init_subclass__.  Patch
by Nate Soares.

@item 
bpo-29581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29581}: ABCMeta.__new__ now accepts @code{**kwargs}, allowing abstract
base classes to use keyword parameters in __init_subclass__. Patch by Nate
Soares.

@item 
bpo-30557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30557}: faulthandler now correctly filters and displays exception codes
on Windows

@item 
bpo-30378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30378}: Fix the problem that logging.handlers.SysLogHandler cannot
handle IPv6 addresses.

@item 
bpo-29960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29960}: Preserve generator state when _random.Random.setstate() raises
an exception. Patch by Bryan Olson.

@item 
bpo-30414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30414}: multiprocessing.Queue._feed background running thread do not
break from main loop on exception.

@item 
bpo-30003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30003}: Fix handling escape characters in HZ codec.  Based on patch by
Ma Lin.

@item 
bpo-30301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30301}: Fix AttributeError when using SimpleQueue.empty() under `spawn'
and `forkserver' start methods.

@item 
bpo-30329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30329}: imaplib and poplib now catch the Windows socket WSAEINVAL error
(code 10022) on shutdown(SHUT_RDWR): An invalid operation was attempted.
This error occurs sometimes on SSL connections.

@item 
bpo-30375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30375}: Warnings emitted when compile a regular expression now always
point to the line in the user code.  Previously they could point into
inners of the re module if emitted from inside of groups or conditionals.

@item 
bpo-30048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30048}: Fixed @code{Task.cancel()} can be ignored when the task is running
coroutine and the coroutine returned without any more @code{await}.

@item 
bpo-30266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30266}: contextlib.AbstractContextManager now supports
anti-registration by setting __enter__ = None or __exit__ = None,
following the pattern introduced in bpo-25958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25958}. Patch by Jelle Zijlstra.

@item 
bpo-30298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30298}: Weaken the condition of deprecation warnings for inline
modifiers. Now allowed several subsequential inline modifiers at the start
of the pattern (e.g. @code{'(?i)(?s)...'}).  In verbose mode whitespaces and
comments now are allowed before and between inline modifiers (e.g. @code{'(?x)
(?i) (?s)...'}).

@item 
bpo-29990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29990}: Fix range checking in GB18030 decoder.  Original patch by Ma
Lin.

@item 
bpo-26293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26293}: Change resulted because of zipfile breakage. (See also:
bpo-29094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29094})

@item 
bpo-30243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30243}: Removed the __init__ methods of _json's scanner and encoder.
Misusing them could cause memory leaks or crashes.  Now scanner and
encoder objects are completely initialized in the __new__ methods.

@item 
bpo-30185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30185}: Avoid KeyboardInterrupt tracebacks in forkserver helper process
when Ctrl-C is received.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Various updates to typing module: add typing.NoReturn type, use
WrapperDescriptorType, minor bug-fixes.  Original PRs by Jim
Fasarakis-Hilliard and Ivan Levkivskyi.

@item 
bpo-30205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30205}: Fix getsockname() for unbound AF_UNIX sockets on Linux.

@item 
bpo-30070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30070}: Fixed leaks and crashes in errors handling in the parser
module.

@item 
bpo-30061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30061}: Fixed crashes in IOBase methods __next__() and readlines() when
readline() or __next__() respectively return non-sizeable object. Fixed
possible other errors caused by not checking results of PyObject_Size(),
PySequence_Size(), or PyMapping_Size().

@item 
bpo-30017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30017}: Allowed calling the close() method of the zip entry writer
object multiple times.  Writing to a closed writer now always produces a
ValueError.

@item 
bpo-30068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30068}: _io._IOBase.readlines will check if it's closed first when hint
is present.

@item 
bpo-29694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29694}: Fixed race condition in pathlib mkdir with flags parents=True.
Patch by Armin Rigo.

@item 
bpo-29692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29692}: Fixed arbitrary unchaining of RuntimeError exceptions in
contextlib.contextmanager.  Patch by Siddharth Velankar.

@item 
bpo-29998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29998}: Pickling and copying ImportError now preserves name and path
attributes.

@item 
bpo-29953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29953}: Fixed memory leaks in the replace() method of datetime and time
objects when pass out of bound fold argument.

@item 
bpo-29942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29942}: Fix a crash in itertools.chain.from_iterable when encountering
long runs of empty iterables.

@item 
bpo-27863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27863}: Fixed multiple crashes in ElementTree caused by race conditions
and wrong types.

@item 
bpo-28699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28699}: Fixed a bug in pools in multiprocessing.pool that raising an
exception at the very first of an iterable may swallow the exception or
make the program hang. Patch by Davin Potts and Xiang Zhang.

@item 
bpo-25803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25803}: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when
the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-29861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29861}: Release references to tasks, their arguments and their results
as soon as they are finished in multiprocessing.Pool.

@item 
bpo-29884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29884}: faulthandler: Restore the old sigaltstack during teardown.
Patch by Christophe Zeitouny.

@item 
bpo-25455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25455}: Fixed crashes in repr of recursive buffered file-like objects.

@item 
bpo-29800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29800}: Fix crashes in partial.__repr__ if the keys of partial.keywords
are not strings.  Patch by Michael Seifert.

@item 
bpo-29742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29742}: get_extra_info() raises exception if get called on closed ssl
transport. Patch by Nikolay Kim.

@item 
bpo-8256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8256}: Fixed possible failing or crashing input() if attributes
"encoding" or "errors" of sys.stdin or sys.stdout are not set or are not
strings.

@item 
bpo-28298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28298}: Fix a bug that prevented array 'Q', 'L' and 'I' from accepting
big intables (objects that have __int__) as elements.  Patch by Oren
Milman.

@item 
bpo-28231@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28231}: The zipfile module now accepts path-like objects for external
paths.

@item 
bpo-26915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26915}: index() and count() methods of collections.abc.Sequence now
check identity before checking equality when do comparisons.

@item 
bpo-29615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29615}: SimpleXMLRPCDispatcher no longer chains KeyError (or any other
exception) to exception(s) raised in the dispatched methods. Patch by Petr
Motejlek.

@item 
bpo-30177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30177}: path.resolve(strict=False) no longer cuts the path after the
first element not present in the filesystem.  Patch by Antoine Pietri.
@end itemize

@node IDLE<50>,C API<60>,Library<68>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id600}@anchor{1a8a}
@subsubsection IDLE



@itemize -

@item 
bpo-15786@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15786}: Fix several problems with IDLE's autocompletion box. The
following should now work: clicking on selection box items; using the
scrollbar; selecting an item by hitting Return. Hangs on MacOSX should no
longer happen. Patch by Louie Lu.

@item 
bpo-25514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25514}: Add doc subsubsection about IDLE failure to start. Popup
no-connection message directs users to this section.

@item 
bpo-30642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30642}: Fix reference leaks in IDLE tests. Patches by Louie Lu and
Terry Jan Reedy.

@item 
bpo-30495@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30495}: Add docstrings for textview.py and use PEP8 names. Patches by
Cheryl Sabella and Terry Jan Reedy.

@item 
bpo-30290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30290}: Help-about: use pep8 names and add tests. Increase coverage to
100%. Patches by Louie Lu, Cheryl Sabella, and Terry Jan Reedy.

@item 
bpo-30303@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30303}: Add _utest option to textview; add new tests. Increase coverage
to 100%. Patches by Louie Lu and Terry Jan Reedy.
@end itemize

@node C API<60>,Build<66>,IDLE<50>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id601}@anchor{1a8b}
@subsubsection C API



@itemize -

@item 
bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}: Function PySlice_GetIndicesEx() no longer replaced with a macro
if Py_LIMITED_API is not set.
@end itemize

@node Build<66>,Documentation<61>,C API<60>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id602}@anchor{1a8c}
@subsubsection Build



@itemize -

@item 
bpo-29941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29941}: Add @code{--with-assertions} configure flag to explicitly enable C
@code{assert()} checks. Defaults to off. @code{--with-pydebug} implies
@code{--with-assertions}.

@item 
bpo-28787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28787}: Fix out-of-tree builds of Python when configured with
@code{--with--dtrace}.

@item 
bpo-29243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29243}: Prevent unnecessary rebuilding of Python during @code{make test},
@code{make install} and some other make targets when configured with
@code{--enable-optimizations}.

@item 
bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}: Don't regenerate generated files based on file modification
time anymore: the action is now explicit. Replace @code{make touch} with
@code{make regen-all}.

@item 
bpo-29643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29643}: Fix @code{--enable-optimization} didn't work.
@end itemize

@node Documentation<61>,Tools/Demos<36>,Build<66>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id603}@anchor{1a8d}
@subsubsection Documentation



@itemize -

@item 
bpo-30176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30176}: Add missing attribute related constants in curses
documentation.

@item 
bpo-30052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30052}: the link targets for @ref{1bd,,bytes()} and @ref{528,,bytearray()} are
now their respective type definitions, rather than the corresponding
builtin function entries. Use @ref{1a47,,bytes} and
@ref{1a48,,bytearray} to reference the latter. In order to
ensure this and future cross-reference updates are applied automatically,
the daily documentation builds now disable the default output caching
features in Sphinx.

@item 
bpo-26985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26985}: Add missing info of code object in inspect documentation.
@end itemize

@node Tools/Demos<36>,Tests<62>,Documentation<61>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id604}@anchor{1a8e}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-29367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29367}: python-gdb.py now supports also @code{method-wrapper}
(@code{wrapperobject}) objects.
@end itemize

@node Tests<62>,Windows<59>,Tools/Demos<36>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id605}@anchor{1a8f}
@subsubsection Tests



@itemize -

@item 
bpo-30357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30357}: test_thread: setUp() now uses support.threading_setup() and
support.threading_cleanup() to wait until threads complete to avoid random
side effects on following tests. Initial patch written by Grzegorz
Grzywacz.

@item 
bpo-30197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30197}: Enhanced functions swap_attr() and swap_item() in the
test.support module. They now work when delete replaced attribute or item
inside the with statement.  The old value of the attribute or item (or
None if it doesn't exist) now will be assigned to the target of the "as"
clause, if there is one.
@end itemize

@node Windows<59>,,Tests<62>,Python 3 6 2 release candidate 1
@anchor{whatsnew/changelog id606}@anchor{1a90}
@subsubsection Windows



@itemize -

@item 
bpo-30687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30687}: Locate msbuild.exe on Windows when building rather than
vcvarsall.bat

@item 
bpo-30450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30450}: The build process on Windows no longer depends on Subversion,
instead pulling external code from GitHub via a Python script.  If Python
3.6 is not found on the system (via @code{py -3.6}), NuGet is used to
download a copy of 32-bit Python.
@end itemize

@node Python 3 6 1 final,Python 3 6 1 release candidate 1,Python 3 6 2 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-1-final}@anchor{1a91}
@subsection Python 3.6.1 final


`Release date: 2017-03-21'

@menu
* Core and Builtins: Core and Builtins<68>. 
* Build: Build<67>. 

@end menu

@node Core and Builtins<68>,Build<67>,,Python 3 6 1 final
@anchor{whatsnew/changelog id607}@anchor{1a92}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-29723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29723}: The @code{sys.path[0]} initialization change for bpo-29139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29139} caused
a regression by revealing an inconsistency in how sys.path is initialized
when executing @code{__main__} from a zipfile, directory, or other import
location. The interpreter now consistently avoids ever adding the import
location's parent directory to @code{sys.path}, and ensures no other
@code{sys.path} entries are inadvertently modified when inserting the import
location named on the command line.
@end itemize

@node Build<67>,,Core and Builtins<68>,Python 3 6 1 final
@anchor{whatsnew/changelog id608}@anchor{1a93}
@subsubsection Build



@itemize -

@item 
bpo-27593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27593}: fix format of git information used in sys.version

@item 
Fix incompatible comment in python.h
@end itemize

@node Python 3 6 1 release candidate 1,Python 3 6 0 final,Python 3 6 1 final,Changelog
@anchor{whatsnew/changelog python-3-6-1-release-candidate-1}@anchor{1a94}
@subsection Python 3.6.1 release candidate 1


`Release date: 2017-03-04'

@menu
* Core and Builtins: Core and Builtins<69>. 
* Library: Library<69>. 
* IDLE: IDLE<51>. 
* Windows: Windows<60>. 
* C API: C API<61>. 
* Documentation: Documentation<62>. 
* Tests: Tests<63>. 
* Build: Build<68>. 

@end menu

@node Core and Builtins<69>,Library<69>,,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id609}@anchor{1a95}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-28893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28893}: Set correct __cause__ for errors about invalid awaitables
returned from __aiter__ and __anext__.

@item 
bpo-29683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29683}: Fixes to memory allocation in _PyCode_SetExtra.  Patch by Brian
Coleman.

@item 
bpo-29684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29684}: Fix minor regression of PyEval_CallObjectWithKeywords. It
should raise TypeError when kwargs is not a dict.  But it might cause segv
when args=NULL and kwargs is not a dict.

@item 
bpo-28598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28598}: Support __rmod__ for subclasses of str being called before
str.__mod__. Patch by Martijn Pieters.

@item 
bpo-29607@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29607}: Fix stack_effect computation for CALL_FUNCTION_EX. Patch by
Matthieu Dartiailh.

@item 
bpo-29602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29602}: Fix incorrect handling of signed zeros in complex constructor
for complex subclasses and for inputs having a __complex__ method. Patch
by Serhiy Storchaka.

@item 
bpo-29347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29347}: Fixed possibly dereferencing undefined pointers when creating
weakref objects.

@item 
bpo-29438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29438}: Fixed use-after-free problem in key sharing dict.

@item 
bpo-29319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29319}: Prevent RunMainFromImporter overwriting sys.path[0].

@item 
bpo-29337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29337}: Fixed possible BytesWarning when compare the code objects.
Warnings could be emitted at compile time.

@item 
bpo-29327@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29327}: Fixed a crash when pass the iterable keyword argument to
sorted().

@item 
bpo-29034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29034}: Fix memory leak and use-after-free in os module
(path_converter).

@item 
bpo-29159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29159}: Fix regression in bytes(x) when x.__index__() raises Exception.

@item 
bpo-28932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28932}: Do not include <sys/random.h> if it does not exist.

@item 
bpo-25677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25677}: Correct the positioning of the syntax error caret for indented
blocks. Based on patch by Michael Layzell.

@item 
bpo-29000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29000}: Fixed bytes formatting of octals with zero padding in alternate
form.

@item 
bpo-26919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26919}: On Android, operating system data is now always encoded/decoded
to/from UTF-8, instead of the locale encoding to avoid inconsistencies
with os.fsencode() and os.fsdecode() which are already using UTF-8.

@item 
bpo-28991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28991}: functools.lru_cache() was susceptible to an obscure reentrancy
bug triggerable by a monkey-patched len() function.

@item 
bpo-28739@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28739}: f-string expressions are no longer accepted as docstrings and
by ast.literal_eval() even if they do not include expressions.

@item 
bpo-28512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28512}: Fixed setting the offset attribute of SyntaxError by
PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

@item 
bpo-28918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28918}: Fix the cross compilation of xxlimited when Python has been
built with Py_DEBUG defined.

@item 
bpo-28731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28731}: Optimize _PyDict_NewPresized() to create correct size dict.
Improve speed of dict literal with constant keys up to 30%.
@end itemize

@node Library<69>,IDLE<51>,Core and Builtins<69>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id610}@anchor{1a96}
@subsubsection Library



@itemize -

@item 
bpo-29169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29169}: Update zlib to 1.2.11.

@item 
bpo-29623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29623}: Allow use of path-like object as a single argument in
ConfigParser.read(). Patch by David Ellis.

@item 
bpo-28963@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28963}: Fix out of bound iteration in
asyncio.Future.remove_done_callback implemented in C.

@item 
bpo-29704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29704}: asyncio.subprocess.SubprocessStreamProtocol no longer closes
before all pipes are closed.

@item 
bpo-29271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29271}: Fix Task.current_task and Task.all_tasks implemented in C to
accept None argument as their pure Python implementation.

@item 
bpo-29703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29703}: Fix asyncio to support instantiation of new event loops in
child processes.

@item 
bpo-29376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29376}: Fix assertion error in threading._DummyThread.is_alive().

@item 
bpo-28624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28624}: Add a test that checks that cwd parameter of Popen() accepts
PathLike objects.  Patch by Sayan Chowdhury.

@item 
bpo-28518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28518}: Start a transaction implicitly before a DML statement. Patch by
Aviv Palivoda.

@item 
bpo-29532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29532}: Altering a kwarg dictionary passed to functools.partial() no
longer affects a partial object after creation.

@item 
bpo-29110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29110}: Fix file object leak in aifc.open() when file is given as a
filesystem path and is not in valid AIFF format. Patch by Anthony Zhang.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Various updates to typing module: typing.Counter,
typing.ChainMap, improved ABC caching, etc. Original PRs by Jelle
Zijlstra, Ivan Levkivskyi, Manuel Krebber, and Łukasz Langa.

@item 
bpo-29100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29100}: Fix datetime.fromtimestamp() regression introduced in Python
3.6.0: check minimum and maximum years.

@item 
bpo-29519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29519}: Fix weakref spewing exceptions during interpreter shutdown when
used with a rare combination of multiprocessing and custom codecs.

@item 
bpo-29416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29416}: Prevent infinite loop in pathlib.Path.mkdir

@item 
bpo-29444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29444}: Fixed out-of-bounds buffer access in the group() method of the
match object. Based on patch by WGH.

@item 
bpo-29335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29335}: Fix subprocess.Popen.wait() when the child process has exited
to a stopped instead of terminated state (ex: when under ptrace).

@item 
bpo-29290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29290}: Fix a regression in argparse that help messages would wrap at
non-breaking spaces.

@item 
bpo-28735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28735}: Fixed the comparison of mock.MagickMock with mock.ANY.

@item 
bpo-29316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29316}: Restore the provisional status of typing module, add
corresponding note to documentation. Patch by Ivan L.

@item 
bpo-29219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29219}: Fixed infinite recursion in the repr of uninitialized
ctypes.CDLL instances.

@item 
bpo-29011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29011}: Fix an important omission by adding Deque to the typing module.

@item 
bpo-28969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28969}: Fixed race condition in C implementation of
functools.lru_cache. KeyError could be raised when cached function with
full cache was simultaneously called from different threads with the same
uncached arguments.

@item 
bpo-29142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29142}: In urllib.request, suffixes in no_proxy environment variable
with leading dots could match related hostnames again (e.g. .b.c matches
a.b.c). Patch by Milan Oberkirch.

@item 
bpo-28961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28961}: Fix unittest.mock._Call helper: don't ignore the name parameter
anymore. Patch written by Jiajun Huang.

@item 
bpo-29203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29203}: functools.lru_cache() now respects 
@geindex Python Enhancement Proposals; PEP 468
PEP 468@footnote{https://peps.python.org/pep-0468/} and preserves the
order of keyword arguments.  f(a=1, b=2) is now cached separately from
f(b=2, a=1) since both calls could potentially give different results.

@item 
bpo-15812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15812}: inspect.getframeinfo() now correctly shows the first line of a
context. Patch by Sam Breese.

@item 
bpo-29094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29094}: Offsets in a ZIP file created with extern file object and modes
"w" and "x" now are relative to the start of the file.

@item 
bpo-29085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29085}: Allow random.Random.seed() to use high quality OS randomness
rather than the pid and time.

@item 
bpo-29061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29061}: Fixed bug in secrets.randbelow() which would hang when given a
negative input.  Patch by Brendan Donegan.

@item 
bpo-29079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29079}: Prevent infinite loop in pathlib.resolve() on Windows

@item 
bpo-13051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13051}: Fixed recursion errors in large or resized
curses.textpad.Textbox.  Based on patch by Tycho Andersen.

@item 
bpo-29119@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29119}: Fix weakrefs in the pure python version of
collections.OrderedDict move_to_end() method. Contributed by Andra
Bogildea.

@item 
bpo-9770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9770}: curses.ascii predicates now work correctly with negative
integers.

@item 
bpo-28427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28427}: old keys should not remove new values from WeakValueDictionary
when collecting from another thread.

@item 
bpo-28923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28923}: Remove editor artifacts from Tix.py.

@item 
bpo-29055@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29055}: Neaten-up empty population error on random.choice() by
suppressing the upstream exception.

@item 
bpo-28871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28871}: Fixed a crash when deallocate deep ElementTree.

@item 
bpo-19542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19542}: Fix bugs in WeakValueDictionary.setdefault() and
WeakValueDictionary.pop() when a GC collection happens in another thread.

@item 
bpo-20191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20191}: Fixed a crash in resource.prlimit() when passing a sequence
that doesn't own its elements as limits.

@item 
bpo-28779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28779}: multiprocessing.set_forkserver_preload() would crash the
forkserver process if a preloaded module instantiated some multiprocessing
objects such as locks.

@item 
bpo-28847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28847}: dbm.dumb now supports reading read-only files and no longer
writes the index file when it is not changed.

@item 
bpo-26937@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26937}: The chown() method of the tarfile.TarFile class does not fail
now when the grp module cannot be imported, as for example on Android
platforms.
@end itemize

@node IDLE<51>,Windows<60>,Library<69>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id611}@anchor{1a97}
@subsubsection IDLE



@itemize -

@item 
bpo-29071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29071}: IDLE colors f-string prefixes (but not invalid ur prefixes).

@item 
bpo-28572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28572}: Add 10% to coverage of IDLE's test_configdialog. Update and
augment description of the configuration system.
@end itemize

@node Windows<60>,C API<61>,IDLE<51>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id612}@anchor{1a98}
@subsubsection Windows



@itemize -

@item 
bpo-29579@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29579}: Removes readme.txt from the installer

@item 
bpo-29326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29326}: Ignores blank lines in ._pth files (Patch by Alexey Izbyshev)

@item 
bpo-28164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28164}: Correctly handle special console filenames (patch by Eryk Sun)

@item 
bpo-29409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29409}: Implement 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} for io.FileIO (Patch by Eryk Sun)

@item 
bpo-29392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29392}: Prevent crash when passing invalid arguments into msvcrt
module.

@item 
bpo-25778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25778}: winreg does not truncate string correctly (Patch by Eryk Sun)

@item 
bpo-28896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28896}: Deprecate WindowsRegistryFinder and disable it by default.
@end itemize

@node C API<61>,Documentation<62>,Windows<60>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id613}@anchor{1a99}
@subsubsection C API



@itemize -

@item 
bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}: Function PySlice_GetIndicesEx() is replaced with a macro if
Py_LIMITED_API is not set or set to the value between 0x03050400 and
0x03060000 (not including) or 0x03060100 or higher.

@item 
bpo-29083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29083}: Fixed the declaration of some public API functions.
PyArg_VaParse() and PyArg_VaParseTupleAndKeywords() were not available in
limited API. PyArg_ValidateKeywordArguments(), PyArg_UnpackTuple() and
Py_BuildValue() were not available in limited API of version < 3.3 when
PY_SSIZE_T_CLEAN is defined.

@item 
bpo-29058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29058}: All stable API extensions added after Python 3.2 are now
available only when Py_LIMITED_API is set to the PY_VERSION_HEX value of
the minimum Python version supporting this API.
@end itemize

@node Documentation<62>,Tests<63>,C API<61>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id614}@anchor{1a9a}
@subsubsection Documentation



@itemize -

@item 
bpo-28929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28929}: Link the documentation to its source file on GitHub.

@item 
bpo-25008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25008}: Document smtpd.py as effectively deprecated and add a pointer
to aiosmtpd, a third-party asyncio-based replacement.

@item 
bpo-26355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26355}: Add canonical header link on each page to corresponding major
version of the documentation. Patch by Matthias Bussonnier.

@item 
bpo-29349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29349}: Fix Python 2 syntax in code for building the documentation.
@end itemize

@node Tests<63>,Build<68>,Documentation<62>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id615}@anchor{1a9b}
@subsubsection Tests



@itemize -

@item 
bpo-28087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28087}: Skip test_asyncore and test_eintr poll failures on macOS. Skip
some tests of select.poll when running on macOS due to unresolved issues
with the underlying system poll function on some macOS versions.

@item 
bpo-29571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29571}: to match the behaviour of the @code{re.LOCALE} flag,
test_re.test_locale_flag now uses @code{locale.getpreferredencoding(False)}
to determine the candidate encoding for the test regex (allowing it to
correctly skip the test when the default locale encoding is a multi-byte
encoding)

@item 
bpo-28950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28950}: Disallow -j0 to be combined with -T/-l in regrtest command line
arguments.

@item 
bpo-28683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28683}: Fix the tests that bind() a unix socket and raise
PermissionError on Android for a non-root user.

@item 
bpo-26939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26939}: Add the support.setswitchinterval() function to fix
test_functools hanging on the Android armv7 qemu emulator.
@end itemize

@node Build<68>,,Tests<63>,Python 3 6 1 release candidate 1
@anchor{whatsnew/changelog id616}@anchor{1a9c}
@subsubsection Build



@itemize -

@item 
bpo-27593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27593}: sys.version and the platform module python_build(),
python_branch(), and python_revision() functions now use git information
rather than hg when building from a repo.

@item 
bpo-29572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29572}: Update Windows build and OS X installers to use OpenSSL 1.0.2k.

@item 
bpo-26851@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26851}: Set Android compilation and link flags.

@item 
bpo-28768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28768}: Fix implicit declaration of function _setmode. Patch by
Masayuki Yamamoto

@item 
bpo-29080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29080}: Removes hard dependency on hg.exe from PCBuild/build.bat

@item 
bpo-23903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23903}: Added missed names to PC/python3.def.

@item 
bpo-28762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28762}: lockf() is available on Android API level 24, but the F_LOCK
macro is not defined in android-ndk-r13.

@item 
bpo-28538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28538}: Fix the compilation error that occurs because if_nameindex() is
available on Android API level 24, but the if_nameindex structure is not
defined.

@item 
bpo-20211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20211}: Do not add the directory for installing C header files and the
directory for installing object code libraries to the cross compilation
search paths. Original patch by Thomas Petazzoni.

@item 
bpo-28849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28849}: Do not define sys.implementation._multiarch on Android.
@end itemize

@node Python 3 6 0 final,Python 3 6 0 release candidate 2,Python 3 6 1 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-0-final}@anchor{1a9d}
@subsection Python 3.6.0 final


`Release date: 2016-12-23'

No changes since release candidate 2

@node Python 3 6 0 release candidate 2,Python 3 6 0 release candidate 1,Python 3 6 0 final,Changelog
@anchor{whatsnew/changelog python-3-6-0-release-candidate-2}@anchor{1a9e}
@subsection Python 3.6.0 release candidate 2


`Release date: 2016-12-16'

@menu
* Core and Builtins: Core and Builtins<70>. 
* Tools/Demos: Tools/Demos<37>. 
* Windows: Windows<61>. 
* Build: Build<69>. 

@end menu

@node Core and Builtins<70>,Tools/Demos<37>,,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id617}@anchor{1a9f}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-28147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28147}: Fix a memory leak in split-table dictionaries: setattr() must
not convert combined table into split table. Patch written by INADA Naoki.

@item 
bpo-28990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28990}: Fix asyncio SSL hanging if connection is closed before
handshake is completed. (Patch by HoHo-Ho)
@end itemize

@node Tools/Demos<37>,Windows<61>,Core and Builtins<70>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id618}@anchor{1aa0}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-28770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28770}: Fix python-gdb.py for fastcalls.
@end itemize

@node Windows<61>,Build<69>,Tools/Demos<37>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id619}@anchor{1aa1}
@subsubsection Windows



@itemize -

@item 
bpo-28896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28896}: Deprecate WindowsRegistryFinder.
@end itemize

@node Build<69>,,Windows<61>,Python 3 6 0 release candidate 2
@anchor{whatsnew/changelog id620}@anchor{1aa2}
@subsubsection Build



@itemize -

@item 
bpo-28898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28898}: Prevent gdb build errors due to HAVE_LONG_LONG redefinition.
@end itemize

@node Python 3 6 0 release candidate 1,Python 3 6 0 beta 4,Python 3 6 0 release candidate 2,Changelog
@anchor{whatsnew/changelog python-3-6-0-release-candidate-1}@anchor{1aa3}
@subsection Python 3.6.0 release candidate 1


`Release date: 2016-12-06'

@menu
* Core and Builtins: Core and Builtins<71>. 
* Library: Library<70>. 
* C API: C API<62>. 
* Documentation: Documentation<63>. 
* Tools/Demos: Tools/Demos<38>. 

@end menu

@node Core and Builtins<71>,Library<70>,,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id621}@anchor{1aa4}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}: Rather than silently producing a class that doesn't support
zero-argument @code{super()} in methods, failing to pass the new
@code{__classcell__} namespace entry up to @code{type.__new__} now results in a
@code{DeprecationWarning} and a class that supports zero-argument
@code{super()}.

@item 
bpo-28797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28797}: Modifying the class __dict__ inside the __set_name__ method of
a descriptor that is used inside that class no longer prevents calling the
__set_name__ method of other descriptors.

@item 
bpo-28782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28782}: Fix a bug in the implementation @code{yield from} when checking if
the next instruction is YIELD_FROM. Regression introduced by WORDCODE
(bpo-26647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26647}).
@end itemize

@node Library<70>,C API<62>,Core and Builtins<71>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id622}@anchor{1aa5}
@subsubsection Library



@itemize -

@item 
bpo-27030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27030}: Unknown escapes in re.sub() replacement template are allowed
again.  But they still are deprecated and will be disabled in 3.7.

@item 
bpo-28835@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28835}: Fix a regression introduced in warnings.catch_warnings(): call
warnings.showwarning() if it was overridden inside the context manager.

@item 
bpo-27172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27172}: To assist with upgrades from 2.7, the previously documented
deprecation of @code{inspect.getfullargspec()} has been reversed. This
decision may be revisited again after the Python 2.7 branch is no longer
officially supported.

@item 
bpo-26273@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26273}: Add new @code{socket.TCP_CONGESTION} (Linux 2.6.13) and
@code{socket.TCP_USER_TIMEOUT} (Linux 2.6.37) constants. Patch written
by Omar Sandoval.

@item 
bpo-24142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24142}: Reading a corrupt config file left configparser in an invalid
state. Original patch by Florian Höch.

@item 
bpo-28843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28843}: Fix asyncio C Task to handle exceptions __traceback__.
@end itemize

@node C API<62>,Documentation<63>,Library<70>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id623}@anchor{1aa6}
@subsubsection C API



@itemize -

@item 
bpo-28808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28808}: PyUnicode_CompareWithASCIIString() now never raises exceptions.
@end itemize

@node Documentation<63>,Tools/Demos<38>,C API<62>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id624}@anchor{1aa7}
@subsubsection Documentation



@itemize -

@item 
bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}: The data model reference and the porting section in the What's
New guide now cover the additional @code{__classcell__} handling needed for
custom metaclasses to fully support 
@geindex Python Enhancement Proposals; PEP 487
PEP 487@footnote{https://peps.python.org/pep-0487/} and zero-argument
@code{super()}.
@end itemize

@node Tools/Demos<38>,,Documentation<63>,Python 3 6 0 release candidate 1
@anchor{whatsnew/changelog id625}@anchor{1aa8}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-28023@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28023}: Fix python-gdb.py didn't support new dict implementation.
@end itemize

@node Python 3 6 0 beta 4,Python 3 6 0 beta 3,Python 3 6 0 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-6-0-beta-4}@anchor{1aa9}
@subsection Python 3.6.0 beta 4


`Release date: 2016-11-21'

@menu
* Core and Builtins: Core and Builtins<72>. 
* Library: Library<71>. 
* Documentation: Documentation<64>. 
* Tests: Tests<64>. 
* Build: Build<70>. 

@end menu

@node Core and Builtins<72>,Library<71>,,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id626}@anchor{1aaa}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-28532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28532}: Show sys.version when -V option is supplied twice.

@item 
bpo-27100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27100}: The with-statement now checks for __enter__ before it checks
for __exit__. This gives less confusing error messages when both methods
are missing. Patch by Jonathan Ellington.

@item 
bpo-28746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28746}: Fix the set_inheritable() file descriptor method on platforms
that do not have the ioctl FIOCLEX and FIONCLEX commands.

@item 
bpo-26920@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26920}: Fix not getting the locale's charset upon initializing the
interpreter, on platforms that do not have langinfo.

@item 
bpo-28648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28648}: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X
when decode astral characters.  Patch by Xiang Zhang.

@item 
bpo-19398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19398}: Extra slash no longer added to sys.path components in case of
empty compile-time PYTHONPATH components.

@item 
bpo-28665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28665}: Improve speed of the STORE_DEREF opcode by 40%.

@item 
bpo-28583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28583}: PyDict_SetDefault didn't combine split table when needed. Patch
by Xiang Zhang.

@item 
bpo-27243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27243}: Change PendingDeprecationWarning -> DeprecationWarning. As it
was agreed in the issue, __aiter__ returning an awaitable should result in
PendingDeprecationWarning in 3.5 and in DeprecationWarning in 3.6.

@item 
bpo-26182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26182}: Fix a refleak in code that raises DeprecationWarning.

@item 
bpo-28721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28721}: Fix asynchronous generators aclose() and athrow() to handle
StopAsyncIteration propagation properly.
@end itemize

@node Library<71>,Documentation<64>,Core and Builtins<72>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id627}@anchor{1aab}
@subsubsection Library



@itemize -

@item 
bpo-28752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28752}: Restored the __reduce__() methods of datetime objects.

@item 
bpo-28727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28727}: Regular expression patterns, _sre.SRE_Pattern objects created
by re.compile(), become comparable (only x==y and x!=y operators). This
change should fix the bpo-18383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18383}: don't duplicate warning filters when
the warnings module is reloaded (thing usually only done in unit tests).

@item 
bpo-20572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20572}: The subprocess.Popen.wait method's undocumented endtime
parameter now raises a DeprecationWarning.

@item 
bpo-25659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25659}: In ctypes, prevent a crash calling the from_buffer() and
from_buffer_copy() methods on abstract classes like Array.

@item 
bpo-19717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19717}: Makes Path.resolve() succeed on paths that do not exist. Patch
by Vajrasky Kok

@item 
bpo-28563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28563}: Fixed possible DoS and arbitrary code execution when handle
plural form selections in the gettext module.  The expression parser now
supports exact syntax supported by GNU gettext.

@item 
bpo-28387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28387}: Fixed possible crash in _io.TextIOWrapper deallocator when the
garbage collector is invoked in other thread.  Based on patch by Sebastian
Cufre.

@item 
bpo-28600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28600}: Optimize loop.call_soon.

@item 
bpo-28613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28613}: Fix get_event_loop() return the current loop if called from
coroutines/callbacks.

@item 
bpo-28634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28634}: Fix asyncio.isfuture() to support unittest.Mock.

@item 
bpo-26081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26081}: Fix refleak in _asyncio.Future.__iter__().throw.

@item 
bpo-28639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28639}: Fix inspect.isawaitable to always return bool Patch by Justin
Mayfield.

@item 
bpo-28652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28652}: Make loop methods reject socket kinds they do not support.

@item 
bpo-28653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28653}: Fix a refleak in functools.lru_cache.

@item 
bpo-28703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28703}: Fix asyncio.iscoroutinefunction to handle Mock objects.

@item 
bpo-28704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28704}: Fix create_unix_server to support Path-like objects (PEP 519).

@item 
bpo-28720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28720}: Add collections.abc.AsyncGenerator.
@end itemize

@node Documentation<64>,Tests<64>,Library<71>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id628}@anchor{1aac}
@subsubsection Documentation



@itemize -

@item 
bpo-28513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28513}: Documented command-line interface of zipfile.
@end itemize

@node Tests<64>,Build<70>,Documentation<64>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id629}@anchor{1aad}
@subsubsection Tests



@itemize -

@item 
bpo-28666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28666}: Now test.support.rmtree is able to remove unwritable or
unreadable directories.

@item 
bpo-23839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23839}: Various caches now are cleared before running every test file.
@end itemize

@node Build<70>,,Tests<64>,Python 3 6 0 beta 4
@anchor{whatsnew/changelog id630}@anchor{1aae}
@subsubsection Build



@itemize -

@item 
bpo-10656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10656}: Fix out-of-tree building on AIX.  Patch by Tristan Carel and
Michael Haubenwallner.

@item 
bpo-26359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26359}: Rename --with-optimiations to --enable-optimizations.

@item 
bpo-28676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28676}: Prevent missing 'getentropy' declaration warning on macOS.
Patch by Gareth Rees.
@end itemize

@node Python 3 6 0 beta 3,Python 3 6 0 beta 2,Python 3 6 0 beta 4,Changelog
@anchor{whatsnew/changelog python-3-6-0-beta-3}@anchor{1aaf}
@subsection Python 3.6.0 beta 3


`Release date: 2016-10-31'

@menu
* Core and Builtins: Core and Builtins<73>. 
* Library: Library<72>. 
* Windows: Windows<62>. 
* Build: Build<71>. 
* Tests: Tests<65>. 

@end menu

@node Core and Builtins<73>,Library<72>,,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id631}@anchor{1ab0}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-28128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28128}: Deprecation warning for invalid str and byte escape sequences
now prints better information about where the error occurs. Patch by
Serhiy Storchaka and Eric Smith.

@item 
bpo-28509@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28509}: dict.update() no longer allocate unnecessary large memory.

@item 
bpo-28426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28426}: Fixed potential crash in PyUnicode_AsDecodedObject() in debug
build.

@item 
bpo-28517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28517}: Fixed of-by-one error in the peephole optimizer that caused
keeping unreachable code.

@item 
bpo-28214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28214}: Improved exception reporting for problematic __set_name__
attributes.

@item 
bpo-23782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23782}: Fixed possible memory leak in _PyTraceback_Add() and exception
loss in PyTraceBack_Here().

@item 
bpo-28471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28471}: Fix "Python memory allocator called without holding the GIL"
crash in socket.setblocking.
@end itemize

@node Library<72>,Windows<62>,Core and Builtins<73>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id632}@anchor{1ab1}
@subsubsection Library



@itemize -

@item 
bpo-27517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27517}: LZMA compressor and decompressor no longer raise exceptions if
given empty data twice.  Patch by Benjamin Fogle.

@item 
bpo-28549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28549}: Fixed segfault in curses's addch() with ncurses6.

@item 
bpo-28449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28449}: tarfile.open() with mode "r" or "r:" now tries to open a tar
file with compression before trying to open it without compression.
Otherwise it had 50% chance failed with ignore_zeros=True.

@item 
bpo-23262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23262}: The webbrowser module now supports Firefox 36+ and derived
browsers.  Based on patch by Oleg Broytman.

@item 
bpo-27939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27939}: Fixed bugs in tkinter.ttk.LabeledScale and tkinter.Scale caused
by representing the scale as float value internally in Tk.  tkinter.IntVar
now works if float value is set to underlying Tk variable.

@item 
bpo-18844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18844}: The various ways of specifying weights for random.choices() now
produce the same result sequences.

@item 
bpo-28255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28255}: calendar.TextCalendar().prmonth() no longer prints a space at
the start of new line after printing a month's calendar.  Patch by Xiang
Zhang.

@item 
bpo-20491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20491}: The textwrap.TextWrapper class now honors non-breaking spaces.
Based on patch by Kaarle Ritvanen.

@item 
bpo-28353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28353}: os.fwalk() no longer fails on broken links.

@item 
bpo-28430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28430}: Fix iterator of C implemented asyncio.Future doesn't accept
non-None value is passed to it.send(val).

@item 
bpo-27025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27025}: Generated names for Tkinter widgets now start by the "!" prefix
for readability.

@item 
bpo-25464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25464}: Fixed HList.header_exists() in tkinter.tix module by addin a
workaround to Tix library bug.

@item 
bpo-28488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28488}: shutil.make_archive() no longer adds entry "./" to ZIP archive.

@item 
bpo-25953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25953}: re.sub() now raises an error for invalid numerical group
reference in replacement template even if the pattern is not found in the
string.  Error message for invalid group reference now includes the group
index and the position of the reference. Based on patch by SilentGhost.

@item 
bpo-18219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18219}: Optimize csv.DictWriter for large number of columns. Patch by
Mariatta Wijaya.

@item 
bpo-28448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28448}: Fix C implemented asyncio.Future didn't work on Windows.

@item 
bpo-28480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28480}: Fix error building socket module when multithreading is
disabled.

@item 
bpo-24452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24452}: Make webbrowser support Chrome on Mac OS X.

@item 
bpo-20766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20766}: Fix references leaked by pdb in the handling of SIGINT
handlers.

@item 
bpo-28492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28492}: Fix how StopIteration exception is raised in _asyncio.Future.

@item 
bpo-28500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28500}: Fix asyncio to handle async gens GC from another thread.

@item 
bpo-26923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26923}: Fix asyncio.Gather to refuse being cancelled once all children
are done. Patch by Johannes Ebke.

@item 
bpo-26796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26796}: Don't configure the number of workers for default threadpool
executor. Initial patch by Hans Lawrenz.

@item 
bpo-28544@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28544}: Implement asyncio.Task in C.
@end itemize

@node Windows<62>,Build<71>,Library<72>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id633}@anchor{1ab2}
@subsubsection Windows



@itemize -

@item 
bpo-28522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28522}: Fixes mishandled buffer reallocation in getpathp.c
@end itemize

@node Build<71>,Tests<65>,Windows<62>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id634}@anchor{1ab3}
@subsubsection Build



@itemize -

@item 
bpo-28444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28444}: Fix missing extensions modules when cross compiling.

@item 
bpo-28208@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28208}: Update Windows build and OS X installers to use SQLite 3.14.2.

@item 
bpo-28248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28248}: Update Windows build and OS X installers to use OpenSSL 1.0.2j.
@end itemize

@node Tests<65>,,Build<71>,Python 3 6 0 beta 3
@anchor{whatsnew/changelog id635}@anchor{1ab4}
@subsubsection Tests



@itemize -

@item 
bpo-26944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26944}: Fix test_posix for Android where 'id -G' is entirely wrong or
missing the effective gid.

@item 
bpo-28409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28409}: regrtest: fix the parser of command line arguments.
@end itemize

@node Python 3 6 0 beta 2,Python 3 6 0 beta 1,Python 3 6 0 beta 3,Changelog
@anchor{whatsnew/changelog python-3-6-0-beta-2}@anchor{1ab5}
@subsection Python 3.6.0 beta 2


`Release date: 2016-10-10'

@menu
* Core and Builtins: Core and Builtins<74>. 
* Library: Library<73>. 
* Windows: Windows<63>. 
* C API: C API<63>. 
* Build: Build<72>. 
* Tests: Tests<66>. 

@end menu

@node Core and Builtins<74>,Library<73>,,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id636}@anchor{1ab6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-28183@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28183}: Optimize and cleanup dict iteration.

@item 
bpo-26081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26081}: Added C implementation of asyncio.Future. Original patch by
Yury Selivanov.

@item 
bpo-28379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28379}: Added sanity checks and tests for PyUnicode_CopyCharacters().
Patch by Xiang Zhang.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: The type of long range iterator is now registered as Iterator.
Patch by Oren Milman.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: Creating instances of range_iterator by calling range_iterator
type now is deprecated.  Patch by Oren Milman.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: The constructor of range_iterator now checks that step is not
0. Patch by Oren Milman.

@item 
bpo-26906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26906}: Resolving special methods of uninitialized type now causes
implicit initialization of the type instead of a fail.

@item 
bpo-18287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18287}: PyType_Ready() now checks that tp_name is not NULL. Original
patch by Niklas Koep.

@item 
bpo-24098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24098}: Fixed possible crash when AST is changed in process of
compiling it.

@item 
bpo-28201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28201}: Dict reduces possibility of 2nd conflict in hash table when
hashes have same lower bits.

@item 
bpo-28350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28350}: String constants with null character no longer interned.

@item 
bpo-26617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26617}: Fix crash when GC runs during weakref callbacks.

@item 
bpo-27942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27942}: String constants now interned recursively in tuples and
frozensets.

@item 
bpo-21578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21578}: Fixed misleading error message when ImportError called with
invalid keyword args.

@item 
bpo-28203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28203}: Fix incorrect type in complex(1.0, @{2:3@}) error message. Patch
by Soumya Sharma.

@item 
bpo-28086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28086}: Single var-positional argument of tuple subtype was passed
unscathed to the C-defined function.  Now it is converted to exact tuple.

@item 
bpo-28214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28214}: Now __set_name__ is looked up on the class instead of the
instance.

@item 
bpo-27955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27955}: Fallback on reading /dev/urandom device when the getrandom()
syscall fails with EPERM, for example when blocked by SECCOMP.

@item 
bpo-28192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28192}: Don't import readline in isolated mode.

@item 
Upgrade internal unicode databases to Unicode version 9.0.0.

@item 
bpo-28131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28131}: Fix a regression in zipimport's compile_source().  zipimport
should use the same optimization level as the interpreter.

@item 
bpo-28126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28126}: Replace Py_MEMCPY with memcpy(). Visual Studio can properly
optimize memcpy().

@item 
bpo-28120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28120}: Fix dict.pop() for splitted dictionary when trying to remove a
"pending key" (Not yet inserted in split-table). Patch by Xiang Zhang.

@item 
bpo-26182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26182}: Raise DeprecationWarning when async and await keywords are used
as variable/attribute/class/function name.
@end itemize

@node Library<73>,Windows<63>,Core and Builtins<74>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id637}@anchor{1ab7}
@subsubsection Library



@itemize -

@item 
bpo-27998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27998}: Fixed bytes path support in os.scandir() on Windows. Patch by
Eryk Sun.

@item 
bpo-28317@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28317}: The disassembler now decodes FORMAT_VALUE argument.

@item 
bpo-26293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26293}: Fixed writing ZIP files that starts not from the start of the
file.  Offsets in ZIP file now are relative to the start of the archive in
conforming to the specification.

@item 
bpo-28380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28380}: unittest.mock Mock autospec functions now properly support
assert_called, assert_not_called, and assert_called_once.

@item 
bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181}: remove statistics.geometric_mean and defer until 3.7.

@item 
bpo-28229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28229}: lzma module now supports pathlib.

@item 
bpo-28321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28321}: Fixed writing non-BMP characters with binary format in
plistlib.

@item 
bpo-28225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28225}: bz2 module now supports pathlib.  Initial patch by Ethan
Furman.

@item 
bpo-28227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28227}: gzip now supports pathlib.  Patch by Ethan Furman.

@item 
bpo-27358@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27358}: Optimized merging var-keyword arguments and improved error
message when passing a non-mapping as a var-keyword argument.

@item 
bpo-28257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28257}: Improved error message when passing a non-iterable as a
var-positional argument.  Added opcode BUILD_TUPLE_UNPACK_WITH_CALL.

@item 
bpo-28322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28322}: Fixed possible crashes when unpickle itertools objects from
incorrect pickle data.  Based on patch by John Leitch.

@item 
bpo-28228@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28228}: imghdr now supports pathlib.

@item 
bpo-28226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28226}: compileall now supports pathlib.

@item 
bpo-28314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28314}: Fix function declaration (C flags) for the getiterator() method
of xml.etree.ElementTree.Element.

@item 
bpo-28148@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28148}: Stop using localtime() and gmtime() in the time module.
Introduced platform independent _PyTime_localtime API that is similar to
POSIX localtime_r, but available on all platforms.  Patch by Ed Schouten.

@item 
bpo-28253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28253}: Fixed calendar functions for extreme months: 0001-01 and
9999-12. Methods itermonthdays() and itermonthdays2() are reimplemented so
that they don't call itermonthdates() which can cause datetime.date
under/overflow.

@item 
bpo-28275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28275}: Fixed possible use after free in the decompress() methods of
the LZMADecompressor and BZ2Decompressor classes. Original patch by John
Leitch.

@item 
bpo-27897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27897}: Fixed possible crash in sqlite3.Connection.create_collation()
if pass invalid string-like object as a name.  Patch by Xiang Zhang.

@item 
bpo-18844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18844}: random.choices() now has k as a keyword-only argument to
improve the readability of common cases and come into line with the
signature used in other languages.

@item 
bpo-18893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18893}: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py.
Patch by Madison May.

@item 
bpo-27611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27611}: Fixed support of default root window in the tkinter.tix module.
Added the master parameter in the DisplayStyle constructor.

@item 
bpo-27348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27348}: In the traceback module, restore the formatting of exception
messages like "Exception: None".  This fixes a regression introduced in
3.5a2.

@item 
bpo-25651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25651}: Allow false values to be used for msg parameter of subTest().

@item 
bpo-27778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27778}: Fix a memory leak in os.getrandom() when the getrandom() is
interrupted by a signal and a signal handler raises a Python exception.

@item 
bpo-28200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28200}: Fix memory leak on Windows in the os module (fix
path_converter() function).

@item 
bpo-25400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25400}: RobotFileParser now correctly returns default values for
crawl_delay and request_rate.  Initial patch by Peter Wirtz.

@item 
bpo-27932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27932}: Prevent memory leak in win32_ver().

@item 
Fix UnboundLocalError in socket._sendfile_use_sendfile.

@item 
bpo-28075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28075}: Check for ERROR_ACCESS_DENIED in Windows implementation of
os.stat().  Patch by Eryk Sun.

@item 
bpo-22493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22493}: Warning message emitted by using inline flags in the middle of
regular expression now contains a (truncated) regex pattern. Patch by Tim
Graham.

@item 
bpo-25270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25270}: Prevent codecs.escape_encode() from raising SystemError when an
empty bytestring is passed.

@item 
bpo-28181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28181}: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

@item 
bpo-25895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25895}: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by
Gergely Imreh and Markus Holtermann.

@item 
bpo-28114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28114}: Fix a crash in parse_envlist() when env contains byte strings.
Patch by Eryk Sun.

@item 
bpo-27599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27599}: Fixed buffer overrun in binascii.b2a_qp() and
binascii.a2b_qp().

@item 
bpo-27906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27906}: Fix socket accept exhaustion during high TCP traffic. Patch by
Kevin Conway.

@item 
bpo-28174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28174}: Handle when SO_REUSEPORT isn't properly supported. Patch by
Seth Michael Larson.

@item 
bpo-26654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26654}: Inspect functools.partial in asyncio.Handle.__repr__. Patch by
iceboy.

@item 
bpo-26909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26909}: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

@item 
bpo-28176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28176}: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

@item 
bpo-27759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27759}: Fix selectors incorrectly retain invalid file descriptors.
Patch by Mark Williams.

@item 
bpo-28368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28368}: Refuse monitoring processes if the child watcher has no loop
attached. Patch by Vincent Michel.

@item 
bpo-28369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28369}: Raise RuntimeError when transport's FD is used with add_reader,
add_writer, etc.

@item 
bpo-28370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28370}: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг
Марк.

@item 
bpo-28371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28371}: Deprecate passing asyncio.Handles to run_in_executor.

@item 
bpo-28372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28372}: Fix asyncio to support formatting of non-python coroutines.

@item 
bpo-28399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28399}: Remove UNIX socket from FS before binding. Patch by Коренберг
Марк.

@item 
bpo-27972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27972}: Prohibit Tasks to await on themselves.
@end itemize

@node Windows<63>,C API<63>,Library<73>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id638}@anchor{1ab8}
@subsubsection Windows



@itemize -

@item 
bpo-28402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28402}: Adds signed catalog files for stdlib on Windows.

@item 
bpo-28333@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28333}: Enables Unicode for ps1/ps2 and input() prompts. (Patch by Eryk
Sun)

@item 
bpo-28251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28251}: Improvements to help manuals on Windows.

@item 
bpo-28110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28110}: launcher.msi has different product codes between 32-bit and
64-bit

@item 
bpo-28161@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28161}: Opening CON for write access fails

@item 
bpo-28162@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28162}: WindowsConsoleIO readall() fails if first line starts with
Ctrl+Z

@item 
bpo-28163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28163}: WindowsConsoleIO fileno() passes wrong flags to _open_osfhandle

@item 
bpo-28164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28164}: _PyIO_get_console_type fails for various paths

@item 
bpo-28137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28137}: Renames Windows path file to ._pth

@item 
bpo-28138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28138}: Windows ._pth file should allow import site
@end itemize

@node C API<63>,Build<72>,Windows<63>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id639}@anchor{1ab9}
@subsubsection C API



@itemize -

@item 
bpo-28426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28426}: Deprecated undocumented functions PyUnicode_AsEncodedObject(),
PyUnicode_AsDecodedObject(), PyUnicode_AsDecodedUnicode() and
PyUnicode_AsEncodedUnicode().
@end itemize

@node Build<72>,Tests<66>,C API<63>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id640}@anchor{1aba}
@subsubsection Build



@itemize -

@item 
bpo-28258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28258}: Fixed build with Estonian locale (python-config and distclean
targets in Makefile).  Patch by Arfrever Frehtes Taifersar Arahesis.

@item 
bpo-26661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26661}: setup.py now detects system libffi with multiarch wrapper.

@item 
bpo-15819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15819}: Remove redundant include search directory option for building
outside the source tree.
@end itemize

@node Tests<66>,,Build<72>,Python 3 6 0 beta 2
@anchor{whatsnew/changelog id641}@anchor{1abb}
@subsubsection Tests



@itemize -

@item 
bpo-28217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28217}: Adds _testconsole module to test console input.
@end itemize

@node Python 3 6 0 beta 1,Python 3 6 0 alpha 4,Python 3 6 0 beta 2,Changelog
@anchor{whatsnew/changelog python-3-6-0-beta-1}@anchor{1abc}
@subsection Python 3.6.0 beta 1


`Release date: 2016-09-12'

@menu
* Core and Builtins: Core and Builtins<75>. 
* Library: Library<74>. 
* IDLE: IDLE<52>. 
* C API: C API<64>. 
* Tests: Tests<67>. 
* Build: Build<73>. 
* Tools/Demos: Tools/Demos<39>. 
* Windows: Windows<64>. 

@end menu

@node Core and Builtins<75>,Library<74>,,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id642}@anchor{1abd}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-23722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23722}: The __class__ cell used by zero-argument super() is now
initialized from type.__new__ rather than __build_class__, so class
methods relying on that will now work correctly when called from metaclass
methods during class creation. Patch by Martin Teichmann.

@item 
bpo-25221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25221}: Fix corrupted result from PyLong_FromLong(0) when Python is
compiled with NSMALLPOSINTS = 0.

@item 
bpo-27080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27080}: Implement formatting support for 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/}.  Initial patch by
Chris Angelico.

@item 
bpo-27199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27199}: In tarfile, expose copyfileobj bufsize to improve throughput.
Patch by Jason Fried.

@item 
bpo-27948@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27948}: In f-strings, only allow backslashes inside the braces (where
the expressions are).  This is a breaking change from the 3.6 alpha
releases, where backslashes are allowed anywhere in an f-string.  Also,
require that expressions inside f-strings be enclosed within literal
braces, and not escapes like @code{f'\x7b"hi"\x7d'}.

@item 
bpo-28046@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28046}: Remove platform-specific directories from sys.path.

@item 
bpo-28071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28071}: Add early-out for differencing from an empty set.

@item 
bpo-25758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25758}: Prevents zipimport from unnecessarily encoding a filename
(patch by Eryk Sun)

@item 
bpo-25856@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25856}: The __module__ attribute of extension classes and functions now
is interned. This leads to more compact pickle data with protocol 4.

@item 
bpo-27213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27213}: Rework CALL_FUNCTION* opcodes to produce shorter and more
efficient bytecode. Patch by Demur Rumed, design by Serhiy Storchaka,
reviewed by Serhiy Storchaka and Victor Stinner.

@item 
bpo-26331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26331}: Implement tokenizing support for 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/}. Patch by Georg
Brandl.

@item 
bpo-27999@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27999}: Make "global after use" a SyntaxError, and ditto for nonlocal.
Patch by Ivan Levkivskyi.

@item 
bpo-28003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28003}: Implement 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} -- Asynchronous Generators.

@item 
bpo-27985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27985}: Implement 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} -- Syntax for Variable Annotations. Patch
by Ivan Levkivskyi.

@item 
bpo-26058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26058}: Add a new private version to the builtin dict type, incremented
at each dictionary creation and at each dictionary change. Implementation
of the PEP 509.

@item 
bpo-27364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27364}: A backslash-character pair that is not a valid escape sequence
now generates a DeprecationWarning.  Patch by Emanuel Barry.

@item 
bpo-27350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27350}: @code{dict} implementation is changed like PyPy. It is more
compact and preserves insertion order. (Concept developed by Raymond
Hettinger and patch by Inada Naoki.)

@item 
bpo-27911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27911}: Remove unnecessary error checks in
@code{exec_builtin_or_dynamic()}.

@item 
bpo-27078@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27078}: Added BUILD_STRING opcode.  Optimized f-strings evaluation.

@item 
bpo-17884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17884}: Python now requires systems with inttypes.h and stdint.h

@item 
bpo-27961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27961}: Require platforms to support @code{long long}. Python hasn't
compiled without @code{long long} for years, so this is basically a
formality.

@item 
bpo-27355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27355}: Removed support for Windows CE.  It was never finished, and
Windows CE is no longer a relevant platform for Python.

@item 
Implement 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/}.

@item 
bpo-27870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27870}: A left shift of zero by a large integer no longer attempts to
allocate large amounts of memory.

@item 
bpo-25402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25402}: In int-to-decimal-string conversion, improve the estimate of
the intermediate memory required, and remove an unnecessarily strict
overflow check. Patch by Serhiy Storchaka.

@item 
bpo-27214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27214}: In long_invert, be more careful about modifying object returned
by long_add, and remove an unnecessary check for small longs. Thanks Oren
Milman for analysis and patch.

@item 
bpo-27506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27506}: Support passing the bytes/bytearray.translate() "delete"
argument by keyword.

@item 
bpo-27812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27812}: Properly clear out a generator's frame's backreference to the
generator to prevent crashes in frame.clear().

@item 
bpo-27811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27811}: Fix a crash when a coroutine that has not been awaited is
finalized with warnings-as-errors enabled.

@item 
bpo-27587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27587}: Fix another issue found by PVS-Studio: Null pointer check after
use of 'def' in _PyState_AddModule(). Initial patch by Christian Heimes.

@item 
bpo-27792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27792}: The modulo operation applied to @code{bool} and other @code{int}
subclasses now always returns an @code{int}. Previously the return type
depended on the input values. Patch by Xiang Zhang.

@item 
bpo-26984@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26984}: int() now always returns an instance of exact int.

@item 
bpo-25604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25604}: Fix a minor bug in integer true division; this bug could
potentially have caused off-by-one-ulp results on platforms with
unreliable ldexp implementations.

@item 
bpo-24254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24254}: Make class definition namespace ordered by default.

@item 
bpo-27662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27662}: Fix an overflow check in @code{List_New}: the original code was
checking against @code{Py_SIZE_MAX} instead of the correct upper bound of
@code{Py_SSIZE_T_MAX}. Patch by Xiang Zhang.

@item 
bpo-27782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27782}: Multi-phase extension module import now correctly allows the
@code{m_methods} field to be used to add module level functions to instances
of non-module types returned from @code{Py_create_mod}. Patch by Xiang Zhang.

@item 
bpo-27936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27936}: The round() function accepted a second None argument for some
types but not for others.  Fixed the inconsistency by accepting None for
all numeric types.

@item 
bpo-27487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27487}: Warn if a submodule argument to "python -m" or
runpy.run_module() is found in sys.modules after parent packages are
imported, but before the submodule is executed.

@item 
bpo-27157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27157}: Make only type() itself accept the one-argument form. Patch by
Eryk Sun and Emanuel Barry.

@item 
bpo-27558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27558}: Fix a SystemError in the implementation of "raise" statement.
In a brand new thread, raise a RuntimeError since there is no active
exception to reraise. Patch written by Xiang Zhang.

@item 
bpo-28008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28008}: Implement 
@geindex Python Enhancement Proposals; PEP 530
PEP 530@footnote{https://peps.python.org/pep-0530/} -- asynchronous comprehensions.

@item 
bpo-27942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27942}: Fix memory leak in codeobject.c
@end itemize

@node Library<74>,IDLE<52>,Core and Builtins<75>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id643}@anchor{1abe}
@subsubsection Library



@itemize -

@item 
bpo-28732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28732}: Fix crash in os.spawnv() with no elements in args

@item 
bpo-28485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28485}: Always raise ValueError for negative
compileall.compile_dir(workers=...) parameter, even when multithreading is
unavailable.

@item 
bpo-28037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28037}: Use sqlite3_get_autocommit() instead of setting
Connection->inTransaction manually.

@item 
bpo-25283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25283}: Attributes tm_gmtoff and tm_zone are now available on all
platforms in the return values of time.localtime() and time.gmtime().

@item 
bpo-24454@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24454}: Regular expression match object groups are now accessible using
__getitem__. "mo[x]" is equivalent to "mo.group(x)".

@item 
bpo-10740@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10740}: sqlite3 no longer implicitly commit an open transaction before
DDL statements.

@item 
bpo-17941@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17941}: Add a `module' parameter to collections.namedtuple().

@item 
bpo-22493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22493}: Inline flags now should be used only at the start of the
regular expression. Deprecation warning is emitted if uses them in the
middle of the regular expression.

@item 
bpo-26885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26885}: xmlrpc now supports unmarshalling additional data types used by
Apache XML-RPC implementation for numerics and None.

@item 
bpo-28070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28070}: Fixed parsing inline verbose flag in regular expressions.

@item 
bpo-19500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19500}: Add client-side SSL session resumption to the ssl module.

@item 
bpo-28022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28022}: Deprecate ssl-related arguments in favor of SSLContext. The
deprecation include manual creation of SSLSocket and certfile/keyfile (or
similar) in ftplib, httplib, imaplib, smtplib, poplib and urllib.

@item 
bpo-28043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28043}: SSLContext has improved default settings: OP_NO_SSLv2,
OP_NO_SSLv3, OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE,
OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE and HIGH ciphers without MD5.

@item 
bpo-24693@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24693}: Changed some RuntimeError's in the zipfile module to more
appropriate types. Improved some error messages and debugging output.

@item 
bpo-17909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17909}: @code{json.load} and @code{json.loads} now support binary input
encoded as UTF-8, UTF-16 or UTF-32. Patch by Serhiy Storchaka.

@item 
bpo-27137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27137}: the pure Python fallback implementation of
@code{functools.partial} now matches the behaviour of its accelerated C
counterpart for subclassing, pickling and text representation purposes.
Patch by Emanuel Barry and Serhiy Storchaka.

@item 
Fix possible integer overflows and crashes in the mmap module with unusual
usage patterns.

@item 
bpo-1703178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1703178}: Fix the ability to pass the --link-objects option to the
distutils build_ext command.

@item 
bpo-28019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28019}: itertools.count() no longer rounds non-integer step in range
between 1.0 and 2.0 to 1.

@item 
bpo-18401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18401}: Pdb now supports the 'readrc' keyword argument to control
whether .pdbrc files should be read.  Patch by Martin Matusiak and Sam
Kimbrel.

@item 
bpo-25969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25969}: Update the lib2to3 grammar to handle the unpacking
generalizations added in 3.5.

@item 
bpo-14977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14977}: mailcap now respects the order of the lines in the mailcap
files ("first match"), as required by RFC 1542.  Patch by Michael Lazar.

@item 
bpo-28082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28082}: Convert re flag constants to IntFlag.

@item 
bpo-28025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28025}: Convert all ssl module constants to IntEnum and IntFlags.
SSLContext properties now return flags and enums.

@item 
bpo-23591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23591}: Add Flag, IntFlag, and auto() to enum module.

@item 
bpo-433028@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=433028}: Added support of modifier spans in regular expressions.

@item 
bpo-24594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24594}: Validates persist parameter when opening MSI database

@item 
bpo-17582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17582}: xml.etree.ElementTree nows preserves whitespaces in attributes
(Patch by Duane Griffin.  Reviewed and approved by Stefan Behnel.)

@item 
bpo-28047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28047}: Fixed calculation of line length used for the base64 CTE in the
new email policies.

@item 
bpo-27576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27576}: Fix call order in OrderedDict.__init__().

@item 
email.generator.DecodedGenerator now supports the policy keyword.

@item 
bpo-28027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28027}: Remove undocumented modules from @code{Lib/plat-*}: IN, CDROM,
DLFCN, TYPES, CDIO, and STROPTS.

@item 
bpo-27445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27445}: Don't pass str(_charset) to MIMEText.set_payload(). Patch by
Claude Paroz.

@item 
bpo-24277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24277}: The new email API is no longer provisional, and the docs have
been reorganized and rewritten to emphasize the new API.

@item 
bpo-22450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22450}: urllib now includes an @code{Accept: */*} header among the default
headers. This makes the results of REST API requests more consistent and
predictable especially when proxy servers are involved.

@item 
lib2to3.pgen3.driver.load_grammar() now creates a stable cache file
between runs given the same Grammar.txt input regardless of the hash
randomization setting.

@item 
bpo-28005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28005}: Allow ImportErrors in encoding implementation to propagate.

@item 
bpo-26667@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26667}: Support path-like objects in importlib.util.

@item 
bpo-27570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27570}: Avoid zero-length memcpy() etc calls with null source pointers
in the "ctypes" and "array" modules.

@item 
bpo-22233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22233}: Break email header lines `only' on the RFC specified CR and LF
characters, not on arbitrary unicode line breaks.  This also fixes a bug
in HTTP header parsing.

@item 
bpo-27331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27331}: The email.mime classes now all accept an optional policy
keyword.

@item 
bpo-27988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27988}: Fix email iter_attachments incorrect mutation of payload list.

@item 
bpo-16113@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16113}: Add SHA-3 and SHAKE support to hashlib module.

@item 
Eliminate a tautological-pointer-compare warning in _scproxy.c.

@item 
bpo-27776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27776}: The @ref{50c,,os.urandom()} function does now block on Linux 3.17
and newer until the system urandom entropy pool is initialized to increase
the security. This change is part of the 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/}.

@item 
bpo-27778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27778}: Expose the Linux @code{getrandom()} syscall as a new
@ref{cab,,os.getrandom()} function. This change is part of the 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/}.

@item 
bpo-27691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27691}: Fix ssl module's parsing of GEN_RID subject alternative name
fields in X.509 certs.

@item 
bpo-18844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18844}: Add random.choices().

@item 
bpo-25761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25761}: Improved error reporting about truncated pickle data in C
implementation of unpickler.  UnpicklingError is now raised instead of
AttributeError and ValueError in some cases.

@item 
bpo-26798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26798}: Add BLAKE2 (blake2b and blake2s) to hashlib.

@item 
bpo-26032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26032}: Optimized globbing in pathlib by using os.scandir(); it is now
about 1.5--4 times faster.

@item 
bpo-25596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25596}: Optimized glob() and iglob() functions in the glob module; they
are now about 3--6 times faster.

@item 
bpo-27928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27928}: Add scrypt (password-based key derivation function) to hashlib
module (requires OpenSSL 1.1.0).

@item 
bpo-27850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27850}: Remove 3DES from ssl module's default cipher list to counter
measure sweet32 attack (
@geindex Common Vulnerabilities and Exposures; CVE 2016-2183
CVE 2016-2183@footnote{https://www.cve.org/CVERecord?id=CVE-2016-2183}).

@item 
bpo-27766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27766}: Add ChaCha20 Poly1305 to ssl module's default cipher list.
(Required OpenSSL 1.1.0 or LibreSSL).

@item 
bpo-25387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25387}: Check return value of winsound.MessageBeep.

@item 
bpo-27866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27866}: Add SSLContext.get_ciphers() method to get a list of all
enabled ciphers.

@item 
bpo-27744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27744}: Add AF_ALG (Linux Kernel crypto) to socket module.

@item 
bpo-26470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26470}: Port ssl and hashlib module to OpenSSL 1.1.0.

@item 
bpo-11620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11620}: Fix support for SND_MEMORY in winsound.PlaySound.  Based on a
patch by Tim Lesher.

@item 
bpo-11734@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11734}: Add support for IEEE 754 half-precision floats to the struct
module. Based on a patch by Eli Stevens.

@item 
bpo-27919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27919}: Deprecated @code{extra_path} distribution option in distutils
packaging.

@item 
bpo-23229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23229}: Add new @code{cmath} constants: @code{cmath.inf} and @code{cmath.nan} to
match @code{math.inf} and @code{math.nan}, and also @code{cmath.infj} and
@code{cmath.nanj} to match the format used by complex repr.

@item 
bpo-27842@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27842}: The csv.DictReader now returns rows of type OrderedDict.
(Contributed by Steve Holden.)

@item 
Remove support for passing a file descriptor to os.access. It never worked
but previously didn't raise.

@item 
bpo-12885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12885}: Fix error when distutils encounters symlink.

@item 
bpo-27881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27881}: Fixed possible bugs when setting
sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

@item 
bpo-27861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27861}: Fixed a crash in sqlite3.Connection.cursor() when a factory
creates not a cursor.  Patch by Xiang Zhang.

@item 
bpo-19884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19884}: Avoid spurious output on OS X with Gnu Readline.

@item 
bpo-27706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27706}: Restore deterministic behavior of random.Random().seed() for
string seeds using seeding version 1.  Allows sequences of calls to
random() to exactly match those obtained in Python 2. Patch by Nofar
Schnider.

@item 
bpo-10513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10513}: Fix a regression in Connection.commit().  Statements should not
be reset after a commit.

@item 
bpo-12319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12319}: Chunked transfer encoding support added to
http.client.HTTPConnection requests.  The
urllib.request.AbstractHTTPHandler class does not enforce a Content-Length
header any more.  If a HTTP request has a file or iterable body, but no
Content-Length header, the library now falls back to use chunked
transfer-encoding.

@item 
A new version of typing.py from @indicateurl{https://github.com/python/typing}: -
Collection (only for 3.6) (bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}) - Add FrozenSet to __all__
(upstream #261) - fix crash in _get_type_vars() (upstream #259) - Remove
the dict constraint in ForwardRef._eval_type (upstream #252)

@item 
bpo-27832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27832}: Make @code{_normalize} parameter to @code{Fraction} constructor
keyword-only, so that @code{Fraction(2, 3, 4)} now raises @code{TypeError}.

@item 
bpo-27539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27539}: Fix unnormalised @code{Fraction.__pow__} result in the case of
negative exponent and negative base.

@item 
bpo-21718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21718}: cursor.description is now available for queries using CTEs.

@item 
bpo-27819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27819}: In distutils sdists, simply produce the "gztar" (gzipped tar
format) distributions on all platforms unless "formats" is supplied.

@item 
bpo-2466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2466}: posixpath.ismount now correctly recognizes mount points which
the user does not have permission to access.

@item 
bpo-9998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9998}: On Linux, ctypes.util.find_library now looks in LD_LIBRARY_PATH
for shared libraries.

@item 
bpo-27573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27573}: exit message for code.interact is now configurable.

@item 
bpo-27930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27930}: Improved behaviour of logging.handlers.QueueListener. Thanks to
Paulo Andrade and Petr Viktorin for the analysis and patch.

@item 
bpo-6766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6766}: Distributed reference counting added to multiprocessing to
support nesting of shared values / proxy objects.

@item 
bpo-21201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21201}: Improves readability of multiprocessing error message.  Thanks
to Wojciech Walczak for patch.

@item 
asyncio: Add set_protocol / get_protocol to Transports.

@item 
bpo-27456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27456}: asyncio: Set TCP_NODELAY by default.
@end itemize

@node IDLE<52>,C API<64>,Library<74>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id644}@anchor{1abf}
@subsubsection IDLE



@itemize -

@item 
bpo-15308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15308}: Add 'interrupt execution' (^C) to Shell menu. Patch by Roger
Serwy, updated by Bayard Randel.

@item 
bpo-27922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27922}: Stop IDLE tests from 'flashing' gui widgets on the screen.

@item 
bpo-27891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27891}: Consistently group and sort imports within idlelib modules.

@item 
bpo-17642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17642}: add larger font sizes for classroom projection.

@item 
Add version to title of IDLE help window.

@item 
bpo-25564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25564}: In section on IDLE -- console differences, mention that using
exec means that __builtins__ is defined for each statement.

@item 
bpo-27821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27821}: Fix 3.6.0a3 regression that prevented custom key sets from
being selected when no custom theme was defined.
@end itemize

@node C API<64>,Tests<67>,IDLE<52>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id645}@anchor{1ac0}
@subsubsection C API



@itemize -

@item 
bpo-26900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26900}: Excluded underscored names and other private API from limited
API.

@item 
bpo-26027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26027}: Add support for path-like objects in PyUnicode_FSConverter() &
PyUnicode_FSDecoder().
@end itemize

@node Tests<67>,Build<73>,C API<64>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id646}@anchor{1ac1}
@subsubsection Tests



@itemize -

@item 
bpo-27427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27427}: Additional tests for the math module. Patch by Francisco Couzo.

@item 
bpo-27953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27953}: Skip math and cmath tests that fail on OS X 10.4 due to a poor
libm implementation of tan.

@item 
bpo-26040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26040}: Improve test_math and test_cmath coverage and rigour. Patch by
Jeff Allen.

@item 
bpo-27787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27787}: Call gc.collect() before checking each test for "dangling
threads", since the dangling threads are weak references.
@end itemize

@node Build<73>,Tools/Demos<39>,Tests<67>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id647}@anchor{1ac2}
@subsubsection Build



@itemize -

@item 
bpo-27566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27566}: Fix clean target in freeze makefile (patch by Lisa Roach)

@item 
bpo-27705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27705}: Update message in validate_ucrtbase.py

@item 
bpo-27976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27976}: Deprecate building _ctypes with the bundled copy of libffi on
non-OSX UNIX platforms.

@item 
bpo-27983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27983}: Cause lack of llvm-profdata tool when using clang as required
for PGO linking to be a configure time error rather than make time when
@code{--with-optimizations} is enabled.  Also improve our ability to find the
llvm-profdata tool on MacOS and some Linuxes.

@item 
bpo-21590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21590}: Support for DTrace and SystemTap probes.

@item 
bpo-26307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26307}: The profile-opt build now applies PGO to the built-in modules.

@item 
bpo-26359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26359}: Add the --with-optimizations flag to turn on LTO and PGO build
support when available.

@item 
bpo-27917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27917}: Set platform triplets for Android builds.

@item 
bpo-25825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25825}: Update references to the $(LIBPL) installation path on AIX.
This path was changed in 3.2a4.

@item 
Update OS X installer to use SQLite 3.14.1 and XZ 5.2.2.

@item 
bpo-21122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21122}: Fix LTO builds on OS X.

@item 
bpo-17128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17128}: Build OS X installer with a private copy of OpenSSL. Also
provide a sample Install Certificates command script to install a set of
root certificates from the third-party certifi module.
@end itemize

@node Tools/Demos<39>,Windows<64>,Build<73>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id648}@anchor{1ac3}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-27952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27952}: Get Tools/scripts/fixcid.py working with Python 3 and the
current "re" module, avoid invalid Python backslash escapes, and fix a bug
parsing escaped C quote signs.
@end itemize

@node Windows<64>,,Tools/Demos<39>,Python 3 6 0 beta 1
@anchor{whatsnew/changelog id649}@anchor{1ac4}
@subsubsection Windows



@itemize -

@item 
bpo-28065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28065}: Update xz dependency to 5.2.2 and build it from source.

@item 
bpo-25144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25144}: Ensures TargetDir is set before continuing with custom install.

@item 
bpo-1602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1602}: Windows console doesn't input or print Unicode (PEP 528)

@item 
bpo-27781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27781}: Change file system encoding on Windows to UTF-8 (PEP 529)

@item 
bpo-27731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27731}: Opt-out of MAX_PATH on Windows 10

@item 
bpo-6135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6135}: Adds encoding and errors parameters to subprocess.

@item 
bpo-27959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27959}: Adds oem encoding, alias ansi to mbcs, move aliasmbcs to codec
lookup.

@item 
bpo-27982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27982}: The functions of the winsound module now accept keyword
arguments.

@item 
bpo-20366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20366}: Build full text search support into SQLite on Windows.

@item 
bpo-27756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27756}: Adds new icons for Python files and processes on Windows.
Designs by Cherry Wang.

@item 
bpo-27883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27883}: Update sqlite to 3.14.1.0 on Windows.
@end itemize

@node Python 3 6 0 alpha 4,Python 3 6 0 alpha 3,Python 3 6 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-6-0-alpha-4}@anchor{1ac5}
@subsection Python 3.6.0 alpha 4


`Release date: 2016-08-15'

@menu
* Core and Builtins: Core and Builtins<76>. 
* Library: Library<75>. 
* IDLE: IDLE<53>. 
* Tests: Tests<68>. 
* Windows: Windows<65>. 
* Build: Build<74>. 

@end menu

@node Core and Builtins<76>,Library<75>,,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id650}@anchor{1ac6}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-27704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27704}: Optimized creating bytes and bytearray from byte-like objects
and iterables. Speed up to 3 times for short objects.  Original patch by
Naoki Inada.

@item 
bpo-26823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26823}: Large sections of repeated lines in tracebacks are now
abbreviated as "[Previous line repeated @{count@} more times]" by the
builtin traceback rendering. Patch by Emanuel Barry.

@item 
bpo-27574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27574}: Decreased an overhead of parsing keyword arguments in functions
implemented with using Argument Clinic.

@item 
bpo-22557@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22557}: Now importing already imported modules is up to 2.5 times
faster.

@item 
bpo-17596@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17596}: Include <wincrypt.h> to help with Min GW building.

@item 
bpo-17599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17599}: On Windows, rename the privately defined REPARSE_DATA_BUFFER
structure to avoid conflicting with the definition from Min GW.

@item 
bpo-27507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27507}: Add integer overflow check in bytearray.extend().  Patch by
Xiang Zhang.

@item 
bpo-27581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27581}: Don't rely on wrapping for overflow check in
PySequence_Tuple().  Patch by Xiang Zhang.

@item 
bpo-1621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1621}: Avoid signed integer overflow in list and tuple operations.
Patch by Xiang Zhang.

@item 
bpo-27419@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27419}: Standard __import__() no longer look up "__import__" in globals
or builtins for importing submodules or "from import".  Fixed a crash if
raise a warning about unabling to resolve package from __spec__ or
__package__.

@item 
bpo-27083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27083}: Respect the PYTHONCASEOK environment variable under Windows.

@item 
bpo-27514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27514}: Make having too many statically nested blocks a SyntaxError
instead of SystemError.

@item 
bpo-27366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27366}: Implemented 
@geindex Python Enhancement Proposals; PEP 487
PEP 487@footnote{https://peps.python.org/pep-0487/} (Simpler customization of class
creation). Upon subclassing, the __init_subclass__ classmethod is called
on the base class. Descriptors are initialized with __set_name__ after
class creation.
@end itemize

@node Library<75>,IDLE<53>,Core and Builtins<76>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id651}@anchor{1ac7}
@subsubsection Library



@itemize -

@item 
bpo-26027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26027}: Add 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}/__fspath__() support to the os and os.path
modules. Includes code from Jelle Zijlstra. (See also: bpo-27524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27524})

@item 
bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}: Add Collections to collections.abc. Patch by Ivan Levkivskyi,
docs by Neil Girdhar.

@item 
bpo-25958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25958}: Support "anti-registration" of special methods from various
ABCs, like __hash__, __iter__ or __len__.  All these (and several more)
can be set to None in an implementation class and the behavior will be as
if the method is not defined at all. (Previously, this mechanism existed
only for __hash__, to make mutable classes unhashable.)  Code contributed
by Andrew Barnert and Ivan Levkivskyi.

@item 
bpo-16764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16764}: Support keyword arguments to zlib.decompress().  Patch by Xiang
Zhang.

@item 
bpo-27736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27736}: Prevent segfault after interpreter re-initialization due to ref
count problem introduced in code for bpo-27038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27038} in 3.6.0a3. Patch by
Xiang Zhang.

@item 
bpo-25628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25628}: The `verbose' and `rename' parameters for
collections.namedtuple are now keyword-only.

@item 
bpo-12345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12345}: Add mathematical constant tau to math and cmath. See also
@geindex Python Enhancement Proposals; PEP 628
PEP 628@footnote{https://peps.python.org/pep-0628/}.

@item 
bpo-26823@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26823}: traceback.StackSummary.format now abbreviates large sections of
repeated lines as "[Previous line repeated @{count@} more times]" (this
change then further affects other traceback display operations in the
module). Patch by Emanuel Barry.

@item 
bpo-27664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27664}: Add to concurrent.futures.thread.ThreadPoolExecutor() the
ability to specify a thread name prefix.

@item 
bpo-27181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27181}: Add geometric_mean and harmonic_mean to statistics module.

@item 
bpo-27573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27573}: code.interact now prints an message when exiting.

@item 
bpo-6422@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6422}: Add autorange method to timeit.Timer objects.

@item 
bpo-27773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27773}: Correct some memory management errors server_hostname in
_ssl.wrap_socket().

@item 
bpo-26750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26750}: unittest.mock.create_autospec() now works properly for
subclasses of property() and other data descriptors.  Removes the never
publicly used, never documented unittest.mock.DescriptorTypes tuple.

@item 
bpo-26754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26754}: Undocumented support of general bytes-like objects as path in
compile() and similar functions is now deprecated.

@item 
bpo-26800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26800}: Undocumented support of general bytes-like objects as paths in
os functions is now deprecated.

@item 
bpo-26981@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26981}: Add _order_ compatibility shim to enum.Enum for Python 2/3 code
bases.

@item 
bpo-27661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27661}: Added tzinfo keyword argument to datetime.combine.

@item 
In the curses module, raise an error if window.getstr() or window.instr()
is passed a negative value.

@item 
bpo-27783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27783}: Fix possible usage of uninitialized memory in
operator.methodcaller.

@item 
bpo-27774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27774}: Fix possible Py_DECREF on unowned object in _sre.

@item 
bpo-27760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27760}: Fix possible integer overflow in binascii.b2a_qp.

@item 
bpo-27758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27758}: Fix possible integer overflow in the _csv module for large
record lengths.

@item 
bpo-27568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27568}: Prevent HTTPoxy attack (
@geindex Common Vulnerabilities and Exposures; CVE 2016-1000110
CVE 2016-1000110@footnote{https://www.cve.org/CVERecord?id=CVE-2016-1000110}). Ignore the
HTTP_PROXY variable when REQUEST_METHOD environment is set, which
indicates that the script is in CGI mode.

@item 
bpo-7063@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7063}: Remove dead code from the "array" module's slice handling. Patch
by Chuck.

@item 
bpo-27656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27656}: Do not assume sched.h defines any SCHED_* constants.

@item 
bpo-27130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27130}: In the "zlib" module, fix handling of large buffers (typically
4 GiB) when compressing and decompressing.  Previously, inputs were
limited to 4 GiB, and compression and decompression operations did not
properly handle results of 4 GiB.

@item 
bpo-24773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24773}: Implemented 
@geindex Python Enhancement Proposals; PEP 495
PEP 495@footnote{https://peps.python.org/pep-0495/} (Local Time Disambiguation).

@item 
Expose the EPOLLEXCLUSIVE constant (when it is defined) in the select
module.

@item 
bpo-27567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27567}: Expose the EPOLLRDHUP and POLLRDHUP constants in the select
module.

@item 
bpo-1621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1621}: Avoid signed int negation overflow in the "audioop" module.

@item 
bpo-27533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27533}: Release GIL in nt._isdir

@item 
bpo-17711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17711}: Fixed unpickling by the persistent ID with protocol 0. Original
patch by Alexandre Vassalotti.

@item 
bpo-27522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27522}: Avoid an unintentional reference cycle in email.feedparser.

@item 
bpo-27512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27512}: Fix a segfault when os.fspath() called an __fspath__() method
that raised an exception. Patch by Xiang Zhang.
@end itemize

@node IDLE<53>,Tests<68>,Library<75>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id652}@anchor{1ac8}
@subsubsection IDLE



@itemize -

@item 
bpo-27714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27714}: text_textview and test_autocomplete now pass when re-run in the
same process.  This occurs when test_idle fails when run with the -w
option but without -jn.  Fix warning from test_config.

@item 
bpo-27621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27621}: Put query response validation error messages in the query box
itself instead of in a separate messagebox.  Redo tests to match. Add Mac
OSX refinements. Original patch by Mark Roseman.

@item 
bpo-27620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27620}: Escape key now closes Query box as cancelled.

@item 
bpo-27609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27609}: IDLE: tab after initial whitespace should tab, not
autocomplete. This fixes problem with writing docstrings at least twice
indented.

@item 
bpo-27609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27609}: Explicitly return None when there are also non-None returns. In
a few cases, reverse a condition and eliminate a return.

@item 
bpo-25507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25507}: IDLE no longer runs buggy code because of its tkinter imports.
Users must include the same imports required to run directly in Python.

@item 
bpo-27173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27173}: Add 'IDLE Modern Unix' to the built-in key sets. Make the
default key set depend on the platform. Add tests for the changes to the
config module.

@item 
bpo-27452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27452}: add line counter and crc to IDLE configHandler test dump.
@end itemize

@node Tests<68>,Windows<65>,IDLE<53>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id653}@anchor{1ac9}
@subsubsection Tests



@itemize -

@item 
bpo-25805@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25805}: Skip a test in test_pkgutil as needed that doesn't work when
@code{__name__ == __main__}. Patch by SilentGhost.

@item 
bpo-27472@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27472}: Add test.support.unix_shell as the path to the default shell.

@item 
bpo-27369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27369}: In test_pyexpat, avoid testing an error message detail that
changed in Expat 2.2.0.

@item 
bpo-27594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27594}: Prevent assertion error when running test_ast with coverage
enabled: ensure code object has a valid first line number. Patch suggested
by Ivan Levkivskyi.
@end itemize

@node Windows<65>,Build<74>,Tests<68>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id654}@anchor{1aca}
@subsubsection Windows



@itemize -

@item 
bpo-27647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27647}: Update bundled Tcl/Tk to 8.6.6.

@item 
bpo-27610@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27610}: Adds 
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} metadata to Windows installer

@item 
bpo-27469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27469}: Adds a shell extension to the launcher so that drag and drop
works correctly.

@item 
bpo-27309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27309}: Enables proper Windows styles in python[w].exe manifest.
@end itemize

@node Build<74>,,Windows<65>,Python 3 6 0 alpha 4
@anchor{whatsnew/changelog id655}@anchor{1acb}
@subsubsection Build



@itemize -

@item 
bpo-27713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27713}: Suppress spurious build warnings when updating importlib's
bootstrap files. Patch by Xiang Zhang

@item 
bpo-25825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25825}: Correct the references to Modules/python.exp, which is required
on AIX.  The references were accidentally changed in 3.5.0a1.

@item 
bpo-27453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27453}: CPP invocation in configure must use CPPFLAGS. Patch by Chi
Hsuan Yen.

@item 
bpo-27641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27641}: The configure script now inserts comments into the makefile to
prevent the pgen and _freeze_importlib executables from being
cross-compiled.

@item 
bpo-26662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26662}: Set PYTHON_FOR_GEN in configure as the Python program to be
used for file generation during the build.

@item 
bpo-10910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10910}: Avoid C++ compilation errors on FreeBSD and OS X. Also update
FreedBSD version checks for the original ctype UTF-8 workaround.
@end itemize

@node Python 3 6 0 alpha 3,Python 3 6 0 alpha 2,Python 3 6 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-6-0-alpha-3}@anchor{1acc}
@subsection Python 3.6.0 alpha 3


`Release date: 2016-07-11'

@menu
* Security: Security<43>. 
* Core and Builtins: Core and Builtins<77>. 
* Library: Library<76>. 
* IDLE: IDLE<54>. 
* C API: C API<65>. 
* Build: Build<75>. 
* Tools/Demos: Tools/Demos<40>. 
* Documentation: Documentation<65>. 
* Tests: Tests<69>. 

@end menu

@node Security<43>,Core and Builtins<77>,,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id656}@anchor{1acd}
@subsubsection Security



@itemize -

@item 
bpo-27278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27278}: Fix os.urandom() implementation using getrandom() on Linux.
Truncate size to INT_MAX and loop until we collected enough random bytes,
instead of casting a directly Py_ssize_t to int.

@item 
bpo-22636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22636}: Avoid shell injection problems with ctypes.util.find_library().
@end itemize

@node Core and Builtins<77>,Library<76>,Security<43>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id657}@anchor{1ace}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-27473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27473}: Fixed possible integer overflow in bytes and bytearray
concatenations. Patch by Xiang Zhang.

@item 
bpo-23034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23034}: The output of a special Python build with defined COUNT_ALLOCS,
SHOW_ALLOC_COUNT or SHOW_TRACK_COUNT macros is now off by  default.  It
can be re-enabled using the "-X showalloccount" option.  It now outputs to
stderr instead of stdout.

@item 
bpo-27443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27443}: __length_hint__() of bytearray iterators no longer return a
negative integer for a resized bytearray.

@item 
bpo-27007@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27007}: The fromhex() class methods of bytes and bytearray subclasses
now return an instance of corresponding subclass.
@end itemize

@node Library<76>,IDLE<54>,Core and Builtins<77>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id658}@anchor{1acf}
@subsubsection Library



@itemize -

@item 
bpo-26844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26844}: Fix error message for imp.find_module() to refer to 'path'
instead of 'name'. Patch by Lev Maximov.

@item 
bpo-23804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23804}: Fix SSL zero-length recv() calls to not block and not raise an
error about unclean EOF.

@item 
bpo-27466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27466}: Change time format returned by http.cookie.time2netscape,
confirming the netscape cookie format and making it consistent with
documentation.

@item 
bpo-21708@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21708}: Deprecated dbm.dumb behavior that differs from common dbm
behavior: creating a database in 'r' and 'w' modes and modifying a
database in 'r' mode.

@item 
bpo-26721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26721}: Change the socketserver.StreamRequestHandler.wfile attribute to
implement BufferedIOBase. In particular, the write() method no longer does
partial writes.

@item 
bpo-22115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22115}: Added methods trace_add, trace_remove and trace_info in the
tkinter.Variable class.  They replace old methods trace_variable, trace,
trace_vdelete and trace_vinfo that use obsolete Tcl commands and might not
work in future versions of Tcl.  Fixed old tracing methods:
trace_vdelete() with wrong mode no longer break tracing, trace_vinfo() now
always returns a list of pairs of strings, tracing in the "u" mode now
works.

@item 
bpo-26243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26243}: Only the level argument to zlib.compress() is keyword argument
now.  The first argument is positional-only.

@item 
bpo-27038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27038}: Expose the DirEntry type as os.DirEntry. Code patch by Jelle
Zijlstra.

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Update os.fspath()/PyOS_FSPath() to check the return value of
__fspath__() to be either str or bytes.

@item 
bpo-18726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18726}: All optional parameters of the dump(), dumps(), load() and
loads() functions and JSONEncoder and JSONDecoder class constructors in
the json module are now keyword-only.

@item 
bpo-27319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27319}: Methods selection_set(), selection_add(), selection_remove()
and selection_toggle() of ttk.TreeView now allow passing multiple items as
multiple arguments instead of passing them as a tuple.  Deprecated
undocumented ability of calling the selection() method with arguments.

@item 
bpo-27079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27079}: Fixed curses.ascii functions isblank(), iscntrl() and
ispunct().

@item 
bpo-27294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27294}: Numerical state in the repr for Tkinter event objects is now
represented as a combination of known flags.

@item 
bpo-27177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27177}: Match objects in the re module now support index-like objects
as group indices.  Based on patches by Jeroen Demeyer and Xiang Zhang.

@item 
bpo-26754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26754}: Some functions (compile() etc) accepted a filename argument
encoded as an iterable of integers. Now only strings and byte-like objects
are accepted.

@item 
bpo-26536@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26536}: socket.ioctl now supports SIO_LOOPBACK_FAST_PATH. Patch by
Daniel Stokes.

@item 
bpo-27048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27048}: Prevents distutils failing on Windows when environment
variables contain non-ASCII characters

@item 
bpo-27330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27330}: Fixed possible leaks in the ctypes module.

@item 
bpo-27238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27238}: Got rid of bare excepts in the turtle module.  Original patch
by Jelle Zijlstra.

@item 
bpo-27122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27122}: When an exception is raised within the context being managed by
a contextlib.ExitStack() and one of the exit stack generators catches and
raises it in a chain, do not re-raise the original exception when exiting,
let the new chained one through.  This avoids the 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} bug described
in issue25782.

@item 
bpo-16864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16864}: sqlite3.Cursor.lastrowid now supports REPLACE statement.
Initial patch by Alex LordThorsen.

@item 
bpo-26386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26386}: Fixed ttk.TreeView selection operations with item id's
containing spaces.

@item 
bpo-8637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8637}: Honor a pager set by the env var MANPAGER (in preference to one
set by the env var PAGER).

@item 
bpo-16182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16182}: Fix various functions in the "readline" module to use the
locale encoding, and fix get_begidx() and get_endidx() to return code
point indexes.

@item 
bpo-27392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27392}: Add loop.connect_accepted_socket(). Patch by Jim Fulton.
@end itemize

@node IDLE<54>,C API<65>,Library<76>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id659}@anchor{1ad0}
@subsubsection IDLE



@itemize -

@item 
bpo-27477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27477}: IDLE search dialogs now use ttk widgets.

@item 
bpo-27173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27173}: Add 'IDLE Modern Unix' to the built-in key sets. Make the
default key set depend on the platform. Add tests for the changes to the
config module.

@item 
bpo-27452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27452}: make command line "idle-test> python test_help.py" work.
__file__ is relative when python is started in the file's directory.

@item 
bpo-27452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27452}: add line counter and crc to IDLE configHandler test dump.

@item 
bpo-27380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27380}: IDLE: add query.py with base Query dialog and ttk widgets.
Module had subclasses SectionName, ModuleName, and HelpSource, which are
used to get information from users by configdialog and file =>Load Module.
Each subclass has itw own validity checks.  Using ModuleName allows users
to edit bad module names instead of starting over. Add tests and delete
the two files combined into the new one.

@item 
bpo-27372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27372}: Test_idle no longer changes the locale.

@item 
bpo-27365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27365}: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.

@item 
bpo-27245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27245}: IDLE: Cleanly delete custom themes and key bindings.
Previously, when IDLE was started from a console or by import, a cascade
of warnings was emitted. Patch by Serhiy Storchaka.

@item 
bpo-24137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24137}: Run IDLE, test_idle, and htest with tkinter default root
disabled.  Fix code and tests that fail with this restriction.  Fix htests
to not create a second and redundant root and mainloop.

@item 
bpo-27310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27310}: Fix IDLE.app failure to launch on OS X due to vestigial import.
@end itemize

@node C API<65>,Build<75>,IDLE<54>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id660}@anchor{1ad1}
@subsubsection C API



@itemize -

@item 
bpo-26754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26754}: PyUnicode_FSDecoder() accepted a filename argument encoded as
an iterable of integers. Now only strings and byte-like objects are
accepted.
@end itemize

@node Build<75>,Tools/Demos<40>,C API<65>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id661}@anchor{1ad2}
@subsubsection Build



@itemize -

@item 
bpo-28066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28066}: Fix the logic that searches build directories for generated
include files when building outside the source tree.

@item 
bpo-27442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27442}: Expose the Android API level that python was built against, in
sysconfig.get_config_vars() as 'ANDROID_API_LEVEL'.

@item 
bpo-27434@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27434}: The interpreter that runs the cross-build, found in PATH, must
now be of the same feature version (e.g. 3.6) as the source being built.

@item 
bpo-26930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26930}: Update Windows builds to use OpenSSL 1.0.2h.

@item 
bpo-23968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23968}: Rename the platform directory from plat-$(MACHDEP) to
plat-$(PLATFORM_TRIPLET). Rename the config directory (LIBPL) from
config-$(LDVERSION) to config-$(LDVERSION)-$(PLATFORM_TRIPLET). Install
the platform specific _sysconfigdata module into the platform directory
and rename it to include the ABIFLAGS.

@item 
Don't use largefile support for GNU/Hurd.
@end itemize

@node Tools/Demos<40>,Documentation<65>,Build<75>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id662}@anchor{1ad3}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-27332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27332}: Fixed the type of the first argument of module-level functions
generated by Argument Clinic.  Patch by Petr Viktorin.

@item 
bpo-27418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27418}: Fixed Tools/importbench/importbench.py.
@end itemize

@node Documentation<65>,Tests<69>,Tools/Demos<40>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id663}@anchor{1ad4}
@subsubsection Documentation



@itemize -

@item 
bpo-19489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19489}: Moved the search box from the sidebar to the header and footer
of each page. Patch by Ammar Askar.

@item 
bpo-27285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27285}: Update documentation to reflect the deprecation of @code{pyvenv}
and normalize on the term "virtual environment". Patch by Steve Piercy.
@end itemize

@node Tests<69>,,Documentation<65>,Python 3 6 0 alpha 3
@anchor{whatsnew/changelog id664}@anchor{1ad5}
@subsubsection Tests



@itemize -

@item 
bpo-27027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27027}: Added test.support.is_android that is True when this is an
Android build.
@end itemize

@node Python 3 6 0 alpha 2,Python 3 6 0 alpha 1,Python 3 6 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-6-0-alpha-2}@anchor{1ad6}
@subsection Python 3.6.0 alpha 2


`Release date: 2016-06-13'

@menu
* Security: Security<44>. 
* Core and Builtins: Core and Builtins<78>. 
* Library: Library<77>. 
* IDLE: IDLE<55>. 
* Documentation: Documentation<66>. 
* Tests: Tests<70>. 
* Windows: Windows<66>. 
* Build: Build<76>. 
* C API: C API<66>. 
* Tools/Demos: Tools/Demos<41>. 

@end menu

@node Security<44>,Core and Builtins<78>,,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id665}@anchor{1ad7}
@subsubsection Security



@itemize -

@item 
bpo-26556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26556}: Update expat to 2.1.1, fixes 
@geindex Common Vulnerabilities and Exposures; CVE 2015-1283
CVE 2015-1283@footnote{https://www.cve.org/CVERecord?id=CVE-2015-1283}.

@item 
Fix TLS stripping vulnerability in smtplib, 
@geindex Common Vulnerabilities and Exposures; CVE 2016-0772
CVE 2016-0772@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0772}. Reported by
Team Oststrom.

@item 
bpo-26839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26839}: On Linux, @ref{50c,,os.urandom()} now calls @code{getrandom()} with
@code{GRND_NONBLOCK} to fall back on reading @code{/dev/urandom} if the urandom
entropy pool is not initialized yet. Patch written by Colm Buckley.
@end itemize

@node Core and Builtins<78>,Library<77>,Security<44>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id666}@anchor{1ad8}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-27095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27095}: Simplified MAKE_FUNCTION and removed MAKE_CLOSURE opcodes.
Patch by Demur Rumed.

@item 
bpo-27190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27190}: Raise NotSupportedError if sqlite3 is older than 3.3.1. Patch
by Dave Sawyer.

@item 
bpo-27286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27286}: Fixed compiling BUILD_MAP_UNPACK_WITH_CALL opcode.  Calling
function with generalized unpacking (PEP 448) and conflicting keyword
names could cause undefined behavior.

@item 
bpo-27140@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27140}: Added BUILD_CONST_KEY_MAP opcode.

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Add support for os.PathLike objects to open() (part of
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}).

@item 
bpo-27066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27066}: Fixed SystemError if a custom opener (for open()) returns a
negative number without setting an exception.

@item 
bpo-26983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26983}: float() now always return an instance of exact float. The
deprecation warning is emitted if __float__ returns an instance of a
strict subclass of float.  In a future versions of Python this can be an
error.

@item 
bpo-27097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27097}: Python interpreter is now about 7% faster due to optimized
instruction decoding.  Based on patch by Demur Rumed.

@item 
bpo-26647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26647}: Python interpreter now uses 16-bit wordcode instead of
bytecode. Patch by Demur Rumed.

@item 
bpo-23275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23275}: Allow assigning to an empty target list in round brackets: () =
iterable.

@item 
bpo-27243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27243}: Update the __aiter__ protocol: instead of returning an
awaitable that resolves to an asynchronous iterator, the asynchronous
iterator should be returned directly.  Doing the former will trigger a
PendingDeprecationWarning.
@end itemize

@node Library<77>,IDLE<55>,Core and Builtins<78>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id667}@anchor{1ad9}
@subsubsection Library



@itemize -

@item 
Comment out socket (SO_REUSEPORT) and posix (O_SHLOCK, O_EXLOCK) constants
exposed on the API which are not implemented on GNU/Hurd. They would not
work at runtime anyway.

@item 
bpo-27025@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27025}: Generated names for Tkinter widgets are now more meaningful and
recognizable.

@item 
bpo-25455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25455}: Fixed crashes in repr of recursive ElementTree.Element and
functools.partial objects.

@item 
bpo-27294@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27294}: Improved repr for Tkinter event objects.

@item 
bpo-20508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20508}: Improve exception message of IPv@{4,6@}Network.__getitem__. Patch
by Gareth Rees.

@item 
bpo-21386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21386}: Implement missing IPv4Address.is_global property.  It was
documented since 07a5610bae9d.  Initial patch by Roger Luethi.

@item 
bpo-27029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27029}: Removed deprecated support of universal newlines mode from
ZipFile.open().

@item 
bpo-27030@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27030}: Unknown escapes consisting of @code{'\'} and an ASCII letter in
regular expressions now are errors.  The re.LOCALE flag now can be used
only with bytes patterns.

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Add os.PathLike support to DirEntry (part of 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}).
Initial patch by Jelle Zijlstra.

@item 
bpo-20900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20900}: distutils register command now decodes HTTP responses
correctly.  Initial patch by ingrid.

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Add os.PathLike support to pathlib, removing its provisional
status (part of PEP 519). Initial patch by Dusty Phillips.

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Add support for os.PathLike objects to os.fsencode() and
os.fsdecode() (part of 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}).

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Introduce os.PathLike and os.fspath() (part of 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}).

@item 
A new version of typing.py provides several new classes and features:
@@overload outside stubs, Reversible, DefaultDict, Text, ContextManager,
Type[], NewType(), TYPE_CHECKING, and numerous bug fixes (note that some
of the new features are not yet implemented in mypy or other static
analyzers). Also classes for 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} (Awaitable, AsyncIterable,
AsyncIterator) have been added (in fact they made it into 3.5.1 but were
never mentioned).

@item 
bpo-25738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25738}: Stop http.server.BaseHTTPRequestHandler.send_error() from
sending a message body for 205 Reset Content.  Also, don't send Content
header fields in responses that don't have a body.  Patch by Susumu
Koshiba.

@item 
bpo-21313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21313}: Fix the "platform" module to tolerate when sys.version contains
truncated build information.

@item 
bpo-23883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23883}: Added missing APIs to __all__ to match the documented APIs for
the following modules: cgi, mailbox, mimetypes, plistlib and smtpd.
Patches by Jacek Kołodziej.

@item 
bpo-27164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27164}: In the zlib module, allow decompressing raw Deflate streams
with a predefined zdict.  Based on patch by Xiang Zhang.

@item 
bpo-24291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24291}: Fix wsgiref.simple_server.WSGIRequestHandler to completely
write data to the client.  Previously it could do partial writes and
truncate data.  Also, wsgiref.handler.ServerHandler can now handle stdout
doing partial writes, but this is deprecated.

@item 
bpo-21272@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21272}: Use _sysconfigdata.py to initialize distutils.sysconfig.

@item 
bpo-19611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19611}: @ref{7d,,inspect} now reports the implicit @code{.0} parameters
generated by the compiler for comprehension and generator expression
scopes as if they were positional-only parameters called @code{implicit0}.
Patch by Jelle Zijlstra.

@item 
bpo-26809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26809}: Add @code{__all__} to @ref{d2,,string}.  Patch by Emanuel Barry.

@item 
bpo-26373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26373}: subprocess.Popen.communicate now correctly ignores
BrokenPipeError when the child process dies before .communicate() is
called in more/all circumstances.

@item 
signal, socket, and ssl module IntEnum constant name lookups now return a
consistent name for values having multiple names.  Ex: signal.Signals(6)
now refers to itself as signal.SIGALRM rather than flipping between that
and signal.SIGIOT based on the interpreter's hash randomization seed.

@item 
bpo-27167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27167}: Clarify the subprocess.CalledProcessError error message text
when the child process died due to a signal.

@item 
bpo-25931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25931}: Don't define socketserver.Forking* names on platforms such as
Windows that do not support os.fork().

@item 
bpo-21776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21776}: distutils.upload now correctly handles HTTPError. Initial patch
by Claudiu Popa.

@item 
bpo-26526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26526}: Replace custom parse tree validation in the parser module with
a simple DFA validator.

@item 
bpo-27114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27114}: Fix SSLContext._load_windows_store_certs fails with
PermissionError

@item 
bpo-18383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18383}: Avoid creating duplicate filters when using filterwarnings and
simplefilter. Based on patch by Alex Shkop.

@item 
bpo-23026@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23026}: winreg.QueryValueEx() now return an integer for REG_QWORD type.

@item 
bpo-26741@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26741}: subprocess.Popen destructor now emits a ResourceWarning warning
if the child process is still running.

@item 
bpo-27056@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27056}: Optimize pickle.load() and pickle.loads(), up to 10% faster to
deserialize a lot of small objects.

@item 
bpo-21271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21271}: New keyword only parameters in reset_mock call.
@end itemize

@node IDLE<55>,Documentation<66>,Library<77>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id668}@anchor{1ada}
@subsubsection IDLE



@itemize -

@item 
bpo-5124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5124}: Paste with text selected now replaces the selection on X11. This
matches how paste works on Windows, Mac, most modern Linux apps, and ttk
widgets. Original patch by Serhiy Storchaka.

@item 
bpo-24750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24750}: Switch all scrollbars in IDLE to ttk versions. Where needed,
minimal tests are added to cover changes.

@item 
bpo-24759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24759}: IDLE requires tk 8.5 and availability ttk widgets. Delete now
unneeded tk version tests and code for older versions. Add test for IDLE
syntax colorizer.

@item 
bpo-27239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27239}: idlelib.macosx.isXyzTk functions initialize as needed.

@item 
bpo-27262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27262}: move Aqua unbinding code, which enable context menus, to
macosx.

@item 
bpo-24759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24759}: Make clear in idlelib.idle_test.__init__ that the directory is
a private implementation of test.test_idle and tool for maintainers.

@item 
bpo-27196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27196}: Stop 'ThemeChanged' warnings when running IDLE tests. These
persisted after other warnings were suppressed in #20567. Apply Serhiy
Storchaka's update_idletasks solution to four test files. Record this
additional advice in idle_test/README.txt

@item 
bpo-20567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20567}: Revise idle_test/README.txt with advice about avoiding tk
warning messages from tests.  Apply advice to several IDLE tests.

@item 
bpo-24225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24225}: Update idlelib/README.txt with new file names and event
handlers.

@item 
bpo-27156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27156}: Remove obsolete code not used by IDLE.

@item 
bpo-27117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27117}: Make colorizer htest and turtledemo work with dark themes. Move
code for configuring text widget colors to a new function.

@item 
bpo-24225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24225}: Rename many @code{idlelib/*.py} and @code{idle_test/test_*.py} files.
Edit files to replace old names with new names when the old name referred
to the module rather than the class it contained. See the issue and IDLE
section in What's New in 3.6 for more.

@item 
bpo-26673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26673}: When tk reports font size as 0, change to size 10. Such fonts
on Linux prevented the configuration dialog from opening.

@item 
bpo-21939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21939}: Add test for IDLE's percolator. Original patch by Saimadhav
Heblikar.

@item 
bpo-21676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21676}: Add test for IDLE's replace dialog. Original patch by Saimadhav
Heblikar.

@item 
bpo-18410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18410}: Add test for IDLE's search dialog. Original patch by Westley
Martínez.

@item 
bpo-21703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21703}: Add test for undo delegator.  Patch mostly by Saimadhav
Heblikar .

@item 
bpo-27044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27044}: Add ConfigDialog.remove_var_callbacks to stop memory leaks.

@item 
bpo-23977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23977}: Add more asserts to test_delegator.
@end itemize

@node Documentation<66>,Tests<70>,IDLE<55>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id669}@anchor{1adb}
@subsubsection Documentation



@itemize -

@item 
bpo-16484@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16484}: Change the default PYTHONDOCS URL to "https:", and fix the
resulting links to use lowercase.  Patch by Sean Rodman, test by Kaushik
Nadikuditi.

@item 
bpo-24136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24136}: Document the new 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/} unpacking syntax of 3.5.

@item 
bpo-22558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22558}: Add remaining doc links to source code for Python-coded
modules. Patch by Yoni Lavi.
@end itemize

@node Tests<70>,Windows<66>,Documentation<66>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id670}@anchor{1adc}
@subsubsection Tests



@itemize -

@item 
bpo-25285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25285}: regrtest now uses subprocesses when the -j1 command line option
is used: each test file runs in a fresh child process. Before, the -j1
option was ignored.

@item 
bpo-25285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25285}: Tools/buildbot/test.bat script now uses -j1 by default to run
each test file in fresh child process.
@end itemize

@node Windows<66>,Build<76>,Tests<70>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id671}@anchor{1add}
@subsubsection Windows



@itemize -

@item 
bpo-27064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27064}: The py.exe launcher now defaults to Python 3. The Windows
launcher @code{py.exe} no longer prefers an installed Python 2 version over
Python 3 by default when used interactively.

@item 
bpo-17500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17500}: Remove unused and outdated icons. (See also:
@indicateurl{https://github.com/python/pythondotorg/issues/945})
@end itemize

@node Build<76>,C API<66>,Windows<66>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id672}@anchor{1ade}
@subsubsection Build



@itemize -

@item 
bpo-27229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27229}: Fix the cross-compiling pgen rule for in-tree builds.  Patch by
Xavier de Gaye.

@item 
bpo-26930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26930}: Update OS X 10.5+ 32-bit-only installer to build and link with
OpenSSL 1.0.2h.
@end itemize

@node C API<66>,Tools/Demos<41>,Build<76>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id673}@anchor{1adf}
@subsubsection C API



@itemize -

@item 
bpo-27186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27186}: Add the PyOS_FSPath() function (part of 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}).

@item 
bpo-26282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26282}: PyArg_ParseTupleAndKeywords() now supports positional-only
parameters.
@end itemize

@node Tools/Demos<41>,,C API<66>,Python 3 6 0 alpha 2
@anchor{whatsnew/changelog id674}@anchor{1ae0}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-26282@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26282}: Argument Clinic now supports positional-only and keyword
parameters in the same function.
@end itemize

@node Python 3 6 0 alpha 1,Python 3 5 5 final,Python 3 6 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-6-0-alpha-1}@anchor{1ae1}
@subsection Python 3.6.0 alpha 1


`Release date: 2016-05-16'

@menu
* Security: Security<45>. 
* Core and Builtins: Core and Builtins<79>. 
* Library: Library<78>. 
* IDLE: IDLE<56>. 
* Documentation: Documentation<67>. 
* Tests: Tests<71>. 
* Build: Build<77>. 
* Windows: Windows<67>. 
* Tools/Demos: Tools/Demos<42>. 
* C API: C API<67>. 

@end menu

@node Security<45>,Core and Builtins<79>,,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id675}@anchor{1ae2}
@subsubsection Security



@itemize -

@item 
bpo-26657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26657}: Fix directory traversal vulnerability with http.server on
Windows.  This fixes a regression that was introduced in 3.3.4rc1 and
3.4.0rc1.  Based on patch by Philipp Hagemeister.

@item 
bpo-26313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26313}: ssl.py _load_windows_store_certs fails if windows cert store is
empty. Patch by Baji.

@item 
bpo-25939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25939}: On Windows open the cert store readonly in
ssl.enum_certificates.
@end itemize

@node Core and Builtins<79>,Library<78>,Security<45>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id676}@anchor{1ae3}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-20041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20041}: Fixed TypeError when frame.f_trace is set to None. Patch by
Xavier de Gaye.

@item 
bpo-26168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26168}: Fixed possible refleaks in failing Py_BuildValue() with the "N"
format unit.

@item 
bpo-26991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26991}: Fix possible refleak when creating a function with annotations.

@item 
bpo-27039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27039}: Fixed bytearray.remove() for values greater than 127.  Based on
patch by Joe Jevnik.

@item 
bpo-23640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23640}: int.from_bytes() no longer bypasses constructors for
subclasses.

@item 
bpo-27005@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27005}: Optimized the float.fromhex() class method for exact float. It
is now 2 times faster.

@item 
bpo-18531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18531}: Single var-keyword argument of dict subtype was passed
unscathed to the C-defined function.  Now it is converted to exact dict.

@item 
bpo-26811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26811}: gc.get_objects() no longer contains a broken tuple with NULL
pointer.

@item 
bpo-20120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20120}: Use RawConfigParser for .pypirc parsing, removing support for
interpolation unintentionally added with move to Python 3. Behavior no
longer does any interpolation in .pypirc files, matching behavior in
Python 2.7 and Setuptools 19.0.

@item 
bpo-26249@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26249}: Memory functions of the @ref{c54,,PyMem_Malloc()} domain
(@ref{c57,,PYMEM_DOMAIN_MEM}) now use the @ref{cfd,,pymalloc allocator} rather than system @code{malloc()}. Applications calling
@ref{c54,,PyMem_Malloc()} without holding the GIL can now crash: use
@code{PYTHONMALLOC=debug} environment variable to validate the usage of
memory allocators in your application.

@item 
bpo-26802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26802}: Optimize function calls only using unpacking like
@code{func(*tuple)} (no other positional argument, no keyword): avoid copying
the tuple. Patch written by Joe Jevnik.

@item 
bpo-26659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26659}: Make the builtin slice type support cycle collection.

@item 
bpo-26718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26718}: super.__init__ no longer leaks memory if called multiple times.
NOTE: A direct call of super.__init__ is not endorsed!

@item 
bpo-27138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27138}: Fix the doc comment for FileFinder.find_spec().

@item 
bpo-27147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27147}: Mention 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} in the importlib docs.

@item 
bpo-25339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25339}: PYTHONIOENCODING now has priority over locale in setting the
error handler for stdin and stdout.

@item 
bpo-26494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26494}: Fixed crash on iterating exhausting iterators. Affected classes
are generic sequence iterators, iterators of str, bytes, bytearray, list,
tuple, set, frozenset, dict, OrderedDict, corresponding views and
os.scandir() iterator.

@item 
bpo-26574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26574}: Optimize @code{bytes.replace(b'@w{'}, b'.')} and
@code{bytearray.replace(b'@w{'}, b'.')}. Patch written by Josh Snider.

@item 
bpo-26581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26581}: If coding cookie is specified multiple times on a line in
Python source code file, only the first one is taken to account.

@item 
bpo-19711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19711}: Add tests for reloading namespace packages.

@item 
bpo-21099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21099}: Switch applicable importlib tests to use 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} API.

@item 
bpo-26563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26563}: Debug hooks on Python memory allocators now raise a fatal error
if functions of the @ref{c54,,PyMem_Malloc()} family are called without
holding the GIL.

@item 
bpo-26564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26564}: On error, the debug hooks on Python memory allocators now use
the @ref{fe,,tracemalloc} module to get the traceback where a memory block
was allocated.

@item 
bpo-26558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26558}: The debug hooks on Python memory allocator
@ref{c56,,PyObject_Malloc()} now detect when functions are called without
holding the GIL.

@item 
bpo-26516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26516}: Add 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable to set the
Python memory allocators and/or install debug hooks.

@item 
bpo-26516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26516}: The @ref{c58,,PyMem_SetupDebugHooks()} function can now also be
used on Python compiled in release mode.

@item 
bpo-26516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26516}: The 
@geindex PYTHONMALLOCSTATS
@geindex variable d'environnement; PYTHONMALLOCSTATS
@ref{1ae4,,PYTHONMALLOCSTATS} environment variable can now
also be used on Python compiled in release mode. It now has no effect if
set to an empty string.

@item 
bpo-26516@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26516}: In debug mode, debug hooks are now also installed on Python
memory allocators when Python is configured without pymalloc.

@item 
bpo-26464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26464}: Fix str.translate() when string is ASCII and first replacements
removes character, but next replacement uses a non-ASCII character or a
string longer than 1 character. Regression introduced in Python 3.5.0.

@item 
bpo-22836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22836}: Ensure exception reports from PyErr_Display() and
PyErr_WriteUnraisable() are sensible even when formatting them produces
secondary errors.  This affects the reports produced by
sys.__excepthook__() and when __del__() raises an exception.

@item 
bpo-26302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26302}: Correct behavior to reject comma as a legal character for
cookie names.

@item 
bpo-26136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26136}: Upgrade the warning when a generator raises StopIteration from
PendingDeprecationWarning to DeprecationWarning.  Patch by Anish Shah.

@item 
bpo-26204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26204}: The compiler now ignores all constant statements: bytes, str,
int, float, complex, name constants (None, False, True), Ellipsis and
ast.Constant; not only str and int. For example, @code{1.0} is now ignored in
@code{def f(): 1.0}.

@item 
bpo-4806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4806}: Avoid masking the original TypeError exception when using star
(@code{*}) unpacking in function calls.  Based on patch by Hagen Fürstenau
and Daniel Urban.

@item 
bpo-26146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26146}: Add a new kind of AST node: @code{ast.Constant}. It can be used by
external AST optimizers, but the compiler does not emit directly such
node.

@item 
bpo-23601@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23601}: Sped-up allocation of dict key objects by using Python's small
object allocator.  (Contributed by Julian Taylor.)

@item 
bpo-18018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18018}: Import raises ImportError instead of SystemError if a relative
import is attempted without a known parent package.

@item 
bpo-25843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25843}: When compiling code, don't merge constants if they are equal
but have a different types. For example, @code{f1, f2 = lambda: 1, lambda:
1.0} is now correctly compiled to two different functions: @code{f1()}
returns @code{1} (@code{int}) and @code{f2()} returns @code{1.0} (@code{float}), even if
@code{1} and @code{1.0} are equal.

@item 
bpo-26107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26107}: The format of the @code{co_lnotab} attribute of code objects
changes to support negative line number delta.

@item 
bpo-26154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26154}: Add a new private _PyThreadState_UncheckedGet() function to get
the current Python thread state, but don't issue a fatal error if it is
NULL. This new function must be used instead of accessing directly the
_PyThreadState_Current variable.  The variable is no more exposed since
Python 3.5.1 to hide the exact implementation of atomic C types, to avoid
compiler issues.

@item 
bpo-25791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25791}: If __package__ != __spec__.parent or if neither __package__ or
__spec__ are defined then ImportWarning is raised.

@item 
bpo-22995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22995}: [UPDATE] Comment out the one of the pickleability tests in
_PyObject_GetState() due to regressions observed in Cython-based projects.

@item 
bpo-25961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25961}: Disallowed null characters in the type name.

@item 
bpo-25973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25973}: Fix segfault when an invalid nonlocal statement binds a name
starting with two underscores.

@item 
bpo-22995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22995}: Instances of extension types with a state that aren't
subclasses of list or dict and haven't implemented any pickle-related
methods (__reduce__, __reduce_ex__, __getnewargs__, __getnewargs_ex__, or
__getstate__), can no longer be pickled.  Including memoryview.

@item 
bpo-20440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20440}: Massive replacing unsafe attribute setting code with special
macro Py_SETREF.

@item 
bpo-25766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25766}: Special method __bytes__() now works in str subclasses.

@item 
bpo-25421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25421}: __sizeof__ methods of builtin types now use dynamic basic size.
This allows sys.getsize() to work correctly with their subclasses with
__slots__ defined.

@item 
bpo-25709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25709}: Fixed problem with in-place string concatenation and utf-8
cache.

@item 
bpo-5319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5319}: New Py_FinalizeEx() API allowing Python to set an exit status of
120 on failure to flush buffered streams.

@item 
bpo-25485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25485}: telnetlib.Telnet is now a context manager.

@item 
bpo-24097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24097}: Fixed crash in object.__reduce__() if slot name is freed inside
__getattr__.

@item 
bpo-24731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24731}: Fixed crash on converting objects with special methods
__bytes__, __trunc__, and __float__ returning instances of subclasses of
bytes, int, and float to subclasses of bytes, int, and float
correspondingly.

@item 
bpo-25630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25630}: Fix a possible segfault during argument parsing in functions
that accept filesystem paths.

@item 
bpo-23564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23564}: Fixed a partially broken sanity check in the _posixsubprocess
internals regarding how fds_to_pass were passed to the child.  The bug had
no actual impact as subprocess.py already avoided it.

@item 
bpo-25388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25388}: Fixed tokenizer crash when processing undecodable source code
with a null byte.

@item 
bpo-25462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25462}: The hash of the key now is calculated only once in most
operations in C implementation of OrderedDict.

@item 
bpo-22995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22995}: Default implementation of __reduce__ and __reduce_ex__ now
rejects builtin types with not defined __new__.

@item 
bpo-24802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24802}: Avoid buffer overreads when int(), float(), compile(), exec()
and eval() are passed bytes-like objects.  These objects are not
necessarily terminated by a null byte, but the functions assumed they
were.

@item 
bpo-25555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25555}: Fix parser and AST: fill lineno and col_offset of "arg" node
when compiling AST from Python objects.

@item 
bpo-24726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24726}: Fixed a crash and leaking NULL in repr() of OrderedDict that
was mutated by direct calls of dict methods.

@item 
bpo-25449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25449}: Iterating OrderedDict with keys with unstable hash now raises
KeyError in C implementations as well as in Python implementation.

@item 
bpo-25395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25395}: Fixed crash when highly nested OrderedDict structures were
garbage collected.

@item 
bpo-25401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25401}: Optimize bytes.fromhex() and bytearray.fromhex(): they are now
between 2x and 3.5x faster.

@item 
bpo-25399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25399}: Optimize bytearray % args using the new private _PyBytesWriter
API. Formatting is now between 2.5 and 5 times faster.

@item 
bpo-25274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25274}: sys.setrecursionlimit() now raises a RecursionError if the new
recursion limit is too low depending at the current recursion depth.
Modify also the "lower-water mark" formula to make it monotonic. This mark
is used to decide when the overflowed flag of the thread state is reset.

@item 
bpo-24402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24402}: Fix input() to prompt to the redirected stdout when
sys.stdout.fileno() fails.

@item 
bpo-25349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25349}: Optimize bytes % args using the new private _PyBytesWriter API.
Formatting is now up to 2 times faster.

@item 
bpo-24806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24806}: Prevent builtin types that are not allowed to be subclassed
from being subclassed through multiple inheritance.

@item 
bpo-25301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25301}: The UTF-8 decoder is now up to 15 times as fast for error
handlers: @code{ignore}, @code{replace} and @code{surrogateescape}.

@item 
bpo-24848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24848}: Fixed a number of bugs in UTF-7 decoding of misformed data.

@item 
bpo-25267@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25267}: The UTF-8 encoder is now up to 75 times as fast for error
handlers: @code{ignore}, @code{replace}, @code{surrogateescape}, @code{surrogatepass}.
Patch co-written with Serhiy Storchaka.

@item 
bpo-25280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25280}: Import trace messages emitted in verbose (-v) mode are no
longer formatted twice.

@item 
bpo-25227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25227}: Optimize ASCII and latin1 encoders with the @code{surrogateescape}
error handler: the encoders are now up to 3 times as fast. Initial patch
written by Serhiy Storchaka.

@item 
bpo-25003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25003}: On Solaris 11.3 or newer, os.urandom() now uses the getrandom()
function instead of the getentropy() function. The getentropy() function
is blocking to generate very good quality entropy, os.urandom() doesn't
need such high-quality entropy.

@item 
bpo-9232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9232}: Modify Python's grammar to allow trailing commas in the argument
list of a function declaration.  For example, "def f(*, a = 3,): pass" is
now legal. Patch from Mark Dickinson.

@item 
bpo-24965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24965}: Implement 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/} "Literal String Interpolation". This
allows you to embed expressions inside f-strings, which are converted to
normal strings at run time. Given x=3, then f'value=@{x@}' == 'value=3'.
Patch by Eric V. Smith.

@item 
bpo-26478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26478}: Fix semantic bugs when using binary operators with dictionary
views and tuples.

@item 
bpo-26171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26171}: Fix possible integer overflow and heap corruption in
zipimporter.get_data().

@item 
bpo-25660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25660}: Fix TAB key behaviour in REPL with readline.

@item 
bpo-26288@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26288}: Optimize PyLong_AsDouble.

@item 
bpo-26289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26289}: Optimize floor and modulo division for single-digit longs.
Microbenchmarks show 2-2.5x improvement.  Built-in 'divmod' function is
now also ~10% faster. (See also: bpo-26315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26315})

@item 
bpo-25887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25887}: Raise a RuntimeError when a coroutine object is awaited more
than once.
@end itemize

@node Library<78>,IDLE<56>,Core and Builtins<79>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id677}@anchor{1ae5}
@subsubsection Library



@itemize -

@item 
bpo-27057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27057}: Fix os.set_inheritable() on Android, ioctl() is blocked by
SELinux and fails with EACCESS. The function now falls back to fcntl().
Patch written by Michał Bednarski.

@item 
bpo-27014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27014}: Fix infinite recursion using typing.py.  Thanks to Kalle Tuure!

@item 
bpo-27031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27031}: Removed dummy methods in Tkinter widget classes: tk_menuBar()
and tk_bindForTraversal().

@item 
bpo-14132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14132}: Fix urllib.request redirect handling when the target only has a
query string.  Original fix by Ján Janech.

@item 
bpo-17214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17214}: The "urllib.request" module now percent-encodes non-ASCII bytes
found in redirect target URLs.  Some servers send Location header fields
with non-ASCII bytes, but "http.client" requires the request target to be
ASCII-encodable, otherwise a UnicodeEncodeError is raised.  Based on patch
by Christian Heimes.

@item 
bpo-27033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27033}: The default value of the decode_data parameter for
smtpd.SMTPChannel and smtpd.SMTPServer constructors is changed to False.

@item 
bpo-27034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27034}: Removed deprecated class asynchat.fifo.

@item 
bpo-26870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26870}: Added readline.set_auto_history(), which can stop entries being
automatically added to the history list.  Based on patch by Tyler
Crompton.

@item 
bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}: zipfile.ZipFile.open() can now be used to write data into a ZIP
file, as well as for extracting data.  Patch by Thomas Kluyver.

@item 
bpo-26892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26892}: Honor debuglevel flag in urllib.request.HTTPHandler. Patch
contributed by Chi Hsuan Yen.

@item 
bpo-22274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22274}: In the subprocess module, allow stderr to be redirected to
stdout even when stdout is not redirected.  Patch by Akira Li.

@item 
bpo-26807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26807}: mock_open 'files' no longer error on readline at end of file.
Patch from Yolanda Robla.

@item 
bpo-25745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25745}: Fixed leaking a userptr in curses panel destructor.

@item 
bpo-26977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26977}: Removed unnecessary, and ignored, call to sum of squares helper
in statistics.pvariance.

@item 
bpo-26002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26002}: Use bisect in statistics.median instead of a linear search.
Patch by Upendra Kuma.

@item 
bpo-25974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25974}: Make use of new Decimal.as_integer_ratio() method in statistics
module. Patch by Stefan Krah.

@item 
bpo-26996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26996}: Add secrets module as described in 
@geindex Python Enhancement Proposals; PEP 506
PEP 506@footnote{https://peps.python.org/pep-0506/}.

@item 
bpo-26881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26881}: The modulefinder module now supports extended opcode arguments.

@item 
bpo-23815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23815}: Fixed crashes related to directly created instances of types in
_tkinter and curses.panel modules.

@item 
bpo-17765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17765}: weakref.ref() no longer silently ignores keyword arguments.
Patch by Georg Brandl.

@item 
bpo-26873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26873}: xmlrpc now raises ResponseError on unsupported type tags
instead of silently return incorrect result.

@item 
bpo-26915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26915}: The __contains__ methods in the collections ABCs now check for
identity before checking equality.  This better matches the behavior of
the concrete classes, allows sensible handling of NaNs, and makes it
easier to reason about container invariants.

@item 
bpo-26711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26711}: Fixed the comparison of plistlib.Data with other types.

@item 
bpo-24114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24114}: Fix an uninitialized variable in @code{ctypes.util}. The bug only
occurs on SunOS when the ctypes implementation searches for the @code{crle}
program. Patch by Xiang Zhang.  Tested on SunOS by Kees Bos.

@item 
bpo-26864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26864}: In urllib.request, change the proxy bypass host checking
against no_proxy to be case-insensitive, and to not match unrelated host
names that happen to have a bypassed hostname as a suffix.  Patch by Xiang
Zhang.

@item 
bpo-24902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24902}: Print server URL on http.server startup.  Initial patch by
Felix Kaiser.

@item 
bpo-25788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25788}: fileinput.hook_encoded() now supports an "errors" argument for
passing to open.  Original patch by Joseph Hackman.

@item 
bpo-26634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26634}: recursive_repr() now sets __qualname__ of wrapper.  Patch by
Xiang Zhang.

@item 
bpo-26804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26804}: urllib.request will prefer lower_case proxy environment
variables over UPPER_CASE or Mixed_Case ones. Patch contributed by
Hans-Peter Jansen.

@item 
bpo-26837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26837}: assertSequenceEqual() now correctly outputs non-stringified
differing items (like bytes in the -b mode).  This affects
assertListEqual() and assertTupleEqual().

@item 
bpo-26041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26041}: Remove "will be removed in Python 3.7" from deprecation
messages of platform.dist() and platform.linux_distribution(). Patch by
Kumaripaba Miyurusara Athukorala.

@item 
bpo-26822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26822}: itemgetter, attrgetter and methodcaller objects no longer
silently ignore keyword arguments.

@item 
bpo-26733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26733}: Disassembling a class now disassembles class and static
methods. Patch by Xiang Zhang.

@item 
bpo-26801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26801}: Fix error handling in @ref{10e3,,shutil.get_terminal_size()}, catch
@ref{343,,AttributeError} instead of @ref{428,,NameError}. Patch written by
Emanuel Barry.

@item 
bpo-24838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24838}: tarfile's ustar and gnu formats now correctly calculate name
and link field limits for multibyte character encodings like utf-8.

@item 
bpo-26717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26717}: Stop encoding Latin-1-ized WSGI paths with UTF-8.  Patch by
Anthony Sottile.

@item 
bpo-26782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26782}: Add STARTUPINFO to subprocess.__all__ on Windows.

@item 
bpo-26404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26404}: Add context manager to socketserver.  Patch by Aviv Palivoda.

@item 
bpo-26735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26735}: Fix @ref{50c,,os.urandom()} on Solaris 11.3 and newer when reading
more than 1,024 bytes: call @code{getrandom()} multiple times with a limit of
1024 bytes per call.

@item 
bpo-26585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26585}: Eliminate http.server._quote_html() and use
html.escape(quote=False).  Patch by Xiang Zhang.

@item 
bpo-26685@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26685}: Raise OSError if closing a socket fails.

@item 
bpo-16329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16329}: Add .webm to mimetypes.types_map.  Patch by Giampaolo Rodola'.

@item 
bpo-13952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13952}: Add .csv to mimetypes.types_map.  Patch by Geoff Wilson.

@item 
bpo-26587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26587}: the site module now allows .pth files to specify files to be
added to sys.path (e.g. zip files).

@item 
bpo-25609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25609}: Introduce contextlib.AbstractContextManager and
typing.ContextManager.

@item 
bpo-26709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26709}: Fixed Y2038 problem in loading binary PLists.

@item 
bpo-23735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23735}: Handle terminal resizing with Readline 6.3+ by installing our
own SIGWINCH handler.  Patch by Eric Price.

@item 
bpo-25951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25951}: Change SSLSocket.sendall() to return None, as explicitly
documented for plain socket objects.  Patch by Aviv Palivoda.

@item 
bpo-26586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26586}: In http.server, respond with "413 Request header fields too
large" if there are too many header fields to parse, rather than killing
the connection and raising an unhandled exception.  Patch by Xiang Zhang.

@item 
bpo-26676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26676}: Added missing XMLPullParser to ElementTree.__all__.

@item 
bpo-22854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22854}: Change BufferedReader.writable() and BufferedWriter.readable()
to always return False.

@item 
bpo-26492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26492}: Exhausted iterator of array.array now conforms with the
behavior of iterators of other mutable sequences: it lefts exhausted even
if iterated array is extended.

@item 
bpo-26641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26641}: doctest.DocFileTest and doctest.testfile() now support packages
(module splitted into multiple directories) for the package parameter.

@item 
bpo-25195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25195}: Fix a regression in mock.MagicMock. _Call is a subclass of
tuple (changeset 3603bae63c13 only works for classes) so we need to
implement __ne__ ourselves.  Patch by Andrew Plummer.

@item 
bpo-26644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26644}: Raise ValueError rather than SystemError when a negative length
is passed to SSLSocket.recv() or read().

@item 
bpo-23804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23804}: Fix SSL recv(0) and read(0) methods to return zero bytes
instead of up to 1024.

@item 
bpo-26616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26616}: Fixed a bug in datetime.astimezone() method.

@item 
bpo-26637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26637}: The @ref{76,,importlib} module now emits an @ref{40f,,ImportError}
rather than a @ref{522,,TypeError} if @ref{8c1,,__import__()} is tried during the
Python shutdown process but @ref{3ab,,sys.path} is already cleared (set to
@code{None}).

@item 
bpo-21925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21925}: @ref{19a3,,warnings.formatwarning()} now catches exceptions when
calling @ref{e10,,linecache.getline()} and
@ref{1ae6,,tracemalloc.get_object_traceback()} to be able to log
@ref{241,,ResourceWarning} emitted late during the Python shutdown process.

@item 
bpo-23848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23848}: On Windows, faulthandler.enable() now also installs an
exception handler to dump the traceback of all Python threads on any
Windows exception, not only on UNIX signals (SIGSEGV, SIGFPE, SIGABRT).

@item 
bpo-26530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26530}: Add C functions @code{_PyTraceMalloc_Track()} and
@code{_PyTraceMalloc_Untrack()} to track memory blocks using the
@ref{fe,,tracemalloc} module. Add @code{_PyTraceMalloc_GetTraceback()} to
get the traceback of an object.

@item 
bpo-26588@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26588}: The _tracemalloc now supports tracing memory allocations of
multiple address spaces (domains).

@item 
bpo-24266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24266}: Ctrl+C during Readline history search now cancels the search
mode when compiled with Readline 7.

@item 
bpo-26590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26590}: Implement a safe finalizer for the _socket.socket type. It now
releases the GIL to close the socket.

@item 
bpo-18787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18787}: spwd.getspnam() now raises a PermissionError if the user
doesn't have privileges.

@item 
bpo-26560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26560}: Avoid potential ValueError in BaseHandler.start_response.
Initial patch by Peter Inglesby.

@item 
bpo-26567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26567}: Add a new function @ref{d05,,PyErr_ResourceWarning()} function to
pass the destroyed object. Add a `source' attribute to
@code{warnings.WarningMessage}. Add warnings._showwarnmsg() which uses
tracemalloc to get the traceback where source object was allocated.

@item 
bpo-26569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26569}: Fix @ref{815,,pyclbr.readmodule()} and @ref{816,,pyclbr.readmodule_ex()}
to support importing packages.

@item 
bpo-26499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26499}: Account for remaining Content-Length in HTTPResponse.readline()
and read1(). Based on patch by Silent Ghost. Also document that
HTTPResponse now supports these methods.

@item 
bpo-25320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25320}: Handle sockets in directories unittest discovery is scanning.
Patch from Victor van den Elzen.

@item 
bpo-16181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16181}: cookiejar.http2time() now returns None if year is higher than
datetime.MAXYEAR.

@item 
bpo-26513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26513}: Fixes platform module detection of Windows Server

@item 
bpo-23718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23718}: Fixed parsing time in week 0 before Jan 1.  Original patch by
Tamás Bence Gedai.

@item 
bpo-26323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26323}: Add Mock.assert_called() and Mock.assert_called_once() methods
to unittest.mock. Patch written by Amit Saha.

@item 
bpo-20589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20589}: Invoking Path.owner() and Path.group() on Windows now raise
NotImplementedError instead of ImportError.

@item 
bpo-26177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26177}: Fixed the keys() method for Canvas and Scrollbar widgets.

@item 
bpo-15068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15068}: Got rid of excessive buffering in fileinput. The bufsize
parameter is now deprecated and ignored.

@item 
bpo-19475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19475}: Added an optional argument timespec to the datetime isoformat()
method to choose the precision of the time component.

@item 
bpo-2202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2202}: Fix UnboundLocalError in
AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu
Dupuy.

@item 
bpo-26167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26167}: Minimized overhead in copy.copy() and copy.deepcopy().
Optimized copying and deepcopying bytearrays, NotImplemented, slices,
short lists, tuples, dicts, sets.

@item 
bpo-25718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25718}: Fixed pickling and copying the accumulate() iterator with total
is None.

@item 
bpo-26475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26475}: Fixed debugging output for regular expressions with the (?x)
flag.

@item 
bpo-26482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26482}: Allowed pickling recursive dequeues.

@item 
bpo-26335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26335}: Make mmap.write() return the number of bytes written like other
write methods.  Patch by Jakub Stasiak.

@item 
bpo-26457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26457}: Fixed the subnets() methods in IP network classes for the case
when resulting prefix length is equal to maximal prefix length. Based on
patch by Xiang Zhang.

@item 
bpo-26385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26385}: Remove the file if the internal open() call in
NamedTemporaryFile() fails. Patch by Silent Ghost.

@item 
bpo-26402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26402}: Fix XML-RPC client to retry when the server shuts down a
persistent connection.  This was a regression related to the new
http.client.RemoteDisconnected exception in 3.5.0a4.

@item 
bpo-25913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25913}: Leading @code{<~} is optional now in base64.a85decode() with
adobe=True.  Patch by Swati Jaiswal.

@item 
bpo-26186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26186}: Remove an invalid type check in importlib.util.LazyLoader.

@item 
bpo-26367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26367}: importlib.__import__() raises ImportError like
builtins.__import__() when @code{level} is specified but without an
accompanying package specified.

@item 
bpo-26309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26309}: In the "socketserver" module, shut down the request (closing
the connected socket) when verify_request() returns false.  Patch by Aviv
Palivoda.

@item 
bpo-23430@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23430}: Change the socketserver module to only catch exceptions raised
from a request handler that are derived from Exception (instead of
BaseException). Therefore SystemExit and KeyboardInterrupt no longer
trigger the handle_error() method, and will now to stop a single-threaded
server.

@item 
bpo-25995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25995}: os.walk() no longer uses FDs proportional to the tree depth.

@item 
bpo-25994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25994}: Added the close() method and the support of the context manager
protocol for the os.scandir() iterator.

@item 
bpo-23992@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23992}: multiprocessing: make MapResult not fail-fast upon exception.

@item 
bpo-26243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26243}: Support keyword arguments to zlib.compress().  Patch by Aviv
Palivoda.

@item 
bpo-26117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26117}: The os.scandir() iterator now closes file descriptor not only
when the iteration is finished, but when it was failed with error.

@item 
bpo-25949@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25949}: __dict__ for an OrderedDict instance is now created only when
needed.

@item 
bpo-25911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25911}: Restored support of bytes paths in os.walk() on Windows.

@item 
bpo-26045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26045}: Add UTF-8 suggestion to error message when posting a
non-Latin-1 string with http.client.

@item 
bpo-26039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26039}: Added zipfile.ZipInfo.from_file() and zipinfo.ZipInfo.is_dir().
Patch by Thomas Kluyver.

@item 
bpo-12923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12923}: Reset FancyURLopener's redirect counter even if there is an
exception. Based on patches by Brian Brazil and Daniel Rocco.

@item 
bpo-25945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25945}: Fixed a crash when unpickle the functools.partial object with
wrong state. Fixed a leak in failed functools.partial constructor. "args"
and "keywords" attributes of functools.partial have now always types tuple
and dict correspondingly.

@item 
bpo-26202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26202}: copy.deepcopy() now correctly copies range() objects with
non-atomic attributes.

@item 
bpo-23076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23076}: Path.glob() now raises a ValueError if it's called with an
invalid pattern. Patch by Thomas Nyberg.

@item 
bpo-19883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19883}: Fixed possible integer overflows in zipimport.

@item 
bpo-26227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26227}: On Windows, getnameinfo(), gethostbyaddr() and
gethostbyname_ex() functions of the socket module now decode the hostname
from the ANSI code page rather than UTF-8.

@item 
bpo-26099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26099}: The site module now writes an error into stderr if
sitecustomize module can be imported but executing the module raise an
ImportError. Same change for usercustomize.

@item 
bpo-26147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26147}: xmlrpc now works with strings not encodable with used non-UTF-8
encoding.

@item 
bpo-25935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25935}: Garbage collector now breaks reference loops with OrderedDict.

@item 
bpo-16620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16620}: Fixed AttributeError in msilib.Directory.glob().

@item 
bpo-26013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26013}: Added compatibility with broken protocol 2 pickles created in
old Python 3 versions (3.4.3 and lower).

@item 
bpo-26129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26129}: Deprecated accepting non-integers in grp.getgrgid().

@item 
bpo-25850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25850}: Use cross-compilation by default for 64-bit Windows.

@item 
bpo-25822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25822}: Add docstrings to the fields of urllib.parse results. Patch
contributed by Swati Jaiswal.

@item 
bpo-22642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22642}: Convert trace module option parsing mechanism to argparse.
Patch contributed by SilentGhost.

@item 
bpo-24705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24705}: Fix sysconfig._parse_makefile not expanding $@{@} vars appearing
before $() vars.

@item 
bpo-26069@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26069}: Remove the deprecated apis in the trace module.

@item 
bpo-22138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22138}: Fix mock.patch behavior when patching descriptors. Restore
original values after patching. Patch contributed by Sean McCully.

@item 
bpo-25672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25672}: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode
option if it is safe to do so.

@item 
bpo-26012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26012}: Don't traverse into symlinks for @code{**} pattern in
pathlib.Path.[r]glob().

@item 
bpo-24120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24120}: Ignore PermissionError when traversing a tree with
pathlib.Path.[r]glob(). Patch by Ulrich Petri.

@item 
bpo-21815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21815}: Accept ] characters in the data portion of imap responses, in
order to handle the flags with square brackets accepted and produced by
servers such as gmail.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: fileinput now uses sys.stdin as-is if it does not have a buffer
attribute (restores backward compatibility).

@item 
bpo-25971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25971}: Optimized creating Fractions from floats by 2 times and from
Decimals by 3 times.

@item 
bpo-25802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25802}: Document as deprecated the remaining implementations of
importlib.abc.Loader.load_module().

@item 
bpo-25928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25928}: Add Decimal.as_integer_ratio().

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: Copying the lru_cache() wrapper object now always works,
independently from the type of the wrapped object (by returning the
original object unchanged).

@item 
bpo-25768@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25768}: Have the functions in compileall return booleans instead of
ints and add proper documentation and tests for the return values.

@item 
bpo-24103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24103}: Fixed possible use after free in ElementTree.XMLPullParser.

@item 
bpo-25860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25860}: os.fwalk() no longer skips remaining directories when error
occurs. Original patch by Samson Lee.

@item 
bpo-25914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25914}: Fixed and simplified OrderedDict.__sizeof__.

@item 
bpo-25869@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25869}: Optimized deepcopying ElementTree; it is now 20 times faster.

@item 
bpo-25873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25873}: Optimized iterating ElementTree.  Iterating elements
Element.iter() is now 40% faster, iterating text Element.itertext() is now
up to 2.5 times faster.

@item 
bpo-25902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25902}: Fixed various refcount issues in ElementTree iteration.

@item 
bpo-22227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22227}: The TarFile iterator is reimplemented using generator. This
implementation is simpler that using class.

@item 
bpo-25638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25638}: Optimized ElementTree.iterparse(); it is now 2x faster.
Optimized ElementTree parsing; it is now 10% faster.

@item 
bpo-25761@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25761}: Improved detecting errors in broken pickle data.

@item 
bpo-25717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25717}: Restore the previous behaviour of tolerating most fstat()
errors when opening files.  This was a regression in 3.5a1, and stopped
anonymous temporary files from working in special cases.

@item 
bpo-24903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24903}: Fix regression in number of arguments compileall accepts when
'-d' is specified.  The check on the number of arguments has been dropped
completely as it never worked correctly anyway.

@item 
bpo-25764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25764}: In the subprocess module, preserve any exception caused by
fork() failure when preexec_fn is used.

@item 
bpo-25771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25771}: Tweak the exception message for importlib.util.resolve_name()
when 'package' isn't specified but necessary.

@item 
bpo-6478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6478}: _strptime's regexp cache now is reset after changing timezone
with time.tzset().

@item 
bpo-14285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14285}: When executing a package with the "python -m package" option,
and package initialization fails, a proper traceback is now reported.  The
"runpy" module now lets exceptions from package initialization pass back
to the caller, rather than raising ImportError.

@item 
bpo-19771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19771}: Also in runpy and the "-m" option, omit the irrelevant message
". . . is a package and cannot be directly executed" if the package could
not even be initialized (e.g. due to a bad @code{*.pyc} file).

@item 
bpo-25177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25177}: Fixed problem with the mean of very small and very large
numbers. As a side effect, statistics.mean and statistics.variance should
be significantly faster.

@item 
bpo-25718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25718}: Fixed copying object with state with boolean value is false.

@item 
bpo-10131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10131}: Fixed deep copying of minidom documents.  Based on patch by
Marian Ganisin.

@item 
bpo-7990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7990}: dir() on ElementTree.Element now lists properties: "tag",
"text", "tail" and "attrib".  Original patch by Santoso Wijaya.

@item 
bpo-25725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25725}: Fixed a reference leak in pickle.loads() when unpickling
invalid data including tuple instructions.

@item 
bpo-25663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25663}: In the Readline completer, avoid listing duplicate global
names, and search the global namespace before searching builtins.

@item 
bpo-25688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25688}: Fixed file leak in ElementTree.iterparse() raising an error.

@item 
bpo-23914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23914}: Fixed SystemError raised by unpickler on broken pickle data.

@item 
bpo-25691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25691}: Fixed crash on deleting ElementTree.Element attributes.

@item 
bpo-25624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25624}: ZipFile now always writes a ZIP_STORED header for directory
entries.  Patch by Dingyuan Wang.

@item 
bpo-25626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25626}: Change three zlib functions to accept sizes that fit in
Py_ssize_t, but internally cap those sizes to UINT_MAX.  This resolves a
regression in 3.5 where GzipFile.read() failed to read chunks larger than
2 or 4 GiB.  The change affects the zlib.Decompress.decompress()
max_length parameter, the zlib.decompress() bufsize parameter, and the
zlib.Decompress.flush() length parameter.

@item 
bpo-25583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25583}: Avoid incorrect errors raised by os.makedirs(exist_ok=True)
when the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-25593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25593}: Change semantics of EventLoop.stop() in asyncio.

@item 
bpo-6973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6973}: When we know a subprocess.Popen process has died, do not allow
the send_signal(), terminate(), or kill() methods to do anything as they
could potentially signal a different process.

@item 
bpo-23883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23883}: Added missing APIs to __all__ to match the documented APIs for
the following modules: calendar, csv, enum, fileinput, ftplib, logging,
optparse, tarfile, threading and wave.  Also added a
test.support.check__all__() helper. Patches by Jacek Kołodziej, Mauro S.
M. Rodrigues and Joel Taddei.

@item 
bpo-25590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25590}: In the Readline completer, only call getattr() once per
attribute.  Also complete names of attributes such as properties and slots
which are listed by dir() but not yet created on an instance.

@item 
bpo-25498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25498}: Fix a crash when garbage-collecting ctypes objects created by
wrapping a memoryview.  This was a regression made in 3.5a1.  Based on
patch by Eryksun.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Added "escape" to the __all__ list in the glob module.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Fixed recursive glob() with patterns starting with @code{**}.

@item 
bpo-25446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25446}: Fix regression in smtplib's AUTH LOGIN support.

@item 
bpo-18010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18010}: Fix the pydoc web server's module search function to handle
exceptions from importing packages.

@item 
bpo-25554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25554}: Got rid of circular references in regular expression parsing.

@item 
bpo-18973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18973}: Command-line interface of the calendar module now uses argparse
instead of optparse.

@item 
bpo-25510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25510}: fileinput.FileInput.readline() now returns b'@w{'} instead of '@w{'} at
the end if the FileInput was opened with binary mode. Patch by Ryosuke
Ito.

@item 
bpo-25503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25503}: Fixed inspect.getdoc() for inherited docstrings of properties.
Original patch by John Mark Vandenberg.

@item 
bpo-25515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25515}: Always use os.urandom as a source of randomness in uuid.uuid4.

@item 
bpo-21827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21827}: Fixed textwrap.dedent() for the case when largest common
whitespace is a substring of smallest leading whitespace. Based on patch
by Robert Li.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: The lru_cache() wrapper objects now can be copied and pickled
(by returning the original object unchanged).

@item 
bpo-25390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25390}: typing: Don't crash on Union[str, Pattern].

@item 
bpo-25441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25441}: asyncio: Raise error from drain() when socket is closed.

@item 
bpo-25410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25410}: Cleaned up and fixed minor bugs in C implementation of
OrderedDict.

@item 
bpo-25411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25411}: Improved Unicode support in SMTPHandler through better use of
the email package. Thanks to user simon04 for the patch.

@item 
Move the imp module from a PendingDeprecationWarning to
DeprecationWarning.

@item 
bpo-25407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25407}: Remove mentions of the formatter module being removed in Python
3.6.

@item 
bpo-25406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25406}: Fixed a bug in C implementation of OrderedDict.move_to_end()
that caused segmentation fault or hang in iterating after moving several
items to the start of ordered dict.

@item 
bpo-25382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25382}: pickletools.dis() now outputs implicit memo index for the
MEMOIZE opcode.

@item 
bpo-25357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25357}: Add an optional newline parameter to binascii.b2a_base64().
base64.b64encode() uses it to avoid a memory copy.

@item 
bpo-24164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24164}: Objects that need calling @code{__new__} with keyword arguments,
can now be pickled using pickle protocols older than protocol version 4.

@item 
bpo-25364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25364}: zipfile now works in threads disabled builds.

@item 
bpo-25328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25328}: smtpd's SMTPChannel now correctly raises a ValueError if both
decode_data and enable_SMTPUTF8 are set to true.

@item 
bpo-16099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16099}: RobotFileParser now supports Crawl-delay and Request-rate
extensions.  Patch by Nikolay Bogoychev.

@item 
bpo-25316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25316}: distutils raises OSError instead of DistutilsPlatformError when
MSVC is not installed.

@item 
bpo-25380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25380}: Fixed protocol for the STACK_GLOBAL opcode in
pickletools.opcodes.

@item 
bpo-23972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23972}: Updates asyncio datagram create method allowing reuseport and
reuseaddr socket options to be set prior to binding the socket. Mirroring
the existing asyncio create_server method the reuseaddr option for
datagram sockets defaults to True if the O/S is 'posix' (except if the
platform is Cygwin). Patch by Chris Laws.

@item 
bpo-25304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25304}: Add asyncio.run_coroutine_threadsafe().  This lets you submit a
coroutine to a loop from another thread, returning a
concurrent.futures.Future.  By Vincent Michel.

@item 
bpo-25232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25232}: Fix CGIRequestHandler to split the query from the URL at the
first question mark (?) rather than the last. Patch from Xiang Zhang.

@item 
bpo-24657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24657}: Prevent CGIRequestHandler from collapsing slashes in the query
part of the URL as if it were a path. Patch from Xiang Zhang.

@item 
bpo-25287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25287}: Don't add crypt.METHOD_CRYPT to crypt.methods if it's not
supported. Check if it is supported, it may not be supported on OpenBSD
for example.

@item 
bpo-23600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23600}: Default implementation of tzinfo.fromutc() was returning wrong
results in some cases.

@item 
bpo-25203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25203}: Failed readline.set_completer_delims() no longer left the
module in inconsistent state.

@item 
bpo-25011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25011}: rlcompleter now omits private and special attribute names
unless the prefix starts with underscores.

@item 
bpo-25209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25209}: rlcompleter now can add a space or a colon after completed
keyword.

@item 
bpo-22241@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22241}: timezone.utc name is now plain 'UTC', not 'UTC-00:00'.

@item 
bpo-23517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23517}: fromtimestamp() and utcfromtimestamp() methods of
datetime.datetime now round microseconds to nearest with ties going to
nearest even integer (ROUND_HALF_EVEN), as round(float), instead of
rounding towards -Infinity (ROUND_FLOOR).

@item 
bpo-23552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23552}: Timeit now warns when there is substantial (4x) variance
between best and worst times. Patch from Serhiy Storchaka.

@item 
bpo-24633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24633}: site-packages/README -> README.txt.

@item 
bpo-24879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24879}: help() and pydoc can now list named tuple fields in the order
they were defined rather than alphabetically.  The ordering is determined
by the _fields attribute if present.

@item 
bpo-24874@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24874}: Improve speed of itertools.cycle() and make its pickle more
compact.

@item 
Fix crash in itertools.cycle.__setstate__() when the first argument wasn't
a list.

@item 
bpo-20059@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20059}: urllib.parse raises ValueError on all invalid ports. Patch by
Martin Panter.

@item 
bpo-24360@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24360}: Improve __repr__ of argparse.Namespace() for invalid
identifiers.  Patch by Matthias Bussonnier.

@item 
bpo-23426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23426}: run_setup was broken in distutils. Patch from Alexander
Belopolsky.

@item 
bpo-13938@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13938}: 2to3 converts StringTypes to a tuple. Patch from Mark Hammond.

@item 
bpo-2091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2091}: open() accepted a 'U' mode string containing '+', but 'U' can
only be used with 'r'. Patch from Jeff Balogh and John O'Connor.

@item 
bpo-8585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8585}: improved tests for zipimporter2. Patch from Mark Lawrence.

@item 
bpo-18622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18622}: unittest.mock.mock_open().reset_mock would recurse infinitely.
Patch from Nicola Palumbo and Laurent De Buyst.

@item 
bpo-24426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24426}: Fast searching optimization in regular expressions now works
for patterns that starts with capturing groups.  Fast searching
optimization now can't be disabled at compile time.

@item 
bpo-23661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23661}: unittest.mock side_effects can now be exceptions again. This
was a regression vs Python 3.4. Patch from Ignacio Rossi

@item 
bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}: Remove deprecated inspect.getmoduleinfo function.

@item 
bpo-25578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25578}: Fix (another) memory leak in SSLSocket.getpeercer().

@item 
bpo-25530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25530}: Disable the vulnerable SSLv3 protocol by default when creating
ssl.SSLContext.

@item 
bpo-25569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25569}: Fix memory leak in SSLSocket.getpeercert().

@item 
bpo-25471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25471}: Sockets returned from accept() shouldn't appear to be
nonblocking.

@item 
bpo-25319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25319}: When threading.Event is reinitialized, the underlying condition
should use a regular lock rather than a recursive lock.

@item 
Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu
Davis.

@item 
bpo-26050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26050}: Add asyncio.StreamReader.readuntil() method. Patch by Марк
Коренберг.

@item 
bpo-25924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25924}: Avoid unnecessary serialization of getaddrinfo(3) calls on OS X
versions 10.5 or higher.  Original patch by A. Jesse Jiryu Davis.

@item 
bpo-26406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26406}: Avoid unnecessary serialization of getaddrinfo(3) calls on
current versions of OpenBSD and NetBSD.  Patch by A. Jesse Jiryu Davis.

@item 
bpo-26848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26848}: Fix asyncio/subprocess.communicate() to handle empty input.
Patch by Jack O'Connor.

@item 
bpo-27040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27040}: Add loop.get_exception_handler method

@item 
bpo-27041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27041}: asyncio: Add loop.create_future method
@end itemize

@node IDLE<56>,Documentation<67>,Library<78>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id678}@anchor{1ae7}
@subsubsection IDLE



@itemize -

@item 
bpo-20640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20640}: Add tests for idlelib.configHelpSourceEdit. Patch by Saimadhav
Heblikar.

@item 
In the 'IDLE-console differences' section of the IDLE doc, clarify how
running with IDLE affects sys.modules and the standard streams.

@item 
bpo-25507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25507}: fix incorrect change in IOBinding that prevented printing.
Augment IOBinding htest to include all major IOBinding functions.

@item 
bpo-25905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25905}: Revert unwanted conversion of ' to ’ RIGHT SINGLE QUOTATION
MARK in README.txt and open this and NEWS.txt with 'ascii'. Re-encode
CREDITS.txt to utf-8 and open it with 'utf-8'.

@item 
bpo-15348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15348}: Stop the debugger engine (normally in a user process) before
closing the debugger window (running in the IDLE process). This prevents
the RuntimeErrors that were being caught and ignored.

@item 
bpo-24455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24455}: Prevent IDLE from hanging when a) closing the shell while the
debugger is active (15347); b) closing the debugger with the [X] button
(15348); and c) activating the debugger when already active (24455). The
patch by Mark Roseman does this by making two changes. 1. Suspend and
resume the gui.interaction method with the tcl vwait mechanism intended
for this purpose (instead of root.mainloop & .quit). 2. In gui.run, allow
any existing interaction to terminate first.

@item 
Change 'The program' to 'Your program' in an IDLE 'kill program?' message
to make it clearer that the program referred to is the currently running
user program, not IDLE itself.

@item 
bpo-24750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24750}: Improve the appearance of the IDLE editor window status bar.
Patch by Mark Roseman.

@item 
bpo-25313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25313}: Change the handling of new built-in text color themes to better
address the compatibility problem introduced by the addition of IDLE Dark.
Consistently use the revised idleConf.CurrentTheme everywhere in idlelib.

@item 
bpo-24782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24782}: Extension configuration is now a tab in the IDLE Preferences
dialog rather than a separate dialog.  The former tabs are now a sorted
list.  Patch by Mark Roseman.

@item 
bpo-22726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22726}: Re-activate the config dialog help button with some content
about the other buttons and the new IDLE Dark theme.

@item 
bpo-24820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24820}: IDLE now has an 'IDLE Dark' built-in text color theme. It is
more or less IDLE Classic inverted, with a cobalt blue background.
Strings, comments, keywords, ... are still green, red, orange, ... . To
use it with IDLEs released before November 2015, hit the 'Save as New
Custom Theme' button and enter a new name, such as 'Custom Dark'.  The
custom theme will work with any IDLE release, and can be modified.

@item 
bpo-25224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25224}: README.txt is now an idlelib index for IDLE developers and
curious users. The previous user content is now in the IDLE doc chapter.
'IDLE' now means 'Integrated Development and Learning Environment'.

@item 
bpo-24820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24820}: Users can now set breakpoint colors in Settings -> Custom
Highlighting. Original patch by Mark Roseman.

@item 
bpo-24972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24972}: Inactive selection background now matches active selection
background, as configured by users, on all systems.  Found items are now
always highlighted on Windows.  Initial patch by Mark Roseman.

@item 
bpo-24570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24570}: Idle: make calltip and completion boxes appear on Macs affected
by a tk regression.  Initial patch by Mark Roseman.

@item 
bpo-24988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24988}: Idle ScrolledList context menus (used in debugger) now work on
Mac Aqua. Patch by Mark Roseman.

@item 
bpo-24801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24801}: Make right-click for context menu work on Mac Aqua. Patch by
Mark Roseman.

@item 
bpo-25173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25173}: Associate tkinter messageboxes with a specific widget. For Mac
OSX, make them a 'sheet'.  Patch by Mark Roseman.

@item 
bpo-25198@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25198}: Enhance the initial html viewer now used for Idle Help.
Properly indent fixed-pitch text (patch by Mark Roseman). Give code
snippet a very Sphinx-like light blueish-gray background. Re-use initial
width and height set by users for shell and editor. When the Table of
Contents (TOC) menu is used, put the section header at the top of the
screen.

@item 
bpo-25225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25225}: Condense and rewrite Idle doc section on text colors.

@item 
bpo-21995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21995}: Explain some differences between IDLE and console Python.

@item 
bpo-22820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22820}: Explain need for `print' when running file from Idle editor.

@item 
bpo-25224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25224}: Doc: augment Idle feature list and no-subprocess section.

@item 
bpo-25219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25219}: Update doc for Idle command line options. Some were missing and
notes were not correct.

@item 
bpo-24861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24861}: Most of idlelib is private and subject to change. Use
idleib.idle.* to start Idle. See idlelib.__init__.__doc__.

@item 
bpo-25199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25199}: Idle: add synchronization comments for future maintainers.

@item 
bpo-16893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16893}: Replace help.txt with help.html for Idle doc display. The new
idlelib/help.html is rstripped Doc/build/html/library/idle.html. It looks
better than help.txt and will better document Idle as released. The
tkinter html viewer that works for this file was written by Rose Roseman.
The now unused EditorWindow.HelpDialog class and helt.txt file are
deprecated.

@item 
bpo-24199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24199}: Deprecate unused idlelib.idlever with possible removal in 3.6.

@item 
bpo-24790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24790}: Remove extraneous code (which also create 2 & 3 conflicts).
@end itemize

@node Documentation<67>,Tests<71>,IDLE<56>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id679}@anchor{1ae8}
@subsubsection Documentation



@itemize -

@item 
bpo-26736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26736}: Used HTTPS for external links in the documentation if possible.

@item 
bpo-6953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6953}: Rework the Readline module documentation to group related
functions together, and add more details such as what underlying Readline
functions and variables are accessed.

@item 
bpo-23606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23606}: Adds note to ctypes documentation regarding cdll.msvcrt.

@item 
bpo-24952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24952}: Clarify the default size argument of stack_size() in the
"threading" and "_thread" modules. Patch from Mattip.

@item 
bpo-26014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26014}: Update 3.x packaging documentation: * "See also" links to the
new docs are now provided in the legacy pages * links to setuptools
documentation have been updated
@end itemize

@node Tests<71>,Build<77>,Documentation<67>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id680}@anchor{1ae9}
@subsubsection Tests



@itemize -

@item 
bpo-21916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21916}: Added tests for the turtle module.  Patch by ingrid, Gregory
Loyse and Jelle Zijlstra.

@item 
bpo-26295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26295}: When using "python3 -m test --testdir=TESTDIR", regrtest
doesn't add "test." prefix to test module names.

@item 
bpo-26523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26523}: The multiprocessing thread pool (multiprocessing.dummy.Pool)
was untested.

@item 
bpo-26015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26015}: Added new tests for pickling iterators of mutable sequences.

@item 
bpo-26325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26325}: Added test.support.check_no_resource_warning() to check that no
ResourceWarning is emitted.

@item 
bpo-25940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25940}: Changed test_ssl to use its internal local server more.  This
avoids relying on svn.python.org, which recently changed root certificate.

@item 
bpo-25616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25616}: Tests for OrderedDict are extracted from test_collections into
separate file test_ordered_dict.

@item 
bpo-25449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25449}: Added tests for OrderedDict subclasses.

@item 
bpo-25188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25188}: Add -P/--pgo to test.regrtest to suppress error output when
running the test suite for the purposes of a PGO build. Initial patch by
Alecsandru Patrascu.

@item 
bpo-22806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22806}: Add @code{python -m test --list-tests} command to list tests.

@item 
bpo-18174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18174}: @code{python -m test --huntrleaks ...} now also checks for leak of
file descriptors. Patch written by Richard Oudkerk.

@item 
bpo-25260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25260}: Fix @code{python -m test --coverage} on Windows. Remove the list
of ignored directories.

@item 
@code{PCbuild\rt.bat} now accepts an unlimited number of arguments to pass
along to regrtest.py.  Previously there was a limit of 9.

@item 
bpo-26583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26583}: Skip test_timestamp_overflow in test_import if bytecode files
cannot be written.
@end itemize

@node Build<77>,Windows<67>,Tests<71>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id681}@anchor{1aea}
@subsubsection Build



@itemize -

@item 
bpo-21277@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21277}: Don't try to link _ctypes with a ffi_convenience library.

@item 
bpo-26884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26884}: Fix linking extension modules for cross builds. Patch by Xavier
de Gaye.

@item 
bpo-26932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26932}: Fixed support of RTLD_* constants defined as enum values, not
via macros (in particular on Android).  Patch by Chi Hsuan Yen.

@item 
bpo-22359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22359}: Disable the rules for running _freeze_importlib and pgen when
cross-compiling.  The output of these programs is normally saved with the
source code anyway, and is still regenerated when doing a native build.
Patch by Xavier de Gaye.

@item 
bpo-21668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21668}: Link audioop, _datetime, _ctypes_test modules to libm, except
on Mac OS X. Patch written by Chi Hsuan Yen.

@item 
bpo-25702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25702}: A --with-lto configure option has been added that will enable
link time optimizations at build time during a make profile-opt. Some
compilers and toolchains are known to not produce stable code when using
LTO, be sure to test things thoroughly before relying on it. It can
provide a few % speed up over profile-opt alone.

@item 
bpo-26624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26624}: Adds validation of ucrtbase[d].dll version with warning for old
versions.

@item 
bpo-17603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17603}: Avoid error about nonexistent fileblocks.o file by using a
lower-level check for st_blocks in struct stat.

@item 
bpo-26079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26079}: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern
Thiel.

@item 
bpo-26465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26465}: Update Windows builds to use OpenSSL 1.0.2g.

@item 
bpo-25348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25348}: Added @code{--pgo} and @code{--pgo-job} arguments to
@code{PCbuild\build.bat} for building with Profile-Guided Optimization.  The
old @code{PCbuild\build_pgo.bat} script is removed.

@item 
bpo-25827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25827}: Add support for building with ICC to @code{configure}, including a
new @code{--with-icc} flag.

@item 
bpo-25696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25696}: Fix installation of Python on UNIX with make -j9.

@item 
bpo-24986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24986}: It is now possible to build Python on Windows without errors
when external libraries are not available.

@item 
bpo-24421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24421}: Compile Modules/_math.c once, before building extensions.
Previously it could fail to compile properly if the math and cmath builds
were concurrent.

@item 
bpo-26465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26465}: Update OS X 10.5+ 32-bit-only installer to build and link with
OpenSSL 1.0.2g.

@item 
bpo-26268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26268}: Update Windows builds to use OpenSSL 1.0.2f.

@item 
bpo-25136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25136}: Support Apple Xcode 7's new textual SDK stub libraries.

@item 
bpo-24324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24324}: Do not enable unreachable code warnings when using gcc as the
option does not work correctly in older versions of gcc and has been
silently removed as of gcc-4.5.
@end itemize

@node Windows<67>,Tools/Demos<42>,Build<77>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id682}@anchor{1aeb}
@subsubsection Windows



@itemize -

@item 
bpo-27053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27053}: Updates make_zip.py to correctly generate library ZIP file.

@item 
bpo-26268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26268}: Update the prepare_ssl.py script to handle OpenSSL releases
that don't include the contents of the include directory (that is, 1.0.2e
and later).

@item 
bpo-26071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26071}: bdist_wininst created binaries fail to start and find 32bit
Python

@item 
bpo-26073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26073}: Update the list of magic numbers in launcher

@item 
bpo-26065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26065}: Excludes venv from library when generating embeddable distro.

@item 
bpo-25022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25022}: Removed very outdated PC/example_nt/ directory.
@end itemize

@node Tools/Demos<42>,C API<67>,Windows<67>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id683}@anchor{1aec}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-26799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26799}: Fix python-gdb.py: don't get C types once when the Python code
is loaded, but get C types on demand. The C types can change if
python-gdb.py is loaded before the Python executable. Patch written by
Thomas Ilsche.

@item 
bpo-26271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26271}: Fix the Freeze tool to properly use flags passed through
configure. Patch by Daniel Shaulov.

@item 
bpo-26489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26489}: Add dictionary unpacking support to Tools/parser/unparse.py.
Patch by Guo Ci Teo.

@item 
bpo-26316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26316}: Fix variable name typo in Argument Clinic.

@item 
bpo-25440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25440}: Fix output of python-config --extension-suffix.

@item 
bpo-25154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25154}: The pyvenv script has been deprecated in favour of @code{python3 -m
venv}.
@end itemize

@node C API<67>,,Tools/Demos<42>,Python 3 6 0 alpha 1
@anchor{whatsnew/changelog id684}@anchor{1aed}
@subsubsection C API



@itemize -

@item 
bpo-26312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26312}: SystemError is now raised in all programming bugs with using
PyArg_ParseTupleAndKeywords().  RuntimeError did raised before in some
programming bugs.

@item 
bpo-26198@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26198}: ValueError is now raised instead of TypeError on buffer
overflow in parsing "es#" and "et#" format units.  SystemError is now
raised instead of TypeError on programmatical error in parsing format
string.
@end itemize

@node Python 3 5 5 final,Python 3 5 5 release candidate 1,Python 3 6 0 alpha 1,Changelog
@anchor{whatsnew/changelog python-3-5-5-final}@anchor{1aee}
@subsection Python 3.5.5 final


`Release date: 2018-02-04'

There were no new changes in version 3.5.5.

@node Python 3 5 5 release candidate 1,Python 3 5 4 final,Python 3 5 5 final,Changelog
@anchor{whatsnew/changelog python-3-5-5-release-candidate-1}@anchor{1aef}
@subsection Python 3.5.5 release candidate 1


`Release date: 2018-01-23'

@menu
* Security: Security<46>. 
* Core and Builtins: Core and Builtins<80>. 
* Library: Library<79>. 

@end menu

@node Security<46>,Core and Builtins<80>,,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id685}@anchor{1af0}
@subsubsection Security



@itemize -

@item 
bpo-32551@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32551}: The @code{sys.path[0]} initialization change for bpo-29139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29139} caused
a regression by revealing an inconsistency in how sys.path is initialized
when executing @code{__main__} from a zipfile, directory, or other import
location. This is considered a potential security issue, as it may lead to
privileged processes unexpectedly loading code from user controlled
directories in situations where that was not previously the case. The
interpreter now consistently avoids ever adding the import location's
parent directory to @code{sys.path}, and ensures no other @code{sys.path}
entries are inadvertently modified when inserting the import location
named on the command line. (Originally reported as bpo-29723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29723} against
Python 3.6rc1, but it was missed at the time that the then upcoming Python
3.5.4 release would also be affected)

@item 
bpo-30657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30657}: Fixed possible integer overflow in PyBytes_DecodeEscape,
@geindex Common Vulnerabilities and Exposures; CVE 2017-1000158
CVE 2017-1000158@footnote{https://www.cve.org/CVERecord?id=CVE-2017-1000158}. Original patch by Jay Bosamiya; rebased to Python 3
by Miro Hrončok.

@item 
bpo-30947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30947}: Upgrade libexpat embedded copy from version 2.2.1 to 2.2.3 to
get security fixes.
@end itemize

@node Core and Builtins<80>,Library<79>,Security<46>,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id686}@anchor{1af1}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-31095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31095}: Fix potential crash during GC caused by @code{tp_dealloc} which
doesn't call @code{PyObject_GC_UnTrack()}.
@end itemize

@node Library<79>,,Core and Builtins<80>,Python 3 5 5 release candidate 1
@anchor{whatsnew/changelog id687}@anchor{1af2}
@subsubsection Library



@itemize -

@item 
bpo-32072@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=32072}: Fixed issues with binary plists: Fixed saving bytearrays.
Identical objects will be saved only once. Equal references will be load
as identical objects. Added support for saving and loading recursive data
structures.

@item 
bpo-31170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=31170}: expat: Update libexpat from 2.2.3 to 2.2.4. Fix copying of
partial characters for UTF-8 input (libexpat bug 115):
@indicateurl{https://github.com/libexpat/libexpat/issues/115}
@end itemize

@node Python 3 5 4 final,Python 3 5 4 release candidate 1,Python 3 5 5 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-5-4-final}@anchor{1af3}
@subsection Python 3.5.4 final


`Release date: 2017-08-07'

@menu
* Library: Library<80>. 

@end menu

@node Library<80>,,,Python 3 5 4 final
@anchor{whatsnew/changelog id688}@anchor{1af4}
@subsubsection Library



@itemize -

@item 
bpo-30119@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30119}: ftplib.FTP.putline() now throws ValueError on commands that
contains CR or LF. Patch by Donghee Na.
@end itemize

@node Python 3 5 4 release candidate 1,Python 3 5 3 final,Python 3 5 4 final,Changelog
@anchor{whatsnew/changelog python-3-5-4-release-candidate-1}@anchor{1af5}
@subsection Python 3.5.4 release candidate 1


`Release date: 2017-07-23'

@menu
* Security: Security<47>. 
* Core and Builtins: Core and Builtins<81>. 
* Library: Library<81>. 
* Documentation: Documentation<68>. 
* Tests: Tests<72>. 
* Build: Build<78>. 
* Windows: Windows<68>. 
* C API: C API<68>. 

@end menu

@node Security<47>,Core and Builtins<81>,,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id689}@anchor{1af6}
@subsubsection Security



@itemize -

@item 
bpo-30730@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30730}: Prevent environment variables injection in subprocess on
Windows.  Prevent passing other environment variables and command
arguments.

@item 
bpo-30694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30694}: Upgrade expat copy from 2.2.0 to 2.2.1 to get fixes of multiple
security vulnerabilities including: 
@geindex Common Vulnerabilities and Exposures; CVE 2017-9233
CVE 2017-9233@footnote{https://www.cve.org/CVERecord?id=CVE-2017-9233} (External entity
infinite loop DoS), 
@geindex Common Vulnerabilities and Exposures; CVE 2016-9063
CVE 2016-9063@footnote{https://www.cve.org/CVERecord?id=CVE-2016-9063} (Integer overflow, re-fix),
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718} (Fix regression bugs from 2.2.0's fix to
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718}) and 
@geindex Common Vulnerabilities and Exposures; CVE 2012-0876
CVE 2012-0876@footnote{https://www.cve.org/CVERecord?id=CVE-2012-0876} (Counter hash flooding with
SipHash). Note: the 
@geindex Common Vulnerabilities and Exposures; CVE 2016-5300
CVE 2016-5300@footnote{https://www.cve.org/CVERecord?id=CVE-2016-5300} (Use os-specific entropy sources like
getrandom) doesn't impact Python, since Python already gets entropy from
the OS to set the expat secret using @code{XML_SetHashSalt()}.

@item 
bpo-30500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30500}: Fix urllib.parse.splithost() to correctly parse fragments. For
example, @code{splithost('//127.0.0.1#@@evil.com/')} now correctly returns the
@code{127.0.0.1} host, instead of treating @code{@@evil.com} as the host in an
authentication (@code{login@@host}).

@item 
bpo-29591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29591}: Update expat copy from 2.1.1 to 2.2.0 to get fixes of
@geindex Common Vulnerabilities and Exposures; CVE 2016-0718
CVE 2016-0718@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0718} and 
@geindex Common Vulnerabilities and Exposures; CVE 2016-4472
CVE 2016-4472@footnote{https://www.cve.org/CVERecord?id=CVE-2016-4472}. See
@indicateurl{https://sourceforge.net/p/expat/bugs/537/} for more information.
@end itemize

@node Core and Builtins<81>,Library<81>,Security<47>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id690}@anchor{1af7}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-30876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30876}: Relative import from unloaded package now reimports the package
instead of failing with SystemError.  Relative import from non-package now
fails with ImportError rather than SystemError.

@item 
bpo-30765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30765}: Avoid blocking in pthread_mutex_lock() when
PyThread_acquire_lock() is asked not to block.

@item 
bpo-27945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27945}: Fixed various segfaults with dict when input collections are
mutated during searching, inserting or comparing.  Based on patches by
Duane Griffin and Tim Mitchell.

@item 
bpo-25794@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25794}: Fixed type.__setattr__() and type.__delattr__() for
non-interned attribute names.  Based on patch by Eryk Sun.

@item 
bpo-29935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29935}: Fixed error messages in the index() method of tuple, list and
deque when pass indices of wrong type.

@item 
bpo-28876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28876}: @code{bool(range)} works even if @code{len(range)} raises
@ref{86d,,OverflowError}.

@item 
bpo-29600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29600}: Fix wrapping coroutine return values in StopIteration.

@item 
bpo-29537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29537}: Restore runtime compatibility with bytecode files generated by
CPython 3.5.0 to 3.5.2, and adjust the eval loop to avoid the problems
that could be caused by the malformed variant of the
BUILD_MAP_UNPACK_WITH_CALL opcode that they may contain. Patch by Petr
Viktorin, Serhiy Storchaka, and Nick Coghlan.

@item 
bpo-28598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28598}: Support __rmod__ for subclasses of str being called before
str.__mod__. Patch by Martijn Pieters.

@item 
bpo-29602@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29602}: Fix incorrect handling of signed zeros in complex constructor
for complex subclasses and for inputs having a __complex__ method. Patch
by Serhiy Storchaka.

@item 
bpo-29347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29347}: Fixed possibly dereferencing undefined pointers when creating
weakref objects.

@item 
bpo-29438@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29438}: Fixed use-after-free problem in key sharing dict.

@item 
bpo-29319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29319}: Prevent RunMainFromImporter overwriting sys.path[0].

@item 
bpo-29337@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29337}: Fixed possible BytesWarning when compare the code objects.
Warnings could be emitted at compile time.

@item 
bpo-29478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29478}: If max_line_length=None is specified while using the Compat32
policy, it is no longer ignored.  Patch by Mircea Cosbuc.
@end itemize

@node Library<81>,Documentation<68>,Core and Builtins<81>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id691}@anchor{1af8}
@subsubsection Library



@itemize -

@item 
bpo-29403@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29403}: Fix @code{unittest.mock}'s autospec to not fail on method-bound
builtin functions.  Patch by Aaron Gallagher.

@item 
bpo-30961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30961}: Fix decrementing a borrowed reference in tracemalloc.

@item 
bpo-30886@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30886}: Fix multiprocessing.Queue.join_thread(): it now waits until the
thread completes, even if the thread was started by the same process which
created the queue.

@item 
bpo-29854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29854}: Fix segfault in readline when using readline's history-size
option.  Patch by Nir Soffer.

@item 
bpo-30807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30807}: signal.setitimer() may disable the timer when passed a tiny
value. Tiny values (such as 1e-6) are valid non-zero values for
setitimer(), which is specified as taking microsecond-resolution
intervals. However, on some platform, our conversion routine could convert
1e-6 into a zero interval, therefore disabling the timer instead of
(re-)scheduling it.

@item 
bpo-30441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30441}: Fix bug when modifying os.environ while iterating over it

@item 
bpo-30532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30532}: Fix email header value parser dropping folding white space in
certain cases.

@item 
bpo-29169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29169}: Update zlib to 1.2.11.

@item 
bpo-30879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30879}: os.listdir() and os.scandir() now emit bytes names when called
with bytes-like argument.

@item 
bpo-30746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30746}: Prohibited the '=' character in environment variable names in
@code{os.putenv()} and @code{os.spawn*()}.

@item 
bpo-29755@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29755}: Fixed the lgettext() family of functions in the gettext module.
They now always return bytes.

@item 
bpo-30645@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30645}: Fix path calculation in imp.load_package(), fixing it for cases
when a package is only shipped with bytecodes. Patch by Alexandru
Ardelean.

@item 
bpo-23890@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23890}: unittest.TestCase.assertRaises() now manually breaks a
reference cycle to not keep objects alive longer than expected.

@item 
bpo-30149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30149}: inspect.signature() now supports callables with
variable-argument parameters wrapped with partialmethod. Patch by Donghee
Na.

@item 
bpo-29931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29931}: Fixed comparison check for ipaddress.ip_interface objects.
Patch by Sanjay Sundaresan.

@item 
bpo-24484@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24484}: Avoid race condition in multiprocessing cleanup.

@item 
bpo-28994@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28994}: The traceback no longer displayed for SystemExit raised in a
callback registered by atexit.

@item 
bpo-30508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30508}: Don't log exceptions if Task/Future "cancel()" method was
called.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Updates to typing module: Add generic AsyncContextManager, add
support for ContextManager on all versions. Original PRs by Jelle Zijlstra
and Ivan Levkivskyi

@item 
bpo-29870@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29870}: Fix ssl sockets leaks when connection is aborted in asyncio/ssl
implementation. Patch by Michaël Sghaïer.

@item 
bpo-29743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29743}: Closing transport during handshake process leaks open socket.
Patch by Nikolay Kim

@item 
bpo-27585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27585}: Fix waiter cancellation in asyncio.Lock. Patch by Mathieu
Sornay.

@item 
bpo-30418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30418}: On Windows, subprocess.Popen.communicate() now also ignore
EINVAL on stdin.write() if the child process is still running but closed
the pipe.

@item 
bpo-30378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30378}: Fix the problem that logging.handlers.SysLogHandler cannot
handle IPv6 addresses.

@item 
bpo-29960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29960}: Preserve generator state when _random.Random.setstate() raises
an exception. Patch by Bryan Olson.

@item 
bpo-30414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30414}: multiprocessing.Queue._feed background running thread do not
break from main loop on exception.

@item 
bpo-30003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30003}: Fix handling escape characters in HZ codec.  Based on patch by
Ma Lin.

@item 
bpo-30301@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30301}: Fix AttributeError when using SimpleQueue.empty() under `spawn'
and `forkserver' start methods.

@item 
bpo-30329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30329}: imaplib and poplib now catch the Windows socket WSAEINVAL error
(code 10022) on shutdown(SHUT_RDWR): An invalid operation was attempted.
This error occurs sometimes on SSL connections.

@item 
bpo-30375@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30375}: Warnings emitted when compile a regular expression now always
point to the line in the user code.  Previously they could point into
inners of the re module if emitted from inside of groups or conditionals.

@item 
bpo-30048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30048}: Fixed @code{Task.cancel()} can be ignored when the task is running
coroutine and the coroutine returned without any more @code{await}.

@item 
bpo-29990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29990}: Fix range checking in GB18030 decoder.  Original patch by Ma
Lin.

@item 
bpo-26293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26293}: Change resulted because of zipfile breakage. (See also:
bpo-29094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29094})

@item 
bpo-30243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30243}: Removed the __init__ methods of _json's scanner and encoder.
Misusing them could cause memory leaks or crashes.  Now scanner and
encoder objects are completely initialized in the __new__ methods.

@item 
bpo-30185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30185}: Avoid KeyboardInterrupt tracebacks in forkserver helper process
when Ctrl-C is received.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Various updates to typing module: add typing.NoReturn type, use
WrapperDescriptorType, minor bug-fixes.  Original PRs by Jim
Fasarakis-Hilliard and Ivan Levkivskyi.

@item 
bpo-30205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30205}: Fix getsockname() for unbound AF_UNIX sockets on Linux.

@item 
bpo-30070@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30070}: Fixed leaks and crashes in errors handling in the parser
module.

@item 
bpo-30061@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30061}: Fixed crashes in IOBase methods __next__() and readlines() when
readline() or __next__() respectively return non-sizeable object. Fixed
possible other errors caused by not checking results of PyObject_Size(),
PySequence_Size(), or PyMapping_Size().

@item 
bpo-30068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30068}: _io._IOBase.readlines will check if it's closed first when hint
is present.

@item 
bpo-29694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29694}: Fixed race condition in pathlib mkdir with flags parents=True.
Patch by Armin Rigo.

@item 
bpo-29692@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29692}: Fixed arbitrary unchaining of RuntimeError exceptions in
contextlib.contextmanager.  Patch by Siddharth Velankar.

@item 
bpo-29998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29998}: Pickling and copying ImportError now preserves name and path
attributes.

@item 
bpo-29942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29942}: Fix a crash in itertools.chain.from_iterable when encountering
long runs of empty iterables.

@item 
bpo-27863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27863}: Fixed multiple crashes in ElementTree caused by race conditions
and wrong types.

@item 
bpo-28699@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28699}: Fixed a bug in pools in multiprocessing.pool that raising an
exception at the very first of an iterable may swallow the exception or
make the program hang. Patch by Davin Potts and Xiang Zhang.

@item 
bpo-25803@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25803}: Avoid incorrect errors raised by Path.mkdir(exist_ok=True) when
the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-29861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29861}: Release references to tasks, their arguments and their results
as soon as they are finished in multiprocessing.Pool.

@item 
bpo-29884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29884}: faulthandler: Restore the old sigaltstack during teardown.
Patch by Christophe Zeitouny.

@item 
bpo-25455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25455}: Fixed crashes in repr of recursive buffered file-like objects.

@item 
bpo-29800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29800}: Fix crashes in partial.__repr__ if the keys of partial.keywords
are not strings.  Patch by Michael Seifert.

@item 
bpo-29742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29742}: get_extra_info() raises exception if get called on closed ssl
transport. Patch by Nikolay Kim.

@item 
bpo-8256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8256}: Fixed possible failing or crashing input() if attributes
"encoding" or "errors" of sys.stdin or sys.stdout are not set or are not
strings.

@item 
bpo-28298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28298}: Fix a bug that prevented array 'Q', 'L' and 'I' from accepting
big intables (objects that have __int__) as elements.  Patch by Oren
Milman.

@item 
bpo-29615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29615}: SimpleXMLRPCDispatcher no longer chains KeyError (or any other
exception) to exception(s) raised in the dispatched methods. Patch by Petr
Motejlek.

@item 
bpo-29704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29704}: asyncio.subprocess.SubprocessStreamProtocol no longer closes
before all pipes are closed.

@item 
bpo-29703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29703}: Fix asyncio to support instantiation of new event loops in
child processes.

@item 
bpo-29376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29376}: Fix assertion error in threading._DummyThread.is_alive().

@item 
bpo-29110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29110}: Fix file object leak in aifc.open() when file is given as a
filesystem path and is not in valid AIFF format. Patch by Anthony Zhang.

@item 
bpo-28961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28961}: Fix unittest.mock._Call helper: don't ignore the name parameter
anymore. Patch written by Jiajun Huang.

@item 
bpo-29532@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29532}: Altering a kwarg dictionary passed to functools.partial() no
longer affects a partial object after creation.

@item 
bpo-28556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28556}: Various updates to typing module: typing.Counter,
typing.ChainMap, improved ABC caching, etc. Original PRs by Jelle
Zijlstra, Ivan Levkivskyi, Manuel Krebber, and Łukasz Langa.

@item 
bpo-29100@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29100}: Fix datetime.fromtimestamp() regression introduced in Python
3.6.0: check minimum and maximum years.

@item 
bpo-29519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29519}: Fix weakref spewing exceptions during interpreter shutdown when
used with a rare combination of multiprocessing and custom codecs.

@item 
bpo-29416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29416}: Prevent infinite loop in pathlib.Path.mkdir

@item 
bpo-29444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29444}: Fixed out-of-bounds buffer access in the group() method of the
match object. Based on patch by WGH.

@item 
bpo-29335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29335}: Fix subprocess.Popen.wait() when the child process has exited
to a stopped instead of terminated state (ex: when under ptrace).

@item 
bpo-29290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29290}: Fix a regression in argparse that help messages would wrap at
non-breaking spaces.

@item 
bpo-28735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28735}: Fixed the comparison of mock.MagickMock with mock.ANY.

@item 
bpo-29011@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29011}: Fix an important omission by adding Deque to the typing module.

@item 
bpo-29219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29219}: Fixed infinite recursion in the repr of uninitialized
ctypes.CDLL instances.

@item 
bpo-28969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28969}: Fixed race condition in C implementation of
functools.lru_cache. KeyError could be raised when cached function with
full cache was simultaneously called from different threads with the same
uncached arguments.

@item 
bpo-29142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29142}: In urllib.request, suffixes in no_proxy environment variable
with leading dots could match related hostnames again (e.g. .b.c matches
a.b.c). Patch by Milan Oberkirch.
@end itemize

@node Documentation<68>,Tests<72>,Library<81>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id692}@anchor{1af9}
@subsubsection Documentation



@itemize -

@item 
bpo-30176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30176}: Add missing attribute related constants in curses
documentation.

@item 
bpo-26985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26985}: Add missing info of code object in inspect documentation.

@item 
bpo-28929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28929}: Link the documentation to its source file on GitHub.

@item 
bpo-25008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25008}: Document smtpd.py as effectively deprecated and add a pointer
to aiosmtpd, a third-party asyncio-based replacement.

@item 
bpo-26355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26355}: Add canonical header link on each page to corresponding major
version of the documentation. Patch by Matthias Bussonnier.

@item 
bpo-29349@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29349}: Fix Python 2 syntax in code for building the documentation.
@end itemize

@node Tests<72>,Build<78>,Documentation<68>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id693}@anchor{1afa}
@subsubsection Tests



@itemize -

@item 
bpo-30822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30822}: Fix regrtest command line parser to allow passing -u
extralargefile to run test_zipfile64.

@item 
bpo-30383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30383}: regrtest: Enhance regrtest and backport features from the
master branch. Add options: --coverage, --testdir, --list-tests (list test
files, don't run them), --list-cases (list test identifiers, don't run
them, bpo-30523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30523}), --matchfile (load a list of test filters from a
text file, bpo-30540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30540}), --slowest (alias to --slow). Enhance output:
add timestamp, test result, currently running tests, "Tests result: xxx"
summary with total duration, etc. Fix reference leak hunting in regrtest,
--huntrleaks: regrtest now warms up caches, create explicitly all internal
singletons which are created on demand to prevent false positives when
checking for reference leaks. (bpo-30675@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30675}).

@item 
bpo-30357@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30357}: test_thread: setUp() now uses support.threading_setup() and
support.threading_cleanup() to wait until threads complete to avoid random
side effects on following tests. Initial patch written by Grzegorz
Grzywacz.

@item 
bpo-28087@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28087}: Skip test_asyncore and test_eintr poll failures on macOS. Skip
some tests of select.poll when running on macOS due to unresolved issues
with the underlying system poll function on some macOS versions.

@item 
bpo-30197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30197}: Enhanced functions swap_attr() and swap_item() in the
test.support module. They now work when delete replaced attribute or item
inside the with statement.  The old value of the attribute or item (or
None if it doesn't exist) now will be assigned to the target of the "as"
clause, if there is one.

@item 
bpo-29571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29571}: to match the behaviour of the @code{re.LOCALE} flag,
test_re.test_locale_flag now uses @code{locale.getpreferredencoding(False)}
to determine the candidate encoding for the test regex (allowing it to
correctly skip the test when the default locale encoding is a multi-byte
encoding)
@end itemize

@node Build<78>,Windows<68>,Tests<72>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id694}@anchor{1afb}
@subsubsection Build



@itemize -

@item 
bpo-29243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29243}: Prevent unnecessary rebuilding of Python during @code{make test},
@code{make install} and some other make targets when configured with
@code{--enable-optimizations}.

@item 
bpo-23404@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23404}: Don't regenerate generated files based on file modification
time anymore: the action is now explicit. Replace @code{make touch} with
@code{make regen-all}.

@item 
bpo-29643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29643}: Fix @code{--enable-optimization} didn't work.
@end itemize

@node Windows<68>,C API<68>,Build<78>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id695}@anchor{1afc}
@subsubsection Windows



@itemize -

@item 
bpo-30687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=30687}: Locate msbuild.exe on Windows when building rather than
vcvarsall.bat

@item 
bpo-29392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29392}: Prevent crash when passing invalid arguments into msvcrt
module.
@end itemize

@node C API<68>,,Windows<68>,Python 3 5 4 release candidate 1
@anchor{whatsnew/changelog id696}@anchor{1afd}
@subsubsection C API



@itemize -

@item 
bpo-27867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27867}: Function PySlice_GetIndicesEx() is replaced with a macro if
Py_LIMITED_API is set to the value between 0x03050400 and 0x03060000 (not
including) or 0x03060100 or higher.

@item 
bpo-29083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29083}: Fixed the declaration of some public API functions.
PyArg_VaParse() and PyArg_VaParseTupleAndKeywords() were not available in
limited API. PyArg_ValidateKeywordArguments(), PyArg_UnpackTuple() and
Py_BuildValue() were not available in limited API of version < 3.3 when
PY_SSIZE_T_CLEAN is defined.
@end itemize

@node Python 3 5 3 final,Python 3 5 3 release candidate 1,Python 3 5 4 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-5-3-final}@anchor{1afe}
@subsection Python 3.5.3 final


`Release date: 2017-01-17'

There were no code changes between 3.5.3rc1 and 3.5.3 final.

@node Python 3 5 3 release candidate 1,Python 3 5 2 final,Python 3 5 3 final,Changelog
@anchor{whatsnew/changelog python-3-5-3-release-candidate-1}@anchor{1aff}
@subsection Python 3.5.3 release candidate 1


`Release date: 2017-01-02'

@menu
* Security: Security<48>. 
* Core and Builtins: Core and Builtins<82>. 
* Library: Library<82>. 
* IDLE: IDLE<57>. 
* C API: C API<69>. 
* Documentation: Documentation<69>. 
* Tests: Tests<73>. 
* Tools/Demos: Tools/Demos<43>. 
* Windows: Windows<69>. 
* Build: Build<79>. 

@end menu

@node Security<48>,Core and Builtins<82>,,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id697}@anchor{1b00}
@subsubsection Security



@itemize -

@item 
bpo-27278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27278}: Fix os.urandom() implementation using getrandom() on Linux.
Truncate size to INT_MAX and loop until we collected enough random bytes,
instead of casting a directly Py_ssize_t to int.

@item 
bpo-22636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22636}: Avoid shell injection problems with ctypes.util.find_library().
@end itemize

@node Core and Builtins<82>,Library<82>,Security<48>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id698}@anchor{1b01}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-29073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29073}: bytearray formatting no longer truncates on first null byte.

@item 
bpo-28932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28932}: Do not include <sys/random.h> if it does not exist.

@item 
bpo-28147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28147}: Fix a memory leak in split-table dictionaries: setattr() must
not convert combined table into split table.

@item 
bpo-25677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25677}: Correct the positioning of the syntax error caret for indented
blocks. Based on patch by Michael Layzell.

@item 
bpo-29000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29000}: Fixed bytes formatting of octals with zero padding in alternate
form.

@item 
bpo-28512@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28512}: Fixed setting the offset attribute of SyntaxError by
PyErr_SyntaxLocationEx() and PyErr_SyntaxLocationObject().

@item 
bpo-28991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28991}: functools.lru_cache() was susceptible to an obscure reentrancy
bug caused by a monkey-patched len() function.

@item 
bpo-28648@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28648}: Fixed crash in Py_DecodeLocale() in debug build on Mac OS X
when decode astral characters.  Patch by Xiang Zhang.

@item 
bpo-19398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19398}: Extra slash no longer added to sys.path components in case of
empty compile-time PYTHONPATH components.

@item 
bpo-28426@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28426}: Fixed potential crash in PyUnicode_AsDecodedObject() in debug
build.

@item 
bpo-23782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23782}: Fixed possible memory leak in _PyTraceback_Add() and exception
loss in PyTraceBack_Here().

@item 
bpo-28379@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28379}: Added sanity checks and tests for PyUnicode_CopyCharacters().
Patch by Xiang Zhang.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: The type of long range iterator is now registered as Iterator.
Patch by Oren Milman.

@item 
bpo-28376@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28376}: The constructor of range_iterator now checks that step is not
0. Patch by Oren Milman.

@item 
bpo-26906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26906}: Resolving special methods of uninitialized type now causes
implicit initialization of the type instead of a fail.

@item 
bpo-18287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18287}: PyType_Ready() now checks that tp_name is not NULL. Original
patch by Niklas Koep.

@item 
bpo-24098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24098}: Fixed possible crash when AST is changed in process of
compiling it.

@item 
bpo-28350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28350}: String constants with null character no longer interned.

@item 
bpo-26617@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26617}: Fix crash when GC runs during weakref callbacks.

@item 
bpo-27942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27942}: String constants now interned recursively in tuples and
frozensets.

@item 
bpo-21578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21578}: Fixed misleading error message when ImportError called with
invalid keyword args.

@item 
bpo-28203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28203}: Fix incorrect type in error message from @code{complex(1.0,
@{2:3@})}. Patch by Soumya Sharma.

@item 
bpo-27955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27955}: Fallback on reading /dev/urandom device when the getrandom()
syscall fails with EPERM, for example when blocked by SECCOMP.

@item 
bpo-28131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28131}: Fix a regression in zipimport's compile_source().  zipimport
should use the same optimization level as the interpreter.

@item 
bpo-25221@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25221}: Fix corrupted result from PyLong_FromLong(0) when Python is
compiled with NSMALLPOSINTS = 0.

@item 
bpo-25758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25758}: Prevents zipimport from unnecessarily encoding a filename
(patch by Eryk Sun)

@item 
bpo-28189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28189}: dictitems_contains no longer swallows compare errors. (Patch by
Xiang Zhang)

@item 
bpo-27812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27812}: Properly clear out a generator's frame's backreference to the
generator to prevent crashes in frame.clear().

@item 
bpo-27811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27811}: Fix a crash when a coroutine that has not been awaited is
finalized with warnings-as-errors enabled.

@item 
bpo-27587@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27587}: Fix another issue found by PVS-Studio: Null pointer check after
use of 'def' in _PyState_AddModule(). Initial patch by Christian Heimes.

@item 
bpo-26020@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26020}: set literal evaluation order did not match documented
behaviour.

@item 
bpo-27782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27782}: Multi-phase extension module import now correctly allows the
@code{m_methods} field to be used to add module level functions to instances
of non-module types returned from @code{Py_create_mod}. Patch by Xiang Zhang.

@item 
bpo-27936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27936}: The round() function accepted a second None argument for some
types but not for others.  Fixed the inconsistency by accepting None for
all numeric types.

@item 
bpo-27487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27487}: Warn if a submodule argument to "python -m" or
runpy.run_module() is found in sys.modules after parent packages are
imported, but before the submodule is executed.

@item 
bpo-27558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27558}: Fix a SystemError in the implementation of "raise" statement.
In a brand new thread, raise a RuntimeError since there is no active
exception to reraise. Patch written by Xiang Zhang.

@item 
bpo-27419@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27419}: Standard __import__() no longer look up "__import__" in globals
or builtins for importing submodules or "from import".  Fixed handling an
error of non-string package name.

@item 
bpo-27083@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27083}: Respect the PYTHONCASEOK environment variable under Windows.

@item 
bpo-27514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27514}: Make having too many statically nested blocks a SyntaxError
instead of SystemError.

@item 
bpo-27473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27473}: Fixed possible integer overflow in bytes and bytearray
concatenations. Patch by Xiang Zhang.

@item 
bpo-27507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27507}: Add integer overflow check in bytearray.extend().  Patch by
Xiang Zhang.

@item 
bpo-27581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27581}: Don't rely on wrapping for overflow check in
PySequence_Tuple().  Patch by Xiang Zhang.

@item 
bpo-27443@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27443}: __length_hint__() of bytearray iterators no longer return a
negative integer for a resized bytearray.

@item 
bpo-27942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27942}: Fix memory leak in codeobject.c
@end itemize

@node Library<82>,IDLE<57>,Core and Builtins<82>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id699}@anchor{1b02}
@subsubsection Library



@itemize -

@item 
bpo-15812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15812}: inspect.getframeinfo() now correctly shows the first line of a
context. Patch by Sam Breese.

@item 
bpo-29094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29094}: Offsets in a ZIP file created with extern file object and modes
"w" and "x" now are relative to the start of the file.

@item 
bpo-13051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13051}: Fixed recursion errors in large or resized
curses.textpad.Textbox.  Based on patch by Tycho Andersen.

@item 
bpo-29119@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29119}: Fix weakrefs in the pure python version of
collections.OrderedDict move_to_end() method. Contributed by Andra
Bogildea.

@item 
bpo-9770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9770}: curses.ascii predicates now work correctly with negative
integers.

@item 
bpo-28427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28427}: old keys should not remove new values from WeakValueDictionary
when collecting from another thread.

@item 
bpo-28923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28923}: Remove editor artifacts from Tix.py.

@item 
bpo-28871@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28871}: Fixed a crash when deallocate deep ElementTree.

@item 
bpo-19542@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19542}: Fix bugs in WeakValueDictionary.setdefault() and
WeakValueDictionary.pop() when a GC collection happens in another thread.

@item 
bpo-20191@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20191}: Fixed a crash in resource.prlimit() when pass a sequence that
doesn't own its elements as limits.

@item 
bpo-28779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28779}: multiprocessing.set_forkserver_preload() would crash the
forkserver process if a preloaded module instantiated some multiprocessing
objects such as locks.

@item 
bpo-28847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28847}: dbm.dumb now supports reading read-only files and no longer
writes the index file when it is not changed.

@item 
bpo-25659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25659}: In ctypes, prevent a crash calling the from_buffer() and
from_buffer_copy() methods on abstract classes like Array.

@item 
bpo-28732@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28732}: Fix crash in os.spawnv() with no elements in args

@item 
bpo-28485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28485}: Always raise ValueError for negative
compileall.compile_dir(workers=...) parameter, even when multithreading is
unavailable.

@item 
bpo-28387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28387}: Fixed possible crash in _io.TextIOWrapper deallocator when the
garbage collector is invoked in other thread.  Based on patch by Sebastian
Cufre.

@item 
bpo-27517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27517}: LZMA compressor and decompressor no longer raise exceptions if
given empty data twice.  Patch by Benjamin Fogle.

@item 
bpo-28549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28549}: Fixed segfault in curses's addch() with ncurses6.

@item 
bpo-28449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28449}: tarfile.open() with mode "r" or "r:" now tries to open a tar
file with compression before trying to open it without compression.
Otherwise it had 50% chance failed with ignore_zeros=True.

@item 
bpo-23262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23262}: The webbrowser module now supports Firefox 36+ and derived
browsers.  Based on patch by Oleg Broytman.

@item 
bpo-27939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27939}: Fixed bugs in tkinter.ttk.LabeledScale and tkinter.Scale caused
by representing the scale as float value internally in Tk.  tkinter.IntVar
now works if float value is set to underlying Tk variable.

@item 
bpo-28255@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28255}: calendar.TextCalendar().prmonth() no longer prints a space at
the start of new line after printing a month's calendar.  Patch by Xiang
Zhang.

@item 
bpo-20491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20491}: The textwrap.TextWrapper class now honors non-breaking spaces.
Based on patch by Kaarle Ritvanen.

@item 
bpo-28353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28353}: os.fwalk() no longer fails on broken links.

@item 
bpo-25464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25464}: Fixed HList.header_exists() in tkinter.tix module by addin a
workaround to Tix library bug.

@item 
bpo-28488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28488}: shutil.make_archive() no longer add entry "./" to ZIP archive.

@item 
bpo-24452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24452}: Make webbrowser support Chrome on Mac OS X.

@item 
bpo-20766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20766}: Fix references leaked by pdb in the handling of SIGINT
handlers.

@item 
bpo-26293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26293}: Fixed writing ZIP files that starts not from the start of the
file.  Offsets in ZIP file now are relative to the start of the archive in
conforming to the specification.

@item 
bpo-28321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28321}: Fixed writing non-BMP characters with binary format in
plistlib.

@item 
bpo-28322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28322}: Fixed possible crashes when unpickle itertools objects from
incorrect pickle data.  Based on patch by John Leitch.

@item 
Fix possible integer overflows and crashes in the mmap module with unusual
usage patterns.

@item 
bpo-1703178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1703178}: Fix the ability to pass the --link-objects option to the
distutils build_ext command.

@item 
bpo-28253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28253}: Fixed calendar functions for extreme months: 0001-01 and
9999-12. Methods itermonthdays() and itermonthdays2() are reimplemented so
that they don't call itermonthdates() which can cause datetime.date
under/overflow.

@item 
bpo-28275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28275}: Fixed possible use after free in the decompress() methods of
the LZMADecompressor and BZ2Decompressor classes. Original patch by John
Leitch.

@item 
bpo-27897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27897}: Fixed possible crash in sqlite3.Connection.create_collation()
if pass invalid string-like object as a name.  Patch by Xiang Zhang.

@item 
bpo-18893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18893}: Fix invalid exception handling in Lib/ctypes/macholib/dyld.py.
Patch by Madison May.

@item 
bpo-27611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27611}: Fixed support of default root window in the tkinter.tix module.

@item 
bpo-27348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27348}: In the traceback module, restore the formatting of exception
messages like "Exception: None".  This fixes a regression introduced in
3.5a2.

@item 
bpo-25651@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25651}: Allow false values to be used for msg parameter of subTest().

@item 
bpo-27932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27932}: Prevent memory leak in win32_ver().

@item 
Fix UnboundLocalError in socket._sendfile_use_sendfile.

@item 
bpo-28075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28075}: Check for ERROR_ACCESS_DENIED in Windows implementation of
os.stat().  Patch by Eryk Sun.

@item 
bpo-25270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25270}: Prevent codecs.escape_encode() from raising SystemError when an
empty bytestring is passed.

@item 
bpo-28181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28181}: Get antigravity over HTTPS. Patch by Kaartic Sivaraam.

@item 
bpo-25895@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25895}: Enable WebSocket URL schemes in urllib.parse.urljoin. Patch by
Gergely Imreh and Markus Holtermann.

@item 
bpo-27599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27599}: Fixed buffer overrun in binascii.b2a_qp() and
binascii.a2b_qp().

@item 
bpo-19003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19003}: m email.generator now replaces only @code{\r} and/or @code{\n} line
endings, per the RFC, instead of all unicode line endings.

@item 
bpo-28019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28019}: itertools.count() no longer rounds non-integer step in range
between 1.0 and 2.0 to 1.

@item 
bpo-25969@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25969}: Update the lib2to3 grammar to handle the unpacking
generalizations added in 3.5.

@item 
bpo-14977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14977}: mailcap now respects the order of the lines in the mailcap
files ("first match"), as required by RFC 1542.  Patch by Michael Lazar.

@item 
bpo-24594@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24594}: Validates persist parameter when opening MSI database

@item 
bpo-17582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17582}: xml.etree.ElementTree nows preserves whitespaces in attributes
(Patch by Duane Griffin.  Reviewed and approved by Stefan Behnel.)

@item 
bpo-28047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28047}: Fixed calculation of line length used for the base64 CTE in the
new email policies.

@item 
bpo-27445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27445}: Don't pass str(_charset) to MIMEText.set_payload(). Patch by
Claude Paroz.

@item 
bpo-22450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22450}: urllib now includes an @code{Accept: */*} header among the default
headers. This makes the results of REST API requests more consistent and
predictable especially when proxy servers are involved.

@item 
lib2to3.pgen3.driver.load_grammar() now creates a stable cache file
between runs given the same Grammar.txt input regardless of the hash
randomization setting.

@item 
bpo-27570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27570}: Avoid zero-length memcpy() etc calls with null source pointers
in the "ctypes" and "array" modules.

@item 
bpo-22233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22233}: Break email header lines `only' on the RFC specified CR and LF
characters, not on arbitrary unicode line breaks.  This also fixes a bug
in HTTP header parsing.

@item 
bpo-27988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27988}: Fix email iter_attachments incorrect mutation of payload list.

@item 
bpo-27691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27691}: Fix ssl module's parsing of GEN_RID subject alternative name
fields in X.509 certs.

@item 
bpo-27850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27850}: Remove 3DES from ssl module's default cipher list to counter
measure sweet32 attack (
@geindex Common Vulnerabilities and Exposures; CVE 2016-2183
CVE 2016-2183@footnote{https://www.cve.org/CVERecord?id=CVE-2016-2183}).

@item 
bpo-27766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27766}: Add ChaCha20 Poly1305 to ssl module's default cipher list.
(Required OpenSSL 1.1.0 or LibreSSL).

@item 
bpo-26470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26470}: Port ssl and hashlib module to OpenSSL 1.1.0.

@item 
Remove support for passing a file descriptor to os.access. It never worked
but previously didn't raise.

@item 
bpo-12885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12885}: Fix error when distutils encounters symlink.

@item 
bpo-27881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27881}: Fixed possible bugs when setting
sqlite3.Connection.isolation_level. Based on patch by Xiang Zhang.

@item 
bpo-27861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27861}: Fixed a crash in sqlite3.Connection.cursor() when a factory
creates not a cursor.  Patch by Xiang Zhang.

@item 
bpo-19884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19884}: Avoid spurious output on OS X with Gnu Readline.

@item 
bpo-27706@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27706}: Restore deterministic behavior of random.Random().seed() for
string seeds using seeding version 1.  Allows sequences of calls to
random() to exactly match those obtained in Python 2. Patch by Nofar
Schnider.

@item 
bpo-10513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10513}: Fix a regression in Connection.commit().  Statements should not
be reset after a commit.

@item 
A new version of typing.py from @indicateurl{https://github.com/python/typing}:
Collection (only for 3.6) (bpo-27598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27598}). Add FrozenSet to __all__
(upstream #261). Fix crash in _get_type_vars() (upstream #259). Remove the
dict constraint in ForwardRef._eval_type (upstream #252).

@item 
bpo-27539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27539}: Fix unnormalised @code{Fraction.__pow__} result in the case of
negative exponent and negative base.

@item 
bpo-21718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21718}: cursor.description is now available for queries using CTEs.

@item 
bpo-2466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2466}: posixpath.ismount now correctly recognizes mount points which
the user does not have permission to access.

@item 
bpo-27773@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27773}: Correct some memory management errors server_hostname in
_ssl.wrap_socket().

@item 
bpo-26750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26750}: unittest.mock.create_autospec() now works properly for
subclasses of property() and other data descriptors.

@item 
In the curses module, raise an error if window.getstr() or window.instr()
is passed a negative value.

@item 
bpo-27783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27783}: Fix possible usage of uninitialized memory in
operator.methodcaller.

@item 
bpo-27774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27774}: Fix possible Py_DECREF on unowned object in _sre.

@item 
bpo-27760@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27760}: Fix possible integer overflow in binascii.b2a_qp.

@item 
bpo-27758@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27758}: Fix possible integer overflow in the _csv module for large
record lengths.

@item 
bpo-27568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27568}: Prevent HTTPoxy attack (
@geindex Common Vulnerabilities and Exposures; CVE 2016-1000110
CVE 2016-1000110@footnote{https://www.cve.org/CVERecord?id=CVE-2016-1000110}). Ignore the
HTTP_PROXY variable when REQUEST_METHOD environment is set, which
indicates that the script is in CGI mode.

@item 
bpo-27656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27656}: Do not assume sched.h defines any SCHED_* constants.

@item 
bpo-27130@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27130}: In the "zlib" module, fix handling of large buffers (typically
4 GiB) when compressing and decompressing.  Previously, inputs were
limited to 4 GiB, and compression and decompression operations did not
properly handle results of 4 GiB.

@item 
bpo-27533@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27533}: Release GIL in nt._isdir

@item 
bpo-17711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17711}: Fixed unpickling by the persistent ID with protocol 0. Original
patch by Alexandre Vassalotti.

@item 
bpo-27522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27522}: Avoid an unintentional reference cycle in email.feedparser.

@item 
bpo-26844@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26844}: Fix error message for imp.find_module() to refer to 'path'
instead of 'name'. Patch by Lev Maximov.

@item 
bpo-23804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23804}: Fix SSL zero-length recv() calls to not block and not raise an
error about unclean EOF.

@item 
bpo-27466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27466}: Change time format returned by http.cookie.time2netscape,
confirming the netscape cookie format and making it consistent with
documentation.

@item 
bpo-26664@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26664}: Fix activate.fish by removing mis-use of @code{$}.

@item 
bpo-22115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22115}: Fixed tracing Tkinter variables: trace_vdelete() with wrong
mode no longer break tracing, trace_vinfo() now always returns a list of
pairs of strings, tracing in the "u" mode now works.

@item 
Fix a scoping issue in importlib.util.LazyLoader which triggered an
UnboundLocalError when lazy-loading a module that was already put into
sys.modules.

@item 
bpo-27079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27079}: Fixed curses.ascii functions isblank(), iscntrl() and
ispunct().

@item 
bpo-26754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26754}: Some functions (compile() etc) accepted a filename argument
encoded as an iterable of integers. Now only strings and byte-like objects
are accepted.

@item 
bpo-27048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27048}: Prevents distutils failing on Windows when environment
variables contain non-ASCII characters

@item 
bpo-27330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27330}: Fixed possible leaks in the ctypes module.

@item 
bpo-27238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27238}: Got rid of bare excepts in the turtle module.  Original patch
by Jelle Zijlstra.

@item 
bpo-27122@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27122}: When an exception is raised within the context being managed by
a contextlib.ExitStack() and one of the exit stack generators catches and
raises it in a chain, do not re-raise the original exception when exiting,
let the new chained one through.  This avoids the 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} bug described
in issue25782.

@item 
bpo-26386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26386}: Fixed ttk.TreeView selection operations with item id's
containing spaces.

@item 
bpo-16182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16182}: Fix various functions in the "readline" module to use the
locale encoding, and fix get_begidx() and get_endidx() to return code
point indexes.

@item 
bpo-27392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27392}: Add loop.connect_accepted_socket(). Patch by Jim Fulton.

@item 
bpo-27930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27930}: Improved behaviour of logging.handlers.QueueListener. Thanks to
Paulo Andrade and Petr Viktorin for the analysis and patch.

@item 
bpo-21201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21201}: Improves readability of multiprocessing error message.  Thanks
to Wojciech Walczak for patch.

@item 
bpo-27456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27456}: asyncio: Set TCP_NODELAY by default.

@item 
bpo-27906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27906}: Fix socket accept exhaustion during high TCP traffic. Patch by
Kevin Conway.

@item 
bpo-28174@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28174}: Handle when SO_REUSEPORT isn't properly supported. Patch by
Seth Michael Larson.

@item 
bpo-26654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26654}: Inspect functools.partial in asyncio.Handle.__repr__. Patch by
iceboy.

@item 
bpo-26909@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26909}: Fix slow pipes IO in asyncio. Patch by INADA Naoki.

@item 
bpo-28176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28176}: Fix callbacks race in asyncio.SelectorLoop.sock_connect.

@item 
bpo-27759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27759}: Fix selectors incorrectly retain invalid file descriptors.
Patch by Mark Williams.

@item 
bpo-28368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28368}: Refuse monitoring processes if the child watcher has no loop
attached. Patch by Vincent Michel.

@item 
bpo-28369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28369}: Raise RuntimeError when transport's FD is used with add_reader,
add_writer, etc.

@item 
bpo-28370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28370}: Speedup asyncio.StreamReader.readexactly. Patch by Коренберг
Марк.

@item 
bpo-28371@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28371}: Deprecate passing asyncio.Handles to run_in_executor.

@item 
bpo-28372@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28372}: Fix asyncio to support formatting of non-python coroutines.

@item 
bpo-28399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28399}: Remove UNIX socket from FS before binding. Patch by Коренберг
Марк.

@item 
bpo-27972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27972}: Prohibit Tasks to await on themselves.

@item 
bpo-26923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26923}: Fix asyncio.Gather to refuse being cancelled once all children
are done. Patch by Johannes Ebke.

@item 
bpo-26796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26796}: Don't configure the number of workers for default threadpool
executor. Initial patch by Hans Lawrenz.

@item 
bpo-28600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28600}: Optimize loop.call_soon().

@item 
bpo-28613@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28613}: Fix get_event_loop() return the current loop if called from
coroutines/callbacks.

@item 
bpo-28639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28639}: Fix inspect.isawaitable to always return bool Patch by Justin
Mayfield.

@item 
bpo-28652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28652}: Make loop methods reject socket kinds they do not support.

@item 
bpo-28653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28653}: Fix a refleak in functools.lru_cache.

@item 
bpo-28703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28703}: Fix asyncio.iscoroutinefunction to handle Mock objects.

@item 
bpo-24142@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24142}: Reading a corrupt config file left the parser in an invalid
state.  Original patch by Florian Höch.

@item 
bpo-28990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28990}: Fix SSL hanging if connection is closed before handshake
completed. (Patch by HoHo-Ho)
@end itemize

@node IDLE<57>,C API<69>,Library<82>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id700}@anchor{1b03}
@subsubsection IDLE



@itemize -

@item 
bpo-15308@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15308}: Add 'interrupt execution' (^C) to Shell menu. Patch by Roger
Serwy, updated by Bayard Randel.

@item 
bpo-27922@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27922}: Stop IDLE tests from 'flashing' gui widgets on the screen.

@item 
Add version to title of IDLE help window.

@item 
bpo-25564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25564}: In section on IDLE -- console differences, mention that using
exec means that __builtins__ is defined for each statement.

@item 
bpo-27714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27714}: text_textview and test_autocomplete now pass when re-run in the
same process.  This occurs when test_idle fails when run with the -w
option but without -jn.  Fix warning from test_config.

@item 
bpo-25507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25507}: IDLE no longer runs buggy code because of its tkinter imports.
Users must include the same imports required to run directly in Python.

@item 
bpo-27452@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27452}: add line counter and crc to IDLE configHandler test dump.

@item 
bpo-27365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27365}: Allow non-ascii chars in IDLE NEWS.txt, for contributor names.

@item 
bpo-27245@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27245}: IDLE: Cleanly delete custom themes and key bindings.
Previously, when IDLE was started from a console or by import, a cascade
of warnings was emitted. Patch by Serhiy Storchaka.
@end itemize

@node C API<69>,Documentation<69>,IDLE<57>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id701}@anchor{1b04}
@subsubsection C API



@itemize -

@item 
bpo-28808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28808}: PyUnicode_CompareWithASCIIString() now never raises exceptions.

@item 
bpo-26754@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26754}: PyUnicode_FSDecoder() accepted a filename argument encoded as
an iterable of integers. Now only strings and bytes-like objects are
accepted.
@end itemize

@node Documentation<69>,Tests<73>,C API<69>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id702}@anchor{1b05}
@subsubsection Documentation



@itemize -

@item 
bpo-28513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28513}: Documented command-line interface of zipfile.
@end itemize

@node Tests<73>,Tools/Demos<43>,Documentation<69>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id703}@anchor{1b06}
@subsubsection Tests



@itemize -

@item 
bpo-28950@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28950}: Disallow -j0 to be combined with -T/-l/-M in regrtest command
line arguments.

@item 
bpo-28666@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28666}: Now test.support.rmtree is able to remove unwritable or
unreadable directories.

@item 
bpo-23839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23839}: Various caches now are cleared before running every test file.

@item 
bpo-28409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28409}: regrtest: fix the parser of command line arguments.

@item 
bpo-27787@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27787}: Call gc.collect() before checking each test for "dangling
threads", since the dangling threads are weak references.

@item 
bpo-27369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27369}: In test_pyexpat, avoid testing an error message detail that
changed in Expat 2.2.0.
@end itemize

@node Tools/Demos<43>,Windows<69>,Tests<73>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id704}@anchor{1b07}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-27952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27952}: Get Tools/scripts/fixcid.py working with Python 3 and the
current "re" module, avoid invalid Python backslash escapes, and fix a bug
parsing escaped C quote signs.

@item 
bpo-27332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27332}: Fixed the type of the first argument of module-level functions
generated by Argument Clinic.  Patch by Petr Viktorin.

@item 
bpo-27418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27418}: Fixed Tools/importbench/importbench.py.
@end itemize

@node Windows<69>,Build<79>,Tools/Demos<43>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id705}@anchor{1b08}
@subsubsection Windows



@itemize -

@item 
bpo-28251@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28251}: Improvements to help manuals on Windows.

@item 
bpo-28110@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28110}: launcher.msi has different product codes between 32-bit and
64-bit

@item 
bpo-25144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25144}: Ensures TargetDir is set before continuing with custom install.

@item 
bpo-27469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27469}: Adds a shell extension to the launcher so that drag and drop
works correctly.

@item 
bpo-27309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27309}: Enabled proper Windows styles in python[w].exe manifest.
@end itemize

@node Build<79>,,Windows<69>,Python 3 5 3 release candidate 1
@anchor{whatsnew/changelog id706}@anchor{1b09}
@subsubsection Build



@itemize -

@item 
bpo-29080@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=29080}: Removes hard dependency on hg.exe from PCBuild/build.bat

@item 
bpo-23903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23903}: Added missed names to PC/python3.def.

@item 
bpo-10656@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10656}: Fix out-of-tree building on AIX.  Patch by Tristan Carel and
Michael Haubenwallner.

@item 
bpo-26359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26359}: Rename --with-optimiations to --enable-optimizations.

@item 
bpo-28444@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28444}: Fix missing extensions modules when cross compiling.

@item 
bpo-28248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28248}: Update Windows build and OS X installers to use OpenSSL 1.0.2j.

@item 
bpo-28258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28258}: Fixed build with Estonian locale (python-config and distclean
targets in Makefile).  Patch by Arfrever Frehtes Taifersar Arahesis.

@item 
bpo-26661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26661}: setup.py now detects system libffi with multiarch wrapper.

@item 
bpo-28066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28066}: Fix the logic that searches build directories for generated
include files when building outside the source tree.

@item 
bpo-15819@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15819}: Remove redundant include search directory option for building
outside the source tree.

@item 
bpo-27566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27566}: Fix clean target in freeze makefile (patch by Lisa Roach)

@item 
bpo-27705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27705}: Update message in validate_ucrtbase.py

@item 
bpo-27983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27983}: Cause lack of llvm-profdata tool when using clang as required
for PGO linking to be a configure time error rather than make time when
--with-optimizations is enabled.  Also improve our ability to find the
llvm-profdata tool on MacOS and some Linuxes.

@item 
bpo-26307@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26307}: The profile-opt build now applies PGO to the built-in modules.

@item 
bpo-26359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26359}: Add the --with-optimizations configure flag.

@item 
bpo-27713@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27713}: Suppress spurious build warnings when updating importlib's
bootstrap files. Patch by Xiang Zhang

@item 
bpo-25825@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25825}: Correct the references to Modules/python.exp and ld_so_aix,
which are required on AIX.  This updates references to an installation
path that was changed in 3.2a4, and undoes changed references to the build
tree that were made in 3.5.0a1.

@item 
bpo-27453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27453}: CPP invocation in configure must use CPPFLAGS. Patch by Chi
Hsuan Yen.

@item 
bpo-27641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27641}: The configure script now inserts comments into the makefile to
prevent the pgen and _freeze_importlib executables from being
cross-compiled.

@item 
bpo-26662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26662}: Set PYTHON_FOR_GEN in configure as the Python program to be
used for file generation during the build.

@item 
bpo-10910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10910}: Avoid C++ compilation errors on FreeBSD and OS X. Also update
FreedBSD version checks for the original ctype UTF-8 workaround.

@item 
bpo-28676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28676}: Prevent missing 'getentropy' declaration warning on macOS.
Patch by Gareth Rees.
@end itemize

@node Python 3 5 2 final,Python 3 5 2 release candidate 1,Python 3 5 3 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-5-2-final}@anchor{1b0a}
@subsection Python 3.5.2 final


`Release date: 2016-06-26'

@menu
* Core and Builtins: Core and Builtins<83>. 
* Tests: Tests<74>. 
* IDLE: IDLE<58>. 

@end menu

@node Core and Builtins<83>,Tests<74>,,Python 3 5 2 final
@anchor{whatsnew/changelog id707}@anchor{1b0b}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-26930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26930}: Update Windows builds to use OpenSSL 1.0.2h.
@end itemize

@node Tests<74>,IDLE<58>,Core and Builtins<83>,Python 3 5 2 final
@anchor{whatsnew/changelog id708}@anchor{1b0c}
@subsubsection Tests



@itemize -

@item 
bpo-26867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26867}: Ubuntu's openssl OP_NO_SSLv3 is forced on by default; fix test.
@end itemize

@node IDLE<58>,,Tests<74>,Python 3 5 2 final
@anchor{whatsnew/changelog id709}@anchor{1b0d}
@subsubsection IDLE



@itemize -

@item 
bpo-27365@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27365}: Allow non-ascii in idlelib/NEWS.txt - minimal part for 3.5.2.
@end itemize

@node Python 3 5 2 release candidate 1,Python 3 5 1 final,Python 3 5 2 final,Changelog
@anchor{whatsnew/changelog python-3-5-2-release-candidate-1}@anchor{1b0e}
@subsection Python 3.5.2 release candidate 1


`Release date: 2016-06-12'

@menu
* Security: Security<49>. 
* Core and Builtins: Core and Builtins<84>. 
* Library: Library<83>. 
* IDLE: IDLE<59>. 
* Documentation: Documentation<70>. 
* Tests: Tests<75>. 
* Build: Build<80>. 
* Windows: Windows<70>. 
* Tools/Demos: Tools/Demos<44>. 

@end menu

@node Security<49>,Core and Builtins<84>,,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id710}@anchor{1b0f}
@subsubsection Security



@itemize -

@item 
bpo-26556@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26556}: Update expat to 2.1.1, fixes 
@geindex Common Vulnerabilities and Exposures; CVE 2015-1283
CVE 2015-1283@footnote{https://www.cve.org/CVERecord?id=CVE-2015-1283}.

@item 
Fix TLS stripping vulnerability in smtplib, 
@geindex Common Vulnerabilities and Exposures; CVE 2016-0772
CVE 2016-0772@footnote{https://www.cve.org/CVERecord?id=CVE-2016-0772}. Reported by
Team Oststrom.

@item 
bpo-26839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26839}: On Linux, @ref{50c,,os.urandom()} now calls @code{getrandom()} with
@code{GRND_NONBLOCK} to fall back on reading @code{/dev/urandom} if the urandom
entropy pool is not initialized yet. Patch written by Colm Buckley.

@item 
bpo-26657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26657}: Fix directory traversal vulnerability with http.server on
Windows.  This fixes a regression that was introduced in 3.3.4rc1 and
3.4.0rc1.  Based on patch by Philipp Hagemeister.

@item 
bpo-26313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26313}: ssl.py _load_windows_store_certs fails if windows cert store is
empty. Patch by Baji.

@item 
bpo-25939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25939}: On Windows open the cert store readonly in
ssl.enum_certificates.
@end itemize

@node Core and Builtins<84>,Library<83>,Security<49>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id711}@anchor{1b10}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-27066@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27066}: Fixed SystemError if a custom opener (for open()) returns a
negative number without setting an exception.

@item 
bpo-20041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20041}: Fixed TypeError when frame.f_trace is set to None. Patch by
Xavier de Gaye.

@item 
bpo-26168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26168}: Fixed possible refleaks in failing Py_BuildValue() with the "N"
format unit.

@item 
bpo-26991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26991}: Fix possible refleak when creating a function with annotations.

@item 
bpo-27039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27039}: Fixed bytearray.remove() for values greater than 127.  Patch by
Joe Jevnik.

@item 
bpo-23640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23640}: int.from_bytes() no longer bypasses constructors for
subclasses.

@item 
bpo-26811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26811}: gc.get_objects() no longer contains a broken tuple with NULL
pointer.

@item 
bpo-20120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20120}: Use RawConfigParser for .pypirc parsing, removing support for
interpolation unintentionally added with move to Python 3. Behavior no
longer does any interpolation in .pypirc files, matching behavior in
Python 2.7 and Setuptools 19.0.

@item 
bpo-26659@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26659}: Make the builtin slice type support cycle collection.

@item 
bpo-26718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26718}: super.__init__ no longer leaks memory if called multiple times.
NOTE: A direct call of super.__init__ is not endorsed!

@item 
bpo-25339@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25339}: PYTHONIOENCODING now has priority over locale in setting the
error handler for stdin and stdout.

@item 
bpo-26494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26494}: Fixed crash on iterating exhausting iterators. Affected classes
are generic sequence iterators, iterators of str, bytes, bytearray, list,
tuple, set, frozenset, dict, OrderedDict, corresponding views and
os.scandir() iterator.

@item 
bpo-26581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26581}: If coding cookie is specified multiple times on a line in
Python source code file, only the first one is taken to account.

@item 
bpo-26464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26464}: Fix str.translate() when string is ASCII and first replacements
removes character, but next replacement uses a non-ASCII character or a
string longer than 1 character. Regression introduced in Python 3.5.0.

@item 
bpo-22836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22836}: Ensure exception reports from PyErr_Display() and
PyErr_WriteUnraisable() are sensible even when formatting them produces
secondary errors.  This affects the reports produced by
sys.__excepthook__() and when __del__() raises an exception.

@item 
bpo-26302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26302}: Correct behavior to reject comma as a legal character for
cookie names.

@item 
bpo-4806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4806}: Avoid masking the original TypeError exception when using star
(@code{*}) unpacking in function calls.  Based on patch by Hagen Fürstenau
and Daniel Urban.

@item 
bpo-27138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27138}: Fix the doc comment for FileFinder.find_spec().

@item 
bpo-26154@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26154}: Add a new private _PyThreadState_UncheckedGet() function to get
the current Python thread state, but don't issue a fatal error if it is
NULL. This new function must be used instead of accessing directly the
_PyThreadState_Current variable.  The variable is no more exposed since
Python 3.5.1 to hide the exact implementation of atomic C types, to avoid
compiler issues.

@item 
bpo-26194@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26194}: Deque.insert() gave odd results for bounded deques that had
reached their maximum size.  Now an IndexError will be raised when
attempting to insert into a full deque.

@item 
bpo-25843@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25843}: When compiling code, don't merge constants if they are equal
but have a different types. For example, @code{f1, f2 = lambda: 1, lambda:
1.0} is now correctly compiled to two different functions: @code{f1()}
returns @code{1} (@code{int}) and @code{f2()} returns @code{1.0} (@code{int}), even if
@code{1} and @code{1.0} are equal.

@item 
bpo-22995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22995}: [UPDATE] Comment out the one of the pickleability tests in
_PyObject_GetState() due to regressions observed in Cython-based projects.

@item 
bpo-25961@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25961}: Disallowed null characters in the type name.

@item 
bpo-25973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25973}: Fix segfault when an invalid nonlocal statement binds a name
starting with two underscores.

@item 
bpo-22995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22995}: Instances of extension types with a state that aren't
subclasses of list or dict and haven't implemented any pickle-related
methods (__reduce__, __reduce_ex__, __getnewargs__, __getnewargs_ex__, or
__getstate__), can no longer be pickled.  Including memoryview.

@item 
bpo-20440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20440}: Massive replacing unsafe attribute setting code with special
macro Py_SETREF.

@item 
bpo-25766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25766}: Special method __bytes__() now works in str subclasses.

@item 
bpo-25421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25421}: __sizeof__ methods of builtin types now use dynamic basic size.
This allows sys.getsize() to work correctly with their subclasses with
__slots__ defined.

@item 
bpo-25709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25709}: Fixed problem with in-place string concatenation and utf-8
cache.

@item 
bpo-27147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27147}: Mention 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} in the importlib docs.

@item 
bpo-24097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24097}: Fixed crash in object.__reduce__() if slot name is freed inside
__getattr__.

@item 
bpo-24731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24731}: Fixed crash on converting objects with special methods
__bytes__, __trunc__, and __float__ returning instances of subclasses of
bytes, int, and float to subclasses of bytes, int, and float
correspondingly.

@item 
bpo-26478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26478}: Fix semantic bugs when using binary operators with dictionary
views and tuples.

@item 
bpo-26171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26171}: Fix possible integer overflow and heap corruption in
zipimporter.get_data().

@item 
bpo-25660@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25660}: Fix TAB key behaviour in REPL with readline.

@item 
bpo-25887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25887}: Raise a RuntimeError when a coroutine object is awaited more
than once.

@item 
bpo-27243@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27243}: Update the __aiter__ protocol: instead of returning an
awaitable that resolves to an asynchronous iterator, the asynchronous
iterator should be returned directly.  Doing the former will trigger a
PendingDeprecationWarning.
@end itemize

@node Library<83>,IDLE<59>,Core and Builtins<84>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id712}@anchor{1b11}
@subsubsection Library



@itemize -

@item 
bpo-21386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21386}: Implement missing IPv4Address.is_global property.  It was
documented since 07a5610bae9d.  Initial patch by Roger Luethi.

@item 
bpo-20900@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20900}: distutils register command now decodes HTTP responses
correctly.  Initial patch by ingrid.

@item 
A new version of typing.py provides several new classes and features:
@@overload outside stubs, Reversible, DefaultDict, Text, ContextManager,
Type[], NewType(), TYPE_CHECKING, and numerous bug fixes (note that some
of the new features are not yet implemented in mypy or other static
analyzers). Also classes for 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} (Awaitable, AsyncIterable,
AsyncIterator) have been added (in fact they made it into 3.5.1 but were
never mentioned).

@item 
bpo-25738@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25738}: Stop http.server.BaseHTTPRequestHandler.send_error() from
sending a message body for 205 Reset Content.  Also, don't send Content
header fields in responses that don't have a body.  Patch by Susumu
Koshiba.

@item 
bpo-21313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21313}: Fix the "platform" module to tolerate when sys.version contains
truncated build information.

@item 
bpo-27164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27164}: In the zlib module, allow decompressing raw Deflate streams
with a predefined zdict.  Based on patch by Xiang Zhang.

@item 
bpo-24291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24291}: Fix wsgiref.simple_server.WSGIRequestHandler to completely
write data to the client.  Previously it could do partial writes and
truncate data.  Also, wsgiref.handler.ServerHandler can now handle stdout
doing partial writes, but this is deprecated.

@item 
bpo-26809@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26809}: Add @code{__all__} to @ref{d2,,string}.  Patch by Emanuel Barry.

@item 
bpo-26373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26373}: subprocess.Popen.communicate now correctly ignores
BrokenPipeError when the child process dies before .communicate() is
called in more/all circumstances.

@item 
bpo-21776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21776}: distutils.upload now correctly handles HTTPError. Initial patch
by Claudiu Popa.

@item 
bpo-27114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27114}: Fix SSLContext._load_windows_store_certs fails with
PermissionError

@item 
bpo-18383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18383}: Avoid creating duplicate filters when using filterwarnings and
simplefilter. Based on patch by Alex Shkop.

@item 
bpo-27057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27057}: Fix os.set_inheritable() on Android, ioctl() is blocked by
SELinux and fails with EACCESS. The function now falls back to fcntl().
Patch written by Michał Bednarski.

@item 
bpo-27014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27014}: Fix infinite recursion using typing.py.  Thanks to Kalle Tuure!

@item 
bpo-14132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14132}: Fix urllib.request redirect handling when the target only has a
query string.  Original fix by Ján Janech.

@item 
bpo-17214@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17214}: The "urllib.request" module now percent-encodes non-ASCII bytes
found in redirect target URLs.  Some servers send Location header fields
with non-ASCII bytes, but "http.client" requires the request target to be
ASCII-encodable, otherwise a UnicodeEncodeError is raised.  Based on patch
by Christian Heimes.

@item 
bpo-26892@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26892}: Honor debuglevel flag in urllib.request.HTTPHandler. Patch
contributed by Chi Hsuan Yen.

@item 
bpo-22274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22274}: In the subprocess module, allow stderr to be redirected to
stdout even when stdout is not redirected.  Patch by Akira Li.

@item 
bpo-26807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26807}: mock_open 'files' no longer error on readline at end of file.
Patch from Yolanda Robla.

@item 
bpo-25745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25745}: Fixed leaking a userptr in curses panel destructor.

@item 
bpo-26977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26977}: Removed unnecessary, and ignored, call to sum of squares helper
in statistics.pvariance.

@item 
bpo-26881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26881}: The modulefinder module now supports extended opcode arguments.

@item 
bpo-23815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23815}: Fixed crashes related to directly created instances of types in
_tkinter and curses.panel modules.

@item 
bpo-17765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17765}: weakref.ref() no longer silently ignores keyword arguments.
Patch by Georg Brandl.

@item 
bpo-26873@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26873}: xmlrpc now raises ResponseError on unsupported type tags
instead of silently return incorrect result.

@item 
bpo-26711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26711}: Fixed the comparison of plistlib.Data with other types.

@item 
bpo-24114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24114}: Fix an uninitialized variable in @code{ctypes.util}. The bug only
occurs on SunOS when the ctypes implementation searches for the @code{crle}
program. Patch by Xiang Zhang.  Tested on SunOS by Kees Bos.

@item 
bpo-26864@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26864}: In urllib.request, change the proxy bypass host checking
against no_proxy to be case-insensitive, and to not match unrelated host
names that happen to have a bypassed hostname as a suffix.  Patch by Xiang
Zhang.

@item 
bpo-26634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26634}: recursive_repr() now sets __qualname__ of wrapper.  Patch by
Xiang Zhang.

@item 
bpo-26804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26804}: urllib.request will prefer lower_case proxy environment
variables over UPPER_CASE or Mixed_Case ones. Patch contributed by
Hans-Peter Jansen.

@item 
bpo-26837@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26837}: assertSequenceEqual() now correctly outputs non-stringified
differing items (like bytes in the -b mode).  This affects
assertListEqual() and assertTupleEqual().

@item 
bpo-26041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26041}: Remove "will be removed in Python 3.7" from deprecation
messages of platform.dist() and platform.linux_distribution(). Patch by
Kumaripaba Miyurusara Athukorala.

@item 
bpo-26822@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26822}: itemgetter, attrgetter and methodcaller objects no longer
silently ignore keyword arguments.

@item 
bpo-26733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26733}: Disassembling a class now disassembles class and static
methods. Patch by Xiang Zhang.

@item 
bpo-26801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26801}: Fix error handling in @ref{10e3,,shutil.get_terminal_size()}, catch
@ref{343,,AttributeError} instead of @ref{428,,NameError}. Patch written by
Emanuel Barry.

@item 
bpo-24838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24838}: tarfile's ustar and gnu formats now correctly calculate name
and link field limits for multibyte character encodings like utf-8.

@item 
bpo-26717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26717}: Stop encoding Latin-1-ized WSGI paths with UTF-8.  Patch by
Anthony Sottile.

@item 
bpo-26735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26735}: Fix @ref{50c,,os.urandom()} on Solaris 11.3 and newer when reading
more than 1,024 bytes: call @code{getrandom()} multiple times with a limit of
1024 bytes per call.

@item 
bpo-16329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16329}: Add .webm to mimetypes.types_map.  Patch by Giampaolo Rodola'.

@item 
bpo-13952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13952}: Add .csv to mimetypes.types_map.  Patch by Geoff Wilson.

@item 
bpo-26709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26709}: Fixed Y2038 problem in loading binary PLists.

@item 
bpo-23735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23735}: Handle terminal resizing with Readline 6.3+ by installing our
own SIGWINCH handler.  Patch by Eric Price.

@item 
bpo-26586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26586}: In http.server, respond with "413 Request header fields too
large" if there are too many header fields to parse, rather than killing
the connection and raising an unhandled exception.  Patch by Xiang Zhang.

@item 
bpo-22854@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22854}: Change BufferedReader.writable() and BufferedWriter.readable()
to always return False.

@item 
bpo-25195@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25195}: Fix a regression in mock.MagicMock. _Call is a subclass of
tuple (changeset 3603bae63c13 only works for classes) so we need to
implement __ne__ ourselves.  Patch by Andrew Plummer.

@item 
bpo-26644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26644}: Raise ValueError rather than SystemError when a negative length
is passed to SSLSocket.recv() or read().

@item 
bpo-23804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23804}: Fix SSL recv(0) and read(0) methods to return zero bytes
instead of up to 1024.

@item 
bpo-26616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26616}: Fixed a bug in datetime.astimezone() method.

@item 
bpo-21925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21925}: @ref{19a3,,warnings.formatwarning()} now catches exceptions on
@code{linecache.getline(...)} to be able to log @ref{241,,ResourceWarning}
emitted late during the Python shutdown process.

@item 
bpo-24266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24266}: Ctrl+C during Readline history search now cancels the search
mode when compiled with Readline 7.

@item 
bpo-26560@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26560}: Avoid potential ValueError in BaseHandler.start_response.
Initial patch by Peter Inglesby.

@item 
bpo-26569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26569}: Fix @ref{815,,pyclbr.readmodule()} and @ref{816,,pyclbr.readmodule_ex()}
to support importing packages.

@item 
bpo-26499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26499}: Account for remaining Content-Length in HTTPResponse.readline()
and read1(). Based on patch by Silent Ghost. Also document that
HTTPResponse now supports these methods.

@item 
bpo-25320@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25320}: Handle sockets in directories unittest discovery is scanning.
Patch from Victor van den Elzen.

@item 
bpo-16181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16181}: cookiejar.http2time() now returns None if year is higher than
datetime.MAXYEAR.

@item 
bpo-26513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26513}: Fixes platform module detection of Windows Server

@item 
bpo-23718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23718}: Fixed parsing time in week 0 before Jan 1.  Original patch by
Tamás Bence Gedai.

@item 
bpo-20589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20589}: Invoking Path.owner() and Path.group() on Windows now raise
NotImplementedError instead of ImportError.

@item 
bpo-26177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26177}: Fixed the keys() method for Canvas and Scrollbar widgets.

@item 
bpo-15068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15068}: Got rid of excessive buffering in the fileinput module. The
bufsize parameter is no longer used.

@item 
bpo-2202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2202}: Fix UnboundLocalError in
AbstractDigestAuthHandler.get_algorithm_impls. Initial patch by Mathieu
Dupuy.

@item 
bpo-25718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25718}: Fixed pickling and copying the accumulate() iterator with total
is None.

@item 
bpo-26475@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26475}: Fixed debugging output for regular expressions with the (?x)
flag.

@item 
bpo-26457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26457}: Fixed the subnets() methods in IP network classes for the case
when resulting prefix length is equal to maximal prefix length. Based on
patch by Xiang Zhang.

@item 
bpo-26385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26385}: Remove the file if the internal open() call in
NamedTemporaryFile() fails. Patch by Silent Ghost.

@item 
bpo-26402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26402}: Fix XML-RPC client to retry when the server shuts down a
persistent connection.  This was a regression related to the new
http.client.RemoteDisconnected exception in 3.5.0a4.

@item 
bpo-25913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25913}: Leading @code{<~} is optional now in base64.a85decode() with
adobe=True.  Patch by Swati Jaiswal.

@item 
bpo-26186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26186}: Remove an invalid type check in importlib.util.LazyLoader.

@item 
bpo-26367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26367}: importlib.__import__() raises SystemError like
builtins.__import__() when @code{level} is specified but without an
accompanying package specified.

@item 
bpo-26309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26309}: In the "socketserver" module, shut down the request (closing
the connected socket) when verify_request() returns false.  Patch by Aviv
Palivoda.

@item 
bpo-25995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25995}: os.walk() no longer uses FDs proportional to the tree depth.

@item 
bpo-26117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26117}: The os.scandir() iterator now closes file descriptor not only
when the iteration is finished, but when it was failed with error.

@item 
bpo-25911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25911}: Restored support of bytes paths in os.walk() on Windows.

@item 
bpo-26045@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26045}: Add UTF-8 suggestion to error message when posting a
non-Latin-1 string with http.client.

@item 
bpo-12923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12923}: Reset FancyURLopener's redirect counter even if there is an
exception. Based on patches by Brian Brazil and Daniel Rocco.

@item 
bpo-25945@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25945}: Fixed a crash when unpickle the functools.partial object with
wrong state. Fixed a leak in failed functools.partial constructor. "args"
and "keywords" attributes of functools.partial have now always types tuple
and dict correspondingly.

@item 
bpo-26202@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26202}: copy.deepcopy() now correctly copies range() objects with
non-atomic attributes.

@item 
bpo-23076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23076}: Path.glob() now raises a ValueError if it's called with an
invalid pattern. Patch by Thomas Nyberg.

@item 
bpo-19883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19883}: Fixed possible integer overflows in zipimport.

@item 
bpo-26227@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26227}: On Windows, getnameinfo(), gethostbyaddr() and
gethostbyname_ex() functions of the socket module now decode the hostname
from the ANSI code page rather than UTF-8.

@item 
bpo-26147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26147}: xmlrpc now works with strings not encodable with used non-UTF-8
encoding.

@item 
bpo-25935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25935}: Garbage collector now breaks reference loops with OrderedDict.

@item 
bpo-16620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16620}: Fixed AttributeError in msilib.Directory.glob().

@item 
bpo-26013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26013}: Added compatibility with broken protocol 2 pickles created in
old Python 3 versions (3.4.3 and lower).

@item 
bpo-25850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25850}: Use cross-compilation by default for 64-bit Windows.

@item 
bpo-17633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17633}: Improve zipimport's support for namespace packages.

@item 
bpo-24705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24705}: Fix sysconfig._parse_makefile not expanding $@{@} vars appearing
before $() vars.

@item 
bpo-22138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22138}: Fix mock.patch behavior when patching descriptors. Restore
original values after patching. Patch contributed by Sean McCully.

@item 
bpo-25672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25672}: In the ssl module, enable the SSL_MODE_RELEASE_BUFFERS mode
option if it is safe to do so.

@item 
bpo-26012@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26012}: Don't traverse into symlinks for @code{**} pattern in
pathlib.Path.[r]glob().

@item 
bpo-24120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24120}: Ignore PermissionError when traversing a tree with
pathlib.Path.[r]glob(). Patch by Ulrich Petri.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: fileinput now uses sys.stdin as-is if it does not have a buffer
attribute (restores backward compatibility).

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: Copying the lru_cache() wrapper object now always works,
independently from the type of the wrapped object (by returning the
original object unchanged).

@item 
bpo-24103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24103}: Fixed possible use after free in ElementTree.XMLPullParser.

@item 
bpo-25860@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25860}: os.fwalk() no longer skips remaining directories when error
occurs. Original patch by Samson Lee.

@item 
bpo-25914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25914}: Fixed and simplified OrderedDict.__sizeof__.

@item 
bpo-25902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25902}: Fixed various refcount issues in ElementTree iteration.

@item 
bpo-25717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25717}: Restore the previous behaviour of tolerating most fstat()
errors when opening files.  This was a regression in 3.5a1, and stopped
anonymous temporary files from working in special cases.

@item 
bpo-24903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24903}: Fix regression in number of arguments compileall accepts when
'-d' is specified.  The check on the number of arguments has been dropped
completely as it never worked correctly anyway.

@item 
bpo-25764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25764}: In the subprocess module, preserve any exception caused by
fork() failure when preexec_fn is used.

@item 
bpo-6478@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6478}: _strptime's regexp cache now is reset after changing timezone
with time.tzset().

@item 
bpo-14285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14285}: When executing a package with the "python -m package" option,
and package initialization fails, a proper traceback is now reported.  The
"runpy" module now lets exceptions from package initialization pass back
to the caller, rather than raising ImportError.

@item 
bpo-19771@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19771}: Also in runpy and the "-m" option, omit the irrelevant message
". . . is a package and cannot be directly executed" if the package could
not even be initialized (e.g. due to a bad @code{*.pyc} file).

@item 
bpo-25177@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25177}: Fixed problem with the mean of very small and very large
numbers. As a side effect, statistics.mean and statistics.variance should
be significantly faster.

@item 
bpo-25718@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25718}: Fixed copying object with state with boolean value is false.

@item 
bpo-10131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10131}: Fixed deep copying of minidom documents.  Based on patch by
Marian Ganisin.

@item 
bpo-25725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25725}: Fixed a reference leak in pickle.loads() when unpickling
invalid data including tuple instructions.

@item 
bpo-25663@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25663}: In the Readline completer, avoid listing duplicate global
names, and search the global namespace before searching builtins.

@item 
bpo-25688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25688}: Fixed file leak in ElementTree.iterparse() raising an error.

@item 
bpo-23914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23914}: Fixed SystemError raised by unpickler on broken pickle data.

@item 
bpo-25691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25691}: Fixed crash on deleting ElementTree.Element attributes.

@item 
bpo-25624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25624}: ZipFile now always writes a ZIP_STORED header for directory
entries.  Patch by Dingyuan Wang.

@item 
Skip getaddrinfo if host is already resolved. Patch by A. Jesse Jiryu
Davis.

@item 
bpo-26050@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26050}: Add asyncio.StreamReader.readuntil() method. Patch by Марк
Коренберг.

@item 
bpo-25924@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25924}: Avoid unnecessary serialization of getaddrinfo(3) calls on OS X
versions 10.5 or higher.  Original patch by A. Jesse Jiryu Davis.

@item 
bpo-26406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26406}: Avoid unnecessary serialization of getaddrinfo(3) calls on
current versions of OpenBSD and NetBSD.  Patch by A. Jesse Jiryu Davis.

@item 
bpo-26848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26848}: Fix asyncio/subprocess.communicate() to handle empty input.
Patch by Jack O'Connor.

@item 
bpo-27040@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27040}: Add loop.get_exception_handler method

@item 
bpo-27041@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27041}: asyncio: Add loop.create_future method

@item 
bpo-27223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27223}: asyncio: Fix _read_ready and _write_ready to respect
_conn_lost. Patch by Łukasz Langa.

@item 
bpo-22970@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22970}: asyncio: Fix inconsistency cancelling Condition.wait. Patch by
David Coles.
@end itemize

@node IDLE<59>,Documentation<70>,Library<83>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id713}@anchor{1b12}
@subsubsection IDLE



@itemize -

@item 
bpo-5124@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5124}: Paste with text selected now replaces the selection on X11. This
matches how paste works on Windows, Mac, most modern Linux apps, and ttk
widgets. Original patch by Serhiy Storchaka.

@item 
bpo-24759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24759}: Make clear in idlelib.idle_test.__init__ that the directory is
a private implementation of test.test_idle and tool for maintainers.

@item 
bpo-27196@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27196}: Stop 'ThemeChanged' warnings when running IDLE tests. These
persisted after other warnings were suppressed in #20567. Apply Serhiy
Storchaka's update_idletasks solution to four test files. Record this
additional advice in idle_test/README.txt

@item 
bpo-20567@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20567}: Revise idle_test/README.txt with advice about avoiding tk
warning messages from tests.  Apply advice to several IDLE tests.

@item 
bpo-27117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27117}: Make colorizer htest and turtledemo work with dark themes. Move
code for configuring text widget colors to a new function.

@item 
bpo-26673@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26673}: When tk reports font size as 0, change to size 10. Such fonts
on Linux prevented the configuration dialog from opening.

@item 
bpo-21939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21939}: Add test for IDLE's percolator. Original patch by Saimadhav
Heblikar.

@item 
bpo-21676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21676}: Add test for IDLE's replace dialog. Original patch by Saimadhav
Heblikar.

@item 
bpo-18410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18410}: Add test for IDLE's search dialog. Original patch by Westley
Martínez.

@item 
bpo-21703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21703}: Add test for IDLE's undo delegator. Original patch by Saimadhav
Heblikar .

@item 
bpo-27044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27044}: Add ConfigDialog.remove_var_callbacks to stop memory leaks.

@item 
bpo-23977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23977}: Add more asserts to test_delegator.

@item 
bpo-20640@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20640}: Add tests for idlelib.configHelpSourceEdit. Patch by Saimadhav
Heblikar.

@item 
In the 'IDLE-console differences' section of the IDLE doc, clarify how
running with IDLE affects sys.modules and the standard streams.

@item 
bpo-25507@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25507}: fix incorrect change in IOBinding that prevented printing.
Augment IOBinding htest to include all major IOBinding functions.

@item 
bpo-25905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25905}: Revert unwanted conversion of ' to ’ RIGHT SINGLE QUOTATION
MARK in README.txt and open this and NEWS.txt with 'ascii'. Re-encode
CREDITS.txt to utf-8 and open it with 'utf-8'.
@end itemize

@node Documentation<70>,Tests<75>,IDLE<59>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id714}@anchor{1b13}
@subsubsection Documentation



@itemize -

@item 
bpo-19489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19489}: Moved the search box from the sidebar to the header and footer
of each page. Patch by Ammar Askar.

@item 
bpo-24136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24136}: Document the new 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/} unpacking syntax of 3.5.

@item 
bpo-26736@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26736}: Used HTTPS for external links in the documentation if possible.

@item 
bpo-6953@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6953}: Rework the Readline module documentation to group related
functions together, and add more details such as what underlying Readline
functions and variables are accessed.

@item 
bpo-23606@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23606}: Adds note to ctypes documentation regarding cdll.msvcrt.

@item 
bpo-25500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25500}: Fix documentation to not claim that __import__ is searched for
in the global scope.

@item 
bpo-26014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26014}: Update 3.x packaging documentation: * "See also" links to the
new docs are now provided in the legacy pages * links to setuptools
documentation have been updated
@end itemize

@node Tests<75>,Build<80>,Documentation<70>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id715}@anchor{1b14}
@subsubsection Tests



@itemize -

@item 
bpo-21916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21916}: Added tests for the turtle module.  Patch by ingrid, Gregory
Loyse and Jelle Zijlstra.

@item 
bpo-26523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26523}: The multiprocessing thread pool (multiprocessing.dummy.Pool)
was untested.

@item 
bpo-26015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26015}: Added new tests for pickling iterators of mutable sequences.

@item 
bpo-26325@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26325}: Added test.support.check_no_resource_warning() to check that no
ResourceWarning is emitted.

@item 
bpo-25940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25940}: Changed test_ssl to use self-signed.pythontest.net.  This
avoids relying on svn.python.org, which recently changed root certificate.

@item 
bpo-25616@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25616}: Tests for OrderedDict are extracted from test_collections into
separate file test_ordered_dict.

@item 
bpo-26583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26583}: Skip test_timestamp_overflow in test_import if bytecode files
cannot be written.
@end itemize

@node Build<80>,Windows<70>,Tests<75>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id716}@anchor{1b15}
@subsubsection Build



@itemize -

@item 
bpo-26884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26884}: Fix linking extension modules for cross builds. Patch by Xavier
de Gaye.

@item 
bpo-22359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22359}: Disable the rules for running _freeze_importlib and pgen when
cross-compiling.  The output of these programs is normally saved with the
source code anyway, and is still regenerated when doing a native build.
Patch by Xavier de Gaye.

@item 
bpo-27229@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27229}: Fix the cross-compiling pgen rule for in-tree builds.  Patch by
Xavier de Gaye.

@item 
bpo-21668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21668}: Link audioop, _datetime, _ctypes_test modules to libm, except
on Mac OS X. Patch written by Xavier de Gaye.

@item 
bpo-25702@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25702}: A --with-lto configure option has been added that will enable
link time optimizations at build time during a make profile-opt. Some
compilers and toolchains are known to not produce stable code when using
LTO, be sure to test things thoroughly before relying on it. It can
provide a few % speed up over profile-opt alone.

@item 
bpo-26624@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26624}: Adds validation of ucrtbase[d].dll version with warning for old
versions.

@item 
bpo-17603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17603}: Avoid error about nonexistent fileblocks.o file by using a
lower-level check for st_blocks in struct stat.

@item 
bpo-26079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26079}: Fixing the build output folder for tix-8.4.3.6. Patch by Bjoern
Thiel.

@item 
bpo-26465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26465}: Update Windows builds to use OpenSSL 1.0.2g.

@item 
bpo-24421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24421}: Compile Modules/_math.c once, before building extensions.
Previously it could fail to compile properly if the math and cmath builds
were concurrent.

@item 
bpo-25348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25348}: Added @code{--pgo} and @code{--pgo-job} arguments to
@code{PCbuild\build.bat} for building with Profile-Guided Optimization.  The
old @code{PCbuild\build_pgo.bat} script is now deprecated, and simply calls
@code{PCbuild\build.bat --pgo %*}.

@item 
bpo-25827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25827}: Add support for building with ICC to @code{configure}, including a
new @code{--with-icc} flag.

@item 
bpo-25696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25696}: Fix installation of Python on UNIX with make -j9.

@item 
bpo-26930@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26930}: Update OS X 10.5+ 32-bit-only installer to build and link with
OpenSSL 1.0.2h.

@item 
bpo-26268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26268}: Update Windows builds to use OpenSSL 1.0.2f.

@item 
bpo-25136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25136}: Support Apple Xcode 7's new textual SDK stub libraries.

@item 
bpo-24324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24324}: Do not enable unreachable code warnings when using gcc as the
option does not work correctly in older versions of gcc and has been
silently removed as of gcc-4.5.
@end itemize

@node Windows<70>,Tools/Demos<44>,Build<80>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id717}@anchor{1b16}
@subsubsection Windows



@itemize -

@item 
bpo-27053@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=27053}: Updates make_zip.py to correctly generate library ZIP file.

@item 
bpo-26268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26268}: Update the prepare_ssl.py script to handle OpenSSL releases
that don't include the contents of the include directory (that is, 1.0.2e
and later).

@item 
bpo-26071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26071}: bdist_wininst created binaries fail to start and find 32bit
Python

@item 
bpo-26073@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26073}: Update the list of magic numbers in launcher

@item 
bpo-26065@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26065}: Excludes venv from library when generating embeddable distro.

@item 
bpo-17500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17500}: Remove unused and outdated icons. (See also:
@indicateurl{https://github.com/python/pythondotorg/issues/945})
@end itemize

@node Tools/Demos<44>,,Windows<70>,Python 3 5 2 release candidate 1
@anchor{whatsnew/changelog id718}@anchor{1b17}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-26799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26799}: Fix python-gdb.py: don't get C types once when the Python code
is loaded, but get C types on demand. The C types can change if
python-gdb.py is loaded before the Python executable. Patch written by
Thomas Ilsche.

@item 
bpo-26271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26271}: Fix the Freeze tool to properly use flags passed through
configure. Patch by Daniel Shaulov.

@item 
bpo-26489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26489}: Add dictionary unpacking support to Tools/parser/unparse.py.
Patch by Guo Ci Teo.

@item 
bpo-26316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=26316}: Fix variable name typo in Argument Clinic.
@end itemize

@node Python 3 5 1 final,Python 3 5 1 release candidate 1,Python 3 5 2 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-5-1-final}@anchor{1b18}
@subsection Python 3.5.1 final


`Release date: 2015-12-06'

@menu
* Core and Builtins: Core and Builtins<85>. 
* Windows: Windows<71>. 

@end menu

@node Core and Builtins<85>,Windows<71>,,Python 3 5 1 final
@anchor{whatsnew/changelog id719}@anchor{1b19}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-25709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25709}: Fixed problem with in-place string concatenation and utf-8
cache.
@end itemize

@node Windows<71>,,Core and Builtins<85>,Python 3 5 1 final
@anchor{whatsnew/changelog id720}@anchor{1b1a}
@subsubsection Windows



@itemize -

@item 
bpo-25715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25715}: Python 3.5.1 installer shows wrong upgrade path and incorrect
logic for launcher detection.
@end itemize

@node Python 3 5 1 release candidate 1,Python 3 5 0 final,Python 3 5 1 final,Changelog
@anchor{whatsnew/changelog python-3-5-1-release-candidate-1}@anchor{1b1b}
@subsection Python 3.5.1 release candidate 1


`Release date: 2015-11-22'

@menu
* Core and Builtins: Core and Builtins<86>. 
* Library: Library<84>. 
* IDLE: IDLE<60>. 
* Documentation: Documentation<71>. 
* Tests: Tests<76>. 
* Build: Build<81>. 
* Windows: Windows<72>. 
* Tools/Demos: Tools/Demos<45>. 

@end menu

@node Core and Builtins<86>,Library<84>,,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id721}@anchor{1b1c}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-25630@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25630}: Fix a possible segfault during argument parsing in functions
that accept filesystem paths.

@item 
bpo-23564@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23564}: Fixed a partially broken sanity check in the _posixsubprocess
internals regarding how fds_to_pass were passed to the child.  The bug had
no actual impact as subprocess.py already avoided it.

@item 
bpo-25388@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25388}: Fixed tokenizer crash when processing undecodable source code
with a null byte.

@item 
bpo-25462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25462}: The hash of the key now is calculated only once in most
operations in C implementation of OrderedDict.

@item 
bpo-22995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22995}: Default implementation of __reduce__ and __reduce_ex__ now
rejects builtin types with not defined __new__.

@item 
bpo-25555@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25555}: Fix parser and AST: fill lineno and col_offset of "arg" node
when compiling AST from Python objects.

@item 
bpo-24802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24802}: Avoid buffer overreads when int(), float(), compile(), exec()
and eval() are passed bytes-like objects.  These objects are not
necessarily terminated by a null byte, but the functions assumed they
were.

@item 
bpo-24726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24726}: Fixed a crash and leaking NULL in repr() of OrderedDict that
was mutated by direct calls of dict methods.

@item 
bpo-25449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25449}: Iterating OrderedDict with keys with unstable hash now raises
KeyError in C implementations as well as in Python implementation.

@item 
bpo-25395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25395}: Fixed crash when highly nested OrderedDict structures were
garbage collected.

@item 
bpo-25274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25274}: sys.setrecursionlimit() now raises a RecursionError if the new
recursion limit is too low depending at the current recursion depth.
Modify also the "lower-water mark" formula to make it monotonic. This mark
is used to decide when the overflowed flag of the thread state is reset.

@item 
bpo-24402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24402}: Fix input() to prompt to the redirected stdout when
sys.stdout.fileno() fails.

@item 
bpo-24806@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24806}: Prevent builtin types that are not allowed to be subclassed
from being subclassed through multiple inheritance.

@item 
bpo-24848@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24848}: Fixed a number of bugs in UTF-7 decoding of misformed data.

@item 
bpo-25280@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25280}: Import trace messages emitted in verbose (-v) mode are no
longer formatted twice.

@item 
bpo-25003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25003}: On Solaris 11.3 or newer, os.urandom() now uses the getrandom()
function instead of the getentropy() function. The getentropy() function
is blocking to generate very good quality entropy, os.urandom() doesn't
need such high-quality entropy.

@item 
bpo-25182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25182}: The stdprinter (used as sys.stderr before the io module is
imported at startup) now uses the backslashreplace error handler.

@item 
bpo-25131@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25131}: Make the line number and column offset of set/dict literals and
comprehensions correspond to the opening brace.

@item 
bpo-25150@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25150}: Hide the private @code{_Py_atomic_@var{xxx}} symbols from the
public Python.h header to fix a compilation error with OpenMP.
PyThreadState_GET() becomes an alias to PyThreadState_Get() to avoid ABI
incompatibilities.
@end itemize

@node Library<84>,IDLE<60>,Core and Builtins<86>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id722}@anchor{1b1d}
@subsubsection Library



@itemize -

@item 
bpo-25626@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25626}: Change three zlib functions to accept sizes that fit in
Py_ssize_t, but internally cap those sizes to UINT_MAX.  This resolves a
regression in 3.5 where GzipFile.read() failed to read chunks larger than
2 or 4 GiB.  The change affects the zlib.Decompress.decompress()
max_length parameter, the zlib.decompress() bufsize parameter, and the
zlib.Decompress.flush() length parameter.

@item 
bpo-25583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25583}: Avoid incorrect errors raised by os.makedirs(exist_ok=True)
when the OS gives priority to errors such as EACCES over EEXIST.

@item 
bpo-25593@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25593}: Change semantics of EventLoop.stop() in asyncio.

@item 
bpo-6973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6973}: When we know a subprocess.Popen process has died, do not allow
the send_signal(), terminate(), or kill() methods to do anything as they
could potentially signal a different process.

@item 
bpo-25590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25590}: In the Readline completer, only call getattr() once per
attribute.

@item 
bpo-25498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25498}: Fix a crash when garbage-collecting ctypes objects created by
wrapping a memoryview.  This was a regression made in 3.5a1.  Based on
patch by Eryksun.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Added "escape" to the __all__ list in the glob module.

@item 
bpo-25584@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25584}: Fixed recursive glob() with patterns starting with @code{**}.

@item 
bpo-25446@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25446}: Fix regression in smtplib's AUTH LOGIN support.

@item 
bpo-18010@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18010}: Fix the pydoc web server's module search function to handle
exceptions from importing packages.

@item 
bpo-25554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25554}: Got rid of circular references in regular expression parsing.

@item 
bpo-25510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25510}: fileinput.FileInput.readline() now returns b'@w{'} instead of '@w{'} at
the end if the FileInput was opened with binary mode. Patch by Ryosuke
Ito.

@item 
bpo-25503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25503}: Fixed inspect.getdoc() for inherited docstrings of properties.
Original patch by John Mark Vandenberg.

@item 
bpo-25515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25515}: Always use os.urandom as a source of randomness in uuid.uuid4.

@item 
bpo-21827@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21827}: Fixed textwrap.dedent() for the case when largest common
whitespace is a substring of smallest leading whitespace. Based on patch
by Robert Li.

@item 
bpo-25447@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25447}: The lru_cache() wrapper objects now can be copied and pickled
(by returning the original object unchanged).

@item 
bpo-25390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25390}: typing: Don't crash on Union[str, Pattern].

@item 
bpo-25441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25441}: asyncio: Raise error from drain() when socket is closed.

@item 
bpo-25410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25410}: Cleaned up and fixed minor bugs in C implementation of
OrderedDict.

@item 
bpo-25411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25411}: Improved Unicode support in SMTPHandler through better use of
the email package. Thanks to user simon04 for the patch.

@item 
bpo-25407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25407}: Remove mentions of the formatter module being removed in Python
3.6.

@item 
bpo-25406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25406}: Fixed a bug in C implementation of OrderedDict.move_to_end()
that caused segmentation fault or hang in iterating after moving several
items to the start of ordered dict.

@item 
bpo-25364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25364}: zipfile now works in threads disabled builds.

@item 
bpo-25328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25328}: smtpd's SMTPChannel now correctly raises a ValueError if both
decode_data and enable_SMTPUTF8 are set to true.

@item 
bpo-25316@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25316}: distutils raises OSError instead of DistutilsPlatformError when
MSVC is not installed.

@item 
bpo-25380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25380}: Fixed protocol for the STACK_GLOBAL opcode in
pickletools.opcodes.

@item 
bpo-23972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23972}: Updates asyncio datagram create method allowing reuseport and
reuseaddr socket options to be set prior to binding the socket. Mirroring
the existing asyncio create_server method the reuseaddr option for
datagram sockets defaults to True if the O/S is 'posix' (except if the
platform is Cygwin). Patch by Chris Laws.

@item 
bpo-25304@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25304}: Add asyncio.run_coroutine_threadsafe().  This lets you submit a
coroutine to a loop from another thread, returning a
concurrent.futures.Future.  By Vincent Michel.

@item 
bpo-25232@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25232}: Fix CGIRequestHandler to split the query from the URL at the
first question mark (?) rather than the last. Patch from Xiang Zhang.

@item 
bpo-24657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24657}: Prevent CGIRequestHandler from collapsing slashes in the query
part of the URL as if it were a path. Patch from Xiang Zhang.

@item 
bpo-24483@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24483}: C implementation of functools.lru_cache() now calculates key's
hash only once.

@item 
bpo-22958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22958}: Constructor and update method of weakref.WeakValueDictionary
now accept the self and the dict keyword arguments.

@item 
bpo-22609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22609}: Constructor of collections.UserDict now accepts the self
keyword argument.

@item 
bpo-25111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25111}: Fixed comparison of traceback.FrameSummary.

@item 
bpo-25262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25262}: Added support for BINBYTES8 opcode in Python implementation of
unpickler. Highest 32 bits of 64-bit size for BINUNICODE8 and BINBYTES8
opcodes no longer silently ignored on 32-bit platforms in C
implementation.

@item 
bpo-25034@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25034}: Fix string.Formatter problem with auto-numbering and nested
format_specs. Patch by Anthon van der Neut.

@item 
bpo-25233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25233}: Rewrite the guts of asyncio.Queue and asyncio.Semaphore to be
more understandable and correct.

@item 
bpo-25203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25203}: Failed readline.set_completer_delims() no longer left the
module in inconsistent state.

@item 
bpo-23600@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23600}: Default implementation of tzinfo.fromutc() was returning wrong
results in some cases.

@item 
bpo-23329@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23329}: Allow the ssl module to be built with older versions of
LibreSSL.

@item 
Prevent overflow in _Unpickler_Read.

@item 
bpo-25047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25047}: The XML encoding declaration written by Element Tree now
respects the letter case given by the user. This restores the ability to
write encoding names in uppercase like "UTF-8", which worked in Python 2.

@item 
bpo-25135@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25135}: Make deque_clear() safer by emptying the deque before clearing.
This helps avoid possible reentrancy issues.

@item 
bpo-19143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19143}: platform module now reads Windows version from kernel32.dll to
avoid compatibility shims.

@item 
bpo-25092@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25092}: Fix datetime.strftime() failure when errno was already set to
EINVAL.

@item 
bpo-23517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23517}: Fix rounding in fromtimestamp() and utcfromtimestamp() methods
of datetime.datetime: microseconds are now rounded to nearest with ties
going to nearest even integer (ROUND_HALF_EVEN), instead of being rounding
towards minus infinity (ROUND_FLOOR). It's important that these methods
use the same rounding mode than datetime.timedelta to keep the property:
(datetime(1970,1,1) + timedelta(seconds=t)) ==
datetime.utcfromtimestamp(t). It also the rounding mode used by
round(float) for example.

@item 
bpo-25155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25155}: Fix datetime.datetime.now() and datetime.datetime.utcnow() on
Windows to support date after year 2038. It was a regression introduced in
Python 3.5.0.

@item 
bpo-25108@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25108}: Omitted internal frames in traceback functions print_stack(),
format_stack(), and extract_stack() called without arguments.

@item 
bpo-25118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25118}: Fix a regression of Python 3.5.0 in os.waitpid() on Windows.

@item 
bpo-24684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24684}: socket.socket.getaddrinfo() now calls
PyUnicode_AsEncodedString() instead of calling the encode() method of the
host, to handle correctly custom string with an encode() method which
doesn't return a byte string. The encoder of the IDNA codec is now called
directly instead of calling the encode() method of the string.

@item 
bpo-25060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25060}: Correctly compute stack usage of the BUILD_MAP opcode.

@item 
bpo-24857@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24857}: Comparing call_args to a long sequence now correctly returns a
boolean result instead of raising an exception.  Patch by A Kaptur.

@item 
bpo-23144@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23144}: Make sure that HTMLParser.feed() returns all the data, even
when convert_charrefs is True.

@item 
bpo-24982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24982}: shutil.make_archive() with the "zip" format now adds entries
for directories (including empty directories) in ZIP file.

@item 
bpo-25019@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25019}: Fixed a crash caused by setting non-string key of expat parser.
Based on patch by John Leitch.

@item 
bpo-16180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16180}: Exit pdb if file has syntax error, instead of trapping user in
an infinite loop.  Patch by Xavier de Gaye.

@item 
bpo-24891@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24891}: Fix a race condition at Python startup if the file descriptor
of stdin (0), stdout (1) or stderr (2) is closed while Python is creating
sys.stdin, sys.stdout and sys.stderr objects. These attributes are now set
to None if the creation of the object failed, instead of raising an
OSError exception. Initial patch written by Marco Paolini.

@item 
bpo-24992@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24992}: Fix error handling and a race condition (related to garbage
collection) in collections.OrderedDict constructor.

@item 
bpo-24881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24881}: Fixed setting binary mode in Python implementation of FileIO on
Windows and Cygwin.  Patch from Akira Li.

@item 
bpo-25578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25578}: Fix (another) memory leak in SSLSocket.getpeercer().

@item 
bpo-25530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25530}: Disable the vulnerable SSLv3 protocol by default when creating
ssl.SSLContext.

@item 
bpo-25569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25569}: Fix memory leak in SSLSocket.getpeercert().

@item 
bpo-25471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25471}: Sockets returned from accept() shouldn't appear to be
nonblocking.

@item 
bpo-25319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25319}: When threading.Event is reinitialized, the underlying condition
should use a regular lock rather than a recursive lock.

@item 
bpo-21112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21112}: Fix regression in unittest.expectedFailure on subclasses. Patch
from Berker Peksag.

@item 
bpo-24764@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24764}: cgi.FieldStorage.read_multi() now ignores the Content-Length
header in part headers. Patch written by Peter Landry and reviewed by
Pierre Quentel.

@item 
bpo-24913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24913}: Fix overrun error in deque.index(). Found by John Leitch and
Bryce Darling.

@item 
bpo-24774@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24774}: Fix docstring in http.server.test. Patch from Chiu-Hsiang Hsu.

@item 
bpo-21159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21159}: Improve message in
configparser.InterpolationMissingOptionError. Patch from Łukasz Langa.

@item 
bpo-20362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20362}: Honour TestCase.longMessage correctly in assertRegex. Patch
from Ilia Kurenkov.

@item 
bpo-23572@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23572}: Fixed functools.singledispatch on classes with false
metaclasses.  Patch by Ethan Furman.

@item 
asyncio: ensure_future() now accepts awaitable objects.
@end itemize

@node IDLE<60>,Documentation<71>,Library<84>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id723}@anchor{1b1e}
@subsubsection IDLE



@itemize -

@item 
bpo-15348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15348}: Stop the debugger engine (normally in a user process) before
closing the debugger window (running in the IDLE process). This prevents
the RuntimeErrors that were being caught and ignored.

@item 
bpo-24455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24455}: Prevent IDLE from hanging when a) closing the shell while the
debugger is active (15347); b) closing the debugger with the [X] button
(15348); and c) activating the debugger when already active (24455). The
patch by Mark Roseman does this by making two changes. 1. Suspend and
resume the gui.interaction method with the tcl vwait mechanism intended
for this purpose (instead of root.mainloop & .quit). 2. In gui.run, allow
any existing interaction to terminate first.

@item 
Change 'The program' to 'Your program' in an IDLE 'kill program?' message
to make it clearer that the program referred to is the currently running
user program, not IDLE itself.

@item 
bpo-24750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24750}: Improve the appearance of the IDLE editor window status bar.
Patch by Mark Roseman.

@item 
bpo-25313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25313}: Change the handling of new built-in text color themes to better
address the compatibility problem introduced by the addition of IDLE Dark.
Consistently use the revised idleConf.CurrentTheme everywhere in idlelib.

@item 
bpo-24782@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24782}: Extension configuration is now a tab in the IDLE Preferences
dialog rather than a separate dialog.  The former tabs are now a sorted
list.  Patch by Mark Roseman.

@item 
bpo-22726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22726}: Re-activate the config dialog help button with some content
about the other buttons and the new IDLE Dark theme.

@item 
bpo-24820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24820}: IDLE now has an 'IDLE Dark' built-in text color theme. It is
more or less IDLE Classic inverted, with a cobalt blue background.
Strings, comments, keywords, ... are still green, red, orange, ... . To
use it with IDLEs released before November 2015, hit the 'Save as New
Custom Theme' button and enter a new name, such as 'Custom Dark'.  The
custom theme will work with any IDLE release, and can be modified.

@item 
bpo-25224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25224}: README.txt is now an idlelib index for IDLE developers and
curious users. The previous user content is now in the IDLE doc chapter.
'IDLE' now means 'Integrated Development and Learning Environment'.

@item 
bpo-24820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24820}: Users can now set breakpoint colors in Settings -> Custom
Highlighting. Original patch by Mark Roseman.

@item 
bpo-24972@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24972}: Inactive selection background now matches active selection
background, as configured by users, on all systems.  Found items are now
always highlighted on Windows.  Initial patch by Mark Roseman.

@item 
bpo-24570@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24570}: Idle: make calltip and completion boxes appear on Macs affected
by a tk regression.  Initial patch by Mark Roseman.

@item 
bpo-24988@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24988}: Idle ScrolledList context menus (used in debugger) now work on
Mac Aqua. Patch by Mark Roseman.

@item 
bpo-24801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24801}: Make right-click for context menu work on Mac Aqua. Patch by
Mark Roseman.

@item 
bpo-25173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25173}: Associate tkinter messageboxes with a specific widget. For Mac
OSX, make them a 'sheet'.  Patch by Mark Roseman.

@item 
bpo-25198@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25198}: Enhance the initial html viewer now used for Idle Help.
Properly indent fixed-pitch text (patch by Mark Roseman). Give code
snippet a very Sphinx-like light blueish-gray background. Re-use initial
width and height set by users for shell and editor. When the Table of
Contents (TOC) menu is used, put the section header at the top of the
screen.

@item 
bpo-25225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25225}: Condense and rewrite Idle doc section on text colors.

@item 
bpo-21995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21995}: Explain some differences between IDLE and console Python.

@item 
bpo-22820@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22820}: Explain need for `print' when running file from Idle editor.

@item 
bpo-25224@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25224}: Doc: augment Idle feature list and no-subprocess section.

@item 
bpo-25219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25219}: Update doc for Idle command line options. Some were missing and
notes were not correct.

@item 
bpo-24861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24861}: Most of idlelib is private and subject to change. Use
idleib.idle.* to start Idle. See idlelib.__init__.__doc__.

@item 
bpo-25199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25199}: Idle: add synchronization comments for future maintainers.

@item 
bpo-16893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16893}: Replace help.txt with help.html for Idle doc display. The new
idlelib/help.html is rstripped Doc/build/html/library/idle.html. It looks
better than help.txt and will better document Idle as released. The
tkinter html viewer that works for this file was written by Mark Roseman.
The now unused EditorWindow.HelpDialog class and helt.txt file are
deprecated.

@item 
bpo-24199@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24199}: Deprecate unused idlelib.idlever with possible removal in 3.6.

@item 
bpo-24790@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24790}: Remove extraneous code (which also create 2 & 3 conflicts).
@end itemize

@node Documentation<71>,Tests<76>,IDLE<60>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id724}@anchor{1b1f}
@subsubsection Documentation



@itemize -

@item 
bpo-22558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22558}: Add remaining doc links to source code for Python-coded
modules. Patch by Yoni Lavi.

@item 
bpo-12067@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12067}: Rewrite Comparisons section in the Expressions chapter of the
language reference. Some of the details of comparing mixed types were
incorrect or ambiguous. NotImplemented is only relevant at a lower level
than the Expressions chapter. Added details of comparing range() objects,
and default behaviour and consistency suggestions for user-defined
classes. Patch from Andy Maier.

@item 
bpo-24952@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24952}: Clarify the default size argument of stack_size() in the
"threading" and "_thread" modules. Patch from Mattip.

@item 
bpo-23725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23725}: Overhaul tempfile docs. Note deprecated status of mktemp. Patch
from Zbigniew Jędrzejewski-Szmek.

@item 
bpo-24808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24808}: Update the types of some PyTypeObject fields.  Patch by Joseph
Weston.

@item 
bpo-22812@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22812}: Fix unittest discovery examples. Patch from Pam McA'Nulty.
@end itemize

@node Tests<76>,Build<81>,Documentation<71>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id725}@anchor{1b20}
@subsubsection Tests



@itemize -

@item 
bpo-25449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25449}: Added tests for OrderedDict subclasses.

@item 
bpo-25099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25099}: Make test_compileall not fail when an entry on sys.path cannot
be written to (commonly seen in administrative installs on Windows).

@item 
bpo-23919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23919}: Prevents assert dialogs appearing in the test suite.

@item 
@code{PCbuild\rt.bat} now accepts an unlimited number of arguments to pass
along to regrtest.py.  Previously there was a limit of 9.
@end itemize

@node Build<81>,Windows<72>,Tests<76>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id726}@anchor{1b21}
@subsubsection Build



@itemize -

@item 
bpo-24915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24915}: Add LLVM support for PGO builds and use the test suite to
generate the profile data. Initial patch by Alecsandru Patrascu of Intel.

@item 
bpo-24910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24910}: Windows MSIs now have unique display names.

@item 
bpo-24986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24986}: It is now possible to build Python on Windows without errors
when external libraries are not available.
@end itemize

@node Windows<72>,Tools/Demos<45>,Build<81>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id727}@anchor{1b22}
@subsubsection Windows



@itemize -

@item 
bpo-25450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25450}: Updates shortcuts to start Python in installation directory.

@item 
bpo-25164@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25164}: Changes default all-users install directory to match per-user
directory.

@item 
bpo-25143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25143}: Improves installer error messages for unsupported platforms.

@item 
bpo-25163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25163}: Display correct directory in installer when using non-default
settings.

@item 
bpo-25361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25361}: Disables use of SSE2 instructions in Windows 32-bit build

@item 
bpo-25089@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25089}: Adds logging to installer for case where launcher is not
selected on upgrade.

@item 
bpo-25165@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25165}: Windows uninstallation should not remove launcher if other
versions remain

@item 
bpo-25112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25112}: py.exe launcher is missing icons

@item 
bpo-25102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25102}: Windows installer does not precompile for -O or -OO.

@item 
bpo-25081@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25081}: Makes Back button in installer go back to upgrade page when
upgrading.

@item 
bpo-25091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25091}: Increases font size of the installer.

@item 
bpo-25126@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25126}: Clarifies that the non-web installer will download some
components.

@item 
bpo-25213@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25213}: Restores requestedExecutionLevel to manifest to disable UAC
virtualization.

@item 
bpo-25022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25022}: Removed very outdated PC/example_nt/ directory.
@end itemize

@node Tools/Demos<45>,,Windows<72>,Python 3 5 1 release candidate 1
@anchor{whatsnew/changelog id728}@anchor{1b23}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-25440@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25440}: Fix output of python-config --extension-suffix.
@end itemize

@node Python 3 5 0 final,Python 3 5 0 release candidate 4,Python 3 5 1 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-5-0-final}@anchor{1b24}
@subsection Python 3.5.0 final


`Release date: 2015-09-13'

@menu
* Build: Build<82>. 

@end menu

@node Build<82>,,,Python 3 5 0 final
@anchor{whatsnew/changelog id729}@anchor{1b25}
@subsubsection Build



@itemize -

@item 
bpo-25071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25071}: Windows installer should not require TargetDir parameter when
installing quietly.
@end itemize

@node Python 3 5 0 release candidate 4,Python 3 5 0 release candidate 3,Python 3 5 0 final,Changelog
@anchor{whatsnew/changelog python-3-5-0-release-candidate-4}@anchor{1b26}
@subsection Python 3.5.0 release candidate 4


`Release date: 2015-09-09'

@menu
* Library: Library<85>. 
* Build: Build<83>. 

@end menu

@node Library<85>,Build<83>,,Python 3 5 0 release candidate 4
@anchor{whatsnew/changelog id730}@anchor{1b27}
@subsubsection Library



@itemize -

@item 
bpo-25029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25029}: Fixes MemoryError in test_strptime.
@end itemize

@node Build<83>,,Library<85>,Python 3 5 0 release candidate 4
@anchor{whatsnew/changelog id731}@anchor{1b28}
@subsubsection Build



@itemize -

@item 
bpo-25027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=25027}: Reverts partial-static build options and adds vcruntime140.dll
to Windows installation.
@end itemize

@node Python 3 5 0 release candidate 3,Python 3 5 0 release candidate 2,Python 3 5 0 release candidate 4,Changelog
@anchor{whatsnew/changelog python-3-5-0-release-candidate-3}@anchor{1b29}
@subsection Python 3.5.0 release candidate 3


`Release date: 2015-09-07'

@menu
* Core and Builtins: Core and Builtins<87>. 
* Library: Library<86>. 

@end menu

@node Core and Builtins<87>,Library<86>,,Python 3 5 0 release candidate 3
@anchor{whatsnew/changelog id732}@anchor{1b2a}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24305@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24305}: Prevent import subsystem stack frames from being counted by the
warnings.warn(stacklevel=) parameter.

@item 
bpo-24912@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24912}: Prevent __class__ assignment to immutable built-in objects.

@item 
bpo-24975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24975}: Fix AST compilation for 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/} syntax.
@end itemize

@node Library<86>,,Core and Builtins<87>,Python 3 5 0 release candidate 3
@anchor{whatsnew/changelog id733}@anchor{1b2b}
@subsubsection Library



@itemize -

@item 
bpo-24917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24917}: time_strftime() buffer over-read.

@item 
bpo-24748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24748}: To resolve a compatibility problem found with py2exe and
pywin32, imp.load_dynamic() once again ignores previously loaded modules
to support Python modules replacing themselves with extension modules.
Patch by Petr Viktorin.

@item 
bpo-24635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24635}: Fixed a bug in typing.py where isinstance([], typing.Iterable)
would return True once, then False on subsequent calls.

@item 
bpo-24989@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24989}: Fixed buffer overread in BytesIO.readline() if a position is
set beyond size.  Based on patch by John Leitch.

@item 
bpo-24913@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24913}: Fix overrun error in deque.index(). Found by John Leitch and
Bryce Darling.
@end itemize

@node Python 3 5 0 release candidate 2,Python 3 5 0 release candidate 1,Python 3 5 0 release candidate 3,Changelog
@anchor{whatsnew/changelog python-3-5-0-release-candidate-2}@anchor{1b2c}
@subsection Python 3.5.0 release candidate 2


`Release date: 2015-08-25'

@menu
* Core and Builtins: Core and Builtins<88>. 
* Library: Library<87>. 

@end menu

@node Core and Builtins<88>,Library<87>,,Python 3 5 0 release candidate 2
@anchor{whatsnew/changelog id734}@anchor{1b2d}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24769}: Interpreter now starts properly when dynamic loading is
disabled.  Patch by Petr Viktorin.

@item 
bpo-21167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21167}: NAN operations are now handled correctly when python is
compiled with ICC even if -fp-model strict is not specified.

@item 
bpo-24492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24492}: A "package" lacking a __name__ attribute when trying to perform
a @code{from .. import ...} statement will trigger an ImportError instead of
an AttributeError.
@end itemize

@node Library<87>,,Core and Builtins<88>,Python 3 5 0 release candidate 2
@anchor{whatsnew/changelog id735}@anchor{1b2e}
@subsubsection Library



@itemize -

@item 
bpo-24847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24847}: Removes vcruntime140.dll dependency from Tcl/Tk.

@item 
bpo-24839@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24839}: platform._syscmd_ver raises DeprecationWarning

@item 
bpo-24867@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24867}: Fix Task.get_stack() for 'async def' coroutines
@end itemize

@node Python 3 5 0 release candidate 1,Python 3 5 0 beta 4,Python 3 5 0 release candidate 2,Changelog
@anchor{whatsnew/changelog python-3-5-0-release-candidate-1}@anchor{1b2f}
@subsection Python 3.5.0 release candidate 1


`Release date: 2015-08-09'

@menu
* Core and Builtins: Core and Builtins<89>. 
* Library: Library<88>. 
* IDLE: IDLE<61>. 
* Documentation: Documentation<72>. 
* Tests: Tests<77>. 

@end menu

@node Core and Builtins<89>,Library<88>,,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id736}@anchor{1b30}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24667@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24667}: Resize odict in all cases that the underlying dict resizes.
@end itemize

@node Library<88>,IDLE<61>,Core and Builtins<89>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id737}@anchor{1b31}
@subsubsection Library



@itemize -

@item 
bpo-24824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24824}: Signatures of codecs.encode() and codecs.decode() now are
compatible with pydoc.

@item 
bpo-24634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24634}: Importing uuid should not try to load libc on Windows

@item 
bpo-24798@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24798}: _msvccompiler.py doesn't properly support manifests

@item 
bpo-4395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4395}: Better testing and documentation of binary operators. Patch by
Martin Panter.

@item 
bpo-23973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23973}: Update typing.py from GitHub repo.

@item 
bpo-23004@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23004}: mock_open() now reads binary data correctly when the type of
read_data is bytes.  Initial patch by Aaron Hill.

@item 
bpo-23888@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23888}: Handle fractional time in cookie expiry. Patch by ssh.

@item 
bpo-23652@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23652}: Make it possible to compile the select module against the libc
headers from the Linux Standard Base, which do not include some EPOLL
macros.  Patch by Matt Frank.

@item 
bpo-22932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22932}: Fix timezones in email.utils.formatdate. Patch from Dmitry
Shachnev.

@item 
bpo-23779@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23779}: imaplib raises TypeError if authenticator tries to abort. Patch
from Craig Holmquist.

@item 
bpo-23319@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23319}: Fix ctypes.BigEndianStructure, swap correctly bytes. Patch
written by Matthieu Gautier.

@item 
bpo-23254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23254}: Document how to close the TCPServer listening socket. Patch
from Martin Panter.

@item 
bpo-19450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19450}: Update Windows and OS X installer builds to use SQLite 3.8.11.

@item 
bpo-17527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17527}: Add PATCH to wsgiref.validator. Patch from Luca Sbardella.

@item 
bpo-24791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24791}: Fix grammar regression for call syntax: 'g(*a or b)'.
@end itemize

@node IDLE<61>,Documentation<72>,Library<88>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id738}@anchor{1b32}
@subsubsection IDLE



@itemize -

@item 
bpo-23672@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23672}: Allow Idle to edit and run files with astral chars in name.
Patch by Mohd Sanad Zaki Rizvi.

@item 
bpo-24745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24745}: Idle editor default font. Switch from Courier to
platform-sensitive TkFixedFont.  This should not affect current customized
font selections.  If there is a problem, edit
$HOME/.idlerc/config-main.cfg and remove '@code{font@var{xxx}}' entries from
[Editor Window].  Patch by Mark Roseman.

@item 
bpo-21192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21192}: Idle editor. When a file is run, put its name in the restart
bar. Do not print false prompts. Original patch by Adnan Umer.

@item 
bpo-13884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13884}: Idle menus. Remove tearoff lines. Patch by Roger Serwy.
@end itemize

@node Documentation<72>,Tests<77>,IDLE<61>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id739}@anchor{1b33}
@subsubsection Documentation



@itemize -

@item 
bpo-24129@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24129}: Clarify the reference documentation for name resolution. This
includes removing the assumption that readers will be familiar with the
name resolution scheme Python used prior to the introduction of lexical
scoping for function namespaces. Patch by Ivan Levkivskyi.

@item 
bpo-20769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20769}: Improve reload() docs. Patch by Dorian Pula.

@item 
bpo-23589@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23589}: Remove duplicate sentence from the FAQ.  Patch by Yongzhi Pan.

@item 
bpo-24729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24729}: Correct IO tutorial to match implementation regarding encoding
parameter to open function.
@end itemize

@node Tests<77>,,Documentation<72>,Python 3 5 0 release candidate 1
@anchor{whatsnew/changelog id740}@anchor{1b34}
@subsubsection Tests



@itemize -

@item 
bpo-24751@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24751}: When running regrtest with the @code{-w} command line option, a
test run is no longer marked as a failure if all tests succeed when
re-run.
@end itemize

@node Python 3 5 0 beta 4,Python 3 5 0 beta 3,Python 3 5 0 release candidate 1,Changelog
@anchor{whatsnew/changelog python-3-5-0-beta-4}@anchor{1b35}
@subsection Python 3.5.0 beta 4


`Release date: 2015-07-26'

@menu
* Core and Builtins: Core and Builtins<90>. 
* Library: Library<89>. 
* Build: Build<84>. 

@end menu

@node Core and Builtins<90>,Library<89>,,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id741}@anchor{1b36}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-23573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23573}: Restored optimization of bytes.rfind() and bytearray.rfind()
for single-byte argument on Linux.

@item 
bpo-24569@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24569}: Make 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/} dictionary evaluation more consistent.

@item 
bpo-24583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24583}: Fix crash when set is mutated while being updated.

@item 
bpo-24407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24407}: Fix crash when dict is mutated while being updated.

@item 
bpo-24619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24619}: New approach for tokenizing async/await. As a consequence, it
is now possible to have one-line 'async def foo(): await ..' functions.

@item 
bpo-24687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24687}: Plug refleak on SyntaxError in function parameters annotations.

@item 
bpo-15944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15944}: memoryview: Allow arbitrary formats when casting to bytes.
Patch by Martin Panter.
@end itemize

@node Library<89>,Build<84>,Core and Builtins<90>,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id742}@anchor{1b37}
@subsubsection Library



@itemize -

@item 
bpo-23441@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23441}: rcompleter now prints a tab character instead of displaying
possible completions for an empty word.  Initial patch by Martin Sekera.

@item 
bpo-24683@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24683}: Fixed crashes in _json functions called with arguments of
inappropriate type.

@item 
bpo-21697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21697}: shutil.copytree() now correctly handles symbolic links that
point to directories.  Patch by Eduardo Seabra and Thomas Kluyver.

@item 
bpo-14373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14373}: Fixed segmentation fault when gc.collect() is called during
constructing lru_cache (C implementation).

@item 
bpo-24695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24695}: Fix a regression in traceback.print_exception().  If
exc_traceback is None we shouldn't print a traceback header like described
in the documentation.

@item 
bpo-24620@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24620}: Random.setstate() now validates the value of state last
element.

@item 
bpo-22485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22485}: Fixed an issue that caused @code{inspect.getsource} to return
incorrect results on nested functions.

@item 
bpo-22153@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22153}: Improve unittest docs. Patch from Martin Panter and evilzero.

@item 
bpo-24580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24580}: Symbolic group references to open group in re patterns now are
explicitly forbidden as well as numeric group references.

@item 
bpo-24206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24206}: Fixed __eq__ and __ne__ methods of inspect classes.

@item 
bpo-24631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24631}: Fixed regression in the timeit module with multiline setup.

@item 
bpo-18622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18622}: unittest.mock.mock_open().reset_mock would recurse infinitely.
Patch from Nicola Palumbo and Laurent De Buyst.

@item 
bpo-23661@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23661}: unittest.mock side_effects can now be exceptions again. This
was a regression vs Python 3.4. Patch from Ignacio Rossi

@item 
bpo-24608@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24608}: chunk.Chunk.read() now always returns bytes, not str.

@item 
bpo-18684@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18684}: Fixed reading out of the buffer in the re module.

@item 
bpo-24259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24259}: tarfile now raises a ReadError if an archive is truncated
inside a data segment.

@item 
bpo-15014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15014}: SMTP.auth() and SMTP.login() now support RFC 4954's optional
initial-response argument to the SMTP AUTH command.

@item 
bpo-24669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24669}: Fix inspect.getsource() for 'async def' functions. Patch by Kai
Groner.

@item 
bpo-24688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24688}: ast.get_docstring() for 'async def' functions.
@end itemize

@node Build<84>,,Library<89>,Python 3 5 0 beta 4
@anchor{whatsnew/changelog id743}@anchor{1b38}
@subsubsection Build



@itemize -

@item 
bpo-24603@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24603}: Update Windows builds and OS X 10.5 installer to use OpenSSL
1.0.2d.
@end itemize

@node Python 3 5 0 beta 3,Python 3 5 0 beta 2,Python 3 5 0 beta 4,Changelog
@anchor{whatsnew/changelog python-3-5-0-beta-3}@anchor{1b39}
@subsection Python 3.5.0 beta 3


`Release date: 2015-07-05'

@menu
* Core and Builtins: Core and Builtins<91>. 
* Library: Library<90>. 
* Tests: Tests<78>. 
* Documentation: Documentation<73>. 
* Build: Build<85>. 

@end menu

@node Core and Builtins<91>,Library<90>,,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id744}@anchor{1b3a}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24467@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24467}: Fixed possible buffer over-read in bytearray. The bytearray
object now always allocates place for trailing null byte and it's buffer
now is always null-terminated.

@item 
Upgrade to Unicode 8.0.0.

@item 
bpo-24345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24345}: Add Py_tp_finalize slot for the stable ABI.

@item 
bpo-24400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24400}: Introduce a distinct type for 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} coroutines; add
types.CoroutineType, inspect.getcoroutinestate,
inspect.getcoroutinelocals; coroutines no longer use CO_GENERATOR flag;
sys.set_coroutine_wrapper works only for 'async def' coroutines;
inspect.iscoroutine no longer uses collections.abc.Coroutine, it's
intended to test for pure 'async def' coroutines only; add new opcode:
GET_YIELD_FROM_ITER; fix generators wrapper used in types.coroutine to be
instance of collections.abc.Generator; collections.abc.Awaitable and
collections.abc.Coroutine can no longer be used to detect generator-based
coroutines--use inspect.isawaitable instead.

@item 
bpo-24450@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24450}: Add gi_yieldfrom to generators and cr_await to coroutines.
Contributed by Benno Leslie and Yury Selivanov.

@item 
bpo-19235@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19235}: Add new RecursionError exception. Patch by Georg Brandl.
@end itemize

@node Library<90>,Tests<78>,Core and Builtins<91>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id745}@anchor{1b3b}
@subsubsection Library



@itemize -

@item 
bpo-21750@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21750}: mock_open.read_data can now be read from each instance, as it
could in Python 3.3.

@item 
bpo-24552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24552}: Fix use after free in an error case of the _pickle module.

@item 
bpo-24514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24514}: tarfile now tolerates number fields consisting of only
whitespace.

@item 
bpo-19176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19176}: Fixed doctype() related bugs in C implementation of
ElementTree. A deprecation warning no longer issued by XMLParser subclass
with default doctype() method.  Direct call of doctype() now issues a
warning.  Parser's doctype() now is not called if target's doctype() is
called.  Based on patch by Martin Panter.

@item 
bpo-20387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20387}: Restore semantic round-trip correctness in tokenize/untokenize
for tab-indented blocks.

@item 
bpo-24456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24456}: Fixed possible buffer over-read in adpcm2lin() and lin2adpcm()
functions of the audioop module.

@item 
bpo-24336@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24336}: The contextmanager decorator now works with functions with
keyword arguments called "func" and "self".  Patch by Martin Panter.

@item 
bpo-24522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24522}: Fix possible integer overflow in json accelerator module.

@item 
bpo-24489@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24489}: ensure a previously set C errno doesn't disturb cmath.polar().

@item 
bpo-24408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24408}: Fixed AttributeError in measure() and metrics() methods of
tkinter.Font.

@item 
bpo-14373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14373}: C implementation of functools.lru_cache() now can be used with
methods.

@item 
bpo-24347@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24347}: Set KeyError if PyDict_GetItemWithError returns NULL.

@item 
bpo-24348@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24348}: Drop superfluous incref/decref.

@item 
bpo-24359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24359}: Check for changed OrderedDict size during iteration.

@item 
bpo-24368@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24368}: Support keyword arguments in OrderedDict methods.

@item 
bpo-24362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24362}: Simplify the C OrderedDict fast nodes resize logic.

@item 
bpo-24377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24377}: Fix a ref leak in OrderedDict.__repr__.

@item 
bpo-24369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24369}: Defend against key-changes during iteration.
@end itemize

@node Tests<78>,Documentation<73>,Library<90>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id746}@anchor{1b3c}
@subsubsection Tests



@itemize -

@item 
bpo-24373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24373}: _testmultiphase and xxlimited now use tp_traverse and
tp_finalize to avoid reference leaks encountered when combining tp_dealloc
with PyType_FromSpec (see bpo-16690@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16690} for details)
@end itemize

@node Documentation<73>,Build<85>,Tests<78>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id747}@anchor{1b3d}
@subsubsection Documentation



@itemize -

@item 
bpo-24458@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24458}: Update documentation to cover multi-phase initialization for
extension modules (PEP 489). Patch by Petr Viktorin.

@item 
bpo-24351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24351}: Clarify what is meant by "identifier" in the context of
string.Template instances.
@end itemize

@node Build<85>,,Documentation<73>,Python 3 5 0 beta 3
@anchor{whatsnew/changelog id748}@anchor{1b3e}
@subsubsection Build



@itemize -

@item 
bpo-24432@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24432}: Update Windows builds and OS X 10.5 installer to use OpenSSL
1.0.2c.
@end itemize

@node Python 3 5 0 beta 2,Python 3 5 0 beta 1,Python 3 5 0 beta 3,Changelog
@anchor{whatsnew/changelog python-3-5-0-beta-2}@anchor{1b3f}
@subsection Python 3.5.0 beta 2


`Release date: 2015-05-31'

@menu
* Core and Builtins: Core and Builtins<92>. 
* Library: Library<91>. 

@end menu

@node Core and Builtins<92>,Library<91>,,Python 3 5 0 beta 2
@anchor{whatsnew/changelog id749}@anchor{1b40}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24284@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24284}: The startswith and endswith methods of the str class no longer
return True when finding the empty string and the indexes are completely
out of range.

@item 
bpo-24115@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24115}: Update uses of PyObject_IsTrue(), PyObject_Not(),
PyObject_IsInstance(), PyObject_RichCompareBool() and _PyDict_Contains()
to check for and handle errors correctly.

@item 
bpo-24328@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24328}: Fix importing one character extension modules.

@item 
bpo-11205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11205}: In dictionary displays, evaluate the key before the value.

@item 
bpo-24285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24285}: Fixed regression that prevented importing extension modules
from inside packages. Patch by Petr Viktorin.
@end itemize

@node Library<91>,,Core and Builtins<92>,Python 3 5 0 beta 2
@anchor{whatsnew/changelog id750}@anchor{1b41}
@subsubsection Library



@itemize -

@item 
bpo-23247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23247}: Fix a crash in the StreamWriter.reset() of CJK codecs.

@item 
bpo-24270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24270}: Add math.isclose() and cmath.isclose() functions as per
@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/}. Contributed by Chris Barker and Tal Einat.

@item 
bpo-5633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5633}: Fixed timeit when the statement is a string and the setup is
not.

@item 
bpo-24326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24326}: Fixed audioop.ratecv() with non-default weightB argument.
Original patch by David Moore.

@item 
bpo-16991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16991}: Add a C implementation of OrderedDict.

@item 
bpo-23934@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23934}: Fix inspect.signature to fail correctly for builtin types
lacking signature information.  Initial patch by James Powell.
@end itemize

@node Python 3 5 0 beta 1,Python 3 5 0 alpha 4,Python 3 5 0 beta 2,Changelog
@anchor{whatsnew/changelog python-3-5-0-beta-1}@anchor{1b42}
@subsection Python 3.5.0 beta 1


`Release date: 2015-05-24'

@menu
* Core and Builtins: Core and Builtins<93>. 
* Library: Library<92>. 
* IDLE: IDLE<62>. 
* Tests: Tests<79>. 
* Documentation: Documentation<74>. 
* Tools/Demos: Tools/Demos<46>. 

@end menu

@node Core and Builtins<93>,Library<92>,,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id751}@anchor{1b43}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-24276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24276}: Fixed optimization of property descriptor getter.

@item 
bpo-24268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24268}: PEP 489: Multi-phase extension module initialization. Patch by
Petr Viktorin.

@item 
bpo-23955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23955}: Add pyvenv.cfg option to suppress registry/environment lookup
for generating sys.path on Windows.

@item 
bpo-24257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24257}: Fixed system error in the comparison of faked
types.SimpleNamespace.

@item 
bpo-22939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22939}: Fixed integer overflow in iterator object.  Patch by Clement
Rouault.

@item 
bpo-23985@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23985}: Fix a possible buffer overrun when deleting a slice from the
front of a bytearray and then appending some other bytes data.

@item 
bpo-24102@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24102}: Fixed exception type checking in standard error handlers.

@item 
bpo-15027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15027}: The UTF-32 encoder is now 3x to 7x faster.

@item 
bpo-23290@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23290}: Optimize set_merge() for cases where the target is empty.
(Contributed by Serhiy Storchaka.)

@item 
bpo-2292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2292}: PEP 448: Additional Unpacking Generalizations.

@item 
bpo-24096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24096}: Make warnings.warn_explicit more robust against mutation of the
warnings.filters list.

@item 
bpo-23996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23996}: Avoid a crash when a delegated generator raises an unnormalized
StopIteration exception.  Patch by Stefan Behnel.

@item 
bpo-23910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23910}: Optimize property() getter calls.  Patch by Joe Jevnik.

@item 
bpo-23911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23911}: Move path-based importlib bootstrap code to a separate frozen
module.

@item 
bpo-24192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24192}: Fix namespace package imports.

@item 
bpo-24022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24022}: Fix tokenizer crash when processing undecodable source code.

@item 
bpo-9951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9951}: Added a hex() method to bytes, bytearray, and memoryview.

@item 
bpo-22906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22906}: PEP 479: Change StopIteration handling inside generators.

@item 
bpo-24017@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24017}: PEP 492: Coroutines with async and await syntax.
@end itemize

@node Library<92>,IDLE<62>,Core and Builtins<93>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id752}@anchor{1b44}
@subsubsection Library



@itemize -

@item 
bpo-14373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14373}: Added C implementation of functools.lru_cache().  Based on
patches by Matt Joiner and Alexey Kachayev.

@item 
bpo-24230@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24230}: The tempfile module now accepts bytes for prefix, suffix and
dir parameters and returns bytes in such situations (matching the os
module APIs).

@item 
bpo-22189@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22189}: collections.UserString now supports __getnewargs__(),
__rmod__(), casefold(), format_map(), isprintable(), and maketrans().
Patch by Joe Jevnik.

@item 
bpo-24244@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24244}: Prevents termination when an invalid format string is
encountered on Windows in strftime.

@item 
bpo-23973@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23973}: PEP 484: Add the typing module.

@item 
bpo-23086@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23086}: The collections.abc.Sequence() abstract base class added
`start' and `stop' parameters to the index() mixin. Patch by Devin
Jeanpierre.

@item 
bpo-20035@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20035}: Replaced the @code{tkinter._fix} module used for setting up the
Tcl/Tk environment on Windows with a private function in the @code{_tkinter}
module that makes no permanent changes to the environment.

@item 
bpo-24257@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24257}: Fixed segmentation fault in sqlite3.Row constructor with faked
cursor type.

@item 
bpo-15836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15836}: assertRaises(), assertRaisesRegex(), assertWarns() and
assertWarnsRegex() assertments now check the type of the first argument to
prevent possible user error.  Based on patch by Daniel Wagner-Hall.

@item 
bpo-9858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9858}: Add missing method stubs to _io.RawIOBase.  Patch by Laura
Rupprecht.

@item 
bpo-22955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22955}: attrgetter, itemgetter and methodcaller objects in the operator
module now support pickling.  Added readable and evaluable repr for these
objects. Based on patch by Josh Rosenberg.

@item 
bpo-22107@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22107}: tempfile.gettempdir() and tempfile.mkdtemp() now try again when
a directory with the chosen name already exists on Windows as well as on
Unix. tempfile.mkstemp() now fails early if parent directory is not valid
(not exists or is a file) on Windows.

@item 
bpo-23780@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23780}: Improved error message in os.path.join() with single argument.

@item 
bpo-6598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6598}: Increased time precision and random number range in
email.utils.make_msgid() to strengthen the uniqueness of the message ID.

@item 
bpo-24091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24091}: Fixed various crashes in corner cases in C implementation of
ElementTree.

@item 
bpo-21931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21931}: msilib.FCICreate() now raises TypeError in the case of a bad
argument instead of a ValueError with a bogus FCI error number. Patch by
Jeffrey Armstrong.

@item 
bpo-13866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13866}: `quote_via' argument added to urllib.parse.urlencode.

@item 
bpo-20098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20098}: New mangle_from policy option for email, default True for
compat32, but False for all other policies.

@item 
bpo-24211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24211}: The email library now supports RFC 6532: it can generate
headers using utf-8 instead of encoded words.

@item 
bpo-16314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16314}: Added support for the LZMA compression in distutils.

@item 
bpo-21804@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21804}: poplib now supports RFC 6856 (UTF8).

@item 
bpo-18682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18682}: Optimized pprint functions for builtin scalar types.

@item 
bpo-22027@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22027}: smtplib now supports RFC 6531 (SMTPUTF8).

@item 
bpo-23488@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23488}: Random generator objects now consume 2x less memory on 64-bit.

@item 
bpo-1322@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1322}: platform.dist() and platform.linux_distribution() functions are
now deprecated.  Initial patch by Vajrasky Kok.

@item 
bpo-22486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22486}: Added the math.gcd() function.  The fractions.gcd() function
now is deprecated.  Based on patch by Mark Dickinson.

@item 
bpo-24064@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24064}: Property() docstrings are now writeable. (Patch by Berker
Peksag.)

@item 
bpo-22681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22681}: Added support for the koi8_t encoding.

@item 
bpo-22682@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22682}: Added support for the kz1048 encoding.

@item 
bpo-23796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23796}: peek and read1 methods of BufferedReader now raise ValueError
if they called on a closed object. Patch by John Hergenroeder.

@item 
bpo-21795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21795}: smtpd now supports the 8BITMIME extension whenever the new
`decode_data' constructor argument is set to False.

@item 
bpo-24155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24155}: optimize heapq.heapify() for better cache performance when
heapifying large lists.

@item 
bpo-21800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21800}: imaplib now supports RFC 5161 (enable), RFC 6855
(utf8/internationalized email) and automatically encodes non-ASCII
usernames and passwords to UTF8.

@item 
bpo-20274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20274}: When calling a _sqlite.Connection, it now complains if passed
any keyword arguments.  Previously it silently ignored them.

@item 
bpo-20274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20274}: Remove ignored and erroneous "kwargs" parameters from three
METH_VARARGS methods on _sqlite.Connection.

@item 
bpo-24134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24134}: assertRaises(), assertRaisesRegex(), assertWarns() and
assertWarnsRegex() checks now emits a deprecation warning when callable is
None or keyword arguments except msg is passed in the context manager
mode.

@item 
bpo-24018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24018}: Add a collections.abc.Generator abstract base class.
Contributed by Stefan Behnel.

@item 
bpo-23880@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23880}: Tkinter's getint() and getdouble() now support Tcl_Obj.
Tkinter's getdouble() now supports any numbers (in particular int).

@item 
bpo-22619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22619}: Added negative limit support in the traceback module. Based on
patch by Dmitry Kazakov.

@item 
bpo-24094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24094}: Fix possible crash in json.encode with poorly behaved dict
subclasses.

@item 
bpo-9246@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9246}: On POSIX, os.getcwd() now supports paths longer than 1025 bytes.
Patch written by William Orr.

@item 
bpo-17445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17445}: add difflib.diff_bytes() to support comparison of byte strings
(fixes a regression from Python 2).

@item 
bpo-23917@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23917}: Fall back to sequential compilation when ProcessPoolExecutor
doesn't exist. Patch by Claudiu Popa.

@item 
bpo-23008@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23008}: Fixed resolving attributes with boolean value is False in
pydoc.

@item 
Fix asyncio issue 235: LifoQueue and PriorityQueue's put didn't increment
unfinished tasks (this bug was introduced when JoinableQueue was merged
with Queue).

@item 
bpo-23908@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23908}: os functions now reject paths with embedded null character on
Windows instead of silently truncating them.

@item 
bpo-23728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23728}: binascii.crc_hqx() could return an integer outside of the range
0-0xffff for empty data.

@item 
bpo-23887@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23887}: urllib.error.HTTPError now has a proper repr() representation.
Patch by Berker Peksag.

@item 
asyncio: New event loop APIs: set_task_factory() and get_task_factory().

@item 
asyncio: async() function is deprecated in favour of ensure_future().

@item 
bpo-24178@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24178}: asyncio.Lock, Condition, Semaphore, and BoundedSemaphore
support new 'async with' syntax.  Contributed by Yury Selivanov.

@item 
bpo-24179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24179}: Support 'async for' for asyncio.StreamReader. Contributed by
Yury Selivanov.

@item 
bpo-24184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24184}: Add AsyncIterator and AsyncIterable ABCs to collections.abc.
Contributed by Yury Selivanov.

@item 
bpo-22547@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22547}: Implement informative __repr__ for inspect.BoundArguments.
Contributed by Yury Selivanov.

@item 
bpo-24190@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24190}: Implement inspect.BoundArgument.apply_defaults() method.
Contributed by Yury Selivanov.

@item 
bpo-20691@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20691}: Add 'follow_wrapped' argument to
inspect.Signature.from_callable() and inspect.signature(). Contributed by
Yury Selivanov.

@item 
bpo-24248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24248}: Deprecate inspect.Signature.from_function() and
inspect.Signature.from_builtin().

@item 
bpo-23898@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23898}: Fix inspect.classify_class_attrs() to support attributes with
overloaded __eq__ and __bool__.  Patch by Mike Bayer.

@item 
bpo-24298@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24298}: Fix inspect.signature() to correctly unwrap wrappers around
bound methods.
@end itemize

@node IDLE<62>,Tests<79>,Library<92>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id753}@anchor{1b45}
@subsubsection IDLE



@itemize -

@item 
bpo-23184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23184}: remove unused names and imports in idlelib. Initial patch by Al
Sweigart.
@end itemize

@node Tests<79>,Documentation<74>,IDLE<62>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id754}@anchor{1b46}
@subsubsection Tests



@itemize -

@item 
bpo-21520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21520}: test_zipfile no longer fails if the word 'bad' appears anywhere
in the name of the current directory.

@item 
bpo-9517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9517}: Move script_helper into the support package. Patch by Christie
Wilson.
@end itemize

@node Documentation<74>,Tools/Demos<46>,Tests<79>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id755}@anchor{1b47}
@subsubsection Documentation



@itemize -

@item 
bpo-22155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22155}: Add File Handlers subsection with createfilehandler to tkinter
doc.  Remove obsolete example from FAQ.  Patch by Martin Panter.

@item 
bpo-24029@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24029}: Document the name binding behavior for submodule imports.

@item 
bpo-24077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24077}: Fix typo in man page for -I command option: -s, not -S
@end itemize

@node Tools/Demos<46>,,Documentation<74>,Python 3 5 0 beta 1
@anchor{whatsnew/changelog id756}@anchor{1b48}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-24000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24000}: Improved Argument Clinic's mapping of converters to legacy
"format units". Updated the documentation to match.

@item 
bpo-24001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24001}: Argument Clinic converters now use accept=@{type@} instead of
types=@{'type'@} to specify the types the converter accepts.

@item 
bpo-23330@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23330}: h2py now supports arbitrary filenames in #include.

@item 
bpo-24031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24031}: make patchcheck now supports git checkouts, too.
@end itemize

@node Python 3 5 0 alpha 4,Python 3 5 0 alpha 3,Python 3 5 0 beta 1,Changelog
@anchor{whatsnew/changelog python-3-5-0-alpha-4}@anchor{1b49}
@subsection Python 3.5.0 alpha 4


`Release date: 2015-04-19'

@menu
* Core and Builtins: Core and Builtins<94>. 
* Library: Library<93>. 
* Build: Build<86>. 
* Tests: Tests<80>. 
* Tools/Demos: Tools/Demos<47>. 
* C API: C API<70>. 

@end menu

@node Core and Builtins<94>,Library<93>,,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id757}@anchor{1b4a}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-22980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22980}: Under Linux, GNU/KFreeBSD and the Hurd, C extensions now
include the architecture triplet in the extension name, to make it easy to
test builds for different ABIs in the same working tree.  Under OS X, the
extension name now includes 
@geindex Python Enhancement Proposals; PEP 3149
PEP 3149@footnote{https://peps.python.org/pep-3149/}-style information.

@item 
bpo-22631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22631}: Added Linux-specific socket constant CAN_RAW_FD_FRAMES. Patch
courtesy of Joe Jevnik.

@item 
bpo-23731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23731}: Implement 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}: removal of .pyo files.

@item 
bpo-23726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23726}: Don't enable GC for user subclasses of non-GC types that don't
add any new fields.  Patch by Eugene Toder.

@item 
bpo-23309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23309}: Avoid a deadlock at shutdown if a daemon thread is aborted
while it is holding a lock to a buffered I/O object, and the main thread
tries to use the same I/O object (typically stdout or stderr).  A fatal
error is emitted instead.

@item 
bpo-22977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22977}: Fixed formatting Windows error messages on Wine. Patch by
Martin Panter.

@item 
bpo-23466@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23466}: %c, %o, %x, and %X in bytes formatting now raise TypeError on
non-integer input.

@item 
bpo-24044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24044}: Fix possible null pointer dereference in list.sort in out of
memory conditions.

@item 
bpo-21354@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21354}: PyCFunction_New function is exposed by python DLL again.
@end itemize

@node Library<93>,Build<86>,Core and Builtins<94>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id758}@anchor{1b4b}
@subsubsection Library



@itemize -

@item 
bpo-23840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23840}: tokenize.open() now closes the temporary binary file on error
to fix a resource warning.

@item 
bpo-16914@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16914}: new debuglevel 2 in smtplib adds timestamps to debug output.

@item 
bpo-7159@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7159}: urllib.request now supports sending auth credentials
automatically after the first 401.  This enhancement is a superset of the
enhancement from bpo-19494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19494} and supersedes that change.

@item 
bpo-23703@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23703}: Fix a regression in urljoin() introduced in 901e4e52b20a. Patch
by Demian Brecht.

@item 
bpo-4254@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4254}: Adds _curses.update_lines_cols().  Patch by Arnon Yaari

@item 
bpo-19933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19933}: Provide default argument for ndigits in round. Patch by
Vajrasky Kok.

@item 
bpo-23193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23193}: Add a numeric_owner parameter to tarfile.TarFile.extract and
tarfile.TarFile.extractall. Patch by Michael Vogt and Eric Smith.

@item 
bpo-23342@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23342}: Add a subprocess.run() function than returns a CalledProcess
instance for a more consistent API than the existing call* functions.

@item 
bpo-21217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21217}: inspect.getsourcelines() now tries to compute the start and end
lines from the code object, fixing an issue when a lambda function is used
as decorator argument. Patch by Thomas Ballinger and Allison Kaptur.

@item 
bpo-24521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=24521}: Fix possible integer overflows in the pickle module.

@item 
bpo-22931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22931}: Allow '[' and ']' in cookie values.

@item 
The keywords attribute of functools.partial is now always a dictionary.

@item 
bpo-23811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23811}: Add missing newline to the PyCompileError error message. Patch
by Alex Shkop.

@item 
bpo-21116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21116}: Avoid blowing memory when allocating a multiprocessing shared
array that's larger than 50% of the available RAM.  Patch by Médéric
Boquien.

@item 
bpo-22982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22982}: Improve BOM handling when seeking to multiple positions of a
writable text file.

@item 
bpo-23464@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23464}: Removed deprecated asyncio JoinableQueue.

@item 
bpo-23529@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23529}: Limit the size of decompressed data when reading from GzipFile,
BZ2File or LZMAFile.  This defeats denial of service attacks using
compressed bombs (i.e. compressed payloads which decompress to a huge
size).  Patch by Martin Panter and Nikolaus Rath.

@item 
bpo-21859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21859}: Added Python implementation of io.FileIO.

@item 
bpo-23865@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23865}: close() methods in multiple modules now are idempotent and more
robust at shutdown. If they need to release multiple resources, all are
released even if errors occur.

@item 
bpo-23400@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23400}: Raise same exception on both Python 2 and 3 if sem_open is not
available. Patch by Davin Potts.

@item 
bpo-10838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10838}: The subprocess now module includes SubprocessError and
TimeoutError in its list of exported names for the users wild enough to
use @code{from subprocess import *}.

@item 
bpo-23411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23411}: Added DefragResult, ParseResult, SplitResult,
DefragResultBytes, ParseResultBytes, and SplitResultBytes to
urllib.parse.__all__. Patch by Martin Panter.

@item 
bpo-23881@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23881}: urllib.request.ftpwrapper constructor now closes the socket if
the FTP connection failed to fix a ResourceWarning.

@item 
bpo-23853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23853}: @ref{d95,,socket.socket.sendall()} does no more reset the socket
timeout each time data is sent successfully. The socket timeout is now the
maximum total duration to send all data.

@item 
bpo-22721@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22721}: An order of multiline pprint output of set or dict containing
orderable and non-orderable elements no longer depends on iteration order
of set or dict.

@item 
bpo-15133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15133}: _tkinter.tkapp.getboolean() now supports Tcl_Obj and always
returns bool. tkinter.BooleanVar now validates input values (accepted
bool, int, str, and Tcl_Obj).  tkinter.BooleanVar.get() now always returns
bool.

@item 
bpo-10590@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10590}: xml.sax.parseString() now supports string argument.

@item 
bpo-23338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23338}: Fixed formatting ctypes error messages on Cygwin. Patch by
Makoto Kato.

@item 
bpo-15582@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15582}: inspect.getdoc() now follows inheritance chains.

@item 
bpo-2175@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2175}: SAX parsers now support a character stream of InputSource
object.

@item 
bpo-16840@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16840}: Tkinter now supports 64-bit integers added in Tcl 8.4 and
arbitrary precision integers added in Tcl 8.5.

@item 
bpo-23834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23834}: Fix socket.sendto(), use the C Py_ssize_t type to store the
result of sendto() instead of the C int type.

@item 
bpo-23618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23618}: @ref{d90,,socket.socket.connect()} now waits until the connection
completes instead of raising @ref{d75,,InterruptedError} if the connection is
interrupted by signals, signal handlers don't raise an exception and the
socket is blocking or has a timeout. @ref{d90,,socket.socket.connect()} still
raise @ref{d75,,InterruptedError} for non-blocking sockets.

@item 
bpo-21526@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21526}: Tkinter now supports new boolean type in Tcl 8.5.

@item 
bpo-23836@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23836}: Fix the faulthandler module to handle reentrant calls to its
signal handlers.

@item 
bpo-23838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23838}: linecache now clears the cache and returns an empty result on
MemoryError.

@item 
bpo-10395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10395}: Added os.path.commonpath(). Implemented in posixpath and
ntpath. Based on patch by Rafik Draoui.

@item 
bpo-23611@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23611}: Serializing more "lookupable" objects (such as unbound methods
or nested classes) now are supported with pickle protocols < 4.

@item 
bpo-13583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13583}: sqlite3.Row now supports slice indexing.

@item 
bpo-18473@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18473}: Fixed 2to3 and 3to2 compatible pickle mappings.  Fixed
ambiguous reverse mappings.  Added many new mappings.  Import mapping is
no longer applied to modules already mapped with full name mapping.

@item 
bpo-23485@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23485}: select.select() is now retried automatically with the
recomputed timeout when interrupted by a signal, except if the signal
handler raises an exception. This change is part of the 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/}.

@item 
bpo-23752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23752}: When built from an existing file descriptor, io.FileIO() now
only calls fstat() once. Before fstat() was called twice, which was not
necessary.

@item 
bpo-23704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23704}: collections.deque() objects now support __add__, __mul__, and
__imul__().

@item 
bpo-23171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23171}: csv.Writer.writerow() now supports arbitrary iterables.

@item 
bpo-23745@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23745}: The new email header parser now handles duplicate MIME
parameter names without error, similar to how get_param behaves.

@item 
bpo-22117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22117}: Fix os.utime(), it now rounds the timestamp towards minus
infinity (-inf) instead of rounding towards zero.

@item 
bpo-23310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23310}: Fix MagicMock's initializer to work with __methods__, just like
configure_mock().  Patch by Kasia Jachim.
@end itemize

@node Build<86>,Tests<80>,Library<93>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id759}@anchor{1b4c}
@subsubsection Build



@itemize -

@item 
bpo-23817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23817}: FreeBSD now uses "1.0" in the SOVERSION as other operating
systems, instead of just "1".

@item 
bpo-23501@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23501}: Argument Clinic now generates code into separate files by
default.
@end itemize

@node Tests<80>,Tools/Demos<47>,Build<86>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id760}@anchor{1b4d}
@subsubsection Tests



@itemize -

@item 
bpo-23799@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23799}: Added test.support.start_threads() for running and cleaning up
multiple threads.

@item 
bpo-22390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22390}: test.regrtest now emits a warning if temporary files or
directories are left after running a test.
@end itemize

@node Tools/Demos<47>,C API<70>,Tests<80>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id761}@anchor{1b4e}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-18128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18128}: pygettext now uses standard +NNNN format in the
POT-Creation-Date header.

@item 
bpo-23935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23935}: Argument Clinic's understanding of format units accepting
bytes, bytearrays, and buffers is now consistent with both the
documentation and the implementation.

@item 
bpo-23944@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23944}: Argument Clinic now wraps long impl prototypes at column 78.

@item 
bpo-20586@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20586}: Argument Clinic now ensures that functions without docstrings
have signatures.

@item 
bpo-23492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23492}: Argument Clinic now generates argument parsing code with
PyArg_Parse instead of PyArg_ParseTuple if possible.

@item 
bpo-23500@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23500}: Argument Clinic is now smarter about generating the "#ifndef"
(empty) definition of the methoddef macro: it's only generated once, even
if Argument Clinic processes the same symbol multiple times, and it's
emitted at the end of all processing rather than immediately after the
first use.
@end itemize

@node C API<70>,,Tools/Demos<47>,Python 3 5 0 alpha 4
@anchor{whatsnew/changelog id762}@anchor{1b4f}
@subsubsection C API



@itemize -

@item 
bpo-23998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23998}: PyImport_ReInitLock() now checks for lock allocation error
@end itemize

@node Python 3 5 0 alpha 3,Python 3 5 0 alpha 2,Python 3 5 0 alpha 4,Changelog
@anchor{whatsnew/changelog python-3-5-0-alpha-3}@anchor{1b50}
@subsection Python 3.5.0 alpha 3


`Release date: 2015-03-28'

@menu
* Core and Builtins: Core and Builtins<95>. 
* Library: Library<94>. 
* Build: Build<87>. 
* Tests: Tests<81>. 
* Tools/Demos: Tools/Demos<48>. 

@end menu

@node Core and Builtins<95>,Library<94>,,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id763}@anchor{1b51}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-23573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23573}: Increased performance of string search operations (str.find,
str.index, str.count, the in operator, str.split, str.partition) with
arguments of different kinds (UCS1, UCS2, UCS4).

@item 
bpo-23753@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23753}: Python doesn't support anymore platforms without stat() or
fstat(), these functions are always required.

@item 
bpo-23681@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23681}: The -b option now affects comparisons of bytes with int.

@item 
bpo-23632@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23632}: Memoryviews now allow tuple indexing (including for
multi-dimensional memoryviews).

@item 
bpo-23192@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23192}: Fixed generator lambdas.  Patch by Bruno Cauet.

@item 
bpo-23629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23629}: Fix the default __sizeof__ implementation for variable-sized
objects.
@end itemize

@node Library<94>,Build<87>,Core and Builtins<95>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id764}@anchor{1b52}
@subsubsection Library



@itemize -

@item 
bpo-14260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14260}: The groupindex attribute of regular expression pattern object
now is non-modifiable mapping.

@item 
bpo-23792@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23792}: Ignore KeyboardInterrupt when the pydoc pager is active. This
mimics the behavior of the standard unix pagers, and prevents pipepager
from shutting down while the pager itself is still running.

@item 
bpo-23775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23775}: pprint() of OrderedDict now outputs the same representation as
repr().

@item 
bpo-23765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23765}: Removed IsBadStringPtr calls in ctypes

@item 
bpo-22364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22364}: Improved some re error messages using regex for hints.

@item 
bpo-23742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23742}: ntpath.expandvars() no longer loses unbalanced single quotes.

@item 
bpo-21717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21717}: The zipfile.ZipFile.open function now supports 'x' (exclusive
creation) mode.

@item 
bpo-21802@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21802}: The reader in BufferedRWPair now is closed even when closing
writer failed in BufferedRWPair.close().

@item 
bpo-23622@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23622}: Unknown escapes in regular expressions that consist of @code{'\'}
and ASCII letter now raise a deprecation warning and will be forbidden in
Python 3.6.

@item 
bpo-23671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23671}: string.Template now allows specifying the "self" parameter as a
keyword argument.  string.Formatter now allows specifying the "self" and
the "format_string" parameters as keyword arguments.

@item 
bpo-23502@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23502}: The pprint module now supports mapping proxies.

@item 
bpo-17530@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17530}: pprint now wraps long bytes objects and bytearrays.

@item 
bpo-22687@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22687}: Fixed some corner cases in breaking words in tetxtwrap. Got rid
of quadratic complexity in breaking long words.

@item 
bpo-4727@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4727}: The copy module now uses pickle protocol 4 (PEP 3154) and
supports copying of instances of classes whose __new__ method takes
keyword-only arguments.

@item 
bpo-23491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23491}: Added a zipapp module to support creating executable zip file
archives of Python code. Registered ".pyz" and ".pyzw" extensions on
Windows for these archives (PEP 441).

@item 
bpo-23657@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23657}: Avoid explicit checks for str in zipapp, adding support for
pathlib.Path objects as arguments.

@item 
bpo-23688@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23688}: Added support of arbitrary bytes-like objects and avoided
unnecessary copying of memoryview in gzip.GzipFile.write(). Original patch
by Wolfgang Maier.

@item 
bpo-23252@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23252}: Added support for writing ZIP files to unseekable streams.

@item 
bpo-23647@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23647}: Increase imaplib's MAXLINE to accommodate modern mailbox sizes.

@item 
bpo-23539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23539}: If body is None, http.client.HTTPConnection.request now sets
Content-Length to 0 for PUT, POST, and PATCH headers to avoid 411 errors
from some web servers.

@item 
bpo-22351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22351}: The nntplib.NNTP constructor no longer leaves the connection
and socket open until the garbage collector cleans them up.  Patch by
Martin Panter.

@item 
bpo-23704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23704}: collections.deque() objects now support methods for index(),
insert(), and copy().  This allows deques to be registered as a
MutableSequence and it improves their substitutability for lists.

@item 
bpo-23715@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23715}: @ref{d98,,signal.sigwaitinfo()} and @ref{d97,,signal.sigtimedwait()} are
now retried when interrupted by a signal not in the `sigset' parameter, if
the signal handler does not raise an exception. signal.sigtimedwait()
recomputes the timeout with a monotonic clock when it is retried.

@item 
bpo-23001@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23001}: Few functions in modules mmap, ossaudiodev, socket, ssl, and
codecs, that accepted only read-only bytes-like object now accept writable
bytes-like object too.

@item 
bpo-23646@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23646}: If time.sleep() is interrupted by a signal, the sleep is now
retried with the recomputed delay, except if the signal handler raises an
exception (PEP 475).

@item 
bpo-23136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23136}: _strptime now uniformly handles all days in week 0, including
Dec 30 of previous year.  Based on patch by Jim Carroll.

@item 
bpo-23700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23700}: Iterator of NamedTemporaryFile now keeps a reference to
NamedTemporaryFile instance.  Patch by Bohuslav Kabrda.

@item 
bpo-22903@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22903}: The fake test case created by unittest.loader when it fails
importing a test module is now picklable.

@item 
bpo-22181@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22181}: On Linux, os.urandom() now uses the new getrandom() syscall if
available, syscall introduced in the Linux kernel 3.17. It is more
reliable and more secure, because it avoids the need of a file descriptor
and waits until the kernel has enough entropy.

@item 
bpo-2211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2211}: Updated the implementation of the http.cookies.Morsel class.
Setting attributes key, value and coded_value directly now is deprecated.
update() and setdefault() now transform and check keys.  Comparing for
equality now takes into account attributes key, value and coded_value.
copy() now returns a Morsel, not a dict.  repr() now contains all
attributes. Optimized checking keys and quoting values.  Added new tests.
Original patch by Demian Brecht.

@item 
bpo-18983@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18983}: Allow selection of output units in timeit. Patch by Julian
Gindi.

@item 
bpo-23631@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23631}: Fix traceback.format_list when a traceback has been mutated.

@item 
bpo-23568@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23568}: Add rdivmod support to MagicMock() objects. Patch by Håkan
Lövdahl.

@item 
bpo-2052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2052}: Add charset parameter to HtmlDiff.make_file().

@item 
bpo-23668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23668}: Support os.truncate and os.ftruncate on Windows.

@item 
bpo-23138@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23138}: Fixed parsing cookies with absent keys or values in cookiejar.
Patch by Demian Brecht.

@item 
bpo-23051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23051}: multiprocessing.Pool methods imap() and imap_unordered() now
handle exceptions raised by an iterator.  Patch by Alon Diamant and Davin
Potts.

@item 
bpo-23581@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23581}: Add matmul support to MagicMock. Patch by Håkan Lövdahl.

@item 
bpo-23566@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23566}: enable(), register(), dump_traceback() and
dump_traceback_later() functions of faulthandler now accept file
descriptors. Patch by Wei Wu.

@item 
bpo-22928@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22928}: Disabled HTTP header injections in http.client. Original patch
by Demian Brecht.

@item 
bpo-23615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23615}: Modules bz2, tarfile and tokenize now can be reloaded with
imp.reload(). Patch by Thomas Kluyver.

@item 
bpo-23605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23605}: os.walk() now calls os.scandir() instead of os.listdir(). The
usage of os.scandir() reduces the number of calls to os.stat(). Initial
patch written by Ben Hoyt.
@end itemize

@node Build<87>,Tests<81>,Library<94>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id765}@anchor{1b53}
@subsubsection Build



@itemize -

@item 
bpo-23585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23585}: make patchcheck will ensure the interpreter is built.
@end itemize

@node Tests<81>,Tools/Demos<48>,Build<87>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id766}@anchor{1b54}
@subsubsection Tests



@itemize -

@item 
bpo-23583@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23583}: Added tests for standard IO streams in IDLE.

@item 
bpo-22289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22289}: Prevent test_urllib2net failures due to ftp connection timeout.
@end itemize

@node Tools/Demos<48>,,Tests<81>,Python 3 5 0 alpha 3
@anchor{whatsnew/changelog id767}@anchor{1b55}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-22826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22826}: The result of open() in Tools/freeze/bkfile.py is now better
compatible with regular files (in particular it now supports the context
management protocol).
@end itemize

@node Python 3 5 0 alpha 2,Python 3 5 0 alpha 1,Python 3 5 0 alpha 3,Changelog
@anchor{whatsnew/changelog python-3-5-0-alpha-2}@anchor{1b56}
@subsection Python 3.5.0 alpha 2


`Release date: 2015-03-09'

@menu
* Core and Builtins: Core and Builtins<96>. 
* Library: Library<95>. 
* Build: Build<88>. 
* C API: C API<71>. 
* Windows: Windows<73>. 

@end menu

@node Core and Builtins<96>,Library<95>,,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id768}@anchor{1b57}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-23571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23571}: PyObject_Call() and PyCFunction_Call() now raise a SystemError
if a function returns a result and raises an exception. The SystemError is
chained to the previous exception.
@end itemize

@node Library<95>,Build<88>,Core and Builtins<96>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id769}@anchor{1b58}
@subsubsection Library



@itemize -

@item 
bpo-22524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22524}: New os.scandir() function, part of the 
@geindex Python Enhancement Proposals; PEP 471
PEP 471@footnote{https://peps.python.org/pep-0471/}:
"os.scandir() function -- a better and faster directory iterator". Patch
written by Ben Hoyt.

@item 
bpo-23103@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23103}: Reduced the memory consumption of IPv4Address and IPv6Address.

@item 
bpo-21793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21793}: BaseHTTPRequestHandler again logs response code as numeric, not
as stringified enum.  Patch by Demian Brecht.

@item 
bpo-23476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23476}: In the ssl module, enable OpenSSL's X509_V_FLAG_TRUSTED_FIRST
flag on certificate stores when it is available.

@item 
bpo-23576@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23576}: Avoid stalling in SSL reads when EOF has been reached in the
SSL layer but the underlying connection hasn't been closed.

@item 
bpo-23504@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23504}: Added an __all__ to the types module.

@item 
bpo-23563@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23563}: Optimized utility functions in urllib.parse.

@item 
bpo-7830@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7830}: Flatten nested functools.partial.

@item 
bpo-20204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20204}: Added the __module__ attribute to _tkinter classes.

@item 
bpo-19980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19980}: Improved help() for non-recognized strings.  help('@w{'}) now shows
the help on str.  help('help') now shows the help on help(). Original
patch by Mark Lawrence.

@item 
bpo-23521@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23521}: Corrected pure python implementation of timedelta division.
Eliminated OverflowError from @code{timedelta * float} for some floats;
Corrected rounding in timedelta true division.

@item 
bpo-21619@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21619}: Popen objects no longer leave a zombie after exit in the with
statement if the pipe was broken.  Patch by Martin Panter.

@item 
bpo-22936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22936}: Make it possible to show local variables in tracebacks for both
the traceback module and unittest.

@item 
bpo-15955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15955}: Add an option to limit the output size in bz2.decompress().
Patch by Nikolaus Rath.

@item 
bpo-6639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6639}: Module-level turtle functions no longer raise TclError after
closing the window.

@item 
bpo-814253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=814253}: Group references and conditional group references now work in
lookbehind assertions in regular expressions. (See also: bpo-9179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9179})

@item 
bpo-23215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23215}: Multibyte codecs with custom error handlers that ignores errors
consumed too much memory and raised SystemError or MemoryError. Original
patch by Aleksi Torhamo.

@item 
bpo-5700@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5700}: io.FileIO() called flush() after closing the file. flush() was
not called in close() if closefd=False.

@item 
bpo-23374@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23374}: Fixed pydoc failure with non-ASCII files when stdout encoding
differs from file system encoding (e.g. on Mac OS).

@item 
bpo-23481@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23481}: Remove RC4 from the SSL module's default cipher list.

@item 
bpo-21548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21548}: Fix pydoc.synopsis() and pydoc.apropos() on modules with empty
docstrings.

@item 
bpo-22885@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22885}: Fixed arbitrary code execution vulnerability in the dbm.dumb
module. Original patch by Claudiu Popa.

@item 
bpo-23239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23239}: ssl.match_hostname() now supports matching of IP addresses.

@item 
bpo-23146@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23146}: Fix mishandling of absolute Windows paths with forward slashes
in pathlib.

@item 
bpo-23096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23096}: Pickle representation of floats with protocol 0 now is the same
for both Python and C implementations.

@item 
bpo-19105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19105}: pprint now more efficiently uses free space at the right.

@item 
bpo-14910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14910}: Add allow_abbrev parameter to argparse.ArgumentParser. Patch by
Jonathan Paugh, Steven Bethard, paul j3 and Daniel Eriksson.

@item 
bpo-21717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21717}: tarfile.open() now supports 'x' (exclusive creation) mode.

@item 
bpo-23344@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23344}: marshal.dumps() is now 20-25% faster on average.

@item 
bpo-20416@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20416}: marshal.dumps() with protocols 3 and 4 is now 40-50% faster on
average.

@item 
bpo-23421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23421}: Fixed compression in tarfile CLI.  Patch by wdv4758h.

@item 
bpo-23367@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23367}: Fix possible overflows in the unicodedata module.

@item 
bpo-23361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23361}: Fix possible overflow in Windows subprocess creation code.

@item 
logging.handlers.QueueListener now takes a respect_handler_level keyword
argument which, if set to True, will pass messages to handlers taking
handler levels into account.

@item 
bpo-19705@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19705}: turtledemo now has a visual sorting algorithm demo.  Original
patch from Jason Yeo.

@item 
bpo-23801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23801}: Fix issue where cgi.FieldStorage did not always ignore the
entire preamble to a multipart body.
@end itemize

@node Build<88>,C API<71>,Library<95>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id770}@anchor{1b59}
@subsubsection Build



@itemize -

@item 
bpo-23445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23445}: pydebug builds now use "gcc -Og" where possible, to make the
resulting executable faster.

@item 
bpo-23686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23686}: Update OS X 10.5 installer build to use OpenSSL 1.0.2a.
@end itemize

@node C API<71>,Windows<73>,Build<88>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id771}@anchor{1b5a}
@subsubsection C API



@itemize -

@item 
bpo-20204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20204}: Deprecation warning is now raised for builtin types without the
__module__ attribute.
@end itemize

@node Windows<73>,,C API<71>,Python 3 5 0 alpha 2
@anchor{whatsnew/changelog id772}@anchor{1b5b}
@subsubsection Windows



@itemize -

@item 
bpo-23465@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23465}: Implement 
@geindex Python Enhancement Proposals; PEP 486
PEP 486@footnote{https://peps.python.org/pep-0486/} - Make the Python Launcher aware of
virtual environments. Patch by Paul Moore.

@item 
bpo-23437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23437}: Make user scripts directory versioned on Windows. Patch by Paul
Moore.
@end itemize

@node Python 3 5 0 alpha 1,,Python 3 5 0 alpha 2,Changelog
@anchor{whatsnew/changelog python-3-5-0-alpha-1}@anchor{1b5c}
@subsection Python 3.5.0 alpha 1


`Release date: 2015-02-08'

@menu
* Core and Builtins: Core and Builtins<97>. 
* Library: Library<96>. 
* IDLE: IDLE<63>. 
* Build: Build<89>. 
* C API: C API<72>. 
* Documentation: Documentation<75>. 
* Tests: Tests<82>. 
* Tools/Demos: Tools/Demos<49>. 
* Windows: Windows<74>. 

@end menu

@node Core and Builtins<97>,Library<96>,,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id773}@anchor{1b5d}
@subsubsection Core and Builtins



@itemize -

@item 
bpo-23285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23285}: PEP 475 - EINTR handling.

@item 
bpo-22735@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22735}: Fix many edge cases (including crashes) involving custom mro()
implementations.

@item 
bpo-22896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22896}: Avoid using PyObject_AsCharBuffer(), PyObject_AsReadBuffer()
and PyObject_AsWriteBuffer().

@item 
bpo-21295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21295}: Revert some changes (bpo-16795@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16795}) to AST line numbers and
column offsets that constituted a regression.

@item 
bpo-22986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22986}: Allow changing an object's __class__ between a dynamic type and
static type in some cases.

@item 
bpo-15859@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15859}: PyUnicode_EncodeFSDefault(), PyUnicode_EncodeMBCS() and
PyUnicode_EncodeCodePage() now raise an exception if the object is not a
Unicode object. For PyUnicode_EncodeFSDefault(), it was already the case
on platforms other than Windows. Patch written by Campbell Barton.

@item 
bpo-21408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21408}: The default __ne__() now returns NotImplemented if __eq__()
returned NotImplemented.  Original patch by Martin Panter.

@item 
bpo-23321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23321}: Fixed a crash in str.decode() when error handler returned
replacement string longer than malformed input data.

@item 
bpo-22286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22286}: The "backslashreplace" error handlers now works with decoding
and translating.

@item 
bpo-23253@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23253}: Delay-load ShellExecute[AW] in os.startfile for reduced startup
overhead on Windows.

@item 
bpo-22038@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22038}: pyatomic.h now uses stdatomic.h or GCC built-in functions for
atomic memory access if available. Patch written by Vitor de Lima and
Gustavo Temple.

@item 
bpo-20284@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20284}: %-interpolation (aka printf) formatting added for bytes and
bytearray.

@item 
bpo-23048@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23048}: Fix jumping out of an infinite while loop in the pdb.

@item 
bpo-20335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20335}: bytes constructor now raises TypeError when encoding or errors
is specified with non-string argument.  Based on patch by Renaud Blanch.

@item 
bpo-22834@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22834}: If the current working directory ends up being set to a
non-existent directory then import will no longer raise FileNotFoundError.

@item 
bpo-22869@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22869}: Move the interpreter startup & shutdown code to a new dedicated
pylifecycle.c module

@item 
bpo-22847@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22847}: Improve method cache efficiency.

@item 
bpo-22335@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22335}: Fix crash when trying to enlarge a bytearray to 0x7fffffff
bytes on a 32-bit platform.

@item 
bpo-22653@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22653}: Fix an assertion failure in debug mode when doing a reentrant
dict insertion in debug mode.

@item 
bpo-22643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22643}: Fix integer overflow in Unicode case operations (upper, lower,
title, swapcase, casefold).

@item 
bpo-17636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17636}: Circular imports involving relative imports are now supported.

@item 
bpo-22604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22604}: Fix assertion error in debug mode when dividing a complex
number by (nan+0j).

@item 
bpo-21052@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21052}: Do not raise ImportWarning when sys.path_hooks or sys.meta_path
are set to None.

@item 
bpo-16518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16518}: Use 'bytes-like object required' in error messages that
previously used the far more cryptic "'x' does not support the buffer
protocol.

@item 
bpo-22470@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22470}: Fixed integer overflow issues in "backslashreplace",
"xmlcharrefreplace", and "surrogatepass" error handlers.

@item 
bpo-22540@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22540}: speed up @code{PyObject_IsInstance} and @code{PyObject_IsSubclass} in
the common case that the second argument has metaclass @code{type}.

@item 
bpo-18711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18711}: Add a new @code{PyErr_FormatV} function, similar to
@code{PyErr_Format} but accepting a @code{va_list} argument.

@item 
bpo-22520@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22520}: Fix overflow checking when generating the repr of a unicode
object.

@item 
bpo-22519@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22519}: Fix overflow checking in PyBytes_Repr.

@item 
bpo-22518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22518}: Fix integer overflow issues in latin-1 encoding.

@item 
bpo-16324@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16324}: _charset parameter of MIMEText now also accepts
email.charset.Charset instances. Initial patch by Claude Paroz.

@item 
bpo-1764286@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1764286}: Fix inspect.getsource() to support decorated functions. Patch
by Claudiu Popa.

@item 
bpo-18554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18554}: os.__all__ includes posix functions.

@item 
bpo-21391@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21391}: Use os.path.abspath in the shutil module.

@item 
bpo-11471@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11471}: avoid generating a JUMP_FORWARD instruction at the end of an
if-block if there is no else-clause.  Original patch by Eugene Toder.

@item 
bpo-22215@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22215}: Now ValueError is raised instead of TypeError when str or bytes
argument contains not permitted null character or byte.

@item 
bpo-22258@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22258}: Fix the internal function set_inheritable() on Illumos. This
platform exposes the function @code{ioctl(FIOCLEX)}, but calling it fails
with errno is ENOTTY: "Inappropriate ioctl for device". set_inheritable()
now falls back to the slower @code{fcntl()} (@code{F_GETFD} and then
@code{F_SETFD}).

@item 
bpo-21389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21389}: Displaying the __qualname__ of the underlying function in the
repr of a bound method.

@item 
bpo-22206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22206}: Using pthread, PyThread_create_key() now sets errno to ENOMEM
and returns -1 (error) on integer overflow.

@item 
bpo-20184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20184}: Argument Clinic based signature introspection added for 30 of
the builtin functions.

@item 
bpo-22116@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22116}: C functions and methods (of the 'builtin_function_or_method'
type) can now be weakref'ed.  Patch by Wei Wu.

@item 
bpo-22077@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22077}: Improve index error messages for bytearrays, bytes, lists, and
tuples by adding 'or slices'. Added ', not <typename>' for bytearrays.
Original patch by Claudiu Popa.

@item 
bpo-20179@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20179}: Apply Argument Clinic to bytes and bytearray. Patch by Tal
Einat.

@item 
bpo-22082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22082}: Clear interned strings in slotdefs.

@item 
Upgrade Unicode database to Unicode 7.0.0.

@item 
bpo-21897@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21897}: Fix a crash with the f_locals attribute with closure variables
when frame.clear() has been called.

@item 
bpo-21205@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21205}: Add a new @code{__qualname__} attribute to generator, the
qualified name, and use it in the representation of a generator
(@code{repr(gen)}). The default name of the generator (@code{__name__}
attribute) is now get from the function instead of the code. Use
@code{gen.gi_code.co_name} to get the name of the code.

@item 
bpo-21669@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21669}: With the aid of heuristics in SyntaxError.__init__, the parser
now attempts to generate more meaningful (or at least more search engine
friendly) error messages when "exec" and "print" are used as statements.

@item 
bpo-21642@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21642}: In the conditional if-else expression, allow an integer written
with no space between itself and the @code{else} keyword (e.g. @code{True if
42else False}) to be valid syntax.

@item 
bpo-21523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21523}: Fix over-pessimistic computation of the stack effect of some
opcodes in the compiler.  This also fixes a quadratic compilation time
issue noticeable when compiling code with a large number of "and" and "or"
operators.

@item 
bpo-21418@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21418}: Fix a crash in the builtin function super() when called without
argument and without current frame (ex: embedded Python).

@item 
bpo-21425@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21425}: Fix flushing of standard streams in the interactive
interpreter.

@item 
bpo-21435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21435}: In rare cases, when running finalizers on objects in cyclic
trash a bad pointer dereference could occur due to a subtle flaw in
internal iteration logic.

@item 
bpo-21377@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21377}: PyBytes_Concat() now tries to concatenate in-place when the
first argument has a reference count of 1.  Patch by Nikolaus Rath.

@item 
bpo-20355@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20355}: -W command line options now have higher priority than the
PYTHONWARNINGS environment variable.  Patch by Arfrever.

@item 
bpo-21274@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21274}: Define PATH_MAX for GNU/Hurd in Python/pythonrun.c.

@item 
bpo-20904@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20904}: Support setting FPU precision on m68k.

@item 
bpo-21209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21209}: Fix sending tuples to custom generator objects with the yield
from syntax.

@item 
bpo-21193@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21193}: pow(a, b, c) now raises ValueError rather than TypeError when b
is negative. Patch by Josh Rosenberg.

@item 
bpo-21176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21176}: PEP 465: Add the '@@' operator for matrix multiplication.

@item 
bpo-21134@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21134}: Fix segfault when str is called on an uninitialized
UnicodeEncodeError, UnicodeDecodeError, or UnicodeTranslateError object.

@item 
bpo-19537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19537}: Fix PyUnicode_DATA() alignment under m68k.  Patch by Andreas
Schwab.

@item 
bpo-20929@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20929}: Add a type cast to avoid shifting a negative number.

@item 
bpo-20731@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20731}: Properly position in source code files even if they are opened
in text mode. Patch by Serhiy Storchaka.

@item 
bpo-20637@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20637}: Key-sharing now also works for instance dictionaries of
subclasses.  Patch by Peter Ingebretson.

@item 
bpo-8297@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8297}: Attributes missing from modules now include the module name in
the error text.  Original patch by ysj.ray.

@item 
bpo-19995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19995}: %c, %o, %x, and %X now raise TypeError on non-integer input.

@item 
bpo-19655@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19655}: The ASDL parser - used by the build process to generate code
for managing the Python AST in C - was rewritten. The new parser is self
contained and does not require to carry long the spark.py parser-generator
library; spark.py was removed from the source base.

@item 
bpo-12546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12546}: Allow @code{\x00} to be used as a fill character when using str,
int, float, and complex __format__ methods.

@item 
bpo-20480@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20480}: Add ipaddress.reverse_pointer. Patch by Leon Weber.

@item 
bpo-13598@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13598}: Modify string.Formatter to support auto-numbering of
replacement fields. It now matches the behavior of str.format() in this
regard. Patches by Phil Elson and Ramchandra Apte.

@item 
bpo-8931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8931}: Make alternate formatting ('#') for type 'c' raise an exception.
In versions prior to 3.5, '#' with 'c' had no effect. Now specifying it is
an error. Patch by Torsten Landschoff.

@item 
bpo-23165@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23165}: Perform overflow checks before allocating memory in the
_Py_char2wchar function.
@end itemize

@node Library<96>,IDLE<63>,Core and Builtins<97>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id774}@anchor{1b5e}
@subsubsection Library



@itemize -

@item 
bpo-23399@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23399}: pyvenv creates relative symlinks where possible.

@item 
bpo-20289@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20289}: cgi.FieldStorage() now supports the context management
protocol.

@item 
bpo-13128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13128}: Print response headers for CONNECT requests when debuglevel >
0. Patch by Demian Brecht.

@item 
bpo-15381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15381}: Optimized io.BytesIO to make less allocations and copyings.

@item 
bpo-22818@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22818}: Splitting on a pattern that could match an empty string now
raises a warning.  Patterns that can only match empty strings are now
rejected.

@item 
bpo-23099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23099}: Closing io.BytesIO with exported buffer is rejected now to
prevent corrupting exported buffer.

@item 
bpo-23326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23326}: Removed __ne__ implementations.  Since fixing default __ne__
implementation in bpo-21408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21408} they are redundant.

@item 
bpo-23363@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23363}: Fix possible overflow in itertools.permutations.

@item 
bpo-23364@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23364}: Fix possible overflow in itertools.product.

@item 
bpo-23366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23366}: Fixed possible integer overflow in itertools.combinations.

@item 
bpo-23369@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23369}: Fixed possible integer overflow in
_json.encode_basestring_ascii.

@item 
bpo-23353@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23353}: Fix the exception handling of generators in
PyEval_EvalFrameEx(). At entry, save or swap the exception state even if
PyEval_EvalFrameEx() is called with throwflag=0. At exit, the exception
state is now always restored or swapped, not only if why is WHY_YIELD or
WHY_RETURN. Patch co-written with Antoine Pitrou.

@item 
bpo-14099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14099}: Restored support of writing ZIP files to tellable but
non-seekable streams.

@item 
bpo-14099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14099}: Writing to ZipFile and reading multiple ZipExtFiles is
threadsafe now.

@item 
bpo-19361@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19361}: JSON decoder now raises JSONDecodeError instead of ValueError.

@item 
bpo-18518@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18518}: timeit now rejects statements which can't be compiled outside a
function or a loop (e.g. "return" or "break").

@item 
bpo-23094@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23094}: Fixed readline with frames in Python implementation of pickle.

@item 
bpo-23268@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23268}: Fixed bugs in the comparison of ipaddress classes.

@item 
bpo-21408@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21408}: Removed incorrect implementations of __ne__() which didn't
returned NotImplemented if __eq__() returned NotImplemented.  The default
__ne__() now works correctly.

@item 
bpo-19996@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19996}: @code{email.feedparser.FeedParser} now handles (malformed)
headers with no key rather than assuming the body has started.

@item 
bpo-20188@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20188}: Support Application-Layer Protocol Negotiation (ALPN) in the
ssl module.

@item 
bpo-23133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23133}: Pickling of ipaddress objects now produces more compact and
portable representation.

@item 
bpo-23248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23248}: Update ssl error codes from latest OpenSSL git master.

@item 
bpo-23266@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23266}: Much faster implementation of ipaddress.collapse_addresses()
when there are many non-consecutive addresses.

@item 
bpo-23098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23098}: 64-bit dev_t is now supported in the os module.

@item 
bpo-21817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21817}: When an exception is raised in a task submitted to a
ProcessPoolExecutor, the remote traceback is now displayed in the parent
process.  Patch by Claudiu Popa.

@item 
bpo-15955@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15955}: Add an option to limit output size when decompressing LZMA
data.  Patch by Nikolaus Rath and Martin Panter.

@item 
bpo-23250@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23250}: In the http.cookies module, capitalize "HttpOnly" and "Secure"
as they are written in the standard.

@item 
bpo-23063@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23063}: In the distutils' check command, fix parsing of reST with code
or code-block directives.

@item 
bpo-23209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23209}: selectors.BaseSelector.get_key() now raises a RuntimeError if
the selector is closed. And selectors.BaseSelector.close() now clears its
internal reference to the selector mapping to break a reference cycle.
Initial patch written by Martin Richard. (See also: bpo-23225@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23225})

@item 
bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}: Provide a way to seed the linecache for a PEP-302 module
without actually loading the code.

@item 
bpo-17911@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17911}: Provide a new object API for traceback, including the ability
to not lookup lines at all until the traceback is actually rendered,
without any trace of the original objects being kept alive.

@item 
bpo-19777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19777}: Provide a home() classmethod on Path objects.  Contributed by
Victor Salgado and Mayank Tripathi.

@item 
bpo-23206@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23206}: Make @code{json.dumps(..., ensure_ascii=False)} as fast as the
default case of @code{ensure_ascii=True}.  Patch by Naoki Inada.

@item 
bpo-23185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23185}: Add math.inf and math.nan constants.

@item 
bpo-23186@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23186}: Add ssl.SSLObject.shared_ciphers() and
ssl.SSLSocket.shared_ciphers() to fetch the client's list ciphers sent at
handshake.

@item 
bpo-23143@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23143}: Remove compatibility with OpenSSLs older than 0.9.8.

@item 
bpo-23132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23132}: Improve performance and introspection support of comparison
methods created by functool.total_ordering.

@item 
bpo-19776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19776}: Add an expanduser() method on Path objects.

@item 
bpo-23112@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23112}: Fix SimpleHTTPServer to correctly carry the query string and
fragment when it redirects to add a trailing slash.

@item 
bpo-21793@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21793}: Added http.HTTPStatus enums (i.e. HTTPStatus.OK,
HTTPStatus.NOT_FOUND). Patch by Demian Brecht.

@item 
bpo-23093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23093}: In the io, module allow more operations to work on detached
streams.

@item 
bpo-23111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23111}: In the ftplib, make ssl.PROTOCOL_SSLv23 the default protocol
version.

@item 
bpo-22585@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22585}: On OpenBSD 5.6 and newer, os.urandom() now calls getentropy(),
instead of reading /dev/urandom, to get pseudo-random bytes.

@item 
bpo-19104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19104}: pprint now produces evaluable output for wrapped strings.

@item 
bpo-23071@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23071}: Added missing names to codecs.__all__.  Patch by Martin Panter.

@item 
bpo-22783@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22783}: Pickling now uses the NEWOBJ opcode instead of the NEWOBJ_EX
opcode if possible.

@item 
bpo-15513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15513}: Added a __sizeof__ implementation for pickle classes.

@item 
bpo-19858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19858}: pickletools.optimize() now aware of the MEMOIZE opcode, can
produce more compact result and no longer produces invalid output if input
data contains MEMOIZE opcodes together with PUT or BINPUT opcodes.

@item 
bpo-22095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22095}: Fixed HTTPConnection.set_tunnel with default port.  The port
value in the host header was set to "None".  Patch by Demian Brecht.

@item 
bpo-23016@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23016}: A warning no longer produces an AttributeError when the program
is run with pythonw.exe.

@item 
bpo-21775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21775}: shutil.copytree(): fix crash when copying to VFAT. An exception
handler assumed that OSError objects always have a 'winerror' attribute.
That is not the case, so the exception handler itself raised
AttributeError when run on Linux (and, presumably, any other non-Windows
OS). Patch by Greg Ward.

@item 
bpo-1218234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1218234}: Fix inspect.getsource() to load updated source of reloaded
module. Initial patch by Berker Peksag.

@item 
bpo-21740@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21740}: Support wrapped callables in doctest. Patch by Claudiu Popa.

@item 
bpo-23009@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23009}: Make sure selectors.EpollSelector.select() works when no FD is
registered.

@item 
bpo-22959@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22959}: In the constructor of http.client.HTTPSConnection, prefer the
context's check_hostname attribute over the `check_hostname' parameter.

@item 
bpo-22696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22696}: Add function @ref{a7d,,sys.is_finalizing()} to know about
interpreter shutdown.

@item 
bpo-16043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16043}: Add a default limit for the amount of data
xmlrpclib.gzip_decode will return. This resolves 
@geindex Common Vulnerabilities and Exposures; CVE 2013-1753
CVE 2013-1753@footnote{https://www.cve.org/CVERecord?id=CVE-2013-1753}.

@item 
bpo-14099@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14099}: ZipFile.open() no longer reopen the underlying file.  Objects
returned by ZipFile.open() can now operate independently of the ZipFile
even if the ZipFile was created by passing in a file-like object as the
first argument to the constructor.

@item 
bpo-22966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22966}: Fix __pycache__ pyc file name clobber when pyc_compile is asked
to compile a source file containing multiple dots in the source file name.

@item 
bpo-21971@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21971}: Update turtledemo doc and add module to the index.

@item 
bpo-21032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21032}: Fixed socket leak if HTTPConnection.getresponse() fails.
Original patch by Martin Panter.

@item 
bpo-22407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22407}: Deprecated the use of re.LOCALE flag with str patterns or
re.ASCII. It was newer worked.

@item 
bpo-22902@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22902}: The "ip" command is now used on Linux to determine MAC address
in uuid.getnode().  Pach by Bruno Cauet.

@item 
bpo-22960@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22960}: Add a context argument to xmlrpclib.ServerProxy constructor.

@item 
bpo-22389@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22389}: Add contextlib.redirect_stderr().

@item 
bpo-21356@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21356}: Make ssl.RAND_egd() optional to support LibreSSL. The
availability of the function is checked during the compilation. Patch
written by Bernard Spil.

@item 
bpo-22915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22915}: SAX parser now supports files opened with file descriptor or
bytes path.

@item 
bpo-22609@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22609}: Constructors and update methods of mapping classes in the
collections module now accept the self keyword argument.

@item 
bpo-22940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22940}: Add readline.append_history_file.

@item 
bpo-19676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19676}: Added the "namereplace" error handler.

@item 
bpo-22788@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22788}: Add `context' parameter to logging.handlers.HTTPHandler.

@item 
bpo-22921@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22921}: Allow SSLContext to take the `hostname' parameter even if
OpenSSL doesn't support SNI.

@item 
bpo-22894@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22894}: TestCase.subTest() would cause the test suite to be stopped
when in failfast mode, even in the absence of failures.

@item 
bpo-22796@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22796}: HTTP cookie parsing is now stricter, in order to protect
against potential injection attacks.

@item 
bpo-22370@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22370}: Windows detection in pathlib is now more robust.

@item 
bpo-22841@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22841}: Reject coroutines in asyncio add_signal_handler(). Patch by
Ludovic.Gasc.

@item 
bpo-19494@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19494}: Added urllib.request.HTTPBasicPriorAuthHandler. Patch by Matej
Cepl.

@item 
bpo-22578@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22578}: Added attributes to the re.error class.

@item 
bpo-22849@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22849}: Fix possible double free in the io.TextIOWrapper constructor.

@item 
bpo-12728@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12728}: Different Unicode characters having the same uppercase but
different lowercase are now matched in case-insensitive regular
expressions.

@item 
bpo-22821@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22821}: Fixed fcntl() with integer argument on 64-bit big-endian
platforms.

@item 
bpo-21650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21650}: Add an @code{--sort-keys} option to @code{json.tool} CLI.

@item 
bpo-22824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22824}: Updated reprlib output format for sets to use set literals.
Patch contributed by Berker Peksag.

@item 
bpo-22824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22824}: Updated reprlib output format for arrays to display empty
arrays without an unnecessary empty list.  Suggested by Serhiy Storchaka.

@item 
bpo-22406@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22406}: Fixed the uu_codec codec incorrectly ported to 3.x. Based on
patch by Martin Panter.

@item 
bpo-17293@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17293}: uuid.getnode() now determines MAC address on AIX using netstat.
Based on patch by Aivars Kalvāns.

@item 
bpo-22769@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22769}: Fixed ttk.Treeview.tag_has() when called without arguments.

@item 
bpo-22417@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22417}: Verify certificates by default in httplib (PEP 476).

@item 
bpo-22775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22775}: Fixed unpickling of http.cookies.SimpleCookie with protocol 2
and above. Patch by Tim Graham.

@item 
bpo-22776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22776}: Brought excluded code into the scope of a try block in
SysLogHandler.emit().

@item 
bpo-22665@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22665}: Add missing get_terminal_size and SameFileError to
shutil.__all__.

@item 
bpo-6623@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6623}: Remove deprecated Netrc class in the ftplib module. Patch by
Matt Chaput.

@item 
bpo-17381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17381}: Fixed handling of case-insensitive ranges in regular
expressions.

@item 
bpo-22410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22410}: Module level functions in the re module now cache compiled
locale-dependent regular expressions taking into account the locale.

@item 
bpo-22759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22759}: Query methods on pathlib.Path() (exists(), is_dir(), etc.) now
return False when the underlying stat call raises NotADirectoryError.

@item 
bpo-8876@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8876}: distutils now falls back to copying files when hard linking
doesn't work. This allows use with special filesystems such as VirtualBox
shared folders.

@item 
bpo-22217@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22217}: Implemented reprs of classes in the zipfile module.

@item 
bpo-22457@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22457}: Honour load_tests in the start_dir of discovery.

@item 
bpo-18216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18216}: gettext now raises an error when a .mo file has an unsupported
major version number.  Patch by Aaron Hill.

@item 
bpo-13918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13918}: Provide a locale.delocalize() function which can remove
locale-specific number formatting from a string representing a number,
without then converting it to a specific type.  Patch by Cédric Krier.

@item 
bpo-22676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22676}: Make the pickling of global objects which don't have a
__module__ attribute less slow.

@item 
bpo-18853@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18853}: Fixed ResourceWarning in shlex.__nain__.

@item 
bpo-9351@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9351}: Defaults set with set_defaults on an argparse subparser are no
longer ignored when also set on the parent parser.

@item 
bpo-7559@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7559}: unittest test loading ImportErrors are reported as import errors
with their import exception rather than as attribute errors after the
import has already failed.

@item 
bpo-19746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19746}: Make it possible to examine the errors from unittest discovery
without executing the test suite. The new @code{errors} attribute on
@code{TestLoader} exposes these non-fatal errors encountered during
discovery.

@item 
bpo-21991@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21991}: Make email.headerregistry's header 'params' attributes be
read-only (MappingProxyType).  Previously the dictionary was modifiable
but a new one was created on each access of the attribute.

@item 
bpo-22638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22638}: SSLv3 is now disabled throughout the standard library. It can
still be enabled by instantiating a SSLContext manually.

@item 
bpo-22641@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22641}: In asyncio, the default SSL context for client connections is
now created using ssl.create_default_context(), for stronger security.

@item 
bpo-17401@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17401}: Include closefd in io.FileIO repr.

@item 
bpo-21338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21338}: Add silent mode for compileall. quiet parameters of
compile_@{dir, file, path@} functions now have a multilevel value. Also, -q
option of the CLI now have a multilevel value. Patch by Thomas Kluyver.

@item 
bpo-20152@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20152}: Convert the array and cmath modules to Argument Clinic.

@item 
bpo-18643@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18643}: Add socket.socketpair() on Windows.

@item 
bpo-22435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22435}: Fix a file descriptor leak when socketserver bind fails.

@item 
bpo-13096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13096}: Fixed segfault in CTypes POINTER handling of large values.

@item 
bpo-11694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11694}: Raise ConversionError in xdrlib as documented.  Patch by Filip
Gruszczyński and Claudiu Popa.

@item 
bpo-19380@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19380}: Optimized parsing of regular expressions.

@item 
bpo-1519638@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=1519638}: Now unmatched groups are replaced with empty strings in
re.sub() and re.subn().

@item 
bpo-18615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18615}: sndhdr.what/whathdr now return a namedtuple.

@item 
bpo-22462@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22462}: Fix pyexpat's creation of a dummy frame to make it appear in
exception tracebacks.

@item 
bpo-21965@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21965}: Add support for in-memory SSL to the ssl module.  Patch by
Geert Jansen.

@item 
bpo-21173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21173}: Fix len() on a WeakKeyDictionary when .clear() was called with
an iterator alive.

@item 
bpo-11866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11866}: Eliminated race condition in the computation of names for new
threads.

@item 
bpo-21905@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21905}: Avoid RuntimeError in pickle.whichmodule() when sys.modules is
mutated while iterating.  Patch by Olivier Grisel.

@item 
bpo-11271@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11271}: concurrent.futures.Executor.map() now takes a `chunksize'
argument to allow batching of tasks in child processes and improve
performance of ProcessPoolExecutor.  Patch by Dan O'Reilly.

@item 
bpo-21883@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21883}: os.path.join() and os.path.relpath() now raise a TypeError with
more helpful error message for unsupported or mismatched types of
arguments.

@item 
bpo-22219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22219}: The zipfile module CLI now adds entries for directories
(including empty directories) in ZIP file.

@item 
bpo-22449@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22449}: In the ssl.SSLContext.load_default_certs, consult the
environmental variables SSL_CERT_DIR and SSL_CERT_FILE on Windows.

@item 
bpo-22508@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22508}: The email.__version__ variable has been removed; the email code
is no longer shipped separately from the stdlib, and __version__ hasn't
been updated in several releases.

@item 
bpo-20076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20076}: Added non derived UTF-8 aliases to locale aliases table.

@item 
bpo-20079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20079}: Added locales supported in glibc 2.18 to locale alias table.

@item 
bpo-20218@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20218}: Added convenience methods read_text/write_text and read_bytes/
write_bytes to pathlib.Path objects.

@item 
bpo-22396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22396}: On 32-bit AIX platform, don't expose os.posix_fadvise() nor
os.posix_fallocate() because their prototypes in system headers are wrong.

@item 
bpo-22517@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22517}: When an io.BufferedRWPair object is deallocated, clear its
weakrefs.

@item 
bpo-22437@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22437}: Number of capturing groups in regular expression is no longer
limited by 100.

@item 
bpo-17442@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17442}: InteractiveInterpreter now displays the full chained traceback
in its showtraceback method, to match the built in interactive
interpreter.

@item 
bpo-23392@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23392}: Added tests for marshal C API that works with FILE*.

@item 
bpo-10510@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10510}: distutils register and upload methods now use HTML standards
compliant CRLF line endings.

@item 
bpo-9850@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9850}: Fixed macpath.join() for empty first component.  Patch by Oleg
Oshmyan.

@item 
bpo-5309@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5309}: distutils' build and build_ext commands now accept a @code{-j}
option to enable parallel building of extension modules.

@item 
bpo-22448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22448}: Improve canceled timer handles cleanup to prevent unbound
memory usage. Patch by Joshua Moore-Oliva.

@item 
bpo-22427@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22427}: TemporaryDirectory no longer attempts to clean up twice when
used in the with statement in generator.

@item 
bpo-22362@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22362}: Forbidden ambiguous octal escapes out of range 0-0o377 in
regular expressions.

@item 
bpo-20912@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20912}: Now directories added to ZIP file have correct Unix and MS-DOS
directory attributes.

@item 
bpo-21866@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21866}: ZipFile.close() no longer writes ZIP64 central directory
records if allowZip64 is false.

@item 
bpo-22278@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22278}: Fix urljoin problem with relative urls, a regression observed
after changes to issue22118 were submitted.

@item 
bpo-22415@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22415}: Fixed debugging output of the GROUPREF_EXISTS opcode in the re
module. Removed trailing spaces in debugging output.

@item 
bpo-22423@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22423}: Unhandled exception in thread no longer causes unhandled
AttributeError when sys.stderr is None.

@item 
bpo-21332@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21332}: Ensure that @code{bufsize=1} in subprocess.Popen() selects line
buffering, rather than block buffering.  Patch by Akira Li.

@item 
bpo-21091@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21091}: Fix API bug: email.message.EmailMessage.is_attachment is now a
method.

@item 
bpo-21079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21079}: Fix email.message.EmailMessage.is_attachment to return the
correct result when the header has parameters as well as a value.

@item 
bpo-22247@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22247}: Add NNTPError to nntplib.__all__.

@item 
bpo-22366@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22366}: urllib.request.urlopen will accept a context object
(SSLContext) as an argument which will then be used for HTTPS connection.
Patch by Alex Gaynor.

@item 
bpo-4180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4180}: The warnings registries are now reset when the filters are
modified.

@item 
bpo-22419@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22419}: Limit the length of incoming HTTP request in wsgiref server to
65536 bytes and send a 414 error code for higher lengths. Patch
contributed by Devin Cook.

@item 
Lax cookie parsing in http.cookies could be a security issue when combined
with non-standard cookie handling in some web browsers.  Reported by
Sergey Bobrov.

@item 
bpo-20537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20537}: logging methods now accept an exception instance as well as a
Boolean value or exception tuple. Thanks to Yury Selivanov for the patch.

@item 
bpo-22384@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22384}: An exception in Tkinter callback no longer crashes the program
when it is run with pythonw.exe.

@item 
bpo-22168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22168}: Prevent turtle AttributeError with non-default Canvas on OS X.

@item 
bpo-21147@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21147}: sqlite3 now raises an exception if the request contains a null
character instead of truncating it.  Based on patch by Victor Stinner.

@item 
bpo-13968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13968}: The glob module now supports recursive search in subdirectories
using the @code{**} pattern.

@item 
bpo-21951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21951}: Fixed a crash in Tkinter on AIX when called Tcl command with
empty string or tuple argument.

@item 
bpo-21951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21951}: Tkinter now most likely raises MemoryError instead of crash if
the memory allocation fails.

@item 
bpo-22338@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22338}: Fix a crash in the json module on memory allocation failure.

@item 
bpo-12410@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12410}: imaplib.IMAP4 now supports the context management protocol.
Original patch by Tarek Ziadé.

@item 
bpo-21270@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21270}: We now override tuple methods in mock.call objects so that they
can be used as normal call attributes.

@item 
bpo-16662@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16662}: @code{load_tests()} is now unconditionally run when it is present
in a package's @code{__init__.py}.  @code{TestLoader.loadTestsFromModule()}
still accepts use_load_tests, but it is deprecated and ignored.  A new
keyword-only attribute @code{pattern} is added and documented.  Patch given
by Robert Collins, tweaked by Barry Warsaw.

@item 
bpo-22226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22226}: First letter no longer is stripped from the "status" key in the
result of Treeview.heading().

@item 
bpo-19524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19524}: Fixed resource leak in the HTTP connection when an invalid
response is received.  Patch by Martin Panter.

@item 
bpo-20421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20421}: Add a .version() method to SSL sockets exposing the actual
protocol version in use.

@item 
bpo-19546@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19546}: configparser exceptions no longer expose implementation
details. Chained KeyErrors are removed, which leads to cleaner tracebacks.
Patch by Claudiu Popa.

@item 
bpo-22051@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22051}: turtledemo no longer reloads examples to re-run them.
Initialization of variables and gui setup should be done in main(), which
is called each time a demo is run, but not on import.

@item 
bpo-21933@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21933}: Turtledemo users can change the code font size with a menu
selection or control(command) '-' or '+' or control-mousewheel. Original
patch by Lita Cho.

@item 
bpo-21597@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21597}: The separator between the turtledemo text pane and the drawing
canvas can now be grabbed and dragged with a mouse.  The code text pane
can be widened to easily view or copy the full width of the text.  The
canvas can be widened on small screens.  Original patches by Jan Kanis and
Lita Cho.

@item 
bpo-18132@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18132}: Turtledemo buttons no longer disappear when the window is
shrunk.  Original patches by Jan Kanis and Lita Cho.

@item 
bpo-22043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22043}: time.monotonic() is now always available.
@code{threading.Lock.acquire()}, @code{threading.RLock.acquire()} and socket
operations now use a monotonic clock, instead of the system clock, when a
timeout is used.

@item 
bpo-21527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21527}: Add a default number of workers to ThreadPoolExecutor equal to
5 times the number of CPUs.  Patch by Claudiu Popa.

@item 
bpo-22216@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22216}: smtplib now resets its state more completely after a quit.  The
most obvious consequence of the previous behavior was a STARTTLS failure
during a connect/starttls/quit/connect/starttls sequence.

@item 
bpo-22098@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22098}: ctypes' BigEndianStructure and LittleEndianStructure now define
an empty __slots__ so that subclasses don't always get an instance dict.
Patch by Claudiu Popa.

@item 
bpo-22185@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22185}: Fix an occasional RuntimeError in threading.Condition.wait()
caused by mutation of the waiters queue without holding the lock.  Patch
by Doug Zongker.

@item 
bpo-22287@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22287}: On UNIX, _PyTime_gettimeofday() now uses
clock_gettime(CLOCK_REALTIME) if available. As a side effect, Python now
depends on the librt library on Solaris and on Linux (only with glibc
older than 2.17).

@item 
bpo-22182@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22182}: Use e.args to unpack exceptions correctly in
distutils.file_util.move_file. Patch by Claudiu Popa.

@item 
The webbrowser module now uses subprocess's start_new_session=True rather
than a potentially risky preexec_fn=os.setsid call.

@item 
bpo-22042@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22042}: signal.set_wakeup_fd(fd) now raises an exception if the file
descriptor is in blocking mode.

@item 
bpo-16808@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16808}: inspect.stack() now returns a named tuple instead of a tuple.
Patch by Daniel Shahaf.

@item 
bpo-22236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22236}: Fixed Tkinter images copying operations in NoDefaultRoot mode.

@item 
bpo-2527@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=2527}: Add a `globals' argument to timeit functions, in order to
override the globals namespace in which the timed code is executed. Patch
by Ben Roberts.

@item 
bpo-22118@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22118}: Switch urllib.parse to use RFC 3986 semantics for the
resolution of relative URLs, rather than RFCs 1808 and 2396. Patch by
Demian Brecht.

@item 
bpo-21549@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21549}: Added the "members" parameter to TarFile.list().

@item 
bpo-19628@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19628}: Allow compileall recursion depth to be specified with a -r
option.

@item 
bpo-15696@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15696}: Add a __sizeof__ implementation for mmap objects on Windows.

@item 
bpo-22068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22068}: Avoided reference loops with Variables and Fonts in Tkinter.

@item 
bpo-22165@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22165}: SimpleHTTPRequestHandler now supports undecodable file names.

@item 
bpo-15381@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15381}: Optimized line reading in io.BytesIO.

@item 
bpo-8797@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=8797}: Raise HTTPError on failed Basic Authentication immediately.
Initial patch by Sam Bull.

@item 
bpo-20729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20729}: Restored the use of lazy iterkeys()/itervalues()/iteritems() in
the mailbox module.

@item 
bpo-21448@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21448}: Changed FeedParser feed() to avoid `O'(`n'@w{^2})
behavior when parsing long line. Original patch by Raymond Hettinger.

@item 
bpo-22184@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22184}: The functools LRU Cache decorator factory now gives an earlier
and clearer error message when the user forgets the required parameters.

@item 
bpo-17923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17923}: glob() patterns ending with a slash no longer match non-dirs on
AIX.  Based on patch by Delhallt.

@item 
bpo-21725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21725}: Added support for RFC 6531 (SMTPUTF8) in smtpd.

@item 
bpo-22176@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22176}: Update the ctypes module's libffi to v3.1.  This release adds
support for the Linux AArch64 and POWERPC ELF ABIv2 little endian
architectures.

@item 
bpo-5411@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5411}: Added support for the "xztar" format in the shutil module.

@item 
bpo-21121@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21121}: Don't force 3rd party C extensions to be built with
-Werror=declaration-after-statement.

@item 
bpo-21975@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21975}: Fixed crash when using uninitialized sqlite3.Row (in particular
when unpickling pickled sqlite3.Row).  sqlite3.Row is now initialized in
the __new__() method.

@item 
bpo-20170@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20170}: Convert posixmodule to use Argument Clinic.

@item 
bpo-21539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21539}: Add an `exists_ok' argument to @code{Pathlib.mkdir()} to mimic
@code{mkdir -p} and @code{os.makedirs()} functionality.  When true, ignore
@code{FileExistsErrors}. Patch by Berker Peksag.

@item 
bpo-22127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22127}: Bypass IDNA for pure-ASCII host names in the socket module (in
particular for numeric IPs).

@item 
bpo-21047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21047}: set the default value for the `convert_charrefs' argument of
HTMLParser to True.  Patch by Berker Peksag.

@item 
Add an __all__ to html.entities.

@item 
bpo-15114@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15114}: the strict mode and argument of HTMLParser, HTMLParser.error,
and the HTMLParserError exception have been removed.

@item 
bpo-22085@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22085}: Dropped support of Tk 8.3 in Tkinter.

@item 
bpo-21580@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21580}: Now Tkinter correctly handles bytes arguments passed to Tk. In
particular this allows initializing images from binary data.

@item 
bpo-22003@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22003}: When initialized from a bytes object, io.BytesIO() now defers
making a copy until it is mutated, improving performance and memory use on
some use cases. Patch by David Wilson.

@item 
bpo-22018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22018}: On Windows, signal.set_wakeup_fd() now also supports sockets. A
side effect is that Python depends to the WinSock library.

@item 
bpo-22054@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22054}: Add os.get_blocking() and os.set_blocking() functions to get
and set the blocking mode of a file descriptor (False if the O_NONBLOCK
flag is set, True otherwise). These functions are not available on
Windows.

@item 
bpo-17172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17172}: Make turtledemo start as active on OS X even when run with
subprocess. Patch by Lita Cho.

@item 
bpo-21704@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21704}: Fix build error for _multiprocessing when semaphores are not
available. Patch by Arfrever Frehtes Taifersar Arahesis.

@item 
bpo-20173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20173}: Convert sha1, sha256, sha512 and md5 to ArgumentClinic. Patch
by Vajrasky Kok.

@item 
Fix repr(_socket.socket) on Windows 64-bit: don't fail with OverflowError
on closed socket. repr(socket.socket) already works fine.

@item 
bpo-22033@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22033}: Reprs of most Python implemented classes now contain actual
class name instead of hardcoded one.

@item 
bpo-21947@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21947}: The dis module can now disassemble generator-iterator objects
based on their gi_code attribute. Patch by Clement Rouault.

@item 
bpo-16133@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16133}: The asynchat.async_chat.handle_read() method now ignores
BlockingIOError exceptions.

@item 
bpo-22044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22044}: Fixed premature DECREF in call_tzinfo_method. Patch by Tom
Flanagan.

@item 
bpo-19884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19884}: readline: Disable the meta modifier key if stdout is not a
terminal to not write the ANSI sequence @code{"\033[1034h"} into stdout. This
sequence is used on some terminal (ex: TERM=xterm-256color") to enable
support of 8 bit characters.

@item 
bpo-4350@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4350}: Removed a number of out-of-dated and non-working for a long time
Tkinter methods.

@item 
bpo-6167@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6167}: Scrollbar.activate() now returns the name of active element if
the argument is not specified.  Scrollbar.set() now always accepts only 2
arguments.

@item 
bpo-15275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15275}: Clean up and speed up the ntpath module.

@item 
bpo-21888@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21888}: plistlib's load() and loads() now work if the fmt parameter is
specified.

@item 
bpo-22032@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22032}: __qualname__ instead of __name__ is now always used to format
fully qualified class names of Python implemented classes.

@item 
bpo-22031@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22031}: Reprs now always use hexadecimal format with the "0x" prefix
when contain an id in form " at 0x...".

@item 
bpo-22018@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22018}: signal.set_wakeup_fd() now raises an OSError instead of a
ValueError on @code{fstat()} failure.

@item 
bpo-21044@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21044}: tarfile.open() now handles fileobj with an integer 'name'
attribute.  Based on patch by Antoine Pietri.

@item 
bpo-21966@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21966}: Respect -q command-line option when code module is ran.

@item 
bpo-19076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19076}: Don't pass the redundant 'file' argument to self.error().

@item 
bpo-16382@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16382}: Improve exception message of warnings.warn() for bad category.
Initial patch by Phil Elson.

@item 
bpo-21932@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21932}: os.read() now uses a @ref{a4e,,Py_ssize_t()} type instead of
int for the size to support reading more than 2 GB at once. On
Windows, the size is truncated to INT_MAX. As any call to os.read(), the
OS may read less bytes than the number of requested bytes.

@item 
bpo-21942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21942}: Fixed source file viewing in pydoc's server mode on Windows.

@item 
bpo-11259@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11259}: asynchat.async_chat().set_terminator() now raises a ValueError
if the number of received bytes is negative.

@item 
bpo-12523@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12523}: asynchat.async_chat.push() now raises a TypeError if it doesn't
get a bytes string

@item 
bpo-21707@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21707}: Add missing kwonlyargcount argument to
ModuleFinder.replace_paths_in_code().

@item 
bpo-20639@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20639}: calling Path.with_suffix('@w{'}) allows removing the suffix again.
Patch by July Tikhonov.

@item 
bpo-21714@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21714}: Disallow the construction of invalid paths using
Path.with_name().  Original patch by Antony Lee.

@item 
bpo-15014@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15014}: Added 'auth' method to smtplib to make implementing auth
mechanisms simpler, and used it internally in the login method.

@item 
bpo-21151@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21151}: Fixed a segfault in the winreg module when @code{None} is passed
as a @code{REG_BINARY} value to SetValueEx.  Patch by John Ehresman.

@item 
bpo-21090@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21090}: io.FileIO.readall() does not ignore I/O errors anymore. Before,
it ignored I/O errors if at least the first C call read() succeed.

@item 
bpo-5800@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5800}: headers parameter of wsgiref.headers.Headers is now optional.
Initial patch by Pablo Torres Navarrete and SilentGhost.

@item 
bpo-21781@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21781}: ssl.RAND_add() now supports strings longer than 2 GB.

@item 
bpo-21679@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21679}: Prevent extraneous fstat() calls during open().  Patch by
Bohuslav Kabrda.

@item 
bpo-21863@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21863}: cProfile now displays the module name of C extension functions,
in addition to their own name.

@item 
bpo-11453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11453}: asyncore: emit a ResourceWarning when an unclosed file_wrapper
object is destroyed. The destructor now closes the file if needed. The
close() method can now be called twice: the second call does nothing.

@item 
bpo-21858@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21858}: Better handling of Python exceptions in the sqlite3 module.

@item 
bpo-21476@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21476}: Make sure the email.parser.BytesParser TextIOWrapper is
discarded after parsing, so the input file isn't unexpectedly closed.

@item 
bpo-20295@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20295}: imghdr now recognizes OpenEXR format images.

@item 
bpo-21729@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21729}: Used the "with" statement in the dbm.dumb module to ensure
files closing. Patch by Claudiu Popa.

@item 
bpo-21491@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21491}: socketserver: Fix a race condition in child processes reaping.

@item 
bpo-21719@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21719}: Added the @code{st_file_attributes} field to os.stat_result on
Windows.

@item 
bpo-21832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21832}: Require named tuple inputs to be exact strings.

@item 
bpo-21722@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21722}: The distutils "upload" command now exits with a non-zero return
code when uploading fails.  Patch by Martin Dengler.

@item 
bpo-21723@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21723}: asyncio.Queue: support any type of number (ex: float) for the
maximum size. Patch written by Vajrasky Kok.

@item 
bpo-21711@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21711}: support for "site-python" directories has now been removed from
the site module (it was deprecated in 3.4).

@item 
bpo-17552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17552}: new socket.sendfile() method allowing a file to be sent over a
socket by using high-performance os.sendfile() on UNIX. Patch by Giampaolo
Rodola'.

@item 
bpo-18039@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18039}: dbm.dump.open() now always creates a new database when the flag
has the value 'n'.  Patch by Claudiu Popa.

@item 
bpo-21326@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21326}: Add a new is_closed() method to asyncio.BaseEventLoop.
run_forever() and run_until_complete() methods of asyncio.BaseEventLoop
now raise an exception if the event loop was closed.

@item 
bpo-21766@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21766}: Prevent a security hole in CGIHTTPServer by URL unquoting paths
before checking for a CGI script at that path.

@item 
bpo-21310@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21310}: Fixed possible resource leak in failed open().

@item 
bpo-21256@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21256}: Printout of keyword args should be in deterministic order in a
mock function call. This will help to write better doctests.

@item 
bpo-21677@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21677}: Fixed chaining nonnormalized exceptions in io close() methods.

@item 
bpo-11709@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11709}: Fix the pydoc.help function to not fail when sys.stdin is not a
valid file.

@item 
bpo-21515@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21515}: tempfile.TemporaryFile now uses os.O_TMPFILE flag is available.

@item 
bpo-13223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13223}: Fix pydoc.writedoc so that the HTML documentation for methods
that use 'self' in the example code is generated correctly.

@item 
bpo-21463@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21463}: In urllib.request, fix pruning of the FTP cache.

@item 
bpo-21618@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21618}: The subprocess module could fail to close open fds that were
inherited by the calling process and already higher than POSIX resource
limits would otherwise allow.  On systems with a functioning /proc/self/fd
or /dev/fd interface the max is now ignored and all fds are closed.

@item 
bpo-20383@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20383}: Introduce importlib.util.module_from_spec() as the preferred
way to create a new module.

@item 
bpo-21552@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21552}: Fixed possible integer overflow of too long string lengths in
the tkinter module on 64-bit platforms.

@item 
bpo-14315@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14315}: The zipfile module now ignores extra fields in the central
directory that are too short to be parsed instead of letting a
struct.unpack error bubble up as this "bad data" appears in many real
world zip files in the wild and is ignored by other zip tools.

@item 
bpo-13742@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13742}: Added "key" and "reverse" parameters to heapq.merge(). (First
draft of patch contributed by Simon Sapin.)

@item 
bpo-21402@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21402}: tkinter.ttk now works when default root window is not set.

@item 
bpo-3015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3015}: @code{_tkinter.create()} now creates @code{tkapp} object with
@code{wantobjects=1} by default.

@item 
bpo-10203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10203}: sqlite3.Row now truly supports sequence protocol.  In
particular it supports reverse() and negative indices.  Original patch by
Claudiu Popa.

@item 
bpo-18807@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18807}: If copying (no symlinks) specified for a venv, then the python
interpreter aliases (python, python3) are now created by copying rather
than symlinking.

@item 
bpo-20197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20197}: Added support for the WebP image type in the imghdr module.
Patch by Fabrice Aneche and Claudiu Popa.

@item 
bpo-21513@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21513}: Speedup some properties of IP addresses (IPv4Address,
IPv6Address) such as .is_private or .is_multicast.

@item 
bpo-21137@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21137}: Improve the repr for threading.Lock() and its variants by
showing the "locked" or "unlocked" status.  Patch by Berker Peksag.

@item 
bpo-21538@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21538}: The plistlib module now supports loading of binary plist files
when reference or offset size is not a power of two.

@item 
bpo-21455@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21455}: Add a default backlog to socket.listen().

@item 
bpo-21525@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21525}: Most Tkinter methods which accepted tuples now accept lists
too.

@item 
bpo-22166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22166}: With the assistance of a new internal _codecs._forget_codec
helping function, test_codecs now clears the encoding caches to avoid the
appearance of a reference leak

@item 
bpo-22236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22236}: Tkinter tests now don't reuse default root window.  New root
window is created for every test class.

@item 
bpo-10744@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10744}: Fix 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} format strings on ctypes objects with a
nontrivial shape.

@item 
bpo-20826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20826}: Optimize ipaddress.collapse_addresses().

@item 
bpo-21487@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21487}: Optimize ipaddress.summarize_address_range() and
ipaddress.@{IPv4Network,IPv6Network@}.subnets().

@item 
bpo-21486@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21486}: Optimize parsing of netmasks in ipaddress.IPv4Network and
ipaddress.IPv6Network.

@item 
bpo-13916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13916}: Disallowed the surrogatepass error handler for non UTF-*
encodings.

@item 
bpo-20998@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20998}: Fixed re.fullmatch() of repeated single character pattern with
ignore case. Original patch by Matthew Barnett.

@item 
bpo-21075@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21075}: fileinput.FileInput now reads bytes from standard stream if
binary mode is specified.  Patch by Sam Kimbrel.

@item 
bpo-19775@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19775}: Add a samefile() method to pathlib Path objects.  Initial patch
by Vajrasky Kok.

@item 
bpo-21226@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21226}: Set up modules properly in PyImport_ExecCodeModuleObject (and
friends).

@item 
bpo-21398@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21398}: Fix a unicode error in the pydoc pager when the documentation
contains characters not encodable to the stdout encoding.

@item 
bpo-16531@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16531}: ipaddress.IPv4Network and ipaddress.IPv6Network now accept an
(address, netmask) tuple argument, so as to easily construct network
objects from existing addresses.

@item 
bpo-21156@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21156}: importlib.abc.InspectLoader.source_to_code() is now a
staticmethod.

@item 
bpo-21424@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21424}: Simplified and optimized heaqp.nlargest() and nmsmallest() to
make fewer tuple comparisons.

@item 
bpo-21396@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21396}: Fix TextIOWrapper(..., write_through=True) to not force a
flush() on the underlying binary stream.  Patch by akira.

@item 
bpo-18314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18314}: Unlink now removes junctions on Windows. Patch by Kim Gräsman

@item 
bpo-21088@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21088}: Bugfix for curses.window.addch() regression in 3.4.0. In
porting to Argument Clinic, the first two arguments were reversed.

@item 
bpo-21407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21407}: _decimal: The module now supports function signatures.

@item 
bpo-10650@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10650}: Remove the non-standard 'watchexp' parameter from the
Decimal.quantize() method in the Python version.  It had never been
present in the C version.

@item 
bpo-21469@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21469}: Reduced the risk of false positives in robotparser by checking
to make sure that robots.txt has been read or does not exist prior to
returning True in can_fetch().

@item 
bpo-19414@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19414}: Have the OrderedDict mark deleted links as unusable. This gives
an early failure if the link is deleted during iteration.

@item 
bpo-21421@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21421}: Add __slots__ to the MappingViews ABC. Patch by Josh Rosenberg.

@item 
bpo-21101@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21101}: Eliminate double hashing in the C speed-up code for
collections.Counter().

@item 
bpo-21321@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21321}: itertools.islice() now releases the reference to the source
iterator when the slice is exhausted.  Patch by Anton Afanasyev.

@item 
bpo-21057@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21057}: TextIOWrapper now allows the underlying binary stream's read()
or read1() method to return an arbitrary bytes-like object (such as a
memoryview). Patch by Nikolaus Rath.

@item 
bpo-20951@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20951}: SSLSocket.send() now raises either SSLWantReadError or
SSLWantWriteError on a non-blocking socket if the operation would block.
Previously, it would return 0.  Patch by Nikolaus Rath.

@item 
bpo-13248@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13248}: removed previously deprecated asyncore.dispatcher __getattr__
cheap inheritance hack.

@item 
bpo-9815@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9815}: assertRaises now tries to clear references to local variables in
the exception's traceback.

@item 
bpo-19940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19940}: ssl.cert_time_to_seconds() now interprets the given time string
in the UTC timezone (as specified in RFC 5280), not the local timezone.

@item 
bpo-13204@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13204}: Calling sys.flags.__new__ would crash the interpreter, now it
raises a TypeError.

@item 
bpo-19385@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19385}: Make operations on a closed dbm.dumb database always raise the
same exception.

@item 
bpo-21207@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21207}: Detect when the os.urandom cached fd has been closed or
replaced, and open it anew.

@item 
bpo-21291@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21291}: subprocess's Popen.wait() is now thread safe so that multiple
threads may be calling wait() or poll() on a Popen instance at the same
time without losing the Popen.returncode value.

@item 
bpo-21127@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21127}: Path objects can now be instantiated from str subclass
instances (such as @code{numpy.str_}).

@item 
bpo-15002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15002}: urllib.response object to use _TemporaryFileWrapper (and
_TemporaryFileCloser) facility. Provides a better way to handle file
descriptor close. Patch contributed by Christian Theune.

@item 
bpo-12220@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12220}: mindom now raises a custom ValueError indicating it doesn't
support spaces in URIs instead of letting a 'split' ValueError bubble up.

@item 
bpo-21068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21068}: The ssl.PROTOCOL* constants are now enum members.

@item 
bpo-21276@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21276}: posixmodule: Don't define USE_XATTRS on KFreeBSD and the Hurd.

@item 
bpo-21262@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21262}: New method assert_not_called for Mock. It raises AssertionError
if the mock has been called.

@item 
bpo-21238@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21238}: New keyword argument @code{unsafe} to Mock. It raises
@code{AttributeError} incase of an attribute startswith assert or assret.

@item 
bpo-20896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20896}: ssl.get_server_certificate() now uses PROTOCOL_SSLv23, not
PROTOCOL_SSLv3, for maximum compatibility.

@item 
bpo-21239@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21239}: patch.stopall() didn't work deterministically when the same
name was patched more than once.

@item 
bpo-21203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21203}: Updated fileConfig and dictConfig to remove inconsistencies.
Thanks to Jure Koren for the patch.

@item 
bpo-21222@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21222}: Passing name keyword argument to mock.create_autospec now
works.

@item 
bpo-21197@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21197}: Add lib64 -> lib symlink in venvs on 64-bit non-OS X POSIX.

@item 
bpo-17498@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17498}: Some SMTP servers disconnect after certain errors, violating
strict RFC conformance.  Instead of losing the error code when we issue
the subsequent RSET, smtplib now returns the error code and defers raising
the SMTPServerDisconnected error until the next command is issued.

@item 
bpo-17826@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17826}: setting an iterable side_effect on a mock function created by
create_autospec now works. Patch by Kushal Das.

@item 
bpo-7776@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=7776}: Fix @code{Host:} header and reconnection when using
http.client.HTTPConnection.set_tunnel(). Patch by Nikolaus Rath.

@item 
bpo-20968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20968}: unittest.mock.MagicMock now supports division. Patch by
Johannes Baiter.

@item 
bpo-21529@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21529}: Fix arbitrary memory access in JSONDecoder.raw_decode with a
negative second parameter. Bug reported by Guido Vranken. (See also:
@geindex Common Vulnerabilities and Exposures; CVE 2014-4616
CVE 2014-4616@footnote{https://www.cve.org/CVERecord?id=CVE-2014-4616})

@item 
bpo-21169@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21169}: getpass now handles non-ascii characters that the input stream
encoding cannot encode by re-encoding using the replace error handler.

@item 
bpo-21171@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21171}: Fixed undocumented filter API of the rot13 codec. Patch by
Berker Peksag.

@item 
bpo-20539@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20539}: Improved math.factorial error message for large positive inputs
and changed exception type (OverflowError -> ValueError) for large
negative inputs.

@item 
bpo-21172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21172}: isinstance check relaxed from dict to collections.Mapping.

@item 
bpo-21155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21155}: asyncio.EventLoop.create_unix_server() now raises a ValueError
if path and sock are specified at the same time.

@item 
bpo-21136@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21136}: Avoid unnecessary normalization of Fractions resulting from
power and other operations.  Patch by Raymond Hettinger.

@item 
bpo-17621@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17621}: Introduce importlib.util.LazyLoader.

@item 
bpo-21076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21076}: signal module constants were turned into enums. Patch by
Giampaolo Rodola'.

@item 
bpo-20636@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20636}: Improved the repr of Tkinter widgets.

@item 
bpo-19505@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19505}: The items, keys, and values views of OrderedDict now support
reverse iteration using reversed().

@item 
bpo-21149@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21149}: Improved thread-safety in logging cleanup during interpreter
shutdown. Thanks to Devin Jeanpierre for the patch.

@item 
bpo-21058@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21058}: Fix a leak of file descriptor in
@ref{4af,,tempfile.NamedTemporaryFile()}, close the file descriptor if
@ref{506,,io.open()} fails

@item 
bpo-21200@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21200}: Return None from pkgutil.get_loader() when __spec__ is missing.

@item 
bpo-21013@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21013}: Enhance ssl.create_default_context() when used for server side
sockets to provide better security by default.

@item 
bpo-20145@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20145}: @code{assertRaisesRegex} and @code{assertWarnsRegex} now raise a
@code{TypeError} if the second argument is not a string or compiled regex.

@item 
bpo-20633@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20633}: Replace relative import by absolute import.

@item 
bpo-20980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20980}: Stop wrapping exception when using ThreadPool.

@item 
bpo-21082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21082}: In os.makedirs, do not set the process-wide umask. Note this
changes behavior of makedirs when exist_ok=True.

@item 
bpo-20990@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20990}: Fix issues found by pyflakes for multiprocessing.

@item 
bpo-21015@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21015}: SSL contexts will now automatically select an elliptic curve
for ECDH key exchange on OpenSSL 1.0.2 and later, and otherwise default to
"prime256v1".

@item 
bpo-21000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21000}: Improve the command-line interface of json.tool.

@item 
bpo-20995@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20995}: Enhance default ciphers used by the ssl module to enable better
security and prioritize perfect forward secrecy.

@item 
bpo-20884@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20884}: Don't assume that __file__ is defined on importlib.__init__.

@item 
bpo-21499@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21499}: Ignore __builtins__ in several test_importlib.test_api tests.

@item 
bpo-20627@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20627}: xmlrpc.client.ServerProxy is now a context manager.

@item 
bpo-19165@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19165}: The formatter module now raises DeprecationWarning instead of
PendingDeprecationWarning.

@item 
bpo-13936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13936}: Remove the ability of datetime.time instances to be considered
false in boolean contexts.

@item 
bpo-18931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18931}: selectors module now supports /dev/poll on Solaris. Patch by
Giampaolo Rodola'.

@item 
bpo-19977@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19977}: When the @code{LC_TYPE} locale is the POSIX locale (@code{C} locale),
@ref{527,,sys.stdin} and @ref{ac4,,sys.stdout} are now using the
@code{surrogateescape} error handler, instead of the @code{strict} error
handler.

@item 
bpo-20574@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20574}: Implement incremental decoder for cp65001 code (Windows code
page 65001, Microsoft UTF-8).

@item 
bpo-20879@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20879}: Delay the initialization of encoding and decoding tables for
base32, ascii85 and base85 codecs in the base64 module, and delay the
initialization of the unquote_to_bytes() table of the urllib.parse module,
to not waste memory if these modules are not used.

@item 
bpo-19157@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19157}: Include the broadcast address in the usuable hosts for IPv6 in
ipaddress.

@item 
bpo-11599@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11599}: When an external command (e.g. compiler) fails, distutils now
prints out the whole command line (instead of just the command name) if
the environment variable DISTUTILS_DEBUG is set.

@item 
bpo-4931@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4931}: distutils should not produce unhelpful "error: None" messages
anymore. distutils.util.grok_environment_error is kept but doc-deprecated.

@item 
bpo-20875@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20875}: Prevent possible gzip "'read' is not defined" NameError. Patch
by Claudiu Popa.

@item 
bpo-11558@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11558}: @code{email.message.Message.attach} now returns a more useful
error message if @code{attach} is called on a message for which
@code{is_multipart} is False.

@item 
bpo-20283@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20283}: RE pattern methods now accept the string keyword parameters as
documented. The pattern and source keyword parameters are left as
deprecated aliases.

@item 
bpo-20778@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20778}: Fix modulefinder to work with bytecode-only modules.

@item 
bpo-20791@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20791}: copy.copy() now doesn't make a copy when the input is a bytes
object. Initial patch by Peter Otten.

@item 
bpo-19748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19748}: On AIX, time.mktime() now raises an OverflowError for year
outsize range [1902; 2037].

@item 
bpo-19573@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19573}: inspect.signature: Use enum for parameter kind constants.

@item 
bpo-20726@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20726}: inspect.signature: Make Signature and Parameter picklable.

@item 
bpo-17373@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17373}: Add inspect.Signature.from_callable method.

@item 
bpo-20378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20378}: Improve repr of inspect.Signature and inspect.Parameter.

@item 
bpo-20816@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20816}: Fix inspect.getcallargs() to raise correct TypeError for
missing keyword-only arguments. Patch by Jeremiah Lowin.

@item 
bpo-20817@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20817}: Fix inspect.getcallargs() to fail correctly if more than 3
arguments are missing. Patch by Jeremiah Lowin.

@item 
bpo-6676@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6676}: Ensure a meaningful exception is raised when attempting to parse
more than one XML document per pyexpat xmlparser instance. (Original
patches by Hirokazu Yamamoto and Amaury Forgeot d'Arc, with suggested
wording by David Gutteridge)

@item 
bpo-21117@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21117}: Fix inspect.signature to better support functools.partial. Due
to the specifics of functools.partial implementation,
positional-or-keyword arguments passed as keyword arguments become
keyword-only.

@item 
bpo-20334@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20334}: inspect.Signature and inspect.Parameter are now hashable.
Thanks to Antony Lee for bug reports and suggestions.

@item 
bpo-15916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15916}: doctest.DocTestSuite returns an empty unittest.TestSuite
instead of raising ValueError if it finds no tests

@item 
bpo-21209@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21209}: Fix asyncio.tasks.CoroWrapper to workaround a bug in yield-from
implementation in CPythons prior to 3.4.1.

@item 
asyncio: Add gi_@{frame,running,code@} properties to CoroWrapper (upstream
bpo-163@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=163}).

@item 
bpo-21311@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21311}: Avoid exception in _osx_support with non-standard compiler
configurations. Patch by John Szakmeister.

@item 
bpo-11571@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11571}: Ensure that the turtle window becomes the topmost window when
launched on OS X.

@item 
bpo-21801@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21801}: Validate that __signature__ is None or an instance of
Signature.

@item 
bpo-21923@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21923}: Prevent AttributeError in
distutils.sysconfig.customize_compiler due to possible uninitialized
_config_vars.

@item 
bpo-21323@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21323}: Fix http.server to again handle scripts in CGI subdirectories,
broken by the fix for security bpo-19435@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19435}.  Patch by Zach Byrne.

@item 
bpo-22733@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22733}: Fix ffi_prep_args not zero-extending argument values correctly
on 64-bit Windows.

@item 
bpo-23302@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23302}: Default to TCP_NODELAY=1 upon establishing an HTTPConnection.
Removed use of hard-coded MSS as it's an optimization that's no longer
needed with Nagle disabled.
@end itemize

@node IDLE<63>,Build<89>,Library<96>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id775}@anchor{1b5f}
@subsubsection IDLE



@itemize -

@item 
bpo-20577@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20577}: Configuration of the max line length for the FormatParagraph
extension has been moved from the General tab of the Idle preferences
dialog to the FormatParagraph tab of the Config Extensions dialog. Patch
by Tal Einat.

@item 
bpo-16893@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16893}: Update Idle doc chapter to match current Idle and add new
information.

@item 
bpo-3068@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3068}: Add Idle extension configuration dialog to Options menu. Changes
are written to HOME/.idlerc/config-extensions.cfg. Original patch by Tal
Einat.

@item 
bpo-16233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16233}: A module browser (File : Class Browser, Alt+C) requires an
editor window with a filename.  When Class Browser is requested otherwise,
from a shell, output window, or 'Untitled' editor, Idle no longer displays
an error box. It now pops up an Open Module box (Alt+M). If a valid name
is entered and a module is opened, a corresponding browser is also opened.

@item 
bpo-4832@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=4832}: Save As to type Python files automatically adds .py to the name
you enter (even if your system does not display it).  Some systems
automatically add .txt when type is Text files.

@item 
bpo-21986@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21986}: Code objects are not normally pickled by the pickle module. To
match this, they are no longer pickled when running under Idle.

@item 
bpo-17390@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17390}: Adjust Editor window title; remove 'Python', move version to
end.

@item 
bpo-14105@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14105}: Idle debugger breakpoints no longer disappear when inserting or
deleting lines.

@item 
bpo-17172@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17172}: Turtledemo can now be run from Idle. Currently, the entry is on
the Help menu, but it may move to Run. Patch by Ramchandra Apt and Lita
Cho.

@item 
bpo-21765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21765}: Add support for non-ascii identifiers to HyperParser.

@item 
bpo-21940@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21940}: Add unittest for WidgetRedirector. Initial patch by Saimadhav
Heblikar.

@item 
bpo-18592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18592}: Add unittest for SearchDialogBase. Patch by Phil Webster.

@item 
bpo-21694@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21694}: Add unittest for ParenMatch. Patch by Saimadhav Heblikar.

@item 
bpo-21686@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21686}: add unittest for HyperParser. Original patch by Saimadhav
Heblikar.

@item 
bpo-12387@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12387}: Add missing upper(lower)case versions of default Windows key
bindings for Idle so Caps Lock does not disable them. Patch by Roger
Serwy.

@item 
bpo-21695@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21695}: Closing a Find-in-files output window while the search is still
in progress no longer closes Idle.

@item 
bpo-18910@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18910}: Add unittest for textView. Patch by Phil Webster.

@item 
bpo-18292@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18292}: Add unittest for AutoExpand. Patch by Saihadhav Heblikar.

@item 
bpo-18409@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18409}: Add unittest for AutoComplete. Patch by Phil Webster.

@item 
bpo-21477@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21477}: htest.py - Improve framework, complete set of tests. Patches by
Saimadhav Heblikar

@item 
bpo-18104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18104}: Add idlelib/idle_test/htest.py with a few sample tests to begin
consolidating and improving human-validated tests of Idle. Change other
files as needed to work with htest.  Running the module as __main__ runs
all tests.

@item 
bpo-21139@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21139}: Change default paragraph width to 72, the 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}
recommendation.

@item 
bpo-21284@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21284}: Paragraph reformat test passes after user changes reformat
width.

@item 
bpo-17654@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17654}: Ensure IDLE menus are customized properly on OS X for
non-framework builds and for all variants of Tk.

@item 
bpo-23180@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23180}: Rename IDLE "Windows" menu item to "Window". Patch by Al
Sweigart.
@end itemize

@node Build<89>,C API<72>,IDLE<63>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id776}@anchor{1b60}
@subsubsection Build



@itemize -

@item 
bpo-15506@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15506}: Use standard PKG_PROG_PKG_CONFIG autoconf macro in the
configure script.

@item 
bpo-22935@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22935}: Allow the ssl module to be compiled if openssl doesn't support
SSL 3.

@item 
bpo-22592@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22592}: Drop support of the Borland C compiler to build Python. The
distutils module still supports it to build extensions.

@item 
bpo-22591@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22591}: Drop support of MS-DOS, especially of the DJGPP compiler
(MS-DOS port of GCC).

@item 
bpo-16537@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16537}: Check whether self.extensions is empty in setup.py. Patch by
Jonathan Hosmer.

@item 
bpo-22359@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22359}: Remove incorrect uses of recursive make.  Patch by Jonas
Wagner.

@item 
bpo-21958@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21958}: Define HAVE_ROUND when building with Visual Studio 2013 and
above.  Patch by Zachary Turner.

@item 
bpo-18093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18093}: the programs that embed the CPython runtime are now in a
separate "Programs" directory, rather than being kept in the Modules
directory.

@item 
bpo-15759@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15759}: "make suspicious", "make linkcheck" and "make doctest" in Doc/
now display special message when and only when there are failures.

@item 
bpo-21141@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21141}: The Windows build process no longer attempts to find Perl,
instead relying on OpenSSL source being configured and ready to build.
The @code{PCbuild\build_ssl.py} script has been re-written and re-named to
@code{PCbuild\prepare_ssl.py}, and takes care of configuring OpenSSL source
for both 32 and 64 bit platforms.  OpenSSL sources obtained from
svn.python.org will always be pre-configured and ready to build.

@item 
bpo-21037@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21037}: Add a build option to enable AddressSanitizer support.

@item 
bpo-19962@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19962}: The Windows build process now creates "python.bat" in the root
of the source tree, which passes all arguments through to the most
recently built interpreter.

@item 
bpo-21285@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21285}: Refactor and fix curses configure check to always search in a
ncursesw directory.

@item 
bpo-15234@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15234}: For BerkeleyDB and Sqlite, only add the found library and
include directories if they aren't already being searched. This avoids an
explicit runtime library dependency.

@item 
bpo-17861@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17861}: Tools/scripts/generate_opcode_h.py automatically regenerates
Include/opcode.h from Lib/opcode.py if the latter gets any change.

@item 
bpo-20644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20644}: OS X installer build support for documentation build changes in
3.4.1: assume externally supplied sphinx-build is available in /usr/bin.

@item 
bpo-20022@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20022}: Eliminate use of deprecated bundlebuilder in OS X builds.

@item 
bpo-15968@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=15968}: Incorporated Tcl, Tk, and Tix builds into the Windows build
solution.

@item 
bpo-17095@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17095}: Fix Modules/Setup `shared' support.

@item 
bpo-21811@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21811}: Anticipated fixes to support OS X versions > 10.9.

@item 
bpo-21166@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21166}: Prevent possible segfaults and other random failures of python
--generate-posix-vars in pybuilddir.txt build target.

@item 
bpo-18096@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18096}: Fix library order returned by python-config.

@item 
bpo-17219@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17219}: Add library build dir for Python extension cross-builds.

@item 
bpo-22919@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22919}: Windows build updated to support VC 14.0 (Visual Studio 2015),
which will be used for the official release.

@item 
bpo-21236@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21236}: Build _msi.pyd with cabinet.lib instead of fci.lib

@item 
bpo-17128@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17128}: Use private version of OpenSSL for OS X 10.5+ installer.
@end itemize

@node C API<72>,Documentation<75>,Build<89>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id777}@anchor{1b61}
@subsubsection C API



@itemize -

@item 
bpo-14203@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=14203}: Remove obsolete support for view==NULL in PyBuffer_FillInfo(),
bytearray_getbuffer(), bytesiobuf_getbuffer() and array_buffer_getbuf().
All functions now raise BufferError in that case.

@item 
bpo-22445@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22445}: PyBuffer_IsContiguous() now implements precise contiguity
tests, compatible with NumPy's NPY_RELAXED_STRIDES_CHECKING compilation
flag.  Previously the function reported false negatives for corner cases.

@item 
bpo-22079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22079}: PyType_Ready() now checks that statically allocated type has no
dynamically allocated bases.

@item 
bpo-22453@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22453}: Removed non-documented macro PyObject_REPR().

@item 
bpo-18395@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18395}: Rename @code{_Py_char2wchar()} to @ref{bb5,,Py_DecodeLocale()},
rename @code{_Py_wchar2char()} to @ref{bb6,,Py_EncodeLocale()}, and document
these functions.

@item 
bpo-21233@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21233}: Add new C functions: PyMem_RawCalloc(), PyMem_Calloc(),
PyObject_Calloc(), _PyObject_GC_Calloc(). bytes(int) is now using
@code{calloc()} instead of @code{malloc()} for large objects which is faster and
use less memory.

@item 
bpo-20942@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20942}: PyImport_ImportFrozenModuleObject() no longer sets __file__ to
match what importlib does; this affects _frozen_importlib as well as any
module loaded using imp.init_frozen().
@end itemize

@node Documentation<75>,Tests<82>,C API<72>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id778}@anchor{1b62}
@subsubsection Documentation



@itemize -

@item 
bpo-19548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19548}: Update the codecs module documentation to better cover the
distinction between text encodings and other codecs, together with other
clarifications. Patch by Martin Panter.

@item 
bpo-22394@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22394}: Doc/Makefile now supports @code{make venv PYTHON=../python} to
create a venv for generating the documentation, e.g., @code{make html
PYTHON=venv/bin/python3}.

@item 
bpo-21514@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21514}: The documentation of the json module now refers to new JSON RFC
7159 instead of obsoleted RFC 4627.

@item 
bpo-21777@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21777}: The binary sequence methods on bytes and bytearray are now
documented explicitly, rather than assuming users will be able to derive
the expected behaviour from the behaviour of the corresponding str
methods.

@item 
bpo-6916@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=6916}: undocument deprecated asynchat.fifo class.

@item 
bpo-17386@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17386}: Expanded functionality of the @code{Doc/make.bat} script to make
it much more comparable to @code{Doc/Makefile}.

@item 
bpo-21312@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21312}: Update the thread_foobar.h template file to include newer
threading APIs. Patch by Jack McCracken.

@item 
bpo-21043@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21043}: Remove the recommendation for specific CA organizations and to
mention the ability to load the OS certificates.

@item 
bpo-20765@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20765}: Add missing documentation for PurePath.with_name() and
PurePath.with_suffix().

@item 
bpo-19407@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19407}: New package installation and distribution guides based on the
Python Packaging Authority tools. Existing guides have been retained as
legacy links from the distutils docs, as they still contain some required
reference material for tool developers that isn't recorded anywhere else.

@item 
bpo-19697@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19697}: Document cases where __main__.__spec__ is None.
@end itemize

@node Tests<82>,Tools/Demos<49>,Documentation<75>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id779}@anchor{1b63}
@subsubsection Tests



@itemize -

@item 
bpo-18982@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18982}: Add tests for CLI of the calendar module.

@item 
bpo-19548@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19548}: Added some additional checks to test_codecs to ensure that
statements in the updated documentation remain accurate. Patch by Martin
Panter.

@item 
bpo-22838@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22838}: All test_re tests now work with unittest test discovery.

@item 
bpo-22173@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22173}: Update lib2to3 tests to use unittest test discovery.

@item 
bpo-16000@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16000}: Convert test_curses to use unittest.

@item 
bpo-21456@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21456}: Skip two tests in test_urllib2net.py if _ssl module not
present. Patch by Remi Pointel.

@item 
bpo-20746@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20746}: Fix test_pdb to run in refleak mode (-R).  Patch by Xavier de
Gaye.

@item 
bpo-22060@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22060}: test_ctypes has been somewhat cleaned up and simplified; it now
uses unittest test discovery to find its tests.

@item 
bpo-22104@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22104}: regrtest.py no longer holds a reference to the suite of tests
loaded from test modules that don't define test_main().

@item 
bpo-22111@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22111}: Assorted cleanups in test_imaplib.  Patch by Milan Oberkirch.

@item 
bpo-22002@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22002}: Added @code{load_package_tests} function to test.support and used
it to implement/augment test discovery in test_asyncio, test_email,
test_importlib, test_json, and test_tools.

@item 
bpo-21976@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21976}: Fix test_ssl to accept LibreSSL version strings.  Thanks to
William Orr.

@item 
bpo-21918@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21918}: Converted test_tools from a module to a package containing
separate test files for each tested script.

@item 
bpo-9554@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=9554}: Use modern unittest features in test_argparse. Initial patch by
Denver Coneybeare and Radu Voicilas.

@item 
bpo-20155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20155}: Changed HTTP method names in failing tests in test_httpservers
so that packet filtering software (specifically Windows Base Filtering
Engine) does not interfere with the transaction semantics expected by the
tests.

@item 
bpo-19493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19493}: Refactored the ctypes test package to skip tests explicitly
rather than silently.

@item 
bpo-18492@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18492}: All resources are now allowed when tests are not run by
regrtest.py.

@item 
bpo-21634@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21634}: Fix pystone micro-benchmark: use floor division instead of true
division to benchmark integers instead of floating-point numbers. Set
pystone version to 1.2. Patch written by Lennart Regebro.

@item 
bpo-21605@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21605}: Added tests for Tkinter images.

@item 
bpo-21493@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21493}: Added test for ntpath.expanduser().  Original patch by Claudiu
Popa.

@item 
bpo-19925@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=19925}: Added tests for the spwd module. Original patch by Vajrasky
Kok.

@item 
bpo-21522@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21522}: Added Tkinter tests for Listbox.itemconfigure(),
PanedWindow.paneconfigure(), and Menu.entryconfigure().

@item 
bpo-17756@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17756}: Fix test_code test when run from the installed location.

@item 
bpo-17752@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17752}: Fix distutils tests when run from the installed location.

@item 
bpo-18604@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18604}: Consolidated checks for GUI availability.  All platforms now at
least check whether Tk can be instantiated when the GUI resource is
requested.

@item 
bpo-21275@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21275}: Fix a socket test on KFreeBSD.

@item 
bpo-21223@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21223}: Pass test_site/test_startup_imports when some of the extensions
are built as builtins.

@item 
bpo-20635@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20635}: Added tests for Tk geometry managers.

@item 
Add test case for freeze.

@item 
bpo-20743@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20743}: Fix a reference leak in test_tcl.

@item 
bpo-21097@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21097}: Move test_namespace_pkgs into test_importlib.

@item 
bpo-21503@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21503}: Use test_both() consistently in test_importlib.

@item 
bpo-20939@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20939}: Avoid various network test failures due to new redirect of
@indicateurl{http://www.python.org/} to @indicateurl{https://www.python.org}: use
@indicateurl{http://www.example.com} instead.

@item 
bpo-20668@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20668}: asyncio tests no longer rely on tests.txt file. (Patch by
Vajrasky Kok)

@item 
bpo-21093@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21093}: Prevent failures of ctypes test_macholib on OS X if a copy of
libz exists in $HOME/lib or /usr/local/lib.

@item 
bpo-22770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22770}: Prevent some Tk segfaults on OS X when running gui tests.

@item 
bpo-23211@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23211}: Workaround test_logging failure on some OS X 10.6 systems.

@item 
bpo-23345@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23345}: Prevent test_ssl failures with large OpenSSL patch level values
(like 0.9.8zc).
@end itemize

@node Tools/Demos<49>,Windows<74>,Tests<82>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id780}@anchor{1b64}
@subsubsection Tools/Demos



@itemize -

@item 
bpo-22314@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22314}: pydoc now works when the LINES environment variable is set.

@item 
bpo-22615@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22615}: Argument Clinic now supports the "type" argument for the int
converter. This permits using the int converter with enums and typedefs.

@item 
bpo-20076@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20076}: The makelocalealias.py script no longer ignores UTF-8 mapping.

@item 
bpo-20079@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20079}: The makelocalealias.py script now can parse the SUPPORTED file
from glibc sources and supports command line options for source paths.

@item 
bpo-22201@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22201}: Command-line interface of the zipfile module now correctly
extracts ZIP files with directory entries.  Patch by Ryan Wilson.

@item 
bpo-22120@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22120}: For functions using an unsigned integer return converter,
Argument Clinic now generates a cast to that type for the comparison to -1
in the generated code.  (This suppresses a compilation warning.)

@item 
bpo-18974@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18974}: Tools/scripts/diff.py now uses argparse instead of optparse.

@item 
bpo-21906@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21906}: Make Tools/scripts/md5sum.py work in Python 3. Patch by Zachary
Ware.

@item 
bpo-21629@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21629}: Fix Argument Clinic's "--converters" feature.

@item 
Add support for @code{yield from} to 2to3.

@item 
Add support for the 
@geindex Python Enhancement Proposals; PEP 465
PEP 465@footnote{https://peps.python.org/pep-0465/} matrix multiplication operator to 2to3.

@item 
bpo-16047@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=16047}: Fix module exception list and __file__ handling in freeze.
Patch by Meador Inge.

@item 
bpo-11824@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=11824}: Consider ABI tags in freeze. Patch by Meador Inge.

@item 
bpo-20535@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=20535}: PYTHONWARNING no longer affects the run_tests.py script. Patch
by Arfrever Frehtes Taifersar Arahesis.
@end itemize

@node Windows<74>,,Tools/Demos<49>,Python 3 5 0 alpha 1
@anchor{whatsnew/changelog id781}@anchor{1b65}
@subsubsection Windows



@itemize -

@item 
bpo-23260@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=23260}: Update Windows installer

@item 
The bundled version of Tcl/Tk has been updated to 8.6.3.  The most visible
result of this change is the addition of new native file dialogs when
running on Windows Vista or newer.  See Tcl/Tk's TIP 432 for more
information.  Also, this version of Tcl/Tk includes support for Windows
10.

@item 
bpo-17896@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17896}: The Windows build scripts now expect external library sources
to be in @code{PCbuild\..\externals} rather than @code{PCbuild\..\..}.

@item 
bpo-17717@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17717}: The Windows build scripts now use a copy of NASM pulled from
svn.python.org to build OpenSSL.

@item 
bpo-21907@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21907}: Improved the batch scripts provided for building Python.

@item 
bpo-22644@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22644}: The bundled version of OpenSSL has been updated to 1.0.1j.

@item 
bpo-10747@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=10747}: Use versioned labels in the Windows start menu. Patch by Olive
Kilburn.

@item 
bpo-22980@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=22980}: .pyd files with a version and platform tag (for example,
".cp35-win32.pyd") will now be loaded in preference to those without tags.
@end itemize

`(For information about older versions, consult the HISTORY file.)'

@node Le tutoriel Python,Installation et utilisation de Python,Nouveautés de Python,Top
@anchor{tutorial/index doc}@anchor{1b66}@anchor{tutorial/index the-python-tutorial}@anchor{1b67}@anchor{tutorial/index tutorial-index}@anchor{1b68}
@chapter Le tutoriel Python


Python est un langage de programmation puissant et facile à apprendre. Il dispose de structures de données de haut niveau et permet une approche simple mais efficace de la programmation orientée objet. Parce que sa syntaxe est élégante, que son typage est dynamique et qu'il est interprété, Python est un langage idéal pour l'écriture de scripts et le développement rapide d'applications dans de nombreux domaines et sur la plupart des plateformes.

L'interpréteur Python et sa vaste bibliothèque standard sont disponibles librement, sous forme de sources ou de binaires, pour toutes les plateformes majeures depuis le site Internet @indicateurl{https://www.python.org/} et peuvent être librement redistribués. Ce même site distribue et pointe vers des modules, des programmes et des outils tiers. Enfin, il constitue une source de documentation.

L'interpréteur Python peut être facilement étendu par de nouvelles fonctions et types de données implémentés en C ou C++ (ou tout autre langage appelable depuis le C). Python est également adapté comme langage d'extension pour personnaliser des applications.

Dans ce tutoriel, nous introduisons, de façon informelle, les concepts de base ainsi que les fonctionnalités du langage Python et de son écosystème. Il est utile de disposer d'un interpréteur Python à portée de main pour mettre en pratique les notions abordées. Si ce n'est pas possible, pas de souci, les exemples sont inclus et le tutoriel est adapté à une lecture "hors ligne".

Pour une description des objets et modules de la bibliothèque standard, reportez-vous à @ref{143,,La bibliothèque standard}. @ref{144,,La référence du langage Python} présente le langage de manière plus formelle. Pour écrire des extensions en C ou en C++, lisez @ref{1b69,,Extension et intégration de l'interpréteur Python} et @ref{1b6a,,Manuel de référence de l'API Python/C}. Des livres sont également disponibles qui couvrent Python dans le détail.

L'ambition de ce tutoriel n'est pas d'être exhaustif et de couvrir chaque fonctionnalité, ni même toutes les fonctionnalités les plus utilisées. Il vise, en revanche, à introduire les fonctionnalités les plus notables et à vous donner une bonne idée de la saveur et du style du langage. Après l'avoir lu, vous serez capable de lire et d'écrire des modules et des programmes Python et vous serez prêt à en apprendre davantage sur les modules de la bibliothèque Python décrits dans @ref{143,,La bibliothèque standard}.

Pensez aussi à consulter le @ref{1b6b,,Glossaire}.

@menu
* Mise en bouche:: 
* Mode d'emploi de l'interpréteur Python:: 
* Introduction informelle à Python:: 
* D'autres outils de contrôle de flux:: 
* Structures de données:: 
* Modules: Modules<2>. 
* Les entrées/sorties:: 
* Erreurs et exceptions:: 
* Classes:: 
* Survol de la bibliothèque standard:: 
* Survol de la bibliothèque standard: Survol de la bibliothèque standard -- Deuxième partie. Deuxième partie
* Environnements virtuels et paquets:: 
* Pour aller plus loin:: 
* Édition interactive des entrées et substitution d'historique:: 
* Floating-Point Arithmetic; Issues and Limitations: Floating-Point Arithmetic Issues and Limitations. 
* Annexe:: 

@end menu

@node Mise en bouche,Mode d'emploi de l'interpréteur Python,,Le tutoriel Python
@anchor{tutorial/appetite doc}@anchor{1b6c}@anchor{tutorial/appetite tut-intro}@anchor{1b6d}@anchor{tutorial/appetite whetting-your-appetite}@anchor{1b6e}
@section Mise en bouche


Lorsqu'on travaille beaucoup sur ordinateur, on finit souvent par vouloir automatiser certaines tâches : par exemple, effectuer une recherche et un remplacement sur un grand nombre de fichiers de texte ; ou renommer et réorganiser des photos d'une manière un peu compliquée. Pour vous, ce peut être créer une petite base de données, une application graphique ou un simple jeu.

Quand on est un développeur professionnel, le besoin peut se faire sentir de travailler avec des bibliothèques C/C++/Java, mais on trouve que le cycle habituel écriture/compilation/test/compilation est trop lourd. Vous écrivez peut-être une suite de tests pour une telle bibliothèque et vous trouvez que l'écriture du code de test est pénible. Ou bien vous avez écrit un logiciel qui a besoin d'être extensible grâce à un langage de script, mais vous ne voulez pas concevoir ni implémenter un nouveau langage pour votre application.

Python est le langage parfait pour vous.

Vous pouvez écrire un script shell Unix ou des fichiers batch Windows pour certaines de ces tâches. Les scripts shell sont appropriés pour déplacer des fichiers et modifier des données textuelles, mais pas pour une application ayant une interface graphique ni pour des jeux. Vous pouvez écrire un programme en C/C++/Java, mais cela peut prendre beaucoup de temps, ne serait-ce que pour avoir une première maquette. Python est plus facile à utiliser et il vous aidera à terminer plus rapidement votre travail, que ce soit sous Windows, macOS ou Unix.

Python reste facile à utiliser, mais c'est un vrai langage de programmation : il offre une bien meilleure structure et prise en charge des grands programmes que les scripts shell ou les fichiers batch. Par ailleurs, Python permet de beaucoup mieux vérifier les erreurs que le langage C et, en tant que `langage de très haut niveau', il possède nativement des types de données très évolués tels que les tableaux de taille variable ou les dictionnaires. Grâce à ses types de données plus universels, Python est utilisable pour des domaines beaucoup plus variés que ne peuvent l'être `Awk' ou même Perl. Pourtant, vous pouvez faire de nombreuses choses au moins aussi facilement en Python que dans ces langages.

Python vous permet de découper votre programme en modules qui peuvent être réutilisés dans d'autres programmes Python. Il est fourni avec une grande variété de modules standards que vous pouvez utiliser comme base de vos programmes, ou comme exemples pour apprendre à programmer. Certains de ces modules donnent accès aux entrées/sorties, aux appels système, aux connecteurs réseaux et même aux outils comme Tk pour créer des interfaces graphiques.

Python est un langage interprété, ce qui peut vous faire gagner un temps considérable pendant le développement de vos programmes car aucune compilation ni édition de liens n'est nécessaire. L'interpréteur peut être utilisé de manière interactive, pour vous permettre d'expérimenter les fonctionnalités du langage, d'écrire des programmes jetables ou de tester des fonctions lors d'un développement incrémental. C'est aussi une calculatrice de bureau bien pratique.

Python permet d'écrire des programmes compacts et lisibles. Les programmes écrits en Python sont généralement beaucoup plus courts que leurs équivalents en C, C++ ou Java. Et ceci pour plusieurs raisons :


@itemize *

@item 
les types de données de haut niveau vous permettent d'exprimer des opérations complexes en une seule instruction ;

@item 
les instructions sont regroupées entre elles grâce à l'indentation, plutôt que par l'utilisation d'accolades ;

@item 
aucune déclaration de variable ou d'argument n'est nécessaire.
@end itemize

Python est `extensible' : si vous savez écrire un programme en C, une nouvelle fonction ou module peut être facilement ajouté à l'interpréteur afin de l'étendre, que ce soit pour effectuer des opérations critiques à vitesse maximale ou pour lier des programmes en Python à des bibliothèques disponibles uniquement sous forme binaire (par exemple des bibliothèques graphiques dédiées à un matériel). Une fois que vous êtes à l'aise avec ces principes, vous pouvez relier l'interpréteur Python à une application écrite en C et l'utiliser comme un langage d'extensions ou de commandes pour cette application.

Au fait, le nom du langage provient de l'émission de la BBC « Monty Python's Flying Circus » et n'a rien à voir avec les reptiles. Faire référence aux sketchs des Monty Python dans la documentation n'est pas seulement permis, c'est encouragé !

Maintenant que vos papilles ont été chatouillées, nous allons pouvoir rentrer dans le vif du sujet Python. Et comme la meilleure façon d'apprendre un langage est de l'utiliser, ce tutoriel vous invite à jouer avec l'interpréteur au fur et à mesure de votre lecture.

Dans le prochain chapitre, nous expliquons l'utilisation de l'interpréteur. Ce n'est pas la section la plus passionnante, mais c'est un passage obligé pour que vous puissiez mettre en pratique les exemples donnés plus loin.

Le reste du tutoriel présente diverses fonctionnalités du langage et du système Python au travers d'exemples, en commençant par les expressions simples, les instructions et les types de données, jusqu'à aborder des concepts avancés comme les exceptions et les classes, en passant par les fonctions et modules.

@node Mode d'emploi de l'interpréteur Python,Introduction informelle à Python,Mise en bouche,Le tutoriel Python
@anchor{tutorial/interpreter doc}@anchor{1b6f}@anchor{tutorial/interpreter tut-using}@anchor{1b70}@anchor{tutorial/interpreter using-the-python-interpreter}@anchor{1b71}
@section Mode d'emploi de l'interpréteur Python


@menu
* Lancement de l'interpréteur:: 
* L'interpréteur et son environnement:: 

@end menu

@node Lancement de l'interpréteur,L'interpréteur et son environnement,,Mode d'emploi de l'interpréteur Python
@anchor{tutorial/interpreter invoking-the-interpreter}@anchor{1b72}@anchor{tutorial/interpreter tut-invoking}@anchor{1b73}
@subsection Lancement de l'interpréteur


En général, vous trouvez l'interpréteur Python sous @code{/usr/local/bin/python3.13} sur les machines où il est disponible ; ajoutez @code{/usr/local/bin} au chemin de recherche de votre shell Unix afin de pouvoir le lancer en tapant la commande :

@example
python3.13
@end example

dans le shell. @footnote{
Sous Unix, par défaut, l'interpréteur Python 3.x n'est pas installé sous le nom de @code{python} afin de ne pas entrer en conflit avec une éventuelle installation de Python 2.x.
} Le choix du répertoire où se trouve l'interpréteur étant une option d'installation, d'autres chemins sont possibles ; voyez avec votre gourou Python local ou votre administrateur système (par exemple, @code{/usr/local/python} est un endroit courant).

Sur les machines Windows sur lesquelles vous avez installé Python à partir du @ref{1b74,,Microsoft Store}, la commande @code{python3.13} est disponible. Si le @ref{5a8,,lanceur py.exe} est installé, vous pouvez utiliser la commande @code{py}. Voir @ref{1b75,,Digression ; définition des variables d'environnement} pour d'autres façons de lancer Python.

Tapez un caractère de fin de fichier (@code{Ctrl-D} sous Unix, @code{Ctrl-Z} sous Windows) dans une invite de commande primaire provoque la fermeture de l'interpréteur avec un code de sortie nul. Si cela ne fonctionne pas, vous pouvez fermer l'interpréteur en tapant la commande @code{quit()}.

Les fonctionnalités d'édition de l'interpréteur comprennent l'édition interactive, la substitution depuis l'historique et la complétion sur les systèmes qui gèrent la bibliothèque GNU Readline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html}. Un moyen rapide de tester comment est gérée l'édition de la ligne de commande, c'est de taper @code{Control-P} à la première invite de commande que vous rencontrez. Si cela bipe, vous disposez de l'édition de la ligne de commande ; lisez l'appendice @ref{1b76,,Édition interactive des entrées et substitution d'historique} pour une introduction aux touches. Si rien ne semble se produire ou si @code{^P} s'affiche, l'édition de la ligne de commande n'est pas disponible ; vous serez seulement en mesure d'utiliser la touche retour arrière pour supprimer des caractères de la ligne courante.

L'interpréteur fonctionne de façon similaire au shell Unix : lorsqu'il est appelé avec l'entrée standard connectée à un périphérique tty, il lit et exécute les commandes de façon interactive ; lorsqu'il est appelé avec un nom de fichier en argument ou avec un fichier comme entrée standard, il lit et exécute un `script' depuis ce fichier.

Une autre façon de lancer l'interpréteur est @code{python -c commande [arg] ...}. Cela exécute les instructions de `commande' de façon analogue à l'option @ref{5ca,,-c} du shell. Parce que les instructions Python contiennent souvent des espaces et d'autres caractères spéciaux pour le shell, il est généralement conseillé de mettre `commande' entre guillemets simples.

Certains modules Python sont aussi utiles en tant que scripts. Ils peuvent être appelés avec @code{python -m module [arg] ...} qui exécute le fichier source de `module' comme si vous aviez tapé son nom complet dans la ligne de commande.

Quand un fichier de script est utilisé, il est parfois utile de pouvoir lancer le script puis d'entrer dans le mode interactif après coup. Cela est possible en passant @ref{1491,,-i} avant le script.

Tous les paramètres utilisables en ligne de commande sont documentés dans @ref{194d,,Ligne de commande et environnement}.

@menu
* Passage d'arguments:: 
* Mode interactif:: 

@end menu

@node Passage d'arguments,Mode interactif,,Lancement de l'interpréteur
@anchor{tutorial/interpreter argument-passing}@anchor{1b77}@anchor{tutorial/interpreter tut-argpassing}@anchor{1b78}
@subsubsection Passage d'arguments


Lorsqu'ils sont connus de l'interpréteur, le nom du script et les arguments additionnels sont représentés sous forme d'une liste de chaînes de caractères assignée à la variable @code{argv} du module @code{sys}. Vous pouvez y accéder en exécutant @code{import sys}. La liste contient au minimum un élément ; quand aucun script ni aucun argument n'est donné, @code{sys.argv[0]} est une chaine vide. Quand @code{'-'} (qui représente l'entrée standard) est passé comme nom de script, @code{sys.argv[0]} contient @code{'-'}. Quand @ref{5ca,,-c} `commande' est utilisé, @code{sys.argv[0]} contient @code{'-c'}. Enfin, quand @ref{5cb,,-m} `module' est utilisé, le nom complet du module est assigné à @code{sys.argv[0]}. Les options trouvées après @ref{5ca,,-c} `commande' ou @ref{5cb,,-m} `module' ne sont pas lues comme options de l'interpréteur Python mais laissées dans @code{sys.argv} pour être utilisées par le module ou la commande.

@node Mode interactif,,Passage d'arguments,Lancement de l'interpréteur
@anchor{tutorial/interpreter interactive-mode}@anchor{1b79}@anchor{tutorial/interpreter tut-interactive}@anchor{fb1}
@subsubsection Mode interactif


Lorsque des commandes sont lues depuis un tty, l'interpréteur est dit être en `mode interactif'. Dans ce mode, il demande la commande suivante avec le `prompt primaire', en général trois signes plus-grand-que (@code{>>>}) ; pour les lignes de continuation, il affiche le `prompt secondaire', par défaut trois points (@code{...}). L'interpréteur affiche un message de bienvenue indiquant son numéro de version et une notice de copyright avant d'afficher le premier prompt :

@example
$ python3.13
Python 3.13 (default, April 4 2023, 09:25:04)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
@end example

@c XXX update for new releases

Les lignes de continuation sont nécessaires pour entrer une construction multi-lignes. Par exemple, regardez cette instruction @ref{2e7,,if} :

@example
>>> the_world_is_flat = True
>>> if the_world_is_flat:
...     print("Be careful not to fall off!")
...
Be careful not to fall off!
@end example

Pour plus d'informations sur le mode interactif, voir @ref{16e,,Mode interactif}.

@node L'interpréteur et son environnement,,Lancement de l'interpréteur,Mode d'emploi de l'interpréteur Python
@anchor{tutorial/interpreter the-interpreter-and-its-environment}@anchor{1b7a}@anchor{tutorial/interpreter tut-interp}@anchor{1b7b}
@subsection L'interpréteur et son environnement


@menu
* Encodage du code source:: 

@end menu

@node Encodage du code source,,,L'interpréteur et son environnement
@anchor{tutorial/interpreter source-code-encoding}@anchor{1b7c}@anchor{tutorial/interpreter tut-source-encoding}@anchor{1b7d}
@subsubsection Encodage du code source


Par défaut, Python considère que ses fichiers sources sont encodés en UTF-8. Dans cet encodage, les caractères de la plupart des langues peuvent être utilisés à la fois dans les chaînes de caractères, identifiants et commentaires. Notez que la bibliothèque standard n'utilise que des caractères ASCII dans ses identifiants et que nous considérons que c'est une bonne habitude que tout code portable devrait suivre. Pour afficher correctement tous ces caractères, votre éditeur doit reconnaître que le fichier est en UTF-8 et utiliser une police qui comprend tous les caractères utilisés dans le fichier.

Pour annoncer un encodage différent de l'encodage par défaut, une ligne de commentaire particulière doit être ajoutée en tant que `première' ligne du fichier. Sa syntaxe est la suivante :

@example
# -*- coding: encoding -*-
@end example

où `encoding' est un des @ref{1b,,codecs} géré par Python.

Par exemple, pour déclarer un encodage `Windows-1252', la première ligne de votre code source doit être :

@example
# -*- coding: cp1252 -*-
@end example

Une exception à la règle `première ligne' est lorsque la première ligne est un @ref{1b7e,,shebang UNIX}. Dans ce cas, la déclaration de l'encodage doit être placée sur la deuxième ligne du fichier. Par exemple :

@example
#!/usr/bin/env python3
# -*- coding: cp1252 -*-
@end example

@subsubheading Notes


@node Introduction informelle à Python,D'autres outils de contrôle de flux,Mode d'emploi de l'interpréteur Python,Le tutoriel Python
@anchor{tutorial/introduction doc}@anchor{1b7f}@anchor{tutorial/introduction an-informal-introduction-to-python}@anchor{1b80}@anchor{tutorial/introduction tut-informal}@anchor{1b81}
@section Introduction informelle à Python


Dans les exemples qui suivent, les entrées et sorties se distinguent par la présence ou l'absence d'invite (@ref{16b,,>>>} et @ref{16c,,...}) : pour reproduire les exemples, vous devez taper tout ce qui est après l'invite, au moment où celle-ci apparaît ; les lignes qui n'affichent pas d'invite sont les sorties de l'interpréteur. Notez qu'une invite secondaire affichée seule sur une ligne dans un exemple indique que vous devez entrer une ligne vide ; ceci est utilisé pour terminer une commande multi-lignes.


@geindex # (hash);comment

Beaucoup d'exemples de ce manuel, même ceux saisis à l'invite de l'interpréteur, incluent des commentaires. Les commentaires en Python commencent avec un caractère croisillon, @code{#}, et s'étendent jusqu'à la fin de la ligne. Un commentaire peut apparaître au début d'une ligne ou à la suite d'un espace ou de code, mais pas à l'intérieur d'une chaîne de caractères littérale. Un caractère croisillon à l'intérieur d'une chaîne de caractères est juste un caractère croisillon. Comme les commentaires ne servent qu'à expliquer le code et ne sont pas interprétés par Python, ils peuvent être ignorés lorsque vous tapez les exemples.

Quelques exemples :

@example
# this is the first comment
spam = 1  # and this is the second comment
          # ... and now a third!
text = "# This is not a comment because it's inside quotes."
@end example

@menu
* Utilisation de Python comme une calculatrice:: 
* Premiers pas vers la programmation:: 

@end menu

@node Utilisation de Python comme une calculatrice,Premiers pas vers la programmation,,Introduction informelle à Python
@anchor{tutorial/introduction tut-calculator}@anchor{1b82}@anchor{tutorial/introduction using-python-as-a-calculator}@anchor{1b83}
@subsection Utilisation de Python comme une calculatrice


Essayons quelques commandes Python simples. Démarrez l'interpréteur et attendez l'invite primaire, @code{>>>}. Ça ne devrait pas être long.

@menu
* Les nombres:: 
* Text:: 
* Listes:: 

@end menu

@node Les nombres,Text,,Utilisation de Python comme une calculatrice
@anchor{tutorial/introduction numbers}@anchor{1b84}@anchor{tutorial/introduction tut-numbers}@anchor{1b85}
@subsubsection Les nombres


L'interpréteur agit comme une simple calculatrice : vous pouvez lui entrer une expression et il vous affiche la valeur. La syntaxe des expressions est simple : les opérateurs @code{+}, @code{-}, @code{*} et @code{/} peuvent être utilisés pour effectuer des calculs arithmétiques ; les parenthèses (@code{()}) peuvent être utilisées pour faire des regroupements. Par exemple :

@example
>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5*6) / 4
5.0
>>> 8 / 5  # division always returns a floating-point number
1.6
@end example

Les nombres entiers (comme @code{2}, @code{4}, @code{20}) sont de type @ref{254,,int}, alors que les décimaux (comme @code{5.0}, @code{1.6}) sont de type @ref{2eb,,float}. Vous trouvez plus de détails sur les types numériques plus loin dans ce tutoriel.

Les divisions (@code{/}) donnent toujours des @code{float}. Utilisez l'opérateur @code{//} pour effectuer une @ref{931,,division entière} et donc obtenir un résultat entier. Pour obtenir le reste d'une division entière, utilisez l'opérateur @code{%} :

@example
>>> 17 / 3  # classic division returns a float
5.666666666666667
>>>
>>> 17 // 3  # floor division discards the fractional part
5
>>> 17 % 3  # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2  # floored quotient * divisor + remainder
17
@end example

En Python, il est possible de calculer des puissances avec l'opérateur @code{**} @footnote{
Puisque @code{**} est prioritaire sur @code{-}, @code{-3 ** 2} est interprété @code{-(3 ** 2)} et vaut donc @code{-9}. Pour éviter cela et obtenir @code{9}, utilisez des parenthèses : @code{(-3) ** 2}.
} :

@example
>>> 5 ** 2  # 5 squared
25
>>> 2 ** 7  # 2 to the power of 7
128
@end example

Le signe égal (@code{=}) est utilisé pour affecter une valeur à une variable. Dans ce cas, aucun résultat n'est affiché avant l'invite suivante :

@example
>>> width = 20
>>> height = 5 * 9
>>> width * height
900
@end example

Si une variable n'est pas « définie » (si aucune valeur ne lui a été affectée), son utilisation produit une erreur :

@example
>>> n  # try to access an undefined variable
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined
@end example

Les nombres à virgule flottante sont tout à fait admis (NdT : Python utilise le point `.' comme séparateur entre la partie entière et la partie décimale des nombres, c'est la convention anglo-saxonne) ; les opérateurs avec des opérandes de types différents convertissent l'opérande de type entier en type virgule flottante :

@example
>>> 4 * 3.75 - 1
14.0
@end example

En mode interactif, la dernière expression affichée est affectée à la variable @code{_}. Ainsi, lorsque vous utilisez Python comme calculatrice, cela vous permet de continuer des calculs facilement, par exemple :

@example
>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06
@end example

Cette variable doit être considérée comme une variable en lecture seule par l'utilisateur. Ne lui affectez pas de valeur explicitement — vous créeriez ainsi une variable locale indépendante, avec le même nom, qui masquerait la variable native et son fonctionnement magique.

En plus des @ref{254,,int} et des @ref{2eb,,float}, il existe les @ref{29a,,Decimal} et les @ref{1e4,,Fraction}. Python gère aussi les @ref{1b86,,nombres complexes}, en utilisant le suffixe @code{j} ou @code{J} pour indiquer la partie imaginaire (tel que @code{3+5j}).

@node Text,Listes,Les nombres,Utilisation de Python comme une calculatrice
@anchor{tutorial/introduction text}@anchor{1b87}@anchor{tutorial/introduction tut-strings}@anchor{1b88}
@subsubsection Text


Python can manipulate text (represented by type @ref{435,,str}, so-called
"strings") as well as numbers.  This includes characters "@code{!}", words
"@code{rabbit}", names "@code{Paris}", sentences "@code{Got your back.}", etc.
"@code{Yay! :)}". They can be enclosed in single quotes (@code{'...'}) or double
quotes (@code{"..."}) with the same result @footnote{
Contrairement à d'autres langages, les caractères spéciaux comme @code{\n} ont la même signification entre guillemets (@code{"..."}) ou entre guillemets simples (@code{'...'}). La seule différence est que, dans une chaîne entre guillemets, il n'est pas nécessaire de protéger les guillemets simples et vice-versa.
}.

@example
>>> 'spam eggs'  # single quotes
'spam eggs'
>>> "Paris rabbit got your back :)! Yay!"  # double quotes
'Paris rabbit got your back :)! Yay!'
>>> '1975'  # digits and numerals enclosed in quotes are also strings
'1975'
@end example

To quote a quote, we need to "escape" it, by preceding it with @code{\}.
Alternatively, we can use the other type of quotation marks:

@example
>>> 'doesn\'t'  # use \' to escape the single quote...
"doesn't"
>>> "doesn't"  # ...or use double quotes instead
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
@end example

In the Python shell, the string definition and output string can look
different.  The @ref{f60,,print()} function produces a more readable output, by
omitting the enclosing quotes and by printing escaped and special characters:

@example
>>> s = 'First line.\nSecond line.'  # \n means newline
>>> s  # without print(), special characters are included in the string
'First line.\nSecond line.'
>>> print(s)  # with print(), special characters are interpreted, so \n produces new line
First line.
Second line.
@end example

Si vous ne voulez pas que les caractères précédés d'un @code{\} soient interprétés comme étant spéciaux, utilisez les `chaînes brutes' (`raw strings' en anglais) en préfixant la chaîne d'un @code{r} :

@example
>>> print('C:\some\name')  # here \n means newline!
C:\some
ame
>>> print(r'C:\some\name')  # note the r before the quote
C:\some\name
@end example

Il existe une petite subtilité concernant les chaînes brutes : une chaîne brute ne peut pas se terminer par un nombre impair de caractères @code{\} ; voir @ref{1b89,,l'entrée FAQ} pour plus d'informations et des solutions de contournement.

Les chaînes de caractères peuvent s'étendre sur plusieurs lignes. Utilisez alors des triples guillemets, simples ou doubles : @code{'@w{'}'...'@w{'}'} ou @code{"""..."""}. Les retours à la ligne sont automatiquement inclus, mais on peut l'empêcher en ajoutant @code{\} à la fin de la ligne. Dans l'exemple suivant, le premier retour à la ligne n'est pas inclus :

@example
>>> print("""\
... Usage: thingy [OPTIONS]
...      -h                        Display this usage message
...      -H hostname               Hostname to connect to
... """)
Usage: thingy [OPTIONS]
     -h                        Display this usage message
     -H hostname               Hostname to connect to

>>>
@end example

Les chaînes peuvent être concaténées (collées ensemble) avec l'opérateur @code{+} et répétées avec l'opérateur @code{*} :

@example
>>> # 3 times 'un', followed by 'ium'
>>> 3 * 'un' + 'ium'
'unununium'
@end example

Plusieurs chaînes de caractères, écrites littéralement (c'est-à-dire entre guillemets), côte à côte, sont automatiquement concaténées.

@example
>>> 'Py' 'thon'
'Python'
@end example

Cette fonctionnalité est surtout intéressante pour couper des chaînes trop longues :

@example
>>> text = ('Put several strings within parentheses '
...         'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined together.'
@end example

Cela ne fonctionne cependant qu'avec les chaînes littérales, pas avec les variables ni les expressions :

@example
>>> prefix = 'Py'
>>> prefix 'thon'  # can't concatenate a variable and a string literal
  File "<stdin>", line 1
    prefix 'thon'
           ^^^^^^
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
  File "<stdin>", line 1
    ('un' * 3) 'ium'
               ^^^^^
SyntaxError: invalid syntax
@end example

Pour concaténer des variables, ou des variables avec des chaînes littérales, utilisez l'opérateur @code{+} :

@example
>>> prefix + 'thon'
'Python'
@end example

Les chaînes de caractères peuvent être indexées (ou indicées, c'est-à-dire que l'on peut accéder aux caractères par leur position), le premier caractère d'une chaîne étant à la position 0. Il n'existe pas de type distinct pour les caractères, un caractère est simplement une chaîne de longueur 1 :

@example
>>> word = 'Python'
>>> word[0]  # character in position 0
'P'
>>> word[5]  # character in position 5
'n'
@end example

Les indices peuvent également être négatifs, on compte alors en partant de la droite. Par exemple :

@example
>>> word[-1]  # last character
'n'
>>> word[-2]  # second-last character
'o'
>>> word[-6]
'P'
@end example

Notez que, comme @code{-0} égale @code{0}, les indices négatifs commencent par @code{-1}.

En plus d'accéder à un élément par son indice, il est aussi possible de « trancher » (`slice' en anglais) une chaîne. Accéder à une chaîne par un indice permet d'obtenir un caractère, `trancher' permet d'obtenir une sous-chaîne :

@example
>>> word[0:2]  # characters from position 0 (included) to 2 (excluded)
'Py'
>>> word[2:5]  # characters from position 2 (included) to 5 (excluded)
'tho'
@end example

Les valeurs par défaut des indices de tranches ont une utilité ; le premier indice vaut zéro par défaut (c.-à-d. lorsqu'il est omis), le deuxième correspond par défaut à la taille de la chaîne de caractères

@example
>>> word[:2]   # character from the beginning to position 2 (excluded)
'Py'
>>> word[4:]   # characters from position 4 (included) to the end
'on'
>>> word[-2:]  # characters from the second-last (included) to the end
'on'
@end example

Notez que le début est toujours inclus et la fin toujours exclue. Cela assure que @code{s[:i] + s[i:]} est toujours égal à @code{s} :

@example
>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'
@end example

Pour mémoriser la façon dont les tranches fonctionnent, vous pouvez imaginer que les indices pointent `entre' les caractères, le côté gauche du premier caractère ayant la position 0. Le côté droit du dernier caractère d'une chaîne de `n' caractères a alors pour indice `n'. Par exemple :

@example
 +---+---+---+---+---+---+
 | P | y | t | h | o | n |
 +---+---+---+---+---+---+
 0   1   2   3   4   5   6
-6  -5  -4  -3  -2  -1
@end example

La première ligne de nombres donne la position des indices 0…6 dans la chaîne ; la deuxième ligne donne l'indice négatif correspondant. La tranche de `i' à `j' est constituée de tous les caractères situés entre les bords libellés `i' et `j', respectivement.

Pour des indices non négatifs, la longueur d'une tranche est la différence entre ces indices, si les deux sont entre les bornes. Par exemple, la longueur de @code{word[1:3]} est 2.

Utiliser un indice trop grand produit une erreur :

@example
>>> word[42]  # the word only has 6 characters
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: string index out of range
@end example

Cependant, les indices hors bornes sont gérés silencieusement lorsqu'ils sont utilisés dans des tranches :

@example
>>> word[4:42]
'on'
>>> word[42:]
'@w{'}
@end example

Les chaînes de caractères, en Python, ne peuvent pas être modifiées. On dit qu'elles sont @ref{97e,,immuables}. Affecter une nouvelle valeur à un indice dans une chaîne produit une erreur :

@example
>>> word[0] = 'J'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment
>>> word[2:] = 'py'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'str' object does not support item assignment
@end example

Si vous avez besoin d'une chaîne différente, vous devez en créer une nouvelle :

@example
>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'
@end example

La fonction native @ref{619,,len()} renvoie la longueur d'une chaîne :

@example
>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34
@end example


@subsubheading Voir aussi



@table @asis

@item @ref{1b8a,,Type Séquence de Texte — str}

Les chaînes de caractères sont des exemples de `types séquences' ; elles acceptent donc les opérations classiques prises en charge par ces types.

@item @ref{1b8b,,Méthodes de chaînes de caractères}

Les chaînes de caractères gèrent un large éventail de méthodes de transformations basiques et de recherche.

@item @ref{997,,f-strings}

Des chaînes littérales qui contiennent des expressions.

@item @ref{1367,,Syntaxe de formatage de chaîne}

Informations sur le formatage des chaînes avec la méthode @ref{60c,,str.format()}.

@item @ref{6b7,,Formatage de chaines à la printf}

Description détaillée des anciennes méthodes de mise en forme, appelées lorsque les chaînes de caractères sont à gauche de l'opérateur @code{%}.
@end table


@node Listes,,Text,Utilisation de Python comme une calculatrice
@anchor{tutorial/introduction lists}@anchor{1b8c}@anchor{tutorial/introduction tut-lists}@anchor{1b8d}
@subsubsection Listes


Python connaît différents types de données `combinés', utilisés pour regrouper plusieurs valeurs. Le plus souple est la `liste', qui peut être écrit comme une suite, placée entre crochets, de valeurs (éléments) séparées par des virgules. Les éléments d'une liste ne sont pas obligatoirement tous du même type, bien qu'à l'usage ce soit souvent le cas.

@example
>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]
@end example

Comme les chaînes de caractères (et toute autre type de @ref{4db,,sequence}), les listes peuvent être indicées et découpées :

@example
>>> squares[0]  # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:]  # slicing returns a new list
[9, 16, 25]
@end example

Les listes gèrent aussi les opérations comme les concaténations :

@example
>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
@end example

Mais à la différence des chaînes qui sont @ref{97e,,immuables}, les listes sont @ref{1b8e,,mutables} : il est possible de modifier leur contenu :

@example
>>> cubes = [1, 8, 27, 65, 125]  # something's wrong here
>>> 4 ** 3  # the cube of 4 is 64, not 65!
64
>>> cubes[3] = 64  # replace the wrong value
>>> cubes
[1, 8, 27, 64, 125]
@end example

Il est aussi possible d'ajouter de nouveaux éléments à la fin d'une liste avec la `méthode' @code{list.append()} (les méthodes sont abordées plus tard) :

@example
>>> cubes.append(216)  # add the cube of 6
>>> cubes.append(7 ** 3)  # and the cube of 7
>>> cubes
[1, 8, 27, 64, 125, 216, 343]
@end example

Simple assignment in Python never copies data. When you assign a list
to a variable, the variable refers to the `existing list'.
Any changes you make to the list through one variable will be seen
through all other variables that refer to it.:

@example
>>> rgb = ["Red", "Green", "Blue"]
>>> rgba = rgb
>>> id(rgb) == id(rgba)  # they reference the same object
True
>>> rgba.append("Alph")
>>> rgb
["Red", "Green", "Blue", "Alph"]
@end example

Toutes les opérations par tranches renvoient une nouvelle liste contenant les éléments demandés. Cela signifie que l'opération suivante renvoie une @ref{1b8f,,copie (superficielle)} de la liste :

@example
>>> correct_rgba = rgba[:]
>>> correct_rgba[-1] = "Alpha"
>>> correct_rgba
["Red", "Green", "Blue", "Alpha"]
>>> rgba
["Red", "Green", "Blue", "Alph"]
@end example

Des affectations de tranches sont également possibles, ce qui peut même modifier la taille de la liste ou la vider complètement :

@example
>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> letters
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> # replace some values
>>> letters[2:5] = ['C', 'D', 'E']
>>> letters
['a', 'b', 'C', 'D', 'E', 'f', 'g']
>>> # now remove them
>>> letters[2:5] = []
>>> letters
['a', 'b', 'f', 'g']
>>> # clear the list by replacing all the elements with an empty list
>>> letters[:] = []
>>> letters
[]
@end example

La primitive @ref{619,,len()} s'applique aussi aux listes :

@example
>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4
@end example

Il est possible d'imbriquer des listes (c.-à-d. créer des listes contenant d'autres listes). Par exemple :

@example
>>> a = ['a', 'b', 'c']
>>> n = [1, 2, 3]
>>> x = [a, n]
>>> x
[['a', 'b', 'c'], [1, 2, 3]]
>>> x[0]
['a', 'b', 'c']
>>> x[0][1]
'b'
@end example

@node Premiers pas vers la programmation,,Utilisation de Python comme une calculatrice,Introduction informelle à Python
@anchor{tutorial/introduction first-steps-towards-programming}@anchor{1b90}@anchor{tutorial/introduction tut-firststeps}@anchor{1b91}
@subsection Premiers pas vers la programmation


Bien entendu, on peut utiliser Python pour des tâches plus compliquées que d'additionner deux et deux. Par exemple, on peut écrire le début de la suite de Fibonacci@footnote{https://fr.wikipedia.org/wiki/Suite_de_Fibonacci} comme ceci :

@example
>>> # Fibonacci series:
>>> # the sum of two elements defines the next
>>> a, b = 0, 1
>>> while a < 10:
...     print(a)
...     a, b = b, a+b
...
0
1
1
2
3
5
8
@end example

Cet exemple introduit plusieurs nouvelles fonctionnalités.


@itemize *

@item 
La première ligne contient une `affectation multiple' : les variables @code{a} et @code{b} se voient affecter simultanément leurs nouvelles valeurs 0 et 1. Cette méthode est encore utilisée à la dernière ligne, pour démontrer que les expressions sur la partie droite de l'affectation sont toutes évaluées avant que les affectations ne soient effectuées. Ces expressions en partie droite sont toujours évaluées de la gauche vers la droite.

@item 
La boucle @ref{1b92,,while} s'exécute tant que la condition (ici : @code{a < 10}) reste vraie. En Python, comme en C, tout entier différent de zéro est vrai et zéro est faux. La condition peut aussi être une chaîne de caractères, une liste, ou en fait toute séquence ; une séquence avec une valeur non nulle est vraie, une séquence vide est fausse. Le test utilisé dans l'exemple est une simple comparaison. Les opérateurs de comparaison standards sont écrits comme en C : @code{<} (inférieur), @code{>} (supérieur), @code{==} (égal), @code{<=} (inférieur ou égal), @code{>=} (supérieur ou égal) et @code{!=} (non égal).

@item 
Le `corps' de la boucle est `indenté' : l'indentation est la méthode utilisée par Python pour regrouper des instructions. En mode interactif, vous devez saisir une tabulation ou des espaces pour chaque ligne indentée. En pratique, vous aurez intérêt à utiliser un éditeur de texte pour les saisies plus compliquées ; tous les éditeurs de texte dignes de ce nom disposent d'une fonction d'auto-indentation. Lorsqu'une expression composée est saisie en mode interactif, elle doit être suivie d'une ligne vide pour indiquer qu'elle est terminée (car l'analyseur ne peut pas deviner que vous venez de saisir la dernière ligne). Notez bien que toutes les lignes à l'intérieur d'un bloc doivent être indentées au même niveau.

@item 
La fonction @ref{f60,,print()} écrit les valeurs des paramètres qui lui sont fournis. Ce n'est pas la même chose que d'écrire l'expression que vous voulez afficher (comme nous l'avons fait dans l'exemple de la calculatrice), en raison de la manière qu'a @code{print} de gérer les paramètres multiples, les nombres décimaux et les chaînes. Les chaînes sont affichées sans apostrophe et une espace est insérée entre les éléments de telle sorte que vous pouvez facilement formater les choses, comme ceci :

@example
>>> i = 256*256
>>> print('The value of i is', i)
The value of i is 65536
@end example

Le paramètre nommé `end' peut servir pour enlever le retour à la ligne ou pour terminer la ligne par une autre chaîne :

@example
>>> a, b = 0, 1
>>> while a < 1000:
...     print(a, end=',')
...     a, b = b, a+b
...
0,1,1,2,3,5,8,13,21,34,55,89,144,233,377,610,987,
@end example
@end itemize

@subsubheading Notes


@node D'autres outils de contrôle de flux,Structures de données,Introduction informelle à Python,Le tutoriel Python
@anchor{tutorial/controlflow doc}@anchor{1b93}@anchor{tutorial/controlflow more-control-flow-tools}@anchor{1b94}@anchor{tutorial/controlflow tut-morecontrol}@anchor{1b95}
@section D'autres outils de contrôle de flux


En plus de l'instruction @ref{1b92,,while} qui vient d'être présentée, Python dispose d'autres instructions de contrôle de flux que l'on détaillera dans ce chapitre.

@menu
* L'instruction if:: 
* L'instruction for:: 
* La fonction range(): La fonction range. 
* Les instructions break et continue:: 
* La clause else au sein des boucles:: 
* L'instruction pass:: 
* L'instruction match:: 
* Définir des fonctions:: 
* Davantage sur la définition des fonctions:: 
* Aparté ; le style de codage: Aparté le style de codage. 

@end menu

@node L'instruction if,L'instruction for,,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow if-statements}@anchor{1b96}@anchor{tutorial/controlflow tut-if}@anchor{1b97}
@subsection L'instruction @code{if}


L'instruction @ref{2e7,,if} est sans doute la plus connue. Par exemple :

@example
>>> x = int(input("Please enter an integer: "))
Please enter an integer: 42
>>> if x < 0:
...     x = 0
...     print('Negative changed to zero')
... elif x == 0:
...     print('Zero')
... elif x == 1:
...     print('Single')
... else:
...     print('More')
...
More
@end example

Il peut y avoir un nombre quelconque de parties @ref{1b98,,elif} et la partie @ref{18a,,else} est facultative. Le mot clé @code{elif} est un raccourci pour `else if', et permet de gagner un niveau d'indentation. Une séquence @code{if} ... @code{elif} ... @code{elif} ... est par ailleurs équivalente aux instructions @code{switch} ou @code{case} disponibles dans d'autres langages.

Pour les comparaisons avec beaucoup de constantes, ainsi que les tests d'appartenance à un type ou de forme d'un attribut, l'instruction @code{match} décrite plus bas peut se révéler utile (voir @ref{1b99,,L'instruction match}).

@node L'instruction for,La fonction range,L'instruction if,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow for-statements}@anchor{1b9a}@anchor{tutorial/controlflow tut-for}@anchor{1b9b}
@subsection L'instruction @code{for}


@geindex statement;for

L'instruction @ref{2e6,,for} que propose Python est un peu différente de celle que l'on peut trouver en C ou en Pascal. Au lieu de toujours itérer sur une suite arithmétique de nombres (comme en Pascal), ou de donner à l'utilisateur la possibilité de définir le pas d'itération et la condition de fin (comme en C), l'instruction @code{for} en Python itère sur les éléments d'une séquence (qui peut être une liste, une chaîne de caractères…), dans l'ordre dans lequel ils apparaissent dans la séquence. Par exemple :

@c One suggestion was to give a real C example here, but that may only serve to
@c confuse non-C programmers.

@example
>>> # Measure some strings:
>>> words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12
@end example

Écrire du code qui modifie une collection tout en itérant dessus peut s'avérer délicat. Il est généralement plus simple de boucler sur une copie de la collection ou de créer une nouvelle collection :

@example
# Create a sample collection
users = @{'Hans': 'active', 'Éléonore': 'inactive', '景太郎': 'active'@}

# Strategy:  Iterate over a copy
for user, status in users.copy().items():
    if status == 'inactive':
        del users[user]

# Strategy:  Create a new collection
active_users = @{@}
for user, status in users.items():
    if status == 'active':
        active_users[user] = status
@end example

@node La fonction range,Les instructions break et continue,L'instruction for,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow the-range-function}@anchor{1b9c}@anchor{tutorial/controlflow tut-range}@anchor{1b9d}
@subsection La fonction @code{range()}


Si vous devez itérer sur une suite de nombres, la fonction native @ref{930,,range()} est faite pour cela. Elle génère des suites arithmétiques :

@example
>>> for i in range(5):
...     print(i)
...
0
1
2
3
4
@end example

Le dernier élément fourni en paramètre ne fait jamais partie de la liste générée ; @code{range(10)} génère une liste de 10 valeurs, dont les valeurs vont de 0 à 9. Il est possible de spécifier une valeur de début et une valeur d'incrément différentes (y compris négative pour cette dernière, que l'on appelle également parfois le « pas ») :

@example
>>> list(range(5, 10))
[5, 6, 7, 8, 9]

>>> list(range(0, 10, 3))
[0, 3, 6, 9]

>>> list(range(-10, -100, -30))
[-10, -40, -70]
@end example

Pour itérer sur les indices d'une séquence, on peut combiner les fonctions @ref{930,,range()} et @ref{619,,len()} :

@example
>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
...     print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb
@end example

Cependant, dans la plupart des cas, il est plus pratique d'utiliser la fonction @ref{1433,,enumerate()}. Voyez pour cela @ref{1b9e,,Techniques de boucles}.

Une chose étrange se produit lorsqu'on affiche un `range' :

@example
>>> range(10)
range(0, 10)
@end example

L'objet renvoyé par @ref{930,,range()} se comporte presque comme une liste, mais ce n'en est pas une. Cet objet génère les éléments de la séquence au fur et à mesure de l'itération, sans réellement produire la liste en tant que telle, économisant ainsi de l'espace.

On appelle de tels objets des @ref{1205,,itérables}, c'est-à-dire des objets qui conviennent à des fonctions ou constructions qui s'attendent à quelque chose duquel elles peuvent tirer des éléments, successivement, jusqu'à épuisement. Nous avons vu que l'instruction @ref{2e6,,for} est une de ces constructions, et un exemple de fonction qui prend un itérable en paramètre est @ref{454,,sum()} :

@example
>>> sum(range(4))  # 0 + 1 + 2 + 3
6
@end example

Plus loin nous voyons d'autres fonctions qui donnent des itérables ou en prennent en paramètre. De plus amples détails sur @ref{5fc,,list()} sont donnés dans @ref{1b9f,,Structures de données}.

@node Les instructions break et continue,La clause else au sein des boucles,La fonction range,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow break-and-continue-statements}@anchor{1ba0}@anchor{tutorial/controlflow tut-break}@anchor{1ba1}
@subsection Les instructions @code{break} et @code{continue}


L'instruction @ref{a97,,break} interrompt la boucle @ref{2e6,,for} ou @ref{1b92,,while} la plus profonde.

@example
>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(f"@{n@} equals @{x@} * @{n//x@}")
...             break
...
4 equals 2 * 2
6 equals 2 * 3
8 equals 2 * 4
9 equals 3 * 3
@end example

L'instruction @ref{9b7,,continue} fait passer la boucle à son itération suivante :

@example
>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print(f"Found an even number @{num@}")
...         continue
...     print(f"Found an odd number @{num@}")
...
Found an even number 2
Found an odd number 3
Found an even number 4
Found an odd number 5
Found an even number 6
Found an odd number 7
Found an even number 8
Found an odd number 9
@end example
@anchor{tutorial/controlflow tut-for-else}@anchor{1ba2}
@node La clause else au sein des boucles,L'instruction pass,Les instructions break et continue,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow break-and-continue-statements-and-else-clauses-on-loops}@anchor{1ba3}@anchor{tutorial/controlflow else-clauses-on-loops}@anchor{1ba4}
@subsection La clause @code{else} au sein des boucles


Dans une boucle @code{for} ou @code{while}, l'instruction @code{break} peut être couplée à la clause @code{else}. Si la boucle finit sans exécuter le @code{break}, alors la clause @code{else} s'exécute.

Dans une boucle @ref{2e6,,for}, la clause @code{else} s'exécute après l'exécution de la dernière itération, c'est-à-dire uniquement si la boucle n'a pas été interrompue.

Dans une boucle @ref{1b92,,while}, celle-ci est exécutée lorsque la condition devient fausse.

Dans les deux types de boucles, la clause @code{else} n'est `pas' exécutée si la boucle a été interrompue par un @ref{a97,,break}. Bien sûr, d'autres façons de terminer une boucle de manière prématurée, comme avec @ref{9bc,,return} ou le déclenchement d'une exception, vont aussi ignorer l'exécution de la clause @ref{18a,,else}.

Un exemple est donné dans la boucle @code{for} ci-dessous, qui cherche des nombres premiers :

@example
>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(n, 'equals', x, '*', n//x)
...             break
...     else:
...         # loop fell through without finding a factor
...         print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3
@end example

(Oui, ce code est correct. Regardez attentivement : la clause @code{else} est rattachée à la boucle @code{for}, et `non' à l'instruction @code{if}.)

Une façon de voir la clause @code{else} est de l'imaginer couplée à @code{if} dans une boucle. Lorsque la boucle s'exécute, une séquence similaire à @code{if/if/if/else} est exécutée. Le @code{if} étant dans la boucle il est exécuté un certain nombre de fois. Si sa condition est vraie, un @code{break} est déclenché. Si la condition n'est jamais vraie, la clause @code{else} en dehors de la boucle est exécutée.

Lorsqu'elle utilisée dans une boucle, la clause @code{else} est donc plus proche de celle associée à une instruction @ref{6d3,,try} que de celle associée à une instruction @code{if} : la clause @code{else} d'une instruction @code{try} s'exécute lorsqu'aucune exception n'est déclenchée, et celle d'une boucle lorsqu'aucun @code{break} n'intervient. Pour plus d'informations sur l'instruction @code{try} et le traitement des exceptions, consultez la section @ref{1ba5,,Gestion des exceptions}.

@node L'instruction pass,L'instruction match,La clause else au sein des boucles,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow pass-statements}@anchor{1ba6}@anchor{tutorial/controlflow tut-pass}@anchor{1ba7}
@subsection L'instruction @code{pass}


L'instruction @ref{1ba8,,pass} ne fait rien. Elle peut être utilisée lorsqu'une instruction est nécessaire pour fournir une syntaxe correcte, mais qu'aucune action ne doit être effectuée. Par exemple :

@example
>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...
@end example

On utilise couramment cette instruction pour créer des classes minimales :

@example
>>> class MyEmptyClass:
...     pass
...
@end example

Un autre cas d'utilisation du @ref{1ba8,,pass} est de réserver un espace en phase de développement pour une fonction ou un traitement conditionnel, vous permettant ainsi de construire votre code à un niveau plus abstrait. L'instruction @code{pass} est alors ignorée silencieusement :

@example
>>> def initlog(*args):
...     pass   # Remember to implement this!
...
@end example

@node L'instruction match,Définir des fonctions,L'instruction pass,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow match-statements}@anchor{1ba9}@anchor{tutorial/controlflow tut-match}@anchor{1b99}
@subsection L'instruction @code{match}


L'instruction @ref{7f7,,match} confronte la valeur d'une expression à plusieurs filtres successifs donnés par les instructions @code{case}. L’instruction @code{match} peut faire penser au @code{switch} que l'on trouve dans les langages C, Java, JavaScript et autres, mais elle ressemble plus au filtrage par motif des langages Rust et Haskell. Seul le premier filtre qui correspond est exécuté et elle permet aussi d'extraire dans des variables des composantes de la valeur, comme les éléments d'une séquence ou les attributs d'un objet.

Dans sa plus simple expression, une instruction @code{match} compare une valeur à des littéraux :

@example
def http_error(status):
    match status:
        case 400:
            return "Bad request"
        case 404:
            return "Not found"
        case 418:
            return "I'm a teapot"
        case _:
            return "Something's wrong with the internet"
@end example

Remarquez l'emploi du signe souligné @code{_} dans le dernier bloc, qui est normalement un nom de variable spécial. Ici, c'est un filtre `attrape-tout', c'est-à-dire qu'il accepte toutes les valeurs. Si aucun des filtres dans les @code{case} ne fonctionne, aucune des branches indentées sous les @code{case} n'est exécutée.

On peut combiner plusieurs littéraux en un seul filtre avec le signe @code{|}, qui se lit OU :

@example
case 401 | 403 | 404:
    return "Not allowed"
@end example

Les filtres peuvent prendre une forme similaire aux affectations multiples, et provoquer la liaison de variables :

@example
# point is an (x, y) tuple
match point:
    case (0, 0):
        print("Origin")
    case (0, y):
        print(f"Y=@{y@}")
    case (x, 0):
        print(f"X=@{x@}")
    case (x, y):
        print(f"X=@{x@}, Y=@{y@}")
    case _:
        raise ValueError("Not a point")
@end example

Observez bien cet exemple ! Le premier filtre contient simplement deux littéraux. C'est une sorte d'extension des filtres littéraux. Mais les deux filtres suivants mélangent un littéral et un nom de variable. Si un tel filtre réussit, il provoque l'affectation à la variable. Le quatrième filtre est constitué de deux variables, ce qui le fait beaucoup ressembler à l'affectation multiple @code{(x, y) = point}.

Si vous structurez vos données par l'utilisation de classes, vous pouvez former des filtres avec le nom de la classe suivi d'une liste d'arguments. Ces filtres sont semblables à l'appel d'un constructeur, et permettent de capturer des attributs :

@example
class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

def where_is(point):
    match point:
        case Point(x=0, y=0):
            print("Origin")
        case Point(x=0, y=y):
            print(f"Y=@{y@}")
        case Point(x=x, y=0):
            print(f"X=@{x@}")
        case Point():
            print("Somewhere else")
        case _:
            print("Not a point")
@end example

Un certain nombre de classes natives, notamment les classes de données, prennent en charge le filtrage par arguments positionnels en définissant un ordre des attributs. Vous pouvez ajouter cette possibilité à vos propres classes en y définissant l'attribut spécial @code{__match_args__}. Par exemple, le mettre à @code{("x", "y")} rend tous les filtres ci-dessous équivalents (en particulier, tous provoquent la liaison de l'attribut @code{y} à la variable @code{var}) :

@example
Point(1, var)
Point(1, y=var)
Point(x=1, y=var)
Point(y=var, x=1)
@end example

Une méthode préconisée pour lire les filtres est de les voir comme une extension de ce que l'on peut placer à gauche du signe @code{=} dans une affectation. Cela permet de visualiser quelles variables sont liées à quoi. Seuls les noms simples, comme @code{var} ci-dessus, sont des variables susceptibles d'être liées à une valeur. Il n'y a jamais de liaison pour les noms qualifiés (avec un point, comme dans @code{truc.machin}), les noms d'attributs (tels que @code{x=} et @code{y=} dans l'exemple précédent) et les noms de classes (identifiés par les parenthèses à leur droite, comme @code{Point}).

On peut imbriquer les filtres autant que de besoin. Ainsi, on peut lire une courte liste de points, avec @code{__match_args__}, comme ceci :

@example
class Point:
    __match_args__ = ('x', 'y')
    def __init__(self, x, y):
        self.x = x
        self.y = y

match points:
    case []:
        print("No points")
    case [Point(0, 0)]:
        print("The origin")
    case [Point(x, y)]:
        print(f"Single point @{x@}, @{y@}")
    case [Point(0, y1), Point(0, y2)]:
        print(f"Two on the Y axis at @{y1@}, @{y2@}")
    case _:
        print("Something else")
@end example

Un filtre peut comporter un @code{if}, qui introduit ce que l'on appelle une garde. Si le filtre réussit, la garde est alors testée et, si elle s'évalue à une valeur fausse, l'exécution continue au bloc @code{case} suivant. Les variables sont liées avant l'évaluation de la garde, et peuvent être utilisées à l'intérieur :

@example
match point:
    case Point(x, y) if x == y:
        print(f"Y=X at @{x@}")
    case Point(x, y):
        print(f"Not on the diagonal")
@end example

Voici d’autres caractéristiques importantes de cette instruction :


@itemize -

@item 
comme dans les affectations multiples, les filtres de `n'-uplet et de liste sont totalement équivalents et autorisent tous les types de séquences. Exception importante, ils n'autorisent pas les itérateurs ni les chaînes de caractères ;

@item 
les filtres de séquence peuvent faire intervenir l'affectation étoilée : @code{[x, y, *reste]} ou @code{(x, y, *reste)} ont le même sens que dans une affectation avec @code{=}. Le nom de variable après l'étoile peut aussi être l'attrape-tout @code{_}. Ainsi, @code{(x, y, *_)} est un filtre qui reconnaît les séquences à deux éléments ou plus, en capturant les deux premiers et en ignorant le reste ;

@item 
Il existe des filtres d'association. Par exemple, le filtre @code{@{"bande_passante": b, "latence": l@}} extrait les valeurs des clés @code{"bande_passante"} et @code{"latence"} dans un dictionnaire. Contrairement aux filtres de séquence, les clés absentes du filtre sont ignorées. L'affectation double-étoilée (@code{**reste}) fonctionne aussi (cependant, @code{**_} serait redondant et n'est donc pas permis) ;

@item 
on peut capturer la valeur d'une partie d'un filtre avec le mot-clé @code{as}, par exemple :

@example
case (Point(x1, y1), Point(x2, y2) as p2): ...
@end example

Ce filtre, lorsqu'il est comparé à une séquence de deux points, réussit et capture le second dans la variable @code{p2} ;

@item 
la plupart des littéraux sont comparés par égalité. Néanmoins, les singletons @code{True}, @code{False} et @code{None} sont comparés par identité ;

@item 
les filtres peuvent contenir des noms qui se réfèrent à des constantes. Ces noms doivent impérativement être qualifiés (contenir un point) pour ne pas être interprétés comme des variables de capture :

@example
from enum import Enum
class Color(Enum):
    RED = 'red'
    GREEN = 'green'
    BLUE = 'blue'

color = Color(input("Enter your choice of 'red', 'blue' or 'green': "))

match color:
    case Color.RED:
        print("I see red!")
    case Color.GREEN:
        print("Grass is green")
    case Color.BLUE:
        print("I'm feeling the blues :(")
@end example
@end itemize

Pour plus d'explications et d'exemples, lire la 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} (en anglais), qui est écrite sous forme de tutoriel.

@node Définir des fonctions,Davantage sur la définition des fonctions,L'instruction match,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow defining-functions}@anchor{1baa}@anchor{tutorial/controlflow tut-functions}@anchor{1bab}
@subsection Définir des fonctions


On peut créer une fonction qui écrit la suite de Fibonacci jusqu'à une limite imposée :

@example
>>> def fib(n):    # write Fibonacci series less than n
...     """Print a Fibonacci series less than n."""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # Now call the function we just defined:
>>> fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
@end example

@geindex documentation strings
@geindex docstrings
@geindex strings@comma{} documentation

Le mot-clé @ref{140e,,def} introduit une `définition' de fonction. Il doit être suivi du nom de la fonction et d'une liste, entre parenthèses, de ses paramètres. L'instruction qui constitue le corps de la fonction débute à la ligne suivante et doit être indentée.

La première instruction d'une fonction peut, de façon facultative, être une chaîne de caractères littérale ; cette chaîne de caractères est alors la chaîne de documentation de la fonction, appelée `docstring' (consultez la section @ref{1bac,,Chaînes de documentation} pour en savoir plus). Il existe des outils qui utilisent ces chaînes de documentation pour générer automatiquement une documentation en ligne ou imprimée, ou pour permettre à l'utilisateur de naviguer de façon interactive dans le code ; prenez-en l'habitude, c'est une bonne pratique que de documenter le code que vous écrivez.

`L'exécution' d'une fonction introduit une nouvelle table de symboles utilisée par les variables locales de la fonction. Plus précisément, toutes les affectations de variables effectuées au sein d'une fonction stockent les valeurs dans la table des symboles locaux ; en revanche, les références de variables sont recherchées dans la table des symboles locaux, puis dans les tables des symboles locaux des fonctions englobantes, puis dans la table des symboles globaux et finalement dans la table des noms des primitives. Par conséquent, bien qu'elles puissent être référencées, il est impossible d'affecter une valeur à une variable globale ou à une variable d'une fonction englobante (sauf pour les variables globales désignées dans une instruction @ref{188,,global} et, pour les variables des fonctions englobantes, désignées dans une instruction @ref{1285,,nonlocal}).

Les paramètres effectifs (arguments) d'une fonction sont introduits dans la table des symboles locaux de la fonction appelée, au moment où elle est appelée ; par conséquent, les passages de paramètres se font `par valeur', la `valeur' étant toujours une `référence' à un objet et non la valeur de l'objet lui-même @footnote{
En fait, `appels par référence d'objets' serait sans doute une description plus juste dans la mesure où, si un objet mutable est passé en argument, l'appelant verra toutes les modifications qui lui auront été apportées par l'appelé (insertion d'éléments dans une liste…).
}. Lorsqu'une fonction appelle une autre fonction, ou s'appelle elle-même par récursion, une nouvelle table de symboles locaux est créée pour cet appel.

Une définition de fonction associe un nom de fonction à un objet fonction dans l'espace de noms actuel. Pour l'interpréteur, l'objet référencé par ce nom est une fonction définie par l'utilisateur. Plusieurs noms peuvent faire référence à une même fonction, ils peuvent alors tous être utilisés pour appeler la fonction :

@example
>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89
@end example

Si vous venez d'autres langages, vous pouvez penser que @code{fib} n'est pas une fonction mais une procédure, puisqu'elle ne renvoie pas de résultat. En fait, même les fonctions sans instruction @ref{9bc,,return} renvoient une valeur, quoique ennuyeuse. Cette valeur est appelée @code{None} (c'est le nom d'une primitive). Écrire la valeur @code{None} est normalement supprimé par l'interpréteur lorsqu'il s'agit de la seule valeur qui doit être écrite. Vous pouvez le constater, si vous y tenez vraiment, en utilisant @ref{f60,,print()} :

@example
>>> fib(0)
>>> print(fib(0))
None
@end example

Il est facile d'écrire une fonction qui renvoie une liste de la série de Fibonacci au lieu de l'afficher :

@example
>>> def fib2(n):  # return Fibonacci series up to n
...     """Return a list containing the Fibonacci series up to n."""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # see below
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # call it
>>> f100                # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
@end example

Cet exemple, comme d'habitude, illustre de nouvelles fonctionnalités de Python :


@itemize *

@item 
l'instruction @ref{9bc,,return} provoque la sortie de la fonction en renvoyant une valeur. @code{return} sans expression en paramètre renvoie @code{None}. Arriver à la fin d'une fonction renvoie également @code{None} ;

@item 
l'instruction @code{result.append(a)} appelle une `méthode' de l'objet @code{result} qui est une liste. Une méthode est une fonction qui « appartient » à un objet et qui est nommée @code{obj.methodname}, où @code{obj} est un objet (il peut également s'agir d'une expression) et @code{methodname} est le nom d'une méthode que le type de l'objet définit. Différents types définissent différentes méthodes. Des méthodes de différents types peuvent porter le même nom sans qu'il n'y ait d'ambigüité (vous pouvez définir vos propres types d'objets et leurs méthodes en utilisant des `classes', voir @ref{1bad,,Classes}). La méthode @code{append()} utilisée dans cet exemple est définie pour les listes ; elle ajoute un nouvel élément à la fin de la liste. Dans cet exemple, elle est l'équivalent de @code{result = result + [a]}, en plus efficace.
@end itemize

@node Davantage sur la définition des fonctions,Aparté le style de codage,Définir des fonctions,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow more-on-defining-functions}@anchor{1bae}@anchor{tutorial/controlflow tut-defining}@anchor{1baf}
@subsection Davantage sur la définition des fonctions


Il est également possible de définir des fonctions avec un nombre variable d'arguments. Trois syntaxes peuvent être utilisées, éventuellement combinées.

@menu
* Valeur par défaut des arguments:: 
* Les arguments nommés:: 
* Paramètres spéciaux:: 
* Listes d'arguments arbitraires:: 
* Séparation des listes d'arguments:: 
* Fonctions anonymes:: 
* Chaînes de documentation:: 
* Annotations de fonctions:: 

@end menu

@node Valeur par défaut des arguments,Les arguments nommés,,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow default-argument-values}@anchor{1bb0}@anchor{tutorial/controlflow tut-defaultargs}@anchor{1bb1}
@subsubsection Valeur par défaut des arguments


La forme la plus utile consiste à indiquer une valeur par défaut pour certains arguments. Ceci crée une fonction qui peut être appelée avec moins d'arguments que ceux présents dans sa définition. Par exemple :

@example
def ask_ok(prompt, retries=4, reminder='Please try again!'):
    while True:
        reply = input(prompt)
        if reply in @{'y', 'ye', 'yes'@}:
            return True
        if reply in @{'n', 'no', 'nop', 'nope'@}:
            return False
        retries = retries - 1
        if retries < 0:
            raise ValueError('invalid user response')
        print(reminder)
@end example

Cette fonction peut être appelée de plusieurs façons :


@itemize *

@item 
en ne fournissant que les arguments obligatoires : @code{ask_ok('Do you really want to quit?')} ;

@item 
en fournissant une partie des arguments facultatifs : @code{ask_ok('OK to overwrite the file?', 2)} ;

@item 
en fournissant tous les arguments : @code{ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')}.
@end itemize

Cet exemple présente également le mot-clé @ref{2e8,,in}. Celui-ci permet de tester si une séquence contient une certaine valeur.

Les valeurs par défaut sont évaluées lors de la définition de la fonction dans la portée de la `définition', de telle sorte que

@example
i = 5

def f(arg=i):
    print(arg)

i = 6
f()
@end example

affiche @code{5}.

`Avertissement important :' la valeur par défaut n'est évaluée qu'une seule fois. Ceci fait une différence lorsque cette valeur par défaut est un objet mutable tel qu'une liste, un dictionnaire ou des instances de la plupart des classes. Par exemple, la fonction suivante accumule les arguments qui lui sont passés au fil des appels successifs :

@example
def f(a, L=[]):
    L.append(a)
    return L

print(f(1))
print(f(2))
print(f(3))
@end example

affiche

@example
[1]
[1, 2]
[1, 2, 3]
@end example

Si vous ne voulez pas que cette valeur par défaut soit partagée entre des appels successifs, vous pouvez écrire la fonction de cette façon :

@example
def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L
@end example

@node Les arguments nommés,Paramètres spéciaux,Valeur par défaut des arguments,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow keyword-arguments}@anchor{1bb2}@anchor{tutorial/controlflow tut-keywordargs}@anchor{1bb3}
@subsubsection Les arguments nommés


Les fonctions peuvent également être appelées en utilisant des @ref{d00,,arguments nommés} sous la forme @code{kwarg=value}. Par exemple, la fonction suivante :

@example
def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
    print("-- This parrot wouldn't", action, end=' ')
    print("if you put", voltage, "volts through it.")
    print("-- Lovely plumage, the", type)
    print("-- It's", state, "!")
@end example

accepte un argument obligatoire (@code{voltage}) et trois arguments facultatifs (@code{state}, @code{action} et @code{type}). Cette fonction peut être appelée de n'importe laquelle des façons suivantes :

@example
parrot(1000)                                          # 1 positional argument
parrot(voltage=1000)                                  # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword
@end example

mais tous les appels qui suivent sont incorrects :

@example
parrot()                     # required argument missing
parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
parrot(110, voltage=220)     # duplicate value for the same argument
parrot(actor='John Cleese')  # unknown keyword argument
@end example

Dans un appel de fonction, les arguments nommés doivent suivre les arguments positionnés. Tous les arguments nommés doivent correspondre à l'un des arguments acceptés par la fonction (par exemple, @code{actor} n'est pas un argument accepté par la fonction @code{parrot}), mais leur ordre n'est pas important. Ceci inclut également les arguments obligatoires (@code{parrot(voltage=1000)} est également correct). Aucun argument ne peut recevoir une valeur plus d'une fois, comme l'illustre cet exemple incorrect du fait de cette restriction :

@example
>>> def function(a):
...     pass
...
>>> function(0, a=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for argument 'a'
@end example

Quand un dernier paramètre formel est présent sous la forme @code{**name}, il reçoit un dictionnaire (voir @ref{ab4,,Les types de correspondances — dict}) contenant tous les arguments nommés à l'exception de ceux correspondant à un paramètre formel. Ceci peut être combiné à un paramètre formel sous la forme @code{*name} (décrit dans la section suivante) qui lui reçoit un @ref{1bb4,,n-uplet} contenant les arguments positionnés au-delà de la liste des paramètres formels (@code{*name} doit être présent avant @code{**name}). Par exemple, si vous définissez une fonction comme ceci :

@example
def cheeseshop(kind, *arguments, **keywords):
    print("-- Do you have any", kind, "?")
    print("-- I'm sorry, we're all out of", kind)
    for arg in arguments:
        print(arg)
    print("-" * 40)
    for kw in keywords:
        print(kw, ":", keywords[kw])
@end example

Elle pourrait être appelée comme ceci :

@example
cheeseshop("Limburger", "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           shopkeeper="Michael Palin",
           client="John Cleese",
           sketch="Cheese Shop Sketch")
@end example

et, bien sûr, elle affiche :

@example
-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
sketch : Cheese Shop Sketch
@end example

Notez que Python garantit que l'ordre d'affichage des arguments est le même que l'ordre dans lesquels ils sont fournis lors de l'appel à la fonction.

@node Paramètres spéciaux,Listes d'arguments arbitraires,Les arguments nommés,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow special-parameters}@anchor{1bb5}
@subsubsection Paramètres spéciaux


Par défaut, les arguments peuvent être passés à une fonction Python par position, ou explicitement en les nommant. Pour la lisibilité et la performance, il est logique de restreindre la façon dont les arguments peuvent être transmis afin qu'un développeur n'ait qu'à regarder la définition de la fonction pour déterminer si les éléments sont transmis par position seule, par position ou nommé, ou seulement nommé.

Voici à quoi ressemble une définition de fonction :

@example
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only
@end example

où @code{/} et @code{*} sont facultatifs. S'ils sont utilisés, ces symboles indiquent par quel type de paramètre un argument peut être transmis à la fonction : position seule, position ou nommé, et seulement nommé. Les paramètres par mot-clé sont aussi appelés paramètres nommés.

@menu
* Les arguments positionnels-ou-nommés:: 
* Paramètres positionnels uniquement:: 
* Arguments nommés uniquement:: 
* Exemples de fonctions:: 
* Récapitulatif:: 

@end menu

@node Les arguments positionnels-ou-nommés,Paramètres positionnels uniquement,,Paramètres spéciaux
@anchor{tutorial/controlflow positional-or-keyword-arguments}@anchor{1bb6}
@subsubsection Les arguments positionnels-ou-nommés


Si @code{/} et @code{*} ne sont pas présents dans la définition de fonction, les arguments peuvent être passés à une fonction par position ou par nommés.

@node Paramètres positionnels uniquement,Arguments nommés uniquement,Les arguments positionnels-ou-nommés,Paramètres spéciaux
@anchor{tutorial/controlflow positional-only-parameters}@anchor{1bb7}
@subsubsection Paramètres positionnels uniquement


En y regardant de plus près, il est possible de marquer certains paramètres comme `positionnels uniquement'. S'ils sont marqués comme `positionnels uniquement', l'ordre des paramètres est important, et les paramètres ne peuvent pas être transmis en tant que « arguments nommés ». Les paramètres « positionnels uniquement » sont placés avant un @code{/}. Le @code{/} est utilisé pour séparer logiquement les paramètres « positionnels uniquement » du reste des paramètres. S'il n'y a pas de @code{/} dans la définition de fonction, il n'y a pas de paramètres « positionnels uniquement ».

Les paramètres qui suivent le @code{/} peuvent être `positionnels-ou-nommés' ou `nommés-uniquement'.

@node Arguments nommés uniquement,Exemples de fonctions,Paramètres positionnels uniquement,Paramètres spéciaux
@anchor{tutorial/controlflow keyword-only-arguments}@anchor{1bb8}
@subsubsection Arguments nommés uniquement


Pour marquer les paramètres comme `uniquement nommés', indiquant que les paramètres doivent être passés avec l'argument comme mot-clé, placez un @code{*} dans la liste des arguments juste avant le premier paramètre `uniquement nommé'.

@node Exemples de fonctions,Récapitulatif,Arguments nommés uniquement,Paramètres spéciaux
@anchor{tutorial/controlflow function-examples}@anchor{1bb9}
@subsubsection Exemples de fonctions


Considérons l'exemple suivant de définitions de fonctions en portant une attention particulière aux marqueurs @code{/} et @code{*} :

@example
>>> def standard_arg(arg):
...     print(arg)
...
>>> def pos_only_arg(arg, /):
...     print(arg)
...
>>> def kwd_only_arg(*, arg):
...     print(arg)
...
>>> def combined_example(pos_only, /, standard, *, kwd_only):
...     print(pos_only, standard, kwd_only)
@end example

La première définition de fonction, @code{standard_arg}, la forme la plus familière, n'impose aucune restriction sur la convention d'appel et les arguments peuvent être passés par position ou nommés :

@example
>>> standard_arg(2)
2

>>> standard_arg(arg=2)
2
@end example

La deuxième fonction @code{pos_only_arg} restreint le passage aux seuls arguments par position car il y a un @code{/} dans la définition de fonction :

@example
>>> pos_only_arg(1)
1

>>> pos_only_arg(arg=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: pos_only_arg() got some positional-only arguments passed as keyword arguments: 'arg'
@end example

La troisième fonction @code{kwd_only_arg} n'autorise que les arguments nommés comme l'indique le @code{*} dans la définition de fonction :

@example
>>> kwd_only_arg(3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given

>>> kwd_only_arg(arg=3)
3
@end example

Et la dernière utilise les trois conventions d'appel dans la même définition de fonction :

@example
>>> combined_example(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() takes 2 positional arguments but 3 were given

>>> combined_example(1, 2, kwd_only=3)
1 2 3

>>> combined_example(1, standard=2, kwd_only=3)
1 2 3

>>> combined_example(pos_only=1, standard=2, kwd_only=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() got some positional-only arguments passed as keyword arguments: 'pos_only'
@end example

Enfin, considérons cette définition de fonction qui a une collision potentielle entre l'argument positionnel @code{name} et @code{**kwds} qui a @code{name} comme mot-clé :

@example
def foo(name, **kwds):
    return 'name' in kwds
@end example

Il n'y a pas d'appel possible qui renvoie @code{True} car le mot-clé @code{'name'} est toujours lié au premier paramètre. Par exemple :

@example
>>> foo(1, **@{'name': 2@})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>
@end example

Mais en utilisant @code{/} (arguments positionnels seulement), c'est possible puisqu'il permet d'utiliser @code{name} comme argument positionnel et @code{'name'} comme mot-clé dans les arguments nommés :

@example
>>> def foo(name, /, **kwds):
...     return 'name' in kwds
...
>>> foo(1, **@{'name': 2@})
True
@end example

En d'autres termes, les noms des paramètres seulement positionnels peuvent être utilisés sans ambiguïté dans @code{**kwds}.

@node Récapitulatif,,Exemples de fonctions,Paramètres spéciaux
@anchor{tutorial/controlflow recap}@anchor{1bba}
@subsubsection Récapitulatif


Le cas d'utilisation détermine les paramètres à utiliser dans la définition de fonction :

@example
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
@end example

Quelques conseils :


@itemize *

@item 
utilisez les paramètres positionnels si vous voulez que le nom des paramètres soit masqué à l'utilisateur. Ceci est utile lorsque les noms de paramètres n'ont pas de signification réelle, si vous voulez faire respecter l'ordre des arguments lorsque la fonction est appelée ou si vous avez besoin de prendre certains paramètres positionnels et mots-clés arbitraires ;

@item 
utilisez les paramètres nommés lorsque les noms ont un sens et que la définition de la fonction est plus compréhensible avec des noms explicites ou si vous voulez empêcher les utilisateurs de se fier à la position de l'argument qui est passé ;

@item 
dans le cas d'une API, utilisez les paramètres seulement positionnels pour éviter de casser l'API si le nom du paramètre est modifié dans l'avenir.
@end itemize

@node Listes d'arguments arbitraires,Séparation des listes d'arguments,Paramètres spéciaux,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow arbitrary-argument-lists}@anchor{1bbb}@anchor{tutorial/controlflow tut-arbitraryargs}@anchor{1bbc}
@subsubsection Listes d'arguments arbitraires


@geindex * (asterisk);in function calls

Pour terminer, l'option la moins fréquente consiste à indiquer qu'une fonction peut être appelée avec un nombre arbitraire d'arguments. Ces arguments sont intégrés dans un `n'-uplet (voir @ref{1bb4,,n-uplets et séquences}). Avant le nombre variable d'arguments, zéro ou plus arguments normaux peuvent apparaître

@example
def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))
@end example

Normalement, ces arguments @code{variadiques} sont les derniers paramètres, parce qu'ils agrègent toutes les valeurs suivantes. Tout paramètre placé après le paramètre @code{*arg} ne pourra être utilisé que comme argument nommé, pas comme argument positionnel

@example
>>> def concat(*args, sep="/"):
...     return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'
@end example

@node Séparation des listes d'arguments,Fonctions anonymes,Listes d'arguments arbitraires,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow tut-unpacking-arguments}@anchor{1bbd}@anchor{tutorial/controlflow unpacking-argument-lists}@anchor{1bbe}
@subsubsection Séparation des listes d'arguments


La situation inverse intervient lorsque les arguments sont déjà dans une liste ou un `n'-uplet mais doivent être séparés pour un appel de fonction nécessitant des arguments positionnés séparés. Par exemple, la primitive @ref{930,,range()} attend des arguments `start' et `stop' distincts. S'ils ne sont pas disponibles séparément, écrivez l'appel de fonction en utilisant l'opérateur @code{*} pour séparer les arguments présents dans une liste ou un `n'-uplet :

@example
>>> list(range(3, 6))            # normal call with separate arguments
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args))            # call with arguments unpacked from a list
[3, 4, 5]
@end example

@geindex **;in function calls

De la même façon, les dictionnaires peuvent fournir des arguments nommés en utilisant l'opérateur @code{**} :

@example
>>> def parrot(voltage, state='a stiff', action='voom'):
...     print("-- This parrot wouldn't", action, end=' ')
...     print("if you put", voltage, "volts through it.", end=' ')
...     print("E's", state, "!")
...
>>> d = @{"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"@}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
@end example

@node Fonctions anonymes,Chaînes de documentation,Séparation des listes d'arguments,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow lambda-expressions}@anchor{1bbf}@anchor{tutorial/controlflow tut-lambda}@anchor{1bc0}
@subsubsection Fonctions anonymes


Avec le mot-clé @ref{127a,,lambda}, vous pouvez créer de petites fonctions anonymes. En voici une qui renvoie la somme de ses deux arguments : @code{lambda a, b: a+b}. Les fonctions lambda peuvent être utilisées partout où un objet fonction est attendu. Elles sont syntaxiquement restreintes à une seule expression. Sémantiquement, elles ne sont que du sucre syntaxique pour une définition de fonction normale. Comme les fonctions imbriquées, les fonctions lambda peuvent référencer des variables de la portée englobante :

@example
>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43
@end example

L'exemple précédent utilise une fonction anonyme pour renvoyer une fonction. Une autre utilisation classique est de donner une fonction minimaliste directement en tant que paramètre :

@example
>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]
@end example

@node Chaînes de documentation,Annotations de fonctions,Fonctions anonymes,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow documentation-strings}@anchor{1bc1}@anchor{tutorial/controlflow tut-docstrings}@anchor{1bac}
@subsubsection Chaînes de documentation


@geindex docstrings
@geindex documentation strings
@geindex strings@comma{} documentation

Voici quelques conventions concernant le contenu et le format des chaînes de documentation.

Il convient que la première ligne soit toujours courte et résume de manière concise l'utilité de l'objet. Afin d'être bref, nul besoin de rappeler le nom de l'objet ou son type, qui sont accessibles par d'autres moyens (sauf si le nom est un verbe qui décrit une opération). La convention veut que la ligne commence par une majuscule et se termine par un point.

S'il y a d'autres lignes dans la chaîne de documentation, la deuxième ligne devrait être vide, pour la séparer visuellement du reste de la description. Les autres lignes peuvent alors constituer un ou plusieurs paragraphes décrivant le mode d'utilisation de l'objet, ses effets de bord, etc.

L'analyseur de code Python ne supprime pas l'indentation des chaînes de caractères littérales multi-lignes, donc les outils qui utilisent la documentation doivent si besoin faire cette opération eux-mêmes. La convention suivante s'applique : la première ligne non vide `après' la première détermine la profondeur d'indentation de l'ensemble de la chaîne de documentation (on ne peut pas utiliser la première ligne qui est généralement accolée aux guillemets d'ouverture de la chaîne de caractères et dont l'indentation n'est donc pas visible). Les espaces « correspondant » à cette profondeur d'indentation sont alors supprimées du début de chacune des lignes de la chaîne. Aucune ligne ne devrait présenter un niveau d'indentation inférieur mais, si cela arrive, toutes les espaces situées en début de ligne doivent être supprimées. L'équivalent des espaces doit être testé après expansion des tabulations (normalement remplacées par 8 espaces).

Voici un exemple de chaîne de documentation multi-lignes :

@example
>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.
@end example

@node Annotations de fonctions,,Chaînes de documentation,Davantage sur la définition des fonctions
@anchor{tutorial/controlflow function-annotations}@anchor{1bc2}@anchor{tutorial/controlflow tut-annotations}@anchor{1bc3}
@subsubsection Annotations de fonctions


@geindex function;annotations
@geindex ->;function annotations
@geindex ; (colon);function annotations

@ref{1bc4,,Les annotations de fonction} sont des métadonnées optionnelles décrivant les types utilisés par une fonction définie par l'utilisateur (voir les 
@geindex Python Enhancement Proposals; PEP 3107
PEP 3107@footnote{https://peps.python.org/pep-3107/} et 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} pour plus d'informations).

Les @ref{1bc5,,annotations} sont stockées dans l'attribut @code{__annotations__} de la fonction, sous la forme d'un dictionnaire, et n'ont aucun autre effet. Les annotations sur les paramètres sont définies par deux points (@code{:}) après le nom du paramètre suivi d'une expression donnant la valeur de l'annotation. Les annotations de retour sont définies par @code{->} suivi d'une expression, entre la liste des paramètres et les deux points de fin de l'instruction @ref{140e,,def}. L'exemple suivant a un paramètre requis, un paramètre optionnel et la valeur de retour annotés :

@example
>>> def f(ham: str, eggs: str = 'eggs') -> str:
...     print("Annotations:", f.__annotations__)
...     print("Arguments:", ham, eggs)
...     return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: @{'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>@}
Arguments: spam eggs
'spam and eggs'
@end example

@node Aparté le style de codage,,Davantage sur la définition des fonctions,D'autres outils de contrôle de flux
@anchor{tutorial/controlflow intermezzo-coding-style}@anchor{1bc6}@anchor{tutorial/controlflow tut-codingstyle}@anchor{1bc7}
@subsection Aparté : le style de codage


@geindex coding;style

Maintenant que vous êtes prêt à écrire des programmes plus longs et plus complexes, il est temps de parler du `style de codage'. La plupart des langages peuvent être écrits (ou plutôt `formatés') selon différents styles ; certains sont plus lisibles que d'autres. Rendre la lecture de votre code plus facile aux autres est toujours une bonne idée et adopter un bon style de codage peut énormément vous y aider.

En Python, la plupart des projets adhèrent au style défini dans la 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} ; elle met en avant un style de codage très lisible et agréable à l’œil. Chaque développeur Python se doit donc de la lire et de s'en inspirer autant que possible ; voici ses principaux points notables :


@itemize *

@item 
utilisez des indentations de 4 espaces et pas de tabulation.

4 espaces constituent un bon compromis entre une indentation courte (qui permet une profondeur d'imbrication plus importante) et une longue (qui rend le code plus facile à lire). Les tabulations introduisent de la confusion et doivent être proscrites autant que possible ;

@item 
faites en sorte que les lignes ne dépassent pas 79 caractères, au besoin en insérant des retours à la ligne.

Vous facilitez ainsi la lecture pour les utilisateurs qui n'ont qu'un petit écran et, pour les autres, cela leur permet de visualiser plusieurs fichiers côte à côte ;

@item 
utilisez des lignes vides pour séparer les fonctions et les classes, ou pour scinder de gros blocs de code à l'intérieur de fonctions ;

@item 
lorsque c'est possible, placez les commentaires sur leurs propres lignes ;

@item 
utilisez les chaînes de documentation ;

@item 
utilisez des espaces autour des opérateurs et après les virgules, mais pas juste à l'intérieur des parenthèses : @code{a = f(1, 2) + g(3, 4)} ;

@item 
nommez toujours vos classes et fonctions de la même manière ; la convention est d'utiliser une notation @code{UpperCamelCase} pour les classes, et @code{minuscules_avec_trait_bas} pour les fonctions et méthodes. Utilisez toujours @code{self} comme nom du premier argument des méthodes (voyez @ref{1bc8,,Une première approche des classes} pour en savoir plus sur les classes et les méthodes) ;

@item 
n’utilisez pas d'encodage exotique dès lors que votre code est censé être utilisé dans des environnements internationaux. Par défaut, Python travaille en UTF-8. Pour couvrir tous les cas, préférez le simple ASCII ;

@item 
de la même manière, n'utilisez que des caractères ASCII pour vos noms de variables s'il est envisageable qu'une personne parlant une autre langue lise ou doive modifier votre code.
@end itemize

@subsubheading Notes


@node Structures de données,Modules<2>,D'autres outils de contrôle de flux,Le tutoriel Python
@anchor{tutorial/datastructures doc}@anchor{1bc9}@anchor{tutorial/datastructures data-structures}@anchor{1bca}@anchor{tutorial/datastructures tut-structures}@anchor{1b9f}
@section Structures de données


Ce chapitre reprend plus en détail quelques points déjà décrits précédemment et introduit également de nouvelles notions.

@menu
* Compléments sur les listes:: 
* L'instruction del:: 
* n-uplets et séquences:: 
* Ensembles:: 
* Dictionnaires:: 
* Techniques de boucles:: 
* Plus d'informations sur les conditions:: 
* Comparer des séquences avec d'autres types:: 

@end menu

@node Compléments sur les listes,L'instruction del,,Structures de données
@anchor{tutorial/datastructures more-on-lists}@anchor{1bcb}@anchor{tutorial/datastructures tut-morelists}@anchor{1bcc}
@subsection Compléments sur les listes


Le type liste dispose de méthodes supplémentaires. Voici toutes les méthodes des objets liste :


@deffn {Méthode} list.append (x)

Add an item to the end of the list.  Similar to @code{a[len(a):] = [x]}.
@end deffn


@deffn {Méthode} list.extend (iterable)

Extend the list by appending all the items from the iterable.  Similar to
@code{a[len(a):] = iterable}.
@end deffn


@deffn {Méthode} list.insert (i, x)

Insère un élément à la position indiquée. Le premier argument est la position de l'élément avant lequel l'insertion doit s'effectuer, donc @code{a.insert(0, x)} insère l'élément en tête de la liste et @code{a.insert(len(a), x)} est équivalent à @code{a.append(x)}.
@end deffn


@deffn {Méthode} list.remove (x)

Supprime de la liste le premier élément dont la valeur est égale à `x'. Une exception @ref{1ff,,ValueError} est levée s'il n'existe aucun élément avec cette valeur.
@end deffn


@deffn {Méthode} list.pop ([i])

Remove the item at the given position in the list, and return it.  If no index
is specified, @code{a.pop()} removes and returns the last item in the list.
It raises an @ref{14eb,,IndexError} if the list is empty or the index is
outside the list range.
@end deffn


@deffn {Méthode} list.clear ()

Remove all items from the list.  Similar to @code{del a[:]}.
@end deffn


@deffn {Méthode} list.index (x[, start[, end]])

Renvoie la position du premier élément de la liste dont la valeur égale `x' (en commençant à compter les positions à partir de zéro). Une exception @ref{1ff,,ValueError} est levée si aucun élément n'est trouvé.

Les arguments optionnels `start' et `end' sont interprétés de la même manière que dans la notation des tranches et sont utilisés pour limiter la recherche à une sous-séquence particulière. L'indice renvoyé est calculé relativement au début de la séquence complète et non relativement à `start'.
@end deffn


@deffn {Méthode} list.count (x)

Renvoie le nombre d'éléments ayant la valeur `x' dans la liste.
@end deffn


@deffn {Méthode} list.sort (*, key=None, reverse=False)

Ordonne les éléments dans la liste (les arguments peuvent personnaliser l'ordonnancement, voir @ref{bbc,,sorted()} pour leur explication).
@end deffn


@deffn {Méthode} list.reverse ()

Inverse l'ordre des éléments dans la liste.
@end deffn


@deffn {Méthode} list.copy ()

Return a shallow copy of the list.  Similar to @code{a[:]}.
@end deffn

L'exemple suivant utilise la plupart des méthodes des listes :

@example
>>> fruits = ['orange', 'apple', 'pear', 'banana', 'kiwi', 'apple', 'banana']
>>> fruits.count('apple')
2
>>> fruits.count('tangerine')
0
>>> fruits.index('banana')
3
>>> fruits.index('banana', 4)  # Find next banana starting at position 4
6
>>> fruits.reverse()
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange']
>>> fruits.append('grape')
>>> fruits
['banana', 'apple', 'kiwi', 'banana', 'pear', 'apple', 'orange', 'grape']
>>> fruits.sort()
>>> fruits
['apple', 'apple', 'banana', 'banana', 'grape', 'kiwi', 'orange', 'pear']
>>> fruits.pop()
'pear'
@end example

Vous avez probablement remarqué que les méthodes qui ne font que modifier la liste, comme @code{insert}, @code{remove} ou @code{sort}, n'affichent pas de valeur de retour (elles renvoient @code{None}) @footnote{
D'autres langages renvoient l'objet modifié, ce qui permet de chaîner les méthodes comme ceci : @code{d->insert("a")->remove("b")->sort();}.
}. C'est un principe respecté par toutes les structures de données mutables en Python.

Another thing you might notice is that not all data can be sorted or
compared.  For instance, @code{[None, 'hello', 10]} doesn't sort because
integers can't be compared to strings and @code{None} can't be compared to
other types.  Also, there are some types that don't have a defined
ordering relation.  For example, @code{3+4j < 5+7j} isn't a valid
comparison.

@menu
* Utilisation des listes comme des piles:: 
* Utilisation des listes comme des files:: 
* Listes en compréhension:: 
* Listes en compréhensions imbriquées:: 

@end menu

@node Utilisation des listes comme des piles,Utilisation des listes comme des files,,Compléments sur les listes
@anchor{tutorial/datastructures tut-lists-as-stacks}@anchor{1bcd}@anchor{tutorial/datastructures using-lists-as-stacks}@anchor{1bce}
@subsubsection Utilisation des listes comme des piles


The list methods make it very easy to use a list as a stack, where the last
element added is the first element retrieved ("last-in, first-out").  To add an
item to the top of the stack, use @code{append()}.  To retrieve an item from the
top of the stack, use @code{pop()} without an explicit index.  For example:

@example
>>> stack = [3, 4, 5]
>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]
@end example

@node Utilisation des listes comme des files,Listes en compréhension,Utilisation des listes comme des piles,Compléments sur les listes
@anchor{tutorial/datastructures tut-lists-as-queues}@anchor{1bcf}@anchor{tutorial/datastructures using-lists-as-queues}@anchor{1bd0}
@subsubsection Utilisation des listes comme des files


Il est également possible d'utiliser une liste comme une file, où le premier élément ajouté est le premier récupéré (« premier entré, premier sorti » ou FIFO pour `first-in, first-out') ; toutefois, les listes ne sont pas très efficaces pour réaliser ce type de traitement. Alors que les ajouts et suppressions en fin de liste sont rapides, les insertions ou les retraits en début de liste sont lents (car tous les autres éléments doivent être décalés d'une position).

Pour implémenter une file, utilisez plutôt la classe @ref{5c6,,collections.deque} qui a été conçue spécialement pour réaliser rapidement les opérations d'ajout et de retrait aux deux extrémités. Par exemple :

@example
>>> from collections import deque
>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry")           # Terry arrives
>>> queue.append("Graham")          # Graham arrives
>>> queue.popleft()                 # The first to arrive now leaves
'Eric'
>>> queue.popleft()                 # The second to arrive now leaves
'John'
>>> queue                           # Remaining queue in order of arrival
deque(['Michael', 'Terry', 'Graham'])
@end example

@node Listes en compréhension,Listes en compréhensions imbriquées,Utilisation des listes comme des files,Compléments sur les listes
@anchor{tutorial/datastructures list-comprehensions}@anchor{1bd1}@anchor{tutorial/datastructures tut-listcomps}@anchor{1bd2}
@subsubsection Listes en compréhension


Les listes en compréhension fournissent un moyen de construire des listes de manière très concise. Une application classique consiste à construire une liste dont les éléments sont les résultats d'une opération appliquée à chaque élément d'une autre séquence ; une autre consiste à créer une sous-séquence des éléments respectant une condition donnée.

Par exemple, supposons que l'on veuille créer une liste de carrés, comme :

@example
>>> squares = []
>>> for x in range(10):
...     squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
@end example

Notez que cela crée (ou remplace) une variable nommée @code{x} qui existe toujours après l'exécution de la boucle. On peut calculer une liste de carrés sans effet de bord avec :

@example
squares = list(map(lambda x: x**2, range(10)))
@end example

ou, de manière équivalente :

@example
squares = [x**2 for x in range(10)]
@end example

ce qui est plus court et lisible.

Une liste en compréhension consiste à placer entre crochets une expression suivie par une clause @code{for} puis par zéro ou plus clauses @code{for} ou @code{if}. Le résultat est une nouvelle liste résultat de l'évaluation de l'expression dans le contexte des clauses @code{for} et @code{if} qui la suivent. Par exemple, cette compréhension de liste combine les éléments de deux listes s'ils ne sont pas égaux :

@example
>>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
@end example

et c'est équivalent à :

@example
>>> combs = []
>>> for x in [1,2,3]:
...     for y in [3,1,4]:
...         if x != y:
...             combs.append((x, y))
...
>>> combs
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
@end example

Notez que l'ordre des instructions @ref{2e6,,for} et @ref{2e7,,if} est le même dans ces différents extraits de code.

Si l'expression est un `n'-uplet (c'est-à-dire @code{(x, y)} dans cet exemple), elle doit être mise entre parenthèses

@example
>>> vec = [-4, -2, 0, 2, 4]
>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = ['  banana', '  loganberry ', 'passion fruit  ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is raised
>>> [x, x**2 for x in range(6)]
  File "<stdin>", line 1
    [x, x**2 for x in range(6)]
     ^^^^^^^
SyntaxError: did you forget parentheses around the comprehension target?
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]
@end example

Les listes en compréhension peuvent contenir des expressions complexes et des fonctions imbriquées :

@example
>>> from math import pi
>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']
@end example

@node Listes en compréhensions imbriquées,,Listes en compréhension,Compléments sur les listes
@anchor{tutorial/datastructures nested-list-comprehensions}@anchor{1bd3}
@subsubsection Listes en compréhensions imbriquées


La première expression dans une liste en compréhension peut être n'importe quelle expression, y compris une autre liste en compréhension.

Voyez l'exemple suivant d'une matrice de 3 par 4, implémentée sous la forme de 3 listes de 4 éléments :

@example
>>> matrix = [
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
...     [9, 10, 11, 12],
... ]
@end example

Cette compréhension de liste transpose les lignes et les colonnes :

@example
>>> [[row[i] for row in matrix] for i in range(4)]
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
@end example

Comme nous l'avons vu dans la section précédente, la liste en compréhension à l'intérieur est évaluée dans le contexte de l'instruction @ref{2e6,,for} qui la suit, donc cet exemple est équivalent à :

@example
>>> transposed = []
>>> for i in range(4):
...     transposed.append([row[i] for row in matrix])
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
@end example

lequel est lui-même équivalent à :

@example
>>> transposed = []
>>> for i in range(4):
...     # the following 3 lines implement the nested listcomp
...     transposed_row = []
...     for row in matrix:
...         transposed_row.append(row[i])
...     transposed.append(transposed_row)
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
@end example

Dans des cas concrets, il est toujours préférable d'utiliser des fonctions natives plutôt que des instructions de contrôle de flux complexes. La fonction @ref{7ba,,zip()} fait dans ce cas un excellent travail :

@example
>>> list(zip(*matrix))
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]
@end example

Voir @ref{1bbd,,Séparation des listes d'arguments} pour plus de détails sur l'astérisque de cette ligne.

@node L'instruction del,n-uplets et séquences,Compléments sur les listes,Structures de données
@anchor{tutorial/datastructures the-del-statement}@anchor{1bd4}@anchor{tutorial/datastructures tut-del}@anchor{1bd5}
@subsection L'instruction @code{del}


There is a way to remove an item from a list given its index instead of its
value: the @ref{1734,,del} statement.  This differs from the @code{pop()} method
which returns a value.  The @code{del} statement can also be used to remove
slices from a list or clear the entire list (which we did earlier by assignment
of an empty list to the slice).  For example:

@example
>>> a = [-1, 1, 66.25, 333, 333, 1234.5]
>>> del a[0]
>>> a
[1, 66.25, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.25, 1234.5]
>>> del a[:]
>>> a
[]
@end example

@ref{1734,,del} peut aussi être utilisée pour supprimer des variables :

@example
>>> del a
@end example

À partir de là, référencer le nom @code{a} est une erreur (au moins jusqu'à ce qu'une autre valeur lui soit affectée). Vous trouverez d'autres utilisations de la fonction @ref{1734,,del} dans la suite de ce tutoriel.

@node n-uplets et séquences,Ensembles,L'instruction del,Structures de données
@anchor{tutorial/datastructures tuples-and-sequences}@anchor{1bd6}@anchor{tutorial/datastructures tut-tuples}@anchor{1bb4}
@subsection `n'-uplets et séquences


Nous avons vu que les listes et les chaînes de caractères ont beaucoup de propriétés en commun, comme l'indiçage et les opérations sur des tranches. Ce sont deux exemples de `séquences' (voir @ref{1bd7,,Types séquentiels — list@comma{} tuple@comma{} range}). Comme Python est un langage en constante évolution, d'autres types de séquences y seront peut-être ajoutés. Il existe également un autre type standard de séquence : le `n'-uplet (`tuple' en anglais).

Un `n'-uplet consiste en différentes valeurs séparées par des virgules, par exemple :

@example
>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
>>> u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
>>> t[0] = 88888
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
>>> v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])
@end example

Comme vous pouvez le voir, les `n'-uplets sont toujours affichés entre parenthèses, de façon à ce que des `n'-uplets imbriqués soient interprétés correctement ; ils peuvent être saisis avec ou sans parenthèses, même si celles-ci sont souvent nécessaires (notamment lorsqu'un `n'-uplet fait partie d'une expression plus longue). Il n'est pas possible d'affecter de valeur à un élément d'un `n'-uplet ; par contre, il est en revanche possible de créer des `n'-uplets contenant des objets mutables, comme des listes.

Si les `n'-uplets peuvent sembler similaires aux listes, ils sont souvent utilisés dans des cas différents et pour des raisons différentes. Les `n'-uplets sont @ref{97e,,immuables} et contiennent souvent des séquences hétérogènes d'éléments auxquelles on accède par « dissociation » (`unpacking' en anglais, voir plus loin) ou par indice (ou même par attribut dans le cas des @ref{1c5,,namedtuples}). Les listes sont souvent @ref{1b8e,,mutables} et contiennent des éléments généralement homogènes auxquels on accède en itérant sur la liste.

La construction de `n'-uplets ne contenant aucun ou un seul élément est un cas particulier : la syntaxe a quelques tournures spécifiques pour le gérer. Un `n'-uplet vide se construit avec une paire de parenthèses vides ; un `n'-uplet avec un seul élément se construit en faisant suivre la valeur par une virgule (placer cette valeur entre parenthèses ne suffit pas). Pas très joli, mais efficace. Par exemple :

@example
>>> empty = ()
>>> singleton = 'hello',    # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)
@end example

L'instruction @code{t = 12345, 54321, 'hello!'} est un exemple `d'agrégation de *n'-uplet* (`tuple packing' en anglais) : les valeurs @code{12345}, @code{54321} et @code{hello!} sont agrégées ensemble dans un `n'-uplet. L'opération inverse est aussi possible :

@example
>>> x, y, z = t
@end example

Ceci est appelé, de façon plus ou moins appropriée, une `dissociation de séquence' (`sequence unpacking' en anglais) et fonctionne pour toute séquence placée à droite de l'expression. Cette dissociation requiert autant de variables dans la partie gauche qu'il y a d'éléments dans la séquence. Notez également que cette affectation multiple est juste une combinaison entre une agrégation de `n'-uplet et une dissociation de séquence.

@node Ensembles,Dictionnaires,n-uplets et séquences,Structures de données
@anchor{tutorial/datastructures sets}@anchor{1bd8}@anchor{tutorial/datastructures tut-sets}@anchor{1bd9}
@subsection Ensembles


Python fournit également un type de donnée pour les `ensembles'. Un ensemble est une collection non ordonnée sans éléments en double. Un ensemble permet de réaliser des tests d'appartenance ou des suppressions de doublons de manière simple. Les ensembles savent également effectuer les opérations mathématiques telles que les unions, intersections, différences et différences symétriques.

On crée des ensembles en appelant avec des accolades ou avec la fonction @ref{5c3,,set()}. Notez que @code{@{@}} ne crée pas un ensemble vide, mais un dictionnaire (une structure de données dont nous allons parler dans la séquence suivante) vide ; utilisez @code{set()} pour ce cas.

Voici une brève démonstration :

@example
>>> basket = @{'apple', 'orange', 'apple', 'pear', 'orange', 'banana'@}
>>> print(basket)                      # show that duplicates have been removed
@{'orange', 'banana', 'pear', 'apple'@}
>>> 'orange' in basket                 # fast membership testing
True
>>> 'crabgrass' in basket
False

>>> # Demonstrate set operations on unique letters from two words
>>>
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a                                  # unique letters in a
@{'a', 'r', 'b', 'c', 'd'@}
>>> a - b                              # letters in a but not in b
@{'r', 'd', 'b'@}
>>> a | b                              # letters in a or b or both
@{'a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'@}
>>> a & b                              # letters in both a and b
@{'a', 'c'@}
>>> a ^ b                              # letters in a or b but not both
@{'r', 'd', 'b', 'm', 'z', 'l'@}
@end example

Tout comme pour les @ref{1bd2,,listes en compréhension}, il est possible d'écrire des ensembles en compréhension :

@example
>>> a = @{x for x in 'abracadabra' if x not in 'abc'@}
>>> a
@{'r', 'd'@}
@end example

@node Dictionnaires,Techniques de boucles,Ensembles,Structures de données
@anchor{tutorial/datastructures dictionaries}@anchor{1bda}@anchor{tutorial/datastructures tut-dictionaries}@anchor{1bdb}
@subsection Dictionnaires


Another useful data type built into Python is the `dictionary' (see
@ref{ab4,,Les types de correspondances — dict}). Dictionaries are sometimes found in other languages as
"associative memories" or "associative arrays".  Unlike sequences, which are
indexed by a range of numbers, dictionaries are indexed by `keys', which can be
any immutable type; strings and numbers can always be keys.  Tuples can be used
as keys if they contain only strings, numbers, or tuples; if a tuple contains
any mutable object either directly or indirectly, it cannot be used as a key.
You can't use lists as keys, since lists can be modified in place using index
assignments, slice assignments, or methods like @code{append()} and
@code{extend()}.

Le plus simple est de voir un dictionnaire comme un ensemble de paires `clé-valeur' au sein duquel les clés doivent être uniques. Une paire d'accolades crée un dictionnaire vide : @code{@{@}}. Placer une liste de paires clé-valeur séparées par des virgules à l'intérieur des accolades ajoute les valeurs correspondantes au dictionnaire ; c'est également de cette façon que les dictionnaires sont affichés.

Les opérations classiques sur un dictionnaire consistent à stocker une valeur pour une clé et à extraire la valeur correspondant à une clé. Il est également possible de supprimer une paire clé-valeur avec @code{del}. Si vous stockez une valeur pour une clé qui est déjà utilisée, l'ancienne valeur associée à cette clé est perdue. Si vous tentez d'extraire une valeur associée à une clé qui n'existe pas, une exception est levée.

Exécuter @code{list(d)} sur un dictionnaire @code{d} renvoie une liste de toutes les clés utilisées dans le dictionnaire, dans l'ordre d'insertion (si vous voulez qu'elles soient ordonnées, utilisez @code{sorted(d)}). Pour tester si une clé est dans le dictionnaire, utilisez le mot-clé @ref{2e8,,in}.

Voici un petit exemple utilisant un dictionnaire :

@example
>>> tel = @{'jack': 4098, 'sape': 4139@}
>>> tel['guido'] = 4127
>>> tel
@{'jack': 4098, 'sape': 4139, 'guido': 4127@}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
@{'jack': 4098, 'guido': 4127, 'irv': 4127@}
>>> list(tel)
['jack', 'guido', 'irv']
>>> sorted(tel)
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
>>> 'jack' not in tel
False
@end example

Le constructeur @ref{253,,dict()} fabrique un dictionnaire directement à partir d'une liste de paires clé-valeur stockées sous la forme de `n'-uplets :

@example
>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
@{'sape': 4139, 'guido': 4127, 'jack': 4098@}
@end example

De plus, il est possible de créer des dictionnaires en compréhension depuis un jeu de clés et valeurs :

@example
>>> @{x: x**2 for x in (2, 4, 6)@}
@{2: 4, 4: 16, 6: 36@}
@end example

Lorsque les clés sont de simples chaînes de caractères, il est parfois plus facile de définir les paires en utilisant des paramètres nommés :

@example
>>> dict(sape=4139, guido=4127, jack=4098)
@{'sape': 4139, 'guido': 4127, 'jack': 4098@}
@end example

@node Techniques de boucles,Plus d'informations sur les conditions,Dictionnaires,Structures de données
@anchor{tutorial/datastructures looping-techniques}@anchor{1bdc}@anchor{tutorial/datastructures tut-loopidioms}@anchor{1b9e}
@subsection Techniques de boucles


When looping through dictionaries, the key and corresponding value can be
retrieved at the same time using the @ref{7b9,,items()} method.

@example
>>> knights = @{'gallahad': 'the pure', 'robin': 'the brave'@}
>>> for k, v in knights.items():
...     print(k, v)
...
gallahad the pure
robin the brave
@end example

Lorsque vous faites une boucle sur une séquence, la position et la valeur associée peuvent être récupérées en même temps en utilisant la fonction @ref{1433,,enumerate()}.

@example
>>> for i, v in enumerate(['tic', 'tac', 'toe']):
...     print(i, v)
...
0 tic
1 tac
2 toe
@end example

Pour faire une boucle sur deux séquences ou plus en même temps, les éléments peuvent être associés en utilisant la fonction @ref{7ba,,zip()}

@example
>>> questions = ['name', 'quest', 'favorite color']
>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
...     print('What is your @{0@}?  It is @{1@}.'.format(q, a))
...
What is your name?  It is lancelot.
What is your quest?  It is the holy grail.
What is your favorite color?  It is blue.
@end example

Pour faire une boucle en sens inverse sur une séquence, commencez par spécifier la séquence dans son ordre normal, puis appliquez la fonction @ref{850,,reversed()}

@example
>>> for i in reversed(range(1, 10, 2)):
...     print(i)
...
9
7
5
3
1
@end example

Pour faire une boucle sur une séquence de manière ordonnée, utilisez la fonction @ref{bbc,,sorted()} qui renvoie une nouvelle liste ordonnée sans altérer la source

@example
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for i in sorted(basket):
...     print(i)
...
apple
apple
banana
orange
orange
pear
@end example

L'utilisation de la fonction @ref{5c3,,set()} sur une séquence élimine les doublons. Combiner les fonctions @ref{bbc,,sorted()} et @ref{5c3,,set()} sur une séquence est la façon « canonique » d'itérer sur les éléments uniques d'une séquence dans l'ordre.

@example
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
...     print(f)
...
apple
banana
orange
pear
@end example

Il est parfois tentant de modifier une liste pendant que l'on itère dessus. Il est souvent plus simple et plus sûr de créer une nouvelle liste à la place.

@example
>>> import math
>>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5, float('NaN'), 47.8]
>>> filtered_data = []
>>> for value in raw_data:
...     if not math.isnan(value):
...         filtered_data.append(value)
...
>>> filtered_data
[56.2, 51.7, 55.3, 52.5, 47.8]
@end example

@node Plus d'informations sur les conditions,Comparer des séquences avec d'autres types,Techniques de boucles,Structures de données
@anchor{tutorial/datastructures more-on-conditions}@anchor{1bdd}@anchor{tutorial/datastructures tut-conditions}@anchor{1bde}
@subsection Plus d'informations sur les conditions


Les conditions utilisées dans une instruction @code{while} ou @code{if} peuvent contenir n'importe quel opérateur, pas seulement des comparaisons.

Les opérateurs de comparaison @code{in} et @code{not in} testent si une valeur appartient (ou pas) à un conteneur. Les opérateurs @code{is} et @code{is not} testent si deux objets sont vraiment le même objet. Tous les opérateurs de comparaison ont la même priorité, qui est plus faible que celle des opérateurs numériques.

Les comparaisons peuvent être chaînées. Par exemple, @code{a < b == c} teste si @code{a} est inférieur à @code{b} et si, de plus, @code{b} égale @code{c}.

Les comparaisons peuvent être combinées en utilisant les opérateurs booléens @code{and} et @code{or}, le résultat d'une comparaison (ou de toute expression booléenne) pouvant être inversé avec @code{not}. Ces opérateurs ont une priorité inférieure à celle des opérateurs de comparaison ; entre eux, @code{not} a la priorité la plus élevée et @code{or} la plus faible, de telle sorte que @code{A and not B or C} est équivalent à @code{(A and (not B)) or C}. Comme d'habitude, les parenthèses permettent d'exprimer l'instruction désirée.

Les opérateurs booléens @code{and} et @code{or} sont appelés opérateurs `en circuit court' : leurs arguments sont évalués de la gauche vers la droite et l'évaluation s'arrête dès que le résultat est déterminé. Par exemple, si @code{A} et @code{C} sont vrais et @code{B} est faux, @code{A and B and C} n'évalue pas l'expression @code{C}. Lorsqu'elle est utilisée en tant que valeur et non en tant que booléen, la valeur de retour d'un opérateur en circuit court est celle du dernier argument évalué.

Il est possible d'affecter le résultat d'une comparaison ou d'une autre expression booléenne à une variable. Par exemple

@example
>>> string1, string2, string3 = '@w{'}, 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'
@end example

Notez qu'en Python, à la différence du C, une affectation à l'intérieur d'une expression doit être faite explicitement avec @ref{1bdf,,l'opérateur morse} @code{:=}. Cela évite des erreurs fréquentes que l'on rencontre en C, lorsque l'on tape @code{=} alors que l'on voulait faire un test avec @code{==}.

@node Comparer des séquences avec d'autres types,,Plus d'informations sur les conditions,Structures de données
@anchor{tutorial/datastructures comparing-sequences-and-other-types}@anchor{1be0}@anchor{tutorial/datastructures tut-comparing}@anchor{1be1}
@subsection Comparer des séquences avec d'autres types


Des séquences peuvent être comparées avec d'autres séquences du même type. La comparaison utilise un ordre `lexicographique' : les deux premiers éléments de chaque séquence sont comparés et, s'ils diffèrent, cela détermine le résultat de la comparaison ; s'ils sont égaux, les deux éléments suivants sont comparés à leur tour et ainsi de suite jusqu'à ce que l'une des séquences soit épuisée. Si deux éléments à comparer sont eux-mêmes des séquences du même type, alors la comparaison lexicographique est effectuée récursivement. Si tous les éléments des deux séquences sont égaux, les deux séquences sont alors considérées comme égales. Si une séquence est une sous-séquence de l'autre, la séquence la plus courte est celle dont la valeur est inférieure. La comparaison lexicographique des chaînes de caractères utilise le code Unicode des caractères. Voici quelques exemples de comparaisons entre séquences de même type :

@example
(1, 2, 3)              < (1, 2, 4)
[1, 2, 3]              < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4)           < (1, 2, 4)
(1, 2)                 < (1, 2, -1)
(1, 2, 3)             == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab'))   < (1, 2, ('abc', 'a'), 4)
@end example

Comparer des objets de type différents avec @code{<} ou @code{>} est autorisé si les objets ont des méthodes de comparaison appropriées. Par exemple, les types numériques sont comparés via leur valeur numérique, donc @code{0} égale @code{0,0}, etc. Dans les autres cas, au lieu de donner un ordre imprévisible, l'interpréteur lève une exception @ref{522,,TypeError}.

@subsubheading Notes


@node Modules<2>,Les entrées/sorties,Structures de données,Le tutoriel Python
@anchor{tutorial/modules doc}@anchor{1be2}@anchor{tutorial/modules modules}@anchor{1be3}@anchor{tutorial/modules tut-modules}@anchor{1be4}
@section Modules


Lorsque vous quittez et entrez à nouveau dans l'interpréteur Python, tout ce que vous avez déclaré dans la session précédente est perdu. Afin de rédiger des programmes plus longs, vous devez utiliser un éditeur de texte, préparer votre code dans un fichier et exécuter Python avec ce fichier en paramètre. Cela s'appelle créer un `script'. Lorsque votre programme grandit, vous pouvez séparer votre code dans plusieurs fichiers. Ainsi, il vous est facile de réutiliser des fonctions écrites pour un programme dans un autre sans avoir à les copier.

Pour gérer cela, Python vous permet de placer des définitions dans un fichier et de les utiliser dans un script ou une session interactive. Un tel fichier est appelé un `module' et les définitions d'un module peuvent être importées dans un autre module ou dans le module `main' (qui est le module qui contient vos variables et définitions lors de l'exécution d'un script au niveau le plus haut ou en mode interactif).

Un module est un fichier contenant des définitions et des instructions. Son nom de fichier est le nom du module suffixé de @code{.py}. À l'intérieur d'un module, son propre nom est accessible par la variable @code{__name__}. Par exemple, prenez votre éditeur favori et créez un fichier @code{fibo.py} dans le répertoire courant qui contient :

@example
# Fibonacci numbers module

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
    result = []
    a, b = 0, 1
    while a < n:
        result.append(a)
        a, b = b, a+b
    return result
@end example

Maintenant, ouvrez un interpréteur et importez le module en tapant :

@example
>>> import fibo
@end example

Les noms des fonctions définies dans @code{fibo} ne sont pas ajoutés directement dans l'@ref{1be5,,espace de nommage} courant (voir @ref{1be6,,Portées et espaces de nommage en Python} pour plus de détails), seul le nom de module @code{fibo} est ajouté. L'appel des fonctions se fait donc `via' le nom du module :

@example
>>> fibo.fib(1000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'
@end example

Si vous avez l'intention d'utiliser souvent une fonction, il est possible de lui assigner un nom local :

@example
>>> fib = fibo.fib
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

@menu
* Les modules en détail:: 
* Modules standards:: 
* La fonction dir(): La fonction dir. 
* Les paquets:: 

@end menu

@node Les modules en détail,Modules standards,,Modules<2>
@anchor{tutorial/modules more-on-modules}@anchor{1be7}@anchor{tutorial/modules tut-moremodules}@anchor{1be8}
@subsection Les modules en détail


Un module peut contenir aussi bien des instructions que des déclarations de fonctions. Ces instructions permettent d'initialiser le module. Elles ne sont exécutées que la `première' fois que le nom d'un module est trouvé dans un @code{import} @footnote{
En réalité, la déclaration d'une fonction est elle-même une instruction ; son exécution ajoute le nom de la fonction dans l'espace de nommage global du module.
} (elles sont aussi exécutées lorsque le fichier est exécuté en tant que script).

Chaque module possède son propre espace de nommage, utilisé comme espace de nommage global par toutes les fonctions définies par le module. Ainsi l'auteur d'un module peut utiliser des variables globales dans un module sans se soucier de collisions de noms avec des variables globales définies par l'utilisateur du module. Cependant, si vous savez ce que vous faites, vous pouvez modifier une variable globale d'un module avec la même notation que pour accéder aux fonctions : @code{nommodule.nomelement}.

Des modules peuvent importer d'autres modules. Il est courant, mais pas obligatoire, de ranger tous les @ref{5cc,,import} au début du module (ou du script). Les noms des modules importés, s'ils sont placés au début d'un module (en dehors des fonctions et des classes) sont ajoutés à l'espace de nommage global du module.

Il existe une variante de l'instruction @ref{5cc,,import} qui importe les noms d'un module directement dans l'espace de nommage du module qui l'importe, par exemple :

@example
>>> from fibo import fib, fib2
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

Cela n'insère pas le nom du module depuis lequel les définitions sont récupérées dans l'espace de nommage local (dans cet exemple, @code{fibo} n'est pas défini).

Il existe même une variante permettant d'importer tous les noms qu'un module définit :

@example
>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

Tous les noms ne commençant pas par un tiret bas (@code{_}) sont importés. Dans la grande majorité des cas, les développeurs n'utilisent pas cette syntaxe puisqu'en important un ensemble indéfini de noms, des noms déjà définis peuvent se retrouver masqués.

Notez qu'en général, importer @code{*} d'un module ou d'un paquet est déconseillé. Souvent, le code devient difficilement lisible. Son utilisation en mode interactif est acceptée pour gagner quelques secondes.

Si le nom du module est suivi par @code{as}, alors le nom suivant @code{as} est directement lié au module importé.

@example
>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

Dans les faits, le module est importé de la même manière qu'avec @code{import fibo}, la seule différence est qu'il sera disponible sous le nom de @code{fib}.

C'est aussi valide en utilisant @ref{1289,,from}, et a le même effet :

@example
>>> from fibo import fib as fibonacci
>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
@end example

@cartouche
@quotation Note 
pour des raisons d’efficacité, chaque module n’est importé qu’une fois par session de l’interpréteur. Par conséquent, si vous modifiez vos modules, vous devez redémarrer l’interpréteur — ou, si c’est juste un module que vous voulez tester interactivement, utilisez @ref{502,,importlib.reload()}, par exemple @code{import importlib ; importlib.reload(modulename)}.
@end quotation
@end cartouche

@menu
* Exécuter des modules comme des scripts:: 
* Les dossiers de recherche de modules:: 
* Fichiers Python « compilés »:: 

@end menu

@node Exécuter des modules comme des scripts,Les dossiers de recherche de modules,,Les modules en détail
@anchor{tutorial/modules executing-modules-as-scripts}@anchor{1be9}@anchor{tutorial/modules tut-modulesasscripts}@anchor{1bea}
@subsubsection Exécuter des modules comme des scripts


Lorsque vous exécutez un module Python avec

@example
python fibo.py <arguments>
@end example

le code du module est exécuté comme si vous l'aviez importé mais son @code{__name__} vaut @code{"__main__"}. Donc, en ajoutant ces lignes à la fin du module :

@example
if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))
@end example

vous pouvez rendre le fichier utilisable comme script aussi bien que comme module importable, car le code qui analyse la ligne de commande n'est lancé que si le module est exécuté comme fichier « main » :

@example
$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34
@end example

Si le fichier est importé, le code n'est pas exécuté :

@example
>>> import fibo
>>>
@end example

C'est typiquement utilisé soit pour proposer une interface utilisateur pour un module, soit pour lancer les tests sur le module (exécuter le module en tant que script lance les tests).

@node Les dossiers de recherche de modules,Fichiers Python « compilés »,Exécuter des modules comme des scripts,Les modules en détail
@anchor{tutorial/modules the-module-search-path}@anchor{1beb}@anchor{tutorial/modules tut-searchpath}@anchor{1bec}
@subsubsection Les dossiers de recherche de modules


@geindex module;search;path

When a module named @code{spam} is imported, the interpreter first searches for
a built-in module with that name. These module names are listed in
@ref{1bed,,sys.builtin_module_names}. If not found, it then searches for a file
named @code{spam.py} in a list of directories given by the variable
@ref{3ab,,sys.path}.  @ref{3ab,,sys.path} is initialized from these locations:


@itemize *

@item 
le dossier contenant le script courant (ou le dossier courant si aucun script n'est donné) ;

@item 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} (une liste de dossiers, utilisant la même syntaxe que la variable shell 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}) ;

@item 
La valeur par défaut, qui dépend de l'installation (incluant par convention un dossier @code{site-packages}, géré par le module @ref{c6,,site}).
@end itemize

Vous trouverez plus de détails dans @ref{1bee,,The initialization of the sys.path module search path}.

@cartouche
@quotation Note 
sur les systèmes qui gèrent les liens symboliques, le dossier contenant le script courant est résolu après avoir suivi le lien symbolique du script. Autrement dit, le dossier contenant le lien symbolique n'est `pas' ajouté aux dossiers de recherche de modules.
@end quotation
@end cartouche

Après leur initialisation, les programmes Python peuvent modifier leur @ref{3ab,,sys.path}. Le dossier contenant le script courant est placé au début de la liste des dossiers à rechercher, avant les dossiers de bibliothèques. Cela signifie qu'un module dans ce dossier, ayant le même nom qu'un module, sera chargé à sa place. C'est une erreur typique, à moins que ce ne soit voulu. Voir @ref{1bef,,Modules standards} pour plus d'informations.

@c %
@c Do we need stuff on zip files etc. ? DUBOIS

@node Fichiers Python « compilés »,,Les dossiers de recherche de modules,Les modules en détail
@anchor{tutorial/modules compiled-python-files}@anchor{1bf0}@anchor{tutorial/modules tut-pycache}@anchor{6c6}
@subsubsection Fichiers Python « compilés »


Pour accélérer le chargement des modules, Python cache une version compilée de chaque module dans un fichier nommé @code{module(version).pyc} (ou `version' représente le format du fichier compilé, typiquement une version de Python) dans le dossier @code{__pycache__}. Par exemple, avec CPython 3.3, la version compilée de `spam.py' serait @code{__pycache__/spam.cpython-33.pyc}. Cette règle de nommage permet à des versions compilées par des versions différentes de Python de coexister.

Python compare les dates de modification du fichier source et de sa version compilée pour voir si le module doit être recompilé. Ce processus est entièrement automatique. Par ailleurs, les versions compilées sont indépendantes de la plateforme et peuvent donc être partagées entre des systèmes d'architectures différentes.

Il existe deux situations où Python ne vérifie pas le cache : le premier cas est lorsque le module est donné par la ligne de commande (cas où le module est toujours recompilé, sans même cacher sa version compilée) ; le second cas est lorsque le module n'a pas de source. Pour gérer un module sans source (où seule la version compilée est fournie), le module compilé doit se trouver dans le dossier source et sa source ne doit pas être présente.

Astuces pour les experts :


@itemize *

@item 
vous pouvez utiliser les options @ref{da2,,-O} ou @ref{da3,,-OO} lors de l'appel à Python pour réduire la taille des modules compilés. L'option @code{-O} supprime les instructions @code{assert} et l'option @code{-OO} supprime aussi les documentations @code{__doc__}. Cependant, puisque certains programmes ont besoin de ces @code{__doc__}, vous ne devriez utiliser @code{-OO} que si vous savez ce que vous faites. Les modules « optimisés » sont marqués d'un @code{opt-} et sont généralement plus petits. Les versions futures de Python pourraient changer les effets de l'optimisation ;

@item 
un programme ne s'exécute pas plus vite lorsqu'il est lu depuis un @code{.pyc}, il est juste chargé plus vite ;

@item 
le module @ref{20,,compileall} peut créer des fichiers @code{.pyc} pour tous les modules d'un dossier ;

@item 
vous trouvez plus de détails sur ce processus, ainsi qu'un organigramme des décisions, dans la 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}.
@end itemize

@node Modules standards,La fonction dir,Les modules en détail,Modules<2>
@anchor{tutorial/modules standard-modules}@anchor{1bf1}@anchor{tutorial/modules tut-standardmodules}@anchor{1bef}
@subsection Modules standards


@geindex module;sys

Python est accompagné d'une bibliothèque de modules standards, décrits dans la documentation de la Bibliothèque Python, plus loin. Certains modules sont intégrés dans l'interpréteur, ils proposent des outils qui ne font pas partie du langage mais qui font tout de même partie de l'interpréteur, soit pour le côté pratique, soit pour mettre à disposition des outils essentiels tels que l'accès aux appels système. La composition de ces modules est configurable à la compilation et dépend aussi de la plateforme cible. Par exemple, le module @ref{115,,winreg} n'est proposé que sur les systèmes Windows. Un module mérite une attention particulière, le module @ref{d8,,sys}, qui est présent dans tous les interpréteurs Python. Les variables @code{sys.ps1} et @code{sys.ps2} définissent les chaînes d'invites principales et secondaires :

@example
>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>
@end example

Ces deux variables ne sont définies que si l'interpréteur est en mode interactif.

La variable @code{sys.path} est une liste de chaînes qui détermine les chemins de recherche de modules pour l'interpréteur. Elle est initialisée à un chemin par défaut pris de la variable d'environnement 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} ou d'une valeur par défaut interne si 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} n'est pas définie. @code{sys.path} est modifiable en utilisant les opérations habituelles des listes :

@example
>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')
@end example

@node La fonction dir,Les paquets,Modules standards,Modules<2>
@anchor{tutorial/modules the-dir-function}@anchor{1bf2}@anchor{tutorial/modules tut-dir}@anchor{1bf3}
@subsection La fonction @code{dir()}


La fonction interne @ref{61d,,dir()} est utilisée pour trouver quels noms sont définis par un module. Elle donne une liste de chaînes classées par ordre lexicographique :

@example
>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)  
['__breakpointhook__', '__displayhook__', '__doc__', '__excepthook__',
 '__interactivehook__', '__loader__', '__name__', '__package__', '__spec__',
 '__stderr__', '__stdin__', '__stdout__', '__unraisablehook__',
 '_clear_type_cache', '_current_frames', '_debugmallocstats', '_framework',
 '_getframe', '_git', '_home', '_xoptions', 'abiflags', 'addaudithook',
 'api_version', 'argv', 'audit', 'base_exec_prefix', 'base_prefix',
 'breakpointhook', 'builtin_module_names', 'byteorder', 'call_tracing',
 'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',
 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',
 'float_repr_style', 'get_asyncgen_hooks', 'get_coroutine_origin_tracking_depth',
 'getallocatedblocks', 'getdefaultencoding', 'getdlopenflags',
 'getfilesystemencodeerrors', 'getfilesystemencoding', 'getprofile',
 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',
 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
 'intern', 'is_finalizing', 'last_traceback', 'last_type', 'last_value',
 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks',
 'path_importer_cache', 'platform', 'prefix', 'ps1', 'ps2', 'pycache_prefix',
 'set_asyncgen_hooks', 'set_coroutine_origin_tracking_depth', 'setdlopenflags',
 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr',
 'stdin', 'stdout', 'thread_info', 'unraisablehook', 'version', 'version_info',
 'warnoptions']
@end example

Sans paramètre, @ref{61d,,dir()} liste les noms actuellement définis :

@example
>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']
@end example

Notez qu'elle liste tous les types de noms : les variables, fonctions, modules, etc.

@geindex module;builtins

@ref{61d,,dir()} ne liste ni les fonctions primitives, ni les variables internes. Si vous voulez les lister, elles sont définies dans le module @ref{12,,builtins} :

@example
>>> import builtins
>>> dir(builtins)  
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
 'NotImplementedError', 'OSError', 'OverflowError',
 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
 'zip']
@end example

@node Les paquets,,La fonction dir,Modules<2>
@anchor{tutorial/modules packages}@anchor{1bf4}@anchor{tutorial/modules tut-packages}@anchor{1bf5}
@subsection Les paquets


Packages are a way of structuring Python's module namespace by using "dotted
module names".  For example, the module name @code{A.B} designates a submodule
named @code{B} in a package named @code{A}.  Just like the use of modules saves the
authors of different modules from having to worry about each other's global
variable names, the use of dotted module names saves the authors of multi-module
packages like NumPy or Pillow from having to worry about
each other's module names.

Imaginez que vous voulez construire un ensemble de modules (un « paquet ») pour gérer uniformément les fichiers contenant du son et des données sonores. Il existe un grand nombre de formats de fichiers pour stocker du son (généralement identifiés par leur extension, par exemple @code{.wav}, @code{.aiff}, @code{.au}), vous avez donc besoin de créer et maintenir un nombre croissant de modules pour gérer la conversion entre tous ces formats. Vous voulez aussi pouvoir appliquer un certain nombre d'opérations sur ces sons : mixer, ajouter de l'écho, égaliser, ajouter un effet stéréo artificiel, etc. Donc, en plus des modules de conversion, vous allez écrire une myriade de modules permettant d'effectuer ces opérations. Voici une structure possible pour votre paquet (exprimée sous la forme d'une arborescence de fichiers) :

@example
sound/                          Top-level package
      __init__.py               Initialize the sound package
      formats/                  Subpackage for file format conversions
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      effects/                  Subpackage for sound effects
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...
      filters/                  Subpackage for filters
              __init__.py
              equalizer.py
              vocoder.py
              karaoke.py
              ...
@end example

Lorsqu'il importe des paquets, Python cherche dans chaque dossier de @code{sys.path} un sous-dossier du nom du paquet.

The @code{__init__.py} files are required to make Python treat directories
containing the file as packages (unless using a @ref{1bf6,,namespace package}, a
relatively advanced feature). This prevents directories with a common name,
such as @code{string}, from unintentionally hiding valid modules that occur later
on the module search path. In the simplest case, @code{__init__.py} can just be
an empty file, but it can also execute initialization code for the package or
set the @code{__all__} variable, described later.

Les utilisateurs d'un module peuvent importer ses modules individuellement, par exemple :

@example
import sound.effects.echo
@end example

This loads the submodule @code{sound.effects.echo}.  It must be referenced with
its full name.

@example
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
@end example

Une autre manière d'importer des sous-modules est :

@example
from sound.effects import echo
@end example

This also loads the submodule @code{echo}, and makes it available without its
package prefix, so it can be used as follows:

@example
echo.echofilter(input, output, delay=0.7, atten=4)
@end example

Une autre méthode consiste à importer la fonction ou la variable désirée directement :

@example
from sound.effects.echo import echofilter
@end example

Again, this loads the submodule @code{echo}, but this makes its function
@code{echofilter()} directly available:

@example
echofilter(input, output, delay=0.7, atten=4)
@end example

Notez que lorsque vous utilisez @code{from package import element}, @code{element} peut aussi bien être un sous-module, un sous-paquet ou simplement un nom déclaré dans le paquet (une variable, une fonction ou une classe). L'instruction @code{import} cherche en premier si @code{element} est défini dans le paquet ; s'il ne l'est pas, elle cherche à charger un module et, si elle n'en trouve pas, une exception @ref{40f,,ImportError} est levée.

Au contraire, en utilisant la syntaxe @code{import element.souselement.soussouselement}, chaque @code{element} sauf le dernier doit être un paquet. Le dernier @code{element} peut être un module ou un paquet, mais ne peut être ni une fonction, ni une classe, ni une variable définie dans l'élément précédent.

@menu
* Importer * depuis un paquet:: 
* Références internes dans un paquet:: 
* Paquets dans plusieurs dossiers:: 

@end menu

@node Importer * depuis un paquet,Références internes dans un paquet,,Les paquets
@anchor{tutorial/modules importing-from-a-package}@anchor{1bf7}@anchor{tutorial/modules tut-pkg-import-star}@anchor{1bf8}
@subsubsection Importer * depuis un paquet


@geindex __all__

Qu'arrive-t-il lorsqu'un utilisateur écrit @code{from sound.effects import *} ? Idéalement, on pourrait espérer que Python aille chercher tous les sous-modules du paquet sur le système de fichiers et qu'ils seraient tous importés. Cela pourrait être long et importer certains sous-modules pourrait avoir des effets secondaires indésirables ou, du moins, désirés seulement lorsque le sous-module est importé explicitement.

La seule solution, pour l'auteur du paquet, est de fournir un index explicite du contenu du paquet. L'instruction @ref{5cc,,import} utilise la convention suivante : si le fichier @code{__init__.py} du paquet définit une liste nommée @code{__all__}, cette liste est utilisée comme liste des noms de modules devant être importés lorsque @code{from package import *} est utilisé. Il est de la responsabilité de l'auteur du paquet de maintenir cette liste à jour lorsque de nouvelles versions du paquet sont publiées. Un auteur de paquet peut aussi décider de ne pas autoriser d'importer @code{*} pour son paquet. Par exemple, le fichier @code{sound/effects/__init__.py} peut contenir le code suivant :

@example
__all__ = ["echo", "surround", "reverse"]
@end example

This would mean that @code{from sound.effects import *} would import the three
named submodules of the @code{sound.effects} package.

Be aware that submodules might become shadowed by locally defined names. For
example, if you added a @code{reverse} function to the
@code{sound/effects/__init__.py} file, the @code{from sound.effects import *}
would only import the two submodules @code{echo} and @code{surround}, but `not' the
@code{reverse} submodule, because it is shadowed by the locally defined
@code{reverse} function:

@example
__all__ = [
    "echo",      # refers to the 'echo.py' file
    "surround",  # refers to the 'surround.py' file
    "reverse",   # !!! refers to the 'reverse' function now !!!
]

def reverse(msg: str):  # <-- this name shadows the 'reverse.py' submodule
    return msg[::-1]    #     in the case of a 'from sound.effects import *'
@end example

If @code{__all__} is not defined, the statement @code{from sound.effects import *}
does `not' import all submodules from the package @code{sound.effects} into the
current namespace; it only ensures that the package @code{sound.effects} has
been imported (possibly running any initialization code in @code{__init__.py})
and then imports whatever names are defined in the package.  This includes any
names defined (and submodules explicitly loaded) by @code{__init__.py}.  It
also includes any submodules of the package that were explicitly loaded by
previous @ref{5cc,,import} statements.  Consider this code:

@example
import sound.effects.echo
import sound.effects.surround
from sound.effects import *
@end example

In this example, the @code{echo} and @code{surround} modules are imported in the
current namespace because they are defined in the @code{sound.effects} package
when the @code{from...import} statement is executed.  (This also works when
@code{__all__} is defined.)

Bien que certains modules ont été pensés pour n'exporter que les noms respectant une certaine structure lorsque @code{import *} est utilisé, @code{import *} reste considéré comme une mauvaise pratique dans du code à destination d'un environnement de production.

Rappelez-vous que rien ne vous empêche d'utiliser @code{from paquet import sous_module_specifique} ! C'est d'ailleurs la manière recommandée, à moins que le module qui fait les importations ait besoin de sous-modules ayant le même nom mais provenant de paquets différents.

@node Références internes dans un paquet,Paquets dans plusieurs dossiers,Importer * depuis un paquet,Les paquets
@anchor{tutorial/modules id2}@anchor{1bf9}@anchor{tutorial/modules intra-package-references}@anchor{1bfa}
@subsubsection Références internes dans un paquet


When packages are structured into subpackages (as with the @code{sound} package
in the example), you can use absolute imports to refer to submodules of siblings
packages.  For example, if the module @code{sound.filters.vocoder} needs to use
the @code{echo} module in the @code{sound.effects} package, it can use @code{from
sound.effects import echo}.

You can also write relative imports, with the @code{from module import name} form
of import statement.  These imports use leading dots to indicate the current and
parent packages involved in the relative import.  From the @code{surround}
module for example, you might use:

@example
from . import echo
from .. import formats
from ..filters import equalizer
@end example

Notez que les importations relatives se fient au nom du module actuel. Puisque le nom du module principal est toujours @code{"__main__"}, les modules utilisés par le module principal d'une application ne peuvent être importés que par des importations absolues.

@node Paquets dans plusieurs dossiers,,Références internes dans un paquet,Les paquets
@anchor{tutorial/modules packages-in-multiple-directories}@anchor{1bfb}
@subsubsection Paquets dans plusieurs dossiers


Packages support one more special attribute, @ref{1bfc,,__path__}.  This is
initialized to be a @ref{4db,,sequence} of strings containing the name of the
directory holding the
package's @code{__init__.py} before the code in that file is executed.  This
variable can be modified; doing so affects future searches for modules and
subpackages contained in the package.

Bien que cette fonctionnalité ne soit que rarement utile, elle peut servir à élargir la liste des modules trouvés dans un paquet.

@subsubheading Notes


@node Les entrées/sorties,Erreurs et exceptions,Modules<2>,Le tutoriel Python
@anchor{tutorial/inputoutput doc}@anchor{1bfd}@anchor{tutorial/inputoutput input-and-output}@anchor{1bfe}@anchor{tutorial/inputoutput tut-io}@anchor{1bff}
@section Les entrées/sorties


Il existe bien des moyens de présenter les sorties d'un programme ; les données peuvent être affichées sous une forme lisible par un être humain ou sauvegardées dans un fichier pour une utilisation future. Ce chapitre présente quelques possibilités.

@menu
* Formatage de données:: 
* Lecture et écriture de fichiers:: 

@end menu

@node Formatage de données,Lecture et écriture de fichiers,,Les entrées/sorties
@anchor{tutorial/inputoutput fancier-output-formatting}@anchor{1c00}@anchor{tutorial/inputoutput tut-formatting}@anchor{1c01}
@subsection Formatage de données


So far we've encountered two ways of writing values: `expression statements' and
the @ref{f60,,print()} function.  (A third way is using the @ref{1c02,,write()} method
of file objects; the standard output file can be referenced as @code{sys.stdout}.
See the Library Reference for more information on this.)

Souvent vous voudrez plus de contrôle sur le formatage de vos sorties et aller au delà d’un affichage de valeurs séparées par des espaces. Il y a plusieurs moyens de les formater.


@itemize *

@item 
Pour utiliser @ref{1c03,,les expressions formatées}, commencez une chaine de caractère avec @code{f} ou @code{F} avant d’ouvrir vos guillemets doubles ou triples. Dans ces chaines de caractère, vous pouvez entrer des expressions Python entre les caractères @code{@{} et @code{@}} qui peuvent contenir des variables ou des valeurs littérales.

@example
>>> year = 2016
>>> event = 'Referendum'
>>> f'Results of the @{year@} @{event@}'
'Results of the 2016 Referendum'
@end example

@item 
The @ref{60c,,str.format()} method of strings requires more manual
effort.  You'll still use @code{@{} and @code{@}} to mark where a variable
will be substituted and can provide detailed formatting directives,
but you'll also need to provide the information to be formatted. In the following code
block there are two examples of how to format variables:

@example
>>> yes_votes = 42_572_654
>>> total_votes = 85_705_149
>>> percentage = yes_votes / total_votes
>>> '@{:-9@} YES votes  @{:2.2%@}'.format(yes_votes, percentage)
' 42572654 YES votes  49.67%'
@end example

Notice how the @code{yes_votes} are padded with spaces and a negative sign only for negative numbers.
The example also prints @code{percentage} multiplied by 100, with 2 decimal
places and followed by a percent sign (see @ref{1e5,,Mini-langage de spécification de format} for details).

@item 
Enfin, vous pouvez construire des concaténations de tranches de chaînes vous-même, et ainsi créer n'importe quel agencement. Le type des chaînes a des méthodes utiles pour aligner des chaînes dans une largeur de taille fixe.
@end itemize

Lorsque qu'un affichage basique suffit, pour afficher simplement une variable pour en inspecter le contenu, vous pouvez convertir n'importe quelle valeur en chaîne de caractères en utilisant la fonction @ref{7e7,,repr()} ou la fonction @ref{435,,str()}.

La fonction @ref{435,,str()} est destinée à représenter les valeurs sous une forme lisible par un être humain, alors que la fonction @ref{7e7,,repr()} est destinée à générer des représentations qui puissent être lues par l'interpréteur (ou qui lèvera une @ref{18b,,SyntaxError} s'il n'existe aucune syntaxe équivalente). Pour les objets qui n'ont pas de représentation humaine spécifique, @ref{435,,str()} renvoie la même valeur que @ref{7e7,,repr()}. Beaucoup de valeurs, comme les nombres ou les structures telles que les listes ou les dictionnaires, ont la même représentation en utilisant les deux fonctions. Les chaînes de caractères, en particulier, ont deux représentations distinctes.

Quelques exemples :

@example
>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
>>> hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print(hellos)
'hello, world\n'
>>> # The argument to repr() may be any Python object:
>>> repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"
@end example

Le module @ref{d2,,string} contient une classe @ref{672,,Template} qui permet aussi de remplacer des valeurs au sein de chaînes de caractères, en utilisant des marqueurs comme @code{$x}, et en les remplaçant par les valeurs d'un dictionnaire, mais sa capacité à formater les chaînes est plus limitée.

@geindex formatted string literal
@geindex interpolated string literal
@geindex string;formatted literal
@geindex string;interpolated literal
@geindex f-string
@geindex fstring

@menu
* Les chaines de caractères formatées (f-strings): Les chaines de caractères formatées f-strings. 
* La méthode de chaine de caractères format(): La méthode de chaine de caractères format. 
* Formatage de chaînes à la main:: 
* Anciennes méthodes de formatage de chaînes:: 

@end menu

@node Les chaines de caractères formatées f-strings,La méthode de chaine de caractères format,,Formatage de données
@anchor{tutorial/inputoutput formatted-string-literals}@anchor{1c04}@anchor{tutorial/inputoutput tut-f-strings}@anchor{1c03}
@subsubsection Les chaines de caractères formatées (`f-strings')


@ref{997,,Les chaines de caractères formatées} (aussi appelées f-strings) vous permettent d’inclure la valeur d’expressions Python dans des chaines de caractères en les préfixant avec @code{f} ou @code{F} et écrire des expressions comme @code{@{expression@}}.

L'expression peut être suivie d'un spécificateur de format. Cela permet un plus grand contrôle sur la façon dont la valeur est rendue. L'exemple suivant arrondit pi à trois décimales après la virgule :

@example
>>> import math
>>> print(f'The value of pi is approximately @{math.pi:.3f@}.')
The value of pi is approximately 3.142.
@end example

Donner un entier après le @code{':'} indique la largeur minimale de ce champ en nombre de caractères. C'est utile pour faire de jolis tableaux

@example
>>> table = @{'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678@}
>>> for name, phone in table.items():
...     print(f'@{name:10@} ==> @{phone:10d@}')
...
Sjoerd     ==>       4127
Jack       ==>       4098
Dcab       ==>       7678
@end example

D’autres modificateurs peuvent être utilisés pour convertir la valeur avant son formatage. @code{'!a'} applique @ref{139d,,ascii()}, @code{'!s'} applique @ref{435,,str()}, et @code{'!r'} applique @ref{7e7,,repr()} :

@example
>>> animals = 'eels'
>>> print(f'My hovercraft is full of @{animals@}.')
My hovercraft is full of eels.
>>> print(f'My hovercraft is full of @{animals!r@}.')
My hovercraft is full of 'eels'.
@end example

Le spécificateur @code{=} peut être utilisé pour développer une expression en « texte de l'expression, un signe égal, puis la représentation de l'expression évaluée » :

@example
>>> bugs = 'roaches'
>>> count = 13
>>> area = 'living room'
>>> print(f'Debugging @{bugs=@} @{count=@} @{area=@}')
Debugging bugs='roaches' count=13 area='living room'
@end example

Lisez @ref{995,,self-documenting expressions} pour davantage d'information sur le spécificateur @code{=}. Pour une référence sur ces spécifications de formats, voir le guide de référence pour le @ref{1e5,,Mini-langage de spécification de format}.

@node La méthode de chaine de caractères format,Formatage de chaînes à la main,Les chaines de caractères formatées f-strings,Formatage de données
@anchor{tutorial/inputoutput the-string-format-method}@anchor{1c05}@anchor{tutorial/inputoutput tut-string-format}@anchor{1c06}
@subsubsection La méthode de chaine de caractères @code{format()}


L'utilisation de base de la méthode @ref{60c,,str.format()} ressemble à ceci :

@example
>>> print('We are the @{@} who say "@{@}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"
@end example

Les accolades et les caractères à l'intérieur (appelés les champs de formatage) sont remplacés par les objets passés en paramètres à la méthode @ref{60c,,str.format()}. Un nombre entre accolades se réfère à la position de l'objet passé à la méthode @ref{60c,,str.format()}.

@example
>>> print('@{0@} and @{1@}'.format('spam', 'eggs'))
spam and eggs
>>> print('@{1@} and @{0@}'.format('spam', 'eggs'))
eggs and spam
@end example

Si des arguments nommés sont utilisés dans la méthode @ref{60c,,str.format()}, leurs valeurs sont utilisées en se basant sur le nom des arguments

@example
>>> print('This @{food@} is @{adjective@}.'.format(
...       food='spam', adjective='absolutely horrible'))
This spam is absolutely horrible.
@end example

Les arguments positionnés et nommés peuvent être combinés arbitrairement :

@example
>>> print('The story of @{0@}, @{1@}, and @{other@}.'.format('Bill', 'Manfred',
...                                                    other='Georg'))
The story of Bill, Manfred, and Georg.
@end example

Si vous avez une chaîne de formatage vraiment longue que vous ne voulez pas découper, il est possible de référencer les variables à formater par leur nom plutôt que par leur position. Utilisez simplement un dictionnaire et la notation entre crochets @code{'[]'} pour accéder aux clés

@example
>>> table = @{'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678@}
>>> print('Jack: @{0[Jack]:d@}; Sjoerd: @{0[Sjoerd]:d@}; '
...       'Dcab: @{0[Dcab]:d@}'.format(table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
@end example

Vous pouvez obtenir le même résultat en passant le dictionnaire @code{table} comme des arguments nommés en utilisant la notation @code{**}

@example
>>> table = @{'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678@}
>>> print('Jack: @{Jack:d@}; Sjoerd: @{Sjoerd:d@}; Dcab: @{Dcab:d@}'.format(**table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
@end example

This is particularly useful in combination with the built-in function
@ref{19d0,,vars()}, which returns a dictionary containing all local variables:

@example
>>> table = @{k: str(v) for k, v in vars().items()@}
>>> message = " ".join([f'@{k@}: ' + '@{' + k +'@};' for k in table.keys()])
>>> print(message.format(**table))
__name__: __main__; __doc__: None; __package__: None; __loader__: ...
@end example

À titre d’exemple, les lignes suivantes produisent un ensemble de colonnes alignées de façon ordonnée donnant les entiers, leurs carrés et leurs cubes :

@example
>>> for x in range(1, 11):
...     print('@{0:2d@} @{1:3d@} @{2:4d@}'.format(x, x*x, x*x*x))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000
@end example

Pour avoir une description complète du formatage des chaînes de caractères avec la méthode @ref{60c,,str.format()}, lisez : @ref{1367,,Syntaxe de formatage de chaîne}.

@node Formatage de chaînes à la main,Anciennes méthodes de formatage de chaînes,La méthode de chaine de caractères format,Formatage de données
@anchor{tutorial/inputoutput manual-string-formatting}@anchor{1c07}
@subsubsection Formatage de chaînes à la main


Voici le même tableau de carrés et de cubes, formaté à la main :

@example
>>> for x in range(1, 11):
...     print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ')
...     # Note use of 'end' on previous line
...     print(repr(x*x*x).rjust(4))
...
 1   1    1
 2   4    8
 3   9   27
 4  16   64
 5  25  125
 6  36  216
 7  49  343
 8  64  512
 9  81  729
10 100 1000
@end example

(Remarquez que l'espace séparant les colonnes vient de la manière dont @ref{f60,,print()} fonctionne : il ajoute toujours des espaces entre ses arguments.)

La méthode @ref{1c08,,str.rjust()} des chaînes de caractères justifie à droite une chaîne dans un champ d'une largeur donnée en ajoutant des espaces sur la gauche. Il existe des méthodes similaires @ref{1c09,,str.ljust()} et @ref{1c0a,,str.center()}. Ces méthodes n'écrivent rien, elles renvoient simplement une nouvelle chaîne. Si la chaîne passée en paramètre est trop longue, elle n'est pas tronquée mais renvoyée sans modification ; cela peut chambouler votre mise en page mais c'est souvent préférable à l'alternative, qui pourrait mentir sur une valeur (et si vous voulez vraiment tronquer vos valeurs, vous pouvez toujours utiliser une tranche, comme dans @code{x.ljust(n)[:n]}).

Il existe une autre méthode, @ref{1466,,str.zfill()}, qui comble une chaîne numérique à gauche avec des zéros. Elle comprend les signes plus et moins :

@example
>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'
@end example

@node Anciennes méthodes de formatage de chaînes,,Formatage de chaînes à la main,Formatage de données
@anchor{tutorial/inputoutput old-string-formatting}@anchor{1c0b}
@subsubsection Anciennes méthodes de formatage de chaînes


The % operator (modulo) can also be used for string formatting.
Given @code{format % values} (where `format' is a string),
@code{%} conversion specifications in `format' are replaced with
zero or more elements of `values'.
This operation is commonly known as string
interpolation. For example:

@example
>>> import math
>>> print('The value of pi is approximately %5.3f.' % math.pi)
The value of pi is approximately 3.142.
@end example

Vous trouvez plus d'informations dans la section @ref{6b7,,Formatage de chaines à la printf}.

@node Lecture et écriture de fichiers,,Formatage de données,Les entrées/sorties
@anchor{tutorial/inputoutput reading-and-writing-files}@anchor{1c0c}@anchor{tutorial/inputoutput tut-files}@anchor{1c0d}
@subsection Lecture et écriture de fichiers


@geindex built-in function;open
@geindex object;file

La fonction @ref{505,,open()} renvoie un @ref{11a0,,objet fichier} et est le plus souvent utilisée avec deux arguments positionnels et un argument nommé : @code{open(filename, mode, encoding=None)}

@example
>>> f = open('workfile', 'w', encoding="utf-8")
@end example

@c XXX str(f) is <io.TextIOWrapper object at 0x82e8dc4>
@c 
@c >>> print(f)
@c <open file 'workfile', mode 'w' at 80a0960>

Le premier argument est une chaîne contenant le nom du fichier. Le deuxième argument est une autre chaîne contenant quelques caractères décrivant la façon dont le fichier est utilisé. `mode' peut être @code{'r'} quand le fichier n'est accédé qu'en lecture, @code{'w'} en écriture seulement (un fichier existant portant le même nom sera alors écrasé) et @code{'a'} ouvre le fichier en mode ajout (toute donnée écrite dans le fichier est automatiquement ajoutée à la fin). @code{'r+'} ouvre le fichier en mode lecture/écriture. L'argument `mode' est optionnel, sa valeur par défaut est @code{'r'}.

Normalement, les fichiers sont ouverts en `mode texte', c'est-à-dire que vous lisez et écrivez des chaînes de caractères depuis et dans ce fichier, suivant un encodage donné via `encoding'. Si `encoding' n'est pas spécifié, l'encodage par défaut dépend de la plateforme (voir @ref{505,,open()}). UTF-8 étant le standard moderne de facto, @code{encoding="utf-8"} est recommandé à moins que vous ne sachiez que vous devez utiliser un autre encodage. L’ajout d’un @code{'b'} au mode ouvre le fichier en `mode binaire'. Les données en mode binaire sont lues et écrites sous forme d’objets @ref{1bd,,bytes}. Vous ne pouvez pas spécifier `encoding' lorsque vous ouvrez un fichier en mode binaire.

En mode texte, le comportement par défaut, à la lecture, est de convertir les fin de lignes spécifiques à la plateforme (@code{\n} sur Unix, @code{\r\n} sur Windows, etc.) en simples @code{\n}. Lors de l'écriture, le comportement par défaut est d'appliquer l'opération inverse : les @code{\n} sont convertis dans leur équivalent sur la plateforme courante. Ces modifications effectuées automatiquement sont normales pour du texte mais détérioreraient des données binaires contenues dans un fichier de type @code{JPEG} ou @code{EXE}. Soyez particulièrement attentifs à ouvrir ces fichiers binaires en mode binaire.

C'est une bonne pratique d'utiliser le mot-clé @ref{5bc,,with} lorsque vous traitez des fichiers. Vous fermez ainsi toujours correctement le fichier, même si une exception est levée. Utiliser @code{with} est aussi beaucoup plus court que d'utiliser l'équivalent avec des blocs @ref{6d3,,try}…@ref{9b8,,finally} :

@example
>>> with open('workfile', encoding="utf-8") as f:
...     read_data = f.read()

>>> # We can check that the file has been automatically closed.
>>> f.closed
True
@end example

Si vous n'utilisez pas le mot clé @ref{5bc,,with}, vous devez appeler @code{f.close()} pour fermer le fichier, et ainsi immédiatement libérer les ressources qu'il utilise.

@cartouche
@quotation Avertissement 
Appeler @code{f.write()} sans utiliser le mot clé @code{with} ni appeler @code{f.close()} `pourrait' mener à une situation où les arguments de @code{f.write()} ne seraient pas complètement écrits sur le disque, même si le programme se termine avec succès.
@end quotation
@end cartouche

@c See also https://bugs.python.org/issue17852

Après la fermeture du fichier, que ce soit `via' une instruction @ref{5bc,,with} ou en appelant @code{f.close()}, toute tentative d'utilisation de l'objet fichier échoue systématiquement.

@example
>>> f.close()
>>> f.read()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: I/O operation on closed file.
@end example

@menu
* Méthodes des objets fichiers:: 
* Sauvegarde de données structurées avec le module json:: 

@end menu

@node Méthodes des objets fichiers,Sauvegarde de données structurées avec le module json,,Lecture et écriture de fichiers
@anchor{tutorial/inputoutput methods-of-file-objects}@anchor{1c0e}@anchor{tutorial/inputoutput tut-filemethods}@anchor{1c0f}
@subsubsection Méthodes des objets fichiers


Les derniers exemples de cette section supposent qu'un objet fichier appelé @code{f} a déjà été créé.

Pour lire le contenu d'un fichier, appelez @code{f.read(taille)}, cette dernière lit une certaine quantité de données et la renvoie sous forme de chaîne (en mode texte) ou d'objet `bytes' (en mode binaire). `taille' est un argument numérique facultatif. Lorsque `taille' est omis ou négatif, la totalité du contenu du fichier sera lue et renvoyée ; c'est votre problème si le fichier est deux fois plus grand que la mémoire de votre machine. Sinon, au maximum `taille' caractères (en mode texte) ou `taille' octets (en mode binaire) sont lus et renvoyés. Si la fin du fichier est atteinte, @code{f.read()} renvoie une chaîne vide (@code{'@w{'}}).

@example
>>> f.read()
'This is the entire file.\n'
>>> f.read()
'@w{'}
@end example

@code{f.readline()} lit une seule ligne du fichier ; un caractère de fin de ligne (@code{\n}) est laissé à la fin de la chaîne. Il n'est omis que sur la dernière ligne du fichier si celui-ci ne se termine pas un caractère de fin de ligne. Ceci permet de rendre la valeur de retour non ambigüe : si @code{f.readline()} renvoie une chaîne vide, c'est que la fin du fichier a été atteinte, alors qu'une ligne vide est représentée par @code{'\n'} (une chaîne de caractères ne contenant qu'une fin de ligne).

@example
>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
'@w{'}
@end example

Pour lire ligne à ligne, vous pouvez aussi boucler sur l'objet fichier. C'est plus efficace en termes de gestion mémoire, plus rapide et donne un code plus simple :

@example
>>> for line in f:
...     print(line, end='@w{'})
...
This is the first line of the file.
Second line of the file
@end example

Pour construire une liste avec toutes les lignes d'un fichier, il est aussi possible d'utiliser @code{list(f)} ou @code{f.readlines()}.

@code{f.write(chaine)} écrit le contenu de `chaine' dans le fichier et renvoie le nombre de caractères écrits.

@example
>>> f.write('This is a test\n')
15
@end example

Les autres types doivent être convertis, soit en une chaîne (en mode texte), soit en objet `bytes' (en mode binaire) avant de les écrire :

@example
>>> value = ('the answer', 42)
>>> s = str(value)  # convert the tuple to string
>>> f.write(s)
18
@end example

@code{f.tell()} renvoie un entier indiquant la position actuelle dans le fichier, mesurée en octets à partir du début du fichier lorsque le fichier est ouvert en mode binaire, ou un nombre obscur en mode texte.

Pour modifier la position dans le fichier, utilisez @code{f.seek(décalage, origine)}. La position est calculée en ajoutant `décalage' à un point de référence ; ce point de référence est déterminé par l'argument `origine' : la valeur 0 pour le début du fichier, 1 pour la position actuelle et 2 pour la fin du fichier. `origine' peut être omis et sa valeur par défaut est 0 (Python utilise le début du fichier comme point de référence).

@example
>>> f = open('workfile', 'rb+')
>>> f.write(b'0123456789abcdef')
16
>>> f.seek(5)      # Go to the 6th byte in the file
5
>>> f.read(1)
b'5'
>>> f.seek(-3, 2)  # Go to the 3rd byte before the end
13
>>> f.read(1)
b'd'
@end example

Sur un fichier en mode texte (ceux ouverts sans @code{b} dans le mode), seuls les changements de position relatifs au début du fichier sont autorisés (sauf une exception : se rendre à la fin du fichier avec @code{seek(0, 2)}) et les seules valeurs possibles pour le paramètre `décalage' sont les valeurs renvoyées par @code{f.tell()}, ou zéro. Toute autre valeur pour le paramètre `décalage' produit un comportement indéfini.

File objects have some additional methods, such as @ref{1c10,,isatty()} and
@ref{12ef,,truncate()} which are less frequently used; consult the Library
Reference for a complete guide to file objects.

@node Sauvegarde de données structurées avec le module json,,Méthodes des objets fichiers,Lecture et écriture de fichiers
@anchor{tutorial/inputoutput saving-structured-data-with-json}@anchor{1c11}@anchor{tutorial/inputoutput tut-json}@anchor{1c12}
@subsubsection Sauvegarde de données structurées avec le module @code{json}


@geindex module;json

Strings can easily be written to and read from a file.  Numbers take a bit more
effort, since the @ref{1c13,,read()} method only returns strings, which will have to
be passed to a function like @ref{254,,int()}, which takes a string like @code{'123'}
and returns its numeric value 123.  When you want to save more complex data
types like nested lists and dictionaries, parsing and serializing by hand
becomes complicated.

Plutôt que de passer son temps à écrire et déboguer du code permettant de sauvegarder des types de données compliqués, Python permet d'utiliser JSON (*JavaScript Object Notation*)@footnote{https://json.org}, un format répandu de représentation et d'échange de données. Le module standard appelé @ref{81,,json} peut transformer des données hiérarchisées Python en une représentation sous forme de chaîne de caractères. Ce processus est nommé `sérialiser'. Reconstruire les données à partir de leur représentation sous forme de chaîne est appelé `déserialiser'. Entre sa sérialisation et sa dé-sérialisation, la chaîne représentant les données peut avoir été stockée ou transmise à une autre machine.

@cartouche
@quotation Note 
Le format JSON est couramment utilisé dans les applications modernes pour échanger des données. Beaucoup de développeurs le maîtrisent, ce qui en fait un format de prédilection pour l'interopérabilité.
@end quotation
@end cartouche

Si vous avez un objet @code{x}, vous pouvez voir sa représentation JSON en tapant simplement :

@example
>>> import json
>>> x = [1, 'simple', 'list']
>>> json.dumps(x)
'[1, "simple", "list"]'
@end example

Une variante de la fonction @ref{d33,,dumps()}, nommée @ref{d32,,dump()}, sérialise simplement l'objet donné vers un @ref{1c14,,text file}. Donc si @code{f} est un @ref{1c14,,text file} ouvert en écriture, il est possible de faire :

@example
json.dump(x, f)
@end example

Pour reconstruire l'objet, si @code{f} est cette fois un @ref{1c15,,binary file} ou un @ref{1c14,,text file} ouvert en lecture :

@example
x = json.load(f)
@end example

@cartouche
@quotation Note 
Les fichiers JSON doivent être encodés en UTF-8. Utilisez @code{encoding="utf-8"} lorsque vous ouvrez un fichier JSON en tant que @ref{1c14,,fichier texte}, que ce soit en lecture ou en écriture.
@end quotation
@end cartouche

Cette méthode de sérialisation peut sérialiser des listes et des dictionnaires. Mais sérialiser d'autres types de données requiert un peu plus de travail. La documentation du module @ref{81,,json} explique comment faire.


@subsubheading Voir aussi


Le module @ref{a5,,pickle}

Au contraire de @ref{1c12,,JSON}, `pickle' est un protocole permettant la sérialisation d'objets Python arbitrairement complexes. Il est donc spécifique à Python et ne peut pas être utilisé pour communiquer avec d'autres langages. Il est aussi, par défaut, une source de vulnérabilité : dé-sérialiser des données au format `pickle' provenant d'une source malveillante et particulièrement habile peut mener à exécuter du code arbitraire.


@node Erreurs et exceptions,Classes,Les entrées/sorties,Le tutoriel Python
@anchor{tutorial/errors doc}@anchor{1c16}@anchor{tutorial/errors errors-and-exceptions}@anchor{1c17}@anchor{tutorial/errors tut-errors}@anchor{1c18}
@section Erreurs et exceptions


Jusqu'ici, les messages d'erreurs ont seulement été mentionnés. Mais si vous avez essayé les exemples vous avez certainement vu plus que cela. En fait, il y a au moins deux types d'erreurs à distinguer : les `erreurs de syntaxe' et les `exceptions'.

@menu
* Les erreurs de syntaxe:: 
* Exceptions:: 
* Gestion des exceptions:: 
* Déclencher des exceptions:: 
* Chaînage d'exceptions:: 
* Exceptions définies par l'utilisateur:: 
* Définition d'actions de nettoyage:: 
* Actions de nettoyage prédéfinies:: 
* Levée et gestion de multiples exceptions non corrélées:: 
* Enrichissement des exceptions avec des notes:: 

@end menu

@node Les erreurs de syntaxe,Exceptions,,Erreurs et exceptions
@anchor{tutorial/errors syntax-errors}@anchor{1c19}@anchor{tutorial/errors tut-syntaxerrors}@anchor{1c1a}
@subsection Les erreurs de syntaxe


Les erreurs de syntaxe, qui sont des erreurs d'analyse du code, sont peut-être celles que vous rencontrez le plus souvent lorsque vous êtes encore en phase d'apprentissage de Python :

@example
>>> while True print('Hello world')
  File "<stdin>", line 1
    while True print('Hello world')
               ^^^^^
SyntaxError: invalid syntax
@end example

The parser repeats the offending line and displays little arrows pointing
at the token in the line where the error was detected.  The error may be
caused by the absence of a token `before' the indicated token.  In the
example, the error is detected at the function @ref{f60,,print()}, since a colon
(@code{':'}) is missing before it.  File name and line number are printed so you
know where to look in case the input came from a script.

@node Exceptions,Gestion des exceptions,Les erreurs de syntaxe,Erreurs et exceptions
@anchor{tutorial/errors exceptions}@anchor{1c1b}@anchor{tutorial/errors tut-exceptions}@anchor{1c1c}
@subsection Exceptions


Même si une instruction ou une expression est syntaxiquement correcte, elle peut générer une erreur lors de son exécution. Les erreurs détectées durant l'exécution sont appelées des `exceptions' et ne sont pas toujours fatales : nous apprendrons bientôt comment les traiter dans vos programmes. La plupart des exceptions toutefois ne sont pas prises en charge par les programmes, ce qui génère des messages d'erreurs comme celui-ci :

@example
>>> 10 * (1/0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    10 * (1/0)
          ~^~
ZeroDivisionError: division by zero
>>> 4 + spam*3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    4 + spam*3
        ^^^^
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    '2' + 2
    ~~~~^~~
TypeError: can only concatenate str (not "int") to str
@end example

La dernière ligne du message d'erreur indique ce qui s'est passé. Les exceptions peuvent être de différents types et ce type est indiqué dans le message : les types indiqués dans l'exemple sont @ref{932,,ZeroDivisionError}, @ref{428,,NameError} et @ref{522,,TypeError}. Le texte affiché comme type de l'exception est le nom de l'exception native qui a été déclenchée. Ceci est vrai pour toutes les exceptions natives mais n'est pas une obligation pour les exceptions définies par l'utilisateur (même si c'est une convention bien pratique). Les noms des exceptions standards sont des identifiants natifs (pas des mots-clef réservés).

Le reste de la ligne fournit plus de détails en fonction du type de l'exception et de ce qui l'a causée.

La partie précédente du message d'erreur indique le contexte dans lequel s'est produite l'exception, sous la forme d'une trace de pile d'exécution. En général, celle-ci contient les lignes du code source ; toutefois, les lignes lues à partir de l'entrée standard ne sont pas affichées.

Vous trouvez la liste des exceptions natives et leur signification dans @ref{1811,,Exceptions natives}.

@node Gestion des exceptions,Déclencher des exceptions,Exceptions,Erreurs et exceptions
@anchor{tutorial/errors handling-exceptions}@anchor{1c1d}@anchor{tutorial/errors tut-handling}@anchor{1ba5}
@subsection Gestion des exceptions


Il est possible d'écrire des programmes qui prennent en charge certaines exceptions. Regardez l'exemple suivant, qui demande une saisie à l'utilisateur jusqu'à ce qu'un entier valide ait été entré, mais permet à l'utilisateur d'interrompre le programme (en utilisant @code{Control-C} ou un autre raccourci que le système accepte) ; notez qu'une interruption générée par l'utilisateur est signalée en levant l'exception @ref{9bf,,KeyboardInterrupt}.

@example
>>> while True:
...     try:
...         x = int(input("Please enter a number: "))
...         break
...     except ValueError:
...         print("Oops!  That was no valid number.  Try again...")
...
@end example

L'instruction @ref{6d3,,try} fonctionne comme ceci :


@itemize *

@item 
premièrement, la `clause try' (instruction(s) placée(s) entre les mots-clés @ref{6d3,,try} et @ref{189,,except}) est exécutée.

@item 
si aucune exception n'intervient, la clause @code{except} est sautée et l'exécution de l'instruction @ref{6d3,,try} est terminée.

@item 
si une exception intervient pendant l'exécution de la clause @ref{6d3,,try}, le reste de cette clause est sauté. Si le type d'exception levée correspond à un nom indiqué après le mot-clé @ref{189,,except}, la clause @code{except} correspondante est exécutée, puis l'exécution continue après le bloc @code{try}/@code{except}.

@item 
si une exception intervient et ne correspond à aucune exception mentionnée dans la clause @code{except}, elle est transmise à l'instruction @ref{6d3,,try} de niveau supérieur ; si aucun gestionnaire d'exception n'est trouvé, il s'agit d'une `exception non gérée' et l'exécution s'arrête avec un message.
@end itemize

Une instruction @ref{6d3,,try} peut comporter plusieurs clauses @code{except} pour permettre la prise en charge de différentes exceptions. Mais un seul gestionnaire, au plus, sera exécuté. Les gestionnaires ne prennent en charge que les exceptions qui interviennent dans la clause @code{try} correspondante, pas dans d'autres gestionnaires de la même instruction @code{try}. Mais une même clause @code{except} peut citer plusieurs exceptions sous la forme d'un `n'-uplet entre parenthèses, comme dans cet exemple :

@example
... except (RuntimeError, TypeError, NameError):
...     pass
@end example

Une classe dans une clause @ref{189,,except} correspond avec une exception si elle est de la même classe ou d'une de ses classes dérivées. Mais l'inverse n'est pas vrai, une clause @code{except} spécifiant une classe dérivée ne correspond pas avec une classe mère. Par exemple, le code suivant affiche B, C et D dans cet ordre :

@example
class B(Exception):
    pass

class C(B):
    pass

class D(C):
    pass

for cls in [B, C, D]:
    try:
        raise cls()
    except D:
        print("D")
    except C:
        print("C")
    except B:
        print("B")
@end example

Notez que si les clauses @code{except} avaient été inversées (avec @code{except B} en premier), il aurait affiché B, B, B — la première clause @code{except} qui correspond est déclenchée.

Quand une exception intervient, une valeur peut lui être associée, que l'on appelle `l'argument' de l'exception. La présence de cet argument et son type dépendent du type de l'exception.

La clause @code{except} peut spécifier un nom de variable après le nom de l'exception. Cette variable est liée à l'instance d'exception avec les arguments stockés dans l'attribut @code{args}. Pour plus de commodité, l'instance de l'exception définit la méthode @ref{608,,__str__()} afin que les arguments puissent être affichés directement sans avoir à référencer @code{.args}.

@example
>>> try:
...     raise Exception('spam', 'eggs')
... except Exception as inst:
...     print(type(inst))    # the exception type
...     print(inst.args)     # arguments stored in .args
...     print(inst)          # __str__ allows args to be printed directly,
...                          # but may be overridden in exception subclasses
...     x, y = inst.args     # unpack args
...     print('x =', x)
...     print('y =', y)
...
<class 'Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs
@end example

La sortie produite par @ref{608,,__str__()} de l'exception est affichée en dernière partie (« détail ») du message des exceptions qui ne sont pas gérées.

@ref{5a5,,BaseException} est la classe mère de toutes les exceptions. Une de ses sous-classes, @ref{9c7,,Exception}, est la classe mère de toutes les exceptions non fatales. Les exceptions qui ne sont pas des sous-classes de @ref{9c7,,Exception} ne sont normalement pas gérées, car elles sont utilisées pour indiquer que le programme doit se terminer. C'est le cas de @ref{d2e,,SystemExit} qui est levée par @ref{1327,,sys.exit()} et @ref{9bf,,KeyboardInterrupt} qui est levée quand l'utilisateur souhaite interrompre le programme.

@ref{9c7,,Exception} peut être utilisée pour intercepter (presque) tous les cas. Cependant, une bonne pratique consiste à être aussi précis que possible dans les types d'exception que l'on souhaite gérer et autoriser toutes les exceptions non prévues à se propager.

La manière la plus utilisée pour gérer une @ref{9c7,,Exception} consiste à afficher ou journaliser l'exception et ensuite la lever à nouveau afin de permettre à l'appelant de la gérer à son tour :

@example
import sys

try:
    f = open('myfile.txt')
    s = f.readline()
    i = int(s.strip())
except OSError as err:
    print("OS error:", err)
except ValueError:
    print("Could not convert data to an integer.")
except Exception as err:
    print(f"Unexpected @{err=@}, @{type(err)=@}")
    raise
@end example

L'instruction @ref{6d3,,try} … @ref{189,,except} accepte également une clause @code{else} optionnelle qui, lorsqu'elle est présente, doit se placer après toutes les clauses @code{except}. Elle est utile pour du code qui doit être exécuté lorsqu'aucune exception n'a été levée par la clause @code{try}. Par exemple :

@example
for arg in sys.argv[1:]:
    try:
        f = open(arg, 'r')
    except OSError:
        print('cannot open', arg)
    else:
        print(arg, 'has', len(f.readlines()), 'lines')
        f.close()
@end example

Il vaut mieux utiliser la clause @code{else} plutôt que d'ajouter du code à la clause @ref{6d3,,try} car cela évite de capturer accidentellement une exception qui n'a pas été levée par le code initialement protégé par l'instruction @code{try} … @code{except}.

Les gestionnaires d'exceptions n'interceptent pas que les exceptions qui sont levées immédiatement dans leur clause @code{try}, mais aussi celles qui sont levées au sein de fonctions appelées (parfois indirectement) dans la clause @code{try}. Par exemple :

@example
>>> def this_fails():
...     x = 1/0
...
>>> try:
...     this_fails()
... except ZeroDivisionError as err:
...     print('Handling run-time error:', err)
...
Handling run-time error: division by zero
@end example

@node Déclencher des exceptions,Chaînage d'exceptions,Gestion des exceptions,Erreurs et exceptions
@anchor{tutorial/errors raising-exceptions}@anchor{1c1e}@anchor{tutorial/errors tut-raising}@anchor{1c1f}
@subsection Déclencher des exceptions


L'instruction @ref{5d7,,raise} permet au programmeur de déclencher une exception spécifique. Par exemple :

@example
>>> raise NameError('HiThere')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise NameError('HiThere')
NameError: HiThere
@end example

Le seul argument à @ref{5d7,,raise} indique l'exception à déclencher. Cela peut être soit une instance d'exception, soit une classe d'exception (une classe dérivée de @ref{5a5,,BaseException}, telle que @ref{9c7,,Exception} ou une de ses sous-classes). Si une classe est donnée, elle est implicitement instanciée `via' l'appel de son constructeur, sans argument :

@example
raise ValueError  # shorthand for 'raise ValueError()'
@end example

Si vous avez besoin de savoir si une exception a été levée mais que vous n'avez pas intention de la gérer, une forme plus simple de l'instruction @ref{5d7,,raise} permet de propager l'exception :

@example
>>> try:
...     raise NameError('HiThere')
... except NameError:
...     print('An exception flew by!')
...     raise
...
An exception flew by!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    raise NameError('HiThere')
NameError: HiThere
@end example

@node Chaînage d'exceptions,Exceptions définies par l'utilisateur,Déclencher des exceptions,Erreurs et exceptions
@anchor{tutorial/errors exception-chaining}@anchor{1c20}@anchor{tutorial/errors tut-exception-chaining}@anchor{1c21}
@subsection Chaînage d'exceptions


Si une exception non gérée se produit à l'intérieur d'une section @ref{189,,except}, l'exception en cours de traitement est jointe à l'exception non gérée et incluse dans le message d'erreur :

@example
>>> try:
...     open("database.sqlite")
... except OSError:
...     raise RuntimeError("unable to handle error")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    open("database.sqlite")
    ~~~~^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: 'database.sqlite'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("unable to handle error")
RuntimeError: unable to handle error
@end example

Pour indiquer qu'une exception est la conséquence directe d'une autre, l'instruction @ref{5d7,,raise} autorise une clause facultative @ref{5d7,,from} :

@example
# exc must be exception instance or None.
raise RuntimeError from exc
@end example

Cela peut être utile lorsque vous transformez des exceptions. Par exemple :

@example
>>> def func():
...     raise ConnectionError
...
>>> try:
...     func()
... except ConnectionError as exc:
...     raise RuntimeError('Failed to open database') from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    func()
    ~~~~^^
  File "<stdin>", line 2, in func
ConnectionError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError('Failed to open database') from exc
RuntimeError: Failed to open database
@end example

Cela permet également de désactiver le chaînage automatique des exceptions à l'aide de l'idiome @code{from None} :

@example
>>> try:
...     open('database.sqlite')
... except OSError:
...     raise RuntimeError from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError from None
RuntimeError
@end example

Pour plus d'informations sur les mécanismes de chaînage, voir @ref{1811,,Exceptions natives}.

@node Exceptions définies par l'utilisateur,Définition d'actions de nettoyage,Chaînage d'exceptions,Erreurs et exceptions
@anchor{tutorial/errors tut-userexceptions}@anchor{1c22}@anchor{tutorial/errors user-defined-exceptions}@anchor{1c23}
@subsection Exceptions définies par l'utilisateur


Les programmes peuvent nommer leurs propres exceptions en créant une nouvelle classe d'exception (voir @ref{1bad,,Classes} pour en savoir plus sur les classes de Python). Les exceptions sont typiquement dérivées de la classe @ref{9c7,,Exception}, directement ou non.

Les classes d'exceptions sont des classes comme les autres, et peuvent donc utiliser toutes les fonctionnalités des classes. Néanmoins, en général, elles demeurent assez simples, et se contentent d'offrir des attributs qui permettent aux gestionnaires de ces exceptions d'extraire les informations relatives à l'erreur qui s'est produite.

La plupart des exceptions sont définies avec des noms qui se terminent par "Error", comme les exceptions standards.

Beaucoup de modules standards définissent leurs propres exceptions pour signaler les erreurs possibles dans les fonctions qu'ils définissent.

@node Définition d'actions de nettoyage,Actions de nettoyage prédéfinies,Exceptions définies par l'utilisateur,Erreurs et exceptions
@anchor{tutorial/errors defining-clean-up-actions}@anchor{1c24}@anchor{tutorial/errors tut-cleanup}@anchor{1c25}
@subsection Définition d'actions de nettoyage


L'instruction @ref{6d3,,try} a une autre clause optionnelle qui est destinée à définir des actions de nettoyage devant être exécutées dans certaines circonstances. Par exemple :

@example
>>> try:
...     raise KeyboardInterrupt
... finally:
...     print('Goodbye, world!')
...
Goodbye, world!
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    raise KeyboardInterrupt
KeyboardInterrupt
@end example

Si la clause @ref{9b8,,finally} est présente, la clause @code{finally} est la dernière tâche exécutée avant la fin du bloc @ref{6d3,,try}. La clause @code{finally} se lance que le bloc @code{try} produise une exception ou non. Les prochains points parlent de cas plus complexes lorsqu'une exception apparait :


@itemize *

@item 
Si une exception se produit durant l'exécution de la clause @code{try}, elle peut être récupérée par une clause @ref{189,,except}. Si l'exception n'est pas récupérée par une clause @code{except}, l'exception est levée à nouveau après que la clause @code{finally} a été exécutée.

@item 
Une exception peut se produire durant l'exécution d'une clause @code{except} ou @code{else}. Encore une fois, l'exception est reprise après que la clause @code{finally} a été exécutée.

@item 
Si dans l'exécution d'un bloc @code{finally}, on atteint une instruction @ref{a97,,break}, @ref{9b7,,continue} ou @ref{9bc,,return}, alors les exceptions ne sont pas reprises.

@item 
Si dans l'exécution d'un bloc @code{try}, on atteint une instruction @ref{a97,,break}, @ref{9b7,,continue} ou @ref{9bc,,return}, alors la clause @code{finally} s'exécute juste avant l'exécution de @code{break}, @code{continue} ou @code{return}.

@item 
Si la clause @code{finally} contient une instruction @code{return}, la valeur retournée sera celle du @code{return} de la clause @code{finally}, et non la valeur du @code{return} de la clause @code{try}.
@end itemize

Par exemple :

@example
>>> def bool_return():
...     try:
...         return True
...     finally:
...         return False
...
>>> bool_return()
False
@end example

Un exemple plus compliqué :

@example
>>> def divide(x, y):
...     try:
...         result = x / y
...     except ZeroDivisionError:
...         print("division by zero!")
...     else:
...         print("result is", result)
...     finally:
...         print("executing finally clause")
...
>>> divide(2, 1)
result is 2.0
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    divide("2", "1")
    ~~~~~~^^^^^^^^^^
  File "<stdin>", line 3, in divide
    result = x / y
             ~~^~~
TypeError: unsupported operand type(s) for /: 'str' and 'str'
@end example

Comme vous pouvez le voir, la clause @ref{9b8,,finally} est exécutée dans tous les cas. L'exception de type @ref{522,,TypeError}, déclenchée en divisant deux chaînes de caractères, n'est pas prise en charge par la clause @ref{189,,except} et est donc propagée après que la clause @code{finally} a été exécutée.

Dans les vraies applications, la clause @ref{9b8,,finally} est notamment utile pour libérer des ressources externes (telles que des fichiers ou des connexions réseau), quelle qu'ait été l'utilisation de ces ressources.

@node Actions de nettoyage prédéfinies,Levée et gestion de multiples exceptions non corrélées,Définition d'actions de nettoyage,Erreurs et exceptions
@anchor{tutorial/errors predefined-clean-up-actions}@anchor{1c26}@anchor{tutorial/errors tut-cleanup-with}@anchor{1c27}
@subsection Actions de nettoyage prédéfinies


Certains objets définissent des actions de nettoyage standards qui doivent être exécutées lorsque l'objet n'est plus nécessaire, indépendamment du fait que l'opération ayant utilisé l'objet ait réussi ou non. Regardez l'exemple suivant, qui tente d'ouvrir un fichier et d'afficher son contenu à l'écran

@example
for line in open("myfile.txt"):
    print(line, end="")
@end example

Le problème avec ce code est qu'il laisse le fichier ouvert pendant une durée indéterminée après que le code a fini de s'exécuter. Ce n'est pas un problème avec des scripts simples, mais peut l'être au sein d'applications plus conséquentes. L'instruction @ref{5bc,,with} permet d'utiliser certains objets comme des fichiers d'une façon qui assure qu'ils seront toujours nettoyés rapidement et correctement.

@example
with open("myfile.txt") as f:
    for line in f:
        print(line, end="")
@end example

Après l'exécution du bloc, le fichier `f' est toujours fermé, même si un problème est survenu pendant l'exécution de ces lignes. D'autres objets qui, comme pour les fichiers, fournissent des actions de nettoyage prédéfinies l'indiquent dans leur documentation.

@node Levée et gestion de multiples exceptions non corrélées,Enrichissement des exceptions avec des notes,Actions de nettoyage prédéfinies,Erreurs et exceptions
@anchor{tutorial/errors raising-and-handling-multiple-unrelated-exceptions}@anchor{1c28}@anchor{tutorial/errors tut-exception-groups}@anchor{1c29}
@subsection Levée et gestion de multiples exceptions non corrélées


Il existe des situations où il est nécessaire de signaler plusieurs exceptions qui se sont produites. C'est souvent le cas dans les programmes à multiples fils, lorsque plusieurs tâches échouent en parallèle. Mais il existe également d'autres cas où il est souhaitable de poursuivre l'exécution, de collecter plusieurs erreurs plutôt que de lever la première exception rencontrée.

L'idiome natif @ref{1b4,,ExceptionGroup} englobe une liste d'instances d'exceptions afin de pouvoir les lever en même temps. C'est une exception, et peut donc être interceptée comme toute autre exception.

@example
>>> def f():
...     excs = [OSError('error 1'), SystemError('error 2')]
...     raise ExceptionGroup('there were problems', excs)
...
>>> f()
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 1, in <module>
  |     f()
  |     ~^^
  |   File "<stdin>", line 3, in f
  |     raise ExceptionGroup('there were problems', excs)
  | ExceptionGroup: there were problems (2 sub-exceptions)
  +-+---------------- 1 ----------------
    | OSError: error 1
    +---------------- 2 ----------------
    | SystemError: error 2
    +------------------------------------
>>> try:
...     f()
... except Exception as e:
...     print(f'caught @{type(e)@}: e')
...
caught <class 'ExceptionGroup'>: e
>>>
@end example

En utilisant @code{except*} au lieu de @code{except}, vous pouvez choisir de ne gérer que les exceptions du groupe qui correspondent à un certain type. Dans l'exemple qui suit, dans lequel se trouve imbriqué un groupe d'exceptions, chaque clause @code{except*} extrait du groupe des exceptions d'un certain type tout en laissant toutes les autres exceptions se propager vers d'autres clauses et éventuellement être réactivées.

@example
>>> def f():
...     raise ExceptionGroup(
...         "group1",
...         [
...             OSError(1),
...             SystemError(2),
...             ExceptionGroup(
...                 "group2",
...                 [
...                     OSError(3),
...                     RecursionError(4)
...                 ]
...             )
...         ]
...     )
...
>>> try:
...     f()
... except* OSError as e:
...     print("There were OSErrors")
... except* SystemError as e:
...     print("There were SystemErrors")
...
There were OSErrors
There were SystemErrors
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 2, in <module>
  |     f()
  |     ~^^
  |   File "<stdin>", line 2, in f
  |     raise ExceptionGroup(
  |     ...<12 lines>...
  |     )
  | ExceptionGroup: group1 (1 sub-exception)
  +-+---------------- 1 ----------------
    | ExceptionGroup: group2 (1 sub-exception)
    +-+---------------- 1 ----------------
      | RecursionError: 4
      +------------------------------------
>>>
@end example

Notez que les exceptions imbriquées dans un groupe d'exceptions doivent être des instances, pas des types. En effet, dans la pratique, les exceptions sont normalement celles qui ont déjà été déclenchées et interceptées par le programme, en utilisant le modèle suivant :

@example
>>> excs = []
... for test in tests:
...     try:
...         test.run()
...     except Exception as e:
...         excs.append(e)
...
>>> if excs:
...    raise ExceptionGroup("Test Failures", excs)
...
@end example

@node Enrichissement des exceptions avec des notes,,Levée et gestion de multiples exceptions non corrélées,Erreurs et exceptions
@anchor{tutorial/errors enriching-exceptions-with-notes}@anchor{1c2a}@anchor{tutorial/errors tut-exception-notes}@anchor{1c2b}
@subsection Enrichissement des exceptions avec des notes


Quand une exception est créée pour être levée, elle est généralement initialisée avec des informations décrivant l'erreur qui s'est produite. Il existe des cas où il est utile d'ajouter des informations après que l'exception a été interceptée. Dans ce but, les exceptions ont une méthode @code{add_note(note)} qui reçoit une chaîne et l'ajoute à la liste des notes de l'exception. L'affichage de la pile de trace standard inclut toutes les notes, dans l'ordre dans lequel elles ont été ajoutées, après l'exception.

@example
>>> try:
...     raise TypeError('bad type')
... except Exception as e:
...     e.add_note('Add some information')
...     e.add_note('Add some more information')
...     raise
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    raise TypeError('bad type')
TypeError: bad type
Add some information
Add some more information
>>>
@end example

Par exemple, lors de la collecte d'exceptions dans un groupe d'exceptions, il est probable que vous souhaitiez ajouter des informations de contexte aux erreurs individuelles. Dans ce qui suit, chaque exception du groupe est accompagnée d'une note indiquant quand cette erreur s'est produite.

@example
>>> def f():
...     raise OSError('operation failed')
...
>>> excs = []
>>> for i in range(3):
...     try:
...         f()
...     except Exception as e:
...         e.add_note(f'Happened in Iteration @{i+1@}')
...         excs.append(e)
...
>>> raise ExceptionGroup('We have some problems', excs)
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 1, in <module>
  |     raise ExceptionGroup('We have some problems', excs)
  | ExceptionGroup: We have some problems (3 sub-exceptions)
  +-+---------------- 1 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |     f()
    |     ~^^
    |   File "<stdin>", line 2, in f
    |     raise OSError('operation failed')
    | OSError: operation failed
    | Happened in Iteration 1
    +---------------- 2 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |     f()
    |     ~^^
    |   File "<stdin>", line 2, in f
    |     raise OSError('operation failed')
    | OSError: operation failed
    | Happened in Iteration 2
    +---------------- 3 ----------------
    | Traceback (most recent call last):
    |   File "<stdin>", line 3, in <module>
    |     f()
    |     ~^^
    |   File "<stdin>", line 2, in f
    |     raise OSError('operation failed')
    | OSError: operation failed
    | Happened in Iteration 3
    +------------------------------------
>>>
@end example

@node Classes,Survol de la bibliothèque standard,Erreurs et exceptions,Le tutoriel Python
@anchor{tutorial/classes doc}@anchor{1c2c}@anchor{tutorial/classes classes}@anchor{1c2d}@anchor{tutorial/classes tut-classes}@anchor{1bad}
@section Classes


Les classes sont un moyen de réunir des données et des fonctionnalités. Créer une nouvelle classe crée un nouveau `type' d'objet et ainsi de nouvelles `instances' de ce type peuvent être construites. Chaque instance peut avoir ses propres attributs, ce qui définit son état. Une instance peut aussi avoir des méthodes (définies par la classe de l'instance) pour modifier son état.

La notion de classes en Python s'inscrit dans le langage avec un minimum de syntaxe et de sémantique nouvelles. C'est un mélange des mécanismes rencontrés dans C++ et Modula-3. Les classes fournissent toutes les fonctionnalités standards de la programmation orientée objet : l'héritage de classes autorise les héritages multiples, une classe dérivée peut surcharger les méthodes de sa ou ses classes mères et une méthode peut appeler la méthode d'une classe mère qui possède le même nom. Les objets peuvent contenir n'importe quel nombre ou type de données. De la même manière que les modules, les classes participent à la nature dynamique de Python : elles sont créées pendant l'exécution et peuvent être modifiées après leur création.

Dans la terminologie C++, les membres des classes (y compris les données) sont `publics' (sauf exception, voir @ref{1c2e,,Variables privées}) et toutes les fonctions membres sont `virtuelles'. Comme avec Modula-3, il n'y a aucune façon d'accéder aux membres d'un objet à partir de ses méthodes : une méthode est déclarée avec un premier argument explicite représentant l'objet et cet argument est transmis de manière implicite lors de l'appel. Comme avec Smalltalk, les classes elles-mêmes sont des objets. Il existe ainsi une sémantique pour les importer et les renommer. Au contraire de C++ et Modula-3, les types natifs peuvent être utilisés comme classes mères pour être étendus par l'utilisateur. Enfin, comme en C++, la plupart des opérateurs natifs avec une syntaxe spéciale (opérateurs arithmétiques, indiçage, etc.) peuvent être redéfinis pour les instances de classes.

En l'absence d'une terminologie communément admise pour parler des classes, nous utilisons parfois des termes de Smalltalk et C++. Nous voulions utiliser les termes de Modula-3 puisque sa sémantique orientée objet est plus proche de celle de Python que C++, mais il est probable que seul un petit nombre de lecteurs les connaissent.

@menu
* Objets et noms ; préambule: Objets et noms préambule. 
* Portées et espaces de nommage en Python:: 
* Une première approche des classes:: 
* Remarques diverses:: 
* Héritage:: 
* Variables privées:: 
* Trucs et astuces:: 
* Itérateurs:: 
* Générateurs:: 
* Expressions et générateurs:: 

@end menu

@node Objets et noms préambule,Portées et espaces de nommage en Python,,Classes
@anchor{tutorial/classes a-word-about-names-and-objects}@anchor{1c2f}@anchor{tutorial/classes tut-object}@anchor{1c30}
@subsection Objets et noms : préambule


Les objets possèdent une existence propre et plusieurs noms peuvent être utilisés (dans divers contextes) pour faire référence à un même objet. Ce concept est connu sous le nom d'alias dans d'autres langages. Il n'apparaît pas au premier coup d'œil en Python et il peut être ignoré tant qu'on travaille avec des types de base immuables (nombres, chaînes, `n'-uplets). Cependant, les alias peuvent produire des effets surprenants sur la sémantique d'un code Python mettant en jeu des objets mutables comme les listes, les dictionnaires et la plupart des autres types. En général, leur utilisation est bénéfique au programme car les alias se comportent, d'un certain point de vue, comme des pointeurs. Par exemple, transmettre un objet n'a aucun coût car c'est simplement un pointeur qui est transmis par l'implémentation ; et si une fonction modifie un objet passé en argument, le code à l'origine de l'appel voit le changement. Ceci élimine le besoin d'avoir deux mécanismes de transmission d'arguments comme en Pascal.

@node Portées et espaces de nommage en Python,Une première approche des classes,Objets et noms préambule,Classes
@anchor{tutorial/classes python-scopes-and-namespaces}@anchor{1c31}@anchor{tutorial/classes tut-scopes}@anchor{1be6}
@subsection Portées et espaces de nommage en Python


Avant de présenter les classes, nous devons aborder la notion de portée en Python. Les définitions de classes font d'habiles manipulations avec les espaces de nommage, vous devez donc savoir comment les portées et les espaces de nommage fonctionnent. Soit dit en passant, la connaissance de ce sujet est aussi utile aux développeurs Python expérimentés.

Commençons par quelques définitions.

Un `espace de nommage' est une table de correspondance entre des noms et des objets. La plupart des espaces de nommage sont actuellement implémentés sous forme de dictionnaires Python, mais ceci n'est normalement pas visible (sauf pour les performances) et peut changer dans le futur. Comme exemples d'espaces de nommage, nous pouvons citer les primitives (fonctions comme @ref{1c32,,abs()} et les noms des exceptions de base) ; les noms globaux dans un module ; et les noms locaux lors d'un appel de fonction. D'une certaine manière, l'ensemble des attributs d'un objet forme lui-même un espace de nommage. L'important à retenir concernant les espaces de nommage est qu'il n'y a absolument aucun lien entre les noms de différents espaces de nommage ; par exemple, deux modules différents peuvent définir une fonction @code{maximize} sans qu'il n'y ait de confusion. Les utilisateurs des modules doivent préfixer le nom de la fonction avec celui du module.

À ce propos, nous utilisons le mot `attribut' pour tout nom suivant un point. Par exemple, dans l'expression @code{z.real}, @code{real} est un attribut de l'objet @code{z}. Rigoureusement parlant, les références à des noms dans des modules sont des références d'attributs : dans l'expression @code{nommodule.nomfonction}, @code{nommodule} est un objet module et @code{nomfonction} est un attribut de cet objet. Dans ces conditions, il existe une correspondance directe entre les attributs du module et les noms globaux définis dans le module : ils partagent le même espace de nommage @footnote{
Il existe une exception : les modules disposent d'un attribut secret en lecture seule appelé @ref{546,,__dict__} qui renvoie le dictionnaire utilisé pour implémenter l'espace de nommage du module ; le nom @code{__dict__} est un attribut mais pas un nom global. Évidemment, si vous l'utilisez, vous brisez l'abstraction de l'implémentation des espaces de nommage. Il est donc réservé à des choses comme les débogueurs post-mortem.
} !

Les attributs peuvent être en lecture seule ou modifiables. S'ils sont modifiables, l'affectation à un attribut est possible. Les attributs de modules sont modifiables : vous pouvez écrire @code{nommodule.la_reponse = 42}. Les attributs modifiables peuvent aussi être effacés avec l'instruction @ref{1734,,del}. Par exemple, @code{del nommodule.la_reponse} supprime l'attribut @code{la_reponse} de l'objet nommé @code{nommodule}.

Les espaces de nommage sont créés à différents moments et ont différentes durées de vie. L'espace de nommage contenant les primitives est créé au démarrage de l'interpréteur Python et n'est jamais effacé. L'espace de nommage globaux pour un module est créé lorsque la définition du module est lue. Habituellement, les espaces de nommage des modules durent aussi jusqu'à l'arrêt de l'interpréteur. Les instructions exécutées par la première invocation de l'interpréteur, qu'elles soient lues depuis un fichier de script ou de manière interactive, sont considérées comme faisant partie d'un module appelé @ref{1,,__main__}, de façon qu'elles possèdent leur propre espace de nommage (les primitives vivent elles-mêmes dans un module, appelé @ref{12,,builtins}).

L'espace des noms locaux d'une fonction est créé lors de son appel, puis effacé lorsqu'elle renvoie un résultat ou lève une exception non prise en charge (en fait, « oublié » serait une meilleure façon de décrire ce qui se passe réellement). Bien sûr, des invocations récursives ont chacune leur propre espace de nommage.

La `portée' est la zone textuelle d'un programme Python où un espace de nommage est directement accessible. « Directement accessible » signifie ici qu'une référence non qualifiée à un nom est cherchée dans l'espace de nommage.

Bien que les portées soient déterminées de manière statique, elles sont utilisées de manière dynamique. À n'importe quel moment de l'exécution, il y a au minimum trois ou quatre portées imbriquées dont les espaces de nommage sont directement accessibles :


@itemize *

@item 
la portée la plus au centre, celle qui est consultée en premier, contient les noms locaux ;

@item 
les portées des fonctions englobantes, qui sont consultées en commençant avec la portée englobante la plus proche, contiennent des noms non-locaux mais aussi non-globaux ;

@item 
l'avant-dernière portée contient les noms globaux du module courant ;

@item 
la portée englobante, consultée en dernier, est l'espace de nommage contenant les primitives.
@end itemize

Si un nom est déclaré comme global, alors toutes les références et affectations vont directement dans l'avant-dernière portée contenant les noms globaux du module. Pour pointer une variable qui se trouve en dehors de la portée la plus locale, vous pouvez utiliser l'instruction @ref{1285,,nonlocal}. Si une telle variable n'est pas déclarée `nonlocal', elle est en lecture seule (toute tentative de la modifier crée simplement une `nouvelle' variable dans la portée la plus locale, en laissant inchangée la variable du même nom dans sa portée d'origine).

Habituellement, la portée locale référence les noms locaux de la fonction courante. En dehors des fonctions, la portée locale référence le même espace de nommage que la portée globale : l'espace de nommage du module. Les définitions de classes créent un nouvel espace de nommage dans la portée locale.

Il est important de réaliser que les portées sont déterminées de manière textuelle : la portée globale d'une fonction définie dans un module est l'espace de nommage de ce module, quelle que soit la provenance de l'appel à la fonction. En revanche, la recherche réelle des noms est faite dynamiquement au moment de l'exécution. Cependant la définition du langage est en train d'évoluer vers une résolution statique des noms au moment de la « compilation », donc ne vous basez pas sur une résolution dynamique (en réalité, les variables locales sont déjà déterminées de manière statique) !

Une particularité de Python est que, si aucune instruction @ref{188,,global} ou @ref{1285,,nonlocal} n'est active, les affectations de noms vont toujours dans la portée la plus proche. Les affectations ne copient aucune donnée : elles se contentent de lier des noms à des objets. Ceci est également vrai pour l'effacement : l'instruction @code{del x} supprime la liaison de @code{x} dans l'espace de nommage référencé par la portée locale. En réalité, toutes les opérations qui impliquent des nouveaux noms utilisent la portée locale : en particulier, les instructions @ref{5cc,,import} et les définitions de fonctions effectuent une liaison du module ou du nom de fonction dans la portée locale.

L'instruction @ref{188,,global} peut être utilisée pour indiquer que certaines variables existent dans la portée globale et doivent être reliées en local ; l'instruction @ref{1285,,nonlocal} indique que certaines variables existent dans une portée supérieure et doivent être reliées en local.

@menu
* Exemple de portées et d'espaces de nommage:: 

@end menu

@node Exemple de portées et d'espaces de nommage,,,Portées et espaces de nommage en Python
@anchor{tutorial/classes scopes-and-namespaces-example}@anchor{1c33}@anchor{tutorial/classes tut-scopeexample}@anchor{1c34}
@subsubsection Exemple de portées et d'espaces de nommage


Ceci est un exemple montrant comment utiliser les différentes portées et espaces de nommage, et comment @ref{188,,global} et @ref{1285,,nonlocal} modifient l'affectation de variable :

@example
def scope_test():
    def do_local():
        spam = "local spam"

    def do_nonlocal():
        nonlocal spam
        spam = "nonlocal spam"

    def do_global():
        global spam
        spam = "global spam"

    spam = "test spam"
    do_local()
    print("After local assignment:", spam)
    do_nonlocal()
    print("After nonlocal assignment:", spam)
    do_global()
    print("After global assignment:", spam)

scope_test()
print("In global scope:", spam)
@end example

Ce code donne le résultat suivant :

@example
After local assignment: test spam
After nonlocal assignment: nonlocal spam
After global assignment: nonlocal spam
In global scope: global spam
@end example

Vous pouvez constater que l'affectation `locale' (qui est effectuée par défaut) n'a pas modifié la liaison de `spam' dans `scope_test'. L'affectation @ref{1285,,nonlocal} a changé la liaison de `spam' dans `scope_test' et l'affectation @ref{188,,global} a changé la liaison au niveau du module.

Vous pouvez également voir qu'aucune liaison pour `spam' n'a été faite avant l'affectation @ref{188,,global}.

@node Une première approche des classes,Remarques diverses,Portées et espaces de nommage en Python,Classes
@anchor{tutorial/classes a-first-look-at-classes}@anchor{1c35}@anchor{tutorial/classes tut-firstclasses}@anchor{1bc8}
@subsection Une première approche des classes


Le concept de classe introduit un peu de syntaxe nouvelle, trois nouveaux types d'objets ainsi que quelques nouveaux éléments de sémantique.

@menu
* Syntaxe de définition des classes:: 
* Objets classes:: 
* Objets instances:: 
* Objets méthode:: 
* Variables de classe et d’instance:: 

@end menu

@node Syntaxe de définition des classes,Objets classes,,Une première approche des classes
@anchor{tutorial/classes class-definition-syntax}@anchor{1c36}@anchor{tutorial/classes tut-classdefinition}@anchor{1c37}
@subsubsection Syntaxe de définition des classes


La forme la plus simple de définition d'une classe est la suivante :

@example
class ClassName:
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Les définitions de classes, comme les définitions de fonctions (définitions @ref{140e,,def}), doivent être exécutées avant d'avoir un effet. Vous pouvez tout à fait placer une définition de classe dans une branche d'une instruction conditionnelle @ref{2e7,,if} ou encore à l'intérieur d'une fonction.

Dans la pratique, les déclarations dans une définition de classe sont généralement des définitions de fonctions mais d'autres déclarations sont permises et parfois utiles (nous revenons sur ce point plus tard). Les définitions de fonction à l'intérieur d'une classe ont normalement une forme particulière de liste d'arguments, dictée par les conventions d'appel aux méthodes (à nouveau, tout ceci est expliqué plus loin).

Quand une classe est définie, un nouvel espace de nommage est créé et utilisé comme portée locale --- Ainsi, toutes les affectations de variables locales entrent dans ce nouvel espace de nommage. En particulier, les définitions de fonctions y lient le nom de la nouvelle fonction.

À la fin de la définition d'une classe, un `objet classe' est créé. C'est, pour simplifier, une encapsulation du contenu de l'espace de nommage créé par la définition de classe. Nous en apprendrons plus sur les objets classes dans la prochaine section. La portée locale initiale (celle qui prévaut avant le début de la définition de la classe) est ré-instanciée et l'objet de classe est lié ici au nom de classe donné dans l'en-tête de définition de classe (@code{ClassName} dans l'exemple).

@node Objets classes,Objets instances,Syntaxe de définition des classes,Une première approche des classes
@anchor{tutorial/classes class-objects}@anchor{1c38}@anchor{tutorial/classes tut-classobjects}@anchor{1c39}
@subsubsection Objets classes


Les objets classes prennent en charge deux types d'opérations : des références à des attributs et l'instanciation.

Les `références d'attributs' utilisent la syntaxe standard utilisée pour toutes les références d'attributs en Python : @code{obj.nom}. Les noms d'attribut valides sont tous les noms qui se trouvaient dans l'espace de nommage de la classe quand l'objet classe a été créé. Donc, si la définition de classe est de cette forme :

@example
class MyClass:
    """A simple example class"""
    i = 12345

    def f(self):
        return 'hello world'
@end example

alors @code{MyClass.i} et @code{MyClass.f} sont des références valides à des attributs, renvoyant respectivement un entier et un objet fonction. Les attributs de classes peuvent également être affectés, de sorte que vous pouvez modifier la valeur de @code{MyClass.i} par affectation. @ref{1c3a,,__doc__} est aussi un attribut valide, renvoyant la `docstring' appartenant à la classe : @code{"A simple example class"}.

L'`instanciation' de classes utilise la notation des fonctions. Considérez simplement que l'objet classe est une fonction sans paramètre qui renvoie une nouvelle instance de la classe. Par exemple (en considérant la classe définie ci-dessus) :

@example
x = MyClass()
@end example

crée une nouvelle `instance' de la classe et affecte cet objet à la variable locale @code{x}.

L'opération d'instanciation (en "appelant" un objet classe) crée un objet vide. De nombreuses classes aiment créer des instances personnalisées correspondant à un état initial spécifique. À cet effet, une classe peut définir une méthode spéciale nommée @ref{69b,,__init__()}, comme ceci :

@example
def __init__(self):
    self.data = []
@end example

Quand une classe définit une méthode @ref{69b,,__init__()}, l'instanciation de la classe appelle automatiquement @code{__init__()} pour la nouvelle instance de la classe. Donc, dans cet exemple, l'initialisation d'une nouvelle instance peut être obtenue par :

@example
x = MyClass()
@end example

Bien sûr, la méthode @ref{69b,,__init__()} peut avoir des arguments pour une plus grande flexibilité. Dans ce cas, les arguments donnés à l'opérateur d'instanciation de classe sont transmis à @code{__init__()}. Par exemple

@example
>>> class Complex:
...     def __init__(self, realpart, imagpart):
...         self.r = realpart
...         self.i = imagpart
...
>>> x = Complex(3.0, -4.5)
>>> x.r, x.i
(3.0, -4.5)
@end example

@node Objets instances,Objets méthode,Objets classes,Une première approche des classes
@anchor{tutorial/classes instance-objects}@anchor{1c3b}@anchor{tutorial/classes tut-instanceobjects}@anchor{1c3c}
@subsubsection Objets instances


Maintenant, que pouvons-nous faire avec des objets instances ? Les seules opérations comprises par les objets instances sont des références d'attributs. Il y a deux sortes de noms d'attributs valides, les attributs 'données' et les méthodes.

Les `attributs 'données'' correspondent à des "variables d'instance" en Smalltalk et aux "membres de données" en C++. Les attributs 'données' n'ont pas à être déclarés. Comme les variables locales, ils existent dès lors qu'ils sont assignés une première fois. Par exemple, si @code{x} est l'instance de @code{MyClass} créée ci-dessus, le code suivant affiche la valeur @code{16}, sans laisser de trace :

@example
x.counter = 1
while x.counter < 10:
    x.counter = x.counter * 2
print(x.counter)
del x.counter
@end example

La deuxième sorte d'attribut d'instance est une `méthode'. Une méthode est une fonction qui « appartient à » un objet.

@geindex objets;method

Les noms de méthodes valides d'un objet instance dépendent de sa classe. Par définition, tous les attributs d'une classe qui sont des objets fonctions définissent les méthodes correspondantes de ses instances. Donc, dans notre exemple, @code{x.f} est une référence valide à une méthode car @code{MyClass.f} est une fonction, mais pas @code{x.i} car @code{MyClass.i} n'en est pas une. Attention cependant, @code{x.f} n'est pas la même chose que @code{MyClass.f} --- Il s'agit d'un `objet méthode', pas d'un objet fonction.

@node Objets méthode,Variables de classe et d’instance,Objets instances,Une première approche des classes
@anchor{tutorial/classes method-objects}@anchor{1c3d}@anchor{tutorial/classes tut-methodobjects}@anchor{1c3e}
@subsubsection Objets méthode


Le plus souvent, une méthode est appelée juste après avoir été liée :

@example
x.f()
@end example

Dans l'exemple de la classe @code{MyClass}, cela renvoie la chaîne de caractères @code{hello world}. Toutefois, il n'est pas nécessaire d'appeler la méthode directement : @code{x.f} est un objet méthode, il peut être gardé de côté et être appelé plus tard. Par exemple :

@example
xf = x.f
while True:
    print(xf())
@end example

affiche @code{hello world} jusqu'à la fin des temps.

Que se passe-t-il exactement quand une méthode est appelée ? Vous avez dû remarquer que @code{x.f()} a été appelée dans le code ci-dessus sans argument, alors que la définition de la méthode @code{f()} spécifie bien qu'elle prend un argument. Qu'est-il arrivé à l'argument ? Python doit sûrement lever une exception lorsqu'une fonction qui requiert un argument est appelée sans -- même si l'argument n'est pas utilisé…

En fait, vous avez peut-être deviné la réponse : la particularité des méthodes est que l'objet est passé comme premier argument de la fonction. Dans notre exemple, l'appel @code{x.f()} est exactement équivalent à @code{MyClass.f(x)}. En général, appeler une méthode avec une liste de `n' arguments est équivalent à appeler la fonction correspondante avec une liste d'arguments créée en ajoutant l'instance de l'objet de la méthode avant le premier argument.

En général, les méthodes marchent de la manière suivante. Lorsque un attribut d'une instance est référencé et que ce n'est pas un attribut 'données', sa classe est recherchée. Si le nom correspond à un attribut valide et que c'est un objet fonction, des références à l'objet instance et l'objet fonction sont empaquetées dans un objet méthode. Quand l'objet méthode est appelé avec une liste d'arguments, une nouvelle liste d'arguments est construite à partir de l'objet instance et de la liste des arguments. L'objet fonction est alors appelé avec cette nouvelle liste d'arguments.

@node Variables de classe et d’instance,,Objets méthode,Une première approche des classes
@anchor{tutorial/classes class-and-instance-variables}@anchor{1c3f}@anchor{tutorial/classes tut-class-and-instance-variables}@anchor{1c40}
@subsubsection Variables de classe et d’instance


En général, les variables d'instance stockent des informations relatives à chaque instance alors que les variables de classe servent à stocker les attributs et méthodes communes à toutes les instances de la classe :

@example
class Dog:

    kind = 'canine'         # class variable shared by all instances

    def __init__(self, name):
        self.name = name    # instance variable unique to each instance

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind                  # shared by all dogs
'canine'
>>> e.kind                  # shared by all dogs
'canine'
>>> d.name                  # unique to d
'Fido'
>>> e.name                  # unique to e
'Buddy'
@end example

Comme nous l'avons vu dans @ref{1c30,,Objets et noms ; préambule}, les données partagées @ref{1b8e,,mutable} (telles que les listes, dictionnaires, etc.) peuvent avoir des effets surprenants. Par exemple, la liste `tricks' dans le code suivant ne devrait pas être utilisée en tant que variable de classe car, dans ce cas, une seule liste est partagée par toutes les instances de `Dog' :

@example
class Dog:

    tricks = []             # mistaken use of a class variable

    def __init__(self, name):
        self.name = name

    def add_trick(self, trick):
        self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks                # unexpectedly shared by all dogs
['roll over', 'play dead']
@end example

Une conception correcte de la classe est d'utiliser une variable d'instance à la place :

@example
class Dog:

    def __init__(self, name):
        self.name = name
        self.tricks = []    # creates a new empty list for each dog

    def add_trick(self, trick):
        self.tricks.append(trick)

>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks
['roll over']
>>> e.tricks
['play dead']
@end example

@node Remarques diverses,Héritage,Une première approche des classes,Classes
@anchor{tutorial/classes random-remarks}@anchor{1c41}@anchor{tutorial/classes tut-remarks}@anchor{1c42}
@subsection Remarques diverses


@c These should perhaps be placed more carefully...

Si le même nom d'attribut apparaît à la fois dans une instance et dans une classe, alors la recherche d'attribut donne la priorité à l'instance :

@example
>>> class Warehouse:
...    purpose = 'storage'
...    region = 'west'
...
>>> w1 = Warehouse()
>>> print(w1.purpose, w1.region)
storage west
>>> w2 = Warehouse()
>>> w2.region = 'east'
>>> print(w2.purpose, w2.region)
storage east
@end example

Les attributs 'données' peuvent être référencés par des méthodes comme par des utilisateurs ordinaires ("clients") d'un objet. En d'autres termes, les classes ne sont pas utilisables pour implémenter des types de données purement abstraits. En fait, il n'est pas possible en Python d'imposer de masquer des données — tout est basé sur des conventions (d'un autre côté, l'implémentation de Python, écrite en C, peut complètement masquer les détails d'implémentation et contrôler l'accès à un objet si nécessaire ; ceci peut être utilisé par des extensions de Python écrites en C).

Les clients doivent utiliser les attributs 'données' avec précaution --- ils pourraient mettre le désordre dans les invariants gérés par les méthodes avec leurs propres valeurs d'attributs. Remarquez que les clients peuvent ajouter leurs propres attributs 'données' à une instance d'objet sans altérer la validité des méthodes, pour autant que les noms n'entrent pas en conflit --- là aussi, adopter une convention de nommage peut éviter bien des problèmes.

Il n'y a pas de notation abrégée pour référencer des attributs 'données' (ou les autres méthodes !) depuis les méthodes. Nous pensons que ceci améliore en fait la lisibilité des méthodes : il n'y a aucune chance de confondre variables locales et variables d'instances quand on regarde le code d'une méthode.

Souvent, le premier argument d'une méthode est nommé @code{self}. Ce n'est qu'une convention : le nom @code{self} n'a aucune signification particulière en Python. Notez cependant que si vous ne suivez pas cette convention, votre code risque d'être moins lisible pour d'autres programmeurs Python et il est aussi possible qu'un programme qui fasse l'introspection de classes repose sur une telle convention.

Tout objet fonction qui est un attribut de classe définit une méthode pour des instances de cette classe. Il n'est pas nécessaire que le texte de définition de la fonction soit dans la définition de la classe : il est possible d'affecter un objet fonction à une variable locale de la classe. Par exemple :

@example
# Function defined outside the class
def f1(self, x, y):
    return min(x, x+y)

class C:
    f = f1

    def g(self):
        return 'hello world'

    h = g
@end example

Maintenant, @code{f}, @code{g} et @code{h} sont toutes des attributs de la classe @code{C} et font référence à des fonctions objets. Par conséquent, ce sont toutes des méthodes des instances de @code{C} --- @code{h} est exactement identique à @code{g}. Remarquez qu'en pratique, ceci ne sert qu'à embrouiller le lecteur d'un programme.

Les méthodes peuvent appeler d'autres méthodes en utilisant des méthodes qui sont des attributs de l'argument @code{self} :

@example
class Bag:
    def __init__(self):
        self.data = []

    def add(self, x):
        self.data.append(x)

    def addtwice(self, x):
        self.add(x)
        self.add(x)
@end example

Les méthodes peuvent faire référence à des noms globaux de la même manière que les fonctions. La portée globale associée à une méthode est le module contenant la définition de la classe (la classe elle-même n'est jamais utilisée en tant que portée globale). Alors qu'il est rare d'avoir une bonne raison d'utiliser des données globales dans une méthode, il y a de nombreuses utilisations légitimes de la portée globale : par exemple, les fonctions et modules importés dans une portée globale peuvent être utilisés par des méthodes, de même que les fonctions et classes définies dans cette même portée. Habituellement, la classe contenant la méthode est elle-même définie dans cette portée globale et, dans la section suivante, nous verrons de bonnes raisons pour qu'une méthode référence sa propre classe.

Toute valeur est un objet et a donc une `classe' (appelée aussi son `type'). Elle est stockée dans @code{objet.__class__}.

@node Héritage,Variables privées,Remarques diverses,Classes
@anchor{tutorial/classes inheritance}@anchor{1c43}@anchor{tutorial/classes tut-inheritance}@anchor{1c44}
@subsection Héritage


Bien sûr, ce terme de "classe" ne serait pas utilisé s'il n'y avait pas d'héritage. La syntaxe pour définir une sous-classe est de cette forme :

@example
class DerivedClassName(BaseClassName):
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Le nom @code{BaseClassName} doit être défini dans une portée contenant la définition de la classe dérivée. À la place du nom d'une classe mère, une expression est aussi autorisée. Ceci peut être utile, par exemple, lorsque la classe mère est définie dans un autre module :

@example
class DerivedClassName(modname.BaseClassName):
@end example

L'exécution d'une définition de classe dérivée se déroule comme pour une classe mère. Quand l'objet de la classe est construit, la classe mère est mémorisée. Elle est utilisée pour la résolution des références d'attributs : si un attribut n'est pas trouvé dans la classe, la recherche se poursuit en regardant dans la classe mère. Cette règle est appliquée récursivement si la classe mère est elle-même dérivée d'une autre classe.

Il n'y a rien de particulier dans l'instanciation des classes dérivées : @code{DerivedClassName()} crée une nouvelle instance de la classe. Les références aux méthodes sont résolues comme suit : l'attribut correspondant de la classe est recherché, en remontant la hiérarchie des classes mères si nécessaire, et la référence de méthode est valide si cela conduit à une fonction.

Les classes dérivées peuvent surcharger des méthodes de leurs classes mères. Comme les méthodes n'ont aucun privilège particulier quand elles appellent d'autres méthodes d'un même objet, une méthode d'une classe mère qui appelle une autre méthode définie dans la même classe peut en fait appeler une méthode d'une classe dérivée qui la surcharge (pour les programmeurs C++ : toutes les méthodes de Python sont en effet "virtuelles").

Une méthode dans une classe dérivée peut aussi, en fait, vouloir étendre plutôt que simplement remplacer la méthode du même nom de sa classe mère. L'appel direct à la méthode de la classe mère s'écrit simplement @code{BaseClassName.nomMethode(self, arguments)}. C'est parfois utile également aux clients (notez bien que ceci ne fonctionne que si la classe mère est accessible en tant que @code{BaseClassName} dans la portée globale).

Python définit deux fonctions primitives pour gérer l'héritage :


@itemize *

@item 
utilisez @ref{42b,,isinstance()} pour tester le type d'une instance : @code{isinstance(obj, int)} renvoie @code{True} seulement si @code{obj.__class__} est égal à @ref{254,,int} ou à une autre classe dérivée de @ref{254,,int} ;

@item 
utilisez @ref{7ab,,issubclass()} pour tester l'héritage d'une classe : @code{issubclass(bool, int)} renvoie @code{True} car la classe @ref{451,,bool} est une sous-classe de @ref{254,,int}. Cependant, @code{issubclass(float, int)} renvoie @code{False} car @ref{2eb,,float} n'est pas une sous-classe de @ref{254,,int}.
@end itemize

@menu
* Héritage multiple:: 

@end menu

@node Héritage multiple,,,Héritage
@anchor{tutorial/classes multiple-inheritance}@anchor{1c45}@anchor{tutorial/classes tut-multiple}@anchor{1c46}
@subsubsection Héritage multiple


Python gère également une forme d'héritage multiple. Une définition de classe ayant plusieurs classes mères est de cette forme :

@example
class DerivedClassName(Base1, Base2, Base3):
    <statement-1>
    .
    .
    .
    <statement-N>
@end example

Dans la plupart des cas, vous pouvez vous représenter la recherche d'attributs dans les classes parentes comme étant : le plus profond d'abord, de gauche à droite, sans chercher deux fois dans la même classe si elle apparaît plusieurs fois dans la hiérarchie. Ainsi, si un attribut n'est pas trouvé dans @code{DerivedClassName}, il est recherché dans @code{Base1}, puis (récursivement) dans les classes mères de @code{Base1} ; s'il n'y est pas trouvé, il est recherché dans @code{Base2} et ses classes mères, et ainsi de suite.

Dans les faits, c'est un peu plus complexe que ça ; l'ordre de la recherche (`method resolution order, ou MRO' en anglais) change dynamiquement pour gérer des appels coopératifs à @ref{4c5,,super()}. Cette approche est connue sous le nom de la "appel de la méthode la plus proche" (`call-next-method' en anglais) dans d'autres langages avec héritage multiple. Elle est plus puissante que le simple appel à super que l'on trouve dans les langages à héritage simple.

L'ordre défini dynamiquement est nécessaire car tous les cas d'héritage multiple comportent une ou plusieurs relations en losange (où au moins une classe peut être accédée à partir de plusieurs chemins en partant de la classe la plus basse). Par exemple, puisque toutes les classes héritent de @ref{a7a,,object}, tout héritage multiple ouvre plusieurs chemins pour atteindre @ref{a7a,,object}. Pour qu'une classe mère ne soit pas appelée plusieurs fois, l'algorithme dynamique linéarise l'ordre de recherche d'une façon qui préserve l'ordre d'héritage, de la gauche vers la droite, spécifié dans chaque classe, qui appelle chaque classe parente une seule fois, qui est monotone (ce qui signifie qu'une classe peut être sous-classée sans affecter l'ordre d'héritage de ses parents). Prises ensemble, ces propriétés permettent de concevoir des classes de façon fiable et extensible dans un contexte d'héritage multiple. Pour plus de détails, consultez @ref{145e,,The Python 2.3 Method Resolution Order}.

@node Variables privées,Trucs et astuces,Héritage,Classes
@anchor{tutorial/classes private-variables}@anchor{1c47}@anchor{tutorial/classes tut-private}@anchor{1c2e}
@subsection Variables privées


Les membres "privés", qui ne peuvent être accédés que depuis l'intérieur d'un objet, n'existent pas en Python. Toutefois, il existe une convention respectée par la majorité du code Python : un nom préfixé par un tiret bas (comme @code{_spam}) doit être considéré comme une partie non publique de l'API (qu'il s'agisse d'une fonction, d'une méthode ou d'un attribut 'données'). Il doit être vu comme un détail d'implémentation pouvant faire l'objet de modifications futures sans préavis.

@geindex name;mangling

Dès lors qu'il y a un cas d'utilisation valable pour avoir des attributs privés aux classes (notamment pour éviter des conflits avec des noms définis dans des sous-classes), il existe un support (certes limité) pour un tel mécanisme, appelé `name mangling'. Tout identifiant de la forme @code{__spam} (avec au moins deux tirets bas en tête et au plus un à la fin) est remplacé textuellement par @code{_classname__spam}, où @code{classname} est le nom de la classe sans le ou les premiers tirets-bas. Ce "découpage" est effectué sans tenir compte de la position syntaxique de l'identifiant, tant qu'il est présent dans la définition d'une classe.


@subsubheading Voir aussi


La @ref{1c48,,spécification des transformations de noms} pour  les détails et cas particuliers.


Ce changement de nom est utile pour permettre à des sous-classes de surcharger des méthodes sans casser les appels de méthodes à l'intérieur d'une classe. Par exemple :

@example
class Mapping:
    def __init__(self, iterable):
        self.items_list = []
        self.__update(iterable)

    def update(self, iterable):
        for item in iterable:
            self.items_list.append(item)

    __update = update   # private copy of original update() method

class MappingSubclass(Mapping):

    def update(self, keys, values):
        # provides new signature for update()
        # but does not break __init__()
        for item in zip(keys, values):
            self.items_list.append(item)
@end example

L'exemple si dessus fonctionnerait même si @code{MappingSubclass} introduisait un identifieur @code{__update} puisqu'il a été remplacé avec @code{_Mapping__update} dans la classe @code{Mapping} et @code{_MappingSubclass__update} dans la classe @code{MappingSubclass} respectivement.

Notez que ces règles sont conçues avant tout pour éviter les accidents ; il reste possible d'accéder ou de modifier une variable considérée comme privée. Ceci peut même être utile dans certaines circonstances, comme au sein du débogueur.

Remarquez que le code que vous passez à @code{exec()}, @code{eval()} ne considère pas le nom de la classe appelante comme étant la classe courante ; le même effet s'applique à la directive @code{global} dont l'effet est, de la même façon, restreint au code compilé dans le même ensemble de byte-code. Les mêmes restrictions s'appliquent à @code{getattr()}, @code{setattr()} et @code{delattr()}, ainsi qu'aux références directes à @code{__dict__}.

@node Trucs et astuces,Itérateurs,Variables privées,Classes
@anchor{tutorial/classes odds-and-ends}@anchor{1c49}@anchor{tutorial/classes tut-odds}@anchor{1c4a}
@subsection Trucs et astuces


Il est parfois utile d'avoir un type de donnée similaire au `record' du Pascal ou au `struct' du C, qui regroupent ensemble quelques attributs « données » nommés. L'approche idiomatique correspondante en Python est d'utiliser des @ref{2f,,dataclasses} :

@example
from dataclasses import dataclass

@@dataclass
class Employee:
    name: str
    dept: str
    salary: int
@end example

@example
>>> john = Employee('john', 'computer lab', 1000)
>>> john.dept
'computer lab'
>>> john.salary
1000
@end example

À du code Python qui s'attend à recevoir un type de donnée abstrait spécifique, on peut souvent fournir une classe qui simule les méthodes de ce type. Par exemple, à une fonction qui formate des données extraites d'un objet fichier, vous pouvez lui passer comme argument une instance d'une classe qui implémente les méthodes @ref{1c13,,read()} et @ref{1c4b,,readline()} en puisant ses données à partir d'un tampon de chaînes de caractères.

@c (Unfortunately, this technique has its limitations: a class can't define
@c operations that are accessed by special syntax such as sequence subscripting
@c or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
@c not cause the interpreter to read further input from it.)

Les objets méthodes d'instances ont aussi des attributs : @ref{137f,,m.__self__} est l'instance d'objet avec la méthode @code{m()} et @ref{12da,,m.__func__} est l'@ref{296,,objet fonction} correspondant à la méthode.

@node Itérateurs,Générateurs,Trucs et astuces,Classes
@anchor{tutorial/classes iterators}@anchor{1c4c}@anchor{tutorial/classes tut-iterators}@anchor{1c4d}
@subsection Itérateurs


Vous avez maintenant certainement remarqué que l'on peut itérer sur la plupart des objets conteneurs en utilisant une instruction @ref{2e6,,for} :

@example
for element in [1, 2, 3]:
    print(element)
for element in (1, 2, 3):
    print(element)
for key in @{'one':1, 'two':2@}:
    print(key)
for char in "123":
    print(char)
for line in open("myfile.txt"):
    print(line, end='@w{'})
@end example

Ce style est simple, concis et pratique. L'utilisation d'itérateurs imprègne et unifie Python. En arrière plan, l'instruction @ref{2e6,,for} appelle la fonction @ref{7c1,,iter()} sur l'objet conteneur. Cette fonction renvoie un objet itérateur qui définit la méthode @ref{12ab,,__next__()}, laquelle accède aux éléments du conteneur un par un. Lorsqu'il n'y a plus d'élément, @ref{12ab,,__next__()} lève une exception @ref{be8,,StopIteration} qui indique à la boucle de l'instruction @code{for} de se terminer. Vous pouvez appeler la méthode @ref{12ab,,__next__()} en utilisant la fonction native @ref{7c2,,next()}. Cet exemple montre comment tout cela fonctionne :

@example
>>> s = 'abc'
>>> it = iter(s)
>>> it
<str_iterator object at 0x10c90e650>
>>> next(it)
'a'
>>> next(it)
'b'
>>> next(it)
'c'
>>> next(it)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    next(it)
StopIteration
@end example

Une fois compris les mécanismes de gestion des itérateurs, il est simple d'ajouter ce comportement à vos classes. Définissez une méthode @ref{1c4e,,__iter__()} qui renvoie un objet disposant d'une méthode @code{!__next__()}. Si la classe définit elle-même la méthode @code{__next__()}, alors @code{__iter__()} peut simplement renvoyer @code{self} :

@example
class Reverse:
    """Iterator for looping over a sequence backwards."""
    def __init__(self, data):
        self.data = data
        self.index = len(data)

    def __iter__(self):
        return self

    def __next__(self):
        if self.index == 0:
            raise StopIteration
        self.index = self.index - 1
        return self.data[self.index]
@end example

@example
>>> rev = Reverse('spam')
>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
...     print(char)
...
m
a
p
s
@end example

@node Générateurs,Expressions et générateurs,Itérateurs,Classes
@anchor{tutorial/classes generators}@anchor{1c4f}@anchor{tutorial/classes tut-generators}@anchor{1c50}
@subsection Générateurs


Les @ref{104a,,générateurs} sont des outils simples et puissants pour créer des itérateurs. Ils sont écrits comme des fonctions classiques mais utilisent l'instruction @ref{9bb,,yield} lorsqu'ils veulent renvoyer des données. À chaque fois qu'il est appelé par @ref{7c2,,next()}, le générateur reprend son exécution là où il s'était arrêté (en conservant tout son contexte d'exécution). Un exemple montre très bien combien les générateurs sont simples à créer :

@example
def reverse(data):
    for index in range(len(data)-1, -1, -1):
        yield data[index]
@end example

@example
>>> for char in reverse('golf'):
...     print(char)
...
f
l
o
g
@end example

Tout ce qui peut être fait avec des générateurs peut également être fait avec des itérateurs basés sur des classes, comme décrit dans le paragraphe précédent. Ce qui rend les générateurs si compacts, c'est que les méthodes @ref{1c51,,__iter__()} et @ref{1c52,,__next__()} sont créées automatiquement.

Une autre fonctionnalité clé est que les variables locales ainsi que le contexte d'exécution sont sauvegardés automatiquement entre les appels. Cela simplifie d'autant plus l'écriture de ces fonctions et rend leur code beaucoup plus lisible qu'avec une approche utilisant des variables d'instance telles que @code{self.index} et @code{self.data}.

En plus de la création automatique de méthodes et de la sauvegarde du contexte d'exécution, les générateurs lèvent automatiquement une exception @ref{be8,,StopIteration} lorsqu'ils terminent leur exécution. La combinaison de ces fonctionnalités rend très simple la création d'itérateurs, sans plus d'effort que l'écriture d'une fonction classique.

@node Expressions et générateurs,,Générateurs,Classes
@anchor{tutorial/classes generator-expressions}@anchor{1c53}@anchor{tutorial/classes tut-genexps}@anchor{1c54}
@subsection Expressions et générateurs


Des générateurs simples peuvent être codés très rapidement avec des expressions utilisant la même syntaxe que les compréhensions de listes, mais en utilisant des parenthèses à la place des crochets. Ces expressions sont conçues pour des situations où le générateur est utilisé tout de suite dans une fonction. Ces expressions sont plus compactes mais moins souples que des définitions complètes de générateurs et ont tendance à être plus économes en mémoire que leur équivalent en compréhension de listes.

Exemples :

@example
>>> sum(i*i for i in range(10))                 # sum of squares
285

>>> xvec = [10, 20, 30]
>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec))         # dot product
260

>>> unique_words = set(word for line in page  for word in line.split())

>>> valedictorian = max((student.gpa, student.name) for student in graduates)

>>> data = 'golf'
>>> list(data[i] for i in range(len(data)-1, -1, -1))
['f', 'l', 'o', 'g']
@end example

@node Survol de la bibliothèque standard,Survol de la bibliothèque standard -- Deuxième partie,Classes,Le tutoriel Python
@anchor{tutorial/stdlib doc}@anchor{1c55}@anchor{tutorial/stdlib brief-tour-of-the-standard-library}@anchor{1c56}@anchor{tutorial/stdlib tut-brieftour}@anchor{1c57}
@section Survol de la bibliothèque standard


@menu
* Interface avec le système d'exploitation:: 
* Jokers sur les noms de fichiers:: 
* Paramètres passés en ligne de commande:: 
* Redirection de la sortie d'erreur et fin d'exécution:: 
* Recherche de motifs dans les chaînes:: 
* Mathématiques:: 
* Accès à internet:: 
* Dates et heures:: 
* Compression de données:: 
* Mesure des performances:: 
* Contrôle qualité:: 
* Piles fournies:: 

@end menu

@node Interface avec le système d'exploitation,Jokers sur les noms de fichiers,,Survol de la bibliothèque standard
@anchor{tutorial/stdlib operating-system-interface}@anchor{1c58}@anchor{tutorial/stdlib tut-os-interface}@anchor{1c59}
@subsection Interface avec le système d'exploitation


Le module @ref{a0,,os} propose des dizaines de fonctions pour interagir avec le système d'exploitation :

@example
>>> import os
>>> os.getcwd()      # Return the current working directory
'C:\\Python313'
>>> os.chdir('/server/accesslogs')   # Change current working directory
>>> os.system('mkdir today')   # Run the command mkdir in the system shell
0
@end example

Veillez bien à utiliser @code{import os} plutôt que @code{from os import *}, sinon @ref{d7f,,os.open()} cache la primitive @ref{505,,open()} qui fonctionne différemment.

@geindex built-in function;help

Les primitives @ref{61d,,dir()} et @ref{8c4,,help()} sont des aides utiles lorsque vous travaillez en mode interactif avez des gros modules comme @ref{a0,,os} :

@example
>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>
@end example

Pour la gestion des fichiers et dossiers, le module @ref{c4,,shutil} expose une interface plus abstraite et plus facile à utiliser :

@example
>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
'archive.db'
>>> shutil.move('/build/executables', 'installdir')
'installdir'
@end example

@node Jokers sur les noms de fichiers,Paramètres passés en ligne de commande,Interface avec le système d'exploitation,Survol de la bibliothèque standard
@anchor{tutorial/stdlib file-wildcards}@anchor{1c5a}@anchor{tutorial/stdlib tut-file-wildcards}@anchor{1c5b}
@subsection Jokers sur les noms de fichiers


Le module @ref{63,,glob} fournit une fonction pour construire des listes de fichiers à partir de motifs :

@example
>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']
@end example

@node Paramètres passés en ligne de commande,Redirection de la sortie d'erreur et fin d'exécution,Jokers sur les noms de fichiers,Survol de la bibliothèque standard
@anchor{tutorial/stdlib command-line-arguments}@anchor{1c5c}@anchor{tutorial/stdlib tut-command-line-arguments}@anchor{1c5d}
@subsection Paramètres passés en ligne de commande


Common utility scripts often need to process command line arguments. These
arguments are stored in the @ref{d8,,sys} module's `argv' attribute as a list.  For
instance, let's take the following @code{demo.py} file:

@example
# File demo.py
import sys
print(sys.argv)
@end example

Here is the output from running @code{python demo.py one two three} at the command
line:

@example
['demo.py', 'one', 'two', 'three']
@end example

Le module @ref{6,,argparse} fournit un mécanisme plus sophistiqué pour traiter les arguments de la ligne de commande. Le script suivant extrait un ou plusieurs noms de fichiers et un nombre facultatif de lignes à afficher :

@example
import argparse

parser = argparse.ArgumentParser(
    prog='top',
    description='Show top lines from each file')
parser.add_argument('filenames', nargs='+')
parser.add_argument('-l', '--lines', type=int, default=10)
args = parser.parse_args()
print(args)
@end example

Lorsqu'il est exécuté avec la ligne de commande @code{python top.py --lines=5 alpha.txt beta.txt}, le script définit @code{args.lines} à @code{5} et @code{args.filenames} à @code{['alpha.txt', 'beta.txt']}.

@node Redirection de la sortie d'erreur et fin d'exécution,Recherche de motifs dans les chaînes,Paramètres passés en ligne de commande,Survol de la bibliothèque standard
@anchor{tutorial/stdlib error-output-redirection-and-program-termination}@anchor{1c5e}@anchor{tutorial/stdlib tut-stderr}@anchor{1c5f}
@subsection Redirection de la sortie d'erreur et fin d'exécution


Le module @ref{d8,,sys} a aussi des attributs pour `stdin', `stdout' et `stderr'. Ce dernier est utile pour émettre des messages d'avertissement ou d'erreur qui restent visibles même si `stdout' est redirigé :

@example
>>> sys.stderr.write('Warning, log file not found starting a new one\n')
Warning, log file not found starting a new one
@end example

Le moyen le plus direct de terminer un script est d'utiliser @code{sys.exit()}.

@node Recherche de motifs dans les chaînes,Mathématiques,Redirection de la sortie d'erreur et fin d'exécution,Survol de la bibliothèque standard
@anchor{tutorial/stdlib string-pattern-matching}@anchor{1c60}@anchor{tutorial/stdlib tut-string-pattern-matching}@anchor{1c61}
@subsection Recherche de motifs dans les chaînes


Le module @ref{b8,,re} fournit des outils basés sur les expressions rationnelles permettant des opérations complexes sur les chaînes. C'est une solution optimisée, utilisant une syntaxe concise, pour rechercher des motifs complexes ou effectuer des remplacements complexes dans les chaînes :

@example
>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'
@end example

Lorsque les opérations sont simples, il est préférable d'utiliser les méthodes des chaînes. Elles sont plus lisibles et plus faciles à déboguer :

@example
>>> 'tea for too'.replace('too', 'two')
'tea for two'
@end example

@node Mathématiques,Accès à internet,Recherche de motifs dans les chaînes,Survol de la bibliothèque standard
@anchor{tutorial/stdlib mathematics}@anchor{1c62}@anchor{tutorial/stdlib tut-mathematics}@anchor{1c63}
@subsection Mathématiques


The @ref{8d,,math} module gives access to the underlying C library functions for
floating-point math:

@example
>>> import math
>>> math.cos(math.pi / 4)
0.70710678118654757
>>> math.log(1024, 2)
10.0
@end example

Le module @ref{b7,,random} offre des outils pour faire des tirages aléatoires :

@example
>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(range(100), 10)   # sampling without replacement
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random()    # random float from the interval [0.0, 1.0)
0.17970987693706186
>>> random.randrange(6)    # random integer chosen from range(6)
4
@end example

Le module @ref{d1,,statistics} permet de calculer des valeurs statistiques basiques (moyenne, médiane, variance…) :

@example
>>> import statistics
>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> statistics.mean(data)
1.6071428571428572
>>> statistics.median(data)
1.25
>>> statistics.variance(data)
1.3720238095238095
@end example

Le projet SciPy <@indicateurl{https://scipy.org}> contient beaucoup d'autres modules dédiés aux calculs numériques.

@node Accès à internet,Dates et heures,Mathématiques,Survol de la bibliothèque standard
@anchor{tutorial/stdlib internet-access}@anchor{1c64}@anchor{tutorial/stdlib tut-internet-access}@anchor{1c65}
@subsection Accès à internet


Il existe beaucoup de modules permettant d'accéder à internet et gérer les protocoles réseaux. Les deux plus simples sont @ref{10a,,urllib.request} qui permet de récupérer des données à partir d'une URL et @ref{c9,,smtplib} pour envoyer des courriers électroniques :

@example
>>> from urllib.request import urlopen
>>> with urlopen('http://worldtimeapi.org/api/timezone/etc/UTC.txt') as response:
...     for line in response:
...         line = line.decode()             # Convert bytes to a str
...         if line.startswith('datetime'):
...             print(line.rstrip())         # Remove trailing newline
...
datetime: 2022-01-01T01:36:47.689215+00:00

>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@@example.org', 'jcaesar@@example.org',
... """To: jcaesar@@example.org
... From: soothsayer@@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()
@end example

(Notez que le deuxième exemple a besoin d'un serveur mail tournant localement.)

@node Dates et heures,Compression de données,Accès à internet,Survol de la bibliothèque standard
@anchor{tutorial/stdlib dates-and-times}@anchor{1c66}@anchor{tutorial/stdlib tut-dates-and-times}@anchor{1c67}
@subsection Dates et heures


Le module @ref{30,,datetime} propose des classes pour manipuler les dates et les heures de manière simple ou plus complexe. Bien que faire des calculs de dates et d'heures soit possible, la priorité de l'implémentation est mise sur l'extraction efficace des attributs pour le formatage et la manipulation. Le module gère aussi les objets dépendant des fuseaux horaires

@example
>>> # dates are easily constructed and formatted
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

>>> # dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368
@end example

@node Compression de données,Mesure des performances,Dates et heures,Survol de la bibliothèque standard
@anchor{tutorial/stdlib data-compression}@anchor{1c68}@anchor{tutorial/stdlib tut-data-compression}@anchor{1c69}
@subsection Compression de données


Les formats d'archivage et de compression les plus communs sont directement gérés par les modules @ref{132,,zlib}, @ref{66,,gzip}, @ref{13,,bz2}, @ref{89,,lzma}, @ref{130,,zipfile} et @ref{dd,,tarfile}

@example
>>> import zlib
>>> s = b'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
b'witch which has which witches wrist watch'
>>> zlib.crc32(s)
226805979
@end example

@node Mesure des performances,Contrôle qualité,Compression de données,Survol de la bibliothèque standard
@anchor{tutorial/stdlib performance-measurement}@anchor{1c6a}@anchor{tutorial/stdlib tut-performance-measurement}@anchor{1c6b}
@subsection Mesure des performances


Certains utilisateurs de Python sont très intéressés par les performances de différentes approches d'un même problème. Python propose un outil de mesure répondant simplement à ces questions.

Par exemple, pour échanger deux variables, il peut être tentant d'utiliser l'empaquetage et le dépaquetage de `n'-uplets plutôt que la méthode traditionnelle. Le module @ref{ee,,timeit} montre rapidement le léger gain de performance obtenu :

@example
>>> from timeit import Timer
>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.57535828626024577
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.54962537085770791
@end example

En opposition à @ref{ee,,timeit} et sa granularité fine, @ref{ae,,profile} et @ref{af,,pstats} fournissent des outils permettant d'identifier les parties les plus gourmandes en temps d'exécution dans des volumes de code plus grands.

@node Contrôle qualité,Piles fournies,Mesure des performances,Survol de la bibliothèque standard
@anchor{tutorial/stdlib quality-control}@anchor{1c6c}@anchor{tutorial/stdlib tut-quality-control}@anchor{1c6d}
@subsection Contrôle qualité


Une approche possible pour développer des applications de très bonne qualité est d'écrire des tests pour chaque fonction au fur et à mesure de son développement, puis d'exécuter ces tests fréquemment lors du processus de développement.

Le module @ref{3a,,doctest} cherche des tests dans les chaînes de documentation. Un test ressemble à un simple copier-coller d'un appel et son résultat depuis le mode interactif. Cela améliore la documentation en fournissant des exemples tout en prouvant qu'ils sont justes :

@example
def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> print(average([20, 30, 70]))
    40.0
    """
    return sum(values) / len(values)

import doctest
doctest.testmod()   # automatically validate the embedded tests
@end example

Le module @ref{105,,unittest} requiert plus d'efforts que le module @ref{3a,,doctest} mais il permet de construire un jeu de tests plus complet que l'on fait évoluer dans un fichier séparé :

@example
import unittest

class TestStatisticalFunctions(unittest.TestCase):

    def test_average(self):
        self.assertEqual(average([20, 30, 70]), 40.0)
        self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
        with self.assertRaises(ZeroDivisionError):
            average([])
        with self.assertRaises(TypeError):
            average(20, 30, 70)

unittest.main()  # Calling from the command line invokes all tests
@end example

@node Piles fournies,,Contrôle qualité,Survol de la bibliothèque standard
@anchor{tutorial/stdlib batteries-included}@anchor{1c6e}@anchor{tutorial/stdlib tut-batteries-included}@anchor{1c6f}
@subsection Piles fournies


Python adopte le principe des "piles fournies". Vous pouvez le constater au travers des fonctionnalités évoluées et solides fournies par ses plus gros paquets. Par exemple :


@itemize *

@item 
Les modules @ref{12d,,xmlrpc.client} et @ref{12e,,xmlrpc.server} permettent d'appeler des fonctions à distance quasiment sans effort. En dépit du nom des modules, aucune connaissance du XML n'est nécessaire.

@item 
Le paquet @ref{3b,,email} est une bibliothèque pour gérer les messages électroniques, incluant les MIME et autres encodages basés sur la 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}. Contrairement à @ref{c9,,smtplib} et @ref{ab,,poplib} qui envoient et reçoivent des messages, le paquet `email' est une boite à outils pour construire, lire des structures de messages complexes (comprenant des pièces jointes) ou implémenter des encodages et protocoles.

@item 
Le paquet @ref{81,,json} permet de lire et d'écrire du JSON, format d'encodage de données répandu. Le module @ref{29,,csv} gère la lecture et l'écriture de données stockées sous forme de valeurs séparées par des virgules dans des fichiers (`Comma-Separated Values' en anglais), format typiquement interopérable avec les bases de données et les feuilles de calculs. Pour la lecture du XML, utilisez les paquets @ref{124,,xml.etree.ElementTree}, @ref{120,,xml.dom} et @ref{128,,xml.sax}. Combinés, ces modules et paquets simplifient grandement l'échange de données entre les applications Python et les autres outils.

@item 
Le module @ref{ce,,sqlite3} est une abstraction de la bibliothèque SQLite, permettant de manipuler une base de données persistante, accédée et manipulée en utilisant une syntaxe SQL quasi standard.

@item 
L'internationalisation est possible grâce à de nombreux paquets tels que @ref{62,,gettext}, @ref{85,,locale} ou @ref{1b,,codecs}.
@end itemize

@node Survol de la bibliothèque standard -- Deuxième partie,Environnements virtuels et paquets,Survol de la bibliothèque standard,Le tutoriel Python
@anchor{tutorial/stdlib2 doc}@anchor{1c70}@anchor{tutorial/stdlib2 brief-tour-of-the-standard-library-part-ii}@anchor{1c71}@anchor{tutorial/stdlib2 tut-brieftourtwo}@anchor{1c72}
@section Survol de la bibliothèque standard -- Deuxième partie


Cette deuxième partie aborde des modules plus à destination des programmeurs professionnels. Ces modules sont rarement nécessaires dans de petits scripts.

@menu
* Formatage de l'affichage:: 
* Gabarits (templates en anglais): Gabarits templates en anglais. 
* Traitement des données binaires:: 
* Fils d'exécution: Fils d'exécution<2>. 
* Journalisation:: 
* Références faibles:: 
* Outils pour les listes:: 
* Decimal Floating-Point Arithmetic:: 

@end menu

@node Formatage de l'affichage,Gabarits templates en anglais,,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 output-formatting}@anchor{1c73}@anchor{tutorial/stdlib2 tut-output-formatting}@anchor{1c74}
@subsection Formatage de l'affichage


Le module @ref{ba,,reprlib} est une variante de la fonction @ref{7e7,,repr()}, spécialisé dans l'affichage concis de conteneurs volumineux ou fortement imbriqués :

@example
>>> import reprlib
>>> reprlib.repr(set('supercalifragilisticexpialidocious'))
"@{'a', 'c', 'd', 'e', 'f', 'g', ...@}"
@end example

Le module @ref{ad,,pprint} propose un contrôle plus fin de l'affichage des objets, aussi bien natifs que ceux définis par l'utilisateur, de manière à être lisible par l'interpréteur. Lorsque le résultat fait plus d'une ligne, il est séparé sur plusieurs lignes et est indenté pour rendre la structure plus visible :

@example
>>> import pprint
>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
...     'yellow'], 'blue']]]
...
>>> pprint.pprint(t, width=30)
[[[['black', 'cyan'],
   'white',
   ['green', 'red']],
  [['magenta', 'yellow'],
   'blue']]]
@end example

Le module @ref{eb,,textwrap} formate des paragraphes de texte pour tenir sur un écran d'une largeur donnée :

@example
>>> import textwrap
>>> doc = """The wrap() method is just like fill() except that it returns
... a list of strings instead of one big string with newlines to separate
... the wrapped lines."""
...
>>> print(textwrap.fill(doc, width=40))
The wrap() method is just like fill()
except that it returns a list of strings
instead of one big string with newlines
to separate the wrapped lines.
@end example

Le module @ref{85,,locale} utilise une base de données des formats spécifiques à chaque région pour les dates, nombres, etc. L'attribut @code{grouping} de la fonction de formatage permet de formater directement des nombres avec un séparateur :

@example
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv()          # get a mapping of conventions
>>> x = 1234567.8
>>> locale.format_string("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
...                      conv['frac_digits'], x), grouping=True)
'$1,234,567.80'
@end example

@node Gabarits templates en anglais,Traitement des données binaires,Formatage de l'affichage,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 templating}@anchor{1c75}@anchor{tutorial/stdlib2 tut-templating}@anchor{1c76}
@subsection Gabarits (`templates' en anglais)


Le module @ref{d2,,string} contient une classe polyvalente : @ref{672,,Template}. Elle permet d'écrire des gabarits (`templates' en anglais) avec une syntaxe simple, dans le but d'être utilisable par des non-développeurs. Ainsi, vos utilisateurs peuvent personnaliser leur application sans la modifier.

Le format utilise des marqueurs formés d'un @code{$} suivi d'un identifiant Python valide (caractères alphanumériques et tirets-bas). Entourer le marqueur d'accolades permet de lui coller d'autres caractères alphanumériques sans intercaler une espace. Écrire @code{$$} produit un simple @code{$} :

@example
>>> from string import Template
>>> t = Template('$@{village@}folk send $$10 to $cause.')
>>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.'
@end example

La méthode @ref{1c77,,substitute()} lève une exception @ref{33a,,KeyError} lorsqu'un marqueur n'a pas été fourni, ni dans un dictionnaire, ni sous forme d'un paramètre nommé. Dans certains cas, lorsque la donnée à appliquer peut n'être fournie que partiellement par l'utilisateur, la méthode @ref{1c78,,safe_substitute()} est plus appropriée car elle laisse tels quels les marqueurs manquants :

@example
>>> t = Template('Return the $item to $owner.')
>>> d = dict(item='unladen swallow')
>>> t.substitute(d)
Traceback (most recent call last):
  ...
KeyError: 'owner'
>>> t.safe_substitute(d)
'Return the unladen swallow to $owner.'
@end example

Les classes filles de @code{Template} peuvent définir leur propre délimiteur. Typiquement, un script de renommage de photos par lots peut choisir le symbole pourcent comme marqueur pour les champs tels que la date actuelle, le numéro de l'image ou son format :

@example
>>> import time, os.path
>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
>>> class BatchRename(Template):
...     delimiter = '%'
...
>>> fmt = input('Enter rename style (%d-date %n-seqnum %f-format):  ')
Enter rename style (%d-date %n-seqnum %f-format):  Ashley_%n%f

>>> t = BatchRename(fmt)
>>> date = time.strftime('%d%b%y')
>>> for i, filename in enumerate(photofiles):
...     base, ext = os.path.splitext(filename)
...     newname = t.substitute(d=date, n=i, f=ext)
...     print('@{0@} --> @{1@}'.format(filename, newname))

img_1074.jpg --> Ashley_0.jpg
img_1076.jpg --> Ashley_1.jpg
img_1077.jpg --> Ashley_2.jpg
@end example

Une autre utilisation des gabarits consiste à séparer la logique métier des détails spécifiques à chaque format de sortie. Il est ainsi possible de générer des gabarits spécifiques pour les fichiers XML, texte, HTML…

@node Traitement des données binaires,Fils d'exécution<2>,Gabarits templates en anglais,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 tut-binary-formats}@anchor{1c79}@anchor{tutorial/stdlib2 working-with-binary-data-record-layouts}@anchor{1c7a}
@subsection Traitement des données binaires


Le module @ref{d4,,struct} expose les fonctions @ref{1255,,pack()} et @ref{1754,,unpack()} permettant de travailler avec des données binaires. L'exemple suivant montre comment parcourir un entête de fichier ZIP sans recourir au module @ref{130,,zipfile}. Les marqueurs @code{"H"} et @code{"I"} représentent des nombres entiers non signés, stockés respectivement sur deux et quatre octets. Le @code{"<"} indique qu'ils ont une taille standard et utilisent la convention petit-boutiste :

@example
import struct

with open('myfile.zip', 'rb') as f:
    data = f.read()

start = 0
for i in range(3):                      # show the first 3 file headers
    start += 14
    fields = struct.unpack('<IIIHH', data[start:start+16])
    crc32, comp_size, uncomp_size, filenamesize, extra_size = fields

    start += 16
    filename = data[start:start+filenamesize]
    start += filenamesize
    extra = data[start:start+extra_size]
    print(filename, hex(crc32), comp_size, uncomp_size)

    start += extra_size + comp_size     # skip to the next header
@end example

@node Fils d'exécution<2>,Journalisation,Traitement des données binaires,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 multi-threading}@anchor{1c7b}@anchor{tutorial/stdlib2 tut-multi-threading}@anchor{1c7c}
@subsection Fils d'exécution


Des tâches indépendantes peuvent être exécutées de manière non séquentielle en utilisant des fils d'exécution (`threading' en anglais). Les fils d'exécution peuvent être utilisés pour améliorer la réactivité d'une application qui interagit avec l'utilisateur pendant que d'autres traitements sont exécutés en arrière-plan. Une autre utilisation typique est de séparer sur deux fils d'exécution distincts les entrées / sorties et le calcul.

Le code suivant donne un exemple d'utilisation du module @ref{ec,,threading} exécutant des tâches en arrière-plan pendant que le programme principal continue de s'exécuter :

@example
import threading, zipfile

class AsyncZip(threading.Thread):
    def __init__(self, infile, outfile):
        threading.Thread.__init__(self)
        self.infile = infile
        self.outfile = outfile

    def run(self):
        f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
        f.write(self.infile)
        f.close()
        print('Finished background zip of:', self.infile)

background = AsyncZip('mydata.txt', 'myarchive.zip')
background.start()
print('The main program continues to run in foreground.')

background.join()    # Wait for the background task to finish
print('Main program waited until background was done.')
@end example

Le principal défi des applications avec plusieurs fils d'exécution consiste à coordonner ces fils qui partagent des données ou des ressources. Pour ce faire, le module @code{threading} expose quelques outils dédiés à la synchronisation comme les verrous (`locks' en anglais), les événements (`events' en anglais), les variables conditionnelles (`condition variables' en anglais) et les sémaphores (`semaphore' en anglais).

Bien que ces outils soient puissants, de petites erreurs de conception peuvent engendrer des problèmes difficiles à reproduire. Donc, l'approche classique pour coordonner des tâches est de restreindre l'accès d'une ressource à un seul fil d'exécution et d'utiliser le module @ref{b5,,queue} pour alimenter ce fil d'exécution en requêtes venant d'autres fils d'exécution. Les applications utilisant des @ref{1365,,Queue} pour leurs communication et coordination entre fils d'exécution sont plus simples à concevoir, plus lisibles et plus fiables.

@node Journalisation,Références faibles,Fils d'exécution<2>,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 logging}@anchor{1c7d}@anchor{tutorial/stdlib2 tut-logging}@anchor{1c7e}
@subsection Journalisation


Le module @ref{86,,logging} est un système de journalisation complet. Dans son utilisation la plus élémentaire, les messages sont simplement envoyés dans un fichier ou sur @code{sys.stderr} :

@example
import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')
@end example

Cela produit l'affichage suivant :

@example
WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down
@end example

Par défaut, les messages d'information et de débogage sont ignorés, les autres sont envoyés vers la sortie standard. Il est aussi possible d'envoyer les messages par courriel, datagrammes, en utilisant des connecteurs réseau ou vers un serveur HTTP. Des nouveaux filtres permettent d'utiliser des sorties différentes en fonction de la priorité du message : @ref{1c7f,,DEBUG}, @ref{1c80,,INFO}, @ref{1c81,,WARNING}, @ref{1c82,,ERROR} et @ref{1c83,,CRITICAL}.

La configuration de la journalisation peut être effectuée directement dans le code Python ou peut être chargée depuis un fichier de configuration, permettant de personnaliser la journalisation sans modifier l'application.

@node Références faibles,Outils pour les listes,Journalisation,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 tut-weak-references}@anchor{1c84}@anchor{tutorial/stdlib2 weak-references}@anchor{1c85}
@subsection Références faibles


Python gère lui-même la mémoire (par comptage des références pour la plupart des objets et en utilisant un @ref{18a7,,ramasse-miettes} (`garbage collector' en anglais) pour éliminer les cycles). La mémoire est libérée rapidement lorsque sa dernière référence est supprimée.

Cette approche fonctionne bien pour la majorité des applications mais, parfois, il est nécessaire de surveiller un objet seulement durant son utilisation par quelque chose d'autre. Malheureusement, le simple fait de le suivre crée une référence qui rend l'objet permanent. Le module @ref{113,,weakref} expose des outils pour suivre les objets sans pour autant créer une référence. Lorsqu'un objet n'est pas utilisé, il est automatiquement supprimé du tableau des références faibles et une fonction de rappel (`callback' en anglais) est appelée. Un exemple typique est le cache d'objets coûteux à créer :

@example
>>> import weakref, gc
>>> class A:
...     def __init__(self, value):
...         self.value = value
...     def __repr__(self):
...         return str(self.value)
...
>>> a = A(10)                   # create a reference
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a            # does not create a reference
>>> d['primary']                # fetch the object if it is still alive
10
>>> del a                       # remove the one reference
>>> gc.collect()                # run garbage collection right away
0
>>> d['primary']                # entry was automatically removed
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    d['primary']                # entry was automatically removed
  File "C:/python313/lib/weakref.py", line 46, in __getitem__
    o = self.data[key]()
KeyError: 'primary'
@end example

@node Outils pour les listes,Decimal Floating-Point Arithmetic,Références faibles,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 tools-for-working-with-lists}@anchor{1c86}@anchor{tutorial/stdlib2 tut-list-tools}@anchor{1c87}
@subsection Outils pour les listes


Beaucoup de structures de données peuvent être représentées avec les listes natives. Cependant, d'autres besoins peuvent émerger pour des structures ayant des caractéristiques différentes, typiquement en termes de performance.

The @ref{7,,array} module provides an @ref{19e,,array} object that is like
a list that stores only homogeneous data and stores it more compactly.  The
following example shows an array of numbers stored as two byte unsigned binary
numbers (typecode @code{"H"}) rather than the usual 16 bytes per entry for regular
lists of Python int objects:

@example
>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])
@end example

The @ref{1d,,collections} module provides a @ref{5c6,,deque} object
that is like a list with faster appends and pops from the left side but slower
lookups in the middle. These objects are well suited for implementing queues
and breadth first tree searches:

@example
>>> from collections import deque
>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print("Handling", d.popleft())
Handling task1
@end example

@example
unsearched = deque([starting_node])
def breadth_first_search(unsearched):
    node = unsearched.popleft()
    for m in gen_moves(node):
        if is_goal(m):
            return m
        unsearched.append(m)
@end example

En plus de fournir des implémentations de listes alternatives, la bibliothèque fournit des outils tels que @ref{11,,bisect}, un module contenant des fonctions de manipulation de listes triées :

@example
>>> import bisect
>>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
>>> bisect.insort(scores, (300, 'ruby'))
>>> scores
[(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]
@end example

Le module @ref{68,,heapq} permet d'implémenter des tas (`heap' en anglais) à partir de simples listes. La valeur la plus faible est toujours à la première position (indice 0). C'est utile dans les cas où l'application accède souvent à l'élément le plus petit mais sans vouloir classer entièrement la liste :

@example
>>> from heapq import heapify, heappop, heappush
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data)                      # rearrange the list into heap order
>>> heappush(data, -5)                 # add a new entry
>>> [heappop(data) for i in range(3)]  # fetch the three smallest entries
[-5, 0, 1]
@end example

@node Decimal Floating-Point Arithmetic,,Outils pour les listes,Survol de la bibliothèque standard -- Deuxième partie
@anchor{tutorial/stdlib2 decimal-floating-point-arithmetic}@anchor{1c88}@anchor{tutorial/stdlib2 tut-decimal-fp}@anchor{1c89}
@subsection Decimal Floating-Point Arithmetic


The @ref{36,,decimal} module offers a @ref{29a,,Decimal} datatype for
decimal floating-point arithmetic.  Compared to the built-in @ref{2eb,,float}
implementation of binary floating point, the class is especially helpful for


@itemize *

@item 
les applications traitant de finance et autres utilisations nécessitant une représentation décimale exacte,

@item 
le contrôle de la précision,

@item 
le contrôle sur les arrondis pour répondre à des obligations légales ou réglementaires,

@item 
suivre les décimales significatives, ou

@item 
les applications pour lesquelles l'utilisateur attend des résultats identiques aux calculs faits à la main.
@end itemize

Par exemple, calculer 5 % de taxe sur une facture de 70 centimes donne un résultat différent en nombre à virgule flottante binaire et décimale. La différence devient significative lorsqu'on arrondit le résultat au centime près :

@example
>>> from decimal import *
>>> round(Decimal('0.70') * Decimal('1.05'), 2)
Decimal('0.74')
>>> round(.70 * 1.05, 2)
0.73
@end example

Le résultat d'un calcul donné par @ref{29a,,Decimal} conserve les zéros non-significatifs. La classe conserve automatiquement quatre décimales significatives pour des opérandes à deux décimales significatives. La classe @code{Decimal} imite les mathématiques telles qu'elles pourraient être effectuées à la main, évitant les problèmes typiques de l'arithmétique binaire à virgule flottante qui n'est pas capable de représenter exactement certaines quantités décimales.

La représentation exacte de la classe @ref{29a,,Decimal} lui permet de faire des calculs de modulo ou des tests d'égalité qui ne seraient pas possibles avec une représentation à virgule flottante binaire :

@example
>>> Decimal('1.00') % Decimal('.10')
Decimal('0.00')
>>> 1.00 % 0.10
0.09999999999999995

>>> sum([Decimal('0.1')]*10) == Decimal('1.0')
True
>>> 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 == 1.0
False
@end example

Le module @ref{36,,decimal} permet de faire des calculs avec autant de précision que nécessaire :

@example
>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')
@end example

@node Environnements virtuels et paquets,Pour aller plus loin,Survol de la bibliothèque standard -- Deuxième partie,Le tutoriel Python
@anchor{tutorial/venv doc}@anchor{1c8a}@anchor{tutorial/venv tut-venv}@anchor{1c8b}@anchor{tutorial/venv virtual-environments-and-packages}@anchor{1c8c}
@section Environnements virtuels et paquets


@menu
* Introduction: Introduction<4>. 
* Création d'environnements virtuels:: 
* Gestion des paquets avec pip:: 

@end menu

@node Introduction<4>,Création d'environnements virtuels,,Environnements virtuels et paquets
@anchor{tutorial/venv introduction}@anchor{1c8d}
@subsection Introduction


Les programmes Python utilisent souvent des paquets et modules qui ne font pas partie de la bibliothèque standard. Ils nécessitent aussi, parfois, une version spécifique d'une bibliothèque, par exemple parce qu'un certain bogue a été corrigé ou encore que le programme a été implémenté en utilisant une version obsolète de l'interface de cette bibliothèque.

Cela signifie qu'il n'est pas toujours possible, pour une installation unique de Python, de couvrir tous les besoins de toutes les applications. Basiquement, si une application A dépend de la version 1.0 d'un module et qu'une application B dépend de la version 2.0, ces dépendances entrent en conflit et installer la version 1.0 ou 2.0 laisse une des deux applications incapable de fonctionner.

La solution est de créer un @ref{1c8e,,environnement virtuel}, un dossier auto-suffisant qui contient une installation de Python pour une version particulière de Python ainsi que des paquets additionnels.

Différentes applications peuvent alors utiliser des environnements virtuels différents. Pour résoudre l'exemple précédent où il existe un conflit de dépendances, l'application A a son environnement virtuel avec la version 1.0 installée pendant que l'application B a un autre environnement virtuel avec la version 2.0. Si l'application B requiert que la bibliothèque soit mise à jour à la version 3.0, cela n'affecte pas l'environnement de A.

@node Création d'environnements virtuels,Gestion des paquets avec pip,Introduction<4>,Environnements virtuels et paquets
@anchor{tutorial/venv creating-virtual-environments}@anchor{1c8f}
@subsection Création d'environnements virtuels


The module used to create and manage virtual environments is called
@ref{110,,venv}.  @ref{110,,venv} will install the Python version from which
the command was run (as reported by the @ref{d09,,--version} option).
For instance, executing the command with @code{python3.12} will install
version 3.12.

Pour créer un environnement virtuel, décidez d'un dossier où vous voulez le placer et exécutez le module @ref{110,,venv} comme un script avec le chemin du dossier :

@example
python -m venv tutorial-env
@end example

Cela crée le dossier @code{tutorial-env} (s'il n'existe pas) et des sous-dossiers contenant une copie de l'interpréteur Python et d'autres fichiers utiles.

Un répertoire habituel pour un environnement virtuel est @code{.venv}. Ce nom fait que le répertoire est généralement caché dans votre explorateur de fichiers, et donc non gênant, tout en lui donnant un nom qui explique pourquoi le répertoire existe. Il empêche également de rentrer en conflit avec les fichiers de définition de variable d'environnement @code{.env} que certains outils utilisent.

Une fois l'environnement virtuel créé, vous pouvez l'activer.

Sur Windows, lancez :

@example
tutorial-env\Scripts\activate
@end example

Sur Unix et MacOS, lancez :

@example
source tutorial-env/bin/activate
@end example

(Ce script est écrit pour le shell @code{bash}. Si vous utilisez @code{csh} ou @code{fish}, utilisez les variantes @code{activate.csh} ou @code{activate.fish}.)

Activer l'environnement virtuel change le prompt de votre ligne de commande pour afficher le nom de l'environnement virtuel que vous utilisez. Cela modifie aussi l'environnement afin, lorsque vous tapez @code{python}, d'exécuter la version spécifique de Python installée dans l'environnement. Par exemple :

@example
$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May  6 2016, 10:59:36)
  ...
>>> import sys
>>> sys.path
['@w{'}, '/usr/local/lib/python35.zip', ...,
'~/envs/tutorial-env/lib/python3.5/site-packages']
>>>
@end example

Pour désactiver un environnement virtuel, tapez :

@example
deactivate
@end example

dans le terminal.

@node Gestion des paquets avec pip,,Création d'environnements virtuels,Environnements virtuels et paquets
@anchor{tutorial/venv managing-packages-with-pip}@anchor{1c90}
@subsection Gestion des paquets avec `pip'


Vous pouvez installer, mettre à jour et supprimer des paquets en utilisant un programme appelé @code{pip}. Par défaut, @code{pip} installe les paquets du Python Package Index@footnote{https://pypi.org}. Vous pouvez parcourir le Python Package Index avec un navigateur.

@code{pip} a plusieurs sous-commandes : @code{install}, @code{uninstall}, @code{freeze}, etc. Consultez le guide @ref{ee0,,Installation de modules Python} pour une documentation exhaustive sur @code{pip}.

Vous pouvez installer la dernière version d'un paquet en indiquant son nom :

@example
(tutorial-env) $ python -m pip install novas
Collecting novas
  Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
  Running setup.py install for novas
Successfully installed novas-3.1.1.3
@end example

Vous pouvez installer une version spécifique d'un paquet en donnant le nom du paquet suivi de @code{==} et du numéro de version souhaitée :

@example
(tutorial-env) $ python -m pip install requests==2.6.0
Collecting requests==2.6.0
  Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0
@end example

Si vous relancez cette commande, @code{pip} remarque que la version demandée est déjà installée et ne fait rien. Vous pouvez fournir un numéro de version différent pour récupérer cette version ou lancer @code{python -m pip install --upgrade} pour mettre à jour le paquet à la dernière version :

@example
(tutorial-env) $ python -m pip install --upgrade requests
Collecting requests
Installing collected packages: requests
  Found existing installation: requests 2.6.0
    Uninstalling requests-2.6.0:
      Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0
@end example

@code{python -m pip uninstall} suivi d'un ou plusieurs noms de paquets les supprime de votre environnement virtuel.

@code{python -m pip show} affiche des informations à propos d'un paquet précis :

@example
(tutorial-env) $ python -m pip show requests
---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: me@@kennethreitz.com
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
Requires:
@end example

@code{python -m pip list} liste tous les paquets installés dans l'environnement virtuel :

@example
(tutorial-env) $ python -m pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)
@end example

@code{python -m pip freeze} produit une liste similaire des paquets installés mais l'affichage adopte un format que @code{pip install} peut lire. La convention habituelle est de mettre cette liste dans un fichier @code{requirements.txt} :

@example
(tutorial-env) $ python -m pip freeze > requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0
@end example

Le fichier @code{requirements.txt} peut alors être ajouté dans un système de gestion de versions comme faisant partie de votre application. Les utilisateurs peuvent alors installer tous les paquets nécessaires à l'application avec @code{install -r} :

@example
(tutorial-env) $ python -m pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
  ...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
  ...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
  ...
Installing collected packages: novas, numpy, requests
  Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0
@end example

@code{pip} has many more options.  Consult the @ref{ee0,,Installation de modules Python}
guide for complete documentation for @code{pip}.  When you've written
a package and want to make it available on the Python Package Index,
consult the Python packaging user guide@footnote{https://packaging.python.org/en/latest/tutorials/packaging-projects/}.

@node Pour aller plus loin,Édition interactive des entrées et substitution d'historique,Environnements virtuels et paquets,Le tutoriel Python
@anchor{tutorial/whatnow doc}@anchor{1c91}@anchor{tutorial/whatnow tut-whatnow}@anchor{1c92}@anchor{tutorial/whatnow what-now}@anchor{1c93}
@section Pour aller plus loin


La lecture de ce tutoriel a probablement renforcé votre intérêt pour Python et vous devez être impatient de l'utiliser pour résoudre des vrais problèmes. Où aller pour en apprendre plus ?

Ce tutoriel fait partie de la documentation de Python, et la documentation de Python est vaste :


@itemize *

@item 
@ref{143,,La bibliothèque standard} :

Nous vous conseillons de naviguer dans le manuel, c'est une référence complète (quoique laconique) sur les types, fonctions et modules de la bibliothèque standard. La distribution standard de Python inclut `énormément' de code supplémentaire. Il existe des modules pour lire les courriels, récupérer des documents `via' HTTP, générer des nombres aléatoires, analyser les paramètres de la ligne de commande, compresser des données et beaucoup d'autres fonctions. Une balade dans la documentation de la bibliothèque vous donnera une idée de ce qui est disponible.

@item 
@ref{ee0,,Installation de modules Python} explique comment installer des paquets écrits par d'autres utilisateurs de Python.

@item 
@ref{144,,La référence du langage Python} contient une explication détaillée de la syntaxe et sémantique de Python. C'est une lecture fastidieuse, mais elle a sa place dans une documentation exhaustive.
@end itemize

D'autres ressources :


@itemize *

@item 
@indicateurl{https://www.python.org} : le site principal pour Python. Il contient du code, de la documentation, des liens vers d'autres sites traitant de Python partout sur Internet.

@item 
@indicateurl{https://docs.python.org/fr/} offre un accès rapide à la documentation de Python en français.

@item 
@indicateurl{https://pypi.org} (`The Python Package Index' en anglais, pour le "répertoire des paquets Python") : auparavant surnommé "La Fromagerie" @footnote{
« Cheese Shop » est un sketch de Monty Python : un client entre dans une fromagerie, mais peu importe le fromage que demande le client, le vendeur dit qu’il n’en a pas.
} (`The Cheese Shop' en anglais), c'est un catalogue de modules Python disponibles au téléchargement, construit par les utilisateurs. Lorsque vous commencez à distribuer du code, vous pouvez l'inscrire ici afin que les autres puissent le trouver.

@item 
@indicateurl{https://code.activestate.com/recipes/langs/python/} : "The Python Cookbook" est un recueil assez imposant d'exemples de code, de modules et de scripts. Les contributions les plus remarquables y sont regroupées dans le livre "Python Cookbook" (O'Reilly & Associates, ISBN 0-596-00797-3).

@item 
@indicateurl{https://pyvideo.org} regroupe des liens vers des vidéos relatives à Python, enregistrées lors de conférences ou de réunions de groupes d'utilisateurs.

@item 
@indicateurl{https://scipy.org} : le projet "The Scientific Python" contient des modules pour manipuler et calculer rapidement sur des tableaux. Le projet héberge aussi divers paquets sur l'algèbre linéaire, les transformées de Fourier, des résolveurs non-linéaires, différentes distributions de nombres aléatoires, l'analyse statistique et d'autres choses du domaine scientifique.
@end itemize

Pour poser des questions ou remonter des problèmes liés à Python, vous pouvez écrire sur le forum @code{comp.lang.python} ou les envoyer à la liste de diffusion <@email{python-list@@python.org}>. Le forum et la liste de diffusion sont liées, un message publié sur l'un sera automatiquement transféré sur l'autre. Des centaines de messages y sont publiés chaque jour, posant (ou répondant à) des questions, suggérant de nouvelles fonctionnalités et annonçant des nouveaux modules. Les archives sont disponibles à @indicateurl{https://mail.python.org/pipermail/}.

Avant de publier un message, assurez-vous d'avoir lu la liste de la @ref{1c94,,Foire Aux Questions} (aussi appelée FAQ). La FAQ répond à beaucoup de questions fréquentes et contient probablement une solution à votre problème.

@subsubheading Notes


@node Édition interactive des entrées et substitution d'historique,Floating-Point Arithmetic Issues and Limitations,Pour aller plus loin,Le tutoriel Python
@anchor{tutorial/interactive doc}@anchor{1c95}@anchor{tutorial/interactive interactive-input-editing-and-history-substitution}@anchor{1c96}@anchor{tutorial/interactive tut-interacting}@anchor{1b76}
@section Édition interactive des entrées et substitution d'historique


Certaines versions de l'interpréteur Python prennent en charge l'édition de la ligne d'entrée courante et la substitution d'historique, similaires aux facilités que l'on trouve dans le shell Korn et dans le shell GNU Bash. Ces implémentations utilisent la bibliothèque GNU Readline@footnote{https://tiswww.case.edu/php/chet/readline/rltop.html}, qui gère plusieurs styles d'édition. La bibliothèque a sa propre documentation, nous ne la dupliquons pas ici.

@menu
* Complétion automatique et édition de l'historique:: 
* Alternatives à l'interpréteur interactif:: 

@end menu

@node Complétion automatique et édition de l'historique,Alternatives à l'interpréteur interactif,,Édition interactive des entrées et substitution d'historique
@anchor{tutorial/interactive tab-completion-and-history-editing}@anchor{1c97}@anchor{tutorial/interactive tut-keybindings}@anchor{1c98}
@subsection Complétion automatique et édition de l'historique


Completion of variable and module names is
@ref{fb4,,automatically enabled} at interpreter startup so
that the @code{Tab} key invokes the completion function; it looks at
Python statement names, the current local variables, and the available
module names.  For dotted expressions such as @code{string.a}, it will evaluate
the expression up to the final @code{'.'} and then suggest completions from
the attributes of the resulting object.  Note that this may execute
application-defined code if an object with a @ref{4bc,,__getattr__()} method
is part of the expression.  The default configuration also saves your
history into a file named @code{.python_history} in your user directory.
The history will be available again during the next interactive interpreter
session.

@node Alternatives à l'interpréteur interactif,,Complétion automatique et édition de l'historique,Édition interactive des entrées et substitution d'historique
@anchor{tutorial/interactive alternatives-to-the-interactive-interpreter}@anchor{1c99}@anchor{tutorial/interactive tut-commentary}@anchor{1c9a}
@subsection Alternatives à l'interpréteur interactif


Cette facilité constitue un énorme pas en avant comparé aux versions précédentes de l'interpréteur. Toutefois, il reste des fonctions à implémenter comme l'indentation correcte sur les lignes de continuation (l'analyseur sait si une indentation doit suivre) ; le mécanisme de complétion devrait utiliser la table de symboles de l'interpréteur. Une commande pour vérifier (ou même suggérer) les correspondances de parenthèses, de guillemets, etc., serait également utile.

Une alternative améliorée de l'interpréteur interactif est développée depuis maintenant quelques temps : IPython@footnote{https://ipython.org/}. Il fournit la complétion, l'exploration d'objets et une gestion avancée de l'historique. Il peut également être personnalisé en profondeur et embarqué dans d'autres applications. Un autre environnement interactif amélioré similaire est bpython@footnote{https://bpython-interpreter.org/}.

@c import math
@c from fractions import Fraction

@node Floating-Point Arithmetic Issues and Limitations,Annexe,Édition interactive des entrées et substitution d'historique,Le tutoriel Python
@anchor{tutorial/floatingpoint doc}@anchor{1c9b}@anchor{tutorial/floatingpoint floating-point-arithmetic-issues-and-limitations}@anchor{1c9c}@anchor{tutorial/floatingpoint tut-fp-issues}@anchor{1c9d}
@section Floating-Point Arithmetic:  Issues and Limitations


Floating-point numbers are represented in computer hardware as base 2 (binary)
fractions.  For example, the `decimal' fraction @code{0.625}
has value 6/10 + 2/100 + 5/1000, and in the same way the `binary' fraction @code{0.101}
has value 1/2 + 0/4 + 1/8. These two fractions have identical values, the only
real difference being that the first is written in base 10 fractional notation,
and the second in base 2.

Malheureusement, la plupart des fractions décimales ne peuvent pas avoir de représentation exacte en fractions binaires. Par conséquent, en général, les nombres à virgule flottante que vous donnez sont seulement approximés en fractions binaires pour être stockés dans la machine.

Le problème est plus simple à aborder en base 10. Prenons par exemple, la fraction 1/3. Vous pouvez l'approximer en une fraction décimale :

@example
0.3
@end example

ou, mieux

@example
0.33
@end example

ou, mieux

@example
0.333
@end example

etc. Peu importe le nombre de décimales que vous écrivez, le résultat ne vaut jamais exactement 1/3, mais c'est une estimation s'en approchant toujours mieux.

De la même manière, peu importe combien de décimales en base 2 vous utilisez, la valeur décimale 0.1 ne peut pas être représentée exactement en fraction binaire. En base 2, 1/10 est le nombre périodique suivant

@example
0.0001100110011001100110011001100110011001100110011...
@end example

En se limitant à une quantité finie de bits, on ne peut obtenir qu'une approximation. Sur la majorité des machines aujourd'hui, les nombres à virgule flottante sont approximés par une fraction binaire avec les 53 premiers bits comme numérateur et une puissance de deux au dénominateur. Dans le cas de 1/10, la fraction binaire est @code{3602879701896397 / 2 ** 55} qui est proche mais ne vaut pas exactement 1/10.

Many users are not aware of the approximation because of the way values are
displayed.  Python only prints a decimal approximation to the true decimal
value of the binary approximation stored by the machine.  On most machines, if
Python were to print the true decimal value of the binary approximation stored
for 0.1, it would have to display:

@example
>>> 0.1
0.1000000000000000055511151231257827021181583404541015625
@end example

That is more digits than most people find useful, so Python keeps the number
of digits manageable by displaying a rounded value instead:

@example
>>> 1 / 10
0.1
@end example

Rappelez-vous simplement que, bien que la valeur affichée ressemble à la valeur exacte de 1/10, la valeur stockée est la représentation la plus proche en fraction binaire.

Il existe beaucoup de nombres décimaux qui partagent une même approximation en fraction binaire. Par exemple, @code{0.1}, @code{0.10000000000000001} et @code{0.1000000000000000055511151231257827021181583404541015625} ont tous pour approximation @code{3602879701896397 / 2 ** 55}. Puisque toutes ces valeurs décimales partagent la même approximation, chacune peut être affichée tout en respectant @code{eval(repr(x)) == x}.

Historiquement, le mode interactif de Python et la primitive @ref{7e7,,repr()} choisissaient la version avec 17 décimales significatives, @code{0.10000000000000001}. Python, depuis la version 3.1 (sur la majorité des systèmes) est maintenant capable de choisir la plus courte représentation et n'affiche que @code{0.1}.

Note that this is in the very nature of binary floating point: this is not a bug
in Python, and it is not a bug in your code either.  You'll see the same kind of
thing in all languages that support your hardware's floating-point arithmetic
(although some languages may not `display' the difference by default, or in all
output modes).

For more pleasant output, you may wish to use string formatting to produce a
limited number of significant digits:

@example
>>> format(math.pi, '.12g')  # give 12 significant digits
'3.14159265359'

>>> format(math.pi, '.2f')   # give 2 digits after the point
'3.14'

>>> repr(math.pi)
'3.141592653589793'
@end example

Il est important de comprendre que tout cela n'est, au sens propre, qu'une illusion : vous demandez simplement à Python d'arrondir la valeur stockée réellement dans la machine à `l'affichage'.

One illusion may beget another.  For example, since 0.1 is not exactly 1/10,
summing three values of 0.1 may not yield exactly 0.3, either:

@example
>>> 0.1 + 0.1 + 0.1 == 0.3
False
@end example

Also, since the 0.1 cannot get any closer to the exact value of 1/10 and
0.3 cannot get any closer to the exact value of 3/10, then pre-rounding with
@ref{12b8,,round()} function cannot help:

@example
>>> round(0.1, 1) + round(0.1, 1) + round(0.1, 1) == round(0.3, 1)
False
@end example

Though the numbers cannot be made closer to their intended exact values,
the @ref{d9d,,math.isclose()} function can be useful for comparing inexact values:

@example
>>> math.isclose(0.1 + 0.1 + 0.1, 0.3)
True
@end example

Alternatively, the @ref{12b8,,round()} function can be used to compare rough
approximations:

@example
>>> round(math.pi, ndigits=2) == round(22 / 7, ndigits=2)
True
@end example

Binary floating-point arithmetic holds many surprises like this.  The problem
with "0.1" is explained in precise detail below, in the "Representation Error"
section.  See Examples of Floating Point Problems@footnote{https://jvns.ca/blog/2023/01/13/examples-of-floating-point-problems/} for
a pleasant summary of how binary floating point works and the kinds of
problems commonly encountered in practice.  Also see
The Perils of Floating Point@footnote{http://www.indowsway.com/floatingpoint.htm}
for a more complete account of other common surprises.

As that says near the end, "there are no easy answers."  Still, don't be unduly
wary of floating point!  The errors in Python float operations are inherited
from the floating-point hardware, and on most machines are on the order of no
more than 1 part in 2**53 per operation.  That's more than adequate for most
tasks, but you do need to keep in mind that it's not decimal arithmetic and
that every float operation can suffer a new rounding error.

Bien que des cas pathologiques existent, pour la plupart des cas d'utilisations courants vous obtiendrez le résultat attendu à la fin en arrondissant simplement au nombre de décimales désirées à l'affichage avec @ref{435,,str()}. Pour un contrôle fin sur la manière dont les décimales sont affichées, consultez dans @ref{1367,,Syntaxe de formatage de chaîne} les spécifications de formatage de la méthode @ref{60c,,str.format()}.

Pour les cas requérant une représentation décimale exacte, le module @ref{36,,decimal} peut être utile : il implémente l'arithmétique décimale et peut donc être un choix adapté pour des applications nécessitant une grande précision.

Une autre forme d'arithmétique exacte est implémentée dans le module @ref{5c,,fractions} qui se base sur les nombres rationnels (donc 1/3 peut y être représenté exactement).

If you are a heavy user of floating-point operations you should take a look
at the NumPy package and many other packages for mathematical and
statistical operations supplied by the SciPy project. See <@indicateurl{https://scipy.org}>.

Python provides tools that may help on those rare occasions when you really
`do' want to know the exact value of a float.  The
@ref{1c9e,,float.as_integer_ratio()} method expresses the value of a float as a
fraction:

@example
>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)
@end example

Since the ratio is exact, it can be used to losslessly recreate the
original value:

@example
>>> x == 3537115888337719 / 1125899906842624
True
@end example

The @ref{1c9f,,float.hex()} method expresses a float in hexadecimal (base
16), again giving the exact value stored by your computer:

@example
>>> x.hex()
'0x1.921f9f01b866ep+1'
@end example

This precise hexadecimal representation can be used to reconstruct
the float value exactly:

@example
>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True
@end example

Puisque cette représentation est exacte, elle est pratique pour échanger des valeurs entre différentes versions de Python (indépendamment de la machine) ou d'autres langages qui comprennent ce format (tels que Java et C99).

Another helpful tool is the @ref{454,,sum()} function which helps mitigate
loss-of-precision during summation.  It uses extended precision for
intermediate rounding steps as values are added onto a running total.
That can make a difference in overall accuracy so that the errors do not
accumulate to the point where they affect the final total:

@example
>>> 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 == 1.0
False
>>> sum([0.1] * 10) == 1.0
True
@end example

The @ref{138b,,math.fsum()} goes further and tracks all of the "lost digits"
as values are added onto a running total so that the result has only a
single rounding.  This is slower than @ref{454,,sum()} but will be more
accurate in uncommon cases where large magnitude inputs mostly cancel
each other out leaving a final sum near zero:

@example
>>> arr = [-0.10430216751806065, -266310978.67179024, 143401161448607.16,
...        -143401161400469.7, 266262841.31058735, -0.003244936839808227]
>>> float(sum(map(Fraction, arr)))   # Exact summation with single rounding
8.042173697819788e-13
>>> math.fsum(arr)                   # Single rounding
8.042173697819788e-13
>>> sum(arr)                         # Multiple roundings in extended precision
8.042178034628478e-13
>>> total = 0.0
>>> for x in arr:
...     total += x                   # Multiple roundings in standard precision
...
>>> total                            # Straight addition has no correct digits!
-0.0051575902860057365
@end example

@menu
* Erreurs de représentation:: 

@end menu

@node Erreurs de représentation,,,Floating-Point Arithmetic Issues and Limitations
@anchor{tutorial/floatingpoint representation-error}@anchor{1ca0}@anchor{tutorial/floatingpoint tut-fp-error}@anchor{1ca1}
@subsection Erreurs de représentation


Cette section explique en détail l'exemple du « 0.1 » et montre comment vous pouvez effectuer une analyse exacte de ce type de cas par vous-même. Nous supposons que la représentation binaire des nombres flottants vous est familière.

Le terme `Erreur de représentation' (`representation error' en anglais) signifie que la plupart des fractions décimales ne peuvent être représentées exactement en binaire. C'est la principale raison pour laquelle Python (ou Perl, C, C++, Java, Fortran et beaucoup d'autres) n'affiche habituellement pas le résultat exact en décimal.

Why is that?  1/10 is not exactly representable as a binary fraction.  Since at
least 2000, almost all machines use IEEE 754 binary floating-point arithmetic,
and almost all platforms map Python floats to IEEE 754 binary64 "double
precision" values.  IEEE 754 binary64 values contain 53 bits of precision, so
on input the computer strives to convert 0.1 to the closest fraction it can of
the form `J'/2**`N' where `J' is an integer containing exactly 53 bits.
Rewriting

@example
1 / 10 ~= J / (2**N)
@end example

en

@example
J ~= 2**N / 10
@end example

and recalling that `J' has exactly 53 bits (is @code{>= 2**52} but @code{< 2**53}),
the best value for `N' is 56:

@example
>>> 2**52 <=  2**56 // 10  < 2**53
True
@end example

That is, 56 is the only value for `N' that leaves `J' with exactly 53 bits.  The
best possible value for `J' is then that quotient rounded:

@example
>>> q, r = divmod(2**56, 10)
>>> r
6
@end example

Since the remainder is more than half of 10, the best approximation is obtained
by rounding up:

@example
>>> q+1
7205759403792794
@end example

Therefore the best possible approximation to 1/10 in IEEE 754 double precision
is:

@example
7205759403792794 / 2 ** 56
@end example

Diviser le numérateur et le dénominateur par deux réduit la fraction à :

@example
3602879701896397 / 2 ** 55
@end example

Notez que puisque l'arrondi a été fait vers le haut, le résultat est en réalité légèrement plus grand que 1/10 ; si nous n'avions pas arrondi par le haut, le quotient aurait été légèrement plus petit que 1/10. Mais dans aucun cas il ne vaut `exactement' 1/10 !

So the computer never "sees" 1/10:  what it sees is the exact fraction given
above, the best IEEE 754 double approximation it can get:

@example
>>> 0.1 * 2 ** 55
3602879701896397.0
@end example

If we multiply that fraction by 10**55, we can see the value out to
55 decimal digits:

@example
>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625
@end example

meaning that the exact number stored in the computer is equal to
the decimal value 0.1000000000000000055511151231257827021181583404541015625.
Instead of displaying the full decimal value, many languages (including
older versions of Python), round the result to 17 significant digits:

@example
>>> format(0.1, '.17f')
'0.10000000000000001'
@end example

The @ref{5c,,fractions} and @ref{36,,decimal} modules make these calculations
easy:

@example
>>> from decimal import Decimal
>>> from fractions import Fraction

>>> Fraction.from_float(0.1)
Fraction(3602879701896397, 36028797018963968)

>>> (0.1).as_integer_ratio()
(3602879701896397, 36028797018963968)

>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')

>>> format(Decimal.from_float(0.1), '.17')
'0.10000000000000001'
@end example

@node Annexe,,Floating-Point Arithmetic Issues and Limitations,Le tutoriel Python
@anchor{tutorial/appendix doc}@anchor{1ca2}@anchor{tutorial/appendix appendix}@anchor{1ca3}@anchor{tutorial/appendix tut-appendix}@anchor{1ca4}
@section Annexe


@menu
* Mode interactif: Mode interactif<2>. 

@end menu

@node Mode interactif<2>,,,Annexe
@anchor{tutorial/appendix interactive-mode}@anchor{1ca5}@anchor{tutorial/appendix tut-interac}@anchor{16e}
@subsection Mode interactif


There are two variants of the interactive @ref{169,,REPL}.  The classic
basic interpreter is supported on all platforms with minimal line
control capabilities.

On Windows, or Unix-like systems with @ref{2b,,curses} support,
a new interactive shell is used by default.
This one supports color, multiline editing, history browsing, and
paste mode.  To disable color, see @ref{16a,,Controlling color} for
details.  Function keys provide some additional functionality.
@code{F1} enters the interactive help browser @ref{b4,,pydoc}.
@code{F2} allows for browsing command-line history with neither output nor the
@ref{16b,,>>>} and @ref{16c,,...} prompts. @code{F3} enters "paste mode", which
makes pasting larger blocks of code easier. Press @code{F3} to return to
the regular prompt.

When using the new interactive shell, exit the shell by typing @code{exit}
or @code{quit}. Adding call parentheses after those commands is not
required.

If the new interactive shell is not desired, it can be disabled via
the 
@geindex PYTHON_BASIC_REPL
@geindex variable d'environnement; PYTHON_BASIC_REPL
@ref{16d,,PYTHON_BASIC_REPL} environment variable.

@menu
* Gestion des erreurs:: 
* Scripts Python exécutables:: 
* Configuration du mode interactif:: 
* Modules de personnalisation:: 

@end menu

@node Gestion des erreurs,Scripts Python exécutables,,Mode interactif<2>
@anchor{tutorial/appendix error-handling}@anchor{1ca6}@anchor{tutorial/appendix tut-error}@anchor{1ca7}
@subsubsection Gestion des erreurs


When an error occurs, the interpreter prints an error message and a stack trace.
In interactive mode, it then returns to the primary prompt; when input came from
a file, it exits with a nonzero exit status after printing the stack trace.
(Exceptions handled by an @ref{189,,except} clause in a @ref{6d3,,try} statement
are not errors in this context.)  Some errors are unconditionally fatal and
cause an exit with a nonzero exit status; this applies to internal inconsistencies and
some cases of running out of memory.  All error messages are written to the
standard error stream; normal output from executed commands is written to
standard output.

Taper le caractère d'interruption (généralement @code{Ctrl+C} ou @code{Supprimer}) au niveau de l'invite de commande primaire annule l'entrée et revient à l'invite @footnote{
Un problème avec GNU `Readline' peut l'en empêcher.
}. Saisir une interruption tandis qu'une commande s'exécute lève une exception @ref{9bf,,KeyboardInterrupt} qui peut être gérée par une instruction @ref{6d3,,try}.

@node Scripts Python exécutables,Configuration du mode interactif,Gestion des erreurs,Mode interactif<2>
@anchor{tutorial/appendix executable-python-scripts}@anchor{1ca8}@anchor{tutorial/appendix tut-scripts}@anchor{1b7e}
@subsubsection Scripts Python exécutables


Sur les systèmes Unix, un script Python peut être rendu directement exécutable, comme un script `shell', en ajoutant la ligne

@example
#!/usr/bin/env python3
@end example

(en supposant que l'interpréteur est dans le 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} de l'utilisateur) au début du script et en rendant le fichier exécutable. @code{'#!'} doivent être les deux premiers caractères du fichier. Sur certaines plateformes, cette première ligne doit finir avec une fin de ligne de type Unix (@code{'\n'}) et pas de type Windows (@code{'\r\n'}). Notez que le caractère croisillon, @code{'#'}, est utilisé pour initier un commentaire en Python.

Un script peut être rendu exécutable en utilisant la commande @code{chmod}.

@example
$ chmod +x myscript.py
@end example

Sur les systèmes Windows il n'y a pas de "mode exécutable". L'installateur Python associe automatiquement les fichiers en @code{.py} avec @code{python.exe} de telle sorte qu'un double clic sur un fichier Python le lance comme un script. L'extension peut aussi être @code{.pyw}. Dans ce cas, la console n'apparait pas.

@node Configuration du mode interactif,Modules de personnalisation,Scripts Python exécutables,Mode interactif<2>
@anchor{tutorial/appendix the-interactive-startup-file}@anchor{1ca9}@anchor{tutorial/appendix tut-startup}@anchor{1caa}
@subsubsection Configuration du mode interactif


En mode interactif, il peut être pratique de faire exécuter quelques commandes au lancement de l’interpréteur. Configurez la variable d'environnement 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} avec le nom d'un fichier contenant les instructions à exécuter, à la même manière du @code{.profile} pour un `shell' Unix.

Ce fichier n'est lu qu'en mode interactif, pas quand Python lit les instructions depuis un fichier, ni quand @code{/dev/tty} est donné explicitement comme fichier source (pour tout le reste, Python se comporte alors comme dans une session interactive). Les instructions de ce fichier sont exécutées dans le même espace de nommage que vos commandes, donc les objets définis et modules importés peuvent être utilisés directement dans la session interactive. Dans ce fichier, il est aussi possible de changer les invites de commande @code{sys.ps1} et @code{sys.ps2}.

Si vous voulez exécuter d'autres fichiers du dossier courant au démarrage, vous pouvez le programmer dans le fichier de démarrage global, par exemple avec le code suivant : @code{if os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())}. Et si vous voulez exécuter le fichier de démarrage depuis un script, vous devez le faire explicitement dans le script :

@example
import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
    with open(filename) as fobj:
        startup_file = fobj.read()
    exec(startup_file)
@end example

@node Modules de personnalisation,,Configuration du mode interactif,Mode interactif<2>
@anchor{tutorial/appendix the-customization-modules}@anchor{1cab}@anchor{tutorial/appendix tut-customize}@anchor{1cac}
@subsubsection Modules de personnalisation


Python provides two hooks to let you customize it: 
@geindex sitecustomize
sitecustomize and
@geindex usercustomize
usercustomize.  To see how it works, you need first to find the location
of your user site-packages directory.  Start Python and run this code:

@example
>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.x/site-packages'
@end example

Vous pouvez maintenant y créer un fichier @code{usercustomize.py} et y écrire ce que vous voulez. Il est toujours pris en compte par Python, peu importe le mode, sauf lorsque vous démarrez avec l'option @ref{1362,,-s} qui désactive l'importation automatique.

@geindex sitecustomize
sitecustomize works in the same way, but is typically created by an
administrator of the computer in the global site-packages directory, and is
imported before 
@geindex usercustomize
usercustomize.  See the documentation of the @ref{c6,,site}
module for more details.

@subsubheading Notes


@node Installation et utilisation de Python,La référence du langage Python,Le tutoriel Python,Top
@anchor{using/index doc}@anchor{1cad}@anchor{using/index python-setup-and-usage}@anchor{1cae}@anchor{using/index using-index}@anchor{1caf}
@chapter Installation et utilisation de Python


Cette partie de la documentation est consacrée aux informations générales au sujet de l'installation de l'environnement Python sur différentes plateformes, l'invocation de l'interpréteur et des choses qui facilitent le travail avec Python.

@c ATTENTION: You probably should update Misc/python.man, too, if you modify
@c this file.

@menu
* Ligne de commande et environnement:: 
* Utilisation de Python sur les plateformes Unix:: 
* Configurer Python:: 
* Utilisation de Python sur Windows:: 
* Using Python on macOS:: 
* Using Python on Android:: 
* Using Python on iOS:: 
* Éditeurs et IDEs:: 

@end menu

@node Ligne de commande et environnement,Utilisation de Python sur les plateformes Unix,,Installation et utilisation de Python
@anchor{using/cmdline doc}@anchor{1cb0}@anchor{using/cmdline command-line-and-environment}@anchor{1cb1}@anchor{using/cmdline using-on-general}@anchor{194d}
@section Ligne de commande et environnement


L'interpréteur CPython analyse la ligne de commande et l'environnement à la recherche de différents paramètres.

`Particularité de l'implémentation CPython :' Le format des lignes de commande utilisé par d'autres implémentations peut s'avérer différent. Voir @ref{1cb2,,Autres implémentations} pour plus d'informations.

@menu
* Ligne de commande:: 
* Variables d'environnement:: 

@end menu

@node Ligne de commande,Variables d'environnement,,Ligne de commande et environnement
@anchor{using/cmdline command-line}@anchor{1cb3}@anchor{using/cmdline using-on-cmdline}@anchor{ff0}
@subsection Ligne de commande


Quand vous invoquez Python, vous pouvez spécifier n’importe laquelle de ces options :

@example
python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]
@end example

Le cas d'utilisation le plus courant est, bien entendu, la simple invocation d'un script :

@example
python myscript.py
@end example

@menu
* Options de l'interface:: 
* Options génériques:: 
* Options diverses:: 
* Controlling color:: 
* Options à ne pas utiliser:: 

@end menu

@node Options de l'interface,Options génériques,,Ligne de commande
@anchor{using/cmdline interface-options}@anchor{1cb4}@anchor{using/cmdline using-on-interface-options}@anchor{1cb5}
@subsubsection Options de l'interface


L'interface de l’interpréteur ressemble à celle du shell UNIX mais fournit quelques méthodes d'invocation supplémentaires :


@itemize *

@item 
When called with standard input connected to a tty device, it prompts for
commands and executes them until an EOF (an end-of-file character, you can
produce that with @code{Ctrl-D} on UNIX or @code{Ctrl-Z, Enter} on Windows) is read.
For more on interactive mode, see @ref{16e,,Mode interactif}.

@item 
Quand l'interpréteur est appelé avec un argument correspondant à un nom de fichier ou avec un fichier comme entrée standard, il lit et exécute le script contenu dans ce fichier.

@item 
Quand l'interpréteur est appelé avec un argument correspondant à un répertoire, il lit et exécute un script d’un certain nom dans ce répertoire.

@item 
Quand l'interpréteur est appelé avec l'option @code{-c commande}, il exécute la ou les instructions Python données comme `commande'. Ici `commande' peut contenir plusieurs instructions séparées par des fins de ligne. Les blancs en début de ligne ne sont pas ignorés dans les instructions Python !

@item 
Quand l'interpréteur est appelé avec l'option @code{-m nom-de-module}, le module donné est recherché dans le chemin des modules Python et est exécuté en tant que script.
@end itemize

En mode non-interactif, toute l’entrée est analysée avant d’être exécutée.

Une option d'interface termine la liste des options consommées par l'interpréteur ; tous les arguments atterrissent dans @ref{1243,,sys.argv} — notez que le premier élément, à l'indice zéro (@code{sys.argv|0]}), est une chaîne de caractères indiquant la source du programme.

@geindex option de ligne de commande; -c
@anchor{using/cmdline cmdoption-c}@anchor{5ca}
@deffn {Option} @w{-}c <command>

Exécute le code Python dans `command'. `command' peut être une ou plusieurs instructions, séparées par des fins de ligne, dont les espaces en début de ligne sont significatives, comme dans le code d’un module.

Si cette option est donnée, le premier élément de @ref{1243,,sys.argv} est @code{"-c"} et le répertoire courant est ajouté au début de @ref{3ab,,sys.path} (permettant aux modules de ce répertoire d'être importés comme des modules de premier niveau).

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_command} avec comme argument @code{command}.
@end deffn

@geindex option de ligne de commande; -m
@anchor{using/cmdline cmdoption-m}@anchor{5cb}
@deffn {Option} @w{-}m <module@w{-}name>

Parcourt @ref{3ab,,sys.path} à la recherche du module donné et exécute son contenu en tant que module @ref{1,,__main__}.

L'argument étant un nom de `module', vous ne devez pas fournir d’extension de fichier (@code{.py}). Le nom du module doit être un nom de module Python valide, absolu, mais l'implémentation peut ne pas l'imposer (par exemple, l'utilisation d'un trait d'union peut être autorisée).

Les noms de paquets sont aussi autorisés (ainsi que les paquets-espace de nommage, `namespace packages' en anglais). Quand un nom de paquet est donné à la place d'un simple module, l'interpréteur exécute @code{<pkg>.__main__} comme module principal. Ce comportement est délibérément identique au traitement d'un dossier ou d'un fichier zip donné en argument à l'interpréteur comme script.

@cartouche
@quotation Note 
Cette option ne peut pas être utilisée avec les modules natifs et les modules d'extension écrits en C, étant donné qu'ils ne possèdent pas de fichiers modules en Python. Cependant, elle peut toujours être utilisée pour les modules pré-compilés, même si le fichier source original n'est pas disponible.
@end quotation
@end cartouche

Si cette option est donnée, le premier élément de @ref{1243,,sys.argv} est le chemin complet d'accès au fichier du module (pendant que le fichier est recherché, le premier élément est mis à @code{"-m"}). Comme avec l'option @ref{5ca,,-c}, le dossier courant est ajouté au début de @ref{3ab,,sys.path}.

@ref{94b,,-I} option can  be used to run the script in isolated mode where
@ref{3ab,,sys.path} contains neither the current directory nor the user's
site-packages directory. All @code{PYTHON*} environment variables are
ignored, too.

De nombreux modules de la bibliothèque standard contiennent du code qui est invoqué quand ils sont exécutés comme scripts. Un exemple est le module @ref{ee,,timeit} :

@example
python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details
@end example

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_command} avec comme argument @code{module-name}.


@subsubheading Voir aussi



@table @asis

@item @ref{179a,,runpy.run_module()}

Fonctionnalité équivalente directement disponible en code Python
@end table

@geindex Python Enhancement Proposals; PEP 338
PEP 338@footnote{https://peps.python.org/pep-0338/} -- Exécuter des modules en tant que scripts



Modifié dans la version 3.1: Fournir le nom d'un paquet pour exécuter un sous-module @code{__main__}.



Modifié dans la version 3.4: les paquets-espaces de nommage sont aussi gérés

@end deffn

@anchor{using/cmdline cmdarg-dash}@anchor{1cb6}
@deffn {Describe} @w{-}

Lit les commandes depuis l'entrée standard (@ref{527,,sys.stdin}). Si l'entrée standard est un terminal, l'option @ref{1491,,-i} est activée implicitement.

Si cette option est donnée, le premier élément de @ref{1243,,sys.argv} est @code{"-"} et le dossier courant est ajouté au début de @ref{3ab,,sys.path}.

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_stdin} sans argument.
@end deffn

@anchor{using/cmdline cmdarg-script}@anchor{1cb7}
@deffn {Describe} <script>

Exécute le code Python contenu dans `script', qui doit être un chemin d'accès (absolu ou relatif) à un fichier, faisant référence à un fichier Python, à un répertoire contenant un fichier @code{__main__.py} ou à un fichier zip contenant un fichier @code{__main__.py}.

Si cette option est donnée, le premier élément de @ref{1243,,sys.argv} est le nom du script tel que donné sur la ligne de commande.

Si le nom du script se réfère directement à un fichier Python, le répertoire contenant ce fichier est ajouté au début de @ref{3ab,,sys.path} et le fichier est exécuté en tant que module @ref{1,,__main__}.

Si le nom du script fait référence à un dossier ou à un fichier zip, le nom du script est ajouté au début de @ref{3ab,,sys.path} et le fichier @code{__main__.py} à cet endroit est exécuté en tant que module @ref{1,,__main__}.

@ref{94b,,-I} option can  be used to run the script in isolated mode where
@ref{3ab,,sys.path} contains neither the script's directory nor the user's
site-packages directory. All @code{PYTHON*} environment variables are
ignored, too.

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_file} avec comme argument @code{filename}.


@subsubheading Voir aussi



@table @asis

@item @ref{17f,,runpy.run_path()}

Fonctionnalité équivalente directement disponible en code Python
@end table

@end deffn

Si aucune option d'interface n'est donnée, l'option @ref{1491,,-i} est activée implicitement, @code{sys.argv[0]} est une chaine vide (@code{""}) et le dossier courant est ajouté au début de @ref{3ab,,sys.path}. Aussi, la complétion par tabulation et l'édition de l'historique sont automatiquement activés, s'ils sont disponibles sur votre système (voir @ref{fb4,,Readline configuration}).


@subsubheading Voir aussi


@ref{1b73,,Lancement de l'interpréteur}



Modifié dans la version 3.4: Activation automatique de la complétion par tabulation et édition de l'historique.


@node Options génériques,Options diverses,Options de l'interface,Ligne de commande
@anchor{using/cmdline generic-options}@anchor{1cb8}@anchor{using/cmdline using-on-generic-options}@anchor{1cb9}
@subsubsection Options génériques


@geindex option de ligne de commande; -?
@geindex option de ligne de commande; -h
@geindex option de ligne de commande; --help
@anchor{using/cmdline cmdoption-0}@anchor{13de}
@deffn {Option} @w{-}?
@anchor{using/cmdline cmdoption-h}@anchor{1cba}
@deffnx {Option} @w{-}h
@anchor{using/cmdline cmdoption-help}@anchor{5da}
@deffnx {Option} @w{-}@w{-}help

Affiche une brève description de toutes les options de la ligne de commande et des variables d'environnement correspondantes, puis quitte.
@end deffn

@geindex option de ligne de commande; --help-env
@anchor{using/cmdline cmdoption-help-env}@anchor{5dc}
@deffn {Option} @w{-}@w{-}help@w{-}env

Affiche une brève description des variables d'environnement spécifiques à Python et quitte.


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --help-xoptions
@anchor{using/cmdline cmdoption-help-xoptions}@anchor{5dd}
@deffn {Option} @w{-}@w{-}help@w{-}xoptions

Affiche une description spécifique à l'implémentation des options @ref{175,,-X} et quitte.


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --help-all
@anchor{using/cmdline cmdoption-help-all}@anchor{5de}
@deffn {Option} @w{-}@w{-}help@w{-}all

Affiche toutes les informations d'utilisation et quitte.


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; -V
@geindex option de ligne de commande; --version
@anchor{using/cmdline cmdoption-V}@anchor{176}
@deffn {Option} @w{-}V
@anchor{using/cmdline cmdoption-version}@anchor{d09}
@deffnx {Option} @w{-}@w{-}version

Affiche la version de Python et termine. Par exemple :

@example
Python 3.8.0b2+
@end example

Lorsque l'option est doublée, affiche davantage d'informations sur la manière dont Python a été compilé, comme :

@example
Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]
@end example


Ajouté dans la version 3.6: L'option @code{-VV}.

@end deffn

@node Options diverses,Controlling color,Options génériques,Ligne de commande
@anchor{using/cmdline miscellaneous-options}@anchor{1cbb}@anchor{using/cmdline using-on-misc-options}@anchor{ff1}
@subsubsection Options diverses


@geindex option de ligne de commande; -b
@anchor{using/cmdline cmdoption-b}@anchor{5cd}
@deffn {Option} @w{-}b

Issue a warning when converting @ref{1bd,,bytes} or @ref{528,,bytearray} to
@ref{435,,str} without specifying encoding or comparing @code{bytes} or
@code{bytearray} with @code{str} or @code{bytes} with @ref{254,,int}.
Issue an error when the option is given twice (@code{-bb}).


Modifié dans la version 3.5: Affects also comparisons of @ref{1bd,,bytes} with @ref{254,,int}.

@end deffn

@geindex option de ligne de commande; -B
@anchor{using/cmdline cmdoption-B}@anchor{1384}
@deffn {Option} @w{-}B

S'il est donné, Python ne tente pas d'écrire de fichier @code{.pyc} ou @code{.pyo} à l'importation des modules sources. Voir aussi 
@geindex PYTHONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@ref{1385,,PYTHONDONTWRITEBYTECODE}.
@end deffn

@geindex option de ligne de commande; --check-hash-based-pycs
@anchor{using/cmdline cmdoption-check-hash-based-pycs}@anchor{1cbc}
@deffn {Option} @w{-}@w{-}check@w{-}hash@w{-}based@w{-}pycs default|always|never

Contrôle la façon dont sont validés les fichiers @code{.pyc} avec empreinte (voir @ref{5d6,,Invalidation de bytecode mis en cache}). Quand la valeur est @code{default}, les caches de fichiers de code intermédiaire sont validés en fonction de leur sémantique par défaut. Quand la valeur est @code{always}, tous les fichiers @code{.pyc}, qu'ils soient vérifiés ou non, sont validés par rapport à leurs fichiers sources correspondants. Quand la valeur est @code{never}, les fichiers @code{.pyc} ne sont pas validés par rapport à leurs fichiers sources correspondants.

La sémantique des fichiers @code{.pyc} générés en fonction de l'horodatage n'est pas affectée par cette option.
@end deffn

@geindex option de ligne de commande; -d
@anchor{using/cmdline cmdoption-d}@anchor{1cbd}
@deffn {Option} @w{-}d

Turn on parser debugging output (for expert only).
See also the 
@geindex PYTHONDEBUG
@geindex variable d'environnement; PYTHONDEBUG
@ref{1cbe,,PYTHONDEBUG} environment variable.

This option requires a @ref{1f6,,debug build of Python}, otherwise
it's ignored.
@end deffn

@geindex option de ligne de commande; -E
@anchor{using/cmdline cmdoption-E}@anchor{94a}
@deffn {Option} @w{-}E

Ignore all @code{PYTHON*} environment variables, e.g.
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} and 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME}, that might be set.

Voir aussi les options @ref{58e,,-P} et @ref{94b,,-I} (mode isolé).
@end deffn

@geindex option de ligne de commande; -i
@anchor{using/cmdline cmdoption-i}@anchor{1491}
@deffn {Option} @w{-}i

Quand un script est passé comme premier argument ou que l'option @ref{5ca,,-c} est utilisée, entre en mode interactif après avoir exécuté le script ou la commande, même lorsque @ref{527,,sys.stdin} ne semble pas être un terminal. Le fichier 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} n'est pas lu.

Cela peut être utile pour examiner les variables globales ou une trace de la pile lorsque le script lève une exception. Voir aussi 
@geindex PYTHONINSPECT
@geindex variable d'environnement; PYTHONINSPECT
@ref{1490,,PYTHONINSPECT}.
@end deffn

@geindex option de ligne de commande; -I
@anchor{using/cmdline cmdoption-I}@anchor{94b}
@deffn {Option} @w{-}I

Lance Python en mode isolé. Cela implique les options @ref{94a,,-E}, @ref{58e,,-P} et @ref{1362,,-s}.

In isolated mode @ref{3ab,,sys.path} contains neither the script's directory nor
the user's site-packages directory. All @code{PYTHON*} environment
variables are ignored, too. Further restrictions may be imposed to prevent
the user from injecting malicious code.


Ajouté dans la version 3.4.

@end deffn

@geindex option de ligne de commande; -O
@anchor{using/cmdline cmdoption-O}@anchor{da2}
@deffn {Option} @w{-}O

Enlève les instructions `assert' et tout le code qui dépend de la valeur de @ref{7c4,,__debug__}. Ajoute @code{.opt-1} au nom de fichier du code intermédiaire (@ref{185,,bytecode}), avant l'extension @code{.pyc} (voir la 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}). Voir aussi 
@geindex PYTHONOPTIMIZE
@geindex variable d'environnement; PYTHONOPTIMIZE
@ref{1cbf,,PYTHONOPTIMIZE}.


Modifié dans la version 3.5: Modifie les noms de fichiers @code{.pyc} suivant la 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}.

@end deffn

@geindex option de ligne de commande; -OO
@anchor{using/cmdline cmdoption-OO}@anchor{da3}
@deffn {Option} @w{-}OO

Agit comme @ref{da2,,-O} et ignore aussi les `docstrings'. Ajoute @code{.opt-2} au nom de fichier du code intermédiaire (@ref{185,,bytecode}), avant l'extension @code{.pyc} (voir la 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}).


Modifié dans la version 3.5: Modifie les noms de fichiers @code{.pyc} suivant la 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/}.

@end deffn

@geindex option de ligne de commande; -P
@anchor{using/cmdline cmdoption-P}@anchor{58e}
@deffn {Option} @w{-}P

Ne pas ajouter de chemin (qui serait alors prioritaire) potentiellement non sûr à @ref{3ab,,sys.path} :


@itemize *

@item 
@code{python -m module} en ligne de commande : ne pas ajouter le répertoire de travail courant.

@item 
@code{python script.py} en ligne de commande : ne pas ajouter le répertoire du script. Si c'est un lien symbolique, résoudre les liens symboliques.

@item 
@code{python -c code} et @code{python} (REPL) en lignes de commande : ne pas ajouter de chaîne vide, ce qui voudrait dire le répertoire de travail courant.
@end itemize

Voir aussi la variable d'environnement 
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} ainsi que les options @ref{94a,,-E} et @ref{94b,,-I} (mode isolé).


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; -q
@anchor{using/cmdline cmdoption-q}@anchor{1cc0}
@deffn {Option} @w{-}q

N'affiche pas le copyright et la version, même en mode interactif.


Ajouté dans la version 3.2.

@end deffn

@geindex option de ligne de commande; -R
@anchor{using/cmdline cmdoption-R}@anchor{1a25}
@deffn {Option} @w{-}R

Active l'imprévisibilité du hachage. Cette option ne produit un effet que si la variable d'environnement 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} est mise à @code{0}, puisque l'imprévisibilité du hachage est activée par défaut.

On previous versions of Python, this option turns on hash randomization,
so that the @ref{ae9,,__hash__()} values of str and bytes objects
are "salted" with an unpredictable random value.  Although they remain
constant within an individual Python process, they are not predictable
between repeated invocations of Python.

Hash randomization is intended to provide protection against a
denial-of-service caused by carefully chosen inputs that exploit the worst
case performance of a dict construction, `O'(`n'@w{^2}) complexity.  See
@indicateurl{http://ocert.org/advisories/ocert-2011-003.html} for details.

@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} vous permet de définir vous-même la valeur du sel pour l'algorithme de calcul des empreintes.


Ajouté dans la version 3.2.3.



Modifié dans la version 3.7: Cette option n'est plus ignorée.

@end deffn

@geindex option de ligne de commande; -s
@anchor{using/cmdline cmdoption-s}@anchor{1362}
@deffn {Option} @w{-}s

N'ajoute pas le répertoire utilisateur @ref{1cc1,,site-packages} à @ref{3ab,,sys.path}.

See also 
@geindex PYTHONNOUSERSITE
@geindex variable d'environnement; PYTHONNOUSERSITE
@ref{1363,,PYTHONNOUSERSITE}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} -- Répertoire site-packages propre à l'utilisateur

@end deffn

@geindex option de ligne de commande; -S
@anchor{using/cmdline cmdoption-S}@anchor{1186}
@deffn {Option} @w{-}S

Désactive l’importation du module @ref{c6,,site} et les modifications locales de @ref{3ab,,sys.path} qu’il implique. Désactive aussi ces manipulations si @ref{c6,,site} est importé explicitement plus tard (appelez @ref{1cc2,,site.main()} si vous voulez les déclencher).
@end deffn

@geindex option de ligne de commande; -u
@anchor{using/cmdline cmdoption-u}@anchor{1932}
@deffn {Option} @w{-}u

Force les flux de sortie et d'erreur standards à ne pas utiliser de tampon. Cette option n'a pas d'effet sur le flux d'entrée standard.

Voir aussi 
@geindex PYTHONUNBUFFERED
@geindex variable d'environnement; PYTHONUNBUFFERED
@ref{1933,,PYTHONUNBUFFERED}.


Modifié dans la version 3.7: La couche texte des flux de sortie et d'erreur standards n'utilise maintenant plus de tampon.

@end deffn

@geindex option de ligne de commande; -v
@anchor{using/cmdline cmdoption-v}@anchor{13db}
@deffn {Option} @w{-}v

Affiche un message chaque fois qu'un module est initialisé, montrant l'emplacement (nom du fichier ou module natif) à partir duquel il est chargé. Lorsque l'option est doublée (@code{-vv}), affiche un message pour chaque fichier vérifié lors de la recherche du module. Fournit aussi des informations sur le nettoyage des modules à la fin.


Modifié dans la version 3.10: Le module @ref{c6,,site} affiche les emplacements de recherche de modules spécifiques à l'installation ainsi que les fichiers @code{.pth} qui sont lus.


Voir aussi 
@geindex PYTHONVERBOSE
@geindex variable d'environnement; PYTHONVERBOSE
@ref{1cc3,,PYTHONVERBOSE}.
@end deffn

@geindex option de ligne de commande; -W
@anchor{using/cmdline using-on-warnings}@anchor{1cc4}@anchor{using/cmdline cmdoption-W}@anchor{8b4}
@deffn {Option} @w{-}W arg

Contrôle des avertissements. Le mécanisme d'avertissement de Python, par défaut, affiche les messages d'avertissement sur @ref{926,,sys.stderr}.

Les configurations les plus simples forcent l'application de l'action à tous les avertissements émis par un processus (même ceux qui auraient été ignorés par défaut) :

@example
-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn
@end example

Les noms des actions peuvent être abrégés à votre convenance, l'interpréteur fait la résolution vers le nom adéquat. Par exemple, @code{-Wi} équivaut à @code{-Wignore}.

La forme développée de l'argument de @code{-W} est :

@example
action:message:category:module:lineno
@end example

Les champs `message', `category', `module', `line' appliquent des filtres de sélection. Ils sont facultatifs : on peut les laisser vides, ou en omettre certains à la fin. Par exemple, @code{-W ignore::DeprecationWarning} permet d'ignorer tous les avertissements de type @code{DeprecationWarning}.

Le champ `action' déjà décrit s'applique donc uniquement aux avertissements qui sont passés à travers les filtres.

Un filtre `message' restreint l'action aux avertissements dont le texte complet correspond à `message' (la comparaison ne prend pas en compte la casse).

Un filtre `category' restreint l'action aux avertissements dont la classe est celle nommée `category', ou bien une classe fille de la classe nommée `category'. Un exemple pour `category' est @code{DeprecationWarning}.

The `module' field matches the (fully qualified) module name; this match is
case-sensitive.

Enfin, un filtre `lineno' restreint l'action aux avertissements qui proviennent d'un numéro de ligne donné. La valeur zéro revient à appliquer le filtre sur toutes les lignes, c.-à-d. l'équivalent de ne pas mettre de numéro.

L'option @ref{8b4,,-W} peut être répétée ; lorsqu'un avertissement correspond à plus d'une option, l'action associée à la dernière correspondance est effectuée. Les options @ref{8b4,,-W} invalides sont ignorées (cependant, un message d'avertissement est affiché sur les options invalides au moment où le premier avertissement est généré).

Les avertissements peuvent aussi être contrôlés en utilisant la variable d'environnement 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS} et depuis un programme Python en utilisant le module @ref{111,,warnings}. Par exemple, la fonction @ref{145d,,warnings.filterwarnings()} peut être utilisée pour filtrer les messages d'avertissement en utilisant une expression rationnelle.

Voir  @ref{8b6,,Le filtre des avertissements} et @ref{1cc5,,Rédaction de filtres d'avertissement} pour plus de détails.
@end deffn

@geindex option de ligne de commande; -x
@anchor{using/cmdline cmdoption-x}@anchor{1cc6}
@deffn {Option} @w{-}x

Saute la première ligne du code source, autorisant ainsi les directives de type @code{#!cmd} non conformes au standard Unix. L'objectif est de proposer une astuce spécifique pour le DOS.
@end deffn

@geindex option de ligne de commande; -X
@anchor{using/cmdline cmdoption-X}@anchor{175}
@deffn {Option} @w{-}X

Réservée pour les options spécifiques aux différentes implémentations. CPython reconnaît actuellement les valeurs suivantes :


@itemize *

@item 
@code{-X faulthandler} to enable @ref{57,,faulthandler}.
See also 
@geindex PYTHONFAULTHANDLER
@geindex variable d'environnement; PYTHONFAULTHANDLER
@ref{1069,,PYTHONFAULTHANDLER}.


Ajouté dans la version 3.3.


@item 
@code{-X showrefcount} pour afficher le compteur des références et le nombre de blocs mémoire utilisés lorsque le programme se termine ou après chaque entrée de l'interpréteur interactif. Ceci ne fonctionne que sur les versions @ref{1f6,,compilées en mode débogage}.


Ajouté dans la version 3.4.


@item 
@code{-X tracemalloc} to start tracing Python memory allocations using the
@ref{fe,,tracemalloc} module. By default, only the most recent frame is
stored in a traceback of a trace. Use @code{-X tracemalloc=NFRAME} to start
tracing with a traceback limit of `NFRAME' frames.
See @ref{1cc7,,tracemalloc.start()} and 
@geindex PYTHONTRACEMALLOC
@geindex variable d'environnement; PYTHONTRACEMALLOC
@ref{1cc8,,PYTHONTRACEMALLOC}
for more information.


Ajouté dans la version 3.4.


@item 
@code{-X int_max_str_digits} configure la @ref{5df,,limitation de la longueur de conversion des chaînes entières}.  Voir aussi 
@geindex PYTHONINTMAXSTRDIGITS
@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@ref{174b,,PYTHONINTMAXSTRDIGITS}.


Ajouté dans la version 3.11.


@item 
@code{-X importtime} affiche le temps mis pour chaque importation. Le temps total par module est affiché  (y compris le temps pris par les importations imbriquées) ainsi que le temps propre du module (c.-à-d. sans les importations imbriquées). Notez que l'affichage peut être perturbé dans une application avec de multiples fils d'exécution. L'utilisation classique est @code{python3 -X importtime -c 'import asyncio'}. Voir aussi 
@geindex PYTHONPROFILEIMPORTTIME
@geindex variable d'environnement; PYTHONPROFILEIMPORTTIME
@ref{ae3,,PYTHONPROFILEIMPORTTIME}.


Ajouté dans la version 3.7.


@item 
@code{-X dev}: enable @ref{1f5,,Python Development Mode}, introducing
additional runtime checks that are too expensive to be enabled by
default.  See also 
@geindex PYTHONDEVMODE
@geindex variable d'environnement; PYTHONDEVMODE
@ref{adb,,PYTHONDEVMODE}.


Ajouté dans la version 3.7.


@item 
@code{-X utf8} enables the @ref{641,,Python UTF-8 Mode}.
@code{-X utf8=0} explicitly disables @ref{641,,Python UTF-8 Mode}
(even when it would otherwise activate automatically).
See also 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8}.


Ajouté dans la version 3.7.


@item 
@code{-X pycache_prefix=PATH} place l'arborescence des fichiers @code{.pyc} à partir du chemin donné au lieu de l'arborescence du code source. Voir aussi 
@geindex PYTHONPYCACHEPREFIX
@geindex variable d'environnement; PYTHONPYCACHEPREFIX
@ref{991,,PYTHONPYCACHEPREFIX}.


Ajouté dans la version 3.8.


@item 
@code{-X warn_default_encoding} pour émettre un @ref{1cc9,,EncodingWarning} lorsqu'un fichier est ouvert avec l'encodage par défaut des paramètres régionaux. Voir aussi 
@geindex PYTHONWARNDEFAULTENCODING
@geindex variable d'environnement; PYTHONWARNDEFAULTENCODING
@ref{7a6,,PYTHONWARNDEFAULTENCODING}.


Ajouté dans la version 3.10.


@item 
@code{-X no_debug_ranges} désactive l'inclusion des tableaux qui font la correspondance avec des informations extérieures (ligne de fin, numéros des colonnes de début et de fin) pour toutes les instructions du code. C'est utile quand vous souhaitez diminuer la taille du code objet et des fichiers pyc ou alors quand vous voulez supprimer des informations de position quand l'interpréteur affiche les traces d'appels. Regardez aussi 
@geindex PYTHONNODEBUGRANGES
@geindex variable d'environnement; PYTHONNODEBUGRANGES
@ref{5a0,,PYTHONNODEBUGRANGES}.


Ajouté dans la version 3.11.


@item 
@code{-X frozen_modules} determines whether or not frozen modules are
ignored by the import machinery.  A value of @code{on} means they get
imported and @code{off} means they are ignored.  The default is @code{on}
if this is an installed Python (the normal case).  If it's under
development (running from the source tree) then the default is @code{off}.
Note that the @code{importlib_bootstrap} and
@code{importlib_bootstrap_external} frozen modules are always used, even
if this flag is set to @code{off}. See also 
@geindex PYTHON_FROZEN_MODULES
@geindex variable d'environnement; PYTHON_FROZEN_MODULES
@ref{18c,,PYTHON_FROZEN_MODULES}.


Ajouté dans la version 3.11.


@item 
@code{-X perf} enables support for the Linux @code{perf} profiler.
When this option is provided, the @code{perf} profiler will be able to
report Python calls. This option is only available on some platforms and
will do nothing if is not supported on the current system. The default value
is "off". See also 
@geindex PYTHONPERFSUPPORT
@geindex variable d'environnement; PYTHONPERFSUPPORT
@ref{458,,PYTHONPERFSUPPORT} and @ref{18d,,Python support for the Linux perf profiler}.


Ajouté dans la version 3.12.


@item 
@code{-X perf_jit} enables support for the Linux @code{perf} profiler with DWARF
support. When this option is provided, the @code{perf} profiler will be able
to report Python calls using DWARF information. This option is only available on
some platforms and will do nothing if is not supported on the current
system. The default value is "off". See also 
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex variable d'environnement; PYTHON_PERF_JIT_SUPPORT
@ref{18e,,PYTHON_PERF_JIT_SUPPORT}
and @ref{18d,,Python support for the Linux perf profiler}.


Ajouté dans la version 3.13.


@item 
@code{-X cpu_count=@var{n}} overrides @ref{1c0,,os.cpu_count()},
@ref{1bf,,os.process_cpu_count()}, and @ref{f5a,,multiprocessing.cpu_count()}.
`n' must be greater than or equal to 1.
This option may be useful for users who need to limit CPU resources of a
container system. See also 
@geindex PYTHON_CPU_COUNT
@geindex variable d'environnement; PYTHON_CPU_COUNT
@ref{20d,,PYTHON_CPU_COUNT}.
If `n' is @code{default}, nothing is overridden.


Ajouté dans la version 3.13.


@item 
@code{-X presite=@var{package.module}} specifies a module that should be
imported before the @ref{c6,,site} module is executed and before the
@ref{1,,__main__} module exists.  Therefore, the imported module isn't
@ref{1,,__main__}. This can be used to execute code early during Python
initialization. Python needs to be @ref{1f6,,built in debug mode}
for this option to exist.  See also 
@geindex PYTHON_PRESITE
@geindex variable d'environnement; PYTHON_PRESITE
@ref{1cca,,PYTHON_PRESITE}.


Ajouté dans la version 3.13.


@item 
@code{-X gil=@var{0,1}} forces the GIL to be disabled or enabled,
respectively. Setting to @code{0} is only available in builds configured with
@ref{173,,--disable-gil}. See also 
@geindex PYTHON_GIL
@geindex variable d'environnement; PYTHON_GIL
@ref{174,,PYTHON_GIL} and
@ref{13e,,Free-threaded CPython}.


Ajouté dans la version 3.13.

@end itemize

Il est aussi possible de passer des valeurs arbitraires et de les récupérer par le dictionnaire @ref{1ccb,,sys._xoptions}.


Ajouté dans la version 3.2.



Modifié dans la version 3.9: Removed the @code{-X showalloccount} option.



Modifié dans la version 3.10: Removed the @code{-X oldparser} option.

@end deffn

@node Controlling color,Options à ne pas utiliser,Options diverses,Ligne de commande
@anchor{using/cmdline controlling-color}@anchor{1ccc}@anchor{using/cmdline using-on-controlling-color}@anchor{16a}
@subsubsection Controlling color


The Python interpreter is configured by default to use colors to highlight
output in certain situations such as when displaying tracebacks. This
behavior can be controlled by setting different environment variables.

Setting the environment variable @code{TERM} to @code{dumb} will disable color.

If the FORCE_COLOR@footnote{https://force-color.org/} environment variable is set, then color will be
enabled regardless of the value of TERM. This is useful on CI systems which
aren’t terminals but can still display ANSI escape sequences.

If the NO_COLOR@footnote{https://no-color.org/} environment variable is set, Python will disable all color
in the output. This takes precedence over @code{FORCE_COLOR}.

All these environment variables are used also by other tools to control color
output. To control the color output only in the Python interpreter, the
@geindex PYTHON_COLORS
@geindex variable d'environnement; PYTHON_COLORS
@ref{149,,PYTHON_COLORS} environment variable can be used. This variable takes
precedence over @code{NO_COLOR}, which in turn takes precedence over
@code{FORCE_COLOR}.

@c Apparently this how you hack together a formatted link:

@node Options à ne pas utiliser,,Controlling color,Ligne de commande
@anchor{using/cmdline no-color}@anchor{1ccd}@anchor{using/cmdline options-you-shouldn-t-use}@anchor{1cce}
@subsubsection Options à ne pas utiliser


@geindex option de ligne de commande; -J
@anchor{using/cmdline cmdoption-J}@anchor{1383}
@deffn {Option} @w{-}J

Utilisation réservée à Jython@footnote{https://www.jython.org/}.
@end deffn

@node Variables d'environnement,,Ligne de commande,Ligne de commande et environnement
@anchor{using/cmdline environment-variables}@anchor{1ccf}@anchor{using/cmdline using-on-envvars}@anchor{5db}
@subsection Variables d'environnement


Les variables d'environnement suivantes modifient le comportement de Python. Elles sont analysées avant les options de la ligne de commande, autres que `-E' ou `-I'. Il est d'usage que les options de la ligne de commande prennent le pas sur les variables d'environnement en cas de conflit.

@geindex variable d'environnement; PYTHONHOME
@anchor{using/cmdline envvar-PYTHONHOME}@anchor{3b3}
@deffn {Variable d'environnement} PYTHONHOME

Modifie l'emplacement des bibliothèques standards de Python. Par défaut, les bibliothèques sont recherchées dans @code{`préfixe'/lib/python`version'} et @code{`préfixe_exec'/lib/python`version'} où @code{`préfixe'} et @code{`préfixe_exec'} sont des répertoires qui dépendent de l'installation (leur valeur par défaut étant @code{/usr/local}).

Quand 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} est défini à un simple répertoire, sa valeur remplace à la fois @code{`préfixe'} et @code{`préfixe_exec'}. Pour spécifier des valeurs différentes à ces variables, définissez 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} à @code{`préfixe':`préfixe_exec'}.
@end deffn

@geindex variable d'environnement; PYTHONPATH
@anchor{using/cmdline envvar-PYTHONPATH}@anchor{1006}
@deffn {Variable d'environnement} PYTHONPATH

Augmente le chemin de recherche par défaut des fichiers de modules. Le format est le même que pour 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} du shell : un ou plusieurs chemins de répertoires séparés par @ref{1cd0,,os.pathsep}  (par exemple, le caractère deux-points sous Unix et point-virgule sous Windows). Les répertoires qui n'existent pas sont ignorés silencieusement.

En plus des répertoires normaux, des entrées individuelles de 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} peuvent faire référence à des fichiers zip contenant des modules en pur Python (soit sous forme de code source, soit sous forme compilée). Les modules d'extensions ne peuvent pas être importés à partir de fichiers zip.

Le chemin de recherche par défaut dépend de l'installation mais commence généralement par @code{`préfixe'/lib/python`version'} (voir 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} ci-dessus). Il est `toujours' ajouté à  
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH}.

Comme indiqué ci-dessus dans @ref{1cb5,,Options de l'interface}, un répertoire supplémentaire est inséré dans le chemin de recherche devant 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH}. Le chemin de recherche peut être manipulé depuis un programme Python avec la variable @ref{3ab,,sys.path}.
@end deffn

@geindex variable d'environnement; PYTHONSAFEPATH
@anchor{using/cmdline envvar-PYTHONSAFEPATH}@anchor{58f}
@deffn {Variable d'environnement} PYTHONSAFEPATH

Si elle est définie à une chaîne non vide, ne pas ajouter un chemin potentiellement non sûr à @ref{3ab,,sys.path} : voir l'option @ref{58e,,-P} pour les détails.


Ajouté dans la version 3.11.

@end deffn

@geindex variable d'environnement; PYTHONPLATLIBDIR
@anchor{using/cmdline envvar-PYTHONPLATLIBDIR}@anchor{18cd}
@deffn {Variable d'environnement} PYTHONPLATLIBDIR

Si elle est définie à une chaîne non vide, elle remplace la valeur de @ref{925,,sys.platlibdir}.


Ajouté dans la version 3.9.

@end deffn

@geindex variable d'environnement; PYTHONSTARTUP
@anchor{using/cmdline envvar-PYTHONSTARTUP}@anchor{fb3}
@deffn {Variable d'environnement} PYTHONSTARTUP

S'il s'agit d'un nom de fichier accessible en lecture, les commandes Python de ce fichier sont exécutées avant que la première invite ne soit affichée en mode interactif. Le fichier est exécuté dans le même espace de nommage que les commandes interactives, de manière à ce que les objets définis ou importés puissent être utilisés sans qualificatif dans la session interactive. Vous pouvez aussi changer les invites @ref{1cd1,,sys.ps1} et @ref{1cd2,,sys.ps2} ainsi que le point d'entrée (`hook' en anglais) @ref{fb2,,sys.__interactivehook__} dans ce fichier.

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_startup} avec le nom du fichier en argument lorsqu'il est lancé au démarrage.
@end deffn

@geindex variable d'environnement; PYTHONOPTIMIZE
@anchor{using/cmdline envvar-PYTHONOPTIMIZE}@anchor{1cbf}
@deffn {Variable d'environnement} PYTHONOPTIMIZE

Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option @ref{da2,,-O}. Si elle est définie à un entier, c'est équivalent à spécifier l'option @ref{da2,,-O} plusieurs fois.
@end deffn

@geindex variable d'environnement; PYTHONBREAKPOINT
@anchor{using/cmdline envvar-PYTHONBREAKPOINT}@anchor{ac9}
@deffn {Variable d'environnement} PYTHONBREAKPOINT

Si elle est définie, elle fait référence à un appelable en utilisant la notation des chemins délimités par des points. Le module contenant l'appelable est importé et l'appelable est alors lancé par l'implémentation par défaut de @ref{ac8,,sys.breakpointhook()}, elle-même étant appelée par la fonction native @ref{231,,breakpoint()}. Si elle n'est pas définie ou définie par une chaîne vide, elle vaut la même chose que @code{pdb.set_trace}. La définir à la chaîne "0" entraine que l'implémentation par défaut de @ref{ac8,,sys.breakpointhook()} ne fait rien et s'interrompt immédiatement.


Ajouté dans la version 3.7.

@end deffn

@geindex variable d'environnement; PYTHONDEBUG
@anchor{using/cmdline envvar-PYTHONDEBUG}@anchor{1cbe}
@deffn {Variable d'environnement} PYTHONDEBUG

Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option @ref{1cbd,,-d}. Si elle est définie à un entier, c'est équivalent à spécifier l'option @ref{1cbd,,-d} plusieurs fois.

This environment variable requires a @ref{1f6,,debug build of Python}, otherwise it's ignored.
@end deffn

@geindex variable d'environnement; PYTHONINSPECT
@anchor{using/cmdline envvar-PYTHONINSPECT}@anchor{1490}
@deffn {Variable d'environnement} PYTHONINSPECT

Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option @ref{1491,,-i}.

Cette variable peut aussi être modifiée par du code Python en utilisant @ref{1197,,os.environ} pour forcer le mode introspectif à la fin du programme.

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_stdin} sans argument.


Modifié dans la version 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20)
Emits audit events.



Modifié dans la version 3.13: Uses PyREPL if possible, in which case 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} is
also executed. Emits audit events.

@end deffn

@geindex variable d'environnement; PYTHONUNBUFFERED
@anchor{using/cmdline envvar-PYTHONUNBUFFERED}@anchor{1933}
@deffn {Variable d'environnement} PYTHONUNBUFFERED

Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option @ref{1932,,-u}.
@end deffn

@geindex variable d'environnement; PYTHONVERBOSE
@anchor{using/cmdline envvar-PYTHONVERBOSE}@anchor{1cc3}
@deffn {Variable d'environnement} PYTHONVERBOSE

Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option @ref{13db,,-v}. Si elle est définie à un entier, c'est équivalent à spécifier l'option @ref{13db,,-v} plusieurs fois.
@end deffn

@geindex variable d'environnement; PYTHONCASEOK
@anchor{using/cmdline envvar-PYTHONCASEOK}@anchor{949}
@deffn {Variable d'environnement} PYTHONCASEOK

Si elle est définie, Python ignore la casse dans les instructions @ref{5cc,,import}. Ceci ne fonctionne que sous Windows et macOS.
@end deffn

@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@anchor{using/cmdline envvar-PYTHONDONTWRITEBYTECODE}@anchor{1385}
@deffn {Variable d'environnement} PYTHONDONTWRITEBYTECODE

Si elle est définie et n'est pas une chaîne vide, Python n'écrit pas de fichier @code{.pyc} à l'importation des modules sources. C'est équivalent à spécifier l'option @ref{1384,,-B}.
@end deffn

@geindex variable d'environnement; PYTHONPYCACHEPREFIX
@anchor{using/cmdline envvar-PYTHONPYCACHEPREFIX}@anchor{991}
@deffn {Variable d'environnement} PYTHONPYCACHEPREFIX

Si elle est définie, Python n'écrit pas ses fichiers @code{.pyc} dans @code{__pycache__} mais dans une arborescence miroir à ce chemin. C'est l'équivalent de l'option @ref{175,,-X} @code{pycache_prefix=PATH}.


Ajouté dans la version 3.8.

@end deffn

@geindex variable d'environnement; PYTHONHASHSEED
@anchor{using/cmdline envvar-PYTHONHASHSEED}@anchor{1066}
@deffn {Variable d'environnement} PYTHONHASHSEED

Si cette variable n'est pas définie ou définie à @code{random}, une valeur aléatoire est utilisée pour saler les empreintes des objets @code{str} et @code{bytes}.

Si 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} est définie à une valeur entière, elle est utilisée comme valeur de salage pour générer les empreintes des types utilisant l'imprévisibilité du hachage.

L'objectif est d'avoir des empreintes reproductibles, pour des tests de l'interpréteur lui-même ou pour qu'un groupe de processus Python puisse partager des empreintes.

Le nombre entier doit être écrit en base 10 et être compris entre 0 et 4 294 967 295. Spécifier la valeur 0 désactive l'imprévisibilité des empreintes.


Ajouté dans la version 3.2.3.

@end deffn

@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@anchor{using/cmdline envvar-PYTHONINTMAXSTRDIGITS}@anchor{174b}
@deffn {Variable d'environnement} PYTHONINTMAXSTRDIGITS

Si un entier est assigné à cette variable, elle est utilisée pour configurer la limite globale de l'interpréteur @ref{5df,,limitation de la longueur de conversion des chaînes de caractères entiers}.


Ajouté dans la version 3.11.

@end deffn

@geindex variable d'environnement; PYTHONIOENCODING
@anchor{using/cmdline envvar-PYTHONIOENCODING}@anchor{ff3}
@deffn {Variable d'environnement} PYTHONIOENCODING

Si la variable est définie sous la forme @code{nom_encodage:gestionnaire_erreur} avant le lancement de l'interpréteur, cela prend le pas sur l'encodage utilisé pour l'entrée standard, la sortie standard ou la sortie d'erreur.  @code{nom_encodage} et @code{:gestionnaire_erreur} sont facultatifs tous les deux et possèdent la même signification que dans @ref{8c2,,str.encode()}.

Pour la sortie d'erreur, la partie @code{:gestionnaire_erreur} est ignorée : le gestionnaire est toujours @code{'backslashreplace'}.


Modifié dans la version 3.4: La partie @code{nom_encodage} est maintenant optionnelle.



Modifié dans la version 3.6: Sous Windows, l'encodage spécifié par cette variable est ignoré pour le tampon des consoles interactives à moins que 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex variable d'environnement; PYTHONLEGACYWINDOWSSTDIO
@ref{c49,,PYTHONLEGACYWINDOWSSTDIO} ne soit aussi spécifié. Les fichiers et tubes (`pipes' en anglais) redirigés vers les flux standards ne sont pas concernés.

@end deffn

@geindex variable d'environnement; PYTHONNOUSERSITE
@anchor{using/cmdline envvar-PYTHONNOUSERSITE}@anchor{1363}
@deffn {Variable d'environnement} PYTHONNOUSERSITE

Si elle est définie, Python n'ajoute pas le répertoire @ref{1cc1,,site-packages propre à l'utilisateur} à @ref{3ab,,sys.path}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} -- Répertoire site-packages propre à l'utilisateur

@end deffn

@geindex variable d'environnement; PYTHONUSERBASE
@anchor{using/cmdline envvar-PYTHONUSERBASE}@anchor{1361}
@deffn {Variable d'environnement} PYTHONUSERBASE

Defines the @ref{12fa,,user base directory}, which is used to
compute the path of the @ref{1cc1,,user site-packages directory}
and @ref{1cd3,,installation paths} for
@code{python -m pip install --user}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} -- Répertoire site-packages propre à l'utilisateur

@end deffn

@geindex variable d'environnement; PYTHONEXECUTABLE
@anchor{using/cmdline envvar-PYTHONEXECUTABLE}@anchor{1cd4}
@deffn {Variable d'environnement} PYTHONEXECUTABLE

Si cette variable d'environnement est définie, @code{sys.argv[0]} est définie à cette valeur au lieu de la valeur fournie par l'exécutable. Ne fonctionne que sur macOS.
@end deffn

@geindex variable d'environnement; PYTHONWARNINGS
@anchor{using/cmdline envvar-PYTHONWARNINGS}@anchor{b98}
@deffn {Variable d'environnement} PYTHONWARNINGS

C'est équivalent à spécifier l'option @ref{8b4,,-W}. Si la valeur est une chaîne séparée par des virgules, c'est équivalent à spécifier l'option @ref{8b4,,-W} plusieurs fois. Dans ce cas, les filtres spécifiés en derniers prennent le pas sur ceux qui les précèdent dans la liste.

Les configurations les plus simples forcent l'application de l'action à tous les avertissements émis par un processus (même ceux qui auraient été ignorés par défaut) :

@example
PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=all      # Same as PYTHONWARNINGS=always
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn
@end example

Voir  @ref{8b6,,Le filtre des avertissements} et @ref{1cc5,,Rédaction de filtres d'avertissement} pour plus de détails.
@end deffn

@geindex variable d'environnement; PYTHONFAULTHANDLER
@anchor{using/cmdline envvar-PYTHONFAULTHANDLER}@anchor{1069}
@deffn {Variable d'environnement} PYTHONFAULTHANDLER

If this environment variable is set to a non-empty string,
@ref{c8c,,faulthandler.enable()} is called at startup: install a handler for
@ref{1cd5,,SIGSEGV}, @ref{1cd6,,SIGFPE},
@ref{1cd7,,SIGABRT}, @ref{1cd8,,SIGBUS} and
@ref{1cd9,,SIGILL} signals to dump the Python traceback.
This is equivalent to @ref{175,,-X} @code{faulthandler} option.


Ajouté dans la version 3.3.

@end deffn

@geindex variable d'environnement; PYTHONTRACEMALLOC
@anchor{using/cmdline envvar-PYTHONTRACEMALLOC}@anchor{1cc8}
@deffn {Variable d'environnement} PYTHONTRACEMALLOC

If this environment variable is set to a non-empty string, start tracing
Python memory allocations using the @ref{fe,,tracemalloc} module. The value of
the variable is the maximum number of frames stored in a traceback of a
trace. For example, @code{PYTHONTRACEMALLOC=1} stores only the most recent
frame.
See the @ref{1cc7,,tracemalloc.start()} function for more information.
This is equivalent to setting the @ref{175,,-X} @code{tracemalloc} option.


Ajouté dans la version 3.4.

@end deffn

@geindex variable d'environnement; PYTHONPROFILEIMPORTTIME
@anchor{using/cmdline envvar-PYTHONPROFILEIMPORTTIME}@anchor{ae3}
@deffn {Variable d'environnement} PYTHONPROFILEIMPORTTIME

If this environment variable is set to a non-empty string, Python will
show how long each import takes.
This is equivalent to setting the @ref{175,,-X} @code{importtime} option.


Ajouté dans la version 3.7.

@end deffn

@geindex variable d'environnement; PYTHONASYNCIODEBUG
@anchor{using/cmdline envvar-PYTHONASYNCIODEBUG}@anchor{1cda}
@deffn {Variable d'environnement} PYTHONASYNCIODEBUG

Si elle est définie à une chaîne non vide, active le @ref{1cdb,,mode debogage} du module @ref{a,,asyncio}.


Ajouté dans la version 3.4.

@end deffn

@geindex variable d'environnement; PYTHONMALLOC
@anchor{using/cmdline envvar-PYTHONMALLOC}@anchor{c52}
@deffn {Variable d'environnement} PYTHONMALLOC

Définit l'allocateur mémoire de Python ou installe des points d'entrée (`hooks' en anglais) de débogage.

Définit la famille d'allocateurs mémoire utilisés par Python :


@itemize *

@item 
@code{default}: utilise les @ref{1cdc,,allocateurs de mémoire par défaut}.

@item 
@code{malloc}: use the @code{malloc()} function of the C library
for all domains (@ref{1cdd,,PYMEM_DOMAIN_RAW}, @ref{c57,,PYMEM_DOMAIN_MEM},
@ref{c55,,PYMEM_DOMAIN_OBJ}).

@item 
@code{pymalloc}: use the @ref{cfd,,pymalloc allocator} for
@ref{c57,,PYMEM_DOMAIN_MEM} and @ref{c55,,PYMEM_DOMAIN_OBJ} domains and use
the @code{malloc()} function for the @ref{1cdd,,PYMEM_DOMAIN_RAW} domain.

@item 
@code{mimalloc}: use the @ref{1cde,,mimalloc allocator} for
@ref{c57,,PYMEM_DOMAIN_MEM} and @ref{c55,,PYMEM_DOMAIN_OBJ} domains and use
the @code{malloc()} function for the @ref{1cdd,,PYMEM_DOMAIN_RAW} domain.
@end itemize

Chacun de ces modes possède un pendant qui ajoute en plus des @ref{1cdf,,points d'entrée de débogage} :


@itemize *

@item 
@code{debug} : installe des points d'entrée de débogage au-dessus des @ref{1cdc,,allocateurs de mémoire par défaut}.

@item 
@code{malloc_debug}: identique à @code{malloc} mais installe aussi des points d'entrée de débogage.

@item 
@code{pymalloc_debug} pour @code{pymalloc}.

@item 
@code{mimalloc_debug}: same as @code{mimalloc} but also install debug hooks.
@end itemize


Ajouté dans la version 3.6.



Modifié dans la version 3.7: L'allocateur @code{default} a été ajouté.

@end deffn

@geindex variable d'environnement; PYTHONMALLOCSTATS
@anchor{using/cmdline envvar-PYTHONMALLOCSTATS}@anchor{1ae4}
@deffn {Variable d'environnement} PYTHONMALLOCSTATS

Si elle est définie à une chaîne non vide, Python affiche des statistiques relatives à l’@ref{cfd,,allocateur mémoire pymalloc} chaque fois qu'un objet est créé par ce gestionnaire, ainsi qu'à la fin de l'exécution du programme.

Cette variable est ignorée si la variable d'environnement 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} est utilisée pour forcer l'allocateur @code{malloc()} de la bibliothèque C standard ou si Python est configuré sans le support de @code{pymalloc}.


Modifié dans la version 3.6: Cette variable peut maintenant être utilisée avec Python compilé en mode `release'. Elle n'a pas d'effet si elle est définie à une chaine vide.

@end deffn

@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@anchor{using/cmdline envvar-PYTHONLEGACYWINDOWSFSENCODING}@anchor{2ac}
@deffn {Variable d'environnement} PYTHONLEGACYWINDOWSFSENCODING

Si elle est définie et n’est pas une chaîne vide, @ref{525,,l'encodage utilisé pour interagir avec le système de fichiers et le gestionnaire d'erreurs associé} reviennent à leurs valeurs par défaut pré-3.6, respectivement @code{'mbcs'} et @code{'replace'}. Sinon, elles prennent les nouvelles valeurs par défaut @code{"UTF-8"} et @code{"surrogatepass"}.

This may also be enabled at runtime with
@ref{2ab,,sys._enablelegacywindowsfsencoding()}.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.6: Voir la 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} pour plus d'informations.

@end deffn

@geindex variable d'environnement; PYTHONLEGACYWINDOWSSTDIO
@anchor{using/cmdline envvar-PYTHONLEGACYWINDOWSSTDIO}@anchor{c49}
@deffn {Variable d'environnement} PYTHONLEGACYWINDOWSSTDIO

Si elle est définie et n’est pas une chaîne vide, n'utilise pas les lecteur et écrivain de la nouvelle console. Cela signifie que les caractères Unicode sont encodés avec l'encodage de la console active plutôt qu'en UTF-8.

Cette variable est ignorée si les flux standards sont redirigés (vers des fichiers ou des tubes) plutôt que pointant vers des mémoires tampons de console.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.6.

@end deffn

@geindex variable d'environnement; PYTHONCOERCECLOCALE
@anchor{using/cmdline envvar-PYTHONCOERCECLOCALE}@anchor{ac3}
@deffn {Variable d'environnement} PYTHONCOERCECLOCALE

Si elle est définie à la valeur @code{0}, l'application en ligne de commande principale Python ne prend pas en compte les configurations régionales C et POSIX à base ASCII, mais bascule sur une alternative basée sur l'UTF-8 qui doit posséder plus de possibilités.

Si cette variable n'est pas définie (ou est définie à une valeur autre que @code{0}), que la variable d'environnement de configuration régionale @code{LC_ALL} est également non définie et que la configuration régionale indiquée dans la catégorie @code{LC_TYPE} est soit la région par défaut @code{C}, soit la région @code{POSIX} qui demande explicitement de l'ASCII, alors l'interpréteur en ligne de commande Python essaie de configurer les paramètres régionaux pour la catégorie @code{LC_TYPE} dans l'ordre suivant avant de charger l'exécutable de l'interpréteur :


@itemize *

@item 
@code{C.UTF-8}

@item 
@code{C.utf8}

@item 
@code{UTF-8}
@end itemize

Si la définition d'une des configurations régionales fonctionne, la variable d'environnement @code{LC_TYPE} est aussi définie ainsi dans l'environnement du processus avant que l'exécutable Python ne soit initialisé. Ceci assure que, en plus d'être vue par l'interpréteur lui-même et tous les autres composants prenant en charge la configuration régionale dans le même processus (telle que la bibliothèque GNU @code{readline}), la configuration mise à jour est aussi valable pour les sous-processus (indépendamment du fait qu'ils utilisent un interpréteur Python ou non) ainsi que pour les opérations qui font appel à l'environnement (qui utiliseraient sinon la configuration régionale C courante, tel que c'est le cas pour la propre fonction Python @ref{2d8,,locale.getdefaultlocale()}).

La configuration d'une de ces variables régionales (soit explicitement, soit `via' le mécanisme décrit ci-dessus) active automatiquement @code{surrogateescape} pour la @ref{1774,,gestion des erreurs} de @ref{527,,sys.stdin} et @ref{ac4,,sys.stdout} (@ref{926,,sys.stderr} continue d'utiliser @code{backslashreplace} comme pour toute autre configuration régionale). Ce comportement relatif à la gestion des flux standards peut être surchargé, comme d'habitude, par 
@geindex PYTHONIOENCODING
@geindex variable d'environnement; PYTHONIOENCODING
@ref{ff3,,PYTHONIOENCODING}.

À fin de débogage, définir @code{PYTHONCOERCECLOCALE=warn} indique à Python d'émettre les messages d'avertissement sur @code{stderr} si la configuration régionale est activée, ou si une configuration régionale qui `aurait' activé est toujours active quand l'interpréteur Python est initialisé.

Notez également que même si la contrainte sur la configuration régionale est désactivée, ou si elle ne trouve pas une configuration satisfaisante et échoue, 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8} s'active par défaut avec une configuration régionale par défaut à base ASCII. Ces fonctionnalités doivent être désactivées pour forcer l'interpréteur à utiliser @code{ASCII} en lieu et place de @code{UTF-8} pour les interfaces avec le système.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.7: Voir la 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/} pour plus d'informations.

@end deffn

@geindex variable d'environnement; PYTHONDEVMODE
@anchor{using/cmdline envvar-PYTHONDEVMODE}@anchor{adb}
@deffn {Variable d'environnement} PYTHONDEVMODE

If this environment variable is set to a non-empty string, enable
@ref{1f5,,Python Development Mode}, introducing additional runtime
checks that are too expensive to be enabled by default.
This is equivalent to setting the @ref{175,,-X} @code{dev} option.


Ajouté dans la version 3.7.

@end deffn

@geindex variable d'environnement; PYTHONUTF8
@anchor{using/cmdline envvar-PYTHONUTF8}@anchor{ac6}
@deffn {Variable d'environnement} PYTHONUTF8

La valeur @code{1} active le @ref{641,,mode UTF-8}.

La valeur @code{0} désactive le @ref{641,,mode UTF-8}.

Définir une valeur autre (non vide) entraine une erreur pendant l'initialisation de l'interpréteur.


Ajouté dans la version 3.7.

@end deffn

@geindex variable d'environnement; PYTHONWARNDEFAULTENCODING
@anchor{using/cmdline envvar-PYTHONWARNDEFAULTENCODING}@anchor{7a6}
@deffn {Variable d'environnement} PYTHONWARNDEFAULTENCODING

Si elle est définie à une chaîne non vide, un avertissement @ref{1cc9,,EncodingWarning} est émis lorsque l'encodage par défaut de la configuration régionale est utilisé.

Voir  @ref{1ce1,,Opt-in EncodingWarning} pour plus de détails.


Ajouté dans la version 3.10.

@end deffn

@geindex variable d'environnement; PYTHONNODEBUGRANGES
@anchor{using/cmdline envvar-PYTHONNODEBUGRANGES}@anchor{5a0}
@deffn {Variable d'environnement} PYTHONNODEBUGRANGES

Si cette variable est définie, cela désactive l'inclusion des tableaux qui font la correspondance avec des informations extérieures (ligne de fin, numéros des colonnes de début et de fin) pour toutes les instructions du code. C'est utile quand vous souhaitez diminuer la taille du code objet et des fichiers pyc ou alors quand vous voulez supprimer des informations de position quand l'interpréteur affiche les traces d'appels.


Ajouté dans la version 3.11.

@end deffn

@geindex variable d'environnement; PYTHONPERFSUPPORT
@anchor{using/cmdline envvar-PYTHONPERFSUPPORT}@anchor{458}
@deffn {Variable d'environnement} PYTHONPERFSUPPORT

If this variable is set to a nonzero value, it enables support for
the Linux @code{perf} profiler so Python calls can be detected by it.

If set to @code{0}, disable Linux @code{perf} profiler support.

See also the @ref{175,,-X perf} command-line option
and @ref{18d,,Python support for the Linux perf profiler}.


Ajouté dans la version 3.12.

@end deffn

@geindex variable d'environnement; PYTHON_PERF_JIT_SUPPORT
@anchor{using/cmdline envvar-PYTHON_PERF_JIT_SUPPORT}@anchor{18e}
@deffn {Variable d'environnement} PYTHON_PERF_JIT_SUPPORT

If this variable is set to a nonzero value, it enables support for
the Linux @code{perf} profiler so Python calls can be detected by it
using DWARF information.

If set to @code{0}, disable Linux @code{perf} profiler support.

See also the @ref{175,,-X perf_jit} command-line option
and @ref{18d,,Python support for the Linux perf profiler}.


Ajouté dans la version 3.13.

@end deffn

@geindex variable d'environnement; PYTHON_CPU_COUNT
@anchor{using/cmdline envvar-PYTHON_CPU_COUNT}@anchor{20d}
@deffn {Variable d'environnement} PYTHON_CPU_COUNT

If this variable is set to a positive integer, it overrides the return
values of @ref{1c0,,os.cpu_count()} and @ref{1bf,,os.process_cpu_count()}.

See also the @ref{175,,-X cpu_count} command-line option.


Ajouté dans la version 3.13.

@end deffn

@geindex variable d'environnement; PYTHON_FROZEN_MODULES
@anchor{using/cmdline envvar-PYTHON_FROZEN_MODULES}@anchor{18c}
@deffn {Variable d'environnement} PYTHON_FROZEN_MODULES

If this variable is set to @code{on} or @code{off}, it determines whether or not
frozen modules are ignored by the import machinery.  A value of @code{on} means
they get imported and @code{off} means they are ignored.  The default is @code{on}
for non-debug builds (the normal case) and @code{off} for debug builds.
Note that the @code{importlib_bootstrap} and
@code{importlib_bootstrap_external} frozen modules are always used, even
if this flag is set to @code{off}.

See also the @ref{175,,-X frozen_modules} command-line option.


Ajouté dans la version 3.13.

@end deffn

@geindex variable d'environnement; PYTHON_COLORS
@anchor{using/cmdline envvar-PYTHON_COLORS}@anchor{149}
@deffn {Variable d'environnement} PYTHON_COLORS

If this variable is set to @code{1}, the interpreter will colorize various kinds
of output. Setting it to @code{0} deactivates this behavior.
See also @ref{16a,,Controlling color}.


Ajouté dans la version 3.13.

@end deffn

@geindex variable d'environnement; PYTHON_BASIC_REPL
@anchor{using/cmdline envvar-PYTHON_BASIC_REPL}@anchor{16d}
@deffn {Variable d'environnement} PYTHON_BASIC_REPL

If this variable is set to @code{1}, the interpreter will not attempt to
load the Python-based @ref{169,,REPL} that requires @ref{2b,,curses} and
@ref{b9,,readline}, and will instead use the traditional parser-based
@ref{169,,REPL}.


Ajouté dans la version 3.13.

@end deffn

@geindex variable d'environnement; PYTHON_HISTORY
@anchor{using/cmdline envvar-PYTHON_HISTORY}@anchor{18f}
@deffn {Variable d'environnement} PYTHON_HISTORY

This environment variable can be used to set the location of a
@code{.python_history} file (by default, it is @code{.python_history} in the
user's home directory).


Ajouté dans la version 3.13.

@end deffn

@geindex variable d'environnement; PYTHON_GIL
@anchor{using/cmdline envvar-PYTHON_GIL}@anchor{174}
@deffn {Variable d'environnement} PYTHON_GIL

If this variable is set to @code{1}, the global interpreter lock (GIL) will be
forced on. Setting it to @code{0} forces the GIL off (needs Python configured with
the @ref{173,,--disable-gil} build option).

See also the @ref{175,,-X gil} command-line option, which takes
precedence over this variable, and @ref{13e,,Free-threaded CPython}.


Ajouté dans la version 3.13.

@end deffn

@menu
* Variables en mode débogage:: 

@end menu

@node Variables en mode débogage,,,Variables d'environnement
@anchor{using/cmdline debug-mode-variables}@anchor{1ce2}
@subsubsection Variables en mode débogage


@geindex variable d'environnement; PYTHONDUMPREFS
@anchor{using/cmdline envvar-PYTHONDUMPREFS}@anchor{994}
@deffn {Variable d'environnement} PYTHONDUMPREFS

Si elle est définie, Python affiche (de manière brute) les objets et les compteurs de références toujours existant après la fermeture de l'interpréteur.

Needs Python configured with the @ref{38b,,--with-trace-refs} build option.
@end deffn

@geindex variable d'environnement; PYTHONDUMPREFSFILE
@anchor{using/cmdline envvar-PYTHONDUMPREFSFILE}@anchor{1820}
@deffn {Variable d'environnement} PYTHONDUMPREFSFILE

If set, Python will dump objects and reference counts still alive
after shutting down the interpreter into a file under the path given
as the value to this environment variable.

Needs Python configured with the @ref{38b,,--with-trace-refs} build option.


Ajouté dans la version 3.11.

@end deffn

@geindex variable d'environnement; PYTHON_PRESITE
@anchor{using/cmdline envvar-PYTHON_PRESITE}@anchor{1cca}
@deffn {Variable d'environnement} PYTHON_PRESITE

If this variable is set to a module, that module will be imported
early in the interpreter lifecycle, before the @ref{c6,,site} module is
executed, and before the @ref{1,,__main__} module is created.
Therefore, the imported module is not treated as @ref{1,,__main__}.

This can be used to execute code early during Python initialization.

To import a submodule, use @code{package.module} as the value, like in
an import statement.

See also the @ref{175,,-X presite} command-line option,
which takes precedence over this variable.

Needs Python configured with the @ref{418,,--with-pydebug} build option.


Ajouté dans la version 3.13.

@end deffn

@node Utilisation de Python sur les plateformes Unix,Configurer Python,Ligne de commande et environnement,Installation et utilisation de Python
@anchor{using/unix doc}@anchor{1ce3}@anchor{using/unix using-on-unix}@anchor{1ce4}@anchor{using/unix using-python-on-unix-platforms}@anchor{1ce5}
@section Utilisation de Python sur les plateformes Unix


@menu
* Récupérer et installer la dernière version de Python:: 
* Compiler Python:: 
* Fichiers et chemins liés à Python:: 
* Divers:: 
* Version personnalisée d'OpenSSL:: 

@end menu

@node Récupérer et installer la dernière version de Python,Compiler Python,,Utilisation de Python sur les plateformes Unix
@anchor{using/unix getting-and-installing-the-latest-version-of-python}@anchor{1ce6}
@subsection Récupérer et installer la dernière version de Python


@menu
* Sur Linux:: 
* Sur FreeBSD et OpenBSD:: 

@end menu

@node Sur Linux,Sur FreeBSD et OpenBSD,,Récupérer et installer la dernière version de Python
@anchor{using/unix on-linux}@anchor{1ce7}
@subsubsection Sur Linux


Python est préinstallé sur la plupart des distributions Linux, et est disponible en paquet sur toutes les autres. Cependant, il y a certaines fonctionnalités que vous pourriez vouloir utiliser qui ne sont pas disponibles dans le paquet de votre distribution. Vous pouvez compiler la dernière version de Python depuis les sources.

Dans le cas où Python n'est pas préinstallé et n'est pas disponible dans les dépôts, vous pouvez faire les paquets pour votre propre distribution. Jetez un œil à ces liens :


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://www.debian.org/doc/manuals/maint-guide/first.fr.html}

pour les utilisateurs de Debian

@item @indicateurl{https://en.opensuse.org/Portal:Packaging}

pour les utilisateurs d'OpenSuse

@item @indicateurl{https://docs.fedoraproject.org/fr/package-maintainers/Packaging_Tutorial_2_GNU_Hello/}

pour les utilisateurs de Fedora

@item @indicateurl{https://slackbook.org/html/package-management-making-packages.html}

pour les utilisateurs de Slackware
@end table


@node Sur FreeBSD et OpenBSD,,Sur Linux,Récupérer et installer la dernière version de Python
@anchor{using/unix on-freebsd-and-openbsd}@anchor{1ce8}
@subsubsection Sur FreeBSD et OpenBSD



@itemize *

@item 
Utilisateurs de FreeBSD, pour installer le paquet, utilisez :

@example
pkg install python3
@end example

@item 
Utilisateurs d'OpenBSD, pour installer le paquet, utilisez :

@example
pkg_add -r python

pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/<insert your architecture here>/python-<version>.tgz
@end example

Par exemple les utilisateurs d'@code{i386} récupèrent la version 2.5.1 de Python en faisant :

@example
pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-2.5.1p2.tgz
@end example
@end itemize

@node Compiler Python,Fichiers et chemins liés à Python,Récupérer et installer la dernière version de Python,Utilisation de Python sur les plateformes Unix
@anchor{using/unix building-python}@anchor{1ce9}@anchor{using/unix building-python-on-unix}@anchor{ede}
@subsection Compiler Python


Si vous voulez compiler CPython vous-même, la première chose à faire est de récupérer le code source@footnote{https://www.python.org/downloads/source/}. Vous pouvez télécharger la dernière version ou faire un clone@footnote{https://devguide.python.org/setup/#get-the-source-code}. (Si vous voulez contribuer à des correctifs, il vous faut un clone.)

La compilation s'effectue avec les commandes habituelles :

@example
./configure
make
make install
@end example

Les @ref{1cea,,options de configuration} et mises en garde pour certaines plateformes Unix spécifiques sont largement documentées dans le fichier README.rst@footnote{https://github.com/python/cpython/tree/3.13/README.rst} à la racine du dossier des sources Python.

@cartouche
@quotation Avertissement 
@code{make install} peut écraser ou cacher le binaire @code{python3}. @code{make altinstall} est donc recommandé à la place de @code{make install} puisqu'il installe seulement @code{`exec_prefix'/bin/python`version'}.
@end quotation
@end cartouche

@node Fichiers et chemins liés à Python,Divers,Compiler Python,Utilisation de Python sur les plateformes Unix
@anchor{using/unix python-related-paths-and-files}@anchor{1ceb}
@subsection Fichiers et chemins liés à Python


Ceux-ci sont sujets à des différences en fonction des conventions locales d'installation ; @ref{1cec,,prefix} et @ref{1ced,,exec_prefix} sont dépendants de l’installation et doivent être interprétés comme pour des logiciels GNU ; ils peuvent être égaux.

Par exemple, sur la plupart des systèmes Linux, leur valeur par défaut est @code{/usr}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Fichier/dossier

@tab

Signification

@item

@code{`exec_prefix'/bin/python3}

@tab

Emplacement recommandé de l'interpréteur.

@item

@code{`prefix'/lib/python`version'},
@code{`exec_prefix'/lib/python`version'}

@tab

Emplacements recommandés des dossiers contenant les modules standards.

@item

@code{`prefix'/include/python`version'},
@code{`exec_prefix'/include/python`version'}

@tab

Emplacements recommandés des dossiers contenant les entêtes nécessaires au développement d'extensions Python et à l'intégration de l'interpréteur.

@end multitable


@node Divers,Version personnalisée d'OpenSSL,Fichiers et chemins liés à Python,Utilisation de Python sur les plateformes Unix
@anchor{using/unix miscellaneous}@anchor{1cee}
@subsection Divers


Pour utiliser facilement des scripts Python sur Unix, vous devez les rendre exécutables, par exemple avec

@example
$ chmod +x script
@end example

et mettre un `shebang' approprié en haut du script. Un bon choix est généralement

@example
#!/usr/bin/env python3
@end example

qui cherche l’interpréteur Python dans le 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} complet. Cependant, certains systèmes Unix peuvent ne pas avoir la commande @code{env}, donc vous devrez littéralement écrire @code{/usr/bin/python3} en tant que chemin d’interpréteur.

Pour utiliser des commandes `shell' dans vos scripts Python, regardez le module @ref{d5,,subprocess}.

@node Version personnalisée d'OpenSSL,,Divers,Utilisation de Python sur les plateformes Unix
@anchor{using/unix custom-openssl}@anchor{1cef}@anchor{using/unix unix-custom-openssl}@anchor{1cf0}
@subsection Version personnalisée d'OpenSSL



@enumerate 

@item 
Pour compiler avec votre propre configuration d'OpenSSL et le magasin des certificats de confiance du système, commencez par trouver le sous-dossier de @code{/etc} qui contient le fichier ou le lien symbolique @code{openssl.cnf}. Sur la plupart des distributions, c'est soit @code{/etc/ssl}, soit @code{/etc/pki/tls}. Ce dossier doit également contenir un fichier @code{cert.pem} ou un sous-dossier @code{certs} (ou les deux).

@example
$ find /etc/ -name openssl.cnf -printf "%h\n"
/etc/ssl
@end example

@item 
Téléchargez et compilez OpenSSL. Installez-le, en prenant bien garde de le faire avec la cible @code{install_sw} et non pas @code{install}. En effet, @code{install} réécrirait le fichier @code{openssl.cnf}.

@example
$ curl -O https://www.openssl.org/source/openssl-VERSION.tar.gz
$ tar xzf openssl-VERSION
$ pushd openssl-VERSION
$ ./config \
    --prefix=/usr/local/custom-openssl \
    --libdir=lib \
    --openssldir=/etc/ssl
$ make -j1 depend
$ make -j8
$ make install_sw
$ popd
@end example

@item 
Ensuite, compilez Python avec votre version d'OpenSSL personnalisée (voir les options @code{--with-openssl} et @code{--with-openssl-rpath} du script @code{configure}).

@example
$ pushd python-3.x.x
$ ./configure -C \
    --with-openssl=/usr/local/custom-openssl \
    --with-openssl-rpath=auto \
    --prefix=/usr/local/python-3.x.x
$ make -j8
$ make altinstall
@end example
@end enumerate

@cartouche
@quotation Note 
Les versions d'OpenSSL dans une même série (incrémentation du troisième chiffre) conservent la compatibilité de l'interface binaire. Pour mettre à jour OpenSSL, il n'y a pas besoin de recompiler Python, il suffit de remplacer l'installation d'OpenSSL avec la nouvelle version.
@end quotation
@end cartouche

@node Configurer Python,Utilisation de Python sur Windows,Utilisation de Python sur les plateformes Unix,Installation et utilisation de Python
@anchor{using/configure doc}@anchor{1cf1}@anchor{using/configure configure-python}@anchor{1cf2}
@section Configurer Python


@menu
* Build Requirements:: 
* Generated files:: 
* Options de configuration:: 
* Python Build System:: 
* Compiler and linker flags:: 

@end menu

@node Build Requirements,Generated files,,Configurer Python
@anchor{using/configure build-requirements}@anchor{1cf3}
@subsection Build Requirements


Features and minimum versions required to build CPython:


@itemize *

@item 
A C11@footnote{https://en.cppreference.com/w/c/11} compiler. Optional C11 features@footnote{https://en.wikipedia.org/wiki/C11_(C_standard_revision)#Optional_features}
are not required.

@item 
On Windows, Microsoft Visual Studio 2017 or later is required.

@item 
Support for IEEE 754@footnote{https://en.wikipedia.org/wiki/IEEE_754}
floating-point numbers and floating-point Not-a-Number (NaN)@footnote{https://en.wikipedia.org/wiki/NaN#Floating_point}.

@item 
Support for threads.

@item 
OpenSSL 1.1.1 is the minimum version and OpenSSL 3.0.9 is the recommended
minimum version for the @ref{cf,,ssl} and @ref{67,,hashlib} extension modules.

@item 
SQLite 3.15.2 for the @ref{ce,,sqlite3} extension module.

@item 
Tcl/Tk 8.5.12 for the @ref{ef,,tkinter} module.

@item 
Autoconf 2.71 and aclocal 1.16.5 are required to regenerate the
@code{configure} script.
@end itemize


Modifié dans la version 3.1: Tcl/Tk version 8.3.1 is now required.



Modifié dans la version 3.5: On Windows, Visual Studio 2015 or later is now required.
Tcl/Tk version 8.4 is now required.



Modifié dans la version 3.6: Selected C99 features are now required, like @code{<stdint.h>} and @code{static
inline} functions.



Modifié dans la version 3.7: Thread support and OpenSSL 1.0.2 are now required.



Modifié dans la version 3.10: OpenSSL 1.1.1 is now required.
Require SQLite 3.7.15.



Modifié dans la version 3.11: C11 compiler, IEEE 754 and NaN support are now required.
On Windows, Visual Studio 2017 or later is required.
Tcl/Tk version 8.5.12 is now required for the @ref{ef,,tkinter} module.



Modifié dans la version 3.13: Autoconf 2.71, aclocal 1.16.5 and SQLite 3.15.2 are now required.


See also 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/} "Style Guide for C Code" and 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} "CPython platform
support".

@node Generated files,Options de configuration,Build Requirements,Configurer Python
@anchor{using/configure generated-files}@anchor{1cf4}
@subsection Generated files


To reduce build dependencies, Python source code contains multiple generated
files. Commands to regenerate all generated files:

@example
make regen-all
make regen-stdlib-module-names
make regen-limited-abi
make regen-configure
@end example

The @code{Makefile.pre.in} file documents generated files, their inputs, and tools used
to regenerate them. Search for @code{regen-*} make targets.

@menu
* configure script:: 

@end menu

@node configure script,,,Generated files
@anchor{using/configure configure-script}@anchor{1cf5}
@subsubsection configure script


The @code{make regen-configure} command regenerates the @code{aclocal.m4} file and
the @code{configure} script using the @code{Tools/build/regen-configure.sh} shell
script which uses an Ubuntu container to get the same tools versions and have a
reproducible output.

The container is optional, the following command can be run locally:

@example
autoreconf -ivf -Werror
@end example

The generated files can change depending on the exact @code{autoconf-archive},
@code{aclocal} and @code{pkg-config} versions.

@node Options de configuration,Python Build System,Generated files,Configurer Python
@anchor{using/configure configure-options}@anchor{1cea}@anchor{using/configure id1}@anchor{1cf6}
@subsection Options de configuration


List all @code{configure} script options using:

@example
./configure --help
@end example

Voir aussi le fichier @code{Misc/SpecialBuilds.txt} dans la distribution des sources Python.

@menu
* Options générales:: 
* C compiler options:: 
* Linker options:: 
* Options for third-party dependencies:: 
* Options de WebAssembly:: 
* Options d'installation:: 
* Options de performance:: 
* Compilation de Python en mode débogage:: 
* Debug options:: 
* Linker options: Linker options<2>. 
* Libraries options:: 
* Security Options:: 
* macOS Options:: 
* iOS Options:: 
* Cross Compiling Options:: 

@end menu

@node Options générales,C compiler options,,Options de configuration
@anchor{using/configure general-options}@anchor{1cf7}
@subsubsection Options générales


@geindex option de ligne de commande; --enable-loadable-sqlite-extensions
@anchor{using/configure cmdoption-enable-loadable-sqlite-extensions}@anchor{1cf8}
@deffn {Option} @w{-}@w{-}enable@w{-}loadable@w{-}sqlite@w{-}extensions

Support loadable extensions in the @code{_sqlite} extension module (default
is no) of the @ref{ce,,sqlite3} module.

Voir la méthode  @ref{828,,sqlite3.Connection.enable_load_extension()} du module @ref{ce,,sqlite3}.


Ajouté dans la version 3.6.

@end deffn

@geindex option de ligne de commande; --disable-ipv6
@anchor{using/configure cmdoption-disable-ipv6}@anchor{1cf9}
@deffn {Option} @w{-}@w{-}disable@w{-}ipv6

Désactive la prise en charge d'IPv6 (activé par défaut si géré), voir le module @ref{cb,,socket}.
@end deffn

@geindex option de ligne de commande; --enable-big-digits
@anchor{using/configure cmdoption-enable-big-digits}@anchor{737}
@deffn {Option} @w{-}@w{-}enable@w{-}big@w{-}digits=[15|30]

Définit la taille en bits des chiffres Python @ref{254,,int} : 15 ou 30 bits.

La valeur par défaut est @code{30} bits.

Définit @code{PYLONG_BITS_IN_DIGIT} à @code{15} ou @code{30}.

Voir @ref{1271,,sys.int_info.bits_per_digit}.
@end deffn

@geindex option de ligne de commande; --with-suffix
@anchor{using/configure cmdoption-with-suffix}@anchor{1cfa}
@deffn {Option} @w{-}@w{-}with@w{-}suffix=SUFFIX

Définit à `SUFFIX' le suffixe de l'exécutable Python.

Le suffixe par défaut est @code{.exe} sur Windows et macOS (exécutable @code{python.exe}), @code{.js} pour Emscripten (@code{node}), @code{.html} pour Emscripten (navigateur), @code{.wasm} pour WASI, et une chaîne vide sur les autres plateformes (exécutable @code{python}).


Modifié dans la version 3.11: les suffixes par défaut pour la plateforme WASM sont maintenant @code{.js}, @code{.html} et @code{.wasm}.

@end deffn

@geindex option de ligne de commande; --with-tzpath
@anchor{using/configure cmdoption-with-tzpath}@anchor{1cfb}
@deffn {Option} @w{-}@w{-}with@w{-}tzpath=<list of absolute paths separated by pathsep>

Select the default time zone search path for @ref{1cfc,,zoneinfo.TZPATH}.
See the @ref{1cfd,,Compile-time configuration} of the @ref{133,,zoneinfo} module.

Par défaut : @code{/usr/share/zoneinfo:/usr/lib/zoneinfo:/usr/share/lib/zoneinfo:/etc/zoneinfo}.

Voir le séparateur de chemins @ref{1cd0,,os.pathsep}.


Ajouté dans la version 3.9.

@end deffn

@geindex option de ligne de commande; --without-decimal-contextvar
@anchor{using/configure cmdoption-without-decimal-contextvar}@anchor{1cfe}
@deffn {Option} @w{-}@w{-}without@w{-}decimal@w{-}contextvar

Compile le module d'extension @code{_decimal} en utilisant un contexte local au fil d'exécution plutôt qu'un contexte local de coroutine (défaut). Voir le module @ref{36,,decimal}.

See @ref{1cff,,decimal.HAVE_CONTEXTVAR} and the @ref{24,,contextvars} module.


Ajouté dans la version 3.9.

@end deffn

@geindex option de ligne de commande; --with-dbmliborder
@anchor{using/configure cmdoption-with-dbmliborder}@anchor{1d00}
@deffn {Option} @w{-}@w{-}with@w{-}dbmliborder=<list of backend names>

Change l'ordre de détection des implémentations de base de données pour le module @ref{31,,dbm}.

Une valeur valide est une chaîne de noms d'implémentations séparés par des deux-points (@code{:}) :


@itemize *

@item 
@code{ndbm} ;

@item 
@code{gdbm} ;

@item 
@code{bdb}.
@end itemize
@end deffn

@geindex option de ligne de commande; --without-c-locale-coercion
@anchor{using/configure cmdoption-without-c-locale-coercion}@anchor{1d01}
@deffn {Option} @w{-}@w{-}without@w{-}c@w{-}locale@w{-}coercion

Désactive le forçage des paramètres régionaux C pour un paramètre régional basé sur UTF-8 (activé par défaut).

Ne pas définir la macro @code{PY_COERCE_C_LOCALE}.

Voir 
@geindex PYTHONCOERCECLOCALE
@geindex variable d'environnement; PYTHONCOERCECLOCALE
@ref{ac3,,PYTHONCOERCECLOCALE} et la 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/}.
@end deffn

@geindex option de ligne de commande; --without-freelists
@anchor{using/configure cmdoption-without-freelists}@anchor{736}
@deffn {Option} @w{-}@w{-}without@w{-}freelists

Disable all freelists except the empty tuple singleton.


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --with-platlibdir
@anchor{using/configure cmdoption-with-platlibdir}@anchor{1d02}
@deffn {Option} @w{-}@w{-}with@w{-}platlibdir=DIRNAME

Nom du dossier de bibliothèques Python (par défaut : @code{lib}).

Fedora et SuSE utilisent @code{lib64} sur les systèmes 64-bit.

Voir @ref{925,,sys.platlibdir}.


Ajouté dans la version 3.9.

@end deffn

@geindex option de ligne de commande; --with-wheel-pkg-dir
@anchor{using/configure cmdoption-with-wheel-pkg-dir}@anchor{879}
@deffn {Option} @w{-}@w{-}with@w{-}wheel@w{-}pkg@w{-}dir=PATH

Dossier de paquets `wheel' utilisé par le module @ref{54,,ensurepip} (par défaut : aucun).

Some Linux distribution packaging policies recommend against bundling
dependencies. For example, Fedora installs wheel packages in the
@code{/usr/share/python-wheels/} directory and don't install the
@code{ensurepip._bundled} package.


Ajouté dans la version 3.10.

@end deffn

@geindex option de ligne de commande; --with-pkg-config
@anchor{using/configure cmdoption-with-pkg-config}@anchor{1d03}
@deffn {Option} @w{-}@w{-}with@w{-}pkg@w{-}config=[check|yes|no]

Est-ce que `configure' doit utiliser @code{pkg-config} pour détecter les dépendances de construction.


@itemize *

@item 
@code{check} (par défaut) : @code{pkg-config} est optionnel

@item 
@code{yes} : @code{pkg-config} est obligatoire

@item 
@code{no} : `configure' n'utilise pas @code{pkg-config} même s'il est présent
@end itemize


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --enable-pystats
@anchor{using/configure cmdoption-enable-pystats}@anchor{1749}
@deffn {Option} @w{-}@w{-}enable@w{-}pystats

Turn on internal Python performance statistics gathering.

By default, statistics gathering is off. Use @code{python3 -X pystats} command
or set @code{PYTHONSTATS=1} environment variable to turn on statistics
gathering at Python startup.

At Python exit, dump statistics if statistics gathering was on and not
cleared.

Effects:


@itemize *

@item 
Add @ref{175,,-X pystats} command line option.

@item 
Add @code{PYTHONSTATS} environment variable.

@item 
Define the @code{Py_STATS} macro.

@item 
Add functions to the @ref{d8,,sys} module:


@itemize *

@item 
@code{sys._stats_on()}: Turns on statistics gathering.

@item 
@code{sys._stats_off()}: Turns off statistics gathering.

@item 
@code{sys._stats_clear()}: Clears the statistics.

@item 
@code{sys._stats_dump()}: Dump statistics to file, and clears the statistics.
@end itemize
@end itemize

The statistics will be dumped to a arbitrary (probably unique) file in
@code{/tmp/py_stats/} (Unix) or @code{C:\temp\py_stats\} (Windows). If that
directory does not exist, results will be printed on stderr.

Utilisez @code{Tools/scripts/summarize_stats.py} pour lire les statistiques.

Statistics:


@itemize *

@item 
Opcode:


@itemize *

@item 
Specialization: success, failure, hit, deferred, miss, deopt, failures;

@item 
Execution count;

@item 
Pair count.
@end itemize

@item 
Call:


@itemize *

@item 
Inlined Python calls;

@item 
PyEval calls;

@item 
Frames pushed;

@item 
Frame object created;

@item 
Eval calls: vector, generator, legacy, function VECTORCALL, build class,
slot, function "ex", API, method.
@end itemize

@item 
Object:


@itemize *

@item 
incref and decref;

@item 
interpreter incref and decref;

@item 
allocations: all, 512 bytes, 4 kiB, big;

@item 
free;

@item 
to/from free lists;

@item 
dictionary materialized/dematerialized;

@item 
type cache;

@item 
optimization attempts;

@item 
optimization traces created/executed;

@item 
uops executed.
@end itemize

@item 
Garbage collector:


@itemize *

@item 
Garbage collections;

@item 
Objects visited;

@item 
Objects collected.
@end itemize
@end itemize


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --disable-gil
@anchor{using/configure free-threading-build}@anchor{1d04}@anchor{using/configure cmdoption-disable-gil}@anchor{173}
@deffn {Option} @w{-}@w{-}disable@w{-}gil

Enables `experimental' support for running Python without the
@ref{147,,global interpreter lock} (GIL): free threading build.

Defines the @code{Py_GIL_DISABLED} macro and adds @code{"t"} to
@ref{a52,,sys.abiflags}.

See @ref{13e,,Free-threaded CPython} for more detail.


Ajouté dans la version 3.13.

@end deffn

@geindex option de ligne de commande; --enable-experimental-jit
@anchor{using/configure cmdoption-enable-experimental-jit}@anchor{1d05}
@deffn {Option} @w{-}@w{-}enable@w{-}experimental@w{-}jit=[no|yes|yes@w{-}off|interpreter]

Indicate how to integrate the @ref{13f,,JIT compiler}.


@itemize *

@item 
@code{no} - build the interpreter without the JIT.

@item 
@code{yes} - build the interpreter with the JIT.

@item 
@code{yes-off} - build the interpreter with the JIT but disable it by default.

@item 
@code{interpreter} - build the interpreter without the JIT, but with the tier 2 enabled interpreter.
@end itemize

By convention, @code{--enable-experimental-jit} is a shorthand for @code{--enable-experimental-jit=yes}.


Ajouté dans la version 3.13.

@end deffn

@geindex option de ligne de commande; PKG_CONFIG
@anchor{using/configure cmdoption-arg-PKG_CONFIG}@anchor{1d06}
@deffn {Option} PKG_CONFIG

Path to @code{pkg-config} utility.
@end deffn

@geindex option de ligne de commande; PKG_CONFIG_LIBDIR
@anchor{using/configure cmdoption-arg-PKG_CONFIG_LIBDIR}@anchor{1d07}
@deffn {Option} PKG_CONFIG_LIBDIR
@end deffn

@geindex option de ligne de commande; PKG_CONFIG_PATH
@anchor{using/configure cmdoption-arg-PKG_CONFIG_PATH}@anchor{1d08}
@deffn {Option} PKG_CONFIG_PATH

@code{pkg-config} options.
@end deffn

@node C compiler options,Linker options,Options générales,Options de configuration
@anchor{using/configure c-compiler-options}@anchor{1d09}
@subsubsection C compiler options


@geindex option de ligne de commande; CC
@anchor{using/configure cmdoption-arg-CC}@anchor{1d0a}
@deffn {Option} CC

C compiler command.
@end deffn

@geindex option de ligne de commande; CFLAGS
@anchor{using/configure cmdoption-arg-CFLAGS}@anchor{1d0b}
@deffn {Option} CFLAGS

C compiler flags.
@end deffn

@geindex option de ligne de commande; CPP
@anchor{using/configure cmdoption-arg-CPP}@anchor{1d0c}
@deffn {Option} CPP

C preprocessor command.
@end deffn

@geindex option de ligne de commande; CPPFLAGS
@anchor{using/configure cmdoption-arg-CPPFLAGS}@anchor{1d0d}
@deffn {Option} CPPFLAGS

C preprocessor flags, e.g. @code{-I@var{include_dir}}.
@end deffn

@node Linker options,Options for third-party dependencies,C compiler options,Options de configuration
@anchor{using/configure linker-options}@anchor{1d0e}
@subsubsection Linker options


@geindex option de ligne de commande; LDFLAGS
@anchor{using/configure cmdoption-arg-LDFLAGS}@anchor{1d0f}
@deffn {Option} LDFLAGS

Linker flags, e.g. @code{-L@var{library_directory}}.
@end deffn

@geindex option de ligne de commande; LIBS
@anchor{using/configure cmdoption-arg-LIBS}@anchor{1d10}
@deffn {Option} LIBS

Libraries to pass to the linker, e.g. @code{-l@var{library}}.
@end deffn

@geindex option de ligne de commande; MACHDEP
@anchor{using/configure cmdoption-arg-MACHDEP}@anchor{1d11}
@deffn {Option} MACHDEP

Name for machine-dependent library files.
@end deffn

@node Options for third-party dependencies,Options de WebAssembly,Linker options,Options de configuration
@anchor{using/configure options-for-third-party-dependencies}@anchor{1d12}
@subsubsection Options for third-party dependencies



Ajouté dans la version 3.11.


@geindex option de ligne de commande; BZIP2_CFLAGS
@anchor{using/configure cmdoption-arg-BZIP2_CFLAGS}@anchor{1d13}
@deffn {Option} BZIP2_CFLAGS
@end deffn

@geindex option de ligne de commande; BZIP2_LIBS
@anchor{using/configure cmdoption-arg-BZIP2_LIBS}@anchor{1d14}
@deffn {Option} BZIP2_LIBS

C compiler and linker flags to link Python to @code{libbz2}, used by @ref{13,,bz2}
module, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; CURSES_CFLAGS
@anchor{using/configure cmdoption-arg-CURSES_CFLAGS}@anchor{1d15}
@deffn {Option} CURSES_CFLAGS
@end deffn

@geindex option de ligne de commande; CURSES_LIBS
@anchor{using/configure cmdoption-arg-CURSES_LIBS}@anchor{1d16}
@deffn {Option} CURSES_LIBS

C compiler and linker flags for @code{libncurses} or @code{libncursesw}, used by
@ref{2b,,curses} module, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; GDBM_CFLAGS
@anchor{using/configure cmdoption-arg-GDBM_CFLAGS}@anchor{1d17}
@deffn {Option} GDBM_CFLAGS
@end deffn

@geindex option de ligne de commande; GDBM_LIBS
@anchor{using/configure cmdoption-arg-GDBM_LIBS}@anchor{1d18}
@deffn {Option} GDBM_LIBS

C compiler and linker flags for @code{gdbm}.
@end deffn

@geindex option de ligne de commande; LIBB2_CFLAGS
@anchor{using/configure cmdoption-arg-LIBB2_CFLAGS}@anchor{1d19}
@deffn {Option} LIBB2_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBB2_LIBS
@anchor{using/configure cmdoption-arg-LIBB2_LIBS}@anchor{1d1a}
@deffn {Option} LIBB2_LIBS

C compiler and linker flags for @code{libb2} (@ref{1d1b,,BLAKE2}),
used by @ref{67,,hashlib} module, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; LIBEDIT_CFLAGS
@anchor{using/configure cmdoption-arg-LIBEDIT_CFLAGS}@anchor{1d1c}
@deffn {Option} LIBEDIT_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBEDIT_LIBS
@anchor{using/configure cmdoption-arg-LIBEDIT_LIBS}@anchor{1d1d}
@deffn {Option} LIBEDIT_LIBS

C compiler and linker flags for @code{libedit}, used by @ref{b9,,readline} module,
overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; LIBFFI_CFLAGS
@anchor{using/configure cmdoption-arg-LIBFFI_CFLAGS}@anchor{1d1e}
@deffn {Option} LIBFFI_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBFFI_LIBS
@anchor{using/configure cmdoption-arg-LIBFFI_LIBS}@anchor{1d1f}
@deffn {Option} LIBFFI_LIBS

C compiler and linker flags for @code{libffi}, used by @ref{2a,,ctypes} module,
overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; LIBMPDEC_CFLAGS
@anchor{using/configure cmdoption-arg-LIBMPDEC_CFLAGS}@anchor{1d20}
@deffn {Option} LIBMPDEC_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBMPDEC_LIBS
@anchor{using/configure cmdoption-arg-LIBMPDEC_LIBS}@anchor{1d21}
@deffn {Option} LIBMPDEC_LIBS

C compiler and linker flags for @code{libmpdec}, used by @ref{36,,decimal} module,
overriding @code{pkg-config}.

@cartouche
@quotation Note 
These environment variables have no effect unless
@ref{408,,--with-system-libmpdec} is specified.
@end quotation
@end cartouche
@end deffn

@geindex option de ligne de commande; LIBLZMA_CFLAGS
@anchor{using/configure cmdoption-arg-LIBLZMA_CFLAGS}@anchor{1d22}
@deffn {Option} LIBLZMA_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBLZMA_LIBS
@anchor{using/configure cmdoption-arg-LIBLZMA_LIBS}@anchor{1d23}
@deffn {Option} LIBLZMA_LIBS

C compiler and linker flags for @code{liblzma}, used by @ref{89,,lzma} module,
overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; LIBREADLINE_CFLAGS
@anchor{using/configure cmdoption-arg-LIBREADLINE_CFLAGS}@anchor{1d24}
@deffn {Option} LIBREADLINE_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBREADLINE_LIBS
@anchor{using/configure cmdoption-arg-LIBREADLINE_LIBS}@anchor{1d25}
@deffn {Option} LIBREADLINE_LIBS

C compiler and linker flags for @code{libreadline}, used by @ref{b9,,readline}
module, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; LIBSQLITE3_CFLAGS
@anchor{using/configure cmdoption-arg-LIBSQLITE3_CFLAGS}@anchor{1d26}
@deffn {Option} LIBSQLITE3_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBSQLITE3_LIBS
@anchor{using/configure cmdoption-arg-LIBSQLITE3_LIBS}@anchor{1d27}
@deffn {Option} LIBSQLITE3_LIBS

C compiler and linker flags for @code{libsqlite3}, used by @ref{ce,,sqlite3}
module, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; LIBUUID_CFLAGS
@anchor{using/configure cmdoption-arg-LIBUUID_CFLAGS}@anchor{1d28}
@deffn {Option} LIBUUID_CFLAGS
@end deffn

@geindex option de ligne de commande; LIBUUID_LIBS
@anchor{using/configure cmdoption-arg-LIBUUID_LIBS}@anchor{1d29}
@deffn {Option} LIBUUID_LIBS

C compiler and linker flags for @code{libuuid}, used by @ref{10f,,uuid} module,
overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; PANEL_CFLAGS
@anchor{using/configure cmdoption-arg-PANEL_CFLAGS}@anchor{1d2a}
@deffn {Option} PANEL_CFLAGS
@end deffn

@geindex option de ligne de commande; PANEL_LIBS
@anchor{using/configure cmdoption-arg-PANEL_LIBS}@anchor{1d2b}
@deffn {Option} PANEL_LIBS

C compiler and linker flags for PANEL, overriding @code{pkg-config}.

C compiler and linker flags for @code{libpanel} or @code{libpanelw}, used by
@ref{2d,,curses.panel} module, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; TCLTK_CFLAGS
@anchor{using/configure cmdoption-arg-TCLTK_CFLAGS}@anchor{1d2c}
@deffn {Option} TCLTK_CFLAGS
@end deffn

@geindex option de ligne de commande; TCLTK_LIBS
@anchor{using/configure cmdoption-arg-TCLTK_LIBS}@anchor{1d2d}
@deffn {Option} TCLTK_LIBS

C compiler and linker flags for TCLTK, overriding @code{pkg-config}.
@end deffn

@geindex option de ligne de commande; ZLIB_CFLAGS
@anchor{using/configure cmdoption-arg-ZLIB_CFLAGS}@anchor{1d2e}
@deffn {Option} ZLIB_CFLAGS
@end deffn

@geindex option de ligne de commande; ZLIB_LIBS
@anchor{using/configure cmdoption-arg-ZLIB_LIBS}@anchor{1d2f}
@deffn {Option} ZLIB_LIBS

C compiler and linker flags for @code{libzlib}, used by @ref{66,,gzip} module,
overriding @code{pkg-config}.
@end deffn

@node Options de WebAssembly,Options d'installation,Options for third-party dependencies,Options de configuration
@anchor{using/configure webassembly-options}@anchor{1d30}
@subsubsection Options de WebAssembly


@geindex option de ligne de commande; --with-emscripten-target
@anchor{using/configure cmdoption-with-emscripten-target}@anchor{1d31}
@deffn {Option} @w{-}@w{-}with@w{-}emscripten@w{-}target=[browser|node]

Définit la version de construction pour @code{wasm32-emscripten}.


@itemize *

@item 
@code{browser} (par défaut) : précharge une version minimale de la `stdlib', par défaut MEMFS.

@item 
@code{node}: NODERAWFS et la gestion des `pthread'.
@end itemize


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --enable-wasm-dynamic-linking
@anchor{using/configure cmdoption-enable-wasm-dynamic-linking}@anchor{17bb}
@deffn {Option} @w{-}@w{-}enable@w{-}wasm@w{-}dynamic@w{-}linking

Active la gestion d'édition de liens dynamique pour WASM

L'édition de liens dynamique autorise @code{dlopen}. La taille du fichier exécutable augmente en raison de l'élimination moindre du code mort et des fonctionnalités supplémentaires.


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; --enable-wasm-pthreads
@anchor{using/configure cmdoption-enable-wasm-pthreads}@anchor{178e}
@deffn {Option} @w{-}@w{-}enable@w{-}wasm@w{-}pthreads

Active la gestion des `pthreads' pour WASM.


Ajouté dans la version 3.11.

@end deffn

@node Options d'installation,Options de performance,Options de WebAssembly,Options de configuration
@anchor{using/configure install-options}@anchor{1d32}
@subsubsection Options d'installation


@geindex option de ligne de commande; --prefix
@anchor{using/configure cmdoption-prefix}@anchor{1cec}
@deffn {Option} @w{-}@w{-}prefix=PREFIX

Install architecture-independent files in PREFIX. On Unix, it
defaults to @code{/usr/local}.

This value can be retrieved at runtime using @ref{3ad,,sys.prefix}.

As an example, one can use @code{--prefix="$HOME/.local/"} to install
a Python in its home directory.
@end deffn

@geindex option de ligne de commande; --exec-prefix
@anchor{using/configure cmdoption-exec-prefix}@anchor{1ced}
@deffn {Option} @w{-}@w{-}exec@w{-}prefix=EPREFIX

Install architecture-dependent files in EPREFIX, defaults to @ref{1cec,,--prefix}.

This value can be retrieved at runtime using @ref{3a9,,sys.exec_prefix}.
@end deffn

@geindex option de ligne de commande; --disable-test-modules
@anchor{using/configure cmdoption-disable-test-modules}@anchor{878}
@deffn {Option} @w{-}@w{-}disable@w{-}test@w{-}modules

Don't build nor install test modules, like the @ref{e1,,test} package or the
@code{_testcapi} extension module (built and installed by default).


Ajouté dans la version 3.10.

@end deffn

@geindex option de ligne de commande; --with-ensurepip
@anchor{using/configure cmdoption-with-ensurepip}@anchor{1d33}
@deffn {Option} @w{-}@w{-}with@w{-}ensurepip=[upgrade|install|no]

Sélectionne la commande @ref{54,,ensurepip} exécutée à l'installation de Python :


@itemize *

@item 
@code{upgrade} (défaut) : exécute la commande @code{python -m ensurepip --altinstall --upgrade} ;

@item 
@code{install} : exécute la commande @code{python -m ensurepip --altinstall} ;

@item 
@code{no} : n'exécute pas `ensurepip'.
@end itemize


Ajouté dans la version 3.6.

@end deffn

@node Options de performance,Compilation de Python en mode débogage,Options d'installation,Options de configuration
@anchor{using/configure performance-options}@anchor{1d34}
@subsubsection Options de performance


Configuring Python using @code{--enable-optimizations --with-lto} (PGO + LTO) is
recommended for best performance. The experimental @code{--enable-bolt} flag can
also be used to improve performance.

@geindex option de ligne de commande; --enable-optimizations
@anchor{using/configure cmdoption-enable-optimizations}@anchor{84c}
@deffn {Option} @w{-}@w{-}enable@w{-}optimizations

Active l'optimisation guidée par profilage (`Profile Guided Optimization', PGO) en utilisant 
@geindex PROFILE_TASK
@geindex variable d'environnement; PROFILE_TASK
@ref{169a,,PROFILE_TASK} (désactivé par défaut).

L'utilisation de PGO avec le compilateur C Clang nécessite @code{llvm-profdata}. Sur macOS, GCC est juste un alias vers Clang et partage donc cette contrainte.

Désactive également l'interposition sémantique dans `libpython' si GCC est utilisé avec @code{--enable-shared} : ajoute l'option @code{-fno-semantic-interposition} à la compilation et à l'édition des liens.

@cartouche
@quotation Note 
During the build, you may encounter compiler warnings about
profile data not being available for some source files.
These warnings are harmless, as only a subset of the code is exercised
during profile data acquisition.
To disable these warnings on Clang, manually suppress them by adding
@code{-Wno-profile-instr-unprofiled} to 
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS}.
@end quotation
@end cartouche


Ajouté dans la version 3.6.



Modifié dans la version 3.10: Utilisation de @code{-fno-semantic-interposition} avec GCC.

@end deffn

@geindex variable d'environnement; PROFILE_TASK
@anchor{using/configure envvar-PROFILE_TASK}@anchor{169a}
@deffn {Variable d'environnement} PROFILE_TASK

Variable d'environnement utilisée dans le @code{Makefile} : arguments Python utilisés pour la tâche de préparation de la PGO.

Par défaut : @code{-m test --pgo --timeout=$(TESTTIMEOUT)}.


Ajouté dans la version 3.8.



Modifié dans la version 3.13: Task failure is no longer ignored silently.

@end deffn

@geindex option de ligne de commande; --with-lto
@anchor{using/configure cmdoption-with-lto}@anchor{735}
@deffn {Option} @w{-}@w{-}with@w{-}lto=[full|thin|no|yes]

Active l'optimisation à l'édition des liens (`Link Time Optimization', LTO) à la compilation (désactivé par défaut).

Le compilateur C Clang nécessite @code{llvm-ar} pour la LTO (@code{ar} sur macOS), ainsi qu'un éditeur de liens implémentant la LTO (@code{ld.gold} ou @code{lld}).


Ajouté dans la version 3.6.



Ajouté dans la version 3.11: Pour avoir la fonctionnalité ThinLTO, utilisez @code{--with-lto=thin} avec Clang.



Modifié dans la version 3.12: Use ThinLTO as the default optimization policy on Clang if the compiler accepts the flag.

@end deffn

@geindex option de ligne de commande; --enable-bolt
@anchor{using/configure cmdoption-enable-bolt}@anchor{1d35}
@deffn {Option} @w{-}@w{-}enable@w{-}bolt

Enable usage of the BOLT post-link binary optimizer@footnote{https://github.com/llvm/llvm-project/tree/main/bolt} (disabled by
default).

BOLT is part of the LLVM project but is not always included in their binary
distributions. This flag requires that @code{llvm-bolt} and @code{merge-fdata}
are available.

BOLT is still a fairly new project so this flag should be considered
experimental for now. Because this tool operates on machine code its success
is dependent on a combination of the build environment + the other
optimization configure args + the CPU architecture, and not all combinations
are supported.
BOLT versions before LLVM 16 are known to crash BOLT under some scenarios.
Use of LLVM 16 or newer for BOLT optimization is strongly encouraged.

The @code{BOLT_INSTRUMENT_FLAGS} and @code{BOLT_APPLY_FLAGS}
@code{configure} variables can be defined to override the default set of
arguments for @code{llvm-bolt} to instrument and apply BOLT data to
binaries, respectively.


Ajouté dans la version 3.12.

@end deffn

@geindex option de ligne de commande; BOLT_APPLY_FLAGS
@anchor{using/configure cmdoption-arg-BOLT_APPLY_FLAGS}@anchor{1d36}
@deffn {Option} BOLT_APPLY_FLAGS

Arguments to @code{llvm-bolt} when creating a BOLT optimized binary@footnote{https://github.com/facebookarchive/BOLT}.


Ajouté dans la version 3.12.

@end deffn

@geindex option de ligne de commande; BOLT_INSTRUMENT_FLAGS
@anchor{using/configure cmdoption-arg-BOLT_INSTRUMENT_FLAGS}@anchor{1d37}
@deffn {Option} BOLT_INSTRUMENT_FLAGS

Arguments to @code{llvm-bolt} when instrumenting binaries.


Ajouté dans la version 3.12.

@end deffn

@geindex option de ligne de commande; --with-computed-gotos
@anchor{using/configure cmdoption-with-computed-gotos}@anchor{1d38}
@deffn {Option} @w{-}@w{-}with@w{-}computed@w{-}gotos

Autorise les `gotos' calculés dans les boucles (activé par défaut pour les compilateurs qui le gèrent).
@end deffn

@geindex option de ligne de commande; --without-mimalloc
@anchor{using/configure cmdoption-without-mimalloc}@anchor{1d39}
@deffn {Option} @w{-}@w{-}without@w{-}mimalloc

Disable the fast @ref{1cde,,mimalloc} allocator
(enabled by default).

Voir aussi la variable d'environnement 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC}.
@end deffn

@geindex option de ligne de commande; --without-pymalloc
@anchor{using/configure cmdoption-without-pymalloc}@anchor{1d3a}
@deffn {Option} @w{-}@w{-}without@w{-}pymalloc

Désactive l'allocateur spécialisé de mémoire de Python @ref{cfd,,pymalloc} (activé par défaut).

Voir aussi la variable d'environnement 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC}.
@end deffn

@geindex option de ligne de commande; --without-doc-strings
@anchor{using/configure cmdoption-without-doc-strings}@anchor{1d3b}
@deffn {Option} @w{-}@w{-}without@w{-}doc@w{-}strings

Désactive les chaînes de documentation statiques pour réduire l'empreinte mémoire (activé par défaut). Les chaînes définies dans Python ne sont pas affectées.

Ne définit pas la macro @code{WITH_DOC_STRINGS}.

Voir la macro @code{PyDoc_STRVAR()}.
@end deffn

@geindex option de ligne de commande; --enable-profiling
@anchor{using/configure cmdoption-enable-profiling}@anchor{1d3c}
@deffn {Option} @w{-}@w{-}enable@w{-}profiling

Active le profilage du code C avec @code{gprof} (désactivé par défaut).
@end deffn

@geindex option de ligne de commande; --with-strict-overflow
@anchor{using/configure cmdoption-with-strict-overflow}@anchor{16f0}
@deffn {Option} @w{-}@w{-}with@w{-}strict@w{-}overflow

Add @code{-fstrict-overflow} to the C compiler flags (by default we add
@code{-fno-strict-overflow} instead).
@end deffn

@node Compilation de Python en mode débogage,Debug options,Options de performance,Options de configuration
@anchor{using/configure debug-build}@anchor{1f6}@anchor{using/configure python-debug-build}@anchor{1d3d}
@subsubsection Compilation de Python en mode débogage


Une compilation de Python en mode débogage se fait avec l'option de configuration @ref{418,,--with-pydebug}.

Effets du mode débogage :


@itemize *

@item 
Affichage de tous les avertissements par défaut : le filtre par défaut des avertissements est vide dans le module @ref{111,,warnings}.

@item 
Ajout de @code{d} à @ref{a52,,sys.abiflags}.

@item 
Add @code{sys.gettotalrefcount()} function.

@item 
Ajout de l'option de ligne de commande @ref{175,,-X showrefcount}.

@item 
Add @ref{1cbd,,-d} command line option and 
@geindex PYTHONDEBUG
@geindex variable d'environnement; PYTHONDEBUG
@ref{1cbe,,PYTHONDEBUG} environment
variable to debug the parser.

@item 
Prise en charge de la variable @code{__ltrace__} : si la variable est définie, active le traçage de bas niveau dans la boucle d'évaluation du code intermédiaire.

@item 
Installation des @ref{1cdc,,debug hooks on memory allocators} pour détecter les débordements de mémoire tampon et autres erreurs de mémoire.

@item 
Définition des macros @code{Py_DEBUG} et @code{Py_REF_DEBUG}.

@item 
Ajout de vérifications à l'exécution : codes entourés de @code{#ifdef Py_DEBUG} et @code{#endif}. Active les assertions @code{assert(...)} et @code{_PyObject_ASSERT(...)} : ne définit pas la macro @code{NDEBUG} (voir aussi l'option de configuration @ref{382,,--with-assertions}). Les principales vérifications à l'exécution :


@itemize *

@item 
Ajout des contrôles d'intégrité sur les arguments de fonction.

@item 
Les objets @code{unicode} et @code{int} sont créés avec un motif particulier à l'initialisation de leur mémoire afin de détecter l'usage d'objets non initialisés.

@item 
S'assurer que les fonctions qui peuvent effacer ou remplacer l'exception courante ne sont pas appelées avec une exception levée.

@item 
S'assurer que les fonctions qui désallouent ne changent pas l'exception en cours.

@item 
Le ramasse-miettes (la fonction @ref{a28,,gc.collect()}) effectue quelques tests basiques relatifs à la cohérence des objets.

@item 
The @code{Py_SAFE_DOWNCAST()} macro checks for integer underflow and
overflow when downcasting from wide types to narrow types.
@end itemize
@end itemize

Voir aussi le @ref{1f5,,mode de développement Python} et l'option de configuration @ref{38b,,--with-trace-refs}.


Modifié dans la version 3.8: Release builds and debug builds are now ABI compatible: defining the
@code{Py_DEBUG} macro no longer implies the @code{Py_TRACE_REFS} macro (see the
@ref{38b,,--with-trace-refs} option).


@node Debug options,Linker options<2>,Compilation de Python en mode débogage,Options de configuration
@anchor{using/configure debug-options}@anchor{1d3e}
@subsubsection Debug options


@geindex option de ligne de commande; --with-pydebug
@anchor{using/configure cmdoption-with-pydebug}@anchor{418}
@deffn {Option} @w{-}@w{-}with@w{-}pydebug

@ref{1f6,,Build Python in debug mode}: define the @code{Py_DEBUG}
macro (disabled by default).
@end deffn

@geindex option de ligne de commande; --with-trace-refs
@anchor{using/configure cmdoption-with-trace-refs}@anchor{38b}
@deffn {Option} @w{-}@w{-}with@w{-}trace@w{-}refs

Enable tracing references for debugging purpose (disabled by default).

Effects:


@itemize *

@item 
Define the @code{Py_TRACE_REFS} macro.

@item 
Add @ref{41b,,sys.getobjects()} function.

@item 
Add 
@geindex PYTHONDUMPREFS
@geindex variable d'environnement; PYTHONDUMPREFS
@ref{994,,PYTHONDUMPREFS} environment variable.
@end itemize

The 
@geindex PYTHONDUMPREFS
@geindex variable d'environnement; PYTHONDUMPREFS
@ref{994,,PYTHONDUMPREFS} environment variable can be used to dump
objects and reference counts still alive at Python exit.

@ref{769,,Statically allocated objects} are not traced.


Ajouté dans la version 3.8.



Modifié dans la version 3.13: This build is now ABI compatible with release build and @ref{1f6,,debug build}.

@end deffn

@geindex option de ligne de commande; --with-assertions
@anchor{using/configure cmdoption-with-assertions}@anchor{382}
@deffn {Option} @w{-}@w{-}with@w{-}assertions

Build with C assertions enabled (default is no): @code{assert(...);} and
@code{_PyObject_ASSERT(...);}.

If set, the @code{NDEBUG} macro is not defined in the 
@geindex OPT
@geindex variable d'environnement; OPT
@ref{1d3f,,OPT} compiler
variable.

See also the @ref{418,,--with-pydebug} option (@ref{1f6,,debug build}) which also enables assertions.


Ajouté dans la version 3.6.

@end deffn

@geindex option de ligne de commande; --with-valgrind
@anchor{using/configure cmdoption-with-valgrind}@anchor{1d40}
@deffn {Option} @w{-}@w{-}with@w{-}valgrind

Enable Valgrind support (default is no).
@end deffn

@geindex option de ligne de commande; --with-dtrace
@anchor{using/configure cmdoption-with-dtrace}@anchor{1d41}
@deffn {Option} @w{-}@w{-}with@w{-}dtrace

Enable DTrace support (default is no).

See @ref{c5a,,Instrumenting CPython with DTrace and SystemTap}.


Ajouté dans la version 3.6.

@end deffn

@geindex option de ligne de commande; --with-address-sanitizer
@anchor{using/configure cmdoption-with-address-sanitizer}@anchor{1d42}
@deffn {Option} @w{-}@w{-}with@w{-}address@w{-}sanitizer

Enable AddressSanitizer memory error detector, @code{asan} (default is no).


Ajouté dans la version 3.6.

@end deffn

@geindex option de ligne de commande; --with-memory-sanitizer
@anchor{using/configure cmdoption-with-memory-sanitizer}@anchor{1d43}
@deffn {Option} @w{-}@w{-}with@w{-}memory@w{-}sanitizer

Enable MemorySanitizer allocation error detector, @code{msan} (default is no).


Ajouté dans la version 3.6.

@end deffn

@geindex option de ligne de commande; --with-undefined-behavior-sanitizer
@anchor{using/configure cmdoption-with-undefined-behavior-sanitizer}@anchor{1d44}
@deffn {Option} @w{-}@w{-}with@w{-}undefined@w{-}behavior@w{-}sanitizer

Enable UndefinedBehaviorSanitizer undefined behaviour detector, @code{ubsan}
(default is no).


Ajouté dans la version 3.6.

@end deffn

@geindex option de ligne de commande; --with-thread-sanitizer
@anchor{using/configure cmdoption-with-thread-sanitizer}@anchor{1d45}
@deffn {Option} @w{-}@w{-}with@w{-}thread@w{-}sanitizer

Enable ThreadSanitizer data race detector, @code{tsan}
(default is no).


Ajouté dans la version 3.13.

@end deffn

@node Linker options<2>,Libraries options,Debug options,Options de configuration
@anchor{using/configure id2}@anchor{1d46}
@subsubsection Linker options


@geindex option de ligne de commande; --enable-shared
@anchor{using/configure cmdoption-enable-shared}@anchor{84d}
@deffn {Option} @w{-}@w{-}enable@w{-}shared

Enable building a shared Python library: @code{libpython} (default is no).
@end deffn

@geindex option de ligne de commande; --without-static-libpython
@anchor{using/configure cmdoption-without-static-libpython}@anchor{87a}
@deffn {Option} @w{-}@w{-}without@w{-}static@w{-}libpython

Do not build @code{libpythonMAJOR.MINOR.a} and do not install @code{python.o}
(built and enabled by default).


Ajouté dans la version 3.10.

@end deffn

@node Libraries options,Security Options,Linker options<2>,Options de configuration
@anchor{using/configure libraries-options}@anchor{1d47}
@subsubsection Libraries options


@geindex option de ligne de commande; --with-libs
@anchor{using/configure cmdoption-with-libs}@anchor{1d48}
@deffn {Option} @w{-}@w{-}with@w{-}libs='lib1 ...'

Link against additional libraries (default is no).
@end deffn

@geindex option de ligne de commande; --with-system-expat
@anchor{using/configure cmdoption-with-system-expat}@anchor{1740}
@deffn {Option} @w{-}@w{-}with@w{-}system@w{-}expat

Build the @code{pyexpat} module using an installed @code{expat} library
(default is no).
@end deffn

@geindex option de ligne de commande; --with-system-libmpdec
@anchor{using/configure cmdoption-with-system-libmpdec}@anchor{408}
@deffn {Option} @w{-}@w{-}with@w{-}system@w{-}libmpdec

Build the @code{_decimal} extension module using an installed @code{mpdecimal}
library, see the @ref{36,,decimal} module (default is yes).


Ajouté dans la version 3.3.



Modifié dans la version 3.13: Default to using the installed @code{mpdecimal} library.



Deprecated since version 3.13, will be removed in version 3.15: A copy of the @code{mpdecimal} library sources will no longer be distributed
with Python 3.15.



@subsubheading Voir aussi


@ref{1d20,,LIBMPDEC_CFLAGS} and @ref{1d21,,LIBMPDEC_LIBS}.

@end deffn

@geindex option de ligne de commande; --with-readline
@anchor{using/configure cmdoption-with-readline}@anchor{1d49}
@deffn {Option} @w{-}@w{-}with@w{-}readline=readline|editline

Designate a backend library for the @ref{b9,,readline} module.


@itemize *

@item 
readline: Use readline as the backend.

@item 
editline: Use editline as the backend.
@end itemize


Ajouté dans la version 3.10.

@end deffn

@geindex option de ligne de commande; --without-readline
@anchor{using/configure cmdoption-without-readline}@anchor{1d4a}
@deffn {Option} @w{-}@w{-}without@w{-}readline

Don't build the @ref{b9,,readline} module (built by default).

Don't define the @code{HAVE_LIBREADLINE} macro.


Ajouté dans la version 3.10.

@end deffn

@geindex option de ligne de commande; --with-libm
@anchor{using/configure cmdoption-with-libm}@anchor{1d4b}
@deffn {Option} @w{-}@w{-}with@w{-}libm=STRING

Override @code{libm} math library to `STRING' (default is system-dependent).
@end deffn

@geindex option de ligne de commande; --with-libc
@anchor{using/configure cmdoption-with-libc}@anchor{1d4c}
@deffn {Option} @w{-}@w{-}with@w{-}libc=STRING

Override @code{libc} C library to `STRING' (default is system-dependent).
@end deffn

@geindex option de ligne de commande; --with-openssl
@anchor{using/configure cmdoption-with-openssl}@anchor{1d4d}
@deffn {Option} @w{-}@w{-}with@w{-}openssl=DIR

Root of the OpenSSL directory.


Ajouté dans la version 3.7.

@end deffn

@geindex option de ligne de commande; --with-openssl-rpath
@anchor{using/configure cmdoption-with-openssl-rpath}@anchor{87b}
@deffn {Option} @w{-}@w{-}with@w{-}openssl@w{-}rpath=[no|auto|DIR]

Set runtime library directory (rpath) for OpenSSL libraries:


@itemize *

@item 
@code{no} (default): don't set rpath;

@item 
@code{auto}: auto-detect rpath from @ref{1d4d,,--with-openssl} and
@code{pkg-config};

@item 
`DIR': set an explicit rpath.
@end itemize


Ajouté dans la version 3.10.

@end deffn

@node Security Options,macOS Options,Libraries options,Options de configuration
@anchor{using/configure security-options}@anchor{1d4e}
@subsubsection Security Options


@geindex option de ligne de commande; --with-hash-algorithm
@anchor{using/configure cmdoption-with-hash-algorithm}@anchor{1d4f}
@deffn {Option} @w{-}@w{-}with@w{-}hash@w{-}algorithm=[fnv|siphash13|siphash24]

Select hash algorithm for use in @code{Python/pyhash.c}:


@itemize *

@item 
@code{siphash13} (default);

@item 
@code{siphash24};

@item 
@code{fnv}.
@end itemize


Ajouté dans la version 3.4.



Ajouté dans la version 3.11: @code{siphash13} is added and it is the new default.

@end deffn

@geindex option de ligne de commande; --with-builtin-hashlib-hashes
@anchor{using/configure cmdoption-with-builtin-hashlib-hashes}@anchor{1d50}
@deffn {Option} @w{-}@w{-}with@w{-}builtin@w{-}hashlib@w{-}hashes=md5,sha1,sha256,sha512,sha3,blake2

Built-in hash modules:


@itemize *

@item 
@code{md5};

@item 
@code{sha1};

@item 
@code{sha256};

@item 
@code{sha512};

@item 
@code{sha3} (with shake);

@item 
@code{blake2}.
@end itemize


Ajouté dans la version 3.9.

@end deffn

@geindex option de ligne de commande; --with-ssl-default-suites
@anchor{using/configure cmdoption-with-ssl-default-suites}@anchor{1d51}
@deffn {Option} @w{-}@w{-}with@w{-}ssl@w{-}default@w{-}suites=[python|openssl|STRING]

Override the OpenSSL default cipher suites string:


@itemize *

@item 
@code{python} (default): use Python's preferred selection;

@item 
@code{openssl}: leave OpenSSL's defaults untouched;

@item 
`STRING': use a custom string
@end itemize

See the @ref{cf,,ssl} module.


Ajouté dans la version 3.7.



Modifié dans la version 3.10: The settings @code{python} and `STRING' also set TLS 1.2 as minimum
protocol version.

@end deffn

@node macOS Options,iOS Options,Security Options,Options de configuration
@anchor{using/configure macos-options}@anchor{1d52}
@subsubsection macOS Options


See Mac/README.rst@footnote{https://github.com/python/cpython/tree/3.13/Mac/README.rst}.

@geindex option de ligne de commande; --enable-universalsdk
@anchor{using/configure cmdoption-enable-universalsdk}@anchor{958}
@deffn {Option} @w{-}@w{-}enable@w{-}universalsdk
@end deffn

@geindex option de ligne de commande; --enable-universalsdk
@anchor{using/configure cmdoption-0}@anchor{1d53}
@deffn {Option} @w{-}@w{-}enable@w{-}universalsdk=SDKDIR

Create a universal binary build. `SDKDIR' specifies which macOS SDK should
be used to perform the build (default is no).
@end deffn

@geindex option de ligne de commande; --enable-framework
@anchor{using/configure cmdoption-enable-framework}@anchor{1d54}
@deffn {Option} @w{-}@w{-}enable@w{-}framework
@end deffn

@geindex option de ligne de commande; --enable-framework
@anchor{using/configure cmdoption-1}@anchor{1d55}
@deffn {Option} @w{-}@w{-}enable@w{-}framework=INSTALLDIR

Create a Python.framework rather than a traditional Unix install. Optional
`INSTALLDIR' specifies the installation path (default is no).
@end deffn

@geindex option de ligne de commande; --with-universal-archs
@anchor{using/configure cmdoption-with-universal-archs}@anchor{1d56}
@deffn {Option} @w{-}@w{-}with@w{-}universal@w{-}archs=ARCH

Specify the kind of universal binary that should be created. This option is
only valid when @ref{958,,--enable-universalsdk} is set.

Options:


@itemize *

@item 
@code{universal2};

@item 
@code{32-bit};

@item 
@code{64-bit};

@item 
@code{3-way};

@item 
@code{intel};

@item 
@code{intel-32};

@item 
@code{intel-64};

@item 
@code{all}.
@end itemize
@end deffn

@geindex option de ligne de commande; --with-framework-name
@anchor{using/configure cmdoption-with-framework-name}@anchor{1d57}
@deffn {Option} @w{-}@w{-}with@w{-}framework@w{-}name=FRAMEWORK

Specify the name for the python framework on macOS only valid when
@ref{1d54,,--enable-framework} is set (default: @code{Python}).
@end deffn

@geindex option de ligne de commande; --with-app-store-compliance
@anchor{using/configure cmdoption-with-app-store-compliance}@anchor{157b}
@deffn {Option} @w{-}@w{-}with@w{-}app@w{-}store@w{-}compliance
@end deffn

@geindex option de ligne de commande; --with-app-store-compliance
@anchor{using/configure cmdoption-2}@anchor{1d58}
@deffn {Option} @w{-}@w{-}with@w{-}app@w{-}store@w{-}compliance=PATCH@w{-}FILE

The Python standard library contains strings that are known to trigger
automated inspection tool errors when submitted for distribution by
the macOS and iOS App Stores. If enabled, this option will apply the list of
patches that are known to correct app store compliance. A custom patch
file can also be specified. This option is disabled by default.


Ajouté dans la version 3.13.

@end deffn

@node iOS Options,Cross Compiling Options,macOS Options,Options de configuration
@anchor{using/configure ios-options}@anchor{1d59}
@subsubsection iOS Options


See iOS/README.rst@footnote{https://github.com/python/cpython/tree/3.13/iOS/README.rst}.

@geindex option de ligne de commande; --enable-framework
@anchor{using/configure cmdoption-3}@anchor{1d5a}
@deffn {Option} @w{-}@w{-}enable@w{-}framework=INSTALLDIR

Create a Python.framework. Unlike macOS, the `INSTALLDIR' argument
specifying the installation path is mandatory.
@end deffn

@geindex option de ligne de commande; --with-framework-name
@anchor{using/configure cmdoption-4}@anchor{1d5b}
@deffn {Option} @w{-}@w{-}with@w{-}framework@w{-}name=FRAMEWORK

Specify the name for the framework (default: @code{Python}).
@end deffn

@node Cross Compiling Options,,iOS Options,Options de configuration
@anchor{using/configure cross-compiling-options}@anchor{1d5c}
@subsubsection Cross Compiling Options


Cross compiling, also known as cross building, can be used to build Python
for another CPU architecture or platform. Cross compiling requires a Python
interpreter for the build platform. The version of the build Python must match
the version of the cross compiled host Python.

@geindex option de ligne de commande; --build
@anchor{using/configure cmdoption-build}@anchor{1d5d}
@deffn {Option} @w{-}@w{-}build=BUILD

configure for building on BUILD, usually guessed by @code{config.guess}.
@end deffn

@geindex option de ligne de commande; --host
@anchor{using/configure cmdoption-host}@anchor{1d5e}
@deffn {Option} @w{-}@w{-}host=HOST

cross-compile to build programs to run on HOST (target platform)
@end deffn

@geindex option de ligne de commande; --with-build-python
@anchor{using/configure cmdoption-with-build-python}@anchor{1d5f}
@deffn {Option} @w{-}@w{-}with@w{-}build@w{-}python=path/to/python

path to build @code{python} binary for cross compiling


Ajouté dans la version 3.11.

@end deffn

@geindex option de ligne de commande; CONFIG_SITE
@anchor{using/configure cmdoption-arg-CONFIG_SITE}@anchor{1d60}
@deffn {Option} CONFIG_SITE=file

An environment variable that points to a file with configure overrides.

Example `config.site' file:

@example
# config.site-aarch64
ac_cv_buggy_getaddrinfo=no
ac_cv_file__dev_ptmx=yes
ac_cv_file__dev_ptc=no
@end example
@end deffn

@geindex option de ligne de commande; HOSTRUNNER
@anchor{using/configure cmdoption-arg-HOSTRUNNER}@anchor{1d61}
@deffn {Option} HOSTRUNNER

Program to run CPython for the host platform for cross-compilation.


Ajouté dans la version 3.11.

@end deffn

Cross compiling example:

@example
CONFIG_SITE=config.site-aarch64 ../configure \
    --build=x86_64-pc-linux-gnu \
    --host=aarch64-unknown-linux-gnu \
    --with-build-python=../x86_64/python
@end example

@node Python Build System,Compiler and linker flags,Options de configuration,Configurer Python
@anchor{using/configure python-build-system}@anchor{1d62}
@subsection Python Build System


@menu
* Main files of the build system:: 
* Main build steps:: 
* Main Makefile targets:: 
* C extensions:: 

@end menu

@node Main files of the build system,Main build steps,,Python Build System
@anchor{using/configure main-files-of-the-build-system}@anchor{1d63}
@subsubsection Main files of the build system



@itemize *

@item 
@code{configure.ac} => @code{configure};

@item 
@code{Makefile.pre.in} => @code{Makefile} (created by @code{configure});

@item 
@code{pyconfig.h} (created by @code{configure});

@item 
@code{Modules/Setup}: C extensions built by the Makefile using
@code{Module/makesetup} shell script;
@end itemize

@node Main build steps,Main Makefile targets,Main files of the build system,Python Build System
@anchor{using/configure main-build-steps}@anchor{1d64}
@subsubsection Main build steps



@itemize *

@item 
C files (@code{.c}) are built as object files (@code{.o}).

@item 
A static @code{libpython} library (@code{.a}) is created from objects files.

@item 
@code{python.o} and the static @code{libpython} library are linked into the
final @code{python} program.

@item 
C extensions are built by the Makefile (see @code{Modules/Setup}).
@end itemize

@node Main Makefile targets,C extensions,Main build steps,Python Build System
@anchor{using/configure main-makefile-targets}@anchor{1d65}
@subsubsection Main Makefile targets


@menu
* make:: 
* make platform:: 
* make profile-opt:: 
* make clean:: 
* make distclean:: 
* make install:: 
* make test:: 
* make buildbottest:: 
* make regen-all:: 

@end menu

@node make,make platform,,Main Makefile targets
@anchor{using/configure make}@anchor{1d66}
@subsubsection make


For the most part, when rebuilding after editing some code or
refreshing your checkout from upstream, all you need to do is execute
@code{make}, which (per Make's semantics) builds the default target, the
first one defined in the Makefile.  By tradition (including in the
CPython project) this is usually the @code{all} target. The
@code{configure} script expands an @code{autoconf} variable,
@code{@@DEF_MAKE_ALL_RULE@@} to describe precisely which targets @code{make
all} will build. The three choices are:


@itemize *

@item 
@code{profile-opt} (configured with @code{--enable-optimizations})

@item 
@code{build_wasm} (configured with @code{--with-emscripten-target})

@item 
@code{build_all} (configured without explicitly using either of the others)
@end itemize

Depending on the most recent source file changes, Make will rebuild
any targets (object files and executables) deemed out-of-date,
including running @code{configure} again if necessary. Source/target
dependencies are many and maintained manually however, so Make
sometimes doesn't have all the information necessary to correctly
detect all targets which need to be rebuilt.  Depending on which
targets aren't rebuilt, you might experience a number of problems. If
you have build or test problems which you can't otherwise explain,
@code{make clean && make} should work around most dependency problems, at
the expense of longer build times.

@node make platform,make profile-opt,make,Main Makefile targets
@anchor{using/configure make-platform}@anchor{1d67}
@subsubsection make platform


Build the @code{python} program, but don't build the standard library
extension modules. This generates a file named @code{platform} which
contains a single line describing the details of the build platform,
e.g., @code{macosx-14.3-arm64-3.12} or @code{linux-x86_64-3.13}.

@node make profile-opt,make clean,make platform,Main Makefile targets
@anchor{using/configure make-profile-opt}@anchor{1d68}
@subsubsection make profile-opt


Build Python using profile-guided optimization (PGO).  You can use the
configure @ref{84c,,--enable-optimizations} option to make this the
default target of the @code{make} command (@code{make all} or just
@code{make}).

@node make clean,make distclean,make profile-opt,Main Makefile targets
@anchor{using/configure make-clean}@anchor{1d69}
@subsubsection make clean


Remove built files.

@node make distclean,make install,make clean,Main Makefile targets
@anchor{using/configure make-distclean}@anchor{1d6a}
@subsubsection make distclean


In addition to the work done by @code{make clean}, remove files
created by the configure script.  @code{configure} will have to be run
before building again. @footnote{
@code{git clean -fdx} is an even more extreme way to "clean" your
checkout. It removes all files not known to Git.
When bug hunting using @code{git bisect}, this is
@uref{https://github.com/python/cpython/issues/114505#issuecomment-1907021718,recommended between probes}
to guarantee a completely clean build. `Use with care', as it
will delete all files not checked into Git, including your
new, uncommitted work.
}

@node make install,make test,make distclean,Main Makefile targets
@anchor{using/configure make-install}@anchor{1d6b}
@subsubsection make install


Build the @code{all} target and install Python.

@node make test,make buildbottest,make install,Main Makefile targets
@anchor{using/configure make-test}@anchor{1d6c}
@subsubsection make test


Build the @code{all} target and run the Python test suite with the
@code{--fast-ci} option. Variables:


@itemize *

@item 
@code{TESTOPTS}: additional regrtest command-line options.

@item 
@code{TESTPYTHONOPTS}: additional Python command-line options.

@item 
@code{TESTTIMEOUT}: timeout in seconds (default: 10 minutes).
@end itemize

@node make buildbottest,make regen-all,make test,Main Makefile targets
@anchor{using/configure make-buildbottest}@anchor{1d6d}
@subsubsection make buildbottest


This is similar to @code{make test}, but uses the @code{--slow-ci}
option and default timeout of 20 minutes, instead of @code{--fast-ci} option.

@node make regen-all,,make buildbottest,Main Makefile targets
@anchor{using/configure make-regen-all}@anchor{1d6e}
@subsubsection make regen-all


Regenerate (almost) all generated files. These include (but are not
limited to) bytecode cases, and parser generator file.
@code{make regen-stdlib-module-names} and @code{autoconf} must be run
separately for the remaining @ref{1cf4,,generated files}.

@node C extensions,,Main Makefile targets,Python Build System
@anchor{using/configure c-extensions}@anchor{1d6f}
@subsubsection C extensions


Some C extensions are built as built-in modules, like the @code{sys} module.
They are built with the @code{Py_BUILD_CORE_BUILTIN} macro defined.
Built-in modules have no @code{__file__} attribute:

@example
>>> import sys
>>> sys
<module 'sys' (built-in)>
>>> sys.__file__
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: module 'sys' has no attribute '__file__'
@end example

Other C extensions are built as dynamic libraries, like the @code{_asyncio} module.
They are built with the @code{Py_BUILD_CORE_MODULE} macro defined.
Example on Linux x86-64:

@example
>>> import _asyncio
>>> _asyncio
<module '_asyncio' from '/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'>
>>> _asyncio.__file__
'/usr/lib64/python3.9/lib-dynload/_asyncio.cpython-39-x86_64-linux-gnu.so'
@end example

@code{Modules/Setup} is used to generate Makefile targets to build C extensions.
At the beginning of the files, C extensions are built as built-in modules.
Extensions defined after the @code{*shared*} marker are built as dynamic libraries.

The @code{PyAPI_FUNC()}, @code{PyAPI_DATA()} and
@ref{1489,,PyMODINIT_FUNC} macros of @code{Include/exports.h} are defined
differently depending if the @code{Py_BUILD_CORE_MODULE} macro is defined:


@itemize *

@item 
Use @code{Py_EXPORTED_SYMBOL} if the @code{Py_BUILD_CORE_MODULE} is defined

@item 
Use @code{Py_IMPORTED_SYMBOL} otherwise.
@end itemize

If the @code{Py_BUILD_CORE_BUILTIN} macro is used by mistake on a C extension
built as a shared library, its @code{PyInit_@var{xxx}()} function is not exported,
causing an @ref{40f,,ImportError} on import.

@node Compiler and linker flags,,Python Build System,Configurer Python
@anchor{using/configure compiler-and-linker-flags}@anchor{1d70}
@subsection Compiler and linker flags


Options set by the @code{./configure} script and environment variables and used by
@code{Makefile}.

@menu
* Preprocessor flags:: 
* Compiler flags:: 
* Linker flags:: 

@end menu

@node Preprocessor flags,Compiler flags,,Compiler and linker flags
@anchor{using/configure preprocessor-flags}@anchor{1d71}
@subsubsection Preprocessor flags


@geindex variable d'environnement; CONFIGURE_CPPFLAGS
@anchor{using/configure envvar-CONFIGURE_CPPFLAGS}@anchor{1d72}
@deffn {Variable d'environnement} CONFIGURE_CPPFLAGS

Value of 
@geindex CPPFLAGS
@geindex variable d'environnement; CPPFLAGS
@ref{146d,,CPPFLAGS} variable passed to the @code{./configure} script.


Ajouté dans la version 3.6.

@end deffn

@geindex variable d'environnement; CPPFLAGS
@anchor{using/configure envvar-CPPFLAGS}@anchor{146d}
@deffn {Variable d'environnement} CPPFLAGS

(Objective) C/C++ preprocessor flags, e.g. @code{-I@var{include_dir}} if you have
headers in a nonstandard directory `include_dir'.

Both 
@geindex CPPFLAGS
@geindex variable d'environnement; CPPFLAGS
@ref{146d,,CPPFLAGS} and 
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS} need to contain the shell's
value to be able to build extension modules using the
directories specified in the environment variables.
@end deffn

@geindex variable d'environnement; BASECPPFLAGS
@anchor{using/configure envvar-BASECPPFLAGS}@anchor{1d73}
@deffn {Variable d'environnement} BASECPPFLAGS


Ajouté dans la version 3.4.

@end deffn

@geindex variable d'environnement; PY_CPPFLAGS
@anchor{using/configure envvar-PY_CPPFLAGS}@anchor{1d74}
@deffn {Variable d'environnement} PY_CPPFLAGS

Extra preprocessor flags added for building the interpreter object files.

Default: @code{$(BASECPPFLAGS) -I. -I$(srcdir)/Include $(CONFIGURE_CPPFLAGS) $(CPPFLAGS)}.


Ajouté dans la version 3.2.

@end deffn

@node Compiler flags,Linker flags,Preprocessor flags,Compiler and linker flags
@anchor{using/configure compiler-flags}@anchor{1d75}
@subsubsection Compiler flags


@geindex variable d'environnement; CC
@anchor{using/configure envvar-CC}@anchor{146a}
@deffn {Variable d'environnement} CC

C compiler command.

Example: @code{gcc -pthread}.
@end deffn

@geindex variable d'environnement; CXX
@anchor{using/configure envvar-CXX}@anchor{1d76}
@deffn {Variable d'environnement} CXX

C++ compiler command.

Example: @code{g++ -pthread}.
@end deffn

@geindex variable d'environnement; CFLAGS
@anchor{using/configure envvar-CFLAGS}@anchor{146b}
@deffn {Variable d'environnement} CFLAGS

C compiler flags.
@end deffn

@geindex variable d'environnement; CFLAGS_NODIST
@anchor{using/configure envvar-CFLAGS_NODIST}@anchor{1d77}
@deffn {Variable d'environnement} CFLAGS_NODIST

@geindex CFLAGS_NODIST
@geindex variable d'environnement; CFLAGS_NODIST
@ref{1d77,,CFLAGS_NODIST} is used for building the interpreter and stdlib C
extensions.  Use it when a compiler flag should `not' be part of
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS} once Python is installed (gh-65320@footnote{https://github.com/python/cpython/issues/65320}).

In particular, 
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS} should not contain:


@itemize *

@item 
the compiler flag @code{-I} (for setting the search path for include files).
The @code{-I} flags are processed from left to right, and any flags in
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS} would take precedence over user- and package-supplied @code{-I}
flags.

@item 
hardening flags such as @code{-Werror} because distributions cannot control
whether packages installed by users conform to such heightened
standards.
@end itemize


Ajouté dans la version 3.5.

@end deffn

@geindex variable d'environnement; COMPILEALL_OPTS
@anchor{using/configure envvar-COMPILEALL_OPTS}@anchor{1d78}
@deffn {Variable d'environnement} COMPILEALL_OPTS

Options passed to the @ref{20,,compileall} command line when building PYC files
in @code{make install}. Default: @code{-j0}.


Ajouté dans la version 3.12.

@end deffn

@geindex variable d'environnement; EXTRA_CFLAGS
@anchor{using/configure envvar-EXTRA_CFLAGS}@anchor{1d79}
@deffn {Variable d'environnement} EXTRA_CFLAGS

Extra C compiler flags.
@end deffn

@geindex variable d'environnement; CONFIGURE_CFLAGS
@anchor{using/configure envvar-CONFIGURE_CFLAGS}@anchor{1d7a}
@deffn {Variable d'environnement} CONFIGURE_CFLAGS

Value of 
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS} variable passed to the @code{./configure}
script.


Ajouté dans la version 3.2.

@end deffn

@geindex variable d'environnement; CONFIGURE_CFLAGS_NODIST
@anchor{using/configure envvar-CONFIGURE_CFLAGS_NODIST}@anchor{1d7b}
@deffn {Variable d'environnement} CONFIGURE_CFLAGS_NODIST

Value of 
@geindex CFLAGS_NODIST
@geindex variable d'environnement; CFLAGS_NODIST
@ref{1d77,,CFLAGS_NODIST} variable passed to the @code{./configure}
script.


Ajouté dans la version 3.5.

@end deffn

@geindex variable d'environnement; BASECFLAGS
@anchor{using/configure envvar-BASECFLAGS}@anchor{1d7c}
@deffn {Variable d'environnement} BASECFLAGS

Base compiler flags.
@end deffn

@geindex variable d'environnement; OPT
@anchor{using/configure envvar-OPT}@anchor{1d3f}
@deffn {Variable d'environnement} OPT

Optimization flags.
@end deffn

@geindex variable d'environnement; CFLAGS_ALIASING
@anchor{using/configure envvar-CFLAGS_ALIASING}@anchor{1d7d}
@deffn {Variable d'environnement} CFLAGS_ALIASING

Strict or non-strict aliasing flags used to compile @code{Python/dtoa.c}.


Ajouté dans la version 3.7.

@end deffn

@geindex variable d'environnement; CCSHARED
@anchor{using/configure envvar-CCSHARED}@anchor{1d7e}
@deffn {Variable d'environnement} CCSHARED

Compiler flags used to build a shared library.

For example, @code{-fPIC} is used on Linux and on BSD.
@end deffn

@geindex variable d'environnement; CFLAGSFORSHARED
@anchor{using/configure envvar-CFLAGSFORSHARED}@anchor{1d7f}
@deffn {Variable d'environnement} CFLAGSFORSHARED

Extra C flags added for building the interpreter object files.

Default: @code{$(CCSHARED)} when @ref{84d,,--enable-shared} is used, or an empty
string otherwise.
@end deffn

@geindex variable d'environnement; PY_CFLAGS
@anchor{using/configure envvar-PY_CFLAGS}@anchor{1d80}
@deffn {Variable d'environnement} PY_CFLAGS

Default: @code{$(BASECFLAGS) $(OPT) $(CONFIGURE_CFLAGS) $(CFLAGS) $(EXTRA_CFLAGS)}.
@end deffn

@geindex variable d'environnement; PY_CFLAGS_NODIST
@anchor{using/configure envvar-PY_CFLAGS_NODIST}@anchor{1d81}
@deffn {Variable d'environnement} PY_CFLAGS_NODIST

Default: @code{$(CONFIGURE_CFLAGS_NODIST) $(CFLAGS_NODIST) -I$(srcdir)/Include/internal}.


Ajouté dans la version 3.5.

@end deffn

@geindex variable d'environnement; PY_STDMODULE_CFLAGS
@anchor{using/configure envvar-PY_STDMODULE_CFLAGS}@anchor{1d82}
@deffn {Variable d'environnement} PY_STDMODULE_CFLAGS

C flags used for building the interpreter object files.

Default: @code{$(PY_CFLAGS) $(PY_CFLAGS_NODIST) $(PY_CPPFLAGS) $(CFLAGSFORSHARED)}.


Ajouté dans la version 3.7.

@end deffn

@geindex variable d'environnement; PY_CORE_CFLAGS
@anchor{using/configure envvar-PY_CORE_CFLAGS}@anchor{1d83}
@deffn {Variable d'environnement} PY_CORE_CFLAGS

Default: @code{$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE}.


Ajouté dans la version 3.2.

@end deffn

@geindex variable d'environnement; PY_BUILTIN_MODULE_CFLAGS
@anchor{using/configure envvar-PY_BUILTIN_MODULE_CFLAGS}@anchor{1d84}
@deffn {Variable d'environnement} PY_BUILTIN_MODULE_CFLAGS

Compiler flags to build a standard library extension module as a built-in
module, like the @ref{ac,,posix} module.

Default: @code{$(PY_STDMODULE_CFLAGS) -DPy_BUILD_CORE_BUILTIN}.


Ajouté dans la version 3.8.

@end deffn

@geindex variable d'environnement; PURIFY
@anchor{using/configure envvar-PURIFY}@anchor{1d85}
@deffn {Variable d'environnement} PURIFY

Purify command. Purify is a memory debugger program.

Default: empty string (not used).
@end deffn

@node Linker flags,,Compiler flags,Compiler and linker flags
@anchor{using/configure linker-flags}@anchor{1d86}
@subsubsection Linker flags


@geindex variable d'environnement; LINKCC
@anchor{using/configure envvar-LINKCC}@anchor{1d87}
@deffn {Variable d'environnement} LINKCC

Linker command used to build programs like @code{python} and @code{_testembed}.

Default: @code{$(PURIFY) $(CC)}.
@end deffn

@geindex variable d'environnement; CONFIGURE_LDFLAGS
@anchor{using/configure envvar-CONFIGURE_LDFLAGS}@anchor{1d88}
@deffn {Variable d'environnement} CONFIGURE_LDFLAGS

Value of 
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS} variable passed to the @code{./configure} script.

Avoid assigning 
@geindex CFLAGS
@geindex variable d'environnement; CFLAGS
@ref{146b,,CFLAGS}, 
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS}, etc. so users can use
them on the command line to append to these values without stomping the
pre-set values.


Ajouté dans la version 3.2.

@end deffn

@geindex variable d'environnement; LDFLAGS_NODIST
@anchor{using/configure envvar-LDFLAGS_NODIST}@anchor{1d89}
@deffn {Variable d'environnement} LDFLAGS_NODIST

@geindex LDFLAGS_NODIST
@geindex variable d'environnement; LDFLAGS_NODIST
@ref{1d89,,LDFLAGS_NODIST} is used in the same manner as
@geindex CFLAGS_NODIST
@geindex variable d'environnement; CFLAGS_NODIST
@ref{1d77,,CFLAGS_NODIST}.  Use it when a linker flag should `not' be part of
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS} once Python is installed (gh-65320@footnote{https://github.com/python/cpython/issues/65320}).

In particular, 
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS} should not contain:


@itemize *

@item 
the compiler flag @code{-L} (for setting the search path for libraries).
The @code{-L} flags are processed from left to right, and any flags in
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS} would take precedence over user- and package-supplied @code{-L}
flags.
@end itemize
@end deffn

@geindex variable d'environnement; CONFIGURE_LDFLAGS_NODIST
@anchor{using/configure envvar-CONFIGURE_LDFLAGS_NODIST}@anchor{1d8a}
@deffn {Variable d'environnement} CONFIGURE_LDFLAGS_NODIST

Value of 
@geindex LDFLAGS_NODIST
@geindex variable d'environnement; LDFLAGS_NODIST
@ref{1d89,,LDFLAGS_NODIST} variable passed to the @code{./configure}
script.


Ajouté dans la version 3.8.

@end deffn

@geindex variable d'environnement; LDFLAGS
@anchor{using/configure envvar-LDFLAGS}@anchor{146c}
@deffn {Variable d'environnement} LDFLAGS

Linker flags, e.g. @code{-L@var{lib_dir}} if you have libraries in a nonstandard
directory `lib_dir'.

Both 
@geindex CPPFLAGS
@geindex variable d'environnement; CPPFLAGS
@ref{146d,,CPPFLAGS} and 
@geindex LDFLAGS
@geindex variable d'environnement; LDFLAGS
@ref{146c,,LDFLAGS} need to contain the shell's
value to be able to build extension modules using the
directories specified in the environment variables.
@end deffn

@geindex variable d'environnement; LIBS
@anchor{using/configure envvar-LIBS}@anchor{1d8b}
@deffn {Variable d'environnement} LIBS

Linker flags to pass libraries to the linker when linking the Python
executable.

Example: @code{-lrt}.
@end deffn

@geindex variable d'environnement; LDSHARED
@anchor{using/configure envvar-LDSHARED}@anchor{1d8c}
@deffn {Variable d'environnement} LDSHARED

Command to build a shared library.

Default: @code{@@LDSHARED@@ $(PY_LDFLAGS)}.
@end deffn

@geindex variable d'environnement; BLDSHARED
@anchor{using/configure envvar-BLDSHARED}@anchor{1d8d}
@deffn {Variable d'environnement} BLDSHARED

Command to build @code{libpython} shared library.

Default: @code{@@BLDSHARED@@ $(PY_CORE_LDFLAGS)}.
@end deffn

@geindex variable d'environnement; PY_LDFLAGS
@anchor{using/configure envvar-PY_LDFLAGS}@anchor{1d8e}
@deffn {Variable d'environnement} PY_LDFLAGS

Default: @code{$(CONFIGURE_LDFLAGS) $(LDFLAGS)}.
@end deffn

@geindex variable d'environnement; PY_LDFLAGS_NODIST
@anchor{using/configure envvar-PY_LDFLAGS_NODIST}@anchor{1d8f}
@deffn {Variable d'environnement} PY_LDFLAGS_NODIST

Default: @code{$(CONFIGURE_LDFLAGS_NODIST) $(LDFLAGS_NODIST)}.


Ajouté dans la version 3.8.

@end deffn

@geindex variable d'environnement; PY_CORE_LDFLAGS
@anchor{using/configure envvar-PY_CORE_LDFLAGS}@anchor{1d90}
@deffn {Variable d'environnement} PY_CORE_LDFLAGS

Linker flags used for building the interpreter object files.


Ajouté dans la version 3.8.

@end deffn

@subsubheading Notes


@node Utilisation de Python sur Windows,Using Python on macOS,Configurer Python,Installation et utilisation de Python
@anchor{using/windows doc}@anchor{1d91}@anchor{using/windows using-on-windows}@anchor{a95}@anchor{using/windows using-python-on-windows}@anchor{1d92}
@section Utilisation de Python sur Windows


Ce document a pour but de donner une vue d'ensemble des comportements spécifiques à Windows dont vous devriez être au courant si vous utilisez Python sur Microsoft Windows.

Unlike most Unix systems and services, Windows does not include a system
supported installation of Python. To make Python available, the CPython team
has compiled Windows installers with every release@footnote{https://www.python.org/downloads/} for many years. These installers
are primarily intended to add a per-user installation of Python, with the
core interpreter and library being used by a single user. The installer is also
able to install for all users of a single machine, and a separate ZIP file is
available for application-local distributions.

Comme spécifié dans la 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/}, une `release' Python ne gère qu'une plateforme Windows alors que Microsoft considère la plateforme sous support étendu. Ce qui veut dire que Python 3.13 fonctionne sur Windows 8.1 et plus. Si vous avez besoin de compatibilité Windows 7, vous devez utiliser Python 3.8.

Il existe un certain nombre d'installateurs différents disponibles pour Windows, chacun avec certains avantages et inconvénients.

@ref{1d93,,L'installateur complet} contient tous les composants et est la meilleure option pour les développeurs utilisant Python pour tout type de projet.

@ref{1b74,,Le paquet Microsoft Store} est une simple installation de Python qui convient à l'exécution de scripts, de paquets et à l’utilisation d’IDLE ou d'autres environnements de développement. Il nécessite Windows 10 ou supérieur, mais peut être installé en toute sécurité sans endommager d'autres programmes. Il fournit également de nombreuses commandes pratiques pour lancer Python et ses outils.

@ref{1d94,,Les paquets nuget.org} sont des installations légères destinées aux systèmes d'intégration continue. Ils peuvent être utilisés pour créer des packages Python ou exécuter des scripts, mais ne sont pas modifiables et n'ont pas d'outils d'interface utilisateur.

@ref{1d95,,Le paquet intégrable} est un paquet minimal de Python approprié pour l'intégration dans une plus grande application.

@menu
* L'installateur complet:: 
* Le paquet Microsoft Store:: 
* Les paquets nuget.org: Les paquets nuget org. 
* Le paquet intégrable:: 
* Paquets alternatifs:: 
* Configurer Python: Configurer Python<2>. 
* Mode UTF-8:: 
* Lanceur Python pour Windows:: 
* Recherche de modules:: 
* Modules supplémentaires:: 
* Compiler Python sous Windows:: 
* Autres plateformes:: 

@end menu

@node L'installateur complet,Le paquet Microsoft Store,,Utilisation de Python sur Windows
@anchor{using/windows the-full-installer}@anchor{1d96}@anchor{using/windows windows-full}@anchor{1d93}
@subsection L'installateur complet


@menu
* Étapes d'installation:: 
* Suppression de la limitation MAX_PATH:: 
* Installation sans l'interface utilisateur:: 
* Installation sans téléchargement:: 
* Modification d'une installation:: 
* Installing Free-threaded Binaries:: 

@end menu

@node Étapes d'installation,Suppression de la limitation MAX_PATH,,L'installateur complet
@anchor{using/windows installation-steps}@anchor{1d97}
@subsubsection Étapes d'installation


Quatre installateurs Python 3.13 sont disponibles au téléchargement — deux de chaque pour les versions 32-bit et 64-bit de l'interpréteur. L'`installateur web' est léger, et téléchargera automatiquement les composants nécessaires. L'`installateur hors-ligne' inclut les composants nécessaires pour une installation par défaut et n'a besoin d'une connexion internet que pour des fonctionnalités optionnelles. Voir @ref{1d98,,Installation sans téléchargement} pour d'autres moyens d’éviter des téléchargements durant l'installation.

Après avoir lancé l'installateur, deux options s'affichent :

@image{python-figures/win_installer,,,,png}

Si vous sélectionnez « Installer Maintenant » (@code{Install Now}) :


@itemize *

@item 
Vous n'aurez `pas' besoin d'avoir les droits d'administrateur (sauf si une mise à jour de la bibliothèque d'exécution C est nécessaire ou si vous installez le @ref{5a8,,Lanceur Python pour Windows} pour tous les utilisateurs)

@item 
Python sera installé dans votre répertoire utilisateur

@item 
Le @ref{5a8,,Lanceur Python pour Windows} sera installé suivant l'option en bas de la première page

@item 
La bibliothèque standard, la suite de tests, le lanceur et `pip' seront installés

@item 
Si l'option est cochée, le dossier d'installation sera ajouté à votre 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}

@item 
Les raccourcis ne seront visibles que pour l'utilisateur actuel
@end itemize

Sélectionner « Personnaliser l’installation » (@code{Customize installation}) vous permettra de sélectionner les fonctionnalités à installer, le chemin d'installation et d'autres options ou des options post-installation. Pour installer des binaires ou symboles de débogage, vous devrez utiliser cette option.

Pour effectuer une installation pour tous les utilisateurs, vous devez sélectionner « Personnaliser l’installation ». Dans ce cas :


@itemize *

@item 
Vous pouvez avoir à donner une approbation ou des identifiants administrateur

@item 
Python sera installé dans le dossier `Program Files'

@item 
Le @ref{5a8,,Lanceur Python pour Windows} sera installé dans le dossier `Windows'

@item 
Des fonctionnalités optionnelles peuvent être sélectionnées durant l'installation

@item 
La bibliothèque standard peut être pré-compilée en code intermédiaire (`bytecode' en anglais)

@item 
Si sélectionné, le chemin d'installation sera ajouté au 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} système

@item 
Les raccourcis sont disponibles pour tous les utilisateurs
@end itemize

@node Suppression de la limitation MAX_PATH,Installation sans l'interface utilisateur,Étapes d'installation,L'installateur complet
@anchor{using/windows max-path}@anchor{c2f}@anchor{using/windows removing-the-max-path-limitation}@anchor{1d99}
@subsubsection Suppression de la limitation @code{MAX_PATH}


Historiquement les chemins sous Windows étaient limités 260 caractères. Cela impliquait que les chemins plus longs n'étaient pas résolus, et seraient une cause d'erreurs.

Dans les dernières versions de Windows, cette limitation peut être étendue à approximativement 32.000 caractères. Votre administrateur devra activer la stratégie de groupe « `Enable Win32 long paths' » ou mettre la valeur de @code{LongPathsEnabled} à @code{1} dans de registre à @code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem}.

Ceci permet à la fonction @ref{505,,open()}, au module @ref{a0,,os} et à la plupart des autres fonctionnalités utilisant des chemins d'accepter et de renvoyer des chemins plus longs que 260 caractères.

Après avoir changé l'option si-dessus, aucune configuration supplémentaire n'est requise.


Modifié dans la version 3.6: Gestion des chemins longs.


@node Installation sans l'interface utilisateur,Installation sans téléchargement,Suppression de la limitation MAX_PATH,L'installateur complet
@anchor{using/windows install-quiet-option}@anchor{5d8}@anchor{using/windows installing-without-ui}@anchor{1d9a}
@subsubsection Installation sans l'interface utilisateur


Toutes les options disponibles dans l'installateur graphique peuvent aussi être spécifiées dans l'invite de commande, permettant à des installateurs scriptés de répliquer une installation sur plusieurs machines sans interaction humaine. Ces options peuvent aussi être ajoutées sans enlever l'interface graphique pour changer les valeurs par défauts.

The following options (found by executing the installer with @code{/?}) can be
passed into the installer:


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Nom

@tab

Description

@item

/passive

@tab

to display progress without requiring user interaction

@item

/quiet

@tab

to install/uninstall without displaying any UI

@item

/simple

@tab

to prevent user customization

@item

/uninstall

@tab

to remove Python (without confirmation)

@item

/layout [directory]

@tab

to pre-download all components

@item

/log [filename]

@tab

to specify log files location

@end multitable


Toutes les autres options sont passées sous la forme @code{name=value}, ou @code{value} est normalement soit @code{0} pour désactiver une fonctionnalité, soit @code{1} pour activer une fonctionnalité, soit un chemin. Ci-dessous la liste complète des options.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Nom

@tab

Description

@tab

Valeur par défaut

@item

InstallAllUsers

@tab

Effectue une installation pour tous les utilisateurs.

@tab

0

@item

TargetDir

@tab

Le dossier d'installation

@tab

Sélection basée sur InstallAllUsers

@item

DefaultAllUsersTargetDir

@tab

Le dossier d'installation par défaut pour les installations pour tous les utilisateurs

@tab

@code{%ProgramFiles%\Python X.Y} ou @code{%ProgramFiles(x86)%\Python X.Y}

@item

DefaultJustForMeTargetDir

@tab

Le dossier d'installation par défaut pour des installations juste pour soi

@tab

@code{%LocalAppData%\Programs\Python\PythonXY} ou @code{%LocalAppData%\Programs\Python\PythonXY-32} ou @code{%LocalAppData%\Programs\Python\PythonXY-64}

@item

DefaultCustomTargetDir

@tab

Le dossier d'installation personnalisé par défaut affiché par l'interface utilisateur

@tab

(vide)

@item

AssociateFiles

@tab

Crée les associations de fichiers si le lanceur est aussi installé.

@tab

1

@item

CompileAll

@tab

Compile tous les fichiers @code{.py} en @code{.pyc}.

@tab

0

@item

PrependPath

@tab

Ajoute les dossiers @code{install} et @code{Scripts} à 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} et assigne @code{.PY} à 
@geindex PATHEXT
@geindex variable d'environnement; PATHEXT
@code{PATHEXT}

@tab

0

@item

AppendPath

@tab

Ajoute les dossiers @code{install} et @code{Scripts} à 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} et assigne @code{.PY} à 
@geindex PATHEXT
@geindex variable d'environnement; PATHEXT
@code{PATHEXT}

@tab

0

@item

Shortcuts

@tab

Crée des raccourcis pour l'interpréteur, la documentation et IDLE si installé.

@tab

1

@item

Include_doc

@tab

Installe le manuel Python

@tab

1

@item

Include_debug

@tab

Installe les binaires de débogage

@tab

0

@item

Include_dev

@tab

Installe les en-têtes et les bibliothèques de développement. L'omission de cette étape peut conduire à une installation inutilisable.

@tab

1

@item

Include_exe

@tab

Installer @code{python.exe} et les fichiers associés. L'omission de cette étape peut conduire à une installation inutilisable.

@tab

1

@item

Include_launcher

@tab

Installe le @ref{5a8,,Lanceur Python pour Windows}.

@tab

1

@item

InstallLauncherAllUsers

@tab

Installe le lanceur pour tous les utilisateurs. Nécessite que @code{Include_launcher} soit mis à @code{1}

@tab

1

@item

Include_lib

@tab

Installe la bibliothèque standard et les modules d'extension. L'omission de cette étape peut conduire à une installation inutilisable.

@tab

1

@item

Include_pip

@tab

Installe @code{pip} et @code{setuptools}

@tab

1

@item

Include_symbols

@tab

Installe les symboles de débogage (@code{*.pdb})

@tab

0

@item

Include_tcltk

@tab

Installe Tcl/Tk et IDLE

@tab

1

@item

Include_test

@tab

Installe la suite de tests de la bibliothèque standard

@tab

1

@item

Include_tools

@tab

Installe les scripts utilitaires

@tab

1

@item

LauncherOnly

@tab

Installe seulement le lanceur. Ceci écrasera la plupart des autres options.

@tab

0

@item

SimpleInstall

@tab

Désactive la plupart de l'interface d'installation

@tab

0

@item

SimpleInstallDescription

@tab

Un message personnalisé à afficher quand l'interface d'installation simplifiée est utilisée.

@tab

(vide)

@end multitable


Par exemple, pour installer silencieusement Python sur tout le système, vous pourriez utilisez la commande suivante (depuis une invite de commande administrateur) :

@example
python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0
@end example

Pour permettre à l'utilisateur d'installer facilement une copie de Python sans la suite de tests, vous pouvez proposer un raccourci avec la commande suivante. Cela affichera une page initiale simplifiée et interdira la personnalisation :

@example
python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."
@end example

(Notez qu'omettre le lanceur omet aussi les associations de fichiers, et n'est recommandé que pour les installations par utilisateur quand il y a aussi une installation complète sur le système qui a inclus de lanceur.)

Les options listées ci-dessus peuvent aussi être passées dans un fichier nommé @code{unattend.xml} à côté de l'exécutable. Ce fichier spécifie une liste d'options et de valeurs. Quand une valeur est donnée en tant qu'attribut, elle sera convertie en nombre si possible. Les valeurs données en élément texte sont toujours laissées en tant que chaînes de caractères. Ce fichier d'exemple propose les mêmes options que l'exemple précédent :

@example
<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
</Options>
@end example

@node Installation sans téléchargement,Modification d'une installation,Installation sans l'interface utilisateur,L'installateur complet
@anchor{using/windows install-layout-option}@anchor{1d98}@anchor{using/windows installing-without-downloading}@anchor{1d9b}
@subsubsection Installation sans téléchargement


Comme certaines fonctionnalités de Python ne sont pas incluses dans l'installateur initial, la sélection de certaines de ces fonctionnalités peut demander une connexion Internet. Pour éviter ce besoin, tous les composants nécessaires peuvent être téléchargés à la demande pour créer un agencement (`layout') complet qui ne demandera plus de connexion Internet indépendamment des options sélectionnées. Notez que ce téléchargement peut être plus gros que nécessaire, mais lorsqu'un un grand nombre d'installations doivent être faites, il est très utile d'avoir une copie locale.

Exécutez la commande suivante depuis l'invite de commande pour télécharger tous les fichiers requis possibles. Rappelez-vous de remplacer @code{python-3.9.0.exe} par le nom réel de votre installateur et de créer des agencements avec leurs propres dossiers pour éviter les conflits entre fichiers du même nom.

@example
python-3.9.0.exe /layout [optional target directory]
@end example

Vous pouvez aussi spécifier l'option @code{/quiet} pour masquer la progression.

@node Modification d'une installation,Installing Free-threaded Binaries,Installation sans téléchargement,L'installateur complet
@anchor{using/windows modifying-an-install}@anchor{1d9c}
@subsubsection Modification d'une installation


Une fois Python installé, vous pouvez ajouter ou supprimer des fonctionnalités depuis l'outil Windows `Programs and Features' (Programmes et Fonctionnalités). Sélectionnez la ligne @code{Python} et choisissez « Uninstall/Change » (Désinstaller/Modifier) pour ouvrir l'installateur en mode maintenance.

« Modify » vous permet d'ajouter ou d'enlever des fonctionnalités en modifiant les cases à cocher (les cases inchangées n'installeront ou ne supprimeront rien). Certaines options ne peuvent pas être modifiées dans ce mode, comme le dossier d'installation. Pour modifier ces options, vous devrez ré-installer Python entièrement.

« Repair » vérifiera tous les fichiers qui doivent être installés avec les paramètres actuels le sont, et remplacera ceux qui ont étés supprimés ou modifiés.

« Uninstall » désinstallera Python entièrement, à l'exception du @ref{5a8,,Lanceur Python pour Windows} qui à sa propre ligne dans `Programs and Features'.

@node Installing Free-threaded Binaries,,Modification d'une installation,L'installateur complet
@anchor{using/windows install-freethreaded-windows}@anchor{171}@anchor{using/windows installing-free-threaded-binaries}@anchor{1d9d}
@subsubsection Installing Free-threaded Binaries



Ajouté dans la version 3.13: (Experimental)


@cartouche
@quotation Note 
Everything described in this section is considered experimental,
and should be expected to change in future releases.
@end quotation
@end cartouche

To install pre-built binaries with free-threading enabled (see 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}), you
should select "Customize installation". The second page of options includes the
"Download free-threaded binaries" checkbox.

@image{python-figures/win_install_freethreaded,,,,png}

Selecting this option will download and install additional binaries to the same
location as the main Python install. The main executable is called
@code{python3.13t.exe}, and other binaries either receive a @code{t} suffix or a full
ABI suffix. Python source files and bundled third-party dependencies are shared
with the main install.

The free-threaded version is registered as a regular Python install with the
tag @code{3.13t} (with a @code{-32} or @code{-arm64} suffix as normal for those
platforms). This allows tools to discover it, and for the @ref{5a8,,Lanceur Python pour Windows} to
support @code{py.exe -3.13t}. Note that the launcher will interpret @code{py.exe -3}
(or a @code{python3} shebang) as "the latest 3.x install", which will prefer the
free-threaded binaries over the regular ones, while @code{py.exe -3.13} will not.
If you use the short style of option, you may prefer to not install the
free-threaded binaries at this time.

To specify the install option at the command line, use
@code{Include_freethreaded=1}. See @ref{1d98,,Installation sans téléchargement} for instructions on
pre-emptively downloading the additional binaries for offline install. The
options to include debug symbols and binaries also apply to the free-threaded
builds.

Free-threaded binaries are also available @ref{1d94,,on nuget.org}.

@node Le paquet Microsoft Store,Les paquets nuget org,L'installateur complet,Utilisation de Python sur Windows
@anchor{using/windows the-microsoft-store-package}@anchor{1d9e}@anchor{using/windows windows-store}@anchor{1b74}
@subsection Le paquet Microsoft Store



Ajouté dans la version 3.7.2.


Le paquet `Microsoft Store' est un interpréteur Python facilement installable qui est destiné principalement à une utilisation interactive, par exemple, par des étudiants.

Pour installer le paquet, assurez-vous d'avoir les dernières mises à jour de Windows 10 et de chercher dans l'application `Microsoft Store' “Python 3.13”. Assurez-vous que l'application que vous sélectionnez est publiée par la `Python Software Foundation' et installez-la.

@cartouche
@quotation Avertissement 
Python sera toujours disponible gratuitement sur le Microsoft Store. Si vous êtes invité à payer, vous n'avez pas sélectionné le bon paquet.
@end quotation
@end cartouche

Après l'installation, Python peut être lancé depuis le menu Démarrer. Il est aussi disponible à partir de n'importe quelle invite de commande ou session PowerShell en entrant @code{python}. De plus, pip et IDLE peuvent être utilisés en entrant @code{pip} ou @code{idle} . IDLE peut également être trouvé dans le menu Démarrer.

Les trois commandes sont également disponibles avec les suffixes de numéro de version, par exemple, @code{python3.exe} et @code{python3.x.exe} ainsi que @code{python.exe} (ou @code{3.x} est la version spécifique que vous souhaitez lancer, tel que 3.13). Depuis le « menu Démarrer », ouvrez « Alias d'exécution d'application » (ou « `Manage App Execution Aliases' » en anglais) pour choisir quelle version de Python est associée à quelle commande. Il est recommandé de s'assurer que @code{pip} et @code{idle} utilisent la même version de Python que la commande @code{python}.

Les environnements virtuels peuvent être créés avec @code{python -m venv} et activés et utilisés normalement.

Si vous avez installé une autre version de Python et l'avez ajoutée à votre variable d'environnement @code{PATH}, elle sera disponible en tant que @code{python.exe} plutôt que celle de la boutique Microsoft. Pour accéder à la nouvelle installation, utilisez @code{python3.exe} ou @code{python3.x.exe}.

Le lanceur @code{py.exe} va détecter cette installation Python, mais préfèrera les versions de l'installateur traditionnel.

Pour supprimer Python, depuis les paramètres Windows ouvrez `Apps and Features' (Applications et Fonctionnalités), ou bien trouvez Python dans le menu Démarrer et cliquez avec le bouton droit pour sélectionner désinstaller. La désinstallation supprimera tous les paquets que vous avez installés directement dans cette installation Python, mais ne supprimera aucun environnement virtuel

@menu
* Problèmes connus:: 

@end menu

@node Problèmes connus,,,Le paquet Microsoft Store
@anchor{using/windows known-issues}@anchor{1d9f}
@subsubsection Problèmes connus


@menu
* Redirection des données locales@comma{} du registre et des chemins temporaires: Redirection des données locales du registre et des chemins temporaires. 

@end menu

@node Redirection des données locales du registre et des chemins temporaires,,,Problèmes connus
@anchor{using/windows redirection-of-local-data-registry-and-temporary-paths}@anchor{1da0}
@subsubsection Redirection des données locales, du registre et des chemins temporaires


En raison de restrictions sur les applications Microsoft Store, les scripts Python peuvent ne pas avoir un accès en écriture complet aux emplacements partagés tels que 
@geindex TEMP
@geindex variable d'environnement; TEMP
@code{TEMP} et le registre. Au lieu de cela, il écrira sur une copie privée. Si vos scripts doivent modifier les emplacements partagés, vous devrez installer le programme d'installation complet.

At runtime, Python will use a private copy of well-known Windows folders and the registry.
For example, if the environment variable 
@geindex %APPDATA%
@geindex variable d'environnement; %APPDATA%
@code{%APPDATA%} is @code{c:\Users\<user>\AppData\},
then when writing to @code{C:\Users\<user>\AppData\Local} will write to
@code{C:\Users\<user>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\LocalCache\Local\}.

When reading files, Windows will return the file from the private folder, or if that does not exist, the
real Windows directory. For example reading @code{C:\Windows\System32} returns the contents of @code{C:\Windows\System32}
plus the contents of @code{C:\Program Files\WindowsApps\package_name\VFS\SystemX86}.

Vous pouvez trouver le chemin réel de n'importe quel fichier existant en utilisant @ref{222,,os.path.realpath()} :

@example
>>> import os
>>> test_file = 'C:\\Users\\example\\AppData\\Local\\test.txt'
>>> os.path.realpath(test_file)
'C:\\Users\\example\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\LocalCache\\Local\\test.txt'
@end example

Lors de l'écriture dans le registre Windows, les comportements suivants existent :


@itemize *

@item 
Reading from @code{HKLM\\Software} is allowed and results are merged with the @code{registry.dat} file in the package.

@item 
Writing to @code{HKLM\\Software} is not allowed if the corresponding key/value exists, i.e. modifying existing keys.

@item 
Writing to @code{HKLM\\Software} is allowed as long as a corresponding key/value does not exist in the package
and the user has the correct access permissions.
@end itemize

For more detail on the technical basis for these limitations, please consult
Microsoft's documentation on packaged full-trust apps, currently available at
docs.microsoft.com/en-us/windows/msix/desktop/desktop-to-uwp-behind-the-scenes@footnote{https://learn.microsoft.com/windows/msix/desktop/desktop-to-uwp-behind-the-scenes}

@node Les paquets nuget org,Le paquet intégrable,Le paquet Microsoft Store,Utilisation de Python sur Windows
@anchor{using/windows the-nuget-org-packages}@anchor{1da1}@anchor{using/windows windows-nuget}@anchor{1d94}
@subsection Les paquets `nuget.org'



Ajouté dans la version 3.5.2.


Le paquet `nuget.org' est un environnement Python de taille réduite destiné à être utilisé sur des systèmes d'intégration et de génération continus qui n'ont pas Python d'installé. Alors que `nuget' est “le gestionnaire de package pour .NET”, il fonctionne également parfaitement bien pour les packages contenant des outils de `build-time'.

Visitez nuget.org@footnote{https://www.nuget.org/} pour les informations les plus à jour sur l'utilisation de `nuget'. Ce qui suit est un résumé suffisant pour les développeurs Python.

L'outil de ligne de commande @code{nuget.exe} peut être téléchargé directement à partir de @code{https://aka.ms/nugetclidl}, par exemple, à l'aide de `curl' ou de PowerShell. Avec l'outil, la dernière version de Python pour les machines 64 bits ou 32 bits est installée à l'aide de :

@example
nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .
@end example

Pour sélectionner une version particulière, ajoutez un @code{-Version 3.x.y}. Le répertoire d'installation être modifié (de @code{.}), et le paquet sera installé dans un sous-répertoire. Par défaut, le sous-répertoire est nommé comme le paquet, et sans l'option @code{-ExcludeVersion}, ce nom inclura la version spécifique installée. À l'intérieur du sous-répertoire se trouve un répertoire @code{tools} qui contient l'installation Python :

@example
# Without -ExcludeVersion
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# With -ExcludeVersion
> .\python\tools\python.exe -V
Python 3.5.2
@end example

En général, les paquets `nuget' ne peuvent pas êtres mis à jour et les versions plus récentes doivent être installées côte à côte et référencées à l'aide du chemin d'accès complet. Vous pouvez également supprimer le répertoire du paquet manuellement et l'installer à nouveau. De nombreux systèmes CI le feront automatiquement s'ils ne conservent pas les fichiers entre les `builds'.

À côté du répertoire @code{tools} est un répertoire @code{build\native}. Il contient un fichier de propriétés MSBuild @code{python.props} qui peut être utilisé dans un projet C++ pour référencer l'installation de Python. L'inclusion des paramètres utilisera automatiquement les en-têtes et les bibliothèques d'importation dans votre `build'.

The package information pages on nuget.org are
www.nuget.org/packages/python@footnote{https://www.nuget.org/packages/python}
for the 64-bit version, www.nuget.org/packages/pythonx86@footnote{https://www.nuget.org/packages/pythonx86} for the 32-bit version, and
www.nuget.org/packages/pythonarm64@footnote{https://www.nuget.org/packages/pythonarm64} for the ARM64 version

@menu
* Free-threaded packages:: 

@end menu

@node Free-threaded packages,,,Les paquets nuget org
@anchor{using/windows free-threaded-packages}@anchor{1da2}
@subsubsection Free-threaded packages



Ajouté dans la version 3.13: (Experimental)


@cartouche
@quotation Note 
Everything described in this section is considered experimental,
and should be expected to change in future releases.
@end quotation
@end cartouche

Packages containing free-threaded binaries are named
python-freethreaded@footnote{https://www.nuget.org/packages/python-freethreaded}
for the 64-bit version, pythonx86-freethreaded@footnote{https://www.nuget.org/packages/pythonx86-freethreaded} for the 32-bit
version, and pythonarm64-freethreaded@footnote{https://www.nuget.org/packages/pythonarm64-freethreaded} for the ARM64
version. These packages contain both the @code{python3.13t.exe} and
@code{python.exe} entry points, both of which run free threaded.

@node Le paquet intégrable,Paquets alternatifs,Les paquets nuget org,Utilisation de Python sur Windows
@anchor{using/windows the-embeddable-package}@anchor{1da3}@anchor{using/windows windows-embeddable}@anchor{1d95}
@subsection Le paquet intégrable



Ajouté dans la version 3.5.


La distribution embarquée est un fichier ZIP contenant un environnement Python minimal. Il est destiné à agir dans le cadre d'une autre application, plutôt que d'être directement accessible par les utilisateurs finaux.

When extracted, the embedded distribution is (almost) fully isolated from the
user's system, including environment variables, system registry settings, and
installed packages. The standard library is included as pre-compiled and
optimized @code{.pyc} files in a ZIP, and @code{python3.dll}, @code{python37.dll},
@code{python.exe} and @code{pythonw.exe} are all provided. Tcl/tk (including all
dependents, such as Idle), pip and the Python documentation are not included.

@cartouche
@quotation Note 
The embedded distribution does not include the Microsoft C Runtime@footnote{https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist#visual-studio-2015-2017-2019-and-2022} and it is
the responsibility of the application installer to provide this. The
runtime may have already been installed on a user's system previously or
automatically via Windows Update, and can be detected by finding
@code{ucrtbase.dll} in the system directory.
@end quotation
@end cartouche

Les paquets tiers doivent être installés par le programme d'installation de l'application parallèlement à la distribution embarquée. L'utilisation de pip pour gérer les dépendances comme pour une installation Python régulière n'est pas prise en charge avec cette distribution, mais il reste possible d'inclure et d'utiliser pip pour les mises à jour automatiques. En général, les paquets tiers doivent être traités dans le cadre de l'application (`vendoring') afin que le développeur puisse assurer la compatibilité avec les versions plus récentes avant de fournir des mises à jour aux utilisateurs.

Les deux cas d'utilisation recommandés pour cette distribution sont décrits ci-dessous.

@menu
* Application Python:: 
* Embarquer Python:: 

@end menu

@node Application Python,Embarquer Python,,Le paquet intégrable
@anchor{using/windows python-application}@anchor{1da4}
@subsubsection Application Python


Une application écrite en Python n'exige pas nécessairement que les utilisateurs soient au courant de ce fait. La distribution embarquée peut être utilisée dans ce cas pour inclure une version privée de Python dans un package d'installation. Selon la façon dont il devrait être transparent (ou inversement, à quel point il doit paraître professionnel), il y a deux options.

L'utilisation d'un exécutable spécialisé en tant que lanceur nécessite de la programmation, mais fournit l'expérience la plus transparente pour les utilisateurs. Avec un lanceur personnalisé, il n'y a pas d'indications évidentes que le programme s'exécute sur Python : les icônes peuvent être personnalisées, les informations de la société et de la version peuvent être spécifiées, et les associations de fichiers se comportent correctement. Dans la plupart des cas, un lanceur personnalisé devrait simplement pouvoir appeler @code{Py_Main} avec une ligne de commande codée en dur.

L'approche la plus simple consiste à fournir un fichier batch ou un raccourci généré qui appelle directement le @code{python.exe} ou @code{pythonw.exe} avec les arguments de ligne de commande requis. Dans ce cas, l'application semble être Python et non son nom réel, et les utilisateurs peuvent avoir du mal à le distinguer des autres processus Python en cours d'exécution ou des associations de fichiers.

Avec cette dernière approche, les packages doivent être installés en tant que répertoires à côté de l'exécutable Python pour s'assurer qu'ils soient visibles par Python. Avec le lanceur spécialisé, les paquets peuvent être installés dans d'autres emplacements car il y a une possibilité de spécifier le chemin de recherche avant de lancer l'application.

@node Embarquer Python,,Application Python,Le paquet intégrable
@anchor{using/windows embedding-python}@anchor{1da5}
@subsubsection Embarquer Python


Les applications écrites en code natif nécessitent souvent une certaine forme de langage de `scripting', et la distribution Python intégrée peut être utilisée à cette fin. En général, la majorité de l'application est dans le code natif, qui soit invoque @code{python.exe} soit utilise directement @code{python3.dll}. Dans les deux cas, l'extraction de la distribution intégrée dans un sous-répertoire de l'installation de l'application est suffisante pour fournir un interpréteur Python chargeable.

Comme pour l'utilisation de l'application, les paquets peuvent être installés sur n'importe quel emplacement, car il est possible de spécifier des chemins de recherche avant d'initialiser l'interpréteur. Sinon, il n'y a pas de différences fondamentales entre l'utilisation de la distribution embarquée et une installation classique.

@node Paquets alternatifs,Configurer Python<2>,Le paquet intégrable,Utilisation de Python sur Windows
@anchor{using/windows alternative-bundles}@anchor{1da6}
@subsection Paquets alternatifs


À part la distribution standard CPython, il y a des paquets modifiés incluant des fonctionnalités additionnelles. La liste qui suit est une liste de versions populaires et de leurs fonctionnalités principales :


@table @asis

@item ActivePython@footnote{https://www.activestate.com/products/python/}

Installateur avec une compatibilité multiplateforme, de la documentation, et `PyWin32'

@item Anaconda@footnote{https://www.anaconda.com/download/}

Des modules scientifiques populaires (comme `numpy', `scipy' et `pandas') et le gestionnaire de paquets @code{conda}.

@item Enthought Deployment Manager@footnote{https://assets.enthought.com/downloads/edm/}

« L’environnement Python et gestionnaire de paquets de nouvelle génération ».

Auparavant, Enthought fournissait Canopy, mais celui-ci est arrivé en fin de vie en 2016@footnote{https://support.enthought.com/hc/en-us/articles/360038600051-Canopy-GUI-end-of-life-transition-to-the-Enthought-Deployment-Manager-EDM-and-Visual-Studio-Code}.

@item WinPython@footnote{https://winPython.github.io/}

Distribution spécifique à Windows avec des paquets scientifiques pré-compilés et des outils pour construire des paquets.
@end table

Notez que ces paquets peuvent ne pas inclure la dernière version de Python ou d'autres bibliothèques, et ne sont pas maintenus ni supportés par les `core devs' Python.

@node Configurer Python<2>,Mode UTF-8,Paquets alternatifs,Utilisation de Python sur Windows
@anchor{using/windows configuring-python}@anchor{1da7}
@subsection Configurer Python


Pour exécuter Python confortablement à partir d'une invite de commandes, vous pouvez envisager de modifier certaines variables d'environnement par défaut dans Windows. Bien que l'installateur offre une option pour configurer les variables @code{PATH} et @code{PATHEXT} pour vous, ce n'est fiable que pour une seule installation à l'échelle du système. Si vous utilisez régulièrement plusieurs versions de Python, pensez à utiliser le @ref{5a8,,Lanceur Python pour Windows}.

@menu
* Digression ; définition des variables d'environnement: Digression définition des variables d'environnement. 
* Trouver l'exécutable Python:: 

@end menu

@node Digression définition des variables d'environnement,Trouver l'exécutable Python,,Configurer Python<2>
@anchor{using/windows excursus-setting-environment-variables}@anchor{1da8}@anchor{using/windows setting-envvars}@anchor{1b75}
@subsubsection Digression : définition des variables d'environnement


Windows permet de configurer les variables d'environnement de façon permanente au niveau de l'utilisateur et du système, ou temporairement dans une invite de commandes.

Pour définir temporairement les variables d'environnement, ouvrez l'invite de commandes et utilisez la commande @code{set} :

@example
C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
C:\>python
@end example

Ces modifications s'appliqueront à toutes les autres commandes exécutées dans cette console et seront héritées par toutes les applications démarrées à partir de cette console.

Un nom de variable entre des signes pour cent sera remplacé par sa valeur, vous permettant d'ajouter votre nouvelle valeur au début ou à la fin. Ajouter @code{python.exe} au début de 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} est un moyen courant de s'assurer que la version correcte de Python est lancée.

Pour modifier définitivement les variables d'environnement par défaut, recherchez « modifier les variables d'environnement », via le menu démarrer, ou ouvrez « Propriétés Système », Paramètres Système Avancés et cliquez sur le bouton Variables d'Environnement. Dans cette boîte de dialogue, vous pouvez ajouter ou modifier des variables utilisateurs et systèmes. Pour modifier les variables systèmes, vous avez besoin d'un accès non restreint à votre ordinateur (c'est-à-dire aux droits d'administrateur).

@cartouche
@quotation Note 
Windows va concaténer les variables utilisateurs `après' les variables systèmes, ce qui peut provoquer des résultats inattendus lors de la modification de 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}.

La variable 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} est utilisée par toutes les versions de Python, vous ne devez donc pas configurer cette variable de façon permanente à moins qu'elle n'ajoute que du code compatible avec toutes les versions de Python installées.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://learn.microsoft.com/windows/win32/procthread/environment-variables}

Aperçu des variables d'environnement dans Windows

@item @indicateurl{https://learn.microsoft.com/windows-server/administration/windows-commands/set_1}

La commande @code{set}, pour modifier temporairement les variables d'environnement

@item @indicateurl{https://learn.microsoft.com/windows-server/administration/windows-commands/setx}

La commande @code{setx}, pour modifier de façon permanente les variables d'environnement
@end table


@node Trouver l'exécutable Python,,Digression définition des variables d'environnement,Configurer Python<2>
@anchor{using/windows finding-the-python-executable}@anchor{1da9}@anchor{using/windows windows-path-mod}@anchor{1039}
@subsubsection Trouver l'exécutable Python



Modifié dans la version 3.5.


En plus d'utiliser l'entrée du menu Démarrer automatiquement créée pour l'interpréteur Python, vous souhaiterez peut-être démarrer Python depuis l'invite de commandes. L'installateur a une option pour installer cela pour vous.

Sur la première page de l'installateur, une option intitulée « Ajouter Python au `PATH' » peut être sélectionnée pour que l'installateur ajoute l'emplacement d'installation dans le 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}. L'emplacement du dossier @code{Scripts\} y est également ajouté. Cela vous permet de taper @code{Python} pour exécuter l'interpréteur, et @code{pip} pour l'installateur de paquets. Ainsi, vous pouvez également exécuter vos scripts avec les options de ligne de commande, voir la documentation @ref{ff0,,Ligne de commande}.

Si vous n'activez pas cette option au moment de l'installation, vous pouvez toujours ré-exécuter l'installateur, sélectionner Modifier et l'activer. Vous pouvez également modifier manuellement le 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} à l'aide des instructions de @ref{1b75,,Digression ; définition des variables d'environnement}. Vous devez définir votre variable d'environnement 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} pour inclure le répertoire de votre installation Python, délimité par un point-virgule des autres entrées. Une variable d'exemple pourrait ressembler à ceci (en supposant que les deux premières entrées existaient déjà) :

@example
C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9
@end example

@node Mode UTF-8,Lanceur Python pour Windows,Configurer Python<2>,Utilisation de Python sur Windows
@anchor{using/windows utf-8-mode}@anchor{1daa}@anchor{using/windows win-utf8-mode}@anchor{1dab}
@subsection Mode UTF-8



Ajouté dans la version 3.7.


Windows utilise toujours les anciens codages pour l'encodage du système (la page de code ANSI).  Python l'utilise pour le codage par défaut des fichiers texte (par exemple @ref{2db,,locale.getencoding()}).

Cela peut poser des problèmes car l'UTF-8 est largement utilisé sur Internet et sur la plupart des systèmes Unix, y compris le WSL (`Windows Subsystem for Linux').

Vous pouvez utiliser le @ref{641,,mode UTF-8} pour changer le codage de texte par défaut en UTF-8. Vous pouvez activer le @ref{641,,mode UTF-8} via l'option de ligne de commande @code{-X utf8} ou la variable d'environnement @code{PYTHONUTF8=1}.  Voir 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8} pour activer le mode UTF-8, et @ref{1b75,,Digression ; définition des variables d'environnement} pour savoir comment modifier les variables d'environnement.

Lorsque le @ref{641,,mode UTF-8} est activé, vous pouvez toujours utiliser l’encodage système (la page de code ANSI) via le codec « `mbcs' ».

Notez que l'ajout de @code{PYTHONUTF8=1} aux variables d'environnement par défaut affectera toutes les applications Python 3.7+ sur votre système. Si vous avez des applications Python 3.7+ qui dépendent de l'encodage du système existant, il est recommandé de définir la variable d'environnement temporairement ou d'utiliser l'option de ligne de commande @code{-X utf8}.

@cartouche
@quotation Note 
même lorsque le mode UTF-8 est désactivé, Python utilise UTF-8 par défaut sur Windows pour :


@itemize *

@item 
Les E/S de la console, y compris les E/S standards (voir 
@geindex Python Enhancement Proposals; PEP 528
PEP 528@footnote{https://peps.python.org/pep-0528/} pour plus de détails).

@item 
L'@ref{525,,encodage du système de fichiers} (voir 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} pour plus de détails).
@end itemize
@end quotation
@end cartouche

@node Lanceur Python pour Windows,Recherche de modules,Mode UTF-8,Utilisation de Python sur Windows
@anchor{using/windows launcher}@anchor{5a8}@anchor{using/windows python-launcher-for-windows}@anchor{1dac}
@subsection Lanceur Python pour Windows



Ajouté dans la version 3.3.


Le lanceur Python pour Windows est un utilitaire qui facilite la recherche et l'exécution de différentes versions de Python. Il permet aux scripts (ou à la ligne de commande) d'indiquer une préférence pour une version Python spécifique, cherchera et exécutera cette version.

Contrairement à la variable 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}, le lanceur sélectionne correctement la version la plus appropriée de Python. Il préfère les installations par utilisateur sur celles du système, et les trie par version plutôt que d'utiliser la version la plus récente installée.

Le lanceur a été initialement spécifié dans 
@geindex Python Enhancement Proposals; PEP 397
PEP 397@footnote{https://peps.python.org/pep-0397/}.

@menu
* Pour commencer:: 
* Lignes Shebang:: 
* Arguments dans les lignes shebang:: 
* Personnalisation:: 
* Diagnostics:: 
* Exécution à vide:: 
* Installation à la demande:: 
* Codes de retour:: 

@end menu

@node Pour commencer,Lignes Shebang,,Lanceur Python pour Windows
@anchor{using/windows getting-started}@anchor{1dad}
@subsubsection Pour commencer


@menu
* Depuis la ligne de commande:: 
* Environnements virtuels:: 
* À partir d'un script:: 
* À partir d'associations de fichiers:: 

@end menu

@node Depuis la ligne de commande,Environnements virtuels,,Pour commencer
@anchor{using/windows from-the-command-line}@anchor{1dae}
@subsubsection Depuis la ligne de commande



Modifié dans la version 3.6.


Les installations systèmes de Python 3.3 et ultérieur placent le lanceur dans votre 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}. Le lanceur est compatible avec toutes les versions disponibles de Python, peu importe lesquelles sont installées. Pour vérifier que le lanceur est disponible, exécutez la commande suivante dans l'invite de commandes :

@example
py
@end example

Vous devriez voir se lancer la dernière version de Python installée — il peut être quitté normalement, et tous les arguments de ligne de commande supplémentaires spécifiés seront envoyés directement à Python.

Si plusieurs versions de Python sont installées (par exemple, 3.7 et 3.13), vous aurez remarqué que Python 3.13 se lance -- pour lancer Python 3.7, essayez la commande :

@example
py -3.7
@end example

Si vous voulez que la dernière version de Python 2.x que vous avez installé, essayez la commande :

@example
py -2
@end example

Si vous voyez l'erreur suivante, le lanceur n'est pas installé :

@example
'py' is not recognized as an internal or external command,
operable program or batch file.
@end example

La commande :

@example
py --list
@end example

affiche la ou les versions actuellement installées de Python.

The @code{-x.y} argument is the short form of the @code{-V:Company/Tag} argument,
which allows selecting a specific Python runtime, including those that may have
come from somewhere other than python.org. Any runtime registered by following
@geindex Python Enhancement Proposals; PEP 514
PEP 514@footnote{https://peps.python.org/pep-0514/} will be discoverable. The @code{--list} command lists all available
runtimes using the @code{-V:} format.

When using the @code{-V:} argument, specifying the Company will limit selection to
runtimes from that provider, while specifying only the Tag will select from all
providers. Note that omitting the slash implies a tag:

@example
# Select any '3.*' tagged runtime
py -V:3

# Select any 'PythonCore' released runtime
py -V:PythonCore/

# Select PythonCore's latest Python 3 runtime
py -V:PythonCore/3
@end example

The short form of the argument (@code{-3}) only ever selects from core Python
releases, and not other distributions. However, the longer form (@code{-V:3}) will
select from any.

The Company is matched on the full string, case-insensitive. The Tag is matched
on either the full string, or a prefix, provided the next character is a dot or a
hyphen. This allows @code{-V:3.1} to match @code{3.1-32}, but not @code{3.10}. Tags are
sorted using numerical ordering (@code{3.10} is newer than @code{3.1}), but are
compared using text (@code{-V:3.01} does not match @code{3.1}).

@node Environnements virtuels,À partir d'un script,Depuis la ligne de commande,Pour commencer
@anchor{using/windows virtual-environments}@anchor{1daf}
@subsubsection Environnements virtuels



Ajouté dans la version 3.5.


Si le lanceur est exécuté sans version de Python explicite et qu'un environnement virtuel (créé avec le module de la bibliothèque standard @ref{110,,venv} ou l'outil externe @code{virtualenv}) est actif, le lanceur exécute l'interpréteur de l'environnement virtuel plutôt que l'interpréteur global. Pour exécuter l'interpréteur global, désactivez l'environnement virtuel ou spécifiez explicitement la version Python globale.

@node À partir d'un script,À partir d'associations de fichiers,Environnements virtuels,Pour commencer
@anchor{using/windows from-a-script}@anchor{1db0}
@subsubsection À partir d'un script


Créons un script Python de test, créez un fichier appelé @code{hello.py} avec le contenu suivant

@example
#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))
@end example

À partir du répertoire dans lequel se trouve @code{hello.py}, exécutez la commande :

@example
py hello.py
@end example

Vous devriez voir le numéro de version du Python 2.x le plus récemment installé. Maintenant, essayez de changer la première ligne en :

@example
#! python3
@end example

La commande doit maintenant afficher les dernières informations de Python 3.x. Comme pour les exemples de ligne de commande ci-dessus, vous pouvez spécifier un qualificateur de version plus explicite. En supposant que vous avez installé Python 3.7, essayez de changer la première ligne en @code{#! python3.7} et vous devriez trouver les informations de version 3.7 affichées.

Notez que, contrairement à l'utilisation interactive, un "python" nu utilisera la dernière version de Python 2.x que vous avez installé. C'est pour la compatibilité ascendante et pour la compatibilité avec UNIX, où la commande @code{python} fait généralement référence à Python 2.

@node À partir d'associations de fichiers,,À partir d'un script,Pour commencer
@anchor{using/windows from-file-associations}@anchor{1db1}
@subsubsection À partir d'associations de fichiers


Le lanceur aurait dû être associé à des fichiers Python (des fichiers comme @code{.py}, @code{.pyw}, @code{.pyc}) lorsqu'il a été installé. Cela signifie que lorsque vous double-cliquez sur l'un de ces fichiers à partir de l'Explorateur Windows, le lanceur sera utilisé, et donc vous pouvez utiliser les mêmes installations décrites ci-dessus pour que le script spécifie la version qui doit être utilisée.

L'avantage principal de ceci est qu'un seul lanceur peut prendre en charge plusieurs versions de Python en même temps en fonction du contenu de la première ligne.

@node Lignes Shebang,Arguments dans les lignes shebang,Pour commencer,Lanceur Python pour Windows
@anchor{using/windows shebang-lines}@anchor{1db2}
@subsubsection Lignes Shebang


Si la première ligne d'un fichier de script commence par @code{#!}, elle est connue sous le nom de ligne « `shebang' ». Linux et d'autres systèmes basés sur Unix ont une prise en charge native de ces lignes et les `shebangs' sont couramment utilisés sur ces systèmes pour indiquer comment un script doit être exécuté. Ce lanceur permet aux mêmes installations d'être utilisés avec des scripts Python sur Windows et les exemples ci-dessus démontrent leur utilisation.

Pour permettre aux `shebang' dans les scripts Python d'être portables entre UNIX et Windows, ce lanceur prend en charge un certain nombre de commandes « virtuelles » pour spécifier l'interpréteur à utiliser. Les commandes virtuelles prises en charge sont :


@itemize *

@item 
@code{/usr/bin/env}

@item 
@code{/usr/bin/python}

@item 
@code{/usr/local/bin/python}

@item 
@code{python}
@end itemize

Par exemple, si la première ligne de votre script commence par

@example
#! /usr/bin/python
@end example

The default Python or an active virtual environment will be located and used.
As many Python scripts written to work on Unix will already have this line,
you should find these scripts can be used by the launcher without modification.
If you are writing a new script on Windows which you hope will be useful on
Unix, you should use one of the shebang lines starting with @code{/usr}.

Any of the above virtual commands can be suffixed with an explicit version
(either just the major version, or the major and minor version).
Furthermore the 32-bit version can be requested by adding "-32" after the
minor version. I.e. @code{/usr/bin/python3.7-32} will request usage of the
32-bit Python 3.7. If a virtual environment is active, the version will be
ignored and the environment will be used.


Ajouté dans la version 3.7: Depuis la version 3.7 du lanceur Python, il est possible de demander une version `64-bit' en utilisant le suffixe `-64'. De plus il est possible de spécifier une version majeure et une architecture sans version mineure (par exemple @code{/usr/bin/python3-64}).



Modifié dans la version 3.11: The "-64" suffix is deprecated, and now implies "any architecture that is
not provably i386/32-bit". To request a specific environment, use the new
@code{-V:@var{TAG}} argument with the complete tag.



Modifié dans la version 3.13: Virtual commands referencing @code{python} now prefer an active virtual
environment rather than searching 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}. This handles cases where
the shebang specifies @code{/usr/bin/env python3} but @code{python3.exe} is
not present in the active environment.


La forme @code{/usr/bin/env} de la ligne shebang possède une autre propriété spéciale. Avant de rechercher les interpréteurs Python installés, cette forme recherchera dans 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} un exécutable Python correspondant au nom fourni en premier argument. Cela correspond au comportement du programme Unix @code{env}, qui effectue une recherche dans 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}. Si un exécutable correspondant au premier argument de la commande @code{env} ne peut être trouvé, mais que l'argument commence par @code{python}, il sera traité comme décrit pour les autres commandes virtuelles. La variable d'environnement 
@geindex PYLAUNCHER_NO_SEARCH_PATH
@geindex variable d'environnement; PYLAUNCHER_NO_SEARCH_PATH
@code{PYLAUNCHER_NO_SEARCH_PATH} peut être définie (à n'importe quelle valeur) pour ignorer cette recherche dans 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}.

Shebang lines that do not match any of these patterns are looked up in the
@code{[commands]} section of the launcher's @ref{1db3,,.INI file}.
This may be used to handle certain commands in a way that makes sense for your
system. The name of the command must be a single argument (no spaces in the
shebang executable), and the value substituted is the full path to the
executable (additional arguments specified in the .INI will be quoted as part
of the filename).

@example
[commands]
/bin/xpython=C:\Program Files\XPython\python.exe
@end example

Any commands not found in the .INI file are treated as `Windows' executable
paths that are absolute or relative to the directory containing the script file.
This is a convenience for Windows-only scripts, such as those generated by an
installer, since the behavior is not compatible with Unix-style shells.
These paths may be quoted, and may include multiple arguments, after which the
path to the script and any additional arguments will be appended.

@node Arguments dans les lignes shebang,Personnalisation,Lignes Shebang,Lanceur Python pour Windows
@anchor{using/windows arguments-in-shebang-lines}@anchor{1db4}
@subsubsection Arguments dans les lignes `shebang'


Les lignes `shebang' peuvent également spécifier des options supplémentaires à passer à l'interpréteur Python. Par exemple, si vous avez une ligne `shebang' :

@example
#! /usr/bin/python -v
@end example

Alors, Python sera démarré avec l'option @code{-v}

@node Personnalisation,Diagnostics,Arguments dans les lignes shebang,Lanceur Python pour Windows
@anchor{using/windows customization}@anchor{1db5}
@subsubsection Personnalisation


@menu
* Personnalisation via des fichiers INI:: 
* Personnalisation des versions Python par défaut:: 

@end menu

@node Personnalisation via des fichiers INI,Personnalisation des versions Python par défaut,,Personnalisation
@anchor{using/windows customization-via-ini-files}@anchor{1db6}@anchor{using/windows launcher-ini}@anchor{1db3}
@subsubsection Personnalisation via des fichiers INI


Deux fichiers @code{.ini} seront recherchés par le lanceur - @code{py.ini} dans le répertoire de données de l'application de l'utilisateur courant (@code{%LOCALAPPDATA%} ou @code{$env:LocalAppData}) et @code{py.ini} dans le même répertoire que le lanceur. Les mêmes fichiers @code{.ini} sont utilisés à la fois pour la version `console' du lanceur (i.e. @code{py.exe}) et pour la version `windows' (i.e. @code{pyw.exe}).

La personnalisation spécifiée dans le « répertoire de l'application » aura la priorité sur celle à côté de l'exécutable, de sorte qu'un utilisateur, qui peut ne pas avoir accès en écriture au fichier @code{.ini} à côté du lanceur, peut substituer des commandes dans ce fichier @code{.ini} global)

@node Personnalisation des versions Python par défaut,,Personnalisation via des fichiers INI,Personnalisation
@anchor{using/windows customizing-default-python-versions}@anchor{1db7}
@subsubsection Personnalisation des versions Python par défaut


Dans certains cas, un qualificateur de version peut être inclus dans une commande pour dicter quelle version de Python sera utilisée par la commande. Un qualificateur de version commence par un numéro de version majeure et peut éventuellement être suivi d'un point (@code{.}) et d'un spécificateur de version secondaire. De plus il est possible de préciser si une implémentation 32 ou 64 bit doit être demandée en ajoutant `-32' ou `-64'.

Par exemple, une ligne `shebang' valant @code{#!python} n'a pas de qualificateur de version, tandis que @code{#!python3} a un qualificateur de version qui ne spécifie qu'une version majeure.

Si aucun qualificateur de version n'est trouvé dans une commande, la variable d'environnement 
@geindex PY_PYTHON
@geindex variable d'environnement; PY_PYTHON
@code{PY_PYTHON} peut être définie pour spécifier le qualificateur de version par défaut. Si non définie, la valeur par défaut est @code{3}. La variable peut spécifier n’importe quelle valeur qui peut être passée dans la ligne de commande telle que @code{3}, @code{3.7}, @code{3.7-32} ou @code{3.7-64}. (Notez que l’option `-64' est seulement disponible avec le lanceur inclus avec Python 3.7 ou plus récent.)

Si aucun qualificateur de version mineure n'est trouvé, la variable d'environnement @code{PY_PYTHON@{major@}} (où @code{@{major@}} est le qualificateur de version principale actuelle tel que déterminé ci-dessus) peut être définie pour spécifier la version complète. Si aucune option de ce type n'est trouvée, le lanceur énumérera les versions de Python installées et utilisera la dernière version mineure trouvée pour la version principale, qui est probablement la plus récemment installée dans cette famille.

Sur Windows 64-bits avec les implémentations 32-bits et 64-bits de la même version Python (@code{major.minor}) installée, la version 64-bit est toujours préférée. Cela est vrai pour les implémentations 32-bits et 64-bits du lanceur – un lanceur 32-bits préfère exécuter une installation Python de 64-bits de la version spécifiée si elle est disponible. Le comportement du lanceur est donc prévisible en sachant seulement quelles versions sont installées sur le PC et sans tenir compte de l'ordre dans lequel ils ont été installés (c.-à-d. sans savoir si une version 32 ou 64-bit de Python et le lanceur correspondant a été installé en dernier). Comme indiqué ci-dessus, un suffixe optionnel @code{-32} ou @code{-64} peut être utilisé sur un spécificateur de version pour modifier ce comportement.

Exemples :


@itemize *

@item 
Si aucune option pertinente n'est définie, les commandes @code{python} et @code{python2} utiliseront la dernière version de Python 2.x installée et la commande @code{python3} utilisera le dernier Python 3.x installé.

@item 
La commande @code{python3.7} ne consulte aucune option du tout car les versions sont entièrement spécifiées.

@item 
Si @code{PY_PYTHON=3}, les commandes @code{python} et @code{python3} utiliseront la dernière version de Python 3 installée.

@item 
Si @code{PY_PYTHON=3.7-32}, la commande @code{python} utilisera l'implémentation 32-bits de 3.7 alors que la commande @code{python3} utilisera le dernier Python installé (`PY_PYTHON' n'a pas été considéré du tout comme une version majeure a été spécifiée.)

@item 
Si @code{PY_PYTHON=3} et @code{PY_PYTHON3=3.7}, les commandes @code{python} et @code{python3} utiliseront spécifiquement 3.7
@end itemize

En plus des variables d'environnement, les mêmes paramètres peuvent être configurés dans le @code{.INI} utilisé par le lanceur. La section dans le fichier INI est appelée @code{[defaults]} et le nom de la clé sera le même que les variables d'environnement sans le préfixe @code{PY_} principal (et notez que les noms de clés dans le fichier `INI' sont insensibles à la case.) Le contenu d'une variable d'environnement remplacera les éléments spécifiés dans le fichier `INI'.

Par exemple :


@itemize *

@item 
Le paramètre @code{PY_PYTHON=3.7} équivaut au fichier `INI' contenant :
@end itemize

@example
[defaults]
python=3.7
@end example


@itemize *

@item 
Le paramètre @code{PY_PYTHON=3} et @code{PY_PYTHON3=3.7} équivaut au fichier `INI' contenant :
@end itemize

@example
[defaults]
python=3
python3=3.7
@end example

@node Diagnostics,Exécution à vide,Personnalisation,Lanceur Python pour Windows
@anchor{using/windows diagnostics}@anchor{1db8}
@subsubsection Diagnostics


Si une variable d'environnement 
@geindex PYLAUNCHER_DEBUG
@geindex variable d'environnement; PYLAUNCHER_DEBUG
@code{PYLAUNCHER_DEBUG} est définie (à n'importe quelle valeur), le lanceur affiche des informations de diagnostic sur `stderr' (c'est-à-dire sur la console). Bien que ces informations parviennent à être en même temps nombreuses et concises, elles devraient vous permettre de voir quelles versions de Python ont été trouvées, pourquoi une version particulière a été choisie et la ligne de commande exacte utilisée pour exécuter le Python cible.

@node Exécution à vide,Installation à la demande,Diagnostics,Lanceur Python pour Windows
@anchor{using/windows dry-run}@anchor{1db9}
@subsubsection Exécution à vide


Si une variable d'environnement 
@geindex PYLAUNCHER_DRYRUN
@geindex variable d'environnement; PYLAUNCHER_DRYRUN
@code{PYLAUNCHER_DRYRUN} est définie (à n'importe quelle valeur), le lanceur affiche la commande qu'il aurait exécutée, mais ne lance pas réellement Python. Cela peut être utile pour les outils qui souhaitent utiliser le lanceur pour détecter puis lancer Python directement. Notez que la commande écrite sur la sortie standard est toujours codée en UTF-8 et peut ne pas s'afficher correctement dans la console.

@node Installation à la demande,Codes de retour,Exécution à vide,Lanceur Python pour Windows
@anchor{using/windows install-on-demand}@anchor{1dba}
@subsubsection Installation à la demande


Si une variable d'environnement 
@geindex PYLAUNCHER_ALLOW_INSTALL
@geindex variable d'environnement; PYLAUNCHER_ALLOW_INSTALL
@code{PYLAUNCHER_ALLOW_INSTALL} est définie (à n'importe quelle valeur) et que la version de Python demandée n'est pas installée mais est disponible sur le Microsoft Store, le lanceur tente de l'installer. Cela peut nécessiter une intervention de l'utilisateur et il faudra peut-être exécuter à nouveau la commande.

Une variable supplémentaire 
@geindex PYLAUNCHER_ALWAYS_INSTALL
@geindex variable d'environnement; PYLAUNCHER_ALWAYS_INSTALL
@code{PYLAUNCHER_ALWAYS_INSTALL} oblige le lanceur à toujours essayer d'installer Python, même s'il est détecté. Ceci est principalement destiné aux tests (et doit être utilisé avec 
@geindex PYLAUNCHER_DRYRUN
@geindex variable d'environnement; PYLAUNCHER_DRYRUN
@code{PYLAUNCHER_DRYRUN}).

@node Codes de retour,,Installation à la demande,Lanceur Python pour Windows
@anchor{using/windows return-codes}@anchor{1dbb}
@subsubsection Codes de retour


Les codes de retour suivants peuvent être renvoyés par le lanceur Python. Malheureusement, il n'y a aucun moyen de les distinguer du code de sortie de Python lui-même.

Les noms des codes sont tels qu'utilisés dans les sources et ne sont donnés qu'à titre de référence. Il n'y a aucun moyen d'y accéder ou de les résoudre en dehors de la lecture de cette page. Les entrées sont classées par ordre alphabétique des noms.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Nom

@tab

Valeur

@tab

Description

@item

RC_BAD_VENV_CFG

@tab

107

@tab

@code{pyvenv.cfg} a été trouvé mais est corrompu.

@item

RC_CREATE_PROCESS

@tab

101

@tab

Échec du lancement de Python.

@item

RC_INSTALLING

@tab

111

@tab

Une installation a commencé, mais la commande doit être relancée après qu'elle a terminé.

@item

RC_INTERNAL_ERROR

@tab

109

@tab

Erreur non prévue. Merci de remonter un bogue.

@item

RC_NO_COMMANDLINE

@tab

108

@tab

Le système d'exploitation n'a pas fourni de ligne de commande.

@item

RC_NO_PYTHON

@tab

103

@tab

Impossible de trouver la version demandée.

@item

RC_NO_VENV_CFG

@tab

106

@tab

@code{pyvenv.cfg} est requis mais n'a pas été trouvé.

@end multitable


@node Recherche de modules,Modules supplémentaires,Lanceur Python pour Windows,Utilisation de Python sur Windows
@anchor{using/windows finding-modules}@anchor{1dbc}@anchor{using/windows windows-finding-modules}@anchor{c0f}
@subsection Recherche de modules


Ces notes complètent la description de @ref{1bee,,The initialization of the sys.path module search path} avec des notes Windows détaillées.

Lorsque aucun fichier @code{._pth} n'est trouvé, voilà comment @ref{3ab,,sys.path} est construit sur Windows :


@itemize *

@item 
Une entrée vide est ajoutée au début, qui correspond au répertoire courant.

@item 
Si la variable d'environnement 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} existe, comme décrit dans @ref{5db,,Variables d'environnement}, ses entrées sont ajoutées ensuite. Notez que sur Windows, les chemins d'accès de cette variable doivent être séparés par des points-virgules, pour les distinguer des deux points utilisés dans les identificateurs de lecteur (@code{C:\} etc.).

@item 
Des "chemins d'accès d'application" supplémentaires peuvent être ajoutés dans le registre en tant que sous-clés de @code{\SOFTWARE\Python\PythonCore@{version@}\PythonPath} sous les ruches @code{HKEY_CURRENT_USER} et @code{HKEY_LOCAL_MACHINE}. Les sous-clés qui ont des chaînes de chemin délimitées par des points-virgules comme valeur par défaut entraînent l'ajout de chaque chemin d'accès à @ref{3ab,,sys.path}. (Notez que tous les installateurs connus utilisent seulement HKLM, donc HKCU est généralement vide.)

@item 
Si la variable d'environnement 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} est définie, elle est supposée comme "Python Home". Sinon, le chemin de l'exécutable principal de Python est utilisé pour chercher un "fichier de repère" (soit @code{Lib\os.py} ou @code{pythonXY.zip}) pour déduire le "Python Home". Si un "Python Home" est trouvé, les sous-répertoires correspondants ajoutés à @ref{3ab,,sys.path} (@code{Lib}, @code{plat-win}, etc) sont basés sur ce dossier. Sinon, le chemin d'accès Python principal est construit à partir du PythonPath stocké dans le registre.

@item 
Si le "Python Home" ne peut pas être trouvé, 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} n'est pas spécifié dans l'environnement et aucune entrée de registre ne peut être trouvée, un chemin par défaut avec des entrées relatives est utilisé (par exemple @code{.\Lib} ; @code{.\plat-win}, etc.).
@end itemize

Si un fichier @code{pyvenv.cfg} se trouve à côté de l'exécutable principal ou dans le répertoire un niveau au-dessus de l'exécutable, les variantes suivantes s'appliquent :


@itemize *

@item 
Si @code{home} est un chemin absolu et 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} n'est pas défini, ce chemin d'accès est utilisé au lieu du chemin d'accès à l'exécutable principal lors de la déduction de l'emplacement du @code{home}.
@end itemize

Le résultat final de tout ceci est :


@itemize *

@item 
Lors de l'exécution de @code{python.exe}, ou tout autre @code{.exe} dans le répertoire principal de Python (soit une version installée, soit directement à partir du répertoire PCbuild), le chemin principal est déduit et les chemins d'accès principaux dans le Registre sont ignorés. D'autres "chemins d'application" dans le registre sont toujours lus.

@item 
Lorsque Python est hébergé dans un autre fichier @code{.exe} (répertoire différent, intégré via COM, etc.), le "Python Home" ne sera pas déduit, de sorte que le chemin d'accès principal du registre est utilisé. D'autres "chemins d'application" dans le registre sont toujours lus.

@item 
Si Python ne peut pas trouver son "home" et il n'y a pas de valeur de registre (`.exe' figé, une installation très étrange) vous obtenez un chemin d'accès avec certains chemins par défaut, mais relatif.
@end itemize

Pour ceux qui veulent intégrer Python dans leur application ou leur distribution, les conseils suivants empêcheront les conflits avec d'autres installations :


@itemize *

@item 
Incluez un fichier @code{._pth} à côté de votre exécutable contenant les répertoires à inclure. Ceci ignorera les chemins répertoriés dans le registre et les variables d'environnement, et ignorera également @ref{c6,,site} à moins que @code{import site} soit listé.

@item 
If you are loading @code{python3.dll} or @code{python37.dll} in your own
executable, explicitly set @ref{399,,PyConfig.module_search_paths} before
@ref{3bc,,Py_InitializeFromConfig()}.

@item 
Effacer et/ou écraser 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} et configurez 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} avant de lancer le @code{python.exe} de votre application.

@item 
Si vous ne pouvez pas utiliser les suggestions précédentes (par exemple, vous êtes une distribution qui permet aux gens d'exécuter @code{python.exe} directement), assurez-vous que le point de repère @code{Lib\os.py} existe dans votre répertoire d'installation. (Notez qu'il ne sera pas détecté à l'intérieur d'un fichier ZIP, mais un fichier ZIP correctement nommé sera détecté à la place.)
@end itemize

Ceux-ci garantiront que les fichiers d'une installation à l'échelle du système n'auront pas la priorité sur la copie de la bibliothèque standard livrée avec votre application. Sinon, vos utilisateurs pourraient rencontrer des problèmes en utilisant votre application. Notez que la première suggestion est la meilleure, car les autres peuvent encore être sensibles aux chemins non-standard dans le registre et le `site-packages' utilisateur.


Modifié dans la version 3.6: Add @code{._pth} file support and removes @code{applocal} option from
@code{pyvenv.cfg}.



Modifié dans la version 3.6: Add @code{python`XX'.zip} as a potential landmark when directly adjacent
to the executable.



Obsolète depuis la version 3.6: Modules specified in the registry under @code{Modules} (not @code{PythonPath})
may be imported by @ref{d18,,importlib.machinery.WindowsRegistryFinder}.
This finder is enabled on Windows in 3.6.0 and earlier, but may need to
be explicitly added to @ref{d19,,sys.meta_path} in the future.


@node Modules supplémentaires,Compiler Python sous Windows,Recherche de modules,Utilisation de Python sur Windows
@anchor{using/windows additional-modules}@anchor{1dbd}
@subsection Modules supplémentaires


Même si Python a l'ambition d'être portable parmi toutes les plates-formes, il existe des fonctionnalités propres à Windows. Certains modules, à la fois dans la bibliothèque standard et externe, et des exemples existent pour utiliser ces fonctionnalités.

Les modules standard de Windows sont documentés dans @ref{1dbe,,Services spécifiques à MS Windows}.

@menu
* PyWin32:: 
* cx_Freeze:: 

@end menu

@node PyWin32,cx_Freeze,,Modules supplémentaires
@anchor{using/windows pywin32}@anchor{1dbf}
@subsubsection PyWin32


The PyWin32@footnote{https://pypi.org/project/PyWin32/} module by Mark Hammond
is a collection of modules for advanced Windows-specific support.  This includes
utilities for:


@itemize *

@item 
Component Object Model@footnote{https://learn.microsoft.com/windows/win32/com/component-object-model--com--portal}
(COM)

@item 
Appels à l'API Win32

@item 
Registre

@item 
Journal d'événement

@item 
Microsoft Foundation Classes@footnote{https://learn.microsoft.com/cpp/mfc/mfc-desktop-applications}
(MFC) user interfaces
@end itemize

PythonWin@footnote{http://web.archive.org/web/20060524042422/http://www.python.org/windows/pythonwin/} est un exemple d'application MFC livrée avec PyWin32. Il s'agit d'un IDE embarqué avec débogueur intégré.


@subsubheading Voir aussi



@table @asis

@item Win32 How Do I...?@footnote{https://timgolden.me.uk/python/win32_how_do_i.html}

par Tim Golden

@item Python and COM@footnote{https://www.boddie.org.uk/python/COM.html}

par David et Paul Boddie
@end table


@node cx_Freeze,,PyWin32,Modules supplémentaires
@anchor{using/windows cx-freeze}@anchor{1dc0}
@subsubsection cx_Freeze


cx_Freeze@footnote{https://cx-freeze.readthedocs.io/en/latest/}
wraps Python scripts into executable Windows programs
(@code{`*'.exe} files).  When you have done this, you can distribute your
application without requiring your users to install Python.

@node Compiler Python sous Windows,Autres plateformes,Modules supplémentaires,Utilisation de Python sur Windows
@anchor{using/windows compiling-python-on-windows}@anchor{1dc1}
@subsection Compiler Python sous Windows


Si vous voulez compiler CPython vous-même, la première chose à faire est obtenir la source@footnote{https://www.python.org/downloads/source/}. Vous pouvez télécharger soit la source de la dernière version ou tout simplement prendre un checkout@footnote{https://devguide.python.org/setup/#get-the-source-code}.

L'arborescence source contient une solution de compilation et des fichiers projet pour Microsoft Visual Studio, qui est le compilateur utilisé pour générer les versions officielles de Python. Ces fichiers se trouvent dans le répertoire @code{PCbuild}.

Consultez @code{PC/readme.txt} pour des informations générales sur le processus de construction.

Pour les modules d'extension, consultez @ref{1dc2,,Construire des extensions C et C++ sur Windows}.

@node Autres plateformes,,Compiler Python sous Windows,Utilisation de Python sur Windows
@anchor{using/windows other-platforms}@anchor{1dc3}
@subsection Autres plateformes


Avec le développement continu de Python, certaines plateformes qui étaient auparavant prises en charge ne sont plus prises en charge (en raison du manque d'utilisateurs ou de développeurs). Voir 
@geindex Python Enhancement Proposals; PEP 11
PEP 11@footnote{https://peps.python.org/pep-0011/} pour plus de détails sur toutes les plateformes non prises en charge.


@itemize *

@item 
Windows CE@footnote{https://pythonce.sourceforge.net/} n’est plus pris en charge @indicateurl{https://github.com/python/cpython/issues/71542} depuis Python 3 (s’il l’a jamais été).

@item 
Le programme d’installation de Cygwin@footnote{https://cygwin.com/} propose d’installer également l’interpréteur Python@footnote{https://cygwin.com/packages/summary/python3.html}.
@end itemize

Voir Python pour Windows@footnote{https://www.python.org/downloads/windows/} pour des instructions détaillées sur les plateformes avec installateurs pré-compilés.

@node Using Python on macOS,Using Python on Android,Utilisation de Python sur Windows,Installation et utilisation de Python
@anchor{using/mac doc}@anchor{1dc4}@anchor{using/mac using-on-mac}@anchor{1dc5}@anchor{using/mac using-python-on-macos}@anchor{1dc6}
@section Using Python on macOS


This document aims to give an overview of macOS-specific behavior you should
know about to get started with Python on Mac computers.
Python on a Mac running macOS is very similar to Python on other Unix-derived platforms,
but there are some differences in installation and some features.

There are various ways to obtain and install Python for macOS.
Pre-built versions of the most recent versions of Python are available
from a number of distributors. Much of this document describes use of
the Pythons provided by the CPython release team for download from
the python.org website@footnote{https://www.python.org/downloads/}. See
@ref{1dc7,,Alternative Distributions} for some other options.
@anchor{using/mac getting-osx}@anchor{1dc8}
@menu
* Using Python for macOS from python.org: Using Python for macOS from python org. 
* Alternative Distributions:: 
* Installation de paquets Python additionnels:: 
* GUI Programming:: 
* Sujets avancés:: 
* Autres ressources:: 

@end menu

@node Using Python for macOS from python org,Alternative Distributions,,Using Python on macOS
@anchor{using/mac getting-and-installing-macpython}@anchor{1dc9}@anchor{using/mac using-python-for-macos-from-python-org}@anchor{1dca}
@subsection Using Python for macOS from @code{python.org}


@menu
* Étapes d'installation: Étapes d'installation<2>. 
* Comment exécuter un script Python:: 

@end menu

@node Étapes d'installation<2>,Comment exécuter un script Python,,Using Python for macOS from python org
@anchor{using/mac installation-steps}@anchor{1dcb}
@subsubsection Étapes d'installation


For current Python versions@footnote{https://www.python.org/downloads/}
(other than those in @code{security} status), the release team produces a
`Python for macOS' installer package for each new release.
A list of available installers
is available here@footnote{https://www.python.org/downloads/macos/}.
We recommend using the most recent supported Python version where possible.
Current installers provide a
universal2 binary@footnote{https://en.wikipedia.org/wiki/Universal_binary} build
of Python which runs natively on all Macs (Apple Silicon and Intel) that are
supported by a wide range of macOS versions,
currently typically from at least `macOS 10.13 High Sierra' on.

The downloaded file is a standard macOS installer package file (@code{.pkg}).
File integrity information (checksum, size, sigstore signature, etc) for each file is included
on the release download page. Installer packages and their contents are signed and notarized
with @code{Python Software Foundation} Apple Developer ID certificates
to meet macOS Gatekeeper requirements@footnote{https://support.apple.com/en-us/102445}.

For a default installation, double-click on the downloaded installer package file.
This should launch the standard macOS Installer app and display the first of several
installer windows steps.

@image{python-figures/mac_installer_01_introduction,,,,png}

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 @code{/Applications/Python 3.13/} and available to read anytime.

@image{python-figures/mac_installer_02_readme,,,,png}

Clicking on `Continue' proceeds to display the license for Python and for
other included software. You will then need to `Agree' to the license terms
before proceeding to the next step. This license file will also be installed
and available to be read later.

@image{python-figures/mac_installer_03_license,,,,png}

After the license terms are accepted, the next step is the `Installation Type'
display. For most uses, the standard set of installation operations is appropriate.

@image{python-figures/mac_installer_04_installation_type,,,,png}

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,
see @ref{172,,Installing Free-threaded Binaries}.

@image{python-figures/mac_installer_05_custom_install,,,,png}

In either case, clicking `Install' will begin the install process by asking
permission to install new software. A macOS user name with @code{Administrator} privilege
is needed as the installed Python will be available to all users of the Mac.

When the installation is complete, the `Summary' window will appear.

@image{python-figures/mac_installer_06_summary,,,,png}

Double-click on the @code{Install Certificates.command}
icon or file in the @code{/Applications/Python 3.13/} window to complete the
installation.

@image{python-figures/mac_installer_07_applications,,,,png}

This will open a temporary @code{Terminal} shell window that
will use the new Python to download and install SSL root certificates
for its use.

@image{python-figures/mac_installer_08_install_certificates,,,,png}

If @code{Successfully installed certifi} and @code{update complete} appears
in the terminal window, the installation is complete.
Close this terminal window and the installer window.

A default install will include:


@itemize *

@item 
A @code{Python 3.13} folder in your @code{Applications} folder. In here
you find @code{IDLE}, the development environment that is a standard part of official
Python distributions; and @code{Python Launcher}, which handles double-clicking Python
scripts from the macOS Finder@footnote{https://support.apple.com/en-us/HT201732}.

@item 
A framework @code{/Library/Frameworks/Python.framework}, which includes the
Python executable and libraries. The installer adds this location to your shell
path. To uninstall Python, you can remove these three things.
Symlinks to the Python executable are placed in @code{/usr/local/bin/}.
@end itemize

@cartouche
@quotation Note 
Recent versions of macOS include a @code{python3} command in @code{/usr/bin/python3}
that links to a usually older and incomplete version of Python provided by and for use by
the Apple development tools, @code{Xcode} or the @code{Command Line Tools for Xcode}.
You should never modify or attempt to delete this installation, as it is
Apple-controlled and is used by Apple-provided or third-party software.  If
you choose to install a newer Python version from @code{python.org}, you will have
two different but functional Python installations on your computer that
can co-exist. The default installer options should ensure that its @code{python3}
will be used instead of the system @code{python3}.
@end quotation
@end cartouche

@node Comment exécuter un script Python,,Étapes d'installation<2>,Using Python for macOS from python org
@anchor{using/mac how-to-run-a-python-script}@anchor{1dcc}
@subsubsection Comment exécuter un script Python


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 @code{python3.13} or @code{python3} optionally
followed by one or more command line options (described in @ref{194d,,Ligne de commande et environnement}).
The Python tutorial also has a useful section on
@ref{16e,,using Python interactively from a shell}.

You can also invoke the interpreter through an integrated
development environment.
@ref{ffe,,IDLE} is a basic editor and interpreter environment
which is included with the standard distribution of Python.
@code{IDLE} includes a Help menu that allows you to access Python documentation. If you
are completely new to Python, you can read the tutorial introduction
in that document.

There are many other editors and IDEs available, see @ref{1dcd,,Éditeurs et IDEs}
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:

@quotation

@code{python3.13} @code{myscript.py}
@end quotation

To run your script from the Finder, you can either:


@itemize *

@item 
Drag it to @code{Python Launcher}.

@item 
Select @code{Python Launcher} as the default application to open your
script (or any @code{.py} script) through the Finder Info window and double-click it.
@code{Python Launcher} has various preferences to control how your script is
launched. Option-dragging allows you to change these for one invocation, or use
its @code{Preferences} menu to change things globally.
@end itemize

Be aware that running the script directly from the macOS Finder might
produce different results than when running from a terminal window as
the script will not be run in the usual shell environment including
any setting of environment variables in shell profiles.
And, as with any other script or program,
be certain of what you are about to run.

@node Alternative Distributions,Installation de paquets Python additionnels,Using Python for macOS from python org,Using Python on macOS
@anchor{using/mac alternative-bundles}@anchor{1dc7}@anchor{using/mac alternative-distributions}@anchor{1dce}
@subsection Alternative Distributions


Besides the standard @code{python.org} for macOS installer, there are third-party
distributions for macOS that may include additional functionality.
Some popular distributions and their key features:


@table @asis

@item ActivePython@footnote{https://www.activestate.com/products/python/}

Installer with multi-platform compatibility, documentation

@item Anaconda@footnote{https://www.anaconda.com/download/}

Popular scientific modules (such as numpy, scipy, and pandas) and the
@code{conda} package manager.

@item Homebrew@footnote{https://brew.sh}

Package manager for macOS including multiple versions of Python and many
third-party Python-based packages (including numpy, scipy, and pandas).

@item MacPorts@footnote{https://www.macports.org}

Another package manager for macOS including multiple versions of Python and many
third-party Python-based packages. May include pre-built versions of Python and
many packages for older versions of macOS.
@end table

Note that distributions might not include the latest versions of Python or
other libraries, and are not maintained or supported by the core Python team.

@node Installation de paquets Python additionnels,GUI Programming,Alternative Distributions,Using Python on macOS
@anchor{using/mac installing-additional-python-packages}@anchor{1dcf}@anchor{using/mac mac-package-manager}@anchor{1dd0}
@subsection Installation de paquets Python additionnels


Refer to the Python Packaging User Guide@footnote{https://packaging.python.org/en/latest/tutorials/installing-packages/} for more information.
@anchor{using/mac osx-gui-scripts}@anchor{1dd1}
@node GUI Programming,Sujets avancés,Installation de paquets Python additionnels,Using Python on macOS
@anchor{using/mac gui-programming}@anchor{1dd2}@anchor{using/mac gui-programming-on-the-mac}@anchor{1dd3}
@subsection GUI Programming


Il y a plusieurs options pour construire des applications avec interface graphique sur le Mac avec Python.

The standard Python GUI toolkit is @ref{ef,,tkinter}, based on the cross-platform
Tk toolkit (@indicateurl{https://www.tcl.tk}). A macOS-native version of Tk is included with
the installer.

`PyObjC' is a Python binding to Apple's Objective-C/Cocoa framework.
Information on PyObjC is available from pyobjc@footnote{https://pypi.org/project/pyobjc/}.

A number of alternative macOS GUI toolkits are available including:


@itemize *

@item 
PySide@footnote{https://www.qt.io/qt-for-python}: Official Python bindings to the
Qt GUI toolkit@footnote{https://wiki.qt.io/Qt_for_Python}.

@item 
PyQt@footnote{https://riverbankcomputing.com/software/pyqt/}: Alternative
Python bindings to Qt.

@item 
Kivy@footnote{https://kivy.org}: A cross-platform GUI toolkit that supports
desktop and mobile platforms.

@item 
Toga@footnote{https://toga.readthedocs.io}: Part of the BeeWare Project@footnote{https://beeware.org}; supports desktop, mobile, web and console apps.

@item 
wxPython@footnote{https://wxpython.org}: A cross-platform toolkit that
supports desktop operating systems.
@end itemize

@node Sujets avancés,Autres ressources,GUI Programming,Using Python on macOS
@anchor{using/mac advanced-topics}@anchor{1dd4}
@subsection Sujets avancés


@menu
* Installing Free-threaded Binaries: Installing Free-threaded Binaries<2>. 
* Installing using the command line:: 
* Distributing Python Applications:: 
* App Store Compliance:: 

@end menu

@node Installing Free-threaded Binaries<2>,Installing using the command line,,Sujets avancés
@anchor{using/mac install-freethreaded-macos}@anchor{172}@anchor{using/mac installing-free-threaded-binaries}@anchor{1dd5}
@subsubsection Installing Free-threaded Binaries



Ajouté dans la version 3.13: (Experimental)


@cartouche
@quotation Note 
Everything described in this section is considered experimental,
and should be expected to change in future releases.
@end quotation
@end cartouche

The @code{python.org} @ref{1dc9,,Python for macOS}
installer package can optionally install an additional build of
Python 3.13 that supports 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}, the experimental free-threading feature
(running with the @ref{147,,global interpreter lock} disabled).
Check the release page on @code{python.org} for possible updated information.

Because this feature is still considered experimental, the support for it
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.

@image{python-figures/mac_installer_09_custom_install_free_threaded,,,,png}

If the box next to the `Free-threaded Python' package name is checked,
a separate @code{PythonT.framework} will also be installed
alongside the normal @code{Python.framework} in @code{/Library/Frameworks}.
This configuration allows a free-threaded Python 3.13 build to co-exist
on your system with a traditional (GIL only) Python 3.13 build with
minimal risk while installing or testing. This installation layout is itself
experimental and is subject to change in future releases.

Known cautions and limitations:


@itemize -

@item 
The `UNIX command-line tools' package, which is selected by default,
will install links in @code{/usr/local/bin} for @code{python3.13t},
the free-threaded interpreter, and @code{python3.13t-config},
a configuration utility which may be useful for package builders.
Since @code{/usr/local/bin} is typically included in your shell @code{PATH},
in most cases no changes to your @code{PATH} environment variables should
be needed to use @code{python3.13t}.

@item 
For this release, the `Shell profile updater' package and the
@code{Update Shell Profile.command} in @code{/Applications/Python 3.13/}
do not support the free-threaded package.

@item 
The free-threaded build and the traditional build have separate search
paths and separate @code{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 @code{pip} for use
with @code{python3.13t}.


@itemize -

@item 
To install a package using @code{pip} without a @code{venv}:

@quotation

@code{python3.13t} @code{-m pip install <package_name>}
@end quotation
@end itemize

@item 
When working with multiple Python environments, it is usually safest and easiest
to @ref{1c8b,,create and use virtual environments}.
This can avoid possible command name conflicts and confusion about which Python is in use:

@quotation

@code{python3.13t} @code{-m venv <venv_name>}
@end quotation

then @code{activate}.

@item 
To run a free-threaded version of IDLE:

@quotation

@code{python3.13t} @code{-m idlelib}
@end quotation

@item 
The interpreters in both builds respond to the same
@ref{5db,,PYTHON environment variables}
which may have unexpected results, for example, if you have @code{PYTHONPATH}
set in a shell profile. If necessary, there are
@ref{1cb5,,command line options} like @code{-E}
to ignore these environment variables.

@item 
The free-threaded build links to the third-party shared libraries,
such as @code{OpenSSL} and @code{Tk}, installed in the traditional framework.
This means that both builds also share one set of trust certificates
as installed by the @code{Install Certificates.command} script,
thus it only needs to be run once.

@item 
If you cannot depend on the link in @code{/usr/local/bin} pointing to the
@code{python.org} free-threaded @code{python3.13t} (for example, if you want
to install your own version there or some other distribution does),
you can explicitly set your shell @code{PATH} environment variable to
include the @code{PythonT} framework @code{bin} directory:

@example
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"
@end example

The traditional framework installation by default does something similar,
except for @code{Python.framework}. Be aware that having both framework @code{bin}
directories in @code{PATH} can lead to confusion if there are duplicate names
like @code{python3.13} in both; which one is actually used depends on the order
they appear in @code{PATH}. The @code{which python3.x} or @code{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 @code{alias} to the desired interpreter, like:

@example
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"
@end example
@end itemize

@node Installing using the command line,Distributing Python Applications,Installing Free-threaded Binaries<2>,Sujets avancés
@anchor{using/mac installing-using-the-command-line}@anchor{1dd6}
@subsubsection Installing using the command line


If you want to use automation to install the @code{python.org} installer package
(rather than by using the familiar macOS @code{Installer} GUI app),
the macOS command line @code{installer} utility lets you select non-default
options, too. If you are not familiar with @code{installer}, it can be
somewhat cryptic (see @code{man installer} for more information).
As an example, the following shell snippet shows one way to do it,
using the @code{3.13.0b2} release and selecting the free-threaded interpreter
option:

@example
RELEASE="python-3.13.0b2-macos11.pkg"

# download installer pkg
curl -O https://www.python.org/ftp/python/3.13.0/$@{RELEASE@}

# create installer choicechanges to customize the install:
#    enable the PythonTFramework-3.13 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">
<plist version="1.0">
<array>
        <dict>
                <key>attributeSetting</key>
                <integer>1</integer>
                <key>choiceAttribute</key>
                <string>selected</string>
                <key>choiceIdentifier</key>
                <string>org.python.Python.PythonTFramework-3.13</string>
        </dict>
</array>
</plist>
EOF

sudo installer -pkg ./$@{RELEASE@} -applyChoiceChangesXML ./choicechanges.plist -target /
@end example

You can then test that both installer builds are now available with something like:

@example
$ # 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)]
$ #    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)]
$ # 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)]
@end example

@cartouche
@quotation Note 
Current @code{python.org} installers only install to fixed locations like
@code{/Library/Frameworks/}, @code{/Applications}, and @code{/usr/local/bin}.
You cannot use the @code{installer} @code{-domain} option to install to
other locations.
@end quotation
@end cartouche

@node Distributing Python Applications,App Store Compliance,Installing using the command line,Sujets avancés
@anchor{using/mac distributing-python-applications}@anchor{1dd7}@anchor{using/mac distributing-python-applications-on-the-mac}@anchor{1dd8}
@subsubsection Distributing Python Applications


A range of tools exist for converting your Python code into a standalone
distributable application:


@itemize *

@item 
py2app@footnote{https://pypi.org/project/py2app/}: Supports creating macOS @code{.app}
bundles from a Python project.

@item 
Briefcase@footnote{https://briefcase.readthedocs.io}: Part of the BeeWare Project@footnote{https://beeware.org}; a cross-platform packaging tool that supports
creation of @code{.app} bundles on macOS, as well as managing signing and
notarization.

@item 
PyInstaller@footnote{https://pyinstaller.org/}: A cross-platform packaging tool that creates
a single file or folder as a distributable artifact.
@end itemize

@node App Store Compliance,,Distributing Python Applications,Sujets avancés
@anchor{using/mac app-store-compliance}@anchor{1dd9}
@subsubsection App Store Compliance


Apps submitted for distribution through the macOS App Store must pass Apple's
app review process. This process includes a set of automated validation rules
that inspect the submitted application bundle for problematic code.

The Python standard library contains some code that is known to violate these
automated rules. While these violations appear to be false positives, Apple's
review rules cannot be challenged. Therefore, it is necessary to modify the
Python standard library for an app to pass App Store review.

The Python source tree contains
a patch file@footnote{https://github.com/python/cpython/tree/3.13/Mac/Resources/app-store-compliance.patch} that will remove
all code that is known to cause issues with the App Store review process. This
patch is applied automatically when CPython is configured with the
@ref{157b,,--with-app-store-compliance} option.

This patch is not normally required to use CPython on a Mac; nor is it required
if you are distributing an app `outside' the macOS App Store. It is `only'
required if you are using the macOS App Store as a distribution channel.

@node Autres ressources,,Sujets avancés,Using Python on macOS
@anchor{using/mac other-resources}@anchor{1dda}
@subsection Autres ressources


The python.org Help page@footnote{https://www.python.org/about/help/} has links to many useful resources.
The Pythonmac-SIG mailing list@footnote{https://www.python.org/community/sigs/current/pythonmac-sig/}
is another support resource specifically for Python users and developers on the Mac.

@node Using Python on Android,Using Python on iOS,Using Python on macOS,Installation et utilisation de Python
@anchor{using/android doc}@anchor{1ddb}@anchor{using/android using-android}@anchor{1ddc}@anchor{using/android using-python-on-android}@anchor{1ddd}
@section Using Python on Android


Python on Android is unlike Python on desktop platforms. On a desktop platform,
Python is generally installed as a system resource that can be used by any user
of that computer. Users then interact with Python by running a @code{python}
executable and entering commands at an interactive prompt, or by running a
Python script.

On Android, there is no concept of installing as a system resource. The only unit
of software distribution is an "app". There is also no console where you could
run a @code{python} executable, or interact with a Python REPL.

As a result, the only way you can use Python on Android is in embedded mode – that
is, by writing a native Android application, embedding a Python interpreter
using @code{libpython}, and invoking Python code using the @ref{1dde,,Python embedding API}. The full Python interpreter, the standard library, and all
your Python code is then packaged into your app for its own private use.

The Python standard library has some notable omissions and restrictions on
Android. See the @ref{1ddf,,API availability guide} for
details.

@menu
* Adding Python to an Android app:: 

@end menu

@node Adding Python to an Android app,,,Using Python on Android
@anchor{using/android adding-python-to-an-android-app}@anchor{1de0}
@subsection Adding Python to an Android app


These instructions are only needed if you're planning to compile Python for
Android yourself. Most users should `not' need to do this. Instead, use one of
the following tools, which will provide a much easier experience:


@itemize *

@item 
Briefcase@footnote{https://briefcase.readthedocs.io}, from the BeeWare project

@item 
Buildozer@footnote{https://buildozer.readthedocs.io}, from the Kivy project

@item 
Chaquopy@footnote{https://chaquo.com/chaquopy}

@item 
pyqtdeploy@footnote{https://www.riverbankcomputing.com/static/Docs/pyqtdeploy/}

@item 
Termux@footnote{https://termux.dev/en/}
@end itemize

If you're sure you want to do all of this manually, read on. You can use the
testbed app@footnote{https://github.com/python/cpython/tree/3.13/Android/testbed} as a guide; each step below contains a
link to the relevant file.


@itemize *

@item 
Build Python by following the instructions in Android/README.md@footnote{https://github.com/python/cpython/tree/3.13/Android/README.md}.

@item 
Add code to your build.gradle@footnote{https://github.com/python/cpython/tree/3.13/Android/testbed/app/build.gradle.kts}
file to copy the following items into your project. All except your own Python
code can be copied from @code{cross-build/HOST/prefix/lib}:


@itemize *

@item 
In your JNI libraries:


@itemize *

@item 
@code{libpython*.*.so}

@item 
@code{lib*_python.so} (external libraries such as OpenSSL)
@end itemize

@item 
In your assets:


@itemize *

@item 
@code{python*.*} (the Python standard library)

@item 
@code{python*.*/site-packages} (your own Python code)
@end itemize
@end itemize

@item 
Add code to your app to extract the assets to the filesystem@footnote{https://github.com/python/cpython/tree/3.13/Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt}.

@item 
Add code to your app to start Python in embedded mode@footnote{https://github.com/python/cpython/tree/3.13/Android/testbed/app/src/main/c/main_activity.c}. This will need to be C code
called via JNI.
@end itemize

@node Using Python on iOS,Éditeurs et IDEs,Using Python on Android,Installation et utilisation de Python
@anchor{using/ios doc}@anchor{1de1}@anchor{using/ios using-ios}@anchor{1de2}@anchor{using/ios using-python-on-ios}@anchor{1de3}
@section Using Python on iOS


@*Authors: 
Russell Keith-Magee (2024-03)


Python on iOS is unlike Python on desktop platforms. On a desktop platform,
Python is generally installed as a system resource that can be used by any user
of that computer. Users then interact with Python by running a @code{python}
executable and entering commands at an interactive prompt, or by running a
Python script.

On iOS, there is no concept of installing as a system resource. The only unit
of software distribution is an "app". There is also no console where you could
run a @code{python} executable, or interact with a Python REPL.

As a result, the only way you can use Python on iOS is in embedded mode - that
is, by writing a native iOS application, and embedding a Python interpreter
using @code{libPython}, and invoking Python code using the @ref{1dde,,Python embedding API}. The full Python interpreter, the standard library, and all
your Python code is then packaged as a standalone bundle that can be
distributed via the iOS App Store.

If you're looking to experiment for the first time with writing an iOS app in
Python, projects such as BeeWare@footnote{https://beeware.org} and Kivy@footnote{https://kivy.org} will provide a much more approachable user experience.
These projects manage the complexities associated with getting an iOS project
running, so you only need to deal with the Python code itself.

@menu
* Python at runtime on iOS:: 
* Installing Python on iOS:: 
* App Store Compliance: App Store Compliance<2>. 

@end menu

@node Python at runtime on iOS,Installing Python on iOS,,Using Python on iOS
@anchor{using/ios python-at-runtime-on-ios}@anchor{1de4}
@subsection Python at runtime on iOS


@menu
* iOS version compatibility:: 
* Platform identification:: 
* Standard library availability:: 
* Binary extension modules:: 
* Compiler stub binaries:: 

@end menu

@node iOS version compatibility,Platform identification,,Python at runtime on iOS
@anchor{using/ios ios-version-compatibility}@anchor{1de5}
@subsubsection iOS version compatibility


The minimum supported iOS version is specified at compile time, using the
@ref{1d5e,,--host} option to @code{configure}. By default, when compiled for iOS,
Python will be compiled with a minimum supported iOS version of 13.0. To use a
different minimum iOS version, provide the version number as part of the
@code{--host} argument - for example,
@code{--host=arm64-apple-ios15.4-simulator} would compile an ARM64 simulator build
with a deployment target of 15.4.

@node Platform identification,Standard library availability,iOS version compatibility,Python at runtime on iOS
@anchor{using/ios platform-identification}@anchor{1de6}
@subsubsection Platform identification


When executing on iOS, @code{sys.platform} will report as @code{ios}. This value will
be returned on an iPhone or iPad, regardless of whether the app is running on
the simulator or a physical device.

Information about the specific runtime environment, including the iOS version,
device model, and whether the device is a simulator, can be obtained using
@ref{1de7,,platform.ios_ver()}. @ref{1de8,,platform.system()} will report @code{iOS} or
@code{iPadOS}, depending on the device.

@ref{10f6,,os.uname()} reports kernel-level details; it will report a name of
@code{Darwin}.

@node Standard library availability,Binary extension modules,Platform identification,Python at runtime on iOS
@anchor{using/ios standard-library-availability}@anchor{1de9}
@subsubsection Standard library availability


The Python standard library has some notable omissions and restrictions on
iOS. See the @ref{1ddf,,API availability guide for iOS} for
details.

@node Binary extension modules,Compiler stub binaries,Standard library availability,Python at runtime on iOS
@anchor{using/ios binary-extension-modules}@anchor{1dea}
@subsubsection Binary extension modules


One notable difference about iOS as a platform is that App Store distribution
imposes hard requirements on the packaging of an application. One of these
requirements governs how binary extension modules are distributed.

The iOS App Store requires that `all' binary modules in an iOS app must be
dynamic libraries, contained in a framework with appropriate metadata, stored
in the @code{Frameworks} folder of the packaged app. There can be only a single
binary per framework, and there can be no executable binary material outside
the @code{Frameworks} folder.

This conflicts with the usual Python approach for distributing binaries, which
allows a binary extension module to be loaded from any location on
@code{sys.path}. To ensure compliance with App Store policies, an iOS project must
post-process any Python packages, converting @code{.so} binary modules into
individual standalone frameworks with appropriate metadata and signing. For
details on how to perform this post-processing, see the guide for @ref{1deb,,adding Python to your project}.

To help Python discover binaries in their new location, the original @code{.so}
file on @code{sys.path} is replaced with a @code{.fwork} file. This file is a text
file containing the location of the framework binary, relative to the app
bundle. To allow the framework to resolve back to the original location, the
framework must contain a @code{.origin} file that contains the location of the
@code{.fwork} file, relative to the app bundle.

For example, consider the case of an import @code{from foo.bar import _whiz},
where @code{_whiz} is implemented with the binary module
@code{sources/foo/bar/_whiz.abi3.so}, with @code{sources} being the location
registered on @code{sys.path}, relative to the application bundle. This module
`must' be distributed as @code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz}
(creating the framework name from the full import path of the module), with an
@code{Info.plist} file in the @code{.framework} directory identifying the binary as a
framework. The @code{foo.bar._whiz} module would be represented in the original
location with a @code{sources/foo/bar/_whiz.abi3.fwork} marker file, containing
the path @code{Frameworks/foo.bar._whiz/foo.bar._whiz}. The framework would also
contain @code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin}, containing
the path to the @code{.fwork} file.

When running on iOS, the Python interpreter will install an
@ref{1dec,,AppleFrameworkLoader} that is able to read and
import @code{.fwork} files. Once imported, the @code{__file__} attribute of the
binary module will report as the location of the @code{.fwork} file. However, the
@ref{1ded,,ModuleSpec} for the loaded module will report the
@code{origin} as the location of the binary in the framework folder.

@node Compiler stub binaries,,Binary extension modules,Python at runtime on iOS
@anchor{using/ios compiler-stub-binaries}@anchor{1dee}
@subsubsection Compiler stub binaries


Xcode doesn't expose explicit compilers for iOS; instead, it uses an @code{xcrun}
script that resolves to a full compiler path (e.g., @code{xcrun --sdk iphoneos
clang} to get the @code{clang} for an iPhone device). However, using this script
poses two problems:


@itemize *

@item 
The output of @code{xcrun} includes paths that are machine specific, resulting
in a sysconfig module that cannot be shared between users; and

@item 
It results in @code{CC}/@code{CPP}/@code{LD}/@code{AR} definitions that include spaces.
There is a lot of C ecosystem tooling that assumes that you can split a
command line at the first space to get the path to the compiler executable;
this isn't the case when using @code{xcrun}.
@end itemize

To avoid these problems, Python provided stubs for these tools. These stubs are
shell script wrappers around the underingly @code{xcrun} tools, distributed in a
@code{bin} folder distributed alongside the compiled iOS framework. These scripts
are relocatable, and will always resolve to the appropriate local system paths.
By including these scripts in the bin folder that accompanies a framework, the
contents of the @code{sysconfig} module becomes useful for end-users to compile
their own modules. When compiling third-party Python modules for iOS, you
should ensure these stub binaries are on your path.

@node Installing Python on iOS,App Store Compliance<2>,Python at runtime on iOS,Using Python on iOS
@anchor{using/ios installing-python-on-ios}@anchor{1def}
@subsection Installing Python on iOS


@menu
* Tools for building iOS apps:: 
* Adding Python to an iOS project:: 
* Testing a Python package:: 

@end menu

@node Tools for building iOS apps,Adding Python to an iOS project,,Installing Python on iOS
@anchor{using/ios tools-for-building-ios-apps}@anchor{1df0}
@subsubsection Tools for building iOS apps


Building for iOS requires the use of Apple's Xcode tooling. It is strongly
recommended that you use the most recent stable release of Xcode. This will
require the use of the most (or second-most) recently released macOS version,
as Apple does not maintain Xcode for older macOS versions. The Xcode Command
Line Tools are not sufficient for iOS development; you need a `full' Xcode
install.

If you want to run your code on the iOS simulator, you'll also need to install
an iOS Simulator Platform. You should be prompted to select an iOS Simulator
Platform when you first run Xcode. Alternatively, you can add an iOS Simulator
Platform by selecting from the Platforms tab of the Xcode Settings panel.

@node Adding Python to an iOS project,Testing a Python package,Tools for building iOS apps,Installing Python on iOS
@anchor{using/ios adding-ios}@anchor{1deb}@anchor{using/ios adding-python-to-an-ios-project}@anchor{1df1}
@subsubsection Adding Python to an iOS project


Python can be added to any iOS project, using either Swift or Objective C. The
following examples will use Objective C; if you are using Swift, you may find a
library like PythonKit@footnote{https://github.com/pvieito/PythonKit} to be
helpful.

To add Python to an iOS Xcode project:


@enumerate 

@item 
Build or obtain a Python @code{XCFramework}. See the instructions in
iOS/README.rst@footnote{https://github.com/python/cpython/tree/3.13/iOS/README.rst} (in the CPython source distribution) for details on
how to build a Python @code{XCFramework}. At a minimum, you will need a build
that supports @code{arm64-apple-ios}, plus one of either
@code{arm64-apple-ios-simulator} or @code{x86_64-apple-ios-simulator}.

@item 
Drag the @code{XCframework} into your iOS project. In the following
instructions, we'll assume you've dropped the @code{XCframework} into the root
of your project; however, you can use any other location that you want by
adjusting paths as needed.

@item 
Drag the @code{iOS/Resources/dylib-Info-template.plist} file into your project,
and ensure it is associated with the app target.

@item 
Add your application code as a folder in your Xcode project. In the
following instructions, we'll assume that your user code is in a folder
named @code{app} in the root of your project; you can use any other location by
adjusting paths as needed. Ensure that this folder is associated with your
app target.

@item 
Select the app target by selecting the root node of your Xcode project, then
the target name in the sidebar that appears.

@item 
In the "General" settings, under "Frameworks, Libraries and Embedded
Content", add @code{Python.xcframework}, with "Embed & Sign" selected.

@item 
In the "Build Settings" tab, modify the following:


@itemize -

@item 
Build Options


@itemize *

@item 
User Script Sandboxing: No

@item 
Enable Testability: Yes
@end itemize

@item 
Search Paths


@itemize *

@item 
Framework Search Paths: @code{$(PROJECT_DIR)}

@item 
Header Search Paths: @code{"$(BUILT_PRODUCTS_DIR)/Python.framework/Headers"}
@end itemize

@item 
Apple Clang - Warnings - All languages


@itemize *

@item 
Quoted Include In Framework Header: No
@end itemize
@end itemize

@item 
Add a build step that copies the Python standard library into your app. In
the "Build Phases" tab, add a new "Run Script" build step `before' the
"Embed Frameworks" step, but `after' the "Copy Bundle Resources" step. Name
the step "Install Target Specific Python Standard Library", disable the
"Based on dependency analysis" checkbox, and set the script content to:

@example
set -e

mkdir -p "$CODESIGNING_FOLDER_PATH/python/lib"
if [ "$EFFECTIVE_PLATFORM_NAME" = "-iphonesimulator" ]; then
    echo "Installing Python modules for iOS Simulator"
    rsync -au --delete "$PROJECT_DIR/Python.xcframework/ios-arm64_x86_64-simulator/lib/" "$CODESIGNING_FOLDER_PATH/python/lib/"
else
    echo "Installing Python modules for iOS Device"
    rsync -au --delete "$PROJECT_DIR/Python.xcframework/ios-arm64/lib/" "$CODESIGNING_FOLDER_PATH/python/lib/"
fi
@end example

Note that the name of the simulator "slice" in the XCframework may be
different, depending the CPU architectures your @code{XCFramework} supports.

@item 
Add a second build step that processes the binary extension modules in the
standard library into "Framework" format. Add a "Run Script" build step
`directly after' the one you added in step 8, named "Prepare Python Binary
Modules". It should also have "Based on dependency analysis" unchecked, with
the following script content:

@example
set -e

install_dylib () @{
    INSTALL_BASE=$1
    FULL_EXT=$2

    # The name of the extension file
    EXT=$(basename "$FULL_EXT")
    # The location of the extension file, relative to the bundle
    RELATIVE_EXT=$@{FULL_EXT#$CODESIGNING_FOLDER_PATH/@}
    # The path to the extension file, relative to the install base
    PYTHON_EXT=$@{RELATIVE_EXT/$INSTALL_BASE/@}
    # The full dotted name of the extension module, constructed from the file path.
    FULL_MODULE_NAME=$(echo $PYTHON_EXT | cut -d "." -f 1 | tr "/" ".");
    # A bundle identifier; not actually used, but required by Xcode framework packaging
    FRAMEWORK_BUNDLE_ID=$(echo $PRODUCT_BUNDLE_IDENTIFIER.$FULL_MODULE_NAME | tr "_" "-")
    # The name of the framework folder.
    FRAMEWORK_FOLDER="Frameworks/$FULL_MODULE_NAME.framework"

    # If the framework folder doesn't exist, create it.
    if [ ! -d "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER" ]; then
        echo "Creating framework for $RELATIVE_EXT"
        mkdir -p "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER"
        cp "$CODESIGNING_FOLDER_PATH/dylib-Info-template.plist" "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER/Info.plist"
        plutil -replace CFBundleExecutable -string "$FULL_MODULE_NAME" "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER/Info.plist"
        plutil -replace CFBundleIdentifier -string "$FRAMEWORK_BUNDLE_ID" "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER/Info.plist"
    fi

    echo "Installing binary for $FRAMEWORK_FOLDER/$FULL_MODULE_NAME"
    mv "$FULL_EXT" "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER/$FULL_MODULE_NAME"
    # Create a placeholder .fwork file where the .so was
    echo "$FRAMEWORK_FOLDER/$FULL_MODULE_NAME" > $@{FULL_EXT%.so@}.fwork
    # Create a back reference to the .so file location in the framework
    echo "$@{RELATIVE_EXT%.so@}.fwork" > "$CODESIGNING_FOLDER_PATH/$FRAMEWORK_FOLDER/$FULL_MODULE_NAME.origin"
 @}

 PYTHON_VER=$(ls -1 "$CODESIGNING_FOLDER_PATH/python/lib")
 echo "Install Python $PYTHON_VER standard library extension modules..."
 find "$CODESIGNING_FOLDER_PATH/python/lib/$PYTHON_VER/lib-dynload" -name "*.so" | while read FULL_EXT; do
    install_dylib python/lib/$PYTHON_VER/lib-dynload/ "$FULL_EXT"
 done

 # Clean up dylib template
 rm -f "$CODESIGNING_FOLDER_PATH/dylib-Info-template.plist"

 echo "Signing frameworks as $EXPANDED_CODE_SIGN_IDENTITY_NAME ($EXPANDED_CODE_SIGN_IDENTITY)..."
 find "$CODESIGNING_FOLDER_PATH/Frameworks" -name "*.framework" -exec /usr/bin/codesign --force --sign "$EXPANDED_CODE_SIGN_IDENTITY" $@{OTHER_CODE_SIGN_FLAGS:-@} -o runtime --timestamp=none --preserve-metadata=identifier,entitlements,flags --generate-entitlement-der "@{@}" \;
@end example

@item 
Add Objective C code to initialize and use a Python interpreter in embedded
mode. You should ensure that:
@end enumerate

@quotation


@itemize *

@item 
UTF-8 mode (@ref{3e1,,PyPreConfig.utf8_mode}) is `enabled';

@item 
Buffered stdio (@ref{3d6,,PyConfig.buffered_stdio}) is `disabled';

@item 
Writing bytecode (@ref{3d2,,PyConfig.write_bytecode}) is `disabled';

@item 
Signal handlers (@ref{8ab,,PyConfig.install_signal_handlers}) are `enabled';

@item 
System logging (@ref{1df2,,PyConfig.use_system_logger}) is `enabled'
(optional, but strongly recommended);

@item 
@code{PYTHONHOME} for the interpreter is configured to point at the
@code{python} subfolder of your app's bundle; and

@item 
The @code{PYTHONPATH} for the interpreter includes:


@itemize -

@item 
the @code{python/lib/python3.X} subfolder of your app's bundle,

@item 
the @code{python/lib/python3.X/lib-dynload} subfolder of your app's bundle, and

@item 
the @code{app} subfolder of your app's bundle
@end itemize
@end itemize

Your app's bundle location can be determined using @code{[[NSBundle mainBundle]
resourcePath]}.
@end quotation

Steps 8, 9 and 10 of these instructions assume that you have a single folder of
pure Python application code, named @code{app}. If you have third-party binary
modules in your app, some additional steps will be required:


@itemize *

@item 
You need to ensure that any folders containing third-party binaries are
either associated with the app target, or copied in as part of step 8. Step 8
should also purge any binaries that are not appropriate for the platform a
specific build is targeting (i.e., delete any device binaries if you're
building an app targeting the simulator).

@item 
Any folders that contain third-party binaries must be processed into
framework form by step 9. The invocation of @code{install_dylib} that processes
the @code{lib-dynload} folder can be copied and adapted for this purpose.

@item 
If you're using a separate folder for third-party packages, ensure that folder
is included as part of the @code{PYTHONPATH} configuration in step 10.
@end itemize

@node Testing a Python package,,Adding Python to an iOS project,Installing Python on iOS
@anchor{using/ios testing-a-python-package}@anchor{1df3}
@subsubsection Testing a Python package


The CPython source tree contains a testbed project@footnote{https://github.com/python/cpython/tree/3.13/iOS/testbed} that
is used to run the CPython test suite on the iOS simulator. This testbed can also
be used as a testbed project for running your Python library's test suite on iOS.

After building or obtaining an iOS XCFramework (See iOS/README.rst@footnote{https://github.com/python/cpython/tree/3.13/iOS/README.rst}
for details), create a clone of the Python iOS testbed project by running:

@example
$ python iOS/testbed clone --framework <path/to/Python.xcframework> --app <path/to/module1> --app <path/to/module2> app-testbed
@end example

You will need to modify the @code{iOS/testbed} reference to point to that
directory in the CPython source tree; any folders specified with the @code{--app}
flag will be copied into the cloned testbed project. The resulting testbed will
be created in the @code{app-testbed} folder. In this example, the @code{module1} and
@code{module2} would be importable modules at runtime. If your project has
additional dependencies, they can be installed into the
@code{app-testbed/iOSTestbed/app_packages} folder (using @code{pip install --target
app-testbed/iOSTestbed/app_packages} or similar).

You can then use the @code{app-testbed} folder to run the test suite for your app,
For example, if @code{module1.tests} was the entry point to your test suite, you
could run:

@example
$ python app-testbed run -- module1.tests
@end example

This is the equivalent of running @code{python -m module1.tests} on a desktop
Python build. Any arguments after the @code{--} will be passed to the testbed as
if they were arguments to @code{python -m} on a desktop machine.

You can also open the testbed project in Xcode by running:

@example
$ open app-testbed/iOSTestbed.xcodeproj
@end example

This will allow you to use the full Xcode suite of tools for debugging.

@node App Store Compliance<2>,,Installing Python on iOS,Using Python on iOS
@anchor{using/ios app-store-compliance}@anchor{1df4}
@subsection App Store Compliance


The only mechanism for distributing apps to third-party iOS devices is to
submit the app to the iOS App Store; apps submitted for distribution must pass
Apple's app review process. This process includes a set of automated validation
rules that inspect the submitted application bundle for problematic code.

The Python standard library contains some code that is known to violate these
automated rules. While these violations appear to be false positives, Apple's
review rules cannot be challenged; so, it is necessary to modify the Python
standard library for an app to pass App Store review.

The Python source tree contains
a patch file@footnote{https://github.com/python/cpython/tree/3.13/Mac/Resources/app-store-compliance.patch} that will remove
all code that is known to cause issues with the App Store review process. This
patch is applied automatically when building for iOS.

@node Éditeurs et IDEs,,Using Python on iOS,Installation et utilisation de Python
@anchor{using/editors doc}@anchor{1df5}@anchor{using/editors editors}@anchor{1dcd}@anchor{using/editors editors-and-ides}@anchor{1df6}
@section Éditeurs et IDEs


Il y a un grand nombre d'environnement de développement qui gèrent le langage de programmation Python. Beaucoup d'éditeurs et d'EDIs proposent une mise en surbrillance de la syntaxe, des outils de débogage et une vérification PEP-8.

Merci d'aller sur Python Editors@footnote{https://wiki.python.org/moin/PythonEditors} et Integrated Development Environments@footnote{https://wiki.python.org/moin/IntegratedDevelopmentEnvironments} pour une liste exhaustive.

@node La référence du langage Python,La bibliothèque standard,Installation et utilisation de Python,Top
@anchor{reference/index doc}@anchor{1df7}@anchor{reference/index reference-index}@anchor{144}@anchor{reference/index the-python-language-reference}@anchor{1df8}
@chapter La référence du langage Python


Cette documentation décrit la syntaxe et la « sémantique interne » du langage. Elle peut être laconique, mais essaye d'être exhaustive et exacte. La sémantique des objets natifs secondaires, des fonctions, et des modules est documentée dans @ref{143,,La bibliothèque standard}. Pour une présentation informelle du langage, voyez plutôt @ref{1b68,,Le tutoriel Python}. Pour les développeurs C ou C++, deux manuels supplémentaires existent : @ref{1b69,,Extension et intégration de l'interpréteur Python} survole l'écriture d'extensions, et @ref{1b6a,,Manuel de référence de l'API Python/C} décrit l'interface C/C++ en détail.

@menu
* Introduction: Introduction<5>. 
* Analyse lexicale:: 
* Modèle de données:: 
* Modèle d'exécution:: 
* Le système d'importation:: 
* Expressions:: 
* Les instructions simples:: 
* Instructions composées:: 
* Composants de plus haut niveau:: 
* Spécification complète de la grammaire:: 

@end menu

@node Introduction<5>,Analyse lexicale,,La référence du langage Python
@anchor{reference/introduction doc}@anchor{1df9}@anchor{reference/introduction id1}@anchor{1dfa}@anchor{reference/introduction introduction}@anchor{1dfb}
@section Introduction


Ce manuel de référence décrit le langage de programmation Python. Il n'a pas vocation à être un tutoriel.

Nous essayons d'être le plus précis possible et nous utilisons le français (NdT : ou l’anglais pour les parties qui ne sont pas encore traduites) plutôt que des spécifications formelles, sauf pour la syntaxe et l’analyse lexicale. Nous espérons ainsi rendre ce document plus compréhensible pour un grand nombre de lecteurs, même si cela laisse un peu de place à l’ambiguïté. En conséquence, si vous arrivez de Mars et que vous essayez de ré-implémenter Python à partir de cet unique document, vous devrez faire des hypothèses et, finalement, vous aurez certainement implémenté un langage sensiblement différent. D’un autre côté, si vous utilisez Python et que vous vous demandez quelles règles s’appliquent pour telle partie du langage, vous devriez trouver une réponse satisfaisante ici. Si vous souhaitez voir une définition plus formelle du langage, nous acceptons toutes les bonnes volontés (ou bien inventez une machine pour nous cloner ☺).

S’agissant du manuel de référence d’un langage, il est dangereux de rentrer profondément dans les détails d’implémentation ; l’implémentation peut changer et d’autres implémentations du même langage peuvent fonctionner différemment. En même temps, CPython est l’implémentation de Python la plus répandue (bien que d’autres implémentations gagnent en popularité) et certaines de ses bizarreries méritent parfois d’être mentionnées, en particulier lorsque l’implémentation impose des limitations supplémentaires. Par conséquent, vous trouvez de courtes "notes d’implémentation" saupoudrées dans le texte.

Chaque implémentation de Python est livrée avec un certain nombre de modules natifs. Ceux-ci sont documentés dans @ref{143,,La bibliothèque standard}. Quelques modules natifs sont mentionnés quand ils interagissent significativement avec la définition du langage.

@menu
* Autres implémentations:: 
* Notations:: 

@end menu

@node Autres implémentations,Notations,,Introduction<5>
@anchor{reference/introduction alternate-implementations}@anchor{1dfc}@anchor{reference/introduction implementations}@anchor{1cb2}
@subsection Autres implémentations


Bien qu’il existe une implémentation Python qui soit de loin la plus populaire, il existe d’autres implémentations qui présentent un intérêt particulier pour différents publics.

Parmi les implémentations les plus connues, nous pouvons citer :


@table @asis

@item CPython

C’est l’implémentation originelle et la plus entretenue de Python, écrite en C. Elle implémente généralement en premier les nouvelles fonctionnalités du langage.

@item Jython

Python implemented in Java.  This implementation can be used as a scripting
language for Java applications, or can be used to create applications using the
Java class libraries.  It is also often used to create tests for Java libraries.
More information can be found at the Jython website@footnote{https://www.jython.org/}.

@item Python pour .NET

Cette implémentation utilise en fait l’implémentation CPython, mais c’est une application .NET et permet un accès aux bibliothèques .NET. Elle a été créée par Brian Lloyd. Pour plus d’informations, consultez la page d’accueil Python pour .NET@footnote{https://pythonnet.github.io/} (site en anglais).

@item IronPython

An alternate Python for .NET.  Unlike Python.NET, this is a complete Python
implementation that generates IL, and compiles Python code directly to .NET
assemblies.  It was created by Jim Hugunin, the original creator of Jython.  For
more information, see the IronPython website@footnote{https://ironpython.net/}.

@item PyPy

An implementation of Python written completely in Python. It supports several
advanced features not found in other implementations like stackless support
and a Just in Time compiler. One of the goals of the project is to encourage
experimentation with the language itself by making it easier to modify the
interpreter (since it is written in Python).  Additional information is
available on the PyPy project's home page@footnote{https://pypy.org/}.
@end table

Chacune de ces implémentations diffère d'une manière ou d'une autre par rapport au langage décrit dans ce manuel, ou comporte des spécificités que la documentation standard de Python ne couvre pas. Reportez-vous à la documentation spécifique à l'implémentation pour déterminer ce que vous devez savoir sur l'implémentation que vous utilisez.

@node Notations,,Autres implémentations,Introduction<5>
@anchor{reference/introduction id2}@anchor{1dfd}@anchor{reference/introduction notation}@anchor{1dfe}
@subsection Notations


@geindex BNF
@geindex grammar
@geindex syntax
@geindex notation

The descriptions of lexical analysis and syntax use a modified
Backus–Naur form (BNF)@footnote{https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form} grammar
notation.  This uses the following style of definition:

@example
@anchor{reference/introduction grammar-token-notation-name}@anchor{1dff}name      ::= lc_letter (lc_letter | "_")*
@anchor{reference/introduction grammar-token-notation-lc_letter}@anchor{1e00}lc_letter ::= "a"..."z"
@end example

La première ligne indique qu'un @code{name} est un @code{lc_letter} suivi d'une suite de zéro ou plus @code{lc_letter}s ou tiret bas. Un @code{lc_letter} est, à son tour, l'un des caractères @code{'a'} à @code{'z'} (cette règle est effectivement respectée pour les noms définis dans les règles lexicales et grammaticales de ce document).

Chaque règle commence par un nom (qui est le nom que la règle définit) et @code{::=}. Une barre verticale (@code{|}) est utilisée pour séparer les alternatives ; c'est l'opérateur le moins prioritaire de cette notation. Une étoile (@code{*}) signifie zéro ou plusieurs répétitions de l'élément précédent ; de même, un plus (@code{+}) signifie une ou plusieurs répétitions, et une expression entre crochets (@code{[ ]}) signifie zéro ou une occurrence (en d'autres termes, l'expression encadrée est facultative). Les opérateurs @code{*} et @code{+} agissent aussi étroitement que possible ; les parenthèses sont utilisées pour le regroupement. Les chaînes littérales sont entourées de guillemets anglais @code{"}. L'espace n'est utilisée que pour séparer les lexèmes. Les règles sont normalement contenues sur une seule ligne ; les règles avec de nombreuses alternatives peuvent être formatées avec chaque ligne représentant une alternative (et donc débutant par une barre verticale, sauf la première).

@geindex lexical definitions
@geindex ASCII

Dans les définitions lexicales (comme dans l'exemple ci-dessus), deux autres conventions sont utilisées : deux caractères littéraux séparés par des points de suspension signifient le choix d'un seul caractère dans la plage donnée (en incluant les bornes) de caractères ASCII. Une phrase entre les signes inférieur et supérieur (@code{<...>}) donne une description informelle du symbole défini ; par exemple, pour décrire la notion de "caractère de contrôle" si nécessaire.

Même si la notation utilisée est presque la même, il existe une grande différence entre la signification des définitions lexicales et syntaxiques : une définition lexicale opère sur les caractères individuels de l'entrée, tandis qu'une définition syntaxique opère sur le flux de lexèmes générés par l'analyse lexicale. Toutes les notations sous la forme BNF dans le chapitre suivant (« Analyse lexicale ») sont des définitions lexicales ; les notations dans les chapitres suivants sont des définitions syntaxiques.

@node Analyse lexicale,Modèle de données,Introduction<5>,La référence du langage Python
@anchor{reference/lexical_analysis doc}@anchor{1e01}@anchor{reference/lexical_analysis lexical}@anchor{1e02}@anchor{reference/lexical_analysis lexical-analysis}@anchor{1e03}
@section Analyse lexicale


@geindex lexical analysis
@geindex parser
@geindex token

Un programme Python est lu par un analyseur syntaxique (`parser' en anglais). En entrée de cet analyseur syntaxique, nous trouvons des lexèmes (`tokens' en anglais), produits par un analyseur lexical. Ce chapitre décrit comment l'analyseur lexical découpe le fichier en lexèmes.

Python lit le texte du programme comme des suites de caractères Unicode ; l'encodage du fichier source peut être spécifié par une déclaration d'encodage et vaut par défaut UTF-8, voir la 
@geindex Python Enhancement Proposals; PEP 3120
PEP 3120@footnote{https://peps.python.org/pep-3120/} pour les détails. Si le fichier source ne peut pas être décodé, une exception @ref{18b,,SyntaxError} (erreur de syntaxe) est levée.

@menu
* Structure des lignes:: 
* Autres lexèmes:: 
* Identifiants et mots-clés:: 
* Littéraux:: 
* Opérateurs:: 
* Délimiteurs:: 

@end menu

@node Structure des lignes,Autres lexèmes,,Analyse lexicale
@anchor{reference/lexical_analysis id1}@anchor{1e04}@anchor{reference/lexical_analysis line-structure}@anchor{1e05}
@subsection Structure des lignes


@geindex line structure

Un programme en Python est divisé en `lignes logiques'.

@menu
* Lignes logiques:: 
* Lignes physiques:: 
* Commentaires:: 
* Déclaration d'encodage:: 
* Continuation de ligne explicite:: 
* Continuation de ligne implicite:: 
* Lignes vierges:: 
* Indentation:: 
* Espaces entre lexèmes:: 

@end menu

@node Lignes logiques,Lignes physiques,,Structure des lignes
@anchor{reference/lexical_analysis id2}@anchor{1e06}@anchor{reference/lexical_analysis logical-lines}@anchor{1e07}
@subsubsection Lignes logiques


@geindex logical line
@geindex physical line
@geindex line joining
@geindex NEWLINE token

La fin d'une ligne logique est représentée par le lexème NEWLINE. Les instructions ne peuvent pas traverser les limites des lignes logiques, sauf quand NEWLINE est autorisé par la syntaxe (par exemple, entre les instructions des instructions composées). Une ligne logique est constituée d'une ou plusieurs `lignes physiques' en fonction des règles, explicites ou implicites, de `continuation de ligne'.

@node Lignes physiques,Commentaires,Lignes logiques,Structure des lignes
@anchor{reference/lexical_analysis id3}@anchor{1e08}@anchor{reference/lexical_analysis physical-lines}@anchor{1e09}
@subsubsection Lignes physiques


Une ligne physique est une suite de caractères terminée par une séquence de fin de ligne. Dans les fichiers sources et les chaînes de caractères, n'importe quelle séquence de fin de ligne des plateformes standards peut être utilisée ; Unix utilise le caractère ASCII LF (pour `linefeed', saut de ligne en français), Windows utilise la séquence CR LF (`carriage return' suivi de `linefeed') et Macintosh utilisait le caractère ASCII CR. Toutes ces séquences peuvent être utilisées, quelle que soit la plateforme. La fin de l'entrée est aussi une fin de ligne physique implicite.

Lorsque vous encapsulez Python, les chaînes de code source doivent être passées à l'API Python en utilisant les conventions du C standard pour les caractères de fin de ligne : le caractère @code{\n}, dont le code ASCII est LF.

@node Commentaires,Déclaration d'encodage,Lignes physiques,Structure des lignes
@anchor{reference/lexical_analysis comments}@anchor{1e0a}@anchor{reference/lexical_analysis id4}@anchor{1e0b}
@subsubsection Commentaires


@geindex comment
@geindex hash character
@geindex # (hash);comment

Un commentaire commence par le caractère croisillon (@code{#}, `hash' en anglais et qui ressemble au symbole musical dièse, c'est pourquoi il est souvent improprement appelé caractère dièse) situé en dehors d'une chaine de caractères littérale et se termine à la fin de la ligne physique. Un commentaire signifie la fin de la ligne logique à moins qu'une règle de continuation de ligne implicite ne s'applique. Les commentaires sont ignorés au niveau syntaxique, ce ne sont pas des lexèmes.

@node Déclaration d'encodage,Continuation de ligne explicite,Commentaires,Structure des lignes
@anchor{reference/lexical_analysis encoding-declarations}@anchor{1e0c}@anchor{reference/lexical_analysis encodings}@anchor{1e0d}
@subsubsection Déclaration d'encodage


@geindex source character set
@geindex encoding declarations (source file)
@geindex # (hash);source encoding declaration

Si un commentaire placé sur la première ou deuxième ligne du script Python correspond à l'expression rationnelle @code{coding[=:]\s*([-\w.]+)}, ce commentaire est analysé comme une déclaration d'encodage ; le premier groupe de cette expression désigne l'encodage du fichier source. Cette déclaration d'encodage doit être seule sur sa ligne et, si elle est sur la deuxième ligne, la première ligne doit aussi être une ligne composée uniquement d'un commentaire. Les formes recommandées pour l'expression de l'encodage sont

@example
# -*- coding: <encoding-name> -*-
@end example

qui est reconnue aussi par GNU Emacs et

@example
# vim:fileencoding=<encoding-name>
@end example

qui est reconnue par VIM de Bram Moolenaar.

If no encoding declaration is found, the default encoding is UTF-8.  If the
implicit or explicit encoding of a file is UTF-8, an initial UTF-8 byte-order
mark (b'xefxbbxbf') is ignored rather than being a syntax error.

Si un encodage est déclaré, le nom de l'encodage doit être reconnu par Python (voir @ref{da6,,Standard Encodings}). L'encodage est utilisé pour toute l'analyse lexicale, y compris les chaînes de caractères, les commentaires et les identifiants.

@node Continuation de ligne explicite,Continuation de ligne implicite,Déclaration d'encodage,Structure des lignes
@anchor{reference/lexical_analysis explicit-joining}@anchor{1e0e}@anchor{reference/lexical_analysis explicit-line-joining}@anchor{1e0f}
@subsubsection Continuation de ligne explicite


@geindex physical line
@geindex line joining
@geindex line continuation
@geindex backslash character

Deux lignes physiques, ou plus, peuvent être jointes pour former une seule ligne logique en utilisant la barre oblique inversée (@code{\}) selon la règle suivante : quand la ligne physique se termine par une barre oblique inversée qui ne fait pas partie d'une chaine de caractères ou d'un commentaire, la ligne immédiatement suivante lui est adjointe pour former une seule ligne logique, en supprimant la barre oblique inversée et le caractère de fin de ligne. Par exemple :

@example
if 1900 < year < 2100 and 1 <= month <= 12 \
   and 1 <= day <= 31 and 0 <= hour < 24 \
   and 0 <= minute < 60 and 0 <= second < 60:   # Looks like a valid date
        return 1
@end example

Une ligne que se termine par une barre oblique inversée ne peut pas avoir de commentaire. La barre oblique inversée ne permet pas de continuer un commentaire. La barre oblique inversée ne permet pas de continuer un lexème, sauf s'il s'agit d'une chaîne de caractères (par exemple, les lexèmes autres que les chaînes de caractères ne peuvent pas être répartis sur plusieurs lignes en utilisant une barre oblique inversée). La barre oblique inversée n'est pas autorisée ailleurs sur la ligne, en dehors d'une chaîne de caractères.

@node Continuation de ligne implicite,Lignes vierges,Continuation de ligne explicite,Structure des lignes
@anchor{reference/lexical_analysis implicit-joining}@anchor{1e10}@anchor{reference/lexical_analysis implicit-line-joining}@anchor{1e11}
@subsubsection Continuation de ligne implicite


Les expressions entre parenthèses, crochets ou accolades peuvent être réparties sur plusieurs lignes sans utiliser de barre oblique inversée. Par exemple :

@example
month_names = ['Januari', 'Februari', 'Maart',      # These are the
               'April',   'Mei',      'Juni',       # Dutch names
               'Juli',    'Augustus', 'September',  # for the months
               'Oktober', 'November', 'December']   # of the year
@end example

Les lignes continuées implicitement peuvent avoir des commentaires. L'indentation des lignes de continuation n'est pas importante. Une ligne blanche est autorisée comme ligne de continuation. Il ne doit pas y avoir de lexème NEWLINE entre des lignes implicitement continuées. Les lignes continuées implicitement peuvent être utilisées dans des chaînes entre triples guillemets (voir ci-dessous) ; dans ce cas, elles ne peuvent pas avoir de commentaires.

@node Lignes vierges,Indentation,Continuation de ligne implicite,Structure des lignes
@anchor{reference/lexical_analysis blank-lines}@anchor{1e12}@anchor{reference/lexical_analysis id5}@anchor{1e13}
@subsubsection Lignes vierges


@geindex blank line

Une ligne logique qui ne contient que des espaces, tabulations, caractères de saut de page (`formfeed' en anglais) ou commentaires est ignorée (c'est-à-dire que le lexème NEWLINE n'est pas produit). Pendant l'édition interactive d'instructions, la gestion des lignes vierges peut différer en fonction de l'implémentation de la boucle REPL. Dans l'interpréteur standard, une ligne complètement vierge (c'est-à-dire ne contenant strictement rien, même pas une espace ou un commentaire) termine une instruction multi-lignes.

@node Indentation,Espaces entre lexèmes,Lignes vierges,Structure des lignes
@anchor{reference/lexical_analysis id6}@anchor{1e14}@anchor{reference/lexical_analysis indentation}@anchor{1e15}
@subsubsection Indentation


@geindex indentation
@geindex leading whitespace
@geindex space
@geindex tab
@geindex grouping
@geindex statement grouping

Des espaces ou tabulations au début d’une ligne logique sont utilisées pour connaître le niveau d’indentation de la ligne, qui est ensuite utilisé pour déterminer comment les instructions sont groupées.

Les tabulations sont remplacées (de la gauche vers la droite) par une à huit espaces de manière à ce que le nombre de caractères remplacés soit un multiple de huit (nous avons ainsi la même règle que celle d'Unix). Le nombre total d'espaces précédant le premier caractère non blanc détermine alors le niveau d'indentation de la ligne. L'indentation ne peut pas être répartie sur plusieurs lignes physiques à l'aide de barres obliques inversées ; les espaces jusqu'à la première barre oblique inversée déterminent l'indentation.

L'indentation est déclarée inconsistante et rejetée si, dans un même fichier source, le mélange des tabulations et des espaces est tel que la signification dépend du nombre d'espaces que représente une tabulation. Une exception @ref{52e,,TabError} est levée dans ce cas.

`Note de compatibilité entre les plateformes :' en raison de la nature des éditeurs de texte sur les plateformes non Unix, il n'est pas judicieux d'utiliser un mélange d'espaces et de tabulations pour l'indentation dans un seul fichier source. Il convient également de noter que des plateformes peuvent explicitement limiter le niveau d'indentation maximal.

Un caractère de saut de page peut être présent au début de la ligne ; il est ignoré pour les calculs d'indentation ci-dessus. Les caractères de saut de page se trouvant ailleurs avec les espaces en tête de ligne ont un effet indéfini (par exemple, ils peuvent remettre à zéro le nombre d'espaces).

@geindex INDENT token
@geindex DEDENT token

Les niveaux d'indentation de lignes consécutives sont utilisés pour générer les lexèmes INDENT et DEDENT, en utilisant une pile, de cette façon :

Avant que la première ligne du fichier ne soit lue, un « zéro » est posé sur la pile ; il ne sera plus jamais enlevé. Les nombres empilés sont toujours strictement croissants de bas en haut. Au début de chaque ligne logique, le niveau d'indentation de la ligne est comparé au sommet de la pile. S'ils sont égaux, il ne se passe rien. S'il est plus grand, il est empilé et un lexème INDENT est produit. S'il est plus petit, il `doit' être l'un des nombres présents dans la pile ; tous les nombres de la pile qui sont plus grands sont retirés et, pour chaque nombre retiré, un lexème DEDENT est produit. À la fin du fichier, un lexème DEDENT est produit pour chaque nombre supérieur à zéro restant sur la pile.

Voici un exemple de code Python correctement indenté (bien que très confus) :

@example
def perm(l):
        # Compute the list of all permutations of l
    if len(l) <= 1:
                  return [l]
    r = []
    for i in range(len(l)):
             s = l[:i] + l[i+1:]
             p = perm(s)
             for x in p:
              r.append(l[i:i+1] + x)
    return r
@end example

L'exemple suivant montre plusieurs erreurs d'indentation :

@example
 def perm(l):                       # error: first line indented
for i in range(len(l)):             # error: not indented
    s = l[:i] + l[i+1:]
        p = perm(l[:i] + l[i+1:])   # error: unexpected indent
        for x in p:
                r.append(l[i:i+1] + x)
            return r                # error: inconsistent dedent
@end example

En fait, les trois premières erreurs sont détectées par l'analyseur syntaxique ; seule la dernière erreur est trouvée par l'analyseur lexical (l'indentation de @code{return r} ne correspond à aucun niveau dans la pile).

@node Espaces entre lexèmes,,Indentation,Structure des lignes
@anchor{reference/lexical_analysis whitespace}@anchor{1e16}@anchor{reference/lexical_analysis whitespace-between-tokens}@anchor{1e17}
@subsubsection Espaces entre lexèmes


Sauf au début d'une ligne logique ou dans les chaînes de caractères, les caractères « blancs » espace, tabulation et saut de page peuvent être utilisés de manière interchangeable pour séparer les lexèmes. Un blanc n'est nécessaire entre deux lexèmes que si leur concaténation pourrait être interprétée comme un lexème différent (par exemple, ab est un lexème, mais a b comporte deux lexèmes).

@node Autres lexèmes,Identifiants et mots-clés,Structure des lignes,Analyse lexicale
@anchor{reference/lexical_analysis id7}@anchor{1e18}@anchor{reference/lexical_analysis other-tokens}@anchor{1e19}
@subsection Autres lexèmes


Outre NEWLINE, INDENT et DEDENT, il existe les catégories de lexèmes suivantes : `identifiants', `mots clés', `littéraux', `opérateurs' et `délimiteurs'. Les blancs (autres que les fins de lignes, vus auparavant) ne sont pas des lexèmes mais servent à délimiter les lexèmes. Quand une ambiguïté existe, le lexème correspond à la plus grande chaîne possible qui forme un lexème licite, en lisant de la gauche vers la droite.

@node Identifiants et mots-clés,Littéraux,Autres lexèmes,Analyse lexicale
@anchor{reference/lexical_analysis identifiers}@anchor{1e1a}@anchor{reference/lexical_analysis identifiers-and-keywords}@anchor{1e1b}
@subsection Identifiants et mots-clés


@geindex identifier
@geindex name

Les identifiants (aussi appelés `noms') sont décrits par les définitions lexicales suivantes.

La syntaxe des identifiants en Python est basée sur l'annexe UAX-31 du standard Unicode avec les modifications définies ci-dessous ; consultez la 
@geindex Python Enhancement Proposals; PEP 3131
PEP 3131@footnote{https://peps.python.org/pep-3131/} pour plus de détails.

Within the ASCII range (U+0001..U+007F), the valid characters for identifiers
include the uppercase and lowercase letters @code{A} through
@code{Z}, the underscore @code{_} and, except for the first character, the digits
@code{0} through @code{9}.
Python 3.0 introduced additional characters from outside the ASCII range (see
@geindex Python Enhancement Proposals; PEP 3131
PEP 3131@footnote{https://peps.python.org/pep-3131/}).  For these characters, the classification uses the version of the
Unicode Character Database as included in the @ref{104,,unicodedata} module.

Les identifiants n'ont pas de limite de longueur. La casse est prise en compte.

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-identifier}@anchor{1e1c}identifier   ::= xid_start xid_continue*
@anchor{reference/lexical_analysis grammar-token-python-grammar-id_start}@anchor{1e1d}id_start     ::= <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
@anchor{reference/lexical_analysis grammar-token-python-grammar-id_continue}@anchor{1e1e}id_continue  ::= <all characters in id_start, plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
@anchor{reference/lexical_analysis grammar-token-python-grammar-xid_start}@anchor{1e1f}xid_start    ::= <all characters in id_start whose NFKC normalization is in "id_start xid_continue*">
@anchor{reference/lexical_analysis grammar-token-python-grammar-xid_continue}@anchor{1e20}xid_continue ::= <all characters in id_continue whose NFKC normalization is in "id_continue*">
@end example

Les codes de catégories Unicode cités ci-dessus signifient :


@itemize *

@item 
`Lu' — lettres majuscules

@item 
`Ll' — lettres minuscules

@item 
`Lt' — lettres majuscules particulières (catégorie `titlecase' de l'Unicode)

@item 
`Lm' — lettres modificatives avec chasse

@item 
`Lo' — autres lettres

@item 
`Nl' — nombres lettres (par exemple, les nombres romains)

@item 
`Mn' — symboles que l'on combine avec d'autres (accents ou autres) sans générer d'espace (`nonspacing marks' en anglais)

@item 
`Mc' — symboles que l'on combine avec d'autres en générant une espace (`spacing combining marks' en anglais)

@item 
`Nd' — chiffres (arabes et autres)

@item 
`Pc' — connecteurs (tirets et autres lignes)

@item 
`Other_ID_Start' - explicit list of characters in PropList.txt@footnote{https://www.unicode.org/Public/15.1.0/ucd/PropList.txt} to support backwards
compatibility

@item 
`Other_ID_Continue' — pareillement
@end itemize

Tous les identifiants sont convertis dans la forme normale NFKC pendant l'analyse syntaxique : la comparaison des identifiants se base sur leur forme NFKC.

A non-normative HTML file listing all valid identifier characters for Unicode
15.1.0 can be found at
@indicateurl{https://www.unicode.org/Public/15.1.0/ucd/DerivedCoreProperties.txt}

@menu
* Mots-clés:: 
* Mots-clés ad hoc:: 
* Classes réservées pour les identifiants:: 

@end menu

@node Mots-clés,Mots-clés ad hoc,,Identifiants et mots-clés
@anchor{reference/lexical_analysis id8}@anchor{1e21}@anchor{reference/lexical_analysis keywords}@anchor{1e22}
@subsubsection Mots-clés


@geindex keyword
@geindex reserved word

Les identifiants suivants sont des mots réservés par le langage et ne peuvent pas être utilisés en tant qu'identifiants normaux. Ils doivent être écrits exactement comme ci-dessous :

@example
False      await      else       import     pass
None       break      except     in         raise
True       class      finally    is         return
and        continue   for        lambda     try
as         def        from       nonlocal   while
assert     del        global     not        with
async      elif       if         or         yield
@end example

@node Mots-clés ad hoc,Classes réservées pour les identifiants,Mots-clés,Identifiants et mots-clés
@anchor{reference/lexical_analysis id9}@anchor{1e23}@anchor{reference/lexical_analysis soft-keywords}@anchor{7f6}
@subsubsection Mots-clés ad hoc


@geindex soft keyword
@geindex keyword


Ajouté dans la version 3.10.


Some identifiers are only reserved under specific contexts. These are known as
`soft keywords'.  The identifiers @code{match}, @code{case}, @code{type} and @code{_} can
syntactically act as keywords in certain contexts,
but this distinction is done at the parser level, not when tokenizing.

As soft keywords, their use in the grammar is possible while still
preserving compatibility with existing code that uses these names as
identifier names.

@code{match}, @code{case}, and @code{_} are used in the @ref{7f7,,match} statement.
@code{type} is used in the @ref{421,,type} statement.


Modifié dans la version 3.12: @code{type} is now a soft keyword.


@geindex _@comma{} identifiers
@geindex __@comma{} identifiers

@node Classes réservées pour les identifiants,,Mots-clés ad hoc,Identifiants et mots-clés
@anchor{reference/lexical_analysis id-classes}@anchor{1e24}@anchor{reference/lexical_analysis reserved-classes-of-identifiers}@anchor{1e25}
@subsubsection Classes réservées pour les identifiants


Certaines classes d'identifiants (outre les mots-clés) ont une signification particulière. Ces classes se reconnaissent par des caractères de soulignement en tête et en queue d'identifiant :


@table @asis

@item @code{_*}

N'est pas importé par @code{from module import *}.

@item @code{_}

Dans un motif @code{case} d'une instruction @ref{7f7,,match}, @code{_} est un @ref{7f6,,mot-clé ad hoc} qui décrit un motif @ref{7f8,,attrape-tout}.

De son côté, l'interpréteur interactif place le résultat de la dernière évaluation dans la variable @code{-} (son emplacement se situe dans le module @ref{12,,builtins}, avec les fonctions natives telles que @code{print}).

Ailleurs, @code{_} est un identifiant comme un autre. Il est souvent utilisé pour désigner des éléments « spéciaux », mais il n'est pas spécial pour Python en tant que tel.

@cartouche
@quotation Note 
Le nom @code{_} est souvent utilisé pour internationaliser l'affichage ; reportez-vous à la documentation du module @ref{62,,gettext} pour plus d'informations sur cette convention.

Il est aussi communément utilisé pour signifier que la variable n'est pas utilisée.
@end quotation
@end cartouche

@item @code{__*__}

Noms définis par le système, appelés noms « `dunder' » (pour `Double Underscores') de manière informelle. Ces noms sont définis par l'interpréteur et son implémentation (y compris la bibliothèque standard). Les noms actuels définis par le système sont abordés dans la section @ref{c5c,,Méthodes spéciales}, mais aussi ailleurs. D'autres noms seront probablement définis dans les futures versions de Python. Toute utilisation de noms de la forme @code{__*__}, dans n'importe quel contexte, qui n'est pas conforme à ce qu'indique explicitement la documentation, est sujette à des mauvaises surprises sans avertissement.

@item @code{__*}

Noms privés pour une classe. Les noms de cette forme, lorsqu'ils sont utilisés dans le contexte d'une définition de classe, sont réécrits sous une forme modifiée pour éviter les conflits de noms entre les attributs « privés » des classes de base et les classes dérivées. Voir la section @ref{1e26,,Identifiants (noms)}.
@end table

@node Littéraux,Opérateurs,Identifiants et mots-clés,Analyse lexicale
@anchor{reference/lexical_analysis id10}@anchor{1e27}@anchor{reference/lexical_analysis literals}@anchor{1e28}
@subsection Littéraux


@geindex literal
@geindex constant

Les littéraux sont des notations pour indiquer des valeurs constantes de certains types natifs.

@geindex string literal
@geindex bytes literal
@geindex ASCII
@geindex ' (single quote);string literal
@geindex " (double quote);string literal
@geindex u';string literal
@geindex u";string literal

@menu
* Littéraux de chaînes de caractères et de suites d'octets:: 
* Concaténation de chaînes de caractères:: 
* f-strings:: 
* Littéraux numériques:: 
* Entiers littéraux:: 
* Floating-point literals:: 
* Imaginaires littéraux:: 

@end menu

@node Littéraux de chaînes de caractères et de suites d'octets,Concaténation de chaînes de caractères,,Littéraux
@anchor{reference/lexical_analysis string-and-bytes-literals}@anchor{1e29}@anchor{reference/lexical_analysis strings}@anchor{1e2a}
@subsubsection Littéraux de chaînes de caractères et de suites d'octets


Les chaînes de caractères littérales sont définies par les définitions lexicales suivantes :

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringliteral}@anchor{1e2b}stringliteral   ::= [stringprefix](shortstring | longstring)
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringprefix}@anchor{1e2c}stringprefix    ::= "r" | "u" | "R" | "U" | "f" | "F"
                    | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
@anchor{reference/lexical_analysis grammar-token-python-grammar-shortstring}@anchor{1e2d}shortstring     ::= "'" shortstringitem* "'" | '"' shortstringitem* '"'
@anchor{reference/lexical_analysis grammar-token-python-grammar-longstring}@anchor{1e2e}longstring      ::= "'@w{'}'" longstringitem* "'@w{'}'" | '"""' longstringitem* '"""'
@anchor{reference/lexical_analysis grammar-token-python-grammar-shortstringitem}@anchor{1e2f}shortstringitem ::= shortstringchar | stringescapeseq
@anchor{reference/lexical_analysis grammar-token-python-grammar-longstringitem}@anchor{1e30}longstringitem  ::= longstringchar | stringescapeseq
@anchor{reference/lexical_analysis grammar-token-python-grammar-shortstringchar}@anchor{1e31}shortstringchar ::= <any source character except "\" or newline or the quote>
@anchor{reference/lexical_analysis grammar-token-python-grammar-longstringchar}@anchor{1e32}longstringchar  ::= <any source character except "\">
@anchor{reference/lexical_analysis grammar-token-python-grammar-stringescapeseq}@anchor{1e33}stringescapeseq ::= "\" <any source character>
@end example

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-bytesliteral}@anchor{1e34}bytesliteral   ::= bytesprefix(shortbytes | longbytes)
@anchor{reference/lexical_analysis grammar-token-python-grammar-bytesprefix}@anchor{1e35}bytesprefix    ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
@anchor{reference/lexical_analysis grammar-token-python-grammar-shortbytes}@anchor{1e36}shortbytes     ::= "'" shortbytesitem* "'" | '"' shortbytesitem* '"'
@anchor{reference/lexical_analysis grammar-token-python-grammar-longbytes}@anchor{1e37}longbytes      ::= "'@w{'}'" longbytesitem* "'@w{'}'" | '"""' longbytesitem* '"""'
@anchor{reference/lexical_analysis grammar-token-python-grammar-shortbytesitem}@anchor{1e38}shortbytesitem ::= shortbyteschar | bytesescapeseq
@anchor{reference/lexical_analysis grammar-token-python-grammar-longbytesitem}@anchor{1e39}longbytesitem  ::= longbyteschar | bytesescapeseq
@anchor{reference/lexical_analysis grammar-token-python-grammar-shortbyteschar}@anchor{1e3a}shortbyteschar ::= <any ASCII character except "\" or newline or the quote>
@anchor{reference/lexical_analysis grammar-token-python-grammar-longbyteschar}@anchor{1e3b}longbyteschar  ::= <any ASCII character except "\">
@anchor{reference/lexical_analysis grammar-token-python-grammar-bytesescapeseq}@anchor{1e3c}bytesescapeseq ::= "\" <any ASCII character>
@end example

Une restriction syntaxique non indiquée par ces règles est qu'aucun blanc n'est autorisé entre le @ref{1e2c,,stringprefix} ou @ref{1e35,,bytesprefix} et le reste du littéral. Le jeu de caractères source est défini par la déclaration d'encodage ; il vaut UTF-8 si aucune déclaration d'encodage n'est donnée dans le fichier source ; voir la section @ref{1e0d,,Déclaration d'encodage}.

@geindex triple-quoted string
@geindex Unicode Consortium
@geindex raw string
@geindex """;string literal
@geindex '@w{'}';string literal

In plain English: Both types of literals can be enclosed in matching single quotes
(@code{'}) or double quotes (@code{"}).  They can also be enclosed in matching groups
of three single or double quotes (these are generally referred to as
`triple-quoted strings'). The backslash (@code{\}) character is used to give special
meaning to otherwise ordinary characters like @code{n}, which means 'newline' when
escaped (@code{\n}). It can also be used to escape characters that otherwise have a
special meaning, such as newline, backslash itself, or the quote character.
See @ref{443,,escape sequences} below for examples.

@geindex b';bytes literal
@geindex b";bytes literal

Les littéraux de suites d'octets sont toujours préfixés par @code{'b'} ou @code{'B'} ; cela crée une instance de type @ref{1bd,,bytes} au lieu du type @ref{435,,str}. Ils ne peuvent contenir que des caractères ASCII ; les octets dont la valeur est supérieure ou égale à 128 doivent être exprimés à l'aide d'échappements.

@geindex r';raw string literal
@geindex r";raw string literal

Both string and bytes literals may optionally be prefixed with a letter @code{'r'}
or @code{'R'}; such constructs are called `raw string literals'
and `raw bytes literals' respectively and treat backslashes as
literal characters.  As a result, in raw string literals, @code{'\U'} and @code{'\u'}
escapes are not treated specially.


Ajouté dans la version 3.3: le préfixe @code{'rb'} a été ajouté comme synonyme de @code{'br'} pour les littéraux de suites d'octets.

la gestion du préfixe historique pour les chaînes Unicode (@code{u'chaine'}) a été réintroduite afin de simplifier la maintenance de code compatible Python 2.x et 3.x. Voir la 
@geindex Python Enhancement Proposals; PEP 414
PEP 414@footnote{https://peps.python.org/pep-0414/} pour davantage d'informations.


@geindex f';formatted string literal
@geindex f";formatted string literal

Une chaîne littérale qui contient @code{'f'} ou @code{'F'} dans le préfixe est une `chaîne de caractères littérale formatée' ; lisez @ref{997,,f-strings}. Le @code{'f'} peut être combiné avec @code{'r'} mais pas avec @code{'b'} ou @code{'u'}, donc les chaînes de caractères formatées sont possibles mais les littéraux de suites d'octets ne peuvent pas l'être.

Dans les chaînes entre triples guillemets, les sauts de ligne et guillemets peuvent ne pas être échappés (et sont donc pris en compte), mais trois guillemets non échappés à la suite terminent le littéral (on entend par guillemet le caractère utilisé pour commencer le littéral, c'est-à-dire @code{'} ou @code{"}).

@geindex physical line
@geindex escape sequence
@geindex Standard C
@geindex C
@geindex \ (backslash);escape sequence
@geindex \\;escape sequence
@geindex \a;escape sequence
@geindex \b;escape sequence
@geindex \f;escape sequence
@geindex \n;escape sequence
@geindex \r;escape sequence
@geindex \t;escape sequence
@geindex \v;escape sequence
@geindex \x;escape sequence
@geindex \N;escape sequence
@geindex \u;escape sequence
@geindex \U;escape sequence

@menu
* Escape sequences:: 

@end menu

@node Escape sequences,,,Littéraux de chaînes de caractères et de suites d'octets
@anchor{reference/lexical_analysis escape-sequences}@anchor{443}@anchor{reference/lexical_analysis id11}@anchor{1e3d}
@subsubsection Escape sequences


À moins que le préfixe @code{'r'} ou @code{'R'} ne soit présent, les séquences d'échappement dans les littéraux de chaînes et suites d'octets sont interprétées comme elles le seraient par le C Standard. Les séquences d'échappement reconnues sont :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Séquence d'échappement

@tab

Signification

@tab

Notes

@item

@code{\}<newline>

@tab

barre oblique inversée et retour à la ligne ignorés

@tab

(1)

@item

@code{\\}

@tab

barre oblique inversée (@code{\})

@tab

@item

@code{\'}

@tab

guillemet simple (@code{'})

@tab

@item

@code{\"}

@tab

guillemet double (@code{"})

@tab

@item

@code{\a}

@tab

cloche ASCII (BEL)

@tab

@item

@code{\b}

@tab

retour arrière ASCII (BS)

@tab

@item

@code{\f}

@tab

saut de page ASCII (FF)

@tab

@item

@code{\n}

@tab

saut de ligne ASCII (LF)

@tab

@item

@code{\r}

@tab

retour à la ligne ASCII (CR)

@tab

@item

@code{\t}

@tab

tabulation horizontale ASCII (TAB)

@tab

@item

@code{\v}

@tab

tabulation verticale ASCII (VT)

@tab

@item

@code{\@var{ooo}}

@tab

caractère dont le code est `ooo' en octal

@tab

(2,4)

@item

@code{\x@var{hh}}

@tab

caractère dont le code est `ooo' en hexadécimal

@tab

(3,4)

@end multitable


Les séquences d'échappement reconnues seulement dans les chaînes littérales sont :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Séquence d'échappement

@tab

Signification

@tab

Notes

@item

@code{\N@{@var{name}@}}

@tab

caractère dont le nom est `name' dans la base de données Unicode

@tab

(5)

@item

@code{\u@var{xxxx}}

@tab

caractère dont le code est `xxxx' en hexadécimal

@tab

(6)

@item

@code{\U@var{xxxxxxxx}}

@tab

caractère dont le code est `xxxxxxxx' en hexadécimal sur 32 bits

@tab

(7)

@end multitable


Notes :


@enumerate 

@item 
A backslash can be added at the end of a line to ignore the newline:

@example
>>> 'This string will not include \
... backslashes or newline characters.'
'This string will not include backslashes or newline characters.'
@end example

The same result can be achieved using @ref{1e2a,,triple-quoted strings},
or parentheses and @ref{1e3e,,string literal concatenation}.

@item 
Comme dans le C Standard, jusqu'à trois chiffres en base huit sont acceptés.


Modifié dans la version 3.11: Octal escapes with value larger than @code{0o377} produce a
@ref{1a3,,DeprecationWarning}.



Modifié dans la version 3.12: Octal escapes with value larger than @code{0o377} produce a
@ref{44f,,SyntaxWarning}. In a future Python version they will be eventually
a @ref{18b,,SyntaxError}.


@item 
Contrairement au C Standard, il est obligatoire de fournir deux chiffres hexadécimaux.

@item 
Dans un littéral de suite d'octets, un échappement hexadécimal ou octal est un octet dont la valeur est donnée. Dans une chaîne littérale, un échappement est un caractère Unicode dont le code est donné.

@item 

Modifié dans la version 3.3: Ajout du support pour les alias de noms @footnote{
@indicateurl{https://www.unicode.org/Public/15.1.0/ucd/NameAliases.txt}
}.


@item 
Exactement quatre chiffres hexadécimaux sont requis.

@item 
N'importe quel caractère Unicode peut être encodé de cette façon. Exactement huit chiffres hexadécimaux sont requis.
@end enumerate

@geindex unrecognized escape sequence

Contrairement au C standard, toutes les séquences d'échappement non reconnues sont laissées inchangées dans la chaîne, c'est-à-dire que `la barre oblique inversée est laissée dans le résultat' (ce comportement est utile en cas de débogage : si une séquence d'échappement est mal tapée, la sortie résultante est plus facilement reconnue comme source de l'erreur). Notez bien également que les séquences d'échappement reconnues uniquement dans les littéraux de chaînes de caractères ne sont pas reconnues pour les littéraux de suites d'octets.


Modifié dans la version 3.6: Unrecognized escape sequences produce a @ref{1a3,,DeprecationWarning}.



Modifié dans la version 3.12: Unrecognized escape sequences produce a @ref{44f,,SyntaxWarning}. In a future
Python version they will be eventually a @ref{18b,,SyntaxError}.


Même dans une chaîne littérale brute, les guillemets peuvent être échappés avec une barre oblique inversée mais la barre oblique inversée reste dans le résultat ; par exemple, @code{r"\""} est une chaîne de caractères valide composée de deux caractères : une barre oblique inversée et un guillemet double ; @code{r"\"} n'est pas une chaîne de caractères valide (même une chaîne de caractères brute ne peut pas se terminer par un nombre impair de barres obliques inversées). Plus précisément, `une chaîne littérale brute ne peut pas se terminer par une seule barre oblique inversée' (puisque la barre oblique inversée échappe le guillemet suivant). Notez également qu'une simple barre oblique inversée suivie d'un saut de ligne est interprétée comme deux caractères faisant partie du littéral et `non' comme une continuation de ligne.

@node Concaténation de chaînes de caractères,f-strings,Littéraux de chaînes de caractères et de suites d'octets,Littéraux
@anchor{reference/lexical_analysis string-concatenation}@anchor{1e3e}@anchor{reference/lexical_analysis string-literal-concatenation}@anchor{1e3f}
@subsubsection Concaténation de chaînes de caractères


Plusieurs chaînes de caractères ou suites d'octets adjacentes (séparées par des blancs), utilisant éventuellement des conventions de guillemets différentes, sont autorisées. La signification est la même que leur concaténation. Ainsi, @code{"hello" 'world'} est l'équivalent de @code{"helloworld"}. Cette fonctionnalité peut être utilisée pour réduire le nombre de barres obliques inverses, pour diviser de longues chaînes de caractères sur plusieurs lignes ou même pour ajouter des commentaires à des portions de chaînes de caractères. Par exemple :

@example
re.compile("[A-Za-z_]"       # letter or underscore
           "[A-Za-z0-9_]*"   # letter, digit or underscore
          )
@end example

Notez que cette fonctionnalité agit au niveau syntaxique mais est implémentée au moment de la compilation. Pour concaténer les expressions des chaînes de caractères au moment de l'exécution, vous devez utiliser l'opérateur @code{+}. Notez également que la concaténation littérale peut utiliser un style différent de guillemets pour chaque composant (et même mélanger des chaînes de caractères brutes et des chaînes de caractères entre triples guillemets). Enfin, les chaînes de caractères formatées peuvent être concaténées avec des chaînes de caractères ordinaires.

@geindex formatted string literal
@geindex interpolated string literal
@geindex string;formatted literal
@geindex string;interpolated literal
@geindex f-string
@geindex fstring
@geindex @{@} (curly brackets);in formatted string literal
@geindex ! (exclamation);in formatted string literal
@geindex ; (colon);in formatted string literal
@geindex = (equals);for help in debugging using string literals
@anchor{reference/lexical_analysis f-strings}@anchor{997}
@node f-strings,Littéraux numériques,Concaténation de chaînes de caractères,Littéraux
@anchor{reference/lexical_analysis formatted-string-literals}@anchor{1e40}@anchor{reference/lexical_analysis id13}@anchor{1e41}
@subsubsection f-strings



Ajouté dans la version 3.6.


Une `chaine de caractères littérale formatée' ou `f-string' est une chaine de caractères littérale préfixée par @code{'f'} ou @code{'F'}. Ces chaines peuvent contenir des champs à remplacer, c'est-à-dire des expressions délimitées par des accolades @code{@{@}}. Alors que les autres littéraux de chaines ont des valeurs constantes, les chaines formatées sont de vraies expressions évaluées à l'exécution.

Les séquences d'échappement sont décodées comme à l'intérieur des chaînes de caractères ordinaires (sauf lorsqu'une chaîne de caractères est également marquée comme une chaîne brute). Après décodage, la grammaire s'appliquant au contenu de la chaîne de caractères est :

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_string}@anchor{1e42}f_string          ::= (literal_char | "@{@{" | "@}@}" | replacement_field)*
@anchor{reference/lexical_analysis grammar-token-python-grammar-replacement_field}@anchor{1e43}replacement_field ::= "@{" f_expression ["="] ["!" conversion] [":" format_spec] "@}"
@anchor{reference/lexical_analysis grammar-token-python-grammar-f_expression}@anchor{1e44}f_expression      ::= (conditional_expression | "*" or_expr)
                        ("," conditional_expression | "," "*" or_expr)* [","]
                      | yield_expression
@anchor{reference/lexical_analysis grammar-token-python-grammar-conversion}@anchor{1e45}conversion        ::= "s" | "r" | "a"
@anchor{reference/lexical_analysis grammar-token-python-grammar-format_spec}@anchor{1e46}format_spec       ::= (literal_char | replacement_field)*
@anchor{reference/lexical_analysis grammar-token-python-grammar-literal_char}@anchor{1e47}literal_char      ::= <any code point except "@{", "@}" or NULL>
@end example

Les portions qui sont en dehors des accolades sont traitées comme les littéraux, sauf les doubles accolades @code{'@{@{'} ou @code{'@}@}'} qui sont remplacées par la simple accolade correspondante. Une simple accolade ouvrante @code{'@{'} marque le début du champ à remplacer, qui commence par une expression Python. Pour afficher à la fois le texte de l'expression et sa valeur une fois évaluée (utile lors du débogage), un signe égal @code{'='} peut être ajouté après l'expression. Ensuite, il peut y avoir un champ de conversion, introduit par un point d'exclamation @code{'!'}. Une spécification de format peut aussi être rajoutée, introduite par le caractère deux-points @code{':'}. Le champ à remplacer se termine par une accolade fermante @code{'@}'}.

Expressions in formatted string literals are treated like regular
Python expressions surrounded by parentheses, with a few exceptions.
An empty expression is not allowed, and both @ref{127a,,lambda}  and
assignment expressions @code{:=} must be surrounded by explicit parentheses.
Each expression is evaluated in the context where the formatted string literal
appears, in order from left to right.  Replacement expressions can contain
newlines in both single-quoted and triple-quoted f-strings and they can contain
comments.  Everything that comes after a @code{#} inside a replacement field
is a comment (even closing braces and quotes). In that case, replacement fields
must be closed in a different line.

@example
>>> f"abc@{a # This is a comment @}"
... + 3@}"
'abc5'
@end example


Modifié dans la version 3.7: Avant Python 3.7, il était illégal d’utiliser @ref{1b7,,await} ainsi que les compréhensions utilisant @ref{a99,,async for} dans les expressions au sein des chaînes de caractères formatées littérales à cause d’un problème dans l’implémentation.



Modifié dans la version 3.12: Prior to Python 3.12, comments were not allowed inside f-string replacement
fields.


Lorsqu'un signe égal @code{'='} est présent, la sortie comprend le texte de l'expression, le signe @code{'='} et la valeur calculée. Les espaces après l'accolade ouvrante @code{'@{'}, dans l'expression et après le signe @code{'='} sont conservées à l'affichage. Par défaut, le signe @code{'='} utilise la @ref{7e7,,repr()} de l'expression, sauf si un format est indiqué. Quand le format est indiqué, c'est @ref{435,,str()} de l'expression qui est utilisée à moins qu'une conversion @code{!r} ne soit déclarée.


Ajouté dans la version 3.8: le signe égal @code{'='}.


Si une conversion est spécifiée, le résultat de l'évaluation de l'expression est converti avant d'être formaté. La conversion @code{'!s'} appelle @ref{435,,str()} sur le résultat, @code{'!r'} appelle @ref{7e7,,repr()} et @code{'!a'} appelle @ref{139d,,ascii()}.

The result is then formatted using the @ref{60a,,format()} protocol.  The
format specifier is passed to the @ref{609,,__format__()} method of the
expression or conversion result.  An empty string is passed when the
format specifier is omitted.  The formatted result is then included in
the final value of the whole string.

Top-level format specifiers may include nested replacement fields. These nested
fields may include their own conversion fields and @ref{1e5,,format specifiers}, but may not include more deeply nested replacement fields. The
@ref{1e5,,format specifier mini-language} is the same as that used by
the @ref{60c,,str.format()} method.

Les chaînes formatées littérales peuvent être concaténées mais les champs à remplacer ne peuvent pas être divisés entre les littéraux.

Quelques exemples de chaines formatées littérales :

@example
>>> name = "Fred"
>>> f"He said his name is @{name!r@}."
"He said his name is 'Fred'."
>>> f"He said his name is @{repr(name)@}."  # repr() is equivalent to !r
"He said his name is 'Fred'."
>>> width = 10
>>> precision = 4
>>> value = decimal.Decimal("12.34567")
>>> f"result: @{value:@{width@}.@{precision@}@}"  # nested fields
'result:      12.35'
>>> today = datetime(year=2017, month=1, day=27)
>>> f"@{today:%B %d, %Y@}"  # using date format specifier
'January 27, 2017'
>>> f"@{today=:%B %d, %Y@}" # using date format specifier and debugging
'today=January 27, 2017'
>>> number = 1024
>>> f"@{number:#0x@}"  # using integer format specifier
'0x400'
>>> foo = "bar"
>>> f"@{ foo = @}" # preserves whitespace
" foo = 'bar'"
>>> line = "The mill's closed"
>>> f"@{line = @}"
'line = "The mill\'s closed"'
>>> f"@{line = :20@}"
"line = The mill's closed   "
>>> f"@{line = !r:20@}"
'line = "The mill\'s closed" '
@end example

Reusing the outer f-string quoting type inside a replacement field is
permitted:

@example
>>> a = dict(x=2)
>>> f"abc @{a["x"]@} def"
'abc 2 def'
@end example


Modifié dans la version 3.12: Prior to Python 3.12, reuse of the same quoting type of the outer f-string
inside a replacement field was not possible.


Backslashes are also allowed in replacement fields and are evaluated the same
way as in any other context:

@example
>>> a = ["a", "b", "c"]
>>> print(f"List a contains:\n@{"\n".join(a)@}")
List a contains:
a
b
c
@end example


Modifié dans la version 3.12: Prior to Python 3.12, backslashes were not permitted inside an f-string
replacement field.


Une chaine formatée littérale ne peut pas être utilisée en tant que `docstring', même si elle ne comporte pas d'expression.

@example
>>> def foo():
...     f"Not a docstring"
...
>>> foo.__doc__ is None
True
@end example

Consultez aussi la 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/} qui propose l'ajout des chaines formatées littérales et @ref{60c,,str.format()} qui utilise un mécanisme similaire pour formater les chaînes de caractères.

@node Littéraux numériques,Entiers littéraux,f-strings,Littéraux
@anchor{reference/lexical_analysis numbers}@anchor{1e48}@anchor{reference/lexical_analysis numeric-literals}@anchor{1e49}
@subsubsection Littéraux numériques


@geindex number
@geindex numeric literal
@geindex integer literal
@geindex floating-point literal
@geindex hexadecimal literal
@geindex octal literal
@geindex binary literal
@geindex decimal literal
@geindex imaginary literal
@geindex 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).

Notez que les littéraux numériques ne comportent pas de signe ; une phrase telle que @code{-1} est en fait une expression composée de l'opérateur unitaire @code{-} et du littéral @code{1}.

@geindex 0b;integer literal
@geindex 0o;integer literal
@geindex 0x;integer literal
@geindex _ (underscore);in numeric literal

@node Entiers littéraux,Floating-point literals,Littéraux numériques,Littéraux
@anchor{reference/lexical_analysis integer-literals}@anchor{1e4a}@anchor{reference/lexical_analysis integers}@anchor{1e4b}
@subsubsection Entiers littéraux


Les entiers littéraux sont décrits par les définitions lexicales suivantes :

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-integer}@anchor{1e4c}integer      ::= decinteger | bininteger | octinteger | hexinteger
@anchor{reference/lexical_analysis grammar-token-python-grammar-decinteger}@anchor{1e4d}decinteger   ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] "0")*
@anchor{reference/lexical_analysis grammar-token-python-grammar-bininteger}@anchor{1e4e}bininteger   ::= "0" ("b" | "B") (["_"] bindigit)+
@anchor{reference/lexical_analysis grammar-token-python-grammar-octinteger}@anchor{1e4f}octinteger   ::= "0" ("o" | "O") (["_"] octdigit)+
@anchor{reference/lexical_analysis grammar-token-python-grammar-hexinteger}@anchor{1e50}hexinteger   ::= "0" ("x" | "X") (["_"] hexdigit)+
@anchor{reference/lexical_analysis grammar-token-python-grammar-nonzerodigit}@anchor{1e51}nonzerodigit ::= "1"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-digit}@anchor{1e52}digit        ::= "0"..."9"
@anchor{reference/lexical_analysis grammar-token-python-grammar-bindigit}@anchor{1e53}bindigit     ::= "0" | "1"
@anchor{reference/lexical_analysis grammar-token-python-grammar-octdigit}@anchor{1e54}octdigit     ::= "0"..."7"
@anchor{reference/lexical_analysis grammar-token-python-grammar-hexdigit}@anchor{1e55}hexdigit     ::= digit | "a"..."f" | "A"..."F"
@end example

Il n'y a pas de limite pour la longueur des entiers littéraux, sauf celle relative à la capacité mémoire.

Les tirets bas sont ignorés pour déterminer la valeur numérique du littéral. Ils peuvent être utilisés pour grouper les chiffres afin de faciliter la lecture. Un souligné peut être placé entre des chiffres ou après la spécification de la base telle que @code{0x}.

Notez que placer des zéros en tête de nombre pour un nombre décimal différent de zéro n'est pas autorisé. Cela permet d'éviter l’ambigüité avec les littéraux en base octale selon le style C que Python utilisait avant la version 3.0.

Quelques exemples d'entiers littéraux :

@example
7     2147483647                        0o177    0b100110111
3     79228162514264337593543950336     0o377    0xdeadbeef
      100_000_000_000                   0b_1110_0101
@end example


Modifié dans la version 3.6: Les tirets bas ne sont pas autorisés pour grouper les littéraux.


@geindex . (dot);in numeric literal
@geindex e;in numeric literal
@geindex _ (underscore);in numeric literal

@node Floating-point literals,Imaginaires littéraux,Entiers littéraux,Littéraux
@anchor{reference/lexical_analysis floating}@anchor{1e56}@anchor{reference/lexical_analysis floating-point-literals}@anchor{1e57}
@subsubsection Floating-point literals


Floating-point literals are described by the following lexical definitions:

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-floatnumber}@anchor{1e58}floatnumber   ::= pointfloat | exponentfloat
@anchor{reference/lexical_analysis grammar-token-python-grammar-pointfloat}@anchor{1e59}pointfloat    ::= [digitpart] fraction | digitpart "."
@anchor{reference/lexical_analysis grammar-token-python-grammar-exponentfloat}@anchor{1e5a}exponentfloat ::= (digitpart | pointfloat) exponent
@anchor{reference/lexical_analysis grammar-token-python-grammar-digitpart}@anchor{1e5b}digitpart     ::= digit (["_"] digit)*
@anchor{reference/lexical_analysis grammar-token-python-grammar-fraction}@anchor{1e5c}fraction      ::= "." digitpart
@anchor{reference/lexical_analysis grammar-token-python-grammar-exponent}@anchor{1e5d}exponent      ::= ("e" | "E") ["+" | "-"] digitpart
@end example

Note that the integer and exponent parts are always interpreted using radix 10.
For example, @code{077e010} is legal, and denotes the same number as @code{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:

@example
3.14    10.    .001    1e100    3.14e-10    0e0    3.14_15_93
@end example


Modifié dans la version 3.6: Les tirets bas ne sont pas autorisés pour grouper les littéraux.


@geindex j;in numeric literal

@node Imaginaires littéraux,,Floating-point literals,Littéraux
@anchor{reference/lexical_analysis imaginary}@anchor{1e5e}@anchor{reference/lexical_analysis imaginary-literals}@anchor{1e5f}
@subsubsection Imaginaires littéraux


Les nombres imaginaires sont décrits par les définitions lexicales suivantes :

@example
@anchor{reference/lexical_analysis grammar-token-python-grammar-imagnumber}@anchor{1e60}imagnumber ::= (floatnumber | digitpart) ("j" | "J")
@end example

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., @code{(3+4j)}.  Some examples of
imaginary literals:

@example
3.14j   10.j    10j     .001j   1e100j   3.14e-10j   3.14_15_93j
@end example

@node Opérateurs,Délimiteurs,Littéraux,Analyse lexicale
@anchor{reference/lexical_analysis id14}@anchor{1e61}@anchor{reference/lexical_analysis operators}@anchor{1e62}
@subsection Opérateurs


@geindex operators

Les lexèmes suivants sont des opérateurs :

@example
+       -       *       **      /       //      %      @@
<<      >>      &       |       ^       ~       :=
<       >       <=      >=      ==      !=
@end example

@node Délimiteurs,,Opérateurs,Analyse lexicale
@anchor{reference/lexical_analysis delimiters}@anchor{1e63}@anchor{reference/lexical_analysis id15}@anchor{1e64}
@subsection Délimiteurs


@geindex delimiters

Les lexèmes suivants servent de délimiteurs dans la grammaire :

@example
(       )       [       ]       @{       @}
,       :       !       .       ;       @@       =
->      +=      -=      *=      /=      //=     %=
@@=      &=      |=      ^=      >>=     <<=     **=
@end example

Le point peut aussi apparaître dans les littéraux de nombres à virgule flottante et imaginaires. Une suite de trois points possède une signification spéciale : c'est une ellipse littérale. La deuxième partie de la liste, les opérateurs d'affectation augmentés, servent de délimiteurs pour l'analyseur lexical mais sont aussi des opérateurs.

Les caractères ASCII suivants ont une signification spéciale en tant que partie d'autres lexèmes ou ont une signification particulière pour l'analyseur lexical :

@example
'       "       #       \
@end example

Les caractères ASCII suivants ne sont pas utilisés en Python. S'ils apparaissent en dehors de chaines littérales ou de commentaires, ils produisent une erreur :

@example
$       ?       `
@end example

@subsubheading Notes


@node Modèle de données,Modèle d'exécution,Analyse lexicale,La référence du langage Python
@anchor{reference/datamodel doc}@anchor{1e65}@anchor{reference/datamodel data-model}@anchor{1e66}@anchor{reference/datamodel datamodel}@anchor{18ff}
@section Modèle de données


@menu
* Objets@comma{} valeurs et types: Objets valeurs et types. 
* Hiérarchie des types standards:: 
* Méthodes spéciales:: 
* Coroutines:: 

@end menu

@node Objets valeurs et types,Hiérarchie des types standards,,Modèle de données
@anchor{reference/datamodel objects}@anchor{1e67}@anchor{reference/datamodel objects-values-and-types}@anchor{1e68}
@subsection Objets, valeurs et types


@geindex object
@geindex data

En Python, les données sont représentées sous forme `d'objets'. Toutes les données d'un programme Python sont représentées par des objets ou par des relations entre les objets (dans un certain sens, et en conformité avec le modèle de Von Neumann d'« ordinateur à programme enregistré », le code est aussi représenté par des objets).

@geindex built-in function;id
@geindex built-in function;type
@geindex identity of an object
@geindex value of an object
@geindex type of an object
@geindex mutable object
@geindex immutable object

@c XXX it *is* now possible in some cases to change an object's
@c type, under certain controlled conditions

Every object has an identity, a type and a value.  An object's `identity' never
changes once it has been created; you may think of it as the object's address in
memory.  The @ref{2e9,,is} operator compares the identity of two objects; the
@ref{13d9,,id()} function returns an integer representing its identity.

`Particularité de l'implémentation CPython :' en CPython, @code{id(x)} est l'adresse mémoire où est stocké @code{x}.

Le type de l'objet détermine les opérations que l'on peut appliquer à l'objet (par exemple, « a-t-il une longueur ? ») et définit aussi les valeurs possibles pour les objets de ce type. La fonction @ref{d36,,type()} renvoie le type de l'objet (qui est lui-même un objet). Comme l'identifiant, le `type' d'un objet ne peut pas être modifié @footnote{
Il `est' possible, dans certains cas, de changer le type d'un objet, sous certaines conditions. Cependant, ce n'est généralement pas une bonne idée car cela peut conduire à un comportement très étrange si ce n'est pas géré correctement.
}.

La `valeur' de certains objets peut changer. Les objets dont la valeur peut changer sont dits mutables ; les objets dont la valeur est définitivement fixée à leur création sont dits `immuables' (`immutable' en anglais). La valeur d'un objet conteneur immuable qui contient une référence vers un objet mutable peut varier lorsque la valeur de l'objet mutable change ; cependant, le conteneur est quand même considéré comme immuable parce que l'ensemble des objets qu'il contient ne peut pas être modifié. Ainsi, l'immuabilité n'est pas strictement équivalente au fait d'avoir une valeur non modifiable, c'est plus subtil. La muabilité d'un objet est définie par son type ; par exemple, les nombres, les chaînes de caractères et les `n'-uplets sont immuables alors que les dictionnaires et les listes sont mutables.

@geindex garbage collection
@geindex reference counting
@geindex unreachable object

Un objet n'est jamais explicitement détruit ; cependant, lorsqu'il ne peut plus être atteint, il a vocation à être supprimé par le ramasse-miettes (`garbage-collector' en anglais). L'implémentation peut retarder cette opération ou même ne pas la faire du tout — la façon dont fonctionne le ramasse-miette est particulière à chaque implémentation, l'important étant qu'il ne supprime pas d'objet qui peut encore être atteint.

`Particularité de l'implémentation CPython :' CPython utilise aujourd'hui un mécanisme de compteur de références avec une détection, en temps différé et optionnelle, des cycles d'objets. Ce mécanisme supprime la plupart des objets dès qu'ils ne sont plus accessibles mais il ne garantit pas la suppression des objets où il existe des références circulaires. Consultez la documentation du module @ref{5f,,gc} pour tout ce qui concerne la suppression des cycles. D'autres implémentations agissent différemment et CPython pourrait évoluer. Ne vous reposez pas sur la finalisation immédiate des objets devenus inaccessibles (ainsi, vous devez toujours fermer les fichiers explicitement).

Note that the use of the implementation's tracing or debugging facilities may
keep objects alive that would normally be collectable. Also note that catching
an exception with a @ref{6d3,,try}...@ref{189,,except} statement may keep
objects alive.

Some objects contain references to "external" resources such as open files or
windows.  It is understood that these resources are freed when the object is
garbage-collected, but since garbage collection is not guaranteed to happen,
such objects also provide an explicit way to release the external resource,
usually a @code{close()} method. Programs are strongly recommended to explicitly
close such objects.  The @ref{6d3,,try}...@ref{9b8,,finally} statement
and the @ref{5bc,,with} statement provide convenient ways to do this.

@geindex container

Certains objets contiennent des références à d'autres objets ; on les appelle `conteneurs'. Comme exemples de conteneurs, nous pouvons citer les `n'-uplets, les listes et les dictionnaires. Les références sont parties intégrantes de la valeur d'un conteneur. Dans la plupart des cas, lorsque nous parlons de la valeur d'un conteneur, nous parlons des valeurs, pas des identifiants des objets contenus ; cependant, lorsque nous parlons de la muabilité d'un conteneur, seuls les identifiants des objets immédiatement contenus sont concernés. Ainsi, si un conteneur immuable (comme un `n'-uplet) contient une référence à un objet mutable, sa valeur change si cet objet mutable est modifié.

Types affect almost all aspects of object behavior.  Even the importance of
object identity is affected in some sense: for immutable types, operations that
compute new values may actually return a reference to any existing object with
the same type and value, while for mutable objects this is not allowed.
For example, after @code{a = 1; b = 1}, `a' and `b' may or may not refer to
the same object with the value one, depending on the implementation.
This is because @ref{254,,int} is an immutable type, so the reference to @code{1}
can be reused. This behaviour depends on the implementation used, so should
not be relied upon, but is something to be aware of when making use of object
identity tests.
However, after @code{c = []; d = []}, `c' and `d' are guaranteed to refer to two
different, unique, newly created empty lists. (Note that @code{e = f = []} assigns
the `same' object to both `e' and `f'.)

@node Hiérarchie des types standards,Méthodes spéciales,Objets valeurs et types,Modèle de données
@anchor{reference/datamodel the-standard-type-hierarchy}@anchor{1e69}@anchor{reference/datamodel types}@anchor{1e6a}
@subsection Hiérarchie des types standards


@geindex type
@geindex data;type
@geindex type;hierarchy
@geindex extension;module
@geindex C;language

Vous trouvez ci-dessous une liste des types natifs de Python. Des modules d'extension (écrits en C, Java ou d'autres langages) peuvent définir des types supplémentaires. Les futures versions de Python pourront ajouter des types à cette hiérarchie (par exemple les nombres rationnels, des tableaux d'entiers stockés efficacement, etc.), bien que de tels ajouts se trouvent souvent plutôt dans la bibliothèque standard.

@geindex attribute
@geindex special;attribute
@geindex generic;special;attribute

Quelques descriptions des types ci-dessous contiennent un paragraphe listant des « attributs spéciaux ». Ces attributs donnent accès à l'implémentation et n'ont, en général, pas vocation à être utilisés. Leur définition peut changer dans le futur.

@menu
* None:: 
* NotImplemented:: 
* Ellipse:: 
* numbers.Number: numbers Number. 
* Séquences:: 
* Ensembles: Ensembles<2>. 
* Tableaux de correspondances:: 
* Types appelables:: 
* Modules: Modules<3>. 
* Classes déclarées par le développeur:: 
* Instances de classe: Instances de classe<2>. 
* Objets entrées-sorties (ou objets fichiers): Objets entrées-sorties ou objets fichiers. 
* Types internes:: 

@end menu

@node None,NotImplemented,,Hiérarchie des types standards
@anchor{reference/datamodel none}@anchor{1e6b}
@subsubsection @code{None}


@geindex object;`@w{`}None`@w{`}

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette valeur. Vous accédez à cet objet avec le nom natif @code{None}. Il est utilisé pour signifier l'absence de valeur dans de nombreux cas, par exemple pour des fonctions qui ne renvoient rien explicitement. Sa valeur booléenne est fausse.

@node NotImplemented,Ellipse,None,Hiérarchie des types standards
@anchor{reference/datamodel notimplemented}@anchor{1e6c}
@subsubsection NotImplemented


@geindex object;NotImplemented

This type has a single value.  There is a single object with this value. This
object is accessed through the built-in name @ref{7bc,,NotImplemented}. Numeric methods
and rich comparison methods should return this value if they do not implement the
operation for the operands provided.  (The interpreter will then try the
reflected operation, or some other fallback, depending on the operator.)  It
should not be evaluated in a boolean context.

Consultez @ref{1e6d,,Implémentation des opérations arithmétiques} pour davantage de détails.


Modifié dans la version 3.9: Evaluating @ref{7bc,,NotImplemented} in a boolean context is deprecated. While
it currently evaluates as true, it will emit a @ref{1a3,,DeprecationWarning}.
It will raise a @ref{522,,TypeError} in a future version of Python.


@node Ellipse,numbers Number,NotImplemented,Hiérarchie des types standards
@anchor{reference/datamodel ellipsis}@anchor{1e6e}
@subsubsection Ellipse


@geindex object;Ellipse
@geindex ...;ellipsis literal

Ce type ne possède qu'une seule valeur. Il n'existe qu'un seul objet avec cette valeur. Vous accédez à cet objet avec le littéral @code{...} ou le nom natif @code{Ellipsis}. Sa valeur booléenne est vraie.

@node numbers Number,Séquences,Ellipse,Hiérarchie des types standards
@anchor{reference/datamodel numbers-number}@anchor{1e6f}
@subsubsection @code{numbers.Number}


@geindex object;numeric

Ces objets sont créés par les littéraux numériques et renvoyés en tant que résultats par les opérateurs et les fonctions arithmétiques natives. Les objets numériques sont immuables ; une fois créés, leur valeur ne change pas. Les nombres Python sont bien sûr très fortement corrélés aux nombres mathématiques mais ils sont soumis aux limitations des représentations numériques par les ordinateurs.

Les représentations sous forme de chaînes de caractères des objets numériques, produites par @ref{607,,__repr__()} et @ref{608,,__str__()}, ont les propriétés suivantes :


@itemize *

@item 
Ce sont des littéraux numériques valides qui, s'ils sont passés au constructeur de leur classe, produisent un objet qui a la valeur numérique de l'objet d'origine.

@item 
La représentation est en base 10, si possible.

@item 
Les zéros en tête, sauf en ce qui concerne un zéro seul avant la virgule (représentée par un point en Python conformément à la convention anglo-saxonne), ne sont pas affichés.

@item 
Les zéros en fin, sauf en ce qui concerne un zéro seul après la virgule, ne sont pas affichés.

@item 
Le signe n'est affiché que lorsque le nombre est négatif.
@end itemize

Python distinguishes between integers, floating-point numbers, and complex
numbers:

@menu
* numbers.Integral: numbers Integral. 
* numbers.Real (float): numbers Real float. 
* numbers.Complex (complex): numbers Complex complex. 

@end menu

@node numbers Integral,numbers Real float,,numbers Number
@anchor{reference/datamodel numbers-integral}@anchor{1e70}
@subsubsection @code{numbers.Integral}


@geindex object;integer

Ils représentent des éléments de l'ensemble mathématique des entiers (positifs ou négatifs).

@cartouche
@quotation Note 
@geindex integer;representation

Les règles pour la représentation des entiers ont pour objet de donner l'interprétation la plus naturelle pour les opérations de décalage et masquage qui impliquent des entiers négatifs.
@end quotation
@end cartouche

Il existe deux types d'entiers :


@table @asis

@item Entiers (@ref{254,,int})

Ils représentent les nombres, sans limite de taille, sous réserve de pouvoir être stockés en mémoire (virtuelle). Afin de pouvoir effectuer des décalages et appliquer des masques, on considère qu'ils ont une représentation binaire. Les nombres négatifs sont représentés comme une variante du complément à 2, qui donne l'illusion d'une chaîne infinie de bits de signe s'étendant vers la gauche.

@item Booléens (@ref{451,,bool})

@geindex object;Boolean
@geindex False
@geindex True

Ils représentent les valeurs `faux' et `vrai'. Deux objets, @code{False} et @code{True}, sont les seuls objets booléens. Le type booléen est un sous-type du type entier et les valeurs booléennes se comportent comme les valeurs 0 (pour @code{False}) et 1 (pour @code{True}) dans presque tous les contextes. L'exception concerne la conversion en chaîne de caractères où @code{"False"} et @code{"True"} sont renvoyées.
@end table

@node numbers Real float,numbers Complex complex,numbers Integral,numbers Number
@anchor{reference/datamodel numbers-real-float}@anchor{1e71}
@subsubsection @code{numbers.Real} (@code{float})


@geindex object;floating-point
@geindex floating-point;number
@geindex C;language
@geindex Java;language

These represent machine-level double precision floating-point numbers. You are
at the mercy of the underlying machine architecture (and C or Java
implementation) for the accepted range and handling of overflow. Python does not
support single-precision floating-point numbers; the savings in processor and
memory usage that are usually the reason for using these are dwarfed by the
overhead of using objects in Python, so there is no reason to complicate the
language with two kinds of floating-point numbers.

@node numbers Complex complex,,numbers Real float,numbers Number
@anchor{reference/datamodel numbers-complex-complex}@anchor{1e72}
@subsubsection @code{numbers.Complex} (@code{complex})


@geindex object;complex
@geindex complex;number

These represent complex numbers as a pair of machine-level double precision
floating-point numbers.  The same caveats apply as for floating-point numbers.
The real and imaginary parts of a complex number @code{z} can be retrieved through
the read-only attributes @code{z.real} and @code{z.imag}.

@node Séquences,Ensembles<2>,numbers Number,Hiérarchie des types standards
@anchor{reference/datamodel sequences}@anchor{1e73}
@subsubsection Séquences


@geindex built-in function;len
@geindex object;sequence
@geindex index operation
@geindex item selection
@geindex subscription

These represent finite ordered sets indexed by non-negative numbers. The
built-in function @ref{619,,len()} returns the number of items of a sequence. When
the length of a sequence is `n', the index set contains the numbers 0, 1,
..., `n'-1.  Item `i' of sequence `a' is selected by @code{a[i]}. Some sequences,
including built-in sequences, interpret negative subscripts by adding the
sequence length. For example, @code{a[-2]} equals @code{a[n-2]}, the second to last
item of sequence a with length @code{n}.

@geindex slicing

Sequences also support slicing: @code{a[i:j]} selects all items with index `k' such
that `i' @code{<=} `k' @code{<} `j'.  When used as an expression, a slice is a
sequence of the same type. The comment above about negative indexes also applies
to negative slice positions.

Quelques séquences gèrent le « découpage étendu » (`extended slicing' en anglais) avec un troisième paramètre : @code{a[i:j:k]} sélectionne tous les éléments de `a' d'indice `x' où @code{x = i + n*k}, avec `n' @code{>=} @code{0} et `i' @code{<=} `x' @code{<} `j'.

Les séquences se différencient en fonction de leur muabilité :

@menu
* Séquences immuables:: 
* Séquences mutables:: 

@end menu

@node Séquences immuables,Séquences mutables,,Séquences
@anchor{reference/datamodel immutable-sequences}@anchor{1e74}
@subsubsection Séquences immuables


@geindex object;immutable sequence
@geindex object;immutable

Un objet de type de séquence immuable ne peut pas être modifié une fois qu'il a été créé. Si l'objet contient des références à d'autres objets, ces autres objets peuvent être mutables et peuvent être modifiés ; cependant, les objets directement référencés par un objet immuable ne peuvent pas être modifiés.

Les types suivants sont des séquences immuables :

@geindex string;immutable sequences


@table @asis

@item Chaînes de caractères

@geindex built-in function;chr
@geindex built-in function;ord
@geindex character
@geindex integer
@geindex Unicode

A string is a sequence of values that represent Unicode code points.
All the code points in the range @code{U+0000 - U+10FFFF} can be
represented in a string.  Python doesn't have a char type;
instead, every code point in the string is represented as a string
object with length @code{1}.  The built-in function @ref{1e75,,ord()}
converts a code point from its string form to an integer in the
range @code{0 - 10FFFF}; @ref{15fb,,chr()} converts an integer in the range
@code{0 - 10FFFF} to the corresponding length @code{1} string object.
@ref{8c2,,str.encode()} can be used to convert a @ref{435,,str} to
@ref{1bd,,bytes} using the given text encoding, and
@ref{8c3,,bytes.decode()} can be used to achieve the opposite.

@item `n'-uplets (`tuples' en anglais)

@geindex object;tuple
@geindex singleton;tuple
@geindex empty;tuple

Les éléments d'un `n'-uplet peuvent être n'importe quel objet Python. Les `n'-uplets de deux éléments ou plus sont formés par une liste d'expressions dont les éléments sont séparés par des virgules. Un `n'-uplet composé d'un seul élément (un « singleton ») est formé en suffixant une expression avec une virgule (une expression en tant que telle ne crée pas un `n'-uplet car les parenthèses doivent rester disponibles pour grouper les expressions). Un `n'-uplet vide est formé à l'aide d'une paire de parenthèses vide.

@item Chaînes d'octets (ou `bytes')

@geindex bytes
@geindex byte

A bytes object is an immutable array.  The items are 8-bit bytes,
represented by integers in the range 0 <= x < 256.  Bytes literals
(like @code{b'abc'}) and the built-in @ref{1bd,,bytes()} constructor
can be used to create bytes objects.  Also, bytes objects can be
decoded to strings via the @ref{8c3,,decode()} method.
@end table

@node Séquences mutables,,Séquences immuables,Séquences
@anchor{reference/datamodel mutable-sequences}@anchor{1e76}
@subsubsection Séquences mutables


@geindex object;mutable sequence
@geindex object;mutable
@geindex assignment;statement
@geindex subscription
@geindex slicing

Les séquences mutables peuvent être modifiées après leur création. Les notations de tranches et de sous-ensembles peuvent être utilisées en tant que cibles d'une affectation ou de l'instruction @ref{1734,,del} (suppression).

@cartouche
@quotation Note 
@geindex module;array

@geindex module;collections

The @ref{1d,,collections} and @ref{7,,array} module provide
additional examples of mutable sequence types.
@end quotation
@end cartouche

Il existe aujourd'hui deux types intrinsèques de séquences mutables :


@table @asis

@item Listes

@geindex object;list

N'importe quel objet Python peut être élément d'une liste. Les listes sont créées en plaçant entre crochets une liste d'expressions dont les éléments sont séparés par des virgules (notez que les listes de longueur 0 ou 1 ne sont pas des cas particuliers).

@item Tableaux d'octets

@geindex bytearray

Un objet `bytearray' est un tableau mutable. Il est créé par la fonction native constructeur @ref{528,,bytearray()}. À part la propriété d'être mutable (et donc de ne pas pouvoir calculer son empreinte par hachage), un tableau d'octets possède la même interface et les mêmes fonctionnalités qu'un objet immuable @ref{1bd,,bytes}.
@end table

@node Ensembles<2>,Tableaux de correspondances,Séquences,Hiérarchie des types standards
@anchor{reference/datamodel set-types}@anchor{1e77}
@subsubsection Ensembles


@geindex built-in function;len
@geindex object;set type

Ils représentent les ensembles d'objets, non ordonnés, finis et dont les éléments sont uniques. Tels quels, ils ne peuvent pas être indicés. Cependant, il est possible d'itérer dessus et la fonction native @ref{619,,len()} renvoie le nombre d'éléments de l'ensemble. Les utilisations classiques des ensembles sont les tests d'appartenance rapides, la suppression de doublons dans une séquence et le calcul d'opérations mathématiques telles que l'intersection, l'union, la différence et le complémentaire.

Pour les éléments des ensembles, les mêmes règles concernant l'immuabilité s'appliquent que pour les clés de dictionnaires. Notez que les types numériques obéissent aux règles normales pour les comparaisons numériques : si deux nombres sont égaux (pour l'opération de comparaison, par exemple @code{1} et @code{1.0}), un seul élément est conservé dans l'ensemble.

Actuellement, il existe deux types d'ensembles natifs :


@table @asis

@item Ensembles

@geindex object;set

Ils représentent les ensembles mutables. Un ensemble est créé par la fonction native constructeur @ref{5c3,,set()} et peut être modifié par la suite à l'aide de différentes méthodes, par exemple @code{add()}.

@item Ensembles figés

@geindex object;frozenset

Ils représentent les ensembles immuables. Ils sont créés par la fonction native constructeur @ref{5c4,,frozenset()}. Comme un ensemble figé est immuable et @ref{5fb,,hachable}, il peut être utilisé comme élément d'un autre ensemble ou comme clé de dictionnaire.
@end table

@node Tableaux de correspondances,Types appelables,Ensembles<2>,Hiérarchie des types standards
@anchor{reference/datamodel mappings}@anchor{1e78}
@subsubsection Tableaux de correspondances


@geindex built-in function;len
@geindex subscription
@geindex object;mapping

Ils représentent les ensembles finis d'objets indicés par des ensembles index arbitraires. La notation @code{a[k]} sélectionne l'élément indicé par @code{k} dans le tableau de correspondances @code{a} ; elle peut être utilisée dans des expressions, comme cible d'une affectation ou avec l'instruction @ref{1734,,del}. La fonction native @ref{619,,len()} renvoie le nombre d'éléments du tableau de correspondances.

Il n'existe actuellement qu'un seul type natif pour les tableaux de correspondances :

@menu
* Dictionnaires: Dictionnaires<2>. 

@end menu

@node Dictionnaires<2>,,,Tableaux de correspondances
@anchor{reference/datamodel dictionaries}@anchor{1e79}
@subsubsection Dictionnaires


@geindex object;dictionary

Ils représentent les ensembles finis d'objets indicés par des valeurs presque arbitraires. Les seuls types de valeurs non reconnus comme clés sont les valeurs contenant des listes, des dictionnaires ou les autres types mutables qui sont comparés par valeur plutôt que par l'identifiant de l'objet. La raison de cette limitation est qu'une implémentation efficace de dictionnaire requiert que l'empreinte par hachage des clés reste constante dans le temps. Les types numériques obéissent aux règles normales pour les comparaisons numériques : si deux nombres sont égaux pour l'opération de comparaison, par exemple @code{1} et @code{1.0}, alors ces deux nombres peuvent être utilisés indifféremment pour désigner la même entrée du dictionnaire.

Les dictionnaires préservent l’ordre d’insertion, ce qui signifie que les clés sont renvoyées séquentiellement dans le même ordre que celui de l’insertion. Remplacer une clé existante ne change pas l’ordre. Par contre, la retirer puis la réinsérer la met à la fin et non à sa précédente position.

Dictionaries are mutable; they can be created by the @code{@{@}} notation (see
section @ref{d6c,,Agencements de dictionnaires}).

@geindex module;dbm.ndbm
@geindex module;dbm.gnu

Les modules d'extensions @ref{34,,dbm.ndbm} et @ref{33,,dbm.gnu} apportent d'autres exemples de types tableaux de correspondances, de même que le module @ref{1d,,collections}.


Modifié dans la version 3.7: les dictionnaires ne conservaient pas l’ordre d’insertion dans les versions antérieures à Python 3.6. Dans CPython 3.6, l’ordre d’insertion était déjà conservé, mais considéré comme un détail d’implémentation et non comme une garantie du langage.


@node Types appelables,Modules<3>,Tableaux de correspondances,Hiérarchie des types standards
@anchor{reference/datamodel callable-types}@anchor{1e7a}
@subsubsection Types appelables


@geindex object;callable
@geindex function;call
@geindex invocation
@geindex function;argument

Ce sont les types sur lesquels on peut faire un appel de fonction (lisez la section @ref{d6a,,Appels}) :

@menu
* Fonctions définies par l'utilisateur:: 
* Méthodes d'instances:: 
* Fonctions génératrices (ou générateurs): Fonctions génératrices ou générateurs. 
* Fonctions coroutines:: 
* Fonctions génératrices (ou générateurs) asynchrones: Fonctions génératrices ou générateurs asynchrones. 
* Fonctions natives:: 
* Méthodes natives:: 
* Classes: Classes<2>. 
* Instances de classe:: 

@end menu

@node Fonctions définies par l'utilisateur,Méthodes d'instances,,Types appelables
@anchor{reference/datamodel user-defined-funcs}@anchor{296}@anchor{reference/datamodel user-defined-functions}@anchor{1e7b}
@subsubsection Fonctions définies par l'utilisateur


@geindex user-defined;function
@geindex object;function
@geindex object;user-defined function

Un objet fonction définie par l'utilisateur (mais ce n'est pas forcément l'utilisateur courant qui a défini cette fonction) est créé par la définition d'une fonction (voir la section @ref{1bc4,,Définition de fonctions}). Il doit être appelé avec une liste d'arguments contenant le même nombre d'éléments que la liste des paramètres formels de la fonction.

@menu
* Special read-only attributes:: 
* Special writable attributes:: 

@end menu

@node Special read-only attributes,Special writable attributes,,Fonctions définies par l'utilisateur
@anchor{reference/datamodel special-read-only-attributes}@anchor{1e7c}
@subsubsection Special read-only attributes


@geindex __closure__ (function attribute)
@geindex __globals__ (function attribute)
@geindex global;namespace


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Signification

@item

@geindex __globals__ (attribut function)
@anchor{reference/datamodel function __globals__}@anchor{12b1}
@deffn {Attribut} function.__globals__
@end deffn

@tab

A reference to the @ref{253,,dictionary} that holds the function's
@ref{1e7d,,global variables} -- the global namespace of the module
in which the function was defined.

@item

@geindex __closure__ (attribut function)
@anchor{reference/datamodel function __closure__}@anchor{12ae}
@deffn {Attribut} function.__closure__
@end deffn

@tab

@code{None} or a @ref{366,,tuple} of cells that contain bindings for the names specified
in the @ref{1e7e,,co_freevars} attribute of the function's
@ref{297,,code object}.

Un objet cellule possède un attribut @code{cell_contents}. Il peut être utilisé pour obtenir la valeur de la cellule et pour en définir la valeur.

@end multitable


@node Special writable attributes,,Special read-only attributes,Fonctions définies par l'utilisateur
@anchor{reference/datamodel special-writable-attributes}@anchor{1e7f}
@subsubsection Special writable attributes


@geindex __doc__ (function attribute)
@geindex __name__ (function attribute)
@geindex __module__ (function attribute)
@geindex __dict__ (function attribute)
@geindex __defaults__ (function attribute)
@geindex __code__ (function attribute)
@geindex __annotations__ (function attribute)
@geindex __kwdefaults__ (function attribute)
@geindex __type_params__ (function attribute)

Most of these attributes check the type of the assigned value:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Signification

@item

@geindex __doc__ (attribut function)
@anchor{reference/datamodel function __doc__}@anchor{11b6}
@deffn {Attribut} function.__doc__
@end deffn

@tab

The function's documentation string, or @code{None} if unavailable.

@item

@geindex __name__ (attribut function)
@anchor{reference/datamodel function __name__}@anchor{12b2}
@deffn {Attribut} function.__name__
@end deffn

@tab

The function's name.
See also: @ref{104f,,__name__ attributes}.

@item

@geindex __qualname__ (attribut function)
@anchor{reference/datamodel function __qualname__}@anchor{1e80}
@deffn {Attribut} function.__qualname__
@end deffn

@tab

The function's @ref{18ce,,qualified name}.
See also: @ref{104e,,__qualname__ attributes}.


Ajouté dans la version 3.3.


@item

@geindex __module__ (attribut function)
@anchor{reference/datamodel function __module__}@anchor{1e81}
@deffn {Attribut} function.__module__
@end deffn

@tab

Nom du module où la fonction est définie ou @code{None} si ce nom n'est pas disponible.

@item

@geindex __defaults__ (attribut function)
@anchor{reference/datamodel function __defaults__}@anchor{12af}
@deffn {Attribut} function.__defaults__
@end deffn

@tab

A @ref{366,,tuple} containing default @ref{1e82,,parameter} values
for those parameters that have defaults,
or @code{None} if no parameters have a default value.

@item

@geindex __code__ (attribut function)
@anchor{reference/datamodel function __code__}@anchor{297}
@deffn {Attribut} function.__code__
@end deffn

@tab

The @ref{1cd,,code object} representing
the compiled function body.

@item

@geindex __dict__ (attribut function)
@anchor{reference/datamodel function __dict__}@anchor{12b0}
@deffn {Attribut} function.__dict__
@end deffn

@tab

The namespace supporting arbitrary function attributes.
See also: @ref{546,,__dict__ attributes}.

@item

@geindex __annotations__ (attribut function)
@anchor{reference/datamodel function __annotations__}@anchor{11b5}
@deffn {Attribut} function.__annotations__
@end deffn

@tab

A @ref{253,,dictionary} containing annotations of
@ref{1e82,,parameters}.
The keys of the dictionary are the parameter names,
and @code{'return'} for the return annotation, if provided.
See also: @ref{7c3,,Bonnes pratiques concernant les annotations}.

@item

@geindex __kwdefaults__ (attribut function)
@anchor{reference/datamodel function __kwdefaults__}@anchor{1011}
@deffn {Attribut} function.__kwdefaults__
@end deffn

@tab

A @ref{253,,dictionary} containing defaults for keyword-only
@ref{1e82,,parameters}.

@item

@geindex __type_params__ (attribut function)
@anchor{reference/datamodel function __type_params__}@anchor{1e83}
@deffn {Attribut} function.__type_params__
@end deffn

@tab

A @ref{366,,tuple} containing the @ref{2b0,,type parameters} of
a @ref{43c,,generic function}.


Ajouté dans la version 3.12.


@end multitable


Function objects also support getting and setting arbitrary attributes, which
can be used, for example, to attach metadata to functions.  Regular attribute
dot-notation is used to get and set such attributes.

`Particularité de l'implémentation CPython :' CPython's current implementation only supports function attributes
on user-defined functions. Function attributes on
@ref{1e84,,built-in functions} may be supported in the
future.

Additional information about a function's definition can be retrieved from its
@ref{1cd,,code object}
(accessible via the @ref{297,,__code__} attribute).

@node Méthodes d'instances,Fonctions génératrices ou générateurs,Fonctions définies par l'utilisateur,Types appelables
@anchor{reference/datamodel id2}@anchor{1e85}@anchor{reference/datamodel instance-methods}@anchor{1e86}
@subsubsection Méthodes d'instances


@geindex object;method
@geindex object;user-defined method
@geindex user-defined;method

Un objet méthode d'instance combine une classe, une instance de classe et tout objet appelable (normalement une fonction définie par l'utilisateur).

@geindex __func__ (method attribute)
@geindex __self__ (method attribute)
@geindex __doc__ (method attribute)
@geindex __name__ (method attribute)
@geindex __module__ (method attribute)

Special read-only attributes:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex __self__ (attribut method)
@anchor{reference/datamodel method __self__}@anchor{137f}
@deffn {Attribut} method.__self__
@end deffn

@tab

Refers to the class instance object to which the method is
@ref{1e87,,bound}

@item

@geindex __func__ (attribut method)
@anchor{reference/datamodel method __func__}@anchor{12da}
@deffn {Attribut} method.__func__
@end deffn

@tab

Refers to the original @ref{296,,function object}

@item

@geindex __doc__ (attribut method)
@anchor{reference/datamodel method __doc__}@anchor{1e88}
@deffn {Attribut} method.__doc__
@end deffn

@tab

The method's documentation
(same as @ref{11b6,,method.__func__.__doc__}).
A @ref{435,,string} if the original function had a docstring, else
@code{None}.

@item

@geindex __name__ (attribut method)
@anchor{reference/datamodel method __name__}@anchor{1e89}
@deffn {Attribut} method.__name__
@end deffn

@tab

The name of the method
(same as @ref{12b2,,method.__func__.__name__})

@item

@geindex __module__ (attribut method)
@anchor{reference/datamodel method __module__}@anchor{1e8a}
@deffn {Attribut} method.__module__
@end deffn

@tab

The name of the module the method was defined in, or @code{None} if
unavailable.

@end multitable


Methods also support accessing (but not setting) the arbitrary function
attributes on the underlying @ref{296,,function object}.

User-defined method objects may be created when getting an attribute of a
class (perhaps via an instance of that class), if that attribute is a
user-defined @ref{296,,function object} or a
@ref{165,,classmethod} object.
@anchor{reference/datamodel method-binding}@anchor{1e87}
When an instance method object is created by retrieving a user-defined
@ref{296,,function object} from a class via one of its
instances, its @ref{137f,,__self__} attribute is the instance, and the
method object is said to be `bound'.  The new method's @ref{12da,,__func__}
attribute is the original function object.

When an instance method object is created by retrieving a @ref{165,,classmethod}
object from a class or instance, its @ref{137f,,__self__} attribute is the
class itself, and its @ref{12da,,__func__} attribute is the function object
underlying the class method.

When an instance method object is called, the underlying function
(@ref{12da,,__func__}) is called, inserting the class instance
(@ref{137f,,__self__}) in front of the argument list.  For instance, when
@code{C} is a class which contains a definition for a function
@code{f()}, and @code{x} is an instance of @code{C}, calling @code{x.f(1)} is
equivalent to calling @code{C.f(x, 1)}.

When an instance method object is derived from a @ref{165,,classmethod} object, the
"class instance" stored in @ref{137f,,__self__} will actually be the class
itself, so that calling either @code{x.f(1)} or @code{C.f(1)} is equivalent to
calling @code{f(C,1)} where @code{f} is the underlying function.

It is important to note that user-defined functions
which are attributes of a class instance are not converted to bound
methods; this `only' happens when the function is an attribute of the
class.

@node Fonctions génératrices ou générateurs,Fonctions coroutines,Méthodes d'instances,Types appelables
@anchor{reference/datamodel generator-functions}@anchor{1e8b}
@subsubsection Fonctions génératrices (ou générateurs)


@geindex generator;function
@geindex generator;iterator

Une fonction ou une méthode qui utilise l'instruction @ref{9bb,,yield} (voir la section @ref{9bb,,L'instruction yield}) est appelée `fonction génératrice'. Une telle fonction, lorsqu'elle est appelée, renvoie toujours un objet @ref{1aa,,itérateur} qui peut être utilisé pour exécuter le corps de la fonction : appeler la méthode @ref{12ab,,iterator.__next__()} de l'itérateur exécute la fonction jusqu'à ce qu'elle renvoie une valeur à l'aide de l'instruction @code{yield}. Quand la fonction exécute l'instruction @ref{9bc,,return} ou se termine, une exception @ref{be8,,StopIteration} est levée et l'itérateur a atteint la fin de l'ensemble de valeurs qu'il peut renvoyer.

@node Fonctions coroutines,Fonctions génératrices ou générateurs asynchrones,Fonctions génératrices ou générateurs,Types appelables
@anchor{reference/datamodel coroutine-functions}@anchor{1e8c}
@subsubsection Fonctions coroutines


@geindex coroutine;function

Une fonction ou méthode définie en utilisant @ref{5bb,,async def} est appelée `fonction coroutine'. Une telle fonction, quand elle est appelée, renvoie un objet @ref{47b,,coroutine}. Elle peut contenir des expressions @ref{1b7,,await} ou @ref{5bf,,async with} ou des instructions @ref{a99,,async for}. Voir également la section @ref{1e8d,,Objets coroutines}.

@node Fonctions génératrices ou générateurs asynchrones,Fonctions natives,Fonctions coroutines,Types appelables
@anchor{reference/datamodel asynchronous-generator-functions}@anchor{1e8e}
@subsubsection Fonctions génératrices (ou générateurs) asynchrones


@geindex asynchronous generator;function
@geindex asynchronous generator;asynchronous iterator

Une fonction ou une méthode définie avec @ref{5bb,,async def} et qui utilise l'instruction @ref{9bb,,yield} est appelée `fonction génératrice asynchrone'. Une telle fonction, quand elle est appelée, renvoie un objet @ref{1a9,,itérateur asynchrone} qui peut être utilisé dans des instructions @ref{a99,,async for} pour exécuter le corps de la fonction.

Appeler la méthode @ref{1e8f,,aiterator.__anext__} de l'itérateur asynchrone renvoie un @ref{1ab,,awaitable} qui, lorsqu'on l'attend, s'exécute jusqu'à ce qu'il fournisse une valeur à l'aide de l'expression @ref{9bb,,yield}. Quand la fonction exécute une instruction @ref{9bc,,return} (sans valeur) ou arrive à la fin, une exception @ref{19bb,,StopAsyncIteration} est levée et l'itérateur asynchrone a atteint la fin de l'ensemble des valeurs qu'il peut produire.

@node Fonctions natives,Méthodes natives,Fonctions génératrices ou générateurs asynchrones,Types appelables
@anchor{reference/datamodel built-in-functions}@anchor{1e90}@anchor{reference/datamodel builtin-functions}@anchor{1e84}
@subsubsection Fonctions natives


@geindex object;built-in function
@geindex object;function
@geindex C;language

A built-in function object is a wrapper around a C function.  Examples of
built-in functions are @ref{619,,len()} and @ref{1472,,math.sin()} (@ref{8d,,math} is a
standard built-in module). The number and type of the arguments are
determined by the C function. Special read-only attributes:


@itemize *

@item 
@code{__doc__} is the function's documentation string, or @code{None} if
unavailable. See @ref{11b6,,function.__doc__}.

@item 
@code{__name__} is the function's name. See @ref{12b2,,function.__name__}.

@item 
@code{__self__} is set to @code{None} (but see the next item).

@item 
@code{__module__} is the name of
the module the function was defined in or @code{None} if unavailable.
See @ref{1e81,,function.__module__}.
@end itemize

@node Méthodes natives,Classes<2>,Fonctions natives,Types appelables
@anchor{reference/datamodel built-in-methods}@anchor{1e91}@anchor{reference/datamodel builtin-methods}@anchor{1e92}
@subsubsection Méthodes natives


@geindex object;built-in method
@geindex object;method
@geindex built-in;method

This is really a different disguise of a built-in function, this time containing
an object passed to the C function as an implicit extra argument.  An example of
a built-in method is @code{alist.append()}, assuming `alist' is a list object. In
this case, the special read-only attribute @code{__self__} is set to the object
denoted by `alist'. (The attribute has the same semantics as it does with
@ref{137f,,other instance methods}.)

@node Classes<2>,Instances de classe,Méthodes natives,Types appelables
@anchor{reference/datamodel classes}@anchor{1e93}@anchor{reference/datamodel id3}@anchor{1e94}
@subsubsection Classes


Classes are callable.  These objects normally act as factories for new
instances of themselves, but variations are possible for class types that
override @ref{56c,,__new__()}.  The arguments of the call are passed to
@code{__new__()} and, in the typical case, to @ref{69b,,__init__()} to
initialize the new instance.

@node Instances de classe,,Classes<2>,Types appelables
@anchor{reference/datamodel class-instances}@anchor{1e95}
@subsubsection Instances de classe


Les instances d'une classe peuvent devenir des appelables si vous définissez la méthode @ref{543,,__call__()} de leur classe.

@node Modules<3>,Classes déclarées par le développeur,Types appelables,Hiérarchie des types standards
@anchor{reference/datamodel module-objects}@anchor{1e96}@anchor{reference/datamodel modules}@anchor{1e97}
@subsubsection Modules


@geindex statement;import
@geindex object;module

Modules are a basic organizational unit of Python code, and are created by
the @ref{1e98,,import system} as invoked either by the
@ref{5cc,,import} statement, or by calling
functions such as @ref{501,,importlib.import_module()} and built-in
@ref{8c1,,__import__()}.  A module object has a namespace implemented by a
@ref{253,,dictionary} object (this is the dictionary referenced by the
@ref{12b1,,__globals__}
attribute of functions defined in the module).  Attribute references are
translated to lookups in this dictionary, e.g., @code{m.x} is equivalent to
@code{m.__dict__["x"]}. A module object does not contain the code object used
to initialize the module (since it isn't needed once the initialization is
done).

L'affectation d'un attribut met à jour le dictionnaire d'espace de nommage du module, par exemple @code{m.x = 1} est équivalent à @code{m.__dict__["x"] = 1}.

@geindex __name__ (module attribute)
@geindex __spec__ (module attribute)
@geindex __package__ (module attribute)
@geindex __loader__ (module attribute)
@geindex __path__ (module attribute)
@geindex __file__ (module attribute)
@geindex __cached__ (module attribute)
@geindex __doc__ (module attribute)
@geindex __annotations__ (module attribute)
@geindex module;namespace

@menu
* Import-related attributes on module objects:: 
* Other writable attributes on module objects:: 
* Module dictionaries:: 

@end menu

@node Import-related attributes on module objects,Other writable attributes on module objects,,Modules<3>
@anchor{reference/datamodel import-mod-attrs}@anchor{1e99}@anchor{reference/datamodel import-related-attributes-on-module-objects}@anchor{1e9a}
@subsubsection Import-related attributes on module objects


Module objects have the following attributes that relate to the
@ref{1e98,,import system}. When a module is created using the machinery associated
with the import system, these attributes are filled in based on the module's
@ref{1e9b,,spec}, before the @ref{1639,,loader} executes and loads the
module.

To create a module dynamically rather than using the import system,
it's recommended to use @ref{dff,,importlib.util.module_from_spec()},
which will set the various import-controlled attributes to appropriate values.
It's also possible to use the @ref{e00,,types.ModuleType} constructor to create
modules directly, but this technique is more error-prone, as most attributes
must be manually set on the module object after it has been created when using
this approach.

@cartouche
@quotation Prudence 
With the exception of @ref{135f,,__name__}, it is `strongly'
recommended that you rely on @ref{1e9c,,__spec__} and its attributes
instead of any of the other individual attributes listed in this subsection.
Note that updating an attribute on @code{__spec__} will not update the
corresponding attribute on the module itself:

@example
>>> import typing
>>> typing.__name__, typing.__spec__.name
('typing', 'typing')
>>> typing.__spec__.name = 'spelling'
>>> typing.__name__, typing.__spec__.name
('typing', 'spelling')
>>> typing.__name__ = 'keyboard_smashing'
>>> typing.__name__, typing.__spec__.name
('keyboard_smashing', 'spelling')
@end example
@end quotation
@end cartouche

@geindex __name__ (attribut module)
@anchor{reference/datamodel module __name__}@anchor{135f}
@deffn {Attribut} module.__name__

The name used to uniquely identify the module in the import system.
For a directly executed module, this will be set to @code{"__main__"}.

This attribute must be set to the fully qualified name of the module.
It is expected to match the value of
@ref{1e9d,,module.__spec__.name}.
@end deffn

@geindex __spec__ (attribut module)
@anchor{reference/datamodel module __spec__}@anchor{1e9c}
@deffn {Attribut} module.__spec__

A record of the module's import-system-related state.

Set to the @ref{1ded,,module spec} that was
used when importing the module. See @ref{1e9e,,Spécificateurs de modules} for more details.


Ajouté dans la version 3.4.

@end deffn

@geindex __package__ (attribut module)
@anchor{reference/datamodel module __package__}@anchor{2d6}
@deffn {Attribut} module.__package__

The @ref{1e9f,,package} a module belongs to.

If the module is top-level (that is, not a part of any specific package)
then the attribute should be set to @code{'@w{'}} (the empty string). Otherwise,
it should be set to the name of the module's package (which can be equal to
@ref{135f,,module.__name__} if the module itself is a package). See 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/}
for further details.

This attribute is used instead of @ref{135f,,__name__} to calculate
explicit relative imports for main modules. It defaults to @code{None} for
modules created dynamically using the @ref{e00,,types.ModuleType} constructor;
use @ref{dff,,importlib.util.module_from_spec()} instead to ensure the attribute
is set to a @ref{435,,str}.

It is `strongly' recommended that you use
@ref{2d7,,module.__spec__.parent}
instead of @code{module.__package__}. @ref{2d6,,__package__} is now only used
as a fallback if @code{__spec__.parent} is not set, and this fallback
path is deprecated.


Modifié dans la version 3.4: This attribute now defaults to @code{None} for modules created dynamically
using the @ref{e00,,types.ModuleType} constructor.
Previously the attribute was optional.



Modifié dans la version 3.6: The value of @code{__package__} is expected to be the same as
@ref{2d7,,__spec__.parent}.
@ref{2d6,,__package__} is now only used as a fallback during import
resolution if @code{__spec__.parent} is not defined.



Modifié dans la version 3.10: @ref{4e4,,ImportWarning} is raised if an import resolution falls back to
@code{__package__} instead of
@ref{2d7,,__spec__.parent}.



Modifié dans la version 3.12: Raise @ref{1a3,,DeprecationWarning} instead of @ref{4e4,,ImportWarning} when
falling back to @code{__package__} during import resolution.



Deprecated since version 3.13, will be removed in version 3.15: @code{__package__} will cease to be set or taken into consideration
by the import system or standard library.

@end deffn

@geindex __loader__ (attribut module)
@anchor{reference/datamodel module __loader__}@anchor{2e0}
@deffn {Attribut} module.__loader__

The @ref{1639,,loader} object that the import machinery used to load the module.

This attribute is mostly useful for introspection, but can be used for
additional loader-specific functionality, for example getting data
associated with a loader.

@code{__loader__} defaults to @code{None} for modules created dynamically
using the @ref{e00,,types.ModuleType} constructor;
use @ref{dff,,importlib.util.module_from_spec()} instead to ensure the attribute
is set to a @ref{1639,,loader} object.

It is `strongly' recommended that you use
@ref{2e1,,module.__spec__.loader}
instead of @code{module.__loader__}.


Modifié dans la version 3.4: This attribute now defaults to @code{None} for modules created dynamically
using the @ref{e00,,types.ModuleType} constructor.
Previously the attribute was optional.



Deprecated since version 3.12, will be removed in version 3.16: Setting @code{__loader__} on a module while failing to set
@code{__spec__.loader} is deprecated. In Python 3.16,
@code{__loader__} will cease to be set or taken into consideration by
the import system or the standard library.

@end deffn

@geindex __path__ (attribut module)
@anchor{reference/datamodel module __path__}@anchor{1bfc}
@deffn {Attribut} module.__path__

A (possibly empty) @ref{4db,,sequence} of strings enumerating the locations
where the package's submodules will be found. Non-package modules should
not have a @code{__path__} attribute. See @ref{1ea0,,l'attribut __path__ des modules} for
more details.

It is `strongly' recommended that you use
@ref{1ea1,,module.__spec__.submodule_search_locations}
instead of @code{module.__path__}.
@end deffn

@geindex __file__ (attribut module)
@anchor{reference/datamodel module __file__}@anchor{1ea2}
@deffn {Attribut} module.__file__
@end deffn

@geindex __cached__ (attribut module)
@anchor{reference/datamodel module __cached__}@anchor{2d4}
@deffn {Attribut} module.__cached__

@code{__file__} and @code{__cached__} are both optional attributes that
may or may not be set. Both attributes should be a @ref{435,,str} when they
are available.

@code{__file__} indicates the pathname of the file from which the module
was loaded (if loaded from a file), or the pathname of the shared library
file for extension modules loaded dynamically from a shared library.
It might be missing for certain types of modules, such as C modules that are
statically linked into the interpreter, and the
@ref{1e98,,import system} may opt to leave it unset if it
has no semantic meaning (for example, a module loaded from a database).

If @code{__file__} is set then the @code{__cached__} attribute might
also be set,  which is the path to any compiled version of
the code (for example, a byte-compiled file). The file does not need to exist
to set this attribute; the path can simply point to where the
compiled file `would' exist (see 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}).

Note that @code{__cached__} may be set even if @code{__file__} is not
set.  However, that scenario is quite atypical.  Ultimately, the
@ref{1639,,loader} is what makes use of the module spec provided by the
@ref{1ea3,,finder} (from which @code{__file__} and @code{__cached__} are
derived).  So if a loader can load from a cached module but otherwise does
not load from a file, that atypical scenario may be appropriate.

It is `strongly' recommended that you use
@ref{2d5,,module.__spec__.cached}
instead of @code{module.__cached__}.


Deprecated since version 3.13, will be removed in version 3.15: Setting @code{__cached__} on a module while failing to set
@code{__spec__.cached} is deprecated. In Python 3.15,
@code{__cached__} will cease to be set or taken into consideration by
the import system or standard library.

@end deffn

@node Other writable attributes on module objects,Module dictionaries,Import-related attributes on module objects,Modules<3>
@anchor{reference/datamodel other-writable-attributes-on-module-objects}@anchor{1ea4}
@subsubsection Other writable attributes on module objects


As well as the import-related attributes listed above, module objects also have
the following writable attributes:

@geindex __doc__ (attribut module)
@anchor{reference/datamodel module __doc__}@anchor{17e0}
@deffn {Attribut} module.__doc__

The module's documentation string, or @code{None} if unavailable.
See also: @ref{915,,__doc__ attributes}.
@end deffn

@geindex __annotations__ (attribut module)
@anchor{reference/datamodel module __annotations__}@anchor{1ea5}
@deffn {Attribut} module.__annotations__

Dictionnaire des @ref{d43,,annotations de variable} trouvées lors de l'exécution du code du module. Pour plus de détails sur l'attribut @ref{1ea5,,__annotations__}, voir @ref{7c3,,Bonnes pratiques concernant les annotations}.
@end deffn

@node Module dictionaries,,Other writable attributes on module objects,Modules<3>
@anchor{reference/datamodel module-dictionaries}@anchor{1ea6}
@subsubsection Module dictionaries


Module objects also have the following special read-only attribute:

@geindex __dict__ (module attribute)

@geindex __dict__ (attribut module)
@anchor{reference/datamodel module __dict__}@anchor{1ea7}
@deffn {Attribut} module.__dict__

The module's namespace as a dictionary object. Uniquely among the attributes
listed here, @code{__dict__} cannot be accessed as a global variable from
within a module; it can only be accessed as an attribute on module objects.

`Particularité de l'implémentation CPython :' en raison de la manière dont CPython nettoie les dictionnaires de modules, le dictionnaire du module est effacé quand le module n'est plus visible, même si le dictionnaire possède encore des références actives. Pour éviter ceci, copiez le dictionnaire ou gardez le module dans votre champ de visibilité tant que vous souhaitez utiliser le dictionnaire directement.
@end deffn

@node Classes déclarées par le développeur,Instances de classe<2>,Modules<3>,Hiérarchie des types standards
@anchor{reference/datamodel class-attrs-and-methods}@anchor{1ea8}@anchor{reference/datamodel custom-classes}@anchor{1ea9}
@subsubsection Classes déclarées par le développeur


Custom class types are typically created by class definitions (see section
@ref{12b5,,Définition de classes}).  A class has a namespace implemented by a dictionary object.
Class attribute references are translated to lookups in this dictionary, e.g.,
@code{C.x} is translated to @code{C.__dict__["x"]} (although there are a number of
hooks which allow for other means of locating attributes). When the attribute
name is not found there, the attribute search continues in the base classes.
This search of the base classes uses the C3 method resolution order which
behaves correctly even in the presence of 'diamond' inheritance structures
where there are multiple inheritance paths leading back to a common ancestor.
Additional details on the C3 MRO used by Python can be found at
@ref{145e,,The Python 2.3 Method Resolution Order}.

@geindex object;class
@geindex object;class instance
@geindex object;instance
@geindex class object;call
@geindex container
@geindex object;dictionary
@geindex class;attribute

When a class attribute reference (for class @code{C}, say) would yield a
class method object, it is transformed into an instance method object whose
@ref{137f,,__self__} attribute is @code{C}.
When it would yield a @ref{40c,,staticmethod} object,
it is transformed into the object wrapped by the static method
object. See section @ref{c3d,,Implémentation de descripteurs} for another way in which attributes
retrieved from a class may differ from those actually contained in its
@ref{546,,__dict__}.

@geindex class;attribute;assignment

Les affectations d'un attribut de classe mettent à jour le dictionnaire de la classe, jamais le dictionnaire d'une classe de base.

@geindex class object;call

Un objet classe peut être appelé (voir ci-dessus) pour produire une instance de classe (voir ci-dessous).

@menu
* Special attributes:: 
* Special methods:: 

@end menu

@node Special attributes,Special methods,,Classes déclarées par le développeur
@anchor{reference/datamodel special-attributes}@anchor{1eaa}
@subsubsection Special attributes


@geindex __name__ (class attribute)
@geindex __module__ (class attribute)
@geindex __dict__ (class attribute)
@geindex __bases__ (class attribute)
@geindex __doc__ (class attribute)
@geindex __annotations__ (class attribute)
@geindex __type_params__ (class attribute)
@geindex __static_attributes__ (class attribute)
@geindex __firstlineno__ (class attribute)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Signification

@item

@geindex __name__ (attribut type)
@anchor{reference/datamodel type __name__}@anchor{145f}
@deffn {Attribut} type.__name__
@end deffn

@tab

The class's name.
See also: @ref{104f,,__name__ attributes}.

@item

@geindex __qualname__ (attribut type)
@anchor{reference/datamodel type __qualname__}@anchor{1eab}
@deffn {Attribut} type.__qualname__
@end deffn

@tab

The class's @ref{18ce,,qualified name}.
See also: @ref{104e,,__qualname__ attributes}.

@item

@geindex __module__ (attribut type)
@anchor{reference/datamodel type __module__}@anchor{36a}
@deffn {Attribut} type.__module__
@end deffn

@tab

Nom du module où la classe a été définie.

@item

@geindex __dict__ (attribut type)
@anchor{reference/datamodel type __dict__}@anchor{c4b}
@deffn {Attribut} type.__dict__
@end deffn

@tab

A @ref{457,,mapping proxy}
providing a read-only view of the class's namespace.
See also: @ref{546,,__dict__ attributes}.

@item

@geindex __bases__ (attribut type)
@anchor{reference/datamodel type __bases__}@anchor{1460}
@deffn {Attribut} type.__bases__
@end deffn

@tab

A @ref{366,,tuple} containing the class's bases.
In most cases, for a class defined as @code{class X(A, B, C)},
@code{X.__bases__} will be exactly equal to @code{(A, B, C)}.

@item

@geindex __doc__ (attribut type)
@anchor{reference/datamodel type __doc__}@anchor{1c3a}
@deffn {Attribut} type.__doc__
@end deffn

@tab

The class's documentation string, or @code{None} if undefined.
Not inherited by subclasses.

@item

@geindex __annotations__ (attribut type)
@anchor{reference/datamodel type __annotations__}@anchor{1eac}
@deffn {Attribut} type.__annotations__
@end deffn

@tab

A dictionary containing
@ref{d43,,variable annotations}
collected during class body execution. For best practices on working
with @code{__annotations__}, please see @ref{7c3,,Bonnes pratiques concernant les annotations}.

@cartouche
@quotation Prudence 
Accessing the @code{__annotations__} attribute of a class
object directly may yield incorrect results in the presence of
metaclasses. In addition, the attribute may not exist for
some classes. Use @ref{7fd,,inspect.get_annotations()} to
retrieve class annotations safely.
@end quotation
@end cartouche

@item

@geindex __type_params__ (attribut type)
@anchor{reference/datamodel type __type_params__}@anchor{1ead}
@deffn {Attribut} type.__type_params__
@end deffn

@tab

A @ref{366,,tuple} containing the @ref{2b0,,type parameters} of
a @ref{43b,,generic class}.


Ajouté dans la version 3.12.


@item

@geindex __static_attributes__ (attribut type)
@anchor{reference/datamodel type __static_attributes__}@anchor{14a}
@deffn {Attribut} type.__static_attributes__
@end deffn

@tab

A @ref{366,,tuple} containing names of attributes of this class which are
assigned through @code{self.X} from any function in its body.


Ajouté dans la version 3.13.


@item

@geindex __firstlineno__ (attribut type)
@anchor{reference/datamodel type __firstlineno__}@anchor{14b}
@deffn {Attribut} type.__firstlineno__
@end deffn

@tab

The line number of the first line of the class definition,
including decorators.
Setting the @code{__module__} attribute removes the
@code{__firstlineno__} item from the type's dictionary.


Ajouté dans la version 3.13.


@item

@geindex __mro__ (attribut type)
@anchor{reference/datamodel type __mro__}@anchor{1eae}
@deffn {Attribut} type.__mro__
@end deffn

@tab

The @ref{366,,tuple} of classes that are considered when looking for
base classes during method resolution.

@end multitable


@node Special methods,,Special attributes,Classes déclarées par le développeur
@anchor{reference/datamodel special-methods}@anchor{1eaf}
@subsubsection Special methods


In addition to the special attributes described above, all Python classes also
have the following two methods available:

@geindex mro() (méthode type)
@anchor{reference/datamodel type mro}@anchor{1eb0}
@deffn {Méthode} type.mro ()

This method can be overridden by a metaclass to customize the method
resolution order for its instances.  It is called at class instantiation,
and its result is stored in @ref{1eae,,__mro__}.
@end deffn

@geindex __subclasses__() (méthode type)
@anchor{reference/datamodel type __subclasses__}@anchor{55f}
@deffn {Méthode} type.__subclasses__ ()

Each class keeps a list of weak references to its immediate subclasses. This
method returns a list of all those references still alive. The list is in
definition order. Example:

@example
>>> class A: pass
>>> class B(A): pass
>>> A.__subclasses__()
[<class 'B'>]
@end example
@end deffn

@node Instances de classe<2>,Objets entrées-sorties ou objets fichiers,Classes déclarées par le développeur,Hiérarchie des types standards
@anchor{reference/datamodel id4}@anchor{1eb1}
@subsubsection Instances de classe


@geindex object;class instance
@geindex object;instance
@geindex class;instance
@geindex class instance;attribute

A class instance is created by calling a class object (see above).  A class
instance has a namespace implemented as a dictionary which is the first place
in which attribute references are searched.  When an attribute is not found
there, and the instance's class has an attribute by that name, the search
continues with the class attributes.  If a class attribute is found that is a
user-defined function object, it is transformed into an instance method
object whose @ref{137f,,__self__} attribute is the instance.  Static method and
class method objects are also transformed; see above under "Classes".  See
section @ref{c3d,,Implémentation de descripteurs} for another way in which attributes of a class
retrieved via its instances may differ from the objects actually stored in
the class's @ref{546,,__dict__}.  If no class attribute is found, and the
object's class has a @ref{4bc,,__getattr__()} method, that is called to satisfy
the lookup.

@geindex class instance;attribute;assignment

Les affectations et suppressions d'attributs mettent à jour le dictionnaire de l'instance, jamais le dictionnaire de la classe. Si la classe possède une méthode @ref{1eb2,,__setattr__()} ou @ref{1eb3,,__delattr__()}, elle est appelée au lieu de mettre à jour le dictionnaire de l'instance directement.

@geindex object;numeric
@geindex object;sequence
@geindex object;mapping

Les instances de classes peuvent prétendre être des nombres, des séquences ou des tableaux de correspondances si elles ont des méthodes avec des noms spéciaux. Voir la section @ref{c5c,,Méthodes spéciales}.

@menu
* Special attributes: Special attributes<2>. 

@end menu

@node Special attributes<2>,,,Instances de classe<2>
@anchor{reference/datamodel id5}@anchor{1eb4}
@subsubsection Special attributes


@geindex __dict__ (instance attribute)
@geindex __class__ (instance attribute)

@geindex __class__ (attribut object)
@anchor{reference/datamodel object __class__}@anchor{1461}
@deffn {Attribut} object.__class__

Classe de l'instance de classe.
@end deffn

@geindex __dict__ (attribut object)
@anchor{reference/datamodel object __dict__}@anchor{546}
@deffn {Attribut} object.__dict__

A dictionary or other mapping object used to store an object's (writable)
attributes. Not all instances have a @code{__dict__} attribute; see the
section on @ref{1eb5,,créneaux prédéfinis (__slots__)} for more details.
@end deffn

@node Objets entrées-sorties ou objets fichiers,Types internes,Instances de classe<2>,Hiérarchie des types standards
@anchor{reference/datamodel i-o-objects-also-known-as-file-objects}@anchor{1eb6}
@subsubsection Objets entrées-sorties (ou objets fichiers)


@geindex built-in function;open
@geindex module;io
@geindex popen() (in module os)
@geindex makefile() (socket method)
@geindex sys.stdin
@geindex sys.stdout
@geindex sys.stderr
@geindex stdio
@geindex stdin (in module sys)
@geindex stdout (in module sys)
@geindex stderr (in module sys)

Un @ref{11a0,,objet fichier} représente un fichier ouvert. Différents raccourcis existent pour créer des objets fichiers : la fonction native @ref{505,,open()} et aussi @ref{a75,,os.popen()}, @ref{1eb7,,os.fdopen()} ou la méthode @ref{117d,,makefile()} des objets connecteurs (et sûrement d'autres fonctions ou méthodes fournies par les modules d'extensions).

Les objets @code{sys.stdin}, @code{sys.stdout} et @code{sys.stderr} sont initialisés à des objets fichiers correspondant à l'entrée standard, la sortie standard et le flux d'erreurs de l'interpréteur ; ils sont tous ouverts en mode texte et se conforment donc à l'interface définie par la classe abstraite @ref{680,,io.TextIOBase}.

@node Types internes,,Objets entrées-sorties ou objets fichiers,Hiérarchie des types standards
@anchor{reference/datamodel internal-types}@anchor{1eb8}
@subsubsection Types internes


@geindex internal type
@geindex types@comma{} internal

Quelques types utilisés en interne par l'interpréteur sont accessibles à l'utilisateur. Leur définition peut changer dans les futures versions de l'interpréteur mais ils sont donnés ci-dessous à fin d'exhaustivité.

@menu
* Objets Code:: 
* Objets cadres:: 
* Objets traces d'appels:: 
* Objets tranches:: 
* Objets méthodes statiques:: 
* Objets méthodes de classes:: 

@end menu

@node Objets Code,Objets cadres,,Types internes
@anchor{reference/datamodel code-objects}@anchor{1cd}@anchor{reference/datamodel id6}@anchor{1eb9}
@subsubsection Objets Code


@geindex bytecode
@geindex object;code
@geindex code object

Un objet code représente le code Python sous sa forme compilée en @ref{185,,code intermédiaire}. La différence entre un objet code et un objet fonction est que l'objet fonction contient une référence explicite vers les globales de la fonction (le module dans lequel elle est définie) alors qu'un objet code ne contient aucun contexte ; par ailleurs, les valeurs par défaut des arguments sont stockées dans l'objet fonction, pas dans l'objet code (parce que ce sont des valeurs calculées au moment de l'exécution). Contrairement aux objets fonctions, les objets codes sont immuables et ne contiennent aucune référence (directe ou indirecte) à des objets mutables.

@geindex co_argcount (code object attribute)
@geindex co_posonlyargcount (code object attribute)
@geindex co_kwonlyargcount (code object attribute)
@geindex co_code (code object attribute)
@geindex co_consts (code object attribute)
@geindex co_filename (code object attribute)
@geindex co_firstlineno (code object attribute)
@geindex co_flags (code object attribute)
@geindex co_lnotab (code object attribute)
@geindex co_name (code object attribute)
@geindex co_names (code object attribute)
@geindex co_nlocals (code object attribute)
@geindex co_stacksize (code object attribute)
@geindex co_varnames (code object attribute)
@geindex co_cellvars (code object attribute)
@geindex co_freevars (code object attribute)
@geindex co_qualname (code object attribute)

@menu
* Special read-only attributes: Special read-only attributes<2>. 
* Methods on code objects:: 

@end menu

@node Special read-only attributes<2>,Methods on code objects,,Objets Code
@anchor{reference/datamodel id7}@anchor{1eba}
@subsubsection Special read-only attributes



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex co_name (attribut codeobject)
@anchor{reference/datamodel codeobject co_name}@anchor{1ebb}
@deffn {Attribut} codeobject.co_name
@end deffn

@tab

The function name

@item

@geindex co_qualname (attribut codeobject)
@anchor{reference/datamodel codeobject co_qualname}@anchor{1ebc}
@deffn {Attribut} codeobject.co_qualname
@end deffn

@tab

The fully qualified function name


Ajouté dans la version 3.11.


@item

@geindex co_argcount (attribut codeobject)
@anchor{reference/datamodel codeobject co_argcount}@anchor{1ebd}
@deffn {Attribut} codeobject.co_argcount
@end deffn

@tab

The total number of positional @ref{1e82,,parameters}
(including positional-only parameters and parameters with default values)
that the function has

@item

@geindex co_posonlyargcount (attribut codeobject)
@anchor{reference/datamodel codeobject co_posonlyargcount}@anchor{1ebe}
@deffn {Attribut} codeobject.co_posonlyargcount
@end deffn

@tab

The number of positional-only @ref{1e82,,parameters}
(including arguments with default values) that the function has

@item

@geindex co_kwonlyargcount (attribut codeobject)
@anchor{reference/datamodel codeobject co_kwonlyargcount}@anchor{1ebf}
@deffn {Attribut} codeobject.co_kwonlyargcount
@end deffn

@tab

The number of keyword-only @ref{1e82,,parameters}
(including arguments with default values) that the function has

@item

@geindex co_nlocals (attribut codeobject)
@anchor{reference/datamodel codeobject co_nlocals}@anchor{1ec0}
@deffn {Attribut} codeobject.co_nlocals
@end deffn

@tab

The number of @ref{1e7d,,local variables} used by the function
(including parameters)

@item

@geindex co_varnames (attribut codeobject)
@anchor{reference/datamodel codeobject co_varnames}@anchor{1ec1}
@deffn {Attribut} codeobject.co_varnames
@end deffn

@tab

A @ref{366,,tuple} containing the names of the local variables in the
function (starting with the parameter names)

@item

@geindex co_cellvars (attribut codeobject)
@anchor{reference/datamodel codeobject co_cellvars}@anchor{1ec2}
@deffn {Attribut} codeobject.co_cellvars
@end deffn

@tab

A @ref{366,,tuple} containing the names of @ref{1e7d,,local variables}
that are referenced from at least one @ref{1ec3,,nested scope} inside the function

@item

@geindex co_freevars (attribut codeobject)
@anchor{reference/datamodel codeobject co_freevars}@anchor{1e7e}
@deffn {Attribut} codeobject.co_freevars
@end deffn

@tab

A @ref{366,,tuple} containing the names of
@ref{1ec4,,free (closure) variables} that a @ref{1ec3,,nested scope}
references in an outer scope. See also @ref{12ae,,function.__closure__}.

Note: references to global and builtin names are `not' included.

@item

@geindex co_code (attribut codeobject)
@anchor{reference/datamodel codeobject co_code}@anchor{1ec5}
@deffn {Attribut} codeobject.co_code
@end deffn

@tab

A string representing the sequence of @ref{185,,bytecode} instructions in
the function

@item

@geindex co_consts (attribut codeobject)
@anchor{reference/datamodel codeobject co_consts}@anchor{1ec6}
@deffn {Attribut} codeobject.co_consts
@end deffn

@tab

A @ref{366,,tuple} containing the literals used by the @ref{185,,bytecode} in
the function

@item

@geindex co_names (attribut codeobject)
@anchor{reference/datamodel codeobject co_names}@anchor{1ec7}
@deffn {Attribut} codeobject.co_names
@end deffn

@tab

A @ref{366,,tuple} containing the names used by the @ref{185,,bytecode} in
the function

@item

@geindex co_filename (attribut codeobject)
@anchor{reference/datamodel codeobject co_filename}@anchor{1344}
@deffn {Attribut} codeobject.co_filename
@end deffn

@tab

The name of the file from which the code was compiled

@item

@geindex co_firstlineno (attribut codeobject)
@anchor{reference/datamodel codeobject co_firstlineno}@anchor{1ec8}
@deffn {Attribut} codeobject.co_firstlineno
@end deffn

@tab

The line number of the first line of the function

@item

@geindex co_lnotab (attribut codeobject)
@anchor{reference/datamodel codeobject co_lnotab}@anchor{2de}
@deffn {Attribut} codeobject.co_lnotab
@end deffn

@tab

A string encoding the mapping from @ref{185,,bytecode} offsets to line
numbers. For details, see the source code of the interpreter.


Obsolète depuis la version 3.12: This attribute of code objects is deprecated, and may be removed in
Python 3.15.


@item

@geindex co_stacksize (attribut codeobject)
@anchor{reference/datamodel codeobject co_stacksize}@anchor{1ec9}
@deffn {Attribut} codeobject.co_stacksize
@end deffn

@tab

The required stack size of the code object

@item

@geindex co_flags (attribut codeobject)
@anchor{reference/datamodel codeobject co_flags}@anchor{1eca}
@deffn {Attribut} codeobject.co_flags
@end deffn

@tab

An @ref{254,,integer} encoding a number of flags for the
interpreter.

@end multitable


@geindex object;generator

The following flag bits are defined for @ref{1eca,,co_flags}:
bit @code{0x04} is set if
the function uses the @code{*arguments} syntax to accept an arbitrary number of
positional arguments; bit @code{0x08} is set if the function uses the
@code{**keywords} syntax to accept arbitrary keyword arguments; bit @code{0x20} is set
if the function is a generator. See @ref{1ecb,,Bit d'option des objets code} for details
on the semantics of each flags that might be present.

Future feature declarations (@code{from __future__ import division}) also use bits
in @ref{1eca,,co_flags} to indicate whether a code object was compiled with a
particular feature enabled: bit @code{0x2000} is set if the function was compiled
with future division enabled; bits @code{0x10} and @code{0x1000} were used in earlier
versions of Python.

Other bits in @ref{1eca,,co_flags} are reserved for internal use.

@geindex documentation string

If a code object represents a function, the first item in
@ref{1ec6,,co_consts} is
the documentation string of the function, or @code{None} if undefined.

@node Methods on code objects,,Special read-only attributes<2>,Objets Code
@anchor{reference/datamodel methods-on-code-objects}@anchor{1ecc}
@subsubsection Methods on code objects


@geindex co_positions() (méthode codeobject)
@anchor{reference/datamodel codeobject co_positions}@anchor{59d}
@deffn {Méthode} codeobject.co_positions ()

Returns an iterable over the source code positions of each @ref{185,,bytecode}
instruction in the code object.

The iterator returns @ref{366,,tuple}s containing the @code{(start_line, end_line,
start_column, end_column)}. The `i-th' tuple corresponds to the
position of the source code that compiled to the `i-th' code unit.
Column information is 0-indexed utf-8 byte offsets on the given source
line.

L'information sur la position peut être manquante. Ce peut être le cas si (liste non exhaustive) :


@itemize -

@item 
l'interpréteur est lancé avec l'option  @ref{175,,-X} @code{no_debug_ranges} ;

@item 
le fichier `.pyc' est le produit d'une compilation avec l'option  @ref{175,,-X} @code{no_debug_ranges} ;

@item 
le `n'-uplet de position correspond à des instructions artificielles ;

@item 
les lignes et colonnes ne peuvent pas être représentées en tant que nombre, en raison de limitations dues à l'implémentation ;
@end itemize

Dans ce cas, certains ou tous les éléments du `n'-uplet peuvent valoir @ref{660,,None}.


Ajouté dans la version 3.11.


@cartouche
@quotation Note 
cette fonctionnalité nécessite de stocker les positions de colonne dans les objets code, ce qui peut conduire à une légère augmentation de l'utilisation du disque par les fichiers Python compilés ou de l'utilisation de la mémoire. Pour éviter de stocker cette information supplémentaire ou pour désactiver l'affichage supplémentaire dans la pile d'appels, vous pouvez activer l'option de ligne de commande @ref{175,,-X} @code{no_debug_ranges} ou la variable d'environnement 
@geindex PYTHONNODEBUGRANGES
@geindex variable d'environnement; PYTHONNODEBUGRANGES
@ref{5a0,,PYTHONNODEBUGRANGES}.
@end quotation
@end cartouche
@end deffn

@geindex co_lines() (méthode codeobject)
@anchor{reference/datamodel codeobject co_lines}@anchor{2ef}
@deffn {Méthode} codeobject.co_lines ()

Returns an iterator that yields information about successive ranges of
@ref{185,,bytecode}s. Each item yielded is a @code{(start, end, lineno)}
@ref{366,,tuple}:


@itemize *

@item 
@code{start} (an @ref{254,,int}) represents the offset (inclusive) of the start
of the @ref{185,,bytecode} range

@item 
@code{end} (an @ref{254,,int}) represents the offset (exclusive) of the end of
the @ref{185,,bytecode} range

@item 
@code{lineno} is an @ref{254,,int} representing the line number of the
@ref{185,,bytecode} range, or @code{None} if the bytecodes in the given range
have no line number
@end itemize

The items yielded will have the following properties:


@itemize *

@item 
The first range yielded will have a @code{start} of 0.

@item 
The @code{(start, end)} ranges will be non-decreasing and consecutive. That
is, for any pair of @ref{366,,tuple}s, the @code{start} of the second will be
equal to the @code{end} of the first.

@item 
No range will be backwards: @code{end >= start} for all triples.

@item 
The last @ref{366,,tuple} yielded will have @code{end} equal to the size of the
@ref{185,,bytecode}.
@end itemize

Zero-width ranges, where @code{start == end}, are allowed. Zero-width ranges
are used for lines that are present in the source code, but have been
eliminated by the @ref{185,,bytecode} compiler.


Ajouté dans la version 3.10.



@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 626

@item PEP 626@footnote{https://peps.python.org/pep-0626/} - Precise line numbers for debugging and other tools.

The PEP that introduced the @code{co_lines()} method.
@end table

@end deffn

@geindex replace() (méthode codeobject)
@anchor{reference/datamodel codeobject replace}@anchor{1ecd}
@deffn {Méthode} codeobject.replace (**kwargs)

Return a copy of the code object with new values for the specified fields.

Code objects are also supported by the generic function @ref{150,,copy.replace()}.


Ajouté dans la version 3.8.

@end deffn

@node Objets cadres,Objets traces d'appels,Objets Code,Types internes
@anchor{reference/datamodel frame-objects}@anchor{6ca}@anchor{reference/datamodel id8}@anchor{1ece}
@subsubsection Objets cadres


@geindex object;frame

Frame objects represent execution frames.  They may occur in
@ref{ae2,,traceback objects},
and are also passed to registered trace functions.

@geindex f_back (frame attribute)
@geindex f_code (frame attribute)
@geindex f_globals (frame attribute)
@geindex f_locals (frame attribute)
@geindex f_lasti (frame attribute)
@geindex f_builtins (frame attribute)

@menu
* Special read-only attributes: Special read-only attributes<3>. 
* Special writable attributes: Special writable attributes<2>. 
* Frame object methods:: 

@end menu

@node Special read-only attributes<3>,Special writable attributes<2>,,Objets cadres
@anchor{reference/datamodel id9}@anchor{1ecf}
@subsubsection Special read-only attributes



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex f_back (attribut frame)
@anchor{reference/datamodel frame f_back}@anchor{776}
@deffn {Attribut} frame.f_back
@end deffn

@tab

Points to the previous stack frame (towards the caller),
or @code{None} if this is the bottom stack frame

@item

@geindex f_code (attribut frame)
@anchor{reference/datamodel frame f_code}@anchor{1ed0}
@deffn {Attribut} frame.f_code
@end deffn

@tab

The @ref{1cd,,code object} being executed in this frame.
Accessing this attribute raises an @ref{1848,,auditing event}
@code{object.__getattr__} with arguments @code{obj} and @code{"f_code"}.

@item

@geindex f_locals (attribut frame)
@anchor{reference/datamodel frame f_locals}@anchor{180}
@deffn {Attribut} frame.f_locals
@end deffn

@tab

The mapping used by the frame to look up
@ref{1e7d,,local variables}.
If the frame refers to an @ref{17c,,optimized scope},
this may return a write-through proxy object.


Modifié dans la version 3.13: Return a proxy for optimized scopes.


@item

@geindex f_globals (attribut frame)
@anchor{reference/datamodel frame f_globals}@anchor{1ed1}
@deffn {Attribut} frame.f_globals
@end deffn

@tab

The dictionary used by the frame to look up
@ref{1e7d,,global variables}

@item

@geindex f_builtins (attribut frame)
@anchor{reference/datamodel frame f_builtins}@anchor{1ed2}
@deffn {Attribut} frame.f_builtins
@end deffn

@tab

The dictionary used by the frame to look up
@ref{1e7d,,built-in (intrinsic) names}

@item

@geindex f_lasti (attribut frame)
@anchor{reference/datamodel frame f_lasti}@anchor{874}
@deffn {Attribut} frame.f_lasti
@end deffn

@tab

The "precise instruction" of the frame object
(this is an index into the @ref{185,,bytecode} string of the
@ref{1cd,,code object})

@end multitable


@geindex f_trace (frame attribute)
@geindex f_trace_lines (frame attribute)
@geindex f_trace_opcodes (frame attribute)
@geindex f_lineno (frame attribute)

@node Special writable attributes<2>,Frame object methods,Special read-only attributes<3>,Objets cadres
@anchor{reference/datamodel id10}@anchor{1ed3}
@subsubsection Special writable attributes



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex f_trace (attribut frame)
@anchor{reference/datamodel frame f_trace}@anchor{1ed4}
@deffn {Attribut} frame.f_trace
@end deffn

@tab

If not @code{None}, this is a function called for various events during
code execution (this is used by debuggers). Normally an event is
triggered for each new source line (see @ref{bc9,,f_trace_lines}).

@item

@geindex f_trace_lines (attribut frame)
@anchor{reference/datamodel frame f_trace_lines}@anchor{bc9}
@deffn {Attribut} frame.f_trace_lines
@end deffn

@tab

Set this attribute to @ref{b25,,False} to disable triggering a tracing
event for each source line.

@item

@geindex f_trace_opcodes (attribut frame)
@anchor{reference/datamodel frame f_trace_opcodes}@anchor{bca}
@deffn {Attribut} frame.f_trace_opcodes
@end deffn

@tab

Set this attribute to @ref{bfb,,True} to allow per-opcode events to be
requested. Note that this may lead to
undefined interpreter behaviour if exceptions raised by the trace
function escape to the function being traced.

@item

@geindex f_lineno (attribut frame)
@anchor{reference/datamodel frame f_lineno}@anchor{796}
@deffn {Attribut} frame.f_lineno
@end deffn

@tab

The current line number of the frame -- writing to this
from within a trace function jumps to the given line (only for the bottom-most
frame).  A debugger can implement a Jump command (aka Set Next Statement)
by writing to this attribute.

@end multitable


@node Frame object methods,,Special writable attributes<2>,Objets cadres
@anchor{reference/datamodel frame-object-methods}@anchor{1ed5}
@subsubsection Frame object methods


Les objets cadres comprennent une méthode :

@geindex clear() (méthode frame)
@anchor{reference/datamodel frame clear}@anchor{27d}
@deffn {Méthode} frame.clear ()

This method clears all references to @ref{1e7d,,local variables} held by the
frame.  Also, if the frame belonged to a @ref{104a,,generator}, the generator
is finalized.  This helps break reference cycles involving frame
objects (for example when catching an @ref{1811,,exception}
and storing its @ref{ae2,,traceback} for later use).

@ref{193,,RuntimeError} is raised if the frame is currently executing
or suspended.


Ajouté dans la version 3.4.



Modifié dans la version 3.13: Attempting to clear a suspended frame raises @ref{193,,RuntimeError}
(as has always been the case for executing frames).

@end deffn

@node Objets traces d'appels,Objets tranches,Objets cadres,Types internes
@anchor{reference/datamodel id11}@anchor{1ed6}@anchor{reference/datamodel traceback-objects}@anchor{ae2}
@subsubsection Objets traces d'appels


@geindex object;traceback
@geindex stack;trace
@geindex exception;handler
@geindex execution;stack
@geindex exc_info (in module sys)
@geindex last_traceback (in module sys)
@geindex sys.exc_info
@geindex sys.exception
@geindex sys.last_traceback

Traceback objects represent the stack trace of an @ref{1c18,,exception}.
A traceback object
is implicitly created when an exception occurs, and may also be explicitly
created by calling @ref{ae0,,types.TracebackType}.


Modifié dans la version 3.7: Traceback objects can now be explicitly instantiated from Python code.


For implicitly created tracebacks, when the search for an exception handler
unwinds the execution stack, at each unwound level a traceback object is
inserted in front of the current traceback.  When an exception handler is
entered, the stack trace is made available to the program. (See section
@ref{6d3,,L'instruction try}.) It is accessible as the third item of the
tuple returned by @ref{675,,sys.exc_info()}, and as the
@ref{12a4,,__traceback__} attribute
of the caught exception.

When the program contains no suitable
handler, the stack trace is written (nicely formatted) to the standard error
stream; if the interpreter is interactive, it is also made available to the user
as @ref{4aa,,sys.last_traceback}.

For explicitly created tracebacks, it is up to the creator of the traceback
to determine how the @ref{ae1,,tb_next} attributes should be linked to
form a full stack trace.

@geindex tb_frame (traceback attribute)
@geindex tb_lineno (traceback attribute)
@geindex tb_lasti (traceback attribute)
@geindex statement;try

Special read-only attributes:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex tb_frame (attribut traceback)
@anchor{reference/datamodel traceback tb_frame}@anchor{1ed7}
@deffn {Attribut} traceback.tb_frame
@end deffn

@tab

Points to the execution @ref{6ca,,frame} of the current
level.

Accessing this attribute raises an
@ref{1848,,auditing event} @code{object.__getattr__} with arguments
@code{obj} and @code{"tb_frame"}.

@item

@geindex tb_lineno (attribut traceback)
@anchor{reference/datamodel traceback tb_lineno}@anchor{1ed8}
@deffn {Attribut} traceback.tb_lineno
@end deffn

@tab

Gives the line number where the exception occurred

@item

@geindex tb_lasti (attribut traceback)
@anchor{reference/datamodel traceback tb_lasti}@anchor{1ed9}
@deffn {Attribut} traceback.tb_lasti
@end deffn

@tab

Indicates the "precise instruction".

@end multitable


The line number and last instruction in the traceback may differ from the
line number of its @ref{6ca,,frame object} if the exception
occurred in a
@ref{6d3,,try} statement with no matching except clause or with a
@ref{9b8,,finally} clause.

@geindex tb_next (traceback attribute)

@geindex tb_next (attribut traceback)
@anchor{reference/datamodel traceback tb_next}@anchor{ae1}
@deffn {Attribut} traceback.tb_next

The special writable attribute @code{tb_next} is the next level in the
stack trace (towards the frame where the exception occurred), or @code{None} if
there is no next level.


Modifié dans la version 3.7: This attribute is now writable

@end deffn

@node Objets tranches,Objets méthodes statiques,Objets traces d'appels,Types internes
@anchor{reference/datamodel slice-objects}@anchor{1eda}
@subsubsection Objets tranches


@geindex built-in function;slice

Un objet tranche est utilisé pour représenter des découpes des méthodes @ref{280,,__getitem__()}. Ils sont aussi créés par la fonction native @ref{453,,slice()}.

@geindex start (slice object attribute)
@geindex stop (slice object attribute)
@geindex step (slice object attribute)

Attributs spéciaux en lecture seule : @code{start} est la borne inférieure ; @code{stop} est la borne supérieure ; @code{step} est la valeur du pas ; chaque attribut vaut @code{None} s'il est omis. Ces attributs peuvent être de n'importe quel type.

Les objets tranches comprennent une méthode :

@geindex indices() (méthode slice)
@anchor{reference/datamodel slice indices}@anchor{1010}
@deffn {Méthode} slice.indices (self, length)

Cette méthode prend un argument entier `length' et calcule les informations de la tranche que l'objet `slice' décrit s'il est appliqué à une séquence de `length' éléments. Elle renvoie un triplet d'entiers ; respectivement, ce sont les indices de `début' et `fin' ainsi que le `pas' de découpe. Les indices manquants ou en dehors sont gérés de manière cohérente avec les tranches normales.
@end deffn

@node Objets méthodes statiques,Objets méthodes de classes,Objets tranches,Types internes
@anchor{reference/datamodel static-method-objects}@anchor{1edb}
@subsubsection Objets méthodes statiques


Les objets méthodes statiques permettent la transformation des objets fonctions en objets méthodes décrits au-dessus. Un objet méthode statique encapsule tout autre objet, souvent un objet méthode définie par l'utilisateur. Quand un objet méthode statique est récupéré depuis une classe ou une instance de classe, l'objet réellement renvoyé est un objet encapsulé, qui n'a pas vocation à être transformé encore une fois. Les objets méthodes statiques sont aussi appelables. Les objets méthodes statiques sont créés par le constructeur natif @ref{40c,,staticmethod()}.

@node Objets méthodes de classes,,Objets méthodes statiques,Types internes
@anchor{reference/datamodel class-method-objects}@anchor{1edc}
@subsubsection Objets méthodes de classes


A class method object, like a static method object, is a wrapper around another
object that alters the way in which that object is retrieved from classes and
class instances. The behaviour of class method objects upon such retrieval is
described above, under @ref{1e86,,"instance methods"}. Class method objects are created
by the built-in @ref{165,,classmethod()} constructor.

@node Méthodes spéciales,Coroutines,Hiérarchie des types standards,Modèle de données
@anchor{reference/datamodel special-method-names}@anchor{1edd}@anchor{reference/datamodel specialnames}@anchor{c5c}
@subsection Méthodes spéciales


@geindex operator;overloading
@geindex __getitem__() (mapping object method)

Une classe peut implémenter certaines opérations que l'on invoque par une syntaxe spéciale (telles que les opérations arithmétiques ou la découpe en tranches) en définissant des méthodes aux noms particuliers. C'est l'approche utilisée par Python pour la `surcharge d'opérateur', permettant à une classe de définir son propre comportement vis-à-vis des opérateurs du langage. Par exemple, si une classe définit une méthode @ref{280,,__getitem__()} et que @code{x} est une instance de cette classe, alors @code{x[i]} est globalement équivalent à @code{type(x).__getitem__(x, i)}. Sauf lorsque c'est mentionné, toute tentative d'appliquer une opération alors que la méthode appropriée n'est pas définie lève une exception (typiquement @ref{343,,AttributeError} ou @ref{522,,TypeError}).

Définir une méthode spéciale à @code{None} indique que l'opération correspondante n'est pas disponible. Par exemple, si une classe assigne @code{None} à @ref{1ede,,__iter__()}, vous ne pouvez pas itérer sur la classe et appeler @ref{7c1,,iter()} sur une instance lève @ref{522,,TypeError} (sans se replier sur @ref{280,,__getitem__()}) @footnote{
The @ref{ae9,,__hash__()}, @ref{1ede,,__iter__()},
@ref{1edf,,__reversed__()}, @ref{1ee0,,__contains__()},
@ref{725,,__class_getitem__()} and @ref{c40,,__fspath__()}
methods have special handling for this. Others
will still raise a @ref{522,,TypeError}, but may do so by relying on
the behavior that @code{None} is not callable.
}.

Lorsque vous implémentez une classe qui émule un type natif, il est important que cette émulation n'implémente que ce qui fait sens pour l'objet qui est modélisé. Par exemple, la recherche d'éléments individuels d'une séquence peut faire sens, mais pas l'extraction d'une tranche (un exemple est l'interface de @code{NodeList} dans le modèle objet des documents W3C).

@menu
* Personnalisation de base:: 
* Personnalisation de l'accès aux attributs:: 
* Personnalisation de la création de classes:: 
* Personnalisation des instances et vérification des sous-classes:: 
* Émulation de types génériques:: 
* Émulation d'objets appelables:: 
* Émulation de types conteneurs:: 
* Émulation de types numériques:: 
* Gestionnaire de contexte With:: 
* Arguments positionnels dans le filtrage par motif sur les classes:: 
* Emulating buffer types:: 
* Recherche des méthodes spéciales:: 

@end menu

@node Personnalisation de base,Personnalisation de l'accès aux attributs,,Méthodes spéciales
@anchor{reference/datamodel basic-customization}@anchor{1ee1}@anchor{reference/datamodel customization}@anchor{1ee2}
@subsubsection Personnalisation de base


@geindex __new__() (méthode object)
@anchor{reference/datamodel object __new__}@anchor{56c}
@deffn {Méthode} object.__new__ (cls[, ...])

@geindex subclassing;immutable types

Appelée pour créer une nouvelle instance de la classe `cls'. La méthode @ref{56c,,__new__()} est statique (c'est un cas particulier, vous n'avez pas besoin de la déclarer comme telle) qui prend comme premier argument la classe pour laquelle on veut créer une instance. Les autres arguments sont ceux passés à l'expression de l'objet constructeur (l'appel à la classe). La valeur de retour de @ref{56c,,__new__()} doit être l'instance du nouvel objet (classiquement une instance de `cls').

Typical implementations create a new instance of the class by invoking the
superclass's @ref{56c,,__new__()} method using @code{super().__new__(cls[, ...])}
with appropriate arguments and then modifying the newly created instance
as necessary before returning it.

Si @ref{56c,,__new__()} est appelée pendant la construction de l'objet et renvoie une instance de `cls', alors la méthode @ref{69b,,__init__()} de la nouvelle instance est invoquée avec @code{__init__(self[, …])} où `self' est la nouvelle instance et les autres arguments sont les mêmes que ceux passés au constructeur de l'objet.

Si @ref{56c,,__new__()} ne renvoie pas une instance de `cls', alors la méthode @ref{69b,,__init__()} de la nouvelle instance n'est pas invoquée.

L'objectif de @ref{56c,,__new__()} est principalement, pour les sous-classes de types immuables (comme @code{int}, @code{str} ou @code{tuple}), d'autoriser la création sur mesure des instances. Elle est aussi souvent surchargée dans les métaclasses pour particulariser la création des classes.
@end deffn

@geindex __init__() (méthode object)
@anchor{reference/datamodel object __init__}@anchor{69b}
@deffn {Méthode} object.__init__ (self[, ...])

@geindex class;constructor

Appelée après la création de l'instance (par @ref{56c,,__new__()}), mais avant le retour vers l'appelant. Les arguments sont ceux passés à l'expression du constructeur de classe. Si une classe de base possède une méthode @ref{69b,,__init__()}, la méthode @ref{69b,,__init__()} de la classe dérivée, si elle existe, doit explicitement appeler cette méthode pour assurer une initialisation correcte de la partie classe de base de l'instance ; par exemple : @code{super().__init__([args…])}.

Comme @ref{56c,,__new__()} et @ref{69b,,__init__()} travaillent ensemble pour créer des objets (@ref{56c,,__new__()} pour le créer, @ref{69b,,__init__()} pour le particulariser), @ref{69b,,__init__()} ne doit pas renvoyer de valeur @code{None} ; sinon une exception @ref{522,,TypeError} est levée à l'exécution.
@end deffn

@geindex __del__() (méthode object)
@anchor{reference/datamodel object __del__}@anchor{1ee3}
@deffn {Méthode} object.__del__ (self)

@geindex destructor
@geindex finalizer
@geindex statement;del

Appelée au moment où une instance est sur le point d'être détruite. On l'appelle aussi finaliseur ou (improprement) destructeur. Si une classe de base possède une méthode @ref{1ee3,,__del__()}, la méthode @ref{1ee3,,__del__()} de la classe dérivée, si elle existe, doit explicitement l'appeler pour s'assurer de l'effacement correct de la partie classe de base de l'instance.

Il est possible (mais pas recommandé) que la méthode @ref{1ee3,,__del__()} retarde la destruction de l'instance en créant une nouvelle référence vers cet objet. Python appelle ceci la `résurrection' d'objet. En fonction de l'implémentation, @ref{1ee3,,__del__()} peut être appelée une deuxième fois au moment où l'objet ressuscité va être détruit ; l'implémentation actuelle de @ref{6e0,,CPython} ne l'appelle qu'une fois.

It is not guaranteed that @ref{1ee3,,__del__()} methods are called for objects
that still exist when the interpreter exits.
@ref{a6a,,weakref.finalize} provides a straightforward way to register
a cleanup function to be called when an object is garbage collected.

@cartouche
@quotation Note 
@code{del x} n'appelle pas directement @code{x.__del__()} — la première décrémente le compteur de références de @code{x}. La seconde n'est appelée que quand le compteur de références de @code{x} atteint zéro.
@end quotation
@end cartouche

`Particularité de l'implémentation CPython :' It is possible for a reference cycle to prevent the reference count
of an object from going to zero.  In this case, the cycle will be
later detected and deleted by the @ref{18a7,,cyclic garbage collector}.  A common cause of reference cycles is when
an exception has been caught in a local variable.  The frame's
locals then reference the exception, which references its own
traceback, which references the locals of all frames caught in the
traceback.


@subsubheading Voir aussi


Documentation du module @ref{5f,,gc}.


@cartouche
@quotation Avertissement 
en raison des conditions particulières qui règnent quand @ref{1ee3,,__del__()} est appelée, les exceptions levées pendant son exécution sont ignorées et, à la place, un avertissement est affiché sur @code{sys.stderr}. En particulier :


@itemize *

@item 
@ref{1ee3,,__del__()} peut être invoquée quand du code arbitraire est en cours d'exécution, et ce dans n'importe quel fil d'exécution. Si @ref{1ee3,,__del__()} a besoin de poser un verrou ou d'accéder à tout autre ressource bloquante, elle peut provoquer un blocage mutuel (`deadlock' en anglais) car la ressource peut être déjà utilisée par le code qui est interrompu pour exécuter la méthode @ref{1ee3,,__del__()}.

@item 
@ref{1ee3,,__del__()} peut être exécutée pendant que l'interpréteur se ferme. En conséquence, les variables globales auxquelles elle souhaite accéder (y compris les autres modules) peuvent déjà être détruites ou assignées à @code{None}. Python garantit que les variables globales dont le nom commence par un tiret bas sont supprimées de leur module avant que les autres variables globales ne le soient ; si aucune autre référence vers ces variables globales n'existe, cela peut aider à s'assurer que les modules importés soient toujours accessibles au moment où la méthode @ref{1ee3,,__del__()} est appelée.
@end itemize
@end quotation
@end cartouche

@geindex repr() (built-in function);__repr__() (object method)
@end deffn

@geindex __repr__() (méthode object)
@anchor{reference/datamodel object __repr__}@anchor{607}
@deffn {Méthode} object.__repr__ (self)

Appelée par la fonction native @ref{7e7,,repr()} pour calculer la représentation « officielle » en chaîne de caractères d'un objet. Tout est fait pour que celle-ci ressemble à une expression Python valide pouvant être utilisée pour recréer un objet avec la même valeur (dans un environnement donné). Si ce n'est pas possible, une chaîne de la forme @code{<…une description utile…>} est renvoyée. La valeur renvoyée doit être un objet chaîne de caractères. Si une classe définit @ref{607,,__repr__()} mais pas @ref{608,,__str__()}, alors @ref{607,,__repr__()} est aussi utilisée quand une représentation « informelle » en chaîne de caractères est demandée pour une instance de cette classe.

This is typically used for debugging, so it is important that the representation
is information-rich and unambiguous. A default implementation is provided by the
@ref{a7a,,object} class itself.

@geindex string;__str__() (object method)
@geindex format() (built-in function);__str__() (object method)
@geindex print() (built-in function);__str__() (object method)
@end deffn

@geindex __str__() (méthode object)
@anchor{reference/datamodel object __str__}@anchor{608}
@deffn {Méthode} object.__str__ (self)

Called by @ref{435,,str(object)}, the default @ref{609,,__format__()} implementation,
and the built-in function @ref{f60,,print()}, to compute the "informal" or nicely
printable string representation of an object.  The return value must be a
@ref{1b8a,,str} object.

Cette méthode diffère de @ref{607,,object.__repr__()} car il n'est pas attendu que @ref{608,,__str__()} renvoie une expression Python valide : une représentation plus agréable à lire ou plus concise peut être utilisée.

L'implémentation par défaut du type natif @ref{a7a,,object} appelle @ref{607,,object.__repr__()} .

@c XXX what about subclasses of string?
@end deffn

@geindex __bytes__() (méthode object)
@anchor{reference/datamodel object __bytes__}@anchor{5d2}
@deffn {Méthode} object.__bytes__ (self)

@geindex built-in function;bytes

Called by @ref{1a47,,bytes} to compute a byte-string representation
of an object. This should return a @ref{1bd,,bytes} object. The @ref{a7a,,object}
class itself does not provide this method.

@geindex string;__format__() (object method)
@geindex string;conversion
@geindex built-in function;print
@end deffn

@geindex __format__() (méthode object)
@anchor{reference/datamodel object __format__}@anchor{609}
@deffn {Méthode} object.__format__ (self, format_spec)

Appelée par la fonction native @ref{60a,,format()} et, par extension, lors de l'évaluation de @ref{997,,chaînes de caractères littérales formatées} et la méthode @ref{60c,,str.format()}. Elle produit une chaîne de caractères « formatée » représentant un objet. L'argument @code{format_spec} est une chaîne de caractères contenant la description des options de formatage voulues. L'interprétation de l'argument @code{format_spec} est laissée au type implémentant @ref{609,,__format__()}. Cependant, la plupart des classes délèguent le formatage aux types natifs ou utilisent une syntaxe similaire pour les options de formatage.

Lisez @ref{1e5,,Mini-langage de spécification de format} pour une description de la syntaxe standard du formatage.

La valeur renvoyée doit être un objet chaîne de caractères.

The default implementation by the @ref{a7a,,object} class should be given
an empty `format_spec' string. It delegates to @ref{608,,__str__()}.


Modifié dans la version 3.4: la méthode @code{__format__} de @code{object} lui-même lève une @ref{522,,TypeError} si vous lui passez une chaîne non vide.



Modifié dans la version 3.7: @code{object.__format__(x, '@w{'})} est maintenant équivalent à @code{str(x)} plutôt qu'à @code{format(str(x), '@w{'})}.

@end deffn

@geindex __lt__() (méthode object)
@geindex __le__() (méthode object)
@geindex __eq__() (méthode object)
@geindex __ne__() (méthode object)
@geindex __gt__() (méthode object)
@geindex __ge__() (méthode object)
@anchor{reference/datamodel richcmpfuncs}@anchor{1ee4}@anchor{reference/datamodel object __lt__}@anchor{127d}
@deffn {Méthode} object.__lt__ (self, other)
@anchor{reference/datamodel object __le__}@anchor{12e9}
@deffnx {Méthode} object.__le__ (self, other)
@anchor{reference/datamodel object __eq__}@anchor{ae8}
@deffnx {Méthode} object.__eq__ (self, other)
@anchor{reference/datamodel object __ne__}@anchor{14ce}
@deffnx {Méthode} object.__ne__ (self, other)
@anchor{reference/datamodel object __gt__}@anchor{12ea}
@deffnx {Méthode} object.__gt__ (self, other)
@anchor{reference/datamodel object __ge__}@anchor{12eb}
@deffnx {Méthode} object.__ge__ (self, other)

@geindex comparisons

Ce sont les méthodes dites de « comparaisons riches ». La correspondance entre les symboles opérateurs et les noms de méthodes est la suivante : @code{x<y} appelle @code{x.__lt__(y)}, @code{x<=y} appelle @code{x.__le__(y)}, @code{x==y} appelle @code{x.__eq__(y)}, @code{x!=y} appelle @code{x.__ne__(y)}, @code{x>y} appelle @code{x.__gt__(y)} et @code{x>=y} appelle @code{x.__ge__(y)}.

A rich comparison method may return the singleton @ref{7bc,,NotImplemented} if it does
not implement the operation for a given pair of arguments. By convention,
@code{False} and @code{True} are returned for a successful comparison. However, these
methods can return any value, so if the comparison operator is used in a Boolean
context (e.g., in the condition of an @code{if} statement), Python will call
@ref{451,,bool()} on the value to determine if the result is true or false.

By default, @code{object} implements @ref{ae8,,__eq__()} by using @code{is}, returning
@ref{7bc,,NotImplemented} in the case of a false comparison:
@code{True if x is y else NotImplemented}. For @ref{14ce,,__ne__()}, by default it
delegates to @ref{ae8,,__eq__()} and inverts the result unless it is
@code{NotImplemented}.  There are no other implied relationships among the
comparison operators or default implementations; for example, the truth of
@code{(x<y or x==y)} does not imply @code{x<=y}. To automatically generate ordering
operations from a single root operation, see @ref{f2d,,functools.total_ordering()}.

By default, the @ref{a7a,,object} class provides implementations consistent
with @ref{1809,,Comparaisons de valeurs}: equality compares according to
object identity, and order comparisons raise @ref{522,,TypeError}. Each default
method may generate these results directly, but may also return
@ref{7bc,,NotImplemented}.

Lisez le paragraphe @ref{ae9,,__hash__()} pour connaître certaines notions importantes relatives à la création d'objets @ref{5fb,,hachables} qui acceptent les opérations de comparaison personnalisées et qui sont utilisables en tant que clés de dictionnaires.

There are no swapped-argument versions of these methods (to be used when the
left argument does not support the operation but the right argument does);
rather, @ref{127d,,__lt__()} and @ref{12ea,,__gt__()} are each other's reflection,
@ref{12e9,,__le__()} and @ref{12eb,,__ge__()} are each other's reflection, and
@ref{ae8,,__eq__()} and @ref{14ce,,__ne__()} are their own reflection.
If the operands are of different types, and the right operand's type is
a direct or indirect subclass of the left operand's type,
the reflected method of the right operand has priority, otherwise
the left operand's method has priority.  Virtual subclassing is
not considered.

When no appropriate method returns any value other than @ref{7bc,,NotImplemented}, the
@code{==} and @code{!=} operators will fall back to @code{is} and @code{is not}, respectively.
@end deffn

@geindex __hash__() (méthode object)
@anchor{reference/datamodel object __hash__}@anchor{ae9}
@deffn {Méthode} object.__hash__ (self)

@geindex object;dictionary
@geindex built-in function;hash

Appelée par la fonction native @ref{5d5,,hash()} et par les opérations sur les membres de collections hachées (ce qui comprend @ref{5c3,,set}, @ref{5c4,,frozenset} et @ref{253,,dict}). La méthode @code{__hash__()} doit renvoyer un entier. La seule propriété requise est que les objets qui sont égaux pour la comparaison doivent avoir la même valeur de hachage ; il est conseillé de mélanger les valeurs de hachage des composants d'un objet qui jouent un rôle dans la comparaison des objets, en les emballant dans un `n'-uplet dont on calcule l'empreinte. Par exemple :

@example
def __hash__(self):
    return hash((self.name, self.nick, self.color))
@end example

@cartouche
@quotation Note 
@ref{5d5,,hash()} limite la valeur renvoyée d'un objet ayant une méthode @ref{ae9,,__hash__()} personnalisée à la taille d'un @ref{a4e,,Py_ssize_t}. C'est classiquement 8 octets pour une implémentation 64 bits et 4 octets sur une implémentation 32 bits. Si la méthode @ref{ae9,,__hash__()} d'un objet doit être interopérable sur des plateformes ayant des implémentations différentes, assurez-vous de vérifier la taille du hachage sur toutes les plateformes. Une manière facile de le faire est la suivante : @code{python -c "import sys; print(sys.hash_info.width)"}.
@end quotation
@end cartouche

If a class does not define an @ref{ae8,,__eq__()} method it should not define a
@ref{ae9,,__hash__()} operation either; if it defines @ref{ae8,,__eq__()} but not
@ref{ae9,,__hash__()}, its instances will not be usable as items in hashable
collections.  If a class defines mutable objects and implements an
@ref{ae8,,__eq__()} method, it should not implement @ref{ae9,,__hash__()}, since the
implementation of @ref{5fb,,hashable} collections requires that a key's hash value is
immutable (if the object's hash value changes, it will be in the wrong hash
bucket).

User-defined classes have @ref{ae8,,__eq__()} and @ref{ae9,,__hash__()} methods
by default (inherited from the @ref{a7a,,object} class); with them, all objects compare
unequal (except with themselves) and @code{x.__hash__()} returns an appropriate
value such that @code{x == y} implies both that @code{x is y} and @code{hash(x) == hash(y)}.

Une classe qui surcharge @ref{ae8,,__eq__()} et qui ne définit pas @ref{ae9,,__hash__()} a sa méthode @ref{ae9,,__hash__()} implicitement assignée à @code{None}. Quand la méthode @ref{ae9,,__hash__()} d'une classe est @code{None}, une instance de cette classe lève @ref{522,,TypeError} quand un programme essaie de demander son empreinte et elle est correctement identifiée comme `non hachable' quand on vérifie @code{isinstance(obj, collections.abc.Hashable)}.

Si une classe qui surcharge @ref{ae8,,__eq__()} a besoin de conserver l'implémentation de @ref{ae9,,__hash__()} de la classe parente, vous devez l'indiquer explicitement à l'interpréteur en définissant @code{__hash__ = <ClasseParente>.__hash__}.

Si une classe ne surcharge pas @ref{ae8,,__eq__()} et veut supprimer le calcul des empreintes, elle doit inclure @code{__hash__ = None} dans la définition de la classe. Une classe qui définit sa propre méthode @ref{ae9,,__hash__()} qui lève explicitement @ref{522,,TypeError} serait incorrectement identifiée comme hachable par un appel à @code{isinstance(obj, collections.abc.Hashable)}.

@cartouche
@quotation Note 
par défaut, les valeurs renvoyées par @ref{ae9,,__hash__()} pour les chaînes et les `bytes' sont « salées » avec une valeur aléatoire non prévisible. Bien qu'une empreinte reste constante tout au long d'un processus Python, sa valeur n'est pas prévisible entre deux invocations de Python.

This is intended to provide protection against a denial-of-service caused
by carefully chosen inputs that exploit the worst case performance of a
dict insertion, `O'(`n'@w{^2}) complexity.  See
@indicateurl{http://ocert.org/advisories/ocert-2011-003.html} for details.

Modifier les empreintes obtenues par hachage modifie l'ordre d'itération sur les `sets'. Python n'a jamais donné de garantie sur cet ordre (d'ailleurs, l'ordre n'est pas le même entre les implémentations 32 et 64 bits).

Voir aussi 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED}.
@end quotation
@end cartouche


Modifié dans la version 3.3: la randomisation des empreintes est activée par défaut.

@end deffn

@geindex __bool__() (méthode object)
@anchor{reference/datamodel object __bool__}@anchor{12b3}
@deffn {Méthode} object.__bool__ (self)

@geindex __len__() (mapping object method)

Called to implement truth value testing and the built-in operation
@code{bool()}; should return @code{False} or @code{True}.  When this method is not
defined, @ref{1ee5,,__len__()} is called, if it is defined, and the object is
considered true if its result is nonzero.  If a class defines neither
@code{__len__()} nor @code{__bool__()} (which is true of the @ref{a7a,,object}
class itself), all its instances are considered true.
@end deffn

@node Personnalisation de l'accès aux attributs,Personnalisation de la création de classes,Personnalisation de base,Méthodes spéciales
@anchor{reference/datamodel attribute-access}@anchor{1ee6}@anchor{reference/datamodel customizing-attribute-access}@anchor{1ee7}
@subsubsection Personnalisation de l'accès aux attributs


Les méthodes suivantes peuvent être définies pour personnaliser l'accès aux attributs (utilisation, assignation, suppression de @code{x.name}) pour les instances de classes.

@c XXX explain how descriptors interfere here!

@geindex __getattr__() (méthode object)
@anchor{reference/datamodel object __getattr__}@anchor{4bc}
@deffn {Méthode} object.__getattr__ (self, name)

Called when the default attribute access fails with an @ref{343,,AttributeError}
(either @ref{bc0,,__getattribute__()} raises an @ref{343,,AttributeError} because
`name' is not an instance attribute or an attribute in the class tree
for @code{self}; or @ref{149d,,__get__()} of a `name' property raises
@ref{343,,AttributeError}).  This method should either return the (computed)
attribute value or raise an @ref{343,,AttributeError} exception.
The @ref{a7a,,object} class itself does not provide this method.

Note that if the attribute is found through the normal mechanism,
@ref{4bc,,__getattr__()} is not called.  (This is an intentional asymmetry between
@ref{4bc,,__getattr__()} and @ref{1eb2,,__setattr__()}.) This is done both for efficiency
reasons and because otherwise @ref{4bc,,__getattr__()} would have no way to access
other attributes of the instance.  Note that at least for instance variables,
you can take total control by not inserting any values in the instance attribute
dictionary (but instead inserting them in another object).  See the
@ref{bc0,,__getattribute__()} method below for a way to actually get total control
over attribute access.
@end deffn

@geindex __getattribute__() (méthode object)
@anchor{reference/datamodel object __getattribute__}@anchor{bc0}
@deffn {Méthode} object.__getattribute__ (self, name)

Appelée de manière inconditionnelle pour implémenter l'accès aux attributs des instances de la classe. Si la classe définit également @ref{4bc,,__getattr__()}, cette dernière n'est pas appelée à moins que @ref{bc0,,__getattribute__()} ne l'appelle explicitement ou ne lève une exception @ref{343,,AttributeError}. Cette méthode doit renvoyer la valeur (calculée) de l'attribut ou lever une exception @ref{343,,AttributeError}. Afin d'éviter une récursion infinie sur cette méthode, son implémentation doit toujours appeler la méthode de la classe de base avec le même paramètre `name' pour accéder à n'importe quel attribut dont elle a besoin. Par exemple, @code{object.__getattribute__(self, name)}.

@cartouche
@quotation Note 
This method may still be bypassed when looking up special methods as the
result of implicit invocation via language syntax or
@ref{1e84,,built-in functions}.
See @ref{1ee8,,Recherche des méthodes spéciales}.
@end quotation
@end cartouche

Pour les accès à certains attributs sensibles, lève un @ref{1848,,événement d'audit} @code{object.__getattr__} avec les arguments @code{obj} et @code{name}.
@end deffn

@geindex __setattr__() (méthode object)
@anchor{reference/datamodel object __setattr__}@anchor{1eb2}
@deffn {Méthode} object.__setattr__ (self, name, value)

Appelée lors d'une assignation d'attribut. Elle est appelée à la place du mécanisme normal (c'est-à-dire stocker la valeur dans le dictionnaire de l'instance). `name' est le nom de l'attribut, `value' est la valeur à assigner à cet attribut.

Si @ref{1eb2,,__setattr__()} veut assigner un attribut d'instance, elle doit appeler la méthode de la classe de base avec le même nom, par exemple @code{object.__setattr__(self, name, value)}.

Pour les assignations de certains attributs sensibles, lève un @ref{1848,,événement d'audit} @code{object.__setattr__} avec les arguments @code{obj}, @code{name} et @code{value}.
@end deffn

@geindex __delattr__() (méthode object)
@anchor{reference/datamodel object __delattr__}@anchor{1eb3}
@deffn {Méthode} object.__delattr__ (self, name)

Comme @ref{1eb2,,__setattr__()} mais pour supprimer un attribut au lieu de l'assigner. Elle ne doit être implémentée que si @code{del obj.name} a du sens pour cet objet.

Pour les suppressions de certains attributs sensibles, lève un @ref{1848,,événement d'audit} @code{object.__deltattr__} avec les arguments @code{obj} et @code{name}.
@end deffn

@geindex __dir__() (méthode object)
@anchor{reference/datamodel object __dir__}@anchor{1ee9}
@deffn {Méthode} object.__dir__ (self)

Called when @ref{61d,,dir()} is called on the object. An iterable must be
returned. @ref{61d,,dir()} converts the returned iterable to a list and sorts it.
@end deffn

@menu
* Personnalisation de l'accès aux attributs d'un module:: 
* Implémentation de descripteurs:: 
* Invocation des descripteurs:: 
* créneaux prédéfinis (__slots__): créneaux prédéfinis __slots__. 

@end menu

@node Personnalisation de l'accès aux attributs d'un module,Implémentation de descripteurs,,Personnalisation de l'accès aux attributs
@anchor{reference/datamodel customizing-module-attribute-access}@anchor{1eea}
@subsubsection Personnalisation de l'accès aux attributs d'un module


@geindex __getattr__ (module attribute)
@geindex __dir__ (module attribute)
@geindex __class__ (module attribute)

Les noms spéciaux @code{__getattr__} et @code{__dir__} peuvent aussi être personnalisés pour accéder aux attributs du module. La fonction @code{__getattr__} au niveau du module doit accepter un argument qui est un nom d'attribut et doit renvoyer la valeur calculée ou lever une @ref{343,,AttributeError}. Si un attribut n'est pas trouvé dans l'objet module en utilisant la recherche normale, c'est-à-dire @ref{bc0,,object.__getattribute__()}, alors Python recherche @code{__getattr__} dans le @code{__dict__} du module avant de lever une @ref{343,,AttributeError}. S'il la trouve, il l'appelle avec le nom de l'attribut et renvoie le résultat.

The @code{__dir__} function should accept no arguments, and return an iterable of
strings that represents the names accessible on module. If present, this
function overrides the standard @ref{61d,,dir()} search on a module.

Pour une personnalisation plus fine du comportement d'un module (assignation des attributs, propriétés, etc.), vous pouvez assigner l'attribut @code{__class__} d'un objet module à une sous-classe de @ref{e00,,types.ModuleType}. Par exemple :

@example
import sys
from types import ModuleType

class VerboseModule(ModuleType):
    def __repr__(self):
        return f'Verbose @{self.__name__@}'

    def __setattr__(self, attr, value):
        print(f'Setting @{attr@}...')
        super().__setattr__(attr, value)

sys.modules[__name__].__class__ = VerboseModule
@end example

@cartouche
@quotation Note 
définir @code{__getattr__} du module et @code{__class__} pour le module impacte uniquement les recherches qui utilisent la syntaxe d'accès aux attributs — accéder directement aux globales d'un module (soit par le code dans le module, soit `via' une référence au dictionnaire des variables globales du module) fonctionne toujours de la même façon.
@end quotation
@end cartouche


Modifié dans la version 3.5: l'attribut @code{__class__} du module est maintenant en lecture-écriture.



Ajouté dans la version 3.7: attributs @code{__getattr__} et @code{__dir__} du module.



@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 562

@item PEP 562@footnote{https://peps.python.org/pep-0562/} — @code{__getattr__} et @code{__dir__} pour un module

Décrit les fonctions @code{__getattr__} et @code{__dir__} des modules.
@end table


@node Implémentation de descripteurs,Invocation des descripteurs,Personnalisation de l'accès aux attributs d'un module,Personnalisation de l'accès aux attributs
@anchor{reference/datamodel descriptors}@anchor{c3d}@anchor{reference/datamodel implementing-descriptors}@anchor{1eeb}
@subsubsection Implémentation de descripteurs


The following methods only apply when an instance of the class containing the
method (a so-called `descriptor' class) appears in an `owner' class (the
descriptor must be in either the owner's class dictionary or in the class
dictionary for one of its parents).  In the examples below, "the attribute"
refers to the attribute whose name is the key of the property in the owner
class' @ref{546,,__dict__}.  The @ref{a7a,,object} class itself does not
implement any of these protocols.

@geindex __get__() (méthode object)
@anchor{reference/datamodel object __get__}@anchor{149d}
@deffn {Méthode} object.__get__ (self, instance, owner=None)

Appelée pour obtenir l'attribut de la classe propriétaire (accès à un attribut de classe) ou d'une instance de cette classe (accès à un attribut d'instance). L'argument optionnel `owner' est la classe propriétaire alors que `instance' est l'instance par laquelle on accède à l'attribut ou @code{None} lorsque l'on accède par la classe `owner'.

Il convient que cette méthode renvoie la valeur calculée de l'attribut ou lève une exception @ref{343,,AttributeError}.

La 
@geindex Python Enhancement Proposals; PEP 252
PEP 252@footnote{https://peps.python.org/pep-0252/} spécifie que @ref{149d,,__get__()} soit un appelable avec un ou deux arguments. Les descripteurs natifs de Python suivent cette spécification ; cependant, il est probable que des outils tiers aient des descripteurs qui requièrent les deux arguments. L'implémentation de @ref{bc0,,__getattribute__()} de Python passe toujours les deux arguments, qu'ils soient requis ou non.
@end deffn

@geindex __set__() (méthode object)
@anchor{reference/datamodel object __set__}@anchor{1eec}
@deffn {Méthode} object.__set__ (self, instance, value)

Appelée pour définir l'attribut d'une instance `instance' de la classe propriétaire à la nouvelle valeur `value'.

Notez que ajouter @ref{1eec,,__set__()} ou @ref{1591,,__delete__()} modifie la nature du descripteur vers un « descripteur de donnée ». Reportez-vous à @ref{1eed,,Invocation des descripteurs} pour plus de détails.
@end deffn

@geindex __delete__() (méthode object)
@anchor{reference/datamodel object __delete__}@anchor{1591}
@deffn {Méthode} object.__delete__ (self, instance)

Appelée pour supprimer l'attribut de l'instance `instance' de la classe propriétaire.
@end deffn

Instances of descriptors may also have the @code{__objclass__} attribute
present:

@geindex __objclass__ (attribut object)
@anchor{reference/datamodel object __objclass__}@anchor{1eee}
@deffn {Attribut} object.__objclass__

The attribute @code{__objclass__} is interpreted by the @ref{7d,,inspect} module
as specifying the class where this object was defined (setting this
appropriately can assist in runtime introspection of dynamic class attributes).
For callables, it may indicate that an instance of the given type (or a
subclass) is expected or required as the first positional argument (for example,
CPython sets this attribute for unbound methods that are implemented in C).
@end deffn

@node Invocation des descripteurs,créneaux prédéfinis __slots__,Implémentation de descripteurs,Personnalisation de l'accès aux attributs
@anchor{reference/datamodel descriptor-invocation}@anchor{1eed}@anchor{reference/datamodel invoking-descriptors}@anchor{1eef}
@subsubsection Invocation des descripteurs


En général, un descripteur est un attribut d'objet dont le comportement est « lié » (`binding dehavior' en anglais), c'est-à-dire que les accès aux attributs ont été surchargés par des méthodes conformes au protocole des descripteurs : @ref{149d,,__get__()}, @ref{1eec,,__set__()} et @ref{1591,,__delete__()}. Si l'une de ces méthodes est définie pour un objet, il est réputé être un descripteur.

Le comportement par défaut pour la gestion d'un attribut est de définir, obtenir et supprimer cet attribut du dictionnaire de l'objet. Par exemple, pour @code{a.x} Python commence d'abord par rechercher @code{a.__dict__['x']}, puis @code{type(a).__dict__['x']} ; ensuite Python continue en remontant les classes de base de @code{type(a)}, en excluant les métaclasses.

Cependant, si la valeur cherchée est un objet qui définit une des méthodes de descripteur, alors Python modifie son comportement et invoque la méthode du descripteur à la place. Le moment où cela intervient dans la recherche citée ci-dessus dépend de l'endroit où a été définie la méthode de descripteur et comment elle a été appelée.

Le point de départ pour une invocation de descripteur est la liaison @code{a.x}. La façon dont les arguments sont assemblés dépend de @code{a} :


@table @asis

@item Appel direct

Le plus simple et le plus rare des appels est quand l'utilisateur code directement l'appel à la méthode du descripteur : @code{x.__get__(a)}.

@item Liaison avec une instance

Si elle est liée à un objet instance, @code{a.x} est transformé en l'appel suivant : @code{type(a).__dict__['x'].__get__(a, type(a))}.

@item Liaison avec une classe

Si elle est liée à une classe, @code{A.x} est transformé en l'appel suivant : @code{A.__dict__['x'].__get__(None, A)}.

@item Liaison super

Une recherche avec un point telle que @code{super(A, a).x} cherche @code{a.__class__.__mro__} pour une classe de base @code{B} qui suit (dans l'ordre MRO) @code{A}, puis renvoie @code{B.__dict__['x'].__get__(a, A)}.  Si ce n'est pas un descripteur, @code{x} est renvoyé inchangé.
@end table

@c class Desc:
@c     def __get__(*args):
@c         return args
@c 
@c class B:
@c 
@c     x = Desc()
@c 
@c class A(B):
@c 
@c     x = 999
@c 
@c     def m(self):
@c         'Demonstrate these two descriptor invocations are equivalent'
@c         result1 = super(A, self).x
@c         result2 = B.__dict__['x'].__get__(self, A)
@c         return result1 == result2

@c >>> a = A()
@c >>> a.__class__.__mro__.index(B) > a.__class__.__mro__.index(A)
@c True
@c >>> super(A, a).x == B.__dict__['x'].__get__(a, A)
@c True
@c >>> a.m()
@c True

For instance bindings, the precedence of descriptor invocation depends on
which descriptor methods are defined.  A descriptor can define any combination
of @ref{149d,,__get__()}, @ref{1eec,,__set__()} and
@ref{1591,,__delete__()}.  If it does not
define @code{__get__()}, then accessing the attribute will return the descriptor
object itself unless there is a value in the object's instance dictionary.  If
the descriptor defines @code{__set__()} and/or @code{__delete__()}, it is a data
descriptor; if it defines neither, it is a non-data descriptor.  Normally, data
descriptors define both @code{__get__()} and @code{__set__()}, while non-data
descriptors have just the @code{__get__()} method.  Data descriptors with
@code{__get__()} and @code{__set__()} (and/or @code{__delete__()}) defined
always override a redefinition in an
instance dictionary.  In contrast, non-data descriptors can be overridden by
instances.

Les méthodes Python (y compris celles décorées par @ref{40c,,@@staticmethod} et @ref{165,,@@classmethod}) sont implémentées comme des descripteurs hors-données. De la même manière, les instances peuvent redéfinir et surcharger les méthodes. Ceci permet à chaque instance d'avoir un comportement qui diffère des autres instances de la même classe.

La fonction @ref{192,,property()} est implémentée en tant que descripteur de données. Ainsi, les instances ne peuvent pas surcharger le comportement d'une propriété.

@node créneaux prédéfinis __slots__,,Invocation des descripteurs,Personnalisation de l'accès aux attributs
@anchor{reference/datamodel id13}@anchor{1ef0}@anchor{reference/datamodel slots}@anchor{1eb5}
@subsubsection créneaux prédéfinis (@code{__slots__})


Les créneaux prédéfinis (@code{__slots__}) vous permettent de déclarer des membres d'une donnée (comme une propriété) et d'interdire la création de @ref{546,,__dict__} ou de `__weakref__' (à moins qu'ils ne soient explicitement déclarés dans le @code{__slots__} ou présent dans le parent).

L'espace gagné par rapport à l'utilisation d'un @ref{546,,__dict__} peut être significatif. La recherche d'attribut peut aussi s'avérer beaucoup plus rapide.

@geindex object.__slots__ (variable de base)
@anchor{reference/datamodel object __slots__}@anchor{14a0}
@deffn {Données} object.__slots__

Cette variable de classe peut être assignée avec une chaîne, un itérable ou une séquence de chaînes avec les noms de variables utilisés par les instances. `__slots__' réserve de la place pour ces variables déclarées et interdit la création automatique de @ref{546,,__dict__} et `__weakref__' pour chaque instance.
@end deffn
@anchor{reference/datamodel datamodel-note-slots}@anchor{1ef1}
Notes on using `__slots__':


@itemize *

@item 
Lorsque vous héritez d'une classe sans `__slots__', les attributs @ref{546,,__dict__} et `__weakref__' des instances sont toujours accessibles.

@item 
Sans variable @ref{546,,__dict__}, les instances ne peuvent pas assigner de nouvelles variables (non listées dans la définition de `__slots__'). Les tentatives d'assignation sur un nom de variable non listé lève @ref{343,,AttributeError}. Si l'assignation dynamique de nouvelles variables est nécessaire, ajoutez @code{'__dict__'} à la séquence de chaînes dans la déclaration `__slots__'.

@item 
Sans variable `__weakref__' pour chaque instance, les classes qui définissent `__slots__' ne gèrent pas les @ref{113,,références faibles} vers leurs instances. Si vous avez besoin de gérer des références faibles, ajoutez @code{'__weakref__'} à la séquence de chaînes dans la déclaration de `__slots__'.

@item 
Les `__slots__' sont implémentés au niveau de la classe en créant des @ref{c3d,,descripteurs} pour chaque nom de variable. Ainsi, les attributs de classe ne peuvent pas être utilisés pour des valeurs par défaut aux variables d'instances définies par `__slots__' ; sinon, l'attribut de classe surchargerait l'assignation par descripteur.

@item 
The action of a `__slots__' declaration is not limited to the class
where it is defined.  `__slots__' declared in parents are available in
child classes. However, instances of a child subclass will get a
@ref{546,,__dict__} and `__weakref__' unless the subclass also defines
`__slots__' (which should only contain names of any `additional' slots).

@item 
Si une classe définit un `slot' déjà défini dans une classe de base, la variable d'instance définie par la classe de base est inaccessible (sauf à utiliser le descripteur de la classe de base directement). Cela rend la signification du programme indéfinie. Dans le futur, une vérification sera ajoutée pour empêcher cela.

@item 
@ref{522,,TypeError} will be raised if nonempty `__slots__' are defined for a
class derived from a
@ref{1ef2,,"variable-length" built-in type} such as
@ref{254,,int}, @ref{1bd,,bytes}, and @ref{366,,tuple}.

@item 
Tout @ref{1205,,itérable}, sauf les chaînes de caractères, peuvent être affectés à `__slots__'.

@item 
Si vous affectez `__slots__' à un @ref{253,,dictionnaire}, les clés du dictionnaires seront les noms du `slot'. Les valeurs du dictionnaire peuvent être utilisées en tant que chaines de description (`docstrings') et sont reconnues par @ref{9e8,,inspect.getdoc()} qui les affiche dans la sortie de @ref{8c4,,help()}.

@item 
@ref{1461,,__class__} assignment works only if both classes have the
same `__slots__'.

@item 
L'@ref{1c46,,héritage multiple} avec plusieurs classes parentes qui ont des `__slots__' est possible, mais seul un parent peut avoir des attributs créés par `__slots__' (les autres classes parentes doivent avoir des `__slots__' vides). La violation de cette règle lève @ref{522,,TypeError}.

@item 
Si un @ref{1aa,,itérateur} est utilisé pour `__slots__', alors un @ref{1ef3,,descripteur} est créé pour chacune des valeurs de l'itérateur. Cependant, l'attribut `__slots__' est un itérateur vide.
@end itemize

@node Personnalisation de la création de classes,Personnalisation des instances et vérification des sous-classes,Personnalisation de l'accès aux attributs,Méthodes spéciales
@anchor{reference/datamodel class-customization}@anchor{c39}@anchor{reference/datamodel customizing-class-creation}@anchor{1ef4}
@subsubsection Personnalisation de la création de classes


Quand une classe hérite d'une classe parente, la méthode @ref{61c,,__init_subclass__()} de la classe parente est appelée. Ainsi, il est possible d'écrire des classes qui modifient le comportement des sous-classes. Ce comportement est corrélé aux décorateurs de classes mais, alors que les décorateurs de classes agissent seulement sur la classe qu'ils décorent, @code{__init_subclass__} agit uniquement sur les futures sous-classes de la classe qui définit cette méthode.

@geindex __init_subclass__() (méthode de la classe object)
@anchor{reference/datamodel object __init_subclass__}@anchor{61c}
@deffn {Méthode} classmethod object.__init_subclass__ (cls)

Cette méthode est appelée quand la classe est sous-classée. `cls' est alors la nouvelle sous-classe. Si elle est définie en tant que méthode d'instance normale, cette méthode est implicitement convertie en méthode de classe.

Keyword arguments which are given to a new class are passed to
the parent class's @code{__init_subclass__}. For compatibility with
other classes using @code{__init_subclass__}, one should take out the
needed keyword arguments and pass the others over to the base
class, as in:

@example
class Philosopher:
    def __init_subclass__(cls, /, default_name, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.default_name = default_name

class AustralianPhilosopher(Philosopher, default_name="Bruce"):
    pass
@end example

L'implémentation par défaut de @code{object.__init_subclass__} ne fait rien sans argument, mais lève une erreur si elle est appelée avec un argument ou plus.

@cartouche
@quotation Note 
l'indication de métaclasse @code{metaclass} est absorbée par le reste du mécanisme de types et n'est jamais passée à l'implémentation de @code{__init_subclass__}. La métaclasse réelle (plutôt que l'indication explicite) peut être récupérée par @code{type(cls)}.
@end quotation
@end cartouche


Ajouté dans la version 3.6.

@end deffn

Lorsqu'une classe est créée, @code{type.__new__()} exécute le point d'entrée @code{___set_name__()} de toute variable de la classe qui en possède un.

@geindex __set_name__() (méthode object)
@anchor{reference/datamodel object __set_name__}@anchor{c3c}
@deffn {Méthode} object.__set_name__ (self, owner, name)

Appelée automatiquement au moment où la classe propriétaire `owner' est créée. L'objet `self' a été assigné à `name' dans `owner' :

@example
class A:
    x = C()  # Automatically calls: x.__set_name__(A, 'x')
@end example

Si l'affectation se produit après la création de la classe, le point d'entrée @ref{c3c,,__set_name__()} n'est pas appelé automatiquement. Mais il est autorisé d'appeler @ref{c3c,,__set_name__()} manuellement :

@example
class A:
   pass

c = C()
A.x = c                  # The hook is not called
c.__set_name__(A, 'x')   # Manually invoke the hook
@end example

Consultez @ref{c38,,Création de l'objet classe} pour davantage de détails.


Ajouté dans la version 3.6.

@end deffn

@menu
* Métaclasses:: 
* Résolution des entrées MRO:: 
* Détermination de la métaclasse appropriée:: 
* Préparation de l'espace de nommage de la classe:: 
* Exécution du corps de la classe:: 
* Création de l'objet classe:: 
* Cas d'utilisations des métaclasses:: 

@end menu

@node Métaclasses,Résolution des entrées MRO,,Personnalisation de la création de classes
@anchor{reference/datamodel id14}@anchor{1ef5}@anchor{reference/datamodel metaclasses}@anchor{1ef6}
@subsubsection Métaclasses


@geindex metaclass
@geindex built-in function;type
@geindex = (equals);class definition

Par défaut, les classes sont construites en utilisant @ref{d36,,type()}. Le corps de la classe est exécuté dans un nouvel espace de nommage et le nom de la classe est lié localement au résultat de @code{type(name, bases, namespace)}.

Le déroulement de création de la classe peut être personnalisé en passant l'argument nommé @code{metaclass} dans la ligne de définition de la classe ou en héritant d'une classe existante qui comporte déjà un tel argument. Dans l'exemple qui suit, @code{MyClass} et @code{MySubclass} sont des instances de @code{Meta} :

@example
class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass
@end example

Tout autre argument nommé spécifié dans la définition de la classe est passé aux opérations de métaclasses décrites auparavant.

Quand la définition d'une classe est exécutée, les différentes étapes suivies sont :


@itemize *

@item 
les entrées MRO sont résolues ;

@item 
la métaclasse appropriée est déterminée ;

@item 
l'espace de nommage de la classe est préparé ;

@item 
le corps de la classe est exécuté ;

@item 
l'objet classe est créé.
@end itemize

@node Résolution des entrées MRO,Détermination de la métaclasse appropriée,Métaclasses,Personnalisation de la création de classes
@anchor{reference/datamodel resolving-mro-entries}@anchor{1ef7}
@subsubsection Résolution des entrées MRO


@geindex __mro_entries__() (méthode object)
@anchor{reference/datamodel object __mro_entries__}@anchor{1ef8}
@deffn {Méthode} object.__mro_entries__ (self, bases)

If a base that appears in a class definition is not an instance of
@ref{d36,,type}, then an @code{__mro_entries__()} method is searched on the base.
If an @code{__mro_entries__()} method is found, the base is substituted with the
result of a call to @code{__mro_entries__()} when creating the class.
The method is called with the original bases tuple
passed to the `bases' parameter, and must return a tuple
of classes that will be used instead of the base. The returned tuple may be
empty: in these cases, the original base is ignored.
@end deffn


@subsubheading Voir aussi



@table @asis

@item @ref{b8a,,types.resolve_bases()}

Dynamically resolve bases that are not instances of @ref{d36,,type}.

@item @ref{4b7,,types.get_original_bases()}

Retrieve a class's "original bases" prior to modifications by
@ref{1ef8,,__mro_entries__()}.

@geindex Python Enhancement Proposals; PEP 560

@item PEP 560@footnote{https://peps.python.org/pep-0560/}

Core support for typing module and generic types.
@end table


@node Détermination de la métaclasse appropriée,Préparation de l'espace de nommage de la classe,Résolution des entrées MRO,Personnalisation de la création de classes
@anchor{reference/datamodel determining-the-appropriate-metaclass}@anchor{1ef9}
@subsubsection Détermination de la métaclasse appropriée


@geindex metaclass hint

La métaclasse appropriée pour une définition de classe est déterminée de la manière suivante :


@itemize *

@item 
si aucune classe et aucune métaclasse n'est donnée, alors @ref{d36,,type()} est utilisée ;

@item 
si une métaclasse explicite est donnée et que `ce n'est pas' une instance de @ref{d36,,type()}, alors elle est utilisée directement en tant que métaclasse ;

@item 
si une instance de @ref{d36,,type()} est donnée comme métaclasse explicite ou si `bases' est définie, alors la métaclasse la plus dérivée est utilisée.
@end itemize

La métaclasse la plus dérivée est choisie à partir des métaclasses explicitement spécifiées (s'il y en a) et les métaclasses (c'est-à-dire les @code{type(cls)}) de toutes les classes de base spécifiées. La métaclasse la plus dérivée est celle qui est un sous-type de `toutes' ces métaclasses candidates. Si aucune des métaclasses candidates ne remplit ce critère, alors la définition de la classe échoue en levant @code{TypeError}.

@node Préparation de l'espace de nommage de la classe,Exécution du corps de la classe,Détermination de la métaclasse appropriée,Personnalisation de la création de classes
@anchor{reference/datamodel prepare}@anchor{c4c}@anchor{reference/datamodel preparing-the-class-namespace}@anchor{1efa}
@subsubsection Préparation de l'espace de nommage de la classe


@geindex __prepare__ (metaclass method)

Une fois que la métaclasse appropriée est identifiée, l'espace de nommage de la classe est préparé. Si la métaclasse possède un attribut @code{__prepare__}, il est appelé avec @code{namespace = metaclass.__prepare__(name, bases, **kwds)} (où les arguments nommés supplémentaires, s'il y en a, sont les arguments de la définition de la classe). La méthode @code{__prepare__} doit être implémentée comme une @ref{165,,méthode de classe}). L’espace de nommage renvoyé par @code{__prepare__} est passé à @code{__new__}, mais quand l’instance finale est créée, l’espace de nommage est copié vers un nouveau @code{dict}.

Si la métaclasse ne possède pas d'attribut @code{__prepare__}, alors l'espace de nommage de la classe est initialisé en tant que tableau de correspondances ordonné.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} — Métaclasses dans Python 3000

introduction de la fonction automatique @code{__prepare__} de l'espace de nommage
@end table


@node Exécution du corps de la classe,Création de l'objet classe,Préparation de l'espace de nommage de la classe,Personnalisation de la création de classes
@anchor{reference/datamodel executing-the-class-body}@anchor{1efb}
@subsubsection Exécution du corps de la classe


@geindex class;body

Le corps de la classe est exécuté (approximativement) avec @code{exec(body, globals(), namespace)}. La principale différence avec un appel normal à @ref{17d,,exec()} est que la portée lexicale autorise le corps de la classe (y compris les méthodes) à faire référence aux noms de la portée courante et des portées externes lorsque la définition de classe a lieu dans une fonction.

Cependant, même quand une définition de classe intervient dans une fonction, les méthodes définies à l'intérieur de la classe ne peuvent pas voir les noms définis en dehors de la portée de la classe. On accède aux variables de la classe `via' le premier paramètre des méthodes d'instance ou de classe, ou `via' la référence implicite @code{__class__} incluse dans la portée lexicale et décrite dans la section suivante.

@node Création de l'objet classe,Cas d'utilisations des métaclasses,Exécution du corps de la classe,Personnalisation de la création de classes
@anchor{reference/datamodel class-object-creation}@anchor{c38}@anchor{reference/datamodel creating-the-class-object}@anchor{1efc}
@subsubsection Création de l'objet classe


@geindex __class__ (method cell)
@geindex __classcell__ (class namespace entry)

Quand l'espace de nommage a été rempli en exécutant le corps de la classe, l'objet classe est créé en appelant @code{metaclass(name, bases, namespace, **kwds)} (les arguments nommés supplémentaires passés ici sont les mêmes que ceux passés à @code{__prepare__}).

Cet objet classe est celui qui est référencé par la forme sans argument de @ref{4c5,,super()}. @code{__class__} est une référence implicite créée par le compilateur si une méthode du corps de la classe fait référence soit à @code{__class__}, soit à @code{super}. Ceci permet que la forme sans argument de @ref{4c5,,super()} identifie la classe en cours de définition en fonction de la portée lexicale, tandis que la classe ou l'instance utilisée pour effectuer l'appel en cours est identifiée en fonction du premier argument transmis à la méthode.

`Particularité de l'implémentation CPython :' dans CPython 3.6 et suivants, la cellule @code{__class__} est passée à la métaclasse en tant qu'entrée @code{__classcell__} dans l'espace de nommage de la classe. Si elle est présente, elle doit être propagée à l'appel @code{type.__new__} pour que la classe soit correctement initialisée. Ne pas le faire se traduit par un @ref{193,,RuntimeError} dans Python 3.8.

Quand vous utilisez la métaclasse par défaut @ref{d36,,type} ou toute autre métaclasse qui finit par appeler @code{type.__new__}, les étapes de personnalisation supplémentaires suivantes sont suivies après la création de l'objet classe :


@enumerate 

@item 
@code{type.__new__} récupère, dans l'espace de nommage de la classe, tous les descripteurs qui définissent une méthode @ref{c3c,,__set_name__()} ;

@item 
Toutes ces méthodes @code{__set_name__} sont appelées avec la classe en cours de définition et le nom assigné à chaque descripteur ;

@item 
La méthode automatique @ref{61c,,__init_subclass__()} est appelée sur le parent immédiat de la nouvelle classe en utilisant l'ordre de résolution des méthodes.
@end enumerate

Après la création de l'objet classe, il est passé aux décorateurs de la classe, y compris ceux inclus dans la définition de la classe (s'il y en a) et l'objet résultant est lié à l'espace de nommage local en tant que classe définie.

When a new class is created by @code{type.__new__}, the object provided as the
namespace parameter is copied to a new ordered mapping and the original
object is discarded. The new copy is wrapped in a read-only proxy, which
becomes the @ref{c4b,,__dict__} attribute of the class object.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3135

@item PEP 3135@footnote{https://peps.python.org/pep-3135/} — Nouvelle méthode super

Décrit la référence à la fermeture (`closure' en anglais) de la @code{__class__} implicite
@end table


@node Cas d'utilisations des métaclasses,,Création de l'objet classe,Personnalisation de la création de classes
@anchor{reference/datamodel uses-for-metaclasses}@anchor{1efd}
@subsubsection Cas d'utilisations des métaclasses


Les utilisations possibles des métaclasses sont immenses. Quelques pistes ont déjà été explorées comme l'énumération, la gestion des traces, le contrôle des interfaces, la délégation automatique, la création automatique de propriétés, les mandataires, les `frameworks' ainsi que le verrouillage ou la synchronisation automatique de ressources.

@node Personnalisation des instances et vérification des sous-classes,Émulation de types génériques,Personnalisation de la création de classes,Méthodes spéciales
@anchor{reference/datamodel customizing-instance-and-subclass-checks}@anchor{1efe}
@subsubsection Personnalisation des instances et vérification des sous-classes


Les méthodes suivantes sont utilisées pour surcharger le comportement par défaut des fonctions natives @ref{42b,,isinstance()} et @ref{7ab,,issubclass()}.

En particulier, la métaclasse @ref{f03,,abc.ABCMeta} implémente ces méthodes pour autoriser l'ajout de classes de base abstraites (ABC pour `Abstract Base Classes' en anglais) en tant que « classes de base virtuelles » pour toute classe ou type (y compris les types natifs).

@geindex __instancecheck__() (méthode type)
@anchor{reference/datamodel type __instancecheck__}@anchor{1eff}
@deffn {Méthode} type.__instancecheck__ (self, instance)

Renvoie @code{True} si `instance' doit être considérée comme une instance (directe ou indirecte) de `class'. Si elle est définie, elle est appelée pour implémenter @code{isinstance(instance, class)}.
@end deffn

@geindex __subclasscheck__() (méthode type)
@anchor{reference/datamodel type __subclasscheck__}@anchor{1f00}
@deffn {Méthode} type.__subclasscheck__ (self, subclass)

Renvoie @code{True} si `subclass' doit être considérée comme une sous-classe (directe ou indirecte) de `class'. Si elle est définie, appelée pour implémenter @code{issubclass(subclass, class)}.
@end deffn

Notez que ces méthodes sont recherchées dans le type (la métaclasse) d'une classe. Elles ne peuvent pas être définies en tant que méthodes de classe dans la classe réelle. C'est cohérent avec la recherche des méthodes spéciales qui sont appelées pour les instances, sauf qu'ici l'instance est elle-même une classe.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3119

@item PEP 3119@footnote{https://peps.python.org/pep-3119/} — Introduction aux classes de bases abstraites

Includes the specification for customizing @ref{42b,,isinstance()} and
@ref{7ab,,issubclass()} behavior through @ref{1eff,,__instancecheck__()} and
@ref{1f00,,__subclasscheck__()}, with motivation for this functionality
in the context of adding Abstract Base Classes (see the @ref{4,,abc}
module) to the language.
@end table


@node Émulation de types génériques,Émulation d'objets appelables,Personnalisation des instances et vérification des sous-classes,Méthodes spéciales
@anchor{reference/datamodel emulating-generic-types}@anchor{1f01}
@subsubsection Émulation de types génériques


Lors de l'utilisation d'@ref{441,,annotations de types}, il est souvent utile de `paramètrer' un @ref{422,,type générique} en se servant de la notation crochets de Python. Par exemple, l'annotation @code{list[int]} peut être utilisée pour signifier une @ref{5fc,,liste} dans laquelle tous les éléments sont de type @ref{254,,entiers}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} — Indications de types

Introduction à l'annotation de types en Python (document en anglais)

@item @ref{69d,,Types alias génériques}

Documentation pour les objets qui représentent des classes génériques paramétrées

@item @ref{1f02,,Génériques}, @ref{4b8,,Types génériques définis par l'utilisateur} et classe @ref{15a1,,typing.Generic (classe de base abstraite pour les types génériques)}

Documentation sur la manière d'implémenter des classes génériques qui peuvent être paramétrées à l'exécution et comprises par les vérificateurs statiques de types.
@end table


`Généralement', une classe ne peut être paramétrée que si elle définit une méthode spéciale de classe @code{__class_getitem__()}.

@geindex __class_getitem__() (méthode de la classe object)
@anchor{reference/datamodel object __class_getitem__}@anchor{725}
@deffn {Méthode} classmethod object.__class_getitem__ (cls, key)

Renvoie un objet représentant la spécialisation d'une classe générique en fonction des arguments types trouvés dans `key'.

Lorsqu'elle est définie dans une classe, @code{__class_getitem__()} est automatiquement une méthode de classe. Ainsi, il est superflu de la décorer avec @ref{165,,@@classmethod} lors de sa définition.
@end deffn

@menu
* Intention de __class_getitem__:: 
* __class_getitem__ contre __getitem__:: 

@end menu

@node Intention de __class_getitem__,__class_getitem__ contre __getitem__,,Émulation de types génériques
@anchor{reference/datamodel the-purpose-of-class-getitem}@anchor{1f03}
@subsubsection Intention de `__class_getitem__'


Le but de @ref{725,,__class_getitem__()} est de permettre la paramétrisation à l'exécution des classes génériques de la bibliothèque standard de façon à pouvoir appliquer plus facilement des @ref{1f04,,annotations de type} à ces classes.

Pour implémenter des classes génériques particularisées pouvant être paramétrées à l'exécution, et comprises par les vérificateurs statiques de type, vous pouvez soit hériter d'une classe de la bibliothèque standard qui implémente déjà @ref{725,,__class_getitem__()}, ou hériter de @ref{15a1,,typing.Generic}, qui a sa propre implémentation de @code{__class_getitem__()}.

Les implémentations particularisées de @ref{725,,__class_getitem__()} sur des classes définies ailleurs que la bibliothèque standard peuvent ne pas être comprises par des vérificateurs de types tiers tels que `mypy'. L'utilisation de @code{__class_getitem__()} pour tout autre objectif que l'annotation de type n'est pas conseillée.

@node __class_getitem__ contre __getitem__,,Intention de __class_getitem__,Émulation de types génériques
@anchor{reference/datamodel class-getitem-versus-getitem}@anchor{1f05}@anchor{reference/datamodel classgetitem-versus-getitem}@anchor{1f06}
@subsubsection `__class_getitem__' contre `__getitem__'


D'habitude, l'@ref{1f07,,indiçage} d'un objet en utilisant des crochets appelle la méthode @ref{280,,__getitem__()} de l'instance, définie dans la classe de l'objet. Cependant, si l'objet dont on cherche un indice est lui-même une classe, la méthode de classe @ref{725,,__class_getitem__()} peut être appelée à la place. @code{__class_getitem__()} doit renvoyer un objet @ref{69d,,GenericAlias} si elle est correctement définie.

Lorsqu'on lui présente l'@ref{1f08,,expression} @code{obj[x]}, l'interpréteur Python suit une sorte de processus suivant pour décider s'il faut appeler @ref{280,,__getitem__()} ou @ref{725,,__class_getitem__()} :

@example
from inspect import isclass

def subscribe(obj, x):
    """Return the result of the expression 'obj[x]'"""

    class_of_obj = type(obj)

    # If the class of obj defines __getitem__,
    # call class_of_obj.__getitem__(obj, x)
    if hasattr(class_of_obj, '__getitem__'):
        return class_of_obj.__getitem__(obj, x)

    # Else, if obj is a class and defines __class_getitem__,
    # call obj.__class_getitem__(x)
    elif isclass(obj) and hasattr(obj, '__class_getitem__'):
        return obj.__class_getitem__(x)

    # Else, raise an exception
    else:
        raise TypeError(
            f"'@{class_of_obj.__name__@}' object is not subscriptable"
        )
@end example

En Python, toutes les classes sont des instances d'autres classes. La classe d'une classe est appelée la @ref{1f09,,métaclasse} de la classe et la plupart des classes ont la classe @ref{d36,,type} comme métaclasse. @ref{d36,,type} ne définit pas @ref{280,,__getitem__()}, ce qui veut dire que des expressions telles que @code{list[int]}, @code{dict[str, float]} et @code{tuple[str, bytes]} aboutissent toutes à l'appel de @ref{725,,__class_getitem__()} :

@example
>>> # list has class "type" as its metaclass, like most classes:
>>> type(list)
<class 'type'>
>>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
True
>>> # "list[int]" calls "list.__class_getitem__(int)"
>>> list[int]
list[int]
>>> # list.__class_getitem__ returns a GenericAlias object:
>>> type(list[int])
<class 'types.GenericAlias'>
@end example

Cependant, si une classe a une métaclasse particularisée qui définit @ref{280,,__getitem__()}, l'indiçage de la classe peut conduire à un comportement différent. Un exemple peut être trouvé dans le module @ref{55,,enum} :

@example
>>> from enum import Enum
>>> class Menu(Enum):
...     """A breakfast menu"""
...     SPAM = 'spam'
...     BACON = 'bacon'
...
>>> # Enum classes have a custom metaclass:
>>> type(Menu)
<class 'enum.EnumMeta'>
>>> # EnumMeta defines __getitem__,
>>> # so __class_getitem__ is not called,
>>> # and the result is not a GenericAlias object:
>>> Menu['SPAM']
<Menu.SPAM: 'spam'>
>>> type(Menu['SPAM'])
<enum 'Menu'>
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 560

@item PEP 560@footnote{https://peps.python.org/pep-0560/} — Gestion de base pour les types modules et les types génériques

Introduction de @ref{725,,__class_getitem__()}, et présentation des cas où un @ref{1f07,,indiçage} conduit à l'appel de @code{__class_getitem__()} au lieu de @ref{280,,__getitem__()}
@end table


@node Émulation d'objets appelables,Émulation de types conteneurs,Émulation de types génériques,Méthodes spéciales
@anchor{reference/datamodel emulating-callable-objects}@anchor{1f0a}@anchor{reference/datamodel id15}@anchor{1f0b}
@subsubsection Émulation d'objets appelables


@geindex __call__() (méthode object)
@anchor{reference/datamodel object __call__}@anchor{543}
@deffn {Méthode} object.__call__ (self[, args...])

@geindex call;instance

Called when the instance is "called" as a function; if this method is defined,
@code{x(arg1, arg2, ...)} roughly translates to @code{type(x).__call__(x, arg1, ...)}.
The @ref{a7a,,object} class itself does not provide this method.
@end deffn

@node Émulation de types conteneurs,Émulation de types numériques,Émulation d'objets appelables,Méthodes spéciales
@anchor{reference/datamodel emulating-container-types}@anchor{1f0c}@anchor{reference/datamodel sequence-types}@anchor{1f0d}
@subsubsection Émulation de types conteneurs


The following methods can be defined to implement container objects. None of them
are provided by the @ref{a7a,,object} class itself. Containers usually are
@ref{4db,,sequences} (such as @ref{5fc,,lists} or
@ref{366,,tuples}) or @ref{1199,,mappings} (like
@ref{1f0e,,dictionaries}),
but can represent other containers as well.  The first set of methods is used
either to emulate a sequence or to emulate a mapping; the difference is that for
a sequence, the allowable keys should be the integers `k' for which @code{0 <= k <
N} where `N' is the length of the sequence, or @ref{453,,slice} objects, which define a
range of items.  It is also recommended that mappings provide the methods
@code{keys()}, @code{values()}, @code{items()}, @code{get()}, @code{clear()},
@code{setdefault()}, @code{pop()}, @code{popitem()}, @code{copy()}, and
@code{update()} behaving similar to those for Python's standard @ref{253,,dictionary}
objects.  The @ref{1e,,collections.abc} module provides a
@ref{1090,,MutableMapping}
@ref{1193,,abstract base class} to help create those methods from a base set of
@ref{280,,__getitem__()}, @ref{12a9,,__setitem__()},
@ref{12aa,,__delitem__()}, and @code{keys()}.
Mutable sequences should provide methods @code{append()}, @code{count()},
@code{index()}, @code{extend()}, @code{insert()}, @code{pop()}, @code{remove()},
@code{reverse()} and @code{sort()}, like Python standard @ref{5fc,,list}
objects. Finally,
sequence types should implement addition (meaning concatenation) and
multiplication (meaning repetition) by defining the methods
@ref{1f0f,,__add__()}, @ref{1f10,,__radd__()}, @ref{1f11,,__iadd__()},
@ref{1f12,,__mul__()}, @ref{1f13,,__rmul__()} and @ref{1f14,,__imul__()}
described below; they should not define other numerical
operators.  It is recommended that both mappings and sequences implement the
@ref{1ee0,,__contains__()} method to allow efficient use of the @code{in}
operator; for
mappings, @code{in} should search the mapping's keys; for sequences, it should
search through the values.  It is further recommended that both mappings and
sequences implement the @ref{1ede,,__iter__()} method to allow efficient iteration
through the container; for mappings, @code{__iter__()} should iterate
through the object's keys; for sequences, it should iterate through the values.

@geindex __len__() (méthode object)
@anchor{reference/datamodel object __len__}@anchor{1ee5}
@deffn {Méthode} object.__len__ (self)

@geindex built-in function;len
@geindex __bool__() (object method)

Called to implement the built-in function @ref{619,,len()}.  Should return the length
of the object, an integer @code{>=} 0.  Also, an object that doesn't define a
@ref{12b3,,__bool__()} method and whose @code{__len__()} method returns zero is
considered to be false in a Boolean context.

`Particularité de l'implémentation CPython :' In CPython, the length is required to be at most @ref{11a2,,sys.maxsize}.
If the length is larger than @code{sys.maxsize} some features (such as
@ref{619,,len()}) may raise @ref{86d,,OverflowError}.  To prevent raising
@code{OverflowError} by truth value testing, an object must define a
@ref{12b3,,__bool__()} method.
@end deffn

@geindex __length_hint__() (méthode object)
@anchor{reference/datamodel object __length_hint__}@anchor{ef6}
@deffn {Méthode} object.__length_hint__ (self)

Called to implement @ref{f58,,operator.length_hint()}. Should return an estimated
length for the object (which may be greater or less than the actual length).
The length must be an integer @code{>=} 0. The return value may also be
@ref{7bc,,NotImplemented}, which is treated the same as if the
@code{__length_hint__} method didn't exist at all. This method is purely an
optimization and is never required for correctness.


Ajouté dans la version 3.4.

@end deffn

@geindex object;slice

@cartouche
@quotation Note 
le découpage est effectué uniquement à l'aide des trois méthodes suivantes. Un appel comme

@example
a[1:2] = b
@end example

est traduit en

@example
a[slice(1, 2, None)] = b
@end example

et ainsi de suite. Les éléments manquants sont remplacés par @code{None}.
@end quotation
@end cartouche

@geindex __getitem__() (méthode object)
@anchor{reference/datamodel object __getitem__}@anchor{280}
@deffn {Méthode} object.__getitem__ (self, key)

Called to implement evaluation of @code{self[key]}. For @ref{4db,,sequence} types,
the accepted keys should be integers. Optionally, they may support
@ref{453,,slice} objects as well.  Negative index support is also optional.
If `key' is
of an inappropriate type, @ref{522,,TypeError} may be raised; if `key' is a value
outside the set of indexes for the sequence (after any special
interpretation of negative values), @ref{14eb,,IndexError} should be raised. For
@ref{1199,,mapping} types, if `key' is missing (not in the container),
@ref{33a,,KeyError} should be raised.

@cartouche
@quotation Note 
@ref{2e6,,for} s'attend à ce qu'une @ref{14eb,,IndexError} soit levée en cas d'indice illégal afin de détecter correctement la fin de la séquence.
@end quotation
@end cartouche

@cartouche
@quotation Note 
quand on vous @ref{1f07,,spécifiez un indice} pour une `classe', la méthode de classe spéciale @ref{725,,__class_getitem__()} peut être appelée au lieu de @code{__getitem__()}. Reportez-vous à @ref{1f06,,__class_getitem__ contre __getitem__} pour plus de détails.
@end quotation
@end cartouche
@end deffn

@geindex __setitem__() (méthode object)
@anchor{reference/datamodel object __setitem__}@anchor{12a9}
@deffn {Méthode} object.__setitem__ (self, key, value)

Appelée pour implémenter l'assignation à @code{self[key]}. La même note que pour @ref{280,,__getitem__()} s'applique. Elle ne doit être implémentée que pour les tableaux de correspondances qui autorisent les modifications de valeurs des clés, ceux pour lesquels on peut ajouter de nouvelles clés ou, pour les séquences, celles dont les éléments peuvent être remplacés. Les mêmes exceptions que pour la méthode @ref{280,,__getitem__()} doivent être levées en cas de mauvaises valeurs de clés.
@end deffn

@geindex __delitem__() (méthode object)
@anchor{reference/datamodel object __delitem__}@anchor{12aa}
@deffn {Méthode} object.__delitem__ (self, key)

Appelée pour implémenter la suppression de @code{self[key]}. La même note que pour @ref{280,,__getitem__()} s'applique. Elle ne doit être implémentée que pour les tableaux de correspondances qui autorisent les suppressions de clés ou pour les séquences dont les éléments peuvent être supprimés de la séquence. Les mêmes exceptions que pour la méthode @ref{280,,__getitem__()} doivent être levées en cas de mauvaises valeurs de clés.
@end deffn

@geindex __missing__() (méthode object)
@anchor{reference/datamodel object __missing__}@anchor{1f15}
@deffn {Méthode} object.__missing__ (self, key)

Appelée par @ref{253,,dict}.@ref{280,,__getitem__()} pour implémenter @code{self[key]} dans les sous-classes de dictionnaires lorsque la clé n'est pas dans le dictionnaire.
@end deffn

@geindex __iter__() (méthode object)
@anchor{reference/datamodel object __iter__}@anchor{1ede}
@deffn {Méthode} object.__iter__ (self)

Cette méthode est appelée quand un @ref{1aa,,itérateur} est requis pour un conteneur. Cette méthode doit renvoyer un nouvel objet itérateur qui peut itérer sur tous les objets du conteneur. Pour les tableaux de correspondances, elle doit itérer sur les clés du conteneur.
@end deffn

@geindex __reversed__() (méthode object)
@anchor{reference/datamodel object __reversed__}@anchor{1edf}
@deffn {Méthode} object.__reversed__ (self)

Appelée (si elle existe) par la fonction native @ref{850,,reversed()} pour implémenter l'itération en sens inverse. Elle doit renvoyer un nouvel objet itérateur qui itère sur tous les objets du conteneur en sens inverse.

Si la méthode @ref{1edf,,__reversed__()} n'est pas fournie, la fonction native @ref{850,,reversed()} se replie sur le protocole de séquence (@ref{1ee5,,__len__()} et @ref{280,,__getitem__()}). Les objets qui connaissent le protocole de séquence ne doivent fournir @ref{1edf,,__reversed__()} que si l'implémentation qu'ils proposent est plus efficace que celle de @ref{850,,reversed()}.
@end deffn

Les opérateurs de tests d'appartenance (@ref{2e8,,in} et @ref{61a,,not in}) sont normalement implémentés comme des itérations sur un conteneur. Cependant, les objets conteneurs peuvent fournir les méthodes spéciales suivantes avec une implémentation plus efficace, qui ne requièrent d'ailleurs pas que l'objet soit itérable.

@geindex __contains__() (méthode object)
@anchor{reference/datamodel object __contains__}@anchor{1ee0}
@deffn {Méthode} object.__contains__ (self, item)

Appelée pour implémenter les opérateurs de test d'appartenance. Elle doit renvoyer @code{True} si `item' est dans `self' et @code{False} sinon. Pour les tableaux de correspondances, seules les clés sont considérées (pas les valeurs des paires clés-valeurs).

Pour les objets qui ne définissent pas @ref{1ee0,,__contains__()}, les tests d'appartenance essaient d'abord d'itérer avec @ref{1ede,,__iter__()} puis avec le vieux protocole d'itération sur les séquences `via' @ref{280,,__getitem__()}, reportez-vous à @ref{1f16,,cette section dans la référence du langage}.
@end deffn

@node Émulation de types numériques,Gestionnaire de contexte With,Émulation de types conteneurs,Méthodes spéciales
@anchor{reference/datamodel emulating-numeric-types}@anchor{1f17}@anchor{reference/datamodel numeric-types}@anchor{1f18}
@subsubsection Émulation de types numériques


Les méthodes suivantes peuvent être définies pour émuler des objets numériques. Les méthodes correspondant à des opérations qui ne sont pas autorisées pour la catégorie de nombres considérée (par exemple, les opérations bit à bit pour les nombres qui ne sont pas entiers) doivent être laissées indéfinies.

@geindex __add__() (méthode object)
@geindex __sub__() (méthode object)
@geindex __mul__() (méthode object)
@geindex __matmul__() (méthode object)
@geindex __truediv__() (méthode object)
@geindex __floordiv__() (méthode object)
@geindex __mod__() (méthode object)
@geindex __divmod__() (méthode object)
@geindex __pow__() (méthode object)
@geindex __lshift__() (méthode object)
@geindex __rshift__() (méthode object)
@geindex __and__() (méthode object)
@geindex __xor__() (méthode object)
@geindex __or__() (méthode object)
@anchor{reference/datamodel object __add__}@anchor{1f0f}
@deffn {Méthode} object.__add__ (self, other)
@anchor{reference/datamodel object __sub__}@anchor{1f19}
@deffnx {Méthode} object.__sub__ (self, other)
@anchor{reference/datamodel object __mul__}@anchor{1f12}
@deffnx {Méthode} object.__mul__ (self, other)
@anchor{reference/datamodel object __matmul__}@anchor{1f1a}
@deffnx {Méthode} object.__matmul__ (self, other)
@anchor{reference/datamodel object __truediv__}@anchor{14a9}
@deffnx {Méthode} object.__truediv__ (self, other)
@anchor{reference/datamodel object __floordiv__}@anchor{14aa}
@deffnx {Méthode} object.__floordiv__ (self, other)
@anchor{reference/datamodel object __mod__}@anchor{1f1b}
@deffnx {Méthode} object.__mod__ (self, other)
@anchor{reference/datamodel object __divmod__}@anchor{1f1c}
@deffnx {Méthode} object.__divmod__ (self, other)
@anchor{reference/datamodel object __pow__}@anchor{7bd}
@deffnx {Méthode} object.__pow__ (self, other[, modulo])
@anchor{reference/datamodel object __lshift__}@anchor{1f1d}
@deffnx {Méthode} object.__lshift__ (self, other)
@anchor{reference/datamodel object __rshift__}@anchor{1f1e}
@deffnx {Méthode} object.__rshift__ (self, other)
@anchor{reference/datamodel object __and__}@anchor{1f1f}
@deffnx {Méthode} object.__and__ (self, other)
@anchor{reference/datamodel object __xor__}@anchor{1f20}
@deffnx {Méthode} object.__xor__ (self, other)
@anchor{reference/datamodel object __or__}@anchor{1f21}
@deffnx {Méthode} object.__or__ (self, other)

@geindex built-in function;divmod
@geindex built-in function;pow
@geindex built-in function;pow

Ces méthodes sont appelées pour implémenter les opérations arithmétiques binaires (@code{+}, @code{-}, @code{*}, @code{@@}, @code{/}, @code{//}, @code{%}, @ref{98f,,divmod()}, @ref{9c0,,pow()}, @code{**}, @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|}). Par exemple, pour évaluer l'expression @code{x + y}, où `x' est une instance d'une classe qui possède une méthode @ref{1f0f,,__add__()}, @code{type(x).__add__(x, y)} est appelée. La méthode @ref{1f1c,,__divmod__()} doit être l'équivalent d'appeler @ref{14aa,,__floordiv__()} et @ref{1f1b,,__mod__()} ; elle ne doit pas être reliée à @ref{14a9,,__truediv__()}. Notez que @ref{7bd,,__pow__()} doit être définie de manière à accepter un troisième argument optionnel si la version ternaire de la fonction native @ref{9c0,,pow()} est autorisée.

If one of those methods does not support the operation with the supplied
arguments, it should return @ref{7bc,,NotImplemented}.
@end deffn

@geindex __radd__() (méthode object)
@geindex __rsub__() (méthode object)
@geindex __rmul__() (méthode object)
@geindex __rmatmul__() (méthode object)
@geindex __rtruediv__() (méthode object)
@geindex __rfloordiv__() (méthode object)
@geindex __rmod__() (méthode object)
@geindex __rdivmod__() (méthode object)
@geindex __rpow__() (méthode object)
@geindex __rlshift__() (méthode object)
@geindex __rrshift__() (méthode object)
@geindex __rand__() (méthode object)
@geindex __rxor__() (méthode object)
@geindex __ror__() (méthode object)
@anchor{reference/datamodel object __radd__}@anchor{1f10}
@deffn {Méthode} object.__radd__ (self, other)
@anchor{reference/datamodel object __rsub__}@anchor{1f22}
@deffnx {Méthode} object.__rsub__ (self, other)
@anchor{reference/datamodel object __rmul__}@anchor{1f13}
@deffnx {Méthode} object.__rmul__ (self, other)
@anchor{reference/datamodel object __rmatmul__}@anchor{1f23}
@deffnx {Méthode} object.__rmatmul__ (self, other)
@anchor{reference/datamodel object __rtruediv__}@anchor{1f24}
@deffnx {Méthode} object.__rtruediv__ (self, other)
@anchor{reference/datamodel object __rfloordiv__}@anchor{1f25}
@deffnx {Méthode} object.__rfloordiv__ (self, other)
@anchor{reference/datamodel object __rmod__}@anchor{1f26}
@deffnx {Méthode} object.__rmod__ (self, other)
@anchor{reference/datamodel object __rdivmod__}@anchor{1f27}
@deffnx {Méthode} object.__rdivmod__ (self, other)
@anchor{reference/datamodel object __rpow__}@anchor{7be}
@deffnx {Méthode} object.__rpow__ (self, other[, modulo])
@anchor{reference/datamodel object __rlshift__}@anchor{1f28}
@deffnx {Méthode} object.__rlshift__ (self, other)
@anchor{reference/datamodel object __rrshift__}@anchor{1f29}
@deffnx {Méthode} object.__rrshift__ (self, other)
@anchor{reference/datamodel object __rand__}@anchor{1f2a}
@deffnx {Méthode} object.__rand__ (self, other)
@anchor{reference/datamodel object __rxor__}@anchor{1f2b}
@deffnx {Méthode} object.__rxor__ (self, other)
@anchor{reference/datamodel object __ror__}@anchor{1f2c}
@deffnx {Méthode} object.__ror__ (self, other)

@geindex built-in function;divmod
@geindex built-in function;pow

These methods are called to implement the binary arithmetic operations
(@code{+}, @code{-}, @code{*}, @code{@@}, @code{/}, @code{//}, @code{%}, @ref{98f,,divmod()},
@ref{9c0,,pow()}, @code{**}, @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|}) with reflected
(swapped) operands.  These functions are only called if the left operand does
not support the corresponding operation @footnote{
"Does not support" here means that the class has no such method, or
the method returns @ref{7bc,,NotImplemented}.  Do not set the method to
@code{None} if you want to force fallback to the right operand's reflected
method—that will instead have the opposite effect of explicitly
`blocking' such fallback.
} and the operands are of different
types. @footnote{
Pour des opérandes de même type, on considère que si la méthode originelle (telle que @ref{1f0f,,__add__()}) échoue, alors l'opération en tant que telle n'est pas autorisée et donc la méthode symétrique n'est pas appelée.
} For instance, to evaluate the expression @code{x - y}, where `y' is
an instance of a class that has an @ref{1f22,,__rsub__()} method,
@code{type(y).__rsub__(y, x)} is called if @code{type(x).__sub__(x, y)} returns
@ref{7bc,,NotImplemented}.

@geindex built-in function;pow

Notez que la fonction ternaire @ref{9c0,,pow()} n'essaie pas d'appeler @ref{7be,,__rpow__()} (les règles de coercition seraient trop compliquées).

@cartouche
@quotation Note 
si le type de l'opérande de droite est une sous-classe du type de l'opérande de gauche et que cette sous-classe fournit une implémentation différente de la méthode symétrique pour l'opération, cette méthode est appelée avant la méthode originelle de l'opérande gauche. Ce comportement permet à des sous-classes de surcharger les opérations de leurs ancêtres.
@end quotation
@end cartouche
@end deffn

@geindex __iadd__() (méthode object)
@geindex __isub__() (méthode object)
@geindex __imul__() (méthode object)
@geindex __imatmul__() (méthode object)
@geindex __itruediv__() (méthode object)
@geindex __ifloordiv__() (méthode object)
@geindex __imod__() (méthode object)
@geindex __ipow__() (méthode object)
@geindex __ilshift__() (méthode object)
@geindex __irshift__() (méthode object)
@geindex __iand__() (méthode object)
@geindex __ixor__() (méthode object)
@geindex __ior__() (méthode object)
@anchor{reference/datamodel object __iadd__}@anchor{1f11}
@deffn {Méthode} object.__iadd__ (self, other)
@anchor{reference/datamodel object __isub__}@anchor{1f2d}
@deffnx {Méthode} object.__isub__ (self, other)
@anchor{reference/datamodel object __imul__}@anchor{1f14}
@deffnx {Méthode} object.__imul__ (self, other)
@anchor{reference/datamodel object __imatmul__}@anchor{1f2e}
@deffnx {Méthode} object.__imatmul__ (self, other)
@anchor{reference/datamodel object __itruediv__}@anchor{1f2f}
@deffnx {Méthode} object.__itruediv__ (self, other)
@anchor{reference/datamodel object __ifloordiv__}@anchor{1f30}
@deffnx {Méthode} object.__ifloordiv__ (self, other)
@anchor{reference/datamodel object __imod__}@anchor{1f31}
@deffnx {Méthode} object.__imod__ (self, other)
@anchor{reference/datamodel object __ipow__}@anchor{7bb}
@deffnx {Méthode} object.__ipow__ (self, other[, modulo])
@anchor{reference/datamodel object __ilshift__}@anchor{1f32}
@deffnx {Méthode} object.__ilshift__ (self, other)
@anchor{reference/datamodel object __irshift__}@anchor{1f33}
@deffnx {Méthode} object.__irshift__ (self, other)
@anchor{reference/datamodel object __iand__}@anchor{1f34}
@deffnx {Méthode} object.__iand__ (self, other)
@anchor{reference/datamodel object __ixor__}@anchor{1f35}
@deffnx {Méthode} object.__ixor__ (self, other)
@anchor{reference/datamodel object __ior__}@anchor{1f36}
@deffnx {Méthode} object.__ior__ (self, other)

These methods are called to implement the augmented arithmetic assignments
(@code{+=}, @code{-=}, @code{*=}, @code{@@=}, @code{/=}, @code{//=}, @code{%=}, @code{**=}, @code{<<=},
@code{>>=}, @code{&=}, @code{^=}, @code{|=}).  These methods should attempt to do the
operation in-place (modifying `self') and return the result (which could be,
but does not have to be, `self').  If a specific method is not defined, or if
that method returns @ref{7bc,,NotImplemented}, the
augmented assignment falls back to the normal methods.  For instance, if `x'
is an instance of a class with an @ref{1f11,,__iadd__()} method, @code{x += y} is
equivalent to @code{x = x.__iadd__(y)} . If @ref{1f11,,__iadd__()} does not exist, or if @code{x.__iadd__(y)}
returns @code{NotImplemented}, @code{x.__add__(y)} and
@code{y.__radd__(x)} are considered, as with the evaluation of @code{x + y}. In
certain situations, augmented assignment can result in unexpected errors (see
@ref{1f37,,Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?}), but this behavior is in fact
part of the data model.
@end deffn

@geindex __neg__() (méthode object)
@geindex __pos__() (méthode object)
@geindex __abs__() (méthode object)
@geindex __invert__() (méthode object)
@anchor{reference/datamodel object __neg__}@anchor{1f38}
@deffn {Méthode} object.__neg__ (self)
@anchor{reference/datamodel object __pos__}@anchor{1f39}
@deffnx {Méthode} object.__pos__ (self)
@anchor{reference/datamodel object __abs__}@anchor{1f3a}
@deffnx {Méthode} object.__abs__ (self)
@anchor{reference/datamodel object __invert__}@anchor{1f3b}
@deffnx {Méthode} object.__invert__ (self)

@geindex built-in function;abs

Appelées pour implémenter les opérations arithmétiques unaires (@code{-}, @code{+}, @ref{1c32,,abs()} et @code{~}).
@end deffn

@geindex __complex__() (méthode object)
@geindex __int__() (méthode object)
@geindex __float__() (méthode object)
@anchor{reference/datamodel object __complex__}@anchor{5d1}
@deffn {Méthode} object.__complex__ (self)
@anchor{reference/datamodel object __int__}@anchor{706}
@deffnx {Méthode} object.__int__ (self)
@anchor{reference/datamodel object __float__}@anchor{9ba}
@deffnx {Méthode} object.__float__ (self)

@geindex built-in function;complex
@geindex built-in function;int
@geindex built-in function;float

Appelées pour implémenter les fonctions natives @ref{2ec,,complex()}, @ref{254,,int()} et @ref{2eb,,float()}. Elles doivent renvoyer une valeur du type approprié.
@end deffn

@geindex __index__() (méthode object)
@anchor{reference/datamodel object __index__}@anchor{707}
@deffn {Méthode} object.__index__ (self)

Appelée pour implémenter @ref{189c,,operator.index()} et lorsque Python a besoin de convertir sans perte un objet numérique en objet entier (pour un découpage ou dans les fonctions natives @ref{1286,,bin()}, @ref{12ad,,hex()} et @ref{12ac,,oct()}). La présence de cette méthode indique que l'objet numérique est un type entier. Elle doit renvoyer un entier.

Si @ref{706,,__int__()}, @ref{9ba,,__float__()} et @ref{5d1,,__complex__()} ne sont pas définies, alors les fonctions natives @ref{254,,int()}, @ref{2eb,,float()} et @ref{2ec,,complex()} redirigent par défaut vers @ref{707,,__index__()}.
@end deffn

@geindex __round__() (méthode object)
@geindex __trunc__() (méthode object)
@geindex __floor__() (méthode object)
@geindex __ceil__() (méthode object)
@anchor{reference/datamodel object __round__}@anchor{1f3c}
@deffn {Méthode} object.__round__ (self[, ndigits])
@anchor{reference/datamodel object __trunc__}@anchor{705}
@deffnx {Méthode} object.__trunc__ (self)
@anchor{reference/datamodel object __floor__}@anchor{1f3d}
@deffnx {Méthode} object.__floor__ (self)
@anchor{reference/datamodel object __ceil__}@anchor{1f3e}
@deffnx {Méthode} object.__ceil__ (self)

@geindex built-in function;round

Appelées pour implémenter la fonction native @ref{12b8,,round()} et les fonctions du module @ref{8d,,math} @ref{137a,,trunc()}, @ref{1378,,floor()} et @ref{1379,,ceil()}. À moins que `ndigits' ne soit passé à @code{__round__()}, toutes ces méthodes doivent renvoyer la valeur de l'objet tronquée pour donner un @ref{1f3f,,Integral} (typiquement un @ref{254,,int}).

La fonction native @ref{254,,int()} se replie sur @ref{705,,__trunc__()} dans le cas où ni @ref{706,,__int__()} ni @ref{707,,__index__()} ne sont définies.


Modifié dans la version 3.11: la délégation de @ref{254,,int()} vers @code{__trunc__()} est obsolète.

@end deffn

@node Gestionnaire de contexte With,Arguments positionnels dans le filtrage par motif sur les classes,Émulation de types numériques,Méthodes spéciales
@anchor{reference/datamodel context-managers}@anchor{1f40}@anchor{reference/datamodel with-statement-context-managers}@anchor{1f41}
@subsubsection Gestionnaire de contexte With


Un `gestionnaire de contexte' est un objet qui met en place un contexte prédéfini au moment de l'exécution de l'instruction @ref{5bc,,with}. Le gestionnaire de contexte gère l'entrée et la sortie de ce contexte d'exécution pour tout un bloc de code. Les gestionnaires de contextes sont normalement invoqués en utilisant une instruction @code{with} (décrite dans la section @ref{5bc,,L'instruction with}), mais ils peuvent aussi être directement invoqués par leurs méthodes.

@geindex statement;with
@geindex context manager

Les utilisations classiques des gestionnaires de contexte sont la sauvegarde et la restauration d'états divers, le verrouillage et le déverrouillage de ressources, la fermeture de fichiers ouverts, etc.

For more information on context managers, see @ref{1f42,,Le type gestionnaire de contexte}.
The @ref{a7a,,object} class itself does not provide the context manager methods.

@geindex __enter__() (méthode object)
@anchor{reference/datamodel object __enter__}@anchor{5b2}
@deffn {Méthode} object.__enter__ (self)

Entre dans le contexte d'exécution relatif à cet objet. L'instruction @ref{5bc,,with} lie la valeur de retour de cette méthode à une (ou plusieurs) cible spécifiée par la clause @code{as} de l'instruction, si elle est spécifiée.
@end deffn

@geindex __exit__() (méthode object)
@anchor{reference/datamodel object __exit__}@anchor{12de}
@deffn {Méthode} object.__exit__ (self, exc_type, exc_value, traceback)

Sort du contexte d'exécution relatif à cet objet. Les paramètres décrivent l'exception qui a causé la sortie du contexte. Si l'on sort du contexte sans exception, les trois arguments sont à @ref{660,,None}.

Si une exception est indiquée et que la méthode souhaite supprimer l'exception (c'est-à-dire qu'elle ne veut pas que l'exception soit propagée), elle doit renvoyer @code{True}. Sinon, l'exception est traitée normalement à la sortie de cette méthode.

Note that @ref{12de,,__exit__()} methods should not reraise the passed-in exception;
this is the caller's responsibility.
@end deffn


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} — L'instruction @code{with}

La spécification, les motivations et des exemples de l'instruction @ref{5bc,,with} en Python.
@end table


@node Arguments positionnels dans le filtrage par motif sur les classes,Emulating buffer types,Gestionnaire de contexte With,Méthodes spéciales
@anchor{reference/datamodel class-pattern-matching}@anchor{1f43}@anchor{reference/datamodel customizing-positional-arguments-in-class-pattern-matching}@anchor{1f44}
@subsubsection Arguments positionnels dans le filtrage par motif sur les classes


When using a class name in a pattern, positional arguments in the pattern are not
allowed by default, i.e. @code{case MyClass(x, y)} is typically invalid without special
support in @code{MyClass}. To be able to use that kind of pattern, the class needs to
define a `__match_args__' attribute.

@geindex object.__match_args__ (variable de base)
@anchor{reference/datamodel object __match_args__}@anchor{184d}
@deffn {Données} object.__match_args__

Cet attribut de la classe est un `n'-uplet de chaînes. Lorsque la classe apparaît dans un filtre avec des arguments positionnels, ils sont convertis en arguments nommés avec les noms du `n'-uplet, dans l'ordre. Si l'attribut n'est pas défini, tout se passe comme si sa valeur était le `n'-uplet vide @code{()}.
@end deffn

Ainsi, si @code{UneClasse.__match_args__} est mis à @code{("gauche", "milieu", "droite")}, le filtre @code{case UneClasse(x, y)} est équivalent à @code{case UneClasse(gauche=x, milieu=y)}. Le filtre doit comporter au maximum autant d'arguments positionnels que la longueur @code{__match_args__}. Dans le cas contraire, le filtrage lève l'exception @ref{522,,TypeError}.


Ajouté dans la version 3.10.



@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 634

@item PEP 634@footnote{https://peps.python.org/pep-0634/} — Filtrage par motif structurel

Spécification de l'instruction @code{match}.
@end table


@node Emulating buffer types,Recherche des méthodes spéciales,Arguments positionnels dans le filtrage par motif sur les classes,Méthodes spéciales
@anchor{reference/datamodel emulating-buffer-types}@anchor{1f45}@anchor{reference/datamodel python-buffer-protocol}@anchor{1f46}
@subsubsection Emulating buffer types


The @ref{38e,,buffer protocol} provides a way for Python
objects to expose efficient access to a low-level memory array. This protocol
is implemented by builtin types such as @ref{1bd,,bytes} and @ref{452,,memoryview},
and third-party libraries may define additional buffer types.

While buffer types are usually implemented in C, it is also possible to
implement the protocol in Python.

@geindex __buffer__() (méthode object)
@anchor{reference/datamodel object __buffer__}@anchor{448}
@deffn {Méthode} object.__buffer__ (self, flags)

Called when a buffer is requested from `self' (for example, by the
@ref{452,,memoryview} constructor). The `flags' argument is an integer
representing the kind of buffer requested, affecting for example whether
the returned buffer is read-only or writable. @ref{449,,inspect.BufferFlags}
provides a convenient way to interpret the flags. The method must return
a @ref{452,,memoryview} object.
@end deffn

@geindex __release_buffer__() (méthode object)
@anchor{reference/datamodel object __release_buffer__}@anchor{167c}
@deffn {Méthode} object.__release_buffer__ (self, buffer)

Called when a buffer is no longer needed. The `buffer' argument is a
@ref{452,,memoryview} object that was previously returned by
@ref{448,,__buffer__()}. The method must release any resources associated
with the buffer. This method should return @code{None}.
Buffer objects that do not need to perform any cleanup are not required
to implement this method.
@end deffn


Ajouté dans la version 3.12.



@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 688

@item PEP 688@footnote{https://peps.python.org/pep-0688/} - Making the buffer protocol accessible in Python

Introduces the Python @code{__buffer__} and @code{__release_buffer__} methods.

@item @ref{2c1,,collections.abc.Buffer}

ABC for buffer types.
@end table


@node Recherche des méthodes spéciales,,Emulating buffer types,Méthodes spéciales
@anchor{reference/datamodel special-lookup}@anchor{1ee8}@anchor{reference/datamodel special-method-lookup}@anchor{1f47}
@subsubsection Recherche des méthodes spéciales


Pour les classes définies par le développeur, l'invocation implicite de méthodes spéciales n'est garantie que si ces méthodes sont définies par le type d'objet, pas dans le dictionnaire de l'objet instance. Ce comportement explique pourquoi le code suivant lève une exception :

@example
>>> class C:
...     pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()
@end example

La raison de ce comportement vient de certaines méthodes spéciales telles que @ref{ae9,,__hash__()} et @ref{607,,__repr__()} qui sont implémentées par tous les objets, y compris les objets types. Si la recherche effectuée par ces méthodes utilisait le processus normal de recherche, elles ne fonctionneraient pas si on les appelait sur l'objet type lui-même :

@example
>>> 1 .__hash__() == hash(1)
True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an argument
@end example

Essayer d'invoquer une méthode non liée d'une classe de cette manière est parfois appelé « confusion de métaclasse » et se contourne en shuntant l'instance lors de la recherche des méthodes spéciales :

@example
>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True
@end example

En plus de shunter les attributs des instances pour fonctionner correctement, la recherche des méthodes spéciales implicites shunte aussi la méthode @ref{bc0,,__getattribute__()} même dans la métaclasse de l'objet :

@example
>>> class Meta(type):
...     def __getattribute__(*args):
...         print("Metaclass getattribute invoked")
...         return type.__getattribute__(*args)
...
>>> class C(object, metaclass=Meta):
...     def __len__(self):
...         return 10
...     def __getattribute__(*args):
...         print("Class getattribute invoked")
...         return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__()                 # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c)          # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c)                      # Implicit lookup
10
@end example

En shuntant le mécanisme de @ref{bc0,,__getattribute__()} de cette façon, cela permet d'optimiser la vitesse de l'interpréteur moyennant une certaine manœuvre dans la gestion des méthodes spéciales (la méthode spéciale `doit' être définie sur l'objet classe lui-même afin d'être invoquée de manière cohérente par l'interpréteur).

@geindex coroutine

@node Coroutines,,Méthodes spéciales,Modèle de données
@anchor{reference/datamodel coroutines}@anchor{1f48}
@subsection Coroutines


@menu
* Objets attendables (awaitable): Objets attendables awaitable. 
* Objets coroutines:: 
* Itérateurs asynchrones:: 
* Gestionnaires de contexte asynchrones:: 

@end menu

@node Objets attendables awaitable,Objets coroutines,,Coroutines
@anchor{reference/datamodel awaitable-objects}@anchor{1f49}
@subsubsection Objets `attendables' (`awaitable')


Un objet @ref{1ab,,awaitable} implémente généralement une méthode @ref{1f4a,,__await__()}. Les objets @ref{47b,,coroutine} renvoyés par les fonctions @ref{5bb,,async def} sont des `attendables' (`awaitable').

@cartouche
@quotation Note 
les objets @ref{bcc,,itérateur de générateur} renvoyés par les générateurs décorés par @ref{e73,,types.coroutine()} sont aussi des `attendables' (`awaitable'), mais ils n'implémentent pas @ref{1f4a,,__await__()}.
@end quotation
@end cartouche

@geindex __await__() (méthode object)
@anchor{reference/datamodel object __await__}@anchor{1f4a}
@deffn {Méthode} object.__await__ (self)

Must return an @ref{1aa,,iterator}.  Should be used to implement
@ref{1ab,,awaitable} objects.  For instance, @ref{bbb,,asyncio.Future} implements
this method to be compatible with the @ref{1b7,,await} expression.
The @ref{a7a,,object} class itself is not awaitable and does not provide
this method.

@cartouche
@quotation Note 
The language doesn't place any restriction on the type or value of the
objects yielded by the iterator returned by @code{__await__}, as this is
specific to the implementation of the asynchronous execution framework
(e.g. @ref{a,,asyncio}) that will be managing the @ref{1ab,,awaitable} object.
@end quotation
@end cartouche
@end deffn


Ajouté dans la version 3.5.



@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} pour les informations relatives aux objets `attendables' (`awaitable').


@node Objets coroutines,Itérateurs asynchrones,Objets attendables awaitable,Coroutines
@anchor{reference/datamodel coroutine-objects}@anchor{1e8d}@anchor{reference/datamodel id18}@anchor{1f4b}
@subsubsection Objets coroutines


Les objets @ref{47b,,coroutine} sont des objets @ref{1ab,,awaitable}. L'exécution d'une coroutine peut être contrôlée en appelant @ref{1f4a,,__await__()} et en itérant sur le résultat. Quand la coroutine a fini de s'exécuter et termine, l'itérateur lève @ref{be8,,StopIteration} et l'attribut @ref{1f4c,,value} de l'exception contient la valeur de retour. Si la coroutine lève une exception, elle est propagée par l'itérateur. Les coroutines ne doivent pas lever directement des exceptions @ref{be8,,StopIteration} non gérées.

Les coroutines disposent aussi des méthodes listées ci-dessous, analogues à celles des générateurs (voir @ref{1f4d,,Méthodes des générateurs-itérateurs}). Cependant, au contraire des générateurs, vous ne pouvez pas itérer directement sur des coroutines.


Modifié dans la version 3.5.2: utiliser `await' plus d'une fois sur une coroutine lève une @ref{193,,RuntimeError}.


@geindex send() (méthode coroutine)
@anchor{reference/datamodel coroutine send}@anchor{1f4e}
@deffn {Méthode} coroutine.send (value)

Starts or resumes execution of the coroutine.  If `value' is @code{None},
this is equivalent to advancing the iterator returned by
@ref{1f4a,,__await__()}.  If `value' is not @code{None}, this method delegates
to the @ref{1f4f,,send()} method of the iterator that caused
the coroutine to suspend.  The result (return value,
@ref{be8,,StopIteration}, or other exception) is the same as when
iterating over the @code{__await__()} return value, described above.
@end deffn

@geindex throw() (méthode coroutine)
@anchor{reference/datamodel coroutine throw}@anchor{4e1}
@deffn {Méthode} coroutine.throw (value)

@deffnx {Méthode} coroutine.throw (type[, value[, traceback]])

Lève l'exception spécifiée dans la coroutine. Cette méthode délègue à la méthode @ref{4e2,,throw()} de l'itérateur qui a causé la suspension de la coroutine, s'il possède une telle méthode. Sinon, l'exception est levée au point de suspension. Le résultat (valeur de retour, @ref{be8,,StopIteration} ou une autre exception) est le même que lorsque vous itérez sur la valeur de retour de @ref{1f4a,,__await__()}, décrite ci-dessus. Si l'exception n'est pas gérée par la coroutine, elle est propagée à l'appelant.


Modifié dans la version 3.12: The second signature (type[, value[, traceback]]) is deprecated and
may be removed in a future version of Python.

@end deffn

@geindex close() (méthode coroutine)
@anchor{reference/datamodel coroutine close}@anchor{1f50}
@deffn {Méthode} coroutine.close ()

Demande à la coroutine de faire le ménage et de se terminer. Si la coroutine est suspendue, cette méthode délègue d'abord à la méthode @ref{167d,,close()} de l'itérateur qui a causé la suspension de la coroutine, s'il possède une telle méthode. Ensuite, elle lève @ref{137e,,GeneratorExit} au point de suspension, ce qui fait le ménage dans la coroutine immédiatement. Enfin, la coroutine est marquée comme ayant terminé son exécution, même si elle n'a jamais démarré.

Les objets coroutines sont automatiquement fermés en utilisant le processus décrit au-dessus au moment où ils sont détruits.
@end deffn

@node Itérateurs asynchrones,Gestionnaires de contexte asynchrones,Objets coroutines,Coroutines
@anchor{reference/datamodel async-iterators}@anchor{d67}@anchor{reference/datamodel asynchronous-iterators}@anchor{1f51}
@subsubsection Itérateurs asynchrones


Un `itérateur asynchrone' peut appeler du code asynchrone dans sa méthode @code{__anext__}.

Les itérateurs asynchrones peuvent être utilisés dans des instructions @ref{a99,,async for}.

The @ref{a7a,,object} class itself does not provide these methods.

@geindex __aiter__() (méthode object)
@anchor{reference/datamodel object __aiter__}@anchor{be9}
@deffn {Méthode} object.__aiter__ (self)

Doit renvoyer un objet `itérateur asynchrone'.
@end deffn

@geindex __anext__() (méthode object)
@anchor{reference/datamodel object __anext__}@anchor{1e8f}
@deffn {Méthode} object.__anext__ (self)

Doit renvoyer un `attendable' (`awaitable') qui se traduit par la valeur suivante de l'itérateur. Doit lever une @ref{19bb,,StopAsyncIteration} quand l'itération est terminée.
@end deffn

Un exemple d'objet itérateur asynchrone :

@example
class Reader:
    async def readline(self):
        ...

    def __aiter__(self):
        return self

    async def __anext__(self):
        val = await self.readline()
        if val == b'@w{'}:
            raise StopAsyncIteration
        return val
@end example


Ajouté dans la version 3.5.



Modifié dans la version 3.7: avant Python 3.7, @ref{be9,,__aiter__()} pouvait renvoyer un `attendable' (`awaitable') qui se résolvait potentiellement en un @ref{1a9,,itérateur asynchrone}.

À partir de Python 3.7, @ref{be9,,__aiter__()} doit renvoyer un objet itérateur asynchrone. Renvoyer autre chose entraine une erreur @ref{522,,TypeError}.


@node Gestionnaires de contexte asynchrones,,Itérateurs asynchrones,Coroutines
@anchor{reference/datamodel async-context-managers}@anchor{5e6}@anchor{reference/datamodel asynchronous-context-managers}@anchor{1f52}
@subsubsection Gestionnaires de contexte asynchrones


Un `gestionnaire de contexte asynchrone' est un `gestionnaire de contexte' qui est capable de suspendre son exécution dans ses méthodes @code{__aenter__} et @code{__aexit__}.

Les gestionnaires de contexte asynchrones peuvent être utilisés dans des instructions @ref{5bf,,async with}.

The @ref{a7a,,object} class itself does not provide these methods.

@geindex __aenter__() (méthode object)
@anchor{reference/datamodel object __aenter__}@anchor{1f53}
@deffn {Méthode} object.__aenter__ (self)

Semantically similar to @ref{5b2,,__enter__()}, the only
difference being that it must return an `awaitable'.
@end deffn

@geindex __aexit__() (méthode object)
@anchor{reference/datamodel object __aexit__}@anchor{15b3}
@deffn {Méthode} object.__aexit__ (self, exc_type, exc_value, traceback)

Semantically similar to @ref{12de,,__exit__()}, the only
difference being that it must return an `awaitable'.
@end deffn

Un exemple de classe de gestionnaire de contexte asynchrone :

@example
class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')

    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')
@end example


Ajouté dans la version 3.5.


@node Modèle d'exécution,Le système d'importation,Modèle de données,La référence du langage Python
@anchor{reference/executionmodel doc}@anchor{1f54}@anchor{reference/executionmodel execmodel}@anchor{1f55}@anchor{reference/executionmodel execution-model}@anchor{1f56}
@section Modèle d'exécution


@geindex execution model
@geindex code;block

@menu
* Structure d'un programme:: 
* Noms et liaisons:: 
* Exceptions: Exceptions<2>. 

@end menu

@node Structure d'un programme,Noms et liaisons,,Modèle d'exécution
@anchor{reference/executionmodel prog-structure}@anchor{1f57}@anchor{reference/executionmodel structure-of-a-program}@anchor{1f58}
@subsection Structure d'un programme


@geindex block

Un programme Python est construit à partir de blocs de code. Un `bloc' est un morceau de texte de programme Python qui est exécuté en tant qu'unité. Les éléments suivants sont des blocs : un module, un corps de fonction et une définition de classe. Chaque commande écrite dans l'interpréteur interactif de Python est un bloc. Un fichier de script (un fichier donné en entrée standard à l'interpréteur ou spécifié en tant qu'argument de ligne de commande à l'interpréteur) est un bloc de code. Une commande de script (une commande spécifiée en ligne de commande à l'interpréteur avec l'option @ref{5ca,,-c}) est un bloc de code. Un module exécuté en tant que script principal (module @code{__main__}) depuis la ligne de commande en utilisant l'option @ref{5cb,,-m} est aussi un bloc de code. La chaîne passée en argument aux fonctions natives @ref{17e,,eval()} et @ref{17d,,exec()} est un bloc de code.

@geindex execution;frame

Un bloc de code est exécuté dans un `cadre d'exécution'. Un cadre contient des informations administratives (utilisées pour le débogage) et détermine où et comment l'exécution se poursuit après la fin de l'exécution du bloc de code.

@node Noms et liaisons,Exceptions<2>,Structure d'un programme,Modèle d'exécution
@anchor{reference/executionmodel naming}@anchor{1e7d}@anchor{reference/executionmodel naming-and-binding}@anchor{1f59}
@subsection Noms et liaisons


@geindex namespace
@geindex scope

@menu
* Liaisons des noms:: 
* Résolution des noms:: 
* Annotation scopes:: 
* Lazy evaluation:: 
* Noms natifs et restrictions d'exécution:: 
* Interaction avec les fonctionnalités dynamiques:: 

@end menu

@node Liaisons des noms,Résolution des noms,,Noms et liaisons
@anchor{reference/executionmodel bind-names}@anchor{1f5a}@anchor{reference/executionmodel binding-of-names}@anchor{1f5b}
@subsubsection Liaisons des noms


@geindex name
@geindex binding;name

Les `noms' sont des références aux objets. Ils sont créés lors des opérations de liaisons de noms (`name binding' en anglais).

@geindex from;import statement

Les noms sont liés `via' les constructions suivantes :


@itemize *

@item 
paramètres formels de fonctions,

@item 
définitions de classes,

@item 
définitions de fonctions,

@item 
expressions d'affectation,

@item 
@ref{1f5c,,cibles} qui sont des identifiants, lorsque c'est une affectation :


@itemize +

@item 
de l'entête d'une boucle @ref{2e6,,for},

@item 
after @code{as} in a @ref{5bc,,with} statement, @ref{189,,except}
clause, @ref{5a2,,except*} clause, or in the as-pattern in structural pattern matching,

@item 
dans un champ de recherche d'un filtrage par motifs
@end itemize

@item 
des instructions @ref{5cc,,import}.

@item 
@ref{421,,type} statements.

@item 
@ref{2b0,,type parameter lists}.
@end itemize

L'instruction @code{import} sous la forme @code{from ... import *} lie tous les noms définis dans le module importé, sauf ceux qui commencent par le caractère souligné. Cette écriture ne peut être utilisée qu'au niveau du module.

Une cible qui apparaît dans une instruction @ref{1734,,del} est aussi considérée comme une liaison à un nom dans ce cadre (bien que la sémantique véritable soit de délier le nom).

Chaque affectation ou instruction `import' a lieu dans un bloc défini par une définition de classe ou de fonction, ou au niveau du module (le bloc de code de plus haut niveau).

@geindex free;variable

If a name is bound in a block, it is a local variable of that block, unless
declared as @ref{1285,,nonlocal} or @ref{188,,global}.  If a name is bound at
the module level, it is a global variable.  (The variables of the module code
block are local and global.)  If a variable is used in a code block but not
defined there, it is a @ref{1f5d,,free variable}.

Chaque occurrence d'un nom dans un programme fait référence à la `liaison' de ce nom établie par les règles de résolution des noms suivantes.

@node Résolution des noms,Annotation scopes,Liaisons des noms,Noms et liaisons
@anchor{reference/executionmodel resolution-of-names}@anchor{1f5e}@anchor{reference/executionmodel resolve-names}@anchor{1f5f}
@subsubsection Résolution des noms


@geindex scope

La `portée' définit la visibilité d'un nom dans un bloc. Si une variable locale est définie dans un bloc, sa portée comprend ce bloc. Si la définition intervient dans le bloc d'une fonction, la portée s'étend à tous les blocs contenus dans celui qui comprend la définition, à moins qu'un bloc intérieur ne définisse une autre liaison pour ce nom.

@geindex environment

Quand un nom est utilisé dans un bloc de code, la résolution utilise la portée la plus petite. L'ensemble de toutes les portées visibles dans un bloc de code s'appelle `l'environnement' du bloc.

@geindex NameError (built-in exception)
@geindex UnboundLocalError

Quand un nom n'est trouvé nulle part, une exception @ref{428,,NameError} est levée. Si la portée courante est celle d'une fonction et que le nom fait référence à une variable locale qui n'a pas encore été liée au moment où le nom est utilisé, une exception @ref{14ec,,UnboundLocalError} est levée. @ref{14ec,,UnboundLocalError} est une sous-classe de @ref{428,,NameError}.

If a name binding operation occurs anywhere within a code block, all uses of the
name within the block are treated as references to the current block.  This can
lead to errors when a name is used within a block before it is bound.  This rule
is subtle.  Python lacks declarations and allows name binding operations to
occur anywhere within a code block.  The local variables of a code block can be
determined by scanning the entire text of the block for name binding operations.
See @ref{1f60,,the FAQ entry on UnboundLocalError}
for examples.

If the @ref{188,,global} statement occurs within a block, all uses of the names
specified in the statement refer to the bindings of those names in the top-level
namespace.  Names are resolved in the top-level namespace by searching the
global namespace, i.e. the namespace of the module containing the code block,
and the builtins namespace, the namespace of the module @ref{12,,builtins}.  The
global namespace is searched first.  If the names are not found there, the
builtins namespace is searched next. If the names are also not found in the
builtins namespace, new variables are created in the global namespace.
The global statement must precede all uses of the listed names.

L'instruction @ref{188,,global} a la même porte qu'une opération de liaison du même bloc. Si la portée englobante la plus petite pour une variable libre contient une instruction `global', la variable libre est considérée globale.

@c XXX say more about "nonlocal" semantics here

The @ref{1285,,nonlocal} statement causes corresponding names to refer
to previously bound variables in the nearest enclosing function scope.
@ref{18b,,SyntaxError} is raised at compile time if the given name does not
exist in any enclosing function scope. @ref{2b0,,Type parameters}
cannot be rebound with the @code{nonlocal} statement.

@geindex module;__main__

L'espace de nommage pour un module est créé automatiquement la première fois que le module est importé. Le module principal d'un script s'appelle toujours @ref{1,,__main__}.

Class definition blocks and arguments to @ref{17d,,exec()} and @ref{17e,,eval()} are
special in the context of name resolution.
A class definition is an executable statement that may use and define names.
These references follow the normal rules for name resolution with an exception
that unbound local variables are looked up in the global namespace.
The namespace of the class definition becomes the attribute dictionary of
the class. The scope of names defined in a class block is limited to the
class block; it does not extend to the code blocks of methods. This includes
comprehensions and generator expressions, but it does not include
@ref{186,,annotation scopes},
which have access to their enclosing class scopes.
This means that the following will fail:

@example
class A:
    a = 42
    b = list(a + i for i in range(10))
@end example

However, the following will succeed:

@example
class A:
    type Alias = Nested
    class Nested: pass

print(A.Alias.__value__)  # <type 'A.Nested'>
@end example

@node Annotation scopes,Lazy evaluation,Résolution des noms,Noms et liaisons
@anchor{reference/executionmodel annotation-scopes}@anchor{186}@anchor{reference/executionmodel id1}@anchor{1f61}
@subsubsection Annotation scopes


@ref{2b0,,Type parameter lists} and @ref{421,,type} statements
introduce `annotation scopes', which behave mostly like function scopes,
but with some exceptions discussed below. @ref{441,,Annotations}
currently do not use annotation scopes, but they are expected to use
annotation scopes in Python 3.13 when 
@geindex Python Enhancement Proposals; PEP 649
PEP 649@footnote{https://peps.python.org/pep-0649/} is implemented.

Annotation scopes are used in the following contexts:


@itemize *

@item 
Type parameter lists for @ref{43f,,generic type aliases}.

@item 
Type parameter lists for @ref{43c,,generic functions}.
A generic function's annotations are
executed within the annotation scope, but its defaults and decorators are not.

@item 
Type parameter lists for @ref{43b,,generic classes}.
A generic class's base classes and
keyword arguments are executed within the annotation scope, but its decorators are not.

@item 
The bounds, constraints, and default values for type parameters
(@ref{440,,lazily evaluated}).

@item 
The value of type aliases (@ref{440,,lazily evaluated}).
@end itemize

Annotation scopes differ from function scopes in the following ways:


@itemize *

@item 
Annotation scopes have access to their enclosing class namespace.
If an annotation scope is immediately within a class scope, or within another
annotation scope that is immediately within a class scope, the code in the
annotation scope can use names defined in the class scope as if it were
executed directly within the class body. This contrasts with regular
functions defined within classes, which cannot access names defined in the class scope.

@item 
Expressions in annotation scopes cannot contain @ref{9bb,,yield}, @code{yield from},
@ref{1b7,,await}, or @ref{1f62,,;=}
expressions. (These expressions are allowed in other scopes contained within the
annotation scope.)

@item 
Names defined in annotation scopes cannot be rebound with @ref{1285,,nonlocal}
statements in inner scopes. This includes only type parameters, as no other
syntactic elements that can appear within annotation scopes can introduce new names.

@item 
While annotation scopes have an internal name, that name is not reflected in the
@ref{18ce,,qualified name} of objects defined within the scope.
Instead, the @ref{104e,,__qualname__}
of such objects is as if the object were defined in the enclosing scope.
@end itemize


Ajouté dans la version 3.12: Annotation scopes were introduced in Python 3.12 as part of 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



Modifié dans la version 3.13: Annotation scopes are also used for type parameter defaults, as
introduced by 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}.


@node Lazy evaluation,Noms natifs et restrictions d'exécution,Annotation scopes,Noms et liaisons
@anchor{reference/executionmodel id2}@anchor{1f63}@anchor{reference/executionmodel lazy-evaluation}@anchor{440}
@subsubsection Lazy evaluation


The values of type aliases created through the @ref{421,,type} statement are
`lazily evaluated'. The same applies to the bounds, constraints, and default values of type
variables created through the @ref{2b0,,type parameter syntax}.
This means that they are not evaluated when the type alias or type variable is
created. Instead, they are only evaluated when doing so is necessary to resolve
an attribute access.

Exemple :

@example
>>> type Alias = 1/0
>>> Alias.__value__
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
>>> def func[T: 1/0](): pass
>>> T = func.__type_params__[0]
>>> T.__bound__
Traceback (most recent call last):
  ...
ZeroDivisionError: division by zero
@end example

Here the exception is raised only when the @code{__value__} attribute
of the type alias or the @code{__bound__} attribute of the type variable
is accessed.

This behavior is primarily useful for references to types that have not
yet been defined when the type alias or type variable is created. For example,
lazy evaluation enables creation of mutually recursive type aliases:

@example
from typing import Literal

type SimpleExpr = int | Parenthesized
type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]
type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr]
@end example

Lazily evaluated values are evaluated in @ref{186,,annotation scope},
which means that names that appear inside the lazily evaluated value are looked up
as if they were used in the immediately enclosing scope.


Ajouté dans la version 3.12.


@node Noms natifs et restrictions d'exécution,Interaction avec les fonctionnalités dynamiques,Lazy evaluation,Noms et liaisons
@anchor{reference/executionmodel builtins-and-restricted-execution}@anchor{1f64}@anchor{reference/executionmodel restrict-exec}@anchor{1f65}
@subsubsection Noms natifs et restrictions d'exécution


@geindex restricted;execution

`Particularité de l'implémentation CPython :' L'utilisateur ne doit pas toucher à @code{__builtins__} ; c'est et cela doit rester réservé aux besoins de l'implémentation. Les utilisateurs qui souhaitent surcharger des valeurs dans l'espace de nommage natif doivent @ref{5cc,,importer} le module @ref{12,,builtins} et modifier ses attributs judicieusement.

L'espace de nommage natif associé à l'exécution d'un bloc de code est effectivement trouvé en cherchant le nom @code{__builtins__} dans l'espace de nommage globaux ; ce doit être un dictionnaire ou un module (dans ce dernier cas, le dictionnaire du module est utilisé). Par défaut, lorsque l'on se trouve dans le module @ref{1,,__main__}, @code{__builtins__} est le module natif @ref{12,,builtins} ; lorsque l'on se trouve dans tout autre module, @code{__builtins__} est un pseudonyme du dictionnaire du module @ref{12,,builtins} lui-même.

@node Interaction avec les fonctionnalités dynamiques,,Noms natifs et restrictions d'exécution,Noms et liaisons
@anchor{reference/executionmodel dynamic-features}@anchor{1f66}@anchor{reference/executionmodel interaction-with-dynamic-features}@anchor{1f67}
@subsubsection Interaction avec les fonctionnalités dynamiques


La résolution des noms de variables libres intervient à l'exécution, pas à la compilation. Cela signifie que le code suivant affiche 42 :

@example
i = 10
def f():
    print(i)
i = 42
f()
@end example

@c XXX from * also invalid with relative imports (at least currently)

Les fonctions @ref{17e,,eval()} et @ref{17d,,exec()} n'ont pas accès à l'environnement complet pour résoudre les noms. Les noms doivent être résolus dans les espaces de nommage locaux et globaux de l'appelant. Les variables libres ne sont pas résolues dans l'espace de nommage englobant le plus proche mais dans l'espace de nommage globaux @footnote{
En effet, le code qui est exécuté par ces opérations n'est pas connu au moment où le module est compilé.
}. Les fonctions @ref{17e,,eval()} et @ref{17d,,exec()} possèdent des arguments optionnels pour surcharger les espaces de nommage globaux et locaux. Si seulement un espace de nommage est spécifié, il est utilisé pour les deux.

@c XXX(ncoghlan) above is only accurate for string execution. When executing code objects,
@c closure cells may now be passed explicitly to resolve co_freevars references.
@c Docs issue: https://github.com/python/cpython/issues/122826

@node Exceptions<2>,,Noms et liaisons,Modèle d'exécution
@anchor{reference/executionmodel exceptions}@anchor{1f68}@anchor{reference/executionmodel id4}@anchor{1f69}
@subsection Exceptions


@geindex exception

@geindex raise an exception
@geindex handle an exception
@geindex exception handler
@geindex errors
@geindex error handling

Les exceptions sont un moyen de sortir du flot normal d'exécution d'un bloc de code de manière à gérer des erreurs ou des conditions exceptionnelles. Une exception est `levée' au moment où l'erreur est détectée ; elle doit être `gérée' par le bloc de code qui l'entoure ou par tout bloc de code qui a, directement ou indirectement, invoqué le bloc de code où l'erreur s'est produite.

L'interpréteur Python lève une exception quand il détecte une erreur à l'exécution (telle qu'une division par zéro). Un programme Python peut aussi lever explicitement une exception avec l'instruction @ref{5d7,,raise}. Les gestionnaires d'exception sont spécifiés avec l'instruction @ref{6d3,,try} … @ref{189,,except}. La clause @ref{9b8,,finally} d'une telle instruction peut être utilisée pour spécifier un code de nettoyage qui ne gère pas l'exception mais qui est exécuté quoi qu'il arrive (exception ou pas).

@geindex termination model

Python utilise le modèle par `terminaison' de gestion des erreurs : un gestionnaire d'exception peut trouver ce qui est arrivé et continuer l'exécution à un niveau plus élevé, mais il ne peut pas réparer l'origine de l'erreur et ré-essayer l'opération qui a échoué (sauf à entrer à nouveau dans le code en question par le haut).

@geindex SystemExit (built-in exception)

Quand une exception n'est pas du tout gérée, l'interpréteur termine l'exécution du programme ou retourne à la boucle interactive. Dans ces cas, il affiche une trace de la pile d'appels, sauf si l'exception est @ref{d2e,,SystemExit}.

Les exceptions sont identifiées par des instances de classe. La clause @ref{189,,except} sélectionnée dépend de la classe de l'instance : elle doit faire référence à la classe de l'instance ou à une de ses @ref{1193,,classes ancêtres non virtuelles}. L'instance peut être transmise au gestionnaire et peut apporter des informations complémentaires sur les conditions de l'exception.

@cartouche
@quotation Note 
Les messages d'exception ne font pas partie de l'API Python. Leur contenu peut changer d'une version de Python à une autre sans avertissement et le code ne doit pas reposer sur ceux-ci s'il doit fonctionner sur plusieurs versions de l'interpréteur.
@end quotation
@end cartouche

Reportez-vous aussi aux descriptions de l'instruction @ref{6d3,,try} dans la section @ref{6d3,,L'instruction try} et de l'instruction @ref{5d7,,raise} dans la section @ref{5d7,,L'instruction raise}.

@subsubheading Notes


@node Le système d'importation,Expressions,Modèle d'exécution,La référence du langage Python
@anchor{reference/import doc}@anchor{1f6a}@anchor{reference/import importsystem}@anchor{1e98}@anchor{reference/import the-import-system}@anchor{1f6b}
@section Le système d'importation


@geindex importation

Le code Python d'un @ref{15e8,,module} peut accéder à du code d'un autre module par un mécanisme qui consiste à @ref{1f6c,,importer} cet autre module. L'instruction @ref{5cc,,import} est la façon la plus courante de faire appel à ce système d'importation, mais ce n'est pas la seule. Les fonctions telles que @ref{501,,importlib.import_module()} et @ref{8c1,,__import__()} peuvent aussi être utilisées pour mettre en œuvre le mécanisme d'importation.

L'instruction @ref{5cc,,import} effectue deux opérations ; elle cherche le module dont le nom a été donné puis elle lie le résultat de cette recherche à un nom dans la portée locale. L'opération de recherche de l'instruction @code{import} consiste à appeler la fonction @ref{8c1,,__import__()} avec les arguments adéquats. La valeur renvoyée par @ref{8c1,,__import__()} est utilisée pour effectuer l'opération de liaison avec le nom fourni à l'instruction @code{import}. Reportez-vous à l'instruction @code{import} pour les détails exacts de l'opération de liaison avec le nom.

Un appel direct à @ref{8c1,,__import__()} effectue seulement la recherche du module et, s'il est trouvé, l'opération de création du module. Bien que des effets collatéraux puissent se produire, tels que l'importation de paquets parents et la mise à jour de divers caches (y compris @ref{18f9,,sys.modules}), il n'y a que l'instruction @ref{5cc,,import} qui déclenche l'opération de liaison avec le nom.

Quand une instruction @ref{5cc,,import} est exécutée, la fonction native @ref{8c1,,__import__()} est appelée. D'autres mécanismes d'appel au système d'importation (tels que @ref{501,,importlib.import_module()}) peuvent choisir d'ignorer @ref{8c1,,__import__()} et utiliser leurs propres solutions pour implémenter la sémantique d'importation.

Quand un module est importé pour la première fois, Python recherche le module et, s'il est trouvé, crée un objet module @footnote{
Voir @ref{e00,,types.ModuleType}.
} en l'initialisant. Si le module n'est pas trouvé, une @ref{b35,,ModuleNotFoundError} est levée. Python implémente plusieurs stratégies pour rechercher le module d'un nom donné quand le mécanisme d'importation est invoqué. Ces stratégies peuvent être modifiées et étendues par divers moyens décrits dans les sections suivantes.


Modifié dans la version 3.3: le système d'importation a été mis à jour pour implémenter complètement la deuxième partie de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}. Il n'existe plus de mécanisme implicite d'importation (le système d'importation complet est exposé `via' @ref{d19,,sys.meta_path}). En complément, la gestion des paquets dans l'espace des noms natif a été implémentée (voir la 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}).


@menu
* importlib: importlib<10>. 
* Les paquets: Les paquets<2>. 
* Recherche:: 
* Chargement:: 
* Le chercheur dans path:: 
* Remplacement du système d'importation standard:: 
* Importations relatives au paquet:: 
* Cas particulier de __main__:: 
* Références:: 

@end menu

@node importlib<10>,Les paquets<2>,,Le système d'importation
@anchor{reference/import importlib}@anchor{1f6d}
@subsection @code{importlib}


Le module @ref{76,,importlib} fournit une API riche pour interagir avec le système d'importation. Par exemple, @ref{501,,importlib.import_module()} fournit une API (que nous vous recommandons) plus simple que la fonction native @ref{8c1,,__import__()} pour mettre en œuvre le mécanisme d'importation. Reportez-vous à la documentation de la bibliothèque @ref{76,,importlib} pour obtenir davantage de détails.

@node Les paquets<2>,Recherche,importlib<10>,Le système d'importation
@anchor{reference/import packages}@anchor{1f6e}
@subsection Les paquets


@geindex Les paquets

Python ne connait qu'un seul type d'objet module et tous les modules sont donc de ce type, que le module soit implémenté en Python, en C ou quoi que ce soit d'autre. Pour aider à l'organisation des modules et fournir une hiérarchie des noms, Python développe le concept de @ref{1e9f,,paquets}.

Vous pouvez vous représenter les paquets comme des répertoires dans le système de fichiers et les modules comme des fichiers dans ces répertoires. Mais ne prenez pas trop cette analogie au pied de la lettre car les paquets et les modules ne proviennent pas obligatoirement du système de fichiers. Dans le cadre de cette documentation, nous utilisons cette analogie bien pratique des répertoires et des fichiers. Comme les répertoires du système de fichiers, les paquets sont organisés de manière hiérarchique et les paquets peuvent eux-mêmes contenir des sous-paquets ou des modules.

Il est important de garder à l'esprit que tous les paquets sont des modules mais que tous les modules ne sont pas des paquets. Formulé autrement, les paquets sont juste un certain type de modules. Spécifiquement, tout module qui contient un attribut @code{__path__} est réputé être un paquet.

Tous les modules ont un nom. Les noms des sous-paquets sont séparés du nom du paquet parent par un point (@code{.}), à l'instar de la syntaxe standard d'accès aux attributs en Python. Ainsi, vous pouvez avoir un paquet nommé @ref{3b,,email} qui possède un sous-paquet nommé @ref{45,,email.mime} et un module dans ce sous-paquet nommé @ref{4d,,email.mime.text}.

@menu
* Paquets classiques:: 
* Paquets espaces de nommage:: 

@end menu

@node Paquets classiques,Paquets espaces de nommage,,Les paquets<2>
@anchor{reference/import regular-packages}@anchor{1f6f}
@subsubsection Paquets classiques


@geindex Les paquets;classique

Python définit deux types de paquets, les @ref{1f70,,paquets classiques} et les @ref{1bf6,,paquets espaces de nommage}. Les paquets classiques sont les paquets traditionnels tels qu'ils existaient dans Python 3.2 et antérieurs. Un paquet classique est typiquement implémenté sous la forme d'un répertoire contenant un fichier @code{__init__.py}. Quand un paquet classique est importé, ce fichier @code{__init__.py} est implicitement exécuté.

Par exemple, l'arborescence suivante définit un paquet @code{parent} au niveau le plus haut avec trois sous-paquets :

@example
parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py
@end example

Importer @code{parent.one} exécute implicitement @code{parent/__init__.py} et @code{parent/one/__init__.py}. Les importations postérieures de @code{parent.two} ou @code{parent.three} respectivement exécutent @code{parent/two/__init__.py} ou @code{parent/three/__init__.py} respectivement.

@node Paquets espaces de nommage,,Paquets classiques,Les paquets<2>
@anchor{reference/import namespace-packages}@anchor{1f71}
@subsubsection Paquets espaces de nommage


@geindex Les paquets;espace de nommage
@geindex Les paquets;portion

Un paquet-espace de nommage est la combinaison de plusieurs @ref{1f72,,portions} où chaque portion fournit un sous-paquet au paquet parent. Les portions peuvent être situées à différents endroits du système de fichiers. Les portions peuvent aussi être stockées dans des fichiers zip, sur le réseau ou à tout autre endroit dans lequel Python cherche pendant l'importation. Les paquets-espaces de nommage peuvent correspondre directement à des objets du système de fichiers, ou pas ; ils peuvent être des modules virtuels qui n'ont aucune représentation concrète.

Les paquets-espaces de nommage n'utilisent pas une liste ordinaire pour leur attribut @code{__path__}. Ils utilisent en lieu et place un type itérable personnalisé qui effectue automatiquement une nouvelle recherche de portions de paquets à la tentative suivante d'importation dans ce paquet si le chemin de leur paquet parent (ou @ref{3ab,,sys.path} pour les paquets de plus haut niveau) change.

Pour les paquets-espaces de nommage, il n'existe pas de fichier @code{parent/__init__.py}. En fait, il peut y avoir plusieurs répertoires @code{parent} trouvés pendant le processus d'importation, où chacun est apporté par une portion différente. Ainsi, @code{parent/one} n'est pas forcément physiquement à côté de @code{parent/two}. Dans ce cas, Python crée un paquet-espace de nommage pour le paquet de plus haut niveau @code{parent} dès que lui ou l'un de ses sous-paquet est importé.

Voir aussi la 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} pour les spécifications des paquets-espaces de nommage.

@node Recherche,Chargement,Les paquets<2>,Le système d'importation
@anchor{reference/import searching}@anchor{1f73}
@subsection Recherche


Pour commencer la recherche, Python a besoin du @ref{18ce,,nom qualifié} du module (ou du paquet, mais ici cela ne fait pas de différence) que vous souhaitez importer. Le nom peut être donné en argument à l'instruction @ref{5cc,,import} ou comme paramètre aux fonctions @ref{501,,importlib.import_module()} ou @ref{8c1,,__import__()}.

Le nom est utilisé dans plusieurs phases de la recherche et peut être un chemin séparé par des points pour un sous-module, par exemple @code{truc.machin.bidule}. Dans ce cas, Python essaie d'abord d'importer @code{truc} puis @code{truc.machin} et enfin @code{truc.machin.bidule}. Si n'importe laquelle des importations intermédiaires échoue, une @ref{b35,,ModuleNotFoundError} est levée.

@menu
* Cache des modules:: 
* Chercheurs et chargeurs:: 
* Points d'entrées automatiques pour l'importation:: 
* Méta-chemins:: 

@end menu

@node Cache des modules,Chercheurs et chargeurs,,Recherche
@anchor{reference/import the-module-cache}@anchor{1f74}
@subsubsection Cache des modules


@geindex sys.modules

Le premier endroit vérifié pendant la recherche d'une importation est @ref{18f9,,sys.modules}. Ce tableau de correspondances est utilisé comme cache de tous les modules déjà importés, y compris les chemins intermédiaires. Ainsi, si @code{truc.machin.bidule} a déjà été importé, @ref{18f9,,sys.modules} contient les entrées correspondantes à @code{truc}, @code{truc.machin} et @code{truc.machin.bidule}. À chaque chemin correspond une clé.

Pendant l'importation, le nom de module est cherché dans @ref{18f9,,sys.modules} et, s'il est trouvé, la valeur associée est le module recherché et le processus est fini. Cependant, si la valeur est @code{None}, alors une @ref{b35,,ModuleNotFoundError} est levée. Si le nom du module n'est pas trouvé, Python continue la recherche du module.

@ref{18f9,,sys.modules} est accessible en lecture-écriture. Supprimer une clé peut ne pas détruire le module associé (car d'autres modules contiennent possiblement des références vers ce module), mais cela invalide l'entrée du cache pour ce nom de module. Python cherche alors un nouveau module pour ce nom. La clé peut aussi être assignée à @code{None} de manière à forcer une @ref{b35,,ModuleNotFoundError} lors de la prochaine importation du module.

Attention cependant : s'il reste une référence à l'objet module et que vous invalidez l'entrée dans le cache de @ref{18f9,,sys.modules} puis ré-importez le module, les deux objets modules ne seront pas les mêmes. À l'inverse, @ref{502,,importlib.reload()} ré-utilise le `même' objet module et ré-initialise simplement le contenu du module en ré-exécutant le code du module.

@node Chercheurs et chargeurs,Points d'entrées automatiques pour l'importation,Cache des modules,Recherche
@anchor{reference/import finders-and-loaders}@anchor{1f75}@anchor{reference/import id2}@anchor{1f76}
@subsubsection Chercheurs et chargeurs


@geindex chercheur
@geindex chargeur
@geindex spécificateur de module

Si le module n'est pas trouvé dans @ref{18f9,,sys.modules}, alors Python utilise son protocole d'importation pour chercher et charger le module. Ce protocole se compose de deux objets conceptuels : les @ref{1ea3,,chercheurs} et les @ref{1639,,chargeurs}. Le travail du chercheur consiste à trouver, à l'aide de différentes stratégies, le module dont le nom a été fourni. Les objets qui implémentent ces deux interfaces sont connus sous le vocable « @ref{1f6c,,importateurs} » (ils renvoient une référence vers eux-mêmes quand ils trouvent un module qui répond aux attentes).

Python inclut plusieurs chercheurs et importateurs par défaut. Le premier sait comment trouver les modules natifs et le deuxième sait comment trouver les modules figés. Un troisième chercheur recherche les modules dans @ref{1f77,,import path}. @ref{1f77,,import path} est une énumération sous forme de liste de chemins ou de fichiers zip. Il peut être étendu pour rechercher aussi dans toute ressource qui dispose d'un identifiant pour la localiser, une URL par exemple.

Le mécanisme d'importation est extensible, vous pouvez donc ajouter de nouveaux chercheurs pour étendre le domaine de recherche des modules.

Les chercheurs ne chargent pas les modules. S'il trouve le module demandé, un chercheur renvoie un `spécificateur de module', qui contient toutes les informations nécessaires pour importer le module ; celui-ci sera alors utilisé par le mécanisme d'importation pour charger le module.

Les sections suivantes décrivent plus en détail le protocole utilisé par les chercheurs et les chargeurs, y compris la manière de les créer et les enregistrer pour étendre le mécanisme d'importation.


Modifié dans la version 3.4: dans les versions précédentes de Python, les chercheurs renvoyaient directement les @ref{1639,,chargeurs}. Dorénavant, ils renvoient des spécificateurs de modules qui `contiennent' les chargeurs. Les chargeurs sont encore utilisés lors de l'importation mais ont moins de responsabilités.


@node Points d'entrées automatiques pour l'importation,Méta-chemins,Chercheurs et chargeurs,Recherche
@anchor{reference/import import-hooks}@anchor{1f78}
@subsubsection Points d'entrées automatiques pour l'importation


@geindex points d'entrée d'importation
@geindex méta-points d'entrée d'importation
@geindex points d'entrée de chemin de fichier
@geindex points d'entrée;importation
@geindex points d'entrée;méta
@geindex points d'entrée;chemin

Le mécanisme d'importation est conçu pour être extensible ; vous pouvez y insérer des `points d'entrée automatique' (`hooks' en anglais). Il existe deux types de points d'entrée automatique pour l'importation : les `méta-points d'entrée' et les `points d'entrée sur le chemin des importations'.

Les méta-points d'entrée sont appelés au début du processus d'importation, juste après la vérification dans le cache @ref{18f9,,sys.modules} mais avant tout le reste. Cela permet aux méta-points d'entrée de surcharger le traitement effectué sur @ref{3ab,,sys.path}, les modules figés ou même les modules natifs. L'enregistrement des méta-points d'entrée se fait en ajoutant de nouveaux objets chercheurs à @ref{d19,,sys.meta_path}, comme décrit ci-dessous.

Les points d'entrée sur le chemin des importations sont appelés pendant le traitement de @ref{3ab,,sys.path} (ou @code{package.__path__}), au moment où le chemin qui leur correspond est atteint. Les points d'entrée sur le chemin des importations sont enregistrés en ajoutant de nouveaux appelables à @ref{100d,,sys.path_hooks}, comme décrit ci-dessous.

@node Méta-chemins,,Points d'entrées automatiques pour l'importation,Recherche
@anchor{reference/import the-meta-path}@anchor{1f79}
@subsubsection Méta-chemins


@geindex sys.meta_path
@geindex chercheur;find_spec

Quand le module demandé n'est pas trouvé dans @ref{18f9,,sys.modules}, Python recherche alors dans @ref{d19,,sys.meta_path} qui contient une liste d'objets chercheurs dans des méta-chemins. Ces chercheurs sont interrogés dans l'ordre pour voir s'ils savent prendre en charge le module passé en paramètre. Les chercheurs dans les méta-chemins implémentent une méthode @ref{853,,find_spec()} qui prend trois arguments : un nom, un chemin d'importation et (optionnellement) un module cible. Un chercheur dans les méta-chemins peut utiliser n'importe quelle stratégie pour déterminer s'il est apte à prendre en charge le module.

Si un chercheur dans les méta-chemins sait prendre en charge le module donné, il renvoie un objet spécificateur. S'il ne sait pas, il renvoie @code{None}. Si le traitement de @ref{d19,,sys.meta_path} arrive à la fin de la liste sans qu'aucun chercheur n'a renvoyé un objet spécificateur, alors une @ref{b35,,ModuleNotFoundError} est levée. Toute autre exception levée est simplement propagée à l'appelant, mettant fin au processus d'importation.

La méthode @ref{853,,find_spec()} des chercheurs dans les méta-chemins est appelée avec deux ou trois arguments. Le premier est le nom complètement qualifié du module à importer, par exemple @code{truc.machin.bidule}. Le deuxième argument est l'ensemble des chemins dans lesquels chercher. Pour les modules de plus haut niveau, le deuxième argument est @code{None} mais pour les sous-modules ou les paquets, le deuxième argument est la valeur de l'attribut @code{__path__} du paquet parent. Si l'attribut @code{__path__} approprié n'est pas accessible, une @ref{b35,,ModuleNotFoundError} est levée. Le troisième argument est un objet module existant qui va être la cible du chargement (plus tard). Le système d'importation ne passe le module cible en paramètre que lors d'un rechargement.

Le méta-chemin peut être parcouru plusieurs fois pour une seule requête d'importation. Par exemple, si nous supposons qu'aucun des modules concernés n'a déjà été mis en cache, importer @code{truc.machin.bidule} effectue une première importation au niveau le plus haut, en appelant @code{c_m_c.find_spec("truc", None, None)} pour chaque chercheur dans les méta-chemins (@code{c_m_c}). Après que @code{truc} a été importé, @code{truc.machin} est importé en parcourant le méta-chemin une deuxième fois, appelant @code{c_m_c.find_spec("truc.machin", truc.__path__, None)}. Une fois @code{truc.machin} importé, le parcours final appelle @code{c_m_c.find_spec("truc.machin.bidule", truc.machin.__path__, None)}.

Quelques chercheurs dans les méta-chemins ne gèrent que les importations de plus haut niveau. Ces importateurs renvoient toujours @code{None} si on leur passe un deuxième argument autre que @code{None}.

Le @ref{d19,,sys.meta_path} de Python comprend trois chercheurs par défaut : un qui sait importer les modules natifs, un qui sait importer les modules figés et un qui sait importer les modules depuis un @ref{1f77,,chemin des importations} (c'est le @ref{1f7a,,chercheur dans path}).


Modifié dans la version 3.4: La méthode @ref{853,,find_spec()} des chercheurs dans les méta-chemins a remplacé @code{find_module()}, devenue obsolète. Bien qu'elle continue de fonctionner comme avant, le mécanisme d'importation essaie @code{find_module()} uniquement si le chercheur n'implémente pas @ref{853,,find_spec()}.



Modifié dans la version 3.10: L'utilisation de @code{find_module()} par le système d'importation lève maintenant un @ref{4e4,,ImportWarning}.



Modifié dans la version 3.12: @code{find_module()} a été supprimé. Utiliser @ref{853,,find_spec()} à la place.


@node Chargement,Le chercheur dans path,Recherche,Le système d'importation
@anchor{reference/import loading}@anchor{1f7b}
@subsection Chargement


Quand un spécificateur de module est trouvé, le mécanisme d'importation l'utilise (et le chargeur qu'il contient) pour charger le module. Voici à peu près ce qui se passe au sein de l'importation pendant la phase de chargement :

@example
module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
    # It is assumed 'exec_module' will also be defined on the loader.
    module = spec.loader.create_module(spec)
if module is None:
    module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)

if spec.loader is None:
    # unsupported
    raise ImportError
if spec.origin is None and spec.submodule_search_locations is not None:
    # namespace package
    sys.modules[spec.name] = module
elif not hasattr(spec.loader, 'exec_module'):
    module = spec.loader.load_module(spec.name)
else:
    sys.modules[spec.name] = module
    try:
        spec.loader.exec_module(module)
    except BaseException:
        try:
            del sys.modules[spec.name]
        except KeyError:
            pass
        raise
return sys.modules[spec.name]
@end example

Notez les détails suivants :


@itemize *

@item 
S'il existe un objet module dans @ref{18f9,,sys.modules} avec le même nom, `import' l'aurait déjà renvoyé.

@item 
Le module existe dans @ref{18f9,,sys.modules} avant que le chargeur exécute le code du module. C'est crucial car le code du module peut (directement ou indirectement) s'importer lui-même ; l'ajouter à @ref{18f9,,sys.modules} avant évite les récursions infinies dans le pire cas et le chargement multiple dans le meilleur des cas.

@item 
Si le chargement échoue, le module en cause (et seulement ce module) est enlevé de @ref{18f9,,sys.modules}. Tout module déjà dans le cache de @ref{18f9,,sys.modules} et tout module qui a été chargé avec succès par effet de bord doit rester dans le cache. C'est différent dans le cas d'un rechargement où même le module qui a échoué est conservé dans @ref{18f9,,sys.modules}.

@item 
Après que le module est créé mais avant son exécution, le mécanisme d'importation définit les attributs relatifs à l'importation (@code{_init_module_attrs} dans l'exemple de pseudo-code ci-dessus), comme indiqué brièvement dans une @ref{1e99,,section} que nous abordons ensuite.

@item 
L'exécution du module est le moment clé du chargement dans lequel l'espace de nommage du module est peuplé. L'exécution est entièrement déléguée au chargeur qui doit décider ce qui est peuplé et comment.

@item 
Le modulé créé pendant le chargement et passé à @code{exec_module()} peut ne pas être celui qui est renvoyé à la fin de l'importation @footnote{
L'implémentation de `importlib' évite d'utiliser directement la valeur de retour. À la place, elle récupère l'objet module en recherchant le nom du module dans @ref{18f9,,sys.modules}. L'effet indirect est que le module importé peut remplacer le module de même nom dans @ref{18f9,,sys.modules}. C'est un comportement spécifique à l'implémentation dont le résultat n'est pas garanti pour les autres implémentations de Python.
}.
@end itemize


Modifié dans la version 3.4: le système d'importation a pris en charge les responsabilités des chargeurs. Celles-ci étaient auparavant effectuées par la méthode @ref{854,,importlib.abc.Loader.load_module()}.


@menu
* Chargeurs:: 
* Sous-modules:: 
* Spécificateurs de modules:: 
* l'attribut __path__ des modules:: 
* Représentation textuelle d'un module:: 
* Invalidation de bytecode mis en cache:: 

@end menu

@node Chargeurs,Sous-modules,,Chargement
@anchor{reference/import loaders}@anchor{1f7c}
@subsubsection Chargeurs


Les chargeurs de modules fournissent la fonction critique du chargement : l'exécution du module. Le mécanisme d'importation appelle la méthode @ref{855,,importlib.abc.Loader.exec_module()} avec un unique argument, l'objet module à exécuter. Toute valeur renvoyée par @ref{855,,exec_module()} est ignorée.

Les chargeurs doivent satisfaire les conditions suivantes :


@itemize *

@item 
Si le module est un module Python (par opposition aux modules natifs ou aux extensions chargées dynamiquement), le chargeur doit exécuter le code du module dans l'espace des noms globaux du module (@code{module.__dict__}).

@item 
Si le chargeur ne peut pas exécuter le module, il doit lever une @ref{40f,,ImportError}, alors que toute autre exception levée durant @ref{855,,exec_module()} est propagée.
@end itemize

Souvent, le chercheur et le chargeur sont le même objet ; dans ce cas, la méthode @ref{853,,find_spec()} doit juste renvoyer un spécificateur avec le chargeur défini à @code{self}.

Les chargeurs de modules peuvent choisir de créer l'objet module pendant le chargement en implémentant une méthode @ref{c9c,,create_module()}. Elle prend un argument, l'objet spécificateur du module et renvoie le nouvel objet du module à utiliser pendant le chargement. Notez que @code{create_module()} n'a besoin de définir aucun attribut sur l'objet module. Si cette méthode renvoie @code{None}, le mécanisme d'importation crée le nouveau module lui-même.


Ajouté dans la version 3.4: la méthode @ref{c9c,,create_module()} des chargeurs.



Modifié dans la version 3.4: la méthode @ref{854,,load_module()} a été remplacée par @ref{855,,exec_module()} et le mécanisme d'import assume toutes les responsabilités du chargement.

Par compatibilité avec les chargeurs existants, le mécanisme d'importation utilise la méthode @code{load_module()} des chargeurs si elle existe et si le chargeur n'implémente pas @code{exec_module()}. Cependant, @code{load_module()} est déclarée obsolète et les chargeurs doivent implémenter @code{exec_module()} à la place.

La méthode @code{load_module()} `doit' implémenter toutes les fonctionnalités de chargement décrites ci-dessus en plus de l'exécution du module. Toutes les contraintes s'appliquent aussi, avec quelques précisions supplémentaires :


@itemize *

@item 
S'il y a un objet module existant avec le même nom dans @ref{18f9,,sys.modules}, le chargeur doit utiliser le module existant (sinon, @ref{502,,importlib.reload()} ne fonctionnera pas correctement). Si le module considéré n'est pas trouvé dans @ref{18f9,,sys.modules}, le chargeur doit créer un nouvel objet module et l'ajouter à @ref{18f9,,sys.modules}.

@item 
Le module `doit' exister dans @ref{18f9,,sys.modules} avant que le chargeur n'exécute le code du module, afin d'éviter les récursions infinies ou le chargement multiple.

@item 
Si le chargement échoue, le chargeur ne doit enlever de @ref{18f9,,sys.modules} `que' le (ou les) module ayant échoué et seulement si le chargeur lui-même a chargé le module explicitement.
@end itemize



Modifié dans la version 3.5: un avertissement @ref{1a3,,DeprecationWarning} est levé quand @code{exec_module()} est définie mais @code{create_module()} ne l'est pas.



Modifié dans la version 3.6: une exception @ref{40f,,ImportError} est levée quand @code{exec_module()} est définie mais @code{create_module()} ne l'est pas.



Modifié dans la version 3.10: l'utilisation de @code{load_module()} lève un @ref{4e4,,ImportWarning}.


@node Sous-modules,Spécificateurs de modules,Chargeurs,Chargement
@anchor{reference/import submodules}@anchor{1f7d}
@subsubsection Sous-modules


Quand un sous-module est chargé, quel que soit le mécanisme (par exemple avec les instructions @code{import}, @code{import-from} ou avec la fonction native @code{__import__()}), une liaison est créée dans l'espace de nommage du module parent vers l'objet sous-module. Par exemple, si le paquet @code{spam} possède un sous-module @code{foo}, après l'importation de @code{spam.foo}, @code{spam} possède un attribut @code{foo} qui est lié au sous-module. Supposons que nous ayons l'arborescence suivante :

@example
spam/
    __init__.py
    foo.py
@end example

et que le contenu de @code{spam/__init__.py} contienne :

@example
from .foo import Foo
@end example

alors exécuter les lignes suivantes crée des liens vers @code{foo} et @code{Foo} dans le module @code{spam} :

@example
>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.Foo
<class 'spam.foo.Foo'>
@end example

Connaissant la façon habituelle dont Python effectue les liens, cela peut sembler surprenant. Mais c'est en fait une fonctionnalité fondamentale du système d'importation. Si vous avez quelque part @code{sys.modules['spam']} et @code{sys.modules['spam.foo']} (comme dans c'est le cas ci-dessus après l'importation), alors le dernier doit apparaître comme l'attribut @code{foo} du premier.

@node Spécificateurs de modules,l'attribut __path__ des modules,Sous-modules,Chargement
@anchor{reference/import id4}@anchor{1f7e}@anchor{reference/import module-specs}@anchor{1e9e}
@subsubsection Spécificateurs de modules


Le mécanisme d'importation utilise diverses informations de chaque module pendant l'importation, spécialement avant le chargement. La plupart de ces informations sont communes à tous les modules. Le but d'un spécificateur de module est d'encapsuler ces informations relatives à l'importation au sein de chaque module.

Utiliser un spécificateur pendant l'importation permet de transférer l'état entre les composants du système d'importation, par exemple entre le chercheur qui crée le spécificateur de module et le chargeur qui l'exécute. Surtout, cela permet au mécanisme d'importation d'effectuer toutes les opérations classiques de chargement, alors que c'était le chargeur qui en avait la responsabilité quand il n'y avait pas de spécificateur.

L'attribut @ref{1e9c,,module.__spec__} doit contenir un lien vers le spécificateur de module qui a été utilisé lors de l'importation du module. Définir @code{__spec__} correctement s'applique aussi lors de @ref{1f7f,,l'initialisation des modules au démarrage de l'interpréteur}. La seule exception est @code{__main__} pour lequel la valeur de @code{__spec__} @ref{1f80,,peut être parfois None}.

Lisez @ref{1ded,,ModuleSpec} pour davantage d'informations sur le contenu du spécificateur de module.


Ajouté dans la version 3.4.


@node l'attribut __path__ des modules,Représentation textuelle d'un module,Spécificateurs de modules,Chargement
@anchor{reference/import package-path-rules}@anchor{1ea0}@anchor{reference/import path-attributes-on-modules}@anchor{1f81}
@subsubsection l'attribut @code{__path__} des modules


L'attribut @ref{1bfc,,__path__} doit être une @ref{4db,,sequence} (possiblement vide) de chaînes de caractères listant tous les emplacements où se trouvent les sous-modules du paquet. Par définition, si un module a un attribut @code{__path__} alors c'est un @ref{1e9f,,paquet}

L'attribut @ref{1bfc,,__path__} d'un paquet est utilisé pendant l'importation de ses sous-paquets. Dans le mécanisme d'importation, son fonctionnement ressemble beaucoup à @ref{3ab,,sys.path}, c'est-à-dire qu'il fournit une liste d'emplacements où rechercher les modules pendant l'importation. Cependant, @code{__path__} est beaucoup plus contraint que @code{sys.path}.

Les mêmes règles que pour @ref{3ab,,sys.path} s'appliquent au @code{__path__} d'un paquet. Les @ref{100d,,sys.path_hooks} (dont la description est donnée plus bas) sont consultés pendant le parcours du @code{__path__} du paquet.

Le fichier @code{__init__.py} d'un paquet peut définir ou modifier l'attribut @ref{1bfc,,__path__} d'un paquet, et c'est ainsi qu'étaient implémentés les paquets-espaces de nommage avant la 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}. Depuis l'adoption de la 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}, les paquets-espaces de nommage n'ont plus besoin d'avoir des fichiers @code{__init__.py} qui ne font que de la manipulation de @code{__path__} ; le mécanisme d'importation définit automatiquement @code{__path__} correctement pour un paquet-espace de nommage.

@node Représentation textuelle d'un module,Invalidation de bytecode mis en cache,l'attribut __path__ des modules,Chargement
@anchor{reference/import module-reprs}@anchor{1f82}
@subsubsection Représentation textuelle d'un module


Par défaut, tous les modules ont une représentation textuelle utilisable. Cependant, en utilisant les attributs définis ci-dessus et dans le spécificateur de module, vous pouvez explicitement mieux contrôler l'affichage des objets modules.

Si le module possède un spécificateur (@code{__spec__}), le mécanisme d'importation essaie de générer une représentation avec celui-ci. S'il échoue ou s'il n'y a pas de spécificateur, le système d'importation construit une représentation par défaut en utilisant toute information disponible sur le module. Il tente d'utiliser @code{module.__name__}, @code{module.__file__} et @code{module.__loader__} comme entrées pour la représentation, avec des valeurs par défaut lorsque l'information est manquante.

Les règles exactes utilisées sont :


@itemize *

@item 
Si le module possède un attribut @code{__spec__}, la valeur est utilisée pour générer la représentation. Les attributs `name', `loader', `origin' et `has_location' sont consultés.

@item 
Si le module possède un attribut @code{__file__}, il est utilisé pour construire la représentation du module.

@item 
Si le module ne possède pas d'attribut @code{__file__} mais possède un @code{__loader__} qui n'est pas @code{None}, alors la représentation du chargeur est utilisée pour construire la représentation du module.

@item 
Sinon, il utilise juste le @code{__name__} du module dans la représentation.
@end itemize


Modifié dans la version 3.12: La méthode @code{module_repr()} est obsolète depuis Python 3.4, et a été supprimée en Python 3.12 et n'est donc plus appelée lors de la résolution du @code{__repr__()} d'un module.


@node Invalidation de bytecode mis en cache,,Représentation textuelle d'un module,Chargement
@anchor{reference/import cached-bytecode-invalidation}@anchor{1f83}@anchor{reference/import pyc-invalidation}@anchor{5d6}
@subsubsection Invalidation de `bytecode' mis en cache


Avant que Python ne charge du `bytecode' en cache à partir d'un fichier @code{.pyc}, il vérifie si ce cache est bien à jour par rapport au fichier source @code{.py}. Python effectue cette vérification en stockant l'horodatage de la dernière modification de la source ainsi que sa taille dans le fichier cache au moment où il l'écrit. À l'exécution, le système d'importation valide le fichier cache en comparant les métadonnées que le cache contient avec les métadonnées de la source.

Python gère également les fichiers caches « avec empreintes », qui stockent une empreinte (`hash' en anglais) du contenu de la source plutôt que des métadonnées. Il existe deux variations des fichiers @code{.pyc} avec empreintes : vérifiés et non-vérifiés. Pour les fichiers @code{.pyc} avec empreinte vérifiés, Python valide le fichier cache en calculant l'empreinte du fichier source et compare les empreintes. Si l'empreinte stockée dans le fichier cache est invalide, Python la recalcule et écrit un nouveau fichier cache avec empreinte. Pour les fichiers @code{.pyc} avec empreinte non vérifiés, Python considère simplement que le fichier cache est valide s'il existe. La validation (ou non) des fichiers @code{.pyc} avec empreinte peut être définie avec l'option @ref{1cbc,,--check-hash-based-pycs}.


Modifié dans la version 3.7: ajout des fichiers @code{.pyc} avec empreinte. Auparavant, Python gérait les caches de `bytecode' sur la base de l'horodatage.


@node Le chercheur dans path,Remplacement du système d'importation standard,Chargement,Le système d'importation
@anchor{reference/import the-path-based-finder}@anchor{1f84}
@subsection Le chercheur dans `path'


@geindex le chercheur dans *path*

Comme indiqué précédemment, Python est livré par défaut avec plusieurs chercheurs dans les méta-chemins. L'un deux, appelé @ref{1f7a,,chercheur dans path} (@ref{100c,,PathFinder}), recherche dans le @ref{1f77,,chemin des importations} qui contient une liste @ref{1f85,,d'entrées dans path}. Chaque entrée désigne un emplacement où rechercher des modules.

Le chercheur dans `path' en tant que tel ne sait pas comment importer quoi que ce soit. Il ne fait que parcourir chaque entrée de `path' et associe à chacune d'elle un « chercheur d'entrée dans `path' » qui sait comment gérer le type particulier de chemin considéré.

L'ensemble par défaut des « chercheurs d'entrée dans `path' » implémente toute la sémantique pour trouver des modules dans le système de fichiers, gérer des fichiers spéciaux tels que le code source Python (fichiers @code{.py}), le `bytecode' Python (fichiers @code{.pyc}) et les bibliothèques partagées (par exemple les fichiers @code{.so}). Quand le module @ref{131,,zipimport} de la bibliothèque standard le permet, les « chercheurs d'entrée dans `path' » par défaut savent aussi gérer tous ces types de fichiers (autres que les bibliothèques partagées) encapsulés dans des fichiers zip.

Les chemins ne sont pas limités au système de fichiers. Ils peuvent faire référence à des URL, des requêtes dans des bases de données ou tout autre emplacement qui peut être spécifié dans une chaîne de caractères.

Le chercheur dans `path' fournit aussi des points d'entrées (ou `hooks') et des protocoles de manière à pouvoir étendre et personnaliser les types de chemins dans lesquels chercher. Par exemple, si vous voulez pouvoir chercher dans des URL réseau, vous pouvez écrire une fonction « point d'entrée » qui implémente la sémantique HTTP pour chercher des modules sur la toile. Ce point d'entrée (qui doit être un appelable) doit renvoyer un @ref{105a,,chercheur d'entrée dans path} qui gère le protocole décrit plus bas et qui sera utilisé pour obtenir un chargeur de module sur la toile.

Avertissement : cette section et la précédente utilisent toutes les deux le terme `chercheur', dans un cas @ref{1059,,chercheur dans les méta-chemins} et dans l'autre @ref{105a,,chercheur d'entrée dans path}. Ces deux types de chercheurs sont très similaires, gèrent des protocoles similaires et fonctionnent de manière semblable pendant le processus d'importation, mais il est important de garder à l'esprit qu'ils sont subtilement différents. En particulier, les chercheurs dans les méta-chemins opèrent au début du processus d'importation, comme clé de parcours de @ref{d19,,sys.meta_path}.

Au contraire, les « chercheurs d'entrée dans `path' » sont, dans un sens, un détail d'implémentation du chercheur dans `path' et, en fait, si le chercheur dans `path' était enlevé de @ref{d19,,sys.meta_path}, aucune des sémantiques des « chercheurs d'entrée dans `path' » ne serait invoquée.

@menu
* Chercheurs d'entrée dans path:: 
* Protocole des chercheurs d'entrée dans path:: 

@end menu

@node Chercheurs d'entrée dans path,Protocole des chercheurs d'entrée dans path,,Le chercheur dans path
@anchor{reference/import path-entry-finders}@anchor{1f86}
@subsubsection Chercheurs d'entrée dans `path'


@geindex sys.path
@geindex sys.path_hooks
@geindex sys.path_importer_cache
@geindex PYTHONPATH

Le @ref{1f7a,,chercheur dans path} (`path based finder' en anglais) est responsable de trouver et charger les modules et les paquets Python dont l'emplacement est spécifié par une chaîne dite @ref{1f85,,d'entrée dans path}. La plupart de ces entrées désignent des emplacements sur le système de fichiers, mais il n'y a aucune raison de les limiter à ça.

En tant que chercheur dans les méta-chemins, un @ref{1f7a,,chercheur dans path} implémente le protocole @ref{853,,find_spec()} décrit précédemment. Cependant, il autorise des points d'entrée (`hooks' en anglais) supplémentaires qui peuvent être utilisés pour personnaliser la façon dont les modules sont trouvés et chargés depuis le @ref{1f77,,chemin des importations}.

Trois variables sont utilisées par le @ref{1f7a,,chercheur dans path} : @ref{3ab,,sys.path}, @ref{100d,,sys.path_hooks} et @ref{5ce,,sys.path_importer_cache}. L'attribut @code{__path__} des objets paquets est aussi utilisé. Il permet de personnaliser encore davantage le mécanisme d'importation.

@ref{3ab,,sys.path} contient une liste de chaînes de caractères indiquant des emplacements où chercher des modules ou des paquets. Elle est initialisée à partir de la variable d'environnement 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} et de plusieurs autres valeurs par défaut qui dépendent de l'installation et de l'implémentation. Les entrées de @ref{3ab,,sys.path} désignent des répertoires du système de fichiers, des fichiers zip et possiblement d'autres « endroits » (lisez le module @ref{c6,,site}) tels que des URL ou des requêtes dans des bases de données où Python doit rechercher des modules. @ref{3ab,,sys.path} ne doit contenir que des chaînes de caractères ; tous les autres types sont ignorés.

Le @ref{1f7a,,chercheur dans path} est un @ref{1059,,chercheur dans les méta-chemins}, donc le mécanisme d'importation commence la recherche dans le @ref{1f77,,chemin des importations} par un appel à la méthode @ref{ffa,,find_spec()} du chercheur dans `path', comme décrit précédemment. Quand l'argument `path' de @ref{ffa,,find_spec()} est donné, c'est une liste de chemins à parcourir, typiquement un attribut @code{__path__} pour une importation à l'intérieur d'un paquet. Si l'argument `path' est @code{None}, cela indique une importation de niveau le plus haut et @ref{3ab,,sys.path} est utilisée.

Le chercheur dans `path' itère sur chaque entrée dans le `path' et, pour chacune, regarde s'il trouve un @ref{105a,,chercheur d'entrée dans path} (@ref{85a,,PathEntryFinder}) approprié à cette entrée. Comme cette opération est coûteuse (elle peut faire appel à plusieurs appels @code{stat()} pour cela), le chercheur dans `path' maintient un cache de correspondance entre les entrées et les « chercheurs d'entrée dans `path' ». Ce cache est stocké sous @ref{5ce,,sys.path_importer_cache} (en dépit de son nom, ce cache stocke les objets chercheurs plutôt que les simples objets @ref{1f6c,,importateurs}). Ainsi, la recherche coûteuse pour une @ref{1f85,,entrée de path} spécifique n'a besoin d'être effectuée qu'une seule fois par le @ref{105a,,chercheur d'entrée dans path}. Le code de l'utilisateur peut très bien supprimer les entrées du cache @ref{5ce,,sys.path_importer_cache}, forçant ainsi le chercheur dans `path' à effectuer une nouvelle fois la recherche sur chaque entrée.

Si une entrée n'est pas présente dans le cache, le chercheur dans `path' itère sur chaque `callable' de @ref{100d,,sys.path_hooks}. Chaque @ref{1f87,,point d'entrée sur une entrée de path} de cette liste est appelé avec un unique argument, l'entrée dans laquelle chercher. L'appelable peut soit renvoyer un @ref{105a,,chercheur d'entrée dans path} apte à prendre en charge l'entrée ou lever une @ref{40f,,ImportError}. Une @ref{40f,,ImportError} est utilisée par le chercheur dans `path' pour signaler que le point d'entrée n'a pas trouvé de @ref{105a,,chercheur d'entrée dans path} pour cette @ref{1f85,,entrée}. L'exception est ignorée et l'itération sur le @ref{1f77,,chemin des importations} se poursuit. Le point d'entrée doit attendre qu'on lui passe soit une chaîne de caractères soit une chaîne d'octets ; l'encodage des chaînes d'octets est à la main du point d'entrée (par exemple, ce peut être l'encodage du système de fichiers, de l'UTF-8 ou autre chose) et, si le point d'entrée n'arrive pas à décoder l'argument, il doit lever une @ref{40f,,ImportError}.

Si l'itération sur @ref{100d,,sys.path_hooks} se termine sans qu'aucun @ref{105a,,chercheur d'entrée dans path} ne soit renvoyé, alors la méthode @ref{ffa,,find_spec()} du chercheur dans `path' stocke @code{None} dans le @ref{5ce,,sys.path_importer_cache} (pour indiquer qu'il n'y a pas de chercheur pour cette entrée) et renvoie @code{None}, indiquant que ce @ref{1059,,chercheur dans les méta-chemins} n'a pas trouvé le module.

Si un @ref{105a,,chercheur d'entrée dans path} `est' renvoyé par un des @ref{1f87,,points d'entrée} de @ref{100d,,sys.path_hooks}, alors le protocole suivant est utilisé pour demander un spécificateur de module au chercheur, spécificateur qui sera utilisé pour charger le module.

Le répertoire de travail courant — noté sous la forme d'une chaîne de caractères vide — est géré d'une manière légèrement différente des autres entrées de @ref{3ab,,sys.path}. D'abord, si le répertoire de travail courant s'avère ne pas exister, aucune valeur n'est stockée dans @ref{5ce,,sys.path_importer_cache}. Ensuite, la valeur pour le répertoire de travail courant est vérifiée à chaque recherche de module. Enfin, le chemin utilisé pour @ref{5ce,,sys.path_importer_cache} et renvoyée par @ref{ffa,,importlib.machinery.PathFinder.find_spec()} est le nom réel du répertoire de travail courant et non pas la chaîne vide.

@node Protocole des chercheurs d'entrée dans path,,Chercheurs d'entrée dans path,Le chercheur dans path
@anchor{reference/import path-entry-finder-protocol}@anchor{1f88}
@subsubsection Protocole des chercheurs d'entrée dans `path'


Afin de gérer les importations de modules, l'initialisation des paquets et d'être capables de contribuer aux portions des paquets-espaces de nommage, les chercheurs d'entrée dans `path' doivent implémenter la méthode @ref{857,,find_spec()}.

La méthode @ref{857,,find_spec()} prend deux arguments : le nom complètement qualifié du module en cours d'importation et (optionnellement) le module cible. @code{find_spec()} renvoie un spécificateur de module pleinement peuplé. Ce spécificateur doit avoir son chargeur (attribut @code{loader}) défini, à une exception près.

Pour indiquer au mécanisme d'importation que le spécificateur représente une @ref{1f72,,portion} d'un espace de nommage, le chercheur d'entrée dans `path' définit l'attribut @code{submodule_search_locations} à une liste contenant la portion.


Modifié dans la version 3.4: la méthode @ref{857,,find_spec()} remplace @code{find_loader()} et @code{find_module()}, ces deux méthodes étant dorénavant obsolètes mais restant utilisées si @code{find_spec()} n'est pas définie.

Les vieux chercheurs d'entrée dans `path' peuvent implémenter une des deux méthodes obsolètes à la place de @code{find_spec()}. Ces méthodes sont toujours prises en compte dans le cadre de la compatibilité descendante. Cependant, si @code{find_spec()} est implémentée par le chercheur d'entrée dans `path', les méthodes historiques sont ignorées.

La méthode @code{find_loader()} prend un argument : le nom complètement qualifié du module en cours d'importation. @code{find_loader()} renvoie un couple dont le premier élément est le chargeur et le second est une @ref{1f72,,portion} d'espace de nommage.

À fin de compatibilité descendante avec d'autres implémentations du protocole d'importation, beaucoup de chercheurs d'entrée dans `path' gèrent aussi la méthode traditionnelle @code{find_module()} que l'on trouve dans les chercheurs dans les méta-chemins. Cependant, les méthodes @code{find_module()} des chercheurs d'entrée dans `path' ne sont jamais appelées avec un argument `path' (il est convenu qu'elles enregistrent les informations relatives au chemin approprié au moment de leur appel initial au point d'entrée).

La méthode @code{find_module()} des chercheurs d'entrée dans `path' est obsolète car elle n'autorise pas le chercheur d'entrée dans `path' à contribuer aux portions d'espaces de nommage des paquets-espaces de nommage. Si à la fois @code{find_loader()} et @code{find_module()} sont définies pour un chercheur d'entrée dans `path', le système d'importation utilise toujours @code{find_loader()} plutôt que @code{find_module()}.



Modifié dans la version 3.10: Les appels à @code{find_module()} et @code{find_loader()} par le système d'importation lèvent un @ref{4e4,,ImportWarning}.



Modifié dans la version 3.12: @code{find_module()} et @code{find_loader()} ont été supprimées.


@node Remplacement du système d'importation standard,Importations relatives au paquet,Le chercheur dans path,Le système d'importation
@anchor{reference/import replacing-the-standard-import-system}@anchor{1f89}
@subsection Remplacement du système d'importation standard


La manière la plus fiable de remplacer tout le système d'importation est de supprimer le contenu par défaut de @ref{d19,,sys.meta_path} et de le remplacer complètement par un chercheur dans les méta-chemins sur mesure.

S'il convient juste de modifier le comportement de l'instruction import sans affecter les autres API qui utilisent le système d'importation, alors remplacer la fonction native @ref{8c1,,__import__()} peut être suffisant. Cette technique peut aussi être employée au niveau d'un module pour n'altérer le comportement des importations qu'à l'intérieur de ce module.

Pour empêcher sélectivement l'importation de certains modules par un point d'entrée placé en tête dans le méta-chemin (plutôt que de désactiver complètement le système d'importation), il suffit de lever une @ref{b35,,ModuleNotFoundError} directement depuis @ref{853,,find_spec()} au lieu de renvoyer @code{None}. En effet, ce dernier indique que la recherche dans le méta-chemin peut continuer alors que la levée de l'exception termine immédiatement la recherche.

@node Importations relatives au paquet,Cas particulier de __main__,Remplacement du système d'importation standard,Le système d'importation
@anchor{reference/import package-relative-imports}@anchor{1f8a}@anchor{reference/import relativeimports}@anchor{1f8b}
@subsection Importations relatives au paquet


Les importations relatives commencent par une suite de points. Un seul point avant indique une importation relative, démarrant avec le paquet actuel. Deux points ou plus avant indiquent une importation relative au parent du paquet actuel, un niveau par point avant le premier. Par exemple, en ayant le contenu suivant :

@example
package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py
@end example

Dans @code{subpackage1/moduleX.py} ou @code{subpackage1/__init__.py}, les importations suivantes sont des importations relatives valides :

@example
from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo
@end example

Les importations absolues peuvent utiliser soit la syntaxe @code{import <>}, soit @code{from <> import <>}, mais les importations relatives doivent seulement utiliser la deuxième forme, la raison étant :

@example
import XXX.YYY.ZZZ
@end example

doit exposer @code{XXX.YYY.ZZZ} comme une expression utilisable, mais @code{.moduleY} n’est pas une expression valide.

@node Cas particulier de __main__,Références,Importations relatives au paquet,Le système d'importation
@anchor{reference/import import-dunder-main}@anchor{1f8c}@anchor{reference/import special-considerations-for-main}@anchor{1f8d}
@subsection Cas particulier de @code{__main__}


Le module @ref{1,,__main__} est un cas particulier pour le système d'importation de Python. Comme indiqué par @ref{1f7f,,ailleurs}, le module @code{__main__} est initialisé directement au démarrage de l'interpréteur, un peu comme @ref{d8,,sys} et @ref{12,,builtins}. Cependant, au contraire des deux cités précédemment, ce n'est pas vraiment un module natif. Effectivement, la manière dont est initialisé @code{__main__} dépend des drapeaux et options avec lesquels l'interpréteur est lancé.

@menu
* __main__.__spec__: __main__ __spec__. 

@end menu

@node __main__ __spec__,,,Cas particulier de __main__
@anchor{reference/import id5}@anchor{1f8e}@anchor{reference/import main-spec}@anchor{1f80}
@subsubsection @code{__main__.__spec__}


En fonction de la manière dont @ref{1,,__main__} est initialisé, @code{__main__.__spec__} est défini de manière conforme ou mis à @code{None}.

Quand Python est démarré avec l'option @ref{5cb,,-m}, @code{__spec__} est défini à la valeur du spécificateur du module ou paquet correspondant. Python peuple aussi @code{__spec__} quand le module @code{__main__} est chargé en tant que partie de l'exécution d'un répertoire, d'un fichier zip ou d'une entrée de @ref{3ab,,sys.path}.

Dans @ref{1cb5,,les autres cas}, @code{__main__.__spec__} est mis à @code{None}, car le code qui peuple @ref{1,,__main__} ne trouve pas de correspondance directe avec un module que l'on importe :


@itemize -

@item 
invite de commande interactive

@item 
l'option @ref{5ca,,-c}

@item 
lecture depuis l'entrée standard

@item 
lecture depuis un fichier de code source ou de `bytecode'
@end itemize

Notez que @code{__main__.__spec__} vaut toujours @code{None} dans le dernier cas, `même si' le fichier pourrait techniquement être importé directement en tant que module. Utilisez l'option @ref{5cb,,-m} si vous souhaitez disposer de métadonnées valides du module dans @ref{1,,__main__}.

Notez aussi que même quand @code{__main__} correspond à un module importable et que @code{__main__.__spec__} est défini en conséquence, ils seront toujours considérés comme des modules `distincts'. Cela est dû au fait que le bloc encadré par @code{if __name__ == "__main__":} ne s'exécute que quand le module est utilisé pour peupler l'espace de nommage de @code{__main__}, et pas durant une importation normale.

@node Références,,Cas particulier de __main__,Le système d'importation
@anchor{reference/import references}@anchor{1f8f}
@subsection Références


Le mécanisme d'importation a considérablement évolué depuis les débuts de Python. La spécification des paquets@footnote{https://www.python.org/doc/essays/packages/} originale est toujours disponible, bien que quelques détails ont changé depuis l'écriture de ce document.

La spécification originale de @ref{d19,,sys.meta_path} se trouve dans la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}. La 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} contient des extensions significatives.

La 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} a introduit les @ref{1bf6,,paquets-espaces de nommage} pour Python 3.3. La 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/} a aussi introduit le protocole @code{find_loader()} comme une alternative à @code{find_module()}.

La 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} décrit l'ajout de l'attribut @code{__package__} pour les importations relatives explicites dans les modules principaux.

La 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} a introduit les importations absolues et les importations relatives explicites. Elle a aussi proposé @code{__name__} pour la sémantique que la 
@geindex Python Enhancement Proposals; PEP 366
PEP 366@footnote{https://peps.python.org/pep-0366/} attribuait à @code{__package__}.

@geindex Python Enhancement Proposals; PEP 338
PEP 338@footnote{https://peps.python.org/pep-0338/} définit l'exécution de modules en tant que scripts.

@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/} ajoute l'encapsulation dans les objets spécificateurs de l'état des importations, module par module. Elle reporte aussi la majorité des responsabilités des chargeurs vers le mécanisme d'importation. Ces changements permettent de supprimer plusieurs API dans le système d'importation et d'ajouter de nouvelles méthodes aux chercheurs et chargeurs.

@subsubheading Notes


@node Expressions,Les instructions simples,Le système d'importation,La référence du langage Python
@anchor{reference/expressions doc}@anchor{1f90}@anchor{reference/expressions expressions}@anchor{1f91}@anchor{reference/expressions id1}@anchor{1f92}
@section Expressions


@geindex expression
@geindex BNF

Ce chapitre explique la signification des éléments des expressions en Python.

`Notes sur la syntaxe :' dans ce chapitre et le suivant, nous utilisons la notation BNF étendue pour décrire la syntaxe, pas l'analyse lexicale. Quand une règle de syntaxe est de la forme

@example
@anchor{reference/expressions grammar-token-python-grammar-name}@anchor{1f93}name ::= othername
@end example

et qu'aucune sémantique n'est donnée, la sémantique de @code{name} est la même que celle de @code{othername}.

@menu
* Conversions arithmétiques:: 
* Atomes:: 
* Primaires:: 
* Expression await:: 
* L'opérateur puissance:: 
* Arithmétique unaire et opérations sur les bits:: 
* Opérations arithmétiques binaires:: 
* Opérations de décalage:: 
* Opérations binaires bit à bit:: 
* Comparaisons:: 
* Opérations booléennes:: 
* Expressions d'affectation:: 
* Expressions conditionnelles:: 
* Expressions lambda:: 
* Listes d'expressions:: 
* Ordre d'évaluation:: 
* Priorités des opérateurs:: 

@end menu

@node Conversions arithmétiques,Atomes,,Expressions
@anchor{reference/expressions arithmetic-conversions}@anchor{1f94}@anchor{reference/expressions conversions}@anchor{1f95}
@subsection Conversions arithmétiques


@geindex arithmetic;conversion

Quand la description d'un opérateur arithmétique ci-dessous utilise la phrase « les arguments numériques sont convertis vers un type commun », cela signifie que l'implémentation de l'opérateur fonctionne de la manière suivante pour les types natifs :


@itemize *

@item 
Si l'un des deux arguments est du type nombre complexe, l'autre est converti en nombre complexe ;

@item 
otherwise, if either argument is a floating-point number, the other is
converted to floating point;

@item 
sinon, les deux doivent être des entiers et aucune conversion n'est nécessaire.
@end itemize

Des règles supplémentaires s'appliquent pour certains opérateurs (par exemple, une chaîne comme opérande de gauche pour l'opérateur @code{%}). Les extensions doivent définir leurs propres règles de conversion.

@node Atomes,Primaires,Conversions arithmétiques,Expressions
@anchor{reference/expressions atoms}@anchor{1f96}@anchor{reference/expressions id2}@anchor{1f97}
@subsection Atomes


@geindex atom

Les atomes sont les éléments de base des expressions. Les atomes les plus simples sont les identifiants et les littéraux. Les expressions entre parenthèses, crochets ou accolades sont aussi classées syntaxiquement comme des atomes. La syntaxe pour les atomes est :

@example
@anchor{reference/expressions grammar-token-python-grammar-atom}@anchor{1f98}atom      ::= identifier | literal | enclosure
@anchor{reference/expressions grammar-token-python-grammar-enclosure}@anchor{1f99}enclosure ::= parenth_form | list_display | dict_display | set_display
              | generator_expression | yield_atom
@end example

@menu
* Identifiants (noms): Identifiants noms. 
* Littéraux: Littéraux<2>. 
* Formes parenthésées:: 
* Agencements des listes@comma{} ensembles et dictionnaires: Agencements des listes ensembles et dictionnaires. 
* Agencements de listes:: 
* Agencements d'ensembles:: 
* Agencements de dictionnaires:: 
* Expressions génératrices:: 
* Expressions yield:: 

@end menu

@node Identifiants noms,Littéraux<2>,,Atomes
@anchor{reference/expressions atom-identifiers}@anchor{1e26}@anchor{reference/expressions identifiers-names}@anchor{1f9a}
@subsubsection Identifiants (noms)


@geindex name
@geindex identifier

Un identifiant qui apparaît en tant qu'atome est un nom. Lisez la section @ref{1e1a,,Identifiants et mots-clés} pour la définition lexicale et la section @ref{1e7d,,Noms et liaisons} pour la documentation sur les noms et les liaisons afférentes.

@geindex exception;NameError

Quand un nom est lié à un objet, l'évaluation de l'atome produit cet objet. Quand le nom n'est pas lié, toute tentative de l'évaluer lève une exception @ref{428,,NameError}.

@geindex name;mangling
@geindex private;names
@anchor{reference/expressions private-name-mangling}@anchor{1c48}
@menu
* Private name mangling:: 

@end menu

@node Private name mangling,,,Identifiants noms
@anchor{reference/expressions id3}@anchor{1f9b}
@subsubsection Private name mangling


When an identifier that textually occurs in a class definition begins with two
or more underscore characters and does not end in two or more underscores, it
is considered a `private name' of that class.


@subsubheading Voir aussi


The @ref{12b5,,class specifications}.


More precisely, private names are transformed to a longer form before code is
generated for them.  If the transformed name is longer than 255 characters,
implementation-defined truncation may happen.

The transformation is independent of the syntactical context in which the
identifier is used but only the following private identifiers are mangled:


@itemize -

@item 
Any name used as the name of a variable that is assigned or read or any
name of an attribute being accessed.

The @ref{104f,,__name__} attribute of nested functions, classes, and
type aliases is however not mangled.

@item 
The name of imported modules, e.g., @code{__spam} in @code{import __spam}.
If the module is part of a package (i.e., its name contains a dot),
the name is `not' mangled, e.g., the @code{__foo} in @code{import __foo.bar}
is not mangled.

@item 
The name of an imported member, e.g., @code{__f} in @code{from spam import __f}.
@end itemize

The transformation rule is defined as follows:


@itemize -

@item 
The class name, with leading underscores removed and a single leading
underscore inserted, is inserted in front of the identifier, e.g., the
identifier @code{__spam} occurring in a class named @code{Foo}, @code{_Foo} or
@code{__Foo} is transformed to @code{_Foo__spam}.

@item 
If the class name consists only of underscores, the transformation is the
identity, e.g., the identifier @code{__spam} occurring in a class named @code{_}
or @code{__} is left as is.
@end itemize

@node Littéraux<2>,Formes parenthésées,Identifiants noms,Atomes
@anchor{reference/expressions atom-literals}@anchor{1f9c}@anchor{reference/expressions literals}@anchor{1f9d}
@subsubsection Littéraux


@geindex literal

Python gère les littéraux de chaînes de caractères, de chaînes d'octets et de plusieurs autres types numériques :

@example
@anchor{reference/expressions grammar-token-python-grammar-literal}@anchor{1f9e}literal ::= stringliteral | bytesliteral
            | integer | floatnumber | imagnumber
@end example

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
may be approximated in the case of floating-point and imaginary (complex)
literals.  See section @ref{1e28,,Littéraux} for details.

@geindex immutable;data;type
@geindex immutable;object

Tous les littéraux sont de types immuables et donc l'identifiant de l'objet est moins important que sa valeur. Des évaluations multiples de littéraux avec la même valeur (soit la même occurrence dans le texte du programme, soit une autre occurrence) résultent dans le même objet ou un objet différent avec la même valeur.

@node Formes parenthésées,Agencements des listes ensembles et dictionnaires,Littéraux<2>,Atomes
@anchor{reference/expressions parenthesized}@anchor{1f9f}@anchor{reference/expressions parenthesized-forms}@anchor{1fa0}
@subsubsection Formes parenthésées


@geindex parenthesized form
@geindex () (parentheses);tuple display

Une forme parenthésée est une liste d'expressions (cette liste est en fait optionnelle) placée à l'intérieur de parenthèses :

@example
@anchor{reference/expressions grammar-token-python-grammar-parenth_form}@anchor{1fa1}parenth_form ::= "(" [starred_expression] ")"
@end example

Une liste d'expressions entre parenthèses produit ce que la liste de ces expressions produirait : si la liste contient au moins une virgule, elle produit un `n'-uplet (type `n'-uplet) ; sinon, elle produit l'expression elle-même (qui constitue donc elle-même la liste d'expressions).

@geindex empty;tuple

Une paire de parenthèses vide produit un objet `n'-uplet vide. Comme les n-uplets sont immuables, la même règle que pour les littéraux s'applique (c'est-à-dire que deux occurrences du `n'-uplet vide peuvent, ou pas, produire le même objet).

@geindex comma
@geindex @comma{} (comma)

Notez que les `n'-uplets ne sont pas créés par les parenthèses mais par l'utilisation de la virgule. L'exception est le `n'-uplet vide, pour lequel les parenthèses `sont requises' (autoriser que « rien » ne soit pas parenthésé dans les expressions aurait généré des ambigüités et aurait permis à certaines coquilles de passer inaperçu).

@node Agencements des listes ensembles et dictionnaires,Agencements de listes,Formes parenthésées,Atomes
@anchor{reference/expressions comprehensions}@anchor{5ba}@anchor{reference/expressions displays-for-lists-sets-and-dictionaries}@anchor{1fa2}
@subsubsection Agencements des listes, ensembles et dictionnaires


@geindex comprehensions

Pour construire une liste, un ensemble ou un dictionnaire, Python fournit des syntaxes spéciales dites « agencements » (`displays' en anglais), chaque agencement comportant deux variantes :


@itemize *

@item 
soit le contenu du conteneur est listé explicitement,

@item 
soit il est calculé à l'aide de la combinaison d'une boucle et d'instructions de filtrage, appelée une `compréhension' (dans le sens de ce qui sert à définir un concept, par opposition à `extension').
@end itemize

@geindex for;in comprehensions
@geindex if;in comprehensions
@geindex async for;in comprehensions

Les compréhensions sont constituées des éléments de syntaxe communs suivants :

@example
@anchor{reference/expressions grammar-token-python-grammar-comprehension}@anchor{1fa3}comprehension ::= assignment_expression comp_for
@anchor{reference/expressions grammar-token-python-grammar-comp_for}@anchor{1fa4}comp_for      ::= ["async"] "for" target_list "in" or_test [comp_iter]
@anchor{reference/expressions grammar-token-python-grammar-comp_iter}@anchor{1fa5}comp_iter     ::= comp_for | comp_if
@anchor{reference/expressions grammar-token-python-grammar-comp_if}@anchor{1fa6}comp_if       ::= "if" or_test [comp_iter]
@end example

Une compréhension est constituée par une seule expression suivie par au moins une clause @code{for} et zéro ou plus clauses @code{for} ou @code{if}. Dans ce cas, les éléments du nouveau conteneur sont ceux qui auraient été produits si l'on avait considéré toutes les clauses @code{for} ou @code{if} comme des blocs, imbriqués de la gauche vers la droite, et évalué l'expression pour produire un élément à chaque fois que le bloc le plus imbriqué était atteint.

Cependant, à part l'expression de l'itérable dans la clause @code{for} la plus à gauche, la compréhension est exécutée dans une portée séparée, implicitement imbriquée. Ceci assure que les noms assignés dans la liste cible ne « fuient » pas en dehors de cette portée.

L'expression de l'itérable dans la clause @code{for} la plus à gauche est évaluée directement dans la portée englobante puis passée en tant qu'argument à la portée implicite imbriquée. Les clauses @code{for} suivantes et les filtres conditionnels de la clause @code{for} la plus à gauche ne peuvent pas être évalués dans la portée englobante, car ils peuvent dépendre de valeurs obtenues à partir de l'itérable le plus à gauche. Par exemple : @code{[x*y for x in range(10) for y in range(x, x+10)]}.

Pour assurer que le résultat de la compréhension soit un conteneur du type approprié, les expressions @code{yield} et @code{yield from} sont interdites dans la portée implicite imbriquée.

@geindex await;in comprehensions

Since Python 3.6, in an @ref{5bb,,async def} function, an @code{async for}
clause may be used to iterate over a @ref{1a9,,asynchronous iterator}.
A comprehension in an @code{async def} function may consist of either a
@code{for} or @code{async for} clause following the leading
expression, may contain additional @code{for} or @code{async for}
clauses, and may also use @ref{1b7,,await} expressions.

If a comprehension contains @code{async for} clauses, or if it contains
@code{await} expressions or other asynchronous comprehensions anywhere except
the iterable expression in the leftmost @code{for} clause, it is called an
`asynchronous comprehension'. An asynchronous comprehension may suspend the
execution of the coroutine function in which it appears.
See also 
@geindex Python Enhancement Proposals; PEP 530
PEP 530@footnote{https://peps.python.org/pep-0530/}.


Ajouté dans la version 3.6: Les compréhensions asynchrones ont été introduites.



Modifié dans la version 3.8: @code{yield} et @code{yield from} sont interdites dans la portée implicite imbriquée.



Modifié dans la version 3.11: les compréhensions asynchrones sont maintenant autorisées dans les compréhensions des fonctions asynchrones. Les compréhensions englobantes deviennent implicitement asynchrones.


@node Agencements de listes,Agencements d'ensembles,Agencements des listes ensembles et dictionnaires,Atomes
@anchor{reference/expressions list-displays}@anchor{1fa7}@anchor{reference/expressions lists}@anchor{1fa8}
@subsubsection Agencements de listes


@geindex list;display
@geindex list;comprehensions
@geindex empty;list
@geindex object;list
@geindex [] (square brackets);list expression
@geindex @comma{} (comma);expression list

Un agencement de liste est une suite (possiblement vide) d'expressions à l'intérieur de crochets :

@example
@anchor{reference/expressions grammar-token-python-grammar-list_display}@anchor{1fa9}list_display ::= "[" [flexible_expression_list | comprehension] "]"
@end example

Un agencement de liste produit un nouvel objet liste, dont le contenu est spécifié soit par une liste d'expression soit par une compréhension. Quand une liste d'expressions (dont les éléments sont séparés par des virgules) est fournie, ces éléments sont évalués de la gauche vers la droite et placés dans l'objet liste, dans cet ordre. Quand c'est une compréhension qui est fournie, la liste est construite à partir des éléments produits par la compréhension.

@node Agencements d'ensembles,Agencements de dictionnaires,Agencements de listes,Atomes
@anchor{reference/expressions set}@anchor{1faa}@anchor{reference/expressions set-displays}@anchor{1fab}
@subsubsection Agencements d'ensembles


@geindex set;display
@geindex set;comprehensions
@geindex object;set
@geindex @{@} (curly brackets);set expression
@geindex @comma{} (comma);expression list

Un agencement d'ensemble (type `set') est délimité par des accolades et se distingue de l'agencement d'un dictionnaire par le fait qu'il n'y a pas de « deux points » @code{:} pour séparer les clés et les valeurs :

@example
@anchor{reference/expressions grammar-token-python-grammar-set_display}@anchor{1fac}set_display ::= "@{" (flexible_expression_list | comprehension) "@}"
@end example

Un agencement d'ensemble produit un nouvel objet ensemble mutable, le contenu étant spécifié soit par une séquence d'expression, soit par une compréhension. Quand une liste (dont les éléments sont séparés par des virgules) est fournie, ses éléments sont évalués de la gauche vers la droite et ajoutés à l'objet ensemble. Quand une compréhension est fournie, l'ensemble est construit à partir des éléments produits par la compréhension.

Un ensemble vide ne peut pas être construit par @code{@{@}} ; cette écriture construit un dictionnaire vide.

@node Agencements de dictionnaires,Expressions génératrices,Agencements d'ensembles,Atomes
@anchor{reference/expressions dict}@anchor{d6c}@anchor{reference/expressions dictionary-displays}@anchor{1fad}
@subsubsection Agencements de dictionnaires


@geindex dictionary;display
@geindex dictionary;comprehensions
@geindex key
@geindex value
@geindex key/value pair
@geindex object;dictionary
@geindex @{@} (curly brackets);dictionary expression
@geindex ; (colon);in dictionary expressions
@geindex @comma{} (comma);in dictionary displays

Un agencement de dictionnaire est une série (possiblement vide) de couples clés-valeurs entourée par des accolades :

@example
@anchor{reference/expressions grammar-token-python-grammar-dict_display}@anchor{1fae}dict_display       ::= "@{" [dict_item_list | dict_comprehension] "@}"
@anchor{reference/expressions grammar-token-python-grammar-dict_item_list}@anchor{1faf}dict_item_list     ::= dict_item ("," dict_item)* [","]
@anchor{reference/expressions grammar-token-python-grammar-dict_item}@anchor{1fb0}dict_item          ::= expression ":" expression | "**" or_expr
@anchor{reference/expressions grammar-token-python-grammar-dict_comprehension}@anchor{1fb1}dict_comprehension ::= expression ":" expression comp_for
@end example

Un agencement de dictionnaire produit un nouvel objet dictionnaire.

Si une séquence (dont les éléments sont séparés par des virgules) de couples clés-valeurs est fournie, les couples sont évalués de la gauche vers la droite pour définir les entrées du dictionnaire : chaque objet clé est utilisé comme clé dans le dictionnaire pour stocker la valeur correspondante. Cela signifie que vous pouvez spécifier la même clé plusieurs fois dans la liste des couples clés-valeurs et, dans ce cas, la valeur finalement stockée dans le dictionnaire est la dernière donnée.

@geindex unpacking;dictionary
@geindex **;in dictionary displays

Une double astérisque @code{**} demande de `dépaqueter le dictionnaire'. L'opérande doit être un @ref{1199,,tableau de correspondances}. Chaque élément du tableau de correspondances est ajouté au nouveau dictionnaire. Les valeurs les plus récentes remplacent les valeurs déjà définies par des couples clés-valeurs antérieurs ou par d'autres dépaquetages de dictionnaires antérieurs.


Ajouté dans la version 3.5: le dépaquetage peut se faire vers un agencement de dictionnaire, proposé à l'origine par la 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/}.


Une compréhension de dictionnaire, au contraire des compréhensions de listes ou d'ensembles, requiert deux expressions séparées par une virgule et suivies par les clauses usuelles "for" et "if". Quand la compréhension est exécutée, les éléments clés-valeurs sont insérés dans le nouveau dictionnaire dans l'ordre dans lequel ils sont produits.

@geindex immutable;object
@geindex hashable

Les restrictions relatives aux types des clés sont données dans la section @ref{1e6a,,Hiérarchie des types standards} (pour résumer, le type de la clé doit être @ref{5fb,,hachable}, ce qui exclut tous les objets mutables). Les collisions entre les clés dupliquées ne sont pas détectées ; la dernière valeur (celle qui apparaît le plus à droite dans l'agencement) stockée prévaut pour une clé donnée.


Modifié dans la version 3.8: Avant Python 3.8, dans les compréhensions de dictionnaires, l'ordre d'évaluation entre les clés et les valeurs n'était pas bien défini. Dans CPython, la valeur était évaluée avant la clé. À partir de la version 3.8, la clé est évaluée avant la valeur, comme proposé par la 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/}.


@node Expressions génératrices,Expressions yield,Agencements de dictionnaires,Atomes
@anchor{reference/expressions generator-expressions}@anchor{1fb2}@anchor{reference/expressions genexpr}@anchor{1fb3}
@subsubsection Expressions génératrices


@geindex generator;expression
@geindex object;generator
@geindex () (parentheses);generator expression

Une expression génératrice est une notation concise pour un générateur, entourée de parenthèses :

@example
@anchor{reference/expressions grammar-token-python-grammar-generator_expression}@anchor{1fb4}generator_expression ::= "(" expression comp_for ")"
@end example

Une expression génératrice produit un nouvel objet générateur. Sa syntaxe est la même que celle des compréhensions, sauf qu'elle est entourée de parenthèses au lieu de crochets ou d'accolades.

Les variables utilisées dans une expression génératrice sont évaluées paresseusement, au moment où la méthode @ref{1c52,,__next__()} de l'objet générateur est appelée (de la même manière que pour les générateurs classiques). Cependant, l'expression de l'itérable dans la clause @code{for} la plus à gauche est immédiatement évaluée, de manière à ce qu'une erreur dans cette partie soit signalée à l'endroit où l'expression génératrice est définie plutôt qu'à l'endroit où la première valeur est récupérée. Les clauses @code{for} suivantes ne peuvent pas être évaluées dans la portée implicite imbriquée car elles peuvent dépendre de valeurs obtenues à partir de boucles @code{for} plus à gauche. Par exemple, @code{(x*y for x in range(10) for y in range(x, x+10))}.

Les parenthèses peuvent être omises pour les appels qui ne possèdent qu'un seul argument. Voir la section @ref{d6a,,Appels} pour les détails.

Pour éviter d'interférer avec l'opération attendue de l'expression génératrice elle-même, les expressions @code{yield} et @code{yield from} sont interdites dans les générateurs définis de manière implicite.

Si une expression génératrice contient  une ou des expressions @code{async for} ou @ref{1b7,,await}, elle est appelée `expression génératrice asynchrone'. Une expression génératrice asynchrone produit un nouvel objet générateur asynchrone qui est un itérateur asynchrone (voir @ref{d67,,Itérateurs asynchrones}).


Ajouté dans la version 3.6: les expressions génératrices asynchrones ont été introduites.



Modifié dans la version 3.7: Avant Python 3.7, les expressions génératrices asynchrones ne pouvaient apparaître que dans les coroutines @ref{5bb,,async def}. À partir de la version 3.7, toute fonction peut utiliser des expressions génératrices asynchrones.



Modifié dans la version 3.8: @code{yield} et @code{yield from} sont interdites dans la portée implicite imbriquée.


@node Expressions yield,,Expressions génératrices,Atomes
@anchor{reference/expressions yield-expressions}@anchor{1fb5}@anchor{reference/expressions yieldexpr}@anchor{1fb6}
@subsubsection Expressions @code{yield}


@geindex keyword;yield
@geindex keyword;from
@geindex yield;expression
@geindex generator;function

@example
@anchor{reference/expressions grammar-token-python-grammar-yield_atom}@anchor{1fb7}yield_atom       ::= "(" yield_expression ")"
@anchor{reference/expressions grammar-token-python-grammar-yield_from}@anchor{1fb8}yield_from       ::= "yield" "from" expression
@anchor{reference/expressions grammar-token-python-grammar-yield_expression}@anchor{1fb9}yield_expression ::= "yield" yield_list | yield_from
@end example

Une expression @code{yield} est utilisée pour définir une @ref{104a,,fonction génératrice} ou une @ref{1fba,,fonction génératrice asynchrone} et ne peut donc être utilisée que dans le corps de la définition d'une fonction. L'utilisation d'une expression @code{yield} dans le corps d'une fonction entraîne que cette fonction devient une fonction génératrice et son utilisation dans le corps d'une fonction @ref{5bb,,async def} entraine que cette fonction coroutine devient une fonction génératrice asynchrone. Par exemple :

@example
def gen():  # defines a generator function
    yield 123

async def agen(): # defines an asynchronous generator function
    yield 123
@end example

En raison des effets de bords sur la portée contenant, les expressions @code{yield} ne sont pas autorisées dans la portée implicite utilisée dans l'implémentation des compréhensions et des expressions génératrices.


Modifié dans la version 3.8: Les expressions @code{yield} sont interdites dans la portée implicite imbriquée utilisée dans l'implémentation des compréhensions et des expressions génératrices.


Les fonctions génératrices sont décrites plus loin alors que les fonctions générateurs asynchrones sont décrites séparément dans la section @ref{1fbb,,Fonctions génératrices asynchrones}.

When a generator function is called, it returns an iterator known as a
generator.  That generator then controls the execution of the generator
function.  The execution starts when one of the generator's methods is called.
At that time, the execution proceeds to the first yield expression, where it is
suspended again, returning the value of @ref{1fbc,,yield_list}
to the generator's caller,
or @code{None} if @ref{1fbc,,yield_list} is omitted.
By suspended, we mean that all local state is
retained, including the current bindings of local variables, the instruction
pointer, the internal evaluation stack, and the state of any exception handling.
When the execution is resumed by calling one of the generator's methods, the
function can proceed exactly as if the yield expression were just another
external call.  The value of the yield expression after resuming depends on the
method which resumed the execution.  If @ref{1c52,,__next__()} is used
(typically via either a @ref{2e6,,for} or the @ref{7c2,,next()} builtin) then the
result is @ref{660,,None}.  Otherwise, if @ref{1f4f,,send()} is used, then
the result will be the value passed in to that method.

@geindex coroutine

Tout ceci rend les fonctions génératrices très similaires aux coroutines : elles produisent plusieurs objets `via' des expressions @code{yield}, elles possèdent plus qu'un seul point d'entrée et leur exécution peut être suspendue. La seule différence est qu'une fonction génératrice ne peut pas contrôler où l'exécution doit se poursuivre après une instruction @code{yield} ; ce contrôle est toujours du ressort de l'appelant au générateur.

Les expressions @code{yield} sont autorisées partout dans un bloc @ref{6d3,,try}. Si l'exécution du générateur ne reprend pas avant qu'il ne soit finalisé (parce que son compteur de référence est tombé à zéro ou parce qu'il est nettoyé par le ramasse-miettes), la méthode @ref{167d,,close()} du générateur-itérateur est appelée, ce qui permet l'exécution de toutes les clauses @ref{9b8,,finally} en attente.

@geindex from;yield from expression

L'expression passée à @code{yield from <expr>} doit être un itérateur. Toutes les valeurs produites par cet itérateur sont directement passées à l'appelant des méthodes du générateur courant. Toute valeur passée par @ref{1f4f,,send()} ou toute exception passée par @ref{4e2,,throw()} est transmise à l'itérateur sous-jacent s'il possède les méthodes appropriées. Si ce n'est pas le cas, alors @ref{1f4f,,send()} lève une @ref{343,,AttributeError} ou une @ref{522,,TypeError}, alors que @ref{4e2,,throw()} ne fait que propager l'exception immédiatement.

Quand l'itérateur sous-jacent a terminé, l'attribut @ref{1f4c,,value} de l'instance @ref{be8,,StopIteration} qui a été levée devient la valeur produite par l'expression @code{yield}. Elle peut être définie explicitement quand vous levez @ref{be8,,StopIteration} ou automatiquement que le sous-itérateur est un générateur (en renvoyant une valeur par le sous-générateur).


Modifié dans la version 3.3: @code{yield from <expr>} a été ajoutée pour déléguer le contrôle du flot d'exécution à un sous-itérateur.


Les parenthèses peuvent être omises quand l'expression @code{yield} est la seule expression à droite de l'instruction de l'instruction d'affectation.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 255

@item PEP 255@footnote{https://peps.python.org/pep-0255/} : générateurs simples

La proposition d'ajouter à Python des générateurs et l'instruction @ref{9bb,,yield}.

@geindex Python Enhancement Proposals; PEP 342

@item PEP 342@footnote{https://peps.python.org/pep-0342/} -- Coroutines `via' des générateurs améliorés

Proposition d'améliorer l'API et la syntaxe des générateurs, de manière à pouvoir les utiliser comme de simples coroutines.

@geindex Python Enhancement Proposals; PEP 380

@item PEP 380@footnote{https://peps.python.org/pep-0380/} -- Syntaxe pour déléguer à un sous-générateur

Proposition d'introduire la syntaxe @ref{1fb8,,yield_from}, de manière à déléguer facilement l'exécution à un sous-générateur.

@geindex Python Enhancement Proposals; PEP 525

@item PEP 525@footnote{https://peps.python.org/pep-0525/} : Générateurs asynchrones

La proposition qui a amélioré la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} en ajoutant des capacités de générateur pour les coroutines.
@end table


@geindex object;generator

@menu
* Méthodes des générateurs-itérateurs:: 
* Exemples:: 
* Fonctions génératrices asynchrones:: 
* Méthodes des générateurs-itérateurs asynchrones:: 

@end menu

@node Méthodes des générateurs-itérateurs,Exemples,,Expressions yield
@anchor{reference/expressions generator-iterator-methods}@anchor{1fbd}@anchor{reference/expressions generator-methods}@anchor{1f4d}
@subsubsection Méthodes des générateurs-itérateurs


Cette sous-section décrit les méthodes des générateurs-itérateurs. Elles peuvent être utilisées pour contrôler l'exécution des fonctions génératrices.

Notez que l'appel à une méthode ci-dessous d'un générateur alors que le générateur est déjà en cours d'exécution lève une exception @ref{1ff,,ValueError}.

@geindex exception;StopIteration

@geindex __next__() (méthode generator)
@anchor{reference/expressions generator __next__}@anchor{1c52}
@deffn {Méthode} generator.__next__ ()

Starts the execution of a generator function or resumes it at the last
executed yield expression.  When a generator function is resumed with a
@ref{1c52,,__next__()} method, the current yield expression always
evaluates to @ref{660,,None}.  The execution then continues to the next yield
expression, where the generator is suspended again, and the value of the
@ref{1fbc,,yield_list} is returned to @ref{1c52,,__next__()}'s
caller.  If the generator exits without yielding another value, a
@ref{be8,,StopIteration} exception is raised.

Cette méthode est normalement appelée implicitement, par exemple par une boucle @ref{2e6,,for} ou par la fonction native @ref{7c2,,next()}.
@end deffn

@geindex send() (méthode generator)
@anchor{reference/expressions generator send}@anchor{1f4f}
@deffn {Méthode} generator.send (value)

Reprend l'exécution et « envoie » une valeur à la fonction génératrice. L'argument `value' devient le résultat de l'expression @code{yield} courante. La méthode @ref{1f4f,,send()} renvoie la valeur suivante produite par le générateur ou lève @ref{be8,,StopIteration} si le générateur termine sans produire de nouvelle valeur. Quand @ref{1f4f,,send()} est utilisée pour démarrer le générateur, elle doit avoir @ref{660,,None} comme argument, car il n'y a aucune expression @code{yield} qui peut recevoir la valeur.
@end deffn

@geindex throw() (méthode generator)
@anchor{reference/expressions generator throw}@anchor{4e2}
@deffn {Méthode} generator.throw (value)

@deffnx {Méthode} generator.throw (type[, value[, traceback]])

Lève une exception à l'endroit où le générateur est en pause et renvoie la valeur suivante produite par la fonction génératrice. Si le générateur termine sans produire de nouvelle valeur, une exception @ref{be8,,StopIteration} est levée. Si la fonction génératrice ne gère pas l'exception passée ou lève une autre exception, alors cette exception est propagée vers l'appelant.

Dans son utilisation typique, elle est appelée avec une seule instance d'exception, de façon similaire à l'utilisation du mot-clé @ref{5d7,,raise}.

Cependant, pour assurer la rétrocompatibilité, la deuxième signature est prise en charge, suivant une convention des anciennes versions de Python. L'argument `type' doit être une classe d'exception et `value' doit être une instance d'exception. Si `value' n'est pas fournie, le constructeur de `type' est appelé pour obtenir une instance. Si `traceback' est fournie, elle est liée sur l'exception, sinon tout attribut @ref{12a4,,__traceback__} existant stocké dans `value' est possiblement effacé.


Modifié dans la version 3.12: The second signature (type[, value[, traceback]]) is deprecated and
may be removed in a future version of Python.

@end deffn

@geindex exception;GeneratorExit

@geindex close() (méthode generator)
@anchor{reference/expressions generator close}@anchor{167d}
@deffn {Méthode} generator.close ()

Raises a @ref{137e,,GeneratorExit} at the point where the generator function was
paused.  If the generator function catches the exception and returns a
value, this value is returned from @ref{167d,,close()}.  If the generator function
is already closed, or raises @ref{137e,,GeneratorExit} (by not catching the
exception), @ref{167d,,close()} returns @ref{660,,None}.  If the generator yields a
value, a @ref{193,,RuntimeError} is raised.  If the generator raises any other
exception, it is propagated to the caller.  If the generator has already
exited due to an exception or normal exit, @ref{167d,,close()} returns
@ref{660,,None} and has no other effect.


Modifié dans la version 3.13: If a generator returns a value upon being closed, the value is returned
by @ref{167d,,close()}.

@end deffn

@geindex yield;examples

@node Exemples,Fonctions génératrices asynchrones,Méthodes des générateurs-itérateurs,Expressions yield
@anchor{reference/expressions examples}@anchor{1fbe}
@subsubsection Exemples


Voici un exemple simple qui montre le comportement des générateurs et des fonctions génératrices :

@example
>>> def echo(value=None):
...     print("Execution starts when 'next()' is called for the first time.")
...     try:
...         while True:
...             try:
...                 value = (yield value)
...             except Exception as e:
...                 value = e
...     finally:
...         print("Don't forget to clean up when 'close()' is called.")
...
>>> generator = echo(1)
>>> print(next(generator))
Execution starts when 'next()' is called for the first time.
1
>>> print(next(generator))
None
>>> print(generator.send(2))
2
>>> generator.throw(TypeError, "spam")
TypeError('spam',)
>>> generator.close()
Don't forget to clean up when 'close()' is called.
@end example

Pour des exemples d'utilisation de @code{yield from}, lisez la @ref{1022,,PEP 380; Syntax for Delegating to a Subgenerator} dans « Les nouveautés de Python ».

@node Fonctions génératrices asynchrones,Méthodes des générateurs-itérateurs asynchrones,Exemples,Expressions yield
@anchor{reference/expressions asynchronous-generator-functions}@anchor{1fbb}@anchor{reference/expressions id4}@anchor{1fbf}
@subsubsection Fonctions génératrices asynchrones


La présence d'une expression `yield' dans une fonction ou une méthode définie en utilisant @ref{5bb,,async def} transforme cette fonction en fonction @ref{1fba,,générateur asynchrone}.

Quand une fonction génératrice asynchrone est appelée, elle renvoie un itérateur asynchrone, autrement appelé objet générateur asynchrone. Cet objet contrôle l'exécution de la fonction génératrice. Un objet générateur asynchrone est typiquement utilisé dans une instruction @ref{a99,,async for} à l'intérieur d'une fonction coroutine de la même manière qu'un objet générateur serait utilisé dans une instruction @ref{2e6,,for}.

Calling one of the asynchronous generator's methods returns an @ref{1ab,,awaitable}
object, and the execution starts when this object is awaited on. At that time,
the execution proceeds to the first yield expression, where it is suspended
again, returning the value of @ref{1fbc,,yield_list} to the
awaiting coroutine. As with a generator, suspension means that all local state
is retained, including the current bindings of local variables, the instruction
pointer, the internal evaluation stack, and the state of any exception handling.
When the execution is resumed by awaiting on the next object returned by the
asynchronous generator's methods, the function can proceed exactly as if the
yield expression were just another external call. The value of the yield
expression after resuming depends on the method which resumed the execution.  If
@ref{1fc0,,__anext__()} is used then the result is @ref{660,,None}. Otherwise, if
@ref{8c6,,asend()} is used, then the result will be the value passed in to that
method.

Si un générateur asynchrone se termine précipitamment en raison d'un @ref{a97,,break}, de l'annulation de la tâche de l'appelant ou d'une exception, le code de nettoyage du générateur asynchrone est exécuté et lève possiblement des exceptions, accède à des variables de contexte dans un contexte inattendu — peut-être parce que la tâche de laquelle il dépend est finie, ou pendant la fermeture de la boucle d'événements quand le point d'entrée du ramasse-miettes a déjà été appelé. Afin d'éviter cette situation, l'appelant doit explicitement fermer le générateur asynchrone en appelant la méthode @ref{8c5,,aclose()} pour « finaliser » le générateur et le détacher de la boucle d'événements.

Dans une fonction génératrice asynchrone, les expressions @code{yield} sont autorisées n'importe où dans une construction @ref{6d3,,try}. Cependant, si l'exécution d'un générateur asynchrone n'a pas repris avant que le générateur ne soit finalisé (parce que son compteur de référence a atteint zéro ou parce qu'il est nettoyé par le ramasse-miettes), alors une expression @code{yield} dans une construction @code{try} pourrait ne pas atteindre la clause @ref{9b8,,finally} en attente. Dans ce cas, c'est la responsabilité de la boucle d'événements ou du programmateur exécutant le générateur asynchrone d'appeler la méthode @ref{8c5,,aclose()} du générateur asynchrone et d'exécuter l'objet coroutine résultant, permettant ainsi à toute clause @code{finally} en attente d'être exécutée.

Pour effectuer correctement la finalisation, une boucle d'événements doit définir une fonction `finalizer' qui prend un générateur-itérateur asynchrone, appelle sans doute @ref{8c5,,aclose()} et exécute la coroutine. Ce `finalizer' peut s'enregistrer en appelant @ref{15af,,sys.set_asyncgen_hooks()}. Lors de la première itération, un générateur-itérateur asynchrone stocke le `finalizer' enregistré à appeler lors de la finalisation. Pour un exemple de référence relatif à une méthode de `finalizer', regardez l'implémentation de @code{asyncio.Loop.shutdown_asyncgens} dans Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/base_events.py}.

L'expression @code{yield from <expr>} produit une erreur de syntaxe quand elle est utilisée dans une fonction génératrice asynchrone.

@geindex object;asynchronous-generator

@node Méthodes des générateurs-itérateurs asynchrones,,Fonctions génératrices asynchrones,Expressions yield
@anchor{reference/expressions asynchronous-generator-iterator-methods}@anchor{1fc1}@anchor{reference/expressions asynchronous-generator-methods}@anchor{1fc2}
@subsubsection Méthodes des générateurs-itérateurs asynchrones


Cette sous-section décrit les méthodes des générateurs-itérateurs asynchrones. Elles sont utilisées pour contrôler l’exécution des fonctions génératrices.

@geindex exception;StopAsyncIteration

@geindex __anext__() (méthode agen)
@anchor{reference/expressions agen __anext__}@anchor{1fc0}
@deffn {Méthode} coroutine agen.__anext__ ()

Returns an awaitable which when run starts to execute the asynchronous
generator or resumes it at the last executed yield expression.  When an
asynchronous generator function is resumed with an @ref{1fc0,,__anext__()}
method, the current yield expression always evaluates to @ref{660,,None} in the
returned awaitable, which when run will continue to the next yield
expression. The value of the @ref{1fbc,,yield_list} of the
yield expression is the value of the @ref{be8,,StopIteration} exception raised by
the completing coroutine.  If the asynchronous generator exits without
yielding another value, the awaitable instead raises a
@ref{19bb,,StopAsyncIteration} exception, signalling that the asynchronous
iteration has completed.

Cette méthode est normalement appelée implicitement par une boucle @ref{a99,,async for}.
@end deffn

@geindex asend() (méthode agen)
@anchor{reference/expressions agen asend}@anchor{8c6}
@deffn {Méthode} coroutine agen.asend (value)

Returns an awaitable which when run resumes the execution of the
asynchronous generator. As with the @ref{1f4f,,send()} method for a
generator, this "sends" a value into the asynchronous generator function,
and the `value' argument becomes the result of the current yield expression.
The awaitable returned by the @ref{8c6,,asend()} method will return the next
value yielded by the generator as the value of the raised
@ref{be8,,StopIteration}, or raises @ref{19bb,,StopAsyncIteration} if the
asynchronous generator exits without yielding another value.  When
@ref{8c6,,asend()} is called to start the asynchronous
generator, it must be called with @ref{660,,None} as the argument,
because there is no yield expression that could receive the value.
@end deffn

@geindex athrow() (méthode agen)
@anchor{reference/expressions agen athrow}@anchor{4e3}
@deffn {Méthode} coroutine agen.athrow (value)

@deffnx {Méthode} coroutine agen.athrow (type[, value[, traceback]])

Renvoie un `awaitable' qui lève une exception du type @code{type} à l'endroit où le générateur asynchrone a été mis en pause et renvoie la valeur suivante produite par la fonction génératrice comme valeur de l'exception @ref{be8,,StopIteration} qui a été levée. Si le générateur asynchrone termine sans produire de nouvelle valeur, une exception @ref{19bb,,StopAsyncIteration} est levée par le `awaitable'. Si la fonction génératrice ne traite pas l'exception reçue ou lève une autre exception alors, quand le `awaitable' est lancé, cette exception est propagée vers l'appelant du `awaitable'.


Modifié dans la version 3.12: The second signature (type[, value[, traceback]]) is deprecated and
may be removed in a future version of Python.

@end deffn

@geindex exception;GeneratorExit

@geindex aclose() (méthode agen)
@anchor{reference/expressions agen aclose}@anchor{8c5}
@deffn {Méthode} coroutine agen.aclose ()

Renvoie un `awaitable' qui, quand il s'exécute, lève une exception @ref{137e,,GeneratorExit} dans la fonction génératrice asynchrone à l'endroit où le générateur était en pause. Si la fonction génératrice asynchrone termine normalement, est déjà fermée ou lève @ref{137e,,GeneratorExit} (parce qu'elle ne gère pas l'exception), alors le `awaitable' renvoyé lève une exception @ref{be8,,StopIteration}. Tout nouveau `awaitable' produit par un appel postérieur au générateur asynchrone lève une exception @ref{19bb,,StopAsyncIteration}. Si le générateur asynchrone produit une valeur, une @ref{193,,RuntimeError} est levée par le `awaitable'. Si le générateur asynchrone lève une autre exception, elle est propagée à l'appelant du `awaitable'. Si le générateur asynchrone a déjà terminé (soit par une exception, soit normalement), alors tout nouvel appel à @ref{8c5,,aclose()} renvoie un `awaitable' qui ne fait rien.
@end deffn

@node Primaires,Expression await,Atomes,Expressions
@anchor{reference/expressions id5}@anchor{1fc3}@anchor{reference/expressions primaries}@anchor{1fc4}
@subsection Primaires


@geindex primary

Les primaires (`primary' dans la grammaire formelle ci-dessous) représentent les opérations qui se lient au plus proche dans le langage. Leur syntaxe est :

@example
@anchor{reference/expressions grammar-token-python-grammar-primary}@anchor{1fc5}primary ::= atom | attributeref | subscription | slicing | call
@end example

@menu
* Références à des attributs:: 
* sélection (ou indiçage): sélection ou indiçage. 
* Tranches:: 
* Appels:: 

@end menu

@node Références à des attributs,sélection ou indiçage,,Primaires
@anchor{reference/expressions attribute-references}@anchor{1fc6}@anchor{reference/expressions id6}@anchor{1fc7}
@subsubsection Références à des attributs


@geindex attribute;reference
@geindex . (dot);attribute reference

Une référence à un attribut (`attributeref' dans la grammaire formelle ci-dessous) est une primaire suivie par un point et un nom :

@example
@anchor{reference/expressions grammar-token-python-grammar-attributeref}@anchor{1fc8}attributeref ::= primary "." identifier
@end example

@geindex exception;AttributeError
@geindex object;module
@geindex object;list

The primary must evaluate to an object of a type that supports attribute
references, which most objects do.  This object is then asked to produce the
attribute whose name is the identifier. The type and value produced is
determined by the object.  Multiple evaluations of the same attribute
reference may yield different objects.

This production can be customized by overriding the
@ref{bc0,,__getattribute__()} method or the @ref{4bc,,__getattr__()}
method.  The @code{__getattribute__()} method is called first and either
returns a value or raises @ref{343,,AttributeError} if the attribute is not
available.

If an @ref{343,,AttributeError} is raised and the object has a @code{__getattr__()}
method, that method is called as a fallback.

@node sélection ou indiçage,Tranches,Références à des attributs,Primaires
@anchor{reference/expressions id7}@anchor{1fc9}@anchor{reference/expressions subscriptions}@anchor{1f07}
@subsubsection sélection (ou indiçage)


@geindex subscription
@geindex [] (square brackets);subscription

@geindex object;sequence
@geindex object;mapping
@geindex object;string
@geindex object;tuple
@geindex object;list
@geindex object;dictionary
@geindex sequence;item

L'indiçage d'une instance de @ref{1f0d,,classe conteneur} sélectionne généralement un élément du conteneur. L'indiçage d'une @ref{422,,classe générique} renvoie généralement un objet @ref{69d,,GenericAlias}.

@example
@anchor{reference/expressions grammar-token-python-grammar-subscription}@anchor{1fca}subscription ::= primary "[" flexible_expression_list "]"
@end example

Lorsqu'on accède à l'indice d'un objet, l'interpréteur évalue la primaire et la liste d'expressions.

L'évaluation de la primaire doit produire un objet qui gère l'indiçage. Un objet est susceptible de gérer l'indiçage s'il définit la ou les deux méthodes @ref{280,,__getitem__()} et @ref{725,,__class_getitem__()}. Quand on spécifie un indice du primaire, le résultat de l'évaluation de la liste d'expression est passé à l'une de ces méthodes. Pour plus de détails sur le choix de @code{__class_getitem__} ou @code{__getitem__} pour l'appel, lisez @ref{1f06,,__class_getitem__ contre __getitem__}.

If the expression list contains at least one comma, or if any of the expressions
are starred, the expression list will evaluate to a @ref{366,,tuple} containing
the items of the expression list. Otherwise, the expression list will evaluate
to the value of the list's sole member.


Modifié dans la version 3.11: Expressions in an expression list may be starred. See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}.


Pour les objets natifs, deux types d'objets gèrent la sélection `via' @ref{280,,__getitem__()} :


@enumerate 

@item 
Si la primaire est un @ref{1199,,tableau de correspondances}, la liste d'expressions (`expression_list' dans la grammaire formelle ci-dessous) doit pouvoir être évaluée comme un objet dont la valeur est une des clés du tableau de correspondances et la sélection désigne la valeur qui correspond à cette clé. Un exemple de classe implémentant le concept de tableau de correspondances est la classe @ref{253,,dict}.

@item 
Si la primaire est une @ref{4db,,séquence}, la liste d'expressions (`expression_list' dans la grammaire) doit pouvoir être évaluée comme un @ref{254,,entier} ou une @ref{453,,tranche} (comme expliqué dans la section suivante). Des exemples de classes natives implémentant le concept de séquence sont les @ref{435,,chaînes}, @ref{5fc,,listes} et les @ref{366,,n-uplets}.
@end enumerate

The formal syntax makes no special provision for negative indices in
@ref{4db,,sequences}. However, built-in sequences all provide a @ref{280,,__getitem__()}
method that interprets negative indices by adding the length of the sequence
to the index so that, for example, @code{x[-1]} selects the last item of @code{x}. The
resulting value must be a nonnegative integer less than the number of items in
the sequence, and the subscription selects the item whose index is that value
(counting from zero). Since the support for negative indices and slicing
occurs in the object's @ref{280,,__getitem__()} method, subclasses overriding
this method will need to explicitly add that support.

@geindex character
@geindex string;item

Une @ref{435,,chaîne} est une espèce particulière de séquence dont les éléments sont des `caractères'. Un caractère n'est pas un type en tant que tel, c'est une chaîne de longueur un.

@node Tranches,Appels,sélection ou indiçage,Primaires
@anchor{reference/expressions id8}@anchor{1fcb}@anchor{reference/expressions slicings}@anchor{1fcc}
@subsubsection Tranches


@geindex slicing
@geindex slice
@geindex ; (colon);slicing
@geindex @comma{} (comma);slicing

@geindex object;sequence
@geindex object;string
@geindex object;tuple
@geindex object;list

Une tranche (`slicing' dans la grammaire formelle ci-dessous) sélectionne un intervalle d'éléments d'un objet séquence (par exemple une chaîne, un n-uplet ou une liste, respectivement les types `string', `tuple' et `list'). Les tranches peuvent être utilisées comme des expressions ou des cibles dans les affectations ou les instructions @ref{1734,,del}. La syntaxe est la suivante :

@example
@anchor{reference/expressions grammar-token-python-grammar-slicing}@anchor{1fcd}slicing      ::= primary "[" slice_list "]"
@anchor{reference/expressions grammar-token-python-grammar-slice_list}@anchor{1fce}slice_list   ::= slice_item ("," slice_item)* [","]
@anchor{reference/expressions grammar-token-python-grammar-slice_item}@anchor{1fcf}slice_item   ::= expression | proper_slice
@anchor{reference/expressions grammar-token-python-grammar-proper_slice}@anchor{1fd0}proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" [stride] ]
@anchor{reference/expressions grammar-token-python-grammar-lower_bound}@anchor{1fd1}lower_bound  ::= expression
@anchor{reference/expressions grammar-token-python-grammar-upper_bound}@anchor{1fd2}upper_bound  ::= expression
@anchor{reference/expressions grammar-token-python-grammar-stride}@anchor{1fd3}stride       ::= expression
@end example

Il existe une ambigüité dans la syntaxe formelle ci-dessus : tout ce qui ressemble à une liste d'expressions (`expression_list' vue avant) ressemble aussi à une liste de tranches (`slice_list' dans la grammaire ci-dessus). En conséquence, toute sélection (`subscription' dans la grammaire) peut être interprétée comme une tranche. Plutôt que de compliquer encore la syntaxe, l'ambigüité est levée en disant que, dans ce cas, l'interprétation en tant que sélection (`subscription') est prioritaire sur l'interprétation en tant que tranche (c'est le cas si la liste de tranches (`slice_list') ne contient aucune tranche en tant que telle).

@geindex start (slice object attribute)
@geindex stop (slice object attribute)
@geindex step (slice object attribute)

The semantics for a slicing are as follows.  The primary is indexed (using the
same @ref{280,,__getitem__()} method as
normal subscription) with a key that is constructed from the slice list, as
follows.  If the slice list contains at least one comma, the key is a tuple
containing the conversion of the slice items; otherwise, the conversion of the
lone slice item is the key.  The conversion of a slice item that is an
expression is that expression.  The conversion of a proper slice is a slice
object (see section @ref{1e6a,,Hiérarchie des types standards}) whose @ref{1fd4,,start},
@ref{1fd5,,stop} and @ref{1fd6,,step} attributes are the values of the
expressions given as lower bound, upper bound and stride, respectively,
substituting @code{None} for missing expressions.

@geindex object;callable
@geindex call
@geindex argument;call semantics
@geindex () (parentheses);call
@geindex @comma{} (comma);argument list
@geindex = (equals);in function calls

@node Appels,,Tranches,Primaires
@anchor{reference/expressions calls}@anchor{d6a}@anchor{reference/expressions id9}@anchor{1fd7}
@subsubsection Appels


Un appel (`call' dans la grammaire ci-dessous) appelle un objet appelable (par exemple, une @ref{1fd8,,fonction}) avec, possiblement, une liste d'@ref{432,,arguments} :

@example
@anchor{reference/expressions grammar-token-python-grammar-call}@anchor{1fd9}call                 ::= primary "(" [argument_list [","] | comprehension] ")"
@anchor{reference/expressions grammar-token-python-grammar-argument_list}@anchor{1fda}argument_list        ::= positional_arguments ["," starred_and_keywords]
                           ["," keywords_arguments]
                         | starred_and_keywords ["," keywords_arguments]
                         | keywords_arguments
@anchor{reference/expressions grammar-token-python-grammar-positional_arguments}@anchor{1fdb}positional_arguments ::= positional_item ("," positional_item)*
@anchor{reference/expressions grammar-token-python-grammar-positional_item}@anchor{1fdc}positional_item      ::= assignment_expression | "*" expression
@anchor{reference/expressions grammar-token-python-grammar-starred_and_keywords}@anchor{1fdd}starred_and_keywords ::= ("*" expression | keyword_item)
                         ("," "*" expression | "," keyword_item)*
@anchor{reference/expressions grammar-token-python-grammar-keywords_arguments}@anchor{1fde}keywords_arguments   ::= (keyword_item | "**" expression)
                         ("," keyword_item | "," "**" expression)*
@anchor{reference/expressions grammar-token-python-grammar-keyword_item}@anchor{1fdf}keyword_item         ::= identifier "=" expression
@end example

Une virgule finale (optionnelle) peut être présente, après les arguments positionnels et nommés, mais elle n'affecte pas la sémantique.

@geindex parameter;call semantics

The primary must evaluate to a callable object (user-defined functions, built-in
functions, methods of built-in objects, class objects, methods of class
instances, and all objects having a @ref{543,,__call__()} method are callable).  All
argument expressions are evaluated before the call is attempted.  Please refer
to section @ref{1bc4,,Définition de fonctions} for the syntax of formal @ref{1e82,,parameter} lists.

@c XXX update with kwonly args PEP

Si des arguments par mots-clés sont présents, ils sont d'abord convertis en arguments positionnels, comme suit. Pour commencer, une liste de `slots' vides est créée pour les paramètres formels. S'il y a N arguments positionnels, ils sont placés dans les N premiers `slots'. Ensuite, pour chaque argument nommé, l'identifiant est utilisé pour déterminer le `slot' correspondant (si l'identifiant est le même que le nom du premier paramètre formel, le premier `slot' est utilisé, et ainsi de suite). Si le `slot' est déjà rempli, une exception @ref{522,,TypeError} est levée. Sinon, l'argument est placé dans le `slot', ce qui le remplit (même si l'expression est @code{None}, cela remplit le `slot'). Quand tous les arguments ont été traités, les `slots' qui sont toujours vides sont remplis avec la valeur par défaut correspondante dans la définition de la fonction (les valeurs par défaut sont calculées, une seule fois, lorsque la fonction est définie ; ainsi, un objet mutable tel qu'une liste ou un dictionnaire utilisé en tant valeur par défaut sera partagé entre tous les appels qui ne spécifient pas de valeur d argument pour ce `slot' ; on évite généralement de faire ça). S'il reste des `slots' pour lesquels aucune valeur par défaut n'est définie, une exception @ref{522,,TypeError} est levée. Sinon, la liste des `slots' remplie est utilisée en tant que liste des arguments pour l'appel.

`Particularité de l'implémentation CPython :' Une implémentation peut fournir des fonctions natives dont les paramètres positionnels n'ont pas de nom, même s'ils sont « nommés » pour les besoins de la documentation. Ils ne peuvent donc pas être fournis comme arguments nommés. En CPython, les fonctions implémentées en C qui utilisent @ref{55d,,PyArg_ParseTuple()} pour analyser leurs arguments en font partie.

S'il y a plus d'arguments positionnels que de `slots' de paramètres formels, une exception @ref{522,,TypeError} est levée, à moins qu'un paramètre formel n'utilise la syntaxe @code{*identifier} ; dans ce cas, le paramètre formel reçoit un `n'-uplet contenant les arguments positionnels en supplément (ou un `n'-uplet vide s'il n'y avait pas d'argument positionnel en trop).

Si un argument nommé ne correspond à aucun nom de paramètre formel, une exception @ref{522,,TypeError} est levée, à moins qu'un paramètre formel n'utilise la syntaxe @code{**identifier} ; dans ce cas, le paramètre formel reçoit un dictionnaire contenant les arguments nommés en trop (en utilisant les mots-clés comme clés et les arguments comme valeurs pour ce dictionnaire), ou un (nouveau) dictionnaire vide s'il n'y a pas d'argument nommé en trop.

@geindex * (asterisk);in function calls
@geindex unpacking;in function calls

Si la syntaxe @code{*expression} apparaît dans l'appel de la fonction, @code{expression} doit pouvoir s'évaluer à un @ref{1205,,itérable}. Les éléments de ces itérables sont traités comme s'ils étaient des arguments positionnels supplémentaires. Pour l'appel @code{f(x1, x2, *y, x3, x4)}, si `y' s'évalue comme une séquence `y1' … `yM', c'est équivalent à un appel avec M+4 arguments positionnels `x1', `x2', `y1' … `yM', `x3', `x4'.

Une conséquence est que bien que la syntaxe @code{*expression} puisse apparaître `après' les arguments par nommés explicites, ils sont traités `avant' les arguments nommés (et avant tout argument @code{**expression} -- voir ci-dessous). Ainsi :

@example
>>> def f(a, b):
...     print(a, b)
...
>>> f(b=1, *(2,))
2 1
>>> f(a=1, *(2,))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: f() got multiple values for keyword argument 'a'
>>> f(1, *(2,))
1 2
@end example

Il est inhabituel que les syntaxes d'arguments par mots-clés et @code{*expression} soient utilisés simultanément dans un même appel, ce qui fait que la confusion reste rare.

@geindex **;in function calls

Si la syntaxe @code{**expression} apparaît dans un appel de fonction, @code{expression} doit pouvoir s'évaluer comme un @ref{1199,,tableau de correspondances}, dont le contenu est traité comme des arguments par mots-clés supplémentaires. Si un paramètre correspondant à une clé a déjà été fourni (en tant qu'argument nommé explicite, en provenance d'un autre dépaquetage), une exception @ref{522,,TypeError} est levée.

Lorsque @code{**expression} est utilisée, chaque clé de ce tableau de correspondances doit être une chaîne. Chaque valeur du tableau est affectée au premier paramètre formel éligible à l'affectation par mot-clé dont le nom est égal à la clé. Une clé n'a pas besoin d'être un identifiant Python (par exemple, @code{"max-temp °F"} est acceptable, bien qu'elle ne corresponde à aucun paramètre formel qui pourrait être déclaré). S'il n'y a pas de correspondance avec un paramètre formel, la paire clé-valeur est collectée par le paramètre @code{**}, s'il y en a un. S'il n'y a pas de paramètre @code{**}, une exception @ref{522,,TypeError} est levée.

Les paramètres formels qui utilisent la syntaxe @code{*identifier} ou @code{**identifier} ne peuvent pas être utilisés comme arguments positionnels ou comme noms d'arguments par mots-clés.


Modifié dans la version 3.5: Les appels de fonction acceptent n'importe quel nombre de dépaquetages par @code{*} ou @code{**}. Des arguments positionnels peuvent suivre les dépaquetages d'itérables (@code{*}) et les arguments par mots-clés peuvent suivre les dépaquetages de dictionnaires (@code{**}). Proposé pour la première fois par la 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/}.


Un appel renvoie toujours une valeur, possiblement @code{None}, à moins qu'il ne lève une exception. La façon dont celle valeur est calculée dépend du type de l'objet appelable.

Si c'est


@table @asis

@item une fonction définie par l'utilisateur :

@geindex function;call
@geindex user-defined;function;call
@geindex object;user-defined function
@geindex object;function

The code block for the function is executed, passing it the argument list.  The
first thing the code block will do is bind the formal parameters to the
arguments; this is described in section @ref{1bc4,,Définition de fonctions}.  When the code block
executes a @ref{9bc,,return} statement, this specifies the return value of the
function call.  If execution reaches the end of the code block without
executing a @ref{9bc,,return} statement, the return value is @code{None}.

@item une fonction ou une méthode native :

@geindex function;call
@geindex built-in function;call
@geindex method;call
@geindex built-in method;call
@geindex object;built-in method
@geindex object;built-in function
@geindex object;method
@geindex object;function

le résultat dépend de l'interpréteur ; lisez @ref{123b,,Fonctions natives} pour une description des fonctions et méthodes natives.

@item un objet classe :

@geindex object;class
@geindex class object;call

une nouvelle instance de cette classe est renvoyée.

@item une méthode d'instance de classe :

@geindex object;class instance
@geindex object;instance
@geindex class instance;call

la fonction correspondante définie par l'utilisateur est appelée, avec la liste d'arguments qui est plus grande d'un élément que la liste des arguments de l'appel : l'instance est placée en tête des arguments.

@item une instance de classe :

@geindex instance;call
@geindex __call__() (object method)

The class must define a @ref{543,,__call__()} method; the effect is then the same as
if that method was called.
@end table

@geindex keyword;await

@node Expression await,L'opérateur puissance,Primaires,Expressions
@anchor{reference/expressions await}@anchor{1b7}@anchor{reference/expressions await-expression}@anchor{1fe0}
@subsection Expression @code{await}


Suspend l'exécution de la @ref{47b,,coroutine} sur un objet @ref{1ab,,awaitable}. Ne peut être utilisée qu'à l'intérieur d'une @ref{d64,,coroutine function}.

@example
@anchor{reference/expressions grammar-token-python-grammar-await_expr}@anchor{1fe1}await_expr ::= "await" primary
@end example


Ajouté dans la version 3.5.


@node L'opérateur puissance,Arithmétique unaire et opérations sur les bits,Expression await,Expressions
@anchor{reference/expressions power}@anchor{1fe2}@anchor{reference/expressions the-power-operator}@anchor{1fe3}
@subsection L'opérateur puissance


@geindex power;operation
@geindex operator;**

L'opérateur puissance est plus prioritaire que les opérateurs unaires sur sa gauche ; il est moins prioritaire que les opérateurs unaires sur sa droite. La syntaxe est :

@example
@anchor{reference/expressions grammar-token-python-grammar-power}@anchor{1fe4}power ::= (await_expr | primary) ["**" u_expr]
@end example

Ainsi, dans une séquence sans parenthèse de puissance et d'opérateurs unaires, les opérateurs sont évalués de droite à gauche (ceci ne contraint pas l'ordre d'évaluation des opérandes) : @code{-1**2} donne @code{-1}.

L'opérateur puissance possède la même sémantique que la fonction native @ref{9c0,,pow()} lorsqu'elle est appelée avec deux arguments : il produit son argument de gauche élevé à la puissance de son argument de droite. Les arguments numériques sont d'abord convertis vers un type commun et le résultat est de ce type.

Pour les opérandes entiers, le résultat est du même type à moins que le deuxième argument ne soit négatif ; dans ce cas, tous les arguments sont convertis en nombres à virgule flottante et le résultat est un nombre à virgule flottante. Par exemple, @code{10**2} renvoie @code{100} mais @code{10**-2} renvoie @code{0.01}.

Élever @code{0.0} à une puissance négative entraîne une @ref{932,,ZeroDivisionError}. Élever un nombre négatif à une puissance fractionnaire renvoie un nombre @ref{2ec,,complexe} (dans les versions antérieures, cela levait une @ref{1ff,,ValueError}).

This operation can be customized using the special @ref{7bd,,__pow__()} and
@ref{7be,,__rpow__()} methods.

@node Arithmétique unaire et opérations sur les bits,Opérations arithmétiques binaires,L'opérateur puissance,Expressions
@anchor{reference/expressions unary}@anchor{1fe5}@anchor{reference/expressions unary-arithmetic-and-bitwise-operations}@anchor{1fe6}
@subsection Arithmétique unaire et opérations sur les bits


@geindex unary;arithmetic;operation
@geindex unary;bitwise;operation

Toute l'arithmétique unaire et les opérations sur les bits ont la même priorité :

@example
@anchor{reference/expressions grammar-token-python-grammar-u_expr}@anchor{1fe7}u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr
@end example

@geindex negation
@geindex minus
@geindex operator;- (minus)
@geindex - (minus);unary operator

The unary @code{-} (minus) operator yields the negation of its numeric argument; the
operation can be overridden with the @ref{1f38,,__neg__()} special method.

@geindex plus
@geindex operator;+ (plus)
@geindex + (plus);unary operator

The unary @code{+} (plus) operator yields its numeric argument unchanged; the
operation can be overridden with the @ref{1f39,,__pos__()} special method.

@geindex inversion
@geindex operator;~ (tilde)

The unary @code{~} (invert) operator yields the bitwise inversion of its integer
argument.  The bitwise inversion of @code{x} is defined as @code{-(x+1)}.  It only
applies to integral numbers or to custom objects that override the
@ref{1f3b,,__invert__()} special method.

@geindex exception;TypeError

Dans ces trois cas, si l'argument n'est pas du bon type, une exception @ref{522,,TypeError} est levée.

@node Opérations arithmétiques binaires,Opérations de décalage,Arithmétique unaire et opérations sur les bits,Expressions
@anchor{reference/expressions binary}@anchor{1fe8}@anchor{reference/expressions binary-arithmetic-operations}@anchor{1fe9}
@subsection Opérations arithmétiques binaires


@geindex binary;arithmetic;operation

Les opérations arithmétiques binaires suivent les conventions pour les priorités. Notez que certaines de ces opérations s'appliquent aussi à des types non numériques. À part l'opérateur puissance, il n'y a que deux niveaux, le premier pour les opérateurs multiplicatifs et le second pour les opérateurs additifs :

@example
@anchor{reference/expressions grammar-token-python-grammar-m_expr}@anchor{1fea}m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@@" m_expr |
           m_expr "//" u_expr | m_expr "/" u_expr |
           m_expr "%" u_expr
@anchor{reference/expressions grammar-token-python-grammar-a_expr}@anchor{1feb}a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr
@end example

@geindex multiplication
@geindex operator;* (asterisk)

L'opérateur @code{*} (multiplication) produit le produit de ses arguments. Les deux arguments doivent être des nombres ou alors le premier argument doit être un entier et l'autre doit être une séquence. Dans le premier cas, les nombres sont convertis dans un type commun puis sont multipliés entre eux. Dans le dernier cas, la séquence est répétée ; une répétition négative produit une séquence vide.

This operation can be customized using the special @ref{1f12,,__mul__()} and
@ref{1f13,,__rmul__()} methods.

@geindex matrix multiplication
@geindex operator;@@ (at)

L'opérateur @code{@@} (prononcé `at' en anglais) a vocation à multiplier des matrices. Aucun type Python natif n'implémente cet opérateur.

This operation can be customized using the special @ref{1f1a,,__matmul__()} and
@ref{1f23,,__rmatmul__()} methods.


Ajouté dans la version 3.5.


@geindex exception;ZeroDivisionError
@geindex division
@geindex operator;/ (slash)
@geindex operator;//

Les opérateurs @code{/} (division) et @code{//} (division entière ou `floor division' en anglais) produisent le quotient de leurs arguments. Les arguments numériques sont d'abord convertis vers un type commun. La division d'entiers produit un nombre à virgule flottante alors que la division entière d'entiers produit un entier ; le résultat est celui de la division mathématique suivie de la fonction @code{floor} appliquée au résultat. Une division par zéro lève une exception @ref{932,,ZeroDivisionError}.

The division operation can be customized using the special @ref{14a9,,__truediv__()}
and @ref{1f24,,__rtruediv__()} methods.
The floor division operation can be customized using the special
@ref{14aa,,__floordiv__()} and @ref{1f25,,__rfloordiv__()} methods.

@geindex modulo
@geindex operator;% (percent)

The @code{%} (modulo) operator yields the remainder from the division of the first
argument by the second.  The numeric arguments are first converted to a common
type.  A zero right argument raises the @ref{932,,ZeroDivisionError} exception.  The
arguments may be floating-point numbers, e.g., @code{3.14%0.7} equals @code{0.34}
(since @code{3.14} equals @code{4*0.7 + 0.34}.)  The modulo operator always yields a
result with the same sign as its second operand (or zero); the absolute value of
the result is strictly smaller than the absolute value of the second operand
@footnote{
Bien que @code{abs(x%y) < abs(y)} soit vrai mathématiquement, ce n'est pas toujours vrai pour les nombres à virgule flottante en raison des arrondis. Par exemple, en supposant que Python tourne sur une plateforme où les `float' sont des nombres à double précision IEEE 754, afin que @code{-1e-100 % 1e100} soit du même signe que @code{1e100}, le résultat calculé est @code{-1e-100 + 1e100}, qui vaut exactement @code{1e100} dans ce standard. Or, la fonction @ref{1fec,,math.fmod()} renvoie un résultat dont le signe est le signe du premier argument, c'est-à-dire @code{-1e-100} dans ce cas. La meilleure approche dépend de l'application.
}.

Les opérateurs division entière et modulo sont liés par la relation suivante : @code{x == (x//y)*y + (x%y)}. La division entière et le module sont aussi liés à la fonction native  @ref{98f,,divmod()} : @code{divmod(x, y) == (x//y, x%y)} @footnote{
Si x est très proche d'un multiple entier de y, il est possible que @code{x/y} soit supérieur de un par rapport à @code{(x-x%y)//y} en raison des arrondis. Dans de tels cas, Python renvoie le second résultat afin d'avoir @code{divmod(x,y)[0] * y + x % y} le plus proche de @code{x}.
}.

En plus de calculer le modulo sur les nombres, l'opérateur @code{%} est aussi surchargé par les objets chaînes de caractères pour effectuer le formatage de chaîne « à l'ancienne ». La syntaxe pour le formatage de chaînes est décrit dans la référence de la bibliothèque Python, dans la section  @ref{6b7,,Formatage de chaines à la printf}.

The `modulo' operation can be customized using the special @ref{1f1b,,__mod__()}
and @ref{1f26,,__rmod__()} methods.

The floor division operator, the modulo operator, and the @ref{98f,,divmod()}
function are not defined for complex numbers.  Instead, convert to a
floating-point number using the @ref{1c32,,abs()} function if appropriate.

@geindex addition
@geindex operator;+ (plus)
@geindex + (plus);binary operator

L'opérateur @code{+} (addition) produit la somme de ses arguments. Les arguments doivent être tous les deux des nombres ou des séquences du même type. Dans le premier cas, les nombres sont convertis vers un type commun puis sont additionnés entre eux. Dans le dernier cas, les séquences sont concaténées.

This operation can be customized using the special @ref{1f0f,,__add__()} and
@ref{1f10,,__radd__()} methods.

@geindex subtraction
@geindex operator;- (minus)
@geindex - (minus);binary operator

L'opérateur @code{-} (soustraction) produit la différence entre ses arguments. Les arguments numériques sont d'abord convertis vers un type commun.

This operation can be customized using the special @ref{1f19,,__sub__()} and
@ref{1f22,,__rsub__()} methods.

@node Opérations de décalage,Opérations binaires bit à bit,Opérations arithmétiques binaires,Expressions
@anchor{reference/expressions shifting}@anchor{1fed}@anchor{reference/expressions shifting-operations}@anchor{1fee}
@subsection Opérations de décalage


@geindex shifting;operation
@geindex operator;<<
@geindex operator;>>

Les opérations de décalage sont moins prioritaires que les opérations arithmétiques :

@example
@anchor{reference/expressions grammar-token-python-grammar-shift_expr}@anchor{1fef}shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr
@end example

Ces opérateurs prennent des entiers comme arguments. Ils décalent le premier argument vers la gauche ou vers la droite du nombre de bits donné par le deuxième argument.

The left shift operation can be customized using the special @ref{1f1d,,__lshift__()}
and @ref{1f28,,__rlshift__()} methods.
The right shift operation can be customized using the special @ref{1f1e,,__rshift__()}
and @ref{1f29,,__rrshift__()} methods.

@geindex exception;ValueError

Un décalage à droite de `n' bits est défini comme la division entière par @code{pow(2,n)}. Un décalage à gauche de `n' bits est défini comme la multiplication par @code{pow(2,n)}.

@node Opérations binaires bit à bit,Comparaisons,Opérations de décalage,Expressions
@anchor{reference/expressions binary-bitwise-operations}@anchor{1ff0}@anchor{reference/expressions bitwise}@anchor{1ff1}
@subsection Opérations binaires bit à bit


@geindex binary;bitwise;operation

Chacune des trois opérations binaires bit à bit possède une priorité différente :

@example
@anchor{reference/expressions grammar-token-python-grammar-and_expr}@anchor{1ff2}and_expr ::= shift_expr | and_expr "&" shift_expr
@anchor{reference/expressions grammar-token-python-grammar-xor_expr}@anchor{1ff3}xor_expr ::= and_expr | xor_expr "^" and_expr
@anchor{reference/expressions grammar-token-python-grammar-or_expr}@anchor{1ff4}or_expr  ::= xor_expr | or_expr "|" xor_expr
@end example

@geindex bitwise;and
@geindex operator;& (ampersand)

The @code{&} operator yields the bitwise AND of its arguments, which must be
integers or one of them must be a custom object overriding @ref{1f1f,,__and__()} or
@ref{1f2a,,__rand__()} special methods.

@geindex bitwise;xor
@geindex exclusive;or
@geindex operator;^ (caret)

The @code{^} operator yields the bitwise XOR (exclusive OR) of its arguments, which
must be integers or one of them must be a custom object overriding @ref{1f20,,__xor__()} or
@ref{1f2b,,__rxor__()} special methods.

@geindex bitwise;or
@geindex inclusive;or
@geindex operator;| (vertical bar)

The @code{|} operator yields the bitwise (inclusive) OR of its arguments, which
must be integers or one of them must be a custom object overriding @ref{1f21,,__or__()} or
@ref{1f2c,,__ror__()} special methods.

@node Comparaisons,Opérations booléennes,Opérations binaires bit à bit,Expressions
@anchor{reference/expressions comparisons}@anchor{1ff5}@anchor{reference/expressions id12}@anchor{1ff6}
@subsection Comparaisons


@geindex comparison
@geindex C;language
@geindex operator;< (less)
@geindex operator;> (greater)
@geindex operator;<=
@geindex operator;>=
@geindex operator;==
@geindex operator;!=

Au contraire du C, toutes les opérations de comparaison en Python possèdent la même priorité, qui est plus faible que celle des opérations arithmétiques, décalages ou binaires bit à bit. Toujours contrairement au C, les expressions telles que @code{a < b < c} sont interprétées comme elles le seraient conventionnellement en mathématiques :

@example
@anchor{reference/expressions grammar-token-python-grammar-comparison}@anchor{1ff7}comparison    ::= or_expr (comp_operator or_expr)*
@anchor{reference/expressions grammar-token-python-grammar-comp_operator}@anchor{1ff8}comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="
                  | "is" ["not"] | ["not"] "in"
@end example

Les comparaisons donnent des valeurs booléennes (@code{True} ou @code{False}). Cependant, les `méthodes de comparaison riche' définies par l'utilisateur peuvent renvoyer des non-booléens. Dans ce cas, le résultat de la comparaison est converti en booléen avec @ref{451,,bool()} dans les contextes qui attendent un booléen.

@geindex chaining;comparisons

Les comparaisons peuvent être enchaînées arbitrairement, par exemple @code{x < y <= z} est équivalent à @code{x < y and y <= z}, sauf que @code{y} est évalué seulement une fois (mais dans les deux cas, @code{z} n'est pas évalué du tout si @code{x < y} s'avère être faux).

Formellement, si `a', `b', `c' … `y', `z' sont des expressions et `op1', `op2' … `opN' sont des opérateurs de comparaison, alors @code{a op1 b op2 c … y opN z} est équivalent à @code{a op1 b and b op2 c and … y opN z}, sauf que chaque expression est évaluée au maximum une fois.

Notez que @code{a op1 b op2 c} n'implique aucune comparaison entre `a' et `c'. Ainsi, par exemple, @code{x < y > z} est parfaitement légal (mais peut-être pas très élégant).

@menu
* Comparaisons de valeurs:: 
* Opérations de tests d’appartenance à un ensemble:: 
* Comparaisons d'identifiants:: 

@end menu

@node Comparaisons de valeurs,Opérations de tests d’appartenance à un ensemble,,Comparaisons
@anchor{reference/expressions expressions-value-comparisons}@anchor{1809}@anchor{reference/expressions value-comparisons}@anchor{1ff9}
@subsubsection Comparaisons de valeurs


Les opérateurs @code{<}, @code{>}, @code{==}, @code{>=}, @code{<=} et  @code{!=} comparent les valeurs de deux objets. Les objets n'ont pas besoin d'être du même type.

Le chapitre @ref{1e67,,Objets@comma{} valeurs et types} indique que les objets ont une valeur (en plus d'un type et d'un identifiant). La valeur d'un objet est une notion plutôt abstraite en Python : par exemple, il n'existe pas de méthode canonique pour accéder à la valeur d'un objet. De la même manière, il n'y a aucune obligation concernant la construction de la valeur d'un objet, par exemple qu'elle prenne en compte toutes les données de ses attributs. Les opérateurs de comparaison implémentent une notion particulière de ce qu'est la valeur d'un objet. Vous pouvez vous le représenter comme une définition indirecte de la valeur d'un objet, `via' l'implémentation de leur comparaison.

Because all types are (direct or indirect) subtypes of @ref{a7a,,object}, they
inherit the default comparison behavior from @ref{a7a,,object}.  Types can
customize their comparison behavior by implementing
`rich comparison methods' like @ref{127d,,__lt__()}, described in
@ref{1ee2,,Personnalisation de base}.

Le comportement par défaut pour le test d'égalité (@code{==} et @code{!=}) se base sur les identifiants des objets. Ainsi, un test d'égalité entre deux instances qui ont le même identifiant est vrai, un test d'égalité entre deux instances qui ont des identifiants différents est faux. La raison de ce choix est que Python souhaite que tous les objets soient réflexifs, c'est-à-dire que @code{x is y} implique @code{x == y}.

La relation d'ordre (@code{<}, @code{>}, @code{<=} et @code{>=}) n'est pas fournie par défaut ; une tentative se solde par une @ref{522,,TypeError}. La raison de ce choix est qu'il n'existe pas d'invariant similaire à celui de l'égalité.

Le comportement du test d'égalité par défaut, à savoir que les instances avec des identités différentes ne sont jamais égales, peut être en contradiction avec les types qui définissent la « valeur » d'un objet et se basent sur cette « valeur » pour l'égalité. De tels types doivent personnaliser leurs tests de comparaison et, en fait, c'est ce qu'ont fait un certain nombre de types natifs.

La liste suivante décrit le comportement des tests d'égalité pour les types natifs les plus importants.


@itemize *

@item 
Beaucoup de types numériques natifs (@ref{1b86,,Types numériques — int@comma{} float@comma{} complex}) et de types de la bibliothèque standard @ref{1e4,,fractions.Fraction} ainsi que @code{decimal.decimal} peuvent être comparés, au sein de leur propre classe ou avec d'autres objets de classes différentes. Une exception notable concerne les nombres complexes qui ne gèrent pas la relation d'ordre. Dans les limites des types concernés, la comparaison mathématique équivaut à la comparaison algorithmique, sans perte de précision.

Les valeurs non numériques @code{float('NaN')} et @code{decimal.Decimal('NaN')} sont spéciales : toute comparaison entre un nombre et une valeur non numérique est fausse. Une implication contre-intuitive à cela est que les valeurs non numériques ne sont pas égales à elles-mêmes. Par exemple, avec @code{x = float('NaN')}, les expressions @code{3 < x}, @code{x < 3} et @code{x == x} sont toutes fausses, mais l’expression @code{x != x} est vraie. Ce comportement est en accord avec IEEE 754.

@item 
@code{None} and @ref{7bc,,NotImplemented} are singletons.  
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} advises that
comparisons for singletons should always be done with @code{is} or @code{is not},
never the equality operators.

@item 
Les séquences binaires (instances du type @ref{1bd,,bytes} ou @ref{528,,bytearray}) peuvent être comparées au sein de la classe et entre classes. La comparaison est lexicographique, en utilisant la valeur numérique des éléments.

@item 
Les chaînes de caractères (instances de @ref{435,,str}) respectent l'ordre lexicographique en utilisant la valeur Unicode (le résultat de la fonction native @ref{1e75,,ord()}) des caractères @footnote{
Le standard Unicode distingue les `points codes' (`code points' en anglais, par exemple `U+0041') et les `caractères abstraits' (`abstract characters' en anglais, par exemple « LATIN CAPITAL LETTER A »). Bien que la plupart des caractères abstraits de l'Unicode ne sont représentés que par un seul point code, il y a un certain nombre de caractères abstraits qui peuvent être représentés par une séquence de plus qu'un point code. Par exemple, le caractère abstrait « LATIN CAPITAL LETTER C WITH CEDILLA » peut être représenté comme un unique `caractère précomposé' au point code `U+00C7', ou en tant que séquence d'un `caractère de base' à la position `U+0043' (LATIN CAPITAL LETTER C) du code, suivi par un `caractère combiné' à la position `U+0327' (`COMBINING CEDILLA') du code.

Les opérateurs de comparaison des chaînes opèrent au niveau des points codes Unicode. Cela peut être déroutant pour des humains. Par exemple, @code{"\u00C7" == "\u0043\u0327"} renvoie @code{False}, bien que les deux chaînes représentent le même caractère abstrait "LATIN CAPITAL LETTER C WITH CEDILLA".

Pour comparer des chaînes au niveau des caractères abstraits (afin d'avoir quelque chose d'intuitif pour les humains), utilisez @ref{6bf,,unicodedata.normalize()}.
}.

Les chaînes de caractères et les séquences binaires ne peuvent pas être comparées directement.

@item 
Les séquences (instances de @ref{366,,tuple}, @ref{5fc,,list} ou @ref{930,,range}) peuvent être comparées uniquement entre instances de même type, en sachant que les intervalles (`range') ne gèrent pas la relation d'ordre. Le test d'égalité entre ces types renvoie faux et une comparaison entre instances de types différents lève une  @ref{522,,TypeError}.

Les séquences se comparent lexicographiquement en comparant les éléments correspondants. Les conteneurs natifs supposent généralement que les objets identiques sont égaux à eux-mêmes. Cela leur permet d'économiser les tests d’égalité pour des objets identiques afin d’améliorer les performances et de conserver leurs invariants internes.

L'ordre lexicographique pour les collections natives fonctionne comme suit :


@itemize -

@item 
Deux collections sont égales si elles sont du même type, ont la même longueur et si les éléments correspondants de chaque paire sont égaux. Par exemple, @code{[1,2] == (1,2)} est faux car les types sont différents.

@item 
Les collections qui gèrent la relation d'ordre sont ordonnées comme leur premier élément différent (par exemple, @code{[1,2,x] <= [1,2,y]} a la même valeur que @code{x <= y}). Si un élément n'a pas de correspondant, la collection la plus courte est la plus petite (par exemple, @code{[1,2] < [1,2,3]} est vrai).
@end itemize

@item 
Les tableaux de correspondances (instances de @ref{253,,dict}) sont égales si et seulement si toutes leurs paires @code{(clé, valeur)} sont égales.  L'égalité des clés et des valeurs met en œuvre la réflexivité.

Les comparaisons (@code{<}, @code{>}, @code{<=} et @code{>=}) lèvent @ref{522,,TypeError}.

@item 
Les ensembles (instances de @ref{5c3,,set} ou @ref{5c4,,frozenset}) peuvent être comparés au sein de leur propre type et entre types différents.

Les opérateurs d'inclusion et de sur-ensemble sont définis. Ces relations ne sont pas des relations d'ordre total (par exemple, les deux ensembles @code{@{1,2@}} et @code{@{2,3@}} ne sont pas égaux, l'un n'est pas inclus dans l'autre, l'un n'est pas un sur-ensemble de l'autre). Ainsi, les ensembles ne sont pas des arguments appropriés pour les fonctions qui dépendent d'un ordre total (par exemple, les fonctions @ref{ef3,,min()}, @ref{ef4,,max()} et @ref{bbc,,sorted()} produisent des résultats indéfinis si on leur donne des listes d'ensembles en entrée).

La comparaison des ensembles met en œuvre la réflexivité des éléments.

@item 
La plupart des autres types natifs n'implémentent pas de méthodes de comparaisons, ils héritent donc du comportement par défaut.
@end itemize

Les classes définies par l'utilisateur qui particularisent les opérations de comparaison doivent, si possible, respecter quelques règles pour la cohérence :


@itemize *

@item 
Le test d'égalité doit être réflexif. En d'autres termes, des objets identiques doivent être égaux :

@quotation

@code{x is y} implique @code{x == y}
@end quotation

@item 
La comparaison doit être symétrique. En d'autres termes, les expressions suivantes doivent donner le même résultat :

@quotation

@code{x == y} et @code{y == x}

@code{x != y} et @code{y != x}

@code{x < y} et @code{y > x}

@code{x <= y} et @code{y >= x}
@end quotation

@item 
La comparaison doit être transitive. Les exemples suivants (liste non exhaustive) illustrent ce concept :

@quotation

@code{x > y and y > z} implique @code{x > z}

@code{x < y and y <= z} implique @code{x < z}
@end quotation

@item 
Si vous inversez la comparaison, cela doit en produire la négation booléenne. En d'autres termes, les expressions suivantes doivent produire le même résultat :

@quotation

@code{x == y} et @code{not x != y}

@code{x < y} et @code{not x >= y} (pour une relation d'ordre total)

@code{x > y} et @code{not x <= y} (pour une relation d'ordre total)
@end quotation

Ces deux dernières expressions s'appliquent pour les collections totalement ordonnées (par exemple, les séquences mais pas les ensembles ou les tableaux de correspondances). Regardez aussi le décorateur @ref{f2d,,total_ordering()}.

@item 
Le résultat de @ref{5d5,,hash()} doit être cohérent avec l'égalité. Les objets qui sont égaux doivent avoir la même empreinte ou être marqués comme non-hachables.
@end itemize

Python ne vérifie pas ces règles de cohérence. En fait, l'utilisation de valeurs non numériques est un exemple de non-respect de ces règles.
@anchor{reference/expressions in}@anchor{2e8}@anchor{reference/expressions not-in}@anchor{61a}
@node Opérations de tests d’appartenance à un ensemble,Comparaisons d'identifiants,Comparaisons de valeurs,Comparaisons
@anchor{reference/expressions membership-test-details}@anchor{1f16}@anchor{reference/expressions membership-test-operations}@anchor{1ffa}
@subsubsection Opérations de tests d’appartenance à un ensemble


Les opérateurs @ref{2e8,,in} et @ref{61a,,not in} testent l’appartenance. @code{x in s} s’évalue à @code{True} si `x' appartient à `s' et à @code{False} sinon. @code{x not in s} renvoie la négation de @code{x in s}. Tous les types séquences et ensembles natifs gèrent ces opérateurs, ainsi que les dictionnaires pour lesquels @code{in} teste si dictionnaire possède une clé donnée. Pour les types conteneurs tels que les listes, `n'-uplets (`tuple'), ensembles (`set'), ensembles figés (`frozen set'), dictionnaires (`dict') ou `collections.deque', l’expression @code{x in y} est équivalente à @code{any(x is e or x == e for e in y)}.

Pour les chaînes de caractères et chaînes d'octets, @code{x in y} vaut @code{True} si et seulement si `x' est une sous-chaîne de `y'. Un test équivalent est @code{y.find(x) != -1}. Une chaîne vide est considérée comme une sous-chaîne de toute autre chaîne, ainsi @code{"" in "abc"} renvoie @code{True}.

For user-defined classes which define the @ref{1ee0,,__contains__()} method, @code{x in
y} returns @code{True} if @code{y.__contains__(x)} returns a true value, and
@code{False} otherwise.

For user-defined classes which do not define @ref{1ee0,,__contains__()} but do define
@ref{1ede,,__iter__()}, @code{x in y} is @code{True} if some value @code{z}, for which the
expression @code{x is z or x == z} is true, is produced while iterating over @code{y}.
If an exception is raised during the iteration, it is as if @ref{2e8,,in} raised
that exception.

Lastly, the old-style iteration protocol is tried: if a class defines
@ref{280,,__getitem__()}, @code{x in y} is @code{True} if and only if there is a non-negative
integer index `i' such that @code{x is y[i] or x == y[i]}, and no lower integer index
raises the @ref{14eb,,IndexError} exception.  (If any other exception is raised, it is as
if @ref{2e8,,in} raised that exception).

@geindex operator;in
@geindex operator;not in
@geindex membership;test
@geindex object;sequence

L'opérateur @ref{61a,,not in} est défini comme produisant le contraire de @ref{2e8,,in}.

@geindex operator;is
@geindex operator;is not
@geindex identity;test
@anchor{reference/expressions is}@anchor{2e9}
@node Comparaisons d'identifiants,,Opérations de tests d’appartenance à un ensemble,Comparaisons
@anchor{reference/expressions identity-comparisons}@anchor{1ffb}@anchor{reference/expressions is-not}@anchor{1ffc}
@subsubsection Comparaisons d'identifiants


Les opérateurs @ref{2e9,,is} et @ref{1ffc,,is not} testent l'égalité des identifiants des objets : @code{x is y} est vrai si et seulement si `x' et `y' sont le même objet. L'identifiant d'un objet est déterminé en utilisant la fonction @ref{13d9,,id()}. @code{x is not y} renvoie le résultat contraire de l'égalité des identifiants @footnote{
En raison du ramasse-miettes automatique et de la nature dynamique des descripteurs, vous pouvez être confronté à un comportement semblant bizarre lors de certaines utilisations de l'opérateur @ref{2e9,,is}, par exemple si cela implique des comparaisons entre des méthodes d'instances ou des constantes. Allez vérifier dans la documentation pour plus d'informations.
}.
@anchor{reference/expressions booleans}@anchor{1ffd}@anchor{reference/expressions and}@anchor{2e5}@anchor{reference/expressions or}@anchor{2ea}
@node Opérations booléennes,Expressions d'affectation,Comparaisons,Expressions
@anchor{reference/expressions boolean-operations}@anchor{1ffe}@anchor{reference/expressions not}@anchor{1fff}
@subsection Opérations booléennes


@geindex Conditional;expression
@geindex Boolean;operation

@example
@anchor{reference/expressions grammar-token-python-grammar-or_test}@anchor{2000}or_test  ::= and_test | or_test "or" and_test
@anchor{reference/expressions grammar-token-python-grammar-and_test}@anchor{2001}and_test ::= not_test | and_test "and" not_test
@anchor{reference/expressions grammar-token-python-grammar-not_test}@anchor{2002}not_test ::= comparison | "not" not_test
@end example

In the context of Boolean operations, and also when expressions are used by
control flow statements, the following values are interpreted as false:
@code{False}, @code{None}, numeric zero of all types, and empty strings and containers
(including strings, tuples, lists, dictionaries, sets and frozensets).  All
other values are interpreted as true.  User-defined objects can customize their
truth value by providing a @ref{12b3,,__bool__()} method.

@geindex operator;not

L'opérateur @ref{1fff,,not} produit @code{True} si son argument est faux, @code{False} sinon.

@geindex operator;and

L'expression @code{x and y} commence par évaluer `x' ; si `x' est faux, sa valeur est renvoyée ; sinon, `y' est évalué et la valeur résultante est renvoyée.

@geindex operator;or

L'expression @code{x or y} commence par évaluer `x' ; si `x' est vrai, sa valeur est renvoyée ; sinon, `y' est évalué et la valeur résultante est renvoyée.

Notez que ni @ref{2e5,,and} ni @ref{2ea,,or} ne restreignent la valeur et le type qu'ils renvoient à @code{False} et @code{True} : ils renvoient le dernier argument évalué. Ceci peut être utile, par exemple : si une chaîne @code{s} doit être remplacée par une valeur par défaut si elle est vide, l'expression @code{s or 'truc'} produit la valeur voulue. Comme @ref{1fff,,not} doit créer une nouvelle valeur, il renvoie une valeur booléenne quel que soit le type de son argument (par exemple, @code{not 'truc'} produit @code{False} plutôt que @code{'@w{'}}.

@geindex ;= (colon equals)
@geindex assignment expression
@geindex walrus operator
@geindex named expression
@geindex assignment;expression

@node Expressions d'affectation,Expressions conditionnelles,Opérations booléennes,Expressions
@anchor{reference/expressions assignment-expressions}@anchor{2003}@anchor{reference/expressions id15}@anchor{2004}
@subsection Expressions d'affectation


@example
@anchor{reference/expressions grammar-token-python-grammar-assignment_expression}@anchor{1f62}assignment_expression ::= [identifier ":="] expression
@end example

Une expression d'affectation (parfois aussi appelée « expression nommée » ou « expression morse ») affecte l'@ref{2005,,expression} à un @ref{1e1c,,identifiant} et renvoie la valeur de l'@ref{2005,,expression}.

Une utilisation classique concerne les correspondances d'expressions rationnelles :

@example
if matching := pattern.search(data):
    do_something(matching)
@end example

Ou lorsqu'on traite le contenu d'un fichier par morceaux :

@example
while chunk := file.read(9000):
    process(chunk)
@end example

Assignment expressions must be surrounded by parentheses when
used as expression statements and when used as sub-expressions in
slicing, conditional, lambda,
keyword-argument, and comprehension-if expressions and
in @code{assert}, @code{with}, and @code{assignment} statements.
In all other places where they can be used, parentheses are not required,
including in @code{if} and @code{while} statements.


Ajouté dans la version 3.8: Voir la 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} pour plus de détails sur les expressions d’affectation.


@node Expressions conditionnelles,Expressions lambda,Expressions d'affectation,Expressions
@anchor{reference/expressions conditional-expressions}@anchor{2006}@anchor{reference/expressions if-expr}@anchor{2007}
@subsection Expressions conditionnelles


@geindex conditional;expression
@geindex ternary;operator
@geindex if;conditional expression
@geindex else;conditional expression

@example
@anchor{reference/expressions grammar-token-python-grammar-conditional_expression}@anchor{2008}conditional_expression ::= or_test ["if" or_test "else" expression]
@anchor{reference/expressions grammar-token-python-grammar-expression}@anchor{2005}expression             ::= conditional_expression | lambda_expr
@end example

Les expressions conditionnelles (parfois appelées « opérateur ternaire ») sont les moins prioritaires de toutes les opérations Python.

L'expression @code{x if C else y} commence par évaluer la condition `C'. Si `C' est vrai, alors `x' est évalué et sa valeur est renvoyée ; sinon, `y' est évalué et sa valeur est renvoyée.

Voir la 
@geindex Python Enhancement Proposals; PEP 308
PEP 308@footnote{https://peps.python.org/pep-0308/} pour plus de détails sur les expressions conditionnelles.
@anchor{reference/expressions lambdas}@anchor{2009}
@node Expressions lambda,Listes d'expressions,Expressions conditionnelles,Expressions
@anchor{reference/expressions id16}@anchor{200a}@anchor{reference/expressions lambda}@anchor{127a}
@subsection Expressions lambda


@geindex lambda;expression
@geindex lambda;form
@geindex anonymous;function
@geindex ; (colon);lambda expression

@example
@anchor{reference/expressions grammar-token-python-grammar-lambda_expr}@anchor{200b}lambda_expr ::= "lambda" [parameter_list] ":" expression
@end example

Les expressions lambda sont utilisées pour créer des fonctions anonymes. L'expression @code{lambda parameters: expression} produit un objet fonction. Cet objet anonyme se comporte comme un objet fonction défini par :

@example
def <lambda>(parameters):
    return expression
@end example

Voir la section @ref{1bc4,,Définition de fonctions} pour la syntaxe des listes de paramètres. Notez que les fonctions créées par des expressions lambda ne peuvent pas contenir d'instructions ou d'annotations.

@node Listes d'expressions,Ordre d'évaluation,Expressions lambda,Expressions
@anchor{reference/expressions expression-lists}@anchor{200c}@anchor{reference/expressions exprlists}@anchor{d6b}
@subsection Listes d'expressions


@geindex expression;list
@geindex @comma{} (comma);expression list

@example
@anchor{reference/expressions grammar-token-python-grammar-starred_expression}@anchor{200d}starred_expression       ::= ["*"] or_expr
@anchor{reference/expressions grammar-token-python-grammar-flexible_expression}@anchor{200e}flexible_expression      ::= assignment_expression | starred_expression
@anchor{reference/expressions grammar-token-python-grammar-flexible_expression_list}@anchor{200f}flexible_expression_list ::= flexible_expression ("," flexible_expression)* [","]
@anchor{reference/expressions grammar-token-python-grammar-starred_expression_list}@anchor{2010}starred_expression_list  ::= starred_expression ("," starred_expression)* [","]
@anchor{reference/expressions grammar-token-python-grammar-expression_list}@anchor{2011}expression_list          ::= expression ("," expression)* [","]
@anchor{reference/expressions grammar-token-python-grammar-yield_list}@anchor{1fbc}yield_list               ::= expression_list | starred_expression "," [starred_expression_list]
@end example

@geindex object;tuple

Sauf lorsqu'elle fait partie d'un agencement de liste ou d'ensemble, une liste d'expressions qui contient au moins une virgule produit un `n'-uplet. La longueur du `n'-uplet est le nombre d'expressions dans la liste. Les expressions sont évaluées de la gauche vers la droite.

@geindex iterable;unpacking
@geindex * (asterisk);in expression lists

Un astérisque @code{*} indique `dépaquetage d'itérable' (`iterable unpacking' en anglais). Son opérande doit être un @ref{1205,,iterable}. L'itérable est développé en une séquence d'éléments qui sont inclus dans un nouvel objet `n'-uplet, liste ou ensemble à l'emplacement du dépaquetage.


Ajouté dans la version 3.5: dépaquetage d'itérables dans les listes d'expressions, proposé à l'origine par la 
@geindex Python Enhancement Proposals; PEP 448
PEP 448@footnote{https://peps.python.org/pep-0448/}.



Ajouté dans la version 3.11: Any item in an expression list may be starred. See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}.


@geindex trailing;comma

A trailing comma is required only to create a one-item tuple,
such as @code{1,}; it is optional in all other cases.
A single expression without a
trailing comma doesn't create a tuple, but rather yields the value of that
expression. (To create an empty tuple, use an empty pair of parentheses:
@code{()}.)

@node Ordre d'évaluation,Priorités des opérateurs,Listes d'expressions,Expressions
@anchor{reference/expressions evalorder}@anchor{2012}@anchor{reference/expressions evaluation-order}@anchor{2013}
@subsection Ordre d'évaluation


@geindex evaluation;order

Python évalue les expressions de la gauche vers la droite. Remarquez que lors de l'évaluation d'une affectation, la partie droite de l'affectation est évaluée avant la partie gauche.

Dans les lignes qui suivent, les expressions sont évaluées suivant l'ordre arithmétique de leurs suffixes :

@example
expr1, expr2, expr3, expr4
(expr1, expr2, expr3, expr4)
@{expr1: expr2, expr3: expr4@}
expr1 + expr2 * (expr3 - expr4)
expr1(expr2, expr3, *expr4, **expr5)
expr3, expr4 = expr1, expr2
@end example

@node Priorités des opérateurs,,Ordre d'évaluation,Expressions
@anchor{reference/expressions operator-precedence}@anchor{2014}@anchor{reference/expressions operator-summary}@anchor{2015}
@subsection Priorités des opérateurs


@geindex operator;precedence

Le tableau suivant résume les priorités des opérateurs en Python, du plus prioritaire (portée la plus courte) au moins prioritaire (portée la plus grande). Les opérateurs qui sont dans la même case ont la même priorité. À moins que la syntaxe ne soit explicitement indiquée, les opérateurs sont binaires. Les opérateurs dans la même case regroupent de la gauche vers la droite (sauf pour la puissance et les expressions conditionnelles qui regroupent de la droite vers la gauche).

Notez que les comparaisons, les tests d'appartenance et les tests d'identifiants possèdent tous la même priorité et s'enchaînent de la gauche vers la droite comme décrit dans la section @ref{1ff5,,Comparaisons}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opérateur

@tab

Description

@item

@code{(expressions…)},

@code{[expressions…]}, @code{@{key: value…@}}, @code{@{expressions…@}}

@tab

Expression de liaison ou parenthèse, affichage de liste, affichage de dictionnaire, affichage de `set'

@item

@code{x[indice]}, @code{x[indice:indice]}, @code{x(arguments…)}, @code{x.attribut}

@tab

indiçage, tranches, appel, référence à un attribut

@item

@ref{1b7,,await x}

@tab

Expression @code{await}

@item

@code{**}

@tab

Puissance @footnote{
L'opérateur puissance @code{**} est moins prioritaire qu'un opérateur unaire arithmétique ou bit à bit sur sa droite. Ainsi, @code{2**-1} vaut @code{0.5}.
}

@item

@code{+x}, @code{-x}, @code{~x}

@tab

NOT (positif, négatif, bit à bit)

@item

@code{*}, @code{@@}, @code{/}, @code{//}, @code{%}

@tab

Multiplication, multiplication de matrices, division, division entière, reste @footnote{
L'opérateur @code{%} est aussi utilisé pour formater les chaînes de caractères ; il y possède la même priorité.
}

@item

@code{+}, @code{-}

@tab

Addition et soustraction

@item

@code{<<}, @code{>>}

@tab

décalages

@item

@code{&}

@tab

AND (bit à bit)

@item

@code{^}

@tab

XOR (bit à bit)

@item

@code{|}

@tab

OR (bit à bit)

@item

@ref{2e8,,in}, @ref{61a,,not in},
@ref{2e9,,is}, @ref{1ffc,,is not}, @code{<},
@code{<=}, @code{>}, @code{>=}, @code{!=}, @code{==}

@tab

Comparaisons, y compris les tests d'appartenance et les tests d'identifiants

@item

@ref{1fff,,not x}

@tab

NOT (booléen)

@item

@ref{2e5,,and}

@tab

AND (booléen)

@item

@ref{2ea,,or}

@tab

OR (booléen)

@item

@ref{2007,,if} -- @code{else}

@tab

Expressions conditionnelles

@item

@ref{127a,,lambda}

@tab

Expression lambda

@item

@code{:=}

@tab

Expression d'affectation

@end multitable


@subsubheading Notes


@node Les instructions simples,Instructions composées,Expressions,La référence du langage Python
@anchor{reference/simple_stmts doc}@anchor{2016}@anchor{reference/simple_stmts simple}@anchor{2017}@anchor{reference/simple_stmts simple-statements}@anchor{2018}
@section Les instructions simples


@geindex simple;statement

Une instruction simple est contenue dans une seule ligne logique. Plusieurs instructions simples peuvent être écrites sur une seule ligne, séparées par des points-virgules. La syntaxe d'une instruction simple est :

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-simple_stmt}@anchor{2019}simple_stmt ::= expression_stmt
                | assert_stmt
                | assignment_stmt
                | augmented_assignment_stmt
                | annotated_assignment_stmt
                | pass_stmt
                | del_stmt
                | return_stmt
                | yield_stmt
                | raise_stmt
                | break_stmt
                | continue_stmt
                | import_stmt
                | future_stmt
                | global_stmt
                | nonlocal_stmt
                | type_stmt
@end example

@menu
* Les expressions:: 
* Les assignations:: 
* L'instruction assert:: 
* L'instruction pass: L'instruction pass<2>. 
* L'instruction del: L'instruction del<2>. 
* L'instruction return:: 
* L'instruction yield:: 
* L'instruction raise:: 
* L'instruction break:: 
* L'instruction continue:: 
* L'instruction import:: 
* L'instruction global:: 
* L'instruction nonlocal:: 
* The type statement:: 

@end menu

@node Les expressions,Les assignations,,Les instructions simples
@anchor{reference/simple_stmts expression-statements}@anchor{201a}@anchor{reference/simple_stmts exprstmts}@anchor{201b}
@subsection Les expressions


@geindex expression;statement
@geindex expression;list

@geindex expression;list

Les expressions sont utilisées (généralement de manière interactive) comme instructions pour calculer et écrire des valeurs, appeler une procédure (une fonction dont le résultat renvoyé n'a pas d'importance ; en Python, les procédures renvoient la valeur @code{None}). D'autres utilisations des expressions sont autorisées et parfois utiles. La syntaxe pour une expression en tant qu'instruction est :

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-expression_stmt}@anchor{201c}expression_stmt ::= starred_expression
@end example

Ce genre d'instruction évalue la liste d'expressions (qui peut se limiter à une seule expression).

@geindex built-in function;repr
@geindex object;None
@geindex string;conversion
@geindex output
@geindex standard;output
@geindex writing;values
@geindex procedure;call

En mode interactif, si la valeur n'est pas @code{None}, elle est convertie en chaîne en utilisant la fonction native @ref{7e7,,repr()} et la chaîne résultante est écrite sur la sortie standard sur sa propre ligne. Si le résultat est @code{None}, rien n'est écrit ce qui est usuel pour les appels de procédures.

@node Les assignations,L'instruction assert,Les expressions,Les instructions simples
@anchor{reference/simple_stmts assignment}@anchor{1f5c}@anchor{reference/simple_stmts assignment-statements}@anchor{201d}
@subsection Les assignations


@geindex = (equals);assignment statement
@geindex assignment;statement
@geindex binding;name
@geindex rebinding;name
@geindex object;mutable
@geindex attribute;assignment

Les assignations sont utilisées pour lier ou relier des noms à des valeurs et modifier des attributs ou des éléments d'objets mutables :

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-assignment_stmt}@anchor{201e}assignment_stmt ::= (target_list "=")+ (starred_expression | yield_expression)
@anchor{reference/simple_stmts grammar-token-python-grammar-target_list}@anchor{201f}target_list     ::= target ("," target)* [","]
@anchor{reference/simple_stmts grammar-token-python-grammar-target}@anchor{2020}target          ::= identifier
                    | "(" [target_list] ")"
                    | "[" [target_list] "]"
                    | attributeref
                    | subscription
                    | slicing
                    | "*" target
@end example

Voir la section @ref{1fc4,,Primaires} pour la définition des syntaxes de `attributeref', `subscription' et `slicing'.

Une assignation évalue la liste d'expressions (gardez en mémoire que ce peut être une simple expression ou une liste dont les éléments sont séparés par des virgules, cette dernière produisant un `n'-uplet) et assigne l'unique objet résultant à chaque liste cible, de la gauche vers la droite.

@geindex target
@geindex target;list

Une assignation est définie récursivement en fonction de la forme de la cible (une liste). Quand la cible est une partie d'un objet mutable (une référence à un attribut, une sélection ou une tranche), l'objet mutable doit effectuer l'assignation au final et décider de sa validité, voire lever une exception si l'assignation n'est pas acceptable. Les règles suivies par les différents types et les exceptions levées sont données dans les définitions des types d'objets (voir la section @ref{1e6a,,Hiérarchie des types standards}).

@geindex target;list;assignment
@geindex @comma{} (comma);in target list
@geindex * (asterisk);in assignment target list
@geindex [] (square brackets);in assignment target list
@geindex () (parentheses);in assignment target list

L'assignation d'un objet à une liste cible, optionnellement entourée par des parenthèses ou des crochets, est définie récursivement comme suit.


@itemize *

@item 
Si la liste cible est une cible unique sans virgule de fin, optionnellement entre parenthèses, l'objet est assigné à cette cible.

@item 
Sinon :


@itemize *

@item 
Si la liste cible contient une cible préfixée par un astérisque, appelée cible `étoilée' (`starred target' en anglais) : l'objet doit être un itérable avec au moins autant d'éléments qu'il y a de cibles dans la liste cible, moins un. Les premiers éléments de l'itérable sont assignés, de la gauche vers la droite, aux cibles avant la cible étoilée. Les éléments de queue de l'itérable sont assignés aux cibles après la cible étoilée. Une liste des éléments restants dans l'itérable est alors assignée à la cible étoilée (cette liste peut être vide).

@item 
Sinon : l'objet doit être un itérable avec le même nombre d'éléments qu'il y a de cibles dans la liste cible ; les éléments sont assignés, de la gauche vers la droite, vers les cibles correspondantes.
@end itemize
@end itemize

L'assignation d'un objet vers une cible unique est définie récursivement comme suit.


@itemize *

@item 
Si la cible est une variable (un nom) :


@itemize *

@item 
si le nom n'apparaît pas dans une instruction @ref{188,,global} ou @ref{1285,,nonlocal} (respectivement) du bloc de code courant, le nom est lié à l'objet dans l'espace courant des noms locaux ;

@item 
sinon le nom est lié à l'objet dans l'espace des noms globaux ou dans un espace de nommage plus large déterminé par @ref{1285,,nonlocal}, respectivement.
@end itemize

@geindex destructor

Le lien du nom est modifié si le nom était déjà lié. Ceci peut faire que le compteur de références de l'objet auquel le nom était précédemment lié tombe à zéro, entrainant la dé-allocation de l'objet et l'appel de son destructeur (s'il existe).

@geindex attribute;assignment

@item 
Si la cible est une référence à un attribut : l'expression primaire de la référence est évaluée. Elle doit produire un objet avec des attributs que l'on peut assigner : si ce n'est pas le cas, une @ref{522,,TypeError} est levée. Python demande alors à cet objet d'assigner l'attribut donné ; si ce n'est pas possible, une exception est levée (habituellement, mais pas nécessairement, @ref{343,,AttributeError}).
@anchor{reference/simple_stmts attr-target-note}@anchor{2021}
Note : si l'objet est une instance de classe et que la référence à l'attribut apparaît des deux côtés de l'opérateur d'assignation, l'expression « à droite », @code{a.x} peut accéder soit à l'attribut d'instance ou (si cet attribut d'instance n'existe pas) à l'attribut de classe. L'expression cible « à gauche » @code{a.x} est toujours définie comme un attribut d'instance, en le créant si nécessaire. Ainsi, les deux occurrences de @code{a.x} ne font pas nécessairement référence au même attribut : si l'expression « à droite » fait référence à un attribut de classe, l'expression « à gauche » crée un nouvel attribut d'instance comme cible de l'assignation :

@example
class Cls:
    x = 3             # class variable
inst = Cls()
inst.x = inst.x + 1   # writes inst.x as 4 leaving Cls.x as 3
@end example

Cette description ne s'applique pas nécessairement aux attributs des descripteurs, telles que les propriétés créées avec @ref{192,,property()}.

@geindex subscription;assignment
@geindex object;mutable

@item 
Si la cible est une sélection : l'expression primaire de la référence est évaluée. Elle doit produire soit un objet séquence mutable (telle qu'une liste) ou un objet tableau de correspondances (tel qu'un dictionnaire). Ensuite, l'expression de la sélection est évaluée.

@geindex object;sequence
@geindex object;list

Si la primaire est un objet séquence mutable (telle qu'une liste), la sélection doit produire un entier. S'il est négatif, la longueur de la séquence lui est ajoutée. La valeur résultante doit être un entier positif ou nul, plus petit que la longueur de la séquence, et Python demande à la séquence d'assigner l'objet à l'élément se trouvant à cet indice. Si l'indice est hors limites, une @ref{14eb,,IndexError} est levée (une assignation à une sélection dans une séquence ne peut pas ajouter de nouveaux éléments à une liste).

@geindex object;mapping
@geindex object;dictionary

Si la primaire est un objet tableau de correspondances (tel qu'un dictionnaire), la sélection doit être d'un type compatible avec le type des clés ; Python demande alors au tableau de correspondances de créer un couple clé-valeur qui associe la sélection à l'objet assigné. Ceci peut remplacer une correspondance déjà existante pour une clé donnée ou insérer un nouveau couple clé-valeur.

For user-defined objects, the @ref{12a9,,__setitem__()} method is called with
appropriate arguments.

@geindex slicing;assignment

@item 
Si la cible est une tranche : l'expression primaire de la référence est évaluée. Elle doit produire un objet séquence mutable (telle qu'une liste). L'objet assigné doit être un objet séquence du même type. Ensuite, les expressions de la borne inférieure et de la borne supérieure sont évaluées, dans la mesure où elles sont spécifiées (les valeurs par défaut sont zéro et la longueur de la séquence). Les bornes doivent être des entiers. Si une borne est négative, la longueur de la séquence lui est ajoutée. Les bornes résultantes sont coupées pour être dans l'intervalle zéro -- longueur de la séquence, inclus. Finalement, Python demande à l'objet séquence de remplacer la tranche avec les éléments de la séquence à assigner. La longueur de la tranche peut être différente de la longueur de la séquence à assigner, ce qui modifie alors la longueur de la séquence cible, si celle-ci le permet.
@end itemize

`Particularité de l'implémentation CPython :' Dans l'implémentation actuelle, la syntaxe pour les cibles est similaire à celle des expressions. Toute syntaxe invalide est rejetée pendant la phase de génération de code, ce qui produit des messages d'erreurs moins détaillés.

Bien que la définition de l'assignation implique que le passage entre le côté gauche et le côté droit soient « simultanés » (par exemple, @code{a, b = b, a} permute les deux variables), le passage `à l'intérieur' des collections de variables que l'on assigne intervient de la gauche vers la droite, ce qui peut entraîner quelques confusions. Par exemple, le programme suivant affiche @code{[0, 2]} :

@example
x = [0, 1]
i = 0
i, x[i] = 1, 2         # i is updated, then x[i] is updated
print(x)
@end example


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3132

@item PEP 3132@footnote{https://peps.python.org/pep-3132/} -- dépaquetage étendu d'itérable

Spécification de la fonctionnalité @code{*cible}.
@end table


@menu
* Les assignations augmentées:: 
* Les assignations annotées:: 

@end menu

@node Les assignations augmentées,Les assignations annotées,,Les assignations
@anchor{reference/simple_stmts augassign}@anchor{2022}@anchor{reference/simple_stmts augmented-assignment-statements}@anchor{2023}
@subsubsection Les assignations augmentées


@geindex augmented;assignment
@geindex statement;assignment@comma{} augmented
@geindex +=;augmented assignment
@geindex -=;augmented assignment
@geindex *=;augmented assignment
@geindex /=;augmented assignment
@geindex %=;augmented assignment
@geindex &=;augmented assignment
@geindex ^=;augmented assignment
@geindex |=;augmented assignment
@geindex **=;augmented assignment
@geindex //=;augmented assignment
@geindex >>=;augmented assignment
@geindex <<=;augmented assignment

Une assignation augmentée est la combinaison, dans une seule instruction, d'une opération binaire et d'une assignation :

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-augmented_assignment_stmt}@anchor{2024}augmented_assignment_stmt ::= augtarget augop (expression_list | yield_expression)
@anchor{reference/simple_stmts grammar-token-python-grammar-augtarget}@anchor{2025}augtarget                 ::= identifier | attributeref | subscription | slicing
@anchor{reference/simple_stmts grammar-token-python-grammar-augop}@anchor{2026}augop                     ::= "+=" | "-=" | "*=" | "@@=" | "/=" | "//=" | "%=" | "**="
                              | ">>=" | "<<=" | "&=" | "^=" | "|="
@end example

Voir la section @ref{1fc4,,Primaires} pour la définition des syntaxes des trois derniers symboles.

Une assignation augmentée évalue la cible (qui, au contraire des assignations normales, ne peut pas être un dépaquetage) et la liste d'expressions, effectue l'opération binaire (spécifique au type d'assignation) sur les deux opérandes et assigne le résultat à la cible originale. La cible n'est évaluée qu'une seule fois.

An augmented assignment statement like @code{x += 1} can be rewritten as @code{x = x +
1} to achieve a similar, but not exactly equal effect. In the augmented
version, @code{x} is only evaluated once. Also, when possible, the actual operation
is performed `in-place', meaning that rather than creating a new object and
assigning that to the target, the old object is modified instead.

Au contraire des assignations normales, les assignations augmentées évaluent la partie gauche `avant' d'évaluer la partie droite. Par exemple, @code{a[i] += f(x)} commence par s'intéresser à @code{a[i]}, puis Python évalue @code{f(x)}, effectue l'addition et, enfin, écrit le résultat dans @code{a[i]}.

À l'exception de l'assignation de `n'-uplets et de cibles multiples dans une seule instruction, l'assignation effectuée par une assignation augmentée est traitée de la même manière qu'une assignation normale. De même, à l'exception du comportement possible `sur place', l'opération binaire effectuée par assignation augmentée est la même que les opérations binaires normales.

Pour les cibles qui sont des références à des attributs, la même @ref{2021,,mise en garde sur les attributs de classe et d'instances} s'applique que pour les assignations normales.

@node Les assignations annotées,,Les assignations augmentées,Les assignations
@anchor{reference/simple_stmts annassign}@anchor{2027}@anchor{reference/simple_stmts annotated-assignment-statements}@anchor{2028}
@subsubsection Les assignations annotées


@geindex annotated;assignment
@geindex statement;assignment@comma{} annotated
@geindex ; (colon);annotated variable

Une assignation @ref{d43,,annotée} est la combinaison, dans une seule instruction, d'une annotation de variable ou d'attribut et d'une assignation optionnelle :

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-annotated_assignment_stmt}@anchor{2029}annotated_assignment_stmt ::= augtarget ":" expression
                              ["=" (starred_expression | yield_expression)]
@end example

La différence avec une assignation normale (voir @ref{1f5c,,ci-dessus}) est qu'une seule cible est autorisée.

The assignment target is considered "simple" if it consists of a single
name that is not enclosed in parentheses.
For simple assignment targets, if in class or module scope,
the annotations are evaluated and stored in a special class or module
attribute @code{__annotations__}
that is a dictionary mapping from variable names (mangled if private) to
evaluated annotations. This attribute is writable and is automatically
created at the start of class or module body execution, if annotations
are found statically.

If the assignment target is not simple (an attribute, subscript node, or
parenthesized name), the annotation is evaluated if
in class or module scope, but not stored.

Si le nom est annoté dans la portée d'une fonction, alors ce nom est local à cette portée. Les annotations ne sont jamais évaluées et stockées dans les portées des fonctions.

If the right hand side is present, an annotated
assignment performs the actual assignment before evaluating annotations
(where applicable). If the right hand side is not present for an expression
target, then the interpreter evaluates the target except for the last
@ref{12a9,,__setitem__()} or @ref{1eb2,,__setattr__()} call.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} -- Syntaxe pour les annotations de variables

La proposition qui a ajouté la syntaxe pour annoter les types de variables (y compris les variables de classe et les variables d'instance), au lieu de les exprimer par le biais de commentaires.

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} -- Indices de type

La proposition qui a ajouté le module @ref{103,,typing} pour fournir une syntaxe standard pour les annotations de type qui peuvent être utilisées dans les outils d'analyse statique et les environnements de développement intégrés (`EDI').
@end table



Modifié dans la version 3.8: Dorénavant, côté droit des assignations annotées, peuvent figurer les mêmes expressions que pour les assignations normales. Auparavant, certaines expressions (comme des `n'-uplets sans parenthèse englobante) généraient des erreurs de syntaxe.


@node L'instruction assert,L'instruction pass<2>,Les assignations,Les instructions simples
@anchor{reference/simple_stmts assert}@anchor{955}@anchor{reference/simple_stmts the-assert-statement}@anchor{202a}
@subsection L'instruction @code{assert}


@geindex statement;assert
@geindex debugging;assertions
@geindex @comma{} (comma);expression list

Les instructions @code{assert} sont une manière pratique d'insérer des tests de débogage au sein d'un programme :

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-assert_stmt}@anchor{202b}assert_stmt ::= "assert" expression ["," expression]
@end example

La forme la plus simple, @code{assert expression}, est équivalente à :

@example
if __debug__:
    if not expression: raise AssertionError
@end example

La forme étendue, @code{assert expression1, expression2}, est équivalente à :

@example
if __debug__:
    if not expression1: raise AssertionError(expression2)
@end example

@geindex __debug__
@geindex exception;AssertionError

These equivalences assume that @ref{7c4,,__debug__} and @ref{694,,AssertionError} refer to
the built-in variables with those names.  In the current implementation, the
built-in variable @code{__debug__} is @code{True} under normal circumstances,
@code{False} when optimization is requested (command line option @ref{da2,,-O}).  The current
code generator emits no code for an @ref{955,,assert} statement when optimization is
requested at compile time.  Note that it is unnecessary to include the source
code for the expression that failed in the error message; it will be displayed
as part of the stack trace.

Assigner vers @ref{7c4,,__debug__} est illégal. La valeur de cette variable native est déterminée au moment où l'interpréteur démarre.

@node L'instruction pass<2>,L'instruction del<2>,L'instruction assert,Les instructions simples
@anchor{reference/simple_stmts pass}@anchor{1ba8}@anchor{reference/simple_stmts the-pass-statement}@anchor{202c}
@subsection L'instruction @code{pass}


@geindex statement;pass
@geindex null;operation
@geindex null;operation

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-pass_stmt}@anchor{202d}pass_stmt ::= "pass"
@end example

@ref{1ba8,,pass} est une opération vide --- quand elle est exécutée, rien ne se passe. Elle est utile comme bouche-trou lorsqu'une instruction est syntaxiquement requise mais qu'aucun code ne doit être exécuté. Par exemple :

@example
def f(arg): pass    # a function that does nothing (yet)

class C: pass       # a class with no methods (yet)
@end example

@node L'instruction del<2>,L'instruction return,L'instruction pass<2>,Les instructions simples
@anchor{reference/simple_stmts del}@anchor{1734}@anchor{reference/simple_stmts the-del-statement}@anchor{202e}
@subsection L'instruction @code{del}


@geindex statement;del
@geindex deletion;target
@geindex deletion;target;list

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-del_stmt}@anchor{202f}del_stmt ::= "del" target_list
@end example

La suppression est récursivement définie de la même manière que l'assignation. Plutôt que de détailler cela de manière approfondie, voici quelques indices.

La suppression d'une liste cible (`target_list' dans la grammaire ci-dessus) supprime récursivement chaque cible, de la gauche vers la droite.

@geindex statement;global
@geindex unbinding;name

La suppression d'un nom détruit le lien entre ce nom dans l'espace des noms locaux, ou l'espace des noms globaux si ce nom apparaît dans une instruction @ref{188,,global} dans le même bloc de code. Si le nom n'est pas lié, une exception @ref{428,,NameError} est levée.

@geindex attribute;deletion

La suppression d'une référence à un attribut, une sélection ou une tranche est passée à l'objet primaire concerné : la suppression d'une tranche est en général équivalente à l'assignation d'une tranche vide du type adéquat (mais ceci est au final déterminé par l'objet que l'on tranche).


Modifié dans la version 3.2: Auparavant, il était illégal de supprimer un nom dans l'espace des noms locaux si celui-ci apparaissait comme variable libre dans un bloc imbriqué.


@node L'instruction return,L'instruction yield,L'instruction del<2>,Les instructions simples
@anchor{reference/simple_stmts return}@anchor{9bc}@anchor{reference/simple_stmts the-return-statement}@anchor{2030}
@subsection L'instruction @code{return}


@geindex statement;return
@geindex function;definition
@geindex class;definition

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-return_stmt}@anchor{2031}return_stmt ::= "return" [expression_list]
@end example

@ref{9bc,,return} ne peut être placée qu'à l'intérieur d'une définition de fonction, pas à l'intérieur d'une définition de classe.

Si une liste d'expressions (`expression_list' dans la grammaire ci-dessus) est présente, elle est évaluée, sinon @code{None} est utilisée comme valeur par défaut.

@ref{9bc,,return} quitte l'appel à la fonction courante avec la liste d'expressions (ou @code{None}) comme valeur de retour.

@geindex keyword;finally

Quand @ref{9bc,,return} fait sortir d'une instruction @ref{6d3,,try} avec une clause @ref{9b8,,finally}, cette clause @code{finally} est exécutée avant de réellement quitter la fonction.

Dans une fonction génératrice, l'instruction @ref{9bc,,return} indique que le générateur est terminé et provoque la levée d'une @ref{be8,,StopIteration}. La valeur de retour (s'il y en a une) est utilisée comme argument pour construire l'exception @ref{be8,,StopIteration} et devient l'attribut @ref{1f4c,,StopIteration.value}.

Dans une fonction génératrice asynchrone, une instruction @ref{9bc,,return} vide indique que le générateur asynchrone est terminé et provoque la levée d'une @ref{19bb,,StopAsyncIteration}. Une instruction @code{return} non vide est une erreur de syntaxe dans une fonction génératrice asynchrone.

@node L'instruction yield,L'instruction raise,L'instruction return,Les instructions simples
@anchor{reference/simple_stmts the-yield-statement}@anchor{2032}@anchor{reference/simple_stmts yield}@anchor{9bb}
@subsection L'instruction @code{yield}


@geindex statement;yield
@geindex generator;function
@geindex generator;iterator
@geindex function;generator
@geindex exception;StopIteration

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-yield_stmt}@anchor{2033}yield_stmt ::= yield_expression
@end example

A @ref{9bb,,yield} statement is semantically equivalent to a @ref{1fb6,,yield expression}. The @code{yield} statement can be used to omit the
parentheses that would otherwise be required in the equivalent yield expression
statement. For example, the yield statements

@example
yield <expr>
yield from <expr>
@end example

sont équivalentes aux instructions expressions `yield' :

@example
(yield <expr>)
(yield from <expr>)
@end example

Yield expressions and statements are only used when defining a @ref{104a,,generator}
function, and are only used in the body of the generator function.  Using @ref{9bb,,yield}
in a function definition is sufficient to cause that definition to create a
generator function instead of a normal function.

Pour tous les détails sur la sémantique de @ref{9bb,,yield}, reportez-vous à la section @ref{1fb6,,Expressions yield}.

@node L'instruction raise,L'instruction break,L'instruction yield,Les instructions simples
@anchor{reference/simple_stmts raise}@anchor{5d7}@anchor{reference/simple_stmts the-raise-statement}@anchor{2034}
@subsection L'instruction @code{raise}


@geindex statement;raise
@geindex exception
@geindex raising;exception
@geindex __traceback__ (exception attribute)

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-raise_stmt}@anchor{2035}raise_stmt ::= "raise" [expression ["from" expression]]
@end example

Si aucune expression n'est présente, @ref{5d7,,raise} propage l'exception en cours de traitement, aussi dénommée `exception active'. Si aucune exception n'est active, une exception @ref{193,,RuntimeError} est levée, indiquant que c'est une erreur.

Sinon, @ref{5d7,,raise} évalue la première expression en tant qu'objet exception. Ce doit être une sous-classe ou une instance de @ref{5a5,,BaseException}. Si c'est une classe, l'instance de l'exception est obtenue en instanciant la classe sans argument (au moment voulu).

Le `type' de l'exception est la classe de l'instance de l'exception, la `value' est l'instance elle-même.

@geindex object;traceback

A traceback object is normally created automatically when an exception is raised
and attached to it as the @ref{12a4,,__traceback__} attribute.
You can create an exception and set your own traceback in one step using the
@ref{2036,,with_traceback()} exception method (which returns the
same exception instance, with its traceback set to its argument), like so:

@example
raise Exception("foo occurred").with_traceback(tracebackobj)
@end example

@geindex exception;chaining
@geindex __cause__ (exception attribute)
@geindex __context__ (exception attribute)

The @code{from} clause is used for exception chaining: if given, the second
`expression' must be another exception class or instance. If the second
expression is an exception instance, it will be attached to the raised
exception as the @ref{12a6,,__cause__} attribute (which is writable). If the
expression is an exception class, the class will be instantiated and the
resulting exception instance will be attached to the raised exception as the
@code{__cause__} attribute. If the raised exception is not handled, both
exceptions will be printed:

@example
>>> try:
...     print(1 / 0)
... except Exception as exc:
...     raise RuntimeError("Something bad happened") from exc
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("Something bad happened") from exc
RuntimeError: Something bad happened
@end example

A similar mechanism works implicitly if a new exception is raised when
an exception is already being handled.  An exception may be handled
when an @ref{189,,except} or @ref{9b8,,finally} clause, or a
@ref{5bc,,with} statement, is used.  The previous exception is then
attached as the new exception's @ref{12a5,,__context__} attribute:

@example
>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened")
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
    print(1 / 0)
          ~~^~~
ZeroDivisionError: division by zero

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
    raise RuntimeError("Something bad happened")
RuntimeError: Something bad happened
@end example

Exception chaining can be explicitly suppressed by specifying @ref{660,,None} in
the @code{from} clause:

@example
>>> try:
...     print(1 / 0)
... except:
...     raise RuntimeError("Something bad happened") from None
...
Traceback (most recent call last):
  File "<stdin>", line 4, in <module>
RuntimeError: Something bad happened
@end example

Des informations complémentaires sur les exceptions sont disponibles dans la section @ref{1f68,,Exceptions} et sur la gestion des exceptions dans la section @ref{6d3,,L'instruction try}.


Modifié dans la version 3.3: @ref{660,,None} est dorénavant autorisée en tant que @code{Y} dans @code{raise X from Y}.

Added the @ref{2037,,__suppress_context__} attribute to suppress
automatic display of the exception context.



Modifié dans la version 3.11: si la trace d'appels de l'exception active est modifiée dans une clause @ref{189,,except}, une instruction @code{raise} postérieure lève à nouveau l'exception avec la trace modifiée. Auparavant, l'exception était levée à nouveau avec la trace qu'elle avait au moment de son interception.


@node L'instruction break,L'instruction continue,L'instruction raise,Les instructions simples
@anchor{reference/simple_stmts break}@anchor{a97}@anchor{reference/simple_stmts the-break-statement}@anchor{2038}
@subsection L'instruction @code{break}


@geindex statement;break
@geindex statement;for
@geindex statement;while
@geindex loop;statement

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-break_stmt}@anchor{2039}break_stmt ::= "break"
@end example

Une instruction @ref{a97,,break} ne peut apparaître qu'à l'intérieur d'une boucle @ref{2e6,,for} ou @ref{1b92,,while}, mais pas dans une définition de fonction ou de classe à l'intérieur de cette boucle.

@geindex keyword;else
@geindex loop control;target

Elle termine la boucle la plus imbriquée, shuntant l'éventuelle clause @code{else} de la boucle.

Si une boucle @ref{2e6,,for} est terminée par un @ref{a97,,break}, la cible qui contrôle la boucle garde sa valeur.

@geindex keyword;finally

Quand @ref{a97,,break} passe le contrôle en dehors d'une instruction @ref{6d3,,try} qui comporte une clause @ref{9b8,,finally}, cette clause @code{finally} est exécutée avant de quitter la boucle.

@node L'instruction continue,L'instruction import,L'instruction break,Les instructions simples
@anchor{reference/simple_stmts continue}@anchor{9b7}@anchor{reference/simple_stmts the-continue-statement}@anchor{203a}
@subsection L'instruction @code{continue}


@geindex statement;continue
@geindex statement;for
@geindex statement;while
@geindex loop;statement
@geindex keyword;finally

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-continue_stmt}@anchor{203b}continue_stmt ::= "continue"
@end example

L'instruction @ref{9b7,,continue} ne peut apparaître qu'à l'intérieur d'une boucle @ref{2e6,,for} ou @ref{1b92,,while}, mais pas dans une définition de fonction ou de classe à l'intérieur de cette boucle. Elle fait continuer le flot d'exécution au prochain cycle de la boucle la plus imbriquée.

Quand @ref{9b7,,continue} passe le contrôle en dehors d'une instruction @ref{6d3,,try} qui comporte une clause @ref{9b8,,finally}, cette clause @code{finally} est exécutée avant de commencer le cycle suivant de la boucle.
@anchor{reference/simple_stmts import}@anchor{5cc}
@node L'instruction import,L'instruction global,L'instruction continue,Les instructions simples
@anchor{reference/simple_stmts from}@anchor{1289}@anchor{reference/simple_stmts the-import-statement}@anchor{203c}
@subsection L'instruction @code{import}


@geindex statement;import
@geindex module;importing
@geindex name;binding
@geindex keyword;from
@geindex keyword;as
@geindex exception;ImportError
@geindex @comma{} (comma);import statement

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-import_stmt}@anchor{203d}import_stmt     ::= "import" module ["as" identifier] ("," module ["as" identifier])*
                    | "from" relative_module "import" identifier ["as" identifier]
                    ("," identifier ["as" identifier])*
                    | "from" relative_module "import" "(" identifier ["as" identifier]
                    ("," identifier ["as" identifier])* [","] ")"
                    | "from" relative_module "import" "*"
@anchor{reference/simple_stmts grammar-token-python-grammar-module}@anchor{203e}module          ::= (identifier ".")* identifier
@anchor{reference/simple_stmts grammar-token-python-grammar-relative_module}@anchor{203f}relative_module ::= "."* module | "."+
@end example

L'instruction de base `import' (sans clause @ref{1289,,from}) est exécutée en deux étapes :


@enumerate 

@item 
trouve un module, le charge et l'initialise si nécessaire

@item 
définit un ou des noms (`name' dans la grammaire ci-dessus) dans l'espace des noms locaux de la portée où l'instruction @ref{5cc,,import} apparaît.
@end enumerate

Quand l'instruction contient plusieurs clauses (séparées par des virgules), les deux étapes sont menées séparément pour chaque clause, comme si les clauses étaient séparées dans des instructions d'importations individuelles.

Les détails de la première étape, de recherche et de chargement des modules, sont décrits largement dans la section relative au @ref{1e98,,système d'importation}, qui décrit également les différents types de paquets et modules qui peuvent être importés, de même que les points d'entrée pouvant être utilisés pour personnaliser le système d'importation. Notez que des erreurs dans cette étape peuvent indiquer soit que le module n'a pas été trouvé, soit qu'une erreur s'est produite lors de l'initialisation du module, ce qui comprend l'exécution du code du module.

Si le module requis est bien récupéré, il est mis à disposition de l'espace de nommage local suivant l'une des trois façons suivantes :

@geindex as;import statement


@itemize *

@item 
Si le nom du module est suivi par @code{as}, alors le nom suivant @code{as} est directement lié au module importé.

@item 
si aucun autre nom n'est spécifié et que le module en cours d'importation est un module de niveau le plus haut, le nom du module est lié dans l'espace des noms locaux au module importé ;

@item 
si le module en cours d'importation n'est `pas' un module de plus haut niveau, alors le nom du paquet de plus haut niveau qui contient ce module est lié dans l'espace des noms locaux au paquet de plus haut niveau. Vous pouvez accéder au module importé en utilisant son nom pleinement qualifié et non directement.
@end itemize

@geindex name;binding
@geindex from;import statement

La forme @ref{1289,,from} utilise un processus un peu plus complexe :


@enumerate 

@item 
trouve le module spécifié dans la clause @ref{1289,,from}, le charge et l'initialise si nécessaire ;

@item 
pour chaque nom spécifié dans les clauses @ref{5cc,,import} :


@enumerate 

@item 
vérifie si le module importé possède un attribut avec ce nom ;

@item 
si non, essaie d'importer un sous-module avec ce nom puis vérifie si le module importé possède lui-même cet attribut ;

@item 
si l'attribut n'est pas trouvé, une @ref{40f,,ImportError} est levée.

@item 
sinon, une référence à cette valeur est stockée dans l'espace des noms locaux, en utilisant le nom de la clause @code{as} si elle est présente, sinon en utilisant le nom de l'attribut.
@end enumerate
@end enumerate

Exemples :

@example
import foo                 # foo imported and bound locally
import foo.bar.baz         # foo, foo.bar, and foo.bar.baz imported, foo bound locally
import foo.bar.baz as fbb  # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as fbb
from foo.bar import baz    # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as baz
from foo import attr       # foo imported and foo.attr bound as attr
@end example

@geindex * (asterisk);import statement

Si la liste des noms est remplacée par une étoile (@code{'*'}), tous les noms publics définis dans le module sont liés dans l'espace des noms locaux de la portée où apparaît l'instruction @ref{5cc,,import}.

@geindex __all__ (optional module attribute)

Les `noms publics' définis par un module sont déterminés en cherchant dans l'espace de nommage du module une variable nommée @code{__all__} ; Si elle est définie, elle doit être une séquence de chaînes désignant les noms définis ou importés par ce module. Les noms donnés dans @code{__all__} sont tous considérés publics et doivent exister. Si @code{__all__} n'est pas définie, l'ensemble des noms publics contient tous les noms trouvés dans l'espace des noms du module qui ne commencent pas par un caractère souligné (@code{_}). @code{__all__} doit contenir toute l'API publique. Elle est destinée à éviter l'exportation accidentelle d'éléments qui ne font pas partie de l'API (tels que des modules de bibliothèques qui ont été importés et utilisés à l'intérieur du module).

La forme d'`import' avec astérisque --- @code{from module import *} --- est autorisée seulement au niveau du module. Si vous essayez de l'utiliser dans une définition de classe ou de fonction, cela lève une @ref{18b,,SyntaxError}.

@geindex relative;import

Quand vous spécifiez les modules à importer, vous n'avez pas besoin de spécifier les noms absolus des modules. Quand un module ou un paquet est contenu dans un autre paquet, il est possible d'effectuer une importation relative à l'intérieur du même paquet de plus haut niveau sans avoir à mentionner le nom du paquet. En utilisant des points en entête du module ou du paquet spécifié après @ref{1289,,from}, vous pouvez spécifier combien de niveaux vous souhaitez remonter dans la hiérarchie du paquet courant sans spécifier de nom exact. Un seul point en tête signifie le paquet courant où se situe le module qui effectue l'importation. Deux points signifient de remonter d'un niveau. Trois points, remonter de deux niveaux et ainsi de suite. Ainsi, si vous exécutez @code{from . import mod} dans un module du paquet @code{pkg}, vous importez finalement @code{pkg.mod}. Et si vous exécutez @code{from ..souspkg2 import mod} depuis @code{pkg.souspkg1}, vous importez finalement @code{pkg.souspkg2.mod}. La spécification des importations relatives se situe dans la section @ref{1f8b,,Importations relatives au paquet}.

@ref{501,,importlib.import_module()} est fournie pour gérer les applications qui déterminent dynamiquement les modules à charger.

Lève un @ref{1848,,évènement d'audit} avec les arguments @code{module}, @code{filename}, @code{sys.path}, @code{sys.meta_path}, @code{sys.path_hooks}.

@menu
* L'instruction future:: 

@end menu

@node L'instruction future,,,L'instruction import
@anchor{reference/simple_stmts future}@anchor{187}@anchor{reference/simple_stmts future-statements}@anchor{2040}
@subsubsection L'instruction future


@geindex future;statement
@geindex __future__;future statement

Une `instruction future' est une directive à l'attention du compilateur afin qu'un module particulier soit compilé en utilisant une syntaxe ou une sémantique qui sera disponible dans une future version de Python où cette fonctionnalité est devenue un standard.

L'instruction `future' a vocation à faciliter les migrations vers les futures versions de Python qui introduisent des changements incompatibles au langage. Cela permet l'utilisation de nouvelles fonctionnalités module par module avant qu'une version n'officialise cette fonctionnalité comme un standard.

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-future_stmt}@anchor{2041}future_stmt ::= "from" "__future__" "import" feature ["as" identifier]
                ("," feature ["as" identifier])*
                | "from" "__future__" "import" "(" feature ["as" identifier]
                ("," feature ["as" identifier])* [","] ")"
@anchor{reference/simple_stmts grammar-token-python-grammar-feature}@anchor{2042}feature     ::= identifier
@end example

Une instruction `future' doit apparaître en haut du module. Les seules lignes autorisées avant une instruction `future' sont :


@itemize *

@item 
la chaîne de documentation du module (si elle existe),

@item 
des commentaires,

@item 
des lignes vides et

@item 
d'autres instructions `future'.
@end itemize

La seule fonctionnalité qui nécessite l'utilisation de l'instruction @code{future} est @code{annotations} (voir la 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}).

Toutes les fonctionnalités (`feature' dans la grammaire ci-dessus) autorisées par l'instruction @code{future} sont toujours reconnues par Python 3. Cette liste comprend @code{absolute_import}, @code{division}, @code{generators}, @code{generator_stop}, @code{unicode_literals}, @code{print_function}, @code{nested_scopes} et @code{with_statement}. Elles sont toutes redondantes car elles sont de toute manière activées ; elles ne sont conservées que par souci de compatibilité descendante.

Une instruction `future' est reconnue et traitée spécialement au moment de la compilation : les modifications à la sémantique des constructions de base sont souvent implémentées en générant un code différent. Il peut même arriver qu'une nouvelle fonctionnalité ait une syntaxe incompatible (tel qu'un nouveau mot réservé) ; dans ce cas, le compilateur a besoin d'analyser le module de manière différente. De telles décisions ne peuvent pas être différées au moment de l'exécution.

Pour une version donnée, le compilateur sait quelles fonctionnalités ont été définies et lève une erreur à la compilation si une instruction `future' contient une fonctionnalité qui lui est inconnue.

La sémantique à l'exécution est la même que pour toute autre instruction d'importation : il existe un module standard @ref{0,,__future__}, décrit plus loin, qui est importé comme les autres au moment où l'instruction `future' est exécutée.

La sémantique particulière à l'exécution dépend des fonctionnalités apportées par l'instruction `future'.

Notez que l'instruction suivante est tout à fait normale :

@example
import __future__ [as name]
@end example

Ce n'est pas une instruction `future' ; c'est une instruction d'importation ordinaire qui n'a aucune sémantique particulière ou restriction de syntaxe.

Code compiled by calls to the built-in functions @ref{17d,,exec()} and @ref{190,,compile()}
that occur in a module @code{M} containing a future statement will, by default,
use the new syntax or semantics associated with the future statement.  This can
be controlled by optional arguments to @ref{190,,compile()} --- see the documentation
of that function for details.

Une instruction `future' entrée à l'invite de l'interpréteur interactif est effective pour le reste de la session de l'interpréteur. Si l'interpréteur est démarré avec l'option @ref{1491,,-i}, qu'un nom de script est passé pour être exécuté et que ce script contient une instruction `future', elle est effective pour la session interactive qui démarre après l'exécution du script.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} — retour vers le @code{__future__}

La proposition originale pour le mécanisme de @code{__future__}.
@end table


@node L'instruction global,L'instruction nonlocal,L'instruction import,Les instructions simples
@anchor{reference/simple_stmts global}@anchor{188}@anchor{reference/simple_stmts the-global-statement}@anchor{2043}
@subsection L'instruction @code{global}


@geindex statement;global
@geindex global;name;binding
@geindex @comma{} (comma);identifier list

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-global_stmt}@anchor{2044}global_stmt ::= "global" identifier ("," identifier)*
@end example

The @ref{188,,global} statement causes the listed identifiers to be interpreted
as globals. It would be impossible to assign to a global variable without
@code{global}, although free variables may refer to globals without being
declared global.

The @ref{188,,global} statement applies to the entire scope of a function or
class body. A @ref{18b,,SyntaxError} is raised if a variable is used or
assigned to prior to its global declaration in the scope.

@geindex built-in function;exec
@geindex built-in function;eval
@geindex built-in function;compile

`Note pour les programmeurs :' @ref{188,,global} est une directive à l'attention de l'analyseur syntaxique. Elle s'applique uniquement au code analysé en même temps que l'instruction @code{global}. En particulier, une instruction @code{global} contenue dans une chaîne ou un objet code fourni à la fonction native @ref{17d,,exec()} n'affecte pas le code `contenant' cet appel et le code contenu dans un telle chaîne n'est pas affecté par une instruction @code{global} placée dans le code contenant l'appel. Il en est de même pour les fonctions @ref{17e,,eval()} et @ref{190,,compile()}.

@node L'instruction nonlocal,The type statement,L'instruction global,Les instructions simples
@anchor{reference/simple_stmts nonlocal}@anchor{1285}@anchor{reference/simple_stmts the-nonlocal-statement}@anchor{2045}
@subsection L'instruction @code{nonlocal}


@geindex statement;nonlocal
@geindex @comma{} (comma);identifier list

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-nonlocal_stmt}@anchor{2046}nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*
@end example

When the definition of a function or class is nested (enclosed) within
the definitions of other functions, its nonlocal scopes are the local
scopes of the enclosing functions. The @ref{1285,,nonlocal} statement
causes the listed identifiers to refer to names previously bound in
nonlocal scopes. It allows encapsulated code to rebind such nonlocal
identifiers.  If a name is bound in more than one nonlocal scope, the
nearest binding is used. If a name is not bound in any nonlocal scope,
or if there is no nonlocal scope, a @ref{18b,,SyntaxError} is raised.

The @ref{1285,,nonlocal} statement applies to the entire scope of a function or
class body. A @ref{18b,,SyntaxError} is raised if a variable is used or
assigned to prior to its nonlocal declaration in the scope.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3104

@item PEP 3104@footnote{https://peps.python.org/pep-3104/} -- Accès à des noms en dehors de la portée locale

Les spécifications pour l'instruction @ref{1285,,nonlocal}.
@end table


`Programmer's note:' @ref{1285,,nonlocal} is a directive to the parser
and applies only to code parsed along with it.  See the note for the
@ref{188,,global} statement.

@node The type statement,,L'instruction nonlocal,Les instructions simples
@anchor{reference/simple_stmts the-type-statement}@anchor{2047}@anchor{reference/simple_stmts type}@anchor{421}
@subsection The @code{type} statement


@geindex statement;type

@example
@anchor{reference/simple_stmts grammar-token-python-grammar-type_stmt}@anchor{2048}type_stmt ::= 'type' identifier [type_params] "=" expression
@end example

The @code{type} statement declares a type alias, which is an instance
of @ref{43e,,typing.TypeAliasType}.

For example, the following statement creates a type alias:

@example
type Point = tuple[float, float]
@end example

This code is roughly equivalent to:

@example
annotation-def VALUE_OF_Point():
    return tuple[float, float]
Point = typing.TypeAliasType("Point", VALUE_OF_Point())
@end example

@code{annotation-def} indicates an @ref{186,,annotation scope}, which behaves
mostly like a function, but with several small differences.

The value of the
type alias is evaluated in the annotation scope. It is not evaluated when the
type alias is created, but only when the value is accessed through the type alias's
@code{__value__} attribute (see @ref{440,,Lazy evaluation}).
This allows the type alias to refer to names that are not yet defined.

Type aliases may be made generic by adding a @ref{2b0,,type parameter list}
after the name. See @ref{43f,,Generic type aliases} for more.

@code{type} is a @ref{7f6,,soft keyword}.


Ajouté dans la version 3.12.



@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 695

@item PEP 695@footnote{https://peps.python.org/pep-0695/} - Type Parameter Syntax

Introduced the @code{type} statement and syntax for
generic classes and functions.
@end table


@node Instructions composées,Composants de plus haut niveau,Les instructions simples,La référence du langage Python
@anchor{reference/compound_stmts doc}@anchor{2049}@anchor{reference/compound_stmts compound}@anchor{204a}@anchor{reference/compound_stmts compound-statements}@anchor{204b}
@section Instructions composées


@geindex compound;statement

Les instructions composées contiennent d'autres (groupes d’) instructions ; elles affectent ou contrôlent l'exécution de ces autres instructions d'une manière ou d'une autre. En général, une instruction composée couvre plusieurs lignes bien que, dans sa forme la plus simple, une instruction composée peut tenir sur une seule ligne.

Les instructions @ref{2e7,,if}, @ref{1b92,,while} et @ref{2e6,,for} implémentent les constructions classiques de contrôle de flux. @ref{6d3,,try} définit des gestionnaires d'exception et du code de nettoyage pour un groupe d'instructions, tandis que l'instruction @ref{5bc,,with} permet l'exécution de code d'initialisation et de finalisation autour d'un bloc de code. Les définitions de fonctions et de classes sont également, au sens syntaxique, des instructions composées.

@geindex clause
@geindex suite
@geindex ; (semicolon)

Une instruction composée comporte une ou plusieurs « clauses ». Une clause se compose d'un en-tête et d'une « suite ». Les en-têtes des clauses d'une instruction composée particulière sont toutes placées au même niveau d'indentation. Chaque en-tête de clause commence par un mot-clé spécifique et se termine par le caractère deux-points (@code{:}) ; une suite est un groupe d'instructions contrôlées par une clause ; une suite se compose, après les deux points de l'en-tête, soit d'une ou plusieurs instructions simples séparées par des points-virgules si elles sont sur la même ligne que l'en-tête, soit d'une ou plusieurs instructions en retrait sur les lignes suivantes. Seule cette dernière forme d'une suite peut contenir des instructions composées ; ce qui suit n'est pas licite, principalement parce qu'il ne serait pas clair de savoir à quelle clause @ref{2e7,,if} se rapporterait une clause @ref{18a,,else} placée en fin de ligne :

@example
if test1: if test2: print(x)
@end example

Notez également que le point-virgule se lie plus étroitement que le deux-points dans ce contexte, de sorte que dans l'exemple suivant, soit tous les appels @ref{f60,,print()} sont exécutés, soit aucun ne l'est :

@example
if x < y < z: print(x); print(y); print(z)
@end example

En résumé :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-compound_stmt}@anchor{204c}compound_stmt ::= if_stmt
                  | while_stmt
                  | for_stmt
                  | try_stmt
                  | with_stmt
                  | match_stmt
                  | funcdef
                  | classdef
                  | async_with_stmt
                  | async_for_stmt
                  | async_funcdef
@anchor{reference/compound_stmts grammar-token-python-grammar-suite}@anchor{204d}suite         ::= stmt_list NEWLINE | NEWLINE INDENT statement+ DEDENT
@anchor{reference/compound_stmts grammar-token-python-grammar-statement}@anchor{204e}statement     ::= stmt_list NEWLINE | compound_stmt
@anchor{reference/compound_stmts grammar-token-python-grammar-stmt_list}@anchor{204f}stmt_list     ::= simple_stmt (";" simple_stmt)* [";"]
@end example

@geindex NEWLINE token
@geindex DEDENT token
@geindex dangling;else

Notez que ces instructions se terminent toujours par un lexème @code{NEWLINE} suivi éventuellement d'un @code{DEDENT}. Notez également que les clauses facultatives qui suivent commencent toujours par un mot-clé qui ne peut pas commencer une instruction. Ainsi, il n'y a pas d'ambiguïté (le problème du @ref{18a,,else} dont on ne sait pas à quel @code{if} il est relié est résolu en Python en exigeant que des instructions @ref{2e7,,if} imbriquées soient indentées les unes par rapport aux autres).

L'agencement des règles de grammaire dans les sections qui suivent place chaque clause sur une ligne séparée pour plus de clarté.
@anchor{reference/compound_stmts if}@anchor{2e7}@anchor{reference/compound_stmts elif}@anchor{1b98}
@menu
* L'instruction if: L'instruction if<2>. 
* L'instruction while:: 
* L'instruction for: L'instruction for<2>. 
* L'instruction try:: 
* L'instruction with:: 
* L'instruction match: L'instruction match<2>. 
* Définition de fonctions:: 
* Définition de classes:: 
* Coroutines: Coroutines<2>. 
* Type parameter lists:: 

@end menu

@node L'instruction if<2>,L'instruction while,,Instructions composées
@anchor{reference/compound_stmts else}@anchor{18a}@anchor{reference/compound_stmts the-if-statement}@anchor{2050}
@subsection L'instruction @code{if}


@geindex statement;if
@geindex keyword;elif
@geindex keyword;else
@geindex ; (colon);compound statement

L'instruction @ref{2e7,,if} est utilisée pour exécuter des instructions en fonction d'une condition :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-if_stmt}@anchor{2051}if_stmt ::= "if" assignment_expression ":" suite
            ("elif" assignment_expression ":" suite)*
            ["else" ":" suite]
@end example

Elle sélectionne exactement une des suites en évaluant les expressions une par une jusqu'à ce qu'une soit vraie (voir la section @ref{1ffd,,Opérations booléennes} pour la définition de vrai et faux) ; ensuite cette suite est exécutée (et aucune autre partie de l'instruction @ref{2e7,,if} n'est exécutée ou évaluée). Si toutes les expressions sont fausses, la suite de la clause @ref{18a,,else}, si elle existe, est exécutée.

@node L'instruction while,L'instruction for<2>,L'instruction if<2>,Instructions composées
@anchor{reference/compound_stmts the-while-statement}@anchor{2052}@anchor{reference/compound_stmts while}@anchor{1b92}
@subsection L'instruction @code{while}


@geindex statement;while
@geindex keyword;else
@geindex loop;statement
@geindex ; (colon);compound statement

L'instruction @ref{1b92,,while} est utilisée pour exécuter des instructions de manière répétée tant qu'une expression est vraie :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-while_stmt}@anchor{2053}while_stmt ::= "while" assignment_expression ":" suite
               ["else" ":" suite]
@end example

Python évalue l'expression de manière répétée et, tant qu'elle est vraie, exécute la première suite ; si l'expression est fausse (ce qui peut arriver même lors du premier test), la suite de la clause @code{else}, si elle existe, est exécutée et la boucle se termine.

@geindex statement;break
@geindex statement;continue

Une instruction @ref{a97,,break} exécutée dans la première suite termine la boucle sans exécuter la suite de la clause @code{else}. Une instruction @ref{9b7,,continue} exécutée dans la première suite saute le reste de la suite et retourne au test de l'expression.

@node L'instruction for<2>,L'instruction try,L'instruction while,Instructions composées
@anchor{reference/compound_stmts for}@anchor{2e6}@anchor{reference/compound_stmts the-for-statement}@anchor{2054}
@subsection L'instruction @code{for}


@geindex statement;for
@geindex keyword;in
@geindex keyword;else
@geindex target;list
@geindex loop;statement
@geindex object;sequence
@geindex ; (colon);compound statement

L'instruction @ref{2e6,,for} est utilisée pour itérer sur les éléments d'une séquence (par exemple une chaîne, un `n'-uplet ou une liste) ou un autre objet itérable :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-for_stmt}@anchor{2055}for_stmt ::= "for" target_list "in" starred_list ":" suite
             ["else" ":" suite]
@end example

L'expression @code{starred_list} n'est évaluée qu'une seule fois ; elle doit produire un objet @ref{1205,,iterable}. Un @ref{1aa,,iterator} est créé pour cet itérable. Le premier élément produit par l'itérateur est assigné à la liste cible (`target_list' dans la grammaire ci-dessus) en utilisant les règles des affectations (voir @ref{1f5c,,Les assignations}), puis la « suite » est exécutée. Lorsque les éléments de l'itérateur sont épuisés, la « suite » de la clause @code{else}, si elle existe, est exécutée et la boucle se termine.

@geindex statement;break
@geindex statement;continue

Une instruction @ref{a97,,break} exécutée dans la première suite termine la boucle sans exécuter la suite de la clause @code{else}. Une instruction @ref{9b7,,continue} exécutée dans la première suite saute le reste de la suite et continue avec l'élément suivant, ou avec la clause @code{else} s'il n'y a pas d'élément suivant.

La boucle @code{for} effectue des affectations aux variables de la liste cible, ce qui écrase toutes les affectations antérieures de ces variables, y compris celles effectuées dans la suite de la boucle @code{for} :

@example
for i in range(10):
    print(i)
    i = 5             # this will not affect the for-loop
                      # because i will be overwritten with the next
                      # index in the range
@end example

@geindex built-in function;range

Les noms dans la liste cible ne sont pas supprimés lorsque la boucle est terminée mais, si la séquence est vide, ils n'auront pas du tout été assignés par la boucle. Petite astuce : le type natif @ref{930,,range()} représente des suites arithmétiques immuables de nombres entiers ; par exemple, itérer sur @code{range(3)} renvoie successivement les entiers 0, 1 et 2.


Modifié dans la version 3.11: les éléments étoilés sont maintenant autorisés dans l'expression liste.


@node L'instruction try,L'instruction with,L'instruction for<2>,Instructions composées
@anchor{reference/compound_stmts the-try-statement}@anchor{2056}@anchor{reference/compound_stmts try}@anchor{6d3}
@subsection L'instruction @code{try}


@geindex statement;try
@geindex keyword;except
@geindex keyword;finally
@geindex keyword;else
@geindex keyword;as
@geindex ; (colon);compound statement

L'instruction @code{try} définit les gestionnaires d'exception ou le code de nettoyage pour un groupe d'instructions :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-try_stmt}@anchor{2057}try_stmt  ::= try1_stmt | try2_stmt | try3_stmt
@anchor{reference/compound_stmts grammar-token-python-grammar-try1_stmt}@anchor{2058}try1_stmt ::= "try" ":" suite
              ("except" [expression ["as" identifier]] ":" suite)+
              ["else" ":" suite]
              ["finally" ":" suite]
@anchor{reference/compound_stmts grammar-token-python-grammar-try2_stmt}@anchor{2059}try2_stmt ::= "try" ":" suite
              ("except" "*" expression ["as" identifier] ":" suite)+
              ["else" ":" suite]
              ["finally" ":" suite]
@anchor{reference/compound_stmts grammar-token-python-grammar-try3_stmt}@anchor{205a}try3_stmt ::= "try" ":" suite
              "finally" ":" suite
@end example

Vous trouvez des informations supplémentaires relatives aux exceptions dans la section @ref{1f68,,Exceptions} et, dans la section @ref{5d7,,L'instruction raise}, des informations relatives à l'utilisation de l'instruction @ref{5d7,,raise} pour produire des exceptions.

@menu
* clause except:: 
* clause except*:: 
* clause else:: 
* clause finally:: 

@end menu

@node clause except,clause except*,,L'instruction try
@anchor{reference/compound_stmts except}@anchor{189}@anchor{reference/compound_stmts except-clause}@anchor{205b}
@subsubsection clause @code{except}


The @code{except} clause(s) specify one or more exception handlers. When no
exception occurs in the @ref{6d3,,try} clause, no exception handler is executed.
When an exception occurs in the @code{try} suite, a search for an exception
handler is started. This search inspects the @code{except} clauses in turn
until one is found that matches the exception.
An expression-less @code{except} clause, if present, must be last;
it matches any exception.

For an @code{except} clause with an expression, the
expression must evaluate to an exception type or a tuple of exception types.
The raised exception matches an @code{except} clause whose expression evaluates
to the class or a @ref{1193,,non-virtual base class} of the exception object,
or to a tuple that contains such a class.

Si aucune clause @code{except} ne correspond à l'exception, la recherche d'un gestionnaire d'exception se poursuit dans le code englobant et dans la pile d'appels. @footnote{
L'exception est propagée à la pile d'appels à moins qu'il n'y ait une clause @ref{9b8,,finally} qui lève une autre exception, ce qui entraîne la perte de l'ancienne exception. Cette nouvelle exception entraîne la perte pure et simple de l'ancienne.
}

Si l'évaluation d'une expression dans l'en-tête d'une clause @code{except} lève une exception, la recherche initiale d'un gestionnaire est annulée et une recherche commence pour la nouvelle exception dans le code englobant et dans la pile d'appels (c'est traité comme si l'instruction @ref{6d3,,try} avait levé l'exception).

@geindex as;except clause

Lorsqu'une clause @code{except} correspond, l'exception est affectée à la cible précisée après le mot-clé @code{as} dans cette clause @code{except}, si cette cible existe, et la suite de clause @code{except} est exécutée. Toutes les clauses @code{except} doivent avoir un bloc exécutable. Lorsque la fin de ce bloc est atteinte, l'exécution continue normalement après l'ensemble de l'instruction @ref{6d3,,try} (cela signifie que si deux gestionnaires imbriqués existent pour la même exception, et que l'exception se produit dans la clause @code{try} du gestionnaire interne, le gestionnaire externe ne gère pas l'exception).

Lorsqu'une exception a été affectée en utilisant @code{as cible}, elle est effacée à la fin de la clause @code{except}. C'est comme si :

@example
except E as N:
    foo
@end example

avait été traduit en :

@example
except E as N:
    try:
        foo
    finally:
        del N
@end example

Cela veut dire que l'exception doit être assignée à un nom différent pour pouvoir s'y référer après la clause @code{except}. Les exceptions sont effacées parce qu'avec la trace de la pile d'appels qui leur est attachée, elles créent un cycle dans les pointeurs de références (avec le cadre de la pile), ce qui conduit à conserver tous les noms locaux de ce cadre en mémoire jusqu'au passage du ramasse-miettes.

@geindex module;sys
@geindex object;traceback

Avant qu'une suite de clauses @code{except} ne soit exécutée, l'exception est stockée dans le module @ref{d8,,sys}, où elle est accessible depuis le corps de la clause @code{except} en appelant @ref{676,,sys.exception()}. Lorsque vous quittez un gestionnaire d'exceptions, l'exception stockée dans le module @ref{d8,,sys} est réinitialisée à sa valeur précédente :

@example
>>> print(sys.exception())
None
>>> try:
...     raise TypeError
... except:
...     print(repr(sys.exception()))
...     try:
...          raise ValueError
...     except:
...         print(repr(sys.exception()))
...     print(repr(sys.exception()))
...
TypeError()
ValueError()
TypeError()
>>> print(sys.exception())
None
@end example

@geindex keyword;except_star

@node clause except*,clause else,clause except,L'instruction try
@anchor{reference/compound_stmts except-star}@anchor{5a2}@anchor{reference/compound_stmts id2}@anchor{205c}
@subsubsection clause @code{except*}


Les clauses @code{except*} sont utilisées pour gérer des @ref{1b4,,ExceptionGroup}. Le type de l'exception pour la correspondance est interprété de la même manière que dans le cas d'un @ref{189,,except} mais, dans le cas d'un groupe d'exceptions, il est possible d'avoir une correspondance partielle quand le type correspond à une ou plusieurs exceptions dans le groupe. Cela veut dire que plusieurs clauses @code{except*} peuvent être exécutées, chacune gérant une partie du groupe d'exceptions. Chaque clause ne s'exécute (au maximum) qu'une fois et gère un groupe d'exception constitué des exceptions qui correspondent. Chaque exception du groupe est gérée par une clause @code{except*} au plus, la première à laquelle elle correspond.

@example
>>> try:
...     raise ExceptionGroup("eg",
...         [ValueError(1), TypeError(2), OSError(3), OSError(4)])
... except* TypeError as e:
...     print(f'caught @{type(e)@} with nested @{e.exceptions@}')
... except* OSError as e:
...     print(f'caught @{type(e)@} with nested @{e.exceptions@}')
...
caught <class 'ExceptionGroup'> with nested (TypeError(2),)
caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
  + Exception Group Traceback (most recent call last):
  |   File "<stdin>", line 2, in <module>
  | ExceptionGroup: eg
  +-+---------------- 1 ----------------
    | ValueError: 1
    +------------------------------------
@end example

Any remaining exceptions that were not handled by any @code{except*}
clause are re-raised at the end, along with all exceptions that were
raised from within the @code{except*} clauses. If this list contains
more than one exception to reraise, they are combined into an exception
group.

Si l'exception levée n'est pas un groupe d'exceptions et que son type correspond à l'une des clauses @code{except*}, elle est interceptée et encapsulée par un groupe d'exceptions avec une chaîne de message vide. :

@example
>>> try:
...     raise BlockingIOError
... except* BlockingIOError as e:
...     print(repr(e))
...
ExceptionGroup('@w{'}, (BlockingIOError()))
@end example

An @code{except*} clause must have a matching expression; it cannot be @code{except*:}.
Furthermore, this expression cannot contain exception group types, because that would
have ambiguous semantics.

It is not possible to mix @ref{189,,except} and @code{except*}
in the same @ref{6d3,,try}.
@ref{a97,,break}, @ref{9b7,,continue} and @ref{9bc,,return}
cannot appear in an @code{except*} clause.

@geindex keyword;else
@geindex statement;return
@geindex statement;break
@geindex statement;continue

@node clause else,clause finally,clause except*,L'instruction try
@anchor{reference/compound_stmts else-clause}@anchor{205d}@anchor{reference/compound_stmts except-else}@anchor{205e}
@subsubsection clause @code{else}


La clause optionnelle @code{else} n'est exécutée que si l'exécution atteint la fin de la clause @ref{6d3,,try}, aucune exception n'a été levée, et aucun @ref{9bc,,return}, @ref{9b7,,continue}, ou @ref{a97,,break} ont étés exécutés. Les exceptions dans la clause @code{else} ne sont pas gérées par les clauses @ref{189,,except} précédentes.

@geindex keyword;finally

@node clause finally,,clause else,L'instruction try
@anchor{reference/compound_stmts finally}@anchor{9b8}@anchor{reference/compound_stmts finally-clause}@anchor{205f}
@subsubsection clause @code{finally}


Si @code{finally} est présente, elle définit un gestionnaire de « nettoyage ». La clause @ref{6d3,,try} est exécutée, y compris les clauses @ref{189,,except} et @ref{18a,,else}. Si une exception se produit dans l'une des clauses et n'est pas traitée, l'exception est temporairement sauvegardée. La clause @code{finally} est exécutée. S'il y a une exception sauvegardée, elle est levée à nouveau à la fin de la clause @code{finally}. Si la clause @code{finally} lève une autre exception, l'exception sauvegardée est définie comme le contexte de la nouvelle exception. Si la clause @code{finally} exécute une instruction @ref{9bc,,return}, @ref{a97,,break} ou @ref{9b7,,continue}, l'exception sauvegardée est jetée :

@example
>>> def f():
...     try:
...         1/0
...     finally:
...         return 42
...
>>> f()
42
@end example

L'information relative à l'exception n'est pas disponible pour le programme pendant l'exécution de la clause @code{finally}.

@geindex statement;return
@geindex statement;break
@geindex statement;continue

Lorsqu'une instruction @ref{9bc,,return}, @ref{a97,,break} ou @ref{9b7,,continue} est exécutée dans la suite d'une instruction @ref{6d3,,try} d'une construction @code{try}…@code{finally}, la clause @code{finally} est aussi exécutée « à la sortie ».

La valeur de retour d'une fonction est déterminée par la dernière instruction @ref{9bc,,return} exécutée. Puisque la clause @code{finally} s'exécute toujours, une instruction @code{return} exécutée dans le @code{finally} sera toujours la dernière clause exécutée :

@example
>>> def foo():
...     try:
...         return 'try'
...     finally:
...         return 'finally'
...
>>> foo()
'finally'
@end example


Modifié dans la version 3.8: Avant Python 3.8, une instruction @ref{9b7,,continue} n'était pas licite dans une clause @code{finally} en raison d'un problème dans l'implémentation.

@anchor{reference/compound_stmts with}@anchor{5bc}
@node L'instruction with,L'instruction match<2>,L'instruction try,Instructions composées
@anchor{reference/compound_stmts as}@anchor{2060}@anchor{reference/compound_stmts the-with-statement}@anchor{2061}
@subsection L'instruction @code{with}


@geindex statement;with
@geindex keyword;as
@geindex as;with statement
@geindex @comma{} (comma);with statement
@geindex ; (colon);compound statement

L'instruction @ref{5bc,,with} est utilisée pour encapsuler l'exécution d'un bloc avec des méthodes définies par un gestionnaire de contexte (voir la section @ref{1f40,,Gestionnaire de contexte With}). Cela permet d'utiliser de manière simple le patron de conception classique @ref{6d3,,try}…@ref{189,,except}…@ref{9b8,,finally}.

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-with_stmt}@anchor{2062}with_stmt          ::= "with" ( "(" with_stmt_contents ","? ")" | with_stmt_contents ) ":" suite
@anchor{reference/compound_stmts grammar-token-python-grammar-with_stmt_contents}@anchor{2063}with_stmt_contents ::= with_item ("," with_item)*
@anchor{reference/compound_stmts grammar-token-python-grammar-with_item}@anchor{2064}with_item          ::= expression ["as" target]
@end example

L'exécution de l'instruction @ref{5bc,,with} avec un seul « élément » (`item' dans la grammaire) se déroule comme suit :


@enumerate 

@item 
L'expression de contexte (l'expression donnée dans le @ref{2064,,with_item}) est évaluée pour obtenir un gestionnaire de contexte.

@item 
The context manager's @ref{5b2,,__enter__()} is loaded for later use.

@item 
The context manager's @ref{12de,,__exit__()} is loaded for later use.

@item 
The context manager's @ref{5b2,,__enter__()} method is invoked.

@item 
If a target was included in the @ref{5bc,,with} statement, the return value
from @ref{5b2,,__enter__()} is assigned to it.

@cartouche
@quotation Note 
The @ref{5bc,,with} statement guarantees that if the @ref{5b2,,__enter__()}
method returns without an error, then @ref{12de,,__exit__()} will always be
called. Thus, if an error occurs during the assignment to the target list,
it will be treated the same as an error occurring within the suite would
be. See step 7 below.
@end quotation
@end cartouche

@item 
La suite est exécutée.

@item 
The context manager's @ref{12de,,__exit__()} method is invoked.  If an exception
caused the suite to be exited, its type, value, and traceback are passed as
arguments to @ref{12de,,__exit__()}. Otherwise, three @ref{660,,None} arguments are
supplied.

If the suite was exited due to an exception, and the return value from the
@ref{12de,,__exit__()} method was false, the exception is reraised.  If the return
value was true, the exception is suppressed, and execution continues with the
statement following the @ref{5bc,,with} statement.

If the suite was exited for any reason other than an exception, the return
value from @ref{12de,,__exit__()} is ignored, and execution proceeds at the normal
location for the kind of exit that was taken.
@end enumerate

Le code suivant :

@example
with EXPRESSION as TARGET:
    SUITE
@end example

est sémantiquement équivalent à :

@example
manager = (EXPRESSION)
enter = type(manager).__enter__
exit = type(manager).__exit__
value = enter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not exit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        exit(manager, None, None, None)
@end example

Avec plus d'un élément, les gestionnaires de contexte sont traités comme si plusieurs instructions @ref{5bc,,with} étaient imbriquées :

@example
with A() as a, B() as b:
    SUITE
@end example

est sémantiquement équivalent à :

@example
with A() as a:
    with B() as b:
        SUITE
@end example

Vous pouvez aussi écrire des gestionnaires de contexte sur plusieurs lignes pour plus d'un élément si ceux-ci sont placés entre parenthèses. Par exemple :

@example
with (
    A() as a,
    B() as b,
):
    SUITE
@end example


Modifié dans la version 3.1: Prise en charge de multiples expressions de contexte.



Modifié dans la version 3.10: prise en charge des parenthèses pour pouvoir écrire l'instruction sur plusieurs lignes.



@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} — L'instruction « `with' »

La spécification, les motivations et des exemples de l'instruction @ref{5bc,,with} en Python.
@end table


@node L'instruction match<2>,Définition de fonctions,L'instruction with,Instructions composées
@anchor{reference/compound_stmts match}@anchor{7f7}@anchor{reference/compound_stmts the-match-statement}@anchor{2065}
@subsection L'instruction @code{match}


@geindex statement;match
@geindex keyword;case
@geindex pattern matching
@geindex keyword;if
@geindex keyword;as
@geindex match;case
@geindex as;match statement
@geindex ; (colon);compound statement


Ajouté dans la version 3.10.


L'instruction `match' est utilisée pour le filtrage par motif. Sa syntaxe est :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-match_stmt}@anchor{2066}match_stmt   ::= 'match' subject_expr ":" NEWLINE INDENT case_block+ DEDENT
@anchor{reference/compound_stmts grammar-token-python-grammar-subject_expr}@anchor{2067}subject_expr ::= star_named_expression "," star_named_expressions?
                 | named_expression
@anchor{reference/compound_stmts grammar-token-python-grammar-case_block}@anchor{2068}case_block   ::= 'case' patterns [guard] ":" block
@end example

@cartouche
@quotation Note 
cette section utilise les guillemets simples pour désigner les @ref{7f6,,mots-clés ad-hoc}.
@end quotation
@end cartouche

Le filtrage par motif prend un motif en entrée (@code{pattern} après @code{case}) et un champ de recherche (@code{subject_expr} après @code{match}). Le motif du filtre (qui peut contenir des sous-motifs de filtrage) est confronté au contenu du champ de recherche. La sortie est composée de :


@itemize *

@item 
un indicateur de réussite ou d'échec pour le filtrage (on peut aussi dire que le motif a réussi ou échoué) ;

@item 
la possibilité de lier les valeurs filtrées à un nom. Les pré-requis sont indiqués plus bas.
@end itemize

Les mots-clés @code{match} et @code{case} sont des @ref{7f6,,mots-clés ad-hoc}.


@subsubheading Voir aussi



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} — Spécifications pour le filtrage par motif

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} — Tutoriel pour le filtrage par motif
@end itemize


@menu
* Aperçu:: 
* Gardes:: 
* Bloc case attrape-tout:: 
* Filtres:: 

@end menu

@node Aperçu,Gardes,,L'instruction match<2>
@anchor{reference/compound_stmts overview}@anchor{2069}
@subsubsection Aperçu


Voici un aperçu du déroulement logique d'un filtrage par motif :


@enumerate 

@item 
L'expression confrontée aux filtres, @code{subject_expr}, est évaluée pour obtenir la valeur résultante. Si l'expression contient une virgule, un `n'-uplet est construit en utilisant les @ref{206a,,règles classiques}.

@item 
Chaque filtre des blocs @code{case_block} est confronté à la valeur résultante du champ de recherche. Les règles particulières pour la réussite ou l'échec sont décrites plus bas. La confrontation du filtre peut aussi conduire à lier un ou plusieurs noms présents dans le motif. Les règles pour lier les noms des motifs dépendent du type de filtre et sont décrites plus bas. `Le nommage effectué lors d'un filtrage par motif qui a réussi persiste à l'extérieur du bloc et le nom peut être utilisé après l'instruction' @code{match}.

@cartouche
@quotation Note 
en cas d'échec de la recherche, certains sous-filtres peuvent avoir réussi. Ne vous fiez pas aux nommages faits lors d'un filtrage qui a échoué. Inversement, ne vous fiez pas aux variables qui restent inchangées après un filtrage infructueux. Le comportement exact dépend de l'implémentation et peut varier. Il s'agit d'un choix intentionnel afin de permettre aux implémentations d'ajouter des optimisations.
@end quotation
@end cartouche

@item 
Si la recherche réussit, la garde correspondante (si elle existe) est évaluée. Dans ce cas, on est sûr que les nommages ont bien eu lieu.


@itemize *

@item 
Si la garde s'évalue à vrai ou s'il n'y a pas de garde, le @code{block} à l'intérieur du @code{case_block} est exécuté.

@item 
Sinon, le @code{case_block} est testé comme décrit ci-dessus.

@item 
S'il n'y a plus de bloc @code{case_block}, l'instruction est terminée.
@end itemize
@end enumerate

@cartouche
@quotation Note 
l'utilisateur ne doit jamais faire confiance à un filtre en cours d'évaluation. En fonction de l'implémentation, l'interpréteur peut mettre des valeurs en cache ou utiliser des optimisations qui évitent des réévaluations.
@end quotation
@end cartouche

Voici un exemple d'instruction de filtrage par motif :

@example
>>> flag = False
>>> match (100, 200):
...    case (100, 300):  # Mismatch: 200 != 300
...        print('Case 1')
...    case (100, 200) if flag:  # Successful match, but guard fails
...        print('Case 2')
...    case (100, y):  # Matches and binds y to 200
...        print(f'Case 3, y: @{y@}')
...    case _:  # Pattern not attempted
...        print('Case 4, I match anything!')
...
Case 3, y: 200
@end example

Dans cet exemple, @code{if flag} est une garde. Plus de détails sont fournis dans la prochaine section.

@node Gardes,Bloc case attrape-tout,Aperçu,L'instruction match<2>
@anchor{reference/compound_stmts guards}@anchor{206b}
@subsubsection Gardes


@geindex guard

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-guard}@anchor{206c}guard ::= "if" named_expression
@end example

Une garde (@code{guard} qui fait partie du @code{case}) doit s'évaluer à vrai pour que le code à l'intérieur du bloc @code{case} soit exécuté. Elle s'écrit sous la forme du mot-clé @ref{2e7,,if} suivi d'une expression.

Le déroulement logique d'un bloc @code{case} qui comprend une garde est le suivant :


@enumerate 

@item 
Vérification que le filtrage dans le bloc @code{case} est fructueux. Si le filtrage échoue, la garde n'est pas évaluée et on passe au bloc @code{case} suivant.

@item 
Si le filtrage est fructueux, évaluation de la garde.


@itemize *

@item 
Si la garde s'évalue à `vrai', le bloc est sélectionné.

@item 
Si la garde s'évalue à `faux', le bloc n'est pas sélectionné.

@item 
Si une exception est levée lors de l'évaluation de la garde, cette exception est propagée.
@end itemize
@end enumerate

Les gardes étant des expressions, il est possible qu'elles aient des effets secondaires. L'ordre d'évaluation des gardes est du premier au dernier bloc @code{case}, un à la fois, en sautant les blocs @code{case} dont la recherche de motif échouent. L'évaluation des gardes s'arrête dès qu'un bloc @code{case} est sélectionné.

@node Bloc case attrape-tout,Filtres,Gardes,L'instruction match<2>
@anchor{reference/compound_stmts irrefutable-case}@anchor{206d}@anchor{reference/compound_stmts irrefutable-case-blocks}@anchor{206e}
@subsubsection Bloc @code{case} attrape-tout


@geindex irrefutable case block
@geindex case block

Un bloc @code{case} attrape-tout est un bloc qui réussit toujours. Une instruction @code{match} ne peut avoir qu'un seul bloc attrape-tout, et ce doit être le dernier.

Un bloc @code{case} est considéré attrape-tout s'il n'y a pas de garde et que le motif est attrape-tout. Un motif est attrape-tout si l'on peut déterminer, simplement à partir de sa syntaxe, qu'il correspond toujours. Seuls les motifs suivants sont attrape-tout :


@itemize *

@item 
Les @ref{206f,,Filtres AS} pour lesquels la partie gauche est attrape-tout

@item 
Les @ref{2070,,Filtres OU} contenant au moins un filtre attrape-tout

@item 
Les @ref{2071,,Filtres de capture}

@item 
Les @ref{7f8,,Filtres attrape-tout}

@item 
les filtres attrape-tout entre parenthèses
@end itemize

@node Filtres,,Bloc case attrape-tout,L'instruction match<2>
@anchor{reference/compound_stmts patterns}@anchor{2072}
@subsubsection Filtres


@geindex ! patterns
@geindex AS pattern@comma{} OR pattern@comma{} capture pattern@comma{} wildcard pattern

@cartouche
@quotation Note 
Cette section utilise des notations grammaticales qui ne font pas partie du standard EBNF :


@itemize *

@item 
la notation @code{SEP.REGLE+} désigne @code{REGLE (SEP REGLE)*}

@item 
la notation @code{!REGLE} désigne la négation logique de l'assertion @code{REGLE}
@end itemize
@end quotation
@end cartouche

La syntaxe générale pour les filtres @code{patterns} est :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-patterns}@anchor{2073}patterns       ::= open_sequence_pattern | pattern
@anchor{reference/compound_stmts grammar-token-python-grammar-pattern}@anchor{2074}pattern        ::= as_pattern | or_pattern
@anchor{reference/compound_stmts grammar-token-python-grammar-closed_pattern}@anchor{2075}closed_pattern ::= | literal_pattern
                   | capture_pattern
                   | wildcard_pattern
                   | value_pattern
                   | group_pattern
                   | sequence_pattern
                   | mapping_pattern
                   | class_pattern
@end example

Les explications ci-dessous décrivent « en termes simples » ce qu'un modèle fait (merci à Raymond Hettinger pour son document qui a inspiré la plupart des descriptions). Notez que ces descriptions sont purement à fin d'illustration et peuvent ne `pas' être strictement conformes à l'implémentation sous-jacente. De plus, nous ne couvrons pas toutes les formes valides.

@menu
* Filtres OU:: 
* Filtres AS:: 
* Filtres littéraux:: 
* Filtres de capture:: 
* Filtres attrape-tout:: 
* Filtres par valeurs:: 
* Filtres de groupes:: 
* Filtres de séquences:: 
* Filtres associatifs:: 
* Filtres de classes:: 

@end menu

@node Filtres OU,Filtres AS,,Filtres
@anchor{reference/compound_stmts id3}@anchor{2076}@anchor{reference/compound_stmts or-patterns}@anchor{2070}
@subsubsection Filtres OU


Un filtre OU est composé de deux filtres ou plus séparés par des barres verticales @code{|}. La syntaxe est :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-or_pattern}@anchor{2077}or_pattern ::= "|".closed_pattern+
@end example

Seul le dernier sous-filtre peut être @ref{206d,,attrape-tout} et chaque sous-filtre doit être lié au même ensemble de noms pour éviter toute ambigüité.

Un filtre OU confronte chacun des sous-filtres à tour de rôle à la valeur du champ de recherche, jusqu'à ce que l'un d'eux réussisse. Le filtre OU réussit si l'un des sous-filtres a réussi, sinon il échoue.

En termes plus simples, @code{M1 | M2 | ...} teste le filtre par motif @code{M1}, s'il échoue il teste le filtre par motif @code{M2}, réussit immédiatement si l'un d'eux réussit, échoue dans le cas contraire.

@node Filtres AS,Filtres littéraux,Filtres OU,Filtres
@anchor{reference/compound_stmts as-patterns}@anchor{206f}@anchor{reference/compound_stmts id4}@anchor{2078}
@subsubsection Filtres AS


Un filtre AS confronte un filtre OU sur la gauche du mot-clé @ref{2060,,as} au champ de recherche. La syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-as_pattern}@anchor{2079}as_pattern ::= or_pattern "as" capture_pattern
@end example

Si le filtre OU échoue, le filtre AS échoue. Sinon, le filtre AS lie le champ de recherche au nom sur la droite du mot-clé @code{as} et réussit. @code{capture_pattern} ne peut pas être un @code{_}.

En termes simples, @code{M as NOM} filtre avec le motif @code{M} et, s'il réussit, définit @code{NOM = <subject>}.

@node Filtres littéraux,Filtres de capture,Filtres AS,Filtres
@anchor{reference/compound_stmts id5}@anchor{207a}@anchor{reference/compound_stmts literal-patterns}@anchor{207b}
@subsubsection Filtres littéraux


Un filtre littéral effectue une correspondance avec la plupart des @ref{1e28,,littéraux} en Python. La syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-literal_pattern}@anchor{207c}literal_pattern ::= signed_number
                    | signed_number "+" NUMBER
                    | signed_number "-" NUMBER
                    | strings
                    | "None"
                    | "True"
                    | "False"
@anchor{reference/compound_stmts grammar-token-python-grammar-signed_number}@anchor{207d}signed_number   ::= ["-"] NUMBER
@end example

La règle @code{strings} et le lexème @code{NUMBER} sont définis dans @ref{207e,,la grammaire de Python standard}. Les chaînes avec triples guillemets sont gérées. Les chaînes brutes et les chaînes d'octets sont gérées. Les @ref{997,,f-strings} ne sont pas gérées.

Les formes @code{signed_number '+' NUMBER} et @code{signed_number '-' NUMBER} permettent d'exprimer des @ref{1e5e,,nombres complexes} ; vous devez indiquer un nombre réel sur la gauche et un nombre imaginaire sur la droite. Par exemple, @code{3 + 4j}.

En termes simples, @code{LITERAL} réussit seulement si @code{<subject> == LITERAL}. Pour les singletons @code{None}, @code{True} et @code{False}, l'opérateur @ref{2e9,,is} est utilisé.

@node Filtres de capture,Filtres attrape-tout,Filtres littéraux,Filtres
@anchor{reference/compound_stmts capture-patterns}@anchor{2071}@anchor{reference/compound_stmts id6}@anchor{207f}
@subsubsection Filtres de capture


Un filtre de capture lie la valeur du champ de recherche à un nom. La syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-capture_pattern}@anchor{2080}capture_pattern ::= !'_' NAME
@end example

Un simple caractère souligné @code{_} n'est pas un filtre de capture (c'est ce que @code{!'_'} veut dire). C'est le motif pour désigner un filtre attrape-tout (lexème @code{wilcard_pattern}, voir plus bas).

Dans un filtre donné, un nom ne peut être lié qu'une seule fois. Par exemple, @code{case x, x: ...} est invalide mais @code{case [x] | x: ...} est autorisé.

Les filtres de capture réussissent toujours. La portée du lien est conforme aux règles définies pour l'opérateur d'affectation indiquées dans la 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} ; le nom devient une variable locale dans la fonction la plus intérieure à moins qu'il n'y ait une instruction @ref{188,,global} ou @ref{1285,,nonlocal} qui s'applique.

En termes simples, @code{NAME} réussit toujours et définit @code{NAME = <subject>}.

@node Filtres attrape-tout,Filtres par valeurs,Filtres de capture,Filtres
@anchor{reference/compound_stmts id7}@anchor{2081}@anchor{reference/compound_stmts wildcard-patterns}@anchor{7f8}
@subsubsection Filtres attrape-tout


Un filtre attrape-tout réussit toujours (quel que soit le champ de recherche) et ne lie aucun nom. La syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-wildcard_pattern}@anchor{2082}wildcard_pattern ::= '_'
@end example

@code{_} est un @ref{7f6,,mot-clé ad-hoc} dans un filtre par motif, mais seulement dans un filtre. Ailleurs, c'est un identifiant, comme d'habitude, même à l'intérieur d'une expression champ de recherche de @code{match}, d'une garde ou d'un bloc @code{case}.

En termes simples, @code{_} réussit toujours.

@node Filtres par valeurs,Filtres de groupes,Filtres attrape-tout,Filtres
@anchor{reference/compound_stmts id8}@anchor{2083}@anchor{reference/compound_stmts value-patterns}@anchor{2084}
@subsubsection Filtres par valeurs


Un filtre par valeur représente une valeur nommée de Python. Sa syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-value_pattern}@anchor{2085}value_pattern ::= attr
@anchor{reference/compound_stmts grammar-token-python-grammar-attr}@anchor{2086}attr          ::= name_or_attr "." NAME
@anchor{reference/compound_stmts grammar-token-python-grammar-name_or_attr}@anchor{2087}name_or_attr  ::= attr | NAME
@end example

Le nom qualifié dans le filtre est recherché en utilisant la @ref{1f5f,,méthode de résolution des noms} standard de Python. Le filtrage réussit si la valeur trouvée vérifie l'égalité avec la valeur du champ de recherche (en utilisant l'opérateur d'égalité @code{==}).

En termes plus simples, @code{NOM1.NOM2} réussit seulement si @code{<subject> == NOM1.NOM2}

@cartouche
@quotation Note 
si la même valeur apparaît plusieurs fois dans la même instruction @code{match}, l'interpréteur peut mettre en cache la première valeur trouvée et la réutiliser plutôt que de refaire une recherche. Ce cache est strictement limité à l'exécution de l'instruction @code{match} donnée.
@end quotation
@end cartouche

@node Filtres de groupes,Filtres de séquences,Filtres par valeurs,Filtres
@anchor{reference/compound_stmts group-patterns}@anchor{2088}@anchor{reference/compound_stmts id9}@anchor{2089}
@subsubsection Filtres de groupes


Un filtre de groupe permet au programmeur de souligner l’intention de regrouper des motifs en plaçant ceux-ci entre parenthèses. À part ça, il n’introduit aucune syntaxe supplémentaire. Sa syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-group_pattern}@anchor{208a}group_pattern ::= "(" pattern ")"
@end example

En termes plus simples, @code{(P)} équivaut à @code{P}.

@node Filtres de séquences,Filtres associatifs,Filtres de groupes,Filtres
@anchor{reference/compound_stmts id10}@anchor{208b}@anchor{reference/compound_stmts sequence-patterns}@anchor{208c}
@subsubsection Filtres de séquences


Un filtre de séquence contient des sous-filtres par motif dont chacun doit correspondre à un élément d’une séquence. La syntaxe est similaire au déballage d’une liste ou d’un `n'-uplet.

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-sequence_pattern}@anchor{208d}sequence_pattern       ::= "[" [maybe_sequence_pattern] "]"
                           | "(" [open_sequence_pattern] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-open_sequence_pattern}@anchor{208e}open_sequence_pattern  ::= maybe_star_pattern "," [maybe_sequence_pattern]
@anchor{reference/compound_stmts grammar-token-python-grammar-maybe_sequence_pattern}@anchor{208f}maybe_sequence_pattern ::= ",".maybe_star_pattern+ ","?
@anchor{reference/compound_stmts grammar-token-python-grammar-maybe_star_pattern}@anchor{2090}maybe_star_pattern     ::= star_pattern | pattern
@anchor{reference/compound_stmts grammar-token-python-grammar-star_pattern}@anchor{2091}star_pattern           ::= "*" (capture_pattern | wildcard_pattern)
@end example

Vous pouvez utiliser indifféremment des parenthèses @code{(...)} ou des crochets @code{[...]} pour encadrer les filtres à regrouper.

@cartouche
@quotation Note 
un filtre seul entre parenthèses qui ne se termine pas par une virgule (par exemple @code{(3 | 4)}) est un @ref{2088,,filtre de groupe}. En revanche, un filtre seul entre crochets (par exemple @code{[3 | 4]}) reste un filtre de séquence.
@end quotation
@end cartouche

Il peut y avoir au plus un sous-filtre étoilé (lexème @code{star_pattern}) dans un filtre de séquence. Le filtre étoilé peut se trouver à n’importe quelle position. S’il n’y en a pas, le filtre de séquence est un filtre de séquence à longueur fixe, sinon c’est un filtre de séquence à longueur variable.

Voici le déroulement logique d’un filtrage par motif de séquence sur une valeur du champ de recherche :


@enumerate 

@item 
Si la valeur du champ de recherche n’est pas une séquence @footnote{
Dans le filtrage par motif, une séquence est définie comme suit :


@itemize *

@item 
une classe qui hérite de @ref{11a1,,collections.abc.Sequence}

@item 
une classe Python qui a été enregistrée en tant que @ref{11a1,,collections.abc.Sequence}

@item 
une classe native dont le bit (CPython) @ref{1832,,Py_TPFLAGS_SEQUENCE} est à 1

@item 
une classe qui hérite d'une classe citée ci-dessus
@end itemize

Les classes suivantes de la bibliothèque standard sont des séquences :


@itemize *

@item 
@ref{19e,,array.array}

@item 
@ref{5c6,,collections.deque}

@item 
@ref{5fc,,list}

@item 
@ref{452,,memoryview}

@item 
@ref{930,,range}

@item 
@ref{366,,tuple}
@end itemize

@cartouche
@quotation Note 
Les champs de recherche du type @code{str}, @code{bytes} et @code{bytearray} ne correspondent pas avec des filtres de séquence.
@end quotation
@end cartouche
}, le filtre de séquence échoue.

@item 
Si la valeur du champ de recherche est une instance de @code{str}, @code{bytes} ou @code{bytearray}, le filtre de séquence échoue.

@item 
Les étapes suivantes dépendent de la longueur fixe ou non du filtre de séquence.

Si le filtre de séquence est de longueur fixe :


@enumerate 

@item 
Si la longueur de la séquence champ de recherche n’est pas égale au nombre de sous-filtres, le filtre de séquence échoue.

@item 
Les sous-filtres de la séquence sont confrontés aux éléments correspondants dans la séquence champ de recherche, de la gauche vers la droite. La recherche de correspondance s’arrête dès qu’un sous-filtre échoue. Si tous les sous-filtres réussissent la confrontation à l’élément du champ de recherche correspondant, le filtre de séquence réussit.
@end enumerate

Sinon, si le filtre de séquence est de longueur variable :


@enumerate 

@item 
Si la longueur de la séquence champ de recherche est plus petite que le nombre de sous-filtres sans étoile, le filtre de séquence échoue.

@item 
Les sous-filtres sans étoile du début sont confrontés aux éléments correspondants comme pour un filtre de séquences de longueur fixe.

@item 
Si les étapes précédentes ont réussi, le sous-filtre étoilé correspond à une liste formée des éléments restants du champ de recherche, en excluant les éléments restants qui correspondent à des sous-filtres sans étoile qui suivent le sous-filtre étoilé.

@item 
Les sous-filtres sans étoile qui restent sont confrontés aux éléments restants du champ de recherche, comme pour un filtre de séquences de longueur fixe.
@end enumerate

@cartouche
@quotation Note 
la longueur de la séquence champ de recherche est obtenue par @ref{619,,len()} (c.-à-d. avec le protocole @code{__len__()}). Cette longueur peut être mise en cache par l’interpréteur de la même manière que pour les @ref{2084,,filtres par valeur}.
@end quotation
@end cartouche
@end enumerate

En termes plus simples, @code{[M1, M2, M3,} … @code{, M<N>]} réussit seulement si tout ce qui suit a lieu :


@itemize *

@item 
vérification que @code{<subject>} est une séquence,

@item 
@code{len(subject) == <N>},

@item 
@code{M1} correspond à @code{<subject>[0]} (notez que cette correspondance peut lier des noms),

@item 
@code{M2} correspond à @code{<subject>[1]} (notez que cette correspondance peut lier des noms),

@item 
et ainsi de suite pour chaque filtre par motif / élément.
@end itemize

@node Filtres associatifs,Filtres de classes,Filtres de séquences,Filtres
@anchor{reference/compound_stmts id12}@anchor{2092}@anchor{reference/compound_stmts mapping-patterns}@anchor{2093}
@subsubsection Filtres associatifs


Un filtre associatif contient un ou plusieurs motifs clé-valeur. La syntaxe est similaire à la construction d’un dictionnaire :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-mapping_pattern}@anchor{2094}mapping_pattern     ::= "@{" [items_pattern] "@}"
@anchor{reference/compound_stmts grammar-token-python-grammar-items_pattern}@anchor{2095}items_pattern       ::= ",".key_value_pattern+ ","?
@anchor{reference/compound_stmts grammar-token-python-grammar-key_value_pattern}@anchor{2096}key_value_pattern   ::= (literal_pattern | value_pattern) ":" pattern
                        | double_star_pattern
@anchor{reference/compound_stmts grammar-token-python-grammar-double_star_pattern}@anchor{2097}double_star_pattern ::= "**" capture_pattern
@end example

Un seul sous-filtre doublement étoilé peut être présent dans le filtre associatif. Le filtre doublement étoilé doit être le dernier sous-filtre du filtre associatif.

Il est interdit d’avoir des clés en double dans les filtres associatifs. Une clé en double sous forme littérale lève une @code{Syntax Error}. Deux clés qui ont la même valeur lèvent une @ref{1ff,,ValueError} à l’exécution.

Voici le déroulement d’un filtrage associatif sur la valeur du champ de recherche :


@enumerate 

@item 
Si la valeur du champ de recherche n'est pas un tableau associatif @footnote{
Dans le filtrage par motif, un tableau associatif est défini comme suit :


@itemize *

@item 
une classe qui hérite de @ref{8b7,,collections.abc.Mapping}

@item 
une classe Python qui a été enregistrée en tant que @ref{8b7,,collections.abc.Mapping}

@item 
une classe native dont le bit (CPython) @ref{1831,,Py_TPFLAGS_MAPPING} est à 1

@item 
une classe qui hérite d'une classe citée ci-dessus
@end itemize

Les classes  @ref{253,,dict} et @ref{457,,types.MappingProxyType} de la bibliothèque standard sont des tableaux associatifs.
}, le filtre associatif échoue.

@item 
Si chaque clé donnée dans le filtre associatif est présente dans le tableau associatif du champ de recherche, et que le filtre pour chaque clé correspond aux éléments du tableau associatif champ de recherche, le filtre associatif réussit.

@item 
Si des clés identiques sont détectées dans le filtre par motif, le filtre est déclaré invalide. Une @ref{18b,,SyntaxError} est levée pour les valeurs littérales dupliquées ou une @ref{1ff,,ValueError} pour des clés s'évaluant à la même valeur.
@end enumerate

@cartouche
@quotation Note 
Key-value pairs are matched using the two-argument form of the mapping
subject's @code{get()} method.  Matched key-value pairs must already be present
in the mapping, and not created on-the-fly via @code{__missing__()} or
@ref{280,,__getitem__()}.
@end quotation
@end cartouche

En termes simples, @code{@{CLÉ1: M1, CLÉ2: M2, ... @}} réussit seulement si tout ce qui suit a lieu :


@itemize *

@item 
vérification que @code{<subject>} est un tableau associatif,

@item 
@code{CLÉ1 in <subject>},

@item 
@code{M1} correspond à @code{<subject>[CLÉ1]},

@item 
et ainsi de suite pour chaque paire CLÉ/Motif.
@end itemize

@node Filtres de classes,,Filtres associatifs,Filtres
@anchor{reference/compound_stmts class-patterns}@anchor{2098}@anchor{reference/compound_stmts id14}@anchor{2099}
@subsubsection Filtres de classes


Un filtre de classe représente une classe et ses arguments positionnels et par mots-clés (s'il y en a). La syntaxe est la suivante :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-class_pattern}@anchor{209a}class_pattern       ::= name_or_attr "(" [pattern_arguments ","?] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-pattern_arguments}@anchor{209b}pattern_arguments   ::= positional_patterns ["," keyword_patterns]
                        | keyword_patterns
@anchor{reference/compound_stmts grammar-token-python-grammar-positional_patterns}@anchor{209c}positional_patterns ::= ",".pattern+
@anchor{reference/compound_stmts grammar-token-python-grammar-keyword_patterns}@anchor{209d}keyword_patterns    ::= ",".keyword_pattern+
@anchor{reference/compound_stmts grammar-token-python-grammar-keyword_pattern}@anchor{209e}keyword_pattern     ::= NAME "=" pattern
@end example

Le même mot-clé ne doit pas être répété dans les filtres de classes.

Voici le déroulement d’un filtrage de classe sur la valeur du champ de recherche :


@enumerate 

@item 
Si @code{name_or_attr} n'est pas une instance de la classe native @ref{d36,,type}, lève une @ref{522,,TypeError}.

@item 
Si la valeur du champ de recherche n'est pas une instance de @code{name_or_attr} (testé `via' @ref{42b,,isinstance()}), le filtre de classe échoue.

@item 
S'il n'y a pas d'argument au filtre, le filtre réussit. Sinon, les étapes suivantes dépendent de la présence ou non de motifs pour les arguments positionnels ou par mot-clé.

Pour un certain nombre de types natifs (indiqués ci-dessous), un motif positionnel seul est accepté, qui est confronté au champ de recherche en entier ; pour ces types, les motifs par mots-clés fonctionnent comme les autres types.

S'il n'y a que des motifs par mot-clé (NdT : dans le sens « argument par mot-clé »), ils sont évalués comme ceci, un par un :

I. Le mot-clé est recherché en tant qu'attribut du champ de recherche.

@quotation


@itemize *

@item 
Si cela lève une exception autre que @ref{343,,AttributeError}, l'exception est propagée vers le haut.

@item 
Si cela lève l'exception @ref{343,,AttributeError}, le filtre échoue.

@item 
Sinon, le motif associé au mot-clé est confronté à la valeur de l'attribut du champ de recherche. Si cela échoue, le filtre de classe échoue ; si cela réussit, le filtre passe au mot-clé suivant.
@end itemize
@end quotation

II. Si tous les motifs par mot-clé ont réussi, le filtre de classe réussit.

Si des motifs positionnels sont présents, ils sont convertis en motifs par mot-clé en utilisant l'attribut @ref{184d,,__match_args__} de la classe @code{name_or_attr} avant le filtrage :

I. L'équivalent de @code{getattr(cls, "__match_args__", ())} est appelé.

@quotation


@itemize *

@item 
Si cela lève une exception, elle est propagée vers le haut.

@item 
Si la valeur de retour n'est pas un `n'-uplet, la conversion échoue et une @ref{522,,TypeError} est levée.

@item 
S'il y a plus de motifs positionnels que @code{len(cls.__match_args__)}, une @ref{522,,TypeError} est levée.

@item 
Sinon, le motif positionnel @code{i} est converti en motif par mot-clé (le mot-clé sera @code{__match_args__[i]}). @code{__match_args__[i]} doit être une chaîne, sinon une @ref{522,,TypeError} est levée.

@item 
Si un mot-clé est dupliqué, une @ref{522,,TypeError} est levée.
@end itemize


@subsubheading Voir aussi


@ref{1f43,,Arguments positionnels dans le filtrage par motif sur les classes}

@end quotation


@table @asis

@item II. Une fois que tous les motifs positionnels ont été convertis en motifs par mot-clé,

le filtre se déroule comme si tous les motifs étaient des motifs par mots-clés.
@end table

Pour les types natifs suivants, le traitement des motifs positionnels est différent :


@itemize *

@item 
@ref{451,,bool}

@item 
@ref{528,,bytearray}

@item 
@ref{1bd,,bytes}

@item 
@ref{253,,dict}

@item 
@ref{2eb,,float}

@item 
@ref{5c4,,frozenset}

@item 
@ref{254,,int}

@item 
@ref{5fc,,list}

@item 
@ref{5c3,,set}

@item 
@ref{435,,str}

@item 
@ref{366,,tuple}
@end itemize

Ces classes acceptent un argument positionnel seul et le filtre s'applique alors sur l'ensemble de l'objet plutôt que sur un simple attribut. Par exemple, @code{int(0|1)} réussit lorsqu'il est confronté à la valeur @code{0}, mais pas lorsque c'est la valeur @code{0.0}.
@end enumerate

En termes simples, @code{CLS(P1, attr=P2)} réussit seulement si la séquence suivante est déroulée :


@itemize *

@item 
@code{isinstance(<subject>, CLS)}

@item 
convertit @code{P1} vers un motif par mot-clé en utilisant @code{CLS.__match_args__}

@item 
Pour chaque argument par mot-clé @code{attr=P2} :


@itemize *

@item 
@code{hasattr(<subject>, "attr")}

@item 
@code{P2} correspond à @code{<subject>.attr}
@end itemize

@item 
… et ainsi de suite pour les paires motif/argument par mot-clé.
@end itemize


@subsubheading Voir aussi



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} — Spécifications pour le filtrage par motif

@item 
@geindex Python Enhancement Proposals; PEP 636
PEP 636@footnote{https://peps.python.org/pep-0636/} — Tutoriel pour le filtrage par motif
@end itemize


@geindex parameter;function definition
@anchor{reference/compound_stmts function}@anchor{1bc4}
@node Définition de fonctions,Définition de classes,L'instruction match<2>,Instructions composées
@anchor{reference/compound_stmts def}@anchor{140e}@anchor{reference/compound_stmts function-definitions}@anchor{209f}
@subsection Définition de fonctions


@geindex statement;def
@geindex function;definition
@geindex function;name
@geindex name;binding
@geindex object;user-defined function
@geindex object;function
@geindex function;name
@geindex name;binding
@geindex () (parentheses);function definition
@geindex @comma{} (comma);parameter list
@geindex ; (colon);compound statement

Une définition de fonction définit un objet fonction défini par l'utilisateur (voir la section @ref{1e6a,,Hiérarchie des types standards}) :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-funcdef}@anchor{20a0}funcdef                   ::= [decorators] "def" funcname [type_params] "(" [parameter_list] ")"
                              ["->" expression] ":" suite
@anchor{reference/compound_stmts grammar-token-python-grammar-decorators}@anchor{20a1}decorators                ::= decorator+
@anchor{reference/compound_stmts grammar-token-python-grammar-decorator}@anchor{20a2}decorator                 ::= "@@" assignment_expression NEWLINE
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list}@anchor{20a3}parameter_list            ::= defparameter ("," defparameter)* "," "/" ["," [parameter_list_no_posonly]]
                                | parameter_list_no_posonly
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list_no_posonly}@anchor{20a4}parameter_list_no_posonly ::= defparameter ("," defparameter)* ["," [parameter_list_starargs]]
                              | parameter_list_starargs
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter_list_starargs}@anchor{20a5}parameter_list_starargs   ::= "*" [star_parameter] ("," defparameter)* ["," ["**" parameter [","]]]
                              | "**" parameter [","]
@anchor{reference/compound_stmts grammar-token-python-grammar-parameter}@anchor{20a6}parameter                 ::= identifier [":" expression]
@anchor{reference/compound_stmts grammar-token-python-grammar-star_parameter}@anchor{20a7}star_parameter            ::= identifier [":" ["*"] expression]
@anchor{reference/compound_stmts grammar-token-python-grammar-defparameter}@anchor{20a8}defparameter              ::= parameter ["=" expression]
@anchor{reference/compound_stmts grammar-token-python-grammar-funcname}@anchor{20a9}funcname                  ::= identifier
@end example

Une définition de fonction est une instruction qui est exécutée. Son exécution lie le nom de la fonction, dans l'espace de nommage local courant, à un objet fonction (un objet qui encapsule le code exécutable de la fonction). Cet objet fonction contient une référence à l'espace des noms globaux courant comme espace des noms globaux à utiliser lorsque la fonction est appelée.

La définition de la fonction n'exécute pas le corps de la fonction ; elle n'est exécutée que lorsque la fonction est appelée. @footnote{
A string literal appearing as the first statement in the function body is
transformed into the function's @ref{11b6,,__doc__} attribute and
therefore the function's @ref{20aa,,docstring}.
}

@geindex @@ (at);function definition

Une définition de fonction peut être encapsulée dans une ou plusieurs expressions @ref{71b,,decorator} ; les décorateurs sont évalués lorsque la fonction est définie, dans la portée qui contient la définition de fonction ; le résultat doit être un appelable, qui est invoqué avec l'objet fonction comme seul argument ; la valeur renvoyée est liée au nom de la fonction en lieu et place de l'objet fonction. Lorsqu'il y a plusieurs décorateurs, ils sont appliqués par imbrication ; par exemple, le code suivant :

@example
@@f1(arg)
@@f2
def func(): pass
@end example

est à peu près équivalent à :

@example
def func(): pass
func = f1(arg)(f2(func))
@end example

sauf que la fonction originale n'est pas temporairement liée au nom @code{func}.


Modifié dans la version 3.9: les fonctions peuvent être décorées par toute @ref{1f62,,expression d'affectation} valide. Auparavant, la grammaire était beaucoup plus restrictive ; voir la 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/} pour obtenir les détails.


A list of @ref{2b0,,type parameters} may be given in square brackets
between the function's name and the opening parenthesis for its parameter list.
This indicates to static type checkers that the function is generic. At runtime,
the type parameters can be retrieved from the function's
@ref{1e83,,__type_params__}
attribute. See @ref{43c,,Generic functions} for more.


Modifié dans la version 3.12: Type parameter lists are new in Python 3.12.


@geindex default;parameter;value
@geindex argument;function definition
@geindex = (equals);function definition

Lorsqu'un ou plusieurs @ref{1e82,,paramètres} sont de la forme `parameter' @code{=} `expression', on dit que la fonction a des « valeurs de paramètres par défaut ». Pour un paramètre avec une valeur par défaut, l’@ref{432,,argument} correspondant peut être omis lors de l'appel, la valeur par défaut du paramètre est alors utilisée. Si un paramètre a une valeur par défaut, tous les paramètres suivants jusqu'à "@code{*}" doivent aussi avoir une valeur par défaut — ceci est une restriction syntaxique qui n'est pas exprimée dans la grammaire.

`Les valeurs par défaut des paramètres sont évaluées de la gauche vers la droite quand la définition de la fonction est exécutée'. Cela signifie que l'expression est évaluée une fois, lorsque la fonction est définie, et que c'est la même valeur « pré-calculée » qui est utilisée à chaque appel. C'est particulièrement important à comprendre lorsque la valeur d'un paramètre par défaut est un objet mutable (cas d'une liste ou un dictionnaire par exemple) : si la fonction modifie l'objet (par exemple en ajoutant un élément à une liste), la valeur par défaut est modifiée. En général, ce n'est pas l'effet voulu. Une façon d'éviter cet écueil est d'utiliser @code{None} par défaut et de tester explicitement la valeur dans le corps de la fonction. Par exemple :

@example
def whats_on_the_telly(penguin=None):
    if penguin is None:
        penguin = []
    penguin.append("property of the zoo")
    return penguin
@end example

@geindex / (slash);function definition
@geindex * (asterisk);function definition
@geindex **;function definition

La sémantique de l'appel de fonction est décrite plus en détail dans la section @ref{d6a,,Appels}. Un appel de fonction assigne toujours des valeurs à tous les paramètres mentionnés dans la liste des paramètres, soit à partir d'arguments positionnels, d'arguments par mots-clés ou de valeurs par défaut. S'il y a un paramètre de la forme @code{*identifier}, il est initialisé à un `n'-uplet recevant les paramètres positionnels en surplus, la valeur par défaut étant le `n'-uplet vide. S'il y a un paramètre de la forme @code{**identifier}, il est initialisé à un nouveau tableau associatif ordonné qui récupère tous les arguments par mot-clé en surplus, la valeur par défaut étant un tableau associatif vide du même type. Les paramètres après @code{*} ou @code{*identifier} sont forcément des paramètres par mot-clé et ne peuvent être passés qu'en utilisant des arguments par mot-clé. Au contraire, ceux avant @code{/} ne peuvent être passés qu'avec des arguments positionnels.


Modifié dans la version 3.8: ajout de la syntaxe avec @code{/} pour indiquer les paramètre exclusivement positionnels (voir la 
@geindex Python Enhancement Proposals; PEP 570
PEP 570@footnote{https://peps.python.org/pep-0570/}).


@geindex function;annotations
@geindex ->;function annotations
@geindex ; (colon);function annotations

Parameters may have an @ref{1bc5,,annotation} of the form "@code{: expression}"
following the parameter name.  Any parameter may have an annotation, even those of the form
@code{*identifier} or @code{**identifier}. (As a special case, parameters of the form
@code{*identifier} may have an annotation "@code{: *expression}".) Functions may have "return" annotation of
the form "@code{-> expression}" after the parameter list.  These annotations can be
any valid Python expression.  The presence of annotations does not change the
semantics of a function.  The annotation values are available as values of
a dictionary keyed by the parameters' names in the @code{__annotations__}
attribute of the function object.  If the @code{annotations} import from
@ref{0,,__future__} is used, annotations are preserved as strings at runtime which
enables postponed evaluation.  Otherwise, they are evaluated when the function
definition is executed.  In this case annotations may be evaluated in
a different order than they appear in the source code.


Modifié dans la version 3.11: Parameters of the form "@code{*identifier}" may have an annotation
"@code{: *expression}". See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/}.


@geindex lambda;expression

Il est aussi possible de créer des fonctions anonymes (fonctions non liées à un nom), pour une utilisation immédiate dans des expressions. Utilisez alors des expressions lambda, décrites dans la section @ref{127a,,Expressions lambda}. Notez qu'une expression lambda est simplement un raccourci pour définir une fonction simple ; une fonction définie par une instruction "@ref{140e,,def}" peut être passée (en argument) ou assignée à un autre nom, tout comme une fonction définie par une expression lambda. La forme "@code{def}" est en fait plus puissante puisqu'elle permet l'exécution de plusieurs instructions et les annotations.

`Note pour les programmeurs :' les fonctions sont des objets de première classe. Une instruction "@code{def}" exécutée à l'intérieur d'une définition de fonction définit une fonction locale qui peut être renvoyée ou passée en tant qu'argument. Les variables libres utilisées dans la fonction imbriquée ont accès aux variables locales de la fonction contenant le "@code{def}".  Voir la section @ref{1e7d,,Noms et liaisons} pour plus de détails.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3107

@item PEP 3107@footnote{https://peps.python.org/pep-3107/} — Annotations de fonctions

La spécification originale pour les annotations de fonctions.

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} — Indications de types

Définition de la signification standard pour les annotations : indications de types.

@geindex Python Enhancement Proposals; PEP 526

@item PEP 526@footnote{https://peps.python.org/pep-0526/} — Syntaxe pour les annotations de variables

Ability to type hint variable declarations, including class
variables and instance variables.

@geindex Python Enhancement Proposals; PEP 563

@item PEP 563@footnote{https://peps.python.org/pep-0563/} — Évaluation différée des annotations

Gestion des références postérieures à l'intérieur des annotations en préservant les annotations sous forme de chaînes à l'exécution au lieu d'une évaluation directe.

@geindex Python Enhancement Proposals; PEP 318

@item PEP 318@footnote{https://peps.python.org/pep-0318/} - Decorators for Functions and Methods

Function and method decorators were introduced.
Class decorators were introduced in 
@geindex Python Enhancement Proposals; PEP 3129
PEP 3129@footnote{https://peps.python.org/pep-3129/}.
@end table


@node Définition de classes,Coroutines<2>,Définition de fonctions,Instructions composées
@anchor{reference/compound_stmts class}@anchor{12b5}@anchor{reference/compound_stmts class-definitions}@anchor{20ab}
@subsection Définition de classes


@geindex object;class
@geindex statement;class
@geindex class;definition
@geindex class;name
@geindex name;binding
@geindex execution;frame
@geindex inheritance
@geindex docstring
@geindex () (parentheses);class definition
@geindex @comma{} (comma);expression list
@geindex ; (colon);compound statement

Une définition de classe définit un objet classe (voir la section @ref{1e6a,,Hiérarchie des types standards}) :

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-classdef}@anchor{20ac}classdef    ::= [decorators] "class" classname [type_params] [inheritance] ":" suite
@anchor{reference/compound_stmts grammar-token-python-grammar-inheritance}@anchor{20ad}inheritance ::= "(" [argument_list] ")"
@anchor{reference/compound_stmts grammar-token-python-grammar-classname}@anchor{20ae}classname   ::= identifier
@end example

Une définition de classe est une instruction qui est exécutée. La liste d'héritage (`inheritance' entre crochets dans la grammaire ci-dessus) donne habituellement une liste de classes mères (voir @ref{1ef6,,Métaclasses} pour des utilisations plus avancées). Donc chaque élément de la liste doit pouvoir être évalué comme un objet classe qui autorise les sous-classes. Les classes sans liste d'héritage héritent, par défaut, de la classe mère @ref{a7a,,object} ; d'où :

@example
class Foo:
    pass
@end example

est équivalente à :

@example
class Foo(object):
    pass
@end example

La suite de la classe est ensuite exécutée dans un nouveau cadre d'exécution (voir @ref{1e7d,,Noms et liaisons}), en utilisant un espace de nommage local nouvellement créé et l'espace de nommage global d'origine (habituellement, la suite contient principalement des définitions de fonctions). Lorsque la suite de la classe termine son exécution, son cadre d'exécution est abandonné mais son espace des noms locaux est sauvegardé @footnote{
A string literal appearing as the first statement in the class body is
transformed into the namespace's @ref{1c3a,,__doc__} item and therefore
the class's @ref{20aa,,docstring}.
}. Un objet classe est alors créé en utilisant la liste d'héritage pour les classes mères et l'espace de nommage sauvegardé comme dictionnaire des attributs. Le nom de classe est lié à l'objet classe dans l'espace de nommage local original.

The order in which attributes are defined in the class body is preserved
in the new class's @ref{c4b,,__dict__}.  Note that this is reliable only right
after the class is created and only for classes that were defined using
the definition syntax.

La création de classes peut être fortement personnalisée en utilisant les @ref{1ef6,,métaclasses}.

@geindex @@ (at);class definition

Les classes peuvent aussi être décorées. Comme pour les décorateurs de fonctions :

@example
@@f1(arg)
@@f2
class Foo: pass
@end example

est à peu près équivalent à :

@example
class Foo: pass
Foo = f1(arg)(f2(Foo))
@end example

Les règles d'évaluation pour les expressions de décorateurs sont les mêmes que pour les décorateurs de fonctions. Le résultat est alors lié au nom de la classe.


Modifié dans la version 3.9: les classes peuvent être décorées par toute @ref{1f62,,expression d'affectation} valide. Auparavant, la grammaire était beaucoup plus restrictive ; voir la 
@geindex Python Enhancement Proposals; PEP 614
PEP 614@footnote{https://peps.python.org/pep-0614/} pour obtenir les détails.


A list of @ref{2b0,,type parameters} may be given in square brackets
immediately after the class's name.
This indicates to static type checkers that the class is generic. At runtime,
the type parameters can be retrieved from the class's
@ref{1ead,,__type_params__} attribute. See @ref{43b,,Generic classes} for more.


Modifié dans la version 3.12: Type parameter lists are new in Python 3.12.


`Note pour les programmeurs :' les variables définies dans la définition de classe sont des attributs de classe ; elles sont partagées par les instances. Les attributs d'instance peuvent être définis dans une méthode en utilisant @code{self.name = value}. Les attributs de classe et d'instance sont accessibles par la notation "@code{self.name}", et un attribut d'instance masque un attribut de classe de même nom lorsqu'on y accède de cette façon. Les attributs de classe peuvent être utilisés comme valeurs par défaut pour les attributs d'instances, mais l'utilisation de valeurs mutables peut conduire à des résultats inattendus. Les @ref{c3d,,descripteurs} peuvent être utilisés pour créer des variables d'instances avec des détails d'implémentation différents.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} — Métaclasses dans Python 3000

La proposition qui a modifié la déclaration de métaclasses à la syntaxe actuelle, et la sémantique pour la façon dont les classes avec métaclasses sont construites.

@geindex Python Enhancement Proposals; PEP 3129

@item PEP 3129@footnote{https://peps.python.org/pep-3129/} — Décorateurs de classes

La proposition qui a ajouté des décorateurs de classe. Les décorateurs de fonction et de méthode ont été introduits dans 
@geindex Python Enhancement Proposals; PEP 318
PEP 318@footnote{https://peps.python.org/pep-0318/}.
@end table


@node Coroutines<2>,Type parameter lists,Définition de classes,Instructions composées
@anchor{reference/compound_stmts async}@anchor{71c}@anchor{reference/compound_stmts coroutines}@anchor{20af}
@subsection Coroutines



Ajouté dans la version 3.5.


@geindex statement;async def

@menu
* Définition de fonctions coroutines:: 
* L'instruction async for:: 
* L'instruction async with:: 

@end menu

@node Définition de fonctions coroutines,L'instruction async for,,Coroutines<2>
@anchor{reference/compound_stmts async-def}@anchor{5bb}@anchor{reference/compound_stmts coroutine-function-definition}@anchor{20b0}
@subsubsection Définition de fonctions coroutines


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_funcdef}@anchor{20b1}async_funcdef ::= [decorators] "async" "def" funcname "(" [parameter_list] ")"
                  ["->" expression] ":" suite
@end example

@geindex keyword;async
@geindex keyword;await

L'exécution de coroutines Python peut être suspendue et reprise à plusieurs endroits (voir @ref{47b,,coroutine}). Les expressions @ref{1b7,,await}, @ref{a99,,async for} et @ref{5bf,,async with} ne peuvent être utilisées que dans les corps de coroutines.

Les fonctions définies avec la syntaxe @code{async def} sont toujours des fonctions coroutines, même si elles ne contiennent aucun mot-clé @code{await} ou @code{async}.

C'est une @ref{18b,,SyntaxError} d'utiliser une expression @code{yield from} dans une coroutine.

Un exemple de fonction coroutine :

@example
async def func(param1, param2):
    do_stuff()
    await some_coroutine()
@end example


Modifié dans la version 3.7: @code{await} et @code{async} sont dorénavant des mots-clés ; auparavant, ils n'étaient traités comme tels que dans le corps d'une fonction coroutine.


@geindex statement;async for

@node L'instruction async for,L'instruction async with,Définition de fonctions coroutines,Coroutines<2>
@anchor{reference/compound_stmts async-for}@anchor{a99}@anchor{reference/compound_stmts the-async-for-statement}@anchor{20b2}
@subsubsection L'instruction @code{async for}


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_for_stmt}@anchor{20b3}async_for_stmt ::= "async" for_stmt
@end example

Un @ref{d65,,itérable asynchrone} fournit une méthode @code{__aiter__} qui renvoie directement un @ref{1a9,,itérateur asynchrone}, celui-ci pouvant appeler du code asynchrone dans sa méthode @code{__anext__}.

L'instruction @code{async for} permet d'itérer facilement sur des itérables asynchrones.

Le code suivant :

@example
async for TARGET in ITER:
    SUITE
else:
    SUITE2
@end example

est sémantiquement équivalent à :

@example
iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True

while running:
    try:
        TARGET = await type(iter).__anext__(iter)
    except StopAsyncIteration:
        running = False
    else:
        SUITE
else:
    SUITE2
@end example

Voir aussi @ref{be9,,__aiter__()} et @ref{1e8f,,__anext__()} pour plus de détails.

C'est une @ref{18b,,SyntaxError} d'utiliser une instruction @code{async for} en dehors d'une fonction coroutine.

@geindex statement;async with

@node L'instruction async with,,L'instruction async for,Coroutines<2>
@anchor{reference/compound_stmts async-with}@anchor{5bf}@anchor{reference/compound_stmts the-async-with-statement}@anchor{20b4}
@subsubsection L'instruction @code{async with}


@example
@anchor{reference/compound_stmts grammar-token-python-grammar-async_with_stmt}@anchor{20b5}async_with_stmt ::= "async" with_stmt
@end example

Un @ref{5c1,,gestionnaire de contexte asynchrone} est un @ref{5be,,gestionnaire de contexte} qui est capable de suspendre l'exécution dans ses méthodes `enter' et `exit'.

Le code suivant :

@example
async with EXPRESSION as TARGET:
    SUITE
@end example

est sémantiquement équivalent à :

@example
manager = (EXPRESSION)
aenter = type(manager).__aenter__
aexit = type(manager).__aexit__
value = await aenter(manager)
hit_except = False

try:
    TARGET = value
    SUITE
except:
    hit_except = True
    if not await aexit(manager, *sys.exc_info()):
        raise
finally:
    if not hit_except:
        await aexit(manager, None, None, None)
@end example

Voir aussi @ref{1f53,,__aenter__()} et @ref{15b3,,__aexit__()} pour plus de détails.

C'est une @ref{18b,,SyntaxError} d'utiliser l'instruction @code{async with} en dehors d'une fonction coroutine.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 492

@item PEP 492@footnote{https://peps.python.org/pep-0492/} — Coroutines avec les syntaxes `async' et `await'

La proposition qui a fait que les coroutines soient un concept propre en Python, et a ajouté la syntaxe de prise en charge de celles-ci.
@end table


@node Type parameter lists,,Coroutines<2>,Instructions composées
@anchor{reference/compound_stmts type-parameter-lists}@anchor{20b6}@anchor{reference/compound_stmts type-params}@anchor{2b0}
@subsection Type parameter lists



Ajouté dans la version 3.12.



Modifié dans la version 3.13: Support for default values was added (see 
@geindex Python Enhancement Proposals; PEP 696
PEP 696@footnote{https://peps.python.org/pep-0696/}).


@geindex type parameters

@example
@anchor{reference/compound_stmts grammar-token-python-grammar-type_params}@anchor{20b7}type_params  ::= "[" type_param ("," type_param)* "]"
@anchor{reference/compound_stmts grammar-token-python-grammar-type_param}@anchor{20b8}type_param   ::= typevar | typevartuple | paramspec
@anchor{reference/compound_stmts grammar-token-python-grammar-typevar}@anchor{20b9}typevar      ::= identifier (":" expression)? ("=" expression)?
@anchor{reference/compound_stmts grammar-token-python-grammar-typevartuple}@anchor{20ba}typevartuple ::= "*" identifier ("=" expression)?
@anchor{reference/compound_stmts grammar-token-python-grammar-paramspec}@anchor{20bb}paramspec    ::= "**" identifier ("=" expression)?
@end example

@ref{140e,,Functions} (including @ref{5bb,,coroutines}),
@ref{12b5,,classes} and @ref{421,,type aliases} may
contain a type parameter list:

@example
def max[T](args: list[T]) -> T:
    ...

async def amax[T](args: list[T]) -> T:
    ...

class Bag[T]:
    def __iter__(self) -> Iterator[T]:
        ...

    def add(self, arg: T) -> None:
        ...

type ListOrSet[T] = list[T] | set[T]
@end example

Semantically, this indicates that the function, class, or type alias is
generic over a type variable. This information is primarily used by static
type checkers, and at runtime, generic objects behave much like their
non-generic counterparts.

Type parameters are declared in square brackets (@code{[]}) immediately
after the name of the function, class, or type alias. The type parameters
are accessible within the scope of the generic object, but not elsewhere.
Thus, after a declaration @code{def func[T](): pass}, the name @code{T} is not available in
the module scope. Below, the semantics of generic objects are described
with more precision. The scope of type parameters is modeled with a special
function (technically, an @ref{186,,annotation scope}) that
wraps the creation of the generic object.

Generic functions, classes, and type aliases have a
@ref{20bc,,__type_params__} attribute listing their type parameters.

Type parameters come in three kinds:


@itemize *

@item 
@ref{15c,,typing.TypeVar}, introduced by a plain name (e.g., @code{T}). Semantically, this
represents a single type to a type checker.

@item 
@ref{15e,,typing.TypeVarTuple}, introduced by a name prefixed with a single
asterisk (e.g., @code{*Ts}). Semantically, this stands for a tuple of any
number of types.

@item 
@ref{15d,,typing.ParamSpec}, introduced by a name prefixed with two asterisks
(e.g., @code{**P}). Semantically, this stands for the parameters of a callable.
@end itemize

@ref{15c,,typing.TypeVar} declarations can define `bounds' and `constraints' with
a colon (@code{:}) followed by an expression. A single expression after the colon
indicates a bound (e.g. @code{T: int}). Semantically, this means
that the @code{typing.TypeVar} can only represent types that are a subtype of
this bound. A parenthesized tuple of expressions after the colon indicates a
set of constraints (e.g. @code{T: (str, bytes)}). Each member of the tuple should be a
type (again, this is not enforced at runtime). Constrained type variables can only
take on one of the types in the list of constraints.

For @code{typing.TypeVar}s declared using the type parameter list syntax,
the bound and constraints are not evaluated when the generic object is created,
but only when the value is explicitly accessed through the attributes @code{__bound__}
and @code{__constraints__}. To accomplish this, the bounds or constraints are
evaluated in a separate @ref{186,,annotation scope}.

@ref{15e,,typing.TypeVarTuple}s and @ref{15d,,typing.ParamSpec}s cannot have bounds
or constraints.

All three flavors of type parameters can also have a `default value', which is used
when the type parameter is not explicitly provided. This is added by appending
a single equals sign (@code{=}) followed by an expression. Like the bounds and
constraints of type variables, the default value is not evaluated when the
object is created, but only when the type parameter's @code{__default__} attribute
is accessed. To this end, the default value is evaluated in a separate
@ref{186,,annotation scope}. If no default value is specified
for a type parameter, the @code{__default__} attribute is set to the special
sentinel object @ref{25f,,typing.NoDefault}.

The following example indicates the full set of allowed type parameter declarations:

@example
def overly_generic[
   SimpleTypeVar,
   TypeVarWithDefault = int,
   TypeVarWithBound: int,
   TypeVarWithConstraints: (str, bytes),
   *SimpleTypeVarTuple = (int, float),
   **SimpleParamSpec = (str, bytearray),
](
   a: SimpleTypeVar,
   b: TypeVarWithDefault,
   c: TypeVarWithBound,
   d: Callable[SimpleParamSpec, TypeVarWithConstraints],
   *e: SimpleTypeVarTuple,
): ...
@end example

@menu
* Generic functions:: 
* Generic classes:: 
* Generic type aliases:: 

@end menu

@node Generic functions,Generic classes,,Type parameter lists
@anchor{reference/compound_stmts generic-functions}@anchor{43c}@anchor{reference/compound_stmts id17}@anchor{20bd}
@subsubsection Generic functions


Generic functions are declared as follows:

@example
def func[T](arg: T): ...
@end example

This syntax is equivalent to:

@example
annotation-def TYPE_PARAMS_OF_func():
    T = typing.TypeVar("T")
    def func(arg: T): ...
    func.__type_params__ = (T,)
    return func
func = TYPE_PARAMS_OF_func()
@end example

Here @code{annotation-def} indicates an @ref{186,,annotation scope},
which is not actually bound to any name at runtime. (One
other liberty is taken in the translation: the syntax does not go through
attribute access on the @ref{103,,typing} module, but creates an instance of
@ref{15c,,typing.TypeVar} directly.)

The annotations of generic functions are evaluated within the annotation scope
used for declaring the type parameters, but the function's defaults and
decorators are not.

The following example illustrates the scoping rules for these cases,
as well as for additional flavors of type parameters:

@example
@@decorator
def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = some_default):
    ...
@end example

Except for the @ref{440,,lazy evaluation} of the
@ref{15c,,TypeVar} bound, this is equivalent to:

@example
DEFAULT_OF_arg = some_default

annotation-def TYPE_PARAMS_OF_func():

    annotation-def BOUND_OF_T():
        return int
    # In reality, BOUND_OF_T() is evaluated only on demand.
    T = typing.TypeVar("T", bound=BOUND_OF_T())

    Ts = typing.TypeVarTuple("Ts")
    P = typing.ParamSpec("P")

    def func(*args: *Ts, arg: Callable[P, T] = DEFAULT_OF_arg):
        ...

    func.__type_params__ = (T, Ts, P)
    return func
func = decorator(TYPE_PARAMS_OF_func())
@end example

The capitalized names like @code{DEFAULT_OF_arg} are not actually
bound at runtime.

@node Generic classes,Generic type aliases,Generic functions,Type parameter lists
@anchor{reference/compound_stmts generic-classes}@anchor{43b}@anchor{reference/compound_stmts id18}@anchor{20be}
@subsubsection Generic classes


Generic classes are declared as follows:

@example
class Bag[T]: ...
@end example

This syntax is equivalent to:

@example
annotation-def TYPE_PARAMS_OF_Bag():
    T = typing.TypeVar("T")
    class Bag(typing.Generic[T]):
        __type_params__ = (T,)
        ...
    return Bag
Bag = TYPE_PARAMS_OF_Bag()
@end example

Here again @code{annotation-def} (not a real keyword) indicates an
@ref{186,,annotation scope}, and the name
@code{TYPE_PARAMS_OF_Bag} is not actually bound at runtime.

Generic classes implicitly inherit from @ref{15a1,,typing.Generic}.
The base classes and keyword arguments of generic classes are
evaluated within the type scope for the type parameters,
and decorators are evaluated outside that scope. This is illustrated
by this example:

@example
@@decorator
class Bag(Base[T], arg=T): ...
@end example

This is equivalent to:

@example
annotation-def TYPE_PARAMS_OF_Bag():
    T = typing.TypeVar("T")
    class Bag(Base[T], typing.Generic[T], arg=T):
        __type_params__ = (T,)
        ...
    return Bag
Bag = decorator(TYPE_PARAMS_OF_Bag())
@end example

@node Generic type aliases,,Generic classes,Type parameter lists
@anchor{reference/compound_stmts generic-type-aliases}@anchor{43f}@anchor{reference/compound_stmts id19}@anchor{20bf}
@subsubsection Generic type aliases


The @ref{421,,type} statement can also be used to create a generic type alias:

@example
type ListOrSet[T] = list[T] | set[T]
@end example

Except for the @ref{440,,lazy evaluation} of the value,
this is equivalent to:

@example
annotation-def TYPE_PARAMS_OF_ListOrSet():
    T = typing.TypeVar("T")

    annotation-def VALUE_OF_ListOrSet():
        return list[T] | set[T]
    # In reality, the value is lazily evaluated
    return typing.TypeAliasType("ListOrSet", VALUE_OF_ListOrSet(), type_params=(T,))
ListOrSet = TYPE_PARAMS_OF_ListOrSet()
@end example

Here, @code{annotation-def} (not a real keyword) indicates an
@ref{186,,annotation scope}. The capitalized names
like @code{TYPE_PARAMS_OF_ListOrSet} are not actually bound at runtime.

@subsubheading Notes


@node Composants de plus haut niveau,Spécification complète de la grammaire,Instructions composées,La référence du langage Python
@anchor{reference/toplevel_components doc}@anchor{20c0}@anchor{reference/toplevel_components top-level}@anchor{20c1}@anchor{reference/toplevel_components top-level-components}@anchor{20c2}
@section Composants de plus haut niveau


@geindex interpreter

L'entrée de l'interpréteur Python peut provenir d'un certain nombre de sources : d'un script passé en entrée standard ou en argument de programme, tapée de manière interactive, à partir d'un fichier source de module, etc. Ce chapitre donne la syntaxe utilisée dans ces différents cas.

@menu
* Programmes Python complets:: 
* Fichier d'entrée:: 
* Entrée interactive:: 
* Entrée d'expression:: 

@end menu

@node Programmes Python complets,Fichier d'entrée,,Composants de plus haut niveau
@anchor{reference/toplevel_components complete-python-programs}@anchor{20c3}@anchor{reference/toplevel_components programs}@anchor{1f7f}
@subsection Programmes Python complets


@geindex program

@geindex module;sys
@geindex module;__main__
@geindex module;builtins

Bien que les spécifications d'un langage n'ont pas à préciser comment l'interpréteur du langage est invoqué, il est utile d'avoir des notions sur ce qu'est un programme Python complet. Un programme Python complet est exécuté dans un environnement dont l'initialisation est minimale : tous les modules intégrés et standard sont disponibles mais aucun n'a été initialisé, à l'exception de @ref{d8,,sys} (divers services système), @ref{12,,builtins} (fonctions natives, exceptions et @code{None}) et @ref{1,,__main__}. Ce dernier est utilisé pour avoir des espaces de nommage locaux et globaux pour l'exécution du programme complet.

La syntaxe d'un programme Python complet est celle d'un fichier d'entrée, dont la description est donnée dans la section suivante.

@geindex interactive mode
@geindex module;__main__

L'interpréteur peut également être invoqué en mode interactif ; dans ce cas, il ne lit et n'exécute pas un programme complet mais lit et exécute une seule instruction (éventuellement composée) à la fois. L'environnement initial est identique à celui d'un programme complet ; chaque instruction est exécutée dans l'espace de nommage de @ref{1,,__main__}.

@geindex UNIX
@geindex Windows
@geindex command line
@geindex standard input

Un programme complet peut être transmis à l'interpréteur sous trois formes : avec l'option @ref{5ca,,-c} `chaîne' en ligne de commande, avec un fichier passé comme premier argument de ligne de commande ou comme entrée standard. Si le fichier ou l'entrée standard est un périphérique tty, l'interpréteur entre en mode interactif ; sinon, il exécute le fichier comme un programme complet.

@node Fichier d'entrée,Entrée interactive,Programmes Python complets,Composants de plus haut niveau
@anchor{reference/toplevel_components file-input}@anchor{20c4}@anchor{reference/toplevel_components id1}@anchor{20c5}
@subsection Fichier d'entrée


Toutes les entrées lues à partir de fichiers non interactifs sont de la même forme :

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-file_input}@anchor{20c6}file_input ::= (NEWLINE | statement)*
@end example

Cette syntaxe est utilisée dans les situations suivantes :


@itemize *

@item 
lors de l'analyse d'un programme Python complet (à partir d'un fichier ou d'une chaîne de caractères) ;

@item 
lors de l'analyse d'un module ;

@item 
lors de l'analyse d'une chaîne de caractères passée à la fonction @ref{17d,,exec()}.
@end itemize

@node Entrée interactive,Entrée d'expression,Fichier d'entrée,Composants de plus haut niveau
@anchor{reference/toplevel_components interactive}@anchor{20c7}@anchor{reference/toplevel_components interactive-input}@anchor{20c8}
@subsection Entrée interactive


L'entrée en mode interactif est analysée à l'aide de la grammaire suivante :

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-interactive_input}@anchor{20c9}interactive_input ::= [stmt_list] NEWLINE | compound_stmt NEWLINE
@end example

Notez qu'une instruction composée (de niveau supérieur) doit être suivie d'une ligne blanche en mode interactif ; c'est nécessaire pour aider l'analyseur à détecter la fin de l'entrée.

@node Entrée d'expression,,Entrée interactive,Composants de plus haut niveau
@anchor{reference/toplevel_components expression-input}@anchor{20ca}@anchor{reference/toplevel_components id2}@anchor{20cb}
@subsection Entrée d'expression


@geindex input

@geindex built-in function;eval

@ref{17e,,eval()} est utilisée pour évaluer les expressions entrées. Elle ignore les espaces en tête. L'argument de @ref{17e,,eval()}, de type chaîne de caractères, doit être de la forme suivante :

@example
@anchor{reference/toplevel_components grammar-token-python-grammar-eval_input}@anchor{20cc}eval_input ::= expression_list NEWLINE*
@end example

@node Spécification complète de la grammaire,,Composants de plus haut niveau,La référence du langage Python
@anchor{reference/grammar doc}@anchor{207e}@anchor{reference/grammar full-grammar-specification}@anchor{20cd}@anchor{reference/grammar id1}@anchor{20ce}
@section Spécification complète de la grammaire


Ceci est la grammaire complète de Python, issue directement de la grammaire utilisée pour générer l'analyseur syntaxique CPython (voir Grammar/python.gram@footnote{https://github.com/python/cpython/tree/3.13/Grammar/python.gram}). La version ci-dessous ne comprend pas les détails relatifs à la génération de code et la reprise sur erreur.

The notation is a mixture of EBNF@footnote{https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form}
and PEG@footnote{https://en.wikipedia.org/wiki/Parsing_expression_grammar}.
In particular, @code{&} followed by a symbol, token or parenthesized
group indicates a positive lookahead (i.e., is required to match but
not consumed), while @code{!} indicates a negative lookahead (i.e., is
required `not' to match).  We use the @code{|} separator to mean PEG's
"ordered choice" (written as @code{/} in traditional PEG grammars). See
@geindex Python Enhancement Proposals; PEP 617
PEP 617@footnote{https://peps.python.org/pep-0617/} for more details on the grammar's syntax.

@example
# PEG grammar for Python

@@trailer '@w{'}'
void *
_PyPegen_parse(Parser *p)
@{
    // Initialize keywords
    p->keywords = reserved_keywords;
    p->n_keyword_lists = n_keyword_lists;
    p->soft_keywords = soft_keywords;

    // Run parser
    void *result = NULL;
    if (p->start_rule == Py_file_input) @{
        result = file_rule(p);
    @} else if (p->start_rule == Py_single_input) @{
        result = interactive_rule(p);
    @} else if (p->start_rule == Py_eval_input) @{
        result = eval_rule(p);
    @} else if (p->start_rule == Py_func_type_input) @{
        result = func_type_rule(p);
    @}

    return result;
@}
'@w{'}'

# ========================= START OF THE GRAMMAR =========================

# General grammatical elements and rules:
#
# * Strings with double quotes (") denote SOFT KEYWORDS
# * Strings with single quotes (') denote KEYWORDS
# * Upper case names (NAME) denote tokens in the Grammar/Tokens file
# * Rule names starting with "invalid_" are used for specialized syntax errors
#     - These rules are NOT used in the first pass of the parser.
#     - Only if the first pass fails to parse, a second pass including the invalid
#       rules will be executed.
#     - If the parser fails in the second phase with a generic syntax error, the
#       location of the generic failure of the first pass will be used (this avoids
#       reporting incorrect locations due to the invalid rules).
#     - The order of the alternatives involving invalid rules matter
#       (like any rule in PEG).
#
# Grammar Syntax (see PEP 617 for more information):
#
# rule_name: expression
#   Optionally, a type can be included right after the rule name, which
#   specifies the return type of the C or Python function corresponding to the
#   rule:
# rule_name[return_type]: expression
#   If the return type is omitted, then a void * is returned in C and an Any in
#   Python.
# e1 e2
#   Match e1, then match e2.
# e1 | e2
#   Match e1 or e2.
#   The first alternative can also appear on the line after the rule name for
#   formatting purposes. In that case, a | must be used before the first
#   alternative, like so:
#       rule_name[return_type]:
#            | first_alt
#            | second_alt
# ( e )
#   Match e (allows also to use other operators in the group like '(e)*')
# [ e ] or e?
#   Optionally match e.
# e*
#   Match zero or more occurrences of e.
# e+
#   Match one or more occurrences of e.
# s.e+
#   Match one or more occurrences of e, separated by s. The generated parse tree
#   does not include the separator. This is otherwise identical to (e (s e)*).
# &e
#   Succeed if e can be parsed, without consuming any input.
# !e
#   Fail if e can be parsed, without consuming any input.
# ~
#   Commit to the current alternative, even if it fails to parse.
# &&e
#   Eager parse e. The parser will not backtrack and will immediately 
#   fail with SyntaxError if e cannot be parsed.
#

# STARTING RULES
# ==============

file[mod_ty]: a=[statements] ENDMARKER @{ _PyPegen_make_module(p, a) @}
interactive[mod_ty]: a=statement_newline @{ _PyAST_Interactive(a, p->arena) @}
eval[mod_ty]: a=expressions NEWLINE* ENDMARKER @{ _PyAST_Expression(a, p->arena) @}
func_type[mod_ty]: '(' a=[type_expressions] ')' '->' b=expression NEWLINE* ENDMARKER @{ _PyAST_FunctionType(a, b, p->arena) @}

# GENERAL STATEMENTS
# ==================

statements[asdl_stmt_seq*]: a=statement+ @{ (asdl_stmt_seq*)_PyPegen_seq_flatten(p, a) @}

statement[asdl_stmt_seq*]: a=compound_stmt @{ (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) @} | a[asdl_stmt_seq*]=simple_stmts @{ a @}

statement_newline[asdl_stmt_seq*]:
    | a=compound_stmt NEWLINE @{ (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) @}
    | simple_stmts
    | NEWLINE @{ (asdl_stmt_seq*)_PyPegen_singleton_seq(p, CHECK(stmt_ty, _PyAST_Pass(EXTRA))) @}
    | ENDMARKER @{ _PyPegen_interactive_exit(p) @}

simple_stmts[asdl_stmt_seq*]:
    | a=simple_stmt !';' NEWLINE @{ (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) @} # Not needed, there for speedup
    | a[asdl_stmt_seq*]=';'.simple_stmt+ [';'] NEWLINE @{ a @}

# NOTE: assignment MUST precede expression, else parsing a simple assignment
# will throw a SyntaxError.
simple_stmt[stmt_ty] (memo):
    | assignment
    | &"type" type_alias
    | e=star_expressions @{ _PyAST_Expr(e, EXTRA) @}
    | &'return' return_stmt
    | &('import' | 'from') import_stmt
    | &'raise' raise_stmt
    | 'pass' @{ _PyAST_Pass(EXTRA) @}
    | &'del' del_stmt
    | &'yield' yield_stmt
    | &'assert' assert_stmt
    | 'break' @{ _PyAST_Break(EXTRA) @}
    | 'continue' @{ _PyAST_Continue(EXTRA) @}
    | &'global' global_stmt
    | &'nonlocal' nonlocal_stmt

compound_stmt[stmt_ty]:
    | &('def' | '@@' | 'async') function_def
    | &'if' if_stmt
    | &('class' | '@@') class_def
    | &('with' | 'async') with_stmt
    | &('for' | 'async') for_stmt
    | &'try' try_stmt
    | &'while' while_stmt
    | match_stmt

# SIMPLE STATEMENTS
# =================

# NOTE: annotated_rhs may start with 'yield'; yield_expr must start with 'yield'
assignment[stmt_ty]:
    | a=NAME ':' b=expression c=['=' d=annotated_rhs @{ d @}] @{
        CHECK_VERSION(
            stmt_ty,
            6,
            "Variable annotation syntax is",
            _PyAST_AnnAssign(CHECK(expr_ty, _PyPegen_set_expr_context(p, a, Store)), b, c, 1, EXTRA)
        ) @}
    | a=('(' b=single_target ')' @{ b @}
         | single_subscript_attribute_target) ':' b=expression c=['=' d=annotated_rhs @{ d @}] @{
        CHECK_VERSION(stmt_ty, 6, "Variable annotations syntax is", _PyAST_AnnAssign(a, b, c, 0, EXTRA)) @}
    | a[asdl_expr_seq*]=(z=star_targets '=' @{ z @})+ b=(yield_expr | star_expressions) !'=' tc=[TYPE_COMMENT] @{
         _PyAST_Assign(a, b, NEW_TYPE_COMMENT(p, tc), EXTRA) @}
    | a=single_target b=augassign ~ c=(yield_expr | star_expressions) @{
         _PyAST_AugAssign(a, b->kind, c, EXTRA) @}
    | invalid_assignment

annotated_rhs[expr_ty]: yield_expr | star_expressions

augassign[AugOperator*]:
    | '+=' @{ _PyPegen_augoperator(p, Add) @}
    | '-=' @{ _PyPegen_augoperator(p, Sub) @}
    | '*=' @{ _PyPegen_augoperator(p, Mult) @}
    | '@@=' @{ CHECK_VERSION(AugOperator*, 5, "The '@@' operator is", _PyPegen_augoperator(p, MatMult)) @}
    | '/=' @{ _PyPegen_augoperator(p, Div) @}
    | '%=' @{ _PyPegen_augoperator(p, Mod) @}
    | '&=' @{ _PyPegen_augoperator(p, BitAnd) @}
    | '|=' @{ _PyPegen_augoperator(p, BitOr) @}
    | '^=' @{ _PyPegen_augoperator(p, BitXor) @}
    | '<<=' @{ _PyPegen_augoperator(p, LShift) @}
    | '>>=' @{ _PyPegen_augoperator(p, RShift) @}
    | '**=' @{ _PyPegen_augoperator(p, Pow) @}
    | '//=' @{ _PyPegen_augoperator(p, FloorDiv) @}

return_stmt[stmt_ty]:
    | 'return' a=[star_expressions] @{ _PyAST_Return(a, EXTRA) @}

raise_stmt[stmt_ty]:
    | 'raise' a=expression b=['from' z=expression @{ z @}] @{ _PyAST_Raise(a, b, EXTRA) @}
    | 'raise' @{ _PyAST_Raise(NULL, NULL, EXTRA) @}

global_stmt[stmt_ty]: 'global' a[asdl_expr_seq*]=','.NAME+ @{
    _PyAST_Global(CHECK(asdl_identifier_seq*, _PyPegen_map_names_to_ids(p, a)), EXTRA) @}

nonlocal_stmt[stmt_ty]: 'nonlocal' a[asdl_expr_seq*]=','.NAME+ @{
    _PyAST_Nonlocal(CHECK(asdl_identifier_seq*, _PyPegen_map_names_to_ids(p, a)), EXTRA) @}

del_stmt[stmt_ty]:
    | 'del' a=del_targets &(';' | NEWLINE) @{ _PyAST_Delete(a, EXTRA) @}
    | invalid_del_stmt

yield_stmt[stmt_ty]: y=yield_expr @{ _PyAST_Expr(y, EXTRA) @}

assert_stmt[stmt_ty]: 'assert' a=expression b=[',' z=expression @{ z @}] @{ _PyAST_Assert(a, b, EXTRA) @}

import_stmt[stmt_ty]:
    | invalid_import
    | import_name
    | import_from

# Import statements
# -----------------

import_name[stmt_ty]: 'import' a=dotted_as_names @{ _PyAST_Import(a, EXTRA) @}
# note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
import_from[stmt_ty]:
    | 'from' a=('.' | '...')* b=dotted_name 'import' c=import_from_targets @{
        _PyAST_ImportFrom(b->v.Name.id, c, _PyPegen_seq_count_dots(a), EXTRA) @}
    | 'from' a=('.' | '...')+ 'import' b=import_from_targets @{
        _PyAST_ImportFrom(NULL, b, _PyPegen_seq_count_dots(a), EXTRA) @}
import_from_targets[asdl_alias_seq*]:
    | '(' a=import_from_as_names [','] ')' @{ a @}
    | import_from_as_names !','
    | '*' @{ (asdl_alias_seq*)_PyPegen_singleton_seq(p, CHECK(alias_ty, _PyPegen_alias_for_star(p, EXTRA))) @}
    | invalid_import_from_targets
import_from_as_names[asdl_alias_seq*]:
    | a[asdl_alias_seq*]=','.import_from_as_name+ @{ a @}
import_from_as_name[alias_ty]:
    | a=NAME b=['as' z=NAME @{ z @}] @{ _PyAST_alias(a->v.Name.id,
                                               (b) ? ((expr_ty) b)->v.Name.id : NULL,
                                               EXTRA) @}
dotted_as_names[asdl_alias_seq*]:
    | a[asdl_alias_seq*]=','.dotted_as_name+ @{ a @}
dotted_as_name[alias_ty]:
    | a=dotted_name b=['as' z=NAME @{ z @}] @{ _PyAST_alias(a->v.Name.id,
                                                      (b) ? ((expr_ty) b)->v.Name.id : NULL,
                                                      EXTRA) @}
dotted_name[expr_ty]:
    | a=dotted_name '.' b=NAME @{ _PyPegen_join_names_with_dot(p, a, b) @}
    | NAME

# COMPOUND STATEMENTS
# ===================

# Common elements
# ---------------

block[asdl_stmt_seq*] (memo):
    | NEWLINE INDENT a=statements DEDENT @{ a @}
    | simple_stmts
    | invalid_block

decorators[asdl_expr_seq*]: a[asdl_expr_seq*]=('@@' f=named_expression NEWLINE @{ f @})+ @{ a @}

# Class definitions
# -----------------

class_def[stmt_ty]:
    | a=decorators b=class_def_raw @{ _PyPegen_class_def_decorators(p, a, b) @}
    | class_def_raw

class_def_raw[stmt_ty]:
    | invalid_class_def_raw
    | 'class' a=NAME t=[type_params] b=['(' z=[arguments] ')' @{ z @}] ':' c=block @{
        _PyAST_ClassDef(a->v.Name.id,
                     (b) ? ((expr_ty) b)->v.Call.args : NULL,
                     (b) ? ((expr_ty) b)->v.Call.keywords : NULL,
                     c, NULL, t, EXTRA) @}

# Function definitions
# --------------------

function_def[stmt_ty]:
    | d=decorators f=function_def_raw @{ _PyPegen_function_def_decorators(p, d, f) @}
    | function_def_raw

function_def_raw[stmt_ty]:
    | invalid_def_raw
    | 'def' n=NAME t=[type_params] '(' params=[params] ')' a=['->' z=expression @{ z @}] ':' tc=[func_type_comment] b=block @{
        _PyAST_FunctionDef(n->v.Name.id,
                        (params) ? params : CHECK(arguments_ty, _PyPegen_empty_arguments(p)),
                        b, NULL, a, NEW_TYPE_COMMENT(p, tc), t, EXTRA) @}
    | 'async' 'def' n=NAME t=[type_params] '(' params=[params] ')' a=['->' z=expression @{ z @}] ':' tc=[func_type_comment] b=block @{
        CHECK_VERSION(
            stmt_ty,
            5,
            "Async functions are",
            _PyAST_AsyncFunctionDef(n->v.Name.id,
                            (params) ? params : CHECK(arguments_ty, _PyPegen_empty_arguments(p)),
                            b, NULL, a, NEW_TYPE_COMMENT(p, tc), t, EXTRA)
        ) @}

# Function parameters
# -------------------

params[arguments_ty]:
    | invalid_parameters
    | parameters

parameters[arguments_ty]:
    | a=slash_no_default b[asdl_arg_seq*]=param_no_default* c=param_with_default* d=[star_etc] @{
        CHECK_VERSION(arguments_ty, 8, "Positional-only parameters are", _PyPegen_make_arguments(p, a, NULL, b, c, d)) @}
    | a=slash_with_default b=param_with_default* c=[star_etc] @{
        CHECK_VERSION(arguments_ty, 8, "Positional-only parameters are", _PyPegen_make_arguments(p, NULL, a, NULL, b, c)) @}
    | a[asdl_arg_seq*]=param_no_default+ b=param_with_default* c=[star_etc] @{
        _PyPegen_make_arguments(p, NULL, NULL, a, b, c) @}
    | a=param_with_default+ b=[star_etc] @{ _PyPegen_make_arguments(p, NULL, NULL, NULL, a, b)@}
    | a=star_etc @{ _PyPegen_make_arguments(p, NULL, NULL, NULL, NULL, a) @}

# Some duplication here because we can't write (',' | &')'),
# which is because we don't support empty alternatives (yet).

slash_no_default[asdl_arg_seq*]:
    | a[asdl_arg_seq*]=param_no_default+ '/' ',' @{ a @}
    | a[asdl_arg_seq*]=param_no_default+ '/' &')' @{ a @}
slash_with_default[SlashWithDefault*]:
    | a=param_no_default* b=param_with_default+ '/' ',' @{ _PyPegen_slash_with_default(p, (asdl_arg_seq *)a, b) @}
    | a=param_no_default* b=param_with_default+ '/' &')' @{ _PyPegen_slash_with_default(p, (asdl_arg_seq *)a, b) @}

star_etc[StarEtc*]:
    | invalid_star_etc
    | '*' a=param_no_default b=param_maybe_default* c=[kwds] @{
        _PyPegen_star_etc(p, a, b, c) @}
    | '*' a=param_no_default_star_annotation b=param_maybe_default* c=[kwds] @{
        _PyPegen_star_etc(p, a, b, c) @}
    | '*' ',' b=param_maybe_default+ c=[kwds] @{
        _PyPegen_star_etc(p, NULL, b, c) @}
    | a=kwds @{ _PyPegen_star_etc(p, NULL, NULL, a) @}

kwds[arg_ty]:
    | invalid_kwds
    | '**' a=param_no_default @{ a @}

# One parameter.  This *includes* a following comma and type comment.
#
# There are three styles:
# - No default
# - With default
# - Maybe with default
#
# There are two alternative forms of each, to deal with type comments:
# - Ends in a comma followed by an optional type comment
# - No comma, optional type comment, must be followed by close paren
# The latter form is for a final parameter without trailing comma.
#

param_no_default[arg_ty]:
    | a=param ',' tc=TYPE_COMMENT? @{ _PyPegen_add_type_comment_to_arg(p, a, tc) @}
    | a=param tc=TYPE_COMMENT? &')' @{ _PyPegen_add_type_comment_to_arg(p, a, tc) @}
param_no_default_star_annotation[arg_ty]:
    | a=param_star_annotation ',' tc=TYPE_COMMENT? @{ _PyPegen_add_type_comment_to_arg(p, a, tc) @}
    | a=param_star_annotation tc=TYPE_COMMENT? &')' @{ _PyPegen_add_type_comment_to_arg(p, a, tc) @}
param_with_default[NameDefaultPair*]:
    | a=param c=default ',' tc=TYPE_COMMENT? @{ _PyPegen_name_default_pair(p, a, c, tc) @}
    | a=param c=default tc=TYPE_COMMENT? &')' @{ _PyPegen_name_default_pair(p, a, c, tc) @}
param_maybe_default[NameDefaultPair*]:
    | a=param c=default? ',' tc=TYPE_COMMENT? @{ _PyPegen_name_default_pair(p, a, c, tc) @}
    | a=param c=default? tc=TYPE_COMMENT? &')' @{ _PyPegen_name_default_pair(p, a, c, tc) @}
param[arg_ty]: a=NAME b=annotation? @{ _PyAST_arg(a->v.Name.id, b, NULL, EXTRA) @}
param_star_annotation[arg_ty]: a=NAME b=star_annotation @{ _PyAST_arg(a->v.Name.id, b, NULL, EXTRA) @}
annotation[expr_ty]: ':' a=expression @{ a @}
star_annotation[expr_ty]: ':' a=star_expression @{ a @}
default[expr_ty]: '=' a=expression @{ a @} | invalid_default

# If statement
# ------------

if_stmt[stmt_ty]:
    | invalid_if_stmt
    | 'if' a=named_expression ':' b=block c=elif_stmt @{
        _PyAST_If(a, b, CHECK(asdl_stmt_seq*, _PyPegen_singleton_seq(p, c)), EXTRA) @}
    | 'if' a=named_expression ':' b=block c=[else_block] @{ _PyAST_If(a, b, c, EXTRA) @}
elif_stmt[stmt_ty]:
    | invalid_elif_stmt
    | 'elif' a=named_expression ':' b=block c=elif_stmt @{
        _PyAST_If(a, b, CHECK(asdl_stmt_seq*, _PyPegen_singleton_seq(p, c)), EXTRA) @}
    | 'elif' a=named_expression ':' b=block c=[else_block] @{ _PyAST_If(a, b, c, EXTRA) @}
else_block[asdl_stmt_seq*]:
    | invalid_else_stmt
    | 'else' &&':' b=block @{ b @}

# While statement
# ---------------

while_stmt[stmt_ty]:
    | invalid_while_stmt
    | 'while' a=named_expression ':' b=block c=[else_block] @{ _PyAST_While(a, b, c, EXTRA) @}

# For statement
# -------------

for_stmt[stmt_ty]:
    | invalid_for_stmt
    | 'for' t=star_targets 'in' ~ ex=star_expressions ':' tc=[TYPE_COMMENT] b=block el=[else_block] @{
        _PyAST_For(t, ex, b, el, NEW_TYPE_COMMENT(p, tc), EXTRA) @}
    | 'async' 'for' t=star_targets 'in' ~ ex=star_expressions ':' tc=[TYPE_COMMENT] b=block el=[else_block] @{
        CHECK_VERSION(stmt_ty, 5, "Async for loops are", _PyAST_AsyncFor(t, ex, b, el, NEW_TYPE_COMMENT(p, tc), EXTRA)) @}
    | invalid_for_target

# With statement
# --------------

with_stmt[stmt_ty]:
    | invalid_with_stmt_indent
    | 'with' '(' a[asdl_withitem_seq*]=','.with_item+ ','? ')' ':' tc=[TYPE_COMMENT] b=block @{
       _PyAST_With(a, b, NEW_TYPE_COMMENT(p, tc), EXTRA) @}
    | 'with' a[asdl_withitem_seq*]=','.with_item+ ':' tc=[TYPE_COMMENT] b=block @{
        _PyAST_With(a, b, NEW_TYPE_COMMENT(p, tc), EXTRA) @}
    | 'async' 'with' '(' a[asdl_withitem_seq*]=','.with_item+ ','? ')' ':' b=block @{
       CHECK_VERSION(stmt_ty, 5, "Async with statements are", _PyAST_AsyncWith(a, b, NULL, EXTRA)) @}
    | 'async' 'with' a[asdl_withitem_seq*]=','.with_item+ ':' tc=[TYPE_COMMENT] b=block @{
       CHECK_VERSION(stmt_ty, 5, "Async with statements are", _PyAST_AsyncWith(a, b, NEW_TYPE_COMMENT(p, tc), EXTRA)) @}
    | invalid_with_stmt

with_item[withitem_ty]:
    | e=expression 'as' t=star_target &(',' | ')' | ':') @{ _PyAST_withitem(e, t, p->arena) @}
    | invalid_with_item
    | e=expression @{ _PyAST_withitem(e, NULL, p->arena) @}

# Try statement
# -------------

try_stmt[stmt_ty]:
    | invalid_try_stmt
    | 'try' &&':' b=block f=finally_block @{ _PyAST_Try(b, NULL, NULL, f, EXTRA) @}
    | 'try' &&':' b=block ex[asdl_excepthandler_seq*]=except_block+ el=[else_block] f=[finally_block] @{ _PyAST_Try(b, ex, el, f, EXTRA) @}
    | 'try' &&':' b=block ex[asdl_excepthandler_seq*]=except_star_block+ el=[else_block] f=[finally_block] @{
        CHECK_VERSION(stmt_ty, 11, "Exception groups are",
                      _PyAST_TryStar(b, ex, el, f, EXTRA)) @}


# Except statement
# ----------------

except_block[excepthandler_ty]:
    | invalid_except_stmt_indent
    | 'except' e=expression t=['as' z=NAME @{ z @}] ':' b=block @{
        _PyAST_ExceptHandler(e, (t) ? ((expr_ty) t)->v.Name.id : NULL, b, EXTRA) @}
    | 'except' ':' b=block @{ _PyAST_ExceptHandler(NULL, NULL, b, EXTRA) @}
    | invalid_except_stmt
except_star_block[excepthandler_ty]:
    | invalid_except_star_stmt_indent
    | 'except' '*' e=expression t=['as' z=NAME @{ z @}] ':' b=block @{
        _PyAST_ExceptHandler(e, (t) ? ((expr_ty) t)->v.Name.id : NULL, b, EXTRA) @}
    | invalid_except_stmt
finally_block[asdl_stmt_seq*]:
    | invalid_finally_stmt
    | 'finally' &&':' a=block @{ a @}

# Match statement
# ---------------

match_stmt[stmt_ty]:
    | "match" subject=subject_expr ':' NEWLINE INDENT cases[asdl_match_case_seq*]=case_block+ DEDENT @{
        CHECK_VERSION(stmt_ty, 10, "Pattern matching is", _PyAST_Match(subject, cases, EXTRA)) @}
    | invalid_match_stmt

subject_expr[expr_ty]:
    | value=star_named_expression ',' values=star_named_expressions? @{
        _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, value, values)), Load, EXTRA) @}
    | named_expression

case_block[match_case_ty]:
    | invalid_case_block
    | "case" pattern=patterns guard=guard? ':' body=block @{
        _PyAST_match_case(pattern, guard, body, p->arena) @}

guard[expr_ty]: 'if' guard=named_expression @{ guard @}

patterns[pattern_ty]:
    | patterns[asdl_pattern_seq*]=open_sequence_pattern @{
        _PyAST_MatchSequence(patterns, EXTRA) @}
    | pattern

pattern[pattern_ty]:
    | as_pattern
    | or_pattern

as_pattern[pattern_ty]:
    | pattern=or_pattern 'as' target=pattern_capture_target @{
        _PyAST_MatchAs(pattern, target->v.Name.id, EXTRA) @}
    | invalid_as_pattern

or_pattern[pattern_ty]:
    | patterns[asdl_pattern_seq*]='|'.closed_pattern+ @{
        asdl_seq_LEN(patterns) == 1 ? asdl_seq_GET(patterns, 0) : _PyAST_MatchOr(patterns, EXTRA) @}

closed_pattern[pattern_ty] (memo):
    | literal_pattern
    | capture_pattern
    | wildcard_pattern
    | value_pattern
    | group_pattern
    | sequence_pattern
    | mapping_pattern
    | class_pattern

# Literal patterns are used for equality and identity constraints
literal_pattern[pattern_ty]:
    | value=signed_number !('+' | '-') @{ _PyAST_MatchValue(value, EXTRA) @}
    | value=complex_number @{ _PyAST_MatchValue(value, EXTRA) @}
    | value=strings @{ _PyAST_MatchValue(value, EXTRA) @}
    | 'None' @{ _PyAST_MatchSingleton(Py_None, EXTRA) @}
    | 'True' @{ _PyAST_MatchSingleton(Py_True, EXTRA) @}
    | 'False' @{ _PyAST_MatchSingleton(Py_False, EXTRA) @}

# Literal expressions are used to restrict permitted mapping pattern keys
literal_expr[expr_ty]:
    | signed_number !('+' | '-')
    | complex_number
    | strings
    | 'None' @{ _PyAST_Constant(Py_None, NULL, EXTRA) @}
    | 'True' @{ _PyAST_Constant(Py_True, NULL, EXTRA) @}
    | 'False' @{ _PyAST_Constant(Py_False, NULL, EXTRA) @}

complex_number[expr_ty]:
    | real=signed_real_number '+' imag=imaginary_number @{
        _PyAST_BinOp(real, Add, imag, EXTRA) @}
    | real=signed_real_number '-' imag=imaginary_number  @{
        _PyAST_BinOp(real, Sub, imag, EXTRA) @}

signed_number[expr_ty]:
    | NUMBER
    | '-' number=NUMBER @{ _PyAST_UnaryOp(USub, number, EXTRA) @}

signed_real_number[expr_ty]:
    | real_number
    | '-' real=real_number @{ _PyAST_UnaryOp(USub, real, EXTRA) @}

real_number[expr_ty]:
    | real=NUMBER @{ _PyPegen_ensure_real(p, real) @}

imaginary_number[expr_ty]:
    | imag=NUMBER @{ _PyPegen_ensure_imaginary(p, imag) @}

capture_pattern[pattern_ty]:
    | target=pattern_capture_target @{ _PyAST_MatchAs(NULL, target->v.Name.id, EXTRA) @}

pattern_capture_target[expr_ty]:
    | !"_" name=NAME !('.' | '(' | '=') @{
        _PyPegen_set_expr_context(p, name, Store) @}

wildcard_pattern[pattern_ty]:
    | "_" @{ _PyAST_MatchAs(NULL, NULL, EXTRA) @}

value_pattern[pattern_ty]:
    | attr=attr !('.' | '(' | '=') @{ _PyAST_MatchValue(attr, EXTRA) @}

attr[expr_ty]:
    | value=name_or_attr '.' attr=NAME @{
        _PyAST_Attribute(value, attr->v.Name.id, Load, EXTRA) @}

name_or_attr[expr_ty]:
    | attr
    | NAME

group_pattern[pattern_ty]:
    | '(' pattern=pattern ')' @{ pattern @}

sequence_pattern[pattern_ty]:
    | '[' patterns=maybe_sequence_pattern? ']' @{ _PyAST_MatchSequence(patterns, EXTRA) @}
    | '(' patterns=open_sequence_pattern? ')' @{ _PyAST_MatchSequence(patterns, EXTRA) @}

open_sequence_pattern[asdl_seq*]:
    | pattern=maybe_star_pattern ',' patterns=maybe_sequence_pattern? @{
        _PyPegen_seq_insert_in_front(p, pattern, patterns) @}

maybe_sequence_pattern[asdl_seq*]:
    | patterns=','.maybe_star_pattern+ ','? @{ patterns @}

maybe_star_pattern[pattern_ty]:
    | star_pattern
    | pattern

star_pattern[pattern_ty] (memo):
    | '*' target=pattern_capture_target @{
        _PyAST_MatchStar(target->v.Name.id, EXTRA) @}
    | '*' wildcard_pattern @{
        _PyAST_MatchStar(NULL, EXTRA) @}

mapping_pattern[pattern_ty]:
    | '@{' '@}' @{
        _PyAST_MatchMapping(NULL, NULL, NULL, EXTRA) @}
    | '@{' rest=double_star_pattern ','? '@}' @{
        _PyAST_MatchMapping(NULL, NULL, rest->v.Name.id, EXTRA) @}
    | '@{' items=items_pattern ',' rest=double_star_pattern ','? '@}' @{
        _PyAST_MatchMapping(
            CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, items)),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, items)),
            rest->v.Name.id,
            EXTRA) @}
    | '@{' items=items_pattern ','? '@}' @{
        _PyAST_MatchMapping(
            CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, items)),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, items)),
            NULL,
            EXTRA) @}

items_pattern[asdl_seq*]:
    | ','.key_value_pattern+

key_value_pattern[KeyPatternPair*]:
    | key=(literal_expr | attr) ':' pattern=pattern @{
        _PyPegen_key_pattern_pair(p, key, pattern) @}

double_star_pattern[expr_ty]:
    | '**' target=pattern_capture_target @{ target @}

class_pattern[pattern_ty]:
    | cls=name_or_attr '(' ')' @{
        _PyAST_MatchClass(cls, NULL, NULL, NULL, EXTRA) @}
    | cls=name_or_attr '(' patterns=positional_patterns ','? ')' @{
        _PyAST_MatchClass(cls, patterns, NULL, NULL, EXTRA) @}
    | cls=name_or_attr '(' keywords=keyword_patterns ','? ')' @{
        _PyAST_MatchClass(
            cls, NULL,
            CHECK(asdl_identifier_seq*, _PyPegen_map_names_to_ids(p,
                CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, keywords)))),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, keywords)),
            EXTRA) @}
    | cls=name_or_attr '(' patterns=positional_patterns ',' keywords=keyword_patterns ','? ')' @{
        _PyAST_MatchClass(
            cls,
            patterns,
            CHECK(asdl_identifier_seq*, _PyPegen_map_names_to_ids(p,
                CHECK(asdl_expr_seq*, _PyPegen_get_pattern_keys(p, keywords)))),
            CHECK(asdl_pattern_seq*, _PyPegen_get_patterns(p, keywords)),
            EXTRA) @}
    | invalid_class_pattern

positional_patterns[asdl_pattern_seq*]:
    | args[asdl_pattern_seq*]=','.pattern+ @{ args @}

keyword_patterns[asdl_seq*]:
    | ','.keyword_pattern+

keyword_pattern[KeyPatternPair*]:
    | arg=NAME '=' value=pattern @{ _PyPegen_key_pattern_pair(p, arg, value) @}

# Type statement
# ---------------

type_alias[stmt_ty]:
    | "type" n=NAME t=[type_params] '=' b=expression @{
        CHECK_VERSION(stmt_ty, 12, "Type statement is",
        _PyAST_TypeAlias(CHECK(expr_ty, _PyPegen_set_expr_context(p, n, Store)), t, b, EXTRA)) @}

# Type parameter declaration
# --------------------------

type_params[asdl_type_param_seq*]: 
    | invalid_type_params
    | '[' t=type_param_seq ']' @{
        CHECK_VERSION(asdl_type_param_seq *, 12, "Type parameter lists are", t) @}

type_param_seq[asdl_type_param_seq*]: a[asdl_type_param_seq*]=','.type_param+ [','] @{ a @}

type_param[type_param_ty] (memo):
    | a=NAME b=[type_param_bound] c=[type_param_default] @{ _PyAST_TypeVar(a->v.Name.id, b, c, EXTRA) @}
    | '*' a=NAME colon=':' e=expression @{
            RAISE_SYNTAX_ERROR_STARTING_FROM(colon, e->kind == Tuple_kind
                ? "cannot use constraints with TypeVarTuple"
                : "cannot use bound with TypeVarTuple")
        @}
    | '*' a=NAME b=[type_param_starred_default] @{ _PyAST_TypeVarTuple(a->v.Name.id, b, EXTRA) @}
    | '**' a=NAME colon=':' e=expression @{
            RAISE_SYNTAX_ERROR_STARTING_FROM(colon, e->kind == Tuple_kind
                ? "cannot use constraints with ParamSpec"
                : "cannot use bound with ParamSpec")
        @}
    | '**' a=NAME b=[type_param_default] @{ _PyAST_ParamSpec(a->v.Name.id, b, EXTRA) @}

type_param_bound[expr_ty]: ':' e=expression @{ e @}
type_param_default[expr_ty]: '=' e=expression @{
    CHECK_VERSION(expr_ty, 13, "Type parameter defaults are", e) @}
type_param_starred_default[expr_ty]: '=' e=star_expression @{
    CHECK_VERSION(expr_ty, 13, "Type parameter defaults are", e) @}

# EXPRESSIONS
# -----------

expressions[expr_ty]:
    | a=expression b=(',' c=expression @{ c @})+ [','] @{
        _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)), Load, EXTRA) @}
    | a=expression ',' @{ _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_singleton_seq(p, a)), Load, EXTRA) @}
    | expression

expression[expr_ty] (memo):
    | invalid_expression
    | invalid_legacy_expression
    | a=disjunction 'if' b=disjunction 'else' c=expression @{ _PyAST_IfExp(b, a, c, EXTRA) @}
    | disjunction
    | lambdef

yield_expr[expr_ty]:
    | 'yield' 'from' a=expression @{ _PyAST_YieldFrom(a, EXTRA) @}
    | 'yield' a=[star_expressions] @{ _PyAST_Yield(a, EXTRA) @}

star_expressions[expr_ty]:
    | a=star_expression b=(',' c=star_expression @{ c @})+ [','] @{
        _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)), Load, EXTRA) @}
    | a=star_expression ',' @{ _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_singleton_seq(p, a)), Load, EXTRA) @}
    | star_expression

star_expression[expr_ty] (memo):
    | '*' a=bitwise_or @{ _PyAST_Starred(a, Load, EXTRA) @}
    | expression

star_named_expressions[asdl_expr_seq*]: a[asdl_expr_seq*]=','.star_named_expression+ [','] @{ a @}

star_named_expression[expr_ty]:
    | '*' a=bitwise_or @{ _PyAST_Starred(a, Load, EXTRA) @}
    | named_expression

assignment_expression[expr_ty]:
    | a=NAME ':=' ~ b=expression @{
        CHECK_VERSION(expr_ty, 8, "Assignment expressions are",
        _PyAST_NamedExpr(CHECK(expr_ty, _PyPegen_set_expr_context(p, a, Store)), b, EXTRA)) @}

named_expression[expr_ty]:
    | assignment_expression
    | invalid_named_expression
    | expression !':='

disjunction[expr_ty] (memo):
    | a=conjunction b=('or' c=conjunction @{ c @})+ @{ _PyAST_BoolOp(
        Or,
        CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)),
        EXTRA) @}
    | conjunction

conjunction[expr_ty] (memo):
    | a=inversion b=('and' c=inversion @{ c @})+ @{ _PyAST_BoolOp(
        And,
        CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)),
        EXTRA) @}
    | inversion

inversion[expr_ty] (memo):
    | 'not' a=inversion @{ _PyAST_UnaryOp(Not, a, EXTRA) @}
    | comparison

# Comparison operators
# --------------------

comparison[expr_ty]:
    | a=bitwise_or b=compare_op_bitwise_or_pair+ @{
        _PyAST_Compare(
            a,
            CHECK(asdl_int_seq*, _PyPegen_get_cmpops(p, b)),
            CHECK(asdl_expr_seq*, _PyPegen_get_exprs(p, b)),
            EXTRA) @}
    | bitwise_or

compare_op_bitwise_or_pair[CmpopExprPair*]:
    | eq_bitwise_or
    | noteq_bitwise_or
    | lte_bitwise_or
    | lt_bitwise_or
    | gte_bitwise_or
    | gt_bitwise_or
    | notin_bitwise_or
    | in_bitwise_or
    | isnot_bitwise_or
    | is_bitwise_or

eq_bitwise_or[CmpopExprPair*]: '==' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Eq, a) @}
noteq_bitwise_or[CmpopExprPair*]:
    | (tok='!=' @{ _PyPegen_check_barry_as_flufl(p, tok) ? NULL : tok@}) a=bitwise_or @{_PyPegen_cmpop_expr_pair(p, NotEq, a) @}
lte_bitwise_or[CmpopExprPair*]: '<=' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, LtE, a) @}
lt_bitwise_or[CmpopExprPair*]: '<' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Lt, a) @}
gte_bitwise_or[CmpopExprPair*]: '>=' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, GtE, a) @}
gt_bitwise_or[CmpopExprPair*]: '>' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Gt, a) @}
notin_bitwise_or[CmpopExprPair*]: 'not' 'in' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, NotIn, a) @}
in_bitwise_or[CmpopExprPair*]: 'in' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, In, a) @}
isnot_bitwise_or[CmpopExprPair*]: 'is' 'not' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, IsNot, a) @}
is_bitwise_or[CmpopExprPair*]: 'is' a=bitwise_or @{ _PyPegen_cmpop_expr_pair(p, Is, a) @}

# Bitwise operators
# -----------------

bitwise_or[expr_ty]:
    | a=bitwise_or '|' b=bitwise_xor @{ _PyAST_BinOp(a, BitOr, b, EXTRA) @}
    | bitwise_xor

bitwise_xor[expr_ty]:
    | a=bitwise_xor '^' b=bitwise_and @{ _PyAST_BinOp(a, BitXor, b, EXTRA) @}
    | bitwise_and

bitwise_and[expr_ty]:
    | a=bitwise_and '&' b=shift_expr @{ _PyAST_BinOp(a, BitAnd, b, EXTRA) @}
    | shift_expr

shift_expr[expr_ty]:
    | a=shift_expr '<<' b=sum @{ _PyAST_BinOp(a, LShift, b, EXTRA) @}
    | a=shift_expr '>>' b=sum @{ _PyAST_BinOp(a, RShift, b, EXTRA) @}
    | invalid_arithmetic
    | sum

# Arithmetic operators
# --------------------

sum[expr_ty]:
    | a=sum '+' b=term @{ _PyAST_BinOp(a, Add, b, EXTRA) @}
    | a=sum '-' b=term @{ _PyAST_BinOp(a, Sub, b, EXTRA) @}
    | term

term[expr_ty]:
    | a=term '*' b=factor @{ _PyAST_BinOp(a, Mult, b, EXTRA) @}
    | a=term '/' b=factor @{ _PyAST_BinOp(a, Div, b, EXTRA) @}
    | a=term '//' b=factor @{ _PyAST_BinOp(a, FloorDiv, b, EXTRA) @}
    | a=term '%' b=factor @{ _PyAST_BinOp(a, Mod, b, EXTRA) @}
    | a=term '@@' b=factor @{ CHECK_VERSION(expr_ty, 5, "The '@@' operator is", _PyAST_BinOp(a, MatMult, b, EXTRA)) @}
    | invalid_factor
    | factor

factor[expr_ty] (memo):
    | '+' a=factor @{ _PyAST_UnaryOp(UAdd, a, EXTRA) @}
    | '-' a=factor @{ _PyAST_UnaryOp(USub, a, EXTRA) @}
    | '~' a=factor @{ _PyAST_UnaryOp(Invert, a, EXTRA) @}
    | power

power[expr_ty]:
    | a=await_primary '**' b=factor @{ _PyAST_BinOp(a, Pow, b, EXTRA) @}
    | await_primary

# Primary elements
# ----------------

# Primary elements are things like "obj.something.something", "obj[something]", "obj(something)", "obj" ...

await_primary[expr_ty] (memo):
    | 'await' a=primary @{ CHECK_VERSION(expr_ty, 5, "Await expressions are", _PyAST_Await(a, EXTRA)) @}
    | primary

primary[expr_ty]:
    | a=primary '.' b=NAME @{ _PyAST_Attribute(a, b->v.Name.id, Load, EXTRA) @}
    | a=primary b=genexp @{ _PyAST_Call(a, CHECK(asdl_expr_seq*, (asdl_expr_seq*)_PyPegen_singleton_seq(p, b)), NULL, EXTRA) @}
    | a=primary '(' b=[arguments] ')' @{
        _PyAST_Call(a,
                 (b) ? ((expr_ty) b)->v.Call.args : NULL,
                 (b) ? ((expr_ty) b)->v.Call.keywords : NULL,
                 EXTRA) @}
    | a=primary '[' b=slices ']' @{ _PyAST_Subscript(a, b, Load, EXTRA) @}
    | atom

slices[expr_ty]:
    | a=slice !',' @{ a @}
    | a[asdl_expr_seq*]=','.(slice | starred_expression)+ [','] @{ _PyAST_Tuple(a, Load, EXTRA) @}

slice[expr_ty]:
    | a=[expression] ':' b=[expression] c=[':' d=[expression] @{ d @}] @{ _PyAST_Slice(a, b, c, EXTRA) @}
    | a=named_expression @{ a @}

atom[expr_ty]:
    | NAME
    | 'True' @{ _PyAST_Constant(Py_True, NULL, EXTRA) @}
    | 'False' @{ _PyAST_Constant(Py_False, NULL, EXTRA) @}
    | 'None' @{ _PyAST_Constant(Py_None, NULL, EXTRA) @}
    | &(STRING|FSTRING_START) strings
    | NUMBER
    | &'(' (tuple | group | genexp)
    | &'[' (list | listcomp)
    | &'@{' (dict | set | dictcomp | setcomp)
    | '...' @{ _PyAST_Constant(Py_Ellipsis, NULL, EXTRA) @}

group[expr_ty]:
    | '(' a=(yield_expr | named_expression) ')' @{ a @}
    | invalid_group

# Lambda functions
# ----------------

lambdef[expr_ty]:
    | 'lambda' a=[lambda_params] ':' b=expression @{
        _PyAST_Lambda((a) ? a : CHECK(arguments_ty, _PyPegen_empty_arguments(p)), b, EXTRA) @}

lambda_params[arguments_ty]:
    | invalid_lambda_parameters
    | lambda_parameters

# lambda_parameters etc. duplicates parameters but without annotations
# or type comments, and if there's no comma after a parameter, we expect
# a colon, not a close parenthesis.  (For more, see parameters above.)
#
lambda_parameters[arguments_ty]:
    | a=lambda_slash_no_default b[asdl_arg_seq*]=lambda_param_no_default* c=lambda_param_with_default* d=[lambda_star_etc] @{
        CHECK_VERSION(arguments_ty, 8, "Positional-only parameters are", _PyPegen_make_arguments(p, a, NULL, b, c, d)) @}
    | a=lambda_slash_with_default b=lambda_param_with_default* c=[lambda_star_etc] @{
        CHECK_VERSION(arguments_ty, 8, "Positional-only parameters are", _PyPegen_make_arguments(p, NULL, a, NULL, b, c)) @}
    | a[asdl_arg_seq*]=lambda_param_no_default+ b=lambda_param_with_default* c=[lambda_star_etc] @{
        _PyPegen_make_arguments(p, NULL, NULL, a, b, c) @}
    | a=lambda_param_with_default+ b=[lambda_star_etc] @{ _PyPegen_make_arguments(p, NULL, NULL, NULL, a, b)@}
    | a=lambda_star_etc @{ _PyPegen_make_arguments(p, NULL, NULL, NULL, NULL, a) @}

lambda_slash_no_default[asdl_arg_seq*]:
    | a[asdl_arg_seq*]=lambda_param_no_default+ '/' ',' @{ a @}
    | a[asdl_arg_seq*]=lambda_param_no_default+ '/' &':' @{ a @}

lambda_slash_with_default[SlashWithDefault*]:
    | a=lambda_param_no_default* b=lambda_param_with_default+ '/' ',' @{ _PyPegen_slash_with_default(p, (asdl_arg_seq *)a, b) @}
    | a=lambda_param_no_default* b=lambda_param_with_default+ '/' &':' @{ _PyPegen_slash_with_default(p, (asdl_arg_seq *)a, b) @}

lambda_star_etc[StarEtc*]:
    | invalid_lambda_star_etc
    | '*' a=lambda_param_no_default b=lambda_param_maybe_default* c=[lambda_kwds] @{
        _PyPegen_star_etc(p, a, b, c) @}
    | '*' ',' b=lambda_param_maybe_default+ c=[lambda_kwds] @{
        _PyPegen_star_etc(p, NULL, b, c) @}
    | a=lambda_kwds @{ _PyPegen_star_etc(p, NULL, NULL, a) @}

lambda_kwds[arg_ty]:
    | invalid_lambda_kwds
    | '**' a=lambda_param_no_default @{ a @}

lambda_param_no_default[arg_ty]:
    | a=lambda_param ',' @{ a @}
    | a=lambda_param &':' @{ a @}
lambda_param_with_default[NameDefaultPair*]:
    | a=lambda_param c=default ',' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
    | a=lambda_param c=default &':' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
lambda_param_maybe_default[NameDefaultPair*]:
    | a=lambda_param c=default? ',' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
    | a=lambda_param c=default? &':' @{ _PyPegen_name_default_pair(p, a, c, NULL) @}
lambda_param[arg_ty]: a=NAME @{ _PyAST_arg(a->v.Name.id, NULL, NULL, EXTRA) @}

# LITERALS
# ========

fstring_middle[expr_ty]:
    | fstring_replacement_field
    | t=FSTRING_MIDDLE @{ _PyPegen_constant_from_token(p, t) @}
fstring_replacement_field[expr_ty]:
    | '@{' a=annotated_rhs debug_expr='='? conversion=[fstring_conversion] format=[fstring_full_format_spec] rbrace='@}' @{
        _PyPegen_formatted_value(p, a, debug_expr, conversion, format, rbrace, EXTRA) @}
    | invalid_replacement_field
fstring_conversion[ResultTokenWithMetadata*]:
    | conv_token="!" conv=NAME @{ _PyPegen_check_fstring_conversion(p, conv_token, conv) @}
fstring_full_format_spec[ResultTokenWithMetadata*]:
    | colon=':' spec=fstring_format_spec* @{ _PyPegen_setup_full_format_spec(p, colon, (asdl_expr_seq *) spec, EXTRA) @}
fstring_format_spec[expr_ty]:
    | t=FSTRING_MIDDLE @{ _PyPegen_decoded_constant_from_token(p, t) @}
    | fstring_replacement_field
fstring[expr_ty]:
    | a=FSTRING_START b=fstring_middle* c=FSTRING_END @{ _PyPegen_joined_str(p, a, (asdl_expr_seq*)b, c) @}

string[expr_ty]: s[Token*]=STRING @{ _PyPegen_constant_from_string(p, s) @}
strings[expr_ty] (memo): a[asdl_expr_seq*]=(fstring|string)+ @{ _PyPegen_concatenate_strings(p, a, EXTRA) @}

list[expr_ty]:
    | '[' a=[star_named_expressions] ']' @{ _PyAST_List(a, Load, EXTRA) @}

tuple[expr_ty]:
    | '(' a=[y=star_named_expression ',' z=[star_named_expressions] @{ _PyPegen_seq_insert_in_front(p, y, z) @} ] ')' @{
        _PyAST_Tuple(a, Load, EXTRA) @}

set[expr_ty]: '@{' a=star_named_expressions '@}' @{ _PyAST_Set(a, EXTRA) @}

# Dicts
# -----

dict[expr_ty]:
    | '@{' a=[double_starred_kvpairs] '@}' @{
        _PyAST_Dict(
            CHECK(asdl_expr_seq*, _PyPegen_get_keys(p, a)),
            CHECK(asdl_expr_seq*, _PyPegen_get_values(p, a)),
            EXTRA) @}
    | '@{' invalid_double_starred_kvpairs '@}'

double_starred_kvpairs[asdl_seq*]: a=','.double_starred_kvpair+ [','] @{ a @}

double_starred_kvpair[KeyValuePair*]:
    | '**' a=bitwise_or @{ _PyPegen_key_value_pair(p, NULL, a) @}
    | kvpair

kvpair[KeyValuePair*]: a=expression ':' b=expression @{ _PyPegen_key_value_pair(p, a, b) @}

# Comprehensions & Generators
# ---------------------------

for_if_clauses[asdl_comprehension_seq*]:
    | a[asdl_comprehension_seq*]=for_if_clause+ @{ a @}

for_if_clause[comprehension_ty]:
    | 'async' 'for' a=star_targets 'in' ~ b=disjunction c[asdl_expr_seq*]=('if' z=disjunction @{ z @})* @{
        CHECK_VERSION(comprehension_ty, 6, "Async comprehensions are", _PyAST_comprehension(a, b, c, 1, p->arena)) @}
    | 'for' a=star_targets 'in' ~ b=disjunction c[asdl_expr_seq*]=('if' z=disjunction @{ z @})* @{
        _PyAST_comprehension(a, b, c, 0, p->arena) @}
    | 'async'? 'for' (bitwise_or (',' bitwise_or)* [',']) !'in' @{
        RAISE_SYNTAX_ERROR("'in' expected after for-loop variables") @}
    | invalid_for_target

listcomp[expr_ty]:
    | '[' a=named_expression b=for_if_clauses ']' @{ _PyAST_ListComp(a, b, EXTRA) @}
    | invalid_comprehension

setcomp[expr_ty]:
    | '@{' a=named_expression b=for_if_clauses '@}' @{ _PyAST_SetComp(a, b, EXTRA) @}
    | invalid_comprehension

genexp[expr_ty]:
    | '(' a=( assignment_expression | expression !':=') b=for_if_clauses ')' @{ _PyAST_GeneratorExp(a, b, EXTRA) @}
    | invalid_comprehension

dictcomp[expr_ty]:
    | '@{' a=kvpair b=for_if_clauses '@}' @{ _PyAST_DictComp(a->key, a->value, b, EXTRA) @}
    | invalid_dict_comprehension

# FUNCTION CALL ARGUMENTS
# =======================

arguments[expr_ty] (memo):
    | a=args [','] &')' @{ a @}
    | invalid_arguments

args[expr_ty]:
    | a[asdl_expr_seq*]=','.(starred_expression | ( assignment_expression | expression !':=') !'=')+ b=[',' k=kwargs @{k@}] @{
        _PyPegen_collect_call_seqs(p, a, b, EXTRA) @}
    | a=kwargs @{ _PyAST_Call(_PyPegen_dummy_name(p),
                          CHECK_NULL_ALLOWED(asdl_expr_seq*, _PyPegen_seq_extract_starred_exprs(p, a)),
                          CHECK_NULL_ALLOWED(asdl_keyword_seq*, _PyPegen_seq_delete_starred_exprs(p, a)),
                          EXTRA) @}

kwargs[asdl_seq*]:
    | a=','.kwarg_or_starred+ ',' b=','.kwarg_or_double_starred+ @{ _PyPegen_join_sequences(p, a, b) @}
    | ','.kwarg_or_starred+
    | ','.kwarg_or_double_starred+

starred_expression[expr_ty]:
    | invalid_starred_expression
    | '*' a=expression @{ _PyAST_Starred(a, Load, EXTRA) @}
    | '*' @{ RAISE_SYNTAX_ERROR("Invalid star expression") @}

kwarg_or_starred[KeywordOrStarred*]:
    | invalid_kwarg
    | a=NAME '=' b=expression @{
        _PyPegen_keyword_or_starred(p, CHECK(keyword_ty, _PyAST_keyword(a->v.Name.id, b, EXTRA)), 1) @}
    | a=starred_expression @{ _PyPegen_keyword_or_starred(p, a, 0) @}

kwarg_or_double_starred[KeywordOrStarred*]:
    | invalid_kwarg
    | a=NAME '=' b=expression @{
        _PyPegen_keyword_or_starred(p, CHECK(keyword_ty, _PyAST_keyword(a->v.Name.id, b, EXTRA)), 1) @}
    | '**' a=expression @{ _PyPegen_keyword_or_starred(p, CHECK(keyword_ty, _PyAST_keyword(NULL, a, EXTRA)), 1) @}

# ASSIGNMENT TARGETS
# ==================

# Generic targets
# ---------------

# NOTE: star_targets may contain *bitwise_or, targets may not.
star_targets[expr_ty]:
    | a=star_target !',' @{ a @}
    | a=star_target b=(',' c=star_target @{ c @})* [','] @{
        _PyAST_Tuple(CHECK(asdl_expr_seq*, _PyPegen_seq_insert_in_front(p, a, b)), Store, EXTRA) @}

star_targets_list_seq[asdl_expr_seq*]: a[asdl_expr_seq*]=','.star_target+ [','] @{ a @}

star_targets_tuple_seq[asdl_expr_seq*]:
    | a=star_target b=(',' c=star_target @{ c @})+ [','] @{ (asdl_expr_seq*) _PyPegen_seq_insert_in_front(p, a, b) @}
    | a=star_target ',' @{ (asdl_expr_seq*) _PyPegen_singleton_seq(p, a) @}

star_target[expr_ty] (memo):
    | '*' a=(!'*' star_target) @{
        _PyAST_Starred(CHECK(expr_ty, _PyPegen_set_expr_context(p, a, Store)), Store, EXTRA) @}
    | target_with_star_atom

target_with_star_atom[expr_ty] (memo):
    | a=t_primary '.' b=NAME !t_lookahead @{ _PyAST_Attribute(a, b->v.Name.id, Store, EXTRA) @}
    | a=t_primary '[' b=slices ']' !t_lookahead @{ _PyAST_Subscript(a, b, Store, EXTRA) @}
    | star_atom

star_atom[expr_ty]:
    | a=NAME @{ _PyPegen_set_expr_context(p, a, Store) @}
    | '(' a=target_with_star_atom ')' @{ _PyPegen_set_expr_context(p, a, Store) @}
    | '(' a=[star_targets_tuple_seq] ')' @{ _PyAST_Tuple(a, Store, EXTRA) @}
    | '[' a=[star_targets_list_seq] ']' @{ _PyAST_List(a, Store, EXTRA) @}

single_target[expr_ty]:
    | single_subscript_attribute_target
    | a=NAME @{ _PyPegen_set_expr_context(p, a, Store) @}
    | '(' a=single_target ')' @{ a @}

single_subscript_attribute_target[expr_ty]:
    | a=t_primary '.' b=NAME !t_lookahead @{ _PyAST_Attribute(a, b->v.Name.id, Store, EXTRA) @}
    | a=t_primary '[' b=slices ']' !t_lookahead @{ _PyAST_Subscript(a, b, Store, EXTRA) @}

t_primary[expr_ty]:
    | a=t_primary '.' b=NAME &t_lookahead @{ _PyAST_Attribute(a, b->v.Name.id, Load, EXTRA) @}
    | a=t_primary '[' b=slices ']' &t_lookahead @{ _PyAST_Subscript(a, b, Load, EXTRA) @}
    | a=t_primary b=genexp &t_lookahead @{
        _PyAST_Call(a, CHECK(asdl_expr_seq*, (asdl_expr_seq*)_PyPegen_singleton_seq(p, b)), NULL, EXTRA) @}
    | a=t_primary '(' b=[arguments] ')' &t_lookahead @{
        _PyAST_Call(a,
                 (b) ? ((expr_ty) b)->v.Call.args : NULL,
                 (b) ? ((expr_ty) b)->v.Call.keywords : NULL,
                 EXTRA) @}
    | a=atom &t_lookahead @{ a @}

t_lookahead: '(' | '[' | '.'

# Targets for del statements
# --------------------------

del_targets[asdl_expr_seq*]: a[asdl_expr_seq*]=','.del_target+ [','] @{ a @}

del_target[expr_ty] (memo):
    | a=t_primary '.' b=NAME !t_lookahead @{ _PyAST_Attribute(a, b->v.Name.id, Del, EXTRA) @}
    | a=t_primary '[' b=slices ']' !t_lookahead @{ _PyAST_Subscript(a, b, Del, EXTRA) @}
    | del_t_atom

del_t_atom[expr_ty]:
    | a=NAME @{ _PyPegen_set_expr_context(p, a, Del) @}
    | '(' a=del_target ')' @{ _PyPegen_set_expr_context(p, a, Del) @}
    | '(' a=[del_targets] ')' @{ _PyAST_Tuple(a, Del, EXTRA) @}
    | '[' a=[del_targets] ']' @{ _PyAST_List(a, Del, EXTRA) @}

# TYPING ELEMENTS
# ---------------

# type_expressions allow */** but ignore them
type_expressions[asdl_expr_seq*]:
    | a=','.expression+ ',' '*' b=expression ',' '**' c=expression @{
        (asdl_expr_seq*)_PyPegen_seq_append_to_end(
            p,
            CHECK(asdl_seq*, _PyPegen_seq_append_to_end(p, a, b)),
            c) @}
    | a=','.expression+ ',' '*' b=expression @{ (asdl_expr_seq*)_PyPegen_seq_append_to_end(p, a, b) @}
    | a=','.expression+ ',' '**' b=expression @{ (asdl_expr_seq*)_PyPegen_seq_append_to_end(p, a, b) @}
    | '*' a=expression ',' '**' b=expression @{
        (asdl_expr_seq*)_PyPegen_seq_append_to_end(
            p,
            CHECK(asdl_seq*, _PyPegen_singleton_seq(p, a)),
            b) @}
    | '*' a=expression @{ (asdl_expr_seq*)_PyPegen_singleton_seq(p, a) @}
    | '**' a=expression @{ (asdl_expr_seq*)_PyPegen_singleton_seq(p, a) @}
    | a[asdl_expr_seq*]=','.expression+ @{a@}

func_type_comment[Token*]:
    | NEWLINE t=TYPE_COMMENT &(NEWLINE INDENT) @{ t @}  # Must be followed by indented block
    | invalid_double_type_comments
    | TYPE_COMMENT

# ========================= END OF THE GRAMMAR ===========================



# ========================= START OF INVALID RULES =======================

# From here on, there are rules for invalid syntax with specialised error messages
invalid_arguments:
    | ((','.(starred_expression | ( assignment_expression | expression !':=') !'=')+ ',' kwargs) | kwargs) a=',' ','.(starred_expression !'=')+ @{
        RAISE_SYNTAX_ERROR_STARTING_FROM(a, "iterable argument unpacking follows keyword argument unpacking") @}
    | a=expression b=for_if_clauses ',' [args | expression for_if_clauses] @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, _PyPegen_get_last_comprehension_item(PyPegen_last_item(b, comprehension_ty)), "Generator expression must be parenthesized") @}
    | a=NAME b='=' expression for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid syntax. Maybe you meant '==' or ':=' instead of '='?")@}
    | (args ',')? a=NAME b='=' &(',' | ')') @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "expected argument value expression")@}
    | a=args b=for_if_clauses @{ _PyPegen_nonparen_genexp_in_call(p, a, b) @}
    | args ',' a=expression b=for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, _PyPegen_get_last_comprehension_item(PyPegen_last_item(b, comprehension_ty)), "Generator expression must be parenthesized") @}
    | a=args ',' args @{ _PyPegen_arguments_parsing_error(p, a) @}
invalid_kwarg:
    | a[Token*]=('True'|'False'|'None') b='=' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot assign to %s", PyBytes_AS_STRING(a->bytes)) @}
    | a=NAME b='=' expression for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid syntax. Maybe you meant '==' or ':=' instead of '='?")@}
    | !(NAME '=') a=expression b='=' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(
            a, b, "expression cannot contain assignment, perhaps you meant \"==\"?") @}
    | a='**' expression '=' b=expression @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot assign to keyword argument unpacking") @}

# IMPORTANT: Note that the "_without_invalid" suffix causes the rule to not call invalid rules under it
expression_without_invalid[expr_ty]:
    | a=disjunction 'if' b=disjunction 'else' c=expression @{ _PyAST_IfExp(b, a, c, EXTRA) @}
    | disjunction
    | lambdef
invalid_legacy_expression:
    | a=NAME !'(' b=star_expressions @{
        _PyPegen_check_legacy_stmt(p, a) ? RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b,
            "Missing parentheses in call to '%U'. Did you mean %U(...)?", a->v.Name.id, a->v.Name.id) : NULL@}

invalid_expression:
    # !(NAME STRING) is not matched so we don't show this error with some invalid string prefixes like: kf"dsfsdf"
    # Soft keywords need to also be ignored because they can be parsed as NAME NAME
   | !(NAME STRING | SOFT_KEYWORD) a=disjunction b=expression_without_invalid @{
        _PyPegen_check_legacy_stmt(p, a) ? NULL : p->tokens[p->mark-1]->level == 0 ? NULL :
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid syntax. Perhaps you forgot a comma?") @}
   | a=disjunction 'if' b=disjunction !('else'|':') @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "expected 'else' after 'if' expression") @}
   | a='lambda' [lambda_params] b=':' &FSTRING_MIDDLE  @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "f-string: lambda expressions are not allowed without parentheses") @}

invalid_named_expression(memo):
    | a=expression ':=' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a, "cannot use assignment expressions with %s", _PyPegen_get_expr_name(a)) @}
    | a=NAME '=' b=bitwise_or !('='|':=') @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "invalid syntax. Maybe you meant '==' or ':=' instead of '='?") @}
    | !(list|tuple|genexp|'True'|'None'|'False') a=bitwise_or b='=' bitwise_or !('='|':=') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot assign to %s here. Maybe you meant '==' instead of '='?",
                                          _PyPegen_get_expr_name(a)) @}

invalid_assignment:
    | a=invalid_ann_assign_target ':' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a,
            "only single target (not %s) can be annotated",
            _PyPegen_get_expr_name(a)
        )@}
    | a=star_named_expression ',' star_named_expressions* ':' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "only single target (not tuple) can be annotated") @}
    | a=expression ':' expression @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "illegal target for annotation") @}
    | (star_targets '=')* a=star_expressions '=' @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(STAR_TARGETS, a) @}
    | (star_targets '=')* a=yield_expr '=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "assignment to yield expression not possible") @}
    | a=star_expressions augassign annotated_rhs @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
            a,
            "'%s' is an illegal expression for augmented assignment",
            _PyPegen_get_expr_name(a)
        )@}
invalid_ann_assign_target[expr_ty]:
    | list
    | tuple
    | '(' a=invalid_ann_assign_target ')' @{ a @}
invalid_del_stmt:
    | 'del' a=star_expressions @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(DEL_TARGETS, a) @}
invalid_block:
    | NEWLINE !INDENT @{ RAISE_INDENTATION_ERROR("expected an indented block") @}
invalid_comprehension:
    | ('[' | '(' | '@{') a=starred_expression for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "iterable unpacking cannot be used in comprehension") @}
    | ('[' | '@{') a=star_named_expression ',' b=star_named_expressions for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, PyPegen_last_item(b, expr_ty),
        "did you forget parentheses around the comprehension target?") @}
    | ('[' | '@{') a=star_named_expression b=',' for_if_clauses @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "did you forget parentheses around the comprehension target?") @}
invalid_dict_comprehension:
    | '@{' a='**' bitwise_or for_if_clauses '@}' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "dict unpacking cannot be used in dict comprehension") @}
invalid_parameters:
    | a="/" ',' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "at least one argument must precede /") @}
    | (slash_no_default | slash_with_default) param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ may appear only once") @}
    | slash_no_default? param_no_default* invalid_parameters_helper a=param_no_default @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameter without a default follows parameter with a default") @}
    | param_no_default* a='(' param_no_default+ ','? b=')' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "Function parameters cannot be parenthesized") @}
    | (slash_no_default | slash_with_default)? param_maybe_default* '*' (',' | param_no_default) param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ must be ahead of *") @}
    | param_maybe_default+ '/' a='*' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expected comma between / and *") @}
invalid_default:
    | a='=' &(')'|',') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expected default value expression") @}
invalid_star_etc:
    | a='*' (')' | ',' (')' | '**')) @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "named arguments must follow bare *") @}
    | '*' ',' TYPE_COMMENT @{ RAISE_SYNTAX_ERROR("bare * has associated type comment") @}
    | '*' param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-positional argument cannot have default value") @}
    | '*' (param_no_default | ',') param_maybe_default* a='*' (param_no_default | ',') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "* argument may appear only once") @}
invalid_kwds:
    | '**' param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-keyword argument cannot have default value") @}
    | '**' param ',' a=param @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
    | '**' param ',' a[Token*]=('*'|'**'|'/') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
invalid_parameters_helper: # This is only there to avoid type errors
    | a=slash_with_default @{ _PyPegen_singleton_seq(p, a) @}
    | param_with_default+
invalid_lambda_parameters:
    | a="/" ',' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "at least one argument must precede /") @}
    | (lambda_slash_no_default | lambda_slash_with_default) lambda_param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ may appear only once") @}
    | lambda_slash_no_default? lambda_param_no_default* invalid_lambda_parameters_helper a=lambda_param_no_default @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "parameter without a default follows parameter with a default") @}
    | lambda_param_no_default* a='(' ','.lambda_param+ ','? b=')' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "Lambda expression parameters cannot be parenthesized") @}
    | (lambda_slash_no_default | lambda_slash_with_default)? lambda_param_maybe_default* '*' (',' | lambda_param_no_default) lambda_param_maybe_default* a='/' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "/ must be ahead of *") @}
    | lambda_param_maybe_default+ '/' a='*' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expected comma between / and *") @}
invalid_lambda_parameters_helper:
    | a=lambda_slash_with_default @{ _PyPegen_singleton_seq(p, a) @}
    | lambda_param_with_default+
invalid_lambda_star_etc:
    | '*' (':' | ',' (':' | '**')) @{ RAISE_SYNTAX_ERROR("named arguments must follow bare *") @}
    | '*' lambda_param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-positional argument cannot have default value") @}
    | '*' (lambda_param_no_default | ',') lambda_param_maybe_default* a='*' (lambda_param_no_default | ',') @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "* argument may appear only once") @}
invalid_lambda_kwds:
    | '**' lambda_param a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "var-keyword argument cannot have default value") @}
    | '**' lambda_param ',' a=lambda_param @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
    | '**' lambda_param ',' a[Token*]=('*'|'**'|'/') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "arguments cannot follow var-keyword argument") @}
invalid_double_type_comments:
    | TYPE_COMMENT NEWLINE TYPE_COMMENT NEWLINE INDENT @{
        RAISE_SYNTAX_ERROR("Cannot have two type comments on def") @}
invalid_with_item:
    | expression 'as' a=expression &(',' | ')' | ':') @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(STAR_TARGETS, a) @}

invalid_for_target:
    | 'async'? 'for' a=star_expressions @{
        RAISE_SYNTAX_ERROR_INVALID_TARGET(FOR_TARGETS, a) @}

invalid_group:
    | '(' a=starred_expression ')' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot use starred expression here") @}
    | '(' a='**' expression ')' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot use double starred expression here") @}
invalid_import:
    | a='import' ','.dotted_name+ 'from' dotted_name @{
        RAISE_SYNTAX_ERROR_STARTING_FROM(a, "Did you mean to use 'from ... import ...' instead?") @}
    | 'import' token=NEWLINE @{ 
        RAISE_SYNTAX_ERROR_STARTING_FROM(token, "Expected one or more names after 'import'") @}

invalid_import_from_targets:
    | import_from_as_names ',' NEWLINE @{
        RAISE_SYNTAX_ERROR("trailing comma not allowed without surrounding parentheses") @}
    | token=NEWLINE @{ 
        RAISE_SYNTAX_ERROR_STARTING_FROM(token, "Expected one or more names after 'import'") @}

invalid_with_stmt:
    | ['async'] 'with' ','.(expression ['as' star_target])+ NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | ['async'] 'with' '(' ','.(expressions ['as' star_target])+ ','? ')' NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
invalid_with_stmt_indent:
    | ['async'] a='with' ','.(expression ['as' star_target])+ ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'with' statement on line %d", a->lineno) @}
    | ['async'] a='with' '(' ','.(expressions ['as' star_target])+ ','? ')' ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'with' statement on line %d", a->lineno) @}

invalid_try_stmt:
    | a='try' ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'try' statement on line %d", a->lineno) @}
    | 'try' ':' block !('except' | 'finally') @{ RAISE_SYNTAX_ERROR("expected 'except' or 'finally' block") @}
    | 'try' ':' block* except_block+ a='except' b='*' expression ['as' NAME] ':' @{
        RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot have both 'except' and 'except*' on the same 'try'") @}
    | 'try' ':' block* except_star_block+ a='except' [expression ['as' NAME]] ':' @{
        RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot have both 'except' and 'except*' on the same 'try'") @}
invalid_except_stmt:
    | 'except' '*'? a=expression ',' expressions ['as' NAME ] ':' @{
        RAISE_SYNTAX_ERROR_STARTING_FROM(a, "multiple exception types must be parenthesized") @}
    | a='except' '*'? expression ['as' NAME ] NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='except' NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='except' '*' (NEWLINE | ':') @{ RAISE_SYNTAX_ERROR("expected one or more exception types") @}
invalid_finally_stmt:
    | a='finally' ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'finally' statement on line %d", a->lineno) @}
invalid_except_stmt_indent:
    | a='except' expression ['as' NAME ] ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'except' statement on line %d", a->lineno) @}
    | a='except' ':' NEWLINE !INDENT @{ RAISE_INDENTATION_ERROR("expected an indented block after 'except' statement on line %d", a->lineno) @}
invalid_except_star_stmt_indent:
    | a='except' '*' expression ['as' NAME ] ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'except*' statement on line %d", a->lineno) @}
invalid_match_stmt:
    | "match" subject_expr NEWLINE @{ CHECK_VERSION(void*, 10, "Pattern matching is", RAISE_SYNTAX_ERROR("expected ':'") ) @}
    | a="match" subject=subject_expr ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'match' statement on line %d", a->lineno) @}
invalid_case_block:
    | "case" patterns guard? NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a="case" patterns guard? ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'case' statement on line %d", a->lineno) @}
invalid_as_pattern:
    | or_pattern 'as' a="_" @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "cannot use '_' as a target") @}
    | or_pattern 'as' !NAME a=expression @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "invalid pattern target") @}
invalid_class_pattern:
    | name_or_attr '(' a=invalid_class_argument_pattern  @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(
        PyPegen_first_item(a, pattern_ty),
        PyPegen_last_item(a, pattern_ty),
        "positional patterns follow keyword patterns") @}
invalid_class_argument_pattern[asdl_pattern_seq*]:
    | [positional_patterns ','] keyword_patterns ',' a=positional_patterns @{ a @}
invalid_if_stmt:
    | 'if' named_expression NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='if' a=named_expression ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'if' statement on line %d", a->lineno) @}
invalid_elif_stmt:
    | 'elif' named_expression NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='elif' named_expression ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'elif' statement on line %d", a->lineno) @}
invalid_else_stmt:
    | a='else' ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'else' statement on line %d", a->lineno) @}
invalid_while_stmt:
    | 'while' named_expression NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='while' named_expression ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'while' statement on line %d", a->lineno) @}
invalid_for_stmt:
    | ['async'] 'for' star_targets 'in' star_expressions NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | ['async'] a='for' star_targets 'in' star_expressions ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after 'for' statement on line %d", a->lineno) @}
invalid_def_raw:
    | ['async'] a='def' NAME [type_params] '(' [params] ')' ['->' expression] ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after function definition on line %d", a->lineno) @}
    | ['async'] 'def' NAME [type_params] &&'(' [params] ')' ['->' expression] &&':' [func_type_comment] block
invalid_class_def_raw:
    | 'class' NAME [type_params] ['(' [arguments] ')'] NEWLINE @{ RAISE_SYNTAX_ERROR("expected ':'") @}
    | a='class' NAME [type_params] ['(' [arguments] ')'] ':' NEWLINE !INDENT @{
        RAISE_INDENTATION_ERROR("expected an indented block after class definition on line %d", a->lineno) @}

invalid_double_starred_kvpairs:
    | ','.double_starred_kvpair+ ',' invalid_kvpair
    | expression ':' a='*' bitwise_or @{ RAISE_SYNTAX_ERROR_STARTING_FROM(a, "cannot use a starred expression in a dictionary value") @}
    | expression a=':' &('@}'|',') @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expression expected after dictionary key and ':'") @}
invalid_kvpair:
    | a=expression !(':') @{
        RAISE_ERROR_KNOWN_LOCATION(p, PyExc_SyntaxError, a->lineno, a->end_col_offset - 1, a->end_lineno, -1, "':' expected after dictionary key") @}
    | expression ':' a='*' bitwise_or @{ RAISE_SYNTAX_ERROR_STARTING_FROM(a, "cannot use a starred expression in a dictionary value") @}
    | expression a=':' &('@}'|',') @{RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "expression expected after dictionary key and ':'") @}
invalid_starred_expression:
    | a='*' expression '=' b=expression @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "cannot assign to iterable argument unpacking") @}

invalid_replacement_field:
    | '@{' a='=' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "f-string: valid expression required before '='") @}
    | '@{' a='!' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "f-string: valid expression required before '!'") @}
    | '@{' a=':' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "f-string: valid expression required before ':'") @}
    | '@{' a='@}' @{ RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "f-string: valid expression required before '@}'") @}
    | '@{' !annotated_rhs @{ RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: expecting a valid expression after '@{'")@}
    | '@{' annotated_rhs !('=' | '!' | ':' | '@}') @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: expecting '=', or '!', or ':', or '@}'") @}
    | '@{' annotated_rhs '=' !('!' | ':' | '@}') @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: expecting '!', or ':', or '@}'") @}
    | '@{' annotated_rhs '='? invalid_conversion_character
    | '@{' annotated_rhs '='? ['!' NAME] !(':' | '@}') @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: expecting ':' or '@}'") @}
    | '@{' annotated_rhs '='? ['!' NAME] ':' fstring_format_spec* !'@}' @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: expecting '@}', or format specs") @}
    | '@{' annotated_rhs '='? ['!' NAME] !'@}' @{
        PyErr_Occurred() ? NULL : RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: expecting '@}'") @}

invalid_conversion_character:
    | '!' &(':' | '@}') @{ RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: missing conversion character") @}
    | '!' !NAME @{ RAISE_SYNTAX_ERROR_ON_NEXT_TOKEN("f-string: invalid conversion character") @}

invalid_arithmetic:
    | sum ('+'|'-'|'*'|'/'|'%'|'//'|'@@') a='not' b=inversion @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "'not' after an operator must be parenthesized") @}
invalid_factor:
    | ('+' | '-' | '~') a='not' b=factor @{ RAISE_SYNTAX_ERROR_KNOWN_RANGE(a, b, "'not' after an operator must be parenthesized") @}

invalid_type_params:
    | '[' token=']' @{
        RAISE_SYNTAX_ERROR_STARTING_FROM(
            token, 
            "Type parameter list cannot be empty")@}
@end example

@node La bibliothèque standard,Extension et intégration de l'interpréteur Python,La référence du langage Python,Top
@anchor{library/index doc}@anchor{20cf}@anchor{library/index library-index}@anchor{143}@anchor{library/index the-python-standard-library}@anchor{20d0}
@chapter La bibliothèque standard


Alors que @ref{144,,La référence du langage Python} décrit exactement la syntaxe et la sémantique du langage Python, ce manuel de référence de la Bibliothèque décrit la bibliothèque standard distribuée avec Python. Il décrit aussi certains composants optionnels typiquement inclus dans les distributions de Python.

La bibliothèque standard de Python est très grande, elle offre un large éventail d'outils comme le montre la longueur de la table des matières ci-dessous. La bibliothèque contient des modules natifs (écrits en C) exposant les fonctionnalités du système telles que les interactions avec les fichiers qui autrement ne seraient pas accessibles aux développeurs Python, ainsi que des modules écrits en Python exposant des solutions standardisées à de nombreux problèmes du quotidien du développeur. Certains de ces modules sont définis explicitement pour encourager et améliorer la portabilité des programmes Python en abstrayant des spécificités sous-jacentes en API neutres.

Les installateurs de Python pour Windows incluent généralement la bibliothèque standard en entier, et y ajoutent souvent d'autres composants. Pour les systèmes d'exploitation Unix, Python est typiquement fourni sous forme d'une collection de paquets, il peut donc être nécessaire d'utiliser le gestionnaire de paquets fourni par le système d'exploitation pour obtenir certains composants optionnels.

Au delà de la bibliothèque standard, il existe une collection grandissante de plusieurs centaine de milliers de composants (des programmes, des modules, ou des `frameworks'), disponibles dans le Python Package Index@footnote{https://pypi.org}.

@c We don't use :numbered: option for the TOC below as it enforces
@c numbered sections for the entire stdlib docs.  If desired,
@c :numbered: can be enabled on a per-module basis.

@menu
* Introduction: Introduction<6>. 
* Fonctions natives: Fonctions natives<2>. 
* Constantes natives:: 
* Types natifs:: 
* Exceptions natives:: 
* Services de Manipulation de Texte:: 
* Services autour des Données Binaires:: 
* Types de données:: 
* Modules numériques et mathématiques:: 
* Modules de programmation fonctionnelle:: 
* Accès aux Fichiers et aux Dossiers:: 
* Persistance des données:: 
* Compression de donnée et archivage:: 
* Formats de fichiers:: 
* Service de cryptographie:: 
* Services génériques du système d'exploitation:: 
* Command Line Interface Libraries:: 
* Exécution concourante:: 
* Réseau et communication entre processus:: 
* Traitement des données provenant d'Internet:: 
* Outils de traitement de balises structurées:: 
* Gestion des protocoles internet:: 
* Services multimédia:: 
* Internationalisation:: 
* Cadriciels d'applications:: 
* Interfaces Utilisateur Graphiques avec Tk:: 
* Outils de développement:: 
* Débogueur et instrumentation:: 
* Paquets et distribution de paquets logiciels:: 
* Environnement d'exécution Python:: 
* Interpréteurs Python personnalisés:: 
* Importer des modules:: 
* Services du Langage Python:: 
* Services spécifiques à MS Windows:: 
* Services spécifiques à Unix:: 
* Modules command-line interface (CLI): Modules command-line interface CLI. 
* Modules remplacés:: 
* Removed Modules:: 
* Considérations de sécurité: Considérations de sécurité<4>. 

@end menu

@node Introduction<6>,Fonctions natives<2>,,La bibliothèque standard
@anchor{library/intro doc}@anchor{20d1}@anchor{library/intro introduction}@anchor{20d2}@anchor{library/intro library-intro}@anchor{20d3}
@section Introduction


La « Bibliothèque Python » contient divers composants dans différentes catégories.

Elle contient des types de données qui seraient normalement considérés comme « fondamentaux » au langage, tel que les nombres et les listes. Pour ces types, le cœur du langage en définit les écritures littérales et impose quelques contraintes sémantiques, sans les définir exhaustivement. (Cependant le cœur du langage impose quelques propriétés comme l'orthographe des attributs ou les caractéristiques des opérateurs.)

La bibliothèque contient aussi des fonctions et des exceptions natives, pouvant être utilisées par tout code Python sans @ref{5cc,,import}. Certaines sont définies par le noyau de Python, bien qu'elles ne soient pas toutes essentielles.

La grande majorité de la bibliothèque consiste cependant en une collection de modules. Cette collection peut être parcourue de différentes manières. Certains modules sont rédigés en C et inclus dans l'interpréteur Python, d'autres sont écrits en Python et leur source est importée. Certains modules fournissent des interfaces extrêmement spécifiques à Python, tel que l'affichage d'une pile d'appels, d'autres fournissent des interfaces spécifiques à un système d'exploitation, comme l'accès à du matériel spécifique. D'autres fournissent des interfaces spécifiques à un domaine d'application, comme le `World Wide Web'. Certains modules sont disponibles dans toutes les versions et implémentations de Python, d'autres ne sont disponibles que si le système sous-jacent les gère ou en a besoin. Enfin, d'autres ne sont disponibles que si Python à été compilé avec une certaine option.

Cette documentation organise les modules « de l'intérieur vers l'extérieur », documentant en premier les fonctions natives, les types de données et exceptions, puis les modules, groupés par chapitre, par thématiques.

Ça signifie que si vous commencez à lire cette documentation du début, et sautez au chapitre suivant lorsqu'elle vous ennuie, vous aurez un aperçu global des modules et domaines couverts par cette bibliothèque. Bien sûr vous n'avez pas à la lire comme un roman, vous pouvez simplement survoler la table des matières (au début), ou chercher une fonction, un module, ou un mot dans l'index (à la fin). Et si vous appréciez apprendre sur des sujets au hasard, choisissez une page au hasard (avec le module @ref{b7,,random}) et lisez un chapitre ou deux. Peu importe l'ordre que vous adopterez, commencez par le chapitre @ref{123b,,Fonctions natives}, car les autres chapitres présument que vous en avez une bonne connaissance.

Que le spectacle commence !

@menu
* Notes sur la disponibilité:: 

@end menu

@node Notes sur la disponibilité,,,Introduction<6>
@anchor{library/intro availability}@anchor{1ce0}@anchor{library/intro notes-on-availability}@anchor{20d4}
@subsection Notes sur la disponibilité



@itemize *

@item 
Une note « Disponibilité : Unix » signifie que cette fonction est communément implémentée dans les systèmes Unix. Une telle note ne prétend pas l'existence de la fonction sur un système d'exploitation particulier.

@item 
If not separately noted, all functions that claim "Availability: Unix" are
supported on macOS, iOS and Android, all of which build on a Unix core.

@item 
Si une note de disponibilité contient à la fois une version minimale du noyau et une version minimale de la `libc', les deux conditions doivent être remplies. Par exemple, une fonctionnalité avec la note `Disponibilité : Linux >= 3.17 avec glibc >= 2.27' nécessite à la fois Linux 3.17 ou plus récent et glibc 2.27 ou plus récent.
@end itemize

@menu
* Plateformes WebAssembly:: 
* Mobile platforms:: 

@end menu

@node Plateformes WebAssembly,Mobile platforms,,Notes sur la disponibilité
@anchor{library/intro wasm-availability}@anchor{176f}@anchor{library/intro webassembly-platforms}@anchor{20d5}
@subsubsection Plateformes WebAssembly


Les plates-formes WebAssembly@footnote{https://webassembly.org/} @code{wasm32-emscripten} (Emscripten@footnote{https://emscripten.org/}) et @code{wasm32-wasi} (WASI@footnote{https://wasi.dev/}) fournissent un sous-ensemble des API POSIX. Les environnements d'exécution WebAssembly et les navigateurs sont dans des bacs à sable et ont un accès limité à l'hôte et aux ressources externes. Tout module de bibliothèque standard Python qui utilise des processus, des threads, le réseau, des signaux ou d'autres formes de communication inter-processus (IPC) n'est pas disponible ou peut ne pas fonctionner comme sur d'autres systèmes de type Unix. Les entrées-sorties de fichiers, le système de fichiers et les fonctions liées aux autorisations Unix sont également restreintes. `Emscripten' ne permet pas d'effectuer des entrées-sorties bloquantes. D'autres opérations bloquantes comme @ref{688,,sleep()} bloquent la boucle d'événements du navigateur.

Les propriétés et le comportement de Python sur les plates-formes WebAssembly dépendent de la version du SDK Emscripten@footnote{https://emscripten.org/} ou WASI@footnote{https://wasi.dev/}, des programmes exécutables WASM (navigateur, NodeJS, wasmtime@footnote{https://wasmtime.dev/}) et de la configuration de compilation de Python. WebAssembly, Emscripten et WASI sont des normes en évolution ; certaines fonctionnalités telles que la gestion du réseau pourraient être prises en charge à l'avenir.

Pour exécuter du Python dans le navigateur, les utilisateurs doivent envisager Pyodide@footnote{https://pyodide.org/} ou PyScript@footnote{https://pyscript.net/}. `PyScript' est construit sur `Pyodide', qui est lui-même construit sur CPython et `Emscripten'. `Pyodide' donne accès aux API JavaScript et DOM des navigateurs ainsi qu'à des capacités réseau limitées avec les API @code{XMLHttpRequest} et @code{Fetch} de JavaScript.


@itemize *

@item 
Les API liées aux processus ne sont pas disponibles ou échouent toujours avec une erreur. Cela inclut les API qui génèrent de nouveaux processus (@ref{195,,fork()}, @ref{10d9,,execve()}), attendent des processus (@ref{d87,,waitpid()}), envoient des signaux (@ref{133e,,kill()}), ou interagissent d'une autre manière avec les processus. Le module @ref{d5,,subprocess} peut être importé mais ne fonctionne pas.

@item 
Le module @ref{cb,,socket} est disponible, mais est limité et n'a pas le même comportement que sur les autres plates-formes. Sur `Emscripten', les connecteurs réseau sont toujours non bloquants et nécessitent du code JavaScript et du code supplémentaire sur le serveur pour faire mandataire TCP via `WebSockets' ; voir Emscripten Networking@footnote{https://emscripten.org/docs/porting/networking.html} pour plus d'informations. La pré-version 1 de `WASI' n'autorise que les connecteurs réseau utilisant un descripteur de fichier déjà existant.

@item 
Certaines fonctions sont des émulations embryonnaires qui ne font rien et renvoient toujours des valeurs codées en dur.

@item 
Les fonctions liées aux descripteurs de fichiers, aux autorisations de fichiers, aux propriétaires des fichiers et aux liens sont limitées et ne prennent pas en charge certaines opérations. Par exemple, WASI n'autorise pas les liens symboliques avec des noms de fichiers absolus.
@end itemize
@anchor{library/intro mobile-availability}@anchor{1ddf}
@node Mobile platforms,,Plateformes WebAssembly,Notes sur la disponibilité
@anchor{library/intro ios-availability}@anchor{20d6}@anchor{library/intro mobile-platforms}@anchor{20d7}
@subsubsection Mobile platforms


Android and iOS are, in most respects, POSIX operating systems. File I/O, socket handling,
and threading all behave as they would on any POSIX operating system. However,
there are several major differences:


@itemize *

@item 
Mobile platforms can only use Python in "embedded" mode. There is no Python
REPL, and no ability to use separate executables such as @code{python} or
@code{pip}. To add Python code to your mobile app, you must use
the @ref{1dde,,Python embedding API}. For more details, see
@ref{1ddc,,Using Python on Android} and @ref{1de2,,Using Python on iOS}.

@item 
Subprocesses:


@itemize *

@item 
On Android, creating subprocesses is possible but officially unsupported@footnote{https://issuetracker.google.com/issues/128554619#comment4}.
In particular, Android does not support any part of the System V IPC API,
so @ref{93,,multiprocessing} is not available.

@item 
An iOS app cannot use any form of subprocessing, multiprocessing, or
inter-process communication. If an iOS app attempts to create a subprocess,
the process creating the subprocess will either lock up, or crash. An iOS app
has no visibility of other applications that are running, nor any ability to
communicate with other running applications, outside of the iOS-specific APIs
that exist for this purpose.
@end itemize

@item 
Mobile apps have limited access to modify system resources (such as the system
clock). These resources will often be `readable', but attempts to modify
those resources will usually fail.

@item 
Console input and output:


@itemize *

@item 
On Android, the native @code{stdout} and @code{stderr} are not connected to
anything, so Python installs its own streams which redirect messages to the
system log. These can be seen under the tags @code{python.stdout} and
@code{python.stderr} respectively.

@item 
iOS apps have a limited concept of console output. @code{stdout} and
@code{stderr} `exist', and content written to @code{stdout} and @code{stderr} will be
visible in logs when running in Xcode, but this content `won't' be recorded
in the system log. If a user who has installed your app provides their app
logs as a diagnostic aid, they will not include any detail written to
@code{stdout} or @code{stderr}.

@item 
Mobile apps have no usable @code{stdin} at all. While apps can display an on-screen
keyboard, this is a software feature, not something that is attached to
@code{stdin}.

As a result, Python modules that involve console manipulation (such as
@ref{2b,,curses} and @ref{b9,,readline}) are not available on mobile platforms.
@end itemize
@end itemize

@c XXX document all delegations to __special__ methods

@node Fonctions natives<2>,Constantes natives,Introduction<6>,La bibliothèque standard
@anchor{library/functions doc}@anchor{20d8}@anchor{library/functions built-in-funcs}@anchor{123b}@anchor{library/functions built-in-functions}@anchor{20d9}
@section Fonctions natives


L'interpréteur Python propose quelques fonctions et types natifs qui sont toujours disponibles. Ils sont listés ici par ordre alphabétique.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Fonctions natives

@tab

@tab

@tab

@item


@display
`A'@w{ }
@ref{1c32,,abs()}@w{ }
@ref{7bf,,aiter()}@w{ }
@ref{13d8,,all()}@w{ }
@ref{7c0,,anext()}@w{ }
@ref{13d7,,any()}@w{ }
@ref{139d,,ascii()}@w{ }
@w{ }
`B'@w{ }
@ref{1286,,bin()}@w{ }
@ref{451,,bool()}@w{ }
@ref{231,,breakpoint()}@w{ }
@ref{1a48,,bytearray()}@w{ }
@ref{1a47,,bytes()}@w{ }
@w{ }
`C'@w{ }
@ref{11a3,,callable()}@w{ }
@ref{15fb,,chr()}@w{ }
@ref{165,,classmethod()}@w{ }
@ref{190,,compile()}@w{ }
@ref{2ec,,complex()}@w{ }
@w{ }
`D'@w{ }
@ref{20da,,delattr()}@w{ }
@ref{20db,,dict()}@w{ }
@ref{61d,,dir()}@w{ }
@ref{98f,,divmod()}@w{ }
@w{ }
@end display



@tab


@display
`E'@w{ }
@ref{1433,,enumerate()}@w{ }
@ref{17e,,eval()}@w{ }
@ref{17d,,exec()}@w{ }
@w{ }
`F'@w{ }
@ref{84f,,filter()}@w{ }
@ref{2eb,,float()}@w{ }
@ref{60a,,format()}@w{ }
@ref{20dc,,frozenset()}@w{ }
@w{ }
`G'@w{ }
@ref{bbf,,getattr()}@w{ }
@ref{17f5,,globals()}@w{ }
@w{ }
`H'@w{ }
@ref{4bb,,hasattr()}@w{ }
@ref{5d5,,hash()}@w{ }
@ref{8c4,,help()}@w{ }
@ref{12ad,,hex()}@w{ }
@w{ }
`I'@w{ }
@ref{13d9,,id()}@w{ }
@ref{12b6,,input()}@w{ }
@ref{254,,int()}@w{ }
@ref{42b,,isinstance()}@w{ }
@ref{7ab,,issubclass()}@w{ }
@ref{7c1,,iter()}@w{ }
@end display



@tab


@display
`L'@w{ }
@ref{619,,len()}@w{ }
@ref{20dd,,list()}@w{ }
@ref{140,,locals()}@w{ }
@w{ }
`M'@w{ }
@ref{84e,,map()}@w{ }
@ref{ef4,,max()}@w{ }
@ref{20de,,memoryview()}@w{ }
@ref{ef3,,min()}@w{ }
@w{ }
`N'@w{ }
@ref{7c2,,next()}@w{ }
@w{ }
`O'@w{ }
@ref{a7a,,object()}@w{ }
@ref{12ac,,oct()}@w{ }
@ref{505,,open()}@w{ }
@ref{1e75,,ord()}@w{ }
@w{ }
`P'@w{ }
@ref{9c0,,pow()}@w{ }
@ref{f60,,print()}@w{ }
@ref{192,,property()}@w{ }
@w{ }
@w{ }
@w{ }
@w{ }
@end display



@tab


@display
`R'@w{ }
@ref{20df,,range()}@w{ }
@ref{7e7,,repr()}@w{ }
@ref{850,,reversed()}@w{ }
@ref{12b8,,round()}@w{ }
@w{ }
`S'@w{ }
@ref{20e0,,set()}@w{ }
@ref{20e1,,setattr()}@w{ }
@ref{453,,slice()}@w{ }
@ref{bbc,,sorted()}@w{ }
@ref{40c,,staticmethod()}@w{ }
@ref{20e2,,str()}@w{ }
@ref{454,,sum()}@w{ }
@ref{4c5,,super()}@w{ }
@w{ }
`T'@w{ }
@ref{20e3,,tuple()}@w{ }
@ref{d36,,type()}@w{ }
@w{ }
`V'@w{ }
@ref{19d0,,vars()}@w{ }
@w{ }
`Z'@w{ }
@ref{7ba,,zip()}@w{ }
@w{ }
`_'@w{ }
@ref{8c1,,__import__()}@w{ }
@end display



@end multitable


@c using :func:`dict` would create a link to another page, so local targets are
@c used, with replacement texts to make the output in the table consistent

@geindex built-in function; abs()
@anchor{library/functions abs}@anchor{1c32}
@deffn {Fonction} abs (x)

Renvoie la valeur absolue d'un nombre. L'argument peut être un nombre entier, un nombre à virgule flottante, ou tout objet définissant @ref{1f3a,,__abs__()}. Si l'argument est un nombre complexe, son module est renvoyé.
@end deffn

@geindex built-in function; aiter()
@anchor{library/functions aiter}@anchor{7bf}
@deffn {Fonction} aiter (async_iterable)

Renvoie un @ref{1a9,,itérateur asynchrone} pour l'@ref{d65,,itérable asynchrone} donné. Équivaut à appeler @code{x.__aiter__()}.

Remarque : contrairement à @ref{7c1,,iter()}, @ref{7bf,,aiter()} n'a pas de variante à 2 arguments.


Ajouté dans la version 3.10.

@end deffn

@geindex built-in function; all()
@anchor{library/functions all}@anchor{13d8}
@deffn {Fonction} all (iterable)

Renvoie @code{True} si tous les éléments de `iterable' sont vrais (ou s'il est vide). Équivaut à :

@example
def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True
@end example
@end deffn

@geindex built-in function; anext()
@anchor{library/functions anext}@anchor{7c0}
@deffn {Fonction} awaitable anext (async_iterator)

@deffnx {Fonction} awaitable anext (async_iterator, default)

Lorsqu'il est attendu, renvoie l'élément suivant à partir de l'@ref{1a9,,itérateur asynchrone} donné, ou `default' s'il est fourni et que l'itérateur est épuisé.

Il s'agit de la variante asynchrone de la fonction native @ref{7c2,,next()} et elle se comporte de la même manière.

Renvoie un @ref{1ab,,attendable} en appelant la méthode @ref{1e8f,,__anext__()} de `async_iterator'. L'attente renvoie la prochaine valeur de l'itérateur. Si `default' est fourni, il est renvoyé si l'itérateur est épuisé, sinon @ref{19bb,,StopAsyncIteration} est levée.


Ajouté dans la version 3.10.

@end deffn

@geindex built-in function; any()
@anchor{library/functions any}@anchor{13d7}
@deffn {Fonction} any (iterable)

Renvoie @code{True} si au moins un élément de `iterable' est vrai. @code{False} est renvoyé dans le cas où `iterable' est vide. Équivaut à :

@example
def any(iterable):
    for element in iterable:
        if element:
            return True
    return False
@end example
@end deffn

@geindex built-in function; ascii()
@anchor{library/functions ascii}@anchor{139d}
@deffn {Fonction} ascii (object)

Renvoie, tout comme @ref{7e7,,repr()}, une chaîne contenant une représentation d'un objet destinée à l'affichage, mais en transformant les caractères non ASCII renvoyés par @ref{7e7,,repr()} par l'utilisation de séquences d'échappement @code{\x}, @code{\u} ou @code{\U}. Cela génère une chaîne similaire à ce que renvoie @ref{7e7,,repr()} dans Python 2.
@end deffn

@geindex built-in function; bin()
@anchor{library/functions bin}@anchor{1286}
@deffn {Fonction} bin (x)

Convertit un nombre entier en binaire dans une chaîne avec le préfixe "0b". Le résultat est une expression Python valide. Si `x' n'est pas un @ref{254,,int}, il doit définir une méthode @code{__index__()} donnant un nombre entier. Voici quelques exemples :

@example
>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'
@end example

Vous pouvez contrôler l'affichage du préfixe @code{"0b"} à l'aide d'un des moyens suivants.

@example
>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'@{14:#b@}', f'@{14:b@}'
('0b1110', '1110')
@end example

Voir aussi @ref{60a,,format()} pour plus d'informations.
@end deffn

@geindex bool (classe de base)
@anchor{library/functions bool}@anchor{451}
@deffn {Classe} bool (object=False, /)

Renvoie une valeur booléenne, c'est-à-dire soit @code{True}, soit @code{False}. L'argument est converti en utilisant la @ref{20e4,,procédure standard d'évaluation de valeur de vérité}. Si l'argument est faux, ou omis, elle renvoie @code{False}, sinon, elle renvoie @code{True}. La classe @ref{451,,bool} hérite de la classe @ref{254,,int} (voir @ref{1b86,,Types numériques — int@comma{} float@comma{} complex}). Il n'est pas possible d'en hériter. Ses seules instances sont @code{False} et @code{True} (voir @ref{20e5,,Boolean Type - bool}).

@geindex Boolean;type


Modifié dans la version 3.7: Le paramètre est désormais un argument exclusivement positionnel.

@end deffn

@geindex built-in function; breakpoint()
@anchor{library/functions breakpoint}@anchor{231}
@deffn {Fonction} breakpoint (*args, **kws)

Cette fonction vous place dans le débogueur lorsqu'elle est appelée. Plus précisément, elle appelle @ref{ac8,,sys.breakpointhook()}, en lui passant les arguments @code{args} et @code{kws}. Par défaut, @code{sys.breakpointhook()} appelle @ref{232,,pdb.set_trace()} qui n'attend aucun argument. Dans ce cas, c'est purement une fonction de commodité donc vous n'avez pas à importer explicitement @ref{a4,,pdb} ou à taper plus de code pour entrer dans le débogueur. Cependant, il est possible d'affecter une autre fonction à @ref{ac8,,sys.breakpointhook()}, que @ref{231,,breakpoint()} appellera automatiquement, vous permettant ainsi de basculer dans le débogueur de votre choix. Si @ref{ac8,,sys.breakpointhook()} n'est pas accessible, cette fonction lève @ref{193,,RuntimeError}.

Par défaut, le comportement de la fonction @ref{231,,breakpoint()} peut être changé par la variable d'environnement 
@geindex PYTHONBREAKPOINT
@geindex variable d'environnement; PYTHONBREAKPOINT
@ref{ac9,,PYTHONBREAKPOINT}. Voir @ref{ac8,,sys.breakpointhook()} pour plus de détails.

Notez que ceci n'est plus garanti si la fonction @ref{ac8,,sys.breakpointhook()} a été remplacée.

Lève un @ref{1848,,évènement d'audit} @code{builtins.breakpoint} avec l'argument @code{breakpointhook}.


Ajouté dans la version 3.7.

@end deffn

@anchor{library/functions func-bytearray}@anchor{1a48}
@deffn {Classe} bytearray (source=b'@w{'})

@deffnx {Classe} bytearray (source, encoding)

@deffnx {Classe} bytearray (source, encoding, errors)

Renvoie un nouveau tableau d'octets. La classe @ref{528,,bytearray} est une séquence mutable de nombres entiers dans l'intervalle 0 ≤ x < 256. Il possède la plupart des méthodes des séquences variables, décrites dans @ref{20e6,,Types de séquences mutables}, ainsi que la plupart des méthodes de la classe @ref{1bd,,bytes}, voir @ref{20e7,,Opérations sur les bytes et bytearray}.

Le paramètre optionnel `source' peut être utilisé pour initialiser le tableau de plusieurs façons :


@itemize *

@item 
si c'est une `chaîne', vous devez aussi donner le paramètre `encoding' pour l'encodage (et éventuellement `errors'). La fonction @ref{528,,bytearray()} convertit ensuite la chaîne en octets `via' la méthode @ref{8c2,,str.encode()} ;

@item 
si c'est un `entier', le tableau a cette taille et est initialisé d'octets `null' ;

@item 
si c'est un objet conforme à @ref{38e,,l'interface tampon}, un tampon en lecture seule de l'objet est utilisé pour initialiser le tableau ;

@item 
si c'est un `itérable', il doit itérer sur des nombres entier dans l'intervalle @code{0 <= x < 256}, qui sont utilisés pour initialiser le contenu du tableau.
@end itemize

Sans argument, un tableau vide est créé.

Voir @ref{20e8,,Séquences Binaires — bytes@comma{} bytearray@comma{} vue mémoire} et @ref{20e9,,Objets bytearray}.
@end deffn

@anchor{library/functions func-bytes}@anchor{1a47}
@deffn {Classe} bytes (source=b'@w{'})

@deffnx {Classe} bytes (source, encoding)

@deffnx {Classe} bytes (source, encoding, errors)

Renvoie un nouvel objet `bytes', qui est une séquence immuable de nombres entiers dans l'intervalle @code{0 <= x < 256}. Un @ref{1bd,,bytes} est une version immuable de @ref{528,,bytearray} — avec les mêmes méthodes d'accès, et le même comportement lors de l'indexation ou du découpage.

En conséquence, les arguments du constructeur sont les mêmes que pour @ref{528,,bytearray()}.

Les objets `bytes' peuvent aussi être créés à partir de littéraux, voir @ref{1e2a,,Littéraux de chaînes de caractères et de suites d'octets}.

Voir aussi @ref{20e8,,Séquences Binaires — bytes@comma{} bytearray@comma{} vue mémoire}, @ref{20ea,,Objets bytes}, et @ref{20e7,,Opérations sur les bytes et bytearray}.
@end deffn

@geindex built-in function; callable()
@anchor{library/functions callable}@anchor{11a3}
@deffn {Fonction} callable (object)

Renvoie @ref{bfb,,True} si l'argument `object' semble être appelable, sinon @ref{b25,,False}. Lorsqu'elle renvoie @code{True}, il est toujours possible qu'un appel échoue. Cependant, lorsqu'elle renvoie @code{False}, il n'est jamais possible d'appeler `object'. Notez qu'une classe est toujours appelable (appeler une classe donne une nouvelle instance) ; une instance n'est appelable que si sa classe définit une méthode @ref{543,,__call__()}.


Ajouté dans la version 3.2: cette fonction a d'abord été supprimée avec Python 3.0 puis elle a été remise dans Python 3.2.

@end deffn

@geindex built-in function; chr()
@anchor{library/functions chr}@anchor{15fb}
@deffn {Fonction} chr (i)

Renvoie la chaîne représentant un caractère dont le code de caractère Unicode est le nombre entier `i'. Par exemple, @code{chr(97)} renvoie la chaîne de caractères @code{'a'}, tandis que @code{chr(8364)} renvoie @code{'€'}. Il s'agit de la réciproque de @ref{1e75,,ord()}.

L'intervalle valide pour cet argument est de @code{0} à @code{1114111} (@code{0x10FFFF} en base 16). Une exception @ref{1ff,,ValueError} est levée si `i' est en dehors de l'intervalle.
@end deffn

@geindex built-in function; classmethod()
@anchor{library/functions classmethod}@anchor{165}
@deffn {Fonction} @@classmethod

Transforme une méthode en méthode de classe.

Une méthode de classe reçoit implicitement la classe en premier argument, tout comme une méthode d'instance reçoit l'instance. Voici comment déclarer une méthode de classe :

@example
class C:
    @@classmethod
    def f(cls, arg1, arg2): ...
@end example

La forme @code{@@classmethod} est un @ref{71b,,décorateur} de fonction — consultez @ref{1bc4,,Définition de fonctions} pour plus de détails.

Elle peut être appelée soit sur la classe (comme @code{C.f()}) ou sur une instance (comme @code{C().f()}). L'instance est ignorée, sauf pour déterminer sa classe. Si la méthode est appelée sur une instance de classe fille, c'est la classe fille qui sera donnée en premier argument implicite.

Les méthodes de classe sont différentes des méthodes statiques du C++ ou du Java. Si ce sont elles dont vous avez besoin, regardez du côté de @ref{40c,,staticmethod()} dans cette section. Voir aussi @ref{1e6a,,Hiérarchie des types standards}.


Modifié dans la version 3.9: les méthodes de classe peuvent encapsuler d'autres @ref{1ef3,,descripteurs} comme @ref{192,,property()}.



Modifié dans la version 3.10: les méthodes de classe héritent dorénavant des attributs des méthodes (@ref{1e81,,__module__}, @ref{12b2,,__name__}, @ref{1e80,,__qualname__}, @ref{11b6,,__doc__} et @ref{11b5,,__annotations__}) et ont un nouvel attribut @code{__wrapped__}.



Deprecated since version 3.11, removed in version 3.13: les méthodes de classe ne peuvent plus encapsuler d'autres @ref{1ef3,,descripteurs} comme @ref{192,,property()}.

@end deffn

@geindex built-in function; compile()
@anchor{library/functions compile}@anchor{190}
@deffn {Fonction} compile (source, filename, mode, flags=0, dont_inherit=False, optimize=-1)

Compile `source' en un objet code ou objet AST. Les objets code peuvent être exécutés par @ref{17d,,exec()} ou @ref{17e,,eval()}. `source' peut être une chaîne, une chaîne d'octets, ou un objet AST. Consultez la documentation du module @ref{8,,ast} pour des informations sur la manipulation d'objets AST.

L'argument `filename' doit désigner le fichier depuis lequel le code a été lu. Donnez quelque chose de reconnaissable lorsqu'il n'a pas été lu depuis un fichier (typiquement @code{"<string>"}).

L'argument `mode' indique quel type de code doit être compilé : @code{'exec'} si `source' est une suite d'instructions, @code{'eval'} pour une seule expression, ou @code{'single'} s'il ne contient qu'une instruction interactive (dans ce dernier cas, les résultats d'expressions donnant autre chose que @code{None} sont affichés).

Les arguments optionnels `flags' et `dont_inherit' contrôlent quelles @ref{20eb,,options de compilation} seront activées et quelles @ref{187,,instructions future} seront autorisées. Si aucun des deux n'est présent (ou que les deux sont à 0), le code est compilé avec les mêmes paramètres que le code appelant @ref{190,,compile()}. Si l'argument `flags' est fourni alors que `dont_inherit' ne l'est pas (ou vaut 0), les options de compilation et les instructions `futures' utilisées sont celles définies par `flags' en plus de celles qui auraient été utilisées. Si `dont_inherit' est un entier différent de zéro, `flags' est utilisé tel quel — les `flags' (instructions futures et options de compilation) valables pour le code encadrant `compile' sont ignorés.

Les instructions `future' sont contrôlées par des bits, il est ainsi possible d'en activer plusieurs en les combinant avec un `OU' binaire. Les bits requis pour demander une certaine fonctionnalité se trouvent dans l'attribut @ref{20ec,,compiler_flag} de la classe @code{Feature} du module @ref{0,,__future__}. Les @ref{20eb,,options du compilateur} se trouvent dans le module @ref{8,,ast}, avec le préfixe @code{PyCF_}.

L'argument `optimize' indique le niveau d'optimisation du compilateur. La valeur par défaut est @code{-1} qui prend le niveau d'optimisation de l'interpréteur tel que reçu via l'option @ref{da2,,-O}. Les niveaux explicites sont : @code{0} (pas d'optimisation, @code{__debug__} est @code{True}), @code{1} (les @code{assert} sont supprimés, @code{__debug__} est @code{False}) ou @code{2} (les chaines de documentation sont également supprimées).

Cette fonction lève une @ref{18b,,SyntaxError} si la source n'est pas valide, et @ref{1ff,,ValueError} si la source contient des octets `null'.

Si vous voulez transformer du code Python en sa représentation AST, voyez @ref{1a6,,ast.parse()}.

Lève un @ref{1848,,évènement d'audit} @code{compile} avec les arguments @code{source} et @code{filename}. Cet événement peut également être levé par une compilation implicite.

@cartouche
@quotation Note 
lors de la compilation d'une chaîne de plusieurs lignes de code avec les modes @code{'single'} ou @code{'eval'}, celles-ci doivent être terminées par au moins un retour à la ligne. Cela permet de faciliter la distinction entre les instructions complètes et incomplètes dans le module @ref{1a,,code}.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
il est possible de faire planter l'interpréteur Python avec des chaînes suffisamment grandes ou complexes lors de la compilation d'un objet AST. Ceci est dû à limitation de la profondeur de la pile d'appels.
@end quotation
@end cartouche


Modifié dans la version 3.2: autorise l'utilisation de retours à la ligne Mac et Windows. Par ailleurs, la chaîne donnée à @code{'exec'} n'a plus besoin de terminer par un retour à la ligne. Ajout du paramètre `optimize'.



Modifié dans la version 3.5: précédemment, l'exception @ref{522,,TypeError} était levée quand un caractère nul était rencontré dans `source'.



Ajouté dans la version 3.8: @code{ast.PyCF_ALLOW_TOP_LEVEL_AWAIT} peut maintenant être passée à `flags' pour permettre une gestion haut niveau de @code{await}, @code{async for} et @code{async with}.

@end deffn

@geindex complex (classe de base)
@anchor{library/functions complex}@anchor{2ec}
@deffn {Classe} complex (number=0, /)

@deffnx {Classe} complex (string, /)

@deffnx {Classe} complex (real=0, imag=0)

Convert a single string or number to a complex number, or create a
complex number from real and imaginary parts.

Exemples :

@example
>>> complex('+1.23')
(1.23+0j)
>>> complex('-4.5j')
-4.5j
>>> complex('-1.23+4.5j')
(-1.23+4.5j)
>>> complex('\t( -1.23+4.5J )\n')
(-1.23+4.5j)
>>> complex('-Infinity+NaNj')
(-inf+nanj)
>>> complex(1.23)
(1.23+0j)
>>> complex(imag=-4.5)
-4.5j
>>> complex(-1.23, 4.5)
(-1.23+4.5j)
@end example

If the argument is a string, it must contain either a real part (in the
same format as for @ref{2eb,,float()}) or an imaginary part (in the same
format but with a @code{'j'} or @code{'J'} suffix), or both real and imaginary
parts (the sign of the imaginary part is mandatory in this case).
The string can optionally be surrounded by whitespaces and the round
parentheses @code{'('} and @code{')'}, which are ignored.
The string must not contain whitespace between @code{'+'}, @code{'-'}, the
@code{'j'} or @code{'J'} suffix, and the decimal number.
For example, @code{complex('1+2j')} is fine, but @code{complex('1 + 2j')} raises
@ref{1ff,,ValueError}.
More precisely, the input must conform to the @ref{20ed,,complexvalue}
production rule in the following grammar, after parentheses and leading and
trailing whitespace characters are removed:

@example
@anchor{library/functions grammar-token-float-complexvalue}@anchor{20ed}complexvalue ::= floatvalue |
                 floatvalue ("j" | "J") |
                 floatvalue sign absfloatvalue ("j" | "J")
@end example

Si l'argument est un nombre, le constructeur le convertit, comme le font les classes @ref{254,,int} et @ref{2eb,,float}. Pour les autres objets @code{x}, @code{complex(x)} délègue à @code{x.__complex__()}. Si @ref{5d1,,__complex__()} n'est pas définie, elle délègue à @ref{9ba,,__float__()}. Si @code{__float__()} n'est pas défini, alors elle délègue à  @ref{707,,__index__()}.

If two arguments are provided or keyword arguments are used, each argument
may be any numeric type (including complex).
If both arguments are real numbers, return a complex number with the real
component `real' and the imaginary component `imag'.
If both arguments are complex numbers, return a complex number with the real
component @code{real.real-imag.imag} and the imaginary component
@code{real.imag+imag.real}.
If one of arguments is a real number, only its real component is used in
the above expressions.

If all arguments are omitted, returns @code{0j}.

Le type complexe est décrit dans @ref{1b86,,Types numériques — int@comma{} float@comma{} complex}.


Modifié dans la version 3.6: les chiffres peuvent être groupés avec des tirets bas comme dans les expressions littérales.



Modifié dans la version 3.8: délègue à @ref{707,,__index__()} si @ref{5d1,,__complex__()} et @ref{9ba,,__float__()} ne sont pas définies.

@end deffn

@geindex built-in function; delattr()
@anchor{library/functions delattr}@anchor{20da}
@deffn {Fonction} delattr (object, name)

C'est une cousine de @ref{20e1,,setattr()}. Les arguments sont un objet et une chaîne. La chaîne doit être le nom de l'un des attributs de l'objet. La fonction supprime l'attribut nommé, si l'objet l'y autorise. Par exemple @code{delattr(x, 'foobar')} est l'équivalent de @code{del x.foobar}. `name' n'a pas besoin d'être un identifiant Python (voir @ref{20e1,,setattr()}).
@end deffn

@anchor{library/functions func-dict}@anchor{20db}
@deffn {Classe} dict (**kwarg)

@deffnx {Classe} dict (mapping, **kwarg)

@deffnx {Classe} dict (iterable, **kwarg)

Crée un nouveau dictionnaire. L'objet @ref{253,,dict} est la classe du dictionnaire. Voir @ref{253,,dict} et @ref{ab4,,Les types de correspondances — dict} pour vous documenter sur cette classe.

Pour les autres conteneurs, voir les classes natives @ref{5fc,,list}, @ref{5c3,,set}, et @ref{366,,tuple}, ainsi que le module @ref{1d,,collections}.
@end deffn

@geindex built-in function; dir()
@anchor{library/functions dir}@anchor{61d}
@deffn {Fonction} dir ()

@deffnx {Fonction} dir (object)

Sans argument, elle donne la liste des noms dans l'espace de nommage local. Avec un argument, elle essaye de donner une liste d'attributs valides pour cet objet.

Si l'objet a une méthode @ref{1ee9,,__dir__()}, elle est appelée et doit donner une liste d'attributs. Cela permet aux objets implémentant @ref{4bc,,__getattr__()} ou @ref{bc0,,__getattribute__()} de personnaliser ce que renvoie @ref{61d,,dir()}.

Si l'objet ne fournit pas de méthode @ref{1ee9,,__dir__()}, la fonction fait de son mieux en rassemblant les informations de l'attribut @ref{546,,__dict__} de l'objet, s'il est défini, et depuis son type. La liste résultante n'est pas nécessairement complète, et peut être erronée quand l'objet a une @ref{4bc,,__getattr__()} personnalisée.

Le mécanisme par défaut de @ref{61d,,dir()} se comporte différemment avec différents types d'objets, car elle préfère donner une information pertinente plutôt qu'exhaustive :


@itemize *

@item 
si l'objet est un module, la liste contiendra les noms des attributs du module ;

@item 
si l'objet est un type ou une classe, la liste contiendra les noms de ses attributs et, récursivement, des attributs de ses parents ;

@item 
autrement, la liste contient les noms des attributs de l'objet, le nom des attributs de la classe, et récursivement des attributs des parents de la classe.
@end itemize

La liste donnée est triée par ordre alphabétique, par exemple :

@example
>>> import struct
>>> dir()   # show the names in the module namespace  
['__builtins__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module 
['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
 '__initializing__', '__loader__', '__name__', '__package__',
 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape:
...     def __dir__(self):
...         return ['area', 'perimeter', 'location']
...
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']
@end example

@cartouche
@quotation Note 
étant donné que @ref{61d,,dir()} est d'abord fournie pour son côté pratique en mode interactif, elle a tendance à fournir un ensemble de noms pertinents plutôt qu'un ensemble exhaustif et rigoureusement défini, son comportement peut aussi changer d'une version à l'autre. Par exemple, les attributs de méta-classes ne sont pas donnés lorsque l'argument est une classe.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; divmod()
@anchor{library/functions divmod}@anchor{98f}
@deffn {Fonction} divmod (a, b)

Prend deux nombres (qui ne sont pas des nombres complexes) et renvoie leur quotient et reste de leur division entière sous forme d'une paire de nombres. Avec des opérandes de types différents, les règles des opérateurs binaires s'appliquent. Pour deux entiers le résultat est le même que @code{(a // b, a % b)}. Pour des nombres à virgule flottante le résultat est @code{(q, a % b)}, où `q' est généralement @code{math.floor(a / b)} mais peut valoir 1 de moins. Dans tous les cas @code{q * b + a % b} est très proche de `a'. Si @code{a % b} est différent de zéro, il a le même signe que `b' et @code{0 <= abs(a % b) < abs(b)}.
@end deffn

@geindex built-in function; enumerate()
@anchor{library/functions enumerate}@anchor{1433}
@deffn {Fonction} enumerate (iterable, start=0)

Renvoie un objet énumérant. `iterable' doit être une séquence, un @ref{1aa,,itérateur}, ou tout autre objet prenant en charge l'itération. La méthode @ref{12ab,,__next__()} de l'itérateur donné par @ref{1433,,enumerate()} renvoie un `n'-uplet contenant un compte (démarrant à `start', 0 par défaut) et les valeurs obtenues de l'itération sur `iterable'.

@example
>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
@end example

Équivalent à :

@example
def enumerate(iterable, start=0):
    n = start
    for elem in iterable:
        yield n, elem
        n += 1
@end example
@end deffn

@geindex built-in function; eval()
@anchor{library/functions func-eval}@anchor{20ee}@anchor{library/functions eval}@anchor{17e}
@deffn {Fonction} eval (source, /, globals=None, locals=None)

@*Paramètres: 

@itemize *

@item 
@code{source} (@ref{435,,str} | @ref{1cd,,code object}) -- A Python expression.

@item 
@code{globals} (@ref{253,,dict} | @code{None}) -- The global namespace (default: @code{None}).

@item 
@code{locals} (@ref{1199,,mapping} | @code{None}) -- The local namespace (default: @code{None}).
@end itemize


@*Renvoie: 
The result of the evaluated expression.


@*Raises: 
Syntax errors are reported as exceptions.


@cartouche
@quotation Avertissement 
This function executes arbitrary code. Calling it with
user-supplied input may lead to security vulnerabilities.
@end quotation
@end cartouche

The `expression' argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the `globals' and `locals'
mappings as global and local namespace.  If the `globals' dictionary is
present and does not contain a value for the key @code{__builtins__}, a
reference to the dictionary of the built-in module @ref{12,,builtins} is
inserted under that key before `expression' is parsed.  That way you can
control what builtins are available to the executed code by inserting your
own @code{__builtins__} dictionary into `globals' before passing it to
@ref{17e,,eval()}.  If the `locals' mapping is omitted it defaults to the
`globals' dictionary.  If both mappings are omitted, the expression is
executed with the `globals' and `locals' in the environment where
@ref{17e,,eval()} is called.  Note, `eval()' will only have access to the
@ref{1ec3,,nested scopes} (non-locals) in the enclosing
environment if they are already referenced in the scope that is calling
@ref{17e,,eval()} (e.g. via a @ref{1285,,nonlocal} statement).

Example:

@example
>>> x = 1
>>> eval('x+1')
2
@end example

Cette fonction peut aussi être utilisée pour exécuter n'importe quel objet code (tels que ceux créés par @ref{190,,compile()}). Dans ce cas, donnez un objet code plutôt qu'une chaîne. Si l'objet code a été compilé avec l'argument `mode' à @code{'exec'}, @ref{17e,,eval()} renvoie @code{None}.

Conseils : l'exécution dynamique d'instructions est gérée par la fonction @ref{17d,,exec()}. Les fonctions @ref{17f5,,globals()} et @ref{140,,locals()} renvoient respectivement les dictionnaires globaux et locaux, qui peuvent être utiles lors de l'usage de @ref{17e,,eval()} et @ref{17d,,exec()}.

Si la source donnée est une chaîne, les espaces de début et de fin et les tabulations sont supprimées.

Utilisez @ref{c06,,ast.literal_eval()} si vous avez besoin d'une fonction qui peut évaluer en toute sécurité des chaînes avec des expressions ne contenant que des valeurs littérales.

Lève un @ref{1848,,évènement d'audit} @code{exec} avec l'objet de code comme argument. Les événements de compilation de code peuvent également être levés.


Modifié dans la version 3.13: The `globals' and `locals' arguments can now be passed as keywords.



Modifié dans la version 3.13: The semantics of the default `locals' namespace have been adjusted as
described for the @ref{140,,locals()} builtin.

@end deffn

@geindex built-in function;exec

@geindex built-in function; exec()
@anchor{library/functions exec}@anchor{17d}
@deffn {Fonction} exec (source, /, globals=None, locals=None, *, closure=None)

@cartouche
@quotation Avertissement 
This function executes arbitrary code. Calling it with
user-supplied input may lead to security vulnerabilities.
@end quotation
@end cartouche

This function supports dynamic execution of Python code. `source' must be
either a string or a code object.  If it is a string, the string is parsed as
a suite of Python statements which is then executed (unless a syntax error
occurs). @footnote{
Notez que l'analyseur n'accepte que des fin de lignes de style Unix. Si vous lisez le code depuis un fichier, assurez-vous d'utiliser la conversion de retours à la ligne pour convertir les fin de lignes Windows et Mac.
} If it is a code object, it is simply executed.  In all cases,
the code that's executed is expected to be valid as file input (see the
section @ref{20c4,,Fichier d'entrée} in the Reference Manual). Be aware that the
@ref{1285,,nonlocal}, @ref{9bb,,yield},  and @ref{9bc,,return}
statements may not be used outside of
function definitions even within the context of code passed to the
@ref{17d,,exec()} function. The return value is @code{None}.

In all cases, if the optional parts are omitted, the code is executed in the
current scope.  If only `globals' is provided, it must be a dictionary
(and not a subclass of dictionary), which
will be used for both the global and the local variables.  If `globals' and
`locals' are given, they are used for the global and local variables,
respectively.  If provided, `locals' can be any mapping object.  Remember
that at the module level, globals and locals are the same dictionary.

@cartouche
@quotation Note 
When @code{exec} gets two separate objects as `globals' and `locals', the
code will be executed as if it were embedded in a class definition. This
means functions and classes defined in the executed code will not be able
to access variables assigned at the top level (as the "top level"
variables are treated as class variables in a class definition).
@end quotation
@end cartouche

Si le dictionnaire `globals' ne contient pas de valeur pour la clé @code{__builtins__}, une référence au dictionnaire du module @ref{12,,builtins} y est inséré. Cela vous permet de contrôler quelles fonctions natives sont exposées au code exécuté en insérant votre propre dictionnaire @code{__builtins__} dans `globals' avant de le donner à @ref{17d,,exec()}.

The `closure' argument specifies a closure--a tuple of cellvars.
It's only valid when the `object' is a code object containing
@ref{1ec4,,free (closure) variables}.
The length of the tuple must exactly match the length of the code object's
@ref{1e7e,,co_freevars} attribute.

Lève un @ref{1848,,évènement d'audit} @code{exec} avec l'objet de code comme argument. Les événements de compilation de code peuvent également être levés.

@cartouche
@quotation Note 
The built-in functions @ref{17f5,,globals()} and @ref{140,,locals()} return the current
global and local namespace, respectively, which may be useful to pass around
for use as the second and third argument to @ref{17d,,exec()}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
The default `locals' act as described for function @ref{140,,locals()} below.
Pass an explicit `locals' dictionary if you need to see effects of the
code on `locals' after function @ref{17d,,exec()} returns.
@end quotation
@end cartouche


Modifié dans la version 3.11: ajout du paramètre `closure'.



Modifié dans la version 3.13: The `globals' and `locals' arguments can now be passed as keywords.



Modifié dans la version 3.13: The semantics of the default `locals' namespace have been adjusted as
described for the @ref{140,,locals()} builtin.

@end deffn

@geindex built-in function; filter()
@anchor{library/functions filter}@anchor{84f}
@deffn {Fonction} filter (function, iterable)

Construit un itérateur depuis les éléments d'`iterable' pour lesquels `function' renvoie @code{True}. `iterable' peut aussi bien être une séquence, un conteneur qui prend en charge l'itération, ou un itérateur. Si `function' est @code{None}, la fonction identité est prise, c'est-à-dire que tous les éléments faux d'`iterable' sont supprimés.

Notez que @code{filter(function, iterable)} est l'équivalent du générateur @code{(item for item in iterable if function(item))} si `function' n'est pas @code{None}, et de @code{(item for item in iterable if item)} si `function' est @code{None}.

Voir @ref{20ef,,itertools.filterfalse()} pour la fonction complémentaire qui donne les éléments d'`iterable' pour lesquels `function' renvoie @code{False}.
@end deffn

@geindex float (classe de base)
@anchor{library/functions float}@anchor{2eb}
@deffn {Classe} float (number=0.0, /)

@deffnx {Classe} float (string, /)

@geindex NaN
@geindex Infinity

Return a floating-point number constructed from a number or a string.

Exemples :

@example
>>> float('+1.23')
1.23
>>> float('   -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf
@end example

If the argument is a string, it should contain a decimal number, optionally
preceded by a sign, and optionally embedded in whitespace.  The optional
sign may be @code{'+'} or @code{'-'}; a @code{'+'} sign has no effect on the value
produced.  The argument may also be a string representing a NaN
(not-a-number), or positive or negative infinity.
More precisely, the input must conform to the @ref{20f0,,floatvalue}
production rule in the following grammar, after leading and trailing
whitespace characters are removed:

@example
@anchor{library/functions grammar-token-float-sign}@anchor{20f1}sign          ::= "+" | "-"
@anchor{library/functions grammar-token-float-infinity}@anchor{20f2}infinity      ::= "Infinity" | "inf"
@anchor{library/functions grammar-token-float-nan}@anchor{20f3}nan           ::= "nan"
@anchor{library/functions grammar-token-float-digit}@anchor{20f4}digit         ::= <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
@anchor{library/functions grammar-token-float-digitpart}@anchor{20f5}digitpart     ::= digit (["_"] digit)*
@anchor{library/functions grammar-token-float-number}@anchor{20f6}number        ::= [digitpart] "." digitpart | digitpart ["."]
@anchor{library/functions grammar-token-float-exponent}@anchor{20f7}exponent      ::= ("e" | "E") [sign] digitpart
@anchor{library/functions grammar-token-float-floatnumber}@anchor{20f8}floatnumber   ::= number [exponent]
@anchor{library/functions grammar-token-float-absfloatvalue}@anchor{20f9}absfloatvalue ::= floatnumber | infinity | nan
@anchor{library/functions grammar-token-float-floatvalue}@anchor{20f0}floatvalue    ::= [sign] absfloatvalue
@end example

Case is not significant, so, for example, "inf", "Inf", "INFINITY", and
"iNfINity" are all acceptable spellings for positive infinity.

Otherwise, if the argument is an integer or a floating-point number, a
floating-point number with the same value (within Python's floating-point
precision) is returned.  If the argument is outside the range of a Python
float, an @ref{86d,,OverflowError} will be raised.

Pour un objet Python général @code{x}, @code{float(x)} est délégué à @code{x.__float__()}. Si @ref{9ba,,__float__()} n'est pas défini alors il est délégué à @ref{707,,__index__()}.

Sans argument, @code{0.0} est renvoyé.

Le type `float' est décrit dans @ref{1b86,,Types numériques — int@comma{} float@comma{} complex}.


Modifié dans la version 3.6: les chiffres peuvent être groupés avec des tirets bas comme dans les expressions littérales.



Modifié dans la version 3.7: Le paramètre est désormais un argument exclusivement positionnel.



Modifié dans la version 3.8: délègue à @ref{707,,__index__()} si @ref{9ba,,__float__()} n'est pas définie.

@end deffn

@geindex __format__
@geindex string;format() (built-in function)

@geindex built-in function; format()
@anchor{library/functions format}@anchor{60a}
@deffn {Fonction} format (value, format_spec='@w{'})

Convertit une valeur en sa représentation « formatée », contrôlée par `format_spec'. L'interprétation de `format_spec' dépend du type de la valeur. Cependant, il existe une syntaxe standard utilisée par la plupart des types natifs : @ref{1e5,,Mini-langage de spécification de format}.

Par défaut, `format_spec' est une chaîne vide. Dans ce cas, appeler cette fonction a généralement le même effet qu'appeler @ref{435,,str(value)}.

A call to @code{format(value, format_spec)} is translated to
@code{type(value).__format__(value, format_spec)} which bypasses the instance
dictionary when searching for the value's @ref{609,,__format__()} method.
A @ref{522,,TypeError} exception is raised if the method search reaches
@ref{a7a,,object} and the `format_spec' is non-empty, or if either the
`format_spec' or the return value are not strings.


Modifié dans la version 3.4: @code{object().__format__(format_spec)} lève @ref{522,,TypeError} si `format_spec' n'est pas une chaîne vide.

@end deffn

@anchor{library/functions func-frozenset}@anchor{20dc}
@deffn {Classe} frozenset (iterable=set())

Renvoie un nouveau @ref{5c4,,frozenset}, dont les objets sont éventuellement tirés d'`iterable'. @code{frozenset} est une classe native. Voir @ref{5c4,,frozenset} et @ref{20fa,,Types d'ensembles — set@comma{} frozenset} pour la documentation sur cette classe.

Pour d'autres conteneurs, voyez les classes natives @ref{5c3,,set}, @ref{5fc,,list}, @ref{366,,tuple}, et @ref{253,,dict}, ainsi que le module @ref{1d,,collections}.
@end deffn

@geindex built-in function; getattr()
@anchor{library/functions getattr}@anchor{bbf}
@deffn {Fonction} getattr (object, name)

@deffnx {Fonction} getattr (object, name, default)

Renvoie la valeur de l'attribut nommé `name' de l'objet `object'. `name' doit être une chaîne. Si la chaîne est le nom d'un des attributs de l'objet, le résultat est la valeur de cet attribut. Par exemple, @code{getattr(x, 'foobar')} est équivalent à @code{x.foobar}. Si l'attribut n'existe pas, mais que `default' est fourni, celui-ci est renvoyé. Sinon l'exception @ref{343,,AttributeError} est levée. `name' n'a pas besoin d'être un identifiant Python (voir @ref{20e1,,setattr()}).

@cartouche
@quotation Note 
étant donné que la @ref{1c48,,transformation des noms privés} se produit au moment de la compilation, il faut modifier manuellement le nom d'un attribut privé (attributs avec deux traits de soulignement en tête) afin de le récupérer avec @ref{bbf,,getattr()}.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; globals()
@anchor{library/functions globals}@anchor{17f5}
@deffn {Fonction} globals ()

Renvoie le dictionnaire implémentant l'espace de nommage du module actuel. Pour le code dans les fonctions, il est défini lorsque la fonction est définie et reste le même quel que soit le moment où la fonction est appelée.
@end deffn

@geindex built-in function; hasattr()
@anchor{library/functions hasattr}@anchor{4bb}
@deffn {Fonction} hasattr (object, name)

Les arguments sont : un objet et une chaîne de caractères. Le résultat est @code{True} si la chaîne est le nom d'un des attributs de l'objet, sinon @code{False} (l'implémentation appelle @code{getattr(object, name)} et regarde si une exception @ref{343,,AttributeError} a été levée).
@end deffn

@geindex built-in function; hash()
@anchor{library/functions hash}@anchor{5d5}
@deffn {Fonction} hash (object)

Renvoie la valeur de hachage d'un objet (s'il en a une). Les valeurs de hachage sont des entiers. Elles sont utilisées pour comparer rapidement des clés de dictionnaire lors de leur recherche. Les valeurs numériques égales ont la même valeur de hachage (même si leurs types sont différents, comme pour @code{1} et @code{1.0}).

@cartouche
@quotation Note 
For objects with custom @ref{ae9,,__hash__()} methods,
note that @ref{5d5,,hash()}
truncates the return value based on the bit width of the host machine.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; help()
@anchor{library/functions help}@anchor{8c4}
@deffn {Fonction} help ()

@deffnx {Fonction} help (request)

Invoque le système d'aide natif (cette fonction est destinée à l'usage en mode interactif). Si aucun argument n'est fourni, le système d'aide démarre dans l'interpréteur. Si l'argument est une chaîne, celle-ci est recherchée comme le nom d'un module, d'une fonction, d'une classe, d'une méthode, d'un mot clé, ou d'un sujet de documentation, et une page d'aide est affichée sur la console. Si l'argument est d'un autre type, une page d'aide sur cet objet est générée.

Notez que si une barre oblique (/) apparaît dans la liste des paramètres d'une fonction lorsque vous appelez @ref{8c4,,help()}, cela signifie que les paramètres placés avant la barre oblique sont strictement positionnels. Pour plus d'informations, voir @ref{20fb,,La FAQ sur les arguments positionnels}.

Cette fonction est ajoutée à l'espace de nommage natif par le module @ref{c6,,site}.


Modifié dans la version 3.4: les changements aux modules @ref{b4,,pydoc} et @ref{7d,,inspect} rendent les signatures des appelables plus compréhensibles et cohérentes.

@end deffn

@geindex built-in function; hex()
@anchor{library/functions hex}@anchor{12ad}
@deffn {Fonction} hex (x)

Convertit un entier en chaîne hexadécimale préfixée de "0x". Si `x' n'est pas un @ref{254,,int}, il doit définir une méthode @ref{707,,__index__()} qui renvoie un entier. Quelques exemples :

@example
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
@end example

Si vous voulez convertir un nombre entier en chaîne hexadécimale, en majuscule ou non, préfixée ou non, vous pouvez utiliser l'une des méthodes suivantes :

@example
>>> '%#x' % 255, '%x' % 255, '%X' % 255
('0xff', 'ff', 'FF')
>>> format(255, '#x'), format(255, 'x'), format(255, 'X')
('0xff', 'ff', 'FF')
>>> f'@{255:#x@}', f'@{255:x@}', f'@{255:X@}'
('0xff', 'ff', 'FF')
@end example

Voir aussi @ref{60a,,format()} pour plus d'informations.

Voir aussi @ref{254,,int()} pour convertir une chaîne hexadécimale en un entier (en affectant 16 à l'argument `base').

@cartouche
@quotation Note 
pour obtenir une représentation hexadécimale sous forme de chaîne d'un nombre à virgule flottante, utilisez la méthode @ref{1c9f,,float.hex()}.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; id()
@anchor{library/functions id}@anchor{13d9}
@deffn {Fonction} id (object)

Renvoie l'« identité » d'un objet. C'est un nombre entier garanti unique et constant pour cet objet durant sa durée de vie. Deux objets dont les durées de vie ne se chevauchent pas peuvent partager le même @ref{13d9,,id()}.

`Particularité de l'implémentation CPython :' c'est l'adresse de l'objet en mémoire.

Lève un @ref{1848,,évènement d'audit} @code{builtins.id} avec l'argument @code{id}.
@end deffn

@geindex built-in function; input()
@anchor{library/functions input}@anchor{12b6}
@deffn {Fonction} input ()

@deffnx {Fonction} input (prompt)

Si l'argument `prompt' est donné, il est écrit sur la sortie standard sans le retour à la ligne final. La fonction lit ensuite une ligne sur l'entrée standard et la convertit en chaîne (supprimant le retour à la ligne final) qu'elle renvoie. Lorsque EOF est lu, @ref{12b7,,EOFError} est levée. Exemple :

@example
>>> s = input('--> ')  
--> Monty Python's Flying Circus
>>> s  
"Monty Python's Flying Circus"
@end example

Si le module @ref{b9,,readline} est chargé, @ref{12b6,,input()} l'utilisera pour fournir des fonctionnalités d'édition et d'historique élaborées.

Lève un @ref{1848,,évènement d'audit} @code{builtins.input} avec l'argument @code{prompt} avant de lire l'entrée.

Lève un @ref{1848,,événement d'audit} @code{builtins.input/result} avec le résultat après avoir lu avec succès l'entrée.
@end deffn

@geindex int (classe de base)
@anchor{library/functions int}@anchor{254}
@deffn {Classe} int (number=0, /)

@deffnx {Classe} int (string, /, base=10)

Return an integer object constructed from a number or a string, or return
@code{0} if no arguments are given.

Exemples :

@example
>>> int(123.45)
123
>>> int('123')
123
>>> int('   -12_345\n')
-12345
>>> int('FACE', 16)
64206
>>> int('0xface', 0)
64206
>>> int('01110011', base=2)
115
@end example

If the argument defines @ref{706,,__int__()},
@code{int(x)} returns @code{x.__int__()}.  If the argument defines @ref{707,,__index__()},
it returns @code{x.__index__()}.  If the argument defines @ref{705,,__trunc__()},
it returns @code{x.__trunc__()}.
For floating-point numbers, this truncates towards zero.

If the argument is not a number or if `base' is given, then it must be a string,
@ref{1bd,,bytes}, or @ref{528,,bytearray} instance representing an integer
in radix `base'.  Optionally, the string can be preceded by @code{+} or @code{-}
(with no space in between), have leading zeros, be surrounded by whitespace,
and have single underscores interspersed between digits.

Une chaine représentant un entier en base `n' contient des chiffres, chacun représentant une valeur de 0 à n-1. Les valeurs 0 à 9 peuvent être représentées par n'importe lequel des chiffres décimaux Unicode. Les valeurs de 10 à 35 peuvent être représentées par @code{a} jusqu'à @code{z} (ou @code{A} à @code{Z}). La `base' par défaut est 10. Les valeurs autorisées pour `base' sont 0 et 2 à 36. Les littéraux en base 2, 8, et 16 peuvent être préfixés avec @code{0b}/@code{0B}, @code{0o}/@code{0O}, ou @code{0x}/@code{0X} tout comme les littéraux dans le code. Fournir 0 comme `base' demande d'interpréter exactement comme un @ref{1e4b,,entier littéral dans du code} Python, donc la base sera 2, 8, 10, ou 16 en fonction du préfixe. Indiquer 0 comme base interdit les zéros en tête, ainsi @code{int('010', 0)} n'est pas légal, alors que @code{int('010')} l'est tout comme @code{int('010', 8)}.

Le type des entiers est décrit dans @ref{1b86,,Types numériques — int@comma{} float@comma{} complex}.


Modifié dans la version 3.4: si `base' n'est pas une instance d'@ref{254,,int} et que `base' a une méthode @ref{707,,base.__index__}, cette méthode est appelée pour obtenir un entier pour cette base. Les versions précédentes utilisaient @ref{706,,base.__int__} au lieu de @ref{707,,base.__index__}.



Modifié dans la version 3.6: les chiffres peuvent être groupés avec des tirets bas comme dans les expressions littérales.



Modifié dans la version 3.7: The first parameter is now positional-only.



Modifié dans la version 3.8: Revient à @ref{707,,__index__()} si @ref{706,,__int__()} n'est pas définie.



Modifié dans la version 3.11: le repli vers @ref{705,,__trunc__()} est obsolète.



Modifié dans la version 3.11: @ref{254,,int} string inputs and string representations can be limited to
help avoid denial of service attacks. A @ref{1ff,,ValueError} is raised when
the limit is exceeded while converting a string to an @ref{254,,int} or
when converting an @ref{254,,int} into a string would exceed the limit.
See the @ref{5df,,integer string conversion length limitation} documentation.

@end deffn

@geindex built-in function; isinstance()
@anchor{library/functions isinstance}@anchor{42b}
@deffn {Fonction} isinstance (object, classinfo)

Renvoie @code{True} si `object' est une instance de `classinfo', ou d'une de ses classes filles, directe, indirecte, ou @ref{1193,,abstraite}. Si `object' n'est pas un objet du type donné, la fonction renvoie toujours @code{False}. Si `classinfo' est un `n'-uplet de types (ou récursivement, d'autres `n'-uplets) ou une @ref{7ac,,union de types} différents, renvoie @code{True} si `object' est une instance de n'importe quel de ces types. Si `classinfo' n'est ni un type ni un `n'-uplet de types (et récursivement), une exception @ref{522,,TypeError} est levée. @ref{522,,TypeError} ne peut pas être levée pour un type invalide si une des vérifications précédentes réussit.


Modifié dans la version 3.10: `classinfo' peut être une @ref{7ac,,union de types}.

@end deffn

@geindex built-in function; issubclass()
@anchor{library/functions issubclass}@anchor{7ab}
@deffn {Fonction} issubclass (class, classinfo)

Renvoie @code{True} si `class' est une classe fille (directe, indirecte ou @ref{1193,,abstraite}) de `classinfo'. Une classe est considérée sous-classe d'elle-même. `classinfo' peut être un `n'-uplet de classes (ou récursivement, d'autres `n'-uplets) ou une @ref{7ac,,union de types}, dans ce cas elle renvoie @code{True} si `class' est une sous-classe d'une partie de `classinfo'. Dans tous les autres cas, une @ref{522,,TypeError} est levée.


Modifié dans la version 3.10: `classinfo' peut être une @ref{7ac,,union de types}.

@end deffn

@geindex built-in function; iter()
@anchor{library/functions iter}@anchor{7c1}
@deffn {Fonction} iter (object)

@deffnx {Fonction} iter (object, sentinel)

Return an @ref{1aa,,iterator} object.  The first argument is interpreted very
differently depending on the presence of the second argument. Without a
second argument, `object' must be a collection object which supports the
@ref{1205,,iterable} protocol (the @ref{1ede,,__iter__()} method),
or it must support
the sequence protocol (the @ref{280,,__getitem__()} method with integer arguments
starting at @code{0}).  If it does not support either of those protocols,
@ref{522,,TypeError} is raised. If the second argument, `sentinel', is given,
then `object' must be a callable object.  The iterator created in this case
will call `object' with no arguments for each call to its
@ref{12ab,,__next__()} method; if the value returned is equal to
`sentinel', @ref{be8,,StopIteration} will be raised, otherwise the value will
be returned.

Voir aussi @ref{20fc,,Les types itérateurs}.

Une autre application utile de la deuxième forme de @ref{7c1,,iter()} est de construire un lecteur par blocs. Par exemple, lire des blocs de taille fixe d'une base de donnée binaire jusqu'à ce que la fin soit atteinte :

@example
from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b'@w{'}):
        process_block(block)
@end example
@end deffn

@geindex built-in function; len()
@anchor{library/functions len}@anchor{619}
@deffn {Fonction} len (s)

Renvoie la longueur (nombre d'éléments) d'un objet. L'argument peut être une séquence (telle qu'une chaîne de caractères ou d'octets, un `n'-uplet, une liste ou un intervalle) ou une collection (telle qu'un dictionnaire, un ensemble ou un ensemble figé).

`Particularité de l'implémentation CPython :' @code{len} lève une @ref{86d,,OverflowError} sur des longueurs supérieures à @ref{11a2,,sys.maxsize}, par exemple pour @ref{930,,range(2 ** 100)}.
@end deffn

@anchor{library/functions func-list}@anchor{20dd}
@deffn {Classe} list

@deffnx {Classe} list (iterable)

Contrairement aux apparences, @ref{5fc,,list} n'est pas une fonction mais un type séquentiel mutable, comme décrit dans @ref{20fd,,Listes} et @ref{1bd7,,Types séquentiels — list@comma{} tuple@comma{} range}.
@end deffn

@geindex built-in function; locals()
@anchor{library/functions locals}@anchor{140}
@deffn {Fonction} locals ()

@quotation

Return a mapping object representing the current local symbol table, with
variable names as the keys, and their currently bound references as the
values.

At module scope, as well as when using @ref{17d,,exec()} or @ref{17e,,eval()} with
a single namespace, this function returns the same namespace as
@ref{17f5,,globals()}.

At class scope, it returns the namespace that will be passed to the
metaclass constructor.

When using @code{exec()} or @code{eval()} with separate local and global
arguments, it returns the local namespace passed in to the function call.

In all of the above cases, each call to @code{locals()} in a given frame of
execution will return the `same' mapping object. Changes made through
the mapping object returned from @code{locals()} will be visible as assigned,
reassigned, or deleted local variables, and assigning, reassigning, or
deleting local variables will immediately affect the contents of the
returned mapping object.

In an @ref{17c,,optimized scope} (including functions, generators, and
coroutines), each call to @code{locals()} instead returns a fresh dictionary
containing the current bindings of the function's local variables and any
nonlocal cell references. In this case, name binding changes made via the
returned dict are `not' written back to the corresponding local variables
or nonlocal cell references, and assigning, reassigning, or deleting local
variables and nonlocal cell references does `not' affect the contents
of previously returned dictionaries.

Calling @code{locals()} as part of a comprehension in a function, generator, or
coroutine is equivalent to calling it in the containing scope, except that
the comprehension's initialised iteration variables will be included. In
other scopes, it behaves as if the comprehension were running as a nested
function.

Calling @code{locals()} as part of a generator expression is equivalent to
calling it in a nested generator function.
@end quotation


Modifié dans la version 3.12: The behaviour of @code{locals()} in a comprehension has been updated as
described in 
@geindex Python Enhancement Proposals; PEP 709
PEP 709@footnote{https://peps.python.org/pep-0709/}.



Modifié dans la version 3.13: As part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}, the semantics of mutating the mapping objects
returned from this function are now defined. The behavior in
@ref{17c,,optimized scopes} is now as described above.
Aside from being defined, the behaviour in other scopes remains
unchanged from previous versions.

@end deffn

@geindex built-in function; map()
@anchor{library/functions map}@anchor{84e}
@deffn {Fonction} map (function, iterable, *iterables)

Renvoie un itérateur appliquant `function' à chaque élément de `iterable', et donnant ses résultats au fur et à mesure avec @code{yield}. Si d'autres `iterables' sont fournis, `function' doit prendre autant d'arguments, et est appelée avec les éléments de tous les itérables en parallèle. Avec plusieurs itérables, l'itération s'arrête avec l'itérable le plus court. Pour les cas où les arguments sont déjà rangés sous forme de `n'-uplets, voir @ref{10c5,,itertools.starmap()}.
@end deffn

@geindex built-in function; max()
@anchor{library/functions max}@anchor{ef4}
@deffn {Fonction} max (iterable, *, key=None)

@deffnx {Fonction} max (iterable, *, default, key=None)

@deffnx {Fonction} max (arg1, arg2, *args, key=None)

Renvoie le plus grand élément d'un itérable, ou l'argument le plus grand parmi au moins deux arguments.

Si un seul argument positionnel est fourni, il doit être @ref{1205,,itérable}. Le plus grand élément de l'itérable est renvoyé. Si au moins deux arguments positionnels sont fournis, l'argument le plus grand sera renvoyé.

Elle accepte deux arguments nommés optionnels. L'argument `key' spécifie une fonction à un argument permettant de trier comme pour @ref{bbd,,list.sort()}. L'argument `default' fournit quant à lui un objet à donner si l'itérable fourni est vide. Si l'itérable est vide et que `default' n'est pas fourni, @ref{1ff,,ValueError} est levée.

Si plusieurs éléments représentent la plus grande valeur, le premier rencontré est renvoyé. C'est cohérent avec d'autres outils préservant une stabilité lors du tri, tels que @code{sorted(iterable, key=keyfunc, reverse=True)[0]} et @code{heapq.nlargest(1, iterable, key=keyfunc)}.


Modifié dans la version 3.4: Added the `default' keyword-only parameter.



Modifié dans la version 3.8: l'argument `key' peut être @code{None}.

@end deffn

@anchor{library/functions func-memoryview}@anchor{20de}
@deffn {Classe} memoryview (object)

Renvoie une « vue mémoire » (`memory view') créée depuis l'argument. Voir @ref{20fe,,Vues mémoire} pour plus d'informations.
@end deffn

@geindex built-in function; min()
@anchor{library/functions min}@anchor{ef3}
@deffn {Fonction} min (iterable, *, key=None)

@deffnx {Fonction} min (iterable, *, default, key=None)

@deffnx {Fonction} min (arg1, arg2, *args, key=None)

Renvoie le plus petit élément d'un itérable ou le plus petit d'au moins deux arguments.

Si un seul argument est fourni, il doit être @ref{1205,,itérable}. Le plus petit élément de l'itérable est renvoyé. Si au moins deux arguments positionnels sont fournis, le plus petit argument positionnel est renvoyé.

Elle accepte deux arguments nommés optionnels. L'argument `key' spécifie une fonction à un argument permettant de trier comme pour @ref{bbd,,list.sort()}. L'argument `default' fournit quant à lui un objet à donner si l'itérable fourni est vide. Si l'itérable est vide et que `default' n'est pas fourni, @ref{1ff,,ValueError} est levée.

Si plusieurs éléments sont minimaux, la fonction renvoie le premier rencontré. C'est cohérent avec d'autres outils préservant une stabilité lors du tri, tels que @code{sorted(iterable, key=keyfunc)[0]} et @code{heapq.nsmallest(1, iterable, key=keyfunc)}.


Modifié dans la version 3.4: Added the `default' keyword-only parameter.



Modifié dans la version 3.8: l'argument `key' peut être @code{None}.

@end deffn

@geindex built-in function; next()
@anchor{library/functions next}@anchor{7c2}
@deffn {Fonction} next (iterator)

@deffnx {Fonction} next (iterator, default)

Donne l'élément suivant de l'@ref{1aa,,itérateur} en appelant sa méthode @ref{12ab,,__next__()}. Si `default' est fourni, il est renvoyé quand l'itérateur est épuisé, sinon une @ref{be8,,StopIteration} est levée.
@end deffn

@geindex object (classe de base)
@anchor{library/functions object}@anchor{a7a}
@deffn {Classe} object

This is the ultimate base class of all other classes. It has methods
that are common to all instances of Python classes. When the constructor
is called, it returns a new featureless object. The constructor does not
accept any arguments.

@cartouche
@quotation Note 
@ref{a7a,,object} instances do `not' have @ref{546,,__dict__}
attributes, so you can't assign arbitrary attributes to an instance of
@ref{a7a,,object}.
@end quotation
@end cartouche
@end deffn

@geindex built-in function; oct()
@anchor{library/functions oct}@anchor{12ac}
@deffn {Fonction} oct (x)

Convertit un entier en sa représentation octale dans une chaîne préfixée de "0o". Le résultat est une expression Python valide. Si `x' n'est pas un objet @ref{254,,int}, il doit définir une méthode @ref{707,,__index__()} qui donne un entier, par exemple :

@example
>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'
@end example

Si vous voulez convertir un nombre entier en une chaîne octale, avec ou sans le préfixe @code{0o}, vous pouvez utiliser l'une des méthodes suivantes.

@example
>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'@{10:#o@}', f'@{10:o@}'
('0o12', '12')
@end example

Voir aussi @ref{60a,,format()} pour plus d'informations.
@end deffn

@geindex file object;open() built-in function

@geindex built-in function; open()
@anchor{library/functions open}@anchor{505}
@deffn {Fonction} open (file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Ouvre `file' et donne un @ref{11a0,,objet fichier} correspondant. Si le fichier ne peut pas être ouvert, une @ref{40d,,OSError} est levée. Voir @ref{1c0d,,Lecture et écriture de fichiers} pour plus d'exemples d'utilisation de cette fonction.

`file' est un @ref{29d,,objet simili-chemin} donnant le chemin (absolu ou relatif au répertoire courant) du fichier à ouvrir ou un nombre entier représentant le descripteur de fichier à envelopper (si un descripteur de fichier est donné, il sera fermé en même temps que l'objet d'entrée-sortie renvoyé, sauf si `closefd' est mis à @code{False}).

`mode' is an optional string that specifies the mode in which the file is
opened.  It defaults to @code{'r'} which means open for reading in text mode.
Other common values are @code{'w'} for writing (truncating the file if it
already exists), @code{'x'} for exclusive creation, and @code{'a'} for appending
(which on `some' Unix systems, means that `all' writes append to the end of
the file regardless of the current seek position).  In text mode, if
`encoding' is not specified the encoding used is platform-dependent:
@ref{2db,,locale.getencoding()} is called to get the current locale encoding.
(For reading and writing raw bytes use binary mode and leave
`encoding' unspecified.)  The available modes are:

@geindex file;modes
@anchor{library/functions filemodes}@anchor{20ff}

@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Caractère

@tab

Signification

@item

@code{'r'}

@tab

ouvre en lecture (par défaut)

@item

@code{'w'}

@tab

ouvre en écriture, en effaçant le contenu du fichier

@item

@code{'x'}

@tab

ouvre pour une création exclusive, échouant si le fichier existe déjà

@item

@code{'a'}

@tab

ouvre en écriture, ajoutant à la fin du fichier s'il existe

@item

@code{'b'}

@tab

mode binaire

@item

@code{'t'}

@tab

mode texte (par défaut)

@item

@code{'+'}

@tab

ouvre en modification (lecture et écriture)

@end multitable


Le mode par défaut est @code{'r'} (ouverture pour lire du texte, un synonyme pour @code{'rt'}). Les modes @code{'w+'} et @code{'w+b'} ouvrent et vident le fichier. Les modes @code{'r+'} et @code{'r+b'} ouvrent le fichier sans le vider.

Comme mentionné dans @ref{2100,,Aperçu}, Python fait la différence entre les entrées-sorties binaires et textes. Les fichiers ouverts en mode binaire (avec @code{'b'} dans `mode') donnent leur contenu sous forme de @ref{1bd,,bytes} sans décodage. En mode texte (par défaut, ou lorsque @code{'t'} est dans le `mode'), le contenu du fichier est donné sous forme de @ref{435,,str}, les octets ayant été décodés au préalable en utilisant un encodage déduit de l'environnement ou `encoding' s'il est donné.

@cartouche
@quotation Note 
Python ne dépend pas de la représentation du fichier texte du système sous-jacent. Tout le traitement est effectué par Python lui-même, et est ainsi indépendant de la plate-forme.
@end quotation
@end cartouche

`buffering' is an optional integer used to set the buffering policy.  Pass 0
to switch buffering off (only allowed in binary mode), 1 to select line
buffering (only usable when writing in text mode), and an integer > 1 to indicate the size
in bytes of a fixed-size chunk buffer. Note that specifying a buffer size this
way applies for binary buffered I/O, but @code{TextIOWrapper} (i.e., files opened
with @code{mode='r+'}) would have another buffering. To disable buffering in
@code{TextIOWrapper}, consider using the @code{write_through} flag for
@ref{b37,,io.TextIOWrapper.reconfigure()}. When no `buffering' argument is
given, the default buffering policy works as follows:


@itemize *

@item 
les fichiers binaires sont mis dans un tampon de taille fixe, dont la taille est choisie par une heuristique essayant de déterminer la taille des blocs du système sous-jacent, ou en utilisant par défaut @ref{1651,,io.DEFAULT_BUFFER_SIZE}. Sur de nombreux systèmes, le tampon est de 4096 ou 8192 octets ;

@item 
les fichiers texte « interactifs » (fichiers pour lesquels @ref{1c10,,io.IOBase.isatty()} renvoie @code{True}) utilisent un tampon ligne par ligne. Les autres fichiers textes sont traités comme les fichiers binaires.
@end itemize

`encoding' est le nom de l'encodage utilisé pour encoder ou décoder le fichier. Il doit seulement être utilisé en mode texte. L'encodage par défaut dépend de la plateforme (ce que renvoie @ref{2db,,locale.getencoding()}), mais n'importe quel @ref{2101,,encodage de texte} pris en charge par Python peut être utilisé. Voir @ref{1b,,codecs} pour une liste des encodages pris en charge.

`errors' est une chaîne facultative spécifiant comment les erreurs d'encodage et de décodage sont gérées, ce n'est pas utilisable en mode binaire. De nombreux gestionnaires d'erreurs standards sont disponibles (listés sous @ref{1774,,Gestionnaires d'erreurs}), aussi, tout nom de gestionnaire d'erreur enregistré avec @ref{144d,,codecs.register_error()} est aussi un argument valide. Les noms standards sont :


@itemize *

@item 
@code{'strict'} pour lever une @ref{1ff,,ValueError} si une erreur d'encodage est rencontrée. La valeur par défaut, @code{None}, a le même effet.

@item 
@code{'ignore'} ignore les erreurs. Notez qu'ignorer les erreurs d'encodage peut mener à des pertes de données.

@item 
@code{'replace'} insère un marqueur de substitution (tel que @code{'?'}) en place des données mal formées.

@item 
@code{'surrogateescape'} représentera tous les octets incorrects comme des points de code de substitution de l'intervalle bas U+DC80 à U+DCFF. Ces points de code de substitution sont ensuite retransformés dans les mêmes octets lorsque le gestionnaire d'erreurs @code{surrogateescape} est utilisé pour l'écriture des données. C'est utile pour traiter des fichiers d'un encodage inconnu.

@item 
@code{'xmlcharrefreplace'} is only supported when writing to a file.
Characters not supported by the encoding are replaced with the
appropriate XML character reference @code{&#@var{nnn};}.

@item 
@code{'backslashreplace'} remplace les données mal formées par des séquences d'échappement Python (utilisant des barres obliques inverses).

@item 
@code{'namereplace'} (aussi supporté lors de l'écriture) remplace les caractères non gérés par des séquences d'échappement @code{\N@{...@}}.
@end itemize

@geindex universal newlines;open() built-in function
@anchor{library/functions open-newline-parameter}@anchor{72b}
`newline' contrôle comment interpréter les retours à la ligne. Il peut être @code{None}, @code{'@w{'}}, @code{'\n'}, @code{'\r'}, et @code{'\r\n'}. Il fonctionne comme suit :


@itemize *

@item 
Lors de la lecture, si `newline' est @code{None}, le mode `universal newlines' est activé. Les lignes lues peuvent se terminer par @code{'\n'}, @code{'\r'}, ou @code{'\r\n'}, et sont remplacées par @code{'\n'}, avant d'être renvoyées à l'appelant. S'il vaut @code{'@w{'}}, le mode `universal newline' est activé mais les fins de ligne ne sont pas remplacées. S'il a n'importe quelle autre valeur autorisée, les lignes sont seulement terminées par la chaîne donnée, qui est rendue telle quelle.

@item 
Lors de l'écriture, si `newline' est @code{None}, chaque @code{'\n'} est remplacé par le séparateur de lignes par défaut du système @ref{2102,,os.linesep}. Si `newline' est @code{'@w{'}} ou @code{'\n'} aucun remplacement n'est effectué. Si `newline' est un autre caractère valide, chaque @code{'\n'} sera remplacé par la chaîne donnée.
@end itemize

Si `closefd' est @code{False} et qu'un descripteur de fichier est fourni plutôt qu'un nom de fichier, le descripteur de fichier sera laissé ouvert lorsque le fichier sera fermé. Si un nom de fichier est donné, `closefd' doit rester @code{True} (la valeur par défaut) ; sinon, une erreur est levée.

Un `opener' personnalisé peut être utilisé en fournissant un appelable comme `opener'. Le descripteur de fichier de cet objet fichier sera alors obtenu en appelant `opener' avec (`file', `flags'). `opener' doit renvoyer un descripteur de fichier ouvert (fournir @ref{d7f,,os.open} en tant qu'`opener' aura le même effet que donner @code{None}).

Il n'est @ref{ee4,,pas possible d'hériter du descripteur de fichier} nouvellement créé.

L'exemple suivant utilise le paramètre @ref{10cb,,dir_fd} de la fonction @ref{d7f,,os.open()} pour ouvrir un fichier relatif au dossier courant :

@example
>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
...     return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
...     print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd)  # don't leak a file descriptor
@end example

Le type d'@ref{11a0,,objet fichier} renvoyé par la fonction @ref{505,,open()} dépend du mode. Lorsque @ref{505,,open()} est utilisé pour ouvrir un fichier en mode texte (@code{w}, @code{r}, @code{wt}, @code{rt}, etc.), il renvoie une classe fille de @ref{680,,io.TextIOBase} (spécifiquement : @ref{7a5,,io.TextIOWrapper}). Lors de l'ouverture d'un fichier en mode binaire avec tampon, la classe renvoyée sera une fille de @ref{67f,,io.BufferedIOBase}. La classe exacte varie : en lecture en mode binaire elle renvoie une @ref{11eb,,io.BufferedReader}, en écriture et ajout en mode binaire c'est une @ref{2103,,io.BufferedWriter}, et en lecture-écriture, c'est une @ref{2104,,io.BufferedRandom}. Lorsque le tampon est désactivé, le flux brut, une classe fille de @ref{10b2,,io.RawIOBase}, @ref{12ee,,io.FileIO} est renvoyée.

@geindex line-buffered I/O
@geindex unbuffered I/O
@geindex buffer size@comma{} I/O
@geindex I/O control;buffering
@geindex mode binaire
@geindex text mode
@geindex module;sys

Consultez aussi les modules de gestion de fichiers tels que @ref{5a,,fileinput}, @ref{7e,,io} (où @ref{505,,open()} est déclarée), @ref{a0,,os}, @ref{a1,,os.path}, @ref{df,,tempfile}, et @ref{c4,,shutil}.

Raises an @ref{1848,,auditing event} @code{open} with arguments @code{path}, @code{mode}, @code{flags}.

Les arguments @code{mode} et @code{flags} peuvent avoir été modifiés ou déduits de l'appel original.


Modifié dans la version 3.3: 


@itemize *

@item 
ajout du paramètre `opener'.

@item 
ajout du mode @code{'x'}.

@item 
@ref{103b,,IOError} était normalement levée, elle est maintenant un alias de @ref{40d,,OSError}.

@item 
@ref{1009,,FileExistsError} est maintenant levée si le fichier ouvert en mode création exclusive (@code{'x'}) existe déjà.
@end itemize



Modifié dans la version 3.4: 


@itemize *

@item 
Il n'est plus possible d'hériter de `file'.
@end itemize



Modifié dans la version 3.5: 


@itemize *

@item 
Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} pour la justification).

@item 
ajout du gestionnaire d'erreurs @code{'namereplace'}.
@end itemize



Modifié dans la version 3.6: 


@itemize *

@item 
prise en charge des objets implémentant @ref{c3f,,os.PathLike}.

@item 
Sous Windows, ouvrir un `buffer' du terminal peut renvoyer une sous-classe de @ref{10b2,,io.RawIOBase} autre que @ref{12ee,,io.FileIO}.
@end itemize



Modifié dans la version 3.11: le mode @code{'U`} a été enlevé.

@end deffn

@geindex built-in function; ord()
@anchor{library/functions ord}@anchor{1e75}
@deffn {Fonction} ord (c)

Renvoie le nombre entier représentant le code Unicode du caractère représenté par la chaîne donnée. Par exemple, @code{ord('a')} renvoie le nombre entier @code{97} et @code{ord('€')} (symbole euro) renvoie @code{8364}. Il s'agit de la réciproque de @ref{15fb,,chr()}.
@end deffn

@geindex built-in function; pow()
@anchor{library/functions pow}@anchor{9c0}
@deffn {Fonction} pow (base, exp, mod=None)

Renvoie `base' puissance `exp' et, si `mod' est présent, donne `base' puissance `exp' modulo `mod' (calculé de manière plus efficiente que @code{pow(base, exp) % mod}). La forme à deux arguments @code{pow(base, exp)} est équivalente à l'opérateur puissance : @code{base**exp}.

The arguments must have numeric types.  With mixed operand types, the
coercion rules for binary arithmetic operators apply.  For @ref{254,,int}
operands, the result has the same type as the operands (after coercion)
unless the second argument is negative; in that case, all arguments are
converted to float and a float result is delivered.  For example, @code{pow(10, 2)}
returns @code{100}, but @code{pow(10, -2)} returns @code{0.01}.  For a negative base of
type @ref{254,,int} or @ref{2eb,,float} and a non-integral exponent, a complex
result is delivered.  For example, @code{pow(-9, 0.5)} returns a value close
to @code{3j}. Whereas, for a negative base of type @ref{254,,int} or @ref{2eb,,float}
with an integral exponent, a float result is delivered. For example,
@code{pow(-9, 2.0)} returns @code{81.0}.

Pour des opérandes `base' et `exp' de type @ref{254,,int}, si `mod' est présent, `mod' doit également être de type entier et `mod' doit être non nul. Si `mod' est présent et que `exp' est négatif, `base' et `mod' doivent être premiers entre eux. Dans ce cas, @code{pow(inv_base, -exp, mod)} est renvoyé, où `inv_base' est un inverse de `base' modulo `mod'.

Voici un exemple de calcul d'un inverse de @code{38} modulo @code{97} :

@example
>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True
@end example


Modifié dans la version 3.8: pour les opérandes @ref{254,,int}, la forme à trois arguments de @code{pow} permet maintenant au deuxième argument d'être négatif, permettant le calcul des inverses modulaires.



Modifié dans la version 3.8: autorise les arguments nommés. Auparavant, seuls les arguments positionnels étaient autorisés.

@end deffn

@geindex built-in function; print()
@anchor{library/functions print}@anchor{f60}
@deffn {Fonction} print (*objects, sep=' ', end='\n', file=None, flush=False)

Écrit `objects' dans le flux texte `file', séparés par `sep' et suivis de `end'. Les arguments `sep', `end', `file', et `flush', s'ils sont présents, doivent être passés en arguments nommés.

Tous les arguments positionnels sont convertis en chaîne comme le fait @ref{435,,str()}, puis écrits sur le flux, séparés par `sep' et terminés par `end'. `sep' et `end' doivent être des chaînes, ou @code{None}, indiquant de prendre les valeurs par défaut. Si aucun `objects' n'est donné @ref{f60,,print()} écrit seulement `end'.

L'argument `file' doit être un objet avec une méthode @code{write(string)} ; s'il n'est pas fourni, ou vaut @code{None}, @ref{ac4,,sys.stdout} est utilisé. Puisque les arguments affichés sont convertis en chaîne, @ref{f60,,print()} ne peut pas être utilisée avec des fichiers ouverts en mode binaire. Pour ceux-ci utilisez plutôt @code{file.write(...)}.

Que la sortie utilise un tampon ou non est souvent décidé par `file'. Cependant, si l'argument `flush' est vrai, le tampon du flux est vidé explicitement.


Modifié dans la version 3.3: ajout de l'argument nommé `flush'.

@end deffn

@geindex property (classe de base)
@anchor{library/functions property}@anchor{192}
@deffn {Classe} property (fget=None, fset=None, fdel=None, doc=None)

Renvoie un attribut propriété.

`fget' est une fonction permettant d'obtenir la valeur d'un attribut. `fset' est une fonction pour en définir la valeur. `fdel' quant à elle permet de supprimer la valeur d'un attribut, et `doc' crée une chaîne de documentation (`docstring') pour l'attribut.

Une utilisation courante est de définir un attribut managé @code{x} :

@example
class C:
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")
@end example

Si `c' est une instance de `C', @code{c.x} appelle l'accesseur (`getter' en anglais), @code{c.x = value} invoque le mutateur (`setter'), et @code{del x} le destructeur (`deleter').

Si elle est fournie, `doc' est la chaîne de documentation de l'attribut. Autrement la propriété copie celle de `fget' (si elle existe). Cela rend possible la création de propriétés en lecture seule en utilisant simplement @ref{192,,property()} comme @ref{71b,,décorateur} :

@example
class Parrot:
    def __init__(self):
        self._voltage = 100000

    @@property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage
@end example

The @code{@@property} decorator turns the @code{voltage()} method into a "getter"
for a read-only attribute with the same name, and it sets the docstring for
`voltage' to "Get the current voltage."

@geindex built-in function; property.getter()
@anchor{library/functions property getter}@anchor{15e3}
@deffn {Fonction} @@getter
@end deffn

@geindex built-in function; property.setter()
@anchor{library/functions property setter}@anchor{15e4}
@deffn {Fonction} @@setter
@end deffn

@geindex built-in function; property.deleter()
@anchor{library/functions property deleter}@anchor{15e5}
@deffn {Fonction} @@deleter

A property object has @code{getter}, @code{setter},
and @code{deleter} methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function.  This is best explained with an example:

@example
class C:
    def __init__(self):
        self._x = None

    @@property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @@x.setter
    def x(self, value):
        self._x = value

    @@x.deleter
    def x(self):
        del self._x
@end example

Ce code est l'exact équivalent du premier exemple. Soyez attentifs à bien donner aux fonctions additionnelles le même nom que la propriété (@code{x} dans ce cas).

L'objet propriété renvoyé possède aussi les attributs @code{fget}, @code{fset} et @code{fdel} correspondants aux arguments du constructeur.
@end deffn


Modifié dans la version 3.5: les chaînes de documentation des objets `property' sont maintenant en lecture-écriture.


@geindex __name__ (attribut property)
@anchor{library/functions property __name__}@anchor{191}
@deffn {Attribut} __name__

Attribute holding the name of the property. The name of the property
can be changed at runtime.


Ajouté dans la version 3.13.

@end deffn
@end deffn

@anchor{library/functions func-range}@anchor{20df}
@deffn {Classe} range (stop)

@deffnx {Classe} range (start, stop, step=1)

Contrairement aux apparences, @ref{930,,range} n'est pas une fonction mais un type de séquence immuable, comme décrit dans @ref{2105,,Ranges} et @ref{1bd7,,Types séquentiels — list@comma{} tuple@comma{} range}.
@end deffn

@geindex built-in function; repr()
@anchor{library/functions repr}@anchor{7e7}
@deffn {Fonction} repr (object)

Return a string containing a printable representation of an object.  For many
types, this function makes an attempt to return a string that would yield an
object with the same value when passed to @ref{17e,,eval()}; otherwise, the
representation is a string enclosed in angle brackets that contains the name
of the type of the object together with additional information often
including the name and address of the object.  A class can control what this
function returns for its instances
by defining a @ref{607,,__repr__()} method.
If @ref{14d6,,sys.displayhook()} is not accessible, this function will raise
@ref{193,,RuntimeError}.

This class has a custom representation that can be evaluated:

@example
class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

   def __repr__(self):
      return f"Person('@{self.name@}', @{self.age@})"
@end example
@end deffn

@geindex built-in function; reversed()
@anchor{library/functions reversed}@anchor{850}
@deffn {Fonction} reversed (seq)

Return a reverse @ref{1aa,,iterator}.  `seq' must be an object which has
a @ref{1edf,,__reversed__()} method or supports the sequence protocol (the
@ref{1ee5,,__len__()} method and the @ref{280,,__getitem__()} method
with integer arguments starting at @code{0}).
@end deffn

@geindex built-in function; round()
@anchor{library/functions round}@anchor{12b8}
@deffn {Fonction} round (number, ndigits=None)

Renvoie `number' arrondi avec une précision de `ndigits' chiffres après la virgule. Si `ndigits' est omis (ou est @code{None}), l'entier le plus proche est renvoyé.

Pour les types natifs prenant en charge @ref{12b8,,round()}, les valeurs sont arrondies au multiple de 10 puissance moins `ndigits', si deux multiples sont équidistants, l'arrondi se fait vers la valeur paire (par exemple @code{round(0.5)} et @code{round(-0.5)} valent tous les deux @code{0}, et @code{round(1.5)} vaut @code{2}). `ndigits' accepte tout nombre entier (positif, zéro, ou négatif). La valeur renvoyée est un entier si `ndigits' n'est pas donné (ou est @code{None}). Sinon elle est du même type que `number'.

Pour tout autre objet Python @code{number}, @code{round} délègue à @code{number.__round__}.

@cartouche
@quotation Note 
le comportement de @ref{12b8,,round()} avec les nombres à virgule flottante peut être surprenant. Par exemple @code{round(2.675, 2)} donne @code{2.67} au lieu de @code{2.68}. Ce n'est pas un bogue, mais dû au fait que la plupart des fractions de décimaux ne peuvent pas être représentés exactement en nombre a virgule flottante. Voir @ref{1c9d,,Floating-Point Arithmetic; Issues and Limitations} pour plus d'information.
@end quotation
@end cartouche
@end deffn

@anchor{library/functions func-set}@anchor{20e0}
@deffn {Classe} set

@deffnx {Classe} set (iterable)

Renvoie un nouvel @ref{5c3,,ensemble}, dont les éléments sont extraits d'`iterable' s'il est fourni. @code{set} est une classe native. Voir @ref{5c3,,set} et @ref{20fa,,Types d'ensembles — set@comma{} frozenset} pour la documentation de cette classe.

D'autres conteneurs existent, comme : @ref{5c4,,frozenset}, @ref{5fc,,list}, @ref{366,,tuple}, et @ref{253,,dict}, ainsi que le module @ref{1d,,collections}.
@end deffn

@geindex built-in function; setattr()
@anchor{library/functions setattr}@anchor{20e1}
@deffn {Fonction} setattr (object, name, value)

C'est le complément de @ref{bbf,,getattr()}. Les arguments sont : un objet, une chaîne et une valeur de type arbitraire. La chaîne `name' peut désigner un attribut existant ou un nouvel attribut. La fonction assigne la valeur à l'attribut, si l'objet l'autorise. Par exemple, @code{setattr(x, 'foobar', 123)} équivaut à @code{x.foobar = 123}.

`name' n'a pas besoin d'être un identifiant Python tel que défini dans @ref{1e1a,,Identifiants et mots-clés} sauf si l'objet choisit de l'imposer, par exemple en personnalisant @ref{bc0,,__getattribute__()} ou `via' @ref{14a0,,__slots__}. Un attribut dont le nom n'est pas un identifiant ne sera pas accessible en utilisant la notation pointée, mais est accessible `via' @ref{bbf,,getattr()} etc.

@cartouche
@quotation Note 
étant donné que la @ref{1c48,,transformation des noms privés} se produit au moment de la compilation, il faut modifier manuellement le nom d'un attribut privé (attributs avec deux traits de soulignement en tête) afin de le définir avec @ref{20e1,,setattr()}.
@end quotation
@end cartouche
@end deffn

@geindex slice (classe de base)
@anchor{library/functions slice}@anchor{453}
@deffn {Classe} slice (stop)

@deffnx {Classe} slice (start, stop, step=None)

Return a @ref{2106,,slice} object representing the set of indices specified by
@code{range(start, stop, step)}.  The `start' and `step' arguments default to
@code{None}.

@geindex start (attribut slice)
@anchor{library/functions slice start}@anchor{1fd4}
@deffn {Attribut} start
@end deffn

@geindex stop (attribut slice)
@anchor{library/functions slice stop}@anchor{1fd5}
@deffn {Attribut} stop
@end deffn

@geindex step (attribut slice)
@anchor{library/functions slice step}@anchor{1fd6}
@deffn {Attribut} step

Slice objects have read-only data attributes @code{start},
@code{stop}, and @code{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.
@end deffn

Slice objects are also generated when extended indexing syntax is used.  For
example: @code{a[start:stop:step]} or @code{a[start:stop, i]}.  See
@ref{b3a,,itertools.islice()} for an alternate version that returns an
@ref{1aa,,iterator}.


Modifié dans la version 3.12: Slice objects are now @ref{5fb,,hashable} (provided @ref{1fd4,,start},
@ref{1fd5,,stop}, and @ref{1fd6,,step} are hashable).

@end deffn

@geindex built-in function; sorted()
@anchor{library/functions sorted}@anchor{bbc}
@deffn {Fonction} sorted (iterable, /, *, key=None, reverse=False)

Renvoie une nouvelle liste triée depuis les éléments d'`iterable'.

Possède deux arguments optionnels qui doivent être spécifiés par arguments nommés.

`key' spécifie une fonction à un argument utilisée pour extraire une clé de comparaison de chaque élément de l'itérable (par exemple, @code{key=str.lower}). La valeur par défaut est @code{None} (compare les éléments directement).

`reverse' est une valeur booléenne. Si elle est @code{True}, la liste d'éléments est triée comme si toutes les comparaisons étaient inversées.

Utilisez @ref{11b7,,functools.cmp_to_key()} pour convertir l'ancienne notation `cmp' en une fonction `key'.

La fonction native @ref{bbc,,sorted()} est garantie stable. Un tri est stable s'il garantit de ne pas changer l'ordre relatif des éléments égaux entre eux. C'est utile pour trier en plusieurs passes (par exemple par direction puis par salaire).

L'algorithme de tri utilise uniquement l'opérateur @code{<} pour comparer les éléments. Alors que la définition d'une méthode @ref{127d,,__lt__()} est suffisante pour trier, la 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/} recommande que les six @ref{1ff5,,comparaisons riches} soient implémentées. Cela contribue à éviter les bogues lors de l'utilisation des mêmes données avec d'autres outils de tri (tels que @ref{ef4,,max()}) qui reposent sur une méthode sous-jacente différente. L'implémentation des six comparaisons permet également d'éviter toute confusion lors de comparaisons de types mixtes qui peuvent appeler la méthode @ref{12ea,,__gt__()}.

Pour des exemples de tris et un bref tutoriel, consultez @ref{2107,,Sorting Techniques}.
@end deffn

@geindex built-in function; staticmethod()
@anchor{library/functions staticmethod}@anchor{40c}
@deffn {Fonction} @@staticmethod

Transforme une méthode en méthode statique.

Une méthode statique ne reçoit pas de premier argument implicitement. Voici comment déclarer une méthode statique :

@example
class C:
    @@staticmethod
    def f(arg1, arg2, argN): ...
@end example

La forme @code{@@staticmethod} est un @ref{71b,,décorateur} de fonction. Consultez @ref{1bc4,,Définition de fonctions} pour plus de détails.

A static method can be called either on the class (such as @code{C.f()}) or on
an instance (such as @code{C().f()}).
Moreover, the static method @ref{1ef3,,descriptor} is also callable, so it can
be used in the class definition (such as @code{f()}).

Les méthodes statiques en Python sont similaires à celles que l'on trouve en Java ou en C++. Consultez @ref{165,,classmethod()} pour une variante utile permettant de créer des constructeurs alternatifs.

Comme pour tous les décorateurs, il est possible d'appeler @code{staticmethod} comme une simple fonction, et faire quelque chose de son résultat. Ça peut être nécessaire dans le cas où vous souhaitez une référence à la fonction depuis le corps d'une classe, et voulez éviter sa transformation en méthode d'instance. Dans ce cas, faites comme suit :

@example
def regular_function():
    ...

class C:
    method = staticmethod(regular_function)
@end example

Pour plus d'informations sur les méthodes statiques, consultez @ref{1e6a,,Hiérarchie des types standards}.


Modifié dans la version 3.10: Static methods now inherit the method attributes
(@ref{1e81,,__module__}, @ref{12b2,,__name__},
@ref{1e80,,__qualname__}, @ref{11b6,,__doc__} and
@ref{11b5,,__annotations__}), have a new @code{__wrapped__} attribute,
and are now callable as regular functions.

@end deffn

@geindex string;str() (built-in function)

@anchor{library/functions func-str}@anchor{20e2}
@deffn {Classe} str (object='@w{'})

@deffnx {Classe} str (object=b'@w{'}, encoding='utf-8', errors='strict')

Renvoie une version d'`object' sous forme de @ref{435,,str}. Voir @ref{435,,str()} pour plus de détails.

@code{str} est la @ref{18bf,,classe} native des chaînes de caractères. Pour des informations générales à propos des chaînes, consultez @ref{1b8a,,Type Séquence de Texte — str}.
@end deffn

@geindex built-in function; sum()
@anchor{library/functions sum}@anchor{454}
@deffn {Fonction} sum (iterable, /, start=0)

Additionne `start' et les éléments d'un `iterable' de gauche à droite et en donne le total. Les éléments de l'`iterable' sont normalement des nombres, et la valeur de `start' ne peut pas être une chaîne de caractères.

For some use cases, there are good alternatives to @ref{454,,sum()}.
The preferred, fast way to concatenate a sequence of strings is by calling
@code{'@w{'}.join(sequence)}.  To add floating-point values with extended precision,
see @ref{138b,,math.fsum()}.  To concatenate a series of iterables, consider using
@ref{2108,,itertools.chain()}.


Modifié dans la version 3.8: le paramètre `start' peut être passé comme un argument nommé.



Modifié dans la version 3.12: Summation of floats switched to an algorithm
that gives higher accuracy and better commutativity on most builds.

@end deffn

@geindex super (classe de base)
@anchor{library/functions super}@anchor{4c5}
@deffn {Classe} super

@deffnx {Classe} super (type, object_or_type=None)

Renvoie un objet mandataire (`proxy object' en anglais) déléguant les appels de méthode à une classe parente ou sœur de `type'. C'est utile pour accéder aux méthodes héritées qui ont été remplacées dans une classe.

`object_or_type' détermine quel @ref{2109,,ordre de résolution des méthodes} est utilisé pour la recherche. La recherche commence à partir de la classe qui suit immédiatement le `type'.

For example, if @ref{1eae,,__mro__} of `object_or_type' is
@code{D -> B -> C -> A -> object} and the value of `type' is @code{B},
then @ref{4c5,,super()} searches @code{C -> A -> object}.

The @ref{1eae,,__mro__} attribute of the class corresponding to
`object_or_type' lists the method resolution search order used by both
@ref{bbf,,getattr()} and @ref{4c5,,super()}.  The attribute is dynamic and can change
whenever the inheritance hierarchy is updated.

Si le second argument est omis, l'objet `super' obtenu n'est pas lié. Si le second argument est un objet, @code{isinstance(obj, type)} doit être vrai. Si le second argument est un type, @code{issubclass(type2, type)} doit être vrai (c'est utile pour les méthodes de classe).

When called directly within an ordinary method of a class, both arguments may
be omitted ("zero-argument @code{super()}"). In this case, `type' will be the
enclosing class, and `obj' will be the first argument of the immediately
enclosing function (typically @code{self}). (This means that zero-argument
@code{super()} will not work as expected within nested functions, including
generator expressions, which implicitly create nested functions.)

Il existe deux autres cas d'usage typiques pour `super'. Dans une hiérarchie de classes à héritage simple, `super' peut être utilisée pour obtenir la classe parente sans avoir à la nommer explicitement, rendant le code plus maintenable. Cet usage se rapproche de l'usage de `super' dans d'autres langages de programmation.

Le second est la gestion d'héritage multiple coopératif dans un environnement d'exécution dynamique. Cet usage est unique à Python, il ne se retrouve ni dans les langages compilés statiquement, ni dans les langages ne gérant que l'héritage simple. Cela rend possible d'implémenter un héritage en diamant dans lequel plusieurs classes parentes implémentent la même méthode. Une bonne conception implique que ces implémentations doivent avoir la même signature lors de leur appel dans tous les cas (parce que l'ordre des appels est déterminée à l'exécution, parce que l'ordre s'adapte aux changements dans la hiérarchie, et parce que l'ordre peut inclure des classes sœurs inconnues avant l'exécution).

Dans tous les cas, un appel typique à une classe parente ressemble à :

@example
class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)
@end example

En plus de la recherche de méthodes, @ref{4c5,,super()} fonctionne également pour la recherche d'attributs. Un cas d'utilisation possible est l'appel d'un @ref{1ef3,,descripteur} d'une classe parente ou sœur.

Note that @ref{4c5,,super()} is implemented as part of the binding process for
explicit dotted attribute lookups such as @code{super().__getitem__(name)}.
It does so by implementing its own @ref{bc0,,__getattribute__()} method
for searching
classes in a predictable order that supports cooperative multiple inheritance.
Accordingly, @ref{4c5,,super()} is undefined for implicit lookups using statements or
operators such as @code{super()[name]}.

Notez aussi que, en dehors de sa forme sans argument, @ref{4c5,,super()} peut être utilisée en dehors des méthodes. La forme à deux arguments est précise et contient tous les arguments nécessaires, donnant les références appropriées. La forme sans argument fonctionne seulement à l'intérieur d'une définition de classe, puisque c'est le compilateur qui donne les détails nécessaires à propos de la classe en cours de définition, ainsi qu'accéder à l'instance courante pour les méthodes ordinaires.

Pour des suggestions pratiques sur la conception de classes coopératives utilisant @ref{4c5,,super()}, consultez guide to using super()@footnote{http://rhettinger.wordpress.com/2011/05/26/super-considered-super/}.
@end deffn

@anchor{library/functions func-tuple}@anchor{20e3}
@deffn {Classe} tuple

@deffnx {Classe} tuple (iterable)

Ce n'est pas une fonction, @ref{366,,tuple} est en fait un type de séquence immuable, comme documenté dans @ref{206a,,N-uplets} et @ref{1bd7,,Types séquentiels — list@comma{} tuple@comma{} range}.
@end deffn

@geindex type (classe de base)
@anchor{library/functions type}@anchor{d36}
@deffn {Classe} type (object)

@deffnx {Classe} type (name, bases, dict, **kwds)

@geindex object;type

With one argument, return the type of an `object'.  The return value is a
type object and generally the same object as returned by
@ref{1461,,object.__class__}.

La fonction native @ref{42b,,isinstance()} est recommandée pour tester le type d'un objet, car elle prend en compte l'héritage.

With three arguments, return a new type object.  This is essentially a
dynamic form of the @ref{12b5,,class} statement. The `name' string is
the class name and becomes the @ref{145f,,__name__} attribute.
The `bases' tuple contains the base classes and becomes the
@ref{1460,,__bases__} attribute; if empty, @ref{a7a,,object}, the
ultimate base of all classes, is added.  The `dict' dictionary contains
attribute and method definitions for the class body; it may be copied
or wrapped before becoming the @ref{c4b,,__dict__} attribute.
The following two statements create identical @code{type} objects:

@example
>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))
@end example

See also:


@itemize *

@item 
@ref{1ea8,,Documentation on attributes and methods on classes}.

@item 
@ref{210a,,Objets type}
@end itemize

Les arguments nommés fournis à la forme à trois arguments sont passés au mécanisme de métaclasse approprié (généralement @ref{61c,,__init_subclass__()}) de la même manière que les arguments nommés dans une définition de classe (en plus de `metaclass').

Voir aussi @ref{c39,,Personnalisation de la création de classes}.


Modifié dans la version 3.6: Subclasses of @code{type} which don't override @code{type.__new__} may no
longer use the one-argument form to get the type of an object.

@end deffn

@geindex built-in function; vars()
@anchor{library/functions vars}@anchor{19d0}
@deffn {Fonction} vars ()

@deffnx {Fonction} vars (object)

Return the @ref{546,,__dict__} attribute for a module, class, instance,
or any other object with a @code{__dict__} attribute.

Objects such as modules and instances have an updateable @ref{546,,__dict__}
attribute; however, other objects may have write restrictions on their
@code{__dict__} attributes (for example, classes use a
@ref{457,,types.MappingProxyType} to prevent direct dictionary updates).

Without an argument, @ref{19d0,,vars()} acts like @ref{140,,locals()}.

Une exception @ref{522,,TypeError} est levée si un objet est spécifié mais qu'il n'a pas d'attribut @ref{546,,__dict__} (par exemple, si sa classe définit l'attribut @ref{14a0,,__slots__}).


Modifié dans la version 3.13: The result of calling this function without an argument has been
updated as described for the @ref{140,,locals()} builtin.

@end deffn

@geindex built-in function; zip()
@anchor{library/functions zip}@anchor{7ba}
@deffn {Fonction} zip (*iterables, strict=False)

Itère sur plusieurs itérables en parallèle, produisant des `n'-uplets avec un élément provenant de chacun.

Exemple :

@example
>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')
@end example

Plus formellement : @ref{7ba,,zip()} renvoie un itérateur de `n'-uplets, où le `i'@w{^e} `n'-uplet contient le `i'@w{^e} élément de chacun des itérables passés en arguments.

Une autre façon de voir @ref{7ba,,zip()} est qu'elle transforme les lignes en colonnes et les colonnes en lignes, fournissant la matrice transposée@footnote{https://fr.wikipedia.org/wiki/Matrice_transpos%C3%A9e}.

@ref{7ba,,zip()} est paresseuse : les éléments ne sont traités qu'au moment où l'on itère, par exemple avec une boucle @code{for} ou en les plaçant dans une @ref{5fc,,liste}.

Il faut savoir que les itérables passés à @ref{7ba,,zip()} peuvent avoir des longueurs différentes ; parfois par conception, parfois à cause d'un bogue dans le code qui a préparé ces itérables. Python propose trois approches différentes pour traiter ce problème :


@itemize *

@item 
par défaut, @ref{7ba,,zip()} s'arrête lorsque l'itérable le plus court est épuisé. Elle ignore les éléments restants dans les itérables plus longs, coupant le résultat à la longueur de l'itérable le plus court :

@example
>>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
[(0, 'fee'), (1, 'fi'), (2, 'fo')]
@end example

@item 
@ref{7ba,,zip()} est souvent utilisée dans les cas où les itérables sont supposés être de même longueur. Dans ce cas, il est recommandé d'utiliser l'option @code{strict=True}. Cela produit la même chose que la @ref{7ba,,zip()} habituelle :

@example
>>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
[('a', 1), ('b', 2), ('c', 3)]
@end example

Mais, contrairement au comportement par défaut, elle lève une @ref{1ff,,ValueError} si un itérable est épuisé avant les autres :

@example
>>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True):  
...     print(item)
...
(0, 'fee')
(1, 'fi')
(2, 'fo')
Traceback (most recent call last):
  ...
ValueError: zip() argument 2 is longer than argument 1
@end example

@c This doctest is disabled because doctest does not support capturing
@c output and exceptions in the same code unit.
@c https://github.com/python/cpython/issues/65382

Sans l'argument @code{strict=True}, tout bogue entraînant des itérables de longueurs différentes est réduit au silence, se manifestant éventuellement comme un bogue difficile à trouver dans une autre partie du programme.

@item 
les itérables plus courts peuvent être remplis avec une valeur constante pour que tous les itérables aient la même longueur. C'est le cas pour @ref{127b,,itertools.zip_longest()}.
@end itemize

Cas extrêmes : avec un seul argument itérable, @ref{7ba,,zip()} renvoie un itérateur de « 1-uplet ». Sans argument, elle renvoie un itérateur vide.

Trucs et astuces :


@itemize *

@item 
il est garanti que les itérables sont évalués de gauche à droite. Cela rend possible de grouper une séquence de données en groupes de taille `n' via @code{zip(*[iter(s)]*n, strict=True)}. Cela duplique le `même' itérateur @code{n} fois ; par conséquent le `n'-uplet obtenu contient le résultat de @code{n} appels à l'itérateur. Cela a pour effet de diviser la séquence en morceaux de taille `n'.

@item 
@ref{7ba,,zip()} peut être utilisée conjointement avec l'opérateur @code{*} pour dézipper une liste :

@example
>>> x = [1, 2, 3]
>>> y = [4, 5, 6]
>>> list(zip(x, y))
[(1, 4), (2, 5), (3, 6)]
>>> x2, y2 = zip(*zip(x, y))
>>> x == list(x2) and y == list(y2)
True
@end example
@end itemize


Modifié dans la version 3.10: ajout de l'argument @code{strict}.

@end deffn

@geindex built-in function; __import__()
@anchor{library/functions import__}@anchor{8c1}
@deffn {Fonction} __import__ (name, globals=None, locals=None, fromlist=(), level=0)

@geindex statement;import
@geindex module;builtins

@cartouche
@quotation Note 
c'est une fonction avancée qui n'est pas fréquemment nécessaire, contrairement à @ref{501,,importlib.import_module()}.
@end quotation
@end cartouche

Cette fonction est invoquée via l'instruction @ref{5cc,,import}. Elle peut être remplacée (en important le module @ref{12,,builtins} et en y remplaçant @code{builtins.__import__}) afin de changer la sémantique de l'instruction @code{import}, mais c'est extrêmement déconseillé, car il est plus simple d'utiliser des points d'entrée pour les importations (`import hooks', voir la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}) pour le même résultat sans perturber du code s'attendant à trouver l'implémentation par défaut. L'usage direct de @ref{8c1,,__import__()} est aussi déconseillé en faveur de @ref{501,,importlib.import_module()}.

La fonction importe le module `name', utilisant potentiellement `globals' et `locals' pour déterminer comment interpréter le nom dans le contexte d'un paquet. `fromlist' donne le nom des objets ou sous-modules qui devraient être importés du module `name'. L'implémentation standard n'utilise pas l'argument `locals' et n'utilise `globals' que pour déterminer le contexte du paquet de l'instruction @ref{5cc,,import}.

`level' permet de choisir entre importation absolue ou relative. @code{0} (par défaut) force à effectuer uniquement des importations absolues. Une valeur positive indique le nombre de dossiers parents relativement au dossier du module appelant @ref{8c1,,__import__()} (voir la 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/}).

Lorsque la variable `name' est de la forme @code{package.module}, normalement, le paquet de plus haut niveau (le nom jusqu'au premier point) est renvoyé, et `pas' le module nommé par `name'. Cependant, lorsqu'un argument `fromlist' est fourni, le module nommé par `name' est renvoyé.

Par exemple, l'instruction @code{import spam} renvoie un code intermédiaire (`bytecode' en anglais) ressemblant au code suivant :

@example
spam = __import__('spam', globals(), locals(), [], 0)
@end example

L'instruction @code{import spam.ham} appelle :

@example
spam = __import__('spam.ham', globals(), locals(), [], 0)
@end example

Notez comment @ref{8c1,,__import__()} renvoie ici le module de plus haut niveau parce que c'est l'objet lié à un nom par l'instruction @ref{5cc,,import}.

En revanche, l'instruction @code{from spam.ham import eggs, sausage as saus} donne

@example
_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage
@end example

Ici le module @code{spam.ham} est renvoyé par @ref{8c1,,__import__()}. De cet objet, les noms à importer sont récupérés et assignés à leurs noms respectifs.

Si vous voulez simplement importer un module (potentiellement dans un paquet) par son nom, utilisez @ref{501,,importlib.import_module()}.


Modifié dans la version 3.3: les valeurs négatives pour `level' ne sont plus prises en charge (et sa valeur par défaut est 0).



Modifié dans la version 3.9: Quand les options @ref{94a,,-E} ou @ref{94b,,-I} sont précisées dans la ligne de commande, la variable d'environnement 
@geindex PYTHONCASEOK
@geindex variable d'environnement; PYTHONCASEOK
@ref{949,,PYTHONCASEOK} est ignorée.

@end deffn

@subsubheading Notes


@node Constantes natives,Types natifs,Fonctions natives<2>,La bibliothèque standard
@anchor{library/constants doc}@anchor{210b}@anchor{library/constants built-in-constants}@anchor{210c}@anchor{library/constants built-in-consts}@anchor{210d}
@section Constantes natives


Un petit nombre de constantes existent dans le `namespace' natif. Elles sont :

@geindex False (variable de base)
@anchor{library/constants False}@anchor{b25}
@deffn {Données} False

La valeur fausse du type @ref{451,,bool}. Les assignations à @code{False} ne sont pas autorisées et lèvent une @ref{18b,,SyntaxError}.
@end deffn

@geindex True (variable de base)
@anchor{library/constants True}@anchor{bfb}
@deffn {Données} True

La valeur vraie du type @ref{451,,bool}. Les assignations à @code{True} ne sont pas autorisées et lèvent une @ref{18b,,SyntaxError}.
@end deffn

@geindex None (variable de base)
@anchor{library/constants None}@anchor{660}
@deffn {Données} None

An object frequently used to represent the absence of a value, as when
default arguments are not passed to a function. Assignments to @code{None}
are illegal and raise a @ref{18b,,SyntaxError}.
@code{None} is the sole instance of the @ref{83c,,NoneType} type.
@end deffn

@geindex NotImplemented (variable de base)
@anchor{library/constants NotImplemented}@anchor{7bc}
@deffn {Données} NotImplemented

A special value which should be returned by the binary special methods
(e.g. @ref{ae8,,__eq__()}, @ref{127d,,__lt__()}, @ref{1f0f,,__add__()}, @ref{1f22,,__rsub__()},
etc.) to indicate that the operation is not implemented with respect to
the other type; may be returned by the in-place binary special methods
(e.g. @ref{1f14,,__imul__()}, @ref{1f34,,__iand__()}, etc.) for the same purpose.
It should not be evaluated in a boolean context.
@code{NotImplemented} is the sole instance of the @ref{83d,,types.NotImplementedType} type.

@cartouche
@quotation Note 
When a binary (or in-place) method returns @code{NotImplemented} the
interpreter will try the reflected operation on the other type (or some
other fallback, depending on the operator).  If all attempts return
@code{NotImplemented}, the interpreter will raise an appropriate exception.
Incorrectly returning @code{NotImplemented} will result in a misleading
error message or the @code{NotImplemented} value being returned to Python code.

Voir @ref{1e6d,,Implémentation des opérations arithmétiques} pour des exemples.
@end quotation
@end cartouche

@cartouche
@quotation Note 
@code{NotImplementedError} and @code{NotImplemented} are not interchangeable,
even though they have similar names and purposes.
See @ref{225,,NotImplementedError} for details on when to use it.
@end quotation
@end cartouche


Modifié dans la version 3.9: Evaluating @code{NotImplemented} in a boolean context is deprecated. While
it currently evaluates as true, it will emit a @ref{1a3,,DeprecationWarning}.
It will raise a @ref{522,,TypeError} in a future version of Python.

@end deffn

@geindex ...;ellipsis literal

@geindex Ellipsis (variable de base)
@anchor{library/constants Ellipsis}@anchor{210e}
@deffn {Données} Ellipsis

Identique au littéral `points de suspension' ("@code{...}"). Valeur spéciale utilisée principalement de manière conjointe avec la syntaxe de découpage (`slicing') étendu pour les conteneurs personnalisés. @code{Ellipsis} est la seule instance de @ref{83b,,types.EllipsisType}.
@end deffn

@geindex __debug__ (variable de base)
@anchor{library/constants debug__}@anchor{7c4}
@deffn {Données} __debug__

Cette constante est vraie si Python n'a pas été démarré avec une option @ref{da2,,-O}. Voir aussi l'expression @ref{955,,assert}.
@end deffn

@cartouche
@quotation Note 
Les noms @ref{660,,None}, @ref{b25,,False}, @ref{bfb,,True} et @ref{7c4,,__debug__} ne peuvent pas être réassignés (des assignations à ces noms, ou aux noms de leurs attributs, lèvent une @ref{18b,,SyntaxError}), donc ils peuvent être considérés comme des "vraies" constantes.
@end quotation
@end cartouche

@menu
* Constantes ajoutées par le module site:: 

@end menu

@node Constantes ajoutées par le module site,,,Constantes natives
@anchor{library/constants constants-added-by-the-site-module}@anchor{210f}@anchor{library/constants site-consts}@anchor{2110}
@subsection Constantes ajoutées par le module @code{site}


Le module @ref{c6,,site} (qui est importé automatiquement au démarrage, sauf si l'option de ligne de commande @ref{1186,,-S} est donnée ajoute un certain nombre de constantes au `namespace' natif. Elles sont utiles pour l'interpréteur interactif et ne devraient pas être utilisées par des programmes.

@geindex quit (variable de base)
@geindex exit (variable de base)
@anchor{library/constants quit}@anchor{2111}
@deffn {Données} quit (code=None)
@anchor{library/constants exit}@anchor{2112}
@deffnx {Données} exit (code=None)

Objets qui, lorsqu'ils sont représentés, affichent un message comme `"Use quit() or Ctrl-D (i.e. EOF) to exit"', et lorsqu'ils sont appelés, lèvent un @ref{d2e,,SystemExit} avec le code de retour spécifié.
@end deffn


@deffn {Données} help

Object that when printed, prints the message "Type help() for interactive
help, or help(object) for help about object.", and when called,
acts as described @ref{8c4,,elsewhere}.
@end deffn

@geindex copyright (variable de base)
@geindex credits (variable de base)
@anchor{library/constants copyright}@anchor{2113}
@deffn {Données} copyright
@anchor{library/constants credits}@anchor{2114}
@deffnx {Données} credits

Objets qui, lorsqu'ils sont affichés ou appelés, affichent le copyright ou les crédits, respectivement.
@end deffn

@geindex license (variable de base)
@anchor{library/constants license}@anchor{2115}
@deffn {Données} license

Objet qui, lorsqu'il est affiché, affiche un message comme `"Type license() to see the full license text"', et lorsqu'il est appelé, affiche le texte complet de la licence dans un style paginé (un écran à la fois).
@end deffn

@c XXX: reference/datamodel and this have quite a few overlaps!

@node Types natifs,Exceptions natives,Constantes natives,La bibliothèque standard
@anchor{library/stdtypes doc}@anchor{2116}@anchor{library/stdtypes bltin-types}@anchor{2117}@anchor{library/stdtypes built-in-types}@anchor{2118}
@section Types natifs


Les sections suivantes décrivent les types standards intégrés à l'interpréteur.

@geindex built-in;types

Les principaux types natifs sont les numériques, les séquences, les dictionnaires, les classes, les instances et les exceptions.

Certaines classes de collection sont mutables. Les méthodes qui ajoutent, retirent, ou réorganisent leurs éléments sur place, et qui ne renvoient pas un élément spécifique, ne renvoient jamais l'instance de la collection elle-même, mais @code{None}.

Certaines opérations sont prises en charge par plusieurs types d'objets ; en particulier, pratiquement tous les objets peuvent être comparés en égalité, testés en véridicité (valeur booléenne) et convertis en une chaîne de caractères (avec la fonction @ref{7e7,,repr()} ou la fonction légèrement différente @ref{435,,str()}). Cette dernière est implicitement utilisée quand un objet est affiché par la fonction @ref{f60,,print()}.

@menu
* Valeurs booléennes:: 
* Opérations booléennes — and@comma{} or@comma{} not: Opérations booléennes — and or not. 
* Comparaisons: Comparaisons<2>. 
* Types numériques — int@comma{} float@comma{} complex: Types numériques — int float complex. 
* Boolean Type - bool:: 
* Les types itérateurs:: 
* Types séquentiels — list@comma{} tuple@comma{} range: Types séquentiels — list tuple range. 
* Type Séquence de Texte — str:: 
* Séquences Binaires — bytes@comma{} bytearray@comma{} vue mémoire: Séquences Binaires — bytes bytearray vue mémoire. 
* Types d'ensembles — set@comma{} frozenset: Types d'ensembles — set frozenset. 
* Les types de correspondances — dict:: 
* Le type gestionnaire de contexte:: 
* Types d'annotation de type — Alias générique@comma{} Union: Types d'annotation de type — Alias générique Union. 
* Autres types natifs:: 
* Attributs spéciaux:: 
* Limitation de longueur de conversion de chaîne vers un entier:: 

@end menu

@node Valeurs booléennes,Opérations booléennes — and or not,,Types natifs
@anchor{library/stdtypes truth}@anchor{20e4}@anchor{library/stdtypes truth-value-testing}@anchor{2119}
@subsection Valeurs booléennes


@geindex statement;if
@geindex statement;while
@geindex truth;value
@geindex Boolean;operations
@geindex false

Tout objet peut être comparé à une valeur booléenne, typiquement dans une condition @ref{2e7,,if} ou @ref{1b92,,while} ou comme opérande des opérations booléennes ci-dessous.

@geindex true

Par défaut, tout objet est considéré vrai à moins que sa classe définisse soit une méthode @ref{12b3,,__bool__()} renvoyant @code{False} soit une méthode @ref{1ee5,,__len__()} renvoyant zéro lorsqu'elle est appelée avec l'objet. @footnote{
Plus d'informations sur ces méthodes spéciales peuvent être trouvées dans le `Python Reference Manual' (@ref{1ee2,,Personnalisation de base}).
} Voici la majorité des objets natifs considérés comme étant faux :

@geindex None (Built-in object)
@geindex False (Built-in object)


@itemize *

@item 
les constantes définies comme étant fausses : @code{None} et @code{False} ;

@item 
zéro de tout type numérique : @code{0}, @code{0.0}, @code{0j}, @code{Decimal(0)}, @code{Fraction(0, 1)}

@item 
les chaînes et collections vides : @code{'@w{'}}, @code{()}, @code{[]}, @code{@{@}}, @code{set()}, @code{range(0)}
@end itemize

@geindex operator;or
@geindex operator;and
@geindex False
@geindex True

Les opérations et fonctions natives dont le résultat est booléen renvoient toujours @code{0} ou @code{False} pour faux et @code{1} ou @code{True} pour vrai, sauf indication contraire (exception importante : les opérations booléennes @code{or} et @code{and} renvoient toujours l'une de leurs opérandes).

@node Opérations booléennes — and or not,Comparaisons<2>,Valeurs booléennes,Types natifs
@anchor{library/stdtypes boolean}@anchor{211a}@anchor{library/stdtypes boolean-operations-and-or-not}@anchor{211b}
@subsection Opérations booléennes — @code{and}, @code{or}, @code{not}


@geindex Boolean;operations

Ce sont les opérations booléennes, classées par priorité ascendante :


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@tab

Notes

@item

@code{x or y}

@tab

si `x' est vrai, alors `x', sinon `y'

@tab

(1)

@item

@code{x and y}

@tab

si `x' est faux, alors `x', sinon `y'

@tab

(2)

@item

@code{not x}

@tab

si `x' est faux, alors @code{True}, sinon @code{False}

@tab

(3)

@end multitable


@geindex operator;and
@geindex operator;or
@geindex operator;not

Notes :


@enumerate 

@item 
C'est un opérateur court-circuit : il n'évalue le deuxième argument que si le premier est faux.

@item 
C'est un opérateur court-circuit : il n'évalue le deuxième argument que si le premier est vrai.

@item 
@code{not} a une priorité inférieure à celle des opérateurs non-booléens, donc @code{not a == b} est interprété comme @code{not (a == b)} et @code{a == not b} est une erreur de syntaxe.
@end enumerate

@node Comparaisons<2>,Types numériques — int float complex,Opérations booléennes — and or not,Types natifs
@anchor{library/stdtypes comparisons}@anchor{211c}@anchor{library/stdtypes stdcomparisons}@anchor{211d}
@subsection Comparaisons


@geindex chaining;comparisons
@geindex operator;comparison
@geindex operator;==
@geindex operator;< (less)
@geindex operator;<=
@geindex operator;> (greater)
@geindex operator;>=
@geindex operator;!=
@geindex operator;is
@geindex operator;is not

Il y a huit opérations de comparaison en Python. Elles ont toutes la même priorité (qui est supérieure à celle des opérations booléennes). Les comparaisons peuvent être enchaînées arbitrairement ; par exemple, @code{x < y <= z} est équivalent à @code{x < y and y <= z}, sauf que `y' n'est évalué qu'une seule fois (mais dans les deux cas `z' n'est pas évalué du tout quand @code{x < y} est faux).

Ce tableau résume les opérations de comparaison :


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Signification

@item

@code{<}

@tab

strictement inférieur

@item

@code{<=}

@tab

inférieur ou égal

@item

@code{>}

@tab

strictement supérieur

@item

@code{>=}

@tab

supérieur ou égal

@item

@code{==}

@tab

égal

@item

@code{!=}

@tab

différent

@item

@code{is}

@tab

identité d'objet

@item

@code{is not}

@tab

contraire de l'identité d'objet

@end multitable


@geindex object;numeric
@geindex objects;comparing

Vous ne pouvez pas tester l'égalité d'objets de types différents, à l'exception des types numériques entre eux. L'opérateur @code{==} est toujours défini mais pour certains types d'objets (par exemple, les objets de type classe), il est équivalent à @ref{2e9,,is}. Les opérateurs @code{<}, @code{<=}, @code{>} et @code{>=} sont définis seulement quand ils ont un sens. Par exemple, ils lèvent une exception @ref{522,,TypeError} lorsque l'un des arguments est un nombre complexe.

@geindex __eq__() (instance method)
@geindex __ne__() (instance method)
@geindex __lt__() (instance method)
@geindex __le__() (instance method)
@geindex __gt__() (instance method)
@geindex __ge__() (instance method)

Des instances différentes d'une classe sont normalement considérées différentes à moins que la classe ne définisse la méthode @ref{ae8,,__eq__()}.

Les instances d'une classe ne peuvent pas être ordonnées par rapport à d'autres instances de la même classe, ou d'autres types d'objets, à moins que la classe ne définisse suffisamment de méthodes parmi @ref{127d,,__lt__()}, @ref{12e9,,__le__()}, @ref{12ea,,__gt__()} et @ref{12eb,,__ge__()} (en général, @code{__lt__()} et @code{__eq__()} sont suffisantes, si vous voulez les significations classiques des opérateurs de comparaison).

Le comportement des opérateurs @ref{2e9,,is} et @ref{1ffc,,is not} ne peut pas être personnalisé ; aussi ils peuvent être appliqués à deux objets quelconques et ne lèvent jamais d'exception.

@geindex operator;in
@geindex operator;not in

Deux autres opérations avec la même priorité syntaxique, @ref{2e8,,in} et @ref{61a,,not in}, sont pris en charge par les types @ref{1205,,iterable} ou qui implémentent la méthode @ref{1ee0,,__contains__()}.

@node Types numériques — int float complex,Boolean Type - bool,Comparaisons<2>,Types natifs
@anchor{library/stdtypes numeric-types-int-float-complex}@anchor{211e}@anchor{library/stdtypes typesnumeric}@anchor{1b86}
@subsection Types numériques — @code{int}, @code{float}, @code{complex}


@geindex object;numeric
@geindex object;Boolean
@geindex object;integer
@geindex object;floating-point
@geindex object;complex number
@geindex C;language

Il existe trois types numériques distincts : les entiers (`integers'), les nombres flottants (`floating point numbers') et les nombres complexes (`complex numbers'). En outre, les booléens sont un sous-type des entiers. Les entiers ont une précision illimitée. Les nombres à virgule flottante sont généralement implémentés en utilisant des double en C ; des informations sur la précision et la représentation interne des nombres à virgule flottante pour la machine sur laquelle le programme est en cours d'exécution sont disponibles dans @ref{1979,,sys.float_info}. Les nombres complexes ont une partie réelle et une partie imaginaire, qui sont chacune des nombres à virgule flottante. Pour extraire ces parties d'un nombre complexe `z', utilisez @code{z.real} et @code{z.imag}. (La bibliothèque standard comprend les types numériques additionnels @ref{1e4,,fractions.Fraction} pour les rationnels et @ref{29a,,decimal.Decimal} pour les nombres à virgule flottante avec une précision définissable par l'utilisateur.)

@geindex numeric;literals
@geindex integer;literals
@geindex floating-point;literals
@geindex complex number;literals
@geindex hexadecimal;literals
@geindex octal;literals
@geindex binary;literals

Les nombres sont créés par des littéraux numériques ou sont le résultat de fonctions natives ou d'opérateurs. Les entiers littéraux basiques (y compris leur forme hexadécimale, octale et binaire) donnent des entiers. Les nombres littéraux contenant un point décimal (NdT : notation anglo-saxonne de la virgule) ou un exposant donnent des nombres à virgule flottante. Suffixer @code{'j'} ou @code{'J'} à un nombre littéral donne un nombre imaginaire (un nombre complexe avec une partie réelle nulle) que vous pouvez ajouter à un nombre (entier ou à virgule flottante) pour obtenir un nombre complexe avec une partie réelle et une partie imaginaire.

@geindex arithmetic
@geindex built-in function;int
@geindex built-in function;float
@geindex built-in function;complex
@geindex operator;+ (plus)
@geindex + (plus);unary operator
@geindex + (plus);binary operator
@geindex operator;- (minus)
@geindex - (minus);unary operator
@geindex - (minus);binary operator
@geindex operator;* (asterisk)
@geindex operator;/ (slash)
@geindex operator;//
@geindex operator;% (percent)
@geindex operator;**

Python gère pleinement l'arithmétique de types numériques mixtes : lorsqu'un opérateur arithmétique binaire possède des opérandes de types numériques différents, l'opérande de type le plus « étroit » est élargi à celui de l'autre. Dans ce système, l'entier est plus « étroit » que la virgule flottante, qui est plus « étroite » que le complexe. Une comparaison entre des nombres de types différents se comporte comme si les valeurs exactes de ces nombres étaient comparées @footnote{
Par conséquent, la liste @code{[1, 2]} est considérée égale à @code{[1.0, 2.0]}. Idem avec des `n'-uplets.
}.

Les constructeurs @ref{254,,int()}, @ref{2eb,,float()} et @ref{2ec,,complex()} peuvent être utilisés pour produire des nombres d'un type numérique spécifique.

Tous les types numériques (sauf complexe) gèrent les opérations suivantes (pour les priorités des opérations, voir @ref{2015,,Priorités des opérateurs}) :


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@tab

Notes

@tab

Documentation complète

@item

@code{x + y}

@tab

somme de `x' et `y'

@tab

@tab

@item

@code{x - y}

@tab

différence de `x' et `y'

@tab

@tab

@item

@code{x * y}

@tab

produit de `x' et `y'

@tab

@tab

@item

@code{x / y}

@tab

quotient de `x' et `y'

@tab

@tab

@item

@code{x // y}

@tab

quotient entier de `x' et `y'

@tab

(1)(2)

@tab

@item

@code{x % y}

@tab

reste de @code{x / y}

@tab

(2)

@tab

@item

@code{-x}

@tab

négatif de `x'

@tab

@tab

@item

@code{+x}

@tab

`x' inchangé

@tab

@tab

@item

@code{abs(x)}

@tab

valeur absolue de `x'

@tab

@tab

@ref{1c32,,abs()}

@item

@code{int(x)}

@tab

`x' converti en nombre entier

@tab

(3)(6)

@tab

@ref{254,,int()}

@item

@code{float(x)}

@tab

`x' converti en nombre à virgule flottante

@tab

(4)(6)

@tab

@ref{2eb,,float()}

@item

@code{complex(re, im)}

@tab

un nombre complexe avec `re' pour partie réelle et `im' pour partie imaginaire. `im' vaut zéro par défaut.

@tab

(6)

@tab

@ref{2ec,,complex()}

@item

@code{c.conjugate()}

@tab

conjugué du nombre complexe `c'

@tab

@tab

@item

@code{divmod(x, y)}

@tab

la paire @code{(x // y, x % y)}

@tab

(2)

@tab

@ref{98f,,divmod()}

@item

@code{pow(x, y)}

@tab

`x' à la puissance `y'

@tab

(5)

@tab

@ref{9c0,,pow()}

@item

@code{x ** y}

@tab

`x' à la puissance `y'

@tab

(5)

@tab

@end multitable


@geindex operations on;numeric;types
@geindex conjugate() (complex number method)

Notes :


@enumerate 

@item 
Également appelé division entière. Pour les opérandes de type @ref{254,,int}, la valeur résultante est de type @ref{254,,int}. Pour les opérandes de type @ref{2eb,,float},la valeur résultante est de type @ref{2eb,,float}. En général, la valeur résultante est strictement entière,  bien que le type du résultat ne soit pas nécessairement `int'. Le résultat est toujours arrondi vers moins l'infini : @code{1//2} vaut @code{0}, @code{(-1)//2} vaut @code{-1}, @code{1//(-2)} vaut @code{-1}, et @code{(-1)//(-2)} vaut @code{0}.

@item 
Pas pour les nombres complexes. Convertissez-les plutôt en nombres flottants à l'aide de @ref{1c32,,abs()} si c'est approprié.

@item 
@geindex module;math
@geindex floor() (in module math)
@geindex ceil() (in module math)
@geindex trunc() (in module math)
@geindex numeric;conversions

La conversion de @ref{2eb,,float} en @ref{254,,int} tronque la partie fractionnaire. Voir les fonctions @ref{1378,,math.floor()} et @ref{1379,,math.ceil()} pour d'autres conversions.

@item 
`float' accepte aussi les chaînes `nan' et `inf' avec un préfixe optionnel @code{+} ou @code{-} pour `Not a Number' (`NaN') et les infinis positif ou négatif.

@item 
Python définit @code{pow(0, 0)} et @code{0 ** 0} valant @code{1}, puisque c'est courant pour les langages de programmation, et logique.

@item 
Les littéraux numériques acceptés comprennent les chiffres @code{0} à @code{9} ou tout équivalent Unicode (caractères avec la propriété @code{Nd}).

See the Unicode Standard@footnote{https://unicode.org/Public/UNIDATA/extracted/DerivedNumericType.txt}
for a complete list of code points with the @code{Nd} property.
@end enumerate

Tous types @ref{211f,,numbers.Real} (@ref{254,,int} et @ref{2eb,,float}) comprennent également les opérations suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@item

@ref{137a,,math.trunc(x)}

@tab

`x' tronqué à l'@ref{1f3f,,Integral}

@item

@ref{12b8,,round(x[@comma{} n])}

@tab

`x' arrondi à `n' chiffres, arrondissant la moitié au pair. Si `n' est omis, la valeur par défaut est 0.

@item

@ref{1378,,math.floor(x)}

@tab

le plus grand @ref{1f3f,,Integral} ≤ `x'

@item

@ref{1379,,math.ceil(x)}

@tab

le plus petit @ref{1f3f,,Integral} ≥ `x'

@end multitable


Pour d'autres opérations numériques voir les modules @ref{8d,,math} et @ref{18,,cmath}.

@c XXXJH exceptions: overflow (when? what operations?) zerodivision

@menu
* Opérations sur les bits des nombres entiers:: 
* Méthodes supplémentaires sur les entiers:: 
* Méthodes supplémentaires sur les nombres à virgule flottante:: 
* Hachage des types numériques:: 

@end menu

@node Opérations sur les bits des nombres entiers,Méthodes supplémentaires sur les entiers,,Types numériques — int float complex
@anchor{library/stdtypes bitstring-ops}@anchor{2120}@anchor{library/stdtypes bitwise-operations-on-integer-types}@anchor{2121}
@subsubsection Opérations sur les bits des nombres entiers


@geindex operations on;integer;types
@geindex bitwise;operations
@geindex shifting;operations
@geindex masking;operations
@geindex operator;| (vertical bar)
@geindex operator;^ (caret)
@geindex operator;& (ampersand)
@geindex operator;<<
@geindex operator;>>
@geindex operator;~ (tilde)

Les opérations bit à bit n'ont de sens que pour les entiers relatifs. Le résultat d'une opération bit à bit est calculé comme si elle était effectuée en complément à deux avec un nombre infini de bits de signe.

Les priorités de toutes les opérations bit à bit à deux opérandes sont inférieures à celles des opérations numériques et plus élevées que les comparaisons ; l'opération unaire @code{~} a la même priorité que les autres opérations numériques unaires (@code{+} et @code{-}).

Ce tableau répertorie les opérations binaires triées par priorité ascendante :


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@tab

Notes

@item

@code{x | y}

@tab

`OU' bit à bit de `x' et `y'

@tab

(4)

@item

@code{x ^ y}

@tab

`OU exclusif' bit à bit de `x' et `y'

@tab

(4)

@item

@code{x & y}

@tab

`ET' bit à bit de `x' et `y'

@tab

(4)

@item

@code{x << n}

@tab

`x' décalé vers la gauche de `n' bits

@tab

(1)(2)

@item

@code{x >> n}

@tab

`x' décalé vers la droite de `n' bits

@tab

(1)(3)

@item

@code{~x}

@tab

les bits de `x', inversés

@tab

@end multitable


Notes :


@enumerate 

@item 
Des valeurs de décalage négatives sont illégales et provoquent une exception @ref{1ff,,ValueError}.

@item 
Un décalage à gauche de `n' bits est équivalent à la multiplication par @code{pow(2, n)}.

@item 
Un décalage à droite de `n' les bits est équivalent à la division par @code{pow(2, n)}.

@item 
Effectuer ces calculs avec au moins un bit d'extension de signe supplémentaire dans une représentation finie du complément à deux éléments (une largeur de bit fonctionnelle de @code{1 + max(x.bit_length(), y.bit_length()} ou plus) est suffisante pour obtenir le même résultat que s'il y avait un nombre infini de bits de signe.
@end enumerate

@node Méthodes supplémentaires sur les entiers,Méthodes supplémentaires sur les nombres à virgule flottante,Opérations sur les bits des nombres entiers,Types numériques — int float complex
@anchor{library/stdtypes additional-methods-on-integer-types}@anchor{2122}
@subsubsection Méthodes supplémentaires sur les entiers


Le type `int' implémente la @ref{1193,,classe mère abstraite} @ref{1f3f,,numbers.Integral}. Il fournit aussi quelques autres méthodes :

@geindex bit_length() (méthode int)
@anchor{library/stdtypes int bit_length}@anchor{2123}
@deffn {Méthode} int.bit_length ()

Renvoie le nombre de bits nécessaires pour représenter un nombre entier en binaire, à l'exclusion du signe et des zéros non significatifs :

@example
>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6
@end example

Plus précisément, si @code{x} est différent de zéro, @code{x.bit_length()} est le nombre entier positif unique, @code{k} tel que @code{2**(k-1) <= abs(x) < 2**k}. Équivalemment, quand @code{abs(x)} est assez petit pour avoir un logarithme correctement arrondi, @code{k = 1 + int(log(abs(x), 2))}. Si @code{x} est nul, alors @code{x.bit_length()} donne @code{0}.

Équivalent à :

@example
def bit_length(self):
    s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # remove leading zeros and minus sign
    return len(s)       # len('100101') --> 6
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex bit_count() (méthode int)
@anchor{library/stdtypes int bit_count}@anchor{7b6}
@deffn {Méthode} int.bit_count ()

Renvoie le nombre de 1 dans la représentation binaire de la valeur absolue de l'entier. On la connait également sous le nom de dénombrement de la population. Par exemple :

@example
>>> n = 19
>>> bin(n)
'0b10011'
>>> n.bit_count()
3
>>> (-n).bit_count()
3
@end example

Équivalent à :

@example
def bit_count(self):
    return bin(self).count("1")
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex to_bytes() (méthode int)
@anchor{library/stdtypes int to_bytes}@anchor{181d}
@deffn {Méthode} int.to_bytes (length=1, byteorder='big', *, signed=False)

Renvoie un tableau d'octets représentant un nombre entier.

@example
>>> (1024).to_bytes(2, byteorder='big')
b'\x04\x00'
>>> (1024).to_bytes(10, byteorder='big')
b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00'
>>> (-1024).to_bytes(10, byteorder='big', signed=True)
b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00'
>>> x = 1000
>>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little')
b'\xe8\x03'
@end example

L'entier est représenté en utilisant `length' octets, dont la valeur par défaut est 1. Une exception @ref{86d,,OverflowError} est levée s'il n'est pas possible de représenter l'entier avec le nombre donné d'octets.

L'argument `byteorder' détermine l'ordre des octets utilisé pour représenter le nombre entier, la valeur par défaut étant @code{"big"}. Si `byteorder' est @code{"big"}, l'octet le plus significatif est au début du tableau d'octets. Si `byteorder' est @code{"little"}, l'octet le plus significatif est à la fin du tableau d'octets.

L'argument `signed' détermine si le complément à deux est utilisé pour représenter le nombre entier. Si `signed' est @code{False} et qu'un entier négatif est donné, une exception @ref{86d,,OverflowError} est levée. La valeur par défaut pour `signed' est @code{False}.

Les valeurs par défaut peuvent être utilisées pour transformer facilement un entier en un objet à un seul octet :

@example
>>> (65).to_bytes()
b'A'
@end example

Cependant, lorsque vous utilisez les arguments par défaut, n'essayez pas de convertir une valeur supérieure à 255 ou vous lèverez une @ref{86d,,OverflowError} :

Équivalent à :

@example
def to_bytes(n, length=1, byteorder='big', signed=False):
    if byteorder == 'little':
        order = range(length)
    elif byteorder == 'big':
        order = reversed(range(length))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    return bytes((n >> i*8) & 0xff for i in order)
@end example


Ajouté dans la version 3.2.



Modifié dans la version 3.11: ajout de valeurs par défaut pour les arguments @code{length} et @code{byteorder}.

@end deffn

@geindex from_bytes() (méthode de la classe int)
@anchor{library/stdtypes int from_bytes}@anchor{17dd}
@deffn {Méthode} classmethod int.from_bytes (bytes, byteorder='big', *, signed=False)

Renvoie le nombre entier représenté par le tableau d'octets fourni.

@example
>>> int.from_bytes(b'\x00\x10', byteorder='big')
16
>>> int.from_bytes(b'\x00\x10', byteorder='little')
4096
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True)
-1024
>>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False)
64512
>>> int.from_bytes([255, 0, 0], byteorder='big')
16711680
@end example

L'argument `bytes' doit être soit un @ref{d1b,,objet octet-compatible}, soit un itérable produisant des `bytes'.

L'argument `byteorder' détermine l'ordre des octets utilisé pour représenter le nombre entier, la valeur par défaut étant @code{"big"}. Si `byteorder' est @code{"big"}, l'octet le plus significatif est au début du tableau d'octets. Si `byteorder' est @code{"little"}, l'octet le plus significatif est à la fin du tableau d'octets. Pour demander l'ordre natif des octets du système hôte, donnez @ref{2124,,sys.byteorder} comme `byteorder'.

L'argument `signed' indique si le complément à deux est utilisé pour représenter le nombre entier.

Équivalent à :

@example
def from_bytes(bytes, byteorder='big', signed=False):
    if byteorder == 'little':
        little_ordered = list(bytes)
    elif byteorder == 'big':
        little_ordered = list(reversed(bytes))
    else:
        raise ValueError("byteorder must be either 'little' or 'big'")

    n = sum(b << i*8 for i, b in enumerate(little_ordered))
    if signed and little_ordered and (little_ordered[-1] & 0x80):
        n -= 1 << 8*len(little_ordered)

    return n
@end example


Ajouté dans la version 3.2.



Modifié dans la version 3.11: ajout de la valeur par défaut pour l'argument @code{byteorder}.

@end deffn

@geindex as_integer_ratio() (méthode int)
@anchor{library/stdtypes int as_integer_ratio}@anchor{9b9}
@deffn {Méthode} int.as_integer_ratio ()

Return a pair of integers whose ratio is equal to the original
integer and has a positive denominator.  The integer ratio of integers
(whole numbers) is always the integer as the numerator and @code{1} as the
denominator.


Ajouté dans la version 3.8.

@end deffn

@geindex is_integer() (méthode int)
@anchor{library/stdtypes int is_integer}@anchor{1709}
@deffn {Méthode} int.is_integer ()

Returns @code{True}. Exists for duck type compatibility with @ref{2125,,float.is_integer()}.


Ajouté dans la version 3.12.

@end deffn

@node Méthodes supplémentaires sur les nombres à virgule flottante,Hachage des types numériques,Méthodes supplémentaires sur les entiers,Types numériques — int float complex
@anchor{library/stdtypes additional-methods-on-float}@anchor{2126}
@subsubsection Méthodes supplémentaires sur les nombres à virgule flottante


Le type `float' implémente la @ref{1193,,classe mère abstraite} @ref{211f,,numbers.Real} et a également les méthodes suivantes.

@geindex as_integer_ratio() (méthode float)
@anchor{library/stdtypes float as_integer_ratio}@anchor{1c9e}
@deffn {Méthode} float.as_integer_ratio ()

Return a pair of integers whose ratio is exactly equal to the
original float. The ratio is in lowest terms and has a positive denominator.  Raises
@ref{86d,,OverflowError} on infinities and a @ref{1ff,,ValueError} on
NaNs.
@end deffn

@geindex is_integer() (méthode float)
@anchor{library/stdtypes float is_integer}@anchor{2125}
@deffn {Méthode} float.is_integer ()

Renvoie @code{True} si l'instance de `float' est finie avec une valeur entière, et @code{False} autrement :

@example
>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False
@end example
@end deffn

Deux méthodes prennent en charge la conversion vers et à partir de chaînes hexadécimales. Étant donné que les `float' de Python sont stockés en interne sous forme de nombres binaires, la conversion d'un `float' depuis ou vers une chaine décimale implique généralement une petite erreur d'arrondi. En revanche, les chaînes hexadécimales permettent de représenter exactement les nombres à virgule flottante. Cela peut être utile lors du débogage, et dans un travail numérique.

@geindex hex() (méthode float)
@anchor{library/stdtypes float hex}@anchor{1c9f}
@deffn {Méthode} float.hex ()

Renvoie une représentation d'un nombre à virgule flottante sous forme de chaîne hexadécimale. Pour les nombres à virgule flottante finis, cette représentation comprendra toujours un préfixe @code{0x}, un suffixe @code{p} et un exposant.
@end deffn

@geindex fromhex() (méthode de la classe float)
@anchor{library/stdtypes float fromhex}@anchor{2127}
@deffn {Méthode} classmethod float.fromhex (s)

Méthode de classe pour obtenir le `float' représenté par une chaîne de caractères hexadécimale `s'. La chaîne `s' peut contenir des espaces avant et après le nombre.
@end deffn

Notez que @ref{1c9f,,float.hex()} est une méthode d'instance, alors que @ref{2127,,float.fromhex()} est une méthode de classe.

Une chaîne hexadécimale prend la forme :

@example
[sign] ['0x'] integer ['.' fraction] ['p' exponent]
@end example

où @code{sign} peut être soit @code{+} soit @code{-}, @code{integer} et @code{fraction} sont des chaînes de chiffres hexadécimaux, et @code{exponent} est un entier décimal facultativement signé. La casse n'est pas significative, et il doit y avoir au moins un chiffre hexadécimal soit dans le nombre entier soit dans la fraction. Cette syntaxe est similaire à la syntaxe spécifiée dans la section 6.4.4.2 de la norme C99, et est aussi la syntaxe utilisée à partir de Java 1.5. En particulier, la sortie de @ref{1c9f,,float.hex()} est utilisable comme valeur hexadécimale à virgule flottante littérale en C ou Java, et des chaînes hexadécimales produites en C via un format @code{%a} ou Java via @code{Double.toHexString} sont acceptées par @ref{2127,,float.fromhex()}.

Notez que l'exposant est écrit en décimal plutôt qu'en hexadécimal, et qu'il donne la puissance de 2 par lequel multiplier le coefficient. Par exemple, la chaîne hexadécimale @code{0x3.a7p10} représente le nombre à virgule flottante @code{(3 + 10./16 + 7./16**2) *2.0**10}, ou @code{3740.0} :

@example
>>> float.fromhex('0x3.a7p10')
3740.0
@end example

L'application de la conversion inverse à @code{3740.0} donne une chaîne hexadécimale différente représentant le même nombre :

@example
>>> float.hex(3740.0)
'0x1.d380000000000p+11'
@end example

@node Hachage des types numériques,,Méthodes supplémentaires sur les nombres à virgule flottante,Types numériques — int float complex
@anchor{library/stdtypes hashing-of-numeric-types}@anchor{2128}@anchor{library/stdtypes numeric-hash}@anchor{2129}
@subsubsection Hachage des types numériques


For numbers @code{x} and @code{y}, possibly of different types, it's a requirement
that @code{hash(x) == hash(y)} whenever @code{x == y} (see the @ref{ae9,,__hash__()}
method documentation for more details).  For ease of implementation and
efficiency across a variety of numeric types (including @ref{254,,int},
@ref{2eb,,float}, @ref{29a,,decimal.Decimal} and @ref{1e4,,fractions.Fraction})
Python's hash for numeric types is based on a single mathematical function
that's defined for any rational number, and hence applies to all instances of
@ref{254,,int} and @ref{1e4,,fractions.Fraction}, and all finite instances of
@ref{2eb,,float} and @ref{29a,,decimal.Decimal}.  Essentially, this function is
given by reduction modulo @code{P} for a fixed prime @code{P}.  The value of @code{P} is
made available to Python as the @ref{212a,,modulus} attribute of
@ref{fe8,,sys.hash_info}.

`Particularité de l'implémentation CPython :' actuellement, le premier utilisé est @code{P = 2 ** 31 - 1} sur des machines dont les `longs' en C sont de 32 bits @code{P = 2 ** 61 - 1} sur des machines dont les `longs' en C font 64 bits.

Voici les règles en détail :


@itemize -

@item 
Si @code{x = m / n} est un nombre rationnel non négatif et @code{n} n'est pas divisible par @code{P}, définir @code{hash(x)} comme @code{m * invmod(n, P) % P}, où @code{invmod(n, P)} donne l'inverse de @code{n} modulo @code{P}.

@item 
Si @code{x = m / n} est un nombre rationnel non négatif et @code{n} est divisible par @code{P} (mais @code{m} ne l'est pas), alors @code{n} n'a pas de modulo inverse @code{P} et la règle ci-dessus n'est pas applicable ; dans ce cas définir @code{hash(x)} comme étant la valeur de la constante @code{sys.hash_info.inf}.

@item 
Si @code{x = m / n} est un nombre rationnel négatif définir @code{hash(x)} comme @code{-hash(-x)}. Si le résultat est @code{-1}, le remplacer par @code{-2}.

@item 
Les valeurs particulières @code{sys.hash_info.inf} et @code{-sys.hash_info.inf} sont utilisées comme valeurs de hachage pour l'infini positif et l'infini négatif (respectivement).

@item 
Pour un nombre @ref{2ec,,complexe} @code{z}, les valeurs de hachage des parties réelles et imaginaires sont combinées en calculant @code{hash(z.real) + sys.hash_info.imag * hash(z.imag)}, réduit au modulo @code{2**sys.hash_info.width} de sorte qu'il se trouve dans @code{range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - 1))}. Encore une fois, si le résultat est @code{-1}, il est remplacé par @code{-2}.
@end itemize

Afin de clarifier les règles ci-dessus, voici quelques exemples de code Python, équivalent à la fonction de hachage native, pour calculer le hachage d'un nombre rationnel,  d'un @ref{2eb,,float}, ou d'un @ref{2ec,,complex} :

@example
import sys, math

def hash_fraction(m, n):
    """Compute the hash of a rational number m / n.

    Assumes m and n are integers, with n positive.
    Equivalent to hash(fractions.Fraction(m, n)).

    """
    P = sys.hash_info.modulus
    # Remove common factors of P.  (Unnecessary if m and n already coprime.)
    while m % P == n % P == 0:
        m, n = m // P, n // P

    if n % P == 0:
        hash_value = sys.hash_info.inf
    else:
        # Fermat's Little Theorem: pow(n, P-1, P) is 1, so
        # pow(n, P-2, P) gives the inverse of n modulo P.
        hash_value = (abs(m) % P) * pow(n, P - 2, P) % P
    if m < 0:
        hash_value = -hash_value
    if hash_value == -1:
        hash_value = -2
    return hash_value

def hash_float(x):
    """Compute the hash of a float x."""

    if math.isnan(x):
        return object.__hash__(x)
    elif math.isinf(x):
        return sys.hash_info.inf if x > 0 else -sys.hash_info.inf
    else:
        return hash_fraction(*x.as_integer_ratio())

def hash_complex(z):
    """Compute the hash of a complex number z."""

    hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag)
    # do a signed reduction modulo 2**sys.hash_info.width
    M = 2**(sys.hash_info.width - 1)
    hash_value = (hash_value & (M - 1)) - (hash_value & M)
    if hash_value == -1:
        hash_value = -2
    return hash_value
@end example
@anchor{library/stdtypes bltin-boolean-values}@anchor{212b}
@node Boolean Type - bool,Les types itérateurs,Types numériques — int float complex,Types natifs
@anchor{library/stdtypes boolean-type-bool}@anchor{212c}@anchor{library/stdtypes typebool}@anchor{20e5}
@subsection Boolean Type - @code{bool}


Booleans represent truth values. The @ref{451,,bool} type has exactly two
constant instances: @code{True} and @code{False}.

@geindex False
@geindex True
@geindex Boolean;values

The built-in function @ref{451,,bool()}  converts any value to a boolean, if the
value can be interpreted as a truth value (see section @ref{20e4,,Valeurs booléennes} above).

For logical operations, use the @ref{211a,,boolean operators} @code{and},
@code{or} and @code{not}.
When applying the bitwise operators @code{&}, @code{|}, @code{^} to two booleans, they
return a bool equivalent to the logical operations "and", "or", "xor". However,
the logical operators @code{and}, @code{or} and @code{!=} should be preferred
over @code{&}, @code{|} and @code{^}.


Obsolète depuis la version 3.12: The use of the bitwise inversion operator @code{~} is deprecated and will
raise an error in Python 3.16.


@ref{451,,bool} is a subclass of @ref{254,,int} (see @ref{1b86,,Types numériques — int@comma{} float@comma{} complex}). In
many numeric contexts, @code{False} and @code{True} behave like the integers 0 and 1, respectively.
However, relying on this is discouraged; explicitly convert using @ref{254,,int()}
instead.

@node Les types itérateurs,Types séquentiels — list tuple range,Boolean Type - bool,Types natifs
@anchor{library/stdtypes iterator-types}@anchor{212d}@anchor{library/stdtypes typeiter}@anchor{20fc}
@subsection Les types itérateurs


@geindex iterator protocol
@geindex protocol;iterator
@geindex sequence;iteration
@geindex container;iteration over

Python gère un concept d'itération sur les conteneurs. Il l'implémente en utilisant deux méthodes distinctes qui permettent aux classes définies par l'utilisateur de devenir itérables. Les séquences, décrites plus bas en détail, savent toujours gérer les méthodes d'itération.

Une méthode doit être définie afin que les objets conteneurs prennent en charge @ref{1205,,l’itération} :

@c XXX duplicated in reference/datamodel!

@geindex __iter__() (méthode container)
@anchor{library/stdtypes container __iter__}@anchor{1c4e}
@deffn {Méthode} container.__iter__ ()

Renvoie un objet @ref{1aa,,itérateur}. L'objet doit implémenter le protocole d'itération décrit ci-dessous. Si un conteneur prend en charge différents types d'itération, d'autres méthodes peuvent être fournies pour obtenir spécifiquement les itérateurs pour ces types d'itération. (Exemple d'un objet gérant plusieurs formes d'itération : une structure d'arbre pouvant être parcourue en largeur ou en profondeur.) Cette méthode correspond à l'attribut @ref{14a4,,tp_iter} de la structure du type des objets Python dans l'API Python/C.
@end deffn

Les itérateurs eux-mêmes doivent implémenter les deux méthodes suivantes, qui forment ensemble le `protocole d'itération' :

@geindex __iter__() (méthode iterator)
@anchor{library/stdtypes iterator __iter__}@anchor{1c51}
@deffn {Méthode} iterator.__iter__ ()

Renvoie @ref{1aa,,l’objet itérateur} lui-même. C'est nécessaire pour permettre à la fois à des conteneurs et des itérateurs d'être utilisés avec les instructions @ref{2e6,,for} et @ref{2e8,,in}. Cette méthode correspond à l'attribut @ref{14a4,,tp_iter} de la structure des types des objets Python dans l'API Python/C.
@end deffn

@geindex __next__() (méthode iterator)
@anchor{library/stdtypes iterator __next__}@anchor{12ab}
@deffn {Méthode} iterator.__next__ ()

Renvoie l'élément suivant de l’@ref{1aa,,itérateur}. S'il n'y a pas d'autres éléments, une exception @ref{be8,,StopIteration} est levée. Cette méthode correspond à l'attribut @ref{14a5,,tp_iternext} de la structure du type des objets Python dans l'API Python/C.
@end deffn

Python définit plusieurs objets itérateurs pour itérer sur les types standards ou spécifiques de séquence, de  dictionnaires et d'autres formes plus spécialisées. Les types spécifiques ne sont  pas importants au-delà de leur implémentation du protocole d'itération.

Dès que la méthode @ref{12ab,,__next__()} lève une  exception @ref{be8,,StopIteration}, elle doit continuer à le faire lors des appels ultérieurs. Les implémentations qui ne respectent pas cette propriété sont considérées cassées.

@menu
* Types générateurs:: 

@end menu

@node Types générateurs,,,Les types itérateurs
@anchor{library/stdtypes generator-types}@anchor{212e}@anchor{library/stdtypes id3}@anchor{212f}
@subsubsection Types générateurs


Python's @ref{104a,,generator}s provide a convenient way to implement the iterator
protocol.  If a container object's @ref{1c51,,__iter__()} method is implemented as a
generator, it will automatically return an iterator object (technically, a
generator object) supplying the @code{__iter__()} and @ref{1c52,,__next__()}
methods.
More information about generators can be found in @ref{1fb6,,the documentation for the yield expression}.

@node Types séquentiels — list tuple range,Type Séquence de Texte — str,Les types itérateurs,Types natifs
@anchor{library/stdtypes sequence-types-list-tuple-range}@anchor{2130}@anchor{library/stdtypes typesseq}@anchor{1bd7}
@subsection Types séquentiels — @code{list}, @code{tuple}, @code{range}


Il existe trois types séquentiels élémentaires : les listes (objets `list'), `n'-uplets (objets `tuple') et les intervalles (objets `range'). D'autres types séquentiels spécifiques au traitement de @ref{20e8,,données binaires} et @ref{1b8a,,chaînes de caractères} sont décrits dans des sections dédiées.

@menu
* Opérations communes sur les séquences:: 
* Types de séquences immuables:: 
* Types de séquences mutables:: 
* Listes: Listes<2>. 
* N-uplets:: 
* Ranges:: 

@end menu

@node Opérations communes sur les séquences,Types de séquences immuables,,Types séquentiels — list tuple range
@anchor{library/stdtypes common-sequence-operations}@anchor{2131}@anchor{library/stdtypes typesseq-common}@anchor{2132}
@subsubsection Opérations communes sur les séquences


@geindex object;sequence

Les opérations dans le tableau ci-dessous sont prises en charge par la plupart des types séquentiels, variables et immuables. La classe mère abstraite @ref{11a1,,collections.abc.Sequence} est fournie pour aider à implémenter correctement ces opérations sur les types séquentiels personnalisés.

Ce tableau répertorie les opérations sur les séquences  triées par priorité ascendante. Dans le tableau, `s' et `t' sont des séquences du même type, `n', `i', `j' et `k' sont des nombres entiers et `x' est un objet arbitraire qui répond à toutes les restrictions de type et de valeur imposée par `s'.

Les opérations @code{in} et @code{not in} ont les mêmes priorités que les opérations de comparaison. Les opérations @code{+} (concaténation) et @code{*} (répétition) ont la même priorité que les opérations numériques correspondantes @footnote{
Nécessairement, puisque l'analyseur ne peut pas discerner le type des opérandes.
}.

@geindex operations on;sequence;types
@geindex built-in function;len
@geindex built-in function;min
@geindex built-in function;max
@geindex concatenation;operation
@geindex repetition;operation
@geindex subscript;operation
@geindex slice;operation
@geindex operator;in
@geindex operator;not in
@geindex count() (sequence method)
@geindex index() (sequence method)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@tab

Notes

@item

@code{x in s}

@tab

@code{True} si un élément de `s' est égal à `x', sinon @code{False}

@tab

(1)

@item

@code{x not in s}

@tab

@code{False} si un élément de `s' est égal à `x', sinon @code{True}

@tab

(1)

@item

@code{s + t}

@tab

la concaténation de `s' et `t'

@tab

(6)(7)

@item

@code{s * n} ou @code{n * s}

@tab

équivalent à ajouter `s' `n' fois à lui-même

@tab

(2)(7)

@item

@code{s[i]}

@tab

`i'@w{^e} élément de `s' en commençant par 0

@tab

(3)

@item

@code{s[i:j]}

@tab

tranche (`slice') de `s' de `i' à `j'

@tab

(3)(4)

@item

@code{s[i:j:k]}

@tab

tranche (`slice') de `s' de `i' à `j' avec un pas de `k'

@tab

(3)(5)

@item

@code{len(s)}

@tab

longueur de `s'

@tab

@item

@code{min(s)}

@tab

plus petit élément de `s'

@tab

@item

@code{max(s)}

@tab

plus grand élément de `s'

@tab

@item

@code{s.index(x[, i[, j]])}

@tab

indice de la première occurrence de `x' dans `s' (à ou après l'indice `i' et avant l'indice `j')

@tab

(8)

@item

@code{s.count(x)}

@tab

nombre total d'occurrences de `x' dans `s'

@tab

@end multitable


Les séquences du même type gèrent également la comparaison. En particulier, les `n'-uplets et les listes sont comparés lexicographiquement en comparant les éléments correspondants. Cela signifie que, pour que deux séquences soit égales, les éléments les constituant doivent être égaux deux à deux et les deux séquences doivent être du même type et de la même longueur. (Pour plus de détails voir @ref{1ff5,,Comparaisons} dans la référence du langage.)

@geindex loop;over mutable sequence
@geindex mutable sequence;loop over

Les itérateurs avant et arrière sur des séquences modifiables accèdent aux valeurs à l'aide d'un indice. Cet indice continue à avancer (ou à reculer) même si la séquence sous-jacente est modifiée. L'itérateur ne se termine que lorsqu'une @ref{14eb,,IndexError} ou une @ref{be8,,StopIteration} est rencontrée (ou lorsque l'indice tombe en dessous de zéro).

Notes :


@enumerate 

@item 
Bien que les opérations @code{in} et @code{not in} ne soient généralement utilisées que pour les tests d'appartenance simple, certaines séquences spécialisées (telles que @ref{435,,str}, @ref{1bd,,bytes} et @ref{528,,bytearray}) les utilisent aussi pour tester l'existence de sous-séquences :

@example
>>> "gg" in "eggs"
True
@end example

@item 
Les valeurs de `n' plus petites que @code{0} sont traitées comme @code{0} (ce qui donne une séquence vide du même type que `s'). Notez que les éléments de `s' ne sont pas copiés ; ils sont référencés plusieurs fois. Cela hante souvent de nouveaux développeurs Python, typiquement :

@example
>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]
@end example

Ce qui est arrivé est que @code{[[]]} est une liste à un élément contenant une liste vide, de sorte que les trois éléments de @code{[[]] * 3} sont des références à cette seule liste vide. Modifier l'un des éléments de @code{lists} modifie cette liste unique. Vous pouvez créer une liste des différentes listes de cette façon :

@example
>>> lists = [[] for i in range(3)]
>>> lists[0].append(3)
>>> lists[1].append(5)
>>> lists[2].append(7)
>>> lists
[[3], [5], [7]]
@end example

De plus amples explications sont disponibles dans la FAQ à la question @ref{2133,,Comment créer une liste à plusieurs dimensions ?}.

@item 
Si `i' ou `j' sont négatifs, l'indice est relatif à la fin de la séquence `s' : @code{len(s) + i} ou @code{len(s) + j} est substitué. Mais notez que @code{-0} est toujours @code{0}.

@item 
La tranche de `s' de `i' à `j' est définie comme la séquence d'éléments d'indices `k' tels que @code{i <= k < j}. Si `i' ou `j' est supérieur à @code{len(s)}, @code{len(s)} est utilisé. Si `i' est omis ou @code{None}, @code{0} est utilisé. Si `j' est omis ou @code{None}, @code{len(s)} est utilisé. Si `i' est supérieur ou égal à `j', la tranche est vide.

@item 
La tranche de `s' de `i' à `j' avec un pas de `k' est définie comme la séquence d'éléments d'indices @code{x = i + n*k} tels que @code{0 <= n < (j-i)/k}. En d'autres termes, les indices sont @code{i}, @code{i+k}, @code{i+2*k}, @code{i+3*k} et ainsi de suite, en arrêtant lorsque `j' est atteint (mais jamais inclus). Si `k' est positif, `i' et `j' sont réduits, s'ils sont plus grands, à @code{len(s)}. Si `k' est négatif, `i' et `j' sont réduits à @code{len(s) - 1} s'ils sont plus grands. Si `i' ou `j' sont omis ou sont @code{None}, ils deviennent des valeurs « limites » (la limite haute ou basse dépend du signe de `k'). Notez que `k' ne peut pas valoir zéro. Si `k' est @code{None}, il est traité comme @code{1}.

@item 
Concaténer des séquences immuables donne toujours un nouvel objet. Cela signifie que la construction d'une séquence par concaténations répétées aura une durée d'exécution quadratique par rapport à la longueur de la séquence totale. Pour obtenir un temps d'exécution linéaire, vous devez utiliser l'une des alternatives suivantes :


@itemize *

@item 
si vous concaténez des @ref{435,,str}, vous pouvez construire une liste puis utiliser @ref{2134,,str.join()} à la fin, ou bien écrire dans une instance de @ref{f12,,io.StringIO} et récupérer sa valeur lorsque vous avez terminé ;

@item 
si vous concaténez des @ref{1bd,,bytes}, vous pouvez aussi utiliser @ref{2135,,bytes.join()} ou @ref{e8d,,io.BytesIO}, ou vous pouvez faire les concaténations sur place avec un objet @ref{528,,bytearray}. Les objets @ref{528,,bytearray} sont mutables et ont un mécanisme de sur-allocation efficace ;

@item 
si vous concaténez des @ref{366,,n-uplets}, utilisez plutôt `extend' sur une @ref{5fc,,list} ;

@item 
pour les autres types, cherchez dans la documentation de la classe concernée.
@end itemize

@item 
Certains types séquentiels (tels que @ref{930,,range}) ne gèrent que des séquences qui suivent des modèles spécifiques, et donc ne prennent pas en charge la concaténation ou la répétition.

@item 
@code{index} lève une exception @ref{1ff,,ValueError} quand `x' ne se trouve pas dans `s'. Toutes les implémentations ne gèrent pas les deux paramètres supplémentaires `i' et `j'. Ces deux arguments permettent de chercher efficacement dans une sous-séquence de la séquence. Donner ces arguments est plus ou moins équivalent à @code{s[i:j].index(x)}, sans copier les données ; l'indice renvoyé est relatif au début de la séquence et non au début de la tranche.
@end enumerate

@node Types de séquences immuables,Types de séquences mutables,Opérations communes sur les séquences,Types séquentiels — list tuple range
@anchor{library/stdtypes immutable-sequence-types}@anchor{2136}@anchor{library/stdtypes typesseq-immutable}@anchor{2137}
@subsubsection Types de séquences immuables


@geindex immutable;sequence;types
@geindex object;tuple
@geindex built-in function;hash

La seule opération que les types de séquences immuables implémentent et qui n'est pas implémentée par les types de séquences mutables est la fonction native @ref{5d5,,hash()}.

Cette implémentation permet d'utiliser des séquences immuables, comme les instances de @ref{366,,n-uplets}, en tant que clés de @ref{253,,dict} et stockées dans les instances de @ref{5c3,,set} et @ref{5c4,,frozenset}.

Essayer de hacher une séquence immuable qui contient des valeurs non hachables lève une @ref{522,,TypeError}.

@node Types de séquences mutables,Listes<2>,Types de séquences immuables,Types séquentiels — list tuple range
@anchor{library/stdtypes mutable-sequence-types}@anchor{2138}@anchor{library/stdtypes typesseq-mutable}@anchor{20e6}
@subsubsection Types de séquences mutables


@geindex mutable;sequence;types
@geindex object;list
@geindex object;bytearray

Les opérations dans le tableau ci-dessous sont définies sur les types de séquences mutables. La classe mère abstraite @ref{19f,,collections.abc.MutableSequence} est prévue pour faciliter l'implémentation correcte de ces opérations sur les types de séquences personnalisées.

Dans le tableau ci-dessosus, `s' est une instance d'un type de séquence mutable, `t' est un objet itérable et `x' est un objet arbitraire qui répond à toutes les restrictions de type et de valeur imposées par `s' (par exemple, @ref{528,,bytearray} accepte uniquement des nombres entiers qui répondent à la restriction de la valeur @code{0 <= x <= 255}).

@geindex operations on;sequence;types
@geindex operations on;list;type
@geindex subscript;assignment
@geindex slice;assignment
@geindex statement;del
@geindex append() (sequence method)
@geindex clear() (sequence method)
@geindex copy() (sequence method)
@geindex extend() (sequence method)
@geindex insert() (sequence method)
@geindex pop() (sequence method)
@geindex remove() (sequence method)
@geindex reverse() (sequence method)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@tab

Notes

@item

@code{s[i] = x}

@tab

l'élément `i' de `s' est remplacé par `x'

@tab

@item

@code{s[i:j] = t}

@tab

la tranche de `s' de `i' à `j' est remplacée par le contenu de l'itérable `t'

@tab

@item

@code{del s[i:j]}

@tab

identique à @code{s[i:j] = []}

@tab

@item

@code{s[i:j:k] = t}

@tab

les éléments de @code{s[i:j:k]} sont remplacés par ceux de `t'

@tab

(1)

@item

@code{del s[i:j:k]}

@tab

supprime les éléments de @code{s[i:j:k]} de la liste

@tab

@item

@code{s.append(x)}

@tab

ajoute `x' à la fin de la séquence (identique à @code{s[len(s):len(s)] = [x]})

@tab

@item

@code{s.clear()}

@tab

supprime tous les éléments de `s' (identique à @code{del s[:]})

@tab

(5)

@item

@code{s.copy()}

@tab

crée une copie superficielle de `s' (identique à @code{s[:]})

@tab

(5)

@item

@code{s.extend(t)} ou @code{s += t}

@tab

étend `s' avec le contenu de `t' (proche de  @code{s[len(s):len(s)] = t})

@tab

@item

@code{s *= n}

@tab

met à jour `s' avec son contenu répété `n' fois

@tab

(6)

@item

@code{s.insert(i, x)}

@tab

insère `x' dans `s' à l'indice donné par `i' (identique à @code{s[i:i] = [x]})

@tab

@item

@code{s.pop()} ou @code{s.pop(i)}

@tab

récupère l'élément à la position `i' et le supprime de `s'

@tab

(2)

@item

@code{s.remove(x)}

@tab

removes the first item from
`s' where @code{s[i]} is equal to
`x'

@tab

(3)

@item

@code{s.reverse()}

@tab

inverse sur place les éléments de `s'

@tab

(4)

@end multitable


Notes :


@enumerate 

@item 
If `k' is not equal to @code{1}, `t' must have the same length as the slice it is replacing.

@item 
L'argument optionnel `i' vaut @code{-1} par défaut, afin que, par défaut, le dernier élément soit retiré et renvoyé.

@item 
@code{remove()} lève une exception @ref{1ff,,ValueError} si `x' ne se trouve pas dans `s'.

@item 
La méthode @code{reverse()} modifie la séquence sur place pour économiser de l'espace lors du traitement de grandes séquences. Pour rappeler aux utilisateurs qu'elle a un effet de bord, elle ne renvoie pas la séquence inversée.

@item 
@code{clear()} et @code{copy()} sont incluses pour la compatibilité avec les interfaces des conteneurs mutables qui ne gèrent pas les opérations de découpage (comme @ref{253,,dict} et @ref{5c3,,set}). @code{copy()} ne fait pas partie des classes mères abstraites (`ABC') de @ref{19f,,collections.abc.MutableSequence}, mais la plupart des classes implémentées gérant des séquences la proposent.


Ajouté dans la version 3.3: méthodes @code{clear()} et @code{copy()}.


@item 
La valeur `n' est un entier, ou un objet implémentant @ref{707,,__index__()}. Zéro et les valeurs négatives de `n' permettent d'effacer la séquence. Les éléments dans la séquence ne sont pas copiés ; ils sont référencés plusieurs fois, comme expliqué pour @code{s * n} dans @ref{2132,,Opérations communes sur les séquences}.
@end enumerate

@node Listes<2>,N-uplets,Types de séquences mutables,Types séquentiels — list tuple range
@anchor{library/stdtypes lists}@anchor{2139}@anchor{library/stdtypes typesseq-list}@anchor{20fd}
@subsubsection Listes


@geindex object;list

Les listes sont des séquences mutables, généralement utilisées pour stocker des collections d'éléments homogènes (le degré de similitude varie selon l'usage).

@geindex list (classe de base)
@anchor{library/stdtypes list}@anchor{5fc}
@deffn {Classe} list ([iterable])

Les listes peuvent être construites de différentes manières :


@itemize *

@item 
en utilisant une paire de crochets pour indiquer une liste vide : @code{[]} ;

@item 
au moyen de crochets, en séparant les éléments par des virgules : @code{[a]}, @code{[a, b, c]} ;

@item 
en utilisant une liste en compréhension : @code{[x for x in iterable]} ;

@item 
en utilisant le constructeur du type : @code{list()} ou @code{list(iterable)}.
@end itemize

Le constructeur crée une liste dont les éléments sont les mêmes et dans le même ordre que les éléments d'`iterable'. `iterable' peut être une séquence, un conteneur qui prend en charge l'itération, ou un itérateur. Si `iterable' est déjà une liste, une copie est faite et renvoyée, comme avec @code{iterable[:]}. Par exemple, @code{list('abc')} renvoie @code{['a', 'b', 'c']} et @code{list( (1, 2, 3) )} renvoie @code{[1, 2, 3]}. Si aucun argument est donné, le constructeur crée une nouvelle liste vide, @code{[]}.

De nombreuses autres opérations produisent des listes, comme la fonction native @ref{bbc,,sorted()}.

Les listes gèrent toutes les opérations des séquences @ref{2132,,communes} et @ref{20e6,,mutables}. Les listes fournissent également la méthode supplémentaire suivante :

@geindex sort() (méthode list)
@anchor{library/stdtypes list sort}@anchor{bbd}
@deffn {Méthode} sort (*, key=None, reverse=False)

Cette méthode trie la liste sur place, en utilisant uniquement des comparaisons @code{<} entre les éléments. Les exceptions ne sont pas supprimées : si n'importe quelle opération de comparaison échoue, le tri échoue (et la liste sera probablement laissée dans un état partiellement modifié).

@ref{bbd,,sort()} accepte deux arguments qui ne peuvent être fournis que nommés (voir @ref{2a2,,arguments nommés}) :

`key' spécifie une fonction d'un argument utilisée pour extraire une clé de comparaison de chaque élément de la liste (par exemple, @code{key=str.lower}). La clé correspondant à chaque élément de la liste n'est calculée qu'une seule fois, puis utilisée durant tout le processus. La valeur par défaut, @code{None}, signifie que les éléments sont triés directement sans calculer de « valeur clé » séparée.

La fonction utilitaire @ref{11b7,,functools.cmp_to_key()} est disponible pour convertir une fonction `cmp' du style 2.x à une fonction `key'.

`reverse', une valeur booléenne. Si elle est @code{True}, la liste d'éléments est triée comme si toutes les comparaisons étaient inversées.

Cette méthode modifie la séquence sur place pour économiser de l'espace lors du tri de grandes séquences. Pour rappeler aux utilisateurs cet effet de bord, elle ne renvoie pas la séquence triée (utilisez @ref{bbc,,sorted()} pour demander explicitement une nouvelle instance de liste triée).

La méthode @ref{bbd,,sort()} est garantie stable. Un tri est stable s'il garantit de ne pas changer l'ordre relatif des éléments égaux — cela est utile pour trier en plusieurs passes (par exemple, trier par service, puis par niveau de salaire).

Pour des exemples de tris et un bref tutoriel, consultez @ref{2107,,Sorting Techniques}.

`Particularité de l'implémentation CPython :' l'effet de tenter de modifier, ou même inspecter la liste pendant qu'on la trie est indéfini. L'implémentation C de Python fait apparaître la liste comme vide pour la durée du traitement, et lève @ref{1ff,,ValueError} si elle détecte que la liste a été modifiée au cours du tri.
@end deffn
@end deffn

@node N-uplets,Ranges,Listes<2>,Types séquentiels — list tuple range
@anchor{library/stdtypes tuples}@anchor{213a}@anchor{library/stdtypes typesseq-tuple}@anchor{206a}
@subsubsection `N'-uplets


@geindex object;tuple

Les `n'-uplets (`tuples' en anglais) sont des séquences immuables, généralement utilisées pour stocker des collections de données hétérogènes (telles que les paires produites par la fonction native @ref{1433,,enumerate()}). Les `n'-uplets sont également utilisés dans des cas où une séquence homogène et immuable de données  est nécessaire (pour, par exemple, les stocker dans un @ref{5c3,,ensemble} ou un @ref{253,,dictionnaire}).

@geindex tuple (classe de base)
@anchor{library/stdtypes tuple}@anchor{366}
@deffn {Classe} tuple ([iterable])

Les `n'-uplets peuvent être construits de différentes façons :


@itemize *

@item 
en utilisant une paire de parenthèses pour désigner le `n'-uplet vide : @code{()} ;

@item 
en utilisant une virgule, pour créer un `n'-uplet d'un élément : @code{a,} ou @code{(a,)} ;

@item 
en séparant les éléments avec des virgules : @code{a, b, c} ou @code{(a, b, c)} ;

@item 
en utilisant la fonction native @ref{366,,tuple()} : @code{tuple()} ou @code{tuple(iterable)}.
@end itemize

Le constructeur construit un `n'-uplet dont les éléments sont les mêmes et dans le même ordre que les éléments de `iterable'. `iterable' peut être une séquence, un conteneur qui prend en charge l'itération ou un itérateur. Si `iterable' est déjà un `n'-uplet, il est renvoyé inchangé. Par exemple, @code{tuple('abc')} renvoie @code{('a', 'b', 'c')} et @code{tuple( [1, 2, 3] )} renvoie @code{(1, 2, 3)}. Si aucun argument n'est donné, le constructeur crée un nouveau `n'-uplet vide, @code{()}.

Notez que c'est en fait la virgule qui fait un `n'-uplet et non les parenthèses. Les parenthèses sont facultatives, sauf dans le cas du `n'-uplet vide, ou lorsqu'elles sont nécessaires pour éviter l'ambiguïté syntaxique. Par exemple, @code{f(a, b, c)} est un appel de fonction avec trois arguments, alors que @code{f((a, b, c))} est un appel de fonction avec un triplet comme unique argument.

Les `n'-uplets implémentent toutes les opérations @ref{2132,,communes} des séquences.
@end deffn

Pour les collections hétérogènes de données où l'accès par nom est plus clair que l'accès par indice, @ref{1c5,,collections.namedtuple()} peut être un choix plus approprié qu'un simple `n'-uplet.

@node Ranges,,N-uplets,Types séquentiels — list tuple range
@anchor{library/stdtypes ranges}@anchor{213b}@anchor{library/stdtypes typesseq-range}@anchor{2105}
@subsubsection `Ranges'


@geindex object;range

Le type @ref{930,,range} représente une séquence immuable de nombres et est couramment utilisé pour itérer un certain nombre de fois dans les boucles @ref{2e6,,for}.

@geindex range (classe de base)
@anchor{library/stdtypes range}@anchor{930}
@deffn {Classe} range (stop)

@deffnx {Classe} range (start, stop[, step])

Les arguments du constructeur de `range' doivent être des entiers (des @ref{254,,int} ou tout autre objet qui implémente la méthode spéciale @ref{707,,__index__()}). La valeur par défaut de l'argument `step' est @code{1}. La valeur par défaut de l'argument `start' est @code{0}. Si `step' est égal à zéro, une exception @ref{1ff,,ValueError} est levée.

Pour un `step' positif, le contenu d'un `range' @code{r} est déterminé par la formule @code{r[i] = start + step*i} où @code{i >= 0} et @code{r[i] < stop}.

Pour un `step' négatif, le contenu du `range' est toujours déterminé par la formule @code{r[i] = start + step*i}, mais les contraintes sont @code{i >= 0} et @code{r[i] > stop}.

Un objet `range' sera vide si @code{r[0]} ne répond pas à la contrainte de valeur. Les `range' prennent en charge les indices négatifs, mais ceux-ci sont interprétées comme un indice à partir de la fin de la séquence déterminée par les indices positifs.

Les `range' contenant des valeurs absolues plus grandes que @ref{11a2,,sys.maxsize} sont permises, mais certaines fonctionnalités (comme @ref{619,,len()}) peuvent lever @ref{86d,,OverflowError}.

Exemples avec `range' :

@example
>>> list(range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(range(1, 11))
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> list(range(0, 30, 5))
[0, 5, 10, 15, 20, 25]
>>> list(range(0, 10, 3))
[0, 3, 6, 9]
>>> list(range(0, -10, -1))
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> list(range(0))
[]
>>> list(range(1, 0))
[]
@end example

`range' implémente toutes les opérations @ref{2132,,communes} des séquences sauf la concaténation et la répétition (en raison du fait que les `range' ne peuvent représenter que des séquences qui respectent un motif strict et que la répétition et la concaténation les feraient dévier de ce motif).

@geindex start (attribut range)
@anchor{library/stdtypes range start}@anchor{213c}
@deffn {Attribut} start

Valeur du paramètre `start' (ou @code{0} si le paramètre n'a pas été fourni)
@end deffn

@geindex stop (attribut range)
@anchor{library/stdtypes range stop}@anchor{213d}
@deffn {Attribut} stop

Valeur du paramètre `stop'
@end deffn

@geindex step (attribut range)
@anchor{library/stdtypes range step}@anchor{213e}
@deffn {Attribut} step

Valeur du paramètre `step' (ou @code{1} si le paramètre n'a pas été fourni)
@end deffn
@end deffn

L'avantage du type @ref{930,,range} sur une @ref{5fc,,liste} classique ou un @ref{366,,n-uplet} est qu'un objet @ref{930,,range} occupe toujours la même (petite) quantité de mémoire, peu importe la taille de l'intervalle qu'il représente (car il ne stocke que les valeurs @code{start}, @code{stop}, @code{step}, le calcul des éléments individuels et les sous-intervalles au besoin).

Les `range' implémentent la classe mère abstraite @ref{11a1,,collections.abc.Sequence} et offrent des fonctionnalités telles que les tests d'appartenance (avec `in'), de recherche par indice, les tranches et ils gèrent les indices négatifs (voir @ref{1bd7,,Types séquentiels — list@comma{} tuple@comma{} range}) :

@example
>>> r = range(0, 20, 2)
>>> r
range(0, 20, 2)
>>> 11 in r
False
>>> 10 in r
True
>>> r.index(10)
5
>>> r[5]
10
>>> r[:5]
range(0, 10, 2)
>>> r[-1]
18
@end example

Comparer des `range' avec @code{==} et @code{!=} les compare comme des séquences. C'est-à-dire que deux objets `range' sont considérés comme égaux s'ils représentent la même séquence de valeurs. (Notez que deux objets `range' dits égaux pourraient avoir leurs attributs @ref{213c,,start}, @ref{213d,,stop} et @ref{213e,,step} différents, par exemple @code{range(0) == range(2, 1, 3)} ou @code{range(0, 3, 2) == range(0, 4, 2)}.)


Modifié dans la version 3.2: implémente la classe mère abstraite `Sequence'. prend en charge les tranches (`slicing') et les indices négatifs. Teste l'appartenance d'un @ref{254,,int} en temps constant au lieu d'itérer sur tous les éléments.



Modifié dans la version 3.3: @code{==} et @code{!=} comparent des `range' en fonction de la séquence de valeurs qu'ils définissent (au lieu d'une comparaison fondée sur l'identité de l'objet).

Added the @ref{213c,,start}, @ref{213d,,stop} and @ref{213e,,step}
attributes.



@subsubheading Voir aussi



@itemize *

@item 
The linspace recipe@footnote{https://code.activestate.com/recipes/579000-equally-spaced-numbers-linspace/}
shows how to implement a lazy version of range suitable for floating-point
applications.
@end itemize


@geindex string;text sequence type
@geindex str (built-in class);(see also string)
@geindex object;string

@node Type Séquence de Texte — str,Séquences Binaires — bytes bytearray vue mémoire,Types séquentiels — list tuple range,Types natifs
@anchor{library/stdtypes text-sequence-type-str}@anchor{213f}@anchor{library/stdtypes textseq}@anchor{1b8a}
@subsection Type Séquence de Texte — @code{str}


Les données textuelles en Python sont manipulées avec des objets @ref{435,,str} ou `strings'. Les chaînes sont  des @ref{1bd7,,séquences} immuables de points de code Unicode. Les chaînes littérales peuvent être écrites de différentes manières :


@itemize *

@item 
entre guillemets simples : @code{'cela autorise les "guillemets anglais"'} ;

@item 
entre guillemets (anglais) : @code{"cela autorise les guillemets 'simples'"} ;

@item 
entre guillemets triples : @code{'@w{'}'Trois guillemets simples'@w{'}'}, @code{"""Trois guillemets anglais"""}.
@end itemize

Les chaînes entre guillemets triples peuvent couvrir plusieurs lignes, tous les espaces associées sont alors incluses dans la chaîne littérale.

Les chaînes littérales qui font partie d'une seule expression et ont seulement des espaces entre elles sont implicitement converties en une seule chaîne littérale. Autrement dit, @code{("spam " "eggs") == "spam eggs"}.

See @ref{1e2a,,Littéraux de chaînes de caractères et de suites d'octets} for more about the various forms of string literal,
including supported @ref{443,,escape sequences}, and the @code{r} ("raw") prefix that
disables most escape sequence processing.

Les chaînes peuvent également être créées à partir d'autres objets à l'aide du constructeur @ref{435,,str}.

Comme il n'y a pas de type « caractère » propre, un indice d'une chaîne produit une chaîne de longueur 1. Autrement dit, pour une chaîne non vide `s', @code{s[0] == s[0:1]}.

@geindex object;io.StringIO

Il n'y a aucun type de chaîne mutable, mais @ref{2134,,str.join()} ou @ref{f12,,io.StringIO} peuvent être utilisées pour construire efficacement des chaînes à partir de plusieurs fragments.


Modifié dans la version 3.3: pour une compatibilité ascendante avec la série Python 2, le préfixe @code{u} est à nouveau autorisé sur les chaînes littérales. Il n'a aucun effet sur le sens des chaînes littérales et ne peut pas être combiné avec le préfixe @code{r}.


@geindex string;str (built-in class)

@geindex str (classe de base)
@anchor{library/stdtypes str}@anchor{435}
@deffn {Classe} str (object='@w{'})

@deffnx {Classe} str (object=b'@w{'}, encoding='utf-8', errors='strict')

Renvoie une représentation en @ref{1b8a,,chaîne de caractères} de `object'. Si `object' n'est pas fourni, renvoie une chaîne vide. Sinon, le comportement de @code{str()} dépend des valeurs données pour `encoding' et `errors', comme indiqué ci-dessous.

If neither `encoding' nor `errors' is given, @code{str(object)} returns
@ref{608,,type(object).__str__(object)},
which is the "informal" or nicely
printable string representation of `object'.  For string objects, this is
the string itself.  If `object' does not have a @ref{608,,__str__()}
method, then @ref{435,,str()} falls back to returning
@ref{7e7,,repr(object)}.

@geindex buffer protocol;str (built-in class)
@geindex bytes;str (built-in class)

Si au moins un des deux arguments `encoding' ou `errors' est donné, `object' doit être un @ref{d1b,,objet octet-compatible} (par exemple, @ref{1bd,,bytes} ou @ref{528,,bytearray}). Dans ce cas, si `object' est un objet @ref{1bd,,bytes} (ou @ref{528,,bytearray}), alors @code{str(bytes, encoding, errors)} est équivalent à @ref{8c3,,bytes.decode(encoding@comma{} errors)}. Sinon, l'objet `bytes' sous-jacent au tampon est obtenu avant d'appeler @ref{8c3,,bytes.decode()}. Voir @ref{20e8,,Séquences Binaires — bytes@comma{} bytearray@comma{} vue mémoire} et @ref{38e,,Protocole tampon} pour plus d'informations sur les tampons.

Donner un objet @ref{1bd,,bytes} à @ref{435,,str()} sans argument `encoding' ni argument `errors' relève du premier cas, où la représentation informelle de la chaîne est renvoyée (voir aussi l'option @ref{5cd,,-b} de Python). Par exemple :

@example
>>> str(b'Zoot!')
"b'Zoot!'"
@end example

Pour plus d'informations sur la classe @code{str} et ses méthodes, voir les sections @ref{1b8a,,Type Séquence de Texte — str} et @ref{1b8b,,Méthodes de chaînes de caractères}. Pour formater des chaînes de caractères, voir les sections @ref{997,,f-strings} et @ref{1367,,Syntaxe de formatage de chaîne}. La section @ref{2140,,Services de Manipulation de Texte} contient aussi des informations.
@end deffn

@geindex string;methods

@menu
* Méthodes de chaînes de caractères: Méthodes de chaînes de caractères<2>. 
* Formatage de chaines à la printf:: 

@end menu

@node Méthodes de chaînes de caractères<2>,Formatage de chaines à la printf,,Type Séquence de Texte — str
@anchor{library/stdtypes id5}@anchor{2141}@anchor{library/stdtypes string-methods}@anchor{1b8b}
@subsubsection Méthodes de chaînes de caractères


@geindex module;re

Les chaînes implémentent toutes les opérations @ref{2132,,communes des séquences}, ainsi que les autres méthodes décrites ci-dessous.

Les chaînes gèrent aussi deux styles de mise en forme, l'un fournissant une grande flexibilité et de personnalisation (voir @ref{60c,,str.format()}, @ref{1367,,Syntaxe de formatage de chaîne} et @ref{2142,,Formatage personnalisé de chaîne}) et l'autre basée sur le style de formatage de @code{printf} du C qui gère une gamme plus étroite de types et est légèrement plus difficile à utiliser correctement, mais qui est souvent plus rapide pour les cas pris en charge (@ref{6b7,,Formatage de chaines à la printf}).

La section @ref{2143,,Services de Manipulation de Texte} de la bibliothèque standard couvre un certain nombre d'autres modules qui fournissent différents services relatifs au texte (y compris les expressions rationnelles dans le module @ref{b8,,re}).

@geindex capitalize() (méthode str)
@anchor{library/stdtypes str capitalize}@anchor{2144}
@deffn {Méthode} str.capitalize ()

Renvoie une copie de la chaîne avec son premier caractère en majuscule et le reste en minuscule.


Modifié dans la version 3.8: le premier caractère est maintenant mis en `titlecase' plutôt qu'en majuscule. Cela veut dire que les caractères comme les digrammes auront seulement leur première lettre en majuscule, au lieu du caractère en entier.

@end deffn

@geindex casefold() (méthode str)
@anchor{library/stdtypes str casefold}@anchor{dc3}
@deffn {Méthode} str.casefold ()

Renvoie une copie `casefolded' de la chaîne. Les chaînes `casefolded' peuvent être utilisées dans des comparaisons insensibles à la casse.

Le `casefolding' est une technique agressive de mise en minuscule, car il vise à éliminer toutes les distinctions de casse dans une chaîne. Par exemple, la lettre minuscule @code{'ß'} de l'allemand équivaut à @code{"ss"}. Comme il est déjà minuscule, @ref{177b,,lower()} ne fait rien à @code{'ß'} ; @ref{dc3,,casefold()} le convertit en @code{"ss"}.

The casefolding algorithm is
described in section 3.13 'Default Case Folding' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode15.1.0/ch03.pdf}.


Ajouté dans la version 3.3.

@end deffn

@geindex center() (méthode str)
@anchor{library/stdtypes str center}@anchor{1c0a}
@deffn {Méthode} str.center (width[, fillchar])

Renvoie la chaîne au centre d'une chaîne de longueur `width'. Le remplissage est fait en utilisant l'argument `fillchar' (qui par défaut est une espace ASCII). La chaîne d'origine est renvoyée si `width' est inférieure ou égale à @code{len(s)}.
@end deffn

@geindex count() (méthode str)
@anchor{library/stdtypes str count}@anchor{15cd}
@deffn {Méthode} str.count (sub[, start[, end]])

Renvoie le nombre d'occurrences de `sub' ne se chevauchant pas dans l'intervalle [`start', `end']. Les arguments facultatifs `start' et `end' sont interprétés comme dans la notation des tranches (`slices' en anglais).

Si `sub' est vide, renvoie le nombre de chaînes vides entre les caractères de début et de fin, ce qui correspond à la longueur de la chaîne plus un.
@end deffn

@geindex encode() (méthode str)
@anchor{library/stdtypes str encode}@anchor{8c2}
@deffn {Méthode} str.encode (encoding='utf-8', errors='strict')

Renvoie la chaine encodée dans une instance de @ref{1bd,,bytes}.

`encoding' vaut par défaut @code{utf-8} ; pour une liste des encodages possibles, voir la section @ref{da6,,Standard Encodings}.

`errors' détermine la manière dont les erreurs sont traitées. La valeur par défaut est @code{'strict'}, ce qui signifie que les erreurs d'encodage lèvent une @ref{1281,,UnicodeError}. Les autres valeurs possibles sont @code{'ignore'}, @code{'replace'}, @code{'xmlcharrefreplace'}, @code{'backslashreplace'} et tout autre nom enregistré `via' @ref{144d,,codecs.register_error()}. Voir la section @ref{1774,,Gestionnaires d'erreurs} pour plus de détails.

Pour des raisons de performances, la valeur de `errors' n'est pas vérifiée à moins qu'une erreur d'encodage ne se produise réellement, que le @ref{1f5,,mode développeur} ne soit activé ou que Python ait été compilé en @ref{1f6,,mode débogage}.


Modifié dans la version 3.1: gère les arguments nommés.



Modifié dans la version 3.9: les valeurs de `errors' sont maintenant vérifiées en @ref{1f5,,mode de développement} et en @ref{1f6,,mode de débogage}.

@end deffn

@geindex endswith() (méthode str)
@anchor{library/stdtypes str endswith}@anchor{eb5}
@deffn {Méthode} str.endswith (suffix[, start[, end]])

Renvoie @code{True} si la chaîne se termine par `suffix', sinon @code{False}. `suffix' peut aussi être un `n'-uplet de suffixes à rechercher. Si l'argument optionnel `start' est donné, le test se fait à partir de cette position. Si l'argument optionnel `end' est fourni, la comparaison s'arrête à cette position.
@end deffn

@geindex expandtabs() (méthode str)
@anchor{library/stdtypes str expandtabs}@anchor{2145}
@deffn {Méthode} str.expandtabs (tabsize=8)

Renvoie une copie de la chaîne où toutes les tabulations sont remplacées par une ou plusieurs espaces, en fonction de la colonne courante et de la taille de tabulation donnée. Les positions des tabulations se trouvent tous les `tabsize' caractères (8 par défaut, ce qui donne les positions de tabulations aux colonnes 0, 8, 16 et ainsi de suite). Pour travailler sur la chaîne, la colonne en cours est mise à zéro et la chaîne est examinée caractère par caractère. Si le caractère est une tabulation (@code{\t}), un ou plusieurs caractères d'espacement sont insérés dans le résultat jusqu'à ce que la colonne courante soit égale à la position de tabulation suivante (le caractère tabulation lui-même n'est pas copié). Si le caractère est un saut de ligne (@code{\n}) ou un retour chariot (@code{\r}), il est copié et la colonne en cours est remise à zéro. Tout autre caractère est copié inchangé et la colonne en cours est incrémentée de un indépendamment de la façon dont le caractère est représenté lors de l'affichage.

@example
>>> '01\t012\t0123\t01234'.expandtabs()
'01      012     0123    01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01  012 0123    01234'
@end example
@end deffn

@geindex find() (méthode str)
@anchor{library/stdtypes str find}@anchor{e91}
@deffn {Méthode} str.find (sub[, start[, end]])

Renvoie l'indice de la première position dans la chaîne où `sub' est trouvé dans le découpage @code{s[start:end]}. Les arguments facultatifs `start' et `end' sont interprétés comme dans la notation des découpages (`slice' en anglais). Renvoie @code{-1} si `sub' n'est pas trouvé.

@cartouche
@quotation Note 
la méthode @ref{e91,,find()} ne doit être utilisée que si vous avez besoin de connaître la position de `sub'. Pour vérifier si `sub' est une sous chaine ou non, utilisez l'opérateur @ref{2e8,,in} :

@example
>>> 'Py' in 'Python'
True
@end example
@end quotation
@end cartouche
@end deffn

@geindex format() (méthode str)
@anchor{library/stdtypes str format}@anchor{60c}
@deffn {Méthode} str.format (*args, **kwargs)

Formate une chaîne. La chaîne sur laquelle cette méthode est appelée peut contenir du texte littéral ou des emplacements de remplacement délimités par des accolades @code{@{@}}. Chaque champ de remplacement contient soit l'indice numérique d'un argument positionnel, soit le nom d'un argument nommé. Renvoie une copie de la chaîne où chaque champ de remplacement est remplacé par la valeur de chaîne de l'argument correspondant.

@example
>>> "The sum of 1 + 2 is @{0@}".format(1+2)
'The sum of 1 + 2 is 3'
@end example

Voir @ref{1367,,Syntaxe de formatage de chaîne} pour une description des options de formatage qui peuvent être spécifiées dans les chaînes de format.

@cartouche
@quotation Note 
lors du formatage avec le format @code{n} (comme @code{'@{:n@}'.format(1234)}) d'un nombre (@ref{254,,int}, @ref{2eb,,float}, @ref{2ec,,complex}, @ref{29a,,decimal.Decimal} et classes dérivées), la fonction met temporairement la variable @code{LC_CTYPE} à la valeur de @code{LC_NUMERIC} pour décoder correctement les attributs @code{decimal_point} et @code{thousands_sep} de @code{localeconv()}, s'ils ne sont pas en ASCII ou font plus d'un octet et que @code{LC_NUMERIC} est différent de @code{LC_CTYPE}. Ce changement temporaire affecte les autres fils d'exécution.
@end quotation
@end cartouche


Modifié dans la version 3.7: lors du formatage d'un nombre avec le format @code{n}, la fonction change temporairement @code{LC_CTYPE} par la valeur de @code{LC_NUMERIC} dans certains cas.

@end deffn

@geindex format_map() (méthode str)
@anchor{library/stdtypes str format_map}@anchor{dc4}
@deffn {Méthode} str.format_map (mapping, /)

Semblable à @code{str.format(**mapping)}, sauf que @code{mapping} est utilisé directement et non copié dans un @ref{253,,dict}. C'est utile si, par exemple, @code{mapping} est une sous-classe de @code{dict} :

@example
>>> class Default(dict):
...     def __missing__(self, key):
...         return key
...
>>> '@{name@} was born in @{country@}'.format_map(Default(name='Guido'))
'Guido was born in country'
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex index() (méthode str)
@anchor{library/stdtypes str index}@anchor{15ce}
@deffn {Méthode} str.index (sub[, start[, end]])

Comme @ref{e91,,find()}, mais lève une @ref{1ff,,ValueError} lorsque la chaîne est introuvable.
@end deffn

@geindex isalnum() (méthode str)
@anchor{library/stdtypes str isalnum}@anchor{2146}
@deffn {Méthode} str.isalnum ()

Renvoie @code{True} si tous les caractères de la chaîne sont alphanumériques et qu'il y a au moins un caractère, sinon @code{False}. Un caractère @code{c} est alphanumérique si l'un des tests suivants renvoie @code{True} : @code{c.isalpha()}, @code{c.isdecimal()}, @code{c.isdigit()} ou @code{c.isnumeric()}.
@end deffn

@geindex isalpha() (méthode str)
@anchor{library/stdtypes str isalpha}@anchor{2147}
@deffn {Méthode} str.isalpha ()

Return @code{True} if all characters in the string are alphabetic and there is at least
one character, @code{False} otherwise.  Alphabetic characters are those characters defined
in the Unicode character database as "Letter", i.e., those with general category
property being one of "Lm", "Lt", "Lu", "Ll", or "Lo".  Note that this is different
from the Alphabetic property defined in the section 4.10 'Letters@comma{} Alphabetic@comma{} and Ideographic' of the Unicode Standard@footnote{https://www.unicode.org/versions/Unicode15.1.0/ch04.pdf}.
@end deffn

@geindex isascii() (méthode str)
@anchor{library/stdtypes str isascii}@anchor{adf}
@deffn {Méthode} str.isascii ()

Renvoie @code{True} si la chaîne est vide ou ne contient que des caractères ASCII, @code{False} sinon. Les caractères ASCII ont un code dans l'intervalle @code{"U+0000"}–@code{"U+007F"}.


Ajouté dans la version 3.7.

@end deffn

@geindex isdecimal() (méthode str)
@anchor{library/stdtypes str isdecimal}@anchor{2148}
@deffn {Méthode} str.isdecimal ()

Renvoie @code{True} si tous les caractères de la chaîne sont des caractères décimaux et qu'elle contient au moins un caractère, sinon @code{False}. Les caractères décimaux sont ceux pouvant être utilisés pour former des nombres en base 10, tels que U+0660, ARABIC-INDIC DIGIT ZERO. Formellement, un caractère décimal est un caractère dans la catégorie Unicode générale "Nd".
@end deffn

@geindex isdigit() (méthode str)
@anchor{library/stdtypes str isdigit}@anchor{2149}
@deffn {Méthode} str.isdigit ()

Renvoie @code{True} si tous les caractères de la chaîne sont des chiffres et qu'elle contient au moins un caractère, @code{False} sinon. Les chiffres incluent des caractères décimaux et des chiffres qui nécessitent une manipulation particulière, tels que les `compatibility superscript digits'. Ça couvre les chiffres qui ne peuvent pas être utilisés pour construire des nombres en base 10, tels que les nombres de Kharosthi. Formellement, un chiffre est un caractère dont la valeur de la propriété `Numeric_Type' est `Digit' ou `Decimal'.
@end deffn

@geindex isidentifier() (méthode str)
@anchor{library/stdtypes str isidentifier}@anchor{18e7}
@deffn {Méthode} str.isidentifier ()

Renvoie @code{True} si la chaîne est un identifiant valide selon la définition du langage, section @ref{1e1a,,Identifiants et mots-clés}.

@ref{214a,,keyword.iskeyword()} can be used to test whether string @code{s} is a reserved
identifier, such as @ref{140e,,def} and @ref{12b5,,class}.

Par exemple :

@example
>>> from keyword import iskeyword

>>> 'hello'.isidentifier(), iskeyword('hello')
(True, False)
>>> 'def'.isidentifier(), iskeyword('def')
(True, True)
@end example
@end deffn

@geindex islower() (méthode str)
@anchor{library/stdtypes str islower}@anchor{214b}
@deffn {Méthode} str.islower ()

Renvoie @code{True} si tous les caractères capitalisables @footnote{
Les caractères capitalisables sont ceux dont la propriété Unicode `general category' est soit "Lu" (pour `Letter', `uppercase'), soit "Ll" (pour `Letter', `lowercase'), soit "Lt" (pour `Letter', `titlecase').
} de la chaîne sont en minuscules et qu'elle contient au moins un caractère capitalisable. Renvoie @code{False} dans le cas contraire.
@end deffn

@geindex isnumeric() (méthode str)
@anchor{library/stdtypes str isnumeric}@anchor{214c}
@deffn {Méthode} str.isnumeric ()

Renvoie @code{True} si tous les caractères de la chaîne sont des caractères numériques et qu'elle contient au moins un caractère, sinon @code{False}. Les caractères numériques comprennent les chiffres et tous les caractères qui ont la propriété Unicode `numeric value', par exemple U+2155, `VULGAR FRACTION OF FIFTH'. Formellement, les caractères numériques sont ceux avec les propriétés `Numeric_Type=Digit', `Numeric_Type=Decimal' ou `Numeric_Type=Numeric'.
@end deffn

@geindex isprintable() (méthode str)
@anchor{library/stdtypes str isprintable}@anchor{dc5}
@deffn {Méthode} str.isprintable ()

Renvoie @code{True} si tous les caractères de la chaîne sont affichables ou si elle est vide, sinon @code{False}. Les caractères non affichables sont les caractères définis dans la base de données de caractères Unicode comme « `Other' » ou « `Separator' », à l'exception de l'espace ASCII (@code{0x20}) qui est considérée comme affichable. (Notez que les caractères imprimables dans ce contexte sont ceux qui ne doivent pas être échappés quand @ref{7e7,,repr()} est invoquée sur une chaîne. Ça n'a aucune incidence sur le traitement des chaînes écrites sur @ref{ac4,,sys.stdout} ou @ref{926,,sys.stderr}.)
@end deffn

@geindex isspace() (méthode str)
@anchor{library/stdtypes str isspace}@anchor{214d}
@deffn {Méthode} str.isspace ()

Renvoie @code{True} s'il n'y a que des caractères d'espacement dans la chaîne et qu'elle comporte au moins un caractère. Renvoie @code{False} dans le cas contraire.

Un caractère est considéré comme un caractère d'espacement (`whitespace' en anglais) si, dans la base de données caractères Unicode (voir @ref{104,,unicodedata}), sa catégorie générale est @code{Zs} (« séparateur, espace »), ou sa classe bidirectionnelle est une de @code{WS}, @code{B}, ou @code{S}.
@end deffn

@geindex istitle() (méthode str)
@anchor{library/stdtypes str istitle}@anchor{214e}
@deffn {Méthode} str.istitle ()

Renvoie @code{True} si la chaîne est une chaîne `titlecased' et qu'elle contient au moins un caractère, par exemple les caractères majuscules ne peuvent suivre les caractères non capitalisables et les caractères minuscules ne peuvent suivre que des caractères capitalisables. Renvoie @code{False} dans le cas contraire.
@end deffn

@geindex isupper() (méthode str)
@anchor{library/stdtypes str isupper}@anchor{214f}
@deffn {Méthode} str.isupper ()

Renvoie @code{True} si tous les caractères différentiables sur la casse @footnote{
Les caractères capitalisables sont ceux dont la propriété Unicode `general category' est soit "Lu" (pour `Letter', `uppercase'), soit "Ll" (pour `Letter', `lowercase'), soit "Lt" (pour `Letter', `titlecase').
} de la chaîne sont en majuscules et s'il y a au moins un caractère différentiable sur la casse, sinon @code{False}.

@example
>>> 'BANANA'.isupper()
True
>>> 'banana'.isupper()
False
>>> 'baNana'.isupper()
False
>>> ' '.isupper()
False
@end example
@end deffn

@geindex join() (méthode str)
@anchor{library/stdtypes meth-str-join}@anchor{2150}@anchor{library/stdtypes str join}@anchor{2134}
@deffn {Méthode} str.join (iterable)

Renvoie une chaîne qui est la concaténation des chaînes contenues dans `iterable'. Une @ref{522,,TypeError} est levée si une valeur d'`iterable' n'est pas une chaîne, y compris pour les objets @ref{1bd,,bytes}. Le séparateur entre les éléments est la chaîne fournissant cette méthode.
@end deffn

@geindex ljust() (méthode str)
@anchor{library/stdtypes str ljust}@anchor{1c09}
@deffn {Méthode} str.ljust (width[, fillchar])

Renvoie la chaîne justifiée à gauche dans une chaîne de longueur `width'. Le bourrage est fait en utilisant `fillchar' (qui par défaut est une espace ASCII). La chaîne d'origine est renvoyée si `width' est inférieure ou égale à @code{len(s)}.
@end deffn

@geindex lower() (méthode str)
@anchor{library/stdtypes str lower}@anchor{177b}
@deffn {Méthode} str.lower ()

Renvoie une copie de la chaîne avec tous les caractères différentiables sur la casse @footnote{
Les caractères capitalisables sont ceux dont la propriété Unicode `general category' est soit "Lu" (pour `Letter', `uppercase'), soit "Ll" (pour `Letter', `lowercase'), soit "Lt" (pour `Letter', `titlecase').
} convertis en minuscules.

L'algorithme de mise en minuscules utilisé est décrit dans la section 3.13 ’Default Case Folding’ de la norme Unicode@footnote{https://www.unicode.org/versions/Unicode15.1.0/ch03.pdf}.
@end deffn

@geindex lstrip() (méthode str)
@anchor{library/stdtypes str lstrip}@anchor{1464}
@deffn {Méthode} str.lstrip ([chars])

Renvoie une copie de la chaîne avec des caractères supprimés au début. L'argument `chars' est une chaîne spécifiant le jeu de caractères à supprimer. En cas d'omission ou @code{None}, la valeur par défaut de `chars' permet de supprimer des caractères d'espacement. L'argument `chars' n'est pas un préfixe, toutes les combinaisons de ses valeurs sont supprimées :

@example
>>> '   spacious   '.lstrip()
'spacious   '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
@end example

Voir @ref{8bc,,str.removeprefix()} pour une méthode qui supprime une seule chaîne de préfixe plutôt que la totalité d'un ensemble de caractères. Par exemple :

@example
>>> 'Arthur: three!'.lstrip('Arthur: ')
'ee!'
>>> 'Arthur: three!'.removeprefix('Arthur: ')
'three!'
@end example
@end deffn

@geindex maketrans() (méthode statique str)
@anchor{library/stdtypes str maketrans}@anchor{dc6}
@deffn {Méthode} static str.maketrans (x[, y[, z]])

Cette méthode statique renvoie une table de traduction utilisable pour @ref{2151,,str.translate()}.

Si un seul argument est fourni, ce soit être un dictionnaire faisant correspondre des points de code Unicode (nombres entiers) ou des caractères (chaînes de longueur 1) à des points de code Unicode.

Si deux arguments sont fournis, ce doit être deux chaînes de caractères de même longueur. Le dictionnaire renvoyé fera correspondre pour chaque caractère de x un caractère de y pris à la même place. Si un troisième argument est fourni, ce doit être une chaîne dont chaque caractère correspondra à @code{None} dans le résultat.
@end deffn

@geindex partition() (méthode str)
@anchor{library/stdtypes str partition}@anchor{e94}
@deffn {Méthode} str.partition (sep)

Divise la chaîne à la première occurrence de `sep', et renvoie un triplet contenant la partie avant le séparateur, le séparateur lui-même, et la partie après le séparateur. Si le séparateur n'est pas trouvé, le triplet contient la chaîne elle-même, suivie de deux chaînes vides.
@end deffn

@geindex removeprefix() (méthode str)
@anchor{library/stdtypes str removeprefix}@anchor{8bc}
@deffn {Méthode} str.removeprefix (prefix, /)

Si la chaîne de caractères commence par la chaîne `prefix', renvoie @code{string[len(prefix):]}. Sinon, renvoie une copie de la chaîne originale :

@example
>>> 'TestHook'.removeprefix('Test')
'Hook'
>>> 'BaseTestCase'.removeprefix('Test')
'BaseTestCase'
@end example


Ajouté dans la version 3.9.

@end deffn

@geindex removesuffix() (méthode str)
@anchor{library/stdtypes str removesuffix}@anchor{8bd}
@deffn {Méthode} str.removesuffix (suffix, /)

Si la chaîne de caractères se termine par la chaîne `suffix' et que `suffix' n'est pas vide, renvoie @code{string[:-len(suffix)]}. Sinon, renvoie une copie de la chaîne originale :

@example
>>> 'MiscTests'.removesuffix('Tests')
'Misc'
>>> 'TmpDirMixin'.removesuffix('Tests')
'TmpDirMixin'
@end example


Ajouté dans la version 3.9.

@end deffn

@geindex replace() (méthode str)
@anchor{library/stdtypes str replace}@anchor{198}
@deffn {Méthode} str.replace (old, new, count=-1)

Return a copy of the string with all occurrences of substring `old' replaced by
`new'.  If `count' is given, only the first `count' occurrences are replaced.
If `count' is not specified or @code{-1}, then all occurrences are replaced.


Modifié dans la version 3.13: `count' is now supported as a keyword argument.

@end deffn

@geindex rfind() (méthode str)
@anchor{library/stdtypes str rfind}@anchor{e92}
@deffn {Méthode} str.rfind (sub[, start[, end]])

Renvoie l'indice le plus élevé dans la chaîne où la sous-chaîne `sub' se trouve, de telle sorte que `sub' soit contenue dans @code{s[start:end]}. Les arguments facultatifs `start' et `end' sont interprétés comme dans la notation des découpages. Renvoie  @code{-1} en cas d'échec.
@end deffn

@geindex rindex() (méthode str)
@anchor{library/stdtypes str rindex}@anchor{1236}
@deffn {Méthode} str.rindex (sub[, start[, end]])

Comme @ref{e92,,rfind()} mais lève une exception @ref{1ff,,ValueError} lorsque la sous-chaîne `sub' est introuvable.
@end deffn

@geindex rjust() (méthode str)
@anchor{library/stdtypes str rjust}@anchor{1c08}
@deffn {Méthode} str.rjust (width[, fillchar])

Renvoie la chaîne justifiée à droite dans une chaîne de longueur `width'. Le bourrage est fait en utilisant le caractère spécifié par `fillchar' (par défaut une espace ASCII). La chaîne d'origine est renvoyée si `width' est inférieure ou égale à @code{len(s)}.
@end deffn

@geindex rpartition() (méthode str)
@anchor{library/stdtypes str rpartition}@anchor{1237}
@deffn {Méthode} str.rpartition (sep)

Divise la chaîne à la dernière occurrence de `sep', et renvoie un triplet contenant la partie avant le séparateur, le séparateur lui-même, et la partie après le séparateur. Si le séparateur n'est pas trouvé, le triplet contient deux chaînes vides, puis la chaîne elle-même.
@end deffn

@geindex rsplit() (méthode str)
@anchor{library/stdtypes str rsplit}@anchor{1234}
@deffn {Méthode} str.rsplit (sep=None, maxsplit=-1)

Renvoie une liste des mots de la chaîne, en utilisant `sep' comme séparateur. Si `maxsplit' est donné, c'est le nombre maximum de divisions qui pourront être faites, celles « les plus à droite ». Si `sep' est pas spécifié ou est @code{None}, tout caractère d'espacement est un séparateur. En dehors du fait qu'il découpe par la droite, @ref{1234,,rsplit()} se comporte comme @ref{e93,,split()} qui est décrit en détail ci-dessous.
@end deffn

@geindex rstrip() (méthode str)
@anchor{library/stdtypes str rstrip}@anchor{1465}
@deffn {Méthode} str.rstrip ([chars])

Renvoie une copie de la chaîne avec des caractères finaux supprimés. L'argument `chars' est une chaîne spécifiant le jeu de caractères à supprimer. En cas d'omission ou @code{None}, les caractères d'espacement sont supprimés. L'argument `chars' n'est pas un suffixe : toutes les combinaisons de ses valeurs sont retirées :

@example
>>> '   spacious   '.rstrip()
'   spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'
@end example

Voir @ref{8bd,,str.removesuffix()} pour une méthode qui supprime une seule chaîne de suffixe plutôt que la totalité d'un ensemble de caractères. Par exemple :

@example
>>> 'Monty Python'.rstrip(' Python')
'M'
>>> 'Monty Python'.removesuffix(' Python')
'Monty'
@end example
@end deffn

@geindex split() (méthode str)
@anchor{library/stdtypes str split}@anchor{e93}
@deffn {Méthode} str.split (sep=None, maxsplit=-1)

Renvoie une liste des mots de la chaîne, en utilisant `sep' comme séparateur de mots. Si `maxsplit' est donné, c'est le nombre maximum de divisions qui pourront être effectuées (donnant ainsi une liste de longueur @code{maxsplit+1}). Si `maxsplit' n'est pas fourni, ou vaut @code{-1}, le nombre de découpes n'est pas limité (toutes les découpes possibles sont faites).

If `sep' is given, consecutive delimiters are not grouped together and are
deemed to delimit empty strings (for example, @code{'1,,2'.split(',')} returns
@code{['1', '@w{'}, '2']}).  The `sep' argument may consist of multiple characters
as a single delimiter (to split with multiple delimiters, use
@ref{29f,,re.split()}). Splitting an empty string with a specified separator
returns @code{['@w{'}]}.

Par exemple :

@example
>>> '1,2,3'.split(',')
['1', '2', '3']
>>> '1,2,3'.split(',', maxsplit=1)
['1', '2,3']
>>> '1,2,,3,'.split(',')
['1', '2', '@w{'}, '3', '@w{'}]
>>> '1<>2<>3<4'.split('<>')
['1', '2', '3<4']
@end example

Si `sep' n'est pas spécifié ou est @code{None}, un autre algorithme de découpage est appliqué : les caractères d'espacement consécutifs sont considérés comme un seul séparateur, et le résultat ne contient pas les chaînes vides de début ou de la fin si la chaîne est préfixée ou suffixé de caractères d'espacement. Par conséquent, diviser une chaîne vide ou une chaîne composée d'espaces avec un séparateur @code{None} renvoie @code{[]}.

Par exemple :

@example
>>> '1 2 3'.split()
['1', '2', '3']
>>> '1 2 3'.split(maxsplit=1)
['1', '2 3']
>>> '   1   2   3   '.split()
['1', '2', '3']
@end example
@end deffn

@geindex universal newlines;str.splitlines method

@geindex splitlines() (méthode str)
@anchor{library/stdtypes str splitlines}@anchor{1235}
@deffn {Méthode} str.splitlines (keepends=False)

Renvoie les lignes de la chaîne sous forme de liste, la découpe se faisant au niveau des limites des lignes. Les sauts de ligne ne sont pas inclus dans la liste des résultats, sauf si `keepends' est donné et est vrai.

Cette méthode découpe sur les limites de ligne suivantes. Ces limites sont un sur-ensemble de @ref{d28,,universal newlines}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Représentation

@tab

Description

@item

@code{\n}

@tab

Saut de ligne

@item

@code{\r}

@tab

Retour chariot

@item

@code{\r\n}

@tab

Retour chariot + saut de ligne

@item

@code{\v} or @code{\x0b}

@tab

Tabulation verticale

@item

@code{\f} or @code{\x0c}

@tab

Saut de page

@item

@code{\x1c}

@tab

Séparateur de fichiers

@item

@code{\x1d}

@tab

Séparateur de groupes

@item

@code{\x1e}

@tab

Séparateur d'enregistrements

@item

@code{\x85}

@tab

Ligne suivante (code de contrôle `C1')

@item

@code{\u2028}

@tab

Séparateur de ligne

@item

@code{\u2029}

@tab

Séparateur de paragraphe

@end multitable



Modifié dans la version 3.2: @code{\v} et @code{\f} ajoutés à la liste des limites de lignes.


Par exemple :

@example
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '@w{'}, 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']
@end example

Contrairement à @ref{e93,,split()} lorsque `sep' est fourni, cette méthode renvoie une liste vide pour la chaîne vide, et un saut de ligne à la fin ne se traduit pas par une ligne supplémentaire :

@example
>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']
@end example

À titre de comparaison, @code{split('\n')} donne :

@example
>>> '@w{'}.split('\n')
['@w{'}]
>>> 'Two lines\n'.split('\n')
['Two lines', '@w{'}]
@end example
@end deffn

@geindex startswith() (méthode str)
@anchor{library/stdtypes str startswith}@anchor{eb4}
@deffn {Méthode} str.startswith (prefix[, start[, end]])

Renvoie @code{True} si la chaîne commence par `prefix', sinon  @code{False}. `prefix' peut aussi être un `n'-uplet de préfixes à rechercher. Lorsque `start' est donné, la comparaison commence à cette position et, lorsque `end' est donné, la comparaison s'arrête à celle-ci.
@end deffn

@geindex strip() (méthode str)
@anchor{library/stdtypes str strip}@anchor{1463}
@deffn {Méthode} str.strip ([chars])

Renvoie une copie de la chaîne dont des caractères initiaux et finaux sont supprimés. L'argument `chars' est une chaîne spécifiant le jeu de caractères à supprimer. En cas d'omission ou @code{None}, les caractères d'espacement sont supprimés. L'argument `chars' est pas un préfixe ni un suffixe, toutes les combinaisons de ses valeurs sont supprimées :

@example
>>> '   spacious   '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'
@end example

Les caractères de `char' sont retirés du début et de la fin de la chaîne. Les caractères sont retirés de la gauche jusqu'à atteindre un caractère ne figurant pas dans le jeu de caractères dans `chars'. La même opération a lieu par la droite. Par exemple :

@example
>>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
>>> comment_string.strip('.#! ')
'Section 3.2.1 Issue #32'
@end example
@end deffn

@geindex swapcase() (méthode str)
@anchor{library/stdtypes str swapcase}@anchor{2152}
@deffn {Méthode} str.swapcase ()

Renvoie une copie de la chaîne dont les caractères majuscules sont convertis en minuscules et vice versa. Notez qu'il est pas nécessairement vrai que @code{s.swapcase().swapcase() == s}.
@end deffn

@geindex title() (méthode str)
@anchor{library/stdtypes str title}@anchor{2153}
@deffn {Méthode} str.title ()

Renvoie une version de la chaîne où les mots commencent par une capitale et les caractères restants sont en minuscules.

Par exemple :

@example
>>> 'Hello world'.title()
'Hello World'
@end example

Pour l'algorithme, la notion de mot est définie simplement et indépendamment de la langue comme un groupe de lettres consécutives. La définition fonctionne dans de nombreux contextes, mais cela signifie que les apostrophes (typiquement de la forme possessive en Anglais) forment les limites de mot, ce qui n'est pas toujours le résultat souhaité :

@example
>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"
@end example

La fonction @ref{2154,,string.capwords()} n'a pas ce problème, car elle sépare les mots uniquement sur les espaces.

Sinon, une solution pour contourner le problème des apostrophes est d'utiliser des expressions rationnelles :

@example
>>> import re
>>> def titlecase(s):
...     return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0).capitalize(),
...                   s)
...
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."
@end example
@end deffn

@geindex translate() (méthode str)
@anchor{library/stdtypes str translate}@anchor{2151}
@deffn {Méthode} str.translate (table)

Return a copy of the string in which each character has been mapped through
the given translation table.  The table must be an object that implements
indexing via @ref{280,,__getitem__()}, typically a @ref{1199,,mapping} or
@ref{4db,,sequence}.  When indexed by a Unicode ordinal (an integer), the
table object can do any of the following: return a Unicode ordinal or a
string, to map the character to one or more other characters; return
@code{None}, to delete the character from the return string; or raise a
@ref{2155,,LookupError} exception, to map the character to itself.

Vous pouvez utiliser @ref{dc6,,str.maketrans()} pour créer une table de correspondances de caractères dans différents formats.

Voir aussi le module @ref{1b,,codecs} pour une approche plus souple de changements de caractères par correspondance.
@end deffn

@geindex upper() (méthode str)
@anchor{library/stdtypes str upper}@anchor{2156}
@deffn {Méthode} str.upper ()

Renvoie une copie de la chaîne où tous les caractères capitalisables @footnote{
Les caractères capitalisables sont ceux dont la propriété Unicode `general category' est soit "Lu" (pour `Letter', `uppercase'), soit "Ll" (pour `Letter', `lowercase'), soit "Lt" (pour `Letter', `titlecase').
} ont été convertis en capitales. Notez que @code{s.upper().isupper()} peut être @code{False} si @code{s} contient des caractères non capitalisables ou si la catégorie Unicode d'un caractère du résultat n'est pas "Lu" (`Letter', `uppercase'), mais par exemple "Lt" (`Letter', `titlecase').

L'algorithme de capitalisation utilisé est décrit dans la section 3.13 ’Default Case Folding’ de la norme Unicode@footnote{https://www.unicode.org/versions/Unicode15.1.0/ch03.pdf}.
@end deffn

@geindex zfill() (méthode str)
@anchor{library/stdtypes str zfill}@anchor{1466}
@deffn {Méthode} str.zfill (width)

Renvoie une copie de la chaîne remplie par la gauche du chiffre (le caractère ASCII) @code{'0'} pour faire une chaîne de longueur `width'. Un préfixe (@code{'+'} / @code{'-'}) est permis par l'insertion du caractère de bourrage `après' le caractère désigné plutôt qu'avant. La chaîne d'origine est renvoyée si `width' est inférieure ou égale à @code{len(s)}.

Par exemple :

@example
>>> "42".zfill(5)
'00042'
>>> "-42".zfill(5)
'-0042'
@end example
@end deffn

@node Formatage de chaines à la printf,,Méthodes de chaînes de caractères<2>,Type Séquence de Texte — str
@anchor{library/stdtypes old-string-formatting}@anchor{6b7}@anchor{library/stdtypes printf-style-string-formatting}@anchor{2157}
@subsubsection Formatage de chaines à la @code{printf}


@geindex formatting@comma{} string (%)
@geindex interpolation@comma{} string (%)
@geindex string;formatting@comma{} printf
@geindex string;interpolation@comma{} printf
@geindex printf-style formatting
@geindex sprintf-style formatting
@geindex % (percent);printf-style formatting

@cartouche
@quotation Note 
ces opérations de mise en forme contiennent des bizarreries menant à de nombreuses erreurs classiques (telles que ne pas réussir à afficher des `n'-uplets ou des dictionnaires correctement).  Utiliser les @ref{997,,formatted string literals}, la méthode @ref{60c,,str.format()} ou les @ref{2158,,template strings} aide à éviter ces erreurs.  Chacune de ces alternatives apporte son lot d'avantages et inconvénients en matière de simplicité, de flexibilité et/ou de généralisation possible.
@end quotation
@end cartouche

String objects have one unique built-in operation: the @code{%} operator (modulo).
This is also known as the string `formatting' or `interpolation' operator.
Given @code{format % values} (where `format' is a string), @code{%} conversion
specifications in `format' are replaced with zero or more elements of `values'.
The effect is similar to using the @code{sprintf()} function in the C language.
For example:

@example
>>> print('%s has %d quote types.' % ('Python', 2))
Python has 2 quote types.
@end example

Si `format' ne nécessite qu'un seul argument, `values' peut être un objet unique @footnote{
Pour insérer un `n'-uplet, vous devez donc donner un `n'-uplet d'un seul élément, contenant le `n'-uplet à insérer.
}. Si `values' est un `n'-uplet, il doit contenir exactement le nombre d'éléments spécifiés par la chaîne de format, ou un seul objet tableau de correspondances (`mapping object', par exemple, un dictionnaire).

@geindex () (parentheses);in printf-style formatting
@geindex * (asterisk);in printf-style formatting
@geindex . (dot);in printf-style formatting

Un indicateur de conversion contient deux ou plusieurs caractères et comporte les éléments suivants, qui doivent apparaître dans cet ordre :


@enumerate 

@item 
le caractère @code{'%'}, qui marque le début du marqueur ;

@item 
la clé de correspondance (facultative), composée d'une suite de caractères entre parenthèses (par exemple, @code{(somename)}) ;

@item 
des indications de conversion, facultatives, qui affectent le résultat de certains types de conversion ;

@item 
largeur minimum (facultative). Si elle vaut @code{'*'} (astérisque), la largeur est lue de l'élément suivant du `n'-uplet `values', et l'objet à convertir vient après la largeur de champ minimale et la précision facultative ;

@item 
précision (facultatif), donnée sous la forme d'un @code{'.'} (point) suivi de la précision. Si la précision est @code{'*'} (un astérisque), la précision est lue à partir de l'élément suivant du `n'-uplet `values' et la valeur à convertir vient ensuite ;

@item 
modificateur de longueur (facultatif) ;

@item 
type de conversion.
@end enumerate

Lorsque l'argument de droite est un dictionnaire (ou un autre type de tableau de correspondances), les marqueurs dans la chaîne `doivent' inclure une clé présente dans le dictionnaire, écrite entre parenthèses,  immédiatement après le caractère @code{'%'}. La clé indique quelle valeur du dictionnaire doit être formatée. Par exemple :

@example
>>> print('%(language)s has %(number)03d quote types.' %
...       @{'language': "Python", "number": 2@})
Python has 002 quote types.
@end example

Dans ce cas, aucune @code{*} ne peut se trouver dans le format (car ces @code{*} nécessitent une liste (accès séquentiel) de paramètres).

Les caractères indicateurs de conversion sont :

@geindex # (hash);in printf-style formatting
@geindex - (minus);in printf-style formatting
@geindex + (plus);in printf-style formatting
@geindex space;in printf-style formatting


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@item

@code{'#'}

@tab

La conversion utilise la « forme alternative » (définie ci-dessous).

@item

@code{'0'}

@tab

Les valeurs numériques converties sont complétées de zéros.

@item

@code{'-'}

@tab

La valeur convertie est ajustée à gauche (remplace la conversion @code{'0'} si les deux sont données).

@item

@code{' '}

@tab

(une espace) Une espace doit être laissée avant un nombre positif (ou chaîne vide) produite par la conversion d'une valeur signée.

@item

@code{'+'}

@tab

Un caractère de signe (@code{'+'} ou @code{'-'}) précède la valeur convertie (remplace le marqueur « espace »).

@end multitable


Un modificateur de longueur (@code{h}, @code{l} ou @code{L}) peut être présent, mais est ignoré car il est pas nécessaire pour Python, donc par exemple @code{%ld} est identique à @code{%d}.

Les types utilisables dans les conversions sont :


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Conversion

@tab

Signification

@tab

Notes

@item

@code{'d'}

@tab

Entier décimal signé.

@tab

@item

@code{'i'}

@tab

Entier décimal signé.

@tab

@item

@code{'o'}

@tab

Valeur octale signée.

@tab

(1)

@item

@code{'u'}

@tab

Type obsolète — identique à @code{'d'}.

@tab

(6)

@item

@code{'x'}

@tab

Hexadécimal signé (en minuscules).

@tab

(2)

@item

@code{'X'}

@tab

Hexadécimal signé (capitales).

@tab

(2)

@item

@code{'e'}

@tab

Floating-point exponential format (lowercase).

@tab

(3)

@item

@code{'E'}

@tab

Floating-point exponential format (uppercase).

@tab

(3)

@item

@code{'f'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'F'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'g'}

@tab

Floating-point format. Uses lowercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'G'}

@tab

Floating-point format. Uses uppercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'c'}

@tab

Un seul caractère (accepte des entiers ou une chaîne d'un seul caractère).

@tab

@item

@code{'r'}

@tab

String (convertit n'importe quel objet Python avec @ref{7e7,,repr()}).

@tab

(5)

@item

@code{'s'}

@tab

String (convertit n'importe quel objet Python avec @ref{435,,str()}).

@tab

(5)

@item

@code{'a'}

@tab

String (convertit n'importe quel objet Python en utilisant @ref{139d,,ascii()}).

@tab

(5)

@item

@code{'%'}

@tab

Aucun argument n'est converti, donne un caractère de @code{'%'} dans le résultat.

@tab

@end multitable


Notes :


@enumerate 

@item 
La forme alternative entraîne l'insertion d'un préfixe octal (@code{'0o'}) avant le premier chiffre.

@item 
La forme alternative entraîne l'insertion d'un préfixe @code{'0x'} ou @code{'0X'} (respectivement pour les formats @code{'x'} et @code{'X'}) avant le premier chiffre.

@item 
La forme alternative implique la présence d'un point décimal, même si aucun chiffre ne le suit.

La précision détermine le nombre de chiffres après la virgule, 6 par défaut.

@item 
La forme alternative implique la présence d'un point décimal et les zéros non significatifs sont conservés (ils ne le seraient pas autrement).

La précision détermine le nombre de chiffres significatifs avant et après la virgule. 6 par défaut.

@item 
Si la précision est @code{N}, la sortie est tronquée à @code{N} caractères.

@item 
Voir la 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}.
@end enumerate

Puisque les chaînes Python ont une longueur explicite, les conversions @code{%s} ne considèrent pas @code{'\0'} comme la fin de la chaîne.

@c XXX Examples?


Modifié dans la version 3.1: les conversions @code{%f} des nombres dont la valeur absolue est supérieure à @code{1e50} ne sont plus remplacées par des conversions @code{%g}.


@geindex buffer protocol;binary sequence types

@node Séquences Binaires — bytes bytearray vue mémoire,Types d'ensembles — set frozenset,Type Séquence de Texte — str,Types natifs
@anchor{library/stdtypes binary-sequence-types-bytes-bytearray-memoryview}@anchor{2159}@anchor{library/stdtypes binaryseq}@anchor{20e8}
@subsection Séquences Binaires — @code{bytes}, @code{bytearray}, @code{vue mémoire}


@geindex object;bytes
@geindex object;bytearray
@geindex object;memoryview
@geindex module;array

Les principaux types natifs pour manipuler des données binaires sont @ref{1bd,,bytes} et @ref{528,,bytearray}. Ils sont gérés par les @ref{452,,vues mémoire} qui utilisent le @ref{38e,,protocole tampon} pour accéder à la mémoire d'autres objets binaires sans avoir besoin d'en faire une copie.

Le module @ref{7,,array} permet le stockage efficace de types basiques comme les entiers de 32 bits et les `float' double précision IEEE754.

@menu
* Objets bytes:: 
* Objets bytearray:: 
* Opérations sur les bytes et bytearray:: 
* Formatage de bytes a la printf:: 
* Vues mémoire:: 

@end menu

@node Objets bytes,Objets bytearray,,Séquences Binaires — bytes bytearray vue mémoire
@anchor{library/stdtypes bytes-objects}@anchor{215a}@anchor{library/stdtypes typebytes}@anchor{20ea}
@subsubsection Objets `bytes'


@geindex object;bytes

Les `bytes' sont des séquences immuables d'octets. Comme beaucoup de protocoles binaires utilisent l'ASCII, les objets `bytes' offrent plusieurs méthodes qui ne sont valables que lors de la manipulation de données ASCII et sont étroitement liés aux objets `str' dans bien d'autres aspects.

@geindex bytes (classe de base)
@anchor{library/stdtypes bytes}@anchor{1bd}
@deffn {Classe} bytes ([source[, encoding[, errors]]])

Tout d'abord, la syntaxe des `bytes' littéraux est en grande partie la même que pour les chaînes littérales, en dehors du préfixe @code{b} :


@itemize *

@item 
entre guillemets simples : @code{b'cela autorise les guillemets "doubles"'} ;

@item 
entre guillemets (anglais) : @code{b"cela permet aussi les guillemets 'simples'"} ;

@item 
entre guillemets triples : @code{b'@w{'}'3 single quotes'@w{'}'}, @code{b"""3 double quotes"""}.
@end itemize

Seuls les caractères ASCII sont autorisés dans les littéraux de `bytes' (quel que soit l'encodage du code source déclaré). Toutes les valeurs au-delà de 127 doivent être écrites en utilisant une séquence d'échappement appropriée.

Comme avec les chaînes littérales, les `bytes' littéraux peuvent également utiliser un préfixe @code{r} pour désactiver le traitement des séquences d'échappement. Voir @ref{1e2a,,Littéraux de chaînes de caractères et de suites d'octets} pour plus d'informations sur les différentes formes littérales de `bytes', y compris les séquences d'échappement gérées.

Bien que les `bytes' littéraux, et leur représentation, soient basés sur du texte ASCII, les `bytes' se comportent en fait comme des séquences immuables de nombres entiers, dont les valeurs sont restreintes dans l'intervalle @code{0 <= x < 256} (ne pas respecter cette restriction lève une @ref{1ff,,ValueError}). C'est délibéré afin de souligner que, bien que de nombreux encodages binaires soient compatibles avec l'ASCII, et peuvent être manipulés avec des algorithmes orientés texte, ce n'est généralement pas le cas pour les données binaires arbitraires (appliquer aveuglément des algorithmes de texte sur des données binaires qui ne sont pas compatibles ASCII conduit généralement à leur corruption).

En plus des formes littérales, des objets `bytes' peuvent être créés par de nombreux moyens :


@itemize *

@item 
un objet `bytes' rempli de zéros d'une longueur spécifiée : @code{bytes(10)} ;

@item 
un itérable d'entiers : @code{bytes(range(20))} ;

@item 
la copie de données binaires existantes via le protocole tampon : @code{bytes(obj)}.
@end itemize

Voir aussi la fonction native @ref{1a47,,bytes}.

Puisque 2 chiffres hexadécimaux correspondent précisément à un seul octet, les nombres hexadécimaux sont un format couramment utilisé pour décrire les données binaires. Par conséquent, le type `bytes' a une méthode de classe pour lire des données dans ce format :

@geindex fromhex() (méthode de la classe bytes)
@anchor{library/stdtypes bytes fromhex}@anchor{add}
@deffn {Méthode} classmethod fromhex (string)

Cette méthode de la classe @ref{1bd,,bytes} renvoie un objet `bytes', décodant la chaîne donnée.  La chaîne doit contenir deux chiffres hexadécimaux par octet, les espaces ASCII sont ignorés.

@example
>>> bytes.fromhex('2Ef0 F1f2  ')
b'.\xf0\xf1\xf2'
@end example


Modifié dans la version 3.7: @ref{add,,bytes.fromhex()} saute maintenant dans la chaîne tous les caractères ASCII d'espacement, pas seulement les espaces.

@end deffn

Une fonction de conversion inverse existe pour transformer un objet `bytes' en sa représentation hexadécimale.

@geindex hex() (méthode bytes)
@anchor{library/stdtypes bytes hex}@anchor{d56}
@deffn {Méthode} hex ([sep[, bytes_per_sep]])

Renvoie une chaîne contenant deux chiffres hexadécimaux pour chaque octet de l'instance.

@example
>>> b'\xf0\xf1\xf2'.hex()
'f0f1f2'
@end example

Si vous voulez obtenir une chaîne hexadécimale plus facile à lire, vous pouvez spécifier le paramètre `sep' comme « caractère de séparation », à inclure dans la sortie. Par défaut, ce caractère est inséré entre chaque octet. Un second paramètre optionnel `bytes_per_sep' contrôle l'espacement. Les valeurs positives calculent la position du séparateur en partant de la droite, les valeurs négatives de la gauche.

@example
>>> value = b'\xf0\xf1\xf2'
>>> value.hex('-')
'f0-f1-f2'
>>> value.hex('_', 2)
'f0_f1f2'
>>> b'UUDDLRLRAB'.hex(' ', -4)
'55554444 4c524c52 4142'
@end example


Ajouté dans la version 3.5.



Modifié dans la version 3.8: @ref{d56,,bytes.hex()} prend désormais en charge les paramètres optionnels `sep' et `bytes_per_sep' pour insérer des séparateurs entre les octets dans la sortie hexadécimale.

@end deffn
@end deffn

Comme les objets `bytes' sont des séquences d'entiers (semblables à un `n'-uplet), pour une instance de `bytes' `b', @code{b[0]} est un entier, tandis que @code{b[0:1]} est un objet `bytes' de longueur 1. (Cela contraste avec les chaînes, où un indice et le découpage donnent une chaîne de longueur 1.)

La représentation des `bytes' utilise le format littéral (@code{b'...'}) car il est souvent plus utile que par exemple @code{bytes([46, 46, 46])}. Vous pouvez toujours convertir un `bytes' en liste d'entiers en utilisant @code{list(b)}.

@node Objets bytearray,Opérations sur les bytes et bytearray,Objets bytes,Séquences Binaires — bytes bytearray vue mémoire
@anchor{library/stdtypes bytearray-objects}@anchor{215b}@anchor{library/stdtypes typebytearray}@anchor{20e9}
@subsubsection Objets `bytearray'


@geindex object;bytearray

Les objets @ref{528,,bytearray} sont l'équivalent mutable des objets @ref{1bd,,bytes}.

@geindex bytearray (classe de base)
@anchor{library/stdtypes bytearray}@anchor{528}
@deffn {Classe} bytearray ([source[, encoding[, errors]]])

Il n'y a pas de syntaxe littérale dédiée aux `bytearray', ils sont toujours créés en appelant le constructeur :


@itemize *

@item 
créer une instance vide : @code{bytearray()} ;

@item 
crée une instance remplie de zéros d'une longueur donnée : @code{bytearray(10)} ;

@item 
à partir d'un itérable d'entiers : @code{bytearray(range(20))} ;

@item 
copie des données binaires existantes via le protocole tampon : @code{bytearray(b'Hi!')}.
@end itemize

Comme les `bytearray' sont mutables, ils prennent en charge les opérations de séquences @ref{20e6,,mutables} en plus des opérations communes de `bytes' et `bytearray' décrites dans @ref{20e7,,Opérations sur les bytes et bytearray}.

Voir aussi la fonction native @ref{1a48,,bytearray}.

Puisque 2 chiffres hexadécimaux correspondent précisément à un octet, les nombres hexadécimaux sont un format couramment utilisé pour décrire les données binaires. Par conséquent, le type `bytearray' a une méthode de classe pour lire les données dans ce format :

@geindex fromhex() (méthode de la classe bytearray)
@anchor{library/stdtypes bytearray fromhex}@anchor{ade}
@deffn {Méthode} classmethod fromhex (string)

Cette méthode de la classe @ref{528,,bytearray} renvoie un objet `bytearray', décodant la chaîne donnée.  La chaîne doit contenir deux chiffres hexadécimaux par octet, les caractères d'espacement ASCII sont ignorés.

@example
>>> bytearray.fromhex('2Ef0 F1f2  ')
bytearray(b'.\xf0\xf1\xf2')
@end example


Modifié dans la version 3.7: @ref{ade,,bytearray.fromhex()} saute maintenant tous les caractères d'espacement ASCII dans la chaîne, pas seulement les espaces.

@end deffn

Une fonction de conversion inverse existe pour transformer un objet `bytearray' en sa représentation hexadécimale.

@geindex hex() (méthode bytearray)
@anchor{library/stdtypes bytearray hex}@anchor{d57}
@deffn {Méthode} hex ([sep[, bytes_per_sep]])

Renvoie une chaîne contenant deux chiffres hexadécimaux pour chaque octet de l'instance.

@example
>>> bytearray(b'\xf0\xf1\xf2').hex()
'f0f1f2'
@end example


Ajouté dans la version 3.5.



Modifié dans la version 3.8: similaire à @ref{d56,,bytes.hex()}, @ref{d57,,bytearray.hex()} prend désormais en charge les paramètres optionnels `sep' et `bytes_per_sep' pour insérer des séparateurs entre les octets dans la sortie hexadécimale.

@end deffn
@end deffn

Comme les `bytearray' sont des séquences d'entiers (semblables à une liste), pour un objet `bytearray' `b', @code{b[0]} est un entier, tandis que @code{b[0:1]} est un objet `bytearray' de longueur 1. (Ceci contraste avec les chaînes de texte, où l'indice et le découpage produisent une chaîne de longueur 1)

La représentation des objets `bytearray' utilise le format littéral des `bytes' (@code{bytearray(b'...')}) car il est souvent plus utile que par exemple @code{bytearray([46, 46, 46])}. Vous pouvez toujours convertir un objet `bytearray' en une liste de nombres entiers en utilisant @code{list(b)}.

@node Opérations sur les bytes et bytearray,Formatage de bytes a la printf,Objets bytearray,Séquences Binaires — bytes bytearray vue mémoire
@anchor{library/stdtypes bytes-and-bytearray-operations}@anchor{215c}@anchor{library/stdtypes bytes-methods}@anchor{20e7}
@subsubsection Opérations sur les `bytes' et `bytearray'


@geindex bytes;methods
@geindex bytearray;methods

`bytes' et `bytearray' prennent en charge les opérations @ref{2132,,communes} des séquences. Ils interagissent non seulement avec des opérandes de même type, mais aussi avec les @ref{d1b,,objets octet-compatibles}. En raison de cette flexibilité, ils peuvent être mélangés librement dans des opérations sans provoquer d'erreurs. Cependant, le type du résultat peut dépendre de l'ordre des opérandes.

@cartouche
@quotation Note 
les méthodes sur les `bytes' et les `bytearray' n'acceptent pas les chaînes comme arguments, tout comme les méthodes sur les chaînes n'acceptent pas les `bytes' comme arguments. Par exemple, vous devez écrire :

@example
a = "abc"
b = a.replace("a", "f")
@end example

et :

@example
a = b"abc"
b = a.replace(b"a", b"f")
@end example
@end quotation
@end cartouche

Quelques opérations de `bytes' et `bytesarray' supposent l'utilisation de formats binaires compatibles ASCII, et donc doivent être évités lorsque vous travaillez avec des données binaires arbitraires. Ces restrictions sont couvertes ci-dessous.

@cartouche
@quotation Note 
utiliser ces opérations basées sur l'ASCII pour manipuler des données binaires qui ne sont pas au format ASCII peut les corrompre.
@end quotation
@end cartouche

Les méthodes suivantes sur les `bytes' et `bytearray' peuvent être utilisées avec des données binaires arbitraires.

@geindex count() (méthode bytes)
@geindex count() (méthode bytearray)
@anchor{library/stdtypes bytes count}@anchor{215d}
@deffn {Méthode} bytes.count (sub[, start[, end]])
@anchor{library/stdtypes bytearray count}@anchor{215e}
@deffnx {Méthode} bytearray.count (sub[, start[, end]])

Renvoie le nombre d'occurrences qui ne se chevauchent pas de la  sous-séquence `sub' dans l'intervalle [`start', `end']. Les arguments facultatifs `start' et `end' sont interprétés comme dans la notation des découpages.

La sous-séquence à rechercher peut être un quelconque @ref{d1b,,objet octet-compatible} ou un nombre entier compris entre 0 et 255.

Si `sub' est vide, renvoie le nombre de tranches vides entre les caractères de début et de fin, ce qui correspond à la longueur de l'objet bytes plus un.


Modifié dans la version 3.3: accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.

@end deffn

@geindex removeprefix() (méthode bytes)
@geindex removeprefix() (méthode bytearray)
@anchor{library/stdtypes bytes removeprefix}@anchor{215f}
@deffn {Méthode} bytes.removeprefix (prefix, /)
@anchor{library/stdtypes bytearray removeprefix}@anchor{2160}
@deffnx {Méthode} bytearray.removeprefix (prefix, /)

Si les données binaires commencent par la chaîne `prefix', renvoie @code{bytes[len(prefix):]}. Sinon, renvoie une copie des données binaires d'origine :

@example
>>> b'TestHook'.removeprefix(b'Test')
b'Hook'
>>> b'BaseTestCase'.removeprefix(b'Test')
b'BaseTestCase'
@end example

Le `prefix' peut être n'importe quel @ref{d1b,,objet octet-compatible}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche


Ajouté dans la version 3.9.

@end deffn

@geindex removesuffix() (méthode bytes)
@geindex removesuffix() (méthode bytearray)
@anchor{library/stdtypes bytes removesuffix}@anchor{2161}
@deffn {Méthode} bytes.removesuffix (suffix, /)
@anchor{library/stdtypes bytearray removesuffix}@anchor{2162}
@deffnx {Méthode} bytearray.removesuffix (suffix, /)

Si les données binaires terminent par la chaîne `suffix', renvoie @code{bytes[:-len(suffix)]}. Sinon, renvoie une copie des données binaires d'origine :

@example
>>> b'MiscTests'.removesuffix(b'Tests')
b'Misc'
>>> b'TmpDirMixin'.removesuffix(b'Tests')
b'TmpDirMixin'
@end example

Le `suffix' peut être n'importe quel @ref{d1b,,objet octet-compatible}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche


Ajouté dans la version 3.9.

@end deffn

@geindex decode() (méthode bytes)
@geindex decode() (méthode bytearray)
@anchor{library/stdtypes bytes decode}@anchor{8c3}
@deffn {Méthode} bytes.decode (encoding='utf-8', errors='strict')
@anchor{library/stdtypes bytearray decode}@anchor{2163}
@deffnx {Méthode} bytearray.decode (encoding='utf-8', errors='strict')

Renvoie la chaine d'octets décodée en instance de @ref{435,,str}.

`encoding' vaut par défaut @code{utf-8} ; pour une liste des encodages possibles, voir la section @ref{da6,,Standard Encodings}.

`errors' détermine la manière dont sont traitées les erreurs. Sa valeur par défaut est @code{'strict'}, ce qui signifie que les erreurs d'encodage lèvent une @ref{1281,,UnicodeError}. Les autres valeurs possibles sont @code{'ignore'}, @code{'replace'} et tout autre nom enregistré `via' @ref{144d,,codecs.register_error()}, voir la section @ref{1774,,Gestionnaires d'erreurs} pour les détails.

Pour des raisons de performances, la valeur de `errors' n'est pas vérifiée à moins qu'une erreur de décodage ne se produise réellement, que le @ref{1f5,,mode développeur} ne soit activé ou que Python ait été compilé en @ref{1f6,,mode débogage}.

@cartouche
@quotation Note 
passer l'argument `encoding' à @ref{435,,str} permet de décoder tout @ref{d1b,,objet octet-compatible} directement, sans avoir besoin d'utiliser un @code{bytes} ou @code{bytearray} temporaire.
@end quotation
@end cartouche


Modifié dans la version 3.1: gère les arguments nommés.



Modifié dans la version 3.9: les valeurs de `errors' sont maintenant vérifiées en @ref{1f5,,mode de développement} et en @ref{1f6,,mode de débogage}.

@end deffn

@geindex endswith() (méthode bytes)
@geindex endswith() (méthode bytearray)
@anchor{library/stdtypes bytes endswith}@anchor{2164}
@deffn {Méthode} bytes.endswith (suffix[, start[, end]])
@anchor{library/stdtypes bytearray endswith}@anchor{2165}
@deffnx {Méthode} bytearray.endswith (suffix[, start[, end]])

Renvoie @code{True} si les octets se terminent par `suffix', sinon @code{False}. `suffix' peut aussi être un `n'-uplet de suffixes à rechercher. Avec l'argument optionnel `start', la recherche se fait à partir de cette position. Avec l'argument optionnel `end', la comparaison s'arrête à cette position.

Les suffixes à rechercher peuvent être n'importe quel @ref{d1b,,objet octet-compatible}.
@end deffn

@geindex find() (méthode bytes)
@geindex find() (méthode bytearray)
@anchor{library/stdtypes bytes find}@anchor{17cb}
@deffn {Méthode} bytes.find (sub[, start[, end]])
@anchor{library/stdtypes bytearray find}@anchor{2166}
@deffnx {Méthode} bytearray.find (sub[, start[, end]])

Renvoie la première position où le `sub' se trouve dans les données,  de telle sorte que `sub' soit contenue dans @code{s[start:end]}. Les arguments facultatifs `start' et `end' sont interprétés comme dans la notation des découpages. Renvoie @code{-1} si `sub' n'est pas trouvé.

La sous-séquence à rechercher peut être un quelconque @ref{d1b,,objet octet-compatible} ou un nombre entier compris entre 0 et 255.

@cartouche
@quotation Note 
la méthode @ref{17cb,,find()} ne doit être utilisée que si vous avez besoin de connaître la position de `sub'. Pour vérifier si `sub' est présent ou non, utilisez l'opérateur @ref{2e8,,in} :

@example
>>> b'Py' in b'Python'
True
@end example
@end quotation
@end cartouche


Modifié dans la version 3.3: accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.

@end deffn

@geindex index() (méthode bytes)
@geindex index() (méthode bytearray)
@anchor{library/stdtypes bytes index}@anchor{2167}
@deffn {Méthode} bytes.index (sub[, start[, end]])
@anchor{library/stdtypes bytearray index}@anchor{2168}
@deffnx {Méthode} bytearray.index (sub[, start[, end]])

Comme @ref{17cb,,find()}, mais lève une @ref{1ff,,ValueError} lorsque la séquence est introuvable.

La sous-séquence à rechercher peut être un quelconque @ref{d1b,,objet octet-compatible} ou un nombre entier compris entre 0 et 255.


Modifié dans la version 3.3: accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.

@end deffn

@geindex join() (méthode bytes)
@geindex join() (méthode bytearray)
@anchor{library/stdtypes bytes join}@anchor{2135}
@deffn {Méthode} bytes.join (iterable)
@anchor{library/stdtypes bytearray join}@anchor{2169}
@deffnx {Méthode} bytearray.join (iterable)

Renvoie un `bytes' ou `bytearray' qui est la concaténation des séquences de données binaires dans `iterable'.  Une exception @ref{522,,TypeError} est levée si une valeur d'`iterable' n'est pas un @ref{d1b,,objet octet-compatible}, y compris pour des @ref{435,,str}. Le séparateur entre les éléments est le contenu du `bytes' ou du `bytearray' depuis lequel cette méthode est appelée.
@end deffn

@geindex maketrans() (méthode statique bytes)
@geindex maketrans() (méthode statique bytearray)
@anchor{library/stdtypes bytes maketrans}@anchor{1253}
@deffn {Méthode} static bytes.maketrans (from, to)
@anchor{library/stdtypes bytearray maketrans}@anchor{1254}
@deffnx {Méthode} static bytearray.maketrans (from, to)

Cette méthode statique renvoie une table de traduction utilisable par @ref{216a,,bytes.translate()} qui permettra de changer chaque caractère de `from' par un caractère à la même position dans `to' ; `from' et `to' doivent tous deux être des @ref{d1b,,objets octet-compatibles} et avoir la même longueur.


Ajouté dans la version 3.1.

@end deffn

@geindex partition() (méthode bytes)
@geindex partition() (méthode bytearray)
@anchor{library/stdtypes bytes partition}@anchor{216b}
@deffn {Méthode} bytes.partition (sep)
@anchor{library/stdtypes bytearray partition}@anchor{216c}
@deffnx {Méthode} bytearray.partition (sep)

Divise la séquence à la première occurrence de `sep', et renvoie un triplet contenant la partie précédant le séparateur, le séparateur lui-même (ou sa copie en `byterray'), et la partie suivant le séparateur. Si le séparateur n'est pas trouvé, le triplet renvoyé contient une copie de la séquence d'origine, suivi de deux `bytes' ou `bytearray' vides.

Le séparateur à rechercher peut être tout @ref{d1b,,objet octet-compatible}.
@end deffn

@geindex replace() (méthode bytes)
@geindex replace() (méthode bytearray)
@anchor{library/stdtypes bytes replace}@anchor{216d}
@deffn {Méthode} bytes.replace (old, new[, count])
@anchor{library/stdtypes bytearray replace}@anchor{216e}
@deffnx {Méthode} bytearray.replace (old, new[, count])

Renvoie une copie de la séquence dont toutes les occurrences de la sous-séquence `old' sont remplacées par `new'. Si l'argument optionnel `count' est donné, seules les `count' premières occurrences sont remplacées.

La sous-séquence à rechercher et son remplacement peuvent être n'importe quel @ref{d1b,,objet octet-compatible}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex rfind() (méthode bytes)
@geindex rfind() (méthode bytearray)
@anchor{library/stdtypes bytes rfind}@anchor{17cc}
@deffn {Méthode} bytes.rfind (sub[, start[, end]])
@anchor{library/stdtypes bytearray rfind}@anchor{216f}
@deffnx {Méthode} bytearray.rfind (sub[, start[, end]])

Renvoie la plus grande position de `sub' dans la séquence, de telle sorte que `sub' soit dans @code{s[start:end]}. Les arguments facultatifs `start' et `end' sont interprétés comme dans la notation des découpages. Renvoie @code{-1} si `sub' n'est pas trouvable.

La sous-séquence à rechercher peut être un quelconque @ref{d1b,,objet octet-compatible} ou un nombre entier compris entre 0 et 255.


Modifié dans la version 3.3: accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.

@end deffn

@geindex rindex() (méthode bytes)
@geindex rindex() (méthode bytearray)
@anchor{library/stdtypes bytes rindex}@anchor{2170}
@deffn {Méthode} bytes.rindex (sub[, start[, end]])
@anchor{library/stdtypes bytearray rindex}@anchor{2171}
@deffnx {Méthode} bytearray.rindex (sub[, start[, end]])

Semblable à @ref{17cc,,rfind()} mais lève une @ref{1ff,,ValueError} lorsque `sub' est introuvable.

La sous-séquence à rechercher peut être un quelconque @ref{d1b,,objet octet-compatible} ou un nombre entier compris entre 0 et 255.


Modifié dans la version 3.3: accepte aussi un nombre entier compris entre 0 et 255 comme sous-séquence.

@end deffn

@geindex rpartition() (méthode bytes)
@geindex rpartition() (méthode bytearray)
@anchor{library/stdtypes bytes rpartition}@anchor{2172}
@deffn {Méthode} bytes.rpartition (sep)
@anchor{library/stdtypes bytearray rpartition}@anchor{2173}
@deffnx {Méthode} bytearray.rpartition (sep)

Coupe la séquence à la dernière occurrence de `sep', et renvoie un triplet de trois éléments contenant la partie précédant le séparateur, le séparateur lui-même (ou sa copie, un `bytearray'), et la partie suivant le séparateur. Si le séparateur n'est pas trouvé, le triplet contient deux `bytes' ou `bytesarray' vides suivi d’une copie de la séquence d'origine.

Le séparateur à rechercher peut être tout @ref{d1b,,objet octet-compatible}.
@end deffn

@geindex startswith() (méthode bytes)
@geindex startswith() (méthode bytearray)
@anchor{library/stdtypes bytes startswith}@anchor{2174}
@deffn {Méthode} bytes.startswith (prefix[, start[, end]])
@anchor{library/stdtypes bytearray startswith}@anchor{2175}
@deffnx {Méthode} bytearray.startswith (prefix[, start[, end]])

Renvoie @code{True} si les données binaires commencent par le `prefix' spécifié, sinon @code{False}. `prefix' peut aussi être un `n'-uplet de préfixes à rechercher. Avec l'argument `start' la recherche commence à cette position. Avec l'argument `end' option, la recherche s'arrête à cette position.

Les préfixes à rechercher peuvent être n'importe quels @ref{d1b,,objets octet-compatibles}.
@end deffn

@geindex translate() (méthode bytes)
@geindex translate() (méthode bytearray)
@anchor{library/stdtypes bytes translate}@anchor{216a}
@deffn {Méthode} bytes.translate (table, /, delete=b'@w{'})
@anchor{library/stdtypes bytearray translate}@anchor{12d9}
@deffnx {Méthode} bytearray.translate (table, /, delete=b'@w{'})

Renvoie une copie du `bytes' ou `bytearray' dont tous les octets de  `delete' sont supprimés, et les octets restants changés par la table de correspondance donnée, qui doit être un objet `bytes' d'une longueur de 256.

Vous pouvez utiliser la méthode @ref{1253,,bytes.maketrans()} pour créer une table de correspondance.

Donnez @code{None} comme `table' pour seulement supprimer des caractères :

@example
>>> b'read this short text'.translate(None, b'aeiou')
b'rd ths shrt txt'
@end example


Modifié dans la version 3.6: `delete' est maintenant accepté comme argument nommé.

@end deffn

Les méthodes suivantes sur les `bytes' et `bytearray' supposent par défaut que les données traitées sont compatibles ASCII, mais peuvent toujours être utilisées avec des données binaires, arbitraires, en passant des arguments appropriés. Notez que toutes les méthodes de `bytearray' de cette section ne travaillent jamais sur l'objet lui-même, mais renvoient un nouvel objet.

@geindex center() (méthode bytes)
@geindex center() (méthode bytearray)
@anchor{library/stdtypes bytes center}@anchor{2176}
@deffn {Méthode} bytes.center (width[, fillbyte])
@anchor{library/stdtypes bytearray center}@anchor{2177}
@deffnx {Méthode} bytearray.center (width[, fillbyte])

Renvoie une copie de l'objet centrée dans une séquence de longueur `width'. Le remplissage est fait en utilisant `fillbyte' (qui par défaut est une espace ASCII). Pour les objets @ref{1bd,,bytes}, la séquence initiale est renvoyée si `width' est inférieure ou égale à @code{len(s)}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex ljust() (méthode bytes)
@geindex ljust() (méthode bytearray)
@anchor{library/stdtypes bytes ljust}@anchor{2178}
@deffn {Méthode} bytes.ljust (width[, fillbyte])
@anchor{library/stdtypes bytearray ljust}@anchor{2179}
@deffnx {Méthode} bytearray.ljust (width[, fillbyte])

Renvoie une copie de l'objet aligné à gauche dans une séquence de longueur `width'. Le remplissage est fait en utilisant `fillbyte' (par défaut un espace ASCII). Pour les objets @ref{1bd,,bytes}, la séquence initiale est renvoyée si `width' est inférieure ou égale à @code{len(s)}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex lstrip() (méthode bytes)
@geindex lstrip() (méthode bytearray)
@anchor{library/stdtypes bytes lstrip}@anchor{217a}
@deffn {Méthode} bytes.lstrip ([chars])
@anchor{library/stdtypes bytearray lstrip}@anchor{217b}
@deffnx {Méthode} bytearray.lstrip ([chars])

Renvoie une copie de la séquence dont certains préfixes ont été supprimés. L’argument `chars' est une séquence binaire spécifiant le jeu d'octets à supprimer. Ce nom se réfère au fait de cette méthode est généralement utilisée avec des caractères ASCII. En cas d’omission ou @code{None}, la valeur par défaut de `chars' permet de supprimer des espaces ASCII. L’argument `chars' n’est pas un préfixe, toutes les combinaisons de ses valeurs sont supprimées :

@example
>>> b'   spacious   '.lstrip()
b'spacious   '
>>> b'www.example.com'.lstrip(b'cmowz.')
b'example.com'
@end example

Les octets à retirer peuvent être n'importe quel @ref{d1b,,bytes-like object}. Voir @ref{215f,,removeprefix()} pour une méthode qui supprime, au début de la séquence, la chaîne de caractères en tant que telle plutôt que l'ensemble des caractères passés en paramètre. Par exemple :

@example
>>> b'Arthur: three!'.lstrip(b'Arthur: ')
b'ee!'
>>> b'Arthur: three!'.removeprefix(b'Arthur: ')
b'three!'
@end example

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex rjust() (méthode bytes)
@geindex rjust() (méthode bytearray)
@anchor{library/stdtypes bytes rjust}@anchor{217c}
@deffn {Méthode} bytes.rjust (width[, fillbyte])
@anchor{library/stdtypes bytearray rjust}@anchor{217d}
@deffnx {Méthode} bytearray.rjust (width[, fillbyte])

Renvoie une copie de l'objet justifié à droite dans une séquence de longueur `width'. Le remplissage est fait en utilisant le caractère `fillbyte' (par défaut est un espace ASCII). Pour les objets @ref{1bd,,bytes}, la séquence d'origine est renvoyée si `width' est inférieure ou égale à @code{len(s)}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex rsplit() (méthode bytes)
@geindex rsplit() (méthode bytearray)
@anchor{library/stdtypes bytes rsplit}@anchor{217e}
@deffn {Méthode} bytes.rsplit (sep=None, maxsplit=-1)
@anchor{library/stdtypes bytearray rsplit}@anchor{217f}
@deffnx {Méthode} bytearray.rsplit (sep=None, maxsplit=-1)

Divise la séquence d'octets en sous-séquences du même type, en utilisant `sep' comme séparateur. Si `maxsplit' est donné, c'est le nombre maximum de divisions qui pourront être faites, celles "à droite". Si `sep' est pas spécifié ou est @code{None}, toute sous-séquence composée uniquement d'espaces ASCII est un séparateur. En dehors du fait qu'il découpe par la droite, @ref{217f,,rsplit()} se comporte comme @ref{2180,,split()} qui est décrit en détail ci-dessous.
@end deffn

@geindex rstrip() (méthode bytes)
@geindex rstrip() (méthode bytearray)
@anchor{library/stdtypes bytes rstrip}@anchor{2181}
@deffn {Méthode} bytes.rstrip ([chars])
@anchor{library/stdtypes bytearray rstrip}@anchor{2182}
@deffnx {Méthode} bytearray.rstrip ([chars])

Renvoie une copie de la séquence dont des octets finaux sont supprimés. L'argument `chars' est une séquence d'octets spécifiant le jeu de caractères à supprimer. En cas d'omission ou @code{None}, les espaces ASCII sont supprimées. L'argument `chars' n'est pas un suffixe : toutes les combinaisons de ses valeurs sont retirées :

@example
>>> b'   spacious   '.rstrip()
b'   spacious'
>>> b'mississippi'.rstrip(b'ipz')
b'mississ'
@end example

Les octets à retirer peuvent être n'importe quel @ref{d1b,,bytes-like object}. Voir @ref{2161,,removesuffix()} pour une méthode qui supprime, à la fin de la séquence, la chaîne de caractères en tant que telle plutôt que l'ensemble des caractères passés en paramètre. Par exemple :

@example
>>> b'Monty Python'.rstrip(b' Python')
b'M'
>>> b'Monty Python'.removesuffix(b' Python')
b'Monty'
@end example

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex split() (méthode bytes)
@geindex split() (méthode bytearray)
@anchor{library/stdtypes bytes split}@anchor{2183}
@deffn {Méthode} bytes.split (sep=None, maxsplit=-1)
@anchor{library/stdtypes bytearray split}@anchor{2180}
@deffnx {Méthode} bytearray.split (sep=None, maxsplit=-1)

Divise la séquence en sous-séquences du même type, en utilisant `sep' comme séparateur. Si `maxsplit' est donné, c'est le nombre maximum de divisions qui pourront être faites (la liste aura donc au plus @code{maxsplit+1} éléments), Si `maxsplit' n'est pas spécifié ou faut @code{-1}, il n'y a aucune limite au nombre de découpes (elles sont toutes effectuées).

If `sep' is given, consecutive delimiters are not grouped together and are
deemed to delimit empty subsequences (for example, @code{b'1,,2'.split(b',')}
returns @code{[b'1', b'@w{'}, b'2']}).  The `sep' argument may consist of a
multibyte sequence as a single delimiter. Splitting an empty sequence with
a specified separator returns @code{[b'@w{'}]} or @code{[bytearray(b'@w{'})]} depending
on the type of object being split.  The `sep' argument may be any
@ref{d1b,,bytes-like object}.

Par exemple :

@example
>>> b'1,2,3'.split(b',')
[b'1', b'2', b'3']
>>> b'1,2,3'.split(b',', maxsplit=1)
[b'1', b'2,3']
>>> b'1,2,,3,'.split(b',')
[b'1', b'2', b'@w{'}, b'3', b'@w{'}]
>>> b'1<>2<>3<4'.split(b'<>')
[b'1', b'2', b'3<4']
@end example

Si `sep' n'est pas spécifié ou est @code{None}, un autre algorithme de découpe est appliqué : les espaces ASCII consécutifs sont considérés comme un seul séparateur, et le résultat ne contiendra pas les chaînes vides de début ou de la fin si la chaîne est préfixée ou suffixé d'espaces. Par conséquent, diviser une séquence vide ou une séquence composée d'espaces ASCII avec un séparateur @code{None} renvoie @code{[]}.

Par exemple :

@example
>>> b'1 2 3'.split()
[b'1', b'2', b'3']
>>> b'1 2 3'.split(maxsplit=1)
[b'1', b'2 3']
>>> b'   1   2   3   '.split()
[b'1', b'2', b'3']
@end example
@end deffn

@geindex strip() (méthode bytes)
@geindex strip() (méthode bytearray)
@anchor{library/stdtypes bytes strip}@anchor{2184}
@deffn {Méthode} bytes.strip ([chars])
@anchor{library/stdtypes bytearray strip}@anchor{2185}
@deffnx {Méthode} bytearray.strip ([chars])

Renvoie une copie de la séquence dont des caractères initiaux et finaux sont supprimés. L'argument `chars' est une séquence spécifiant le jeu d'octets à supprimer, le nom se réfère au fait de cette méthode est généralement utilisée avec des caractères ASCII. En cas d'omission ou @code{None}, les espaces ASCII sont supprimés. L'argument `chars' n'est ni un préfixe ni un suffixe, toutes les combinaisons de ses valeurs sont supprimées :

@example
>>> b'   spacious   '.strip()
b'spacious'
>>> b'www.example.com'.strip(b'cmowz.')
b'example'
@end example

Les octets à retirer peuvent être tout @ref{d1b,,bytes-like object}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

Les méthodes suivantes sur les `bytes' et `bytearray' supposent l'utilisation d'un format binaire compatible ASCII, et donc doivent être évités lorsque vous travaillez avec des données binaires arbitraires. Notez que toutes les méthodes de `bytearray' de cette section `ne modifient pas' les octets, ils produisent de nouveaux objets.

@geindex capitalize() (méthode bytes)
@geindex capitalize() (méthode bytearray)
@anchor{library/stdtypes bytes capitalize}@anchor{2186}
@deffn {Méthode} bytes.capitalize ()
@anchor{library/stdtypes bytearray capitalize}@anchor{2187}
@deffnx {Méthode} bytearray.capitalize ()

Renvoie une copie de la séquence dont chaque octet est interprété comme un caractère ASCII, le premier octet en capitale et le reste en minuscules. Les octets non ASCII ne sont pas modifiés.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex expandtabs() (méthode bytes)
@geindex expandtabs() (méthode bytearray)
@anchor{library/stdtypes bytes expandtabs}@anchor{2188}
@deffn {Méthode} bytes.expandtabs (tabsize=8)
@anchor{library/stdtypes bytearray expandtabs}@anchor{2189}
@deffnx {Méthode} bytearray.expandtabs (tabsize=8)

Renvoie une copie de la séquence où toutes les tabulations ASCII sont remplacées par un ou plusieurs espaces ASCII, en fonction de la colonne courante et de la taille de tabulation donnée. Les positions des tabulations se trouvent tous les `tabsize' caractères (8 par défaut, ce qui donne les positions de tabulations aux colonnes 0, 8, 16 et ainsi de suite). Pour travailler sur la séquence, la colonne en cours est mise à zéro et la séquence est examinée octets par octets. Si l'octet est une tabulation ASCII (@code{b'\t'}), un ou plusieurs espaces sont insérés au résultat jusqu’à ce que la colonne courante soit égale à la position de tabulation suivante. (Le caractère tabulation lui-même n’est pas copié.) Si l'octet courant est un saut de ligne ASCII (@code{b'\n'}) ou un retour chariot (@code{b'\r'}), il est copié et la colonne en cours est remise à zéro. Tout autre octet est copié inchangé et la colonne en cours est incrémentée de un indépendamment de la façon dont l'octet est représenté lors de l’affichage :

@example
>>> b'01\t012\t0123\t01234'.expandtabs()
b'01      012     0123    01234'
>>> b'01\t012\t0123\t01234'.expandtabs(4)
b'01  012 0123    01234'
@end example

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex isalnum() (méthode bytes)
@geindex isalnum() (méthode bytearray)
@anchor{library/stdtypes bytes isalnum}@anchor{218a}
@deffn {Méthode} bytes.isalnum ()
@anchor{library/stdtypes bytearray isalnum}@anchor{218b}
@deffnx {Méthode} bytearray.isalnum ()

Renvoie @code{True} si tous les caractères de la chaîne sont des caractères ASCII alphabétiques ou chiffres et que la séquence n'est pas vide, sinon @code{False}. Les caractères ASCII alphabétiques sont les suivants dans la séquence d'octets @code{b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'} et les chiffres : @code{b'0123456789'}.

Par exemple :

@example
>>> b'ABCabc1'.isalnum()
True
>>> b'ABC abc1'.isalnum()
False
@end example
@end deffn

@geindex isalpha() (méthode bytes)
@geindex isalpha() (méthode bytearray)
@anchor{library/stdtypes bytes isalpha}@anchor{218c}
@deffn {Méthode} bytes.isalpha ()
@anchor{library/stdtypes bytearray isalpha}@anchor{218d}
@deffnx {Méthode} bytearray.isalpha ()

Renvoie @code{True} si tous les octets dans la séquence sont des caractères alphabétiques ASCII et que la séquence n'est pas vide, sinon @code{False}. Les caractères ASCII alphabétiques sont : @code{b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

Par exemple :

@example
>>> b'ABCabc'.isalpha()
True
>>> b'ABCabc1'.isalpha()
False
@end example
@end deffn

@geindex isascii() (méthode bytes)
@geindex isascii() (méthode bytearray)
@anchor{library/stdtypes bytes isascii}@anchor{218e}
@deffn {Méthode} bytes.isascii ()
@anchor{library/stdtypes bytearray isascii}@anchor{218f}
@deffnx {Méthode} bytearray.isascii ()

Renvoie @code{True} si la séquence est vide, ou si tous ses octets sont des octets ASCII, renvoie @code{False} dans le cas contraire. Les octets ASCII dans l'intervalle @code{0}–@code{0x7F}.


Ajouté dans la version 3.7.

@end deffn

@geindex isdigit() (méthode bytes)
@geindex isdigit() (méthode bytearray)
@anchor{library/stdtypes bytes isdigit}@anchor{2190}
@deffn {Méthode} bytes.isdigit ()
@anchor{library/stdtypes bytearray isdigit}@anchor{2191}
@deffnx {Méthode} bytearray.isdigit ()

Renvoie @code{True} si tous les octets de la séquence sont des chiffres ASCII et que la séquence n'est pas vide, sinon @code{False}. Les chiffres ASCII sont ceux dans la séquence d'octets @code{b'0123456789'}.

Par exemple :

@example
>>> b'1234'.isdigit()
True
>>> b'1.23'.isdigit()
False
@end example
@end deffn

@geindex islower() (méthode bytes)
@geindex islower() (méthode bytearray)
@anchor{library/stdtypes bytes islower}@anchor{2192}
@deffn {Méthode} bytes.islower ()
@anchor{library/stdtypes bytearray islower}@anchor{2193}
@deffnx {Méthode} bytearray.islower ()

Renvoie @code{True} s'il y a au moins un caractère ASCII minuscule dans la séquence et aucune capitale, sinon @code{False}.

Par exemple :

@example
>>> b'hello world'.islower()
True
>>> b'Hello world'.islower()
False
@end example

Les caractères ASCII minuscules sont @code{b'abcdefghijklmnopqrstuvwxyz'}. Les capitales ASCII sont @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
@end deffn

@geindex isspace() (méthode bytes)
@geindex isspace() (méthode bytearray)
@anchor{library/stdtypes bytes isspace}@anchor{2194}
@deffn {Méthode} bytes.isspace ()
@anchor{library/stdtypes bytearray isspace}@anchor{2195}
@deffnx {Méthode} bytearray.isspace ()

Renvoie @code{True} si tous les octets de la séquence sont des espaces ASCII et que la séquence n'est pas vide, sinon @code{False}. Les espèces ASCII sont @code{b' \t\n\r\x0b\f'} (espace, tabulation, saut de ligne, retour chariot, tabulation verticale, saut de page).
@end deffn

@geindex istitle() (méthode bytes)
@geindex istitle() (méthode bytearray)
@anchor{library/stdtypes bytes istitle}@anchor{2196}
@deffn {Méthode} bytes.istitle ()
@anchor{library/stdtypes bytearray istitle}@anchor{2197}
@deffnx {Méthode} bytearray.istitle ()

Renvoie @code{True} si la séquence ASCII est `titlecased', et qu'elle n'est pas vide, sinon @code{False}. Voir @ref{2198,,bytes.title()} pour plus de détails sur la définition de `titlecase'.

Par exemple :

@example
>>> b'Hello World'.istitle()
True
>>> b'Hello world'.istitle()
False
@end example
@end deffn

@geindex isupper() (méthode bytes)
@geindex isupper() (méthode bytearray)
@anchor{library/stdtypes bytes isupper}@anchor{2199}
@deffn {Méthode} bytes.isupper ()
@anchor{library/stdtypes bytearray isupper}@anchor{219a}
@deffnx {Méthode} bytearray.isupper ()

Renvoie @code{True} s'il y a au moins un caractère alphabétique majuscule ASCII dans la séquence et aucun caractère ASCII minuscule, sinon @code{False}.

Par exemple :

@example
>>> b'HELLO WORLD'.isupper()
True
>>> b'Hello world'.isupper()
False
@end example

Les caractères ASCII minuscules sont @code{b'abcdefghijklmnopqrstuvwxyz'}. Les capitales ASCII sont @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
@end deffn

@geindex lower() (méthode bytes)
@geindex lower() (méthode bytearray)
@anchor{library/stdtypes bytes lower}@anchor{219b}
@deffn {Méthode} bytes.lower ()
@anchor{library/stdtypes bytearray lower}@anchor{219c}
@deffnx {Méthode} bytearray.lower ()

Renvoie une copie de la séquence dont tous les caractères ASCII en majuscules sont convertis en leur équivalent en minuscules.

Par exemple :

@example
>>> b'Hello World'.lower()
b'hello world'
@end example

Les caractères ASCII minuscules sont @code{b'abcdefghijklmnopqrstuvwxyz'}. Les capitales ASCII sont @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex universal newlines;bytes.splitlines method
@geindex universal newlines;bytearray.splitlines method

@geindex splitlines() (méthode bytes)
@geindex splitlines() (méthode bytearray)
@anchor{library/stdtypes bytes splitlines}@anchor{219d}
@deffn {Méthode} bytes.splitlines (keepends=False)
@anchor{library/stdtypes bytearray splitlines}@anchor{219e}
@deffnx {Méthode} bytearray.splitlines (keepends=False)

Renvoie une liste des lignes de la séquence d'octets, découpant au niveau des fin de lignes ASCII. Cette méthode utilise l'approche @ref{d28,,universal newlines} pour découper les lignes. Les fins de ligne ne sont pas inclus dans la liste des résultats, sauf si `keepends' est donné et vrai.

Par exemple :

@example
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines()
[b'ab c', b'@w{'}, b'de fg', b'kl']
>>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
[b'ab c\n', b'\n', b'de fg\r', b'kl\r\n']
@end example

Contrairement à @ref{2183,,split()} lorsque le délimiteur `sep' est fourni, cette méthode renvoie une liste vide pour la chaîne vide, et un saut de ligne à la fin ne se traduit pas par une ligne supplémentaire :

@example
>>> b"".split(b'\n'), b"Two lines\n".split(b'\n')
([b'@w{'}], [b'Two lines', b'@w{'}])
>>> b"".splitlines(), b"One line\n".splitlines()
([], [b'One line'])
@end example
@end deffn

@geindex swapcase() (méthode bytes)
@geindex swapcase() (méthode bytearray)
@anchor{library/stdtypes bytes swapcase}@anchor{219f}
@deffn {Méthode} bytes.swapcase ()
@anchor{library/stdtypes bytearray swapcase}@anchor{21a0}
@deffnx {Méthode} bytearray.swapcase ()

Renvoie une copie de la séquence dont tous les caractères ASCII minuscules sont convertis en majuscules et vice-versa.

Par exemple :

@example
>>> b'Hello World'.swapcase()
b'hELLO wORLD'
@end example

Les caractères ASCII minuscules sont @code{b'abcdefghijklmnopqrstuvwxyz'}. Les capitales ASCII sont @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

Unlike @ref{2152,,str.swapcase()}, it is always the case that
@code{bin.swapcase().swapcase() == bin} for the binary versions. Case
conversions are symmetrical in ASCII, even though that is not generally
true for arbitrary Unicode code points.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex title() (méthode bytes)
@geindex title() (méthode bytearray)
@anchor{library/stdtypes bytes title}@anchor{2198}
@deffn {Méthode} bytes.title ()
@anchor{library/stdtypes bytearray title}@anchor{21a1}
@deffnx {Méthode} bytearray.title ()

Renvoie une version `titlecased' de la séquence d'octets où les mots commencent par un caractère ASCII majuscule et les caractères restants sont en minuscules. Les octets non capitalisables ne sont pas modifiés.

Par exemple :

@example
>>> b'Hello world'.title()
b'Hello World'
@end example

Les caractères ASCII minuscules sont @code{b'abcdefghijklmnopqrstuvwxyz'}. Les caractères ASCII majuscules sont @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Aucun autre octet n'est capitalisable.

Pour l'algorithme, la notion de mot est définie simplement et indépendamment de la langue comme un groupe de lettres consécutives. La définition fonctionne dans de nombreux contextes, mais cela signifie que les apostrophes (typiquement de la forme possessive en Anglais) forment les limites de mot, ce qui n'est pas toujours le résultat souhaité :

@example
>>> b"they're bill's friends from the UK".title()
b"They'Re Bill'S Friends From The Uk"
@end example

Une solution pour contourner le problème des apostrophes peut être obtenue en utilisant des expressions rationnelles :

@example
>>> import re
>>> def titlecase(s):
...     return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?",
...                   lambda mo: mo.group(0)[0:1].upper() +
...                              mo.group(0)[1:].lower(),
...                   s)
...
>>> titlecase(b"they're bill's friends.")
b"They're Bill's Friends."
@end example

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex upper() (méthode bytes)
@geindex upper() (méthode bytearray)
@anchor{library/stdtypes bytes upper}@anchor{21a2}
@deffn {Méthode} bytes.upper ()
@anchor{library/stdtypes bytearray upper}@anchor{21a3}
@deffnx {Méthode} bytearray.upper ()

Renvoie une copie de la séquence dont tous les caractères ASCII minuscules sont convertis en leur équivalent majuscule.

Par exemple :

@example
>>> b'Hello World'.upper()
b'HELLO WORLD'
@end example

Les caractères ASCII minuscules sont @code{b'abcdefghijklmnopqrstuvwxyz'}. Les capitales ASCII sont @code{b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@geindex zfill() (méthode bytes)
@geindex zfill() (méthode bytearray)
@anchor{library/stdtypes bytes zfill}@anchor{21a4}
@deffn {Méthode} bytes.zfill (width)
@anchor{library/stdtypes bytearray zfill}@anchor{21a5}
@deffnx {Méthode} bytearray.zfill (width)

Renvoie une copie de la séquence remplie par la gauche du chiffre @code{b'0'} pour en faire une séquence de longueur `width'. Un préfixe (@code{b'+'} / @code{b'-'}) est permis par l'insertion du caractère de remplissage `après' le caractère de signe plutôt qu'avant. Pour les objets @ref{1bd,,bytes} la séquence d'origine est renvoyée si `width' est inférieur ou égale à @code{len(seq)}.

Par exemple :

@example
>>> b"42".zfill(5)
b'00042'
>>> b"-42".zfill(5)
b'-0042'
@end example

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche
@end deffn

@node Formatage de bytes a la printf,Vues mémoire,Opérations sur les bytes et bytearray,Séquences Binaires — bytes bytearray vue mémoire
@anchor{library/stdtypes bytes-formatting}@anchor{d6e}@anchor{library/stdtypes printf-style-bytes-formatting}@anchor{21a6}
@subsubsection Formatage de `bytes' a la @code{printf}


@geindex formatting;bytes (%)
@geindex formatting;bytearray (%)
@geindex interpolation;bytes (%)
@geindex interpolation;bytearray (%)
@geindex bytes;formatting
@geindex bytearray;formatting
@geindex bytes;interpolation
@geindex bytearray;interpolation
@geindex printf-style formatting
@geindex sprintf-style formatting
@geindex % (percent);printf-style formatting

@cartouche
@quotation Note 
Les opérations de formatage décrites ici présentent une variété de bizarreries qui conduisent à un certain nombre d’erreurs classiques (typiquement, échouer à afficher des `n'-uplets ou des dictionnaires correctement). Si la valeur à afficher peut être un `n'-uplet ou un dictionnaire, mettez-le à l'intérieur d'un autre `n'-uplet.
@end quotation
@end cartouche

Les objets `bytes' (@code{bytes} et @code{bytearray}) ont un unique opérateur : l'opérateur @code{%} (modulo). Il est aussi connu sous le nom d'opérateur de mise en forme. Avec @code{format % values} (où `format' est un objet `bytes'), les marqueurs de conversion @code{%} dans `format' sont remplacés par zéro ou plus de `values'. L'effet est similaire à la fonction @code{sprintf()} du langage C.

Si `format' ne nécessite qu'un seul argument, `values' peut être un objet unique. @footnote{
Pour insérer un `n'-uplet, vous devez donc donner un `n'-uplet d'un seul élément, contenant le `n'-uplet à insérer.
} Si `values' est un `n'-uplet, il doit contenir exactement le nombre d'éléments spécifiés dans le format en `bytes', ou un seul objet de correspondances (`mapping object', par exemple, un dictionnaire).

@geindex () (parentheses);in printf-style formatting
@geindex * (asterisk);in printf-style formatting
@geindex . (dot);in printf-style formatting

Un indicateur de conversion contient deux ou plusieurs caractères et comporte les éléments suivants, qui doivent apparaître dans cet ordre :


@enumerate 

@item 
le caractère @code{'%'}, qui marque le début du marqueur ;

@item 
la clé de correspondance (facultative), composée d'une suite de caractères entre parenthèses (par exemple, @code{(somename)}) ;

@item 
des indications de conversion, facultatives, qui affectent le résultat de certains types de conversion ;

@item 
largeur minimum (facultative). Si elle vaut @code{'*'} (astérisque), la largeur est lue de l'élément suivant du `n'-uplet `values', et l'objet à convertir vient après la largeur de champ minimale et la précision facultative ;

@item 
précision (facultatif), donnée sous la forme d'un @code{'.'} (point) suivi de la précision. Si la précision est @code{'*'} (un astérisque), la précision est lue à partir de l'élément suivant du `n'-uplet `values' et la valeur à convertir vient ensuite ;

@item 
modificateur de longueur (facultatif) ;

@item 
type de conversion.
@end enumerate

Lorsque l'argument de droite est un dictionnaire (ou un autre type de `mapping'), les marqueurs dans le `bytes' `doivent' inclure une clé présente dans le dictionnaire, écrite entre parenthèses,  immédiatement après le caractère @code{'%'}. La clé indique quelle valeur du dictionnaire doit être formatée. Par exemple :

@example
>>> print(b'%(language)s has %(number)03d quote types.' %
...       @{b'language': b"Python", b"number": 2@})
b'Python has 002 quote types.'
@end example

Dans ce cas, aucune @code{*} ne peut se trouver dans le format (car ces @code{*} nécessitent une liste (accès séquentiel) de paramètres).

Les caractères indicateurs de conversion sont :

@geindex # (hash);in printf-style formatting
@geindex - (minus);in printf-style formatting
@geindex + (plus);in printf-style formatting
@geindex space;in printf-style formatting


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@item

@code{'#'}

@tab

La conversion utilise la « forme alternative » (définie ci-dessous).

@item

@code{'0'}

@tab

Les valeurs numériques converties sont complétées de zéros.

@item

@code{'-'}

@tab

La valeur convertie est ajustée à gauche (remplace la conversion @code{'0'} si les deux sont données).

@item

@code{' '}

@tab

(une espace) Une espace doit être laissée avant un nombre positif (ou chaîne vide) produite par la conversion d'une valeur signée.

@item

@code{'+'}

@tab

Un caractère de signe (@code{'+'} ou @code{'-'}) précède la valeur convertie (remplace le marqueur « espace »).

@end multitable


Un modificateur de longueur (@code{h}, @code{l} ou @code{L}) peut être présent, mais est ignoré car il est pas nécessaire pour Python, donc par exemple @code{%ld} est identique à @code{%d}.

Les types utilisables dans les conversions sont :


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Conversion

@tab

Signification

@tab

Notes

@item

@code{'d'}

@tab

Entier décimal signé.

@tab

@item

@code{'i'}

@tab

Entier décimal signé.

@tab

@item

@code{'o'}

@tab

Valeur octale signée.

@tab

(1)

@item

@code{'u'}

@tab

Type obsolète — identique à @code{'d'}.

@tab

(8)

@item

@code{'x'}

@tab

Hexadécimal signé (en minuscules).

@tab

(2)

@item

@code{'X'}

@tab

Hexadécimal signé (capitales).

@tab

(2)

@item

@code{'e'}

@tab

Floating-point exponential format (lowercase).

@tab

(3)

@item

@code{'E'}

@tab

Floating-point exponential format (uppercase).

@tab

(3)

@item

@code{'f'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'F'}

@tab

Floating-point decimal format.

@tab

(3)

@item

@code{'g'}

@tab

Floating-point format. Uses lowercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'G'}

@tab

Floating-point format. Uses uppercase exponential
format if exponent is less than -4 or not less than
precision, decimal format otherwise.

@tab

(4)

@item

@code{'c'}

@tab

Octet simple (Accepte un nombre entier ou un seul objet `byte').

@tab

@item

@code{'b'}

@tab

Bytes (any object that follows the
@ref{38e,,buffer protocol} or has
@ref{5d2,,__bytes__()}).

@tab

(5)

@item

@code{'s'}

@tab

@code{'s'} est un alias de @code{'b'} et ne devrait être utilisé que pour du code Python2/3.

@tab

(6)

@item

@code{'a'}

@tab

`Bytes' (convertit n'importe quel objet Python en utilisant @code{repr(obj).encode('ascii', 'backslashreplace)}).

@tab

(5)

@item

@code{'r'}

@tab

@code{'r'} est un alias de @code{'a'} et ne devrait être utilise que dans du code Python2/3.

@tab

(7)

@item

@code{'%'}

@tab

Aucun argument n'est converti, donne un caractère de @code{'%'} dans le résultat.

@tab

@end multitable


Notes :


@enumerate 

@item 
La forme alternative entraîne l'insertion d'un préfixe octal (@code{'0o'}) avant le premier chiffre.

@item 
La forme alternative entraîne l'insertion d'un préfixe @code{'0x'} ou @code{'0X'} (respectivement pour les formats @code{'x'} et @code{'X'}) avant le premier chiffre.

@item 
La forme alternative implique la présence d'un point décimal, même si aucun chiffre ne le suit.

La précision détermine le nombre de chiffres après la virgule, 6 par défaut.

@item 
La forme alternative implique la présence d'un point décimal et les zéros non significatifs sont conservés (ils ne le seraient pas autrement).

La précision détermine le nombre de chiffres significatifs avant et après la virgule. 6 par défaut.

@item 
Si la précision est @code{N}, la sortie est tronquée à @code{N} caractères.

@item 
@code{b'%s'} est obsolète, mais ne sera pas retiré des version 3.x.

@item 
@code{b'%r'} est obsolète mais ne sera pas retiré dans Python 3.x.

@item 
Voir la 
@geindex Python Enhancement Proposals; PEP 237
PEP 237@footnote{https://peps.python.org/pep-0237/}.
@end enumerate

@cartouche
@quotation Note 
la version `bytearray' de cette méthode `ne modifie pas' les octets,  elle produit toujours un nouvel objet, même si aucune modification n'a été effectuée.
@end quotation
@end cartouche


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 461
PEP 461@footnote{https://peps.python.org/pep-0461/} -- Ajout du formatage via % aux `bytes' et `bytesarray'



Ajouté dans la version 3.5.


@node Vues mémoire,,Formatage de bytes a la printf,Séquences Binaires — bytes bytearray vue mémoire
@anchor{library/stdtypes memory-views}@anchor{21a7}@anchor{library/stdtypes typememoryview}@anchor{20fe}
@subsubsection Vues mémoire


Les @ref{452,,vues mémoire} permettent à du code Python d'accéder sans copie aux données internes d'un objet prenant en charge le @ref{38e,,protocole tampon}.

@geindex memoryview (classe de base)
@anchor{library/stdtypes memoryview}@anchor{452}
@deffn {Classe} memoryview (object)

Crée une @ref{452,,vue mémoire} faisant référence à `object'. `object' doit savoir gérer le protocole tampon. @ref{1bd,,bytes} et @ref{528,,bytearray} sont des classes natives prenant en charge le protocole tampon.

Une @ref{452,,vue mémoire} a la notion d'`élement', qui est l'unité de mémoire atomique gérée par l'objet `object' d'origine. Pour de nombreux types simples comme @ref{1bd,,bytes} et @ref{528,,bytearray}, l'élément est l'octet, mais pour d'autres types tels que @ref{19e,,array.array} les éléments peuvent être plus grands.

@code{len(view)} is equal to the length of @ref{21a8,,tolist}, which
is the nested list representation of the view. If @code{view.ndim = 1},
this is equal to the number of elements in the view.


Modifié dans la version 3.12: If @code{view.ndim == 0}, @code{len(view)} now raises @ref{522,,TypeError} instead of returning 1.


The @ref{21a9,,itemsize} attribute will give you the number of
bytes in a single element.

Une @ref{452,,vue mémoire} autorise le découpage et l'indiçage de ses données. Découper sur une dimension donne une sous-vue :

@example
>>> v = memoryview(b'abcefg')
>>> v[1]
98
>>> v[-1]
103
>>> v[1:4]
<memory at 0x7f3ddc9f4350>
>>> bytes(v[1:4])
b'bce'
@end example

Si le @ref{21aa,,format} est un des formats natif du module @ref{d4,,struct}, indexer avec un nombre entier ou un `n'-uplet de nombres entiers est aussi autorisé et renvoie un seul `element' du bon type.  Les vues mémoire unidimensionnelles peuvent être indexées avec un nombre entier ou un `n'-uplet d'un entier.  Les `memoryview' multi-dimensionnelles peuvent être indexées avec des `ndim'-uplets où `ndim' est le nombre de dimensions.  Les `memoryviews' à zéro dimension peuvent être indexées avec un `n'-uplet vide.

Voici un exemple avec un autre format que `byte' :

@example
>>> import array
>>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444])
>>> m = memoryview(a)
>>> m[0]
-11111111
>>> m[-1]
44444444
>>> m[::2].tolist()
[-11111111, -33333333]
@end example

Si l'objet sous-jacent est accessible en écriture, la vue mémoire prend en charge les assignations de tranches unidimensionnelles. Redimensionner n'est cependant pas autorisé :

@example
>>> data = bytearray(b'abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = ord(b'z')
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = b'123'
>>> data
bytearray(b'z123fg')
>>> v[2:3] = b'spam'
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: memoryview assignment: lvalue and rvalue have different structures
>>> v[2:6] = b'spam'
>>> data
bytearray(b'z1spam')
@end example

Les vues mémoire unidimensionnelles de @ref{5fb,,hachables} (lecture seule) avec les formats 'B', 'b', ou 'c' sont aussi hachables. La fonction de hachage est définie telle que @code{hash(m) == hash(m.tobytes())} :

@example
>>> v = memoryview(b'abcefg')
>>> hash(v) == hash(b'abcefg')
True
>>> hash(v[2:4]) == hash(b'ce')
True
>>> hash(v[::-2]) == hash(b'abcefg'[::-2])
True
@end example


Modifié dans la version 3.3: Les vues mémoire unidimensionnelles peuvent aussi être découpées. Les vues mémoire unidimensionnelles avec les formats 'B', 'b' ou 'c' sont maintenant @ref{5fb,,hachables}.



Modifié dans la version 3.4: `memoryview' est maintenant enregistrée automatiquement avec @ref{11a1,,collections.abc.Sequence}



Modifié dans la version 3.5: les vues mémoire peuvent maintenant être indicées par un `n'-uplet d'entiers.


La classe @ref{452,,vue mémoire} dispose de plusieurs méthodes :

@geindex __eq__() (méthode memoryview)
@anchor{library/stdtypes memoryview __eq__}@anchor{21ab}
@deffn {Méthode} __eq__ (exporter)

Une vue mémoire et un `exporter' de la 
@geindex Python Enhancement Proposals; PEP 3118
PEP 3118@footnote{https://peps.python.org/pep-3118/} sont égaux si leurs formes sont équivalentes et si toutes les valeurs correspondantes sont égales, les formats respectifs des opérandes étant interprétés en utilisant la syntaxe de @ref{d4,,struct}.

Pour le sous-ensemble des formats de @ref{d4,,struct} pris en charge  par @ref{21a8,,tolist()}, @code{v} et @code{w} sont égaux si @code{v.tolist() ==w.tolist()} :

@example
>>> import array
>>> a = array.array('I', [1, 2, 3, 4, 5])
>>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0])
>>> c = array.array('b', [5, 3, 1])
>>> x = memoryview(a)
>>> y = memoryview(b)
>>> x == a == y == b
True
>>> x.tolist() == a.tolist() == y.tolist() == b.tolist()
True
>>> z = y[::-2]
>>> z == c
True
>>> z.tolist() == c.tolist()
True
@end example

Si l'un des formats n'est pas géré par le module de @ref{d4,,struct}, les objets sont toujours considérés différents  (même si les formats et les valeurs contenues sont identiques) :

@example
>>> from ctypes import BigEndianStructure, c_long
>>> class BEPoint(BigEndianStructure):
...     _fields_ = [("x", c_long), ("y", c_long)]
...
>>> point = BEPoint(100, 200)
>>> a = memoryview(point)
>>> b = memoryview(point)
>>> a == point
False
>>> a == b
False
@end example

Note that, as with floating-point numbers, @code{v is w} does `not' imply
@code{v == w} for memoryview objects.


Modifié dans la version 3.3: les versions précédentes comparaient la mémoire brute sans tenir compte du format de l'objet ni de sa structure logique.

@end deffn

@geindex tobytes() (méthode memoryview)
@anchor{library/stdtypes memoryview tobytes}@anchor{21ac}
@deffn {Méthode} tobytes (order='C')

Renvoie les données de la vue mémoire sous forme de `bytes'. Cela  équivaut à appeler le constructeur @ref{1bd,,bytes} sur la vue mémoire.

@example
>>> m = memoryview(b"abc")
>>> m.tobytes()
b'abc'
>>> bytes(m)
b'abc'
@end example

Pour les tableaux non contigus le résultat est égal à la représentation en liste aplatie dont tous les éléments sont convertis en octets. @ref{21ac,,tobytes()} prend en charge toutes les chaînes de format, y compris celles qui ne sont pas connues du module @ref{d4,,struct}.


Ajouté dans la version 3.8: `order' peut être @code{'C'}, @code{'F'} ou @code{'A'}. Lorsque `order' est @code{'C'} ou @code{'F'}, les données du tableau original sont converties en ordre C ou Fortran. Pour les vues contiguës, @code{'A'} renvoie une copie exacte de la mémoire physique. En particulier, l'ordre Fortran en mémoire est conservé. Pour les vues non contiguës, les données sont d'abord converties en C. @code{order=None} est identique à @code{order='C'}.

@end deffn

@geindex hex() (méthode memoryview)
@anchor{library/stdtypes memoryview hex}@anchor{d58}
@deffn {Méthode} hex ([sep[, bytes_per_sep]])

Renvoie une chaîne contenant deux chiffres hexadécimaux pour chaque octet de la mémoire.

@example
>>> m = memoryview(b"abc")
>>> m.hex()
'616263'
@end example


Ajouté dans la version 3.5.



Modifié dans la version 3.8: similaire à @ref{d56,,bytes.hex()}, @ref{d58,,memoryview.hex()} prend désormais en charge les paramètres optionnels `sep' et `bytes_per_sep' pour insérer des séparateurs entre les octets dans la sortie hexadécimale.

@end deffn

@geindex tolist() (méthode memoryview)
@anchor{library/stdtypes memoryview tolist}@anchor{21a8}
@deffn {Méthode} tolist ()

Renvoie les données de la mémoire sous la forme d'une liste d'éléments.

@example
>>> memoryview(b'abc').tolist()
[97, 98, 99]
>>> import array
>>> a = array.array('d', [1.1, 2.2, 3.3])
>>> m = memoryview(a)
>>> m.tolist()
[1.1, 2.2, 3.3]
@end example


Modifié dans la version 3.3: @ref{21a8,,tolist()} prend désormais en charge tous les formats d'un caractère du module @ref{d4,,struct} ainsi que des représentations multidimensionnelles.

@end deffn

@geindex toreadonly() (méthode memoryview)
@anchor{library/stdtypes memoryview toreadonly}@anchor{21ad}
@deffn {Méthode} toreadonly ()

Renvoie une version en lecture seule de l'objet `memoryview'. L'objet original `memoryview' est inchangé.

@example
>>> m = memoryview(bytearray(b'abc'))
>>> mm = m.toreadonly()
>>> mm.tolist()
[97, 98, 99]
>>> mm[0] = 42
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> m[0] = 43
>>> mm.tolist()
[43, 98, 99]
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex release() (méthode memoryview)
@anchor{library/stdtypes memoryview release}@anchor{119b}
@deffn {Méthode} release ()

Libère le tampon sous-jacent exposé par l'objet `memoryview'.  Beaucoup d'objets ont des comportements spécifiques lorsqu'ils sont liés à une vue (par exemple, un @ref{528,,bytearray} refusera temporairement de se faire redimensionner). Par conséquent, appeler `release()' peut être pratique pour lever ces restrictions (et libérer des ressources liées) aussi tôt que possible.

Après le premier appel de cette méthode, toute nouvelle opération sur la vue mémoire lève une @ref{1ff,,ValueError} (sauf @ref{119b,,release()} elle-même qui peut être appelée plusieurs fois) :

@example
>>> m = memoryview(b'abc')
>>> m.release()
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object
@end example

Le protocole de gestion de contexte peut être utilisé pour obtenir un effet similaire, via l'instruction @code{with} :

@example
>>> with memoryview(b'abc') as m:
...     m[0]
...
97
>>> m[0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: operation forbidden on released memoryview object
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex cast() (méthode memoryview)
@anchor{library/stdtypes memoryview cast}@anchor{21ae}
@deffn {Méthode} cast (format[, shape])

Change le format ou la forme d'une vue mémoire. Par défaut `shape' vaut @code{[byte_length//new_itemsize]}, ce qui signifie que la vue résultante n'a qu'une dimension. La valeur renvoyée est une nouvelle vue mémoire, mais le tampon sous-jacent lui-même n'est pas copié. Les changements de format pris en charge sont « une dimension vers C-@ref{21af,,contiguous} » et « `C-contiguous' vers une dimension ».

The destination format is restricted to a single element native format in
@ref{d4,,struct} syntax. One of the formats must be a byte format
('B', 'b' or 'c'). The byte length of the result must be the same
as the original length.
Note that all byte lengths may depend on the operating system.

Transformer un `1D/long' en `1D/unsigned bytes' :

@example
>>> import array
>>> a = array.array('l', [1,2,3])
>>> x = memoryview(a)
>>> x.format
'l'
>>> x.itemsize
8
>>> len(x)
3
>>> x.nbytes
24
>>> y = x.cast('B')
>>> y.format
'B'
>>> y.itemsize
1
>>> len(y)
24
>>> y.nbytes
24
@end example

Transformer un `1D/unsigned bytes' en `1D/char' :

@example
>>> b = bytearray(b'zyz')
>>> x = memoryview(b)
>>> x[0] = b'a'
Traceback (most recent call last):
  ...
TypeError: memoryview: invalid type for format 'B'
>>> y = x.cast('c')
>>> y[0] = b'a'
>>> b
bytearray(b'ayz')
@end example

Transformer un `1D/bytes' en `3D/ints' en `1D/signed char' :

@example
>>> import struct
>>> buf = struct.pack("i"*12, *list(range(12)))
>>> x = memoryview(buf)
>>> y = x.cast('i', shape=[2,2,3])
>>> y.tolist()
[[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]]
>>> y.format
'i'
>>> y.itemsize
4
>>> len(y)
2
>>> y.nbytes
48
>>> z = y.cast('b')
>>> z.format
'b'
>>> z.itemsize
1
>>> len(z)
48
>>> z.nbytes
48
@end example

Transformer un `1D/unsigned char' en `2D/unsigned long' :

@example
>>> buf = struct.pack("L"*6, *list(range(6)))
>>> x = memoryview(buf)
>>> y = x.cast('L', shape=[2,3])
>>> len(y)
2
>>> y.nbytes
48
>>> y.tolist()
[[0, 1, 2], [3, 4, 5]]
@end example


Ajouté dans la version 3.3.



Modifié dans la version 3.5: le format de la source n'est plus restreint lors de la transformation vers une vue d'octets.

@end deffn

Plusieurs attributs en lecture seule sont également disponibles :

@geindex obj (attribut memoryview)
@anchor{library/stdtypes memoryview obj}@anchor{21b0}
@deffn {Attribut} obj

L'objet sous-jacent de la vue mémoire :

@example
>>> b  = bytearray(b'xyz')
>>> m = memoryview(b)
>>> m.obj is b
True
@end example


Ajouté dans la version 3.3.

@end deffn

@geindex nbytes (attribut memoryview)
@anchor{library/stdtypes memoryview nbytes}@anchor{21b1}
@deffn {Attribut} nbytes

@code{nbytes == product(shape) * itemsize == len(m.tobytes())}. C'est l'espace que la liste occuperait en octets, dans une représentation contiguë. Ce n'est pas nécessairement égal à @code{len(m)} :

@example
>>> import array
>>> a = array.array('i', [1,2,3,4,5])
>>> m = memoryview(a)
>>> len(m)
5
>>> m.nbytes
20
>>> y = m[::2]
>>> len(y)
3
>>> y.nbytes
12
>>> len(y.tobytes())
12
@end example

Tableaux multidimensionnels :

@example
>>> import struct
>>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)])
>>> x = memoryview(buf)
>>> y = x.cast('d', shape=[3,4])
>>> y.tolist()
[[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]]
>>> len(y)
3
>>> y.nbytes
96
@end example


Ajouté dans la version 3.3.

@end deffn

@geindex readonly (attribut memoryview)
@anchor{library/stdtypes memoryview readonly}@anchor{21b2}
@deffn {Attribut} readonly

Booléen indiquant si la mémoire est en lecture seule.
@end deffn

@geindex format (attribut memoryview)
@anchor{library/stdtypes memoryview format}@anchor{21aa}
@deffn {Attribut} format

Chaîne contenant le format (dans le style de @ref{d4,,struct}) pour chaque élément de la vue. Une vue mémoire peut être créée depuis des exportateurs de formats arbitraires, mais certaines méthodes (comme @ref{21a8,,tolist()}) sont limitées aux formats natifs à un seul élément.


Modifié dans la version 3.3: le format @code{'B'} est maintenant traité selon la syntaxe du module `struct'. Cela signifie que @code{memoryview(b'abc')[0] == b'abc'[0] == 97}.

@end deffn

@geindex itemsize (attribut memoryview)
@anchor{library/stdtypes memoryview itemsize}@anchor{21a9}
@deffn {Attribut} itemsize

Taille en octets de chaque élément de la vue mémoire :

@example
>>> import array, struct
>>> m = memoryview(array.array('H', [32000, 32001, 32002]))
>>> m.itemsize
2
>>> m[0]
32000
>>> struct.calcsize('H') == m.itemsize
True
@end example
@end deffn

@geindex ndim (attribut memoryview)
@anchor{library/stdtypes memoryview ndim}@anchor{21b3}
@deffn {Attribut} ndim

Nombre de dimensions du tableau multi-dimensionnel pointé par la vue mémoire.
@end deffn

@geindex shape (attribut memoryview)
@anchor{library/stdtypes memoryview shape}@anchor{21b4}
@deffn {Attribut} shape

@ref{21b3,,ndim}-uplet d'entiers donnant la forme du tableau à N dimensions pointé par la vue mémoire.


Modifié dans la version 3.3: le `n'-uplet est vide au lieu de @code{None} lorsque `ndim' = 0.

@end deffn

@geindex strides (attribut memoryview)
@anchor{library/stdtypes memoryview strides}@anchor{21b5}
@deffn {Attribut} strides

@ref{21b3,,ndim}-uplet d'entiers donnant la taille en octets permettant d'accéder à chaque élément pour chaque dimension du tableau.


Modifié dans la version 3.3: le `n'-uplet est vide au lieu de @code{None} lorsque `ndim' = 0.

@end deffn

@geindex suboffsets (attribut memoryview)
@anchor{library/stdtypes memoryview suboffsets}@anchor{21b6}
@deffn {Attribut} suboffsets

Détail de l'implémentation des `PIL-style arrays'. La valeur n'est donnée qu'à titre d'information.
@end deffn

@geindex c_contiguous (attribut memoryview)
@anchor{library/stdtypes memoryview c_contiguous}@anchor{21b7}
@deffn {Attribut} c_contiguous

Booléen indiquant si la mémoire est C-@ref{21af,,contiguë}.


Ajouté dans la version 3.3.

@end deffn

@geindex f_contiguous (attribut memoryview)
@anchor{library/stdtypes memoryview f_contiguous}@anchor{21b8}
@deffn {Attribut} f_contiguous

Booléen indiquant si la mémoire est Fortran-@ref{21af,,contiguë}.


Ajouté dans la version 3.3.

@end deffn

@geindex contiguous (attribut memoryview)
@anchor{library/stdtypes memoryview contiguous}@anchor{21b9}
@deffn {Attribut} contiguous

Booléen indiquant si la mémoire est @ref{21af,,contiguë}.


Ajouté dans la version 3.3.

@end deffn
@end deffn

@node Types d'ensembles — set frozenset,Les types de correspondances — dict,Séquences Binaires — bytes bytearray vue mémoire,Types natifs
@anchor{library/stdtypes set-types-set-frozenset}@anchor{21ba}@anchor{library/stdtypes types-set}@anchor{20fa}
@subsection Types d'ensembles — @code{set}, @code{frozenset}


@geindex object;set

Un ensemble (objet `set') est une collection non triée d'objets @ref{5fb,,hachables} distincts. Les utilisations classiques sont le test d'appartenance, la déduplication d'une séquence, ou le calcul d'opérations mathématiques telles que l'intersection, l'union, la différence, ou la différence symétrique. (Pour les autres conteneurs, voir les classes natives @ref{253,,dict}, @ref{5fc,,liste}, et @ref{366,,n-uplet}, ainsi que le module @ref{1d,,collections}.)

Comme pour les autres collections, les ensembles gèrent @code{x in set}, @code{len(set)}, et @code{for x in set}. En tant que collection non triée, les ensembles n'enregistrent pas la position des éléments ou leur ordre d'insertion. En conséquence, les ensembles n'autorisent ni l'indexation, ni le découpage, ou tout autre comportement de séquence.

Il existe actuellement deux types natifs pour les ensembles, @ref{5c3,,set} et @ref{5c4,,frozenset}. Le type @ref{5c3,,set} est mutable — son contenu peut changer en utilisant des méthodes comme @code{add()} et @code{remove()}. Puisqu'il est mutable, il n'a pas de valeur de hachage et ne peut donc pas être utilisé ni comme clé de dictionnaire ni comme élément d'un autre ensemble. Le type @ref{5c4,,frozenset} est immuable et @ref{5fb,,hachable} — son contenu ne peut être modifié après sa création, il peut ainsi être utilisé comme clé de dictionnaire ou élément d'un autre ensemble.

Des `sets' (mais pas des `frozensets') peuvent être créés par une liste d'éléments séparés par des virgules et entre accolades, par exemple @code{@{'jack', 'sjoerd'@}}, en plus du constructeur de la classe @ref{5c3,,set}.

Les constructeurs des deux classes fonctionnent de la même manière :

@geindex set (classe de base)
@geindex frozenset (classe de base)
@anchor{library/stdtypes set}@anchor{5c3}
@deffn {Classe} set ([iterable])
@anchor{library/stdtypes frozenset}@anchor{5c4}
@deffnx {Classe} frozenset ([iterable])

Renvoie un nouvel ensemble (`set' ou `frozenset') dont les éléments viennent d'`iterable'.  Les éléments d'un `set' doivent être @ref{5fb,,hachables}.  Pour représenter des ensembles d'ensembles, les ensembles intérieurs doivent être des @ref{5c4,,frozenset}.  Si `iterable' n'est pas spécifié, un nouvel ensemble vide est renvoyé.

Les ensembles peuvent être construits de différentes manières :


@itemize *

@item 
en utilisant une liste d'éléments séparés par des virgules entre accolades : @code{@{'jack', 'sjoerd'@}} ;

@item 
en utilisant un ensemble en compréhension : @code{@{c for c in 'abracadabra' if c not in 'abc'@}} ;

@item 
en utilisant le constructeur du type : @code{set()}, @code{set('foobar')}, @code{set(['a', 'b', 'foo'])}.
@end itemize

Les instances de @ref{5c3,,set} et @ref{5c4,,frozenset} fournissent les opérations suivantes :


@deffn {Describe} len(s)

Renvoie le nombre d'éléments dans l'ensemble `s' (cardinalité de `s').
@end deffn


@deffn {Describe} x in s

Test d'appartenance de `x' dans `s'.
@end deffn


@deffn {Describe} x not in s

Test de non-appartenance de `x' dans `s'.
@end deffn

@geindex isdisjoint() (méthode frozenset)
@anchor{library/stdtypes frozenset isdisjoint}@anchor{21bb}
@deffn {Méthode} isdisjoint (other)

Renvoie @code{True} si l'ensemble n'a aucun élément en commun avec `other'.  Les ensembles sont disjoints si et seulement si leur intersection est un ensemble vide.
@end deffn

@geindex issubset() (méthode frozenset)
@anchor{library/stdtypes frozenset issubset}@anchor{21bc}
@deffn {Méthode} issubset (other)

@deffnx {Méthode} set <= other

Teste si tous les éléments de l'ensemble sont dans `other'.
@end deffn


@deffn {Méthode} set < other

Teste si l'ensemble est un sous-ensemble propre de `other', c'est-à-dire @code{set <= other and set != other}.
@end deffn

@geindex issuperset() (méthode frozenset)
@anchor{library/stdtypes frozenset issuperset}@anchor{21bd}
@deffn {Méthode} issuperset (other)

@deffnx {Méthode} set >= other

Teste si tous les éléments de `other' sont dans l'ensemble.
@end deffn


@deffn {Méthode} set > other

Teste si l'ensemble est un sur-ensemble propre de `other', c'est-à-dire, @code{set >= other and set != other}.
@end deffn

@geindex union() (méthode frozenset)
@anchor{library/stdtypes frozenset union}@anchor{1435}
@deffn {Méthode} union (*others)

@deffnx {Méthode} set | other | ...

Renvoie un nouvel ensemble dont les éléments viennent de l'ensemble et de tous les autres (`others').
@end deffn

@geindex intersection() (méthode frozenset)
@anchor{library/stdtypes frozenset intersection}@anchor{1436}
@deffn {Méthode} intersection (*others)

@deffnx {Méthode} set & other & ...

Renvoie un nouvel ensemble dont les éléments sont communs à l'ensemble et à tous les autres (`others').
@end deffn

@geindex difference() (méthode frozenset)
@anchor{library/stdtypes frozenset difference}@anchor{21be}
@deffn {Méthode} difference (*others)

@deffnx {Méthode} set @w{-} other @w{-} ...

Renvoie un nouvel ensemble dont les éléments sont dans l'ensemble mais ne sont dans aucun des autres.
@end deffn

@geindex symmetric_difference() (méthode frozenset)
@anchor{library/stdtypes frozenset symmetric_difference}@anchor{21bf}
@deffn {Méthode} symmetric_difference (other)

@deffnx {Méthode} set ^ other

Renvoie un nouvel ensemble dont les éléments sont soit dans l'ensemble, soit dans `other', mais pas dans les deux.
@end deffn

@geindex copy() (méthode frozenset)
@anchor{library/stdtypes frozenset copy}@anchor{21c0}
@deffn {Méthode} copy ()

Renvoie une copie superficielle du dictionnaire.
@end deffn

Remarque : les méthodes  @ref{1435,,union()}, @ref{1436,,intersection()}, @ref{21be,,difference()}, @ref{21bf,,symmetric_difference()}, @ref{21bc,,issubset()} et @ref{21bd,,issuperset()} acceptent n'importe quel itérable comme argument, contrairement aux opérateurs équivalents qui n'acceptent que des ensembles. Il est donc préférable d'éviter les constructions comme @code{set('abc') & 'cbs'}, sources typiques d'erreurs, en faveur d'une construction plus lisible : @code{set('abc').intersection('cbs')}.

Les classes @ref{5c3,,set} et @ref{5c4,,frozenset} gèrent les comparaisons d'ensemble à ensemble. Deux ensembles sont égaux si et seulement si chaque élément de chaque ensemble est contenu dans l'autre (autrement dit que chaque ensemble est un sous-ensemble de l'autre). Un ensemble est plus petit qu'un autre ensemble si et seulement si le premier est un sous-ensemble propre du second (un sous-ensemble, mais pas égal). Un ensemble est plus grand qu'un autre ensemble si et seulement si le premier est un sur-ensemble propre du second (est un sur-ensemble mais n'est pas égal).

Les instances de @ref{5c3,,set} se comparent aux instances de @ref{5c4,,frozenset} en fonction de leurs membres.  Par exemple, @code{set('abc') == frozenset('abc')} envoie @code{True}, ainsi que @code{set('abc') in set([frozenset('abc')])}.

Les tests de sous-ensemble et d'égalité ne se généralisent pas pour former une fonction donnant un ordre total. Par exemple, deux ensembles disjoints non vides ne sont ni égaux et ni des sous-ensembles l'un de l'autre, donc toutes ces comparaisons donnent @code{False} : @code{a<b}, @code{a==b} et @code{a>b}.

Puisque les ensembles ne définissent qu'un ordre partiel (par leurs relations de sous-ensembles), la sortie de la méthode @ref{bbd,,list.sort()} n'est pas définie pour des listes d'ensembles.

Les éléments des ensembles, comme les clés de dictionnaires, doivent être @ref{5fb,,hachables}.

Les opérations binaires mélangeant des instances de @ref{5c3,,set} et @ref{5c4,,frozenset} renvoient le type de la première opérande. Par exemple, @code{frozenset('ab') | set('bc')} renvoie une instance de @ref{5c4,,frozenset}.

La table suivante liste les opérations disponibles pour les @ref{5c3,,set} mais qui ne s'appliquent pas aux instances de @ref{5c4,,frozenset} :

@geindex update() (méthode frozenset)
@anchor{library/stdtypes frozenset update}@anchor{21c1}
@deffn {Méthode} update (*others)

@deffnx {Méthode} set |= other | ...

Met à jour l'ensemble, ajoutant les éléments de tous les autres (`others').
@end deffn

@geindex intersection_update() (méthode frozenset)
@anchor{library/stdtypes frozenset intersection_update}@anchor{1437}
@deffn {Méthode} intersection_update (*others)

@deffnx {Méthode} set &= other & ...

Met à jour l'ensemble, ne gardant que les éléments trouvés dans tous les autres.
@end deffn

@geindex difference_update() (méthode frozenset)
@anchor{library/stdtypes frozenset difference_update}@anchor{21c2}
@deffn {Méthode} difference_update (*others)

@deffnx {Méthode} set @w{-}= other | ...

Met à jour l'ensemble, retirant les éléments trouvés dans les autres.
@end deffn

@geindex symmetric_difference_update() (méthode frozenset)
@anchor{library/stdtypes frozenset symmetric_difference_update}@anchor{1438}
@deffn {Méthode} symmetric_difference_update (other)

@deffnx {Méthode} set ^= other

Met à jour l'ensemble, ne gardant que les éléments trouvés dans un des deux ensembles mais pas dans les deux.
@end deffn

@geindex add() (méthode frozenset)
@anchor{library/stdtypes frozenset add}@anchor{21c3}
@deffn {Méthode} add (elem)

Ajoute l'élément `elem' à l'ensemble.
@end deffn

@geindex remove() (méthode frozenset)
@anchor{library/stdtypes frozenset remove}@anchor{21c4}
@deffn {Méthode} remove (elem)

Retire l'élément `elem' de l'ensemble. Lève une exception @ref{33a,,KeyError} si `elem' n'est pas dans l'ensemble.
@end deffn

@geindex discard() (méthode frozenset)
@anchor{library/stdtypes frozenset discard}@anchor{21c5}
@deffn {Méthode} discard (elem)

Retire l'élément `elem' de l'ensemble s'il y est.
@end deffn

@geindex pop() (méthode frozenset)
@anchor{library/stdtypes frozenset pop}@anchor{21c6}
@deffn {Méthode} pop ()

Retire et renvoie un élément arbitraire de l'ensemble. Lève une exception @ref{33a,,KeyError} si l'ensemble est vide.
@end deffn

@geindex clear() (méthode frozenset)
@anchor{library/stdtypes frozenset clear}@anchor{21c7}
@deffn {Méthode} clear ()

Supprime tous les éléments de l'ensemble.
@end deffn

Notez que les versions n'utilisant pas la syntaxe d'opérateur des méthodes @ref{21c1,,update()}, @ref{1437,,intersection_update()}, @ref{21c2,,difference_update()}, et @ref{1438,,symmetric_difference_update()} acceptent n'importe quel itérable comme argument.

Note, the `elem' argument to the @ref{1ee0,,__contains__()},
@ref{21c4,,remove()}, and
@ref{21c5,,discard()} methods may be a set.  To support searching for an equivalent
frozenset, a temporary one is created from `elem'.
@end deffn

@node Les types de correspondances — dict,Le type gestionnaire de contexte,Types d'ensembles — set frozenset,Types natifs
@anchor{library/stdtypes mapping-types-dict}@anchor{21c8}@anchor{library/stdtypes typesmapping}@anchor{ab4}
@subsection Les types de correspondances — @code{dict}


@geindex object;mapping
@geindex object;dictionary
@geindex operations on;mapping;types
@geindex operations on;dictionary;type
@geindex statement;del
@geindex built-in function;len

Un objet @ref{1199,,tableau de correspondances} (`mapping') fait correspondre des valeurs @ref{5fb,,hachables} à des objets arbitraires. Les tableaux de correspondances sont des objets mutables. Il n'existe pour le moment qu'un type de tableau de correspondances standard, le `dictionary'.  (Pour les autres conteneurs, voir les types natifs @ref{5fc,,liste}, @ref{5c3,,ensemble} et @ref{366,,n-uplet}, ainsi que le module @ref{1d,,collections}.)

Les clés d'un dictionnaire sont `presque' des données arbitraires. Les valeurs qui ne sont pas @ref{5fb,,hachables}, c'est-à-dire les valeurs contenant des listes, dictionnaires ou autres types mutables (qui sont comparés à l'aide de leurs valeurs plutôt que par l'identité de l'objet) ne peuvent pas être utilisées comme clés. Des valeurs qui sont considérées égales lors d'une comparaison (comme @code{1}, @code{1.0} et @code{True}) peuvent être utilisées pour obtenir la même entrée d'un dictionnaire.

@geindex dict (classe de base)
@anchor{library/stdtypes dict}@anchor{253}
@deffn {Classe} dict (**kwargs)

@deffnx {Classe} dict (mapping, **kwargs)

@deffnx {Classe} dict (iterable, **kwargs)

Renvoie un nouveau dictionnaire initialisé à partir d'un argument positionnel optionnel, et un ensemble (vide ou non) d'arguments nommés.

Les dictionnaires peuvent être construits de différentes manières :


@itemize *

@item 
en utilisant une liste de paires @code{clé: valeur} séparées par des virgules entre accolades : @code{@{'jack': 4098, 'sjoerd': 4127@}} ou @code{@{4098: 'jack', 4127: 'sjoerd'@}} ;

@item 
en utilisant un dictionnaire en compréhension : @code{@{@}}, @code{@{x: x ** 2 for x in range(10)@}} ;

@item 
en utilisant le constructeur du type : @code{dict()}, @code{dict([('foo', 100), ('bar', 200)])}, @code{dict(foo=100, bar=200)}.
@end itemize

If no positional argument is given, an empty dictionary is created.
If a positional argument is given and it defines a @code{keys()} method, a
dictionary is created by calling @ref{280,,__getitem__()} on the argument with
each returned key from the method.  Otherwise, the positional argument must be an
@ref{1205,,iterable} object.  Each item in the iterable must itself be an iterable
with exactly two elements.  The first element of each item becomes a key in the
new dictionary, and the second element the corresponding value.  If a key occurs
more than once, the last value for that key becomes the corresponding value in
the new dictionary.

Si des arguments nommés sont donnés, ils sont ajoutés au dictionnaire créé depuis l'argument positionnel. Si une clé est déjà présente, la valeur de l'argument nommé remplace la valeur reçue par l'argument positionnel.

Typiquement, les exemples suivants renvoient tous un dictionnaire valant @code{@{"one": 1, "two": 2, "three": 3@}} :

@example
>>> a = dict(one=1, two=2, three=3)
>>> b = @{'one': 1, 'two': 2, 'three': 3@}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict(@{'three': 3, 'one': 1, 'two': 2@})
>>> f = dict(@{'one': 1, 'three': 3@}, two=2)
>>> a == b == c == d == e == f
True
@end example

Fournir les arguments nommés comme dans le premier exemple ne fonctionne que pour des clés qui sont des identifiants valides en Python. Dans les autres cas, toutes les clés valides sont utilisables.

Voici les opérations gérées par les dictionnaires (par conséquent, d'autres types de tableaux de correspondances devraient les gérer aussi) :


@deffn {Describe} list(d)

Renvoie une liste de toutes les clés utilisées dans le dictionnaire `d'.
@end deffn


@deffn {Describe} len(d)

Renvoie le nombre d'éléments dans le dictionnaire `d'.
@end deffn


@deffn {Describe} d[key]

Renvoie l'élément de `d' dont la clé est `key'. Lève une exception @ref{33a,,KeyError} si `key' n'est pas dans le dictionnaire.

@geindex __missing__()

Si une sous-classe de `dict' définit une méthode @code{__missing__()} et que `key' manque, l'opération @code{d[key]} appelle cette méthode avec la clé `key' en argument. L'opération @code{d[key]} renvoie la valeur, ou lève l'exception renvoyée ou levée par l'appel à @code{__missing__(key)}. Aucune autre opération ni méthode n'appelle @code{__missing__()}. Si @code{__missing__()} n'est pas définie, une exception @ref{33a,,KeyError} est levée. @code{__missing__()} doit être une méthode ; ça ne peut pas être une variable d'instance :

@example
>>> class Counter(dict):
...     def __missing__(self, key):
...         return 0
...
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1
@end example

L'exemple ci-dessus montre une partie de l'implémentation de @ref{107b,,collections.Counter}.  @ref{119a,,collections.defaultdict} implémente aussi @code{__missing__}.
@end deffn


@deffn {Describe} d[key] = value

Assigne @code{d[key]} à `value'.
@end deffn


@deffn {Describe} del d[key]

Supprime @code{d[key]} de `d'.  Lève une exception @ref{33a,,KeyError} si `key' n'est pas dans le dictionnaire.
@end deffn


@deffn {Describe} key in d

Renvoie @code{True} si `d' a la clé `key', sinon @code{False}.
@end deffn


@deffn {Describe} key not in d

Équivalent à @code{not key in d}.
@end deffn


@deffn {Describe} iter(d)

Renvoie un itérateur sur les clés du dictionnaire. C'est un raccourci pour @code{iter(d.keys())}.
@end deffn

@geindex clear() (méthode dict)
@anchor{library/stdtypes dict clear}@anchor{21c9}
@deffn {Méthode} clear ()

Supprime tous les éléments du dictionnaire.
@end deffn

@geindex copy() (méthode dict)
@anchor{library/stdtypes dict copy}@anchor{bbe}
@deffn {Méthode} copy ()

Renvoie une copie superficielle du dictionnaire.
@end deffn

@geindex fromkeys() (méthode de la classe dict)
@anchor{library/stdtypes dict fromkeys}@anchor{21ca}
@deffn {Méthode} classmethod fromkeys (iterable, value=None, /)

Crée un nouveau dictionnaire avec les clés de `iterable' et les valeurs à `value'.

@ref{21ca,,fromkeys()} est une méthode de classe qui renvoie un nouveau dictionnaire. `value' vaut par défaut @code{None}. Toutes les valeurs se réfèrent à une seule instance, donc il n'est généralement pas logique que `value' soit un objet mutable comme une liste vide. Pour avoir des valeurs distinctes, utilisez plutôt une @ref{d6c,,compréhension de dictionnaire}.
@end deffn

@geindex get() (méthode dict)
@anchor{library/stdtypes dict get}@anchor{21cb}
@deffn {Méthode} get (key, default=None)

Renvoie la valeur de `key' si `key' est dans le dictionnaire, sinon `default'. Si `default' n'est pas donné, il vaut @code{None} par défaut, de manière à ce que cette méthode ne lève jamais @ref{33a,,KeyError}.
@end deffn

@geindex items() (méthode dict)
@anchor{library/stdtypes dict items}@anchor{7b9}
@deffn {Méthode} items ()

Renvoie une nouvelle vue des éléments du dictionnaire (paires de @code{(key, value)}). Voir la @ref{21cc,,documentation des vues}.
@end deffn

@geindex keys() (méthode dict)
@anchor{library/stdtypes dict keys}@anchor{7b7}
@deffn {Méthode} keys ()

Renvoie une nouvelle vue des clés du dictionnaire. Voir la @ref{21cc,,documentation des vues}.
@end deffn

@geindex pop() (méthode dict)
@anchor{library/stdtypes dict pop}@anchor{339}
@deffn {Méthode} pop (key[, default])

Si `key' est dans le dictionnaire elle est supprimée et sa valeur est renvoyée, sinon renvoie `default'.  Si `default' n'est pas donné et que `key' n'est pas dans le dictionnaire, une @ref{33a,,KeyError} est levée.
@end deffn

@geindex popitem() (méthode dict)
@anchor{library/stdtypes dict popitem}@anchor{14dd}
@deffn {Méthode} popitem ()

Supprime et renvoie une paire @code{(key, value)} du dictionnaire. Les paires sont renvoyées dans un ordre @abbr{LIFO,Last In - First Out c.-à-d. dernier entré@comma{} premier sorti}.

@ref{14dd,,popitem()} est pratique pour itérer un dictionnaire de manière destructive, comme souvent dans les algorithmes sur les ensembles.  Si le dictionnaire est vide, appeler @ref{14dd,,popitem()} lève une @ref{33a,,KeyError}.


Modifié dans la version 3.7: l'ordre « dernier entré, premier sorti » (LIFO) est désormais assuré. Dans les versions précédentes, @ref{14dd,,popitem()} renvoyait une paire clé-valeur arbitraire.

@end deffn


@deffn {Describe} reversed(d)

Renvoie un itérateur inversé sur les clés du dictionnaire. C'est un raccourci pour @code{reversed(d.keys())}.


Ajouté dans la version 3.8.

@end deffn

@geindex setdefault() (méthode dict)
@anchor{library/stdtypes dict setdefault}@anchor{1062}
@deffn {Méthode} setdefault (key, default=None)

Si `key' est dans le dictionnaire, sa valeur est renvoyée. Sinon, insère `key' avec comme valeur `default' et renvoie `default'. `default' vaut @code{None} par défaut.
@end deffn

@geindex update() (méthode dict)
@anchor{library/stdtypes dict update}@anchor{1419}
@deffn {Méthode} update ([other])

Met à jour le dictionnaire avec les paires de clé-valeur d'`other', écrasant les clés existantes. Renvoie @code{None}.

@ref{1419,,update()} accepts either another object with a @code{keys()} method (in
which case @ref{280,,__getitem__()} is called with every key returned from
the method) or an iterable of key/value pairs (as tuples or other iterables
of length two). If keyword arguments are specified, the dictionary is then
updated with those key/value pairs: @code{d.update(red=1, blue=2)}.
@end deffn

@geindex values() (méthode dict)
@anchor{library/stdtypes dict values}@anchor{7b8}
@deffn {Méthode} values ()

Renvoie une nouvelle vue des valeurs du dictionnaire.  Voir la @ref{21cc,,documentation des vues}.

Une comparaison d'égalité entre une vue de @code{dict.values()} et une autre renvoie toujours @code{False}. Cela s'applique aussi lorsque l'on compare @code{dict.values()} à lui-même :

@example
>>> d = @{'a': 1@}
>>> d.values() == d.values()
False
@end example
@end deffn


@deffn {Describe} d | other

Crée un nouveau dictionnaire avec les clés et les valeurs fusionnées de `d' et `other', qui doivent tous deux être des dictionnaires. Les valeurs de `other' sont prioritaires lorsque `d' et `other' partagent des clés.


Ajouté dans la version 3.9.

@end deffn


@deffn {Describe} d |= other

Met à jour le dictionnaire `d' avec les clés et les valeurs de `other', qui peut être soit un @ref{1199,,tableau de correspondances} soit un @ref{1205,,itérable} de paires clé-valeur. Les valeurs de `other' sont prioritaires lorsque `d' et `other' partagent des clés.


Ajouté dans la version 3.9.

@end deffn

Deux dictionnaires sont égaux si et seulement s'ils ont les mêmes paires de clé-valeur (@code{(key, value)}, peu importe leur ordre). Les comparaisons d'ordre (@code{<}, @code{<=}, @code{>=}, @code{>}) lèvent une @ref{522,,TypeError}.

Les dictionnaires préservent l'ordre des insertions. Notez que modifier une clé n'affecte pas l'ordre. Les clés ajoutées après un effacement sont insérées à la fin.

@example
>>> d = @{"one": 1, "two": 2, "three": 3, "four": 4@}
>>> d
@{'one': 1, 'two': 2, 'three': 3, 'four': 4@}
>>> list(d)
['one', 'two', 'three', 'four']
>>> list(d.values())
[1, 2, 3, 4]
>>> d["one"] = 42
>>> d
@{'one': 42, 'two': 2, 'three': 3, 'four': 4@}
>>> del d["two"]
>>> d["two"] = None
>>> d
@{'one': 42, 'three': 3, 'four': 4, 'two': None@}
@end example


Modifié dans la version 3.7: l'ordre d'un dictionnaire est toujours l'ordre des insertions. Ce comportement était un détail d'implémentation de CPython depuis la version 3.6.


Les dictionnaires et les vues de dictionnaires sont réversibles.

@example
>>> d = @{"one": 1, "two": 2, "three": 3, "four": 4@}
>>> d
@{'one': 1, 'two': 2, 'three': 3, 'four': 4@}
>>> list(reversed(d))
['four', 'three', 'two', 'one']
>>> list(reversed(d.values()))
[4, 3, 2, 1]
>>> list(reversed(d.items()))
[('four', 4), ('three', 3), ('two', 2), ('one', 1)]
@end example


Modifié dans la version 3.8: les dictionnaires sont maintenant réversibles.

@end deffn


@subsubheading Voir aussi


@ref{457,,types.MappingProxyType} peut être utilisé pour créer une vue en lecture seule d'un @ref{253,,dict}.


@menu
* Les vues de dictionnaires:: 

@end menu

@node Les vues de dictionnaires,,,Les types de correspondances — dict
@anchor{library/stdtypes dict-views}@anchor{21cc}@anchor{library/stdtypes dictionary-view-objects}@anchor{21cd}
@subsubsection Les vues de dictionnaires


Les objets renvoyés par @ref{7b7,,dict.keys()}, @ref{7b8,,dict.values()} et @ref{7b9,,dict.items()} sont des `vues'.  Ils fournissent une vue dynamique des éléments du dictionnaire, ce qui signifie que si le dictionnaire change, la vue reflète ces changements.

Les vues de dictionnaires peuvent être itérées et ainsi renvoyer les données du dictionnaire ; elles gèrent aussi les tests d'appartenance :


@deffn {Describe} len(dictview)

Renvoie le nombre d'entrées du dictionnaire.
@end deffn


@deffn {Describe} iter(dictview)

Renvoie un itérateur sur les clés, les valeurs ou les éléments (représentés par des paires @code{(clé, valeur)}) du dictionnaire.

Les clés et les valeurs sont itérées dans l'ordre de leur insertion. Ceci permet la création de paires de @code{(key, value)} en utilisant @ref{7ba,,zip()} : @code{pairs = zip(d.values(), d.keys())}. Un autre moyen de construire la même liste est @code{pairs = [(v, k) for (k, v) in d.items()]}.

Parcourir des vues tout en ajoutant ou supprimant des entrées dans un dictionnaire peut lever une @ref{193,,RuntimeError} ou ne pas fournir toutes les entrées.


Modifié dans la version 3.7: l'ordre d'un dictionnaire est toujours l'ordre des insertions.

@end deffn


@deffn {Describe} x in dictview

Renvoie @code{True} si `x' est dans les clés, les valeurs ou les éléments du dictionnaire sous-jacent (dans le dernier cas, `x' doit être une paire @code{(key, value)}).
@end deffn


@deffn {Describe} reversed(dictview)

Renvoie un itérateur inversé sur les clés, les valeurs ou les éléments du dictionnaire. La vue est itérée dans l'ordre inverse d'insertion.


Modifié dans la version 3.8: les vues de dictionnaires sont dorénavant réversibles.

@end deffn


@deffn {Describe} dictview.mapping

Renvoie une @ref{457,,types.MappingProxyType} qui encapsule le dictionnaire original auquel la vue se réfère.


Ajouté dans la version 3.10.

@end deffn

Keys views are set-like since their entries are unique and @ref{5fb,,hashable}.
Items views also have set-like operations since the (key, value) pairs
are unique and the keys are hashable.
If all values in an items view are hashable as well,
then the items view can interoperate with other sets.
(Values views are not treated as set-like
since the entries are generally not unique.)  For set-like views, all of the
operations defined for the abstract base class @ref{21ce,,collections.abc.Set} are
available (for example, @code{==}, @code{<}, or @code{^}).  While using set operators,
set-like views accept any iterable as the other operand,
unlike sets which only accept sets as the input.

Voici un exemple d'utilisation de vue de dictionnaire :

@example
>>> dishes = @{'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500@}
>>> keys = dishes.keys()
>>> values = dishes.values()

>>> # iteration
>>> n = 0
>>> for val in values:
...     n += val
...
>>> print(n)
504

>>> # keys and values are iterated over in the same order (insertion order)
>>> list(keys)
['eggs', 'sausage', 'bacon', 'spam']
>>> list(values)
[2, 1, 1, 500]

>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['bacon', 'spam']

>>> # set operations
>>> keys & @{'eggs', 'bacon', 'salad'@}
@{'bacon'@}
>>> keys ^ @{'sausage', 'juice'@} == @{'juice', 'sausage', 'bacon', 'spam'@}
True
>>> keys | ['juice', 'juice', 'juice'] == @{'bacon', 'spam', 'juice'@}
True

>>> # get back a read-only proxy for the original dictionary
>>> values.mapping
mappingproxy(@{'bacon': 1, 'spam': 500@})
>>> values.mapping['spam']
500
@end example

@node Le type gestionnaire de contexte,Types d'annotation de type — Alias générique Union,Les types de correspondances — dict,Types natifs
@anchor{library/stdtypes context-manager-types}@anchor{21cf}@anchor{library/stdtypes typecontextmanager}@anchor{1f42}
@subsection Le type gestionnaire de contexte


@geindex context manager
@geindex context management protocol
@geindex protocol;context management

L'instruction Python @ref{5bc,,with} permet de créer des contextes d'exécution à l'aide de gestionnaires de contextes. L'implémentation est réalisée via deux méthodes permettant aux classes définies par l'utilisateur de définir un contexte d'exécution, dans lequel on entre avant l'exécution du corps de l'instruction et que l'on quitte lorsque l'instruction se termine :

@geindex __enter__() (méthode contextmanager)
@anchor{library/stdtypes contextmanager __enter__}@anchor{21d0}
@deffn {Méthode} contextmanager.__enter__ ()

Entre dans le contexte d'exécution, soit se renvoyant lui-même, soit en renvoyant un autre objet en lien avec ce contexte. La valeur renvoyée par cette méthode est liée à l'identifiant donné au @code{as} de l'instruction @ref{5bc,,with} utilisant ce gestionnaire de contexte.

Un exemple de gestionnaire de contexte se renvoyant lui-même est l'@ref{11a0,,objet fichier}. Les objets fichiers se renvoient eux-mêmes depuis @code{__enter__()} pour ainsi permettre à @ref{505,,open()} d'être utilisée comme expression dans une instruction @ref{5bc,,with}.

Un exemple de gestionnaire de contexte renvoyant un objet connexe est celui renvoyé par @ref{1792,,decimal.localcontext()}. Ces gestionnaires remplacent le contexte décimal courant par une copie de l'original, copie qui est renvoyée. Ça permet de changer le contexte courant dans le corps du @ref{5bc,,with} sans affecter le code en dehors de l'instruction @code{with}.
@end deffn

@geindex __exit__() (méthode contextmanager)
@anchor{library/stdtypes contextmanager __exit__}@anchor{21d1}
@deffn {Méthode} contextmanager.__exit__ (exc_type, exc_val, exc_tb)

Sort du contexte et renvoie un booléen indiquant si une exception est survenue et doit être supprimée.  Si une exception est survenue lors de l'exécution du corps de l'instruction @ref{5bc,,with}, les arguments contiennent le type de l'exception, sa valeur et la trace de la pile (`traceback'). Sinon les trois arguments valent @code{None}.

L'instruction @ref{5bc,,with} inhibe l'exception si cette méthode renvoie la valeur vraie, l'exécution continuant ainsi à l'instruction suivant immédiatement l'instruction @code{with}. Sinon, l'exception continue de se propager après la fin de cette méthode. Les exceptions se produisant pendant l'exécution de cette méthode remplacent toute exception qui s'est produite dans le corps du @code{with}.

L'exception reçue ne doit jamais être relancée explicitement, cette méthode devrait plutôt renvoyer une valeur fausse pour indiquer que son exécution s'est terminée avec succès et qu'elle ne veut pas supprimer l'exception. Ceci permet au code de gestion du contexte de comprendre si une méthode @ref{12de,,__exit__()} a échoué.
@end deffn

Python définit plusieurs gestionnaires de contexte pour faciliter la synchronisation des fils d'exécution, la fermeture des fichiers ou d'autres objets, et la configuration du contexte arithmétique décimal. Ces types spécifiques ne sont pas traités différemment, ils respectent simplement le protocole de gestion du contexte. Voir les exemples dans la documentation du module @ref{23,,contextlib}.

Les @ref{104a,,générateurs} Python et le décorateur @ref{11df,,contextlib.contextmanager} permettent d'implémenter simplement ces protocoles. Si un générateur est décoré avec @code{contextlib. contextmanager}, il renvoie un gestionnaire de contexte implémentant les méthodes @ref{21d0,,__enter__()} et @ref{21d1,,__exit__()}, plutôt que l'itérateur produit par un générateur non décoré.

Notez qu'il n'y a pas d'emplacement spécifique pour ces méthodes dans la structure de type pour les objets Python dans l'API Python/C. Les types souhaitant définir ces méthodes doivent les fournir comme une méthode accessible en Python. Comparé au coût de la mise en place du contexte d'exécution, le coût d'un accès au dictionnaire d'une classe unique est négligeable.

@node Types d'annotation de type — Alias générique Union,Autres types natifs,Le type gestionnaire de contexte,Types natifs
@anchor{library/stdtypes type-annotation-types-generic-alias-union}@anchor{21d2}
@subsection Types d'annotation de type — Alias générique, Union


@geindex annotation;type annotation; type hint

Les principaux types natifs pour l'@ref{441,,annotation de types} sont l'@ref{69d,,Alias générique} et l'@ref{7ac,,Union}.

@menu
* Type Alias générique:: 
* Type Union:: 

@end menu

@node Type Alias générique,Type Union,,Types d'annotation de type — Alias générique Union
@anchor{library/stdtypes generic-alias-type}@anchor{21d3}@anchor{library/stdtypes types-genericalias}@anchor{69d}
@subsubsection Type Alias générique


@geindex object;GenericAlias
@geindex Generic;Alias

Les objets @code{GenericAlias} sont généralement créés en @ref{1f07,,indiçant} une classe. Ils sont le plus souvent utilisés avec des @ref{1f0d,,classes conteneurs}, telles que @ref{5fc,,list} ou @ref{253,,dict}. Par exemple, @code{list[int]} est un objet GenericAlias créé en indiçant la classe @code{list} avec l'argument @ref{254,,int}. Les objets @code{GenericAlias} sont principalement destinés à être utilisés en tant qu'@ref{441,,annotations de types}.

@cartouche
@quotation Note 
il n'est généralement possible d'indicer une classe que si la classe implémente la méthode spéciale @ref{725,,__class_getitem__()}.
@end quotation
@end cartouche

Un objet @code{GenericAlias} agit comme un mandataire pour un @ref{422,,type générique}, en implémentant des `types génériques pouvant recevoir des paramètres'.

Pour une classe conteneur, les arguments fournis comme @ref{1f07,,indices} de la classe indiquent les types des éléments que l'objet peut contenir. Par exemple, @code{set[bytes]} peut être utilisé dans les annotations de type pour signifier un @ref{5c3,,ensemble} dans lequel tous les éléments sont de type @ref{1bd,,bytes}.

Pour une classe qui définit @ref{725,,__class_getitem__()} mais n'est pas un conteneur, les arguments fournis comme indices de la classe indiquent souvent les types de retour d'une ou plusieurs méthodes définies sur un objet. Par exemple, @ref{b8,,re} (expressions rationnelles) peut être utilisé à la fois sur le type de données @ref{435,,str} et sur le type de données @ref{1bd,,bytes} :


@itemize *

@item 
si @code{x = re.search('foo', 'foo')}, @code{x} est un objet @ref{f72,,re.Match} où les valeurs de retour de @code{x.group(0)} et @code{x[0]} sont toutes les deux de type @ref{435,,str}. Nous pouvons représenter ce type d'objet dans des annotations de type avec le @code{GenericAlias} @code{re.Match[str]} ;

@item 
si @code{y = re.search(b'bar', b'bar')}, (notez le @code{b} pour @ref{1bd,,bytes}), @code{y} est également une instance de @code{re.Match}, mais les valeurs de retour de @code{y.group(0)} et @code{y[0]} sont toutes les deux de type @ref{1bd,,bytes}. Dans les annotations de type, nous représenterons cette variété d'objets @ref{f72,,re.Match} par @code{re.Match[bytes]}.
@end itemize

Les objets @code{GenericAlias} sont des instances de la classe @ref{7d5,,types.GenericAlias}, qui peut également être utilisée pour créer directement des objets @code{GenericAlias}.


@deffn {Describe} T[X, Y, ...]

Crée un @code{GenericAlias} représentant un type @code{T} paramétré par les types `X', `Y' et plus selon le @code{T} utilisé. Par exemple, pour une fonction attendant une @ref{5fc,,list} contenant des éléments @ref{2eb,,float} :

@example
def average(values: list[float]) -> float:
    return sum(values) / len(values)
@end example

Un autre exemple peut être un objet @ref{1199,,tableau de correspondances}, utilisant un @ref{253,,dict}, qui est un type générique attendant deux paramètres de type représentant le type clé et le type valeur. Dans cet exemple, la fonction attend un @code{dict} avec des clés de type @ref{435,,str} et des valeurs de type @ref{254,,int} :

@example
def send_post_request(url: str, body: dict[str, int]) -> None:
    ...
@end example
@end deffn

Les fonctions natives @ref{42b,,isinstance()} et @ref{7ab,,issubclass()} n'acceptent pas les types @code{GenericAlias} pour leur second argument :

@example
>>> isinstance([1, 2], list[str])
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: isinstance() argument 2 cannot be a parameterized generic
@end example

Lors de l'exécution, Python ne regarde pas les @ref{441,,annotations de type}. Cela vaut pour les types génériques et les types qu'on leur passe en paramètres. Lors de la création d'un objet conteneur à partir d'un @code{GenericAlias}, les types des éléments du conteneur ne sont pas vérifiés. Par exemple, le code suivant est déconseillé, mais s'exécute sans erreur :

@example
>>> t = list[str]
>>> t([1, 2, 3])
[1, 2, 3]
@end example

De plus, les types génériques pouvant recevoir des paramètres effacent les paramètres de type lors de la création d'objet :

@example
>>> t = list[str]
>>> type(t)
<class 'types.GenericAlias'>

>>> l = t()
>>> type(l)
<class 'list'>
@end example

Appeler @ref{7e7,,repr()} ou @ref{435,,str()} sur un type générique affiche le type pouvant recevoir des paramètres :

@example
>>> repr(list[int])
'list[int]'

>>> str(list[int])
'list[int]'
@end example

La méthode @ref{280,,__getitem__()} des conteneurs génériques lève une exception pour interdire les erreurs telles que @code{dict[str][str]} :

@example
>>> dict[str][str]
Traceback (most recent call last):
  ...
TypeError: dict[str] is not a generic class
@end example

Cependant, de telles expressions sont valides lorsque @ref{1f02,,des variables de type} sont utilisées. L'indice doit avoir autant d'éléments qu'il y a d'éléments variables de type dans l'objet @code{GenericAlias} @ref{21d4,,__args__}.

@example
>>> from typing import TypeVar
>>> Y = TypeVar('Y')
>>> dict[str, Y][int]
dict[str, int]
@end example

@menu
* Classes génériques standards:: 
* Attributs spéciaux des alias génériques:: 

@end menu

@node Classes génériques standards,Attributs spéciaux des alias génériques,,Type Alias générique
@anchor{library/stdtypes standard-generic-classes}@anchor{21d5}
@subsubsection Classes génériques standards


Les classes suivantes de la bibliothèque standard prennent en charge les types génériques pouvant accepter des paramètres. Cette liste est non exhaustive.


@itemize *

@item 
@ref{366,,tuple}

@item 
@ref{5fc,,list}

@item 
@ref{253,,dict}

@item 
@ref{5c3,,set}

@item 
@ref{5c4,,frozenset}

@item 
@ref{d36,,type}

@item 
@ref{5c6,,collections.deque}

@item 
@ref{119a,,collections.defaultdict}

@item 
@ref{5c5,,collections.OrderedDict}

@item 
@ref{107b,,collections.Counter}

@item 
@ref{c0a,,collections.ChainMap}

@item 
@ref{dc9,,collections.abc.Awaitable}

@item 
@ref{dca,,collections.abc.Coroutine}

@item 
@ref{dcc,,collections.abc.AsyncIterable}

@item 
@ref{dcb,,collections.abc.AsyncIterator}

@item 
@ref{c78,,collections.abc.AsyncGenerator}

@item 
@ref{21d6,,collections.abc.Iterable}

@item 
@ref{21d7,,collections.abc.Iterator}

@item 
@ref{dc8,,collections.abc.Generator}

@item 
@ref{c77,,collections.abc.Reversible}

@item 
@ref{21d8,,collections.abc.Container}

@item 
@ref{c76,,collections.abc.Collection}

@item 
@ref{7d4,,collections.abc.Callable}

@item 
@ref{21ce,,collections.abc.Set}

@item 
@ref{21d9,,collections.abc.MutableSet}

@item 
@ref{8b7,,collections.abc.Mapping}

@item 
@ref{1090,,collections.abc.MutableMapping}

@item 
@ref{11a1,,collections.abc.Sequence}

@item 
@ref{19f,,collections.abc.MutableSequence}

@item 
@ref{2c0,,collections.abc.ByteString}

@item 
@ref{21da,,collections.abc.MappingView}

@item 
@ref{21db,,collections.abc.KeysView}

@item 
@ref{21dc,,collections.abc.ItemsView}

@item 
@ref{21dd,,collections.abc.ValuesView}

@item 
@ref{c7b,,contextlib.AbstractContextManager}

@item 
@ref{b19,,contextlib.AbstractAsyncContextManager}

@item 
@ref{21de,,dataclasses.Field}

@item 
@ref{52c,,functools.cached_property}

@item 
@ref{a69,,functools.partialmethod}

@item 
@ref{c3f,,os.PathLike}

@item 
@ref{21df,,queue.LifoQueue}

@item 
@ref{1365,,queue.Queue}

@item 
@ref{21e0,,queue.PriorityQueue}

@item 
@ref{b58,,queue.SimpleQueue}

@item 
@ref{f71,,re.Pattern}

@item 
@ref{f72,,re.Match}

@item 
@ref{21e1,,shelve.BsdDbShelf}

@item 
@ref{21e2,,shelve.DbfilenameShelf}

@item 
@ref{f85,,shelve.Shelf}

@item 
@ref{457,,types.MappingProxyType}

@item 
@ref{18fc,,weakref.WeakKeyDictionary}

@item 
@ref{fd8,,weakref.WeakMethod}

@item 
@ref{5c7,,weakref.WeakSet}

@item 
@ref{18fb,,weakref.WeakValueDictionary}
@end itemize

@node Attributs spéciaux des alias génériques,,Classes génériques standards,Type Alias générique
@anchor{library/stdtypes special-attributes-of-genericalias-objects}@anchor{21e3}
@subsubsection Attributs spéciaux des alias génériques


Tous les types génériques pouvant accepter des paramètres implémentent des attributs spéciaux en lecture seule.

@geindex __origin__ (attribut genericalias)
@anchor{library/stdtypes genericalias __origin__}@anchor{21e4}
@deffn {Attribut} genericalias.__origin__

Cet attribut pointe vers la classe générique sans paramètres :

@example
>>> list[int].__origin__
<class 'list'>
@end example
@end deffn

@geindex __args__ (attribut genericalias)
@anchor{library/stdtypes genericalias __args__}@anchor{21d4}
@deffn {Attribut} genericalias.__args__

Cet attribut est un @ref{366,,n-uplet} (éventuellement de longueur 1) de types génériques passés à la @ref{725,,__class_getitem__()} d'origine de la classe générique :

@example
>>> dict[str, list[int]].__args__
(<class 'str'>, list[int])
@end example
@end deffn

@geindex __parameters__ (attribut genericalias)
@anchor{library/stdtypes genericalias __parameters__}@anchor{21e5}
@deffn {Attribut} genericalias.__parameters__

Cet attribut est un `n'-uplet calculé paresseusement (éventuellement vide) de variables de type (chaque type n'est mentionné qu'une seule fois) trouvées dans @code{__args__} :

@example
>>> from typing import TypeVar

>>> T = TypeVar('T')
>>> list[T].__parameters__
(~T,)
@end example

@cartouche
@quotation Note 
un objet @code{GenericAlias} avec des paramètres @ref{15d,,typing.ParamSpec} peut ne pas avoir de @code{__parameters__} corrects après substitution car @ref{15d,,typing.ParamSpec} est principalement destiné à la vérification de type statique.
@end quotation
@end cartouche
@end deffn

@geindex __unpacked__ (attribut genericalias)
@anchor{library/stdtypes genericalias __unpacked__}@anchor{21e6}
@deffn {Attribut} genericalias.__unpacked__

Booléen qui est vrai si l'alias a été décompressé à l'aide de l'opérateur @code{*} (voir @ref{15e,,TypeVarTuple}).


Ajouté dans la version 3.11.

@end deffn


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 484

@item PEP 484@footnote{https://peps.python.org/pep-0484/} - Indications des types (page en anglais)

Présentation du cadre Python pour les annotations de type.

@geindex Python Enhancement Proposals; PEP 585

@item PEP 585@footnote{https://peps.python.org/pep-0585/} – Types génériques d'indication de type dans les conteneurs standard (page en anglais)

Présentation de la possibilité de paramétrer nativement les classes de la bibliothèque standard, à condition qu'elles implémentent la méthode de classe spéciale @ref{725,,__class_getitem__()}.

@item @ref{1f02,,Génériques}, @ref{4b8,,génériques personnalisés} et @ref{15a1,,typing.Generic}

Documentation sur la façon d'implémenter des classes génériques qui peuvent être paramétrées à l'exécution et comprises par les vérificateurs de type statiques.
@end table



Ajouté dans la version 3.9.


@node Type Union,,Type Alias générique,Types d'annotation de type — Alias générique Union
@anchor{library/stdtypes types-union}@anchor{7ac}@anchor{library/stdtypes union-type}@anchor{21e7}
@subsubsection Type Union


@geindex object;Union
@geindex union;type

Un objet `union' contient la valeur de l'opération @code{|} (OU bit à bit) sur plusieurs @ref{210a,,objets types}. Ces types sont principalement destinés aux @ref{441,,annotations de types}. L'expression d'union de types permet une syntaxe plus claire pour les indications de type par rapport à @ref{626,,typing.Union}.


@deffn {Describe} X | Y | ...

Définit un objet `union' qui contient les types `X', `Y', etc. @code{X | Y} signifie X ou Y. Cela équivaut à @code{typing.Union[X, Y]}. Par exemple, la fonction suivante attend un argument de type @ref{254,,int} ou @ref{2eb,,float} :

@example
def square(number: int | float) -> int | float:
    return number ** 2
@end example

@cartouche
@quotation Note 
The @code{|} operand cannot be used at runtime to define unions where one or
more members is a forward reference. For example, @code{int | "Foo"}, where
@code{"Foo"} is a reference to a class not yet defined, will fail at
runtime. For unions which include forward references, present the
whole expression as a string, e.g. @code{"int | Foo"}.
@end quotation
@end cartouche
@end deffn


@deffn {Describe} union_object == other

Les objets `union' peuvent être testés pour savoir s'ils sont égaux à d'autres objets `union'. Plus en détails :


@itemize *

@item 
Les unions d'unions sont aplaties :

@example
(int | str) | float == int | str | float
@end example

@item 
Les types redondants sont supprimés :

@example
int | str | int == int | str
@end example

@item 
Lors de la comparaison d'unions, l'ordre est ignoré :

@example
int | str == str | int
@end example

@item 
Il est compatible avec @ref{626,,typing.Union} :

@example
int | str == typing.Union[int, str]
@end example

@item 
Les types optionnels peuvent être orthographiés comme une union avec @code{None} :

@example
str | None == typing.Optional[str]
@end example
@end itemize
@end deffn


@deffn {Describe} isinstance(obj, union_object)
@end deffn


@deffn {Describe} issubclass(obj, union_object)

Les appels à @ref{42b,,isinstance()} et @ref{7ab,,issubclass()} sont également pris en charge avec un objet `union' :

@example
>>> isinstance("", int | str)
True
@end example

However, @ref{69d,,parameterized generics} in
union objects cannot be checked:

@example
>>> isinstance(1, int | list[int])  # short-circuit evaluation
True
>>> isinstance([1], int | list[int])
Traceback (most recent call last):
  ...
TypeError: isinstance() argument 2 cannot be a parameterized generic
@end example
@end deffn

Le type indiqué à l'utilisateur pour l'objet `union' est accessible par @ref{625,,types.UnionType} et utilisé pour les vérifications @ref{42b,,isinstance()}. Un objet ne peut pas être instancié à partir du type :

@example
>>> import types
>>> isinstance(int | str, types.UnionType)
True
>>> types.UnionType()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: cannot create 'types.UnionType' instances
@end example

@cartouche
@quotation Note 
The @code{__or__()} method for type objects was added to support the syntax
@code{X | Y}.  If a metaclass implements @code{__or__()}, the Union may
override it:

@example
>>> class M(type):
...     def __or__(self, other):
...         return "Hello"
...
>>> class C(metaclass=M):
...     pass
...
>>> C | int
'Hello'
>>> int | C
int | C
@end example
@end quotation
@end cartouche


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} – PEP proposant la syntaxe  @code{X | Y} et le type `Union'.



Ajouté dans la version 3.10.


@node Autres types natifs,Attributs spéciaux,Types d'annotation de type — Alias générique Union,Types natifs
@anchor{library/stdtypes other-built-in-types}@anchor{21e8}@anchor{library/stdtypes typesother}@anchor{21e9}
@subsection Autres types natifs


L'interpréteur gère aussi d'autres types d'objets, la plupart ne gèrent cependant qu'une ou deux opérations.

@menu
* Modules: Modules<4>. 
* Les classes et instances de classes:: 
* Fonctions:: 
* Méthodes:: 
* Objets code:: 
* Objets type:: 
* L'objet Null:: 
* L'objet points de suspension (ou ellipse): L'objet points de suspension ou ellipse. 
* L'objet NotImplemented:: 
* Objets internes:: 

@end menu

@node Modules<4>,Les classes et instances de classes,,Autres types natifs
@anchor{library/stdtypes modules}@anchor{21ea}@anchor{library/stdtypes typesmodules}@anchor{21eb}
@subsubsection Modules


La seule opération spéciale sur un module est l'accès à ses attributs : @code{m.name}, où `m' est un module et `name' donne accès un nom défini dans la table des symboles de `m'.  Il est possible d'assigner un attribut de module.  (Notez que l'instruction @ref{5cc,,import} n'est pas strictement une opération sur un objet module. @code{import foo} ne nécessite pas qu'un objet module nommé `foo' existe, il nécessite cependant une `définition' (externe) d'un module nommé `foo' quelque part.)

Un attribut spécial à chaque module est @ref{546,,__dict__}. C'est le dictionnaire contenant la table des symboles du module. Modifier ce dictionnaire change la table des symboles du module, mais assigner directement @ref{546,,__dict__} n'est pas possible (vous pouvez écrire @code{m.__dict__['a'] = 1}, qui donne @code{1} comme valeur pour @code{m.a}, mais vous ne pouvez pas écrire @code{m.__dict__ = @{@}}). Modifier @ref{546,,__dict__} directement n'est pas recommandé.

Les modules natifs de l'interpréteur sont affichés comme @code{<module 'sys' (built-in)>}.  S'ils sont chargés depuis un fichier, ils sont affichés sous la forme @code{<module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>}.

@node Les classes et instances de classes,Fonctions,Modules<4>,Autres types natifs
@anchor{library/stdtypes classes-and-class-instances}@anchor{21ec}@anchor{library/stdtypes typesobjects}@anchor{21ed}
@subsubsection Les classes et instances de classes


Voir @ref{1e67,,Objets@comma{} valeurs et types} et @ref{12b5,,Définition de classes}.

@node Fonctions,Méthodes,Les classes et instances de classes,Autres types natifs
@anchor{library/stdtypes functions}@anchor{21ee}@anchor{library/stdtypes typesfunctions}@anchor{21ef}
@subsubsection Fonctions


Les objets fonctions sont créés par les définitions de fonctions.  La seule opération applicable à un objet fonction est de l'appeler : @code{func(argument-list)}.

Il existe en fait deux catégories d'objets fonctions : les fonctions natives et les fonctions définies par l'utilisateur. Les deux gèrent les mêmes opérations (l'appel à la fonction), mais leur implémentation est différente, d'où les deux types distincts.

Voir @ref{1bc4,,Définition de fonctions} pour plus d'information.

@node Méthodes,Objets code,Fonctions,Autres types natifs
@anchor{library/stdtypes methods}@anchor{21f0}@anchor{library/stdtypes typesmethods}@anchor{21f1}
@subsubsection Méthodes


@geindex object;method

Methods are functions that are called using the attribute notation. There are
two flavors: @ref{1e92,,built-in methods} (such as @code{append()}
on lists) and @ref{1e86,,class instance method}.
Built-in methods are described with the types that support them.

If you access a method (a function defined in a class namespace) through an
instance, you get a special object: a `bound method' (also called
@ref{1e86,,instance method}) object. When called, it will add
the @code{self} argument
to the argument list.  Bound methods have two special read-only attributes:
@ref{137f,,m.__self__} is the object on which the method
operates, and @ref{12da,,m.__func__} is
the function implementing the method.  Calling @code{m(arg-1, arg-2, ..., arg-n)}
is completely equivalent to calling @code{m.__func__(m.__self__, arg-1, arg-2, ...,
arg-n)}.

Like @ref{296,,function objects}, bound method objects support
getting arbitrary
attributes.  However, since method attributes are actually stored on the
underlying function object (@ref{12da,,method.__func__}), setting method attributes on
bound methods is disallowed.  Attempting to set an attribute on a method
results in an @ref{343,,AttributeError} being raised.  In order to set a method
attribute, you need to explicitly set it on the underlying function object:

@example
>>> class C:
...     def method(self):
...         pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method'  # can't set on the method
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'method' object has no attribute 'whoami'
>>> c.method.__func__.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'
@end example

Voir @ref{1e86,,Méthodes d'instances} pour plus d'information.

@geindex object;code
@geindex code object

@node Objets code,Objets type,Méthodes,Autres types natifs
@anchor{library/stdtypes bltin-code-objects}@anchor{21f2}@anchor{library/stdtypes code-objects}@anchor{21f3}
@subsubsection Objets code


@geindex built-in function;compile
@geindex __code__ (function object attribute)

Code objects are used by the implementation to represent "pseudo-compiled"
executable Python code such as a function body. They differ from function
objects because they don't contain a reference to their global execution
environment.  Code objects are returned by the built-in @ref{190,,compile()} function
and can be extracted from function objects through their
@ref{297,,__code__} attribute. See also the @ref{1a,,code} module.

L'accès à @ref{297,,__code__} déclenche un @ref{1848,,événement d'audit} @code{object.__getattr__} avec les arguments @code{obj} et @code{"__code__"}.

@geindex built-in function;exec
@geindex built-in function;eval

Les objets code peuvent être exécutés ou évalués en les passant (au lieu d'une chaîne contenant du code) aux fonctions natives @ref{17d,,exec()} ou @ref{17e,,eval()}.

Voir @ref{1e6a,,Hiérarchie des types standards} pour plus d'information.

@node Objets type,L'objet Null,Objets code,Autres types natifs
@anchor{library/stdtypes bltin-type-objects}@anchor{210a}@anchor{library/stdtypes type-objects}@anchor{21f4}
@subsubsection Objets type


@geindex built-in function;type
@geindex module;types

Les objets types représentent les différents types d'objets. Le type d'un objet est obtenu via la fonction native @ref{d36,,type()}. Il n'existe aucune opération spéciale sur les types. Le module standard @ref{102,,types} définit les noms de tous les types natifs.

Les types sont affichés comme suit : @code{<class 'int'>}.

@node L'objet Null,L'objet points de suspension ou ellipse,Objets type,Autres types natifs
@anchor{library/stdtypes bltin-null-object}@anchor{21f5}@anchor{library/stdtypes the-null-object}@anchor{21f6}
@subsubsection L'objet Null


Cet objet est renvoyé par les fonctions ne renvoyant pas explicitement une valeur. Il ne gère aucune opération spéciale. Il existe exactement un seul objet `null' nommé @code{None} (c'est un nom natif). @code{type(None)()} produit ce singleton.

Il s'écrit @code{None}.

@geindex ...;ellipsis literal

@node L'objet points de suspension ou ellipse,L'objet NotImplemented,L'objet Null,Autres types natifs
@anchor{library/stdtypes bltin-ellipsis-object}@anchor{21f7}@anchor{library/stdtypes the-ellipsis-object}@anchor{21f8}
@subsubsection L'objet points de suspension (ou ellipse)


Cet objet est utilisé classiquement lors des découpes (voir @ref{1fcc,,Tranches}). Il ne gère aucune opération spéciale. Il n'y a qu'un seul objet `points de suspension', nommé @ref{210e,,Ellipsis} (un nom natif). @code{type(Ellipsis)()} produit le `singleton' @ref{210e,,Ellipsis}.

Il s'écrit @code{Ellipsis} ou @code{...}.

@node L'objet NotImplemented,Objets internes,L'objet points de suspension ou ellipse,Autres types natifs
@anchor{library/stdtypes bltin-notimplemented-object}@anchor{21f9}@anchor{library/stdtypes the-notimplemented-object}@anchor{21fa}
@subsubsection L'objet `NotImplemented'


Cet objet est renvoyé depuis des comparaisons ou des opérations binaires effectuées sur des types qu'elles ne gèrent pas. Voir @ref{1ff5,,Comparaisons} pour plus d'informations. Il n'y a qu'un seul objet @ref{7bc,,NotImplemented}. @code{type(NotImplemented)()} renvoie cette instance de singleton.

Il s'écrit @code{NotImplemented}.

@node Objets internes,,L'objet NotImplemented,Autres types natifs
@anchor{library/stdtypes internal-objects}@anchor{21fb}@anchor{library/stdtypes typesinternal}@anchor{21fc}
@subsubsection Objets internes


See @ref{1e6a,,Hiérarchie des types standards} for this information.  It describes
@ref{6ca,,stack frame objects},
@ref{ae2,,traceback objects}, and slice objects.

@node Attributs spéciaux,Limitation de longueur de conversion de chaîne vers un entier,Autres types natifs,Types natifs
@anchor{library/stdtypes special-attributes}@anchor{21fd}@anchor{library/stdtypes specialattrs}@anchor{21fe}
@subsection Attributs spéciaux


L'implémentation ajoute quelques attributs spéciaux en lecture seule à certains types, lorsque ça a du sens. Certains ne sont pas listés par la fonction native @ref{61d,,dir()}.

@geindex __name__ (attribut definition)
@anchor{library/stdtypes definition __name__}@anchor{104f}
@deffn {Attribut} definition.__name__

Nom de la classe, fonction, méthode, descripteur ou instance du générateur.
@end deffn

@geindex __qualname__ (attribut definition)
@anchor{library/stdtypes definition __qualname__}@anchor{104e}
@deffn {Attribut} definition.__qualname__

@ref{18ce,,Nom qualifié} de la classe, fonction, méthode, descripteur ou instance du générateur.


Ajouté dans la version 3.3.

@end deffn

@geindex __module__ (attribut definition)
@anchor{library/stdtypes definition __module__}@anchor{21ff}
@deffn {Attribut} definition.__module__

The name of the module in which a class or function was defined.
@end deffn

@geindex __doc__ (attribut definition)
@anchor{library/stdtypes definition __doc__}@anchor{915}
@deffn {Attribut} definition.__doc__

The documentation string of a class or function, or @code{None} if undefined.
@end deffn

@geindex __type_params__ (attribut definition)
@anchor{library/stdtypes definition __type_params__}@anchor{20bc}
@deffn {Attribut} definition.__type_params__

The @ref{2b0,,type parameters} of generic classes, functions,
and @ref{43d,,type aliases}. For classes and functions that
are not generic, this will be an empty tuple.


Ajouté dans la version 3.12.

@end deffn

@node Limitation de longueur de conversion de chaîne vers un entier,,Attributs spéciaux,Types natifs
@anchor{library/stdtypes int-max-str-digits}@anchor{5df}@anchor{library/stdtypes integer-string-conversion-length-limitation}@anchor{2200}
@subsection Limitation de longueur de conversion de chaîne vers un entier


CPython a une limite globale pour la conversion entre @ref{254,,int} et @ref{435,,str} pour atténuer les attaques par déni de service. Cette limite s'applique `uniquement' aux décimaux ou autres bases de nombres qui ne sont pas des puissances de deux. Les conversions hexadécimales, octales et binaires sont illimitées. La limite peut être configurée.

Le type @ref{254,,int} dans CPython stocke un nombre de longueur arbitraire sous forme binaire (communément appelé « `bignum' »). Il n'existe aucun algorithme capable de convertir une chaîne en un entier binaire ou un entier binaire en une chaîne en temps linéaire, sauf si la base est une puissance de 2. Même les meilleurs algorithmes connus pour la base 10 ont une complexité sous-quadratique. La conversion d'une grande valeur telle que @code{int('1' * 500_000)} peut prendre plus d'une seconde sur un CPU rapide.

Limiter la taille de la conversion offre un moyen pratique d'éviter la vulnérabilité 
@geindex Common Vulnerabilities and Exposures; CVE 2020-10735
CVE 2020-10735@footnote{https://www.cve.org/CVERecord?id=CVE-2020-10735}.

La limite est appliquée au nombre de caractères numériques dans la chaîne d'entrée ou de sortie lorsqu'un algorithme de conversion non linéaire doit être appliqué. Les traits de soulignement et le signe ne sont pas comptés dans la limite.

Si une opération va dépasser la limite, une @ref{1ff,,ValueError} est levée :

@example
>>> import sys
>>> sys.set_int_max_str_digits(4300)  # Illustrative, this is the default.
>>> _ = int('2' * 5432)
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion: value has 5432 digits; use sys.set_int_max_str_digits() to increase the limit
>>> i = int('2' * 4300)
>>> len(str(i))
4300
>>> i_squared = i*i
>>> len(str(i_squared))
Traceback (most recent call last):
...
ValueError: Exceeds the limit (4300 digits) for integer string conversion; use sys.set_int_max_str_digits() to increase the limit
>>> len(hex(i_squared))
7144
>>> assert int(hex(i_squared), base=16) == i*i  # Hexadecimal is unlimited.
@end example

La limite par défaut est de 4 300 chiffres comme indiqué dans @ref{1271,,sys.int_info.default_max_str_digits}. La limite la plus basse pouvant être configurée est de 640 chiffres, comme indiqué dans @ref{1271,,sys.int_info.str_digits_check_threshold}.

Vérification :

@example
>>> import sys
>>> assert sys.int_info.default_max_str_digits == 4300, sys.int_info
>>> assert sys.int_info.str_digits_check_threshold == 640, sys.int_info
>>> msg = int('578966293710682886880994035146873798396722250538762761564'
...           '9252925514383915483333812743580549779436104706260696366600'
...           '571186405732').to_bytes(53, 'big')
...
@end example


Ajouté dans la version 3.11.


@menu
* API concernées:: 
* Configuration de la limite:: 
* Configuration recommandée:: 

@end menu

@node API concernées,Configuration de la limite,,Limitation de longueur de conversion de chaîne vers un entier
@anchor{library/stdtypes affected-apis}@anchor{2201}
@subsubsection API concernées


La limitation s'applique uniquement aux conversions potentiellement lentes entre @ref{254,,int} et @ref{435,,str} ou @ref{1bd,,bytes} :


@itemize *

@item 
@code{int(string)} en base 10 (par défaut).

@item 
@code{int(string, base)} pour toutes les bases qui ne sont pas des puissances de 2.

@item 
@code{str(integer)}.

@item 
@code{repr(integer)}.

@item 
toute autre conversion de chaîne en base 10, par exemple @code{f"@{integer@}"}, @code{"@{@}".format(integer)} ou @code{b"%d" % integer}.
@end itemize

Les limitations ne s'appliquent pas aux fonctions avec un algorithme linéaire :


@itemize *

@item 
@code{int(chaîne, base)} en base 2, 4, 8, 16 ou 32.

@item 
@ref{17dd,,int.from_bytes()} et @ref{181d,,int.to_bytes()}.

@item 
@ref{12ad,,hex()}, @ref{12ac,,oct()}, @ref{1286,,bin()}.

@item 
@ref{1e5,,Mini-langage de spécification de format} pour les nombres hexadécimaux, octaux et binaires.

@item 
@ref{435,,str} vers @ref{2eb,,float}.

@item 
@ref{435,,str} vers @ref{29a,,decimal.Decimal}.
@end itemize

@node Configuration de la limite,Configuration recommandée,API concernées,Limitation de longueur de conversion de chaîne vers un entier
@anchor{library/stdtypes configuring-the-limit}@anchor{2202}
@subsubsection Configuration de la limite


Avant le démarrage de Python, vous pouvez utiliser une variable d'environnement ou une option de ligne de commande d'interpréteur pour configurer la limite :


@itemize *

@item 
@geindex PYTHONINTMAXSTRDIGITS
@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@ref{174b,,PYTHONINTMAXSTRDIGITS}, par exemple @code{PYTHONINTMAXSTRDIGITS=640 python3} pour fixer la limite à 640 chiffres ou @code{PYTHONINTMAXSTRDIGITS=0 python3} pour désactiver la limitation.

@item 
@ref{175,,-X int_max_str_digits}, par exemple @code{python3 -X int_max_str_digits=640}

@item 
@ref{2203,,sys.flags.int_max_str_digits} contient la valeur de 
@geindex PYTHONINTMAXSTRDIGITS
@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@ref{174b,,PYTHONINTMAXSTRDIGITS} ou @ref{175,,-X int_max_str_digits}. Si la variable d'environnement et l'option @code{-X} sont définies toutes les deux, l'option @code{-X} est prioritaire. Une valeur de `-1' indique que les deux n'étaient pas définies, donc qu'une valeur de @ref{2204,,sys.int_info.default_max_str_digits} a été utilisée lors de l'initialisation.
@end itemize

Depuis le code, vous pouvez inspecter la limite actuelle et en définir une nouvelle à l'aide de ces API @ref{d8,,sys} :


@itemize *

@item 
@ref{2205,,sys.get_int_max_str_digits()} et @ref{174c,,sys.set_int_max_str_digits()} sont un accesseur et un mutateur pour la limite relative à l'interpréteur. Les sous-interprètes possèdent leur propre limite.
@end itemize

Des informations sur la valeur par défaut et le minimum peuvent être trouvées dans @ref{1271,,sys.int_info} :


@itemize *

@item 
@ref{1271,,sys.int_info.default_max_str_digits} est la limite par défaut pour la compilation.

@item 
@ref{1271,,sys.int_info.str_digits_check_threshold} est la valeur la plus basse acceptée pour la limite (autre que 0 qui la désactive).
@end itemize


Ajouté dans la version 3.11.


@cartouche
@quotation Prudence 
fixer une limite basse `peut' entraîner des problèmes. Bien que rare, du code contenant des constantes entières en décimal dans la source qui dépasse le seuil minimum peut exister. Une conséquence de la définition de la limite est que le code source Python contenant des littéraux entiers décimaux plus longs que la limite lèvera une erreur lors de l'analyse, généralement au démarrage ou à l'importation ou même au moment de l'installation – dès qu'un @code{.pyc} à jour n'existe pas déjà pour le code. Une solution de contournement pour les sources qui contiennent de si grandes constantes consiste à les convertir au format hexadécimal @code{0x} car il n'y a pas de limite.

Testez soigneusement votre application si vous utilisez une limite basse. Assurez-vous que vos tests s'exécutent avec la limite définie au début `via' l'environnement ou l'option de ligne de commande afin qu'elle s'applique au démarrage et même lors de toute étape d'installation pouvant invoquer Python pour compiler les sources @code{.py} en fichiers @code{.pyc}.
@end quotation
@end cartouche

@node Configuration recommandée,,Configuration de la limite,Limitation de longueur de conversion de chaîne vers un entier
@anchor{library/stdtypes recommended-configuration}@anchor{2206}
@subsubsection Configuration recommandée


La valeur par défaut @ref{2204,,sys.int_info.default_max_str_digits} devrait être raisonnable pour la plupart des applications. Si votre application nécessite une limite différente, définissez-la à partir de votre point d'entrée principal à l'aide d'un code indépendant de la version Python, car ces API ont été ajoutées dans des correctifs de sécurité des versions antérieures à 3.12.

Par exemple :

@example
>>> import sys
>>> if hasattr(sys, "set_int_max_str_digits"):
...     upper_bound = 68000
...     lower_bound = 4004
...     current_limit = sys.get_int_max_str_digits()
...     if current_limit == 0 or current_limit > upper_bound:
...         sys.set_int_max_str_digits(upper_bound)
...     elif current_limit < lower_bound:
...         sys.set_int_max_str_digits(lower_bound)
@end example

Pour la désactiver entièrement, réglez-la à @code{0}.

@subsubheading Notes


@node Exceptions natives,Services de Manipulation de Texte,Types natifs,La bibliothèque standard
@anchor{library/exceptions doc}@anchor{2207}@anchor{library/exceptions bltin-exceptions}@anchor{1811}@anchor{library/exceptions built-in-exceptions}@anchor{2208}
@section Exceptions natives


@geindex statement;try
@geindex statement;except

En python, une exception est une instance d'une classe héritée de @ref{5a5,,BaseException}. Dans un bloc @ref{6d3,,try}, la clause  @ref{189,,except} traite non seulement la classe d'exception qu'elle mentionne, mais aussi toutes les classes dérivées de cette classe (contrairement à ses classes mères).  Deux classes qui ne sont pas liées par héritage ne sont jamais équivalentes, même si elles ont le même nom.

@geindex statement;raise

The built-in exceptions listed in this chapter can be generated by the interpreter or
built-in functions.  Except where mentioned, they have an "associated value"
indicating the detailed cause of the error.  This may be a string or a tuple of
several items of information (e.g., an error code and a string explaining the
code).  The associated value is usually passed as arguments to the exception
class's constructor.

Du code utilisateur peut lever des exceptions natives. Cela peut être utilisé pour tester un gestionnaire d'exception ou pour rapporter une condition d'erreur "comme si" c'était l'interpréteur qui levait cette exception ; mais attention car rien n'empêche du code utilisateur de lever une erreur inappropriée.

Les classes d'exception natives peuvent être héritées pour définir de nouvelles exceptions ; les programmeurs sont encouragés à faire dériver les nouvelles exceptions de la classe @ref{9c7,,Exception} ou d'une de ses sous-classes, et non de @ref{5a5,,BaseException}. Plus d'informations sur la définition des exceptions sont disponibles dans le Tutoriel Python au chapitre @ref{1c22,,Exceptions définies par l'utilisateur}.

@menu
* Contexte des exceptions:: 
* Hériter des exceptions natives:: 
* Classes mères:: 
* Exceptions concrètes:: 
* Avertissements:: 
* Exception groups:: 
* Hiérarchie des exceptions:: 

@end menu

@node Contexte des exceptions,Hériter des exceptions natives,,Exceptions natives
@anchor{library/exceptions exception-context}@anchor{2209}
@subsection Contexte des exceptions


@geindex exception;chaining
@geindex __cause__ (exception attribute)
@geindex __context__ (exception attribute)
@geindex __suppress_context__ (exception attribute)

Three attributes on exception objects provide information about the context in
which the exception was raised:

@geindex __context__ (attribut BaseException)
@geindex __cause__ (attribut BaseException)
@geindex __suppress_context__ (attribut BaseException)
@anchor{library/exceptions BaseException __context__}@anchor{12a5}
@deffn {Attribut} BaseException.__context__
@anchor{library/exceptions BaseException __cause__}@anchor{12a6}
@deffnx {Attribut} BaseException.__cause__
@anchor{library/exceptions BaseException __suppress_context__}@anchor{2037}
@deffnx {Attribut} BaseException.__suppress_context__

When raising a new exception while another exception
is already being handled, the new exception's
@code{__context__} attribute is automatically set to the handled
exception.  An exception may be handled when an @ref{189,,except} or
@ref{9b8,,finally} clause, or a @ref{5bc,,with} statement, is used.

Ce contexte implicite d'exception peut être complété par une cause explicite en utilisant @code{from} avec @ref{5d7,,raise} :

@example
raise new_exc from original_exc
@end example

The expression following @ref{5d7,,from} must be an exception or @code{None}. It
will be set as @code{__cause__} on the raised exception. Setting
@code{__cause__} also implicitly sets the @code{__suppress_context__}
attribute to @code{True}, so that using @code{raise new_exc from None}
effectively replaces the old exception with the new one for display
purposes (e.g. converting @ref{33a,,KeyError} to @ref{343,,AttributeError}), while
leaving the old exception available in @code{__context__} for introspection
when debugging.

The default traceback display code shows these chained exceptions in
addition to the traceback for the exception itself. An explicitly chained
exception in @code{__cause__} is always shown when present. An implicitly
chained exception in @code{__context__} is shown only if @code{__cause__}
is @ref{660,,None} and @code{__suppress_context__} is false.

Dans les deux cas, l'exception elle-même est toujours affichée après toutes les exceptions enchaînées, de sorte que la dernière ligne de la trace d'appels montre toujours la dernière exception qui a été levée.
@end deffn

@node Hériter des exceptions natives,Classes mères,Contexte des exceptions,Exceptions natives
@anchor{library/exceptions inheriting-from-built-in-exceptions}@anchor{220a}
@subsection Hériter des exceptions natives


Le code de l'utilisateur peut créer des sous-classes qui dérivent d'un type d'exception. Il est recommandé de ne dériver que d'un seul type d'exception à la fois pour éviter des conflits possibles dans la façon dont les classes mères traitent l'argument @code{args} ainsi que des incompatibilités potentielles avec l'utilisation de la mémoire.

`Particularité de l'implémentation CPython :' La majorité des exceptions natives sont implémentées en C pour des raisons d'efficacité, voir Objects/exceptions.c@footnote{https://github.com/python/cpython/tree/3.13/Objects/exceptions.c}. L'architecture interne de certaines est telle que cela rend impossible la création de sous-classes qui dérivent de plusieurs types d'exceptions. L'agencement de la mémoire est un détail d'implémentation qui est sujet à changement d'une version de Python à l'autre, ce qui peut poser conflit dans le futur. Il est donc déconseillé de dériver de plusieurs types d'exceptions.

@node Classes mères,Exceptions concrètes,Hériter des exceptions natives,Exceptions natives
@anchor{library/exceptions base-classes}@anchor{220b}
@subsection Classes mères


Les exceptions suivantes sont utilisées principalement en tant que classes mères pour d'autres exceptions.

@geindex BaseException
@anchor{library/exceptions BaseException}@anchor{5a5}
@deffn {Exception} BaseException

La classe mère pour toutes les exceptions natives. Elle n'est pas vouée à être héritée directement par des classes utilisateur (pour cela, utilisez @ref{9c7,,Exception}). Si @ref{435,,str()} est appelée sur une instance de cette classe, la représentation du ou des argument(s) de l'instance est retournée, ou la chaîne vide s'il n'y avait pas d'arguments.

@geindex args (attribut BaseException)
@anchor{library/exceptions BaseException args}@anchor{558}
@deffn {Attribut} args

Le `n'-uplet d'arguments donné au constructeur d'exception. Certaines exceptions natives (comme @ref{40d,,OSError}) attendent un certain nombre d'arguments et attribuent une signification spéciale aux éléments de ce `n'-uplet, alors que d'autres ne sont généralement appelées qu'avec une seule chaîne de caractères rendant un message d'erreur.
@end deffn

@geindex with_traceback() (méthode BaseException)
@anchor{library/exceptions BaseException with_traceback}@anchor{2036}
@deffn {Méthode} with_traceback (tb)

Cette méthode affecte `tb' comme la nouvelle trace d'appels de l'exception et renvoie l'objet exception. Elle était utilisée de façon plus courante avant que la fonctionnalité de chaînage des exceptions de la 
@geindex Python Enhancement Proposals; PEP 3134
PEP 3134@footnote{https://peps.python.org/pep-3134/} devienne disponible. L'exemple suivant démontre comment convertir une instance de @code{SomeException} en une instance de @code{OtherException} tout en préservant la pile d'appels. Une fois l'exception levée, le cadre courant est empilé sur la trace d'appels de @code{OtherException}, comme cela se serait produit pour la trace d'appels de @code{SomeException} si on l'avait laissée se propager jusqu'à l'appelant

@example
try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)
@end example
@end deffn

@geindex __traceback__ (attribut BaseException)
@anchor{library/exceptions BaseException __traceback__}@anchor{12a4}
@deffn {Attribut} __traceback__

A writable field that holds the
@ref{ae2,,traceback object} associated with this
exception. See also: @ref{5d7,,L'instruction raise}.
@end deffn

@geindex add_note() (méthode BaseException)
@anchor{library/exceptions BaseException add_note}@anchor{5a4}
@deffn {Méthode} add_note (note)

Add the string @code{note} to the exception's notes which appear in the standard
traceback after the exception string. A @ref{522,,TypeError} is raised if @code{note}
is not a string.


Ajouté dans la version 3.11.

@end deffn

@geindex __notes__ (attribut BaseException)
@anchor{library/exceptions BaseException __notes__}@anchor{220c}
@deffn {Attribut} __notes__

A list of the notes of this exception, which were added with @ref{5a4,,add_note()}.
This attribute is created when @ref{5a4,,add_note()} is called.


Ajouté dans la version 3.11.

@end deffn
@end deffn

@geindex Exception
@anchor{library/exceptions Exception}@anchor{9c7}
@deffn {Exception} Exception

Toutes les exceptions natives, qui n'entraînent pas une sortie du système dérivent de cette classe. Toutes les exceptions définies par l'utilisateur devraient également être dérivées de cette classe.
@end deffn

@geindex ArithmeticError
@anchor{library/exceptions ArithmeticError}@anchor{220d}
@deffn {Exception} ArithmeticError

La classe mère pour les exceptions natives qui sont levées pour diverses erreurs arithmétiques : @ref{86d,,OverflowError}, @ref{932,,ZeroDivisionError}, @ref{220e,,FloatingPointError}.
@end deffn

@geindex BufferError
@anchor{library/exceptions BufferError}@anchor{17b2}
@deffn {Exception} BufferError

Levée lorsqu'une opération liée à un @ref{38e,,tampon} ne peut pas être exécutée.
@end deffn

@geindex LookupError
@anchor{library/exceptions LookupError}@anchor{2155}
@deffn {Exception} LookupError

La classe mère pour les exceptions qui sont levées lorsqu'une clé ou un index utilisé sur un tableau de correspondances ou une séquence est invalide : @ref{14eb,,IndexError}, @ref{33a,,KeyError}. Peut être levée directement par @ref{950,,codecs.lookup()}.
@end deffn

@node Exceptions concrètes,Avertissements,Classes mères,Exceptions natives
@anchor{library/exceptions concrete-exceptions}@anchor{220f}
@subsection Exceptions concrètes


Les exceptions suivantes sont celles qui sont habituellement levées.

@geindex AssertionError
@anchor{library/exceptions AssertionError}@anchor{694}
@deffn {Exception} AssertionError

@geindex statement;assert

Levée lorsqu'une instruction @ref{955,,assert} échoue.
@end deffn

@geindex AttributeError
@anchor{library/exceptions AttributeError}@anchor{343}
@deffn {Exception} AttributeError

Levée lorsqu'une référence ou une assignation d'attribut (voir @ref{1fc6,,Références à des attributs}) échoue. (Lorsqu'un objet ne supporte pas du tout la référence ou l'assignation d'attribut, @ref{522,,TypeError}  est levé.)

Les attributs @code{name} et @code{obj} peuvent être définis uniquement à l'aide d'arguments nommés passés au constructeur. Lorsqu'ils sont définis, ils représentent respectivement le nom de l'attribut pour lequel il y a eu une tentative d'accès et l'objet qui a été accédé pour cet attribut.


Modifié dans la version 3.10: Ajout des attributs @code{name} et @code{obj}.

@end deffn

@geindex EOFError
@anchor{library/exceptions EOFError}@anchor{12b7}
@deffn {Exception} EOFError

Levée lorsque la fonction @ref{12b6,,input()} atteint une condition de fin de fichier (EOF) sans lire aucune donnée. (N.B. : les méthodes @code{io.IOBase.read()} et @ref{1307,,io.IOBase.readline()} retournent une chaîne vide lorsqu'elles atteignent EOF.)
@end deffn

@geindex FloatingPointError
@anchor{library/exceptions FloatingPointError}@anchor{220e}
@deffn {Exception} FloatingPointError

N’est pas utilisé pour le moment.
@end deffn

@geindex GeneratorExit
@anchor{library/exceptions GeneratorExit}@anchor{137e}
@deffn {Exception} GeneratorExit

Levée lorsqu'un @ref{104a,,generator} ou une @ref{47b,,coroutine} est fermé, voir @ref{167d,,generator.close()} et @ref{1f50,,coroutine.close()}. Elle hérite directement de @ref{5a5,,BaseException} au lieu de @ref{9c7,,Exception} puisqu'il ne s'agit pas techniquement d'une erreur.
@end deffn

@geindex ImportError
@anchor{library/exceptions ImportError}@anchor{40f}
@deffn {Exception} ImportError

Levée lorsque l'instruction @ref{5cc,,import} a des problèmes pour essayer de charger un module. Également levée lorsque Python ne trouve pas un nom dans @code{from ... import}.

The optional `name' and `path' keyword-only arguments
set the corresponding attributes:

@geindex name (attribut ImportError)
@anchor{library/exceptions ImportError name}@anchor{2210}
@deffn {Attribut} name

The name of the module that was attempted to be imported.
@end deffn

@geindex path (attribut ImportError)
@anchor{library/exceptions ImportError path}@anchor{2211}
@deffn {Attribut} path

The path to any file which triggered the exception.
@end deffn


Modifié dans la version 3.3: Ajout des attributs @ref{2210,,name} et @ref{2211,,path}.

@end deffn

@geindex ModuleNotFoundError
@anchor{library/exceptions ModuleNotFoundError}@anchor{b35}
@deffn {Exception} ModuleNotFoundError

Une sous-classe de @ref{40f,,ImportError} qui est levée par @ref{5cc,,import} lorsqu'un module n'a pas pu être localisé. Elle est généralement levée quand @code{None} est trouvé dans @ref{18f9,,sys.modules}.


Ajouté dans la version 3.6.

@end deffn

@geindex IndexError
@anchor{library/exceptions IndexError}@anchor{14eb}
@deffn {Exception} IndexError

Levée lorsqu'un indice de séquence est hors de la plage. (Les indices de tranches (`slices') sont tronqués silencieusement pour tomber dans la plage autorisée ; si un indice n'est pas un entier, @ref{522,,TypeError} est levée.)

@c XXX xref to sequences
@end deffn

@geindex KeyError
@anchor{library/exceptions KeyError}@anchor{33a}
@deffn {Exception} KeyError

Levée lorsqu'une clef (de dictionnaire) n'est pas trouvée dans l'ensemble des clefs existantes.

@c XXX xref to mapping objects?
@end deffn

@geindex KeyboardInterrupt
@anchor{library/exceptions KeyboardInterrupt}@anchor{9bf}
@deffn {Exception} KeyboardInterrupt

Levée lorsque l'utilisateur appuie sur la touche d'interruption (normalement @code{Control-C} or @code{Delete}). Pendant l'exécution, un contrôle des interruptions est effectué régulièrement. L'exception hérite de @ref{5a5,,BaseException} afin de ne pas être accidentellement interceptée par du code qui intercepte @ref{9c7,,Exception} et ainsi empêcher l'interpréteur de quitter.

@cartouche
@quotation Note 
Attraper une @ref{9bf,,KeyboardInterrupt} demande une considération particulière. Comme elle peut être levée à des moments imprévisibles, elle peut dans certains cas laisser le programme en cours d'exécution dans un état incohérent. Il est généralement préférable de laisser @ref{9bf,,KeyboardInterrupt} arrêter le programme aussi rapidement que possible ou d'éviter catégoriquement de la lever (voir @ref{2212,,Note on Signal Handlers and Exceptions}).
@end quotation
@end cartouche
@end deffn

@geindex MemoryError
@anchor{library/exceptions MemoryError}@anchor{164b}
@deffn {Exception} MemoryError

Levée lorsqu'une opération est à court de mémoire mais que la situation peut encore être rattrapée (en supprimant certains objets). La valeur associée est une chaîne de caractères indiquant quel type d'opération (interne) est à court de mémoire. À noter qu'en raison de l'architecture interne de gestion de la mémoire (la fonction @code{malloc()} du C), l'interpréteur peut ne pas toujours être capable de rattraper cette situation ; il lève néanmoins une exception pour qu'une pile d'appels puisse être affichée, dans le cas où un programme en cours d'exécution en était la cause.
@end deffn

@geindex NameError
@anchor{library/exceptions NameError}@anchor{428}
@deffn {Exception} NameError

Levée lorsqu'un nom local ou global n'est pas trouvé. Ceci ne s'applique qu'aux noms non qualifiés. La valeur associée est un message d'erreur qui inclut le nom qui n'a pas pu être trouvé.

L'attribut @code{name} doit être défini uniquement à l'aide d'un argument nommé passé au constructeur. Lorsqu'il est défini, il représente le nom de la variable pour laquelle il y a eu une tentative d'accès.


Modifié dans la version 3.10: Ajout de l'attribut @code{name}.

@end deffn

@geindex NotImplementedError
@anchor{library/exceptions NotImplementedError}@anchor{225}
@deffn {Exception} NotImplementedError

Cette exception est dérivée de @ref{193,,RuntimeError}. Dans les classes mères définies par l'utilisateur, les méthodes abstraites devraient lever cette exception lorsqu'elles nécessitent des classes dérivées pour remplacer la méthode, ou lorsque la classe est en cours de développement pour indiquer que l'implémentation concrète doit encore être ajoutée.

@cartouche
@quotation Note 
Elle ne devrait pas être utilisée pour indiquer qu'un opérateur ou qu'une méthode n'est pas destiné à être pris en charge du tout – dans ce cas, évitez de définir l'opérateur ou la méthode, ou s'il s'agit d'une sous-classe, assignez-le à @ref{660,,None}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
@code{NotImplementedError} and @ref{7bc,,NotImplemented} are not interchangeable,
even though they have similar names and purposes.  See
@code{NotImplemented} for details on when to use it.
@end quotation
@end cartouche
@end deffn

@geindex OSError
@anchor{library/exceptions OSError}@anchor{40d}
@deffn {Exception} OSError ([arg])

@deffnx {Exception} OSError (errno, strerror[, filename[, winerror[, filename2]]])

@geindex module;errno

Cette exception est levée lorsqu'une fonction système retourne une erreur liée au système, incluant les erreurs entrées-sorties telles que "fichier non trouvé" ou "disque plein" (pas pour les types d'arguments illégaux ou d'autres erreurs accidentelles).

La deuxième forme du constructeur définit les attributs correspondants, décrits ci-dessous. Les attributs par défaut sont @ref{660,,None} si non spécifiés. Pour la rétrocompatibilité, si trois arguments sont passés, l'attribut @ref{558,,args} contient seulement une paire avec les valeurs des deux premiers arguments du constructeur.

Le constructeur retourne souvent une sous-classe d'@ref{40d,,OSError}, comme décrit dans @ref{2213,,OS exceptions} ci-dessous. La sous-classe particulière dépend de la valeur finale d'@ref{2214,,errno}. Ce comportement ne se produit que lors de la construction d'@ref{40d,,OSError} directement ou via un alias, et n'est pas hérité lors du sous-classement.

@geindex errno (attribut OSError)
@anchor{library/exceptions OSError errno}@anchor{2214}
@deffn {Attribut} errno

Code d'erreur numérique de la variable C @code{errno}.
@end deffn

@geindex winerror (attribut OSError)
@anchor{library/exceptions OSError winerror}@anchor{2215}
@deffn {Attribut} winerror

Sous Windows, cela donne le code d'erreur Windows natif. L'attribut @ref{2214,,errno} est alors une traduction approximative, en termes POSIX, de ce code d'erreur natif.

Sous Windows, si l'argument du constructeur `winerror' est un entier, l'attribut @ref{2214,,errno} est déterminé à partir du code d'erreur Windows, et l'argument `errno' est ignoré. Sur d'autres plateformes, l'argument `winerror' est ignoré, et l'attribut @ref{2215,,winerror} n'existe pas.
@end deffn

@geindex strerror (attribut OSError)
@anchor{library/exceptions OSError strerror}@anchor{2216}
@deffn {Attribut} strerror

Le message d'erreur correspondant, tel que fourni par le système d'exploitation. Il est formaté par les fonctions C @code{perror()} sous POSIX, et @code{FormatMessage()} sous Windows.
@end deffn

@geindex filename (attribut OSError)
@geindex filename2 (attribut OSError)
@anchor{library/exceptions OSError filename}@anchor{2217}
@deffn {Attribut} filename
@anchor{library/exceptions OSError filename2}@anchor{2218}
@deffnx {Attribut} filename2

Pour les exceptions qui font référence à un chemin d'accès au système de fichiers (comme @ref{505,,open()} ou @ref{10d6,,os.unlink()}), @ref{2217,,filename} est le nom du fichier transmis à la fonction. Pour les fonctions qui font référence à deux chemins d'accès au système de fichiers (comme @ref{10d2,,os.rename()}), @ref{2218,,filename2} correspond au deuxième nom de fichier passé à la fonction.
@end deffn


Modifié dans la version 3.3: @ref{103c,,EnvironmentError}, @ref{103b,,IOError}, @ref{103d,,WindowsError}, @ref{103e,,socket.error}, @ref{103f,,select.error} et @code{mmap.error} ont fusionnées en @ref{40d,,OSError}, et le constructeur peut renvoyer une sous-classe.



Modifié dans la version 3.4: L'attribut @ref{2217,,filename} est maintenant le nom du fichier originel passé à la fonction, au lieu du nom encodé ou décodé à partir du @ref{525,,gestionnaire d'encodage et d'erreur du système de fichiers}. De plus, l'argument du constructeur et attribut `filename2' a été ajouté.

@end deffn

@geindex OverflowError
@anchor{library/exceptions OverflowError}@anchor{86d}
@deffn {Exception} OverflowError

Raised when the result of an arithmetic operation is too large to be
represented.  This cannot occur for integers (which would rather raise
@ref{164b,,MemoryError} than give up).  However, for historical reasons,
OverflowError is sometimes raised for integers that are outside a required
range.   Because of the lack of standardization of floating-point exception
handling in C, most floating-point operations are not checked.
@end deffn

@geindex PythonFinalizationError
@anchor{library/exceptions PythonFinalizationError}@anchor{14c}
@deffn {Exception} PythonFinalizationError

This exception is derived from @ref{193,,RuntimeError}.  It is raised when
an operation is blocked during interpreter shutdown also known as
@ref{14d,,Python finalization}.

Examples of operations which can be blocked with a
@ref{14c,,PythonFinalizationError} during the Python finalization:


@itemize *

@item 
Creating a new Python thread.

@item 
@ref{195,,os.fork()}.
@end itemize

See also the @ref{a7d,,sys.is_finalizing()} function.


Ajouté dans la version 3.13: Auparavant, une simple @ref{193,,RuntimeError} était levée.

@end deffn

@geindex RecursionError
@anchor{library/exceptions RecursionError}@anchor{d59}
@deffn {Exception} RecursionError

Cette exception est dérivée de @ref{193,,RuntimeError}. Elle est levée lorsque l'interpréteur détecte que la profondeur de récursivité maximale (voir @ref{4ad,,sys.getrecursionlimit()}) est dépassée.


Ajouté dans la version 3.5: Auparavant, une simple @ref{193,,RuntimeError} était levée.

@end deffn

@geindex ReferenceError
@anchor{library/exceptions ReferenceError}@anchor{14c5}
@deffn {Exception} ReferenceError

Cette exception est levée lorsqu'un pointeur faible d'un objet proxy, créé par la fonction @ref{a40,,weakref.proxy()}, est utilisé pour accéder à un attribut du référent après qu'il ait été récupéré par le ramasse-miettes. Pour plus d'informations sur les pointeurs faibles, voir le module @ref{113,,weakref}.
@end deffn

@geindex RuntimeError
@anchor{library/exceptions RuntimeError}@anchor{193}
@deffn {Exception} RuntimeError

Levée lorsqu'une erreur qui n'appartient à aucune des autres catégories est détectée. La valeur associée est une chaîne de caractères indiquant précisément ce qui s'est mal passé.
@end deffn

@geindex StopIteration
@anchor{library/exceptions StopIteration}@anchor{be8}
@deffn {Exception} StopIteration

Levée par la fonction native @ref{7c2,,next()} et la méthode @ref{12ab,,__next__()} d'un @ref{1aa,,iterator} (itérateur) pour signaler qu'il n'y a pas d'autres éléments produits par l'itérateur.

@geindex value (attribut StopIteration)
@anchor{library/exceptions StopIteration value}@anchor{1f4c}
@deffn {Attribut} value

The exception object has a single attribute @code{value}, which is
given as an argument when constructing the exception, and defaults
to @ref{660,,None}.
@end deffn

Lorsqu'une fonction de type @ref{104a,,generator} ou @ref{47b,,coroutine} retourne une valeur, une nouvelle instance de @ref{be8,,StopIteration} est levée, et la valeur retournée par la fonction est passée au paramètre @ref{1f4c,,value} du constructeur de l'exception.

Si le code d'un générateur lève, directement ou indirectement, une @ref{be8,,StopIteration}, elle est convertie en @ref{193,,RuntimeError} (en conservant @ref{be8,,StopIteration} comme cause de la nouvelle exception).


Modifié dans la version 3.3: Ajout de l'attribut @code{value} et de la possibilité pour les fonctions de générateur de l'utiliser pour retourner une valeur.



Modifié dans la version 3.5: Introduit la transformation des erreurs @code{RuntimeError} via @code{from __future__ import generator_stop}, cf. 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/}.



Modifié dans la version 3.7: Active 
@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} pour tout le code par défaut : quand une erreur @ref{be8,,StopIteration} est levée dans un générateur elle est transformée en une @ref{193,,RuntimeError}.

@end deffn

@geindex StopAsyncIteration
@anchor{library/exceptions StopAsyncIteration}@anchor{19bb}
@deffn {Exception} StopAsyncIteration

Must be raised by @ref{1e8f,,__anext__()} method of an
@ref{1a9,,asynchronous iterator} object to stop the iteration.


Ajouté dans la version 3.5.

@end deffn

@geindex SyntaxError
@anchor{library/exceptions SyntaxError}@anchor{18b}
@deffn {Exception} SyntaxError (message, details)

Levée lorsque l'analyseur syntaxique rencontre une erreur de syntaxe. Cela peut se produire dans une instruction @ref{5cc,,import}, dans un appel aux fonctions natives @ref{190,,compile()}, @ref{17d,,exec()} ou @ref{17e,,eval()}, ou lors de la lecture du script initial ou de l'entrée standard (également de manière interactive).

La conversion en chaîne avec @ref{435,,str()} de l'instance de l'exception ne renvoie que le message d'erreur. L'argument @code{details} est un `n'-uplet dont les membres sont disponibles en tant qu'attributs séparés.

@geindex filename (attribut SyntaxError)
@anchor{library/exceptions SyntaxError filename}@anchor{2219}
@deffn {Attribut} filename

Le nom du fichier dans lequel l'erreur de syntaxe a été rencontrée.
@end deffn

@geindex lineno (attribut SyntaxError)
@anchor{library/exceptions SyntaxError lineno}@anchor{221a}
@deffn {Attribut} lineno

Le numéro de la ligne dans le fichier où l'erreur s'est produite. L'indiçage commence à 1 : @code{lineno} vaut 1 pour la première ligne du fichier.
@end deffn

@geindex offset (attribut SyntaxError)
@anchor{library/exceptions SyntaxError offset}@anchor{221b}
@deffn {Attribut} offset

La colonne dans la ligne où l'erreur s'est produite. L'indiçage commence à 1 : @code{offset} vaut 1 pour le premier caractère de la ligne.
@end deffn

@geindex text (attribut SyntaxError)
@anchor{library/exceptions SyntaxError text}@anchor{221c}
@deffn {Attribut} text

Le texte du code source impliqué dans l'erreur.
@end deffn

@geindex end_lineno (attribut SyntaxError)
@anchor{library/exceptions SyntaxError end_lineno}@anchor{221d}
@deffn {Attribut} end_lineno

Le numéro de la dernière ligne produisant l'erreur. L'indiçage commence à 1 : @code{lineno} vaut 1 pour la première ligne du fichier.
@end deffn

@geindex end_offset (attribut SyntaxError)
@anchor{library/exceptions SyntaxError end_offset}@anchor{221e}
@deffn {Attribut} end_offset

Le numéro de la dernière colonne (de la dernière ligne) produisant l'erreur. L'indiçage commence à 1 : @code{offset} vaut 1 pour le premier caractère de la ligne.
@end deffn

Pour les erreurs dans les chaînes de formatage `f-strings', le message commence par « f-string: » et les champs `offset' sont les décalages dans un texte construit à partir de l’expression de remplacement. Par exemple, compiler @code{f'Bad @{a b@} field'} produit cet attribut `args' : @code{('f-string: ...', ('@w{'}, 1, 2, '(a b)\n', 1, 5)).}


Modifié dans la version 3.10: Ajout des attributs @ref{221d,,end_lineno} et @ref{221e,,end_offset}.

@end deffn

@geindex IndentationError
@anchor{library/exceptions IndentationError}@anchor{792}
@deffn {Exception} IndentationError

Classe mère pour les erreurs de syntaxe liées à une indentation incorrecte. C'est une sous-classe de @ref{18b,,SyntaxError}.
@end deffn

@geindex TabError
@anchor{library/exceptions TabError}@anchor{52e}
@deffn {Exception} TabError

Levée lorsqu'une indentation contient une utilisation incohérente des tabulations et des espaces. C'est une sous-classe de @ref{792,,IndentationError}.
@end deffn

@geindex SystemError
@anchor{library/exceptions SystemError}@anchor{561}
@deffn {Exception} SystemError

Levée lorsque l'interpréteur trouve une erreur interne, mais que la situation ne semble pas si grave au point de lui faire abandonner tout espoir. La valeur associée est une chaîne de caractères indiquant l'erreur qui est survenue (en termes bas niveau).

Vous devriez le signaler à l'auteur ou au responsable de votre interpréteur Python. Assurez-vous de signaler la version de l'interpréteur (@code{sys.version} ; elle est également affichée au lancement d'une session interactive), le message d'erreur exact (la valeur associée à l'exception) et si possible le code source du programme qui a déclenché l'erreur.
@end deffn

@geindex SystemExit
@anchor{library/exceptions SystemExit}@anchor{d2e}
@deffn {Exception} SystemExit

Cette exception est levée par la fonction @ref{1327,,sys.exit()}. Elle hérite de @ref{5a5,,BaseException} au lieu d'@ref{9c7,,Exception} pour ne pas qu'elle soit interceptée accidentellement par du code qui intercepte @ref{9c7,,Exception}. Cela permet à l'exception de se propager correctement et de faire quitter l'interpréteur. Lorsqu'elle n'est pas gérée, l'interpréteur Python quitte ; aucune trace d'appels n'est affichée. Le constructeur accepte le même argument optionnel passé à @ref{1327,,sys.exit()}. Si la valeur est un entier, elle spécifie l'état de sortie du système (passé à la fonction C @code{exit()}) ; si elle est @code{None}, l'état de sortie est zéro ; si elle a un autre type (comme une chaîne de caractères), la valeur de l'objet est affichée et l'état de sortie est un.

Un appel à @ref{1327,,sys.exit()} est traduit en une exception pour que les gestionnaires de nettoyage (les clauses @ref{9b8,,finally} des instructions @ref{6d3,,try}) puissent être exécutés, et pour qu'un débogueur puisse exécuter un script sans courir le risque de perdre le contrôle. La fonction @ref{221f,,os._exit()} peut être utilisée s'il est absolument nécessaire de sortir immédiatement (par exemple, dans le processus enfant après un appel à @ref{195,,os.fork()}).

@geindex code (attribut SystemExit)
@anchor{library/exceptions SystemExit code}@anchor{2220}
@deffn {Attribut} code

L'état de sortie ou le message d'erreur passé au constructeur. (@code{None} par défaut.)
@end deffn
@end deffn

@geindex TypeError
@anchor{library/exceptions TypeError}@anchor{522}
@deffn {Exception} TypeError

Levée lorsqu'une opération ou fonction est appliquée à un objet d'un type inapproprié. La valeur associée est une chaîne de caractères donnant des détails sur le type d'inadéquation.

Cette exception peut être levée par du code utilisateur pour indiquer qu'une tentative d'opération sur un objet n'est pas prise en charge, et n'est pas censée l'être. Si un objet est destiné à prendre en charge une opération donnée mais n'a pas encore fourni une implémentation, lever @ref{225,,NotImplementedError} est plus approprié.

Le passage d'arguments du mauvais type (e.g. passer une @ref{5fc,,list} quand un @ref{254,,int} est attendu) devrait résulter en un @ref{522,,TypeError}, mais le passage d'arguments avec la mauvaise valeur (e.g. un nombre en dehors des limites attendues) devrait résulter en une @ref{1ff,,ValueError}.
@end deffn

@geindex UnboundLocalError
@anchor{library/exceptions UnboundLocalError}@anchor{14ec}
@deffn {Exception} UnboundLocalError

Levée lorsqu'une référence est faite à une variable locale dans une fonction ou une méthode, mais qu'aucune valeur n'a été liée à cette variable. C'est une sous-classe de @ref{428,,NameError}.
@end deffn

@geindex UnicodeError
@anchor{library/exceptions UnicodeError}@anchor{1281}
@deffn {Exception} UnicodeError

Levée lorsqu'une erreur d'encodage ou de décodage liée à Unicode se produit. C'est une sous-classe de @ref{1ff,,ValueError}.

@ref{1281,,UnicodeError} a des attributs qui décrivent l'erreur d'encodage ou de décodage. Par exemple, @code{err.object[err.start:err.end]} donne l'entrée particulière invalide sur laquelle le codec a échoué.

@geindex encoding (attribut UnicodeError)
@anchor{library/exceptions UnicodeError encoding}@anchor{2221}
@deffn {Attribut} encoding

Le nom de l'encodage qui a provoqué l'erreur.
@end deffn

@geindex reason (attribut UnicodeError)
@anchor{library/exceptions UnicodeError reason}@anchor{2222}
@deffn {Attribut} reason

Une chaîne de caractères décrivant l'erreur de codec spécifique.
@end deffn

@geindex object (attribut UnicodeError)
@anchor{library/exceptions UnicodeError object}@anchor{2223}
@deffn {Attribut} object

L'objet que le codec essayait d'encoder ou de décoder.
@end deffn

@geindex start (attribut UnicodeError)
@anchor{library/exceptions UnicodeError start}@anchor{1541}
@deffn {Attribut} start

Le premier index des données invalides dans @ref{a7a,,object}.
@end deffn

@geindex end (attribut UnicodeError)
@anchor{library/exceptions UnicodeError end}@anchor{1542}
@deffn {Attribut} end

L'index après la dernière donnée invalide dans @ref{a7a,,object}.
@end deffn
@end deffn

@geindex UnicodeEncodeError
@anchor{library/exceptions UnicodeEncodeError}@anchor{662}
@deffn {Exception} UnicodeEncodeError

Levée lorsqu'une erreur liée à Unicode se produit durant l'encodage. C'est une sous-classe d'@ref{1281,,UnicodeError}.
@end deffn

@geindex UnicodeDecodeError
@anchor{library/exceptions UnicodeDecodeError}@anchor{a01}
@deffn {Exception} UnicodeDecodeError

Levée lorsqu'une erreur liée à Unicode se produit durant le décodage. C'est une sous-classe d'@ref{1281,,UnicodeError}.
@end deffn

@geindex UnicodeTranslateError
@anchor{library/exceptions UnicodeTranslateError}@anchor{2224}
@deffn {Exception} UnicodeTranslateError

Levée lorsqu'une erreur liée à Unicode se produit durant la traduction. C'est une sous-classe d'@ref{1281,,UnicodeError}.
@end deffn

@geindex ValueError
@anchor{library/exceptions ValueError}@anchor{1ff}
@deffn {Exception} ValueError

Levée lorsqu'une opération ou fonction native reçoit un argument qui possède le bon type mais une valeur inappropriée, et que la situation n'est pas décrite par une exception plus précise telle que @ref{14eb,,IndexError}.
@end deffn

@geindex ZeroDivisionError
@anchor{library/exceptions ZeroDivisionError}@anchor{932}
@deffn {Exception} ZeroDivisionError

Levée lorsque le second argument d'une opération de division ou d'un modulo est zéro. La valeur associée est une chaîne indiquant le type des opérandes et de l'opération.
@end deffn

Les exceptions suivantes sont conservées pour la compatibilité avec les anciennes versions ; depuis Python 3.3, ce sont des alias d'@ref{40d,,OSError}.

@geindex EnvironmentError
@anchor{library/exceptions EnvironmentError}@anchor{103c}
@deffn {Exception} EnvironmentError
@end deffn

@geindex IOError
@anchor{library/exceptions IOError}@anchor{103b}
@deffn {Exception} IOError
@end deffn

@geindex WindowsError
@anchor{library/exceptions WindowsError}@anchor{103d}
@deffn {Exception} WindowsError

Seulement disponible sous Windows.
@end deffn

@menu
* Exceptions système:: 

@end menu

@node Exceptions système,,,Exceptions concrètes
@anchor{library/exceptions os-exceptions}@anchor{2213}
@subsubsection Exceptions système


Les exceptions suivantes sont des sous-classes d'@ref{40d,,OSError}, elles sont levées en fonction du code d'erreur système.

@geindex BlockingIOError
@anchor{library/exceptions BlockingIOError}@anchor{1040}
@deffn {Exception} BlockingIOError

Raised when an operation would block on an object (e.g. socket) set
for non-blocking operation.
Corresponds to @code{errno} @ref{2225,,EAGAIN}, @ref{2226,,EALREADY},
@ref{2227,,EWOULDBLOCK} and @ref{2228,,EINPROGRESS}.

En plus de ceux de @ref{40d,,OSError}, @ref{1040,,BlockingIOError} peut avoir un attribut de plus :

@geindex characters_written (attribut BlockingIOError)
@anchor{library/exceptions BlockingIOError characters_written}@anchor{2229}
@deffn {Attribut} characters_written

Un nombre entier contenant le nombre de caractères écrits dans le flux avant qu'il ne soit bloqué. Cet attribut est disponible lors de l'utilisation des classes tampon entrées-sorties du module @ref{7e,,io}.
@end deffn
@end deffn

@geindex ChildProcessError
@anchor{library/exceptions ChildProcessError}@anchor{1041}
@deffn {Exception} ChildProcessError

Raised when an operation on a child process failed.
Corresponds to @code{errno} @ref{222a,,ECHILD}.
@end deffn

@geindex ConnectionError
@anchor{library/exceptions ConnectionError}@anchor{df7}
@deffn {Exception} ConnectionError

Classe mère pour les problèmes de connexion.

Les sous-classes sont @ref{1045,,BrokenPipeError}, @ref{1046,,ConnectionAbortedError}, @ref{1047,,ConnectionRefusedError} et @ref{1048,,ConnectionResetError}.
@end deffn

@geindex BrokenPipeError
@anchor{library/exceptions BrokenPipeError}@anchor{1045}
@deffn {Exception} BrokenPipeError

A subclass of @ref{df7,,ConnectionError}, raised when trying to write on a
pipe while the other end has been closed, or trying to write on a socket
which has been shutdown for writing.
Corresponds to @code{errno} @ref{222b,,EPIPE} and @ref{222c,,ESHUTDOWN}.
@end deffn

@geindex ConnectionAbortedError
@anchor{library/exceptions ConnectionAbortedError}@anchor{1046}
@deffn {Exception} ConnectionAbortedError

A subclass of @ref{df7,,ConnectionError}, raised when a connection attempt
is aborted by the peer.
Corresponds to @code{errno} @ref{222d,,ECONNABORTED}.
@end deffn

@geindex ConnectionRefusedError
@anchor{library/exceptions ConnectionRefusedError}@anchor{1047}
@deffn {Exception} ConnectionRefusedError

A subclass of @ref{df7,,ConnectionError}, raised when a connection attempt
is refused by the peer.
Corresponds to @code{errno} @ref{222e,,ECONNREFUSED}.
@end deffn

@geindex ConnectionResetError
@anchor{library/exceptions ConnectionResetError}@anchor{1048}
@deffn {Exception} ConnectionResetError

A subclass of @ref{df7,,ConnectionError}, raised when a connection is
reset by the peer.
Corresponds to @code{errno} @ref{222f,,ECONNRESET}.
@end deffn

@geindex FileExistsError
@anchor{library/exceptions FileExistsError}@anchor{1009}
@deffn {Exception} FileExistsError

Raised when trying to create a file or directory which already exists.
Corresponds to @code{errno} @ref{2230,,EEXIST}.
@end deffn

@geindex FileNotFoundError
@anchor{library/exceptions FileNotFoundError}@anchor{eae}
@deffn {Exception} FileNotFoundError

Raised when a file or directory is requested but doesn't exist.
Corresponds to @code{errno} @ref{2231,,ENOENT}.
@end deffn

@geindex InterruptedError
@anchor{library/exceptions InterruptedError}@anchor{d75}
@deffn {Exception} InterruptedError

Raised when a system call is interrupted by an incoming signal.
Corresponds to @code{errno} @ref{d74,,EINTR}.


Modifié dans la version 3.5: Python relance maintenant les appels système lorsqu'ils sont interrompus par un signal, sauf si le gestionnaire de signal lève une exception (voir 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} pour les raisons), au lieu de lever @ref{d75,,InterruptedError}.

@end deffn

@geindex IsADirectoryError
@anchor{library/exceptions IsADirectoryError}@anchor{1042}
@deffn {Exception} IsADirectoryError

Raised when a file operation (such as @ref{10d1,,os.remove()}) is requested
on a directory.
Corresponds to @code{errno} @ref{2232,,EISDIR}.
@end deffn

@geindex NotADirectoryError
@anchor{library/exceptions NotADirectoryError}@anchor{1043}
@deffn {Exception} NotADirectoryError

Raised when a directory operation (such as @ref{10da,,os.listdir()}) is requested on
something which is not a directory.  On most POSIX platforms, it may also be
raised if an operation attempts to open or traverse a non-directory file as if
it were a directory.
Corresponds to @code{errno} @ref{2233,,ENOTDIR}.
@end deffn

@geindex PermissionError
@anchor{library/exceptions PermissionError}@anchor{d30}
@deffn {Exception} PermissionError

Raised when trying to run an operation without the adequate access
rights - for example filesystem permissions.
Corresponds to @code{errno} @ref{2234,,EACCES},
@ref{175a,,EPERM}, and @ref{174d,,ENOTCAPABLE}.


Modifié dans la version 3.11.1: WASI's @ref{174d,,ENOTCAPABLE} is now mapped to
@ref{d30,,PermissionError}.

@end deffn

@geindex ProcessLookupError
@anchor{library/exceptions ProcessLookupError}@anchor{1044}
@deffn {Exception} ProcessLookupError

Raised when a given process doesn't exist.
Corresponds to @code{errno} @ref{2235,,ESRCH}.
@end deffn

@geindex TimeoutError
@anchor{library/exceptions TimeoutError}@anchor{81f}
@deffn {Exception} TimeoutError

Raised when a system function timed out at the system level.
Corresponds to @code{errno} @ref{2236,,ETIMEDOUT}.
@end deffn


Ajouté dans la version 3.3: Toutes les sous-classes d'@ref{40d,,OSError} ci-dessus ont été ajoutées.



@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/} -- Refonte de la hiérarchie des exceptions système et IO


@node Avertissements,Exception groups,Exceptions concrètes,Exceptions natives
@anchor{library/exceptions warning-categories-as-exceptions}@anchor{2237}@anchor{library/exceptions warnings}@anchor{2238}
@subsection Avertissements


Les exceptions suivantes sont utilisées comme catégories d'avertissement ; voir @code{warning-categories} pour plus d'informations.

@geindex Warning
@anchor{library/exceptions Warning}@anchor{2239}
@deffn {Exception} Warning

Classe mère pour les catégories d'avertissement.
@end deffn

@geindex UserWarning
@anchor{library/exceptions UserWarning}@anchor{223a}
@deffn {Exception} UserWarning

Classe mère pour les avertissements générés par du code utilisateur.
@end deffn

@geindex DeprecationWarning
@anchor{library/exceptions DeprecationWarning}@anchor{1a3}
@deffn {Exception} DeprecationWarning

Classe mère pour les avertissements sur les fonctionnalités obsolètes, lorsque ces avertissements sont destinés aux autres développeurs Python.

Ignoré par les filtres d'avertissements par défaut, sauf dans le module @code{__main__} (
@geindex Python Enhancement Proposals; PEP 565
PEP 565@footnote{https://peps.python.org/pep-0565/}). Activer le @ref{1f5,,mode de développement de Python} affiche cet avertissement.

La politique relative à l'obsolescence est décrite dans la 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/}.
@end deffn

@geindex PendingDeprecationWarning
@anchor{library/exceptions PendingDeprecationWarning}@anchor{8b5}
@deffn {Exception} PendingDeprecationWarning

Classe mère pour les avertissements d'obsolescence programmée. Ils indiquent que la fonctionnalité peut encore être utilisée actuellement, mais qu'elle sera supprimée dans le futur.

Cette classe est rarement utilisée car émettre un avertissement à propos d’une obsolescence à venir est inhabituel, et @ref{1a3,,DeprecationWarning} est préféré pour les obsolescences actuelles.

Ignoré par les filtres d'avertissements par défaut. Activer le @ref{1f5,,mode de développement de Python} affiche cet avertissement.

La politique relative à l'obsolescence est décrite dans la 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/}.
@end deffn

@geindex SyntaxWarning
@anchor{library/exceptions SyntaxWarning}@anchor{44f}
@deffn {Exception} SyntaxWarning

Classe mère pour les avertissements sur de la syntaxe douteuse.
@end deffn

@geindex RuntimeWarning
@anchor{library/exceptions RuntimeWarning}@anchor{1bb}
@deffn {Exception} RuntimeWarning

Classe mère pour les avertissements sur les comportements d'exécution douteux.
@end deffn

@geindex FutureWarning
@anchor{library/exceptions FutureWarning}@anchor{40b}
@deffn {Exception} FutureWarning

Classe mère pour les avertissements à propos de fonctionnalités qui seront obsolètes dans le futur quand ces avertissements destinés aux utilisateurs finaux des applications écrites en Python.
@end deffn

@geindex ImportWarning
@anchor{library/exceptions ImportWarning}@anchor{4e4}
@deffn {Exception} ImportWarning

Classe mère pour les avertissements sur des erreurs probables dans les importations de modules.

Ignoré par les filtres d'avertissements par défaut. Activer le @ref{1f5,,mode de développement de Python} affiche cet avertissement.
@end deffn

@geindex UnicodeWarning
@anchor{library/exceptions UnicodeWarning}@anchor{13da}
@deffn {Exception} UnicodeWarning

Classe mère pour les avertissements liés à l'Unicode.
@end deffn

@geindex EncodingWarning
@anchor{library/exceptions EncodingWarning}@anchor{1cc9}
@deffn {Exception} EncodingWarning

Classe mère pour les avertissements liés à l'encodage des chaînes.

Voir @ref{1ce1,,Opt-in EncodingWarning} pour plus d'informations.


Ajouté dans la version 3.10.

@end deffn

@geindex BytesWarning
@anchor{library/exceptions BytesWarning}@anchor{c11}
@deffn {Exception} BytesWarning

Classe mère pour les avertissements liés à @ref{1bd,,bytes} et @ref{528,,bytearray}.
@end deffn

@geindex ResourceWarning
@anchor{library/exceptions ResourceWarning}@anchor{241}
@deffn {Exception} ResourceWarning

Classe mère pour les avertissements liés à l'utilisation des ressources.

Ignoré par les filtres d'avertissements par défaut. Activer le @ref{1f5,,mode de développement de Python} affiche cet avertissement.


Ajouté dans la version 3.2.

@end deffn

@node Exception groups,Hiérarchie des exceptions,Avertissements,Exceptions natives
@anchor{library/exceptions exception-groups}@anchor{223b}@anchor{library/exceptions lib-exception-groups}@anchor{223c}
@subsection Exception groups


The following are used when it is necessary to raise multiple unrelated
exceptions. They are part of the exception hierarchy so they can be
handled with @ref{189,,except} like all other exceptions. In addition,
they are recognised by @ref{5a2,,except*}, which matches
their subgroups based on the types of the contained exceptions.

@geindex ExceptionGroup
@anchor{library/exceptions ExceptionGroup}@anchor{1b4}
@deffn {Exception} ExceptionGroup (msg, excs)
@end deffn

@geindex BaseExceptionGroup
@anchor{library/exceptions BaseExceptionGroup}@anchor{25c}
@deffn {Exception} BaseExceptionGroup (msg, excs)

Both of these exception types wrap the exceptions in the sequence @code{excs}.
The @code{msg} parameter must be a string. The difference between the two
classes is that @ref{25c,,BaseExceptionGroup} extends @ref{5a5,,BaseException} and
it can wrap any exception, while @ref{1b4,,ExceptionGroup} extends @ref{9c7,,Exception}
and it can only wrap subclasses of @ref{9c7,,Exception}. This design is so that
@code{except Exception} catches an @ref{1b4,,ExceptionGroup} but not
@ref{25c,,BaseExceptionGroup}.

The @ref{25c,,BaseExceptionGroup} constructor returns an @ref{1b4,,ExceptionGroup}
rather than a @ref{25c,,BaseExceptionGroup} if all contained exceptions are
@ref{9c7,,Exception} instances, so it can be used to make the selection
automatic. The @ref{1b4,,ExceptionGroup} constructor, on the other hand,
raises a @ref{522,,TypeError} if any contained exception is not an
@ref{9c7,,Exception} subclass.

@geindex message (attribut BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup message}@anchor{223d}
@deffn {Attribut} message

The @code{msg} argument to the constructor. This is a read-only attribute.
@end deffn

@geindex exceptions (attribut BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup exceptions}@anchor{223e}
@deffn {Attribut} exceptions

A tuple of the exceptions in the @code{excs} sequence given to the
constructor. This is a read-only attribute.
@end deffn

@geindex subgroup() (méthode BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup subgroup}@anchor{164a}
@deffn {Méthode} subgroup (condition)

Returns an exception group that contains only the exceptions from the
current group that match `condition', or @code{None} if the result is empty.

The condition can be an exception type or tuple of exception types, in which
case each exception is checked for a match using the same check that is used
in an @code{except} clause.  The condition can also be a callable (other than
a type object) that accepts an exception as its single argument and returns
true for the exceptions that should be in the subgroup.

The nesting structure of the current exception is preserved in the result,
as are the values of its @ref{223d,,message},
@ref{12a4,,__traceback__}, @ref{12a6,,__cause__},
@ref{12a5,,__context__} and
@ref{220c,,__notes__} fields.
Empty nested groups are omitted from the result.

The condition is checked for all exceptions in the nested exception group,
including the top-level and any nested exception groups. If the condition is
true for such an exception group, it is included in the result in full.


Ajouté dans la version 3.13: @code{condition} can be any callable which is not a type object.

@end deffn

@geindex split() (méthode BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup split}@anchor{150f}
@deffn {Méthode} split (condition)

Like @ref{164a,,subgroup()}, but returns the pair @code{(match, rest)} where @code{match}
is @code{subgroup(condition)} and @code{rest} is the remaining non-matching
part.
@end deffn

@geindex derive() (méthode BaseExceptionGroup)
@anchor{library/exceptions BaseExceptionGroup derive}@anchor{1649}
@deffn {Méthode} derive (excs)

Returns an exception group with the same @ref{223d,,message}, but which
wraps the exceptions in @code{excs}.

This method is used by @ref{164a,,subgroup()} and @ref{150f,,split()}, which
are used in various contexts to break up an exception group. A
subclass needs to override it in order to make @ref{164a,,subgroup()}
and @ref{150f,,split()} return instances of the subclass rather
than @ref{1b4,,ExceptionGroup}.

@ref{164a,,subgroup()} and @ref{150f,,split()} copy the
@ref{12a4,,__traceback__},
@ref{12a6,,__cause__}, @ref{12a5,,__context__} and
@ref{220c,,__notes__} fields from
the original exception group to the one returned by @ref{1649,,derive()}, so
these fields do not need to be updated by @ref{1649,,derive()}.

@example
>>> class MyGroup(ExceptionGroup):
...     def derive(self, excs):
...         return MyGroup(self.message, excs)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("a note")
>>> e.__context__ = Exception("context")
>>> e.__cause__ = Exception("cause")
>>> try:
...    raise e
... except Exception as e:
...    exc = e
...
>>> match, rest = exc.split(ValueError)
>>> exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
>>> rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
True
@end example
@end deffn

Note that @ref{25c,,BaseExceptionGroup} defines @ref{56c,,__new__()}, so
subclasses that need a different constructor signature need to
override that rather than @ref{69b,,__init__()}. For example, the following
defines an exception group subclass which accepts an exit_code and
and constructs the group's message from it.

@example
class Errors(ExceptionGroup):
   def __new__(cls, errors, exit_code):
      self = super().__new__(Errors, f"exit code: @{exit_code@}", errors)
      self.exit_code = exit_code
      return self

   def derive(self, excs):
      return Errors(excs, self.exit_code)
@end example

Like @ref{1b4,,ExceptionGroup}, any subclass of @ref{25c,,BaseExceptionGroup} which
is also a subclass of @ref{9c7,,Exception} can only wrap instances of
@ref{9c7,,Exception}.


Ajouté dans la version 3.11.

@end deffn

@node Hiérarchie des exceptions,,Exception groups,Exceptions natives
@anchor{library/exceptions exception-hierarchy}@anchor{223f}
@subsection Hiérarchie des exceptions


La hiérarchie de classes pour les exceptions natives est la suivante :

@example
BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    ├── PythonFinalizationError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning
@end example
@anchor{library/text stringservices}@anchor{2140}
@node Services de Manipulation de Texte,Services autour des Données Binaires,Exceptions natives,La bibliothèque standard
@anchor{library/text doc}@anchor{2240}@anchor{library/text text-processing-services}@anchor{2241}@anchor{library/text textservices}@anchor{2143}
@section Services de Manipulation de Texte


Les modules décrits dans ce chapitre fournissent un large ensemble d'opérations de manipulation sur les chaînes de caractères et le texte en général.

Le module @ref{1b,,codecs} documenté dans @ref{2242,,Services autour des Données Binaires} est aussi très pertinent pour la manipulation de texte. Consultez aussi la documentation du type `str' natif Python dans @ref{1b8a,,Type Séquence de Texte — str}.

@menu
* string: string --- Common string operations. Common string operations
* re: re --- Regular expression operations. Regular expression operations
* difflib: difflib --- Helpers for computing deltas. Helpers for computing deltas
* textwrap: textwrap --- Text wrapping and filling. Text wrapping and filling
* unicodedata: unicodedata --- Unicode Database. Unicode Database
* stringprep: stringprep --- Internet String Preparation. Internet String Preparation
* readline: readline --- GNU readline interface. GNU readline interface
* rlcompleter: rlcompleter --- Completion function for GNU readline. Completion function for GNU readline

@end menu

@node string --- Common string operations,re --- Regular expression operations,,Services de Manipulation de Texte
@anchor{library/string doc}@anchor{2243}@anchor{library/string module-string}@anchor{d2}@anchor{library/string string-common-string-operations}@anchor{2244}
@subsection @code{string} --- Common string operations


@geindex module; string

`Code source :' Lib/string.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/string.py}


__________________________________________________________________



@subsubheading Voir aussi


@ref{1b8a,,Type Séquence de Texte — str}

@ref{1b8b,,Méthodes de chaînes de caractères}


@menu
* Chaînes constantes:: 
* Formatage personnalisé de chaîne:: 
* Syntaxe de formatage de chaîne:: 
* Chaînes modèles:: 
* Fonctions d'assistance:: 

@end menu

@node Chaînes constantes,Formatage personnalisé de chaîne,,string --- Common string operations
@anchor{library/string string-constants}@anchor{2245}
@subsubsection Chaînes constantes


Les constantes définies dans ce module sont :

@geindex ascii_letters (dans le module string)
@anchor{library/string string ascii_letters}@anchor{12a1}
@deffn {Données} string.ascii_letters

La concaténation des constantes @ref{2246,,ascii_lowercase} et @ref{2247,,ascii_uppercase} décrites ci-dessous. Cette valeur n'est pas dépendante de la configuration de la localisation.
@end deffn

@geindex ascii_lowercase (dans le module string)
@anchor{library/string string ascii_lowercase}@anchor{2246}
@deffn {Données} string.ascii_lowercase

Les lettres minuscules @code{'abcdefghijklmnopqrstuvwxyz'}. Cette valeur ne dépend pas de la configuration de localisation et ne changera pas.
@end deffn

@geindex ascii_uppercase (dans le module string)
@anchor{library/string string ascii_uppercase}@anchor{2247}
@deffn {Données} string.ascii_uppercase

Les lettres majuscules @code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Cette valeur ne dépend pas de la configuration de la localisation et ne changera pas.
@end deffn

@geindex digits (dans le module string)
@anchor{library/string string digits}@anchor{2248}
@deffn {Données} string.digits

La chaîne @code{'0123456789'}.
@end deffn

@geindex hexdigits (dans le module string)
@anchor{library/string string hexdigits}@anchor{2249}
@deffn {Données} string.hexdigits

La chaîne @code{'0123456789abcdefABCDEF'}.
@end deffn

@geindex octdigits (dans le module string)
@anchor{library/string string octdigits}@anchor{224a}
@deffn {Données} string.octdigits

La chaîne @code{'01234567}.
@end deffn

@geindex punctuation (dans le module string)
@anchor{library/string string punctuation}@anchor{224b}
@deffn {Données} string.punctuation

Chaîne de caractères ASCII considérés comme ponctuation dans la configuration de localisation @code{C} : @code{!"#$%&'()*+,-./:;<=>?@@[\]^_`@{|@}~}.
@end deffn

@geindex printable (dans le module string)
@anchor{library/string string printable}@anchor{224c}
@deffn {Données} string.printable

Chaîne de caractères ASCII considérés comme affichables. C'est une combinaison de @ref{2248,,digits}, @ref{12a1,,ascii_letters}, @ref{224b,,punctuation}, et @ref{224d,,whitespace}.
@end deffn

@geindex whitespace (dans le module string)
@anchor{library/string string whitespace}@anchor{224d}
@deffn {Données} string.whitespace

Une chaîne comprenant tous les caractères ASCII considérés comme espaces. Sont inclus les caractères espace, tabulations, saut de ligne, retour du chariot, saut de page, et tabulation verticale.
@end deffn

@node Formatage personnalisé de chaîne,Syntaxe de formatage de chaîne,Chaînes constantes,string --- Common string operations
@anchor{library/string custom-string-formatting}@anchor{224e}@anchor{library/string string-formatting}@anchor{2142}
@subsubsection Formatage personnalisé de chaîne


La classe primitive @code{str} fournit la possibilité de faire des substitutions de variables complexes et du formatage de valeurs via la méthode @ref{60c,,format()} décrite par 
@geindex Python Enhancement Proposals; PEP 3101
PEP 3101@footnote{https://peps.python.org/pep-3101/}. La classe @ref{ea5,,Formatter} dans le module @ref{d2,,string} permet de créer et personnaliser vos propres comportements de formatage de chaînes en utilisant la même implémentation que la méthode primitive @ref{60c,,format()}.

@geindex Formatter (classe dans string)
@anchor{library/string string Formatter}@anchor{ea5}
@deffn {Classe} string.Formatter

La classe @ref{ea5,,Formatter} a les méthodes publiques suivantes :

@geindex format() (méthode string.Formatter)
@anchor{library/string string Formatter format}@anchor{bee}
@deffn {Méthode} format (format_string, /, *args, **kwargs)

La méthode principale de l'API. Elle prend une chaîne de format et un ensemble arbitraire d'arguments positions et mot-clefs. C'est uniquement un conteneur qui appelle @ref{224f,,vformat()}.


Modifié dans la version 3.7: L'argument `format_string' est maintenant @ref{a73,,obligatoirement un paramètre positionnel}.

@end deffn

@geindex vformat() (méthode string.Formatter)
@anchor{library/string string Formatter vformat}@anchor{224f}
@deffn {Méthode} vformat (format_string, args, kwargs)

Cette fonction fait le travail effectif du formatage. Elle existe comme méthode séparée au cas où vous voudriez passer un dictionnaire d'arguments prédéfini plutôt que décompresser et recompresser le dictionnaire en arguments individuels en utilisant la syntaxe @code{*args} et @code{**kwargs}. @ref{224f,,vformat()} s'occupe de découper la chaîne de format en données de caractères et champs de remplacement. Elle appelle les différentes méthodes décrites ci-dessous.
@end deffn

De plus, la classe @ref{ea5,,Formatter} définit un certain nombre de méthodes qui ont pour vocation d'être remplacées par des sous-classes :

@geindex parse() (méthode string.Formatter)
@anchor{library/string string Formatter parse}@anchor{2250}
@deffn {Méthode} parse (format_string)

Boucle sur la chaîne de format et renvoie un itérable de quadruplets (`literal_text', `field_name', `format_spec', `conversion'). Ceci est utilisé par @ref{224f,,vformat()} pour découper la chaîne de format en littéraux ou en champs de remplacement.

Les valeurs dans le `n'-uplet représentent conceptuellement un ensemble de littéraux suivis d'un unique champ de remplacement. S'il n'y a pas de littéral, (ce qui peut arriver si deux champs de remplacement sont placés côte à côte), alors `literal_text' est une chaîne vide. S'il n'y a pas de champ de remplacement, les valeurs `field_name', `format_spec' et `conversion' sont mises à @code{None}.
@end deffn

@geindex get_field() (méthode string.Formatter)
@anchor{library/string string Formatter get_field}@anchor{2251}
@deffn {Méthode} get_field (field_name, args, kwargs)

Récupère le champ `field_name' du `n'-uplet renvoyé par @ref{2250,,parse()} (voir ci-dessus), le convertit en un objet à formater. Renvoie une paire (`obj', `used_key'). La version par défaut prend une chaîne de la forme définie par 
@geindex Python Enhancement Proposals; PEP 3101
PEP 3101@footnote{https://peps.python.org/pep-3101/}, telle que @code{"0[name]"} ou @code{"label.title"}. `args' et `kwargs' sont tels que ceux passés à @ref{224f,,vformat()}. La valeur renvoyée `used_key' a le même sens que le paramètre `key' de @ref{2252,,get_value()}.
@end deffn

@geindex get_value() (méthode string.Formatter)
@anchor{library/string string Formatter get_value}@anchor{2252}
@deffn {Méthode} get_value (key, args, kwargs)

Récupère la valeur d'un champ donné. L'argument `key' est soit un entier, soit une chaîne. Si c'est un entier, il représente l'indice de l'argument dans `args'. Si c'est une chaîne de caractères, elle représente le nom de l'argument dans `kwargs'.

Le paramètre `args' est défini par la liste des arguments positionnels de @ref{224f,,vformat()}, et le paramètre `kwargs' est défini par le dictionnaire des arguments mot-clefs.

Pour les noms de champs composés, ces fonctions sont uniquement appelées sur la première composante du nom. Les composantes suivantes sont manipulées au travers des attributs normaux et des opérations sur les indices.

Donc par exemple, le champ-expression @code{0.name} amènerait @ref{2252,,get_value()} à être appelée avec un argument `key' valant 0. L'attribut @code{name} sera recherché après l'appel @ref{2252,,get_value()} en faisant appel à la primitive @ref{bbf,,getattr()}.

Si l'indice ou le mot-clef fait référence à un objet qui n'existe pas, alors une exception @ref{14eb,,IndexError} ou @ref{33a,,KeyError} doit être levée.
@end deffn

@geindex check_unused_args() (méthode string.Formatter)
@anchor{library/string string Formatter check_unused_args}@anchor{2253}
@deffn {Méthode} check_unused_args (used_args, args, kwargs)

Implémente une vérification pour les arguments non utilisés si désiré. L'argument de cette fonction est l'ensemble des clefs qui ont été effectivement référencées dans la chaîne de format (des entiers pour les indices et des chaînes de caractères pour les arguments nommés), et une référence vers les arguments `args' et `kwargs' qui ont été passés à @code{vformat}. L'ensemble des arguments non utilisés peut être calculé sur base de ces paramètres. @ref{2253,,check_unused_args()} est censée lever une exception si la vérification échoue.
@end deffn

@geindex format_field() (méthode string.Formatter)
@anchor{library/string string Formatter format_field}@anchor{2254}
@deffn {Méthode} format_field (value, format_spec)

La méthode @ref{2254,,format_field()} fait simplement appel à la primitive globale @ref{60a,,format()}. Cette méthode est fournie afin que les sous-classes puissent la redéfinir.
@end deffn

@geindex convert_field() (méthode string.Formatter)
@anchor{library/string string Formatter convert_field}@anchor{2255}
@deffn {Méthode} convert_field (value, conversion)

Convertit la valeur (renvoyée par @ref{2251,,get_field()}) selon un type de conversion donné (comme dans le `n'-uplet renvoyé par la méthode @ref{2250,,parse()}). La version par défaut comprend 's' (@code{str}), 'r' (@code{repr}) et 'a' (ASCII) comme types de conversion.
@end deffn
@end deffn

@node Syntaxe de formatage de chaîne,Chaînes modèles,Formatage personnalisé de chaîne,string --- Common string operations
@anchor{library/string format-string-syntax}@anchor{2256}@anchor{library/string formatstrings}@anchor{1367}
@subsubsection Syntaxe de formatage de chaîne


La méthode @ref{60c,,str.format()} et la classe @ref{ea5,,Formatter} partagent la même syntaxe pour les chaînes de formatage (bien que dans le cas de @ref{ea5,,Formatter} les sous-classes puissent définir leur propre syntaxe).  La syntaxe est liée à celle des @ref{997,,chaînes de formatage littérales}, mais elle est moins sophistiquée, et surtout ne permet pas d'inclure des expressions arbitraires.

@geindex @{@} (curly brackets);in string formatting
@geindex . (dot);in string formatting
@geindex [] (square brackets);in string formatting
@geindex ! (exclamation);in string formatting
@geindex ; (colon);in string formatting

Les chaînes de formatage contiennent des "champs de remplacement" entourés d'accolades @code{@{@}}. Tout ce qui n'est pas placé entre deux accolades est considéré comme littéral, qui est copié tel quel dans le résultat. Si vous avez besoin d'inclure une accolade en littéral, elles peuvent être échappées en les doublant : @code{@{@{} et @code{@}@}}.

La grammaire pour un champ de remplacement est définie comme suit :

@example
@anchor{library/string grammar-token-format-string-replacement_field}@anchor{2257}replacement_field ::= "@{" [field_name] ["!" conversion] [":" format_spec] "@}"
@anchor{library/string grammar-token-format-string-field_name}@anchor{2258}field_name        ::= arg_name ("." attribute_name | "[" element_index "]")*
@anchor{library/string grammar-token-format-string-arg_name}@anchor{2259}arg_name          ::= [identifier | digit+]
@anchor{library/string grammar-token-format-string-attribute_name}@anchor{225a}attribute_name    ::= identifier
@anchor{library/string grammar-token-format-string-element_index}@anchor{225b}element_index     ::= digit+ | index_string
@anchor{library/string grammar-token-format-string-index_string}@anchor{225c}index_string      ::= <any source character except "]"> +
@anchor{library/string grammar-token-format-string-conversion}@anchor{225d}conversion        ::= "r" | "s" | "a"
@anchor{library/string grammar-token-format-string-format_spec}@anchor{225e}format_spec       ::= format-spec:format_spec
@end example

En termes moins formels, un champ de remplacement peut débuter par un `field_name' qui spécifie l'objet dont la valeur va être formatée et insérée dans le résultat à l'endroit du champ de remplacement Le `field_name' peut éventuellement être suivi d'un champ `conversion' qui est précédé d'un point d'exclamation @code{'!'}, et d'un `format_spec' qui est précédé par deux-points @code{':'}. Cela définit un format personnalisé pour le remplacement d'une valeur.

Voir également la section @ref{1e5,,Mini-langage de spécification de format}.

The `field_name' itself begins with an `arg_name' that is either a number or a
keyword.  If it's a number, it refers to a positional argument, and if it's a keyword,
it refers to a named keyword argument. An `arg_name' is treated as a number if
a call to @ref{2148,,str.isdecimal()} on the string would return true.
If the numerical arg_names in a format string
are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
and the numbers 0, 1, 2, ... will be automatically inserted in that order.
Because `arg_name' is not quote-delimited, it is not possible to specify arbitrary
dictionary keys (e.g., the strings @code{'10'} or @code{':-]'}) within a format string.
The `arg_name' can be followed by any number of index or
attribute expressions. An expression of the form @code{'.name'} selects the named
attribute using @ref{bbf,,getattr()}, while an expression of the form @code{'[index]'}
does an index lookup using @ref{280,,__getitem__()}.


Modifié dans la version 3.1: Les spécificateurs de position d'argument peuvent être omis dans les appels à @ref{60c,,str.format()}. Donc @code{'@{@} @{@}'.format(a, b)} est équivalent à @code{'@{0@} @{1@}'.format(a, b)}.



Modifié dans la version 3.4: Les spécificateurs de position d'argument peuvent être omis pour @ref{ea5,,Formatter}.


Quelques exemples simples de formatage de chaînes :

@example
"First, thou shalt count to @{0@}"  # References first positional argument
"Bring me a @{@}"                   # Implicitly references the first positional argument
"From @{@} to @{@}"                   # Same as "From @{0@} to @{1@}"
"My quest is @{name@}"              # References keyword argument 'name'
"Weight in tons @{0.weight@}"       # 'weight' attribute of first positional arg
"Units destroyed: @{players[0]@}"   # First element of keyword argument 'players'.
@end example

The `conversion' field causes a type coercion before formatting.  Normally, the
job of formatting a value is done by the @ref{609,,__format__()} method of the value
itself.  However, in some cases it is desirable to force a type to be formatted
as a string, overriding its own definition of formatting.  By converting the
value to a string before calling @ref{609,,__format__()}, the normal formatting logic
is bypassed.

Actuellement, trois indicateurs sont gérés : @code{'!s'} qui appelle la fonction @ref{435,,str()} sur la valeur, @code{'!r'} qui appelle la fonction @ref{7e7,,repr()} et @code{!a} qui appelle la fonction @ref{139d,,ascii()}.

Quelques exemples :

@example
"Harold's a clever @{0!s@}"        # Calls str() on the argument first
"Bring out the holy @{name!r@}"    # Calls repr() on the argument first
"More @{!a@}"                      # Calls ascii() on the argument first
@end example

Le champ `format_spec' contient une spécification sur la manière selon laquelle la valeur devrait être représentée : des informations telles que la longueur du champ, l'alignement, le remplissage, la précision décimale, etc. Chaque type peut définir son propre "mini-langage de formatage" ou sa propre interprétation de `format_spec'.

La plupart des types natifs gèrent un mini-langage de formatage usuel qui est décrit dans la section suivante.

Un champ `format_spec' peut contenir un champ de remplacement imbriqué. Ces champs de remplacement imbriqués peuvent contenir un nom de champ, un indicateur de conversion, mais une imbrication récursive plus profonde n'est pas permise. Les champs de remplacement au sein de `format_spec' sont substitués avant que la chaîne `format_spec' ne soit interprétée. Cela permet que le formatage d'une valeur soit dynamiquement spécifié.

Voir la section @ref{225f,,Exemples de formats} pour des exemples.

@menu
* Mini-langage de spécification de format:: 
* Exemples de formats:: 

@end menu

@node Mini-langage de spécification de format,Exemples de formats,,Syntaxe de formatage de chaîne
@anchor{library/string format-specification-mini-language}@anchor{2260}@anchor{library/string formatspec}@anchor{1e5}
@subsubsection Mini-langage de spécification de format


Les "Spécifications de format" sont utilisées avec les champs de remplacement contenus dans les chaînes de formatage, pour définir comment les valeurs doivent être représentées (voir @ref{1367,,Syntaxe de formatage de chaîne} et @ref{997,,f-strings}). Elles peuvent aussi être passées directement à la fonction native @ref{60a,,format()}.  Chaque type `formatable' peut définir comment les spécifications sur les valeurs de ce type doivent être interprétées.

La plupart des primitives implémentent les options suivantes, même si certaines options de formatage ne sont prises en charge que pour les types numériques.

Une convention généralement admise est qu'une chaîne vide produit le même résultat que si vous aviez appelé @ref{435,,str()} sur la valeur. Une chaîne de format non vide modifie habituellement le résultat.

La forme générale d'un `spécificateur de format standard' est :

@example
@anchor{library/string grammar-token-format-spec-format_spec}@anchor{2261}format_spec     ::= [[fill]align][sign]["z"]["#"]["0"][width][grouping_option]["." precision][type]
@anchor{library/string grammar-token-format-spec-fill}@anchor{2262}fill            ::= <any character>
@anchor{library/string grammar-token-format-spec-align}@anchor{2263}align           ::= "<" | ">" | "=" | "^"
@anchor{library/string grammar-token-format-spec-sign}@anchor{2264}sign            ::= "+" | "-" | " "
@anchor{library/string grammar-token-format-spec-width}@anchor{2265}width           ::= digit+
@anchor{library/string grammar-token-format-spec-grouping_option}@anchor{2266}grouping_option ::= "_" | ","
@anchor{library/string grammar-token-format-spec-precision}@anchor{2267}precision       ::= digit+
@anchor{library/string grammar-token-format-spec-type}@anchor{2268}type            ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
@end example

Si une valeur valide est spécifiée pour `align', elle peut être précédée par un caractère `fill', qui peut être n'importe quel caractère (espace par défaut si la valeur est omise). Il n'est pas possible d'utiliser une accolade littérale ("@code{@{}" ou "@code{@}}") comme caractère `fill' dans une @ref{997,,chaîne de formatage littérale} ou avec la méthode @ref{60c,,str.format()}.  Cependant, il est possible d'insérer une accolade à l'aide d'un champ de remplacement imbriqué.  Cette limitation n'affecte pas la fonction @ref{60a,,format()}.

Le sens des différentes options d'alignement est donné comme suit :

@geindex < (less);in string formatting
@geindex > (greater);in string formatting
@geindex = (equals);in string formatting
@geindex ^ (caret);in string formatting


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@item

@code{'<'}

@tab

Force le champ à être aligné à gauche dans l'espace disponible (c'est le spécificateur par défaut pour la plupart des objets).

@item

@code{'>'}

@tab

Force le champ à être aligné à droite dans l'espace disponible (c'est le spécificateur par défaut pour les nombres).

@item

@code{'='}

@tab

Forces the padding to be placed after the sign (if any)
but before the digits.  This is used for printing fields
in the form '+000000120'. This alignment option is only
valid for numeric types, excluding @ref{2ec,,complex}.
It becomes the default for numbers when '0' immediately
precedes the field width.

@item

@code{'^'}

@tab

Force le champ à être centré dans l'espace disponible.

@end multitable


Notons que la longueur du champ est toujours égale à la taille nécessaire pour remplir le champ avec l'objet à moins que la valeur minimum ne soit précisée.  Ainsi, si aucune valeur n'est précisée, l'option d'alignement n'a aucun sens.

L'option `sign' est uniquement valide pour les types numériques, et peut valoir :

@geindex + (plus);in string formatting
@geindex - (minus);in string formatting
@geindex espace;in string formatting


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@item

@code{'+'}

@tab

indique que le signe doit être affiché pour les nombres tant positifs que négatifs.

@item

@code{'-'}

@tab

indique que le signe doit être affiché uniquement pour les nombres négatifs (c'est le comportement par défaut).

@item

espace

@tab

indique qu'un espace doit précéder les nombres positifs et qu'un signe moins doit précéder les nombres négatifs.

@end multitable


@geindex z;in string formatting

The @code{'z'} option coerces negative zero floating-point values to positive
zero after rounding to the format precision.  This option is only valid for
floating-point presentation types.


Modifié dans la version 3.11: Added the @code{'z'} option (see also 
@geindex Python Enhancement Proposals; PEP 682
PEP 682@footnote{https://peps.python.org/pep-0682/}).


@geindex # (hash);in string formatting

L'option @code{'#'} impose l'utilisation de la "forme alternative" pour la conversion. La forme alternative est définie différemment pour différent types. Cette option est uniquement valide pour les types entiers, flottants et complexes. Pour les entiers, quand l'affichage binaire, octal ou hexadécimal est utilisé, cette option ajoute le préfixe @code{'0b'}, @code{'0o'}, @code{'0x'} ou @code{'0X'} à la valeur affichée. Pour les flottants et les complexes, la forme alternative impose que le résultat de la conversion contienne toujours une virgule, même si aucun chiffre ne vient après. Normalement, une virgule apparaît dans le résultat de ces conversions seulement si un chiffre le suit. De plus, pour les conversions @code{'g'} et @code{'G'}, les zéros finaux ne sont pas retirés du résultat.

@geindex @comma{} (comma);in string formatting

The @code{','} option signals the use of a comma for a thousands separator for
floating-point presentation types and for integer presentation type @code{'d'}.
For other presentation types, this option is an error.
For a locale aware separator, use the @code{'n'} integer presentation type
instead.


Modifié dans la version 3.1: Ajout de l'option @code{','} (voir 
@geindex Python Enhancement Proposals; PEP 378
PEP 378@footnote{https://peps.python.org/pep-0378/}).


@geindex _ (underscore);in string formatting

The @code{'_'} option signals the use of an underscore for a thousands
separator for floating-point presentation types and for integer
presentation type @code{'d'}.  For integer presentation types @code{'b'},
@code{'o'}, @code{'x'}, and @code{'X'}, underscores will be inserted every 4
digits.  For other presentation types, specifying this option is an
error.


Modifié dans la version 3.6: Ajout de l'option @code{'_'} (voir aussi 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/}).


`width' est un entier en base 10 qui définit la longueur minimale de tout le champ, y compris les préfixes, séparateurs et autres caractères de formatage. Si elle n'est pas spécifiée, alors le champ `width' est déterminé par le contenu.

When no explicit alignment is given, preceding the `width' field by a zero
(@code{'0'}) character enables sign-aware zero-padding for numeric types,
excluding @ref{2ec,,complex}.  This is equivalent to a `fill' character of
@code{'0'} with an `alignment' type of @code{'='}.


Modifié dans la version 3.10: Preceding the `width' field by @code{'0'} no longer affects the default
alignment for strings.


The `precision' is a decimal integer indicating how many digits should be
displayed after the decimal point for presentation types
@code{'f'} and @code{'F'}, or before and after the decimal point for presentation
types @code{'g'} or @code{'G'}.  For string presentation types the field
indicates the maximum field size - in other words, how many characters will be
used from the field content.  The `precision' is not allowed for integer
presentation types.

Finalement, le spécificateur `type' détermine comment la donnée doit être représentée.

Les types disponibles de représentation de chaîne sont :

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Signification

@item

@code{'s'}

@tab

Format de chaîne. C'est le type par défaut pour les chaînes de caractères et peut être omis.

@item

@code{None}

@tab

Pareil que @code{'s'}.

@end multitable

@end quotation

Les types disponibles de représentation d'entier sont :

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Signification

@item

@code{'b'}

@tab

Format binaire. Affiche le nombre en base 2.

@item

@code{'c'}

@tab

Caractère. Convertit l'entier en caractère Unicode associé avant de l'afficher.

@item

@code{'d'}

@tab

Entier décimal. Affiche le nombre en base 10.

@item

@code{'o'}

@tab

Format octal. Affiche le nombre en base 8.

@item

@code{'x'}

@tab

Format hexadécimal. Affiche le nombre en base 16 en utilisant les lettres minuscules pour les chiffres au-dessus de 9.

@item

@code{'X'}

@tab

Format hexadécimal. Affiche le nombre en base 16 en utilisant les lettres majuscules pour les chiffres au-dessus de 9. Si @code{'#'} est présent, le préfixe @code{'0x'} est également passé en majuscules pour devenir @code{'0X'}.

@item

@code{'n'}

@tab

Nombre. Pareil que @code{'d'} si ce n'est que ce sont les paramètres de localisation qui sont utilisés afin de déterminer le séparateur de nombres approprié.

@item

@code{None}

@tab

Pareil que @code{'d'}.

@end multitable

@end quotation

In addition to the above presentation types, integers can be formatted
with the floating-point presentation types listed below (except
@code{'n'} and @code{None}). When doing so, @ref{2eb,,float()} is used to convert the
integer to a floating-point number before formatting.

Les représentations possibles pour les @ref{2eb,,float} et les @ref{29a,,Decimal} sont :

@quotation


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Signification

@item

@code{'e'}

@tab

Scientific notation. For a given precision @code{p},
formats the number in scientific notation with the
letter 'e' separating the coefficient from the exponent.
The coefficient has one digit before and @code{p} digits
after the decimal point, for a total of @code{p + 1}
significant digits. With no precision given, uses a
precision of @code{6} digits after the decimal point for
@ref{2eb,,float}, and shows all coefficient digits
for @ref{29a,,Decimal}.  If @code{p=0}, the decimal
point is omitted unless the @code{#} option is used.

@item

@code{'E'}

@tab

Notation scientifique. Pareil que @code{'e'} sauf que Python utilise la lettre majuscule 'E' comme séparateur.

@item

@code{'f'}

@tab

Fixed-point notation. For a given precision @code{p},
formats the number as a decimal number with exactly
@code{p} digits following the decimal point. With no
precision given, uses a precision of @code{6} digits after
the decimal point for @ref{2eb,,float}, and uses a
precision large enough to show all coefficient digits
for @ref{29a,,Decimal}.  If @code{p=0}, the decimal
point is omitted unless the @code{#} option is used.

@item

@code{'F'}

@tab

Virgule fixe. Pareil que @code{'f'} à part @code{nan} qui devient @code{NAN} et @code{inf} qui devient @code{INF}.

@item

@code{'g'}

@tab

Format général. Pour une précision donnée @code{p >= 1}, Python arrondit le nombre à @code{p} chiffres significatifs et puis formate le résultat soit en virgule fixe soit en notation scientifique, en fonction de la magnitude. Une précision de @code{0} est considérée équivalente à une précision de @code{1}.

Les règles précises sont les suivantes : supposons que le résultat formaté avec le type de représentation @code{'e'} et une précision @code{p-1} ait un exposant @code{exp}. Alors, si @code{m <= exp <= p} où @code{m} vaut @code{–4} pour les nombres à virgule flottante et @code{–6} pour les @ref{29a,,Decimals}, le nombre est formaté avec le type de représentation @code{'f'} et une précision @code{p-1-exp}. Sinon, le nombre est formaté avec le type de représentation @code{'e'} et une précision @code{p-1}. Dans les deux cas, les zéros finaux et non significatifs sont retirés, et la virgule est également retirée s'il n'y a aucun chiffre la suivant, sauf si l'option @code{'#'} est utilisée.

Si la précision n'est pas donnée, utilise une précision de @code{6} chiffres significatifs pour les @ref{2eb,,float}. Pour les @ref{29a,,Decimal}, la mantisse du résultat dépend de la valeur : la notation scientifique est utilisée pour les valeurs inférieures à @code{1e-6} en valeur absolue et pour celles dont le dernier chiffre significatif a une position supérieure à 1 ; dans les autres cas, la notation en virgule fixe est utilisée.

Les valeurs suivantes : infini négatif, infini positif, zéro positif, zéro négatif, `not a number' sont formatées respectivement par @code{inf}, @code{-inf}, @code{0}, @code{-0} et @code{nan}, peu importe la précision.

@item

@code{'G'}

@tab

Format général. Pareil que @code{'G'} si ce n'est que @code{'E'} est utilisé si le nombre est trop grand. La représentation des infinis et de `NaN' sont en majuscules également.

@item

@code{'n'}

@tab

Nombre. Pareil que @code{'g'}, si ce n'est que la configuration de localisation est prise en compte pour insérer le séparateur approprié.

@item

@code{'%'}

@tab

Pourcentage. Multiplie le nombre par 100 et l'affiche en virgule fixe (@code{'f'}), suivi d'un symbole pourcent @code{'%'}.

@item

@code{None}

@tab

For @ref{2eb,,float} this is like the @code{'g'} type, except
that when fixed-point notation is used to format the
result, it always includes at least one digit past the
decimal point, and switches to the scientific notation
when @code{exp >= p - 1}.  When the precision is not
specified, the latter will be as large as needed to
represent the given value faithfully.

Pour les @ref{29a,,Decimal}, c'est identique à @code{'g'} ou @code{'G'} en fonction de la valeur de @code{context.capitals} du contexte décimal courant.

L'effet visé est de coller à la valeur renvoyée par @ref{435,,str()} telle que modifiée par les autres modificateurs de format.

@end multitable

@end quotation

The result should be correctly rounded to a given precision @code{p} of digits
after the decimal point.  The rounding mode for @ref{2eb,,float} matches that
of the @ref{12b8,,round()} builtin.  For @ref{29a,,Decimal}, the rounding
mode of the current @ref{2269,,context} will be used.

The available presentation types for @ref{2ec,,complex} are the same as those for
@ref{2eb,,float} (@code{'%'} is not allowed).  Both the real and imaginary components
of a complex number are formatted as floating-point numbers, according to the
specified presentation type.  They are separated by the mandatory sign of the
imaginary part, the latter being terminated by a @code{j} suffix.  If the presentation
type is missing, the result will match the output of @ref{435,,str()} (complex numbers with
a non-zero real part are also surrounded by parentheses), possibly altered by
other format modifiers.

@node Exemples de formats,,Mini-langage de spécification de format,Syntaxe de formatage de chaîne
@anchor{library/string format-examples}@anchor{226a}@anchor{library/string formatexamples}@anchor{225f}
@subsubsection Exemples de formats


Cette section contient des exemples de la syntaxe de @ref{60c,,str.format()} et des comparaisons avec l'ancien formatage par @code{%}.

Dans la plupart des cas, la syntaxe est similaire à l'ancien formatage par @code{%}, avec l'ajout de @code{@{@}} et avec @code{:} au lieu de @code{%}. Par exemple : @code{'%03.2f'} peut être changé en @code{'@{03.2f@}'}.

La nouvelle syntaxe de formatage gère également de nouvelles options et des options différentes, montrées dans les exemples qui suivent.

Accéder à un argument par sa position :

@example
>>> '@{0@}, @{1@}, @{2@}'.format('a', 'b', 'c')
'a, b, c'
>>> '@{@}, @{@}, @{@}'.format('a', 'b', 'c')  # 3.1+ only
'a, b, c'
>>> '@{2@}, @{1@}, @{0@}'.format('a', 'b', 'c')
'c, b, a'
>>> '@{2@}, @{1@}, @{0@}'.format(*'abc')      # unpacking argument sequence
'c, b, a'
>>> '@{0@}@{1@}@{0@}'.format('abra', 'cad')   # arguments' indices can be repeated
'abracadabra'
@end example

Accéder à un argument par son nom :

@example
>>> 'Coordinates: @{latitude@}, @{longitude@}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = @{'latitude': '37.24N', 'longitude': '-115.81W'@}
>>> 'Coordinates: @{latitude@}, @{longitude@}'.format(**coord)
'Coordinates: 37.24N, -115.81W'
@end example

Accéder aux attributs d'un argument :

@example
>>> c = 3-5j
>>> ('The complex number @{0@} is formed from the real part @{0.real@} '
...  'and the imaginary part @{0.imag@}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point:
...     def __init__(self, x, y):
...         self.x, self.y = x, y
...     def __str__(self):
...         return 'Point(@{self.x@}, @{self.y@})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'
@end example

Accéder aux éléments d'un argument :

@example
>>> coord = (3, 5)
>>> 'X: @{0[0]@};  Y: @{0[1]@}'.format(coord)
'X: 3;  Y: 5'
@end example

Remplacer @code{%s} et @code{%r} :

@example
>>> "repr() shows quotes: @{!r@}; str() doesn't: @{!s@}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"
@end example

Aligner le texte et spécifier une longueur minimale :

@example
>>> '@{:<30@}'.format('left aligned')
'left aligned                  '
>>> '@{:>30@}'.format('right aligned')
'                 right aligned'
>>> '@{:^30@}'.format('centered')
'           centered           '
>>> '@{:*^30@}'.format('centered')  # use '*' as a fill char
'***********centered***********'
@end example

Remplacer @code{%+f}, @code{%-f}, et @code{%f} et spécifier un signe :

@example
>>> '@{:+f@}; @{:+f@}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'
>>> '@{: f@}; @{: f@}'.format(3.14, -3.14)  # show a space for positive numbers
' 3.140000; -3.140000'
>>> '@{:-f@}; @{:-f@}'.format(3.14, -3.14)  # show only the minus -- same as '@{:f@}; @{:f@}'
'3.140000; -3.140000'
@end example

Remplacer @code{%x} et @code{%o} et convertir la valeur dans différentes bases :

@example
>>> # format also supports binary numbers
>>> "int: @{0:d@};  hex: @{0:x@};  oct: @{0:o@};  bin: @{0:b@}".format(42)
'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "int: @{0:d@};  hex: @{0:#x@};  oct: @{0:#o@};  bin: @{0:#b@}".format(42)
'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'
@end example

Utiliser une virgule comme séparateur des milliers :

@example
>>> '@{:,@}'.format(1234567890)
'1,234,567,890'
@end example

Exprimer un pourcentage :

@example
>>> points = 19
>>> total = 22
>>> 'Correct answers: @{:.2%@}'.format(points/total)
'Correct answers: 86.36%'
@end example

Utiliser un formatage propre au type :

@example
>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '@{:%Y-%m-%d %H:%M:%S@}'.format(d)
'2010-07-04 12:15:58'
@end example

Arguments imbriqués et des exemples plus complexes :

@example
>>> for align, text in zip('<^>', ['left', 'center', 'right']):
...     '@{0:@{fill@}@{align@}16@}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '@{:02X@}@{:02X@}@{:02X@}@{:02X@}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12): 
...     for base in 'dXob':
...         print('@{0:@{width@}@{base@}@}'.format(num, base=base, width=width), end=' ')
...     print()
...
    5     5     5   101
    6     6     6   110
    7     7     7   111
    8     8    10  1000
    9     9    11  1001
   10     A    12  1010
   11     B    13  1011
@end example

@node Chaînes modèles,Fonctions d'assistance,Syntaxe de formatage de chaîne,string --- Common string operations
@anchor{library/string id1}@anchor{226b}@anchor{library/string template-strings}@anchor{2158}
@subsubsection Chaînes modèles


Template strings provide simpler string substitutions as described in
@geindex Python Enhancement Proposals; PEP 292
PEP 292@footnote{https://peps.python.org/pep-0292/}.  A primary use case for template strings is for
internationalization (i18n) since in that context, the simpler syntax and
functionality makes it easier to translate than other built-in string
formatting facilities in Python.  As an example of a library built on template
strings for i18n, see the
flufl.i18n@footnote{https://flufli18n.readthedocs.io/en/latest/} package.

@geindex $ (dollar);in template strings

Les chaînes modèles prennent en charge les substitutions basées sur @code{$} en utilisant les règles suivantes :


@itemize *

@item 
@code{$$} est un échappement ; il est remplacé par un simple @code{$}.

@item 
@code{$identifier} dénomme un substituant lié à la clef @code{"identifier"}. Par défaut, @code{"identifier"} est restreint à toute chaîne de caractères ASCII alphanumériques sensibles à la casse (avec les `underscores') commençant avec un `underscore' ou un caractère alphanumérique. Le premier caractère n'étant pas un identifieur après le @code{$} termine la spécification du substituant.

@item 
@code{$@{identifier@}} est équivalent à @code{$identifier}. Cette notation est requise quand un caractère valide pour une clef de substituant suit directement le substituant mais ne fait pas partie du substituant, comme @code{"$@{noun@}ification"}.
@end itemize

Tout autre présence du symbole @code{$} dans une chaîne résultera en la levée d'une @ref{1ff,,ValueError}.

Le module @ref{d2,,string} fournit une classe @ref{672,,Template} qui implémente ces règles. Les méthodes de @ref{672,,Template} sont :

@geindex Template (classe dans string)
@anchor{library/string string Template}@anchor{672}
@deffn {Classe} string.Template (template)

Le constructeur prend un seul argument qui est la chaîne du `template'.

@geindex substitute() (méthode string.Template)
@anchor{library/string string Template substitute}@anchor{1c77}
@deffn {Méthode} substitute (mapping=@{@}, /, **kwds)

Applique les substitutions du `template', et la renvoie dans une nouvelle chaîne. `mapping' est un objet dictionnaire-compatible qui lie les substituants dans le `template'. De même, vous pouvez fournir des arguments mot-clefs tels que les mot-clefs sont les substituants. Quand à la fois `mapping' et `kwds' sont donnés et qu'il y a des doublons, les substituants de `kwds' sont prioritaires.
@end deffn

@geindex safe_substitute() (méthode string.Template)
@anchor{library/string string Template safe_substitute}@anchor{1c78}
@deffn {Méthode} safe_substitute (mapping=@{@}, /, **kwds)

Comme @ref{1c77,,substitute()}, si ce n'est qu'au lieu de lever une @ref{33a,,KeyError} si un substituant n'est ni dans `mapping', ni dans `kwds', c'est le nom du substituant inchangé qui apparaît dans la chaîne finale. Également, à l'inverse de @ref{1c77,,substitute()}, toute autre apparition de @code{$} renverra simplement @code{$} au lieu de lever une exception @ref{1ff,,ValueError}.

Bien que d'autres exceptions peuvent toujours être levées, cette méthode est dite sûre car elle tente de toujours renvoyer une chaîne utilisable au lieu de lever une exception. Ceci dit, @ref{1c78,,safe_substitute()} est tout sauf sûre car elle ignore silencieusement toute malformation dans le `template' qui contient des délimiteurs fantômes, des accolades non fermées, ou des substituants qui ne sont pas des identificateurs Python valides.
@end deffn

@geindex is_valid() (méthode string.Template)
@anchor{library/string string Template is_valid}@anchor{671}
@deffn {Méthode} is_valid ()

Returns false if the template has invalid placeholders that will cause
@ref{1c77,,substitute()} to raise @ref{1ff,,ValueError}.


Ajouté dans la version 3.11.

@end deffn

@geindex get_identifiers() (méthode string.Template)
@anchor{library/string string Template get_identifiers}@anchor{670}
@deffn {Méthode} get_identifiers ()

Returns a list of the valid identifiers in the template, in the order
they first appear, ignoring any invalid identifiers.


Ajouté dans la version 3.11.

@end deffn

Les instances de la classe @ref{672,,Template} fournissent également un attribut public :

@geindex template (attribut string.Template)
@anchor{library/string string Template template}@anchor{226c}
@deffn {Attribut} template

C'est l'objet `template' passé comme argument au constructeur. En général, vous ne devriez pas le changer, mais un accès en lecture-seule n'est pas possible à fournir.
@end deffn
@end deffn

Voici un exemple de comment utiliser un `Template' :

@example
>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
>>> d = dict(who='tim')
>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
...
ValueError: Invalid placeholder in string: line 1, col 11
>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
...
KeyError: 'what'
>>> Template('$who likes $what').safe_substitute(d)
'tim likes $what'
@end example

Usage avancé : vous pouvez faire dériver vos sous-classes de @ref{672,,Template} pour personnaliser la syntaxe des substituants, les caractères délimiteurs, ou l'entièreté de l'expression rationnelle utilisée pour analyser les chaînes `templates'. Pour faire cela, vous pouvez redéfinir les attributs suivants :


@itemize *

@item 
`delimiter' — La chaîne littérale décrivant le délimiteur pour introduire un substituant. Sa valeur par défaut est @code{$}. Notez qu'elle ne doit `pas' être une expression rationnelle, puisque l'implémentation appelle @ref{bf7,,re.escape()} sur cette chaîne si nécessaire. Notez aussi que le délimiteur ne peut pas être changé après la création de la classe.

@item 
`idpattern' — L'expression rationnelle décrivant le motif pour les substituants non entourés d'accolades. La valeur par défaut de cette expression rationnelle est @code{(?a:[_a-z][_a-z0-9]*)}. Si `idpattern' est donné et `braceidpattern' est @code{None}, ce motif est aussi utilisé pour les marqueurs entre accolades.

@cartouche
@quotation Note 
Puisque par défaut `flags' vaut @code{re.IGNORECASE}, des caractères `non-ASCII' peuvent correspondre au motif @code{[a-z]}. C'est pourquoi on utilise une option locale @code{a} ici.
@end quotation
@end cartouche


Modifié dans la version 3.7: `braceidpattern' peut être utilisé pour définir des motifs des motifs différents suivant qu’ils sont à l’intérieur ou à l’extérieur des accolades.


@item 
`braceidpattern' — Similaire à `idpattern' mais décrit le motif quand il est placé entre accolades.  La valeur par défaut est @code{None} ce qui signifie que seul `idpattern' est pris en compte (le motif est le même, qu’il soit à l’intérieur d’accolades ou non). S’il est donné, cela vous permet de définir des motifs entre accolades différents des motifs sans accolades.


Ajouté dans la version 3.7.


@item 
`flags' — L'indicateur d'expression rationnelle  qui sera appliqué lors de la compilation de l'expression rationnelle pour reconnaître les substitutions. La valeur par défaut est @code{re.IGNORECASE}. Notez que @code{re.VERBOSE} sera toujours ajouté à l'indicateur. Donc, un `idpattern' personnalisé doit suivre les conventions des expressions rationnelles `verbose'.


Ajouté dans la version 3.2.

@end itemize

Également, vous pouvez fournir le motif d'expression rationnelle en entier en redéfinissant l'attribut `pattern'. Si vous faites cela, la valeur doit être un objet 'expression rationnelle' avec quatre groupes de capture de noms. Les groupes de capture correspondent aux règles données au-dessus, ainsi qu'à la règle du substituant invalide :


@itemize *

@item 
`escaped' — Ce groupe lie les séquences échappées (par exemple @code{$$}) dans le motif par défaut.

@item 
`named' — Ce groupe lie les substituants non entourés d'accolades ; il ne devrait pas inclure le délimiteur dans le groupe de capture.

@item 
`braced' — Ce groupe lie le nom entouré d'accolades ; il ne devrait inclure ni le délimiteur, ni les accolades dans le groupe de capture.

@item 
`invalid' — Ce groupe lie tout autre motif de délimitation (habituellement, un seul délimiteur) et il devrait apparaître en dernier dans l'expression rationnelle.
@end itemize

The methods on this class will raise @ref{1ff,,ValueError} if the pattern matches
the template without one of these named groups matching.

@node Fonctions d'assistance,,Chaînes modèles,string --- Common string operations
@anchor{library/string helper-functions}@anchor{226d}
@subsubsection Fonctions d'assistance


@geindex capwords() (dans le module string)
@anchor{library/string string capwords}@anchor{2154}
@deffn {Fonction} string.capwords (s, sep=None)

Divise l'argument en mots en utilisant @ref{e93,,str.split()}, capitalise chaque mot en utilisant @ref{2144,,str.capitalize()} et assemble les mots capitalisés en utilisant @ref{2134,,str.join()}. Si le second argument optionnel `sep' est absent ou vaut @code{None}, les séquences de caractères blancs sont remplacées par un seul espace et les espaces débutant et finissant la chaîne sont retirés. Sinon, `sep' et utilisé pour séparer et ré-assembler les mots.
@end deffn

@node re --- Regular expression operations,difflib --- Helpers for computing deltas,string --- Common string operations,Services de Manipulation de Texte
@anchor{library/re doc}@anchor{226e}@anchor{library/re module-re}@anchor{b8}@anchor{library/re re-regular-expression-operations}@anchor{226f}
@subsection @code{re} --- Regular expression operations


@geindex module; re

`Code source :' Lib/re/@footnote{https://github.com/python/cpython/tree/3.13/Lib/re/}


__________________________________________________________________


Ce module fournit des opérations sur les expressions rationnelles similaires à celles que l'on trouve dans Perl.

Both patterns and strings to be searched can be Unicode strings (@ref{435,,str})
as well as 8-bit strings (@ref{1bd,,bytes}).
However, Unicode strings and 8-bit strings cannot be mixed:
that is, you cannot match a Unicode string with a bytes pattern or
vice-versa; similarly, when asking for a substitution, the replacement
string must be of the same type as both the pattern and the search string.

Regular expressions use the backslash character (@code{'\'}) to indicate
special forms or to allow special characters to be used without invoking
their special meaning.  This collides with Python's usage of the same
character for the same purpose in string literals; for example, to match
a literal backslash, one might have to write @code{'\\\\'} as the pattern
string, because the regular expression must be @code{\\}, and each
backslash must be expressed as @code{\\} inside a regular Python string
literal. Also, please note that any invalid escape sequences in Python's
usage of the backslash in string literals now generate a @ref{44f,,SyntaxWarning}
and in the future this will become a @ref{18b,,SyntaxError}. This behaviour
will happen even if it is a valid escape sequence for a regular expression.

La solution est d'utiliser la notation des chaînes brutes en Python pour les expressions rationnelles ; Les `backslashs' ne provoquent aucun traitement spécifique dans les chaînes littérales préfixées par @code{'r'}. Ainsi, @code{r"\n"} est une chaîne de deux caractères contenant @code{'\'} et @code{'n'}, tandis que @code{"\n"} est une chaîne contenant un unique caractère : un saut de ligne. Généralement, les motifs seront exprimés en Python à l'aide de chaînes brutes.

Il est important de noter que la plupart des opérations sur les expressions rationnelles sont disponibles comme fonctions au niveau du module et comme méthodes des @ref{f71,,expressions rationnelles compilées}. Les fonctions sont des raccourcis qui ne vous obligent pas à d'abord compiler un objet `regex', mais auxquelles manquent certains paramètres de configuration fine.


@subsubheading Voir aussi


The third-party regex@footnote{https://pypi.org/project/regex/} module,
which has an API compatible with the standard library @ref{b8,,re} module,
but offers additional functionality and a more thorough Unicode support.


@menu
* Syntaxe des expressions rationnelles:: 
* Contenu du module:: 
* Objets d'expressions rationnelles:: 
* Objets de correspondance:: 
* Exemples d'expressions rationnelles:: 

@end menu

@node Syntaxe des expressions rationnelles,Contenu du module,,re --- Regular expression operations
@anchor{library/re re-syntax}@anchor{70e}@anchor{library/re regular-expression-syntax}@anchor{2270}
@subsubsection Syntaxe des expressions rationnelles


Une expression rationnelle (`regular expression' ou `RE') spécifie un ensemble de chaînes de caractères qui lui correspondent ; les fonctions de ce module vous permettent de vérifier si une chaîne particulière correspond à une expression rationnelle donnée (ou si un expression rationnelle donnée correspond à une chaîne particulière, ce qui revient à la même chose).

Les expressions rationnelles peuvent être concaténées pour former de nouvelles expressions : si `A' et `B' sont deux expressions rationnelles, alors `AB' est aussi une expression rationnelle. En général, si une chaîne `p' valide `A' et qu'une autre chaîne `q' valide `B', la chaîne `pq' validera AB. Cela est vrai tant que `A' et `B' ne contiennent pas d'opérations de priorité ; de conditions de frontière entre `A' et `B' ; ou de références vers des groupes numérotés. Ainsi, des expressions complexes peuvent facilement être construites depuis de plus simples expressions primitives comme celles décrites ici. Pour plus de détails sur la théorie et l'implémentation des expressions rationnelles, consultez le livre de Friedl @ref{2271,,[Frie09]}, ou à peu près n'importe quel livre dédié à la construction de compilateurs.

Une brève explication sur le format des expressions rationnelles suit. Pour de plus amples informations et une présentation plus simple, référez-vous au @ref{2272,,Guide des expressions régulières}.

Les expressions rationnelles peuvent contenir à la fois des caractères spéciaux et ordinaires. Les plus ordinaires, comme @code{'A'}, @code{'a'} ou @code{'0'} sont les expressions rationnelles les plus simples : elles correspondent simplement à elles-mêmes.  Vous pouvez concaténer des caractères ordinaires, ainsi @code{last} correspond à la chaîne @code{'last'}. (Dans la suite de cette section, nous écrirons les expressions rationnelles dans @code{ce style spécifique}, généralement sans guillemets, et les chaînes à tester @code{'entourées de simples guillemets'}.)

Certains caractères, comme @code{'|'} ou @code{'('}, sont spéciaux. Des caractères spéciaux peuvent aussi exister pour les classes de caractères ordinaires, ou affecter comment les expressions rationnelles autour d'eux seront interprétées.

Les caractères de répétition ou quantificateurs (@code{*}, @code{+}, @code{?}, @code{@{m,n@}}, etc.) ne peuvent être directement imbriqués. Cela empêche l'ambiguïté avec le suffixe modificateur non gourmand @code{?} et avec les autres modificateurs dans d'autres implémentations. Pour appliquer une seconde répétition à une première, des parenthèses peuvent être utilisées. Par exemple, l'expression @code{(?:a@{6@})*} valide toutes les chaînes composées d'un nombre de caractères @code{'a'} multiple de six.

Les caractères spéciaux sont :

@geindex . (dot);in regular expressions


@table @asis

@item @code{.}

(Dot.)  In the default mode, this matches any character except a newline.  If
the @ref{2273,,DOTALL} flag has been specified, this matches any character
including a newline.  @code{(?s:.)} matches any character regardless of flags.
@end table

@geindex ^ (caret);in regular expressions


@table @asis

@item @code{^}

(Accent circonflexe.) Valide le début d'une chaîne de caractères, ainsi que ce qui suit chaque saut de ligne en mode @ref{2274,,MULTILINE}.
@end table

@geindex $ (dollar);in regular expressions


@table @asis

@item @code{$}

Valide la fin d'une chaîne de caractères, ou juste avant le saut de ligne à la fin de la chaîne, ainsi qu'avant chaque saut de ligne en mode @ref{2274,,MULTILINE}. @code{foo} valide à la fois `foo' et `foobar', tandis que l'expression rationnelle @code{foo$} ne correspond qu'à @code{'foo'}. Plus intéressant, chercher @code{foo.$} dans @code{'foo1\nfoo2\n'} trouve normalement @code{'foo2'}, mais @code{'foo1'} en mode @ref{2274,,MULTILINE} ; chercher un simple @code{$} dans @code{'foo\n'} trouvera deux correspondances (vides) : une juste avant le saut de ligne, et une à la fin de la chaîne.
@end table

@geindex * (asterisk);in regular expressions


@table @asis

@item @code{*}

Fait valider par l'expression rationnelle résultante 0 répétition ou plus de l'expression qui précède, avec autant de répétitions que possible. @code{ab*} validera 'a', 'ab' ou 'a' suivi de n'importe quel nombre de 'b'.
@end table

@geindex + (plus);in regular expressions


@table @asis

@item @code{+}

Fait valider par l'expression rationnelle résultante 1 répétition ou plus de l'expression qui précède. @code{ab+} validera 'a' suivi de n'importe quel nombre non nul de 'b' ; cela ne validera pas la chaîne 'a'.
@end table

@geindex ? (question mark);in regular expressions


@table @asis

@item @code{?}

Fait valider par l'expression rationnelle résultante 0 ou 1 répétition de l'expression qui précède. @code{ab?} correspondra à 'a' ou 'ab'.
@end table

@geindex *?;in regular expressions
@geindex +?;in regular expressions
@geindex ??;in regular expressions


@table @asis

@item @code{*?}, @code{+?}, @code{??}

Les quantificateurs @code{'*'}, @code{'+'} et @code{'?'} sont tous `greedy' (gourmands) ; ils valident autant de texte que possible.  Parfois ce comportement n'est pas désiré ; si l'expression rationnelle @code{<.*>} est testée avec la chaîne @code{'<a> b <c>'}, cela correspondra à la chaîne entière, et non juste à @code{'<a>'}.  Ajouter @code{?} derrière le quantificateur lui fait réaliser l'opération de façon `non-greedy' (ou `minimal') ; le `moins' de caractères possibles seront validés.  Utiliser l'expression rationnelle @code{<.*?>} validera uniquement @code{'<a>'}.
@end table

@geindex *+;in regular expressions
@geindex ++;in regular expressions
@geindex ?+;in regular expressions


@table @asis

@item @code{*+}, @code{++}, @code{?+}

Like the @code{'*'}, @code{'+'}, and @code{'?'} quantifiers, those where @code{'+'} is
appended also match as many times as possible.
However, unlike the true greedy quantifiers, these do not allow
back-tracking when the expression following it fails to match.
These are known as `possessive' quantifiers.
For example, @code{a*a} will match @code{'aaaa'} because the @code{a*} will match
all 4 @code{'a'}s, but, when the final @code{'a'} is encountered, the
expression is backtracked so that in the end the @code{a*} ends up matching
3 @code{'a'}s total, and the fourth @code{'a'} is matched by the final @code{'a'}.
However, when @code{a*+a} is used to match @code{'aaaa'}, the @code{a*+} will
match all 4 @code{'a'}, but when the final @code{'a'} fails to find any more
characters to match, the expression cannot be backtracked and will thus
fail to match.
@code{x*+}, @code{x++} and @code{x?+} are equivalent to @code{(?>x*)}, @code{(?>x+)}
and @code{(?>x?)} correspondingly.


Ajouté dans la version 3.11.

@end table

@geindex @{@} (curly brackets);in regular expressions


@table @asis

@item @code{@{m@}}

Spécifie qu'exactement `m' copies de l'expression rationnelle qui précède devront être validées ; un nombre plus faible de correspondances empêche l'expression entière de correspondre. Par exemple, @code{a@{6@}} correspondra exactement à six caractères @code{'a'}, mais pas à cinq.

@item @code{@{m,n@}}

Fait valider par l'expression rationnelle résultante entre `m' et `n' répétitions de l'expression qui précède, cherchant à en valider le plus possible.  Par exemple, @code{a@{3,5@}} validera entre 3 et 5 caractères @code{'a'}.  Omettre `m' revient à spécifier 0 comme borne inférieure, et omettre `n' à avoir une borne supérieure infinie.  Par exemple, @code{a@{4,@}b} correspondra à @code{'aaaab'} ou à un millier de caractères @code{'a'} suivis d'un @code{'b'}, mais pas à @code{'aaab'}. La virgule ne doit pas être omise, auquel cas le modificateur serait confondu avec la forme décrite précédemment.

@item @code{@{m,n@}?}

Fait valider l'expression rationnelle résultante entre `m' et `n' répétitions de l'expression qui précède, cherchant à en valider le moins possible. Il s'agit de la version non gourmande du précédent quantificateur. Par exemple, dans la chaîne de 6 caractères @code{'aaaaaa'}, @code{a@{3,5@}} trouvera 5 caractères @code{'a'}, alors que @code{a@{3,5@}?} n'en trouvera que 3.

@item @code{@{m,n@}+}

Causes the resulting RE to match from `m' to `n' repetitions of the
preceding RE, attempting to match as many repetitions as possible
`without' establishing any backtracking points.
This is the possessive version of the quantifier above.
For example, on the 6-character string @code{'aaaaaa'}, @code{a@{3,5@}+aa}
attempt to match 5 @code{'a'} characters, then, requiring 2 more @code{'a'}s,
will need more characters than available and thus fail, while
@code{a@{3,5@}aa} will match with @code{a@{3,5@}} capturing 5, then 4 @code{'a'}s
by backtracking and then the final 2 @code{'a'}s are matched by the final
@code{aa} in the pattern.
@code{x@{m,n@}+} is equivalent to @code{(?>x@{m,n@})}.


Ajouté dans la version 3.11.

@end table

@geindex \ (backslash);in regular expressions


@table @asis

@item @code{\}

Échappe les caractères spéciaux (permettant d’identifier des caractères comme @code{'*'}, @code{'?'} et autres) ou signale une séquence spéciale ; les séquences spéciales sont décrites ci-dessous.

Si vous n'utilisez pas de chaînes brutes pour exprimer le motif, souvenez-vous que Python utilise aussi le `backslash' comme une séquence d'échappement dans les chaînes littérales ; si la séquence d'échappement n'est pas reconnue par l'interpréteur Python, le `backslash' et les caractères qui le suivent sont inclus dans la chaîne renvoyée. Cependant, si Python reconnait la séquence, le `backslash' doit être doublé (pour ne plus être reconnu). C'est assez compliqué et difficile à comprendre, c'est pourquoi il est hautement recommandé d'utiliser des chaînes brutes pour tout sauf les expressions les plus simples.
@end table

@geindex [] (square brackets);in regular expressions


@table @asis

@item @code{[]}

Utilisé pour indiquer un ensemble de caractères. Dans un ensemble :


@itemize *

@item 
Les caractères peuvent être listés individuellement, e.g. @code{[amk]} correspondra à @code{'a'}, @code{'m'} ou @code{'k'}.
@end itemize

@geindex - (minus);in regular expressions


@itemize *

@item 
Des intervalles de caractères peuvent être indiqués en donnant deux caractères et les séparant par un @code{'-'}, par exemple @code{[a-z]} correspondra à toute lettre minuscule `ASCII', @code{[0-5][0-9]} à tous nombres de deux chiffres entre @code{00} et @code{59}, et @code{[0-9A-Fa-f]} correspondra à n'importe quel chiffre hexadécimal.  Si @code{'-'} est échappé (@code{[a\-z]}) ou s'il est placé comme premier ou dernier caractère (e.g. @code{[-a]} ou @code{[a-]}), il correspondra à un @code{'-'} littéral.

@item 
Les caractères spéciaux perdent leur sens à l'intérieur des ensembles. Par exemple, @code{[(+*)]} validera chacun des caractères littéraux @code{'('}, @code{'+'}, @code{'*'} ou @code{')'}.
@end itemize

@geindex \ (backslash);in regular expressions


@itemize *

@item 
Character classes such as @code{\w} or @code{\S} (defined below) are also accepted
inside a set, although the characters they match depend on the @ref{2275,,flags} used.
@end itemize

@geindex ^ (caret);in regular expressions


@itemize *

@item 
Les caractères qui ne sont pas dans un intervalle peuvent être trouvés avec l'ensemble complémentaire (`complementing'). Si le premier caractère de l'ensemble est @code{'^'}, tous les caractères qui `ne sont pas' dans l'ensemble seront validés. Par exemple, @code{[^5]} correspondra à tout caractère autre que @code{'5'} et @code{[^^]} validera n'importe quel caractère excepté @code{'^'}. @code{^} n'a pas de sens particulier s'il n'est pas le premier caractère de l'ensemble.

@item 
To match a literal @code{']'} inside a set, precede it with a backslash, or
place it at the beginning of the set.  For example, both @code{[()[\]@{@}]} and
@code{[]()[@{@}]} will match a right bracket, as well as left bracket, braces,
and parentheses.
@end itemize

@c .. index:: single: --; in regular expressions

@c .. index:: single: &&; in regular expressions

@c .. index:: single: ~~; in regular expressions

@c .. index:: single: ||; in regular expressions


@itemize *

@item 
La gestion des ensembles inclus l'un dans l'autre et les opérations d'ensemble comme dans Unicode Technical Standard #18@footnote{https://unicode.org/reports/tr18/} pourrait être ajoutée par la suite. Ceci changerait la syntaxe, donc pour faciliter ce changement, une exception @ref{40b,,FutureWarning} sera levée dans les cas ambigus pour le moment. Ceci inclut les ensembles commençant avec le caractère @code{'['} ou contenant les séquences de caractères @code{'--'}, @code{'&&'}, @code{'~~'} et @code{'||'}.  Pour éviter un message d'avertissement, échapper les séquences avec le caractère antislash (@code{"\"}).
@end itemize


Modifié dans la version 3.7: L'exception @ref{40b,,FutureWarning} est levée si un ensemble de caractères contient une construction dont la sémantique changera dans le futur.

@end table

@geindex | (vertical bar);in regular expressions


@table @asis

@item @code{|}

@code{A|B}, où `A' et `B' peuvent être deux expressions rationnelles arbitraires, crée une expression rationnelle qui validera soit `A' soit `B'.  Un nombre arbitraire d'expressions peuvent être séparées de cette façon par des @code{'|'}.  Cela peut aussi être utilisé au sein de groupes (voir ci-dessous).  Quand une chaîne cible est analysée, les expressions séparées par @code{'|'} sont essayées de la gauche vers la droite. Quand un motif correspond complètement, cette branche est acceptée. Cela signifie qu'une fois que `A' correspond, `B' ne sera pas testée plus loin, même si elle pourrait provoquer une plus ample correspondance.  En d'autres termes, l'opérateur @code{'|'} n'est jamais gourmand.  Pour valider un @code{'|'} littéral, utilisez @code{\|}, ou enveloppez-le dans une classe de caractères, comme @code{[|]}.
@end table

@geindex () (parentheses);in regular expressions


@table @asis

@item @code{(...)}

Valide n'importe quelle expression rationnelle comprise entre les parenthèses, et indique le début et la fin d'un groupe ; le contenu d'un groupe peut être récupéré après qu'une analyse a été effectuée et peut être réutilisé plus loin dans la chaîne avec une séquence spéciale @code{\number}, décrite ci-dessous.  Pour écrire des @code{'('} ou @code{')'} littéraux, utilisez @code{\(} ou @code{\)}, ou enveloppez-les dans une classe de caractères : @code{[(]}, @code{[)]}.
@end table

@geindex (?;in regular expressions


@table @asis

@item @code{(?...)}

Il s'agit d'une notation pour les extensions (un @code{'?'} suivant une @code{'('} n'a pas de sens autrement). Le premier caractère après le @code{'?'} détermine quel sens donner à l'expression. Les extensions ne créent généralement pas de nouveaux groupes ; @code{(?P<name>...)} est la seule exception à la règle. Retrouvez ci-dessous la liste des extensions actuellement supportées.

@item @code{(?aiLmsux)}

(One or more letters from the set
@code{'a'}, @code{'i'}, @code{'L'}, @code{'m'}, @code{'s'}, @code{'u'}, @code{'x'}.)
The group matches the empty string;
the letters set the corresponding flags for the entire regular expression:


@itemize *

@item 
@ref{2276,,re.A} (ASCII-only matching)

@item 
@ref{2277,,re.I} (ignore case)

@item 
@ref{2278,,re.L} (locale dependent)

@item 
@ref{2279,,re.M} (multi-line)

@item 
@ref{227a,,re.S} (dot matches all)

@item 
@ref{227b,,re.U} (Unicode matching)

@item 
@ref{227c,,re.X} (verbose)
@end itemize

(The flags are described in @ref{227d,,Contenu du module}.)
This is useful if you wish to include the flags as part of the
regular expression, instead of passing a `flag' argument to the
@ref{bc1,,re.compile()} function.
Flags should be used first in the expression string.


Modifié dans la version 3.11: Cette construction ne peut être utilisée qu'au début d'une chaîne de caractères.

@end table

@geindex (?;;in regular expressions


@table @asis

@item @code{(?:...)}

Une version sans capture des parenthèses habituelles. Valide n'importe quelle expression rationnelle à l'intérieur des parenthèses, mais la sous-chaîne correspondant au groupe `ne peut pas' être récupérée après l'analyse ou être référencée plus loin dans le motif.

@item @code{(?aiLmsux-imsx:...)}

(Zero or more letters from the set
@code{'a'}, @code{'i'}, @code{'L'}, @code{'m'}, @code{'s'}, @code{'u'}, @code{'x'},
optionally followed by @code{'-'} followed by
one or more letters from the @code{'i'}, @code{'m'}, @code{'s'}, @code{'x'}.)
The letters set or remove the corresponding flags for the part of the expression:


@itemize *

@item 
@ref{2276,,re.A} (ASCII-only matching)

@item 
@ref{2277,,re.I} (ignore case)

@item 
@ref{2278,,re.L} (locale dependent)

@item 
@ref{2279,,re.M} (multi-line)

@item 
@ref{227a,,re.S} (dot matches all)

@item 
@ref{227b,,re.U} (Unicode matching)

@item 
@ref{227c,,re.X} (verbose)
@end itemize

(The flags are described in @ref{227d,,Contenu du module}.)

The letters @code{'a'}, @code{'L'} and @code{'u'} are mutually exclusive when used
as inline flags, so they can't be combined or follow @code{'-'}.  Instead,
when one of them appears in an inline group, it overrides the matching mode
in the enclosing group.  In Unicode patterns @code{(?a:...)} switches to
ASCII-only matching, and @code{(?u:...)} switches to Unicode matching
(default).  In bytes patterns @code{(?L:...)} switches to locale dependent
matching, and @code{(?a:...)} switches to ASCII-only matching (default).
This override is only in effect for the narrow inline group, and the
original matching mode is restored outside of the group.


Ajouté dans la version 3.6.



Modifié dans la version 3.7: Les lettres @code{'a'}, @code{'L'} et @code{'u'} peuvent aussi être utilisées dans un groupe.


@item @code{(?>...)}

Attempts to match @code{...} as if it was a separate regular expression, and
if successful, continues to match the rest of the pattern following it.
If the subsequent pattern fails to match, the stack can only be unwound
to a point `before' the @code{(?>...)} because once exited, the expression,
known as an `atomic group', has thrown away all stack points within
itself.
Thus, @code{(?>.*).} would never match anything because first the @code{.*}
would match all characters possible, then, having nothing left to match,
the final @code{.} would fail to match.
Since there are no stack points saved in the Atomic Group, and there is
no stack point before it, the entire expression would thus fail to match.


Ajouté dans la version 3.11.

@end table

@geindex (?P<;in regular expressions


@table @asis

@item @code{(?P<name>...)}

Similar to regular parentheses, but the substring matched by the group is
accessible via the symbolic group name `name'.  Group names must be valid
Python identifiers, and in @ref{1bd,,bytes} patterns they can only contain
bytes in the ASCII range.  Each group name must be defined only once within
a regular expression.  A symbolic group is also a numbered group, just as if
the group were not named.

Les groupes nommés peuvent être référencés dans trois contextes. Si le motif est @code{(?P<quote>['"]).*?(?P=quote)} (c.-à-d. correspondant à une chaîne entourée de guillemets simples ou doubles) :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Contexte de référence au groupe `quote'

@tab

Manières de le référencer

@item

lui-même dans le même motif

@tab


@itemize *

@item 
@code{(?P=quote)} (comme vu)

@item 
@code{\1}
@end itemize

@item

en analysant l'objet résultat `m'

@tab


@itemize *

@item 
@code{m.group('quote')}

@item 
@code{m.end('quote')} (etc.)
@end itemize

@item

dans une chaîne passée à l'argument `repl' de @code{re.sub()}

@tab


@itemize *

@item 
@code{\g<quote>}

@item 
@code{\g<1>}

@item 
@code{\1}
@end itemize

@end multitable



Modifié dans la version 3.12: In @ref{1bd,,bytes} patterns, group `name' can only contain bytes
in the ASCII range (@code{b'\x00'}-@code{b'\x7f'}).

@end table

@geindex (?P=;in regular expressions


@table @asis

@item @code{(?P=name)}

Une référence arrière à un groupe nommé ; elle correspond à n'importe quel texte validé plus tôt par le groupe nommé `name'.
@end table

@geindex (?#;in regular expressions


@table @asis

@item @code{(?#...)}

Un commentaire ; le contenu des parenthèses est simplement ignoré.
@end table

@geindex (?=;in regular expressions


@table @asis

@item @code{(?=...)}

Valide si @code{...} valide la suite, mais ne consomme rien de la chaîne.  On appelle cela une assertion `lookahead'.  Par exemple, @code{Isaac (?=Asimov)} correspondra à la chaîne @code{'Isaac '} seulement si elle est suivie par @code{'Asimov'}.
@end table

@geindex (?!;in regular expressions


@table @asis

@item @code{(?!...)}

Valide si @code{...} ne valide pas la suite.  C'est une assertion `negative lookahead'. Par exemple, @code{Isaac (?!Asimov)} correspondra à la chaîne @code{'Isaac '} seulement si elle `n'est pas' suivie par @code{'Asimov'}.
@end table

@geindex (?<=;in regular expressions


@table @asis

@item @code{(?<=...)}

Valide si la position courante dans la chaîne est précédée par une correspondance sur @code{...} qui se termine à la position courante.  On appelle cela une `positive lookbehind assertion'. @code{(?<=abc)def} cherchera une correspondance dans @code{'abcdef'}, puisque le `lookbehind*' mettra de côté 3 caractères et vérifiera que le motif contenu correspond.  Le motif ne devra correspondre qu'à des chaînes de taille fixe, cela veut dire que @code{abc} ou @code{a|b} sont autorisées, mais pas @code{a*} ou @code{a@{3,4@}}.  Notez que les motifs qui commencent par des assertions `lookbehind' positives ne peuvent pas correspondre au début de la chaîne analysée ; vous préférerez sûrement utiliser la fonction @ref{120a,,search()} plutôt que la fonction @ref{120b,,match()} :

@example
>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'
@end example

Cet exemple recherche un mot suivi d'un trait d'union :

@example
>>> m = re.search(r'(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'
@end example


Modifié dans la version 3.5: Ajout du support des références aux groupes de taille fixe.

@end table

@geindex (?<!;in regular expressions


@table @asis

@item @code{(?<!...)}

Valide si la position courante dans la chaîne n'est pas précédée par une correspondance sur @code{...}.  On appelle cela une `negative lookbehind assertion'.  À la manière des assertions `lookbehind' positives, le motif contenu ne peut que correspondre à des chaînes de taille fixe.  Les motifs débutant par une assertion `lookbehind' négative peuvent correspondre au début de la chaîne analysée.
@end table

@geindex (?(;in regular expressions
@anchor{library/re re-conditional-expression}@anchor{173b}

@table @asis

@item @code{(?(id/name)yes-pattern|no-pattern)}

Essaiera de faire la correspondance avec @code{yes-pattern} si le groupe indiqué par `id' ou `name' existe, et avec @code{no-pattern} s'il n'existe pas. @code{no-pattern} est optionnel et peut être omis. Par exemple, @code{(<)?(\w+@@\w+(?:\.\w+)+)(?(1)>|$)} est un motif simpliste pour identifier une adresse courriel, qui validera @code{'<user@@host.com>'} ainsi que @code{'user@@host.com'} mais pas @code{'<user@@host.com'} ni @code{'user@@host.com>'}.


Modifié dans la version 3.12: Group `id' can only contain ASCII digits.
In @ref{1bd,,bytes} patterns, group `name' can only contain bytes
in the ASCII range (@code{b'\x00'}-@code{b'\x7f'}).

@end table
@anchor{library/re re-special-sequences}@anchor{227e}
Les séquences spéciales sont composées de @code{'\'} et d'un caractère de la liste qui suit. Si le caractère ordinaire n'est pas un chiffre `ASCII' ou une lettre `ASCII', alors l'expression rationnelle résultante validera le second caractère de la séquence.  Par exemple, @code{\$} correspond au caractère @code{'$'}.

@geindex \ (backslash);in regular expressions


@table @asis

@item @code{\number}

Correspond au contenu du groupe du même nombre. Les groupes sont numérotés à partir de 1.  Par exemple, @code{(.+) \1} correspond à @code{'the the'} ou @code{'55 55'}, mais pas à @code{'thethe'} (notez l'espace après le groupe).  Cette séquence spéciale ne peut être utilisée que pour faire référence aux 99 premiers groupes.  Si le premier chiffre de `number' est 0, ou si `number' est un nombre octal de 3 chiffres, il ne sera pas interprété comme une référence à un groupe, mais comme le caractère à la valeur octale `number'. À l'intérieur des @code{'['} et @code{']'} d'une classe de caractères, tous les échappements numériques sont traités comme des caractères.
@end table

@geindex \A;in regular expressions


@table @asis

@item @code{\A}

Correspond uniquement au début d'une chaîne de caractères.
@end table

@geindex \b;in regular expressions


@table @asis

@item @code{\b}

Matches the empty string, but only at the beginning or end of a word.
A word is defined as a sequence of word characters.
Note that formally, @code{\b} is defined as the boundary
between a @code{\w} and a @code{\W} character (or vice versa),
or between @code{\w} and the beginning or end of the string.
This means that @code{r'\bat\b'} matches @code{'at'}, @code{'at.'}, @code{'(at)'},
and @code{'as at ay'} but not @code{'attempt'} or @code{'atlas'}.

The default word characters in Unicode (str) patterns
are Unicode alphanumerics and the underscore,
but this can be changed by using the @ref{617,,ASCII} flag.
Word boundaries are determined by the current locale
if the @ref{b5a,,LOCALE} flag is used.

@cartouche
@quotation Note 
Inside a character range, @code{\b} represents the backspace character,
for compatibility with Python's string literals.
@end quotation
@end cartouche
@end table

@geindex \B;in regular expressions


@table @asis

@item @code{\B}

Matches the empty string,
but only when it is `not' at the beginning or end of a word.
This means that @code{r'at\B'} matches @code{'athens'}, @code{'atom'},
@code{'attorney'}, but not @code{'at'}, @code{'at.'}, or @code{'at!'}.
@code{\B} is the opposite of @code{\b},
so word characters in Unicode (str) patterns
are Unicode alphanumerics or the underscore,
although this can be changed by using the @ref{617,,ASCII} flag.
Word boundaries are determined by the current locale
if the @ref{b5a,,LOCALE} flag is used.

@cartouche
@quotation Note 
Note that @code{\B} does not match an empty string, which differs from
RE implementations in other programming languages such as Perl.
This behavior is kept for compatibility reasons.
@end quotation
@end cartouche
@end table

@geindex \d;in regular expressions


@table @asis

@item @code{\d}


@table @asis

@item Pour les motifs Unicode (`str') :

Matches any Unicode decimal digit
(that is, any character in Unicode character category [Nd]@footnote{https://www.unicode.org/versions/Unicode15.0.0/ch04.pdf#G134153}).
This includes @code{[0-9]}, and also many other digit characters.

Matches @code{[0-9]} if the @ref{617,,ASCII} flag is used.

@item Pour les motifs 8-bits (`bytes') :

Matches any decimal digit in the ASCII character set;
this is equivalent to @code{[0-9]}.
@end table
@end table

@geindex \D;in regular expressions


@table @asis

@item @code{\D}

Matches any character which is not a decimal digit.
This is the opposite of @code{\d}.

Matches @code{[^0-9]} if the @ref{617,,ASCII} flag is used.
@end table

@geindex \s;in regular expressions


@table @asis

@item @code{\s}


@table @asis

@item Pour les motifs Unicode (`str') :

Matches Unicode whitespace characters (as defined by @ref{214d,,str.isspace()}).
This includes @code{[ \t\n\r\f\v]}, and also many other characters, for example the
non-breaking spaces mandated by typography rules in many languages.

Matches @code{[ \t\n\r\f\v]} if the @ref{617,,ASCII} flag is used.

@item Pour les motifs 8-bits (`bytes') :

Valide les caractères considérés comme des espacements dans la table ASCII ; équivalent à @code{[ \t\n\r\f\v]}.
@end table
@end table

@geindex \S;in regular expressions


@table @asis

@item @code{\S}

Matches any character which is not a whitespace character. This is
the opposite of @code{\s}.

Matches @code{[^ \t\n\r\f\v]} if the @ref{617,,ASCII} flag is used.
@end table

@geindex \w;in regular expressions


@table @asis

@item @code{\w}


@table @asis

@item Pour les motifs Unicode (`str') :

Matches Unicode word characters;
this includes all Unicode alphanumeric characters
(as defined by @ref{2146,,str.isalnum()}),
as well as the underscore (@code{_}).

Matches @code{[a-zA-Z0-9_]} if the @ref{617,,ASCII} flag is used.

@item Pour les motifs 8-bits (`bytes') :

Matches characters considered alphanumeric in the ASCII character set;
this is equivalent to @code{[a-zA-Z0-9_]}.
If the @ref{b5a,,LOCALE} flag is used,
matches characters considered alphanumeric in the current locale and the underscore.
@end table
@end table

@geindex \W;in regular expressions


@table @asis

@item @code{\W}

Matches any character which is not a word character.
This is the opposite of @code{\w}.
By default, matches non-underscore (@code{_}) characters
for which @ref{2146,,str.isalnum()} returns @code{False}.

Matches @code{[^a-zA-Z0-9_]} if the @ref{617,,ASCII} flag is used.

If the @ref{b5a,,LOCALE} flag is used,
matches characters which are neither alphanumeric in the current locale
nor the underscore.
@end table

@geindex \Z;in regular expressions


@table @asis

@item @code{\Z}

Correspond uniquement à la fin d'une chaîne de caractères.
@end table

@geindex \a;in regular expressions
@geindex \b;in regular expressions
@geindex \f;in regular expressions
@geindex \n;in regular expressions
@geindex \N;in regular expressions
@geindex \r;in regular expressions
@geindex \t;in regular expressions
@geindex \u;in regular expressions
@geindex \U;in regular expressions
@geindex \v;in regular expressions
@geindex \x;in regular expressions
@geindex \\;in regular expressions

Most of the @ref{443,,escape sequences} supported by Python
string literals are also accepted by the regular expression parser:

@example
\a      \b      \f      \n
\N      \r      \t      \u
\U      \v      \x      \\
@end example

(Notez que @code{\b} est utilisé pour représenter les bornes d'un mot, et signifie « `retour arrière' » uniquement à l'intérieur d'une classe de caractères)

@code{'\u'}, @code{'\U'}, and @code{'\N'} escape sequences are
only recognized in Unicode (str) patterns.
In bytes patterns they are errors.
Unknown escapes of ASCII letters are reserved
for future use and treated as errors.

Les séquences octales d'échappement sont incluses dans une forme limitée.  Si le premier chiffre est un 0, ou s'il y a trois chiffres octaux, la séquence est considérée comme octale. Autrement, il s'agit d'une référence vers un groupe.  Comme pour les chaînes littérales, les séquences octales ne font jamais plus de 3 caractères de long.


Modifié dans la version 3.3: Les séquences d'échappement @code{'\u'} et @code{'\U'} ont été ajoutées.



Modifié dans la version 3.6: Les séquences inconnues composées de @code{'\'} et d'une lettre ASCII sont maintenant des erreurs.



Modifié dans la version 3.8: The @code{'\N@{@var{name}@}'} escape sequence has been added. As in string literals,
it expands to the named Unicode character (e.g. @code{'\N@{EM DASH@}'}).


@node Contenu du module,Objets d'expressions rationnelles,Syntaxe des expressions rationnelles,re --- Regular expression operations
@anchor{library/re contents-of-module-re}@anchor{227d}@anchor{library/re module-contents}@anchor{227f}
@subsubsection Contenu du module


Le module définit plusieurs fonctions, constantes, et une exception. Certaines fonctions sont des versions simplifiées des méthodes plus complètes des expressions rationnelles compilées.  La plupart des applications non triviales utilisent toujours la version compilée.

@menu
* Flags:: 
* Fonctions: Fonctions<2>. 
* Exceptions: Exceptions<3>. 

@end menu

@node Flags,Fonctions<2>,,Contenu du module
@anchor{library/re flags}@anchor{2275}
@subsubsection Flags



Modifié dans la version 3.6: Les constantes d'options sont maintenant des instances de @ref{618,,RegexFlag}, sous-classe de @ref{2280,,enum.IntFlag}.


@geindex RegexFlag (classe dans re)
@anchor{library/re re RegexFlag}@anchor{618}
@deffn {Classe} re.RegexFlag

An @ref{2280,,enum.IntFlag} class containing the regex options listed below.


Ajouté dans la version 3.11: - added to @code{__all__}

@end deffn

@geindex A (dans le module re)
@geindex ASCII (dans le module re)
@anchor{library/re re A}@anchor{2276}
@deffn {Données} re.A
@anchor{library/re re ASCII}@anchor{617}
@deffnx {Données} re.ASCII

Make @code{\w}, @code{\W}, @code{\b}, @code{\B}, @code{\d}, @code{\D}, @code{\s} and @code{\S}
perform ASCII-only matching instead of full Unicode matching.  This is only
meaningful for Unicode (str) patterns, and is ignored for bytes patterns.

Corresponds to the inline flag @code{(?a)}.

@cartouche
@quotation Note 
The @ref{227b,,U} flag still exists for backward compatibility,
but is redundant in Python 3 since
matches are Unicode by default for @code{str} patterns,
and Unicode matching isn't allowed for bytes patterns.
@ref{b5b,,UNICODE} and the inline flag @code{(?u)} are similarly redundant.
@end quotation
@end cartouche
@end deffn

@geindex DEBUG (dans le module re)
@anchor{library/re re DEBUG}@anchor{2281}
@deffn {Données} re.DEBUG

Display debug information about compiled expression.

No corresponding inline flag.
@end deffn

@geindex I (dans le module re)
@geindex IGNORECASE (dans le module re)
@anchor{library/re re I}@anchor{2277}
@deffn {Données} re.I
@anchor{library/re re IGNORECASE}@anchor{16b0}
@deffnx {Données} re.IGNORECASE

Perform case-insensitive matching;
expressions like @code{[A-Z]} will also  match lowercase letters.
Full Unicode matching (such as @code{Ü} matching @code{ü})
also works unless the @ref{617,,ASCII} flag
is used to disable non-ASCII matches.
The current locale does not change the effect of this flag
unless the @ref{b5a,,LOCALE} flag is also used.

Corresponds to the inline flag @code{(?i)}.

Note that when the Unicode patterns @code{[a-z]} or @code{[A-Z]} are used in
combination with the @ref{16b0,,IGNORECASE} flag, they will match the 52 ASCII
letters and 4 additional non-ASCII letters: 'İ' (U+0130, Latin capital
letter I with dot above), 'ı' (U+0131, Latin small letter dotless i),
'ſ' (U+017F, Latin small letter long s) and 'K' (U+212A, Kelvin sign).
If the @ref{617,,ASCII} flag is used, only letters 'a' to 'z'
and 'A' to 'Z' are matched.
@end deffn

@geindex L (dans le module re)
@geindex LOCALE (dans le module re)
@anchor{library/re re L}@anchor{2278}
@deffn {Données} re.L
@anchor{library/re re LOCALE}@anchor{b5a}
@deffnx {Données} re.LOCALE

Make @code{\w}, @code{\W}, @code{\b}, @code{\B} and case-insensitive matching
dependent on the current locale.
This flag can be used only with bytes patterns.

Corresponds to the inline flag @code{(?L)}.

@cartouche
@quotation Avertissement 
This flag is discouraged; consider Unicode matching instead.
The locale mechanism is very unreliable
as it only handles one "culture" at a time
and only works with 8-bit locales.
Unicode matching is enabled by default for Unicode (str) patterns
and it is able to handle different locales and languages.
@end quotation
@end cartouche


Modifié dans la version 3.6: @ref{b5a,,LOCALE} can be used only with bytes patterns
and is not compatible with @ref{617,,ASCII}.



Modifié dans la version 3.7: Compiled regular expression objects with the @ref{b5a,,LOCALE} flag
no longer depend on the locale at compile time.
Only the locale at matching time affects the result of matching.

@end deffn

@geindex M (dans le module re)
@geindex MULTILINE (dans le module re)
@anchor{library/re re M}@anchor{2279}
@deffn {Données} re.M
@anchor{library/re re MULTILINE}@anchor{2274}
@deffnx {Données} re.MULTILINE

When specified, the pattern character @code{'^'} matches at the beginning of the
string and at the beginning of each line (immediately following each newline);
and the pattern character @code{'$'} matches at the end of the string and at the
end of each line (immediately preceding each newline).  By default, @code{'^'}
matches only at the beginning of the string, and @code{'$'} only at the end of the
string and immediately before the newline (if any) at the end of the string.

Corresponds to the inline flag @code{(?m)}.
@end deffn

@geindex NOFLAG (dans le module re)
@anchor{library/re re NOFLAG}@anchor{2282}
@deffn {Données} re.NOFLAG

Indicates no flag being applied, the value is @code{0}.  This flag may be used
as a default value for a function keyword argument or as a base value that
will be conditionally ORed with other flags.  Example of use as a default
value:

@example
def myfunc(text, flag=re.NOFLAG):
    return re.match(text, flag)
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex S (dans le module re)
@geindex DOTALL (dans le module re)
@anchor{library/re re S}@anchor{227a}
@deffn {Données} re.S
@anchor{library/re re DOTALL}@anchor{2273}
@deffnx {Données} re.DOTALL

Make the @code{'.'} special character match any character at all, including a
newline; without this flag, @code{'.'} will match anything `except' a newline.

Corresponds to the inline flag @code{(?s)}.
@end deffn

@geindex U (dans le module re)
@geindex UNICODE (dans le module re)
@anchor{library/re re U}@anchor{227b}
@deffn {Données} re.U
@anchor{library/re re UNICODE}@anchor{b5b}
@deffnx {Données} re.UNICODE

In Python 3, Unicode characters are matched by default
for @code{str} patterns.
This flag is therefore redundant with `no effect'
and is only kept for backward compatibility.

See @ref{617,,ASCII} to restrict matching to ASCII characters instead.
@end deffn

@geindex X (dans le module re)
@geindex VERBOSE (dans le module re)
@anchor{library/re re X}@anchor{227c}
@deffn {Données} re.X
@anchor{library/re re VERBOSE}@anchor{2283}
@deffnx {Données} re.VERBOSE

@geindex # (hash);in regular expressions

Cette option vous autorise à écrire des expressions rationnelles qui présentent mieux et sont plus lisibles en vous permettant de séparer visuellement les sections logiques du motif et d'ajouter des commentaires. Les caractères d'espacement à l'intérieur du motif sont ignorés, sauf à l'intérieur des classes de caractères ou quand ils sont précédés d'un `backslash' non échappé, ou dans des séquences comme @code{*?}, @code{(?:} ou @code{(?P<...>}.Par exemple, @code{(? :} et @code{* ?} ne sont pas autorisés. Quand une ligne contient un @code{#} qui n'est ni dans une classe de caractères, ni précédé d'un `backslash' non échappé, tous les caractères depuis le @code{#} le plus à gauche jusqu'à la fin de la ligne sont ignorés.

Cela signifie que les deux expressions rationnelles suivantes qui valident un nombre décimal sont fonctionnellement égales :

@example
a = re.compile(r"""\d +  # the integral part
                   \.    # the decimal point
                   \d *  # some fractional digits""", re.X)
b = re.compile(r"\d+\.\d*")
@end example

Correspond à l'option de groupe @code{(?x)}.
@end deffn

@node Fonctions<2>,Exceptions<3>,Flags,Contenu du module
@anchor{library/re functions}@anchor{2284}
@subsubsection Fonctions


@geindex compile() (dans le module re)
@anchor{library/re re compile}@anchor{bc1}
@deffn {Fonction} re.compile (pattern, flags=0)

Compile un motif vers une @ref{f71,,expression rationnelle} compilée, dont les méthodes @ref{2285,,match()} et @ref{2286,,search()}, décrites ci-dessous, peuvent être utilisées pour analyser des textes.

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).

La séquence

@example
prog = re.compile(pattern)
result = prog.match(string)
@end example

est équivalente à

@example
result = re.match(pattern, string)
@end example

mais utiliser @ref{bc1,,re.compile()} et sauvegarder l'expression rationnelle renvoyée pour la réutiliser est plus efficace quand l'expression est amenée à être utilisée plusieurs fois dans un même programme.

@cartouche
@quotation Note 
Les versions compilées des motifs les plus récents passés à @ref{bc1,,re.compile()} et autres fonctions d'analyse du module sont mises en cache, ainsi les programmes qui n'utilisent que quelques expressions rationnelles en même temps n'ont pas à s'inquiéter de la compilation de ces expressions.
@end quotation
@end cartouche
@end deffn

@geindex search() (dans le module re)
@anchor{library/re re search}@anchor{120a}
@deffn {Fonction} re.search (pattern, string, flags=0)

Scan through `string' looking for the first location where the regular expression
`pattern' produces a match, and return a corresponding @ref{cb6,,Match}. Return
@code{None} if no position in the string matches the pattern; note that this is
different from finding a zero-length match at some point in the string.

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).
@end deffn

@geindex match() (dans le module re)
@anchor{library/re re match}@anchor{120b}
@deffn {Fonction} re.match (pattern, string, flags=0)

If zero or more characters at the beginning of `string' match the regular
expression `pattern', return a corresponding @ref{cb6,,Match}.  Return
@code{None} if the string does not match the pattern; note that this is
different from a zero-length match.

Notez que même en mode @ref{2274,,MULTILINE}, @ref{120b,,re.match()} ne validera qu'au début de la chaîne et non au début de chaque ligne.

Si vous voulez trouver une correspondance n'importe où dans `string', utilisez plutôt @ref{120a,,search()} (voir aussi @ref{2287,,Comparaison de search() et match()}).

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).
@end deffn

@geindex fullmatch() (dans le module re)
@anchor{library/re re fullmatch}@anchor{f70}
@deffn {Fonction} re.fullmatch (pattern, string, flags=0)

If the whole `string' matches the regular expression `pattern', return a
corresponding @ref{cb6,,Match}.  Return @code{None} if the string does not match
the pattern; note that this is different from a zero-length match.

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Ajouté dans la version 3.4.

@end deffn

@geindex split() (dans le module re)
@anchor{library/re re split}@anchor{29f}
@deffn {Fonction} re.split (pattern, string, maxsplit=0, flags=0)

Sépare `string' selon les occurrences de `pattern'.  Si des parenthèses de capture sont utilisées dans `pattern', alors les textes des groupes du motif sont aussi renvoyés comme éléments de la liste résultante. Si `maxsplit' est différent de zéro, il ne pourra y avoir plus de `maxsplit' séparations, et le reste de la chaîne sera renvoyé comme le dernier élément de la liste.

@example
>>> re.split(r'\W+', 'Words, words, words.')
['Words', 'words', 'words', '@w{'}]
>>> re.split(r'(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '@w{'}]
>>> re.split(r'\W+', 'Words, words, words.', maxsplit=1)
['Words', 'words, words.']
>>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)
['0', '3', '9']
@end example

S'il y a des groupes de capture dans le séparateur et qu'ils trouvent une correspondance au début de la chaîne, le résultat commencera par une chaîne vide.  La même chose se produit pour la fin de la chaîne :

@example
>>> re.split(r'(\W+)', '...words, words...')
['@w{'}, '...', 'words', ', ', 'words', '...', '@w{'}]
@end example

De cette manière, les séparateurs sont toujours trouvés aux mêmes indices relatifs dans la liste résultante.

Les correspondances vides pour le motif scindent la chaîne de caractères seulement lorsqu'ils ne sont pas adjacents à une correspondance vide précédente.

@example
>>> re.split(r'\b', 'Words, words, words.')
['@w{'}, 'Words', ', ', 'words', ', ', 'words', '.']
>>> re.split(r'\W*', '...words...')
['@w{'}, '@w{'}, 'w', 'o', 'r', 'd', 's', '@w{'}, '@w{'}]
>>> re.split(r'(\W*)', '...words...')
['@w{'}, '...', '@w{'}, '@w{'}, 'w', '@w{'}, 'o', '@w{'}, 'r', '@w{'}, 'd', '@w{'}, 's', '...', '@w{'}, '@w{'}, '@w{'}]
@end example

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Modifié dans la version 3.1: ajout de l'argument optionnel `flags'.



Modifié dans la version 3.7: Gestion du découpage avec un motif qui pourrait correspondre à une chaine de caractère vide.



Obsolète depuis la version 3.13: Passing `maxsplit' and `flags' as positional arguments is deprecated.
In future Python versions they will be
@ref{2a2,,keyword-only parameters}.

@end deffn

@geindex findall() (dans le module re)
@anchor{library/re re findall}@anchor{1013}
@deffn {Fonction} re.findall (pattern, string, flags=0)

Renvoie toutes les correspondances, sans chevauchements, entre le motif `pattern' et la chaîne `string', comme une liste de chaînes ou de `n'-uplets.  La chaîne `string' est examinée de gauche à droite, et les correspondances sont données dans cet ordre. Le résultat peut contenir des correspondances vides.

Le type du résultat dépend du nombre de groupes capturants dans le motif. S'il n'y en a pas, le résultat est une liste de sous-chaînes de caractères qui correspondent au motif.  S'il y a exactement un groupe, le résultat est une liste constituée des sous-chaînes qui correspondaient à ce groupe pour chaque correspondance entre le motif et la chaîne.  S'il y a plusieurs groupes, le résultat est formé de `n'-uplets avec les sous-chaînes correspondant aux différents groupes.

@example
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.findall(r'(\w+)=(\d+)', 'set width=20 and height=10')
[('width', '20'), ('height', '10')]
@end example

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Modifié dans la version 3.7: Les correspondances non vides peuvent maintenant démarrer juste après une correspondance vide précédente.

@end deffn

@geindex finditer() (dans le module re)
@anchor{library/re re finditer}@anchor{14b0}
@deffn {Fonction} re.finditer (pattern, string, flags=0)

Return an @ref{1aa,,iterator} yielding @ref{cb6,,Match} objects over
all non-overlapping matches for the RE `pattern' in `string'.  The `string'
is scanned left-to-right, and matches are returned in the order found.  Empty
matches are included in the result.

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Modifié dans la version 3.7: Les correspondances non vides peuvent maintenant démarrer juste après une correspondance vide précédente.

@end deffn

@geindex sub() (dans le module re)
@anchor{library/re re sub}@anchor{2a0}
@deffn {Fonction} re.sub (pattern, repl, string, count=0, flags=0)

Renvoie la chaîne obtenue en remplaçant les occurrences (sans chevauchement) les plus à gauche de `pattern' dans `string' par le remplacement `repl'.  Si le motif n'est pas trouvé, `string' est renvoyée inchangée.  `repl' peut être une chaîne de caractères ou une fonction ; si c'est une chaîne, toutes les séquences d'échappement qu'elle contient sont traduites.  Ainsi, @code{\n} est convertie en un simple saut de ligne, @code{\r} en un retour chariot, et ainsi de suite.  Les échappements inconnus de lettres ASCII sont réservés pour une utilisation future et sont considérés comme des erreurs. Les autres échappements tels que @code{\&} sont laissés intacts. Les références arrières, telles que @code{\6}, sont remplacées par la sous-chaîne correspondant au groupe 6 dans le motif. Par exemple :

@example
>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
...        r'static PyObject*\npy_\1(void)\n@{',
...        'def myfunc():')
'static PyObject*\npy_myfunc(void)\n@{'
@end example

If `repl' is a function, it is called for every non-overlapping occurrence of
`pattern'.  The function takes a single @ref{cb6,,Match} argument, and returns
the replacement string.  For example:

@example
>>> def dashrepl(matchobj):
...     if matchobj.group(0) == '-': return ' '
...     else: return '-'
...
>>> re.sub('-@{1,2@}', dashrepl, 'pro----gram-files')
'pro--gram files'
>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
'Baked Beans & Spam'
@end example

The pattern may be a string or a @ref{176b,,Pattern}.

L'argument optionnel `count' est le nombre maximum d'occurrences du motif à remplacer : `count' ne doit pas être un nombre négatif.  Si omis ou nul, toutes les occurrences seront remplacées. Les correspondances vides avec le motif sont remplacées uniquement quand elles ne sont pas adjacentes à une précédente correspondance, ainsi @code{sub('x*', '-', 'abxd')} renvoie @code{'-a-b--d-'}.

@geindex \g;in regular expressions

Dans les arguments `repl' de type `string', en plus des séquences d'échappement et références arrières décrites au-dessus, @code{\g<name>} utilisera la sous-chaîne correspondant au groupe nommé @code{name}, comme défini par la syntaxe @code{(?P<name>...)}. @code{\g<number>} utilise le groupe numéroté associé ; @code{\g<2>} est ainsi équivalent à @code{\2}, mais n'est pas ambigu dans un remplacement tel que @code{\g<2>0}, @code{\20} serait interprété comme une référence au groupe 20, et non une référence au groupe 2 suivie par un caractère littéral @code{'0'}.  La référence arrière @code{\g<0>} est remplacée par la sous-chaîne entière validée par l'expression rationnelle.

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).


Modifié dans la version 3.1: ajout de l'argument optionnel `flags'.



Modifié dans la version 3.5: Les groupes sans correspondance sont remplacés par une chaîne vide.



Modifié dans la version 3.6: Les séquences d'échappement inconnues dans `pattern' formées par @code{'\'} et une lettre ASCII sont maintenant des erreurs.



Modifié dans la version 3.7: Unknown escapes in `repl' consisting of @code{'\'} and an ASCII letter
now are errors.
Empty matches for the pattern are replaced when adjacent to a previous
non-empty match.



Modifié dans la version 3.12: Group `id' can only contain ASCII digits.
In @ref{1bd,,bytes} replacement strings, group `name' can only contain bytes
in the ASCII range (@code{b'\x00'}-@code{b'\x7f'}).



Obsolète depuis la version 3.13: Passing `count' and `flags' as positional arguments is deprecated.
In future Python versions they will be
@ref{2a2,,keyword-only parameters}.

@end deffn

@geindex subn() (dans le module re)
@anchor{library/re re subn}@anchor{2a1}
@deffn {Fonction} re.subn (pattern, repl, string, count=0, flags=0)

Réalise la même opération que @ref{2a0,,sub()}, mais renvoie une paire @code{(nouvelle_chaîne, nombre_de_substitutions_réalisées)}.

The expression's behaviour can be modified by specifying a `flags' value.
Values can be any of the @ref{2275,,flags} variables, combined using bitwise OR
(the @code{|} operator).
@end deffn

@geindex escape() (dans le module re)
@anchor{library/re re escape}@anchor{bf7}
@deffn {Fonction} re.escape (pattern)

Échappe tous les caractères spéciaux de `pattern'. Cela est utile si vous voulez valider une quelconque chaîne littérale qui pourrait contenir des métacaractères d'expressions rationnelles.  Par exemple :

@example
>>> print(re.escape('https://www.python.org'))
https://www\.python\.org

>>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:"
>>> print('[%s]+' % re.escape(legal_chars))
[abcdefghijklmnopqrstuvwxyz0123456789!\#\$%\&'\*\+\-\.\^_`\|\~:]+

>>> operators = ['+', '-', '*', '/', '**']
>>> print('|'.join(map(re.escape, sorted(operators, reverse=True))))
/|\-|\+|\*\*|\*
@end example

Cette fonction ne doit pas être utilisée pour la chaîne de remplacement dans @ref{2a0,,sub()} et @ref{2a1,,subn()}, seuls les antislashs devraient être échappés. Par exemple :

@example
>>> digits_re = r'\d+'
>>> sample = '/usr/sbin/sendmail - 0 errors, 12 warnings'
>>> print(re.sub(digits_re, digits_re.replace('\\', r'\\'), sample))
/usr/sbin/sendmail - \d+ errors, \d+ warnings
@end example


Modifié dans la version 3.3: Le caractère @code{'_'} n'est plus échappé.



Modifié dans la version 3.7: Seuls les caractères qui peuvent avoir une signification spéciale dans une expression rationnelle sont échappés. De ce fait, @code{'!'}, @code{'"'}, @code{'%'}, @code{"'"}, @code{','}, @code{'/'}, @code{':'}, @code{';'}, @code{'<'}, @code{'='}, @code{'>'}, @code{'@@'}, et @code{"`"} ne sont plus échappés.

@end deffn

@geindex purge() (dans le module re)
@anchor{library/re re purge}@anchor{2288}
@deffn {Fonction} re.purge ()

Vide le cache d'expressions rationnelles.
@end deffn

@node Exceptions<3>,,Fonctions<2>,Contenu du module
@anchor{library/re exceptions}@anchor{2289}
@subsubsection Exceptions


@geindex PatternError
@anchor{library/re re PatternError}@anchor{23b}
@deffn {Exception} re.PatternError (msg, pattern=None, pos=None)

Exception raised when a string passed to one of the functions here is not a
valid regular expression (for example, it might contain unmatched parentheses)
or when some other error occurs during compilation or matching.  It is never an
error if a string contains no match for a pattern.  The @code{PatternError} instance has
the following additional attributes:

@geindex msg (attribut re.PatternError)
@anchor{library/re re PatternError msg}@anchor{228a}
@deffn {Attribut} msg

Le message d'erreur non formaté.
@end deffn

@geindex pattern (attribut re.PatternError)
@anchor{library/re re PatternError pattern}@anchor{228b}
@deffn {Attribut} pattern

Le motif d'expression rationnelle.
@end deffn

@geindex pos (attribut re.PatternError)
@anchor{library/re re PatternError pos}@anchor{228c}
@deffn {Attribut} pos

L'index dans `pattern' où la compilation a échoué (peut valoir @code{None}).
@end deffn

@geindex lineno (attribut re.PatternError)
@anchor{library/re re PatternError lineno}@anchor{228d}
@deffn {Attribut} lineno

La ligne correspondant à `pos' (peut valoir @code{None}).
@end deffn

@geindex colno (attribut re.PatternError)
@anchor{library/re re PatternError colno}@anchor{228e}
@deffn {Attribut} colno

La colonne correspondant à `pos' (peut valoir @code{None}).
@end deffn


Modifié dans la version 3.5: Ajout des attributs additionnels.



Modifié dans la version 3.13: @code{PatternError} was originally named @code{error}; the latter is kept as an alias for
backward compatibility.

@end deffn

@node Objets d'expressions rationnelles,Objets de correspondance,Contenu du module,re --- Regular expression operations
@anchor{library/re re-objects}@anchor{f71}@anchor{library/re regular-expression-objects}@anchor{228f}
@subsubsection Objets d'expressions rationnelles


@geindex Pattern (classe dans re)
@anchor{library/re re Pattern}@anchor{176b}
@deffn {Classe} re.Pattern

Compiled regular expression object returned by @ref{bc1,,re.compile()}.


Modifié dans la version 3.9: @ref{176b,,re.Pattern} supports @code{[]} to indicate a Unicode (str) or bytes pattern.
See @ref{69d,,Type Alias générique}.

@end deffn

@geindex search() (méthode re.Pattern)
@anchor{library/re re Pattern search}@anchor{2286}
@deffn {Méthode} Pattern.search (string[, pos[, endpos]])

Scan through `string' looking for the first location where this regular
expression produces a match, and return a corresponding @ref{cb6,,Match}.
Return @code{None} if no position in the string matches the pattern; note that
this is different from finding a zero-length match at some point in the string.

Le second paramètre `pos' (optionnel) donne l'index dans la chaîne où la recherche doit débuter ; il vaut @code{0} par défaut.  Cela n'est pas complètement équivalent à un `slicing' sur la chaîne ; le caractère de motif @code{'^'} correspond au début réel de la chaîne et aux positions juste après un saut de ligne, mais pas nécessairement à l'index où la recherche commence.

Le paramètre optionnel `endpos' limite la longueur sur laquelle la chaîne sera analysée ; ce sera comme si la chaîne faisait `endpos' caractères de long, donc uniquement les caractères de `pos' à @code{endpos - 1} seront analysés pour trouver une correspondance.  Si `endpos' est inférieur à `pos', aucune correspondance ne sera trouvée ; dit autrement, avec `rx' une expression rationnelle compilée, @code{rx.search(string, 0, 50)} est équivalent à @code{rx.search(string[:50], 0)}.

@example
>>> pattern = re.compile("d")
>>> pattern.search("dog")     # Match at index 0
<re.Match object; span=(0, 1), match='d'>
>>> pattern.search("dog", 1)  # No match; search doesn't include the "d"
@end example
@end deffn

@geindex match() (méthode re.Pattern)
@anchor{library/re re Pattern match}@anchor{2285}
@deffn {Méthode} Pattern.match (string[, pos[, endpos]])

If zero or more characters at the `beginning' of `string' match this regular
expression, return a corresponding @ref{cb6,,Match}. Return @code{None} if the
string does not match the pattern; note that this is different from a
zero-length match.

Les paramètres optionnels `pos' et `endpos' ont le même sens que pour la méthode @ref{2286,,search()}.

@example
>>> pattern = re.compile("o")
>>> pattern.match("dog")      # No match as "o" is not at the start of "dog".
>>> pattern.match("dog", 1)   # Match as "o" is the 2nd character of "dog".
<re.Match object; span=(1, 2), match='o'>
@end example

Si vous voulez une recherche n'importe où dans `string', utilisez plutôt @ref{2286,,search()} (voir aussi @ref{2287,,Comparaison de search() et match()}).
@end deffn

@geindex fullmatch() (méthode re.Pattern)
@anchor{library/re re Pattern fullmatch}@anchor{1791}
@deffn {Méthode} Pattern.fullmatch (string[, pos[, endpos]])

If the whole `string' matches this regular expression, return a corresponding
@ref{cb6,,Match}.  Return @code{None} if the string does not match the pattern;
note that this is different from a zero-length match.

Les paramètres optionnels `pos' et `endpos' ont le même sens que pour la méthode @ref{2286,,search()}.

@example
>>> pattern = re.compile("o[gh]")
>>> pattern.fullmatch("dog")      # No match as "o" is not at the start of "dog".
>>> pattern.fullmatch("ogre")     # No match as not the full string matches.
>>> pattern.fullmatch("doggie", 1, 3)   # Matches within given limits.
<re.Match object; span=(1, 3), match='og'>
@end example


Ajouté dans la version 3.4.

@end deffn

@geindex split() (méthode re.Pattern)
@anchor{library/re re Pattern split}@anchor{2290}
@deffn {Méthode} Pattern.split (string, maxsplit=0)

Identique à la fonction @ref{29f,,split()}, en utilisant le motif compilé.
@end deffn

@geindex findall() (méthode re.Pattern)
@anchor{library/re re Pattern findall}@anchor{2291}
@deffn {Méthode} Pattern.findall (string[, pos[, endpos]])

Similaire à la fonction @ref{1013,,findall()}, en utilisant le motif compilé, mais accepte aussi des paramètres `pos' et `endpos' optionnels qui limitent la région de recherche comme pour @ref{120a,,search()}.
@end deffn

@geindex finditer() (méthode re.Pattern)
@anchor{library/re re Pattern finditer}@anchor{2292}
@deffn {Méthode} Pattern.finditer (string[, pos[, endpos]])

Similaire à la fonction @ref{14b0,,finditer()}, en utilisant le motif compilé, mais accepte aussi des paramètres `pos' et `endpos' optionnels qui limitent la région de recherche comme pour @ref{120a,,search()}.
@end deffn

@geindex sub() (méthode re.Pattern)
@anchor{library/re re Pattern sub}@anchor{2293}
@deffn {Méthode} Pattern.sub (repl, string, count=0)

Identique à la fonction @ref{2a0,,sub()}, en utilisant le motif compilé.
@end deffn

@geindex subn() (méthode re.Pattern)
@anchor{library/re re Pattern subn}@anchor{2294}
@deffn {Méthode} Pattern.subn (repl, string, count=0)

Identique à la fonction @ref{2a1,,subn()}, en utilisant le motif compilé.
@end deffn

@geindex flags (attribut re.Pattern)
@anchor{library/re re Pattern flags}@anchor{2295}
@deffn {Attribut} Pattern.flags

The regex matching flags.  This is a combination of the flags given to
@ref{bc1,,compile()}, any @code{(?...)} inline flags in the pattern, and implicit
flags such as @ref{b5b,,UNICODE} if the pattern is a Unicode string.
@end deffn

@geindex groups (attribut re.Pattern)
@anchor{library/re re Pattern groups}@anchor{2296}
@deffn {Attribut} Pattern.groups

Le nombre de groupes de capture dans le motif.
@end deffn

@geindex groupindex (attribut re.Pattern)
@anchor{library/re re Pattern groupindex}@anchor{2297}
@deffn {Attribut} Pattern.groupindex

Un dictionnaire associant les noms de groupes symboliques définis par @code{(?P<id>)} aux groupes numérotés.  Le dictionnaire est vide si aucun groupe symbolique n'est utilisé dans le motif.
@end deffn

@geindex pattern (attribut re.Pattern)
@anchor{library/re re Pattern pattern}@anchor{2298}
@deffn {Attribut} Pattern.pattern

La chaîne de motif depuis laquelle l'objet motif a été compilé.
@end deffn


Modifié dans la version 3.7: Ajout du support des fonctions @ref{51d,,copy.copy()} et @ref{b5c,,copy.deepcopy()}. Les expressions régulières compilées sont considérées atomiques.


@node Objets de correspondance,Exemples d'expressions rationnelles,Objets d'expressions rationnelles,re --- Regular expression operations
@anchor{library/re id3}@anchor{2299}@anchor{library/re match-objects}@anchor{f72}
@subsubsection Objets de correspondance


Les objets de correspondance ont toujours une valeur booléenne @code{True}. Puisque @ref{2285,,match()} et @ref{2286,,search()} renvoient @code{None} quand il n'y a pas de correspondance, vous pouvez tester s'il y a eu correspondance avec une simple instruction @code{if} :

@example
match = re.search(pattern, string)
if match:
    process(match)
@end example

@geindex Match (classe dans re)
@anchor{library/re re Match}@anchor{cb6}
@deffn {Classe} re.Match

Match object returned by successful @code{match}es and @code{search}es.


Modifié dans la version 3.9: @ref{cb6,,re.Match} supports @code{[]} to indicate a Unicode (str) or bytes match.
See @ref{69d,,Type Alias générique}.

@end deffn

@geindex expand() (méthode re.Match)
@anchor{library/re re Match expand}@anchor{229a}
@deffn {Méthode} Match.expand (template)

Return the string obtained by doing backslash substitution on the template
string `template', as done by the @ref{2293,,sub()} method.
Escapes such as @code{\n} are converted to the appropriate characters,
and numeric backreferences (@code{\1}, @code{\2}) and named backreferences
(@code{\g<1>}, @code{\g<name>}) are replaced by the contents of the
corresponding group. The backreference @code{\g<0>} will be
replaced by the entire match.


Modifié dans la version 3.5: Les groupes sans correspondance sont remplacés par une chaîne vide.

@end deffn

@geindex group() (méthode re.Match)
@anchor{library/re re Match group}@anchor{229b}
@deffn {Méthode} Match.group ([group1, ...])

Renvoie un ou plus sous-groupes de la correspondance.  Si un seul argument est donné, le résultat est une chaîne simple ; s'il y a plusieurs arguments, le résultat est un `n'-uplet comprenant un élément par argument. Sans arguments, `group1' vaut par défaut zéro (la correspondance entière est renvoyée). Si un argument `groupN' vaut zéro, l'élément associé sera la chaîne de correspondance entière ; s'il est dans l'intervalle fermé [1..99], c'est la correspondance avec le groupe de parenthèses associé.  Si un numéro de groupe est négatif ou supérieur au nombre de groupes définis dans le motif, une exception @code{indexError} est levée. Si un groupe est contenu dans une partie du motif qui n'a aucune correspondance, l'élément associé sera @code{None}. Si un groupe est contenu dans une partie du motif qui a plusieurs correspondances, seule la dernière correspondance est renvoyée.

@example
>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m.group(0)       # The entire match
'Isaac Newton'
>>> m.group(1)       # The first parenthesized subgroup.
'Isaac'
>>> m.group(2)       # The second parenthesized subgroup.
'Newton'
>>> m.group(1, 2)    # Multiple arguments give us a tuple.
('Isaac', 'Newton')
@end example

Si l'expression rationnelle utilise la syntaxe @code{(?P<name>...)}, les arguments `groupN' peuvent alors aussi être des chaînes identifiant les groupes par leurs noms.  Si une chaîne donnée en argument n'est pas utilisée comme nom de groupe dans le motif, une exception @ref{14eb,,IndexError} est levée.

Un exemple modérément compliqué :

@example
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.group('first_name')
'Malcolm'
>>> m.group('last_name')
'Reynolds'
@end example

Les groupes nommés peuvent aussi être référencés par leur index :

@example
>>> m.group(1)
'Malcolm'
>>> m.group(2)
'Reynolds'
@end example

Si un groupe a plusieurs correspondances, seule la dernière est accessible :

@example
>>> m = re.match(r"(..)+", "a1b2c3")  # Matches 3 times.
>>> m.group(1)                        # Returns only the last match.
'c3'
@end example
@end deffn

@geindex __getitem__() (méthode re.Match)
@anchor{library/re re Match __getitem__}@anchor{229c}
@deffn {Méthode} Match.__getitem__ (g)

Cela est identique à @code{m.group(g)}.  Cela permet un accès plus facile à un groupe individuel depuis une correspondance :

@example
>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m[0]       # The entire match
'Isaac Newton'
>>> m[1]       # The first parenthesized subgroup.
'Isaac'
>>> m[2]       # The second parenthesized subgroup.
'Newton'
@end example

Named groups are supported as well:

@example
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Isaac Newton")
>>> m['first_name']
'Isaac'
>>> m['last_name']
'Newton'
@end example


Ajouté dans la version 3.6.

@end deffn

@geindex groups() (méthode re.Match)
@anchor{library/re re Match groups}@anchor{229d}
@deffn {Méthode} Match.groups (default=None)

Renvoie un `n'-uplet contenant tous les sous-groupes de la correspondance, de 1 jusqu'au nombre de groupes dans le motif.  L'argument `default' est utilisé pour les groupes sans correspondance ; il vaut @code{None} par défaut.

Par exemple :

@example
>>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
>>> m.groups()
('24', '1632')
@end example

Si on rend la partie décimale et tout ce qui la suit optionnels, tous les groupes ne figureront pas dans la correspondance.  Ces groupes sans correspondance vaudront @code{None} sauf si une autre valeur est donnée à l'argument `default' :

@example
>>> m = re.match(r"(\d+)\.?(\d+)?", "24")
>>> m.groups()      # Second group defaults to None.
('24', None)
>>> m.groups('0')   # Now, the second group defaults to '0'.
('24', '0')
@end example
@end deffn

@geindex groupdict() (méthode re.Match)
@anchor{library/re re Match groupdict}@anchor{229e}
@deffn {Méthode} Match.groupdict (default=None)

Renvoie un dictionnaire contenant tous les sous-groupes `nommés' de la correspondance, accessibles par leurs noms.  L'argument `default' est utilisé pour les groupes qui ne figurent pas dans la correspondance ; il vaut @code{None} par défaut.  Par exemple :

@example
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.groupdict()
@{'first_name': 'Malcolm', 'last_name': 'Reynolds'@}
@end example
@end deffn

@geindex start() (méthode re.Match)
@geindex end() (méthode re.Match)
@anchor{library/re re Match start}@anchor{229f}
@deffn {Méthode} Match.start ([group])
@anchor{library/re re Match end}@anchor{22a0}
@deffnx {Méthode} Match.end ([group])

Renvoie les indices de début et de fin de la sous-chaîne correspondant au groupe `group' ; `group' vaut par défaut zéro (pour récupérer les indices de la correspondance complète). Renvoie @code{-1} si `group' existe mais ne figure pas dans la correspondance.  Pour un objet de correspondance `m', et un groupe `g' qui y figure, la sous-chaîne correspondant au groupe `g' (équivalente à @code{m.group(g)}) est

@example
m.string[m.start(g):m.end(g)]
@end example

Notez que @code{m.start(group)} sera égal à @code{m.end(group)} si `group' correspond à une chaîne vide.  Par exemple, après @code{m = re.search('b(c?)', 'cba')}, @code{m.start(0)} vaut 1, @code{m.end(0)} vaut 2, @code{m.start(1)} et @code{m.end(1)} valent tous deux 2, et @code{m.start(2)} lève une exception @ref{14eb,,IndexError}.

Un exemple qui supprimera `remove_this' d'une adresse mail :

@example
>>> email = "tony@@tiremove_thisger.net"
>>> m = re.search("remove_this", email)
>>> email[:m.start()] + email[m.end():]
'tony@@tiger.net'
@end example
@end deffn

@geindex span() (méthode re.Match)
@anchor{library/re re Match span}@anchor{22a1}
@deffn {Méthode} Match.span ([group])

Pour un objet de correspondance `m', renvoie la paire @code{(m.start(group), m.end(group))}. Notez que si `group' ne figure pas dans la correspondance, @code{(-1, -1)} est renvoyé. `group' vaut par défaut zéro, pour la correspondance entière.
@end deffn

@geindex pos (attribut re.Match)
@anchor{library/re re Match pos}@anchor{22a2}
@deffn {Attribut} Match.pos

La valeur de `pos' qui a été passée à la méthode @ref{2286,,search()} ou @ref{2285,,match()} d'un @ref{f71,,objet expression rationnelle}.  C'est l'index dans la chaîne à partir duquel le moteur d'expressions rationnelles recherche une correspondance.
@end deffn

@geindex endpos (attribut re.Match)
@anchor{library/re re Match endpos}@anchor{22a3}
@deffn {Attribut} Match.endpos

La valeur de `endpos' qui a été passée à la méthode @ref{2286,,search()} ou @ref{2285,,match()} d'un @ref{f71,,objet expression rationnelle}.  C'est l'index dans la chaîne que le moteur d'expressions rationnelles ne dépassera pas.
@end deffn

@geindex lastindex (attribut re.Match)
@anchor{library/re re Match lastindex}@anchor{22a4}
@deffn {Attribut} Match.lastindex

L'index entier du dernier groupe de capture validé, ou @code{None} si aucun groupe ne correspondait. Par exemple, les expressions @code{(a)b}, @code{((a)(b))} et @code{((ab))} auront un @code{lastindex == 1} si appliquées à la chaîne @code{'ab'}, alors que l'expression @code{(a)(b)} aura un @code{lastindex == 2} si appliquée à la même chaîne.
@end deffn

@geindex lastgroup (attribut re.Match)
@anchor{library/re re Match lastgroup}@anchor{22a5}
@deffn {Attribut} Match.lastgroup

Le nom du dernier groupe capturant validé, ou @code{None} si le groupe n'a pas de nom, ou si aucun groupe ne correspondait.
@end deffn

@geindex re (attribut re.Match)
@anchor{library/re re Match re}@anchor{22a6}
@deffn {Attribut} Match.re

@ref{f71,,L'expression rationnelle} dont la méthode @ref{2285,,match()} ou @ref{2286,,search()} a produit cet objet de correspondance.
@end deffn

@geindex string (attribut re.Match)
@anchor{library/re re Match string}@anchor{22a7}
@deffn {Attribut} Match.string

La chaîne passée à @ref{2285,,match()} ou @ref{2286,,search()}.
@end deffn


Modifié dans la version 3.7: Ajout du support des fonctions @ref{51d,,copy.copy()} et @ref{b5c,,copy.deepcopy()}. Les objets correspondants sont considérés atomiques.


@node Exemples d'expressions rationnelles,,Objets de correspondance,re --- Regular expression operations
@anchor{library/re re-examples}@anchor{123c}@anchor{library/re regular-expression-examples}@anchor{22a8}
@subsubsection Exemples d'expressions rationnelles


@menu
* Rechercher une paire:: 
* Simuler scanf(): Simuler scanf. 
* Comparaison de search() et match(): Comparaison de search et match. 
* Construire un répertoire téléphonique:: 
* Mélanger les lettres des mots:: 
* Trouver tous les adverbes:: 
* Trouver tous les adverbes et leurs positions:: 
* Notation brute de chaînes:: 
* Écrire un analyseur lexical:: 

@end menu

@node Rechercher une paire,Simuler scanf,,Exemples d'expressions rationnelles
@anchor{library/re checking-for-a-pair}@anchor{22a9}
@subsubsection Rechercher une paire


Dans cet exemple, nous nous aidons de la fonction suivante pour afficher de manière plus jolie les objets qui correspondent :

@example
def displaymatch(match):
    if match is None:
        return None
    return '<Match: %r, groups=%r>' % (match.group(), match.groups())
@end example

Supposez que vous écriviez un jeu de poker où la main d'un joueur est représentée par une chaîne de 5 caractères avec chaque caractère représentant une carte, « a » pour l'as, « k » pour le roi (`king'), « q » pour la reine (`queen'), « j » pour le valet (`jack'), « t » pour 10 (`ten'), et les caractères de « 2 » à « 9 » représentant les cartes avec ces valeurs.

Pour vérifier qu'une chaîne donnée est une main valide, on pourrait faire comme suit :

@example
>>> valid = re.compile(r"^[a2-9tjqk]@{5@}$")
>>> displaymatch(valid.match("akt5q"))  # Valid.
"<Match: 'akt5q', groups=()>"
>>> displaymatch(valid.match("akt5e"))  # Invalid.
>>> displaymatch(valid.match("akt"))    # Invalid.
>>> displaymatch(valid.match("727ak"))  # Valid.
"<Match: '727ak', groups=()>"
@end example

La dernière main, @code{"727ak"}, contenait une paire, deux cartes de la même valeur. Pour valider cela avec une expression rationnelle, on pourrait utiliser des références arrière comme :

@example
>>> pair = re.compile(r".*(.).*\1")
>>> displaymatch(pair.match("717ak"))     # Pair of 7s.
"<Match: '717', groups=('7',)>"
>>> displaymatch(pair.match("718ak"))     # No pairs.
>>> displaymatch(pair.match("354aa"))     # Pair of aces.
"<Match: '354aa', groups=('a',)>"
@end example

Pour trouver de quelle carte est composée la paire, on pourrait utiliser la méthode @ref{229b,,group()} de l'objet de correspondance de la manière suivante :

@example
>>> pair = re.compile(r".*(.).*\1")
>>> pair.match("717ak").group(1)
'7'

# Error because re.match() returns None, which doesn't have a group() method:
>>> pair.match("718ak").group(1)
Traceback (most recent call last):
  File "<pyshell#23>", line 1, in <module>
    re.match(r".*(.).*\1", "718ak").group(1)
AttributeError: 'NoneType' object has no attribute 'group'

>>> pair.match("354aa").group(1)
'a'
@end example

@node Simuler scanf,Comparaison de search et match,Rechercher une paire,Exemples d'expressions rationnelles
@anchor{library/re simulating-scanf}@anchor{22aa}
@subsubsection Simuler `scanf()'


@geindex scanf (C function)

Python does not currently have an equivalent to @code{scanf()}.  Regular
expressions are generally more powerful, though also more verbose, than
@code{scanf()} format strings.  The table below offers some more-or-less
equivalent mappings between @code{scanf()} format tokens and regular
expressions.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@code{scanf()} Token

@tab

Expression rationnelle

@item

@code{%c}

@tab

@code{.}

@item

@code{%5c}

@tab

@code{.@{5@}}

@item

@code{%d}

@tab

@code{[-+]?\d+}

@item

@code{%e}, @code{%E}, @code{%f}, @code{%g}

@tab

@code{[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?}

@item

@code{%i}

@tab

@code{[-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)}

@item

@code{%o}

@tab

@code{[-+]?[0-7]+}

@item

@code{%s}

@tab

@code{\S+}

@item

@code{%u}

@tab

@code{\d+}

@item

@code{%x}, @code{%X}

@tab

@code{[-+]?(0[xX])?[\dA-Fa-f]+}

@end multitable


Pour extraire le nom de fichier et les nombres depuis une chaîne comme

@example
/usr/sbin/sendmail - 0 errors, 4 warnings
@end example

you would use a @code{scanf()} format like

@example
%s - %d errors, %d warnings
@end example

L'expression rationnelle équivalente serait

@example
(\S+) - (\d+) errors, (\d+) warnings
@end example

@node Comparaison de search et match,Construire un répertoire téléphonique,Simuler scanf,Exemples d'expressions rationnelles
@anchor{library/re id4}@anchor{22ab}@anchor{library/re search-vs-match}@anchor{2287}
@subsubsection Comparaison de `search()' et `match()'


Python offre différentes opérations primitives basées sur des expressions régulières :


@itemize +

@item 
@ref{120b,,re.match()} cherche une correspondance uniquement au début de la chaîne de caractères

@item 
@ref{120a,,re.search()} cherche une correspondance n'importe où dans la chaîne de caractères (ce que fait Perl par défaut)

@item 
@ref{f70,,re.fullmatch()} cherche une correspondance avec l'intégralité de la chaîne de caractères.
@end itemize

Par exemple :

@example
>>> re.match("c", "abcdef")    # No match
>>> re.search("c", "abcdef")   # Match
<re.Match object; span=(2, 3), match='c'>
>>> re.fullmatch("p.*n", "python") # Match
<re.Match object; span=(0, 6), match='python'>
>>> re.fullmatch("r.*n", "python") # No match
@end example

Les expressions rationnelles commençant par @code{'^'} peuvent être utilisées avec @ref{120a,,search()} pour restreindre la recherche au début de la chaîne :

@example
>>> re.match("c", "abcdef")    # No match
>>> re.search("^c", "abcdef")  # No match
>>> re.search("^a", "abcdef")  # Match
<re.Match object; span=(0, 1), match='a'>
@end example

Notez cependant qu'en mode @ref{2274,,MULTILINE}, @ref{120b,,match()} ne recherche qu'au début de la chaîne, alors que @ref{120a,,search()} avec une expression rationnelle commençant par @code{'^'} recherchera au début de chaque ligne.

@example
>>> re.match("X", "A\nB\nX", re.MULTILINE)  # No match
>>> re.search("^X", "A\nB\nX", re.MULTILINE)  # Match
<re.Match object; span=(4, 5), match='X'>
@end example

@node Construire un répertoire téléphonique,Mélanger les lettres des mots,Comparaison de search et match,Exemples d'expressions rationnelles
@anchor{library/re making-a-phonebook}@anchor{22ac}
@subsubsection Construire un répertoire téléphonique


@ref{29f,,split()} découpe une chaîne en une liste délimitée par le motif donné.  La méthode est inestimable pour convertir des données textuelles vers des structures de données qui peuvent être lues et modifiées par Python comme démontré dans l'exemple suivant qui crée un répertoire téléphonique.

Tout d'abord, voici l'entrée. Elle provient normalement d'un fichier, nous utilisons ici une chaîne à guillemets triples

@example
>>> text = """Ross McFluff: 834.345.1254 155 Elm Street
...
... Ronald Heathmore: 892.345.3428 436 Finley Avenue
... Frank Burger: 925.541.7625 662 South Dogwood Way
...
...
... Heather Albrecht: 548.326.4584 919 Park Place"""
@end example

Les entrées sont séparées par un saut de ligne ou plus. Nous convertissons maintenant la chaîne en une liste où chaque ligne non vide aura sa propre entrée :

@example
>>> entries = re.split("\n+", text)
>>> entries
['Ross McFluff: 834.345.1254 155 Elm Street',
'Ronald Heathmore: 892.345.3428 436 Finley Avenue',
'Frank Burger: 925.541.7625 662 South Dogwood Way',
'Heather Albrecht: 548.326.4584 919 Park Place']
@end example

Finalement, on sépare chaque entrée en une liste avec prénom, nom, numéro de téléphone et adresse.  Nous utilisons le paramètre @code{maxsplit} de @ref{29f,,split()} parce que l'adresse contient des espaces, qui sont notre motif de séparation :

@example
>>> [re.split(":? ", entry, maxsplit=3) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155 Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436 Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662 South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919 Park Place']]
@end example

Le motif @code{:?} trouve les deux points derrière le nom de famille, pour qu'ils n'apparaissent pas dans la liste résultante. Avec un @code{maxsplit} de @code{4}, nous pourrions séparer le numéro du nom de la rue :

@example
>>> [re.split(":? ", entry, maxsplit=4) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155', 'Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436', 'Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662', 'South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]
@end example

@node Mélanger les lettres des mots,Trouver tous les adverbes,Construire un répertoire téléphonique,Exemples d'expressions rationnelles
@anchor{library/re text-munging}@anchor{22ad}
@subsubsection Mélanger les lettres des mots


@ref{2a0,,sub()} remplace toutes les occurrences d'un motif par une chaîne ou le résultat d'une fonction.  Cet exemple le montre, en utilisant @ref{2a0,,sub()} avec une fonction qui mélange aléatoirement les caractères de chaque mot dans une phrase (à l'exception des premiers et derniers caractères) :

@example
>>> def repl(m):
...     inner_word = list(m.group(2))
...     random.shuffle(inner_word)
...     return m.group(1) + "".join(inner_word) + m.group(3)
...
>>> text = "Professor Abdolmalek, please report your absences promptly."
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'
@end example

@node Trouver tous les adverbes,Trouver tous les adverbes et leurs positions,Mélanger les lettres des mots,Exemples d'expressions rationnelles
@anchor{library/re finding-all-adverbs}@anchor{22ae}
@subsubsection Trouver tous les adverbes


@ref{1013,,findall()} trouve `toutes' les occurrences d'un motif, pas juste la première comme le fait @ref{120a,,search()}.  Par exemple, si un écrivain voulait trouver tous les adverbes dans un texte, il devrait utiliser @ref{1013,,findall()} de la manière suivante :

@example
>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly\b", text)
['carefully', 'quickly']
@end example

@node Trouver tous les adverbes et leurs positions,Notation brute de chaînes,Trouver tous les adverbes,Exemples d'expressions rationnelles
@anchor{library/re finding-all-adverbs-and-their-positions}@anchor{22af}
@subsubsection Trouver tous les adverbes et leurs positions


If one wants more information about all matches of a pattern than the matched
text, @ref{14b0,,finditer()} is useful as it provides @ref{cb6,,Match} objects
instead of strings.  Continuing with the previous example, if a writer wanted
to find all of the adverbs `and their positions' in some text, they would use
@ref{14b0,,finditer()} in the following manner:

@example
>>> text = "He was carefully disguised but captured quickly by police."
>>> for m in re.finditer(r"\w+ly\b", text):
...     print('%02d-%02d: %s' % (m.start(), m.end(), m.group(0)))
07-16: carefully
40-47: quickly
@end example

@node Notation brute de chaînes,Écrire un analyseur lexical,Trouver tous les adverbes et leurs positions,Exemples d'expressions rationnelles
@anchor{library/re raw-string-notation}@anchor{22b0}
@subsubsection Notation brute de chaînes


La notation brute de chaînes (@code{r"text"}) garde saines les expressions rationnelles.  Sans elle, chaque `backslash' (@code{'\'}) dans une expression rationnelle devrait être préfixé d'un autre `backslash' pour l'échapper.  Par exemple, les deux lignes de code suivantes sont fonctionnellement identiques :

@example
>>> re.match(r"\W(.)\1\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
>>> re.match("\\W(.)\\1\\W", " ff ")
<re.Match object; span=(0, 4), match=' ff '>
@end example

Pour rechercher un `backslash' littéral, il faut l'échapper dans l'expression rationnelle.  Avec la notation brute, cela signifie @code{r"\\"}.  Sans elle, il faudrait utiliser @code{"\\\\"}, faisant que les deux lignes de code suivantes sont fonctionnellement identiques :

@example
>>> re.match(r"\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
>>> re.match("\\\\", r"\\")
<re.Match object; span=(0, 1), match='\\'>
@end example

@node Écrire un analyseur lexical,,Notation brute de chaînes,Exemples d'expressions rationnelles
@anchor{library/re writing-a-tokenizer}@anchor{22b1}
@subsubsection Écrire un analyseur lexical


Un analyseur lexical ou scanner@footnote{https://en.wikipedia.org/wiki/Lexical_analysis} analyse une chaîne pour catégoriser les groupes de caractères.  C'est une première étape utile dans l'écriture d'un compilateur ou d'un interpréteur.

Les catégories de texte sont spécifiées par des expressions rationnelles.  La technique est de les combiner dans une unique expression rationnelle maîtresse, et de boucler sur les correspondances successives :

@example
from typing import NamedTuple
import re

class Token(NamedTuple):
    type: str
    value: str
    line: int
    column: int

def tokenize(code):
    keywords = @{'IF', 'THEN', 'ENDIF', 'FOR', 'NEXT', 'GOSUB', 'RETURN'@}
    token_specification = [
        ('NUMBER',   r'\d+(\.\d*)?'),  # Integer or decimal number
        ('ASSIGN',   r':='),           # Assignment operator
        ('END',      r';'),            # Statement terminator
        ('ID',       r'[A-Za-z]+'),    # Identifiers
        ('OP',       r'[+\-*/]'),      # Arithmetic operators
        ('NEWLINE',  r'\n'),           # Line endings
        ('SKIP',     r'[ \t]+'),       # Skip over spaces and tabs
        ('MISMATCH', r'.'),            # Any other character
    ]
    tok_regex = '|'.join('(?P<%s>%s)' % pair for pair in token_specification)
    line_num = 1
    line_start = 0
    for mo in re.finditer(tok_regex, code):
        kind = mo.lastgroup
        value = mo.group()
        column = mo.start() - line_start
        if kind == 'NUMBER':
            value = float(value) if '.' in value else int(value)
        elif kind == 'ID' and value in keywords:
            kind = value
        elif kind == 'NEWLINE':
            line_start = mo.end()
            line_num += 1
            continue
        elif kind == 'SKIP':
            continue
        elif kind == 'MISMATCH':
            raise RuntimeError(f'@{value!r@} unexpected on line @{line_num@}')
        yield Token(kind, value, line_num, column)

statements = '@w{'}'
    IF quantity THEN
        total := total + price * quantity;
        tax := price * 0.05;
    ENDIF;
'@w{'}'

for token in tokenize(statements):
    print(token)
@end example

L'analyseur produit la sortie suivante :

@example
Token(type='IF', value='IF', line=2, column=4)
Token(type='ID', value='quantity', line=2, column=7)
Token(type='THEN', value='THEN', line=2, column=16)
Token(type='ID', value='total', line=3, column=8)
Token(type='ASSIGN', value=':=', line=3, column=14)
Token(type='ID', value='total', line=3, column=17)
Token(type='OP', value='+', line=3, column=23)
Token(type='ID', value='price', line=3, column=25)
Token(type='OP', value='*', line=3, column=31)
Token(type='ID', value='quantity', line=3, column=33)
Token(type='END', value=';', line=3, column=41)
Token(type='ID', value='tax', line=4, column=8)
Token(type='ASSIGN', value=':=', line=4, column=12)
Token(type='ID', value='price', line=4, column=15)
Token(type='OP', value='*', line=4, column=21)
Token(type='NUMBER', value=0.05, line=4, column=23)
Token(type='END', value=';', line=4, column=27)
Token(type='ENDIF', value='ENDIF', line=5, column=4)
Token(type='END', value=';', line=5, column=9)
@end example

@anchor{library/re frie09}@anchor{2271}@w{(Frie09)} 
`Friedl, Jeffrey. Mastering Regular Expressions. 3rd ed., O'Reilly Media, 2009'. La troisième édition de ce livre ne couvre plus du tout Python, mais la première version explique en détails comment écrire de bonnes expressions rationnelles.

@node difflib --- Helpers for computing deltas,textwrap --- Text wrapping and filling,re --- Regular expression operations,Services de Manipulation de Texte
@anchor{library/difflib doc}@anchor{22b2}@anchor{library/difflib difflib-helpers-for-computing-deltas}@anchor{22b3}@anchor{library/difflib module-difflib}@anchor{37}
@subsection @code{difflib} --- Helpers for computing deltas


@geindex module; difflib

@c Markup by Fred L. Drake, Jr. <fdrake@acm.org>

`Code source:' Lib/difflib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/difflib.py}

@c import sys
@c from difflib import *


__________________________________________________________________


This module provides classes and functions for comparing sequences. It
can be used for example, for comparing files, and can produce information
about file differences in various formats, including HTML and context and unified
diffs. For comparing directories and files, see also, the @ref{59,,filecmp} module.


@deffn {Classe} difflib.SequenceMatcher

C'est une classe flexible permettant de comparer des séquences deux à deux de n'importe quel type, tant que les éléments des séquences sont @ref{5fb,,hachables}. L'algorithme de base est antérieur, et un peu plus sophistiqué, à un algorithme publié à la fin des années 1980 par Ratcliff et Obershelp sous le nom hyperbolique de `gestalt pattern matching'. L'idée est de trouver la plus longue sous-séquence d'appariement contiguë qui ne contient pas d'éléments « indésirables » ; ces éléments « indésirables » sont ceux qui sont inintéressants dans un certain sens, comme les lignes blanches ou les espaces. (Le traitement des éléments indésirables est une extension de l'algorithme de Ratcliff et Obershelp). La même idée est ensuite appliquée récursivement aux morceaux des séquences à gauche et à droite de la sous-séquence correspondante. Cela ne donne pas des séquences de montage minimales, mais tend à donner des correspondances qui « semblent correctes » pour les gens.

`Compléxité temporelle :' l'algorithme de base de Ratcliff-Obershelp est de complexité cubique dans le pire cas et de complexité quadratique dans le cas attendu. @ref{1002,,SequenceMatcher} est de complexité quadratique pour le pire cas et son comportement dans le cas attendu dépend de façon complexe du nombre d'éléments que les séquences ont en commun ; le temps dans le meilleur cas est linéaire.

`Heuristique automatique des indésirables:' @ref{1002,,SequenceMatcher} utilise une heuristique qui traite automatiquement certains éléments de la séquence comme indésirables. L'heuristique compte combien de fois chaque élément individuel apparaît dans la séquence. Si les doublons d'un élément (après le premier) représentent plus de 1 % de la séquence et que la séquence compte au moins 200 éléments, cet élément est marqué comme « populaire » et est traité comme indésirable aux fins de la comparaison des séquences. Cette heuristique peut être désactivée en réglant l'argument @code{autojunk} sur @code{False} lors de la création de la classe @ref{1002,,SequenceMatcher}.


Modifié dans la version 3.2: Added the `autojunk' parameter.

@end deffn

@geindex Differ (classe dans difflib)
@anchor{library/difflib difflib Differ}@anchor{22b4}
@deffn {Classe} difflib.Differ

Il s'agit d'une classe permettant de comparer des séquences de lignes de texte et de produire des différences ou deltas humainement lisibles. `Differ' utilise @ref{1002,,SequenceMatcher} à la fois pour comparer des séquences de lignes, et pour comparer des séquences de caractères dans des lignes similaires (quasi-correspondantes).

Chaque ligne d'un delta @ref{22b4,,Differ} commence par un code de deux lettres :


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Code

@tab

Signification

@item

@code{'- '}

@tab

ligne n'appartenant qu'à la séquence 1

@item

@code{'+ '}

@tab

ligne n'appartenant qu'à la séquence 2

@item

@code{'  '}

@tab

ligne commune aux deux séquences

@item

@code{'? '}

@tab

ligne non présente dans l'une ou l'autre des séquences d'entrée

@end multitable


Lines beginning with '@code{?}' attempt to guide the eye to intraline differences,
and were not present in either input sequence. These lines can be confusing if
the sequences contain whitespace characters, such as spaces, tabs or line breaks.
@end deffn

@geindex HtmlDiff (classe dans difflib)
@anchor{library/difflib difflib HtmlDiff}@anchor{22b5}
@deffn {Classe} difflib.HtmlDiff

Cette classe peut être utilisée pour créer un tableau HTML (ou un fichier HTML complet contenant le tableau) montrant une comparaison côte à côte, ligne par ligne, du texte avec les changements inter-lignes et intralignes. Le tableau peut être généré en mode de différence complet ou contextuel.

Le constructeur pour cette classe est :

@geindex __init__() (méthode difflib.HtmlDiff)
@anchor{library/difflib difflib HtmlDiff __init__}@anchor{22b6}
@deffn {Méthode} __init__ (tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Initialise l'instance de @ref{22b5,,HtmlDiff}.

`tabsize' est argument nommé optionnel pour spécifier l'espacement des tabulations et sa valeur par défaut est @code{8}.

`wrapcolumn' est un argument nommé optionnel pour spécifier le numéro de la colonne où les lignes sont coupées pour être ré-agencées, la valeur par défaut est @code{None} lorsque les lignes ne sont pas ré-agencées.

`linejunk' et `charjunk' sont des arguments nommés optionnels passés dans @ref{22b7,,ndiff()} (utilisés par @ref{22b5,,HtmlDiff} pour générer les différences HTML côte à côte). Voir la documentation de @ref{22b7,,ndiff()} pour les valeurs par défaut des arguments et les descriptions.
@end deffn

Les méthodes suivantes sont publiques :

@geindex make_file() (méthode difflib.HtmlDiff)
@anchor{library/difflib difflib HtmlDiff make_file}@anchor{ddc}
@deffn {Méthode} make_file (fromlines, tolines, fromdesc='@w{'}, todesc='@w{'}, context=False, numlines=5, *, charset='utf-8')

Compare `fromlines' et `tolines' (listes de chaînes de caractères) et renvoie une chaîne de caractères qui est un fichier HTML complet contenant un tableau montrant les différences ligne par ligne avec les changements inter-lignes et intralignes mis en évidence.

`fromdesc' et `todesc' sont des arguments nommés optionnels pour spécifier les chaînes d'en-tête des colonnes `from/to' du fichier (les deux sont des chaînes vides par défaut).

`context' et `numlines' sont tous deux des arguments nommés facultatifs. Mettre `context' à @code{True} lorsque les différences contextuelles doivent être affichées, sinon la valeur par défaut est @code{False} pour afficher les fichiers complets. Les `numlines' ont pour valeur par défaut @code{5}. Lorsque `context' est @code{True}, `numlines' contrôle le nombre de lignes de contexte qui entourent les différences mise en évidence. Lorsque `context' est @code{False}, `numlines' contrôle le nombre de lignes qui sont affichées avant un surlignage de différence lors de l'utilisation des hyperliens « suivants » (un réglage à zéro ferait en sorte que les hyperliens « suivants » placeraient le surlignage de différence suivant en haut du navigateur sans aucun contexte introductif).

@cartouche
@quotation Note 
`fromdesc' et `todesc' sont interprétés comme du HTML non échappé et doivent être correctement échappés lors de la réception de données provenant de sources non fiables.
@end quotation
@end cartouche


Modifié dans la version 3.5: l'argument nommé `charset' a été ajouté. Le jeu de caractères par défaut du document HTML est passé de @code{'ISO-8859-1'} à @code{'utf-8'}.

@end deffn

@geindex make_table() (méthode difflib.HtmlDiff)
@anchor{library/difflib difflib HtmlDiff make_table}@anchor{22b8}
@deffn {Méthode} make_table (fromlines, tolines, fromdesc='@w{'}, todesc='@w{'}, context=False, numlines=5)

Compare `fromlines' et `tolines' (listes de chaînes) et renvoie une chaîne qui est un tableau HTML complet montrant les différences ligne par ligne avec les changements inter-lignes et intralignes mis en évidence.

Les arguments pour cette méthode sont les mêmes que ceux de la méthode @ref{ddc,,make_file()}.
@end deffn
@end deffn

@geindex context_diff() (dans le module difflib)
@anchor{library/difflib difflib context_diff}@anchor{22b9}
@deffn {Fonction} difflib.context_diff (a, b, fromfile='@w{'}, tofile='@w{'}, fromfiledate='@w{'}, tofiledate='@w{'}, n=3, lineterm='\n')

Compare `a' et `b' (listes de chaînes de caractères) ; renvoie un delta (un @ref{104a,,generateur} générant les lignes delta) dans un format de différence de contexte.

Context diffs are a compact way of showing just the lines that have changed plus
a few lines of context.  The changes are shown in a before/after style.  The
number of context lines is set by `n' which defaults to three.

Par défaut, les lignes de contrôle de la différence (celles avec @code{***} ou @code{---}) sont créées avec un saut de ligne à la fin. Ceci est utile pour que les entrées créées à partir de @ref{22ba,,io.IOBase.readlines()} résultent en des différences qui peuvent être utilisées avec @ref{22bb,,io.IOBase.writelines()} puisque les entrées et les sorties ont des nouvelles lignes de fin.

Pour les entrées qui n'ont pas de retour à la ligne, mettre l'argument `lineterm' à @code{""} afin que la sortie soit uniformément sans retour à la ligne.

Le format de contexte de différence comporte normalement un en-tête pour les noms de fichiers et les heures de modification. Tout ou partie de ces éléments peuvent être spécifiés en utilisant les chaînes de caractères `fromfile', `tofile', `fromfiledate' et `tofiledate'. Les heures de modification sont normalement exprimées dans le format ISO 8601. Si elles ne sont pas spécifiées, les chaînes de caractères sont par défaut vierges.

@example
>>> import sys
>>> from difflib import *
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> sys.stdout.writelines(context_diff(s1, s2, fromfile='before.py',
...                        tofile='after.py'))
*** before.py
--- after.py
***************
*** 1,4 ****
! bacon
! eggs
! ham
  guido
--- 1,4 ----
! python
! eggy
! hamster
  guido
@end example

Voir @ref{22bc,,une interface de ligne de commandes pour difflib} pour un exemple plus détaillé.
@end deffn

@geindex get_close_matches() (dans le module difflib)
@anchor{library/difflib difflib get_close_matches}@anchor{22bd}
@deffn {Fonction} difflib.get_close_matches (word, possibilities, n=3, cutoff=0.6)

Return a list of the best "good enough" matches.  `word' is a sequence for which
close matches are desired (typically a string), and `possibilities' is a list of
sequences against which to match `word' (typically a list of strings).

Optional argument `n' (default @code{3}) is the maximum number of close matches to
return; `n' must be greater than @code{0}.

Optional argument `cutoff' (default @code{0.6}) is a float in the range [0, 1].
Possibilities that don't score at least that similar to `word' are ignored.

The best (no more than `n') matches among the possibilities are returned in a
list, sorted by similarity score, most similar first.

@example
>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
>>> import keyword
>>> get_close_matches('wheel', keyword.kwlist)
['while']
>>> get_close_matches('pineapple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']
@end example
@end deffn

@geindex ndiff() (dans le module difflib)
@anchor{library/difflib difflib ndiff}@anchor{22b7}
@deffn {Fonction} difflib.ndiff (a, b, linejunk=None, charjunk=IS_CHARACTER_JUNK)

Compare `a' and `b' (lists of strings); return a @ref{22b4,,Differ}-style
delta (a @ref{104a,,generator} generating the delta lines).

Optional keyword parameters `linejunk' and `charjunk' are filtering functions
(or @code{None}):

`linejunk': A function that accepts a single string argument, and returns
true if the string is junk, or false if not. The default is @code{None}. There
is also a module-level function @ref{22be,,IS_LINE_JUNK()}, which filters out lines
without visible characters, except for at most one pound character (@code{'#'})
-- however the underlying @ref{1002,,SequenceMatcher} class does a dynamic
analysis of which lines are so frequent as to constitute noise, and this
usually works better than using this function.

`charjunk': A function that accepts a character (a string of length 1), and
returns if the character is junk, or false if not. The default is module-level
function @ref{22bf,,IS_CHARACTER_JUNK()}, which filters out whitespace characters (a
blank or tab; it's a bad idea to include newline in this!).

@example
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> print('@w{'}.join(diff), end="")
- one
?  ^
+ ore
?  ^
- two
- three
?  -
+ tree
+ emu
@end example
@end deffn

@geindex restore() (dans le module difflib)
@anchor{library/difflib difflib restore}@anchor{22c0}
@deffn {Fonction} difflib.restore (sequence, which)

Return one of the two sequences that generated a delta.

Given a `sequence' produced by @ref{22c1,,Differ.compare()} or @ref{22b7,,ndiff()}, extract
lines originating from file 1 or 2 (parameter `which'), stripping off line
prefixes.

Exemple :

@example
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(keepends=True),
...              'ore\ntree\nemu\n'.splitlines(keepends=True))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print('@w{'}.join(restore(diff, 1)), end="")
one
two
three
>>> print('@w{'}.join(restore(diff, 2)), end="")
ore
tree
emu
@end example
@end deffn

@geindex unified_diff() (dans le module difflib)
@anchor{library/difflib difflib unified_diff}@anchor{22c2}
@deffn {Fonction} difflib.unified_diff (a, b, fromfile='@w{'}, tofile='@w{'}, fromfiledate='@w{'}, tofiledate='@w{'}, n=3, lineterm='\n')

Compare `a' and `b' (lists of strings); return a delta (a @ref{104a,,generator}
generating the delta lines) in unified diff format.

Unified diffs are a compact way of showing just the lines that have changed plus
a few lines of context.  The changes are shown in an inline style (instead of
separate before/after blocks).  The number of context lines is set by `n' which
defaults to three.

By default, the diff control lines (those with @code{---}, @code{+++}, or @code{@@@@}) are
created with a trailing newline.  This is helpful so that inputs created from
@ref{22ba,,io.IOBase.readlines()} result in diffs that are suitable for use with
@ref{22bb,,io.IOBase.writelines()} since both the inputs and outputs have trailing
newlines.

Pour les entrées qui n'ont pas de retour à la ligne, mettre l'argument `lineterm' à @code{""} afin que la sortie soit uniformément sans retour à la ligne.

The unified diff format normally has a header for filenames and modification
times.  Any or all of these may be specified using strings for `fromfile',
`tofile', `fromfiledate', and `tofiledate'.  The modification times are normally
expressed in the ISO 8601 format. If not specified, the
strings default to blanks.

@example
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> sys.stdout.writelines(unified_diff(s1, s2, fromfile='before.py', tofile='after.py'))
--- before.py
+++ after.py
@@@@ -1,4 +1,4 @@@@
-bacon
-eggs
-ham
+python
+eggy
+hamster
 guido
@end example

Voir @ref{22bc,,une interface de ligne de commandes pour difflib} pour un exemple plus détaillé.
@end deffn

@geindex diff_bytes() (dans le module difflib)
@anchor{library/difflib difflib diff_bytes}@anchor{ddd}
@deffn {Fonction} difflib.diff_bytes (dfunc, a, b, fromfile=b'@w{'}, tofile=b'@w{'}, fromfiledate=b'@w{'}, tofiledate=b'@w{'}, n=3, lineterm=b'\n')

Compare `a' and `b' (lists of bytes objects) using `dfunc'; yield a
sequence of delta lines (also bytes) in the format returned by `dfunc'.
`dfunc' must be a callable, typically either @ref{22c2,,unified_diff()} or
@ref{22b9,,context_diff()}.

Allows you to compare data with unknown or inconsistent encoding. All
inputs except `n' must be bytes objects, not str. Works by losslessly
converting all inputs (except `n') to str, and calling @code{dfunc(a, b,
fromfile, tofile, fromfiledate, tofiledate, n, lineterm)}. The output of
`dfunc' is then converted back to bytes, so the delta lines that you
receive have the same unknown/inconsistent encodings as `a' and `b'.


Ajouté dans la version 3.5.

@end deffn

@geindex IS_LINE_JUNK() (dans le module difflib)
@anchor{library/difflib difflib IS_LINE_JUNK}@anchor{22be}
@deffn {Fonction} difflib.IS_LINE_JUNK (line)

Return @code{True} for ignorable lines.  The line `line' is ignorable if `line' is
blank or contains a single @code{'#'}, otherwise it is not ignorable.  Used as a
default for parameter `linejunk' in @ref{22b7,,ndiff()} in older versions.
@end deffn

@geindex IS_CHARACTER_JUNK() (dans le module difflib)
@anchor{library/difflib difflib IS_CHARACTER_JUNK}@anchor{22bf}
@deffn {Fonction} difflib.IS_CHARACTER_JUNK (ch)

Return @code{True} for ignorable characters.  The character `ch' is ignorable if `ch'
is a space or tab, otherwise it is not ignorable.  Used as a default for
parameter `charjunk' in @ref{22b7,,ndiff()}.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Pattern Matching: The Gestalt Approach@footnote{https://www.drdobbs.com/database/pattern-matching-the-gestalt-approach/184407970}

Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
was published in Dr. Dobb's Journal@footnote{https://www.drdobbs.com/} in July, 1988.
@end table


@menu
* SequenceMatcher Objects:: 
* SequenceMatcher Examples:: 
* Differ Objects:: 
* Differ Example:: 
* A command-line interface to difflib:: 
* ndiff example:: 

@end menu

@node SequenceMatcher Objects,SequenceMatcher Examples,,difflib --- Helpers for computing deltas
@anchor{library/difflib sequence-matcher}@anchor{22c3}@anchor{library/difflib sequencematcher-objects}@anchor{22c4}
@subsubsection SequenceMatcher Objects


The @ref{1002,,SequenceMatcher} class has this constructor:

@geindex SequenceMatcher (classe dans difflib)
@anchor{library/difflib difflib SequenceMatcher}@anchor{1002}
@deffn {Classe} difflib.SequenceMatcher (isjunk=None, a='@w{'}, b='@w{'}, autojunk=True)

Optional argument `isjunk' must be @code{None} (the default) or a one-argument
function that takes a sequence element and returns true if and only if the
element is "junk" and should be ignored. Passing @code{None} for `isjunk' is
equivalent to passing @code{lambda x: False}; in other words, no elements are ignored.
For example, pass:

@example
lambda x: x in " \t"
@end example

if you're comparing lines as sequences of characters, and don't want to synch up
on blanks or hard tabs.

The optional arguments `a' and `b' are sequences to be compared; both default to
empty strings.  The elements of both sequences must be @ref{5fb,,hashable}.

The optional argument `autojunk' can be used to disable the automatic junk
heuristic.


Modifié dans la version 3.2: Added the `autojunk' parameter.


SequenceMatcher objects get three data attributes: `bjunk' is the
set of elements of `b' for which `isjunk' is @code{True}; `bpopular' is the set of
non-junk elements considered popular by the heuristic (if it is not
disabled); `b2j' is a dict mapping the remaining elements of `b' to a list
of positions where they occur. All three are reset whenever `b' is reset
with @ref{22c5,,set_seqs()} or @ref{22c6,,set_seq2()}.


Ajouté dans la version 3.2: The `bjunk' and `bpopular' attributes.


@ref{1002,,SequenceMatcher} objects have the following methods:

@geindex set_seqs() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher set_seqs}@anchor{22c5}
@deffn {Méthode} set_seqs (a, b)

Set the two sequences to be compared.
@end deffn

@ref{1002,,SequenceMatcher} computes and caches detailed information about the
second sequence, so if you want to compare one sequence against many
sequences, use @ref{22c6,,set_seq2()} to set the commonly used sequence once and
call @ref{22c7,,set_seq1()} repeatedly, once for each of the other sequences.

@geindex set_seq1() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher set_seq1}@anchor{22c7}
@deffn {Méthode} set_seq1 (a)

Set the first sequence to be compared.  The second sequence to be compared
is not changed.
@end deffn

@geindex set_seq2() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher set_seq2}@anchor{22c6}
@deffn {Méthode} set_seq2 (b)

Set the second sequence to be compared.  The first sequence to be compared
is not changed.
@end deffn

@geindex find_longest_match() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher find_longest_match}@anchor{18ec}
@deffn {Méthode} find_longest_match (alo=0, ahi=None, blo=0, bhi=None)

Find longest matching block in @code{a[alo:ahi]} and @code{b[blo:bhi]}.

If `isjunk' was omitted or @code{None}, @ref{18ec,,find_longest_match()} returns
@code{(i, j, k)} such that @code{a[i:i+k]} is equal to @code{b[j:j+k]}, where @code{alo
<= i <= i+k <= ahi} and @code{blo <= j <= j+k <= bhi}. For all @code{(i', j',
k')} meeting those conditions, the additional conditions @code{k >= k'}, @code{i
<= i'}, and if @code{i == i'}, @code{j <= j'} are also met. In other words, of
all maximal matching blocks, return one that starts earliest in `a', and
of all those maximal matching blocks that start earliest in `a', return
the one that starts earliest in `b'.

@example
>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=0, b=4, size=5)
@end example

If `isjunk' was provided, first the longest matching block is determined
as above, but with the additional restriction that no junk element appears
in the block.  Then that block is extended as far as possible by matching
(only) junk elements on both sides. So the resulting block never matches
on junk except as identical junk happens to be adjacent to an interesting
match.

Here's the same example as before, but considering blanks to be junk. That
prevents @code{' abcd'} from matching the @code{' abcd'} at the tail end of the
second sequence directly.  Instead only the @code{'abcd'} can match, and
matches the leftmost @code{'abcd'} in the second sequence:

@example
>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=1, b=0, size=4)
@end example

If no blocks match, this returns @code{(alo, blo, 0)}.

This method returns a @ref{639,,named tuple} @code{Match(a, b, size)}.


Modifié dans la version 3.9: Added default arguments.

@end deffn

@geindex get_matching_blocks() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher get_matching_blocks}@anchor{22c8}
@deffn {Méthode} get_matching_blocks ()

Return list of triples describing non-overlapping matching subsequences.
Each triple is of the form @code{(i, j, n)},
and means that @code{a[i:i+n] == b[j:j+n]}.  The
triples are monotonically increasing in `i' and `j'.

The last triple is a dummy, and has the value @code{(len(a), len(b), 0)}.  It
is the only triple with @code{n == 0}.  If @code{(i, j, n)} and @code{(i', j', n')}
are adjacent triples in the list, and the second is not the last triple in
the list, then @code{i+n < i'} or @code{j+n < j'}; in other words, adjacent
triples always describe non-adjacent equal blocks.

@c XXX Explain why a dummy is used!

@example
>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
@end example
@end deffn

@geindex get_opcodes() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher get_opcodes}@anchor{22c9}
@deffn {Méthode} get_opcodes ()

Return list of 5-tuples describing how to turn `a' into `b'. Each tuple is
of the form @code{(tag, i1, i2, j1, j2)}.  The first tuple has @code{i1 == j1 ==
0}, and remaining tuples have `i1' equal to the `i2' from the preceding
tuple, and, likewise, `j1' equal to the previous `j2'.

The `tag' values are strings, with these meanings:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Signification

@item

@code{'replace'}

@tab

@code{a[i1:i2]} should be replaced by
@code{b[j1:j2]}.

@item

@code{'delete'}

@tab

@code{a[i1:i2]} should be deleted.  Note that
@code{j1 == j2} in this case.

@item

@code{'insert'}

@tab

@code{b[j1:j2]} should be inserted at
@code{a[i1:i1]}. Note that @code{i1 == i2} in
this case.

@item

@code{'equal'}

@tab

@code{a[i1:i2] == b[j1:j2]} (the sub-sequences
are equal).

@end multitable


Par exemple :

@example
>>> a = "qabxcd"
>>> b = "abycdf"
>>> s = SequenceMatcher(None, a, b)
>>> for tag, i1, i2, j1, j2 in s.get_opcodes():
...     print('@{:7@}   a[@{@}:@{@}] --> b[@{@}:@{@}] @{!r:>8@} --> @{!r@}'.format(
...         tag, i1, i2, j1, j2, a[i1:i2], b[j1:j2]))
delete    a[0:1] --> b[0:0]      'q' --> '@w{'}
equal     a[1:3] --> b[0:2]     'ab' --> 'ab'
replace   a[3:4] --> b[2:3]      'x' --> 'y'
equal     a[4:6] --> b[3:5]     'cd' --> 'cd'
insert    a[6:6] --> b[5:6]       '@w{'} --> 'f'
@end example
@end deffn

@geindex get_grouped_opcodes() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher get_grouped_opcodes}@anchor{22ca}
@deffn {Méthode} get_grouped_opcodes (n=3)

Return a @ref{104a,,generator} of groups with up to `n' lines of context.

Starting with the groups returned by @ref{22c9,,get_opcodes()}, this method
splits out smaller change clusters and eliminates intervening ranges which
have no changes.

The groups are returned in the same format as @ref{22c9,,get_opcodes()}.
@end deffn

@geindex ratio() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher ratio}@anchor{22cb}
@deffn {Méthode} ratio ()

Return a measure of the sequences' similarity as a float in the range [0,
1].

Where T is the total number of elements in both sequences, and M is the
number of matches, this is 2.0*M / T. Note that this is @code{1.0} if the
sequences are identical, and @code{0.0} if they have nothing in common.

This is expensive to compute if @ref{22c8,,get_matching_blocks()} or
@ref{22c9,,get_opcodes()} hasn't already been called, in which case you may want
to try @ref{22cc,,quick_ratio()} or @ref{22cd,,real_quick_ratio()} first to get an
upper bound.

@cartouche
@quotation Note 
Caution: The result of a @ref{22cb,,ratio()} call may depend on the order of
the arguments. For instance:

@example
>>> SequenceMatcher(None, 'tide', 'diet').ratio()
0.25
>>> SequenceMatcher(None, 'diet', 'tide').ratio()
0.5
@end example
@end quotation
@end cartouche
@end deffn

@geindex quick_ratio() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher quick_ratio}@anchor{22cc}
@deffn {Méthode} quick_ratio ()

Return an upper bound on @ref{22cb,,ratio()} relatively quickly.
@end deffn

@geindex real_quick_ratio() (méthode difflib.SequenceMatcher)
@anchor{library/difflib difflib SequenceMatcher real_quick_ratio}@anchor{22cd}
@deffn {Méthode} real_quick_ratio ()

Return an upper bound on @ref{22cb,,ratio()} very quickly.
@end deffn
@end deffn

The three methods that return the ratio of matching to total characters can give
different results due to differing levels of approximation, although
@ref{22cc,,quick_ratio()} and @ref{22cd,,real_quick_ratio()}
are always at least as large as @ref{22cb,,ratio()}:

@example
>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0
@end example

@node SequenceMatcher Examples,Differ Objects,SequenceMatcher Objects,difflib --- Helpers for computing deltas
@anchor{library/difflib id1}@anchor{22ce}@anchor{library/difflib sequencematcher-examples}@anchor{22cf}
@subsubsection SequenceMatcher Examples


This example compares two strings, considering blanks to be "junk":

@example
>>> s = SequenceMatcher(lambda x: x == " ",
...                     "private Thread currentThread;",
...                     "private volatile Thread currentThread;")
@end example

@ref{22cb,,ratio()} returns a float in [0, 1], measuring the similarity of the
sequences.  As a rule of thumb, a @ref{22cb,,ratio()} value over 0.6 means the
sequences are close matches:

@example
>>> print(round(s.ratio(), 3))
0.866
@end example

If you're only interested in where the sequences match,
@ref{22c8,,get_matching_blocks()} is handy:

@example
>>> for block in s.get_matching_blocks():
...     print("a[%d] and b[%d] match for %d elements" % block)
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 21 elements
a[29] and b[38] match for 0 elements
@end example

Note that the last tuple returned by @ref{22c8,,get_matching_blocks()}
is always a dummy, @code{(len(a), len(b), 0)}, and this is the only case in which the last
tuple element (number of elements matched) is @code{0}.

If you want to know how to change the first sequence into the second, use
@ref{22c9,,get_opcodes()}:

@example
>>> for opcode in s.get_opcodes():
...     print("%6s a[%d:%d] b[%d:%d]" % opcode)
 equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
 equal a[8:29] b[17:38]
@end example


@subsubheading Voir aussi



@itemize *

@item 
The @ref{22bd,,get_close_matches()} function in this module which shows how
simple code building on @ref{1002,,SequenceMatcher} can be used to do useful
work.

@item 
Simple version control recipe@footnote{https://code.activestate.com/recipes/576729-simple-version-control/} for a small application
built with @ref{1002,,SequenceMatcher}.
@end itemize


@node Differ Objects,Differ Example,SequenceMatcher Examples,difflib --- Helpers for computing deltas
@anchor{library/difflib differ-objects}@anchor{22d0}@anchor{library/difflib id2}@anchor{22d1}
@subsubsection Differ Objects


Note that @ref{22b4,,Differ}-generated deltas make no claim to be `minimal'
diffs. To the contrary, minimal diffs are often counter-intuitive, because they
synch up anywhere possible, sometimes accidental matches 100 pages apart.
Restricting synch points to contiguous matches preserves some notion of
locality, at the occasional cost of producing a longer diff.

The @ref{22b4,,Differ} class has this constructor:


@deffn {Classe} difflib.Differ (linejunk=None, charjunk=None)

Optional keyword parameters `linejunk' and `charjunk' are for filter functions
(or @code{None}):

`linejunk': A function that accepts a single string argument, and returns true
if the string is junk.  The default is @code{None}, meaning that no line is
considered junk.

`charjunk': A function that accepts a single character argument (a string of
length 1), and returns true if the character is junk. The default is @code{None},
meaning that no character is considered junk.

These junk-filtering functions speed up matching to find
differences and do not cause any differing lines or characters to
be ignored.  Read the description of the
@ref{18ec,,find_longest_match()} method's `isjunk'
parameter for an explanation.

@ref{22b4,,Differ} objects are used (deltas generated) via a single method:

@geindex compare() (méthode difflib.Differ)
@anchor{library/difflib difflib Differ compare}@anchor{22c1}
@deffn {Méthode} compare (a, b)

Compare two sequences of lines, and generate the delta (a sequence of lines).

Each sequence must contain individual single-line strings ending with
newlines.  Such sequences can be obtained from the
@ref{22ba,,readlines()} method of file-like objects.  The delta
generated also consists of newline-terminated strings, ready to be
printed as-is via the @ref{22bb,,writelines()} method of a
file-like object.
@end deffn
@end deffn

@node Differ Example,A command-line interface to difflib,Differ Objects,difflib --- Helpers for computing deltas
@anchor{library/difflib differ-example}@anchor{22d2}@anchor{library/difflib differ-examples}@anchor{22d3}
@subsubsection Differ Example


This example compares two texts. First we set up the texts, sequences of
individual single-line strings ending with newlines (such sequences can also be
obtained from the @ref{22ba,,readlines()} method of file-like objects):

@example
>>> text1 = '@w{'}'  1. Beautiful is better than ugly.
...   2. Explicit is better than implicit.
...   3. Simple is better than complex.
...   4. Complex is better than complicated.
... '@w{'}'.splitlines(keepends=True)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = '@w{'}'  1. Beautiful is better than ugly.
...   3.   Simple is better than complex.
...   4. Complicated is better than complex.
...   5. Flat is better than nested.
... '@w{'}'.splitlines(keepends=True)
@end example

Next we instantiate a Differ object:

@example
>>> d = Differ()
@end example

Note that when instantiating a @ref{22b4,,Differ} object we may pass functions to
filter out line and character "junk."  See the @ref{22b4,,Differ()} constructor for
details.

Finally, we compare the two:

@example
>>> result = list(d.compare(text1, text2))
@end example

@code{result} is a list of strings, so let's pretty-print it:

@example
>>> from pprint import pprint
>>> pprint(result)
['    1. Beautiful is better than ugly.\n',
 '-   2. Explicit is better than implicit.\n',
 '-   3. Simple is better than complex.\n',
 '+   3.   Simple is better than complex.\n',
 '?     ++\n',
 '-   4. Complex is better than complicated.\n',
 '?            ^                     ---- ^\n',
 '+   4. Complicated is better than complex.\n',
 '?           ++++ ^                      ^\n',
 '+   5. Flat is better than nested.\n']
@end example

As a single multi-line string it looks like this:

@example
>>> import sys
>>> sys.stdout.writelines(result)
    1. Beautiful is better than ugly.
-   2. Explicit is better than implicit.
-   3. Simple is better than complex.
+   3.   Simple is better than complex.
?     ++
-   4. Complex is better than complicated.
?            ^                     ---- ^
+   4. Complicated is better than complex.
?           ++++ ^                      ^
+   5. Flat is better than nested.
@end example

@node A command-line interface to difflib,ndiff example,Differ Example,difflib --- Helpers for computing deltas
@anchor{library/difflib a-command-line-interface-to-difflib}@anchor{22d4}@anchor{library/difflib difflib-interface}@anchor{22bc}
@subsubsection A command-line interface to difflib


This example shows how to use difflib to create a @code{diff}-like utility.

@example
""" Command line interface to difflib.py providing diffs in four formats:

* ndiff:    lists every line and highlights interline changes.
* context:  highlights clusters of changes in a before/after format.
* unified:  highlights clusters of changes in an inline format.
* html:     generates side by side comparison with change highlights.

"""

import sys, os, difflib, argparse
from datetime import datetime, timezone

def file_mtime(path):
    t = datetime.fromtimestamp(os.stat(path).st_mtime,
                               timezone.utc)
    return t.astimezone().isoformat()

def main():

    parser = argparse.ArgumentParser()
    parser.add_argument('-c', action='store_true', default=False,
                        help='Produce a context format diff (default)')
    parser.add_argument('-u', action='store_true', default=False,
                        help='Produce a unified format diff')
    parser.add_argument('-m', action='store_true', default=False,
                        help='Produce HTML side by side diff '
                             '(can use -c and -l in conjunction)')
    parser.add_argument('-n', action='store_true', default=False,
                        help='Produce a ndiff format diff')
    parser.add_argument('-l', '--lines', type=int, default=3,
                        help='Set number of context lines (default 3)')
    parser.add_argument('fromfile')
    parser.add_argument('tofile')
    options = parser.parse_args()

    n = options.lines
    fromfile = options.fromfile
    tofile = options.tofile

    fromdate = file_mtime(fromfile)
    todate = file_mtime(tofile)
    with open(fromfile) as ff:
        fromlines = ff.readlines()
    with open(tofile) as tf:
        tolines = tf.readlines()

    if options.u:
        diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)
    elif options.n:
        diff = difflib.ndiff(fromlines, tolines)
    elif options.m:
        diff = difflib.HtmlDiff().make_file(fromlines,tolines,fromfile,tofile,context=options.c,numlines=n)
    else:
        diff = difflib.context_diff(fromlines, tolines, fromfile, tofile, fromdate, todate, n=n)

    sys.stdout.writelines(diff)

if __name__ == '__main__':
    main()
@end example

@node ndiff example,,A command-line interface to difflib,difflib --- Helpers for computing deltas
@anchor{library/difflib ndiff-example}@anchor{22d5}
@subsubsection ndiff example


This example shows how to use @ref{22b7,,difflib.ndiff()}.

@example
"""ndiff [-q] file1 file2
    or
ndiff (-r1 | -r2) < ndiff_output > file1_or_file2

Print a human-friendly file difference report to stdout.  Both inter-
and intra-line differences are noted.  In the second form, recreate file1
(-r1) or file2 (-r2) on stdout, from an ndiff report on stdin.

In the first form, if -q ("quiet") is not specified, the first two lines
of output are

-: file1
+: file2

Each remaining line begins with a two-letter code:

    "- "    line unique to file1
    "+ "    line unique to file2
    "  "    line common to both files
    "? "    line not present in either input file

Lines beginning with "? " attempt to guide the eye to intraline
differences, and were not present in either input file.  These lines can be
confusing if the source files contain tab characters.

The first file can be recovered by retaining only lines that begin with
"  " or "- ", and deleting those 2-character prefixes; use ndiff with -r1.

The second file can be recovered similarly, but by retaining only "  " and
"+ " lines; use ndiff with -r2; or, on Unix, the second file can be
recovered by piping the output through

    sed -n '/^[+ ] /s/^..//p'
"""

__version__ = 1, 7, 0

import difflib, sys

def fail(msg):
    out = sys.stderr.write
    out(msg + "\n\n")
    out(__doc__)
    return 0

# open a file & return the file object; gripe and return 0 if it
# couldn't be opened
def fopen(fname):
    try:
        return open(fname)
    except IOError as detail:
        return fail("couldn't open " + fname + ": " + str(detail))

# open two files & spray the diff to stdout; return false iff a problem
def fcompare(f1name, f2name):
    f1 = fopen(f1name)
    f2 = fopen(f2name)
    if not f1 or not f2:
        return 0

    a = f1.readlines(); f1.close()
    b = f2.readlines(); f2.close()
    for line in difflib.ndiff(a, b):
        print(line, end=' ')

    return 1

# crack args (sys.argv[1:] is normal) & compare;
# return false iff a problem

def main(args):
    import getopt
    try:
        opts, args = getopt.getopt(args, "qr:")
    except getopt.error as detail:
        return fail(str(detail))
    noisy = 1
    qseen = rseen = 0
    for opt, val in opts:
        if opt == "-q":
            qseen = 1
            noisy = 0
        elif opt == "-r":
            rseen = 1
            whichfile = val
    if qseen and rseen:
        return fail("can't specify both -q and -r")
    if rseen:
        if args:
            return fail("no args allowed with -r option")
        if whichfile in ("1", "2"):
            restore(whichfile)
            return 1
        return fail("-r value must be 1 or 2")
    if len(args) != 2:
        return fail("need 2 filename args")
    f1name, f2name = args
    if noisy:
        print('-:', f1name)
        print('+:', f2name)
    return fcompare(f1name, f2name)

# read ndiff output from stdin, and print file1 (which=='1') or
# file2 (which=='2') to stdout

def restore(which):
    restored = difflib.restore(sys.stdin.readlines(), which)
    sys.stdout.writelines(restored)

if __name__ == '__main__':
    main(sys.argv[1:])
@end example

@node textwrap --- Text wrapping and filling,unicodedata --- Unicode Database,difflib --- Helpers for computing deltas,Services de Manipulation de Texte
@anchor{library/textwrap doc}@anchor{22d6}@anchor{library/textwrap module-textwrap}@anchor{eb}@anchor{library/textwrap textwrap-text-wrapping-and-filling}@anchor{22d7}
@subsection @code{textwrap} --- Text wrapping and filling


@geindex module; textwrap

`Source code:' Lib/textwrap.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/textwrap.py}


__________________________________________________________________


Le module @ref{eb,,textwrap} fournit quelques fonctions pratiques, comme @ref{fb8,,TextWrapper}, la classe qui fait tout le travail. Si vous ne faites que formater ou ajuster une ou deux chaînes de texte, les fonctions de commodité devraient être assez bonnes ; sinon, nous vous conseillons d'utiliser une instance de @ref{fb8,,TextWrapper} pour une meilleure efficacité.

@geindex wrap() (dans le module textwrap)
@anchor{library/textwrap textwrap wrap}@anchor{147b}
@deffn {Fonction} textwrap.wrap (text, width=70, *, initial_indent='@w{'}, subsequent_indent='@w{'}, expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Reformate le paragraphe simple dans `text' (une chaîne de caractères) de sorte que chaque ligne ait au maximum `largeur' caractères. Renvoie une liste de lignes de sortie, sans ligne vide ou caractère de fin de ligne à la fin.

Optional keyword arguments correspond to the instance attributes of
@ref{fb8,,TextWrapper}, documented below.

Consultez la méthode @ref{22d8,,TextWrapper.wrap()} pour plus de détails sur le comportement de @ref{147b,,wrap()}.
@end deffn

@geindex fill() (dans le module textwrap)
@anchor{library/textwrap textwrap fill}@anchor{147a}
@deffn {Fonction} textwrap.fill (text, width=70, *, initial_indent='@w{'}, subsequent_indent='@w{'}, expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Formate le paragraphe unique dans `text' et renvoie une seule chaîne dont le contenu est le paragraphe formaté. @ref{147a,,fill()} est un raccourci pour

@example
"\n".join(wrap(text, ...))
@end example

En particulier, @ref{147a,,fill()} accepte exactement les mêmes arguments nommés que @ref{147b,,wrap()}.
@end deffn

@geindex shorten() (dans le module textwrap)
@anchor{library/textwrap textwrap shorten}@anchor{fbb}
@deffn {Fonction} textwrap.shorten (text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

Réduit et tronque le `text' donné pour l'adapter à la `largeur' donnée.

First the whitespace in `text' is collapsed (all whitespace is replaced by
single spaces).  If the result fits in the `width', it is returned.
Otherwise, enough words are dropped from the end so that the remaining words
plus the `placeholder' fit within `width':

@example
>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'
@end example

Les arguments nommés optionnels correspondent aux attributs d'instance de @ref{fb8,,TextWrapper}, documentés ci-dessous. Notez que l'espace blanc est réduit avant que le texte ne soit passé à la fonction @ref{147a,,fill()} de @ref{fb8,,TextWrapper}, donc changer la valeur de @ref{22d9,,tabsize}, @ref{22da,,expand_tabs}, @ref{22db,,drop_whitespace}, et @ref{22dc,,replace_whitespace} est sans effet.


Ajouté dans la version 3.4.

@end deffn

@geindex dedent() (dans le module textwrap)
@anchor{library/textwrap textwrap dedent}@anchor{22dd}
@deffn {Fonction} textwrap.dedent (text)

Supprime toutes les espaces en de tête de chaque ligne dans `text'.

Ceci peut être utilisé pour aligner les chaînes à trois guillemets avec le bord gauche de l'affichage, tout en les présentant sous forme indentée dans le code source.

Notez que les tabulations et les espaces sont traitées comme des espaces, mais qu'elles ne sont pas égales : les lignes @code{"  hello"} et @code{"\thello"} sont considérées comme n'ayant pas d'espaces de tête communes.

Les lignes contenant uniquement des espaces sont ignorées en entrée et réduites à un seul caractère de saut de ligne en sortie.

Par exemple :

@example
def test():
    # end first line with \ to avoid the empty line!
    s = '@w{'}'\
    hello
      world
    '@w{'}'
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'
@end example
@end deffn

@geindex indent() (dans le module textwrap)
@anchor{library/textwrap textwrap indent}@anchor{273}
@deffn {Fonction} textwrap.indent (text, prefix, predicate=None)

Ajoute `prefix' au début des lignes sélectionnées dans `text'.

Les lignes sont séparées en appelant @code{text.splitlines(True)}.

Par défaut, `prefix' est ajouté à toutes les lignes qui ne sont pas constituées uniquement d'espaces (y compris les fins de ligne).

Par exemple :

@example
>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'
@end example

L'argument optionnel `predicate' peut être utilisé pour contrôler quelles lignes sont en retrait. Par exemple, il est facile d'ajouter `prefix' aux lignes vides et aux lignes blanches seulement :

@example
>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world
@end example


Ajouté dans la version 3.3.

@end deffn

@ref{147b,,wrap()}, @ref{147a,,fill()} et @ref{fbb,,shorten()} travaillent en créant une instance @ref{fb8,,TextWrapper} et en appelant une méthode unique sur celle-ci. Cette instance n'est pas réutilisée, donc pour les applications qui traitent plusieurs chaînes de texte en utilisant @ref{147b,,wrap()} et/ou @ref{147a,,fill()}, il peut être plus efficace de créer votre propre objet @ref{fb8,,TextWrapper}.

Le formatage du texte s'effectue en priorité sur les espaces puis juste après les traits d'union dans des mots séparés par des traits d'union ; ce n'est qu'alors que les mots longs seront cassés si nécessaire, à moins que @ref{22de,,TextWrapper.break_long_words} soit défini sur `False'.

@geindex TextWrapper (classe dans textwrap)
@anchor{library/textwrap textwrap TextWrapper}@anchor{fb8}
@deffn {Classe} textwrap.TextWrapper (**kwargs)

Le constructeur @ref{fb8,,TextWrapper} accepte un certain nombre d'arguments nommés optionnels. Chaque argument nommé correspond à un attribut d'instance, donc par exemple

@example
wrapper = TextWrapper(initial_indent="* ")
@end example

est identique à

@example
wrapper = TextWrapper()
wrapper.initial_indent = "* "
@end example

You can reuse the same @ref{fb8,,TextWrapper} object many times, and you can
change any of its options through direct assignment to instance attributes
between uses.

Les attributs d'instance de la classe @ref{fb8,,TextWrapper} (et les arguments nommés au constructeur) sont les suivants :

@geindex width (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper width}@anchor{22df}
@deffn {Attribut} width

(par défaut : @code{70}) Longueur maximale des lignes reformatées. Tant qu'il n'y a pas de mots individuels dans le texte d'entrée plus longs que @ref{22df,,width}, @ref{fb8,,TextWrapper} garantit qu'aucune ligne de sortie n'est plus longue que @ref{22df,,width} caractères.
@end deffn

@geindex expand_tabs (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper expand_tabs}@anchor{22da}
@deffn {Attribut} expand_tabs

(default: @code{True}) If true, then all tab characters in `text' will be
expanded to spaces using the @ref{2145,,expandtabs()} method of `text'.
@end deffn

@geindex tabsize (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper tabsize}@anchor{22d9}
@deffn {Attribut} tabsize

(par défaut : @code{8}) Si @ref{22da,,expand_tabs} est vrai, alors tous les caractères de tabulation dans `text' sont transformés en zéro ou plus d'espaces, selon la colonne courante et la taille de tabulation donnée.


Ajouté dans la version 3.3.

@end deffn

@geindex replace_whitespace (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper replace_whitespace}@anchor{22dc}
@deffn {Attribut} replace_whitespace

(par défaut : @code{True}) Si vrai, après l'expansion des tabulations mais avant le formatage, la méthode @ref{147b,,wrap()} remplace chaque `blanc' par une espace unique. Les `blancs' remplacés sont les suivants : tabulation, nouvelle ligne, tabulation verticale, saut de page et retour chariot (@code{'\t\n\v\f\r'}).

@cartouche
@quotation Note 
Si @ref{22da,,expand_tabs} est `False' et @ref{22dc,,replace_whitespace} est vrai, chaque caractère de tabulation est remplacé par une espace unique, ce qui `n'est pas' la même chose que l'extension des tabulations.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Si @ref{22dc,,replace_whitespace} est faux, de nouvelles lignes peuvent apparaître au milieu d'une ligne et provoquer une sortie étrange. Pour cette raison, le texte doit être divisé en paragraphes (en utilisant @ref{1235,,str.splitlines()} ou similaire) qui sont formatés séparément.
@end quotation
@end cartouche
@end deffn

@geindex drop_whitespace (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper drop_whitespace}@anchor{22db}
@deffn {Attribut} drop_whitespace

(par défaut : @code{True}) Si `True', l'espace au début et à la fin de chaque ligne (après le formatage mais avant l'indentation) est supprimée. L'espace au début du paragraphe n'est cependant pas supprimée si elle n'est pas suivie par une espace. Si les espaces en cours de suppression occupent une ligne entière, la ligne entière est supprimée.
@end deffn

@geindex initial_indent (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper initial_indent}@anchor{22e0}
@deffn {Attribut} initial_indent

(par défaut : @code{'@w{'}}) Chaîne qui est ajoutée à la première ligne de la sortie formatée. Elle compte pour le calcul de la longueur de la première ligne. La chaîne vide n'est pas indentée.
@end deffn

@geindex subsequent_indent (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper subsequent_indent}@anchor{22e1}
@deffn {Attribut} subsequent_indent

(par défaut : @code{'@w{'}}) Chaîne qui préfixe toutes les lignes de la sortie formatée sauf la première. Elle compte pour le calcul de la longueur de chaque ligne à l'exception de la première.
@end deffn

@geindex fix_sentence_endings (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper fix_sentence_endings}@anchor{22e2}
@deffn {Attribut} fix_sentence_endings

(default: @code{False}) If true, @ref{fb8,,TextWrapper} attempts to detect
sentence endings and ensure that sentences are always separated by exactly
two spaces.  This is generally desired for text in a monospaced font.
However, the sentence detection algorithm is imperfect: it assumes that a
sentence ending consists of a lowercase letter followed by one of @code{'.'},
@code{'!'}, or @code{'?'}, possibly followed by one of @code{'"'} or @code{"'"},
followed by a space.  One problem with this algorithm is that it is
unable to detect the difference between "Dr." in

@example
[...] Dr. Frankenstein's monster [...]
@end example

et "Spot." dans

@example
[...] See Spot. See Spot run [...]
@end example

@ref{22e2,,fix_sentence_endings} est `False' par défaut.

Étant donné que l'algorithme de détection de phrases repose sur @code{string.lowercase} pour la définition de « lettres minuscules » et sur une convention consistant à utiliser deux espaces après un point pour séparer les phrases sur la même ligne, ceci est spécifique aux textes de langue anglaise.
@end deffn

@geindex break_long_words (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper break_long_words}@anchor{22de}
@deffn {Attribut} break_long_words

(par défaut : @code{True}) Si `True', alors les mots plus longs que @ref{22df,,width} sont cassés afin de s'assurer qu'aucune ligne ne soit plus longue que @ref{22df,,width}. Si c'est `False', les mots longs ne sont pas cassés et certaines lignes peuvent être plus longues que @ref{22df,,width} (les mots longs seront mis sur une ligne qui leur est propre, afin de minimiser le dépassement de @ref{22df,,width}).
@end deffn

@geindex break_on_hyphens (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper break_on_hyphens}@anchor{22e3}
@deffn {Attribut} break_on_hyphens

(par défaut : @code{True}) Si c'est vrai, le formatage se fait de préférence sur les espaces et juste après sur les traits d'union des mots composés, comme il est d'usage en anglais. Si `False', seuls les espaces sont considérées comme de bons endroits pour les sauts de ligne, mais vous devez définir @ref{22de,,break_long_words} à `False' si vous voulez des mots vraiment insécables. Le comportement par défaut dans les versions précédentes était de toujours permettre de couper les mots avec trait d'union.
@end deffn

@geindex max_lines (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper max_lines}@anchor{fb9}
@deffn {Attribut} max_lines

(par défaut : @code{None}) Si ce n'est pas @code{None}, alors la sortie contient au maximum `max_lines' lignes, avec `placeholder' à la fin de la sortie.


Ajouté dans la version 3.4.

@end deffn

@geindex ...;placeholder

@geindex placeholder (attribut textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper placeholder}@anchor{fba}
@deffn {Attribut} placeholder

(par défaut : @code{'@w{'} [...]'}) Chaîne qui apparaît à la fin du texte de sortie s'il a été tronqué.


Ajouté dans la version 3.4.

@end deffn

@ref{fb8,,TextWrapper} fournit également quelques méthodes publiques, analogues aux fonctions de commodité au niveau du module :

@geindex wrap() (méthode textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper wrap}@anchor{22d8}
@deffn {Méthode} wrap (text)

Formate le paragraphe unique dans `text' (une chaîne de caractères) de sorte que chaque ligne ait au maximum @ref{22df,,width} caractères. Toutes les options de formatage sont tirées des attributs d'instance de l'instance de classe @ref{fb8,,TextWrapper}. Renvoie une liste de lignes de sortie, sans nouvelles lignes finales. Si la sortie formatée n'a pas de contenu, la liste vide est renvoyée.
@end deffn

@geindex fill() (méthode textwrap.TextWrapper)
@anchor{library/textwrap textwrap TextWrapper fill}@anchor{22e4}
@deffn {Méthode} fill (text)

Formate le paragraphe unique de `text' et renvoie une seule chaîne contenant le paragraphe formaté.
@end deffn
@end deffn

@node unicodedata --- Unicode Database,stringprep --- Internet String Preparation,textwrap --- Text wrapping and filling,Services de Manipulation de Texte
@anchor{library/unicodedata doc}@anchor{22e5}@anchor{library/unicodedata module-unicodedata}@anchor{104}@anchor{library/unicodedata unicodedata-unicode-database}@anchor{22e6}
@subsection @code{unicodedata} --- Unicode Database


@geindex module; unicodedata

@geindex Unicode
@geindex character
@geindex Unicode;database


__________________________________________________________________


This module provides access to the Unicode Character Database (UCD) which
defines character properties for all Unicode characters. The data contained in
this database is compiled from the UCD version 15.1.0@footnote{https://www.unicode.org/Public/15.1.0/ucd}.

The module uses the same names and symbols as defined by Unicode
Standard Annex #44, "Unicode Character Database"@footnote{https://www.unicode.org/reports/tr44/}.  It defines the
following functions:

@geindex lookup() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata lookup}@anchor{1061}
@deffn {Fonction} unicodedata.lookup (name)

Retrouver un caractère par nom. Si un caractère avec le nom donné est trouvé, renvoyer le caractère correspondant. S'il n'est pas trouvé, @ref{33a,,KeyError} est levée.


Modifié dans la version 3.3: La gestion des alias @footnote{
@indicateurl{https://www.unicode.org/Public/15.1.0/ucd/NameAliases.txt}
} et des séquences nommées @footnote{
@indicateurl{https://www.unicode.org/Public/15.1.0/ucd/NamedSequences.txt}
} a été ajouté.

@end deffn

@geindex name() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata name}@anchor{22e7}
@deffn {Fonction} unicodedata.name (chr[, default])

Renvoie le nom assigné au caractère `chr' comme une chaîne de caractères. Si aucun nom n'est défini, `default' est renvoyé, ou, si ce dernier n'est pas renseigné @ref{1ff,,ValueError} est levée.
@end deffn

@geindex decimal() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata decimal}@anchor{22e8}
@deffn {Fonction} unicodedata.decimal (chr[, default])

Renvoie la valeur décimale assignée au caractère `chr' comme un entier. Si aucune valeur de ce type n'est définie, `default' est renvoyé, ou, si ce dernier n'est pas renseigné, @ref{1ff,,ValueError} est levée.
@end deffn

@geindex digit() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata digit}@anchor{22e9}
@deffn {Fonction} unicodedata.digit (chr[, default])

Renvoie le chiffre assigné au caractère `chr' comme un entier. Si aucune valeur de ce type n'est définie, `default' est renvoyé, ou, si ce dernier n'est pas renseigné, @ref{1ff,,ValueError} est levée.
@end deffn

@geindex numeric() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata numeric}@anchor{1241}
@deffn {Fonction} unicodedata.numeric (chr[, default])

Renvoie la valeur numérique assignée au caractère `chr' comme un entier. Si aucune valeur de ce type n'est définie, `default' est renvoyé, ou, si ce dernier n'est pas renseigné, @ref{1ff,,ValueError} est levée.
@end deffn

@geindex category() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata category}@anchor{22ea}
@deffn {Fonction} unicodedata.category (chr)

Renvoie la catégorie générale assignée au caractère `chr' comme une chaîne de caractères.
@end deffn

@geindex bidirectional() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata bidirectional}@anchor{22eb}
@deffn {Fonction} unicodedata.bidirectional (chr)

Renvoie la classe bidirectionnelle assignée au caractère `chr' comme une chaîne de caractères. Si aucune valeur de ce type n'est définie, une chaîne de caractères vide est renvoyée.
@end deffn

@geindex combining() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata combining}@anchor{22ec}
@deffn {Fonction} unicodedata.combining (chr)

Renvoie la classe de combinaison canonique assignée au caractère `chr' comme un entier. Envoie @code{0} si aucune classe de combinaison n'est définie.
@end deffn

@geindex east_asian_width() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata east_asian_width}@anchor{22ed}
@deffn {Fonction} unicodedata.east_asian_width (chr)

Renvoie la largeur est-asiatique assignée à un caractère `chr' comme une chaîne de caractères.
@end deffn

@geindex mirrored() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata mirrored}@anchor{22ee}
@deffn {Fonction} unicodedata.mirrored (chr)

Renvoie la propriété miroir assignée au caractère `chr' comme un entier. Renvoie @code{1} si le caractère a été identifié comme un caractère "réfléchi" dans du texte bidirectionnel, sinon @code{0}.
@end deffn

@geindex decomposition() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata decomposition}@anchor{22ef}
@deffn {Fonction} unicodedata.decomposition (chr)

Renvoie le tableau associatif de décomposition de caractère assigné au caractère `chr' comme une chaîne de caractères. Une chaîne de caractère vide est renvoyée dans le cas où aucun tableau associatif de ce type n'est défini.
@end deffn

@geindex normalize() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata normalize}@anchor{6bf}
@deffn {Fonction} unicodedata.normalize (form, unistr)

Renvoie la forme normale `form' de la chaîne de caractère Unicode `unistr'. Les valeurs valides de `form' sont `NFC', `NFKC', `NFD', et `NFKD'.

Le standard Unicode définit les différentes variantes de normalisation d'une chaîne de caractères Unicode en se basant sur les définitions d'équivalence canonique et d'équivalence de compatibilité. En Unicode, plusieurs caractères peuvent être exprimés de différentes façons. Par exemple, le caractère `U+00C7' (`LATIN CAPITAL LETTER C WITH CEDILLA') peut aussi être exprimé comme la séquence `U+0043' (`LATIN CAPITAL LETTER C') `U+0327' (`COMBINING CEDILLA').

Pour chaque caractère, il existe deux formes normales: la forme normale C et la forme normale D. La forme normale D (NFD) est aussi appelée décomposition canonique, et traduit chaque caractère dans sa forme décomposée. La forme normale C (NFC) applique d'abord la décomposition canonique, puis compose à nouveau les caractères pré-combinés.

En plus de ces deux formes, il existe deux formes nominales basées sur l'équivalence de compatibilité. En Unicode, certains caractères sont gérés alors qu'ils sont normalement unifiés avec d'autres caractères. Par exemple, U+2160 (ROMAN NUMERAL ONE) est vraiment la même chose que U+0049 (LATIN CAPITAL LETTER I). Cependant, ce caractère est supporté par souci de compatibilité avec les jeux de caractères existants (par exemple `gb2312').

La forme normale KD (NFKD) applique la décomposition de compatibilité, c'est-à-dire remplacer les caractères de compatibilités avec leurs équivalents. La forme normale KC (NFKC) applique d'abord la décomposition de compatibilité, puis applique la composition canonique.

Même si deux chaînes de caractères Unicode sont normalisées et ont la même apparence pour un lecteur humain , si un a des caractères combinés et l'autre n'en a pas, elles peuvent ne pas être égales lors d'une comparaison.
@end deffn

@geindex is_normalized() (dans le module unicodedata)
@anchor{library/unicodedata unicodedata is_normalized}@anchor{a37}
@deffn {Fonction} unicodedata.is_normalized (form, unistr)

Return whether the Unicode string `unistr' is in the normal form `form'. Valid
values for `form' are 'NFC', 'NFKC', 'NFD', and 'NFKD'.


Ajouté dans la version 3.8.

@end deffn

De plus, ce module expose la constante suivante :

@geindex unidata_version (dans le module unicodedata)
@anchor{library/unicodedata unicodedata unidata_version}@anchor{22f0}
@deffn {Données} unicodedata.unidata_version

La version de la base de données Unicode utilisée dans ce module.
@end deffn

@geindex ucd_3_2_0 (dans le module unicodedata)
@anchor{library/unicodedata unicodedata ucd_3_2_0}@anchor{13ea}
@deffn {Données} unicodedata.ucd_3_2_0

Ceci est un objet qui a les mêmes méthodes que le module, mais qui utilise la version 3.2 de la base de données Unicode, pour les applications qui nécessitent cette version spécifique de la base de données Unicode (comme l'IDNA).
@end deffn

Exemples :

@example
>>> import unicodedata
>>> unicodedata.lookup('LEFT CURLY BRACKET')
'@{'
>>> unicodedata.name('/')
'SOLIDUS'
>>> unicodedata.decimal('9')
9
>>> unicodedata.decimal('a')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: not a decimal
>>> unicodedata.category('A')  # 'L'etter, 'u'ppercase
'Lu'
>>> unicodedata.bidirectional('\u0660') # 'A'rabic, 'N'umber
'AN'
@end example

@subsubheading Notes


@node stringprep --- Internet String Preparation,readline --- GNU readline interface,unicodedata --- Unicode Database,Services de Manipulation de Texte
@anchor{library/stringprep doc}@anchor{22f1}@anchor{library/stringprep module-stringprep}@anchor{d3}@anchor{library/stringprep stringprep-internet-string-preparation}@anchor{22f2}
@subsection @code{stringprep} --- Internet String Preparation


@geindex module; stringprep

`Code source :' Lib/stringprep.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/stringprep.py}


__________________________________________________________________


Nommer les différentes choses d'internet (comme les hôtes) amène souvent au besoin de comparer ces identifiants, ce qui nécessite un critère d'« égalité ». La manière dont cette comparaison est effectuée dépend du domaine d'application, c'est-à-dire si elle doit être sensible à la casse ou non. Il peut être aussi nécessaire de restreindre les identifiants possibles, pour permettre uniquement les identifiants composés de caractères « imprimables ».

La 
@geindex RFC; RFC 3454
RFC 3454@footnote{https://datatracker.ietf.org/doc/html/rfc3454.html} définit une procédure pour "préparer" des chaines de caractères Unicode dans les protocoles internet. Avant de passer des chaines de caractères sur le câble, elles sont traitées avec la procédure de préparation, après laquelle ils obtiennent une certaines forme normalisée. Les RFC définissent un lot de tables, qui peuvent être combinées en profils. Chaque profil doit définir quelles tables il utilise et quelles autres parties optionnelles de la procédure `stringprep' font partie du profil. Un exemple de profil `stringprep' est `nameprep', qui est utilisé pour les noms de domaine internationalisés.

The module @ref{d3,,stringprep} only exposes the tables from 
@geindex RFC; RFC 3454
RFC 3454@footnote{https://datatracker.ietf.org/doc/html/rfc3454.html}. As these
tables would be very large to represent as dictionaries or lists, the
module uses the Unicode character database internally. The module source code
itself was generated using the @code{mkstringprep.py} utility.

En conséquence, ces tables sont exposées en tant que fonctions et non en structures de données. Il y a deux types de tables dans la RFC : les ensemble et les mises en correspondance. Pour un ensemble, @ref{d3,,stringprep} fournit la "fonction caractéristique", c'est-à-dire une fonction qui renvoie @code{True} si le paramètre fait partie de l'ensemble. Pour les mises en correspondance, il fournit la fonction de mise en correspondance : ayant obtenu la clé, il renvoie la valeur associée. Ci-dessous se trouve une liste de toutes les fonctions disponibles dans le module.

@geindex in_table_a1() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_a1}@anchor{22f3}
@deffn {Fonction} stringprep.in_table_a1 (code)

Détermine si le code est en table A.1 (points de code non-assigné dans Unicode 3.2).
@end deffn

@geindex in_table_b1() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_b1}@anchor{22f4}
@deffn {Fonction} stringprep.in_table_b1 (code)

Détermine si le code est en table B.1 (habituellement mis en correspondance avec rien).
@end deffn

@geindex map_table_b2() (dans le module stringprep)
@anchor{library/stringprep stringprep map_table_b2}@anchor{22f5}
@deffn {Fonction} stringprep.map_table_b2 (code)

Renvoie la valeur correspondante à `code' selon la table B.2 (mise en correspondance pour la gestion de la casse utilisée avec `NFKC').
@end deffn

@geindex map_table_b3() (dans le module stringprep)
@anchor{library/stringprep stringprep map_table_b3}@anchor{22f6}
@deffn {Fonction} stringprep.map_table_b3 (code)

Renvoie la valeur correspondante à `code' dans la table B.3 (mise en correspondance pour la gestion de la casse utilisée sans normalisation).
@end deffn

@geindex in_table_c11() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c11}@anchor{22f7}
@deffn {Fonction} stringprep.in_table_c11 (code)

Détermine si le code est dans la table C.1.1 (caractères d'espacement ASCII).
@end deffn

@geindex in_table_c12() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c12}@anchor{22f8}
@deffn {Fonction} stringprep.in_table_c12 (code)

Détermine si le code est dans la table C.1.2 (caractères d'espacement non ASCII).
@end deffn

@geindex in_table_c11_c12() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c11_c12}@anchor{22f9}
@deffn {Fonction} stringprep.in_table_c11_c12 (code)

Détermine si le code est dans la table C.1 (caractères d'espacement, union de C.1.1 et C.1.2).
@end deffn

@geindex in_table_c21() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c21}@anchor{22fa}
@deffn {Fonction} stringprep.in_table_c21 (code)

Détermine si le code est dans la table C.2.1 (caractères de contrôle ASCII).
@end deffn

@geindex in_table_c22() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c22}@anchor{22fb}
@deffn {Fonction} stringprep.in_table_c22 (code)

Détermine si le code est en table C.2.2 (caractères de contrôle non ASCII).
@end deffn

@geindex in_table_c21_c22() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c21_c22}@anchor{22fc}
@deffn {Fonction} stringprep.in_table_c21_c22 (code)

Détermine si le code est dans la table C.2 (caractères de contrôle, union de C.2.1 et C.2.2).
@end deffn

@geindex in_table_c3() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c3}@anchor{22fd}
@deffn {Fonction} stringprep.in_table_c3 (code)

Détermine si le code est en table C.3 (usage privé).
@end deffn

@geindex in_table_c4() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c4}@anchor{22fe}
@deffn {Fonction} stringprep.in_table_c4 (code)

Détermine si le code est dans la table C.4 (points de code non-caractère).
@end deffn

@geindex in_table_c5() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c5}@anchor{22ff}
@deffn {Fonction} stringprep.in_table_c5 (code)

Détermine si le code est en table C.5 (codes substituts).
@end deffn

@geindex in_table_c6() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c6}@anchor{2300}
@deffn {Fonction} stringprep.in_table_c6 (code)

Détermine si le code est dans la table C.6 (Inapproprié pour texte brut).
@end deffn

@geindex in_table_c7() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c7}@anchor{2301}
@deffn {Fonction} stringprep.in_table_c7 (code)

Détermine si le code est dans la table C.7 (inapproprié pour les représentations `canonics1').
@end deffn

@geindex in_table_c8() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c8}@anchor{2302}
@deffn {Fonction} stringprep.in_table_c8 (code)

Détermine si le code est dans la table C.8 (change de propriétés d'affichage ou sont obsolètes).
@end deffn

@geindex in_table_c9() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_c9}@anchor{2303}
@deffn {Fonction} stringprep.in_table_c9 (code)

Détermine si le code est dans la table C.9 (caractères de marquage).
@end deffn

@geindex in_table_d1() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_d1}@anchor{2304}
@deffn {Fonction} stringprep.in_table_d1 (code)

Détermine si le code est en table D.1 (caractères avec propriété bidirectionnelle "R" ou "AL").
@end deffn

@geindex in_table_d2() (dans le module stringprep)
@anchor{library/stringprep stringprep in_table_d2}@anchor{2305}
@deffn {Fonction} stringprep.in_table_d2 (code)

Détermine si le code est dans la table D.2 (caractères avec propriété bidirectionnelle "L").
@end deffn

@node readline --- GNU readline interface,rlcompleter --- Completion function for GNU readline,stringprep --- Internet String Preparation,Services de Manipulation de Texte
@anchor{library/readline doc}@anchor{2306}@anchor{library/readline module-readline}@anchor{b9}@anchor{library/readline readline-gnu-readline-interface}@anchor{2307}
@subsection @code{readline} --- GNU readline interface


@geindex module; readline


__________________________________________________________________


Le module @ref{b9,,readline} définit des fonctions pour faciliter la complétion et la lecture/écriture des fichiers d'historique depuis l'interpréteur Python. Ce module peut être utilisé directement, ou depuis le module @ref{bc,,rlcompleter}, qui gère la complétion des mots clefs dans l'invite de commande interactive. Les paramétrages faits en utilisant ce module affectent à la fois le comportement de l'invite de commande interactive et l'invite de commande fournie par la fonction native @ref{12b6,,input()}.

Readline keybindings may be configured via an initialization file, typically
@code{.inputrc} in your home directory.  See Readline Init File@footnote{https://tiswww.cwru.edu/php/chet/readline/rluserman.html#Readline-Init-File}
in the GNU Readline manual for information about the format and
allowable constructs of that file, and the capabilities of the
Readline library in general.

@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@cartouche
@quotation Note 
The underlying Readline library API may be implemented by
the @code{editline} (@code{libedit}) library instead of GNU readline.
On macOS the @ref{b9,,readline} module detects which library is being used
at run time.

The configuration file for @code{editline} is different from that
of GNU readline. If you programmatically load configuration strings
you can use @ref{1638,,backend} to determine which library is being used.

If you use @code{editline}/@code{libedit} readline emulation on macOS, the
initialization file located in your home directory is named
@code{.editrc}. For example, the following content in @code{~/.editrc} will
turn ON `vi' keybindings and TAB completion:

@example
python:bind -v
python:bind ^I rl_complete
@end example

Also note that different libraries may use different history file formats.
When switching the underlying library, existing history files may become
unusable.
@end quotation
@end cartouche

@geindex backend (dans le module readline)
@anchor{library/readline readline backend}@anchor{1638}
@deffn {Données} readline.backend

The name of the underlying Readline library being used, either
@code{"readline"} or @code{"editline"}.


Ajouté dans la version 3.13.

@end deffn

@menu
* Fichier d'initialisation:: 
* Tampon de ligne:: 
* Fichier d'historique:: 
* Liste d'historique:: 
* Fonctions de rappel au démarrage:: 
* Complétion:: 
* Exemple:: 

@end menu

@node Fichier d'initialisation,Tampon de ligne,,readline --- GNU readline interface
@anchor{library/readline init-file}@anchor{2308}
@subsubsection Fichier d'initialisation


Les fonctions suivantes se rapportent au fichier d'initialisation et à la configuration utilisateur :

@geindex parse_and_bind() (dans le module readline)
@anchor{library/readline readline parse_and_bind}@anchor{2309}
@deffn {Fonction} readline.parse_and_bind (string)

Exécute la ligne d'initialisation fournie dans l'argument `string'. Cela appelle la fonction @code{rl_parse_and_bind()} de la bibliothèque sous-jacente.
@end deffn

@geindex read_init_file() (dans le module readline)
@anchor{library/readline readline read_init_file}@anchor{230a}
@deffn {Fonction} readline.read_init_file ([filename])

Exécute un fichier d'initialisation `readline'. Le nom de fichier par défaut est le dernier nom de fichier utilisé. Cela appelle la fonction @code{rl_read_init_file()} de la bibliothèque sous-jacente.
@end deffn

@node Tampon de ligne,Fichier d'historique,Fichier d'initialisation,readline --- GNU readline interface
@anchor{library/readline line-buffer}@anchor{230b}
@subsubsection Tampon de ligne


Les fonctions suivantes opèrent sur le tampon de ligne :

@geindex get_line_buffer() (dans le module readline)
@anchor{library/readline readline get_line_buffer}@anchor{230c}
@deffn {Fonction} readline.get_line_buffer ()

Renvoie le contenu courant du tampon de ligne (@code{rl_line_buffer} dans la bibliothèque sous-jacente).
@end deffn

@geindex insert_text() (dans le module readline)
@anchor{library/readline readline insert_text}@anchor{230d}
@deffn {Fonction} readline.insert_text (string)

Insère du texte dans le tampon de ligne à la position du curseur. Cela appelle la fonction @code{rl_insert_text()} de la bibliothèque sous-jacente, mais ignore la valeur de retour.
@end deffn

@geindex redisplay() (dans le module readline)
@anchor{library/readline readline redisplay}@anchor{1479}
@deffn {Fonction} readline.redisplay ()

Change ce qui est affiché sur l'écran pour représenter le contenu courant de la ligne de tampon. Cela appelle la fonction @code{rl_redisplay()} dans la bibliothèque sous-jacente.
@end deffn

@node Fichier d'historique,Liste d'historique,Tampon de ligne,readline --- GNU readline interface
@anchor{library/readline history-file}@anchor{230e}
@subsubsection Fichier d'historique


les fonctions suivantes opèrent sur un fichier d'historique :

@geindex read_history_file() (dans le module readline)
@anchor{library/readline readline read_history_file}@anchor{230f}
@deffn {Fonction} readline.read_history_file ([filename])

Charge un fichier d'historique de `readline', et l'ajoute à la liste d'historique. Le fichier par défaut est @code{~/.history}. Cela appelle la fonction @code{read_history()} de la bibliothèque sous-jacente.
@end deffn

@geindex write_history_file() (dans le module readline)
@anchor{library/readline readline write_history_file}@anchor{2310}
@deffn {Fonction} readline.write_history_file ([filename])

Enregistre la liste de l'historique dans un fichier d'historique de `readline', en écrasant un éventuel fichier existant. Le nom de fichier par défaut est @code{~/.history}. Cela appelle la fonction @code{write_history()} de la bibliothèque sous-jacente.
@end deffn

@geindex append_history_file() (dans le module readline)
@anchor{library/readline readline append_history_file}@anchor{e3a}
@deffn {Fonction} readline.append_history_file (nelements[, filename])

Ajoute les derniers objets `nelements' de l'historique dans un fichier. Le nom de fichier par défaut est @code{~/.history}. Le fichier doit déjà exister. Cela appelle la fonction @code{append_history()} de la bibliothèque sous-jacente.


Ajouté dans la version 3.5.

@end deffn

@geindex get_history_length() (dans le module readline)
@geindex set_history_length() (dans le module readline)
@anchor{library/readline readline get_history_length}@anchor{2311}
@deffn {Fonction} readline.get_history_length ()
@anchor{library/readline readline set_history_length}@anchor{157e}
@deffnx {Fonction} readline.set_history_length (length)

Définit ou renvoie le nombre souhaité de lignes à enregistrer dans le fichier d'historique. La fonction @ref{2310,,write_history_file()} utilise cette valeur pour tronquer le fichier d'historique, en appelant @code{history_truncate_file()} de la bibliothèque sous-jacente. Les valeurs négatives impliquent une taille de fichier d'historique illimitée.
@end deffn

@node Liste d'historique,Fonctions de rappel au démarrage,Fichier d'historique,readline --- GNU readline interface
@anchor{library/readline history-list}@anchor{2312}
@subsubsection Liste d'historique


Les fonctions suivantes opèrent sur une liste d'historique globale :

@geindex clear_history() (dans le module readline)
@anchor{library/readline readline clear_history}@anchor{2313}
@deffn {Fonction} readline.clear_history ()

Effacer l'historique courant. Cela appelle la fonction @code{clear_history()} de la bibliothèque sous-jacente. La fonction Python existe seulement si Python à été compilé pour une version de la bibliothèque qui le gère.
@end deffn

@geindex get_current_history_length() (dans le module readline)
@anchor{library/readline readline get_current_history_length}@anchor{1478}
@deffn {Fonction} readline.get_current_history_length ()

Renvoie le nombre d'objets actuellement dans l'historique. (C'est différent de @ref{2311,,get_history_length()}, qui renvoie le nombre maximum de lignes qui vont être écrites dans un fichier d'historique.)
@end deffn

@geindex get_history_item() (dans le module readline)
@anchor{library/readline readline get_history_item}@anchor{1477}
@deffn {Fonction} readline.get_history_item (index)

Renvoie le contenu courant de l'objet d'historique à `index'. L'index de l'objet commence à 1. Cela appelle @code{history_get()} de la bibliothèque sous-jacente.
@end deffn

@geindex remove_history_item() (dans le module readline)
@anchor{library/readline readline remove_history_item}@anchor{2314}
@deffn {Fonction} readline.remove_history_item (pos)

Supprime l'objet de l'historique défini par sa position depuis l'historique. L'index de la position commence à zéro. Cela appelle la fonction @code{remove_history()} de la bibliothèque sous-jacente.
@end deffn

@geindex replace_history_item() (dans le module readline)
@anchor{library/readline readline replace_history_item}@anchor{2315}
@deffn {Fonction} readline.replace_history_item (pos, line)

Remplace un objet de l'historique à la position définie par `line'. L'index de la position commence à zéro. Cela appelle @code{replace_history_entry()} de la bibliothèque sous-jacente.
@end deffn

@geindex add_history() (dans le module readline)
@anchor{library/readline readline add_history}@anchor{2316}
@deffn {Fonction} readline.add_history (line)

Ajoute `line' au tampon d'historique, comme si c'était la dernière ligne saisie. Cela appelle la fonction @code{add_history()} de la libraire sous-jacente.
@end deffn

@geindex set_auto_history() (dans le module readline)
@anchor{library/readline readline set_auto_history}@anchor{cb8}
@deffn {Fonction} readline.set_auto_history (enabled)

Active ou désactive les appels automatiques à la fonction @code{add_history()} lors de la lecture d'une entrée via `readline'. L'argument `enabled' doit être une valeur booléenne qui lorsqu'elle est vraie, active l'historique automatique, et qui lorsqu'elle est fausse, désactive l'historique automatique.


Ajouté dans la version 3.6.


`Particularité de l'implémentation CPython :' Auto history is enabled by default, and changes to this do not persist
across multiple sessions.
@end deffn

@node Fonctions de rappel au démarrage,Complétion,Liste d'historique,readline --- GNU readline interface
@anchor{library/readline startup-hooks}@anchor{2317}
@subsubsection Fonctions de rappel au démarrage


@geindex set_startup_hook() (dans le module readline)
@anchor{library/readline readline set_startup_hook}@anchor{2318}
@deffn {Fonction} readline.set_startup_hook ([function])

Définit ou supprime la fonction invoquée par le la fonction de retour @code{rl_startup_hook} de la bibliothèque sous-jacente. Si `function' est spécifié, il est utilisé en tant que nouvelle fonction de rappel ; si omis ou @code{None}, toute fonction déjà installée est supprimée. La fonction de rappel est appelée sans arguments juste avant que `readline' affiche la première invite de commande.
@end deffn

@geindex set_pre_input_hook() (dans le module readline)
@anchor{library/readline readline set_pre_input_hook}@anchor{2319}
@deffn {Fonction} readline.set_pre_input_hook ([function])

Définit ou supprime la fonction invoquée par la fonction de retour @code{rl_pre_input_hook} de la bibliothèque sous-jacente. Si `function' est spécifié, il sera utilisé par la nouvelle fonction de rappel ; si omis ou @code{None}, toute fonction déjà installée est supprimée. La fonction de rappel est appelée sans arguments après que la première invite de commande ait été affichée et juste avant que `readline' commence à lire les caractères saisis. Cette fonction existe seulement si Python a été compilé pour une version de la bibliothèque qui le gère.
@end deffn

@node Complétion,Exemple,Fonctions de rappel au démarrage,readline --- GNU readline interface
@anchor{library/readline completion}@anchor{231a}@anchor{library/readline readline-completion}@anchor{231b}
@subsubsection Complétion


Les fonctions suivantes relatent comment implémenter une fonction de complétion d'un mot spécifique. C'est typiquement déclenché par la touche Tab, et peut suggérer et automatiquement compléter un mot en cours de saisie. Par défaut, Readline est configuré pour être utilisé par @ref{bc,,rlcompleter} pour compléter les mots clefs de Python pour l'interpréteur interactif. Si le module @ref{b9,,readline} doit être utilisé avec une complétion spécifique, un ensemble de mots délimiteurs doivent être définis.

@geindex set_completer() (dans le module readline)
@anchor{library/readline readline set_completer}@anchor{231c}
@deffn {Fonction} readline.set_completer ([function])

Définit ou supprime la fonction de complétion. Si `function' est spécifié, il sera utilisé en tant que nouvelle fonction de complétion; si omis ou @code{None}, toute fonction de complétion déjà installé est supprimé. La fonction de complétion est appelée telle que @code{function(text, state)}, pour `state' valant @code{0}, @code{1}, @code{2}, ..., jusqu'à ce qu'elle renvoie une valeur qui n'est pas une chaîne de caractères. Elle doit renvoyer les prochaines complétions possibles commençant par `text'.

La fonction de complétion installée est invoquée par la fonction de retour `entry_func' passée à @code{rl_completion_matches()} de la bibliothèque sous-jacente. La chaîne de caractère `text' va du premier paramètres vers la fonction de retour @code{rl_attempted_completion_function} de la bibliothèque sous-jacente.
@end deffn

@geindex get_completer() (dans le module readline)
@anchor{library/readline readline get_completer}@anchor{231d}
@deffn {Fonction} readline.get_completer ()

Récupère la fonction de complétion, ou @code{None} si aucune fonction de complétion n'a été définie.
@end deffn

@geindex get_completion_type() (dans le module readline)
@anchor{library/readline readline get_completion_type}@anchor{231e}
@deffn {Fonction} readline.get_completion_type ()

Récupère le type de complétion essayé. Cela renvoie la variable @code{rl_completion_type} dans la bibliothèque sous-jacente en tant qu'entier.
@end deffn

@geindex get_begidx() (dans le module readline)
@geindex get_endidx() (dans le module readline)
@anchor{library/readline readline get_begidx}@anchor{1874}
@deffn {Fonction} readline.get_begidx ()
@anchor{library/readline readline get_endidx}@anchor{1875}
@deffnx {Fonction} readline.get_endidx ()

Get the beginning or ending index of the completion scope.
These indexes are the `start' and `end' arguments passed to the
@code{rl_attempted_completion_function} callback of the
underlying library.  The values may be different in the same
input editing scenario based on the underlying C readline implementation.
Ex: libedit is known to behave differently than libreadline.
@end deffn

@geindex set_completer_delims() (dans le module readline)
@geindex get_completer_delims() (dans le module readline)
@anchor{library/readline readline set_completer_delims}@anchor{163c}
@deffn {Fonction} readline.set_completer_delims (string)
@anchor{library/readline readline get_completer_delims}@anchor{231f}
@deffnx {Fonction} readline.get_completer_delims ()

Définit ou récupère les mots délimitants pour la complétion. Ceux-ci déterminent le début du mot devant être considéré pour la complétion (le contexte de la complétion). Ces fonctions accèdent à la variable @code{rl_completer_word_break_characters}  de la bibliothèque sous-jacente.
@end deffn

@geindex set_completion_display_matches_hook() (dans le module readline)
@anchor{library/readline readline set_completion_display_matches_hook}@anchor{2320}
@deffn {Fonction} readline.set_completion_display_matches_hook ([function])

Définit ou supprime la fonction d'affichage de la complétion. Si `function' est spécifié, il sera utilisé en tant que nouvelle fonction d'affichage de complétion; si omis ou @code{None}, toute fonction de complétion déjà installée est supprimée. Cela définit ou supprime la fonction de retour @code{rl_completion_display_matches_hook} dans la bibliothèque sous-jacente. La fonction d'affichage de complétion est appelée telle que @code{function(substitution, [matches], longest_match_length)} une seule fois lorsque les correspondances doivent être affichées.
@end deffn

@node Exemple,,Complétion,readline --- GNU readline interface
@anchor{library/readline example}@anchor{2321}@anchor{library/readline readline-example}@anchor{2322}
@subsubsection Exemple


L'exemple suivant démontre comment utiliser les fonctions de lecture et d'écriture de l'historique du module @ref{b9,,readline} pour charger ou sauvegarder automatiquement un fichier d'historique nommé @code{.python_history} depuis le répertoire d’accueil de l’utilisateur. Le code ci-dessous doit normalement être exécuté automatiquement durant une session interactive depuis le fichier de l'utilisateur 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP}.

@example
import atexit
import os
import readline

histfile = os.path.join(os.path.expanduser("~"), ".python_history")
try:
    readline.read_history_file(histfile)
    # default history len is -1 (infinite), which may grow unruly
    readline.set_history_length(1000)
except FileNotFoundError:
    pass

atexit.register(readline.write_history_file, histfile)
@end example

Ce code est en réalité automatiquement exécuté lorsque Python tourne en @ref{fb1,,mode interactif} (voir @ref{fb4,,Readline configuration}).

L'exemple suivant atteint le même objectif mais gère des sessions interactives concurrentes, en ajoutant seulement le nouvel historique.

@example
import atexit
import os
import readline
histfile = os.path.join(os.path.expanduser("~"), ".python_history")

try:
    readline.read_history_file(histfile)
    h_len = readline.get_current_history_length()
except FileNotFoundError:
    open(histfile, 'wb').close()
    h_len = 0

def save(prev_h_len, histfile):
    new_h_len = readline.get_current_history_length()
    readline.set_history_length(1000)
    readline.append_history_file(new_h_len - prev_h_len, histfile)
atexit.register(save, h_len, histfile)
@end example

L'exemple suivant étend la classe @ref{2323,,code.InteractiveConsole} pour gérer la sauvegarde/restauration de l'historique.

@example
import atexit
import code
import os
import readline

class HistoryConsole(code.InteractiveConsole):
    def __init__(self, locals=None, filename="<console>",
                 histfile=os.path.expanduser("~/.console-history")):
        code.InteractiveConsole.__init__(self, locals, filename)
        self.init_history(histfile)

    def init_history(self, histfile):
        readline.parse_and_bind("tab: complete")
        if hasattr(readline, "read_history_file"):
            try:
                readline.read_history_file(histfile)
            except FileNotFoundError:
                pass
            atexit.register(self.save_history, histfile)

    def save_history(self, histfile):
        readline.set_history_length(1000)
        readline.write_history_file(histfile)
@end example

@node rlcompleter --- Completion function for GNU readline,,readline --- GNU readline interface,Services de Manipulation de Texte
@anchor{library/rlcompleter doc}@anchor{2324}@anchor{library/rlcompleter module-rlcompleter}@anchor{bc}@anchor{library/rlcompleter rlcompleter-completion-function-for-gnu-readline}@anchor{2325}
@subsection @code{rlcompleter} --- Completion function for GNU readline


@geindex module; rlcompleter

`Code source :' Lib/rlcompleter.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/rlcompleter.py}


__________________________________________________________________


The @code{rlcompleter} module defines a completion function suitable to be
passed to @ref{231c,,set_completer()} in the @ref{b9,,readline} module.

When this module is imported on a Unix platform with the @ref{b9,,readline} module
available, an instance of the @ref{18d1,,Completer} class is automatically created
and its @ref{2326,,complete()} method is set as the
@ref{231b,,readline completer}. The method provides
completion of valid Python @ref{1e1a,,identifiers and keywords}.

Exemple :

@example
>>> import rlcompleter
>>> import readline
>>> readline.parse_and_bind("tab: complete")
>>> readline. <TAB PRESSED>
readline.__doc__          readline.get_line_buffer(  readline.read_init_file(
readline.__file__         readline.insert_text(      readline.set_completer(
readline.__name__         readline.parse_and_bind(
>>> readline.
@end example

The @code{rlcompleter} module is designed for use with Python's
@ref{fb1,,interactive mode}.  Unless Python is run with the
@ref{1186,,-S} option, the module is automatically imported and configured
(see @ref{fb4,,Readline configuration}).

Sur les plate-formes sans @ref{b9,,readline}, la classe @ref{18d1,,Completer} définie par ce module peut quand même être utilisée pour des fins personnalisées.

@geindex Completer (classe dans rlcompleter)
@anchor{library/rlcompleter completer-objects}@anchor{2327}@anchor{library/rlcompleter rlcompleter Completer}@anchor{18d1}
@deffn {Classe} rlcompleter.Completer

Les objets pour la complétion (`Completer objects' en anglais) disposent de la méthode suivante :

@geindex complete() (méthode rlcompleter.Completer)
@anchor{library/rlcompleter rlcompleter Completer complete}@anchor{2326}
@deffn {Méthode} complete (text, state)

Return the next possible completion for `text'.

When called by the @ref{b9,,readline} module, this method is called
successively with @code{state == 0, 1, 2, ...} until the method returns
@code{None}.

Si `text' ne contient pas un caractère point (@code{'.'}), il puise dans les noms actuellement définis dans @ref{1,,__main__}, @ref{12,,builtins} ainsi que les mots-clés (ainsi que définis par le module @ref{83,,keyword})

If called for a dotted name, it will try to evaluate anything without obvious
side-effects (functions will not be evaluated, but it can generate calls to
@ref{4bc,,__getattr__()}) up to the last part, and find matches for the
rest via the @ref{61d,,dir()} function.  Any exception raised during the
evaluation of the expression is caught, silenced and @ref{660,,None} is
returned.
@end deffn
@end deffn

@node Services autour des Données Binaires,Types de données,Services de Manipulation de Texte,La bibliothèque standard
@anchor{library/binary doc}@anchor{2328}@anchor{library/binary binary-data-services}@anchor{2329}@anchor{library/binary binaryservices}@anchor{2242}
@section Services autour des Données Binaires


Les modules décrits dans ce chapitre fournissent des services élémentaires pour manipuler des données binaires. Les autres manipulations sur les données binaires, particulièrement celles en relation avec les formats de fichier et les protocoles réseaux sont décrits dans leurs propres chapitres.

Certaines bibliothèques décrites dans @ref{2143,,Services de Manipulation de Texte} fonctionnent aussi avec soit des formats binaires compatibles ASCII (comme le module @ref{b8,,re}) soit toutes les données binaires (comme le module @ref{37,,difflib}).

En complément, consultez la documentation des types natifs binaires dans @ref{20e8,,Séquences Binaires — bytes@comma{} bytearray@comma{} vue mémoire}.

@menu
* struct: struct --- Interpret bytes as packed binary data. Interpret bytes as packed binary data
* codecs: codecs --- Codec registry and base classes. Codec registry and base classes

@end menu

@node struct --- Interpret bytes as packed binary data,codecs --- Codec registry and base classes,,Services autour des Données Binaires
@anchor{library/struct doc}@anchor{232a}@anchor{library/struct struct-interpret-bytes-as-packed-binary-data}@anchor{232b}
@subsection @code{struct} --- Interpret bytes as packed binary data


@c from struct import *

@geindex module; struct
@anchor{library/struct module-struct}@anchor{d4}
`Code source :' Lib/struct.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/struct.py}

@geindex C;structures
@geindex packing;binary;data


__________________________________________________________________


This module converts between Python values and C structs represented
as Python @ref{1bd,,bytes} objects.  Compact @ref{232c,,format strings}
describe the intended conversions to/from Python values.
The module's functions and objects can be used for two largely
distinct applications, data exchange with external sources (files or
network connections), or data transfer between the Python application
and the C layer.

@cartouche
@quotation Note 
When no prefix character is given, native mode is the default. It
packs or unpacks data based on the platform and compiler on which
the Python interpreter was built.
The result of packing a given C struct includes pad bytes which
maintain proper alignment for the C types involved; similarly,
alignment is taken into account when unpacking.  In contrast, when
communicating data between external sources, the programmer is
responsible for defining byte ordering and padding between elements.
See @ref{232d,,Boutisme@comma{} taille et alignement} for details.
@end quotation
@end cartouche

Plusieurs fonctions de @ref{d4,,struct} (et méthodes de @ref{163a,,Struct}) prennent un argument `buffer'. Cet argument fait référence à des objets qui implémentent @ref{38e,,le protocole tampon} et qui proposent un tampon soit en lecture seule, soit en lecture-écriture. Les types les plus courants qui utilisent cette fonctionnalité sont @ref{1bd,,bytes} et @ref{528,,bytearray}, mais beaucoup d'autres types qui peuvent être considérés comme des tableaux d'octets implémentent le protocole tampon ; ils peuvent ainsi être lus ou remplis depuis un objet @ref{1bd,,bytes} sans faire de copie.

@menu
* Fonctions et exceptions:: 
* Chaînes de spécification du format:: 
* Applications:: 
* Classes: Classes<3>. 

@end menu

@node Fonctions et exceptions,Chaînes de spécification du format,,struct --- Interpret bytes as packed binary data
@anchor{library/struct functions-and-exceptions}@anchor{232e}
@subsubsection Fonctions et exceptions


Le module définit les exceptions et fonctions suivantes :

@geindex error
@anchor{library/struct struct error}@anchor{1301}
@deffn {Exception} struct.error

Exception levée à plusieurs occasions ; l'argument est une chaîne qui décrit ce qui ne va pas.
@end deffn

@geindex pack() (dans le module struct)
@anchor{library/struct struct pack}@anchor{1255}
@deffn {Fonction} struct.pack (format, v1, v2, ...)

Renvoie un objet `bytes' contenant les valeurs `v1', `v2'… agrégées conformément à la chaîne de format `format'. Les arguments doivent correspondre exactement aux valeurs requises par le format.
@end deffn

@geindex pack_into() (dans le module struct)
@anchor{library/struct struct pack_into}@anchor{232f}
@deffn {Fonction} struct.pack_into (format, buffer, offset, v1, v2, ...)

Agrège les valeurs `v1', `v2'… conformément à la chaîne de format `format' et écrit les octets agrégés dans le tampon `buffer', en commençant à la position `offset'. Notez que `offset' est un argument obligatoire.
@end deffn

@geindex unpack() (dans le module struct)
@anchor{library/struct struct unpack}@anchor{1754}
@deffn {Fonction} struct.unpack (format, buffer)

Dissocie depuis le tampon `buffer' (en supposant que celui-ci a été agrégé avec @code{pack(format, …)}) à l'aide de la chaîne de format `format'. Le résultat est un `n'-uplet, qui peut éventuellement ne contenir qu'un seul élément. La taille de `buffer' en octets doit correspondre à la taille requise par le format, telle que calculée par @ref{1952,,calcsize()}.
@end deffn

@geindex unpack_from() (dans le module struct)
@anchor{library/struct struct unpack_from}@anchor{2330}
@deffn {Fonction} struct.unpack_from (format, /, buffer, offset=0)

Dissocie les éléments du tampon `buffer', en commençant à la position `offset', conformément à la chaîne de format `format'. Le résultat est un n-uplet, qui peut éventuellement ne contenir qu'un seul élément. La taille du tampon en octets, en commençant à la position `offset', doit être au moins égale à la taille requise par le format, telle que calculée par @ref{1952,,calcsize()}.
@end deffn

@geindex iter_unpack() (dans le module struct)
@anchor{library/struct struct iter_unpack}@anchor{fa9}
@deffn {Fonction} struct.iter_unpack (format, buffer)

Iteratively unpack from the buffer `buffer' according to the format
string `format'.  This function returns an iterator which will read
equally sized chunks from the buffer until all its contents have been
consumed.  The buffer's size in bytes must be a multiple of the size
required by the format, as reflected by @ref{1952,,calcsize()}.

Chaque itération produit un `n'-uplet tel que spécifié par la chaîne de format.


Ajouté dans la version 3.4.

@end deffn

@geindex calcsize() (dans le module struct)
@anchor{library/struct struct calcsize}@anchor{1952}
@deffn {Fonction} struct.calcsize (format)

Renvoie la taille de la structure (et donc celle de l'objet `bytes' produit par @code{pack(format, ...)}) correspondant à la chaîne de format `format'.
@end deffn

@node Chaînes de spécification du format,Applications,Fonctions et exceptions,struct --- Interpret bytes as packed binary data
@anchor{library/struct format-strings}@anchor{2331}@anchor{library/struct struct-format-strings}@anchor{232c}
@subsubsection Chaînes de spécification du format


Format strings describe the data layout when
packing and unpacking data.  They are built up from @ref{2332,,format characters},
which specify the type of data being packed/unpacked.  In addition,
special characters control the @ref{232d,,byte order@comma{} size and alignment}.
Each format string consists of an optional prefix character which
describes the overall properties of the data and one or more format
characters which describe the actual data values and padding.

@menu
* Boutisme@comma{} taille et alignement: Boutisme taille et alignement. 
* Caractères de format:: 
* Exemples: Exemples<2>. 

@end menu

@node Boutisme taille et alignement,Caractères de format,,Chaînes de spécification du format
@anchor{library/struct byte-order-size-and-alignment}@anchor{2333}@anchor{library/struct struct-alignment}@anchor{232d}
@subsubsection Boutisme, taille et alignement


By default, C types are represented in the machine's native format and byte
order, and properly aligned by skipping pad bytes if necessary (according to the
rules used by the C compiler).
This behavior is chosen so
that the bytes of a packed struct correspond exactly to the memory layout
of the corresponding C struct.
Whether to use native byte ordering
and padding or standard formats depends on the application.

@geindex @@ (at);in struct format strings
@geindex = (equals);in struct format strings
@geindex < (less);in struct format strings
@geindex > (greater);in struct format strings
@geindex ! (exclamation);in struct format strings

Cependant, le premier caractère de la chaîne de format peut être utilisé pour indiquer le boutisme, la taille et l'alignement des données agrégées, conformément à la table suivante :


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxxxxx} 
@headitem

Caractère

@tab

Boutisme

@tab

Taille

@tab

Alignement

@item

@code{@@}

@tab

natif

@tab

natif

@tab

natif

@item

@code{=}

@tab

natif

@tab

standard

@tab

aucun

@item

@code{<}

@tab

petit-boutiste

@tab

standard

@tab

aucun

@item

@code{>}

@tab

gros-boutiste

@tab

standard

@tab

aucun

@item

@code{!}

@tab

réseau (= gros-boutiste)

@tab

standard

@tab

aucun

@end multitable


Si le premier caractère n'est pas dans cette liste, le module se comporte comme si @code{'@@'} avait été indiqué.

@cartouche
@quotation Note 
The number 1023 (@code{0x3ff} in hexadecimal) has the following byte representations:


@itemize *

@item 
@code{03 ff} in big-endian (@code{>})

@item 
@code{ff 03} in little-endian (@code{<})
@end itemize

Python example:

@example
>>> import struct
>>> struct.pack('>h', 1023)
b'\x03\xff'
>>> struct.pack('<h', 1023)
b'\xff\x03'
@end example
@end quotation
@end cartouche

Native byte order is big-endian or little-endian, depending on the
host system. For example, Intel x86, AMD64 (x86-64), and Apple M1 are
little-endian; IBM z and many legacy architectures are big-endian.
Use @ref{2124,,sys.byteorder} to check the endianness of your system.

La taille et l'alignement natifs sont déterminés en utilisant l'expression @code{sizeof} du compilateur C. Leur valeur est toujours combinée au boutisme natif.

La taille standard dépend seulement du caractère du format ; référez-vous au tableau dans la section @ref{2332,,Caractères de format}.

Notez la différence entre @code{'@@'} et @code{'='} : les deux utilisent le boutisme natif mais la taille et l'alignement du dernier sont standards.

The form @code{'!'} represents the network byte order which is always big-endian
as defined in IETF RFC 1700@footnote{https://datatracker.ietf.org/doc/html/rfc1700}.

Il n'y a pas de moyen de spécifier le boutisme contraire au boutisme natif (c'est-à-dire forcer la permutation des octets) ; utilisez le bon caractère entre @code{'<'} et @code{'>'}.

Notes :


@enumerate 

@item 
Le bourrage (`padding' en anglais) n'est automatiquement ajouté qu'entre les membres successifs de la structure. Il n'y a pas de bourrage au début ou à la fin de la structure agrégée.

@item 
Il n'y a pas d'ajout de bourrage lorsque vous utilisez une taille et un alignement non-natifs, par exemple avec @code{'<'}, @code{'>'}, @code{'='} ou @code{'!'}.

@item 
Pour aligner la fin d'une structure à l'alignement requis par un type particulier, terminez le format avec le code du type voulu et une valeur de répétition à zéro. Référez-vous à @ref{2334,,Exemples}.
@end enumerate

@node Caractères de format,Exemples<2>,Boutisme taille et alignement,Chaînes de spécification du format
@anchor{library/struct format-characters}@anchor{2332}@anchor{library/struct id1}@anchor{2335}
@subsubsection Caractères de format


Les caractères de format possèdent les significations suivantes ; la conversion entre les valeurs C et Python doit être évidente compte tenu des types concernés. La colonne « taille standard » fait référence à la taille en octets de la valeur agrégée avec l'utilisation de la taille standard (c'est-à-dire lorsque la chaîne de format commence par l'un des caractères suivants : @code{'<'}, @code{'>'}, @code{'!'} ou @code{'='}). Si vous utilisez la taille native, la taille de la valeur agrégée dépend de la plateforme.


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Format

@tab

Type C

@tab

Type Python

@tab

Taille standard

@tab

Notes

@item

@code{x}

@tab

octet de bourrage

@tab

pas de valeur

@tab

@tab

(7)

@item

@code{c}

@tab

char

@tab

`bytes' (suite d'octets) de taille 1

@tab

1

@tab

@item

@code{b}

@tab

signed char

@tab

`int' (entier)

@tab

1

@tab

(1), (2)

@item

@code{B}

@tab

unsigned char

@tab

`int' (entier)

@tab

1

@tab

(2)

@item

@code{?}

@tab

_Bool

@tab

`bool' (booléen)

@tab

1

@tab

(1)

@item

@code{h}

@tab

short

@tab

`int' (entier)

@tab

2

@tab

(2)

@item

@code{H}

@tab

unsigned short

@tab

`int' (entier)

@tab

2

@tab

(2)

@item

@code{i}

@tab

int

@tab

`int' (entier)

@tab

4

@tab

(2)

@item

@code{I}

@tab

unsigned int

@tab

`int' (entier)

@tab

4

@tab

(2)

@item

@code{l}

@tab

long

@tab

`int' (entier)

@tab

4

@tab

(2)

@item

@code{L}

@tab

unsigned long

@tab

`int' (entier)

@tab

4

@tab

(2)

@item

@code{q}

@tab

long long

@tab

`int' (entier)

@tab

8

@tab

(2)

@item

@code{Q}

@tab

unsigned long long

@tab

`int' (entier)

@tab

8

@tab

(2)

@item

@code{n}

@tab

@code{ssize_t}

@tab

`int' (entier)

@tab

@tab

(3)

@item

@code{N}

@tab

@code{size_t}

@tab

`int' (entier)

@tab

@tab

(3)

@item

@code{e}

@tab

(6)

@tab

`float' (nombre à virgule flottante)

@tab

2

@tab

(4)

@item

@code{f}

@tab

float

@tab

`float' (nombre à virgule flottante)

@tab

4

@tab

(4)

@item

@code{d}

@tab

double

@tab

`float' (nombre à virgule flottante)

@tab

8

@tab

(4)

@item

@code{s}

@tab

char[]

@tab

`bytes' (séquence d'octets)

@tab

@tab

(9)

@item

@code{p}

@tab

char[]

@tab

`bytes' (séquence d'octets)

@tab

@tab

(8)

@item

@code{P}

@tab

void*

@tab

`int' (entier)

@tab

@tab

(5)

@end multitable



Modifié dans la version 3.3: ajouté la gestion des formats @code{'n'} et @code{'N'}.



Modifié dans la version 3.6: ajouté la gestion du format @code{'e'}.


Notes :


@enumerate 

@item 
@geindex ? (question mark);in struct format strings

The @code{'?'} conversion code corresponds to the _Bool type
defined by C standards since C99.  In standard mode, it is
represented by one byte.

@item 
When attempting to pack a non-integer using any of the integer conversion
codes, if the non-integer has a @ref{707,,__index__()} method then that method is
called to convert the argument to an integer before packing.


Modifié dans la version 3.2: Added use of the @ref{707,,__index__()} method for non-integers.


@item 
Les codes de conversion @code{'n'} et @code{'N'} ne sont disponibles que pour la taille native (choisie par défaut ou à l'aide du caractère de boutisme @code{'@@'}). Pour la taille standard, vous pouvez utiliser n'importe quel format d'entier qui convient à votre application.

@item 
Pour les codes de conversion @code{'f'}, @code{'d'} et @code{'e'}, la représentation agrégée utilise respectivement le format IEEE 754 `binaire32', `binaire64' ou `binaire16' (pour @code{'f'}, @code{'d'} ou @code{'e'} respectivement), quel que soit le format des nombres à virgule flottante de la plateforme.

@item 
Le caractère de format @code{'P'} n'est disponible que pour le boutisme natif (choisi par défaut ou à l'aide du caractère @code{'@@'} de boutisme). Le caractère de boutisme @code{'='} choisit d'utiliser un petit ou un gros en fonction du système hôte. Le module `struct' ne l'interprète pas comme un boutisme natif, donc le format @code{'P'} n'est pas disponible.

@item 
Le type IEEE 754 `binaire16' « demie-précision » a été introduit en 2008 par la révision du standard IEEE 754@footnote{https://en.wikipedia.org/wiki/IEEE_754-2008_revision}. Il comprend un bit de signe, un exposant sur 5 bits et une précision de 11 bits (dont 10 bits sont explicitement stockés) ; il peut représenter les nombres entre environ @code{6.1e-05} et @code{6.5e+04} avec une précision maximale. Ce type est rarement pris en charge par les compilateurs C : sur une machine courante, un `unsigned short' (entier court non signé) peut être utilisé pour le stockage mais pas pour les opérations mathématiques. Lisez la page Wikipédia (NdT : non traduite en français) half-precision floating-point format@footnote{https://en.wikipedia.org/wiki/Half-precision_floating-point_format} pour davantage d'informations.

@item 
When packing, @code{'x'} inserts one NUL byte.

@item 
Le caractère de format @code{'p'} sert à encoder une « chaîne Pascal », c'est-à-dire une courte chaîne de longueur variable, stockée dans un `nombre défini d'octets' dont la valeur est définie par la répétition. Le premier octet stocké est la longueur de la chaîne (dans la limite maximum de 255). Les octets composant la chaîne suivent. Si la chaîne passée à @ref{1255,,pack()} est trop longue (supérieure à la valeur de la répétition moins 1), seuls les @code{count-1} premiers octets de la chaîne sont stockés. Si la chaîne est plus courte que @code{count-1}, des octets de bourrage nuls sont insérés de manière à avoir exactement `count' octets au final. Notez que pour @ref{1754,,unpack()}, le caractère de format @code{'p'} consomme @code{count} octets mais que la chaîne renvoyée ne peut pas excéder 255 octets.

@item 
For the @code{'s'} format character, the count is interpreted as the length of the
bytes, not a repeat count like for the other format characters; for example,
@code{'10s'} means a single 10-byte string mapping to or from a single
Python byte string, while @code{'10c'} means 10
separate one byte character elements (e.g., @code{cccccccccc}) mapping
to or from ten different Python byte objects. (See @ref{2334,,Exemples}
for a concrete demonstration of the difference.)
If a count is not given, it defaults to 1.  For packing, the string is
truncated or padded with null bytes as appropriate to make it fit. For
unpacking, the resulting bytes object always has exactly the specified number
of bytes.  As a special case, @code{'0s'} means a single, empty string (while
@code{'0c'} means 0 characters).
@end enumerate

Un caractère de format peut être précédé par un entier indiquant le nombre de répétitions. Par exemple, la chaîne de format @code{'4h'} a exactement la même signification que @code{'hhhh'}.

Les caractères d'espacement entre les indications de format sont ignorés ; cependant, le nombre de répétitions et le format associé ne doivent pas être séparés par des caractères d'espacement.

Lors de l'agrégation d'une valeur @code{x} en utilisant l'un des formats pour les entiers (@code{'b'}, @code{'B'}, @code{'h'}, @code{'H'}, @code{'i'}, @code{'I'}, @code{'l'}, @code{'L'}, @code{'q'}, @code{'Q'}), si @code{x} est en dehors de l'intervalle du format spécifié, une @ref{1301,,struct.error} est levée.


Modifié dans la version 3.1: Previously, some of the integer formats wrapped out-of-range values and
raised @ref{1a3,,DeprecationWarning} instead of @ref{1301,,struct.error}.


@geindex ? (question mark);in struct format strings

Pour le caractère de format @code{'?'}, la valeur renvoyée est @ref{bfb,,True} ou @ref{b25,,False}. Lors de l'agrégation, la valeur de vérité de l'objet argument est utilisée. La valeur agrégée est 0 ou 1 dans la représentation native ou standard et, lors de la dissociation, n'importe quelle valeur différente de zéro est renvoyée @code{True}.

@node Exemples<2>,,Caractères de format,Chaînes de spécification du format
@anchor{library/struct examples}@anchor{2336}@anchor{library/struct struct-examples}@anchor{2334}
@subsubsection Exemples


@cartouche
@quotation Note 
Native byte order examples (designated by the @code{'@@'} format prefix or
lack of any prefix character) may not match what the reader's
machine produces as
that depends on the platform and compiler.
@end quotation
@end cartouche

Pack and unpack integers of three different sizes, using big endian
ordering:

@example
>>> from struct import *
>>> pack(">bhl", 1, 2, 3)
b'\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('>bhl', b'\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('>bhl')
7
@end example

Attempt to pack an integer which is too large for the defined field:

@example
>>> pack(">h", 99999)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
struct.error: 'h' format requires -32768 <= number <= 32767
@end example

Demonstrate the difference between @code{'s'} and @code{'c'} format
characters:

@example
>>> pack("@@ccc", b'1', b'2', b'3')
b'123'
>>> pack("@@3s", b'123')
b'123'
@end example

Les champs dissociés peuvent être nommés en leur assignant des variables ou en encapsulant le résultat dans un `n'-uplet nommé :

@example
>>> record = b'raymond   \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)
@end example

The ordering of format characters may have an impact on size in native
mode since padding is implicit. In standard mode, the user is
responsible for inserting any desired padding.
Note in
the first @code{pack} call below that three NUL bytes were added after the
packed @code{'#'} to align the following integer on a four-byte boundary.
In this example, the output was produced on a little endian machine:

@example
>>> pack('@@ci', b'#', 0x12131415)
b'#\x00\x00\x00\x15\x14\x13\x12'
>>> pack('@@ic', 0x12131415, b'#')
b'\x15\x14\x13\x12#'
>>> calcsize('@@ci')
8
>>> calcsize('@@ic')
5
@end example

The following format @code{'llh0l'} results in two pad bytes being added
at the end, assuming the platform's longs are aligned on 4-byte boundaries:

@example
>>> pack('@@llh0l', 1, 2, 3)
b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'
@end example


@subsubheading Voir aussi



@table @asis

@item Module @ref{7,,array}

Stockage agrégé binaire de données homogènes.

@item Module @ref{81,,json}

JSON encoder and decoder.

@item Module @ref{a5,,pickle}

Python object serialization.
@end table


@node Applications,Classes<3>,Chaînes de spécification du format,struct --- Interpret bytes as packed binary data
@anchor{library/struct applications}@anchor{2337}@anchor{library/struct id2}@anchor{2338}
@subsubsection Applications


Two main applications for the @ref{d4,,struct} module exist, data
interchange between Python and C code within an application or another
application compiled using the same compiler (@ref{2339,,native formats}), and
data interchange between applications using agreed upon data layout
(@ref{233a,,standard formats}).  Generally speaking, the format strings
constructed for these two domains are distinct.

@menu
* Native Formats:: 
* Standard Formats:: 

@end menu

@node Native Formats,Standard Formats,,Applications
@anchor{library/struct native-formats}@anchor{233b}@anchor{library/struct struct-native-formats}@anchor{2339}
@subsubsection Native Formats


When constructing format strings which mimic native layouts, the
compiler and machine architecture determine byte ordering and padding.
In such cases, the @code{@@} format character should be used to specify
native byte ordering and data sizes.  Internal pad bytes are normally inserted
automatically.  It is possible that a zero-repeat format code will be
needed at the end of a format string to round up to the correct
byte boundary for proper alignment of consecutive chunks of data.

Consider these two simple examples (on a 64-bit, little-endian
machine):

@example
>>> calcsize('@@lhl')
24
>>> calcsize('@@llh')
18
@end example

Data is not padded to an 8-byte boundary at the end of the second
format string without the use of extra padding.  A zero-repeat format
code solves that problem:

@example
>>> calcsize('@@llh0l')
24
@end example

The @code{'x'} format code can be used to specify the repeat, but for
native formats it is better to use a zero-repeat format like @code{'0l'}.

By default, native byte ordering and alignment is used, but it is
better to be explicit and use the @code{'@@'} prefix character.

@node Standard Formats,,Native Formats,Applications
@anchor{library/struct standard-formats}@anchor{233c}@anchor{library/struct struct-standard-formats}@anchor{233a}
@subsubsection Standard Formats


When exchanging data beyond your process such as networking or storage,
be precise.  Specify the exact byte order, size, and alignment.  Do
not assume they match the native order of a particular machine.
For example, network byte order is big-endian, while many popular CPUs
are little-endian.  By defining this explicitly, the user need not
care about the specifics of the platform their code is running on.
The first character should typically be @code{<} or @code{>}
(or @code{!}).  Padding is the responsibility of the programmer.  The
zero-repeat format character won't work.  Instead, the user must
explicitly add @code{'x'} pad bytes where needed.  Revisiting the
examples from the previous section, we have:

@example
>>> calcsize('<qh6xq')
24
>>> pack('<qh6xq', 1, 2, 3) == pack('@@lhl', 1, 2, 3)
True
>>> calcsize('@@llh')
18
>>> pack('@@llh', 1, 2, 3) == pack('<qqh', 1, 2, 3)
True
>>> calcsize('<qqh6x')
24
>>> calcsize('@@llh0l')
24
>>> pack('@@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
True
@end example

The above results (executed on a 64-bit machine) aren't guaranteed to
match when executed on different machines.  For example, the examples
below were executed on a 32-bit machine:

@example
>>> calcsize('<qqh6x')
24
>>> calcsize('@@llh0l')
12
>>> pack('@@llh0l', 1, 2, 3) == pack('<qqh6x', 1, 2, 3)
False
@end example

@node Classes<3>,,Applications,struct --- Interpret bytes as packed binary data
@anchor{library/struct classes}@anchor{233d}@anchor{library/struct struct-objects}@anchor{233e}
@subsubsection Classes


Le module @ref{d4,,struct} définit aussi le type suivant :

@geindex Struct (classe dans struct)
@anchor{library/struct struct Struct}@anchor{163a}
@deffn {Classe} struct.Struct (format)

Return a new Struct object which writes and reads binary data according to
the format string `format'.  Creating a @code{Struct} object once and calling its
methods is more efficient than calling module-level functions with the
same format since the format string is only compiled once.

@cartouche
@quotation Note 
The compiled versions of the most recent format strings passed to
the module-level functions are cached, so programs that use only a few
format strings needn't worry about reusing a single @ref{163a,,Struct}
instance.
@end quotation
@end cartouche

Les objets @code{Struct} compilés gèrent les méthodes et attributs suivants :

@geindex pack() (méthode struct.Struct)
@anchor{library/struct struct Struct pack}@anchor{233f}
@deffn {Méthode} pack (v1, v2, ...)

Identique à la fonction @ref{1255,,pack()}, en utilisant le format compilé (@code{len(result)} vaut @ref{2340,,size}).
@end deffn

@geindex pack_into() (méthode struct.Struct)
@anchor{library/struct struct Struct pack_into}@anchor{2341}
@deffn {Méthode} pack_into (buffer, offset, v1, v2, ...)

Identique à la fonction @ref{232f,,pack_into()}, en utilisant le format compilé.
@end deffn

@geindex unpack() (méthode struct.Struct)
@anchor{library/struct struct Struct unpack}@anchor{2342}
@deffn {Méthode} unpack (buffer)

Identique à la fonction @ref{1754,,unpack()}, en utilisant le format compilé. La taille du tampon `buffer' en octets doit valoir @ref{2340,,size}.
@end deffn

@geindex unpack_from() (méthode struct.Struct)
@anchor{library/struct struct Struct unpack_from}@anchor{2343}
@deffn {Méthode} unpack_from (buffer, offset=0)

Identique à la fonction @ref{2330,,unpack_from()}, en utilisant le format compilé. La taille du tampon `buffer' en octets, en commençant à la position `offset', doit valoir au moins @ref{2340,,size}.
@end deffn

@geindex iter_unpack() (méthode struct.Struct)
@anchor{library/struct struct Struct iter_unpack}@anchor{faa}
@deffn {Méthode} iter_unpack (buffer)

Identique à la fonction @ref{fa9,,iter_unpack()}, en utilisant le format compilé. La taille du tampon `buffer' en octets doit être un multiple de @ref{2340,,size}.


Ajouté dans la version 3.4.

@end deffn

@geindex format (attribut struct.Struct)
@anchor{library/struct struct Struct format}@anchor{bf4}
@deffn {Attribut} format

La chaîne de format utilisée pour construire l'objet @code{Struct}.


Modifié dans la version 3.7: la chaîne de format est maintenant de type @ref{435,,str} au lieu de @ref{1bd,,bytes}.

@end deffn

@geindex size (attribut struct.Struct)
@anchor{library/struct struct Struct size}@anchor{2340}
@deffn {Attribut} size

La taille calculée de la structure agrégée (et donc de l'objet @code{bytes} produit par la méthode @ref{1255,,pack()}) correspondante à @ref{60a,,format}.
@end deffn


Modifié dans la version 3.13: The `repr()' of structs has changed.  It
is now:

@example
>>> Struct('i')
Struct('i')
@end example

@end deffn

@node codecs --- Codec registry and base classes,,struct --- Interpret bytes as packed binary data,Services autour des Données Binaires
@anchor{library/codecs doc}@anchor{2344}@anchor{library/codecs codecs-codec-registry-and-base-classes}@anchor{2345}@anchor{library/codecs module-codecs}@anchor{1b}
@subsection @code{codecs} --- Codec registry and base classes


@geindex module; codecs

`Code source :' Lib/codecs.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/codecs.py}

@geindex Unicode
@geindex Codecs
@geindex Codecs;encode
@geindex Codecs;decode
@geindex streams
@geindex stackable;streams


__________________________________________________________________


This module defines base classes for standard Python codecs (encoders and
decoders) and provides access to the internal Python codec registry, which
manages the codec and error handling lookup process. Most standard codecs
are @ref{2101,,text encodings}, which encode text to bytes (and
decode bytes to text), but there are also codecs provided that encode text to
text, and bytes to bytes. Custom codecs may encode and decode between arbitrary
types, but some module features are restricted to be used specifically with
@ref{2101,,text encodings} or with codecs that encode to
@ref{1bd,,bytes}.

Le module définit les fonctions suivantes pour encoder et décoder à l'aide de n'importe quel codec :

@geindex encode() (dans le module codecs)
@anchor{library/codecs codecs encode}@anchor{eec}
@deffn {Fonction} codecs.encode (obj, encoding='utf-8', errors='strict')

Encode `obj' en utilisant le codec enregistré pour `encoding'.

Vous pouvez spécifier `errors' pour définir la façon de gérer les erreurs. Le gestionnaire d'erreurs par défaut est @code{'strict'}, ce qui veut dire qu'une erreur lors de l'encodage lève @ref{1ff,,ValueError} (ou une sous-classe spécifique du codec, telle que @ref{662,,UnicodeEncodeError}). Référez-vous aux @ref{2346,,classes de base des codecs} pour plus d'informations sur la gestion des erreurs par les codecs.
@end deffn

@geindex decode() (dans le module codecs)
@anchor{library/codecs codecs decode}@anchor{eed}
@deffn {Fonction} codecs.decode (obj, encoding='utf-8', errors='strict')

Décode `obj' en utilisant le codec enregistré pour `encoding'.

Vous pouvez spécifier `errors' pour définir la façon de gérer les erreurs. Le gestionnaire d'erreurs par défaut est @code{'strict'}, ce qui veut dire qu'une erreur lors du décodage lève @ref{1ff,,ValueError} (ou une sous-classe spécifique du codec, telle que @ref{a01,,UnicodeDecodeError}). Référez-vous aux @ref{2346,,classes de base des codecs} pour plus d'informations sur la gestion des erreurs par les codecs.
@end deffn

Les détails complets de chaque codec peuvent être examinés directement :

@geindex lookup() (dans le module codecs)
@anchor{library/codecs codecs lookup}@anchor{950}
@deffn {Fonction} codecs.lookup (encoding)

Recherche les informations relatives au codec dans le registre des codecs de Python et renvoie l'objet @ref{1684,,CodecInfo} tel que défini ci-dessous.

Les encodeurs sont recherchés en priorité dans le cache du registre. S'ils n'y sont pas, la liste des fonctions de recherche enregistrées est passée en revue. Si aucun objet @ref{1684,,CodecInfo} n'est trouvé, une @ref{2155,,LookupError} est levée. Sinon, l'objet @ref{1684,,CodecInfo} est mis en cache et renvoyé vers l'appelant.
@end deffn

@geindex CodecInfo (classe dans codecs)
@anchor{library/codecs codecs CodecInfo}@anchor{1684}
@deffn {Classe} codecs.CodecInfo (encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Les détails d'un codec trouvé dans le registre des codecs. Les arguments du constructeur sont stockés dans les attributs éponymes :

@geindex name (attribut codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo name}@anchor{2347}
@deffn {Attribut} name

Le nom de l'encodeur.
@end deffn

@geindex encode (attribut codecs.CodecInfo)
@geindex decode (attribut codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo encode}@anchor{2348}
@deffn {Attribut} encode
@anchor{library/codecs codecs CodecInfo decode}@anchor{2349}
@deffnx {Attribut} decode

Les fonctions d'encodage et de décodage. Ces fonctions ou méthodes doivent avoir la même interface que les méthodes @ref{234a,,encode()} et @ref{234b,,decode()} des instances de Codec (voir @ref{234c,,Interface des codecs}). Les fonctions et méthodes sont censées fonctionner sans état interne.
@end deffn

@geindex incrementalencoder (attribut codecs.CodecInfo)
@geindex incrementaldecoder (attribut codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo incrementalencoder}@anchor{234d}
@deffn {Attribut} incrementalencoder
@anchor{library/codecs codecs CodecInfo incrementaldecoder}@anchor{234e}
@deffnx {Attribut} incrementaldecoder

Classes d'encodeurs et de décodeurs incrémentaux ou fonctions usines. Elles doivent avoir respectivement les mêmes interfaces que celles définies par les classes de base @ref{234f,,IncrementalEncoder} et @ref{2350,,IncrementalDecoder}. Les codecs incrémentaux peuvent conserver des états internes.
@end deffn

@geindex streamwriter (attribut codecs.CodecInfo)
@geindex streamreader (attribut codecs.CodecInfo)
@anchor{library/codecs codecs CodecInfo streamwriter}@anchor{2351}
@deffn {Attribut} streamwriter
@anchor{library/codecs codecs CodecInfo streamreader}@anchor{2352}
@deffnx {Attribut} streamreader

Classes d'écriture et de lecture de flux ou fonctions usines. Elles doivent avoir les mêmes interfaces que celles définies par les classes de base @ref{2353,,StreamWriter} et @ref{2354,,StreamReader}, respectivement. Les codecs de flux peuvent conserver un état interne.
@end deffn
@end deffn

Pour simplifier l'accès aux différents composants du codec, le module fournit les fonctions supplémentaires suivantes qui utilisent @ref{950,,lookup()} pour la recherche du codec :

@geindex getencoder() (dans le module codecs)
@anchor{library/codecs codecs getencoder}@anchor{2355}
@deffn {Fonction} codecs.getencoder (encoding)

Recherche le codec pour l'encodage `encoding' et renvoie sa fonction d'encodage.

Lève une @ref{2155,,LookupError} si l'encodage `encoding' n'est pas trouvé.
@end deffn

@geindex getdecoder() (dans le module codecs)
@anchor{library/codecs codecs getdecoder}@anchor{2356}
@deffn {Fonction} codecs.getdecoder (encoding)

Recherche le codec pour l'encodage `encoding' et renvoie sa fonction de décodage.

Lève une @ref{2155,,LookupError} si l'encodage `encoding' n'est pas trouvé.
@end deffn

@geindex getincrementalencoder() (dans le module codecs)
@anchor{library/codecs codecs getincrementalencoder}@anchor{2357}
@deffn {Fonction} codecs.getincrementalencoder (encoding)

Recherche le codec pour l'encodage `encoding' et renvoie sa classe d'encodage incrémental ou la fonction usine.

Lève une @ref{2155,,LookupError} si l'encodage `encoding' n'est pas trouvé ou si le codec ne gère pas l'encodage incrémental.
@end deffn

@geindex getincrementaldecoder() (dans le module codecs)
@anchor{library/codecs codecs getincrementaldecoder}@anchor{2358}
@deffn {Fonction} codecs.getincrementaldecoder (encoding)

Recherche le codec pour l'encodage `encoding' et renvoie sa classe de décodage incrémental ou la fonction usine.

Lève une @ref{2155,,LookupError} si l'encodage `encoding' n'est pas trouvé ou si le codec ne gère pas le décodage incrémental.
@end deffn

@geindex getreader() (dans le module codecs)
@anchor{library/codecs codecs getreader}@anchor{2359}
@deffn {Fonction} codecs.getreader (encoding)

Recherche le codec pour l'encodage `encoding' et renvoie sa classe @ref{2354,,StreamReader} ou la fonction usine.

Lève une @ref{2155,,LookupError} si l'encodage `encoding' n'est pas trouvé.
@end deffn

@geindex getwriter() (dans le module codecs)
@anchor{library/codecs codecs getwriter}@anchor{235a}
@deffn {Fonction} codecs.getwriter (encoding)

Recherche le codec pour l'encodage `encoding' et renvoie sa classe @ref{2353,,StreamWriter} ou la fonction usine.

Lève une @ref{2155,,LookupError} si l'encodage `encoding' n'est pas trouvé.
@end deffn

Les codecs personnalisés sont mis à disposition en enregistrant une fonction de recherche de codecs adaptée :

@geindex register() (dans le module codecs)
@anchor{library/codecs codecs register}@anchor{235b}
@deffn {Fonction} codecs.register (search_function)

Register a codec search function. Search functions are expected to take one
argument, being the encoding name in all lower case letters with hyphens
and spaces converted to underscores, and return a @ref{1684,,CodecInfo} object.
In case a search function cannot find a given encoding, it should return
@code{None}.


Modifié dans la version 3.9: Hyphens and spaces are converted to underscore.

@end deffn

@geindex unregister() (dans le module codecs)
@anchor{library/codecs codecs unregister}@anchor{7d2}
@deffn {Fonction} codecs.unregister (search_function)

Unregister a codec search function and clear the registry's cache.
If the search function is not registered, do nothing.


Ajouté dans la version 3.10.

@end deffn

Alors qu'il est recommandé d'utiliser la fonction native @ref{505,,open()} et le module associé @ref{7e,,io} pour travailler avec des fichiers texte encodés, le présent module fournit des fonctions et classes utilitaires supplémentaires qui permettent l'utilisation d'une plus large gamme de codecs si vous travaillez avec des fichiers binaires :

@geindex open() (dans le module codecs)
@anchor{library/codecs codecs open}@anchor{72a}
@deffn {Fonction} codecs.open (filename, mode='r', encoding=None, errors='strict', buffering=-1)

Ouvre un fichier encodé en utilisant le `mode' donné et renvoie une instance de @ref{235c,,StreamReaderWriter}, permettant un encodage-décodage transparent. Le mode de fichier par défaut est @code{'r'}, ce qui signifie que le fichier est ouvert en lecture.

@cartouche
@quotation Note 
If `encoding' is not @code{None}, then the
underlying encoded files are always opened in binary mode.
No automatic conversion of @code{'\n'} is done on reading and writing.
The `mode' argument may be any binary mode acceptable to the built-in
@ref{505,,open()} function; the @code{'b'} is automatically added.
@end quotation
@end cartouche

`encoding' spécifie l'encodage à utiliser pour le fichier. Tout encodage qui encode et décode des octets (type `bytes') est autorisé et les types de données pris en charge par les méthodes relatives aux fichiers dépendent du codec utilisé.

`errors' peut être spécifié pour définir la gestion des erreurs. La valeur par défaut est @code{'strict'}, ce qui lève une @ref{1ff,,ValueError} en cas d'erreur lors du codage.

`buffering' a la même signification que pour la fonction native @ref{505,,open()}. Il vaut @code{-1} par défaut, ce qui signifie que la taille par défaut du tampon est utilisée.


Modifié dans la version 3.11: le mode @code{'U`} a été enlevé.

@end deffn

@geindex EncodedFile() (dans le module codecs)
@anchor{library/codecs codecs EncodedFile}@anchor{235d}
@deffn {Fonction} codecs.EncodedFile (file, data_encoding, file_encoding=None, errors='strict')

Renvoie une instance de @ref{197f,,StreamRecoder}, version encapsulée de `file' qui fournit un transcodage transparent. Le fichier original est fermé quand la version encapsulée est fermée.

Les données écrites dans un fichier encapsulant sont décodées en fonction du `data_encoding' spécifié puis écrites vers le fichier original en tant que `bytes' en utilisant `file_encoding'. Les octets lus dans le fichier original sont décodés conformément à `file_encoding' et le résultat est encodé en utilisant `data_encoding'.

Si `file_encoding' n'est pas spécifié, la valeur par défaut est `data_encoding'.

`errors' peut être spécifié pour définir la gestion des erreurs. La valeur par défaut est @code{'strict'}, ce qui lève une @ref{1ff,,ValueError} en cas d'erreur lors du codage.
@end deffn

@geindex iterencode() (dans le module codecs)
@anchor{library/codecs codecs iterencode}@anchor{235e}
@deffn {Fonction} codecs.iterencode (iterator, encoding, errors='strict', **kwargs)

Utilise un encodeur incrémental pour encoder de manière itérative l'entrée fournie par `iterator'. Cette fonction est un @ref{104a,,générateur}. L'argument `errors' (ainsi que tout autre argument passé par son nom) est transmis à l'encodeur incrémental.

Cette fonction nécessite que le codec accepte les objets texte (classe @ref{435,,str}) en entrée. Par conséquent, il ne prend pas en charge les encodeurs `bytes' vers `bytes' tels que @code{base64_codec}.
@end deffn

@geindex iterdecode() (dans le module codecs)
@anchor{library/codecs codecs iterdecode}@anchor{235f}
@deffn {Fonction} codecs.iterdecode (iterator, encoding, errors='strict', **kwargs)

Utilise un décodeur incrémental pour décoder de manière itérative l'entrée fournie par `iterator'. Cette fonction est un @ref{104a,,générateur}. L'argument `errors' (ainsi que tout autre argument passé par son nom) est transmis au décodeur incrémental.

Cette fonction requiert que le codec accepte les objets @ref{1bd,,bytes} en entrée. Par conséquent, elle ne prend pas en charge les encodeurs de texte vers texte tels que @code{rot_13}, bien que @code{rot_13} puisse être utilisé de manière équivalente avec @ref{235e,,iterencode()}.
@end deffn

Le module fournit également les constantes suivantes qui sont utiles pour lire et écrire les fichiers dépendants de la plateforme :

@geindex BOM (dans le module codecs)
@geindex BOM_BE (dans le module codecs)
@geindex BOM_LE (dans le module codecs)
@geindex BOM_UTF8 (dans le module codecs)
@geindex BOM_UTF16 (dans le module codecs)
@geindex BOM_UTF16_BE (dans le module codecs)
@geindex BOM_UTF16_LE (dans le module codecs)
@geindex BOM_UTF32 (dans le module codecs)
@geindex BOM_UTF32_BE (dans le module codecs)
@geindex BOM_UTF32_LE (dans le module codecs)
@anchor{library/codecs codecs BOM}@anchor{2360}
@deffn {Données} codecs.BOM
@anchor{library/codecs codecs BOM_BE}@anchor{2361}
@deffnx {Données} codecs.BOM_BE
@anchor{library/codecs codecs BOM_LE}@anchor{2362}
@deffnx {Données} codecs.BOM_LE
@anchor{library/codecs codecs BOM_UTF8}@anchor{2363}
@deffnx {Données} codecs.BOM_UTF8
@anchor{library/codecs codecs BOM_UTF16}@anchor{2364}
@deffnx {Données} codecs.BOM_UTF16
@anchor{library/codecs codecs BOM_UTF16_BE}@anchor{2365}
@deffnx {Données} codecs.BOM_UTF16_BE
@anchor{library/codecs codecs BOM_UTF16_LE}@anchor{2366}
@deffnx {Données} codecs.BOM_UTF16_LE
@anchor{library/codecs codecs BOM_UTF32}@anchor{2367}
@deffnx {Données} codecs.BOM_UTF32
@anchor{library/codecs codecs BOM_UTF32_BE}@anchor{2368}
@deffnx {Données} codecs.BOM_UTF32_BE
@anchor{library/codecs codecs BOM_UTF32_LE}@anchor{2369}
@deffnx {Données} codecs.BOM_UTF32_LE

Ces constantes définissent diverses séquences d'octets, les marques d'ordre d'octets (BOM pour `byte order mark' en anglais) Unicode pour plusieurs encodages. Elles sont utilisées dans les flux de données UTF-16 et UTF-32 pour indiquer l'ordre des octets utilisé, et dans UTF-8 comme signature Unicode. @ref{2364,,BOM_UTF16} vaut soit @ref{2365,,BOM_UTF16_BE}, soit @ref{2366,,BOM_UTF16_LE} selon le boutisme natif de la plateforme, @ref{2360,,BOM} est un alias pour @ref{2364,,BOM_UTF16}, @ref{2362,,BOM_LE} pour @ref{2366,,BOM_UTF16_LE} et @ref{2361,,BOM_BE} pour @ref{2365,,BOM_UTF16_BE}. Les autres sont les marques BOM dans les encodages UTF-8 et UTF-32.
@end deffn

@menu
* Classes de base de codecs:: 
* Encodings and Unicode:: 
* Standard Encodings:: 
* Python Specific Encodings:: 
* encodings.idna: encodings idna --- Internationalized Domain Names in Applications. Internationalized Domain Names in Applications
* encodings.mbcs: encodings mbcs --- Windows ANSI codepage. Windows ANSI codepage
* encodings.utf_8_sig: encodings utf_8_sig --- UTF-8 codec with BOM signature. UTF-8 codec with BOM signature

@end menu

@node Classes de base de codecs,Encodings and Unicode,,codecs --- Codec registry and base classes
@anchor{library/codecs codec-base-classes}@anchor{2346}@anchor{library/codecs id1}@anchor{236a}
@subsubsection Classes de base de codecs


Le module @ref{1b,,codecs} définit un ensemble de classes de base qui spécifient les interfaces pour travailler avec des objets codecs et qui peuvent également être utilisées comme base pour des implémentations de codecs personnalisés.

Chaque codec doit définir quatre interfaces pour être utilisable comme codec en Python : codeur sans état, décodeur sans état, lecteur de flux et écrivain de flux. Le lecteur et l'écrivain de flux réutilisent généralement l'encodeur-décodeur sans état pour implémenter les protocoles de fichiers. Les auteurs de codecs doivent également définir comment le codec gère les erreurs d'encodage et de décodage.
@anchor{library/codecs surrogateescape}@anchor{236b}
@menu
* Gestionnaires d'erreurs:: 
* Stateless Encoding and Decoding:: 
* Incremental Encoding and Decoding:: 
* Stream Encoding and Decoding:: 

@end menu

@node Gestionnaires d'erreurs,Stateless Encoding and Decoding,,Classes de base de codecs
@anchor{library/codecs error-handlers}@anchor{1774}@anchor{library/codecs id2}@anchor{236c}
@subsubsection Gestionnaires d'erreurs


To simplify and standardize error handling, codecs may implement different
error handling schemes by accepting the `errors' string argument:

@example
>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German &#223;, &#9836;'
@end example

@geindex strict;error handler's name
@geindex ignore;error handler's name
@geindex replace;error handler's name
@geindex backslashreplace;error handler's name
@geindex surrogateescape;error handler's name
@geindex ? (question mark);replacement character
@geindex \ (backslash);escape sequence
@geindex \x;escape sequence
@geindex \u;escape sequence
@geindex \U;escape sequence

The following error handlers can be used with all Python
@ref{da6,,Standard Encodings} codecs:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Signification

@item

@code{'strict'}

@tab

Raise @ref{1281,,UnicodeError} (or a subclass),
this is the default. Implemented in
@ref{236d,,strict_errors()}.

@item

@code{'ignore'}

@tab

Ignore les données incorrectement formatées et continue sans rien signaler. Implémenté dans @ref{236e,,ignore_errors()}.

@item

@code{'replace'}

@tab

Replace with a replacement marker. On
encoding, use @code{?} (ASCII character). On
decoding, use @code{�} (U+FFFD, the official
REPLACEMENT CHARACTER). Implemented in
@ref{236f,,replace_errors()}.

@item

@code{'backslashreplace'}

@tab

Replace with backslashed escape sequences.
On encoding, use hexadecimal form of Unicode
code point with formats @code{\x@var{hh}}
@code{\u@var{xxxx}} @code{\U@var{xxxxxxxx}}.
On decoding, use hexadecimal form of byte
value with format @code{\x@var{hh}}.
Implemented in
@ref{2370,,backslashreplace_errors()}.

@item

@code{'surrogateescape'}

@tab

Lors du décodage, remplace un octet par un code de substitution individuel allant de @code{U+DC80} à @code{U+DCFF}. Ce code est reconverti vers l'octet de départ quand le gestionnaire d'erreurs @code{'surrogateescape'} est utilisé pour l'encodage des données (voir la 
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/} pour plus de détails).

@end multitable


@geindex xmlcharrefreplace;error handler's name
@geindex namereplace;error handler's name
@geindex \N;escape sequence

The following error handlers are only applicable to encoding (within
@ref{2101,,text encodings}):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Signification

@item

@code{'xmlcharrefreplace'}

@tab

Replace with XML/HTML numeric character
reference, which is a decimal form of Unicode
code point with format @code{&#@var{num};}.
Implemented in
@ref{2371,,xmlcharrefreplace_errors()}.

@item

@code{'namereplace'}

@tab

Replace with @code{\N@{...@}} escape sequences,
what appears in the braces is the Name
property from Unicode Character Database.
Implemented in @ref{2372,,namereplace_errors()}.

@end multitable


@geindex surrogatepass;error handler's name

En plus, le gestionnaire d'erreurs suivant est spécifique aux codecs suivants :


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Codecs

@tab

Signification

@item

@code{'surrogatepass'}

@tab

utf-8, utf-16, utf-32,
utf-16-be, utf-16-le,
utf-32-be, utf-32-le

@tab

Allow encoding and decoding surrogate code
point (@code{U+D800} - @code{U+DFFF}) as normal
code point. Otherwise these codecs treat
the presence of surrogate code point in
@ref{435,,str} as an error.

@end multitable



Ajouté dans la version 3.1: les gestionnaires d'erreurs @code{'surrogateescape'} et @code{'surrogatepass'}.



Modifié dans la version 3.4: The @code{'surrogatepass'} error handler now works with utf-16* and utf-32*
codecs.



Ajouté dans la version 3.5: le gestionnaire d'erreurs @code{'namereplace'}.



Modifié dans la version 3.5: The @code{'backslashreplace'} error handler now works with decoding and
translating.


L'ensemble des valeurs autorisées peut être étendu en enregistrant un nouveau gestionnaire d'erreurs nommé :

@geindex register_error() (dans le module codecs)
@anchor{library/codecs codecs register_error}@anchor{144d}
@deffn {Fonction} codecs.register_error (name, error_handler)

Register the error handling function `error_handler' under the name `name'.
The `error_handler' argument will be called during encoding and decoding
in case of an error, when `name' is specified as the errors parameter.

For encoding, `error_handler' will be called with a @ref{662,,UnicodeEncodeError}
instance, which contains information about the location of the error. The
error handler must either raise this or a different exception, or return a
tuple with a replacement for the unencodable part of the input and a position
where encoding should continue. The replacement may be either @ref{435,,str} or
@ref{1bd,,bytes}. If the replacement is bytes, the encoder will simply copy
them into the output buffer. If the replacement is a string, the encoder will
encode the replacement. Encoding continues on original input at the
specified position. Negative position values will be treated as being
relative to the end of the input string. If the resulting position is out of
bound an @ref{14eb,,IndexError} will be raised.

Decoding and translating works similarly, except @ref{a01,,UnicodeDecodeError} or
@ref{2224,,UnicodeTranslateError} will be passed to the handler and that the
replacement from the error handler will be put into the output directly.
@end deffn

Previously registered error handlers (including the standard error handlers)
can be looked up by name:

@geindex lookup_error() (dans le module codecs)
@anchor{library/codecs codecs lookup_error}@anchor{144e}
@deffn {Fonction} codecs.lookup_error (name)

Return the error handler previously registered under the name `name'.

Raises a @ref{2155,,LookupError} in case the handler cannot be found.
@end deffn

The following standard error handlers are also made available as module level
functions:

@geindex strict_errors() (dans le module codecs)
@anchor{library/codecs codecs strict_errors}@anchor{236d}
@deffn {Fonction} codecs.strict_errors (exception)

Implements the @code{'strict'} error handling.

Each encoding or decoding error raises a @ref{1281,,UnicodeError}.
@end deffn

@geindex ignore_errors() (dans le module codecs)
@anchor{library/codecs codecs ignore_errors}@anchor{236e}
@deffn {Fonction} codecs.ignore_errors (exception)

Implements the @code{'ignore'} error handling.

Malformed data is ignored; encoding or decoding is continued without
further notice.
@end deffn

@geindex replace_errors() (dans le module codecs)
@anchor{library/codecs codecs replace_errors}@anchor{236f}
@deffn {Fonction} codecs.replace_errors (exception)

Implements the @code{'replace'} error handling.

Substitutes @code{?} (ASCII character) for encoding errors or @code{�} (U+FFFD,
the official REPLACEMENT CHARACTER) for decoding errors.
@end deffn

@geindex backslashreplace_errors() (dans le module codecs)
@anchor{library/codecs codecs backslashreplace_errors}@anchor{2370}
@deffn {Fonction} codecs.backslashreplace_errors (exception)

Implements the @code{'backslashreplace'} error handling.

Malformed data is replaced by a backslashed escape sequence.
On encoding, use the hexadecimal form of Unicode code point with formats
@code{\x@var{hh}} @code{\u@var{xxxx}} @code{\U@var{xxxxxxxx}}.
On decoding, use the hexadecimal form of
byte value with format @code{\x@var{hh}}.


Modifié dans la version 3.5: Works with decoding and translating.

@end deffn

@geindex xmlcharrefreplace_errors() (dans le module codecs)
@anchor{library/codecs codecs xmlcharrefreplace_errors}@anchor{2371}
@deffn {Fonction} codecs.xmlcharrefreplace_errors (exception)

Implements the @code{'xmlcharrefreplace'} error handling (for encoding within
@ref{2101,,text encoding} only).

The unencodable character is replaced by an appropriate XML/HTML numeric
character reference, which is a decimal form of Unicode code point with
format @code{&#@var{num};} .
@end deffn

@geindex namereplace_errors() (dans le module codecs)
@anchor{library/codecs codecs namereplace_errors}@anchor{2372}
@deffn {Fonction} codecs.namereplace_errors (exception)

Implements the @code{'namereplace'} error handling (for encoding within
@ref{2101,,text encoding} only).

The unencodable character is replaced by a @code{\N@{...@}} escape sequence. The
set of characters that appear in the braces is the Name property from
Unicode Character Database. For example, the German lowercase letter @code{'ß'}
will be converted to byte sequence @code{\N@{LATIN SMALL LETTER SHARP S@}} .


Ajouté dans la version 3.5.

@end deffn

@node Stateless Encoding and Decoding,Incremental Encoding and Decoding,Gestionnaires d'erreurs,Classes de base de codecs
@anchor{library/codecs codec-objects}@anchor{234c}@anchor{library/codecs stateless-encoding-and-decoding}@anchor{2373}
@subsubsection Stateless Encoding and Decoding


The base @ref{2374,,Codec} class defines these methods which also define the
function interfaces of the stateless encoder and decoder:

@geindex Codec (classe dans codecs)
@anchor{library/codecs codecs Codec}@anchor{2374}
@deffn {Classe} codecs.Codec

@geindex encode() (méthode codecs.Codec)
@anchor{library/codecs codecs Codec encode}@anchor{234a}
@deffn {Méthode} encode (input, errors='strict')

Encodes the object `input' and returns a tuple (output object, length consumed).
For instance, @ref{2101,,text encoding} converts
a string object to a bytes object using a particular
character set encoding (e.g., @code{cp1252} or @code{iso-8859-1}).

The `errors' argument defines the error handling to apply.
It defaults to @code{'strict'} handling.

The method may not store state in the @ref{2374,,Codec} instance. Use
@ref{2353,,StreamWriter} for codecs which have to keep state in order to make
encoding efficient.

The encoder must be able to handle zero length input and return an empty object
of the output object type in this situation.
@end deffn

@geindex decode() (méthode codecs.Codec)
@anchor{library/codecs codecs Codec decode}@anchor{234b}
@deffn {Méthode} decode (input, errors='strict')

Decodes the object `input' and returns a tuple (output object, length
consumed). For instance, for a @ref{2101,,text encoding}, decoding converts
a bytes object encoded using a particular
character set encoding to a string object.

For text encodings and bytes-to-bytes codecs,
`input' must be a bytes object or one which provides the read-only
buffer interface -- for example, buffer objects and memory mapped files.

The `errors' argument defines the error handling to apply.
It defaults to @code{'strict'} handling.

The method may not store state in the @ref{2374,,Codec} instance. Use
@ref{2354,,StreamReader} for codecs which have to keep state in order to make
decoding efficient.

The decoder must be able to handle zero length input and return an empty object
of the output object type in this situation.
@end deffn
@end deffn

@node Incremental Encoding and Decoding,Stream Encoding and Decoding,Stateless Encoding and Decoding,Classes de base de codecs
@anchor{library/codecs incremental-encoding-and-decoding}@anchor{2375}
@subsubsection Incremental Encoding and Decoding


The @ref{234f,,IncrementalEncoder} and @ref{2350,,IncrementalDecoder} classes provide
the basic interface for incremental encoding and decoding. Encoding/decoding the
input isn't done with one call to the stateless encoder/decoder function, but
with multiple calls to the
@ref{2376,,encode()}/@ref{2377,,decode()} method of
the incremental encoder/decoder. The incremental encoder/decoder keeps track of
the encoding/decoding process during method calls.

The joined output of calls to the
@ref{2376,,encode()}/@ref{2377,,decode()} method is
the same as if all the single inputs were joined into one, and this input was
encoded/decoded with the stateless encoder/decoder.

@menu
* IncrementalEncoder Objects:: 
* IncrementalDecoder Objects:: 

@end menu

@node IncrementalEncoder Objects,IncrementalDecoder Objects,,Incremental Encoding and Decoding
@anchor{library/codecs incremental-encoder-objects}@anchor{2378}@anchor{library/codecs incrementalencoder-objects}@anchor{2379}
@subsubsection IncrementalEncoder Objects


The @ref{234f,,IncrementalEncoder} class is used for encoding an input in multiple
steps. It defines the following methods which every incremental encoder must
define in order to be compatible with the Python codec registry.

@geindex IncrementalEncoder (classe dans codecs)
@anchor{library/codecs codecs IncrementalEncoder}@anchor{234f}
@deffn {Classe} codecs.IncrementalEncoder (errors='strict')

Constructor for an @ref{234f,,IncrementalEncoder} instance.

All incremental encoders must provide this constructor interface. They are free
to add additional keyword arguments, but only the ones defined here are used by
the Python codec registry.

The @ref{234f,,IncrementalEncoder} may implement different error handling schemes
by providing the `errors' keyword argument. See @ref{1774,,Gestionnaires d'erreurs} for
possible values.

The `errors' argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the @ref{234f,,IncrementalEncoder}
object.

@geindex encode() (méthode codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder encode}@anchor{2376}
@deffn {Méthode} encode (object, final=False)

Encodes `object' (taking the current state of the encoder into account)
and returns the resulting encoded object. If this is the last call to
@ref{eec,,encode()} `final' must be true (the default is false).
@end deffn

@geindex reset() (méthode codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder reset}@anchor{237a}
@deffn {Méthode} reset ()

Reset the encoder to the initial state. The output is discarded: call
@code{.encode(object, final=True)}, passing an empty byte or text string
if necessary, to reset the encoder and to get the output.
@end deffn

@geindex getstate() (méthode codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder getstate}@anchor{237b}
@deffn {Méthode} getstate ()

Return the current state of the encoder which must be an integer. The
implementation should make sure that @code{0} is the most common
state. (States that are more complicated than integers can be converted
into an integer by marshaling/pickling the state and encoding the bytes
of the resulting string into an integer.)
@end deffn

@geindex setstate() (méthode codecs.IncrementalEncoder)
@anchor{library/codecs codecs IncrementalEncoder setstate}@anchor{237c}
@deffn {Méthode} setstate (state)

Set the state of the encoder to `state'. `state' must be an encoder state
returned by @ref{237b,,getstate()}.
@end deffn
@end deffn

@node IncrementalDecoder Objects,,IncrementalEncoder Objects,Incremental Encoding and Decoding
@anchor{library/codecs incremental-decoder-objects}@anchor{237d}@anchor{library/codecs incrementaldecoder-objects}@anchor{237e}
@subsubsection IncrementalDecoder Objects


The @ref{2350,,IncrementalDecoder} class is used for decoding an input in multiple
steps. It defines the following methods which every incremental decoder must
define in order to be compatible with the Python codec registry.

@geindex IncrementalDecoder (classe dans codecs)
@anchor{library/codecs codecs IncrementalDecoder}@anchor{2350}
@deffn {Classe} codecs.IncrementalDecoder (errors='strict')

Constructor for an @ref{2350,,IncrementalDecoder} instance.

All incremental decoders must provide this constructor interface. They are free
to add additional keyword arguments, but only the ones defined here are used by
the Python codec registry.

The @ref{2350,,IncrementalDecoder} may implement different error handling schemes
by providing the `errors' keyword argument. See @ref{1774,,Gestionnaires d'erreurs} for
possible values.

The `errors' argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the @ref{2350,,IncrementalDecoder}
object.

@geindex decode() (méthode codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder decode}@anchor{2377}
@deffn {Méthode} decode (object, final=False)

Decodes `object' (taking the current state of the decoder into account)
and returns the resulting decoded object. If this is the last call to
@ref{eed,,decode()} `final' must be true (the default is false). If `final' is
true the decoder must decode the input completely and must flush all
buffers. If this isn't possible (e.g. because of incomplete byte sequences
at the end of the input) it must initiate error handling just like in the
stateless case (which might raise an exception).
@end deffn

@geindex reset() (méthode codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder reset}@anchor{237f}
@deffn {Méthode} reset ()

Reset the decoder to the initial state.
@end deffn

@geindex getstate() (méthode codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder getstate}@anchor{2380}
@deffn {Méthode} getstate ()

Return the current state of the decoder. This must be a tuple with two
items, the first must be the buffer containing the still undecoded
input. The second must be an integer and can be additional state
info. (The implementation should make sure that @code{0} is the most common
additional state info.) If this additional state info is @code{0} it must be
possible to set the decoder to the state which has no input buffered and
@code{0} as the additional state info, so that feeding the previously
buffered input to the decoder returns it to the previous state without
producing any output. (Additional state info that is more complicated than
integers can be converted into an integer by marshaling/pickling the info
and encoding the bytes of the resulting string into an integer.)
@end deffn

@geindex setstate() (méthode codecs.IncrementalDecoder)
@anchor{library/codecs codecs IncrementalDecoder setstate}@anchor{2381}
@deffn {Méthode} setstate (state)

Set the state of the decoder to `state'. `state' must be a decoder state
returned by @ref{2380,,getstate()}.
@end deffn
@end deffn

@node Stream Encoding and Decoding,,Incremental Encoding and Decoding,Classes de base de codecs
@anchor{library/codecs stream-encoding-and-decoding}@anchor{2382}
@subsubsection Stream Encoding and Decoding


The @ref{2353,,StreamWriter} and @ref{2354,,StreamReader} classes provide generic
working interfaces which can be used to implement new encoding submodules very
easily. See @code{encodings.utf_8} for an example of how this is done.

@menu
* StreamWriter Objects:: 
* StreamReader Objects:: 
* StreamReaderWriter Objects:: 
* StreamRecoder Objects:: 

@end menu

@node StreamWriter Objects,StreamReader Objects,,Stream Encoding and Decoding
@anchor{library/codecs stream-writer-objects}@anchor{2383}@anchor{library/codecs streamwriter-objects}@anchor{2384}
@subsubsection StreamWriter Objects


The @ref{2353,,StreamWriter} class is a subclass of @ref{2374,,Codec} and defines the
following methods which every stream writer must define in order to be
compatible with the Python codec registry.

@geindex StreamWriter (classe dans codecs)
@anchor{library/codecs codecs StreamWriter}@anchor{2353}
@deffn {Classe} codecs.StreamWriter (stream, errors='strict')

Constructor for a @ref{2353,,StreamWriter} instance.

All stream writers must provide this constructor interface. They are free to add
additional keyword arguments, but only the ones defined here are used by the
Python codec registry.

The `stream' argument must be a file-like object open for writing
text or binary data, as appropriate for the specific codec.

The @ref{2353,,StreamWriter} may implement different error handling schemes by
providing the `errors' keyword argument. See @ref{1774,,Gestionnaires d'erreurs} for
the standard error handlers the underlying stream codec may support.

The `errors' argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the @ref{2353,,StreamWriter} object.

@geindex write() (méthode codecs.StreamWriter)
@anchor{library/codecs codecs StreamWriter write}@anchor{2385}
@deffn {Méthode} write (object)

Writes the object's contents encoded to the stream.
@end deffn

@geindex writelines() (méthode codecs.StreamWriter)
@anchor{library/codecs codecs StreamWriter writelines}@anchor{2386}
@deffn {Méthode} writelines (list)

Writes the concatenated iterable of strings to the stream (possibly by reusing
the @ref{2385,,write()} method). Infinite or
very large iterables are not supported. The standard bytes-to-bytes codecs
do not support this method.
@end deffn

@geindex reset() (méthode codecs.StreamWriter)
@anchor{library/codecs codecs StreamWriter reset}@anchor{2387}
@deffn {Méthode} reset ()

Resets the codec buffers used for keeping internal state.

Calling this method should ensure that the data on the output is put into
a clean state that allows appending of new fresh data without having to
rescan the whole stream to recover state.
@end deffn
@end deffn

In addition to the above methods, the @ref{2353,,StreamWriter} must also inherit
all other methods and attributes from the underlying stream.

@node StreamReader Objects,StreamReaderWriter Objects,StreamWriter Objects,Stream Encoding and Decoding
@anchor{library/codecs stream-reader-objects}@anchor{2388}@anchor{library/codecs streamreader-objects}@anchor{2389}
@subsubsection StreamReader Objects


The @ref{2354,,StreamReader} class is a subclass of @ref{2374,,Codec} and defines the
following methods which every stream reader must define in order to be
compatible with the Python codec registry.

@geindex StreamReader (classe dans codecs)
@anchor{library/codecs codecs StreamReader}@anchor{2354}
@deffn {Classe} codecs.StreamReader (stream, errors='strict')

Constructor for a @ref{2354,,StreamReader} instance.

All stream readers must provide this constructor interface. They are free to add
additional keyword arguments, but only the ones defined here are used by the
Python codec registry.

The `stream' argument must be a file-like object open for reading
text or binary data, as appropriate for the specific codec.

The @ref{2354,,StreamReader} may implement different error handling schemes by
providing the `errors' keyword argument. See @ref{1774,,Gestionnaires d'erreurs} for
the standard error handlers the underlying stream codec may support.

The `errors' argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the @ref{2354,,StreamReader} object.

The set of allowed values for the `errors' argument can be extended with
@ref{144d,,register_error()}.

@geindex read() (méthode codecs.StreamReader)
@anchor{library/codecs codecs StreamReader read}@anchor{238a}
@deffn {Méthode} read (size=-1, chars=-1, firstline=False)

Decodes data from the stream and returns the resulting object.

The `chars' argument indicates the number of decoded
code points or bytes to return. The @ref{238a,,read()} method will
never return more data than requested, but it might return less,
if there is not enough available.

The `size' argument indicates the approximate maximum
number of encoded bytes or code points to read
for decoding. The decoder can modify this setting as
appropriate. The default value -1 indicates to read and decode as much as
possible. This parameter is intended to
prevent having to decode huge files in one step.

The `firstline' flag indicates that
it would be sufficient to only return the first
line, if there are decoding errors on later lines.

The method should use a greedy read strategy meaning that it should read
as much data as is allowed within the definition of the encoding and the
given size, e.g.  if optional encoding endings or state markers are
available on the stream, these should be read too.
@end deffn

@geindex readline() (méthode codecs.StreamReader)
@anchor{library/codecs codecs StreamReader readline}@anchor{238b}
@deffn {Méthode} readline (size=None, keepends=True)

Read one line from the input stream and return the decoded data.

`size', if given, is passed as size argument to the stream's
@ref{238a,,read()} method.

If `keepends' is false line-endings will be stripped from the lines
returned.
@end deffn

@geindex readlines() (méthode codecs.StreamReader)
@anchor{library/codecs codecs StreamReader readlines}@anchor{238c}
@deffn {Méthode} readlines (sizehint=None, keepends=True)

Read all lines available on the input stream and return them as a list of
lines.

Line-endings are implemented using the codec's @ref{eed,,decode()} method and
are included in the list entries if `keepends' is true.

`sizehint', if given, is passed as the `size' argument to the stream's
@ref{238a,,read()} method.
@end deffn

@geindex reset() (méthode codecs.StreamReader)
@anchor{library/codecs codecs StreamReader reset}@anchor{238d}
@deffn {Méthode} reset ()

Resets the codec buffers used for keeping internal state.

Note that no stream repositioning should take place. This method is
primarily intended to be able to recover from decoding errors.
@end deffn
@end deffn

In addition to the above methods, the @ref{2354,,StreamReader} must also inherit
all other methods and attributes from the underlying stream.

@node StreamReaderWriter Objects,StreamRecoder Objects,StreamReader Objects,Stream Encoding and Decoding
@anchor{library/codecs stream-reader-writer}@anchor{238e}@anchor{library/codecs streamreaderwriter-objects}@anchor{238f}
@subsubsection StreamReaderWriter Objects


The @ref{235c,,StreamReaderWriter} is a convenience class that allows wrapping
streams which work in both read and write modes.

The design is such that one can use the factory functions returned by the
@ref{950,,lookup()} function to construct the instance.

@geindex StreamReaderWriter (classe dans codecs)
@anchor{library/codecs codecs StreamReaderWriter}@anchor{235c}
@deffn {Classe} codecs.StreamReaderWriter (stream, Reader, Writer, errors='strict')

Creates a @ref{235c,,StreamReaderWriter} instance. `stream' must be a file-like
object. `Reader' and `Writer' must be factory functions or classes providing the
@ref{2354,,StreamReader} and @ref{2353,,StreamWriter} interface resp. Error handling
is done in the same way as defined for the stream readers and writers.
@end deffn

@ref{235c,,StreamReaderWriter} instances define the combined interfaces of
@ref{2354,,StreamReader} and @ref{2353,,StreamWriter} classes. They inherit all other
methods and attributes from the underlying stream.

@node StreamRecoder Objects,,StreamReaderWriter Objects,Stream Encoding and Decoding
@anchor{library/codecs stream-recoder-objects}@anchor{2390}@anchor{library/codecs streamrecoder-objects}@anchor{2391}
@subsubsection StreamRecoder Objects


The @ref{197f,,StreamRecoder} translates data from one encoding to another,
which is sometimes useful when dealing with different encoding environments.

The design is such that one can use the factory functions returned by the
@ref{950,,lookup()} function to construct the instance.

@geindex StreamRecoder (classe dans codecs)
@anchor{library/codecs codecs StreamRecoder}@anchor{197f}
@deffn {Classe} codecs.StreamRecoder (stream, encode, decode, Reader, Writer, errors='strict')

Creates a @ref{197f,,StreamRecoder} instance which implements a two-way conversion:
`encode' and `decode' work on the frontend — the data visible to
code calling @ref{238a,,read()} and @ref{2385,,write()},
while `Reader' and `Writer'
work on the backend — the data in `stream'.

You can use these objects to do transparent transcodings, e.g., from Latin-1
to UTF-8 and back.

The `stream' argument must be a file-like object.

The `encode' and `decode' arguments must
adhere to the @ref{2374,,Codec} interface. `Reader' and
`Writer' must be factory functions or classes providing objects of the
@ref{2354,,StreamReader} and @ref{2353,,StreamWriter} interface respectively.

Error handling is done in the same way as defined for the stream readers and
writers.
@end deffn

@ref{197f,,StreamRecoder} instances define the combined interfaces of
@ref{2354,,StreamReader} and @ref{2353,,StreamWriter} classes. They inherit all other
methods and attributes from the underlying stream.

@node Encodings and Unicode,Standard Encodings,Classes de base de codecs,codecs --- Codec registry and base classes
@anchor{library/codecs encodings-and-unicode}@anchor{2392}@anchor{library/codecs encodings-overview}@anchor{2393}
@subsubsection Encodings and Unicode


Strings are stored internally as sequences of code points in
range @code{U+0000}--@code{U+10FFFF}. (See 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} for
more details about the implementation.)
Once a string object is used outside of CPU and memory, endianness
and how these arrays are stored as bytes become an issue. As with other
codecs, serialising a string into a sequence of bytes is known as `encoding',
and recreating the string from the sequence of bytes is known as `decoding'.
There are a variety of different text serialisation codecs, which are
collectivity referred to as @ref{2101,,text encodings}.

The simplest text encoding (called @code{'latin-1'} or @code{'iso-8859-1'}) maps
the code points 0--255 to the bytes @code{0x0}--@code{0xff}, which means that a string
object that contains code points above @code{U+00FF} can't be encoded with this
codec. Doing so will raise a @ref{662,,UnicodeEncodeError} that looks
like the following (although the details of the error message may differ):
@code{UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in
position 3: ordinal not in range(256)}.

There's another group of encodings (the so called charmap encodings) that choose
a different subset of all Unicode code points and how these code points are
mapped to the bytes @code{0x0}--@code{0xff}. To see how this is done simply open
e.g. @code{encodings/cp1252.py} (which is an encoding that is used primarily on
Windows). There's a string constant with 256 characters that shows you which
character is mapped to which byte value.

All of these encodings can only encode 256 of the 1114112 code points
defined in Unicode. A simple and straightforward way that can store each Unicode
code point, is to store each code point as four consecutive bytes. There are two
possibilities: store the bytes in big endian or in little endian order. These
two encodings are called @code{UTF-32-BE} and @code{UTF-32-LE} respectively. Their
disadvantage is that if e.g. you use @code{UTF-32-BE} on a little endian machine you
will always have to swap bytes on encoding and decoding. @code{UTF-32} avoids this
problem: bytes will always be in natural endianness. When these bytes are read
by a CPU with a different endianness, then bytes have to be swapped though. To
be able to detect the endianness of a @code{UTF-16} or @code{UTF-32} byte sequence,
there's the so called BOM ("Byte Order Mark"). This is the Unicode character
@code{U+FEFF}. This character can be prepended to every @code{UTF-16} or @code{UTF-32}
byte sequence. The byte swapped version of this character (@code{0xFFFE}) is an
illegal character that may not appear in a Unicode text. So when the
first character in a @code{UTF-16} or @code{UTF-32} byte sequence
appears to be a @code{U+FFFE} the bytes have to be swapped on decoding.
Unfortunately the character @code{U+FEFF} had a second purpose as
a @code{ZERO WIDTH NO-BREAK SPACE}: a character that has no width and doesn't allow
a word to be split. It can e.g. be used to give hints to a ligature algorithm.
With Unicode 4.0 using @code{U+FEFF} as a @code{ZERO WIDTH NO-BREAK SPACE} has been
deprecated (with @code{U+2060} (@code{WORD JOINER}) assuming this role). Nevertheless
Unicode software still must be able to handle @code{U+FEFF} in both roles: as a BOM
it's a device to determine the storage layout of the encoded bytes, and vanishes
once the byte sequence has been decoded into a string; as a @code{ZERO WIDTH
NO-BREAK SPACE} it's a normal character that will be decoded like any other.

There's another encoding that is able to encode the full range of Unicode
characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues
with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two
parts: marker bits (the most significant bits) and payload bits. The marker bits
are a sequence of zero to four @code{1} bits followed by a @code{0} bit. Unicode characters are
encoded like this (with x being payload bits, which when concatenated give the
Unicode character):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

`Range'

@tab

Encoding

@item

@code{U-00000000} ... @code{U-0000007F}

@tab

0xxxxxxx

@item

@code{U-00000080} ... @code{U-000007FF}

@tab

110xxxxx 10xxxxxx

@item

@code{U-00000800} ... @code{U-0000FFFF}

@tab

1110xxxx 10xxxxxx 10xxxxxx

@item

@code{U-00010000} ... @code{U-0010FFFF}

@tab

11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

@end multitable


The least significant bit of the Unicode character is the rightmost x bit.

As UTF-8 is an 8-bit encoding no BOM is required and any @code{U+FEFF} character in
the decoded string (even if it's the first character) is treated as a @code{ZERO
WIDTH NO-BREAK SPACE}.

Without external information it's impossible to reliably determine which
encoding was used for encoding a string. Each charmap encoding can
decode any random byte sequence. However that's not possible with UTF-8, as
UTF-8 byte sequences have a structure that doesn't allow arbitrary byte
sequences. To increase the reliability with which a UTF-8 encoding can be
detected, Microsoft invented a variant of UTF-8 (that Python calls
@code{"utf-8-sig"}) for its Notepad program: Before any of the Unicode characters
is written to the file, a UTF-8 encoded BOM (which looks like this as a byte
sequence: @code{0xef}, @code{0xbb}, @code{0xbf}) is written. As it's rather improbable
that any charmap encoded file starts with these byte values (which would e.g.
map to

@quotation


@display
LATIN SMALL LETTER I WITH DIAERESIS@w{ }
RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK@w{ }
INVERTED QUESTION MARK@w{ }
@end display


@end quotation

in iso-8859-1), this increases the probability that a @code{utf-8-sig} encoding can be
correctly guessed from the byte sequence. So here the BOM is not used to be able
to determine the byte order used for generating the byte sequence, but as a
signature that helps in guessing the encoding. On encoding the utf-8-sig codec
will write @code{0xef}, @code{0xbb}, @code{0xbf} as the first three bytes to the file. On
decoding @code{utf-8-sig} will skip those three bytes if they appear as the first
three bytes in the file. In UTF-8, the use of the BOM is discouraged and
should generally be avoided.

@node Standard Encodings,Python Specific Encodings,Encodings and Unicode,codecs --- Codec registry and base classes
@anchor{library/codecs id3}@anchor{2394}@anchor{library/codecs standard-encodings}@anchor{da6}
@subsubsection Standard Encodings


Python comes with a number of codecs built-in, either implemented as C functions
or with dictionaries as mapping tables. The following table lists the codecs by
name, together with a few common aliases, and the languages for which the
encoding is likely used. Neither the list of aliases nor the list of languages
is meant to be exhaustive. Notice that spelling alternatives that only differ in
case or use a hyphen instead of an underscore are also valid aliases; therefore,
e.g. @code{'utf-8'} is a valid alias for the @code{'utf_8'} codec.

`Particularité de l'implémentation CPython :' Some common encodings can bypass the codecs lookup machinery to
improve performance. These optimization opportunities are only
recognized by CPython for a limited set of (case insensitive)
aliases: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs
(Windows only), ascii, us-ascii, utf-16, utf16, utf-32, utf32, and
the same using underscores instead of dashes. Using alternative
aliases for these encodings may result in slower execution.


Modifié dans la version 3.6: Optimization opportunity recognized for us-ascii.


Many of the character sets support the same languages. They vary in individual
characters (e.g. whether the EURO SIGN is supported or not), and in the
assignment of characters to code positions. For the European languages in
particular, the following variants typically exist:


@itemize *

@item 
an ISO 8859 codeset

@item 
a Microsoft Windows code page, which is typically derived from an 8859 codeset,
but replaces control characters with additional graphic characters

@item 
an IBM EBCDIC code page

@item 
an IBM PC code page, which is ASCII compatible
@end itemize


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Languages

@item

`ascii'

@tab

`646', `us-ascii'

@tab

Anglais

@item

`big5'

@tab

`big5-tw', `csbig5'

@tab

Chinois Traditionnel

@item

`big5hkscs'

@tab

`big5-hkscs', `hkscs'

@tab

Chinois Traditionnel

@item

`cp037'

@tab

`IBM037', `IBM039'

@tab

Anglais

@item

`cp273'

@tab

`273', `IBM273', `csIBM273'

@tab

Allemand


Ajouté dans la version 3.4.


@item

`cp424'

@tab

`EBCDIC-CP-HE', `IBM424'

@tab

Hébreux

@item

`cp437'

@tab

`437', `IBM437'

@tab

Anglais

@item

`cp500'

@tab

`EBCDIC-CP-BE', `EBCDIC-CP-CH', `IBM500'

@tab

Europe de l'ouest

@item

`cp720'

@tab

@tab

Arabe

@item

`cp737'

@tab

@tab

Grec

@item

`cp775'

@tab

`IBM775'

@tab

Langues Baltiques

@item

`cp850'

@tab

`850', `IBM850'

@tab

Europe de l'ouest

@item

`cp852'

@tab

`852', `IBM852'

@tab

Europe centrale et Europe de l'Est

@item

`cp855'

@tab

`855', `IBM855'

@tab

Bulgare, Biélorusse, Macédonien, Russe, Serbe

@item

`cp856'

@tab

@tab

Hébreux

@item

`cp857'

@tab

`857', `IBM857'

@tab

Turc

@item

`cp858'

@tab

`858', `IBM858'

@tab

Europe de l'ouest

@item

`cp860'

@tab

`860', `IBM860'

@tab

Portugais

@item

`cp861'

@tab

`861', `CP-IS', `IBM861'

@tab

Islandais

@item

`cp862'

@tab

`862', `IBM862'

@tab

Hébreux

@item

`cp863'

@tab

`863', `IBM863'

@tab

Canadien

@item

`cp864'

@tab

`IBM864'

@tab

Arabe

@item

`cp865'

@tab

`865', `IBM865'

@tab

Danish, Norwegian

@item

`cp866'

@tab

`866', `IBM866'

@tab

Russe

@item

`cp869'

@tab

`869', `CP-GR', `IBM869'

@tab

Grec

@item

`cp874'

@tab

@tab

Thai

@item

`cp875'

@tab

@tab

Grec

@item

`cp932'

@tab

932, ms932, mskanji, ms-kanji,
windows-31j

@tab

Japanese

@item

`cp949'

@tab

`949', `ms949', `uhc'

@tab

Korean

@item

`cp950'

@tab

`950', `ms950'

@tab

Chinois Traditionnel

@item

`cp1006'

@tab

@tab

Urdu

@item

`cp1026'

@tab

`ibm1026'

@tab

Turc

@item

`cp1125'

@tab

`1125', `ibm1125', `cp866u', `ruscii'

@tab

Ukrainian


Ajouté dans la version 3.4.


@item

`cp1140'

@tab

`ibm1140'

@tab

Europe de l'ouest

@item

`cp1250'

@tab

`windows-1250'

@tab

Europe centrale et Europe de l'Est

@item

`cp1251'

@tab

`windows-1251'

@tab

Bulgare, Biélorusse, Macédonien, Russe, Serbe

@item

`cp1252'

@tab

`windows-1252'

@tab

Europe de l'ouest

@item

`cp1253'

@tab

`windows-1253'

@tab

Grec

@item

`cp1254'

@tab

`windows-1254'

@tab

Turc

@item

`cp1255'

@tab

`windows-1255'

@tab

Hébreux

@item

`cp1256'

@tab

`windows-1256'

@tab

Arabe

@item

`cp1257'

@tab

`windows-1257'

@tab

Langues Baltiques

@item

`cp1258'

@tab

`windows-1258'

@tab

Vietnamese

@item

`euc_jp'

@tab

`eucjp', `ujis', `u-jis'

@tab

Japanese

@item

`euc_jis_2004'

@tab

`jisx0213', `eucjis2004'

@tab

Japanese

@item

`euc_jisx0213'

@tab

`eucjisx0213'

@tab

Japanese

@item

`euc_kr'

@tab

`euckr', `korean', `ksc5601', `ks_c-5601', `ks_c-5601-1987', `ksx1001', `ks_x-1001'

@tab

Korean

@item

`gb2312'

@tab

`chinese', `csiso58gb231280', `euc-cn', `euccn', `eucgb2312-cn', `gb2312-1980', `gb2312-80', `iso-ir-58'

@tab

Simplified Chinese

@item

`gbk'

@tab

`936', `cp936', `ms936'

@tab

Unified Chinese

@item

`gb18030'

@tab

`gb18030-2000'

@tab

Unified Chinese

@item

`hz'

@tab

`hzgb', `hz-gb', `hz-gb-2312'

@tab

Simplified Chinese

@item

`iso2022_jp'

@tab

`csiso2022jp', `iso2022jp', `iso-2022-jp'

@tab

Japanese

@item

`iso2022_jp_1'

@tab

`iso2022jp-1', `iso-2022-jp-1'

@tab

Japanese

@item

`iso2022_jp_2'

@tab

`iso2022jp-2', `iso-2022-jp-2'

@tab

Japanese, Korean, Simplified
Chinese, Western Europe, Greek

@item

`iso2022_jp_2004'

@tab

`iso2022jp-2004', `iso-2022-jp-2004'

@tab

Japanese

@item

`iso2022_jp_3'

@tab

`iso2022jp-3', `iso-2022-jp-3'

@tab

Japanese

@item

`iso2022_jp_ext'

@tab

`iso2022jp-ext', `iso-2022-jp-ext'

@tab

Japanese

@item

`iso2022_kr'

@tab

`csiso2022kr', `iso2022kr', `iso-2022-kr'

@tab

Korean

@item

`latin_1'

@tab

`iso-8859-1', `iso8859-1', `8859', `cp819', `latin', `latin1', `L1'

@tab

Europe de l'ouest

@item

`iso8859_2'

@tab

`iso-8859-2', `latin2', `L2'

@tab

Europe centrale et Europe de l'Est

@item

`iso8859_3'

@tab

`iso-8859-3', `latin3', `L3'

@tab

Esperanto, Maltese

@item

`iso8859_4'

@tab

`iso-8859-4', `latin4', `L4'

@tab

Langues Baltiques

@item

`iso8859_5'

@tab

`iso-8859-5', `cyrillic'

@tab

Bulgare, Biélorusse, Macédonien, Russe, Serbe

@item

`iso8859_6'

@tab

`iso-8859-6', `arabic'

@tab

Arabe

@item

`iso8859_7'

@tab

`iso-8859-7', `greek', `greek8'

@tab

Grec

@item

`iso8859_8'

@tab

`iso-8859-8', `hebrew'

@tab

Hébreux

@item

`iso8859_9'

@tab

`iso-8859-9', `latin5', `L5'

@tab

Turc

@item

`iso8859_10'

@tab

`iso-8859-10', `latin6', `L6'

@tab

Nordic languages

@item

`iso8859_11'

@tab

`iso-8859-11', `thai'

@tab

Thai languages

@item

`iso8859_13'

@tab

`iso-8859-13', `latin7', `L7'

@tab

Langues Baltiques

@item

`iso8859_14'

@tab

`iso-8859-14', `latin8', `L8'

@tab

Celtic languages

@item

`iso8859_15'

@tab

`iso-8859-15', `latin9', `L9'

@tab

Europe de l'ouest

@item

`iso8859_16'

@tab

`iso-8859-16', `latin10', `L10'

@tab

South-Eastern Europe

@item

`johab'

@tab

`cp1361', `ms1361'

@tab

Korean

@item

`koi8_r'

@tab

@tab

Russe

@item

`koi8_t'

@tab

@tab

`Tajik'


Ajouté dans la version 3.5.


@item

`koi8_u'

@tab

@tab

Ukrainian

@item

`kz1048'

@tab

`kz_1048', `strk1048_2002', `rk1048'

@tab

Kazakh


Ajouté dans la version 3.5.


@item

`mac_cyrillic'

@tab

`maccyrillic'

@tab

Bulgare, Biélorusse, Macédonien, Russe, Serbe

@item

`mac_greek'

@tab

`macgreek'

@tab

Grec

@item

`mac_iceland'

@tab

`maciceland'

@tab

Islandais

@item

`mac_latin2'

@tab

maclatin2, maccentraleurope,
mac_centeuro

@tab

Europe centrale et Europe de l'Est

@item

`mac_roman'

@tab

`macroman', `macintosh'

@tab

Europe de l'ouest

@item

`mac_turkish'

@tab

`macturkish'

@tab

Turc

@item

`ptcp154'

@tab

`csptcp154', `pt154', `cp154', `cyrillic-asian'

@tab

Kazakh

@item

`shift_jis'

@tab

`csshiftjis', `shiftjis', `sjis', `s_jis'

@tab

Japanese

@item

`shift_jis_2004'

@tab

`shiftjis2004', `sjis_2004', `sjis2004'

@tab

Japanese

@item

`shift_jisx0213'

@tab

`shiftjisx0213', `sjisx0213', `s_jisx0213'

@tab

Japanese

@item

`utf_32'

@tab

`U32', `utf32'

@tab

all languages

@item

`utf_32_be'

@tab

`UTF-32BE'

@tab

all languages

@item

`utf_32_le'

@tab

`UTF-32LE'

@tab

all languages

@item

`utf_16'

@tab

`U16', `utf16'

@tab

all languages

@item

`utf_16_be'

@tab

`UTF-16BE'

@tab

all languages

@item

`utf_16_le'

@tab

`UTF-16LE'

@tab

all languages

@item

`utf_7'

@tab

`U7', `unicode-1-1-utf-7'

@tab

all languages

@item

`utf_8'

@tab

U8, UTF, utf8, cp65001

@tab

all languages

@item

`utf_8_sig'

@tab

@tab

all languages

@end multitable



Modifié dans la version 3.4: The utf-16* and utf-32* encoders no longer allow surrogate code points
(@code{U+D800}--@code{U+DFFF}) to be encoded.
The utf-32* decoders no longer decode
byte sequences that correspond to surrogate code points.



Modifié dans la version 3.8: @code{cp65001} is now an alias to @code{utf_8}.


@node Python Specific Encodings,encodings idna --- Internationalized Domain Names in Applications,Standard Encodings,codecs --- Codec registry and base classes
@anchor{library/codecs python-specific-encodings}@anchor{2395}
@subsubsection Python Specific Encodings


A number of predefined codecs are specific to Python, so their codec names have
no meaning outside Python. These are listed in the tables below based on the
expected input and output types (note that while text encodings are the most
common use case for codecs, the underlying codec infrastructure supports
arbitrary data transforms rather than just text encodings). For asymmetric
codecs, the stated meaning describes the encoding direction.

@menu
* Text Encodings:: 
* Binary Transforms:: 
* Text Transforms:: 

@end menu

@node Text Encodings,Binary Transforms,,Python Specific Encodings
@anchor{library/codecs text-encodings}@anchor{2396}
@subsubsection Text Encodings


The following codecs provide @ref{435,,str} to @ref{1bd,,bytes} encoding and
@ref{d1b,,bytes-like object} to @ref{435,,str} decoding, similar to the Unicode text
encodings.


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Signification

@item

idna

@tab

@tab

Implement 
@geindex RFC; RFC 3490
RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html},
see also
@ref{51,,encodings.idna}.
Only @code{errors='strict'}
is supported.

@item

mbcs

@tab

ansi,
dbcs

@tab

Windows only: Encode the
operand according to the
ANSI codepage (CP_ACP).

@item

oem

@tab

@tab

Windows only: Encode the
operand according to the
OEM codepage (CP_OEMCP).


Ajouté dans la version 3.6.


@item

palmos

@tab

@tab

Encoding of PalmOS 3.5.

@item

punycode

@tab

@tab

Implement 
@geindex RFC; RFC 3492
RFC 3492@footnote{https://datatracker.ietf.org/doc/html/rfc3492.html}.
Stateful codecs are not
supported.

@item

raw_unicode_escape

@tab

@tab

Latin-1 encoding with
@code{\u@var{XXXX}} and
@code{\U@var{XXXXXXXX}}
for other code points.
Existing
backslashes are not
escaped in any way.
It is used in the Python
pickle protocol.

@item

undefined

@tab

@tab

Raise an exception for
all conversions, even
empty strings. The error
handler is ignored.

@item

unicode_escape

@tab

@tab

Encoding suitable as the
contents of a Unicode
literal in ASCII-encoded
Python source code,
except that quotes are
not escaped. Decode
from Latin-1 source code.
Beware that Python source
code actually uses UTF-8
by default.

@end multitable



Modifié dans la version 3.8: "unicode_internal" codec is removed.


@node Binary Transforms,Text Transforms,Text Encodings,Python Specific Encodings
@anchor{library/codecs binary-transforms}@anchor{eee}@anchor{library/codecs id4}@anchor{2397}
@subsubsection Binary Transforms


The following codecs provide binary transforms: @ref{d1b,,bytes-like object}
to @ref{1bd,,bytes} mappings. They are not supported by @ref{8c3,,bytes.decode()}
(which only produces @ref{435,,str} output).


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Signification

@tab

Encoder / decoder

@item

base64_codec @footnote{
In addition to @ref{d1b,,bytes-like objects},
@code{'base64_codec'} also accepts ASCII-only instances of @ref{435,,str} for
decoding
}

@tab

base64, base_64

@tab

Convert the operand to
multiline MIME base64 (the
result always includes a
trailing @code{'\n'}).


Modifié dans la version 3.4: accepts any
@ref{d1b,,bytes-like object}
as input for encoding and
decoding


@tab

@ref{940,,base64.encodebytes()} /
@ref{941,,base64.decodebytes()}

@item

bz2_codec

@tab

bz2

@tab

Compress the operand using
bz2.

@tab

@ref{2398,,bz2.compress()} /
@ref{1078,,bz2.decompress()}

@item

hex_codec

@tab

hex

@tab

Convert the operand to
hexadecimal
representation, with two
digits per byte.

@tab

@ref{2399,,binascii.b2a_hex()} /
@ref{239a,,binascii.a2b_hex()}

@item

quopri_codec

@tab

quopri,
quotedprintable,
quoted_printable

@tab

Convert the operand to MIME
quoted printable.

@tab

@ref{239b,,quopri.encode()} with
@code{quotetabs=True} /
@ref{239c,,quopri.decode()}

@item

uu_codec

@tab

uu

@tab

Convert the operand using
uuencode.

@tab

@item

zlib_codec

@tab

zip, zlib

@tab

Compress the operand using
gzip.

@tab

@ref{62a,,zlib.compress()} /
@ref{cfb,,zlib.decompress()}

@end multitable



Ajouté dans la version 3.2: Restoration of the binary transforms.



Modifié dans la version 3.4: Restoration of the aliases for the binary transforms.


@node Text Transforms,,Binary Transforms,Python Specific Encodings
@anchor{library/codecs id6}@anchor{239d}@anchor{library/codecs text-transforms}@anchor{eef}
@subsubsection Text Transforms


The following codec provides a text transform: a @ref{435,,str} to @ref{435,,str}
mapping. It is not supported by @ref{8c2,,str.encode()} (which only produces
@ref{1bd,,bytes} output).


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Codec

@tab

Aliases

@tab

Signification

@item

rot_13

@tab

rot13

@tab

Return the Caesar-cypher
encryption of the
operand.

@end multitable



Ajouté dans la version 3.2: Restoration of the @code{rot_13} text transform.



Modifié dans la version 3.4: Restoration of the @code{rot13} alias.


@node encodings idna --- Internationalized Domain Names in Applications,encodings mbcs --- Windows ANSI codepage,Python Specific Encodings,codecs --- Codec registry and base classes
@anchor{library/codecs encodings-idna-internationalized-domain-names-in-applications}@anchor{239e}@anchor{library/codecs module-encodings idna}@anchor{51}
@subsubsection @code{encodings.idna} --- Internationalized Domain Names in Applications


@geindex module; encodings.idna

This module implements 
@geindex RFC; RFC 3490
RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html} (Internationalized Domain Names in
Applications) and 
@geindex RFC; RFC 3492
RFC 3492@footnote{https://datatracker.ietf.org/doc/html/rfc3492.html} (Nameprep: A Stringprep Profile for
Internationalized Domain Names (IDN)). It builds upon the @code{punycode} encoding
and @ref{d3,,stringprep}.

If you need the IDNA 2008 standard from 
@geindex RFC; RFC 5891
RFC 5891@footnote{https://datatracker.ietf.org/doc/html/rfc5891.html} and 
@geindex RFC; RFC 5895
RFC 5895@footnote{https://datatracker.ietf.org/doc/html/rfc5895.html}, use the
third-party idna@footnote{https://pypi.org/project/idna/} module.

These RFCs together define a protocol to support non-ASCII characters in domain
names. A domain name containing non-ASCII characters (such as
@code{www.Alliancefrançaise.nu}) is converted into an ASCII-compatible encoding
(ACE, such as @code{www.xn--alliancefranaise-npb.nu}). The ACE form of the domain
name is then used in all places where arbitrary characters are not allowed by
the protocol, such as DNS queries, HTTP @code{Host} fields, and so
on. This conversion is carried out in the application; if possible invisible to
the user: The application should transparently convert Unicode domain labels to
IDNA on the wire, and convert back ACE labels to Unicode before presenting them
to the user.

Python supports this conversion in several ways:  the @code{idna} codec performs
conversion between Unicode and ACE, separating an input string into labels
based on the separator characters defined in 
@geindex RFC; RFC 3490 Section 3.1
section 3.1 of RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html#section-3.1}
and converting each label to ACE as required, and conversely separating an input
byte string into labels based on the @code{.} separator and converting any ACE
labels found into unicode. Furthermore, the @ref{cb,,socket} module
transparently converts Unicode host names to ACE, so that applications need not
be concerned about converting host names themselves when they pass them to the
socket module. On top of that, modules that have host names as function
parameters, such as @ref{6e,,http.client} and @ref{5d,,ftplib}, accept Unicode host
names (@ref{6e,,http.client} then also transparently sends an IDNA hostname in the
@code{Host} field if it sends that field at all).

When receiving host names from the wire (such as in reverse name lookup), no
automatic conversion to Unicode is performed: applications wishing to present
such host names to the user should decode them to Unicode.

The module @ref{51,,encodings.idna} also implements the nameprep procedure, which
performs certain normalizations on host names, to achieve case-insensitivity of
international domain names, and to unify similar characters. The nameprep
functions can be used directly if desired.

@geindex nameprep() (dans le module encodings.idna)
@anchor{library/codecs encodings idna nameprep}@anchor{239f}
@deffn {Fonction} encodings.idna.nameprep (label)

Return the nameprepped version of `label'. The implementation currently assumes
query strings, so @code{AllowUnassigned} is true.
@end deffn

@geindex ToASCII() (dans le module encodings.idna)
@anchor{library/codecs encodings idna ToASCII}@anchor{23a0}
@deffn {Fonction} encodings.idna.ToASCII (label)

Convert a label to ASCII, as specified in 
@geindex RFC; RFC 3490
RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html}. @code{UseSTD3ASCIIRules} is
assumed to be false.
@end deffn

@geindex ToUnicode() (dans le module encodings.idna)
@anchor{library/codecs encodings idna ToUnicode}@anchor{23a1}
@deffn {Fonction} encodings.idna.ToUnicode (label)

Convert a label to Unicode, as specified in 
@geindex RFC; RFC 3490
RFC 3490@footnote{https://datatracker.ietf.org/doc/html/rfc3490.html}.
@end deffn

@node encodings mbcs --- Windows ANSI codepage,encodings utf_8_sig --- UTF-8 codec with BOM signature,encodings idna --- Internationalized Domain Names in Applications,codecs --- Codec registry and base classes
@anchor{library/codecs encodings-mbcs-windows-ansi-codepage}@anchor{23a2}@anchor{library/codecs module-encodings mbcs}@anchor{52}
@subsubsection @code{encodings.mbcs} --- Windows ANSI codepage


@geindex module; encodings.mbcs

This module implements the ANSI codepage (CP_ACP).

@ref{1ce0,,Availability}: Windows.


Modifié dans la version 3.2: Before 3.2, the `errors' argument was ignored; @code{'replace'} was always used
to encode, and @code{'ignore'} to decode.



Modifié dans la version 3.3: Support any error handler.


@node encodings utf_8_sig --- UTF-8 codec with BOM signature,,encodings mbcs --- Windows ANSI codepage,codecs --- Codec registry and base classes
@anchor{library/codecs encodings-utf-8-sig-utf-8-codec-with-bom-signature}@anchor{23a3}@anchor{library/codecs module-encodings utf_8_sig}@anchor{53}
@subsubsection @code{encodings.utf_8_sig} --- UTF-8 codec with BOM signature


@geindex module; encodings.utf_8_sig

This module implements a variant of the UTF-8 codec. On encoding, a UTF-8 encoded
BOM will be prepended to the UTF-8 encoded bytes. For the stateful encoder this
is only done once (on the first write to the byte stream). On decoding, an
optional UTF-8 encoded BOM at the start of the data will be skipped.

@node Types de données,Modules numériques et mathématiques,Services autour des Données Binaires,La bibliothèque standard
@anchor{library/datatypes doc}@anchor{23a4}@anchor{library/datatypes data-types}@anchor{23a5}@anchor{library/datatypes datatypes}@anchor{23a6}
@section Types de données


Les modules documentés dans ce chapitre fournissent une gamme de types de données spécialisés tel que les dates et les heures, les listes à type prédéfini, les `heap queue', les queues synchronisées et les énumérations.

Python fournit aussi quelques types natifs, typiquement @ref{253,,dict}, @ref{5fc,,list}, @ref{5c3,,set}, @ref{5c4,,frozenset}, et @ref{366,,tuple}. La classe @ref{435,,str} est utilisée pour stocker des chaînes Unicode, et les classes @ref{1bd,,bytes} et @ref{528,,bytearray} des données binaires.

Les modules suivants sont documentés dans ce chapitre :

@menu
* datetime — Types de base pour la date et l'heure:: 
* zoneinfo: zoneinfo --- IANA time zone support. IANA time zone support
* calendar: calendar --- General calendar-related functions. General calendar-related functions
* collections: collections --- Container datatypes. Container datatypes
* collections.abc: collections abc --- Abstract Base Classes for Containers. Abstract Base Classes for Containers
* heapq: heapq --- Heap queue algorithm. Heap queue algorithm
* bisect: bisect --- Array bisection algorithm. Array bisection algorithm
* array: array --- Efficient arrays of numeric values. Efficient arrays of numeric values
* weakref: weakref --- Weak references. Weak references
* types: types --- Dynamic type creation and names for built-in types. Dynamic type creation and names for built-in types
* copy: copy --- Shallow and deep copy operations. Shallow and deep copy operations
* pprint — L’affichage élégant de données:: 
* reprlib: reprlib --- Alternate repr implementation. Alternate repr() implementation
* enum: enum --- Support for enumerations. Support for enumerations
* graphlib: graphlib --- Functionality to operate with graph-like structures. Functionality to operate with graph-like structures

@end menu

@node datetime — Types de base pour la date et l'heure,zoneinfo --- IANA time zone support,,Types de données
@anchor{library/datetime doc}@anchor{23a7}@anchor{library/datetime datetime-basic-date-and-time-types}@anchor{23a8}@anchor{library/datetime module-datetime}@anchor{30}
@subsection @code{datetime} — Types de base pour la date et l'heure


@geindex module; datetime

`Code source :' Lib/datetime.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/datetime.py}


__________________________________________________________________


@c XXX what order should the types be discussed in?

Le module @code{datetime} fournit des classes permettant de manipuler les dates et les heures.

Bien que les calculs de date et d'heure sont gérés, l'attention lors de l'implémentation s'est essentiellement portée sur l'efficacité de l'extraction des attributs en vue de leur manipulation et formatage pour l'affichage.

@cartouche
@quotation Astuce 
Skip to @ref{23a9,,the format codes}.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item Module @ref{14,,calendar}

Fonctions génériques associées au calendrier.

@item Module @ref{ed,,time}

Accès aux données d'horaires et aux conversions associées.

@item Module @ref{133,,zoneinfo}

Fuseaux horaires concrets représentant la base de données IANA.

@item Paquet dateutil@footnote{https://dateutil.readthedocs.io/en/stable/}

Bibliothèque tierce avec prise en charge complète du fuseau horaire et de l'analyse de dates sous forme textuelle.

@item Package DateType@footnote{https://pypi.org/project/DateType/}

Bibliothèque tierce qui introduit des types statiques distincts pour, par ex. permettre  aux @ref{26a,,vérificateurs statiques de typage} de faire la différence entre les dates et horaires naïfs et avisés.
@end table


@menu
* Objets avisés et naïfs:: 
* Constantes:: 
* Types disponibles:: 
* Objets timedelta:: 
* Objets date:: 
* Objets datetime:: 
* Objets time:: 
* Objets tzinfo:: 
* Objets timezone:: 
* strftime() and strptime() Behavior: strftime and strptime Behavior. 

@end menu

@node Objets avisés et naïfs,Constantes,,datetime — Types de base pour la date et l'heure
@anchor{library/datetime aware-and-naive-objects}@anchor{23aa}@anchor{library/datetime datetime-naive-aware}@anchor{23ab}
@subsubsection Objets avisés et naïfs


Les objets `date' et `time' peuvent être classés comme « avisés » ou « naïfs » selon qu'ils contiennent ou non des informations sur le fuseau horaire.

Un objet `avisé' possède suffisamment de connaissance des règles à appliquer et des politiques d'ajustement de l'heure comme les informations sur les fuseaux horaires et l'heure d'été pour se situer de façon relative par rapport à d'autres objets avisés. Un objet avisé est utilisé pour représenter un instant précis qui n'est pas ouvert à l'interprétation @footnote{
Si on ignore les effets de la Relativité
}.

Un objet `naïf' ne comporte pas assez d'informations pour se situer sans ambiguïté par rapport à d'autres objets `date/time'. Le fait qu'un objet naïf représente un Temps universel coordonné (UTC), une heure locale ou une heure dans un autre fuseau horaire dépend complètement du programme, tout comme un nombre peut représenter une longueur, un poids ou une distance pour le programme. Les objets naïfs sont simples à comprendre et il est aisé de travailler avec, au prix de négliger certains aspects de la réalité.

Pour les applications nécessitant des objets avisés, les objets @ref{1c7,,datetime} et @ref{1c9,,time} ont un attribut facultatif renseignant le fuseau horaire, @code{tzinfo}, qui peut être une instance d'une sous-classe de la classe abstraite @ref{5c8,,tzinfo}. Ces objets @ref{5c8,,tzinfo} regroupent des informations sur le décalage par rapport à l'heure UTC, le nom du fuseau horaire, et si l'heure d'été est en vigueur.

Notez qu'une seule classe concrète @ref{5c8,,tzinfo}, la classe @ref{10a1,,timezone}, est proposée par le module @code{datetime}. La classe @code{timezone} peut représenter des fuseaux horaires simples avec un décalage fixe par rapport à UTC, comme UTC lui-même ou les fuseaux EST et EDT d'Amérique du Nord. Gérer des fuseaux horaires d'un niveau de détails plus avancé est à la charge de l'application. Les règles d'ajustement du temps à travers le monde sont plus politiques que rationnelles, changent fréquemment, et il n'y a pas de standard qui vaille pour toute application, en dehors d'UTC.

@node Constantes,Types disponibles,Objets avisés et naïfs,datetime — Types de base pour la date et l'heure
@anchor{library/datetime constants}@anchor{23ac}
@subsubsection Constantes


Le module @code{datetime} exporte les constantes suivantes :

@geindex MINYEAR (dans le module datetime)
@anchor{library/datetime datetime MINYEAR}@anchor{23ad}
@deffn {Données} datetime.MINYEAR

Le numéro d'année le plus petit autorisé dans un objet @ref{1c8,,date} ou @ref{1c7,,datetime}. @ref{23ad,,MINYEAR} vaut 1.
@end deffn

@geindex MAXYEAR (dans le module datetime)
@anchor{library/datetime datetime MAXYEAR}@anchor{23ae}
@deffn {Données} datetime.MAXYEAR

Le numéro d'année le plus grand autorisé dans un objet @ref{1c8,,date} ou @ref{1c7,,datetime}. @ref{23ae,,MAXYEAR} vaut 9999.
@end deffn

@geindex UTC (dans le module datetime)
@anchor{library/datetime datetime UTC}@anchor{4d8}
@deffn {Attribut} datetime.UTC

Alias du singleton de fuseau horaire UTC @ref{5ff,,datetime.timezone.utc}.


Ajouté dans la version 3.11.

@end deffn

@node Types disponibles,Objets timedelta,Constantes,datetime — Types de base pour la date et l'heure
@anchor{library/datetime available-types}@anchor{23af}
@subsubsection Types disponibles



@deffn {Classe} datetime.date

Une date naïve idéalisée, en supposant que le calendrier Grégorien actuel a toujours existé et qu'il existera toujours. Attributs : @ref{23b0,,year}, @ref{23b1,,month} et @ref{23b2,,day}.
@end deffn


@deffn {Classe} datetime.time

Un temps idéalisé, indépendant d'une date particulière, en supposant qu'une journée est composée d'exactement 24*60*60 secondes (il n'y a pas ici de notion de « seconde intercalaire »). Attributs : @ref{23b3,,hour}, @ref{23b4,,minute}, @ref{23b5,,second}, @ref{23b6,,microsecond} et @ref{23b7,,tzinfo}.
@end deffn


@deffn {Classe} datetime.datetime

Une combinaison d'une date et d'une heure. Attributs : @ref{23b8,,year}, @ref{23b9,,month}, @ref{23ba,,day}, @ref{23bb,,hour}, @ref{23bc,,minute}, @ref{23bd,,second}, @ref{23be,,microsecond}, et @ref{23bf,,tzinfo}.
@end deffn


@deffn {Classe} datetime.timedelta

Une durée qui exprime la différence entre deux instances de @ref{1c7,,datetime} ou @ref{1c8,,date} en microsecondes.
@end deffn


@deffn {Classe} datetime.tzinfo

Une classe mère abstraite pour les objets portants des informations sur les fuseaux horaires. Ceux-ci sont utilisés par les classes @ref{1c7,,datetime} et @ref{1c9,,time} pour donner une notion personnalisable d'ajustement d'horaire (par exemple la prise en compte d'un fuseau horaire et/ou de l'heure d'été).
@end deffn


@deffn {Classe} datetime.timezone

Une classe qui implémente la classe mère abstraite @ref{5c8,,tzinfo} en tant que décalage fixe par rapport au temps UTC.


Ajouté dans la version 3.2.

@end deffn

Les objets issus de ces types sont immuables.

Relations entre les sous-classes :

@example
object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime
@end example

@menu
* Propriétés communes:: 
* Catégorisation d'un objet en « avisé » ou « naïf »:: 

@end menu

@node Propriétés communes,Catégorisation d'un objet en « avisé » ou « naïf »,,Types disponibles
@anchor{library/datetime common-properties}@anchor{23c0}
@subsubsection Propriétés communes


Les types @ref{1c8,,date}, @ref{1c7,,datetime}, @ref{1c9,,time}, et @ref{10a1,,timezone} partagent les caractéristiques suivantes :


@itemize -

@item 
Les objets issus de ces types sont immuables.

@item 
Les objets de ces types sont @ref{5fb,,hachable}, ce qui signifie qu'ils peuvent être utilisés comme clés de dictionnaire.

@item 
Les objets de ces types peuvent être sérialisés efficacement par le module @ref{a5,,pickle}.
@end itemize

@node Catégorisation d'un objet en « avisé » ou « naïf »,,Propriétés communes,Types disponibles
@anchor{library/datetime determining-if-an-object-is-aware-or-naive}@anchor{23c1}
@subsubsection Catégorisation d'un objet en « avisé » ou « naïf »


Les objets de type @ref{1c8,,date} sont toujours naïfs.

Un objet du type @ref{1c9,,time} ou @ref{1c7,,datetime} peut être avisé ou naïf.

Un objet @ref{1c7,,datetime} @code{d} est avisé si les deux conditions suivantes vérifient :


@enumerate 

@item 
@code{d.tzinfo} ne vaut pas @code{None}

@item 
@code{d.tzinfo.utcoffset(d)} ne renvoie pas @code{None}
@end enumerate

Autrement, @code{d} est naïf.

Un objet @ref{1c9,,time} @code{t} est avisé si les deux conditions suivantes vérifient :


@enumerate 

@item 
@code{t.tzinfo} ne vaut pas @code{None}

@item 
@code{t.tzinfo.utcoffset(None)} ne renvoie pas @code{None}.
@end enumerate

Autrement, @code{t} est naïf.

La distinction entre avisé et naïf ne s'applique pas aux objets de type @ref{9bd,,timedelta}.

@node Objets timedelta,Objets date,Types disponibles,datetime — Types de base pour la date et l'heure
@anchor{library/datetime datetime-timedelta}@anchor{23c2}@anchor{library/datetime timedelta-objects}@anchor{23c3}
@subsubsection Objets @code{timedelta}


Un objet @ref{9bd,,timedelta} représente une durée, c'est-à-dire la différence entre deux instances de @ref{1c7,,datetime} ou @ref{1c8,,date}.

@geindex timedelta (classe dans datetime)
@anchor{library/datetime datetime timedelta}@anchor{9bd}
@deffn {Classe} datetime.timedelta (days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

Tous les arguments sont optionnels et ont 0 comme valeur par défaut. Les arguments peuvent être des entiers ou des flottants et ils peuvent être positifs ou négatifs.

Seuls les `jours', les `secondes' et les `microsecondes' sont stockés en interne. Les arguments sont convertis dans ces unités :


@itemize *

@item 
Une milliseconde est convertie en 1000 microsecondes.

@item 
Une minute est convertie en 60 secondes.

@item 
Une heure est convertie en 3600 secondes.

@item 
Une semaine est convertie en 7 jours.
@end itemize

et ensuite les jours, secondes et microsecondes sont normalisés pour que la représentation soit unique avec


@itemize *

@item 
@code{0 <= microseconds < 1000000}

@item 
@code{0 <= secondes < 3600*24} (le nombre de secondes dans une journée)

@item 
@code{-999999999 <= days <= 999999999}
@end itemize

L'exemple suivant illustre comment tous les arguments autres que `days', `seconds' et `microseconds' sont « fusionnés » et normalisés dans ces trois attributs résultants :

@example
>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)
@end example

Si l'un des arguments est un flottant et qu'il y a des microsecondes décimales, les microsecondes décimales laissées par les arguments sont combinées et leur somme est arrondie à la microseconde la plus proche en arrondissant les demis vers le nombre pair. Si aucun argument n'est flottant, les processus de conversion et de normalisation seront exacts (pas d'informations perdues).

Si la valeur normalisée des jours déborde de l'intervalle indiqué, une @ref{86d,,OverflowError} est levée.

Notez que la normalisation de valeurs négatives peut être surprenante au premier abord. Par exemple :

@example
>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
@end example
@end deffn

Attributs de la classe :

@geindex min (attribut datetime.timedelta)
@anchor{library/datetime datetime timedelta min}@anchor{23c4}
@deffn {Attribut} timedelta.min

L'objet @ref{9bd,,timedelta} le plus négatif, @code{timedelta(-999999999)}.
@end deffn

@geindex max (attribut datetime.timedelta)
@anchor{library/datetime datetime timedelta max}@anchor{23c5}
@deffn {Attribut} timedelta.max

L'objet @ref{9bd,,timedelta} le plus positif, @code{timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)}.
@end deffn

@geindex resolution (attribut datetime.timedelta)
@anchor{library/datetime datetime timedelta resolution}@anchor{23c6}
@deffn {Attribut} timedelta.resolution

La plus petite différence entre des objets @ref{9bd,,timedelta} non égaux, @code{timedelta(microseconds=1)}.
@end deffn

Il est à noter, du fait de la normalisation, que @code{timedelta.max} est plus grand que @code{-timedelta.min}. @code{-timedelta.max} n'est pas représentable sous la forme d'un objet @ref{9bd,,timedelta}.

Attributs de l'instance (en lecture seule) :

@geindex days (attribut datetime.timedelta)
@anchor{library/datetime datetime timedelta days}@anchor{23c7}
@deffn {Attribut} timedelta.days

Entre -999999999 et 999999999 inclus
@end deffn

@geindex seconds (attribut datetime.timedelta)
@anchor{library/datetime datetime timedelta seconds}@anchor{23c8}
@deffn {Attribut} timedelta.seconds

Entre 0 et 86399 inclus.

@cartouche
@quotation Prudence 
It is a somewhat common bug for code to unintentionally use this attribute
when it is actually intended to get a @ref{12e4,,total_seconds()}
value instead:

@example
>>> from datetime import timedelta
>>> duration = timedelta(seconds=11235813)
>>> duration.days, duration.seconds
(130, 3813)
>>> duration.total_seconds()
11235813.0
@end example
@end quotation
@end cartouche
@end deffn

@geindex microseconds (attribut datetime.timedelta)
@anchor{library/datetime datetime timedelta microseconds}@anchor{23c9}
@deffn {Attribut} timedelta.microseconds

Entre 0 et 999999 inclus.
@end deffn

Opérations gérées :

@c XXX this table is too wide!


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@item

@code{t1 = t2 + t3}

@tab

Somme de @code{t2} et @code{t3}. Ensuite @code{t1 - t2 == t3} et @code{t1 - t3 == t2} sont des expressions vraies. (1)

@item

@code{t1 = t2 - t3}

@tab

Différence entre @code{t2} et @code{t3}. Ensuite @code{t1 == t2 - t3} et @code{t2 == t1 + t3} sont des expressions vraies. (1)(6)

@item

@code{t1 = t2 * i or t1 = i * t2}

@tab

Delta multiplié par un entier. Ensuite @code{t1 // i == t2} est vrai, en admettant que @code{i != 0}.

@item

@tab

De manière générale, @code{t1  * i == t1  * (i-1) + t1} est vrai. (1)

@item

@code{t1 = t2 * f or t1 = f * t2}

@tab

Delta multiplié par un flottant. Le résultat est arrondi au multiple le plus proche de @code{timedelta.resolution} en utilisant la règle de l'arrondi au pair le plus proche.

@item

@code{f = t2 / t3}

@tab

Division (3) de la durée totale @code{t2} par l'unité d'intervalle @code{t3}. Renvoie un objet @ref{2eb,,float}.

@item

@code{t1 = t2 / f or t1 = t2 / i}

@tab

Delta divisé par un flottant ou un entier. Le résultat est arrondi au multiple le plus proche de @code{timedelta.resolution} en utilisant la règle de l'arrondi au pair le plus proche.

@item

@code{t1 = t2 // i} or
@code{t1 = t2 // t3}

@tab

Le quotient est calculé et le reste (s'il y en a un) est ignoré. Dans le second cas, un entier est renvoyé. (3)

@item

@code{t1 = t2 % t3}

@tab

Le reste est calculé comme un objet de type @ref{9bd,,timedelta}. (3)

@item

@code{q, r = divmod(t1, t2)}

@tab

Calcule le quotient et le reste : @code{q = t1 // t2} (3) et @code{r = t1 % t2}. @code{q} est un entier et @code{r} est un objet @ref{9bd,,timedelta}.

@item

@code{+t1}

@tab

Renvoie un objet @ref{9bd,,timedelta} avec la même valeur. (2)

@item

@code{-t1}

@tab

Équivalent à @code{timedelta(-t1.days, -t1.seconds, -t1.microseconds)}, et à @code{t1 * -1}. (1)(4)

@item

@code{abs(t)}

@tab

Équivalent à @code{+t} quand @code{t.days >= 0}, et à @code{-t} quand @code{t.days < 0}. (2)

@item

@code{str(t)}

@tab

Renvoie une chaîne de la forme @code{[D day[s], ][H]H:MM:SS[.UUUUUU]}, où D est négatif pour @code{t} négatif. (5)

@item

@code{repr(t)}

@tab

Renvoie une chaîne de la forme objet @ref{9bd,,timedelta} comme un appel construit avec des valeurs d'attributs canoniques.

@end multitable


Notes :


@enumerate 

@item 
Ceci est exact, mais peut provoquer un débordement.

@item 
Ceci est exact, et ne peut pas provoquer un débordement.

@item 
Une division par zéro lève une @ref{932,,ZeroDivisionError}.

@item 
@code{-timedelta.max} n'est pas représentable avec un objet @ref{9bd,,timedelta}.

@item 
La représentation en chaîne des objets @ref{9bd,,timedelta} est normalisée similairement à leur représentation interne. Cela amène à des résultats inhabituels pour des `timedeltas' négatifs. Par exemple :

@example
>>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00
@end example

@item 
L'expression @code{t2 - t3} est toujours égale à l'expression @code{t2 + (-t3)} sauf si @code{t3} vaut @code{timedelta.max} ; dans ce cas, la première expression produit une valeur alors que la seconde produit un débordement.
@end enumerate

En plus des opérations listées ci-dessus, les objets @ref{9bd,,timedelta} implémentent certaines additions et soustractions avec des objets @ref{1c8,,date} et @ref{1c7,,datetime} (voir ci-dessous).


Modifié dans la version 3.2: La division entière et la vraie division d'un objet @ref{9bd,,timedelta} par un autre @ref{9bd,,timedelta} sont maintenant gérées, comme le sont les opérations de reste euclidien et la fonction @ref{98f,,divmod()}. La vraie division et la multiplication d'un objet @ref{9bd,,timedelta} par un @ref{2eb,,float} sont maintenant implémentées.


Les objets @ref{9bd,,timedelta} supportent les comparaisons d'égalité et d'ordre.

Dans les contextes booléens, un objet @ref{9bd,,timedelta} est considéré comme vrai si et seulement s'il n'est pas égal à @code{timedelta(0)}.

Méthodes de l'instance :

@geindex total_seconds() (méthode datetime.timedelta)
@anchor{library/datetime datetime timedelta total_seconds}@anchor{12e4}
@deffn {Méthode} timedelta.total_seconds ()

Renvoie le nombre total de secondes contenues dans la durée. Équivalent à @code{td / timedelta(seconds=1)}. Pour un intervalle dont l'unité n'est pas la seconde, utilisez directement la division (par exemple, @code{td / timedelta(microseconds=1)}).

Notez que pour des intervalles de temps très larges (supérieurs à 270 ans sur la plupart des plateformes), cette méthode perdra la précision des microsecondes.


Ajouté dans la version 3.2.

@end deffn

@menu
* Exemples d'utilisation de la classe timedelta ;: Exemples d'utilisation de la classe timedelta. 

@end menu

@node Exemples d'utilisation de la classe timedelta,,,Objets timedelta
@anchor{library/datetime examples-of-usage-timedelta}@anchor{23ca}
@subsubsection Exemples d'utilisation de la classe @code{timedelta} :


Un exemple supplémentaire de normalisation :

@example
>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0
@end example

Exemples d'arithmétique avec la classe @ref{9bd,,timedelta} :

@example
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
@end example

@node Objets date,Objets datetime,Objets timedelta,datetime — Types de base pour la date et l'heure
@anchor{library/datetime date-objects}@anchor{23cb}@anchor{library/datetime datetime-date}@anchor{23cc}
@subsubsection Objets @code{date}


Un objet @ref{1c8,,date} représente une date (année, mois et jour) dans un calendrier idéal, le calendrier grégorien actuel étant indéfiniment étendu dans les deux sens.

Le 1 @w{^er} janvier de l'année 1 est appelé jour numéro 1, le 2 janvier de l'année 1 est appelé jour numéro 2, et ainsi de suite. @footnote{
Cela correspond à la définition du calendrier « grégorien proleptique » dans le livre `Calendrical Calculations' de Dershowitz et Reingold, où il est la base de tous les calculs. Référez-vous au livre pour les algorithmes de conversion entre calendriers grégorien proleptique et les autres systèmes.
}

@geindex date (classe dans datetime)
@anchor{library/datetime datetime date}@anchor{1c8}
@deffn {Classe} datetime.date (year, month, day)

Tous les arguments sont requis. Les arguments peuvent être des entiers, dans les intervalles suivants :


@itemize *

@item 
@code{MINYEAR <= year <= MAXYEAR}

@item 
@code{1 <= month <= 12}

@item 
@code{1 <= day <= nombre de jours dans le mois et l'année donnés}
@end itemize

Si un argument est donné en dehors de ces intervalles, une @ref{1ff,,ValueError} est levée.
@end deffn

Autres constructeurs, méthodes de classe :

@geindex today() (méthode de la classe datetime.date)
@anchor{library/datetime datetime date today}@anchor{1480}
@deffn {Méthode} classmethod date.today ()

Renvoie la date locale courante.

Cela est équivalent à @code{date.fromtimestamp(time.time())}.
@end deffn

@geindex fromtimestamp() (méthode de la classe datetime.date)
@anchor{library/datetime datetime date fromtimestamp}@anchor{1592}
@deffn {Méthode} classmethod date.fromtimestamp (timestamp)

Renvoie la date locale correspondant à l'horodatage POSIX, telle que renvoyée par @ref{251,,time.time()}.

Elle peut lever une @ref{86d,,OverflowError}, si l'horodatage est en dehors des bornes gérées par la fonction C @code{localtime()} de la plateforme, et une exception @ref{40d,,OSError} en cas d'échec de @code{localtime()}. Il est commun d'être restreint aux années entre 1970 et 2038. Notez que sur les systèmes non `POSIX' qui incluent les secondes intercalaires dans leur notion d'horodatage, ces secondes sont ignorées par @ref{1592,,fromtimestamp()}.


Modifié dans la version 3.3: Lève une @ref{86d,,OverflowError} plutôt qu'une @ref{1ff,,ValueError} si l'horodatage (`timestamp' en anglais) est en dehors des bornes gérées par la fonction C @code{localtime()} de la plateforme. Lève une @ref{40d,,OSError} plutôt qu'une @ref{1ff,,ValueError} en cas d'échec de @code{localtime()}.

@end deffn

@geindex fromordinal() (méthode de la classe datetime.date)
@anchor{library/datetime datetime date fromordinal}@anchor{23cd}
@deffn {Méthode} classmethod date.fromordinal (ordinal)

Renvoie la date correspondant à l'ordinal grégorien proleptique, où le 1er janvier de l'an 1 a l'ordinal 1.

@ref{1ff,,ValueError} est levée à moins que @code{1 <= ordinal <= date.max.toordinal()}. Pour toute date @code{d}, @code{date.fromordinal(d.toordinal()) == d}.
@end deffn

@geindex fromisoformat() (méthode de la classe datetime.date)
@anchor{library/datetime datetime date fromisoformat}@anchor{600}
@deffn {Méthode} classmethod date.fromisoformat (date_string)

Renvoie une @ref{1c8,,date} correspondant à `date_string' dans un format ISO 8601 valide, avec les exceptions suivantes :


@enumerate 

@item 
Les dates à précision réduite ne sont actuellement pas gérées (@code{YYYY-MM}, @code{YYYY}).

@item 
Extended date representations are not currently supported
(@code{±YYYYYY-MM-DD}).

@item 
Ordinal dates are not currently supported (@code{YYYY-OOO}).
@end enumerate

Exemples :

@example
>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)
@end example


Ajouté dans la version 3.7.



Modifié dans la version 3.11: Auparavant, cette méthode prenait en charge seulement le format @code{YYYY-MM-DD}.

@end deffn

@geindex fromisocalendar() (méthode de la classe datetime.date)
@anchor{library/datetime datetime date fromisocalendar}@anchor{9da}
@deffn {Méthode} classmethod date.fromisocalendar (year, week, day)

Renvoie une @ref{1c8,,date} correspondant à la date du calendrier ISO définie par l'année, la semaine et le jour. C'est la réciproque de la fonction @ref{8e2,,date.isocalendar()}.


Ajouté dans la version 3.8.

@end deffn

Attributs de la classe :

@geindex min (attribut datetime.date)
@anchor{library/datetime datetime date min}@anchor{23ce}
@deffn {Attribut} date.min

La plus vieille date représentable, @code{date(MINYEAR, 1, 1)}.
@end deffn

@geindex max (attribut datetime.date)
@anchor{library/datetime datetime date max}@anchor{23cf}
@deffn {Attribut} date.max

La dernière date représentable, @code{date(MAXYEAR, 12, 31)}.
@end deffn

@geindex resolution (attribut datetime.date)
@anchor{library/datetime datetime date resolution}@anchor{23d0}
@deffn {Attribut} date.resolution

La plus petite différence possible entre deux objets dates non-égaux, @code{timedelta(days=1)}.
@end deffn

Attributs de l'instance (en lecture seule) :

@geindex year (attribut datetime.date)
@anchor{library/datetime datetime date year}@anchor{23b0}
@deffn {Attribut} date.year

Entre @ref{23ad,,MINYEAR} et @ref{23ae,,MAXYEAR} inclus.
@end deffn

@geindex month (attribut datetime.date)
@anchor{library/datetime datetime date month}@anchor{23b1}
@deffn {Attribut} date.month

Entre 1 et 12 inclus.
@end deffn

@geindex day (attribut datetime.date)
@anchor{library/datetime datetime date day}@anchor{23b2}
@deffn {Attribut} date.day

Entre 1 et le nombre de jours du mois donné de l'année donnée.
@end deffn

Opérations gérées :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@item

@code{date2 = date1 + timedelta}

@tab

@code{date2} will be @code{timedelta.days} days
after @code{date1}. (1)

@item

@code{date2 = date1 - timedelta}

@tab

Computes @code{date2} such that @code{date2 +
timedelta == date1}. (2)

@item

@code{timedelta = date1 - date2}

@tab

(3)

@item


@display
@code{date1 == date2}@w{ }
@code{date1 != date2}@w{ }
@end display



@tab

Equality comparison. (4)

@item


@display
@code{date1 < date2}@w{ }
@code{date1 > date2}@w{ }
@code{date1 <= date2}@w{ }
@code{date1 >= date2}@w{ }
@end display



@tab

Order comparison. (5)

@end multitable


Notes :


@enumerate 

@item 
@code{date2} est déplacée en avant dans le temps si @code{timedelta.days > 0}, ou en arrière si @code{timedelta.days < 0}. Après quoi @code{date2 - date1 == timedelta.days}. @code{timedelta.seconds} et @code{timedelta.microseconds} sont ignorés. Une @ref{86d,,OverflowError} est levée si @code{date2.year} devait être inférieure à @ref{23ad,,MINYEAR} ou supérieure à @ref{23ae,,MAXYEAR}.

@item 
@code{timedelta.seconds} et @code{timedelta.microseconds} sont ignorés.

@item 
This is exact, and cannot overflow. @code{timedelta.seconds} and
@code{timedelta.microseconds} are 0, and @code{date2 + timedelta == date1} after.

@item 
@ref{1c8,,date} objects are equal if they represent the same date.

@code{date} objects that are not also @ref{1c7,,datetime} instances
are never equal to @code{datetime} objects, even if they represent
the same date.

@item 
`date1' is considered less than `date2' when `date1' precedes `date2' in time.
In other words, @code{date1 < date2} if and only if @code{date1.toordinal() <
date2.toordinal()}.

Order comparison between a @code{date} object that is not also a
@ref{1c7,,datetime} instance and a @code{datetime} object raises
@ref{522,,TypeError}.
@end enumerate


Modifié dans la version 3.13: Comparison between @ref{1c7,,datetime} object and an instance of
the @ref{1c8,,date} subclass that is not a @code{datetime} subclass
no longer converts the latter to @code{date}, ignoring the time part
and the time zone.
The default behavior can be changed by overriding the special comparison
methods in subclasses.


Dans des contextes booléens, tous les objets @ref{1c8,,date} sont considérés comme vrai.

Méthodes de l'instance :

@geindex replace() (méthode datetime.date)
@anchor{library/datetime datetime date replace}@anchor{1606}
@deffn {Méthode} date.replace (year=self.year, month=self.month, day=self.day)

Renvoie une date avec la même valeur, à l'exception des paramètres nommés pour lesquels une nouvelle valeur est donnée en argument.

Exemple :

@example
>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)
@end example

@ref{1c8,,date} objects are also supported by generic function
@ref{150,,copy.replace()}.
@end deffn

@geindex timetuple() (méthode datetime.date)
@anchor{library/datetime datetime date timetuple}@anchor{23d1}
@deffn {Méthode} date.timetuple ()

Renvoie une @ref{cd8,,time.struct_time} telle que renvoyée par @ref{14af,,time.localtime()}.

Les heures, minutes et secondes sont égales à 0 et le drapeau DST vaut -1.

@code{d.timetuple()} est équivalent à :

@example
time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))
@end example

where @code{yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1}
is the day number within the current year starting with 1 for January 1st.
@end deffn

@geindex toordinal() (méthode datetime.date)
@anchor{library/datetime datetime date toordinal}@anchor{23d2}
@deffn {Méthode} date.toordinal ()

Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
has ordinal 1. For any @ref{1c8,,date} object @code{d},
@code{date.fromordinal(d.toordinal()) == d}.
@end deffn

@geindex weekday() (méthode datetime.date)
@anchor{library/datetime datetime date weekday}@anchor{23d3}
@deffn {Méthode} date.weekday ()

Renvoie le jour de la semaine sous forme de nombre, où lundi vaut 0 et dimanche vaut 6. Par exemple, @code{date(2002, 12, 4).weekday() == 2}, un mercredi. Voir aussi @ref{23d4,,isoweekday()}.
@end deffn

@geindex isoweekday() (méthode datetime.date)
@anchor{library/datetime datetime date isoweekday}@anchor{23d4}
@deffn {Méthode} date.isoweekday ()

Renvoie le jour de la semaine sous forme de nombre, où lundi vaut 1 et dimanche vaut 7. Par exemple, @code{date(2002, 12, 4).isoweekday() == 3}, un mercredi. Voir aussi @ref{23d3,,weekday()}, @ref{8e2,,isocalendar()}.
@end deffn

@geindex isocalendar() (méthode datetime.date)
@anchor{library/datetime datetime date isocalendar}@anchor{8e2}
@deffn {Méthode} date.isocalendar ()

Renvoie un objet @ref{639,,named tuple} avec trois composants : @code{year}, @code{week} et @code{weekday}.

Le calendrier ISO est une variante largement utilisée du calendrier grégorien. @footnote{
Voir R. H. van Gent @uref{https://web.archive.org/web/20220531051136/https://webspace.science.uu.nl/~gent0113/calendar/isocalendar.htm,guide des mathématiques du calendrier ISO 8601} pour une bonne explication.
}

Une année ISO est composée de 52 ou 53 semaines pleines, où chaque semaine débute un lundi et se termine un dimanche. La première semaine d'une année ISO est la première semaine calendaire (grégorienne) de l'année comportant un jeudi. Elle est appelée la semaine numéro 1, et l'année ISO de ce jeudi est la même que son année Grégorienne.

Par exemple, l'année 2004 débute un jeudi, donc la première semaine de l'année ISO 2004 débute le lundi 29 décembre 2003 et se termine le dimanche 4 janvier 2004 :

@example
>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
@end example


Modifié dans la version 3.9: Le résultat a changé d'un `n'-uplet à un @ref{639,,named tuple}.

@end deffn

@geindex isoformat() (méthode datetime.date)
@anchor{library/datetime datetime date isoformat}@anchor{23d5}
@deffn {Méthode} date.isoformat ()

Renvoie une chaîne représentant la date au format ISO 8601, @code{YYYY-MM-DD} :

@example
>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'
@end example
@end deffn

@geindex __str__() (méthode datetime.date)
@anchor{library/datetime datetime date __str__}@anchor{23d6}
@deffn {Méthode} date.__str__ ()

For a date @code{d}, @code{str(d)} is equivalent to @code{d.isoformat()}.
@end deffn

@geindex ctime() (méthode datetime.date)
@anchor{library/datetime datetime date ctime}@anchor{23d7}
@deffn {Méthode} date.ctime ()

Renvoie une chaîne représentant la date :

@example
>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'
@end example

@code{d.ctime()} est équivalent à :

@example
time.ctime(time.mktime(d.timetuple()))
@end example

sur les plateformes où la fonction C native @code{ctime()} (que @ref{23d8,,time.ctime()} invoque, mais pas @ref{23d7,,date.ctime()}) est conforme au standard C.
@end deffn

@geindex strftime() (méthode datetime.date)
@anchor{library/datetime datetime date strftime}@anchor{c7f}
@deffn {Méthode} date.strftime (format)

Renvoie une chaîne représentant la date, contrôlée par une chaîne de formatage explicite. Les codes de formatage se référant aux heures, minutes ou secondes auront pour valeur 0. Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{23d5,,date.isoformat()}.
@end deffn

@geindex __format__() (méthode datetime.date)
@anchor{library/datetime datetime date __format__}@anchor{23d9}
@deffn {Méthode} date.__format__ (format)

Identique à @ref{c7f,,date.strftime()}. Cela permet de spécifier une chaîne de formatage pour un objet @ref{1c8,,date} dans une @ref{997,,chaîne de formatage littérale} et à l'utilisation de @ref{60c,,str.format()}. Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{23d5,,date.isoformat()}.
@end deffn

@menu
* Exemple d'utilisation de la classe date ;: Exemple d'utilisation de la classe date. 

@end menu

@node Exemple d'utilisation de la classe date,,,Objets date
@anchor{library/datetime examples-of-usage-date}@anchor{23da}
@subsubsection Exemple d'utilisation de la classe @code{date} :


Exemple de décompte des jours avant un évènement :

@example
>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
...
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202
@end example

Plus d'exemples avec la classe @ref{1c8,,date} :

@example
>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The @{1@} is @{0:%d@}, the @{2@} is @{0:%B@}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:     
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:    
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)
@end example

@node Objets datetime,Objets time,Objets date,datetime — Types de base pour la date et l'heure
@anchor{library/datetime datetime-datetime}@anchor{23db}@anchor{library/datetime datetime-objects}@anchor{23dc}
@subsubsection Objets @code{datetime}


Un objet @ref{1c7,,datetime} est un seul et même objet contenant toute l'information d'un objet @ref{1c8,,date} et d'un objet @ref{1c9,,time}.

Comme un objet @ref{1c8,,date}, un objet @ref{1c7,,datetime} utilise le calendrier Grégorien actuel étendu vers le passé et le futur ; comme un objet @ref{1c9,,time}, un objet @ref{1c7,,datetime} suppose qu'il y a exactement 3600*24 secondes chaque jour.

Constructeur :

@geindex datetime (classe dans datetime)
@anchor{library/datetime datetime datetime}@anchor{1c7}
@deffn {Classe} datetime.datetime (year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Les arguments `year', `month' et `day' sont requis. `tzinfo' peut être @code{None} ou une instance d'une sous-classe de @ref{5c8,,tzinfo}. Les arguments restant doivent être des nombres, dans les intervalles suivants :


@itemize *

@item 
@code{MINYEAR <= year <= MAXYEAR},

@item 
@code{1 <= month <= 12},

@item 
@code{1 <= day <= nombre de jours dans le mois donné de l'année donnée},

@item 
@code{0 <= hour < 24},

@item 
@code{0 <= minute < 60},

@item 
@code{0 <= second < 60},

@item 
@code{0 <= microsecond < 1000000},

@item 
@code{fold in [0, 1]}.
@end itemize

Si un argument est donné en dehors de ces intervalles, une @ref{1ff,,ValueError} est levée.


Modifié dans la version 3.6: Added the `fold' parameter.

@end deffn

Autres constructeurs, méthodes de classe :

@geindex today() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime today}@anchor{23dd}
@deffn {Méthode} classmethod datetime.today ()

Return the current local date and time, with @ref{23bf,,tzinfo} @code{None}.

Équivalent à :

@example
datetime.fromtimestamp(time.time())
@end example

Voir aussi @ref{4d6,,now()}, @ref{4d7,,fromtimestamp()}.

Cette méthode est fonctionnellement équivalente à @ref{4d6,,now()}, mais sans le paramètre @code{tz}.
@end deffn

@geindex now() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime now}@anchor{4d6}
@deffn {Méthode} classmethod datetime.now (tz=None)

Renvoie la date et l'heure locale actuelle.

Si l'argument optionnel `tz' est @code{None} ou n'est pas spécifié, la méthode est similaire à @ref{23dd,,today()}, mais, si possible, apporte plus de précisions que ce qui peut être trouvé à travers un horodatage @ref{251,,time.time()} (par exemple, cela peut être possible sur des plateformes fournissant la fonction C @code{gettimeofday()}).

Si `tz' n'est pas @code{None}, il doit être une instance d'une sous-classe @ref{5c8,,tzinfo}, et la date et l'heure courantes sont converties vers le fuseau horaire `tz'.

Cette fonction est préférée à @ref{23dd,,today()} et @ref{2f0,,utcnow()}.

@cartouche
@quotation Note 
Subsequent calls to @code{datetime.now()} may return the same
instant depending on the precision of the underlying clock.
@end quotation
@end cartouche
@end deffn

@geindex utcnow() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime utcnow}@anchor{2f0}
@deffn {Méthode} classmethod datetime.utcnow ()

Renvoie la date et l'heure UTC actuelle, avec @ref{23bf,,tzinfo} @code{None}.

C'est semblable à @ref{4d6,,now()}, mais renvoie la date et l'heure UTC courantes, comme un objet @ref{1c7,,datetime} naïf. Un @code{datetime} UTC courant avisé peut être obtenu en appelant @code{datetime.now(timezone.utc)}. Voir aussi @ref{4d6,,now()}.

@cartouche
@quotation Avertissement 
Parce que les objets naïfs @code{datetime} sont traités par de nombreuses méthodes @code{datetime} comme des heures locales, il est préférable d'utiliser les dates connues pour représenter les heures en UTC. En tant que tel, le moyen recommandé pour créer un objet représentant l'heure actuelle en UTC est d'appeler @code{datetime.now(timezone.utc)}.
@end quotation
@end cartouche


Obsolète depuis la version 3.12: Use @ref{4d6,,datetime.now()} with @ref{4d8,,UTC} instead.

@end deffn

@geindex fromtimestamp() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime fromtimestamp}@anchor{4d7}
@deffn {Méthode} classmethod datetime.fromtimestamp (timestamp, tz=None)

Renvoie la date et l'heure locales correspondant à l'horodatage (`timestamp' en anglais) `POSIX', comme renvoyé par @ref{251,,time.time()}. Si l'argument optionnel `tz' est @code{None} ou n'est pas spécifié, l'horodatage est converti vers la date et l'heure locales de la plateforme, et l'objet @ref{1c7,,datetime} renvoyé est naïf.

Si `tz' n'est pas @code{None}, il doit être une instance d'une sous-classe @ref{5c8,,tzinfo}, et l'horodatage (`timestamp' en anglais) est converti vers le fuseau horaire `tz'.

@ref{4d7,,fromtimestamp()} peut lever une @ref{86d,,OverflowError}, si l'horodatage est en dehors de l'intervalle de valeurs gérées par les fonctions C @code{localtime()} ou @code{gmtime()} de la plateforme, et une @ref{40d,,OSError} en cas d'échec de @code{localtime()} ou @code{gmtime()}. Il est courant d'être restreint aux années de 1970 à 2038. Notez que sur les systèmes non `POSIX' qui incluent les secondes intercalaires dans leur notion d'horodatage, les secondes intercalaires sont ignorées par @ref{4d7,,fromtimestamp()}, et il est alors possible d'avoir deux horodatages différant d'une seconde produisant un objet @ref{1c7,,datetime} identique. Cette méthode est préférée à @ref{2f1,,utcfromtimestamp()}.


Modifié dans la version 3.3: Lève une @ref{86d,,OverflowError} plutôt qu'une @ref{1ff,,ValueError} si l'horodatage est en dehors de l'intervalle de valeurs gérées par les fonctions C @code{localtime()} ou @code{gmtime()} de la plateforme. Lève une @ref{40d,,OSError} plutôt qu'une @ref{1ff,,ValueError} en cas d'échec de @code{localtime()} ou @code{gmtime()}.



Modifié dans la version 3.6: @ref{4d7,,fromtimestamp()} peut renvoyer des instances avec l'attribut @ref{c45,,fold} à 1.

@end deffn

@geindex utcfromtimestamp() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime utcfromtimestamp}@anchor{2f1}
@deffn {Méthode} classmethod datetime.utcfromtimestamp (timestamp)

Renvoie la classe UTC @ref{1c7,,datetime} correspondant à l'horodatage POSIX, avec @ref{23bf,,tzinfo} @code{None} (l'objet résultant est naïf).

Cela peut lever une @ref{86d,,OverflowError}, si l'horodatage est en dehors de l'intervalle de valeurs gérées par la fonction C @code{gmtime()} de la plateforme, et une @ref{40d,,OSError} en cas d'échec de @code{gmtime()}. Il est courant d'être restreint aux années de 1970 à 2038.

Pour obtenir un objet @ref{1c7,,datetime} avisé, appelez @ref{4d7,,fromtimestamp()} :

@example
datetime.fromtimestamp(timestamp, timezone.utc)
@end example

Sur les plateformes respectant `POSIX', cela est équivalent à l'expression suivante :

@example
datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)
@end example

excepté que la dernière formule gère l'intervalle complet des années entre @ref{23ad,,MINYEAR} et @ref{23ae,,MAXYEAR} incluses.

@cartouche
@quotation Avertissement 
Parce que les objets naïfs @code{datetime} sont traités par de nombreuses méthodes @code{datetime} comme des heures locales, il est préférable d'utiliser les dates connues pour représenter les heures en UTC. En tant que tel, le moyen recommandé pour créer un objet représentant un horodatage spécifique en UTC est d'appeler @code{datetime.fromtimestamp(timestamp, tz=timezone.utc)}.
@end quotation
@end cartouche


Modifié dans la version 3.3: Lève une @ref{86d,,OverflowError} plutôt qu'une @ref{1ff,,ValueError} si l'horodatage est en dehors de l'intervalle de valeurs gérées par la fonction C @code{gmtime()} de la plateforme. Lève une @ref{40d,,OSError} plutôt qu'une @ref{1ff,,ValueError} en cas d'échec de @code{gmtime()}.



Obsolète depuis la version 3.12: Use @ref{4d7,,datetime.fromtimestamp()} with @ref{4d8,,UTC} instead.

@end deffn

@geindex fromordinal() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime fromordinal}@anchor{23de}
@deffn {Méthode} classmethod datetime.fromordinal (ordinal)

Renvoie le @ref{1c7,,datetime} correspondant à l'ordinal du calendrier grégorien proleptique, où le 1er janvier de l'an 1 a l'ordinal 1. Une @ref{1ff,,ValueError} est levée à moins que @code{1 <= ordinal <= datetime.max.toordinal()}. Les heures, minutes, secondes et microsecondes du résultat valent toutes 0, et @ref{23bf,,tzinfo} est @code{None}.
@end deffn

@geindex combine() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime combine}@anchor{c80}
@deffn {Méthode} classmethod datetime.combine (date, time, tzinfo=time.tzinfo)

Return a new @ref{1c7,,datetime} object whose date components are equal to the
given @ref{1c8,,date} object's, and whose time components
are equal to the given @ref{1c9,,time} object's. If the `tzinfo'
argument is provided, its value is used to set the @ref{23bf,,tzinfo} attribute
of the result, otherwise the @ref{23b7,,tzinfo} attribute of the `time' argument
is used.  If the `date' argument is a @ref{1c7,,datetime} object, its time components
and @ref{23bf,,tzinfo} attributes are ignored.

For any @ref{1c7,,datetime} object @code{d},
@code{d == datetime.combine(d.date(), d.time(), d.tzinfo)}.


Modifié dans la version 3.6: Ajout de l'argument `tzinfo'.

@end deffn

@geindex fromisoformat() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime fromisoformat}@anchor{602}
@deffn {Méthode} classmethod datetime.fromisoformat (date_string)

Renvoie une classe @ref{1c7,,datetime} correspondant à `date_string' dans un format ISO 8601 valide, avec les exceptions suivantes :


@enumerate 

@item 
Les décalages de fuseaux horaires peuvent comporter des fractions de secondes.

@item 
Le séparateur @code{T} peut être remplacé par n'importe quel caractère Unicode.

@item 
Les fractions d'heures et de minutes ne sont pas gérées.

@item 
Les dates à précision réduite ne sont actuellement pas gérées (@code{YYYY-MM}, @code{YYYY}).

@item 
Extended date representations are not currently supported
(@code{±YYYYYY-MM-DD}).

@item 
Ordinal dates are not currently supported (@code{YYYY-OOO}).
@end enumerate

Exemples :

@example
>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')   
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
@end example


Ajouté dans la version 3.7.



Modifié dans la version 3.11: Previously, this method only supported formats that could be emitted by
@ref{23d5,,date.isoformat()} or @ref{b1e,,datetime.isoformat()}.

@end deffn

@geindex fromisocalendar() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime fromisocalendar}@anchor{9db}
@deffn {Méthode} classmethod datetime.fromisocalendar (year, week, day)

Renvoie une classe @ref{1c7,,datetime} correspondant à la date du calendrier ISO spécifiée par année, semaine et jour. Les composantes ne relevant pas de la date de `datetime' sont renseignées avec leurs valeurs par défaut normales. C'est la réciproque de la fonction @ref{8e3,,datetime.isocalendar()}.


Ajouté dans la version 3.8.

@end deffn

@geindex strptime() (méthode de la classe datetime.datetime)
@anchor{library/datetime datetime datetime strptime}@anchor{1593}
@deffn {Méthode} classmethod datetime.strptime (date_string, format)

Renvoie une classe @ref{1c7,,datetime} correspondant à `date_string', analysée selon `format'.

If `format' does not contain microseconds or time zone information, this is equivalent to:

@example
datetime(*(time.strptime(date_string, format)[0:6]))
@end example

Une @ref{1ff,,ValueError} est levée si `date_string' et `format' ne peuvent être analysés par @ref{13e3,,time.strptime()} ou si elle renvoie une valeur qui n'est pas un `n'-uplet de temps.  Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{602,,datetime.fromisoformat()}.


Modifié dans la version 3.13: If `format' specifies a day of month without a year a
@ref{1a3,,DeprecationWarning} is now emitted.  This is to avoid a quadrennial
leap year bug in code seeking to parse only a month and day as the
default year used in absence of one in the format is not a leap year.
Such `format' values may raise an error as of Python 3.15.  The
workaround is to always include a year in your `format'.  If parsing
`date_string' values that do not have a year, explicitly add a year that
is a leap year before parsing:

@example
>>> from datetime import datetime
>>> date_string = "02/29"
>>> when = datetime.strptime(f"@{date_string@};1984", "%m/%d;%Y")  # Avoids leap year bug.
>>> when.strftime("%B %d")  
'February 29'
@end example

@end deffn

Attributs de la classe :

@geindex min (attribut datetime.datetime)
@anchor{library/datetime datetime datetime min}@anchor{1769}
@deffn {Attribut} datetime.min

Le plus ancien @ref{1c7,,datetime} représentable, @code{datetime(MINYEAR, 1, 1, tzinfo=None)}.
@end deffn

@geindex max (attribut datetime.datetime)
@anchor{library/datetime datetime datetime max}@anchor{23df}
@deffn {Attribut} datetime.max

Le dernier @ref{1c7,,datetime} représentable, @code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}.
@end deffn

@geindex resolution (attribut datetime.datetime)
@anchor{library/datetime datetime datetime resolution}@anchor{23e0}
@deffn {Attribut} datetime.resolution

La plus petite différence possible entre deux objets @ref{1c7,,datetime} non-égaux, @code{timedelta(microseconds=1)}.
@end deffn

Attributs de l'instance (en lecture seule) :

@geindex year (attribut datetime.datetime)
@anchor{library/datetime datetime datetime year}@anchor{23b8}
@deffn {Attribut} datetime.year

Entre @ref{23ad,,MINYEAR} et @ref{23ae,,MAXYEAR} inclus.
@end deffn

@geindex month (attribut datetime.datetime)
@anchor{library/datetime datetime datetime month}@anchor{23b9}
@deffn {Attribut} datetime.month

Entre 1 et 12 inclus.
@end deffn

@geindex day (attribut datetime.datetime)
@anchor{library/datetime datetime datetime day}@anchor{23ba}
@deffn {Attribut} datetime.day

Entre 1 et le nombre de jours du mois donné de l'année donnée.
@end deffn

@geindex hour (attribut datetime.datetime)
@anchor{library/datetime datetime datetime hour}@anchor{23bb}
@deffn {Attribut} datetime.hour

Dans @code{range(24)}.
@end deffn

@geindex minute (attribut datetime.datetime)
@anchor{library/datetime datetime datetime minute}@anchor{23bc}
@deffn {Attribut} datetime.minute

Dans @code{range(60)}.
@end deffn

@geindex second (attribut datetime.datetime)
@anchor{library/datetime datetime datetime second}@anchor{23bd}
@deffn {Attribut} datetime.second

Dans @code{range(60)}.
@end deffn

@geindex microsecond (attribut datetime.datetime)
@anchor{library/datetime datetime datetime microsecond}@anchor{23be}
@deffn {Attribut} datetime.microsecond

Dans @code{range(1000000)}.
@end deffn

@geindex tzinfo (attribut datetime.datetime)
@anchor{library/datetime datetime datetime tzinfo}@anchor{23bf}
@deffn {Attribut} datetime.tzinfo

L'objet passé en tant que paramètre `tzinfo' du constructeur de la classe @ref{1c7,,datetime} ou @code{None} si aucun n'a été donné.
@end deffn

@geindex fold (attribut datetime.datetime)
@anchor{library/datetime datetime datetime fold}@anchor{c45}
@deffn {Attribut} datetime.fold

In @code{[0, 1]}. Used to disambiguate wall times during a repeated interval. (A
repeated interval occurs when clocks are rolled back at the end of daylight saving
time or when the UTC offset for the current zone is decreased for political reasons.)
The values 0 and 1 represent, respectively, the earlier and later of the two
moments with the same wall time representation.


Ajouté dans la version 3.6.

@end deffn

Opérations gérées :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Résultat

@item

@code{datetime2 = datetime1 + timedelta}

@tab

(1)

@item

@code{datetime2 = datetime1 - timedelta}

@tab

(2)

@item

@code{timedelta = datetime1 - datetime2}

@tab

(3)

@item


@display
@code{datetime1 == datetime2}@w{ }
@code{datetime1 != datetime2}@w{ }
@end display



@tab

Equality comparison. (4)

@item


@display
@code{datetime1 < datetime2}@w{ }
@code{datetime1 > datetime2}@w{ }
@code{datetime1 <= datetime2}@w{ }
@code{datetime1 >= datetime2}@w{ }
@end display



@tab

Order comparison. (5)

@end multitable



@enumerate 

@item 
@code{datetime2} is a duration of @code{timedelta} removed from @code{datetime1}, moving forward in
time if @code{timedelta.days > 0}, or backward if @code{timedelta.days < 0}. The
result has the same @ref{23bf,,tzinfo} attribute as the input datetime, and
@code{datetime2 - datetime1 == timedelta} after. @ref{86d,,OverflowError} is raised if
@code{datetime2.year} would be smaller than @ref{23ad,,MINYEAR} or larger than
@ref{23ae,,MAXYEAR}. Note that no time zone adjustments are done even if the
input is an aware object.

@item 
Computes the @code{datetime2} such that @code{datetime2 + timedelta == datetime1}. As for
addition, the result has the same @ref{23bf,,tzinfo} attribute as the input
datetime, and no time zone adjustments are done even if the input is aware.

@item 
La soustraction d'un @ref{1c7,,datetime} à un autre @ref{1c7,,datetime} n'est définie que si les deux opérandes sont naïfs, ou s'ils sont les deux avisés.  Si l'un est avisé et que l'autre est naïf, une @ref{522,,TypeError} est levée.

If both are naive, or both are aware and have the same @ref{23bf,,tzinfo} attribute,
the @ref{23bf,,tzinfo} attributes are ignored, and the result is a @ref{9bd,,timedelta}
object @code{t} such that @code{datetime2 + t == datetime1}. No time zone adjustments
are done in this case.

If both are aware and have different @ref{23bf,,tzinfo} attributes, @code{a-b} acts
as if @code{a} and @code{b} were first converted to naive UTC datetimes. The
result is @code{(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
- b.utcoffset())} except that the implementation never overflows.

@item 
@ref{1c7,,datetime} objects are equal if they represent the same date
and time, taking into account the time zone.

Naive and aware @code{datetime} objects are never equal.

If both comparands are aware, and have the same @code{tzinfo} attribute,
the @code{tzinfo} and @ref{c45,,fold} attributes are ignored and
the base datetimes are compared.
If both comparands are aware and have different @ref{23bf,,tzinfo}
attributes, the comparison acts as comparands were first converted to UTC
datetimes except that the implementation never overflows.
@code{datetime} instances in a repeated interval are never equal to
@code{datetime} instances in other time zone.

@item 
`datetime1' is considered less than `datetime2' when `datetime1' precedes
`datetime2' in time, taking into account the time zone.

Order comparison between naive and aware @ref{1c7,,datetime} objects
raises @ref{522,,TypeError}.

If both comparands are aware, and have the same @code{tzinfo} attribute,
the @code{tzinfo} and @ref{c45,,fold} attributes are ignored and
the base datetimes are compared.
If both comparands are aware and have different @ref{23bf,,tzinfo}
attributes, the comparison acts as comparands were first converted to UTC
datetimes except that the implementation never overflows.
@end enumerate


Modifié dans la version 3.3: Les comparaisons d'égalité entre des instances @ref{1c7,,datetime} naïves et avisées ne lèvent pas d'exception @ref{522,,TypeError}.



Modifié dans la version 3.13: Comparison between @ref{1c7,,datetime} object and an instance of
the @ref{1c8,,date} subclass that is not a @code{datetime} subclass
no longer converts the latter to @code{date}, ignoring the time part
and the time zone.
The default behavior can be changed by overriding the special comparison
methods in subclasses.


Méthodes de l'instance :

@geindex date() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime date}@anchor{23e1}
@deffn {Méthode} datetime.date ()

Renvoie un objet @ref{1c8,,date} avec les mêmes année, mois et jour.
@end deffn

@geindex time() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime time}@anchor{23e2}
@deffn {Méthode} datetime.time ()

Renvoie un objet @ref{1c9,,time} avec les mêmes heures, minutes, secondes, microsecondes et `fold'. @ref{23bf,,tzinfo} est @code{None}.  Voir aussi la méthode @ref{23e3,,timetz()}.


Modifié dans la version 3.6: La valeur `fold' est copiée vers l'objet @ref{1c9,,time} renvoyé.

@end deffn

@geindex timetz() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime timetz}@anchor{23e3}
@deffn {Méthode} datetime.timetz ()

Renvoie un objet @ref{1c9,,time} avec les mêmes attributs heure, minute, seconde, microseconde, `fold' et `tzinfo'.  Voir aussi la méthode @ref{ed,,time()}.


Modifié dans la version 3.6: La valeur `fold' est copiée vers l'objet @ref{1c9,,time} renvoyé.

@end deffn

@geindex replace() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime replace}@anchor{1481}
@deffn {Méthode} datetime.replace (year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Renvoie un `datetime' avec les mêmes attributs, exceptés ceux dont de nouvelles valeurs sont données par les arguments nommés correspondant.  Notez que @code{tzinfo=None} peut être spécifié pour créer un `datetime' naïf depuis un `datetime' avisé sans conversion de la date ou de l'heure.

@ref{1c7,,datetime} objects are also supported by generic function
@ref{150,,copy.replace()}.


Modifié dans la version 3.6: Added the `fold' parameter.

@end deffn

@geindex astimezone() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime astimezone}@anchor{9be}
@deffn {Méthode} datetime.astimezone (tz=None)

Renvoie un objet @ref{1c7,,datetime} avec un nouvel attribut @ref{23bf,,tzinfo} valant `tz', ajustant la date et l'heure pour que le résultat soit le même temps UTC que `self', mais dans le temps local au fuseau `tz'.

If provided, `tz' must be an instance of a @ref{5c8,,tzinfo} subclass, and its
@ref{23e4,,utcoffset()} and @ref{23e5,,dst()} methods must not return @code{None}. If `self'
is naive, it is presumed to represent time in the system time zone.

If called without arguments (or with @code{tz=None}) the system local
time zone is assumed for the target time zone. The @code{.tzinfo} attribute of the converted
datetime instance will be set to an instance of @ref{10a1,,timezone}
with the zone name and offset obtained from the OS.

If @code{self.tzinfo} is `tz', @code{self.astimezone(tz)} is equal to `self':  no
adjustment of date or time data is performed. Else the result is local
time in the time zone `tz', representing the same UTC time as `self':  after
@code{astz = dt.astimezone(tz)}, @code{astz - astz.utcoffset()} will have
the same date and time data as @code{dt - dt.utcoffset()}.

If you merely want to attach a @ref{10a1,,timezone} object `tz' to a datetime `dt' without
adjustment of date and time data, use @code{dt.replace(tzinfo=tz)}. If you
merely want to remove the @code{timezone} object from an aware datetime `dt' without
conversion of date and time data, use @code{dt.replace(tzinfo=None)}.

Notez que la méthode par défaut @ref{23e6,,tzinfo.fromutc()} peut être redéfinie dans une sous-classe @ref{5c8,,tzinfo} pour affecter le résultat renvoyé par @ref{9be,,astimezone()}. En ignorant les cas d'erreurs, @ref{9be,,astimezone()} se comporte comme :

@example
def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new timezone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)
@end example


Modifié dans la version 3.3: `tz' peut maintenant être omis.



Modifié dans la version 3.6: La méthode @ref{9be,,astimezone()} peut maintenant être appelée sur des instances naïves qui sont supposées représenter un temps local au système.

@end deffn

@geindex utcoffset() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime utcoffset}@anchor{23e4}
@deffn {Méthode} datetime.utcoffset ()

Si @ref{23bf,,tzinfo} est @code{None}, renvoie @code{None}, sinon renvoie @code{self.tzinfo.utcoffset(self)}, et lève une exception si l'expression précédente ne renvoie pas @code{None} ou un objet @ref{9bd,,timedelta} d'une magnitude inférieure à un jour.


Modifié dans la version 3.7: Le décalage UTC peut aussi être autre chose qu'un ensemble de minutes.

@end deffn

@geindex dst() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime dst}@anchor{23e5}
@deffn {Méthode} datetime.dst ()

Si @ref{23bf,,tzinfo} est @code{None}, renvoie @code{None}, sinon renvoie @code{self.tzinfo.dst(self)}, et lève une exception si l'expression précédente ne renvoie pas @code{None} ou un objet @ref{9bd,,timedelta} d'une magnitude inférieure à un jour.


Modifié dans la version 3.7: Le décalage DST n'est pas restreint à des minutes entières.

@end deffn

@geindex tzname() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime tzname}@anchor{23e7}
@deffn {Méthode} datetime.tzname ()

Si @ref{23bf,,tzinfo} est @code{None}, renvoie @code{None}, sinon renvoie @code{self.tzinfo.tzname(self)}, lève une exception si l'expression précédente ne renvoie pas @code{None} ou une chaîne de caractères,
@end deffn

@geindex timetuple() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime timetuple}@anchor{23e8}
@deffn {Méthode} datetime.timetuple ()

Renvoie une @ref{cd8,,time.struct_time} telle que renvoyée par @ref{14af,,time.localtime()}.

@code{d.timetuple()} est équivalent à :

@example
time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))
@end example

where @code{yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1}
is the day number within the current year starting with 1 for January
1st. The @ref{23e9,,tm_isdst} flag of the result is set according to the
@ref{23e5,,dst()} method: @ref{23bf,,tzinfo} is @code{None} or @ref{23e5,,dst()} returns
@code{None}, @code{tm_isdst} is set to @code{-1}; else if @ref{23e5,,dst()} returns a
non-zero value, @code{tm_isdst} is set to 1; else @code{tm_isdst} is
set to 0.
@end deffn

@geindex utctimetuple() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime utctimetuple}@anchor{23ea}
@deffn {Méthode} datetime.utctimetuple ()

If @ref{1c7,,datetime} instance @code{d} is naive, this is the same as
@code{d.timetuple()} except that @ref{23e9,,tm_isdst} is forced to 0 regardless of what
@code{d.dst()} returns. DST is never in effect for a UTC time.

If @code{d} is aware, @code{d} is normalized to UTC time, by subtracting
@code{d.utcoffset()}, and a @ref{cd8,,time.struct_time} for the
normalized time is returned. @code{tm_isdst} is forced to 0. Note
that an @ref{86d,,OverflowError} may be raised if @code{d.year} was
@code{MINYEAR} or @code{MAXYEAR} and UTC adjustment spills over a year
boundary.

@cartouche
@quotation Avertissement 
Comme les objets @code{datetime} naïfs sont traités par de nombreuses méthodes @code{datetime} comme des heures locales, il est préférable d'utiliser les @code{datetime} avisés pour représenter les heures en UTC ; par conséquent, l'utilisation de @code{datetime.utcfromtimetuple()} peut donner des résultats trompeurs. Si vous disposez d'une @code{datetime} naïve représentant l'heure UTC, utilisez @code{datetime.replace(tzinfo=timezone.utc)} pour la rendre avisée, puis vous pouvez utiliser @ref{23e8,,datetime.timetuple()}.
@end quotation
@end cartouche
@end deffn

@geindex toordinal() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime toordinal}@anchor{23eb}
@deffn {Méthode} datetime.toordinal ()

Renvoie l'ordinal du calendrier grégorien proleptique de cette date.  Identique à @code{self.date().toordinal()}.
@end deffn

@geindex timestamp() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime timestamp}@anchor{1083}
@deffn {Méthode} datetime.timestamp ()

Renvoie l'horodatage `POSIX' correspondant à l'instance @ref{1c7,,datetime}.  La valeur renvoyée est un @ref{2eb,,float} similaire à ceux renvoyés par @ref{251,,time.time()}.

Naive @ref{1c7,,datetime} instances are assumed to represent local
time and this method relies on the platform C @code{mktime()}
function to perform the conversion. Since @ref{1c7,,datetime}
supports wider range of values than @code{mktime()} on many
platforms, this method may raise @ref{86d,,OverflowError} or @ref{40d,,OSError}
for times far in the past or far in the future.

Pour les instances @ref{1c7,,datetime} avisées, la valeur renvoyée est calculée comme suit :

@example
(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
@end example


Ajouté dans la version 3.3.



Modifié dans la version 3.6: La méthode @ref{1083,,timestamp()} utilise l'attribut @ref{c45,,fold} pour désambiguïser le temps dans un intervalle répété.


@cartouche
@quotation Note 
There is no method to obtain the POSIX timestamp directly from a
naive @ref{1c7,,datetime} instance representing UTC time. If your
application uses this convention and your system time zone is not
set to UTC, you can obtain the POSIX timestamp by supplying
@code{tzinfo=timezone.utc}:

@example
timestamp = dt.replace(tzinfo=timezone.utc).timestamp()
@end example

ou en calculant l'horodatage (`timestamp' en anglais) directement :

@example
timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
@end example
@end quotation
@end cartouche
@end deffn

@geindex weekday() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime weekday}@anchor{23ec}
@deffn {Méthode} datetime.weekday ()

Renvoie le jour de la semaine sous forme de nombre, où lundi vaut 0 et dimanche vaut 6. Identique à @code{self.date().weekday()}. Voir aussi @ref{23ed,,isoweekday()}.
@end deffn

@geindex isoweekday() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime isoweekday}@anchor{23ed}
@deffn {Méthode} datetime.isoweekday ()

Renvoie le jour de la semaine sous forme de nombre, où lundi vaut 1 et dimanche vaut 7. Identique à @code{self.date().isoweekday()}. Voir aussi @ref{23ec,,weekday()}, @ref{8e3,,isocalendar()}.
@end deffn

@geindex isocalendar() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime isocalendar}@anchor{8e3}
@deffn {Méthode} datetime.isocalendar ()

Renvoie un @ref{639,,n-uplet nommé} de 3 éléments : @code{year}, @code{week} et @code{weekday}. Identique à @code{self.date().isocalendar()}.
@end deffn

@geindex isoformat() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime isoformat}@anchor{b1e}
@deffn {Méthode} datetime.isoformat (sep='T', timespec='auto')

Renvoie une chaîne représentant la date et l'heure au format ISO 8601 :


@itemize -

@item 
@code{YYYY-MM-DDTHH:MM:SS.ffffff}, si @ref{23be,,microsecond} ne vaut pas 0

@item 
@code{YYYY-MM-DDTHH:MM:SS}, si @ref{23be,,microsecond} vaut 0
@end itemize

Si @ref{23e4,,utcoffset()} ne renvoie pas @code{None}, une chaîne est ajoutée, donnant le décalage UTC :


@itemize -

@item 
@code{YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]}, si @ref{23be,,microsecond} ne vaut pas 0

@item 
@code{YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]},  si @ref{23be,,microsecond} vaut 0
@end itemize

Exemples :

@example
>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'
@end example

L'argument optionnel `sep' (par défaut @code{'T'}) est un séparateur d'un caractère, placé entre les portions du résultat correspondant à la date et à l'heure. Par exemple :

@example
>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'
@end example

L'argument optionnel `timespec' spécifie le nombre de composants additionnels de temps à inclure (par défaut @code{'auto'}). Il peut valoir l'une des valeurs suivantes :


@itemize -

@item 
@code{'auto'} : Identique à @code{'seconds'} si @ref{23be,,microsecond} vaut 0, à @code{'microseconds'} sinon.

@item 
@code{'hours'} : Inclut @ref{23bb,,hour} au format à deux chiffres @code{HH}.

@item 
@code{'minutes'} : Inclut @ref{23bb,,hour} et @ref{23bc,,minute} au format @code{HH:MM}.

@item 
@code{'seconds'} : Inclut @ref{23bb,,hour}, @ref{23bc,,minute} et @ref{23bd,,second} au format @code{HH:MM:SS}.

@item 
@code{'milliseconds'} : Inclut le temps complet, mais tronque la partie fractionnaire des millisecondes, au format @code{HH:MM:SS.sss}.

@item 
@code{'microseconds'} : Inclut le temps complet, au format @code{HH:MM:SS.ffffff}.
@end itemize

@cartouche
@quotation Note 
Les composants de temps exclus sont tronqués et non arrondis.
@end quotation
@end cartouche

Une @ref{1ff,,ValueError} est levée en cas d'argument `timespec' invalide :

@example
>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')   
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'
@end example


Modifié dans la version 3.6: Added the `timespec' parameter.

@end deffn

@geindex __str__() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime __str__}@anchor{23ee}
@deffn {Méthode} datetime.__str__ ()

For a @ref{1c7,,datetime} instance @code{d}, @code{str(d)} is equivalent to
@code{d.isoformat(' ')}.
@end deffn

@geindex ctime() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime ctime}@anchor{23ef}
@deffn {Méthode} datetime.ctime ()

Renvoie une chaîne représentant la date et l'heure :

@example
>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'
@end example

La chaîne de caractères en sortie n'inclura `pas' d'informations sur le fuseau horaire, que l'entrée soit avisée ou naïve.

@code{d.ctime()} est équivalent à :

@example
time.ctime(time.mktime(d.timetuple()))
@end example

sur les plateformes où la fonction C native @code{ctime()} (que @ref{23d8,,time.ctime()} invoque, mais pas @ref{23ef,,datetime.ctime()}) est conforme au standard C.
@end deffn

@geindex strftime() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime strftime}@anchor{c7e}
@deffn {Méthode} datetime.strftime (format)

Renvoie une chaîne représentant la date et l'heure, contrôlée par une chaîne de format explicite.  Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{b1e,,datetime.isoformat()}.
@end deffn

@geindex __format__() (méthode datetime.datetime)
@anchor{library/datetime datetime datetime __format__}@anchor{23f0}
@deffn {Méthode} datetime.__format__ (format)

Identique à @ref{c7e,,datetime.strftime()}.  Cela permet de spécifier une chaîne de format pour un objet @ref{1c7,,datetime} dans une @ref{997,,chaîne de formatage littérale} et en utilisant @ref{60c,,str.format()}.  Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{b1e,,datetime.isoformat()}.
@end deffn

@menu
* Exemple d'utilisation de la classe datetime ;: Exemple d'utilisation de la classe datetime. 

@end menu

@node Exemple d'utilisation de la classe datetime,,,Objets datetime
@anchor{library/datetime examples-of-usage-datetime}@anchor{23f1}
@subsubsection Exemple d'utilisation de la classe @code{datetime} :


Examples of working with @ref{1c7,,datetime} objects:

@example
>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()   
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)   
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:   
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:   
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The @{1@} is @{0:%d@}, the @{2@} is @{0:%B@}, the @{3@} is @{0:%I:%M%p@}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
@end example

L'exemple ci-dessous définit une sous-classe @ref{5c8,,tzinfo} qui regroupe des informations sur les fuseaux horaires pour Kaboul, en Afghanistan, qui a utilisé +4 UTC jusqu'en 1945, puis +4:30 UTC par la suite :

@example
from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"
@end example

Utilisation de @code{KabulTz} cité plus haut :

@example
>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True
@end example

@node Objets time,Objets tzinfo,Objets datetime,datetime — Types de base pour la date et l'heure
@anchor{library/datetime datetime-time}@anchor{23f2}@anchor{library/datetime time-objects}@anchor{23f3}
@subsubsection Objets @code{time}


A @ref{1c9,,time} object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a @ref{5c8,,tzinfo} object.

@geindex time (classe dans datetime)
@anchor{library/datetime datetime time}@anchor{1c9}
@deffn {Classe} datetime.time (hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Tous les arguments sont optionnels. `tzinfo' peut être @code{None} ou une instance d'une sous-classe @ref{5c8,,tzinfo}.  Les autres arguments doivent être des nombres entiers, dans les intervalles suivants :


@itemize *

@item 
@code{0 <= hour < 24},

@item 
@code{0 <= minute < 60},

@item 
@code{0 <= second < 60},

@item 
@code{0 <= microsecond < 1000000},

@item 
@code{fold in [0, 1]}.
@end itemize

If an argument outside those ranges is given, @ref{1ff,,ValueError} is raised. All
default to 0 except `tzinfo', which defaults to @code{None}.
@end deffn

Attributs de la classe :

@geindex min (attribut datetime.time)
@anchor{library/datetime datetime time min}@anchor{23f4}
@deffn {Attribut} time.min

Le plus petit objet @ref{1c9,,time} représentable, @code{time(0, 0, 0, 0)}.
@end deffn

@geindex max (attribut datetime.time)
@anchor{library/datetime datetime time max}@anchor{23f5}
@deffn {Attribut} time.max

Le plus grand objet @ref{1c9,,time} représentable, @code{time(23, 59, 59, 999999)}.
@end deffn

@geindex resolution (attribut datetime.time)
@anchor{library/datetime datetime time resolution}@anchor{23f6}
@deffn {Attribut} time.resolution

La plus petite différence possible entre deux objets @ref{1c9,,time} non-égaux, @code{timedelta(microseconds=1)}, notez cependant que les objets @ref{1c9,,time} n'implémentent pas d'opérations arithmétiques.
@end deffn

Attributs de l'instance (en lecture seule) :

@geindex hour (attribut datetime.time)
@anchor{library/datetime datetime time hour}@anchor{23b3}
@deffn {Attribut} time.hour

Dans @code{range(24)}.
@end deffn

@geindex minute (attribut datetime.time)
@anchor{library/datetime datetime time minute}@anchor{23b4}
@deffn {Attribut} time.minute

Dans @code{range(60)}.
@end deffn

@geindex second (attribut datetime.time)
@anchor{library/datetime datetime time second}@anchor{23b5}
@deffn {Attribut} time.second

Dans @code{range(60)}.
@end deffn

@geindex microsecond (attribut datetime.time)
@anchor{library/datetime datetime time microsecond}@anchor{23b6}
@deffn {Attribut} time.microsecond

Dans @code{range(1000000)}.
@end deffn

@geindex tzinfo (attribut datetime.time)
@anchor{library/datetime datetime time tzinfo}@anchor{23b7}
@deffn {Attribut} time.tzinfo

L'objet passé comme argument `tzinfo' au constructeur de @ref{1c9,,time}, ou @code{None} si aucune valeur n'a été passée.
@end deffn

@geindex fold (attribut datetime.time)
@anchor{library/datetime datetime time fold}@anchor{23f7}
@deffn {Attribut} time.fold

In @code{[0, 1]}. Used to disambiguate wall times during a repeated interval. (A
repeated interval occurs when clocks are rolled back at the end of daylight saving
time or when the UTC offset for the current zone is decreased for political reasons.)
The values 0 and 1 represent, respectively, the earlier and later of the two
moments with the same wall time representation.


Ajouté dans la version 3.6.

@end deffn

@ref{1c9,,time} objects support equality and order comparisons,
where @code{a} is considered less than @code{b} when @code{a} precedes @code{b} in time.

Naive and aware @code{time} objects are never equal.
Order comparison between naive and aware @code{time} objects raises
@ref{522,,TypeError}.

If both comparands are aware, and have the same @ref{23b7,,tzinfo}
attribute, the @code{tzinfo} and @code{fold} attributes are
ignored and the base times are compared. If both comparands are aware and
have different @code{tzinfo} attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from @code{self.utcoffset()}).


Modifié dans la version 3.3: Equality comparisons between aware and naive @ref{1c9,,time} instances
don't raise @ref{522,,TypeError}.


Dans un contexte booléen, un objet @ref{1c9,,time} est toujours considéré comme vrai.


Modifié dans la version 3.5: Avant Python 3.5, un objet @ref{1c9,,time} était considéré comme faux s'il représentait minuit en UTC.  Ce comportement était considéré comme obscur et propice aux erreurs, il a été supprimé en Python 3.5.  Voir bpo-13936@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=13936} pour les détails complets.


Autre constructeur :

@geindex fromisoformat() (méthode de la classe datetime.time)
@anchor{library/datetime datetime time fromisoformat}@anchor{601}
@deffn {Méthode} classmethod time.fromisoformat (time_string)

Renvoie une @ref{1c9,,time} correspondant à `time_string' dans un format ISO 8601 valide, avec les exceptions suivantes :


@enumerate 

@item 
Les décalages de fuseaux horaires peuvent comporter des fractions de secondes.

@item 
Le @code{T} initial, normalement requis dans les cas où il peut y avoir une ambiguïté entre une date et une heure, n'est pas nécessaire.

@item 
Les fractions de secondes peuvent avoir un nombre quelconque de décimales (tout ce qui dépasse 6 décimales sera tronqué).

@item 
Les fractions d'heures et de minutes ne sont pas gérées.
@end enumerate

Examples:

@example
>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
@end example


Ajouté dans la version 3.7.



Modifié dans la version 3.11: Previously, this method only supported formats that could be emitted by
@ref{23f8,,time.isoformat()}.

@end deffn

Méthodes de l'instance :

@geindex replace() (méthode datetime.time)
@anchor{library/datetime datetime time replace}@anchor{1607}
@deffn {Méthode} time.replace (hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Renvoie un objet @ref{1c9,,time} avec la même valeur, à l'exception des attributs dont les nouvelles valeurs sont spécifiées par les arguments nommés.  Notez que @code{tzinfo=None} peut être spécifié pour créer une instance @ref{1c9,,time} naïve à partir d'une instance @ref{1c9,,time} avisée, sans conversion des données de temps.

@ref{1c9,,time} objects are also supported by generic function
@ref{150,,copy.replace()}.


Modifié dans la version 3.6: Added the `fold' parameter.

@end deffn

@geindex isoformat() (méthode datetime.time)
@anchor{library/datetime datetime time isoformat}@anchor{23f8}
@deffn {Méthode} time.isoformat (timespec='auto')

Renvoie une chaîne représentant la date au format ISO 8601 :


@itemize -

@item 
@code{HH:MM:SS.ffffff}, si @ref{23b6,,microsecond} ne vaut pas 0

@item 
@code{HH:MM:SS}, si @ref{23b6,,microsecond} vaut 0

@item 
@code{HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]}, si @ref{23f9,,utcoffset()} ne renvoie pas @code{None}

@item 
@code{HH:MM:SS+HH:MM[:SS[.ffffff]]}, si @ref{23b6,,microsecond} vaut 0 et @ref{23f9,,utcoffset()} ne renvoie pas @code{None}
@end itemize

L'argument optionnel `timespec' spécifie le nombre de composants additionnels de temps à inclure (par défaut @code{'auto'}). Il peut valoir l'une des valeurs suivantes :


@itemize -

@item 
@code{'auto'} : Identique à @code{'seconds'} si @ref{23b6,,microsecond} vaut 0, à @code{'microseconds'} sinon.

@item 
@code{'hours'} : Inclut @ref{23b3,,hour} au format à deux chiffres @code{HH}.

@item 
@code{'minutes'} : Inclut @ref{23b3,,hour} et @ref{23b4,,minute} au format @code{HH:MM}.

@item 
@code{'seconds'} : Inclut @ref{23b3,,hour}, @ref{23b4,,minute} et @ref{23b5,,second} au format @code{HH:MM:SS}.

@item 
@code{'milliseconds'} : Inclut le temps complet, mais tronque la partie fractionnaire des millisecondes, au format @code{HH:MM:SS.sss}.

@item 
@code{'microseconds'} : Inclut le temps complet, au format @code{HH:MM:SS.ffffff}.
@end itemize

@cartouche
@quotation Note 
Les composants de temps exclus sont tronqués et non arrondis.
@end quotation
@end cartouche

Une @ref{1ff,,ValueError} sera levée en cas d'argument `timespec' invalide.

Exemple :

@example
>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'
@end example


Modifié dans la version 3.6: Added the `timespec' parameter.

@end deffn

@geindex __str__() (méthode datetime.time)
@anchor{library/datetime datetime time __str__}@anchor{23fa}
@deffn {Méthode} time.__str__ ()

For a time @code{t}, @code{str(t)} is equivalent to @code{t.isoformat()}.
@end deffn

@geindex strftime() (méthode datetime.time)
@anchor{library/datetime datetime time strftime}@anchor{1711}
@deffn {Méthode} time.strftime (format)

Renvoie une chaîne représentant l'heure, contrôlée par une chaîne de formatage explicite.  Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{23f8,,time.isoformat()}.
@end deffn

@geindex __format__() (méthode datetime.time)
@anchor{library/datetime datetime time __format__}@anchor{23fb}
@deffn {Méthode} time.__format__ (format)

Identique à @ref{1711,,time.strftime()}. Cela permet de spécifier une chaîne de formatage pour un objet @ref{1c9,,time} dans une @ref{997,,chaîne de formatage littérale} et à l'utilisation de @ref{60c,,str.format()}. Voir @ref{1757,,strftime() and strptime() Behavior} et @ref{23f8,,time.isoformat()}.
@end deffn

@geindex utcoffset() (méthode datetime.time)
@anchor{library/datetime datetime time utcoffset}@anchor{23f9}
@deffn {Méthode} time.utcoffset ()

Si @ref{23b7,,tzinfo} est @code{None}, renvoie @code{None}, sinon renvoie @code{self.tzinfo.utcoffset(None)}, et lève une exception si l'expression précédente ne renvoie pas @code{None} ou un objet @ref{9bd,,timedelta} d'une magnitude inférieure à un jour.


Modifié dans la version 3.7: Le décalage UTC peut aussi être autre chose qu'un ensemble de minutes.

@end deffn

@geindex dst() (méthode datetime.time)
@anchor{library/datetime datetime time dst}@anchor{23fc}
@deffn {Méthode} time.dst ()

Si @ref{23b7,,tzinfo} est @code{None}, renvoie @code{None}, sinon renvoie @code{self.tzinfo.dst(None)}, et lève une exception si l'expression précédente ne renvoie pas @code{None} ou un objet @ref{9bd,,timedelta} d'une magnitude inférieure à un jour.


Modifié dans la version 3.7: Le décalage DST n'est pas restreint à des minutes entières.

@end deffn

@geindex tzname() (méthode datetime.time)
@anchor{library/datetime datetime time tzname}@anchor{23fd}
@deffn {Méthode} time.tzname ()

Si @ref{23b7,,tzinfo} est @code{None}, renvoie @code{None}, sinon renvoie @code{self.tzinfo.tzname(None)}, et lève une exception si l'expression précédente ne renvoie pas @code{None} ou une chaîne de caractères.
@end deffn

@menu
* Exemples d'utilisation de time:: 

@end menu

@node Exemples d'utilisation de time,,,Objets time
@anchor{library/datetime examples-of-usage-time}@anchor{23fe}
@subsubsection Exemples d'utilisation de @code{time}


Exemples d'utilisation de l'objet @ref{1c9,,time} :

@example
>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"@{self.__class__.__name__@}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The @{@} is @{:%H:%M@}.'.format("time", t)
'The time is 12:10.'
@end example

@node Objets tzinfo,Objets timezone,Objets time,datetime — Types de base pour la date et l'heure
@anchor{library/datetime datetime-tzinfo}@anchor{23ff}@anchor{library/datetime tzinfo-objects}@anchor{2400}
@subsubsection Objets @code{tzinfo}


@geindex tzinfo (classe dans datetime)
@anchor{library/datetime datetime tzinfo}@anchor{5c8}
@deffn {Classe} datetime.tzinfo

Il s'agit d'une classe mère abstraite, ce qui signifie que cette classe ne doit pas être instanciée directement.  Définissez une sous-classe de @ref{5c8,,tzinfo} pour capturer des informations sur un fuseau horaire particulier.

Une instance (d'une sous-classe concrète) de @ref{5c8,,tzinfo} peut être passée aux constructeurs des objets @ref{1c7,,datetime} et @ref{1c9,,time}. Les objets en question voient leurs attributs comme étant en temps local, et l'objet @ref{5c8,,tzinfo} contient des méthodes pour obtenir le décalage du temps local par rapport à UTC, le nom du fuseau horaire, le décalage d'heure d'été, tous relatifs à un objet de date ou d'heure qui leur est passé.

You need to derive a concrete subclass, and (at least)
supply implementations of the standard @ref{5c8,,tzinfo} methods needed by the
@ref{1c7,,datetime} methods you use. The @code{datetime} module provides
@ref{10a1,,timezone}, a simple concrete subclass of @ref{5c8,,tzinfo} which can
represent time zones with fixed offset from UTC such as UTC itself or North
American EST and EDT.

Special requirement for pickling:  A @ref{5c8,,tzinfo} subclass must have an
@ref{69b,,__init__()} method that can be called with no arguments,
otherwise it can be
pickled but possibly not unpickled again. This is a technical requirement that
may be relaxed in the future.

A concrete subclass of @ref{5c8,,tzinfo} may need to implement the following
methods. Exactly which methods are needed depends on the uses made of aware
@code{datetime} objects. If in doubt, simply implement all of them.
@end deffn

@geindex utcoffset() (méthode datetime.tzinfo)
@anchor{library/datetime datetime tzinfo utcoffset}@anchor{2401}
@deffn {Méthode} tzinfo.utcoffset (dt)

Renvoie le décalage de l'heure locale par rapport à UTC, sous la forme d'un objet @ref{9bd,,timedelta} qui est positif à l'est de UTC. Si l'heure locale est à l'ouest de UTC, il doit être négatif.

Cela représente le décalage `total' par rapport à UTC ; par exemple, si un objet @ref{5c8,,tzinfo} représente à la fois un fuseau horaire et son ajustement à l'heure d'été, @ref{2401,,utcoffset()} devrait renvoyer leur somme.  Si le décalage UTC n'est pas connu, elle renvoie @code{None}.  Sinon, la valeur renvoyée doit être un objet @ref{9bd,,timedelta} compris strictement entre @code{-timedelta(hours=24)} et @code{timedelta(hours=24)} (l'amplitude du décalage doit être inférieure à un jour).  La plupart des implémentations de @ref{2401,,utcoffset()} ressembleront probablement à l'une des deux suivantes :

@example
return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class
@end example

Si @ref{2401,,utcoffset()} ne renvoie pas @code{None}, @ref{2402,,dst()} ne doit pas non plus renvoyer @code{None}.

L'implémentation par défaut de @ref{2401,,utcoffset()} lève une @ref{225,,NotImplementedError}.


Modifié dans la version 3.7: Le décalage UTC peut aussi être autre chose qu'un ensemble de minutes.

@end deffn

@geindex dst() (méthode datetime.tzinfo)
@anchor{library/datetime datetime tzinfo dst}@anchor{2402}
@deffn {Méthode} tzinfo.dst (dt)

Renvoie le réglage de l'heure d'été (DST), sous la forme d'un objet @ref{9bd,,timedelta} ou @code{None} si l'information DST n'est pas connue.

Return @code{timedelta(0)} if DST is not in effect.
If DST is in effect, return the offset as a @ref{9bd,,timedelta} object
(see @ref{2401,,utcoffset()} for details). Note that DST offset, if applicable, has
already been added to the UTC offset returned by @ref{2401,,utcoffset()}, so there's
no need to consult @ref{2402,,dst()} unless you're interested in obtaining DST info
separately. For example, @ref{23e8,,datetime.timetuple()} calls its @ref{23bf,,tzinfo}
attribute's @ref{2402,,dst()} method to determine how the @ref{23e9,,tm_isdst} flag
should be set, and @ref{23e6,,tzinfo.fromutc()} calls @ref{2402,,dst()} to account for
DST changes when crossing time zones.

Une instance `tz' d'une sous-classe @ref{5c8,,tzinfo} convenant à la fois pour une heure standard et une heure d'été doit être cohérente :

@code{tz.utcoffset(dt) - tz.dst(dt)}

must return the same result for every @ref{1c7,,datetime} `dt' with @code{dt.tzinfo ==
tz}. For sane @ref{5c8,,tzinfo} subclasses, this expression yields the time
zone's "standard offset", which should not depend on the date or the time, but
only on geographic location. The implementation of @ref{9be,,datetime.astimezone()}
relies on this, but cannot detect violations; it's the programmer's
responsibility to ensure it. If a @ref{5c8,,tzinfo} subclass cannot guarantee
this, it may be able to override the default implementation of
@ref{23e6,,tzinfo.fromutc()} to work correctly with @ref{9be,,astimezone()} regardless.

La plupart des implémentations de @ref{2402,,dst()} ressembleront probablement à l'une des deux suivantes :

@example
def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)
@end example

ou :

@example
def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)
@end example

L'implémentation par défaut de @ref{2402,,dst()} lève une @ref{225,,NotImplementedError}.


Modifié dans la version 3.7: Le décalage DST n'est pas restreint à des minutes entières.

@end deffn

@geindex tzname() (méthode datetime.tzinfo)
@anchor{library/datetime datetime tzinfo tzname}@anchor{2403}
@deffn {Méthode} tzinfo.tzname (dt)

Return the time zone name corresponding to the @ref{1c7,,datetime} object `dt', as
a string. Nothing about string names is defined by the @code{datetime} module,
and there's no requirement that it mean anything in particular. For example,
@code{"GMT"}, @code{"UTC"}, @code{"-500"}, @code{"-5:00"}, @code{"EDT"}, @code{"US/Eastern"}, @code{"America/New York"} are all
valid replies. Return @code{None} if a string name isn't known. Note that this is
a method rather than a fixed string primarily because some @ref{5c8,,tzinfo}
subclasses will wish to return different names depending on the specific value
of `dt' passed, especially if the @ref{5c8,,tzinfo} class is accounting for
daylight time.

L'implémentation par défaut de @ref{2403,,tzname()} lève une @ref{225,,NotImplementedError}.
@end deffn

Ces méthodes sont appelées par les objets @ref{1c7,,datetime} et @ref{1c9,,time}, en réponse à leurs méthodes de mêmes noms.  Un objet @ref{1c7,,datetime} se passe lui-même en tant qu'argument, et un objet @ref{1c9,,time} passe @code{None}.  Les méthodes des sous-classes @ref{5c8,,tzinfo} doivent alors être prêtes à recevoir un argument @code{None} pour `dt', ou une instance de @ref{1c7,,datetime}.

Quand @code{None} est passé, il est de la responsabilité du `designer' de la classe de choisir la meilleure réponse.  Par exemple, renvoyer @code{None} est approprié si la classe souhaite signaler que les objets de temps ne participent pas au protocole @ref{5c8,,tzinfo}. Il peut être plus utile pour @code{utcoffset(None)} de renvoyer le décalage UTC standard, comme il n'existe aucune autre convention pour obtenir ce décalage.

When a @ref{1c7,,datetime} object is passed in response to a @ref{1c7,,datetime}
method, @code{dt.tzinfo} is the same object as `self'. @ref{5c8,,tzinfo} methods can
rely on this, unless user code calls @ref{5c8,,tzinfo} methods directly. The
intent is that the @ref{5c8,,tzinfo} methods interpret `dt' as being in local
time, and not need worry about objects in other time zones.

Il y a une dernière méthode de @ref{5c8,,tzinfo} que les sous-classes peuvent vouloir redéfinir :

@geindex fromutc() (méthode datetime.tzinfo)
@anchor{library/datetime datetime tzinfo fromutc}@anchor{23e6}
@deffn {Méthode} tzinfo.fromutc (dt)

This is called from the default @ref{9be,,datetime.astimezone()}
implementation. When called from that, @code{dt.tzinfo} is `self', and `dt''s
date and time data are to be viewed as expressing a UTC time. The purpose
of @ref{23e6,,fromutc()} is to adjust the date and time data, returning an
equivalent datetime in `self''s local time.

Most @ref{5c8,,tzinfo} subclasses should be able to inherit the default
@ref{23e6,,fromutc()} implementation without problems. It's strong enough to handle
fixed-offset time zones, and time zones accounting for both standard and
daylight time, and the latter even if the DST transition times differ in
different years. An example of a time zone the default @ref{23e6,,fromutc()}
implementation may not handle correctly in all cases is one where the standard
offset (from UTC) depends on the specific date and time passed, which can happen
for political reasons. The default implementations of @ref{9be,,astimezone()} and
@ref{23e6,,fromutc()} may not produce the result you want if the result is one of the
hours straddling the moment the standard offset changes.

En omettant le code des cas d'erreurs, l'implémentation par défaut de @ref{23e6,,fromutc()} se comporte comme suit :

@example
def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt
@end example
@end deffn

Dans le fichier @code{tzinfo_examples.py} il y a des exemples de @ref{5c8,,tzinfo} classes :

@example
from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")
@end example

Notez que, deux fois par an, on rencontre des subtilités inévitables dans les sous-classes de @ref{5c8,,tzinfo} représentant à la fois des heures standard et d'été, au passage de l'une à l'autre. Concrètement, considérez le fuseau de l'est des États-Unis (UTC -0500), où EDT (heure d'été) débute à la minute qui suit 1:59 (EST) le second dimanche de mars, et se termine à la minute qui suit 1:59 (EDT) le premier dimanche de novembre :

@example
  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM
@end example

Quand l'heure d'été débute (la ligne « `start' »), l'horloge locale passe de 1:59 à 3:00. Une heure de la forme 2:MM n'a pas vraiment de sens ce jour là, donc  @code{astimezone(Eastern)} ne fournira pas de résultat avec @code{hour == 2} pour le jour où débute l'heure d'été. Par exemple, lors du changement d'heure du printemps 2016, nous obtenons :

@example
>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT
@end example

When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time. In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
@ref{9be,,astimezone()} mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then. In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times
have the @ref{c45,,fold} attribute set to 0 and the later times have it set to 1.
For example, at the Fall back transition of 2016, we get:

@example
>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0
@end example

Note that the @ref{1c7,,datetime} instances that differ only by the value of the
@ref{c45,,fold} attribute are considered equal in comparisons.

Applications that can't bear wall-time ambiguities should explicitly check the
value of the @ref{c45,,fold} attribute or avoid using hybrid
@ref{5c8,,tzinfo} subclasses; there are no ambiguities when using @ref{10a1,,timezone},
or any other fixed-offset @ref{5c8,,tzinfo} subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).


@subsubheading Voir aussi


@quotation


@table @asis

@item @ref{133,,zoneinfo}

The @code{datetime} module has a basic @ref{10a1,,timezone} class (for
handling arbitrary fixed offsets from UTC) and its @ref{5ff,,timezone.utc}
attribute (a UTC @code{timezone} instance).

@code{zoneinfo} brings the `IANA time zone database' (also known as the Olson
database) to Python, and its usage is recommended.
@end table
@end quotation


@table @asis

@item IANA time zone database@footnote{https://www.iana.org/time-zones}

La `Time Zone Database' (souvent appelée `tz', `tzdata' ou `zoneinfo') contient les codes et les données représentant l'historique du temps local pour un grand nombre d'emplacements représentatifs autour du globe. Elle est mise à jour périodiquement, pour refléter les changements opérés par des politiques sur les bornes du fuseau, les décalages UTC, et les règles de passage à l'heure d'été.
@end table


@node Objets timezone,strftime and strptime Behavior,Objets tzinfo,datetime — Types de base pour la date et l'heure
@anchor{library/datetime datetime-timezone}@anchor{2404}@anchor{library/datetime timezone-objects}@anchor{2405}
@subsubsection Objets @code{timezone}


The @ref{10a1,,timezone} class is a subclass of @ref{5c8,,tzinfo}, each
instance of which represents a time zone defined by a fixed offset from
UTC.

Objects of this class cannot be used to represent time zone information in the
locations where different offsets are used in different days of the year or
where historical changes have been made to civil time.

@geindex timezone (classe dans datetime)
@anchor{library/datetime datetime timezone}@anchor{10a1}
@deffn {Classe} datetime.timezone (offset, name=None)

L'argument `offset' doit être spécifié comme un objet @ref{9bd,,timedelta} représentant la différence entre le temps local et UTC. Il doit être strictement compris entre @code{-timedelta(hours=24)} et @code{timedelta(hours=24)}, autrement une @ref{1ff,,ValueError} est levée.

L'argument `name' est optionnel. S'il est spécifié, il doit être une chaîne qui sera utilisée comme valeur de retour de la méthode @ref{23e7,,datetime.tzname()}.


Ajouté dans la version 3.2.



Modifié dans la version 3.7: Le décalage UTC peut aussi être autre chose qu'un ensemble de minutes.

@end deffn

@geindex utcoffset() (méthode datetime.timezone)
@anchor{library/datetime datetime timezone utcoffset}@anchor{2406}
@deffn {Méthode} timezone.utcoffset (dt)

Renvoie la valeur fixe spécifiée lorsque l'instance @ref{10a1,,timezone} est construite.

L'argument `dt' est ignoré. La valeur de retour est une instance @ref{9bd,,timedelta} égale à la différence entre le temps local et UTC.


Modifié dans la version 3.7: Le décalage UTC peut aussi être autre chose qu'un ensemble de minutes.

@end deffn

@geindex tzname() (méthode datetime.timezone)
@anchor{library/datetime datetime timezone tzname}@anchor{2407}
@deffn {Méthode} timezone.tzname (dt)

Renvoie la valeur fixe spécifiée lorsque l'instance @ref{10a1,,timezone} est construite.

Si `name' n'est pas fourni au constructeur, le nom renvoyé par @code{tzname(dt)} est généré comme suit à partir de la valeur de @code{offset}.  Si `offset' vaut @code{timedelta(0)}, le nom sera « UTC », autrement le nom sera une chaîne de la forme @code{UTC±HH:MM}, où ± est le signe d'@code{offset}, et HH et MM sont respectivement les représentations à deux chiffres de @code{offset.hours} et @code{offset.minutes}.


Modifié dans la version 3.6: Le nom généré à partir de @code{offset=timedelta(0)} est maintenant @code{'UTC'} plutôt que @code{'UTC+00:00'}.

@end deffn

@geindex dst() (méthode datetime.timezone)
@anchor{library/datetime datetime timezone dst}@anchor{2408}
@deffn {Méthode} timezone.dst (dt)

Renvoie toujours @code{None}.
@end deffn

@geindex fromutc() (méthode datetime.timezone)
@anchor{library/datetime datetime timezone fromutc}@anchor{2409}
@deffn {Méthode} timezone.fromutc (dt)

Renvoie @code{dt + offset}. L'argument `dt' doit être une instance avisée de @ref{1c7,,datetime}, avec @code{tzinfo} valant @code{self}.
@end deffn

Attributs de la classe :

@geindex utc (attribut datetime.timezone)
@anchor{library/datetime datetime timezone utc}@anchor{5ff}
@deffn {Attribut} timezone.utc

The UTC time zone, @code{timezone(timedelta(0))}.
@end deffn

@geindex % (percent);datetime format

@node strftime and strptime Behavior,,Objets timezone,datetime — Types de base pour la date et l'heure
@anchor{library/datetime strftime-and-strptime-behavior}@anchor{240a}@anchor{library/datetime strftime-strptime-behavior}@anchor{1757}
@subsubsection @code{strftime()} and @code{strptime()} Behavior


Les objets @ref{1c8,,date}, @ref{1c7,,datetime} et @ref{1c9,,time} comportent tous une méthode @code{strftime(format)}, pour créer une représentation du temps sous forme d'une chaîne, contrôlée par une chaîne de formatage explicite.

Inversement, la méthode de classe @ref{1593,,datetime.strptime()} crée un objet @ref{1c7,,datetime} à partir d'une chaîne représentant une date et une heure, et une chaîne de format correspondante.

The table below provides a high-level comparison of @ref{c7e,,strftime()}
versus @ref{1593,,strptime()}:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

@code{strftime}

@tab

@code{strptime}

@item

Utilisation

@tab

Convertit un objet en une chaîne selon un format donné

@tab

Analyse une chaîne dans un objet @ref{1c7,,datetime} en fonction du format de correspondance donné

@item

Type de méthode

@tab

Méthode d'instance

@tab

Méthode de classe

@item

Méthode de

@tab

@ref{1c8,,date} ; @ref{1c7,,datetime} ; @ref{1c9,,time}

@tab

@ref{1c7,,datetime}

@item

Signature

@tab

@code{strftime(format)}

@tab

@code{strptime(date_string, format)}

@end multitable


@quotation
@anchor{library/datetime format-codes}@anchor{23a9}
@end quotation

@menu
* strftime() and strptime() Format Codes: strftime and strptime Format Codes. 
* Détail technique:: 

@end menu

@node strftime and strptime Format Codes,Détail technique,,strftime and strptime Behavior
@anchor{library/datetime strftime-and-strptime-format-codes}@anchor{240b}
@subsubsection @code{strftime()} and @code{strptime()} Format Codes


Ces méthodes acceptent des codes de formatage qui peuvent être utilisés pour analyser et formater les dates :

@example
>>> datetime.strptime('31/01/22 23:59:59.999999',
...                   '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
@end example

Voici la liste de tous les codes de formatage requis par le C standard 1989, et ils fonctionnent sur toutes les plateformes possédant une implémentation de C standard.


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

Signification

@tab

Exemple

@tab

Notes

@item

@code{%a}

@tab

Jour de la semaine abrégé dans la langue locale.

@tab


@display
Sun, Mon, ..., Sat (en_US);@w{ }
Lu, Ma, ..., Di (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%A}

@tab

Jour de la semaine complet dans la langue locale.

@tab


@display
`Sunday', `Monday', ..., `Saturday' (`en_US');@w{ }
Lundi, Mardi, ..., Dimanche (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%w}

@tab

Jour de la semaine en chiffre, avec 0 pour le dimanche et 6 pour le samedi.

@tab

0, 1, ..., 6

@tab

@item

@code{%d}

@tab

Jour du mois sur deux chiffres.

@tab

01, 02, ..., 31

@tab

(9)

@item

@code{%b}

@tab

Nom du mois abrégé dans la langue locale.

@tab


@display
Jan, Feb, ..., Dec (`en_US');@w{ }
janv., févr., ..., déc. (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%B}

@tab

Nom complet du mois dans la langue locale.

@tab


@display
`January', `February', ..., `December' (`en_US');@w{ }
janvier, février, ..., décembre (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%m}

@tab

Numéro du mois sur deux chiffres.

@tab

01, 02, ..., 12

@tab

(9)

@item

@code{%y}

@tab

Année sur deux chiffres (sans le siècle).

@tab

00, 01, ..., 99

@tab

(9)

@item

@code{%Y}

@tab

Année complète sur quatre chiffres.

@tab

0001, 0002, ..., 2013,
2014, ..., 9998, 9999

@tab

(2)

@item

@code{%H}

@tab

Heure à deux chiffres de 00 à 23.

@tab

00, 01, ..., 23

@tab

(9)

@item

@code{%I}

@tab

Heure à deux chiffres pour les horloges 12h (01 à 12).

@tab

01, 02, ..., 12

@tab

(9)

@item

@code{%p}

@tab

Équivalent local à AM/PM.

@tab


@display
AM, PM (en_US);@w{ }
am, pm (de_DE)@w{ }
@end display



@tab

(1),
(3)

@item

@code{%M}

@tab

Minutes sur deux chiffres.

@tab

00, 01, ..., 59

@tab

(9)

@item

@code{%S}

@tab

Secondes sur deux chiffres.

@tab

00, 01, ..., 59

@tab

(4),
(9)

@item

@code{%f}

@tab

Microsecondes sur 6 chiffres.

@tab

000000, 000001, ...,
999999

@tab

(5)

@item

@code{%z}

@tab

Décalage horaire UTC sous la forme @code{±HHMM[SS[.ffffff]]} (chaîne vide si l'instance est naïve).

@tab

(vide), +0000, -0400, +1030, +063415, -030712.345216

@tab

(6)

@item

@code{%Z}

@tab

Nom du fuseau horaire (chaîne vide si l'instance est naïve).

@tab

(vide), UTC, GMT

@tab

(6)

@item

@code{%j}

@tab

Numéro du jour dans l'année sur trois chiffres.

@tab

001, 002, ..., 366

@tab

(9)

@item

@code{%U}

@tab

Numéro de la semaine à deux chiffres (où dimanche est considéré comme le premier jour de la semaine). Tous les jours de l'année précédent le premier dimanche sont considérés comme appartenant à la semaine 0.

@tab

00, 01, ..., 53

@tab

(7),
(9)

@item

@code{%W}

@tab

Numéro de la semaine à deux chiffres (où lundi est considéré comme le premier jour de la semaine). Tous les jours de l'année précédent le premier lundi sont considérés comme appartenant à la semaine 0.

@tab

00, 01, ..., 53

@tab

(7),
(9)

@item

@code{%c}

@tab

Représentation locale de la date et de l'heure.

@tab


@display
Tue Aug 16 21:30:00 1988 (`en_US');@w{ }
mar. 16 août 1988 21:30:00 (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%x}

@tab

Représentation locale de la date.

@tab


@display
08/16/88 (None);@w{ }
08/16/1988 (`en_US');@w{ }
16/08/1988 (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%X}

@tab

Représentation locale de l'heure.

@tab


@display
21:30:00 (`en_US') ;@w{ }
21:30:00 (`fr_FR')@w{ }
@end display



@tab

(1)

@item

@code{%%}

@tab

Un caractère @code{'%'} littéral.

@tab

%

@tab

@end multitable


Plusieurs directives supplémentaires non requises par la norme C89 sont incluses pour des raisons de commodité. Ces paramètres correspondent tous aux valeurs de date de la norme ISO 8601.


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

Signification

@tab

Exemple

@tab

Notes

@item

@code{%G}

@tab

Année complète ISO 8601 représentant l'année contenant la plus grande partie de la semaine ISO (@code{%V}).

@tab

0001, 0002, ..., 2013,
2014, ..., 9998, 9999

@tab

(8)

@item

@code{%u}

@tab

Jour de la semaine ISO 8601 où 1 correspond au lundi.

@tab

1, 2, ..., 7

@tab

@item

@code{%V}

@tab

Numéro de la semaine ISO 8601, avec lundi étant le premier jour de la semaine. La semaine 01 est la semaine contenant le 4 janvier.

@tab

01, 02, ..., 53

@tab

(8),
(9)

@item

@code{%:z}

@tab

UTC offset in the form
@code{±HH:MM[:SS[.ffffff]]}
(empty string if the object is
naive).

@tab

(empty), +00:00,
-04:00, +10:30,
+06:34:15,
-03:07:12.345216

@tab

(6)

@end multitable


These may not be available on all platforms when used with the @ref{c7e,,strftime()}
method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
with the year and week number directives above. Calling @ref{1593,,strptime()} with
incomplete or ambiguous ISO 8601 directives will raise a @ref{1ff,,ValueError}.

The full set of format codes supported varies across platforms, because Python
calls the platform C library's @code{strftime()} function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the @code{strftime(3)@footnote{https://manpages.debian.org/strftime(3)}} documentation. There are also
differences between platforms in handling of unsupported format specifiers.


Ajouté dans la version 3.6: @code{%G}, @code{%u} et @code{%V} ont été ajoutés.



Ajouté dans la version 3.12: @code{%:z} was added.


@node Détail technique,,strftime and strptime Format Codes,strftime and strptime Behavior
@anchor{library/datetime technical-detail}@anchor{240c}
@subsubsection Détail technique


Broadly speaking, @code{d.strftime(fmt)} acts like the @ref{ed,,time} module's
@code{time.strftime(fmt, d.timetuple())} although not all objects support a
@ref{23d1,,timetuple()} method.

For the @ref{1593,,datetime.strptime()} class method, the default value is
@code{1900-01-01T00:00:00.000}: any components not specified in the format string
will be pulled from the default value. @footnote{
Passing @code{datetime.strptime('Feb 29', '%b %d')} will fail since 1900 is not a leap year.
}

L'utilisation de @code{datetime.strptime(date_string, format)} équivaut à :

@example
datetime(*(time.strptime(date_string, format)[0:6]))
@end example

except when the format includes sub-second components or time zone offset
information, which are supported in @code{datetime.strptime} but are discarded by
@code{time.strptime}.

For @ref{1c9,,time} objects, the format codes for year, month, and day should not
be used, as @code{time} objects have no such values. If they're used anyway,
1900 is substituted for the year, and 1 for the month and day.

For @ref{1c8,,date} objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as @ref{1c8,,date} objects have no such
values. If they're used anyway, 0 is substituted for them.

Pour la même raison, la gestion des chaînes contenant des caractères (ou points) Unicode qui ne peuvent pas être représentés dans la `locale' actuelle dépend aussi de la plateforme. Sur certaines plateformes, ces caractères sont conservés tels quels dans la sortie, alors que sur d'autres plateformes @code{strftime} lève une @ref{1281,,UnicodeError} ou renvoie une chaîne vide.

Notes :


@enumerate 

@item 
Comme le format dépend de la locale courante, les assomptions sur la valeur de retour doivent être prises soigneusement. L'ordre des champs variera (par exemple, « mois/jour/année » au lieu de « année/mois/jour »), et le résultat peut contenir des caractères non-ASCII.

@item 
The @ref{1593,,strptime()} method can parse years in the full [1, 9999] range, but
years < 1000 must be zero-filled to 4-digit width.


Modifié dans la version 3.2: In previous versions, @ref{c7e,,strftime()} method was restricted to
years >= 1900.



Modifié dans la version 3.3: In version 3.2, @ref{c7e,,strftime()} method was restricted to
years >= 1000.


@item 
When used with the @ref{1593,,strptime()} method, the @code{%p} directive only affects
the output hour field if the @code{%I} directive is used to parse the hour.

@item 
Unlike the @ref{ed,,time} module, the @code{datetime} module does not support
leap seconds.

@item 
When used with the @ref{1593,,strptime()} method, the @code{%f} directive
accepts from one to six digits and zero pads on the right. @code{%f} is
an extension to the set of format characters in the C standard (but
implemented separately in datetime objects, and therefore always
available).

@item 
For a naive object, the @code{%z}, @code{%:z} and @code{%Z} format codes are replaced
by empty strings.

Pour un objet avisé :


@table @asis

@item @code{%z}

@ref{23e4,,utcoffset()} is transformed into a string of the form
@code{±HHMM[SS[.ffffff]]}, where @code{HH} is a 2-digit string giving the number
of UTC offset hours, @code{MM} is a 2-digit string giving the number of UTC
offset minutes, @code{SS} is a 2-digit string giving the number of UTC offset
seconds and @code{ffffff} is a 6-digit string giving the number of UTC
offset microseconds. The @code{ffffff} part is omitted when the offset is a
whole number of seconds and both the @code{ffffff} and the @code{SS} part is
omitted when the offset is a whole number of minutes. For example, if
@ref{23e4,,utcoffset()} returns @code{timedelta(hours=-3, minutes=-30)}, @code{%z} is
replaced with the string @code{'-0330'}.
@end table


Modifié dans la version 3.7: Le décalage UTC peut aussi être autre chose qu'un ensemble de minutes.



Modifié dans la version 3.7: When the @code{%z} directive is provided to the  @ref{1593,,strptime()} method,
the UTC offsets can have a colon as a separator between hours, minutes
and seconds.
For example, @code{'+01:00:00'} will be parsed as an offset of one hour.
In addition, providing @code{'Z'} is identical to @code{'+00:00'}.



@table @asis

@item @code{%:z}

Behaves exactly as @code{%z}, but has a colon separator added between
hours, minutes and seconds.

@item @code{%Z}

In @ref{c7e,,strftime()}, @code{%Z} is replaced by an empty string if
@ref{23e7,,tzname()} returns @code{None}; otherwise @code{%Z} is replaced by the
returned value, which must be a string.

@ref{1593,,strptime()} only accepts certain values for @code{%Z}:


@enumerate 

@item 
toute valeur dans @code{time.tzname} pour votre machine locale

@item 
les valeurs @code{UTC} et @code{GMT} codés en dur
@end enumerate

Ainsi, quelqu'un qui vit au Japon peut avoir comme valeurs valides @code{JST}, @code{UTC} et @code{GMT}, mais probablement pas @code{EST}. Les valeurs invalides lèvent @code{ValueError}.
@end table


Modifié dans la version 3.2: When the @code{%z} directive is provided to the @ref{1593,,strptime()} method, an
aware @ref{1c7,,datetime} object will be produced. The @code{tzinfo} of the
result will be set to a @ref{10a1,,timezone} instance.


@item 
When used with the @ref{1593,,strptime()} method, @code{%U} and @code{%W} are only used
in calculations when the day of the week and the calendar year (@code{%Y})
are specified.

@item 
Similar to @code{%U} and @code{%W}, @code{%V} is only used in calculations when the
day of the week and the ISO year (@code{%G}) are specified in a
@ref{1593,,strptime()} format string. Also note that @code{%G} and @code{%Y} are not
interchangeable.

@item 
When used with the @ref{1593,,strptime()} method, the leading zero is optional
for  formats @code{%d}, @code{%m}, @code{%H}, @code{%I}, @code{%M}, @code{%S}, @code{%j}, @code{%U},
@code{%W}, and @code{%V}. Format @code{%y} does require a leading zero.

@item 
When parsing a month and day using @ref{1593,,strptime()}, always
include a year in the format.  If the value you need to parse lacks a year,
append an explicit dummy leap year.  Otherwise your code will raise an
exception when it encounters leap day because the default year used by the
parser is not a leap year.  Users run into this bug every four years...

@example
>>> month_day = "02/29"
>>> datetime.strptime(f"@{month_day@};1984", "%m/%d;%Y")  # No leap year bug.
datetime.datetime(1984, 2, 29, 0, 0)
@end example


Deprecated since version 3.13, will be removed in version 3.15: @ref{1593,,strptime()} calls using a format string containing
a day of month without a year now emit a
@ref{1a3,,DeprecationWarning}. In 3.15 or later we may change this into
an error or change the default year to a leap year. See gh-70647@footnote{https://github.com/python/cpython/issues/70647}.

@end enumerate

@subsubheading Notes


@node zoneinfo --- IANA time zone support,calendar --- General calendar-related functions,datetime — Types de base pour la date et l'heure,Types de données
@anchor{library/zoneinfo doc}@anchor{240d}@anchor{library/zoneinfo module-zoneinfo}@anchor{133}@anchor{library/zoneinfo zoneinfo-iana-time-zone-support}@anchor{240e}
@subsection @code{zoneinfo} --- IANA time zone support


@geindex module; zoneinfo


Ajouté dans la version 3.9.


`Code source :' Lib/zoneinfo@footnote{https://github.com/python/cpython/tree/3.13/Lib/zoneinfo}


__________________________________________________________________


The @ref{133,,zoneinfo} module provides a concrete time zone implementation to
support the IANA time zone database as originally specified in 
@geindex Python Enhancement Proposals; PEP 615
PEP 615@footnote{https://peps.python.org/pep-0615/}. By
default, @ref{133,,zoneinfo} uses the system's time zone data if available; if no
system time zone data is available, the library will fall back to using the
first-party tzdata@footnote{https://pypi.org/project/tzdata/} package available on PyPI.


@subsubheading Voir aussi



@table @asis

@item Module : @ref{30,,datetime}

Fournit les types @ref{1c9,,time} et @ref{1c7,,datetime} attendus par @ref{8cc,,ZoneInfo}.

@item Package tzdata@footnote{https://pypi.org/project/tzdata/}

Paquet « quasi natif » maintenu par les développeurs de CPython pour fournir les données des fuseaux horaires via PyPI.
@end table


@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@menu
* Utilisation de ZoneInfo:: 
* Sources de données:: 
* La classe ZoneInfo:: 
* Fonctions: Fonctions<3>. 
* Variables globales:: 
* Exceptions et avertissements:: 

@end menu

@node Utilisation de ZoneInfo,Sources de données,,zoneinfo --- IANA time zone support
@anchor{library/zoneinfo using-zoneinfo}@anchor{240f}
@subsubsection Utilisation de @code{ZoneInfo}


@ref{8cc,,ZoneInfo} est une implémentation concrète de la classe de base abstraite @ref{5c8,,datetime.tzinfo} et est destinée à être rattachée à @code{tzinfo}, par le constructeur, par @ref{1481,,datetime.replace} ou par @ref{9be,,datetime.astimezone} :

@example
>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta

>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00

>>> dt.tzname()
'PDT'
@end example

Les `datetime' construits de cette manière sont compatibles avec l'arithmétique `datetime' et gèrent le passage à l'heure d'été sans autre intervention :

@example
>>> dt_add = dt + timedelta(days=1)

>>> print(dt_add)
2020-11-01 12:00:00-08:00

>>> dt_add.tzname()
'PST'
@end example

Ces fuseaux horaires prennent aussi en charge l'attribut @code{fold} introduit dans la 
@geindex Python Enhancement Proposals; PEP 495
PEP 495@footnote{https://peps.python.org/pep-0495/}. Pendant les transitions des décalages horaires qui induisent des temps ambigus (comme le passage de l'heure d'été à l'heure normale), le décalage `avant' la transition est utilisé quand @code{fold=0}, et le décalage `après' la transition est utilisé quand @code{fold=1}, par exemple :

@example
>>> dt = datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-11-01 01:00:00-07:00

>>> print(dt.replace(fold=1))
2020-11-01 01:00:00-08:00
@end example

Lors de la conversion à partir d'un autre fuseau horaire, `fold' est réglé à la valeur correcte :

@example
>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00
@end example

@node Sources de données,La classe ZoneInfo,Utilisation de ZoneInfo,zoneinfo --- IANA time zone support
@anchor{library/zoneinfo data-sources}@anchor{2410}
@subsubsection Sources de données


The @code{zoneinfo} module does not directly provide time zone data, and instead
pulls time zone information from the system time zone database or the
first-party PyPI package tzdata@footnote{https://pypi.org/project/tzdata/}, if available. Some systems, including
notably Windows systems, do not have an IANA database available, and so for
projects targeting cross-platform compatibility that require time zone data, it
is recommended to declare a dependency on tzdata. If neither system data nor
tzdata are available, all calls to @ref{8cc,,ZoneInfo} will raise
@ref{2411,,ZoneInfoNotFoundError}.

@menu
* Configurer les sources de données:: 

@end menu

@node Configurer les sources de données,,,Sources de données
@anchor{library/zoneinfo configuring-the-data-sources}@anchor{2412}@anchor{library/zoneinfo zoneinfo-data-configuration}@anchor{2413}
@subsubsection Configurer les sources de données


Lorsque @code{ZoneInfo(key)} est appelé, le constructeur recherche d'abord un fichier nommé @code{key} dans les répertoires spécifiés par @ref{1cfc,,TZPATH} et, en cas d'échec, recherche dans le paquet `tzdata'. Ce comportement peut être configuré de trois manières :


@enumerate 

@item 
La valeur par défaut @ref{1cfc,,TZPATH}, lorsqu'elle n'est pas spécifiée autrement, peut être configurée à @ref{1cfd,,la compilation}.

@item 
@ref{1cfc,,TZPATH} peut être configuré en utilisant @ref{2414,,une variable d'environnement}.

@item 
À @ref{2415,,l'exécution}, le chemin de recherche peut être manipulé à l'aide de la fonction @ref{2416,,reset_tzpath()}.
@end enumerate

@menu
* Configuration à la compilation:: 
* Configuration par l'environnement:: 
* Configuration à l'exécution:: 

@end menu

@node Configuration à la compilation,Configuration par l'environnement,,Configurer les sources de données
@anchor{library/zoneinfo compile-time-configuration}@anchor{2417}@anchor{library/zoneinfo zoneinfo-data-compile-time-config}@anchor{1cfd}
@subsubsection Configuration à la compilation


Par défaut, @ref{1cfc,,TZPATH} indique plusieurs emplacements de déploiement courants pour la base de données de fuseaux horaires (sauf sous Windows, où il n'existe pas de consensus pour l'emplacement des données de fuseaux horaires). Sur les systèmes POSIX, les distributeurs en aval ainsi que ceux qui construisent Python à partir des sources et qui savent où sont déployées les données de fuseau horaire de leur système peuvent modifier le chemin par défaut en spécifiant l'option de compilation @code{TZPATH} (ou, plus probablement, en utilisant l'option @ref{1cfb,,--with-tzpath} du script @code{configure}), qui doit être une chaîne délimitée par @ref{1cd0,,os.pathsep}.

Sur toutes les plates-formes, la valeur configurée est disponible en tant que clé de @code{TZPATH} dans @ref{1014,,sysconfig.get_config_var()}.

@node Configuration par l'environnement,Configuration à l'exécution,Configuration à la compilation,Configurer les sources de données
@anchor{library/zoneinfo environment-configuration}@anchor{2418}@anchor{library/zoneinfo zoneinfo-data-environment-var}@anchor{2414}
@subsubsection Configuration par l'environnement


Lors de l'initialisation de @ref{1cfc,,TZPATH} (soit au moment de l'importation, soit lorsque @ref{2416,,reset_tzpath()} est appelé sans argument), le module @code{zoneinfo} utilise la variable d'environnement @code{PYTHONTZPATH}, si elle existe, pour définir le chemin de recherche.

@geindex variable d'environnement; PYTHONTZPATH
@anchor{library/zoneinfo envvar-PYTHONTZPATH}@anchor{2419}
@deffn {Variable d'environnement} PYTHONTZPATH

Il s'agit d'une chaîne séparée par @ref{1cd0,,os.pathsep} contenant le chemin de recherche du fuseau horaire à utiliser. Elle doit être constituée uniquement de chemins absolus et non de chemins relatifs. Les composants relatifs spécifiés dans @code{PYTHONTZPATH} ne sont pas utilisés, mais le comportement reste défini par l'implémentation lorsqu'un chemin relatif est spécifié. CPython lève @ref{241a,,InvalidTZPathWarning} dans ce cas. Les autres implémentations sont libres d'ignorer silencieusement le composant erroné ou de lever une exception.
@end deffn

Pour que le système ignore les données système et utilise le paquet `tzdata' à la place, définissez @code{PYTHONTZPATH=""}.

@node Configuration à l'exécution,,Configuration par l'environnement,Configurer les sources de données
@anchor{library/zoneinfo runtime-configuration}@anchor{241b}@anchor{library/zoneinfo zoneinfo-data-runtime-config}@anchor{2415}
@subsubsection Configuration à l'exécution


Le chemin de recherche `TZ' peut également être configuré au moment de l'exécution à l'aide de la fonction @ref{2416,,reset_tzpath()}. Cette opération n'est généralement pas conseillée, bien qu'il soit raisonnable de l'utiliser dans les fonctions de test qui nécessitent l'utilisation d'un chemin de fuseau horaire spécifique (ou qui nécessitent de désactiver l'accès aux fuseaux horaires du système).

@node La classe ZoneInfo,Fonctions<3>,Sources de données,zoneinfo --- IANA time zone support
@anchor{library/zoneinfo the-zoneinfo-class}@anchor{241c}
@subsubsection La classe @code{ZoneInfo}


@geindex ZoneInfo (classe dans zoneinfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo}@anchor{8cc}
@deffn {Classe} zoneinfo.ZoneInfo (key)

Une sous-classe concrète de @ref{5c8,,datetime.tzinfo} qui représente un fuseau horaire IANA spécifié par la chaîne @code{key}. Les appels au constructeur principal renvoient toujours des objets dont la comparaison est identique ; autrement dit, sauf invalidation du cache via @ref{241d,,ZoneInfo.clear_cache()}, pour toutes les valeurs de @code{key}, l'assertion suivante est toujours vraie :

@example
a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b
@end example

@code{key} doit être sous la forme d'un chemin POSIX relatif et normalisé, sans références de niveau supérieur. Le constructeur lève @ref{1ff,,ValueError} si une clé non conforme est passée.

Si aucun fichier correspondant à @code{key} n'est trouvé, le constructeur lève @ref{2411,,ZoneInfoNotFoundError}.
@end deffn

La classe @code{ZoneInfo} possède deux constructeurs alternatifs :

@geindex from_file() (méthode de la classe zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo from_file}@anchor{241e}
@deffn {Méthode} classmethod ZoneInfo.from_file (fobj, /, key=None)

Construit un objet @code{ZoneInfo} à partir d'un objet fichier renvoyant des octets (par exemple, un fichier ouvert en mode binaire ou un objet @ref{e8d,,io.BytesIO}). Contrairement au constructeur principal, il construit toujours un nouvel objet.

Le paramètre @code{key} définit le nom de la zone pour les besoins de @ref{608,,__str__()} et @ref{607,,__repr__()}.

Les objets créés via ce constructeur ne peuvent pas être sérialisés (voir @ref{241f,,pickling}).
@end deffn

@geindex no_cache() (méthode de la classe zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo no_cache}@anchor{2420}
@deffn {Méthode} classmethod ZoneInfo.no_cache (key)

Un constructeur alternatif qui contourne le cache du constructeur. Il est identique au constructeur principal, mais renvoie un nouvel objet à chaque appel. Il est surtout utile à des fins de test ou de démonstration, mais il peut également être utilisé pour créer un système avec une stratégie d'invalidation du cache différente.

Les objets créés via ce constructeur contournent également le cache d'un processus de `désérialisation' lorsqu'ils sont désérialisés.

@c TODO: Add "See `cache_behavior`_" reference when that section is ready.

@cartouche
@quotation Prudence 
L'utilisation de ce constructeur peut modifier la sémantique de vos `datetimes' de manière surprenante, ne l'utilisez que si vous en avez vraiment besoin.
@end quotation
@end cartouche
@end deffn

Les méthodes de classe suivantes sont également disponibles :

@geindex clear_cache() (méthode de la classe zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo clear_cache}@anchor{241d}
@deffn {Méthode} classmethod ZoneInfo.clear_cache (*, only_keys=None)

Une méthode pour invalider le cache de la classe @code{ZoneInfo}. Si aucun argument n'est passé, tous les caches sont invalidés et le prochain appel au constructeur principal pour chaque clé renverra une nouvelle instance.

Si un itérable de noms de clés est passé au paramètre @code{only_keys}, seules les clés spécifiées sont retirées du cache. Les clés passées à @code{only_keys} mais non trouvées dans le cache sont ignorées.

@c TODO: Add "See `cache_behavior`_" reference when that section is ready.

@cartouche
@quotation Avertissement 
Invoking this function may change the semantics of datetimes using
@code{ZoneInfo} in surprising ways; this modifies module state
and thus may have wide-ranging effects. Only use it if you know that you
need to.
@end quotation
@end cartouche
@end deffn

La classe a un attribut :

@geindex key (attribut zoneinfo.ZoneInfo)
@anchor{library/zoneinfo zoneinfo ZoneInfo key}@anchor{2421}
@deffn {Attribut} ZoneInfo.key

Il s'agit d'un @ref{2422,,attribut} en lecture seule qui renvoie la valeur de @code{key} passée au constructeur, qui doit être une clé de recherche dans la base de données des fuseaux horaires de l'IANA (par exemple, @code{America/New_York}, @code{Europe/Paris} ou @code{Asia/Tokyo}).

Pour les zones construites à partir d'un fichier sans spécifier de paramètre @code{key}, cette valeur sera fixée à @code{None}.

@cartouche
@quotation Note 
Bien qu'il soit assez courant de les exposer aux utilisateurs finaux, ces valeurs sont conçues pour être des clés primaires permettant de représenter les zones concernées et pas nécessairement des éléments destinés à l'utilisateur. Des projets comme `CLDR' (`Unicode Common Locale Data Repository') peuvent être utilisés pour obtenir des chaînes de caractères plus conviviales à partir de ces clés.
@end quotation
@end cartouche
@end deffn

@menu
* Représentation sous forme de chaîne de caractères:: 
* Sérialisation Pickle:: 

@end menu

@node Représentation sous forme de chaîne de caractères,Sérialisation Pickle,,La classe ZoneInfo
@anchor{library/zoneinfo string-representations}@anchor{2423}
@subsubsection Représentation sous forme de chaîne de caractères


La représentation sous forme de chaîne renvoyée lors de l’appel de @ref{435,,str} sur un objet @ref{8cc,,ZoneInfo} utilise par défaut l’attribut @ref{2421,,ZoneInfo.key} (voir la note sur l’utilisation dans la documentation de l’attribut) :

@example
>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> dt = datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"@{dt.isoformat()@} [@{dt.tzinfo@}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'
@end example

Pour les objets construits à partir d’un fichier sans spécifier de paramètre @code{key}, @code{str} revient à appeler @ref{7e7,,repr()}. Le @code{repr} de @code{ZoneInfo} est défini par l’implémentation et n’est pas nécessairement stable entre les versions, mais il est garanti qu’il ne fournit pas un paramètre `key' @code{ZoneInfo} valide.

@node Sérialisation Pickle,,Représentation sous forme de chaîne de caractères,La classe ZoneInfo
@anchor{library/zoneinfo pickle-serialization}@anchor{2424}@anchor{library/zoneinfo pickling}@anchor{241f}
@subsubsection Sérialisation Pickle


Plutôt que de sérialiser toutes les données de transition, les objets @code{ZoneInfo} sont sérialisés à partir de l'attribut `key' et les objets @code{ZoneInfo} construits à partir de fichiers (même ceux avec une valeur pour @code{key} spécifiée) ne peuvent pas être sérialisés.

Le comportement d’un fichier @code{ZoneInfo} dépend de la façon dont il a été construit :


@enumerate 

@item 
@code{ZoneInfo(key)} : lorsqu’il est construit avec le constructeur primaire, un objet @code{ZoneInfo} est sérialisé en utilisant l'attribut `key' et, lorsqu’il est désérialisé, le processus de désérialisation utilise le constructeur primaire et donc on s’attend à ce qu’il soit le même objet que d’autres références au même fuseau horaire. Par exemple, si @code{europe_berlin_pkl} est une chaîne contenant un objet sérialisé construit à partir de @code{ZoneInfo("Europe/Berlin")}, on s’attend au comportement suivant :

@example
>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl)
>>> a is b
True
@end example

@item 
@code{ZoneInfo.no_cache(key)} : lorsqu’il est construit à partir du constructeur de contournement de cache, l’objet @code{ZoneInfo} est également sérialisé en utilisant l'attribut `key' mais, lorsqu’il est désérialisé, le processus de désérialisation utilise le constructeur de contournement de cache. Si @code{europe_berlin_pkl_nc} est une chaîne contenant un objet sérialisé construit à partir de @code{ZoneInfo.no_cache("Europe/Berlin")}, le comportement suivant est attendu :

@example
>>> a = ZoneInfo("Europe/Berlin")
>>> b = pickle.loads(europe_berlin_pkl_nc)
>>> a is b
False
@end example

@item 
@code{ZoneInfo.from_file(fobj, /, key=None)} : lorsqu’il est construit à partir d’un fichier, l’objet @code{ZoneInfo} lève une exception lors de la sérialisation. Si un utilisateur souhaite récupérer une @code{ZoneInfo} construite à partir d’un fichier, il est recommandé d’encapsuler les données dans un autre type ou d’utiliser une fonction de sérialisation personnalisée : soit en sérialisant en utilisant l'attribut `key', soit en stockant le contenu de l’objet fichier et en sérialisant cet objet.
@end enumerate

Cette méthode de sérialisation nécessite que les données de fuseau horaire relatives à l'attribut `key' soient disponibles à la fois du côté de la sérialisation et de la désérialisation, de la même manière que les références aux classes et aux fonctions sont censées exister dans les environnements de sérialisation et de désérialisation. Cela signifie également qu’aucune garantie n’est donnée quant à la cohérence des résultats lors de la désérialisation d’un @code{ZoneInfo} sérialisé dans un environnement avec une version différente des données de fuseau horaire.

@node Fonctions<3>,Variables globales,La classe ZoneInfo,zoneinfo --- IANA time zone support
@anchor{library/zoneinfo functions}@anchor{2425}
@subsubsection Fonctions


@geindex available_timezones() (dans le module zoneinfo)
@anchor{library/zoneinfo zoneinfo available_timezones}@anchor{18e9}
@deffn {Fonction} zoneinfo.available_timezones ()

Fournit un ensemble contenant toutes les clés valides pour les fuseaux horaires IANA disponibles n’importe où sur `TZPATH'. Il est recalculé à chaque appel à la fonction.

Cette fonction n’inclut que les noms de zone canoniques et n’inclut pas les zones « spéciales » telles que celles sous les répertoires @code{posix/} et @code{right/}, ou la zone @code{posixrules}.

@cartouche
@quotation Prudence 
cette fonction peut ouvrir un grand nombre de fichiers, car la meilleure façon de déterminer si un fichier sur le chemin du fuseau horaire est un fuseau horaire valide est de lire la « chaîne magique » au début.
@end quotation
@end cartouche

@cartouche
@quotation Note 
ces valeurs n’ont pas vocation à être montrées aux utilisateurs ; pour les éléments destinés à l’utilisateur, les applications doivent utiliser quelque chose comme `CLDR' (le référentiel de données `Unicode Common Locale') afin d’obtenir des chaînes plus conviviales. Voir aussi la note d’avertissement sur @ref{2421,,ZoneInfo.key}.
@end quotation
@end cartouche
@end deffn

@geindex reset_tzpath() (dans le module zoneinfo)
@anchor{library/zoneinfo zoneinfo reset_tzpath}@anchor{2416}
@deffn {Fonction} zoneinfo.reset_tzpath (to=None)

Définit ou réinitialise le chemin de recherche des fuseaux horaires (@ref{1cfc,,TZPATH}) pour le module. Lorsqu’il est appelé sans arguments, @ref{1cfc,,TZPATH} est défini sur la valeur par défaut.

Appeler @code{reset_tzpath} n’invalide pas le cache @ref{8cc,,ZoneInfo}, donc les appels au constructeur primaire @code{ZoneInfo} n’utiliseront le nouveau @code{TZPATH} qu’en cas d’échec du cache.

Le paramètre @code{to} doit être une @ref{4db,,séquence} de chaînes ou @ref{c3f,,os.PathLike} et non une chaîne, qui doivent toutes être des chemins absolus. @ref{1ff,,ValueError} est levée si autre chose qu’un chemin absolu est passé.
@end deffn

@node Variables globales,Exceptions et avertissements,Fonctions<3>,zoneinfo --- IANA time zone support
@anchor{library/zoneinfo globals}@anchor{2426}
@subsubsection Variables globales


@geindex TZPATH (dans le module zoneinfo)
@anchor{library/zoneinfo zoneinfo TZPATH}@anchor{1cfc}
@deffn {Données} zoneinfo.TZPATH

Séquence en lecture seule représentant le chemin de recherche des fuseaux horaires – lors de la construction d’un @code{ZoneInfo} à partir de l'attribut `key', la clé est jointe à chaque entrée dans le @code{TZPATH} et le premier fichier trouvé est utilisé.

@code{TZPATH} ne peut contenir que des chemins absolus, jamais des chemins relatifs, quelle que soit sa configuration.

L’objet vers lequel @code{zoneinfo.TZPATH} pointe peut changer suite à un appel à @ref{2416,,reset_tzpath()}, il est donc recommandé d’utiliser @code{zoneinfo.TZPATH} plutôt que d’importer @code{TZPATH} de @code{zoneinfo} ou en assignant une variable de longue durée à @code{zoneinfo.TZPATH}.

Pour plus d’informations sur la configuration du chemin de recherche des fuseaux horaires, consultez @ref{2413,,Configurer les sources de données}.
@end deffn

@node Exceptions et avertissements,,Variables globales,zoneinfo --- IANA time zone support
@anchor{library/zoneinfo exceptions-and-warnings}@anchor{2427}
@subsubsection Exceptions et avertissements


@geindex ZoneInfoNotFoundError
@anchor{library/zoneinfo zoneinfo ZoneInfoNotFoundError}@anchor{2411}
@deffn {Exception} zoneinfo.ZoneInfoNotFoundError

Levée lorsque la construction d’un objet @ref{8cc,,ZoneInfo} échoue parce que la clé spécifiée est introuvable sur le système. C’est une sous-classe de @ref{33a,,KeyError}.
@end deffn

@geindex InvalidTZPathWarning
@anchor{library/zoneinfo zoneinfo InvalidTZPathWarning}@anchor{241a}
@deffn {Exception} zoneinfo.InvalidTZPathWarning

Levée lorsque 
@geindex PYTHONTZPATH
@geindex variable d'environnement; PYTHONTZPATH
@ref{2419,,PYTHONTZPATH} contient un composant non valide qui ne sera pas retenu, tel qu’un chemin relatif.
@end deffn

@c Links and references:

@node calendar --- General calendar-related functions,collections --- Container datatypes,zoneinfo --- IANA time zone support,Types de données
@anchor{library/calendar doc}@anchor{2428}@anchor{library/calendar calendar-general-calendar-related-functions}@anchor{2429}@anchor{library/calendar module-calendar}@anchor{14}
@subsection @code{calendar} --- General calendar-related functions


@geindex module; calendar

`Code source :' Lib/calendar.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/calendar.py}


__________________________________________________________________


Ce module permet d'afficher un calendrier comme le fait le programme Unix @code{cal}, et il fournit des fonctions utiles relatives au calendrier. Par défaut, ces calendriers ont le lundi comme premier jour de la semaine et le dimanche comme dernier jour. Utilisez @ref{242a,,setfirstweekday()} pour définir le premier jour de la semaine à dimanche (6) ou à tout autre jour de la semaine. Les paramètres pour spécifier les dates sont donnés sous forme de nombres entiers. Voir aussi les modules @ref{30,,datetime} et @ref{ed,,time}.

Les fonctions et les classes définies dans ce module utilisent un calendrier idéalisé, le calendrier grégorien actuel s'étendant indéfiniment dans les deux sens. Cela correspond à la définition du calendrier grégorien proleptique dans le livre de Dershowitz et Reingold « `Calendrical Calculations' », œuvre dans lequel il est le calendrier de référence de tous les calculs. Les années zéros et les années négatives sont interprétées comme prescrit par la norme ISO 8601. L'année 0 est 1 avant JC, l'année @code{-1} est 2 avant JC et ainsi de suite.

@geindex Calendar (classe dans calendar)
@anchor{library/calendar calendar Calendar}@anchor{242b}
@deffn {Classe} calendar.Calendar (firstweekday=0)

Crée un objet @ref{242b,,Calendar}. `firstweekday' est un entier spécifiant le premier jour de la semaine, valant par défaut @code{0} (soit @ref{242c,,MONDAY} pour lundi), pouvant aller jusqu'à @code{6} (soit @ref{242d,,SUNDAY} pour dimanche).

L'objet @ref{242b,,Calendar} fournit plusieurs méthodes pouvant être utilisées pour préparer les données du calendrier pour le formatage. Cette classe ne fait pas de formatage elle-même. Il s'agit du travail des sous-classes.

Les instances de @ref{242b,,Calendar} ont les méthodes suivantes :

@geindex iterweekdays() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar iterweekdays}@anchor{242e}
@deffn {Méthode} iterweekdays ()

Renvoie un itérateur sur les numéros des jours d'une semaine. La première valeur est donc la même que la valeur de la propriété @ref{242f,,firstweekday}.
@end deffn

@geindex itermonthdates() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdates}@anchor{c07}
@deffn {Méthode} itermonthdates (year, month)

Renvoie un itérateur sur les jours du mois `month' (1 à 12) de l'année `year'. Cet itérateur renvoie tous les jours du mois (sous forme d'instances de @ref{1c8,,datetime.date}) ainsi que tous les jours avant le début du mois et après la fin du mois nécessaires pour obtenir des semaines complètes.
@end deffn

@geindex itermonthdays() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays}@anchor{2430}
@deffn {Méthode} itermonthdays (year, month)

Renvoie un itérateur sur les jours du mois `month' de l'année `year', comme @ref{c07,,itermonthdates()}, sans être limité par l'intervalle de @ref{1c8,,datetime.date}. Les jours renvoyés sont simplement les numéros des jours du mois. Pour les jours en dehors du mois spécifié, le numéro du jour est @code{0}.
@end deffn

@geindex itermonthdays2() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays2}@anchor{2431}
@deffn {Méthode} itermonthdays2 (year, month)

Renvoie un itérateur sur les jours du mois `month' de l'année `year' comme @ref{c07,,itermonthdates()}, sans être limité par la plage @ref{1c8,,datetime.date}. Les jours renvoyés sont des paires composées du numéro du jour dans le mois et du numéro du jour dans la semaine.
@end deffn

@geindex itermonthdays3() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays3}@anchor{c08}
@deffn {Méthode} itermonthdays3 (year, month)

Renvoie un itérateur sur les jours du `month' de l'année `year', comme @ref{c07,,itermonthdates()}, sans être limité par l'intervalle de @ref{1c8,,datetime.date}. Les jours sont renvoyés sous forme de triplets composés du numéro de l'année, du mois et du jour dans le mois.


Ajouté dans la version 3.7.

@end deffn

@geindex itermonthdays4() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar itermonthdays4}@anchor{c09}
@deffn {Méthode} itermonthdays4 (year, month)

Renvoie un itérateur sur les jours du mois `month' de l'année `year', comme @ref{c07,,itermonthdates()}, sans être limité par l'intervalle de @ref{1c8,,datetime.date}. Le jours sont renvoyés sous forme de quadruplets contenant le numéro de l'année, du mois, du jour du mois et du jour de la semaine.


Ajouté dans la version 3.7.

@end deffn

@geindex monthdatescalendar() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar monthdatescalendar}@anchor{2432}
@deffn {Méthode} monthdatescalendar (year, month)

Renvoie la liste des semaines complètes du mois `month' de l'année `year'. Les semaines sont des listes de sept objets @ref{1c8,,datetime.date}.
@end deffn

@geindex monthdays2calendar() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar monthdays2calendar}@anchor{2433}
@deffn {Méthode} monthdays2calendar (year, month)

Renvoie la liste des semaines complètes du mois `month' de l'année `year'. Les semaines sont des listes de sept paires contenant le numéro du jour dans le mois et du numéro du jour dans la semaine.
@end deffn

@geindex monthdayscalendar() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar monthdayscalendar}@anchor{2434}
@deffn {Méthode} monthdayscalendar (year, month)

Renvoie la liste des semaines complètes du mois `month' de l'année `year'. Les semaines sont une liste de sept numéros de jours.
@end deffn

@geindex yeardatescalendar() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar yeardatescalendar}@anchor{2435}
@deffn {Méthode} yeardatescalendar (year, width=3)

Renvoie ce qu'il faut pour afficher correctement une année. La valeur renvoyée est une liste de lignes de mois. Chaque ligne mensuelle contient jusqu'à `width' mois (avec une valeur par défaut à 3). Chaque mois contient de 4 à 6 semaines et chaque semaine 1 à 7 jours. Les jours sont des objets @ref{1c8,,datetime.date}.
@end deffn

@geindex yeardays2calendar() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar yeardays2calendar}@anchor{2436}
@deffn {Méthode} yeardays2calendar (year, width=3)

Renvoie ce qu'il faut pour afficher correctement une année, (similaire à @ref{2435,,yeardatescalendar()}). Les listes des semaines contiennent des paires contenant le numéro du jour du mois et le numéro du jour de la semaine. Les numéro des jours en dehors de ce mois sont à zéro.
@end deffn

@geindex yeardayscalendar() (méthode calendar.Calendar)
@anchor{library/calendar calendar Calendar yeardayscalendar}@anchor{2437}
@deffn {Méthode} yeardayscalendar (year, width=3)

Renvoie ce qu'il faut pour afficher correctement une année, (similaire à @ref{2435,,yeardatescalendar()}). Les listes de semaines contiennent des numéros de jours. Les numéros de jours en dehors de ce mois sont de zéro.
@end deffn
@end deffn

@geindex TextCalendar (classe dans calendar)
@anchor{library/calendar calendar TextCalendar}@anchor{2438}
@deffn {Classe} calendar.TextCalendar (firstweekday=0)

Cette classe peut être utilisée pour générer des calendriers en texte brut.

Les instances @ref{2438,,TextCalendar} exposent les méthodes suivantes :

@geindex formatday() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatday}@anchor{2439}
@deffn {Méthode} formatday (theday, weekday, width)

Return a string representing a single day formatted with the given `width'.
If `theday' is @code{0}, return a string of spaces of
the specified width, representing an empty day. The `weekday' parameter
is unused.
@end deffn

@geindex formatweek() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatweek}@anchor{243a}
@deffn {Méthode} formatweek (theweek, w=0)

Return a single week in a string with no newline. If `w' is provided, it
specifies the width of the date columns, which are centered. Depends
on the first weekday as specified in the constructor or set by the
@ref{242a,,setfirstweekday()} method.
@end deffn

@geindex formatweekday() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatweekday}@anchor{243b}
@deffn {Méthode} formatweekday (weekday, width)

Return a string representing the name of a single weekday formatted to
the specified `width'. The `weekday' parameter is an integer representing
the day of the week, where @code{0} is Monday and @code{6} is Sunday.
@end deffn

@geindex formatweekheader() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatweekheader}@anchor{243c}
@deffn {Méthode} formatweekheader (width)

Return a string containing the header row of weekday names, formatted
with the given `width' for each column. The names depend on the locale
settings and are padded to the specified width.
@end deffn

@geindex formatmonth() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatmonth}@anchor{243d}
@deffn {Méthode} formatmonth (theyear, themonth, w=0, l=0)

Donne le calendrier d'un mois dans une chaîne multi-ligne. Si `w' est fourni, il spécifie la largeur des colonnes de date, qui sont centrées. Si `l' est donné, il spécifie le nombre de lignes que chaque semaine utilisera. Le résultat varie en fonction du premier jour de la semaine spécifié dans le constructeur ou défini par la méthode @ref{242a,,setfirstweekday()}.
@end deffn

@geindex formatmonthname() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatmonthname}@anchor{243e}
@deffn {Méthode} formatmonthname (theyear, themonth, width=0, withyear=True)

Return a string representing the month's name centered within the
specified `width'. If `withyear' is @code{True}, include the year in the
output. The `theyear' and `themonth' parameters specify the year
and month for the name to be formatted respectively.
@end deffn

@geindex prmonth() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar prmonth}@anchor{243f}
@deffn {Méthode} prmonth (theyear, themonth, w=0, l=0)

Affiche le calendrier d'un mois tel que renvoyé par @ref{243d,,formatmonth()}.
@end deffn

@geindex formatyear() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar formatyear}@anchor{2440}
@deffn {Méthode} formatyear (theyear, w=2, l=1, c=6, m=3)

Renvoie un calendrier de `m' colonnes pour une année entière sous forme de chaîne multi-ligne. Les paramètres facultatifs `w', `l' et `c' correspondent respectivement à la largeur de la colonne date, les lignes par semaines, le nombre d'espace entre les colonnes de mois. Le résultat varie en fonction du premier jour de la semaine spécifié dans le constructeur ou défini par la méthode @ref{242a,,setfirstweekday()}. La première année pour laquelle un calendrier peut être généré, dépend de la plateforme.
@end deffn

@geindex pryear() (méthode calendar.TextCalendar)
@anchor{library/calendar calendar TextCalendar pryear}@anchor{2441}
@deffn {Méthode} pryear (theyear, w=2, l=1, c=6, m=3)

Affiche le calendrier pour une année entière comme renvoyé par @ref{2440,,formatyear()}.
@end deffn
@end deffn

@geindex HTMLCalendar (classe dans calendar)
@anchor{library/calendar calendar HTMLCalendar}@anchor{b11}
@deffn {Classe} calendar.HTMLCalendar (firstweekday=0)

Cette classe peut être utilisée pour générer des calendriers HTML.

Les instances de @code{HTMLCalendar} utilisent les méthodes suivantes :

@geindex formatmonth() (méthode calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatmonth}@anchor{2442}
@deffn {Méthode} formatmonth (theyear, themonth, withyear=True)

Renvoie le calendrier d'un mois sous la forme d'une table HTML. Si `withyear' est vrai l'année sera inclue dans l'en-tête, sinon seul le nom du mois sera utilisé.
@end deffn

@geindex formatyear() (méthode calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatyear}@anchor{2443}
@deffn {Méthode} formatyear (theyear, width=3)

Renvoie le calendrier d'une année sous la forme d'une table HTML. `width' (par défaut à 3) spécifie le nombre de mois par ligne.
@end deffn

@geindex formatyearpage() (méthode calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatyearpage}@anchor{2444}
@deffn {Méthode} formatyearpage (theyear, width=3, css='calendar.css', encoding=None)

Renvoie le calendrier d'une année sous la forme d'une page HTML complète. `width' (par défaut à 3) spécifie le nombre de mois par ligne. `css' est le nom de la feuille de style en cascade à utiliser. @ref{660,,None} peut être passé si aucune feuille de style ne doit être utilisée. `encoding' spécifie l'encodage à utiliser pour les données de sortie (par défaut l'encodage par défaut du système).
@end deffn

@geindex formatmonthname() (méthode calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar formatmonthname}@anchor{2445}
@deffn {Méthode} formatmonthname (theyear, themonth, withyear=True)

Return a month name as an HTML table row. If `withyear' is true the year
will be included in the row, otherwise just the month name will be
used.
@end deffn

@code{HTMLCalendar} possède les attributs suivants que vous pouvez surcharger pour personnaliser les classes CSS utilisées par le calendrier :

@geindex cssclasses (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclasses}@anchor{2446}
@deffn {Attribut} cssclasses

Une liste de classes CSS utilisées pour chaque jour de la semaine. La liste par défaut de la classe est :

@example
cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
@end example

davantage de styles peuvent être ajoutés pour chaque jour :

@example
cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]
@end example

Notez que la longueur de cette liste doit être de sept éléments.
@end deffn

@geindex cssclass_noday (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_noday}@anchor{2447}
@deffn {Attribut} cssclass_noday

La classe CSS pour le jour de la semaine apparaissant dans le mois précédent ou à venir.


Ajouté dans la version 3.7.

@end deffn

@geindex cssclasses_weekday_head (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclasses_weekday_head}@anchor{2448}
@deffn {Attribut} cssclasses_weekday_head

Une liste de classes CSS utilisées pour les noms des jours de la semaine dans la ligne d'en-tête. Par défaut les mêmes que @ref{2446,,cssclasses}.


Ajouté dans la version 3.7.

@end deffn

@geindex cssclass_month_head (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_month_head}@anchor{2449}
@deffn {Attribut} cssclass_month_head

La classe CSS du mois en en-tête (utilisé par @ref{2445,,formatmonthname()}). La valeur par défaut est @code{"month"}.


Ajouté dans la version 3.7.

@end deffn

@geindex cssclass_month (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_month}@anchor{244a}
@deffn {Attribut} cssclass_month

La classe CSS pour la table du mois entière (utilisé par @ref{2442,,formatmonth()}). La valeur par défaut est @code{"month"}.


Ajouté dans la version 3.7.

@end deffn

@geindex cssclass_year (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_year}@anchor{244b}
@deffn {Attribut} cssclass_year

La classe CSS pour la table entière des tables de l'année (utilisé par @ref{2443,,formatyear()}). La valeur par défaut est @code{"year"}.


Ajouté dans la version 3.7.

@end deffn

@geindex cssclass_year_head (attribut calendar.HTMLCalendar)
@anchor{library/calendar calendar HTMLCalendar cssclass_year_head}@anchor{244c}
@deffn {Attribut} cssclass_year_head

La classe CSS pour l'en-tête de la table pour l'année entière (utilisé par @ref{2443,,formatyear()}). La valeur par défaut est @code{"year"}.


Ajouté dans la version 3.7.

@end deffn

Notez que même si le nommage ci-dessus des attributs de classe est au singulier (p. ex. @code{cssclass_month} @code{cssclass_noday}), on peut remplacer la seule classe CSS par une liste de classes CSS séparées par une espace, par exemple :

@example
"text-bold text-red"
@end example

Voici un exemple de comment peut être personnalisée @code{HTMLCalendar} :

@example
class CustomHTMLCal(calendar.HTMLCalendar):
    cssclasses = [style + " text-nowrap" for style in
                  calendar.HTMLCalendar.cssclasses]
    cssclass_month_head = "text-center month-head"
    cssclass_month = "text-center month"
    cssclass_year = "text-italic lead"
@end example
@end deffn

@geindex LocaleTextCalendar (classe dans calendar)
@anchor{library/calendar calendar LocaleTextCalendar}@anchor{72e}
@deffn {Classe} calendar.LocaleTextCalendar (firstweekday=0, locale=None)

Il est possible de passer un nom de locale au constructeur de la sous-classe de @ref{2438,,TextCalendar}. Elle renvoie les noms des mois et des jours de la semaine dans la locale précisée.
@end deffn

@geindex LocaleHTMLCalendar (classe dans calendar)
@anchor{library/calendar calendar LocaleHTMLCalendar}@anchor{72f}
@deffn {Classe} calendar.LocaleHTMLCalendar (firstweekday=0, locale=None)

Il est possible de passer un nom de locale au constructeur de la sous-classe de @ref{b11,,HTMLCalendar}. Elle renvoie les noms des mois et des jours de la semaine dans la locale précisée.
@end deffn

@cartouche
@quotation Note 
The constructor, @code{formatweekday()} and @code{formatmonthname()} methods
of these two classes temporarily change the @code{LC_TIME} locale to the given
`locale'. Because the current locale is a process-wide setting, they are
not thread-safe.
@end quotation
@end cartouche

Pour les calendriers texte simples ce module fournit les fonctions suivantes.

@geindex setfirstweekday() (dans le module calendar)
@anchor{library/calendar calendar setfirstweekday}@anchor{242a}
@deffn {Fonction} calendar.setfirstweekday (weekday)

Fixe le jour de la semaine (@code{0} pour lundi, @code{6} pour dimanche) qui débute chaque semaine. Les valeurs @ref{242c,,MONDAY}, @ref{244d,,TUESDAY}, @ref{244e,,WEDNESDAY}, @ref{244f,,THURSDAY}, @ref{2450,,FRIDAY}, @ref{2451,,SATURDAY}, et @ref{242d,,SUNDAY} sont fournies par commodité. Par exemple, pour fixer le premier jour de la semaine à dimanche :

@example
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
@end example
@end deffn

@geindex firstweekday() (dans le module calendar)
@anchor{library/calendar calendar firstweekday}@anchor{242f}
@deffn {Fonction} calendar.firstweekday ()

Renvoie le réglage courant pour le jour de la semaine débutant chaque semaine.
@end deffn

@geindex isleap() (dans le module calendar)
@anchor{library/calendar calendar isleap}@anchor{2452}
@deffn {Fonction} calendar.isleap (year)

Renvoie @ref{bfb,,True} si `year' est une année bissextile, sinon @ref{b25,,False}.
@end deffn

@geindex leapdays() (dans le module calendar)
@anchor{library/calendar calendar leapdays}@anchor{2453}
@deffn {Fonction} calendar.leapdays (y1, y2)

Renvoie le nombre d'années bissextiles dans la période de `y1' à `y2' (non inclus), où `y1' et `y2' sont des années.

Cette fonction marche pour les périodes couvrant un changement de siècle.
@end deffn

@geindex weekday() (dans le module calendar)
@anchor{library/calendar calendar weekday}@anchor{2454}
@deffn {Fonction} calendar.weekday (year, month, day)

Renvoie le jour de la semaine (@code{0} pour lundi) pour `year' (@code{1970}-- …), `month' (@code{1}--@code{12}), `day' (@code{1}--@code{31}).
@end deffn

@geindex weekheader() (dans le module calendar)
@anchor{library/calendar calendar weekheader}@anchor{2455}
@deffn {Fonction} calendar.weekheader (n)

Renvoie un en-tête contenant les jours de la semaine en abrégé. `n' spécifie la largeur en caractères pour un jour de la semaine.
@end deffn

@geindex monthrange() (dans le module calendar)
@anchor{library/calendar calendar monthrange}@anchor{2456}
@deffn {Fonction} calendar.monthrange (year, month)

Renvoie le jour de la semaine correspondant au premier jour du mois et le nombre de jours dans le mois, pour l'année `year' et le mois `month' spécifiés.
@end deffn

@geindex monthcalendar() (dans le module calendar)
@anchor{library/calendar calendar monthcalendar}@anchor{2457}
@deffn {Fonction} calendar.monthcalendar (year, month)

Renvoie une matrice représentant le calendrier d'un mois. Chaque ligne représente une semaine ; les jours en dehors du mois sont représentés par des zéros. Chaque semaine débute avec le lundi à moins de l'avoir modifié avec @ref{242a,,setfirstweekday()}.
@end deffn

@geindex prmonth() (dans le module calendar)
@anchor{library/calendar calendar prmonth}@anchor{2458}
@deffn {Fonction} calendar.prmonth (theyear, themonth, w=0, l=0)

Affiche le calendrier d'un mois tel que renvoyé par @ref{1525,,month()}.
@end deffn

@geindex month() (dans le module calendar)
@anchor{library/calendar calendar month}@anchor{1525}
@deffn {Fonction} calendar.month (theyear, themonth, w=0, l=0)

Returns a month's calendar in a multi-line string using the @ref{243d,,formatmonth()}
of the @ref{2438,,TextCalendar} class.
@end deffn

@geindex prcal() (dans le module calendar)
@anchor{library/calendar calendar prcal}@anchor{2459}
@deffn {Fonction} calendar.prcal (year, w=0, l=0, c=6, m=3)

Affiche le calendrier pour une année entière tel que renvoyé par @ref{14,,calendar()}.
@end deffn

@geindex calendar() (dans le module calendar)
@anchor{library/calendar calendar calendar}@anchor{245a}
@deffn {Fonction} calendar.calendar (year, w=2, l=1, c=6, m=3)

Returns a 3-column calendar for an entire year as a multi-line string using
the @ref{2440,,formatyear()} of the @ref{2438,,TextCalendar} class.
@end deffn

@geindex timegm() (dans le module calendar)
@anchor{library/calendar calendar timegm}@anchor{245b}
@deffn {Fonction} calendar.timegm (tuple)

Une fonction sans rapport mais pratique, qui prend un `n'-uplet temporel tel que celui renvoyé par la fonction @ref{119d,,gmtime()} dans le module @ref{ed,,time}, et renvoie la valeur d'horodatage Unix (`timestamp' en anglais) correspondante, en supposant une époque de 1970, et l'encodage POSIX. En fait, @ref{119d,,time.gmtime()} et @ref{245b,,timegm()} sont l'inverse l'un de l'autre.
@end deffn

Le module @ref{14,,calendar} exporte les attributs suivants :

@geindex day_name (dans le module calendar)
@anchor{library/calendar calendar day_name}@anchor{245c}
@deffn {Données} calendar.day_name

A sequence that represents the days of the week in the current locale,
where Monday is day number 0.

@example
>>> import calendar
>>> list(calendar.day_name)
['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
@end example
@end deffn

@geindex day_abbr (dans le module calendar)
@anchor{library/calendar calendar day_abbr}@anchor{245d}
@deffn {Données} calendar.day_abbr

A sequence that represents the abbreviated days of the week in the current locale,
where Mon is day number 0.

@example
>>> import calendar
>>> list(calendar.day_abbr)
['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
@end example
@end deffn

@geindex MONDAY (dans le module calendar)
@geindex TUESDAY (dans le module calendar)
@geindex WEDNESDAY (dans le module calendar)
@geindex THURSDAY (dans le module calendar)
@geindex FRIDAY (dans le module calendar)
@geindex SATURDAY (dans le module calendar)
@geindex SUNDAY (dans le module calendar)
@anchor{library/calendar calendar MONDAY}@anchor{242c}
@deffn {Données} calendar.MONDAY
@anchor{library/calendar calendar TUESDAY}@anchor{244d}
@deffnx {Données} calendar.TUESDAY
@anchor{library/calendar calendar WEDNESDAY}@anchor{244e}
@deffnx {Données} calendar.WEDNESDAY
@anchor{library/calendar calendar THURSDAY}@anchor{244f}
@deffnx {Données} calendar.THURSDAY
@anchor{library/calendar calendar FRIDAY}@anchor{2450}
@deffnx {Données} calendar.FRIDAY
@anchor{library/calendar calendar SATURDAY}@anchor{2451}
@deffnx {Données} calendar.SATURDAY
@anchor{library/calendar calendar SUNDAY}@anchor{242d}
@deffnx {Données} calendar.SUNDAY

Aliases for the days of the week,
where @code{MONDAY} is @code{0} and @code{SUNDAY} is @code{6}.


Ajouté dans la version 3.12.

@end deffn

@geindex Day (classe dans calendar)
@anchor{library/calendar calendar Day}@anchor{46c}
@deffn {Classe} calendar.Day

Enumeration defining days of the week as integer constants.
The members of this enumeration are exported to the module scope as
@ref{242c,,MONDAY} through @ref{242d,,SUNDAY}.


Ajouté dans la version 3.12.

@end deffn

@geindex month_name (dans le module calendar)
@anchor{library/calendar calendar month_name}@anchor{245e}
@deffn {Données} calendar.month_name

A sequence that represents the months of the year in the current locale.  This
follows normal convention of January being month number 1, so it has a length of
13 and @code{month_name[0]} is the empty string.

@example
>>> import calendar
>>> list(calendar.month_name)
['@w{'}, 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
@end example
@end deffn

@geindex month_abbr (dans le module calendar)
@anchor{library/calendar calendar month_abbr}@anchor{245f}
@deffn {Données} calendar.month_abbr

A sequence that represents the abbreviated months of the year in the current
locale.  This follows normal convention of January being month number 1, so it
has a length of 13 and  @code{month_abbr[0]} is the empty string.

@example
>>> import calendar
>>> list(calendar.month_abbr)
['@w{'}, 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
@end example
@end deffn

@geindex JANUARY (dans le module calendar)
@geindex FEBRUARY (dans le module calendar)
@geindex MARCH (dans le module calendar)
@geindex APRIL (dans le module calendar)
@geindex MAY (dans le module calendar)
@geindex JUNE (dans le module calendar)
@geindex JULY (dans le module calendar)
@geindex AUGUST (dans le module calendar)
@geindex SEPTEMBER (dans le module calendar)
@geindex OCTOBER (dans le module calendar)
@geindex NOVEMBER (dans le module calendar)
@geindex DECEMBER (dans le module calendar)
@anchor{library/calendar calendar JANUARY}@anchor{2ed}
@deffn {Données} calendar.JANUARY
@anchor{library/calendar calendar FEBRUARY}@anchor{2ee}
@deffnx {Données} calendar.FEBRUARY
@anchor{library/calendar calendar MARCH}@anchor{2460}
@deffnx {Données} calendar.MARCH
@anchor{library/calendar calendar APRIL}@anchor{2461}
@deffnx {Données} calendar.APRIL
@anchor{library/calendar calendar MAY}@anchor{2462}
@deffnx {Données} calendar.MAY
@anchor{library/calendar calendar JUNE}@anchor{2463}
@deffnx {Données} calendar.JUNE
@anchor{library/calendar calendar JULY}@anchor{2464}
@deffnx {Données} calendar.JULY
@anchor{library/calendar calendar AUGUST}@anchor{2465}
@deffnx {Données} calendar.AUGUST
@anchor{library/calendar calendar SEPTEMBER}@anchor{2466}
@deffnx {Données} calendar.SEPTEMBER
@anchor{library/calendar calendar OCTOBER}@anchor{2467}
@deffnx {Données} calendar.OCTOBER
@anchor{library/calendar calendar NOVEMBER}@anchor{2468}
@deffnx {Données} calendar.NOVEMBER
@anchor{library/calendar calendar DECEMBER}@anchor{2469}
@deffnx {Données} calendar.DECEMBER

Aliases for the months of the year,
where @code{JANUARY} is @code{1} and @code{DECEMBER} is @code{12}.


Ajouté dans la version 3.12.

@end deffn

@geindex Month (classe dans calendar)
@anchor{library/calendar calendar Month}@anchor{46b}
@deffn {Classe} calendar.Month

Enumeration defining months of the year as integer constants.
The members of this enumeration are exported to the module scope as
@ref{2ed,,JANUARY} through @ref{2469,,DECEMBER}.


Ajouté dans la version 3.12.

@end deffn

The @ref{14,,calendar} module defines the following exceptions:

@geindex IllegalMonthError
@anchor{library/calendar calendar IllegalMonthError}@anchor{1524}
@deffn {Exception} calendar.IllegalMonthError (month)

A subclass of @ref{1ff,,ValueError},
raised when the given month number is outside of the range 1-12 (inclusive).

@geindex month (attribut calendar.IllegalMonthError)
@anchor{library/calendar calendar IllegalMonthError month}@anchor{246a}
@deffn {Attribut} month

The invalid month number.
@end deffn
@end deffn

@geindex IllegalWeekdayError
@anchor{library/calendar calendar IllegalWeekdayError}@anchor{246b}
@deffn {Exception} calendar.IllegalWeekdayError (weekday)

A subclass of @ref{1ff,,ValueError},
raised when the given weekday number is outside of the range 0-6 (inclusive).

@geindex weekday (attribut calendar.IllegalWeekdayError)
@anchor{library/calendar calendar IllegalWeekdayError weekday}@anchor{246c}
@deffn {Attribut} weekday

The invalid weekday number.
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{30,,datetime}

Interface orientée objet pour les dates et les heures avec des fonctionnalités similaires au module @ref{ed,,time}.

@item Module @ref{ed,,time}

Fonctions bas niveau relatives au temps.
@end table


@menu
* Utilisation en ligne de commande.: Utilisation en ligne de commande. 

@end menu

@node Utilisation en ligne de commande,,,calendar --- General calendar-related functions
@anchor{library/calendar calendar-cli}@anchor{246d}@anchor{library/calendar command-line-usage}@anchor{246e}
@subsubsection Utilisation en ligne de commande.



Ajouté dans la version 2.5.


The @ref{14,,calendar} module can be executed as a script from the command line
to interactively print a calendar.

@example
python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t @{text,html@}]
                   [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
                   [-f FIRST_WEEKDAY] [year] [month]
@end example

For example, to print a calendar for the year 2000:

@example
$ python -m calendar 2000
                                  2000

      January                   February                   March
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                1  2          1  2  3  4  5  6             1  2  3  4  5
 3  4  5  6  7  8  9       7  8  9 10 11 12 13       6  7  8  9 10 11 12
10 11 12 13 14 15 16      14 15 16 17 18 19 20      13 14 15 16 17 18 19
17 18 19 20 21 22 23      21 22 23 24 25 26 27      20 21 22 23 24 25 26
24 25 26 27 28 29 30      28 29                     27 28 29 30 31
31

       April                      May                       June
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                1  2       1  2  3  4  5  6  7                1  2  3  4
 3  4  5  6  7  8  9       8  9 10 11 12 13 14       5  6  7  8  9 10 11
10 11 12 13 14 15 16      15 16 17 18 19 20 21      12 13 14 15 16 17 18
17 18 19 20 21 22 23      22 23 24 25 26 27 28      19 20 21 22 23 24 25
24 25 26 27 28 29 30      29 30 31                  26 27 28 29 30

        July                     August                  September
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                1  2          1  2  3  4  5  6                   1  2  3
 3  4  5  6  7  8  9       7  8  9 10 11 12 13       4  5  6  7  8  9 10
10 11 12 13 14 15 16      14 15 16 17 18 19 20      11 12 13 14 15 16 17
17 18 19 20 21 22 23      21 22 23 24 25 26 27      18 19 20 21 22 23 24
24 25 26 27 28 29 30      28 29 30 31               25 26 27 28 29 30
31

      October                   November                  December
Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su      Mo Tu We Th Fr Sa Su
                   1             1  2  3  4  5                   1  2  3
 2  3  4  5  6  7  8       6  7  8  9 10 11 12       4  5  6  7  8  9 10
 9 10 11 12 13 14 15      13 14 15 16 17 18 19      11 12 13 14 15 16 17
16 17 18 19 20 21 22      20 21 22 23 24 25 26      18 19 20 21 22 23 24
23 24 25 26 27 28 29      27 28 29 30               25 26 27 28 29 30 31
30 31
@end example

Les options suivantes sont acceptées :

@geindex option de ligne de commande calendar; --help
@geindex option de ligne de commande calendar; -h
@anchor{library/calendar cmdoption-calendar-help}@anchor{246f}@anchor{library/calendar cmdoption-calendar-h}@anchor{2470}
@deffn {Option} @w{-}@w{-}help, @w{-}h

Affiche un message d'aide et quitte.
@end deffn

@geindex option de ligne de commande calendar; --locale
@geindex option de ligne de commande calendar; -L
@anchor{library/calendar cmdoption-calendar-locale}@anchor{2471}@anchor{library/calendar cmdoption-calendar-L}@anchor{2472}
@deffn {Option} @w{-}@w{-}locale LOCALE, @w{-}L LOCALE

The locale to use for month and weekday names.
Defaults to English.
@end deffn

@geindex option de ligne de commande calendar; --encoding
@geindex option de ligne de commande calendar; -e
@anchor{library/calendar cmdoption-calendar-encoding}@anchor{2473}@anchor{library/calendar cmdoption-calendar-e}@anchor{2474}
@deffn {Option} @w{-}@w{-}encoding ENCODING, @w{-}e ENCODING

The encoding to use for output.
@ref{2473,,--encoding} is required if @ref{2471,,--locale} is set.
@end deffn

@geindex option de ligne de commande calendar; --type
@geindex option de ligne de commande calendar; -t
@anchor{library/calendar cmdoption-calendar-type}@anchor{2475}@anchor{library/calendar cmdoption-calendar-t}@anchor{2476}
@deffn {Option} @w{-}@w{-}type @{text,html@}, @w{-}t @{text,html@}

Print the calendar to the terminal as text,
or as an HTML document.
@end deffn

@geindex option de ligne de commande calendar; --first-weekday
@geindex option de ligne de commande calendar; -f
@anchor{library/calendar cmdoption-calendar-first-weekday}@anchor{2477}@anchor{library/calendar cmdoption-calendar-f}@anchor{2478}
@deffn {Option} @w{-}@w{-}first@w{-}weekday FIRST_WEEKDAY, @w{-}f FIRST_WEEKDAY

The weekday to start each week.
Must be a number between 0 (Monday) and 6 (Sunday).
Defaults to 0.


Ajouté dans la version 3.13.

@end deffn

@geindex option de ligne de commande calendar; year
@anchor{library/calendar cmdoption-calendar-arg-year}@anchor{2479}
@deffn {Option} year

The year to print the calendar for.
Defaults to the current year.
@end deffn

@geindex option de ligne de commande calendar; month
@anchor{library/calendar cmdoption-calendar-arg-month}@anchor{247a}
@deffn {Option} month

The month of the specified @ref{2479,,year} to print the calendar for.
Must be a number between 1 and 12,
and may only be used in text mode.
Defaults to printing a calendar for the full year.
@end deffn

`Text-mode options:'

@geindex option de ligne de commande calendar; --width
@geindex option de ligne de commande calendar; -w
@anchor{library/calendar cmdoption-calendar-width}@anchor{247b}@anchor{library/calendar cmdoption-calendar-w}@anchor{247c}
@deffn {Option} @w{-}@w{-}width WIDTH, @w{-}w WIDTH

The width of the date column in terminal columns.
The date is printed centred in the column.
Any value lower than 2 is ignored.
Defaults to 2.
@end deffn

@geindex option de ligne de commande calendar; --lines
@geindex option de ligne de commande calendar; -l
@anchor{library/calendar cmdoption-calendar-lines}@anchor{247d}@anchor{library/calendar cmdoption-calendar-l}@anchor{247e}
@deffn {Option} @w{-}@w{-}lines LINES, @w{-}l LINES

The number of lines for each week in terminal rows.
The date is printed top-aligned.
Any value lower than 1 is ignored.
Defaults to 1.
@end deffn

@geindex option de ligne de commande calendar; --spacing
@geindex option de ligne de commande calendar; -s
@anchor{library/calendar cmdoption-calendar-spacing}@anchor{247f}@anchor{library/calendar cmdoption-calendar-s}@anchor{2480}
@deffn {Option} @w{-}@w{-}spacing SPACING, @w{-}s SPACING

The space between months in columns.
Any value lower than 2 is ignored.
Defaults to 6.
@end deffn

@geindex option de ligne de commande calendar; --months
@geindex option de ligne de commande calendar; -m
@anchor{library/calendar cmdoption-calendar-months}@anchor{2481}@anchor{library/calendar cmdoption-calendar-m}@anchor{2482}
@deffn {Option} @w{-}@w{-}months MONTHS, @w{-}m MONTHS

The number of months printed per row.
Defaults to 3.
@end deffn

`HTML-mode options:'

@geindex option de ligne de commande calendar; --css
@geindex option de ligne de commande calendar; -c
@anchor{library/calendar cmdoption-calendar-css}@anchor{2483}@anchor{library/calendar cmdoption-calendar-c}@anchor{2484}
@deffn {Option} @w{-}@w{-}css CSS, @w{-}c CSS

The path of a CSS stylesheet to use for the calendar.
This must either be relative to the generated HTML,
or an absolute HTTP or @code{file:///} URL.
@end deffn

@node collections --- Container datatypes,collections abc --- Abstract Base Classes for Containers,calendar --- General calendar-related functions,Types de données
@anchor{library/collections doc}@anchor{2485}@anchor{library/collections collections-container-datatypes}@anchor{2486}@anchor{library/collections module-collections}@anchor{1d}
@subsection @code{collections} --- Container datatypes


@geindex module; collections

`Code source :' Lib/collections/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/collections/__init__.py}

@c from collections import *
@c import itertools
@c __name__ = '<doctest>'


__________________________________________________________________


Ce module implémente des types de données de conteneurs spécialisés qui apportent des alternatives aux conteneurs natifs de Python plus généraux @ref{253,,dict}, @ref{5fc,,list}, @ref{5c3,,set} et @ref{366,,tuple}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1c5,,namedtuple()}

@tab

fonction permettant de créer des sous-classes de @code{tuple} avec des champs nommés

@item

@ref{5c6,,deque}

@tab

conteneur se comportant comme une liste avec des ajouts et retraits rapides à chaque extrémité

@item

@ref{c0a,,ChainMap}

@tab

classe semblable aux dictionnaires qui crée une unique vue à partir de plusieurs dictionnaires

@item

@ref{107b,,Counter}

@tab

dict subclass for counting @ref{5fb,,hashable} objects

@item

@ref{5c5,,OrderedDict}

@tab

sous-classe de @code{dict} qui garde en mémoire l'ordre dans lequel les entrées ont été ajoutées

@item

@ref{119a,,defaultdict}

@tab

sous-classe de @code{dict} qui appelle une fonction de fabrication en cas de valeur manquante

@item

@ref{1922,,UserDict}

@tab

surcouche autour des objets dictionnaires pour faciliter l'héritage de @code{dict}

@item

@ref{1499,,UserList}

@tab

surcouche autour des objets listes pour faciliter l'héritage de @code{list}

@item

@ref{dc2,,UserString}

@tab

surcouche autour des objets chaînes de caractères pour faciliter l'héritage de @code{str}

@end multitable


@menu
* Objets ChainMap:: 
* Objets Counter:: 
* Objets deque:: 
* Objets defaultdict:: 
* namedtuple() ; fonction de construction pour n-uplets avec des champs nommés: namedtuple fonction de construction pour n-uplets avec des champs nommés. 
* Objets OrderedDict:: 
* Objets UserDict:: 
* Objets UserList:: 
* Objets UserString:: 

@end menu

@node Objets ChainMap,Objets Counter,,collections --- Container datatypes
@anchor{library/collections chainmap-objects}@anchor{2487}
@subsubsection Objets @code{ChainMap}



Ajouté dans la version 3.3.


Le module fournit une classe @ref{c0a,,ChainMap} afin de réunir rapidement plusieurs dictionnaires en une unique entité. Cela est souvent plus rapide que de créer un nouveau dictionnaire et d'effectuer plusieurs appels de @ref{1419,,update()}.

Cette classe peut être utilisée pour simuler des portées imbriquées, elle est aussi utile pour le `templating'.

@geindex ChainMap (classe dans collections)
@anchor{library/collections collections ChainMap}@anchor{c0a}
@deffn {Classe} collections.ChainMap (*maps)

Un objet @ref{c0a,,ChainMap} regroupe plusieurs dictionnaires (ou autres tableaux de correspondance) en une vue que l'on peut mettre à jour. Si le paramètre `maps' est vide, un dictionnaire vide est fourni de telle manière qu'une nouvelle chaîne possède toujours au moins un dictionnaire.

Les dictionnaires sous-jacents sont stockés dans une liste. Celle-ci est publique et peut être consultée ou mise à jour via l'attribut `maps'. Il n'y a pas d'autre état.

Les recherches s'effectuent successivement dans chaque dictionnaire jusqu'à la première clé correspondante. En revanche, les écritures, mises à jour et suppressions n'affectent que le premier dictionnaire.

Un objet @ref{c0a,,ChainMap} incorpore les dictionnaires sous-jacents par leur référence. Ainsi, si l'un d'eux est modifié, les changements affectent également la @ref{c0a,,ChainMap}.

Toutes les méthodes usuelles des dictionnaires sont gérées. De plus, cette classe fournit un attribut `maps', une méthode pour créer de nouveaux sous-contextes et une propriété pour accéder à tous les dictionnaires sous-jacents excepté le premier :

@geindex maps (attribut collections.ChainMap)
@anchor{library/collections collections ChainMap maps}@anchor{2488}
@deffn {Attribut} maps

Liste de dictionnaires éditable par l'utilisateur et classée selon l'ordre de recherche. Il s'agit de l'unique état stocké et elle peut être modifiée pour changer l'ordre de recherche. La liste doit toujours contenir au moins un dictionnaire.
@end deffn

@geindex new_child() (méthode collections.ChainMap)
@anchor{library/collections collections ChainMap new_child}@anchor{f0e}
@deffn {Méthode} new_child (m=None, **kwargs)

Renvoie un nouvel objet @ref{c0a,,ChainMap} contenant un nouveau dictionnaire suivi par tous les autres de l'instance actuelle. Si @code{m} est spécifié, il devient le nouveau dictionnaire au début de la liste ; sinon, un dictionnaire vide est utilisé, de telle manière qu'appeler @code{d.new_child()} équivaut à appeler @code{ChainMap(@{@}, *d.maps)}. Si des arguments sont passés par mot-clé, ils sont insérés comme de nouvelles entrées du dictionnaire ajouté. Cette méthode est utile pour créer des sous-contextes qui peuvent être mis à jour sans altérer les valeurs dans les dictionnaires parents.


Modifié dans la version 3.4: ajout du paramètre optionnel @code{m}.



Modifié dans la version 3.10: prise en charge des arguments par mot-clé.

@end deffn

@geindex parents (attribut collections.ChainMap)
@anchor{library/collections collections ChainMap parents}@anchor{2489}
@deffn {Attribut} parents

Propriété qui renvoie un nouvel objet @ref{c0a,,ChainMap} contenant tous les dictionnaires de l'instance actuelle hormis le premier. Cette propriété est utile pour ignorer le premier dictionnaire dans les recherches ; son utilisation rappelle le mot-clé @ref{1285,,nonlocal} (utilisé pour les @ref{1ec3,,portées imbriquées}), ou bien la fonction native @ref{4c5,,super()}. Une référence à @code{d.parents} est équivalente à : @code{ChainMap(*d.maps[1:])}.
@end deffn

Note, the iteration order of a @ref{c0a,,ChainMap} is determined by
scanning the mappings last to first:

@example
>>> baseline = @{'music': 'bach', 'art': 'rembrandt'@}
>>> adjustments = @{'art': 'van gogh', 'opera': 'carmen'@}
>>> list(ChainMap(adjustments, baseline))
['music', 'art', 'opera']
@end example

Cela produit le même ordre qu'une suite d'appels à @ref{1419,,dict.update()} en commençant par le dernier tableau de correspondances :

@example
>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']
@end example


Modifié dans la version 3.9: Ajout de la gestion des opérateurs @code{|} et @code{|=} tels que définis dans 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn


@subsubheading Voir aussi



@itemize *

@item 
La classe MultiContext@footnote{https://github.com/enthought/codetools/blob/4.0.0/codetools/contexts/multi_context.py} dans le package CodeTools@footnote{https://github.com/enthought/codetools} d'Enthought possède des options pour gérer l'écriture dans n'importe quel dictionnaire de la chaîne.

@item 
La classe de contexte de Django@footnote{https://github.com/django/django/blob/main/django/template/context.py} pour la création de modèles est une chaîne de dictionnaires en lecture seule. Elle comporte également des fonctionnalités d'ajouts et de retraits de contextes similaires à la méthode @ref{f0e,,new_child()} et à la propriété @ref{2489,,parents}.

@item 
The Nested Contexts recipe@footnote{https://code.activestate.com/recipes/577434-nested-contexts-a-chain-of-mapping-objects/} has options to control
whether writes and other mutations apply only to the first mapping or to
any mapping in the chain.

@item 
Une version grandement simplifiée de Chainmap en lecture seule@footnote{https://code.activestate.com/recipes/305268/}.
@end itemize


@menu
* Exemples et cas pratiques utilisant ChainMap:: 

@end menu

@node Exemples et cas pratiques utilisant ChainMap,,,Objets ChainMap
@anchor{library/collections chainmap-examples-and-recipes}@anchor{248a}
@subsubsection Exemples et cas pratiques utilisant @code{ChainMap}


Cette partie montre diverses approches afin de travailler avec les dictionnaires chaînés.

Exemple 1 : simulation de la chaîne de recherche interne de Python :

@example
import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))
@end example

Exemple 2 : spécification d'une hiérarchie pour les options : ligne de commande, variable d'environnement, valeurs par défaut :

@example
import os, argparse

defaults = @{'color': 'red', 'user': 'guest'@}

parser = argparse.ArgumentParser()
parser.add_argument('-u', '--user')
parser.add_argument('-c', '--color')
namespace = parser.parse_args()
command_line_args = @{k: v for k, v in vars(namespace).items() if v is not None@}

combined = ChainMap(command_line_args, os.environ, defaults)
print(combined['color'])
print(combined['user'])
@end example

Exemple 3 : modèles pour simuler des contextes imbriqués avec la classe @ref{c0a,,ChainMap} :

@example
c = ChainMap()        # Create root context
d = c.new_child()     # Create nested child context
e = c.new_child()     # Child of c, independent from d
e.maps[0]             # Current context dictionary -- like Python's locals()
e.maps[-1]            # Root context -- like Python's globals()
e.parents             # Enclosing context chain -- like Python's nonlocals

d['x'] = 1            # Set value in current context
d['x']                # Get first key in the chain of contexts
del d['x']            # Delete from current context
list(d)               # All nested values
k in d                # Check all nested values
len(d)                # Number of nested values
d.items()             # All nested items
dict(d)               # Flatten into a regular dictionary
@end example

La classe @ref{c0a,,ChainMap} ne met à jour (écriture et suppression) que le premier dictionnaire de la chaîne, alors qu'une recherche inspecte toute la chaîne. Cependant, si l'on veut effectuer des écritures ou suppressions en profondeur, on peut facilement faire une sous-classe qui met à jour les clés trouvées de la chaîne en profondeur :

@example
class DeepChainMap(ChainMap):
    'Variant of ChainMap that allows direct updates to inner scopes'

    def __setitem__(self, key, value):
        for mapping in self.maps:
            if key in mapping:
                mapping[key] = value
                return
        self.maps[0][key] = value

    def __delitem__(self, key):
        for mapping in self.maps:
            if key in mapping:
                del mapping[key]
                return
        raise KeyError(key)

>>> d = DeepChainMap(@{'zebra': 'black'@}, @{'elephant': 'blue'@}, @{'lion': 'yellow'@})
>>> d['lion'] = 'orange'         # update an existing key two levels down
>>> d['snake'] = 'red'           # new keys get added to the topmost dict
>>> del d['elephant']            # remove an existing key one level down
>>> d                            # display result
DeepChainMap(@{'zebra': 'black', 'snake': 'red'@}, @{@}, @{'lion': 'orange'@})
@end example

@node Objets Counter,Objets deque,Objets ChainMap,collections --- Container datatypes
@anchor{library/collections counter-objects}@anchor{248b}
@subsubsection Objets @code{Counter}


Ce module fournit un outil pour effectuer rapidement et facilement des dénombrements. Par exemple :

@example
>>> # Tally occurrences of words in a list
>>> cnt = Counter()
>>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
...     cnt[word] += 1
...
>>> cnt
Counter(@{'blue': 3, 'red': 2, 'green': 1@})

>>> # Find the ten most common words in Hamlet
>>> import re
>>> words = re.findall(r'\w+', open('hamlet.txt').read().lower())
>>> Counter(words).most_common(10)
[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),
 ('you', 554),  ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]
@end example

@geindex Counter (classe dans collections)
@anchor{library/collections collections Counter}@anchor{107b}
@deffn {Classe} collections.Counter ([iterable-or-mapping])

A @ref{107b,,Counter} is a @ref{253,,dict} subclass for counting @ref{5fb,,hashable} objects.
It is a collection where elements are stored as dictionary keys
and their counts are stored as dictionary values.  Counts are allowed to be
any integer value including zero or negative counts.  The @ref{107b,,Counter}
class is similar to bags or multisets in other languages.

Les éléments sont comptés à partir d'un itérable ou initialisés à partir d'un autre dictionnaire (ou compteur) :

@example
>>> c = Counter()                           # a new, empty counter
>>> c = Counter('gallahad')                 # a new counter from an iterable
>>> c = Counter(@{'red': 4, 'blue': 2@})      # a new counter from a mapping
>>> c = Counter(cats=4, dogs=8)             # a new counter from keyword args
@end example

Les objets Counter ont une interface de dictionnaire, à l'exception près qu'ils renvoient zéro au lieu de lever une exception @ref{33a,,KeyError} pour des éléments manquants :

@example
>>> c = Counter(['eggs', 'ham'])
>>> c['bacon']                              # count of a missing element is zero
0
@end example

Mettre un comptage à zéro pour un élément ne le retire pas de l'objet Counter. Il faut utiliser @code{del} pour le supprimer complètement :

@example
>>> c['sausage'] = 0                        # counter entry with a zero count
>>> del c['sausage']                        # del actually removes the entry
@end example


Ajouté dans la version 3.1.



Modifié dans la version 3.7: As a @ref{253,,dict} subclass, @ref{107b,,Counter}
inherited the capability to remember insertion order.  Math operations
on `Counter' objects also preserve order.  Results are ordered
according to when an element is first encountered in the left operand
and then by the order encountered in the right operand.


Counter objects support additional methods beyond those available for all
dictionaries:

@geindex elements() (méthode collections.Counter)
@anchor{library/collections collections Counter elements}@anchor{12e2}
@deffn {Méthode} elements ()

Renvoie un itérateur sur chaque élément en le répétant autant de fois que la valeur du compteur associé. Les éléments sont renvoyés dans l'ordre selon lequel ils sont rencontrés pour la première fois. Si le comptage d'un élément est strictement inférieur à 1, alors @ref{12e2,,elements()} l'ignore.

@example
>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> sorted(c.elements())
['a', 'a', 'a', 'a', 'b', 'b']
@end example
@end deffn

@geindex most_common() (méthode collections.Counter)
@anchor{library/collections collections Counter most_common}@anchor{12e1}
@deffn {Méthode} most_common ([n])

Renvoie une liste des `n' éléments les plus nombreux et leur valeur respective dans l'ordre décroissant. Si `n' n'est pas fourni ou vaut @code{None}, @ref{12e1,,most_common()} renvoie `tous' les éléments du compteur. Les éléments qui ont le même nombre d'occurrences sont ordonnés par l'ordre selon lequel ils ont été rencontrés pour la première fois :

@example
>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
@end example
@end deffn

@geindex subtract() (méthode collections.Counter)
@anchor{library/collections collections Counter subtract}@anchor{11bb}
@deffn {Méthode} subtract ([iterable-or-mapping])

Les éléments sont soustraits à partir d'un itérable ou d'un autre dictionnaire (ou compteur). Cette méthode se comporte comme @ref{1419,,dict.update()} mais soustrait les nombres d'occurrences au lieu de les remplacer. Les entrées et sorties peuvent être négatives ou nulles.

@example
>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> d = Counter(a=1, b=2, c=3, d=4)
>>> c.subtract(d)
>>> c
Counter(@{'a': 3, 'b': 0, 'c': -3, 'd': -6@})
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex total() (méthode collections.Counter)
@anchor{library/collections collections Counter total}@anchor{248c}
@deffn {Méthode} total ()

Calcule la somme totale des nombres d'occurrences.

@example
>>> c = Counter(a=10, b=5, c=0)
>>> c.total()
15
@end example


Ajouté dans la version 3.10.

@end deffn

Les méthodes usuelles des dictionnaires sont disponibles pour les objets @ref{107b,,Counter} à l'exception de deux méthodes qui fonctionnent différemment pour les compteurs.

@geindex fromkeys() (méthode collections.Counter)
@anchor{library/collections collections Counter fromkeys}@anchor{248d}
@deffn {Méthode} fromkeys (iterable)

Cette méthode de classe n'est pas implémentée pour les objets @ref{107b,,Counter}.
@end deffn

@geindex update() (méthode collections.Counter)
@anchor{library/collections collections Counter update}@anchor{248e}
@deffn {Méthode} update ([iterable-or-mapping])

Les éléments sont comptés à partir d'un itérable ou ajoutés d'un autre dictionnaire (ou compteur). Cette méthode se comporte comme @ref{1419,,dict.update()} mais additionne les nombres d'occurrences au lieu de les remplacer. De plus, l'itérable doit être une séquence d'éléments et non une séquence de paires @code{(clé, valeur)}.
@end deffn
@end deffn

Les compteurs prennent en charge les comparaisons riches pour les tests d'égalité ainsi que d'inclusion du membre gauche dans le membre droite et réciproquement, avec les opérateurs @code{==}, @code{!=}, @code{<}, @code{<=}, @code{>} et @code{>=}. Les éléments dont le nombre d'occurrences est à zéro sont ignorés. Par exemple, on a @code{Counter(a=1) == Counter(a=1, b=0)}.


Modifié dans la version 3.10: ajout des comparaisons riches.



Modifié dans la version 3.10: les éléments dont le nombre d'occurrences est à zéro sont désormais ignorés dans les tests d'égalité. On avait auparavant @code{Counter(a=3) != Counter(a=3, b=0)}.


Opérations usuelles sur les objets @ref{107b,,Counter} :

@example
c.total()                       # total of all counts
c.clear()                       # reset all counts
list(c)                         # list unique elements
set(c)                          # convert to a set
dict(c)                         # convert to a regular dictionary
c.items()                       # access the (elem, cnt) pairs
Counter(dict(list_of_pairs))    # convert from a list of (elem, cnt) pairs
c.most_common()[:-n-1:-1]       # n least common elements
+c                              # remove zero and negative counts
@end example

Several mathematical operations are provided for combining @ref{107b,,Counter}
objects to produce multisets (counters that have counts greater than zero).
Addition and subtraction combine counters by adding or subtracting the counts
of corresponding elements.  Intersection and union return the minimum and
maximum of corresponding counts.  Equality and inclusion compare
corresponding counts.  Each operation can accept inputs with signed
counts, but the output will exclude results with counts of zero or less.

@example
>>> c = Counter(a=3, b=1)
>>> d = Counter(a=1, b=2)
>>> c + d                       # add two counters together:  c[x] + d[x]
Counter(@{'a': 4, 'b': 3@})
>>> c - d                       # subtract (keeping only positive counts)
Counter(@{'a': 2@})
>>> c & d                       # intersection:  min(c[x], d[x])
Counter(@{'a': 1, 'b': 1@})
>>> c | d                       # union:  max(c[x], d[x])
Counter(@{'a': 3, 'b': 2@})
>>> c == d                      # equality:  c[x] == d[x]
False
>>> c <= d                      # inclusion:  c[x] <= d[x]
False
@end example

L'addition et la soustraction unaires (avec un seul terme) sont des raccourcis pour respectivement additionner un compteur avec un compteur vide ou et pour retrancher un compteur d'un compteur vide.

@example
>>> c = Counter(a=2, b=-4)
>>> +c
Counter(@{'a': 2@})
>>> -c
Counter(@{'b': 4@})
@end example


Ajouté dans la version 3.3: Ajout de la gestion des additions et soustractions unaires, et des remplacements dans les multiensembles.


@cartouche
@quotation Note 
Les compteurs ont été conçus essentiellement pour fonctionner avec des entiers naturels pour représenter les dénombrements en cours ; cependant, les cas d'utilisation nécessitant d'autres types ou des valeurs négatives n'ont pas été écartés. Pour vous aider dans ces cas particuliers, cette section documente la plage minimale et les restrictions de type.


@itemize *

@item 
La classe @ref{107b,,Counter} est elle-même une sous-classe de dictionnaire sans restriction particulière sur ces clés ou valeurs. Les valeurs ont vocation à être des nombres représentants des comptages, mais il est `possible' de stocker n'importe quel type de valeur.

@item 
La méthode @ref{12e1,,most_common()} exige uniquement que les valeurs soient ordonnables.

@item 
Les opérations de remplacement telles que @code{c[key] += 1} exigent une valeur dont le type gère l'addition et la soustraction. Cela inclut donc les fractions, les flottants et les décimaux, y compris négatifs. Il en va de même pour @ref{248e,,update()} et @code{substract()} qui acceptent des valeurs négatives ou nulles dans les entrées et sorties.

@item 
Les méthodes de multiensembles sont uniquement conçues pour les cas d'utilisation avec des valeurs positives. Les entrées peuvent contenir des valeurs négatives ou nulles, mais seules les sorties avec des valeurs positives sont créées. Il n'y a pas de restriction de type, mais les types des valeurs doivent gérer l'addition, la soustraction et la comparaison.

@item 
La méthode @ref{12e2,,elements()} exige des valeurs entières et ignore les valeurs négatives ou nulles.
@end itemize
@end quotation
@end cartouche


@subsubheading Voir aussi



@itemize *

@item 
Bag class@footnote{https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html} dans Smalltalk.

@item 
L'article Wikipédia sur les multiensembles@footnote{https://fr.wikipedia.org/wiki/Multiensemble} sur Wikipédia (ou l'article en anglais@footnote{https://en.wikipedia.org/wiki/Multiset}).

@item 
Des guides et exemples à propos des multiensembles en C++@footnote{http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm}.

@item 
Pour les opérations mathématiques sur les multiensembles et leurs applications, voir `Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19'.

@item 
Pour lister tous les multiensembles distincts de même taille parmi un ensemble donné d'éléments, voir @ref{125f,,itertools.combinations_with_replacement()} :

@example
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
@end example
@end itemize


@node Objets deque,Objets defaultdict,Objets Counter,collections --- Container datatypes
@anchor{library/collections deque-objects}@anchor{248f}
@subsubsection Objets @code{deque}


@geindex deque (classe dans collections)
@anchor{library/collections collections deque}@anchor{5c6}
@deffn {Classe} collections.deque ([iterable[, maxlen]])

Renvoie un nouvel objet `deque' initialisé de gauche à droite (en utilisant @ref{2490,,append()}) avec les données d'`iterable'. Si `iterable' n'est pas spécifié, alors la nouvelle `deque' est vide.

Deques are a generalization of stacks and queues (the name is pronounced "deck"
and is short for "double-ended queue").  Deques support thread-safe, memory
efficient appends and pops from either side of the deque with approximately the
same `O'(1) performance in either direction.

Though @ref{5fc,,list} objects support similar operations, they are optimized for
fast fixed-length operations and incur `O'(`n') memory movement costs for
@code{pop(0)} and @code{insert(0, v)} operations which change both the size and
position of the underlying data representation.

Si `maxlen' n'est pas spécifié ou vaut `None', les `deques' peuvent atteindre une taille arbitraire. Sinon, la `deque' est limitée par cette taille maximale. Une fois que celle-ci est atteinte, un ajout d'un ou plusieurs éléments engendre la suppression du nombre correspondant d'éléments à l'autre extrémité de la `deque'. Les `deques' à longueur limitée apportent des fonctionnalités similaires au filtre @code{tail} d'Unix. Elles sont aussi utiles pour le suivi de transactions et autres lots de données où seule l'activité récente est intéressante.

Les objets `deques' gèrent les méthodes suivantes :

@geindex append() (méthode collections.deque)
@anchor{library/collections collections deque append}@anchor{2490}
@deffn {Méthode} append (x)

Ajoute `x' à l'extrémité droite de la `deque'.
@end deffn

@geindex appendleft() (méthode collections.deque)
@anchor{library/collections collections deque appendleft}@anchor{2491}
@deffn {Méthode} appendleft (x)

Ajoute `x' à l'extrémité gauche de la `deque'.
@end deffn

@geindex clear() (méthode collections.deque)
@anchor{library/collections collections deque clear}@anchor{2492}
@deffn {Méthode} clear ()

Supprime tous les éléments de la `deque' et la laisse avec une longueur de 0.
@end deffn

@geindex copy() (méthode collections.deque)
@anchor{library/collections collections deque copy}@anchor{dc1}
@deffn {Méthode} copy ()

Crée une copie superficielle de la `deque'.


Ajouté dans la version 3.5.

@end deffn

@geindex count() (méthode collections.deque)
@anchor{library/collections collections deque count}@anchor{11bd}
@deffn {Méthode} count (x)

Compte le nombre d'éléments de la `deque' égaux à `x'.


Ajouté dans la version 3.2.

@end deffn

@geindex extend() (méthode collections.deque)
@anchor{library/collections collections deque extend}@anchor{2493}
@deffn {Méthode} extend (iterable)

Étend la `deque' en ajoutant les éléments de l'itérable en argument à son extrémité droite.
@end deffn

@geindex extendleft() (méthode collections.deque)
@anchor{library/collections collections deque extendleft}@anchor{2494}
@deffn {Méthode} extendleft (iterable)

Étend la `deque' en ajoutant les éléments d'`iterable' à son extrémité gauche. Dans ce cas, notez que la série d'ajouts inverse l'ordre des éléments de l'argument itérable.
@end deffn

@geindex index() (méthode collections.deque)
@anchor{library/collections collections deque index}@anchor{dbf}
@deffn {Méthode} index (x[, start[, stop]])

Renvoie la position de `x' dans la `deque' (à partir de `start' inclus et jusqu'à `stop' exclus). Renvoie la première correspondance ou lève @ref{1ff,,ValueError} si aucune n'est trouvée.


Ajouté dans la version 3.5.

@end deffn

@geindex insert() (méthode collections.deque)
@anchor{library/collections collections deque insert}@anchor{dc0}
@deffn {Méthode} insert (i, x)

Insère `x' dans la `deque' à la position `i'.

Si une insertion provoque un dépassement de la taille limitée d'une `deque', alors elle lève une exception @ref{14eb,,IndexError}.


Ajouté dans la version 3.5.

@end deffn

@geindex pop() (méthode collections.deque)
@anchor{library/collections collections deque pop}@anchor{2495}
@deffn {Méthode} pop ()

Retire et renvoie un élément de l'extrémité droite de la `deque'. S'il n'y a aucun élément, lève une exception @ref{14eb,,IndexError}.
@end deffn

@geindex popleft() (méthode collections.deque)
@anchor{library/collections collections deque popleft}@anchor{2496}
@deffn {Méthode} popleft ()

Retire et renvoie un élément de l'extrémité gauche de la `deque'. S'il n'y a aucun élément, lève une exception @ref{14eb,,IndexError}.
@end deffn

@geindex remove() (méthode collections.deque)
@anchor{library/collections collections deque remove}@anchor{1899}
@deffn {Méthode} remove (value)

Supprime la première occurrence de `value'. Si aucune occurrence n'est trouvée, lève une exception @ref{1ff,,ValueError}.
@end deffn

@geindex reverse() (méthode collections.deque)
@anchor{library/collections collections deque reverse}@anchor{11be}
@deffn {Méthode} reverse ()

Inverse le sens des éléments de la `deque' sans créer de copie et renvoie @code{None}.


Ajouté dans la version 3.2.

@end deffn

@geindex rotate() (méthode collections.deque)
@anchor{library/collections collections deque rotate}@anchor{1864}
@deffn {Méthode} rotate (n=1)

Décale les éléments de la `deque' de `n' places vers la droite (le dernier élément revient au début). Si `n' est négatif, décale vers la gauche.

Quand la `deque' n'est pas vide, un décalage d'une place vers la droite équivaut à @code{d.appendleft(d.pop())} et un décalage d'une place vers la gauche est équivalent à @code{d.append(d.popleft())}.
@end deffn

Les objets `deques' fournissent également un attribut en lecture seule :

@geindex maxlen (attribut collections.deque)
@anchor{library/collections collections deque maxlen}@anchor{12e3}
@deffn {Attribut} maxlen

La taille maximale d'une `deque', ou @code{None} si illimitée.


Ajouté dans la version 3.1.

@end deffn
@end deffn

In addition to the above, deques support iteration, pickling, @code{len(d)},
@code{reversed(d)}, @code{copy.copy(d)}, @code{copy.deepcopy(d)}, membership testing with
the @ref{2e8,,in} operator, and subscript references such as @code{d[0]} to access
the first element.  Indexed access is `O'(1) at both ends but slows to `O'(`n') in
the middle.  For fast random access, use lists instead.

Depuis la version 3.5, les `deques' gèrent @code{__add__()}, @code{__mul__()} et @code{__imul__()}.

Exemple :

@example
>>> from collections import deque
>>> d = deque('ghi')                 # make a new deque with three items
>>> for elem in d:                   # iterate over the deque's elements
...     print(elem.upper())
G
H
I

>>> d.append('j')                    # add a new entry to the right side
>>> d.appendleft('f')                # add a new entry to the left side
>>> d                                # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])

>>> d.pop()                          # return and remove the rightmost item
'j'
>>> d.popleft()                      # return and remove the leftmost item
'f'
>>> list(d)                          # list the contents of the deque
['g', 'h', 'i']
>>> d[0]                             # peek at leftmost item
'g'
>>> d[-1]                            # peek at rightmost item
'i'

>>> list(reversed(d))                # list the contents of a deque in reverse
['i', 'h', 'g']
>>> 'h' in d                         # search the deque
True
>>> d.extend('jkl')                  # add multiple elements at once
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> d.rotate(1)                      # right rotation
>>> d
deque(['l', 'g', 'h', 'i', 'j', 'k'])
>>> d.rotate(-1)                     # left rotation
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])

>>> deque(reversed(d))               # make a new deque in reverse order
deque(['l', 'k', 'j', 'i', 'h', 'g'])
>>> d.clear()                        # empty the deque
>>> d.pop()                          # cannot pop from an empty deque
Traceback (most recent call last):
    File "<pyshell#6>", line 1, in -toplevel-
        d.pop()
IndexError: pop from an empty deque

>>> d.extendleft('abc')              # extendleft() reverses the input order
>>> d
deque(['c', 'b', 'a'])
@end example

@menu
* Cas pratiques utilisant deque:: 

@end menu

@node Cas pratiques utilisant deque,,,Objets deque
@anchor{library/collections deque-recipes}@anchor{2497}
@subsubsection Cas pratiques utilisant @code{deque}


Cette partie montre diverses approches afin de travailler avec les `deques'.

Les `deques' à taille limitée apportent une fonctionnalité similaire au filtre @code{tail} d'Unix :

@example
def tail(filename, n=10):
    'Return the last n lines of a file'
    with open(filename) as f:
        return deque(f, n)
@end example

Une autre approche d'utilisation des `deques' est de maintenir une séquence d'éléments récemment ajoutés en les ajoutant à droite et en retirant les anciens par la gauche :

@example
def moving_average(iterable, n=3):
    # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0
    # https://en.wikipedia.org/wiki/Moving_average
    it = iter(iterable)
    d = deque(itertools.islice(it, n-1))
    d.appendleft(0)
    s = sum(d)
    for elem in it:
        s += elem - d.popleft()
        d.append(elem)
        yield s / n
@end example

Un ordonnancement en round-robin@footnote{https://fr.wikipedia.org/wiki/Round-robin_(informatique)} peut être implémenté avec des entrées itérateurs stockées dans une @ref{5c6,,deque}. Les valeurs sont produites par l'itérateur actif en position zéro. Si cet itérateur est épuisé, il peut être retiré avec la méthode @ref{2496,,popleft()} ; ou bien il peut être remis à la fin avec la méthode @code{rotate()} :

@example
def roundrobin(*iterables):
    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
    iterators = deque(map(iter, iterables))
    while iterators:
        try:
            while True:
                yield next(iterators[0])
                iterators.rotate(-1)
        except StopIteration:
            # Remove an exhausted iterator.
            iterators.popleft()
@end example

La méthode @ref{1864,,rotate()} apporte une façon d'implémenter la sélection d'intervalle (`slicing') et les suppressions pour les @code{deques}. Par exemple, une implémentation de @code{del d[n]} en Python pur utilise la méthode @code{rotate()} pour mettre en position les éléments à éjecter :

@example
def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)
@end example

Pour implémenter le `slicing' pour les @ref{5c6,,deques}, il est possible d'utiliser une approche similaire en appliquant @ref{1864,,rotate()} afin d'apporter un élément cible à l'extrémité gauche de la `deque'. On éjecte les anciennes entrées avec @ref{2496,,popleft()} et on ajoute les nouvelles avec @ref{2493,,extend()}, puis on inverse la rotation. Il est aisé d'implémenter les manipulations des piles inspirées du Forth telles que @code{dup}, @code{drop}, @code{swap}, @code{over}, @code{pick}, @code{rot} et @code{roll}.

@node Objets defaultdict,namedtuple fonction de construction pour n-uplets avec des champs nommés,Objets deque,collections --- Container datatypes
@anchor{library/collections defaultdict-objects}@anchor{2498}
@subsubsection Objets @code{defaultdict}


@geindex defaultdict (classe dans collections)
@anchor{library/collections collections defaultdict}@anchor{119a}
@deffn {Classe} collections.defaultdict (default_factory=None, /[, ...])

Renvoie un nouvel objet qui se comporte comme un dictionnaire. @ref{119a,,defaultdict} est une sous-classe de la classe native @ref{253,,dict}. Elle surcharge une méthode et ajoute une variable d'instance modifiable. Les autres fonctionnalités sont les mêmes que celles des objets @ref{253,,dict} et ne sont pas documentées ici.

Le premier argument fournit la valeur initiale de l'attribut @ref{2499,,default_factory} qui doit être un objet appelable sans paramètre ou @code{None}, sa valeur par défaut. Tous les autres arguments sont traités comme si on les passait au constructeur de @ref{253,,dict}, y compris les arguments nommés.

En plus des opérations usuelles de @ref{253,,dict}, les objets @ref{119a,,defaultdict} gèrent les méthodes supplémentaires suivantes :

@geindex __missing__() (méthode collections.defaultdict)
@anchor{library/collections collections defaultdict __missing__}@anchor{249a}
@deffn {Méthode} __missing__ (key)

Si l'attribut @ref{2499,,default_factory} est @code{None}, lève une exception @ref{33a,,KeyError} avec `key' comme argument.

Si @code{default_fatory} ne vaut pas @code{None}, cet attribut est appelé sans argument pour fournir une valeur par défaut pour la `key' demandée. Cette valeur est insérée dans le dictionnaire avec pour clé `key' et est renvoyée.

Si appeler @ref{2499,,default_factory} lève une exception, celle-ci est transmise inchangée.

This method is called by the @ref{280,,__getitem__()} method of the
@ref{253,,dict} class when the requested key is not found; whatever it
returns or raises is then returned or raised by @ref{280,,__getitem__()}.

Note that @ref{249a,,__missing__()} is `not' called for any operations besides
@ref{280,,__getitem__()}. This means that @code{get()} will, like normal
dictionaries, return @code{None} as a default rather than using
@ref{2499,,default_factory}.
@end deffn

Les objets @ref{119a,,defaultdict} gèrent la variable d'instance :

@geindex default_factory (attribut collections.defaultdict)
@anchor{library/collections collections defaultdict default_factory}@anchor{2499}
@deffn {Attribut} default_factory

Cet attribut est utilisé par la méthode @ref{249a,,__missing__()} ; il est initialisé par le premier argument passé au constructeur, s'il est spécifié, sinon par @code{None}.
@end deffn


Modifié dans la version 3.9: ajout des opérateurs fusion (@code{|}) et mise-à-jour (@code{|=}) tels que définis dans 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn

@menu
* Exemples utilisant defaultdict:: 

@end menu

@node Exemples utilisant defaultdict,,,Objets defaultdict
@anchor{library/collections defaultdict-examples}@anchor{249b}
@subsubsection Exemples utilisant @code{defaultdict}


Utiliser @ref{5fc,,list} comme @ref{2499,,default_factory} facilite le regroupement d'une séquence de paires clé-valeur en un dictionnaire de listes :

@example
>>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
>>> d = defaultdict(list)
>>> for k, v in s:
...     d[k].append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
@end example

When each key is encountered for the first time, it is not already in the
mapping; so an entry is automatically created using the @ref{2499,,default_factory}
function which returns an empty @ref{5fc,,list}.  The @code{list.append()}
operation then attaches the value to the new list.  When keys are encountered
again, the look-up proceeds normally (returning the list for that key) and the
@code{list.append()} operation adds another value to the list. This technique is
simpler and faster than an equivalent technique using @ref{1062,,dict.setdefault()}:

@example
>>> d = @{@}
>>> for k, v in s:
...     d.setdefault(k, []).append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
@end example

Utiliser @ref{254,,int} comme @ref{2499,,default_factory} rend la classe @ref{119a,,defaultdict} pratique pour le comptage (comme un sac ou multi-ensemble dans d'autres langages) :

@example
>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
...     d[k] += 1
...
>>> sorted(d.items())
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]
@end example

Quand une lettre est rencontrée pour la première fois, elle n'est pas dans le dictionnaire, donc la fonction @ref{2499,,default_factory} appelle @ref{254,,int()} pour mettre un nouveau compteur à zéro. L'incrémentation augmente ensuite le comptage pour chaque lettre.

La fonction @ref{254,,int()} qui retourne toujours zéro est simplement une fonction constante particulière. Un moyen plus flexible et rapide de créer une fonction constante est d'utiliser une fonction lambda qui peut fournir n'importe quelle valeur constante (pas seulement zéro) :

@example
>>> def constant_factory(value):
...     return lambda: value
...
>>> d = defaultdict(constant_factory('<missing>'))
>>> d.update(name='John', action='ran')
>>> '%(name)s %(action)s to %(object)s' % d
'John ran to <missing>'
@end example

Utiliser @ref{5c3,,set} comme @ref{2499,,default_factory} rend la classe @ref{119a,,defaultdict} pratique pour créer un dictionnaire d'ensembles :

@example
>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
>>> d = defaultdict(set)
>>> for k, v in s:
...     d[k].add(v)
...
>>> sorted(d.items())
[('blue', @{2, 4@}), ('red', @{1, 3@})]
@end example

@node namedtuple fonction de construction pour n-uplets avec des champs nommés,Objets OrderedDict,Objets defaultdict,collections --- Container datatypes
@anchor{library/collections namedtuple-factory-function-for-tuples-with-named-fields}@anchor{249c}
@subsubsection @code{namedtuple()} : fonction de construction pour `n'-uplets avec des champs nommés


Les `n'-uplets nommés assignent une signification à chacun de leur élément, ce qui rend le code plus lisible et explicite. Ils peuvent être utilisés partout où les `n'-uplets natifs sont utilisés, et ils ajoutent la possibilité d'accéder à leurs champs grâce à leur nom au lieu de leur index de position.

@geindex namedtuple() (dans le module collections)
@anchor{library/collections collections namedtuple}@anchor{1c5}
@deffn {Fonction} collections.namedtuple (typename, field_names, *, rename=False, defaults=None, module=None)

Renvoie une nouvelle sous-classe de @code{tuple} appelée `typename'. Elle est utilisée pour créer des objets se comportant comme les `n'-uplets qui ont des champs accessibles par recherche d'attribut en plus d'être indexables et itérables. Les instances de cette sous-classe possèdent aussi une `docstring' explicite (avec `type_name' et les `field_names') et une méthode @code{__repr__()} pratique qui liste le contenu du `n'-uplet au format @code{nom=valeur}.

`field_names' peut être une séquence de chaînes de caractères telle que @code{['x', 'y']} ou bien une unique chaîne de caractères où les noms de champs sont séparés par un espace et/ou une virgule, par exemple @code{'x y'} ou @code{'x, y'}.

N'importe quel identifiant Python peut être utilisé pour un nom de champ hormis ceux commençant par un tiret bas. Les identifiants valides peuvent contenir des lettres, des chiffres (sauf en première position) et des tirets bas (sauf en première position). Un identifiant ne peut pas être un @ref{83,,keyword} tel que @code{class}, @code{for}, @code{return}, @code{global}, @code{pass} ou @code{raise}.

Si `rename' vaut @code{True}, alors les noms de champs invalides sont automatiquement renommés en noms positionnels. Par exemple, @code{['abc', 'def', 'ghi', 'abc']} est converti en @code{['abc, '_1', 'ghi', '_3']} afin d'éliminer le mot-clé @code{def} et le doublon de @code{abc}.

`defaults' peut être @code{None} ou un @ref{1205,,iterable} de valeurs par défaut. Comme les champs avec une valeur par défaut doivent être définis après les champs sans valeur par défaut, les `defaults' sont appliqués aux paramètres les plus à droite. Par exemple, si les noms des champs sont @code{['x', 'y', 'z']} et les valeurs par défaut @code{(1, 2)}, alors @code{x} est un argument obligatoire tandis que @code{y} et @code{y} valent par défaut @code{1} et @code{2}.

If `module' is defined, the @ref{36a,,__module__} attribute of the
named tuple is set to that value.

Les instances de `n'-uplets nommés n'ont pas de dictionnaires propres, elles sont donc légères et ne requièrent pas plus de mémoire que les `n'-uplets natifs.

Pour permettre la sérialisation, la classe de `n'-uplet nommée doit être assignée à une variable qui correspond à `typename'.


Modifié dans la version 3.1: Gestion de `rename'.



Modifié dans la version 3.6: Les paramètres `verbose' et `rename' deviennent des @ref{2a2,,arguments obligatoirement nommés}.



Modifié dans la version 3.6: Ajout du paramètre `module'.



Modifié dans la version 3.7: Suppression du paramètre `verbose' et de l'attribut @code{_source}.



Modifié dans la version 3.7: Ajout du paramètre `defaults' et de l'attribut @code{_field_defaults}.

@end deffn

@example
>>> # Basic example
>>> Point = namedtuple('Point', ['x', 'y'])
>>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
>>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
33
>>> x, y = p                # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y               # fields also accessible by name
33
>>> p                       # readable __repr__ with a name=value style
Point(x=11, y=22)
@end example

Les `n'-uplets nommés sont particulièrement utiles pour associer des noms de champs à des `n'-uplets renvoyés par les modules @ref{29,,csv} ou @ref{ce,,sqlite3} :

@example
EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')

import csv
for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
    print(emp.name, emp.title)

import sqlite3
conn = sqlite3.connect('/companydata')
cursor = conn.cursor()
cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
for emp in map(EmployeeRecord._make, cursor.fetchall()):
    print(emp.name, emp.title)
@end example

En plus des méthodes héritées de @code{tuple}, les `n'-uplets nommés implémentent trois méthodes et deux attributs supplémentaires. Pour éviter les conflits avec noms de champs, leurs noms commencent par un tiret bas.

@geindex _make() (méthode de la classe collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _make}@anchor{249d}
@deffn {Méthode} classmethod somenamedtuple._make (iterable)

Méthode de classe qui construit une nouvelle instance à partir d'une séquence ou d'un itérable existant.

@example
>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)
@end example
@end deffn

@geindex _asdict() (méthode collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _asdict}@anchor{9cf}
@deffn {Méthode} somenamedtuple._asdict ()

Renvoie un nouveau @ref{253,,dict} qui associe chaque nom de champ à sa valeur correspondante :

@example
>>> p = Point(x=11, y=22)
>>> p._asdict()
@{'x': 11, 'y': 22@}
@end example


Modifié dans la version 3.1: Renvoie un @ref{5c5,,OrderedDict} au lieu d'un @ref{253,,dict} natif.



Modifié dans la version 3.8: renvoie un @ref{253,,dict} natif plutôt qu'un @ref{5c5,,OrderedDict}. À partir de Python 3.7, les dictionnaires natifs garantissent la préservation de l'ordre. Si les autres fonctionnalités d'@ref{5c5,,OrderedDict} sont nécessaires, la solution préconisée est de convertir le résultat vers le type souhaité : @code{OrderedDict(nt._asdict())}.

@end deffn

@geindex _replace() (méthode collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _replace}@anchor{249e}
@deffn {Méthode} somenamedtuple._replace (**kwargs)

Renvoie une nouvelle instance du `n'-uplet nommé en remplaçant les champs spécifiés par leurs nouvelles valeurs :

@example
>>> p = Point(x=11, y=22)
>>> p._replace(x=33)
Point(x=33, y=22)

>>> for partnum, record in inventory.items():
...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
@end example

Named tuples are also supported by generic function @ref{150,,copy.replace()}.


Modifié dans la version 3.13: Raise @ref{522,,TypeError} instead of @ref{1ff,,ValueError} for invalid
keyword arguments.

@end deffn

@geindex _fields (attribut collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _fields}@anchor{249f}
@deffn {Attribut} somenamedtuple._fields

Tuple de chaînes de caractères listant les noms de champs. Pratique pour l'introspection et pour créer de nouveaux types de `n'-uplets nommés à partir d'existants.

@example
>>> p._fields            # view the field names
('x', 'y')

>>> Color = namedtuple('Color', 'red green blue')
>>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
>>> Pixel(11, 22, 128, 255, 0)
Pixel(x=11, y=22, red=128, green=255, blue=0)
@end example
@end deffn

@geindex _field_defaults (attribut collections.somenamedtuple)
@anchor{library/collections collections somenamedtuple _field_defaults}@anchor{24a0}
@deffn {Attribut} somenamedtuple._field_defaults

Dictionnaire qui assigne les valeurs par défaut aux noms des champs.

@example
>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._field_defaults
@{'balance': 0@}
>>> Account('premium')
Account(type='premium', balance=0)
@end example
@end deffn

Pour récupérer un champ dont le nom est une chaîne de caractères, utilisez la fonction @ref{bbf,,getattr()} :

@example
>>> getattr(p, 'x')
11
@end example

Pour convertir un dictionnaire en `n'-uplet nommé, utilisez l'opérateur double-étoile (comme expliqué dans @ref{1bbd,,Séparation des listes d'arguments}) :

@example
>>> d = @{'x': 11, 'y': 22@}
>>> Point(**d)
Point(x=11, y=22)
@end example

Il est aisé d'ajouter ou de modifier les fonctionnalités des `n'-uplets nommés grâce à l'héritage puisqu'il s'agit de simples classes. Voici comment ajouter un champ calculé avec une longueur fixe d'affichage :

@example
>>> class Point(namedtuple('Point', ['x', 'y'])):
...     __slots__ = ()
...     @@property
...     def hypot(self):
...         return (self.x ** 2 + self.y ** 2) ** 0.5
...     def __str__(self):
...         return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)

>>> for p in Point(3, 4), Point(14, 5/7):
...     print(p)
Point: x= 3.000  y= 4.000  hypot= 5.000
Point: x=14.000  y= 0.714  hypot=14.018
@end example

La sous-classe ci-dessus définit @code{__slots__} comme un `n'-uplet vide. Cela permet de garder une emprunte mémoire faible en empêchant la création de dictionnaire d'instance.

L'héritage n'est pas pertinent pour ajouter de nouveaux champs. Il est préférable de simplement créer un nouveau type de `n'-uplet nommé avec l'attribut @ref{249f,,_fields} :

@example
>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
@end example

Les `docstrings' peuvent être personnalisées en modifiant directement l'attribut @code{__doc__} :

@example
>>> Book = namedtuple('Book', ['id', 'title', 'authors'])
>>> Book.__doc__ += ': Hardcover book in active collection'
>>> Book.id.__doc__ = '13-digit ISBN'
>>> Book.title.__doc__ = 'Title of first printing'
>>> Book.authors.__doc__ = 'List of authors sorted by last name'
@end example


Modifié dans la version 3.5: La propriété devient éditable.



@subsubheading Voir aussi



@itemize *

@item 
Voir @ref{2ad,,typing.NamedTuple()} pour un moyen d'ajouter des indications de type pour les `n'-uplets nommés. Cela propose aussi une notation élégante utilisant le mot-clé @ref{12b5,,class} :

@example
class Component(NamedTuple):
    part_number: int
    weight: float
    description: Optional[str] = None
@end example

@item 
Voir @ref{1cc,,types.SimpleNamespace()} pour un espace de nommage mutable basé sur un dictionnaire sous-jacent à la place d'un `n'-uplet.

@item 
Le module @ref{2f,,dataclasses} fournit un décorateur et des fonctions pour ajouter automatiquement des méthodes spéciales générées aux classes définies par l’utilisateur.
@end itemize


@node Objets OrderedDict,Objets UserDict,namedtuple fonction de construction pour n-uplets avec des champs nommés,collections --- Container datatypes
@anchor{library/collections ordereddict-objects}@anchor{24a1}
@subsubsection Objets @code{OrderedDict}


Les dictionnaires ordonnés sont des dictionnaires comme les autres mais possèdent des capacités supplémentaires pour s'ordonner. Ils sont maintenant moins importants puisque la classe native @ref{253,,dict} sait se souvenir de l'ordre d'insertion (cette fonctionnalité a été garantie par Python 3.7).

Quelques différences persistent vis-à-vis de @ref{253,,dict} :


@itemize *

@item 
Les @ref{253,,dict} classiques ont été conçus pour être performants dans les opérations de correspondance. Garder une trace de l'ordre d'insertion était secondaire.

@item 
Les @ref{5c5,,OrderedDict} ont été conçus pour être performants dans les opérations de ré-arrangement. L'occupation mémoire, la vitesse de parcours et les performances de mise à jour étaient secondaires.

@item 
The @ref{5c5,,OrderedDict} algorithm can handle frequent reordering operations
better than @ref{253,,dict}.  As shown in the recipes below, this makes it
suitable for implementing various kinds of LRU caches.

@item 
Le test d'égalité de @ref{5c5,,OrderedDict} vérifie si l'ordre correspond.

A regular @ref{253,,dict} can emulate the order sensitive equality test with
@code{p == q and all(k1 == k2 for k1, k2 in zip(p, q))}.

@item 
La méthode @code{popitem()} de @ref{5c5,,OrderedDict} possède une signature différente. Elle accepte un argument optionnel pour spécifier quel élément doit être enlevé.

A regular @ref{253,,dict} can emulate OrderedDict's @code{od.popitem(last=True)}
with @code{d.popitem()} which is guaranteed to pop the rightmost (last) item.

A regular @ref{253,,dict} can emulate OrderedDict's @code{od.popitem(last=False)}
with @code{(k := next(iter(d)), d.pop(k))} which will return and remove the
leftmost (first) item if it exists.

@item 
@ref{5c5,,OrderedDict} possède une méthode @code{move_to_end()} pour déplacer efficacement un élément à la fin.

A regular @ref{253,,dict} can emulate OrderedDict's @code{od.move_to_end(k,
last=True)} with @code{d[k] = d.pop(k)} which will move the key and its
associated value to the rightmost (last) position.

A regular @ref{253,,dict} does not have an efficient equivalent for
OrderedDict's @code{od.move_to_end(k, last=False)} which moves the key
and its associated value to the leftmost (first) position.

@item 
Avant Python 3.8, @ref{253,,dict} n'a pas de méthode @code{__reversed__()}.
@end itemize

@geindex OrderedDict (classe dans collections)
@anchor{library/collections collections OrderedDict}@anchor{5c5}
@deffn {Classe} collections.OrderedDict ([items])

Renvoie une instance d'une sous-classe de @ref{253,,dict} qui possède des méthodes spécialisées pour redéfinir l'ordre du dictionnaire.


Ajouté dans la version 3.1.


@geindex popitem() (méthode collections.OrderedDict)
@anchor{library/collections collections OrderedDict popitem}@anchor{12cb}
@deffn {Méthode} popitem (last=True)

La méthode @ref{12cb,,popitem()} pour les dictionnaires ordonnés retire et renvoie une paire @code{(clé, valeur)}. Les paires sont renvoyées comme pour une pile, c'est-à-dire dernier entré, premier sorti (en anglais @abbr{LIFO}) si `last' vaut @code{True}. Si `last' vaut @code{False}, alors les paires sont renvoyées comme pour une file, c'est-à-dire premier entré, premier sorti (en anglais @abbr{FIFO,first-in@comma{} first-out}).
@end deffn

@geindex move_to_end() (méthode collections.OrderedDict)
@anchor{library/collections collections OrderedDict move_to_end}@anchor{11bc}
@deffn {Méthode} move_to_end (key, last=True)

Move an existing `key' to either end of an ordered dictionary.  The item
is moved to the right end if `last' is true (the default) or to the
beginning if `last' is false.  Raises @ref{33a,,KeyError} if the `key' does
not exist:

@example
>>> d = OrderedDict.fromkeys('abcde')
>>> d.move_to_end('b')
>>> '@w{'}.join(d)
'acdeb'
>>> d.move_to_end('b', last=False)
>>> '@w{'}.join(d)
'bacde'
@end example


Ajouté dans la version 3.2.

@end deffn
@end deffn

En plus des méthodes usuelles des dictionnaires, les dictionnaires ordonnés gèrent l'itération en sens inverse grâce à @ref{850,,reversed()}.
@anchor{library/collections collections-ordereddict-eq}@anchor{154f}
Equality tests between @ref{5c5,,OrderedDict} objects are order-sensitive
and are roughly equivalent to @code{list(od1.items())==list(od2.items())}.

Equality tests between @ref{5c5,,OrderedDict} objects and other
@ref{8b7,,Mapping} objects are order-insensitive like regular
dictionaries.  This allows @ref{5c5,,OrderedDict} objects to be substituted
anywhere a regular dictionary is used.


Modifié dans la version 3.5: Les @ref{24a2,,vues} d'éléments, de clés et de valeurs de @ref{5c5,,OrderedDict} gèrent maintenant l'itération en sens inverse en utilisant @ref{850,,reversed()}.



Modifié dans la version 3.6: Suite à l'acceptation de la 
@geindex Python Enhancement Proposals; PEP 468
PEP 468@footnote{https://peps.python.org/pep-0468/}, l'ordre des arguments nommés passés au constructeur et à la méthode @code{update()} de @ref{5c5,,OrderedDict} est conservé.



Modifié dans la version 3.9: ajout des opérateurs fusion (@code{|}) et mise-à-jour (@code{|=}) tels que définis dans 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.


@menu
* Exemples et cas pratiques utilisant OrderDict:: 

@end menu

@node Exemples et cas pratiques utilisant OrderDict,,,Objets OrderedDict
@anchor{library/collections ordereddict-examples-and-recipes}@anchor{24a3}
@subsubsection Exemples et cas pratiques utilisant @code{OrderDict}


Il est facile de créer une variante de dictionnaire ordonné qui retient l'ordre dans lequel les clés ont été insérées `en dernier'. Si une nouvelle entrée écrase une existante, la position d'insertion d'origine est modifiée et déplacée à la fin :

@example
class LastUpdatedOrderedDict(OrderedDict):
    'Store items in the order the keys were last added'

    def __setitem__(self, key, value):
        super().__setitem__(key, value)
        self.move_to_end(key)
@end example

Un @ref{5c5,,OrderedDict} peut aussi être utile pour implémenter des variantes de @ref{9dd,,functools.lru_cache()} :

@example
from collections import OrderedDict
from time import time

class TimeBoundedLRU:
    "LRU Cache that invalidates and refreshes old entries."

    def __init__(self, func, maxsize=128, maxage=30):
        self.cache = OrderedDict()      # @{ args : (timestamp, result)@}
        self.func = func
        self.maxsize = maxsize
        self.maxage = maxage

    def __call__(self, *args):
        if args in self.cache:
            self.cache.move_to_end(args)
            timestamp, result = self.cache[args]
            if time() - timestamp <= self.maxage:
                return result
        result = self.func(*args)
        self.cache[args] = time(), result
        if len(self.cache) > self.maxsize:
            self.cache.popitem(last=False)
        return result
@end example

@example
class MultiHitLRUCache:
    """ LRU cache that defers caching a result until
        it has been requested multiple times.

        To avoid flushing the LRU cache with one-time requests,
        we don't cache until a request has been made more than once.

    """

    def __init__(self, func, maxsize=128, maxrequests=4096, cache_after=1):
        self.requests = OrderedDict()   # @{ uncached_key : request_count @}
        self.cache = OrderedDict()      # @{ cached_key : function_result @}
        self.func = func
        self.maxrequests = maxrequests  # max number of uncached requests
        self.maxsize = maxsize          # max number of stored return values
        self.cache_after = cache_after

    def __call__(self, *args):
        if args in self.cache:
            self.cache.move_to_end(args)
            return self.cache[args]
        result = self.func(*args)
        self.requests[args] = self.requests.get(args, 0) + 1
        if self.requests[args] <= self.cache_after:
            self.requests.move_to_end(args)
            if len(self.requests) > self.maxrequests:
                self.requests.popitem(last=False)
        else:
            self.requests.pop(args, None)
            self.cache[args] = result
            if len(self.cache) > self.maxsize:
                self.cache.popitem(last=False)
        return result
@end example

@c >>> def square(x):
@c ...     return x * x
@c ...
@c >>> f = MultiHitLRUCache(square, maxsize=4, maxrequests=6)
@c >>> list(map(f, range(10)))  # First requests, don't cache
@c [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
@c >>> f(4)  # Cache the second request
@c 16
@c >>> f(6)  # Cache the second request
@c 36
@c >>> f(2)  # The first request aged out, so don't cache
@c 4
@c >>> f(6)  # Cache hit
@c 36
@c >>> f(4)  # Cache hit and move to front
@c 16
@c >>> list(f.cache.values())
@c [36, 16]
@c >>> set(f.requests).isdisjoint(f.cache)
@c True
@c >>> list(map(f, [9, 8, 7]))   # Cache these second requests
@c [81, 64, 49]
@c >>> list(map(f, [7, 9]))  # Cache hits
@c [49, 81]
@c >>> list(f.cache.values())
@c [16, 64, 49, 81]
@c >>> set(f.requests).isdisjoint(f.cache)
@c True

@node Objets UserDict,Objets UserList,Objets OrderedDict,collections --- Container datatypes
@anchor{library/collections userdict-objects}@anchor{24a4}
@subsubsection Objets @code{UserDict}


La classe @ref{1922,,UserDict} se comporte comme une surcouche autour des dictionnaires. L'utilité de cette classe est réduite, car on peut maintenant hériter directement de @ref{253,,dict}. Cependant, il peut être plus facile de travailler avec celle-ci, car le dictionnaire sous-jacent est accessible comme attribut.

@geindex UserDict (classe dans collections)
@anchor{library/collections collections UserDict}@anchor{1922}
@deffn {Classe} collections.UserDict ([initialdata])

Classe simulant un dictionnaire. Les instances de @ref{1922,,UserDict} possèdent un attribut @ref{24a5,,data} où est stocké leur contenu sous forme de dictionnaire natif. Si `initialdata' est spécifié, alors @ref{24a5,,data} est initialisé avec son contenu. Remarquez qu'une référence vers `initialdata' n'est pas conservée, ce qui permet de l'utiliser pour d'autres tâches.

En plus de gérer les méthodes et opérations des dictionnaires, les instances de @ref{1922,,UserDict} fournissent l'attribut suivant :

@geindex data (attribut collections.UserDict)
@anchor{library/collections collections UserDict data}@anchor{24a5}
@deffn {Attribut} data

Un dictionnaire natif où est stocké le contenu de la classe @ref{1922,,UserDict}.
@end deffn
@end deffn

@node Objets UserList,Objets UserString,Objets UserDict,collections --- Container datatypes
@anchor{library/collections userlist-objects}@anchor{24a6}
@subsubsection Objets @code{UserList}


Cette classe agit comme une surcouche autour des objets @code{list}. C'est une classe mère utile pour vos classes listes-compatibles qui peuvent en hériter et surcharger les méthodes existantes ou en ajouter de nouvelles. Ainsi, on peut ajouter de nouveaux comportements aux listes.

L'utilité de cette classe a été partiellement réduite par la possibilité d'hériter directement de @ref{5fc,,list}. Cependant, il peut être plus facile de travailler avec cette classe, car la liste sous-jacente est accessible via un attribut.

@geindex UserList (classe dans collections)
@anchor{library/collections collections UserList}@anchor{1499}
@deffn {Classe} collections.UserList ([list])

Classe simulant une liste. Les instances de @ref{1499,,UserList} possèdent un attribut @ref{1499,,UserList} où est stocké leur contenu sous forme de liste native. Il est initialement une copie de `list', ou @code{[]} par défaut. `list' peut être un itérable, par exemple une liste native ou un objet @ref{1499,,UserList}.

En plus de gérer les méthodes et opérations des séquences mutables, les instances de @ref{1499,,UserList} possèdent l'attribut suivant :

@geindex data (attribut collections.UserList)
@anchor{library/collections collections UserList data}@anchor{24a7}
@deffn {Attribut} data

Un objet @ref{5fc,,list} natif utilisé pour stocker le contenu de la classe @ref{1499,,UserList}.
@end deffn
@end deffn

`Prérequis pour l'héritage :' Les sous-classes de @ref{1499,,UserList} doivent implémenter un constructeur qui peut être appelé avec zéro ou un argument. Les opérations sur les listes qui renvoient une nouvelle séquence essayent de créer une instance de la classe courante. C'est pour cela que le constructeur doit pouvoir être appelé avec un unique paramètre, un objet séquence utilisé comme source de données.

Si une classe fille ne remplit pas cette condition, toutes les méthodes spéciales gérées par cette classe devront être implémentées à nouveau. Merci de consulter les sources pour obtenir des informations sur les méthodes qui doivent être fournies dans ce cas.

@node Objets UserString,,Objets UserList,collections --- Container datatypes
@anchor{library/collections userstring-objects}@anchor{24a8}
@subsubsection Objets @code{UserString}


La classe @ref{dc2,,UserString} agit comme une surcouche autour des objets @code{str}. L'utilité de cette classe a été partiellement réduite par la possibilité d'hériter directement de @ref{435,,str}. Cependant, il peut être plus facile de travailler avec cette classe, car la chaîne de caractère sous-jacente est accessible via un attribut.

@geindex UserString (classe dans collections)
@anchor{library/collections collections UserString}@anchor{dc2}
@deffn {Classe} collections.UserString (seq)

Classe simulant une chaîne de caractères. Les instances de @ref{dc2,,UserString} possèdent un attribut @ref{24a9,,data} où est stocké leur contenu sous forme de chaîne de caractères native. Le contenu de l'instance est initialement une copie de `seq', qui peut être n'importe quel objet convertible en chaîne de caractère avec la fonction native @ref{435,,str()}.

En plus de gérer les méthodes et opérations sur les chaînes de caractères, les instances de @ref{dc2,,UserString} possèdent l'attribut suivant :

@geindex data (attribut collections.UserString)
@anchor{library/collections collections UserString data}@anchor{24a9}
@deffn {Attribut} data

Un objet @ref{435,,str} natif utilisé pour stocker le contenu de la classe @ref{dc2,,UserString}.
@end deffn


Modifié dans la version 3.5: Nouvelles méthodes @code{__getnewargs__}, @code{__rmod__}, @code{casefold}, @code{format_map}, @code{isprintable} et @code{maketrans}.

@end deffn

@node collections abc --- Abstract Base Classes for Containers,heapq --- Heap queue algorithm,collections --- Container datatypes,Types de données
@anchor{library/collections abc doc}@anchor{24aa}@anchor{library/collections abc collections-abc-abstract-base-classes-for-containers}@anchor{24ab}@anchor{library/collections abc module-collections abc}@anchor{1e}
@subsection @code{collections.abc} --- Abstract Base Classes for Containers


@geindex module; collections.abc


Ajouté dans la version 3.3: Auparavant, ce module faisait partie du module @ref{1d,,collections}.


`Code source :' Lib/_collections_abc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/_collections_abc.py}

@c from collections.abc import *
@c import itertools
@c __name__ = '<doctest>'


__________________________________________________________________


This module provides @ref{1193,,abstract base classes} that
can be used to test whether a class provides a particular interface; for
example, whether it is @ref{5fb,,hashable} or whether it is a @ref{1199,,mapping}.

An @ref{7ab,,issubclass()} or @ref{42b,,isinstance()} test for an interface works in one
of three ways.

1) A newly written class can inherit directly from one of the
abstract base classes.  The class must supply the required abstract
methods.  The remaining mixin methods come from inheritance and can be
overridden if desired.  Other methods may be added as needed:

@example
class C(Sequence):                      # Direct inheritance
    def __init__(self): ...             # Extra method not required by the ABC
    def __getitem__(self, index):  ...  # Required abstract method
    def __len__(self):  ...             # Required abstract method
    def count(self, value): ...         # Optionally override a mixin method
@end example

@example
>>> issubclass(C, Sequence)
True
>>> isinstance(C(), Sequence)
True
@end example

2) Existing classes and built-in classes can be registered as "virtual
subclasses" of the ABCs.  Those classes should define the full API
including all of the abstract methods and all of the mixin methods.
This lets users rely on @ref{7ab,,issubclass()} or @ref{42b,,isinstance()} tests
to determine whether the full interface is supported.  The exception to
this rule is for methods that are automatically inferred from the rest
of the API:

@example
class D:                                 # No inheritance
    def __init__(self): ...              # Extra method not required by the ABC
    def __getitem__(self, index):  ...   # Abstract method
    def __len__(self):  ...              # Abstract method
    def count(self, value): ...          # Mixin method
    def index(self, value): ...          # Mixin method

Sequence.register(D)                     # Register instead of inherit
@end example

@example
>>> issubclass(D, Sequence)
True
>>> isinstance(D(), Sequence)
True
@end example

In this example, class @code{D} does not need to define
@code{__contains__}, @code{__iter__}, and @code{__reversed__} because the
@ref{1ff5,,in-operator}, the @ref{1205,,iteration}
logic, and the @ref{850,,reversed()} function automatically fall back to
using @code{__getitem__} and @code{__len__}.

3) Some simple interfaces are directly recognizable by the presence of
the required methods (unless those methods have been set to
@ref{660,,None}):

@example
class E:
    def __iter__(self): ...
    def __next__(self): ...
@end example

@example
>>> issubclass(E, Iterable)
True
>>> isinstance(E(), Iterable)
True
@end example

Complex interfaces do not support this last technique because an
interface is more than just the presence of method names.  Interfaces
specify semantics and relationships between methods that cannot be
inferred solely from the presence of specific method names.  For
example, knowing that a class supplies @code{__getitem__}, @code{__len__}, and
@code{__iter__} is insufficient for distinguishing a @ref{11a1,,Sequence} from
a @ref{8b7,,Mapping}.


Ajouté dans la version 3.9: These abstract classes now support @code{[]}. See @ref{69d,,Type Alias générique}
and 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}.


@menu
* Classes de base abstraites de collections:: 
* Collections Abstract Base Classes: Collections Abstract Base Classes -- Detailed Descriptions. Detailed Descriptions
* Exemples et recettes:: 

@end menu

@node Classes de base abstraites de collections,Collections Abstract Base Classes -- Detailed Descriptions,,collections abc --- Abstract Base Classes for Containers
@anchor{library/collections abc collections-abstract-base-classes}@anchor{863}@anchor{library/collections abc id1}@anchor{24ac}
@subsubsection Classes de base abstraites de collections


Le module collections apporte les @ref{1193,,ABC} suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ABC

@tab

Hérite de

@tab

Méthodes abstraites

@tab

Méthodes `mixin'

@item

@ref{21d8,,Container} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__contains__}

@tab

@item

@ref{4df,,Hashable} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__hash__}

@tab

@item

@ref{21d6,,Iterable} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
} @footnote{
Checking @code{isinstance(obj, Iterable)} detects classes that are
registered as @ref{21d6,,Iterable} or that have an @ref{1c4e,,__iter__()}
method, but it does not detect classes that iterate with the
@ref{280,,__getitem__()} method.  The only reliable way to determine
whether an object is @ref{1205,,iterable} is to call @code{iter(obj)}.
}

@tab

@tab

@code{__iter__}

@tab

@item

@ref{21d7,,Iterator} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{21d6,,Iterable}

@tab

@code{__next__}

@tab

@code{__iter__}

@item

@ref{c77,,Reversible} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{21d6,,Iterable}

@tab

@code{__reversed__}

@tab

@item

@ref{dc8,,Generator}  @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{21d7,,Iterator}

@tab

@code{send}, @code{throw}

@tab

@code{close}, @code{__iter__}, @code{__next__}

@item

@ref{4e0,,Sized}  @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__len__}

@tab

@item

@ref{7d4,,Callable}  @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__call__}

@tab

@item

@ref{c76,,Collection}  @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{4e0,,Sized},
@ref{21d6,,Iterable},
@ref{21d8,,Container}

@tab

@code{__contains__},
@code{__iter__},
@code{__len__}

@tab

@item

@ref{11a1,,Sequence}

@tab

@ref{c77,,Reversible},
@ref{c76,,Collection}

@tab

@code{__getitem__},
@code{__len__}

@tab

@code{__contains__}, @code{__iter__}, @code{__reversed__}, @code{index} et @code{count}

@item

@ref{19f,,MutableSequence}

@tab

@ref{11a1,,Sequence}

@tab

@code{__getitem__},
@code{__setitem__},
@code{__delitem__},
@code{__len__},
@code{insert}

@tab

Inherited @ref{11a1,,Sequence} methods and
@code{append}, @code{clear}, @code{reverse}, @code{extend},
@code{pop}, @code{remove}, and @code{__iadd__}

@item

@ref{2c0,,ByteString}

@tab

@ref{11a1,,Sequence}

@tab

@code{__getitem__},
@code{__len__}

@tab

Méthodes héritées de @ref{11a1,,Sequence}

@item

@ref{21ce,,Set}

@tab

@ref{c76,,Collection}

@tab

@code{__contains__},
@code{__iter__},
@code{__len__}

@tab

@code{__le__}, @code{__lt__}, @code{__eq__}, @code{__ne__}, @code{__gt__}, @code{__ge__}, @code{__and__}, @code{__or__}, @code{__sub__}, @code{__xor__} et @code{isdisjoint}

@item

@ref{21d9,,MutableSet}

@tab

@ref{21ce,,Set}

@tab

@code{__contains__},
@code{__iter__},
@code{__len__},
@code{add},
@code{discard}

@tab

Méthodes héritées de @ref{21ce,,Set}, et @code{clear}, @code{pop}, @code{remove}, @code{__ior__}, @code{__iand__}, @code{__ixor__} et @code{__isub__}

@item

@ref{8b7,,Mapping}

@tab

@ref{c76,,Collection}

@tab

@code{__getitem__},
@code{__iter__},
@code{__len__}

@tab

@code{__contains__}, @code{keys}, @code{items}, @code{values}, @code{get}, @code{__eq__} et @code{__ne__}

@item

@ref{1090,,MutableMapping}

@tab

@ref{8b7,,Mapping}

@tab

@code{__getitem__},
@code{__setitem__},
@code{__delitem__},
@code{__iter__},
@code{__len__}

@tab

Méthodes héritées de @ref{8b7,,Mapping}, et @code{pop}, @code{popitem}, @code{clear}, @code{update} et @code{setdefault}

@item

@ref{21da,,MappingView}

@tab

@ref{4e0,,Sized}

@tab

@tab

@code{__len__}

@item

@ref{21dc,,ItemsView}

@tab

@ref{21da,,MappingView},
@ref{21ce,,Set}

@tab

@tab

@code{__contains__},
@code{__iter__}

@item

@ref{21db,,KeysView}

@tab

@ref{21da,,MappingView},
@ref{21ce,,Set}

@tab

@tab

@code{__contains__},
@code{__iter__}

@item

@ref{21dd,,ValuesView}

@tab

@ref{21da,,MappingView},
@ref{c76,,Collection}

@tab

@tab

@code{__contains__}, @code{__iter__}

@item

@ref{dc9,,Awaitable} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__await__}

@tab

@item

@ref{dca,,Coroutine} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{dc9,,Awaitable}

@tab

@code{send}, @code{throw}

@tab

@code{close}

@item

@ref{dcc,,AsyncIterable} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__aiter__}

@tab

@item

@ref{dcb,,AsyncIterator} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{dcc,,AsyncIterable}

@tab

@code{__anext__}

@tab

@code{__aiter__}

@item

@ref{c78,,AsyncGenerator} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@ref{dcb,,AsyncIterator}

@tab

@code{asend}, @code{athrow}

@tab

@code{aclose}, @code{__aiter__}, @code{__anext__}

@item

@ref{2c1,,Buffer} @footnote{
These ABCs override @ref{24ad,,__subclasshook__()} to support
testing an interface by verifying the required methods are present
and have not been set to @ref{660,,None}.  This only works for simple
interfaces.  More complex interfaces require registration or direct
subclassing.
}

@tab

@tab

@code{__buffer__}

@tab

@end multitable


@subsubheading Notes


@node Collections Abstract Base Classes -- Detailed Descriptions,Exemples et recettes,Classes de base abstraites de collections,collections abc --- Abstract Base Classes for Containers
@anchor{library/collections abc collections-abstract-base-classes-detailed-descriptions}@anchor{24ae}
@subsubsection Collections Abstract Base Classes -- Detailed Descriptions


@geindex Container (classe dans collections.abc)
@anchor{library/collections abc collections abc Container}@anchor{21d8}
@deffn {Classe} collections.abc.Container

ABC for classes that provide the @ref{1ee0,,__contains__()} method.
@end deffn

@geindex Hashable (classe dans collections.abc)
@anchor{library/collections abc collections abc Hashable}@anchor{4df}
@deffn {Classe} collections.abc.Hashable

ABC for classes that provide the @ref{ae9,,__hash__()} method.
@end deffn

@geindex Sized (classe dans collections.abc)
@anchor{library/collections abc collections abc Sized}@anchor{4e0}
@deffn {Classe} collections.abc.Sized

ABC for classes that provide the @ref{1ee5,,__len__()} method.
@end deffn

@geindex Callable (classe dans collections.abc)
@anchor{library/collections abc collections abc Callable}@anchor{7d4}
@deffn {Classe} collections.abc.Callable

ABC for classes that provide the @ref{543,,__call__()} method.

See @ref{24af,,Annotating callable objects} for details on how to use
@code{Callable} in type annotations.
@end deffn

@geindex Iterable (classe dans collections.abc)
@anchor{library/collections abc collections abc Iterable}@anchor{21d6}
@deffn {Classe} collections.abc.Iterable

ABC for classes that provide the @ref{1c4e,,__iter__()} method.

Checking @code{isinstance(obj, Iterable)} detects classes that are registered
as @ref{21d6,,Iterable} or that have an @ref{1c4e,,__iter__()} method,
but it does
not detect classes that iterate with the @ref{280,,__getitem__()} method.
The only reliable way to determine whether an object is @ref{1205,,iterable}
is to call @code{iter(obj)}.
@end deffn

@geindex Collection (classe dans collections.abc)
@anchor{library/collections abc collections abc Collection}@anchor{c76}
@deffn {Classe} collections.abc.Collection

ABC pour les classes de conteneurs itérables et `sized'.


Ajouté dans la version 3.6.

@end deffn

@geindex Iterator (classe dans collections.abc)
@anchor{library/collections abc collections abc Iterator}@anchor{21d7}
@deffn {Classe} collections.abc.Iterator

ABC pour les classes qui définissent les méthodes @ref{1c51,,__iter__()} et @ref{12ab,,__next__()}. Voir aussi la définition d'@ref{1aa,,itérateur}.
@end deffn

@geindex Reversible (classe dans collections.abc)
@anchor{library/collections abc collections abc Reversible}@anchor{c77}
@deffn {Classe} collections.abc.Reversible

ABC for iterable classes that also provide the @ref{1edf,,__reversed__()}
method.


Ajouté dans la version 3.6.

@end deffn

@geindex Generator (classe dans collections.abc)
@anchor{library/collections abc collections abc Generator}@anchor{dc8}
@deffn {Classe} collections.abc.Generator

ABC for @ref{104a,,generator} classes that implement the protocol defined in
@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/} that extends @ref{1aa,,iterators} with the
@ref{1f4f,,send()},
@ref{4e2,,throw()} and @ref{167d,,close()} methods.

See @ref{24b0,,Annotating generators and coroutines}
for details on using @code{Generator} in type annotations.


Ajouté dans la version 3.5.

@end deffn

@geindex Sequence (classe dans collections.abc)
@geindex MutableSequence (classe dans collections.abc)
@geindex ByteString (classe dans collections.abc)
@anchor{library/collections abc collections abc Sequence}@anchor{11a1}
@deffn {Classe} collections.abc.Sequence
@anchor{library/collections abc collections abc MutableSequence}@anchor{19f}
@deffnx {Classe} collections.abc.MutableSequence
@anchor{library/collections abc collections abc ByteString}@anchor{2c0}
@deffnx {Classe} collections.abc.ByteString

ABC pour les @ref{4db,,séquences} immuables et mutables.

Implementation note: Some of the mixin methods, such as
@ref{1c4e,,__iter__()}, @ref{1edf,,__reversed__()} and @code{index()}, make
repeated calls to the underlying @ref{280,,__getitem__()} method.
Consequently, if @ref{280,,__getitem__()} is implemented with constant
access speed, the mixin methods will have linear performance;
however, if the underlying method is linear (as it would be with a
linked list), the mixins will have quadratic performance and will
likely need to be overridden.


Modifié dans la version 3.5: La méthode index() a ajouté le support des arguments `start' et `stop'.



Deprecated since version 3.12, will be removed in version 3.14: The @ref{2c0,,ByteString} ABC has been deprecated.
For use in typing, prefer a union, like @code{bytes | bytearray}, or
@ref{2c1,,collections.abc.Buffer}.
For use as an ABC, prefer @ref{11a1,,Sequence} or @ref{2c1,,collections.abc.Buffer}.

@end deffn

@geindex Set (classe dans collections.abc)
@geindex MutableSet (classe dans collections.abc)
@anchor{library/collections abc collections abc Set}@anchor{21ce}
@deffn {Classe} collections.abc.Set
@anchor{library/collections abc collections abc MutableSet}@anchor{21d9}
@deffnx {Classe} collections.abc.MutableSet

ABCs for read-only and mutable @ref{20fa,,sets}.
@end deffn

@geindex Mapping (classe dans collections.abc)
@geindex MutableMapping (classe dans collections.abc)
@anchor{library/collections abc collections abc Mapping}@anchor{8b7}
@deffn {Classe} collections.abc.Mapping
@anchor{library/collections abc collections abc MutableMapping}@anchor{1090}
@deffnx {Classe} collections.abc.MutableMapping

ABC pour les @ref{1199,,tables de correspondances} immuables et mutables.
@end deffn

@geindex MappingView (classe dans collections.abc)
@geindex ItemsView (classe dans collections.abc)
@geindex KeysView (classe dans collections.abc)
@geindex ValuesView (classe dans collections.abc)
@anchor{library/collections abc collections abc MappingView}@anchor{21da}
@deffn {Classe} collections.abc.MappingView
@anchor{library/collections abc collections abc ItemsView}@anchor{21dc}
@deffnx {Classe} collections.abc.ItemsView
@anchor{library/collections abc collections abc KeysView}@anchor{21db}
@deffnx {Classe} collections.abc.KeysView
@anchor{library/collections abc collections abc ValuesView}@anchor{21dd}
@deffnx {Classe} collections.abc.ValuesView

ABC pour les @ref{24a2,,vues} de `mappings' (tableaux de correspondances), d'éléments, de clés et de valeurs.
@end deffn

@geindex Awaitable (classe dans collections.abc)
@anchor{library/collections abc collections abc Awaitable}@anchor{dc9}
@deffn {Classe} collections.abc.Awaitable

ABC for @ref{1ab,,awaitable} objects, which can be used in @ref{1b7,,await}
expressions.  Custom implementations must provide the
@ref{1f4a,,__await__()} method.

Les objets @ref{47b,,coroutines} et les instances de l'ABC @ref{dca,,Coroutine} sont tous des instances de cette ABC.

@cartouche
@quotation Note 
In CPython, generator-based coroutines (@ref{104a,,generators}
decorated with @ref{e73,,@@types.coroutine}) are
`awaitables', even though they do not have an @ref{1f4a,,__await__()} method.
Using @code{isinstance(gencoro, Awaitable)} for them will return @code{False}.
Use @ref{e04,,inspect.isawaitable()} to detect them.
@end quotation
@end cartouche


Ajouté dans la version 3.5.

@end deffn

@geindex Coroutine (classe dans collections.abc)
@anchor{library/collections abc collections abc Coroutine}@anchor{dca}
@deffn {Classe} collections.abc.Coroutine

ABC for @ref{47b,,coroutine} compatible classes.  These implement the
following methods, defined in @ref{1e8d,,Objets coroutines}:
@ref{1f4e,,send()}, @ref{4e1,,throw()}, and
@ref{1f50,,close()}.  Custom implementations must also implement
@ref{1f4a,,__await__()}.  All @ref{dca,,Coroutine} instances are also
instances of @ref{dc9,,Awaitable}.

@cartouche
@quotation Note 
In CPython, generator-based coroutines (@ref{104a,,generators}
decorated with @ref{e73,,@@types.coroutine}) are
`awaitables', even though they do not have an @ref{1f4a,,__await__()} method.
Using @code{isinstance(gencoro, Coroutine)} for them will return @code{False}.
Use @ref{e04,,inspect.isawaitable()} to detect them.
@end quotation
@end cartouche

See @ref{24b0,,Annotating generators and coroutines}
for details on using @code{Coroutine} in type annotations.
The variance and order of type parameters correspond to those of
@ref{dc8,,Generator}.


Ajouté dans la version 3.5.

@end deffn

@geindex AsyncIterable (classe dans collections.abc)
@anchor{library/collections abc collections abc AsyncIterable}@anchor{dcc}
@deffn {Classe} collections.abc.AsyncIterable

ABC for classes that provide an @code{__aiter__} method.  See also the
definition of @ref{d65,,asynchronous iterable}.


Ajouté dans la version 3.5.

@end deffn

@geindex AsyncIterator (classe dans collections.abc)
@anchor{library/collections abc collections abc AsyncIterator}@anchor{dcb}
@deffn {Classe} collections.abc.AsyncIterator

ABC pour les classes qui définissent les méthodes @code{__aiter__} et @code{__anext__}. Voir aussi la définition d'@ref{1a9,,itérateur asynchrone}.


Ajouté dans la version 3.5.

@end deffn

@geindex AsyncGenerator (classe dans collections.abc)
@anchor{library/collections abc collections abc AsyncGenerator}@anchor{c78}
@deffn {Classe} collections.abc.AsyncGenerator

ABC for @ref{1fba,,asynchronous generator} classes that implement the protocol
defined in 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} and 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.

See @ref{24b0,,Annotating generators and coroutines}
for details on using @code{AsyncGenerator} in type annotations.


Ajouté dans la version 3.6.

@end deffn

@geindex Buffer (classe dans collections.abc)
@anchor{library/collections abc collections abc Buffer}@anchor{2c1}
@deffn {Classe} collections.abc.Buffer

ABC for classes that provide the @ref{448,,__buffer__()} method,
implementing the @ref{38e,,buffer protocol}. See 
@geindex Python Enhancement Proposals; PEP 688
PEP 688@footnote{https://peps.python.org/pep-0688/}.


Ajouté dans la version 3.12.

@end deffn

@node Exemples et recettes,,Collections Abstract Base Classes -- Detailed Descriptions,collections abc --- Abstract Base Classes for Containers
@anchor{library/collections abc examples-and-recipes}@anchor{24b1}
@subsubsection Exemples et recettes


ABCs allow us to ask classes or instances if they provide
particular functionality, for example:

@example
size = None
if isinstance(myvar, collections.abc.Sized):
    size = len(myvar)
@end example

Several of the ABCs are also useful as mixins that make it easier to develop
classes supporting container APIs.  For example, to write a class supporting
the full @ref{21ce,,Set} API, it is only necessary to supply the three underlying
abstract methods: @ref{1ee0,,__contains__()}, @ref{1c4e,,__iter__()}, and
@ref{1ee5,,__len__()}. The ABC supplies the remaining methods such as
@code{__and__()} and @ref{21bb,,isdisjoint()}:

@example
class ListBasedSet(collections.abc.Set):
    '@w{'}' Alternate set implementation favoring space over speed
        and not requiring the set elements to be hashable. '@w{'}'
    def __init__(self, iterable):
        self.elements = lst = []
        for value in iterable:
            if value not in lst:
                lst.append(value)

    def __iter__(self):
        return iter(self.elements)

    def __contains__(self, value):
        return value in self.elements

    def __len__(self):
        return len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2            # The __and__() method is supported automatically
@end example

Notes à propos de l'utilisation de @ref{21ce,,Set} et @ref{21d9,,MutableSet} comme `mixin' :


@enumerate 

@item 
Since some set operations create new sets, the default mixin methods need
a way to create new instances from an @ref{1205,,iterable}. The class constructor is
assumed to have a signature in the form @code{ClassName(iterable)}.
That assumption is factored-out to an internal @ref{165,,classmethod} called
@code{_from_iterable()} which calls @code{cls(iterable)} to produce a new set.
If the @ref{21ce,,Set} mixin is being used in a class with a different
constructor signature, you will need to override @code{_from_iterable()}
with a classmethod or regular method that can construct new instances from
an iterable argument.

@item 
To override the comparisons (presumably for speed, as the
semantics are fixed), redefine @ref{12e9,,__le__()} and
@ref{12eb,,__ge__()},
then the other operations will automatically follow suit.

@item 
The @ref{21ce,,Set} mixin provides a @code{_hash()} method to compute a hash value
for the set; however, @ref{ae9,,__hash__()} is not defined because not all sets
are @ref{5fb,,hashable} or immutable.  To add set hashability using mixins,
inherit from both @ref{21ce,,Set()} and @ref{4df,,Hashable()}, then define
@code{__hash__ = Set._hash}.
@end enumerate


@subsubheading Voir aussi



@itemize *

@item 
OrderedSet recipe@footnote{https://code.activestate.com/recipes/576694/} pour un exemple construit sur @ref{21d9,,MutableSet}.

@item 
Pour plus d'informations à propos des ABC, voir le module @ref{4,,abc} et la 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/}.
@end itemize


@node heapq --- Heap queue algorithm,bisect --- Array bisection algorithm,collections abc --- Abstract Base Classes for Containers,Types de données
@anchor{library/heapq doc}@anchor{24b2}@anchor{library/heapq heapq-heap-queue-algorithm}@anchor{24b3}@anchor{library/heapq module-heapq}@anchor{68}
@subsection @code{heapq} --- Heap queue algorithm


@geindex module; heapq

`Code source :' Lib/heapq.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/heapq.py}


__________________________________________________________________


Ce module expose une implémentation de l'algorithme de file de priorité, basée sur un tas.

Heaps are binary trees for which every parent node has a value less than or
equal to any of its children.  We refer to this condition as the heap invariant.

This implementation uses arrays for which
@code{heap[k] <= heap[2*k+1]} and @code{heap[k] <= heap[2*k+2]} for all `k', counting
elements from zero.  For the sake of comparison, non-existing elements are
considered to be infinite.  The interesting property of a heap is that its
smallest element is always the root, @code{heap[0]}.

L'API ci-dessous diffère de la file de priorité classique par deux aspects : (a) l'indiçage commence à zéro. Cela complexifie légèrement la relation entre l'indice d'un nœud et les indices de ses fils mais est alignée avec l'indiçage commençant à zéro que Python utilise. (b) La méthode `pop' renvoie le plus petit élément et non le plus grand (appelé « tas-min » dans les manuels scolaires ; le « tas-max » étant généralement plus courant dans la littérature car il permet le classement sans tampon).

Ces deux points permettent d'aborder le tas comme une liste Python standard sans surprise : @code{heap[0]} est le plus petit élément et @code{heap.sort()} conserve l'invariant du tas !

Pour créer un tas, utilisez une liste initialisée à @code{[]} ou bien utilisez une liste existante et transformez la en tas à l'aide de la fonction @ref{24b4,,heapify()}.

Les fonctions suivantes sont fournies :

@geindex heappush() (dans le module heapq)
@anchor{library/heapq heapq heappush}@anchor{1470}
@deffn {Fonction} heapq.heappush (heap, item)

Introduit la valeur `item' dans le tas `heap', en conservant l'invariance du tas.
@end deffn

@geindex heappop() (dans le module heapq)
@anchor{library/heapq heapq heappop}@anchor{1471}
@deffn {Fonction} heapq.heappop (heap)

Extraie le plus petit élément de `heap' en préservant l'invariant du tas. Si le tas est vide, une exception @ref{14eb,,IndexError} est levée. Pour accéder au plus petit élément sans le retirer, utilisez @code{heap[0]}.
@end deffn

@geindex heappushpop() (dans le module heapq)
@anchor{library/heapq heapq heappushpop}@anchor{24b5}
@deffn {Fonction} heapq.heappushpop (heap, item)

Introduit l'élément `item' dans le tas, puis extraie le plus petit élément de `heap'. Cette action combinée est plus efficace que @ref{1470,,heappush()} suivie par un appel séparé à @ref{1471,,heappop()}.
@end deffn

@geindex heapify() (dans le module heapq)
@anchor{library/heapq heapq heapify}@anchor{24b4}
@deffn {Fonction} heapq.heapify (x)

Transforme une liste `x' en un tas, sans utiliser de tampon et en temps linéaire.
@end deffn

@geindex heapreplace() (dans le module heapq)
@anchor{library/heapq heapq heapreplace}@anchor{24b6}
@deffn {Fonction} heapq.heapreplace (heap, item)

Extraie le plus petit élément de `heap' et introduit le nouvel élément `item'. La taille du tas ne change pas. Si le tas est vide, une exception @ref{14eb,,IndexError} est levée.

Cette opération en une étape est plus efficace qu'un appel à @ref{1471,,heappop()} suivi d'un appel à @ref{1470,,heappush()} et est plus appropriée lorsque le tas est de taille fixe. La combinaison `pop'/`push' renvoie toujours un élément du tas et le remplace par `item'.

La valeur renvoyée peut être plus grande que l'élément `item' ajouté. Si cela n'est pas souhaitable, utilisez plutôt @ref{24b5,,heappushpop()} à la place. Sa combinaison `push'/`pop' renvoie le plus petit élément des deux valeurs et laisse la plus grande sur le tas.
@end deffn

Ce module contient également trois fonctions génériques utilisant les tas.

@geindex merge() (dans le module heapq)
@anchor{library/heapq heapq merge}@anchor{df1}
@deffn {Fonction} heapq.merge (*iterables, key=None, reverse=False)

Fusionne plusieurs entrées ordonnées en une unique sortie ordonnée (par exemple, fusionne des entrées datées provenant de multiples journaux applicatifs). Renvoie un @ref{1aa,,iterator} sur les valeurs ordonnées.

Similaire à @code{sorted(itertools.chain(*iterables))} mais renvoie un itérable, ne stocke pas toutes les données en mémoire en une fois et suppose que chaque flux d'entrée est déjà classé (en ordre croissant).

A deux arguments optionnels qui doivent être fournis par mot clef.

`key' spécifie une @ref{df2,,key function} d'un argument utilisée pour extraire une clef de comparaison de chaque élément de la liste. La valeur par défaut est @code{None} (compare les éléments directement).

`reverse' est une valeur booléenne. Si elle est @code{True}, la liste d'éléments est fusionnée comme si toutes les comparaisons étaient inversées. Pour obtenir un comportement similaire à @code{sorted(itertools.chain(*iterables), reverse=True)}, tous les itérables doivent être classés par ordre décroissant.


Modifié dans la version 3.5: Ajout des paramètres optionnels `key' et `reverse'.

@end deffn

@geindex nlargest() (dans le module heapq)
@anchor{library/heapq heapq nlargest}@anchor{24b7}
@deffn {Fonction} heapq.nlargest (n, iterable, key=None)

Renvoie une liste contenant les `n' plus grands éléments du jeu de données défini par `iterable'. Si l'option `key' est fournie, celle-ci spécifie une fonction à un argument qui est utilisée pour extraire la clé de comparaison de chaque élément dans `iterable' (par exemple, @code{key=str.lower}). Équivalent à : @code{sorted(iterable, key=key, reverse=True)[:n]}.
@end deffn

@geindex nsmallest() (dans le module heapq)
@anchor{library/heapq heapq nsmallest}@anchor{24b8}
@deffn {Fonction} heapq.nsmallest (n, iterable, key=None)

Renvoie une liste contenant les `n' plus petits éléments du jeu de données défini par `iterable'. Si l'option `key' est fournie, celle-ci spécifie une fonction à un argument qui est utilisée pour extraire la clé de comparaison de chaque élément dans `iterable' (par exemple, @code{key=str.lower}). Équivalent à : @code{sorted(iterable, key=key)[:n]}.
@end deffn

Les deux fonctions précédentes sont les plus efficaces pour des petites valeurs de `n'. Pour de grandes valeurs, il est préférable d'utiliser la fonction @ref{bbc,,sorted()}. En outre, lorsque @code{n==1}, il est plus efficace d'utiliser les fonctions natives @ref{ef3,,min()} et @ref{ef4,,max()}. Si vous devez utiliser ces fonctions de façon répétée, il est préférable de transformer l'itérable en tas.

@menu
* Exemples simples:: 
* Notes d'implémentation de la file de priorité:: 
* Théorie:: 

@end menu

@node Exemples simples,Notes d'implémentation de la file de priorité,,heapq --- Heap queue algorithm
@anchor{library/heapq basic-examples}@anchor{24b9}
@subsubsection Exemples simples


Un tri par tas@footnote{https://fr.wikipedia.org/wiki/Tri_par_tas} peut être implémenté en introduisant toutes les valeurs dans un tas puis en effectuant l'extraction des éléments un par un :

@example
>>> def heapsort(iterable):
...     h = []
...     for value in iterable:
...         heappush(h, value)
...     return [heappop(h) for i in range(len(h))]
...
>>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@end example

Ceci est similaire à @code{sorted(iterable)} mais, contrairement à @ref{bbc,,sorted()}, cette implémentation n'est pas stable.

Les éléments d'un tas peuvent être des `n'-uplets. C'est pratique pour assigner des valeurs de comparaison (par exemple, des priorités de tâches) en plus de l'élément qui est suivi :

@example
>>> h = []
>>> heappush(h, (5, 'write code'))
>>> heappush(h, (7, 'release product'))
>>> heappush(h, (1, 'write spec'))
>>> heappush(h, (3, 'create tests'))
>>> heappop(h)
(1, 'write spec')
@end example

@node Notes d'implémentation de la file de priorité,Théorie,Exemples simples,heapq --- Heap queue algorithm
@anchor{library/heapq priority-queue-implementation-notes}@anchor{24ba}
@subsubsection Notes d'implémentation de la file de priorité


Une file de priorité@footnote{https://fr.wikipedia.org/wiki/File_de_priorit%C3%A9} est une application courante des tas et présente plusieurs défis d'implémentation :


@itemize *

@item 
Stabilité du classement : comment s'assurer que deux tâches avec la même priorité sont renvoyées dans l'ordre de leur ajout ?

@item 
La comparaison des couples (priorité, tâche) échoue si les priorités sont identiques et que les tâches n'ont pas de relation d'ordre par défaut.

@item 
Si la priorité d'une tâche change, comment la déplacer à sa nouvelle position dans le tas ?

@item 
Si une tâche en attente doit être supprimée, comment la trouver et la supprimer de la file ?
@end itemize

Une solution aux deux premiers problèmes consiste à stocker les entrées sous forme de liste à 3 éléments incluant la priorité, le numéro d'ajout et la tâche. Le numéro d'ajout sert à briser les égalités de telle sorte que deux tâches avec la même priorité sont renvoyées dans l'ordre de leur insertion. Puisque deux tâches ne peuvent jamais avoir le même numéro d'ajout, la comparaison des triplets ne va jamais chercher à comparer des tâches entre elles.

Une autre solution au fait que les tâches ne possèdent pas de relation d'ordre est de créer une classe d'encapsulation qui ignore l'élément tâche et ne compare que le champ priorité :

@example
from dataclasses import dataclass, field
from typing import Any

@@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)
@end example

Le problème restant consiste à trouver une tâche en attente et modifier sa priorité ou la supprimer. Trouver une tâche peut être réalisé à l'aide d'un dictionnaire pointant vers une entrée dans la file.

Supprimer une entrée ou changer sa priorité est plus difficile puisque cela romprait l'invariant de la structure de tas. Une solution possible est de marquer l'entrée comme supprimée et d'ajouter une nouvelle entrée avec sa priorité modifiée :

@example
pq = []                         # list of entries arranged in a heap
entry_finder = @{@}               # mapping of tasks to entries
REMOVED = '<removed-task>'      # placeholder for a removed task
counter = itertools.count()     # unique sequence count

def add_task(task, priority=0):
    'Add a new task or update the priority of an existing task'
    if task in entry_finder:
        remove_task(task)
    count = next(counter)
    entry = [priority, count, task]
    entry_finder[task] = entry
    heappush(pq, entry)

def remove_task(task):
    'Mark an existing task as REMOVED.  Raise KeyError if not found.'
    entry = entry_finder.pop(task)
    entry[-1] = REMOVED

def pop_task():
    'Remove and return the lowest priority task. Raise KeyError if empty.'
    while pq:
        priority, count, task = heappop(pq)
        if task is not REMOVED:
            del entry_finder[task]
            return task
    raise KeyError('pop from an empty priority queue')
@end example

@node Théorie,,Notes d'implémentation de la file de priorité,heapq --- Heap queue algorithm
@anchor{library/heapq theory}@anchor{24bb}
@subsubsection Théorie


Les tas sont des tableaux pour lesquels @code{a[k] <= a[2*k+1]} et @code{a[k] <= a[2*k+2]} pour tout `k' en comptant les éléments à partir de 0. Pour simplifier la comparaison, les éléments inexistants sont considérés comme étant infinis. L'intérêt des tas est que @code{a[0]} est toujours leur plus petit élément.

L'invariant étrange ci-dessus est une représentation efficace en mémoire d'un tournoi. Les nombres ci-dessous sont `k' et non @code{a[k]} :

@example
                               0

              1                                 2

      3               4                5               6

  7       8       9       10      11      12      13      14

15 16   17 18   19 20   21 22   23 24   25 26   27 28   29 30
@end example

Dans l'arbre ci-dessus, chaque nœud `k' a pour enfants @code{2*k+1} et @code{2*k+2}. Dans les tournois binaires habituels dans les compétitions sportives, chaque nœud est le vainqueur des deux nœuds inférieurs et nous pouvons tracer le chemin du vainqueur le long de l'arbre afin de voir qui étaient ses adversaires. Cependant, dans de nombreuses applications informatiques de ces tournois, nous n'avons pas besoin de produire l'historique du vainqueur. Afin d'occuper moins de mémoire, on remplace le vainqueur lors de sa promotion par un autre élément à un plus bas niveau. La règle devient alors qu'un nœud et les deux nœuds qu'il chapeaute contiennent trois éléments différents, mais le nœud supérieur « gagne » contre les deux nœuds inférieurs.

If this heap invariant is protected at all time, index 0 is clearly the overall
winner.  The simplest algorithmic way to remove it and find the "next" winner is
to move some loser (let's say cell 30 in the diagram above) into the 0 position,
and then percolate this new 0 down the tree, exchanging values, until the
invariant is re-established. This is clearly logarithmic on the total number of
items in the tree. By iterating over all items, you get an `O'(`n' log `n') sort.

Une propriété agréable de cet algorithme est qu'il est possible d'insérer efficacement de nouveaux éléments en cours de classement, du moment que les éléments insérés ne sont pas « meilleurs » que le dernier élément qui a été extrait. Ceci s'avère très utile dans des simulations où l'arbre contient la liste des événements arrivants et que la condition de « victoire » est le plus petit temps d'exécution planifié. Lorsqu'un événement programme l'exécution d'autres événements, ceux-ci sont planifiés pour le futur et peuvent donc rejoindre le tas. Ainsi, le tas est une bonne structure pour implémenter un ordonnanceur (et c'est ce que j'ai utilisé pour mon séquenceur MIDI ☺).

Plusieurs structures ont été étudiées en détail pour implémenter des ordonnanceurs et les tas sont bien adaptés : ils sont raisonnablement rapides, leur vitesse est presque constante et le pire cas ne diffère pas trop du cas moyen. S'il existe des représentations qui sont plus efficaces en général, les pires cas peuvent être terriblement mauvais.

Les tas sont également très utiles pour ordonner les données sur de gros disques. Vous savez probablement qu'un gros tri implique la production de séquences pré-classées (dont la taille est généralement liée à la quantité de mémoire CPU disponible), suivie par une passe de fusion qui est généralement organisée de façon très intelligente @footnote{
Les algorithmes de répartition de charge pour les disques, courants de nos jours, sont plus embêtants qu'utiles, en raison de la capacité des disques à réaliser des accès aléatoires. Sur les périphériques qui ne peuvent faire que de la lecture séquentielle, comme les gros lecteurs à bandes, le besoin était différent et il fallait être malin pour s'assurer (bien à l'avance) que chaque mouvement de bande serait le plus efficace possible (c'est-à-dire participerait au mieux à l'« avancée » de la fusion). Certaines cassettes pouvaient même lire à l'envers et cela était aussi utilisé pour éviter de remonter dans le temps. Croyez-moi, les bons tris sur bandes étaient spectaculaires à regarder ! Depuis la nuit des temps, trier a toujours été le Grand Art ! ☺
}. Il est très important que le classement initial produise des séquences les plus longues possibles. Les tournois sont une bonne façon d'arriver à ce résultat. Si, en utilisant toute la mémoire disponible pour stocker un tournoi, vous remplacez et faites percoler les éléments qui s'avèrent acceptables pour la séquence courante, vous produirez des séquences d'une taille égale au double de la mémoire pour une entrée aléatoire et bien mieux pour une entrée approximativement triée.

Qui plus est, si vous écrivez l'élément 0 sur le disque et que vous recevez en entrée un élément qui n'est pas adapté au tournoi actuel (parce que sa valeur « gagne » par rapport à la dernière valeur de sortie), alors il ne peut pas être stocké dans le tas donc la taille de ce dernier diminue. La mémoire libérée peut être réutilisée immédiatement pour progressivement construire un deuxième tas, qui croit à la même vitesse que le premier décroît. Lorsque le premier tas a complètement disparu, vous échangez les tas et démarrez une nouvelle séquence. Malin et plutôt efficace !

Pour résumer, les tas sont des structures de données qu'il est bon de connaître. Je les utilise dans quelques applications et je pense qu'il est bon de garder le module `heap' sous le coude. ☺

@subsubheading Notes


@node bisect --- Array bisection algorithm,array --- Efficient arrays of numeric values,heapq --- Heap queue algorithm,Types de données
@anchor{library/bisect doc}@anchor{24bc}@anchor{library/bisect bisect-array-bisection-algorithm}@anchor{24bd}@anchor{library/bisect module-bisect}@anchor{11}
@subsection @code{bisect} --- Array bisection algorithm


@geindex module; bisect

@c example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>

`Code source :' Lib/bisect.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/bisect.py}


__________________________________________________________________


This module provides support for maintaining a list in sorted order without
having to sort the list after each insertion.  For long lists of items with
expensive comparison operations, this can be an improvement over
linear searches or frequent resorting.

The module is called @ref{11,,bisect} because it uses a basic bisection
algorithm to do its work.  Unlike other bisection tools that search for a
specific value, the functions in this module are designed to locate an
insertion point. Accordingly, the functions never call an @ref{ae8,,__eq__()}
method to determine whether a value has been found.  Instead, the
functions only call the @ref{127d,,__lt__()} method and will return an insertion
point between values in an array.
@anchor{library/bisect bisect-functions}@anchor{24be}
Les fonctions suivantes sont fournies :

@geindex bisect_left() (dans le module bisect)
@anchor{library/bisect bisect bisect_left}@anchor{24bf}
@deffn {Fonction} bisect.bisect_left (a, x, lo=0, hi=len(a), *, key=None)

Trouve le point d'insertion de `x' dans `a' permettant de conserver l'ordre. Les paramètres `lo' et `hi' permettent de limiter les emplacements à vérifier dans la liste, par défaut toute la liste est utilisée. Si `x' est déjà présent dans `a', le point d'insertion proposé sera avant (à gauche) de l'entrée existante. Si `a' est déjà triée, la valeur renvoyée peut directement être utilisée comme premier paramètre de @code{list.insert()}.

The returned insertion point `ip' partitions the array `a' into two
slices such that @code{all(elem < x for elem in a[lo : ip])} is true for the
left slice and @code{all(elem >= x for elem in a[ip : hi])} is true for the
right slice.

`key' specifies a @ref{df2,,key function} of one argument that is used to
extract a comparison key from each element in the array.  To support
searching complex records, the key function is not applied to the `x' value.

If `key' is @code{None}, the elements are compared directly and
no key function is called.


Modifié dans la version 3.10: ajout du paramètre `key'.

@end deffn

@geindex bisect_right() (dans le module bisect)
@geindex bisect() (dans le module bisect)
@anchor{library/bisect bisect bisect_right}@anchor{24c0}
@deffn {Fonction} bisect.bisect_right (a, x, lo=0, hi=len(a), *, key=None)
@anchor{library/bisect bisect bisect}@anchor{24c1}
@deffnx {Fonction} bisect.bisect (a, x, lo=0, hi=len(a), *, key=None)

Similar to @ref{24bf,,bisect_left()}, but returns an insertion point which comes
after (to the right of) any existing entries of `x' in `a'.

The returned insertion point `ip' partitions the array `a' into two slices
such that @code{all(elem <= x for elem in a[lo : ip])} is true for the left slice and
@code{all(elem > x for elem in a[ip : hi])} is true for the right slice.


Modifié dans la version 3.10: ajout du paramètre `key'.

@end deffn

@geindex insort_left() (dans le module bisect)
@anchor{library/bisect bisect insort_left}@anchor{24c2}
@deffn {Fonction} bisect.insort_left (a, x, lo=0, hi=len(a), *, key=None)

Insère `x' dans `a' en préservant l'ordre.

This function first runs @ref{24bf,,bisect_left()} to locate an insertion point.
Next, it runs the @code{insert()} method on `a' to insert `x' at the
appropriate position to maintain sort order.

To support inserting records in a table, the `key' function (if any) is
applied to `x' for the search step but not for the insertion step.

Keep in mind that the `O'(log `n') search is dominated by the slow `O'(`n')
insertion step.


Modifié dans la version 3.10: ajout du paramètre `key'.

@end deffn

@geindex insort_right() (dans le module bisect)
@geindex insort() (dans le module bisect)
@anchor{library/bisect bisect insort_right}@anchor{24c3}
@deffn {Fonction} bisect.insort_right (a, x, lo=0, hi=len(a), *, key=None)
@anchor{library/bisect bisect insort}@anchor{24c4}
@deffnx {Fonction} bisect.insort (a, x, lo=0, hi=len(a), *, key=None)

Similar to @ref{24c2,,insort_left()}, but inserting `x' in `a' after any existing
entries of `x'.

This function first runs @ref{24c0,,bisect_right()} to locate an insertion point.
Next, it runs the @code{insert()} method on `a' to insert `x' at the
appropriate position to maintain sort order.

To support inserting records in a table, the `key' function (if any) is
applied to `x' for the search step but not for the insertion step.

Keep in mind that the `O'(log `n') search is dominated by the slow `O'(`n')
insertion step.


Modifié dans la version 3.10: ajout du paramètre `key'.

@end deffn

@menu
* Notes sur la performance:: 
* Chercher dans des listes triées:: 
* Exemples: Exemples<3>. 

@end menu

@node Notes sur la performance,Chercher dans des listes triées,,bisect --- Array bisection algorithm
@anchor{library/bisect performance-notes}@anchor{24c5}
@subsubsection Notes sur la performance


Pour écrire du code sensible à la performance utilisant @code{bisect()} et @code{insort()}, prenez en compte ces quelques considérations :


@itemize *

@item 
La bissection est une bonne idée pour rechercher une plage de valeurs. Pour une seule valeur, mieux vaut un dictionnaire.

@item 
The `insort()' functions are `O'(`n') because the logarithmic search step
is dominated by the linear time insertion step.

@item 
The search functions are stateless and discard key function results after
they are used.  Consequently, if the search functions are used in a loop,
the key function may be called again and again on the same array elements.
If the key function isn't fast, consider wrapping it with
@ref{24c6,,functools.cache()} to avoid duplicate computations.  Alternatively,
consider searching an array of precomputed keys to locate the insertion
point (as shown in the examples section below).
@end itemize


@subsubheading Voir aussi



@itemize *

@item 
Sorted Collections@footnote{https://grantjenks.com/docs/sortedcollections/} is a high performance
module that uses `bisect' to managed sorted collections of data.

@item 
SortedCollection recipe@footnote{https://code.activestate.com/recipes/577197-sortedcollection/} utilise le module `bisect' pour construire une classe collection exposant des méthodes de recherches naturelles et gérant une fonction clef.  Les clefs sont pré-calculées pour économiser des appels inutiles à la fonction clef durant les recherches.
@end itemize


@node Chercher dans des listes triées,Exemples<3>,Notes sur la performance,bisect --- Array bisection algorithm
@anchor{library/bisect searching-sorted-lists}@anchor{24c7}
@subsubsection Chercher dans des listes triées


The above @ref{24be,,bisect functions} are useful for finding insertion points but
can be tricky or awkward to use for common searching tasks. The following five
functions show how to transform them into the standard lookups for sorted
lists:

@example
def index(a, x):
    'Locate the leftmost value exactly equal to x'
    i = bisect_left(a, x)
    if i != len(a) and a[i] == x:
        return i
    raise ValueError

def find_lt(a, x):
    'Find rightmost value less than x'
    i = bisect_left(a, x)
    if i:
        return a[i-1]
    raise ValueError

def find_le(a, x):
    'Find rightmost value less than or equal to x'
    i = bisect_right(a, x)
    if i:
        return a[i-1]
    raise ValueError

def find_gt(a, x):
    'Find leftmost value greater than x'
    i = bisect_right(a, x)
    if i != len(a):
        return a[i]
    raise ValueError

def find_ge(a, x):
    'Find leftmost item greater than or equal to x'
    i = bisect_left(a, x)
    if i != len(a):
        return a[i]
    raise ValueError
@end example

@node Exemples<3>,,Chercher dans des listes triées,bisect --- Array bisection algorithm
@anchor{library/bisect examples}@anchor{24c8}
@subsubsection Exemples

@anchor{library/bisect bisect-example}@anchor{24c9}
The @ref{24c1,,bisect()} function can be useful for numeric table lookups. This
example uses @ref{24c1,,bisect()} to look up a letter grade for an exam score (say)
based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
a 'B', and so on:

@example
>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
...     i = bisect(breakpoints, score)
...     return grades[i]
...
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
@end example

The @ref{24c1,,bisect()} and @ref{24c4,,insort()} functions also work with
lists of tuples.  The `key' argument can serve to extract the field used for ordering
records in a table:

@example
>>> from collections import namedtuple
>>> from operator import attrgetter
>>> from bisect import bisect, insort
>>> from pprint import pprint

>>> Movie = namedtuple('Movie', ('name', 'released', 'director'))

>>> movies = [
...     Movie('Jaws', 1975, 'Spielberg'),
...     Movie('Titanic', 1997, 'Cameron'),
...     Movie('The Birds', 1963, 'Hitchcock'),
...     Movie('Aliens', 1986, 'Cameron')
... ]

>>> # Find the first movie released after 1960
>>> by_year = attrgetter('released')
>>> movies.sort(key=by_year)
>>> movies[bisect(movies, 1960, key=by_year)]
Movie(name='The Birds', released=1963, director='Hitchcock')

>>> # Insert a movie while maintaining sort order
>>> romance = Movie('Love Story', 1970, 'Hiller')
>>> insort(movies, romance, key=by_year)
>>> pprint(movies)
[Movie(name='The Birds', released=1963, director='Hitchcock'),
 Movie(name='Love Story', released=1970, director='Hiller'),
 Movie(name='Jaws', released=1975, director='Spielberg'),
 Movie(name='Aliens', released=1986, director='Cameron'),
 Movie(name='Titanic', released=1997, director='Cameron')]
@end example

If the key function is expensive, it is possible to avoid repeated function
calls by searching a list of precomputed keys to find the index of a record:

@example
>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])       # Or use operator.itemgetter(1).
>>> keys = [r[1] for r in data]         # Precompute a list of keys.
>>> data[bisect_left(keys, 0)]
('black', 0)
>>> data[bisect_left(keys, 1)]
('blue', 1)
>>> data[bisect_left(keys, 5)]
('red', 5)
>>> data[bisect_left(keys, 8)]
('yellow', 8)
@end example

@node array --- Efficient arrays of numeric values,weakref --- Weak references,bisect --- Array bisection algorithm,Types de données
@anchor{library/array doc}@anchor{24ca}@anchor{library/array array-efficient-arrays-of-numeric-values}@anchor{24cb}@anchor{library/array module-array}@anchor{7}
@subsection @code{array} --- Efficient arrays of numeric values


@geindex module; array

@geindex arrays


__________________________________________________________________


This module defines an object type which can compactly represent an array of
basic values: characters, integers, floating-point numbers.  Arrays are sequence
types and behave very much like lists, except that the type of objects stored in
them is constrained.  The type is specified at object creation time by using a
`type code', which is a single character.  The following type codes are
defined:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Code d'indication du type

@tab

Type C

@tab

Type Python

@tab

Taille minimum en octets

@tab

Notes

@item

@code{'b'}

@tab

@code{signed char}

@tab

`int'

@tab

1

@tab

@item

@code{'B'}

@tab

@code{unsigned char}

@tab

`int'

@tab

1

@tab

@item

@code{'u'}

@tab

wchar_t

@tab

Caractère Unicode

@tab

2

@tab

(1)

@item

@code{'w'}

@tab

Py_UCS4

@tab

Caractère Unicode

@tab

4

@tab

@item

@code{'h'}

@tab

@code{signed short}

@tab

`int'

@tab

2

@tab

@item

@code{'H'}

@tab

@code{unsigned short}

@tab

`int'

@tab

2

@tab

@item

@code{'i'}

@tab

@code{signed int}

@tab

`int'

@tab

2

@tab

@item

@code{'I'}

@tab

@code{unsigned int}

@tab

`int'

@tab

2

@tab

@item

@code{'l'}

@tab

@code{signed long}

@tab

`int'

@tab

4

@tab

@item

@code{'L'}

@tab

@code{unsigned long}

@tab

`int'

@tab

4

@tab

@item

@code{'q'}

@tab

@code{signed long long}

@tab

`int'

@tab

8

@tab

@item

@code{'Q'}

@tab

@code{unsigned long long}

@tab

`int'

@tab

8

@tab

@item

@code{'f'}

@tab

`float'

@tab

`float'

@tab

4

@tab

@item

@code{'d'}

@tab

double

@tab

`float'

@tab

8

@tab

@end multitable


Notes :


@enumerate 

@item 
It can be 16 bits or 32 bits depending on the platform.


Modifié dans la version 3.9: @code{array('u')} now uses @code{wchar_t} as C type instead of deprecated
@code{Py_UNICODE}. This change doesn't affect its behavior because
@code{Py_UNICODE} is alias of @code{wchar_t} since Python 3.3.



Deprecated since version 3.3, will be removed in version 3.16: Please migrate to @code{'w'} typecode.

@end enumerate

The actual representation of values is determined by the machine architecture
(strictly speaking, by the C implementation).  The actual size can be accessed
through the @ref{24cc,,array.itemsize} attribute.

The module defines the following item:

@geindex typecodes (dans le module array)
@anchor{library/array array typecodes}@anchor{24cd}
@deffn {Données} array.typecodes

Une chaîne avec tous les codes de types disponibles.
@end deffn

Le module définit le type suivant :

@geindex array (classe dans array)
@anchor{library/array array array}@anchor{19e}
@deffn {Classe} array.array (typecode[, initializer])

A new array whose items are restricted by `typecode', and initialized
from the optional `initializer' value, which must be a @ref{1bd,,bytes}
or @ref{528,,bytearray} object, a Unicode string, or iterable over elements
of the appropriate type.

If given a @ref{1bd,,bytes} or @ref{528,,bytearray} object, the initializer
is passed to the new array's @ref{1250,,frombytes()} method;
if given a Unicode string, the initializer is passed to the
@ref{24ce,,fromunicode()} method;
otherwise, the initializer's iterator is passed to the @ref{24cf,,extend()} method
to add initial items to the array.

Les objets de tableau supportent les opérations classiques de séquence : indiçage, découpage, concaténation et multiplication. Lors de l'utilisation de tranche, la valeur assignée doit être un tableau du même type ; dans tous les autres cas, l'exception @ref{522,,TypeError} est levée. Les objets de tableau implémentent également l'interface tampon, et peuvent être utilisés partout où @ref{d1b,,bytes-like objects} sont supportés.

Lève un @ref{1848,,événement d'audit} @code{array.__new__} avec les arguments @code{typecode}, @code{initializer}.

@geindex typecode (attribut array.array)
@anchor{library/array array array typecode}@anchor{24d0}
@deffn {Attribut} typecode

Le code (de type Python caractère) utilisé pour spécifier le type des éléments du tableau.
@end deffn

@geindex itemsize (attribut array.array)
@anchor{library/array array array itemsize}@anchor{24cc}
@deffn {Attribut} itemsize

La longueur en octets d'un élément du tableau dans la représentation interne.
@end deffn

@geindex append() (méthode array.array)
@anchor{library/array array array append}@anchor{24d1}
@deffn {Méthode} append (x)

Ajoute un nouvel élément avec la valeur `x' à la fin du tableau.
@end deffn

@geindex buffer_info() (méthode array.array)
@anchor{library/array array array buffer_info}@anchor{24d2}
@deffn {Méthode} buffer_info ()

Return a tuple @code{(address, length)} giving the current memory address and the
length in elements of the buffer used to hold array's contents.  The size of the
memory buffer in bytes can be computed as @code{array.buffer_info()[1] *
array.itemsize}.  This is occasionally useful when working with low-level (and
inherently unsafe) I/O interfaces that require memory addresses, such as certain
@code{ioctl()} operations.  The returned numbers are valid as long as the array
exists and no length-changing operations are applied to it.

@cartouche
@quotation Note 
Lors de l'utilisation d'objets tableaux provenant de codes écrits en C ou C++ (le seul moyen d'utiliser efficacement ces informations), il est plus logique d'utiliser l'interface tampon supportée par les objets tableaux. Cette méthode est maintenue pour des raisons de rétrocompatibilité et devrait être évitée dans un nouveau code. L'interface tampon est documentée dans @ref{38e,,Protocole tampon}.
@end quotation
@end cartouche
@end deffn

@geindex byteswap() (méthode array.array)
@anchor{library/array array array byteswap}@anchor{24d3}
@deffn {Méthode} byteswap ()

Boutisme de tous les éléments du tableau. Ceci n'est pris en charge que pour les valeurs de 1, 2, 4 ou 8 octets ; pour les autres types de valeur, @ref{193,,RuntimeError} est levée. Il est utile lors de la lecture de données à partir d'un fichier écrit sur une machine avec un ordre d'octets différent.
@end deffn

@geindex count() (méthode array.array)
@anchor{library/array array array count}@anchor{24d4}
@deffn {Méthode} count (x)

Renvoi le nombre d'occurrences de `x' dans le tableau.
@end deffn

@geindex extend() (méthode array.array)
@anchor{library/array array array extend}@anchor{24cf}
@deffn {Méthode} extend (iterable)

Ajoute les éléments de `iterable' à la fin du tableau. Si `iterable' est un autre tableau, il doit le même code d'indication du type ; dans le cas contraire, @ref{522,,TypeError} sera levée. Si `iterable' n'est pas un tableau, il doit être itérable et ces éléments doivent être du bon type pour être ajoutés dans le tableau.
@end deffn

@geindex frombytes() (méthode array.array)
@anchor{library/array array array frombytes}@anchor{1250}
@deffn {Méthode} frombytes (buffer)

Appends items from the @ref{d1b,,bytes-like object}, interpreting
its content as an array of machine values (as if it had been read
from a file using the @ref{129e,,fromfile()} method).


Ajouté dans la version 3.2: @code{fromstring()} is renamed to @ref{1250,,frombytes()} for clarity.

@end deffn

@geindex fromfile() (méthode array.array)
@anchor{library/array array array fromfile}@anchor{129e}
@deffn {Méthode} fromfile (f, n)

Read `n' items (as machine values) from the @ref{11a0,,file object} `f' and append
them to the end of the array.  If less than `n' items are available,
@ref{12b7,,EOFError} is raised, but the items that were available are still
inserted into the array.
@end deffn

@geindex fromlist() (méthode array.array)
@anchor{library/array array array fromlist}@anchor{24d5}
@deffn {Méthode} fromlist (list)

Ajoute les éléments de la liste. C'est l'équivalent de @code{for x in list: a.append(x)} sauf que s'il y a une erreur de type, le tableau est inchangé.
@end deffn

@geindex fromunicode() (méthode array.array)
@anchor{library/array array array fromunicode}@anchor{24ce}
@deffn {Méthode} fromunicode (s)

Extends this array with data from the given Unicode string.
The array must have type code @code{'u'} or @code{'w'}; otherwise a @ref{1ff,,ValueError} is raised.
Use @code{array.frombytes(unicodestring.encode(enc))} to append Unicode data to an
array of some other type.
@end deffn

@geindex index() (méthode array.array)
@anchor{library/array array array index}@anchor{7ca}
@deffn {Méthode} index (x[, start[, stop]])

Return the smallest `i' such that `i' is the index of the first occurrence of
`x' in the array.  The optional arguments `start' and `stop' can be
specified to search for `x' within a subsection of the array.  Raise
@ref{1ff,,ValueError} if `x' is not found.


Modifié dans la version 3.10: Added optional `start' and `stop' parameters.

@end deffn

@geindex insert() (méthode array.array)
@anchor{library/array array array insert}@anchor{24d6}
@deffn {Méthode} insert (i, x)

Ajoute un nouvel élément avec la valeur `x' dans le tableau avant la position `i'. Les valeurs négatives sont traitées relativement à la fin du tableau.
@end deffn

@geindex pop() (méthode array.array)
@anchor{library/array array array pop}@anchor{24d7}
@deffn {Méthode} pop ([i])

Supprime l'élément du tableau avec l'index `i' et le renvoie. L'argument optionnel par défaut est à @code{-1}, de sorte que par défaut le dernier élément est supprimé et renvoyé.
@end deffn

@geindex remove() (méthode array.array)
@anchor{library/array array array remove}@anchor{24d8}
@deffn {Méthode} remove (x)

Supprime la première occurrence de `x' du tableau.
@end deffn

@geindex clear() (méthode array.array)
@anchor{library/array array array clear}@anchor{1a0}
@deffn {Méthode} clear ()

Remove all elements from the array.


Ajouté dans la version 3.13.

@end deffn

@geindex reverse() (méthode array.array)
@anchor{library/array array array reverse}@anchor{24d9}
@deffn {Méthode} reverse ()

Inverse l'ordre des éléments du tableau.
@end deffn

@geindex tobytes() (méthode array.array)
@anchor{library/array array array tobytes}@anchor{124f}
@deffn {Méthode} tobytes ()

Convertit le tableau en un tableau de valeurs machine et renvoie la représentation en octets (la même séquence d'octets qui serait écrite par la méthode @ref{129f,,tofile()}).


Ajouté dans la version 3.2: @code{tostring()} is renamed to @ref{124f,,tobytes()} for clarity.

@end deffn

@geindex tofile() (méthode array.array)
@anchor{library/array array array tofile}@anchor{129f}
@deffn {Méthode} tofile (f)

Écrit tous les éléments (en tant que valeurs machine) du @ref{11a0,,file object} `f'.
@end deffn

@geindex tolist() (méthode array.array)
@anchor{library/array array array tolist}@anchor{24da}
@deffn {Méthode} tolist ()

Convertit le tableau en une liste ordinaire avec les mêmes éléments.
@end deffn

@geindex tounicode() (méthode array.array)
@anchor{library/array array array tounicode}@anchor{24db}
@deffn {Méthode} tounicode ()

Convert the array to a Unicode string.  The array must have a type @code{'u'} or @code{'w'};
otherwise a @ref{1ff,,ValueError} is raised. Use @code{array.tobytes().decode(enc)} to
obtain a Unicode string from an array of some other type.
@end deffn
@end deffn

The string representation of array objects has the form
@code{array(typecode, initializer)}.
The `initializer' is omitted if the array is empty, otherwise it is
a Unicode string if the `typecode' is @code{'u'} or @code{'w'}, otherwise it is
a list of numbers.
The string representation is guaranteed to be able to be converted back to an
array with the same type and value using @ref{17e,,eval()}, so long as the
@ref{19e,,array} class has been imported using @code{from array import array}.
Variables @code{inf} and @code{nan} must also be defined if it contains
corresponding floating-point values.
Examples:

@example
array('l')
array('w', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14, -inf, nan])
@end example


@subsubheading Voir aussi



@table @asis

@item Module @ref{d4,,struct}

Empaquetage et dépaquetage de données binaires hétérogènes.

@item NumPy@footnote{https://numpy.org/}

The NumPy package defines another array type.
@end table


@node weakref --- Weak references,types --- Dynamic type creation and names for built-in types,array --- Efficient arrays of numeric values,Types de données
@anchor{library/weakref doc}@anchor{24dc}@anchor{library/weakref mod-weakref}@anchor{ef5}@anchor{library/weakref module-weakref}@anchor{113}@anchor{library/weakref weakref-weak-references}@anchor{24dd}
@subsection @code{weakref} --- Weak references


@geindex module; weakref

`Code source :' Lib/weakref.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/weakref.py}


__________________________________________________________________


The @ref{113,,weakref} module allows the Python programmer to create `weak
references' to objects.

@c When making changes to the examples in this file, be sure to update
@c Lib/test/test_weakref.py::libreftest too!

In the following, the term `referent' means the object which is referred to
by a weak reference.

A weak reference to an object is not enough to keep the object alive: when the
only remaining references to a referent are weak references,
@ref{18a7,,garbage collection} is free to destroy the referent and reuse its memory
for something else.  However, until the object is actually destroyed the weak
reference may return the object even if there are no strong references to it.

A primary use for weak references is to implement caches or
mappings holding large objects, where it's desired that a large object not be
kept alive solely because it appears in a cache or mapping.

For example, if you have a number of large binary image objects, you may wish to
associate a name with each.  If you used a Python dictionary to map names to
images, or images to names, the image objects would remain alive just because
they appeared as values or keys in the dictionaries.  The
@ref{18fc,,WeakKeyDictionary} and @ref{18fb,,WeakValueDictionary} classes supplied by
the @ref{113,,weakref} module are an alternative, using weak references to construct
mappings that don't keep objects alive solely because they appear in the mapping
objects.  If, for example, an image object is a value in a
@ref{18fb,,WeakValueDictionary}, then when the last remaining references to that
image object are the weak references held by weak mappings, garbage collection
can reclaim the object, and its corresponding entries in weak mappings are
simply deleted.

@ref{18fc,,WeakKeyDictionary} and @ref{18fb,,WeakValueDictionary} use weak references
in their implementation, setting up callback functions on the weak references
that notify the weak dictionaries when a key or value has been reclaimed by
garbage collection.  @ref{5c7,,WeakSet} implements the @ref{5c3,,set} interface,
but keeps weak references to its elements, just like a
@ref{18fc,,WeakKeyDictionary} does.

@ref{a6a,,finalize} provides a straight forward way to register a
cleanup function to be called when an object is garbage collected.
This is simpler to use than setting up a callback function on a raw
weak reference, since the module automatically ensures that the finalizer
remains alive until the object is collected.

Most programs should find that using one of these weak container types
or @ref{a6a,,finalize} is all they need -- it's not usually necessary to
create your own weak references directly.  The low-level machinery is
exposed by the @ref{113,,weakref} module for the benefit of advanced uses.

Not all objects can be weakly referenced. Objects which support weak references
include class instances, functions written in Python (but not in C), instance methods,
sets, frozensets, some @ref{11a0,,file objects}, @ref{104a,,generators},
type objects, sockets, arrays, deques, regular expression pattern objects, and code
objects.


Modifié dans la version 3.2: Added support for thread.lock, threading.Lock, and code objects.


Several built-in types such as @ref{5fc,,list} and @ref{253,,dict} do not directly
support weak references but can add support through subclassing:

@example
class Dict(dict):
    pass

obj = Dict(red=1, green=2, blue=3)   # this object is weak referenceable
@end example

`Particularité de l'implémentation CPython :' Other built-in types such as @ref{366,,tuple} and @ref{254,,int} do not support weak
references even when subclassed.

Extension types can easily be made to support weak references; see
@ref{24de,,Prise en charge de la référence faible}.

When @code{__slots__} are defined for a given type, weak reference support is
disabled unless a @code{'__weakref__'} string is also present in the sequence of
strings in the @code{__slots__} declaration.
See @ref{1eb5,,__slots__ documentation} for details.

@geindex ref (classe dans weakref)
@anchor{library/weakref weakref ref}@anchor{fd9}
@deffn {Classe} weakref.ref (object[, callback])

Return a weak reference to `object'.  The original object can be retrieved by
calling the reference object if the referent is still alive; if the referent is
no longer alive, calling the reference object will cause @ref{660,,None} to be
returned.  If `callback' is provided and not @ref{660,,None}, and the returned
weakref object is still alive, the callback will be called when the object is
about to be finalized; the weak reference object will be passed as the only
parameter to the callback; the referent will no longer be available.

It is allowable for many weak references to be constructed for the same object.
Callbacks registered for each weak reference will be called from the most
recently registered callback to the oldest registered callback.

Exceptions raised by the callback will be noted on the standard error output,
but cannot be propagated; they are handled in exactly the same way as exceptions
raised from an object's @ref{1ee3,,__del__()} method.

Weak references are @ref{5fb,,hashable} if the `object' is hashable.  They will
maintain their hash value even after the `object' was deleted.  If
@ref{5d5,,hash()} is called the first time only after the `object' was deleted,
the call will raise @ref{522,,TypeError}.

Weak references support tests for equality, but not ordering.  If the referents
are still alive, two references have the same equality relationship as their
referents (regardless of the `callback').  If either referent has been deleted,
the references are equal only if the reference objects are the same object.

This is a subclassable type rather than a factory function.

@geindex __callback__ (attribut weakref.ref)
@anchor{library/weakref weakref ref __callback__}@anchor{fda}
@deffn {Attribut} __callback__

This read-only attribute returns the callback currently associated to the
weakref.  If there is no callback or if the referent of the weakref is
no longer alive then this attribute will have value @code{None}.
@end deffn


Modifié dans la version 3.4: Added the @ref{fda,,__callback__} attribute.

@end deffn

@geindex proxy() (dans le module weakref)
@anchor{library/weakref weakref proxy}@anchor{a40}
@deffn {Fonction} weakref.proxy (object[, callback])

Return a proxy to `object' which uses a weak reference.  This supports use of
the proxy in most contexts instead of requiring the explicit dereferencing used
with weak reference objects.  The returned object will have a type of either
@code{ProxyType} or @code{CallableProxyType}, depending on whether `object' is
callable.  Proxy objects are not @ref{5fb,,hashable} regardless of the referent; this
avoids a number of problems related to their fundamentally mutable nature, and
prevents their use as dictionary keys.  `callback' is the same as the parameter
of the same name to the @ref{fd9,,ref()} function.

Accessing an attribute of the proxy object after the referent is
garbage collected raises @ref{14c5,,ReferenceError}.


Modifié dans la version 3.8: Extended the operator support on proxy objects to include the matrix
multiplication operators @code{@@} and @code{@@=}.

@end deffn

@geindex getweakrefcount() (dans le module weakref)
@anchor{library/weakref weakref getweakrefcount}@anchor{24df}
@deffn {Fonction} weakref.getweakrefcount (object)

Return the number of weak references and proxies which refer to `object'.
@end deffn

@geindex getweakrefs() (dans le module weakref)
@anchor{library/weakref weakref getweakrefs}@anchor{24e0}
@deffn {Fonction} weakref.getweakrefs (object)

Return a list of all weak reference and proxy objects which refer to `object'.
@end deffn

@geindex WeakKeyDictionary (classe dans weakref)
@anchor{library/weakref weakref WeakKeyDictionary}@anchor{18fc}
@deffn {Classe} weakref.WeakKeyDictionary ([dict])

Mapping class that references keys weakly.  Entries in the dictionary will be
discarded when there is no longer a strong reference to the key.  This can be
used to associate additional data with an object owned by other parts of an
application without adding attributes to those objects.  This can be especially
useful with objects that override attribute accesses.

Note that when a key with equal value to an existing key (but not equal identity)
is inserted into the dictionary, it replaces the value but does not replace the
existing key. Due to this, when the reference to the original key is deleted, it
also deletes the entry in the dictionary:

@example
>>> class T(str): pass
...
>>> k1, k2 = T(), T()
>>> d = weakref.WeakKeyDictionary()
>>> d[k1] = 1   # d = @{k1: 1@}
>>> d[k2] = 2   # d = @{k1: 2@}
>>> del k1      # d = @{@}
@end example

A workaround would be to remove the key prior to reassignment:

@example
>>> class T(str): pass
...
>>> k1, k2 = T(), T()
>>> d = weakref.WeakKeyDictionary()
>>> d[k1] = 1   # d = @{k1: 1@}
>>> del d[k1]
>>> d[k2] = 2   # d = @{k2: 2@}
>>> del k1      # d = @{k2: 2@}
@end example


Modifié dans la version 3.9: Added support for @code{|} and @code{|=} operators, as specified in 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn

@ref{18fc,,WeakKeyDictionary} objects have an additional method that
exposes the internal references directly.  The references are not guaranteed to
be "live" at the time they are used, so the result of calling the references
needs to be checked before being used.  This can be used to avoid creating
references that will cause the garbage collector to keep the keys around longer
than needed.

@geindex keyrefs() (méthode weakref.WeakKeyDictionary)
@anchor{library/weakref weakref WeakKeyDictionary keyrefs}@anchor{24e1}
@deffn {Méthode} WeakKeyDictionary.keyrefs ()

Return an iterable of the weak references to the keys.
@end deffn

@geindex WeakValueDictionary (classe dans weakref)
@anchor{library/weakref weakref WeakValueDictionary}@anchor{18fb}
@deffn {Classe} weakref.WeakValueDictionary ([dict])

Mapping class that references values weakly.  Entries in the dictionary will be
discarded when no strong reference to the value exists any more.


Modifié dans la version 3.9: Added support for @code{|} and @code{|=} operators, as specified in 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn

@ref{18fb,,WeakValueDictionary} objects have an additional method that has the
same issues as the @ref{24e1,,WeakKeyDictionary.keyrefs()} method.

@geindex valuerefs() (méthode weakref.WeakValueDictionary)
@anchor{library/weakref weakref WeakValueDictionary valuerefs}@anchor{24e2}
@deffn {Méthode} WeakValueDictionary.valuerefs ()

Return an iterable of the weak references to the values.
@end deffn

@geindex WeakSet (classe dans weakref)
@anchor{library/weakref weakref WeakSet}@anchor{5c7}
@deffn {Classe} weakref.WeakSet ([elements])

Set class that keeps weak references to its elements.  An element will be
discarded when no strong reference to it exists any more.
@end deffn

@geindex WeakMethod (classe dans weakref)
@anchor{library/weakref weakref WeakMethod}@anchor{fd8}
@deffn {Classe} weakref.WeakMethod (method[, callback])

A custom @ref{fd9,,ref} subclass which simulates a weak reference to a bound
method (i.e., a method defined on a class and looked up on an instance).
Since a bound method is ephemeral, a standard weak reference cannot keep
hold of it.  @ref{fd8,,WeakMethod} has special code to recreate the bound
method until either the object or the original function dies:

@example
>>> class C:
...     def method(self):
...         print("method called!")
...
>>> c = C()
>>> r = weakref.ref(c.method)
>>> r()
>>> r = weakref.WeakMethod(c.method)
>>> r()
<bound method C.method of <__main__.C object at 0x7fc859830220>>
>>> r()()
method called!
>>> del c
>>> gc.collect()
0
>>> r()
>>>
@end example

`callback' is the same as the parameter of the same name to the @ref{fd9,,ref()} function.


Ajouté dans la version 3.4.

@end deffn

@geindex finalize (classe dans weakref)
@anchor{library/weakref weakref finalize}@anchor{a6a}
@deffn {Classe} weakref.finalize (obj, func, /, *args, **kwargs)

Return a callable finalizer object which will be called when `obj'
is garbage collected. Unlike an ordinary weak reference, a finalizer
will always survive until the reference object is collected, greatly
simplifying lifecycle management.

A finalizer is considered `alive' until it is called (either explicitly
or at garbage collection), and after that it is `dead'.  Calling a live
finalizer returns the result of evaluating @code{func(*arg, **kwargs)},
whereas calling a dead finalizer returns @ref{660,,None}.

Exceptions raised by finalizer callbacks during garbage collection
will be shown on the standard error output, but cannot be
propagated.  They are handled in the same way as exceptions raised
from an object's @ref{1ee3,,__del__()} method or a weak reference's
callback.

When the program exits, each remaining live finalizer is called
unless its @ref{c,,atexit} attribute has been set to false.  They
are called in reverse order of creation.

A finalizer will never invoke its callback during the later part of
the @ref{14d,,interpreter shutdown} when module globals are liable to have
been replaced by @ref{660,,None}.

@geindex __call__() (méthode weakref.finalize)
@anchor{library/weakref weakref finalize __call__}@anchor{24e3}
@deffn {Méthode} __call__ ()

If `self' is alive then mark it as dead and return the result of
calling @code{func(*args, **kwargs)}.  If `self' is dead then return
@ref{660,,None}.
@end deffn

@geindex detach() (méthode weakref.finalize)
@anchor{library/weakref weakref finalize detach}@anchor{24e4}
@deffn {Méthode} detach ()

If `self' is alive then mark it as dead and return the tuple
@code{(obj, func, args, kwargs)}.  If `self' is dead then return
@ref{660,,None}.
@end deffn

@geindex peek() (méthode weakref.finalize)
@anchor{library/weakref weakref finalize peek}@anchor{24e5}
@deffn {Méthode} peek ()

If `self' is alive then return the tuple @code{(obj, func, args,
kwargs)}.  If `self' is dead then return @ref{660,,None}.
@end deffn

@geindex alive (attribut weakref.finalize)
@anchor{library/weakref weakref finalize alive}@anchor{24e6}
@deffn {Attribut} alive

Property which is true if the finalizer is alive, false otherwise.
@end deffn

@geindex atexit (attribut weakref.finalize)
@anchor{library/weakref weakref finalize atexit}@anchor{24e7}
@deffn {Attribut} atexit

A writable boolean property which by default is true.  When the
program exits, it calls all remaining live finalizers for which
@ref{24e7,,atexit} is true.  They are called in reverse order of
creation.
@end deffn

@cartouche
@quotation Note 
It is important to ensure that `func', `args' and `kwargs' do
not own any references to `obj', either directly or indirectly,
since otherwise `obj' will never be garbage collected.  In
particular, `func' should not be a bound method of `obj'.
@end quotation
@end cartouche


Ajouté dans la version 3.4.

@end deffn

@geindex ReferenceType (dans le module weakref)
@anchor{library/weakref weakref ReferenceType}@anchor{1761}
@deffn {Données} weakref.ReferenceType

The type object for weak references objects.
@end deffn

@geindex ProxyType (dans le module weakref)
@anchor{library/weakref weakref ProxyType}@anchor{1762}
@deffn {Données} weakref.ProxyType

The type object for proxies of objects which are not callable.
@end deffn

@geindex CallableProxyType (dans le module weakref)
@anchor{library/weakref weakref CallableProxyType}@anchor{1763}
@deffn {Données} weakref.CallableProxyType

The type object for proxies of callable objects.
@end deffn

@geindex ProxyTypes (dans le module weakref)
@anchor{library/weakref weakref ProxyTypes}@anchor{24e8}
@deffn {Données} weakref.ProxyTypes

Sequence containing all the type objects for proxies.  This can make it simpler
to test if an object is a proxy without being dependent on naming both proxy
types.
@end deffn


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 205

@item PEP 205@footnote{https://peps.python.org/pep-0205/} - Weak References

The proposal and rationale for this feature, including links to earlier
implementations and information about similar features in other languages.
@end table


@menu
* Objets à références faibles:: 
* Exemple: Exemple<2>. 
* Finalizer Objects:: 
* Comparing finalizers with __del__() methods: Comparing finalizers with __del__ methods. 

@end menu

@node Objets à références faibles,Exemple<2>,,weakref --- Weak references
@anchor{library/weakref weak-reference-objects}@anchor{24e9}@anchor{library/weakref weakref-objects}@anchor{24ea}
@subsubsection Objets à références faibles


Weak reference objects have no methods and no attributes besides
@ref{fda,,ref.__callback__}. A weak reference object allows the referent to be
obtained, if it still exists, by calling it:

@example
>>> import weakref
>>> class Object:
...     pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True
@end example

If the referent no longer exists, calling the reference object returns
@ref{660,,None}:

@example
>>> del o, o2
>>> print(r())
None
@end example

Testing that a weak reference object is still live should be done using the
expression @code{ref() is not None}.  Normally, application code that needs to use
a reference object should follow this pattern:

@example
# r is a weak reference object
o = r()
if o is None:
    # referent has been garbage collected
    print("Object has been deallocated; can't frobnicate.")
else:
    print("Object is still live!")
    o.do_something_useful()
@end example

Using a separate test for "liveness" creates race conditions in threaded
applications; another thread can cause a weak reference to become invalidated
before the weak reference is called; the idiom shown above is safe in threaded
applications as well as single-threaded applications.

Specialized versions of @ref{fd9,,ref} objects can be created through subclassing.
This is used in the implementation of the @ref{18fb,,WeakValueDictionary} to reduce
the memory overhead for each entry in the mapping.  This may be most useful to
associate additional information with a reference, but could also be used to
insert additional processing on calls to retrieve the referent.

This example shows how a subclass of @ref{fd9,,ref} can be used to store
additional information about an object and affect the value that's returned when
the referent is accessed:

@example
import weakref

class ExtendedRef(weakref.ref):
    def __init__(self, ob, callback=None, /, **annotations):
        super().__init__(ob, callback)
        self.__counter = 0
        for k, v in annotations.items():
            setattr(self, k, v)

    def __call__(self):
        """Return a pair containing the referent and the number of
        times the reference has been called.
        """
        ob = super().__call__()
        if ob is not None:
            self.__counter += 1
            ob = (ob, self.__counter)
        return ob
@end example

@node Exemple<2>,Finalizer Objects,Objets à références faibles,weakref --- Weak references
@anchor{library/weakref example}@anchor{24eb}@anchor{library/weakref weakref-example}@anchor{24ec}
@subsubsection Exemple


This simple example shows how an application can use object IDs to retrieve
objects that it has seen before.  The IDs of the objects can then be used in
other data structures without forcing the objects to remain alive, but the
objects can still be retrieved by ID if they do.

@c Example contributed by Tim Peters.

@example
import weakref

_id2obj_dict = weakref.WeakValueDictionary()

def remember(obj):
    oid = id(obj)
    _id2obj_dict[oid] = obj
    return oid

def id2obj(oid):
    return _id2obj_dict[oid]
@end example

@node Finalizer Objects,Comparing finalizers with __del__ methods,Exemple<2>,weakref --- Weak references
@anchor{library/weakref finalize-examples}@anchor{24ed}@anchor{library/weakref finalizer-objects}@anchor{24ee}
@subsubsection Finalizer Objects


The main benefit of using @ref{a6a,,finalize} is that it makes it simple
to register a callback without needing to preserve the returned finalizer
object.  For instance

@example
>>> import weakref
>>> class Object:
...     pass
...
>>> kenny = Object()
>>> weakref.finalize(kenny, print, "You killed Kenny!")  
<finalize object at ...; for 'Object' at ...>
>>> del kenny
You killed Kenny!
@end example

The finalizer can be called directly as well.  However the finalizer
will invoke the callback at most once.

@example
>>> def callback(x, y, z):
...     print("CALLBACK")
...     return x + y + z
...
>>> obj = Object()
>>> f = weakref.finalize(obj, callback, 1, 2, z=3)
>>> assert f.alive
>>> assert f() == 6
CALLBACK
>>> assert not f.alive
>>> f()                     # callback not called because finalizer dead
>>> del obj                 # callback not called because finalizer dead
@end example

You can unregister a finalizer using its @ref{24e4,,detach()}
method.  This kills the finalizer and returns the arguments passed to
the constructor when it was created.

@example
>>> obj = Object()
>>> f = weakref.finalize(obj, callback, 1, 2, z=3)
>>> f.detach()                                           
(<...Object object ...>, <function callback ...>, (1, 2), @{'z': 3@})
>>> newobj, func, args, kwargs = _
>>> assert not f.alive
>>> assert newobj is obj
>>> assert func(*args, **kwargs) == 6
CALLBACK
@end example

Unless you set the @ref{24e7,,atexit} attribute to
@ref{b25,,False}, a finalizer will be called when the program exits if it
is still alive.  For instance

@example
>>> obj = Object()
>>> weakref.finalize(obj, print, "obj dead or exiting")
<finalize object at ...; for 'Object' at ...>
>>> exit()
obj dead or exiting
@end example

@node Comparing finalizers with __del__ methods,,Finalizer Objects,weakref --- Weak references
@anchor{library/weakref comparing-finalizers-with-del-methods}@anchor{24ef}
@subsubsection Comparing finalizers with @code{__del__()} methods


Suppose we want to create a class whose instances represent temporary
directories.  The directories should be deleted with their contents
when the first of the following events occurs:


@itemize *

@item 
the object is garbage collected,

@item 
the object's @code{remove()} method is called, or

@item 
the program exits.
@end itemize

We might try to implement the class using a @ref{1ee3,,__del__()} method as
follows:

@example
class TempDir:
    def __init__(self):
        self.name = tempfile.mkdtemp()

    def remove(self):
        if self.name is not None:
            shutil.rmtree(self.name)
            self.name = None

    @@property
    def removed(self):
        return self.name is None

    def __del__(self):
        self.remove()
@end example

Starting with Python 3.4, @ref{1ee3,,__del__()} methods no longer prevent
reference cycles from being garbage collected, and module globals are
no longer forced to @ref{660,,None} during @ref{14d,,interpreter shutdown}.
So this code should work without any issues on CPython.

However, handling of @ref{1ee3,,__del__()} methods is notoriously implementation
specific, since it depends on internal details of the interpreter's garbage
collector implementation.

A more robust alternative can be to define a finalizer which only references
the specific functions and objects that it needs, rather than having access
to the full state of the object:

@example
class TempDir:
    def __init__(self):
        self.name = tempfile.mkdtemp()
        self._finalizer = weakref.finalize(self, shutil.rmtree, self.name)

    def remove(self):
        self._finalizer()

    @@property
    def removed(self):
        return not self._finalizer.alive
@end example

Defined like this, our finalizer only receives a reference to the details
it needs to clean up the directory appropriately. If the object never gets
garbage collected the finalizer will still be called at exit.

The other advantage of weakref based finalizers is that they can be used to
register finalizers for classes where the definition is controlled by a
third party, such as running code when a module is unloaded:

@example
import weakref, sys
def unloading_module():
    # implicit reference to the module globals from the function body
weakref.finalize(sys.modules[__name__], unloading_module)
@end example

@cartouche
@quotation Note 
If you create a finalizer object in a daemonic thread just as the program
exits then there is the possibility that the finalizer
does not get called at exit.  However, in a daemonic thread
@ref{869,,atexit.register()}, @code{try: ... finally: ...} and @code{with: ...}
do not guarantee that cleanup occurs either.
@end quotation
@end cartouche

@node types --- Dynamic type creation and names for built-in types,copy --- Shallow and deep copy operations,weakref --- Weak references,Types de données
@anchor{library/types doc}@anchor{24f0}@anchor{library/types module-types}@anchor{102}@anchor{library/types types-dynamic-type-creation-and-names-for-built-in-types}@anchor{24f1}
@subsection @code{types} --- Dynamic type creation and names for built-in types


@geindex module; types

`Code source :' Lib/types.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/types.py}


__________________________________________________________________


This module defines utility functions to assist in dynamic creation of
new types.

It also defines names for some object types that are used by the standard
Python interpreter, but not exposed as builtins like @ref{254,,int} or
@ref{435,,str} are.

Finally, it provides some additional type-related utility classes and functions
that are not fundamental enough to be builtins.

@menu
* Dynamic Type Creation:: 
* Standard Interpreter Types:: 
* Additional Utility Classes and Functions:: 
* Coroutine Utility Functions:: 

@end menu

@node Dynamic Type Creation,Standard Interpreter Types,,types --- Dynamic type creation and names for built-in types
@anchor{library/types dynamic-type-creation}@anchor{24f2}
@subsubsection Dynamic Type Creation


@geindex new_class() (dans le module types)
@anchor{library/types types new_class}@anchor{1141}
@deffn {Fonction} types.new_class (name, bases=(), kwds=None, exec_body=None)

Creates a class object dynamically using the appropriate metaclass.

The first three arguments are the components that make up a class
definition header: the class name, the base classes (in order), the
keyword arguments (such as @code{metaclass}).

The `exec_body' argument is a callback that is used to populate the
freshly created class namespace. It should accept the class namespace
as its sole argument and update the namespace directly with the class
contents. If no callback is provided, it has the same effect as passing
in @code{lambda ns: None}.


Ajouté dans la version 3.3.

@end deffn

@geindex prepare_class() (dans le module types)
@anchor{library/types types prepare_class}@anchor{1142}
@deffn {Fonction} types.prepare_class (name, bases=(), kwds=None)

Calculates the appropriate metaclass and creates the class namespace.

The arguments are the components that make up a class definition header:
the class name, the base classes (in order) and the keyword arguments
(such as @code{metaclass}).

The return value is a 3-tuple: @code{metaclass, namespace, kwds}

`metaclass' is the appropriate metaclass, `namespace' is the
prepared class namespace and `kwds' is an updated copy of the passed
in `kwds' argument with any @code{'metaclass'} entry removed. If no `kwds'
argument is passed in, this will be an empty dict.


Ajouté dans la version 3.3.



Modifié dans la version 3.6: The default value for the @code{namespace} element of the returned
tuple has changed.  Now an insertion-order-preserving mapping is
used when the metaclass does not have a @code{__prepare__} method.

@end deffn


@subsubheading Voir aussi



@table @asis

@item @ref{1ef6,,Métaclasses}

Full details of the class creation process supported by these functions

@geindex Python Enhancement Proposals; PEP 3115

@item PEP 3115@footnote{https://peps.python.org/pep-3115/} — Méta-classes dans Python 3000

introduction de la fonction automatique @code{__prepare__} de l'espace de nommage
@end table


@geindex resolve_bases() (dans le module types)
@anchor{library/types types resolve_bases}@anchor{b8a}
@deffn {Fonction} types.resolve_bases (bases)

Resolve MRO entries dynamically as specified by 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}.

This function looks for items in `bases' that are not instances of
@ref{d36,,type}, and returns a tuple where each such object that has
an @ref{1ef8,,__mro_entries__()} method is replaced with an unpacked result of
calling this method.  If a `bases' item is an instance of @ref{d36,,type},
or it doesn't have an @code{__mro_entries__()} method, then it is included in
the return tuple unchanged.


Ajouté dans la version 3.7.

@end deffn

@geindex get_original_bases() (dans le module types)
@anchor{library/types types get_original_bases}@anchor{4b7}
@deffn {Fonction} types.get_original_bases (cls, /)

Return the tuple of objects originally given as the bases of `cls' before
the @ref{1ef8,,__mro_entries__()} method has been called on any bases
(following the mechanisms laid out in 
@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/}). This is useful for
introspecting @ref{4b8,,Generics}.

For classes that have an @code{__orig_bases__} attribute, this
function returns the value of @code{cls.__orig_bases__}.
For classes without the @code{__orig_bases__} attribute,
@ref{1460,,cls.__bases__} is returned.

Exemples :

@example
from typing import TypeVar, Generic, NamedTuple, TypedDict

T = TypeVar("T")
class Foo(Generic[T]): ...
class Bar(Foo[int], float): ...
class Baz(list[str]): ...
Eggs = NamedTuple("Eggs", [("a", int), ("b", str)])
Spam = TypedDict("Spam", @{"a": int, "b": str@})

assert Bar.__bases__ == (Foo, float)
assert get_original_bases(Bar) == (Foo[int], float)

assert Baz.__bases__ == (list,)
assert get_original_bases(Baz) == (list[str],)

assert Eggs.__bases__ == (tuple,)
assert get_original_bases(Eggs) == (NamedTuple,)

assert Spam.__bases__ == (dict,)
assert get_original_bases(Spam) == (TypedDict,)

assert int.__bases__ == (object,)
assert get_original_bases(int) == (object,)
@end example


Ajouté dans la version 3.12.

@end deffn


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 560
PEP 560@footnote{https://peps.python.org/pep-0560/} — Gestion de base pour les types modules et les types génériques


@node Standard Interpreter Types,Additional Utility Classes and Functions,Dynamic Type Creation,types --- Dynamic type creation and names for built-in types
@anchor{library/types standard-interpreter-types}@anchor{24f3}
@subsubsection Standard Interpreter Types


This module provides names for many of the types that are required to
implement a Python interpreter. It deliberately avoids including some of
the types that arise only incidentally during processing such as the
@code{listiterator} type.

Typical use of these names is for @ref{42b,,isinstance()} or
@ref{7ab,,issubclass()} checks.

If you instantiate any of these types, note that signatures may vary between Python versions.

Standard names are defined for the following types:

@geindex NoneType (dans le module types)
@anchor{library/types types NoneType}@anchor{83c}
@deffn {Données} types.NoneType

The type of @ref{660,,None}.


Ajouté dans la version 3.10.

@end deffn

@geindex FunctionType (dans le module types)
@geindex LambdaType (dans le module types)
@anchor{library/types types FunctionType}@anchor{86f}
@deffn {Données} types.FunctionType
@anchor{library/types types LambdaType}@anchor{24f4}
@deffnx {Données} types.LambdaType

The type of user-defined functions and functions created by
@ref{127a,,lambda}  expressions.

Raises an @ref{1848,,auditing event} @code{function.__new__} with argument @code{code}.

The audit event only occurs for direct instantiation of function objects,
and is not raised for normal compilation.
@end deffn

@geindex GeneratorType (dans le module types)
@anchor{library/types types GeneratorType}@anchor{15be}
@deffn {Données} types.GeneratorType

The type of @ref{104a,,generator}-iterator objects, created by
generator functions.
@end deffn

@geindex CoroutineType (dans le module types)
@anchor{library/types types CoroutineType}@anchor{e74}
@deffn {Données} types.CoroutineType

The type of @ref{47b,,coroutine} objects, created by
@ref{5bb,,async def} functions.


Ajouté dans la version 3.5.

@end deffn

@geindex AsyncGeneratorType (dans le module types)
@anchor{library/types types AsyncGeneratorType}@anchor{24f5}
@deffn {Données} types.AsyncGeneratorType

The type of @ref{1fba,,asynchronous generator}-iterator objects, created by
asynchronous generator functions.


Ajouté dans la version 3.6.

@end deffn

@geindex CodeType (classe dans types)
@anchor{library/types types CodeType}@anchor{2dd}
@deffn {Classe} types.CodeType (**kwargs)

@geindex built-in function;compile

The type of @ref{1cd,,code objects} such as returned by @ref{190,,compile()}.

Raises an @ref{1848,,auditing event} @code{code.__new__} with arguments @code{code}, @code{filename}, @code{name}, @code{argcount}, @code{posonlyargcount}, @code{kwonlyargcount}, @code{nlocals}, @code{stacksize}, @code{flags}.

Note that the audited arguments may not match the names or positions
required by the initializer.  The audit event only occurs for direct
instantiation of code objects, and is not raised for normal compilation.
@end deffn

@geindex CellType (dans le module types)
@anchor{library/types types CellType}@anchor{24f6}
@deffn {Données} types.CellType

The type for cell objects: such objects are used as containers for
a function's @ref{1ec4,,closure variables}.


Ajouté dans la version 3.8.

@end deffn

@geindex MethodType (dans le module types)
@anchor{library/types types MethodType}@anchor{1787}
@deffn {Données} types.MethodType

The type of methods of user-defined class instances.
@end deffn

@geindex BuiltinFunctionType (dans le module types)
@geindex BuiltinMethodType (dans le module types)
@anchor{library/types types BuiltinFunctionType}@anchor{24f7}
@deffn {Données} types.BuiltinFunctionType
@anchor{library/types types BuiltinMethodType}@anchor{24f8}
@deffnx {Données} types.BuiltinMethodType

The type of built-in functions like @ref{619,,len()} or @ref{1327,,sys.exit()}, and
methods of built-in classes.  (Here, the term "built-in" means "written in
C".)
@end deffn

@geindex WrapperDescriptorType (dans le module types)
@anchor{library/types types WrapperDescriptorType}@anchor{b87}
@deffn {Données} types.WrapperDescriptorType

The type of methods of some built-in data types and base classes such as
@ref{69b,,object.__init__()} or @ref{127d,,object.__lt__()}.


Ajouté dans la version 3.7.

@end deffn

@geindex MethodWrapperType (dans le module types)
@anchor{library/types types MethodWrapperType}@anchor{636}
@deffn {Données} types.MethodWrapperType

The type of `bound' methods of some built-in data types and base classes.
For example it is the type of @code{object().__str__}.


Ajouté dans la version 3.7.

@end deffn

@geindex NotImplementedType (dans le module types)
@anchor{library/types types NotImplementedType}@anchor{83d}
@deffn {Données} types.NotImplementedType

The type of @ref{7bc,,NotImplemented}.


Ajouté dans la version 3.10.

@end deffn

@geindex MethodDescriptorType (dans le module types)
@anchor{library/types types MethodDescriptorType}@anchor{b88}
@deffn {Données} types.MethodDescriptorType

The type of methods of some built-in data types such as @ref{2134,,str.join()}.


Ajouté dans la version 3.7.

@end deffn

@geindex ClassMethodDescriptorType (dans le module types)
@anchor{library/types types ClassMethodDescriptorType}@anchor{b89}
@deffn {Données} types.ClassMethodDescriptorType

The type of `unbound' class methods of some built-in data types such as
@code{dict.__dict__['fromkeys']}.


Ajouté dans la version 3.7.

@end deffn

@geindex ModuleType (classe dans types)
@anchor{library/types types ModuleType}@anchor{e00}
@deffn {Classe} types.ModuleType (name, doc=None)

The type of @ref{15e8,,modules}. The constructor takes the name of the
module to be created and optionally its @ref{20aa,,docstring}.


@subsubheading Voir aussi



@table @asis

@item @ref{1e96,,Documentation on module objects}

Provides details on the special attributes that can be found on
instances of @code{ModuleType}.

@item @ref{dff,,importlib.util.module_from_spec()}

Modules created using the @code{ModuleType} constructor are
created with many of their special attributes unset or set to default
values. @code{module_from_spec()} provides a more robust way of
creating @code{ModuleType} instances which ensures the various
attributes are set appropriately.
@end table

@end deffn

@geindex EllipsisType (dans le module types)
@anchor{library/types types EllipsisType}@anchor{83b}
@deffn {Données} types.EllipsisType

The type of @ref{210e,,Ellipsis}.


Ajouté dans la version 3.10.

@end deffn

@geindex GenericAlias (classe dans types)
@anchor{library/types types GenericAlias}@anchor{7d5}
@deffn {Classe} types.GenericAlias (t_origin, t_args)

The type of @ref{69d,,parameterized generics} such as
@code{list[int]}.

@code{t_origin} should be a non-parameterized generic class, such as @code{list},
@code{tuple} or @code{dict}.  @code{t_args} should be a @ref{366,,tuple} (possibly of
length 1) of types which parameterize @code{t_origin}:

@example
>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True
@end example


Ajouté dans la version 3.9.



Modifié dans la version 3.9.2: This type can now be subclassed.



@subsubheading Voir aussi



@table @asis

@item @ref{69d,,Types alias génériques}

In-depth documentation on instances of @code{types.GenericAlias}

@geindex Python Enhancement Proposals; PEP 585

@item PEP 585@footnote{https://peps.python.org/pep-0585/} – Types génériques d'indication de type dans les conteneurs standard (page en anglais)

Introducing the @code{types.GenericAlias} class
@end table

@end deffn

@geindex UnionType (classe dans types)
@anchor{library/types types UnionType}@anchor{625}
@deffn {Classe} types.UnionType

The type of @ref{7ac,,union type expressions}.


Ajouté dans la version 3.10.

@end deffn

@geindex TracebackType (classe dans types)
@anchor{library/types types TracebackType}@anchor{ae0}
@deffn {Classe} types.TracebackType (tb_next, tb_frame, tb_lasti, tb_lineno)

The type of traceback objects such as found in @code{sys.exception().__traceback__}.

See @ref{ae2,,the language reference} for details of the
available attributes and operations, and guidance on creating tracebacks
dynamically.
@end deffn

@geindex FrameType (dans le module types)
@anchor{library/types types FrameType}@anchor{17df}
@deffn {Données} types.FrameType

The type of @ref{6ca,,frame objects} such as found in
@ref{1ed7,,tb.tb_frame} if @code{tb} is a traceback object.
@end deffn

@geindex GetSetDescriptorType (dans le module types)
@anchor{library/types types GetSetDescriptorType}@anchor{24f9}
@deffn {Données} types.GetSetDescriptorType

The type of objects defined in extension modules with @code{PyGetSetDef}, such
as @ref{180,,FrameType.f_locals} or @code{array.array.typecode}.
This type is used as
descriptor for object attributes; it has the same purpose as the
@ref{192,,property} type, but for classes defined in extension modules.
@end deffn

@geindex MemberDescriptorType (dans le module types)
@anchor{library/types types MemberDescriptorType}@anchor{24fa}
@deffn {Données} types.MemberDescriptorType

The type of objects defined in extension modules with @code{PyMemberDef}, such
as @code{datetime.timedelta.days}.  This type is used as descriptor for simple C
data members which use standard conversion functions; it has the same purpose
as the @ref{192,,property} type, but for classes defined in extension modules.

In addition, when a class is defined with a @ref{14a0,,__slots__} attribute, then for
each slot, an instance of @code{MemberDescriptorType} will be added as an attribute
on the class. This allows the slot to appear in the class's @ref{c4b,,__dict__}.

`Particularité de l'implémentation CPython :' In other implementations of Python, this type may be identical to
@code{GetSetDescriptorType}.
@end deffn

@geindex MappingProxyType (classe dans types)
@anchor{library/types types MappingProxyType}@anchor{457}
@deffn {Classe} types.MappingProxyType (mapping)

Read-only proxy of a mapping. It provides a dynamic view on the mapping's
entries, which means that when the mapping changes, the view reflects these
changes.


Ajouté dans la version 3.3.



Modifié dans la version 3.9: Updated to support the new union (@code{|}) operator from 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}, which
simply delegates to the underlying mapping.



@deffn {Describe} key in proxy

Return @code{True} if the underlying mapping has a key `key', else
@code{False}.
@end deffn


@deffn {Describe} proxy[key]

Return the item of the underlying mapping with key `key'.  Raises a
@ref{33a,,KeyError} if `key' is not in the underlying mapping.
@end deffn


@deffn {Describe} iter(proxy)

Return an iterator over the keys of the underlying mapping.  This is a
shortcut for @code{iter(proxy.keys())}.
@end deffn


@deffn {Describe} len(proxy)

Return the number of items in the underlying mapping.
@end deffn

@geindex copy() (méthode types.MappingProxyType)
@anchor{library/types types MappingProxyType copy}@anchor{24fb}
@deffn {Méthode} copy ()

Return a shallow copy of the underlying mapping.
@end deffn

@geindex get() (méthode types.MappingProxyType)
@anchor{library/types types MappingProxyType get}@anchor{24fc}
@deffn {Méthode} get (key[, default])

Return the value for `key' if `key' is in the underlying mapping, else
`default'.  If `default' is not given, it defaults to @code{None}, so that
this method never raises a @ref{33a,,KeyError}.
@end deffn

@geindex items() (méthode types.MappingProxyType)
@anchor{library/types types MappingProxyType items}@anchor{24fd}
@deffn {Méthode} items ()

Return a new view of the underlying mapping's items (@code{(key, value)}
pairs).
@end deffn

@geindex keys() (méthode types.MappingProxyType)
@anchor{library/types types MappingProxyType keys}@anchor{24fe}
@deffn {Méthode} keys ()

Return a new view of the underlying mapping's keys.
@end deffn

@geindex values() (méthode types.MappingProxyType)
@anchor{library/types types MappingProxyType values}@anchor{24ff}
@deffn {Méthode} values ()

Return a new view of the underlying mapping's values.
@end deffn


@deffn {Describe} reversed(proxy)

Return a reverse iterator over the keys of the underlying mapping.


Ajouté dans la version 3.9.

@end deffn


@deffn {Describe} hash(proxy)

Return a hash of the underlying mapping.


Ajouté dans la version 3.12.

@end deffn
@end deffn

@geindex CapsuleType (classe dans types)
@anchor{library/types types CapsuleType}@anchor{2500}
@deffn {Classe} types.CapsuleType

The type of @ref{2501,,capsule objects}.


Ajouté dans la version 3.13.

@end deffn

@node Additional Utility Classes and Functions,Coroutine Utility Functions,Standard Interpreter Types,types --- Dynamic type creation and names for built-in types
@anchor{library/types additional-utility-classes-and-functions}@anchor{2502}
@subsubsection Additional Utility Classes and Functions


@geindex SimpleNamespace (classe dans types)
@anchor{library/types types SimpleNamespace}@anchor{1cc}
@deffn {Classe} types.SimpleNamespace

A simple @ref{a7a,,object} subclass that provides attribute access to its
namespace, as well as a meaningful repr.

Unlike @ref{a7a,,object}, with @code{SimpleNamespace} you can add and remove
attributes.

@ref{1cc,,SimpleNamespace} objects may be initialized
in the same way as @ref{253,,dict}: either with keyword arguments,
with a single positional argument, or with both.
When initialized with keyword arguments,
those are directly added to the underlying namespace.
Alternatively, when initialized with a positional argument,
the underlying namespace will be updated with key-value pairs
from that argument (either a mapping object or
an @ref{1205,,iterable} object producing key-value pairs).
All such keys must be strings.

The type is roughly equivalent to the following code:

@example
class SimpleNamespace:
    def __init__(self, mapping_or_iterable=(), /, **kwargs):
        self.__dict__.update(mapping_or_iterable)
        self.__dict__.update(kwargs)

    def __repr__(self):
        items = (f"@{k@}=@{v!r@}" for k, v in self.__dict__.items())
        return "@{@}(@{@})".format(type(self).__name__, ", ".join(items))

    def __eq__(self, other):
        if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
           return self.__dict__ == other.__dict__
        return NotImplemented
@end example

@code{SimpleNamespace} may be useful as a replacement for @code{class NS: pass}.
However, for a structured record type use @ref{1c5,,namedtuple()}
instead.

@code{SimpleNamespace} objects are supported by @ref{150,,copy.replace()}.


Ajouté dans la version 3.3.



Modifié dans la version 3.9: Attribute order in the repr changed from alphabetical to insertion (like
@code{dict}).



Modifié dans la version 3.13: Added support for an optional positional argument.

@end deffn

@geindex DynamicClassAttribute() (dans le module types)
@anchor{library/types types DynamicClassAttribute}@anchor{615}
@deffn {Fonction} types.DynamicClassAttribute (fget=None, fset=None, fdel=None, doc=None)

Route attribute access on a class to __getattr__.

This is a descriptor, used to define attributes that act differently when
accessed through an instance and through a class.  Instance access remains
normal, but access to an attribute through a class will be routed to the
class's __getattr__ method; this is done by raising AttributeError.

This allows one to have properties active on an instance, and have virtual
attributes on the class with the same name (see @ref{61b,,enum.Enum} for an example).


Ajouté dans la version 3.4.

@end deffn

@node Coroutine Utility Functions,,Additional Utility Classes and Functions,types --- Dynamic type creation and names for built-in types
@anchor{library/types coroutine-utility-functions}@anchor{2503}
@subsubsection Coroutine Utility Functions


@geindex coroutine() (dans le module types)
@anchor{library/types types coroutine}@anchor{e73}
@deffn {Fonction} types.coroutine (gen_func)

This function transforms a @ref{104a,,generator} function into a
@ref{d64,,coroutine function} which returns a generator-based coroutine.
The generator-based coroutine is still a @ref{bcc,,generator iterator},
but is also considered to be a @ref{47b,,coroutine} object and is
@ref{1ab,,awaitable}.  However, it may not necessarily implement
the @ref{1f4a,,__await__()} method.

If `gen_func' is a generator function, it will be modified in-place.

If `gen_func' is not a generator function, it will be wrapped. If it
returns an instance of @ref{dc8,,collections.abc.Generator}, the instance
will be wrapped in an `awaitable' proxy object.  All other types
of objects will be returned as is.


Ajouté dans la version 3.5.

@end deffn

@node copy --- Shallow and deep copy operations,pprint — L’affichage élégant de données,types --- Dynamic type creation and names for built-in types,Types de données
@anchor{library/copy doc}@anchor{2504}@anchor{library/copy copy-shallow-and-deep-copy-operations}@anchor{2505}@anchor{library/copy module-copy}@anchor{25}
@subsection @code{copy} --- Shallow and deep copy operations


@geindex module; copy

`Code source :' Lib/copy.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/copy.py}


__________________________________________________________________


Les instructions d'affectation en Python ne copient pas les objets, elles créent des liens entre la cible et l'objet. Concernant les collections qui sont mutables ou contiennent des éléments mutables, une copie est parfois nécessaire, pour pouvoir modifier une copie sans modifier l'autre. Ce module met à disposition des opérations de copie génériques superficielle et récursive (comme expliqué ci-dessous).

Résumé de l'interface :

@geindex copy() (dans le module copy)
@anchor{library/copy copy copy}@anchor{51d}
@deffn {Fonction} copy.copy (obj)

Return a shallow copy of `obj'.
@end deffn

@geindex deepcopy() (dans le module copy)
@anchor{library/copy copy deepcopy}@anchor{b5c}
@deffn {Fonction} copy.deepcopy (obj[, memo])

Return a deep copy of `obj'.
@end deffn

@geindex replace() (dans le module copy)
@anchor{library/copy copy replace}@anchor{150}
@deffn {Fonction} copy.replace (obj, /, **changes)

Creates a new object of the same type as `obj', replacing fields with values
from `changes'.


Ajouté dans la version 3.13.

@end deffn

@geindex Error
@anchor{library/copy copy Error}@anchor{2506}
@deffn {Exception} copy.Error

Levée pour les erreurs spécifiques au module.
@end deffn
@anchor{library/copy shallow-vs-deep-copy}@anchor{1b8f}
La différence entre copie superficielle et récursive n'est pertinente que pour les objets composés (objets contenant d'autres objets, comme des listes ou des instances de classe) :


@itemize *

@item 
Une `copie superficielle' construit un nouvel objet composé puis (dans la mesure du possible) insère dans l'objet composé des `références' aux objets trouvés dans l'original.

@item 
Une `copie récursive (ou profonde)' construit un nouvel objet composé puis, récursivement, insère dans l'objet composé des `copies' des objets trouvés dans l'objet original.
@end itemize

On rencontre souvent deux problèmes avec les opérations de copie récursive qui n'existent pas avec les opérations de copie superficielle :


@itemize *

@item 
Les objets récursifs (objets composés qui, directement ou indirectement, contiennent une référence à eux-mêmes) peuvent causer une boucle récursive.

@item 
Comme une copie récursive copie tout, elle peut en copier trop, par exemple des données qui sont destinées à être partagées entre différentes copies.
@end itemize

La fonction @ref{b5c,,deepcopy()} évite ces problèmes en :


@itemize *

@item 
gardant en mémoire dans un dictionnaire @code{memo} les objets déjà copiés durant la phase de copie actuelle ; et

@item 
laissant les classes créées par l'utilisateur écraser l'opération de copie ou l'ensemble de composants copiés.
@end itemize

This module does not copy types like module, method, stack trace, stack frame,
file, socket, window, or any similar types.  It does "copy" functions and
classes (shallow and deeply), by returning the original object unchanged; this
is compatible with the way these are treated by the @ref{a5,,pickle} module.

Les copies superficielles de dictionnaires peuvent être faites en utilisant @ref{bbe,,dict.copy()}, et de listes en affectant un @code{slice} de la liste, par exemple, @code{copied_list = original_list[:]}.

@geindex module;pickle

Les classes peuvent utiliser les mêmes interfaces de contrôle que celles utilisées pour la sérialisation. Voir la description du module @ref{a5,,pickle} pour plus d'informations sur ces méthodes. En effet, le module @ref{25,,copy} utilise les fonctions de sérialisation enregistrées à partir du module @ref{26,,copyreg}.

@geindex __copy__() (copy protocol)
@geindex __deepcopy__() (copy protocol)

In order for a class to define its own copy implementation, it can define
special methods @ref{2507,,__copy__()} and @ref{2508,,__deepcopy__()}.

@anchor{library/copy object __copy__}@anchor{2507}
@deffn {Méthode} object.__copy__ (self)

Called to implement the shallow copy operation;
no additional arguments are passed.
@end deffn

@anchor{library/copy object __deepcopy__}@anchor{2508}
@deffn {Méthode} object.__deepcopy__ (self, memo)

Called to implement the deep copy operation; it is passed one
argument, the `memo' dictionary.  If the @code{__deepcopy__} implementation needs
to make a deep copy of a component, it should call the @ref{b5c,,deepcopy()} function
with the component as first argument and the `memo' dictionary as second argument.
The `memo' dictionary should be treated as an opaque object.
@end deffn

@geindex __replace__() (replace protocol)

Function @code{copy.replace()} is more limited
than @ref{51d,,copy()} and @ref{b5c,,deepcopy()},
and only supports named tuples created by @ref{1c5,,namedtuple()},
@ref{2f,,dataclasses}, and other classes which define method @ref{151,,__replace__()}.

@anchor{library/copy object __replace__}@anchor{151}
@deffn {Méthode} object.__replace__ (self, /, **changes)

This method should create a new object of the same type,
replacing fields with values from `changes'.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{a5,,pickle}

Discussion sur les méthodes spéciales utilisées pour gérer la récupération et la restauration de l'état d'un objet.
@end table


@node pprint — L’affichage élégant de données,reprlib --- Alternate repr implementation,copy --- Shallow and deep copy operations,Types de données
@anchor{library/pprint doc}@anchor{2509}@anchor{library/pprint module-pprint}@anchor{ad}@anchor{library/pprint pprint-data-pretty-printer}@anchor{250a}
@subsection @code{pprint} — L’affichage élégant de données


@geindex module; pprint

`Code source :' Lib/pprint.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pprint.py}


__________________________________________________________________


Le module @ref{ad,,pprint} permet « d’afficher élégamment » des structures de données Python arbitraires sous une forme qui peut être utilisée ensuite comme une entrée dans l’interpréteur. Si les structures formatées incluent des objets qui ne sont pas des types Python fondamentaux, leurs représentations peuvent ne pas être acceptables en tant que telles par l’interpréteur. Cela peut être le cas si des objets tels que des fichiers, des interfaces de connexion (`sockets' en anglais) ou des classes sont inclus, c’est aussi valable pour beaucoup d’autres types d’objets qui ne peuvent être représentés sous forme littérale en Python.

L’affichage formaté affiche, tant que possible, les objets sur une seule ligne et les sépare sur plusieurs lignes s’ils dépassent la largeur autorisée par l’interpréteur. Cette largeur est ajustable par le paramètre `width' qui est par défaut de 80 caractères.

Les dictionnaires sont classés par clés avant que l’affichage ne soit calculé.


Modifié dans la version 3.9: Prise en charge de l’affichage élégant de @ref{1cc,,types.SimpleNamespace}.



Modifié dans la version 3.10: Prise en charge de l’affichage élégant de @ref{1c6,,dataclasses.dataclass}.


@menu
* Fonctions: Fonctions<4>. 
* Les Objets PrettyPrinter:: 
* Exemple: Exemple<3>. 

@end menu

@node Fonctions<4>,Les Objets PrettyPrinter,,pprint — L’affichage élégant de données
@anchor{library/pprint functions}@anchor{250b}@anchor{library/pprint pprint-functions}@anchor{250c}
@subsubsection Fonctions


@geindex pp() (dans le module pprint)
@anchor{library/pprint pprint pp}@anchor{a11}
@deffn {Fonction} pprint.pp (object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=False, underscore_numbers=False)

Affiche la représentation formatée de `object', suivie d’un retour à la ligne. Cette fonction peut être utilisée dans l’interpréteur interactif au lieu de la fonction @ref{f60,,print()} pour inspecter les valeurs. Astuce : vous pouvez réassigner @code{print = pprint.pp} pour l’utiliser dans une portée.

@*Paramètres: 

@itemize *

@item 
@code{object} -- L’objet à afficher.

@item 
@code{stream} (@ref{250d,,file-like object} | None) -- Un objet fichier-compatible sur lequel la sortie sera écrite en appelant sa méthode @code{write()}. Si la valeur est @code{None} (la valeur par défaut), @ref{ac4,,sys.stdout} est utilisé.

@item 
@code{indent} (@ref{254,,int}) -- La quantité d’indentation ajoutée pour chaque niveau d’imbrication.

@item 
@code{width} (@ref{254,,int}) -- Le nombre maximal de caractères souhaités par ligne dans la sortie. Si une structure ne peut pas être formatée dans la largeur limite donnée, un effort maximal sera fait.

@item 
@code{depth} (@ref{254,,int}@code{ | }@code{None}) -- Le nombre de niveaux d’imbrication qui peuvent être affichés. Si la structure de données à afficher est trop profonde, le niveau suivant est remplacé par @code{...}. Si la valeur est @code{None} (la valeur par défaut), il n’y a pas de contrainte sur la profondeur des objets formatés.

@item 
@code{compact} (@ref{451,,bool}) -- Contrôle la façon dont les longues @ref{4db,,sequences} sont formatées. Si la valeur est @code{False} (la valeur par défaut), chaque élément d’une séquence sera formaté sur une ligne séparée, sinon autant d’éléments que possible qui peuvent tenir dans la `width' (la largeur) seront formatés sur chaque ligne de sortie.

@item 
@code{sort_dicts} (@ref{451,,bool}) -- Si la valeur est @code{True}, les dictionnaires seront formatés avec leurs clés triées, sinon ils seront affichés dans l'ordre d'insertion (la valeur par défaut).

@item 
@code{underscore_numbers} (@ref{451,,bool}) -- Si la valeur est @code{True}, les entiers seront formatés avec le caractère @code{_} comme séparateur de milliers, sinon les underscores ne sont pas affichés (le comportement par défaut).
@end itemize


@example
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pp(stuff)
[<Recursion on list with id=...>,
 'spam',
 'eggs',
 'lumberjack',
 'knights',
 'ni']
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex pprint() (dans le module pprint)
@anchor{library/pprint pprint pprint}@anchor{812}
@deffn {Fonction} pprint.pprint (object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Alias pour @ref{a11,,pp()} avec `sort_dicts' initialisé à @code{True} par défaut (ce qui trie automatiquement les clés des dictionnaires), vous pourriez préférer utiliser @ref{a11,,pp()} à la place où `sort_dicts' est initialisé à @code{False} par défaut.
@end deffn

@geindex pformat() (dans le module pprint)
@anchor{library/pprint pprint pformat}@anchor{f6b}
@deffn {Fonction} pprint.pformat (object, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Renvoie une représentation formatée de `object' sous forme de chaîne de caractères. `indent', `width', `depth', `compact', `sort_dicts' et  `underscore_numbers' sont passés au constructeur de @ref{f6a,,PrettyPrinter} comme paramètres de formatage et leurs significations sont telles que décrites dans la documentation ci-dessus.
@end deffn

@geindex isreadable() (dans le module pprint)
@anchor{library/pprint pprint isreadable}@anchor{250e}
@deffn {Fonction} pprint.isreadable (object)

@geindex built-in function;eval

Détermine si la représentation formatée de `object' est « lisible », ou s’il peut être utilisé pour recomposer sa valeur en utilisant la fonction @ref{17e,,eval()}. Cela renvoie toujours @code{False} pour les objets récursifs.

@example
>>> pprint.isreadable(stuff)
False
@end example
@end deffn

@geindex isrecursive() (dans le module pprint)
@anchor{library/pprint pprint isrecursive}@anchor{250f}
@deffn {Fonction} pprint.isrecursive (object)

Détermine si `object' nécessite une représentation récursive. Cette fonction est soumise aux mêmes limitations que celles notées dans @ref{2510,,saferepr()} ci-dessous et peut lever une exception @ref{d59,,RecursionError} si elle échoue à détecter un objet récursif.
@end deffn

@geindex saferepr() (dans le module pprint)
@anchor{library/pprint pprint saferepr}@anchor{2510}
@deffn {Fonction} pprint.saferepr (object)

Renvoie une représentation de `object', protégée contre la récursivité dans certaines structures de données courantes, à savoir que les instances de @ref{253,,dict}, @ref{5fc,,list} et @ref{366,,tuple} ou les sous-classes dont la méthode @code{__repr__} n’ont pas été surchargées. Si la représentation de `object' présente une entrée récursive, celle-ci sera représentée telle que @code{<Recursion on typename with id=number>}. Par ailleurs, la représentation de l’objet n’est pas formatée.

@example
>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
@end example
@end deffn

@node Les Objets PrettyPrinter,Exemple<3>,Fonctions<4>,pprint — L’affichage élégant de données
@anchor{library/pprint id1}@anchor{2511}@anchor{library/pprint prettyprinter-objects}@anchor{2512}
@subsubsection Les Objets PrettyPrinter


@geindex ...;placeholder

@geindex PrettyPrinter (classe dans pprint)
@anchor{library/pprint pprint PrettyPrinter}@anchor{f6a}
@deffn {Classe} pprint.PrettyPrinter (indent=1, width=80, depth=None, stream=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

Crée une instance de @ref{f6a,,PrettyPrinter}.

Les arguments ont la même signification que pour @ref{a11,,pp()}. Notez qu’ils sont dans un ordre différent, et que `sort_dicts' est initialisé à @code{True} par défaut.

@example
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
    'spam',
    'eggs',
    'lumberjack',
    'knights',
    'ni']
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
>>> pp.pprint(stuff)
[['spam', 'eggs', 'lumberjack',
  'knights', 'ni'],
 'spam', 'eggs', 'lumberjack', 'knights',
 'ni']
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
@end example


Modifié dans la version 3.4: Ajout du paramètre `compact'.



Modifié dans la version 3.8: Ajout du paramètre `sort_dicts'.



Modifié dans la version 3.10: Ajout du paramètre `underscore_numbers'.



Modifié dans la version 3.11: N'essaie plus d’écrire sur @code{sys.stdout} lorsqu'il vaut @code{None}.

@end deffn

Les instances de la classe @ref{f6a,,PrettyPrinter} ont les méthodes suivantes :

@geindex pformat() (méthode pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter pformat}@anchor{2513}
@deffn {Méthode} PrettyPrinter.pformat (object)

Renvoie la représentation formatée de `object'. Cela prend en compte les options passées au constructeur de la classe @ref{f6a,,PrettyPrinter}.
@end deffn

@geindex pprint() (méthode pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter pprint}@anchor{2514}
@deffn {Méthode} PrettyPrinter.pprint (object)

Affiche sur le flux configuré la représentation formatée de `object', suivie d’une fin de ligne.
@end deffn

Les méthodes suivantes fournissent les implémentations pour les fonctions correspondantes de mêmes noms. L’utilisation de ces méthodes sur une instance est légèrement plus efficace, car les nouveaux objets @ref{f6a,,PrettyPrinter} n’ont pas besoin d’être créés.

@geindex isreadable() (méthode pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter isreadable}@anchor{2515}
@deffn {Méthode} PrettyPrinter.isreadable (object)

@geindex built-in function;eval

Détermine si la représentation formatée de `object' est « lisible », ou si elle peut être utilisée pour recomposer sa valeur en utilisant la fonction @ref{17e,,eval()}. Cela renvoie toujours @code{False} pour les objets récursifs. Si le paramètre `depth' de la classe @ref{f6a,,PrettyPrinter} est initialisé et que l’objet est plus « profond » que permis, cela renvoie @code{False}.
@end deffn

@geindex isrecursive() (méthode pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter isrecursive}@anchor{2516}
@deffn {Méthode} PrettyPrinter.isrecursive (object)

Détermine si l’objet nécessite une représentation récursive.
@end deffn

Cette méthode est fournie sous forme de point d’entrée ou méthode (à déclenchement) automatique (`hook' en anglais) pour permettre aux sous-classes de modifier la façon dont les objets sont convertis en chaînes. L’implémentation par défaut est celle de la fonction @ref{2510,,saferepr()}.

@geindex format() (méthode pprint.PrettyPrinter)
@anchor{library/pprint pprint PrettyPrinter format}@anchor{18ac}
@deffn {Méthode} PrettyPrinter.format (object, context, maxlevels, level)

Renvoie trois valeurs : la version formatée de `object' sous forme de chaîne de caractères, une option indiquant si le résultat est « lisible », et une option indiquant si une récursion a été détectée. Le premier argument est l’objet à représenter. Le deuxième est un dictionnaire qui contient l'@ref{13d9,,id()} des objets (conteneurs directs ou indirects de `objet' qui affectent sa représentation) qui font partie du contexte de représentation courant tel que les clés; si un objet doit être représenté, mais l’a déjà été dans ce contexte, le troisième argument renvoie @code{True}. Des appels récursifs à la méthode @ref{18ac,,format()} doivent ajouter des entrés additionnelles aux conteneurs de ce dictionnaire. Le troisième argument `maxlevels', donne la limite maximale de récursivité; la valeur par défaut est @code{0}. Cet argument doit être passé non modifié pour des appels non récursifs. Le quatrième argument, `level', donne le niveau de récursivité courant; les appels récursifs doivent être passés à une valeur inférieure à celle de l’appel courant.
@end deffn

@node Exemple<3>,,Les Objets PrettyPrinter,pprint — L’affichage élégant de données
@anchor{library/pprint example}@anchor{2517}@anchor{library/pprint pprint-example}@anchor{2518}
@subsubsection Exemple


Pour illustrer quelques cas pratiques de l’utilisation de la fonction @ref{a11,,pp()} et de ses paramètres, allons chercher des informations sur un projet PyPI@footnote{https://pypi.org} :

@example
>>> import json
>>> import pprint
>>> from urllib.request import urlopen
>>> with urlopen('https://pypi.org/pypi/sampleproject/1.2.0/json') as resp:
...     project_info = json.load(resp)['info']
@end example

Dans sa forme basique, la fonction @ref{a11,,pp()} affiche l’intégralité de l’objet :

@example
>>> pprint.pp(project_info)
@{'author': 'The Python Packaging Authority',
 'author_email': 'pypa-dev@@googlegroups.com',
 'bugtrack_url': None,
 'classifiers': ['Development Status :: 3 - Alpha',
                 'Intended Audience :: Developers',
                 'License :: OSI Approved :: MIT License',
                 'Programming Language :: Python :: 2',
                 'Programming Language :: Python :: 2.6',
                 'Programming Language :: Python :: 2.7',
                 'Programming Language :: Python :: 3',
                 'Programming Language :: Python :: 3.2',
                 'Programming Language :: Python :: 3.3',
                 'Programming Language :: Python :: 3.4',
                 'Topic :: Software Development :: Build Tools'],
 'description': 'A sample Python project\n'
                '=======================\n'
                '\n'
                'This is the description file for the project.\n'
                '\n'
                'The file should use UTF-8 encoding and be written using '
                'ReStructured Text. It\n'
                'will be used to generate the project webpage on PyPI, and '
                'should be written for\n'
                'that purpose.\n'
                '\n'
                'Typical contents for this file would include an overview of '
                'the project, basic\n'
                'usage examples, etc. Generally, including the project '
                'changelog in here is not\n'
                'a good idea, although a simple "What\'s New" section for the '
                'most recent version\n'
                'may be appropriate.',
 'description_content_type': None,
 'docs_url': None,
 'download_url': 'UNKNOWN',
 'downloads': @{'last_day': -1, 'last_month': -1, 'last_week': -1@},
 'home_page': 'https://github.com/pypa/sampleproject',
 'keywords': 'sample setuptools development',
 'license': 'MIT',
 'maintainer': None,
 'maintainer_email': None,
 'name': 'sampleproject',
 'package_url': 'https://pypi.org/project/sampleproject/',
 'platform': 'UNKNOWN',
 'project_url': 'https://pypi.org/project/sampleproject/',
 'project_urls': @{'Download': 'UNKNOWN',
                  'Homepage': 'https://github.com/pypa/sampleproject'@},
 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
 'requires_dist': None,
 'requires_python': None,
 'summary': 'A sample Python project',
 'version': '1.2.0'@}
@end example

Le résultat peut être limité à une certaine profondeur en initialisant `depth'. ( @code{…} est utilisé pour des contenus plus « profonds ») :

@example
>>> pprint.pp(project_info, depth=1)
@{'author': 'The Python Packaging Authority',
 'author_email': 'pypa-dev@@googlegroups.com',
 'bugtrack_url': None,
 'classifiers': [...],
 'description': 'A sample Python project\n'
                '=======================\n'
                '\n'
                'This is the description file for the project.\n'
                '\n'
                'The file should use UTF-8 encoding and be written using '
                'ReStructured Text. It\n'
                'will be used to generate the project webpage on PyPI, and '
                'should be written for\n'
                'that purpose.\n'
                '\n'
                'Typical contents for this file would include an overview of '
                'the project, basic\n'
                'usage examples, etc. Generally, including the project '
                'changelog in here is not\n'
                'a good idea, although a simple "What\'s New" section for the '
                'most recent version\n'
                'may be appropriate.',
 'description_content_type': None,
 'docs_url': None,
 'download_url': 'UNKNOWN',
 'downloads': @{...@},
 'home_page': 'https://github.com/pypa/sampleproject',
 'keywords': 'sample setuptools development',
 'license': 'MIT',
 'maintainer': None,
 'maintainer_email': None,
 'name': 'sampleproject',
 'package_url': 'https://pypi.org/project/sampleproject/',
 'platform': 'UNKNOWN',
 'project_url': 'https://pypi.org/project/sampleproject/',
 'project_urls': @{...@},
 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
 'requires_dist': None,
 'requires_python': None,
 'summary': 'A sample Python project',
 'version': '1.2.0'@}
@end example

De plus, une valeur maximale de caractères sur une ligne peut être définie en initialisant le paramètre `width'. Si un long objet ne peut être scindé, la valeur donnée à `width' sera outrepassée :

@example
>>> pprint.pp(project_info, depth=1, width=60)
@{'author': 'The Python Packaging Authority',
 'author_email': 'pypa-dev@@googlegroups.com',
 'bugtrack_url': None,
 'classifiers': [...],
 'description': 'A sample Python project\n'
                '=======================\n'
                '\n'
                'This is the description file for the '
                'project.\n'
                '\n'
                'The file should use UTF-8 encoding and be '
                'written using ReStructured Text. It\n'
                'will be used to generate the project '
                'webpage on PyPI, and should be written '
                'for\n'
                'that purpose.\n'
                '\n'
                'Typical contents for this file would '
                'include an overview of the project, '
                'basic\n'
                'usage examples, etc. Generally, including '
                'the project changelog in here is not\n'
                'a good idea, although a simple "What\'s '
                'New" section for the most recent version\n'
                'may be appropriate.',
 'description_content_type': None,
 'docs_url': None,
 'download_url': 'UNKNOWN',
 'downloads': @{...@},
 'home_page': 'https://github.com/pypa/sampleproject',
 'keywords': 'sample setuptools development',
 'license': 'MIT',
 'maintainer': None,
 'maintainer_email': None,
 'name': 'sampleproject',
 'package_url': 'https://pypi.org/project/sampleproject/',
 'platform': 'UNKNOWN',
 'project_url': 'https://pypi.org/project/sampleproject/',
 'project_urls': @{...@},
 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
 'requires_dist': None,
 'requires_python': None,
 'summary': 'A sample Python project',
 'version': '1.2.0'@}
@end example

@node reprlib --- Alternate repr implementation,enum --- Support for enumerations,pprint — L’affichage élégant de données,Types de données
@anchor{library/reprlib doc}@anchor{2519}@anchor{library/reprlib module-reprlib}@anchor{ba}@anchor{library/reprlib reprlib-alternate-repr-implementation}@anchor{251a}
@subsection @code{reprlib} --- Alternate @code{repr()} implementation


@geindex module; reprlib

`Code source :' Lib/reprlib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/reprlib.py}


__________________________________________________________________


The @code{reprlib} module provides a means for producing object representations
with limits on the size of the resulting strings. This is used in the Python
debugger and may be useful in other contexts as well.

This module provides a class, an instance, and a function:

@geindex Repr (classe dans reprlib)
@anchor{library/reprlib reprlib Repr}@anchor{251b}
@deffn {Classe} reprlib.Repr (*, maxlevel=6, maxtuple=6, maxlist=6, maxarray=5, maxdict=4, maxset=6, maxfrozenset=6, maxdeque=6, maxstring=30, maxlong=40, maxother=30, fillvalue='...', indent=None)

Class which provides formatting services useful in implementing functions
similar to the built-in @ref{7e7,,repr()}; size limits for  different object types
are added to avoid the generation of representations which are excessively long.

The keyword arguments of the constructor can be used as a shortcut to set the
attributes of the @ref{251b,,Repr} instance. Which means that the following
initialization:

@example
aRepr = reprlib.Repr(maxlevel=3)
@end example

est équivalent à :

@example
aRepr = reprlib.Repr()
aRepr.maxlevel = 3
@end example

See section @ref{251c,,Repr Objects} for more information about @ref{251b,,Repr}
attributes.


Modifié dans la version 3.12: Allow attributes to be set via keyword arguments.

@end deffn

@geindex aRepr (dans le module reprlib)
@anchor{library/reprlib reprlib aRepr}@anchor{251d}
@deffn {Données} reprlib.aRepr

This is an instance of @ref{251b,,Repr} which is used to provide the
@ref{251e,,repr()} function described below.  Changing the attributes of this
object will affect the size limits used by @ref{251e,,repr()} and the Python
debugger.
@end deffn

@geindex repr() (dans le module reprlib)
@anchor{library/reprlib reprlib repr}@anchor{251e}
@deffn {Fonction} reprlib.repr (obj)

This is the @ref{251f,,repr()} method of @code{aRepr}.  It returns a string
similar to that returned by the built-in function of the same name, but with
limits on most sizes.
@end deffn

In addition to size-limiting tools, the module also provides a decorator for
detecting recursive calls to @ref{607,,__repr__()} and substituting a
placeholder string instead.

@geindex ...;placeholder

@geindex recursive_repr() (dans le module reprlib)
@anchor{library/reprlib reprlib recursive_repr}@anchor{11d0}
@deffn {Fonction} @@reprlib.recursive_repr (fillvalue='...')

Decorator for @ref{607,,__repr__()} methods to detect recursive calls within the
same thread.  If a recursive call is made, the `fillvalue' is returned,
otherwise, the usual @code{__repr__()} call is made.  For example:

@example
>>> from reprlib import recursive_repr
>>> class MyList(list):
...     @@recursive_repr()
...     def __repr__(self):
...         return '<' + '|'.join(map(repr, self)) + '>'
...
>>> m = MyList('abc')
>>> m.append(m)
>>> m.append('x')
>>> print(m)
<'a'|'b'|'c'|...|'x'>
@end example


Ajouté dans la version 3.2.

@end deffn

@menu
* Repr Objects:: 
* Subclassing Repr Objects:: 

@end menu

@node Repr Objects,Subclassing Repr Objects,,reprlib --- Alternate repr implementation
@anchor{library/reprlib id1}@anchor{251c}@anchor{library/reprlib repr-objects}@anchor{2520}
@subsubsection Repr Objects


@ref{251b,,Repr} instances provide several attributes which can be used to provide
size limits for the representations of different object types,  and methods
which format specific object types.

@geindex fillvalue (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr fillvalue}@anchor{2521}
@deffn {Attribut} Repr.fillvalue

This string is displayed for recursive references. It defaults to
@code{...}.


Ajouté dans la version 3.11.

@end deffn

@geindex maxlevel (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxlevel}@anchor{2522}
@deffn {Attribut} Repr.maxlevel

Depth limit on the creation of recursive representations.  The default is @code{6}.
@end deffn

@geindex maxdict (attribut reprlib.Repr)
@geindex maxlist (attribut reprlib.Repr)
@geindex maxtuple (attribut reprlib.Repr)
@geindex maxset (attribut reprlib.Repr)
@geindex maxfrozenset (attribut reprlib.Repr)
@geindex maxdeque (attribut reprlib.Repr)
@geindex maxarray (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxdict}@anchor{2523}
@deffn {Attribut} Repr.maxdict
@anchor{library/reprlib reprlib Repr maxlist}@anchor{2524}
@deffnx {Attribut} Repr.maxlist
@anchor{library/reprlib reprlib Repr maxtuple}@anchor{2525}
@deffnx {Attribut} Repr.maxtuple
@anchor{library/reprlib reprlib Repr maxset}@anchor{2526}
@deffnx {Attribut} Repr.maxset
@anchor{library/reprlib reprlib Repr maxfrozenset}@anchor{2527}
@deffnx {Attribut} Repr.maxfrozenset
@anchor{library/reprlib reprlib Repr maxdeque}@anchor{2528}
@deffnx {Attribut} Repr.maxdeque
@anchor{library/reprlib reprlib Repr maxarray}@anchor{2529}
@deffnx {Attribut} Repr.maxarray

Limits on the number of entries represented for the named object type.  The
default is @code{4} for @ref{2523,,maxdict}, @code{5} for @ref{2529,,maxarray}, and  @code{6} for
the others.
@end deffn

@geindex maxlong (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxlong}@anchor{252a}
@deffn {Attribut} Repr.maxlong

Maximum number of characters in the representation for an integer.  Digits
are dropped from the middle.  The default is @code{40}.
@end deffn

@geindex maxstring (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxstring}@anchor{252b}
@deffn {Attribut} Repr.maxstring

Limit on the number of characters in the representation of the string.  Note
that the "normal" representation of the string is used as the character source:
if escape sequences are needed in the representation, these may be mangled when
the representation is shortened.  The default is @code{30}.
@end deffn

@geindex maxother (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr maxother}@anchor{252c}
@deffn {Attribut} Repr.maxother

This limit is used to control the size of object types for which no specific
formatting method is available on the @ref{251b,,Repr} object. It is applied in a
similar manner as @ref{252b,,maxstring}.  The default is @code{20}.
@end deffn

@geindex indent (attribut reprlib.Repr)
@anchor{library/reprlib reprlib Repr indent}@anchor{252d}
@deffn {Attribut} Repr.indent

If this attribute is set to @code{None} (the default), the output is formatted
with no line breaks or indentation, like the standard @ref{7e7,,repr()}.
For example:

@example
>>> example = [
...     1, 'spam', @{'a': 2, 'b': 'spam eggs', 'c': @{3: 4.5, 6: []@}@}, 'ham']
>>> import reprlib
>>> aRepr = reprlib.Repr()
>>> print(aRepr.repr(example))
[1, 'spam', @{'a': 2, 'b': 'spam eggs', 'c': @{3: 4.5, 6: []@}@}, 'ham']
@end example

If @ref{252d,,indent} is set to a string, each recursion level
is placed on its own line, indented by that string:

@example
>>> aRepr.indent = '-->'
>>> print(aRepr.repr(example))
[
-->1,
-->'spam',
-->@{
-->-->'a': 2,
-->-->'b': 'spam eggs',
-->-->'c': @{
-->-->-->3: 4.5,
-->-->-->6: [],
-->-->@},
-->@},
-->'ham',
]
@end example

Setting @ref{252d,,indent} to a positive integer value behaves as if it
was set to a string with that number of spaces:

@example
>>> aRepr.indent = 4
>>> print(aRepr.repr(example))
[
    1,
    'spam',
    @{
        'a': 2,
        'b': 'spam eggs',
        'c': @{
            3: 4.5,
            6: [],
        @},
    @},
    'ham',
]
@end example


Ajouté dans la version 3.12.

@end deffn

@geindex repr() (méthode reprlib.Repr)
@anchor{library/reprlib reprlib Repr repr}@anchor{251f}
@deffn {Méthode} Repr.repr (obj)

The equivalent to the built-in @ref{7e7,,repr()} that uses the formatting imposed by
the instance.
@end deffn

@geindex repr1() (méthode reprlib.Repr)
@anchor{library/reprlib reprlib Repr repr1}@anchor{252e}
@deffn {Méthode} Repr.repr1 (obj, level)

Recursive implementation used by @ref{251f,,repr()}.  This uses the type of `obj' to
determine which formatting method to call, passing it `obj' and `level'.  The
type-specific methods should call @ref{252e,,repr1()} to perform recursive formatting,
with @code{level - 1} for the value of `level' in the recursive  call.
@end deffn


@deffn {Méthode} Repr.repr_TYPE (obj, level)

Formatting methods for specific types are implemented as methods with a name
based on the type name.  In the method name, `TYPE' is replaced by
@code{'_'.join(type(obj).__name__.split())}. Dispatch to these methods is
handled by @ref{252e,,repr1()}. Type-specific methods which need to recursively
format a value should call @code{self.repr1(subobj, level - 1)}.
@end deffn

@node Subclassing Repr Objects,,Repr Objects,reprlib --- Alternate repr implementation
@anchor{library/reprlib subclassing-repr-objects}@anchor{252f}@anchor{library/reprlib subclassing-reprs}@anchor{2530}
@subsubsection Subclassing Repr Objects


The use of dynamic dispatching by @ref{252e,,Repr.repr1()} allows subclasses of
@ref{251b,,Repr} to add support for additional built-in object types or to modify
the handling of types already supported. This example shows how special support
for file objects could be added:

@example
import reprlib
import sys

class MyRepr(reprlib.Repr):

    def repr_TextIOWrapper(self, obj, level):
        if obj.name in @{'<stdin>', '<stdout>', '<stderr>'@}:
            return obj.name
        return repr(obj)

aRepr = MyRepr()
print(aRepr.repr(sys.stdin))         # prints '<stdin>'
@end example

@example
<stdin>
@end example

@node enum --- Support for enumerations,graphlib --- Functionality to operate with graph-like structures,reprlib --- Alternate repr implementation,Types de données
@anchor{library/enum doc}@anchor{2531}@anchor{library/enum enum-support-for-enumerations}@anchor{2532}@anchor{library/enum module-enum}@anchor{55}
@subsection @code{enum} --- Support for enumerations


@geindex module; enum


Ajouté dans la version 3.4.


`Code source :' Lib/enum.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/enum.py}

@subsubheading Important



Cette page contient les informations de référence de l'API. Pour des informations sur le didacticiel et une discussion sur des sujets plus avancés, reportez-vous à


@itemize *

@item 
@ref{2533,,Tutoriel de base}

@item 
@ref{2534,,Tutoriel avancé}

@item 
@ref{2535,,Recettes pour les énumérations}
@end itemize


__________________________________________________________________


Une énumération :


@itemize *

@item 
est un ensemble de noms symboliques (appelés membres) liés à des valeurs uniques,

@item 
can be iterated over to return its canonical (i.e. non-alias) members in
definition order

@item 
utilise la syntaxe `d'appel' pour renvoyer les valeurs de ses membres,

@item 
utilise la syntaxe `d'indiçage' pour renvoyer les noms de ses membres.
@end itemize

Les énumérations sont créées soit en utilisant la syntaxe @ref{12b5,,class}, soit en utilisant la syntaxe d'appel de fonction :

@example
>>> from enum import Enum

>>> # class syntax
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3

>>> # functional syntax
>>> Color = Enum('Color', [('RED', 1), ('GREEN', 2), ('BLUE', 3)])
@end example

Même si on peut utiliser la syntaxe @ref{12b5,,class} pour créer des énumérations, les `Enums' ne sont pas des vraies classes Python. Lisez @ref{2536,,En quoi les énumérations sont-elles différentes ?} pour plus de détails.

@cartouche
@quotation Note 
Nomenclature


@itemize -

@item 
The class @code{Color} is an `enumeration' (or `enum')

@item 
The attributes @code{Color.RED}, @code{Color.GREEN}, etc., are
`enumeration members' (or `members') and are functionally constants.

@item 
The enum members have `names' and `values' (the name of
@code{Color.RED} is @code{RED}, the value of @code{Color.BLUE} is
@code{3}, etc.)
@end itemize
@end quotation
@end cartouche


__________________________________________________________________


@menu
* Contenu du module: Contenu du module<2>. 
* Types de données: Types de données<2>. 
* Utilitaires et décorateurs:: 
* Notes:: 

@end menu

@node Contenu du module<2>,Types de données<2>,,enum --- Support for enumerations
@anchor{library/enum module-contents}@anchor{2537}
@subsubsection Contenu du module


@quotation

@ref{1e2,,EnumType}

@quotation

Le @code{type} d'`Enum' et de ses sous-classes.
@end quotation

@ref{61b,,Enum}

@quotation

Classe mère pour créer une énumération de constantes.
@end quotation

@ref{ccd,,IntEnum}

@quotation

Classe mère pour créer une énumération de constantes qui sont également des sous-classes de @ref{254,,int} (@ref{2538,,notes}).
@end quotation

@ref{605,,StrEnum}

@quotation

Classe mère pour créer une énumération de constantes qui sont également des sous-classes de @ref{435,,str} (@ref{2538,,notes}).
@end quotation

@ref{60e,,Flag}

@quotation

Classe mère pour créer une énumération de constantes pouvant être combinées avec des opérateurs de comparaison bit-à-bit, sans perdre leur qualité de @ref{60e,,Flag}.
@end quotation

@ref{2280,,IntFlag}

@quotation

Classe mère pour créer une énumération de constantes pouvant être combinées avec des opérateurs de comparaison bit-à-bit, sans perdre leur qualité de @ref{2280,,IntFlag}. Les membres de @ref{2280,,IntFlag} sont aussi des sous-classes de @ref{254,,int} (@ref{2538,,notes}).
@end quotation

@ref{606,,ReprEnum}

@quotation

Used by @ref{ccd,,IntEnum}, @ref{605,,StrEnum}, and @ref{2280,,IntFlag}
to keep the @ref{435,,str()} of the mixed-in type.
@end quotation

@ref{611,,EnumCheck}

@quotation

Énumération avec les valeurs @code{CONTINUOUS}, @code{NAMED_FLAGS} et @code{UNIQUE}, à utiliser avec @ref{610,,verify()} pour s'assurer que diverses contraintes sont satisfaites par une énumération donnée.
@end quotation

@ref{60f,,FlagBoundary}

@quotation

Énumération avec les valeurs @code{STRICT}, @code{CONFORM}, @code{EJECT} et @code{KEEP} qui permet un contrôle plus précis sur la façon dont les valeurs invalides sont traitées dans une énumération.
@end quotation

@ref{1e1,,EnumDict}

@quotation

A subclass of @ref{253,,dict} for use when subclassing @ref{1e2,,EnumType}.
@end quotation

@ref{c8a,,auto}

@quotation

Les instances sont remplacées par une valeur appropriée pour les membres de l'énumération. @ref{605,,StrEnum} utilise par défaut la version minuscule du nom du membre, tandis que les autres énumérations utilisent 1 par défaut et puis augmentent.
@end quotation

@ref{614,,property()}

@quotation

Allows @ref{61b,,Enum} members to have attributes without conflicting with
member names.  The @code{value} and @code{name} attributes are implemented this
way.
@end quotation

@ref{2539,,unique()}

@quotation

Décorateur de classe qui garantit qu'une valeur ne puisse être associée qu'à un seul nom.
@end quotation

@ref{610,,verify()}

@quotation

Décorateur de classe qui vérifie des contraintes personnalisées pour une énumération.
@end quotation

@ref{612,,member()}

@quotation

Fait de @code{obj} un membre. Peut être utilisé comme décorateur.
@end quotation

@ref{613,,nonmember()}

@quotation

Fait que @code{obj} n'est pas un membre. Peut être utilisé comme décorateur.
@end quotation

@ref{616,,global_enum()}

@quotation

Modify the @ref{435,,str()} and @ref{7e7,,repr()} of an enum
to show its members as belonging to the module instead of its class,
and export the enum members to the global namespace.
@end quotation

@ref{253a,,show_flag_values()}

@quotation

Return a list of all power-of-two integers contained in a flag.
@end quotation
@end quotation


Ajouté dans la version 3.6: @code{Flag}, @code{IntFlag}, @code{auto}



Ajouté dans la version 3.11: @code{StrEnum}, @code{EnumCheck}, @code{ReprEnum}, @code{FlagBoundary}, @code{property}, @code{member}, @code{nonmember}, @code{global_enum}, @code{show_flag_values}



Ajouté dans la version 3.13: @code{EnumDict}



__________________________________________________________________


@node Types de données<2>,Utilitaires et décorateurs,Contenu du module<2>,enum --- Support for enumerations
@anchor{library/enum data-types}@anchor{253b}
@subsubsection Types de données


@geindex EnumType (classe dans enum)
@anchor{library/enum enum EnumType}@anchor{1e2}
@deffn {Classe} enum.EnumType

`EnumType' est la @ref{1f09,,métaclasse} pour les énumérations. Il est possible de sous-classer `EnumType' ­— voir @ref{253c,,Sous-classer EnumType} pour plus de détails.

@code{EnumType} is responsible for setting the correct @code{__repr__()},
@code{__str__()}, @code{__format__()}, and @code{__reduce__()} methods on the
final `enum', as well as creating the enum members, properly handling
duplicates, providing iteration over the enum class, etc.

@geindex __call__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __call__}@anchor{253d}
@deffn {Méthode} __call__ (cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Cette méthode peut être appelée de deux manières différentes :


@itemize *

@item 
pour chercher un membre existant :

@quotation

@*cls: 
Classe de l'énumération concernée.


@*value: 
Valeur à chercher.

@end quotation

@item 
to use the @code{cls} enum to create a new enum (only if the existing enum
does not have any members):

@quotation

@*cls: 
Classe de l'énumération concernée.


@*value: 
Nom de la nouvelle énumération à créer.


@*names: 
Couples nom-valeur des membres de la nouvelle énumération.


@*module: 
Nom du module dans lequel la classe `Enum' se trouve.


@*qualname: 
Position dans le module où la classe `Enum' se trouve.


@*type: 
Type à mélanger pour la nouvelle énumération.


@*start: 
The first integer value for the Enum (used by @ref{c8a,,auto}).


@*boundary: 
How to handle out-of-range values from bit operations (@ref{60e,,Flag} only).

@end quotation
@end itemize
@end deffn

@geindex __contains__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __contains__}@anchor{253e}
@deffn {Méthode} __contains__ (cls, member)

Renvoie @code{True} si le membre appartient à @code{cls} :

@example
>>> some_var = Color.RED
>>> some_var in Color
True
>>> Color.RED.value in Color
True
@end example
@end deffn


Modifié dans la version 3.12: Before Python 3.12, a @code{TypeError} is raised if a
non-Enum-member is used in a containment check.


@geindex __dir__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __dir__}@anchor{253f}
@deffn {Méthode} __dir__ (cls)

Renvoie @code{['__class__', '__doc__', '__members__', '__module__']} et les noms des membres de `cls' :

@example
>>> dir(Color)
['BLUE', 'GREEN', 'RED', '__class__', '__contains__', '__doc__', '__getitem__', '__init_subclass__', '__iter__', '__len__', '__members__', '__module__', '__name__', '__qualname__']
@end example
@end deffn

@geindex __getitem__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __getitem__}@anchor{2540}
@deffn {Méthode} __getitem__ (cls, name)

Returns the Enum member in `cls' matching `name', or raises a @ref{33a,,KeyError}:

@example
>>> Color['BLUE']
<Color.BLUE: 3>
@end example
@end deffn

@geindex __iter__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __iter__}@anchor{2541}
@deffn {Méthode} __iter__ (cls)

Renvoie chaque membre de `cls' dans l'ordre de définition :

@example
>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
@end example
@end deffn

@geindex __len__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __len__}@anchor{2542}
@deffn {Méthode} __len__ (cls)

Renvoie le nombre de membres de `cls' :

@example
>>> len(Color)
3
@end example
@end deffn

@geindex __members__ (attribut enum.EnumType)
@anchor{library/enum enum EnumType __members__}@anchor{2543}
@deffn {Attribut} __members__

Returns a mapping of every enum name to its member, including aliases
@end deffn

@geindex __reversed__() (méthode enum.EnumType)
@anchor{library/enum enum EnumType __reversed__}@anchor{2544}
@deffn {Méthode} __reversed__ (cls)

Renvoie chaque membre de `cls' dans l'ordre inverse de définition :

@example
>>> list(reversed(Color))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]
@end example
@end deffn

@geindex _add_alias_() (méthode enum.EnumType)
@anchor{library/enum enum EnumType _add_alias_}@anchor{2545}
@deffn {Méthode} _add_alias_ ()

Adds a new name as an alias to an existing member.  Raises a
@ref{428,,NameError} if the name is already assigned to a different member.
@end deffn

@geindex _add_value_alias_() (méthode enum.EnumType)
@anchor{library/enum enum EnumType _add_value_alias_}@anchor{2546}
@deffn {Méthode} _add_value_alias_ ()

Adds a new value as an alias to an existing member.  Raises a
@ref{1ff,,ValueError} if the value is already linked with a different member.
@end deffn


Ajouté dans la version 3.11: Before 3.11 @code{EnumType} was called @code{EnumMeta}, which is still available as an alias.

@end deffn

@geindex Enum (classe dans enum)
@anchor{library/enum enum Enum}@anchor{61b}
@deffn {Classe} enum.Enum

`Enum' est la classe mère de toutes les énumérations.

@geindex name (attribut enum.Enum)
@anchor{library/enum enum Enum name}@anchor{2547}
@deffn {Attribut} name

Le nom utilisé pour définir le membre de l'@code{Enum} :

@example
>>> Color.BLUE.name
'BLUE'
@end example
@end deffn

@geindex value (attribut enum.Enum)
@anchor{library/enum enum Enum value}@anchor{2548}
@deffn {Attribut} value

La valeur attribuée au membre de l'@code{Enum} :

@example
>>> Color.RED.value
1
@end example

Value of the member, can be set in @ref{2549,,__new__()}.

@cartouche
@quotation Note 
Valeurs des membres d'une `Enum'

Member values can be anything: @ref{254,,int}, @ref{435,,str}, etc.  If
the exact value is unimportant you may use @ref{c8a,,auto} instances and an
appropriate value will be chosen for you.  See @ref{c8a,,auto} for the
details.

While mutable/unhashable values, such as @ref{253,,dict}, @ref{5fc,,list} or
a mutable @ref{1c6,,dataclass}, can be used, they will have a
quadratic performance impact during creation relative to the
total number of mutable/unhashable values in the enum.
@end quotation
@end cartouche
@end deffn

@geindex _name_ (attribut enum.Enum)
@anchor{library/enum enum Enum _name_}@anchor{254a}
@deffn {Attribut} _name_

Name of the member.
@end deffn

@geindex _value_ (attribut enum.Enum)
@anchor{library/enum enum Enum _value_}@anchor{254b}
@deffn {Attribut} _value_

Value of the member, can be set in @ref{2549,,__new__()}.
@end deffn

@geindex _order_ (attribut enum.Enum)
@anchor{library/enum enum Enum _order_}@anchor{254c}
@deffn {Attribut} _order_

No longer used, kept for backward compatibility.
(class attribute, removed during class creation).
@end deffn

@geindex _ignore_ (attribut enum.Enum)
@anchor{library/enum enum Enum _ignore_}@anchor{254d}
@deffn {Attribut} _ignore_

@code{_ignore_} n'est utilisé que lors de la création et est supprimé de l'énumération une fois la création terminée.

@code{_ignore_} est une liste de noms qui ne deviendront pas membres et qui seront également supprimés de l'énumération terminée. Voir @ref{254e,,Intervalle de temps} pour un exemple.
@end deffn

@geindex __dir__() (méthode enum.Enum)
@anchor{library/enum enum Enum __dir__}@anchor{17ef}
@deffn {Méthode} __dir__ (self)

Renvoie @code{['__class__', '__doc__', '__module__', 'name', 'value']} et toutes les méthodes publiques définies pour `self.__class__' :

@example
>>> from datetime import date
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     @@classmethod
...     def today(cls):
...         print('today is %s' % cls(date.today().isoweekday()).name)
...
>>> dir(Weekday.SATURDAY)
['__class__', '__doc__', '__eq__', '__hash__', '__module__', 'name', 'today', 'value']
@end example
@end deffn

@geindex _generate_next_value_() (méthode enum.Enum)
@anchor{library/enum enum Enum _generate_next_value_}@anchor{254f}
@deffn {Méthode} _generate_next_value_ (name, start, count, last_values)

@quotation

@*name: 
Nom du membre en cours de définition (par ex. @code{RED}).


@*start: 
Valeur de départ pour l'énumération ; 1 par défaut.


@*count: 
Nombre de membres actuellement définis, le membre actuel n'étant pas inclus.


@*last_values: 
Liste des valeurs précédentes.

@end quotation

Méthode statique utilisée pour déterminer la prochaine valeur à renvoyer par @ref{c8a,,auto} :

@example
>>> from enum import auto
>>> class PowersOfThree(Enum):
...     @@staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return 3 ** (count + 1)
...     FIRST = auto()
...     SECOND = auto()
...
>>> PowersOfThree.SECOND.value
9
@end example
@end deffn

@geindex __init__() (méthode enum.Enum)
@anchor{library/enum enum Enum __init__}@anchor{2550}
@deffn {Méthode} __init__ (self, *args, **kwds)

By default, does nothing.  If multiple values are given in the member
assignment, those values become separate arguments to @code{__init__}; e.g.

@example
>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1, 'Mon'
@end example

@code{Weekday.__init__()} would be called as @code{Weekday.__init__(self, 1, 'Mon')}
@end deffn

@geindex __init_subclass__() (méthode enum.Enum)
@anchor{library/enum enum Enum __init_subclass__}@anchor{2551}
@deffn {Méthode} __init_subclass__ (cls, **kwds)

Méthode de classe utilisée pour personnaliser davantage les sous-classes à venir. Ne fait rien par défaut.
@end deffn

@geindex _missing_() (méthode enum.Enum)
@anchor{library/enum enum Enum _missing_}@anchor{2552}
@deffn {Méthode} _missing_ (cls, value)

Méthode de classe pour chercher des valeurs non trouvées dans `cls'. Ne fait rien par défaut mais peut être surchargée pour implémenter un comportement personnalisé de recherche :

@example
>>> from enum import StrEnum
>>> class Build(StrEnum):
...     DEBUG = auto()
...     OPTIMIZED = auto()
...     @@classmethod
...     def _missing_(cls, value):
...         value = value.lower()
...         for member in cls:
...             if member.value == value:
...                 return member
...         return None
...
>>> Build.DEBUG.value
'debug'
>>> Build('deBUG')
<Build.DEBUG: 'debug'>
@end example
@end deffn

@geindex __new__() (méthode enum.Enum)
@anchor{library/enum enum Enum __new__}@anchor{2549}
@deffn {Méthode} __new__ (cls, *args, **kwds)

By default, doesn't exist.  If specified, either in the enum class
definition or in a mixin class (such as @code{int}), all values given
in the member assignment will be passed; e.g.

@example
>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     TWENTYSIX = '1a', 16
@end example

results in the call @code{int('1a', 16)} and a value of @code{26} for the member.

@cartouche
@quotation Note 
When writing a custom @code{__new__}, do not use @code{super().__new__} --
call the appropriate @code{__new__} instead.
@end quotation
@end cartouche
@end deffn

@geindex __repr__() (méthode enum.Enum)
@anchor{library/enum enum Enum __repr__}@anchor{1713}
@deffn {Méthode} __repr__ (self)

Renvoie la chaîne utilisée pour les appels à `repr()'. Par défaut, renvoie le nom de l'énumération, le nom du membre et sa valeur, mais peut être surchargée :

@example
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __repr__(self):
...         cls_name = self.__class__.__name__
...         return f'@{cls_name@}.@{self.name@}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"@{OtherStyle.ALTERNATE@}"
(OtherStyle.ALTERNATE, 'OtherStyle.ALTERNATE', 'OtherStyle.ALTERNATE')
@end example
@end deffn

@geindex __str__() (méthode enum.Enum)
@anchor{library/enum enum Enum __str__}@anchor{60d}
@deffn {Méthode} __str__ (self)

Renvoie la chaîne utilisée pour les appels à `str()'. Par défaut, renvoie le nom `Enum' et le nom du membre, mais peut être remplacé :

@example
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __str__(self):
...         return f'@{self.name@}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"@{OtherStyle.ALTERNATE@}"
(<OtherStyle.ALTERNATE: 1>, 'ALTERNATE', 'ALTERNATE')
@end example
@end deffn

@geindex __format__() (méthode enum.Enum)
@anchor{library/enum enum Enum __format__}@anchor{60b}
@deffn {Méthode} __format__ (self)

Returns the string used for `format()' and `f-string' calls.  By default,
returns @ref{60d,,__str__()} return value, but can be overridden:

@example
>>> class OtherStyle(Enum):
...     ALTERNATE = auto()
...     OTHER = auto()
...     SOMETHING_ELSE = auto()
...     def __format__(self, spec):
...         return f'@{self.name@}'
...
>>> OtherStyle.ALTERNATE, str(OtherStyle.ALTERNATE), f"@{OtherStyle.ALTERNATE@}"
(<OtherStyle.ALTERNATE: 1>, 'OtherStyle.ALTERNATE', 'ALTERNATE')
@end example
@end deffn

@cartouche
@quotation Note 
L'utilisation de @ref{c8a,,auto} avec @ref{61b,,Enum} donne des nombres entiers de valeur croissante, en commençant par @code{1}.
@end quotation
@end cartouche


Modifié dans la version 3.12: Added @ref{1712,,Dataclass support}

@end deffn

@geindex IntEnum (classe dans enum)
@anchor{library/enum enum IntEnum}@anchor{ccd}
@deffn {Classe} enum.IntEnum

`IntEnum' is the same as @ref{61b,,Enum}, but its members are also integers and can be
used anywhere that an integer can be used.  If any integer operation is performed
with an `IntEnum' member, the resulting value loses its enumeration status.

@example
>>> from enum import IntEnum
>>> class Number(IntEnum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...
>>> Number.THREE
<Number.THREE: 3>
>>> Number.ONE + Number.TWO
3
>>> Number.THREE + 5
8
>>> Number.THREE == 3
True
@end example

@cartouche
@quotation Note 
L'utilisation de @ref{c8a,,auto} avec @ref{ccd,,IntEnum} donne des entiers de valeur croissante, en commençant par @code{1}.
@end quotation
@end cartouche


Modifié dans la version 3.11: @ref{608,,__str__()} is now @code{int.__str__()} to
better support the `replacement of existing constants' use-case.
@ref{609,,__format__()} was already @code{int.__format__()} for that same reason.

@end deffn

@geindex StrEnum (classe dans enum)
@anchor{library/enum enum StrEnum}@anchor{605}
@deffn {Classe} enum.StrEnum

@code{StrEnum} is the same as @ref{61b,,Enum}, but its members are also strings and can be used
in most of the same places that a string can be used.  The result of any string
operation performed on or with a `StrEnum' member is not part of the enumeration.

@cartouche
@quotation Note 
There are places in the stdlib that check for an exact @ref{435,,str}
instead of a @ref{435,,str} subclass (i.e. @code{type(unknown) == str}
instead of @code{isinstance(unknown, str)}), and in those locations you
will need to use @code{str(StrEnum.member)}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
L'utilisation de @ref{c8a,,auto} avec @ref{605,,StrEnum} donne le nom du membre en minuscule comme valeur.
@end quotation
@end cartouche

@cartouche
@quotation Note 
@ref{608,,__str__()} is @code{str.__str__()} to better support the
`replacement of existing constants' use-case.  @ref{609,,__format__()} is likewise
@code{str.__format__()} for that same reason.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex Flag (classe dans enum)
@anchor{library/enum enum Flag}@anchor{60e}
@deffn {Classe} enum.Flag

@code{Flag} is the same as @ref{61b,,Enum}, but its members support the bitwise
operators @code{&} (`AND'), @code{|} (`OR'), @code{^} (`XOR'), and @code{~} (`INVERT');
the results of those operations are (aliases of) members of the enumeration.

@geindex __contains__() (méthode enum.Flag)
@anchor{library/enum enum Flag __contains__}@anchor{2553}
@deffn {Méthode} __contains__ (self, value)

Renvoie `True' si la valeur est dans `self' :

@example
>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> purple = Color.RED | Color.BLUE
>>> white = Color.RED | Color.GREEN | Color.BLUE
>>> Color.GREEN in purple
False
>>> Color.GREEN in white
True
>>> purple in white
True
>>> white in purple
False
@end example
@end deffn


@deffn {Méthode} __iter__(self):

Returns all contained non-alias members:

@example
>>> list(Color.RED)
[<Color.RED: 1>]
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 4>]
@end example


Ajouté dans la version 3.11.

@end deffn


@deffn {Méthode} __len__(self):

Renvoie le nombre de membres de `Flag' :

@example
>>> len(Color.GREEN)
1
>>> len(white)
3
@end example


Ajouté dans la version 3.11.

@end deffn


@deffn {Méthode} __bool__(self):

Renvoie `True' s'il y a un membre dans les bits de `Flag', `False' sinon :

@example
>>> bool(Color.GREEN)
True
>>> bool(white)
True
>>> black = Color(0)
>>> bool(black)
False
@end example
@end deffn

@geindex __or__() (méthode enum.Flag)
@anchor{library/enum enum Flag __or__}@anchor{2554}
@deffn {Méthode} __or__ (self, other)

Renvoie le `OU' logique entre le membre et `other' :

@example
>>> Color.RED | Color.GREEN
<Color.RED|GREEN: 3>
@end example
@end deffn

@geindex __and__() (méthode enum.Flag)
@anchor{library/enum enum Flag __and__}@anchor{2555}
@deffn {Méthode} __and__ (self, other)

Renvoie le `ET' logique entre le membre et `other' :

@example
>>> purple & white
<Color.RED|BLUE: 5>
>>> purple & Color.GREEN
<Color: 0>
@end example
@end deffn

@geindex __xor__() (méthode enum.Flag)
@anchor{library/enum enum Flag __xor__}@anchor{2556}
@deffn {Méthode} __xor__ (self, other)

Renvoie le `OU Exclusif' logique entre le membre et `other' :

@example
>>> purple ^ white
<Color.GREEN: 2>
>>> purple ^ Color.GREEN
<Color.RED|GREEN|BLUE: 7>
@end example
@end deffn


@deffn {Méthode} __invert__(self):

Returns all the flags in `type(self)' that are not in `self':

@example
>>> ~white
<Color: 0>
>>> ~purple
<Color.GREEN: 2>
>>> ~Color.RED
<Color.GREEN|BLUE: 6>
@end example
@end deffn

@geindex _numeric_repr_() (méthode enum.Flag)
@anchor{library/enum enum Flag _numeric_repr_}@anchor{2557}
@deffn {Méthode} _numeric_repr_ ()

Fonction utilisée pour formater toutes les valeurs numériques sans nom restantes. La valeur par défaut est la représentation de la valeur ; les choix courants sont @ref{12ad,,hex()} et @ref{12ac,,oct()}.
@end deffn

@cartouche
@quotation Note 
L'utilisation de @ref{c8a,,auto} avec @ref{60e,,Flag} donne des entiers qui sont des puissances de deux, en commençant par @code{1}.
@end quotation
@end cartouche


Modifié dans la version 3.11: La `repr()' des membres de valeur zéro a changé. C'est maintenant :

@example
>>> Color(0) 
<Color: 0>
@end example

@end deffn

@geindex IntFlag (classe dans enum)
@anchor{library/enum enum IntFlag}@anchor{2280}
@deffn {Classe} enum.IntFlag

@code{IntFlag} is the same as @ref{60e,,Flag}, but its members are also integers and can be
used anywhere that an integer can be used.

@example
>>> from enum import IntFlag, auto
>>> class Color(IntFlag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> Color.RED & 2
<Color: 0>
>>> Color.RED | 2
<Color.RED|GREEN: 3>
@end example

Si une opération sur un entier est effectuée avec un membre d'un `IntFlag', le résultat n'est pas un `IntFlag' :

@example
>>> Color.RED + 2
3
@end example

If a @ref{60e,,Flag} operation is performed with an `IntFlag' member and:


@itemize *

@item 
le résultat est un `IntFlag' valide : un `IntFlag' est renvoyé ;

@item 
the result is not a valid `IntFlag': the result depends on the @ref{60f,,FlagBoundary} setting
@end itemize

The @ref{7e7,,repr()} of unnamed zero-valued flags has changed.  It is now:

@example
>>> Color(0)
<Color: 0>
@end example

@cartouche
@quotation Note 
L'utilisation de @ref{c8a,,auto} avec @ref{2280,,IntFlag} donne des entiers qui sont des puissances de deux, en commençant par @code{1}.
@end quotation
@end cartouche


Modifié dans la version 3.11: @ref{608,,__str__()} is now @code{int.__str__()} to better support the
`replacement of existing constants' use-case.  @ref{609,,__format__()} was
already @code{int.__format__()} for that same reason.

Inversion of an @code{IntFlag} now returns a positive value that is the
union of all flags not in the given flag, rather than a negative value.
This matches the existing @ref{60e,,Flag} behavior.

@end deffn

@geindex ReprEnum (classe dans enum)
@anchor{library/enum enum ReprEnum}@anchor{606}
@deffn {Classe} enum.ReprEnum

@code{ReprEnum} uses the @ref{1713,,repr()} of @ref{61b,,Enum},
but the @ref{435,,str()} of the mixed-in data type:


@itemize *

@item 
@code{int.__str__()} for @ref{ccd,,IntEnum} and @ref{2280,,IntFlag}

@item 
@code{str.__str__()} for @ref{605,,StrEnum}
@end itemize

Inherit from @code{ReprEnum} to keep the @ref{435,,str()} / @ref{60a,,format()}
of the mixed-in data type instead of using the
@ref{61b,,Enum}-default @ref{60d,,str()}.


Ajouté dans la version 3.11.

@end deffn

@geindex EnumCheck (classe dans enum)
@anchor{library/enum enum EnumCheck}@anchor{611}
@deffn {Classe} enum.EnumCheck

`EnumCheck' contient les options utilisées par le décorateur @ref{610,,verify()} pour assurer diverses contraintes ; si une contrainte n'est pas validée, une @ref{1ff,,ValueError} est levée.

@geindex UNIQUE (attribut enum.EnumCheck)
@anchor{library/enum enum EnumCheck UNIQUE}@anchor{2558}
@deffn {Attribut} UNIQUE

Assure que chaque valeur n'a qu'un seul nom :

@example
>>> from enum import Enum, verify, UNIQUE
>>> @@verify(UNIQUE)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...     CRIMSON = 1
Traceback (most recent call last):
...
ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED
@end example
@end deffn

@geindex CONTINUOUS (attribut enum.EnumCheck)
@anchor{library/enum enum EnumCheck CONTINUOUS}@anchor{2559}
@deffn {Attribut} CONTINUOUS

Assure qu'il n'y a pas de valeurs manquantes entre le membre ayant la valeur la plus faible et le membre ayant la valeur la plus élevée :

@example
>>> from enum import Enum, verify, CONTINUOUS
>>> @@verify(CONTINUOUS)
... class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 5
Traceback (most recent call last):
...
ValueError: invalid enum 'Color': missing values 3, 4
@end example
@end deffn

@geindex NAMED_FLAGS (attribut enum.EnumCheck)
@anchor{library/enum enum EnumCheck NAMED_FLAGS}@anchor{255a}
@deffn {Attribut} NAMED_FLAGS

Ensure that any flag groups/masks contain only named flags -- useful when
values are specified instead of being generated by @ref{c8a,,auto()}:

@example
>>> from enum import Flag, verify, NAMED_FLAGS
>>> @@verify(NAMED_FLAGS)
... class Color(Flag):
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     WHITE = 15
...     NEON = 31
Traceback (most recent call last):
...
ValueError: invalid Flag 'Color': aliases WHITE and NEON are missing combined values of 0x18 [use enum.show_flag_values(value) for details]
@end example
@end deffn

@cartouche
@quotation Note 
CONTINUOUS et NAMED_FLAGS sont conçus pour fonctionner avec des membres à valeur entière.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex FlagBoundary (classe dans enum)
@anchor{library/enum enum FlagBoundary}@anchor{60f}
@deffn {Classe} enum.FlagBoundary

@code{FlagBoundary} controls how out-of-range values are handled in @ref{60e,,Flag} and its
subclasses.

@geindex STRICT (attribut enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary STRICT}@anchor{255b}
@deffn {Attribut} STRICT

Out-of-range values cause a @ref{1ff,,ValueError} to be raised. This is the
default for @ref{60e,,Flag}:

@example
>>> from enum import Flag, STRICT, auto
>>> class StrictFlag(Flag, boundary=STRICT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> StrictFlag(2**2 + 2**4)
Traceback (most recent call last):
...
ValueError: <flag 'StrictFlag'> invalid value 20
    given 0b0 10100
  allowed 0b0 00111
@end example
@end deffn

@geindex CONFORM (attribut enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary CONFORM}@anchor{255c}
@deffn {Attribut} CONFORM

Out-of-range values have invalid values removed, leaving a valid @ref{60e,,Flag}
value:

@example
>>> from enum import Flag, CONFORM, auto
>>> class ConformFlag(Flag, boundary=CONFORM):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> ConformFlag(2**2 + 2**4)
<ConformFlag.BLUE: 4>
@end example
@end deffn

@geindex EJECT (attribut enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary EJECT}@anchor{255d}
@deffn {Attribut} EJECT

Out-of-range values lose their @ref{60e,,Flag} membership and revert to @ref{254,,int}.

@example
>>> from enum import Flag, EJECT, auto
>>> class EjectFlag(Flag, boundary=EJECT):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> EjectFlag(2**2 + 2**4)
20
@end example
@end deffn

@geindex KEEP (attribut enum.FlagBoundary)
@anchor{library/enum enum FlagBoundary KEEP}@anchor{255e}
@deffn {Attribut} KEEP

Out-of-range values are kept, and the @ref{60e,,Flag} membership is kept.
This is the default for @ref{2280,,IntFlag}:

@example
>>> from enum import Flag, KEEP, auto
>>> class KeepFlag(Flag, boundary=KEEP):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...
>>> KeepFlag(2**2 + 2**4)
<KeepFlag.BLUE|16: 20>
@end example
@end deffn


Ajouté dans la version 3.11.

@end deffn

@geindex EnumDict (classe dans enum)
@anchor{library/enum enum EnumDict}@anchor{1e1}
@deffn {Classe} enum.EnumDict

`EnumDict' is a subclass of @ref{253,,dict} that is used as the namespace
for defining enum classes (see @ref{c4c,,Préparation de l'espace de nommage de la classe}).
It is exposed to allow subclasses of @ref{1e2,,EnumType} with advanced
behavior like having multiple values per member.
It should be called with the name of the enum class being created, otherwise
private names and internal classes will not be handled correctly.

Note that only the @ref{1090,,MutableMapping} interface
(@ref{12a9,,__setitem__()} and @ref{1419,,update()}) is overridden.
It may be possible to bypass the checks using other @code{dict}
operations like @ref{1f36,,|=}.

@geindex member_names (attribut enum.EnumDict)
@anchor{library/enum enum EnumDict member_names}@anchor{255f}
@deffn {Attribut} member_names

A list of member names.
@end deffn


Ajouté dans la version 3.13.

@end deffn


__________________________________________________________________


@menu
* Noms de la forme __dunder__ disponibles:: 
* Noms de la forme _sunder_ disponibles:: 

@end menu

@node Noms de la forme __dunder__ disponibles,Noms de la forme _sunder_ disponibles,,Types de données<2>
@anchor{library/enum supported-dunder-names}@anchor{2560}
@subsubsection Noms de la forme @code{__dunder__} disponibles


@ref{2543,,__members__} is a read-only ordered mapping of @code{member_name}:@code{member}
items.  It is only available on the class.

@ref{2549,,__new__()}, if specified, must create and return the enum members;
it is also a very good idea to set the member's @code{_value_} appropriately.
Once all the members are created it is no longer used.

@node Noms de la forme _sunder_ disponibles,,Noms de la forme __dunder__ disponibles,Types de données<2>
@anchor{library/enum supported-sunder-names}@anchor{2561}
@subsubsection Noms de la forme @code{_sunder_} disponibles



@itemize -

@item 
@ref{2545,,_add_alias_()} -- adds a new name as an alias to an existing
member.

@item 
@ref{2546,,_add_value_alias_()} -- adds a new value as an alias to an
existing member.

@item 
@ref{254a,,_name_} -- name of the member

@item 
@ref{254b,,_value_} -- value of the member; can be set in @code{__new__}

@item 
@ref{2552,,_missing_()} -- a lookup function used when a value is not found;
may be overridden

@item 
@ref{254d,,_ignore_} -- a list of names, either as a @ref{5fc,,list} or a
@ref{435,,str}, that will not be transformed into members, and will be removed
from the final class

@item 
@ref{254c,,_order_} -- no longer used, kept for backward
compatibility (class attribute, removed during class creation)

@item 
@ref{254f,,_generate_next_value_()} -- used to get an appropriate value for
an enum member; may be overridden

@cartouche
@quotation Note 
For standard @ref{61b,,Enum} classes the next value chosen is the highest
value seen incremented by one.

For @ref{60e,,Flag} classes the next value chosen will be the next highest
power-of-two.
@end quotation
@end cartouche

@item 
While @code{_sunder_} names are generally reserved for the further development
of the @ref{61b,,Enum} class and can not be used, some are explicitly allowed:


@itemize -

@item 
@code{_repr_*} (e.g. @code{_repr_html_}), as used in IPython's rich display@footnote{https://ipython.readthedocs.io/en/stable/config/integrating.html#rich-display}
@end itemize
@end itemize


Ajouté dans la version 3.6: @code{_missing_}, @code{_order_}, @code{_generate_next_value_}



Ajouté dans la version 3.7: @code{_ignore_}



Ajouté dans la version 3.13: @code{_add_alias_}, @code{_add_value_alias_}, @code{_repr_*}



__________________________________________________________________


@node Utilitaires et décorateurs,Notes,Types de données<2>,enum --- Support for enumerations
@anchor{library/enum ipython-s-rich-display}@anchor{2562}@anchor{library/enum utilities-and-decorators}@anchor{2563}
@subsubsection Utilitaires et décorateurs


@geindex auto (classe dans enum)
@anchor{library/enum enum auto}@anchor{c8a}
@deffn {Classe} enum.auto

`auto' can be used in place of a value.  If used, the `Enum' machinery will
call an @ref{61b,,Enum}'s @ref{254f,,_generate_next_value_()} to get an appropriate value.
For @ref{61b,,Enum} and @ref{ccd,,IntEnum} that appropriate value will be the last value plus
one; for @ref{60e,,Flag} and @ref{2280,,IntFlag} it will be the first power-of-two greater
than the highest value; for @ref{605,,StrEnum} it will be the lower-cased version of
the member's name.  Care must be taken if mixing `auto()' with manually
specified values.

`auto' instances are only resolved when at the top level of an assignment:


@itemize *

@item 
@code{FIRST = auto()} will work (auto() is replaced with @code{1});

@item 
@code{SECOND = auto(), -2} will work (auto is replaced with @code{2}, so @code{2, -2} is
used to create the @code{SECOND} enum member;

@item 
@code{THREE = [auto(), -3]} will `not' work (@code{<auto instance>, -3} is used to
create the @code{THREE} enum member)
@end itemize


Modifié dans la version 3.11.1: In prior versions, @code{auto()} had to be the only thing
on the assignment line to work properly.


@code{_generate_next_value_} peut être surchargée pour personnaliser les valeurs produites par `auto'.

@cartouche
@quotation Note 
in 3.13 the default @code{_generate_next_value_} will always return
the highest member value incremented by 1, and will fail if any
member is an incompatible type.
@end quotation
@end cartouche
@end deffn

@geindex property() (dans le module enum)
@anchor{library/enum enum property}@anchor{614}
@deffn {Fonction} @@enum.property

Décorateur similaire au `property' natif, mais spécifique aux énumérations. Il permet aux attributs de membre d'avoir les mêmes noms que les membres eux-mêmes.

@cartouche
@quotation Note 
`property' et le membre doivent être définis dans des classes distinctes ; par exemple, les attributs `value' et `name' sont définis dans la classe `Enum', et les sous-classes d'`Enum' peuvent définir des membres avec les noms @code{value} et @code{name}.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex unique() (dans le module enum)
@anchor{library/enum enum unique}@anchor{2539}
@deffn {Fonction} @@enum.unique

A @ref{12b5,,class} decorator specifically for enumerations.  It searches an
enumeration's @ref{2543,,__members__}, gathering any aliases it finds; if any are
found @ref{1ff,,ValueError} is raised with the details:

@example
>>> from enum import Enum, unique
>>> @@unique
... class Mistake(Enum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...     FOUR = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
@end example
@end deffn

@geindex verify() (dans le module enum)
@anchor{library/enum enum verify}@anchor{610}
@deffn {Fonction} @@enum.verify

Décorateur de @ref{12b5,,classe} spécifique aux énumérations. Utilisé pour spécifier quelles contraintes doivent être vérifiées par les membres de l'@ref{611,,EnumCheck} décorée.


Ajouté dans la version 3.11.

@end deffn

@geindex member() (dans le module enum)
@anchor{library/enum enum member}@anchor{612}
@deffn {Fonction} @@enum.member

Décorateur à utiliser dans les énumérations : sa cible devient un membre.


Ajouté dans la version 3.11.

@end deffn

@geindex nonmember() (dans le module enum)
@anchor{library/enum enum nonmember}@anchor{613}
@deffn {Fonction} @@enum.nonmember

Décorateur à utiliser dans les énumérations : sa cible ne devient pas un membre.


Ajouté dans la version 3.11.

@end deffn

@geindex global_enum() (dans le module enum)
@anchor{library/enum enum global_enum}@anchor{616}
@deffn {Fonction} @@enum.global_enum

A decorator to change the @ref{435,,str()} and @ref{7e7,,repr()} of an enum
to show its members as belonging to the module instead of its class.
Should only be used when the enum members are exported
to the module global namespace (see @ref{618,,re.RegexFlag} for an example).


Ajouté dans la version 3.11.

@end deffn

@geindex show_flag_values() (dans le module enum)
@anchor{library/enum enum show_flag_values}@anchor{253a}
@deffn {Fonction} enum.show_flag_values (value)

Return a list of all power-of-two integers contained in a flag `value'.


Ajouté dans la version 3.11.

@end deffn


__________________________________________________________________


@node Notes,,Utilitaires et décorateurs,enum --- Support for enumerations
@anchor{library/enum notes}@anchor{2538}
@subsubsection Notes


@ref{ccd,,IntEnum}, @ref{605,,StrEnum} et @ref{2280,,IntFlag}

@quotation

Ces trois types d'énumération sont conçus pour remplacer directement les valeurs existantes basées sur des entiers et des chaînes ; en tant que tels, ils ont des limitations supplémentaires :


@itemize -

@item 
@code{__str__} utilise la valeur et pas le nom du membre de l'énumération

@item 
@code{__format__}, parce qu'elle fait appel à @code{__str__}, utilise également la valeur du membre de l'énumération au lieu de son nom
@end itemize

Si ces limitations ne vous conviennent pas, vous pouvez créer votre propre classe mère en mélangeant vous-même le type @code{int} ou @code{str} :

@example
>>> from enum import Enum
>>> class MyIntEnum(int, Enum):
...     pass
@end example

ou vous pouvez réassigner la @ref{435,,str()} appropriée, etc., dans votre énumération :

@example
>>> from enum import Enum, IntEnum
>>> class MyIntEnum(IntEnum):
...     __str__ = Enum.__str__
@end example
@end quotation

@node graphlib --- Functionality to operate with graph-like structures,,enum --- Support for enumerations,Types de données
@anchor{library/graphlib doc}@anchor{2564}@anchor{library/graphlib graphlib-functionality-to-operate-with-graph-like-structures}@anchor{2565}@anchor{library/graphlib module-graphlib}@anchor{64}
@subsection @code{graphlib} --- Functionality to operate with graph-like structures


@geindex module; graphlib

`Code source:' Lib/graphlib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/graphlib.py}

@c import graphlib
@c from graphlib import *


__________________________________________________________________


@geindex TopologicalSorter (classe dans graphlib)
@anchor{library/graphlib graphlib TopologicalSorter}@anchor{8ce}
@deffn {Classe} graphlib.TopologicalSorter (graph=None)

Provides functionality to topologically sort a graph of @ref{5fb,,hashable} nodes.

L'ordre topologique est un ordre linéaire des sommets d'un graphe afin que pour chaque arête u → v d'un sommet u à un sommet v, cet ordre va placer le sommet u avant le sommet v. Par exemple, les sommets d'un graphe peuvent représenter une tâche à faire et une arête peut représenter la contrainte comme quoi telle tâche doit être réalisée avant telle autre. Dans cet exemple, un ordre topologique est simplement une séquence valide pour ces tâches. Cet ordre n'est possible que si le graphe n'a pas de circuit, c'est-à-dire si c'est un graphe orienté acyclique.

Si l'argument optionnel `graph' est fourni, cela doit être un dictionnaire représentant un graphe acyclique avec comme clés les nœuds et comme valeurs des itérables sur les prédécesseurs de ces nœuds dans le graphe (les nœuds qui ont des arêtes qui pointent vers la valeur de la clé). Les nœuds s'ajoutent en utilisant la méthode @ref{2566,,add()}

De manière générale, les étapes nécessaires pour trier un graphe donné sont les suivantes :


@itemize *

@item 
créer une instance de la classe @ref{8ce,,TopologicalSorter} avec éventuellement un graphe initial ;

@item 
ajouter d'autres nœuds au graphe ;

@item 
appeler @ref{2567,,prepare()} sur le graphe ;

@item 
tant que @ref{2568,,is_active()} est à @code{True}, itérer sur les nœuds renvoyés par @ref{2569,,get_ready()} pour les traiter. Appeler @ref{256a,,done()} sur chaque nœud une fois le traitement terminé.
@end itemize

Si vous souhaitez simplement trier des nœuds du graphe sans parallélisme, la méthode @ref{256b,,TopologicalSorter.static_order()} peut être utilisée directement :

@example
>>> graph = @{"D": @{"B", "C"@}, "C": @{"A"@}, "B": @{"A"@}@}
>>> ts = TopologicalSorter(graph)
>>> tuple(ts.static_order())
('A', 'C', 'B', 'D')
@end example

La classe est conçue pour prendre facilement en charge le traitement en parallèle des nœuds quand ils deviennent disponibles. Par exemple :

@example
topological_sorter = TopologicalSorter()

# Add nodes to 'topological_sorter'...

topological_sorter.prepare()
while topological_sorter.is_active():
    for node in topological_sorter.get_ready():
        # Worker threads or processes take nodes to work on off the
        # 'task_queue' queue.
        task_queue.put(node)

    # When the work for a node is done, workers put the node in
    # 'finalized_tasks_queue' so we can get more nodes to work on.
    # The definition of 'is_active()' guarantees that, at this point, at
    # least one node has been placed on 'task_queue' that hasn't yet
    # been passed to 'done()', so this blocking 'get()' must (eventually)
    # succeed.  After calling 'done()', we loop back to call 'get_ready()'
    # again, so put newly freed nodes on 'task_queue' as soon as
    # logically possible.
    node = finalized_tasks_queue.get()
    topological_sorter.done(node)
@end example

@geindex add() (méthode graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter add}@anchor{2566}
@deffn {Méthode} add (node, *predecessors)

Add a new node and its predecessors to the graph. Both the `node' and all
elements in `predecessors' must be @ref{5fb,,hashable}.

S'il est appelé plusieurs fois avec le même nœud en tant qu'argument, l'ensemble des dépendances sera l'union de toutes les dépendances qui auront été transmises.

Il est possible d'ajouter un nœud sans dépendance (`predecessors' n'est pas fourni) ou de fournir une dépendance deux fois. Si un nœud qui n'a jamais été fourni auparavant est inclus dans `predecessors' il sera automatiquement ajouté au graphe sans prédécesseur lui-même.

Lève une @ref{1ff,,ValueError} si appelée après @ref{2567,,prepare()}.
@end deffn

@geindex prepare() (méthode graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter prepare}@anchor{2567}
@deffn {Méthode} prepare ()

Indique que le graphe est terminé et vérifie les circuits du graphe. Si un circuit est détecté, une @ref{256c,,CycleError} est levée mais @ref{2569,,get_ready()} peut encore être utilisée pour obtenir autant de nœuds que possible avant que les circuits ne bloquent la progression. Après un appel de cette fonction, le graphe ne peut pas être modifié, et donc aucun nœud ne peut être ajouté avec @ref{2566,,add()}.
@end deffn

@geindex is_active() (méthode graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter is_active}@anchor{2568}
@deffn {Méthode} is_active ()

Renvoie @code{True} si une progression peut être faite et @code{False} dans le cas contraire. La progression est possible si des circuits ne bloquent pas la résolution ou qu'il reste des nœuds prêts qui n'ont pas encore été renvoyés par @ref{2569,,TopologicalSorter.get_ready()} ou que le nombre de nœuds marqués @ref{256a,,TopologicalSorter.done()} est inférieur au nombre qui a été renvoyé par @ref{2569,,TopologicalSorter.get_ready()}.

The @ref{12b3,,__bool__()} method of this class defers to
this function, so instead of:

@example
if ts.is_active():
    ...
@end example

il est plus simple de faire :

@example
if ts:
    ...
@end example

Lève une @ref{1ff,,ValueError} si l'appel à @ref{2567,,prepare()} n'a pas été fait au préalable.
@end deffn

@geindex done() (méthode graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter done}@anchor{256a}
@deffn {Méthode} done (*nodes)

Marque un ensemble de nœuds renvoyé par @ref{2569,,TopologicalSorter.get_ready()} comme traités, permettant aux successeurs de chaque nœud de `nodes' d'être renvoyés lors d'un prochain appel à @ref{2569,,get_ready()}.

Lève une @ref{1ff,,ValueError} si n'importe quel nœud dans `nodes' a déjà été marqué comme traité par un précédent appel à cette méthode ou si un nœud n'a pas été ajouté au graphe en utilisant @ref{2566,,TopologicalSorter.add()}, si l'appel est fait sans appel à @ref{2567,,prepare()} ou si le nœud n'a pas encore été renvoyé par @ref{2569,,get_ready()}.
@end deffn

@geindex get_ready() (méthode graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter get_ready}@anchor{2569}
@deffn {Méthode} get_ready ()

Renvoie un `n'-uplet avec tous les nœuds prêts. Renvoie d'abord tous les nœuds sans prédécesseurs, et une fois marqués comme traités avec un appel de @ref{256a,,TopologicalSorter.done()}, les autres appels renvoient tous les nouveaux nœuds dont tous les prédécesseurs sont traités. Une fois que la progression n'est plus possible, des tuples vides sont renvoyés.

Lève une @ref{1ff,,ValueError} si l'appel à @ref{2567,,prepare()} n'a pas été fait au préalable.
@end deffn

@geindex static_order() (méthode graphlib.TopologicalSorter)
@anchor{library/graphlib graphlib TopologicalSorter static_order}@anchor{256b}
@deffn {Méthode} static_order ()

Returns an iterator object which will iterate over nodes in a topological
order. When using this method, @ref{2567,,prepare()} and
@ref{256a,,done()} should not be called. This method is
equivalent to:

@example
def static_order(self):
    self.prepare()
    while self.is_active():
        node_group = self.get_ready()
        yield from node_group
        self.done(*node_group)
@end example

Le tri obtenu peut dépendre de l'ordre dans lequel les éléments ont été ajoutés dans le graphe. Par exemple :

@example
>>> ts = TopologicalSorter()
>>> ts.add(3, 2, 1)
>>> ts.add(1, 0)
>>> print([*ts.static_order()])
[2, 0, 1, 3]

>>> ts2 = TopologicalSorter()
>>> ts2.add(1, 0)
>>> ts2.add(3, 2, 1)
>>> print([*ts2.static_order()])
[0, 2, 1, 3]
@end example

Ceci est dû au fait que "0" et "2" sont au même niveau dans le graphe (ils auraient été renvoyés dans le même appel à @ref{2569,,get_ready()}) et l'ordre entre eux est déterminé par l'ordre lors de l'insertion.

Si un circuit est détecté alors une @ref{256c,,CycleError} est levée.
@end deffn


Ajouté dans la version 3.9.

@end deffn

@menu
* Exceptions: Exceptions<4>. 

@end menu

@node Exceptions<4>,,,graphlib --- Functionality to operate with graph-like structures
@anchor{library/graphlib exceptions}@anchor{256d}
@subsubsection Exceptions


Le module @ref{64,,graphlib} définit les classes d'exceptions suivantes :

@geindex CycleError
@anchor{library/graphlib graphlib CycleError}@anchor{256c}
@deffn {Exception} graphlib.CycleError

Une classe héritant de @ref{1ff,,ValueError} levée par @ref{2567,,TopologicalSorter.prepare()} si un circuit existe dans le graphe courant. Si plusieurs circuits existent, un seul est inclus dans l'exception.

The detected cycle can be accessed via the second element in the @ref{558,,args}
attribute of the exception instance and consists in a list of nodes, such that each node is,
in the graph, an immediate predecessor of the next node in the list. In the reported list,
the first and the last node will be the same, to make it clear that it is cyclic.
@end deffn

@node Modules numériques et mathématiques,Modules de programmation fonctionnelle,Types de données,La bibliothèque standard
@anchor{library/numeric doc}@anchor{256e}@anchor{library/numeric numeric}@anchor{256f}@anchor{library/numeric numeric-and-mathematical-modules}@anchor{2570}
@section Modules numériques et mathématiques


Les modules documentés dans ce chapitre fournissent des fonctions et des types autour des nombres et des mathématiques. Le module @ref{9d,,numbers} définit une hiérarchie abstraite des types numériques. Les modules @ref{8d,,math} et @ref{18,,cmath} contiennent des fonctions mathématiques pour les nombres à virgule flottante ou les nombres complexes.  Le module @ref{36,,decimal} permet de représenter des nombres décimaux de manière exacte, et utilise une arithmétique de précision arbitraire.

Les modules suivants sont documentés dans ce chapitre :

@menu
* numbers: numbers --- Numeric abstract base classes. Numeric abstract base classes
* math: math --- Mathematical functions. Mathematical functions
* cmath: cmath --- Mathematical functions for complex numbers. Mathematical functions for complex numbers
* decimal: decimal --- Decimal fixed-point and floating-point arithmetic. Decimal fixed-point and floating-point arithmetic
* fractions: fractions --- Rational numbers. Rational numbers
* random: random --- Generate pseudo-random numbers. Generate pseudo-random numbers
* statistics: statistics --- Mathematical statistics functions. Mathematical statistics functions

@end menu

@node numbers --- Numeric abstract base classes,math --- Mathematical functions,,Modules numériques et mathématiques
@anchor{library/numbers doc}@anchor{2571}@anchor{library/numbers module-numbers}@anchor{9d}@anchor{library/numbers numbers-numeric-abstract-base-classes}@anchor{2572}
@subsection @code{numbers} --- Numeric abstract base classes


@geindex module; numbers

`Code source :' Lib/numbers.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/numbers.py}


__________________________________________________________________


The @code{numbers} module (
@geindex Python Enhancement Proposals; PEP 3141
PEP 3141@footnote{https://peps.python.org/pep-3141/}) defines a hierarchy of numeric
@ref{1193,,abstract base classes} which progressively define
more operations.  None of the types defined in this module are intended to be instantiated.

@geindex Number (classe dans numbers)
@anchor{library/numbers numbers Number}@anchor{2573}
@deffn {Classe} numbers.Number

La base de la hiérarchie numérique. Si vous voulez juste vérifier qu'un argument `x' est un nombre, peu importe le type, utilisez @code{isinstance(x, Number)}.
@end deffn

@menu
* La tour numérique:: 
* Notes for type implementers:: 

@end menu

@node La tour numérique,Notes for type implementers,,numbers --- Numeric abstract base classes
@anchor{library/numbers the-numeric-tower}@anchor{2574}
@subsubsection La tour numérique


@geindex Complex (classe dans numbers)
@anchor{library/numbers numbers Complex}@anchor{2575}
@deffn {Classe} numbers.Complex

Subclasses of this type describe complex numbers and include the operations
that work on the built-in @ref{2ec,,complex} type. These are: conversions to
@ref{2ec,,complex} and @ref{451,,bool}, @ref{2576,,real}, @ref{2577,,imag}, @code{+},
@code{-}, @code{*}, @code{/}, @code{**}, @ref{1c32,,abs()}, @ref{2578,,conjugate()}, @code{==}, and
@code{!=}. All except @code{-} and @code{!=} are abstract.

@geindex real (attribut numbers.Complex)
@anchor{library/numbers numbers Complex real}@anchor{2576}
@deffn {Attribut} real

Abstrait. Récupère la partie réelle de ce nombre.
@end deffn

@geindex imag (attribut numbers.Complex)
@anchor{library/numbers numbers Complex imag}@anchor{2577}
@deffn {Attribut} imag

Abstrait. Retrouve la partie imaginaire de ce nombre.
@end deffn

@geindex conjugate() (méthode numbers.Complex)
@anchor{library/numbers numbers Complex conjugate}@anchor{2578}
@deffn {Méthode} abstractmethod conjugate ()

Abstrait. Renvoie le complexe conjugué. Par exemple, @code{(1+3j).conjugate() == (1-3j)}.
@end deffn
@end deffn

@geindex Real (classe dans numbers)
@anchor{library/numbers numbers Real}@anchor{211f}
@deffn {Classe} numbers.Real

To @ref{2575,,Complex}, @code{Real} adds the operations that work on real
numbers.

En bref, celles-ci sont : une conversion vers @ref{2eb,,float}, @ref{137a,,math.trunc()}, @ref{12b8,,round()}, @ref{1378,,math.floor()}, @ref{1379,,math.ceil()}, @ref{98f,,divmod()}, @code{//}, @code{%}, @code{<}, @code{<=}, @code{>} et @code{>=}.

`Real' fournit également des valeurs par défaut pour @ref{2ec,,complex()}, @ref{2576,,real}, @ref{2577,,imag} et @ref{2578,,conjugate()}.
@end deffn

@geindex Rational (classe dans numbers)
@anchor{library/numbers numbers Rational}@anchor{129c}
@deffn {Classe} numbers.Rational

Subtypes @ref{211f,,Real} and adds @ref{2579,,numerator} and
@ref{257a,,denominator} properties. It also provides a default for
@ref{2eb,,float()}.

The @ref{2579,,numerator} and @ref{257a,,denominator} values
should be instances of @ref{1f3f,,Integral} and should be in lowest terms with
@ref{257a,,denominator} positive.

@geindex numerator (attribut numbers.Rational)
@anchor{library/numbers numbers Rational numerator}@anchor{2579}
@deffn {Attribut} numerator

Abstrait.
@end deffn

@geindex denominator (attribut numbers.Rational)
@anchor{library/numbers numbers Rational denominator}@anchor{257a}
@deffn {Attribut} denominator

Abstrait.
@end deffn
@end deffn

@geindex Integral (classe dans numbers)
@anchor{library/numbers numbers Integral}@anchor{1f3f}
@deffn {Classe} numbers.Integral

Subtypes @ref{129c,,Rational} and adds a conversion to @ref{254,,int}.  Provides
defaults for @ref{2eb,,float()}, @ref{2579,,numerator}, and
@ref{257a,,denominator}.  Adds abstract methods for @ref{9c0,,pow()} with
modulus and bit-string operations: @code{<<}, @code{>>}, @code{&}, @code{^}, @code{|},
@code{~}.
@end deffn

@node Notes for type implementers,,La tour numérique,numbers --- Numeric abstract base classes
@anchor{library/numbers notes-for-type-implementers}@anchor{257b}
@subsubsection Notes for type implementers


Implementers should be careful to make equal numbers equal and hash
them to the same values. This may be subtle if there are two different
extensions of the real numbers. For example, @ref{1e4,,fractions.Fraction}
implements @ref{5d5,,hash()} as follows:

@example
def __hash__(self):
    if self.denominator == 1:
        # Get integers right.
        return hash(self.numerator)
    # Expensive check, but definitely correct.
    if self == float(self):
        return hash(float(self))
    else:
        # Use tuple's hash to avoid a high collision rate on
        # simple fractions.
        return hash((self.numerator, self.denominator))
@end example

@menu
* Ajouter plus d'ABC numériques:: 
* Implémentation des opérations arithmétiques:: 

@end menu

@node Ajouter plus d'ABC numériques,Implémentation des opérations arithmétiques,,Notes for type implementers
@anchor{library/numbers adding-more-numeric-abcs}@anchor{257c}
@subsubsection Ajouter plus d'ABC numériques


Il est bien entendu possible de créer davantage d’ABC pour les nombres et cette hiérarchie serait médiocre si elle excluait la possibilité d'en ajouter. Vous pouvez ajouter @code{MyFoo} entre @ref{2575,,Complex} et @ref{211f,,Real} ainsi :

@example
class MyFoo(Complex): ...
MyFoo.register(Real)
@end example

@node Implémentation des opérations arithmétiques,,Ajouter plus d'ABC numériques,Notes for type implementers
@anchor{library/numbers id1}@anchor{257d}@anchor{library/numbers implementing-the-arithmetic-operations}@anchor{1e6d}
@subsubsection Implémentation des opérations arithmétiques


We want to implement the arithmetic operations so that mixed-mode
operations either call an implementation whose author knew about the
types of both arguments, or convert both to the nearest built in type
and do the operation there. For subtypes of @ref{1f3f,,Integral}, this
means that @ref{1f0f,,__add__()} and @ref{1f10,,__radd__()} should be
defined as:

@example
class MyIntegral(Integral):

    def __add__(self, other):
        if isinstance(other, MyIntegral):
            return do_my_adding_stuff(self, other)
        elif isinstance(other, OtherTypeIKnowAbout):
            return do_my_other_adding_stuff(self, other)
        else:
            return NotImplemented

    def __radd__(self, other):
        if isinstance(other, MyIntegral):
            return do_my_adding_stuff(other, self)
        elif isinstance(other, OtherTypeIKnowAbout):
            return do_my_other_adding_stuff(other, self)
        elif isinstance(other, Integral):
            return int(other) + int(self)
        elif isinstance(other, Real):
            return float(other) + float(self)
        elif isinstance(other, Complex):
            return complex(other) + complex(self)
        else:
            return NotImplemented
@end example

Il existe 5 cas différents pour une opération de type mixte sur des sous-classes de @ref{2575,,Complex}. Nous nous référerons à tout le code ci-dessus qui ne se réfère pas à @code{MyIntegral} et @code{OtherTypeIKnowAbout} comme "expression générique". @code{a} est une instance de @code{A}, qui est un sous-type de @ref{2575,,Complex} (@code{a : A <: Complex}) et @code{b : B <: Complex}. Considérons @code{a + b} :


@enumerate 

@item 
If @code{A} defines an @ref{1f0f,,__add__()} which accepts @code{b}, all is
well.

@item 
If @code{A} falls back to the boilerplate code, and it were to
return a value from @ref{1f0f,,__add__()}, we'd miss the possibility
that @code{B} defines a more intelligent @ref{1f10,,__radd__()}, so the
boilerplate should return @ref{7bc,,NotImplemented} from
@code{__add__()}. (Or @code{A} may not implement @code{__add__()} at
all.)

@item 
Then @code{B}'s @ref{1f10,,__radd__()} gets a chance. If it accepts
@code{a}, all is well.

@item 
Si elle fait appel au code générique, il n'y a plus de méthode possible à essayer, c'est donc ici que l'implémentation par défaut intervient.

@item 
Si @code{B < : A}, Python essaie @code{B.__radd__} avant @code{A.__add__}. C'est valable parce qu'elle est implémentée avec la connaissance de @code{A}, donc elle peut gérer ces instances avant de déléguer à @ref{2575,,Complex}.
@end enumerate

If @code{A <: Complex} and @code{B <: Real} without sharing any other knowledge,
then the appropriate shared operation is the one involving the built
in @ref{2ec,,complex}, and both @ref{1f10,,__radd__()} s land there, so @code{a+b
== b+a}.

Comme la plupart des opérations sur un type donné seront très similaires, il peut être utile de définir une fonction accessoire qui génère les instances résultantes et inverses d'un opérateur donné. Par exemple, @ref{1e4,,fractions.Fraction} utilise :

@example
def _operator_fallbacks(monomorphic_operator, fallback_operator):
    def forward(a, b):
        if isinstance(b, (int, Fraction)):
            return monomorphic_operator(a, b)
        elif isinstance(b, float):
            return fallback_operator(float(a), b)
        elif isinstance(b, complex):
            return fallback_operator(complex(a), b)
        else:
            return NotImplemented
    forward.__name__ = '__' + fallback_operator.__name__ + '__'
    forward.__doc__ = monomorphic_operator.__doc__

    def reverse(b, a):
        if isinstance(a, Rational):
            # Includes ints.
            return monomorphic_operator(a, b)
        elif isinstance(a, Real):
            return fallback_operator(float(a), float(b))
        elif isinstance(a, Complex):
            return fallback_operator(complex(a), complex(b))
        else:
            return NotImplemented
    reverse.__name__ = '__r' + fallback_operator.__name__ + '__'
    reverse.__doc__ = monomorphic_operator.__doc__

    return forward, reverse

def _add(a, b):
    """a + b"""
    return Fraction(a.numerator * b.denominator +
                    b.numerator * a.denominator,
                    a.denominator * b.denominator)

__add__, __radd__ = _operator_fallbacks(_add, operator.add)

# ...
@end example

@node math --- Mathematical functions,cmath --- Mathematical functions for complex numbers,numbers --- Numeric abstract base classes,Modules numériques et mathématiques
@anchor{library/math doc}@anchor{257e}@anchor{library/math math-mathematical-functions}@anchor{257f}@anchor{library/math module-math}@anchor{8d}
@subsection @code{math} --- Mathematical functions


@geindex module; math

@c from math import fsum


__________________________________________________________________


Ce module fournit l'accès aux fonctions mathématiques définies par la norme C.

Ces fonctions ne peuvent pas être utilisées avec les nombres complexes ; si vous avez besoin de la prise en charge des nombres complexes, utilisez les fonctions du même nom du module @ref{18,,cmath}. La séparation entre les fonctions qui gèrent les nombres complexes et les autres vient du constat que tous les utilisateurs ne souhaitent pas acquérir le niveau mathématique nécessaire à la compréhension des nombres complexes. Recevoir une exception plutôt qu'un nombre complexe en retour d'une fonction permet au programmeur de déterminer immédiatement comment et pourquoi ce nombre a été généré, avant que celui-ci ne soit passé involontairement en paramètre d'une autre fonction.

Les fonctions suivantes sont fournies dans ce module. Sauf mention contraire explicite, toutes les valeurs de retour sont des flottants.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

`Number-theoretic functions'

@tab

@item

@ref{6ba,,comb(n@comma{} k)}

@tab

Number of ways to choose `k' items from `n' items without repetition and without order

@item

@ref{934,,factorial(n)}

@tab

`n' factorial

@item

@ref{8fd,,gcd(*integers)}

@tab

Greatest common divisor of the integer arguments

@item

@ref{9f3,,isqrt(n)}

@tab

Integer square root of a nonnegative integer `n'

@item

@ref{8fe,,lcm(*integers)}

@tab

Least common multiple of the integer arguments

@item

@ref{6bb,,perm(n@comma{} k)}

@tab

Number of ways to choose `k' items from `n' items without repetition and with order

@item

`Floating point arithmetic'

@tab

@item

@ref{1379,,ceil(x)}

@tab

Ceiling of `x', the smallest integer greater than or equal to `x'

@item

@ref{2580,,fabs(x)}

@tab

Absolute value of `x'

@item

@ref{1378,,floor(x)}

@tab

Floor of `x', the largest integer less than or equal to `x'

@item

@ref{202,,fma(x@comma{} y@comma{} z)}

@tab

Fused multiply-add operation: @code{(x * y) + z}

@item

@ref{1fec,,fmod(x@comma{} y)}

@tab

Remainder of division @code{x / y}

@item

@ref{2581,,modf(x)}

@tab

Fractional and integer parts of `x'

@item

@ref{b41,,remainder(x@comma{} y)}

@tab

Remainder of `x' with respect to `y'

@item

@ref{137a,,trunc(x)}

@tab

Integer part of `x'

@item

`Floating point manipulation functions'

@tab

@item

@ref{138a,,copysign(x@comma{} y)}

@tab

Magnitude (absolute value) of `x' with the sign of `y'

@item

@ref{2582,,frexp(x)}

@tab

Mantissa and exponent of `x'

@item

@ref{d9d,,isclose(a@comma{} b@comma{} rel_tol@comma{} abs_tol)}

@tab

Check if the values `a' and `b' are close to each other

@item

@ref{11c8,,isfinite(x)}

@tab

Check if `x' is neither an infinity nor a NaN

@item

@ref{1388,,isinf(x)}

@tab

Check if `x' is a positive or negative infinity

@item

@ref{1389,,isnan(x)}

@tab

Check if `x' is a NaN  (not a number)

@item

@ref{2583,,ldexp(x@comma{} i)}

@tab

@code{x * (2**i)}, inverse of function @ref{2582,,frexp()}

@item

@ref{482,,nextafter(x@comma{} y@comma{} steps)}

@tab

Floating-point value `steps' steps after `x' towards `y'

@item

@ref{8ff,,ulp(x)}

@tab

Value of the least significant bit of `x'

@item

`Power, exponential and logarithmic functions'

@tab

@item

@ref{64c,,cbrt(x)}

@tab

Cube root of `x'

@item

@ref{12f2,,exp(x)}

@tab

`e' raised to the power `x'

@item

@ref{64b,,exp2(x)}

@tab

`2' raised to the power `x'

@item

@ref{11c9,,expm1(x)}

@tab

`e' raised to the power `x', minus 1

@item

@ref{1474,,log(x@comma{} base)}

@tab

Logarithm of `x' to the given base (`e' by default)

@item

@ref{138f,,log1p(x)}

@tab

Natural logarithm of `1+x' (base `e')

@item

@ref{10bd,,log2(x)}

@tab

Base-2 logarithm of `x'

@item

@ref{2584,,log10(x)}

@tab

Base-10 logarithm of `x'

@item

@ref{64d,,pow(x@comma{} y)}

@tab

`x' raised to the power `y'

@item

@ref{9f4,,sqrt(x)}

@tab

Square root of `x'

@item

`Summation and product functions'

@tab

@item

@ref{9f0,,dist(p@comma{} q)}

@tab

Euclidean distance between two points `p' and `q' given as an iterable of coordinates

@item

@ref{138b,,fsum(iterable)}

@tab

Sum of values in the input `iterable'

@item

@ref{9f1,,hypot(*coordinates)}

@tab

Euclidean norm of an iterable of coordinates

@item

@ref{9f2,,prod(iterable@comma{} start)}

@tab

Product of elements in the input `iterable' with a `start' value

@item

@ref{481,,sumprod(p@comma{} q)}

@tab

Sum of products from two iterables `p' and `q'

@item

`Angular conversion'

@tab

@item

@ref{2585,,degrees(x)}

@tab

Convert angle `x' from radians to degrees

@item

@ref{2586,,radians(x)}

@tab

Convert angle `x' from degrees to radians

@item

`Trigonometric functions'

@tab

@item

@ref{2587,,acos(x)}

@tab

Arc cosine of `x'

@item

@ref{2588,,asin(x)}

@tab

Arc sine of `x'

@item

@ref{2589,,atan(x)}

@tab

Arc tangent of `x'

@item

@ref{258a,,atan2(y@comma{} x)}

@tab

@code{atan(y / x)}

@item

@ref{1473,,cos(x)}

@tab

Cosine of `x'

@item

@ref{1472,,sin(x)}

@tab

Sine of `x'

@item

@ref{258b,,tan(x)}

@tab

Tangent of `x'

@item

`Hyperbolic functions'

@tab

@item

@ref{138c,,acosh(x)}

@tab

Inverse hyperbolic cosine of `x'

@item

@ref{138d,,asinh(x)}

@tab

Inverse hyperbolic sine of `x'

@item

@ref{138e,,atanh(x)}

@tab

Inverse hyperbolic tangent of `x'

@item

@ref{258c,,cosh(x)}

@tab

Hyperbolic cosine of `x'

@item

@ref{258d,,sinh(x)}

@tab

Hyperbolic sine of `x'

@item

@ref{258e,,tanh(x)}

@tab

Hyperbolic tangent of `x'

@item

`Special functions'

@tab

@item

@ref{bc6,,erf(x)}

@tab

Error function@footnote{https://en.wikipedia.org/wiki/Error_function} at `x'

@item

@ref{bc7,,erfc(x)}

@tab

Complementary error function@footnote{https://en.wikipedia.org/wiki/Error_function} at `x'

@item

@ref{11ca,,gamma(x)}

@tab

Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at `x'

@item

@ref{11cb,,lgamma(x)}

@tab

Natural logarithm of the absolute value of the Gamma function@footnote{https://en.wikipedia.org/wiki/Gamma_function} at `x'

@item

`Constants'

@tab

@item

@ref{258f,,pi}

@tab

`π' = 3.141592...

@item

@ref{2590,,e}

@tab

`e' = 2.718281...

@item

@ref{2591,,tau}

@tab

`τ' = 2`π' = 6.283185...

@item

@ref{c72,,inf}

@tab

Positive infinity

@item

@ref{64e,,nan}

@tab

"Not a number" (NaN)

@end multitable


@menu
* Number-theoretic functions:: 
* Floating point arithmetic:: 
* Floating point manipulation functions:: 
* Power@comma{} exponential and logarithmic functions: Power exponential and logarithmic functions. 
* Summation and product functions:: 
* Conversion angulaire:: 
* Fonctions trigonométriques:: 
* Fonctions hyperboliques:: 
* Fonctions spéciales:: 
* Constantes: Constantes<2>. 

@end menu

@node Number-theoretic functions,Floating point arithmetic,,math --- Mathematical functions
@anchor{library/math number-theoretic-functions}@anchor{2592}
@subsubsection Number-theoretic functions


@geindex comb() (dans le module math)
@anchor{library/math math comb}@anchor{6ba}
@deffn {Fonction} math.comb (n, k)

Renvoie le nombre de façons de choisir `k' éléments parmi `n' de manière non-ordonnée et sans répétition.

Vaut @code{n! / (k! * (n - k)!)} quand @code{k <= n} et zéro quand @code{k > n}.

Also called the binomial coefficient because it is equivalent
to the coefficient of k-th term in polynomial expansion of
@code{(1 + x)ⁿ}.

Lève une @ref{522,,TypeError} si un des paramètres n'est pas un entier. Lève une @ref{1ff,,ValueError} si un des paramètres est négatif.


Ajouté dans la version 3.8.

@end deffn

@geindex factorial() (dans le module math)
@anchor{library/math math factorial}@anchor{934}
@deffn {Fonction} math.factorial (n)

Return `n' factorial as an integer.  Raises @ref{1ff,,ValueError} if `n' is not integral or
is negative.


Modifié dans la version 3.10: Floats with integral values (like @code{5.0}) are no longer accepted.

@end deffn

@geindex gcd() (dans le module math)
@anchor{library/math math gcd}@anchor{8fd}
@deffn {Fonction} math.gcd (*integers)

Return the greatest common divisor of the specified integer arguments.
If any of the arguments is nonzero, then the returned value is the largest
positive integer that is a divisor of all arguments.  If all arguments
are zero, then the returned value is @code{0}.  @code{gcd()} without arguments
returns @code{0}.


Ajouté dans la version 3.5.



Modifié dans la version 3.9: Added support for an arbitrary number of arguments. Formerly, only two
arguments were supported.

@end deffn

@geindex isqrt() (dans le module math)
@anchor{library/math math isqrt}@anchor{9f3}
@deffn {Fonction} math.isqrt (n)

Renvoie la racine carrée entière du nombre positif `n'. C'est la partie entière de la valeur exacte de la racine carrée de `n' ou, de manière équivalente, le plus grand entier `a' tel que a*² ≤ `n'.

Pour certaines applications, il est plus pratique d'avoir le plus petit entier `a' tel que `n' ≤ `a'² ou, en d'autres termes, la partie entière de la valeur exacte de la racine carrée de `n'. Pour `n' positif, on peut le calculer avec @code{a = 1 + isqrt(n - 1)}.


Ajouté dans la version 3.8.

@end deffn

@geindex lcm() (dans le module math)
@anchor{library/math math lcm}@anchor{8fe}
@deffn {Fonction} math.lcm (*integers)

Return the least common multiple of the specified integer arguments.
If all arguments are nonzero, then the returned value is the smallest
positive integer that is a multiple of all arguments.  If any of the arguments
is zero, then the returned value is @code{0}.  @code{lcm()} without arguments
returns @code{1}.


Ajouté dans la version 3.9.

@end deffn

@geindex perm() (dans le module math)
@anchor{library/math math perm}@anchor{6bb}
@deffn {Fonction} math.perm (n, k=None)

Renvoie le nombre de façons de choisir `k' éléments parmi `n' de manière ordonnée sans répétition.

Vaut @code{n! / (n - k)!} quand @code{k <= n} et vaut zéro quand @code{k > n}.

If `k' is not specified or is @code{None}, then `k' defaults to `n'
and the function returns @code{n!}.

Lève une @ref{522,,TypeError} si un des paramètres n'est pas un entier. Lève une @ref{1ff,,ValueError} si un des paramètres est négatif.


Ajouté dans la version 3.8.

@end deffn

@node Floating point arithmetic,Floating point manipulation functions,Number-theoretic functions,math --- Mathematical functions
@anchor{library/math floating-point-arithmetic}@anchor{2593}
@subsubsection Floating point arithmetic


@geindex ceil() (dans le module math)
@anchor{library/math math ceil}@anchor{1379}
@deffn {Fonction} math.ceil (x)

Return the ceiling of `x', the smallest integer greater than or equal to `x'.
If `x' is not a float, delegates to @ref{1f3e,,x.__ceil__},
which should return an @ref{1f3f,,Integral} value.
@end deffn

@geindex fabs() (dans le module math)
@anchor{library/math math fabs}@anchor{2580}
@deffn {Fonction} math.fabs (x)

Renvoie la valeur absolue de `x'.
@end deffn

@geindex floor() (dans le module math)
@anchor{library/math math floor}@anchor{1378}
@deffn {Fonction} math.floor (x)

Return the floor of `x', the largest integer less than or equal to `x'.  If
`x' is not a float, delegates to @ref{1f3d,,x.__floor__}, which
should return an @ref{1f3f,,Integral} value.
@end deffn

@geindex fma() (dans le module math)
@anchor{library/math math fma}@anchor{202}
@deffn {Fonction} math.fma (x, y, z)

Fused multiply-add operation. Return @code{(x * y) + z}, computed as though with
infinite precision and range followed by a single round to the @code{float}
format. This operation often provides better accuracy than the direct
expression @code{(x * y) + z}.

This function follows the specification of the fusedMultiplyAdd operation
described in the IEEE 754 standard. The standard leaves one case
implementation-defined, namely the result of @code{fma(0, inf, nan)}
and @code{fma(inf, 0, nan)}. In these cases, @code{math.fma} returns a NaN,
and does not raise any exception.


Ajouté dans la version 3.13.

@end deffn

@geindex fmod() (dans le module math)
@anchor{library/math math fmod}@anchor{1fec}
@deffn {Fonction} math.fmod (x, y)

Return the floating-point remainder of @code{x / y},
as defined by the platform C library function @code{fmod(x, y)}. Note that the
Python expression @code{x % y} may not return the same result.  The intent of the C
standard is that @code{fmod(x, y)} be exactly (mathematically; to infinite
precision) equal to @code{x - n*y} for some integer `n' such that the result has
the same sign as `x' and magnitude less than @code{abs(y)}.  Python's @code{x % y}
returns a result with the sign of `y' instead, and may not be exactly computable
for float arguments. For example, @code{fmod(-1e-100, 1e100)} is @code{-1e-100}, but
the result of Python's @code{-1e-100 % 1e100} is @code{1e100-1e-100}, which cannot be
represented exactly as a float, and rounds to the surprising @code{1e100}.  For
this reason, function @ref{1fec,,fmod()} is generally preferred when working with
floats, while Python's @code{x % y} is preferred when working with integers.
@end deffn

@geindex modf() (dans le module math)
@anchor{library/math math modf}@anchor{2581}
@deffn {Fonction} math.modf (x)

Renvoie les parties entière et fractionnelle de `x'. Les deux résultats ont le signe de `x' et sont flottants.

Note that @ref{2581,,modf()} has a different call/return pattern
than its C equivalents: it takes a single argument and return a pair of
values, rather than returning its second return value through an 'output
parameter' (there is no such thing in Python).
@end deffn

@geindex remainder() (dans le module math)
@anchor{library/math math remainder}@anchor{b41}
@deffn {Fonction} math.remainder (x, y)

Renvoie le reste selon la norme IEEE 754 de `x' par rapport à `y'. Pour `x' fini et `y' fini non nul, il s'agit de la différence @code{x - n*y}, où @code{n} est l'entier le plus proche de la valeur exacte du quotient @code{x / y}. Si @code{x / y} est exactement à mi-chemin de deux entiers consécutifs, le plus proche entier `pair' est utilisé pour @code{n}. Ainsi, le reste @code{r = remainder(x, y)} vérifie toujours @code{abs(r) <= 0.5 * abs(y)}.

Les cas spéciaux suivent la norme IEEE 754 : en particulier, @code{remainder(x, math.inf)} vaut `x' pour tout `x' fini,  et @code{remainder(x, 0)} et @code{remainder(math.inf, x)} lèvent @ref{1ff,,ValueError} pour tout `x' `non-NaN'. Si le résultat de l'opération `remainder' est zéro, alors  ce zéro aura le même signe que `x'.

On platforms using IEEE 754 binary floating point, the result of this
operation is always exactly representable: no rounding error is introduced.


Ajouté dans la version 3.7.

@end deffn

@geindex trunc() (dans le module math)
@anchor{library/math math trunc}@anchor{137a}
@deffn {Fonction} math.trunc (x)

Return `x' with the fractional part
removed, leaving the integer part.  This rounds toward 0: @code{trunc()} is
equivalent to @ref{1378,,floor()} for positive `x', and equivalent to @ref{1379,,ceil()}
for negative `x'. If `x' is not a float, delegates to @ref{705,,x.__trunc__}, which should return an @ref{1f3f,,Integral} value.
@end deffn

Pour les fonctions @ref{1379,,ceil()}, @ref{1378,,floor()}, et @ref{2581,,modf()}, notez que `tous' les nombres flottants de magnitude suffisamment grande sont des entiers exacts. Les flottants de Python n'ont généralement pas plus de 53 `bits' de précision (tels que le type C @code{double} de la plate-forme), en quel cas tout flottant `x' tel que @code{abs(x) >= 2**52} n'a aucun `bit' fractionnel.

@node Floating point manipulation functions,Power exponential and logarithmic functions,Floating point arithmetic,math --- Mathematical functions
@anchor{library/math floating-point-manipulation-functions}@anchor{2594}
@subsubsection Floating point manipulation functions


@geindex copysign() (dans le module math)
@anchor{library/math math copysign}@anchor{138a}
@deffn {Fonction} math.copysign (x, y)

Renvoie un flottant contenant la magnitude (valeur absolue) de `x' mais avec le signe de `y'. Sur les plates-formes prenant en charge les zéros signés, @code{copysign(1.0, -0.0)} renvoie @code{-1.0}.
@end deffn

@geindex frexp() (dans le module math)
@anchor{library/math math frexp}@anchor{2582}
@deffn {Fonction} math.frexp (x)

Renvoie la mantisse et l'exposant de `x' dans un couple @code{(m, e)}. `m' est un flottant et `e' est un entier tels que @code{x == m * 2**e} exactement. Si `x' vaut zéro, renvoie @code{(0, 0)}, sinon @code{0.5 <= abs(m) < 1}. Ceci est utilisé pour « extraire » la représentation interne d'un flottant de manière portable.

Note that @ref{2582,,frexp()} has a different call/return pattern
than its C equivalents: it takes a single argument and return a pair of
values, rather than returning its second return value through an 'output
parameter' (there is no such thing in Python).
@end deffn

@geindex isclose() (dans le module math)
@anchor{library/math math isclose}@anchor{d9d}
@deffn {Fonction} math.isclose (a, b, *, rel_tol=1e-09, abs_tol=0.0)

Renvoie @code{True} si les valeurs `a' et `b' sont proches l'une de l'autre, et @code{False} sinon.

Whether or not two values are considered close is determined according to
given absolute and relative tolerances.  If no errors occur, the result will
be: @code{abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)}.

`rel_tol' is the relative tolerance -- it is the maximum allowed difference
between `a' and `b', relative to the larger absolute value of `a' or `b'.
For example, to set a tolerance of 5%, pass @code{rel_tol=0.05}.  The default
tolerance is @code{1e-09}, which assures that the two values are the same
within about 9 decimal digits.  `rel_tol' must be nonnegative and less
than @code{1.0}.

`abs_tol' is the absolute tolerance; it defaults to @code{0.0} and it must be
nonnegative.  When comparing @code{x} to @code{0.0}, @code{isclose(x, 0)} is computed
as @code{abs(x) <= rel_tol  * abs(x)}, which is @code{False} for any @code{x} and
rel_tol less than @code{1.0}.  So add an appropriate positive abs_tol argument
to the call.

Les valeurs spécifiques suivantes : @code{NaN}, @code{inf}, et @code{-inf} définies dans la norme IEEE 754  seront manipulées selon les règles du standard IEEE. En particulier, @code{NaN} n'est considéré proche d'aucune autre valeur, @code{NaN} inclus. @code{inf} et @code{-inf} ne sont considérées proches que d'elles-mêmes.


Ajouté dans la version 3.5.



@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} — Une fonction pour tester des quasi-égalités

@end deffn

@geindex isfinite() (dans le module math)
@anchor{library/math math isfinite}@anchor{11c8}
@deffn {Fonction} math.isfinite (x)

Renvoie @code{True} si `n' n'est ni infini, ni NaN, et @code{False} sinon. (Notez que @code{0.0} `est' considéré comme fini.)


Ajouté dans la version 3.2.

@end deffn

@geindex isinf() (dans le module math)
@anchor{library/math math isinf}@anchor{1388}
@deffn {Fonction} math.isinf (x)

Renvoie @code{True} si `x' vaut l'infini positif ou négatif, et @code{False} sinon.
@end deffn

@geindex isnan() (dans le module math)
@anchor{library/math math isnan}@anchor{1389}
@deffn {Fonction} math.isnan (x)

Renvoie @code{True} si `x' est NaN (`Not a Number', ou `Pas un Nombre' en français), et @code{False} sinon.
@end deffn

@geindex ldexp() (dans le module math)
@anchor{library/math math ldexp}@anchor{2583}
@deffn {Fonction} math.ldexp (x, i)

Renvoie @code{x * (2**i)}. C'est essentiellement l'inverse de la fonction @ref{2582,,frexp()}.
@end deffn

@geindex nextafter() (dans le module math)
@anchor{library/math math nextafter}@anchor{482}
@deffn {Fonction} math.nextafter (x, y, steps=1)

Return the floating-point value `steps' steps after `x' towards `y'.

If `x' is equal to `y', return `y', unless `steps' is zero.

Exemples :


@itemize *

@item 
@code{math.nextafter(x, math.inf)} augmente de valeur : vers l'infini positif.

@item 
@code{math.nextafter(x, -math.inf)} baisse de valeur : vers l'infini négatif.

@item 
@code{math.nextafter(x, 0.0)} augmente ou baisse de valeur, vers zéro.

@item 
@code{math.nextafter(x, math.copysign(math.inf, x))} augmente ou baisse de valeur, en s'éloignant de zéro.
@end itemize

Voir aussi : @ref{8ff,,math.ulp()}.


Ajouté dans la version 3.9.



Modifié dans la version 3.12: Added the `steps' argument.

@end deffn

@geindex ulp() (dans le module math)
@anchor{library/math math ulp}@anchor{8ff}
@deffn {Fonction} math.ulp (x)

Return the value of the least significant bit of the float `x':


@itemize *

@item 
If `x' is a NaN (not a number), return `x'.

@item 
If `x' is negative, return @code{ulp(-x)}.

@item 
If `x' is a positive infinity, return `x'.

@item 
If `x' is equal to zero, return the smallest positive
`denormalized' representable float (smaller than the minimum positive
`normalized' float, @ref{1979,,sys.float_info.min}).

@item 
If `x' is equal to the largest positive representable float,
return the value of the least significant bit of `x', such that the first
float smaller than `x' is @code{x - ulp(x)}.

@item 
Otherwise (`x' is a positive finite number), return the value of the least
significant bit of `x', such that the first float bigger than `x'
is @code{x + ulp(x)}.
@end itemize

ULP stands for "Unit in the Last Place".

See also @ref{482,,math.nextafter()} and @ref{1979,,sys.float_info.epsilon}.


Ajouté dans la version 3.9.

@end deffn

@node Power exponential and logarithmic functions,Summation and product functions,Floating point manipulation functions,math --- Mathematical functions
@anchor{library/math power-exponential-and-logarithmic-functions}@anchor{2595}
@subsubsection Power, exponential and logarithmic functions


@geindex cbrt() (dans le module math)
@anchor{library/math math cbrt}@anchor{64c}
@deffn {Fonction} math.cbrt (x)

Return the cube root of `x'.


Ajouté dans la version 3.11.

@end deffn

@geindex exp() (dans le module math)
@anchor{library/math math exp}@anchor{12f2}
@deffn {Fonction} math.exp (x)

Renvoie `e' à la puissance `x', où `e' = 2.718281… est la base des logarithmes naturels. Cela est en général plus précis que @code{math.e ** x} ou @code{pow(math.e, x)}.
@end deffn

@geindex exp2() (dans le module math)
@anchor{library/math math exp2}@anchor{64b}
@deffn {Fonction} math.exp2 (x)

Return `2' raised to the power `x'.


Ajouté dans la version 3.11.

@end deffn

@geindex expm1() (dans le module math)
@anchor{library/math math expm1}@anchor{11c9}
@deffn {Fonction} math.expm1 (x)

Return `e' raised to the power `x', minus 1.  Here `e' is the base of natural
logarithms.  For small floats `x', the subtraction in @code{exp(x) - 1}
can result in a significant loss of precision@footnote{https://en.wikipedia.org/wiki/Loss_of_significance}; the @ref{11c9,,expm1()}
function provides a way to compute this quantity to full precision:

@example
>>> from math import exp, expm1
>>> exp(1e-5) - 1  # gives result accurate to 11 places
1.0000050000069649e-05
>>> expm1(1e-5)    # result accurate to full precision
1.0000050000166668e-05
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex log() (dans le module math)
@anchor{library/math math log}@anchor{1474}
@deffn {Fonction} math.log (x[, base])

Avec un argument, renvoie le logarithme naturel de `x' (en base `e').

Avec deux arguments, renvoie le logarithme de `x' en la `base' donnée, calculé par @code{log(x)/log(base)}.
@end deffn

@geindex log1p() (dans le module math)
@anchor{library/math math log1p}@anchor{138f}
@deffn {Fonction} math.log1p (x)

Renvoie le logarithme naturel de `1+x' (en base `e'). Le résultat est calculé par un moyen qui reste exact pour `x' proche de zéro.
@end deffn

@geindex log2() (dans le module math)
@anchor{library/math math log2}@anchor{10bd}
@deffn {Fonction} math.log2 (x)

Renvoie le logarithme en base 2 de `x'. C'est en général plus précis que @code{log(x, 2)}.


Ajouté dans la version 3.3.



@subsubheading Voir aussi


@ref{2123,,int.bit_length()} renvoie le nombre de bits nécessaires pour représenter un entier en binaire, en excluant le signe et les zéros de début.

@end deffn

@geindex log10() (dans le module math)
@anchor{library/math math log10}@anchor{2584}
@deffn {Fonction} math.log10 (x)

Renvoie le logarithme de `x' en base 10. C'est habituellement plus exact que @code{log(x, 10)}.
@end deffn

@geindex pow() (dans le module math)
@anchor{library/math math pow}@anchor{64d}
@deffn {Fonction} math.pow (x, y)

Return `x' raised to the power `y'.  Exceptional cases follow
the IEEE 754 standard as far as possible.  In particular,
@code{pow(1.0, x)} and @code{pow(x, 0.0)} always return @code{1.0}, even
when `x' is a zero or a NaN.  If both `x' and `y' are finite,
`x' is negative, and `y' is not an integer then @code{pow(x, y)}
is undefined, and raises @ref{1ff,,ValueError}.

À l'inverse de l'opérateur interne @code{**}, la fonction @ref{64d,,math.pow()} convertit ses deux arguments en @ref{2eb,,float}. Utilisez @code{**} ou la primitive @ref{9c0,,pow()} pour calculer des puissances exactes d'entiers.


Modifié dans la version 3.11: The special cases @code{pow(0.0, -inf)} and @code{pow(-0.0, -inf)} were
changed to return @code{inf} instead of raising @ref{1ff,,ValueError},
for consistency with IEEE 754.

@end deffn

@geindex sqrt() (dans le module math)
@anchor{library/math math sqrt}@anchor{9f4}
@deffn {Fonction} math.sqrt (x)

Renvoie la racine carrée de `x'.
@end deffn

@node Summation and product functions,Conversion angulaire,Power exponential and logarithmic functions,math --- Mathematical functions
@anchor{library/math summation-and-product-functions}@anchor{2596}
@subsubsection Summation and product functions


@geindex dist() (dans le module math)
@anchor{library/math math dist}@anchor{9f0}
@deffn {Fonction} math.dist (p, q)

Renvoie la distance Euclienne entre deux points `p' et `q', passés comme des séquences (ou des itérables) de coordonnées. Les deux points doivent avoir la même dimension.

À peu près équivalent à :

@example
sqrt(sum((px - qx) ** 2.0 for px, qx in zip(p, q)))
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex fsum() (dans le module math)
@anchor{library/math math fsum}@anchor{138b}
@deffn {Fonction} math.fsum (iterable)

Return an accurate floating-point sum of values in the iterable.  Avoids
loss of precision by tracking multiple intermediate partial sums.

La précision de cet algorithme dépend des garanties arithmétiques de IEEE-754 et des cas standards où le mode d'arrondi est `half-even'. Sur certaines versions non Windows, la bibliothèque C sous-jacente utilise une addition par précision étendue et peut occasionnellement effectuer un double-arrondi sur une somme intermédiaire causant la prise d'une mauvaise valeur du bit de poids faible.

For further discussion and two alternative approaches, see the ASPN cookbook recipes for accurate floating-point summation@footnote{https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/}.
@end deffn

@geindex hypot() (dans le module math)
@anchor{library/math math hypot}@anchor{9f1}
@deffn {Fonction} math.hypot (*coordinates)

Renvoie la norme Euclidienne, @code{sqrt(sum(x**2 for x in coordinates))}. C'est la norme du vecteur entre l'origine et le point donné par les coordonnées.

Pour un point bi-dimensionnel @code{(x, y)}, c'est équivalent à calculer la valeur de l’hypoténuse d'un triangle rectangle en utilisant le théorème de Pythagore, @code{sqrt(x*x + y*y)}.


Modifié dans la version 3.8: Ajout de la gestion des points à n-dimensions. Auparavant seuls les points bi-dimensionnels étaient gérés.



Modifié dans la version 3.10: Improved the algorithm's accuracy so that the maximum error is
under 1 ulp (unit in the last place).  More typically, the result
is almost always correctly rounded to within 1/2 ulp.

@end deffn

@geindex prod() (dans le module math)
@anchor{library/math math prod}@anchor{9f2}
@deffn {Fonction} math.prod (iterable, *, start=1)

Calcule le produit de tous les éléments passés dans l'entrée `iterable'. La valeur de `départ' par défaut du produit vaut @code{1}.

Quand l'itérable est vide, renvoie la valeur de départ. Cette fonction ne doit être utilisée qu'avec des valeurs numériques et peut rejeter les types non-numériques.


Ajouté dans la version 3.8.

@end deffn

@geindex sumprod() (dans le module math)
@anchor{library/math math sumprod}@anchor{481}
@deffn {Fonction} math.sumprod (p, q)

Return the sum of products of values from two iterables `p' and `q'.

Raises @ref{1ff,,ValueError} if the inputs do not have the same length.

À peu près équivalent à :

@example
sum(itertools.starmap(operator.mul, zip(p, q, strict=True)))
@end example

For float and mixed int/float inputs, the intermediate products
and sums are computed with extended precision.


Ajouté dans la version 3.12.

@end deffn

@node Conversion angulaire,Fonctions trigonométriques,Summation and product functions,math --- Mathematical functions
@anchor{library/math angular-conversion}@anchor{2597}
@subsubsection Conversion angulaire


@geindex degrees() (dans le module math)
@anchor{library/math math degrees}@anchor{2585}
@deffn {Fonction} math.degrees (x)

Convertit l'angle `x' de radians en degrés.
@end deffn

@geindex radians() (dans le module math)
@anchor{library/math math radians}@anchor{2586}
@deffn {Fonction} math.radians (x)

Convertit l'ange `x' de degrés en radians.
@end deffn

@node Fonctions trigonométriques,Fonctions hyperboliques,Conversion angulaire,math --- Mathematical functions
@anchor{library/math trigonometric-functions}@anchor{2598}
@subsubsection Fonctions trigonométriques


@geindex acos() (dans le module math)
@anchor{library/math math acos}@anchor{2587}
@deffn {Fonction} math.acos (x)

Return the arc cosine of `x', in radians. The result is between @code{0} and
@code{pi}.
@end deffn

@geindex asin() (dans le module math)
@anchor{library/math math asin}@anchor{2588}
@deffn {Fonction} math.asin (x)

Return the arc sine of `x', in radians. The result is between @code{-pi/2} and
@code{pi/2}.
@end deffn

@geindex atan() (dans le module math)
@anchor{library/math math atan}@anchor{2589}
@deffn {Fonction} math.atan (x)

Return the arc tangent of `x', in radians. The result is between @code{-pi/2} and
@code{pi/2}.
@end deffn

@geindex atan2() (dans le module math)
@anchor{library/math math atan2}@anchor{258a}
@deffn {Fonction} math.atan2 (y, x)

Renvoie @code{atan(y / x)}, en radians. Le résultat est entre @code{-pi} et @code{pi}. Le vecteur du plan allant de l'origine vers le point @code{(x, y)} forme cet angle avec l'axe X positif. L'intérêt de @ref{258a,,atan2()} est que le signe des deux entrées est connu. Donc elle peut calculer le bon quadrant pour l'angle. par exemple @code{atan(1)} et @code{atan2(1, 1)} donnent tous deux @code{pi/4}, mais @code{atan2(-1, -1)} donne @code{-3*pi/4}.
@end deffn

@geindex cos() (dans le module math)
@anchor{library/math math cos}@anchor{1473}
@deffn {Fonction} math.cos (x)

Renvoie le cosinus de `x' radians.
@end deffn

@geindex sin() (dans le module math)
@anchor{library/math math sin}@anchor{1472}
@deffn {Fonction} math.sin (x)

Renvoie le sinus de `x' radians.
@end deffn

@geindex tan() (dans le module math)
@anchor{library/math math tan}@anchor{258b}
@deffn {Fonction} math.tan (x)

Renvoie la tangente de `x' radians.
@end deffn

@node Fonctions hyperboliques,Fonctions spéciales,Fonctions trigonométriques,math --- Mathematical functions
@anchor{library/math hyperbolic-functions}@anchor{2599}
@subsubsection Fonctions hyperboliques


Hyperbolic functions@footnote{https://en.wikipedia.org/wiki/Hyperbolic_functions}
are analogs of trigonometric functions that are based on hyperbolas
instead of circles.

@geindex acosh() (dans le module math)
@anchor{library/math math acosh}@anchor{138c}
@deffn {Fonction} math.acosh (x)

Renvoie l'arc cosinus hyperbolique de `x'.
@end deffn

@geindex asinh() (dans le module math)
@anchor{library/math math asinh}@anchor{138d}
@deffn {Fonction} math.asinh (x)

Renvoie l'arc sinus hyperbolique de `x'.
@end deffn

@geindex atanh() (dans le module math)
@anchor{library/math math atanh}@anchor{138e}
@deffn {Fonction} math.atanh (x)

Renvoie l'arc tangente hyperbolique de `x'.
@end deffn

@geindex cosh() (dans le module math)
@anchor{library/math math cosh}@anchor{258c}
@deffn {Fonction} math.cosh (x)

Renvoie le cosinus hyperbolique de `x'.
@end deffn

@geindex sinh() (dans le module math)
@anchor{library/math math sinh}@anchor{258d}
@deffn {Fonction} math.sinh (x)

Renvoie le sinus hyperbolique de `x'.
@end deffn

@geindex tanh() (dans le module math)
@anchor{library/math math tanh}@anchor{258e}
@deffn {Fonction} math.tanh (x)

Renvoie la tangente hyperbolique de `x'.
@end deffn

@node Fonctions spéciales,Constantes<2>,Fonctions hyperboliques,math --- Mathematical functions
@anchor{library/math special-functions}@anchor{259a}
@subsubsection Fonctions spéciales


@geindex erf() (dans le module math)
@anchor{library/math math erf}@anchor{bc6}
@deffn {Fonction} math.erf (x)

Renvoie la fonction d'erreur@footnote{https://en.wikipedia.org/wiki/Error_function} en `x'.

The @ref{bc6,,erf()} function can be used to compute traditional statistical
functions such as the cumulative standard normal distribution@footnote{https://en.wikipedia.org/wiki/Cumulative_distribution_function}:

@example
def phi(x):
    'Cumulative distribution function for the standard normal distribution'
    return (1.0 + erf(x / sqrt(2.0))) / 2.0
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex erfc() (dans le module math)
@anchor{library/math math erfc}@anchor{bc7}
@deffn {Fonction} math.erfc (x)

Renvoie la fonction d'erreur complémentaire en `x'. La fonction d'erreur complémentaire@footnote{https://fr.wikipedia.org/wiki/Fonction_d'erreur} est définie par @code{1.0 - erf(x)}. Elle est utilisée pour les grandes valeurs de `x', où la soustraction en partant de 1,0 entraînerait une perte de précision@footnote{https://en.wikipedia.org/wiki/Loss_of_significance}.


Ajouté dans la version 3.2.

@end deffn

@geindex gamma() (dans le module math)
@anchor{library/math math gamma}@anchor{11ca}
@deffn {Fonction} math.gamma (x)

Renvoie la fonction Gamma@footnote{https://fr.wikipedia.org/wiki/Fonction_gamma} en `x'.


Ajouté dans la version 3.2.

@end deffn

@geindex lgamma() (dans le module math)
@anchor{library/math math lgamma}@anchor{11cb}
@deffn {Fonction} math.lgamma (x)

Renvoie le logarithme naturel de la valeur absolue de la fonction gamma en `x'.


Ajouté dans la version 3.2.

@end deffn

@node Constantes<2>,,Fonctions spéciales,math --- Mathematical functions
@anchor{library/math constants}@anchor{259b}
@subsubsection Constantes


@geindex pi (dans le module math)
@anchor{library/math math pi}@anchor{258f}
@deffn {Données} math.pi

La constante mathématique `π' = 3.141592…, à la précision disponible.
@end deffn

@geindex e (dans le module math)
@anchor{library/math math e}@anchor{2590}
@deffn {Données} math.e

La constante mathématique `e' = 2.718281…, à la précision disponible.
@end deffn

@geindex tau (dans le module math)
@anchor{library/math math tau}@anchor{2591}
@deffn {Données} math.tau

La constante mathématique `τ' = 6.283185…, à la précision disponible. Tau est une constante du cercle égale à 2 *π*, le rapport de la circonférence d'un cercle à son rayon. Pour en apprendre plus sur Tau, regardez la vidéo de Vi Hart, Pi is (still) Wrong@footnote{https://www.youtube.com/watch?v=jG7vhMMXagQ}, et profitez-en pour célébrer le Jour de Tau@footnote{https://tauday.com/} en bavardant comme deux pies !


Ajouté dans la version 3.6.

@end deffn

@geindex inf (dans le module math)
@anchor{library/math math inf}@anchor{c72}
@deffn {Données} math.inf

Un flottant positif infini. (Pour un infini négatif, utilisez @code{-math.inf}.) Équivalent au résultat de @code{float('inf')}.


Ajouté dans la version 3.5.

@end deffn

@geindex nan (dans le module math)
@anchor{library/math math nan}@anchor{64e}
@deffn {Données} math.nan

A floating-point "not a number" (NaN) value. Equivalent to the output of
@code{float('nan')}. Due to the requirements of the IEEE-754 standard@footnote{https://en.wikipedia.org/wiki/IEEE_754}, @code{math.nan} and @code{float('nan')} are
not considered to equal to any other numeric value, including themselves. To check
whether a number is a NaN, use the @ref{1389,,isnan()} function to test
for NaNs instead of @code{is} or @code{==}.
Example:

@example
>>> import math
>>> math.nan == math.nan
False
>>> float('nan') == float('nan')
False
>>> math.isnan(math.nan)
True
>>> math.isnan(float('nan'))
True
@end example


Ajouté dans la version 3.5.



Modifié dans la version 3.11: It is now always available.

@end deffn

`Particularité de l'implémentation CPython :' Le module @ref{8d,,math} consiste majoritairement en un conteneur pour les fonctions mathématiques de la bibliothèque C de la plate-forme. Le comportement dans les cas spéciaux suit l'annexe 'F' du standard C99 quand c'est approprié. L'implémentation actuelle lève une @ref{1ff,,ValueError} pour les opérations invalides telles que @code{sqrt(-1.0)} ou @code{log(0.0)} (où le standard C99 recommande de signaler que l'opération est invalide ou qu'il y a division par zéro), et une @ref{86d,,OverflowError} pour les résultats qui débordent (par exemple @code{exp(1000.0)}). `NaN' ne sera renvoyé pour aucune des fonctions ci-dessus, sauf si au moins un des arguments de la fonction vaut `NaN'. Dans ce cas, la plupart des fonctions renvoient `NaN', mais (à nouveau, selon l'annexe 'F' du standard C99) il y a quelques exceptions à cette règle, par exemple @code{pow(float('nan'), 0.0)} ou @code{hypot(float('nan'), float('inf'))}.

Notez que Python ne fait aucun effort pour distinguer les NaNs signalétiques des NaNs silencieux, et le comportement de signalement des NaNs reste non-spécifié. Le comportement standard est de traiter tous les NaNs comme s'ils étaient silencieux.


@subsubheading Voir aussi



@table @asis

@item Module @ref{18,,cmath}

Version complexe de beaucoup de ces fonctions.
@end table


@node cmath --- Mathematical functions for complex numbers,decimal --- Decimal fixed-point and floating-point arithmetic,math --- Mathematical functions,Modules numériques et mathématiques
@anchor{library/cmath doc}@anchor{259c}@anchor{library/cmath cmath-mathematical-functions-for-complex-numbers}@anchor{259d}@anchor{library/cmath module-cmath}@anchor{18}
@subsection @code{cmath} --- Mathematical functions for complex numbers


@geindex module; cmath


__________________________________________________________________


This module provides access to mathematical functions for complex numbers.  The
functions in this module accept integers, floating-point numbers or complex
numbers as arguments. They will also accept any Python object that has either a
@ref{5d1,,__complex__()} or a @ref{9ba,,__float__()} method: these methods are used to
convert the object to a complex or floating-point number, respectively, and
the function is then applied to the result of the conversion.

@cartouche
@quotation Note 
For functions involving branch cuts, we have the problem of deciding how to
define those functions on the cut itself. Following Kahan's "Branch cuts for
complex elementary functions" paper, as well as Annex G of C99 and later C
standards, we use the sign of zero to distinguish one side of the branch cut
from the other: for a branch cut along (a portion of) the real axis we look
at the sign of the imaginary part, while for a branch cut along the
imaginary axis we look at the sign of the real part.

For example, the @ref{259e,,cmath.sqrt()} function has a branch cut along the
negative real axis. An argument of @code{complex(-2.0, -0.0)} is treated as
though it lies `below' the branch cut, and so gives a result on the negative
imaginary axis:

@example
>>> cmath.sqrt(complex(-2.0, -0.0))
-1.4142135623730951j
@end example

But an argument of @code{complex(-2.0, 0.0)} is treated as though it lies above
the branch cut:

@example
>>> cmath.sqrt(complex(-2.0, 0.0))
1.4142135623730951j
@end example
@end quotation
@end cartouche

@menu
* Conversion vers et à partir de coordonnées polaires:: 
* Fonctions logarithme et exponentielle:: 
* Fonctions trigonométriques: Fonctions trigonométriques<2>. 
* Fonctions hyperboliques: Fonctions hyperboliques<2>. 
* Fonctions de classifications:: 
* Constantes: Constantes<3>. 

@end menu

@node Conversion vers et à partir de coordonnées polaires,Fonctions logarithme et exponentielle,,cmath --- Mathematical functions for complex numbers
@anchor{library/cmath conversions-to-and-from-polar-coordinates}@anchor{259f}
@subsubsection Conversion vers et à partir de coordonnées polaires


A Python complex number @code{z} is stored internally using `rectangular'
or `Cartesian' coordinates.  It is completely determined by its `real
part' @code{z.real} and its `imaginary part' @code{z.imag}.

Les `coordonnées polaires' donnent une manière alternative de représenter un nombre complexe. En coordonnées polaires, un nombre complexe `z' est défini par son module `r' et par son argument (`angle de phase') `phi'. Le module `r' est la distance entre `z' et l'origine, alors que l'argument `phi' est l'angle (dans le sens inverse des aiguilles d'une montre, ou sens trigonométrique), mesuré en radians, à partir de l'axe X positif, et vers le segment de droite joignant `z' à l'origine.

Les fonctions suivantes peuvent être utilisées pour convertir à partir des coordonnées rectangulaires natives vers les coordonnées polaires, et vice-versa.

@geindex phase() (dans le module cmath)
@anchor{library/cmath cmath phase}@anchor{25a0}
@deffn {Fonction} cmath.phase (x)

Return the phase of `x' (also known as the `argument' of `x'), as a float.
@code{phase(x)} is equivalent to @code{math.atan2(x.imag, x.real)}.  The result
lies in the range [-`π', `π'], and the branch cut for this operation lies
along the negative real axis.  The sign of the result is the same as the
sign of @code{x.imag}, even when @code{x.imag} is zero:

@example
>>> phase(complex(-1.0, 0.0))
3.141592653589793
>>> phase(complex(-1.0, -0.0))
-3.141592653589793
@end example
@end deffn

@cartouche
@quotation Note 
Le module (valeur absolue) d'un nombre complexe `x' peut être calculé en utilisant la primitive @ref{1c32,,abs()}. Il n'y a pas de fonction spéciale du module @ref{18,,cmath} pour cette opération.
@end quotation
@end cartouche

@geindex polar() (dans le module cmath)
@anchor{library/cmath cmath polar}@anchor{25a1}
@deffn {Fonction} cmath.polar (x)

Renvoie la représentation de `x' en coordonnées polaires. Renvoie une paire @code{(r, phi)} où `r' est le module de `x' et phi est l'argument de `x'. @code{polar(x)} est équivalent à @code{(abs(x), phase(x))}.
@end deffn

@geindex rect() (dans le module cmath)
@anchor{library/cmath cmath rect}@anchor{25a2}
@deffn {Fonction} cmath.rect (r, phi)

Return the complex number `x' with polar coordinates `r' and `phi'.
Equivalent to @code{complex(r * math.cos(phi), r * math.sin(phi))}.
@end deffn

@node Fonctions logarithme et exponentielle,Fonctions trigonométriques<2>,Conversion vers et à partir de coordonnées polaires,cmath --- Mathematical functions for complex numbers
@anchor{library/cmath power-and-logarithmic-functions}@anchor{25a3}
@subsubsection Fonctions logarithme et exponentielle


@geindex exp() (dans le module cmath)
@anchor{library/cmath cmath exp}@anchor{25a4}
@deffn {Fonction} cmath.exp (x)

Renvoie `e' élevé à la puissance `x', où `e' est la base des logarithmes naturels.
@end deffn

@geindex log() (dans le module cmath)
@anchor{library/cmath cmath log}@anchor{25a5}
@deffn {Fonction} cmath.log (x[, base])

Returns the logarithm of `x' to the given `base'. If the `base' is not
specified, returns the natural logarithm of `x'. There is one branch cut,
from 0 along the negative real axis to -∞.
@end deffn

@geindex log10() (dans le module cmath)
@anchor{library/cmath cmath log10}@anchor{25a6}
@deffn {Fonction} cmath.log10 (x)

Renvoie le logarithme en base 10 de `x'. Elle a la même coupure que @ref{25a5,,log()}.
@end deffn

@geindex sqrt() (dans le module cmath)
@anchor{library/cmath cmath sqrt}@anchor{259e}
@deffn {Fonction} cmath.sqrt (x)

Renvoie la racine carrée de `x'. Elle a la même coupure que @ref{25a5,,log()}.
@end deffn

@node Fonctions trigonométriques<2>,Fonctions hyperboliques<2>,Fonctions logarithme et exponentielle,cmath --- Mathematical functions for complex numbers
@anchor{library/cmath trigonometric-functions}@anchor{25a7}
@subsubsection Fonctions trigonométriques


@geindex acos() (dans le module cmath)
@anchor{library/cmath cmath acos}@anchor{25a8}
@deffn {Fonction} cmath.acos (x)

Return the arc cosine of `x'. There are two branch cuts: One extends right
from 1 along the real axis to ∞. The other extends left from -1 along the
real axis to -∞.
@end deffn

@geindex asin() (dans le module cmath)
@anchor{library/cmath cmath asin}@anchor{25a9}
@deffn {Fonction} cmath.asin (x)

Renvoie l'arc sinus de `x'. Elle a les mêmes coupures que @ref{25a8,,acos()}.
@end deffn

@geindex atan() (dans le module cmath)
@anchor{library/cmath cmath atan}@anchor{25aa}
@deffn {Fonction} cmath.atan (x)

Return the arc tangent of `x'. There are two branch cuts: One extends from
@code{1j} along the imaginary axis to @code{∞j}. The other extends from @code{-1j}
along the imaginary axis to @code{-∞j}.
@end deffn

@geindex cos() (dans le module cmath)
@anchor{library/cmath cmath cos}@anchor{25ab}
@deffn {Fonction} cmath.cos (x)

Renvoie le cosinus de `x'.
@end deffn

@geindex sin() (dans le module cmath)
@anchor{library/cmath cmath sin}@anchor{25ac}
@deffn {Fonction} cmath.sin (x)

Renvoie le sinus de `x'.
@end deffn

@geindex tan() (dans le module cmath)
@anchor{library/cmath cmath tan}@anchor{25ad}
@deffn {Fonction} cmath.tan (x)

Renvoie la tangente de `x'.
@end deffn

@node Fonctions hyperboliques<2>,Fonctions de classifications,Fonctions trigonométriques<2>,cmath --- Mathematical functions for complex numbers
@anchor{library/cmath hyperbolic-functions}@anchor{25ae}
@subsubsection Fonctions hyperboliques


@geindex acosh() (dans le module cmath)
@anchor{library/cmath cmath acosh}@anchor{25af}
@deffn {Fonction} cmath.acosh (x)

Return the inverse hyperbolic cosine of `x'. There is one branch cut,
extending left from 1 along the real axis to -∞.
@end deffn

@geindex asinh() (dans le module cmath)
@anchor{library/cmath cmath asinh}@anchor{25b0}
@deffn {Fonction} cmath.asinh (x)

Return the inverse hyperbolic sine of `x'. There are two branch cuts:
One extends from @code{1j} along the imaginary axis to @code{∞j}.  The other
extends from @code{-1j} along the imaginary axis to @code{-∞j}.
@end deffn

@geindex atanh() (dans le module cmath)
@anchor{library/cmath cmath atanh}@anchor{25b1}
@deffn {Fonction} cmath.atanh (x)

Return the inverse hyperbolic tangent of `x'. There are two branch cuts: One
extends from @code{1} along the real axis to @code{∞}. The other extends from
@code{-1} along the real axis to @code{-∞}.
@end deffn

@geindex cosh() (dans le module cmath)
@anchor{library/cmath cmath cosh}@anchor{25b2}
@deffn {Fonction} cmath.cosh (x)

Renvoie le cosinus hyperbolique de `x'.
@end deffn

@geindex sinh() (dans le module cmath)
@anchor{library/cmath cmath sinh}@anchor{25b3}
@deffn {Fonction} cmath.sinh (x)

Renvoie le sinus hyperbolique de `x'.
@end deffn

@geindex tanh() (dans le module cmath)
@anchor{library/cmath cmath tanh}@anchor{25b4}
@deffn {Fonction} cmath.tanh (x)

Renvoie la tangente hyperbolique de `x'.
@end deffn

@node Fonctions de classifications,Constantes<3>,Fonctions hyperboliques<2>,cmath --- Mathematical functions for complex numbers
@anchor{library/cmath classification-functions}@anchor{25b5}
@subsubsection Fonctions de classifications


@geindex isfinite() (dans le module cmath)
@anchor{library/cmath cmath isfinite}@anchor{25b6}
@deffn {Fonction} cmath.isfinite (x)

Renvoie @code{True} si la partie réelle `et' la partie imaginaire de `x' sont finies, et @code{False} sinon.


Ajouté dans la version 3.2.

@end deffn

@geindex isinf() (dans le module cmath)
@anchor{library/cmath cmath isinf}@anchor{25b7}
@deffn {Fonction} cmath.isinf (x)

Renvoie @code{True} si soit la partie réelle `ou' la partie imaginaire de `x' est infinie, et @code{False} sinon.
@end deffn

@geindex isnan() (dans le module cmath)
@anchor{library/cmath cmath isnan}@anchor{25b8}
@deffn {Fonction} cmath.isnan (x)

Renvoie @code{True} si soit la partie réelle `ou' la partie imaginaire de `x' est NaN, et @code{False} sinon.
@end deffn

@geindex isclose() (dans le module cmath)
@anchor{library/cmath cmath isclose}@anchor{d9e}
@deffn {Fonction} cmath.isclose (a, b, *, rel_tol=1e-09, abs_tol=0.0)

Renvoie @code{True} si les valeurs `a' et `b' sont proches l'une de l'autre, et @code{False} sinon.

Whether or not two values are considered close is determined according to
given absolute and relative tolerances.  If no errors occur, the result will
be: @code{abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)}.

`rel_tol' is the relative tolerance -- it is the maximum allowed difference
between `a' and `b', relative to the larger absolute value of `a' or `b'.
For example, to set a tolerance of 5%, pass @code{rel_tol=0.05}.  The default
tolerance is @code{1e-09}, which assures that the two values are the same
within about 9 decimal digits.  `rel_tol' must be nonnegative and less
than @code{1.0}.

`abs_tol' is the absolute tolerance; it defaults to @code{0.0} and it must be
nonnegative.  When comparing @code{x} to @code{0.0}, @code{isclose(x, 0)} is computed
as @code{abs(x) <= rel_tol  * abs(x)}, which is @code{False} for any @code{x} and
rel_tol less than @code{1.0}.  So add an appropriate positive abs_tol argument
to the call.

Les valeurs spécifiques suivantes : @code{NaN}, @code{inf}, et @code{-inf} définies dans la norme IEEE 754  seront manipulées selon les règles du standard IEEE. En particulier, @code{NaN} n'est considéré proche d'aucune autre valeur, @code{NaN} inclus. @code{inf} et @code{-inf} ne sont considérés proches que d'eux-mêmes.


Ajouté dans la version 3.5.



@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 485
PEP 485@footnote{https://peps.python.org/pep-0485/} -- Une fonction pour tester des égalités approximées

@end deffn

@node Constantes<3>,,Fonctions de classifications,cmath --- Mathematical functions for complex numbers
@anchor{library/cmath constants}@anchor{25b9}
@subsubsection Constantes


@geindex pi (dans le module cmath)
@anchor{library/cmath cmath pi}@anchor{25ba}
@deffn {Données} cmath.pi

La constante mathématique `π', en tant que flottant.
@end deffn

@geindex e (dans le module cmath)
@anchor{library/cmath cmath e}@anchor{25bb}
@deffn {Données} cmath.e

La constante mathématique `e', en tant que flottant.
@end deffn

@geindex tau (dans le module cmath)
@anchor{library/cmath cmath tau}@anchor{c6f}
@deffn {Données} cmath.tau

La constante mathématique `τ', sous forme de flottant.


Ajouté dans la version 3.6.

@end deffn

@geindex inf (dans le module cmath)
@anchor{library/cmath cmath inf}@anchor{c70}
@deffn {Données} cmath.inf

Nombre à virgule flottante positif infini. Équivaut à @code{float('inf')}.


Ajouté dans la version 3.6.

@end deffn

@geindex infj (dans le module cmath)
@anchor{library/cmath cmath infj}@anchor{c73}
@deffn {Données} cmath.infj

Nombre complexe dont la partie réelle vaut zéro et la partie imaginaire un infini positif. Équivalent à @code{complex(0.0, float('inf'))}.


Ajouté dans la version 3.6.

@end deffn

@geindex nan (dans le module cmath)
@anchor{library/cmath cmath nan}@anchor{c71}
@deffn {Données} cmath.nan

Un nombre à virgule flottante `NaN' (`Not a number'). Équivalent à @code{float('nan')}.


Ajouté dans la version 3.6.

@end deffn

@geindex nanj (dans le module cmath)
@anchor{library/cmath cmath nanj}@anchor{c74}
@deffn {Données} cmath.nanj

Nombre complexe dont la partie réelle vaut zéro et la partie imaginaire vaut un `NaN'. Équivalent à @code{complex(0.0, float('nan'))}.


Ajouté dans la version 3.6.

@end deffn

@geindex module;math

Notez que la sélection de fonctions est similaire, mais pas identique, à celles du module @ref{8d,,math}. La raison d'avoir deux modules est que certains utilisateurs ne sont pas intéressés par les nombres complexes, et peut-être ne savent même pas ce qu'ils sont. Ils préféreraient alors que @code{math.sqrt(-1)} lève une exception au lieu de renvoyer un nombre complexe. Également, notez que les fonctions définies dans @ref{18,,cmath} renvoient toujours un nombre complexe, même si le résultat peut être exprimé à l'aide d'un nombre réel (en quel cas la partie imaginaire du complexe vaut zéro).

Une note sur les `coupures' : ce sont des courbes sur lesquelles la fonction n'est pas continue. Ce sont des caractéristiques nécessaires de beaucoup de fonctions complexes. Il est supposé que si vous avez besoin d'utiliser des fonctions complexes, vous comprendrez ce que sont les coupures. Consultez n'importe quel livre (pas trop élémentaire) sur les variables complexes pour plus d'informations. Pour des informations sur les choix des coupures à des fins numériques, voici une bonne référence :


@subsubheading Voir aussi


Kahan, W:  Branch cuts for complex elementary functions; or, Much ado about
nothing's sign bit.  In Iserles, A., and Powell, M. (eds.), The state of the art
in numerical analysis. Clarendon Press (1987) pp165--211.


@node decimal --- Decimal fixed-point and floating-point arithmetic,fractions --- Rational numbers,cmath --- Mathematical functions for complex numbers,Modules numériques et mathématiques
@anchor{library/decimal doc}@anchor{25bc}@anchor{library/decimal decimal-decimal-fixed-point-and-floating-point-arithmetic}@anchor{25bd}@anchor{library/decimal module-decimal}@anchor{36}
@subsection @code{decimal} --- Decimal fixed-point and floating-point arithmetic


@geindex module; decimal

`Code source :' Lib/decimal.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/decimal.py}

@c import modules for testing inline doctests with the Sphinx doctest builder

@c import decimal
@c import math
@c from decimal import *
@c # make sure each group gets a fresh context
@c setcontext(Context())

@c # make sure other tests (outside this file) get a fresh context
@c setcontext(Context())


__________________________________________________________________


The @ref{36,,decimal} module provides support for fast correctly rounded
decimal floating-point arithmetic. It offers several advantages over the
@ref{2eb,,float} datatype:


@itemize *

@item 
Le module @code{decimal} « est basé sur un modèle en virgule flottante conçu pour les humains, qui suit ce principe directeur : l'ordinateur doit fournir un modèle de calcul qui fonctionne de la même manière que le calcul qu'on apprend à l'école » – extrait (traduit) de la spécification de l'arithmétique décimale.

@item 
Les nombres décimaux peuvent être représentés exactement en base décimale flottante. En revanche, des nombres tels que @code{1.1} ou @code{1.2} n'ont pas de représentation exacte en base binaire flottante. L'utilisateur final ne s'attend typiquement pas à obtenir @code{3.3000000000000003} lorsqu'il saisit @code{1.1 + 2.2}, ce qui se passe en arithmétique binaire à virgule flottante.

@item 
Ces inexactitudes ont des conséquences en arithmétique. En base décimale à virgule flottante, @code{0.1 + 0.1 + 0.1 - 0.3} est exactement égal à zéro. En virgule flottante binaire, l'ordinateur l'évalue à @code{5.5511151231257827e-017}. Bien que très proche de zéro, cette différence induit des erreurs lors des tests d'égalité, erreurs qui peuvent s'accumuler. Pour ces raisons @code{decimal} est le module utilisé pour des applications comptables ayant des contraintes strictes de fiabilité.

@item 
Le module @code{decimal} incorpore la notion de chiffres significatifs, de façon à ce que @code{1.30 + 1.20} égale @code{2.50}. Le dernier zéro est conservé pour respecter le nombre de chiffres significatifs. C'est l'affichage préféré pour représenter des sommes d'argent. Pour la multiplication, l'approche « scolaire » utilise tous les chiffres présents dans les facteurs. Par exemple, @code{1.3 * 1.2} donne @code{1.56} tandis que @code{1.30 * 1.20} donne @code{1.5600}.

@item 
Contrairement à l'arithmétique en virgule flottante binaire, le module @code{decimal} possède un paramètre de précision ajustable (par défaut à 28 chiffres significatifs) qui peut être aussi élevée que nécessaire pour un problème donné :

@example
>>> from decimal import *
>>> getcontext().prec = 6
>>> Decimal(1) / Decimal(7)
Decimal('0.142857')
>>> getcontext().prec = 28
>>> Decimal(1) / Decimal(7)
Decimal('0.1428571428571428571428571429')
@end example

@item 
L'arithmétique binaire et décimale en virgule flottante sont implémentées selon des standards publiés. Alors que le type @code{float} n'expose qu'une faible portion de ses capacités, le module @code{decimal} expose tous les composants nécessaires du standard. Lorsque nécessaire, le développeur a un contrôle total de la gestion des signaux et de l'arrondi. Cela inclut la possibilité de forcer une arithmétique exacte en utilisant des exceptions pour bloquer toute opération inexacte.

@item 
Le module @code{decimal} a été conçu pour gérer « sans préjugé, à la fois une arithmétique décimale non-arrondie (aussi appelée arithmétique en virgule fixe) et à la fois une arithmétique en virgule flottante » (extrait traduit de la spécification de l'arithmétique décimale).
@end itemize

Le module est conçu autour de trois concepts : le nombre décimal, le contexte arithmétique et les signaux.

Un @code{Decimal} est immuable. Il a un signe, un coefficient et un exposant. Pour préserver le nombre de chiffres significatifs, les zéros en fin de chaîne ne sont pas tronqués. Les décimaux incluent aussi des valeurs spéciales telles que @code{Infinity}, @code{-Infinity} et @code{NaN}. Le standard fait également la différence entre @code{-0} et @code{+0}.

Le contexte de l'arithmétique est un environnement qui permet de configurer une précision, une règle pour l'arrondi, des limites sur l'exposant, des options indiquant le résultat des opérations et si les signaux (remontés lors d'opérations illégales) sont traités comme des exceptions Python. Les options d'arrondi incluent @ref{25be,,ROUND_CEILING}, @ref{25bf,,ROUND_DOWN}, @ref{25c0,,ROUND_FLOOR}, @ref{25c1,,ROUND_HALF_DOWN}, @ref{25c2,,ROUND_HALF_EVEN}, @ref{25c3,,ROUND_HALF_UP}, @ref{25c4,,ROUND_UP} et @ref{25c5,,ROUND_05UP}.

Les signaux sont des groupes de conditions exceptionnelles qui surviennent durant le calcul. Selon les besoins de l'application, les signaux peuvent être ignorés, considérés comme de l'information, ou bien traités comme des exceptions. Les signaux dans le module @code{decimal} sont : @ref{25c6,,Clamped}, @ref{108c,,InvalidOperation}, @ref{25c7,,DivisionByZero}, @ref{25c8,,Inexact}, @ref{25c9,,Rounded}, @ref{25ca,,Subnormal}, @ref{25cb,,Overflow}, @ref{25cc,,Underflow} et @ref{1086,,FloatOperation}.

Chaque signal est configurable indépendamment, à travers un drapeau (ou option) et un activateur de déroutement. Quand une opération illégale survient, le drapeau du signal est mis à @code{1} puis, si l'activateur est configuré, une exception est levée. La mise à @code{1} du drapeau est persistante, l'utilisateur doit donc remettre les drapeaux à zéro avant de commencer un calcul qu'il souhaite surveiller.


@subsubheading Voir aussi



@itemize *

@item 
Spécification d'IBM sur l'arithmétique décimale : The General Decimal Arithmetic Specification@footnote{https://speleotrove.com/decimal/decarith.html} (article en anglais).
@end itemize


@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@menu
* Introduction pratique:: 
* Les objets Decimal:: 
* Objets de contexte:: 
* Constantes: Constantes<4>. 
* Modes d'arrondi:: 
* Signaux:: 
* Floating-Point Notes:: 
* Working with threads:: 
* Cas pratiques:: 
* FAQ decimal:: 

@end menu

@node Introduction pratique,Les objets Decimal,,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-tutorial}@anchor{25cd}@anchor{library/decimal quick-start-tutorial}@anchor{25ce}
@subsubsection Introduction pratique


Commençons par importer le module, regarder le contexte actuel avec @ref{155c,,getcontext()} et, si nécessaire, configurer la précision, l'arrondi et la gestion des signaux :

@example
>>> from decimal import *
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[], traps=[Overflow, DivisionByZero,
        InvalidOperation])

>>> getcontext().prec = 7       # Set a new precision
@end example

Les instances de @code{Decimal} peuvent être construites avec des entiers, des chaînes de caractères, des @code{floats} ou des `n'-uplets. La construction depuis un entier ou un @code{float} effectue la conversion exacte de cet entier ou de ce @code{float}. Les nombres décimaux incluent des valeurs spéciales telles que @code{NaN} qui signifie en anglais « `Not a number' », en français « pas un nombre », des @code{Infinity} positifs ou négatifs et @code{-0} :

@example
>>> getcontext().prec = 28
>>> Decimal(10)
Decimal('10')
>>> Decimal('3.14')
Decimal('3.14')
>>> Decimal(3.14)
Decimal('3.140000000000000124344978758017532527446746826171875')
>>> Decimal((0, (3, 1, 4), -2))
Decimal('3.14')
>>> Decimal(str(2.0 ** 0.5))
Decimal('1.4142135623730951')
>>> Decimal(2) ** Decimal('0.5')
Decimal('1.414213562373095048801688724')
>>> Decimal('NaN')
Decimal('NaN')
>>> Decimal('-Infinity')
Decimal('-Infinity')
@end example

Si le signal @ref{1086,,FloatOperation} est activé pour déroutement, un mélange accidentel d'objets @code{Decimal} et de @code{float} dans les constructeurs ou des opérations de comparaison lève une exception :

@example
>>> c = getcontext()
>>> c.traps[FloatOperation] = True
>>> Decimal(3.14)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') < 3.7
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.FloatOperation: [<class 'decimal.FloatOperation'>]
>>> Decimal('3.5') == 3.5
True
@end example


Ajouté dans la version 3.3.


Le nombre de chiffres significatifs d'un nouvel objet @code{Decimal} est déterminé entièrement par le nombre de chiffres saisis. La précision et les règles d'arrondis n'interviennent que lors d'opérations arithmétiques.

@example
>>> getcontext().prec = 6
>>> Decimal('3.0')
Decimal('3.0')
>>> Decimal('3.1415926535')
Decimal('3.1415926535')
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85987')
>>> getcontext().rounding = ROUND_UP
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85988')
@end example

Si les limites internes de la version en C sont dépassées, la construction d'un objet décimal lève l'exception @ref{108c,,InvalidOperation} :

@example
>>> Decimal("1e9999999999999999999")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
decimal.InvalidOperation: [<class 'decimal.InvalidOperation'>]
@end example


Modifié dans la version 3.3.


Decimals interact well with much of the rest of Python.  Here is a small decimal
floating-point flying circus:

@example
>>> data = list(map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()))
>>> max(data)
Decimal('9.25')
>>> min(data)
Decimal('0.03')
>>> sorted(data)
[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
 Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
>>> sum(data)
Decimal('19.29')
>>> a,b,c = data[:3]
>>> str(a)
'1.34'
>>> float(a)
1.34
>>> round(a, 1)
Decimal('1.3')
>>> int(a)
1
>>> a * 5
Decimal('6.70')
>>> a * b
Decimal('2.5058')
>>> c % a
Decimal('0.77')
@end example

Et certaines fonctions mathématiques sont également disponibles sur des instances de @code{Decimal} :

@example
>>> getcontext().prec = 28
>>> Decimal(2).sqrt()
Decimal('1.414213562373095048801688724')
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal('10').ln()
Decimal('2.302585092994045684017991455')
>>> Decimal('10').log10()
Decimal('1')
@end example

La méthode @ref{1092,,quantize()} arrondit un nombre à un exposant déterminé. Cette méthode est utile pour des applications monétaires qui arrondissent souvent un résultat à un nombre déterminé de chiffres après la virgule :

@example
>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')
@end example

Comme montré plus haut, la fonction @ref{155c,,getcontext()} accède au contexte actuel et permet de modifier les paramètres. Cette approche répond aux besoins de la plupart des applications.

Pour un travail plus avancé, il peut être utile de créer des contextes alternatifs en utilisant le constructeur de @code{Context}. Pour activer cet objet @code{Context}, utilisez la fonction @ref{25cf,,setcontext()}.

En accord avec le standard, le module @ref{36,,decimal} fournit des objets `Context' standards, @ref{108a,,BasicContext} et @ref{108b,,ExtendedContext}. Le premier est particulièrement utile pour le débogage car beaucoup des signaux ont leur déroutement activé :

@example
>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
>>> setcontext(myothercontext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857142857142857142857142857')

>>> ExtendedContext
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[], traps=[])
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857143')
>>> Decimal(42) / Decimal(0)
Decimal('Infinity')

>>> setcontext(BasicContext)
>>> Decimal(42) / Decimal(0)
Traceback (most recent call last):
  File "<pyshell#143>", line 1, in -toplevel-
    Decimal(42) / Decimal(0)
DivisionByZero: x / 0
@end example

Les objets @code{Context} ont aussi des options pour détecter des opérations illégales lors des calculs. Ces options restent activées jusqu'à ce qu'elles soit remises à zéro de manière explicite. Il convient donc de remettre à zéro ces options avant chaque inspection de chaque calcul, avec la méthode @ref{25d0,,clear_flags()}.

@example
>>> setcontext(ExtendedContext)
>>> getcontext().clear_flags()
>>> Decimal(355) / Decimal(113)
Decimal('3.14159292')
>>> getcontext()
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999, Emax=999999,
        capitals=1, clamp=0, flags=[Inexact, Rounded], traps=[])
@end example

Les options montrent que l'approximation de π par une fraction a été arrondie (les chiffres au-delà de la précision spécifiée par l'objet `Context' ont été tronqués) et que le résultat est différent (certains des chiffres tronqués étaient différents de zéro).

L'activation du déroutement se fait en utilisant un dictionnaire dans l'attribut @code{traps} du contexte :

@example
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(0)
Decimal('Infinity')
>>> getcontext().traps[DivisionByZero] = 1
>>> Decimal(1) / Decimal(0)
Traceback (most recent call last):
  File "<pyshell#112>", line 1, in -toplevel-
    Decimal(1) / Decimal(0)
DivisionByZero: x / 0
@end example

La plupart des applications n'ajustent l'objet @code{Context} qu'une seule fois, au démarrage. Et, dans beaucoup d'applications, les données sont converties une fois pour toutes en @ref{29a,,Decimal}. Une fois le @code{Context} initialisé et les objets @code{Decimal} créés, la majeure partie du programme manipule les données de la même manière qu'avec d'autres types numériques Python.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Les objets Decimal,Objets de contexte,Introduction pratique,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-decimal}@anchor{25d1}@anchor{library/decimal decimal-objects}@anchor{25d2}
@subsubsection Les objets `Decimal'


@geindex Decimal (classe dans decimal)
@anchor{library/decimal decimal Decimal}@anchor{29a}
@deffn {Classe} decimal.Decimal (value='0', context=None)

Construit un nouvel objet @ref{29a,,Decimal} à partir de `value'.

`value' peut être un entier, une chaîne de caractères, un `n'-uplet, un @ref{2eb,,float} ou une autre instance de @ref{29a,,Decimal}. Si `value' n'est pas fourni, le constructeur renvoie @code{Decimal('0')}. Si `value' est une chaîne de caractères, elle doit correspondre à la syntaxe décimale en dehors des espaces de début et de fin, ou des tirets bas, qui sont enlevés :

@example
sign           ::=  '+' | '-'
digit          ::=  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
indicator      ::=  'e' | 'E'
digits         ::=  digit [digit]...
decimal-part   ::=  digits '.' [digits] | ['.'] digits
exponent-part  ::=  indicator [sign] digits
infinity       ::=  'Infinity' | 'Inf'
nan            ::=  'NaN' [digits] | 'sNaN' [digits]
numeric-value  ::=  decimal-part [exponent-part] | infinity
numeric-string ::=  [sign] numeric-value | [sign] nan
@end example

Les chiffres codés en Unicode sont aussi autorisés, dans les emplacements @code{digit} ci-dessus. Cela inclut des chiffres décimaux venant d'autres alphabets (par exemple les chiffres indo-arabes ou Devanagari) ainsi que les chiffres de pleine largeur @code{'\uff10'} jusqu'à @code{'\uff19'}.

Si `value' est un @ref{366,,n-uplet}, il doit avoir trois éléments, le signe (@code{0} pour positif ou @code{1} pour négatif), un @ref{366,,n-uplet} de chiffres et un entier représentant l'exposant. Par exemple, @code{Decimal((0, (1, 4, 1, 4), -3))} construit l'objet @code{Decimal('1.414')}.

If `value' is a @ref{2eb,,float}, the binary floating-point value is losslessly
converted to its exact decimal equivalent.  This conversion can often require
53 or more digits of precision.  For example, @code{Decimal(float('1.1'))}
converts to
@code{Decimal('1.100000000000000088817841970012523233890533447265625')}.

La précision spécifiée dans le contexte n'affecte pas le nombre de chiffres stockés. Cette valeur est déterminée exclusivement par le nombre de chiffres dans `value'. Par exemple, @code{Decimal('3.00000')} enregistre les 5 zéros même si la précision du contexte est de 3.

L'objectif de l'argument `context' est de déterminer ce que Python doit faire si `value' est une chaîne avec un mauvais format. Si le déroutement est activé pour @ref{108c,,InvalidOperation}, une exception est levée, sinon le constructeur renvoie un objet @code{Decimal} de valeur @code{NaN}.

Une fois construit, un objet @ref{29a,,Decimal} est immuable.


Modifié dans la version 3.2: l'argument du constructeur peut désormais être un objet @ref{2eb,,float}.



Modifié dans la version 3.3: un argument @ref{2eb,,float} lève une exception si le déroutement est activé pour @ref{1086,,FloatOperation}. Par défaut le déroutement n'est pas activé.



Modifié dans la version 3.6: les tirets bas sont autorisés pour regrouper, tout comme pour l'arithmétique en virgule fixe et flottante.


Decimal floating-point objects share many properties with the other built-in
numeric types such as @ref{2eb,,float} and @ref{254,,int}.  All of the usual math
operations and special methods apply.  Likewise, decimal objects can be
copied, pickled, printed, used as dictionary keys, used as set elements,
compared, sorted, and coerced to another type (such as @ref{2eb,,float} or
@ref{254,,int}).

Il existe quelques différences mineures entre l'arithmétique entre les objets décimaux et l'arithmétique avec les entiers et les @code{float}. Quand l'opérateur modulo @code{%} est appliqué sur des objets décimaux, le signe du résultat est le signe du `dividende' plutôt que le signe du diviseur :

@example
>>> (-7) % 4
1
>>> Decimal(-7) % Decimal(4)
Decimal('-3')
@end example

L'opérateur division entière (@code{//}) se comporte de la même manière, renvoyant la partie entière du quotient plutôt que son arrondi, de manière à préserver l'identité d'Euclide @code{x == (x // y) * y + x % y} :

@example
>>> -7 // 4
-2
>>> Decimal(-7) // Decimal(4)
Decimal('-1')
@end example

Les opérateurs @code{//} et @code{%} implémentent la division entière et le reste (ou modulo), respectivement, tels que décrits dans la spécification.

Les objets @code{Decimal} ne peuvent généralement pas être combinés avec des @code{float} ou des objets @ref{1e4,,fractions.Fraction} lors d'opérations arithmétiques : toute addition entre un @ref{29a,,Decimal} et un @ref{2eb,,float}, par exemple, lève une exception @ref{522,,TypeError}. Cependant, il est possible d'utiliser les opérateurs de comparaison entre instances de @ref{29a,,Decimal} et les autres types numériques. Cela évite d'avoir des résultats absurdes lors des tests d'égalité entre différents types.


Modifié dans la version 3.2: les comparaisons inter-types entre @ref{29a,,Decimal} et les autres types numériques sont désormais intégralement gérées.


In addition to the standard numeric properties, decimal floating-point
objects also have a number of specialized methods:

@geindex adjusted() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal adjusted}@anchor{25d3}
@deffn {Méthode} adjusted ()

Renvoie l'exposant ajusté après avoir décalé les chiffres les plus à droite du coefficient jusqu'à ce qu'il ne reste que le premier chiffre : @code{Decimal('321e+5').adjusted()} renvoie sept. Utilisée pour déterminer la position du chiffre le plus significatif par rapport à la virgule.
@end deffn

@geindex as_integer_ratio() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal as_integer_ratio}@anchor{c82}
@deffn {Méthode} as_integer_ratio ()

Renvoie un couple d'entiers @code{(n, d)} qui représentent l'instance @ref{29a,,Decimal} donnée sous la forme d'une fraction, avec les termes les plus petits possibles et avec un dénominateur positif :

@example
>>> Decimal('-3.14').as_integer_ratio()
(-157, 50)
@end example

La conversion est exacte. Lève une @code{OverflowError} sur l'infini et @code{ValueError} sur les `Nan'.
@end deffn


Ajouté dans la version 3.6.


@geindex as_tuple() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal as_tuple}@anchor{25d4}
@deffn {Méthode} as_tuple ()

Renvoie une représentation sous la forme d'un @ref{639,,n-uplet nommé} du nombre @code{DecimalTuple(sign, digits, exposant)}.
@end deffn

@geindex canonical() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal canonical}@anchor{25d5}
@deffn {Méthode} canonical ()

Renvoie la forme canonique de l'argument. Actuellement, la forme d'une instance @ref{29a,,Decimal} est toujours canonique, donc cette opération renvoie son argument inchangé.
@end deffn

@geindex compare() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal compare}@anchor{25d6}
@deffn {Méthode} compare (other, context=None)

Compare les valeurs de deux instances `Decimal'. @ref{25d6,,compare()} renvoie une instance `Decimal' et, si l'un des opérandes est un `NaN', alors le résultat est un `NaN' :

@example
a or b is a NaN  ==> Decimal('NaN')
a < b            ==> Decimal('-1')
a == b           ==> Decimal('0')
a > b            ==> Decimal('1')
@end example
@end deffn

@geindex compare_signal() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal compare_signal}@anchor{25d7}
@deffn {Méthode} compare_signal (other, context=None)

Cette opération est identique à la méthode @ref{25d6,,compare()}, sauf que tous les `NaN' activent un déroutement. Autrement dit, si aucun des opérandes n'est un `NaN' de signalisation, alors tout opérande `NaN' silencieux est traité comme s'il s'agissait d'un `NaN' de signalisation.
@end deffn

@geindex compare_total() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal compare_total}@anchor{25d8}
@deffn {Méthode} compare_total (other, context=None)

Compare deux opérandes en utilisant leur représentation abstraite plutôt que leur valeur numérique. Similaire à la méthode @ref{25d6,,compare()}, mais le résultat donne un ordre total sur les instances @ref{29a,,Decimal}. Deux instances de @ref{29a,,Decimal} avec la même valeur numérique mais des représentations différentes se comparent de manière inégale dans cet ordre :

@example
>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')
@end example

Les `NaN' silencieux et de signalisation sont également inclus dans l'ordre total. Le résultat de cette fonction est @code{Decimal('0')} si les deux opérandes ont la même représentation, @code{Decimal('-1')} si le premier opérande est inférieur au second, et @code{Decimal('1')} si le premier opérande est supérieur au deuxième opérande. Voir les spécifications pour les détails de l'ordre total.

Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une `InvalidOperation' si le deuxième opérande ne peut pas être converti exactement.
@end deffn

@geindex compare_total_mag() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal compare_total_mag}@anchor{25d9}
@deffn {Méthode} compare_total_mag (other, context=None)

Compare deux opérandes en utilisant leur représentation abstraite plutôt que leur valeur comme dans @ref{25d8,,compare_total()}, mais en ignorant le signe de chaque opérande. @code{x.compare_total_mag(y)} est équivalent à @code{x.copy_abs().compare_total(y.copy_abs())}.

Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une `InvalidOperation' si le deuxième opérande ne peut pas être converti exactement.
@end deffn

@geindex conjugate() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal conjugate}@anchor{25da}
@deffn {Méthode} conjugate ()

Ne fait que renvoyer self ; cette méthode existe uniquement pour se conformer à la spécification.
@end deffn

@geindex copy_abs() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal copy_abs}@anchor{25db}
@deffn {Méthode} copy_abs ()

Renvoie la valeur absolue de l'argument. Cette opération ne dépend pas du contexte et est silencieuse : aucun drapeau n'est modifié et aucun arrondi n'est effectué.
@end deffn

@geindex copy_negate() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal copy_negate}@anchor{25dc}
@deffn {Méthode} copy_negate ()

Renvoie la négation de l'argument. Cette opération ne dépend pas du contexte et est silencieuse : aucun drapeau n'est modifié et aucun arrondi n'est effectué.
@end deffn

@geindex copy_sign() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal copy_sign}@anchor{25dd}
@deffn {Méthode} copy_sign (other, context=None)

Renvoie une copie du premier opérande mais avec le même signe que celui du deuxième opérande. Par exemple :

@example
>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')
@end example

Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une `InvalidOperation' si le deuxième opérande ne peut pas être converti exactement.
@end deffn

@geindex exp() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal exp}@anchor{108e}
@deffn {Méthode} exp (context=None)

Renvoie la valeur @code{e**x} (fonction exponentielle) du nombre donné. Le résultat est correctement arrondi en utilisant le mode d'arrondi @ref{25c2,,ROUND_HALF_EVEN}.

@example
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal(321).exp()
Decimal('2.561702493119680037517373933E+139')
@end example
@end deffn

@geindex from_float() (méthode de la classe decimal.Decimal)
@anchor{library/decimal decimal Decimal from_float}@anchor{11e1}
@deffn {Méthode} classmethod from_float (f)

Constructeur alternatif qui n'accepte que les instances de @ref{2eb,,float} ou @ref{254,,int}.

Remarquez que @code{Decimal.from_float(0.1)} est différent de @code{Decimal('0.1')}. Puisque 0.1 n'est pas exactement représentable en virgule flottante binaire, la valeur est stockée comme la valeur représentable la plus proche qui est @code{0x1.999999999999ap-4}. La valeur équivalente en décimal est @code{0.1000000000000000055511151231257827021181583404541015625}.

@cartouche
@quotation Note 
depuis Python 3.2, une instance @ref{29a,,Decimal} peut également être construite directement à partir d'un @ref{2eb,,float}.
@end quotation
@end cartouche

@example
>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> Decimal.from_float(float('nan'))
Decimal('NaN')
>>> Decimal.from_float(float('inf'))
Decimal('Infinity')
>>> Decimal.from_float(float('-inf'))
Decimal('-Infinity')
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex fma() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal fma}@anchor{25de}
@deffn {Méthode} fma (other, third, context=None)

Multiplier-ajouter fusionné. Renvoie @code{self*other+third} sans arrondir le produit intermédiaire @code{self*other}.

@example
>>> Decimal(2).fma(3, 5)
Decimal('11')
@end example
@end deffn

@geindex is_canonical() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_canonical}@anchor{25df}
@deffn {Méthode} is_canonical ()

Renvoie @ref{bfb,,True} si l'argument est sous forme canonique et @ref{b25,,False} sinon. Actuellement, une instance @ref{29a,,Decimal} est toujours canonique, donc cette opération renvoie toujours @ref{bfb,,True}.
@end deffn

@geindex is_finite() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_finite}@anchor{25e0}
@deffn {Méthode} is_finite ()

Renvoie @ref{bfb,,True} si l'argument est un nombre fini et @ref{b25,,False} si l'argument est un infini ou un `NaN'.
@end deffn

@geindex is_infinite() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_infinite}@anchor{25e1}
@deffn {Méthode} is_infinite ()

Renvoie @ref{bfb,,True} si l'argument est un infini positif ou négatif, @ref{b25,,False} sinon.
@end deffn

@geindex is_nan() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_nan}@anchor{25e2}
@deffn {Méthode} is_nan ()

Renvoie @ref{bfb,,True} si l'argument est un `NaN' (signalétique ou silencieux), @ref{b25,,False} sinon.
@end deffn

@geindex is_normal() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_normal}@anchor{25e3}
@deffn {Méthode} is_normal (context=None)

Renvoie @ref{bfb,,True} si l'argument est un nombre fini `normal'. Renvoie @ref{b25,,False} si l'argument est zéro, infini, résultat d'un dépassement par valeur inférieure ou un `NaN'.
@end deffn

@geindex is_qnan() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_qnan}@anchor{25e4}
@deffn {Méthode} is_qnan ()

Renvoie @ref{bfb,,True} si l'argument est un `NaN' silencieux, @ref{b25,,False} sinon.
@end deffn

@geindex is_signed() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_signed}@anchor{25e5}
@deffn {Méthode} is_signed ()

Renvoie @ref{bfb,,True} si l'argument est négatif, @ref{b25,,False} sinon. Remarquez que les zéros et les `NaN' peuvent être signés.
@end deffn

@geindex is_snan() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_snan}@anchor{25e6}
@deffn {Méthode} is_snan ()

Renvoie @ref{bfb,,True} si l'argument est un `NaN' signalétique, @ref{b25,,False} sinon.
@end deffn

@geindex is_subnormal() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_subnormal}@anchor{25e7}
@deffn {Méthode} is_subnormal (context=None)

Renvoie @ref{bfb,,True} si l'argument est le résultat d'un dépassement par valeur inférieure, @ref{b25,,False} sinon.
@end deffn

@geindex is_zero() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal is_zero}@anchor{25e8}
@deffn {Méthode} is_zero ()

Renvoie @ref{bfb,,True} si l'argument est un zéro (positif ou négatif), @ref{b25,,False} sinon.
@end deffn

@geindex ln() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal ln}@anchor{108f}
@deffn {Méthode} ln (context=None)

Renvoie le logarithme naturel (base e) de l'opérande. Le résultat est arrondi avec le mode @ref{25c2,,ROUND_HALF_EVEN}.
@end deffn

@geindex log10() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal log10}@anchor{25e9}
@deffn {Méthode} log10 (context=None)

Renvoie le logarithme en base 10 de l'opérande. Le résultat est arrondi avec le mode @ref{25c2,,ROUND_HALF_EVEN}.
@end deffn

@geindex logb() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal logb}@anchor{25ea}
@deffn {Méthode} logb (context=None)

Pour un nombre non nul, renvoie l'exposant ajusté de son opérande en tant qu'instance @ref{29a,,Decimal}. Si l'opérande est un zéro alors @code{Decimal('-Infinity')} est renvoyé et le drapeau @ref{25c7,,DivisionByZero} est levé. Si l'opérande est un infini alors @code{Decimal('Infinity')} est renvoyé.
@end deffn

@geindex logical_and() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_and}@anchor{25eb}
@deffn {Méthode} logical_and (other, context=None)

@ref{25eb,,logical_and()} est une opération logique qui prend deux `opérandes logiques' (voir @ref{25ec,,Opérandes logiques}). Le résultat est le `ET' des chiffres des deux opérandes.
@end deffn

@geindex logical_invert() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_invert}@anchor{25ed}
@deffn {Méthode} logical_invert (context=None)

@ref{25ed,,logical_invert()} est une opération logique. Le résultat est l'inversion de chacun des chiffres de l'opérande.
@end deffn

@geindex logical_or() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_or}@anchor{25ee}
@deffn {Méthode} logical_or (other, context=None)

@ref{25ee,,logical_or()} est une opération logique qui prend deux `opérandes logiques' (voir @ref{25ec,,Opérandes logiques}). Le résultat est le `OU' des chiffres des deux opérandes.
@end deffn

@geindex logical_xor() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal logical_xor}@anchor{25ef}
@deffn {Méthode} logical_xor (other, context=None)

@ref{25ef,,logical_xor()} est une opération logique qui prend deux `opérandes logiques' (voir @ref{25ec,,Opérandes logiques}). Le résultat est le `OU EXCLUSIF' des chiffres des deux opérandes.
@end deffn

@geindex max() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal max}@anchor{25f0}
@deffn {Méthode} max (other, context=None)

Comme @code{max(self, other)} sauf que la règle d'arrondi de `context' est appliquée avant le retour et que les valeurs @code{NaN} sont signalées ou ignorées (selon le contexte et si elles sont signalétiques ou silencieuses).
@end deffn

@geindex max_mag() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal max_mag}@anchor{25f1}
@deffn {Méthode} max_mag (other, context=None)

Semblable à la méthode @ref{25f0,,max()}, mais la comparaison est effectuée en utilisant les valeurs absolues des opérandes.
@end deffn

@geindex min() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal min}@anchor{25f2}
@deffn {Méthode} min (other, context=None)

Comme @code{min(self, other)} sauf que la règle d'arrondi de `context' est appliquée avant le retour et que les valeurs @code{NaN} sont signalées ou ignorées (selon le contexte et si elles sont signalétiques ou silencieuses).
@end deffn

@geindex min_mag() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal min_mag}@anchor{25f3}
@deffn {Méthode} min_mag (other, context=None)

Semblable à la méthode @ref{25f2,,min()}, mais la comparaison est effectuée en utilisant les valeurs absolues des opérandes.
@end deffn

@geindex next_minus() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal next_minus}@anchor{25f4}
@deffn {Méthode} next_minus (context=None)

Renvoie le plus grand nombre représentable dans le `context' donné (ou dans le contexte du fil d'exécution actuel si aucun contexte n'est donné) qui est plus petit que l'opérande donné.
@end deffn

@geindex next_plus() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal next_plus}@anchor{25f5}
@deffn {Méthode} next_plus (context=None)

Renvoie le plus petit nombre représentable dans le `context' donné (ou dans le contexte du fil d'exécution actuel si aucun contexte n'est donné) qui est supérieur à l'opérande donné.
@end deffn

@geindex next_toward() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal next_toward}@anchor{25f6}
@deffn {Méthode} next_toward (other, context=None)

Si les deux opérandes ne sont pas égaux, renvoie le nombre le plus proche du premier opérande dans la direction du deuxième opérande. Si les deux opérandes sont numériquement égaux, renvoie une copie du premier opérande avec le signe défini comme étant le même que le signe du second opérande.
@end deffn

@geindex normalize() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal normalize}@anchor{25f7}
@deffn {Méthode} normalize (context=None)

Utilisé pour produire des valeurs canoniques d'une classe d'équivalence dans le contexte actuel ou dans le contexte spécifié.

C'est la même sémantique que l'opération unaire plus, sauf que si le résultat final est fini, il est réduit à sa forme la plus simple, avec tous les zéros à droite supprimés et son signe conservé. Autrement dit, tant que la mantisse est différente de zéro et est un multiple de dix, elle est divisée par dix et l'exposant est incrémenté de 1. Sinon (la mantisse est nulle), l'exposant est mis à 0. Dans tous les cas, le signe est inchangé.

Par exemple, @code{Decimal('32.100')} et @code{Decimal('0.321000e+2')} se normalisent tous deux à la valeur équivalente @code{Decimal('32.1')}.

Notez que l'arrondi est appliqué `avant' la réduction à la forme la plus simple.

Dans les dernières versions de la spécification, cette opération est également connue sous le nom de @code{reduce}.
@end deffn

@geindex number_class() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal number_class}@anchor{25f8}
@deffn {Méthode} number_class (context=None)

Renvoie une chaîne décrivant la `classe' de l'opérande. La valeur renvoyée est l'une des dix chaînes suivantes.


@itemize *

@item 
@code{"-Infinity"}, indiquant que l'opérande est l'infini négatif ;

@item 
@code{"-Normal"}, indiquant que l'opérande est un nombre négatif normal ;

@item 
@code{"-Subnormal"}, indiquant que l'opérande est négatif et qu'il est le résultat d'un dépassement par valeur inférieure ;

@item 
@code{"-Zero"}, indiquant que l'opérande est un zéro négatif ;

@item 
@code{"+Zero"}, indiquant que l'opérande est un zéro positif ;

@item 
@code{"+Subnormal"}, indiquant que l'opérande est positif et qu'il est le résultat un dépassement par valeur inférieure ;

@item 
@code{"+Normal"}, indiquant que l'opérande est un nombre positif normal ;

@item 
@code{"+Infinity"}, indiquant que l'opérande est l'infini positif ;

@item 
@code{"NaN"}, indiquant que l'opérande est un `NaN' (`Not a Number', pas un nombre) silencieux ;

@item 
@code{"sNaN"}, indiquant que l'opérande est un `NaN' (`Not a Number', pas un nombre) signalétique.
@end itemize
@end deffn

@geindex quantize() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal quantize}@anchor{1092}
@deffn {Méthode} quantize (exp, rounding=None, context=None)

Renvoie une valeur égale au premier opérande après arrondi et ayant l'exposant du second opérande.

@example
>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')
@end example

Contrairement aux autres opérations, si la longueur du coefficient après l'opération de quantification est supérieure à la précision, alors une @ref{108c,,InvalidOperation} est signalée. Ceci garantit que, sauf condition d'erreur, l'exposant quantifié est toujours égal à celui de l'opérande de droite.

Contrairement aux autres opérations, la quantification ne signale jamais de dépassement par valeur inférieure, même si le résultat est inférieur à la valeur minimale représentable et inexact.

Si l'exposant du deuxième opérande est supérieur à celui du premier, un arrondi peut être nécessaire. Dans ce cas, le mode d'arrondi est déterminé par l'argument @code{rounding} s'il est donné, sinon par l'argument @code{context} donné ; si aucun argument n'est donné, le mode d'arrondi du contexte du fil d'exécution courant est utilisé.

Une erreur est renvoyée chaque fois que l'exposant résultant est supérieur à @code{Emax} ou inférieur à @ref{25f9,,Etiny()}.
@end deffn

@geindex radix() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal radix}@anchor{25fa}
@deffn {Méthode} radix ()

Renvoie @code{Decimal(10)}, la base (base) dans laquelle la classe @ref{29a,,Decimal} fait toute son arithmétique. Inclus pour la compatibilité avec la spécification.
@end deffn

@geindex remainder_near() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal remainder_near}@anchor{25fb}
@deffn {Méthode} remainder_near (other, context=None)

Renvoie le reste de la division de `self' par `other'. La différence avec @code{self % other} réside dans le signe du reste, qui est choisi de manière à minimiser sa valeur absolue. Plus précisément, la valeur de retour est @code{self - n * other} où @code{n} est l'entier le plus proche de la valeur exacte de @code{self / other} et, si deux entiers sont également proches, alors l'entier pair est choisi.

Si le résultat est zéro, alors son signe est le signe de `self'.

@example
>>> Decimal(18).remainder_near(Decimal(10))
Decimal('-2')
>>> Decimal(25).remainder_near(Decimal(10))
Decimal('5')
>>> Decimal(35).remainder_near(Decimal(10))
Decimal('-5')
@end example
@end deffn

@geindex rotate() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal rotate}@anchor{25fc}
@deffn {Méthode} rotate (other, context=None)

Renvoie le résultat de la rotation des chiffres du premier opérande d'une quantité spécifiée par le deuxième opérande. Le deuxième opérande doit être un entier compris dans la plage -précision à précision. La valeur absolue du deuxième opérande donne le nombre de rotations unitaires à faire. Si le deuxième opérande est positif alors la rotation se fait vers la gauche ; sinon la rotation se fait vers la droite. Le coefficient du premier opérande est complété à gauche avec des zéros à la précision de la longueur si nécessaire. Le signe et l'exposant du premier opérande sont inchangés.
@end deffn

@geindex same_quantum() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal same_quantum}@anchor{25fd}
@deffn {Méthode} same_quantum (other, context=None)

Teste si `self' et `other' ont le même exposant ou si les deux sont @code{NaN}.

Cette opération ne dépend pas du contexte et est silencieuse : aucun indicateur n'est modifié et aucun arrondi n'est effectué. Exceptionnellement, la version C peut lever une `InvalidOperation' si le deuxième opérande ne peut pas être converti exactement.
@end deffn

@geindex scaleb() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal scaleb}@anchor{25fe}
@deffn {Méthode} scaleb (other, context=None)

Renvoie le premier opérande avec l'exposant ajusté par le second. De manière équivalente, renvoie le premier opérande multiplié par @code{10**other}. Le deuxième opérande doit être entier.
@end deffn

@geindex shift() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal shift}@anchor{25ff}
@deffn {Méthode} shift (other, context=None)

Renvoie le résultat du décalage des chiffres du premier opérande d'une quantité spécifiée par le deuxième opérande. Le deuxième opérande doit être un entier compris dans la plage -précision à précision. La valeur absolue du deuxième opérande donne le nombre de décalages unitaires à effectuer. Si le deuxième opérande est positif alors le décalage est vers la gauche ; sinon le décalage est vers la droite. Les chiffres insérés dans le nombre par le décalage sont des zéros. Le signe et l'exposant du premier opérande sont inchangés.
@end deffn

@geindex sqrt() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal sqrt}@anchor{2600}
@deffn {Méthode} sqrt (context=None)

Renvoie la racine carrée de l'argument avec une précision maximale.
@end deffn

@geindex to_eng_string() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal to_eng_string}@anchor{2601}
@deffn {Méthode} to_eng_string (context=None)

Convertir en chaîne, en utilisant la notation ingénieur si un exposant est nécessaire.

La notation ingénieur possède un exposant qui est un multiple de 3. Cela peut laisser jusqu'à 3 chiffres à gauche de la décimale et peut nécessiter l'ajout d'un ou de deux zéros à la fin.

Par exemple, @code{Decimal('123E+1')} est converti en @code{Decimal('1.23E+3')}.
@end deffn

@geindex to_integral() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal to_integral}@anchor{2602}
@deffn {Méthode} to_integral (rounding=None, context=None)

Identique à la méthode @ref{2603,,to_integral_value()}. Le nom @code{to_integral} a été conservé pour la compatibilité avec les anciennes versions.
@end deffn

@geindex to_integral_exact() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal to_integral_exact}@anchor{2604}
@deffn {Méthode} to_integral_exact (rounding=None, context=None)

Arrondit à l'entier le plus proche, en signalant @ref{25c8,,Inexact} ou @ref{25c9,,Rounded} selon le cas si l'arrondi se produit. Le mode d'arrondi est déterminé par le paramètre @code{rounding} s'il est donné, sinon par le @code{context} donné. Si aucun paramètre n'est donné, le mode d'arrondi du contexte courant est utilisé.
@end deffn

@geindex to_integral_value() (méthode decimal.Decimal)
@anchor{library/decimal decimal Decimal to_integral_value}@anchor{2603}
@deffn {Méthode} to_integral_value (rounding=None, context=None)

Arrondit à l'entier le plus proche sans signaler @ref{25c8,,Inexact} ou @ref{25c9,,Rounded}. Si donné, applique `rounding' ; sinon, utilise la méthode d'arrondi dans le `context' fourni ou dans le contexte actuel.
@end deffn

Decimal numbers can be rounded using the @ref{12b8,,round()} function:


@deffn {Describe} round(number)
@end deffn


@deffn {Describe} round(number, ndigits)

If `ndigits' is not given or @code{None},
returns the nearest @ref{254,,int} to `number',
rounding ties to even, and ignoring the rounding mode of the
@ref{29a,,Decimal} context.  Raises @ref{86d,,OverflowError} if `number' is an
infinity or @ref{1ff,,ValueError} if it is a (quiet or signaling) NaN.

If `ndigits' is an @ref{254,,int}, the context's rounding mode is respected
and a @ref{29a,,Decimal} representing `number' rounded to the nearest
multiple of @code{Decimal('1E-ndigits')} is returned; in this case,
@code{round(number, ndigits)} is equivalent to
@code{self.quantize(Decimal('1E-ndigits'))}.  Returns @code{Decimal('NaN')} if
`number' is a quiet NaN.  Raises @ref{108c,,InvalidOperation} if `number'
is an infinity, a signaling NaN, or if the length of the coefficient after
the quantize operation would be greater than the current context's
precision.  In other words, for the non-corner cases:


@itemize *

@item 
if `ndigits' is positive, return `number' rounded to `ndigits' decimal
places;

@item 
if `ndigits' is zero, return `number' rounded to the nearest integer;

@item 
if `ndigits' is negative, return `number' rounded to the nearest
multiple of @code{10**abs(ndigits)}.
@end itemize

Par exemple :

@example
>>> from decimal import Decimal, getcontext, ROUND_DOWN
>>> getcontext().rounding = ROUND_DOWN
>>> round(Decimal('3.75'))     # context rounding ignored
4
>>> round(Decimal('3.5'))      # round-ties-to-even
4
>>> round(Decimal('3.75'), 0)  # uses the context rounding
Decimal('3')
>>> round(Decimal('3.75'), 1)
Decimal('3.7')
>>> round(Decimal('3.75'), -1)
Decimal('0E+1')
@end example
@end deffn
@end deffn

@menu
* Opérandes logiques:: 

@end menu

@node Opérandes logiques,,,Les objets Decimal
@anchor{library/decimal logical-operands}@anchor{2605}@anchor{library/decimal logical-operands-label}@anchor{25ec}
@subsubsection Opérandes logiques


Les méthodes @ref{25eb,,logical_and()}, @ref{25ed,,logical_invert()}, @ref{25ee,,logical_or()} et @ref{25ef,,logical_xor()} s'attendent à ce que leurs arguments soient des `opérandes logiques'. Un `opérande logique' est une instance @ref{29a,,Decimal} dont l'exposant et le signe sont tous les deux zéro et dont les chiffres sont tous @code{0} ou @code{1}.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Objets de contexte,Constantes<4>,Les objets Decimal,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal context-objects}@anchor{2606}@anchor{library/decimal decimal-context}@anchor{2269}
@subsubsection Objets de contexte


Les contextes sont des environnements pour les opérations arithmétiques. Ils régissent la précision, établissent des règles d'arrondi, déterminent quels signaux sont traités comme des exceptions et limitent la plage des exposants.

Chaque fil d'exécution a son propre contexte actuel qui est accessible ou modifié à l'aide des fonctions @ref{155c,,getcontext()} et @ref{25cf,,setcontext()} :

@geindex getcontext() (dans le module decimal)
@anchor{library/decimal decimal getcontext}@anchor{155c}
@deffn {Fonction} decimal.getcontext ()

Renvoie le contexte actuel du fil d'exécution courant.
@end deffn

@geindex setcontext() (dans le module decimal)
@anchor{library/decimal decimal setcontext}@anchor{25cf}
@deffn {Fonction} decimal.setcontext (c)

Définit le contexte du fil d'exécution courant à `c'.
@end deffn

Vous pouvez également utiliser l'instruction @ref{5bc,,with} et la fonction @ref{1792,,localcontext()} pour modifier temporairement le contexte actif.

@geindex localcontext() (dans le module decimal)
@anchor{library/decimal decimal localcontext}@anchor{1792}
@deffn {Fonction} decimal.localcontext (ctx=None, **kwargs)

Renvoie un gestionnaire de contexte qui définira le contexte actuel du fil d'exécution actif sur une copie de `ctx' à l'entrée de l'instruction `with' et restaurera le contexte précédent lors de la sortie de l'instruction `with'. Si aucun contexte n'est spécifié, une copie du contexte actuel est utilisée. L'argument `kwargs' est utilisé pour définir les attributs du nouveau contexte.

Par exemple, le code suivant définit la précision décimale actuelle à 42 chiffres, effectue un calcul, puis restaure automatiquement le contexte précédent :

@example
from decimal import localcontext

with localcontext() as ctx:
    ctx.prec = 42   # Perform a high precision calculation
    s = calculate_something()
s = +s  # Round the final result back to the default precision
@end example

En utilisant des arguments nommés, le code serait le suivant :

@example
from decimal import localcontext

with localcontext(prec=42) as ctx:
    s = calculate_something()
s = +s
@end example

Lève @ref{522,,TypeError} si `kwargs' fournit un attribut que @ref{1091,,Context} ne prend pas en charge. Lève soit @ref{522,,TypeError} ou @ref{1ff,,ValueError} si `kwargs' fournit une valeur invalide pour un attribut.


Modifié dans la version 3.11: @ref{1792,,localcontext()} prend désormais en charge la définition des attributs de contexte grâce à l'utilisation d'arguments nommés.

@end deffn

De nouveaux contextes peuvent également être créés à l'aide du constructeur @ref{1091,,Context} décrit ci-dessous. De plus, le module fournit trois contextes prédéfinis :

@geindex BasicContext (dans le module decimal)
@anchor{library/decimal decimal BasicContext}@anchor{108a}
@deffn {Données} decimal.BasicContext

Il s'agit d'un contexte standard défini par la `General Decimal Arithmetic Specification'. La précision est fixée à neuf. L'arrondi est défini sur @ref{25c3,,ROUND_HALF_UP}. Tous les drapeaux sont effacés. Tous les déroutements sont activés (ils lèvent des exceptions) sauf @ref{25c8,,Inexact}, @ref{25c9,,Rounded} et @ref{25ca,,Subnormal}.

Étant donné que de nombreuses options de déroutement sont activées, ce contexte est utile pour le débogage.
@end deffn

@geindex ExtendedContext (dans le module decimal)
@anchor{library/decimal decimal ExtendedContext}@anchor{108b}
@deffn {Données} decimal.ExtendedContext

Il s'agit d'un contexte standard défini par la `General Decimal Arithmetic Specification'. La précision est fixée à neuf. L'arrondi est défini sur @ref{25c2,,ROUND_HALF_EVEN}. Toutes les options de déroutement sont désactivées (afin que les exceptions ne soient pas levées pendant les calculs).

Comme les interruptions sont désactivées, ce contexte est utile pour les applications qui préfèrent avoir une valeur de résultat @code{NaN} ou @code{Infinity} au lieu de lever des exceptions. Cela permet à une application de terminer une exécution en présence de conditions qui, autrement, arrêteraient le programme.
@end deffn

@geindex DefaultContext (dans le module decimal)
@anchor{library/decimal decimal DefaultContext}@anchor{1089}
@deffn {Données} decimal.DefaultContext

Ce contexte est utilisé par le constructeur @ref{1091,,Context} comme prototype pour de nouveaux contextes. Changer un champ (par exemple la précision) a pour effet de changer la valeur par défaut pour les nouveaux contextes créés par le constructeur @ref{1091,,Context}.

Ce contexte est particulièrement utile dans les environnements à plusieurs fils d'exécution. La modification de l'un des champs avant le démarrage des fils a pour effet de définir des valeurs par défaut à l'échelle du système. La modification des champs après le démarrage des fils d'exécution n'est pas recommandée car cela nécessiterait une synchronisation des fils d'exécution pour éviter des conditions de concurrence.

Dans les environnements à fil d'exécution unique, il est préférable de ne pas utiliser ce contexte du tout. Créez plutôt simplement des contextes explicitement comme décrit ci-dessous.

Les valeurs par défaut sont @code{Context.prec}=@code{28}, @code{Context.rounding}=@ref{25c2,,ROUND_HALF_EVEN} et les interruptions sont activées pour @ref{25cb,,Overflow}, @ref{108c,,InvalidOperation} et @ref{25c7,,DivisionByZero}.
@end deffn

En plus des trois contextes fournis, de nouveaux contextes peuvent être créés avec le constructeur @ref{1091,,Context}.

@geindex Context (classe dans decimal)
@anchor{library/decimal decimal Context}@anchor{1091}
@deffn {Classe} decimal.Context (prec=None, rounding=None, Emin=None, Emax=None, capitals=None, clamp=None, flags=None, traps=None)

Crée un nouveau contexte. Si un champ n'est pas spécifié ou est @ref{660,,None}, les valeurs par défaut sont copiées à partir du @ref{1089,,DefaultContext}. Si le champ `flags' n'est pas spécifié ou est @ref{660,,None}, tous les indicateurs sont effacés.

`prec' est un entier compris dans la plage [@code{1}, @ref{2607,,MAX_PREC}] qui définit la précision des opérations arithmétiques dans le contexte.

L'option `rounding' est l'une des constantes répertoriées dans la section @ref{2608,,Modes d'arrondi}.

Les champs `traps' et `flags' répertorient tous les signaux à définir. En général, les nouveaux contextes ne doivent qu'activer des surveillances et laisser les drapeaux baissés.

Les champs `Emin' et `Emax' sont des entiers spécifiant les valeurs limites autorisées pour les exposants. `Emin' doit être dans [@ref{2609,,MIN_EMIN}, @code{0}], `Emax' dans la plage [@code{0}, @ref{260a,,MAX_EMAX}].

Le champ `capitals' est soit @code{0} soit @code{1} (la valeur par défaut). S'il est défini à @code{1}, les exposants sont imprimés avec un @code{E} majuscule ; sinon, un @code{e} minuscule est utilisé : @code{Decimal('6.02e+23')}.

Le champ `clamp' est soit @code{0} (la valeur par défaut), soit @code{1}. S'il est défini à @code{1}, l'exposant @code{e} d'une instance @ref{29a,,Decimal} représentable dans ce contexte est strictement limité à la plage @code{Emin - prec + 1 <= e <= Emax - prec + 1}. Si `clamp' est @code{0} alors une condition plus faible est vraie : l'exposant ajusté de l'instance @ref{29a,,Decimal} est au plus @code{Emax}. Lorsque `clamp' vaut @code{1}, un grand nombre normal voit, si possible, son exposant réduit et un nombre correspondant de zéros ajouté à sa mantisse, afin de s'adapter aux contraintes d'exposant ; cela préserve la valeur du nombre mais perd des informations sur les zéros significatifs. Par exemple :

@example
>>> Context(prec=6, Emax=999, clamp=1).create_decimal('1.23e999')
Decimal('1.23000E+999')
@end example

Une valeur `clamp' de @code{1} permet la compatibilité avec les formats d'échange décimaux à largeur fixe spécifiés dans la norme IEEE 754.

La classe @ref{1091,,Context} définit plusieurs méthodes à usage général ainsi qu'un grand nombre de méthodes permettant de faire de l'arithmétique directement dans un contexte donné. De plus, pour chacune des méthodes @ref{29a,,Decimal} décrites ci-dessus (à l'exception des méthodes @ref{25d3,,adjusted()} et @ref{25d4,,as_tuple()}), il existe une méthode @ref{1091,,Context} correspondante. Par exemple, pour une instance @ref{1091,,Context} @code{C} et une instance @ref{29a,,Decimal} @code{x}, @code{C.exp(x)} est équivalent à @code{x.exp(context=C)}. Chaque méthode @ref{1091,,Context} accepte un entier Python (une instance de @ref{254,,int}) partout où une instance Decimal est acceptée.

@geindex clear_flags() (méthode decimal.Context)
@anchor{library/decimal decimal Context clear_flags}@anchor{25d0}
@deffn {Méthode} clear_flags ()

Réinitialise tous les drapeaux à @code{0}.
@end deffn

@geindex clear_traps() (méthode decimal.Context)
@anchor{library/decimal decimal Context clear_traps}@anchor{260b}
@deffn {Méthode} clear_traps ()

Réinitialise toutes les surveillances à @code{0}.


Ajouté dans la version 3.3.

@end deffn

@geindex copy() (méthode decimal.Context)
@anchor{library/decimal decimal Context copy}@anchor{260c}
@deffn {Méthode} copy ()

Renvoie une copie du contexte.
@end deffn

@geindex copy_decimal() (méthode decimal.Context)
@anchor{library/decimal decimal Context copy_decimal}@anchor{260d}
@deffn {Méthode} copy_decimal (num)

Renvoie une copie de l'instance @code{Decimal} `num'.
@end deffn

@geindex create_decimal() (méthode decimal.Context)
@anchor{library/decimal decimal Context create_decimal}@anchor{108d}
@deffn {Méthode} create_decimal (num)

Crée une nouvelle instance Decimal à partir de `num' mais en utilisant `self' comme contexte. Contrairement au constructeur @ref{29a,,Decimal}, la précision du contexte, la méthode d'arrondi, les indicateurs et les surveillances sont appliqués à la conversion.

C'est utile car les constantes sont souvent données avec une précision supérieure à celle requise par l'application. Un autre avantage est que l’arrondi élimine immédiatement les effets involontaires des chiffres au-delà de la précision actuelle. Dans l'exemple suivant, l'utilisation d'entrées non arrondies signifie que l'ajout de zéro à une somme peut modifier le résultat :

@example
>>> getcontext().prec = 3
>>> Decimal('3.4445') + Decimal('1.0023')
Decimal('4.45')
>>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
Decimal('4.44')
@end example

Cette méthode implémente l'opération `to-number' de la spécification IBM. Si l’argument est une chaîne, aucun espace ou trait de soulignement de début ou de fin n’est autorisé.
@end deffn

@geindex create_decimal_from_float() (méthode decimal.Context)
@anchor{library/decimal decimal Context create_decimal_from_float}@anchor{260e}
@deffn {Méthode} create_decimal_from_float (f)

Crée une nouvelle instance Decimal à partir d'un `float' `f' mais en arrondissant en utilisant `self' comme contexte. Contrairement à la méthode de classe @ref{11e1,,Decimal.from_float()}, la précision du contexte, la méthode d'arrondi, les indicateurs et les surveillances sont appliqués à la conversion.

@example
>>> context = Context(prec=5, rounding=ROUND_DOWN)
>>> context.create_decimal_from_float(math.pi)
Decimal('3.1415')
>>> context = Context(prec=5, traps=[Inexact])
>>> context.create_decimal_from_float(math.pi)
Traceback (most recent call last):
    ...
decimal.Inexact: None
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex Etiny() (méthode decimal.Context)
@anchor{library/decimal decimal Context Etiny}@anchor{25f9}
@deffn {Méthode} Etiny ()

Renvoie une valeur égale à @code{Emin - prec + 1} qui est la valeur minimale de l'exposant pour les résultats avec dépassement inférieur. Lorsqu'un dépassement inférieur se produit, l'exposant est défini sur @ref{25f9,,Etiny}.
@end deffn

@geindex Etop() (méthode decimal.Context)
@anchor{library/decimal decimal Context Etop}@anchor{260f}
@deffn {Méthode} Etop ()

Renvoie une valeur égale à @code{Emax - prec + 1}.
@end deffn

L'approche habituelle pour travailler avec des décimaux consiste à créer des instances @ref{29a,,Decimal}, puis à appliquer des opérations arithmétiques qui ont lieu dans le contexte actuel du fil d'exécution actif. Une approche alternative consiste à utiliser des méthodes contextuelles pour calculer dans un contexte spécifique. Les méthodes sont similaires à celles de la classe @ref{29a,,Decimal} et ne sont décrites que brièvement ici.

@geindex abs() (méthode decimal.Context)
@anchor{library/decimal decimal Context abs}@anchor{2610}
@deffn {Méthode} abs (x)

Renvoie la valeur absolue de `x'.
@end deffn

@geindex add() (méthode decimal.Context)
@anchor{library/decimal decimal Context add}@anchor{2611}
@deffn {Méthode} add (x, y)

Renvoie la somme de `x' et `y'.
@end deffn

@geindex canonical() (méthode decimal.Context)
@anchor{library/decimal decimal Context canonical}@anchor{12e5}
@deffn {Méthode} canonical (x)

Renvoie l'objet Decimal `x' lui-même.
@end deffn

@geindex compare() (méthode decimal.Context)
@anchor{library/decimal decimal Context compare}@anchor{2612}
@deffn {Méthode} compare (x, y)

Compare `x' et `y' numériquement.
@end deffn

@geindex compare_signal() (méthode decimal.Context)
@anchor{library/decimal decimal Context compare_signal}@anchor{2613}
@deffn {Méthode} compare_signal (x, y)

Compare numériquement les valeurs des deux opérandes.
@end deffn

@geindex compare_total() (méthode decimal.Context)
@anchor{library/decimal decimal Context compare_total}@anchor{2614}
@deffn {Méthode} compare_total (x, y)

Compare deux opérandes en utilisant leur représentation abstraite.
@end deffn

@geindex compare_total_mag() (méthode decimal.Context)
@anchor{library/decimal decimal Context compare_total_mag}@anchor{2615}
@deffn {Méthode} compare_total_mag (x, y)

Compare deux opérandes en utilisant leur représentation abstraite, en ignorant le signe.
@end deffn

@geindex copy_abs() (méthode decimal.Context)
@anchor{library/decimal decimal Context copy_abs}@anchor{2616}
@deffn {Méthode} copy_abs (x)

Renvoie une copie de `x' avec le signe à 0 (c.-à-d. positif).
@end deffn

@geindex copy_negate() (méthode decimal.Context)
@anchor{library/decimal decimal Context copy_negate}@anchor{2617}
@deffn {Méthode} copy_negate (x)

Renvoie une copie de `x' mais de signe opposé.
@end deffn

@geindex copy_sign() (méthode decimal.Context)
@anchor{library/decimal decimal Context copy_sign}@anchor{2618}
@deffn {Méthode} copy_sign (x, y)

Copie le signe de `y' vers `x'.
@end deffn

@geindex divide() (méthode decimal.Context)
@anchor{library/decimal decimal Context divide}@anchor{2619}
@deffn {Méthode} divide (x, y)

Renvoie `x' divisé par `y'.
@end deffn

@geindex divide_int() (méthode decimal.Context)
@anchor{library/decimal decimal Context divide_int}@anchor{261a}
@deffn {Méthode} divide_int (x, y)

Renvoie `x' divisé par `y', tronqué comme entier.
@end deffn

@geindex divmod() (méthode decimal.Context)
@anchor{library/decimal decimal Context divmod}@anchor{261b}
@deffn {Méthode} divmod (x, y)

Renvoie la partie entière de la division entre deux nombres.
@end deffn

@geindex exp() (méthode decimal.Context)
@anchor{library/decimal decimal Context exp}@anchor{261c}
@deffn {Méthode} exp (x)

Renvoie @code{e ** x}.
@end deffn

@geindex fma() (méthode decimal.Context)
@anchor{library/decimal decimal Context fma}@anchor{261d}
@deffn {Méthode} fma (x, y, z)

Renvoie `x' multiplié par `y', plus `z'.
@end deffn

@geindex is_canonical() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_canonical}@anchor{12e6}
@deffn {Méthode} is_canonical (x)

Renvoie @code{True} si `x' est canonique ; @code{False} sinon.
@end deffn

@geindex is_finite() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_finite}@anchor{261e}
@deffn {Méthode} is_finite (x)

Renvoie @code{True} si `x' est fini ; @code{False} sinon.
@end deffn

@geindex is_infinite() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_infinite}@anchor{261f}
@deffn {Méthode} is_infinite (x)

Renvoie @code{True} si `x' est infini et @code{False} sinon.
@end deffn

@geindex is_nan() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_nan}@anchor{2620}
@deffn {Méthode} is_nan (x)

Renvoie @code{True} si `x' est un `NaN' (silencieux ou signalétique), @code{False} sinon.
@end deffn

@geindex is_normal() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_normal}@anchor{2621}
@deffn {Méthode} is_normal (x)

Renvoie @code{True} si `x' est un nombre normal ; @code{False} sinon.
@end deffn

@geindex is_qnan() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_qnan}@anchor{2622}
@deffn {Méthode} is_qnan (x)

Renvoie @code{True} si `x' est un `NaN' silencieux, @code{False} sinon.
@end deffn

@geindex is_signed() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_signed}@anchor{2623}
@deffn {Méthode} is_signed (x)

Renvoie @code{True} si `x' est négatif et @code{False} sinon.
@end deffn

@geindex is_snan() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_snan}@anchor{2624}
@deffn {Méthode} is_snan (x)

Renvoie @code{True} si `x' est un `NaN' signalétique, @code{False} sinon.
@end deffn

@geindex is_subnormal() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_subnormal}@anchor{2625}
@deffn {Méthode} is_subnormal (x)

Renvoie @code{True} si `x' est est inférieur à la valeur minimale représentable ; sinon, renvoie @code{False}.
@end deffn

@geindex is_zero() (méthode decimal.Context)
@anchor{library/decimal decimal Context is_zero}@anchor{2626}
@deffn {Méthode} is_zero (x)

Renvoie @code{True} si `x' est un zéro et @code{False} sinon.
@end deffn

@geindex ln() (méthode decimal.Context)
@anchor{library/decimal decimal Context ln}@anchor{2627}
@deffn {Méthode} ln (x)

Renvoie le logarithme naturel (en base e) de `x'.
@end deffn

@geindex log10() (méthode decimal.Context)
@anchor{library/decimal decimal Context log10}@anchor{2628}
@deffn {Méthode} log10 (x)

Renvoie le logarithme en base 10 de `x'.
@end deffn

@geindex logb() (méthode decimal.Context)
@anchor{library/decimal decimal Context logb}@anchor{2629}
@deffn {Méthode} logb (x)

Renvoie l'exposant correspondant du chiffre de poids fort de la mantisse de l'opérande.
@end deffn

@geindex logical_and() (méthode decimal.Context)
@anchor{library/decimal decimal Context logical_and}@anchor{262a}
@deffn {Méthode} logical_and (x, y)

Applique l'opération logique `ET' entre les chiffres de chaque opérande.
@end deffn

@geindex logical_invert() (méthode decimal.Context)
@anchor{library/decimal decimal Context logical_invert}@anchor{262b}
@deffn {Méthode} logical_invert (x)

Inverse tous les chiffres de `x'.
@end deffn

@geindex logical_or() (méthode decimal.Context)
@anchor{library/decimal decimal Context logical_or}@anchor{262c}
@deffn {Méthode} logical_or (x, y)

Applique l'opération logique `OU' entre les chiffres de chaque opérande.
@end deffn

@geindex logical_xor() (méthode decimal.Context)
@anchor{library/decimal decimal Context logical_xor}@anchor{262d}
@deffn {Méthode} logical_xor (x, y)

Applique l'opération logique `OU EXCLUSIF' entre les chiffres de chaque opérande.
@end deffn

@geindex max() (méthode decimal.Context)
@anchor{library/decimal decimal Context max}@anchor{262e}
@deffn {Méthode} max (x, y)

Renvoie le maximum entre les deux valeurs numériques.
@end deffn

@geindex max_mag() (méthode decimal.Context)
@anchor{library/decimal decimal Context max_mag}@anchor{262f}
@deffn {Méthode} max_mag (x, y)

Compare les valeurs numériquement en ignorant leur signe.
@end deffn

@geindex min() (méthode decimal.Context)
@anchor{library/decimal decimal Context min}@anchor{2630}
@deffn {Méthode} min (x, y)

Compare numériquement deux valeurs et renvoie le minimum.
@end deffn

@geindex min_mag() (méthode decimal.Context)
@anchor{library/decimal decimal Context min_mag}@anchor{2631}
@deffn {Méthode} min_mag (x, y)

Compare les valeurs numériquement en ignorant leur signe.
@end deffn

@geindex minus() (méthode decimal.Context)
@anchor{library/decimal decimal Context minus}@anchor{2632}
@deffn {Méthode} minus (x)

Correspond à l’opérateur unaire préfixé « moins » en Python.
@end deffn

@geindex multiply() (méthode decimal.Context)
@anchor{library/decimal decimal Context multiply}@anchor{2633}
@deffn {Méthode} multiply (x, y)

Renvoie la multiplication de `x' avec `y'.
@end deffn

@geindex next_minus() (méthode decimal.Context)
@anchor{library/decimal decimal Context next_minus}@anchor{2634}
@deffn {Méthode} next_minus (x)

Renvoie le plus grand nombre représentable inférieur à `x'.
@end deffn

@geindex next_plus() (méthode decimal.Context)
@anchor{library/decimal decimal Context next_plus}@anchor{2635}
@deffn {Méthode} next_plus (x)

Renvoie le plus petit nombre représentable supérieur à `x'.
@end deffn

@geindex next_toward() (méthode decimal.Context)
@anchor{library/decimal decimal Context next_toward}@anchor{2636}
@deffn {Méthode} next_toward (x, y)

Renvoie le nombre le plus proche de `x', en direction de `y'.
@end deffn

@geindex normalize() (méthode decimal.Context)
@anchor{library/decimal decimal Context normalize}@anchor{2637}
@deffn {Méthode} normalize (x)

Réduit `x' à sa forme la plus simple.
@end deffn

@geindex number_class() (méthode decimal.Context)
@anchor{library/decimal decimal Context number_class}@anchor{2638}
@deffn {Méthode} number_class (x)

Renvoie une indication de la classe de `x'.
@end deffn

@geindex plus() (méthode decimal.Context)
@anchor{library/decimal decimal Context plus}@anchor{2639}
@deffn {Méthode} plus (x)

Correspond à l'opérateur unaire préfixé « plus » en Python. Cette opération applique la précision du contexte et l'arrondi, ce n'est donc `pas' une opération d'identité.
@end deffn

@geindex power() (méthode decimal.Context)
@anchor{library/decimal decimal Context power}@anchor{263a}
@deffn {Méthode} power (x, y, modulo=None)

Renvoie @code{x} à la puissance @code{y}, réduit modulo @code{modulo} si celui-ci est donné.

Avec deux arguments, calcule @code{x**y}. Si @code{x} est négatif alors @code{y} doit être entier. Le résultat est inexact à moins que @code{y} soit entier et que le résultat soit fini et puisse être exprimé exactement en @code{precision} chiffres. Le mode d'arrondi du contexte est utilisé. Les résultats sont toujours correctement arrondis à la manière de Python.

@code{Decimal(0) ** Decimal(0)} donne @code{InvalidOperation} et, si @code{InvalidOperation} n'est pas surveillé, cela donne @code{Decimal('NaN')}.


Modifié dans la version 3.3: le module C calcule @ref{263a,,power()} en termes de fonctions @ref{261c,,exp()} et @ref{2627,,ln()} correctement arrondies. Le résultat est bien défini mais seulement « presque toujours correctement arrondi ».


Avec trois arguments, calcule @code{(x**y) % modulo}. Pour la forme à trois arguments, les restrictions suivantes sur les arguments s'appliquent :


@itemize -

@item 
les trois arguments doivent être entiers ;

@item 
@code{y} ne doit pas être négatif ;

@item 
au moins l'un de @code{x} ou @code{y} doit être différent de zéro ;

@item 
@code{modulo} doit être différent de zéro et avoir au plus @code{precision} chiffres.
@end itemize

La valeur résultant de @code{Context.power(x, y, modulo)} est égale à la valeur qui serait obtenue en calculant @code{(x**y) % modulo} avec une précision illimitée, mais est calculée plus efficacement. L'exposant du résultat est zéro, quels que soient les exposants de @code{x}, @code{y} et @code{modulo}. Le résultat est toujours exact.
@end deffn

@geindex quantize() (méthode decimal.Context)
@anchor{library/decimal decimal Context quantize}@anchor{263b}
@deffn {Méthode} quantize (x, y)

Renvoie une valeur égale à `x' (arrondie), ayant l'exposant de `y'.
@end deffn

@geindex radix() (méthode decimal.Context)
@anchor{library/decimal decimal Context radix}@anchor{263c}
@deffn {Méthode} radix ()

Renvoie 10 car c'est `Decimal', :)
@end deffn

@geindex remainder() (méthode decimal.Context)
@anchor{library/decimal decimal Context remainder}@anchor{263d}
@deffn {Méthode} remainder (x, y)

Renvoie le reste de la division entière.

Le signe du résultat, s'il est différent de zéro, est le même que celui du dividende initial.
@end deffn

@geindex remainder_near() (méthode decimal.Context)
@anchor{library/decimal decimal Context remainder_near}@anchor{263e}
@deffn {Méthode} remainder_near (x, y)

Renvoie @code{x - y * n}, où `n' est l'entier le plus proche de la valeur exacte de @code{x / y} (si le résultat est 0 alors son signe est le signe de `x').
@end deffn

@geindex rotate() (méthode decimal.Context)
@anchor{library/decimal decimal Context rotate}@anchor{263f}
@deffn {Méthode} rotate (x, y)

Renvoie une copie pivotée de `x', `y' fois.
@end deffn

@geindex same_quantum() (méthode decimal.Context)
@anchor{library/decimal decimal Context same_quantum}@anchor{2640}
@deffn {Méthode} same_quantum (x, y)

Renvoie @code{True} si les deux opérandes ont le même exposant.
@end deffn

@geindex scaleb() (méthode decimal.Context)
@anchor{library/decimal decimal Context scaleb}@anchor{2641}
@deffn {Méthode} scaleb (x, y)

Renvoie le premier opérande après avoir ajouté la deuxième valeur à son `exp'.
@end deffn

@geindex shift() (méthode decimal.Context)
@anchor{library/decimal decimal Context shift}@anchor{2642}
@deffn {Méthode} shift (x, y)

Renvoie une copie décalée de `x', `y' fois.
@end deffn

@geindex sqrt() (méthode decimal.Context)
@anchor{library/decimal decimal Context sqrt}@anchor{2643}
@deffn {Méthode} sqrt (x)

Renvoie la racine carrée d'un nombre non négatif avec la précision donnée par le contexte.
@end deffn

@geindex subtract() (méthode decimal.Context)
@anchor{library/decimal decimal Context subtract}@anchor{2644}
@deffn {Méthode} subtract (x, y)

Renvoie la différence entre `x' et `y'.
@end deffn

@geindex to_eng_string() (méthode decimal.Context)
@anchor{library/decimal decimal Context to_eng_string}@anchor{2645}
@deffn {Méthode} to_eng_string (x)

Convertir en chaîne, en utilisant la notation ingénieur si un exposant est nécessaire.

La notation ingénieur possède un exposant qui est un multiple de 3. Cela peut laisser jusqu'à 3 chiffres à gauche de la décimale et peut nécessiter l'ajout d'un ou de deux zéros à la fin.
@end deffn

@geindex to_integral_exact() (méthode decimal.Context)
@anchor{library/decimal decimal Context to_integral_exact}@anchor{2646}
@deffn {Méthode} to_integral_exact (x)

Arrondit à un entier.
@end deffn

@geindex to_sci_string() (méthode decimal.Context)
@anchor{library/decimal decimal Context to_sci_string}@anchor{2647}
@deffn {Méthode} to_sci_string (x)

Convertit un nombre en chaîne en utilisant la notation scientifique.
@end deffn
@end deffn

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Constantes<4>,Modes d'arrondi,Objets de contexte,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal constants}@anchor{2648}@anchor{library/decimal decimal-rounding-modes}@anchor{2649}
@subsubsection Constantes


Les constantes de cette section ne sont pertinentes que pour le module C. Elles sont aussi incluses pour la compatibilité dans la version en Python pur.


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@tab

32-bit

@tab

64-bit

@item

@geindex MAX_PREC (dans le module decimal)
@anchor{library/decimal decimal MAX_PREC}@anchor{2607}
@deffn {Données} decimal.MAX_PREC
@end deffn

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@geindex MAX_EMAX (dans le module decimal)
@anchor{library/decimal decimal MAX_EMAX}@anchor{260a}
@deffn {Données} decimal.MAX_EMAX
@end deffn

@tab

@code{425000000}

@tab

@code{999999999999999999}

@item

@geindex MIN_EMIN (dans le module decimal)
@anchor{library/decimal decimal MIN_EMIN}@anchor{2609}
@deffn {Données} decimal.MIN_EMIN
@end deffn

@tab

@code{-425000000}

@tab

@code{-999999999999999999}

@item

@geindex MIN_ETINY (dans le module decimal)
@anchor{library/decimal decimal MIN_ETINY}@anchor{264a}
@deffn {Données} decimal.MIN_ETINY
@end deffn

@tab

@code{-849999999}

@tab

@code{-1999999999999999997}

@end multitable


@geindex HAVE_THREADS (dans le module decimal)
@anchor{library/decimal decimal HAVE_THREADS}@anchor{1087}
@deffn {Données} decimal.HAVE_THREADS

La valeur est @code{True}. Déprécié, parce que maintenant Python possède toujours des fils d'exécution.


Obsolète depuis la version 3.9.

@end deffn

@geindex HAVE_CONTEXTVAR (dans le module decimal)
@anchor{library/decimal decimal HAVE_CONTEXTVAR}@anchor{1cff}
@deffn {Données} decimal.HAVE_CONTEXTVAR

The default value is @code{True}. If Python is @ref{1cfe,,configured using the --without-decimal-contextvar option},
the C version uses a thread-local rather than a coroutine-local context and the value
is @code{False}.  This is slightly faster in some nested context scenarios.


Ajouté dans la version 3.8.3.

@end deffn

@node Modes d'arrondi,Signaux,Constantes<4>,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal rounding-modes}@anchor{2608}
@subsubsection Modes d'arrondi


@geindex ROUND_CEILING (dans le module decimal)
@anchor{library/decimal decimal ROUND_CEILING}@anchor{25be}
@deffn {Données} decimal.ROUND_CEILING

Round towards @code{Infinity}.
@end deffn

@geindex ROUND_DOWN (dans le module decimal)
@anchor{library/decimal decimal ROUND_DOWN}@anchor{25bf}
@deffn {Données} decimal.ROUND_DOWN

Round towards zero.
@end deffn

@geindex ROUND_FLOOR (dans le module decimal)
@anchor{library/decimal decimal ROUND_FLOOR}@anchor{25c0}
@deffn {Données} decimal.ROUND_FLOOR

Round towards @code{-Infinity}.
@end deffn

@geindex ROUND_HALF_DOWN (dans le module decimal)
@anchor{library/decimal decimal ROUND_HALF_DOWN}@anchor{25c1}
@deffn {Données} decimal.ROUND_HALF_DOWN

Round to nearest with ties going towards zero.
@end deffn

@geindex ROUND_HALF_EVEN (dans le module decimal)
@anchor{library/decimal decimal ROUND_HALF_EVEN}@anchor{25c2}
@deffn {Données} decimal.ROUND_HALF_EVEN

Round to nearest with ties going to nearest even integer.
@end deffn

@geindex ROUND_HALF_UP (dans le module decimal)
@anchor{library/decimal decimal ROUND_HALF_UP}@anchor{25c3}
@deffn {Données} decimal.ROUND_HALF_UP

Round to nearest with ties going away from zero.
@end deffn

@geindex ROUND_UP (dans le module decimal)
@anchor{library/decimal decimal ROUND_UP}@anchor{25c4}
@deffn {Données} decimal.ROUND_UP

Round away from zero.
@end deffn

@geindex ROUND_05UP (dans le module decimal)
@anchor{library/decimal decimal ROUND_05UP}@anchor{25c5}
@deffn {Données} decimal.ROUND_05UP

Round away from zero if last digit after rounding towards zero would have
been 0 or 5; otherwise round towards zero.
@end deffn

@node Signaux,Floating-Point Notes,Modes d'arrondi,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-signals}@anchor{264b}@anchor{library/decimal signals}@anchor{264c}
@subsubsection Signaux


Signals represent conditions that arise during computation. Each corresponds to
one context flag and one context trap enabler.

The context flag is set whenever the condition is encountered. After the
computation, flags may be checked for informational purposes (for instance, to
determine whether a computation was exact). After checking the flags, be sure to
clear all flags before starting the next computation.

If the context's trap enabler is set for the signal, then the condition causes a
Python exception to be raised.  For example, if the @ref{25c7,,DivisionByZero} trap
is set, then a @ref{25c7,,DivisionByZero} exception is raised upon encountering the
condition.

@geindex Clamped (classe dans decimal)
@anchor{library/decimal decimal Clamped}@anchor{25c6}
@deffn {Classe} decimal.Clamped

Altered an exponent to fit representation constraints.

Typically, clamping occurs when an exponent falls outside the context's
@code{Emin} and @code{Emax} limits.  If possible, the exponent is reduced to
fit by adding zeros to the coefficient.
@end deffn

@geindex DecimalException (classe dans decimal)
@anchor{library/decimal decimal DecimalException}@anchor{264d}
@deffn {Classe} decimal.DecimalException

Base class for other signals and a subclass of @ref{220d,,ArithmeticError}.
@end deffn

@geindex DivisionByZero (classe dans decimal)
@anchor{library/decimal decimal DivisionByZero}@anchor{25c7}
@deffn {Classe} decimal.DivisionByZero

Signals the division of a non-infinite number by zero.

Can occur with division, modulo division, or when raising a number to a negative
power.  If this signal is not trapped, returns @code{Infinity} or
@code{-Infinity} with the sign determined by the inputs to the calculation.
@end deffn

@geindex Inexact (classe dans decimal)
@anchor{library/decimal decimal Inexact}@anchor{25c8}
@deffn {Classe} decimal.Inexact

Indicates that rounding occurred and the result is not exact.

Signals when non-zero digits were discarded during rounding. The rounded result
is returned.  The signal flag or trap is used to detect when results are
inexact.
@end deffn

@geindex InvalidOperation (classe dans decimal)
@anchor{library/decimal decimal InvalidOperation}@anchor{108c}
@deffn {Classe} decimal.InvalidOperation

An invalid operation was performed.

Indicates that an operation was requested that does not make sense. If not
trapped, returns @code{NaN}.  Possible causes include:

@example
Infinity - Infinity
0 * Infinity
Infinity / Infinity
x % 0
Infinity % x
sqrt(-x) and x > 0
0 ** 0
x ** (non-integer)
x ** Infinity
@end example
@end deffn

@geindex Overflow (classe dans decimal)
@anchor{library/decimal decimal Overflow}@anchor{25cb}
@deffn {Classe} decimal.Overflow

Débordement numérique.

Indicates the exponent is larger than @code{Context.Emax} after rounding has
occurred.  If not trapped, the result depends on the rounding mode, either
pulling inward to the largest representable finite number or rounding outward
to @code{Infinity}.  In either case, @ref{25c8,,Inexact} and @ref{25c9,,Rounded}
are also signaled.
@end deffn

@geindex Rounded (classe dans decimal)
@anchor{library/decimal decimal Rounded}@anchor{25c9}
@deffn {Classe} decimal.Rounded

Rounding occurred though possibly no information was lost.

Signaled whenever rounding discards digits; even if those digits are zero
(such as rounding @code{5.00} to @code{5.0}).  If not trapped, returns
the result unchanged.  This signal is used to detect loss of significant
digits.
@end deffn

@geindex Subnormal (classe dans decimal)
@anchor{library/decimal decimal Subnormal}@anchor{25ca}
@deffn {Classe} decimal.Subnormal

Exponent was lower than @code{Emin} prior to rounding.

Occurs when an operation result is subnormal (the exponent is too small). If
not trapped, returns the result unchanged.
@end deffn

@geindex Underflow (classe dans decimal)
@anchor{library/decimal decimal Underflow}@anchor{25cc}
@deffn {Classe} decimal.Underflow

Numerical underflow with result rounded to zero.

Occurs when a subnormal result is pushed to zero by rounding. @ref{25c8,,Inexact}
and @ref{25ca,,Subnormal} are also signaled.
@end deffn

@geindex FloatOperation (classe dans decimal)
@anchor{library/decimal decimal FloatOperation}@anchor{1086}
@deffn {Classe} decimal.FloatOperation

Enable stricter semantics for mixing floats and Decimals.

If the signal is not trapped (default), mixing floats and Decimals is
permitted in the @ref{29a,,Decimal} constructor,
@ref{108d,,create_decimal()} and all comparison operators.
Both conversion and comparisons are exact. Any occurrence of a mixed
operation is silently recorded by setting @ref{1086,,FloatOperation} in the
context flags. Explicit conversions with @ref{11e1,,from_float()}
or @ref{260e,,create_decimal_from_float()} do not set the flag.

Otherwise (the signal is trapped), only equality comparisons and explicit
conversions are silent. All other mixed operations raise @ref{1086,,FloatOperation}.
@end deffn

The following table summarizes the hierarchy of signals:

@example
exceptions.ArithmeticError(exceptions.Exception)
    DecimalException
        Clamped
        DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
        Inexact
            Overflow(Inexact, Rounded)
            Underflow(Inexact, Rounded, Subnormal)
        InvalidOperation
        Rounded
        Subnormal
        FloatOperation(DecimalException, exceptions.TypeError)
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Floating-Point Notes,Working with threads,Signaux,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-notes}@anchor{264e}@anchor{library/decimal floating-point-notes}@anchor{264f}
@subsubsection Floating-Point Notes


@menu
* Mitigating round-off error with increased precision:: 
* Special values:: 

@end menu

@node Mitigating round-off error with increased precision,Special values,,Floating-Point Notes
@anchor{library/decimal mitigating-round-off-error-with-increased-precision}@anchor{2650}
@subsubsection Mitigating round-off error with increased precision


The use of decimal floating point eliminates decimal representation error
(making it possible to represent @code{0.1} exactly); however, some operations
can still incur round-off error when non-zero digits exceed the fixed precision.

The effects of round-off error can be amplified by the addition or subtraction
of nearly offsetting quantities resulting in loss of significance.  Knuth
provides two instructive examples where rounded floating-point arithmetic with
insufficient precision causes the breakdown of the associative and distributive
properties of addition:

@example
# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
>>> getcontext().prec = 8

>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.5111111')
>>> u + (v + w)
Decimal('10')

>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.01')
>>> u * (v+w)
Decimal('0.0060000')
@end example

The @ref{36,,decimal} module makes it possible to restore the identities by
expanding the precision sufficiently to avoid loss of significance:

@example
>>> getcontext().prec = 20
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.51111111')
>>> u + (v + w)
Decimal('9.51111111')
>>>
>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.0060000')
>>> u * (v+w)
Decimal('0.0060000')
@end example

@node Special values,,Mitigating round-off error with increased precision,Floating-Point Notes
@anchor{library/decimal special-values}@anchor{2651}
@subsubsection Special values


The number system for the @ref{36,,decimal} module provides special values
including @code{NaN}, @code{sNaN}, @code{-Infinity}, @code{Infinity},
and two zeros, @code{+0} and @code{-0}.

Infinities can be constructed directly with:  @code{Decimal('Infinity')}. Also,
they can arise from dividing by zero when the @ref{25c7,,DivisionByZero} signal is
not trapped.  Likewise, when the @ref{25cb,,Overflow} signal is not trapped, infinity
can result from rounding beyond the limits of the largest representable number.

The infinities are signed (affine) and can be used in arithmetic operations
where they get treated as very large, indeterminate numbers.  For instance,
adding a constant to infinity gives another infinite result.

Some operations are indeterminate and return @code{NaN}, or if the
@ref{108c,,InvalidOperation} signal is trapped, raise an exception.  For example,
@code{0/0} returns @code{NaN} which means "not a number".  This variety of
@code{NaN} is quiet and, once created, will flow through other computations
always resulting in another @code{NaN}.  This behavior can be useful for a
series of computations that occasionally have missing inputs --- it allows the
calculation to proceed while flagging specific results as invalid.

A variant is @code{sNaN} which signals rather than remaining quiet after every
operation.  This is a useful return value when an invalid result needs to
interrupt a calculation for special handling.

The behavior of Python's comparison operators can be a little surprising where a
@code{NaN} is involved.  A test for equality where one of the operands is a
quiet or signaling @code{NaN} always returns @ref{b25,,False} (even when doing
@code{Decimal('NaN')==Decimal('NaN')}), while a test for inequality always returns
@ref{bfb,,True}.  An attempt to compare two Decimals using any of the @code{<},
@code{<=}, @code{>} or @code{>=} operators will raise the @ref{108c,,InvalidOperation} signal
if either operand is a @code{NaN}, and return @ref{b25,,False} if this signal is
not trapped.  Note that the General Decimal Arithmetic specification does not
specify the behavior of direct comparisons; these rules for comparisons
involving a @code{NaN} were taken from the IEEE 854 standard (see Table 3 in
section 5.7).  To ensure strict standards-compliance, use the @ref{25d6,,compare()}
and @ref{25d7,,compare_signal()} methods instead.

The signed zeros can result from calculations that underflow. They keep the sign
that would have resulted if the calculation had been carried out to greater
precision.  Since their magnitude is zero, both positive and negative zeros are
treated as equal and their sign is informational.

In addition to the two signed zeros which are distinct yet equal, there are
various representations of zero with differing precisions yet equivalent in
value.  This takes a bit of getting used to.  For an eye accustomed to
normalized floating-point representations, it is not immediately obvious that
the following calculation returns a value equal to zero:

@example
>>> 1 / Decimal('Infinity')
Decimal('0E-1000026')
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Working with threads,Cas pratiques,Floating-Point Notes,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-threads}@anchor{2652}@anchor{library/decimal working-with-threads}@anchor{2653}
@subsubsection Working with threads


The @ref{155c,,getcontext()} function accesses a different @ref{1091,,Context} object for
each thread.  Having separate thread contexts means that threads may make
changes (such as @code{getcontext().prec=10}) without interfering with other threads.

Likewise, the @ref{25cf,,setcontext()} function automatically assigns its target to
the current thread.

If @ref{25cf,,setcontext()} has not been called before @ref{155c,,getcontext()}, then
@ref{155c,,getcontext()} will automatically create a new context for use in the
current thread.

The new context is copied from a prototype context called `DefaultContext'. To
control the defaults so that each thread will use the same values throughout the
application, directly modify the `DefaultContext' object. This should be done
`before' any threads are started so that there won't be a race condition between
threads calling @ref{155c,,getcontext()}. For example:

@example
# Set applicationwide defaults for all threads about to be launched
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)

# Afterwards, the threads can be started
t1.start()
t2.start()
t3.start()
 . . .
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Cas pratiques,FAQ decimal,Working with threads,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-recipes}@anchor{2654}@anchor{library/decimal recipes}@anchor{2655}
@subsubsection Cas pratiques


Here are a few recipes that serve as utility functions and that demonstrate ways
to work with the @ref{29a,,Decimal} class:

@example
def moneyfmt(value, places=2, curr='@w{'}, sep=',', dp='.',
             pos='@w{'}, neg='-', trailneg='@w{'}):
    """Convert Decimal to a money formatted string.

    places:  required number of places after the decimal point
    curr:    optional currency symbol before the sign (may be blank)
    sep:     optional grouping separator (comma, period, space, or blank)
    dp:      decimal point indicator (comma or period)
             only specify as blank when places is zero
    pos:     optional sign for positive numbers: '+', space or blank
    neg:     optional sign for negative numbers: '-', '(', space or blank
    trailneg:optional trailing minus indicator:  '-', ')', space or blank

    >>> d = Decimal('-1234567.8901')
    >>> moneyfmt(d, curr='$')
    '-$1,234,567.89'
    >>> moneyfmt(d, places=0, sep='.', dp='@w{'}, neg='@w{'}, trailneg='-')
    '1.234.568-'
    >>> moneyfmt(d, curr='$', neg='(', trailneg=')')
    '($1,234,567.89)'
    >>> moneyfmt(Decimal(123456789), sep=' ')
    '123 456 789.00'
    >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
    '<0.02>'

    """
    q = Decimal(10) ** -places      # 2 places --> '0.01'
    sign, digits, exp = value.quantize(q).as_tuple()
    result = []
    digits = list(map(str, digits))
    build, next = result.append, digits.pop
    if sign:
        build(trailneg)
    for i in range(places):
        build(next() if digits else '0')
    if places:
        build(dp)
    if not digits:
        build('0')
    i = 0
    while digits:
        build(next())
        i += 1
        if i == 3 and digits:
            i = 0
            build(sep)
    build(curr)
    build(neg if sign else pos)
    return '@w{'}.join(reversed(result))

def pi():
    """Compute Pi to the current precision.

    >>> print(pi())
    3.141592653589793238462643383

    """
    getcontext().prec += 2  # extra digits for intermediate steps
    three = Decimal(3)      # substitute "three=3.0" for regular floats
    lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
    while s != lasts:
        lasts = s
        n, na = n+na, na+8
        d, da = d+da, da+32
        t = (t * n) / d
        s += t
    getcontext().prec -= 2
    return +s               # unary plus applies the new precision

def exp(x):
    """Return e raised to the power of x.  Result type matches input type.

    >>> print(exp(Decimal(1)))
    2.718281828459045235360287471
    >>> print(exp(Decimal(2)))
    7.389056098930650227230427461
    >>> print(exp(2.0))
    7.38905609893
    >>> print(exp(2+0j))
    (7.38905609893+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num = 0, 0, 1, 1, 1
    while s != lasts:
        lasts = s
        i += 1
        fact *= i
        num *= x
        s += num / fact
    getcontext().prec -= 2
    return +s

def cos(x):
    """Return the cosine of x as measured in radians.

    The Taylor series approximation works best for a small value of x.
    For larger values, first compute x = x % (2 * pi).

    >>> print(cos(Decimal('0.5')))
    0.8775825618903727161162815826
    >>> print(cos(0.5))
    0.87758256189
    >>> print(cos(0.5+0j))
    (0.87758256189+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
    while s != lasts:
        lasts = s
        i += 2
        fact *= i * (i-1)
        num *= x * x
        sign *= -1
        s += num / fact * sign
    getcontext().prec -= 2
    return +s

def sin(x):
    """Return the sine of x as measured in radians.

    The Taylor series approximation works best for a small value of x.
    For larger values, first compute x = x % (2 * pi).

    >>> print(sin(Decimal('0.5')))
    0.4794255386042030002732879352
    >>> print(sin(0.5))
    0.479425538604
    >>> print(sin(0.5+0j))
    (0.479425538604+0j)

    """
    getcontext().prec += 2
    i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
    while s != lasts:
        lasts = s
        i += 2
        fact *= i * (i-1)
        num *= x * x
        sign *= -1
        s += num / fact * sign
    getcontext().prec -= 2
    return +s
@end example

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node FAQ decimal,,Cas pratiques,decimal --- Decimal fixed-point and floating-point arithmetic
@anchor{library/decimal decimal-faq}@anchor{2656}@anchor{library/decimal id1}@anchor{2657}
@subsubsection FAQ `decimal'


Q. C'est fastidieux de taper @code{decimal.Decimal('1234.5')}. Y a-t-il un moyen de réduire la frappe quand on utilise l'interpréteur interactif ?

R. Certains utilisateurs abrègent le constructeur en une seule lettre :

@example
>>> D = decimal.Decimal
>>> D('1.23') + D('3.45')
Decimal('4.68')
@end example

Q. In a fixed-point application with two decimal places, some inputs have many
places and need to be rounded.  Others are not supposed to have excess digits
and need to be validated.  What methods should be used?

A. The @ref{1092,,quantize()} method rounds to a fixed number of decimal places. If
the @ref{25c8,,Inexact} trap is set, it is also useful for validation:

@example
>>> TWOPLACES = Decimal(10) ** -2       # same as Decimal('0.01')
@end example

@example
>>> # Round to two places
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')
@end example

@example
>>> # Validate that a number does not exceed two places
>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Decimal('3.21')
@end example

@example
>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
   ...
Inexact: None
@end example

Q. Une fois que mes entrées sont à deux décimales valides, comment maintenir cet invariant dans l'application ?

R. Certaines opérations comme l'addition, la soustraction et la multiplication par un entier préservent automatiquement la virgule fixe. D'autres opérations, comme la division et la multiplication par des non-entiers, changent le nombre de décimales et doivent être suivies d'une étape @ref{1092,,quantize()} :

@example
>>> a = Decimal('102.72')           # Initial fixed-point values
>>> b = Decimal('3.17')
>>> a + b                           # Addition preserves fixed-point
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42                          # So does integer multiplication
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES)     # Must quantize non-integer multiplication
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES)     # And quantize division
Decimal('0.03')
@end example

Lors du développement d'applications en virgule fixe, il est pratique de définir des fonctions pour gérer cette étape de quantification par @ref{1092,,quantize()} :

@example
>>> def mul(x, y, fp=TWOPLACES):
...     return (x * y).quantize(fp)
...
>>> def div(x, y, fp=TWOPLACES):
...     return (x / y).quantize(fp)
@end example

@example
>>> mul(a, b)                       # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')
@end example

Q. There are many ways to express the same value.  The numbers @code{200},
@code{200.000}, @code{2E2}, and @code{.02E+4} all have the same value at
various precisions. Is there a way to transform them to a single recognizable
canonical value?

A. The @ref{25f7,,normalize()} method maps all equivalent values to a single
representative:

@example
>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
@end example

Q. When does rounding occur in a computation?

A. It occurs `after' the computation.  The philosophy of the decimal
specification is that numbers are considered exact and are created
independent of the current context.  They can even have greater
precision than current context.  Computations process with those
exact inputs and then rounding (or other context operations) is
applied to the `result' of the computation:

@example
>>> getcontext().prec = 5
>>> pi = Decimal('3.1415926535')   # More than 5 digits
>>> pi                             # All digits are retained
Decimal('3.1415926535')
>>> pi + 0                         # Rounded after an addition
Decimal('3.1416')
>>> pi - Decimal('0.00005')        # Subtract unrounded numbers, then round
Decimal('3.1415')
>>> pi + 0 - Decimal('0.00005').   # Intermediate values are rounded
Decimal('3.1416')
@end example

Q. Some decimal values always print with exponential notation.  Is there a way
to get a non-exponential representation?

A. For some values, exponential notation is the only way to express the number
of significant places in the coefficient.  For example, expressing
@code{5.0E+3} as @code{5000} keeps the value constant but cannot show the
original's two-place significance.

If an application does not care about tracking significance, it is easy to
remove the exponent and trailing zeroes, losing significance, but keeping the
value unchanged:

@example
>>> def remove_exponent(d):
...     return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
@end example

@example
>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')
@end example

Q. Is there a way to convert a regular float to a @ref{29a,,Decimal}?

A. Yes, any binary floating-point number can be exactly expressed as a
Decimal though an exact conversion may take more precision than intuition would
suggest:

@example
>>> Decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')
@end example

Q. Within a complex calculation, how can I make sure that I haven't gotten a
spurious result because of insufficient precision or rounding anomalies.

A. The decimal module makes it easy to test results.  A best practice is to
re-run calculations using greater precision and with various rounding modes.
Widely differing results indicate insufficient precision, rounding mode issues,
ill-conditioned inputs, or a numerically unstable algorithm.

Q. I noticed that context precision is applied to the results of operations but
not to the inputs.  Is there anything to watch out for when mixing values of
different precisions?

A. Yes.  The principle is that all values are considered to be exact and so is
the arithmetic on those values.  Only the results are rounded.  The advantage
for inputs is that "what you type is what you get".  A disadvantage is that the
results can look odd if you forget that the inputs haven't been rounded:

@example
>>> getcontext().prec = 3
>>> Decimal('3.104') + Decimal('2.104')
Decimal('5.21')
>>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
Decimal('5.20')
@end example

The solution is either to increase precision or to force rounding of inputs
using the unary plus operation:

@example
>>> getcontext().prec = 3
>>> +Decimal('1.23456789')      # unary plus triggers rounding
Decimal('1.23')
@end example

Alternatively, inputs can be rounded upon creation using the
@ref{108d,,Context.create_decimal()} method:

@example
>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')
@end example

Q. Is the CPython implementation fast for large numbers?

A. Yes.  In the CPython and PyPy3 implementations, the C/CFFI versions of
the decimal module integrate the high speed libmpdec@footnote{https://www.bytereef.org/mpdecimal/doc/libmpdec/index.html} library for
arbitrary precision correctly rounded decimal floating-point arithmetic @footnote{

Ajouté dans la version 3.3.

}.
@code{libmpdec} uses Karatsuba multiplication@footnote{https://en.wikipedia.org/wiki/Karatsuba_algorithm}
for medium-sized numbers and the Number Theoretic Transform@footnote{https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform}
for very large numbers.

The context must be adapted for exact arbitrary precision arithmetic. @code{Emin}
and @code{Emax} should always be set to the maximum values, @code{clamp}
should always be 0 (the default).  Setting @code{prec} requires some care.

The easiest approach for trying out bignum arithmetic is to use the maximum
value for @code{prec} as well @footnote{

Modifié dans la version 3.9: This approach now works for all exact results except for non-integer powers.

}:

@example
>>> setcontext(Context(prec=MAX_PREC, Emax=MAX_EMAX, Emin=MIN_EMIN))
>>> x = Decimal(2) ** 256
>>> x / 128
Decimal('904625697166532776746648320380374280103671755200316906558262375061821325312')
@end example

For inexact results, @ref{2607,,MAX_PREC} is far too large on 64-bit platforms and
the available memory will be insufficient:

@example
>>> Decimal(1) / 3
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
MemoryError
@end example

On systems with overallocation (e.g. Linux), a more sophisticated approach is to
adjust @code{prec} to the amount of available RAM.  Suppose that you have 8GB of
RAM and expect 10 simultaneous operands using a maximum of 500MB each:

@example
>>> import sys
>>>
>>> # Maximum number of digits for a single operand using 500MB in 8-byte words
>>> # with 19 digits per word (4-byte and 9 digits for the 32-bit build):
>>> maxdigits = 19 * ((500 * 1024**2) // 8)
>>>
>>> # Check that this works:
>>> c = Context(prec=maxdigits, Emax=MAX_EMAX, Emin=MIN_EMIN)
>>> c.traps[Inexact] = True
>>> setcontext(c)
>>>
>>> # Fill the available precision with nines:
>>> x = Decimal(0).logical_invert() * 9
>>> sys.getsizeof(x)
524288112
>>> x + 2
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  decimal.Inexact: [<class 'decimal.Inexact'>]
@end example

In general (and especially on systems without overallocation), it is recommended
to estimate even tighter bounds and set the @ref{25c8,,Inexact} trap if all calculations
are expected to be exact.

@node fractions --- Rational numbers,random --- Generate pseudo-random numbers,decimal --- Decimal fixed-point and floating-point arithmetic,Modules numériques et mathématiques
@anchor{library/fractions doc}@anchor{2658}@anchor{library/fractions fractions-rational-numbers}@anchor{2659}@anchor{library/fractions module-fractions}@anchor{5c}
@subsection @code{fractions} --- Rational numbers


@geindex module; fractions

`Code source :' Lib/fractions.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/fractions.py}


__________________________________________________________________


Le module @ref{5c,,fractions} fournit un support de l'arithmétique des nombres rationnels.

Une instance de `Fraction' peut être construite depuis une paire d'entiers, depuis un autre nombre rationnel, ou depuis une chaîne de caractères.

@geindex Fraction (classe dans fractions)
@anchor{library/fractions fractions Fraction}@anchor{1e4}
@deffn {Classe} fractions.Fraction (numerator=0, denominator=1)

@deffnx {Classe} fractions.Fraction (other_fraction)

@deffnx {Classe} fractions.Fraction (float)

@deffnx {Classe} fractions.Fraction (decimal)

@deffnx {Classe} fractions.Fraction (string)

The first version requires that `numerator' and `denominator' are instances
of @ref{129c,,numbers.Rational} and returns a new @ref{1e4,,Fraction} instance
with value @code{numerator/denominator}. If `denominator' is @code{0}, it
raises a @ref{932,,ZeroDivisionError}. The second version requires that
`other_fraction' is an instance of @ref{129c,,numbers.Rational} and returns a
@ref{1e4,,Fraction} instance with the same value.  The next two versions accept
either a @ref{2eb,,float} or a @ref{29a,,decimal.Decimal} instance, and return a
@ref{1e4,,Fraction} instance with exactly the same value.  Note that due to the
usual issues with binary floating point (see @ref{1c9d,,Floating-Point Arithmetic; Issues and Limitations}), the
argument to @code{Fraction(1.1)} is not exactly equal to 11/10, and so
@code{Fraction(1.1)} does `not' return @code{Fraction(11, 10)} as one might expect.
(But see the documentation for the @ref{265a,,limit_denominator()} method below.)
The last version of the constructor expects a string or unicode instance.
The usual form for this instance is:

@example
[sign] numerator ['/' denominator]
@end example

where the optional @code{sign} may be either '+' or '-' and
@code{numerator} and @code{denominator} (if present) are strings of
decimal digits (underscores may be used to delimit digits as with
integral literals in code).  In addition, any string that represents a finite
value and is accepted by the @ref{2eb,,float} constructor is also
accepted by the @ref{1e4,,Fraction} constructor.  In either form the
input string may also have leading and/or trailing whitespace.
Here are some examples:

@example
>>> from fractions import Fraction
>>> Fraction(16, -10)
Fraction(-8, 5)
>>> Fraction(123)
Fraction(123, 1)
>>> Fraction()
Fraction(0, 1)
>>> Fraction('3/7')
Fraction(3, 7)
>>> Fraction(' -3/7 ')
Fraction(-3, 7)
>>> Fraction('1.414213 \t\n')
Fraction(1414213, 1000000)
>>> Fraction('-.125')
Fraction(-1, 8)
>>> Fraction('7e-6')
Fraction(7, 1000000)
>>> Fraction(2.25)
Fraction(9, 4)
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)
>>> from decimal import Decimal
>>> Fraction(Decimal('1.1'))
Fraction(11, 10)
@end example

The @ref{1e4,,Fraction} class inherits from the abstract base class
@ref{129c,,numbers.Rational}, and implements all of the methods and
operations from that class.  @ref{1e4,,Fraction} instances are @ref{5fb,,hashable},
and should be treated as immutable.  In addition,
@ref{1e4,,Fraction} has the following properties and methods:


Modifié dans la version 3.2: Le constructeur de @ref{1e4,,Fraction} accepte maintenant des instances de @ref{2eb,,float} et @ref{29a,,decimal.Decimal}.



Modifié dans la version 3.9: The @ref{8fd,,math.gcd()} function is now used to normalize the `numerator'
and `denominator'. @ref{8fd,,math.gcd()} always returns an @ref{254,,int} type.
Previously, the GCD type depended on `numerator' and `denominator'.



Modifié dans la version 3.11: Underscores are now permitted when creating a @ref{1e4,,Fraction} instance
from a string, following 
@geindex Python Enhancement Proposals; PEP 515
PEP 515@footnote{https://peps.python.org/pep-0515/} rules.



Modifié dans la version 3.11: @ref{1e4,,Fraction} implements @code{__int__} now to satisfy
@code{typing.SupportsInt} instance checks.



Modifié dans la version 3.12: Space is allowed around the slash for string inputs: @code{Fraction('2 / 3')}.



Modifié dans la version 3.12: @ref{1e4,,Fraction} instances now support float-style formatting, with
presentation types @code{"e"}, @code{"E"}, @code{"f"}, @code{"F"}, @code{"g"}, @code{"G"}
and @code{"%""}.



Modifié dans la version 3.13: Formatting of @ref{1e4,,Fraction} instances without a presentation type
now supports fill, alignment, sign handling, minimum width and grouping.


@geindex numerator (attribut fractions.Fraction)
@anchor{library/fractions fractions Fraction numerator}@anchor{265b}
@deffn {Attribut} numerator

Numérateur de la fraction irréductible.
@end deffn

@geindex denominator (attribut fractions.Fraction)
@anchor{library/fractions fractions Fraction denominator}@anchor{265c}
@deffn {Attribut} denominator

Dénominateur de la fraction irréductible.
@end deffn

@geindex as_integer_ratio() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction as_integer_ratio}@anchor{265d}
@deffn {Méthode} as_integer_ratio ()

Return a tuple of two integers, whose ratio is equal
to the original Fraction.  The ratio is in lowest terms
and has a positive denominator.


Ajouté dans la version 3.8.

@end deffn

@geindex is_integer() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction is_integer}@anchor{265e}
@deffn {Méthode} is_integer ()

Return @code{True} if the Fraction is an integer.


Ajouté dans la version 3.12.

@end deffn

@geindex from_float() (méthode de la classe fractions.Fraction)
@anchor{library/fractions fractions Fraction from_float}@anchor{11e2}
@deffn {Méthode} classmethod from_float (flt)

Ce constructeur alternatif accepte (uniquement) des nombres à virgule flottante, de classe @ref{2eb,,float}, ou plus généralement des instances de @ref{1f3f,,numbers.Integral}. Attention, @code{Fraction.from_float(0.3)} est différent de @code{Fraction(3, 10)}.

@cartouche
@quotation Note 
Depuis Python 3.2, vous pouvez aussi construire une instance de @ref{1e4,,Fraction} directement depuis un @ref{2eb,,float}.
@end quotation
@end cartouche
@end deffn

@geindex from_decimal() (méthode de la classe fractions.Fraction)
@anchor{library/fractions fractions Fraction from_decimal}@anchor{11e3}
@deffn {Méthode} classmethod from_decimal (dec)

Ce constructeur alternatif accepte (uniquement) les instances de @ref{29a,,decimal.Decimal} ou @ref{1f3f,,numbers.Integral}.

@cartouche
@quotation Note 
Depuis Python 3.2, vous pouvez aussi construire une instance de @ref{1e4,,Fraction} directement depuis une instance de @ref{29a,,decimal.Decimal}.
@end quotation
@end cartouche
@end deffn

@geindex limit_denominator() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction limit_denominator}@anchor{265a}
@deffn {Méthode} limit_denominator (max_denominator=1000000)

Trouve et renvoie la @ref{1e4,,Fraction} la plus proche de @code{self} qui a au plus `max_denominator' comme dénominateur.  Cette méthode est utile pour trouver des approximations rationnelles de nombres flottants donnés :

@example
>>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
Fraction(355, 113)
@end example

ou pour retrouver un nombre rationnel représenté par un flottant :

@example
>>> from math import pi, cos
>>> Fraction(cos(pi/3))
Fraction(4503599627370497, 9007199254740992)
>>> Fraction(cos(pi/3)).limit_denominator()
Fraction(1, 2)
>>> Fraction(1.1).limit_denominator()
Fraction(11, 10)
@end example
@end deffn

@geindex __floor__() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction __floor__}@anchor{1710}
@deffn {Méthode} __floor__ ()

Renvoie le plus grand @ref{254,,int} @code{<= self}.  Cette méthode peut aussi être utilisée à travers la fonction @ref{1378,,math.floor()} :

@example
>>> from math import floor
>>> floor(Fraction(355, 113))
3
@end example
@end deffn

@geindex __ceil__() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction __ceil__}@anchor{170f}
@deffn {Méthode} __ceil__ ()

Renvoie le plus petit @ref{254,,int} @code{>= self}.  Cette méthode peut aussi être utilisée à travers la fonction @ref{1379,,math.ceil()}.
@end deffn

@geindex __round__() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction __round__}@anchor{170e}
@deffn {Méthode} __round__ ()

@deffnx {Méthode} __round__ (ndigits)

La première version renvoie l'@ref{254,,int} le plus proche de @code{self}, arrondissant les demis au nombre pair le plus proche. La seconde version arrondit @code{self} au plus proche multiple de @code{Fraction(1, 10**ndigits)} (logiquement, si @code{ndigits} est négatif), arrondissant toujours les demis au nombre pair le plus proche.  Cette méthode peut aussi être utilisée à via la fonction @ref{12b8,,round()}.
@end deffn

@geindex __format__() (méthode fractions.Fraction)
@anchor{library/fractions fractions Fraction __format__}@anchor{265f}
@deffn {Méthode} __format__ (format_spec, /)

Provides support for formatting of @ref{1e4,,Fraction} instances via the
@ref{60c,,str.format()} method, the @ref{60a,,format()} built-in function, or
@ref{997,,Formatted string literals}.

If the @code{format_spec} format specification string does not end with one
of the presentation types @code{'e'}, @code{'E'}, @code{'f'}, @code{'F'}, @code{'g'},
@code{'G'} or @code{'%'} then formatting follows the general rules for fill,
alignment, sign handling, minimum width, and grouping as described in the
@ref{1e5,,format specification mini-language}. The "alternate
form" flag @code{'#'} is supported: if present, it forces the output string
to always include an explicit denominator, even when the value being
formatted is an exact integer. The zero-fill flag @code{'0'} is not
supported.

If the @code{format_spec} format specification string ends with one of
the presentation types @code{'e'}, @code{'E'}, @code{'f'}, @code{'F'}, @code{'g'},
@code{'G'} or @code{'%'} then formatting follows the rules outlined for the
@ref{2eb,,float} type in the @ref{1e5,,Mini-langage de spécification de format} section.

Voici quelques exemples :

@example
>>> from fractions import Fraction
>>> format(Fraction(103993, 33102), '_')
'103_993/33_102'
>>> format(Fraction(1, 7), '.^+10')
'...+1/7...'
>>> format(Fraction(3, 1), '@w{'})
'3'
>>> format(Fraction(3, 1), '#')
'3/1'
>>> format(Fraction(1, 7), '.40g')
'0.1428571428571428571428571428571428571429'
>>> format(Fraction('1234567.855'), '_.2f')
'1_234_567.86'
>>> f"@{Fraction(355, 113):*>20.6e@}"
'********3.141593e+00'
>>> old_price, new_price = 499, 672
>>> "@{:.2%@} price increase".format(Fraction(new_price, old_price) - 1)
'34.67% price increase'
@end example
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{9d,,numbers}

Les classes abstraites représentant la hiérarchie des nombres.
@end table


@node random --- Generate pseudo-random numbers,statistics --- Mathematical statistics functions,fractions --- Rational numbers,Modules numériques et mathématiques
@anchor{library/random doc}@anchor{2660}@anchor{library/random module-random}@anchor{b7}@anchor{library/random random-generate-pseudo-random-numbers}@anchor{2661}
@subsection @code{random} --- Generate pseudo-random numbers


@geindex module; random

`Code source :' Lib/random.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/random.py}


__________________________________________________________________


Ce module implémente des générateurs de nombres pseudo-aléatoires pour différentes distributions.

Pour les entiers, il existe une sélection uniforme à partir d'une plage. Pour les séquences, il existe une sélection uniforme d'un élément aléatoire, une fonction pour générer une permutation aléatoire d'une liste sur place et une fonction pour un échantillonnage aléatoire sans remplacement.

Pour l'ensemble des réels, il y a des fonctions pour calculer des distributions uniformes, normales (gaussiennes), log-normales, exponentielles négatives, gamma et bêta. Pour générer des distributions d'angles, la distribution de `von Mises' est disponible.

Almost all module functions depend on the basic function @ref{732,,random()}, which
generates a random float uniformly in the half-open range @code{0.0 <= X < 1.0}.
Python uses the Mersenne Twister as the core generator.  It produces 53-bit precision
floats and has a period of 2**19937-1.  The underlying implementation in C is
both fast and threadsafe.  The Mersenne Twister is one of the most extensively
tested random number generators in existence.  However, being completely
deterministic, it is not suitable for all purposes, and is completely unsuitable
for cryptographic purposes.

Les fonctions fournies par ce module dépendent en réalité de méthodes d’une instance cachée de la classe @ref{1835,,random.Random}. Vous pouvez créer vos propres instances de @ref{1835,,Random} pour obtenir des générateurs sans états partagés.

Class @ref{1835,,Random} can also be subclassed if you want to use a different
basic generator of your own devising: see the documentation on that class for
more details.

Le module @ref{b7,,random} fournit également la classe @ref{2662,,SystemRandom} qui utilise la fonction système @ref{50c,,os.urandom()} pour générer des nombres aléatoires à partir de sources fournies par le système d'exploitation.

@cartouche
@quotation Avertissement 
Les générateurs pseudo-aléatoires de ce module ne doivent pas être utilisés à des fins de sécurité.  Pour des utilisations de sécurité ou cryptographiques, voir le module @ref{bf,,secrets}.
@end quotation
@end cartouche


@subsubheading Voir aussi


`M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator", ACM Transactions on Modeling and Computer Simulation Vol. 8, No. 1,' Janvier pp.3--30 1998.

Complementary-Multiply-with-Carry recipe@footnote{https://code.activestate.com/recipes/576707-long-period-random-number-generator/} for a compatible alternative
random number generator with a long period and comparatively simple update
operations.


@cartouche
@quotation Note 
The global random number generator and instances of @ref{1835,,Random} are thread-safe.
However, in the free-threaded build, concurrent calls to the global generator or
to the same instance of @ref{1835,,Random} may encounter contention and poor performance.
Consider using separate instances of @ref{1835,,Random} per thread instead.
@end quotation
@end cartouche

@menu
* Fonctions de gestion d'état:: 
* Fonctions pour les octets:: 
* Fonctions pour les entiers:: 
* Fonctions pour les séquences:: 
* Discrete distributions:: 
* Distributions pour les nombres réels:: 
* Générateur alternatif:: 
* Remarques sur la reproductibilité:: 
* Exemples: Exemples<4>. 
* Cas pratiques: Cas pratiques<2>. 
* Command-line usage:: 
* Command-line example:: 

@end menu

@node Fonctions de gestion d'état,Fonctions pour les octets,,random --- Generate pseudo-random numbers
@anchor{library/random bookkeeping-functions}@anchor{2663}
@subsubsection Fonctions de gestion d'état


@geindex seed() (dans le module random)
@anchor{library/random random seed}@anchor{1252}
@deffn {Fonction} random.seed (a=None, version=2)

Initialise le générateur de nombres aléatoires.

Si `a' est omis ou @code{None}, l'heure système actuelle est utilisée.  Si des sources aléatoires sont fournies par le système d'exploitation, elles sont utilisées à la place de l'heure système (voir la fonction @ref{50c,,os.urandom()} pour les détails sur la disponibilité).

Si `a' est un entier, il est utilisé directement.

Avec la version 2 (par défaut), un objet @ref{435,,str}, @ref{1bd,,bytes} ou @ref{528,,bytearray} est converti en @ref{254,,int} et tous ses bits sont utilisés.

Avec la version 1 (fournie pour reproduire des séquences aléatoires produites par d'anciennes versions de Python), l'algorithme pour @ref{435,,str} et @ref{1bd,,bytes} génère une gamme plus étroite de graines.


Modifié dans la version 3.2: Passée à la version 2 du schéma qui utilise tous les bits d'une graine de chaîne de caractères.



Modifié dans la version 3.11: The `seed' must be one of the following types:
@code{None}, @ref{254,,int}, @ref{2eb,,float}, @ref{435,,str},
@ref{1bd,,bytes}, or @ref{528,,bytearray}.

@end deffn

@geindex getstate() (dans le module random)
@anchor{library/random random getstate}@anchor{2664}
@deffn {Fonction} random.getstate ()

Renvoie un objet capturant l'état interne actuel du générateur. Cet objet peut être passé à @ref{2665,,setstate()} pour restaurer cet état.
@end deffn

@geindex setstate() (dans le module random)
@anchor{library/random random setstate}@anchor{2665}
@deffn {Fonction} random.setstate (state)

Il convient que `state' ait été obtenu à partir d'un appel précédent à @ref{2664,,getstate()}, et @ref{2665,,setstate()} restaure l'état interne du générateur à ce qu'il était au moment où @ref{2664,,getstate()} a été appelé.
@end deffn

@node Fonctions pour les octets,Fonctions pour les entiers,Fonctions de gestion d'état,random --- Generate pseudo-random numbers
@anchor{library/random functions-for-bytes}@anchor{2666}
@subsubsection Fonctions pour les octets


@geindex randbytes() (dans le module random)
@anchor{library/random random randbytes}@anchor{18f8}
@deffn {Fonction} random.randbytes (n)

Génère `n' octets aléatoires.

Cette méthode ne doit pas être utilisée pour générer des jetons de sécurité. Utiliser @ref{2667,,secrets.token_bytes()} à la place.


Ajouté dans la version 3.9.

@end deffn

@node Fonctions pour les entiers,Fonctions pour les séquences,Fonctions pour les octets,random --- Generate pseudo-random numbers
@anchor{library/random functions-for-integers}@anchor{2668}
@subsubsection Fonctions pour les entiers


@geindex randrange() (dans le module random)
@anchor{library/random random randrange}@anchor{856}
@deffn {Fonction} random.randrange (stop)

@deffnx {Fonction} random.randrange (start, stop[, step])

Return a randomly selected element from @code{range(start, stop, step)}.

This is roughly equivalent to @code{choice(range(start, stop, step))} but
supports arbitrarily large ranges and is optimized for common cases.

The positional argument pattern matches the @ref{930,,range()} function.

Keyword arguments should not be used because they can be interpreted
in unexpected ways. For example @code{randrange(start=100)} is interpreted
as @code{randrange(0, 100, 1)}.


Modifié dans la version 3.2: @ref{856,,randrange()} est plus sophistiquée dans la production de valeurs uniformément distribuées.  Auparavant, elle utilisait un style comme @code{int(random()*n)} qui pouvait produire des distributions légèrement inégales.



Modifié dans la version 3.12: Automatic conversion of non-integer types is no longer supported.
Calls such as @code{randrange(10.0)} and @code{randrange(Fraction(10, 1))}
now raise a @ref{522,,TypeError}.

@end deffn

@geindex randint() (dans le module random)
@anchor{library/random random randint}@anchor{120d}
@deffn {Fonction} random.randint (a, b)

Renvoie un entier aléatoire `N' tel que @code{a <= N <= b}.  Alias pour @code{randrange(a, b+1)}.
@end deffn

@geindex getrandbits() (dans le module random)
@anchor{library/random random getrandbits}@anchor{ff6}
@deffn {Fonction} random.getrandbits (k)

Returns a non-negative Python integer with `k' random bits. This method
is supplied with the Mersenne Twister generator and some other generators
may also provide it as an optional part of the API. When available,
@ref{ff6,,getrandbits()} enables @ref{856,,randrange()} to handle arbitrarily large
ranges.


Modifié dans la version 3.9: Cette méthode accepte désormais zéro pour `k'.

@end deffn

@node Fonctions pour les séquences,Discrete distributions,Fonctions pour les entiers,random --- Generate pseudo-random numbers
@anchor{library/random functions-for-sequences}@anchor{2669}
@subsubsection Fonctions pour les séquences


@geindex choice() (dans le module random)
@anchor{library/random random choice}@anchor{120e}
@deffn {Fonction} random.choice (seq)

Renvoie un élément aléatoire de la séquence non vide `seq'. Si `seq' est vide, lève @ref{14eb,,IndexError}.
@end deffn

@geindex choices() (dans le module random)
@anchor{library/random random choices}@anchor{cb4}
@deffn {Fonction} random.choices (population, weights=None, *, cum_weights=None, k=1)

Renvoie une liste de taille `k' d'éléments choisis dans la `population' avec remise. Si la `population' est vide, lève @ref{14eb,,IndexError}.

Si une séquence de `poids' est spécifiée, les tirages sont effectués en fonction des poids relatifs.  Alternativement, si une séquence `cum_weights' est donnée, les tirages sont faits en fonction des poids cumulés (peut-être calculés en utilisant @ref{9eb,,itertools.accumulate()}).  Par exemple, les poids relatifs @code{[10, 5, 30, 5]} sont équivalents aux poids cumulatifs @code{[10, 15, 45, 50]}.  En interne, les poids relatifs sont convertis en poids cumulatifs avant d'effectuer les tirages, ce qui vous permet d'économiser du travail en fournissant des pondérations cumulatives.

Si ni `weights' ni `cum_weights' ne sont spécifiés, les tirages sont effectués avec une probabilité uniforme.  Si une séquence de poids est fournie, elle doit être de la même longueur que la séquence `population'.  Spécifier à la fois `weights' et `cum_weights' lève une @ref{522,,TypeError}.

Les `weights' ou `cum_weights' peuvent utiliser n'importe quel type numérique interopérable avec les valeurs @ref{2eb,,float} renvoyées par @ref{b7,,random()} (qui inclut les entiers, les flottants et les fractions mais exclut les décimaux).  Les poids sont présumés être non négatifs et finis. Une exception @ref{1ff,,ValueError} est levée si tous les poids sont à zéro.

For a given seed, the @ref{cb4,,choices()} function with equal weighting
typically produces a different sequence than repeated calls to
@ref{120e,,choice()}.  The algorithm used by @ref{cb4,,choices()} uses floating-point
arithmetic for internal consistency and speed.  The algorithm used
by @ref{120e,,choice()} defaults to integer arithmetic with repeated selections
to avoid small biases from round-off error.


Ajouté dans la version 3.6.



Modifié dans la version 3.9: Lève une @ref{1ff,,ValueError} si tous les poids sont à zéro.

@end deffn

@geindex shuffle() (dans le module random)
@anchor{library/random random shuffle}@anchor{731}
@deffn {Fonction} random.shuffle (x)

Mélange la séquence `x' sans créer de nouvelle instance (« sur place »).

Pour mélanger une séquence immuable et renvoyer une nouvelle liste mélangée, utilisez @code{sample(x, k=len(x))} à la place.

Notez que même pour les petits @code{len(x)}, le nombre total de permutations de `x' peut rapidement devenir plus grand que la période de la plupart des générateurs de nombres aléatoires. Cela implique que la plupart des permutations d'une longue séquence ne peuvent jamais être générées.  Par exemple, une séquence de longueur 2080 est la plus grande qui puisse tenir dans la période du générateur de nombres aléatoires Mersenne Twister.


Modifié dans la version 3.11: Removed the optional parameter `random'.

@end deffn

@geindex sample() (dans le module random)
@anchor{library/random random sample}@anchor{730}
@deffn {Fonction} random.sample (population, k, *, counts=None)

Return a `k' length list of unique elements chosen from the population
sequence.  Used for random sampling without replacement.

Renvoie une nouvelle liste contenant des éléments de la population tout en laissant la population originale inchangée.  La liste résultante est classée par ordre de sélection de sorte que toutes les sous-tranches soient également des échantillons aléatoires valides.  Cela permet aux gagnants du tirage (l'échantillon) d'être divisés en gagnants du grand prix et en gagnants de la deuxième place (les sous-tranches).

Les membres de la population n'ont pas besoin d'être @ref{5fb,,hachables} ou uniques. Si la population contient des répétitions, alors chaque occurrence est un tirage possible dans l'échantillon.

Les éléments répétés peuvent être spécifiés un à la fois ou avec le paramètre optionnel uniquement nommé `counts'.  Par exemple, @code{sample([‘red’, ‘blue’], counts=[4, 2], k=5)} est équivalent à @code{sample([‘red’, ‘red’, ‘red’, ‘red’, ‘blue’, ‘blue’], k=5)}.

Pour choisir un échantillon parmi un intervalle d'entiers, utilisez un objet @ref{930,,range()} comme argument.  Ceci est particulièrement rapide et économe en mémoire pour un tirage dans une grande population : @code{échantillon(range(10000000), k=60)}.

Si la taille de l'échantillon est supérieure à la taille de la population, une @ref{1ff,,ValueError} est levée.


Modifié dans la version 3.9: Ajoute le paramètre `counts'.



Modifié dans la version 3.11: The `population' must be a sequence.  Automatic conversion of sets
to lists is no longer supported.

@end deffn

@node Discrete distributions,Distributions pour les nombres réels,Fonctions pour les séquences,random --- Generate pseudo-random numbers
@anchor{library/random discrete-distributions}@anchor{266a}
@subsubsection Discrete distributions


The following function generates a discrete distribution.

@geindex binomialvariate() (dans le module random)
@anchor{library/random random binomialvariate}@anchor{499}
@deffn {Fonction} random.binomialvariate (n=1, p=0.5)

Binomial distribution@footnote{https://mathworld.wolfram.com/BinomialDistribution.html}.
Return the number of successes for `n' independent trials with the
probability of success in each trial being `p':

Mathematically equivalent to:

@example
sum(random() < p for i in range(n))
@end example

The number of trials `n' should be a non-negative integer.
The probability of success `p' should be between @code{0.0 <= p <= 1.0}.
The result is an integer in the range @code{0 <= X <= n}.


Ajouté dans la version 3.12.

@end deffn

@node Distributions pour les nombres réels,Générateur alternatif,Discrete distributions,random --- Generate pseudo-random numbers
@anchor{library/random id1}@anchor{266b}@anchor{library/random real-valued-distributions}@anchor{266c}
@subsubsection Distributions pour les nombres réels


Les fonctions suivantes génèrent des distributions spécifiques en nombre réels. Les paramètres de fonction sont nommés d'après les variables correspondantes de l'équation de la distribution, telles qu'elles sont utilisées dans la pratique mathématique courante ; la plupart de ces équations peuvent être trouvées dans tout document traitant de statistiques.

@geindex random() (dans le module random)
@anchor{library/random random random}@anchor{732}
@deffn {Fonction} random.random ()

Return the next random floating-point number in the range @code{0.0 <= X < 1.0}
@end deffn

@geindex uniform() (dans le module random)
@anchor{library/random random uniform}@anchor{266d}
@deffn {Fonction} random.uniform (a, b)

Return a random floating-point number `N' such that @code{a <= N <= b} for
@code{a <= b} and @code{b <= N <= a} for @code{b < a}.

The end-point value @code{b} may or may not be included in the range
depending on floating-point rounding in the expression
@code{a + (b-a) * random()}.
@end deffn

@geindex triangular() (dans le module random)
@anchor{library/random random triangular}@anchor{266e}
@deffn {Fonction} random.triangular (low, high, mode)

Return a random floating-point number `N' such that @code{low <= N <= high} and
with the specified `mode' between those bounds.  The `low' and `high' bounds
default to zero and one.  The `mode' argument defaults to the midpoint
between the bounds, giving a symmetric distribution.
@end deffn

@geindex betavariate() (dans le module random)
@anchor{library/random random betavariate}@anchor{266f}
@deffn {Fonction} random.betavariate (alpha, beta)

Distribution bêta.  Les conditions sur les paramètres sont @code{alpha > 0} et @code{beta > 0}. Les valeurs renvoyées varient entre 0 et 1.
@end deffn

@geindex expovariate() (dans le module random)
@anchor{library/random random expovariate}@anchor{49a}
@deffn {Fonction} random.expovariate (lambd=1.0)

Distribution exponentielle.  `lambd' est 1,0 divisé par la moyenne désirée.  Ce ne doit pas être zéro.  (Le paramètre aurait dû s'appeler "lambda", mais c'est un mot réservé en Python.)  Les valeurs renvoyées vont de 0 à plus l'infini positif si `lambd' est positif, et de moins l'infini à 0 si `lambd' est négatif.


Modifié dans la version 3.12: Added the default value for @code{lambd}.

@end deffn

@geindex gammavariate() (dans le module random)
@anchor{library/random random gammavariate}@anchor{2670}
@deffn {Fonction} random.gammavariate (alpha, beta)

Gamma distribution.  (`Not' the gamma function!)  The shape and
scale parameters, `alpha' and `beta', must have positive values.
(Calling conventions vary and some sources define 'beta'
as the inverse of the scale).

La fonction de distribution de probabilité est :

@example
          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha
@end example
@end deffn

@geindex gauss() (dans le module random)
@anchor{library/random random gauss}@anchor{17cf}
@deffn {Fonction} random.gauss (mu=0.0, sigma=1.0)

Normal distribution, also called the Gaussian distribution.
`mu' is the mean,
and `sigma' is the standard deviation.  This is slightly faster than
the @ref{17d0,,normalvariate()} function defined below.

Note sur les fils d’exécution multiples (`Multithreading') :  quand deux fils d’exécution appellent cette fonction simultanément, il est possible qu’ils reçoivent la même valeur de retour.  On peut l’éviter de 3 façons. 1) Avoir chaque fil utilisant une instance différente du générateur de nombres aléatoires. 2) Mettre des verrous autour de tous les appels. 3) Utiliser la fonction plus lente, mais compatible avec les programmes à fils d’exécution multiples, @ref{17d0,,normalvariate()} à la place.


Modifié dans la version 3.11: `mu' and `sigma' now have default arguments.

@end deffn

@geindex lognormvariate() (dans le module random)
@anchor{library/random random lognormvariate}@anchor{2671}
@deffn {Fonction} random.lognormvariate (mu, sigma)

Logarithme de la distribution normale.  Si vous prenez le logarithme naturel de cette distribution, vous obtiendrez une distribution normale avec `mu' moyen et écart-type `sigma'.  `mu' peut avoir n'importe quelle valeur et `sigma' doit être supérieur à zéro.
@end deffn

@geindex normalvariate() (dans le module random)
@anchor{library/random random normalvariate}@anchor{17d0}
@deffn {Fonction} random.normalvariate (mu=0.0, sigma=1.0)

Distribution normale.  `mu' est la moyenne et `sigma' est l'écart type.


Modifié dans la version 3.11: `mu' and `sigma' now have default arguments.

@end deffn

@geindex vonmisesvariate() (dans le module random)
@anchor{library/random random vonmisesvariate}@anchor{2672}
@deffn {Fonction} random.vonmisesvariate (mu, kappa)

`mu' est l'angle moyen, exprimé en radians entre 0 et 2*`pi', et `kappa' est le paramètre de concentration, qui doit être supérieur ou égal à zéro.  Si `kappa' est égal à zéro, cette distribution se réduit à un angle aléatoire uniforme sur la plage de 0 à 2*`pi'.
@end deffn

@geindex paretovariate() (dans le module random)
@anchor{library/random random paretovariate}@anchor{2673}
@deffn {Fonction} random.paretovariate (alpha)

Distribution de Pareto.  `alpha' est le paramètre de forme.
@end deffn

@geindex weibullvariate() (dans le module random)
@anchor{library/random random weibullvariate}@anchor{2674}
@deffn {Fonction} random.weibullvariate (alpha, beta)

Distribution de Weibull.  `alpha' est le paramètre de l'échelle et `beta' est le paramètre de forme.
@end deffn

@node Générateur alternatif,Remarques sur la reproductibilité,Distributions pour les nombres réels,random --- Generate pseudo-random numbers
@anchor{library/random alternative-generator}@anchor{2675}
@subsubsection Générateur alternatif


@geindex Random (classe dans random)
@anchor{library/random random Random}@anchor{1835}
@deffn {Classe} random.Random ([seed])

Classe qui implémente le générateur de nombres pseudo-aléatoires par défaut utilisé par le module @ref{b7,,random}.


Modifié dans la version 3.11: Formerly the `seed' could be any hashable object.  Now it is limited to:
@code{None}, @ref{254,,int}, @ref{2eb,,float}, @ref{435,,str},
@ref{1bd,,bytes}, or @ref{528,,bytearray}.


Subclasses of @code{Random} should override the following methods if they
wish to make use of a different basic generator:

@geindex seed() (méthode random.Random)
@anchor{library/random random Random seed}@anchor{190f}
@deffn {Méthode} seed (a=None, version=2)

Override this method in subclasses to customise the @ref{1252,,seed()}
behaviour of @code{Random} instances.
@end deffn

@geindex getstate() (méthode random.Random)
@anchor{library/random random Random getstate}@anchor{2676}
@deffn {Méthode} getstate ()

Override this method in subclasses to customise the @ref{2664,,getstate()}
behaviour of @code{Random} instances.
@end deffn

@geindex setstate() (méthode random.Random)
@anchor{library/random random Random setstate}@anchor{2677}
@deffn {Méthode} setstate (state)

Override this method in subclasses to customise the @ref{2665,,setstate()}
behaviour of @code{Random} instances.
@end deffn

@geindex random() (méthode random.Random)
@anchor{library/random random Random random}@anchor{2678}
@deffn {Méthode} random ()

Override this method in subclasses to customise the @ref{732,,random()}
behaviour of @code{Random} instances.
@end deffn

Optionally, a custom generator subclass can also supply the following method:

@geindex getrandbits() (méthode random.Random)
@anchor{library/random random Random getrandbits}@anchor{2679}
@deffn {Méthode} getrandbits (k)

Override this method in subclasses to customise the
@ref{ff6,,getrandbits()} behaviour of @code{Random} instances.
@end deffn
@end deffn

@geindex SystemRandom (classe dans random)
@anchor{library/random random SystemRandom}@anchor{2662}
@deffn {Classe} random.SystemRandom ([seed])

Classe qui utilise la fonction @ref{50c,,os.urandom()} pour générer des nombres aléatoires à partir de sources fournies par le système d'exploitation. Non disponible sur tous les systèmes. Ne repose pas sur un état purement logiciel et les séquences ne sont pas reproductibles. Par conséquent, la méthode @ref{1252,,seed()} n'a aucun effet et est ignorée. Les méthodes @ref{2664,,getstate()} et @ref{2665,,setstate()} lèvent @ref{225,,NotImplementedError} si vous les appelez.
@end deffn

@node Remarques sur la reproductibilité,Exemples<4>,Générateur alternatif,random --- Generate pseudo-random numbers
@anchor{library/random notes-on-reproducibility}@anchor{267a}
@subsubsection Remarques sur la reproductibilité


Sometimes it is useful to be able to reproduce the sequences given by a
pseudo-random number generator.  By reusing a seed value, the same sequence should be
reproducible from run to run as long as multiple threads are not running.

La plupart des algorithmes et des fonctions de génération de graine du module aléatoire sont susceptibles d'être modifiés d'une version à l'autre de Python, mais deux aspects sont garantis de ne pas changer :


@itemize *

@item 
Si une nouvelle méthode de génération de graine est ajoutée, une fonction rétro-compatible sera offerte.

@item 
La méthode @ref{2678,,random()} du générateur continuera à produire la même séquence lorsque la fonction de génération de graine compatible recevra la même semence.
@end itemize

@node Exemples<4>,Cas pratiques<2>,Remarques sur la reproductibilité,random --- Generate pseudo-random numbers
@anchor{library/random examples}@anchor{267b}@anchor{library/random random-examples}@anchor{11b9}
@subsubsection Exemples


Exemples de base :

@example
>>> random()                          # Random float:  0.0 <= x < 1.0
0.37444887175646646

>>> uniform(2.5, 10.0)                # Random float:  2.5 <= x <= 10.0
3.1800146073117523

>>> expovariate(1 / 5)                # Interval between arrivals averaging 5 seconds
5.148957571865031

>>> randrange(10)                     # Integer from 0 to 9 inclusive
7

>>> randrange(0, 101, 2)              # Even integer from 0 to 100 inclusive
26

>>> choice(['win', 'lose', 'draw'])   # Single random element from a sequence
'draw'

>>> deck = 'ace two three four'.split()
>>> shuffle(deck)                     # Shuffle a list
>>> deck
['four', 'two', 'ace', 'three']

>>> sample([10, 20, 30, 40, 50], k=4) # Four samples without replacement
[40, 10, 50, 30]
@end example

Simulations :

@example
>>> # Six roulette wheel spins (weighted sampling with replacement)
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']

>>> # Deal 20 cards without replacement from a deck
>>> # of 52 playing cards, and determine the proportion of cards
>>> # with a ten-value:  ten, jack, queen, or king.
>>> deal = sample(['tens', 'low cards'], counts=[16, 36], k=20)
>>> deal.count('tens') / 20
0.15

>>> # Estimate the probability of getting 5 or more heads from 7 spins
>>> # of a biased coin that settles on heads 60% of the time.
>>> sum(binomialvariate(n=7, p=0.6) >= 5 for i in range(10_000)) / 10_000
0.4169

>>> # Probability of the median of 5 samples being in middle two quartiles
>>> def trial():
...     return 2_500 <= sorted(choices(range(10_000), k=5))[2] < 7_500
...
>>> sum(trial() for i in range(10_000)) / 10_000
0.7958
@end example

Exemple de *bootstrapping* statistique@footnote{https://fr.wikipedia.org/wiki/Bootstrap_(statistiques)} utilisant le ré-échantillonnage avec remise pour estimer un intervalle de confiance pour la moyenne d'un échantillon :

@example
# https://www.thoughtco.com/example-of-bootstrapping-3126155
from statistics import fmean as mean
from random import choices

data = [41, 50, 29, 37, 81, 30, 73, 63, 20, 35, 68, 22, 60, 31, 95]
means = sorted(mean(choices(data, k=len(data))) for i in range(100))
print(f'The sample mean of @{mean(data):.1f@} has a 90% confidence '
      f'interval from @{means[5]:.1f@} to @{means[94]:.1f@}')
@end example

Exemple d'un *resampling permutation test*@footnote{https://en.wikipedia.org/wiki/Resampling_(statistics)#Permutation_tests} pour déterminer la signification statistique ou valeur p@footnote{https://fr.wikipedia.org/wiki/Valeur_p} d'une différence observée entre les effets d'un médicament et ceux d'un placebo :

@example
# Example from "Statistics is Easy" by Dennis Shasha and Manda Wilson
from statistics import fmean as mean
from random import shuffle

drug = [54, 73, 53, 70, 73, 68, 52, 65, 65]
placebo = [54, 51, 58, 44, 55, 52, 42, 47, 58, 46]
observed_diff = mean(drug) - mean(placebo)

n = 10_000
count = 0
combined = drug + placebo
for i in range(n):
    shuffle(combined)
    new_diff = mean(combined[:len(drug)]) - mean(combined[len(drug):])
    count += (new_diff >= observed_diff)

print(f'@{n@} label reshufflings produced only @{count@} instances with a difference')
print(f'at least as extreme as the observed difference of @{observed_diff:.1f@}.')
print(f'The one-sided p-value of @{count / n:.4f@} leads us to reject the null')
print(f'hypothesis that there is no difference between the drug and the placebo.')
@end example

Simulation des heures d'arrivée et des livraisons de services pour une file d'attente de serveurs :

@example
from heapq import heapify, heapreplace
from random import expovariate, gauss
from statistics import mean, quantiles

average_arrival_interval = 5.6
average_service_time = 15.0
stdev_service_time = 3.5
num_servers = 3

waits = []
arrival_time = 0.0
servers = [0.0] * num_servers  # time when each server becomes available
heapify(servers)
for i in range(1_000_000):
    arrival_time += expovariate(1.0 / average_arrival_interval)
    next_server_available = servers[0]
    wait = max(0.0, next_server_available - arrival_time)
    waits.append(wait)
    service_duration = max(0.0, gauss(average_service_time, stdev_service_time))
    service_completed = arrival_time + wait + service_duration
    heapreplace(servers, service_completed)

print(f'Mean wait: @{mean(waits):.1f@}   Max wait: @{max(waits):.1f@}')
print('Quartiles:', [round(q, 1) for q in quantiles(waits)])
@end example


@subsubheading Voir aussi


Statistics for Hackers@footnote{https://www.youtube.com/watch?v=Iq9DzN6mvYA} un tutoriel vidéo par Jake Vanderplas@footnote{https://us.pycon.org/2016/speaker/profile/295/} sur l'analyse statistique en utilisant seulement quelques concepts fondamentaux dont la simulation, l'échantillonnage, le brassage et la validation croisée.

Economics Simulation@footnote{https://nbviewer.org/url/norvig.com/ipython/Economics.ipynb}
a simulation of a marketplace by
Peter Norvig@footnote{https://norvig.com/bio.html} that shows effective
use of many of the tools and distributions provided by this module
(gauss, uniform, sample, betavariate, choice, triangular, and randrange).

A Concrete Introduction to Probability (using Python)@footnote{https://nbviewer.org/url/norvig.com/ipython/Probability.ipynb}
a tutorial by Peter Norvig@footnote{https://norvig.com/bio.html} covering
the basics of probability theory, how to write simulations, and
how to perform data analysis using Python.


@node Cas pratiques<2>,Command-line usage,Exemples<4>,random --- Generate pseudo-random numbers
@anchor{library/random recipes}@anchor{267c}
@subsubsection Cas pratiques


These recipes show how to efficiently make random selections
from the combinatoric iterators in the @ref{80,,itertools} module:

@example
def random_product(*args, repeat=1):
    "Random selection from itertools.product(*args, **kwds)"
    pools = [tuple(pool) for pool in args] * repeat
    return tuple(map(random.choice, pools))

def random_permutation(iterable, r=None):
    "Random selection from itertools.permutations(iterable, r)"
    pool = tuple(iterable)
    r = len(pool) if r is None else r
    return tuple(random.sample(pool, r))

def random_combination(iterable, r):
    "Random selection from itertools.combinations(iterable, r)"
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.sample(range(n), r))
    return tuple(pool[i] for i in indices)

def random_combination_with_replacement(iterable, r):
    "Choose r elements with replacement.  Order the result to match the iterable."
    # Result will be in set(itertools.combinations_with_replacement(iterable, r)).
    pool = tuple(iterable)
    n = len(pool)
    indices = sorted(random.choices(range(n), k=r))
    return tuple(pool[i] for i in indices)
@end example

Par défaut @ref{732,,random()} renvoie des multiples de 2⁻⁵³ dans la plage `0.0 ≤ x < 1.0'.  Tous ces nombres sont uniformément répartis et sont représentés exactement en tant que nombre à virgule flottante Python.  Cependant, de nombreux autres nombres à virgule flottante dans cette plage, et représentables en Python, ne sont pas sélectionnables.  Par exemple @code{0.05954861408025609} n’est pas un multiple de 2⁻⁵³.

La recette suivante utilise une approche différente.  Tous les nombres à virgule flottante de l’intervalle sont sélectionnables.  La mantisse provient d’une distribution uniforme d’entiers dans la plage `2⁵² ≤ mantisse < 2⁵³'.  L’exposant provient d’une distribution géométrique où les exposants plus petits que `-53' apparaissent moitié moins souvent que l’exposant suivant juste plus grand.

@example
from random import Random
from math import ldexp

class FullRandom(Random):

    def random(self):
        mantissa = 0x10_0000_0000_0000 | self.getrandbits(52)
        exponent = -53
        x = 0
        while not x:
            x = self.getrandbits(32)
            exponent += x.bit_length() - 32
        return ldexp(mantissa, exponent)
@end example

Toutes les @ref{266c,,real valued distributions} dans la classe seront utilisées dans la nouvelle méthode :

@example
>>> fr = FullRandom()
>>> fr.random()
0.05954861408025609
>>> fr.expovariate(0.25)
8.87925541791544
@end example

La recette est conceptuellement équivalente à un algorithme qui choisit parmi tous les multiples de 2⁻¹⁰⁷⁴ dans la plage `0.0 ≤ x < 1.0'.  Tous ces nombres sont uniformément répartis, mais la plupart doivent être arrondis au nombre à virgule Python inférieur.  (La valeur 2⁻¹⁰⁷⁴ est le plus petit nombre à virgule flottante positif et est égal à @code{math.ulp(0.0)}.)


@subsubheading Voir aussi


Generating Pseudo-random Floating-Point Values@footnote{https://allendowney.com/research/rand/downey07randfloat.pdf} une publication par `Allen B. Downey' décrivant des manières de générer des nombres à virgule flottante plus fins que normalement générés par @ref{732,,random()}.


@node Command-line usage,Command-line example,Cas pratiques<2>,random --- Generate pseudo-random numbers
@anchor{library/random command-line-usage}@anchor{267d}@anchor{library/random random-cli}@anchor{153}
@subsubsection Command-line usage



Ajouté dans la version 3.13.


The @code{random} module can be executed from the command line.

@example
python -m random [-h] [-c CHOICE [CHOICE ...] | -i N | -f N] [input ...]
@end example

Les options suivantes sont acceptées :

@geindex option de ligne de commande random; -h
@geindex option de ligne de commande random; --help
@anchor{library/random cmdoption-random-h}@anchor{267e}@anchor{library/random cmdoption-random-help}@anchor{267f}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Affiche un message d'aide et quitte.
@end deffn

@geindex option de ligne de commande random; -c
@geindex option de ligne de commande random; --choice
@anchor{library/random cmdoption-random-c}@anchor{2680}
@deffn {Option} @w{-}c CHOICE [CHOICE ...]
@anchor{library/random cmdoption-random-choice}@anchor{2681}
@deffnx {Option} @w{-}@w{-}choice CHOICE [CHOICE ...]

Print a random choice, using @ref{120e,,choice()}.
@end deffn

@geindex option de ligne de commande random; -i
@geindex option de ligne de commande random; --integer
@anchor{library/random cmdoption-random-i}@anchor{2682}
@deffn {Option} @w{-}i <N>
@anchor{library/random cmdoption-random-integer}@anchor{2683}
@deffnx {Option} @w{-}@w{-}integer <N>

Print a random integer between 1 and N inclusive, using @ref{120d,,randint()}.
@end deffn

@geindex option de ligne de commande random; -f
@geindex option de ligne de commande random; --float
@anchor{library/random cmdoption-random-f}@anchor{2684}
@deffn {Option} @w{-}f <N>
@anchor{library/random cmdoption-random-float}@anchor{2685}
@deffnx {Option} @w{-}@w{-}float <N>

Print a random floating-point number between 0 and N inclusive,
using @ref{266d,,uniform()}.
@end deffn

If no options are given, the output depends on the input:


@itemize *

@item 
String or multiple: same as @ref{2681,,--choice}.

@item 
Integer: same as @ref{2683,,--integer}.

@item 
Float: same as @ref{2685,,--float}.
@end itemize

@node Command-line example,,Command-line usage,random --- Generate pseudo-random numbers
@anchor{library/random command-line-example}@anchor{2686}@anchor{library/random random-cli-example}@anchor{2687}
@subsubsection Command-line example


Here are some examples of the @code{random} command-line interface:

@example
$ # Choose one at random
$ python -m random egg bacon sausage spam "Lobster Thermidor aux crevettes with a Mornay sauce"
Lobster Thermidor aux crevettes with a Mornay sauce

$ # Random integer
$ python -m random 6
6

$ # Random floating-point number
$ python -m random 1.8
1.7080016272295635

$ # With explicit arguments
$ python  -m random --choice egg bacon sausage spam "Lobster Thermidor aux crevettes with a Mornay sauce"
egg

$ python -m random --integer 6
3

$ python -m random --float 1.8
1.5666339105010318

$ python -m random --integer 6
5

$ python -m random --float 6
3.1942323316565915
@end example

@node statistics --- Mathematical statistics functions,,random --- Generate pseudo-random numbers,Modules numériques et mathématiques
@anchor{library/statistics doc}@anchor{2688}@anchor{library/statistics module-statistics}@anchor{d1}@anchor{library/statistics statistics-mathematical-statistics-functions}@anchor{2689}
@subsection @code{statistics} --- Mathematical statistics functions


@geindex module; statistics


Ajouté dans la version 3.4.


`Code source :' Lib/statistics.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/statistics.py}

@c from statistics import *
@c import math
@c __name__ = '<doctest>'


__________________________________________________________________


Ce module fournit des fonctions pour le calcul de valeurs statistiques sur des données numériques (valeurs réelles de la classe @ref{211f,,Real}).

The module is not intended to be a competitor to third-party libraries such
as NumPy@footnote{https://numpy.org}, SciPy@footnote{https://scipy.org/}, or
proprietary full-featured statistics packages aimed at professional
statisticians such as Minitab, SAS and Matlab. It is aimed at the level of
graphing and scientific calculators.

À moins que cela ne soit précisé différemment, ces fonctions gèrent les objets @ref{254,,int}, @ref{2eb,,float}, @ref{29a,,Decimal} et @ref{1e4,,Fraction}. Leur bon comportement avec d'autres types (numériques ou non) n'est pas garanti. Le comportement de ces fonctions sur des collections mixtes de différents types est indéfini et dépend de l'implémentation. Si vos données comportement un mélange de plusieurs types, vous pouvez utiliser @ref{84e,,map()} pour vous assurer que le résultat est cohérent, par exemple : @code{map(float, input_data)}.

Some datasets use @code{NaN} (not a number) values to represent missing data.
Since NaNs have unusual comparison semantics, they cause surprising or
undefined behaviors in the statistics functions that sort data or that count
occurrences.  The functions affected are @code{median()}, @code{median_low()},
@code{median_high()}, @code{median_grouped()}, @code{mode()}, @code{multimode()}, and
@code{quantiles()}.  The @code{NaN} values should be stripped before calling these
functions:

@example
>>> from statistics import median
>>> from math import isnan
>>> from itertools import filterfalse

>>> data = [20.7, float('NaN'),19.2, 18.3, float('NaN'), 14.4]
>>> sorted(data)  # This has surprising behavior
[20.7, nan, 14.4, 18.3, 19.2, nan]
>>> median(data)  # This result is unexpected
16.35

>>> sum(map(isnan, data))    # Number of missing values
2
>>> clean = list(filterfalse(isnan, data))  # Strip NaN values
>>> clean
[20.7, 19.2, 18.3, 14.4]
>>> sorted(clean)  # Sorting now works as expected
[14.4, 18.3, 19.2, 20.7]
>>> median(clean)       # This result is now well defined
18.75
@end example

@menu
* Moyennes et mesures de la tendance centrale:: 
* Mesures de la dispersion:: 
* Statistics for relations between two inputs:: 
* Détails des fonctions:: 
* Exceptions: Exceptions<5>. 
* Objets NormalDist:: 
* Examples and Recipes:: 

@end menu

@node Moyennes et mesures de la tendance centrale,Mesures de la dispersion,,statistics --- Mathematical statistics functions
@anchor{library/statistics averages-and-measures-of-central-location}@anchor{268a}
@subsubsection Moyennes et mesures de la tendance centrale


Ces fonctions calculent une moyenne ou une valeur typique à partir d'une population ou d'un échantillon.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{6bc,,mean()}

@tab

Moyenne arithmétique des données.

@item

@ref{a22,,fmean()}

@tab

Fast, floating-point arithmetic mean, with optional weighting.

@item

@ref{a23,,geometric_mean()}

@tab

Moyenne géométrique des données.

@item

@ref{ccf,,harmonic_mean()}

@tab

Moyenne harmonique des données.

@item

@ref{247,,kde()}

@tab

Estimate the probability density distribution of the data.

@item

@ref{248,,kde_random()}

@tab

Random sampling from the PDF generated by kde().

@item

@ref{268b,,median()}

@tab

Médiane (valeur centrale) des données.

@item

@ref{268c,,median_low()}

@tab

Médiane basse des données.

@item

@ref{268d,,median_high()}

@tab

Médiane haute des données.

@item

@ref{268e,,median_grouped()}

@tab

Median (50th percentile) of grouped data.

@item

@ref{a80,,mode()}

@tab

Mode principal (la valeur la plus représentée) de données discrètes ou nominales.

@item

@ref{a24,,multimode()}

@tab

Liste des modes (les valeurs les plus représentées) de données discrètes ou nominales.

@item

@ref{a25,,quantiles()}

@tab

Divise les données en intervalles de même probabilité.

@end multitable


@node Mesures de la dispersion,Statistics for relations between two inputs,Moyennes et mesures de la tendance centrale,statistics --- Mathematical statistics functions
@anchor{library/statistics measures-of-spread}@anchor{268f}
@subsubsection Mesures de la dispersion


Ces fonctions mesurent la tendance de la population ou d'un échantillon à dévier des valeurs typiques ou des valeurs moyennes.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{2690,,pstdev()}

@tab

Écart-type de la population.

@item

@ref{2691,,pvariance()}

@tab

Variance de la population.

@item

@ref{6be,,stdev()}

@tab

Écart-type d'un échantillon.

@item

@ref{6bd,,variance()}

@tab

Variance d'un échantillon.

@end multitable


@node Statistics for relations between two inputs,Détails des fonctions,Mesures de la dispersion,statistics --- Mathematical statistics functions
@anchor{library/statistics statistics-for-relations-between-two-inputs}@anchor{2692}
@subsubsection Statistics for relations between two inputs


These functions calculate statistics regarding relations between two inputs.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{81a,,covariance()}

@tab

Covariance d'un échantillon pour deux variables.

@item

@ref{4a5,,correlation()}

@tab

Pearson and Spearman's correlation coefficients.

@item

@ref{81b,,linear_regression()}

@tab

Slope and intercept for simple linear regression.

@end multitable


@node Détails des fonctions,Exceptions<5>,Statistics for relations between two inputs,statistics --- Mathematical statistics functions
@anchor{library/statistics function-details}@anchor{2693}
@subsubsection Détails des fonctions


Note : les fonctions ne requièrent pas que les données soient ordonnées. Toutefois, pour en faciliter la lecture, les exemples utiliseront des séquences croissantes.

@geindex mean() (dans le module statistics)
@anchor{library/statistics statistics mean}@anchor{6bc}
@deffn {Fonction} statistics.mean (data)

Renvoie la moyenne arithmétique de l'échantillon `data' qui peut être une séquence ou un itérable.

La moyenne arithmétique est la somme des valeurs divisée par le nombre d'observations. Il s'agit de la valeur couramment désignée comme la « moyenne » bien qu'il existe de multiples façons de définir mathématiquement la moyenne. C'est une mesure de la tendance centrale des données.

Une erreur @ref{2694,,StatisticsError} est levée si `data' est vide.

Exemples d'utilisation :

@example
>>> mean([1, 2, 3, 4, 4])
2.8
>>> mean([-1.0, 2.5, 3.25, 5.75])
2.625

>>> from fractions import Fraction as F
>>> mean([F(3, 7), F(1, 21), F(5, 3), F(1, 3)])
Fraction(13, 21)

>>> from decimal import Decimal as D
>>> mean([D("0.5"), D("0.75"), D("0.625"), D("0.375")])
Decimal('0.5625')
@end example

@cartouche
@quotation Note 
La moyenne arithmétique est fortement impactée par la présence de valeurs aberrantes@footnote{https://fr.wikipedia.org/wiki/Donn%C3%A9e_aberrante} et n'est pas un estimateur robuste de la tendance centrale : la moyenne n'est pas nécessairement un exemple représentatif de l'échantillon. Voir @ref{268b,,median()} pour des mesures plus robustes de la tendance centrale@footnote{https://fr.wikipedia.org/wiki/Indicateur_de_tendance_centrale}.

La moyenne de l'échantillon est une estimation non biaisée de la moyenne de la véritable population. Ainsi, en calculant la moyenne sur tous les échantillons possibles, @code{mean(sample)} converge vers la moyenne réelle de la population entière. Si `data' est une population entière plutôt qu'un échantillon, alors @code{mean(data)} équivaut à calculer la véritable moyenne μ.
@end quotation
@end cartouche
@end deffn

@geindex fmean() (dans le module statistics)
@anchor{library/statistics statistics fmean}@anchor{a22}
@deffn {Fonction} statistics.fmean (data, weights=None)

Convertit `data' en nombres à virgule flottante et calcule la moyenne arithmétique.

Cette fonction est plus rapide que @ref{6bc,,mean()} et renvoie toujours un @ref{2eb,,float}. `data' peut être une séquence ou un itérable. Si les données d'entrée sont vides, la fonction lève une erreur @ref{2694,,StatisticsError}.

@example
>>> fmean([3.5, 4.0, 5.25])
4.25
@end example

Optional weighting is supported.  For example, a professor assigns a
grade for a course by weighting quizzes at 20%, homework at 20%, a
midterm exam at 30%, and a final exam at 30%:

@example
>>> grades = [85, 92, 83, 91]
>>> weights = [0.20, 0.20, 0.30, 0.30]
>>> fmean(grades, weights)
87.6
@end example

If `weights' is supplied, it must be the same length as the `data' or
a @ref{1ff,,ValueError} will be raised.


Ajouté dans la version 3.8.



Modifié dans la version 3.11: Added support for `weights'.

@end deffn

@geindex geometric_mean() (dans le module statistics)
@anchor{library/statistics statistics geometric_mean}@anchor{a23}
@deffn {Fonction} statistics.geometric_mean (data)

Convertit `data' en nombres à virgule flottante et calcule la moyenne géométrique.

La moyenne géométrique mesure la tendance centrale ou la valeur typique de `data' en utilisant le produit des valeurs (par opposition à la moyenne arithmétique qui utilise la somme).

Lève une erreur @ref{2694,,StatisticsError} si les données sont vides, si elles contiennent un zéro ou une valeur négative. `data' peut être une séquence ou un itérable.

Aucune mesure particulière n'est prise pour garantir que le résultat est parfaitement exact (cela peut toutefois changer dans une version future).

@example
>>> round(geometric_mean([54, 24, 36]), 1)
36.0
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex harmonic_mean() (dans le module statistics)
@anchor{library/statistics statistics harmonic_mean}@anchor{ccf}
@deffn {Fonction} statistics.harmonic_mean (data, weights=None)

Return the harmonic mean of `data', a sequence or iterable of
real-valued numbers.  If `weights' is omitted or @code{None}, then
equal weighting is assumed.

The harmonic mean is the reciprocal of the arithmetic @ref{6bc,,mean()} of the
reciprocals of the data. For example, the harmonic mean of three values `a',
`b' and `c' will be equivalent to @code{3/(1/a + 1/b + 1/c)}.  If one of the
values is zero, the result will be zero.

The harmonic mean is a type of average, a measure of the central
location of the data.  It is often appropriate when averaging
ratios or rates, for example speeds.

Supposons qu'une voiture parcoure 10 km à 40 km/h puis 10 km à 60 km/h. Quelle a été sa vitesse moyenne ?

@example
>>> harmonic_mean([40, 60])
48.0
@end example

Suppose a car travels 40 km/hr for 5 km, and when traffic clears,
speeds-up to 60 km/hr for the remaining 30 km of the journey. What
is the average speed?

@example
>>> harmonic_mean([40, 60], weights=[5, 30])
56.0
@end example

@ref{2694,,StatisticsError} is raised if `data' is empty, any element
is less than zero, or if the weighted sum isn't positive.

L'algorithme actuellement implémenté s'arrête prématurément lors de la rencontre d'un zéro dans le parcours de l'entrée. Cela signifie que la validité des valeurs suivantes n'est pas testée (ce comportement est susceptible de changer dans une version future).


Ajouté dans la version 3.6.



Modifié dans la version 3.10: Added support for `weights'.

@end deffn

@geindex kde() (dans le module statistics)
@anchor{library/statistics statistics kde}@anchor{247}
@deffn {Fonction} statistics.kde (data, h, kernel='normal', *, cumulative=False)

Kernel Density Estimation (KDE)@footnote{https://www.itm-conferences.org/articles/itmconf/pdf/2018/08/itmconf_sam2018_00037.pdf}:
Create a continuous probability density function or cumulative
distribution function from discrete samples.

The basic idea is to smooth the data using a kernel function@footnote{https://en.wikipedia.org/wiki/Kernel_(statistics)}.
to help draw inferences about a population from a sample.

The degree of smoothing is controlled by the scaling parameter `h'
which is called the bandwidth.  Smaller values emphasize local
features while larger values give smoother results.

The `kernel' determines the relative weights of the sample data
points.  Generally, the choice of kernel shape does not matter
as much as the more influential bandwidth smoothing parameter.

Kernels that give some weight to every sample point include
`normal' (`gauss'), `logistic', and `sigmoid'.

Kernels that only give weight to sample points within the bandwidth
include `rectangular' (`uniform'), `triangular', `parabolic'
(`epanechnikov'), `quartic' (`biweight'), `triweight', and `cosine'.

If `cumulative' is true, will return a cumulative distribution function.

A @ref{2694,,StatisticsError} will be raised if the `data' sequence is empty.

Wikipedia has an example@footnote{https://en.wikipedia.org/wiki/Kernel_density_estimation#Example}
where we can use @ref{247,,kde()} to generate and plot a probability
density function estimated from a small sample:

@example
>>> sample = [-2.1, -1.3, -0.4, 1.9, 5.1, 6.2]
>>> f_hat = kde(sample, h=1.5)
>>> xarr = [i/100 for i in range(-750, 1100)]
>>> yarr = [f_hat(x) for x in xarr]
@end example

The points in @code{xarr} and @code{yarr} can be used to make a PDF plot:

@image{python-figures/kde_example,,,Scatter plot of the estimated probability density function.,png}


Ajouté dans la version 3.13.

@end deffn

@geindex kde_random() (dans le module statistics)
@anchor{library/statistics statistics kde_random}@anchor{248}
@deffn {Fonction} statistics.kde_random (data, h, kernel='normal', *, seed=None)

Return a function that makes a random selection from the estimated
probability density function produced by @code{kde(data, h, kernel)}.

Providing a `seed' allows reproducible selections. In the future, the
values may change slightly as more accurate kernel inverse CDF estimates
are implemented.  The seed may be an integer, float, str, or bytes.

A @ref{2694,,StatisticsError} will be raised if the `data' sequence is empty.

Continuing the example for @ref{247,,kde()}, we can use
@ref{248,,kde_random()} to generate new random selections from an
estimated probability density function:

@example
>>> data = [-2.1, -1.3, -0.4, 1.9, 5.1, 6.2]
>>> rand = kde_random(data, h=1.5, seed=8675309)
>>> new_selections = [rand() for i in range(10)]
>>> [round(x, 1) for x in new_selections]
[0.7, 6.2, 1.2, 6.9, 7.0, 1.8, 2.5, -0.5, -1.8, 5.6]
@end example


Ajouté dans la version 3.13.

@end deffn

@geindex median() (dans le module statistics)
@anchor{library/statistics statistics median}@anchor{268b}
@deffn {Fonction} statistics.median (data)

Renvoie la médiane (la valeur centrale) de données numériques en utilisant la méthode classique « moyenne des deux du milieu ». Lève une erreur @ref{2694,,StatisticsError} si `data' est vide. `data' peut être une séquence ou un itérable.

La médiane est une mesure robuste de la tendance centrale et est moins sensible à la présence de valeurs aberrantes que la moyenne. Lorsque le nombre d'observations est impair, la valeur du milieu est renvoyée :

@example
>>> median([1, 3, 5])
3
@end example

Lorsque le nombre d'observations est pair, la médiane est interpolée en calculant la moyenne des deux valeurs du milieu :

@example
>>> median([1, 3, 5, 7])
4.0
@end example

Cette approche est adaptée à des données discrètes à condition que vous acceptiez que la médiane ne fasse pas nécessairement partie des observations.

Si les données sont ordinales (elles peuvent être ordonnées) mais pas numériques (elles ne peuvent être additionnées), utilisez @ref{268c,,median_low()} ou @ref{268d,,median_high()} à la place.
@end deffn

@geindex median_low() (dans le module statistics)
@anchor{library/statistics statistics median_low}@anchor{268c}
@deffn {Fonction} statistics.median_low (data)

Renvoie la médiane basse de données numériques. Lève une erreur @ref{2694,,StatisticsError} si `data' est vide. `data' peut être une séquence ou un itérable.

La médiane basse est toujours une valeur représentée dans les données. Lorsque le nombre d'observations est impair, la valeur du milieu est renvoyée. Sinon, la plus petite des deux valeurs du milieu est renvoyée.

@example
>>> median_low([1, 3, 5])
3
>>> median_low([1, 3, 5, 7])
3
@end example

Utilisez la médiane basse lorsque vos données sont discrètes et que vous préférez que la médiane soit une valeur représentée dans vos observations plutôt que le résultat d'une interpolation.
@end deffn

@geindex median_high() (dans le module statistics)
@anchor{library/statistics statistics median_high}@anchor{268d}
@deffn {Fonction} statistics.median_high (data)

Renvoie la médiane haute des données. Lève une erreur @ref{2694,,StatisticsError} si `data' est vide. `data' peut être une séquence ou un itérable.

La médiane haute est toujours une valeur représentée dans les données. Lorsque le nombre d'observations est impair, la valeur du milieu est renvoyée. Sinon, la plus grande des deux valeurs du milieu est renvoyée.

@example
>>> median_high([1, 3, 5])
3
>>> median_high([1, 3, 5, 7])
5
@end example

Utilisez la médiane haute lorsque vos données sont discrètes et que vous préférez que la médiane soit une valeur représentée dans vos observations plutôt que le résultat d'une interpolation.
@end deffn

@geindex median_grouped() (dans le module statistics)
@anchor{library/statistics statistics median_grouped}@anchor{268e}
@deffn {Fonction} statistics.median_grouped (data, interval=1.0)

Estimates the median for numeric data that has been grouped or binned@footnote{https://en.wikipedia.org/wiki/Data_binning} around the midpoints
of consecutive, fixed-width intervals.

The `data' can be any iterable of numeric data with each value being
exactly the midpoint of a bin.  At least one value must be present.

The `interval' is the width of each bin.

For example, demographic information may have been summarized into
consecutive ten-year age groups with each group being represented
by the 5-year midpoints of the intervals:

@example
>>> from collections import Counter
>>> demographics = Counter(@{
...    25: 172,   # 20 to 30 years old
...    35: 484,   # 30 to 40 years old
...    45: 387,   # 40 to 50 years old
...    55:  22,   # 50 to 60 years old
...    65:   6,   # 60 to 70 years old
... @})
...
@end example

The 50th percentile (median) is the 536th person out of the 1071
member cohort.  That person is in the 30 to 40 year old age group.

The regular @ref{268b,,median()} function would assume that everyone in the
tricenarian age group was exactly 35 years old.  A more tenable
assumption is that the 484 members of that age group are evenly
distributed between 30 and 40.  For that, we use
@ref{268e,,median_grouped()}:

@example
>>> data = list(demographics.elements())
>>> median(data)
35
>>> round(median_grouped(data, interval=10), 1)
37.5
@end example

The caller is responsible for making sure the data points are separated
by exact multiples of `interval'.  This is essential for getting a
correct result.  The function does not check this precondition.

Inputs may be any numeric type that can be coerced to a float during
the interpolation step.
@end deffn

@geindex mode() (dans le module statistics)
@anchor{library/statistics statistics mode}@anchor{a80}
@deffn {Fonction} statistics.mode (data)

Renvoie la valeur la plus représentée dans la collection `data' (discrète ou nominale). Ce mode, lorsqu'il existe, est la valeur la plus représentative des données et est une mesure de la tendance centrale.

S'il existe plusieurs modes avec la même fréquence, cette fonction renvoie le premier qui a été rencontré dans `data'. Utilisez @code{min(multimode(data))} ou @code{max(multimode(data))} si vous désirez le plus petit mode ou le plus grand mode. Lève une erreur @ref{2694,,StatisticsError} si `data' est vide.

@code{mode} suppose que les données sont discrètes et renvoie une seule valeur. Il s'agit de la définition usuelle du mode telle qu'enseignée dans à l'école :

@example
>>> mode([1, 1, 2, 3, 3, 3, 3, 4])
3
@end example

Le mode a la particularité d'être la seule statistique de ce module à pouvoir être calculée sur des données nominales (non numériques) :

@example
>>> mode(["red", "blue", "blue", "red", "green", "red", "red"])
'red'
@end example

Only hashable inputs are supported.  To handle type @ref{5c3,,set},
consider casting to @ref{5c4,,frozenset}.  To handle type @ref{5fc,,list},
consider casting to @ref{366,,tuple}.  For mixed or nested inputs, consider
using this slower quadratic algorithm that only depends on equality tests:
@code{max(data, key=data.count)}.


Modifié dans la version 3.8: Gère désormais des jeux de données avec plusieurs modes en renvoyant le premier mode rencontré. Précédemment, une erreur @ref{2694,,StatisticsError} était levée si plusieurs modes étaient trouvés.

@end deffn

@geindex multimode() (dans le module statistics)
@anchor{library/statistics statistics multimode}@anchor{a24}
@deffn {Fonction} statistics.multimode (data)

Renvoie une liste des valeurs les plus fréquentes en suivant leur ordre d'apparition dans `data'. Renvoie plusieurs résultats s'il y a plusieurs modes ou une liste vide si `data' est vide :

@example
>>> multimode('aabbbbccddddeeffffgg')
['b', 'd', 'f']
>>> multimode('@w{'})
[]
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex pstdev() (dans le module statistics)
@anchor{library/statistics statistics pstdev}@anchor{2690}
@deffn {Fonction} statistics.pstdev (data, mu=None)

Renvoie l'écart-type de la population (racine carrée de la variance de la population). Voir @ref{2691,,pvariance()} pour les arguments et d'autres précisions.

@example
>>> pstdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
0.986893273527251
@end example
@end deffn

@geindex pvariance() (dans le module statistics)
@anchor{library/statistics statistics pvariance}@anchor{2691}
@deffn {Fonction} statistics.pvariance (data, mu=None)

Renvoie la variance de la population `data', une séquence non-vide ou un itérable de valeurs réelles. La variance, ou moment de second ordre, est une mesure de la variabilité (ou dispersion) des données. Une variance élevée indique une large dispersion des valeurs ; une faible variance indique que les valeurs sont resserrées autour de la moyenne.

If the optional second argument `mu' is given, it should be the `population'
mean of the `data'.  It can also be used to compute the second moment around
a point that is not the mean.  If it is missing or @code{None} (the default),
the arithmetic mean is automatically calculated.

Utilisez cette fonction pour calculer la variance sur une population complète. Pour estimer la variance à partir d'un échantillon, utilisez plutôt @ref{6bd,,variance()} à la place.

Lève une erreur @ref{2694,,StatisticsError} si `data' est vide.

Exemples :

@example
>>> data = [0.0, 0.25, 0.25, 1.25, 1.5, 1.75, 2.75, 3.25]
>>> pvariance(data)
1.25
@end example

Si vous connaissez la moyenne de vos données, il est possible de la passer comme argument optionnel `mu' lors de l'appel de fonction pour éviter de la calculer une nouvelle fois :

@example
>>> mu = mean(data)
>>> pvariance(data, mu)
1.25
@end example

La fonction gère les nombres décimaux et les fractions :

@example
>>> from decimal import Decimal as D
>>> pvariance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
Decimal('24.815')

>>> from fractions import Fraction as F
>>> pvariance([F(1, 4), F(5, 4), F(1, 2)])
Fraction(13, 72)
@end example

@cartouche
@quotation Note 
Cette fonction renvoie la variance de la population σ² lorsqu'elle est appliquée sur la population entière. Si elle est appliquée seulement sur un échantillon, le résultat est alors la variance de l'échantillon s² ou variance à N degrés de liberté.

Si vous connaissez d'avance la vraie moyenne de la population μ, vous pouvez utiliser cette fonction pour calculer la variance de l'échantillon sachant la moyenne de la population en la passante comme second argument. En supposant que les observations sont issues d'un tirage aléatoire uniforme dans la population, le résultat sera une estimation non biaisée de la variance de la population.
@end quotation
@end cartouche
@end deffn

@geindex stdev() (dans le module statistics)
@anchor{library/statistics statistics stdev}@anchor{6be}
@deffn {Fonction} statistics.stdev (data, xbar=None)

Renvoie l'écart-type de l'échantillon (racine carrée de la variance de l'échantillon). Voir @ref{6bd,,variance()} pour les arguments et plus de détails.

@example
>>> stdev([1.5, 2.5, 2.5, 2.75, 3.25, 4.75])
1.0810874155219827
@end example
@end deffn

@geindex variance() (dans le module statistics)
@anchor{library/statistics statistics variance}@anchor{6bd}
@deffn {Fonction} statistics.variance (data, xbar=None)

Renvoie la variance de l'échantillon `data', un itérable d'au moins deux valeurs réelles. La variance, ou moment de second ordre, est une mesure de la variabilité (ou dispersion) des données. Une variance élevée indique que les données sont très dispersées ; une variance faible indique que les valeurs sont resserrées autour de la moyenne.

If the optional second argument `xbar' is given, it should be the `sample'
mean of `data'.  If it is missing or @code{None} (the default), the mean is
automatically calculated.

Utilisez cette fonction lorsque vos données forment un échantillon d'une population plus grande. Pour calculer la variance d'une population complète, utilisez @ref{2691,,pvariance()}.

Lève une erreur @ref{2694,,StatisticsError} si `data' contient moins de deux éléments.

Exemples :

@example
>>> data = [2.75, 1.75, 1.25, 0.25, 0.5, 1.25, 3.5]
>>> variance(data)
1.3720238095238095
@end example

If you have already calculated the sample mean of your data, you can pass it
as the optional second argument `xbar' to avoid recalculation:

@example
>>> m = mean(data)
>>> variance(data, m)
1.3720238095238095
@end example

Cette fonction ne vérifie pas que la valeur passée dans l'argument `xbar' correspond bien à la moyenne. Utiliser des valeurs arbitraires pour `xbar' produit des résultats impossibles ou incorrects.

La fonction gère les nombres décimaux et les fractions :

@example
>>> from decimal import Decimal as D
>>> variance([D("27.5"), D("30.25"), D("30.25"), D("34.5"), D("41.75")])
Decimal('31.01875')

>>> from fractions import Fraction as F
>>> variance([F(1, 6), F(1, 2), F(5, 3)])
Fraction(67, 108)
@end example

@cartouche
@quotation Note 
Cela correspond à la variance s² de l'échantillon avec correction de Bessel (ou variance à N-1 degrés de liberté). En supposant que les observations sont représentatives de la population (c'est-à-dire indépendantes et identiquement distribuées), alors le résultat est une estimation non biaisée de la variance.

Si vous connaissez d'avance la vraie moyenne μ de la population, vous devriez la passer à @ref{2691,,pvariance()} comme paramètre `mu' pour obtenir la variance de l'échantillon.
@end quotation
@end cartouche
@end deffn

@geindex quantiles() (dans le module statistics)
@anchor{library/statistics statistics quantiles}@anchor{a25}
@deffn {Fonction} statistics.quantiles (data, *, n=4, method='exclusive')

Divise `data' en `n' intervalles réels de même probabilité. Renvoie une liste de @code{n - 1} valeurs délimitant les intervalles (les quantiles).

Utilisez @code{n = 4} pour obtenir les quartiles (le défaut), @code{n = 10} pour obtenir les déciles et @code{n = 100} pour obtenir les centiles (ce qui produit 99 valeurs qui séparent `data' en 100 groupes de même taille). Lève une erreur @ref{2694,,StatisticsError} si `n' est strictement inférieur à 1.

The `data' can be any iterable containing sample data.  For meaningful
results, the number of data points in `data' should be larger than `n'.
Raises @ref{2694,,StatisticsError} if there is not at least one data point.

Les quantiles sont linéairement interpolées à partir des deux valeurs les plus proches dans l'échantillon. Par exemple, si un quantile se situe à un tiers de la distance entre les deux valeurs de l'échantillon @code{100} et @code{112}, le quantile vaudra @code{104}.

L'argument `method' indique la méthode à utiliser pour calculer les quantiles et peut être modifié pour spécifier s'il faut inclure ou exclure les valeurs basses et hautes de `data' de la population.

La valeur par défaut pour `method' est @code{"exclusive"} et est applicable pour des données échantillonnées dans une population dont une des valeurs extrêmes peut être plus grande (respectivement plus petite) que le maximum (respectivement le minimum) des valeurs de l'échantillon. La proportion de la population se situant en-dessous du i@w{^e} de `m' valeurs ordonnées est calculée par la formule @code{i / (m + 1)}. Par exemple, en supposant 9 valeurs dans l'échantillon, cette méthode les ordonne et leur associe les quantiles suivants : 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%.

En utilisant @code{"inclusive"} comme valeur du paramètre `method', on suppose que `data' correspond soit à une population entière, soit que les valeurs extrêmes de la population sont représentées dans l'échantillon. Le minimum de `data' est alors considéré comme 0@w{^e} centile et le maximum comme 100@w{^e} centile. La proportion de la population se situant sous la i@w{^e} valeur de `m' valeurs ordonnées est calculée par la formule @code{(i - 1)/(m - 1)}. En supposant que l'on a 11 valeurs dans l'échantillon, cette méthode les ordonne et leur associe les quantiles suivants : 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%.

@example
# Decile cut points for empirically sampled data
>>> data = [105, 129, 87, 86, 111, 111, 89, 81, 108, 92, 110,
...         100, 75, 105, 103, 109, 76, 119, 99, 91, 103, 129,
...         106, 101, 84, 111, 74, 87, 86, 103, 103, 106, 86,
...         111, 75, 87, 102, 121, 111, 88, 89, 101, 106, 95,
...         103, 107, 101, 81, 109, 104]
>>> [round(q, 1) for q in quantiles(data, n=10)]
[81.0, 86.2, 89.0, 99.4, 102.5, 103.6, 106.0, 109.8, 111.0]
@end example


Ajouté dans la version 3.8.



Modifié dans la version 3.13: No longer raises an exception for an input with only a single data point.
This allows quantile estimates to be built up one sample point
at a time becoming gradually more refined with each new data point.

@end deffn

@geindex covariance() (dans le module statistics)
@anchor{library/statistics statistics covariance}@anchor{81a}
@deffn {Fonction} statistics.covariance (x, y, /)

Return the sample covariance of two inputs `x' and `y'. Covariance
is a measure of the joint variability of two inputs.

Both inputs must be of the same length (no less than two), otherwise
@ref{2694,,StatisticsError} is raised.

Exemples :

@example
>>> x = [1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> y = [1, 2, 3, 1, 2, 3, 1, 2, 3]
>>> covariance(x, y)
0.75
>>> z = [9, 8, 7, 6, 5, 4, 3, 2, 1]
>>> covariance(x, z)
-7.5
>>> covariance(z, x)
-7.5
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex correlation() (dans le module statistics)
@anchor{library/statistics statistics correlation}@anchor{4a5}
@deffn {Fonction} statistics.correlation (x, y, /, *, method='linear')

Return the Pearson's correlation coefficient@footnote{https://en.wikipedia.org/wiki/Pearson_correlation_coefficient}
for two inputs. Pearson's correlation coefficient `r' takes values
between -1 and +1. It measures the strength and direction of a linear
relationship.

If `method' is "ranked", computes Spearman's rank correlation coefficient@footnote{https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient}
for two inputs. The data is replaced by ranks.  Ties are averaged so that
equal values receive the same rank.  The resulting coefficient measures the
strength of a monotonic relationship.

Spearman's correlation coefficient is appropriate for ordinal data or for
continuous data that doesn't meet the linear proportion requirement for
Pearson's correlation coefficient.

Both inputs must be of the same length (no less than two), and need
not to be constant, otherwise @ref{2694,,StatisticsError} is raised.

Example with Kepler's laws of planetary motion@footnote{https://en.wikipedia.org/wiki/Kepler's_laws_of_planetary_motion}:

@example
>>> # Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and  Neptune
>>> orbital_period = [88, 225, 365, 687, 4331, 10_756, 30_687, 60_190]    # days
>>> dist_from_sun = [58, 108, 150, 228, 778, 1_400, 2_900, 4_500] # million km

>>> # Show that a perfect monotonic relationship exists
>>> correlation(orbital_period, dist_from_sun, method='ranked')
1.0

>>> # Observe that a linear relationship is imperfect
>>> round(correlation(orbital_period, dist_from_sun), 4)
0.9882

>>> # Demonstrate Kepler's third law: There is a linear correlation
>>> # between the square of the orbital period and the cube of the
>>> # distance from the sun.
>>> period_squared = [p * p for p in orbital_period]
>>> dist_cubed = [d * d * d for d in dist_from_sun]
>>> round(correlation(period_squared, dist_cubed), 4)
1.0
@end example


Ajouté dans la version 3.10.



Modifié dans la version 3.12: Added support for Spearman's rank correlation coefficient.

@end deffn

@geindex linear_regression() (dans le module statistics)
@anchor{library/statistics statistics linear_regression}@anchor{81b}
@deffn {Fonction} statistics.linear_regression (x, y, /, *, proportional=False)

Return the slope and intercept of simple linear regression@footnote{https://en.wikipedia.org/wiki/Simple_linear_regression}
parameters estimated using ordinary least squares. Simple linear
regression describes the relationship between an independent variable `x' and
a dependent variable `y' in terms of this linear function:

@quotation

`y = slope * x + intercept + noise'
@end quotation

where @code{slope} and @code{intercept} are the regression parameters that are
estimated, and @code{noise} represents the
variability of the data that was not explained by the linear regression
(it is equal to the difference between predicted and actual values
of the dependent variable).

Both inputs must be of the same length (no less than two), and
the independent variable `x' cannot be constant;
otherwise a @ref{2694,,StatisticsError} is raised.

For example, we can use the release dates of the Monty Python films@footnote{https://en.wikipedia.org/wiki/Monty_Python#Films}
to predict the cumulative number of Monty Python films
that would have been produced by 2019
assuming that they had kept the pace.

@example
>>> year = [1971, 1975, 1979, 1982, 1983]
>>> films_total = [1, 2, 3, 4, 5]
>>> slope, intercept = linear_regression(year, films_total)
>>> round(slope * 2019 + intercept)
16
@end example

If `proportional' is true, the independent variable `x' and the
dependent variable `y' are assumed to be directly proportional.
The data is fit to a line passing through the origin.
Since the `intercept' will always be 0.0, the underlying linear
function simplifies to:

@quotation

`y = slope * x + noise'
@end quotation

Continuing the example from @ref{4a5,,correlation()}, we look to see
how well a model based on major planets can predict the orbital
distances for dwarf planets:

@example
>>> model = linear_regression(period_squared, dist_cubed, proportional=True)
>>> slope = model.slope

>>> # Dwarf planets:   Pluto,  Eris,    Makemake, Haumea, Ceres
>>> orbital_periods = [90_560, 204_199, 111_845, 103_410, 1_680]  # days
>>> predicted_dist = [math.cbrt(slope * (p * p)) for p in orbital_periods]
>>> list(map(round, predicted_dist))
[5912, 10166, 6806, 6459, 414]

>>> [5_906, 10_152, 6_796, 6_450, 414]  # actual distance in million km
[5906, 10152, 6796, 6450, 414]
@end example


Ajouté dans la version 3.10.



Modifié dans la version 3.11: Added support for `proportional'.

@end deffn

@node Exceptions<5>,Objets NormalDist,Détails des fonctions,statistics --- Mathematical statistics functions
@anchor{library/statistics exceptions}@anchor{2695}
@subsubsection Exceptions


Une seule exception est définie :

@geindex StatisticsError
@anchor{library/statistics statistics StatisticsError}@anchor{2694}
@deffn {Exception} statistics.StatisticsError

Sous-classe de @ref{1ff,,ValueError} pour les exceptions liées aux statistiques.
@end deffn

@node Objets NormalDist,Examples and Recipes,Exceptions<5>,statistics --- Mathematical statistics functions
@anchor{library/statistics normaldist-objects}@anchor{2696}
@subsubsection Objets @code{NormalDist}


@ref{a26,,NormalDist} est un outil permettant de créer et manipuler des lois normales de variables aléatoires@footnote{https://fr.wikipedia.org/wiki/Variable_al%C3%A9atoire}. Cette classe gère la moyenne et l'écart-type d'un ensemble d'observations comme une seule entité.

Les lois normales apparaissent dans de très nombreuses applications des statistiques. Leur ubiquité découle du théorème central limite@footnote{https://fr.wikipedia.org/wiki/Th%C3%A9or%C3%A8me_central_limite}.

@geindex NormalDist (classe dans statistics)
@anchor{library/statistics statistics NormalDist}@anchor{a26}
@deffn {Classe} statistics.NormalDist (mu=0.0, sigma=1.0)

Renvoie un nouvel objet `NormalDist' où `mu' représente la moyenne arithmétique@footnote{https://fr.wikipedia.org/wiki/Moyenne_arithm%C3%A9tique} et `sigma' l'écart-type@footnote{https://fr.wikipedia.org/wiki/%C3%89cart_type}.

Lève une erreur @ref{2694,,StatisticsError} si `sigma' est négatif.

@geindex mean (attribut statistics.NormalDist)
@anchor{library/statistics statistics NormalDist mean}@anchor{2697}
@deffn {Attribut} mean

Attribut en lecture seule correspondant à la moyenne arithmétique@footnote{https://fr.wikipedia.org/wiki/Moyenne_arithm%C3%A9tique} d'une loi normale.
@end deffn

@geindex median (attribut statistics.NormalDist)
@anchor{library/statistics statistics NormalDist median}@anchor{2698}
@deffn {Attribut} median

Attribut en lecture seule correspondant à la médiane@footnote{https://fr.wikipedia.org/wiki/M%C3%A9diane_(statistiques)} d'une loi normale.
@end deffn

@geindex mode (attribut statistics.NormalDist)
@anchor{library/statistics statistics NormalDist mode}@anchor{2699}
@deffn {Attribut} mode

Attribut en lecture seule correspondant au mode@footnote{https://fr.wikipedia.org/wiki/Mode_(statistiques)} d'une loi normale.
@end deffn

@geindex stdev (attribut statistics.NormalDist)
@anchor{library/statistics statistics NormalDist stdev}@anchor{269a}
@deffn {Attribut} stdev

Attribut en lecture seule correspondant à l'écart-type@footnote{https://fr.wikipedia.org/wiki/%C3%89cart_type} d'une loi normale.
@end deffn

@geindex variance (attribut statistics.NormalDist)
@anchor{library/statistics statistics NormalDist variance}@anchor{269b}
@deffn {Attribut} variance

Attribut en lecture seule correspondant à la variance@footnote{https://fr.wikipedia.org/wiki/Variance} d'une loi normale. La variance est égale au carré de l'écart-type.
@end deffn

@geindex from_samples() (méthode de la classe statistics.NormalDist)
@anchor{library/statistics statistics NormalDist from_samples}@anchor{269c}
@deffn {Méthode} classmethod from_samples (data)

Crée une instance de loi normale de paramètres `mu' et `sigma' estimés à partir de `data' en utilisant @ref{a22,,fmean()} et @ref{6be,,stdev()}.

`data' peut être n'importe quel @ref{1205,,iterable} de valeurs pouvant être converties en @ref{2eb,,float}. Lève une erreur @ref{2694,,StatisticsError} si `data' ne contient pas au moins deux éléments car il faut au moins un point pour estimer la moyenne et deux points pour estimer la variance.
@end deffn

@geindex samples() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist samples}@anchor{269d}
@deffn {Méthode} samples (n, *, seed=None)

Génère `n' valeurs aléatoires suivant une loi normale de moyenne et écart-type connus. Renvoie une @ref{5fc,,list} de @ref{2eb,,float}.

Si `seed' est spécifié, sa valeur est utilisée pour initialiser une nouvelle instance du générateur de nombres aléatoires. Cela permet de produire des résultats reproductibles même dans un contexte de parallélisme par fils d'exécution.


Modifié dans la version 3.13.


Switched to a faster algorithm.  To reproduce samples from previous
versions, use @ref{1252,,random.seed()} and @ref{17cf,,random.gauss()}.
@end deffn

@geindex pdf() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist pdf}@anchor{269e}
@deffn {Méthode} pdf (x)

Calcule la vraisemblance qu'une variable aléatoire `X' soit proche de la valeur `x' à partir de la fonction de densité@footnote{https://fr.wikipedia.org/wiki/Variable_al%C3%A9atoire_%C3%A0_densit%C3%A9}. Mathématiquement, cela correspond à la limite de la fraction @code{P(x <= X < x + dx) / dx} lorsque @code{dx} tend vers zéro.

The relative likelihood is computed as the probability of a sample
occurring in a narrow range divided by the width of the range (hence
the word "density").  Since the likelihood is relative to other points,
its value can be greater than @code{1.0}.
@end deffn

@geindex cdf() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist cdf}@anchor{269f}
@deffn {Méthode} cdf (x)

Calcule la probabilité qu'une variable aléatoire `X' soit inférieure ou égale à `x' à partir de la fonction de répartition@footnote{https://fr.wikipedia.org/wiki/Fonction_de_r%C3%A9partition}. Mathématiquement, cela correspond à @code{P(X <= x)}.
@end deffn

@geindex inv_cdf() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist inv_cdf}@anchor{26a0}
@deffn {Méthode} inv_cdf (p)

Compute the inverse cumulative distribution function, also known as the
quantile function@footnote{https://en.wikipedia.org/wiki/Quantile_function}
or the percent-point@footnote{https://web.archive.org/web/20190203145224/https://www.statisticshowto.datasciencecentral.com/inverse-distribution-function/}
function.  Mathematically, it is written @code{x : P(X <= x) = p}.

Détermine la valeur `x' de la variable aléatoire `X' telle que la probabilité que la variable soit inférieure ou égale à cette valeur `x' est égale à `p'.
@end deffn

@geindex overlap() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist overlap}@anchor{26a1}
@deffn {Méthode} overlap (other)

Mesure le recouvrement entre deux lois normales. Renvoie une valeur réelle entre 0 et 1 indiquant l'aire du recouvrement de deux densités de probabilité@footnote{https://www.rasch.org/rmt/rmt101r.htm}.
@end deffn

@geindex quantiles() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist quantiles}@anchor{26a2}
@deffn {Méthode} quantiles (n=4)

Divise la loi normale entre `n' intervalles réels équiprobables. Renvoie une liste de @code{(n - 1)} quantiles séparant les intervalles.

Utilisez @code{n = 4} pour obtenir les quartiles (le défaut), @code{n = 10} pour obtenir les déciles et @code{n = 100} pour obtenir les centiles (ce qui produit 99 valeurs qui séparent `data' en 100 groupes de même taille).
@end deffn

@geindex zscore() (méthode statistics.NormalDist)
@anchor{library/statistics statistics NormalDist zscore}@anchor{26a3}
@deffn {Méthode} zscore (x)

Compute the
Standard Score@footnote{https://www.statisticshowto.com/probability-and-statistics/z-score/}
describing `x' in terms of the number of standard deviations
above or below the mean of the normal distribution:
@code{(x - mean) / stdev}.


Ajouté dans la version 3.9.

@end deffn

Les instances de la classe @ref{a26,,NormalDist} gèrent l'addition, la soustraction, la multiplication et la division par une constante. Ces opérations peuvent être utilisées pour la translation ou la mise à l'échelle, par exemple :

@example
>>> temperature_february = NormalDist(5, 2.5)             # Celsius
>>> temperature_february * (9/5) + 32                     # Fahrenheit
NormalDist(mu=41.0, sigma=4.5)
@end example

Diviser une constante par une instance de @ref{a26,,NormalDist} n'est pas pris en charge car le résultat ne serait pas une loi normale.

Étant donné que les lois normales sont issues des propriétés additives de variables indépendantes, il est possible d'ajouter ou de soustraite deux variables normales indépendantes@footnote{https://en.wikipedia.org/wiki/Sum_of_normally_distributed_random_variables} représentées par des instances de @ref{a26,,NormalDist}. Par exemple :

@example
>>> birth_weights = NormalDist.from_samples([2.5, 3.1, 2.1, 2.4, 2.7, 3.5])
>>> drug_effects = NormalDist(0.4, 0.15)
>>> combined = birth_weights + drug_effects
>>> round(combined.mean, 1)
3.1
>>> round(combined.stdev, 1)
0.5
@end example


Ajouté dans la version 3.8.

@end deffn

@node Examples and Recipes,,Objets NormalDist,statistics --- Mathematical statistics functions
@anchor{library/statistics examples-and-recipes}@anchor{26a4}
@subsubsection Examples and Recipes


@menu
* Classic probability problems:: 
* Monte Carlo inputs for simulations:: 
* Approximating binomial distributions:: 
* Naive bayesian classifier:: 

@end menu

@node Classic probability problems,Monte Carlo inputs for simulations,,Examples and Recipes
@anchor{library/statistics classic-probability-problems}@anchor{26a5}
@subsubsection Classic probability problems


@ref{a26,,NormalDist} permet de résoudre aisément des problèmes probabilistes classiques.

Par exemple, sachant que les scores aux examens SAT@footnote{https://nces.ed.gov/programs/digest/d17/tables/dt17_226.40.asp} suivent une loi normale de moyenne 1060 et d'écart-type 195, déterminer le pourcentage d'étudiants dont les scores se situent entre 1100 et 1200, arrondi à l'entier le plus proche :

@example
>>> sat = NormalDist(1060, 195)
>>> fraction = sat.cdf(1200 + 0.5) - sat.cdf(1100 - 0.5)
>>> round(fraction * 100.0, 1)
18.4
@end example

Déterminer les quartiles@footnote{https://fr.wikipedia.org/wiki/Quartile} et les déciles@footnote{https://fr.wikipedia.org/wiki/Decile} des scores SAT :

@example
>>> list(map(round, sat.quantiles()))
[928, 1060, 1192]
>>> list(map(round, sat.quantiles(n=10)))
[810, 896, 958, 1011, 1060, 1109, 1162, 1224, 1310]
@end example

@node Monte Carlo inputs for simulations,Approximating binomial distributions,Classic probability problems,Examples and Recipes
@anchor{library/statistics monte-carlo-inputs-for-simulations}@anchor{26a6}
@subsubsection Monte Carlo inputs for simulations


To estimate the distribution for a model that isn't easy to solve
analytically, @ref{a26,,NormalDist} can generate input samples for a Monte Carlo simulation@footnote{https://en.wikipedia.org/wiki/Monte_Carlo_method}:

@example
>>> def model(x, y, z):
...     return (3*x + 7*x*y - 5*y) / (11 * z)
...
>>> n = 100_000
>>> X = NormalDist(10, 2.5).samples(n, seed=3652260728)
>>> Y = NormalDist(15, 1.75).samples(n, seed=4582495471)
>>> Z = NormalDist(50, 1.25).samples(n, seed=6582483453)
>>> quantiles(map(model, X, Y, Z))       
[1.4591308524824727, 1.8035946855390597, 2.175091447274739]
@end example

@node Approximating binomial distributions,Naive bayesian classifier,Monte Carlo inputs for simulations,Examples and Recipes
@anchor{library/statistics approximating-binomial-distributions}@anchor{26a7}
@subsubsection Approximating binomial distributions


Normal distributions can be used to approximate Binomial distributions@footnote{https://mathworld.wolfram.com/BinomialDistribution.html}
when the sample size is large and when the probability of a successful
trial is near 50%.

Par exemple, 750 personnes assistent à une conférence sur le logiciel libre. Il y a deux salles pouvant chacune accueillir 500 personnes. Dans la première salle a lieu une présentation sur Python, dans l'autre une présentation à propos de Ruby. Lors des conférences passées, 65% des personnes ont préféré écouter les présentations sur Python. En supposant que les préférences de la population n'ont pas changé, quelle est la probabilité que la salle Python reste en-dessous de sa capacité d'accueil ?

@example
>>> n = 750             # Sample size
>>> p = 0.65            # Preference for Python
>>> q = 1.0 - p         # Preference for Ruby
>>> k = 500             # Room capacity

>>> # Approximation using the cumulative normal distribution
>>> from math import sqrt
>>> round(NormalDist(mu=n*p, sigma=sqrt(n*p*q)).cdf(k + 0.5), 4)
0.8402

>>> # Exact solution using the cumulative binomial distribution
>>> from math import comb, fsum
>>> round(fsum(comb(n, r) * p**r * q**(n-r) for r in range(k+1)), 4)
0.8402

>>> # Approximation using a simulation
>>> from random import seed, binomialvariate
>>> seed(8675309)
>>> mean(binomialvariate(n, p) <= k for i in range(10_000))
0.8406
@end example

@node Naive bayesian classifier,,Approximating binomial distributions,Examples and Recipes
@anchor{library/statistics naive-bayesian-classifier}@anchor{26a8}
@subsubsection Naive bayesian classifier


Les lois normales interviennent souvent en apprentissage automatique.

Wikipedia has a nice example of a Naive Bayesian Classifier@footnote{https://en.wikipedia.org/wiki/Naive_Bayes_classifier#Person_classification}.
The challenge is to predict a person's gender from measurements of normally
distributed features including height, weight, and foot size.

Nous avons à notre disposition un jeu de données d'apprentissage contenant les mesures de huit personnes. On suppose que ces mesures suivent une loi normale. Nous pouvons donc synthétiser les données à l'aide de @ref{a26,,NormalDist} :

@example
>>> height_male = NormalDist.from_samples([6, 5.92, 5.58, 5.92])
>>> height_female = NormalDist.from_samples([5, 5.5, 5.42, 5.75])
>>> weight_male = NormalDist.from_samples([180, 190, 170, 165])
>>> weight_female = NormalDist.from_samples([100, 150, 130, 150])
>>> foot_size_male = NormalDist.from_samples([12, 11, 12, 10])
>>> foot_size_female = NormalDist.from_samples([6, 8, 7, 9])
@end example

Ensuite, nous rencontrons un nouvel individu dont nous connaissons les proportions mais pas le sexe :

@example
>>> ht = 6.0        # height
>>> wt = 130        # weight
>>> fs = 8          # foot size
@end example

En partant d'une probabilité a priori@footnote{https://fr.wikipedia.org/wiki/Th%C3%A9or%C3%A8me_de_Bayes} de 50% d'être un homme ou une femme, nous calculons la probabilité a posteriori comme le produit de la probabilité antérieure et de la vraisemblance des différentes mesures étant donné le sexe :

@example
>>> prior_male = 0.5
>>> prior_female = 0.5
>>> posterior_male = (prior_male * height_male.pdf(ht) *
...                   weight_male.pdf(wt) * foot_size_male.pdf(fs))

>>> posterior_female = (prior_female * height_female.pdf(ht) *
...                     weight_female.pdf(wt) * foot_size_female.pdf(fs))
@end example

La prédiction finale est celle qui a la plus grande probabilité a posteriori. Cette approche est appelée maximum a posteriori@footnote{https://fr.wikipedia.org/wiki/Maximum_a_posteriori} ou MAP :

@example
>>> 'male' if posterior_male > posterior_female else 'female'
'female'
@end example

@c # This modelines must appear within the last ten lines of the file.
@c kate: indent-width 3; remove-trailing-space on; replace-tabs on; encoding utf-8;

@node Modules de programmation fonctionnelle,Accès aux Fichiers et aux Dossiers,Modules numériques et mathématiques,La bibliothèque standard
@anchor{library/functional doc}@anchor{26a9}@anchor{library/functional functional-programming-modules}@anchor{26aa}
@section Modules de programmation fonctionnelle


Les modules décrits dans ce chapitre fournissent des fonctions et des classes permettant d'adopter un style fonctionnel, ainsi que des manipulations sur des appelables.

Les modules suivants sont documentés dans ce chapitre :

@menu
* itertools: itertools --- Functions creating iterators for efficient looping. Functions creating iterators for efficient looping
* functools: functools --- Higher-order functions and operations on callable objects. Higher-order functions and operations on callable
                        objects
* operator — Opérateurs standards en tant que fonctions:: 

@end menu

@node itertools --- Functions creating iterators for efficient looping,functools --- Higher-order functions and operations on callable objects,,Modules de programmation fonctionnelle
@anchor{library/itertools doc}@anchor{26ab}@anchor{library/itertools itertools-functions-creating-iterators-for-efficient-looping}@anchor{26ac}@anchor{library/itertools module-itertools}@anchor{80}
@subsection @code{itertools} --- Functions creating iterators for efficient looping


@geindex module; itertools

@c from itertools import *
@c import collections
@c import math
@c import operator
@c import random


__________________________________________________________________


Ce module implémente de nombreuses briques @ref{1aa,,d'itérateurs} inspirées par des éléments de APL, Haskell et SML. Toutes ont été retravaillées dans un format adapté à Python.

Ce module standardise un ensemble de base d'outils rapides et efficaces en mémoire qui peuvent être utilisés individuellement ou en les combinant. Ensemble, ils forment une « algèbre d'itérateurs » rendant possible la construction rapide et efficace d'outils spécialisés en Python.

Par exemple, SML fournit un outil de tabulation @code{tabulate(f)} qui produit  une séquence @code{f(0), f(1), ...}. Le même résultat peut être obtenu en Python en combinant @ref{84e,,map()} et @ref{1261,,count()} pour former @code{map(f, count())}.

`Itérateurs infinis :'


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Itérateur

@tab

Arguments

@tab

Résultats

@tab

Exemple

@item

@ref{1261,,count()}

@tab

@code{[start[, step]]}

@tab

@code{start, start+step, start+2*step, ...}

@tab

@code{count(10) → 10 11 12 13 14 ...}

@item

@ref{26ad,,cycle()}

@tab

p

@tab

p0, p1, ... plast, p0, p1, ...

@tab

@code{cycle('ABCD') → A B C D A B C D ...}

@item

@ref{26ae,,repeat()}

@tab

elem [,n]

@tab

`elem', `elem', `elem', ... à l'infini ou jusqu'à n fois

@tab

@code{repeat(10, 3) → 10 10 10}

@end multitable


`Itérateurs se terminant par la séquence d'entrée la plus courte :'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Itérateur

@tab

Arguments

@tab

Résultats

@tab

Exemple

@item

@ref{9eb,,accumulate()}

@tab

p [,func]

@tab

p0, p0+p1, p0+p1+p2, ...

@tab

@code{accumulate([1,2,3,4,5]) → 1 3 6 10 15}

@item

@ref{1fe,,batched()}

@tab

p, n

@tab

(p0, p1, ..., p_n-1), ...

@tab

@code{batched('ABCDEFG', n=3) → ABC DEF G}

@item

@ref{2108,,chain()}

@tab

p, q, ...

@tab

p0, p1, ... plast, q0, q1, ...

@tab

@code{chain('ABC', 'DEF') → A B C D E F}

@item

@ref{26af,,chain.from_iterable()}

@tab

itérable

@tab

p0, p1, ... plast, q0, q1, ...

@tab

@code{chain.from_iterable(['ABC', 'DEF']) → A B C D E F}

@item

@ref{1260,,compress()}

@tab

data, selectors

@tab

(d[0] if s[0]), (d[1] if s[1]), ...

@tab

@code{compress('ABCDEF', [1,0,1,0,1,1]) → A C E F}

@item

@ref{26b0,,dropwhile()}

@tab

@code{predicate, seq}

@tab

seq[n], seq[n+1], starting when predicate fails

@tab

@code{dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8}

@item

@ref{20ef,,filterfalse()}

@tab

@code{predicate, seq}

@tab

elements of seq where predicate(elem) fails

@tab

@code{filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8}

@item

@ref{26b1,,groupby()}

@tab

iterable[, key]

@tab

sous-itérateurs groupés par la valeur de `key(v)'

@tab

@code{groupby(['A','B','DEF'], len) → (1, A B) (3, DEF)}

@item

@ref{b3a,,islice()}

@tab

seq, [start,] stop [, step]

@tab

éléments de @code{seq[start:stop:step]}

@tab

@code{islice('ABCDEFG', 2, None) → C D E F G}

@item

@ref{7ff,,pairwise()}

@tab

itérable

@tab

(p[0], p[1]), (p[1], p[2])

@tab

@code{pairwise('ABCDEFG') → AB BC CD DE EF FG}

@item

@ref{10c5,,starmap()}

@tab

func, seq

@tab

func(*seq[0]), func(*seq[1]), ...

@tab

@code{starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000}

@item

@ref{26b2,,takewhile()}

@tab

@code{predicate, seq}

@tab

seq[0], seq[1], until predicate fails

@tab

@code{takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4}

@item

@ref{26b3,,tee()}

@tab

it, n

@tab

`it1', `it2', ... `itn' sépare un itérateur en `n'

@tab

@item

@ref{127b,,zip_longest()}

@tab

p, q, ...

@tab

(p[0], q[0]), (p[1], q[1]), ...

@tab

@code{zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-}

@end multitable


`Itérateurs combinatoires :'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Itérateur

@tab

Arguments

@tab

Résultats

@item

@ref{12f1,,product()}

@tab

p, q, ... [repeat=1]

@tab

produit cartésien, équivalent à une boucle `for' imbriquée

@item

@ref{18a8,,permutations()}

@tab

p[, r]

@tab

`n'-uplets de longueur r, tous les ré-arrangements possibles, sans répétition d'éléments

@item

@ref{12f0,,combinations()}

@tab

p, r

@tab

`n'-uplets de longueur r, ordonnés, sans répétition d'éléments

@item

@ref{125f,,combinations_with_replacement()}

@tab

p, r

@tab

`n'-uplets de longueur r, ordonnés, avec répétition d'éléments

@end multitable



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Exemples

@tab

Résultats

@item

@code{product('ABCD', repeat=2)}

@tab

@code{AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD}

@item

@code{permutations('ABCD', 2)}

@tab

@code{AB AC AD BA BC BD CA CB CD DA DB DC}

@item

@code{combinations('ABCD', 2)}

@tab

@code{AB AC AD BC BD CD}

@item

@code{combinations_with_replacement('ABCD', 2)}

@tab

@code{AA AB AC AD BB BC BD CC CD DD}

@end multitable


@menu
* Itertool Functions:: 
* Recettes itertools:: 

@end menu

@node Itertool Functions,Recettes itertools,,itertools --- Functions creating iterators for efficient looping
@anchor{library/itertools itertool-functions}@anchor{26b4}@anchor{library/itertools itertools-functions}@anchor{26b5}
@subsubsection Itertool Functions


The following functions all construct and return iterators. Some provide
streams of infinite length, so they should only be accessed by functions or
loops that truncate the stream.

@geindex accumulate() (dans le module itertools)
@anchor{library/itertools itertools accumulate}@anchor{9eb}
@deffn {Fonction} itertools.accumulate (iterable[, function, *, initial=None])

Make an iterator that returns accumulated sums or accumulated
results from other binary functions.

The `function' defaults to addition.  The `function' should accept
two arguments, an accumulated total and a value from the `iterable'.

If an `initial' value is provided, the accumulation will start with
that value and the output will have one more element than the input
iterable.

À peu près équivalent à :

@example
def accumulate(iterable, function=operator.add, *, initial=None):
    'Return running totals'
    # accumulate([1,2,3,4,5]) → 1 3 6 10 15
    # accumulate([1,2,3,4,5], initial=100) → 100 101 103 106 110 115
    # accumulate([1,2,3,4,5], operator.mul) → 1 2 6 24 120

    iterator = iter(iterable)
    total = initial
    if initial is None:
        try:
            total = next(iterator)
        except StopIteration:
            return

    yield total
    for element in iterator:
        total = function(total, element)
        yield total
@end example

To compute a running minimum, set `function' to @ref{ef3,,min()}.
For a running maximum, set `function' to @ref{ef4,,max()}.
Or for a running product, set `function' to @ref{26b6,,operator.mul()}.
To build an amortization table@footnote{https://www.ramseysolutions.com/real-estate/amortization-schedule},
accumulate the interest and apply payments:

@example
>>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
>>> list(accumulate(data, max))              # running maximum
[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]
>>> list(accumulate(data, operator.mul))     # running product
[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]

# Amortize a 5% loan of 1000 with 10 annual payments of 90
>>> update = lambda balance, payment: round(balance * 1.05) - payment
>>> list(accumulate(repeat(90, 10), update, initial=1_000))
[1000, 960, 918, 874, 828, 779, 728, 674, 618, 559, 497]
@end example

Voir @ref{12ba,,functools.reduce()} pour une fonction similaire qui ne renvoie que la valeur accumulée finale.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: Added the optional `function' parameter.



Modifié dans la version 3.8: Ajout du paramètre optionnel `initial'.

@end deffn

@geindex batched() (dans le module itertools)
@anchor{library/itertools itertools batched}@anchor{1fe}
@deffn {Fonction} itertools.batched (iterable, n, *, strict=False)

Batch data from the `iterable' into tuples of length `n'. The last
batch may be shorter than `n'.

If `strict' is true, will raise a @ref{1ff,,ValueError} if the final
batch is shorter than `n'.

Loops over the input iterable and accumulates data into tuples up to
size `n'.  The input is consumed lazily, just enough to fill a batch.
The result is yielded as soon as the batch is full or when the input
iterable is exhausted:

@example
>>> flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
>>> unflattened = list(batched(flattened_data, 2))
>>> unflattened
[('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')]
@end example

À peu près équivalent à :

@example
def batched(iterable, n, *, strict=False):
    # batched('ABCDEFG', 3) → ABC DEF G
    if n < 1:
        raise ValueError('n must be at least one')
    iterator = iter(iterable)
    while batch := tuple(islice(iterator, n)):
        if strict and len(batch) != n:
            raise ValueError('batched(): incomplete batch')
        yield batch
@end example


Ajouté dans la version 3.12.



Modifié dans la version 3.13: Added the `strict' option.

@end deffn

@geindex chain() (dans le module itertools)
@anchor{library/itertools itertools chain}@anchor{2108}
@deffn {Fonction} itertools.chain (*iterables)

Make an iterator that returns elements from the first iterable until
it is exhausted, then proceeds to the next iterable, until all of the
iterables are exhausted.  This combines multiple data sources into a
single iterator.  Roughly equivalent to:

@example
def chain(*iterables):
    # chain('ABC', 'DEF') → A B C D E F
    for iterable in iterables:
        yield from iterable
@end example
@end deffn

@geindex from_iterable() (méthode de la classe itertools.chain)
@anchor{library/itertools itertools chain from_iterable}@anchor{26af}
@deffn {Méthode} classmethod chain.from_iterable (iterable)

Constructeur alternatif pour @ref{2108,,chain()}. Récupère des entrées chaînées depuis un unique itérable passé en argument, qui est évalué de manière paresseuse. À peu près équivalent à :

@example
def from_iterable(iterables):
    # chain.from_iterable(['ABC', 'DEF']) → A B C D E F
    for iterable in iterables:
        yield from iterable
@end example
@end deffn

@geindex combinations() (dans le module itertools)
@anchor{library/itertools itertools combinations}@anchor{12f0}
@deffn {Fonction} itertools.combinations (iterable, r)

Renvoie les combinaisons de longueur `r' de `iterable'.

The output is a subsequence of @ref{12f1,,product()} keeping only entries that
are subsequences of the `iterable'.  The length of the output is given
by @ref{6ba,,math.comb()} which computes @code{n! / r! / (n - r)!} when @code{0 ≤ r
≤ n} or zero when @code{r > n}.

The combination tuples are emitted in lexicographic order according to
the order of the input `iterable'. If the input `iterable' is sorted,
the output tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their
value.  If the input elements are unique, there will be no repeated
values within each combination.

À peu près équivalent à :

@example
def combinations(iterable, r):
    # combinations('ABCD', 2) → AB AC AD BC BD CD
    # combinations(range(4), 3) → 012 013 023 123

    pool = tuple(iterable)
    n = len(pool)
    if r > n:
        return
    indices = list(range(r))

    yield tuple(pool[i] for i in indices)
    while True:
        for i in reversed(range(r)):
            if indices[i] != i + n - r:
                break
        else:
            return
        indices[i] += 1
        for j in range(i+1, r):
            indices[j] = indices[j-1] + 1
        yield tuple(pool[i] for i in indices)
@end example
@end deffn

@geindex combinations_with_replacement() (dans le module itertools)
@anchor{library/itertools itertools combinations_with_replacement}@anchor{125f}
@deffn {Fonction} itertools.combinations_with_replacement (iterable, r)

Renvoyer les sous-séquences de longueur `r' des éléments de l'itérable `iterable' d'entrée, permettant aux éléments individuels d'être répétés plus d'une fois.

The output is a subsequence of @ref{12f1,,product()} that keeps only entries
that are subsequences (with possible repeated elements) of the
`iterable'.  The number of subsequence returned is @code{(n + r - 1)! / r! /
(n - 1)!} when @code{n > 0}.

The combination tuples are emitted in lexicographic order according to
the order of the input `iterable'. if the input `iterable' is sorted,
the output tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their
value.  If the input elements are unique, the generated combinations
will also be unique.

À peu près équivalent à :

@example
def combinations_with_replacement(iterable, r):
    # combinations_with_replacement('ABC', 2) → AA AB AC BB BC CC

    pool = tuple(iterable)
    n = len(pool)
    if not n and r:
        return
    indices = [0] * r

    yield tuple(pool[i] for i in indices)
    while True:
        for i in reversed(range(r)):
            if indices[i] != n - 1:
                break
        else:
            return
        indices[i:] = [indices[i] + 1] * (r - i)
        yield tuple(pool[i] for i in indices)
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex compress() (dans le module itertools)
@anchor{library/itertools itertools compress}@anchor{1260}
@deffn {Fonction} itertools.compress (data, selectors)

Make an iterator that returns elements from `data' where the
corresponding element in `selectors' is true.  Stops when either the
`data' or `selectors' iterables have been exhausted.  Roughly
equivalent to:

@example
def compress(data, selectors):
    # compress('ABCDEF', [1,0,1,0,1,1]) → A C E F
    return (datum for datum, selector in zip(data, selectors) if selector)
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex count() (dans le module itertools)
@anchor{library/itertools itertools count}@anchor{1261}
@deffn {Fonction} itertools.count (start=0, step=1)

Make an iterator that returns evenly spaced values beginning with
`start'. Can be used with @ref{84e,,map()} to generate consecutive data
points or with @ref{7ba,,zip()} to add sequence numbers.  Roughly
equivalent to:

@example
def count(start=0, step=1):
    # count(10) → 10 11 12 13 14 ...
    # count(2.5, 0.5) → 2.5 3.0 3.5 ...
    n = start
    while True:
        yield n
        n += step
@end example

When counting with floating-point numbers, better accuracy can sometimes be
achieved by substituting multiplicative code such as: @code{(start + step * i
for i in count())}.


Modifié dans la version 3.1: Ajout de l'argument `step' et ajout du support pour les arguments non-entiers.

@end deffn

@geindex cycle() (dans le module itertools)
@anchor{library/itertools itertools cycle}@anchor{26ad}
@deffn {Fonction} itertools.cycle (iterable)

Make an iterator returning elements from the `iterable' and saving a
copy of each.  When the iterable is exhausted, return elements from
the saved copy.  Repeats indefinitely.  Roughly equivalent to:

@example
def cycle(iterable):
    # cycle('ABCD') → A B C D A B C D A B C D ...

    saved = []
    for element in iterable:
        yield element
        saved.append(element)

    while saved:
        for element in saved:
            yield element
@end example

This itertool may require significant auxiliary storage (depending on
the length of the iterable).
@end deffn

@geindex dropwhile() (dans le module itertools)
@anchor{library/itertools itertools dropwhile}@anchor{26b0}
@deffn {Fonction} itertools.dropwhile (predicate, iterable)

Make an iterator that drops elements from the `iterable' while the
`predicate' is true and afterwards returns every element.  Roughly
equivalent to:

@example
def dropwhile(predicate, iterable):
    # dropwhile(lambda x: x<5, [1,4,6,3,8]) → 6 3 8

    iterator = iter(iterable)
    for x in iterator:
        if not predicate(x):
            yield x
            break

    for x in iterator:
        yield x
@end example

Note this does not produce `any' output until the predicate first
becomes false, so this itertool may have a lengthy start-up time.
@end deffn

@geindex filterfalse() (dans le module itertools)
@anchor{library/itertools itertools filterfalse}@anchor{20ef}
@deffn {Fonction} itertools.filterfalse (predicate, iterable)

Make an iterator that filters elements from the `iterable' returning
only those for which the `predicate' returns a false value.  If
`predicate' is @code{None}, returns the items that are false.  Roughly
equivalent to:

@example
def filterfalse(predicate, iterable):
    # filterfalse(lambda x: x<5, [1,4,6,3,8]) → 6 8

    if predicate is None:
        predicate = bool

    for x in iterable:
        if not predicate(x):
            yield x
@end example
@end deffn

@geindex groupby() (dans le module itertools)
@anchor{library/itertools itertools groupby}@anchor{26b1}
@deffn {Fonction} itertools.groupby (iterable, key=None)

Crée un itérateur qui renvoie les clés et les groupes de l'itérable `iterable'. La clé `key' est une fonction qui génère une clé pour chaque élément. Si `key' n'est pas spécifiée ou est @code{None}, elle vaut par défaut une fonction d'identité qui renvoie l'élément sans le modifier. Généralement, l'itérable a besoin d'avoir ses éléments déjà classés selon cette même fonction de clé.

L'opération de  @ref{26b1,,groupby()} est similaire au filtre @code{uniq} dans Unix. Elle génère un nouveau groupe à chaque fois que la valeur de la fonction `key' change (ce pourquoi il est souvent nécessaire d'avoir trié les données selon la même fonction de clé).  Ce comportement est différent de celui de GROUP BY de SQL qui agrège les éléments sans prendre compte de leur ordre d'entrée.

Le groupe renvoyé est lui-même un itérateur qui partage l'itérable sous-jacent avec @ref{26b1,,groupby()}. Puisque que la source est partagée, quand l'objet @ref{26b1,,groupby()} est avancé, le groupe précédent n'est plus visible. Ainsi, si cette donnée doit être utilisée plus tard, elle doit être stockée comme une liste :

@example
groups = []
uniquekeys = []
data = sorted(data, key=keyfunc)
for k, g in groupby(data, keyfunc):
    groups.append(list(g))      # Store group iterator as a list
    uniquekeys.append(k)
@end example

@ref{26b1,,groupby()} est à peu près équivalente à :

@example
def groupby(iterable, key=None):
    # [k for k, g in groupby('AAAABBBCCDAABBB')] → A B C D A B
    # [list(g) for k, g in groupby('AAAABBBCCD')] → AAAA BBB CC D

    keyfunc = (lambda x: x) if key is None else key
    iterator = iter(iterable)
    exhausted = False

    def _grouper(target_key):
        nonlocal curr_value, curr_key, exhausted
        yield curr_value
        for curr_value in iterator:
            curr_key = keyfunc(curr_value)
            if curr_key != target_key:
                return
            yield curr_value
        exhausted = True

    try:
        curr_value = next(iterator)
    except StopIteration:
        return
    curr_key = keyfunc(curr_value)

    while not exhausted:
        target_key = curr_key
        curr_group = _grouper(target_key)
        yield curr_key, curr_group
        if curr_key == target_key:
            for _ in curr_group:
                pass
@end example
@end deffn

@geindex islice() (dans le module itertools)
@anchor{library/itertools itertools islice}@anchor{b3a}
@deffn {Fonction} itertools.islice (iterable, stop)

@deffnx {Fonction} itertools.islice (iterable, start, stop[, step])

Make an iterator that returns selected elements from the iterable.
Works like sequence slicing but does not support negative values for
`start', `stop', or `step'.

If `start' is zero or @code{None}, iteration starts at zero.  Otherwise,
elements from the iterable are skipped until `start' is reached.

If `stop' is @code{None}, iteration continues until the input is
exhausted, if at all.  Otherwise, it stops at the specified position.

If `step' is @code{None}, the step defaults to one.  Elements are returned
consecutively unless `step' is set higher than one which results in
items being skipped.

À peu près équivalent à :

@example
def islice(iterable, *args):
    # islice('ABCDEFG', 2) → A B
    # islice('ABCDEFG', 2, 4) → C D
    # islice('ABCDEFG', 2, None) → C D E F G
    # islice('ABCDEFG', 0, None, 2) → A C E G

    s = slice(*args)
    start = 0 if s.start is None else s.start
    stop = s.stop
    step = 1 if s.step is None else s.step
    if start < 0 or (stop is not None and stop < 0) or step <= 0:
        raise ValueError

    indices = count() if stop is None else range(max(start, stop))
    next_i = start
    for i, element in zip(indices, iterable):
        if i == next_i:
            yield element
            next_i += step
@end example

If the input is an iterator, then fully consuming the `islice'
advances the input iterator by @code{max(start, stop)} steps regardless
of the `step' value.
@end deffn

@geindex pairwise() (dans le module itertools)
@anchor{library/itertools itertools pairwise}@anchor{7ff}
@deffn {Fonction} itertools.pairwise (iterable)

Renvoie des paires successives d'éléments consécutifs de `iterable'.

En toute logique, il y a une paire de moins que d'éléments dans l'itérable. Aucune paire n'est renvoyée si l'itérable a zéro ou une valeur.

À peu près équivalent à :

@example
def pairwise(iterable):
    # pairwise('ABCDEFG') → AB BC CD DE EF FG

    iterator = iter(iterable)
    a = next(iterator, None)

    for b in iterator:
        yield a, b
        a = b
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex permutations() (dans le module itertools)
@anchor{library/itertools itertools permutations}@anchor{18a8}
@deffn {Fonction} itertools.permutations (iterable, r=None)

Return successive `r' length permutations of elements@footnote{https://www.britannica.com/science/permutation} from the `iterable'.

Si `r' n'est pas spécifié ou vaut @code{None}, alors `r' a pour valeur la longueur de `iterable' et toutes les permutations de longueur `r' possibles sont générées.

The output is a subsequence of @ref{12f1,,product()} where entries with
repeated elements have been filtered out.  The length of the output is
given by @ref{6bb,,math.perm()} which computes @code{n! / (n - r)!} when
@code{0 ≤ r ≤ n} or zero when @code{r > n}.

The permutation tuples are emitted in lexicographic order according to
the order of the input `iterable'.  If the input `iterable' is sorted,
the output tuples will be produced in sorted order.

Elements are treated as unique based on their position, not on their
value.  If the input elements are unique, there will be no repeated
values within a permutation.

À peu près équivalent à :

@example
def permutations(iterable, r=None):
    # permutations('ABCD', 2) → AB AC AD BA BC BD CA CB CD DA DB DC
    # permutations(range(3)) → 012 021 102 120 201 210

    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    if r > n:
        return

    indices = list(range(n))
    cycles = list(range(n, n-r, -1))
    yield tuple(pool[i] for i in indices[:r])

    while n:
        for i in reversed(range(r)):
            cycles[i] -= 1
            if cycles[i] == 0:
                indices[i:] = indices[i+1:] + indices[i:i+1]
                cycles[i] = n - i
            else:
                j = cycles[i]
                indices[i], indices[-j] = indices[-j], indices[i]
                yield tuple(pool[i] for i in indices[:r])
                break
        else:
            return
@end example
@end deffn

@geindex product() (dans le module itertools)
@anchor{library/itertools itertools product}@anchor{12f1}
@deffn {Fonction} itertools.product (*iterables, repeat=1)

Cartesian product@footnote{https://en.wikipedia.org/wiki/Cartesian_product}
of the input iterables.

À peu près équivalent à des boucles `for' imbriquées dans une expression de générateur. Par exemple @code{product(A, B)} renvoie la même chose que @code{((x, y) for x in A for y in B)}.

Les boucles imbriquées tournent comme un compteur kilométrique avec l'élément le plus à droite avançant à chaque itération. Ce motif défini un ordre lexicographique afin que, si les éléments des itérables en l'entrée sont ordonnés, les `n'-uplets produits le sont aussi.

Pour générer le produit d'un itérable avec lui-même, spécifiez le nombre de répétitions avec le paramètre nommé optionnel `repeat'. Par exemple, @code{product(A, repeat=4)} est équivalent à @code{product(A, A, A, A)}.

Cette fonction est à peu près équivalente au code suivant, à la différence près que la vraie implémentation ne crée pas de résultats intermédiaires en mémoire :

@example
def product(*iterables, repeat=1):
    # product('ABCD', 'xy') → Ax Ay Bx By Cx Cy Dx Dy
    # product(range(2), repeat=3) → 000 001 010 011 100 101 110 111

    if repeat < 0:
        raise ValueError('repeat argument cannot be negative')
    pools = [tuple(pool) for pool in iterables] * repeat

    result = [[]]
    for pool in pools:
        result = [x+[y] for x in result for y in pool]

    for prod in result:
        yield tuple(prod)
@end example

@ref{12f1,,product()} commence par consommer totalement les itérables qui lui sont passés et les conserve en mémoire pour générer les produits. Par conséquent, cette fonction ne sert que sur des itérables finis.
@end deffn

@geindex repeat() (dans le module itertools)
@anchor{library/itertools itertools repeat}@anchor{26ae}
@deffn {Fonction} itertools.repeat (object[, times])

Crée un itérateur qui renvoie `object' à l'infini. S'exécute indéfiniment sauf si l'argument `times' est spécifié.

À peu près équivalent à :

@example
def repeat(object, times=None):
    # repeat(10, 3) → 10 10 10
    if times is None:
        while True:
            yield object
    else:
        for i in range(times):
            yield object
@end example

Une utilisation courante de `repeat' est de fournir un flux constant de valeurs à `map' ou `zip' :

@example
>>> list(map(pow, range(10), repeat(2)))
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
@end example
@end deffn

@geindex starmap() (dans le module itertools)
@anchor{library/itertools itertools starmap}@anchor{10c5}
@deffn {Fonction} itertools.starmap (function, iterable)

Make an iterator that computes the `function' using arguments obtained
from the `iterable'.  Used instead of @ref{84e,,map()} when argument
parameters have already been "pre-zipped" into tuples.

The difference between @ref{84e,,map()} and @ref{10c5,,starmap()} parallels the
distinction between @code{function(a,b)} and @code{function(*c)}. Roughly
equivalent to:

@example
def starmap(function, iterable):
    # starmap(pow, [(2,5), (3,2), (10,3)]) → 32 9 1000
    for args in iterable:
        yield function(*args)
@end example
@end deffn

@geindex takewhile() (dans le module itertools)
@anchor{library/itertools itertools takewhile}@anchor{26b2}
@deffn {Fonction} itertools.takewhile (predicate, iterable)

Make an iterator that returns elements from the `iterable' as long as
the `predicate' is true.  Roughly equivalent to:

@example
def takewhile(predicate, iterable):
    # takewhile(lambda x: x<5, [1,4,6,3,8]) → 1 4
    for x in iterable:
        if not predicate(x):
            break
        yield x
@end example

Note, the element that first fails the predicate condition is
consumed from the input iterator and there is no way to access it.
This could be an issue if an application wants to further consume the
input iterator after `takewhile' has been run to exhaustion.  To work
around this problem, consider using more-itertools before_and_after()@footnote{https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.before_and_after}
instead.
@end deffn

@geindex tee() (dans le module itertools)
@anchor{library/itertools itertools tee}@anchor{26b3}
@deffn {Fonction} itertools.tee (iterable, n=2)

Renvoie `n' itérateurs indépendants depuis un unique itérable.

À peu près équivalent à :

@example
def tee(iterable, n=2):
    if n < 0:
        raise ValueError
    if n == 0:
        return ()
    iterator = _tee(iterable)
    result = [iterator]
    for _ in range(n - 1):
        result.append(_tee(iterator))
    return tuple(result)

class _tee:

    def __init__(self, iterable):
        it = iter(iterable)
        if isinstance(it, _tee):
            self.iterator = it.iterator
            self.link = it.link
        else:
            self.iterator = it
            self.link = [None, None]

    def __iter__(self):
        return self

    def __next__(self):
        link = self.link
        if link[1] is None:
            link[0] = next(self.iterator)
            link[1] = [None, None]
        value, self.link = link
        return value
@end example

When the input `iterable' is already a tee iterator object, all
members of the return tuple are constructed as if they had been
produced by the upstream @ref{26b3,,tee()} call.  This "flattening step"
allows nested @ref{26b3,,tee()} calls to share the same underlying data
chain and to have a single update step rather than a chain of calls.

The flattening property makes tee iterators efficiently peekable:

@example
def lookahead(tee_iterator):
     "Return the next value without moving the input forward"
     [forked_iterator] = tee(tee_iterator, 1)
     return next(forked_iterator)
@end example

@example
>>> iterator = iter('abcdef')
>>> [iterator] = tee(iterator, 1)   # Make the input peekable
>>> next(iterator)                  # Move the iterator forward
'a'
>>> lookahead(iterator)             # Check next value
'b'
>>> next(iterator)                  # Continue moving forward
'b'
@end example

@code{tee} iterators are not threadsafe. A @ref{193,,RuntimeError} may be
raised when simultaneously using iterators returned by the same @ref{26b3,,tee()}
call, even if the original `iterable' is threadsafe.

Cet outil peut avoir besoin d'un stockage auxiliaire important (en fonction de la taille des données temporaires nécessaires). En général, si un itérateur utilise la majorité ou toute la donnée avant qu'un autre itérateur ne commence, il est plus rapide d'utiliser @ref{5fc,,list()} à la place de @ref{26b3,,tee()}.
@end deffn

@geindex zip_longest() (dans le module itertools)
@anchor{library/itertools itertools zip_longest}@anchor{127b}
@deffn {Fonction} itertools.zip_longest (*iterables, fillvalue=None)

Make an iterator that aggregates elements from each of the
`iterables'.

If the iterables are of uneven length, missing values are filled-in
with `fillvalue'.  If not specified, `fillvalue' defaults to @code{None}.

Iteration continues until the longest iterable is exhausted.

À peu près équivalent à :

@example
def zip_longest(*iterables, fillvalue=None):
    # zip_longest('ABCD', 'xy', fillvalue='-') → Ax By C- D-

    iterators = list(map(iter, iterables))
    num_active = len(iterators)
    if not num_active:
        return

    while True:
        values = []
        for i, iterator in enumerate(iterators):
            try:
                value = next(iterator)
            except StopIteration:
                num_active -= 1
                if not num_active:
                    return
                iterators[i] = repeat(fillvalue)
                value = fillvalue
            values.append(value)
        yield tuple(values)
@end example

If one of the iterables is potentially infinite, then the @ref{127b,,zip_longest()}
function should be wrapped with something that limits the number of calls
(for example @ref{b3a,,islice()} or @ref{26b2,,takewhile()}).
@end deffn

@node Recettes itertools,,Itertool Functions,itertools --- Functions creating iterators for efficient looping
@anchor{library/itertools id1}@anchor{26b7}@anchor{library/itertools itertools-recipes}@anchor{123d}
@subsubsection Recettes `itertools'


Cette section présente des recettes pour créer une vaste boîte à outils en se servant des `itertools' existants comme des briques.

The primary purpose of the itertools recipes is educational.  The recipes show
various ways of thinking about individual tools — for example, that
@code{chain.from_iterable} is related to the concept of flattening.  The recipes
also give ideas about ways that the tools can be combined — for example, how
@code{starmap()} and @code{repeat()} can work together.  The recipes also show patterns
for using itertools with the @ref{9e,,operator} and @ref{1d,,collections} modules as
well as with the built-in itertools such as @code{map()}, @code{filter()},
@code{reversed()}, and @code{enumerate()}.

A secondary purpose of the recipes is to serve as an incubator.  The
@code{accumulate()}, @code{compress()}, and @code{pairwise()} itertools started out as
recipes.  Currently, the @code{sliding_window()}, @code{iter_index()}, and @code{sieve()}
recipes are being tested to see whether they prove their worth.

Substantially all of these recipes and many, many others can be installed from
the more-itertools@footnote{https://pypi.org/project/more-itertools/} project found
on the Python Package Index:

@example
python -m pip install more-itertools
@end example

Many of the recipes offer the same high performance as the underlying toolset.
Superior memory performance is kept by processing elements one at a time rather
than bringing the whole iterable into memory all at once. Code volume is kept
small by linking the tools together in a functional style@footnote{https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf}.  High speed
is retained by preferring "vectorized" building blocks over the use of for-loops
and @ref{104a,,generators} which incur interpreter overhead.

@example
from collections import deque
from contextlib import suppress
from functools import reduce
from math import sumprod, isqrt
from operator import itemgetter, getitem, mul, neg

def take(n, iterable):
    "Return first n items of the iterable as a list."
    return list(islice(iterable, n))

def prepend(value, iterable):
    "Prepend a single value in front of an iterable."
    # prepend(1, [2, 3, 4]) → 1 2 3 4
    return chain([value], iterable)

def tabulate(function, start=0):
    "Return function(0), function(1), ..."
    return map(function, count(start))

def repeatfunc(function, times=None, *args):
    "Repeat calls to a function with specified arguments."
    if times is None:
        return starmap(function, repeat(args))
    return starmap(function, repeat(args, times))

def flatten(list_of_lists):
    "Flatten one level of nesting."
    return chain.from_iterable(list_of_lists)

def ncycles(iterable, n):
    "Returns the sequence elements n times."
    return chain.from_iterable(repeat(tuple(iterable), n))

def loops(n):
    "Loop n times. Like range(n) but without creating integers."
    # for _ in loops(100): ...
    return repeat(None, n)

def tail(n, iterable):
    "Return an iterator over the last n items."
    # tail(3, 'ABCDEFG') → E F G
    return iter(deque(iterable, maxlen=n))

def consume(iterator, n=None):
    "Advance the iterator n-steps ahead. If n is None, consume entirely."
    # Use functions that consume iterators at C speed.
    if n is None:
        deque(iterator, maxlen=0)
    else:
        next(islice(iterator, n, n), None)

def nth(iterable, n, default=None):
    "Returns the nth item or a default value."
    return next(islice(iterable, n, None), default)

def quantify(iterable, predicate=bool):
    "Given a predicate that returns True or False, count the True results."
    return sum(map(predicate, iterable))

def first_true(iterable, default=False, predicate=None):
    "Returns the first true value or the *default* if there is no true value."
    # first_true([a,b,c], x) → a or b or c or x
    # first_true([a,b], x, f) → a if f(a) else b if f(b) else x
    return next(filter(predicate, iterable), default)

def all_equal(iterable, key=None):
    "Returns True if all the elements are equal to each other."
    # all_equal('4٤௪౪໔', key=int) → True
    return len(take(2, groupby(iterable, key))) <= 1

def unique_justseen(iterable, key=None):
    "Yield unique elements, preserving order. Remember only the element just seen."
    # unique_justseen('AAAABBBCCDAABBB') → A B C D A B
    # unique_justseen('ABBcCAD', str.casefold) → A B c A D
    if key is None:
        return map(itemgetter(0), groupby(iterable))
    return map(next, map(itemgetter(1), groupby(iterable, key)))

def unique_everseen(iterable, key=None):
    "Yield unique elements, preserving order. Remember all elements ever seen."
    # unique_everseen('AAAABBBCCDAABBB') → A B C D
    # unique_everseen('ABBcCAD', str.casefold) → A B c D
    seen = set()
    if key is None:
        for element in filterfalse(seen.__contains__, iterable):
            seen.add(element)
            yield element
    else:
        for element in iterable:
            k = key(element)
            if k not in seen:
                seen.add(k)
                yield element

def unique(iterable, key=None, reverse=False):
   "Yield unique elements in sorted order. Supports unhashable inputs."
   # unique([[1, 2], [3, 4], [1, 2]]) → [1, 2] [3, 4]
   sequenced = sorted(iterable, key=key, reverse=reverse)
   return unique_justseen(sequenced, key=key)

def sliding_window(iterable, n):
    "Collect data into overlapping fixed-length chunks or blocks."
    # sliding_window('ABCDEFG', 4) → ABCD BCDE CDEF DEFG
    iterator = iter(iterable)
    window = deque(islice(iterator, n - 1), maxlen=n)
    for x in iterator:
        window.append(x)
        yield tuple(window)

def grouper(iterable, n, *, incomplete='fill', fillvalue=None):
    "Collect data into non-overlapping fixed-length chunks or blocks."
    # grouper('ABCDEFG', 3, fillvalue='x') → ABC DEF Gxx
    # grouper('ABCDEFG', 3, incomplete='strict') → ABC DEF ValueError
    # grouper('ABCDEFG', 3, incomplete='ignore') → ABC DEF
    iterators = [iter(iterable)] * n
    match incomplete:
        case 'fill':
            return zip_longest(*iterators, fillvalue=fillvalue)
        case 'strict':
            return zip(*iterators, strict=True)
        case 'ignore':
            return zip(*iterators)
        case _:
            raise ValueError('Expected fill, strict, or ignore')

def roundrobin(*iterables):
    "Visit input iterables in a cycle until each is exhausted."
    # roundrobin('ABC', 'D', 'EF') → A D E B F C
    # Algorithm credited to George Sakkis
    iterators = map(iter, iterables)
    for num_active in range(len(iterables), 0, -1):
        iterators = cycle(islice(iterators, num_active))
        yield from map(next, iterators)

def subslices(seq):
    "Return all contiguous non-empty subslices of a sequence."
    # subslices('ABCD') → A AB ABC ABCD B BC BCD C CD D
    slices = starmap(slice, combinations(range(len(seq) + 1), 2))
    return map(getitem, repeat(seq), slices)

def iter_index(iterable, value, start=0, stop=None):
    "Return indices where a value occurs in a sequence or iterable."
    # iter_index('AABCADEAF', 'A') → 0 1 4 7
    seq_index = getattr(iterable, 'index', None)
    if seq_index is None:
        iterator = islice(iterable, start, stop)
        for i, element in enumerate(iterator, start):
            if element is value or element == value:
                yield i
    else:
        stop = len(iterable) if stop is None else stop
        i = start
        with suppress(ValueError):
            while True:
                yield (i := seq_index(value, i, stop))
                i += 1

def iter_except(function, exception, first=None):
    "Convert a call-until-exception interface to an iterator interface."
    # iter_except(d.popitem, KeyError) → non-blocking dictionary iterator
    with suppress(exception):
        if first is not None:
            yield first()
        while True:
            yield function()
@end example

The following recipes have a more mathematical flavor:

@example
def powerset(iterable):
    "Subsequences of the iterable from shortest to longest."
    # powerset([1,2,3]) → () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)
    s = list(iterable)
    return chain.from_iterable(combinations(s, r) for r in range(len(s)+1))

def sum_of_squares(iterable):
    "Add up the squares of the input values."
    # sum_of_squares([10, 20, 30]) → 1400
    return sumprod(*tee(iterable))

def reshape(matrix, columns):
    "Reshape a 2-D matrix to have a given number of columns."
    # reshape([(0, 1), (2, 3), (4, 5)], 3) →  (0, 1, 2), (3, 4, 5)
    return batched(chain.from_iterable(matrix), columns, strict=True)

def transpose(matrix):
    "Swap the rows and columns of a 2-D matrix."
    # transpose([(1, 2, 3), (11, 22, 33)]) → (1, 11) (2, 22) (3, 33)
    return zip(*matrix, strict=True)

def matmul(m1, m2):
    "Multiply two matrices."
    # matmul([(7, 5), (3, 5)], [(2, 5), (7, 9)]) → (49, 80), (41, 60)
    n = len(m2[0])
    return batched(starmap(sumprod, product(m1, transpose(m2))), n)

def convolve(signal, kernel):
    """Discrete linear convolution of two iterables.
    Equivalent to polynomial multiplication.

    Convolutions are mathematically commutative; however, the inputs are
    evaluated differently.  The signal is consumed lazily and can be
    infinite. The kernel is fully consumed before the calculations begin.

    Article:  https://betterexplained.com/articles/intuitive-convolution/
    Video:    https://www.youtube.com/watch?v=KuXjwB4LzSA
    """
    # convolve([1, -1, -20], [1, -3]) → 1 -4 -17 60
    # convolve(data, [0.25, 0.25, 0.25, 0.25]) → Moving average (blur)
    # convolve(data, [1/2, 0, -1/2]) → 1st derivative estimate
    # convolve(data, [1, -2, 1]) → 2nd derivative estimate
    kernel = tuple(kernel)[::-1]
    n = len(kernel)
    padded_signal = chain(repeat(0, n-1), signal, repeat(0, n-1))
    windowed_signal = sliding_window(padded_signal, n)
    return map(sumprod, repeat(kernel), windowed_signal)

def polynomial_from_roots(roots):
    """Compute a polynomial's coefficients from its roots.

       (x - 5) (x + 4) (x - 3)  expands to:   x³ -4x² -17x + 60
    """
    # polynomial_from_roots([5, -4, 3]) → [1, -4, -17, 60]
    factors = zip(repeat(1), map(neg, roots))
    return list(reduce(convolve, factors, [1]))

def polynomial_eval(coefficients, x):
    """Evaluate a polynomial at a specific value.

    Computes with better numeric stability than Horner's method.
    """
    # Evaluate x³ -4x² -17x + 60 at x = 5
    # polynomial_eval([1, -4, -17, 60], x=5) → 0
    n = len(coefficients)
    if not n:
        return type(x)(0)
    powers = map(pow, repeat(x), reversed(range(n)))
    return sumprod(coefficients, powers)

def polynomial_derivative(coefficients):
    """Compute the first derivative of a polynomial.

       f(x)  =  x³ -4x² -17x + 60
       f'(x) = 3x² -8x  -17
    """
    # polynomial_derivative([1, -4, -17, 60]) → [3, -8, -17]
    n = len(coefficients)
    powers = reversed(range(1, n))
    return list(map(mul, coefficients, powers))

def sieve(n):
    "Primes less than n."
    # sieve(30) → 2 3 5 7 11 13 17 19 23 29
    if n > 2:
        yield 2
    data = bytearray((0, 1)) * (n // 2)
    for p in iter_index(data, 1, start=3, stop=isqrt(n) + 1):
        data[p*p : n : p+p] = bytes(len(range(p*p, n, p+p)))
    yield from iter_index(data, 1, start=3)

def factor(n):
    "Prime factors of n."
    # factor(99) → 3 3 11
    # factor(1_000_000_000_000_007) → 47 59 360620266859
    # factor(1_000_000_000_000_403) → 1000000000000403
    for prime in sieve(isqrt(n) + 1):
        while not n % prime:
            yield prime
            n //= prime
            if n == 1:
                return
    if n > 1:
        yield n

def is_prime(n):
    "Return True if n is prime."
    # is_prime(1_000_000_000_000_403) → True
    return n > 1 and next(factor(n)) == n

def totient(n):
    "Count of natural numbers up to n that are coprime to n."
    # https://mathworld.wolfram.com/TotientFunction.html
    # totient(12) → 4 because len([1, 5, 7, 11]) == 4
    for prime in set(factor(n)):
        n -= n // prime
    return n
@end example

@c These examples no longer appear in the docs but are guaranteed
@c to keep working.
@c 
@c >>> amounts = [120.15, 764.05, 823.14]
@c >>> for checknum, amount in zip(count(1200), amounts):
@c ...     print('Check %d is for $%.2f' % (checknum, amount))
@c ...
@c Check 1200 is for $120.15
@c Check 1201 is for $764.05
@c Check 1202 is for $823.14
@c 
@c >>> import operator
@c >>> for cube in map(operator.pow, range(1,4), repeat(3)):
@c ...    print(cube)
@c ...
@c 1
@c 8
@c 27
@c 
@c >>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura', '', 'martin', '', 'walter', '', 'samuele']
@c >>> for name in islice(reportlines, 3, None, 2):
@c ...    print(name.title())
@c ...
@c Alex
@c Laura
@c Martin
@c Walter
@c Samuele
@c 
@c >>> from operator import itemgetter
@c >>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3)
@c >>> di = sorted(sorted(d.items()), key=itemgetter(1))
@c >>> for k, g in groupby(di, itemgetter(1)):
@c ...     print(k, list(map(itemgetter(0), g)))
@c ...
@c 1 ['a', 'c', 'e']
@c 2 ['b', 'd', 'f']
@c 3 ['g']
@c 
@c # Find runs of consecutive numbers using groupby.  The key to the solution
@c # is differencing with a range so that consecutive numbers all appear in
@c # same group.
@c >>> data = [ 1,  4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
@c >>> for k, g in groupby(enumerate(data), lambda t:t[0]-t[1]):
@c ...     print(list(map(operator.itemgetter(1), g)))
@c ...
@c [1]
@c [4, 5, 6]
@c [10]
@c [15, 16, 17, 18]
@c [22]
@c [25, 26, 27, 28]
@c 
@c Now, we test all of the itertool recipes
@c 
@c >>> take(10, count())
@c [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@c >>> # Verify that the input is consumed lazily
@c >>> it = iter('abcdef')
@c >>> take(3, it)
@c ['a', 'b', 'c']
@c >>> list(it)
@c ['d', 'e', 'f']
@c 
@c 
@c >>> list(prepend(1, [2, 3, 4]))
@c [1, 2, 3, 4]
@c 
@c 
@c >>> list(enumerate('abc'))
@c [(0, 'a'), (1, 'b'), (2, 'c')]
@c 
@c 
@c >>> list(islice(tabulate(lambda x: 2*x), 4))
@c [0, 2, 4, 6]
@c 
@c 
@c >>> for _ in loops(5):
@c ...     print('hi')
@c ...
@c hi
@c hi
@c hi
@c hi
@c hi
@c 
@c 
@c >>> list(tail(3, 'ABCDEFG'))
@c ['E', 'F', 'G']
@c >>> # Verify the input is consumed greedily
@c >>> input_iterator = iter('ABCDEFG')
@c >>> output_iterator = tail(3, input_iterator)
@c >>> list(input_iterator)
@c []
@c 
@c 
@c >>> it = iter(range(10))
@c >>> consume(it, 3)
@c >>> # Verify the input is consumed lazily
@c >>> next(it)
@c 3
@c >>> # Verify the input is consumed completely
@c >>> consume(it)
@c >>> next(it, 'Done')
@c 'Done'
@c 
@c 
@c >>> nth('abcde', 3)
@c 'd'
@c >>> nth('abcde', 9) is None
@c True
@c >>> # Verify that the input is consumed lazily
@c >>> it = iter('abcde')
@c >>> nth(it, 2)
@c 'c'
@c >>> list(it)
@c ['d', 'e']
@c 
@c 
@c >>> [all_equal(s) for s in ('', 'A', 'AAAA', 'AAAB', 'AAABA')]
@c [True, True, True, False, False]
@c >>> [all_equal(s, key=str.casefold) for s in ('', 'A', 'AaAa', 'AAAB', 'AAABA')]
@c [True, True, True, False, False]
@c >>> # Verify that the input is consumed lazily and that only
@c >>> # one element of a second equivalence class is used to disprove
@c >>> # the assertion that all elements are equal.
@c >>> it = iter('aaabbbccc')
@c >>> all_equal(it)
@c False
@c >>> ''.join(it)
@c 'bbccc'
@c 
@c 
@c >>> quantify(range(99), lambda x: x%2==0)
@c 50
@c >>> quantify([True, False, False, True, True])
@c 3
@c >>> quantify(range(12), predicate=lambda x: x%2==1)
@c 6
@c 
@c 
@c >>> a = [[1, 2, 3], [4, 5, 6]]
@c >>> list(flatten(a))
@c [1, 2, 3, 4, 5, 6]
@c 
@c 
@c >>> list(ncycles('abc', 3))
@c ['a', 'b', 'c', 'a', 'b', 'c', 'a', 'b', 'c']
@c >>> # Verify greedy consumption of input iterator
@c >>> input_iterator = iter('abc')
@c >>> output_iterator = ncycles(input_iterator, 3)
@c >>> list(input_iterator)
@c []
@c 
@c 
@c >>> sum_of_squares([10, 20, 30])
@c 1400
@c 
@c 
@c >>> list(reshape([(0, 1), (2, 3), (4, 5)], 3))
@c [(0, 1, 2), (3, 4, 5)]
@c >>> M = [(0, 1, 2, 3), (4, 5, 6, 7), (8, 9, 10, 11)]
@c >>> list(reshape(M, 1))
@c [(0,), (1,), (2,), (3,), (4,), (5,), (6,), (7,), (8,), (9,), (10,), (11,)]
@c >>> list(reshape(M, 2))
@c [(0, 1), (2, 3), (4, 5), (6, 7), (8, 9), (10, 11)]
@c >>> list(reshape(M, 3))
@c [(0, 1, 2), (3, 4, 5), (6, 7, 8), (9, 10, 11)]
@c >>> list(reshape(M, 4))
@c [(0, 1, 2, 3), (4, 5, 6, 7), (8, 9, 10, 11)]
@c >>> list(reshape(M, 5))
@c Traceback (most recent call last):
@c ...
@c ValueError: batched(): incomplete batch
@c >>> list(reshape(M, 6))
@c [(0, 1, 2, 3, 4, 5), (6, 7, 8, 9, 10, 11)]
@c >>> list(reshape(M, 12))
@c [(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11)]
@c 
@c 
@c >>> list(transpose([(1, 2, 3), (11, 22, 33)]))
@c [(1, 11), (2, 22), (3, 33)]
@c >>> # Verify that the inputs are consumed lazily
@c >>> input1 = iter([1, 2, 3])
@c >>> input2 = iter([11, 22, 33])
@c >>> output_iterator = transpose([input1, input2])
@c >>> next(output_iterator)
@c (1, 11)
@c >>> list(zip(input1, input2))
@c [(2, 22), (3, 33)]
@c 
@c 
@c >>> list(matmul([(7, 5), (3, 5)], [[2, 5], [7, 9]]))
@c [(49, 80), (41, 60)]
@c >>> list(matmul([[2, 5], [7, 9], [3, 4]], [[7, 11, 5, 4, 9], [3, 5, 2, 6, 3]]))
@c [(29, 47, 20, 38, 33), (76, 122, 53, 82, 90), (33, 53, 23, 36, 39)]
@c 
@c 
@c >>> list(convolve([1, -1, -20], [1, -3])) == [1, -4, -17, 60]
@c True
@c >>> data = [20, 40, 24, 32, 20, 28, 16]
@c >>> list(convolve(data, [0.25, 0.25, 0.25, 0.25]))
@c [5.0, 15.0, 21.0, 29.0, 29.0, 26.0, 24.0, 16.0, 11.0, 4.0]
@c >>> list(convolve(data, [1, -1]))
@c [20, 20, -16, 8, -12, 8, -12, -16]
@c >>> list(convolve(data, [1, -2, 1]))
@c [20, 0, -36, 24, -20, 20, -20, -4, 16]
@c >>> # Verify signal is consumed lazily and the kernel greedily
@c >>> signal_iterator = iter([10, 20, 30, 40, 50])
@c >>> kernel_iterator = iter([1, 2, 3])
@c >>> output_iterator = convolve(signal_iterator, kernel_iterator)
@c >>> list(kernel_iterator)
@c []
@c >>> next(output_iterator)
@c 10
@c >>> next(output_iterator)
@c 40
@c >>> list(signal_iterator)
@c [30, 40, 50]
@c 
@c 
@c >>> from fractions import Fraction
@c >>> from decimal import Decimal
@c >>> polynomial_eval([1, -4, -17, 60], x=5)
@c 0
@c >>> x = 5; x**3 - 4*x**2 -17*x + 60
@c 0
@c >>> polynomial_eval([1, -4, -17, 60], x=2.5)
@c 8.125
@c >>> x = 2.5; x**3 - 4*x**2 -17*x + 60
@c 8.125
@c >>> polynomial_eval([1, -4, -17, 60], x=Fraction(2, 3))
@c Fraction(1274, 27)
@c >>> x = Fraction(2, 3); x**3 - 4*x**2 -17*x + 60
@c Fraction(1274, 27)
@c >>> polynomial_eval([1, -4, -17, 60], x=Decimal('1.75'))
@c Decimal('23.359375')
@c >>> x = Decimal('1.75'); x**3 - 4*x**2 -17*x + 60
@c Decimal('23.359375')
@c >>> polynomial_eval([], 2)
@c 0
@c >>> polynomial_eval([], 2.5)
@c 0.0
@c >>> polynomial_eval([], Fraction(2, 3))
@c Fraction(0, 1)
@c >>> polynomial_eval([], Decimal('1.75'))
@c Decimal('0')
@c >>> polynomial_eval([11], 7) == 11
@c True
@c >>> polynomial_eval([11, 2], 7) == 11 * 7 + 2
@c True
@c 
@c 
@c >>> polynomial_from_roots([5, -4, 3])
@c [1, -4, -17, 60]
@c >>> factored = lambda x: (x - 5) * (x + 4) * (x - 3)
@c >>> expanded = lambda x: x**3 -4*x**2 -17*x + 60
@c >>> all(factored(x) == expanded(x) for x in range(-10, 11))
@c True
@c 
@c 
@c >>> polynomial_derivative([1, -4, -17, 60])
@c [3, -8, -17]
@c 
@c 
@c >>> list(iter_index('AABCADEAF', 'A'))
@c [0, 1, 4, 7]
@c >>> list(iter_index('AABCADEAF', 'B'))
@c [2]
@c >>> list(iter_index('AABCADEAF', 'X'))
@c []
@c >>> list(iter_index('', 'X'))
@c []
@c >>> list(iter_index('AABCADEAF', 'A', 1))
@c [1, 4, 7]
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 1))
@c [1, 4, 7]
@c >>> list(iter_index('AABCADEAF', 'A', 2))
@c [4, 7]
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 2))
@c [4, 7]
@c >>> list(iter_index('AABCADEAF', 'A', 10))
@c []
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 10))
@c []
@c >>> list(iter_index('AABCADEAF', 'A', 1, 7))
@c [1, 4]
@c >>> list(iter_index(iter('AABCADEAF'), 'A', 1, 7))
@c [1, 4]
@c >>> # Verify that ValueErrors not swallowed (gh-107208)
@c >>> def assert_no_value(iterable, forbidden_value):
@c ...     for item in iterable:
@c ...         if item == forbidden_value:
@c ...             raise ValueError
@c ...         yield item
@c ...
@c >>> list(iter_index(assert_no_value('AABCADEAF', 'B'), 'A'))
@c Traceback (most recent call last):
@c ...
@c ValueError
@c >>> # Verify that both paths can find identical NaN values
@c >>> x = float('NaN')
@c >>> y = float('NaN')
@c >>> list(iter_index([0, x, x, y, 0], x))
@c [1, 2]
@c >>> list(iter_index(iter([0, x, x, y, 0]), x))
@c [1, 2]
@c >>> # Test list input. Lists do not support None for the stop argument
@c >>> list(iter_index(list('AABCADEAF'), 'A'))
@c [0, 1, 4, 7]
@c >>> # Verify that input is consumed lazily
@c >>> input_iterator = iter('AABCADEAF')
@c >>> output_iterator = iter_index(input_iterator, 'A')
@c >>> next(output_iterator)
@c 0
@c >>> next(output_iterator)
@c 1
@c >>> next(output_iterator)
@c 4
@c >>> ''.join(input_iterator)
@c 'DEAF'
@c 
@c 
@c >>> # Verify that the target value can be a sequence.
@c >>> seq = [[10, 20], [30, 40], 30, 40, [30, 40], 50]
@c >>> target = [30, 40]
@c >>> list(iter_index(seq, target))
@c [1, 4]
@c 
@c 
@c >>> # Verify faithfulness to type specific index() method behaviors.
@c >>> # For example, bytes and str perform continuous-subsequence searches
@c >>> # that do not match the general behavior specified
@c >>> # in collections.abc.Sequence.index().
@c >>> seq = 'abracadabra'
@c >>> target = 'ab'
@c >>> list(iter_index(seq, target))
@c [0, 7]
@c 
@c 
@c >>> list(sieve(30))
@c [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
@c >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
@c >>> all(list(sieve(n)) == [p for p in small_primes if p < n] for n in range(101))
@c True
@c >>> len(list(sieve(100)))
@c 25
@c >>> len(list(sieve(1_000)))
@c 168
@c >>> len(list(sieve(10_000)))
@c 1229
@c >>> len(list(sieve(100_000)))
@c 9592
@c >>> len(list(sieve(1_000_000)))
@c 78498
@c >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911}  # https://oeis.org/A002997
@c >>> set(sieve(10_000)).isdisjoint(carmichael)
@c True
@c 
@c 
@c >>> small_primes = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97]
@c >>> list(filter(is_prime, range(-100, 100))) == small_primes
@c True
@c >>> carmichael = {561, 1105, 1729, 2465, 2821, 6601, 8911}  # https://oeis.org/A002997
@c >>> any(map(is_prime, carmichael))
@c False
@c >>> # https://www.wolframalpha.com/input?i=is+128884753939+prime
@c >>> is_prime(128_884_753_939)           # large prime
@c True
@c >>> is_prime(999953 * 999983)           # large semiprime
@c False
@c >>> is_prime(1_000_000_000_000_007)     # factor() example
@c False
@c >>> is_prime(1_000_000_000_000_403)     # factor() example
@c True
@c 
@c 
@c >>> list(factor(99))                    # Code example 1
@c [3, 3, 11]
@c >>> list(factor(1_000_000_000_000_007)) # Code example 2
@c [47, 59, 360620266859]
@c >>> list(factor(1_000_000_000_000_403)) # Code example 3
@c [1000000000000403]
@c >>> list(factor(0))
@c []
@c >>> list(factor(1))
@c []
@c >>> list(factor(2))
@c [2]
@c >>> list(factor(3))
@c [3]
@c >>> list(factor(4))
@c [2, 2]
@c >>> list(factor(5))
@c [5]
@c >>> list(factor(6))
@c [2, 3]
@c >>> list(factor(7))
@c [7]
@c >>> list(factor(8))
@c [2, 2, 2]
@c >>> list(factor(9))
@c [3, 3]
@c >>> list(factor(10))
@c [2, 5]
@c >>> list(factor(128_884_753_939))       # large prime
@c [128884753939]
@c >>> list(factor(999953 * 999983))       # large semiprime
@c [999953, 999983]
@c >>> list(factor(6 ** 20)) == [2] * 20 + [3] * 20   # large power
@c True
@c >>> list(factor(909_909_090_909))       # large multiterm composite
@c [3, 3, 7, 13, 13, 751, 113797]
@c >>> math.prod([3, 3, 7, 13, 13, 751, 113797])
@c 909909090909
@c >>> all(math.prod(factor(n)) == n for n in range(1, 2_000))
@c True
@c >>> all(set(factor(n)) <= set(sieve(n+1)) for n in range(2_000))
@c True
@c >>> all(list(factor(n)) == sorted(factor(n)) for n in range(2_000))
@c True
@c 
@c 
@c >>> totient(0)  # https://www.wolframalpha.com/input?i=totient+0
@c 0
@c >>> first_totients = [1, 1, 2, 2, 4, 2, 6, 4, 6, 4, 10, 4, 12, 6, 8, 8, 16, 6,
@c ... 18, 8, 12, 10, 22, 8, 20, 12, 18, 12, 28, 8, 30, 16, 20, 16, 24, 12, 36, 18,
@c ... 24, 16, 40, 12, 42, 20, 24, 22, 46, 16, 42, 20, 32, 24, 52, 18, 40, 24, 36,
@c ... 28, 58, 16, 60, 30, 36, 32, 48, 20, 66, 32, 44]  # https://oeis.org/A000010
@c ...
@c >>> list(map(totient, range(1, 70))) == first_totients
@c True
@c >>> reference_totient = lambda n: sum(math.gcd(t, n) == 1 for t in range(1, n+1))
@c >>> all(totient(n) == reference_totient(n) for n in range(1000))
@c True
@c >>> totient(128_884_753_939) == 128_884_753_938  # large prime
@c True
@c >>> totient(999953 * 999983) == 999952 * 999982  # large semiprime
@c True
@c >>> totient(6 ** 20) == 1 * 2**19 * 2 * 3**19    # repeated primes
@c True
@c 
@c 
@c >>> list(flatten([('a', 'b'), (), ('c', 'd', 'e'), ('f',), ('g', 'h', 'i')]))
@c ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']
@c 
@c 
@c >>> list(repeatfunc(pow, 5, 2, 3))
@c [8, 8, 8, 8, 8]
@c >>> take(5, map(int, repeatfunc(random.random)))
@c [0, 0, 0, 0, 0]
@c >>> random.seed(85753098575309)
@c >>> list(repeatfunc(random.random, 3))
@c [0.16370491282496968, 0.45889608687313455, 0.3747076837820118]
@c >>> list(repeatfunc(chr, 3, 65))
@c ['A', 'A', 'A']
@c >>> list(repeatfunc(pow, 3, 2, 5))
@c [32, 32, 32]
@c 
@c 
@c >>> list(grouper('abcdefg', 3, fillvalue='x'))
@c [('a', 'b', 'c'), ('d', 'e', 'f'), ('g', 'x', 'x')]
@c 
@c 
@c >>> it = grouper('abcdefg', 3, incomplete='strict')
@c >>> next(it)
@c ('a', 'b', 'c')
@c >>> next(it)
@c ('d', 'e', 'f')
@c >>> next(it)
@c Traceback (most recent call last):
@c   ...
@c ValueError: zip() argument 2 is shorter than argument 1
@c 
@c >>> list(grouper('abcdefg', n=3, incomplete='ignore'))
@c [('a', 'b', 'c'), ('d', 'e', 'f')]
@c 
@c 
@c >>> list(sliding_window('ABCDEFG', 1))
@c [('A',), ('B',), ('C',), ('D',), ('E',), ('F',), ('G',)]
@c >>> list(sliding_window('ABCDEFG', 2))
@c [('A', 'B'), ('B', 'C'), ('C', 'D'), ('D', 'E'), ('E', 'F'), ('F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 3))
@c [('A', 'B', 'C'), ('B', 'C', 'D'), ('C', 'D', 'E'), ('D', 'E', 'F'), ('E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 4))
@c [('A', 'B', 'C', 'D'), ('B', 'C', 'D', 'E'), ('C', 'D', 'E', 'F'), ('D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 5))
@c [('A', 'B', 'C', 'D', 'E'), ('B', 'C', 'D', 'E', 'F'), ('C', 'D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 6))
@c [('A', 'B', 'C', 'D', 'E', 'F'), ('B', 'C', 'D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 7))
@c [('A', 'B', 'C', 'D', 'E', 'F', 'G')]
@c >>> list(sliding_window('ABCDEFG', 8))
@c []
@c >>> try:
@c ...     list(sliding_window('ABCDEFG', -1))
@c ... except ValueError:
@c ...     'zero or negative n not supported'
@c ...
@c 'zero or negative n not supported'
@c >>> try:
@c ...     list(sliding_window('ABCDEFG', 0))
@c ... except ValueError:
@c ...     'zero or negative n not supported'
@c ...
@c 'zero or negative n not supported'
@c 
@c 
@c >>> list(roundrobin('abc', 'd', 'ef'))
@c ['a', 'd', 'e', 'b', 'f', 'c']
@c >>> ranges = [range(5, 1000), range(4, 3000), range(0), range(3, 2000), range(2, 5000), range(1, 3500)]
@c >>> collections.Counter(roundrobin(*ranges)) == collections.Counter(chain(*ranges))
@c True
@c >>> # Verify that the inputs are consumed lazily
@c >>> input_iterators = list(map(iter, ['abcd', 'ef', '', 'ghijk', 'l', 'mnopqr']))
@c >>> output_iterator = roundrobin(*input_iterators)
@c >>> ''.join(islice(output_iterator, 10))
@c 'aeglmbfhnc'
@c >>> ''.join(chain(*input_iterators))
@c 'dijkopqr'
@c 
@c 
@c >>> list(subslices('ABCD'))
@c ['A', 'AB', 'ABC', 'ABCD', 'B', 'BC', 'BCD', 'C', 'CD', 'D']
@c 
@c 
@c >>> list(powerset([1,2,3]))
@c [(), (1,), (2,), (3,), (1, 2), (1, 3), (2, 3), (1, 2, 3)]
@c >>> all(len(list(powerset(range(n)))) == 2**n for n in range(18))
@c True
@c >>> list(powerset('abcde')) == sorted(sorted(set(powerset('abcde'))), key=len)
@c True
@c 
@c 
@c >>> list(unique_everseen('AAAABBBCCDAABBB'))
@c ['A', 'B', 'C', 'D']
@c >>> list(unique_everseen('ABBCcAD', str.casefold))
@c ['A', 'B', 'C', 'D']
@c >>> list(unique_everseen('ABBcCAD', str.casefold))
@c ['A', 'B', 'c', 'D']
@c >>> # Verify that the input is consumed lazily
@c >>> input_iterator = iter('AAAABBBCCDAABBB')
@c >>> output_iterator = unique_everseen(input_iterator)
@c >>> next(output_iterator)
@c 'A'
@c >>> ''.join(input_iterator)
@c 'AAABBBCCDAABBB'
@c 
@c 
@c >>> list(unique_justseen('AAAABBBCCDAABBB'))
@c ['A', 'B', 'C', 'D', 'A', 'B']
@c >>> list(unique_justseen('ABBCcAD', str.casefold))
@c ['A', 'B', 'C', 'A', 'D']
@c >>> list(unique_justseen('ABBcCAD', str.casefold))
@c ['A', 'B', 'c', 'A', 'D']
@c >>> # Verify that the input is consumed lazily
@c >>> input_iterator = iter('AAAABBBCCDAABBB')
@c >>> output_iterator = unique_justseen(input_iterator)
@c >>> next(output_iterator)
@c 'A'
@c >>> ''.join(input_iterator)
@c 'AAABBBCCDAABBB'
@c 
@c 
@c >>> list(unique([[1, 2], [3, 4], [1, 2]]))
@c [[1, 2], [3, 4]]
@c >>> list(unique('ABBcCAD', str.casefold))
@c ['A', 'B', 'c', 'D']
@c >>> list(unique('ABBcCAD', str.casefold, reverse=True))
@c ['D', 'c', 'B', 'A']
@c 
@c 
@c >>> d = dict(a=1, b=2, c=3)
@c >>> it = iter_except(d.popitem, KeyError)
@c >>> d['d'] = 4
@c >>> next(it)
@c ('d', 4)
@c >>> next(it)
@c ('c', 3)
@c >>> next(it)
@c ('b', 2)
@c >>> d['e'] = 5
@c >>> next(it)
@c ('e', 5)
@c >>> next(it)
@c ('a', 1)
@c >>> next(it, 'empty')
@c 'empty'
@c 
@c 
@c >>> first_true('ABC0DEF1', '9', str.isdigit)
@c '0'
@c >>> # Verify that inputs are consumed lazily
@c >>> it = iter('ABC0DEF1')
@c >>> first_true(it, predicate=str.isdigit)
@c '0'
@c >>> ''.join(it)
@c 'DEF1'

@c # Old recipes and their tests which are guaranteed to continue to work.
@c 
@c def old_sumprod_recipe(vec1, vec2):
@c     "Compute a sum of products."
@c     return sum(starmap(operator.mul, zip(vec1, vec2, strict=True)))
@c 
@c def dotproduct(vec1, vec2):
@c     return sum(map(operator.mul, vec1, vec2))
@c 
@c def pad_none(iterable):
@c     """Returns the sequence elements and then returns None indefinitely.
@c 
@c     Useful for emulating the behavior of the built-in map() function.
@c     """
@c     return chain(iterable, repeat(None))
@c 
@c def triplewise(iterable):
@c     "Return overlapping triplets from an iterable"
@c     # triplewise('ABCDEFG') → ABC BCD CDE DEF EFG
@c     for (a, _), (b, c) in pairwise(pairwise(iterable)):
@c         yield a, b, c
@c 
@c def nth_combination(iterable, r, index):
@c     "Equivalent to list(combinations(iterable, r))[index]"
@c     pool = tuple(iterable)
@c     n = len(pool)
@c     c = math.comb(n, r)
@c     if index < 0:
@c         index += c
@c     if index < 0 or index >= c:
@c         raise IndexError
@c     result = []
@c     while r:
@c         c, n, r = c*r//n, n-1, r-1
@c         while index >= c:
@c             index -= c
@c             c, n = c*(n-r)//n, n-1
@c         result.append(pool[-1-n])
@c     return tuple(result)
@c 
@c def before_and_after(predicate, it):
@c    """ Variant of takewhile() that allows complete
@c        access to the remainder of the iterator.
@c 
@c        >>> it = iter('ABCdEfGhI')
@c        >>> all_upper, remainder = before_and_after(str.isupper, it)
@c        >>> ''.join(all_upper)
@c        'ABC'
@c        >>> ''.join(remainder)     # takewhile() would lose the 'd'
@c        'dEfGhI'
@c 
@c        Note that the true iterator must be fully consumed
@c        before the remainder iterator can generate valid results.
@c    """
@c    it = iter(it)
@c    transition = []
@c 
@c    def true_iterator():
@c        for elem in it:
@c            if predicate(elem):
@c                yield elem
@c            else:
@c                transition.append(elem)
@c                return
@c 
@c    return true_iterator(), chain(transition, it)
@c 
@c def partition(predicate, iterable):
@c     """Partition entries into false entries and true entries.
@c 
@c     If *predicate* is slow, consider wrapping it with functools.lru_cache().
@c     """
@c     # partition(is_odd, range(10)) → 0 2 4 6 8   and  1 3 5 7 9
@c     t1, t2 = tee(iterable)
@c     return filterfalse(predicate, t1), filter(predicate, t2)

@c >>> dotproduct([1,2,3], [4,5,6])
@c 32
@c 
@c 
@c >>> old_sumprod_recipe([1,2,3], [4,5,6])
@c 32
@c 
@c 
@c >>> list(islice(pad_none('abc'), 0, 6))
@c ['a', 'b', 'c', None, None, None]
@c 
@c 
@c >>> list(triplewise('ABCDEFG'))
@c [('A', 'B', 'C'), ('B', 'C', 'D'), ('C', 'D', 'E'), ('D', 'E', 'F'), ('E', 'F', 'G')]
@c 
@c 
@c >>> population = 'ABCDEFGH'
@c >>> for r in range(len(population) + 1):
@c ...     seq = list(combinations(population, r))
@c ...     for i in range(len(seq)):
@c ...         assert nth_combination(population, r, i) == seq[i]
@c ...     for i in range(-len(seq), 0):
@c ...         assert nth_combination(population, r, i) == seq[i]
@c ...
@c >>> iterable = 'abcde'
@c >>> r = 3
@c >>> combos = list(combinations(iterable, r))
@c >>> all(nth_combination(iterable, r, i) == comb for i, comb in enumerate(combos))
@c True
@c 
@c 
@c >>> it = iter('ABCdEfGhI')
@c >>> all_upper, remainder = before_and_after(str.isupper, it)
@c >>> ''.join(all_upper)
@c 'ABC'
@c >>> ''.join(remainder)
@c 'dEfGhI'
@c 
@c 
@c >>> def is_odd(x):
@c ...     return x % 2 == 1
@c ...
@c >>> evens, odds = partition(is_odd, range(10))
@c >>> list(evens)
@c [0, 2, 4, 6, 8]
@c >>> list(odds)
@c [1, 3, 5, 7, 9]
@c >>> # Verify that the input is consumed lazily
@c >>> input_iterator = iter(range(10))
@c >>> evens, odds = partition(is_odd, input_iterator)
@c >>> next(odds)
@c 1
@c >>> next(odds)
@c 3
@c >>> next(evens)
@c 0
@c >>> list(input_iterator)
@c [4, 5, 6, 7, 8, 9]

@node functools --- Higher-order functions and operations on callable objects,operator — Opérateurs standards en tant que fonctions,itertools --- Functions creating iterators for efficient looping,Modules de programmation fonctionnelle
@anchor{library/functools doc}@anchor{26b8}@anchor{library/functools functools-higher-order-functions-and-operations-on-callable-objects}@anchor{26b9}@anchor{library/functools module-functools}@anchor{5e}
@subsection @code{functools} --- Higher-order functions and operations on callable objects


@geindex module; functools

`Code source :' Lib/functools.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/functools.py}

@c import functools
@c from functools import *


__________________________________________________________________


Le module @ref{5e,,functools} concerne les fonctions d'ordre supérieur : des fonctions qui agissent sur, ou renvoient, d'autres fonctions. En général, tout objet appelable peut être considéré comme une fonction dans la description de ce module.

Le module @ref{5e,,functools} définit les fonctions suivantes :

@geindex cache() (dans le module functools)
@anchor{library/functools functools cache}@anchor{24c6}
@deffn {Fonction} @@functools.cache (user_function)

Fonction de cache très simple et sans limite de taille. Cette technique est parfois appelée « mémoïsation »@footnote{https://fr.wikipedia.org/wiki/M%C3%A9mo%C3%AFsation}.

Returns the same as @code{lru_cache(maxsize=None)}, creating a thin
wrapper around a dictionary lookup for the function arguments.  Because it
never needs to evict old values, this is smaller and faster than
@ref{9dd,,lru_cache()} with a size limit.

Par exemple :

@example
@@cache
def factorial(n):
    return n * factorial(n-1) if n else 1

>>> factorial(10)      # no previously cached result, makes 11 recursive calls
3628800
>>> factorial(5)       # just looks up cached value result
120
>>> factorial(12)      # makes two new recursive calls, the other 10 are cached
479001600
@end example

The cache is threadsafe so that the wrapped function can be used in
multiple threads.  This means that the underlying data structure will
remain coherent during concurrent updates.

It is possible for the wrapped function to be called more than once if
another thread makes an additional call before the initial call has been
completed and cached.


Ajouté dans la version 3.9.

@end deffn

@geindex cached_property() (dans le module functools)
@anchor{library/functools functools cached_property}@anchor{52c}
@deffn {Fonction} @@functools.cached_property (func)

Transform a method of a class into a property whose value is computed once
and then cached as a normal attribute for the life of the instance. Similar
to @ref{192,,property()}, with the addition of caching. Useful for expensive
computed properties of instances that are otherwise effectively immutable.

Exemple :

@example
class DataSet:

    def __init__(self, sequence_of_numbers):
        self._data = tuple(sequence_of_numbers)

    @@cached_property
    def stdev(self):
        return statistics.stdev(self._data)
@end example

The mechanics of @ref{52c,,cached_property()} are somewhat different from
@ref{192,,property()}.  A regular property blocks attribute writes unless a
setter is defined. In contrast, a `cached_property' allows writes.

The `cached_property' decorator only runs on lookups and only when an
attribute of the same name doesn't exist.  When it does run, the
`cached_property' writes to the attribute with the same name. Subsequent
attribute reads and writes take precedence over the `cached_property'
method and it works like a normal attribute.

The cached value can be cleared by deleting the attribute.  This
allows the `cached_property' method to run again.

The `cached_property' does not prevent a possible race condition in
multi-threaded usage. The getter function could run more than once on the
same instance, with the latest run setting the cached value. If the cached
property is idempotent or otherwise not harmful to run more than once on an
instance, this is fine. If synchronization is needed, implement the necessary
locking inside the decorated getter function or around the cached property
access.

Note, this decorator interferes with the operation of 
@geindex Python Enhancement Proposals; PEP 412
PEP 412@footnote{https://peps.python.org/pep-0412/}
key-sharing dictionaries.  This means that instance dictionaries
can take more space than usual.

Also, this decorator requires that the @code{__dict__} attribute on each instance
be a mutable mapping. This means it will not work with some types, such as
metaclasses (since the @code{__dict__} attributes on type instances are
read-only proxies for the class namespace), and those that specify
@code{__slots__} without including @code{__dict__} as one of the defined slots
(as such classes don't provide a @code{__dict__} attribute at all).

If a mutable mapping is not available or if space-efficient key sharing is
desired, an effect similar to @ref{52c,,cached_property()} can also be achieved by
stacking @ref{192,,property()} on top of @ref{9dd,,lru_cache()}. See
@ref{26ba,,Comment mettre en cache le résultat d'une méthode ?} for more details on how this differs from @ref{52c,,cached_property()}.


Ajouté dans la version 3.8.



Modifié dans la version 3.12: Prior to Python 3.12, @code{cached_property} included an undocumented lock to
ensure that in multi-threaded usage the getter function was guaranteed to
run only once per instance. However, the lock was per-property, not
per-instance, which could result in unacceptably high lock contention. In
Python 3.12+ this locking is removed.

@end deffn

@geindex cmp_to_key() (dans le module functools)
@anchor{library/functools functools cmp_to_key}@anchor{11b7}
@deffn {Fonction} functools.cmp_to_key (func)

Transforme une fonction de comparaison à l'ancienne en une @ref{df2,,fonction clé}.  Utilisé avec des outils qui acceptent des fonctions clef (comme @ref{bbc,,sorted()}, @ref{ef3,,min()}, @ref{ef4,,max()}, @ref{24b7,,heapq.nlargest()}, @ref{24b8,,heapq.nsmallest()}, @ref{26b1,,itertools.groupby()}).  Cette fonction est destinée au portage de fonctions python 2 utilisant des fonctions de comparaison vers Python 3.

A comparison function is any callable that accepts two arguments, compares them,
and returns a negative number for less-than, zero for equality, or a positive
number for greater-than.  A key function is a callable that accepts one
argument and returns another value to be used as the sort key.

Exemple :

@example
sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order
@end example

Pour des exemples de tris et un bref tutoriel, consultez @ref{2107,,Sorting Techniques}.


Ajouté dans la version 3.2.

@end deffn

@geindex lru_cache() (dans le module functools)
@anchor{library/functools functools lru_cache}@anchor{9dd}
@deffn {Fonction} @@functools.lru_cache (user_function)

@deffnx {Fonction} @@functools.lru_cache (maxsize=128, typed=False)

Décorateur qui englobe une fonction avec un appelable mémoïsant qui enregistre jusqu'à `maxsize' appels récents. Cela peut gagner du temps quand une fonction coûteuse en ressources est souvent appelée avec les mêmes arguments.

The cache is threadsafe so that the wrapped function can be used in
multiple threads.  This means that the underlying data structure will
remain coherent during concurrent updates.

It is possible for the wrapped function to be called more than once if
another thread makes an additional call before the initial call has been
completed and cached.

Since a dictionary is used to cache results, the positional and keyword
arguments to the function must be @ref{5fb,,hashable}.

Distinct argument patterns may be considered to be distinct calls with
separate cache entries.  For example, @code{f(a=1, b=2)} and @code{f(b=2, a=1)}
differ in their keyword argument order and may have two separate cache
entries.

Si `user_function' est défini, ce doit être un appelable. Ceci permet à `lru_cache' d'être appliqué directement sur une fonction de l'utilisateur, sans préciser `maxsize' (qui est alors défini à sa valeur par défaut, 128) :

@example
@@lru_cache
def count_vowels(sentence):
    return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')
@end example

Si `maxsize' est à @code{None}, la fonctionnalité LRU est désactivée et le cache peut grossir sans limite.

If `typed' is set to true, function arguments of different types will be
cached separately.  If `typed' is false, the implementation will usually
regard them as equivalent calls and only cache a single result. (Some
types such as `str' and `int' may be cached separately even when `typed'
is false.)

Note, type specificity applies only to the function's immediate arguments
rather than their contents.  The scalar arguments, @code{Decimal(42)} and
@code{Fraction(42)} are be treated as distinct calls with distinct results.
In contrast, the tuple arguments @code{('answer', Decimal(42))} and
@code{('answer', Fraction(42))} are treated as equivalent.

The wrapped function is instrumented with a @code{cache_parameters()}
function that returns a new @ref{253,,dict} showing the values for `maxsize'
and `typed'.  This is for information purposes only.  Mutating the values
has no effect.

To help measure the effectiveness of the cache and tune the `maxsize'
parameter, the wrapped function is instrumented with a @code{cache_info()}
function that returns a @ref{639,,named tuple} showing `hits', `misses',
`maxsize' and `currsize'.

Le décorateur fournit également une fonction @code{cache_clear()} pour vider ou invalider le cache.

La fonction sous-jacente originale est accessible à travers l'attribut @code{__wrapped__}.  Ceci est utile pour l'introspection, pour outrepasser le cache, ou pour ré-englober la fonction avec un cache différent.

The cache keeps references to the arguments and return values until they age
out of the cache or until the cache is cleared.

If a method is cached, the @code{self} instance argument is included in the
cache.  See @ref{26ba,,Comment mettre en cache le résultat d'une méthode ?}

An LRU (least recently used) cache@footnote{https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_Recently_Used_(LRU)}
works best when the most recent calls are the best predictors of upcoming
calls (for example, the most popular articles on a news server tend to
change each day).  The cache's size limit assures that the cache does not
grow without bound on long-running processes such as web servers.

In general, the LRU cache should only be used when you want to reuse
previously computed values.  Accordingly, it doesn't make sense to cache
functions with side-effects, functions that need to create
distinct mutable objects on each call (such as generators and async functions),
or impure functions such as time() or random().

Exemple d'un cache LRU pour du contenu web statique :

@example
@@lru_cache(maxsize=32)
def get_pep(num):
    'Retrieve text of a Python Enhancement Proposal'
    resource = f'https://peps.python.org/pep-@{num:04d@}'
    try:
        with urllib.request.urlopen(resource) as s:
            return s.read()
    except urllib.error.HTTPError:
        return 'Not Found'

>>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:
...     pep = get_pep(n)
...     print(n, len(pep))

>>> get_pep.cache_info()
CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)
@end example

Exemple de calcul efficace de la suite de Fibonacci@footnote{https://fr.wikipedia.org/wiki/Suite_de_Fibonacci} en utilisant un cache pour implémenter la technique de programmation dynamique@footnote{https://fr.wikipedia.org/wiki/Programmation_dynamique} :

@example
@@lru_cache(maxsize=None)
def fib(n):
    if n < 2:
        return n
    return fib(n-1) + fib(n-2)

>>> [fib(n) for n in range(16)]
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]

>>> fib.cache_info()
CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)
@end example


Ajouté dans la version 3.2.



Modifié dans la version 3.3: L'option `typed' a été ajoutée.



Modifié dans la version 3.8: Ajout de l'option `user_function'.



Modifié dans la version 3.9: Added the function @code{cache_parameters()}

@end deffn

@geindex total_ordering() (dans le module functools)
@anchor{library/functools functools total_ordering}@anchor{f2d}
@deffn {Fonction} @@functools.total_ordering

A partir d'une classe définissant une ou plusieurs méthodes de comparaison riches, ce décorateur de classe fournit le reste.  Ceci simplifie l'effort à fournir dans la spécification de toutes les opérations de comparaison riche :

La classe doit définir au moins une de ces méthodes @code{__lt__()}, @code{__le__()}, @code{__gt__()}, ou @code{__ge__()}. De plus, la classe doit fournir une méthode @code{__eq__()}.

Par exemple :

@example
@@total_ordering
class Student:
    def _is_valid_operand(self, other):
        return (hasattr(other, "lastname") and
                hasattr(other, "firstname"))
    def __eq__(self, other):
        if not self._is_valid_operand(other):
            return NotImplemented
        return ((self.lastname.lower(), self.firstname.lower()) ==
                (other.lastname.lower(), other.firstname.lower()))
    def __lt__(self, other):
        if not self._is_valid_operand(other):
            return NotImplemented
        return ((self.lastname.lower(), self.firstname.lower()) <
                (other.lastname.lower(), other.firstname.lower()))
@end example

@cartouche
@quotation Note 
Même si ce décorateur permet de créer des types ordonnables facilement, cela vient avec un `coût' d'exécution et des traces d'exécution complexes pour les méthodes de comparaison dérivées. Si des tests de performances le révèlent comme un goulot d'étranglement, l'implémentation manuelle des six méthodes de comparaison riches résoudra normalement vos problèmes de rapidité.
@end quotation
@end cartouche

@cartouche
@quotation Note 
This decorator makes no attempt to override methods that have been
declared in the class `or its superclasses'. Meaning that if a
superclass defines a comparison operator, `total_ordering' will not
implement it again, even if the original method is abstract.
@end quotation
@end cartouche


Ajouté dans la version 3.2.



Modifié dans la version 3.4: Returning @code{NotImplemented} from the underlying comparison function for
unrecognised types is now supported.

@end deffn

@geindex partial() (dans le module functools)
@anchor{library/functools functools partial}@anchor{40a}
@deffn {Fonction} functools.partial (func, /, *args, **keywords)

Retourne un nouvel @ref{26bb,,objet partiel} qui, quand il est appelé, fonctionne comme `func' appelée avec les arguments positionnels `args' et les arguments nommés `keywords'. Si plus d'arguments sont fournis à l'appel, ils sont ajoutés à `args'. Si plus d'arguments nommés sont fournis, ils étendent et surchargent `keywords'. À peu près équivalent à :

@example
def partial(func, /, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = @{**keywords, **fkeywords@}
        return func(*args, *fargs, **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc
@end example

@ref{40a,,partial()} est utilisé pour une application de fonction partielle qui "gèle" une portion des arguments et/ou mots-clés d'une fonction donnant un nouvel objet avec une signature simplifiée.  Par exemple, @ref{40a,,partial()} peut être utilisé pour créer un appelable qui se comporte comme la fonction @ref{254,,int()} ou l'argument `base' est deux par défaut :

@example
>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18
@end example
@end deffn

@geindex partialmethod (classe dans functools)
@anchor{library/functools functools partialmethod}@anchor{a69}
@deffn {Classe} functools.partialmethod (func, /, *args, **keywords)

Retourne un nouveau descripteur @ref{a69,,partialmethod} qui se comporte comme @ref{40a,,partial} sauf qu'il est fait pour être utilisé comme une définition de méthode plutôt que d'être appelé directement.

`func' doit être un @ref{1ef3,,descriptor} ou un appelable (les objets qui sont les deux, comme les fonction normales, sont gérés comme des descripteurs).

Quand `func' est un descripteur (comme une fonction Python normale, @ref{165,,classmethod()}, @ref{40c,,staticmethod()}, @code{abstractmethod()} ou une autre instance de @ref{a69,,partialmethod}), les appels à @code{__get__} sont délégués au descripteur sous-jacent, et un @ref{26bb,,objet partiel} approprié est renvoyé comme résultat.

Quand `func' est un appelable non-descripteur, une méthode liée appropriée est crée dynamiquement. Elle se comporte comme une fonction Python normale quand elle est utilisée comme méthode : l'argument `self' sera inséré comme premier argument positionnel, avant les `args' et `keywords' fournis au constructeur @ref{a69,,partialmethod}.

Exemple :

@example
>>> class Cell:
...     def __init__(self):
...         self._alive = False
...     @@property
...     def alive(self):
...         return self._alive
...     def set_state(self, state):
...         self._alive = bool(state)
...     set_alive = partialmethod(set_state, True)
...     set_dead = partialmethod(set_state, False)
...
>>> c = Cell()
>>> c.alive
False
>>> c.set_alive()
>>> c.alive
True
@end example


Ajouté dans la version 3.4.

@end deffn

@geindex reduce() (dans le module functools)
@anchor{library/functools functools reduce}@anchor{12ba}
@deffn {Fonction} functools.reduce (function, iterable[, initial], /)

Apply `function' of two arguments cumulatively to the items of `iterable', from
left to right, so as to reduce the iterable to a single value.  For example,
@code{reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])} calculates @code{((((1+2)+3)+4)+5)}.
The left argument, `x', is the accumulated value and the right argument, `y', is
the update value from the `iterable'.  If the optional `initial' is present,
it is placed before the items of the iterable in the calculation, and serves as
a default when the iterable is empty.  If `initial' is not given and
`iterable' contains only one item, the first item is returned.

À peu près équivalent à :

@example
initial_missing = object()

def reduce(function, iterable, initial=initial_missing, /):
    it = iter(iterable)
    if initial is initial_missing:
        value = next(it)
    else:
        value = initial
    for element in it:
        value = function(value, element)
    return value
@end example

Voir @ref{9eb,,itertools.accumulate()} pour un itérateur qui génère toutes les valeurs intermédiaires.
@end deffn

@geindex singledispatch() (dans le module functools)
@anchor{library/functools functools singledispatch}@anchor{624}
@deffn {Fonction} @@functools.singledispatch

Transforme une fonction en une @ref{9df,,fonction générique} @ref{9e0,,single-dispatch}.

To define a generic function, decorate it with the @code{@@singledispatch}
decorator. When defining a function using @code{@@singledispatch}, note that the
dispatch happens on the type of the first argument:

@example
>>> from functools import singledispatch
>>> @@singledispatch
... def fun(arg, verbose=False):
...     if verbose:
...         print("Let me just say,", end=" ")
...     print(arg)
@end example

To add overloaded implementations to the function, use the @code{register()}
attribute of the generic function, which can be used as a decorator.  For
functions annotated with types, the decorator will infer the type of the
first argument automatically:

@example
>>> @@fun.register
... def _(arg: int, verbose=False):
...     if verbose:
...         print("Strength in numbers, eh?", end=" ")
...     print(arg)
...
>>> @@fun.register
... def _(arg: list, verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)
@end example

@ref{625,,types.UnionType} and @ref{626,,typing.Union} can also be used:

@example
>>> @@fun.register
... def _(arg: int | float, verbose=False):
...     if verbose:
...         print("Strength in numbers, eh?", end=" ")
...     print(arg)
...
>>> from typing import Union
>>> @@fun.register
... def _(arg: Union[list, set], verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)
...
@end example

Pour le code qui n’utilise pas les indications de type, le type souhaité peut être passé explicitement en argument au décorateur :

@example
>>> @@fun.register(complex)
... def _(arg, verbose=False):
...     if verbose:
...         print("Better than complicated.", end=" ")
...     print(arg.real, arg.imag)
...
@end example

For code that dispatches on a collections type (e.g., @code{list}), but wants
to typehint the items of the collection (e.g., @code{list[int]}), the
dispatch type should be passed explicitly to the decorator itself with the
typehint going into the function definition:

@example
>>> @@fun.register(list)
... def _(arg: list[int], verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)
@end example

@cartouche
@quotation Note 
At runtime the function will dispatch on an instance of a list regardless
of the type contained within the list i.e. @code{[1,2,3]} will be
dispatched the same as @code{["foo", "bar", "baz"]}. The annotation
provided in this example is for static type checkers only and has no
runtime impact.
@end quotation
@end cartouche

To enable registering @ref{26bc,,lambdas} and pre-existing functions,
the @code{register()} attribute can also be used in a functional form:

@example
>>> def nothing(arg, verbose=False):
...     print("Nothing.")
...
>>> fun.register(type(None), nothing)
@end example

The @code{register()} attribute returns the undecorated function. This
enables decorator stacking, @ref{a5,,pickling}, and the creation
of unit tests for each variant independently:

@example
>>> @@fun.register(float)
... @@fun.register(Decimal)
... def fun_num(arg, verbose=False):
...     if verbose:
...         print("Half of your number:", end=" ")
...     print(arg / 2)
...
>>> fun_num is fun
False
@end example

Quand elle est appelée, la fonction générique distribue sur le type du premier argument :

@example
>>> fun("Hello, world.")
Hello, world.
>>> fun("test.", verbose=True)
Let me just say, test.
>>> fun(42, verbose=True)
Strength in numbers, eh? 42
>>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)
Enumerate this:
0 spam
1 spam
2 eggs
3 spam
>>> fun(None)
Nothing.
>>> fun(1.23)
0.615
@end example

Where there is no registered implementation for a specific type, its
method resolution order is used to find a more generic implementation.
The original function decorated with @code{@@singledispatch} is registered
for the base @ref{a7a,,object} type, which means it is used if no better
implementation is found.

If an implementation is registered to an @ref{1193,,abstract base class},
virtual subclasses of the base class will be dispatched to that
implementation:

@example
>>> from collections.abc import Mapping
>>> @@fun.register
... def _(arg: Mapping, verbose=False):
...     if verbose:
...         print("Keys & Values")
...     for key, value in arg.items():
...         print(key, "=>", value)
...
>>> fun(@{"a": "b"@})
a => b
@end example

To check which implementation the generic function will choose for
a given type, use the @code{dispatch()} attribute:

@example
>>> fun.dispatch(float)
<function fun_num at 0x1035a2840>
>>> fun.dispatch(dict)    # note: default implementation
<function fun at 0x103fe0000>
@end example

Pour accéder à toutes les implémentations enregistrées, utiliser l'attribut en lecture seule @code{registry} :

@example
>>> fun.registry.keys()
dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>,
          <class 'decimal.Decimal'>, <class 'list'>,
          <class 'float'>])
>>> fun.registry[float]
<function fun_num at 0x1035a2840>
>>> fun.registry[object]
<function fun at 0x103fe0000>
@end example


Ajouté dans la version 3.4.



Modifié dans la version 3.7: The @code{register()} attribute now supports using type annotations.



Modifié dans la version 3.11: The @code{register()} attribute now supports @ref{625,,types.UnionType}
and @ref{626,,typing.Union} as type annotations.

@end deffn

@geindex singledispatchmethod (classe dans functools)
@anchor{library/functools functools singledispatchmethod}@anchor{9de}
@deffn {Classe} functools.singledispatchmethod (func)

Transforme une méthode en une @ref{9df,,fonction générique} @ref{9e0,,single-dispatch}.

To define a generic method, decorate it with the @code{@@singledispatchmethod}
decorator. When defining a function using @code{@@singledispatchmethod}, note
that the dispatch happens on the type of the first non-`self' or non-`cls'
argument:

@example
class Negator:
    @@singledispatchmethod
    def neg(self, arg):
        raise NotImplementedError("Cannot negate a")

    @@neg.register
    def _(self, arg: int):
        return -arg

    @@neg.register
    def _(self, arg: bool):
        return not arg
@end example

@code{@@singledispatchmethod} supports nesting with other decorators such as
@ref{165,,@@classmethod}. Note that to allow for
@code{dispatcher.register}, @code{singledispatchmethod} must be the `outer most'
decorator. Here is the @code{Negator} class with the @code{neg} methods bound to
the class, rather than an instance of the class:

@example
class Negator:
    @@singledispatchmethod
    @@classmethod
    def neg(cls, arg):
        raise NotImplementedError("Cannot negate a")

    @@neg.register
    @@classmethod
    def _(cls, arg: int):
        return -arg

    @@neg.register
    @@classmethod
    def _(cls, arg: bool):
        return not arg
@end example

The same pattern can be used for other similar decorators:
@ref{40c,,@@staticmethod},
@ref{106f,,@@abstractmethod}, and others.


Ajouté dans la version 3.8.

@end deffn

@geindex update_wrapper() (dans le module functools)
@anchor{library/functools functools update_wrapper}@anchor{100b}
@deffn {Fonction} functools.update_wrapper (wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Update a `wrapper' function to look like the `wrapped' function. The optional
arguments are tuples to specify which attributes of the original function are
assigned directly to the matching attributes on the wrapper function and which
attributes of the wrapper function are updated with the corresponding attributes
from the original function. The default values for these arguments are the
module level constants @code{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper
function's @ref{1e81,,__module__}, @ref{12b2,,__name__},
@ref{1e80,,__qualname__}, @ref{11b5,,__annotations__},
@ref{1e83,,__type_params__}, and @ref{11b6,,__doc__}, the
documentation string) and @code{WRAPPER_UPDATES} (which updates the wrapper
function's @ref{12b0,,__dict__}, i.e. the instance dictionary).

Pour autoriser l'accès à la fonction originale pour l'introspection ou à d'autres fins (par ex. outrepasser l'accès à un décorateur de cache comme @ref{9dd,,lru_cache()}), cette fonction ajoute automatiquement un attribut @code{__wrapped__} qui référence la fonction englobée.

La principale utilisation de cette fonction est dans les @ref{71b,,décorateurs} qui renvoient une nouvelle fonction. Si la fonction crée n'est pas mise à jour, ses métadonnées refléteront sa définition dans le décorateur, au lieu de la définition originale, métadonnées souvent bien moins utiles.

@ref{100b,,update_wrapper()} peut être utilisé avec des appelables autres que des fonctions. Tout attribut défini dans `assigned' ou `updated' qui ne sont pas l'objet englobé sont ignorés (cette fonction n'essaiera pas de les définir dans la fonction englobante). @ref{343,,AttributeError} est toujours levée si le fonction englobante elle même a des attributs non existants dans `updated'.


Modifié dans la version 3.2: The @code{__wrapped__} attribute is now automatically added.
The @ref{11b5,,__annotations__} attribute is now copied by default.
Missing attributes no longer trigger an @ref{343,,AttributeError}.



Modifié dans la version 3.4: L'attribut @code{__wrapped__} renvoie toujours la fonction englobée, même si cette fonction définit un attribut @code{__wrapped__}. (voir bpo-17482@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=17482})



Modifié dans la version 3.12: The @ref{1e83,,__type_params__} attribute is now copied by default.

@end deffn

@geindex wraps() (dans le module functools)
@anchor{library/functools functools wraps}@anchor{f48}
@deffn {Fonction} @@functools.wraps (wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Ceci est une fonction d'aide pour appeler @ref{100b,,update_wrapper()}  comme décorateur de fonction lors de la définition d'une fonction englobante.  C'est équivalent à  @code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)}. Par exemple :

@example
>>> from functools import wraps
>>> def my_decorator(f):
...     @@wraps(f)
...     def wrapper(*args, **kwds):
...         print('Calling decorated function')
...         return f(*args, **kwds)
...     return wrapper
...
>>> @@my_decorator
... def example():
...     """Docstring"""
...     print('Called example function')
...
>>> example()
Calling decorated function
Called example function
>>> example.__name__
'example'
>>> example.__doc__
'Docstring'
@end example

Sans l'utilisation de cette usine à décorateur, le nom de la fonction d'exemple aurait été @code{'wrapper'}, et la chaîne de documentation de la fonction @code{example()} originale aurait été perdue.
@end deffn

@menu
* Objets partial:: 

@end menu

@node Objets partial,,,functools --- Higher-order functions and operations on callable objects
@anchor{library/functools id1}@anchor{26bd}@anchor{library/functools partial-objects}@anchor{26bb}
@subsubsection Objets @code{partial}


Les objets @ref{40a,,partial} sont des objets appelables créés par @ref{40a,,partial()}. Ils ont trois attributs en lecture seule :

@geindex func (attribut functools.partial)
@anchor{library/functools functools partial func}@anchor{26be}
@deffn {Attribut} partial.func

Un objet ou une fonction appelable.  Les appels à l'objet @ref{40a,,partial} seront transmis à @ref{26be,,func} avec les nouveaux arguments et mots-clés.
@end deffn

@geindex args (attribut functools.partial)
@anchor{library/functools functools partial args}@anchor{26bf}
@deffn {Attribut} partial.args

Les arguments positionnels qui seront ajoutés avant les arguments fournis lors de l'appel d'un objet @ref{40a,,partial}.
@end deffn

@geindex keywords (attribut functools.partial)
@anchor{library/functools functools partial keywords}@anchor{26c0}
@deffn {Attribut} partial.keywords

Les arguments nommés qui seront fournis quand l'objet @ref{40a,,partial} est appelé.
@end deffn

@ref{40a,,partial} objects are like @ref{296,,function objects}
in that they are callable, weak referenceable, and can have attributes.
There are some important differences.  For instance, the
@ref{12b2,,__name__} and @ref{11b6,,function.__doc__} attributes
are not created automatically.  Also, @ref{40a,,partial} objects defined in
classes behave like static methods and do not transform into bound methods
during instance attribute look-up.

@node operator — Opérateurs standards en tant que fonctions,,functools --- Higher-order functions and operations on callable objects,Modules de programmation fonctionnelle
@anchor{library/operator doc}@anchor{26c1}@anchor{library/operator module-operator}@anchor{9e}@anchor{library/operator operator-standard-operators-as-functions}@anchor{26c2}
@subsection @code{operator} — Opérateurs standards en tant que fonctions


@geindex module; operator

`Code source :' Lib/operator.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/operator.py}

@c import operator
@c from operator import itemgetter, iadd


__________________________________________________________________


Le module @ref{9e,,operator} fournit un ensemble de fonctions correspondant aux opérateurs natifs de Python.  Par exemple, @code{operator.add(x, y)} correspond à l'expression @code{x+y}. Les noms de la plupart de ces fonctions sont ceux utilisés par les méthodes spéciales, sans les doubles tirets bas.  Pour assurer la rétrocompatibilité, la plupart de ces noms ont une variante `avec' les doubles tirets bas ; la forme simple est cependant à privilégier pour des raisons de clarté.

Les fonctions sont divisées en différentes catégories selon l'opération effectuée : comparaison entre objets, opérations logiques, opérations mathématiques ou opérations sur séquences.

Les fonctions de comparaison s'appliquent à tous les objets, et leur nom vient des opérateurs de comparaison qu'elles implémentent :

@geindex lt() (dans le module operator)
@geindex le() (dans le module operator)
@geindex eq() (dans le module operator)
@geindex ne() (dans le module operator)
@geindex ge() (dans le module operator)
@geindex gt() (dans le module operator)
@geindex __lt__() (dans le module operator)
@geindex __le__() (dans le module operator)
@geindex __eq__() (dans le module operator)
@geindex __ne__() (dans le module operator)
@geindex __ge__() (dans le module operator)
@geindex __gt__() (dans le module operator)
@anchor{library/operator operator lt}@anchor{26c3}
@deffn {Fonction} operator.lt (a, b)
@anchor{library/operator operator le}@anchor{26c4}
@deffnx {Fonction} operator.le (a, b)
@anchor{library/operator operator eq}@anchor{26c5}
@deffnx {Fonction} operator.eq (a, b)
@anchor{library/operator operator ne}@anchor{26c6}
@deffnx {Fonction} operator.ne (a, b)
@anchor{library/operator operator ge}@anchor{26c7}
@deffnx {Fonction} operator.ge (a, b)
@anchor{library/operator operator gt}@anchor{26c8}
@deffnx {Fonction} operator.gt (a, b)
@anchor{library/operator operator __lt__}@anchor{26c9}
@deffnx {Fonction} operator.__lt__ (a, b)
@anchor{library/operator operator __le__}@anchor{26ca}
@deffnx {Fonction} operator.__le__ (a, b)
@anchor{library/operator operator __eq__}@anchor{26cb}
@deffnx {Fonction} operator.__eq__ (a, b)
@anchor{library/operator operator __ne__}@anchor{26cc}
@deffnx {Fonction} operator.__ne__ (a, b)
@anchor{library/operator operator __ge__}@anchor{26cd}
@deffnx {Fonction} operator.__ge__ (a, b)
@anchor{library/operator operator __gt__}@anchor{26ce}
@deffnx {Fonction} operator.__gt__ (a, b)

Effectue une « comparaison riche » entre `a' et `b'. Plus précisément, @code{lt(a, b)} équivaut à @code{a < b}, @code{le(a, b)} équivaut à @code{a <= b}, @code{eq(a, b)} équivaut à @code{a == b}, @code{ne(a, b)} équivaut à @code{a != b}, @code{gt(a, b)} équivaut à @code{a > b} et @code{ge(a, b)} équivaut à @code{a >= b}.  Notez que ces fonctions peuvent renvoyer n'importe quelle valeur, convertible ou non en booléen.  Voir @ref{1ff5,,Comparaisons} pour plus d'informations sur les méthodes de comparaison riches.
@end deffn

En général, les opérations logiques s'appliquent aussi à tous les objets et implémentent les tests de vérité, d'identité et les opérations booléennes :

@geindex not_() (dans le module operator)
@geindex __not__() (dans le module operator)
@anchor{library/operator operator not_}@anchor{26cf}
@deffn {Fonction} operator.not_ (obj)
@anchor{library/operator operator __not__}@anchor{26d0}
@deffnx {Fonction} operator.__not__ (obj)

Renvoie le résultat de @ref{1fff,,not} `obj'.  (Notez qu'il n'existe pas de méthode @code{__not__()} pour les instances d'objet; seul le cœur de l'interpréteur définit cette opération. Le résultat dépend des méthodes @ref{12b3,,__bool__()} et @ref{1ee5,,__len__()}.)
@end deffn

@geindex truth() (dans le module operator)
@anchor{library/operator operator truth}@anchor{26d1}
@deffn {Fonction} operator.truth (obj)

Renvoie @ref{bfb,,True} si `obj' est vrai, et @ref{b25,,False} dans le cas contraire.  Équivaut à utiliser le constructeur de @ref{451,,bool}.
@end deffn

@geindex is_() (dans le module operator)
@anchor{library/operator operator is_}@anchor{26d2}
@deffn {Fonction} operator.is_ (a, b)

Renvoie @code{a is b}.  Vérifie si les deux paramètres sont le même objet.
@end deffn

@geindex is_not() (dans le module operator)
@anchor{library/operator operator is_not}@anchor{26d3}
@deffn {Fonction} operator.is_not (a, b)

Renvoie @code{a is not b}.  Vérifie si les deux paramètres sont deux objets distincts.
@end deffn

Les opérations mathématiques ou bit à bit sont les plus nombreuses :

@geindex abs() (dans le module operator)
@geindex __abs__() (dans le module operator)
@anchor{library/operator operator abs}@anchor{26d4}
@deffn {Fonction} operator.abs (obj)
@anchor{library/operator operator __abs__}@anchor{26d5}
@deffnx {Fonction} operator.__abs__ (obj)

Renvoie la valeur absolue de `obj'.
@end deffn

@geindex add() (dans le module operator)
@geindex __add__() (dans le module operator)
@anchor{library/operator operator add}@anchor{26d6}
@deffn {Fonction} operator.add (a, b)
@anchor{library/operator operator __add__}@anchor{26d7}
@deffnx {Fonction} operator.__add__ (a, b)

Renvoie @code{a + b} où `a' et `b' sont des nombres.
@end deffn

@geindex and_() (dans le module operator)
@geindex __and__() (dans le module operator)
@anchor{library/operator operator and_}@anchor{26d8}
@deffn {Fonction} operator.and_ (a, b)
@anchor{library/operator operator __and__}@anchor{26d9}
@deffnx {Fonction} operator.__and__ (a, b)

Renvoie le `et' bit à bit de `a' et `b'.
@end deffn

@geindex floordiv() (dans le module operator)
@geindex __floordiv__() (dans le module operator)
@anchor{library/operator operator floordiv}@anchor{26da}
@deffn {Fonction} operator.floordiv (a, b)
@anchor{library/operator operator __floordiv__}@anchor{26db}
@deffnx {Fonction} operator.__floordiv__ (a, b)

Renvoie @code{a // b}.
@end deffn

@geindex index() (dans le module operator)
@geindex __index__() (dans le module operator)
@anchor{library/operator operator index}@anchor{189c}
@deffn {Fonction} operator.index (a)
@anchor{library/operator operator __index__}@anchor{26dc}
@deffnx {Fonction} operator.__index__ (a)

Renvoie `a' converti en entier. Équivaut à @code{a.__index__()}.


Modifié dans la version 3.10: Le résultat a toujours le type @ref{254,,int}. Précédemment, le résultat aurait pu être une instance d'une sous-classe de @code{int}.

@end deffn

@geindex inv() (dans le module operator)
@geindex invert() (dans le module operator)
@geindex __inv__() (dans le module operator)
@geindex __invert__() (dans le module operator)
@anchor{library/operator operator inv}@anchor{26dd}
@deffn {Fonction} operator.inv (obj)
@anchor{library/operator operator invert}@anchor{26de}
@deffnx {Fonction} operator.invert (obj)
@anchor{library/operator operator __inv__}@anchor{26df}
@deffnx {Fonction} operator.__inv__ (obj)
@anchor{library/operator operator __invert__}@anchor{26e0}
@deffnx {Fonction} operator.__invert__ (obj)

Renvoie l'inverse bit à bit du nombre `obj'. Équivaut à @code{~obj}.
@end deffn

@geindex lshift() (dans le module operator)
@geindex __lshift__() (dans le module operator)
@anchor{library/operator operator lshift}@anchor{26e1}
@deffn {Fonction} operator.lshift (a, b)
@anchor{library/operator operator __lshift__}@anchor{26e2}
@deffnx {Fonction} operator.__lshift__ (a, b)

Renvoie le décalage de `b' bits vers la gauche de `a'.
@end deffn

@geindex mod() (dans le module operator)
@geindex __mod__() (dans le module operator)
@anchor{library/operator operator mod}@anchor{26e3}
@deffn {Fonction} operator.mod (a, b)
@anchor{library/operator operator __mod__}@anchor{26e4}
@deffnx {Fonction} operator.__mod__ (a, b)

Renvoie @code{a % b}.
@end deffn

@geindex mul() (dans le module operator)
@geindex __mul__() (dans le module operator)
@anchor{library/operator operator mul}@anchor{26b6}
@deffn {Fonction} operator.mul (a, b)
@anchor{library/operator operator __mul__}@anchor{26e5}
@deffnx {Fonction} operator.__mul__ (a, b)

Renvoie @code{a * b} où `a' et `b' sont des nombres.
@end deffn

@geindex matmul() (dans le module operator)
@geindex __matmul__() (dans le module operator)
@anchor{library/operator operator matmul}@anchor{e22}
@deffn {Fonction} operator.matmul (a, b)
@anchor{library/operator operator __matmul__}@anchor{26e6}
@deffnx {Fonction} operator.__matmul__ (a, b)

Renvoie @code{a @@ b}.


Ajouté dans la version 3.5.

@end deffn

@geindex neg() (dans le module operator)
@geindex __neg__() (dans le module operator)
@anchor{library/operator operator neg}@anchor{26e7}
@deffn {Fonction} operator.neg (obj)
@anchor{library/operator operator __neg__}@anchor{26e8}
@deffnx {Fonction} operator.__neg__ (obj)

Renvoie l'opposé de `obj' (@code{-obj}).
@end deffn

@geindex or_() (dans le module operator)
@geindex __or__() (dans le module operator)
@anchor{library/operator operator or_}@anchor{26e9}
@deffn {Fonction} operator.or_ (a, b)
@anchor{library/operator operator __or__}@anchor{26ea}
@deffnx {Fonction} operator.__or__ (a, b)

Renvoie le `ou' bit à bit de `a' et `b'.
@end deffn

@geindex pos() (dans le module operator)
@geindex __pos__() (dans le module operator)
@anchor{library/operator operator pos}@anchor{26eb}
@deffn {Fonction} operator.pos (obj)
@anchor{library/operator operator __pos__}@anchor{26ec}
@deffnx {Fonction} operator.__pos__ (obj)

Renvoie la valeur positive de `obj' (@code{+obj}).
@end deffn

@geindex pow() (dans le module operator)
@geindex __pow__() (dans le module operator)
@anchor{library/operator operator pow}@anchor{26ed}
@deffn {Fonction} operator.pow (a, b)
@anchor{library/operator operator __pow__}@anchor{26ee}
@deffnx {Fonction} operator.__pow__ (a, b)

Renvoie @code{a ** b} où `a' et `b' sont des nombres.
@end deffn

@geindex rshift() (dans le module operator)
@geindex __rshift__() (dans le module operator)
@anchor{library/operator operator rshift}@anchor{26ef}
@deffn {Fonction} operator.rshift (a, b)
@anchor{library/operator operator __rshift__}@anchor{26f0}
@deffnx {Fonction} operator.__rshift__ (a, b)

Renvoie le décalage de `b' bits vers la droite de `a'.
@end deffn

@geindex sub() (dans le module operator)
@geindex __sub__() (dans le module operator)
@anchor{library/operator operator sub}@anchor{26f1}
@deffn {Fonction} operator.sub (a, b)
@anchor{library/operator operator __sub__}@anchor{26f2}
@deffnx {Fonction} operator.__sub__ (a, b)

Renvoie @code{a - b}.
@end deffn

@geindex truediv() (dans le module operator)
@geindex __truediv__() (dans le module operator)
@anchor{library/operator operator truediv}@anchor{26f3}
@deffn {Fonction} operator.truediv (a, b)
@anchor{library/operator operator __truediv__}@anchor{26f4}
@deffnx {Fonction} operator.__truediv__ (a, b)

Renvoie @code{a / b} où 2/3 est 0.66 et non 0.  Appelée aussi division « réelle ».
@end deffn

@geindex xor() (dans le module operator)
@geindex __xor__() (dans le module operator)
@anchor{library/operator operator xor}@anchor{26f5}
@deffn {Fonction} operator.xor (a, b)
@anchor{library/operator operator __xor__}@anchor{26f6}
@deffnx {Fonction} operator.__xor__ (a, b)

Renvoie le ou exclusif bit à bit de `a' et `b'.
@end deffn

Les opérations sur séquences (et pour certaines, sur correspondances) sont :

@geindex concat() (dans le module operator)
@geindex __concat__() (dans le module operator)
@anchor{library/operator operator concat}@anchor{26f7}
@deffn {Fonction} operator.concat (a, b)
@anchor{library/operator operator __concat__}@anchor{26f8}
@deffnx {Fonction} operator.__concat__ (a, b)

Renvoie @code{a + b} où `a' et `b' sont des séquences.
@end deffn

@geindex contains() (dans le module operator)
@geindex __contains__() (dans le module operator)
@anchor{library/operator operator contains}@anchor{8c7}
@deffn {Fonction} operator.contains (a, b)
@anchor{library/operator operator __contains__}@anchor{26f9}
@deffnx {Fonction} operator.__contains__ (a, b)

Renvoie le résultat du test @code{b in a}. Notez que les opérandes sont inversées.
@end deffn

@geindex countOf() (dans le module operator)
@anchor{library/operator operator countOf}@anchor{8c9}
@deffn {Fonction} operator.countOf (a, b)

Renvoie le nombre d’occurrences de `b' dans `a'.
@end deffn

@geindex delitem() (dans le module operator)
@geindex __delitem__() (dans le module operator)
@anchor{library/operator operator delitem}@anchor{26fa}
@deffn {Fonction} operator.delitem (a, b)
@anchor{library/operator operator __delitem__}@anchor{26fb}
@deffnx {Fonction} operator.__delitem__ (a, b)

Renvoie la valeur de `a' à l'indice `b'.
@end deffn

@geindex getitem() (dans le module operator)
@geindex __getitem__() (dans le module operator)
@anchor{library/operator operator getitem}@anchor{26fc}
@deffn {Fonction} operator.getitem (a, b)
@anchor{library/operator operator __getitem__}@anchor{26fd}
@deffnx {Fonction} operator.__getitem__ (a, b)

Renvoie la valeur de `a' à l'indice `b'.
@end deffn

@geindex indexOf() (dans le module operator)
@anchor{library/operator operator indexOf}@anchor{8c8}
@deffn {Fonction} operator.indexOf (a, b)

Renvoie l'indice de la première occurrence de `b' dans `a'.
@end deffn

@geindex setitem() (dans le module operator)
@geindex __setitem__() (dans le module operator)
@anchor{library/operator operator setitem}@anchor{26fe}
@deffn {Fonction} operator.setitem (a, b, c)
@anchor{library/operator operator __setitem__}@anchor{26ff}
@deffnx {Fonction} operator.__setitem__ (a, b, c)

Affecte `c' dans `a' à l'indice `b'.
@end deffn

@geindex length_hint() (dans le module operator)
@anchor{library/operator operator length_hint}@anchor{f58}
@deffn {Fonction} operator.length_hint (obj, default=0)

Renvoie une estimation de la taille de l'objet `obj'. Tente d'abord de renvoyer la taille réelle, puis une estimation en appelant @ref{ef6,,object.__length_hint__()}, ou sinon la valeur par défaut.


Ajouté dans la version 3.4.

@end deffn

L'opération suivante marche avec les objets appelables :

@geindex call() (dans le module operator)
@geindex __call__() (dans le module operator)
@anchor{library/operator operator call}@anchor{180b}
@deffn {Fonction} operator.call (obj, /, *args, **kwargs)
@anchor{library/operator operator __call__}@anchor{2700}
@deffnx {Fonction} operator.__call__ (obj, /, *args, **kwargs)

Return @code{obj(*args, **kwargs)}.


Ajouté dans la version 3.11.

@end deffn

Le module @ref{9e,,operator} définit aussi des fonctions pour la recherche générique d'attributs ou d'objets. Elles sont particulièrement utiles pour construire rapidement des accesseurs d'attributs à passer en paramètre à @ref{84e,,map()}, @ref{bbc,,sorted()}, @ref{26b1,,itertools.groupby()} ou à toute autre fonction prenant une fonction en paramètre.

@geindex attrgetter() (dans le module operator)
@anchor{library/operator operator attrgetter}@anchor{e20}
@deffn {Fonction} operator.attrgetter (attr)

@deffnx {Fonction} operator.attrgetter (*attrs)

Renvoie un objet appelable qui récupère `attr' de son opérande. Si plus d'un attribut est demandé, renvoie un `n'-uplet d'attributs. Les noms des attributs peuvent aussi comporter des points. Par exemple :


@itemize *

@item 
Avec @code{f = attrgetter('name')}, l'appel @code{f(b)} renvoie @code{b.name}.

@item 
Avec @code{f = attrgetter('name', 'date')}, l'appel @code{f(b)} renvoie @code{(b.name, b.date)}.

@item 
Après @code{f = attrgetter('name.first', 'name.last')}, l'appel @code{f(b)} renvoie @code{(b.name.first, b.name.last)}.
@end itemize

Équivalent à :

@example
def attrgetter(*items):
    if any(not isinstance(item, str) for item in items):
        raise TypeError('attribute name must be a string')
    if len(items) == 1:
        attr = items[0]
        def g(obj):
            return resolve_attr(obj, attr)
    else:
        def g(obj):
            return tuple(resolve_attr(obj, attr) for attr in items)
    return g

def resolve_attr(obj, attr):
    for name in attr.split("."):
        obj = getattr(obj, name)
    return obj
@end example
@end deffn

@geindex itemgetter() (dans le module operator)
@anchor{library/operator operator itemgetter}@anchor{a50}
@deffn {Fonction} operator.itemgetter (item)

@deffnx {Fonction} operator.itemgetter (*items)

Renvoie un objet appelable qui récupère `item' de l'opérande en utilisant la méthode @ref{280,,__getitem__()}. Si plusieurs `item' sont passés en paramètre, renvoie un `n'-uplet des valeurs récupérées. Par exemple :


@itemize *

@item 
Avec @code{f = itemgetter(2)}, @code{f(r)} renvoie @code{r[2]}.

@item 
Avec @code{g = itemgetter(2, 5, 3)}, @code{g(r)} renvoie @code{(r[2], r[5], r[3])}.
@end itemize

Équivalent à :

@example
def itemgetter(*items):
    if len(items) == 1:
        item = items[0]
        def g(obj):
            return obj[item]
    else:
        def g(obj):
            return tuple(obj[item] for item in items)
    return g
@end example

Les `items' en entrée peuvent être de n'importe quel type tant que celui-ci est géré par la méthode @ref{280,,__getitem__()} de l'opérande. Les dictionnaires acceptent toute valeur @ref{5fb,,hachable}. Les listes, `n'-uplets et chaînes de caractères acceptent un index ou une tranche :

@example
>>> itemgetter(1)('ABCDEFG')
'B'
>>> itemgetter(1, 3, 5)('ABCDEFG')
('B', 'D', 'F')
>>> itemgetter(slice(2, None))('ABCDEFG')
'CDEFG'
>>> soldier = dict(rank='captain', name='dotterbart')
>>> itemgetter('rank')(soldier)
'captain'
@end example

Exemple d'utilisation de @ref{a50,,itemgetter()} pour récupérer des champs spécifiques d'un `n'-uplet :

@example
>>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
>>> getcount = itemgetter(1)
>>> list(map(getcount, inventory))
[3, 2, 5, 1]
>>> sorted(inventory, key=getcount)
[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
@end example
@end deffn

@geindex methodcaller() (dans le module operator)
@anchor{library/operator operator methodcaller}@anchor{e21}
@deffn {Fonction} operator.methodcaller (name, /, *args, **kwargs)

Renvoie un objet appelable qui appelle la méthode `name' de son opérande. Si des paramètres supplémentaires et/ou des paramètres nommés sont donnés, ils seront aussi passés à la méthode. Par exemple :


@itemize *

@item 
Avec  @code{f = methodcaller('name')}, @code{f(b)} renvoie @code{b.name()}.

@item 
Avec @code{f = methodcaller('name', 'foo', bar=1)}, @code{f(b)} renvoie @code{b.name('foo', bar=1)}.
@end itemize

Équivalent à :

@example
def methodcaller(name, /, *args, **kwargs):
    def caller(obj):
        return getattr(obj, name)(*args, **kwargs)
    return caller
@end example
@end deffn

@menu
* Correspondances entre opérateurs et fonctions:: 
* Opérateurs en-place:: 

@end menu

@node Correspondances entre opérateurs et fonctions,Opérateurs en-place,,operator — Opérateurs standards en tant que fonctions
@anchor{library/operator mapping-operators-to-functions}@anchor{2701}@anchor{library/operator operator-map}@anchor{2702}
@subsubsection Correspondances entre opérateurs et fonctions


Le tableau montre la correspondance entre les symboles des opérateurs Python et les fonctions du module @ref{9e,,operator}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Opération

@tab

Syntaxe

@tab

Fonction

@item

Addition

@tab

@code{a + b}

@tab

@code{add(a, b)}

@item

Concaténation

@tab

@code{seq1 + seq2}

@tab

@code{concat(seq1, seq2)}

@item

Test d'inclusion

@tab

@code{obj in seq}

@tab

@code{contains(seq, obj)}

@item

Division

@tab

@code{a / b}

@tab

@code{truediv(a, b)}

@item

Division

@tab

@code{a // b}

@tab

@code{floordiv(a, b)}

@item

`Et' bit à bit

@tab

@code{a & b}

@tab

@code{and_(a, b)}

@item

`Ou exclusif' bit à bit

@tab

@code{a ^ b}

@tab

@code{xor(a, b)}

@item

Inversion bit à bit

@tab

@code{~ a}

@tab

@code{invert(a)}

@item

`Ou' bit à bit

@tab

@code{a | b}

@tab

@code{or_(a, b)}

@item

Exponentiation

@tab

@code{a ** b}

@tab

@code{pow(a, b)}

@item

Identité

@tab

@code{a is b}

@tab

@code{is_(a, b)}

@item

Identité

@tab

@code{a is not b}

@tab

@code{is_not(a, b)}

@item

Affectation par index

@tab

@code{obj[k] = v}

@tab

@code{setitem(obj, k, v)}

@item

Suppression par index

@tab

@code{del obj[k]}

@tab

@code{delitem(obj, k)}

@item

Indexation

@tab

@code{obj[k]}

@tab

@code{getitem(obj, k)}

@item

Décalage bit à bit gauche

@tab

@code{a << b}

@tab

@code{lshift(a, b)}

@item

Modulo

@tab

@code{a % b}

@tab

@code{mod(a, b)}

@item

Multiplication

@tab

@code{a * b}

@tab

@code{mul(a, b)}

@item

Multiplication matricielle

@tab

@code{a @@ b}

@tab

@code{matmul(a, b)}

@item

Opposé

@tab

@code{- a}

@tab

@code{neg(a)}

@item

Négation (logique)

@tab

@code{not a}

@tab

@code{not_(a)}

@item

Valeur positive

@tab

@code{+ a}

@tab

@code{pos(a)}

@item

Décalage bit à bit droite

@tab

@code{a >> b}

@tab

@code{rshift(a, b)}

@item

Affectation par tranche

@tab

@code{seq[i:j] = values}

@tab

@code{setitem(seq, slice(i, j), values)}

@item

Suppression par tranche

@tab

@code{del seq[i:j]}

@tab

@code{delitem(seq, slice(i, j))}

@item

Tranche

@tab

@code{seq[i:j]}

@tab

@code{getitem(seq, slice(i, j))}

@item

Formatage de chaînes de caractères

@tab

@code{s % obj}

@tab

@code{mod(s, obj)}

@item

Soustraction

@tab

@code{a - b}

@tab

@code{sub(a, b)}

@item

Test de véracité

@tab

@code{obj}

@tab

@code{truth(obj)}

@item

Ordre

@tab

@code{a < b}

@tab

@code{lt(a, b)}

@item

Ordre

@tab

@code{a <= b}

@tab

@code{le(a, b)}

@item

Égalité

@tab

@code{a == b}

@tab

@code{eq(a, b)}

@item

Inégalité

@tab

@code{a != b}

@tab

@code{ne(a, b)}

@item

Ordre

@tab

@code{a >= b}

@tab

@code{ge(a, b)}

@item

Ordre

@tab

@code{a > b}

@tab

@code{gt(a, b)}

@end multitable


@node Opérateurs en-place,,Correspondances entre opérateurs et fonctions,operator — Opérateurs standards en tant que fonctions
@anchor{library/operator in-place-operators}@anchor{2703}
@subsubsection Opérateurs en-place


Beaucoup d'opérations ont une version travaillant « en-place ». Les fonctions listées ci-dessous fournissent un accès plus direct aux opérateurs en-place que la syntaxe Python habituelle ; par exemple, l'expression @ref{2704,,statement} @code{x += y} équivaut à @code{x = operator.iadd(x, y)}.  Autrement dit, l'expression @code{z = operator.iadd(x, y)} équivaut à l'expression composée @code{z = x; z += y}.

Dans ces exemples, notez que lorsqu'une méthode en-place est appelée, le calcul et l'affectation sont effectués en deux étapes distinctes. Les fonctions en-place de la liste ci-dessous ne font que la première, en appelant la méthode en-place. La seconde étape, l'affectation, n'est pas effectuée.

Pour des paramètres non-mutables comme les chaînes de caractères, les nombres et les `n'-uplets, la nouvelle valeur est calculée, mais pas affectée à la variable d'entrée :

@example
>>> a = 'hello'
>>> iadd(a, ' world')
'hello world'
>>> a
'hello'
@end example

Pour des paramètres mutables comme les listes et les dictionnaires, la méthode en-place modifiera la valeur, aucune affectation ultérieure n'est nécessaire :

@example
>>> s = ['h', 'e', 'l', 'l', 'o']
>>> iadd(s, [' ', 'w', 'o', 'r', 'l', 'd'])
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
>>> s
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
@end example

@geindex iadd() (dans le module operator)
@geindex __iadd__() (dans le module operator)
@anchor{library/operator operator iadd}@anchor{2705}
@deffn {Fonction} operator.iadd (a, b)
@anchor{library/operator operator __iadd__}@anchor{2706}
@deffnx {Fonction} operator.__iadd__ (a, b)

@code{a = iadd(a, b)} équivaut à @code{a += b}.
@end deffn

@geindex iand() (dans le module operator)
@geindex __iand__() (dans le module operator)
@anchor{library/operator operator iand}@anchor{2707}
@deffn {Fonction} operator.iand (a, b)
@anchor{library/operator operator __iand__}@anchor{2708}
@deffnx {Fonction} operator.__iand__ (a, b)

@code{a = iand(a, b)} équivaut à @code{a &= b}.
@end deffn

@geindex iconcat() (dans le module operator)
@geindex __iconcat__() (dans le module operator)
@anchor{library/operator operator iconcat}@anchor{2709}
@deffn {Fonction} operator.iconcat (a, b)
@anchor{library/operator operator __iconcat__}@anchor{270a}
@deffnx {Fonction} operator.__iconcat__ (a, b)

@code{a = iconcat(a, b)} équivaut à @code{a += b} où `a' et `b' sont des séquences.
@end deffn

@geindex ifloordiv() (dans le module operator)
@geindex __ifloordiv__() (dans le module operator)
@anchor{library/operator operator ifloordiv}@anchor{270b}
@deffn {Fonction} operator.ifloordiv (a, b)
@anchor{library/operator operator __ifloordiv__}@anchor{270c}
@deffnx {Fonction} operator.__ifloordiv__ (a, b)

@code{a = ifloordiv(a, b)} équivaut à @code{a //= b}.
@end deffn

@geindex ilshift() (dans le module operator)
@geindex __ilshift__() (dans le module operator)
@anchor{library/operator operator ilshift}@anchor{270d}
@deffn {Fonction} operator.ilshift (a, b)
@anchor{library/operator operator __ilshift__}@anchor{270e}
@deffnx {Fonction} operator.__ilshift__ (a, b)

@code{a = ilshift(a, b)} équivaut à @code{a <<= b}.
@end deffn

@geindex imod() (dans le module operator)
@geindex __imod__() (dans le module operator)
@anchor{library/operator operator imod}@anchor{270f}
@deffn {Fonction} operator.imod (a, b)
@anchor{library/operator operator __imod__}@anchor{2710}
@deffnx {Fonction} operator.__imod__ (a, b)

@code{a = imod(a, b)} équivaut à @code{a %= b}.
@end deffn

@geindex imul() (dans le module operator)
@geindex __imul__() (dans le module operator)
@anchor{library/operator operator imul}@anchor{2711}
@deffn {Fonction} operator.imul (a, b)
@anchor{library/operator operator __imul__}@anchor{2712}
@deffnx {Fonction} operator.__imul__ (a, b)

@code{a = imul(a, b)} équivaut à @code{a *= b}.
@end deffn

@geindex imatmul() (dans le module operator)
@geindex __imatmul__() (dans le module operator)
@anchor{library/operator operator imatmul}@anchor{e23}
@deffn {Fonction} operator.imatmul (a, b)
@anchor{library/operator operator __imatmul__}@anchor{2713}
@deffnx {Fonction} operator.__imatmul__ (a, b)

@code{a = imatmul(a, b)} équivaut à @code{a @@= b}.


Ajouté dans la version 3.5.

@end deffn

@geindex ior() (dans le module operator)
@geindex __ior__() (dans le module operator)
@anchor{library/operator operator ior}@anchor{2714}
@deffn {Fonction} operator.ior (a, b)
@anchor{library/operator operator __ior__}@anchor{2715}
@deffnx {Fonction} operator.__ior__ (a, b)

@code{a = ior(a, b)} équivaut à @code{a |= b}.
@end deffn

@geindex ipow() (dans le module operator)
@geindex __ipow__() (dans le module operator)
@anchor{library/operator operator ipow}@anchor{2716}
@deffn {Fonction} operator.ipow (a, b)
@anchor{library/operator operator __ipow__}@anchor{2717}
@deffnx {Fonction} operator.__ipow__ (a, b)

@code{a = ipow(a, b)} équivaut à @code{a **= b}.
@end deffn

@geindex irshift() (dans le module operator)
@geindex __irshift__() (dans le module operator)
@anchor{library/operator operator irshift}@anchor{2718}
@deffn {Fonction} operator.irshift (a, b)
@anchor{library/operator operator __irshift__}@anchor{2719}
@deffnx {Fonction} operator.__irshift__ (a, b)

@code{a = irshift(a, b)} équivaut à @code{a >>= b}.
@end deffn

@geindex isub() (dans le module operator)
@geindex __isub__() (dans le module operator)
@anchor{library/operator operator isub}@anchor{271a}
@deffn {Fonction} operator.isub (a, b)
@anchor{library/operator operator __isub__}@anchor{271b}
@deffnx {Fonction} operator.__isub__ (a, b)

@code{a = isub(a, b)} équivaut à @code{a -= b}.
@end deffn

@geindex itruediv() (dans le module operator)
@geindex __itruediv__() (dans le module operator)
@anchor{library/operator operator itruediv}@anchor{271c}
@deffn {Fonction} operator.itruediv (a, b)
@anchor{library/operator operator __itruediv__}@anchor{271d}
@deffnx {Fonction} operator.__itruediv__ (a, b)

@code{a = itruediv(a, b)} équivaut à @code{a /= b}.
@end deffn

@geindex ixor() (dans le module operator)
@geindex __ixor__() (dans le module operator)
@anchor{library/operator operator ixor}@anchor{271e}
@deffn {Fonction} operator.ixor (a, b)
@anchor{library/operator operator __ixor__}@anchor{271f}
@deffnx {Fonction} operator.__ixor__ (a, b)

@code{a = ixor(a, b)} équivaut à @code{a ^= b}.
@end deffn

@node Accès aux Fichiers et aux Dossiers,Persistance des données,Modules de programmation fonctionnelle,La bibliothèque standard
@anchor{library/filesys doc}@anchor{2720}@anchor{library/filesys file-and-directory-access}@anchor{2721}@anchor{library/filesys filesys}@anchor{2722}
@section Accès aux Fichiers et aux Dossiers


Les modules décrits dans ce chapitre servent à accéder aux fichiers et aux dossiers. Des modules, par exemple, pour lire les propriétés des fichiers, manipuler des chemins de manière portable, et créer des fichiers temporaires. La liste exhaustive des modules de ce chapitre est :

@menu
* pathlib — Chemins de système de fichiers orientés objet:: 
* os.path: os path --- Common pathname manipulations. Common pathname manipulations
* stat: stat --- Interpreting stat results. Interpreting stat() results
* filecmp: filecmp --- File and Directory Comparisons. File and Directory Comparisons
* tempfile: tempfile --- Generate temporary files and directories. Generate temporary files and directories
* glob: glob --- Unix style pathname pattern expansion. Unix style pathname pattern expansion
* fnmatch: fnmatch --- Unix filename pattern matching. Unix filename pattern matching
* linecache: linecache --- Random access to text lines. Random access to text lines
* shutil: shutil --- High-level file operations. High-level file operations

@end menu

@node pathlib — Chemins de système de fichiers orientés objet,os path --- Common pathname manipulations,,Accès aux Fichiers et aux Dossiers
@anchor{library/pathlib doc}@anchor{2723}@anchor{library/pathlib module-pathlib}@anchor{a3}@anchor{library/pathlib pathlib-object-oriented-filesystem-paths}@anchor{2724}
@subsection @code{pathlib} — Chemins de système de fichiers orientés objet


@geindex module; pathlib


Ajouté dans la version 3.4.


`Code source :' Lib/pathlib/@footnote{https://github.com/python/cpython/tree/3.13/Lib/pathlib/}

@geindex path;operations


__________________________________________________________________


Ce module offre des classes représentant le système de fichiers avec la sémantique appropriée pour différents systèmes d'exploitation. Les classes de chemins sont divisées en @ref{2725,,chemins purs}, qui fournissent uniquement des opérations de manipulation sans entrées-sorties, et @ref{2726,,chemins concrets}, qui héritent des chemins purs et fournissent également les opérations d'entrées-sorties.

@image{python-figures/pathlib-inheritance,,,Inheritance diagram showing the classes available in pathlib. The most basic class is PurePath@comma{} which has three direct subclasses: PurePosixPath@comma{} PureWindowsPath@comma{} and Path. Further to these four classes@comma{} there are two classes that use multiple inheritance: PosixPath subclasses PurePosixPath and Path@comma{} and WindowsPath subclasses PureWindowsPath and Path.,png}

Si vous n'avez jamais utilisé ce module précédemment, ou si vous n'êtes pas sûr de quelle classe est faite pour votre tâche, @ref{226,,Path} est très certainement ce dont vous avez besoin. Elle instancie un @ref{2726,,chemin concret} pour la plateforme sur laquelle s'exécute le code.

Les chemins purs sont utiles dans certains cas particuliers ; par exemple :


@enumerate 

@item 
Si vous voulez manipuler des chemins Windows sur une machine Unix (ou vice versa). Vous ne pouvez pas instancier un @ref{2727,,WindowsPath} quand vous êtes sous Unix, mais vous pouvez instancier @ref{168e,,PureWindowsPath}.

@item 
Vous voulez être sûr que votre code manipule des chemins sans réellement accéder au système d'exploitation. Dans ce cas, instancier une de ces classes pures peut être utile puisqu'elle ne possède tout simplement aucune opération permettant d'accéder au système d'exploitation.
@end enumerate


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 428
PEP 428@footnote{https://peps.python.org/pep-0428/} : le module `pathlib' – implémentation orientée-objet des chemins de systèmes de fichiers.



@subsubheading Voir aussi


Pour de la manipulation de chemins bas-niveau avec des chaînes de caractères, vous pouvez aussi utiliser le module @ref{a1,,os.path}.


@menu
* Utilisation basique:: 
* Exceptions: Exceptions<6>. 
* Chemins purs:: 
* Chemins concrets:: 
* Pattern language:: 
* Comparaison avec les outils du module glob:: 
* Comparaison aux modules os et os.path: Comparaison aux modules os et os path. 

@end menu

@node Utilisation basique,Exceptions<6>,,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib basic-use}@anchor{2728}
@subsubsection Utilisation basique


Importer la classe principale :

@example
>>> from pathlib import Path
@end example

Lister les sous-dossiers :

@example
>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]
@end example

Lister les fichiers source Python dans cette arborescence de dossiers :

@example
>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]
@end example

Naviguer à l'intérieur d'une arborescence de dossiers :

@example
>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')
@end example

Récupérer les propriétés de chemin :

@example
>>> q.exists()
True
>>> q.is_dir()
False
@end example

Ouvrir un fichier :

@example
>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'
@end example

@node Exceptions<6>,Chemins purs,Utilisation basique,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib exceptions}@anchor{2729}
@subsubsection Exceptions


@geindex UnsupportedOperation
@anchor{library/pathlib pathlib UnsupportedOperation}@anchor{224}
@deffn {Exception} pathlib.UnsupportedOperation

Une exception qui hérite de @ref{225,,NotImplementedError} levée quand une opération non prise en charge est appelée sur un objet `path'


Ajouté dans la version 3.13.

@end deffn

@node Chemins purs,Chemins concrets,Exceptions<6>,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib id1}@anchor{272a}@anchor{library/pathlib pure-paths}@anchor{2725}
@subsubsection Chemins purs


Les objets chemins purs fournissent les opérations de gestion de chemin qui n'accèdent pas réellement au système de fichiers. Il y a trois façons d'accéder à ces classes que nous appelons aussi `familles' :

@geindex PurePath (classe dans pathlib)
@anchor{library/pathlib pathlib PurePath}@anchor{490}
@deffn {Classe} pathlib.PurePath (*pathsegments)

Une classe générique qui représente la famille de chemin du système (l'instancier crée soit un @ref{272b,,PurePosixPath} soit un @ref{168e,,PureWindowsPath}) :

@example
>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')
@end example

Each element of `pathsegments' can be either a string representing a
path segment, or an object implementing the @ref{c3f,,os.PathLike} interface
where the @ref{c40,,__fspath__()} method returns a string,
such as another path object:

@example
>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')
@end example

Quand `pathsegments' est vide, le dossier courant est utilisé :

@example
>>> PurePath()
PurePosixPath('.')
@end example

Si un segment est un chemin absolu, tous les segments précédents sont ignorés (comme @ref{15bc,,os.path.join()}) :

@example
>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')
@end example

Sous Windows, le nom de lecteur est conservé quand un chemin relatif à la racine (par exemple @code{r'\foo'}) est rencontré :

@example
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')
@end example

Les points et slashs superflus sont supprimés, mais les doubles points (@code{'..'}) et les double slashes  (@code{'//'}) en début de segment ne le sont pas, puisque cela changerait la signification du chemin pour différentes raisons (par exemple pour des liens symboliques ou des chemins UNC) :

@example
>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('//foo/bar')
PurePosixPath('//foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')
@end example

(une analyse naïve considérerait @code{PurePosixPath('foo/../bar')} équivalent à @code{PurePosixPath('bar')}, ce qui est faux si @code{foo} est un lien symbolique vers un autre dossier)

Les objets chemins purs implémentent l'interface @ref{c3f,,os.PathLike}, leur permettant d'être utilisés n'importe où l'interface est acceptée.


Modifié dans la version 3.6: ajout de la gestion de l'interface @ref{c3f,,os.PathLike}.

@end deffn

@geindex PurePosixPath (classe dans pathlib)
@anchor{library/pathlib pathlib PurePosixPath}@anchor{272b}
@deffn {Classe} pathlib.PurePosixPath (*pathsegments)

Sous-classe de @ref{490,,PurePath}, cette famille de chemin représente les chemins de systèmes de fichiers en dehors des chemins Windows :

@example
>>> PurePosixPath('/etc/hosts')
PurePosixPath('/etc/hosts')
@end example

`pathsegments' est spécifié de manière similaire à @ref{490,,PurePath}.
@end deffn

@geindex PureWindowsPath (classe dans pathlib)
@anchor{library/pathlib pathlib PureWindowsPath}@anchor{168e}
@deffn {Classe} pathlib.PureWindowsPath (*pathsegments)

Sous-classe de @ref{490,,PurePath}, cette famille de chemin représente les chemins de systèmes de fichiers Windows, y compris les chemins UNC (voir UNC paths@footnote{https://en.wikipedia.org/wiki/Path_(computing)#UNC}) :

@example
>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')
@end example

`pathsegments' est spécifié de manière similaire à @ref{490,,PurePath}.
@end deffn

Sans tenir compte du système sur lequel vous êtes, vous pouvez instancier toutes ces classes, puisqu'elles ne fournissent aucune opération qui appelle le système d'exploitation.

@menu
* Propriétés générales:: 
* Opérateurs: Opérateurs<2>. 
* Accéder aux parties individuelles:: 
* Méthodes et propriétés:: 

@end menu

@node Propriétés générales,Opérateurs<2>,,Chemins purs
@anchor{library/pathlib general-properties}@anchor{272c}
@subsubsection Propriétés générales


Paths are immutable and @ref{5fb,,hashable}.  Paths of a same flavour are comparable
and orderable.  These properties respect the flavour's case-folding
semantics:

@example
>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in @{ PureWindowsPath('foo') @}
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True
@end example

Les chemins de différentes familles ne sont pas égaux et ne peuvent être ordonnés :

@example
>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'
@end example

@node Opérateurs<2>,Accéder aux parties individuelles,Propriétés générales,Chemins purs
@anchor{library/pathlib operators}@anchor{272d}
@subsubsection Opérateurs


L'opérateur slash aide à créer les chemins enfants, de manière similaire à @ref{15bc,,os.path.join()}. Si l'argument est un chemin absolu, le chemin précédent est ignoré. Sous Windows, le lecteur n'est pas effacé quand l'argument est un chemin relatif enraciné (par exemple @code{r'\foo'}) :

@example
>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')
>>> p / '/an_absolute_path'
PurePosixPath('/an_absolute_path')
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')
@end example

Un objet chemin peut être utilisé n'importe où un objet implémentant @ref{c3f,,os.PathLike} est accepté :

@example
>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'
@end example

La représentation d'un chemin en chaîne de caractères est celle du chemin brut du système de fichiers lui-même (dans sa forme native, c.-à-d. avec des antislashs sous Windows), telle que vous pouvez la passer à n'importe quelle fonction prenant un chemin en tant que chaîne de caractères :

@example
>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'
@end example

De manière similaire, appeler @ref{1bd,,bytes} sur un chemin donne le chemin brut du système de fichiers en tant que bytes, tel qu'encodé par @ref{c43,,os.fsencode()} :

@example
>>> bytes(p)
b'/etc'
@end example

@cartouche
@quotation Note 
Appeler @ref{1bd,,bytes} est seulement recommandé sous Unix. Sous Windows, la forme Unicode est la représentation canonique des chemins du système de fichiers.
@end quotation
@end cartouche

@node Accéder aux parties individuelles,Méthodes et propriétés,Opérateurs<2>,Chemins purs
@anchor{library/pathlib accessing-individual-parts}@anchor{272e}
@subsubsection Accéder aux parties individuelles


Pour accéder aux parties individuelles (composantes) d'un chemin, utilisez les propriétés suivantes :

@geindex parts (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parts}@anchor{272f}
@deffn {Attribut} PurePath.parts

Un tuple donnant accès aux différentes composantes du chemin :

@example
>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')
@end example

(notez comme le lecteur et la racine locale sont regroupés en une seule partie)
@end deffn

@node Méthodes et propriétés,,Accéder aux parties individuelles,Chemins purs
@anchor{library/pathlib methods-and-properties}@anchor{2730}
@subsubsection Méthodes et propriétés


@c from pathlib import PurePath, PurePosixPath, PureWindowsPath

Les chemins purs fournissent les méthodes et propriétés suivantes :

@geindex parser (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parser}@anchor{229}
@deffn {Attribut} PurePath.parser

The implementation of the @ref{a1,,os.path} module used for low-level path
parsing and joining: either @code{posixpath} or @code{ntpath}.


Ajouté dans la version 3.13.

@end deffn

@geindex drive (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath drive}@anchor{2731}
@deffn {Attribut} PurePath.drive

Une chaîne représentant la lettre du lecteur ou le nom, s'il y en a un :

@example
>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
'@w{'}
>>> PurePosixPath('/etc').drive
'@w{'}
@end example

Les partages UNC sont aussi considérés comme des lecteurs :

@example
>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'
@end example
@end deffn

@geindex root (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath root}@anchor{2732}
@deffn {Attribut} PurePath.root

Une chaîne de caractères représentant la racine (locale ou globale), s'il y en a une :

@example
>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
'@w{'}
>>> PurePosixPath('/etc').root
'/'
@end example

Les partages UNC ont toujours une racine :

@example
>>> PureWindowsPath('//host/share').root
'\\'
@end example

Si le chemin commence par plus de deux slashes successifs, @ref{272b,,PurePosixPath} n'en conserve qu'un :

@example
>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'
@end example

@cartouche
@quotation Note 
Ce comportement se conforme au paragraphe 4.11 Pathname Resolution@footnote{https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap04.html#tag_04_11} des `Open Group Base Specifications' version 6 :

`"A pathname that begins with two successive slashes may be interpreted in
an implementation-defined manner, although more than two leading slashes
shall be treated as a single slash."'
@end quotation
@end cartouche
@end deffn

@geindex anchor (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath anchor}@anchor{2733}
@deffn {Attribut} PurePath.anchor

La concaténation du lecteur et de la racine :

@example
>>> PureWindowsPath('c:/Program Files/').anchor
'c:\\'
>>> PureWindowsPath('c:Program Files/').anchor
'c:'
>>> PurePosixPath('/etc').anchor
'/'
>>> PureWindowsPath('//host/share').anchor
'\\\\host\\share\\'
@end example
@end deffn

@geindex parents (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parents}@anchor{80a}
@deffn {Attribut} PurePath.parents

Une séquence immuable fournissant accès aux ancêtres logiques du chemin :

@example
>>> p = PureWindowsPath('c:/foo/bar/setup.py')
>>> p.parents[0]
PureWindowsPath('c:/foo/bar')
>>> p.parents[1]
PureWindowsPath('c:/foo')
>>> p.parents[2]
PureWindowsPath('c:/')
@end example


Modifié dans la version 3.10: La séquence de `parents' prend désormais en charge les @ref{2106,,tranches} et les valeurs d’index négatives.

@end deffn

@geindex parent (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath parent}@anchor{16b7}
@deffn {Attribut} PurePath.parent

Le parent logique du chemin :

@example
>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')
@end example

Vous ne pouvez pas aller au-delà d'une ancre, ou d'un chemin vide :

@example
>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')
@end example

@cartouche
@quotation Note 
C'est une opération purement lexicale, d'où le comportement suivant :

@example
>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')
@end example

Si vous voulez remonter un chemin arbitraire du système de fichiers, il est recommandé d'appeler d'abord @ref{1685,,Path.resolve()} de manière à résoudre les liens symboliques et éliminer les composantes @code{".."}.
@end quotation
@end cartouche
@end deffn

@geindex name (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath name}@anchor{2734}
@deffn {Attribut} PurePath.name

Une chaîne représentant la composante finale du chemin, en excluant le lecteur et la racine, si présent :

@example
>>> PurePosixPath('my/library/setup.py').name
'setup.py'
@end example

Les noms de lecteur UNC ne sont pas pris en compte :

@example
>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
'@w{'}
@end example
@end deffn

@geindex suffix (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath suffix}@anchor{2735}
@deffn {Attribut} PurePath.suffix

The last dot-separated portion of the final component, if any:

@example
>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
'@w{'}
@end example

Ceci est communément appelé une extension de fichier.
@end deffn

@geindex suffixes (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath suffixes}@anchor{2736}
@deffn {Attribut} PurePath.suffixes

Une liste de suffixes du chemin concerné, souvent appelées extensions de fichier :

@example
>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]
@end example
@end deffn

@geindex stem (attribut pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath stem}@anchor{2737}
@deffn {Attribut} PurePath.stem

La composante finale du chemin, sans son suffixe :

@example
>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'
@end example
@end deffn

@geindex as_posix() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath as_posix}@anchor{2738}
@deffn {Méthode} PurePath.as_posix ()

Renvoie une représentation en chaîne de caractères du chemin avec des slashs (@code{/}) :

@example
>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'
@end example
@end deffn

@geindex is_absolute() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath is_absolute}@anchor{16b6}
@deffn {Méthode} PurePath.is_absolute ()

Renvoie si le chemin est absolu ou non. Un chemin est considéré absolu s'il a une racine et un lecteur (si la famille le permet) :

@example
>>> PurePosixPath('/a/b').is_absolute()
True
>>> PurePosixPath('a/b').is_absolute()
False

>>> PureWindowsPath('c:/a/b').is_absolute()
True
>>> PureWindowsPath('/a/b').is_absolute()
False
>>> PureWindowsPath('c:').is_absolute()
False
>>> PureWindowsPath('//some/share').is_absolute()
True
@end example
@end deffn

@geindex is_relative_to() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath is_relative_to}@anchor{2c7}
@deffn {Méthode} PurePath.is_relative_to (other)

Renvoie si ce chemin est relatif ou non au chemin `other'.

@example
>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False
@end example

This method is string-based; it neither accesses the filesystem nor treats
"@code{..}" segments specially. The following code is equivalent:

@example
>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False
@end example


Ajouté dans la version 3.9.



Deprecated since version 3.12, will be removed in version 3.14: Passing additional arguments is deprecated; if supplied, they are joined
with `other'.

@end deffn

@geindex is_reserved() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath is_reserved}@anchor{2a3}
@deffn {Méthode} PurePath.is_reserved ()

Avec @ref{168e,,PureWindowsPath}, renvoie @code{True} si le chemin est considéré réservé sous Windows, @code{False} sinon. Avec @ref{272b,,PurePosixPath}, @code{False} est systématiquement renvoyé.


Modifié dans la version 3.13: Windows path names that contain a colon, or end with a dot or a space,
are considered reserved. UNC paths may be reserved.



Deprecated since version 3.13, will be removed in version 3.15: This method is deprecated; use @ref{220,,os.path.isreserved()} to detect
reserved paths on Windows.

@end deffn

@geindex joinpath() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath joinpath}@anchor{2739}
@deffn {Méthode} PurePath.joinpath (*pathsegments)

Calling this method is equivalent to combining the path with each of
the given `pathsegments' in turn:

@example
>>> PurePosixPath('/etc').joinpath('passwd')
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
PurePosixPath('/etc/init.d/apache2')
>>> PureWindowsPath('c:').joinpath('/Program Files')
PureWindowsPath('c:/Program Files')
@end example
@end deffn

@geindex full_match() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath full_match}@anchor{228}
@deffn {Méthode} PurePath.full_match (pattern, *, case_sensitive=None)

Match this path against the provided glob-style pattern.  Return @code{True}
if matching is successful, @code{False} otherwise.  For example:

@example
>>> PurePath('a/b.py').full_match('a/*.py')
True
>>> PurePath('a/b.py').full_match('*.py')
False
>>> PurePath('/a/b/c.py').full_match('/a/**')
True
>>> PurePath('/a/b/c.py').full_match('**/*.py')
True
@end example


@subsubheading Voir aussi


documentation @ref{273a,,Pattern language}.


Comme pour les autres méthodes, la sensibilité à la casse est la sensibilité par défaut de la plate-forme :

@example
>>> PurePosixPath('b.py').full_match('*.PY')
False
>>> PureWindowsPath('b.py').full_match('*.PY')
True
@end example

La sensibilité à la casse peut être choisie en passant @code{True} ou @code{False} à l'argument `case_sensitive'.


Ajouté dans la version 3.13.

@end deffn

@geindex match() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath match}@anchor{496}
@deffn {Méthode} PurePath.match (pattern, *, case_sensitive=None)

Match this path against the provided non-recursive glob-style pattern.
Return @code{True} if matching is successful, @code{False} otherwise.

This method is similar to @ref{228,,full_match()}, but empty patterns
aren't allowed (@ref{1ff,,ValueError} is raised), the recursive wildcard
"@code{**}" isn't supported (it acts like non-recursive "@code{*}"), and if a
relative pattern is provided, then matching is done from the right:

@example
>>> PurePath('a/b.py').match('*.py')
True
>>> PurePath('/a/b/c.py').match('b/*.py')
True
>>> PurePath('/a/b/c.py').match('a/*.py')
False
@end example


Modifié dans la version 3.12: Le paramètre `pattern' accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.12: ajout du paramètre `case_sensitive'

@end deffn

@geindex relative_to() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath relative_to}@anchor{2c8}
@deffn {Méthode} PurePath.relative_to (other, walk_up=False)

Compute a version of this path relative to the path represented by
`other'.  If it's impossible, @ref{1ff,,ValueError} is raised:

@example
>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/')
PurePosixPath('etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other is absolute.
@end example

When `walk_up' is false (the default), the path must start with `other'.
When the argument is true, @code{..} entries may be added to form the
relative path. In all other cases, such as the paths referencing
different drives, @ref{1ff,,ValueError} is raised.:

@example
>>> p.relative_to('/usr', walk_up=True)
PurePosixPath('../etc/passwd')
>>> p.relative_to('foo', walk_up=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not on the same drive as 'foo' OR one path is relative and the other is absolute.
@end example

@cartouche
@quotation Avertissement 
This function is part of @ref{490,,PurePath} and works with strings.
It does not check or access the underlying file structure.
This can impact the `walk_up' option as it assumes that no symlinks
are present in the path; call @ref{1685,,resolve()} first if
necessary to resolve symlinks.
@end quotation
@end cartouche


Modifié dans la version 3.12: The `walk_up' parameter was added (old behavior is the same as @code{walk_up=False}).



Deprecated since version 3.12, will be removed in version 3.14: Passing additional positional arguments is deprecated; if supplied,
they are joined with `other'.

@end deffn

@geindex with_name() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_name}@anchor{1680}
@deffn {Méthode} PurePath.with_name (name)

Renvoie un nouveau chemin avec @ref{2734,,name} changé. Si le chemin original n'a pas de nom, une @code{ValueError} est levée :

@example
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name
@end example
@end deffn

@geindex with_stem() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_stem}@anchor{15e6}
@deffn {Méthode} PurePath.with_stem (stem)

Renvoie un nouveau chemin avec @ref{2737,,stem} changé. Si le chemin original n'a pas de nom, `ValueError' est levée :

@example
>>> p = PureWindowsPath('c:/Downloads/draft.txt')
>>> p.with_stem('final')
PureWindowsPath('c:/Downloads/final.txt')
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_stem('lib')
PureWindowsPath('c:/Downloads/lib.gz')
>>> p = PureWindowsPath('c:/')
>>> p.with_stem('@w{'})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name
@end example


Ajouté dans la version 3.9.

@end deffn

@geindex with_suffix() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_suffix}@anchor{15a0}
@deffn {Méthode} PurePath.with_suffix (suffix)

Renvoie un nouveau chemin avec @ref{2735,,suffix} changé. Si le chemin original n'a pas de suffixe, le nouveau `suffix' est alors ajouté. Si `suffix' est une chaîne vide, le suffixe d'origine est retiré :

@example
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
>>> p = PureWindowsPath('README.txt')
>>> p.with_suffix('@w{'})
PureWindowsPath('README')
@end example
@end deffn

@geindex with_segments() (méthode pathlib.PurePath)
@anchor{library/pathlib pathlib PurePath with_segments}@anchor{491}
@deffn {Méthode} PurePath.with_segments (*pathsegments)

Create a new path object of the same type by combining the given
`pathsegments'. This method is called whenever a derivative path is created,
such as from @ref{16b7,,parent} and @ref{2c8,,relative_to()}. Subclasses may
override this method to pass information to derivative paths, for example:

@example
from pathlib import PurePosixPath

class MyPath(PurePosixPath):
    def __init__(self, *pathsegments, session_id):
        super().__init__(*pathsegments)
        self.session_id = session_id

    def with_segments(self, *pathsegments):
        return type(self)(*pathsegments, session_id=self.session_id)

etc = MyPath('/etc', session_id=42)
hosts = etc / 'hosts'
print(hosts.session_id)  # 42
@end example


Ajouté dans la version 3.12.

@end deffn

@node Chemins concrets,Pattern language,Chemins purs,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib concrete-paths}@anchor{2726}@anchor{library/pathlib id2}@anchor{273b}
@subsubsection Chemins concrets


Les chemins concrets sont des sous-classes des chemins purs. En plus des opérations fournies par ces derniers, ils fournissent aussi des méthodes pour faire appel au système sur des objets chemin. Il y a trois façons d'instancier des chemins concrets :

@geindex Path (classe dans pathlib)
@anchor{library/pathlib pathlib Path}@anchor{226}
@deffn {Classe} pathlib.Path (*pathsegments)

Une sous-classe de @ref{490,,PurePath}, cette classe représente les chemins concrets d'une famille de chemins de système de fichiers (l'instancier créé soit un @ref{273c,,PosixPath}, soit un @ref{2727,,WindowsPath}) :

@example
>>> Path('setup.py')
PosixPath('setup.py')
@end example

`pathsegments' est spécifié de manière similaire à @ref{490,,PurePath}.
@end deffn

@geindex PosixPath (classe dans pathlib)
@anchor{library/pathlib pathlib PosixPath}@anchor{273c}
@deffn {Classe} pathlib.PosixPath (*pathsegments)

Une sous-classe de @ref{226,,Path} et @ref{272b,,PurePosixPath}, cette classe représente les chemins concrets de systèmes de fichiers non Windows :

@example
>>> PosixPath('/etc/hosts')
PosixPath('/etc/hosts')
@end example

`pathsegments' est spécifié de manière similaire à @ref{490,,PurePath}.


Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} on Windows. In previous versions,
@ref{225,,NotImplementedError} was raised instead.

@end deffn

@geindex WindowsPath (classe dans pathlib)
@anchor{library/pathlib pathlib WindowsPath}@anchor{2727}
@deffn {Classe} pathlib.WindowsPath (*pathsegments)

Une sous-classe de @ref{226,,Path} et @ref{168e,,PureWindowsPath}, cette classe représente les chemins concrets de systèmes de fichiers Windows :

@example
>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')
@end example

`pathsegments' est spécifié de manière similaire à @ref{490,,PurePath}.


Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} on non-Windows platforms. In previous
versions, @ref{225,,NotImplementedError} was raised instead.

@end deffn

Vous pouvez seulement instancier la classe de la famille qui correspond à votre système (permettre des appels au système pour des familles de chemins non compatibles pourrait mener à des bogues ou à des pannes de votre application) :

@example
>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system
@end example

Some concrete path methods can raise an @ref{40d,,OSError} if a system call fails
(for example because the path doesn't exist).

@menu
* Analyse et génération des URI:: 
* Expansion et résolution de chemins:: 
* Requête sur type et statut du fichier:: 
* Lecture et écriture de fichiers: Lecture et écriture de fichiers<2>. 
* Lecture des dossiers:: 
* Création de fichiers et de dossiers:: 
* Renommage et suppression:: 
* Permissions et propriété:: 

@end menu

@node Analyse et génération des URI,Expansion et résolution de chemins,,Chemins concrets
@anchor{library/pathlib parsing-and-generating-uris}@anchor{273d}
@subsubsection Analyse et génération des URI


Concrete path objects can be created from, and represented as, 'file' URIs
conforming to 
@geindex RFC; RFC 8089
RFC 8089@footnote{https://datatracker.ietf.org/doc/html/rfc8089.html}.

@cartouche
@quotation Note 
File URIs are not portable across machines with different
@ref{273e,,filesystem encodings}.
@end quotation
@end cartouche

@geindex from_uri() (méthode de la classe pathlib.Path)
@anchor{library/pathlib pathlib Path from_uri}@anchor{227}
@deffn {Méthode} classmethod Path.from_uri (uri)

Return a new path object from parsing a 'file' URI. For example:

@example
>>> p = Path.from_uri('file:///etc/hosts')
PosixPath('/etc/hosts')
@end example

On Windows, DOS device and UNC paths may be parsed from URIs:

@example
>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file://server/share')
WindowsPath('//server/share')
@end example

Plusieurs variants du formulaire sont pris en charge :

@example
>>> p = Path.from_uri('file:////server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file://///server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file:c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file:/c|/windows')
WindowsPath('c:/windows')
@end example

@ref{1ff,,ValueError} is raised if the URI does not start with @code{file:}, or
the parsed path isn't absolute.


Ajouté dans la version 3.13.

@end deffn

@geindex as_uri() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path as_uri}@anchor{273f}
@deffn {Méthode} Path.as_uri ()

Represent the path as a 'file' URI.  @ref{1ff,,ValueError} is raised if
the path isn't absolute.

@example
>>> p = PosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = WindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'
@end example

For historical reasons, this method is also available from
@ref{490,,PurePath} objects. However, its use of @ref{c43,,os.fsencode()} makes
it strictly impure.
@end deffn

@node Expansion et résolution de chemins,Requête sur type et statut du fichier,Analyse et génération des URI,Chemins concrets
@anchor{library/pathlib expanding-and-resolving-paths}@anchor{2740}
@subsubsection Expansion et résolution de chemins


@geindex home() (méthode de la classe pathlib.Path)
@anchor{library/pathlib pathlib Path home}@anchor{e30}
@deffn {Méthode} classmethod Path.home ()

Renvoie un nouveau chemin représentant le dossier d’accueil de l'utilisateur (comme renvoyé par @ref{a02,,os.path.expanduser()} avec la construction @code{~}). Si le dossier d’accueil de l'utilisateur ne peut être résolu, @ref{193,,RuntimeError} est levée.

@example
>>> Path.home()
PosixPath('/home/antoine')
@end example


Ajouté dans la version 3.5.

@end deffn

@geindex expanduser() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path expanduser}@anchor{e2f}
@deffn {Méthode} Path.expanduser ()

Renvoie un nouveau chemin avec les résolutions des constructions @code{~} et @code{~user}, comme renvoyé par @ref{a02,,os.path.expanduser()}. Si le dossier d’accueil de l'utilisateur ne peut être résolu, @ref{193,,RuntimeError} est levée.

@example
>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')
@end example


Ajouté dans la version 3.5.

@end deffn

@geindex cwd() (méthode de la classe pathlib.Path)
@anchor{library/pathlib pathlib Path cwd}@anchor{16b5}
@deffn {Méthode} classmethod Path.cwd ()

Renvoie un nouveau chemin représentant le dossier courant (comme renvoyé par @ref{1521,,os.getcwd()}) :

@example
>>> Path.cwd()
PosixPath('/home/antoine/pathlib')
@end example
@end deffn

@geindex absolute() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path absolute}@anchor{1637}
@deffn {Méthode} Path.absolute ()

Rend le chemin absolu, sans normaliser ou résoudre les liens symboliques. Renvoie un nouveau :

@example
>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')
@end example
@end deffn

@geindex resolve() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path resolve}@anchor{1685}
@deffn {Méthode} Path.resolve (strict=False)

Rend le chemin absolu, résolvant les liens symboliques. Un nouveau chemin est renvoyé :

@example
>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')
@end example

Les composantes "@code{..}" sont aussi éliminées (c'est la seule méthode pour le faire) :

@example
>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
@end example

If a path doesn't exist or a symlink loop is encountered, and `strict' is
@code{True}, @ref{40d,,OSError} is raised.  If `strict' is @code{False}, the path is
resolved as far as possible and any remainder is appended without checking
whether it exists.


Modifié dans la version 3.6: The `strict' parameter was added (pre-3.6 behavior is strict).



Modifié dans la version 3.13: Symlink loops are treated like other errors: @ref{40d,,OSError} is raised in
strict mode, and no exception is raised in non-strict mode. In previous
versions, @ref{193,,RuntimeError} is raised no matter the value of `strict'.

@end deffn

@geindex readlink() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path readlink}@anchor{90c}
@deffn {Méthode} Path.readlink ()

Renvoie le chemin vers lequel le lien symbolique pointe (tel que renvoyé par @ref{90d,,os.readlink()}) :

@example
>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')
@end example


Ajouté dans la version 3.9.



Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} if @ref{90d,,os.readlink()} is not
available. In previous versions, @ref{225,,NotImplementedError} was raised.

@end deffn

@node Requête sur type et statut du fichier,Lecture et écriture de fichiers<2>,Expansion et résolution de chemins,Chemins concrets
@anchor{library/pathlib querying-file-type-and-status}@anchor{2741}
@subsubsection Requête sur type et statut du fichier



Modifié dans la version 3.8: @ref{a04,,exists()}, @ref{22d,,is_dir()}, @ref{22c,,is_file()},
@ref{a05,,is_mount()}, @ref{a06,,is_symlink()},
@ref{a07,,is_block_device()}, @ref{a08,,is_char_device()},
@ref{a09,,is_fifo()}, @ref{a0a,,is_socket()} now return @code{False}
instead of raising an exception for paths that contain characters
unrepresentable at the OS level.


@geindex stat() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path stat}@anchor{80d}
@deffn {Méthode} Path.stat (*, follow_symlinks=True)

Return an @ref{1475,,os.stat_result} object containing information about this path, like @ref{48a,,os.stat()}.
The result is looked up at each call to this method.

Cette méthode suit normalement les liens symboliques ; pour appeler @code{stat} sur un lien symbolique lui-même, ajoutez l’argument @code{follow_symlinks=False}, ou utilisez @ref{2742,,lstat()}.

@example
>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554
@end example


Modifié dans la version 3.10: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex lstat() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path lstat}@anchor{2742}
@deffn {Méthode} Path.lstat ()

Comme @ref{80d,,Path.stat()}, mais, si le chemin pointe vers un lien symbolique, renvoie les informations du lien symbolique plutôt que celui de sa cible.
@end deffn

@geindex exists() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path exists}@anchor{a04}
@deffn {Méthode} Path.exists (*, follow_symlinks=True)

Renvoie @code{True} si le chemin pointe vers un fichier ou un dossier existant.

This method normally follows symlinks; to check if a symlink exists, add
the argument @code{follow_symlinks=False}.

@example
>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False
@end example


Modifié dans la version 3.12: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex is_file() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_file}@anchor{22c}
@deffn {Méthode} Path.is_file (*, follow_symlinks=True)

Return @code{True} if the path points to a regular file, @code{False} if it
points to another kind of file.

@code{False} est aussi renvoyé si le chemin n'existe pas ou est un lien symbolique cassé. D’autres erreurs (telles que les erreurs de permission) sont propagées.

This method normally follows symlinks; to exclude symlinks, add the
argument @code{follow_symlinks=False}.


Modifié dans la version 3.13: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex is_dir() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_dir}@anchor{22d}
@deffn {Méthode} Path.is_dir (*, follow_symlinks=True)

Return @code{True} if the path points to a directory, @code{False} if it points
to another kind of file.

@code{False} est aussi renvoyé si le chemin n'existe pas ou est un lien symbolique cassé. D’autres erreurs (telles que les erreurs de permission) sont propagées.

This method normally follows symlinks; to exclude symlinks to directories,
add the argument @code{follow_symlinks=False}.


Modifié dans la version 3.13: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex is_symlink() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_symlink}@anchor{a06}
@deffn {Méthode} Path.is_symlink ()

Renvoie @code{True} si le chemin pointe sur un lien symbolique, @code{False} sinon.

@code{False} est aussi renvoyé si le chemin n'existe pas ; d'autres erreurs (telles que les erreurs de permission) sont propagées.
@end deffn

@geindex is_junction() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_junction}@anchor{495}
@deffn {Méthode} Path.is_junction ()

Return @code{True} if the path points to a junction, and @code{False} for any other
type of file. Currently only Windows supports junctions.


Ajouté dans la version 3.12.

@end deffn

@geindex is_mount() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_mount}@anchor{a05}
@deffn {Méthode} Path.is_mount ()

Return @code{True} if the path is a `mount point': a point in a
file system where a different file system has been mounted.  On POSIX, the
function checks whether `path''s parent, @code{path/..}, is on a different
device than `path', or whether @code{path/..} and `path' point to the same
i-node on the same device --- this should detect mount points for all Unix
and POSIX variants.  On Windows, a mount point is considered to be a drive
letter root (e.g. @code{c:\}), a UNC share (e.g. @code{\\server\share}), or a
mounted filesystem directory.


Ajouté dans la version 3.7.



Modifié dans la version 3.12: Ajout de la gestion de Windows.

@end deffn

@geindex is_socket() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_socket}@anchor{a0a}
@deffn {Méthode} Path.is_socket ()

Renvoie @code{True} si le chemin pointe vers un connecteur Unix (ou un lien symbolique pointant vers un connecteur Unix), @code{False} s'il pointe vers une autre sorte de fichier.

@code{False} est aussi renvoyé si le chemin n'existe pas ou est un lien symbolique cassé. D’autres erreurs (telles que les erreurs de permission) sont propagées.
@end deffn

@geindex is_fifo() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_fifo}@anchor{a09}
@deffn {Méthode} Path.is_fifo ()

Renvoie @code{True} si le chemin pointe vers une `FIFO' (ou un lien symbolique pointant vers une `FIFO'), @code{False} s'il pointe vers une autre sorte de fichier.

@code{False} est aussi renvoyé si le chemin n'existe pas ou est un lien symbolique cassé. D’autres erreurs (telles que les erreurs de permission) sont propagées.
@end deffn

@geindex is_block_device() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_block_device}@anchor{a07}
@deffn {Méthode} Path.is_block_device ()

Renvoie @code{True} si le chemin pointe vers un périphérique (ou un lien symbolique pointant vers un périphérique), @code{False} s'il pointe vers une autre sorte de fichier.

@code{False} est aussi renvoyé si le chemin n'existe pas ou est un lien symbolique cassé. D’autres erreurs (telles que les erreurs de permission) sont propagées.
@end deffn

@geindex is_char_device() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path is_char_device}@anchor{a08}
@deffn {Méthode} Path.is_char_device ()

Renvoie @code{True} si le chemin pointe vers un périphérique à caractères (ou un lien symbolique pointant vers un périphérique à caractères), @code{False} s'il pointe vers une autre sorte de fichier.

@code{False} est aussi renvoyé si le chemin n'existe pas ou est un lien symbolique cassé. D’autres erreurs (telles que les erreurs de permission) sont propagées.
@end deffn

@geindex samefile() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path samefile}@anchor{e2d}
@deffn {Méthode} Path.samefile (other_path)

Renvoie si ce chemin pointe vers le même fichier que `other_path', qui peut être soit un chemin, soit une chaîne de caractères. La sémantique est similaire à @ref{f5c,,os.path.samefile()} et @ref{f5b,,os.path.samestat()}.

@ref{40d,,OSError} peut être levée si l'un des fichiers ne peut être accédé pour quelque raison.

@example
>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True
@end example


Ajouté dans la version 3.5.

@end deffn

@node Lecture et écriture de fichiers<2>,Lecture des dossiers,Requête sur type et statut du fichier,Chemins concrets
@anchor{library/pathlib reading-and-writing-files}@anchor{2743}
@subsubsection Lecture et écriture de fichiers


@geindex open() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path open}@anchor{2744}
@deffn {Méthode} Path.open (mode='r', buffering=-1, encoding=None, errors=None, newline=None)

Ouvre le fichier pointé par le chemin, comme la fonction native @ref{505,,open()} le fait :

@example
>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'
@end example
@end deffn

@geindex read_text() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path read_text}@anchor{e32}
@deffn {Méthode} Path.read_text (encoding=None, errors=None, newline=None)

Renvoie le contenu décodé du fichier pointé en tant que chaîne de caractères :

@example
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
@end example

Le fichier est ouvert, puis fermé. Les paramètres optionnels ont la même signification que dans @ref{505,,open()}.


Ajouté dans la version 3.5.



Modifié dans la version 3.13: ajout du paramètre `newline'.

@end deffn

@geindex read_bytes() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path read_bytes}@anchor{e34}
@deffn {Méthode} Path.read_bytes ()

Renvoie le contenu binaire du fichier pointé en tant que chaîne d’octets :

@example
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
@end example


Ajouté dans la version 3.5.

@end deffn

@geindex write_text() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path write_text}@anchor{e31}
@deffn {Méthode} Path.write_text (data, encoding=None, errors=None, newline=None)

Ouvre le fichier pointé en mode texte, écrit `data' dedans, et ferme le fichier :

@example
>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'
@end example

Le fichier du même nom, s'il existe, est écrasé. Les paramètres optionnels ont la même signification que dans @ref{505,,open()}.


Ajouté dans la version 3.5.



Modifié dans la version 3.10: ajout du paramètre `newline'.

@end deffn

@geindex write_bytes() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path write_bytes}@anchor{e33}
@deffn {Méthode} Path.write_bytes (data)

Ouvre le fichier pointé en mode binaire, écrit `data' dedans, et ferme le fichier :

@example
>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'
@end example

Le fichier du même nom, s'il existe, est écrasé.


Ajouté dans la version 3.5.

@end deffn

@node Lecture des dossiers,Création de fichiers et de dossiers,Lecture et écriture de fichiers<2>,Chemins concrets
@anchor{library/pathlib reading-directories}@anchor{2745}
@subsubsection Lecture des dossiers


@geindex iterdir() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path iterdir}@anchor{15ba}
@deffn {Méthode} Path.iterdir ()

Quand le chemin pointe vers un dossier, donne par séquences les objets chemin du contenu du dossier :

@example
>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')
@end example

The children are yielded in arbitrary order, and the special entries
@code{'.'} and @code{'..'} are not included.  If a file is removed from or added
to the directory after creating the iterator, it is unspecified whether
a path object for that file is included.

Si le chemin n'est pas un dossier ou n'est pas accessible, @ref{40d,,OSError} est levée.
@end deffn

@geindex glob() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path glob}@anchor{22a}
@deffn {Méthode} Path.glob (pattern, *, case_sensitive=None, recurse_symlinks=False)

`Glob' de manière relative suivant le motif `pattern' fourni dans le dossier représenté par ce chemin, donnant tous les fichiers correspondants (de n'importe quelle sorte) :

@example
>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]
>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]
@end example


@subsubheading Voir aussi


documentation @ref{273a,,Pattern language}.


By default, or when the `case_sensitive' keyword-only argument is set to
@code{None}, this method matches paths using platform-specific casing rules:
typically, case-sensitive on POSIX, and case-insensitive on Windows.
Set `case_sensitive' to @code{True} or @code{False} to override this behaviour.

By default, or when the `recurse_symlinks' keyword-only argument is set to
@code{False}, this method follows symlinks except when expanding "@code{**}"
wildcards. Set `recurse_symlinks' to @code{True} to always follow symlinks.

Lève un @ref{1848,,évènement d’audit} @code{pathlib.Path.glob} avec comme arguments @code{self} et @code{pattern}.


Modifié dans la version 3.12: ajout du paramètre `case_sensitive'



Modifié dans la version 3.13: Ajout du paramètre `recurse_symlinks'.



Modifié dans la version 3.13: Le paramètre `pattern' accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.13: Any @ref{40d,,OSError} exceptions raised from scanning the filesystem are
suppressed. In previous versions, such exceptions are suppressed in many
cases, but not all.

@end deffn

@geindex rglob() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path rglob}@anchor{22b}
@deffn {Méthode} Path.rglob (pattern, *, case_sensitive=None, recurse_symlinks=False)

Glob the given relative `pattern' recursively.  This is like calling
@ref{22a,,Path.glob()} with "@code{**/}" added in front of the `pattern'.


@subsubheading Voir aussi


Documentation pour @ref{273a,,Pattern language} et @ref{22a,,Path.glob()} .


Lève un @ref{1848,,évènement d’audit} @code{pathlib.Path.glob} avec comme arguments @code{self} et @code{pattern}.


Modifié dans la version 3.12: ajout du paramètre `case_sensitive'



Modifié dans la version 3.13: Ajout du paramètre `recurse_symlinks'.



Modifié dans la version 3.13: Le paramètre `pattern' accepte un @ref{29d,,path-like object}.

@end deffn

@geindex walk() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path walk}@anchor{492}
@deffn {Méthode} Path.walk (top_down=True, on_error=None, follow_symlinks=False)

Generate the file names in a directory tree by walking the tree
either top-down or bottom-up.

For each directory in the directory tree rooted at `self' (including
`self' but excluding '.' and '..'), the method yields a 3-tuple of
@code{(dirpath, dirnames, filenames)}.

`dirpath' is a @ref{226,,Path} to the directory currently being walked,
`dirnames' is a list of strings for the names of subdirectories in `dirpath'
(excluding @code{'.'} and @code{'..'}), and `filenames' is a list of strings for
the names of the non-directory files in `dirpath'. To get a full path
(which begins with `self') to a file or directory in `dirpath', do
@code{dirpath / name}. Whether or not the lists are sorted is file
system-dependent.

If the optional argument `top_down' is true (which is the default), the triple for a
directory is generated before the triples for any of its subdirectories
(directories are walked top-down).  If `top_down' is false, the triple
for a directory is generated after the triples for all of its subdirectories
(directories are walked bottom-up). No matter the value of `top_down', the
list of subdirectories is retrieved before the triples for the directory and
its subdirectories are walked.

When `top_down' is true, the caller can modify the `dirnames' list in-place
(for example, using @ref{1734,,del} or slice assignment), and @ref{492,,Path.walk()}
will only recurse into the subdirectories whose names remain in `dirnames'.
This can be used to prune the search, or to impose a specific order of visiting,
or even to inform @ref{492,,Path.walk()} about directories the caller creates or
renames before it resumes @ref{492,,Path.walk()} again. Modifying `dirnames' when
`top_down' is false has no effect on the behavior of @ref{492,,Path.walk()} since the
directories in `dirnames' have already been generated by the time `dirnames'
is yielded to the caller.

By default, errors from @ref{a4d,,os.scandir()} are ignored.  If the optional
argument `on_error' is specified, it should be a callable; it will be
called with one argument, an @ref{40d,,OSError} instance. The callable can handle the
error to continue the walk or re-raise it to stop the walk. Note that the
filename is available as the @code{filename} attribute of the exception object.

By default, @ref{492,,Path.walk()} does not follow symbolic links, and instead adds them
to the `filenames' list. Set `follow_symlinks' to true to resolve symlinks
and place them in `dirnames' and `filenames' as appropriate for their targets, and
consequently visit directories pointed to by symlinks (where supported).

@cartouche
@quotation Note 
Be aware that setting `follow_symlinks' to true can lead to infinite
recursion if a link points to a parent directory of itself. @ref{492,,Path.walk()}
does not keep track of the directories it has already visited.
@end quotation
@end cartouche

@cartouche
@quotation Note 
@ref{492,,Path.walk()} assumes the directories it walks are not modified during
execution. For example, if a directory from `dirnames' has been replaced
with a symlink and `follow_symlinks' is false, @ref{492,,Path.walk()} will
still try to descend into it. To prevent such behavior, remove directories
from `dirnames' as appropriate.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Unlike @ref{493,,os.walk()}, @ref{492,,Path.walk()} lists symlinks to directories in
`filenames' if `follow_symlinks' is false.
@end quotation
@end cartouche

This example displays the number of bytes used by all files in each directory,
while ignoring @code{__pycache__} directories:

@example
from pathlib import Path
for root, dirs, files in Path("cpython/Lib/concurrent").walk(on_error=print):
  print(
      root,
      "consumes",
      sum((root / file).stat().st_size for file in files),
      "bytes in",
      len(files),
      "non-directory files"
  )
  if '__pycache__' in dirs:
        dirs.remove('__pycache__')
@end example

This next example is a simple implementation of @ref{2f5,,shutil.rmtree()}.
Walking the tree bottom-up is essential as @ref{2746,,rmdir()} doesn't allow
deleting a directory before it is empty:

@example
# Delete everything reachable from the directory "top".
# CAUTION:  This is dangerous! For example, if top == Path('/'),
# it could delete all of your files.
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()
@end example


Ajouté dans la version 3.12.

@end deffn

@node Création de fichiers et de dossiers,Renommage et suppression,Lecture des dossiers,Chemins concrets
@anchor{library/pathlib creating-files-and-directories}@anchor{2747}
@subsubsection Création de fichiers et de dossiers


@geindex touch() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path touch}@anchor{2748}
@deffn {Méthode} Path.touch (mode=0o666, exist_ok=True)

Create a file at this given path.  If `mode' is given, it is combined
with the process's @code{umask} value to determine the file mode and access
flags.  If the file already exists, the function succeeds when `exist_ok'
is true (and its modification time is updated to the current time),
otherwise @ref{1009,,FileExistsError} is raised.


@subsubheading Voir aussi


The @ref{2744,,open()}, @ref{e31,,write_text()} and
@ref{e33,,write_bytes()} methods are often used to create files.

@end deffn

@geindex mkdir() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path mkdir}@anchor{e2e}
@deffn {Méthode} Path.mkdir (mode=0o777, parents=False, exist_ok=False)

Create a new directory at this given path.  If `mode' is given, it is
combined with the process's @code{umask} value to determine the file mode
and access flags.  If the path already exists, @ref{1009,,FileExistsError}
is raised.

Si `parents' est vrai, chaque parent de ce chemin est créé si besoin ; ils sont créés avec les permissions par défaut sans prendre en compte `mode' (reproduisant la commande POSIX @code{mkdir -p}).

Si `parents' est faux (valeur par défaut), un parent manquant lève @ref{eae,,FileNotFoundError}.

Si `exist_ok' est faux (valeur par défaut), @ref{1009,,FileExistsError} est levé si le dossier cible existe déjà.

If `exist_ok' is true, @ref{1009,,FileExistsError} will not be raised unless the given
path already exists in the file system and is not a directory (same
behavior as the POSIX @code{mkdir -p} command).


Modifié dans la version 3.5: ajout du paramètre `exist_ok'.

@end deffn

@geindex symlink_to() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path symlink_to}@anchor{80c}
@deffn {Méthode} Path.symlink_to (target, target_is_directory=False)

Make this path a symbolic link pointing to `target'.

On Windows, a symlink represents either a file or a directory, and does not
morph to the target dynamically.  If the target is present, the type of the
symlink will be created to match. Otherwise, the symlink will be created
as a directory if `target_is_directory' is true or a file symlink (the
default) otherwise.  On non-Windows platforms, `target_is_directory' is ignored.

@example
>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
>>> p.stat().st_size
956
>>> p.lstat().st_size
8
@end example

@cartouche
@quotation Note 
L'ordre des arguments (lien, cible) est l'opposé de ceux de @ref{10d5,,os.symlink()}.
@end quotation
@end cartouche


Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} if @ref{10d5,,os.symlink()} is not
available. In previous versions, @ref{225,,NotImplementedError} was raised.

@end deffn

@geindex hardlink_to() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path hardlink_to}@anchor{80b}
@deffn {Méthode} Path.hardlink_to (target)

Crée un lien physique pointant sur le même fichier que `target'.

@cartouche
@quotation Note 
L'ordre des arguments (lien, cible) est l'opposé de celui de @ref{10d0,,os.link()}.
@end quotation
@end cartouche


Ajouté dans la version 3.10.



Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} if @ref{10d0,,os.link()} is not
available. In previous versions, @ref{225,,NotImplementedError} was raised.

@end deffn

@node Renommage et suppression,Permissions et propriété,Création de fichiers et de dossiers,Chemins concrets
@anchor{library/pathlib renaming-and-deleting}@anchor{2749}
@subsubsection Renommage et suppression


@geindex rename() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path rename}@anchor{274a}
@deffn {Méthode} Path.rename (target)

Rename this file or directory to the given `target', and return a new
@code{Path} instance pointing to `target'.  On Unix, if `target' exists
and is a file, it will be replaced silently if the user has permission.
On Windows, if `target' exists, @ref{1009,,FileExistsError} will be raised.
`target' can be either a string or another path object:

@example
>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'
@end example

The target path may be absolute or relative. Relative paths are interpreted
relative to the current working directory, `not' the directory of the
@code{Path} object.

Cette méthode est implémentée d'après @ref{10d2,,os.rename()} et fournit les mêmes garanties.


Modifié dans la version 3.8: Added return value, return the new @code{Path} instance.

@end deffn

@geindex replace() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path replace}@anchor{274b}
@deffn {Méthode} Path.replace (target)

Rename this file or directory to the given `target', and return a new
@code{Path} instance pointing to `target'.  If `target' points to an
existing file or empty directory, it will be unconditionally replaced.

The target path may be absolute or relative. Relative paths are interpreted
relative to the current working directory, `not' the directory of the
@code{Path} object.


Modifié dans la version 3.8: Added return value, return the new @code{Path} instance.

@end deffn

@geindex unlink() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path unlink}@anchor{1980}
@deffn {Méthode} Path.unlink (missing_ok=False)

Supprime ce fichier ou lien symbolique. Si le chemin pointe vers un dossier, utilisez @ref{2746,,Path.rmdir()} à la place.

Si `missing_ok' est faux (valeur par défaut), une @ref{eae,,FileNotFoundError} est levée si le chemin n'existe pas.

Si `missing_ok' est vrai, les exceptions @ref{eae,,FileNotFoundError} sont ignorées (même comportement que la commande POSIX @code{rm -f}).


Modifié dans la version 3.8: Ajout du paramètre `missing_ok'.

@end deffn

@geindex rmdir() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path rmdir}@anchor{2746}
@deffn {Méthode} Path.rmdir ()

Supprime ce dossier. Le dossier doit être vide.
@end deffn

@node Permissions et propriété,,Renommage et suppression,Chemins concrets
@anchor{library/pathlib permissions-and-ownership}@anchor{274c}
@subsubsection Permissions et propriété


@geindex owner() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path owner}@anchor{22e}
@deffn {Méthode} Path.owner (*, follow_symlinks=True)

Return the name of the user owning the file. @ref{33a,,KeyError} is raised
if the file's user identifier (UID) isn't found in the system database.

This method normally follows symlinks; to get the owner of the symlink, add
the argument @code{follow_symlinks=False}.


Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} if the @ref{b1,,pwd} module is not
available. In earlier versions, @ref{225,,NotImplementedError} was raised.



Modifié dans la version 3.13: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex group() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path group}@anchor{22f}
@deffn {Méthode} Path.group (*, follow_symlinks=True)

Return the name of the group owning the file. @ref{33a,,KeyError} is raised
if the file's group identifier (GID) isn't found in the system database.

This method normally follows symlinks; to get the group of the symlink, add
the argument @code{follow_symlinks=False}.


Modifié dans la version 3.13: Raises @ref{224,,UnsupportedOperation} if the @ref{65,,grp} module is not
available. In earlier versions, @ref{225,,NotImplementedError} was raised.



Modifié dans la version 3.13: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex chmod() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path chmod}@anchor{80e}
@deffn {Méthode} Path.chmod (mode, *, follow_symlinks=True)

Change le mode et les permissions du fichier, comme @ref{218,,os.chmod()}.

Cette méthode suit normalement les liens symboliques. Certaines versions d’Unix prennent en charge la modification des permissions sur le lien symbolique lui-même ; sur ces plateformes, vous pouvez ajouter l’argument @code{follow_symlinks=False}, ou utiliser @ref{274d,,lchmod()}.

@example
>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060
@end example


Modifié dans la version 3.10: ajout du paramètre `follow_symlinks'.

@end deffn

@geindex lchmod() (méthode pathlib.Path)
@anchor{library/pathlib pathlib Path lchmod}@anchor{274d}
@deffn {Méthode} Path.lchmod (mode)

Comme @ref{80e,,Path.chmod()}, mais, si le chemin pointe vers un lien symbolique, le mode du lien symbolique est changé plutôt que celui de sa cible.
@end deffn

@node Pattern language,Comparaison avec les outils du module glob,Chemins concrets,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib pathlib-pattern-language}@anchor{273a}@anchor{library/pathlib pattern-language}@anchor{274e}
@subsubsection Pattern language


The following wildcards are supported in patterns for
@ref{228,,full_match()}, @ref{22a,,glob()} and @ref{22b,,rglob()}:


@table @asis

@item @code{**} (tout le segment)

Matche un nombre quelconque de segments de fichiers ou dossiers, zéro inclus

@item @code{*} (tout le segment)

Correspondance d'un segment de fichier ou de dossier

@item @code{*} (partie du segment)

Matches any number of non-separator characters, including zero.

@item @code{?}

Matches one non-separator character.

@item @code{[seq]}

Correspondance d'un caractère dans `seq'

@item @code{[!seq]}

Matches one character not in `seq'.
@end table

For a literal match, wrap the meta-characters in brackets.
For example, @code{"[?]"} matches the character @code{"?"}.

The "@code{**}" wildcard enables recursive globbing. A few examples:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Motif

@tab

Signification

@item

"@code{**/*}"

@tab

N'importe quel chemin avec au moins un segment

@item

"@code{**/*.py}"

@tab

Any path with a final segment ending "@code{.py}".

@item

"@code{assets/**}"

@tab

Any path starting with "@code{assets/}".

@item

"@code{assets/**/*}"

@tab

Any path starting with "@code{assets/}", excluding "@code{assets/}" itself.

@end multitable


@cartouche
@quotation Note 
Globbing with the "@code{**}" wildcard visits every directory in the tree.
Large directory trees may take a long time to search.
@end quotation
@end cartouche


Modifié dans la version 3.13: Globbing with a pattern that ends with "@code{**}" returns both files and
directories. In previous versions, only directories were returned.


In @ref{22a,,Path.glob()} and @ref{22b,,rglob()}, a trailing slash may be added to
the pattern to match only directories.


Modifié dans la version 3.11: Globbing with a pattern that ends with a pathname components separator
(@ref{655,,sep} or @ref{656,,altsep}) returns only directories.


@node Comparaison avec les outils du module glob,Comparaison aux modules os et os path,Pattern language,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib comparison-to-the-glob-module}@anchor{274f}
@subsubsection Comparaison avec les outils du module @code{glob}


The patterns accepted and results generated by @ref{22a,,Path.glob()} and
@ref{22b,,Path.rglob()} differ slightly from those by the @ref{63,,glob} module:


@enumerate 

@item 
Files beginning with a dot are not special in pathlib. This is
like passing @code{include_hidden=True} to @ref{29c,,glob.glob()}.

@item 
"@code{**}" pattern components are always recursive in pathlib. This is like
passing @code{recursive=True} to @ref{29c,,glob.glob()}.

@item 
"@code{**}" pattern components do not follow symlinks by default in pathlib.
This behaviour has no equivalent in @ref{29c,,glob.glob()}, but you can pass
@code{recurse_symlinks=True} to @ref{22a,,Path.glob()} for compatible behaviour.

@item 
Like all @ref{490,,PurePath} and @ref{226,,Path} objects, the values returned
from @ref{22a,,Path.glob()} and @ref{22b,,Path.rglob()} don't include trailing
slashes.

@item 
The values returned from pathlib's @code{path.glob()} and @code{path.rglob()}
include the `path' as a prefix, unlike the results of
@code{glob.glob(root_dir=path)}.

@item 
The values returned from pathlib's @code{path.glob()} and @code{path.rglob()}
may include `path' itself, for example when globbing "@code{**}", whereas the
results of @code{glob.glob(root_dir=path)} never include an empty string that
would correspond to `path'.
@end enumerate

@node Comparaison aux modules os et os path,,Comparaison avec les outils du module glob,pathlib — Chemins de système de fichiers orientés objet
@anchor{library/pathlib comparison-to-the-os-and-os-path-modules}@anchor{2750}
@subsubsection Comparaison  aux modules @code{os} et @code{os.path}


pathlib implements path operations using @ref{490,,PurePath} and @ref{226,,Path}
objects, and so it's said to be `object-oriented'. On the other hand, the
@ref{a0,,os} and @ref{a1,,os.path} modules supply functions that work with low-level
@code{str} and @code{bytes} objects, which is a more `procedural' approach. Some
users consider the object-oriented style to be more readable.

Many functions in @ref{a0,,os} and @ref{a1,,os.path} support @code{bytes} paths and
@ref{10cb,,paths relative to directory descriptors}. These features aren't
available in pathlib.

Python's @code{str} and @code{bytes} types, and portions of the @ref{a0,,os} and
@ref{a1,,os.path} modules, are written in C and are very speedy. pathlib is
written in pure Python and is often slower, but rarely slow enough to matter.

pathlib's path normalization is slightly more opinionated and consistent than
@ref{a1,,os.path}. For example, whereas @ref{12f9,,os.path.abspath()} eliminates
"@code{..}" segments from a path, which may change its meaning if symlinks are
involved, @ref{1637,,Path.absolute()} preserves these segments for greater safety.

pathlib's path normalization may render it unsuitable for some applications:


@enumerate 

@item 
pathlib normalizes @code{Path("my_folder/")} to @code{Path("my_folder")}, which
changes a path's meaning when supplied to various operating system APIs and
command-line utilities. Specifically, the absence of a trailing separator
may allow the path to be resolved as either a file or directory, rather
than a directory only.

@item 
pathlib normalizes @code{Path("./my_program")} to @code{Path("my_program")},
which changes a path's meaning when used as an executable search path, such
as in a shell or when spawning a child process. Specifically, the absence
of a separator in the path may force it to be looked up in 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}
rather than the current directory.
@end enumerate

As a consequence of these differences, pathlib is not a drop-in replacement
for @ref{a1,,os.path}.

@menu
* Outils correspondants:: 

@end menu

@node Outils correspondants,,,Comparaison aux modules os et os path
@anchor{library/pathlib corresponding-tools}@anchor{2751}
@subsubsection Outils correspondants


Ci-dessous se trouve un tableau associant diverses fonctions @ref{a0,,os} à leur équivalent @ref{490,,PurePath} / @ref{226,,Path} correspondant.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@ref{a0,,os} et @ref{a1,,os.path}

@tab

@ref{a3,,pathlib}

@item

@ref{2752,,os.path.dirname()}

@tab

@ref{16b7,,PurePath.parent}

@item

@ref{2753,,os.path.basename()}

@tab

@ref{2734,,PurePath.name}

@item

@ref{2754,,os.path.splitext()}

@tab

@ref{2737,,PurePath.stem}, @ref{2735,,PurePath.suffix}

@item

@ref{15bc,,os.path.join()}

@tab

@ref{2739,,PurePath.joinpath()}

@item

@ref{221,,os.path.isabs()}

@tab

@ref{16b6,,PurePath.is_absolute()}

@item

@ref{494,,os.path.relpath()}

@tab

@ref{2c8,,PurePath.relative_to()} @footnote{
@ref{494,,os.path.relpath()} calls @ref{12f9,,abspath()} to make paths
absolute and remove "@code{..}" parts, whereas @ref{2c8,,PurePath.relative_to()}
is a lexical operation that raises @ref{1ff,,ValueError} when its inputs'
anchors differ (e.g. if one path is absolute and the other relative.)
}

@item

@ref{a02,,os.path.expanduser()}

@tab

@ref{e2f,,Path.expanduser()} @footnote{
@ref{a02,,os.path.expanduser()} returns the path unchanged if the home
directory can't be resolved, whereas @ref{e2f,,Path.expanduser()} raises
@ref{193,,RuntimeError}.
}

@item

@ref{222,,os.path.realpath()}

@tab

@ref{1685,,Path.resolve()}

@item

@ref{12f9,,os.path.abspath()}

@tab

@ref{1637,,Path.absolute()} @footnote{
@ref{12f9,,os.path.abspath()} removes "@code{..}" components without resolving
symlinks, which may change the meaning of the path, whereas
@ref{1637,,Path.absolute()} leaves any "@code{..}" components in the path.
}

@item

@ref{9fc,,os.path.exists()}

@tab

@ref{a04,,Path.exists()}

@item

@ref{9ff,,os.path.isfile()}

@tab

@ref{22c,,Path.is_file()}

@item

@ref{9fe,,os.path.isdir()}

@tab

@ref{22d,,Path.is_dir()}

@item

@ref{9fa,,os.path.islink()}

@tab

@ref{a06,,Path.is_symlink()}

@item

@ref{48d,,os.path.isjunction()}

@tab

@ref{495,,Path.is_junction()}

@item

@ref{a00,,os.path.ismount()}

@tab

@ref{a05,,Path.is_mount()}

@item

@ref{f5c,,os.path.samefile()}

@tab

@ref{e2d,,Path.samefile()}

@item

@ref{1521,,os.getcwd()}

@tab

@ref{16b5,,Path.cwd()}

@item

@ref{48a,,os.stat()}

@tab

@ref{80d,,Path.stat()}

@item

@ref{48b,,os.lstat()}

@tab

@ref{2742,,Path.lstat()}

@item

@ref{10da,,os.listdir()}

@tab

@ref{15ba,,Path.iterdir()}

@item

@ref{493,,os.walk()}

@tab

@ref{492,,Path.walk()} @footnote{
@ref{493,,os.walk()} always follows symlinks when categorizing paths into
`dirnames' and `filenames', whereas @ref{492,,Path.walk()} categorizes all
symlinks into `filenames' when `follow_symlinks' is false (the default.)
}

@item

@ref{21a,,os.mkdir()}, @ref{21b,,os.makedirs()}

@tab

@ref{e2e,,Path.mkdir()}

@item

@ref{10d0,,os.link()}

@tab

@ref{80b,,Path.hardlink_to()}

@item

@ref{10d5,,os.symlink()}

@tab

@ref{80c,,Path.symlink_to()}

@item

@ref{90d,,os.readlink()}

@tab

@ref{90c,,Path.readlink()}

@item

@ref{10d2,,os.rename()}

@tab

@ref{274a,,Path.rename()}

@item

@ref{10d3,,os.replace()}

@tab

@ref{274b,,Path.replace()}

@item

@ref{10d1,,os.remove()}, @ref{10d6,,os.unlink()}

@tab

@ref{1980,,Path.unlink()}

@item

@ref{10d4,,os.rmdir()}

@tab

@ref{2746,,Path.rmdir()}

@item

@ref{218,,os.chmod()}

@tab

@ref{80e,,Path.chmod()}

@item

@ref{217,,os.lchmod()}

@tab

@ref{274d,,Path.lchmod()}

@end multitable


@subsubheading Notes


@node os path --- Common pathname manipulations,stat --- Interpreting stat results,pathlib — Chemins de système de fichiers orientés objet,Accès aux Fichiers et aux Dossiers
@anchor{library/os path doc}@anchor{2755}@anchor{library/os path module-os path}@anchor{a1}@anchor{library/os path os-path-common-pathname-manipulations}@anchor{2756}
@subsection @code{os.path} --- Common pathname manipulations


@geindex module; os.path

`Source code:' Lib/genericpath.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/genericpath.py}, Lib/posixpath.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/posixpath.py} (for POSIX) and
Lib/ntpath.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/ntpath.py} (for Windows).

@geindex path;operations


__________________________________________________________________


This module implements some useful functions on pathnames. To read or write
files see @ref{505,,open()}, and for accessing the filesystem see the @ref{a0,,os}
module. The path parameters can be passed as strings, or bytes, or any object
implementing the @ref{c3f,,os.PathLike} protocol.

Unlike a Unix shell, Python does not do any `automatic' path expansions.
Functions such as @ref{a02,,expanduser()} and @ref{1390,,expandvars()} can be invoked
explicitly when an application desires shell-like path expansion.  (See also
the @ref{63,,glob} module.)


@subsubheading Voir aussi


Le module @ref{a3,,pathlib} offre une représentation objet de haut niveau des chemins.


@cartouche
@quotation Note 
Toutes ces fonctions n'acceptent que des chaînes d'octets ou des chaînes de caractères en tant que paramètres. Le résultat est un objet du même type si un chemin ou un nom de fichier est renvoyé.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Comme les différents systèmes d'exploitation ont des conventions de noms de chemins différentes, il existe plusieurs versions de ce module dans la bibliothèque standard. Le module @ref{a1,,os.path} est toujours le module de chemin adapté au système d'exploitation sur lequel Python tourne, et donc adapté pour les chemins locaux. Cependant, vous pouvez également importer et utiliser les modules individuels si vous voulez manipuler un chemin qui est `toujours' dans l'un des différents formats. Ils ont tous la même interface :


@itemize *

@item 
@code{posixpath} pour les chemins de type UNIX

@item 
@code{ntpath} pour les chemins Windows
@end itemize
@end quotation
@end cartouche


Modifié dans la version 3.8: @ref{9fc,,exists()}, @ref{9fd,,lexists()}, @ref{9fe,,isdir()}, @ref{9ff,,isfile()},
@ref{9fa,,islink()}, and @ref{a00,,ismount()} now return @code{False} instead of
raising an exception for paths that contain characters or bytes
unrepresentable at the OS level.


@geindex abspath() (dans le module os.path)
@anchor{library/os path os path abspath}@anchor{12f9}
@deffn {Fonction} os.path.abspath (path)

Renvoie une version absolue et normalisée du chemin d'accès `path'. Sur la plupart des plates-formes, cela équivaut à appeler la fonction @ref{12f8,,normpath()} comme suit : @code{normpath(join(os.getcwd(), chemin))}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex basename() (dans le module os.path)
@anchor{library/os path os path basename}@anchor{2753}
@deffn {Fonction} os.path.basename (path)

Renvoie le nom de base du chemin d'accès `path'.  C'est le second élément de la paire renvoyée en passant `path' à la fonction @ref{2757,,split()}. Notez que le résultat de cette fonction est différent de celui du programme Unix @code{basename} ; là où @code{basename} pour @code{'/foo/bar/'} renvoie @code{'bar'}, la fonction @ref{2753,,basename()} renvoie une chaîne vide (@code{'@w{'}}).


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex commonpath() (dans le module os.path)
@anchor{library/os path os path commonpath}@anchor{e2a}
@deffn {Fonction} os.path.commonpath (paths)

Return the longest common sub-path of each pathname in the iterable
`paths'.  Raise @ref{1ff,,ValueError} if `paths' contain both absolute
and relative pathnames, if `paths' are on different drives, or
if `paths' is empty.  Unlike @ref{e2b,,commonprefix()}, this returns a
valid path.


Ajouté dans la version 3.5.



Modifié dans la version 3.6: Accepts a sequence of @ref{29d,,path-like objects}.



Modifié dans la version 3.13: Any iterable can now be passed, rather than just sequences.

@end deffn

@geindex commonprefix() (dans le module os.path)
@anchor{library/os path os path commonprefix}@anchor{e2b}
@deffn {Fonction} os.path.commonprefix (list)

Return the longest path prefix (taken character-by-character) that is a
prefix of all paths in  `list'.  If `list' is empty, return the empty string
(@code{'@w{'}}).

@cartouche
@quotation Note 
This function may return invalid paths because it works a
character at a time.  To obtain a valid path, see
@ref{e2a,,commonpath()}.

@example
>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'
@end example
@end quotation
@end cartouche


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex dirname() (dans le module os.path)
@anchor{library/os path os path dirname}@anchor{2752}
@deffn {Fonction} os.path.dirname (path)

Return the directory name of pathname `path'.  This is the first element of
the pair returned by passing `path' to the function @ref{2757,,split()}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex exists() (dans le module os.path)
@anchor{library/os path os path exists}@anchor{9fc}
@deffn {Fonction} os.path.exists (path)

Return @code{True} if `path' refers to an existing path or an open
file descriptor.  Returns @code{False} for broken symbolic links.  On
some platforms, this function may return @code{False} if permission is
not granted to execute @ref{48a,,os.stat()} on the requested file, even
if the `path' physically exists.


Modifié dans la version 3.3: `path' can now be an integer: @code{True} is returned if it is an
 open file descriptor, @code{False} otherwise.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex lexists() (dans le module os.path)
@anchor{library/os path os path lexists}@anchor{9fd}
@deffn {Fonction} os.path.lexists (path)

Return @code{True} if `path' refers to an existing path, including
broken symbolic links.   Equivalent to @ref{9fc,,exists()} on platforms lacking
@ref{48b,,os.lstat()}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex ~ (tilde);home directory expansion

@geindex expanduser() (dans le module os.path)
@anchor{library/os path os path expanduser}@anchor{a02}
@deffn {Fonction} os.path.expanduser (path)

On Unix and Windows, return the argument with an initial component of @code{~} or
@code{~user} replaced by that `user''s home directory.

@geindex module;pwd

On Unix, an initial @code{~} is replaced by the environment variable 
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME}
if it is set; otherwise the current user's home directory is looked up in the
password directory through the built-in module @ref{b1,,pwd}. An initial @code{~user}
is looked up directly in the password directory.

On Windows, 
@geindex USERPROFILE
@geindex variable d'environnement; USERPROFILE
@code{USERPROFILE} will be used if set, otherwise a combination
of 
@geindex HOMEPATH
@geindex variable d'environnement; HOMEPATH
@code{HOMEPATH} and 
@geindex HOMEDRIVE
@geindex variable d'environnement; HOMEDRIVE
@code{HOMEDRIVE} will be used.  An initial
@code{~user} is handled by checking that the last directory component of the current
user's home directory matches 
@geindex USERNAME
@geindex variable d'environnement; USERNAME
@code{USERNAME}, and replacing it if so.

If the expansion fails or if the path does not begin with a tilde, the path is
returned unchanged.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.8: No longer uses 
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME} on Windows.

@end deffn

@geindex $ (dollar);environment variables expansion
@geindex % (percent);environment variables expansion (Windows)

@geindex expandvars() (dans le module os.path)
@anchor{library/os path os path expandvars}@anchor{1390}
@deffn {Fonction} os.path.expandvars (path)

Return the argument with environment variables expanded.  Substrings of the form
@code{$name} or @code{$@{name@}} are replaced by the value of environment variable
`name'.  Malformed variable names and references to non-existing variables are
left unchanged.

On Windows, @code{%name%} expansions are supported in addition to @code{$name} and
@code{$@{name@}}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex getatime() (dans le module os.path)
@anchor{library/os path os path getatime}@anchor{2758}
@deffn {Fonction} os.path.getatime (path)

Return the time of last access of `path'.  The return value is a floating-point number giving
the number of seconds since the epoch (see the  @ref{ed,,time} module).  Raise
@ref{40d,,OSError} if the file does not exist or is inaccessible.
@end deffn

@geindex getmtime() (dans le module os.path)
@anchor{library/os path os path getmtime}@anchor{2759}
@deffn {Fonction} os.path.getmtime (path)

Return the time of last modification of `path'.  The return value is a floating-point number
giving the number of seconds since the epoch (see the  @ref{ed,,time} module).
Raise @ref{40d,,OSError} if the file does not exist or is inaccessible.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex getctime() (dans le module os.path)
@anchor{library/os path os path getctime}@anchor{275a}
@deffn {Fonction} os.path.getctime (path)

Return the system's ctime which, on some systems (like Unix) is the time of the
last metadata change, and, on others (like Windows), is the creation time for `path'.
The return value is a number giving the number of seconds since the epoch (see
the  @ref{ed,,time} module).  Raise @ref{40d,,OSError} if the file does not exist or
is inaccessible.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex getsize() (dans le module os.path)
@anchor{library/os path os path getsize}@anchor{275b}
@deffn {Fonction} os.path.getsize (path)

Return the size, in bytes, of `path'.  Raise @ref{40d,,OSError} if the file does
not exist or is inaccessible.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex isabs() (dans le module os.path)
@anchor{library/os path os path isabs}@anchor{221}
@deffn {Fonction} os.path.isabs (path)

Return @code{True} if `path' is an absolute pathname.  On Unix, that means it
begins with a slash, on Windows that it begins with two (back)slashes, or a
drive letter, colon, and (back)slash together.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.13: On Windows, returns @code{False} if the given path starts with exactly one
(back)slash.

@end deffn

@geindex isfile() (dans le module os.path)
@anchor{library/os path os path isfile}@anchor{9ff}
@deffn {Fonction} os.path.isfile (path)

Return @code{True} if `path' is an @ref{9fc,,existing} regular file.
This follows symbolic links, so both @ref{9fa,,islink()} and @ref{9ff,,isfile()} can
be true for the same path.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex isdir() (dans le module os.path)
@anchor{library/os path os path isdir}@anchor{9fe}
@deffn {Fonction} os.path.isdir (path)

Return @code{True} if `path' is an @ref{9fc,,existing} directory.  This
follows symbolic links, so both @ref{9fa,,islink()} and @ref{9fe,,isdir()} can be true
for the same path.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex isjunction() (dans le module os.path)
@anchor{library/os path os path isjunction}@anchor{48d}
@deffn {Fonction} os.path.isjunction (path)

Return @code{True} if `path' refers to an @ref{9fd,,existing} directory
entry that is a junction.  Always return @code{False} if junctions are not
supported on the current platform.


Ajouté dans la version 3.12.

@end deffn

@geindex islink() (dans le module os.path)
@anchor{library/os path os path islink}@anchor{9fa}
@deffn {Fonction} os.path.islink (path)

Return @code{True} if `path' refers to an @ref{9fc,,existing} directory
entry that is a symbolic link.  Always @code{False} if symbolic links are not
supported by the Python runtime.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex ismount() (dans le module os.path)
@anchor{library/os path os path ismount}@anchor{a00}
@deffn {Fonction} os.path.ismount (path)

Return @code{True} if pathname `path' is a `mount point': a point in a
file system where a different file system has been mounted.  On POSIX, the
function checks whether `path''s parent, @code{`path'/..}, is on a different
device than `path', or whether @code{`path'/..} and `path' point to the same
i-node on the same device --- this should detect mount points for all Unix
and POSIX variants.  It is not able to reliably detect bind mounts on the
same filesystem.  On Windows, a drive letter root and a share UNC are
always mount points, and for any other path @code{GetVolumePathName} is called
to see if it is different from the input path.


Modifié dans la version 3.4: Added support for detecting non-root mount points on Windows.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex isdevdrive() (dans le module os.path)
@anchor{library/os path os path isdevdrive}@anchor{15d1}
@deffn {Fonction} os.path.isdevdrive (path)

Return @code{True} if pathname `path' is located on a Windows Dev Drive.
A Dev Drive is optimized for developer scenarios, and offers faster
performance for reading and writing files. It is recommended for use for
source code, temporary build directories, package caches, and other
IO-intensive operations.

May raise an error for an invalid path, for example, one without a
recognizable drive, but returns @code{False} on platforms that do not support
Dev Drives. See the Windows documentation@footnote{https://learn.microsoft.com/windows/dev-drive/}
for information on enabling and creating Dev Drives.


Ajouté dans la version 3.12.



Modifié dans la version 3.13: The function is now available on all platforms, and will always return @code{False} on those that have no support for Dev Drives

@end deffn

@geindex isreserved() (dans le module os.path)
@anchor{library/os path os path isreserved}@anchor{220}
@deffn {Fonction} os.path.isreserved (path)

Return @code{True} if `path' is a reserved pathname on the current system.

On Windows, reserved filenames include those that end with a space or dot;
those that contain colons (i.e. file streams such as "name:stream"),
wildcard characters (i.e. @code{'*?"<>'}), pipe, or ASCII control characters;
as well as DOS device names such as "NUL", "CON", "CONIN$", "CONOUT$",
"AUX", "PRN", "COM1", and "LPT1".

@cartouche
@quotation Note 
This function approximates rules for reserved paths on most Windows
systems. These rules change over time in various Windows releases.
This function may be updated in future Python releases as changes to
the rules become broadly available.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.13.

@end deffn

@geindex join() (dans le module os.path)
@anchor{library/os path os path join}@anchor{15bc}
@deffn {Fonction} os.path.join (path, *paths)

Join one or more path segments intelligently.  The return value is the
concatenation of `path' and all members of `*paths', with exactly one
directory separator following each non-empty part, except the last. That is,
the result will only end in a separator if the last part is either empty or
ends in a separator. If a segment is an absolute path (which on Windows
requires both a drive and a root), then all previous segments are ignored and
joining continues from the absolute path segment.

On Windows, the drive is not reset when a rooted path segment (e.g.,
@code{r'\foo'}) is encountered. If a segment is on a different drive or is an
absolute path, all previous segments are ignored and the drive is reset. Note
that since there is a current directory for each drive,
@code{os.path.join("c:", "foo")} represents a path relative to the current
directory on drive @code{C:} (@code{c:foo}), not @code{c:\foo}.


Modifié dans la version 3.6: Accepts a @ref{29d,,path-like object} for `path' and `paths'.

@end deffn

@geindex normcase() (dans le module os.path)
@anchor{library/os path os path normcase}@anchor{275c}
@deffn {Fonction} os.path.normcase (path)

Normalize the case of a pathname.  On Windows, convert all characters in the
pathname to lowercase, and also convert forward slashes to backward slashes.
On other operating systems, return the path unchanged.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex normpath() (dans le module os.path)
@anchor{library/os path os path normpath}@anchor{12f8}
@deffn {Fonction} os.path.normpath (path)

Normalize a pathname by collapsing redundant separators and up-level
references so that @code{A//B}, @code{A/B/}, @code{A/./B} and @code{A/foo/../B} all
become @code{A/B}.  This string manipulation may change the meaning of a path
that contains symbolic links.  On Windows, it converts forward slashes to
backward slashes. To normalize case, use @ref{275c,,normcase()}.

@cartouche
@quotation Note 
On POSIX systems, in accordance with IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution@footnote{https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13},
if a pathname begins with exactly two slashes, the first component
following the leading characters may be interpreted in an implementation-defined
manner, although more than two leading characters shall be treated as a
single character.
@end quotation
@end cartouche


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex realpath() (dans le module os.path)
@anchor{library/os path os path realpath}@anchor{222}
@deffn {Fonction} os.path.realpath (path, *, strict=False)

Return the canonical path of the specified filename, eliminating any symbolic
links encountered in the path (if they are supported by the operating
system). On Windows, this function will also resolve MS-DOS (also called 8.3)
style names such as @code{C:\\PROGRA~1} to @code{C:\\Program Files}.

If a path doesn't exist or a symlink loop is encountered, and `strict' is
@code{True}, @ref{40d,,OSError} is raised. If `strict' is @code{False} these errors
are ignored, and so the result might be missing or otherwise inaccessible.

@cartouche
@quotation Note 
This function emulates the operating system's procedure for making a path
canonical, which differs slightly between Windows and UNIX with respect
to how links and subsequent path components interact.

Operating system APIs make paths canonical as needed, so it's not
normally necessary to call this function.
@end quotation
@end cartouche


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.8: Symbolic links and junctions are now resolved on Windows.



Modifié dans la version 3.10: The `strict' parameter was added.

@end deffn

@geindex relpath() (dans le module os.path)
@anchor{library/os path os path relpath}@anchor{494}
@deffn {Fonction} os.path.relpath (path, start=os.curdir)

Return a relative filepath to `path' either from the current directory or
from an optional `start' directory.  This is a path computation:  the
filesystem is not accessed to confirm the existence or nature of `path' or
`start'.  On Windows, @ref{1ff,,ValueError} is raised when `path' and `start'
are on different drives.

`start' defaults to @ref{275d,,os.curdir}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex samefile() (dans le module os.path)
@anchor{library/os path os path samefile}@anchor{f5c}
@deffn {Fonction} os.path.samefile (path1, path2)

Return @code{True} if both pathname arguments refer to the same file or directory.
This is determined by the device number and i-node number and raises an
exception if an @ref{48a,,os.stat()} call on either pathname fails.


Modifié dans la version 3.2: Prise en charge de Windows.



Modifié dans la version 3.4: Windows now uses the same implementation as all other platforms.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex sameopenfile() (dans le module os.path)
@anchor{library/os path os path sameopenfile}@anchor{275e}
@deffn {Fonction} os.path.sameopenfile (fp1, fp2)

Return @code{True} if the file descriptors `fp1' and `fp2' refer to the same file.


Modifié dans la version 3.2: Prise en charge de Windows.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex samestat() (dans le module os.path)
@anchor{library/os path os path samestat}@anchor{f5b}
@deffn {Fonction} os.path.samestat (stat1, stat2)

Return @code{True} if the stat tuples `stat1' and `stat2' refer to the same file.
These structures may have been returned by @ref{d79,,os.fstat()},
@ref{48b,,os.lstat()}, or @ref{48a,,os.stat()}.  This function implements the
underlying comparison used by @ref{f5c,,samefile()} and @ref{275e,,sameopenfile()}.


Modifié dans la version 3.4: Prise en charge de Windows.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex split() (dans le module os.path)
@anchor{library/os path os path split}@anchor{2757}
@deffn {Fonction} os.path.split (path)

Split the pathname `path' into a pair, @code{(head, tail)} where `tail' is the
last pathname component and `head' is everything leading up to that.  The
`tail' part will never contain a slash; if `path' ends in a slash, `tail'
will be empty.  If there is no slash in `path', `head' will be empty.  If
`path' is empty, both `head' and `tail' are empty.  Trailing slashes are
stripped from `head' unless it is the root (one or more slashes only).  In
all cases, @code{join(head, tail)} returns a path to the same location as `path'
(but the strings may differ).  Also see the functions @ref{2752,,dirname()} and
@ref{2753,,basename()}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex splitdrive() (dans le module os.path)
@anchor{library/os path os path splitdrive}@anchor{be2}
@deffn {Fonction} os.path.splitdrive (path)

Split the pathname `path' into a pair @code{(drive, tail)} where `drive' is either
a mount point or the empty string.  On systems which do not use drive
specifications, `drive' will always be the empty string.  In all cases, @code{drive
+ tail} will be the same as `path'.

On Windows, splits a pathname into drive/UNC sharepoint and relative path.

If the path contains a drive letter, drive will contain everything
up to and including the colon:

@example
>>> splitdrive("c:/dir")
("c:", "/dir")
@end example

If the path contains a UNC path, drive will contain the host name
and share:

@example
>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")
@end example


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex splitroot() (dans le module os.path)
@anchor{library/os path os path splitroot}@anchor{48e}
@deffn {Fonction} os.path.splitroot (path)

Split the pathname `path' into a 3-item tuple @code{(drive, root, tail)} where
`drive' is a device name or mount point, `root' is a string of separators
after the drive, and `tail' is everything after the root. Any of these
items may be the empty string. In all cases, @code{drive + root + tail} will
be the same as `path'.

On POSIX systems, `drive' is always empty. The `root' may be empty (if `path' is
relative), a single forward slash (if `path' is absolute), or two forward slashes
(implementation-defined per IEEE Std 1003.1-2017; 4.13 Pathname Resolution@footnote{https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13}.)
For example:

@example
>>> splitroot('/home/sam')
('@w{'}, '/', 'home/sam')
>>> splitroot('//home/sam')
('@w{'}, '//', 'home/sam')
>>> splitroot('///home/sam')
('@w{'}, '/', '//home/sam')
@end example

On Windows, `drive' may be empty, a drive-letter name, a UNC share, or a device
name. The `root' may be empty, a forward slash, or a backward slash. For
example:

@example
>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')
@end example


Ajouté dans la version 3.12.

@end deffn

@geindex splitext() (dans le module os.path)
@anchor{library/os path os path splitext}@anchor{2754}
@deffn {Fonction} os.path.splitext (path)

Split the pathname `path' into a pair @code{(root, ext)}  such that @code{root + ext ==
path}, and the extension, `ext', is empty or begins with a period and contains at
most one period.

If the path contains no extension, `ext' will be @code{'@w{'}}:

@example
>>> splitext('bar')
('bar', '@w{'})
@end example

If the path contains an extension, then `ext' will be set to this extension,
including the leading period. Note that previous periods will be ignored:

@example
>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')
@end example

Leading periods of the last component of the path are considered to
be part of the root:

@example
>>> splitext('.cshrc')
('.cshrc', '@w{'})
>>> splitext('/foo/....jpg')
('/foo/....jpg', '@w{'})
@end example


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex supports_unicode_filenames (dans le module os.path)
@anchor{library/os path os path supports_unicode_filenames}@anchor{1440}
@deffn {Données} os.path.supports_unicode_filenames

@code{True} if arbitrary Unicode strings can be used as file names (within limitations
imposed by the file system).
@end deffn

@node stat --- Interpreting stat results,filecmp --- File and Directory Comparisons,os path --- Common pathname manipulations,Accès aux Fichiers et aux Dossiers
@anchor{library/stat doc}@anchor{275f}@anchor{library/stat module-stat}@anchor{d0}@anchor{library/stat stat-interpreting-stat-results}@anchor{2760}
@subsection @code{stat} --- Interpreting @code{stat()} results


@geindex module; stat

`Code source :' Lib/stat.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/stat.py}


__________________________________________________________________


The @ref{d0,,stat} module defines constants and functions for interpreting the
results of @ref{48a,,os.stat()}, @ref{d79,,os.fstat()} and @ref{48b,,os.lstat()} (if they
exist).  For complete details about the @code{stat()}, @code{fstat()} and
@code{lstat()} calls, consult the documentation for your system.


Modifié dans la version 3.4: Le module `stat' est implémenté en C.


Le module @ref{d0,,stat} définit les fonctions suivantes pour tester des types de fichiers spécifiques :

@geindex S_ISDIR() (dans le module stat)
@anchor{library/stat stat S_ISDIR}@anchor{2761}
@deffn {Fonction} stat.S_ISDIR (mode)

Renvoie une valeur différente de zéro si c'est un mode d'un répertoire.
@end deffn

@geindex S_ISCHR() (dans le module stat)
@anchor{library/stat stat S_ISCHR}@anchor{2762}
@deffn {Fonction} stat.S_ISCHR (mode)

Renvoie une valeur différente de zéro si c'est le mode d'un fichier spécial caractère de périphérique.
@end deffn

@geindex S_ISBLK() (dans le module stat)
@anchor{library/stat stat S_ISBLK}@anchor{2763}
@deffn {Fonction} stat.S_ISBLK (mode)

Renvoie une valeur différente de zéro si c'est le mode d'un fichier spécial bloc.
@end deffn

@geindex S_ISREG() (dans le module stat)
@anchor{library/stat stat S_ISREG}@anchor{2764}
@deffn {Fonction} stat.S_ISREG (mode)

Renvoie une valeur différente de zéro si c'est le mode d'un fichier normal.
@end deffn

@geindex S_ISFIFO() (dans le module stat)
@anchor{library/stat stat S_ISFIFO}@anchor{2765}
@deffn {Fonction} stat.S_ISFIFO (mode)

Renvoie une valeur différente de zéro si c'est le mode d'une FIFO (tube nommé)
@end deffn

@geindex S_ISLNK() (dans le module stat)
@anchor{library/stat stat S_ISLNK}@anchor{2766}
@deffn {Fonction} stat.S_ISLNK (mode)

Renvoie une valeur différente de zéro si c'est le mode d'un lien symbolique.
@end deffn

@geindex S_ISSOCK() (dans le module stat)
@anchor{library/stat stat S_ISSOCK}@anchor{2767}
@deffn {Fonction} stat.S_ISSOCK (mode)

Renvoie une valeur différente de zéro si c'est le mode d'un `socket'.
@end deffn

@geindex S_ISDOOR() (dans le module stat)
@anchor{library/stat stat S_ISDOOR}@anchor{1954}
@deffn {Fonction} stat.S_ISDOOR (mode)

Return non-zero if the mode is from a door.


Ajouté dans la version 3.4.

@end deffn

@geindex S_ISPORT() (dans le module stat)
@anchor{library/stat stat S_ISPORT}@anchor{1955}
@deffn {Fonction} stat.S_ISPORT (mode)

Return non-zero if the mode is from an event port.


Ajouté dans la version 3.4.

@end deffn

@geindex S_ISWHT() (dans le module stat)
@anchor{library/stat stat S_ISWHT}@anchor{1956}
@deffn {Fonction} stat.S_ISWHT (mode)

Return non-zero if the mode is from a whiteout.


Ajouté dans la version 3.4.

@end deffn

Deux autres fonctions sont définies pour permettre plus de manipulation du mode du fichier :

@geindex S_IMODE() (dans le module stat)
@anchor{library/stat stat S_IMODE}@anchor{2768}
@deffn {Fonction} stat.S_IMODE (mode)

Return the portion of the file's mode that can be set by
@ref{218,,os.chmod()}---that is, the file's permission bits, plus the sticky
bit, set-group-id, and set-user-id bits (on systems that support them).
@end deffn

@geindex S_IFMT() (dans le module stat)
@anchor{library/stat stat S_IFMT}@anchor{2769}
@deffn {Fonction} stat.S_IFMT (mode)

Return the portion of the file's mode that describes the file type (used by the
@code{S_IS*()} functions above).
@end deffn

Normally, you would use the @code{os.path.is*()} functions for testing the type
of a file; the functions here are useful when you are doing multiple tests of
the same file and wish to avoid the overhead of the @code{stat()} system call
for each test.  These are also useful when checking for information about a file
that isn't handled by @ref{a1,,os.path}, like the tests for block and character
devices.

Exemple :

@example
import os, sys
from stat import *

def walktree(top, callback):
    '@w{'}'recursively descend the directory tree rooted at top,
       calling the callback function for each regular file'@w{'}'

    for f in os.listdir(top):
        pathname = os.path.join(top, f)
        mode = os.lstat(pathname).st_mode
        if S_ISDIR(mode):
            # It's a directory, recurse into it
            walktree(pathname, callback)
        elif S_ISREG(mode):
            # It's a file, call the callback function
            callback(pathname)
        else:
            # Unknown file type, print a message
            print('Skipping %s' % pathname)

def visitfile(file):
    print('visiting', file)

if __name__ == '__main__':
    walktree(sys.argv[1], visitfile)
@end example

An additional utility function is provided to convert a file's mode in a human
readable string:

@geindex filemode() (dans le module stat)
@anchor{library/stat stat filemode}@anchor{112b}
@deffn {Fonction} stat.filemode (mode)

Convert a file's mode to a string of the form '-rwxrwxrwx'.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: The function supports @ref{fa5,,S_IFDOOR}, @ref{fa6,,S_IFPORT} and
@ref{fa7,,S_IFWHT}.

@end deffn

All the variables below are simply symbolic indexes into the 10-tuple returned
by @ref{48a,,os.stat()}, @ref{d79,,os.fstat()} or @ref{48b,,os.lstat()}.

@geindex ST_MODE (dans le module stat)
@anchor{library/stat stat ST_MODE}@anchor{fa4}
@deffn {Données} stat.ST_MODE

Mode de protection de l'`inode'.
@end deffn

@geindex ST_INO (dans le module stat)
@anchor{library/stat stat ST_INO}@anchor{276a}
@deffn {Données} stat.ST_INO

Numéro d'`inode'.
@end deffn

@geindex ST_DEV (dans le module stat)
@anchor{library/stat stat ST_DEV}@anchor{276b}
@deffn {Données} stat.ST_DEV

Device inode resides on.
@end deffn

@geindex ST_NLINK (dans le module stat)
@anchor{library/stat stat ST_NLINK}@anchor{276c}
@deffn {Données} stat.ST_NLINK

Nombre de liens vers l'`inode'.
@end deffn

@geindex ST_UID (dans le module stat)
@anchor{library/stat stat ST_UID}@anchor{276d}
@deffn {Données} stat.ST_UID

Identifiant utilisateur du propriétaire.
@end deffn

@geindex ST_GID (dans le module stat)
@anchor{library/stat stat ST_GID}@anchor{276e}
@deffn {Données} stat.ST_GID

Identifiant de groupe du propriétaire.
@end deffn

@geindex ST_SIZE (dans le module stat)
@anchor{library/stat stat ST_SIZE}@anchor{276f}
@deffn {Données} stat.ST_SIZE

Size in bytes of a plain file; amount of data waiting on some special files.
@end deffn

@geindex ST_ATIME (dans le module stat)
@anchor{library/stat stat ST_ATIME}@anchor{2770}
@deffn {Données} stat.ST_ATIME

L'heure du dernier accès.
@end deffn

@geindex ST_MTIME (dans le module stat)
@anchor{library/stat stat ST_MTIME}@anchor{2771}
@deffn {Données} stat.ST_MTIME

L'heure de la dernière modification.
@end deffn

@geindex ST_CTIME (dans le module stat)
@anchor{library/stat stat ST_CTIME}@anchor{2772}
@deffn {Données} stat.ST_CTIME

The "ctime" as reported by the operating system.  On some systems (like Unix) is
the time of the last metadata change, and, on others (like Windows), is the
creation time (see platform documentation for details).
@end deffn

The interpretation of "file size" changes according to the file type.  For plain
files this is the size of the file in bytes.  For FIFOs and sockets under most
flavors of Unix (including Linux in particular), the "size" is the number of
bytes waiting to be read at the time of the call to @ref{48a,,os.stat()},
@ref{d79,,os.fstat()}, or @ref{48b,,os.lstat()}; this can sometimes be useful, especially
for polling one of these special files after a non-blocking open.  The meaning
of the size field for other character and block devices varies more, depending
on the implementation of the underlying system call.

The variables below define the flags used in the @ref{fa4,,ST_MODE} field.

Use of the functions above is more portable than use of the first set of flags:

@geindex S_IFSOCK (dans le module stat)
@anchor{library/stat stat S_IFSOCK}@anchor{2773}
@deffn {Données} stat.S_IFSOCK

Socket.
@end deffn

@geindex S_IFLNK (dans le module stat)
@anchor{library/stat stat S_IFLNK}@anchor{2774}
@deffn {Données} stat.S_IFLNK

Lien symbolique.
@end deffn

@geindex S_IFREG (dans le module stat)
@anchor{library/stat stat S_IFREG}@anchor{2775}
@deffn {Données} stat.S_IFREG

Fichier normal.
@end deffn

@geindex S_IFBLK (dans le module stat)
@anchor{library/stat stat S_IFBLK}@anchor{2776}
@deffn {Données} stat.S_IFBLK

Périphérique en mode bloc.
@end deffn

@geindex S_IFDIR (dans le module stat)
@anchor{library/stat stat S_IFDIR}@anchor{2777}
@deffn {Données} stat.S_IFDIR

Dossier.
@end deffn

@geindex S_IFCHR (dans le module stat)
@anchor{library/stat stat S_IFCHR}@anchor{2778}
@deffn {Données} stat.S_IFCHR

Périphérique en mode caractère.
@end deffn

@geindex S_IFIFO (dans le module stat)
@anchor{library/stat stat S_IFIFO}@anchor{2779}
@deffn {Données} stat.S_IFIFO

FIFO.
@end deffn

@geindex S_IFDOOR (dans le module stat)
@anchor{library/stat stat S_IFDOOR}@anchor{fa5}
@deffn {Données} stat.S_IFDOOR

Door.


Ajouté dans la version 3.4.

@end deffn

@geindex S_IFPORT (dans le module stat)
@anchor{library/stat stat S_IFPORT}@anchor{fa6}
@deffn {Données} stat.S_IFPORT

Event port.


Ajouté dans la version 3.4.

@end deffn

@geindex S_IFWHT (dans le module stat)
@anchor{library/stat stat S_IFWHT}@anchor{fa7}
@deffn {Données} stat.S_IFWHT

Whiteout.


Ajouté dans la version 3.4.

@end deffn

@cartouche
@quotation Note 
@ref{fa5,,S_IFDOOR}, @ref{fa6,,S_IFPORT} or @ref{fa7,,S_IFWHT} sont définies à 0 si la plateforme ne prend pas en charge les types de fichiers.
@end quotation
@end cartouche

Les drapeaux suivant peuvent aussi être utilisé dans l'argument `mode' de @ref{218,,os.chmod()} :

@geindex S_ISUID (dans le module stat)
@anchor{library/stat stat S_ISUID}@anchor{277a}
@deffn {Données} stat.S_ISUID

Définit le bit UID.
@end deffn

@geindex S_ISGID (dans le module stat)
@anchor{library/stat stat S_ISGID}@anchor{277b}
@deffn {Données} stat.S_ISGID

Set-group-ID bit.  This bit has several special uses.  For a directory
it indicates that BSD semantics is to be used for that directory:
files created there inherit their group ID from the directory, not
from the effective group ID of the creating process, and directories
created there will also get the @ref{277b,,S_ISGID} bit set.  For a
file that does not have the group execution bit (@ref{277c,,S_IXGRP})
set, the set-group-ID bit indicates mandatory file/record locking
(see also @ref{277d,,S_ENFMT}).
@end deffn

@geindex S_ISVTX (dans le module stat)
@anchor{library/stat stat S_ISVTX}@anchor{277e}
@deffn {Données} stat.S_ISVTX

Sticky bit.  When this bit is set on a directory it means that a file
in that directory can be renamed or deleted only by the owner of the
file, by the owner of the directory, or by a privileged process.
@end deffn

@geindex S_IRWXU (dans le module stat)
@anchor{library/stat stat S_IRWXU}@anchor{277f}
@deffn {Données} stat.S_IRWXU

Mask for file owner permissions.
@end deffn

@geindex S_IRUSR (dans le module stat)
@anchor{library/stat stat S_IRUSR}@anchor{2780}
@deffn {Données} stat.S_IRUSR

Le propriétaire possède le droit de lecture.
@end deffn

@geindex S_IWUSR (dans le module stat)
@anchor{library/stat stat S_IWUSR}@anchor{2781}
@deffn {Données} stat.S_IWUSR

Le propriétaire possède le droit d'écriture.
@end deffn

@geindex S_IXUSR (dans le module stat)
@anchor{library/stat stat S_IXUSR}@anchor{2782}
@deffn {Données} stat.S_IXUSR

Le propriétaire possède le droit d'exécution.
@end deffn

@geindex S_IRWXG (dans le module stat)
@anchor{library/stat stat S_IRWXG}@anchor{2783}
@deffn {Données} stat.S_IRWXG

Masque pour extraire les permissions du groupe.
@end deffn

@geindex S_IRGRP (dans le module stat)
@anchor{library/stat stat S_IRGRP}@anchor{2784}
@deffn {Données} stat.S_IRGRP

Le groupe possède le droit de lecture.
@end deffn

@geindex S_IWGRP (dans le module stat)
@anchor{library/stat stat S_IWGRP}@anchor{2785}
@deffn {Données} stat.S_IWGRP

Le groupe possède le droit d'écriture.
@end deffn

@geindex S_IXGRP (dans le module stat)
@anchor{library/stat stat S_IXGRP}@anchor{277c}
@deffn {Données} stat.S_IXGRP

Le groupe possède le droit d'exécution.
@end deffn

@geindex S_IRWXO (dans le module stat)
@anchor{library/stat stat S_IRWXO}@anchor{2786}
@deffn {Données} stat.S_IRWXO

Mask for permissions for others (not in group).
@end deffn

@geindex S_IROTH (dans le module stat)
@anchor{library/stat stat S_IROTH}@anchor{2787}
@deffn {Données} stat.S_IROTH

Others have read permission.
@end deffn

@geindex S_IWOTH (dans le module stat)
@anchor{library/stat stat S_IWOTH}@anchor{2788}
@deffn {Données} stat.S_IWOTH

Others have write permission.
@end deffn

@geindex S_IXOTH (dans le module stat)
@anchor{library/stat stat S_IXOTH}@anchor{2789}
@deffn {Données} stat.S_IXOTH

Others have execute permission.
@end deffn

@geindex S_ENFMT (dans le module stat)
@anchor{library/stat stat S_ENFMT}@anchor{277d}
@deffn {Données} stat.S_ENFMT

System V file locking enforcement.  This flag is shared with @ref{277b,,S_ISGID}:
file/record locking is enforced on files that do not have the group
execution bit (@ref{277c,,S_IXGRP}) set.
@end deffn

@geindex S_IREAD (dans le module stat)
@anchor{library/stat stat S_IREAD}@anchor{278a}
@deffn {Données} stat.S_IREAD

Unix V7 synonym for @ref{2780,,S_IRUSR}.
@end deffn

@geindex S_IWRITE (dans le module stat)
@anchor{library/stat stat S_IWRITE}@anchor{278b}
@deffn {Données} stat.S_IWRITE

Unix V7 synonym for @ref{2781,,S_IWUSR}.
@end deffn

@geindex S_IEXEC (dans le module stat)
@anchor{library/stat stat S_IEXEC}@anchor{278c}
@deffn {Données} stat.S_IEXEC

Unix V7 synonym for @ref{2782,,S_IXUSR}.
@end deffn

The following flags can be used in the `flags' argument of @ref{10ce,,os.chflags()}:

@geindex UF_SETTABLE (dans le module stat)
@anchor{library/stat stat UF_SETTABLE}@anchor{278d}
@deffn {Données} stat.UF_SETTABLE

All user settable flags.


Ajouté dans la version 3.13.

@end deffn

@geindex UF_NODUMP (dans le module stat)
@anchor{library/stat stat UF_NODUMP}@anchor{278e}
@deffn {Données} stat.UF_NODUMP

Do not dump the file.
@end deffn

@geindex UF_IMMUTABLE (dans le module stat)
@anchor{library/stat stat UF_IMMUTABLE}@anchor{278f}
@deffn {Données} stat.UF_IMMUTABLE

Le fichier ne peut pas être modifié.
@end deffn

@geindex UF_APPEND (dans le module stat)
@anchor{library/stat stat UF_APPEND}@anchor{2790}
@deffn {Données} stat.UF_APPEND

The file may only be appended to.
@end deffn

@geindex UF_OPAQUE (dans le module stat)
@anchor{library/stat stat UF_OPAQUE}@anchor{2791}
@deffn {Données} stat.UF_OPAQUE

The directory is opaque when viewed through a union stack.
@end deffn

@geindex UF_NOUNLINK (dans le module stat)
@anchor{library/stat stat UF_NOUNLINK}@anchor{2792}
@deffn {Données} stat.UF_NOUNLINK

Le fichier ne peut pas être renommé ou supprimé.
@end deffn

@geindex UF_COMPRESSED (dans le module stat)
@anchor{library/stat stat UF_COMPRESSED}@anchor{2793}
@deffn {Données} stat.UF_COMPRESSED

The file is stored compressed (macOS 10.6+).
@end deffn

@geindex UF_TRACKED (dans le module stat)
@anchor{library/stat stat UF_TRACKED}@anchor{2794}
@deffn {Données} stat.UF_TRACKED

Used for handling document IDs (macOS)


Ajouté dans la version 3.13.

@end deffn

@geindex UF_DATAVAULT (dans le module stat)
@anchor{library/stat stat UF_DATAVAULT}@anchor{2795}
@deffn {Données} stat.UF_DATAVAULT

The file needs an entitlement for reading or writing (macOS 10.13+)


Ajouté dans la version 3.13.

@end deffn

@geindex UF_HIDDEN (dans le module stat)
@anchor{library/stat stat UF_HIDDEN}@anchor{2796}
@deffn {Données} stat.UF_HIDDEN

Le fichier ne peut pas être affiché dans une GUI (macOS 10.5+).
@end deffn

@geindex SF_SETTABLE (dans le module stat)
@anchor{library/stat stat SF_SETTABLE}@anchor{2797}
@deffn {Données} stat.SF_SETTABLE

All super-user changeable flags


Ajouté dans la version 3.13.

@end deffn

@geindex SF_SUPPORTED (dans le module stat)
@anchor{library/stat stat SF_SUPPORTED}@anchor{2798}
@deffn {Données} stat.SF_SUPPORTED

All super-user supported flags

@ref{1ce0,,Availability}: macOS


Ajouté dans la version 3.13.

@end deffn

@geindex SF_SYNTHETIC (dans le module stat)
@anchor{library/stat stat SF_SYNTHETIC}@anchor{2799}
@deffn {Données} stat.SF_SYNTHETIC

All super-user read-only synthetic flags

@ref{1ce0,,Availability}: macOS


Ajouté dans la version 3.13.

@end deffn

@geindex SF_ARCHIVED (dans le module stat)
@anchor{library/stat stat SF_ARCHIVED}@anchor{279a}
@deffn {Données} stat.SF_ARCHIVED

Le fichier peut être archivé.
@end deffn

@geindex SF_IMMUTABLE (dans le module stat)
@anchor{library/stat stat SF_IMMUTABLE}@anchor{279b}
@deffn {Données} stat.SF_IMMUTABLE

Le fichier ne peut pas être modifié.
@end deffn

@geindex SF_APPEND (dans le module stat)
@anchor{library/stat stat SF_APPEND}@anchor{279c}
@deffn {Données} stat.SF_APPEND

The file may only be appended to.
@end deffn

@geindex SF_RESTRICTED (dans le module stat)
@anchor{library/stat stat SF_RESTRICTED}@anchor{279d}
@deffn {Données} stat.SF_RESTRICTED

The file needs an entitlement to write to (macOS 10.13+)


Ajouté dans la version 3.13.

@end deffn

@geindex SF_NOUNLINK (dans le module stat)
@anchor{library/stat stat SF_NOUNLINK}@anchor{279e}
@deffn {Données} stat.SF_NOUNLINK

Le fichier ne peut pas être renommé ou supprimé.
@end deffn

@geindex SF_SNAPSHOT (dans le module stat)
@anchor{library/stat stat SF_SNAPSHOT}@anchor{279f}
@deffn {Données} stat.SF_SNAPSHOT

The file is a snapshot file.
@end deffn

@geindex SF_FIRMLINK (dans le module stat)
@anchor{library/stat stat SF_FIRMLINK}@anchor{27a0}
@deffn {Données} stat.SF_FIRMLINK

The file is a firmlink (macOS 10.15+)


Ajouté dans la version 3.13.

@end deffn

@geindex SF_DATALESS (dans le module stat)
@anchor{library/stat stat SF_DATALESS}@anchor{27a1}
@deffn {Données} stat.SF_DATALESS

The file is a dataless object (macOS 10.15+)


Ajouté dans la version 3.13.

@end deffn

See the *BSD or macOS systems man page @code{chflags(2)@footnote{https://manpages.debian.org/chflags(2)}} for more information.

On Windows, the following file attribute constants are available for use when
testing bits in the @code{st_file_attributes} member returned by @ref{48a,,os.stat()}.
See the Windows API documentation@footnote{https://msdn.microsoft.com/en-us/library/windows/desktop/gg258117.aspx}
for more detail on the meaning of these constants.

@geindex FILE_ATTRIBUTE_ARCHIVE (dans le module stat)
@geindex FILE_ATTRIBUTE_COMPRESSED (dans le module stat)
@geindex FILE_ATTRIBUTE_DEVICE (dans le module stat)
@geindex FILE_ATTRIBUTE_DIRECTORY (dans le module stat)
@geindex FILE_ATTRIBUTE_ENCRYPTED (dans le module stat)
@geindex FILE_ATTRIBUTE_HIDDEN (dans le module stat)
@geindex FILE_ATTRIBUTE_INTEGRITY_STREAM (dans le module stat)
@geindex FILE_ATTRIBUTE_NORMAL (dans le module stat)
@geindex FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (dans le module stat)
@geindex FILE_ATTRIBUTE_NO_SCRUB_DATA (dans le module stat)
@geindex FILE_ATTRIBUTE_OFFLINE (dans le module stat)
@geindex FILE_ATTRIBUTE_READONLY (dans le module stat)
@geindex FILE_ATTRIBUTE_REPARSE_POINT (dans le module stat)
@geindex FILE_ATTRIBUTE_SPARSE_FILE (dans le module stat)
@geindex FILE_ATTRIBUTE_SYSTEM (dans le module stat)
@geindex FILE_ATTRIBUTE_TEMPORARY (dans le module stat)
@geindex FILE_ATTRIBUTE_VIRTUAL (dans le module stat)
@anchor{library/stat stat FILE_ATTRIBUTE_ARCHIVE}@anchor{27a2}
@deffn {Données} stat.FILE_ATTRIBUTE_ARCHIVE
@anchor{library/stat stat FILE_ATTRIBUTE_COMPRESSED}@anchor{27a3}
@deffnx {Données} stat.FILE_ATTRIBUTE_COMPRESSED
@anchor{library/stat stat FILE_ATTRIBUTE_DEVICE}@anchor{27a4}
@deffnx {Données} stat.FILE_ATTRIBUTE_DEVICE
@anchor{library/stat stat FILE_ATTRIBUTE_DIRECTORY}@anchor{27a5}
@deffnx {Données} stat.FILE_ATTRIBUTE_DIRECTORY
@anchor{library/stat stat FILE_ATTRIBUTE_ENCRYPTED}@anchor{27a6}
@deffnx {Données} stat.FILE_ATTRIBUTE_ENCRYPTED
@anchor{library/stat stat FILE_ATTRIBUTE_HIDDEN}@anchor{27a7}
@deffnx {Données} stat.FILE_ATTRIBUTE_HIDDEN
@anchor{library/stat stat FILE_ATTRIBUTE_INTEGRITY_STREAM}@anchor{27a8}
@deffnx {Données} stat.FILE_ATTRIBUTE_INTEGRITY_STREAM
@anchor{library/stat stat FILE_ATTRIBUTE_NORMAL}@anchor{27a9}
@deffnx {Données} stat.FILE_ATTRIBUTE_NORMAL
@anchor{library/stat stat FILE_ATTRIBUTE_NOT_CONTENT_INDEXED}@anchor{27aa}
@deffnx {Données} stat.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
@anchor{library/stat stat FILE_ATTRIBUTE_NO_SCRUB_DATA}@anchor{27ab}
@deffnx {Données} stat.FILE_ATTRIBUTE_NO_SCRUB_DATA
@anchor{library/stat stat FILE_ATTRIBUTE_OFFLINE}@anchor{27ac}
@deffnx {Données} stat.FILE_ATTRIBUTE_OFFLINE
@anchor{library/stat stat FILE_ATTRIBUTE_READONLY}@anchor{27ad}
@deffnx {Données} stat.FILE_ATTRIBUTE_READONLY
@anchor{library/stat stat FILE_ATTRIBUTE_REPARSE_POINT}@anchor{27ae}
@deffnx {Données} stat.FILE_ATTRIBUTE_REPARSE_POINT
@anchor{library/stat stat FILE_ATTRIBUTE_SPARSE_FILE}@anchor{27af}
@deffnx {Données} stat.FILE_ATTRIBUTE_SPARSE_FILE
@anchor{library/stat stat FILE_ATTRIBUTE_SYSTEM}@anchor{27b0}
@deffnx {Données} stat.FILE_ATTRIBUTE_SYSTEM
@anchor{library/stat stat FILE_ATTRIBUTE_TEMPORARY}@anchor{27b1}
@deffnx {Données} stat.FILE_ATTRIBUTE_TEMPORARY
@anchor{library/stat stat FILE_ATTRIBUTE_VIRTUAL}@anchor{27b2}
@deffnx {Données} stat.FILE_ATTRIBUTE_VIRTUAL


Ajouté dans la version 3.5.

@end deffn

On Windows, the following constants are available for comparing against the
@code{st_reparse_tag} member returned by @ref{48b,,os.lstat()}. These are well-known
constants, but are not an exhaustive list.

@geindex IO_REPARSE_TAG_SYMLINK (dans le module stat)
@geindex IO_REPARSE_TAG_MOUNT_POINT (dans le module stat)
@geindex IO_REPARSE_TAG_APPEXECLINK (dans le module stat)
@anchor{library/stat stat IO_REPARSE_TAG_SYMLINK}@anchor{27b3}
@deffn {Données} stat.IO_REPARSE_TAG_SYMLINK
@anchor{library/stat stat IO_REPARSE_TAG_MOUNT_POINT}@anchor{27b4}
@deffnx {Données} stat.IO_REPARSE_TAG_MOUNT_POINT
@anchor{library/stat stat IO_REPARSE_TAG_APPEXECLINK}@anchor{27b5}
@deffnx {Données} stat.IO_REPARSE_TAG_APPEXECLINK


Ajouté dans la version 3.8.

@end deffn

@node filecmp --- File and Directory Comparisons,tempfile --- Generate temporary files and directories,stat --- Interpreting stat results,Accès aux Fichiers et aux Dossiers
@anchor{library/filecmp doc}@anchor{27b6}@anchor{library/filecmp filecmp-file-and-directory-comparisons}@anchor{27b7}@anchor{library/filecmp module-filecmp}@anchor{59}
@subsection @code{filecmp} --- File and Directory Comparisons


@geindex module; filecmp

`Code source :' Lib/filecmp.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/filecmp.py}


__________________________________________________________________


Le module @ref{59,,filecmp} définit les fonctions permettant de comparer les fichiers et les répertoires, avec différents compromis optionnels durée / exactitude. Pour comparer des fichiers, voir aussi le module @ref{37,,difflib}.

Le module @ref{59,,filecmp} définit les fonctions suivantes :

@geindex cmp() (dans le module filecmp)
@anchor{library/filecmp filecmp cmp}@anchor{15e7}
@deffn {Fonction} filecmp.cmp (f1, f2, shallow=True)

Compare les fichiers nommés `f1' et `f2' , renvoie @code{True} s’ils semblent égaux, @code{False} sinon.

If `shallow' is true and the @ref{48a,,os.stat()} signatures (file type, size, and
modification time) of both files are identical, the files are taken to be
equal.

Otherwise, the files are treated as different if their sizes or contents differ.

Notez qu'aucun programme externe n'est appelé à partir de cette fonction, ce qui lui confère des qualités de portabilité et d'efficacité.

Cette fonction utilise un cache pour les comparaisons antérieures et les résultats, les entrées du cache étant invalidées si les informations @ref{48a,,os.stat()} du fichier sont modifiées. La totalité du cache peut être effacée avec @ref{f29,,clear_cache()}.
@end deffn

@geindex cmpfiles() (dans le module filecmp)
@anchor{library/filecmp filecmp cmpfiles}@anchor{1571}
@deffn {Fonction} filecmp.cmpfiles (dir1, dir2, common, shallow=True)

Compare les fichiers des deux répertoires `dir1' et `dir2' dont les noms sont donnés par `common'.

Renvoie trois listes de noms de fichiers : `match' , `mismatch', `errors'. `match' contient la liste des fichiers qui correspondent, `mismatch' contient les noms de ceux qui ne correspondent pas et `errors' répertorie les noms des fichiers qui n'ont pas pu être comparés. Les fichiers sont répertoriés dans `errors' s'ils n'existent pas dans l'un des répertoires, si l'utilisateur ne dispose pas de l'autorisation nécessaire pour les lire ou si la comparaison n'a pas pu être effectuée pour une autre raison.

Le paramètre `shallow' a la même signification et la même valeur par défaut que pour @ref{15e7,,filecmp.cmp()}.

Par exemple, @code{cmpfiles('a', 'b', ['c', 'd/e'])}  compare @code{a/c} et @code{b/c} et @code{a/d/e} avec @code{b/d/e}.  @code{'c'} et @code{'d/e'} seront chacun dans l'une des trois listes renvoyées.
@end deffn

@geindex clear_cache() (dans le module filecmp)
@anchor{library/filecmp filecmp clear_cache}@anchor{f29}
@deffn {Fonction} filecmp.clear_cache ()

Efface le cache `filecmp'. Cela peut être utile si un fichier est comparé juste après avoir été modifié (dans un délai inférieur à la résolution `mtime' du système de fichiers sous-jacent).


Ajouté dans la version 3.4.

@end deffn

@menu
* La classe dircmp:: 

@end menu

@node La classe dircmp,,,filecmp --- File and Directory Comparisons
@anchor{library/filecmp dircmp-objects}@anchor{27b8}@anchor{library/filecmp the-dircmp-class}@anchor{27b9}
@subsubsection La classe @code{dircmp}


@geindex dircmp (classe dans filecmp)
@anchor{library/filecmp filecmp dircmp}@anchor{f2b}
@deffn {Classe} filecmp.dircmp (a, b, ignore=None, hide=None, *, shallow=True)

Construct a new directory comparison object, to compare the directories `a'
and `b'.  `ignore' is a list of names to ignore, and defaults to
@ref{f2a,,filecmp.DEFAULT_IGNORES}.  `hide' is a list of names to hide, and
defaults to @code{[os.curdir, os.pardir]}.

The @ref{f2b,,dircmp} class compares files by doing `shallow' comparisons
as described for @ref{15e7,,filecmp.cmp()} by default using the `shallow'
parameter.


Modifié dans la version 3.13: Added the `shallow' parameter.


La classe @ref{f2b,,dircmp} fournit les méthodes suivantes :

@geindex report() (méthode filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp report}@anchor{27ba}
@deffn {Méthode} report ()

Affiche (sur @ref{ac4,,sys.stdout}) une comparaison entre `a' et `b'.
@end deffn

@geindex report_partial_closure() (méthode filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp report_partial_closure}@anchor{27bb}
@deffn {Méthode} report_partial_closure ()

Affiche une comparaison entre `a' et `b' et les sous-répertoires immédiats communs.
@end deffn

@geindex report_full_closure() (méthode filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp report_full_closure}@anchor{27bc}
@deffn {Méthode} report_full_closure ()

Affiche une comparaison entre a et b et les sous-répertoires communs (récursivement).
@end deffn

La classe @ref{f2b,,dircmp} offre un certain nombre d'attributs intéressants qui peuvent être utilisés pour obtenir diverses informations sur les arborescences de répertoires comparées.

Note that via @ref{4bc,,__getattr__()} hooks, all attributes are computed lazily,
so there is no speed penalty if only those attributes which are lightweight
to compute are used.

@geindex left (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp left}@anchor{27bd}
@deffn {Attribut} left

Le répertoire `a'.
@end deffn

@geindex right (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp right}@anchor{27be}
@deffn {Attribut} right

Le répertoire `b'.
@end deffn

@geindex left_list (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp left_list}@anchor{27bf}
@deffn {Attribut} left_list

Fichiers et sous-répertoires dans `a' , filtrés par `hide' et `ignore'.
@end deffn

@geindex right_list (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp right_list}@anchor{27c0}
@deffn {Attribut} right_list

Fichiers et sous-répertoires dans `b' , filtrés par `hide' et `ignore'.
@end deffn

@geindex common (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common}@anchor{27c1}
@deffn {Attribut} common

Fichiers et sous-répertoires à la fois dans `a' et `b'.
@end deffn

@geindex left_only (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp left_only}@anchor{27c2}
@deffn {Attribut} left_only

Fichiers et sous-répertoires uniquement dans `a'.
@end deffn

@geindex right_only (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp right_only}@anchor{27c3}
@deffn {Attribut} right_only

Fichiers et sous-répertoires uniquement dans `b'.
@end deffn

@geindex common_dirs (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common_dirs}@anchor{27c4}
@deffn {Attribut} common_dirs

Sous-répertoires à la fois dans `a' et `b'.
@end deffn

@geindex common_files (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common_files}@anchor{27c5}
@deffn {Attribut} common_files

Fichiers à la fois dans `a' et `b'.
@end deffn

@geindex common_funny (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp common_funny}@anchor{27c6}
@deffn {Attribut} common_funny

Noms dans `a' et `b' , tels que le type diffère entre les répertoires, ou noms pour lesquels @ref{48a,,os.stat()} signale une erreur.
@end deffn

@geindex same_files (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp same_files}@anchor{27c7}
@deffn {Attribut} same_files

Fichiers identiques dans `a' et `b', en utilisant l'opérateur de comparaison de fichiers de la classe.
@end deffn

@geindex diff_files (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp diff_files}@anchor{27c8}
@deffn {Attribut} diff_files

Fichiers figurant à la fois dans `a' et dans `b' , dont le contenu diffère en fonction de l'opérateur de comparaison de fichiers de la classe.
@end deffn

@geindex funny_files (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp funny_files}@anchor{27c9}
@deffn {Attribut} funny_files

Fichiers à la fois dans `a' et dans `b' , mais ne pouvant pas être comparés.
@end deffn

@geindex subdirs (attribut filecmp.dircmp)
@anchor{library/filecmp filecmp dircmp subdirs}@anchor{18aa}
@deffn {Attribut} subdirs

A dictionary mapping names in @ref{27c4,,common_dirs} to @ref{f2b,,dircmp}
instances (or MyDirCmp instances if this instance is of type MyDirCmp, a
subclass of @ref{f2b,,dircmp}).


Modifié dans la version 3.10: Previously entries were always @ref{f2b,,dircmp} instances. Now entries
are the same type as `self', if `self' is a subclass of
@ref{f2b,,dircmp}.

@end deffn
@end deffn

@geindex DEFAULT_IGNORES (dans le module filecmp)
@anchor{library/filecmp filecmp DEFAULT_IGNORES}@anchor{f2a}
@deffn {Attribut} filecmp.DEFAULT_IGNORES


Ajouté dans la version 3.4.


Liste des répertoires ignorés par défaut par @ref{f2b,,dircmp}.
@end deffn

Voici un exemple simplifié d'utilisation de l'attribut @code{subdirs} pour effectuer une recherche récursive dans deux répertoires afin d'afficher des fichiers communs différents :

@example
>>> from filecmp import dircmp
>>> def print_diff_files(dcmp):
...     for name in dcmp.diff_files:
...         print("diff_file %s found in %s and %s" % (name, dcmp.left,
...               dcmp.right))
...     for sub_dcmp in dcmp.subdirs.values():
...         print_diff_files(sub_dcmp)
...
>>> dcmp = dircmp('dir1', 'dir2') 
>>> print_diff_files(dcmp) 
@end example

@node tempfile --- Generate temporary files and directories,glob --- Unix style pathname pattern expansion,filecmp --- File and Directory Comparisons,Accès aux Fichiers et aux Dossiers
@anchor{library/tempfile doc}@anchor{27ca}@anchor{library/tempfile module-tempfile}@anchor{df}@anchor{library/tempfile tempfile-generate-temporary-files-and-directories}@anchor{27cb}
@subsection @code{tempfile} --- Generate temporary files and directories


@geindex module; tempfile

`Code source :' Lib/tempfile.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tempfile.py}

@geindex temporary;file name
@geindex temporary;file


__________________________________________________________________


This module creates temporary files and directories.  It works on all
supported platforms. @ref{27cc,,TemporaryFile}, @ref{4af,,NamedTemporaryFile},
@ref{1212,,TemporaryDirectory}, and @ref{67e,,SpooledTemporaryFile} are high-level
interfaces which provide automatic cleanup and can be used as
@ref{5be,,context managers}. @ref{27cd,,mkstemp()} and
@ref{21c,,mkdtemp()} are lower-level functions which require manual cleanup.

Toutes les fonctions et constructeurs appelables par l'utilisateur ont des arguments additionnels qui permettent de contrôler directement le chemin et le nom des répertoires et fichiers. Les noms de fichiers utilisés par ce module incluent une chaîne de caractères aléatoires qui leur permet d'être créés de manière sécurisée dans des répertoires temporaires partagés. Afin de maintenir la compatibilité descendante, l'ordre des arguments est quelque peu étrange ; pour des questions de clarté, il est recommandé d'utiliser les arguments nommés.

Le module définit les éléments suivants pouvant être appelés par l'utilisateur :

@geindex TemporaryFile() (dans le module tempfile)
@anchor{library/tempfile tempfile TemporaryFile}@anchor{27cc}
@deffn {Fonction} tempfile.TemporaryFile (mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

Renvoie un @ref{250d,,objet fichier} qui peut être utilisé comme une zone de stockage temporaire. Le fichier est créé de manière sécurisée, utilisant les mêmes règles que @ref{27cd,,mkstemp()}. Il sera détruit dès qu'il sera fermé (y compris lorsque le fichier est implicitement fermé quand il est collecté par le ramasse-miettes). Sous Unix, soit l'entrée du répertoire n'est pas du tout créée, soit elle est supprimée immédiatement après la création du fichier. Les autres plateformes ne gèrent pas cela, votre code ne doit pas compter sur un fichier temporaire créé en utilisant cette fonction ayant ou non un nom visible sur le système de fichiers.

The resulting object can be used as a @ref{5be,,context manager} (see
@ref{27ce,,Exemples}).  On completion of the context or
destruction of the file object the temporary file will be removed
from the filesystem.

Le paramètre `mode' vaut par défaut @code{'w+b'} afin que le fichier créé puisse être lu et écrit sans être fermé. Le mode binaire est utilisé afin que le comportement soit le même sur toutes les plateformes quelle que soit la donnée qui est stockée. `buffering', `encoding', `errors' et `newline' sont interprétés de la même façon que pour @ref{505,,open()}.

Les paramètres `dir', `prefix' et `suffix' ont la même signification et les mêmes valeurs par défaut que dans @ref{27cd,,mkstemp()}.

L'objet renvoyé est un véritable fichier sur les plateformes POSIX. Sur les autres plateformes, c'est un objet fichier-compatible, dont l'attribut @code{file} donne le véritable fichier.

The @ref{f5e,,os.O_TMPFILE} flag is used if it is available and works
(Linux-specific, requires Linux kernel 3.11 or later).

Sur les plateformes qui ne sont pas POSIX ni Cygwin, @code{TemporaryFile} est un alias de @code{NamedTemporaryFile}.

Lève un @ref{1848,,évènement d'audit} @code{tempfile.mkstemp} avec comme argument @code{fullpath}.


Modifié dans la version 3.5: The @ref{f5e,,os.O_TMPFILE} flag is now used if available.



Modifié dans la version 3.8: Le paramètre `errors' a été ajouté.

@end deffn

@geindex NamedTemporaryFile() (dans le module tempfile)
@anchor{library/tempfile tempfile NamedTemporaryFile}@anchor{4af}
@deffn {Fonction} tempfile.NamedTemporaryFile (mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None, delete_on_close=True)

This function operates exactly as @ref{27cc,,TemporaryFile()} does, except the
following differences:


@itemize *

@item 
This function returns a file that is guaranteed to have a visible name in
the file system.

@item 
To manage the named file, it extends the parameters of
@ref{27cc,,TemporaryFile()} with `delete' and `delete_on_close' parameters that
determine whether and how the named file should be automatically deleted.
@end itemize

The returned object is always a @ref{250d,,file-like object} whose @code{file}
attribute is the underlying true file object. This file-like object
can be used in a @ref{5bc,,with} statement, just like a normal file.  The
name of the temporary file can be retrieved from the @code{name} attribute
of the returned file-like object. On Unix, unlike with the
@ref{27cc,,TemporaryFile()}, the directory entry does not get unlinked immediately
after the file creation.

If `delete' is true (the default) and `delete_on_close' is true (the
default), the file is deleted as soon as it is closed. If `delete' is true
and `delete_on_close' is false, the file is deleted on context manager exit
only, or else when the @ref{250d,,file-like object} is finalized. Deletion is not
always guaranteed in this case (see @ref{1ee3,,object.__del__()}). If `delete' is
false, the value of `delete_on_close' is ignored.

Therefore to use the name of the temporary file to reopen the file after
closing it, either make sure not to delete the file upon closure (set the
`delete' parameter to be false) or, in case the temporary file is created in
a @ref{5bc,,with} statement, set the `delete_on_close' parameter to be false.
The latter approach is recommended as it provides assistance in automatic
cleaning of the temporary file upon the context manager exit.

Opening the temporary file again by its name while it is still open works as
follows:


@itemize *

@item 
On POSIX the file can always be opened again.

@item 
On Windows, make sure that at least one of the following conditions are
fulfilled:


@itemize *

@item 
`delete' is false

@item 
additional open shares delete access (e.g. by calling @ref{d7f,,os.open()}
with the flag @code{O_TEMPORARY})

@item 
`delete' is true but `delete_on_close' is false. Note, that in this
case the additional opens that do not share delete access (e.g.
created via builtin @ref{505,,open()}) must be closed before exiting the
context manager, else the @ref{10d6,,os.unlink()} call on context manager
exit will fail with a @ref{d30,,PermissionError}.
@end itemize
@end itemize

On Windows, if `delete_on_close' is false, and the file is created in a
directory for which the user lacks delete access, then the @ref{10d6,,os.unlink()}
call on exit of the context manager will fail with a @ref{d30,,PermissionError}.
This cannot happen when `delete_on_close' is true because delete access is
requested by the open, which fails immediately if the requested access is not
granted.

On POSIX (only), a process that is terminated abruptly with SIGKILL
cannot automatically delete any NamedTemporaryFiles it created.

Lève un @ref{1848,,évènement d'audit} @code{tempfile.mkstemp} avec comme argument @code{fullpath}.


Modifié dans la version 3.8: Le paramètre `errors' a été ajouté.



Modifié dans la version 3.12: Added `delete_on_close' parameter.

@end deffn

@geindex SpooledTemporaryFile (classe dans tempfile)
@anchor{library/tempfile tempfile SpooledTemporaryFile}@anchor{67e}
@deffn {Classe} tempfile.SpooledTemporaryFile (max_size=0, mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

This class operates exactly as @ref{27cc,,TemporaryFile()} does, except that
data is spooled in memory until the file size exceeds `max_size', or
until the file's @ref{27cf,,fileno()} method is called, at which point the
contents are written to disk and operation proceeds as with
@ref{27cc,,TemporaryFile()}.

@geindex rollover() (méthode tempfile.SpooledTemporaryFile)
@anchor{library/tempfile tempfile SpooledTemporaryFile rollover}@anchor{27d0}
@deffn {Méthode} rollover ()

The resulting file has one additional method, @code{rollover()}, which
causes the file to roll over to an on-disk file regardless of its size.
@end deffn

The returned object is a file-like object whose @code{_file} attribute
is either an @ref{e8d,,io.BytesIO} or @ref{7a5,,io.TextIOWrapper} object
(depending on whether binary or text `mode' was specified) or a true file
object, depending on whether @ref{27d0,,rollover()} has been called.  This
file-like object can be used in a @ref{5bc,,with} statement, just like
a normal file.


Modifié dans la version 3.3: the truncate method now accepts a `size' argument.



Modifié dans la version 3.8: Le paramètre `errors' a été ajouté.



Modifié dans la version 3.11: Fully implements the @ref{67f,,io.BufferedIOBase} and
@ref{680,,io.TextIOBase} abstract base classes (depending on whether binary
or text `mode' was specified).

@end deffn

@geindex TemporaryDirectory (classe dans tempfile)
@anchor{library/tempfile tempfile TemporaryDirectory}@anchor{1212}
@deffn {Classe} tempfile.TemporaryDirectory (suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)

This class securely creates a temporary directory using the same rules as @ref{21c,,mkdtemp()}.
The resulting object can be used as a @ref{5be,,context manager} (see
@ref{27ce,,Exemples}).  On completion of the context or destruction
of the temporary directory object, the newly created temporary directory
and all its contents are removed from the filesystem.

@geindex name (attribut tempfile.TemporaryDirectory)
@anchor{library/tempfile tempfile TemporaryDirectory name}@anchor{27d1}
@deffn {Attribut} name

The directory name can be retrieved from the @code{name} attribute of the
returned object.  When the returned object is used as a @ref{5be,,context manager}, the
@code{name} will be assigned to the target of the @code{as} clause in
the @ref{5bc,,with} statement, if there is one.
@end deffn

@geindex cleanup() (méthode tempfile.TemporaryDirectory)
@anchor{library/tempfile tempfile TemporaryDirectory cleanup}@anchor{27d2}
@deffn {Méthode} cleanup ()

The directory can be explicitly cleaned up by calling the
@code{cleanup()} method. If `ignore_cleanup_errors' is true, any unhandled
exceptions during explicit or implicit cleanup (such as a
@ref{d30,,PermissionError} removing open files on Windows) will be ignored,
and the remaining removable items deleted on a "best-effort" basis.
Otherwise, errors will be raised in whatever context cleanup occurs
(the @code{cleanup()} call, exiting the context manager, when the object
is garbage-collected or during interpreter shutdown).
@end deffn

The `delete' parameter can be used to disable cleanup of the directory tree
upon exiting the context.  While it may seem unusual for a context manager
to disable the action taken when exiting the context, it can be useful during
debugging or when you need your cleanup behavior to be conditional based on
other logic.

Lève un @ref{1848,,évènement d'audit} @code{tempfile.mkdtemp} avec comme argument @code{fullpath}.


Ajouté dans la version 3.2.



Modifié dans la version 3.10: ajout du paramètre `ignore_cleanup_errors'.



Modifié dans la version 3.12: Added the `delete' parameter.

@end deffn

@geindex mkstemp() (dans le module tempfile)
@anchor{library/tempfile tempfile mkstemp}@anchor{27cd}
@deffn {Fonction} tempfile.mkstemp (suffix=None, prefix=None, dir=None, text=False)

Crée un fichier temporaire de la manière la plus sécurisée qui soit. Il n'y a pas de problème d'accès concurrent (`race condition' en anglais) au moment de la création du fichier, en supposant que la plateforme implémente correctement l'option @ref{27d3,,os.O_EXCL} pour @ref{d7f,,os.open()}. Le fichier est seulement accessible en lecture et écriture par l'ID de l'utilisateur créateur. Si la plateforme utilise des bits de permissions pour indiquer si le fichier est exécutable, alors le fichier n'est exécutable par personne. Le descripteur de fichier n'est pas hérité par les processus fils.

À la différence de @ref{27cc,,TemporaryFile()}, l'utilisateur de @ref{27cd,,mkstemp()} est responsable de la suppression du fichier temporaire quand il n'en a plus besoin.

Si `suffix' ne vaut pas @code{None}, le nom de fichier se terminera avec ce suffixe, sinon il n'y aura pas de suffixe. @ref{27cd,,mkstemp()} ne met pas de point entre le nom du fichier et le suffixe. Si vous en avez besoin, mettez le point au début de `suffix'.

Si `prefix' ne vaut pas @code{None}, le nom de fichier commencera avec ce préfixe, sinon un préfixe par défaut est utilisé. La valeur par défaut est la valeur retournée par @ref{27d4,,gettempprefix()} ou @ref{27d5,,gettempprefixb()}.

Si `dir' ne vaut pas @code{None}, le fichier sera créé dans ce répertoire, autrement, un répertoire par défaut sera utilisé. Le répertoire par défaut est choisi depuis une liste dépendante de la plateforme, mais l'utilisateur de l'application peut contrôler l'emplacement du répertoire en spécifiant les variables d'environnement `TMPDIR', `TEMP' ou `TMP'. Il n'y a pas de garantie que le nom de fichier généré aura de bonnes propriétés telles que ne pas avoir besoin de le mettre entre guillemets lorsque celui-ci est passé à des commandes externes via @code{os.popen()}.

Si l'un des paramètres `suffix', `prefix' et `dir' n'est pas @code{None}, ils doivent être du même type. S'ils sont de type @code{bytes}, le nom renvoyé est de type @code{bytes} plutôt que de type @code{str}. Si vous voulez forcer la valeur renvoyée en @code{bytes}, passez @code{suffix=b'@w{'}}.

Le fichier est ouvert en mode binaire, sauf si `text' est mis à vrai, auquel cas il est ouvert en mode textuel.

@ref{27cd,,mkstemp()} renvoie une paire contenant un descripteur (`handle' en anglais) au niveau du système d'exploitation vers un fichier ouvert (le même que renvoie @ref{d7f,,os.open()}) et le chemin d'accès absolu de ce fichier, dans cet ordre.

Lève un @ref{1848,,évènement d'audit} @code{tempfile.mkstemp} avec comme argument @code{fullpath}.


Modifié dans la version 3.5: `suffix', `prefix', et `dir' peuvent maintenant être spécifiés en @code{bytes} pour obtenir un résultat en @code{bytes}. Avant cela, le type @code{str} était le seul autorisé. `suffix' et `prefix' acceptent maintenant la valeur par défaut @code{None} pour que la valeur par défaut appropriée soit utilisée.



Modifié dans la version 3.6: Le paramètre `dir' accepte un @ref{29d,,objet fichier-compatible}.

@end deffn

@geindex mkdtemp() (dans le module tempfile)
@anchor{library/tempfile tempfile mkdtemp}@anchor{21c}
@deffn {Fonction} tempfile.mkdtemp (suffix=None, prefix=None, dir=None)

Crée un répertoire temporaire de la manière la plus sécurisée qu'il soit. Il n'y a pas de problème d'accès concurrent (`race condition' en anglais) au moment de la création du répertoire. Le répertoire est accessible en lecture, en écriture, et son contenu lisible uniquement pour l'ID de l'utilisateur créateur.

L'utilisateur de @ref{21c,,mkdtemp()} est responsable de la suppression du répertoire temporaire et de son contenu lorsqu'il n'en a plus besoin.

Les arguments `prefix', `suffix', et `dir' sont les mêmes que pour @ref{27cd,,mkstemp()}.

@ref{21c,,mkdtemp()} renvoie le chemin absolu du nouveau répertoire.

Lève un @ref{1848,,évènement d'audit} @code{tempfile.mkdtemp} avec comme argument @code{fullpath}.


Modifié dans la version 3.5: `suffix', `prefix', et `dir' peuvent maintenant être spécifiés en @code{bytes} pour obtenir un résultat en @code{bytes}. Avant cela, le type @code{str} était le seul autorisé. `suffix' et `prefix' acceptent maintenant la valeur par défaut @code{None} pour que la valeur par défaut appropriée soit utilisée.



Modifié dans la version 3.6: Le paramètre `dir' accepte un @ref{29d,,objet fichier-compatible}.



Modifié dans la version 3.12: @ref{21c,,mkdtemp()} now always returns an absolute path, even if `dir' is relative.

@end deffn

@geindex gettempdir() (dans le module tempfile)
@anchor{library/tempfile tempfile gettempdir}@anchor{1867}
@deffn {Fonction} tempfile.gettempdir ()

Renvoie le nom du répertoire utilisé pour les fichiers temporaires. C'est la valeur par défaut pour l'argument `dir' de toutes les fonctions de ce module.

Python cherche un répertoire parmi une liste standard de répertoires dans lequel l'utilisateur final peut créer des fichiers. La liste est :


@enumerate 

@item 
Le répertoire correspondant à la variable d'environnement 
@geindex TMPDIR
@geindex variable d'environnement; TMPDIR
@code{TMPDIR}.

@item 
Le répertoire correspondant à la variable d'environnement 
@geindex TEMP
@geindex variable d'environnement; TEMP
@code{TEMP}.

@item 
Le répertoire correspondant à la variable d'environnement 
@geindex TMP
@geindex variable d'environnement; TMP
@code{TMP}.

@item 
Un emplacement dépendant de la plateforme :


@itemize *

@item 
Sur Windows, les répertoires @code{C:\TEMP}, @code{C:\TMP}, @code{\TEMP}, et @code{\TMP}, dans cet ordre.

@item 
Sur toutes les autres plate-formes, les répertoires @code{/tmp}, @code{/var/tmp}, et @code{/usr/tmp}, dans cet ordre.
@end itemize

@item 
En dernier ressort, le répertoire de travail courant.
@end enumerate

Le résultat de cette recherche est mis en cache, voir la description de @ref{1866,,tempdir} dessous.


Modifié dans la version 3.10: Cette fonction renvoie désormais systématiquement une chaîne de caractères. Auparavant, elle pouvait renvoyer la valeur de @ref{1866,,tempdir} quel que soit son type tant que ce n'était pas @code{None}.

@end deffn

@geindex gettempdirb() (dans le module tempfile)
@anchor{library/tempfile tempfile gettempdirb}@anchor{1868}
@deffn {Fonction} tempfile.gettempdirb ()

Similaire à @ref{1867,,gettempdir()} mais la valeur retournée est en `bytes'.


Ajouté dans la version 3.5.

@end deffn

@geindex gettempprefix() (dans le module tempfile)
@anchor{library/tempfile tempfile gettempprefix}@anchor{27d4}
@deffn {Fonction} tempfile.gettempprefix ()

Renvoie le préfixe de nom de fichier utilisé pour créer les fichiers temporaires. Cela ne contient pas le nom du répertoire.
@end deffn

@geindex gettempprefixb() (dans le module tempfile)
@anchor{library/tempfile tempfile gettempprefixb}@anchor{27d5}
@deffn {Fonction} tempfile.gettempprefixb ()

Similaire à @ref{27d4,,gettempprefix()} mais la valeur retournée est en `bytes'.


Ajouté dans la version 3.5.

@end deffn

Le module utilise une variable globale pour stocker le nom du répertoire utilisé pour les fichiers temporaires renvoyés par @ref{1867,,gettempdir()}. Vous pouvez directement utiliser la variable globale pour surcharger le processus de sélection, mais ceci est déconseillé. Toutes les fonctions de ce module prennent un argument `dir' qui peut être utilisé pour spécifier le répertoire. Il s'agit de la méthode recommandée car elle n'interfère pas avec le code extérieur en modifiant le comportement global du module.

@geindex tempdir (dans le module tempfile)
@anchor{library/tempfile tempfile tempdir}@anchor{1866}
@deffn {Données} tempfile.tempdir

Quand une valeur autre que @code{None} est spécifiée, cette variable définit la valeur par défaut pour l'argument `dir' des fonctions définies dans ce module, et en particulier son type (@code{bytes} ou @code{str}). Les @ref{29d,,objets fichier-compatibles} ne sont pas acceptés.

Si @code{tempdir} vaut @code{None} (par défaut) pour n'importe laquelle des fonctions ci-dessus, sauf @ref{27d4,,gettempprefix()}, la variable est initialisée suivant l'algorithme décrit dans @ref{1867,,gettempdir()}.

@cartouche
@quotation Note 
Attention, le fait de mettre @code{tempdir} à une valeur de type @code{bytes} a l'effet pervers de changer globalement en @code{bytes} le type de retour de @ref{27cd,,mkstemp()} et @ref{21c,,mkdtemp()} lorsqu'elles sont appelées sans qu'aucun des paramètres `prefix', `suffix' et `dir' ne soit de type @code{str}. Ce comportement par défaut surprenant est préservé par souci de compatibilité avec l'implémentation historique du module. Il est fortement recommandé de ne pas s'y fier.
@end quotation
@end cartouche
@end deffn

@menu
* Exemples: Exemples<5>. 
* Fonctions et variables obsolètes:: 

@end menu

@node Exemples<5>,Fonctions et variables obsolètes,,tempfile --- Generate temporary files and directories
@anchor{library/tempfile examples}@anchor{27d6}@anchor{library/tempfile tempfile-examples}@anchor{27ce}
@subsubsection Exemples


Voici quelques exemples classiques d'utilisation du module @ref{df,,tempfile} :

@example
>>> import tempfile

# create a temporary file and write some data to it
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# read data from file
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# close the file, it will be removed
>>> fp.close()

# create a temporary file using a context manager
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# file is now closed and removed

# create a temporary file using a context manager
# close the file, use the name to open the file again
>>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
...     fp.write(b'Hello world!')
...     fp.close()
... # the file is closed, but not removed
... # open the file again by using its name
...     with open(fp.name, mode='rb') as f:
...         f.read()
b'Hello world!'
>>>
# file is now removed

# create a temporary directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed
@end example

@node Fonctions et variables obsolètes,,Exemples<5>,tempfile --- Generate temporary files and directories
@anchor{library/tempfile deprecated-functions-and-variables}@anchor{27d7}@anchor{library/tempfile tempfile-mktemp-deprecated}@anchor{27d8}
@subsubsection Fonctions et variables obsolètes


Historiquement, la méthode pour créer des fichiers temporaires consistait à générer un nom de fichier avec la fonction @ref{181b,,mktemp()} puis créer un fichier en utilisant ce nom. Malheureusement, cette méthode n'est pas fiable car un autre processus peut créer un fichier avec ce nom entre l'appel à la fonction @ref{181b,,mktemp()} et la tentative de création de fichier par le premier processus en cours. La solution est de combiner les deux étapes et de créer le fichier immédiatement. Cette approche est utilisée par @ref{27cd,,mkstemp()} et les autres fonctions décrites plus haut.

@geindex mktemp() (dans le module tempfile)
@anchor{library/tempfile tempfile mktemp}@anchor{181b}
@deffn {Fonction} tempfile.mktemp (suffix='@w{'}, prefix='tmp', dir=None)


Obsolète depuis la version 2.3: Utilisez @ref{27cd,,mkstemp()} à la place.


Renvoie le chemin absolu d'un fichier qui n'existe pas lorsque l'appel est fait. Les arguments `prefix', `suffix', et `dir' sont similaires à ceux de @ref{27cd,,mkstemp()} mais les noms de fichiers en `bytes', @code{sufix=None} et @code{prefix=None} ne sont pas implémentées.

@cartouche
@quotation Avertissement 
Utiliser cette fonction peut introduire une faille de sécurité dans votre programme. Avant que vous n'ayez le temps de faire quoi que ce soit avec le nom de fichier renvoyé, quelqu'un peut l'utiliser. L'utilisation de @ref{181b,,mktemp()} peut être remplacée facilement avec @ref{4af,,NamedTemporaryFile()} en y passant le paramètre @code{delete=False} :

@example
>>> f = NamedTemporaryFile(delete=False)
>>> f.name
'/tmp/tmptjujjt'
>>> f.write(b"Hello World!\n")
13
>>> f.close()
>>> os.unlink(f.name)
>>> os.path.exists(f.name)
False
@end example
@end quotation
@end cartouche
@end deffn

@node glob --- Unix style pathname pattern expansion,fnmatch --- Unix filename pattern matching,tempfile --- Generate temporary files and directories,Accès aux Fichiers et aux Dossiers
@anchor{library/glob doc}@anchor{27d9}@anchor{library/glob glob-unix-style-pathname-pattern-expansion}@anchor{27da}@anchor{library/glob module-glob}@anchor{63}
@subsection @code{glob} --- Unix style pathname pattern expansion


@geindex module; glob

`Code source :' Lib/glob.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/glob.py}

@geindex filenames;pathname expansion


__________________________________________________________________


@geindex * (asterisk);in glob-style wildcards
@geindex ? (question mark);in glob-style wildcards
@geindex [] (square brackets);in glob-style wildcards
@geindex ! (exclamation);in glob-style wildcards
@geindex - (minus);in glob-style wildcards
@geindex . (dot);in glob-style wildcards

The @ref{63,,glob} module finds all the pathnames matching a specified pattern
according to the rules used by the Unix shell, although results are returned in
arbitrary order.  No tilde expansion is done, but @code{*}, @code{?}, and character
ranges expressed with @code{[]} will be correctly matched.  This is done by using
the @ref{a4d,,os.scandir()} and @ref{182d,,fnmatch.fnmatch()} functions in concert, and
not by actually invoking a subshell.

Note that files beginning with a dot (@code{.}) can only be matched by
patterns that also start with a dot,
unlike @ref{182d,,fnmatch.fnmatch()} or @ref{22a,,pathlib.Path.glob()}.
(For tilde and shell variable expansion, use @ref{a02,,os.path.expanduser()} and
@ref{1390,,os.path.expandvars()}.)

Pour une correspondance littérale, il faut entourer le métacaractère par des crochets. Par exemple, @code{'[?]'} reconnaît le caractère @code{'?'}.

The @ref{63,,glob} module defines the following functions:

@geindex glob() (dans le module glob)
@anchor{library/glob glob glob}@anchor{29c}
@deffn {Fonction} glob.glob (pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

Return a possibly empty list of path names that match `pathname', which must be
a string containing a path specification. `pathname' can be either absolute
(like @code{/usr/src/Python-1.5/Makefile}) or relative (like
@code{../../Tools/*/*.gif}), and can contain shell-style wildcards. Broken
symlinks are included in the results (as in the shell). Whether or not the
results are sorted depends on the file system.  If a file that satisfies
conditions is removed or added during the call of this function, whether
a path name for that file will be included is unspecified.

Si `root_dir' n'est pas @code{None}, cela doit être un @ref{29d,,objet simili-chemin} spécifiant le dossier racine de la recherche.  Cela a le même effet sur @ref{63,,glob()} que de changer le dossier courant avant l'appel de la fonction.  Si `pathname' est relatif, les chemins du résultat seront relatifs au `root_dir' .

Cette fonction prend en charge les @ref{10cb,,chemins relatifs aux descripteurs de dossier} avec le paramètre `dir_fd'.

@geindex **;in glob-style wildcards

Si `recursive' est vrai, le motif "@code{**}" reconnaît tous les fichiers, aucun ou plusieurs répertoires, sous-répertoires et liens symboliques aux répertoires. Si le motif est suivi par @ref{655,,os.sep} ou @ref{656,,os.altsep} alors les fichiers ne sont pas inclus dans le résultat.

If `include_hidden' is true, "@code{**}" pattern will match hidden directories.

Lève un @ref{1848,,évènement d'audit} @code{glob.glob} avec les arguments @code{pathname}, @code{recursive}.

Lève un @ref{1848,,évènement d'audit} @code{glob.glob/2} avec les arguments @code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}.

@cartouche
@quotation Note 
Utiliser le motif "@code{**}" dans de grandes arborescences de dossier peut consommer une quantité de temps démesurée.
@end quotation
@end cartouche

@cartouche
@quotation Note 
This function may return duplicate path names if `pathname'
contains multiple "@code{**}" patterns and `recursive' is true.
@end quotation
@end cartouche


Modifié dans la version 3.5: Prise en charge des chemins récursifs utilisant le motif  "@code{**}".



Modifié dans la version 3.10: Paramètres `root_dir' et `dir_fd' ajoutés.



Modifié dans la version 3.11: Added the `include_hidden' parameter.

@end deffn

@geindex iglob() (dans le module glob)
@anchor{library/glob glob iglob}@anchor{7f1}
@deffn {Fonction} glob.iglob (pathname, *, root_dir=None, dir_fd=None, recursive=False, include_hidden=False)

Renvoie un @ref{1aa,,itérateur} qui produit les mêmes valeurs que @ref{63,,glob()}, sans toutes les charger en mémoire simultanément.

Lève un @ref{1848,,évènement d'audit} @code{glob.glob} avec les arguments @code{pathname}, @code{recursive}.

Lève un @ref{1848,,évènement d'audit} @code{glob.glob/2} avec les arguments @code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}.

@cartouche
@quotation Note 
This function may return duplicate path names if `pathname'
contains multiple "@code{**}" patterns and `recursive' is true.
@end quotation
@end cartouche


Modifié dans la version 3.5: Prise en charge des chemins récursifs utilisant le motif  "@code{**}".



Modifié dans la version 3.10: Paramètres `root_dir' et `dir_fd' ajoutés.



Modifié dans la version 3.11: Added the `include_hidden' parameter.

@end deffn

@geindex escape() (dans le module glob)
@anchor{library/glob glob escape}@anchor{f31}
@deffn {Fonction} glob.escape (pathname)

Échappe tous les caractères spéciaux (@code{'?'}, @code{'*'} et @code{'['}). Cela est utile pour reconnaître une chaîne de caractère littérale arbitraire qui contiendrait ce type de caractères. Les caractères spéciaux dans les disques et répertoires partagés (chemins UNC) ne sont pas échappés, e.g. sous Windows @code{escape('//?/c:/Quo vadis?.txt')} renvoie @code{'//?/c:/Quo vadis[?].txt'}.


Ajouté dans la version 3.4.

@end deffn

@geindex translate() (dans le module glob)
@anchor{library/glob glob translate}@anchor{1e7}
@deffn {Fonction} glob.translate (pathname, *, recursive=False, include_hidden=False, seps=None)

Convert the given path specification to a regular expression for use with
@ref{120b,,re.match()}. The path specification can contain shell-style wildcards.

Par exemple :

@example
>>> import glob, re
>>>
>>> regex = glob.translate('**/*.txt', recursive=True, include_hidden=True)
>>> regex
'(?s:(?:.+/)?[^/]*\\.txt)\\Z'
>>> reobj = re.compile(regex)
>>> reobj.match('foo/bar/baz.txt')
<re.Match object; span=(0, 15), match='foo/bar/baz.txt'>
@end example

Path separators and segments are meaningful to this function, unlike
@ref{19d4,,fnmatch.translate()}. By default wildcards do not match path
separators, and @code{*} pattern segments match precisely one path segment.

If `recursive' is true, the pattern segment "@code{**}" will match any number
of path segments.

If `include_hidden' is true, wildcards can match path segments that start
with a dot (@code{.}).

A sequence of path separators may be supplied to the `seps' argument. If
not given, @ref{655,,os.sep} and @ref{656,,altsep} (if available) are used.


@subsubheading Voir aussi


@ref{228,,pathlib.PurePath.full_match()} and @ref{22a,,pathlib.Path.glob()}
methods, which call this function to implement pattern matching and
globbing.



Ajouté dans la version 3.13.

@end deffn

@menu
* Exemples: Exemples<6>. 

@end menu

@node Exemples<6>,,,glob --- Unix style pathname pattern expansion
@anchor{library/glob examples}@anchor{27db}
@subsubsection Exemples


Consider a directory containing the following files:
@code{1.gif}, @code{2.txt}, @code{card.gif} and a subdirectory @code{sub}
which contains only the file @code{3.txt}.  @ref{63,,glob()} will produce
the following results.  Notice how any leading components of the path are
preserved.

@example
>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
>>> glob.glob('**/*.txt', recursive=True)
['2.txt', 'sub/3.txt']
>>> glob.glob('./**/', recursive=True)
['./', './sub/']
@end example

Si le répertoire contient des fichiers commençant par @code{.}, ils ne sont pas reconnus par défaut. Par exemple, considérons un répertoire contenant @code{card.gif} et @code{.card.gif} :

@example
>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']
@end example


@subsubheading Voir aussi


The @ref{5b,,fnmatch} module offers shell-style filename (not path) expansion.



@subsubheading Voir aussi


Le module @ref{a3,,pathlib} offre une représentation objet de haut niveau des chemins.


@node fnmatch --- Unix filename pattern matching,linecache --- Random access to text lines,glob --- Unix style pathname pattern expansion,Accès aux Fichiers et aux Dossiers
@anchor{library/fnmatch doc}@anchor{27dc}@anchor{library/fnmatch fnmatch-unix-filename-pattern-matching}@anchor{27dd}@anchor{library/fnmatch module-fnmatch}@anchor{5b}
@subsection @code{fnmatch} --- Unix filename pattern matching


@geindex module; fnmatch

`Code source :' Lib/fnmatch.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/fnmatch.py}

@geindex filenames;wildcard expansion

@geindex module;re


__________________________________________________________________


Ce module fournit la gestion des caractères de remplacement de style shell Unix, qui ne sont `pas' identiques à ceux utilisés dans les expressions régulières (documentés dans le module @ref{b8,,re}). Les caractères spéciaux utilisés comme caractères de remplacement de style shell sont :

@geindex * (asterisk);in glob-style wildcards
@geindex ? (question mark);in glob-style wildcards
@geindex [] (square brackets);in glob-style wildcards
@geindex ! (exclamation);in glob-style wildcards
@geindex - (minus);in glob-style wildcards


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Motif

@tab

Signification

@item

@code{*}

@tab

reconnaît n'importe quoi

@item

@code{?}

@tab

reconnaît n'importe quel caractère unique

@item

@code{[seq]}

@tab

reconnaît n'importe quel caractère dans `seq'

@item

@code{[!seq]}

@tab

reconnaît n'importe quel caractère qui n'est pas dans `seq'

@end multitable


Pour une correspondance littérale, il faut entourer le métacaractère par des crochets. Par exemple, @code{'[?]'} reconnaît le caractère @code{'?'}.

@geindex module;glob

Notons que le séparateur de nom de fichiers (@code{'/'} sous Unix) n'est `pas' traité de manière spéciale par ce module. Voir le module @ref{63,,glob} pour la recherche de chemins (@ref{63,,glob} utilise @ref{182f,,filter()} pour reconnaître les composants d'un chemin). De la même manière, les noms de fichiers commençant par un point ne sont pas traités de manière spéciale par ce module, et sont reconnus par les motifs @code{*} et @code{?}.

Also note that @ref{9dd,,functools.lru_cache()} with the `maxsize' of 32768 is used to
cache the compiled regex patterns in the following functions: @ref{5b,,fnmatch()},
@ref{182e,,fnmatchcase()}, @ref{182f,,filter()}.

@geindex fnmatch() (dans le module fnmatch)
@anchor{library/fnmatch fnmatch fnmatch}@anchor{182d}
@deffn {Fonction} fnmatch.fnmatch (name, pat)

Test whether the filename string `name' matches the pattern string `pat',
returning @code{True} or @code{False}.  Both parameters are case-normalized
using @ref{275c,,os.path.normcase()}. @ref{182e,,fnmatchcase()} can be used to perform a
case-sensitive comparison, regardless of whether that's standard for the
operating system.

Cet exemple affiche tous les noms de fichiers du répertoire courant ayant pour extension @code{.txt} :

@example
import fnmatch
import os

for file in os.listdir('.'):
    if fnmatch.fnmatch(file, '*.txt'):
        print(file)
@end example
@end deffn

@geindex fnmatchcase() (dans le module fnmatch)
@anchor{library/fnmatch fnmatch fnmatchcase}@anchor{182e}
@deffn {Fonction} fnmatch.fnmatchcase (name, pat)

Test whether the filename string `name' matches the pattern string `pat',
returning @code{True} or @code{False};
the comparison is case-sensitive and does not apply @ref{275c,,os.path.normcase()}.
@end deffn

@geindex filter() (dans le module fnmatch)
@anchor{library/fnmatch fnmatch filter}@anchor{182f}
@deffn {Fonction} fnmatch.filter (names, pat)

Construct a list from those elements of the @ref{1205,,iterable} `names'
that match pattern `pat'.
It is the same as @code{[n for n in names if fnmatch(n, pat)]},
but implemented more efficiently.
@end deffn

@geindex translate() (dans le module fnmatch)
@anchor{library/fnmatch fnmatch translate}@anchor{19d4}
@deffn {Fonction} fnmatch.translate (pat)

Return the shell-style pattern `pat' converted to a regular expression for
using with @ref{120b,,re.match()}.

Exemple :

@example
>>> import fnmatch, re
>>>
>>> regex = fnmatch.translate('*.txt')
>>> regex
'(?s:.*\\.txt)\\Z'
>>> reobj = re.compile(regex)
>>> reobj.match('foobar.txt')
<re.Match object; span=(0, 10), match='foobar.txt'>
@end example
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{63,,glob}

Recherche de chemins de style shell Unix.
@end table


@node linecache --- Random access to text lines,shutil --- High-level file operations,fnmatch --- Unix filename pattern matching,Accès aux Fichiers et aux Dossiers
@anchor{library/linecache doc}@anchor{27de}@anchor{library/linecache linecache-random-access-to-text-lines}@anchor{27df}@anchor{library/linecache module-linecache}@anchor{84}
@subsection @code{linecache} --- Random access to text lines


@geindex module; linecache

`Code source :' Lib/linecache.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/linecache.py}


__________________________________________________________________


Le module @ref{84,,linecache} permet d'obtenir n'importe quelle ligne d'un fichier source Python. Le cas classique où de nombreuses lignes sont accédées est optimisé en utilisant un cache interne. C'est utilisé par le module @ref{fd,,traceback} pour récupérer les lignes à afficher dans les piles d'appels.

Les fichiers sont ouverts par la fonction @ref{27e0,,tokenize.open()}. Cette fonction utilise @ref{27e1,,tokenize.detect_encoding()} pour obtenir l'encodage du fichier. En l'absence d'un BOM et d'un cookie d'encodage, c'est l'encodage UTF-8 qui sera utilisé.

Le module @ref{84,,linecache} définit les fonctions suivantes :

@geindex getline() (dans le module linecache)
@anchor{library/linecache linecache getline}@anchor{e10}
@deffn {Fonction} linecache.getline (filename, lineno, module_globals=None)

Récupère la ligne `lineno' du fichier `filename'.  Cette fonction ne lèvera jamais d'exception, elle préfèrera renvoyer @code{'@w{'}} en cas d'erreur (le caractère de retour à la ligne sera inclus pour les lignes existantes).

@geindex module;search;path

Si le fichier `filename' n'existe pas, cette fonction vérifie d'abord la présence d'un chargeur @code{__loader__} dans `module_globals', comme le prescrit la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}. Si un chargeur est trouvé avec une méthode @code{get_source}, c'est cette méthode qui détermine les lignes sources (si @code{get_source()} renvoie @code{None}, cette valeur est remplacée par la chaîne vide @code{'@w{'}}). Sinon, si le nom de fichier `filename' est relatif, il est recherché dans les dossiers du chemin de recherche des modules, @code{sys.path}.
@end deffn

@geindex clearcache() (dans le module linecache)
@anchor{library/linecache linecache clearcache}@anchor{27e2}
@deffn {Fonction} linecache.clearcache ()

Nettoie le cache. Utilisez cette fonction si vous n'avez plus besoin des lignes des fichiers précédemment lus via @ref{e10,,getline()}.
@end deffn

@geindex checkcache() (dans le module linecache)
@anchor{library/linecache linecache checkcache}@anchor{150d}
@deffn {Fonction} linecache.checkcache (filename=None)

Vérifie la validité du cache. Utilisez cette fonction si les fichiers du cache pourraient avoir changé sur le disque, et que vous en voudriez une version à jour. Sans `filename', toutes les entrées du cache seront vérifiées.
@end deffn

@geindex lazycache() (dans le module linecache)
@anchor{library/linecache linecache lazycache}@anchor{e0f}
@deffn {Fonction} linecache.lazycache (filename, module_globals)

Récupère suffisamment d'informations sur un module situé hors du système de fichiers pour récupérer ses lignes plus tard via @ref{e10,,getline()}, même si `module_globals' devient @code{None}. Cela évite de lire le fichier avant d'avoir besoin d'une ligne, tout en évitant de conserver les globales du module indéfiniment.


Ajouté dans la version 3.5.

@end deffn

Exemple :

@example
>>> import linecache
>>> linecache.getline(linecache.__file__, 8)
'import sys\n'
@end example

@node shutil --- High-level file operations,,linecache --- Random access to text lines,Accès aux Fichiers et aux Dossiers
@anchor{library/shutil doc}@anchor{27e3}@anchor{library/shutil module-shutil}@anchor{c4}@anchor{library/shutil shutil-high-level-file-operations}@anchor{27e4}
@subsection @code{shutil} --- High-level file operations


@geindex module; shutil

@c partly based on the docstrings

`Code source :' Lib/shutil.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/shutil.py}

@geindex file;copying
@geindex copying files


__________________________________________________________________


Le module @ref{c4,,shutil} propose des opérations de haut niveau sur les fichiers et ensembles de fichiers. En particulier, des fonctions pour copier et déplacer les fichiers sont proposées. Pour les opérations individuelles sur les fichiers, reportez-vous au module @ref{a0,,os}.

@cartouche
@quotation Avertissement 
Même les fonctions de copie haut niveau (@ref{a48,,shutil.copy()}, @ref{a49,,shutil.copy2()}) ne peuvent copier toutes les métadonnées des fichiers.

Sur les plateformes POSIX, cela signifie que le propriétaire et le groupe du fichier sont perdus, ainsi que les `ACLs'. Sur Mac OS, le clonage de ressource et autres métadonnées ne sont pas utilisés. Cela signifie que les ressources seront perdues et que le type de fichier et les codes créateur ne seront pas corrects. Sur Windows, les propriétaires des fichiers, `ACLs' et flux de données alternatifs ne sont pas copiés.
@end quotation
@end cartouche

@menu
* Opérations sur les répertoires et les fichiers:: 
* Archiving operations:: 
* Querying the size of the output terminal:: 

@end menu

@node Opérations sur les répertoires et les fichiers,Archiving operations,,shutil --- High-level file operations
@anchor{library/shutil directory-and-files-operations}@anchor{27e5}@anchor{library/shutil file-operations}@anchor{27e6}
@subsubsection Opérations sur les répertoires et les fichiers


@geindex copyfileobj() (dans le module shutil)
@anchor{library/shutil shutil copyfileobj}@anchor{a4b}
@deffn {Fonction} shutil.copyfileobj (fsrc, fdst[, length])

Copy the contents of the @ref{11a0,,file-like object} `fsrc' to the file-like object `fdst'.
The integer `length', if given, is the buffer size. In particular, a negative
`length' value means to copy the data without looping over the source data in
chunks; by default the data is read in chunks to avoid uncontrolled memory
consumption. Note that if the current file position of the `fsrc' object is not
0, only the contents from the current file position to the end of the file will
be copied.
@end deffn

@geindex copyfile() (dans le module shutil)
@anchor{library/shutil shutil copyfile}@anchor{a47}
@deffn {Fonction} shutil.copyfile (src, dst, *, follow_symlinks=True)

Copy the contents (no metadata) of the file named `src' to a file named
`dst' and return `dst' in the most efficient way possible.
`src' and `dst' are @ref{29d,,path-like objects} or path names given as strings.

`dst' doit être le nom complet du fichier cible ; consultez @ref{a48,,copy()} pour une fonction de copie qui accepte un chemin de répertoire cible. Si `src' et `dst' spécifient le même fichier, lève @ref{f88,,SameFileError}.

La cible doit être accessible en écriture, sinon l'exception @ref{40d,,OSError} est levée. Si `dst' existe déjà, il est remplacé. Les fichiers spéciaux comme les périphériques caractères ou bloc ainsi que les tubes (`pipes') ne peuvent pas être copiés avec cette fonction.

Si `follow_symlinks' est faux et `src' est un lien symbolique, un nouveau lien symbolique est créé au lieu de copier le fichier pointé par `src'.

Lève un @ref{1848,,événement d’audit} @code{shutil.copyfile} avec les arguments @code{src}, @code{dst}.


Modifié dans la version 3.3: @ref{103b,,IOError} était levée au lieu de @ref{40d,,OSError}. Ajout de l'argument `follow_symlinks'. Maintenant renvoie `dst'.



Modifié dans la version 3.4: Lève @ref{f88,,SameFileError} au lieu de @ref{f87,,Error}. Puisque la première est une sous-classe de la seconde, le changement assure la rétrocompatibilité.



Modifié dans la version 3.8: Les appels système de copie rapide spécifiques à la plate-forme peuvent être utilisés en interne afin de copier le fichier plus efficacement. Voir la section @ref{a4c,,Platform-dependent efficient copy operations}.

@end deffn

@geindex SameFileError
@anchor{library/shutil shutil SameFileError}@anchor{f88}
@deffn {Exception} shutil.SameFileError

Cette exception est levée si la source et la destination dans @ref{a47,,copyfile()} sont le même fichier.


Ajouté dans la version 3.4.

@end deffn

@geindex copymode() (dans le module shutil)
@anchor{library/shutil shutil copymode}@anchor{1634}
@deffn {Fonction} shutil.copymode (src, dst, *, follow_symlinks=True)

Copy the permission bits from `src' to `dst'.  The file contents, owner, and
group are unaffected.  `src' and `dst' are @ref{29d,,path-like objects} or path names
given as strings.
If `follow_symlinks' is false, and both `src' and `dst' are symbolic links,
@ref{1634,,copymode()} will attempt to modify the mode of `dst' itself (rather
than the file it points to).  This functionality is not available on every
platform; please see @ref{110e,,copystat()} for more information.  If
@ref{1634,,copymode()} cannot modify symbolic links on the local platform, and it
is asked to do so, it will do nothing and return.

Lève un @ref{1848,,événement d’audit} @code{shutil.copymode} avec les arguments @code{src}, @code{dst}.


Modifié dans la version 3.3: L'argument `follow_symlinks' a été ajouté.

@end deffn

@geindex copystat() (dans le module shutil)
@anchor{library/shutil shutil copystat}@anchor{110e}
@deffn {Fonction} shutil.copystat (src, dst, *, follow_symlinks=True)

Copy the permission bits, last access time, last modification time, and
flags from `src' to `dst'.  On Linux, @ref{110e,,copystat()} also copies the
"extended attributes" where possible.  The file contents, owner, and
group are unaffected.  `src' and `dst' are @ref{29d,,path-like objects} or path
names given as strings.

Si `follow_symlinks' est faux et `src' et `dst' représentent des liens symboliques, @ref{110e,,copystat()} agit sur les liens symboliques au lieu des fichiers cibles — elle lit les informations du lien symbolique de `src' et les écrit vers la destination pointée par `dst'.

@cartouche
@quotation Note 
Toutes les plateformes n'offrent pas la possibilité d'examiner et modifier les liens symboliques. Python peut vous informer des fonctionnalités effectivement disponibles.


@itemize *

@item 
Si @code{os.chmod in os.supports_follow_symlinks} est @code{True}, @ref{110e,,copystat()} peut modifier les octets de droits d'accès du lien symbolique.

@item 
If @code{os.utime in os.supports_follow_symlinks} is
@code{True}, @ref{110e,,copystat()} can modify the last access
and modification times of a symbolic link.

@item 
If @code{os.chflags in os.supports_follow_symlinks} is
@code{True}, @ref{110e,,copystat()} can modify the flags of
a symbolic link.  (@code{os.chflags} is not available on
all platforms.)
@end itemize

On platforms where some or all of this functionality
is unavailable, when asked to modify a symbolic link,
@ref{110e,,copystat()} will copy everything it can.
@ref{110e,,copystat()} never returns failure.

Please see @ref{27e7,,os.supports_follow_symlinks}
for more information.
@end quotation
@end cartouche

Raises an @ref{1848,,auditing event} @code{shutil.copystat} with arguments @code{src}, @code{dst}.


Modifié dans la version 3.3: Added `follow_symlinks' argument and support for Linux extended attributes.

@end deffn

@geindex copy() (dans le module shutil)
@anchor{library/shutil shutil copy}@anchor{a48}
@deffn {Fonction} shutil.copy (src, dst, *, follow_symlinks=True)

Copies the file `src' to the file or directory `dst'.  `src' and `dst'
should be @ref{29d,,path-like objects} or strings.  If
`dst' specifies a directory, the file will be copied into `dst' using the
base filename from `src'. If `dst' specifies a file that already exists,
it will be replaced. Returns the path to the newly created file.

If `follow_symlinks' is false, and `src' is a symbolic link,
`dst' will be created as a symbolic link.  If `follow_symlinks'
is true and `src' is a symbolic link, `dst' will be a copy of
the file `src' refers to.

@ref{a48,,copy()} copies the file data and the file's permission
mode (see @ref{218,,os.chmod()}).  Other metadata, like the
file's creation and modification times, is not preserved.
To preserve all file metadata from the original, use
@ref{a49,,copy2()} instead.

Lève un @ref{1848,,événement d’audit} @code{shutil.copyfile} avec les arguments @code{src}, @code{dst}.

Lève un @ref{1848,,événement d’audit} @code{shutil.copymode} avec les arguments @code{src}, @code{dst}.


Modifié dans la version 3.3: Added `follow_symlinks' argument.
Now returns path to the newly created file.



Modifié dans la version 3.8: Les appels système de copie rapide spécifiques à la plate-forme peuvent être utilisés en interne afin de copier le fichier plus efficacement. Voir la section @ref{a4c,,Platform-dependent efficient copy operations}.

@end deffn

@geindex copy2() (dans le module shutil)
@anchor{library/shutil shutil copy2}@anchor{a49}
@deffn {Fonction} shutil.copy2 (src, dst, *, follow_symlinks=True)

Identical to @ref{a48,,copy()} except that @ref{a49,,copy2()}
also attempts to preserve file metadata.

When `follow_symlinks' is false, and `src' is a symbolic
link, @ref{a49,,copy2()} attempts to copy all metadata from the
`src' symbolic link to the newly created `dst' symbolic link.
However, this functionality is not available on all platforms.
On platforms where some or all of this functionality is
unavailable, @ref{a49,,copy2()} will preserve all the metadata
it can; @ref{a49,,copy2()} never raises an exception because it
cannot preserve file metadata.

@ref{a49,,copy2()} uses @ref{110e,,copystat()} to copy the file metadata.
Please see @ref{110e,,copystat()} for more information
about platform support for modifying symbolic link metadata.

Lève un @ref{1848,,événement d’audit} @code{shutil.copyfile} avec les arguments @code{src}, @code{dst}.

Raises an @ref{1848,,auditing event} @code{shutil.copystat} with arguments @code{src}, @code{dst}.


Modifié dans la version 3.3: Added `follow_symlinks' argument, try to copy extended
file system attributes too (currently Linux only).
Now returns path to the newly created file.



Modifié dans la version 3.8: Les appels système de copie rapide spécifiques à la plate-forme peuvent être utilisés en interne afin de copier le fichier plus efficacement. Voir la section @ref{a4c,,Platform-dependent efficient copy operations}.

@end deffn

@geindex ignore_patterns() (dans le module shutil)
@anchor{library/shutil shutil ignore_patterns}@anchor{27e8}
@deffn {Fonction} shutil.ignore_patterns (*patterns)

This factory function creates a function that can be used as a callable for
@ref{a17,,copytree()}'s `ignore' argument, ignoring files and directories that
match one of the glob-style `patterns' provided.  See the example below.
@end deffn

@geindex copytree() (dans le module shutil)
@anchor{library/shutil shutil copytree}@anchor{a17}
@deffn {Fonction} shutil.copytree (src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Recursively copy an entire directory tree rooted at `src' to a directory
named `dst' and return the destination directory.  All intermediate
directories needed to contain `dst' will also be created by default.

Permissions and times of directories are copied with @ref{110e,,copystat()},
individual files are copied using @ref{a49,,copy2()}.

If `symlinks' is true, symbolic links in the source tree are represented as
symbolic links in the new tree and the metadata of the original links will
be copied as far as the platform allows; if false or omitted, the contents
and metadata of the linked files are copied to the new tree.

When `symlinks' is false, if the file pointed to by the symlink doesn't
exist, an exception will be added in the list of errors raised in
an @ref{f87,,Error} exception at the end of the copy process.
You can set the optional `ignore_dangling_symlinks' flag to true if you
want to silence this exception. Notice that this option has no effect
on platforms that don't support @ref{10d5,,os.symlink()}.

If `ignore' is given, it must be a callable that will receive as its
arguments the directory being visited by @ref{a17,,copytree()}, and a list of its
contents, as returned by @ref{10da,,os.listdir()}.  Since @ref{a17,,copytree()} is
called recursively, the `ignore' callable will be called once for each
directory that is copied.  The callable must return a sequence of directory
and file names relative to the current directory (i.e. a subset of the items
in its second argument); these names will then be ignored in the copy
process.  @ref{27e8,,ignore_patterns()} can be used to create such a callable that
ignores names based on glob-style patterns.

If exception(s) occur, an @ref{f87,,Error} is raised with a list of reasons.

If `copy_function' is given, it must be a callable that will be used to copy
each file. It will be called with the source path and the destination path
as arguments. By default, @ref{a49,,copy2()} is used, but any function
that supports the same signature (like @ref{a48,,copy()}) can be used.

If `dirs_exist_ok' is false (the default) and `dst' already exists, a
@ref{1009,,FileExistsError} is raised. If `dirs_exist_ok' is true, the copying
operation will continue if it encounters existing directories, and files
within the `dst' tree will be overwritten by corresponding files from the
`src' tree.

Raises an @ref{1848,,auditing event} @code{shutil.copytree} with arguments @code{src}, @code{dst}.


Modifié dans la version 3.2: Added the `copy_function' argument to be able to provide a custom copy
function.
Added the `ignore_dangling_symlinks' argument to silence dangling symlinks
errors when `symlinks' is false.



Modifié dans la version 3.3: Copy metadata when `symlinks' is false.
Now returns `dst'.



Modifié dans la version 3.8: Les appels système de copie rapide spécifiques à la plate-forme peuvent être utilisés en interne afin de copier le fichier plus efficacement. Voir la section @ref{a4c,,Platform-dependent efficient copy operations}.



Modifié dans la version 3.8: Added the `dirs_exist_ok' parameter.

@end deffn

@geindex rmtree() (dans le module shutil)
@anchor{library/shutil shutil rmtree}@anchor{2f5}
@deffn {Fonction} shutil.rmtree (path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

@geindex directory;deleting

Delete an entire directory tree; `path' must point to a directory (but not a
symbolic link to a directory).  If `ignore_errors' is true, errors resulting
from failed removals will be ignored; if false or omitted, such errors are
handled by calling a handler specified by `onexc' or `onerror' or, if both
are omitted, exceptions are propagated to the caller.

Cette fonction prend en charge @ref{10cb,,des chemins relatifs à des descripteurs de répertories}.

@cartouche
@quotation Note 
On platforms that support the necessary fd-based functions a symlink
attack resistant version of @ref{2f5,,rmtree()} is used by default.  On other
platforms, the @ref{2f5,,rmtree()} implementation is susceptible to a symlink
attack: given proper timing and circumstances, attackers can manipulate
symlinks on the filesystem to delete files they wouldn't be able to access
otherwise.  Applications can use the @ref{27e9,,rmtree.avoids_symlink_attacks}
function attribute to determine which case applies.
@end quotation
@end cartouche

If `onexc' is provided, it must be a callable that accepts three parameters:
`function', `path', and `excinfo'.

The first parameter, `function', is the function which raised the exception;
it depends on the platform and implementation.  The second parameter,
`path', will be the path name passed to `function'.  The third parameter,
`excinfo', is the exception that was raised. Exceptions raised by `onexc'
will not be caught.

The deprecated `onerror' is similar to `onexc', except that the third
parameter it receives is the tuple returned from @ref{675,,sys.exc_info()}.

Raises an @ref{1848,,auditing event} @code{shutil.rmtree} with arguments @code{path}, @code{dir_fd}.


Modifié dans la version 3.3: Added a symlink attack resistant version that is used automatically
if platform supports fd-based functions.



Modifié dans la version 3.8: On Windows, will no longer delete the contents of a directory junction
before removing the junction.



Modifié dans la version 3.11: Added the `dir_fd' parameter.



Modifié dans la version 3.12: Added the `onexc' parameter, deprecated `onerror'.



Modifié dans la version 3.13: @code{rmtree()} now ignores @ref{eae,,FileNotFoundError} exceptions for all
but the top-level path.
Exceptions other than @ref{40d,,OSError} and subclasses of @code{OSError}
are now always propagated to the caller.


@geindex avoids_symlink_attacks (attribut shutil.rmtree)
@anchor{library/shutil shutil rmtree avoids_symlink_attacks}@anchor{27e9}
@deffn {Attribut} rmtree.avoids_symlink_attacks

Indicates whether the current platform and implementation provides a
symlink attack resistant version of @ref{2f5,,rmtree()}.  Currently this is
only true for platforms supporting fd-based directory access functions.


Ajouté dans la version 3.3.

@end deffn
@end deffn

@geindex move() (dans le module shutil)
@anchor{library/shutil shutil move}@anchor{a4a}
@deffn {Fonction} shutil.move (src, dst, copy_function=copy2)

Recursively move a file or directory (`src') to another location and return
the destination.

If `dst' is an existing directory or a symlink to a directory, then `src'
is moved inside that directory. The destination path in that directory must
not already exist.

If `dst' already exists but is not a directory, it may be overwritten
depending on @ref{10d2,,os.rename()} semantics.

If the destination is on the current filesystem, then @ref{10d2,,os.rename()} is
used. Otherwise, `src' is copied to the destination using `copy_function'
and then removed.  In case of symlinks, a new symlink pointing to the target
of `src' will be created as the destination and `src' will be removed.

If `copy_function' is given, it must be a callable that takes two arguments,
`src' and the destination, and will be used to copy `src' to the destination
if @ref{10d2,,os.rename()} cannot be used.  If the source is a directory,
@ref{a17,,copytree()} is called, passing it the `copy_function'. The
default `copy_function' is @ref{a49,,copy2()}.  Using @ref{a48,,copy()} as the
`copy_function' allows the move to succeed when it is not possible to also
copy the metadata, at the expense of not copying any of the metadata.

Raises an @ref{1848,,auditing event} @code{shutil.move} with arguments @code{src}, @code{dst}.


Modifié dans la version 3.3: Added explicit symlink handling for foreign filesystems, thus adapting
it to the behavior of GNU's @code{mv}.
Now returns `dst'.



Modifié dans la version 3.5: Added the `copy_function' keyword argument.



Modifié dans la version 3.8: Les appels système de copie rapide spécifiques à la plate-forme peuvent être utilisés en interne afin de copier le fichier plus efficacement. Voir la section @ref{a4c,,Platform-dependent efficient copy operations}.



Modifié dans la version 3.9: Accepts a @ref{29d,,path-like object} for both `src' and `dst'.

@end deffn

@geindex disk_usage() (dans le module shutil)
@anchor{library/shutil shutil disk_usage}@anchor{110d}
@deffn {Fonction} shutil.disk_usage (path)

Return disk usage statistics about the given path as a @ref{639,,named tuple}
with the attributes `total', `used' and `free', which are the amount of
total, used and free space, in bytes. `path' may be a file or a
directory.

@cartouche
@quotation Note 
On Unix filesystems, `path' must point to a path within a `mounted'
filesystem partition. On those platforms, CPython doesn't attempt to
retrieve disk usage information from non-mounted filesystems.
@end quotation
@end cartouche


Ajouté dans la version 3.3.



Modifié dans la version 3.8: On Windows, `path' can now be a file or directory.


@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex chown() (dans le module shutil)
@anchor{library/shutil shutil chown}@anchor{23d}
@deffn {Fonction} shutil.chown (path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)

Change owner `user' and/or `group' of the given `path'.

`user' can be a system user name or a uid; the same applies to `group'. At
least one argument is required.

See also @ref{10cf,,os.chown()}, the underlying function.

Raises an @ref{1848,,auditing event} @code{shutil.chown} with arguments @code{path}, @code{user}, @code{group}.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.



Modifié dans la version 3.13: Added `dir_fd' and `follow_symlinks' parameters.

@end deffn

@geindex which() (dans le module shutil)
@anchor{library/shutil shutil which}@anchor{49d}
@deffn {Fonction} shutil.which (cmd, mode=os.F_OK | os.X_OK, path=None)

Return the path to an executable which would be run if the given `cmd' was
called.  If no `cmd' would be called, return @code{None}.

`mode' is a permission mask passed to @ref{10cd,,os.access()}, by default
determining if the file exists and is executable.

`path' is a "@code{PATH} string" specifying the directories to look in,
delimited by @ref{1cd0,,os.pathsep}. When no `path' is specified, the
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment variable is read from @ref{1197,,os.environ},
falling back to @ref{1990,,os.defpath} if it is not set.

On Windows, the current directory is prepended to the `path' if `mode' does
not include @code{os.X_OK}. When the `mode' does include @code{os.X_OK}, the
Windows API @code{NeedCurrentDirectoryForExePathW} will be consulted to
determine if the current directory should be prepended to `path'. To avoid
consulting the current working directory for executables: set the environment
variable @code{NoDefaultCurrentDirectoryInExePath}.

Also on Windows, the 
@geindex PATHEXT
@geindex variable d'environnement; PATHEXT
@code{PATHEXT} environment variable is used to
resolve commands that may not already include an extension. For example,
if you call @code{shutil.which("python")}, @ref{49d,,which()} will search @code{PATHEXT}
to know that it should look for @code{python.exe} within the `path'
directories. For example, on Windows:

@example
>>> shutil.which("python")
'C:\\Python33\\python.EXE'
@end example

This is also applied when `cmd' is a path that contains a directory
component:

@example
>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'
@end example


Ajouté dans la version 3.3.



Modifié dans la version 3.8: The @ref{1bd,,bytes} type is now accepted.  If `cmd' type is
@ref{1bd,,bytes}, the result type is also @ref{1bd,,bytes}.



Modifié dans la version 3.12: On Windows, the current directory is no longer prepended to the search
path if `mode' includes @code{os.X_OK} and WinAPI
@code{NeedCurrentDirectoryForExePathW(cmd)} is false, else the current
directory is prepended even if it is already in the search path;
@code{PATHEXT} is used now even when `cmd' includes a directory component
or ends with an extension that is in @code{PATHEXT}; and filenames that
have no extension can now be found.

@end deffn

@geindex Error
@anchor{library/shutil shutil Error}@anchor{f87}
@deffn {Exception} shutil.Error

This exception collects exceptions that are raised during a multi-file
operation. For @ref{a17,,copytree()}, the exception argument is a list of 3-tuples
(`srcname', `dstname', `exception').
@end deffn

@menu
* Platform-dependent efficient copy operations:: 
* copytree example:: 
* rmtree example:: 

@end menu

@node Platform-dependent efficient copy operations,copytree example,,Opérations sur les répertoires et les fichiers
@anchor{library/shutil platform-dependent-efficient-copy-operations}@anchor{27ea}@anchor{library/shutil shutil-platform-dependent-efficient-copy-operations}@anchor{a4c}
@subsubsection Platform-dependent efficient copy operations


Starting from Python 3.8, all functions involving a file copy
(@ref{a47,,copyfile()}, @ref{a48,,copy()}, @ref{a49,,copy2()},
@ref{a17,,copytree()}, and @ref{a4a,,move()}) may use
platform-specific "fast-copy" syscalls in order to copy the file more
efficiently (see bpo-33671@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33671}).
"fast-copy" means that the copying operation occurs within the kernel, avoiding
the use of userspace buffers in Python as in "@code{outfd.write(infd.read())}".

On macOS fcopyfile@footnote{http://www.manpagez.com/man/3/copyfile/} is used to copy the file content (not metadata).

On Linux @ref{afd,,os.sendfile()} is used.

On Windows @ref{a47,,shutil.copyfile()} uses a bigger default buffer size (1 MiB
instead of 64 KiB) and a @ref{452,,memoryview()}-based variant of
@ref{a4b,,shutil.copyfileobj()} is used.

If the fast-copy operation fails and no data was written in the destination
file then shutil will silently fallback on using less efficient
@ref{a4b,,copyfileobj()} function internally.


Modifié dans la version 3.8.


@node copytree example,rmtree example,Platform-dependent efficient copy operations,Opérations sur les répertoires et les fichiers
@anchor{library/shutil copytree-example}@anchor{27eb}@anchor{library/shutil shutil-copytree-example}@anchor{27ec}
@subsubsection copytree example


An example that uses the @ref{27e8,,ignore_patterns()} helper:

@example
from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))
@end example

This will copy everything except @code{.pyc} files and files or directories whose
name starts with @code{tmp}.

Another example that uses the `ignore' argument to add a logging call:

@example
from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)
@end example

@node rmtree example,,copytree example,Opérations sur les répertoires et les fichiers
@anchor{library/shutil rmtree-example}@anchor{27ed}@anchor{library/shutil shutil-rmtree-example}@anchor{27ee}
@subsubsection rmtree example


This example shows how to remove a directory tree on Windows where some
of the files have their read-only bit set. It uses the onexc callback
to clear the readonly bit and reattempt the remove. Any subsequent failure
will propagate.

@example
import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onexc=remove_readonly)
@end example

@node Archiving operations,Querying the size of the output terminal,Opérations sur les répertoires et les fichiers,shutil --- High-level file operations
@anchor{library/shutil archiving-operations}@anchor{11f6}@anchor{library/shutil id1}@anchor{27ef}
@subsubsection Archiving operations



Ajouté dans la version 3.2.



Modifié dans la version 3.5: Added support for the `xztar' format.


High-level utilities to create and read compressed and archived files are also
provided.  They rely on the @ref{130,,zipfile} and @ref{dd,,tarfile} modules.

@geindex make_archive() (dans le module shutil)
@anchor{library/shutil shutil make_archive}@anchor{49c}
@deffn {Fonction} shutil.make_archive (base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

Create an archive file (such as zip or tar) and return its name.

`base_name' is the name of the file to create, including the path, minus
any format-specific extension.

`format' is the archive format: one of
"zip" (if the @ref{132,,zlib} module is available), "tar", "gztar" (if the
@ref{132,,zlib} module is available), "bztar" (if the @ref{13,,bz2} module is
available), or "xztar" (if the @ref{89,,lzma} module is available).

`root_dir' is a directory that will be the root directory of the
archive, all paths in the archive will be relative to it; for example,
we typically chdir into `root_dir' before creating the archive.

`base_dir' is the directory where we start archiving from;
i.e. `base_dir' will be the common prefix of all files and
directories in the archive.  `base_dir' must be given relative
to `root_dir'.  See @ref{27f0,,Archiving example with base_dir} for how to
use `base_dir' and `root_dir' together.

`root_dir' and `base_dir' both default to the current directory.

If `dry_run' is true, no archive is created, but the operations that would be
executed are logged to `logger'.

`owner' and `group' are used when creating a tar archive. By default,
uses the current owner and group.

`logger' must be an object compatible with 
@geindex Python Enhancement Proposals; PEP 282
PEP 282@footnote{https://peps.python.org/pep-0282/}, usually an instance of
@ref{b3d,,logging.Logger}.

The `verbose' argument is unused and deprecated.

Raises an @ref{1848,,auditing event} @code{shutil.make_archive} with arguments @code{base_name}, @code{format}, @code{root_dir}, @code{base_dir}.

@cartouche
@quotation Note 
This function is not thread-safe when custom archivers registered
with @ref{27f1,,register_archive_format()} do not support the `root_dir'
argument.  In this case it
temporarily changes the current working directory of the process
to `root_dir' to perform archiving.
@end quotation
@end cartouche


Modifié dans la version 3.8: The modern pax (POSIX.1-2001) format is now used instead of
the legacy GNU format for archives created with @code{format="tar"}.



Modifié dans la version 3.10.6: This function is now made thread-safe during creation of standard
@code{.zip} and tar archives.

@end deffn

@geindex get_archive_formats() (dans le module shutil)
@anchor{library/shutil shutil get_archive_formats}@anchor{27f2}
@deffn {Fonction} shutil.get_archive_formats ()

Return a list of supported formats for archiving.
Each element of the returned sequence is a tuple @code{(name, description)}.

By default @ref{c4,,shutil} provides these formats:


@itemize -

@item 
`zip': ZIP file (if the @ref{132,,zlib} module is available).

@item 
`tar': Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives.

@item 
`gztar': gzip'ed tar-file (if the @ref{132,,zlib} module is available).

@item 
`bztar': bzip2'ed tar-file (if the @ref{13,,bz2} module is available).

@item 
`xztar': xz'ed tar-file (if the @ref{89,,lzma} module is available).
@end itemize

You can register new formats or provide your own archiver for any existing
formats, by using @ref{27f1,,register_archive_format()}.
@end deffn

@geindex register_archive_format() (dans le module shutil)
@anchor{library/shutil shutil register_archive_format}@anchor{27f1}
@deffn {Fonction} shutil.register_archive_format (name, function[, extra_args[, description]])

Register an archiver for the format `name'.

`function' is the callable that will be used to unpack archives. The callable
will receive the `base_name' of the file to create, followed by the
`base_dir' (which defaults to @ref{275d,,os.curdir}) to start archiving from.
Further arguments are passed as keyword arguments: `owner', `group',
`dry_run' and `logger' (as passed in @ref{49c,,make_archive()}).

If `function' has the custom attribute @code{function.supports_root_dir} set to @code{True},
the `root_dir' argument is passed as a keyword argument.
Otherwise the current working directory of the process is temporarily
changed to `root_dir' before calling `function'.
In this case @ref{49c,,make_archive()} is not thread-safe.

If given, `extra_args' is a sequence of @code{(name, value)} pairs that will be
used as extra keywords arguments when the archiver callable is used.

`description' is used by @ref{27f2,,get_archive_formats()} which returns the
list of archivers.  Defaults to an empty string.


Modifié dans la version 3.12: Added support for functions supporting the `root_dir' argument.

@end deffn

@geindex unregister_archive_format() (dans le module shutil)
@anchor{library/shutil shutil unregister_archive_format}@anchor{27f3}
@deffn {Fonction} shutil.unregister_archive_format (name)

Remove the archive format `name' from the list of supported formats.
@end deffn

@geindex unpack_archive() (dans le module shutil)
@anchor{library/shutil shutil unpack_archive}@anchor{455}
@deffn {Fonction} shutil.unpack_archive (filename[, extract_dir[, format[, filter]]])

Unpack an archive. `filename' is the full path of the archive.

`extract_dir' is the name of the target directory where the archive is
unpacked. If not provided, the current working directory is used.

`format' is the archive format: one of "zip", "tar", "gztar", "bztar", or
"xztar".  Or any other format registered with
@ref{27f4,,register_unpack_format()}.  If not provided, @ref{455,,unpack_archive()}
will use the archive file name extension and see if an unpacker was
registered for that extension.  In case none is found,
a @ref{1ff,,ValueError} is raised.

The keyword-only `filter' argument is passed to the underlying unpacking
function. For zip files, `filter' is not accepted.
For tar files, it is recommended to set it to @code{'data'},
unless using features specific to tar and UNIX-like filesystems.
(See @ref{456,,Extraction filters} for details.)
The @code{'data'} filter will become the default for tar files
in Python 3.14.

Raises an @ref{1848,,auditing event} @code{shutil.unpack_archive} with arguments @code{filename}, @code{extract_dir}, @code{format}.

@cartouche
@quotation Avertissement 
Never extract archives from untrusted sources without prior inspection.
It is possible that files are created outside of the path specified in
the `extract_dir' argument, e.g. members that have absolute filenames
starting with "/" or filenames with two dots "..".
@end quotation
@end cartouche


Modifié dans la version 3.7: Accepts a @ref{29d,,path-like object} for `filename' and `extract_dir'.



Modifié dans la version 3.12: Added the `filter' argument.

@end deffn

@geindex register_unpack_format() (dans le module shutil)
@anchor{library/shutil shutil register_unpack_format}@anchor{27f4}
@deffn {Fonction} shutil.register_unpack_format (name, extensions, function[, extra_args[, description]])

Registers an unpack format. `name' is the name of the format and
`extensions' is a list of extensions corresponding to the format, like
@code{.zip} for Zip files.

`function' is the callable that will be used to unpack archives. The
callable will receive:


@itemize -

@item 
the path of the archive, as a positional argument;

@item 
the directory the archive must be extracted to, as a positional argument;

@item 
possibly a `filter' keyword argument, if it was given to
@ref{455,,unpack_archive()};

@item 
additional keyword arguments, specified by `extra_args' as a sequence
of @code{(name, value)} tuples.
@end itemize

`description' can be provided to describe the format, and will be returned
by the @ref{27f5,,get_unpack_formats()} function.
@end deffn

@geindex unregister_unpack_format() (dans le module shutil)
@anchor{library/shutil shutil unregister_unpack_format}@anchor{27f6}
@deffn {Fonction} shutil.unregister_unpack_format (name)

Unregister an unpack format. `name' is the name of the format.
@end deffn

@geindex get_unpack_formats() (dans le module shutil)
@anchor{library/shutil shutil get_unpack_formats}@anchor{27f5}
@deffn {Fonction} shutil.get_unpack_formats ()

Return a list of all registered formats for unpacking.
Each element of the returned sequence is a tuple
@code{(name, extensions, description)}.

By default @ref{c4,,shutil} provides these formats:


@itemize -

@item 
`zip': ZIP file (unpacking compressed files works only if the corresponding
module is available).

@item 
`tar': uncompressed tar file.

@item 
`gztar': gzip'ed tar-file (if the @ref{132,,zlib} module is available).

@item 
`bztar': bzip2'ed tar-file (if the @ref{13,,bz2} module is available).

@item 
`xztar': xz'ed tar-file (if the @ref{89,,lzma} module is available).
@end itemize

You can register new formats or provide your own unpacker for any existing
formats, by using @ref{27f4,,register_unpack_format()}.
@end deffn

@menu
* Archiving example:: 
* Archiving example with base_dir:: 

@end menu

@node Archiving example,Archiving example with base_dir,,Archiving operations
@anchor{library/shutil archiving-example}@anchor{27f7}@anchor{library/shutil shutil-archiving-example}@anchor{27f8}
@subsubsection Archiving example


In this example, we create a gzip'ed tar-file archive containing all files
found in the @code{.ssh} directory of the user:

@example
>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'
@end example

The resulting archive contains:

@example
$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts
@end example

@node Archiving example with base_dir,,Archiving example,Archiving operations
@anchor{library/shutil archiving-example-with-base-dir}@anchor{27f9}@anchor{library/shutil shutil-archiving-example-with-basedir}@anchor{27f0}
@subsubsection Archiving example with `base_dir'


In this example, similar to the @ref{27f8,,one above},
we show how to use @ref{49c,,make_archive()}, but this time with the usage of
`base_dir'.  We now have the following directory structure:

@example
$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt
@end example

In the final archive, @code{please_add.txt} should be included, but
@code{do_not_add.txt} should not.  Therefore we use the following:

@example
>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'
@end example

Listing the files in the resulting archive gives us:

@example
$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt
@end example

@node Querying the size of the output terminal,,Archiving operations,shutil --- High-level file operations
@anchor{library/shutil querying-the-size-of-the-output-terminal}@anchor{27fa}
@subsubsection Querying the size of the output terminal


@geindex get_terminal_size() (dans le module shutil)
@anchor{library/shutil shutil get_terminal_size}@anchor{10e3}
@deffn {Fonction} shutil.get_terminal_size (fallback=(columns, lines))

Get the size of the terminal window.

For each of the two dimensions, the environment variable, @code{COLUMNS}
and @code{LINES} respectively, is checked. If the variable is defined and
the value is a positive integer, it is used.

When @code{COLUMNS} or @code{LINES} is not defined, which is the common case,
the terminal connected to @ref{27fb,,sys.__stdout__} is queried
by invoking @ref{10e2,,os.get_terminal_size()}.

If the terminal size cannot be successfully queried, either because
the system doesn't support querying, or because we are not
connected to a terminal, the value given in @code{fallback} parameter
is used. @code{fallback} defaults to @code{(80, 24)} which is the default
size used by many terminal emulators.

The value returned is a named tuple of type @ref{27fc,,os.terminal_size}.

See also: The Single UNIX Specification, Version 2,
Other Environment Variables@footnote{https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003}.


Ajouté dans la version 3.3.



Modifié dans la version 3.11: The @code{fallback} values are also used if @ref{10e2,,os.get_terminal_size()}
returns zeroes.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{a0,,os}

Interfaces du système d'exploitation, incluant des fonctions pour travailler avec des fichiers dans un niveau plus bas que les @ref{11a0,,objets fichiers} de Python.

@item Module @ref{7e,,io}

Bibliothèque d'entrées/sorties native de Python, incluant des classes abstraites et concrètes tel que les I/O sur les fichiers.

@item Fonction native @ref{505,,open()}

Le moyen classique pour ouvrir des fichiers pour les lire ou y écrire avec Python.
@end table


@node Persistance des données,Compression de donnée et archivage,Accès aux Fichiers et aux Dossiers,La bibliothèque standard
@anchor{library/persistence doc}@anchor{27fd}@anchor{library/persistence data-persistence}@anchor{27fe}@anchor{library/persistence persistence}@anchor{27ff}
@section Persistance des données


Les modules décrits dans ce chapitre permettent de stocker des données Python de manière persistante typiquement sur disque.  Les modules @ref{a5,,pickle} et @ref{8c,,marshal} peuvent transformer n'importe quel type Python en une séquence d'octets, puis recréer les objets depuis ces octets. Les différents modules du paquet `dbm' gèrent une catégorie de formats de fichier basée sur des hach, stockant des correspondances entre chaînes de caractères.

La liste des modules documentés dans ce chapitre est :

@menu
* pickle: pickle --- Python object serialization. Python object serialization
* copyreg: copyreg --- Register pickle support functions. Register pickle support functions
* shelve: shelve --- Python object persistence. Python object persistence
* marshal: marshal --- Internal Python object serialization. Internal Python object serialization
* dbm: dbm --- Interfaces to Unix "databases". Interfaces to Unix "databases"
* sqlite3: sqlite3 --- DB-API 2 0 interface for SQLite databases. DB-API 2.0 interface for SQLite databases

@end menu

@node pickle --- Python object serialization,copyreg --- Register pickle support functions,,Persistance des données
@anchor{library/pickle doc}@anchor{2800}@anchor{library/pickle module-pickle}@anchor{a5}@anchor{library/pickle pickle-python-object-serialization}@anchor{2801}
@subsection @code{pickle} --- Python object serialization


@geindex module; pickle

`Code source :' Lib/pickle.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pickle.py}

@geindex persistence
@geindex persistent;objects
@geindex serializing;objects
@geindex marshalling;objects
@geindex flattening;objects
@geindex pickling;objects


__________________________________________________________________


Le module @ref{a5,,pickle} implémente des protocoles binaires de sérialisation et dé-sérialisation d'objets Python. La sérialisation est le procédé par lequel une hiérarchie d'objets Python est convertie en flux d'octets. La désérialisation est l'opération inverse, par laquelle un flux d'octets (à partir d'un @ref{1c15,,binary file} ou @ref{d1b,,bytes-like object}) est converti en hiérarchie d'objets. Sérialisation (et `désérialisation') sont aussi connus sous les termes de `pickling', de "`marshalling'" @footnote{
À ne pas confondre avec ce que fait le module @ref{8c,,marshal}.
} ou encore de "`flattening'".

@cartouche
@quotation Avertissement 
Le module @code{pickle} `n'est pas sécurisé'. Ne désérialisez des objets qu'à partir de sources fiables.

Il est possible de produire des données binaires qui `exécutent du code arbitraire lors de leur désérialisation'. Ne désérialisez jamais des données provenant d'une source non fiable, ou qui pourraient avoir été modifiées.

Pensez au module @ref{69,,hmac} pour signer des données afin de s'assurer qu'elles n'ont pas été modifiées.

Des formats de sérialisation plus sûrs, comme @ref{81,,json}, peuvent se révéler plus adaptés si vous travaillez sur des données qui ne sont pas fiables. Voir @ref{2802,,Comparaison avec json}.
@end quotation
@end cartouche

@menu
* Relations aux autres modules Python:: 
* Format du flux de données:: 
* Interface du module:: 
* Quels objets sont sérialisables ?:: 
* Sérialisation des instances d'une classe:: 
* Réduction personnalisée pour les types@comma{} fonctions et autres objets: Réduction personnalisée pour les types fonctions et autres objets. 
* Tampons hors-bande:: 
* Restriction des noms dans l'espace de nommage global:: 
* Performances: Performances<2>. 
* Exemples: Exemples<7>. 

@end menu

@node Relations aux autres modules Python,Format du flux de données,,pickle --- Python object serialization
@anchor{library/pickle relationship-to-other-python-modules}@anchor{2803}
@subsubsection Relations aux autres modules Python


@menu
* Comparaison avec marshal:: 
* Comparaison avec json:: 

@end menu

@node Comparaison avec marshal,Comparaison avec json,,Relations aux autres modules Python
@anchor{library/pickle comparison-with-marshal}@anchor{2804}
@subsubsection Comparaison avec @code{marshal}


Python possède un module de bas niveau en sérialisation appelé @ref{8c,,marshal}, mais en général il est préférable d'utiliser @ref{a5,,pickle} pour sérialiser des objets Python. @ref{8c,,marshal} existe principalement pour gérer les fichiers Python en @code{.pyc}.

Le module @ref{a5,,pickle} diffère du module @ref{8c,,marshal} sur plusieurs aspects :


@itemize *

@item 
Le module @ref{a5,,pickle} garde la trace des objets qu'il a déjà sérialisés, pour faire en sorte que les prochaines références à cet objet ne soient pas sérialisées à nouveau. @ref{8c,,marshal} ne le fait pas.

Ça a des implications sur les objets partagés et les objets récursifs. Les objets récursifs sont des objets qui contiennent des références à eux-mêmes. Ceux-ci ne sont pas gérées par marshal : lui donner un objet récursif va le faire planter. Un objet est partagé lorsque que plusieurs références pointent dessus, depuis différents endroits dans la hiérarchie sérialisée. Le module @ref{a5,,pickle} repère ces partages et ne stocke ces objets qu'une seule fois. Les objets partagés restent ainsi partagés, ce qui peut être très important pour les objets mutables.

@item 
@ref{8c,,marshal} ne peut être utilisé pour la sérialisation et l'instanciation de classes définies par les utilisateurs. @ref{a5,,pickle} peut sauvegarder et restaurer les instances de classes de manière transparente. Cependant la définition de classe doit être importable et lancée dans le même module et de la même manière que lors de son importation.

@item 
Aucune garantie n'est offerte sur la portabilité du format @ref{8c,,marshal} entre différentes versions de Python. Sa fonction première étant la gestion des fichiers @code{.pyc}, les développeurs se réservent le droit de changer le format de sérialisation de manière non-rétrocompatible si besoin était. Il est garanti que le format @ref{a5,,pickle} restera compatible avec les versions futures de Python, pourvu que vous choisissiez un protocole de sérialisation adapté. De plus, il masque les différences entre les types Python 2 et Python 3, pour le cas où il s'agit de désérialiser en Python 3 des données sérialisées en Python 2.
@end itemize

@node Comparaison avec json,,Comparaison avec marshal,Relations aux autres modules Python
@anchor{library/pickle comparison-with-json}@anchor{2802}@anchor{library/pickle id2}@anchor{2805}
@subsubsection Comparaison avec @code{json}


There are fundamental differences between the pickle protocols and
JSON (JavaScript Object Notation)@footnote{https://json.org}:


@itemize *

@item 
`pickle' est un format binaire, tandis que JSON est un format textuel (constitué de caractères Unicode et généralement encodé en UTF-8) ;

@item 
JSON peut être lu par une personne, contrairement à `pickle' ;

@item 
JSON offre l'interopérabilité avec de nombreux outils en dehors de l'écosystème Python, alors que `pickle' est propre à Python ;

@item 
Par défaut, JSON n'est capable de sérialiser qu'un nombre limité de types natifs Python, et ne prend pas en charge les classes définies par l'utilisateur. Le format `pickle' peut représenter une multitude de types d'objets, dont beaucoup automatiquement, grâce à une utilisation fine des possibilités d'introspection de Python ; on peut traiter les cas les plus complexes en implémentant des @ref{2806,,méthodes de sérialisation propres à une classe} ;

@item 
Contrairement à `pickle', la désérialisation de données JSON n'ouvre pas en soi une vulnérabilité à l'exécution de code arbitraire.
@end itemize


@subsubheading Voir aussi


Le module @ref{81,,json} de la bibliothèque standard permet la sérialisation et désérialisation au format JSON.


@node Format du flux de données,Interface du module,Relations aux autres modules Python,pickle --- Python object serialization
@anchor{library/pickle data-stream-format}@anchor{2807}@anchor{library/pickle pickle-protocols}@anchor{caf}
@subsubsection Format du flux de données


@geindex External Data Representation

The data format used by @ref{a5,,pickle} is Python-specific.  This has the
advantage that there are no restrictions imposed by external standards such as
JSON (which can't represent pointer sharing); however it means that
non-Python programs may not be able to reconstruct pickled Python objects.

Le format binaire @ref{a5,,pickle} est, par défaut, une représentation assez compacte des objets. Il est possible de @ref{2808,,compresser} efficacement les données sérialisées.

Le module @ref{a6,,pickletools} contient des outils servant à analyser les flux de données générés par @ref{a5,,pickle}. Le code source de @ref{a6,,pickletools} contient des commentaires détaillés sur les `opcodes' employés par les protocoles `pickle'.

Il existe actuellement 6 protocoles différents pour la sérialisation. Les protocoles portant les numéros les plus grands sont les derniers ajoutés, et nécessitent en conséquence des versions de Python plus récentes.


@itemize *

@item 
Le protocole 0 est le format originel, humainement lisible. Il est rétrocompatible avec les versions les plus anciennes de Python.

@item 
Le protocole 1 est un ancien format binaire, aussi compatible avec les versions anciennes.

@item 
Protocol version 2 was introduced in Python 2.3.  It provides much more
efficient pickling of @ref{2809,,new-style classes}.  Refer to 
@geindex Python Enhancement Proposals; PEP 307
PEP 307@footnote{https://peps.python.org/pep-0307/} for
information about improvements brought by protocol 2.

@item 
Le protocole 3 a été introduit en Python 3.0. Il gère les objets @ref{1bd,,bytes}, et ne permet pas la désérialisation par Python 2.x. Il fut le protocole par défaut de Python 3.0 à Python 3.7.

@item 
Le protocole 4 est apparu en Python 3.4. Il prend en charge les objets de très grande taille ainsi que la sérialisation d'une plus grande variété d'objets, et optimise le format. Il est le protocole par défaut depuis Python 3.8. Voir la 
@geindex Python Enhancement Proposals; PEP 3154
PEP 3154@footnote{https://peps.python.org/pep-3154/} pour plus d'informations sur les améliorations apportées par le protocole 4.

@item 
Le protocole 5 a été ajouté en Python 3.8 afin de permettre le transfert des données en marge de la sérialisation elle-même. Il a également accéléré les opérations sur les données à sérialiser. Reportez-vous à la 
@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} pour les détails relatifs aux améliorations apportées par le protocole 5.
@end itemize

@cartouche
@quotation Note 
La sérialisation est un problème plus simple que la persistance des données en général. Le module @ref{a5,,pickle} lit et écrit des objets fichiers-compatibles, mais ne s'occupe pas du problème de donner un nom à des objets persistants, ni de gérer l'accès par différents processus en parallèle à ces objets. @ref{a5,,pickle} se contente de transformer des objets complexes en flux d'octets, et lire ces flux d'octets par la suite pour reconstruire des objets avec la même structure. Si l'on peut bien sûr écrire les flux d'octets dans un fichier, rien n'empêche de les transférer à travers un réseau, ou bien de les stocker dans une base de données. Voir le module @ref{c2,,shelve} pour une interface simple qui sérialise et désérialise les objets dans des bases de données de style DBM.
@end quotation
@end cartouche

@node Interface du module,Quels objets sont sérialisables ?,Format du flux de données,pickle --- Python object serialization
@anchor{library/pickle module-interface}@anchor{280a}
@subsubsection Interface du module


Pour sérialiser un objet, contenant éventuellement d'autres objets, appelez tout simplement la fonction @ref{1456,,dumps()}. La fonction @ref{cff,,loads()}, quant à elle, désérialise un flux de données. Pour un contrôle plus fin des opérations de sérialisation ou désérialisation, créez un objet @ref{a0c,,Pickler} ou @ref{1630,,Unpickler}.

Le module @ref{a5,,pickle} définit les constantes suivantes :

@geindex HIGHEST_PROTOCOL (dans le module pickle)
@anchor{library/pickle pickle HIGHEST_PROTOCOL}@anchor{1457}
@deffn {Données} pickle.HIGHEST_PROTOCOL

Entier qui donne la version du @ref{caf,,protocole} le plus récent qui soit disponible. Ce nombre peut être passé comme paramètre `protocol' aux fonctions @ref{280b,,dump()} et @ref{1456,,dumps()} ainsi qu'au constructeur de la classe @ref{a0c,,Pickler}.
@end deffn

@geindex DEFAULT_PROTOCOL (dans le module pickle)
@anchor{library/pickle pickle DEFAULT_PROTOCOL}@anchor{818}
@deffn {Données} pickle.DEFAULT_PROTOCOL

Entier qui donne la version du @ref{caf,,protocole} employé par défaut pour la sérialisation. Il peut être moindre que @ref{1457,,HIGHEST_PROTOCOL}. La valeur actuelle est 4, sachant que le protocole correspondant a été introduit en Python 3.4 et n'est pas compatible avec les versions antérieures.


Modifié dans la version 3.0: Le protocole par défaut est devenu le protocole 3.



Modifié dans la version 3.8: Le protocole par défaut est devenu le protocole 4.

@end deffn

Le module @ref{a5,,pickle} contient quelques fonctions pour faciliter la sérialisation :

@geindex dump() (dans le module pickle)
@anchor{library/pickle pickle dump}@anchor{280b}
@deffn {Fonction} pickle.dump (obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)

Écrit la représentation sérialisée de l'objet `obj' dans l'@ref{11a0,,objet fichier-compatible} `file', qui doit être ouvert. Ceci est l'équivalent de @code{Pickle(file, protocol).dump(obj)}.

Les arguments `file', `protocol', `fix_imports' et `buffer_callback' sont identiques à ceux du constructeur de la classe @ref{a0c,,Pickler}.


Modifié dans la version 3.8: ajout de l'argument `buffer_callback'.

@end deffn

@geindex dumps() (dans le module pickle)
@anchor{library/pickle pickle dumps}@anchor{1456}
@deffn {Fonction} pickle.dumps (obj, protocol=None, *, fix_imports=True, buffer_callback=None)

Renvoie la représentation sérialisée de `obj' sous forme de @ref{1bd,,bytes}, au lieu de l'écrire dans un fichier.

Les arguments `protocol', `fix_imports' et `buffer_callback' sont identiques à ceux du constructeur de la classe @ref{a0c,,Pickler}.


Modifié dans la version 3.8: ajout de l'argument `buffer_callback'.

@end deffn

@geindex load() (dans le module pickle)
@anchor{library/pickle pickle load}@anchor{cfe}
@deffn {Fonction} pickle.load (file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Charge la représentation sérialisée d'un objet depuis l'@ref{11a0,,objet fichier-compatible} ouvert `file', et renvoie l'objet reconstitué obtenu. Ceci est l'équivalent de @code{Unpickler(file).load()}.

La version du protocole utilisée pour la sérialisation est détectée automatiquement, d'où l'absence d'un argument. Les octets situés après la représentation sérialisée de l'objet sont ignorés.

Les arguments `file', `fix_imports', `encoding', `errors', `strict' et `buffers' sont identiques à ceux du constructeur de la classe @ref{1630,,Unpickler}.


Modifié dans la version 3.8: Ajout de l'argument `buffers'.

@end deffn

@geindex loads() (dans le module pickle)
@anchor{library/pickle pickle loads}@anchor{cff}
@deffn {Fonction} pickle.loads (data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Renvoie l'objet reconstitué à partir de la représentation sérialisée `data', qui doit être fournie sous la forme d'un @ref{d1b,,bytes-like object}.

La version du protocole utilisée pour la sérialisation est détectée automatiquement, d'où l'absence d'un argument. Les octets situés après la représentation sérialisée de l'objet sont ignorés.

Arguments `fix_imports', `encoding', `errors', `strict' and `buffers'
have the same meaning as in the @ref{1630,,Unpickler} constructor.


Modifié dans la version 3.8: Ajout de l'argument `buffers'.

@end deffn

Le module @ref{a5,,pickle} définit trois types d'exceptions :

@geindex PickleError
@anchor{library/pickle pickle PickleError}@anchor{280c}
@deffn {Exception} pickle.PickleError

Common base class for the other pickling exceptions.  It inherits from
@ref{9c7,,Exception}.
@end deffn

@geindex PicklingError
@anchor{library/pickle pickle PicklingError}@anchor{280d}
@deffn {Exception} pickle.PicklingError

Error raised when an unpicklable object is encountered by @ref{a0c,,Pickler}.
It inherits from @ref{280c,,PickleError}.

Lisez @ref{280e,,Quels objets sont sérialisables ?} pour en savoir plus sur les types d'objets qui peuvent être sérialisés.
@end deffn

@geindex UnpicklingError
@anchor{library/pickle pickle UnpicklingError}@anchor{280f}
@deffn {Exception} pickle.UnpicklingError

Error raised when there is a problem unpickling an object, such as a data
corruption or a security violation.  It inherits from @ref{280c,,PickleError}.

Veuillez noter que d'autres exceptions peuvent être levées durant la désérialisation, comme @code{AttributeError}, @code{EOFError}, @code{ImportError} et @code{IndexError} (liste non-exhaustive).
@end deffn

Le module @ref{a5,,pickle} exporte trois classes : @ref{a0c,,Pickler}, @ref{1630,,Unpickler} et @ref{1786,,PickleBuffer} :

@geindex Pickler (classe dans pickle)
@anchor{library/pickle pickle Pickler}@anchor{a0c}
@deffn {Classe} pickle.Pickler (file, protocol=None, *, fix_imports=True, buffer_callback=None)

Classe d'objets qui implémentent la sérialisation vers un flux binaire.

L'argument optionnel `protocol' détermine la version du protocole de sérialisation à employer, entre 0 et @ref{1457,,HIGHEST_PROTOCOL}. La valeur par défaut est celle de @ref{818,,DEFAULT_PROTOCOL}. Avec un nombre strictement négatif, c'est @ref{1457,,HIGHEST_PROTOCOL} qui est utilisé.

L'argument `file' peut être un fichier sur disque ouvert en mode binaire pour l'écriture, une instance de la classe @ref{e8d,,io.BytesIO}, ou plus généralement un objet quelconque qui possède une méthode @code{write()} acceptant d'être appelée sur un argument unique de type @code{bytes}.

Si `fix_imports' est vrai et `protocol' est inférieur ou égal à 2, les noms des modules sont reliés par `pickle' aux anciens noms qui avaient cours en Python 2, afin que le flux sérialisé soit lisible aussi bien par Python 2 que Python 3.

If `buffer_callback' is @code{None} (the default), buffer views are
serialized into `file' as part of the pickle stream.

If `buffer_callback' is not @code{None}, then it can be called any number
of times with a buffer view.  If the callback returns a false value
(such as @code{None}), the given buffer is @ref{2810,,out-of-band};
otherwise the buffer is serialized in-band, i.e. inside the pickle stream.

It is an error if `buffer_callback' is not @code{None} and `protocol' is
@code{None} or smaller than 5.


Modifié dans la version 3.8: ajout de l'argument `buffer_callback'.


@geindex dump() (méthode pickle.Pickler)
@anchor{library/pickle pickle Pickler dump}@anchor{19d3}
@deffn {Méthode} dump (obj)

Écrit la représentation sérialisée de l'objet `obj' dans le fichier ouvert passé au constructeur.
@end deffn

@geindex persistent_id() (méthode pickle.Pickler)
@anchor{library/pickle pickle Pickler persistent_id}@anchor{1526}
@deffn {Méthode} persistent_id (obj)

Ne fait rien par défaut. Cette méthode est destinée à être implémentée par une classe fille.

Si @ref{1526,,persistent_id()} renvoie @code{None}, `obj' est sérialisé normalement. Toute autre valeur est reprise par le @ref{a0c,,Pickler} comme ID persistant pour `obj'. Le sens de cet ID persistant doit être défini par @ref{152e,,Unpickler.persistent_load()}. Veuillez noter que la valeur renvoyée par @ref{1526,,persistent_id()} ne peut pas porter elle-même d'ID persistant.

La section @ref{2811,,Persistance d'objets externes} donne des détails et exemples.


Modifié dans la version 3.13: Add the default implementation of this method in the C implementation
of @code{Pickler}.

@end deffn

@geindex dispatch_table (attribut pickle.Pickler)
@anchor{library/pickle pickle Pickler dispatch_table}@anchor{1102}
@deffn {Attribut} dispatch_table

A pickler object's dispatch table is a registry of `reduction
functions' of the kind which can be declared using
@ref{2812,,copyreg.pickle()}.  It is a mapping whose keys are classes
and whose values are reduction functions.  A reduction function
takes a single argument of the associated class and should
conform to the same interface as a @ref{9c1,,__reduce__()}
method.

Lorsqu'un sérialiseur ne possède pas l'attribut @ref{1102,,dispatch_table}, comme c'est le cas par défaut, il utilise le tableau global du module @ref{26,,copyreg}. Afin de personnaliser l'opération de sérialisation pour un sérialiseur particulier, on peut affecter à son attribut @ref{1102,,dispatch_table} un objet compatible avec les dictionnaires. Une autre possibilité est de définir l'attribut @ref{1102,,dispatch_table} dans une classe fille de @ref{a0c,,Pickler}. Sa valeur sera alors utilisée pour toutes les instances de cette classe fille.

Voir @ref{2813,,Tables de distribution} pour des exemples d'utilisation.


Ajouté dans la version 3.3.

@end deffn

@geindex reducer_override() (méthode pickle.Pickler)
@anchor{library/pickle pickle Pickler reducer_override}@anchor{a0d}
@deffn {Méthode} reducer_override (obj)

Special reducer that can be defined in @ref{a0c,,Pickler} subclasses. This
method has priority over any reducer in the @ref{1102,,dispatch_table}.  It
should conform to the same interface as a @ref{9c1,,__reduce__()} method, and
can optionally return @ref{7bc,,NotImplemented} to fallback on
@ref{1102,,dispatch_table}-registered reducers to pickle @code{obj}.

Voir @ref{2814,,Réduction personnalisée pour les types@comma{} fonctions et autres objets} pour un exemple détaillé.


Ajouté dans la version 3.8.

@end deffn

@geindex fast (attribut pickle.Pickler)
@anchor{library/pickle pickle Pickler fast}@anchor{2815}
@deffn {Attribut} fast

Cet attribut est obsolète. Une valeur vraie (« mode rapide ») désactive la mémorisation des objets au fur et à mesure de leur sérialisation, qui permet habituellement de représenter les doublons par une unique référence. Cette option accélère la sérialisation en évitant des `opcodes' PUT superflus. Elle ne doit pas être utilisée sur un objet contenant une référence à lui-même, car le @ref{a0c,,Pickler} entre alors dans une récursion infinie.

Utilisez plutôt @ref{2816,,pickletools.optimize()} pour obtenir des données sérialisées plus compactes.
@end deffn
@end deffn

@geindex Unpickler (classe dans pickle)
@anchor{library/pickle pickle Unpickler}@anchor{1630}
@deffn {Classe} pickle.Unpickler (file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)

Les objets de cette classe sont des désérialiseurs, qui lisent un flux de données pour le convertir en objet.

Il n'y a nul besoin d'argument `protocol'. La version du protocole avec lequel sont encodées les données est déterminée automatiquement.

L'argument `file' doit posséder trois méthodes qui proviennent de l'interface de @ref{67f,,io.BufferedIOBase}. Ce sont : @code{read()}, prenant un entier, @code{readinto()}, prenant un tampon, et @code{readline()}, sans arguments. `file' peut donc être aussi bien un fichier sur disque ouvert en mode lecture binaire qu'un objet @ref{e8d,,io.BytesIO}, ou un objet quelconque vérifiant ces critères.

Les paramètres facultatifs `fix_imports', `encoding' et `errors' sont dédiés à la compatibilité de la désérialisation avec les flux binaires générés par Python 2. Si `fix_imports' est vrai, `pickle' tente de modifier les anciens noms des modules que l'on trouve en Python 2, pour les remplacer par ceux en usage en Python 3. Les paramètres `encoding' et `errors' contrôlent la façon de décoder les chaînes de caractères 8 bits. Leurs valeurs par défaut respectives sont @code{'ASCII'} et @code{'strict'}. `encoding' peut être mis à @code{'bytes'} pour lire des chaînes d'octets en tant que `bytes'. Il doit être mis à @code{'latin1'} pour désérialiser des tableaux NumPy ou des instances de @ref{1c7,,datetime}, @ref{1c8,,date} et @ref{1c9,,time} sérialisées par Python 2.

If `buffers' is @code{None} (the default), then all data necessary for
deserialization must be contained in the pickle stream.  This means
that the `buffer_callback' argument was @code{None} when a @ref{a0c,,Pickler}
was instantiated (or when @ref{280b,,dump()} or @ref{1456,,dumps()} was called).

If `buffers' is not @code{None}, it should be an iterable of buffer-enabled
objects that is consumed each time the pickle stream references
an @ref{2810,,out-of-band} buffer view.  Such buffers have been
given in order to the `buffer_callback' of a Pickler object.


Modifié dans la version 3.8: Ajout de l'argument `buffers'.


@geindex load() (méthode pickle.Unpickler)
@anchor{library/pickle pickle Unpickler load}@anchor{2817}
@deffn {Méthode} load ()

Lit la représentation sérialisée d'un objet depuis le fichier ouvert passé au constructeur, et reconstitue l'objet qui y est stocké, avec tous les objets qu'il contient. Les octets situés au-delà de la fin de la représentation binaire sont ignorés.
@end deffn

@geindex persistent_load() (méthode pickle.Unpickler)
@anchor{library/pickle pickle Unpickler persistent_load}@anchor{152e}
@deffn {Méthode} persistent_load (pid)

Par défaut, cette méthode lève une exception @ref{280f,,UnpicklingError}.

Si elle est définie autrement dans une sous-classe, @ref{152e,,persistent_load()} doit renvoyer l'objet correspondant à l'ID persistant `pid'. Si celui-ci est invalide, elle doit lever une exception @ref{280f,,UnpicklingError}.

La section @ref{2811,,Persistance d'objets externes} donne des détails et exemples.


Modifié dans la version 3.13: Add the default implementation of this method in the C implementation
of @code{Unpickler}.

@end deffn

@geindex find_class() (méthode pickle.Unpickler)
@anchor{library/pickle pickle Unpickler find_class}@anchor{2818}
@deffn {Méthode} find_class (module, name)

Importe `module' si besoin, et renvoie l'objet du nom `name' qu'il contient. `module' et `name' sont des chaînes de caractères (classe @ref{435,,str}). Contrairement à ce que son nom laisse penser, @ref{2818,,find_class()} est également appelée pour trouver les fonctions.

Les classes filles peuvent redéfinir cette méthode pour restreindre la désérialisation à certains types d'objets ou à d'autres conditions, notamment en vue de réduire les risques de sécurité. Voir @ref{2819,,Restriction des noms dans l'espace de nommage global} pour plus de détails.

Lève un @ref{1848,,événement d'audit} @code{pickle.find_class} avec les arguments @code{module} et @code{name}.
@end deffn
@end deffn

@geindex PickleBuffer (classe dans pickle)
@anchor{library/pickle pickle PickleBuffer}@anchor{1786}
@deffn {Classe} pickle.PickleBuffer (buffer)

Encapsule un objet tampon contenant des données sérialisables. `buffer' doit être un objet prenant en charge le @ref{38e,,protocole tampon}, comme un @ref{d1b,,objet octet-compatible} ou un tableau n-dimensionnel.

Les objets @ref{1786,,PickleBuffer} savent gérer le protocole tampon. Il est donc possible de les passer à d'autres API qui attendent un tampon, comme @ref{452,,memoryview}.

Les objets @ref{1786,,PickleBuffer} ne peuvent être sérialisés qu'avec le protocole 5 ou supérieur. Ils sont susceptibles d'être sérialisés @ref{2810,,hors-bande}.


Ajouté dans la version 3.8.


@geindex raw() (méthode pickle.PickleBuffer)
@anchor{library/pickle pickle PickleBuffer raw}@anchor{281a}
@deffn {Méthode} raw ()

Renvoie une @ref{452,,memoryview} de l'espace mémoire sous-jacent à ce tampon. La `memoryview' renvoyée est unidimensionnelle et C-contiguë. Elle a le format @code{B} (octets sans signe). @ref{17b2,,BufferError} est levée si le tampon n'est ni C-contigu, ni Fortran-contigu.
@end deffn

@geindex release() (méthode pickle.PickleBuffer)
@anchor{library/pickle pickle PickleBuffer release}@anchor{281b}
@deffn {Méthode} release ()

Release the underlying buffer exposed by the PickleBuffer object.
@end deffn
@end deffn

@node Quels objets sont sérialisables ?,Sérialisation des instances d'une classe,Interface du module,pickle --- Python object serialization
@anchor{library/pickle pickle-picklable}@anchor{280e}@anchor{library/pickle what-can-be-pickled-and-unpickled}@anchor{281c}
@subsubsection Quels objets sont sérialisables ?


Les objets des types suivants peuvent être sérialisés :


@itemize *

@item 
built-in constants (@code{None}, @code{True}, @code{False}, @code{Ellipsis}, and
@ref{7bc,,NotImplemented});

@item 
integers, floating-point numbers, complex numbers;

@item 
strings, bytes, bytearrays;

@item 
tuples, lists, sets, and dictionaries containing only picklable objects;

@item 
functions (built-in and user-defined) accessible from the top level of a
module (using @ref{140e,,def}, not @ref{127a,,lambda});

@item 
classes accessible from the top level of a module;

@item 
instances of such classes whose the result of calling @ref{5c2,,__getstate__()}
is picklable  (see section @ref{2806,,Sérialisation des instances d'une classe} for details).
@end itemize

Si vous essayez de sérialiser un objet qui ne peut pas l'être, une exception de type @ref{280d,,PicklingError} est levée. Lorsque cela se produit, il est possible qu'un certain nombre d'octets aient déjà été écrits dans le fichier ou flux. La sérialisation d'une structure de donnée avec de nombreux niveaux d'imbrication peut lever une exception @ref{d59,,RecursionError}. Pour augmenter la limite (avec précaution), voir @ref{4ac,,sys.setrecursionlimit()}.

Note that functions (built-in and user-defined) are pickled by fully
@ref{18ce,,qualified name}, not by value. @footnote{
C'est la raison pour laquelle les fonctions @ref{127a,,lambda} ne peuvent pas être sérialisées : elles partagent toutes le même nom, à savoir @code{<lambda>}.
}  This means that only the function name is
pickled, along with the name of the containing module and classes.  Neither
the function's code, nor any of its function attributes are pickled.  Thus the
defining module must be importable in the unpickling environment, and the module
must contain the named object, otherwise an exception will be raised. @footnote{
L'exception levée est généralement de type @ref{40f,,ImportError} ou @ref{343,,AttributeError}, mais ce n'est pas systématique.
}

Similarly, classes are pickled by fully qualified name, so the same restrictions in
the unpickling environment apply.  Note that none of the class's code or data is
pickled, so in the following example the class attribute @code{attr} is not
restored in the unpickling environment:

@example
class Foo:
    attr = 'A class attribute'

picklestring = pickle.dumps(Foo)
@end example

These restrictions are why picklable functions and classes must be defined at
the top level of a module.

Similarly, when class instances are pickled, their class's code and data are not
pickled along with them.  Only the instance data are pickled.  This is done on
purpose, so you can fix bugs in a class or add methods to the class and still
load objects that were created with an earlier version of the class.  If you
plan to have long-lived objects that will see many versions of a class, it may
be worthwhile to put a version number in the objects so that suitable
conversions can be made by the class's @ref{1458,,__setstate__()} method.

@node Sérialisation des instances d'une classe,Réduction personnalisée pour les types fonctions et autres objets,Quels objets sont sérialisables ?,pickle --- Python object serialization
@anchor{library/pickle pickle-inst}@anchor{2806}@anchor{library/pickle pickling-class-instances}@anchor{281d}
@subsubsection Sérialisation des instances d'une classe


Dans cette section sont décrits les mécanismes généraux qui s'offrent à vous pour définir, personnaliser et contrôler la manière dont les instances d'une classe sont sérialisées et désérialisées.

In most cases, no additional code is needed to make instances picklable.  By
default, pickle will retrieve the class and the attributes of an instance via
introspection. When a class instance is unpickled, its @ref{69b,,__init__()} method
is usually `not' invoked.  The default behaviour first creates an uninitialized
instance and then restores the saved attributes.  The following code shows an
implementation of this behaviour:

@example
def save(obj):
    return (obj.__class__, obj.__dict__)

def restore(cls, attributes):
    obj = cls.__new__(cls)
    obj.__dict__.update(attributes)
    return obj
@end example

Les classes peuvent personnaliser le comportement par défaut en définissant des méthodes spéciales :

@geindex __getnewargs_ex__() (méthode object)
@anchor{library/pickle object __getnewargs_ex__}@anchor{281e}
@deffn {Méthode} object.__getnewargs_ex__ ()

Dans les protocoles 2 et suivants, les classes peuvent personnaliser les valeurs passées à la méthode @ref{56c,,__new__()} lors de la désérialisation. Elles le font en définissant une méthode @ref{281e,,__getnewargs_ex__()} qui renvoie un couple @code{(args, kwargs)}, où `args' est un `n'-uplet des arguments positionnels et `kwargs' un dictionnaire des arguments nommés qui seront passés à @ref{56c,,__new__()} — autrement dit, l'appel sera @code{classe.__new__(*args, **kwargs)}.

Définissez cette méthode seulement si la méthode @ref{56c,,__new__()} de votre classe demande des arguments nommés. Dans le cas contraire, mieux vaut définir @ref{1459,,__getnewargs__()} pour préserver la compatibilité avec les protocoles anciens.


Modifié dans la version 3.6: @ref{281e,,__getnewargs_ex__()} est désormais appelée dans les protocoles 2 et 3.

@end deffn

@geindex __getnewargs__() (méthode object)
@anchor{library/pickle object __getnewargs__}@anchor{1459}
@deffn {Méthode} object.__getnewargs__ ()

Comme @ref{281e,,__getnewargs_ex__()}, mais ne permet que les arguments positionnels. Cette méthode doit renvoyer le `n'-uplet @code{args} des arguments passés à @ref{56c,,__new__()} lors de la désérialisation : l'appel sera @code{classe.__new__(*args)}.

Si @ref{281e,,__getnewargs_ex__()} est définie, elle prend la priorité et @ref{1459,,__getnewargs__()} n'est jamais appelée.


Modifié dans la version 3.6: Auparavant, @ref{1459,,__getnewargs__()} était appelée au lieu de @ref{281e,,__getnewargs_ex__()} dans les protocoles 2 et 3.

@end deffn

@geindex __getstate__() (méthode object)
@anchor{library/pickle object __getstate__}@anchor{5c2}
@deffn {Méthode} object.__getstate__ ()

Classes can further influence how their instances are pickled by overriding
the method @ref{5c2,,__getstate__()}.  It is called and the returned object
is pickled as the contents for the instance, instead of a default state.
There are several cases:


@itemize *

@item 
For a class that has no instance @ref{546,,__dict__} and no
@ref{14a0,,__slots__}, the default state is @code{None}.

@item 
For a class that has an instance @ref{546,,__dict__} and no
@ref{14a0,,__slots__}, the default state is @code{self.__dict__}.

@item 
For a class that has an instance @ref{546,,__dict__} and
@ref{14a0,,__slots__}, the default state is a tuple consisting of two
dictionaries:  @code{self.__dict__}, and a dictionary mapping slot
names to slot values.  Only slots that have a value are
included in the latter.

@item 
For a class that has @ref{14a0,,__slots__} and no instance
@ref{546,,__dict__}, the default state is a tuple whose first item
is @code{None} and whose second item is a dictionary mapping slot names
to slot values described in the previous bullet.
@end itemize


Modifié dans la version 3.11: Added the default implementation of the @code{__getstate__()} method in the
@ref{a7a,,object} class.

@end deffn

@geindex __setstate__() (méthode object)
@anchor{library/pickle object __setstate__}@anchor{1458}
@deffn {Méthode} object.__setstate__ (state)

Lors de la désérialisation, l'état de l'instance est passé à la méthode @ref{1458,,__setstate__()}, si elle est définie (l'objet `state' n'a pas besoin d'être un dictionnaire). Si elle ne l'est pas, les attributs de l'objet sont tirés de l'état, qui dans ce cas doit être obligatoirement un dictionnaire.

@cartouche
@quotation Note 
If @ref{9c1,,__reduce__()} returns a state with value @code{None} at pickling,
the @ref{1458,,__setstate__()} method will not be called upon unpickling.
@end quotation
@end cartouche
@end deffn

Refer to the section @ref{281f,,Traitement des objets à état} for more information about how to use
the methods @ref{5c2,,__getstate__()} and @ref{1458,,__setstate__()}.

@cartouche
@quotation Note 
At unpickling time, some methods like @ref{4bc,,__getattr__()},
@ref{bc0,,__getattribute__()}, or @ref{1eb2,,__setattr__()} may be called upon the
instance.  In case those methods rely on some internal invariant being
true, the type should implement @ref{56c,,__new__()} to establish such an
invariant, as @ref{69b,,__init__()} is not called when unpickling an
instance.
@end quotation
@end cartouche

@geindex copy;protocol

As we shall see, pickle does not use directly the methods described above.  In
fact, these methods are part of the copy protocol which implements the
@ref{9c1,,__reduce__()} special method.  The copy protocol provides a unified
interface for retrieving the data necessary for pickling and copying
objects. @footnote{
Le module @ref{25,,copy} fait appel à ce protocole pour les opérations de copie superficielle comme récursive.
}

Although powerful, implementing @ref{9c1,,__reduce__()} directly in your classes is
error prone.  For this reason, class designers should use the high-level
interface (i.e., @ref{281e,,__getnewargs_ex__()}, @ref{5c2,,__getstate__()} and
@ref{1458,,__setstate__()}) whenever possible.  We will show, however, cases where
using @code{__reduce__()} is the only option or leads to more efficient pickling
or both.

@geindex __reduce__() (méthode object)
@anchor{library/pickle object __reduce__}@anchor{9c1}
@deffn {Méthode} object.__reduce__ ()

Voici l'interface de la méthode @ref{9c1,,__reduce__()}. Elle ne prend aucun argument et renvoie soit une chaîne de caractères, soit (c'est conseillé) un `n'-uplet. On appelle souvent l'objet renvoyé « valeur de réduction ».

If a string is returned, the string should be interpreted as the name of a
global variable.  It should be the object's local name relative to its
module; the pickle module searches the module namespace to determine the
object's module.  This behaviour is typically useful for singletons.

Si c'est un `n'-uplet qui est renvoyé, ses éléments sont interprétés dans l'ordre comme suit. Les deux premiers éléments sont obligatoires, les quatre suivants sont facultatifs et peuvent être simplement omis, ou bien mis à @code{None}. Les éléments sont, dans l'ordre :

@c XXX Mention __newobj__ special-case?


@itemize *

@item 
Un objet appelable qui sera appelé pour créer l'objet initial.

@item 
Un `n'-uplet d'arguments passés à cet objet appelable. Donnez un `n'-uplet vide si l'objet appelable n'accepte pas d'arguments.

@item 
L'état de l'objet, qui sera passé à la méthode @ref{1458,,__setstate__()} comme vu précédemment. Si la méthode n'existe pas, cet élément doit être un dictionnaire, et ses éléments compléteront l'attribut @ref{546,,__dict__}.

@item 
Optionally, an iterator (and not a sequence) yielding successive items.
These items will be appended to the object either using
@code{obj.append(item)} or, in batch, using @code{obj.extend(list_of_items)}.
This is primarily used for list subclasses, but may be used by other
classes as long as they have
@ref{2132,,append and extend methods} with
the appropriate signature.  (Whether @code{append()} or @code{extend()} is
used depends on which pickle protocol version is used as well as the number
of items to append, so both must be supported.)

@item 
Un itérateur (non pas une séquence). Les éléments qu'il fournit doivent être des couples @code{(clé, valeur)}. Ils sont ajoutés dans l'objet par affectation aux clés : @code{objet[clé] = valeur}. Ceci est principalement utile aux classes héritant de @code{dict}, mais peut servir à d'autres classes à la seule condition qu'elles implémentent la méthode @ref{12a9,,__setitem__()}.

@item 
Un objet appelable qui puisse recevoir en arguments l'objet et son état. Ceci permet de redéfinir le processus de reconstruction des attributs pour un objet en particulier, outrepassant la méthode @ref{1458,,__setstate__()}. Si cet objet appelable est fourni, @ref{1458,,__setstate__()} n'est pas appelée.


Ajouté dans la version 3.8: ajout du sixième élément.

@end itemize
@end deffn

@geindex __reduce_ex__() (méthode object)
@anchor{library/pickle object __reduce_ex__}@anchor{1540}
@deffn {Méthode} object.__reduce_ex__ (protocol)

Il est également possible de définir une méthode @ref{1540,,__reduce_ex__()}. La seule différence est qu'elle prend la version du protocole en argument. Si elle est définie, elle prend le pas sur @ref{9c1,,__reduce__()}. De plus, @ref{9c1,,__reduce__()} devient automatiquement un alias pour sa version étendue. Cette méthode est principalement destinée à renvoyer des valeurs de réduction compatibles avec les versions anciennes de Python.
@end deffn

@menu
* Persistance d'objets externes:: 
* Tables de distribution:: 
* Traitement des objets à état:: 

@end menu

@node Persistance d'objets externes,Tables de distribution,,Sérialisation des instances d'une classe
@anchor{library/pickle persistence-of-external-objects}@anchor{2820}@anchor{library/pickle pickle-persistent}@anchor{2811}
@subsubsection Persistance d'objets externes


@geindex persistent_id (pickle protocol)
@geindex persistent_load (pickle protocol)

Pour les besoins de la persistance, @ref{a5,,pickle} permet des références à des objets en dehors du flux sérialisé. Ils sont identifiés par un ID persistant. Le protocole 0 requiert que cet ID soit une chaîne de caractères alphanumériques @footnote{
The limitation on alphanumeric characters is due to the fact
that persistent IDs in protocol 0 are delimited by the newline
character.  Therefore if any kind of newline characters occurs in
persistent IDs, the resulting pickled data will become unreadable.
}. Les suivants autorisent un objet quelconque.

@ref{a5,,pickle} délègue la résolution des ID à des méthodes définies par l'utilisateur sur les objets sérialiseurs et désérialiseurs, à savoir @ref{1526,,persistent_id()} et @ref{152e,,persistent_load()}.

Pour affecter à des objets leurs ID persistants provenant d'une source externe, le sérialiseur doit posséder une méthode @ref{1526,,persistent_id()} qui prend un objet et renvoie soit @code{None}, soit son ID. Si cette méthode renvoie @code{None}, l'objet est sérialisé de la manière habituelle. Si un ID est renvoyé, sous forme de chaîne de caractères, c'est cette chaîne qui est sérialisée et elle est marquée de manière spéciale pour être reconnue comme un ID persistant.

Pour désérialiser des objets identifiés par un ID externe, un désérialiseur doit posséder une méthode @ref{152e,,persistent_load()} qui prend un ID et renvoie l'objet qu'il désigne.

Voici un exemple complet qui montre comment sérialiser des objets externes en leur affectant des ID persistants.

@example
# Simple example presenting how persistent ID can be used to pickle
# external objects by reference.

import pickle
import sqlite3
from collections import namedtuple

# Simple class representing a record in our database.
MemoRecord = namedtuple("MemoRecord", "key, task")

class DBPickler(pickle.Pickler):

    def persistent_id(self, obj):
        # Instead of pickling MemoRecord as a regular class instance, we emit a
        # persistent ID.
        if isinstance(obj, MemoRecord):
            # Here, our persistent ID is simply a tuple, containing a tag and a
            # key, which refers to a specific record in the database.
            return ("MemoRecord", obj.key)
        else:
            # If obj does not have a persistent ID, return None. This means obj
            # needs to be pickled as usual.
            return None


class DBUnpickler(pickle.Unpickler):

    def __init__(self, file, connection):
        super().__init__(file)
        self.connection = connection

    def persistent_load(self, pid):
        # This method is invoked whenever a persistent ID is encountered.
        # Here, pid is the tuple returned by DBPickler.
        cursor = self.connection.cursor()
        type_tag, key_id = pid
        if type_tag == "MemoRecord":
            # Fetch the referenced record from the database and return it.
            cursor.execute("SELECT * FROM memos WHERE key=?", (str(key_id),))
            key, task = cursor.fetchone()
            return MemoRecord(key, task)
        else:
            # Always raises an error if you cannot return the correct object.
            # Otherwise, the unpickler will think None is the object referenced
            # by the persistent ID.
            raise pickle.UnpicklingError("unsupported persistent object")


def main():
    import io
    import pprint

    # Initialize and populate our database.
    conn = sqlite3.connect(":memory:")
    cursor = conn.cursor()
    cursor.execute("CREATE TABLE memos(key INTEGER PRIMARY KEY, task TEXT)")
    tasks = (
        'give food to fish',
        'prepare group meeting',
        'fight with a zebra',
        )
    for task in tasks:
        cursor.execute("INSERT INTO memos VALUES(NULL, ?)", (task,))

    # Fetch the records to be pickled.
    cursor.execute("SELECT * FROM memos")
    memos = [MemoRecord(key, task) for key, task in cursor]
    # Save the records using our custom DBPickler.
    file = io.BytesIO()
    DBPickler(file).dump(memos)

    print("Pickled records:")
    pprint.pprint(memos)

    # Update a record, just for good measure.
    cursor.execute("UPDATE memos SET task='learn italian' WHERE key=1")

    # Load the records from the pickle data stream.
    file.seek(0)
    memos = DBUnpickler(file, conn).load()

    print("Unpickled records:")
    pprint.pprint(memos)


if __name__ == '__main__':
    main()
@end example

@node Tables de distribution,Traitement des objets à état,Persistance d'objets externes,Sérialisation des instances d'une classe
@anchor{library/pickle dispatch-tables}@anchor{2821}@anchor{library/pickle pickle-dispatch}@anchor{2813}
@subsubsection Tables de distribution


Pour personnaliser la sérialisation d'une classe à un endroit particulier sans affecter le reste du code, on peut créer un sérialiseur avec une table de distribution spécifique.

The global dispatch table managed by the @ref{26,,copyreg} module is
available as @code{copyreg.dispatch_table}.  Therefore, one may
choose to use a modified copy of @code{copyreg.dispatch_table} as a
private dispatch table.

Par exemple, le code

@example
f = io.BytesIO()
p = pickle.Pickler(f)
p.dispatch_table = copyreg.dispatch_table.copy()
p.dispatch_table[SomeClass] = reduce_SomeClass
@end example

crée une instance de la classe @ref{a0c,,pickle.Pickler} avec une table de distribution propre qui traite la classe @code{SomeClass} de manière spécifique. Le code

@example
class MyPickler(pickle.Pickler):
    dispatch_table = copyreg.dispatch_table.copy()
    dispatch_table[SomeClass] = reduce_SomeClass
f = io.BytesIO()
p = MyPickler(f)
@end example

does the same but all instances of @code{MyPickler} will by default
share the private dispatch table.  On the other hand, the code

@example
copyreg.pickle(SomeClass, reduce_SomeClass)
f = io.BytesIO()
p = pickle.Pickler(f)
@end example

modifies the global dispatch table shared by all users of the @ref{26,,copyreg} module.

@node Traitement des objets à état,,Tables de distribution,Sérialisation des instances d'une classe
@anchor{library/pickle handling-stateful-objects}@anchor{2822}@anchor{library/pickle pickle-state}@anchor{281f}
@subsubsection Traitement des objets à état


@geindex __getstate__() (copy protocol)
@geindex __setstate__() (copy protocol)

Here's an example that shows how to modify pickling behavior for a class.
The @code{TextReader} class below opens a text file, and returns the line number and
line contents each time its @code{readline()} method is called. If a
@code{TextReader} instance is pickled, all attributes `except' the file object
member are saved. When the instance is unpickled, the file is reopened, and
reading resumes from the last location. The @code{__setstate__()} and
@code{__getstate__()} methods are used to implement this behavior.

@example
class TextReader:
    """Print and number lines in a text file."""

    def __init__(self, filename):
        self.filename = filename
        self.file = open(filename)
        self.lineno = 0

    def readline(self):
        self.lineno += 1
        line = self.file.readline()
        if not line:
            return None
        if line.endswith('\n'):
            line = line[:-1]
        return "%i: %s" % (self.lineno, line)

    def __getstate__(self):
        # Copy the object's state from self.__dict__ which contains
        # all our instance attributes. Always use the dict.copy()
        # method to avoid modifying the original state.
        state = self.__dict__.copy()
        # Remove the unpicklable entries.
        del state['file']
        return state

    def __setstate__(self, state):
        # Restore instance attributes (i.e., filename and lineno).
        self.__dict__.update(state)
        # Restore the previously opened file's state. To do so, we need to
        # reopen it and read from it until the line count is restored.
        file = open(self.filename)
        for _ in range(self.lineno):
            file.readline()
        # Finally, save the file.
        self.file = file
@end example

Voici un exemple d'utilisation :

@example
>>> reader = TextReader("hello.txt")
>>> reader.readline()
'1: Hello world!'
>>> reader.readline()
'2: I am line number two.'
>>> new_reader = pickle.loads(pickle.dumps(reader))
>>> new_reader.readline()
'3: Goodbye!'
@end example

@node Réduction personnalisée pour les types fonctions et autres objets,Tampons hors-bande,Sérialisation des instances d'une classe,pickle --- Python object serialization
@anchor{library/pickle custom-reduction-for-types-functions-and-other-objects}@anchor{2823}@anchor{library/pickle reducer-override}@anchor{2814}
@subsubsection Réduction personnalisée pour les types, fonctions et autres objets



Ajouté dans la version 3.8.


Parfois, la simple utilisation de @ref{1102,,dispatch_table} n'offre pas assez de flexibilité. On peut vouloir changer la méthode de sérialisation selon d'autres critères que le type de l'objet, ou bien personnaliser la sérialisation des fonctions et des classes.

For those cases, it is possible to subclass from the @ref{a0c,,Pickler} class and
implement a @ref{a0d,,reducer_override()} method. This method can return an
arbitrary reduction tuple (see @ref{9c1,,__reduce__()}). It can alternatively return
@ref{7bc,,NotImplemented} to fallback to the traditional behavior.

Si @ref{1102,,dispatch_table} et @ref{a0d,,reducer_override()} sont tous les deux définis, @ref{a0d,,reducer_override()} a la priorité.

@cartouche
@quotation Note 
Pour des raisons de performance, la méthode @ref{a0d,,reducer_override()} n'est jamais appelée sur @code{None}, @code{True}, @code{False}, ainsi que les instances exactes (pas dérivées) de @ref{254,,int}, @ref{2eb,,float}, @ref{1bd,,bytes}, @ref{435,,str}, @ref{253,,dict}, @ref{5c3,,set}, @ref{5c4,,frozenset}, @ref{5fc,,list} et @ref{366,,tuple}.
@end quotation
@end cartouche

Voici un exemple simple qui implémente la sérialisation d'une classe :

@example
import io
import pickle

class MyClass:
    my_attribute = 1

class MyPickler(pickle.Pickler):
    def reducer_override(self, obj):
        """Custom reducer for MyClass."""
        if getattr(obj, "__name__", None) == "MyClass":
            return type, (obj.__name__, obj.__bases__,
                          @{'my_attribute': obj.my_attribute@})
        else:
            # For any other object, fallback to usual reduction
            return NotImplemented

f = io.BytesIO()
p = MyPickler(f)
p.dump(MyClass)

del MyClass

unpickled_class = pickle.loads(f.getvalue())

assert isinstance(unpickled_class, type)
assert unpickled_class.__name__ == "MyClass"
assert unpickled_class.my_attribute == 1
@end example

@node Tampons hors-bande,Restriction des noms dans l'espace de nommage global,Réduction personnalisée pour les types fonctions et autres objets,pickle --- Python object serialization
@anchor{library/pickle out-of-band-buffers}@anchor{2824}@anchor{library/pickle pickle-oob}@anchor{2810}
@subsubsection Tampons hors-bande



Ajouté dans la version 3.8.


Le module @ref{a5,,pickle} est parfois utilisé pour transférer des quantités énormes de données. Il peut devenir important de réduire les copies de mémoire au minimum pour préserver la performance et diminuer l'usage des ressources matérielles. Cependant, dans son contexte courant d'utilisation, le module @ref{a5,,pickle} effectue des copies depuis et vers le flux de données pour les besoins de la conversion de structures d'objets semblables à des graphes en flux séquentiels d'octets.

Cette contrainte peut être levée si le `producteur' (qui implémente les types d'objets à transférer) et le `consommateur' (qui implémente le système de communication) emploient les possibilités de transfert hors-bande offertes par les protocoles 5 et suivants.

@menu
* API des producteurs:: 
* API des consommateurs:: 
* Exemple: Exemple<4>. 

@end menu

@node API des producteurs,API des consommateurs,,Tampons hors-bande
@anchor{library/pickle provider-api}@anchor{2825}
@subsubsection API des producteurs


The large data objects to be pickled must implement a @ref{1540,,__reduce_ex__()}
method specialized for protocol 5 and higher, which returns a
@ref{1786,,PickleBuffer} instance (instead of e.g. a @ref{1bd,,bytes} object)
for any large data.

Les objets @ref{1786,,PickleBuffer} ne font que signaler que leur tampon permet le transfert hors-bande. Ils demeurent compatibles avec l'utilisation classique du module @ref{a5,,pickle}. Cependant, les consommateurs peuvent aussi choisir d'indiquer à @ref{a5,,pickle} qu'ils gèrent eux-mêmes ces tampons.

@node API des consommateurs,Exemple<4>,API des producteurs,Tampons hors-bande
@anchor{library/pickle consumer-api}@anchor{2826}
@subsubsection API des consommateurs


Un système de communication peut gérer de manière spécifique les objets @ref{1786,,PickleBuffer} générés lors de la sérialisation d'un réseau d'objets.

Du côté de l'expéditeur, il faut passer le paramètre `buffer_callback' à @ref{a0c,,Pickler} (ou à @ref{280b,,dump()} ou @ref{1456,,dumps()}). Le `buffer_callback' sera appelé avec chaque @ref{1786,,PickleBuffer} généré lors de la sérialisation du réseau d'objets. Les tampons accumulés par le `buffer_callback' ne verront pas leurs données copiées dans le flux sérialisé. Il leur sera substitué un marqueur léger.

Du côté du receveur, il faut passer l'argument `buffers' à @ref{1630,,Unpickler} (ou @ref{cfe,,load()} ou bien @ref{cff,,loads()}). `buffers' est un itérable des tampons passés à `buffer_callback'. Il doit fournir les tampons dans le même ordre que celui dans lequel ils ont été passés à `buffer_callback'. Les tampons fournis constituent la source des données qu'attendent les reconstructeurs des objets dont la sérialisation a abouti aux objets @ref{1786,,PickleBuffer}.

Entre expéditeur et receveur, le système de communication peut implémenter son propre mécanisme de transfert pour les tampons hors-bande. Parmi les optimisations possibles se trouvent l'utilisation de mémoire partagée et la compression spécifique au type de données.

@node Exemple<4>,,API des consommateurs,Tampons hors-bande
@anchor{library/pickle example}@anchor{2827}
@subsubsection Exemple


Voici un exemple trivial où est implémentée une classe fille de @ref{528,,bytearray} capable de sérialisation hors-bande :

@example
class ZeroCopyByteArray(bytearray):

    def __reduce_ex__(self, protocol):
        if protocol >= 5:
            return type(self)._reconstruct, (PickleBuffer(self),), None
        else:
            # PickleBuffer is forbidden with pickle protocols <= 4.
            return type(self)._reconstruct, (bytearray(self),)

    @@classmethod
    def _reconstruct(cls, obj):
        with memoryview(obj) as m:
            # Get a handle over the original buffer object
            obj = m.obj
            if type(obj) is cls:
                # Original buffer object is a ZeroCopyByteArray, return it
                # as-is.
                return obj
            else:
                return cls(obj)
@end example

Lorsqu'il rencontre le bon type, le reconstructeur (la méthode de classe @code{_reconstruct}) renvoie directement le tampon original. Il s'agit d'une manière simple de simuler l'absence de copie dans cet exemple simpliste.

En tant que consommateur des objets, on peut les sérialiser de la manière classique. La désérialisation conduit alors à une copie :

@example
b = ZeroCopyByteArray(b"abc")
data = pickle.dumps(b, protocol=5)
new_b = pickle.loads(data)
print(b == new_b)  # True
print(b is new_b)  # False: a copy was made
@end example

Mais en passant un `buffer_callback' et en donnant les tampons accumulés au désérialiseur, il n'y a plus de copie :

@example
b = ZeroCopyByteArray(b"abc")
buffers = []
data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)
new_b = pickle.loads(data, buffers=buffers)
print(b == new_b)  # True
print(b is new_b)  # True: no copy was made
@end example

Cet exemple est limité par le fait que @ref{528,,bytearray} effectue sa propre allocation de mémoire. Il n'est pas possible de créer un @ref{528,,bytearray} sur la mémoire d'un autre objet. Cependant, certains types de données que l'on trouve dans des bibliothèques externes, comme les tableaux NumPy, n'ont pas cette limitation. Le passage hors-bande permet alors de n'effectuer aucune copie (ou bien de minimiser le nombre de copies) lors du transfert de données d'un système à l'autre ou d'un processus à l'autre.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 574
PEP 574@footnote{https://peps.python.org/pep-0574/} — Protocole `pickle' 5 avec données hors-bande


@node Restriction des noms dans l'espace de nommage global,Performances<2>,Tampons hors-bande,pickle --- Python object serialization
@anchor{library/pickle pickle-restrict}@anchor{2819}@anchor{library/pickle restricting-globals}@anchor{2828}
@subsubsection Restriction des noms dans l'espace de nommage global


@geindex find_class() (pickle protocol)

Par défaut, la désérialisation importe toutes les classes ou fonctions que demande le flux de données. Dans bien des cas, ce comportement est inacceptable, puisqu'il permet de faire exécuter du code arbitraire dans l'environnement de désérialisation. Observez le résultat de ce flux de données fait-main lorsqu'il est lu :

@example
>>> import pickle
>>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
hello world
0
@end example

Dans cet exemple, le désérialiseur importe la fonction @ref{1411,,os.system()} et l'applique à la chaîne de caractères @code{"echo hello world"}. C'est inoffensif, mais il n'est pas difficile d'imaginer des variantes qui endommageraient le système.

C'est pour cette raison qu'il s'avère parfois nécessaire de contrôler ce qui peut être désérialisé. Cela est possible en redéfinissant la méthode @ref{2818,,Unpickler.find_class()}. Contrairement à ce que son nom laisse penser, @ref{2818,,Unpickler.find_class()} est appelée pour tous les noms à chercher dans l'espace de nommage global, ce qui inclut les classes mais aussi les fonctions. Par ce biais, il est possible d'interdire complètement la résolution des noms globaux ou de la restreindre à un sous-ensemble que l'on considère sûr.

Voici un exemple de désérialiseur qui permet seulement la désérialisation d'un petit nombre de classes sûres du module @ref{12,,builtins} :

@example
import builtins
import io
import pickle

safe_builtins = @{
    'range',
    'complex',
    'set',
    'frozenset',
    'slice',
@}

class RestrictedUnpickler(pickle.Unpickler):

    def find_class(self, module, name):
        # Only allow safe classes from builtins.
        if module == "builtins" and name in safe_builtins:
            return getattr(builtins, name)
        # Forbid everything else.
        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
                                     (module, name))

def restricted_loads(s):
    """Helper function analogous to pickle.loads()."""
    return RestrictedUnpickler(io.BytesIO(s)).load()
@end example

A sample usage of our unpickler working as intended:

@example
>>> restricted_loads(pickle.dumps([1, 2, range(15)]))
[1, 2, range(0, 15)]
>>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
Traceback (most recent call last):
  ...
pickle.UnpicklingError: global 'os.system' is forbidden
>>> restricted_loads(b'cbuiltins\neval\n'
...                  b'(S\'getattr(__import__("os"), "system")'
...                  b'("echo hello world")\'\ntR.')
Traceback (most recent call last):
  ...
pickle.UnpicklingError: global 'builtins.eval' is forbidden
@end example

@c XXX Add note about how extension codes could evade our protection
@c mechanism (e.g. cached classes do not invokes find_class()).

Comme le montre l'exemple, il faut faire attention aux objets que l'on autorise à être désérialisés. Si la sécurité est une priorité, il peut être sage de se tourner vers des alternatives comme l'API du module @ref{12d,,xmlrpc.client}, ou des bibliothèques tierces.

@node Performances<2>,Exemples<7>,Restriction des noms dans l'espace de nommage global,pickle --- Python object serialization
@anchor{library/pickle performance}@anchor{2829}
@subsubsection Performances


Recent versions of the pickle protocol (from protocol 2 and upwards) feature
efficient binary encodings for several common features and built-in types.
Also, the @ref{a5,,pickle} module has a transparent optimizer written in C.

@node Exemples<7>,,Performances<2>,pickle --- Python object serialization
@anchor{library/pickle examples}@anchor{282a}@anchor{library/pickle pickle-example}@anchor{282b}
@subsubsection Exemples


Dans les cas les plus simples, utilisez les fonctions @ref{280b,,dump()} et @ref{cfe,,load()}.

@example
import pickle

# An arbitrary collection of objects supported by pickle.
data = @{
    'a': [1, 2.0, 3+4j],
    'b': ("character string", b"byte string"),
    'c': @{None, True, False@}
@}

with open('data.pickle', 'wb') as f:
    # Pickle the 'data' dictionary using the highest protocol available.
    pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)
@end example

Le code suivant lit les données qui viennent d'être sérialisées

@example
import pickle

with open('data.pickle', 'rb') as f:
    # The protocol version used is detected automatically, so we do not
    # have to specify it.
    data = pickle.load(f)
@end example

@c XXX: Add examples showing how to optimize pickles for size (like using

@c pickletools.optimize() or the gzip module).


@subsubheading Voir aussi



@table @asis

@item Module @ref{26,,copyreg}

Enregistre les fonctions de sérialisation pour les types définis par l'utilisateur.

@item Module @ref{a6,,pickletools}

Outils pour travailler sur les données sérialisées et les analyser.

@item Module @ref{c2,,shelve}

Bases de données indexées (module fondé sur @ref{a5,,pickle}).

@item Module @ref{25,,copy}

Copie superficielle ou récursive d'objets.

@item Module @ref{8c,,marshal}

Sérialisation haute-performance des types natifs.
@end table


@subsubheading Notes


@node copyreg --- Register pickle support functions,shelve --- Python object persistence,pickle --- Python object serialization,Persistance des données
@anchor{library/copyreg doc}@anchor{282c}@anchor{library/copyreg copyreg-register-pickle-support-functions}@anchor{282d}@anchor{library/copyreg module-copyreg}@anchor{26}
@subsection @code{copyreg} --- Register @code{pickle} support functions


@geindex module; copyreg

`Code source :' Lib/copyreg.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/copyreg.py}

@geindex module;pickle
@geindex module;copy


__________________________________________________________________


Le module @ref{26,,copyreg} permet de définir des fonctions utilisées durant la sérialisation avec `pickle' de certains objets. Les modules @ref{a5,,pickle} et @ref{25,,copy} utilisent ces fonctions lors d'une sérialisation ou d'une copie de ces objets. Le module propose alors des informations de configuration à propos de constructeurs d'objets qui ne sont pas des classes. De tels constructeurs peuvent être des instances de classes ou des fonctions.

@geindex constructor() (dans le module copyreg)
@anchor{library/copyreg copyreg constructor}@anchor{282e}
@deffn {Fonction} copyreg.constructor (object)

Déclare `object' comme étant un constructeur valide. Si `object' n'est pas appelable (et n'est donc pas un constructeur valide), l'erreur @ref{522,,TypeError} est levée.
@end deffn

@geindex pickle() (dans le module copyreg)
@anchor{library/copyreg copyreg pickle}@anchor{2812}
@deffn {Fonction} copyreg.pickle (type, function, constructor_ob=None)

Declares that `function' should be used as a "reduction" function for objects
of type `type'.  `function' must return either a string or a tuple
containing between two and six elements. See the @ref{1102,,dispatch_table}
for more details on the interface of `function'.

The `constructor_ob' parameter is a legacy feature and is now ignored, but if
passed it must be a callable.

Note that the @ref{1102,,dispatch_table} attribute of a pickler
object or subclass of @ref{a0c,,pickle.Pickler} can also be used for
declaring reduction functions.
@end deffn

@menu
* Exemple: Exemple<5>. 

@end menu

@node Exemple<5>,,,copyreg --- Register pickle support functions
@anchor{library/copyreg example}@anchor{282f}
@subsubsection Exemple


L'exemple si-dessous essaye de démontrer comment enregistrer une fonction `pickle' et comment elle sera utilisée :

@example
>>> import copyreg, copy, pickle
>>> class C:
...     def __init__(self, a):
...         self.a = a
...
>>> def pickle_c(c):
...     print("pickling a C instance...")
...     return C, (c.a,)
...
>>> copyreg.pickle(C, pickle_c)
>>> c = C(1)
>>> d = copy.copy(c)  
pickling a C instance...
>>> p = pickle.dumps(c)  
pickling a C instance...
@end example

@node shelve --- Python object persistence,marshal --- Internal Python object serialization,copyreg --- Register pickle support functions,Persistance des données
@anchor{library/shelve doc}@anchor{2830}@anchor{library/shelve module-shelve}@anchor{c2}@anchor{library/shelve shelve-python-object-persistence}@anchor{2831}
@subsection @code{shelve} --- Python object persistence


@geindex module; shelve

`Code source :' Lib/shelve.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/shelve.py}

@geindex module;pickle


__________________________________________________________________


Une étagère (`shelf' en anglais) est un objet persistant similaire à un dictionnaire. La différence avec les bases de données `dbm' est que les valeurs (pas les clés !) dans une étagère peuvent être des objets Python arbitraires — n'importe quoi que le module @ref{a5,,pickle} peut gérer. Cela inclut la plupart des instances de classe, des types de données récursives, et les objets contenant beaucoup de sous-objets partagés. Les clés sont des chaînes de caractères ordinaires.

@geindex open() (dans le module shelve)
@anchor{library/shelve shelve open}@anchor{168a}
@deffn {Fonction} shelve.open (filename, flag='c', protocol=None, writeback=False)

Ouvre un dictionnaire persistant. Le nom de fichier spécifié est le nom de fichier sans (son) extension pour la base de données sous-jacente. Comme effet de bord, une extension peut être ajoutée au nom de fichier et plus d'un fichier peut être créé. Par défaut, le fichier de base de données sous-jacente est ouvert en lecture et en écriture. Le paramètre optionnel `flag' possède la même interprétation que le paramètre `flag' de @ref{f15,,dbm.open()}.

By default, pickles created with @ref{818,,pickle.DEFAULT_PROTOCOL} are used
to serialize values.  The version of the pickle protocol can be specified
with the `protocol' parameter.

À cause de la sémantique de Python, une étagère ne peut pas savoir lorsqu'une entrée mutable de dictionnaire persistant est modifiée. Par défaut les objets modifiés sont écrits `seulement' lorsqu'ils sont assignés à une étagère (voir @ref{2832,,Exemple}). Si le paramètre optionnel `writeback' est mis à @code{True}, toutes les entrées déjà accédées sont aussi mises en cache en mémoire, et ré-écrites sur @ref{2833,,sync()} et @ref{2834,,close()} ; cela peut faciliter la modification des entrées modifiables dans le dictionnaire persistant, mais, si vous accédez à beaucoup d'entrées, cela peut consommer beaucoup de mémoire cache, et cela peut rendre l'opération de fermeture très lente puisque toutes les entrées déjà accédées sont ré-écrites (il n'y a aucun moyen de savoir quelles entrées déjà accédées sont mutables, ni lesquelles ont été vraiment modifiées).


Modifié dans la version 3.10: @ref{818,,pickle.DEFAULT_PROTOCOL} is now used as the default pickle
protocol.



Modifié dans la version 3.11: Accepts @ref{29d,,path-like object} for filename.


@cartouche
@quotation Note 
Ne pas se fier à la fermeture automatique de l’étagère ; appelez toujours @ref{2834,,close()} explicitement quand vous n'en avez plus besoin, ou utilisez @ref{168a,,shelve.open()} comme un gestionnaire de contexte :

@example
with shelve.open('spam') as db:
    db['eggs'] = 'eggs'
@end example
@end quotation
@end cartouche
@end deffn
@anchor{library/shelve shelve-security}@anchor{2835}
@cartouche
@quotation Avertissement 
Puisque le module @ref{c2,,shelve} utilise en arrière plan @ref{a5,,pickle}, il n'est pas sûr de charger une étagère depuis une source non fiable. Comme avec `pickle', charger une étagère peut exécuter du code arbitraire.
@end quotation
@end cartouche

Les objets d’étagère gèrent la plupart des méthodes et opérations des dictionnaires (à l’exception de la copie, des constructeurs et des opérateurs @code{|} et @code{|=}). Cela facilite la transition depuis les scripts utilisant des dictionnaires vers ceux nécessitant un stockage persistant.

Deux méthodes supplémentaires sont autorisées :

@geindex sync() (méthode shelve.Shelf)
@anchor{library/shelve shelve Shelf sync}@anchor{2833}
@deffn {Méthode} Shelf.sync ()

Réécrit toutes les entrées dans le cache si l’étagère a été ouverte avec `writeback' passé à @ref{bfb,,True}. Vide le cache et synchronise le dictionnaire persistant sur le disque, si faisable. Elle est appelée automatiquement quand l’étagère est fermée avec @ref{2834,,close()}.
@end deffn

@geindex close() (méthode shelve.Shelf)
@anchor{library/shelve shelve Shelf close}@anchor{2834}
@deffn {Méthode} Shelf.close ()

Synchronise et ferme l'objet `dict' persistant. Les opérations sur une étagère fermée échouent avec une @ref{1ff,,ValueError}.
@end deffn


@subsubheading Voir aussi


Persistent dictionary recipe@footnote{https://code.activestate.com/recipes/576642-persistent-dict-with-multiple-standard-file-format/}
with widely supported storage formats and having the speed of native
dictionaries.


@menu
* Limites:: 
* Exemple: Exemple<6>. 

@end menu

@node Limites,Exemple<6>,,shelve --- Python object persistence
@anchor{library/shelve restrictions}@anchor{2836}
@subsubsection Limites


@geindex module;dbm.ndbm
@geindex module;dbm.gnu


@itemize *

@item 
Le choix du paquet de base de données à utiliser (comme @ref{34,,dbm.ndbm} ou @ref{33,,dbm.gnu}) dépend de l'interface disponible. Donc c'est risqué d'ouvrir la base de données directement en utilisant @ref{31,,dbm}. La base de données est également (malheureusement) sujette à des limitations de @ref{31,,dbm}, si c'est utilisé — cela signifie que (la représentation sérialisée de) l'objet stocké dans la base de données doit être assez petit et, dans de rares cas, des collisions de clés peuvent entraîner le refus de mises à jour de la base de données.

@item 
Le module @ref{c2,,shelve} ne gère pas l'accès `concurrent' en lecture/écriture sur les objets stockés (les accès simultanés en lecture sont sûrs). Lorsqu'un programme a une étagère ouverte en écriture, aucun autre programme ne doit l'avoir ouverte en écriture ou lecture. Le verrouillage des fichiers Unix peut être utilisé pour résoudre ce problème, mais cela dépend de la version Unix et nécessite des connaissances à propos de l'implémentation de la base de données utilisée.

@item 
On macOS @ref{34,,dbm.ndbm} can silently corrupt the database file on updates,
which can cause hard crashes when trying to read from the database.
@end itemize

@geindex Shelf (classe dans shelve)
@anchor{library/shelve shelve Shelf}@anchor{f85}
@deffn {Classe} shelve.Shelf (dict, protocol=None, writeback=False, keyencoding='utf-8')

Sous-classe de @ref{1090,,collections.abc.MutableMapping} qui stocke les valeurs sérialisées dans l'objet `dict'.

By default, pickles created with @ref{818,,pickle.DEFAULT_PROTOCOL} are used
to serialize values.  The version of the pickle protocol can be specified
with the `protocol' parameter.  See the @ref{a5,,pickle} documentation for a
discussion of the pickle protocols.

Si le paramètre `writeback' est @code{True}, l'objet garde en cache toutes les entrées accédées et les écrit dans le `dict' aux moments de synchronisation et de fermeture. Cela permet des opérations naturelles sur les entrées mutables, mais peut consommer beaucoup plus de mémoire et rendre les temps de synchronisation et de fermeture très longs.

Le paramètre `keyencoding' est l'encodage utilisé pour encoder les clés avant qu'elles soient utilisées avec le dictionnaire sous-jacent.

Un objet @ref{f85,,Shelf} peut également être utilisé comme un gestionnaire de contexte ; il est automatiquement fermé lorsque le bloc @ref{5bc,,with} se termine.


Modifié dans la version 3.2: Ajout du paramètre `keyencoding' ; précédemment, les clés étaient toujours encodées en UTF-8.



Modifié dans la version 3.4: Ajout de la gestion des gestionnaires de contexte.



Modifié dans la version 3.10: @ref{818,,pickle.DEFAULT_PROTOCOL} is now used as the default pickle
protocol.

@end deffn

@geindex BsdDbShelf (classe dans shelve)
@anchor{library/shelve shelve BsdDbShelf}@anchor{21e1}
@deffn {Classe} shelve.BsdDbShelf (dict, protocol=None, writeback=False, keyencoding='utf-8')

A subclass of @ref{f85,,Shelf} which exposes @code{first()}, @code{next()},
@code{previous()}, @code{last()} and @code{set_location()} methods.
These are available
in the third-party @code{bsddb} module from pybsddb@footnote{https://www.jcea.es/programacion/pybsddb.htm} but not in other database
modules.  The `dict' object passed to the constructor must support those
methods.  This is generally accomplished by calling one of
@code{bsddb.hashopen()}, @code{bsddb.btopen()} or @code{bsddb.rnopen()}.  The
optional `protocol', `writeback', and `keyencoding' parameters have the same
interpretation as for the @ref{f85,,Shelf} class.
@end deffn

@geindex DbfilenameShelf (classe dans shelve)
@anchor{library/shelve shelve DbfilenameShelf}@anchor{21e2}
@deffn {Classe} shelve.DbfilenameShelf (filename, flag='c', protocol=None, writeback=False)

Sous-classe de @ref{f85,,Shelf} qui accepte un `filename' au lieu d'un objet dictionnaire-compatible. Le fichier sous-jacent est ouvert avec @ref{f15,,dbm.open()}. Par défaut le fichier est créé en lecture et en écriture. Le paramètre optionnel `flag' peut être interprété de la même manière que pour la fonction @ref{168a,,open()}. Les paramètres optionnels `protocol' et `writeback' s'interprètent de la même manière que pour la classe @ref{f85,,Shelf}.
@end deffn

@node Exemple<6>,,Limites,shelve --- Python object persistence
@anchor{library/shelve example}@anchor{2837}@anchor{library/shelve shelve-example}@anchor{2832}
@subsubsection Exemple


Pour résumer l'interface (@code{key} est une chaîne de caractère, @code{data} est un objet arbitraire) :

@example
import shelve

d = shelve.open(filename)  # open -- file may get suffix added by low-level
                           # library

d[key] = data              # store data at key (overwrites old data if
                           # using an existing key)
data = d[key]              # retrieve a COPY of data at key (raise KeyError
                           # if no such key)
del d[key]                 # delete data stored at key (raises KeyError
                           # if no such key)

flag = key in d            # true if the key exists
klist = list(d.keys())     # a list of all existing keys (slow!)

# as d was opened WITHOUT writeback=True, beware:
d['xx'] = [0, 1, 2]        # this works as expected, but...
d['xx'].append(3)          # *this doesn't!* -- d['xx'] is STILL [0, 1, 2]!

# having opened d without writeback=True, you need to code carefully:
temp = d['xx']             # extracts the copy
temp.append(5)             # mutates the copy
d['xx'] = temp             # stores the copy right back, to persist it

# or, d=shelve.open(filename,writeback=True) would let you just code
# d['xx'].append(5) and have it work as expected, BUT it would also
# consume more memory and make the d.close() operation slower.

d.close()                  # close it
@end example


@subsubheading Voir aussi



@table @asis

@item Module @ref{31,,dbm}

Interface générique de base de données dans le style de @code{dbm}.

@item Module @ref{a5,,pickle}

Sérialisation d'objet utilisé par @ref{c2,,shelve}.
@end table


@node marshal --- Internal Python object serialization,dbm --- Interfaces to Unix "databases",shelve --- Python object persistence,Persistance des données
@anchor{library/marshal doc}@anchor{2838}@anchor{library/marshal marshal-internal-python-object-serialization}@anchor{2839}@anchor{library/marshal module-marshal}@anchor{8c}
@subsection @code{marshal} --- Internal Python object serialization


@geindex module; marshal


__________________________________________________________________


This module contains functions that can read and write Python values in a binary
format.  The format is specific to Python, but independent of machine
architecture issues (e.g., you can write a Python value to a file on a PC,
transport the file to a Mac, and read it back there).  Details of the format are
undocumented on purpose; it may change between Python versions (although it
rarely does). @footnote{
Le nom de ce module provient d'un peu de terminologie utilisée par les concepteurs de Modula-3 (entre autres), qui utilisent le terme `marshalling' pour l'envoi de données sous une forme autonome. À proprement parler, `to marshal' signifie convertir certaines données d'une forme interne à une forme externe (dans une mémoire tampon RPC par exemple) et `unmarshalling' désigne le processus inverse.
}

@geindex module;pickle
@geindex module;shelve

This is not a general "persistence" module.  For general persistence and
transfer of Python objects through RPC calls, see the modules @ref{a5,,pickle} and
@ref{c2,,shelve}.  The @ref{8c,,marshal} module exists mainly to support reading and
writing the "pseudo-compiled" code for Python modules of @code{.pyc} files.
Therefore, the Python maintainers reserve the right to modify the marshal format
in backward incompatible ways should the need arise.
The format of code objects is not compatible between Python versions,
even if the version of the format is the same.
De-serializing a code object in the incorrect Python version has undefined behavior.
If you're serializing and
de-serializing Python objects, use the @ref{a5,,pickle} module instead -- the
performance is comparable, version independence is guaranteed, and pickle
supports a substantially wider range of objects than marshal.

@cartouche
@quotation Avertissement 
N'utilisez pas le module @ref{8c,,marshal} pour lire des données erronées ou malveillantes.  Ne démantelez jamais des données reçues d'une source non fiable ou non authentifiée.
@end quotation
@end cartouche

@geindex object;code
@geindex code object

Not all Python object types are supported; in general, only objects whose value
is independent from a particular invocation of Python can be written and read by
this module.  The following types are supported: booleans, integers, floating-point
numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets,
frozensets, dictionaries, and code objects (if `allow_code' is true),
where it should be understood that
tuples, lists, sets, frozensets and dictionaries are only supported as long as
the values contained therein are themselves supported.  The
singletons @ref{660,,None}, @ref{210e,,Ellipsis} and @ref{be8,,StopIteration} can also be
marshalled and unmarshalled.
For format `version' lower than 3, recursive lists, sets and dictionaries cannot
be written (see below).

Il existe des fonctions de lecture-écriture de fichiers ainsi que des fonctions opérant sur des objets octet.

Le module définit ces fonctions :

@geindex dump() (dans le module marshal)
@anchor{library/marshal marshal dump}@anchor{283a}
@deffn {Fonction} marshal.dump (value, file, version=version, /, *, allow_code=True)

Écrit la valeur sur le fichier ouvert.  La valeur doit être un type pris en charge.  Le fichier doit être un @ref{1c15,,fichier binaire} ouvert en écriture.

If the value has (or contains an object that has) an unsupported type, a
@ref{1ff,,ValueError} exception is raised --- but garbage data will also be written
to the file.  The object will not be properly read back by @ref{19a1,,load()}.
@ref{1cd,,Code objects} are only supported if `allow_code' is true.

L'argument `version' indique le format de données que le @code{dump} doit utiliser (voir ci-dessous).

Raises an @ref{1848,,auditing event} @code{marshal.dumps} with arguments @code{value}, @code{version}.


Modifié dans la version 3.13: Added the `allow_code' parameter.

@end deffn

@geindex load() (dans le module marshal)
@anchor{library/marshal marshal load}@anchor{19a1}
@deffn {Fonction} marshal.load (file, /, *, allow_code=True)

Read one value from the open file and return it.  If no valid value is read
(e.g. because the data has a different Python version's incompatible marshal
format), raise @ref{12b7,,EOFError}, @ref{1ff,,ValueError} or @ref{522,,TypeError}.
@ref{1cd,,Code objects} are only supported if `allow_code' is true.
The file must be a readable @ref{1c15,,binary file}.

Raises an @ref{1848,,auditing event} @code{marshal.load} with no arguments.

@cartouche
@quotation Note 
Si un objet contenant un type non pris en charge a été dé-compilé avec @ref{283a,,dump()}, @ref{19a1,,load()} remplacera le type non « dé-compilable » par @code{None}.
@end quotation
@end cartouche


Modifié dans la version 3.10: This call used to raise a @code{code.__new__} audit event for each code object. Now
it raises a single @code{marshal.load} event for the entire load operation.



Modifié dans la version 3.13: Added the `allow_code' parameter.

@end deffn

@geindex dumps() (dans le module marshal)
@anchor{library/marshal marshal dumps}@anchor{e8e}
@deffn {Fonction} marshal.dumps (value, version=version, /, *, allow_code=True)

Return the bytes object that would be written to a file by @code{dump(value, file)}.  The
value must be a supported type.  Raise a @ref{1ff,,ValueError} exception if value
has (or contains an object that has) an unsupported type.
@ref{1cd,,Code objects} are only supported if `allow_code' is true.

L'argument `version' indique le format de données que @code{dumps} doivent utiliser (voir ci-dessous).

Raises an @ref{1848,,auditing event} @code{marshal.dumps} with arguments @code{value}, @code{version}.


Modifié dans la version 3.13: Added the `allow_code' parameter.

@end deffn

@geindex loads() (dans le module marshal)
@anchor{library/marshal marshal loads}@anchor{283b}
@deffn {Fonction} marshal.loads (bytes, /, *, allow_code=True)

Convert the @ref{d1b,,bytes-like object} to a value.  If no valid value is found, raise
@ref{12b7,,EOFError}, @ref{1ff,,ValueError} or @ref{522,,TypeError}.
@ref{1cd,,Code objects} are only supported if `allow_code' is true.
Extra bytes in the input are ignored.

Raises an @ref{1848,,auditing event} @code{marshal.loads} with argument @code{bytes}.


Modifié dans la version 3.10: This call used to raise a @code{code.__new__} audit event for each code object. Now
it raises a single @code{marshal.loads} event for the entire load operation.



Modifié dans la version 3.13: Added the `allow_code' parameter.

@end deffn

De plus, les constantes suivantes sont définies :

@geindex version (dans le module marshal)
@anchor{library/marshal marshal version}@anchor{283c}
@deffn {Données} marshal.version

Indicates the format that the module uses. Version 0 is the historical
format, version 1 shares interned strings and version 2 uses a binary format
for floating-point numbers.
Version 3 adds support for object instancing and recursion.
The current version is 4.
@end deffn

@subsubheading Notes


@node dbm --- Interfaces to Unix "databases",sqlite3 --- DB-API 2 0 interface for SQLite databases,marshal --- Internal Python object serialization,Persistance des données
@anchor{library/dbm doc}@anchor{283d}@anchor{library/dbm dbm-interfaces-to-unix-databases}@anchor{283e}@anchor{library/dbm module-dbm}@anchor{31}
@subsection @code{dbm} --- Interfaces to Unix "databases"


@geindex module; dbm

`Source code:' Lib/dbm/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dbm/__init__.py}


__________________________________________________________________


@ref{31,,dbm} is a generic interface to variants of the DBM database:


@itemize *

@item 
@ref{35,,dbm.sqlite3}

@item 
@ref{33,,dbm.gnu}

@item 
@ref{34,,dbm.ndbm}
@end itemize

If none of these modules are installed, the
slow-but-simple implementation in module @ref{32,,dbm.dumb} will be used.  There
is a third party interface@footnote{https://www.jcea.es/programacion/pybsddb.htm} to
the Oracle Berkeley DB.

@geindex error
@anchor{library/dbm dbm error}@anchor{283f}
@deffn {Exception} dbm.error

A tuple containing the exceptions that can be raised by each of the supported
modules, with a unique exception also named @ref{283f,,dbm.error} as the first
item --- the latter is used when @ref{283f,,dbm.error} is raised.
@end deffn

@geindex whichdb() (dans le module dbm)
@anchor{library/dbm dbm whichdb}@anchor{2840}
@deffn {Fonction} dbm.whichdb (filename)

This function attempts to guess which of the several simple database modules
available --- @ref{35,,dbm.sqlite3}, @ref{33,,dbm.gnu}, @ref{34,,dbm.ndbm},
or @ref{32,,dbm.dumb} --- should be used to open a given file.

Return one of the following values:


@itemize *

@item 
@code{None} if the file can't be opened because it's unreadable or doesn't exist

@item 
the empty string (@code{'@w{'}}) if the file's format can't be guessed

@item 
a string containing the required module name, such as @code{'dbm.ndbm'} or @code{'dbm.gnu'}
@end itemize


Modifié dans la version 3.11: `filename' accepts a @ref{29d,,path-like object}.

@end deffn

@c Substitutions for the open() flag param docs;
@c all submodules use the same text.

@geindex open() (dans le module dbm)
@anchor{library/dbm dbm open}@anchor{f15}
@deffn {Fonction} dbm.open (file, flag='r', mode=0o666)

Open a database and return the corresponding database object.

@*Paramètres: 

@itemize *

@item 
@code{file} (@ref{29d,,path-like object}) -- 
The database file to open.

If the database file already exists, the @ref{2840,,whichdb()} function is used to
determine its type and the appropriate module is used; if it does not exist,
the first submodule listed above that can be imported is used.


@item 
@code{flag} (@ref{435,,str}) -- 

@itemize *

@item 
@code{'r'} (default): Open existing database for reading only.

@item 
@code{'w'}: Open existing database for reading and writing.

@item 
@code{'c'}: Open database for reading and writing, creating it if it doesn't exist.

@item 
@code{'n'}: Always create a new, empty database, open for reading and writing.
@end itemize


@item 
@code{mode} (@ref{254,,int}) -- The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize



Modifié dans la version 3.11: `file' accepts a @ref{29d,,path-like object}.

@end deffn

The object returned by @ref{f15,,open()} supports the same basic functionality as a
@ref{253,,dict}; keys and their corresponding values can be stored, retrieved, and
deleted, and the @ref{2e8,,in} operator and the @code{keys()} method are
available, as well as @code{get()} and @code{setdefault()} methods.

Key and values are always stored as @ref{1bd,,bytes}. This means that when
strings are used they are implicitly converted to the default encoding before
being stored.

These objects also support being used in a @ref{5bc,,with} statement, which
will automatically close them when done.


Modifié dans la version 3.2: @code{get()} and @code{setdefault()} methods are now available for all
@ref{31,,dbm} backends.



Modifié dans la version 3.4: Added native support for the context management protocol to the objects
returned by @ref{f15,,open()}.



Modifié dans la version 3.8: Deleting a key from a read-only database raises a database module specific exception
instead of @ref{33a,,KeyError}.


The following example records some hostnames and a corresponding title,  and
then prints out the contents of the database:

@example
import dbm

# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:

    # Record some values
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note that the keys are considered bytes now.
    assert db[b'www.python.org'] == b'Python Website'
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Often-used methods of the dict interface work too.
    print(db.get('python.org', b'not present'))

    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.
@end example


@subsubheading Voir aussi



@table @asis

@item Module @ref{c2,,shelve}

Persistence module which stores non-string data.
@end table


The individual submodules are described in the following sections.

@menu
* dbm.sqlite3: dbm sqlite3 --- SQLite backend for dbm. SQLite backend for dbm
* dbm.gnu: dbm gnu --- GNU database manager. GNU database manager
* dbm.ndbm: dbm ndbm --- New Database Manager. New Database Manager
* dbm.dumb: dbm dumb --- Portable DBM implementation. Portable DBM implementation

@end menu

@node dbm sqlite3 --- SQLite backend for dbm,dbm gnu --- GNU database manager,,dbm --- Interfaces to Unix "databases"
@anchor{library/dbm dbm-sqlite3-sqlite-backend-for-dbm}@anchor{2841}@anchor{library/dbm module-dbm sqlite3}@anchor{35}
@subsubsection @code{dbm.sqlite3} --- SQLite backend for dbm


@geindex module; dbm.sqlite3


Ajouté dans la version 3.13.


`Source code:' Lib/dbm/sqlite3.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dbm/sqlite3.py}


__________________________________________________________________


This module uses the standard library @ref{ce,,sqlite3} module to provide an
SQLite backend for the @ref{31,,dbm} module.
The files created by @ref{35,,dbm.sqlite3} can thus be opened by @ref{ce,,sqlite3},
or any other SQLite browser, including the SQLite CLI.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@geindex open() (dans le module dbm.sqlite3)
@anchor{library/dbm dbm sqlite3 open}@anchor{2842}
@deffn {Fonction} dbm.sqlite3.open (filename, /, flag='r', mode=0o666)

Open an SQLite database.
The returned object behaves like a @ref{1199,,mapping},
implements a @code{close()} method,
and supports a "closing" context manager via the @ref{5bc,,with} keyword.

@*Paramètres: 

@itemize *

@item 
@code{filename} (@ref{29d,,path-like object}) -- The path to the database to be opened.

@item 
@code{flag} (@ref{435,,str}) -- 

@itemize *

@item 
@code{'r'} (default): Open existing database for reading only.

@item 
@code{'w'}: Open existing database for reading and writing.

@item 
@code{'c'}: Open database for reading and writing, creating it if it doesn't exist.

@item 
@code{'n'}: Always create a new, empty database, open for reading and writing.
@end itemize


@item 
@code{mode} -- The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize

@end deffn

@node dbm gnu --- GNU database manager,dbm ndbm --- New Database Manager,dbm sqlite3 --- SQLite backend for dbm,dbm --- Interfaces to Unix "databases"
@anchor{library/dbm dbm-gnu-gnu-database-manager}@anchor{2843}@anchor{library/dbm module-dbm gnu}@anchor{33}
@subsubsection @code{dbm.gnu} --- GNU database manager


@geindex module; dbm.gnu

`Source code:' Lib/dbm/gnu.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dbm/gnu.py}


__________________________________________________________________


The @ref{33,,dbm.gnu} module provides an interface to the @abbr{GDBM,GNU dbm}
library, similar to the @ref{34,,dbm.ndbm} module, but with additional
functionality like crash tolerance.

@cartouche
@quotation Note 
The file formats created by @ref{33,,dbm.gnu} and @ref{34,,dbm.ndbm} are incompatible
and can not be used interchangeably.
@end quotation
@end cartouche

@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@geindex error
@anchor{library/dbm dbm gnu error}@anchor{a88}
@deffn {Exception} dbm.gnu.error

Raised on @ref{33,,dbm.gnu}-specific errors, such as I/O errors. @ref{33a,,KeyError} is
raised for general mapping errors like specifying an incorrect key.
@end deffn

@geindex open() (dans le module dbm.gnu)
@anchor{library/dbm dbm gnu open}@anchor{19cd}
@deffn {Fonction} dbm.gnu.open (filename, flag='r', mode=0o666, /)

Open a GDBM database and return a @code{gdbm} object.

@*Paramètres: 

@itemize *

@item 
@code{filename} (@ref{29d,,path-like object}) -- The database file to open.

@item 
@code{flag} (@ref{435,,str}) -- 

@itemize *

@item 
@code{'r'} (default): Open existing database for reading only.

@item 
@code{'w'}: Open existing database for reading and writing.

@item 
@code{'c'}: Open database for reading and writing, creating it if it doesn't exist.

@item 
@code{'n'}: Always create a new, empty database, open for reading and writing.
@end itemize

The following additional characters may be appended
to control how the database is opened:


@itemize *

@item 
@code{'f'}: Open the database in fast mode.
Writes to the database will not be synchronized.

@item 
@code{'s'}: Synchronized mode.
Changes to the database will be written immediately to the file.

@item 
@code{'u'}: Do not lock database.
@end itemize

Not all flags are valid for all versions of GDBM.
See the @ref{2844,,open_flags} member for a list of supported flag characters.


@item 
@code{mode} (@ref{254,,int}) -- The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize


@*Lève: 
@ref{a88,,error} -- If an invalid `flag' argument is passed.



Modifié dans la version 3.11: `filename' accepts a @ref{29d,,path-like object}.


@geindex open_flags (dans le module dbm.gnu)
@anchor{library/dbm dbm gnu open_flags}@anchor{2844}
@deffn {Données} dbm.gnu.open_flags

A string of characters the `flag' parameter of @ref{19cd,,open()} supports.
@end deffn

@code{gdbm} objects behave similar to @ref{1199,,mappings},
but @code{items()} and @code{values()} methods are not supported.
The following methods are also provided:

@geindex firstkey() (méthode dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm firstkey}@anchor{2845}
@deffn {Méthode} gdbm.firstkey ()

It's possible to loop over every key in the database using this method  and the
@ref{2846,,nextkey()} method.  The traversal is ordered by GDBM's internal
hash values, and won't be sorted by the key values.  This method returns
the starting key.
@end deffn

@geindex nextkey() (méthode dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm nextkey}@anchor{2846}
@deffn {Méthode} gdbm.nextkey (key)

Returns the key that follows `key' in the traversal.  The following code prints
every key in the database @code{db}, without having to create a list in memory that
contains them all:

@example
k = db.firstkey()
while k is not None:
    print(k)
    k = db.nextkey(k)
@end example
@end deffn

@geindex reorganize() (méthode dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm reorganize}@anchor{2847}
@deffn {Méthode} gdbm.reorganize ()

If you have carried out a lot of deletions and would like to shrink the space
used by the GDBM file, this routine will reorganize the database.  @code{gdbm}
objects will not shorten the length of a database file except by using this
reorganization; otherwise, deleted file space will be kept and reused as new
(key, value) pairs are added.
@end deffn

@geindex sync() (méthode dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm sync}@anchor{2848}
@deffn {Méthode} gdbm.sync ()

When the database has been opened in fast mode, this method forces any
unwritten data to be written to the disk.
@end deffn

@geindex close() (méthode dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm close}@anchor{2849}
@deffn {Méthode} gdbm.close ()

Close the GDBM database.
@end deffn

@geindex clear() (méthode dbm.gnu.gdbm)
@anchor{library/dbm dbm gnu gdbm clear}@anchor{1d2}
@deffn {Méthode} gdbm.clear ()

Remove all items from the GDBM database.


Ajouté dans la version 3.13.

@end deffn
@end deffn

@node dbm ndbm --- New Database Manager,dbm dumb --- Portable DBM implementation,dbm gnu --- GNU database manager,dbm --- Interfaces to Unix "databases"
@anchor{library/dbm dbm-ndbm-new-database-manager}@anchor{284a}@anchor{library/dbm module-dbm ndbm}@anchor{34}
@subsubsection @code{dbm.ndbm} --- New Database Manager


@geindex module; dbm.ndbm

`Source code:' Lib/dbm/ndbm.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dbm/ndbm.py}


__________________________________________________________________


The @ref{34,,dbm.ndbm} module provides an interface to the
@abbr{NDBM,New Database Manager} library.
This module can be used with the "classic" NDBM interface or the
@abbr{GDBM} compatibility interface.

@cartouche
@quotation Note 
The file formats created by @ref{33,,dbm.gnu} and @ref{34,,dbm.ndbm} are incompatible
and can not be used interchangeably.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
The NDBM library shipped as part of macOS has an undocumented limitation on the
size of values, which can result in corrupted database files
when storing values larger than this limit. Reading such corrupted files can
result in a hard crash (segmentation fault).
@end quotation
@end cartouche

@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@geindex error
@anchor{library/dbm dbm ndbm error}@anchor{a89}
@deffn {Exception} dbm.ndbm.error

Raised on @ref{34,,dbm.ndbm}-specific errors, such as I/O errors. @ref{33a,,KeyError} is raised
for general mapping errors like specifying an incorrect key.
@end deffn

@geindex library (dans le module dbm.ndbm)
@anchor{library/dbm dbm ndbm library}@anchor{284b}
@deffn {Données} dbm.ndbm.library

Name of the NDBM implementation library used.
@end deffn

@geindex open() (dans le module dbm.ndbm)
@anchor{library/dbm dbm ndbm open}@anchor{19ce}
@deffn {Fonction} dbm.ndbm.open (filename, flag='r', mode=0o666, /)

Open an NDBM database and return an @code{ndbm} object.

@*Paramètres: 

@itemize *

@item 
@code{filename} (@ref{29d,,path-like object}) -- The basename of the database file
(without the @code{.dir} or @code{.pag} extensions).

@item 
@code{flag} (@ref{435,,str}) -- 

@itemize *

@item 
@code{'r'} (default): Open existing database for reading only.

@item 
@code{'w'}: Open existing database for reading and writing.

@item 
@code{'c'}: Open database for reading and writing, creating it if it doesn't exist.

@item 
@code{'n'}: Always create a new, empty database, open for reading and writing.
@end itemize


@item 
@code{mode} (@ref{254,,int}) -- The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize


@code{ndbm} objects behave similar to @ref{1199,,mappings},
but @code{items()} and @code{values()} methods are not supported.
The following methods are also provided:


Modifié dans la version 3.11: Accepts @ref{29d,,path-like object} for filename.


@geindex close() (méthode dbm.ndbm.ndbm)
@anchor{library/dbm dbm ndbm ndbm close}@anchor{284c}
@deffn {Méthode} ndbm.close ()

Close the NDBM database.
@end deffn

@geindex clear() (méthode dbm.ndbm.ndbm)
@anchor{library/dbm dbm ndbm ndbm clear}@anchor{1d3}
@deffn {Méthode} ndbm.clear ()

Remove all items from the NDBM database.


Ajouté dans la version 3.13.

@end deffn
@end deffn

@node dbm dumb --- Portable DBM implementation,,dbm ndbm --- New Database Manager,dbm --- Interfaces to Unix "databases"
@anchor{library/dbm dbm-dumb-portable-dbm-implementation}@anchor{284d}@anchor{library/dbm module-dbm dumb}@anchor{32}
@subsubsection @code{dbm.dumb} --- Portable DBM implementation


@geindex module; dbm.dumb

`Source code:' Lib/dbm/dumb.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dbm/dumb.py}

@geindex databases

@cartouche
@quotation Note 
The @ref{32,,dbm.dumb} module is intended as a last resort fallback for the
@ref{31,,dbm} module when a more robust module is not available. The @ref{32,,dbm.dumb}
module is not written for speed and is not nearly as heavily used as the other
database modules.
@end quotation
@end cartouche


__________________________________________________________________


The @ref{32,,dbm.dumb} module provides a persistent @ref{253,,dict}-like
interface which is written entirely in Python.
Unlike other @ref{31,,dbm} backends, such as @ref{33,,dbm.gnu}, no
external library is required.

The @code{dbm.dumb} module defines the following:

@geindex error
@anchor{library/dbm dbm dumb error}@anchor{a87}
@deffn {Exception} dbm.dumb.error

Raised on @ref{32,,dbm.dumb}-specific errors, such as I/O errors.  @ref{33a,,KeyError} is
raised for general mapping errors like specifying an incorrect key.
@end deffn

@geindex open() (dans le module dbm.dumb)
@anchor{library/dbm dbm dumb open}@anchor{a84}
@deffn {Fonction} dbm.dumb.open (filename, flag='c', mode=0o666)

Open a @code{dbm.dumb} database.
The returned database object behaves similar to a @ref{1199,,mapping},
in addition to providing @ref{284e,,sync()} and @ref{284f,,close()}
methods.

@*Paramètres: 

@itemize *

@item 
@code{filename} -- 
The basename of the database file (without extensions).
A new database creates the following files:


@itemize -

@item 
@code{`filename'.dat}

@item 
@code{`filename'.dir}
@end itemize


@item 
@code{flag} (@ref{435,,str}) -- 

@itemize *

@item 
@code{'r'}: Open existing database for reading only.

@item 
@code{'w'}: Open existing database for reading and writing.

@item 
@code{'c'} (default): Open database for reading and writing, creating it if it doesn't exist.

@item 
@code{'n'}: Always create a new, empty database, open for reading and writing.
@end itemize


@item 
@code{mode} (@ref{254,,int}) -- The Unix file access mode of the file (default: octal @code{0o666}),
used only when the database has to be created.
@end itemize


@cartouche
@quotation Avertissement 
It is possible to crash the Python interpreter when loading a database
with a sufficiently large/complex entry due to stack depth limitations in
Python's AST compiler.
@end quotation
@end cartouche


Modifié dans la version 3.5: @ref{a84,,open()} always creates a new database when `flag' is @code{'n'}.



Modifié dans la version 3.8: A database opened read-only if `flag' is @code{'r'}.
A database is not created if it does not exist if `flag' is @code{'r'} or @code{'w'}.



Modifié dans la version 3.11: `filename' accepts a @ref{29d,,path-like object}.


In addition to the methods provided by the
@ref{1090,,collections.abc.MutableMapping} class,
the following methods are provided:

@geindex sync() (méthode dbm.dumb.dumbdbm)
@anchor{library/dbm dbm dumb dumbdbm sync}@anchor{284e}
@deffn {Méthode} dumbdbm.sync ()

Synchronize the on-disk directory and data files.  This method is called
by the @code{Shelve.sync()} method.
@end deffn

@geindex close() (méthode dbm.dumb.dumbdbm)
@anchor{library/dbm dbm dumb dumbdbm close}@anchor{284f}
@deffn {Méthode} dumbdbm.close ()

Close the database.
@end deffn
@end deffn

@node sqlite3 --- DB-API 2 0 interface for SQLite databases,,dbm --- Interfaces to Unix "databases",Persistance des données
@anchor{library/sqlite3 doc}@anchor{2850}@anchor{library/sqlite3 module-sqlite3}@anchor{ce}@anchor{library/sqlite3 sqlite3-db-api-2-0-interface-for-sqlite-databases}@anchor{2851}
@subsection @code{sqlite3} --- DB-API 2.0 interface for SQLite databases


@geindex module; sqlite3

`Code source :' Lib/sqlite3/@footnote{https://github.com/python/cpython/tree/3.13/Lib/sqlite3/}

@c Make sure we always doctest the tutorial with an empty database.

@c import sqlite3
@c src = sqlite3.connect(":memory:", isolation_level=None)
@c dst = sqlite3.connect("tutorial.db", isolation_level=None)
@c src.backup(dst)
@c src.close()
@c dst.close()
@c del src, dst
@anchor{library/sqlite3 sqlite3-intro}@anchor{2852}
SQLite est une bibliothèque C qui fournit une base de données légère sur disque ne nécessitant pas de processus serveur et qui utilise une variante (non standard) du langage de requête SQL pour accéder aux données. Certaines applications peuvent utiliser SQLite pour le stockage de données internes. Il est également possible de créer une application prototype utilisant SQLite, puis de modifier le code pour utiliser une base de données plus robuste telle que PostgreSQL ou Oracle.

The @code{sqlite3} module was written by Gerhard Häring.  It provides an SQL interface
compliant with the DB-API 2.0 specification described by 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}, and
requires SQLite 3.15.2 or newer.

Ce document inclus 4 sections principales :


@itemize *

@item 
@ref{2853,,tutoriel sqlite3} explique comment utiliser le module @code{sqlite3}.

@item 
@ref{2854,,référence sqlite3} décrit les classes et les fonctions que ce module définit.

@item 
@ref{2855,,guide sqlite3} détaille comment gérer des tâches spécifiques.

@item 
@ref{2856,,explications sqlite3} propose un contexte détaillé du contrôle de transaction.
@end itemize


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://www.sqlite.org}

Dans la page Web de SQLite, la documentation décrit la syntaxe et les types de données disponibles qui sont pris en charge par cette variante SQL.

@item @indicateurl{https://www.w3schools.com/sql/}

Tutoriel, référence et exemples pour apprendre la syntaxe SQL.

@geindex Python Enhancement Proposals; PEP 249

@item PEP 249@footnote{https://peps.python.org/pep-0249/} — Spécifications de l'API 2.0 pour la base de données

PEP écrite par Marc-André Lemburg.
@end table


@c We use the following practises for SQL code:
@c - UPPERCASE for keywords
@c - snake_case for schema
@c - single quotes for string literals
@c - singular for table names
@c - if needed, use double quotes for table and column names

@menu
* Tutoriel:: 
* Références: Références<2>. 
* How-to guides:: 
* Explanation:: 

@end menu

@node Tutoriel,Références<2>,,sqlite3 --- DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 sqlite3-tutorial}@anchor{2853}@anchor{library/sqlite3 tutorial}@anchor{2857}
@subsubsection Tutoriel


Dans ce tutoriel, vous allez créer une base de données des films des Monty Python en utilisant les fonctionnalités de base de @code{sqlite3}. Cela nécessite une compréhension élémentaire des concepts des bases de données, notamment les curseurs@footnote{https://en.wikipedia.org/wiki/Cursor_(databases)} et les transactions@footnote{https://en.wikipedia.org/wiki/Database_transaction}.

Tout d’abord, nous devons créer une nouvelle base de données et ouvrir une connexion à la base de données pour permettre à @code{sqlite3} de travailler avec elle. Appelez @ref{2a5,,sqlite3.connect()} pour créer une connexion à la base de données @code{tutorial.db} dans le répertoire de travail actuel, en la créant implicitement si elle n’existe pas :

@example
import sqlite3
con = sqlite3.connect("tutorial.db")
@end example

L’objet @ref{242,,Connection} renvoyé — @code{con} — représente la connexion à la base de données sur disque.

Afin d’exécuter les instructions SQL et de récupérer les résultats des requêtes SQL, nous devrons utiliser un curseur de base de données. Appelez @ref{2858,,con.cursor()} pour créer la @ref{2859,,Cursor} :

@example
cur = con.cursor()
@end example

Maintenant que nous avons une connexion à la base de données et un curseur, nous pouvons créer une table @code{movie} avec des colonnes pour le titre, l’année de sortie et la note de la critique. Pour plus de simplicité, nous pouvons simplement utiliser les noms des colonnes dans la déclaration de la table — grâce à la fonctionnalité de typage flexible@footnote{https://www.sqlite.org/flextypegood.html} de SQLite, spécifier les types de données est facultatif. Exécutez l’instruction @code{CREATE TABLE} en appelant @ref{2cf,,cur.execute(…)} :

@example
cur.execute("CREATE TABLE movie(title, year, score)")
@end example

@c Ideally, we'd use sqlite_schema instead of sqlite_master below,
@c but SQLite versions older than 3.33.0 do not recognise that variant.

Nous pouvons vérifier que la nouvelle table a été créée en interrogeant la table @code{sqlite_master} intégrée à SQLite, qui devrait maintenant contenir une entrée pour la définition de la table @code{movie} (voir le schéma Table@footnote{https://www.sqlite.org/schematab.html} pour plus de détails). Exécutez cette requête en appelant @ref{2cf,,cur.execute(…)}, affectez le résultat à @code{res}, et appelez @ref{285a,,res.fetchone()} pour récupérer la ligne résultante :

@example
>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)
@end example

We can see that the table has been created,
as the query returns a @ref{366,,tuple} containing the table's name.
If we query @code{sqlite_master} for a non-existent table @code{spam},
@code{res.fetchone()} will return @code{None}:

@example
>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True
@end example

Maintenant, ajoutez deux lignes de données en tant que littéraux SQL en exécutant une instruction @code{INSERT}, une fois encore en appelant @ref{2cf,,cur.execute(…)} :

@example
cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")
@end example

L’instruction @code{INSERT} ouvre implicitement une transaction, qui doit être validée avant que les modifications ne soient enregistrées dans la base de données (voir @ref{285b,,contrôle des transactions SQL} pour plus de détails). Appelez @ref{285c,,con.commit()} sur l’objet de connexion pour valider la transaction :

@example
con.commit()
@end example

Nous pouvons vérifier que les données ont été insérées correctement en exécutant une requête @code{SELECT}. Utilisez la désormais familière @ref{2cf,,cur.execute(…)} pour affecter le résultat à @code{res}, et appelez @ref{285d,,res.fetchall()} pour retourner toutes les lignes résultantes :

@example
>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]
@end example

Le résultat est une @ref{5fc,,liste} de deux @code{tuple}s, une par ligne, chacun contenant la valeur @code{score} de cette ligne.

Maintenant, insérez trois lignes supplémentaires en appelant @ref{2d0,,cur.executemany(…)} :

@example
data = [
    ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
    ("Monty Python's The Meaning of Life", 1983, 7.5),
    ("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit()  # Remember to commit the transaction after executing INSERT.
@end example

Remarquez que les marqueurs @code{?} sont utilisés pour lier les @code{data} à la requête. Utilisez toujours les marqueurs au lieu d’@ref{1c01,,expressions formatées} pour lier les valeurs Python aux instructions SQL, afin d’éviter les injections SQL@footnote{https://en.wikipedia.org/wiki/SQL_injection} (voir @ref{2d1,,placeholder SQL} pour plus de détails).

Nous pouvons vérifier que les nouvelles lignes ont été insérées en exécutant une requête @code{SELECT}, cette fois-ci en itérant sur les résultats de la requête :

@example
>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
...     print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")
@end example

Chaque ligne est un @ref{366,,tuple} de deux éléments @code{(année, titre)}, correspondant aux colonnes sélectionnées dans la requête.

Enfin, vérifiez que la base de données a été écrite sur le disque en appelant @ref{243,,con.close()} pour fermer la connexion existante, en ouvrir une nouvelle, créer un nouveau curseur, puis interroger la base de données :

@example
>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is @{title!r@}, released in @{year@}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
>>> new_con.close()
@end example

Vous avez maintenant créé une base de données SQLite à l’aide du module @code{sqlite3}, inséré des données et récupéré des valeurs de plusieurs façons.


@subsubheading Voir aussi



@itemize *

@item 
@ref{2855,,guide sqlite3} pour une lecture plus poussée :


@itemize *

@item 
@ref{2d1,,placeholders sqlite3}

@item 
@ref{285e,,adaptateurs sqlite3}

@item 
@ref{285f,,convertisseurs sqlite3}

@item 
@ref{1771,,gestionnaire de contexte de connexion sqlite3}

@item 
@ref{2860,,guide de fabrique de ligne sqlite3}
@end itemize

@item 
@ref{2856,,explications sqlite3} pour un contexte détaillé du contrôle de transaction.
@end itemize


@node Références<2>,How-to guides,Tutoriel,sqlite3 --- DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 reference}@anchor{2861}@anchor{library/sqlite3 sqlite3-reference}@anchor{2854}
@subsubsection Références


@c We keep the old sqlite3-module-contents ref to prevent breaking links.
@anchor{library/sqlite3 sqlite3-module-contents}@anchor{2862}
@menu
* Fonctions du module:: 
* Fonctions et constantes du module:: 
* Connection objects:: 
* Cursor objects:: 
* Row objects:: 
* Blob objects:: 
* PrepareProtocol objects:: 
* Exceptions: Exceptions<7>. 
* SQLite and Python types:: 
* Default adapters and converters (deprecated): Default adapters and converters deprecated. 
* Command-line interface:: 

@end menu

@node Fonctions du module,Fonctions et constantes du module,,Références<2>
@anchor{library/sqlite3 module-functions}@anchor{2863}@anchor{library/sqlite3 sqlite3-module-functions}@anchor{2864}
@subsubsection Fonctions du module


@geindex connect() (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 connect}@anchor{2a5}
@deffn {Fonction} sqlite3.connect (database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)

Ouvrez une connexion à une base de données SQLite.

@*Paramètres: 

@itemize *

@item 
@code{database} (@ref{29d,,path-like object}) -- Le chemin d’accès au fichier de la base de données à ouvrir. Passez @code{":memory :"} pour créer une base de données SQLite existant uniquement en mémoire@footnote{https://sqlite.org/inmemorydb.html}, et ouvrir une connexion à celle-ci.

@item 
@code{timeout} (@ref{2eb,,float}) -- Le temps (en secondes) que la connexion doit attendre avant de lever une @ref{182b,,OperationalError}, si la table est verrouillée. Si une autre connexion ouvre une transaction pour modifier la table, celle-ci sera verrouillée jusqu’à ce que cette transaction soit validée. Par défaut, cinq secondes.

@item 
@code{detect_types} (@ref{254,,int}) -- Contrôle si et comment les types de données non @ref{2865,,nativement pris en charge par SQLite} sont recherchés pour être convertis en types Python, en utilisant les convertisseurs enregistrés avec @ref{2866,,register_converter()}. Définissez-le à n’importe quelle combinaison (en utilisant @code{|}, opérateurs bit-à-bit OR) de @ref{2867,,PARSE_DECLTYPES} et @ref{2868,,PARSE_COLNAMES} pour activer ceci. Les noms de colonnes ont la priorité sur les types déclarés si les deux drapeaux sont activés. Les types ne peuvent pas être détectés pour les champs générés (par exemple @code{max(data)}), même si le paramètre `detect_types' est activé ; @ref{435,,str} sera retourné à la place. Par défaut (@code{0}), la détection des types est désactivée.

@item 
@code{isolation_level} (@ref{435,,str}@code{ | }@code{None}) -- Control legacy transaction handling behaviour.
See @ref{2869,,Connection.isolation_level} and
@ref{286a,,Transaction control via the isolation_level attribute} for more information.
Can be @code{"DEFERRED"} (default), @code{"EXCLUSIVE"} or @code{"IMMEDIATE"};
or @code{None} to disable opening transactions implicitly.
Has no effect unless @ref{49f,,Connection.autocommit} is set to
@ref{286b,,LEGACY_TRANSACTION_CONTROL} (the default).

@item 
@code{check_same_thread} (@ref{451,,bool}) -- Si @code{True} (par défaut), @ref{4dc,,ProgrammingError} sera levée si la connexion à la base de données est utilisée par un thread autre que celui qui l’a créée. Si @code{False}, la connexion peut être utilisée par plusieurs threads ; les opérations d’écriture devront peut-être être sérialisées par l’utilisateur pour éviter la corruption des données. Voir @ref{667,,sécurité des threads} pour plus d’informations.

@item 
@code{factory} (@ref{242,,Connection}) -- Une sous-classe personnalisée de @ref{242,,Connection} pour créer la connexion, si ce n’est pas la classe par défaut @ref{242,,Connection}.

@item 
@code{cached_statements} (@ref{254,,int}) -- Le nombre d’instructions que @code{sqlite3} doit mettre en cache en interne pour cette connexion, afin d’éviter les surcharges d’analyse. Par défaut, 128 instructions.

@item 
@code{uri} (@ref{451,,bool}) -- Si elle a pour valeur @code{True}, la base de données est interprétée comme un @abbr{URI,Uniform Resource Identifier} avec un chemin d’accès au fichier et une chaîne de requête facultative. La partie schéma `doit' être @code{"file:"}, et le chemin peut être relatif ou absolu. La chaîne d’interrogation permet de passer des paramètres à SQLite, ce qui permet d’activer diverses @ref{286c,,astuces d’URI sqlite3}.

@item 
@code{autocommit} (@ref{451,,bool}) -- Control 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/} transaction handling behaviour.
See @ref{49f,,Connection.autocommit} and
@ref{4a0,,Transaction control via the autocommit attribute} for more information.
`autocommit' currently defaults to
@ref{286b,,LEGACY_TRANSACTION_CONTROL}.
The default will change to @code{False} in a future Python release.
@end itemize


@*Type renvoyé: 
@ref{242,,Connection}


Raises an @ref{1848,,auditing event} @code{sqlite3.connect} with argument @code{database}.

Raises an @ref{1848,,auditing event} @code{sqlite3.connect/handle} with argument @code{connection_handle}.


Modifié dans la version 3.4: Added the `uri' parameter.



Modifié dans la version 3.7: `database' peut maintenant aussi être un @ref{29d,,objet de type chemin}, et pas seulement une chaîne de caractères.



Modifié dans la version 3.10: Added the @code{sqlite3.connect/handle} auditing event.



Modifié dans la version 3.12: Added the `autocommit' parameter.



Modifié dans la version 3.13: Positional use of the parameters `timeout', `detect_types',
`isolation_level', `check_same_thread', `factory', `cached_statements',
and `uri' is deprecated.
They will become keyword-only parameters in Python 3.15.

@end deffn

@geindex complete_statement() (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 complete_statement}@anchor{286d}
@deffn {Fonction} sqlite3.complete_statement (statement)

Renvoie @code{True} si la déclaration de la chaîne semble contenir une ou plusieurs déclarations SQL complètes. Aucune vérification syntaxique ou analyse syntaxique d’aucune sorte n’est effectuée, si ce n’est la vérification qu’il n’y a pas de chaîne littérale non fermée et que l’instruction se termine par un point-virgule.

Exemple :

@example
>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False
@end example

Cette fonction peut être utile pendant la saisie en ligne de commande pour déterminer si le texte saisi semble former une instruction SQL complète, ou si une saisie supplémentaire est nécessaire avant d’appeler @ref{2cf,,execute()}.

See @code{runsource()} in Lib/sqlite3/__main__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/sqlite3/__main__.py}
for real-world use.
@end deffn

@geindex enable_callback_tracebacks() (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 enable_callback_tracebacks}@anchor{286e}
@deffn {Fonction} sqlite3.enable_callback_tracebacks (flag, /)

Activer ou désactiver les traces des fonctions de rappel. Par défaut, vous n’obtiendrez pas de traces de pile d’appels dans les fonctions définies par l’utilisateur, les agrégats, les convertisseurs, les fonctions de rappel des mécanismes d’autorisation, etc. Si vous voulez les déboguer, vous pouvez appeler cette fonction avec `flag' à @code{True}. Ensuite, vous obtiendrez les traces des fonctions de rappel sur @ref{926,,sys.stderr}. Utilisez @code{False} pour désactiver à nouveau cette fonctionnalité.

@cartouche
@quotation Note 
Errors in user-defined function callbacks are logged as unraisable exceptions.
Use an @ref{1f4,,unraisable hook handler} for
introspection of the failed callback.
@end quotation
@end cartouche
@end deffn

@geindex register_adapter() (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 register_adapter}@anchor{286f}
@deffn {Fonction} sqlite3.register_adapter (type, adapter, /)

Enregistre un `adaptateur' @ref{2870,,callable} pour adapter le type Python `type' en un type SQLite. L'adaptateur est appelé avec un objet Python de type `type' comme seul argument, et doit retourner une valeur d'un @ref{2865,,type que SQLite comprend nativement}.
@end deffn

@geindex register_converter() (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 register_converter}@anchor{2866}
@deffn {Fonction} sqlite3.register_converter (typename, converter, /)

Enregistrer le `convertisseur' @ref{2870,,callable} pour convertir les objets SQLite de type `typename' en un objet Python d'un type spécifique. Le convertisseur est invoqué pour toutes les valeurs SQLite de type `typename' ; on lui passe un objet @ref{1bd,,bytes} et il doit retourner un objet du type Python désiré. Consultez le paramètre `detect_types' de @ref{2a5,,connect()} pour plus d'informations sur le fonctionnement de la détection de type.

Remarque : `typename' et le nom du type dans votre requête sont comparés sans tenir compte de la casse.
@end deffn

@node Fonctions et constantes du module,Connection objects,Fonctions du module,Références<2>
@anchor{library/sqlite3 module-constants}@anchor{2871}@anchor{library/sqlite3 sqlite3-module-constants}@anchor{2872}
@subsubsection Fonctions et constantes du module


@geindex LEGACY_TRANSACTION_CONTROL (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 LEGACY_TRANSACTION_CONTROL}@anchor{286b}
@deffn {Données} sqlite3.LEGACY_TRANSACTION_CONTROL

Set @ref{49f,,autocommit} to this constant to select
old style (pre-Python 3.12) transaction control behaviour.
See @ref{286a,,Transaction control via the isolation_level attribute} for more information.
@end deffn

@geindex PARSE_COLNAMES (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 PARSE_COLNAMES}@anchor{2868}
@deffn {Données} sqlite3.PARSE_COLNAMES

Pass this flag value to the `detect_types' parameter of
@ref{2a5,,connect()} to look up a converter function by
using the type name, parsed from the query column name,
as the converter dictionary key.
The type name must be wrapped in square brackets (@code{[]}).

@example
SELECT p as "p [point]" FROM test;  ! will look up converter "point"
@end example

This flag may be combined with @ref{2867,,PARSE_DECLTYPES} using the @code{|}
(bitwise or) operator.
@end deffn

@geindex PARSE_DECLTYPES (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 PARSE_DECLTYPES}@anchor{2867}
@deffn {Données} sqlite3.PARSE_DECLTYPES

Pass this flag value to the `detect_types' parameter of
@ref{2a5,,connect()} to look up a converter function using
the declared types for each column.
The types are declared when the database table is created.
@code{sqlite3} will look up a converter function using the first word of the
declared type as the converter dictionary key.
For example:

@example
CREATE TABLE test(
   i integer primary key,  ! will look up a converter named "integer"
   p point,                ! will look up a converter named "point"
   n number(10)            ! will look up a converter named "number"
 )
@end example

This flag may be combined with @ref{2868,,PARSE_COLNAMES} using the @code{|}
(bitwise or) operator.
@end deffn

@geindex SQLITE_OK (dans le module sqlite3)
@geindex SQLITE_DENY (dans le module sqlite3)
@geindex SQLITE_IGNORE (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 SQLITE_OK}@anchor{2873}
@deffn {Données} sqlite3.SQLITE_OK
@anchor{library/sqlite3 sqlite3 SQLITE_DENY}@anchor{2874}
@deffnx {Données} sqlite3.SQLITE_DENY
@anchor{library/sqlite3 sqlite3 SQLITE_IGNORE}@anchor{2875}
@deffnx {Données} sqlite3.SQLITE_IGNORE

Flags that should be returned by the `authorizer_callback' @ref{2870,,callable}
passed to @ref{2a8,,Connection.set_authorizer()}, to indicate whether:


@itemize *

@item 
Access is allowed (@code{SQLITE_OK}),

@item 
The SQL statement should be aborted with an error (@code{SQLITE_DENY})

@item 
The column should be treated as a @code{NULL} value (@code{SQLITE_IGNORE})
@end itemize
@end deffn

@geindex apilevel (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 apilevel}@anchor{2876}
@deffn {Données} sqlite3.apilevel

String constant stating the supported DB-API level. Required by the DB-API.
Hard-coded to @code{"2.0"}.
@end deffn

@geindex paramstyle (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 paramstyle}@anchor{2877}
@deffn {Données} sqlite3.paramstyle

String constant stating the type of parameter marker formatting expected by
the @code{sqlite3} module. Required by the DB-API. Hard-coded to
@code{"qmark"}.

@cartouche
@quotation Note 
The @code{named} DB-API parameter style is also supported.
@end quotation
@end cartouche
@end deffn

@geindex sqlite_version (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 sqlite_version}@anchor{2878}
@deffn {Données} sqlite3.sqlite_version

Version number of the runtime SQLite library as a @ref{435,,string}.
@end deffn

@geindex sqlite_version_info (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 sqlite_version_info}@anchor{2879}
@deffn {Données} sqlite3.sqlite_version_info

Version number of the runtime SQLite library as a @ref{366,,tuple} of
@ref{254,,integers}.
@end deffn

@geindex threadsafety (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 threadsafety}@anchor{667}
@deffn {Données} sqlite3.threadsafety

Integer constant required by the DB-API 2.0, stating the level of thread
safety the @code{sqlite3} module supports. This attribute is set based on
the default threading mode@footnote{https://sqlite.org/threadsafe.html} the
underlying SQLite library is compiled with. The SQLite threading modes are:


@enumerate 

@item 
`Single-thread': In this mode, all mutexes are disabled and SQLite is
unsafe to use in more than a single thread at once.

@item 
`Multi-thread': In this mode, SQLite can be safely used by multiple
threads provided that no single database connection is used
simultaneously in two or more threads.

@item 
`Serialized': In serialized mode, SQLite can be safely used by
multiple threads with no restriction.
@end enumerate

The mappings from SQLite threading modes to DB-API 2.0 threadsafety levels
are as follows:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

SQLite threading
mode

@tab

@geindex Python Enhancement Proposals; PEP 0249#threadsafety
threadsafety@footnote{https://peps.python.org/pep-0249/#threadsafety}

@tab

SQLITE_THREADSAFE@footnote{https://sqlite.org/compile.html#threadsafe}

@tab

DB-API 2.0 meaning

@item

single-thread

@tab

0

@tab

0

@tab

Threads may not share the
module

@item

multi-thread

@tab

1

@tab

2

@tab

Threads may share the module,
but not connections

@item

serialized

@tab

3

@tab

1

@tab

Threads may share the module,
connections and cursors

@end multitable



Modifié dans la version 3.11: Set `threadsafety' dynamically instead of hard-coding it to @code{1}.

@end deffn

@geindex version (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 version}@anchor{2cd}
@deffn {Données} sqlite3.version

Version number of this module as a @ref{435,,string}.
This is not the version of the SQLite library.


Deprecated since version 3.12, will be removed in version 3.14: This constant used to reflect the version number of the @code{pysqlite}
package, a third-party library which used to upstream changes to
@code{sqlite3}. Today, it carries no meaning or practical value.

@end deffn

@geindex version_info (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3 version_info}@anchor{2ce}
@deffn {Données} sqlite3.version_info

Version number of this module as a @ref{366,,tuple} of @ref{254,,integers}.
This is not the version of the SQLite library.


Deprecated since version 3.12, will be removed in version 3.14: This constant used to reflect the version number of the @code{pysqlite}
package, a third-party library which used to upstream changes to
@code{sqlite3}. Today, it carries no meaning or practical value.

@end deffn

@geindex SQLITE_DBCONFIG_DEFENSIVE (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_DQS_DDL (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_DQS_DML (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_FKEY (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_QPSG (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_TRIGGER (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_ENABLE_VIEW (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_LEGACY_ALTER_TABLE (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_LEGACY_FILE_FORMAT (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_RESET_DATABASE (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_TRIGGER_EQP (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_TRUSTED_SCHEMA (dans le module sqlite3)
@geindex SQLITE_DBCONFIG_WRITABLE_SCHEMA (dans le module sqlite3)
@anchor{library/sqlite3 sqlite3-dbconfig-constants}@anchor{287a}@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DEFENSIVE}@anchor{287b}
@deffn {Données} sqlite3.SQLITE_DBCONFIG_DEFENSIVE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DQS_DDL}@anchor{287c}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_DQS_DDL
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_DQS_DML}@anchor{287d}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_DQS_DML
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_FKEY}@anchor{287e}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER}@anchor{287f}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION}@anchor{2880}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_QPSG}@anchor{2881}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_TRIGGER}@anchor{2882}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_ENABLE_VIEW}@anchor{2883}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_LEGACY_ALTER_TABLE}@anchor{2884}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_LEGACY_FILE_FORMAT}@anchor{2885}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE}@anchor{2886}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_RESET_DATABASE}@anchor{2887}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_RESET_DATABASE
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_TRIGGER_EQP}@anchor{2888}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_TRUSTED_SCHEMA}@anchor{2889}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA
@anchor{library/sqlite3 sqlite3 SQLITE_DBCONFIG_WRITABLE_SCHEMA}@anchor{288a}
@deffnx {Données} sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA

These constants are used for the @ref{4a3,,Connection.setconfig()}
and @ref{4a2,,getconfig()} methods.

The availability of these constants varies depending on the version of SQLite
Python was compiled with.


Ajouté dans la version 3.12.



@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://www.sqlite.org/c3ref/c_dbconfig_defensive.html}

SQLite docs: Database Connection Configuration Options
@end table

@end deffn

@node Connection objects,Cursor objects,Fonctions et constantes du module,Références<2>
@anchor{library/sqlite3 connection-objects}@anchor{288b}@anchor{library/sqlite3 sqlite3-connection-objects}@anchor{288c}
@subsubsection Connection objects


@geindex Connection (classe dans sqlite3)
@anchor{library/sqlite3 sqlite3 Connection}@anchor{242}
@deffn {Classe} sqlite3.Connection

Each open SQLite database is represented by a @code{Connection} object,
which is created using @ref{2a5,,sqlite3.connect()}.
Their main purpose is creating @ref{2859,,Cursor} objects,
and @ref{285b,,Transaction control}.


@subsubheading Voir aussi



@itemize *

@item 
@ref{288d,,How to use connection shortcut methods}

@item 
@ref{1771,,gestionnaire de contexte de connexion sqlite3}
@end itemize



Modifié dans la version 3.13: A @ref{241,,ResourceWarning} is emitted if @ref{243,,close()} is not called before
a @code{Connection} object is deleted.


An SQLite database connection has the following attributes and methods:

@geindex cursor() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection cursor}@anchor{2858}
@deffn {Méthode} cursor (factory=Cursor)

Create and return a @ref{2859,,Cursor} object.
The cursor method accepts a single optional parameter `factory'. If
supplied, this must be a @ref{2870,,callable} returning
an instance of @ref{2859,,Cursor} or its subclasses.
@end deffn

@geindex blobopen() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection blobopen}@anchor{66c}
@deffn {Méthode} blobopen (table, column, row, /, *, readonly=False, name='main')

Open a @ref{66d,,Blob} handle to an existing
@abbr{BLOB,Binary Large OBject}.

@*Paramètres: 

@itemize *

@item 
@code{table} (@ref{435,,str}) -- The name of the table where the blob is located.

@item 
@code{column} (@ref{435,,str}) -- The name of the column where the blob is located.

@item 
@code{row} (@ref{435,,str}) -- The name of the row where the blob is located.

@item 
@code{readonly} (@ref{451,,bool}) -- Set to @code{True} if the blob should be opened without write
permissions.
Defaults to @code{False}.

@item 
@code{name} (@ref{435,,str}) -- The name of the database where the blob is located.
Defaults to @code{"main"}.
@end itemize


@*Lève: 
@ref{182b,,OperationalError} -- When trying to open a blob in a @code{WITHOUT ROWID} table.


@*Type renvoyé: 
@ref{66d,,Blob}


@cartouche
@quotation Note 
The blob size cannot be changed using the @ref{66d,,Blob} class.
Use the SQL function @code{zeroblob} to create a blob with a fixed size.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex commit() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection commit}@anchor{285c}
@deffn {Méthode} commit ()

Commit any pending transaction to the database.
If @ref{49f,,autocommit} is @code{True}, or there is no open transaction,
this method does nothing.
If @code{autocommit} is @code{False}, a new transaction is implicitly
opened if a pending transaction was committed by this method.
@end deffn

@geindex rollback() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection rollback}@anchor{288e}
@deffn {Méthode} rollback ()

Roll back to the start of any pending transaction.
If @ref{49f,,autocommit} is @code{True}, or there is no open transaction,
this method does nothing.
If @code{autocommit} is @code{False}, a new transaction is implicitly
opened if a pending transaction was rolled back by this method.
@end deffn

@geindex close() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection close}@anchor{243}
@deffn {Méthode} close ()

Close the database connection.
If @ref{49f,,autocommit} is @code{False},
any pending transaction is implicitly rolled back.
If @code{autocommit} is @code{True} or @ref{286b,,LEGACY_TRANSACTION_CONTROL},
no implicit transaction control is executed.
Make sure to @ref{285c,,commit()} before closing
to avoid losing pending changes.
@end deffn

@geindex execute() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection execute}@anchor{288f}
@deffn {Méthode} execute (sql, parameters=(), /)

Create a new @ref{2859,,Cursor} object and call
@ref{2cf,,execute()} on it with the given `sql' and `parameters'.
Return the new cursor object.
@end deffn

@geindex executemany() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection executemany}@anchor{2890}
@deffn {Méthode} executemany (sql, parameters, /)

Create a new @ref{2859,,Cursor} object and call
@ref{2d0,,executemany()} on it with the given `sql' and `parameters'.
Return the new cursor object.
@end deffn

@geindex executescript() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection executescript}@anchor{2891}
@deffn {Méthode} executescript (sql_script, /)

Create a new @ref{2859,,Cursor} object and call
@ref{2892,,executescript()} on it with the given `sql_script'.
Return the new cursor object.
@end deffn

@geindex create_function() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_function}@anchor{2a6}
@deffn {Méthode} create_function (name, narg, func, *, deterministic=False)

Create or remove a user-defined SQL function.

@*Paramètres: 

@itemize *

@item 
@code{name} (@ref{435,,str}) -- The name of the SQL function.

@item 
@code{narg} (@ref{254,,int}) -- The number of arguments the SQL function can accept.
If @code{-1}, it may take any number of arguments.

@item 
@code{func} (@ref{2893,,callback} | None) -- A @ref{2870,,callable} that is called when the SQL function is invoked.
The callable must return @ref{2865,,a type natively supported by SQLite}.
Set to @code{None} to remove an existing SQL function.

@item 
@code{deterministic} (@ref{451,,bool}) -- If @code{True}, the created SQL function is marked as
deterministic@footnote{https://sqlite.org/deterministic.html},
which allows SQLite to perform additional optimizations.
@end itemize



Modifié dans la version 3.8: Added the `deterministic' parameter.


Exemple :

@example
>>> import hashlib
>>> def md5sum(t):
...     return hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
...     print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)
>>> con.close()
@end example


Modifié dans la version 3.13: Passing `name', `narg', and `func' as keyword arguments is deprecated.
These parameters will become positional-only in Python 3.15.

@end deffn

@geindex create_aggregate() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_aggregate}@anchor{2a7}
@deffn {Méthode} create_aggregate (name, n_arg, aggregate_class)

Create or remove a user-defined SQL aggregate function.

@*Paramètres: 

@itemize *

@item 
@code{name} (@ref{435,,str}) -- The name of the SQL aggregate function.

@item 
@code{n_arg} (@ref{254,,int}) -- The number of arguments the SQL aggregate function can accept.
If @code{-1}, it may take any number of arguments.

@item 
@code{aggregate_class} (@ref{18bf,,class} | None) -- 
A class must implement the following methods:


@itemize *

@item 
@code{step()}: Add a row to the aggregate.

@item 
@code{finalize()}: Return the final result of the aggregate as
@ref{2865,,a type natively supported by SQLite}.
@end itemize

The number of arguments that the @code{step()} method must accept
is controlled by `n_arg'.

Set to @code{None} to remove an existing SQL aggregate function.

@end itemize


Exemple :

@example
class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])

con.close()
@end example

@c 3


Modifié dans la version 3.13: Passing `name', `n_arg', and `aggregate_class' as keyword arguments is deprecated.
These parameters will become positional-only in Python 3.15.

@end deffn

@geindex create_window_function() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_window_function}@anchor{66b}
@deffn {Méthode} create_window_function (name, num_params, aggregate_class, /)

Create or remove a user-defined aggregate window function.

@*Paramètres: 

@itemize *

@item 
@code{name} (@ref{435,,str}) -- The name of the SQL aggregate window function to create or remove.

@item 
@code{num_params} (@ref{254,,int}) -- The number of arguments the SQL aggregate window function can accept.
If @code{-1}, it may take any number of arguments.

@item 
@code{aggregate_class} (@ref{18bf,,class} | None) -- 
A class that must implement the following methods:


@itemize *

@item 
@code{step()}: Add a row to the current window.

@item 
@code{value()}: Return the current value of the aggregate.

@item 
@code{inverse()}: Remove a row from the current window.

@item 
@code{finalize()}: Return the final result of the aggregate as
@ref{2865,,a type natively supported by SQLite}.
@end itemize

The number of arguments that the @code{step()} and @code{value()} methods
must accept is controlled by `num_params'.

Set to @code{None} to remove an existing SQL aggregate window function.

@end itemize


@*Lève: 
@ref{2894,,NotSupportedError} -- If used with a version of SQLite older than 3.25.0,
which does not support aggregate window functions.



Ajouté dans la version 3.11.


Exemple :

@example
# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Add a row to the current window."""
        self.count += value

    def value(self):
        """Return the current value of the aggregate."""
        return self.count

    def inverse(self, value):
        """Remove a row from the current window."""
        self.count -= value

    def finalize(self):
        """Return the final value of the aggregate.

        Any clean-up actions should be placed here.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())
con.close()
@end example

@c [('a', 9), ('b', 12), ('c', 16), ('d', 12), ('e', 9)]
@end deffn

@geindex create_collation() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection create_collation}@anchor{661}
@deffn {Méthode} create_collation (name, callable, /)

Create a collation named `name' using the collating function `callable'.
`callable' is passed two @ref{435,,string} arguments,
and it should return an @ref{254,,integer}:


@itemize *

@item 
@code{1} if the first is ordered higher than the second

@item 
@code{-1} if the first is ordered lower than the second

@item 
@code{0} if they are ordered equal
@end itemize

The following example shows a reverse sorting collation:

@example
def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
for row in cur:
    print(row)
con.close()
@end example

@c ('b',)
@c ('a',)

Remove a collation function by setting `callable' to @code{None}.


Modifié dans la version 3.11: The collation name can contain any Unicode character.  Earlier, only
ASCII characters were allowed.

@end deffn

@geindex interrupt() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection interrupt}@anchor{2895}
@deffn {Méthode} interrupt ()

Call this method from a different thread to abort any queries that might
be executing on the connection.
Aborted queries will raise an @ref{182b,,OperationalError}.
@end deffn

@geindex set_authorizer() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection set_authorizer}@anchor{2a8}
@deffn {Méthode} set_authorizer (authorizer_callback)

Register @ref{2870,,callable} `authorizer_callback' to be invoked
for each attempt to access a column of a table in the database.
The callback should return one of @ref{2873,,SQLITE_OK},
@ref{2874,,SQLITE_DENY}, or @ref{2875,,SQLITE_IGNORE}
to signal how access to the column should be handled
by the underlying SQLite library.

The first argument to the callback signifies what kind of operation is to be
authorized. The second and third argument will be arguments or @code{None}
depending on the first argument. The 4th argument is the name of the database
("main", "temp", etc.) if applicable. The 5th argument is the name of the
inner-most trigger or view that is responsible for the access attempt or
@code{None} if this access attempt is directly from input SQL code.

Please consult the SQLite documentation about the possible values for the first
argument and the meaning of the second and third argument depending on the first
one. All necessary constants are available in the @code{sqlite3} module.

Passing @code{None} as `authorizer_callback' will disable the authorizer.


Modifié dans la version 3.11: Added support for disabling the authorizer using @code{None}.



Modifié dans la version 3.13: Passing `authorizer_callback' as a keyword argument is deprecated.
The parameter will become positional-only in Python 3.15.

@end deffn

@geindex set_progress_handler() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection set_progress_handler}@anchor{2a9}
@deffn {Méthode} set_progress_handler (progress_handler, n)

Register @ref{2870,,callable} `progress_handler' to be invoked for every `n'
instructions of the SQLite virtual machine. This is useful if you want to
get called from SQLite during long-running operations, for example to update
a GUI.

If you want to clear any previously installed progress handler, call the
method with @code{None} for `progress_handler'.

Returning a non-zero value from the handler function will terminate the
currently executing query and cause it to raise a @ref{2896,,DatabaseError}
exception.


Modifié dans la version 3.13: Passing `progress_handler' as a keyword argument is deprecated.
The parameter will become positional-only in Python 3.15.

@end deffn

@geindex set_trace_callback() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection set_trace_callback}@anchor{2aa}
@deffn {Méthode} set_trace_callback (trace_callback)

Register @ref{2870,,callable} `trace_callback' to be invoked
for each SQL statement that is actually executed by the SQLite backend.

The only argument passed to the callback is the statement (as
@ref{435,,str}) that is being executed. The return value of the callback is
ignored. Note that the backend does not only run statements passed to the
@ref{2cf,,Cursor.execute()} methods.  Other sources include the
@ref{285b,,transaction management} of the
@code{sqlite3} module and the execution of triggers defined in the current
database.

Passing @code{None} as `trace_callback' will disable the trace callback.

@cartouche
@quotation Note 
Exceptions raised in the trace callback are not propagated. As a
development and debugging aid, use
@ref{286e,,enable_callback_tracebacks()} to enable printing
tracebacks from exceptions raised in the trace callback.
@end quotation
@end cartouche


Ajouté dans la version 3.3.



Modifié dans la version 3.13: Passing `trace_callback' as a keyword argument is deprecated.
The parameter will become positional-only in Python 3.15.

@end deffn

@geindex enable_load_extension() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection enable_load_extension}@anchor{828}
@deffn {Méthode} enable_load_extension (enabled, /)

Enable the SQLite engine to load SQLite extensions from shared libraries
if `enabled' is @code{True};
else, disallow loading SQLite extensions.
SQLite extensions can define new functions,
aggregates or whole new virtual table implementations.  One well-known
extension is the fulltext-search extension distributed with SQLite.

@cartouche
@quotation Note 
The @code{sqlite3} module is not built with loadable extension support by
default, because some platforms (notably macOS) have SQLite
libraries which are compiled without this feature.
To get loadable extension support,
you must pass the @ref{1cf8,,--enable-loadable-sqlite-extensions} option
to @code{configure}.
@end quotation
@end cartouche

Raises an @ref{1848,,auditing event} @code{sqlite3.enable_load_extension} with arguments @code{connection}, @code{enabled}.


Ajouté dans la version 3.2.



Modifié dans la version 3.10: Added the @code{sqlite3.enable_load_extension} auditing event.


@c We cannot doctest the load extension API, since there is no convenient
@c way to skip it.

@example
con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
con.executescript("""
    INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
    INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
    print(row)
@end example
@end deffn

@geindex load_extension() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection load_extension}@anchor{4a1}
@deffn {Méthode} load_extension (path, /, *, entrypoint=None)

Load an SQLite extension from a shared library.
Enable extension loading with @ref{828,,enable_load_extension()} before
calling this method.

@*Paramètres: 

@itemize *

@item 
@code{path} (@ref{435,,str}) -- The path to the SQLite extension.

@item 
@code{entrypoint} (@ref{435,,str}@code{ | }@code{None}) -- Entry point name.
If @code{None} (the default),
SQLite will come up with an entry point name of its own;
see the SQLite docs Loading an Extension@footnote{https://www.sqlite.org/loadext.html#loading_an_extension} for details.
@end itemize


Raises an @ref{1848,,auditing event} @code{sqlite3.load_extension} with arguments @code{connection}, @code{path}.


Ajouté dans la version 3.2.



Modifié dans la version 3.10: Added the @code{sqlite3.load_extension} auditing event.



Modifié dans la version 3.12: Added the `entrypoint' parameter.

@end deffn

@geindex iterdump() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection iterdump}@anchor{244}
@deffn {Méthode} iterdump (*, filter=None)

Return an @ref{1aa,,iterator} to dump the database as SQL source code.
Useful when saving an in-memory database for later restoration.
Similar to the @code{.dump} command in the @code{sqlite3} shell.

@*Paramètres: 
@code{filter} (@ref{435,,str}@code{ | }@code{None}) -- An optional @code{LIKE} pattern for database objects to dump, e.g. @code{prefix_%}.
If @code{None} (the default), all database objects will be included.


Exemple :

@example
# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%s\n' % line)
con.close()
@end example


@subsubheading Voir aussi


@ref{2897,,How to handle non-UTF-8 text encodings}



Modifié dans la version 3.13: Ajout du paramètre `filter'.

@end deffn

@geindex backup() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection backup}@anchor{b68}
@deffn {Méthode} backup (target, *, pages=-1, progress=None, name='main', sleep=0.250)

Create a backup of an SQLite database.

Works even if the database is being accessed by other clients
or concurrently by the same connection.

@*Paramètres: 

@itemize *

@item 
@code{target} (@ref{242,,Connection}) -- The database connection to save the backup to.

@item 
@code{pages} (@ref{254,,int}) -- The number of pages to copy at a time.
If equal to or less than @code{0},
the entire database is copied in a single step.
Defaults to @code{-1}.

@item 
@code{progress} (@ref{2893,,callback} | None) -- If set to a @ref{2870,,callable},
it is invoked with three integer arguments for every backup iteration:
the `status' of the last iteration,
the `remaining' number of pages still to be copied,
and the `total' number of pages.
Defaults to @code{None}.

@item 
@code{name} (@ref{435,,str}) -- The name of the database to back up.
Either @code{"main"} (the default) for the main database,
@code{"temp"} for the temporary database,
or the name of a custom database as attached using the
@code{ATTACH DATABASE} SQL statement.

@item 
@code{sleep} (@ref{2eb,,float}) -- The number of seconds to sleep between successive attempts
to back up remaining pages.
@end itemize


Example 1, copy an existing database into another:

@example
def progress(status, remaining, total):
    print(f'Copied @{total-remaining@} of @{total@} pages...')

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()
@end example

@c Copied 0 of 0 pages...

Example 2, copy an existing database into a transient copy:

@example
src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()
@end example


Ajouté dans la version 3.7.



@subsubheading Voir aussi


@ref{2897,,How to handle non-UTF-8 text encodings}

@end deffn

@geindex getlimit() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection getlimit}@anchor{666}
@deffn {Méthode} getlimit (category, /)

Get a connection runtime limit.

@*Paramètres: 
@code{category} (@ref{254,,int}) -- The SQLite limit category@footnote{https://www.sqlite.org/c3ref/c_limit_attached.html} to be queried.


@*Type renvoyé: 
@ref{254,,int}


@*Lève: 
@ref{4dc,,ProgrammingError} -- If `category' is not recognised by the underlying SQLite library.


Example, query the maximum length of an SQL statement
for @ref{242,,Connection} @code{con} (the default is 1000000000):

@c import sqlite3
@c con = sqlite3.connect(":memory:")
@c con.setlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH, 1_000_000_000)
@c con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 10)

@example
>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex setlimit() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection setlimit}@anchor{665}
@deffn {Méthode} setlimit (category, limit, /)

Set a connection runtime limit.
Attempts to increase a limit above its hard upper bound are silently
truncated to the hard upper bound. Regardless of whether or not the limit
was changed, the prior value of the limit is returned.

@*Paramètres: 

@itemize *

@item 
@code{category} (@ref{254,,int}) -- The SQLite limit category@footnote{https://www.sqlite.org/c3ref/c_limit_attached.html} to be set.

@item 
@code{limit} (@ref{254,,int}) -- The value of the new limit.
If negative, the current limit is unchanged.
@end itemize


@*Type renvoyé: 
@ref{254,,int}


@*Lève: 
@ref{4dc,,ProgrammingError} -- If `category' is not recognised by the underlying SQLite library.


Example, limit the number of attached databases to 1
for @ref{242,,Connection} @code{con} (the default limit is 10):

@example
>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1
@end example

@c con.close()


Ajouté dans la version 3.11.

@end deffn

@geindex getconfig() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection getconfig}@anchor{4a2}
@deffn {Méthode} getconfig (op, /)

Query a boolean connection configuration option.

@*Paramètres: 
@code{op} (@ref{254,,int}) -- A @ref{287a,,SQLITE_DBCONFIG code}.


@*Type renvoyé: 
@ref{451,,bool}



Ajouté dans la version 3.12.

@end deffn

@geindex setconfig() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection setconfig}@anchor{4a3}
@deffn {Méthode} setconfig (op, enable=True, /)

Set a boolean connection configuration option.

@*Paramètres: 

@itemize *

@item 
@code{op} (@ref{254,,int}) -- A @ref{287a,,SQLITE_DBCONFIG code}.

@item 
@code{enable} (@ref{451,,bool}) -- @code{True} if the configuration option should be enabled (default);
@code{False} if it should be disabled.
@end itemize



Ajouté dans la version 3.12.

@end deffn

@geindex serialize() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection serialize}@anchor{669}
@deffn {Méthode} serialize (*, name='main')

Serialize a database into a @ref{1bd,,bytes} object.  For an
ordinary on-disk database file, the serialization is just a copy of the
disk file.  For an in-memory database or a "temp" database, the
serialization is the same sequence of bytes which would be written to
disk if that database were backed up to disk.

@*Paramètres: 
@code{name} (@ref{435,,str}) -- The database name to be serialized.
Defaults to @code{"main"}.


@*Type renvoyé: 
@ref{1bd,,bytes}


@cartouche
@quotation Note 
This method is only available if the underlying SQLite library has the
serialize API.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex deserialize() (méthode sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection deserialize}@anchor{66a}
@deffn {Méthode} deserialize (data, /, *, name='main')

Deserialize a @ref{669,,serialized} database into a
@ref{242,,Connection}.
This method causes the database connection to disconnect from database
`name', and reopen `name' as an in-memory database based on the
serialization contained in `data'.

@*Paramètres: 

@itemize *

@item 
@code{data} (@ref{1bd,,bytes}) -- A serialized database.

@item 
@code{name} (@ref{435,,str}) -- The database name to deserialize into.
Defaults to @code{"main"}.
@end itemize


@*Lève: 

@itemize *

@item 
@ref{182b,,OperationalError} -- If the database connection is currently involved in a read
transaction or a backup operation.

@item 
@ref{2896,,DatabaseError} -- If `data' does not contain a valid SQLite database.

@item 
@ref{86d,,OverflowError} -- If @ref{619,,len(data)} is larger than @code{2**63 - 1}.
@end itemize


@cartouche
@quotation Note 
This method is only available if the underlying SQLite library has the
deserialize API.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex autocommit (attribut sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection autocommit}@anchor{49f}
@deffn {Attribut} autocommit

This attribute controls 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant transaction behaviour.
@code{autocommit} has three allowed values:


@itemize *

@item 
@code{False}: Select 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant transaction behaviour,
implying that @code{sqlite3} ensures a transaction is always open.
Use @ref{285c,,commit()} and @ref{288e,,rollback()} to close transactions.

This is the recommended value of @code{autocommit}.

@item 
@code{True}: Use SQLite's autocommit mode@footnote{https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions}.
@ref{285c,,commit()} and @ref{288e,,rollback()} have no effect in this mode.

@item 
@ref{286b,,LEGACY_TRANSACTION_CONTROL}:
Pre-Python 3.12 (non-
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant) transaction control.
See @ref{2869,,isolation_level} for more details.

This is currently the default value of @code{autocommit}.
@end itemize

Changing @code{autocommit} to @code{False} will open a new transaction,
and changing it to @code{True} will commit any pending transaction.

See @ref{4a0,,Transaction control via the autocommit attribute} for more details.

@cartouche
@quotation Note 
The @ref{2869,,isolation_level} attribute has no effect unless
@ref{49f,,autocommit} is @ref{286b,,LEGACY_TRANSACTION_CONTROL}.
@end quotation
@end cartouche


Ajouté dans la version 3.12.

@end deffn

@geindex in_transaction (attribut sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection in_transaction}@anchor{2898}
@deffn {Attribut} in_transaction

This read-only attribute corresponds to the low-level SQLite
autocommit mode@footnote{https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions}.

@code{True} if a transaction is active (there are uncommitted changes),
@code{False} otherwise.


Ajouté dans la version 3.2.

@end deffn

@geindex isolation_level (attribut sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection isolation_level}@anchor{2869}
@deffn {Attribut} isolation_level

Controls the @ref{286a,,legacy transaction handling mode} of @code{sqlite3}.
If set to @code{None}, transactions are never implicitly opened.
If set to one of @code{"DEFERRED"}, @code{"IMMEDIATE"}, or @code{"EXCLUSIVE"},
corresponding to the underlying SQLite transaction behaviour@footnote{https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions},
@ref{286a,,implicit transaction management} is performed.

If not overridden by the `isolation_level' parameter of @ref{2a5,,connect()},
the default is @code{""}, which is an alias for @code{"DEFERRED"}.

@cartouche
@quotation Note 
Using @ref{49f,,autocommit} to control transaction handling is
recommended over using @code{isolation_level}.
@code{isolation_level} has no effect unless @ref{49f,,autocommit} is
set to @ref{286b,,LEGACY_TRANSACTION_CONTROL} (the default).
@end quotation
@end cartouche
@end deffn

@geindex row_factory (attribut sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection row_factory}@anchor{15b7}
@deffn {Attribut} row_factory

The initial @ref{2899,,row_factory}
for @ref{2859,,Cursor} objects created from this connection.
Assigning to this attribute does not affect the @code{row_factory}
of existing cursors belonging to this connection, only new ones.
Is @code{None} by default,
meaning each row is returned as a @ref{366,,tuple}.

See @ref{2860,,How to create and use row factories} for more details.
@end deffn

@geindex text_factory (attribut sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection text_factory}@anchor{289a}
@deffn {Attribut} text_factory

A @ref{2870,,callable} that accepts a @ref{1bd,,bytes} parameter
and returns a text representation of it.
The callable is invoked for SQLite values with the @code{TEXT} data type.
By default, this attribute is set to @ref{435,,str}.

See @ref{2897,,How to handle non-UTF-8 text encodings} for more details.
@end deffn

@geindex total_changes (attribut sqlite3.Connection)
@anchor{library/sqlite3 sqlite3 Connection total_changes}@anchor{289b}
@deffn {Attribut} total_changes

Return the total number of database rows that have been modified, inserted, or
deleted since the database connection was opened.
@end deffn
@end deffn

@node Cursor objects,Row objects,Connection objects,Références<2>
@anchor{library/sqlite3 cursor-objects}@anchor{289c}@anchor{library/sqlite3 sqlite3-cursor-objects}@anchor{289d}
@subsubsection Cursor objects


@quotation

A @code{Cursor} object represents a database cursor@footnote{https://en.wikipedia.org/wiki/Cursor_(databases)}
which is used to execute SQL statements,
and manage the context of a fetch operation.
Cursors are created using @ref{2858,,Connection.cursor()},
or by using any of the @ref{288d,,connection shortcut methods}.

Cursor objects are @ref{1aa,,iterators},
meaning that if you @ref{2cf,,execute()} a @code{SELECT} query,
you can simply iterate over the cursor to fetch the resulting rows:

@c import sqlite3
@c con = sqlite3.connect(":memory:", isolation_level=None)
@c cur = con.execute("CREATE TABLE data(t)")
@c cur.execute("INSERT INTO data VALUES(1)")

@example
for row in cur.execute("SELECT t FROM data"):
    print(row)
@end example

@c (1,)
@end quotation

@geindex Cursor (classe dans sqlite3)
@anchor{library/sqlite3 sqlite3 Cursor}@anchor{2859}
@deffn {Classe} sqlite3.Cursor

A @ref{2859,,Cursor} instance has the following attributes and methods.

@geindex ? (question mark);in SQL statements

@geindex ; (colon);in SQL statements

@geindex execute() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor execute}@anchor{2cf}
@deffn {Méthode} execute (sql, parameters=(), /)

Execute a single SQL statement,
optionally binding Python values using
@ref{2d1,,placeholders}.

@*Paramètres: 

@itemize *

@item 
@code{sql} (@ref{435,,str}) -- A single SQL statement.

@item 
@code{parameters} (@ref{253,,dict} | @ref{4db,,sequence}) -- Python values to bind to placeholders in `sql'.
A @code{dict} if named placeholders are used.
A sequence if unnamed placeholders are used.
See @ref{2d1,,How to use placeholders to bind values in SQL queries}.
@end itemize


@*Lève: 
@ref{4dc,,ProgrammingError} -- If `sql' contains more than one SQL statement.


If @ref{49f,,autocommit} is
@ref{286b,,LEGACY_TRANSACTION_CONTROL},
@ref{2869,,isolation_level} is not @code{None},
`sql' is an @code{INSERT}, @code{UPDATE}, @code{DELETE}, or @code{REPLACE} statement,
and there is no open transaction,
a transaction is implicitly opened before executing `sql'.


Deprecated since version 3.12, will be removed in version 3.14: @ref{1a3,,DeprecationWarning} is emitted if
@ref{2d1,,named placeholders} are used
and `parameters' is a sequence instead of a @ref{253,,dict}.
Starting with Python 3.14, @ref{4dc,,ProgrammingError} will
be raised instead.


Use @ref{2892,,executescript()} to execute multiple SQL statements.
@end deffn

@geindex executemany() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor executemany}@anchor{2d0}
@deffn {Méthode} executemany (sql, parameters, /)

For every item in `parameters',
repeatedly execute the @ref{2d1,,parameterized}
@abbr{DML,Data Manipulation Language} SQL statement `sql'.

Uses the same implicit transaction handling as @ref{2cf,,execute()}.

@*Paramètres: 

@itemize *

@item 
@code{sql} (@ref{435,,str}) -- A single SQL DML statement.

@item 
@code{parameters} (@ref{1205,,iterable}) -- An iterable of parameters to bind with
the placeholders in `sql'.
See @ref{2d1,,How to use placeholders to bind values in SQL queries}.
@end itemize


@*Lève: 
@ref{4dc,,ProgrammingError} -- If `sql' contains more than one SQL statement,
or is not a DML statement.


Exemple :

@example
rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)
@end example

@c con.close()

@cartouche
@quotation Note 
Any resulting rows are discarded,
including DML statements with RETURNING clauses@footnote{https://www.sqlite.org/lang_returning.html}.
@end quotation
@end cartouche


Deprecated since version 3.12, will be removed in version 3.14: @ref{1a3,,DeprecationWarning} is emitted if
@ref{2d1,,named placeholders} are used
and the items in `parameters' are sequences
instead of @ref{253,,dict}s.
Starting with Python 3.14, @ref{4dc,,ProgrammingError} will
be raised instead.

@end deffn

@geindex executescript() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor executescript}@anchor{2892}
@deffn {Méthode} executescript (sql_script, /)

Execute the SQL statements in `sql_script'.
If the @ref{49f,,autocommit} is
@ref{286b,,LEGACY_TRANSACTION_CONTROL}
and there is a pending transaction,
an implicit @code{COMMIT} statement is executed first.
No other implicit transaction control is performed;
any transaction control must be added to `sql_script'.

`sql_script' must be a @ref{435,,string}.

Exemple :

@example
# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")
@end example
@end deffn

@geindex fetchone() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor fetchone}@anchor{285a}
@deffn {Méthode} fetchone ()

If @ref{2899,,row_factory} is @code{None},
return the next row query result set as a @ref{366,,tuple}.
Else, pass it to the row factory and return its result.
Return @code{None} if no more data is available.
@end deffn

@geindex fetchmany() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor fetchmany}@anchor{289e}
@deffn {Méthode} fetchmany (size=cursor.arraysize)

Return the next set of rows of a query result as a @ref{5fc,,list}.
Return an empty list if no more rows are available.

The number of rows to fetch per call is specified by the `size' parameter.
If `size' is not given, @ref{289f,,arraysize} determines the number of rows
to be fetched.
If fewer than `size' rows are available,
as many rows as are available are returned.

Note there are performance considerations involved with the `size' parameter.
For optimal performance, it is usually best to use the arraysize attribute.
If the `size' parameter is used, then it is best for it to retain the same
value from one @ref{289e,,fetchmany()} call to the next.
@end deffn

@geindex fetchall() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor fetchall}@anchor{285d}
@deffn {Méthode} fetchall ()

Return all (remaining) rows of a query result as a @ref{5fc,,list}.
Return an empty list if no rows are available.
Note that the @ref{289f,,arraysize} attribute can affect the performance of
this operation.
@end deffn

@geindex close() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor close}@anchor{28a0}
@deffn {Méthode} close ()

Close the cursor now (rather than whenever @code{__del__} is called).

The cursor will be unusable from this point forward; a @ref{4dc,,ProgrammingError}
exception will be raised if any operation is attempted with the cursor.
@end deffn

@geindex setinputsizes() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor setinputsizes}@anchor{28a1}
@deffn {Méthode} setinputsizes (sizes, /)

Required by the DB-API. Does nothing in @code{sqlite3}.
@end deffn

@geindex setoutputsize() (méthode sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor setoutputsize}@anchor{28a2}
@deffn {Méthode} setoutputsize (size, column=None, /)

Required by the DB-API. Does nothing in @code{sqlite3}.
@end deffn

@geindex arraysize (attribut sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor arraysize}@anchor{289f}
@deffn {Attribut} arraysize

Read/write attribute that controls the number of rows returned by @ref{289e,,fetchmany()}.
The default value is 1 which means a single row would be fetched per call.
@end deffn

@geindex connection (attribut sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor connection}@anchor{28a3}
@deffn {Attribut} connection

Read-only attribute that provides the SQLite database @ref{242,,Connection}
belonging to the cursor.  A @ref{2859,,Cursor} object created by
calling @ref{2858,,con.cursor()} will have a
@ref{28a3,,connection} attribute that refers to `con':

@example
>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
>>> con.close()
@end example
@end deffn

@geindex description (attribut sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor description}@anchor{28a4}
@deffn {Attribut} description

Read-only attribute that provides the column names of the last query. To
remain compatible with the Python DB API, it returns a 7-tuple for each
column where the last six items of each tuple are @code{None}.

It is set for @code{SELECT} statements without any matching rows as well.
@end deffn

@geindex lastrowid (attribut sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor lastrowid}@anchor{cbf}
@deffn {Attribut} lastrowid

Read-only attribute that provides the row id of the last inserted row. It
is only updated after successful @code{INSERT} or @code{REPLACE} statements
using the @ref{2cf,,execute()} method.  For other statements, after
@ref{2d0,,executemany()} or @ref{2892,,executescript()}, or if the insertion failed,
the value of @code{lastrowid} is left unchanged.  The initial value of
@code{lastrowid} is @code{None}.

@cartouche
@quotation Note 
Inserts into @code{WITHOUT ROWID} tables are not recorded.
@end quotation
@end cartouche


Modifié dans la version 3.6: Added support for the @code{REPLACE} statement.

@end deffn

@geindex rowcount (attribut sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor rowcount}@anchor{1764}
@deffn {Attribut} rowcount

Read-only attribute that provides the number of modified rows for
@code{INSERT}, @code{UPDATE}, @code{DELETE}, and @code{REPLACE} statements;
is @code{-1} for other statements,
including @abbr{CTE,Common Table Expression} queries.
It is only updated by the @ref{2cf,,execute()} and @ref{2d0,,executemany()} methods,
after the statement has run to completion.
This means that any resulting rows must be fetched in order for
@code{rowcount} to be updated.
@end deffn

@geindex row_factory (attribut sqlite3.Cursor)
@anchor{library/sqlite3 sqlite3 Cursor row_factory}@anchor{2899}
@deffn {Attribut} row_factory

Control how a row fetched from this @code{Cursor} is represented.
If @code{None}, a row is represented as a @ref{366,,tuple}.
Can be set to the included @ref{e5a,,sqlite3.Row};
or a @ref{2870,,callable} that accepts two arguments,
a @ref{2859,,Cursor} object and the @code{tuple} of row values,
and returns a custom object representing an SQLite row.

Defaults to what @ref{15b7,,Connection.row_factory} was set to
when the @code{Cursor} was created.
Assigning to this attribute does not affect
@ref{15b7,,Connection.row_factory} of the parent connection.

See @ref{2860,,How to create and use row factories} for more details.
@end deffn
@end deffn

@c The sqlite3.Row example used to be a how-to. It has now been incorporated
@c into the Row reference. We keep the anchor here in order not to break
@c existing links.
@anchor{library/sqlite3 sqlite3-columns-by-name}@anchor{28a5}
@node Row objects,Blob objects,Cursor objects,Références<2>
@anchor{library/sqlite3 row-objects}@anchor{28a6}@anchor{library/sqlite3 sqlite3-row-objects}@anchor{28a7}
@subsubsection Row objects


@geindex Row (classe dans sqlite3)
@anchor{library/sqlite3 sqlite3 Row}@anchor{e5a}
@deffn {Classe} sqlite3.Row

A @code{Row} instance serves as a highly optimized
@ref{15b7,,row_factory} for @ref{242,,Connection} objects.
It supports iteration, equality testing, @ref{619,,len()},
and @ref{1199,,mapping} access by column name and index.

Two @code{Row} objects compare equal
if they have identical column names and values.

See @ref{2860,,How to create and use row factories} for more details.

@geindex keys() (méthode sqlite3.Row)
@anchor{library/sqlite3 sqlite3 Row keys}@anchor{28a8}
@deffn {Méthode} keys ()

Return a @ref{5fc,,list} of column names as @ref{435,,strings}.
Immediately after a query,
it is the first member of each tuple in @ref{28a4,,Cursor.description}.
@end deffn


Modifié dans la version 3.5: Added support of slicing.

@end deffn

@node Blob objects,PrepareProtocol objects,Row objects,Références<2>
@anchor{library/sqlite3 blob-objects}@anchor{28a9}@anchor{library/sqlite3 sqlite3-blob-objects}@anchor{28aa}
@subsubsection Blob objects


@geindex Blob (classe dans sqlite3)
@anchor{library/sqlite3 sqlite3 Blob}@anchor{66d}
@deffn {Classe} sqlite3.Blob


Ajouté dans la version 3.11.


A @ref{66d,,Blob} instance is a @ref{250d,,file-like object}
that can read and write data in an SQLite @abbr{BLOB}.
Call @ref{619,,len(blob)} to get the size (number of bytes) of the blob.
Use indices and @ref{2106,,slices} for direct access to the blob data.

Use the @ref{66d,,Blob} as a @ref{5be,,context manager} to ensure that the blob
handle is closed after use.

@example
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Modify the first and last bytes of our blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # outputs "b'Hello, world!'"
con.close()
@end example

@c b'Hello, world!'

@geindex close() (méthode sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob close}@anchor{28ab}
@deffn {Méthode} close ()

Close the blob.

The blob will be unusable from this point onward.  An
@ref{180e,,Error} (or subclass) exception will be raised if any
further operation is attempted with the blob.
@end deffn

@geindex read() (méthode sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob read}@anchor{28ac}
@deffn {Méthode} read (length=-1, /)

Read `length' bytes of data from the blob at the current offset position.
If the end of the blob is reached, the data up to
@abbr{EOF,End of File} will be returned.  When `length' is not
specified, or is negative, @ref{28ac,,read()} will read until the end of
the blob.
@end deffn

@geindex write() (méthode sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob write}@anchor{28ad}
@deffn {Méthode} write (data, /)

Write `data' to the blob at the current offset.  This function cannot
change the blob length.  Writing beyond the end of the blob will raise
@ref{1ff,,ValueError}.
@end deffn

@geindex tell() (méthode sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob tell}@anchor{28ae}
@deffn {Méthode} tell ()

Return the current access position of the blob.
@end deffn

@geindex seek() (méthode sqlite3.Blob)
@anchor{library/sqlite3 sqlite3 Blob seek}@anchor{28af}
@deffn {Méthode} seek (offset, origin=os.SEEK_SET, /)

Set the current access position of the blob to `offset'.  The `origin'
argument defaults to @ref{126b,,os.SEEK_SET} (absolute blob positioning).
Other values for `origin' are @ref{126c,,os.SEEK_CUR} (seek relative to the
current position) and @ref{126d,,os.SEEK_END} (seek relative to the blob’s
end).
@end deffn
@end deffn

@node PrepareProtocol objects,Exceptions<7>,Blob objects,Références<2>
@anchor{library/sqlite3 prepareprotocol-objects}@anchor{28b0}
@subsubsection PrepareProtocol objects


@geindex PrepareProtocol (classe dans sqlite3)
@anchor{library/sqlite3 sqlite3 PrepareProtocol}@anchor{1770}
@deffn {Classe} sqlite3.PrepareProtocol

The PrepareProtocol type's single purpose is to act as a 
@geindex Python Enhancement Proposals; PEP 246
PEP 246@footnote{https://peps.python.org/pep-0246/} style
adaption protocol for objects that can @ref{28b1,,adapt themselves} to @ref{2865,,native SQLite types}.
@end deffn

@node Exceptions<7>,SQLite and Python types,PrepareProtocol objects,Références<2>
@anchor{library/sqlite3 exceptions}@anchor{28b2}@anchor{library/sqlite3 sqlite3-exceptions}@anchor{28b3}
@subsubsection Exceptions


The exception hierarchy is defined by the DB-API 2.0 (
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}).

@geindex Warning
@anchor{library/sqlite3 sqlite3 Warning}@anchor{17b3}
@deffn {Exception} sqlite3.Warning

This exception is not currently raised by the @code{sqlite3} module,
but may be raised by applications using @code{sqlite3},
for example if a user-defined function truncates data while inserting.
@code{Warning} is a subclass of @ref{9c7,,Exception}.
@end deffn

@geindex Error
@anchor{library/sqlite3 sqlite3 Error}@anchor{180e}
@deffn {Exception} sqlite3.Error

The base class of the other exceptions in this module.
Use this to catch all errors with one single @ref{189,,except} statement.
@code{Error} is a subclass of @ref{9c7,,Exception}.

If the exception originated from within the SQLite library,
the following two attributes are added to the exception:

@geindex sqlite_errorcode (attribut sqlite3.Error)
@anchor{library/sqlite3 sqlite3 Error sqlite_errorcode}@anchor{663}
@deffn {Attribut} sqlite_errorcode

The numeric error code from the
SQLite API@footnote{https://sqlite.org/rescode.html}


Ajouté dans la version 3.11.

@end deffn

@geindex sqlite_errorname (attribut sqlite3.Error)
@anchor{library/sqlite3 sqlite3 Error sqlite_errorname}@anchor{664}
@deffn {Attribut} sqlite_errorname

The symbolic name of the numeric error code
from the SQLite API@footnote{https://sqlite.org/rescode.html}


Ajouté dans la version 3.11.

@end deffn
@end deffn

@geindex InterfaceError
@anchor{library/sqlite3 sqlite3 InterfaceError}@anchor{668}
@deffn {Exception} sqlite3.InterfaceError

Exception raised for misuse of the low-level SQLite C API.
In other words, if this exception is raised, it probably indicates a bug in the
@code{sqlite3} module.
@code{InterfaceError} is a subclass of @ref{180e,,Error}.
@end deffn

@geindex DatabaseError
@anchor{library/sqlite3 sqlite3 DatabaseError}@anchor{2896}
@deffn {Exception} sqlite3.DatabaseError

Exception raised for errors that are related to the database.
This serves as the base exception for several types of database errors.
It is only raised implicitly through the specialised subclasses.
@code{DatabaseError} is a subclass of @ref{180e,,Error}.
@end deffn

@geindex DataError
@anchor{library/sqlite3 sqlite3 DataError}@anchor{182a}
@deffn {Exception} sqlite3.DataError

Exception raised for errors caused by problems with the processed data,
like numeric values out of range, and strings which are too long.
@code{DataError} is a subclass of @ref{2896,,DatabaseError}.
@end deffn

@geindex OperationalError
@anchor{library/sqlite3 sqlite3 OperationalError}@anchor{182b}
@deffn {Exception} sqlite3.OperationalError

Exception raised for errors that are related to the database's operation,
and not necessarily under the control of the programmer.
For example, the database path is not found,
or a transaction could not be processed.
@code{OperationalError} is a subclass of @ref{2896,,DatabaseError}.
@end deffn

@geindex IntegrityError
@anchor{library/sqlite3 sqlite3 IntegrityError}@anchor{28b4}
@deffn {Exception} sqlite3.IntegrityError

Exception raised when the relational integrity of the database is affected,
e.g. a foreign key check fails.  It is a subclass of @ref{2896,,DatabaseError}.
@end deffn

@geindex InternalError
@anchor{library/sqlite3 sqlite3 InternalError}@anchor{28b5}
@deffn {Exception} sqlite3.InternalError

Exception raised when SQLite encounters an internal error.
If this is raised, it may indicate that there is a problem with the runtime
SQLite library.
@code{InternalError} is a subclass of @ref{2896,,DatabaseError}.
@end deffn

@geindex ProgrammingError
@anchor{library/sqlite3 sqlite3 ProgrammingError}@anchor{4dc}
@deffn {Exception} sqlite3.ProgrammingError

Exception raised for @code{sqlite3} API programming errors,
for example supplying the wrong number of bindings to a query,
or trying to operate on a closed @ref{242,,Connection}.
@code{ProgrammingError} is a subclass of @ref{2896,,DatabaseError}.
@end deffn

@geindex NotSupportedError
@anchor{library/sqlite3 sqlite3 NotSupportedError}@anchor{2894}
@deffn {Exception} sqlite3.NotSupportedError

Exception raised in case a method or database API is not supported by the
underlying SQLite library. For example, setting `deterministic' to
@code{True} in @ref{2a6,,create_function()}, if the underlying SQLite library
does not support deterministic functions.
@code{NotSupportedError} is a subclass of @ref{2896,,DatabaseError}.
@end deffn

@node SQLite and Python types,Default adapters and converters deprecated,Exceptions<7>,Références<2>
@anchor{library/sqlite3 sqlite-and-python-types}@anchor{28b6}@anchor{library/sqlite3 sqlite3-types}@anchor{2865}
@subsubsection SQLite and Python types


SQLite natively supports the following types: @code{NULL}, @code{INTEGER},
@code{REAL}, @code{TEXT}, @code{BLOB}.

The following Python types can thus be sent to SQLite without any problem:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 
@headitem

Type Python

@tab

SQLite type

@item

@code{None}

@tab

@code{NULL}

@item

@ref{254,,int}

@tab

@code{INTEGER}

@item

@ref{2eb,,float}

@tab

@code{REAL}

@item

@ref{435,,str}

@tab

@code{TEXT}

@item

@ref{1bd,,bytes}

@tab

@code{BLOB}

@end multitable


This is how SQLite types are converted to Python types by default:


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

SQLite type

@tab

Type Python

@item

@code{NULL}

@tab

@code{None}

@item

@code{INTEGER}

@tab

@ref{254,,int}

@item

@code{REAL}

@tab

@ref{2eb,,float}

@item

@code{TEXT}

@tab

depends on @ref{289a,,text_factory},
@ref{435,,str} by default

@item

@code{BLOB}

@tab

@ref{1bd,,bytes}

@end multitable


The type system of the @code{sqlite3} module is extensible in two ways: you can
store additional Python types in an SQLite database via
@ref{285e,,object adapters},
and you can let the @code{sqlite3} module convert SQLite types to
Python types via @ref{285f,,converters}.

@node Default adapters and converters deprecated,Command-line interface,SQLite and Python types,Références<2>
@anchor{library/sqlite3 default-adapters-and-converters-deprecated}@anchor{28b7}@anchor{library/sqlite3 sqlite3-default-converters}@anchor{4d9}
@subsubsection Default adapters and converters (deprecated)


@cartouche
@quotation Note 
The default adapters and converters are deprecated as of Python 3.12.
Instead, use the @ref{4da,,Adapter and converter recipes}
and tailor them to your needs.
@end quotation
@end cartouche

The deprecated default adapters and converters consist of:


@itemize *

@item 
An adapter for @ref{1c8,,datetime.date} objects to @ref{435,,strings} in
ISO 8601@footnote{https://en.wikipedia.org/wiki/ISO_8601} format.

@item 
An adapter for @ref{1c7,,datetime.datetime} objects to strings in
ISO 8601 format.

@item 
A converter for @ref{285f,,declared} "date" types to
@ref{1c8,,datetime.date} objects.

@item 
A converter for declared "timestamp" types to
@ref{1c7,,datetime.datetime} objects.
Fractional parts will be truncated to 6 digits (microsecond precision).
@end itemize

@cartouche
@quotation Note 
The default "timestamp" converter ignores UTC offsets in the database and
always returns a naive @ref{1c7,,datetime.datetime} object. To preserve UTC
offsets in timestamps, either leave converters disabled, or register an
offset-aware converter with @ref{2866,,register_converter()}.
@end quotation
@end cartouche


Obsolète depuis la version 3.12.


@node Command-line interface,,Default adapters and converters deprecated,Références<2>
@anchor{library/sqlite3 command-line-interface}@anchor{28b8}@anchor{library/sqlite3 sqlite3-cli}@anchor{42a}
@subsubsection Command-line interface


The @code{sqlite3} module can be invoked as a script,
using the interpreter's @ref{5cb,,-m} switch,
in order to provide a simple SQLite shell.
The argument signature is as follows:

@example
python -m sqlite3 [-h] [-v] [filename] [sql]
@end example

Type @code{.quit} or CTRL-D to exit the shell.

@geindex option de ligne de commande python--m-sqlite3-[-h]-[-v]-[filename]-[sql]; -h
@geindex option de ligne de commande python--m-sqlite3-[-h]-[-v]-[filename]-[sql]; --help
@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-h}@anchor{28b9}@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-help}@anchor{28ba}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Print CLI help.
@end deffn

@geindex option de ligne de commande python--m-sqlite3-[-h]-[-v]-[filename]-[sql]; -v
@geindex option de ligne de commande python--m-sqlite3-[-h]-[-v]-[filename]-[sql]; --version
@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-v}@anchor{28bb}@anchor{library/sqlite3 cmdoption-python-m-sqlite3-h-v-filename-sql-version}@anchor{28bc}
@deffn {Option} @w{-}v, @w{-}@w{-}version

Print underlying SQLite library version.
@end deffn


Ajouté dans la version 3.12.


@node How-to guides,Explanation,Références<2>,sqlite3 --- DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 how-to-guides}@anchor{28bd}@anchor{library/sqlite3 sqlite3-howtos}@anchor{2855}
@subsubsection How-to guides


@menu
* How to use placeholders to bind values in SQL queries:: 
* How to adapt custom Python types to SQLite values:: 
* How to convert SQLite values to custom Python types:: 
* Adapter and converter recipes:: 
* How to use connection shortcut methods:: 
* How to use the connection context manager:: 
* How to work with SQLite URIs:: 
* How to create and use row factories:: 
* How to handle non-UTF-8 text encodings:: 

@end menu

@node How to use placeholders to bind values in SQL queries,How to adapt custom Python types to SQLite values,,How-to guides
@anchor{library/sqlite3 how-to-use-placeholders-to-bind-values-in-sql-queries}@anchor{28be}@anchor{library/sqlite3 sqlite3-placeholders}@anchor{2d1}
@subsubsection How to use placeholders to bind values in SQL queries


SQL operations usually need to use values from Python variables. However,
beware of using Python's string operations to assemble queries, as they
are vulnerable to SQL injection attacks@footnote{https://en.wikipedia.org/wiki/SQL_injection}. For example, an attacker can simply
close the single quote and inject @code{OR TRUE} to select all rows:

@example
>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '@w{'} OR TRUE; --'
>>> cur.execute(sql)
@end example

Instead, use the DB-API's parameter substitution. To insert a variable into a
query string, use a placeholder in the string, and substitute the actual values
into the query by providing them as a @ref{366,,tuple} of values to the second
argument of the cursor's @ref{2cf,,execute()} method.

An SQL statement may use one of two kinds of placeholders:
question marks (qmark style) or named placeholders (named style).
For the qmark style, `parameters' must be a
@ref{4db,,sequence} whose length must match the number of placeholders,
or a @ref{4dc,,ProgrammingError} is raised.
For the named style, `parameters' must be
an instance of a @ref{253,,dict} (or a subclass),
which must contain keys for all named parameters;
any extra items are ignored.
Here's an example of both styles:

@example
con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# This is the named style used with executemany():
data = (
    @{"name": "C", "year": 1972@},
    @{"name": "Fortran", "year": 1957@},
    @{"name": "Python", "year": 1991@},
    @{"name": "Go", "year": 2009@},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# This is the qmark style used in a SELECT query:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()
@end example

@c [('C', 1972)]

@cartouche
@quotation Note 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/} numeric placeholders are `not' supported.
If used, they will be interpreted as named placeholders.
@end quotation
@end cartouche

@node How to adapt custom Python types to SQLite values,How to convert SQLite values to custom Python types,How to use placeholders to bind values in SQL queries,How-to guides
@anchor{library/sqlite3 how-to-adapt-custom-python-types-to-sqlite-values}@anchor{28bf}@anchor{library/sqlite3 sqlite3-adapters}@anchor{285e}
@subsubsection How to adapt custom Python types to SQLite values


SQLite supports only a limited set of data types natively.
To store custom Python types in SQLite databases, `adapt' them to one of the
@ref{2865,,Python types SQLite natively understands}.

There are two ways to adapt Python objects to SQLite types:
letting your object adapt itself, or using an `adapter callable'.
The latter will take precedence above the former.
For a library that exports a custom type,
it may make sense to enable that type to adapt itself.
As an application developer, it may make more sense to take direct control by
registering custom adapter functions.

@menu
* How to write adaptable objects:: 
* How to register adapter callables:: 

@end menu

@node How to write adaptable objects,How to register adapter callables,,How to adapt custom Python types to SQLite values
@anchor{library/sqlite3 how-to-write-adaptable-objects}@anchor{28c0}@anchor{library/sqlite3 sqlite3-conform}@anchor{28b1}
@subsubsection How to write adaptable objects


Suppose we have a @code{Point} class that represents a pair of coordinates,
@code{x} and @code{y}, in a Cartesian coordinate system.
The coordinate pair will be stored as a text string in the database,
using a semicolon to separate the coordinates.
This can be implemented by adding a @code{__conform__(self, protocol)}
method which returns the adapted value.
The object passed to `protocol' will be of type @ref{1770,,PrepareProtocol}.

@example
class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return f"@{self.x@};@{self.y@}"

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()
@end example

@c 4.0;-3.2

@node How to register adapter callables,,How to write adaptable objects,How to adapt custom Python types to SQLite values
@anchor{library/sqlite3 how-to-register-adapter-callables}@anchor{28c1}
@subsubsection How to register adapter callables


The other possibility is to create a function that converts the Python object
to an SQLite-compatible type.
This function can then be registered using @ref{286f,,register_adapter()}.

@example
class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return f"@{point.x@};@{point.y@}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()
@end example

@c 1.0;2.5

@node How to convert SQLite values to custom Python types,Adapter and converter recipes,How to adapt custom Python types to SQLite values,How-to guides
@anchor{library/sqlite3 how-to-convert-sqlite-values-to-custom-python-types}@anchor{28c2}@anchor{library/sqlite3 sqlite3-converters}@anchor{285f}
@subsubsection How to convert SQLite values to custom Python types


Writing an adapter lets you convert `from' custom Python types `to' SQLite
values.
To be able to convert `from' SQLite values `to' custom Python types,
we use `converters'.

Let's go back to the @code{Point} class. We stored the x and y coordinates
separated via semicolons as strings in SQLite.

First, we'll define a converter function that accepts the string as a parameter
and constructs a @code{Point} object from it.

@cartouche
@quotation Note 
Converter functions are `always' passed a @ref{1bd,,bytes} object,
no matter the underlying SQLite data type.
@end quotation
@end cartouche

@example
def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)
@end example

We now need to tell @code{sqlite3} when it should convert a given SQLite value.
This is done when connecting to a database, using the `detect_types' parameter
of @ref{2a5,,connect()}. There are three options:


@itemize *

@item 
Implicit: set `detect_types' to @ref{2867,,PARSE_DECLTYPES}

@item 
Explicit: set `detect_types' to @ref{2868,,PARSE_COLNAMES}

@item 
Both: set `detect_types' to
@code{sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES}.
Column names take precedence over declared types.
@end itemize

The following example illustrates the implicit and explicit approaches:

@example
class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point(@{self.x@}, @{self.y@})"

def adapt_point(point):
    return f"@{point.x@};@{point.y@}"

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()
@end example

@c with declared types: Point(4.0, -3.2)
@c with column names: Point(4.0, -3.2)

@node Adapter and converter recipes,How to use connection shortcut methods,How to convert SQLite values to custom Python types,How-to guides
@anchor{library/sqlite3 adapter-and-converter-recipes}@anchor{28c3}@anchor{library/sqlite3 sqlite3-adapter-converter-recipes}@anchor{4da}
@subsubsection Adapter and converter recipes


This section shows recipes for common adapters and converters.

@example
import datetime
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(datetime.date, adapt_date_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_iso)
sqlite3.register_adapter(datetime.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return datetime.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return datetime.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return datetime.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)
@end example

@c dt = datetime.datetime(2019, 5, 18, 15, 17, 8, 123456)
@c 
@c assert adapt_date_iso(dt.date()) == "2019-05-18"
@c assert convert_date(b"2019-05-18") == dt.date()
@c 
@c assert adapt_datetime_iso(dt) == "2019-05-18T15:17:08.123456"
@c assert convert_datetime(b"2019-05-18T15:17:08.123456") == dt
@c 
@c # Using current time as fromtimestamp() returns local date/time.
@c # Dropping microseconds as adapt_datetime_epoch truncates fractional second part.
@c now = datetime.datetime.now().replace(microsecond=0)
@c current_timestamp = int(now.timestamp())
@c 
@c assert adapt_datetime_epoch(now) == current_timestamp
@c assert convert_timestamp(str(current_timestamp).encode()) == now

@node How to use connection shortcut methods,How to use the connection context manager,Adapter and converter recipes,How-to guides
@anchor{library/sqlite3 how-to-use-connection-shortcut-methods}@anchor{28c4}@anchor{library/sqlite3 sqlite3-connection-shortcuts}@anchor{288d}
@subsubsection How to use connection shortcut methods


Using the @ref{288f,,execute()},
@ref{2890,,executemany()}, and @ref{2891,,executescript()}
methods of the @ref{242,,Connection} class, your code can
be written more concisely because you don't have to create the (often
superfluous) @ref{2859,,Cursor} objects explicitly. Instead, the @ref{2859,,Cursor}
objects are created implicitly and these shortcut methods return the cursor
objects. This way, you can execute a @code{SELECT} statement and iterate over it
directly using only a single call on the @ref{242,,Connection} object.

@example
# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# Print the table contents
for row in con.execute("SELECT name, first_appeared FROM lang"):
    print(row)

print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

# close() is not a shortcut method and it's not called automatically;
# the connection object should be closed manually
con.close()
@end example

@c ('C++', 1985)
@c ('Objective-C', 1984)
@c I just deleted 2 rows

@node How to use the connection context manager,How to work with SQLite URIs,How to use connection shortcut methods,How-to guides
@anchor{library/sqlite3 how-to-use-the-connection-context-manager}@anchor{28c5}@anchor{library/sqlite3 sqlite3-connection-context-manager}@anchor{1771}
@subsubsection How to use the connection context manager


A @ref{242,,Connection} object can be used as a context manager that
automatically commits or rolls back open transactions when leaving the body of
the context manager.
If the body of the @ref{5bc,,with} statement finishes without exceptions,
the transaction is committed.
If this commit fails,
or if the body of the @code{with} statement raises an uncaught exception,
the transaction is rolled back.
If @ref{49f,,autocommit} is @code{False},
a new transaction is implicitly opened after committing or rolling back.

If there is no open transaction upon leaving the body of the @code{with} statement,
or if @ref{49f,,autocommit} is @code{True},
the context manager does nothing.

@cartouche
@quotation Note 
The context manager neither implicitly opens a new transaction
nor closes the connection. If you need a closing context manager, consider
using @ref{28c6,,contextlib.closing()}.
@end quotation
@end cartouche

@example
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception,
# the exception is still raised and must be caught
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()
@end example

@c couldn't add Python twice

@node How to work with SQLite URIs,How to create and use row factories,How to use the connection context manager,How-to guides
@anchor{library/sqlite3 how-to-work-with-sqlite-uris}@anchor{28c7}@anchor{library/sqlite3 sqlite3-uri-tricks}@anchor{286c}
@subsubsection How to work with SQLite URIs


Some useful URI tricks include:


@itemize *

@item 
Open a database in read-only mode:
@end itemize

@example
>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database
>>> con.close()
@end example


@itemize *

@item 
Do not implicitly create a new database file if it does not already exist;
will raise @ref{182b,,OperationalError} if unable to create a new file:
@end itemize

@example
>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file
@end example


@itemize *

@item 
Create a shared named in-memory database:
@end itemize

@example
db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

con1.close()
con2.close()
@end example

More information about this feature, including a list of parameters,
can be found in the SQLite URI documentation@footnote{https://www.sqlite.org/uri.html}.

@node How to create and use row factories,How to handle non-UTF-8 text encodings,How to work with SQLite URIs,How-to guides
@anchor{library/sqlite3 how-to-create-and-use-row-factories}@anchor{28c8}@anchor{library/sqlite3 sqlite3-howto-row-factory}@anchor{2860}
@subsubsection How to create and use row factories


By default, @code{sqlite3} represents each row as a @ref{366,,tuple}.
If a @code{tuple} does not suit your needs,
you can use the @ref{e5a,,sqlite3.Row} class
or a custom @ref{2899,,row_factory}.

While @code{row_factory} exists as an attribute both on the
@ref{2859,,Cursor} and the @ref{242,,Connection},
it is recommended to set @ref{15b7,,Connection.row_factory},
so all cursors created from the connection will use the same row factory.

@code{Row} provides indexed and case-insensitive named access to columns,
with minimal memory overhead and performance impact over a @code{tuple}.
To use @code{Row} as a row factory,
assign it to the @code{row_factory} attribute:

@example
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row
@end example

Queries now return @code{Row} objects:

@example
>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0]         # Access by index.
'Earth'
>>> row["name"]    # Access by name.
'Earth'
>>> row["RADIUS"]  # Column names are case-insensitive.
6378
>>> con.close()
@end example

@cartouche
@quotation Note 
The @code{FROM} clause can be omitted in the @code{SELECT} statement, as in the
above example. In such cases, SQLite returns a single row with columns
defined by expressions, e.g. literals, with the given aliases
@code{expr AS alias}.
@end quotation
@end cartouche

You can create a custom @ref{2899,,row_factory}
that returns each row as a @ref{253,,dict}, with column names mapped to values:

@example
def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return @{key: value for key, value in zip(fields, row)@}
@end example

Using it, queries now return a @code{dict} instead of a @code{tuple}:

@example
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
@{'a': 1, 'b': 2@}
>>> con.close()
@end example

The following row factory returns a @ref{639,,named tuple}:

@example
from collections import namedtuple

def namedtuple_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    cls = namedtuple("Row", fields)
    return cls._make(row)
@end example

@code{namedtuple_factory()} can be used as follows:

@example
>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0]  # Indexed access.
1
>>> row.b   # Attribute access.
2
>>> con.close()
@end example

With some adjustments, the above recipe can be adapted to use a
@ref{1c6,,dataclass}, or any other custom class,
instead of a @ref{1c5,,namedtuple}.

@node How to handle non-UTF-8 text encodings,,How to create and use row factories,How-to guides
@anchor{library/sqlite3 how-to-handle-non-utf-8-text-encodings}@anchor{28c9}@anchor{library/sqlite3 sqlite3-howto-encoding}@anchor{2897}
@subsubsection How to handle non-UTF-8 text encodings


By default, @code{sqlite3} uses @ref{435,,str} to adapt SQLite values
with the @code{TEXT} data type.
This works well for UTF-8 encoded text, but it might fail for other encodings
and invalid UTF-8.
You can use a custom @ref{289a,,text_factory} to handle such cases.

Because of SQLite's flexible typing@footnote{https://www.sqlite.org/flextypegood.html}, it is not uncommon to encounter table
columns with the @code{TEXT} data type containing non-UTF-8 encodings,
or even arbitrary data.
To demonstrate, let's assume we have a database with ISO-8859-2 (Latin-2)
encoded text, for example a table of Czech-English dictionary entries.
Assuming we now have a @ref{242,,Connection} instance @code{con}
connected to this database,
we can decode the Latin-2 encoded text using this @ref{289a,,text_factory}:

@example
con.text_factory = lambda data: str(data, encoding="latin2")
@end example

For invalid UTF-8 or arbitrary data in stored in @code{TEXT} table columns,
you can use the following technique, borrowed from the @ref{1282,,Guide Unicode}:

@example
con.text_factory = lambda data: str(data, errors="surrogateescape")
@end example

@cartouche
@quotation Note 
The @code{sqlite3} module API does not support strings
containing surrogates.
@end quotation
@end cartouche


@subsubheading Voir aussi


@ref{1282,,Guide Unicode}


@node Explanation,,How-to guides,sqlite3 --- DB-API 2 0 interface for SQLite databases
@anchor{library/sqlite3 explanation}@anchor{28ca}@anchor{library/sqlite3 sqlite3-explanation}@anchor{2856}
@subsubsection Explanation

@anchor{library/sqlite3 sqlite3-transaction-control}@anchor{28cb}
@menu
* Transaction control:: 

@end menu

@node Transaction control,,,Explanation
@anchor{library/sqlite3 sqlite3-controlling-transactions}@anchor{285b}@anchor{library/sqlite3 transaction-control}@anchor{28cc}
@subsubsection Transaction control


@code{sqlite3} offers multiple methods of controlling whether,
when and how database transactions are opened and closed.
@ref{4a0,,Transaction control via the autocommit attribute} is recommended,
while @ref{286a,,Transaction control via the isolation_level attribute}
retains the pre-Python 3.12 behaviour.

@menu
* Transaction control via the autocommit attribute:: 
* Transaction control via the isolation_level attribute:: 

@end menu

@node Transaction control via the autocommit attribute,Transaction control via the isolation_level attribute,,Transaction control
@anchor{library/sqlite3 sqlite3-transaction-control-autocommit}@anchor{4a0}@anchor{library/sqlite3 transaction-control-via-the-autocommit-attribute}@anchor{28cd}
@subsubsection Transaction control via the @code{autocommit} attribute


The recommended way of controlling transaction behaviour is through
the @ref{49f,,Connection.autocommit} attribute,
which should preferably be set using the `autocommit' parameter
of @ref{2a5,,connect()}.

It is suggested to set `autocommit' to @code{False},
which implies 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant transaction control.
This means:


@itemize *

@item 
@code{sqlite3} ensures that a transaction is always open,
so @ref{2a5,,connect()}, @ref{285c,,Connection.commit()}, and @ref{288e,,Connection.rollback()}
will implicitly open a new transaction
(immediately after closing the pending one, for the latter two).
@code{sqlite3} uses @code{BEGIN DEFERRED} statements when opening transactions.

@item 
Transactions should be committed explicitly using @code{commit()}.

@item 
Transactions should be rolled back explicitly using @code{rollback()}.

@item 
An implicit rollback is performed if the database is
@ref{243,,close()}-ed with pending changes.
@end itemize

Set `autocommit' to @code{True} to enable SQLite's autocommit mode@footnote{https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions}.
In this mode, @ref{285c,,Connection.commit()} and @ref{288e,,Connection.rollback()}
have no effect.
Note that SQLite's autocommit mode is distinct from
the 
@geindex Python Enhancement Proposals; PEP 249
PEP 249@footnote{https://peps.python.org/pep-0249/}-compliant @ref{49f,,Connection.autocommit} attribute;
use @ref{2898,,Connection.in_transaction} to query
the low-level SQLite autocommit mode.

Set `autocommit' to @ref{286b,,LEGACY_TRANSACTION_CONTROL}
to leave transaction control behaviour to the
@ref{2869,,Connection.isolation_level} attribute.
See @ref{286a,,Transaction control via the isolation_level attribute} for more information.

@node Transaction control via the isolation_level attribute,,Transaction control via the autocommit attribute,Transaction control
@anchor{library/sqlite3 sqlite3-transaction-control-isolation-level}@anchor{286a}@anchor{library/sqlite3 transaction-control-via-the-isolation-level-attribute}@anchor{28ce}
@subsubsection Transaction control via the @code{isolation_level} attribute


@cartouche
@quotation Note 
The recommended way of controlling transactions is via the
@ref{49f,,autocommit} attribute.
See @ref{4a0,,Transaction control via the autocommit attribute}.
@end quotation
@end cartouche

If @ref{49f,,Connection.autocommit} is set to
@ref{286b,,LEGACY_TRANSACTION_CONTROL} (the default),
transaction behaviour is controlled using
the @ref{2869,,Connection.isolation_level} attribute.
Otherwise, @code{isolation_level} has no effect.

If the connection attribute @ref{2869,,isolation_level}
is not @code{None},
new transactions are implicitly opened before
@ref{2cf,,execute()} and @ref{2d0,,executemany()} executes
@code{INSERT}, @code{UPDATE}, @code{DELETE}, or @code{REPLACE} statements;
for other statements, no implicit transaction handling is performed.
Use the @ref{285c,,commit()} and @ref{288e,,rollback()} methods
to respectively commit and roll back pending transactions.
You can choose the underlying SQLite transaction behaviour@footnote{https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions} —
that is, whether and what type of @code{BEGIN} statements @code{sqlite3}
implicitly executes –
via the @ref{2869,,isolation_level} attribute.

If @ref{2869,,isolation_level} is set to @code{None},
no transactions are implicitly opened at all.
This leaves the underlying SQLite library in autocommit mode@footnote{https://www.sqlite.org/lang_transaction.html#implicit_versus_explicit_transactions},
but also allows the user to perform their own transaction handling
using explicit SQL statements.
The underlying SQLite library autocommit mode can be queried using the
@ref{2898,,in_transaction} attribute.

The @ref{2892,,executescript()} method implicitly commits
any pending transaction before execution of the given SQL script,
regardless of the value of @ref{2869,,isolation_level}.


Modifié dans la version 3.6: @code{sqlite3} used to implicitly commit an open transaction before DDL
statements.  This is no longer the case.



Modifié dans la version 3.12: The recommended way of controlling transactions is now via the
@ref{49f,,autocommit} attribute.


@c import os
@c os.remove("backup.db")
@c os.remove("dump.sql")
@c os.remove("example.db")
@c os.remove("tutorial.db")

@node Compression de donnée et archivage,Formats de fichiers,Persistance des données,La bibliothèque standard
@anchor{library/archiving doc}@anchor{2808}@anchor{library/archiving archiving}@anchor{28cf}@anchor{library/archiving data-compression-and-archiving}@anchor{28d0}
@section Compression de donnée et archivage


Les modules documentés dans ce chapitre implémentent les algorithmes de compression `zlib', `gzip', `bzip2' et `lzma', ainsi que la création d'archives `ZIP' et `tar'. Voir aussi @ref{11f6,,Archiving operations} fourni par le module @ref{c4,,shutil}.

@menu
* zlib: zlib --- Compression compatible with gzip. Compression compatible with gzip
* gzip: gzip --- Support for gzip files. Support for gzip files
* bz2: bz2 --- Support for bzip2 compression. Support for bzip2 compression
* lzma: lzma --- Compression using the LZMA algorithm. Compression using the LZMA algorithm
* zipfile: zipfile --- Work with ZIP archives. Work with ZIP archives
* tarfile: tarfile --- Read and write tar archive files. Read and write tar archive files

@end menu

@node zlib --- Compression compatible with gzip,gzip --- Support for gzip files,,Compression de donnée et archivage
@anchor{library/zlib doc}@anchor{28d1}@anchor{library/zlib module-zlib}@anchor{132}@anchor{library/zlib zlib-compression-compatible-with-gzip}@anchor{28d2}
@subsection @code{zlib} --- Compression compatible with @code{gzip}


@geindex module; zlib


__________________________________________________________________


Pour des applications nécessitant de compresser des données, les fonctions de ce module permettent la compression et la décompression via la bibliothèque `zlib'. La bibliothèque `zlib' a sa propre page web sur @indicateurl{https://www.zlib.net}. Il existe des incompatibilités connues entre le module Python et les versions de la bibliothèque `zlib' plus anciennes que la 1.1.3 ; 1.1.3 contient une faille de sécurité@footnote{https://zlib.net/zlib_faq.html#faq33} et nous recommandons d'utiliser plutôt la version 1.1.4 ou plus récente.

Les fonctions `zlib' recèlent de nombreuses options et il est nécessaire de suivre un ordre précis. Cette documentation n'a pas pour but de couvrir la globalité des possibilités. Aussi, veuillez consulter le manuel `zlib' en ligne sur @indicateurl{http://www.zlib.net/manual.html} pour compléter davantage son utilisation.

Pour lire ou écrire des fichiers @code{.gz} veuillez consulter le module @ref{66,,gzip}.

Les exceptions et fonctions disponibles dans ce module sont :

@geindex error
@anchor{library/zlib zlib error}@anchor{28d3}
@deffn {Exception} zlib.error

Exception levée lors d'erreurs de compression et de décompression.
@end deffn

@geindex adler32() (dans le module zlib)
@anchor{library/zlib zlib adler32}@anchor{17b7}
@deffn {Fonction} zlib.adler32 (data[, value])

Calcule une somme de contrôle Adler-32 de `data' (une somme de contrôle Adler-32 est aussi fiable qu'un CRC32 mais peut être calculée bien plus rapidement). Le résultat produit est un entier non signé de 32-bit. Si `value' est défini, il devient la valeur initiale de la somme de contrôle ; sinon une valeur par défaut de 1 est utilisée. Définir `value' permet de calculer une somme de contrôle continue pendant la concaténation de plusieurs entrées. Cet algorithme n'a aucune garantie cryptographique puissante, et ne doit pas être utilisé ni pour l'authentification, ni pour des signatures numériques. Conçu comme un algorithme de somme de contrôle, il n'est pas adapté pour une utilisation sous forme de clé de hachage générique.


Modifié dans la version 3.0: Renvoie une valeur non-signée.

@end deffn

@geindex compress() (dans le module zlib)
@anchor{library/zlib zlib compress}@anchor{62a}
@deffn {Fonction} zlib.compress (data, /, level=-1, wbits=MAX_WBITS)

Compresses the bytes in `data', returning a bytes object containing compressed data.
`level' is an integer from @code{0} to @code{9} or @code{-1} controlling the level of compression;
@code{1} (Z_BEST_SPEED) is fastest and produces the least compression, @code{9} (Z_BEST_COMPRESSION)
is slowest and produces the most.  @code{0} (Z_NO_COMPRESSION) is no compression.
The default value is @code{-1} (Z_DEFAULT_COMPRESSION).  Z_DEFAULT_COMPRESSION represents a default
compromise between speed and compression (currently equivalent to level 6).
@anchor{library/zlib compress-wbits}@anchor{28d4}
L'argument `wbits' contrôle la taille du tampon d'historique ("`window size'") utilisé lors de la compression, et si un en-tête et un bloc final seront inclus. Il accepte plusieurs intervalles de valeurs, et vaut @code{15} (MAX_WBITS) par défaut :


@itemize *

@item 
De +9 à +15 : le logarithme binaire de la taille du tampon, par conséquent compris entre 512 et 32 768. Des valeurs plus grandes produisent de meilleures compressions aux dépens d'une utilisation mémoire plus grande. Le résultat final inclus des en-têtes et des blocs spécifiques à `zlib'.

@item 
De @code{-9} à @code{-15} : utilise la valeur absolue de `wbits' comme logarithme binaire de la taille du tampon, et ne produit pas d'entêtes ni de bloc final.

@item 
De +25 à +31 = 16 + (9 à 15) : utilise les 4 bits de poids faible comme logarithme binaire de la taille du tampon, tout en incluant un entête @code{gzip} et une somme de contrôle finale.
@end itemize

Raises the @ref{28d3,,error} exception if any error occurs.


Modifié dans la version 3.6: `level' peut maintenant être passé par son nom.



Modifié dans la version 3.11: The `wbits' parameter is now available to set window bits and
compression type.

@end deffn

@geindex compressobj() (dans le module zlib)
@anchor{library/zlib zlib compressobj}@anchor{28d5}
@deffn {Fonction} zlib.compressobj (level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

Renvoie un objet "compresseur", à utiliser pour compresser des flux de données qui ne peuvent pas être stockés entièrement en mémoire.

`level' est le taux de compression -- un entier compris entre @code{0} et @code{9} ou @code{-1}. La valeur @code{1} est la plus rapide avec taux de compression minimal, tandis que la valeur @code{9} est la plus lente mais produit une compression maximale. @code{0} ne produit aucune compression. La valeur par défaut est @code{-1} (`Z_DEFAULT_COMPRESSION'). La constante `Z_DEFAULT_COMPRESSION' équivaut à un bon compromis par défaut entre rapidité et bonne compression (valeur équivalente au niveau 6).

`method' définit l'algorithme de compression. Pour le moment, la seule valeur acceptée est @code{DEFLATED}.

The `wbits' parameter controls the size of the history buffer (or the
"window size"), and what header and trailer format will be used. It has
the same meaning as @ref{28d4,,described for compress()}.

L'argument `memLevel' permet d'ajuster la quantité de mémoire utilisée pour stocker l'état interne de la compression. Les valeurs valides sont comprises entre @code{1} et @code{9}. Des valeurs plus élevées occupent davantage de mémoire, mais sont plus rapides et produisent des sorties plus compressées.

`strategy' permet d'ajuster l'algorithme de compression. Les valeurs possibles sont @code{Z_DEFAULT_STRATEGY}, @code{Z_FILTERED}, et @code{Z_HUFFMAN_ONLY}, @code{Z_RLE} (`zlib' 1.2.0.1) et @code{Z_FIXED} (`zlib' 1.2.2.2).

`zdict' est un dictionnaire de compression prédéfini. C'est une séquence d'octets (tel qu'un objet @ref{1bd,,bytes}) contenant des sous-séquences attendues régulièrement dans les données à compresser. Les sous-séquences les plus fréquentes sont à placer à la fin du dictionnaire.


Modifié dans la version 3.3: Ajout du paramètre `zdict'.

@end deffn

@geindex crc32() (dans le module zlib)
@anchor{library/zlib zlib crc32}@anchor{161e}
@deffn {Fonction} zlib.crc32 (data[, value])

@geindex Cyclic Redundancy Check
@geindex checksum;Cyclic Redundancy Check

Calcule la somme de contrôle CRC (`Cyclic Redundancy Check' en anglais) de l'argument `data'. Il renvoie un entier non signé de 32 bits. Si l'argument `value' est présent, il permet de définir la valeur de départ de la somme de contrôle. Sinon, la valeur par défaut est 0. L'argument `value' permet de calculer la somme de contrôle glissante d'une concaténation de données. L'algorithme n'est pas fort d'un point de vue cryptographique, et ne doit pas être utilisé pour l'authentification ou des signatures numériques. Cet algorithme a été conçu pour être exploité comme un algorithme de somme de contrôle, ce n'est pas un algorithme de hachage générique.


Modifié dans la version 3.0: Renvoie une valeur non-signée.

@end deffn

@geindex decompress() (dans le module zlib)
@anchor{library/zlib zlib decompress}@anchor{cfb}
@deffn {Fonction} zlib.decompress (data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Décompresse les octets de `data', renvoyant un objet `bytes' contenant les données décompressées. Le paramètre `wbits' dépend du format des données compressées, et est abordé plus loin. Si l'argument `bufsize' est défini, il est utilisé comme taille initiale du tampon de sortie. En cas d'erreur, l'exception @ref{28d3,,error} est levée.
@anchor{library/zlib decompress-wbits}@anchor{28d6}
L'argument `wbits' contrôle la taille du tampon d'historique ("`window size'") utilisé lors de la compression, et si un en-tête et un bloc final sont attendus. Similaire au paramètre de @ref{28d5,,compressobj()}, mais accepte une gamme plus large de valeurs :


@itemize *

@item 
De +8 à +15 : logarithme binaire pour la taille du tampon. L'entrée doit contenir un en-tête et un bloc `zlib'.

@item 
0 : détermine automatiquement la taille du tampon à partir de l'en-tête `zlib'. Géré uniquement depuis `zlib' 1.2.3.5.

@item 
De @code{-8} à @code{-15} : utilise la valeur absolue de `wbits' comme logarithme binaire pour la taille du tampon. L'entrée doit être un flux brut, sans en-tête ni bloc final.

@item 
De +24 à +31 = 16 + (8 à 15) : utilise les 4 de poids faible comme logarithme binaire pour la taille du tampon. L'entrée doit contenir un en-tête `gzip' et son bloc final.

@item 
De +40 à +47 = 32 + (8 à 15) : utilise les 4 bits de poids faible comme logarithme binaire pour la taille du tampon, et accepte automatiquement les formats `zlib' ou `gzip'.
@end itemize

Lors de la décompression d'un flux, la taille du tampon ne doit pas être inférieure à la taille initialement utilisée pour compresser le flux. L'utilisation d'une valeur trop petite peut déclencher une exception @ref{28d3,,error}. La valeur par défaut `wbits' correspond à une taille élevée du tampon et nécessite d'y adjoindre un en-tête `zlib' et son bloc final.

L'argument `bufsize' correspond à la taille initiale du tampon utilisé pour contenir les données décompressées. Si plus d'espace est nécessaire, la taille du tampon sera augmentée au besoin, donc vous n'avez pas besoin de deviner la valeur exacte. Un réglage précis n'économisera que quelques appels à @code{malloc()}.


Modifié dans la version 3.6: `wbits' et `bufsize' peuvent être utilisés comme arguments nommés.

@end deffn

@geindex decompressobj() (dans le module zlib)
@anchor{library/zlib zlib decompressobj}@anchor{28d7}
@deffn {Fonction} zlib.decompressobj (wbits=MAX_WBITS[, zdict])

Renvoie un objet "décompresseur", à utiliser pour décompresser des flux de données qui ne rentrent pas entièrement en mémoire.

Le paramètre `wbits' contrôle la taille du tampon, et détermine quel format d'en-tête et de bloc sont prévus. Il a la même signification que décrit pour @ref{28d6,,decompress()}.

Le paramètre `zdict' définit un dictionnaire de compression prédéfini. S'il est fourni, il doit être identique au dictionnaire utilisé par le compresseur, à l'origine des données à décompresser.

@cartouche
@quotation Note 
Si `zdict' est un objet modifiable (tel qu'un @ref{528,,bytearray}, par exemple), vous ne devez pas modifier son contenu entre l'appel à la fonction @ref{28d7,,decompressobj()} et le premier appel à la méthode @code{decompress()} du décompresseur.
@end quotation
@end cartouche


Modifié dans la version 3.3: Ajout du paramètre `zdict'.

@end deffn

Les objets de compression gèrent les méthodes suivantes :

@geindex compress() (méthode zlib.Compress)
@anchor{library/zlib zlib Compress compress}@anchor{28d8}
@deffn {Méthode} Compress.compress (data)

Compresse `data' et renvoie au moins une partie des données compressées sous forme d'objet `bytes'. Ces données doivent être concaténées à la suite des appels précédant à @ref{62a,,compress()}. Certaines entrées peuvent être conservées dans des tampons internes pour un traitement ultérieur.
@end deffn

@geindex flush() (méthode zlib.Compress)
@anchor{library/zlib zlib Compress flush}@anchor{28d9}
@deffn {Méthode} Compress.flush ([mode])

Toutes les entrées mises en attente sont traitées et un objet `bytes' contenant la sortie des données compressées restantes est renvoyé. L'argument `mode' accepte l'une des constantes suivantes : @code{Z_NO_FLUSH}, @code{Z_PARTIAL_FLUSH}, @code{Z_SYNC_FLUSH}, @code{Z_FULL_FLUSH}, @code{Z_BLOCK} (`zlib' 1.2.3.4), et @code{Z_FINISH}, par défaut @code{Z_FINISH}. Sauf @code{Z_FINISH}, toutes les constantes permettent de compresser d'autres chaînes d'octets, tandis que @code{Z_FINISH} finalise le flux compressé et bloque toute autre tentative de compression. Suite à l'appel de la méthode @ref{28d9,,flush()} avec l'argument `mode' défini à @code{Z_FINISH}, la méthode @ref{62a,,compress()} ne peut plus être rappelée. Il ne reste plus qu'à supprimer l'objet.
@end deffn

@geindex copy() (méthode zlib.Compress)
@anchor{library/zlib zlib Compress copy}@anchor{28da}
@deffn {Méthode} Compress.copy ()

Renvoie une copie de l'objet "compresseur". Utile pour compresser efficacement un ensemble de données qui partagent un préfixe initial commun.
@end deffn


Modifié dans la version 3.8: Les objets compresseurs gère maintenant @ref{51d,,copy.copy()} et @ref{b5c,,copy.deepcopy()}.


Les objets décompresseurs prennent en charge les méthodes et attributs suivants :

@geindex unused_data (attribut zlib.Decompress)
@anchor{library/zlib zlib Decompress unused_data}@anchor{28db}
@deffn {Attribut} Decompress.unused_data

Un objet `bytes' contenant tous les octets restants après les données compressées. Il vaut donc @code{b""} tant que des données compressées sont disponibles. Si toute la chaîne d'octets ne contient que des données compressées, il vaut toujours @code{b""}, un objet `bytes' vide.
@end deffn

@geindex unconsumed_tail (attribut zlib.Decompress)
@anchor{library/zlib zlib Decompress unconsumed_tail}@anchor{28dc}
@deffn {Attribut} Decompress.unconsumed_tail

Un objet `bytes' contenant toutes les données non-traitées par le dernier appel à la méthode @ref{cfb,,decompress()}, à cause d'un dépassement de la limite du tampon de données décompressées. Ces données n'ont pas encore été traitées par la bibliothèque `zlib', vous devez donc les envoyer (potentiellement en y concaténant encore des données) par un appel à la méthode @ref{cfb,,decompress()} pour obtenir une sortie correcte.
@end deffn

@geindex eof (attribut zlib.Decompress)
@anchor{library/zlib zlib Decompress eof}@anchor{114d}
@deffn {Attribut} Decompress.eof

Booléen qui signale si la fin du flux compressé est atteint.

This makes it possible to distinguish between a properly formed compressed
stream, and an incomplete or truncated one.


Ajouté dans la version 3.3.

@end deffn

@geindex decompress() (méthode zlib.Decompress)
@anchor{library/zlib zlib Decompress decompress}@anchor{28dd}
@deffn {Méthode} Decompress.decompress (data, max_length=0)

Décompresse `data', renvoie un objet `bytes', contenant au moins une partie des données décompressées. Ce résultat doit être concaténé aux résultats des appels précédents à @ref{cfb,,decompress()}. Des données d'entrée peuvent être conservées dans les tampons internes pour un traitement ultérieur.

Si le paramètre optionnel `max_length' est différent de zéro alors la valeur renvoyée n'est pas plus grande que `max_length'. Cela peut amener à une décompression partielle. Les données non-encore décompressées sont stockées dans l'attribut @ref{28dc,,unconsumed_tail}. Cette chaîne d'octets doit être transmise à un appel ultérieur à @ref{cfb,,decompress()}. Si `max_length' vaut zéro, la totalité de l'entrée est décompressée, et l'attribut @ref{28dc,,unconsumed_tail} reste vide.


Modifié dans la version 3.6: `max_length' peut être utilisé comme un argument nommé.

@end deffn

@geindex flush() (méthode zlib.Decompress)
@anchor{library/zlib zlib Decompress flush}@anchor{28de}
@deffn {Méthode} Decompress.flush ([length])

Toutes les entrées en attente sont traitées, et un objet `bytes' est renvoyé, contenant le reste des données à décompresser. Après l'appel à @ref{28de,,flush()}, la méthode @ref{cfb,,decompress()} ne peut pas être rappelée. Il ne reste qu'à détruire l'objet.

Le paramètre optionnel `length' définit la taille initiale du tampon de sortie.
@end deffn

@geindex copy() (méthode zlib.Decompress)
@anchor{library/zlib zlib Decompress copy}@anchor{28df}
@deffn {Méthode} Decompress.copy ()

Renvoie une copie du décompresseur. Vous pouvez l'utiliser pour sauvegarder l'état de la décompression en cours, afin de pouvoir revenir rapidement à cet endroit plus tard.
@end deffn


Modifié dans la version 3.8: Ajout de @ref{51d,,copy.copy()} et de @ref{b5c,,copy.deepcopy()} au support de décompression d'objets.


Des informations relatives à la version de la bibliothèque `zlib' utilisée sont disponibles via les constantes suivantes :

@geindex ZLIB_VERSION (dans le module zlib)
@anchor{library/zlib zlib ZLIB_VERSION}@anchor{28e0}
@deffn {Données} zlib.ZLIB_VERSION

Version de la bibliothèque `zlib' utilisée lors de la compilation du module. Elle peut être différente de la bibliothèque `zlib' actuellement utilisée par le système, qui est consultable par @ref{114e,,ZLIB_RUNTIME_VERSION}.
@end deffn

@geindex ZLIB_RUNTIME_VERSION (dans le module zlib)
@anchor{library/zlib zlib ZLIB_RUNTIME_VERSION}@anchor{114e}
@deffn {Données} zlib.ZLIB_RUNTIME_VERSION

Chaîne contenant la version de la bibliothèque `zlib' actuellement utilisée par l'interpréteur.


Ajouté dans la version 3.3.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{66,,gzip}

Lire et écrire des fichiers au format @code{gzip}.

@item @indicateurl{http://www.zlib.net}

Page officielle de la bibliothèque `zlib'.

@item @indicateurl{http://www.zlib.net/manual.html}

La documentation de `zlib' explique le sens et l'utilisation des nombreuses fonctions fournies par la bibliothèque.
@end table


@node gzip --- Support for gzip files,bz2 --- Support for bzip2 compression,zlib --- Compression compatible with gzip,Compression de donnée et archivage
@anchor{library/gzip doc}@anchor{28e1}@anchor{library/gzip gzip-support-for-gzip-files}@anchor{28e2}@anchor{library/gzip module-gzip}@anchor{66}
@subsection @code{gzip} --- Support for @code{gzip} files


@geindex module; gzip

`Code source :' Lib/gzip.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/gzip.py}


__________________________________________________________________


Ce module fournit une interface simple pour compresser et décompresser des fichiers tout comme le font les programmes GNU @code{gzip} et @code{gunzip}.

La compression de données est fournie par le module @ref{132,,zlib}.

Le module @ref{66,,gzip} fournit la classe @ref{410,,GzipFile} ainsi que les fonctions pratiques @ref{28e3,,open()}, @ref{629,,compress()} et @ref{11ea,,decompress()}. La classe @ref{410,,GzipFile} lit et écrit des fichiers au format @code{gzip}, compressant et décompressant automatiquement les données pour qu'elles aient l'apparence d'un objet @ref{11a0,,file object} ordinaire.

Notez que les formats de fichier supplémentaires qui peuvent être décompressés par les programmes @code{gzip} et @code{gunzip}, comme ceux produits par le programmes @code{compress} et @code{pack}, ne sont pas gérés par ce module.

Le module définit les éléments suivants :

@geindex open() (dans le module gzip)
@anchor{library/gzip gzip open}@anchor{28e3}
@deffn {Fonction} gzip.open (filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Ouvre un fichier compressé en `gzip' en mode binaire ou texte, renvoie un objet @ref{11a0,,file object}.

L'argument `filename' peut être un nom de fichier (un objet @ref{435,,str} ou @ref{1bd,,bytes}) ou un objet fichier existant que l'on peut lire, ou où l'on peut écrire.

L'argument `mode' peut-être @code{'r'}, @code{'rb'}, @code{'a'}, @code{'ab'}, @code{'w'}, @code{'wb'}, @code{'x'} ou @code{'xb'} pour le mode binaire ou @code{'rt'}, @code{'at'}, @code{'wt'}, ou @code{'xt'} pour le mode texte. Le mode par défaut est @code{'rb'}.

L'argument `compresslevel' est un entier de 0 à 9, comme pour le constructeur de la classe @ref{410,,GzipFile}.

En mode binaire, cette fonction est équivalente au constructeur de la classe @ref{410,,GzipFile} : @code{GzipFile(filename, mode, compresslevel)}. Dans ce cas, les arguments `encoding', `errors' et `newline' ne doivent pas être fournis.

En mode texte, un objet @ref{410,,GzipFile} est créé et empaqueté dans une instance de @ref{7a5,,io.TextIOWrapper} avec l'encodage, la gestion d'erreur et les fins de ligne spécifiés.


Modifié dans la version 3.3: Ajout de la prise en charge de `filename' en tant qu'objet `file', du mode texte et des arguments `encoding', `errors' et `newline'.



Modifié dans la version 3.4: Ajout de la prise en charge des modes @code{'x'}, @code{'xb'} et @code{'xt'}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex BadGzipFile
@anchor{library/gzip gzip BadGzipFile}@anchor{9e5}
@deffn {Exception} gzip.BadGzipFile

An exception raised for invalid gzip files.  It inherits from @ref{40d,,OSError}.
@ref{12b7,,EOFError} and @ref{28d3,,zlib.error} can also be raised for invalid gzip
files.


Ajouté dans la version 3.8.

@end deffn

@geindex GzipFile (classe dans gzip)
@anchor{library/gzip gzip GzipFile}@anchor{410}
@deffn {Classe} gzip.GzipFile (filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

Constructor for the @ref{410,,GzipFile} class, which simulates most of the
methods of a @ref{11a0,,file object}, with the exception of the @ref{12ef,,truncate()}
method.  At least one of `fileobj' and `filename' must be given a non-trivial
value.

La nouvelle instance de classe est basée sur `fileobj' qui peut être un fichier usuel, un objet @ref{e8d,,io.BytesIO} ou tout autre objet qui simule un fichier. `fileobj' est par défaut à `None', dans ce cas `filename' est ouvert afin de fournir un objet fichier.

Quand `fileobj' n'est pas à @code{None}, l'argument `filename' est uniquement utilisé pour être inclus dans l'entête  du fichier @code{gzip}, qui peut inclure le nom original du fichier décompressé. Il est par défaut défini avec le nom de fichier de `fileobj' s'il est discernable, sinon il est par défaut défini à une chaîne de caractères vide et dans ce cas le nom du fichier orignal n'est pas inclus dans l'entête.

The `mode' argument can be any of @code{'r'}, @code{'rb'}, @code{'a'}, @code{'ab'}, @code{'w'},
@code{'wb'}, @code{'x'}, or @code{'xb'}, depending on whether the file will be read or
written.  The default is the mode of `fileobj' if discernible; otherwise, the
default is @code{'rb'}.  In future Python releases the mode of `fileobj' will
not be used.  It is better to always specify `mode' for writing.

Notez que le fichier est toujours ouvert en mode binaire. Pour ouvrir un fichier compressé en mode texte, utilisez la fonction @ref{28e3,,open()} (ou empaquetez votre classe @ref{410,,GzipFile} avec un @ref{7a5,,io.TextIOWrapper}).

L'argument `compresslevel' est un entier de @code{0} à @code{9} contrôlant le niveau de compression, @code{1} est le plus rapide et produit la compression la plus faible et @code{9} est le plus rapide et produit la compression la plus élevée. @code{0} désactive la compression. Par défaut à @code{9}.

The optional `mtime' argument is the timestamp requested by gzip. The time
is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970.
If `mtime' is omitted or @code{None}, the current time is used. Use `mtime' = 0
to generate a compressed stream that does not depend on creation time.

See below for the @ref{28e4,,mtime} attribute that is set when decompressing.

Calling a @ref{410,,GzipFile} object's @code{close()} method does not close
`fileobj', since you might wish to append more material after the compressed
data.  This also allows you to pass an @ref{e8d,,io.BytesIO} object opened for
writing as `fileobj', and retrieve the resulting memory buffer using the
@ref{e8d,,io.BytesIO} object's @ref{28e5,,getvalue()} method.

@ref{410,,GzipFile} supports the @ref{67f,,io.BufferedIOBase} interface,
including iteration and the @ref{5bc,,with} statement.  Only the
@ref{12ef,,truncate()} method isn't implemented.

La classe @ref{410,,GzipFile} fournit aussi la méthode et l'attribut suivant :

@geindex peek() (méthode gzip.GzipFile)
@anchor{library/gzip gzip GzipFile peek}@anchor{11e9}
@deffn {Méthode} peek (n)

Lit `n' octets non compressés sans avancer la position dans le fichier. Au plus une seule lecture sur le flux compressé est faite pour satisfaire l'appel. Le nombre d'octets retournés peut être supérieur ou inférieur au nombre demandé.

@cartouche
@quotation Note 
Bien que l'appel à @ref{11e9,,peek()} ne change pas la position dans le fichier de l'objet @ref{410,,GzipFile}, il peut changer la position de l'objet de fichier sous-jacent (par exemple, si l'instance de @ref{410,,GzipFile} a été construite avec le paramètre `fileobj').
@end quotation
@end cartouche


Ajouté dans la version 3.2.

@end deffn

@geindex mode (attribut gzip.GzipFile)
@anchor{library/gzip gzip GzipFile mode}@anchor{28e6}
@deffn {Attribut} mode

@code{'rb'} for reading and @code{'wb'} for writing.


Modifié dans la version 3.13: In previous versions it was an integer @code{1} or @code{2}.

@end deffn

@geindex mtime (attribut gzip.GzipFile)
@anchor{library/gzip gzip GzipFile mtime}@anchor{28e4}
@deffn {Attribut} mtime

When decompressing, this attribute is set to the last timestamp in the most
recently read header.  It is an integer, holding the number of seconds
since the Unix epoch (00:00:00 UTC, January 1, 1970).
The initial value before reading any headers is @code{None}.
@end deffn

@geindex name (attribut gzip.GzipFile)
@anchor{library/gzip gzip GzipFile name}@anchor{4f6}
@deffn {Attribut} name

The path to the gzip file on disk, as a @ref{435,,str} or @ref{1bd,,bytes}.
Equivalent to the output of @ref{c41,,os.fspath()} on the original input path,
with no other normalization, resolution or expansion.
@end deffn


Modifié dans la version 3.1: Ajout de la prise en charge du mot-clef @ref{5bc,,with}, ainsi que de l'argument `mtime' du constructeur et de l'attribut @ref{28e4,,mtime}.



Modifié dans la version 3.2: Ajout de la prise en charge des fichiers non navigables ou commençant par des octets nuls.



Modifié dans la version 3.3: La méthode @ref{28e7,,io.BufferedIOBase.read1()} est désormais implémentée.



Modifié dans la version 3.4: Ajout de la prise en charge des modes @code{'x'} et @code{'xb'}.



Modifié dans la version 3.5: Ajout de la prise en charge de l'écriture d'objets @ref{d1b,,bytes-like objects} arbitraires. La méthode @ref{1306,,read()} accepte désormais un argument de valeur @code{None}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Obsolète depuis la version 3.9: Opening @ref{410,,GzipFile} for writing without specifying the `mode'
argument is deprecated.



Modifié dans la version 3.12: Remove the @code{filename} attribute, use the @ref{4f6,,name}
attribute instead.

@end deffn

@geindex compress() (dans le module gzip)
@anchor{library/gzip gzip compress}@anchor{629}
@deffn {Fonction} gzip.compress (data, compresslevel=9, *, mtime=None)

Compress the `data', returning a @ref{1bd,,bytes} object containing
the compressed data.  `compresslevel' and `mtime' have the same meaning as in
the @ref{410,,GzipFile} constructor above.


Ajouté dans la version 3.2.



Modifié dans la version 3.8: Added the `mtime' parameter for reproducible output.



Modifié dans la version 3.11: Speed is improved by compressing all data at once instead of in a
streamed fashion. Calls with `mtime' set to @code{0} are delegated to
@ref{62a,,zlib.compress()} for better speed. In this situation the
output may contain a gzip header "OS" byte value other than 255
"unknown" as supplied by the underlying zlib implementation.



Modifié dans la version 3.13: The gzip header OS byte is guaranteed to be set to 255 when this function
is used as was the case in 3.10 and earlier.

@end deffn

@geindex decompress() (dans le module gzip)
@anchor{library/gzip gzip decompress}@anchor{11ea}
@deffn {Fonction} gzip.decompress (data)

Decompress the `data', returning a @ref{1bd,,bytes} object containing the
uncompressed data. This function is capable of decompressing multi-member
gzip data (multiple gzip blocks concatenated together). When the data is
certain to contain only one member the @ref{cfb,,zlib.decompress()} function with
`wbits' set to 31 is faster.


Ajouté dans la version 3.2.



Modifié dans la version 3.11: Speed is improved by decompressing members at once in memory instead of in
a streamed fashion.

@end deffn

@menu
* Exemples d'utilisation:: 
* Interface en ligne de commande:: 

@end menu

@node Exemples d'utilisation,Interface en ligne de commande,,gzip --- Support for gzip files
@anchor{library/gzip examples-of-usage}@anchor{28e8}@anchor{library/gzip gzip-usage-examples}@anchor{28e9}
@subsubsection Exemples d'utilisation


Exemple montrant comment lire un fichier compressé :

@example
import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()
@end example

Exemple montrant comment créer un fichier GZIP :

@example
import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)
@end example

Exemple montrant comment compresser dans un GZIP un fichier existant :

@example
import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)
@end example

Exemple montrant comment compresser dans un GZIP un binaire dans une chaîne :

@example
import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)
@end example


@subsubheading Voir aussi



@table @asis

@item Module @ref{132,,zlib}

Le module de compression de données de base nécessaire pour gérer le format de fichier @code{gzip}.
@end table


@node Interface en ligne de commande,,Exemples d'utilisation,gzip --- Support for gzip files
@anchor{library/gzip command-line-interface}@anchor{28ea}@anchor{library/gzip gzip-cli}@anchor{28eb}
@subsubsection Interface en ligne de commande


The @ref{66,,gzip} module provides a simple command line interface to compress or
decompress files.

Once executed the @ref{66,,gzip} module keeps the input file(s).


Modifié dans la version 3.8: Add a new command line interface with a usage.
By default, when you will execute the CLI, the default compression level is 6.


@menu
* Options de la ligne de commande:: 

@end menu

@node Options de la ligne de commande,,,Interface en ligne de commande
@anchor{library/gzip command-line-options}@anchor{28ec}
@subsubsection Options de la ligne de commande


@geindex option de ligne de commande gzip; file
@anchor{library/gzip cmdoption-gzip-arg-file}@anchor{28ed}
@deffn {Option} file

If `file' is not specified, read from @ref{527,,sys.stdin}.
@end deffn

@geindex option de ligne de commande gzip; --fast
@anchor{library/gzip cmdoption-gzip-fast}@anchor{28ee}
@deffn {Option} @w{-}@w{-}fast

Indicates the fastest compression method (less compression).
@end deffn

@geindex option de ligne de commande gzip; --best
@anchor{library/gzip cmdoption-gzip-best}@anchor{28ef}
@deffn {Option} @w{-}@w{-}best

Indicates the slowest compression method (best compression).
@end deffn

@geindex option de ligne de commande gzip; -d
@geindex option de ligne de commande gzip; --decompress
@anchor{library/gzip cmdoption-gzip-d}@anchor{28f0}@anchor{library/gzip cmdoption-gzip-decompress}@anchor{28f1}
@deffn {Option} @w{-}d, @w{-}@w{-}decompress

Decompress the given file.
@end deffn

@geindex option de ligne de commande gzip; -h
@geindex option de ligne de commande gzip; --help
@anchor{library/gzip cmdoption-gzip-h}@anchor{28f2}@anchor{library/gzip cmdoption-gzip-help}@anchor{28f3}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Affiche le message d'aide.
@end deffn

@node bz2 --- Support for bzip2 compression,lzma --- Compression using the LZMA algorithm,gzip --- Support for gzip files,Compression de donnée et archivage
@anchor{library/bz2 doc}@anchor{28f4}@anchor{library/bz2 bz2-support-for-bzip2-compression}@anchor{28f5}@anchor{library/bz2 module-bz2}@anchor{13}
@subsection @code{bz2} --- Support for @code{bzip2} compression


@geindex module; bz2

`Code Source :' Lib/bz2.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/bz2.py}


__________________________________________________________________


Ce module fournit une interface complète pour compresser et décompresser les données en utilisant l'algorithme de compression `bzip2'.

Le module @ref{13,,bz2} contient :


@itemize *

@item 
La fonction @ref{1077,,open()} et la classe @ref{851,,BZ2File} pour lire et écrire des fichiers compressés.

@item 
Les classes @ref{16eb,,BZ2Compressor} et @ref{16e9,,BZ2Decompressor} pour la (dé)compression incrémentielle.

@item 
Les fonctions @ref{2398,,compress()} et @ref{1078,,decompress()} pour la (dé)compression en une seule fois.
@end itemize

@menu
* (Dé)compression de fichiers: Dé compression de fichiers. 
* (Dé)compression incrémentielle: Dé compression incrémentielle. 
* (Dé)compression en une fois: Dé compression en une fois. 
* Exemples d'utilisation: Exemples d'utilisation<2>. 

@end menu

@node Dé compression de fichiers,Dé compression incrémentielle,,bz2 --- Support for bzip2 compression
@anchor{library/bz2 de-compression-of-files}@anchor{28f6}
@subsubsection (Dé)compression de fichiers


@geindex open() (dans le module bz2)
@anchor{library/bz2 bz2 open}@anchor{1077}
@deffn {Fonction} bz2.open (filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

Ouvre un fichier compressé par `bzip2' en mode binaire ou texte, le renvoyant en @ref{11a0,,file object}.

Tout comme avec le constructeur pour la classe @ref{851,,BZ2File}, l'argument `filename' peut être un nom de fichier réel (un objet @ref{435,,str} ou @ref{1bd,,bytes}), ou un objet fichier existant à lire ou à écrire.

L'argument `mode' peut valoir @code{'r'}, @code{'rb'}, @code{'w'}, @code{'wb'}, @code{'x'}, @code{'xb'}, @code{'a'} ou @code{'ab'} pour le mode binaire, ou @code{'rt'}, @code{'wt'}, @code{'xt'} ou @code{'at'} pour le mode texte. Il vaut par défaut @code{'rb'}.

L'argument `compresslevel' est un entier de 1 à 9, comme pour le constructeur @ref{851,,BZ2File}.

Pour le mode binaire, cette fonction est équivalente au constructeur @ref{851,,BZ2File} : @code{BZ2File(filename, mode, compresslevel=compresslevel)}. Dans ce cas, les arguments `encoding', `errors' et `newline' arguments ne doivent pas être fournis.

Pour le mode texte, un objet @ref{851,,BZ2File} est créé et encapsulé dans une instance @ref{7a5,,io.TextIOWrapper} avec l'encodage spécifié, le comportement de gestion des erreurs et les fins de ligne.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: Le mode @code{'x'} (création exclusive) est ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex BZ2File (classe dans bz2)
@anchor{library/bz2 bz2 BZ2File}@anchor{851}
@deffn {Classe} bz2.BZ2File (filename, mode='r', *, compresslevel=9)

Ouvre un fichier `bzip2' en mode binaire.

Si `filename' est un objet @ref{435,,str} ou @ref{1bd,,bytes}, ouvre le nom de fichier directement. Autrement, `filename' doit être un @ref{11a0,,file object}, qui est utilisé pour lire ou écrire les données compressées.

L'argument `mode' peut être soit @code{'r'} pour lire (par défaut), @code{'w'} pour écraser, @code{'x'} pour créer exclusivement, ou @code{'a'} pour ajouter. Ils peuvent également être écrits respectivement comme @code{'rb'}, @code{'wb'}, @code{'xb'} et @code{'ab'}.

Si `filename' est un objet fichier (plutôt que le nom de fichier réel), le mode @code{'w'} ne tronque pas le fichier, mais équivaut à @code{'a'}.

Si `mode' est @code{'w'} ou @code{'a'}, `compresslevel' peut être un entier entre @code{1} et @code{9} spécifiant le niveau de compression : @code{1} utilise la compression la moins forte, et @code{9} (par défaut) la compression la plus forte.

Si `mode' est @code{'r'}, le fichier d'entrée peut être la concaténation de plusieurs flux compressés.

@ref{851,,BZ2File} provides all of the members specified by the
@ref{67f,,io.BufferedIOBase}, except for @ref{28f7,,detach()}
and @ref{12ef,,truncate()}.
Iteration and the @ref{5bc,,with} statement are supported.

@ref{851,,BZ2File} also provides the following methods and attributes:

@geindex peek() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File peek}@anchor{28f8}
@deffn {Méthode} peek ([n])

Renvoie des données en mémoire tampon sans avancer la position du fichier. Au moins un octet de donnée (sauf l'EOF) est renvoyé. Le nombre exact d'octets renvoyés n'est pas spécifié.

@cartouche
@quotation Note 
Bien que l'appel à la méthode @ref{28f8,,peek()} ne change pas la position du fichier de la classe @ref{851,,BZ2File}, il peut changer la position de l'objet fichier sous-jacent (e.g. si la classe @ref{851,,BZ2File} a été construite en passant un objet fichier à `filename').
@end quotation
@end cartouche


Ajouté dans la version 3.3.

@end deffn

@geindex fileno() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File fileno}@anchor{28f9}
@deffn {Méthode} fileno ()

Return the file descriptor for the underlying file.


Ajouté dans la version 3.3.

@end deffn

@geindex readable() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File readable}@anchor{28fa}
@deffn {Méthode} readable ()

Return whether the file was opened for reading.


Ajouté dans la version 3.3.

@end deffn

@geindex seekable() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File seekable}@anchor{28fb}
@deffn {Méthode} seekable ()

Return whether the file supports seeking.


Ajouté dans la version 3.3.

@end deffn

@geindex writable() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File writable}@anchor{28fc}
@deffn {Méthode} writable ()

Return whether the file was opened for writing.


Ajouté dans la version 3.3.

@end deffn

@geindex read1() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File read1}@anchor{28fd}
@deffn {Méthode} read1 (size=-1)

Read up to `size' uncompressed bytes, while trying to avoid
making multiple reads from the underlying stream. Reads up to a
buffer's worth of data if size is negative.

Returns @code{b'@w{'}} if the file is at EOF.


Ajouté dans la version 3.3.

@end deffn

@geindex readinto() (méthode bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File readinto}@anchor{28fe}
@deffn {Méthode} readinto (b)

Read bytes into `b'.

Returns the number of bytes read (0 for EOF).


Ajouté dans la version 3.3.

@end deffn

@geindex mode (attribut bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File mode}@anchor{28ff}
@deffn {Attribut} mode

@code{'rb'} for reading and @code{'wb'} for writing.


Ajouté dans la version 3.13.

@end deffn

@geindex name (attribut bz2.BZ2File)
@anchor{library/bz2 bz2 BZ2File name}@anchor{2900}
@deffn {Attribut} name

The bzip2 file name.  Equivalent to the @ref{2901,,name}
attribute of the underlying @ref{11a0,,file object}.


Ajouté dans la version 3.13.

@end deffn


Modifié dans la version 3.1: La prise en charge de l'instruction @ref{5bc,,with} a été ajoutée.



Modifié dans la version 3.3: La gestion de `filename' comme @ref{11a0,,file object} au lieu d'un nom de fichier réel a été ajoutée.

Le mode @code{'a'} (ajout) a été ajouté, avec la prise en charge de la lecture des fichiers `multiflux'.



Modifié dans la version 3.4: Le mode @code{'x'} (création exclusive) est ajouté.



Modifié dans la version 3.5: La méthode @ref{1306,,read()} accepte maintenant un argument @code{None}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.9: Le paramètre `buffering' a été supprimé. Il était ignoré et obsolète depuis Python 3.0. Passez un objet fichier déjà ouvert si vous voulez contrôler la façon dont le fichier est ouvert.

Le paramètre `compresslevel' est devenu un paramètre exclusivement nommé.



Modifié dans la version 3.10: Cette classe n'est plus protégée d'un accès concurrent malheureux par plusieurs lecteurs ou compresseurs. C'était déjà le cas depuis toujours des classes analogues dans les modules @ref{66,,gzip} et @ref{89,,lzma}.

@end deffn

@node Dé compression incrémentielle,Dé compression en une fois,Dé compression de fichiers,bz2 --- Support for bzip2 compression
@anchor{library/bz2 incremental-de-compression}@anchor{2902}
@subsubsection (Dé)compression incrémentielle


@geindex BZ2Compressor (classe dans bz2)
@anchor{library/bz2 bz2 BZ2Compressor}@anchor{16eb}
@deffn {Classe} bz2.BZ2Compressor (compresslevel=9)

Crée un nouvel objet compresseur. Cet objet peut être utilisé pour compresser les données de manière incrémentielle. Pour une compression en une seule fois, utilisez à la place la fonction @ref{2398,,compress()}.

`compresslevel', s'il est fourni, doit être un entier entre @code{1} et @code{9}. Sa valeur par défaut est @code{9}.

@geindex compress() (méthode bz2.BZ2Compressor)
@anchor{library/bz2 bz2 BZ2Compressor compress}@anchor{2903}
@deffn {Méthode} compress (data)

Fournit la donnée à l'objet compresseur. Renvoie un bloc de données compressées si possible, ou autrement une chaîne d'octet vide.

Quand vous avez fini de fournir des données au compresseur, appelez la méthode @ref{2904,,flush()} pour finir le processus de compression.
@end deffn

@geindex flush() (méthode bz2.BZ2Compressor)
@anchor{library/bz2 bz2 BZ2Compressor flush}@anchor{2904}
@deffn {Méthode} flush ()

Finit le processus de compression. Renvoie la donnée compressée restante dans les tampons internes.

L'objet compresseur ne peut pas être utilisé après que cette méthode a été appelée.
@end deffn
@end deffn

@geindex BZ2Decompressor (classe dans bz2)
@anchor{library/bz2 bz2 BZ2Decompressor}@anchor{16e9}
@deffn {Classe} bz2.BZ2Decompressor

Crée un nouvel objet décompresseur. Cet objet peut être utilisé pour décompresser les données de manière incrémentielle. Pour une compression en une seule fois, utilisez à la place la fonction @ref{1078,,decompress()}.

@cartouche
@quotation Note 
Cette classe ne gère pas de manière transparente les entrées contenant plusieurs flux compressés, à la différence de @ref{1078,,decompress()} et @ref{851,,BZ2File}. Si vous avez besoin de décompresser une entrée `multiflux' avec la classe @ref{16e9,,BZ2Decompressor}, vous devez utiliser un nouveau décompresseur pour chaque flux.
@end quotation
@end cartouche

@geindex decompress() (méthode bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor decompress}@anchor{db9}
@deffn {Méthode} decompress (data, max_length=-1)

Décompresse `data' (un @ref{d1b,,bytes-like object}), renvoyant une donnée non compressée en tant que chaîne d'octets. Certaines de ces `data' peuvent être mises en interne en tampon, pour un usage lors d'appels ultérieurs par la méthode @ref{1078,,decompress()}. La donnée renvoyée doit être concaténée avec la sortie des appels précédents à la méthode @ref{1078,,decompress()}.

Si `max_length' est positif, renvoie au plus `max_length' octets de données compressées. Si la limite est atteinte et que d'autres sorties peuvent être produites, l'attribut @ref{2905,,needs_input} est positionné sur @code{False}. Dans ce cas, lors de l'appel suivant à la méthode @ref{db9,,decompress()}, vous pouvez fournir @code{b'@w{'}} dans `data' afin d'obtenir la suite de la sortie.

Si toutes les données entrées ont été décompressées et renvoyées (soit parce qu'il y avait moins de `max_length' octets, ou parce que `max_length' était négatif), l'attribut @ref{2905,,needs_input} sera configuré sur @code{True}.

Attempting to decompress data after the end of stream is reached
raises an @ref{12b7,,EOFError}.  Any data found after the end of the
stream is ignored and saved in the @ref{2906,,unused_data} attribute.


Modifié dans la version 3.5: Ajout du paramètre `max_length'.

@end deffn

@geindex eof (attribut bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor eof}@anchor{2907}
@deffn {Attribut} eof

@code{True} si le marqueur de fin de flux a été atteint.


Ajouté dans la version 3.3.

@end deffn

@geindex unused_data (attribut bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor unused_data}@anchor{2906}
@deffn {Attribut} unused_data

Donnée trouvée après la fin du flux compressé.

Si l'attribut est accédé avant que la fin du flux ait été atteint, sa valeur sera @code{b'@w{'}}.
@end deffn

@geindex needs_input (attribut bz2.BZ2Decompressor)
@anchor{library/bz2 bz2 BZ2Decompressor needs_input}@anchor{2905}
@deffn {Attribut} needs_input

@code{False} si la méthode @ref{db9,,decompress()} peut fournir plus de données décompressées avant l'acquisition d'une nouvelle entrée non compressée.


Ajouté dans la version 3.5.

@end deffn
@end deffn

@node Dé compression en une fois,Exemples d'utilisation<2>,Dé compression incrémentielle,bz2 --- Support for bzip2 compression
@anchor{library/bz2 one-shot-de-compression}@anchor{2908}
@subsubsection (Dé)compression en une fois


@geindex compress() (dans le module bz2)
@anchor{library/bz2 bz2 compress}@anchor{2398}
@deffn {Fonction} bz2.compress (data, compresslevel=9)

Compresse `data', un @ref{d1b,,bytes-like object}.

`compresslevel', s'il est fourni, doit être un entier entre @code{1} et @code{9}. Sa valeur par défaut est @code{9}.

Pour la compression incrémentielle, utilisez à la place la classe @ref{16eb,,BZ2Compressor}.
@end deffn

@geindex decompress() (dans le module bz2)
@anchor{library/bz2 bz2 decompress}@anchor{1078}
@deffn {Fonction} bz2.decompress (data)

Décompresse `data', un @ref{d1b,,bytes-like object}.

Si `data' est la concaténation de multiples flux compressés, décompresse tous les flux.

Pour une décompression incrémentielle, utilisez à la place la classe @ref{16e9,,BZ2Decompressor}.


Modifié dans la version 3.3: Prise en charge des entrées `multiflux'.

@end deffn

@node Exemples d'utilisation<2>,,Dé compression en une fois,bz2 --- Support for bzip2 compression
@anchor{library/bz2 bz2-usage-examples}@anchor{2909}@anchor{library/bz2 examples-of-usage}@anchor{290a}
@subsubsection Exemples d'utilisation


Ci-dessous, nous présentons quelques exemples typiques de l'utilisation du module @ref{13,,bz2}.

Utilise les fonctions @ref{2398,,compress()} et @ref{1078,,decompress()} pour démontrer une compression aller-retour :

@example
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True
@end example

Utilise la classe @ref{16eb,,BZ2Compressor} pour une compression incrémentielle :

@example
>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()
@end example

The example above uses a very "nonrandom" stream of data
(a stream of @code{b"z"} chunks).  Random data tends to compress poorly,
while ordered, repetitive data usually yields a high compression ratio.

Écriture et lecture en mode binaire d'un fichier compressé avec `bzip2' :

@example
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
...
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
...
>>> content == data  # Check equality to original object after round-trip
True
@end example

@c import os
@c os.remove("myfile.bz2")

@node lzma --- Compression using the LZMA algorithm,zipfile --- Work with ZIP archives,bz2 --- Support for bzip2 compression,Compression de donnée et archivage
@anchor{library/lzma doc}@anchor{290b}@anchor{library/lzma lzma-compression-using-the-lzma-algorithm}@anchor{290c}@anchor{library/lzma module-lzma}@anchor{89}
@subsection @code{lzma} --- Compression using the LZMA algorithm


@geindex module; lzma


Ajouté dans la version 3.3.


`Code source :' Lib/lzma.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/lzma.py}


__________________________________________________________________


Ce module fournit des classes et des fonctions utiles pour compresser et décompresser des données en utilisant l'algorithme de compression LZMA. Ce module inclut aussi aussi une interface prenant en charge les fichiers @code{.xz} et son format originel @code{.lzma} utilisés par l'utilitaire @code{xz}, ainsi que les flux bruts compressés.

The interface provided by this module is very similar to that of the @ref{13,,bz2}
module. Note that @ref{ff5,,LZMAFile} and @ref{851,,bz2.BZ2File} are `not'
thread-safe, so if you need to use a single @ref{ff5,,LZMAFile} instance
from multiple threads, it is necessary to protect it with a lock.

@geindex LZMAError
@anchor{library/lzma lzma LZMAError}@anchor{290d}
@deffn {Exception} lzma.LZMAError

Cette exception est levée dès lors qu'une erreur survient pendant la compression ou la décompression, ou pendant l'initialisation de l'état de la compression/décompression.
@end deffn

@menu
* Lire et écrire des fichiers compressés:: 
* Compresser et décompresser une donnée en mémoire:: 
* Divers: Divers<2>. 
* Préciser des chaînes de filtre personnalisées:: 
* Exemples: Exemples<8>. 

@end menu

@node Lire et écrire des fichiers compressés,Compresser et décompresser une donnée en mémoire,,lzma --- Compression using the LZMA algorithm
@anchor{library/lzma reading-and-writing-compressed-files}@anchor{290e}
@subsubsection Lire et écrire des fichiers compressés


@geindex open() (dans le module lzma)
@anchor{library/lzma lzma open}@anchor{290f}
@deffn {Fonction} lzma.open (filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

Open an LZMA-compressed file in binary or text mode, returning a @ref{11a0,,file object}.

L'argument `nom de fichier' peut être soit le nom d'un fichier à créer (donné pour @ref{435,,str}, @ref{1bd,,bytes} ou un objet @ref{29d,,path-like}), dont le fichier nommé reste ouvert, ou soit un objet fichier existant à lire ou à écrire.

L'argument `mode' peut être n'importe quel argument suivant : @code{"r"}, @code{"rb"}, @code{"w"}, @code{"wb"}, @code{"x"}, @code{"xb"}, @code{"a"} ou @code{"ab"} pour le mode binaire, ou @code{"rt"}, @code{"wt"}, @code{"xt"}, ou @code{"at"} pour le mode texte. La valeur par défaut est @code{"rb"}.

Quand un fichier est ouvert pour le lire, les arguments `format' et `filters' ont les mêmes significations que pour la @ref{16e8,,LZMADecompressor}. Par conséquent, les arguments `check' et `preset' ne devront pas être sollicités.

Dès ouverture d'un fichier pour l'écriture, les arguments `format', `check', `preset' et `filters' ont le même sens que dans la @ref{16ea,,LZMACompressor}.

Pour le mode binaire, cette fonction équivaut au constructeur de la @ref{ff5,,LZMAFile} : @code{LZMAFile(filename, mode, ...)}. Dans ce cas précis, les arguments `encoding', `errors' et `newline' ne sont pas accessibles.

For text mode, a @ref{ff5,,LZMAFile} object is created, and wrapped in an
@ref{7a5,,io.TextIOWrapper} instance with the specified encoding, error
handling behavior, and line ending(s).


Modifié dans la version 3.4: Support ajouté pour les modes @code{"x"}, @code{"xb"} et @code{"xt"}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex LZMAFile (classe dans lzma)
@anchor{library/lzma lzma LZMAFile}@anchor{ff5}
@deffn {Classe} lzma.LZMAFile (filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)

Ouvre un fichier LZMA compressé en mode binaire.

An @ref{ff5,,LZMAFile} can wrap an already-open @ref{11a0,,file object}, or operate
directly on a named file. The `filename' argument specifies either the file
object to wrap, or the name of the file to open (as a @ref{435,,str},
@ref{1bd,,bytes} or @ref{29d,,path-like} object). When wrapping an
existing file object, the wrapped file will not be closed when the
@ref{ff5,,LZMAFile} is closed.

L'argument `mode' peut être soit @code{"r"} pour la lecture (défaut), @code{"w"} pour la ré-écriture, @code{"x"} pour la création exclusive, ou @code{"a"} pour l'insertion. Elles peuvent aussi être écrites de la façon suivante : @code{"rb"}, @code{"wb"}, @code{"xb"} et @code{"ab"} respectivement.

If `filename' is a file object (rather than an actual file name), a mode of
@code{"w"} does not truncate the file, and is instead equivalent to @code{"a"}.

Dès l'ouverture d'un fichier pour être lu, le fichier d'entrée peut être le résultat d'une concaténation de plusieurs flux distincts et compressés. Ceux-ci sont décodés de manière transparente en un seul flux logique.

Quand un fichier est ouvert pour le lire, les arguments `format' et `filters' ont les mêmes significations que pour la @ref{16e8,,LZMADecompressor}. Par conséquent, les arguments `check' et `preset' ne devront pas être sollicités.

Dès ouverture d'un fichier pour l'écriture, les arguments `format', `check', `preset' et `filters' ont le même sens que dans la @ref{16ea,,LZMACompressor}.

@ref{ff5,,LZMAFile} supports all the members specified by
@ref{67f,,io.BufferedIOBase}, except for @ref{28f7,,detach()}
and @ref{12ef,,truncate()}.
Iteration and the @ref{5bc,,with} statement are supported.

The following method and attributes are also provided:

@geindex peek() (méthode lzma.LZMAFile)
@anchor{library/lzma lzma LZMAFile peek}@anchor{2910}
@deffn {Méthode} peek (size=-1)

Renvoie la donnée en mémoire-tampon sans progression de la position du fichier. Au moins un octet de donnée sera renvoyé, jusqu'à ce que l'EOF soit atteinte. Le nombre exact d'octets renvoyés demeure indéterminé (l'argument `taille' est ignoré).

@cartouche
@quotation Note 
While calling @ref{2910,,peek()} does not change the file position of
the @ref{ff5,,LZMAFile}, it may change the position of the underlying
file object (e.g. if the @ref{ff5,,LZMAFile} was constructed by passing a
file object for `filename').
@end quotation
@end cartouche
@end deffn

@geindex mode (attribut lzma.LZMAFile)
@anchor{library/lzma lzma LZMAFile mode}@anchor{2911}
@deffn {Attribut} mode

@code{'rb'} for reading and @code{'wb'} for writing.


Ajouté dans la version 3.13.

@end deffn

@geindex name (attribut lzma.LZMAFile)
@anchor{library/lzma lzma LZMAFile name}@anchor{2912}
@deffn {Attribut} name

The lzma file name.  Equivalent to the @ref{2901,,name}
attribute of the underlying @ref{11a0,,file object}.


Ajouté dans la version 3.13.

@end deffn


Modifié dans la version 3.4: Added support for the @code{"x"} and @code{"xb"} modes.



Modifié dans la version 3.5: La méthode @ref{1306,,read()} accepte maintenant un argument @code{None}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@node Compresser et décompresser une donnée en mémoire,Divers<2>,Lire et écrire des fichiers compressés,lzma --- Compression using the LZMA algorithm
@anchor{library/lzma compressing-and-decompressing-data-in-memory}@anchor{2913}
@subsubsection Compresser et décompresser une donnée en mémoire


@geindex LZMACompressor (classe dans lzma)
@anchor{library/lzma lzma LZMACompressor}@anchor{16ea}
@deffn {Classe} lzma.LZMACompressor (format=FORMAT_XZ, check=-1, preset=None, filters=None)

Créé un objet compresseur, qui peut être utilisé pour compresser incrémentalement une donnée.

Pour une façon plus adaptée de compresser un seul extrait de donnée, voir @ref{2914,,compress()}.

L'argument `format' définit quel format de conteneur sera mis en œuvre. Les valeurs possibles sont :


@itemize *

@item 

@table @asis

@item @code{FORMAT_XZ}: Le format du  conteneur @code{.xz}.

C'est le format par défaut.
@end table

@item 

@table @asis

@item @code{FORMAT_ALONE}: L'ancien format du conteneur @code{.lzma}.

Ce format est davantage limité que @code{.xz} --il ne supporte pas les vérifications d'intégrité ou les filtres multiples.
@end table

@item 

@table @asis

@item @code{FORMAT_RAW}: Un flux de données brut, n'utilisant aucun format de conteneur.

Ce format spécifique ne prend pas en charge les vérifications d'intégrité et exige systématiquement la définition d'une chaîne de filtrage personnalisée (à la fois pour la compression et la décompression). Par ailleurs, les données compressées par ce biais ne peuvent pas être décompressées par l'usage de @code{FORMAT_AUTO} (voir :  @ref{16e8,,LZMADecompressor}).
@end table
@end itemize

L'argument `check' détermine le type de vérification d'intégrité à exploiter avec la donnée compressée. Cette vérification est déclenchée lors de la décompression, pour garantir que la donnée n'a pas été corrompue. Les valeurs possibles sont :


@itemize *

@item 
@code{CHECK_NONE}: Pas de vérification d'intégrité. C'est la valeur par défaut (et la seule valeur acceptable) pour @code{FORMAT_ALONE} et @code{FORMAT_RAW}.

@item 
@code{CHECK_CRC32}: Vérification par Redondance Cyclique 32-bit (`Cyclic Redundancy Check').

@item 
@code{CHECK_CRC64}: Vérification par Redondance Cyclique 64-bit (`Cyclic Redundancy Check'). Valeur par défaut pour @code{FORMAT_XZ}.

@item 
@code{CHECK_SHA256}: Algorithme de Hachage Sécurisé 256-bit (`Secure Hash Algorithm').
@end itemize

Si le type de vérification n'est pas supporté par le système, une erreur de type @ref{290d,,LZMAError} est levée.

Les réglages de compression peuvent être définis soit comme un pré-réglage de niveau de compression (avec l'argument `preset') ; soit de façon détaillée comme une chaîne particulière de filtres (avec l'argument `filters').

L'argument `preset' (s'il est fourni) doit être un entier compris entre @code{0} et @code{9} (inclus), éventuellement relié à OR avec la constante @code{PRESET_EXTREME}. Si aucun `preset' ni `filters' ne ont définis, le comportement par défaut consiste à utiliser la @code{PRESET_DEFAULT} (niveau par défaut : @code{6}). Des pré-réglages plus élevés entraîne une sortie plus petite, mais rend le processus de compression plus lent.

@cartouche
@quotation Note 
En plus d'être plus gourmande en CPU, la compression avec des préréglages plus élevés nécessite beaucoup plus de mémoire (et produit des résultats qui nécessitent plus de mémoire pour décompresser). Par exemple, avec le préréglage @code{9}, l'objet d'une @ref{16ea,,LZMACompressor} peut dépasser largement les 800 Mo. Pour cette raison, il est généralement préférable de respecter le préréglage par défaut.
@end quotation
@end cartouche

L'argument `filters' (s'il est défini) doit être un critère de la chaîne de filtrage. Voir @ref{2915,,Préciser des chaînes de filtre personnalisées} pour plus de précisions.

@geindex compress() (méthode lzma.LZMACompressor)
@anchor{library/lzma lzma LZMACompressor compress}@anchor{2916}
@deffn {Méthode} compress (data)

Une `data' compressée (un objet @ref{1bd,,bytes}), renvoie un objet @ref{1bd,,bytes} contenant une donnée compressée pour au moins une partie de l'entrée. Certaine `data' peuvent être mise en tampon, pour être utiliser lors de prochains appels par @ref{2914,,compress()} et @ref{2917,,flush()}. La donnée renvoyée pourra être concaténée avec la sortie d'appels précédents vers la méthode @ref{2914,,compress()}.
@end deffn

@geindex flush() (méthode lzma.LZMACompressor)
@anchor{library/lzma lzma LZMACompressor flush}@anchor{2917}
@deffn {Méthode} flush ()

Conclut l'opération de compression, en renvoyant l'objet @ref{1bd,,bytes} constitué de toutes les données stockées dans les tampons interne du compresseur.

The compressor cannot be used after this method has been called.
@end deffn
@end deffn

@geindex LZMADecompressor (classe dans lzma)
@anchor{library/lzma lzma LZMADecompressor}@anchor{16e8}
@deffn {Classe} lzma.LZMADecompressor (format=FORMAT_AUTO, memlimit=None, filters=None)

Créé un objet de décompression, pour décompresser de façon incrémentale une donnée.

Pour un moyen plus pratique de décompresser un flux compressé complet en une seule fois, voir @ref{2918,,decompress()}.

L'argument `format' spécifie le format du conteneur à utiliser. La valeur par défaut est @code{FORMAT_AUTO} pouvant à la fois décompresser les fichiers @code{.xz} et @code{.lzma}. D'autres valeurs sont possibles comme @code{FORMAT_XZ}, @code{FORMAT_ALONE}, et @code{FORMAT_RAW}.

L'argument `memlimit' spécifie une limite (en octets) sur la quantité de mémoire que le décompresseur peut utiliser. Lorsque cet argument est utilisé, la décompression échouera avec une @ref{290d,,LZMAError} s'il n'est pas possible de décompresser l'entrée dans la limite mémoire disponible.

L'argument `filters' spécifie la chaîne de filtrage utilisée pour créer le flux décompressé. Cet argument est requis si `format' est @code{FORMAT_RAW}, mais ne doit pas être utilisé pour d'autres formats. Voir @ref{2915,,Préciser des chaînes de filtre personnalisées} pour plus d'informations sur les chaînes de filtrage.

@cartouche
@quotation Note 
Cette classe ne gère pas de manière transparente les entrées contenant plusieurs flux compressés, contrairement à @ref{2918,,decompress()} et @ref{ff5,,LZMAFile}. Pour décompresser une entrée multi-flux avec  @ref{16e8,,LZMADecompressor}, vous devez créer un nouveau décompresseur à chaque flux.
@end quotation
@end cartouche

@geindex decompress() (méthode lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor decompress}@anchor{e1b}
@deffn {Méthode} decompress (data, max_length=-1)

Décompresse `data' (un @ref{d1b,,bytes-like object}), renvoyant une donnée non compressée en tant que chaîne d'octets. Certaines de ces `data' peuvent être mises en interne en tampon, pour un usage lors d'appels ultérieurs par la méthode @ref{2918,,decompress()}. La donnée renvoyée doit être concaténée avec la sortie des appels précédents à la méthode @ref{2918,,decompress()}.

Si `max_length' est positif, renvoie au plus `max_length' octets de données compressées. Si la limite est atteinte et que d'autres sorties peuvent être produites, l'attribut @ref{2919,,needs_input} est positionné sur @code{False}. Dans ce cas, lors de l'appel suivant à la méthode @ref{e1b,,decompress()}, vous pouvez fournir @code{b'@w{'}} dans `data' afin d'obtenir la suite de la sortie.

Si toutes les données entrées ont été décompressées et renvoyées (soit parce qu'il y avait moins de `max_length' octets, ou parce que `max_length' était négatif), l'attribut @ref{2919,,needs_input} sera configuré sur @code{True}.

Attempting to decompress data after the end of stream is reached
raises an @ref{12b7,,EOFError}.  Any data found after the end of the
stream is ignored and saved in the @ref{291a,,unused_data} attribute.


Modifié dans la version 3.5: Ajout du paramètre `max_length'.

@end deffn

@geindex check (attribut lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor check}@anchor{291b}
@deffn {Attribut} check

L'ID de la vérification d'intégrité exploité par le flux entrant. Il s'agit de @code{CHECK_UNKNOWN} tant que ce flux a été décodé pour déterminer quel type de vérification d'intégrité à été utilisé.
@end deffn

@geindex eof (attribut lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor eof}@anchor{291c}
@deffn {Attribut} eof

@code{True} si le marqueur de fin de flux a été atteint.
@end deffn

@geindex unused_data (attribut lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor unused_data}@anchor{291a}
@deffn {Attribut} unused_data

Donnée trouvée après la fin du flux compressé.

Avant d'atteindre la fin du flux, ce sera @code{b""}.
@end deffn

@geindex needs_input (attribut lzma.LZMADecompressor)
@anchor{library/lzma lzma LZMADecompressor needs_input}@anchor{2919}
@deffn {Attribut} needs_input

@code{False} si la méthode @ref{e1b,,decompress()} peut fournir plus de données décompressées avant l'acquisition d'une nouvelle entrée non compressée.


Ajouté dans la version 3.5.

@end deffn
@end deffn

@geindex compress() (dans le module lzma)
@anchor{library/lzma lzma compress}@anchor{2914}
@deffn {Fonction} lzma.compress (data, format=FORMAT_XZ, check=-1, preset=None, filters=None)

`data' compressée (un objet @ref{1bd,,bytes}), renvoyant une donnée compressée comme un objet @ref{1bd,,bytes}.

Voir @ref{16ea,,LZMACompressor} ci-dessus pour une description des arguments `format', `check', `preset' et `filters'.
@end deffn

@geindex decompress() (dans le module lzma)
@anchor{library/lzma lzma decompress}@anchor{2918}
@deffn {Fonction} lzma.decompress (data, format=FORMAT_AUTO, memlimit=None, filters=None)

Décompresse `data' (un objet @ref{1bd,,bytes} ), et retourne la donnée décompressée sous la forme d'un objet @ref{1bd,,bytes}.

Si `data' est le résultat de la concaténation de plusieurs flux compressés et distincts , il les décompresse tous, et retourne les résultats concaténés.

Voir @ref{16e8,,LZMADecompressor} ci-dessus pour une description des arguments `format', `memlimit' et `filters'.
@end deffn

@node Divers<2>,Préciser des chaînes de filtre personnalisées,Compresser et décompresser une donnée en mémoire,lzma --- Compression using the LZMA algorithm
@anchor{library/lzma miscellaneous}@anchor{291d}
@subsubsection Divers


@geindex is_check_supported() (dans le module lzma)
@anchor{library/lzma lzma is_check_supported}@anchor{291e}
@deffn {Fonction} lzma.is_check_supported (check)

Return @code{True} if the given integrity check is supported on this system.

@code{CHECK_NONE} et @code{CHECK_CRC32} sont toujours pris en charge. @code{CHECK_CRC64} et @code{CHECK_SHA256} peuvent être indisponibles si vous utilisez une version de @code{liblzma} compilée avec des possibilités restreintes.
@end deffn

@node Préciser des chaînes de filtre personnalisées,Exemples<8>,Divers<2>,lzma --- Compression using the LZMA algorithm
@anchor{library/lzma filter-chain-specs}@anchor{2915}@anchor{library/lzma specifying-custom-filter-chains}@anchor{291f}
@subsubsection Préciser des chaînes de filtre personnalisées


Une chaîne de filtres est une séquence de dictionnaires, où chaque dictionnaire contient l'ID et les options pour chaque filtre. Le moindre dictionnaire contient la clé @code{"id"} et peut aussi contenir d'autres clés pour préciser chaque options relative au filtre déclaré. Les ID valides des filtres sont définies comme suit :


@itemize *

@item 
Filtres de compression :


@itemize *

@item 
@code{FILTER_LZMA1} (à utiliser avec @code{FORMAT_ALONE})

@item 
@code{FILTER_LZMA2} (à utiliser avec @code{FORMAT_XZ} et @code{FORMAT_RAW})
@end itemize

@item 
Filtre Delta :


@itemize *

@item 
@code{FILTER_DELTA}
@end itemize

@item 
Filtres Branch-Call-Jump (BCJ) :


@itemize *

@item 
@code{FILTER_X86}

@item 
@code{FILTER_IA64}

@item 
@code{FILTER_ARM}

@item 
@code{FILTER_ARMTHUMB}

@item 
@code{FILTER_POWERPC}

@item 
@code{FILTER_SPARC}
@end itemize
@end itemize

Une chaîne de filtres peut contenir jusqu'à 4 filtres, et ne peut pas être vide. Le dernier filtre de cette chaîne devra être un filtre de compression, et tous les autres doivent être des filtres delta ou BCJ.

Les filtres de compression contiennent les options suivantes (définies comme entrées additionnelles dans le dictionnaire qui représente le filtre) :


@itemize *

@item 
@code{preset}: Un pré-réglage à exploiter comme une source de valeurs par défaut pour les options qui ne sont pas explicitement définies.

@item 
@code{dict_size}: La taille du dictionnaire en octets. Comprise entre 4 Ko et 1.5 Go (inclus).

@item 
@code{lc}: Nombre de bits dans le contexte littéral.

@item 
@code{lp}: Nombre de bits dans la position littérale. La somme @code{lc + lp} devra être au moins 4.

@item 
@code{pb}: Nombre de bits à cette position ; au moins 4.

@item 
@code{mode}: @code{MODE_FAST} ou @code{MODE_NORMAL}.

@item 
@code{nice_len}: Ce qui devra être pris en compte comme "longueur appréciable" pour une recherche. Il devra être 273 ou moins.

@item 
@code{mf}: Quel type d'index de recherche à utiliser -- @code{MF_HC3}, @code{MF_HC4}, @code{MF_BT2}, @code{MF_BT3}, ou @code{MF_BT4}.

@item 
@code{depth}: Profondeur maximum de la recherche, utilisée par l'index de recherche. 0 (défaut) signifie une sélection automatique basée sur des options de filtres différents.
@end itemize

Le filtre delta stocke les différences entre octets, induisant davantage d'entrées répétitives pour le compresseur, selon les circonstances. Il support une option, @code{dist}. Ce paramètre définit la distance entre les octets à soustraire. Par défaut : 1, soit la différence entre des octets adjacents.

Les filtres BCJ sont conçus pour être appliqués sur du langage machine. Ils convertissent les branches relatives, les appels et les sauts dans le code à des fins d'adressage strict, dans le but d'augmenter la redondance mise en jeu par le compresseur. Ils ne supportent qu'une seule option : @code{start_offset}, pour définir l'adresse où sera déclenché le début de la donnée d'entrée. Par défaut : 0.

@node Exemples<8>,,Préciser des chaînes de filtre personnalisées,lzma --- Compression using the LZMA algorithm
@anchor{library/lzma examples}@anchor{2920}
@subsubsection Exemples


Lire un fichier compressé :

@example
import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()
@end example

Créer un fichier compressé :

@example
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
    f.write(data)
@end example

Compresser des données en mémoire :

@example
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
@end example

Compression incrémentale :

@example
import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])
@end example

Écrire des données compressées dans un fichier préalablement ouvert :

@example
import lzma
with open("file.xz", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with lzma.open(f, "w") as lzf:
        lzf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")
@end example

Créer un fichier compressé en utilisant une chaîne de filtre personnalisée :

@example
import lzma
my_filters = [
    @{"id": lzma.FILTER_DELTA, "dist": 5@},
    @{"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME@},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
    f.write(b"blah blah blah")
@end example

@node zipfile --- Work with ZIP archives,tarfile --- Read and write tar archive files,lzma --- Compression using the LZMA algorithm,Compression de donnée et archivage
@anchor{library/zipfile doc}@anchor{2921}@anchor{library/zipfile module-zipfile}@anchor{130}@anchor{library/zipfile zipfile-work-with-zip-archives}@anchor{2922}
@subsection @code{zipfile} --- Work with ZIP archives


@geindex module; zipfile

`Source code:' Lib/zipfile/@footnote{https://github.com/python/cpython/tree/3.13/Lib/zipfile/}


__________________________________________________________________


Le format de fichier ZIP est une archive et un standard de compression couramment utilisés. Ce module fournit des outils pour créer, écrire, ajouter des données à et lister un fichier ZIP. L'utilisation avancée de ce module requiert une certaine compréhension du format, comme défini dans PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}.

Ce module ne gère pas pour l'instant les fichiers ZIP multi-disque. Il gère les fichiers ZIP qui utilisent les extensions ZIP64 (c'est-à-dire des fichiers d'une taille supérieure à 4 Go). Il gère le chiffrement d'archives ZIP chiffrées, mais il ne peut pas pour l'instant créer de fichier chiffré. Le déchiffrement est extrêmement lent car il est implémenté uniquement en Python plutôt qu'en C.

Le module définit les éléments suivants :

@geindex BadZipFile
@anchor{library/zipfile zipfile BadZipFile}@anchor{176c}
@deffn {Exception} zipfile.BadZipFile

Erreur levée en cas de fichier ZIP non valide.


Ajouté dans la version 3.2.

@end deffn

@geindex BadZipfile
@anchor{library/zipfile zipfile BadZipfile}@anchor{2923}
@deffn {Exception} zipfile.BadZipfile

Alias de @ref{176c,,BadZipFile}, pour la compatibilité avec les versions de Python précédentes.


Obsolète depuis la version 3.2.

@end deffn

@geindex LargeZipFile
@anchor{library/zipfile zipfile LargeZipFile}@anchor{2924}
@deffn {Exception} zipfile.LargeZipFile

Erreur levée quand un fichier ZIP nécessite la fonctionnalité ZIP64 mais qu'elle n'a pas été activée.
@end deffn


@deffn {Classe} zipfile.ZipFile

Classe pour lire et écrire des fichiers ZIP. Voir la section @ref{2925,,Objets ZipFile} pour les détails du constructeur.
@end deffn


@deffn {Classe} zipfile.Path

Class that implements a subset of the interface provided by
@ref{226,,pathlib.Path}, including the full
@ref{1f0,,importlib.resources.abc.Traversable} interface.


Ajouté dans la version 3.8.

@end deffn


@deffn {Classe} zipfile.PyZipFile

Classe pour créer des archives ZIP contenant des bibliothèques Python.
@end deffn

@geindex ZipInfo (classe dans zipfile)
@anchor{library/zipfile zipfile ZipInfo}@anchor{cf8}
@deffn {Classe} zipfile.ZipInfo (filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

Classe utilisée pour représenter les informations d'un membre d'une archive. Les instances de cette classe sont retournées par les méthodes  @ref{2926,,getinfo()} et @ref{2927,,infolist()} des objets @ref{6af,,ZipFile}. La plupart des utilisateurs du module @ref{130,,zipfile} n'ont pas besoin de créer ces instances mais d'utiliser celles créées par ce module. `filename' doit être le nom complet du membre de l'archive et `date_time' doit être un sextuplet  décrivant la date de dernière modification du fichier ; les champs sont décrits dans la section @ref{2928,,Objets ZipInfo}.


Modifié dans la version 3.13: A public @code{compress_level} attribute has been added to expose the
formerly protected @code{_compresslevel}.  The older protected name
continues to work as a property for backwards compatibility.

@end deffn

@geindex is_zipfile() (dans le module zipfile)
@anchor{library/zipfile zipfile is_zipfile}@anchor{1308}
@deffn {Fonction} zipfile.is_zipfile (filename)

Retourne @code{True} si `filename' est un fichier ZIP valide basé sur son nombre magique, sinon retourne @code{False}. `filename' peut aussi être un fichier ou un objet fichier-compatible.


Modifié dans la version 3.1: Gestion des objets fichier et fichier-compatibles.

@end deffn

@geindex ZIP_STORED (dans le module zipfile)
@anchor{library/zipfile zipfile ZIP_STORED}@anchor{2929}
@deffn {Données} zipfile.ZIP_STORED

Constante numérique pour un membre d'une archive décompressée.
@end deffn

@geindex ZIP_DEFLATED (dans le module zipfile)
@anchor{library/zipfile zipfile ZIP_DEFLATED}@anchor{292a}
@deffn {Données} zipfile.ZIP_DEFLATED

Constante numérique pour la méthode habituelle de compression de ZIP. Nécessite le module @ref{132,,zlib}.
@end deffn

@geindex ZIP_BZIP2 (dans le module zipfile)
@anchor{library/zipfile zipfile ZIP_BZIP2}@anchor{292b}
@deffn {Données} zipfile.ZIP_BZIP2

Constante numérique pour la méthode de compressions BZIP2. Nécessite le module @ref{13,,bz2}.


Ajouté dans la version 3.3.

@end deffn

@geindex ZIP_LZMA (dans le module zipfile)
@anchor{library/zipfile zipfile ZIP_LZMA}@anchor{292c}
@deffn {Données} zipfile.ZIP_LZMA

Constante numérique pour la méthode de compressions LZMA. Nécessite le module @ref{89,,lzma}.


Ajouté dans la version 3.3.


@cartouche
@quotation Note 
La spécification du format de fichier ZIP inclut la gestion de la compression BZIP2 depuis 2001 et LZMA depuis 2006. Néanmoins, certains outils (comme certaines versions de Python) ne gèrent pas ces méthodes de compression et peuvent soit totalement refuser de traiter le fichier ZIP soit ne pas extraire certains fichiers.
@end quotation
@end cartouche
@end deffn


@subsubheading Voir aussi



@table @asis

@item PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}

Documentation sur le format de fichier ZIP par Phil Katz, créateur du format et des algorithmes utilisés.

@item Info-ZIP Home Page@footnote{https://infozip.sourceforge.net/}

Informations sur les programmes et les bibliothèques de développement d'archivage ZIP du projet Info-ZIP.
@end table


@menu
* Objets ZipFile:: 
* Objets Path:: 
* Objets PyZipFile:: 
* Objets ZipInfo:: 
* Interface en ligne de commande: Interface en ligne de commande<2>. 
* Problèmes de décompression:: 

@end menu

@node Objets ZipFile,Objets Path,,zipfile --- Work with ZIP archives
@anchor{library/zipfile id1}@anchor{292d}@anchor{library/zipfile zipfile-objects}@anchor{2925}
@subsubsection Objets ZipFile


@geindex ZipFile (classe dans zipfile)
@anchor{library/zipfile zipfile ZipFile}@anchor{6af}
@deffn {Classe} zipfile.ZipFile (file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

Ouvre un fichier ZIP, où `file' peut être un chemin vers un fichier (une chaîne de caractères), un objet fichier-compatible ou un objet chemin-compatible @ref{29d,,path-like object}.

Le paramètre `mode' doit être @code{r} pour lire un fichier existant, @code{w} pour tronquer et écrire un nouveau fichier, @code{a} pour ajouter des données à la fin d'un fichier existant ou @code{x} pour créer et écrire exclusivement un nouveau fichier. Si `mode' est à @code{x} et `file' fait référence à un fichier existant, une exception @ref{1009,,FileExistsError} est levée. Si `mode' est à @code{a} et `file' fait référence à un fichier ZIP existant, alors des fichiers supplémentaires y seront ajoutés. Si `file' ne fait pas référence à un fichier ZIP, alors une nouvelle archive ZIP est ajoutée au fichier, afin de prévoir le cas d'ajouter une archive ZIP à un autre fichier (comme par exemple @code{python.exe}). Si `mode' est à @code{r} ou @code{a}, le fichier doit être navigable.

Le paramètre `compression' est la méthode de compression ZIP à utiliser lors de l'écriture de l'archive et doit être défini à @ref{2929,,ZIP_STORED}, @ref{292a,,ZIP_DEFLATED}, @ref{292b,,ZIP_BZIP2} ou @ref{292c,,ZIP_LZMA} ; les valeurs non reconnues lèveront une exception @ref{225,,NotImplementedError}. Si @ref{292a,,ZIP_DEFLATED}, @ref{292b,,ZIP_BZIP2} ou @ref{292c,,ZIP_LZMA} est spécifié mais le module correspondant (@ref{132,,zlib}, @ref{13,,bz2} ou @ref{89,,lzma}) n'est pas disponible, une exception @ref{193,,RuntimeError} est levée. Est défini par défaut à @ref{2929,,ZIP_STORED}.

Si `allowZip64' est à @code{True} (par défaut), `zipfile' crée des fichiers ZIP utilisant les extensions ZIP64 quand le fichier ZIP est plus grand que 4 Go. S'il est à @code{False}, @ref{130,,zipfile} lève une exception quand le fichier ZIP nécessiterait les extensions ZIP64.

Le paramètre `compresslevel' contrôle le niveau de compression à utiliser lors de l'écriture des fichiers dans l'archive. Avec @ref{2929,,ZIP_STORED} ou @ref{292c,,ZIP_LZMA}, cela est sans effet. Avec @ref{292a,,ZIP_DEFLATED} les entiers de @code{0} à @code{9} sont acceptés (voir @ref{28d5,,zlib} pour plus d'informations). Avec @ref{292b,,ZIP_BZIP2} les entiers de @code{1} à @code{9} sont acceptés (voir @ref{851,,bz2} pour plus d'informations).

Les fichiers ZIP plus anciens que le 1er janvier 1980 sont autorisés lorsque l'argument `strict_timestamps' vaut @code{False}, moyennant de les voir datés du 1er janvier 1980. De même pour les fichiers datés d'après le 31 décembre 2107 qui voient leur horodatage fixé au 31 décembre 2107.

When mode is @code{'r'}, `metadata_encoding' may be set to the name of a codec,
which will be used to decode metadata such as the names of members and ZIP
comments.

Si le fichier est créé avec le mode @code{'w'}, @code{'x'} ou @code{'a'} et ensuite @ref{292e,,fermé} sans ajouter de fichiers à l'archive, la structure appropriée pour un fichier archive ZIP vide sera écrite dans le fichier.

`ZipFile' est aussi un gestionnaire de contexte et gère ainsi la déclaration @ref{5bc,,with}. Dans l'exemple, `myzip' est fermé à la fin de la déclaration @code{with} --- même si une exception est levée :

@example
with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')
@end example

@cartouche
@quotation Note 
`metadata_encoding' is an instance-wide setting for the ZipFile.
It is not currently possible to set this on a per-member basis.

This attribute is a workaround for legacy implementations which produce
archives with names in the current locale encoding or code page (mostly
on Windows).  According to the .ZIP standard, the encoding of metadata
may be specified to be either IBM code page (default) or UTF-8 by a flag
in the archive header.
That flag takes precedence over `metadata_encoding', which is
a Python-specific extension.
@end quotation
@end cartouche


Modifié dans la version 3.2: Ajout de la possibilité d'utiliser @ref{6af,,ZipFile} comme un gestionnaire de contexte.



Modifié dans la version 3.3: Ajout de la gestion de la compression @ref{13,,bzip2} et @ref{89,,lzma}.



Modifié dans la version 3.4: Les extensions ZIP64 sont activées par défaut.



Modifié dans la version 3.5: Ajout de la gestion de l'écriture dans des flux non navigables. Ajout de la gestion du mode @code{x}.



Modifié dans la version 3.6: Auparavant, une simple exception @ref{193,,RuntimeError} était levée pour des valeurs de compression non reconnues.



Modifié dans la version 3.6.2: Le paramètre `file' accepte un objet fichier-compatible @ref{29d,,path-like object}.



Modifié dans la version 3.7: Ajout du paramètre `compresslevel'.



Modifié dans la version 3.8: The `strict_timestamps' keyword-only parameter.



Modifié dans la version 3.11: Added support for specifying member name encoding for reading
metadata in the zipfile's directory and file headers.

@end deffn

@geindex close() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile close}@anchor{292e}
@deffn {Méthode} ZipFile.close ()

Ferme l'archive. Vous devez appeler @ref{292e,,close()} avant de terminer votre programme ou des informations essentielles n'y seront pas enregistrées.
@end deffn

@geindex getinfo() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile getinfo}@anchor{2926}
@deffn {Méthode} ZipFile.getinfo (name)

Retourne un objet @ref{cf8,,ZipInfo} avec les informations du membre `name' de l'archive. Appeler @ref{2926,,getinfo()} pour un nom non contenu dans l'archive lève une exception @ref{33a,,KeyError}.
@end deffn

@geindex infolist() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile infolist}@anchor{2927}
@deffn {Méthode} ZipFile.infolist ()

Retourne une liste contenant un objet @ref{cf8,,ZipInfo} pour chaque membre de l'archive. Les objets ont le même ordre que leurs entrées dans le fichier ZIP présent sur disque s'il s'agissait d'une archive préexistante.
@end deffn

@geindex namelist() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile namelist}@anchor{292f}
@deffn {Méthode} ZipFile.namelist ()

Retourne une liste des membres de l'archive indexés par leur nom.
@end deffn

@geindex open() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile open}@anchor{411}
@deffn {Méthode} ZipFile.open (name, mode='r', pwd=None, *, force_zip64=False)

Access a member of the archive as a binary file-like object.  `name'
can be either the name of a file within the archive or a @ref{cf8,,ZipInfo}
object.  The `mode' parameter, if included, must be @code{'r'} (the default)
or @code{'w'}.  `pwd' is the password used to decrypt encrypted ZIP files as a
@ref{1bd,,bytes} object.

@ref{411,,open()} est aussi un gestionnaire de contexte et gère ainsi la déclaration @ref{5bc,,with} :

@example
with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())
@end example

With `mode' @code{'r'} the file-like object
(@code{ZipExtFile}) is read-only and provides the following methods:
@ref{1306,,read()}, @ref{1307,,readline()},
@ref{22ba,,readlines()}, @ref{126a,,seek()},
@ref{2930,,tell()}, @ref{1c4e,,__iter__()}, @ref{12ab,,__next__()}.
These objects can operate independently of the ZipFile.

Avec @code{mode='w'} un descripteur de fichier en écriture est retourné, gérant la méthode @ref{cc9,,write()}. Quand le descripteur d'un fichier inscriptible est ouvert, tenter de lire ou écrire d'autres fichiers dans le fichier ZIP lève une exception @ref{1ff,,ValueError}.

In both cases the file-like object has also attributes @code{name},
which is equivalent to the name of a file within the archive, and
@code{mode}, which is @code{'rb'} or @code{'wb'} depending on the input mode.

Lors de l'écriture d'un fichier, si la taille du fichier n'est pas connue mais peut être supérieure à 2 GiO, spécifiez @code{force_zip64=True} afin de vous assurer que le format d'en-tête est capable de supporter des fichiers volumineux. Si la taille du fichier est connue à l'avance, instanciez un objet @ref{cf8,,ZipInfo} avec l'attribut @ref{2931,,file_size} défini et utilisez-le en tant que paramètre `name'.

@cartouche
@quotation Note 
Les méthodes @ref{411,,open()}, @ref{2932,,read()} et @ref{2933,,extract()} peuvent prendre un nom de fichier ou un objet @ref{cf8,,ZipInfo}. Cela est appréciable lorsqu'on essaie de lire un fichier ZIP qui contient des membres avec des noms en double.
@end quotation
@end cartouche


Modifié dans la version 3.6: Suppression de la gestion de @code{mode='U'}.  Utilisez @ref{7a5,,io.TextIOWrapper} pour lire des fichiers texte compressés en mode @ref{d28,,universal newlines}.



Modifié dans la version 3.6: @ref{411,,ZipFile.open()} can now be used to write files into the archive with the
@code{mode='w'} option.



Modifié dans la version 3.6: Appeler @ref{411,,open()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.



Modifié dans la version 3.13: Added attributes @code{name} and @code{mode} for the writeable
file-like object.
The value of the @code{mode} attribute for the readable file-like
object was changed from @code{'r'} to @code{'rb'}.

@end deffn

@geindex extract() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile extract}@anchor{2933}
@deffn {Méthode} ZipFile.extract (member, path=None, pwd=None)

Extract a member from the archive to the current working directory; `member'
must be its full name or a @ref{cf8,,ZipInfo} object.  Its file information is
extracted as accurately as possible.  `path' specifies a different directory
to extract to.  `member' can be a filename or a @ref{cf8,,ZipInfo} object.
`pwd' is the password used for encrypted files as a @ref{1bd,,bytes} object.

Retourne le chemin normalisé créé (un dossier ou un nouveau fichier).

@cartouche
@quotation Note 
Si le nom de fichier d'un membre est un chemin absolu, le disque/partage UNC et les (anti)slashes de départ seront supprimés, par exemple @code{///foo/bar} devient @code{foo/bar} sous Unix et @code{C:\foo\bar} devient @code{foo\bar} sous Windows. Et tous les composants @code{".."} dans le nom de fichier d'un membre seront supprimés, par exemple @code{../../foo../../ba..r} devient @code{foo../ba..r}. Sous Windows les caractères illégaux (@code{:}, @code{<}, @code{>}, @code{|}, @code{"}, @code{?} et @code{*}) sont remplacés par un `underscore' (@code{_}).
@end quotation
@end cartouche


Modifié dans la version 3.6: Appeler @ref{2933,,extract()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.



Modifié dans la version 3.6.2: Le paramètre `path' accepte un objet chemin-compatible @ref{29d,,path-like object}.

@end deffn

@geindex extractall() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile extractall}@anchor{2934}
@deffn {Méthode} ZipFile.extractall (path=None, members=None, pwd=None)

Extract all members from the archive to the current working directory.  `path'
specifies a different directory to extract to.  `members' is optional and must
be a subset of the list returned by @ref{292f,,namelist()}.  `pwd' is the password
used for encrypted files as a @ref{1bd,,bytes} object.

@cartouche
@quotation Avertissement 
N'extrayez jamais d'archives depuis des sources non fiables sans inspection préalable. Il est possible que des fichiers soient créés en dehors de `path', par exemple des membres qui ont des chemins de fichier absolus commençant par @code{"/"} ou des noms de fichier avec deux points @code{".."}.  Ce module essaie de prévenir ceci. Voir la note de @ref{2933,,extract()}.
@end quotation
@end cartouche


Modifié dans la version 3.6: Appeler @ref{2934,,extractall()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.



Modifié dans la version 3.6.2: Le paramètre `path' accepte un objet chemin-compatible @ref{29d,,path-like object}.

@end deffn

@geindex printdir() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile printdir}@anchor{2935}
@deffn {Méthode} ZipFile.printdir ()

Affiche la liste des contenus de l'archive sur @code{sys.stdout}.
@end deffn

@geindex setpassword() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile setpassword}@anchor{2936}
@deffn {Méthode} ZipFile.setpassword (pwd)

Set `pwd' (a @ref{1bd,,bytes} object) as default password to extract encrypted files.
@end deffn

@geindex read() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile read}@anchor{2932}
@deffn {Méthode} ZipFile.read (name, pwd=None)

Return the bytes of the file `name' in the archive.  `name' is the name of the
file in the archive, or a @ref{cf8,,ZipInfo} object.  The archive must be open for
read or append. `pwd' is the password used for encrypted files as a @ref{1bd,,bytes}
object and, if specified, overrides the default password set with @ref{2936,,setpassword()}.
Calling @ref{2932,,read()} on a ZipFile that uses a compression method other than
@ref{2929,,ZIP_STORED}, @ref{292a,,ZIP_DEFLATED}, @ref{292b,,ZIP_BZIP2} or
@ref{292c,,ZIP_LZMA} will raise a @ref{225,,NotImplementedError}. An error will also
be raised if the corresponding compression module is not available.


Modifié dans la version 3.6: Appeler @ref{2932,,read()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.

@end deffn

@geindex testzip() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile testzip}@anchor{2937}
@deffn {Méthode} ZipFile.testzip ()

Lit tous les fichiers de l'archive et vérifie leurs sommes CRC et leurs en-têtes. Retourne le nom du premier fichier mauvais ou retourne @code{None} sinon.


Modifié dans la version 3.6: Appeler @ref{2937,,testzip()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.

@end deffn

@geindex write() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile write}@anchor{d3a}
@deffn {Méthode} ZipFile.write (filename, arcname=None, compress_type=None, compresslevel=None)

Écrit le fichier nommé `filename' dans l'archive, lui donnant `arcname' comme nom dans l'archive (par défaut, `arcname' prend la même valeur que `filename' mais sans lettre de disque et séparateur de chemin en première position). Si donné, `compress_type' écrase la valeur donnée pour le paramètre `compression' au constructeur pour la nouvelle entrée. De la même manière, `compression' écrase le constructeur si donné. L'archive doit être ouverte avec le mode @code{'w'}, @code{'x'} ou @code{'a'}.

@cartouche
@quotation Note 
The ZIP file standard historically did not specify a metadata encoding,
but strongly recommended CP437 (the original IBM PC encoding) for
interoperability.  Recent versions allow use of UTF-8 (only).  In this
module, UTF-8 will automatically be used to write the member names if
they contain any non-ASCII characters.  It is not possible to write
member names in any encoding other than ASCII or UTF-8.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Les noms d'archive doivent être relatifs à la racine de l'archive, c'est-à-dire qu'ils ne doivent pas commencer par un séparateur de chemin.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Si @code{arcname} (ou @code{filename} si @code{arcname} n'est pas donné) contient un octet nul, le nom du fichier dans l'archive sera tronqué à l'octet nul.
@end quotation
@end cartouche

@cartouche
@quotation Note 
A leading slash in the filename may lead to the archive being impossible to
open in some zip programs on Windows systems.
@end quotation
@end cartouche


Modifié dans la version 3.6: Appeler @ref{d3a,,write()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.

@end deffn

@geindex writestr() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile writestr}@anchor{1309}
@deffn {Méthode} ZipFile.writestr (zinfo_or_arcname, data, compress_type=None, compresslevel=None)

Écrit un fichier dans l'archive. Le contenu est `data', qui peut être soit une instance de @ref{435,,str} ou une instance de @ref{1bd,,bytes} ; s'il s'agit d'une @ref{435,,str}, il est encodé en UTF-8 au préalable. `zinfo_or_arcname' est soit le nom de fichier qu'il sera donné dans l'archive, soit une instance de @ref{cf8,,ZipInfo}. Si c'est une instance, au moins le nom de fichier, la date et l'heure doivent être donnés. S'il s'agit d'un nom, la date et l'heure sont définies sur la date et l'heure actuelles. L'archive doit être ouverte avec le mode @code{'w'}, @code{'x'} ou @code{'a'}.

Si donné, `compress_type' écrase la valeur donnée pour le paramètre `compression' au constructeur de la nouvelle entrée ou dans le paramètre `zinfo_or_arcname' (si c'est une instance de @ref{cf8,,ZipInfo}). De la même manière, `compresslevel' le constructeur si donné.

@cartouche
@quotation Note 
Lorsque l'on passe une instance de @ref{cf8,,ZipInfo} dans le paramètre `zinfo_or_arcname', la méthode de compression utilisée sera celle spécifiée dans le membre `compress_type' de l'instance @ref{cf8,,ZipInfo} donnée. Par défaut, le constructeur de la classe @ref{cf8,,ZipInfo} définit ce membre à @ref{2929,,ZIP_STORED}.
@end quotation
@end cartouche


Modifié dans la version 3.2: L'argument `compress_type'.



Modifié dans la version 3.6: Appeler @ref{1309,,writestr()} sur un fichier ZipFile fermé lève une erreur @ref{1ff,,ValueError}. Précédemment, une erreur @ref{193,,RuntimeError} était levée.

@end deffn

@geindex mkdir() (méthode zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile mkdir}@anchor{6b0}
@deffn {Méthode} ZipFile.mkdir (zinfo_or_directory, mode=511)

Create a directory inside the archive.  If `zinfo_or_directory' is a string,
a directory is created inside the archive with the mode that is specified in
the `mode' argument. If, however, `zinfo_or_directory' is
a @ref{cf8,,ZipInfo} instance then the `mode' argument is ignored.

The archive must be opened with mode @code{'w'}, @code{'x'} or @code{'a'}.


Ajouté dans la version 3.11.

@end deffn

Les attributs suivants sont aussi disponibles :

@geindex filename (attribut zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile filename}@anchor{2938}
@deffn {Attribut} ZipFile.filename

Nom du fichier ZIP.
@end deffn

@geindex debug (attribut zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile debug}@anchor{2939}
@deffn {Attribut} ZipFile.debug

Le niveau d'affichage de `debug' à utiliser. Peut être défini de @code{0} (par défaut, pas d'affichage) à @code{3} (affichage le plus bavard). Les informations de débogage sont affichées sur @code{sys.stdout}.
@end deffn

@geindex comment (attribut zipfile.ZipFile)
@anchor{library/zipfile zipfile ZipFile comment}@anchor{293a}
@deffn {Attribut} ZipFile.comment

Le commentaire associé au fichier ZIP en tant qu'objet @ref{1bd,,bytes}. Si vous affectez un commentaire à une instance de @ref{6af,,ZipFile} créée avec le mode @code{'w'}, @code{'x'} ou @code{'a'}, il ne doit pas dépasser 65535 octets. Les commentaires plus longs que cette taille seront tronqués.
@end deffn

@node Objets Path,Objets PyZipFile,Objets ZipFile,zipfile --- Work with ZIP archives
@anchor{library/zipfile id2}@anchor{293b}@anchor{library/zipfile path-objects}@anchor{293c}
@subsubsection Objets `Path'


@geindex Path (classe dans zipfile)
@anchor{library/zipfile zipfile Path}@anchor{6b4}
@deffn {Classe} zipfile.Path (root, at='@w{'})

Construit un objet `Path' depuis le fichier ZIP `root' (qui peut être une instance de @ref{6af,,ZipFile} ou tout ce qui sera accepté par le paramètre `file' du constructeur de @ref{6af,,ZipFile}).

@code{at} indique la position de ce `Path' dans l'archive ZIP, par exemple @code{"dir/file.txt"}, @code{"dir/"}, ou @code{""}. Par défaut c'est une chaine vide, indiquant la racine de l'archive.
@end deffn

Les objets @code{Path} de @code{zipfile} exposent les fonctionnalités suivantes des objets de @ref{226,,pathlib.Path} :

Path objects are traversable using the @code{/} operator or @code{joinpath}.

@geindex name (attribut zipfile.Path)
@anchor{library/zipfile zipfile Path name}@anchor{293d}
@deffn {Attribut} Path.name

Le dernier segment du chemin.
@end deffn

@geindex open() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path open}@anchor{151f}
@deffn {Méthode} Path.open (mode='r', *, pwd, **)

Appelle @ref{411,,ZipFile.open()} sur ce chemin. Il est possible d'ouvrir en lecture ou en écriture, au format texte ou binaire, via les modes @code{'r'}, @code{'w'}, @code{'rb'} et @code{'wb'}. Les arguments positionnels et nommés sont passés à la classe @ref{7a5,,io.TextIOWrapper} lors d'une ouverture au format texte, ils sont ignorés autrement. @code{pwd} est le paramètre @code{pwd} de @ref{411,,ZipFile.open()}.


Modifié dans la version 3.9: prise en charge des modes texte et binaire pour @code{open}. Le mode texte est maintenant le mode par défaut.



Modifié dans la version 3.11.2: The @code{encoding} parameter can be supplied as a positional argument
without causing a @ref{522,,TypeError}. As it could in 3.9. Code needing to
be compatible with unpatched 3.10 and 3.11 versions must pass all
@ref{7a5,,io.TextIOWrapper} arguments, @code{encoding} included, as keywords.

@end deffn

@geindex iterdir() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path iterdir}@anchor{293e}
@deffn {Méthode} Path.iterdir ()

Énumère le contenu du dossier actuel.
@end deffn

@geindex is_dir() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path is_dir}@anchor{293f}
@deffn {Méthode} Path.is_dir ()

Renvoie @code{True} si ce chemin pointe sur un dossier.
@end deffn

@geindex is_file() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path is_file}@anchor{2940}
@deffn {Méthode} Path.is_file ()

Renvoie @code{True} si ce chemin pointe sur un fichier.
@end deffn

@geindex is_symlink() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path is_symlink}@anchor{2941}
@deffn {Méthode} Path.is_symlink ()

Return @code{True} if the current context references a symbolic link.


Ajouté dans la version 3.12.



Modifié dans la version 3.13: Previously, @code{is_symlink} would unconditionally return @code{False}.

@end deffn

@geindex exists() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path exists}@anchor{2942}
@deffn {Méthode} Path.exists ()

Renvoie @code{True} si le chemin pointe sur un fichier ou un dossier de l'archive ZIP
@end deffn

@geindex Path.suffix (dans le module zipfile)
@anchor{library/zipfile zipfile Path suffix}@anchor{6b2}
@deffn {Données} Path.suffix

The last dot-separated portion of the final component, if any.
This is commonly called the file extension.


Ajouté dans la version 3.11: Added @ref{6b2,,Path.suffix} property.

@end deffn

@geindex Path.stem (dans le module zipfile)
@anchor{library/zipfile zipfile Path stem}@anchor{6b1}
@deffn {Données} Path.stem

The final path component, without its suffix.


Ajouté dans la version 3.11: Added @ref{6b1,,Path.stem} property.

@end deffn

@geindex Path.suffixes (dans le module zipfile)
@anchor{library/zipfile zipfile Path suffixes}@anchor{6b3}
@deffn {Données} Path.suffixes

A list of the path’s suffixes, commonly called file extensions.


Ajouté dans la version 3.11: Added @ref{6b3,,Path.suffixes} property.

@end deffn

@geindex read_text() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path read_text}@anchor{16fc}
@deffn {Méthode} Path.read_text (*, **)

Lit le fichier au format texte. Les arguments positionnels et nommés sont passés à @ref{7a5,,io.TextIOWrapper} (sauf @code{buffer}, qui est imposé par le contexte)


Modifié dans la version 3.11.2: The @code{encoding} parameter can be supplied as a positional argument
without causing a @ref{522,,TypeError}. As it could in 3.9. Code needing to
be compatible with unpatched 3.10 and 3.11 versions must pass all
@ref{7a5,,io.TextIOWrapper} arguments, @code{encoding} included, as keywords.

@end deffn

@geindex read_bytes() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path read_bytes}@anchor{2943}
@deffn {Méthode} Path.read_bytes ()

Lit le fichier en mode binaire, renvoyant un objet `bytes'.
@end deffn

@geindex joinpath() (méthode zipfile.Path)
@anchor{library/zipfile zipfile Path joinpath}@anchor{2944}
@deffn {Méthode} Path.joinpath (*other)

Return a new Path object with each of the `other' arguments
joined. The following are equivalent:

@example
>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'
@end example


Modifié dans la version 3.10: Prior to 3.10, @code{joinpath} was undocumented and accepted
exactly one parameter.

@end deffn

The zipp@footnote{https://pypi.org/project/zipp/} project provides backports
of the latest path object functionality to older Pythons. Use
@code{zipp.Path} in place of @code{zipfile.Path} for early access to
changes.

@node Objets PyZipFile,Objets ZipInfo,Objets Path,zipfile --- Work with ZIP archives
@anchor{library/zipfile id3}@anchor{2945}@anchor{library/zipfile pyzipfile-objects}@anchor{2946}
@subsubsection Objets `PyZipFile'


Le constructeur de @ref{fe3,,PyZipFile} prend les mêmes paramètres que le constructeur de @ref{6af,,ZipFile} avec un paramètre additionnel `optimize'.

@geindex PyZipFile (classe dans zipfile)
@anchor{library/zipfile zipfile PyZipFile}@anchor{fe3}
@deffn {Classe} zipfile.PyZipFile (file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)


Modifié dans la version 3.2: Added the `optimize' parameter.



Modifié dans la version 3.4: Les extensions ZIP64 sont activées par défaut.


Les instances ont une méthode supplémentaire par rapport aux objets @ref{6af,,ZipFile} :

@geindex writepy() (méthode zipfile.PyZipFile)
@anchor{library/zipfile zipfile PyZipFile writepy}@anchor{fe2}
@deffn {Méthode} writepy (pathname, basename='@w{'}, filterfunc=None)

Cherche les fichiers @code{*.py} et ajoute le fichier correspondant à l'archive.

Si le paramètre `optimize' du constructeur de @ref{fe3,,PyZipFile} n'a pas été donné ou est à @code{-1}, le fichier correspondant est un fichier @code{*.pyc}, à compiler si nécessaire.

Si le paramètre `optimize' du constructeur de @ref{fe3,,PyZipFile} est à @code{0}, @code{1} ou @code{2}, ne sont ajoutés dans l'archive que les fichiers avec ce niveau d'optimisation (voir @ref{190,,compile()}), à compiler si nécessaire.

Si `pathname' est un fichier, le chemin de fichier doit terminer par  @code{.py} et uniquement le fichier (@code{*.pyc} correspondant) est ajouté au niveau le plus haut (sans information de chemin). Si `pathname' est un fichier ne terminant pas par @code{.py}, une exception @ref{193,,RuntimeError} est levée. Si c'est un répertoire et que le répertoire n'est pas un répertoire de paquet, alors tous les fichiers  @code{*.pyc} sont ajoutés à la racine. Si le répertoire est un répertoire de paquet, alors tous les @code{*.pyc} sont ajoutés sous le nom du paquet en tant que chemin, et s'il y a des sous-répertoires qui sont des répertoires de paquet, ils sont tous ajoutés récursivement dans un ordre trié.

`basename' n'est sensé être utilisé qu'en interne.

`filterfunc', si donné, doit être une fonction prenant une seule chaîne de caractères en argument. Il lui sera passé chaque chemin (incluant chaque chemin de fichier complet individuel) avant d'être ajouté à l'archive. Si `filterfunc' retourne une valeur fausse, le chemin n'est pas ajouté et si c'est un répertoire son contenu est ignoré. Par exemple, si nos fichiers de test sont tous soit dans des répertoires @code{test} ou commencent par @code{test_}, nous pouvons utiliser une fonction `filterfunc' pour les exclure :

@example
>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
...
>>> zf.writepy('myprog', filterfunc=notests)
@end example

La méthode @ref{fe2,,writepy()} crée des archives avec des noms de fichier comme suit :

@example
string.pyc                   # Top level name
test/__init__.pyc            # Package directory
test/testall.pyc             # Module test.testall
test/bogus/__init__.pyc      # Subpackage directory
test/bogus/myfile.pyc        # Submodule test.bogus.myfile
@end example


Modifié dans la version 3.4: Added the `filterfunc' parameter.



Modifié dans la version 3.6.2: Le paramètre `pathname' accepte un objet chemin-compatible @ref{29d,,path-like object}.



Modifié dans la version 3.7: La récursion trie les entrées de dossier.

@end deffn
@end deffn

@node Objets ZipInfo,Interface en ligne de commande<2>,Objets PyZipFile,zipfile --- Work with ZIP archives
@anchor{library/zipfile id4}@anchor{2947}@anchor{library/zipfile zipinfo-objects}@anchor{2928}
@subsubsection Objets `ZipInfo'


Des instances de la classe @ref{cf8,,ZipInfo} sont retournées par les méthodes @ref{2926,,getinfo()} et @ref{2927,,infolist()} des objets @ref{6af,,ZipFile}. Chaque objet stocke des informations sur un seul membre de l'archive ZIP.

Il y a une méthode de classe pour créer une instance de @ref{cf8,,ZipInfo} pour un fichier du système de fichiers :

@geindex from_file() (méthode de la classe zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo from_file}@anchor{cf7}
@deffn {Méthode} classmethod ZipInfo.from_file (filename, arcname=None, *, strict_timestamps=True)

Construit une instance de @ref{cf8,,ZipInfo} pour le fichier du système de fichiers, en préparation de l'ajouter à un fichier ZIP.

`filename' doit être un chemin vers un fichier ou un répertoire dans le système de fichiers.

Si `arcname' est spécifié, il est utilisé en tant que nom dans l'archive. Si `arcname' n'est pas spécifié, le nom sera le même que `filename' mais sans lettre de disque et sans séparateur de chemin en première position.

Les fichiers ZIP plus anciens que le 1er janvier 1980 sont autorisés lorsque l'argument `strict_timestamps' vaut @code{False}, moyennant de les voir datés du 1er janvier 1980. De même pour les fichiers datés d'après le 31 décembre 2107 qui voient leur horodatage fixé au 31 décembre 2107.


Ajouté dans la version 3.6.



Modifié dans la version 3.6.2: Le paramètre  `filename' accepte un objet chemin-compatible @ref{29d,,path-like object}.



Modifié dans la version 3.8: Added the `strict_timestamps' keyword-only parameter.

@end deffn

Les instances ont les méthodes et attributs suivants :

@geindex is_dir() (méthode zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo is_dir}@anchor{cf9}
@deffn {Méthode} ZipInfo.is_dir ()

Retourne @code{True} si le membre d'archive est un répertoire.

Utilise le nom de l'entrée : les répertoires doivent toujours se terminer par @code{/}.


Ajouté dans la version 3.6.

@end deffn

@geindex filename (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo filename}@anchor{2948}
@deffn {Attribut} ZipInfo.filename

Nom du fichier dans l'archive.
@end deffn

@geindex date_time (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo date_time}@anchor{2949}
@deffn {Attribut} ZipInfo.date_time

Date et heure de dernière modification pour le membre de l'archive. `Tuple' de six valeurs :


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Valeur

@item

@code{0}

@tab

Année (>= 1980)

@item

@code{1}

@tab

Mois (indexé à partir de 1)

@item

@code{2}

@tab

Jour du mois (indexé à partir de 1)

@item

@code{3}

@tab

Heures (indexées à partir de 0)

@item

@code{4}

@tab

Minutes (indexées à partir de 0)

@item

@code{5}

@tab

Secondes (indexées à partir de 0)

@end multitable


@cartouche
@quotation Note 
Le format de fichier ZIP ne gère pas les horodatages avant 1980.
@end quotation
@end cartouche
@end deffn

@geindex compress_type (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo compress_type}@anchor{294a}
@deffn {Attribut} ZipInfo.compress_type

Type de compression du membre d'archive.
@end deffn

@geindex comment (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo comment}@anchor{294b}
@deffn {Attribut} ZipInfo.comment

Commentaire pour le membre d'archive individuel en tant qu'objet @ref{1bd,,bytes}.
@end deffn

@geindex extra (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo extra}@anchor{294c}
@deffn {Attribut} ZipInfo.extra

Données du champ d'extension. La documentation PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT} contient quelques commentaires sur la structure interne des données contenues dans cet objet @ref{1bd,,bytes}.
@end deffn

@geindex create_system (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo create_system}@anchor{294d}
@deffn {Attribut} ZipInfo.create_system

Système ayant créé l'archive ZIP.
@end deffn

@geindex create_version (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo create_version}@anchor{294e}
@deffn {Attribut} ZipInfo.create_version

Version de PKZIP ayant créé l'archive ZIP.
@end deffn

@geindex extract_version (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo extract_version}@anchor{294f}
@deffn {Attribut} ZipInfo.extract_version

Version de PKZIP nécessaire à l'extraction de l'archive ZIP.
@end deffn

@geindex reserved (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo reserved}@anchor{2950}
@deffn {Attribut} ZipInfo.reserved

Doit être à zéro.
@end deffn

@geindex flag_bits (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo flag_bits}@anchor{2951}
@deffn {Attribut} ZipInfo.flag_bits

Bits d'options ZIP.
@end deffn

@geindex volume (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo volume}@anchor{2952}
@deffn {Attribut} ZipInfo.volume

Numéro de volume de l'entête du fichier.
@end deffn

@geindex internal_attr (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo internal_attr}@anchor{2953}
@deffn {Attribut} ZipInfo.internal_attr

Attributs internes.
@end deffn

@geindex external_attr (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo external_attr}@anchor{2954}
@deffn {Attribut} ZipInfo.external_attr

Attributs de fichier externes.
@end deffn

@geindex header_offset (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo header_offset}@anchor{2955}
@deffn {Attribut} ZipInfo.header_offset

Longueur de l'entête du fichier en octets.
@end deffn

@geindex CRC (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo CRC}@anchor{2956}
@deffn {Attribut} ZipInfo.CRC

CRC-32 du fichier décompressé.
@end deffn

@geindex compress_size (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo compress_size}@anchor{2957}
@deffn {Attribut} ZipInfo.compress_size

Taille des données décompressées.
@end deffn

@geindex file_size (attribut zipfile.ZipInfo)
@anchor{library/zipfile zipfile ZipInfo file_size}@anchor{2931}
@deffn {Attribut} ZipInfo.file_size

Taille du fichier décompressé.
@end deffn

@node Interface en ligne de commande<2>,Problèmes de décompression,Objets ZipInfo,zipfile --- Work with ZIP archives
@anchor{library/zipfile command-line-interface}@anchor{2958}@anchor{library/zipfile zipfile-commandline}@anchor{2959}
@subsubsection Interface en ligne de commande


Le module @ref{130,,zipfile} fournit une interface en ligne de commande simple pour interagir avec des archives ZIP.

Si vous voulez créer une nouvelle archive ZIP, spécifiez son nom après l'option @ref{295a,,-c} et listez ensuite le(s) nom(s) de fichier à inclure :

@example
$ python -m zipfile -c monty.zip spam.txt eggs.txt
@end example

Passer un répertoire est aussi possible :

@example
$ python -m zipfile -c monty.zip life-of-brian_1979/
@end example

Si vous voulez extraire une archive ZIP dans un répertoire donné, utilisez l'option @ref{295b,,-e} :

@example
$ python -m zipfile -e monty.zip target-dir/
@end example

Pour une liste des fichiers dans une archive ZIP, utilisez l'option @ref{295c,,-l} :

@example
$ python -m zipfile -l monty.zip
@end example

@menu
* Options de la ligne de commande: Options de la ligne de commande<2>. 

@end menu

@node Options de la ligne de commande<2>,,,Interface en ligne de commande<2>
@anchor{library/zipfile command-line-options}@anchor{295d}
@subsubsection Options de la ligne de commande


@geindex option de ligne de commande zipfile; -l
@geindex option de ligne de commande zipfile; --list
@anchor{library/zipfile cmdoption-zipfile-l}@anchor{295c}
@deffn {Option} @w{-}l <zipfile>
@anchor{library/zipfile cmdoption-zipfile-list}@anchor{295e}
@deffnx {Option} @w{-}@w{-}list <zipfile>

Liste les fichiers dans un fichier ZIP `zipfile'.
@end deffn

@geindex option de ligne de commande zipfile; -c
@geindex option de ligne de commande zipfile; --create
@anchor{library/zipfile cmdoption-zipfile-c}@anchor{295a}
@deffn {Option} @w{-}c <zipfile> <source1> ... <sourceN>
@anchor{library/zipfile cmdoption-zipfile-create}@anchor{295f}
@deffnx {Option} @w{-}@w{-}create <zipfile> <source1> ... <sourceN>

Crée un fichier ZIP `zipfile' à partir des fichiers `source'.
@end deffn

@geindex option de ligne de commande zipfile; -e
@geindex option de ligne de commande zipfile; --extract
@anchor{library/zipfile cmdoption-zipfile-e}@anchor{295b}
@deffn {Option} @w{-}e <zipfile> <output_dir>
@anchor{library/zipfile cmdoption-zipfile-extract}@anchor{2960}
@deffnx {Option} @w{-}@w{-}extract <zipfile> <output_dir>

Extrait le fichier ZIP `zipfile' vers le répertoire cible `output_dir'.
@end deffn

@geindex option de ligne de commande zipfile; -t
@geindex option de ligne de commande zipfile; --test
@anchor{library/zipfile cmdoption-zipfile-t}@anchor{2961}
@deffn {Option} @w{-}t <zipfile>
@anchor{library/zipfile cmdoption-zipfile-test}@anchor{2962}
@deffnx {Option} @w{-}@w{-}test <zipfile>

Teste si le fichier zip est valide.
@end deffn

@geindex option de ligne de commande zipfile; --metadata-encoding
@anchor{library/zipfile cmdoption-zipfile-metadata-encoding}@anchor{2963}
@deffn {Option} @w{-}@w{-}metadata@w{-}encoding <encoding>

Specify encoding of member names for @ref{295c,,-l}, @ref{295b,,-e} and
@ref{2961,,-t}.


Ajouté dans la version 3.11.

@end deffn

@node Problèmes de décompression,,Interface en ligne de commande<2>,zipfile --- Work with ZIP archives
@anchor{library/zipfile decompression-pitfalls}@anchor{2964}
@subsubsection Problèmes de décompression


L'extraction d'une archive ZIP par le module `zipfile' peut échouer pour les raisons listées ci-dessous.

@menu
* À cause du fichier lui-même:: 
* Limitations du système de fichiers:: 
* Ressources limitées:: 
* Interruption:: 
* Comportements par défaut de l'extraction:: 

@end menu

@node À cause du fichier lui-même,Limitations du système de fichiers,,Problèmes de décompression
@anchor{library/zipfile from-file-itself}@anchor{2965}
@subsubsection À cause du fichier lui-même


La décompression peut échouer à cause d'un mot de passe ou d'une somme de contrôle CRC incorrectes. Elle peut aussi échouer si le format, la méthode de compression, ou de chiffrement n'est pas implémenté.

@node Limitations du système de fichiers,Ressources limitées,À cause du fichier lui-même,Problèmes de décompression
@anchor{library/zipfile file-system-limitations}@anchor{2966}
@subsubsection Limitations du système de fichiers


Dépasser les limites du système de fichiers peut faire échouer la décompression. Ces limites peuvent concerner les caractères licites pour un nom de fichier, la longueur du nom du fichier ou du chemin, la taille d'un fichier, le nombre de fichiers, etc.

@node Ressources limitées,Interruption,Limitations du système de fichiers,Problèmes de décompression
@anchor{library/zipfile resources-limitations}@anchor{2967}@anchor{library/zipfile zipfile-resources-limitations}@anchor{2968}
@subsubsection Ressources limitées


Le manque de mémoire ou d'espace disque peut mener à un échec de décompression. Par exemple, une bombe de décompression (ZIP bomb@footnote{https://en.wikipedia.org/wiki/Zip_bomb}), décompressés avec `zifile' peut remplir l'espace disque.

@node Interruption,Comportements par défaut de l'extraction,Ressources limitées,Problèmes de décompression
@anchor{library/zipfile interruption}@anchor{2969}
@subsubsection Interruption


Une interruption durant la décompression, en utilisant `control-C' ou en tuant le processus, peut mener à une décompression partielle de l'archive.

@node Comportements par défaut de l'extraction,,Interruption,Problèmes de décompression
@anchor{library/zipfile default-behaviors-of-extraction}@anchor{296a}
@subsubsection Comportements par défaut de l'extraction


Ne pas connaître le comportement d'extraction par défaut peut causer des résultats inattendus. Par exemple, lors de l'extraction d'une même archive deux fois, les fichiers sont écrasés sans prévenir.

@node tarfile --- Read and write tar archive files,,zipfile --- Work with ZIP archives,Compression de donnée et archivage
@anchor{library/tarfile doc}@anchor{296b}@anchor{library/tarfile module-tarfile}@anchor{dd}@anchor{library/tarfile tarfile-read-and-write-tar-archive-files}@anchor{296c}
@subsection @code{tarfile} --- Read and write tar archive files


@geindex module; tarfile

`Code source :' Lib/tarfile.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tarfile.py}


__________________________________________________________________


Le module @ref{dd,,tarfile} rend possible la lecture et l'écriture des archives `tar', incluant celles utilisant la compression `gzip', `bz2' et `lzma'. Utilisez le module @ref{130,,zipfile} pour lire ou écrire des fichiers @code{zip}, ou les fonctions de niveau supérieur dans @ref{11f6,,shutil}.

Quelques faits et chiffres :


@itemize *

@item 
lit et écrit des archives compressées avec @ref{66,,gzip}, @ref{13,,bz2} ou @ref{89,,lzma} si les modules respectifs sont disponibles.

@item 
prise en charge de la lecture/écriture pour le format `POSIX.1-1988' (`ustar').

@item 
prise en charge de la lecture/écriture pour le format GNU `tar' incluant les extensions `longname' et `longlink', prise en charge de la lecture seule de toutes les variantes de l'extension `sparse' incluant la restauration des fichiers discontinus.

@item 
prise en charge de la lecture/écriture pour le format `POSIX.1-2001' (`pax').

@item 
gère les répertoires, les fichiers normaux, les liens directs (`hard links' en anglais), les liens symboliques, les tubes nommés (`FIFO' en anglais), les périphériques de caractère et les périphériques de bloc et est en mesure d'acquérir et de restaurer les informations du fichier comme l'horodatage, les autorisations d'accès et le propriétaire.
@end itemize


Modifié dans la version 3.3: prise en charge de la compression @ref{89,,lzma}.



Modifié dans la version 3.12: Archives are extracted using a @ref{456,,filter},
which makes it possible to either limit surprising/dangerous features,
or to acknowledge that they are expected and the archive is fully trusted.
By default, archives are fully trusted, but this default is deprecated
and slated to change in Python 3.14.


@geindex open() (dans le module tarfile)
@anchor{library/tarfile tarfile open}@anchor{e60}
@deffn {Fonction} tarfile.open (name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

Renvoie un objet @ref{11ed,,TarFile} pour le nom de chemin `name'. Pour plus d'informations sur les objets @ref{11ed,,TarFile} et les mot-clefs arguments permis, voir @ref{296d,,Les objets TarFile}.

Le `mode' doit être une chaîne de caractères de la forme @code{'filemode[:compression]'}, par défaut à @code{'r'}. Voici une liste complète des combinaisons de mode :


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

mode

@tab

action

@item

@code{'r' ou 'r:*'}

@tab

Ouvre en lecture avec compression transparente (recommandé).

@item

@code{'r:'}

@tab

Ouvre en lecture, sans compression.

@item

@code{'r:gz'}

@tab

Ouvre en lecture avec la compression `gzip'.

@item

@code{'r:bz2'}

@tab

Ouvre en lecture avec la compression `bzip2'.

@item

@code{'r:xz'}

@tab

Ouvre en lecture avec la compression `lzma'.

@item

@code{'x'} ou @code{'x:'}

@tab

Create a tarfile exclusively without
compression.
Raise a @ref{1009,,FileExistsError} exception
if it already exists.

@item

@code{'x:gz'}

@tab

Create a tarfile with gzip compression.
Raise a @ref{1009,,FileExistsError} exception
if it already exists.

@item

@code{'x:bz2'}

@tab

Create a tarfile with bzip2 compression.
Raise a @ref{1009,,FileExistsError} exception
if it already exists.

@item

@code{'x:xz'}

@tab

Create a tarfile with lzma compression.
Raise a @ref{1009,,FileExistsError} exception
if it already exists.

@item

@code{'a' ou 'a:'}

@tab

Ouvre pour ajouter à la fin, sans compression. Le fichier est créé s'il n'existe pas.

@item

@code{'w' ou 'w:'}

@tab

Ouvre en écriture, sans compression.

@item

@code{'w:gz'}

@tab

Ouvre en écriture avec compression `gzip'.

@item

@code{'w:bz2'}

@tab

Ouvre en écriture avec compression `bzip2'.

@item

@code{'w:xz'}

@tab

Ouvre en écriture avec la compression `lzma'.

@end multitable


Notez que les combinaisons @code{'a:gz'}, @code{'a:bz2'} ou @code{'a:xz'} ne sont pas possibles. Si le mode n'est pas adapté pour ouvrir un certain fichier (compressé) pour la lecture, une exception @ref{1828,,ReadError} est levée. Utilisez le mode @code{'r'} pour éviter cela. Si une méthode de compression n'est pas prise en charge, @ref{296e,,CompressionError} est levée.

Si `fileobj' est spécifié, il est utilisé comme une alternative au @ref{11a0,,file object} ouvert en mode binaire pour `name'. Il est censé être à la position 0.

For modes @code{'w:gz'}, @code{'x:gz'}, @code{'w|gz'}, @code{'w:bz2'}, @code{'x:bz2'},
@code{'w|bz2'}, @ref{e60,,tarfile.open()} accepts the keyword argument
`compresslevel' (default @code{9}) to specify the compression level of the file.

Pour les modes @code{'w:xz'} et @code{'x:xz'}, @ref{e60,,tarfile.open()} accepte l'argument nommé `preset' pour spécifier le niveau de compression du fichier.

For special purposes, there is a second format for `mode':
@code{'filemode|[compression]'}.  @ref{e60,,tarfile.open()} will return a @ref{11ed,,TarFile}
object that processes its data as a stream of blocks.  No random seeking will
be done on the file. If given, `fileobj' may be any object that has a
@ref{e09,,read()} or @ref{296f,,write()} method
(depending on the `mode') that works with bytes.
`bufsize' specifies the blocksize and defaults to @code{20 * 512} bytes.
Use this variant in combination with e.g. @code{sys.stdin.buffer}, a socket
@ref{11a0,,file object} or a tape device.
However, such a @ref{11ed,,TarFile} object is limited in that it does
not allow random access, see @ref{2970,,Exemples}.  The currently
possible modes:


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mode

@tab

Action

@item

@code{'r|*'}

@tab

Ouvre un `flux' des blocs de `tar' en lecture avec une compression transparente.

@item

@code{'r|'}

@tab

Ouvre un `flux' de blocs `tar' non compressés en lecture.

@item

@code{'r|gz'}

@tab

Ouvre un flux compressé avec `gzip' en lecture.

@item

@code{'r|bz2'}

@tab

Ouvre un `flux' compressé avec `bzip2' en lecture.

@item

@code{'r|xz'}

@tab

Ouvre un `flux' compressé avec `lzma' en lecture.

@item

@code{'w|'}

@tab

Ouvre un `flux' non compressé en écriture.

@item

@code{'w|gz'}

@tab

Ouvre un `flux' compressé avec `gzip' en écriture.

@item

@code{'w|bz2'}

@tab

Ouvre un `flux' compressé avec `bzip2' en écriture.

@item

@code{'w|xz'}

@tab

Ouvre un `flux' compressé avec `lzma' en écriture.

@end multitable



Modifié dans la version 3.5: le mode @code{'x'} (création exclusive) a été ajouté.



Modifié dans la version 3.6: le paramètre `name' accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.12: The `compresslevel' keyword argument also works for streams.

@end deffn


@deffn {Classe} tarfile.TarFile

Classe pour la lecture et l'écriture d'archives `tar'. N'utilisez pas cette classe directement, préférez @ref{e60,,tarfile.open()}. Voir @ref{296d,,Les objets TarFile}.
@end deffn

@geindex is_tarfile() (dans le module tarfile)
@anchor{library/tarfile tarfile is_tarfile}@anchor{17d2}
@deffn {Fonction} tarfile.is_tarfile (name)

Renvoie @ref{bfb,,True} si `name' est un fichier d'archive `tar', que le module @ref{dd,,tarfile} peut lire. `name' peut être une @ref{435,,str}, un ficher ou un objet fichier-compatible.


Modifié dans la version 3.9: Prise en charge des fichiers et des objets fichier-compatibles.

@end deffn

Le module @ref{dd,,tarfile} définit les exceptions suivantes :

@geindex TarError
@anchor{library/tarfile tarfile TarError}@anchor{2971}
@deffn {Exception} tarfile.TarError

Classe de base pour toutes les exceptions du module @ref{dd,,tarfile}.
@end deffn

@geindex ReadError
@anchor{library/tarfile tarfile ReadError}@anchor{1828}
@deffn {Exception} tarfile.ReadError

Est levée lors de l'ouverture d'une archive `tar', qui ne peut pas être gérée par le module @ref{dd,,tarfile} ou est invalide.
@end deffn

@geindex CompressionError
@anchor{library/tarfile tarfile CompressionError}@anchor{296e}
@deffn {Exception} tarfile.CompressionError

Est levée lorsqu'une méthode de compression n'est pas prise en charge ou lorsque les données ne peuvent pas être décodées correctement.
@end deffn

@geindex StreamError
@anchor{library/tarfile tarfile StreamError}@anchor{2972}
@deffn {Exception} tarfile.StreamError

Est levée pour les limitations typiques des objets de type flux @ref{11ed,,TarFile}.
@end deffn

@geindex ExtractError
@anchor{library/tarfile tarfile ExtractError}@anchor{2973}
@deffn {Exception} tarfile.ExtractError

Est levée pour des erreurs `non-fatales' lors de l'utilisation de @ref{e62,,TarFile.extract()}, mais uniquement si @ref{2974,,TarFile.errorlevel}@code{== 2}.
@end deffn

@geindex HeaderError
@anchor{library/tarfile tarfile HeaderError}@anchor{2975}
@deffn {Exception} tarfile.HeaderError

Est levée par @ref{2976,,TarInfo.frombuf()} si le tampon qu'il obtient n'est pas valide.
@end deffn

@geindex FilterError
@anchor{library/tarfile tarfile FilterError}@anchor{2977}
@deffn {Exception} tarfile.FilterError

Base class for members @ref{2978,,refused} by
filters.

@geindex tarinfo (attribut tarfile.FilterError)
@anchor{library/tarfile tarfile FilterError tarinfo}@anchor{2979}
@deffn {Attribut} tarinfo

Information about the member that the filter refused to extract,
as @ref{297a,,TarInfo}.
@end deffn
@end deffn

@geindex AbsolutePathError
@anchor{library/tarfile tarfile AbsolutePathError}@anchor{297b}
@deffn {Exception} tarfile.AbsolutePathError

Raised to refuse extracting a member with an absolute path.
@end deffn

@geindex OutsideDestinationError
@anchor{library/tarfile tarfile OutsideDestinationError}@anchor{297c}
@deffn {Exception} tarfile.OutsideDestinationError

Raised to refuse extracting a member outside the destination directory.
@end deffn

@geindex SpecialFileError
@anchor{library/tarfile tarfile SpecialFileError}@anchor{297d}
@deffn {Exception} tarfile.SpecialFileError

Raised to refuse extracting a special file (e.g. a device or pipe).
@end deffn

@geindex AbsoluteLinkError
@anchor{library/tarfile tarfile AbsoluteLinkError}@anchor{297e}
@deffn {Exception} tarfile.AbsoluteLinkError

Raised to refuse extracting a symbolic link with an absolute path.
@end deffn

@geindex LinkOutsideDestinationError
@anchor{library/tarfile tarfile LinkOutsideDestinationError}@anchor{297f}
@deffn {Exception} tarfile.LinkOutsideDestinationError

Raised to refuse extracting a symbolic link pointing outside the destination
directory.
@end deffn

Les constantes suivantes sont disponibles au niveau du module :

@geindex ENCODING (dans le module tarfile)
@anchor{library/tarfile tarfile ENCODING}@anchor{2980}
@deffn {Données} tarfile.ENCODING

L'encodage des caractères par défaut est @code{'utf-8'} sous Windows, sinon la valeur renvoyée par @ref{c47,,sys.getfilesystemencoding()}.
@end deffn

@geindex REGTYPE (dans le module tarfile)
@geindex AREGTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile REGTYPE}@anchor{2981}
@deffn {Données} tarfile.REGTYPE
@anchor{library/tarfile tarfile AREGTYPE}@anchor{2982}
@deffnx {Données} tarfile.AREGTYPE

A regular file @ref{2983,,type}.
@end deffn

@geindex LNKTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile LNKTYPE}@anchor{2984}
@deffn {Données} tarfile.LNKTYPE

A link (inside tarfile) @ref{2983,,type}.
@end deffn

@geindex SYMTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile SYMTYPE}@anchor{2985}
@deffn {Données} tarfile.SYMTYPE

A symbolic link @ref{2983,,type}.
@end deffn

@geindex CHRTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile CHRTYPE}@anchor{2986}
@deffn {Données} tarfile.CHRTYPE

A character special device @ref{2983,,type}.
@end deffn

@geindex BLKTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile BLKTYPE}@anchor{2987}
@deffn {Données} tarfile.BLKTYPE

A block special device @ref{2983,,type}.
@end deffn

@geindex DIRTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile DIRTYPE}@anchor{2988}
@deffn {Données} tarfile.DIRTYPE

A directory @ref{2983,,type}.
@end deffn

@geindex FIFOTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile FIFOTYPE}@anchor{2989}
@deffn {Données} tarfile.FIFOTYPE

A FIFO special device @ref{2983,,type}.
@end deffn

@geindex CONTTYPE (dans le module tarfile)
@anchor{library/tarfile tarfile CONTTYPE}@anchor{298a}
@deffn {Données} tarfile.CONTTYPE

A contiguous file @ref{2983,,type}.
@end deffn

@geindex GNUTYPE_LONGNAME (dans le module tarfile)
@anchor{library/tarfile tarfile GNUTYPE_LONGNAME}@anchor{298b}
@deffn {Données} tarfile.GNUTYPE_LONGNAME

A GNU tar longname @ref{2983,,type}.
@end deffn

@geindex GNUTYPE_LONGLINK (dans le module tarfile)
@anchor{library/tarfile tarfile GNUTYPE_LONGLINK}@anchor{298c}
@deffn {Données} tarfile.GNUTYPE_LONGLINK

A GNU tar longlink @ref{2983,,type}.
@end deffn

@geindex GNUTYPE_SPARSE (dans le module tarfile)
@anchor{library/tarfile tarfile GNUTYPE_SPARSE}@anchor{298d}
@deffn {Données} tarfile.GNUTYPE_SPARSE

A GNU tar sparse file @ref{2983,,type}.
@end deffn

Chacune des constantes suivantes définit un format d'archive `tar' que le module @ref{dd,,tarfile} est capable de créer. Voir la section @ref{298e,,Formats tar pris en charge} pour plus de détails.

@geindex USTAR_FORMAT (dans le module tarfile)
@anchor{library/tarfile tarfile USTAR_FORMAT}@anchor{298f}
@deffn {Données} tarfile.USTAR_FORMAT

Le format `POSIX.1-1988' (`ustar').
@end deffn

@geindex GNU_FORMAT (dans le module tarfile)
@anchor{library/tarfile tarfile GNU_FORMAT}@anchor{2990}
@deffn {Données} tarfile.GNU_FORMAT

Le format GNU `tar'.
@end deffn

@geindex PAX_FORMAT (dans le module tarfile)
@anchor{library/tarfile tarfile PAX_FORMAT}@anchor{2991}
@deffn {Données} tarfile.PAX_FORMAT

Le format `POSIX.1-2001' (`pax').
@end deffn

@geindex DEFAULT_FORMAT (dans le module tarfile)
@anchor{library/tarfile tarfile DEFAULT_FORMAT}@anchor{2992}
@deffn {Données} tarfile.DEFAULT_FORMAT

Format par défaut pour la création d'archives. C'est actuellement @ref{2991,,PAX_FORMAT}.


Modifié dans la version 3.8: Le format par défaut des nouvelles archives a été changé de @ref{2990,,GNU_FORMAT} en @ref{2991,,PAX_FORMAT}.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{130,,zipfile}

Documentation du module standard @ref{130,,zipfile}.

@item @ref{11f6,,Archiving operations}

Documentation des outils d'archivage de haut niveau fournis par le module standard @ref{c4,,shutil}.

@item Manuel GNU *tar*@comma{} format *tar* basique (en anglais)@footnote{https://www.gnu.org/software/tar/manual/html_node/Standard.html}

Documentation pour les fichiers d'archive `tar', y compris les extensions `tar' GNU.
@end table


@menu
* Les objets TarFile:: 
* Les objets TarInfo:: 
* Extraction filters:: 
* Interface en ligne de commande: Interface en ligne de commande<3>. 
* Exemples: Exemples<9>. 
* Formats tar pris en charge:: 
* Problèmes unicode:: 

@end menu

@node Les objets TarFile,Les objets TarInfo,,tarfile --- Read and write tar archive files
@anchor{library/tarfile id1}@anchor{2993}@anchor{library/tarfile tarfile-objects}@anchor{296d}
@subsubsection Les objets `TarFile'


L'objet @ref{11ed,,TarFile} fournit une interface vers une archive `tar'. Une archive `tar' est une séquence de blocs. Un membre d'archive (un fichier stocké) est composé d'un bloc d'en-tête suivi des blocs de données. Il est possible de stocker plusieurs fois un fichier dans une archive `tar'. Chaque membre d'archive est représenté par un objet @ref{11ee,,TarInfo}, voir @ref{297a,,Les objets TarInfo} pour plus de détails.

Un objet @ref{11ed,,TarFile} peut être utilisé comme gestionnaire de contexte dans une instruction @ref{5bc,,with}. Il sera automatiquement fermé une fois le bloc terminé. Veuillez noter qu'en cas d'exception, une archive ouverte en écriture ne sera pas finalisée ; seul l'objet fichier utilisé en interne sera fermé. Voir la section @ref{2970,,Exemples} pour un cas d'utilisation.


Ajouté dans la version 3.2: Ajout de la prise en charge du protocole de gestion de contexte.


@geindex TarFile (classe dans tarfile)
@anchor{library/tarfile tarfile TarFile}@anchor{11ed}
@deffn {Classe} tarfile.TarFile (name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1, stream=False)

Tous les arguments suivants sont facultatifs et sont également accessibles en tant qu'instance d'attributs.

`name' is the pathname of the archive. `name' may be a @ref{29d,,path-like object}.
It can be omitted if `fileobj' is given.
In this case, the file object's @code{name} attribute is used if it exists.

Le `mode' est soit @code{'r'} pour lire à partir d'une archive existante, @code{'a'} pour ajouter des données à un fichier existant, @code{'w'} pour créer un nouveau fichier en écrasant un existant, ou @code{'x'} pour créer un nouveau fichier uniquement s'il n'existe pas déjà.

Si `fileobj' est fourni, il est utilisé pour lire ou écrire des données. S'il peut être déterminé, le `mode' est remplacé par le mode de `fileobj'. `fileobj' sera utilisé à partir de la position 0.

@cartouche
@quotation Note 
`fileobj' n'est pas fermé, lorsque @ref{11ed,,TarFile} est fermé.
@end quotation
@end cartouche

Le `format' contrôle le format d'archive en écriture. Il doit s'agir de l'une des constantes @ref{298f,,USTAR_FORMAT}, @ref{2990,,GNU_FORMAT} ou @ref{2991,,PAX_FORMAT} définies au niveau du module. Lors de la lecture, le format sera automatiquement détecté, même si différents formats sont présents dans une même archive.

L'argument `tarinfo' peut être utilisé pour remplacer la classe par défaut @ref{11ee,,TarInfo} par une autre.

Si `dereference' est @ref{b25,,False}, ajoute des liens symboliques et physiques à l'archive. Si c'est @ref{bfb,,True}, ajoute le contenu des fichiers cibles à l'archive. Cela n'a aucun effet sur les systèmes qui ne prennent pas en charge les liens symboliques.

Si `ignore_zeros' est @ref{b25,,False}, traite un bloc vide comme la fin de l'archive. Si c'est le cas @ref{bfb,,True}, saute les blocs vides (et invalides) et essaye d'obtenir autant de membres que possible. Ceci n'est utile que pour lire des archives concaténées ou endommagées.

`debug' peut être défini de @code{0} (aucun message de débogage) à @code{3} (tous les messages de débogage). Les messages sont écrits dans @code{sys.stderr}.

`errorlevel' controls how extraction errors are handled,
see @ref{2974,,the corresponding attribute}.

Les arguments `encoding' et `errors' définissent l'encodage de caractères à utiliser pour lire ou écrire l'archive et comment les erreurs de conversion vont être traitées. Les paramètres par défaut fonctionneront pour la plupart des utilisateurs. Voir la section @ref{2994,,Problèmes unicode} pour des informations détaillées.

L'argument `pax_headers' est un dictionnaire facultatif de chaînes de caractères qui sera ajouté en tant qu'en-tête global `pax' si le `format' est @ref{2991,,PAX_FORMAT}.

If `stream' is set to @ref{bfb,,True} then while reading the archive info about files
in the archive are not cached, saving memory.


Modifié dans la version 3.2: Utilise @code{'surrogateescape'} comme valeur par défaut pour l'argument `errors'.



Modifié dans la version 3.5: le mode @code{'x'} (création exclusive) a été ajouté.



Modifié dans la version 3.6: le paramètre `name' accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.13: Add the `stream' parameter.

@end deffn

@geindex open() (méthode de la classe tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile open}@anchor{17d3}
@deffn {Méthode} classmethod TarFile.open (...)

Constructeur alternatif. La fonction @ref{e60,,tarfile.open()} est en fait un raccourci vers cette méthode de classe.
@end deffn

@geindex getmember() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile getmember}@anchor{17e1}
@deffn {Méthode} TarFile.getmember (name)

Renvoie un objet @ref{11ee,,TarInfo} pour le membre `name'. Si `name' est introuvable dans l'archive, @ref{33a,,KeyError} est levée.

@cartouche
@quotation Note 
Si un membre apparaît plus d'une fois dans l'archive, sa dernière occurrence est supposée être la version la plus récente.
@end quotation
@end cartouche
@end deffn

@geindex getmembers() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile getmembers}@anchor{e64}
@deffn {Méthode} TarFile.getmembers ()

Renvoie les membres de l'archive sous la forme d'une liste d'objets @ref{11ee,,TarInfo}. La liste a le même ordre que les membres de l'archive.
@end deffn

@geindex getnames() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile getnames}@anchor{2995}
@deffn {Méthode} TarFile.getnames ()

Renvoie les membres comme une liste de leurs noms. Il a le même ordre que la liste renvoyée par @ref{e64,,getmembers()}.
@end deffn

@geindex list() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile list}@anchor{e63}
@deffn {Méthode} TarFile.list (verbose=True, *, members=None)

Imprime une table des matières dans @code{sys.stdout}. Si `verbose' est @ref{b25,,False}, seuls les noms des membres sont imprimés. Si c'est @ref{bfb,,True}, une sortie similaire à celle de @code{ls -l} est produite. Si des `membres' facultatifs sont fournis, il doit s'agir d'un sous-ensemble de la liste renvoyée par @ref{e64,,getmembers()}.


Modifié dans la version 3.5: Ajout du paramètre `members'.

@end deffn

@geindex next() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile next}@anchor{2996}
@deffn {Méthode} TarFile.next ()

Renvoie le membre suivant de l'archive en tant qu'objet @ref{11ee,,TarInfo}, lorsque la classe @ref{11ed,,TarFile} est ouverte en lecture. Renvoie @ref{660,,None} s'il n'y a pas.
@end deffn

@geindex extractall() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extractall}@anchor{e61}
@deffn {Méthode} TarFile.extractall (path='.', members=None, *, numeric_owner=False, filter=None)

Extrait tous les membres de l'archive vers le répertoire de travail actuel ou le répertoire `chemin'. Si des `membres' facultatifs sont fournis, il doit s'agir d'un sous-ensemble de la liste renvoyée par @ref{e64,,getmembers()}. Les informations d'annuaire telles que le propriétaire, l'heure de modification et les autorisations sont définies une fois tous les membres extraits. Cela est fait pour contourner deux problèmes : l'heure de modification d'un répertoire est réinitialisée chaque fois qu'un fichier y est créé. Et, si les autorisations d'un répertoire ne permettent pas l'écriture, l'extraction de fichiers échoue.

Si `numeric_owner' est @ref{bfb,,True}, les numéros `uid' et `gid' du fichier `tar' sont utilisés pour définir le propriétaire et le groupe des fichiers extraits. Sinon, les valeurs nommées du fichier `tar' sont utilisées.

The `filter' argument specifies how @code{members} are modified or rejected
before extraction.
See @ref{456,,Extraction filters} for details.
It is recommended to set this explicitly depending on which `tar' features
you need to support.

@cartouche
@quotation Avertissement 
Ne jamais extraire des archives de sources non fiables sans inspection préalable. Il est possible que des fichiers soient créés en dehors de `chemin', par exemple : les membres qui ont des noms de fichiers absolus commençant par @code{"/"} ou des noms de fichiers avec deux points @code{".."}.

Set @code{filter='data'} to prevent the most dangerous security issues,
and read the @ref{456,,Extraction filters} section for details.
@end quotation
@end cartouche


Modifié dans la version 3.5: Ajout du paramètre `numeric_owner'.



Modifié dans la version 3.6: Le paramètre `path' accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.12: Ajout du paramètre `filter'.

@end deffn

@geindex extract() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extract}@anchor{e62}
@deffn {Méthode} TarFile.extract (member, path='@w{'}, set_attrs=True, *, numeric_owner=False, filter=None)

Extrait un membre de l'archive vers le répertoire de travail actuel, en utilisant son nom complet. Les informations de son fichier sont extraites aussi précisément que possible. Le membre peut être un nom de fichier ou un objet @ref{11ee,,TarInfo}. Vous pouvez spécifier un répertoire différent en utilisant `path'. `path' peut être un @ref{29d,,path-like object}. Les attributs de fichier (propriétaire, `mtime', mode) sont définis sauf si `set_attrs' est faux.

The `numeric_owner' and `filter' arguments are the same as
for @ref{e61,,extractall()}.

@cartouche
@quotation Note 
La méthode @ref{e62,,extract()} ne prend pas en charge plusieurs problèmes d'extraction. Dans la plupart des cas, vous devriez envisager d'utiliser la méthode @ref{e61,,extractall()}.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Voir l'avertissement pour @ref{e61,,extractall()}.

Set @code{filter='data'} to prevent the most dangerous security issues,
and read the @ref{456,,Extraction filters} section for details.
@end quotation
@end cartouche


Modifié dans la version 3.2: Ajout du paramètre `set_attrs'.



Modifié dans la version 3.5: Ajout du paramètre `numeric_owner'.



Modifié dans la version 3.6: Le paramètre `path' accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.12: Ajout du paramètre `filter'.

@end deffn

@geindex extractfile() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extractfile}@anchor{2997}
@deffn {Méthode} TarFile.extractfile (member)

Extrait un membre de l'archive en tant qu'objet fichier. `member' peut être un nom de fichier ou un objet @ref{11ee,,TarInfo}. Si `member' est un fichier normal ou un lien, un objet @ref{11eb,,io.BufferedReader} est renvoyé. Sinon, @ref{660,,None} est renvoyé. Lève une exception @ref{33a,,KeyError} si `member' n'est pas présent dans l'archive.


Modifié dans la version 3.3: Renvoie un objet @ref{11eb,,io.BufferedReader}.



Modifié dans la version 3.13: The returned @ref{11eb,,io.BufferedReader} object has the @code{mode}
attribute which is always equal to @code{'rb'}.

@end deffn

@geindex errorlevel (attribut tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile errorlevel}@anchor{2974}
@deffn {Attribut} TarFile.errorlevel: @ref{254,,int}

If `errorlevel' is @code{0}, errors are ignored when using @ref{e62,,TarFile.extract()}
and @ref{e61,,TarFile.extractall()}.
Nevertheless, they appear as error messages in the debug output when
`debug' is greater than 0.
If @code{1} (the default), all `fatal' errors are raised as @ref{40d,,OSError} or
@ref{2977,,FilterError} exceptions. If @code{2}, all `non-fatal' errors are raised
as @ref{2971,,TarError} exceptions as well.

Some exceptions, e.g. ones caused by wrong argument types or data
corruption, are always raised.

Custom @ref{456,,extraction filters}
should raise @ref{2977,,FilterError} for `fatal' errors
and @ref{2973,,ExtractError} for `non-fatal' ones.

Note that when an exception is raised, the archive may be partially
extracted. It is the user’s responsibility to clean up.
@end deffn

@geindex extraction_filter (attribut tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile extraction_filter}@anchor{2998}
@deffn {Attribut} TarFile.extraction_filter


Ajouté dans la version 3.12.


The @ref{456,,extraction filter} used
as a default for the `filter' argument of @ref{e62,,extract()}
and @ref{e61,,extractall()}.

The attribute may be @code{None} or a callable.
String names are not allowed for this attribute, unlike the `filter'
argument to @ref{e62,,extract()}.

If @code{extraction_filter} is @code{None} (the default),
calling an extraction method without a `filter' argument will raise a
@code{DeprecationWarning},
and fall back to the @ref{2999,,fully_trusted} filter,
whose dangerous behavior matches previous versions of Python.

In Python 3.14+, leaving @code{extraction_filter=None} will cause
extraction methods to use the @ref{1686,,data} filter by default.

The attribute may be set on instances or overridden in subclasses.
It also is possible to set it on the @code{TarFile} class itself to set a
global default, although, since it affects all uses of `tarfile',
it is best practice to only do so in top-level applications or
@ref{c6,,site configuration}.
To set a global default this way, a filter function needs to be wrapped in
@ref{40c,,staticmethod()} to prevent injection of a @code{self} argument.
@end deffn

@geindex add() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile add}@anchor{be1}
@deffn {Méthode} TarFile.add (name, arcname=None, recursive=True, *, filter=None)

Ajoute le fichier `name' à l'archive. `name' peut être n'importe quel type de fichier (répertoire, `fifo', lien symbolique, etc.). S'il est donné, `arcname' spécifie un autre nom pour le fichier dans l'archive. Les répertoires sont ajoutés récursivement par défaut. Cela peut être évité en définissant `recursive' sur @ref{b25,,False}. La récursivité ajoute des entrées dans l'ordre trié. Si `filter' est donné, il convient que ce soit une fonction qui prend un argument d'objet @ref{11ee,,TarInfo} et renvoie l'objet changé @ref{11ee,,TarInfo}. S'il renvoie à la place @ref{660,,None}, l'objet @ref{11ee,,TarInfo} sera exclu de l'archive. Voir @ref{2970,,Exemples} pour un exemple.


Modifié dans la version 3.2: Ajout du paramètre `filter'.



Modifié dans la version 3.7: La récursivité ajoute les entrées dans un ordre trié.

@end deffn

@geindex addfile() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile addfile}@anchor{15b9}
@deffn {Méthode} TarFile.addfile (tarinfo, fileobj=None)

Add the @ref{11ee,,TarInfo} object `tarinfo' to the archive. If `tarinfo' represents
a non zero-size regular file, the `fileobj' argument should be a @ref{1c15,,binary file},
and @code{tarinfo.size} bytes are read from it and added to the archive.  You can
create @ref{11ee,,TarInfo} objects directly, or by using @ref{299a,,gettarinfo()}.


Modifié dans la version 3.13: `fileobj' must be given for non-zero-sized regular files.

@end deffn

@geindex gettarinfo() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile gettarinfo}@anchor{299a}
@deffn {Méthode} TarFile.gettarinfo (name=None, arcname=None, fileobj=None)

Crée un objet @ref{11ee,,TarInfo} à partir du résultat de @ref{48a,,os.stat()} ou équivalent sur un fichier existant. Le fichier est soit nommé par `name', soit spécifié comme @ref{11a0,,file object} `fileobj' avec un descripteur de fichier. `name' peut être un @ref{299b,,objet} semblable à un chemin. S'il est donné, `arcname' spécifie un autre nom pour le fichier dans l'archive, sinon, le nom est tiré de l'attribut `fileobj' @ref{2901,,name}, ou de l'argument `name'. Le nom doit être une chaîne de texte.

Vous pouvez modifier certains des attributs de @ref{11ee,,TarInfo} avant de les ajouter en utilisant @ref{15b9,,addfile()}. Si l'objet fichier n'est pas un objet fichier ordinaire positionné au début du fichier, des attributs tels que @ref{299c,,size} peuvent nécessiter une modification. C'est le cas pour des objets tels que @ref{410,,GzipFile}. Le @ref{299d,,name} peut également être modifié, auquel cas `arcname' pourrait être une chaîne factice.


Modifié dans la version 3.6: le paramètre `name' accepte un @ref{29d,,path-like object}.

@end deffn

@geindex close() (méthode tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile close}@anchor{299e}
@deffn {Méthode} TarFile.close ()

Ferme le @ref{11ed,,TarFile}. En mode écriture, deux blocs de finition à zéro sont ajoutés à l'archive.
@end deffn

@geindex pax_headers (attribut tarfile.TarFile)
@anchor{library/tarfile tarfile TarFile pax_headers}@anchor{299f}
@deffn {Attribut} TarFile.pax_headers: @ref{253,,dict}

Un dictionnaire contenant des paires clé-valeur d'en-têtes globaux `pax'.
@end deffn

@node Les objets TarInfo,Extraction filters,Les objets TarFile,tarfile --- Read and write tar archive files
@anchor{library/tarfile id2}@anchor{29a0}@anchor{library/tarfile tarinfo-objects}@anchor{297a}
@subsubsection Les objets `TarInfo'


Un objet @ref{11ee,,TarInfo} représente un membre dans un @ref{11ed,,TarFile}. En plus de stocker tous les attributs requis d'un fichier (comme le type de fichier, la taille, l'heure, les autorisations, le propriétaire, etc.), il fournit quelques méthodes utiles pour déterminer son type. Il ne contient pas les données du fichier lui-même.

@ref{11ee,,TarInfo} objects are returned by @ref{11ed,,TarFile}'s methods
@ref{17e1,,getmember()}, @ref{e64,,getmembers()} and
@ref{299a,,gettarinfo()}.

Modifying the objects returned by @ref{17e1,,getmember()} or
@ref{e64,,getmembers()} will affect all subsequent
operations on the archive.
For cases where this is unwanted, you can use @ref{25,,copy.copy()} or
call the @ref{29a1,,replace()} method to create a modified copy in one step.

Several attributes can be set to @code{None} to indicate that a piece of metadata
is unused or unknown.
Different @ref{11ee,,TarInfo} methods handle @code{None} differently:


@itemize -

@item 
The @ref{e62,,extract()} or @ref{e61,,extractall()} methods will
ignore the corresponding metadata, leaving it set to a default.

@item 
@ref{15b9,,addfile()} will fail.

@item 
@ref{e63,,list()} will print a placeholder string.
@end itemize

@geindex TarInfo (classe dans tarfile)
@anchor{library/tarfile tarfile TarInfo}@anchor{11ee}
@deffn {Classe} tarfile.TarInfo (name='@w{'})

Crée un objet @ref{11ee,,TarInfo}.
@end deffn

@geindex frombuf() (méthode de la classe tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo frombuf}@anchor{2976}
@deffn {Méthode} classmethod TarInfo.frombuf (buf, encoding, errors)

Crée et renvoie un objet @ref{11ee,,TarInfo} à partir de la chaîne tampon `buf'.

Lève @ref{2975,,HeaderError} si le tampon n'est pas valide.
@end deffn

@geindex fromtarfile() (méthode de la classe tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo fromtarfile}@anchor{29a2}
@deffn {Méthode} classmethod TarInfo.fromtarfile (tarfile)

Lit le membre suivant dans l'objet @ref{11ed,,TarFile} `tarfile' et le renvoie comme un objet @ref{11ee,,TarInfo}.
@end deffn

@geindex tobuf() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo tobuf}@anchor{29a3}
@deffn {Méthode} TarInfo.tobuf (format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

Crée un tampon de chaîne de caractères à partir d'un objet @ref{11ee,,TarInfo}. Pour plus d'informations sur les arguments, voir le constructeur de la classe @ref{11ed,,TarFile}.


Modifié dans la version 3.2: Utilise @code{'surrogateescape'} comme valeur par défaut pour l'argument `errors'.

@end deffn

Un objet @code{TarInfo} a les attributs de données publics suivants :

@geindex name (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo name}@anchor{299d}
@deffn {Attribut} TarInfo.name: @ref{435,,str}

Nom du membre de l'archive.
@end deffn

@geindex size (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo size}@anchor{299c}
@deffn {Attribut} TarInfo.size: @ref{254,,int}

La taille en octets.
@end deffn

@geindex mtime (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo mtime}@anchor{29a4}
@deffn {Attribut} TarInfo.mtime: @ref{254,,int} | @ref{2eb,,float}

Time of last modification in seconds since the @ref{29a5,,epoch},
as in @ref{29a6,,os.stat_result.st_mtime}.


Modifié dans la version 3.12: Can be set to @code{None} for @ref{e62,,extract()} and
@ref{e61,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex mode (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo mode}@anchor{29a7}
@deffn {Attribut} TarInfo.mode: @ref{254,,int}

Permission bits, as for @ref{218,,os.chmod()}.


Modifié dans la version 3.12: Can be set to @code{None} for @ref{e62,,extract()} and
@ref{e61,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex type (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo type}@anchor{2983}
@deffn {Attribut} TarInfo.type

Type de fichier. `type' est généralement l'une des constantes suivantes : @ref{2981,,REGTYPE}, @ref{2982,,AREGTYPE}, @ref{2984,,LNKTYPE}, @ref{2985,,SYMTYPE}, @ref{2988,,DIRTYPE}, @ref{2989,,FIFOTYPE}, @ref{298a,,CONTTYPE}, @ref{2986,,CHRTYPE}, @ref{2987,,BLKTYPE}, @ref{298d,,GNUTYPE_SPARSE}. Pour déterminer plus facilement le type d'un objet @ref{11ee,,TarInfo}, utilisez les méthodes @code{is*()} ci-dessous.
@end deffn

@geindex linkname (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo linkname}@anchor{29a8}
@deffn {Attribut} TarInfo.linkname: @ref{435,,str}

Nom du fichier cible, qui n'est présent que dans les objets @ref{11ee,,TarInfo}  de type @ref{2984,,LNKTYPE} et @ref{2985,,SYMTYPE}.

For symbolic links (@code{SYMTYPE}), the `linkname' is relative to the directory
that contains the link.
For hard links (@code{LNKTYPE}), the `linkname' is relative to the root of
the archive.
@end deffn

@geindex uid (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo uid}@anchor{29a9}
@deffn {Attribut} TarInfo.uid: @ref{254,,int}

ID de l'utilisateur qui a initialement stocké ce membre.


Modifié dans la version 3.12: Can be set to @code{None} for @ref{e62,,extract()} and
@ref{e61,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex gid (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo gid}@anchor{29aa}
@deffn {Attribut} TarInfo.gid: @ref{254,,int}

ID de groupe de l'utilisateur qui a initialement stocké ce membre.


Modifié dans la version 3.12: Can be set to @code{None} for @ref{e62,,extract()} and
@ref{e61,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex uname (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo uname}@anchor{29ab}
@deffn {Attribut} TarInfo.uname: @ref{435,,str}

Nom d'utilisateur.


Modifié dans la version 3.12: Can be set to @code{None} for @ref{e62,,extract()} and
@ref{e61,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex gname (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo gname}@anchor{29ac}
@deffn {Attribut} TarInfo.gname: @ref{435,,str}

Nom de groupe.


Modifié dans la version 3.12: Can be set to @code{None} for @ref{e62,,extract()} and
@ref{e61,,extractall()}, causing extraction to skip applying this
attribute.

@end deffn

@geindex chksum (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo chksum}@anchor{29ad}
@deffn {Attribut} TarInfo.chksum: @ref{254,,int}

Header checksum.
@end deffn

@geindex devmajor (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo devmajor}@anchor{29ae}
@deffn {Attribut} TarInfo.devmajor: @ref{254,,int}

Device major number.
@end deffn

@geindex devminor (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo devminor}@anchor{29af}
@deffn {Attribut} TarInfo.devminor: @ref{254,,int}

Device minor number.
@end deffn

@geindex offset (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo offset}@anchor{29b0}
@deffn {Attribut} TarInfo.offset: @ref{254,,int}

The tar header starts here.
@end deffn

@geindex offset_data (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo offset_data}@anchor{29b1}
@deffn {Attribut} TarInfo.offset_data: @ref{254,,int}

The file's data starts here.
@end deffn

@geindex sparse (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo sparse}@anchor{29b2}
@deffn {Attribut} TarInfo.sparse

Sparse member information.
@end deffn

@geindex pax_headers (attribut tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo pax_headers}@anchor{29b3}
@deffn {Attribut} TarInfo.pax_headers: @ref{253,,dict}

Un dictionnaire contenant des paires clé-valeur d'un en-tête étendu `pax' associé.
@end deffn

@geindex replace() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo replace}@anchor{29a1}
@deffn {Méthode} TarInfo.replace (name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)


Ajouté dans la version 3.12.


Return a `new' copy of the @code{TarInfo} object with the given attributes
changed. For example, to return a @code{TarInfo} with the group name set to
@code{'staff'}, use:

@example
new_tarinfo = old_tarinfo.replace(gname='staff')
@end example

By default, a deep copy is made.
If `deep' is false, the copy is shallow, i.e. @code{pax_headers}
and any custom attributes are shared with the original @code{TarInfo} object.
@end deffn

Un objet @ref{11ee,,TarInfo} fournit également des méthodes de requête pratiques :

@geindex isfile() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isfile}@anchor{29b4}
@deffn {Méthode} TarInfo.isfile ()

Return @ref{bfb,,True} if the @ref{11ee,,TarInfo} object is a regular file.
@end deffn

@geindex isreg() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isreg}@anchor{29b5}
@deffn {Méthode} TarInfo.isreg ()

Identique à @ref{29b4,,isfile()}.
@end deffn

@geindex isdir() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isdir}@anchor{29b6}
@deffn {Méthode} TarInfo.isdir ()

Renvoie @ref{bfb,,True} si c'est un dossier.
@end deffn

@geindex issym() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo issym}@anchor{29b7}
@deffn {Méthode} TarInfo.issym ()

Renvoie @ref{bfb,,True} s'il s'agit d'un lien symbolique.
@end deffn

@geindex islnk() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo islnk}@anchor{29b8}
@deffn {Méthode} TarInfo.islnk ()

Renvoie @ref{bfb,,True} s'il s'agit d'un lien physique.
@end deffn

@geindex ischr() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo ischr}@anchor{29b9}
@deffn {Méthode} TarInfo.ischr ()

Renvoie @ref{bfb,,True} s'il s'agit d'un périphérique de caractères.
@end deffn

@geindex isblk() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isblk}@anchor{29ba}
@deffn {Méthode} TarInfo.isblk ()

Renvoie @ref{bfb,,True} s'il s'agit d'un périphérique de bloc.
@end deffn

@geindex isfifo() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isfifo}@anchor{29bb}
@deffn {Méthode} TarInfo.isfifo ()

Renvoie @ref{bfb,,True} s'il s'agit d'un tube nommé (`FIFO').
@end deffn

@geindex isdev() (méthode tarfile.TarInfo)
@anchor{library/tarfile tarfile TarInfo isdev}@anchor{29bc}
@deffn {Méthode} TarInfo.isdev ()

Renvoie @ref{bfb,,True} s'il s'agit d'un périphérique de caractères, d'un périphérique de bloc ou d'un tube nommé.
@end deffn

@node Extraction filters,Interface en ligne de commande<3>,Les objets TarInfo,tarfile --- Read and write tar archive files
@anchor{library/tarfile extraction-filters}@anchor{29bd}@anchor{library/tarfile tarfile-extraction-filter}@anchor{456}
@subsubsection Extraction filters



Ajouté dans la version 3.12.


The `tar' format is designed to capture all details of a UNIX-like filesystem,
which makes it very powerful.
Unfortunately, the features make it easy to create tar files that have
unintended -- and possibly malicious -- effects when extracted.
For example, extracting a tar file can overwrite arbitrary files in various
ways (e.g.  by using absolute paths, @code{..} path components, or symlinks that
affect later members).

In most cases, the full functionality is not needed.
Therefore, `tarfile' supports extraction filters: a mechanism to limit
functionality, and thus mitigate some of the security issues.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 706

@item PEP 706@footnote{https://peps.python.org/pep-0706/}

Contains further motivation and rationale behind the design.
@end table


The `filter' argument to @ref{e62,,TarFile.extract()} or @ref{e61,,extractall()}
can be:


@itemize *

@item 
the string @code{'fully_trusted'}: Honor all metadata as specified in the
archive.
Should be used if the user trusts the archive completely, or implements
their own complex verification.

@item 
the string @code{'tar'}: Honor most `tar'-specific features (i.e. features of
UNIX-like filesystems), but block features that are very likely to be
surprising or malicious. See @ref{29be,,tar_filter()} for details.

@item 
the string @code{'data'}: Ignore or block most features specific to UNIX-like
filesystems. Intended for extracting cross-platform data archives.
See @ref{1686,,data_filter()} for details.

@item 
@code{None} (default): Use @ref{2998,,TarFile.extraction_filter}.

If that is also @code{None} (the default), raise a @code{DeprecationWarning},
and fall back to the @code{'fully_trusted'} filter, whose dangerous behavior
matches previous versions of Python.

In Python 3.14, the @code{'data'} filter will become the default instead.
It's possible to switch earlier; see @ref{2998,,TarFile.extraction_filter}.

@item 
A callable which will be called for each extracted member with a
@ref{297a,,TarInfo} describing the member and the destination
path to where the archive is extracted (i.e. the same path is used for all
members):

@example
filter(member: TarInfo, path: str, /) -> TarInfo | None
@end example

The callable is called just before each member is extracted, so it can
take the current state of the disk into account.
It can:


@itemize -

@item 
return a @ref{11ee,,TarInfo} object which will be used instead of the metadata
in the archive, or

@item 
return @code{None}, in which case the member will be skipped, or

@item 
raise an exception to abort the operation or skip the member,
depending on @ref{2974,,errorlevel}.
Note that when extraction is aborted, @ref{e61,,extractall()} may leave
the archive partially extracted. It does not attempt to clean up.
@end itemize
@end itemize

@menu
* Default named filters:: 
* Filter errors:: 
* Hints for further verification:: 
* Supporting older Python versions:: 
* Stateful extraction filter example:: 

@end menu

@node Default named filters,Filter errors,,Extraction filters
@anchor{library/tarfile default-named-filters}@anchor{29bf}
@subsubsection Default named filters


The pre-defined, named filters are available as functions, so they can be
reused in custom filters:

@geindex fully_trusted_filter() (dans le module tarfile)
@anchor{library/tarfile tarfile fully_trusted_filter}@anchor{2999}
@deffn {Fonction} tarfile.fully_trusted_filter (member, path)

Return `member' unchanged.

This implements the @code{'fully_trusted'} filter.
@end deffn

@geindex tar_filter() (dans le module tarfile)
@anchor{library/tarfile tarfile tar_filter}@anchor{29be}
@deffn {Fonction} tarfile.tar_filter (member, path)

Implements the @code{'tar'} filter.


@itemize -

@item 
Strip leading slashes (@code{/} and @ref{655,,os.sep}) from filenames.

@item 
@ref{2978,,Refuse} to extract files with absolute
paths (in case the name is absolute
even after stripping slashes, e.g. @code{C:/foo} on Windows).
This raises @ref{297b,,AbsolutePathError}.

@item 
@ref{2978,,Refuse} to extract files whose absolute
path (after following symlinks) would end up outside the destination.
This raises @ref{297c,,OutsideDestinationError}.

@item 
Clear high mode bits (setuid, setgid, sticky) and group/other write bits
(@ref{2785,,S_IWGRP} | @ref{2788,,S_IWOTH}).
@end itemize

Return the modified @code{TarInfo} member.
@end deffn

@geindex data_filter() (dans le module tarfile)
@anchor{library/tarfile tarfile data_filter}@anchor{1686}
@deffn {Fonction} tarfile.data_filter (member, path)

Implements the @code{'data'} filter.
In addition to what @code{tar_filter} does:


@itemize -

@item 
@ref{2978,,Refuse} to extract links (hard or soft)
that link to absolute paths, or ones that link outside the destination.

This raises @ref{297e,,AbsoluteLinkError} or
@ref{297f,,LinkOutsideDestinationError}.

Note that such files are refused even on platforms that do not support
symbolic links.

@item 
@ref{2978,,Refuse} to extract device files
(including pipes).
This raises @ref{297d,,SpecialFileError}.

@item 
For regular files, including hard links:


@itemize -

@item 
Set the owner read and write permissions
(@ref{2780,,S_IRUSR} | @ref{2781,,S_IWUSR}).

@item 
Remove the group & other executable permission
(@ref{277c,,S_IXGRP} | @ref{2789,,S_IXOTH})
if the owner doesn’t have it (@ref{2782,,S_IXUSR}).
@end itemize

@item 
For other files (directories), set @code{mode} to @code{None}, so
that extraction methods skip applying permission bits.

@item 
Set user and group info (@code{uid}, @code{gid}, @code{uname}, @code{gname})
to @code{None}, so that extraction methods skip setting it.
@end itemize

Return the modified @code{TarInfo} member.
@end deffn

@node Filter errors,Hints for further verification,Default named filters,Extraction filters
@anchor{library/tarfile filter-errors}@anchor{29c0}@anchor{library/tarfile tarfile-extraction-refuse}@anchor{2978}
@subsubsection Filter errors


When a filter refuses to extract a file, it will raise an appropriate exception,
a subclass of @ref{2977,,FilterError}.
This will abort the extraction if @ref{2974,,TarFile.errorlevel} is 1 or more.
With @code{errorlevel=0} the error will be logged and the member will be skipped,
but extraction will continue.

@node Hints for further verification,Supporting older Python versions,Filter errors,Extraction filters
@anchor{library/tarfile hints-for-further-verification}@anchor{29c1}
@subsubsection Hints for further verification


Even with @code{filter='data'}, `tarfile' is not suited for extracting untrusted
files without prior inspection.
Among other issues, the pre-defined filters do not prevent denial-of-service
attacks. Users should do additional checks.

Here is an incomplete list of things to consider:


@itemize *

@item 
Extract to a @ref{21c,,new temporary directory}
to prevent e.g. exploiting pre-existing links, and to make it easier to
clean up after a failed extraction.

@item 
When working with untrusted data, use external (e.g. OS-level) limits on
disk, memory and CPU usage.

@item 
Check filenames against an allow-list of characters
(to filter out control characters, confusables, foreign path separators,
etc.).

@item 
Check that filenames have expected extensions (discouraging files that
execute when you “click on them”, or extension-less files like Windows special device names).

@item 
Limit the number of extracted files, total size of extracted data,
filename length (including symlink length), and size of individual files.

@item 
Check for files that would be shadowed on case-insensitive filesystems.
@end itemize

Also note that:


@itemize *

@item 
Tar files may contain multiple versions of the same file.
Later ones are expected to overwrite any earlier ones.
This feature is crucial to allow updating tape archives, but can be abused
maliciously.

@item 
`tarfile' does not protect against issues with “live” data,
e.g. an attacker tinkering with the destination (or source) directory while
extraction (or archiving) is in progress.
@end itemize

@node Supporting older Python versions,Stateful extraction filter example,Hints for further verification,Extraction filters
@anchor{library/tarfile supporting-older-python-versions}@anchor{29c2}
@subsubsection Supporting older Python versions


Extraction filters were added to Python 3.12, but may be backported to older
versions as security updates.
To check whether the feature is available, use e.g.
@code{hasattr(tarfile, 'data_filter')} rather than checking the Python version.

The following examples show how to support Python versions with and without
the feature.
Note that setting @code{extraction_filter} will affect any subsequent operations.


@itemize *

@item 
Fully trusted archive:

@example
my_tarfile.extraction_filter = (lambda member, path: member)
my_tarfile.extractall()
@end example

@item 
Use the @code{'data'} filter if available, but revert to Python 3.11 behavior
(@code{'fully_trusted'}) if this feature is not available:

@example
my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (lambda member, path: member))
my_tarfile.extractall()
@end example

@item 
Use the @code{'data'} filter; `fail' if it is not available:

@example
my_tarfile.extractall(filter=tarfile.data_filter)
@end example

ou :

@example
my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()
@end example

@item 
Use the @code{'data'} filter; `warn' if it is not available:

@example
if hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
else:
    # remove this when no longer needed
    warn_the_user('Extracting may be unsafe; consider updating Python')
    my_tarfile.extractall()
@end example
@end itemize

@node Stateful extraction filter example,,Supporting older Python versions,Extraction filters
@anchor{library/tarfile stateful-extraction-filter-example}@anchor{29c3}
@subsubsection Stateful extraction filter example


While `tarfile''s extraction methods take a simple `filter' callable,
custom filters may be more complex objects with an internal state.
It may be useful to write these as context managers, to be used like this:

@example
with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)
@end example

Such a filter can be written as, for example:

@example
class StatefulFilter:
    def __init__(self):
        self.file_count = 0

    def __enter__(self):
        return self

    def __call__(self, member, path):
        self.file_count += 1
        return member

    def __exit__(self, *exc_info):
        print(f'@{self.file_count@} files extracted')
@end example

@node Interface en ligne de commande<3>,Exemples<9>,Extraction filters,tarfile --- Read and write tar archive files
@anchor{library/tarfile command-line-interface}@anchor{29c4}@anchor{library/tarfile tarfile-commandline}@anchor{fb6}
@subsubsection Interface en ligne de commande



Ajouté dans la version 3.4.


Le module @ref{dd,,tarfile} fournit une interface de ligne de commande simple pour interagir avec les archives `tar'.

Si vous souhaitez créer une nouvelle archive `tar', spécifiez son nom après l'option @ref{29c5,,-c}, puis répertorie-le ou les noms de fichiers à inclure :

@example
$ python -m tarfile -c monty.tar  spam.txt eggs.txt
@end example

Passer un répertoire est aussi possible :

@example
$ python -m tarfile -c monty.tar life-of-brian_1979/
@end example

Si vous souhaitez extraire une archive `tar' dans le répertoire courant, utilisez l'option @ref{29c6,,-e} :

@example
$ python -m tarfile -e monty.tar
@end example

Vous pouvez également extraire une archive `tar' dans un autre répertoire en passant le nom du répertoire :

@example
$ python -m tarfile -e monty.tar  other-dir/
@end example

Pour une liste des fichiers dans une archive `tar', utilisez l'option @ref{29c7,,-l} :

@example
$ python -m tarfile -l monty.tar
@end example

@menu
* Options de la ligne de commande: Options de la ligne de commande<3>. 

@end menu

@node Options de la ligne de commande<3>,,,Interface en ligne de commande<3>
@anchor{library/tarfile command-line-options}@anchor{29c8}
@subsubsection Options de la ligne de commande


@geindex option de ligne de commande tarfile; -l
@geindex option de ligne de commande tarfile; --list
@anchor{library/tarfile cmdoption-tarfile-l}@anchor{29c7}
@deffn {Option} @w{-}l <tarfile>
@anchor{library/tarfile cmdoption-tarfile-list}@anchor{29c9}
@deffnx {Option} @w{-}@w{-}list <tarfile>

Liste les fichiers dans une archive `tar'.
@end deffn

@geindex option de ligne de commande tarfile; -c
@geindex option de ligne de commande tarfile; --create
@anchor{library/tarfile cmdoption-tarfile-c}@anchor{29c5}
@deffn {Option} @w{-}c <tarfile> <source1> ... <sourceN>
@anchor{library/tarfile cmdoption-tarfile-create}@anchor{29ca}
@deffnx {Option} @w{-}@w{-}create <tarfile> <source1> ... <sourceN>

Crée une archive `tar' à partir des fichiers sources.
@end deffn

@geindex option de ligne de commande tarfile; -e
@geindex option de ligne de commande tarfile; --extract
@anchor{library/tarfile cmdoption-tarfile-e}@anchor{29c6}
@deffn {Option} @w{-}e <tarfile> [<output_dir>]
@anchor{library/tarfile cmdoption-tarfile-extract}@anchor{29cb}
@deffnx {Option} @w{-}@w{-}extract <tarfile> [<output_dir>]

Extrait l'archive `tar' dans le répertoire courant si `output_dir' n'est pas spécifié.
@end deffn

@geindex option de ligne de commande tarfile; -t
@geindex option de ligne de commande tarfile; --test
@anchor{library/tarfile cmdoption-tarfile-t}@anchor{29cc}
@deffn {Option} @w{-}t <tarfile>
@anchor{library/tarfile cmdoption-tarfile-test}@anchor{29cd}
@deffnx {Option} @w{-}@w{-}test <tarfile>

Teste si l'archive `tar' est valide ou non.
@end deffn

@geindex option de ligne de commande tarfile; -v
@geindex option de ligne de commande tarfile; --verbose
@anchor{library/tarfile cmdoption-tarfile-v}@anchor{29ce}@anchor{library/tarfile cmdoption-tarfile-verbose}@anchor{29cf}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

Sortie verbeuse.
@end deffn

@geindex option de ligne de commande tarfile; --filter
@anchor{library/tarfile cmdoption-tarfile-filter}@anchor{29d0}
@deffn {Option} @w{-}@w{-}filter <filtername>

Specifies the `filter' for @code{--extract}.
See @ref{456,,Extraction filters} for details.
Only string names are accepted (that is, @code{fully_trusted}, @code{tar},
and @code{data}).
@end deffn

@node Exemples<9>,Formats tar pris en charge,Interface en ligne de commande<3>,tarfile --- Read and write tar archive files
@anchor{library/tarfile examples}@anchor{29d1}@anchor{library/tarfile tar-examples}@anchor{2970}
@subsubsection Exemples


Comment extraire une archive `tar' dans le dossier de travail courant :

@example
import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()
@end example

Comment extraire un sous-ensemble d'une archive `tar' avec @ref{e61,,TarFile.extractall()} en utilisant une fonction de générateur au lieu d'une liste :

@example
import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()
@end example

Comment créer une archive `tar' non compressée à partir d'une liste de noms de fichiers :

@example
import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()
@end example

Le même exemple en utilisant l'instruction @ref{5bc,,with} :

@example
import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)
@end example

Comment lire une archive `tar' compressée avec `gzip' et afficher des informations des membres :

@example
import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()
@end example

Comment créer une archive et réinitialiser les informations de l'utilisateur en utilisant le paramètre `filter' dans @ref{be1,,TarFile.add()} :

@example
import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()
@end example

@node Formats tar pris en charge,Problèmes unicode,Exemples<9>,tarfile --- Read and write tar archive files
@anchor{library/tarfile supported-tar-formats}@anchor{29d2}@anchor{library/tarfile tar-formats}@anchor{298e}
@subsubsection Formats `tar' pris en charge


Il existe trois formats `tar' qui peuvent être créés avec le module @ref{dd,,tarfile} :


@itemize *

@item 
Le format `POSIX.1-1988' `ustar' (@code{ustar_FORMAT}). Il prend en charge les noms de fichiers jusqu'à une longueur maximale de 256 caractères et les noms de liens jusqu'à 100 caractères. La taille maximale du fichier est de 8 Go. Il s'agit d'un format ancien et limité mais largement pris en charge.

@item 
Le format GNU `tar' (@ref{2990,,GNU_FORMAT}). Il prend en charge les noms de fichiers longs et les noms de liens, les fichiers supérieurs à 8 Go et les fichiers discontinus. C'est la norme de facto des systèmes GNU / Linux. @ref{dd,,tarfile} prend entièrement en charge les extensions GNU `tar' pour les noms longs, la prise en charge des fichiers discontinus est en lecture seule.

@item 
The POSIX.1-2001 pax format (@ref{2991,,PAX_FORMAT}). It is the most flexible
format with virtually no limits. It supports long filenames and linknames, large
files and stores pathnames in a portable way. Modern tar implementations,
including GNU tar, bsdtar/libarchive and star, fully support extended `pax'
features; some old or unmaintained libraries may not, but should treat
`pax' archives as if they were in the universally supported `ustar' format.
It is the current default format for new archives.

Il étend le format `ustar' existant avec des en-têtes supplémentaires pour les informations qui ne peuvent pas être stockées autrement. Il existe deux types d'en-têtes `pax' : les en-têtes étendus n'affectent que l'en-tête de fichier suivant, les en-têtes globaux sont valides pour l'archive complète et affectent tous les fichiers suivants. Toutes les données d'un en-tête `pax' sont encodées en `UTF-8' pour des raisons de portabilité.
@end itemize

Il existe d'autres variantes du format `tar' qui peuvent être lues, mais pas créées :


@itemize *

@item 
L'ancien format `V7'. Il s'agit du premier format `tar' d'`Unix Seventh Edition', ne stockant que des fichiers et répertoires normaux. Les noms ne doivent pas dépasser 100 caractères, il n'y a aucune information de nom d'utilisateur / groupe. Certaines archives ont des sommes de contrôle d'en-tête mal calculées dans le cas de champs avec des caractères non ASCII.

@item 
Format étendu `SunOS' `tar'. Ce format est une variante du format `POSIX.1-2001' `pax', mais n'est pas compatible.
@end itemize

@node Problèmes unicode,,Formats tar pris en charge,tarfile --- Read and write tar archive files
@anchor{library/tarfile tar-unicode}@anchor{2994}@anchor{library/tarfile unicode-issues}@anchor{29d3}
@subsubsection Problèmes `unicode'


Le format `tar' a été initialement conçu pour effectuer des sauvegardes sur des lecteurs de bande en mettant principalement l'accent sur la préservation des informations du système de fichiers. De nos jours, les archives `tar' sont couramment utilisées pour la distribution de fichiers et l'échange d'archives sur des réseaux. Un problème du format d'origine (qui est la base de tous les autres formats) est qu'il n'existe aucun concept de prise en charge d'encodages de caractères différents. Par exemple, une archive `tar' ordinaire créée sur un système `UTF-8' ne peut pas être lue correctement sur un système `Latin-1' si elle contient des caractères non `ASCII'. Les métadonnées textuelles (comme les noms de fichiers, les noms de liens, les noms d'utilisateurs / de groupes) sembleront endommagées. Malheureusement, il n'y a aucun moyen de détecter automatiquement l'encodage d'une archive. Le format `pax' a été conçu pour résoudre ce problème. Il stocke les métadonnées non ASCII en utilisant l'encodage universel des caractères `UTF-8'.

Les détails de la conversion des caractères dans @ref{dd,,tarfile} sont contrôlés par les arguments nommés `encoding' et `errors' de la classe @ref{11ed,,TarFile}.

`encoding' définit l'encodage de caractères à utiliser pour les métadonnées de l'archive. La valeur par défaut est @ref{c47,,sys.getfilesystemencoding()} ou @code{'ascii'} comme solution de rechange. Selon que l'archive est lue ou écrite, les métadonnées doivent être décodées ou encodées. Si l'encodage n'est pas défini correctement, cette conversion peut échouer.

L'argument `errors' définit le traitement des caractères qui ne peuvent pas être convertis. Les valeurs possibles sont répertoriées dans la section @ref{1774,,Gestionnaires d'erreurs}. Le schéma par défaut est @code{'surrogateescape'} que Python utilise également pour ses appels de système de fichiers, voir @ref{29d4,,Noms de fichiers@comma{} arguments en ligne de commande@comma{} et variables d'environnement}.

Pour les archives @ref{2991,,PAX_FORMAT} (par défaut), l'encodage n'est généralement pas nécessaire car toutes les métadonnées sont stockées à l'aide de `UTF-8'. L'encodage n'est utilisé que dans les rares cas où les en-têtes `pax' binaires sont décodés ou lorsque les chaînes avec des caractères de substitution sont stockées.

@node Formats de fichiers,Service de cryptographie,Compression de donnée et archivage,La bibliothèque standard
@anchor{library/fileformats doc}@anchor{29d5}@anchor{library/fileformats file-formats}@anchor{29d6}@anchor{library/fileformats fileformats}@anchor{29d7}
@section Formats de fichiers


Les modules décrits dans ce chapitre lisent divers formats de fichier qui ne sont ni des langages balisés ni relatifs aux e-mails.

@menu
* csv: csv --- CSV File Reading and Writing. CSV File Reading and Writing
* configparser: configparser --- Configuration file parser. Configuration file parser
* tomllib: tomllib --- Parse TOML files. Parse TOML files
* netrc: netrc --- netrc file processing. netrc file processing
* plistlib: plistlib --- Generate and parse Apple plist files. Generate and parse Apple .plist files

@end menu

@node csv --- CSV File Reading and Writing,configparser --- Configuration file parser,,Formats de fichiers
@anchor{library/csv doc}@anchor{29d8}@anchor{library/csv csv-csv-file-reading-and-writing}@anchor{29d9}@anchor{library/csv module-csv}@anchor{29}
@subsection @code{csv} --- CSV File Reading and Writing


@geindex module; csv

`Code source :' Lib/csv.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/csv.py}

@geindex csv
@geindex data;tabular


__________________________________________________________________


Le format CSV (`Comma Separated Values', valeurs séparées par des virgules) est le format le plus commun dans l'importation et l'exportation de feuilles de calculs et de bases de données.  Le format fut utilisé pendant des années avant qu'aient lieu des tentatives de standardisation avec la 
@geindex RFC; RFC 4180
RFC 4180@footnote{https://datatracker.ietf.org/doc/html/rfc4180.html}.  L'absence de format bien défini signifie que des différences subtiles existent dans la production et la consommation de données par différentes applications.  Ces différences peuvent gêner lors du traitement de fichiers CSV depuis des sources multiples. Cependant, bien que les séparateurs et délimiteurs varient, le format global est suffisamment similaire pour qu'un module unique puisse manipuler efficacement ces données, masquant au programmeur les détails de lecture/écriture des données.

Le module @ref{29,,csv} implémente des classes pour lire et écrire des données tabulaires au format CSV.  Il vous permet de dire « écris ces données dans le format préféré par Excel » ou « lis les données de ce fichier généré par Excel », sans connaître les détails précis du format CSV utilisé par Excel.  Vous pouvez aussi décrire les formats CSV utilisés par d'autres applications ou définir vos propres spécialisations.

Les objets @ref{470,,reader} et @ref{471,,writer} du module @ref{29,,csv} lisent et écrivent des séquences.  Vous pouvez aussi lire/écrire les données dans un dictionnaire en utilisant les classes @ref{9d3,,DictReader} et @ref{11db,,DictWriter}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 305

@item PEP 305@footnote{https://peps.python.org/pep-0305/} ­— Interface des fichiers CSV

La proposition d'amélioration de Python (PEP) qui a proposé cet ajout au langage.
@end table


@menu
* Contenu du module: Contenu du module<3>. 
* Dialectes et paramètres de formatage:: 
* Objets lecteurs:: 
* Objets transcripteurs:: 
* Exemples: Exemples<10>. 

@end menu

@node Contenu du module<3>,Dialectes et paramètres de formatage,,csv --- CSV File Reading and Writing
@anchor{library/csv csv-contents}@anchor{29da}@anchor{library/csv module-contents}@anchor{29db}
@subsubsection Contenu du module


Le module @ref{29,,csv} définit les fonctions suivantes :

@geindex universal newlines;csv.reader function

@geindex reader() (dans le module csv)
@anchor{library/csv csv reader}@anchor{470}
@deffn {Fonction} csv.reader (csvfile, dialect='excel', **fmtparams)

Return a @ref{29dc,,reader object} that will process
lines from the given `csvfile'.  A csvfile must be an iterable of
strings, each in the reader's defined csv format.
A csvfile is most commonly a file-like object or list.
If `csvfile' is a file object,
it should be opened with @code{newline='@w{'}}. @footnote{
Si @code{newline='@w{'}} n'est pas précisé, les caractères de fin de ligne embarqués dans des champs délimités par des guillemets ne seront pas interprétés correctement, et sur les plateformes qui utilisent @code{\r\n} comme marqueur de fin de ligne, un @code{\r} sera ajouté. Il devrait toujours être sûr de préciser @code{newline='@w{'}}, puisque le module `csv' gère lui-même les fins de lignes (@ref{d28,,universelles}).
}  An optional
`dialect' parameter can be given which is used to define a set of parameters
specific to a particular CSV dialect.  It may be an instance of a subclass of
the @ref{1604,,Dialect} class or one of the strings returned by the
@ref{1797,,list_dialects()} function.  The other optional `fmtparams' keyword arguments
can be given to override individual formatting parameters in the current
dialect.  For full details about the dialect and formatting parameters, see
section @ref{29dd,,Dialectes et paramètres de formatage}.

Chaque ligne lue depuis le fichier CSV est renvoyée comme une liste de chaînes de caractères.  Aucune conversion automatique de type des données n'est effectuée à moins que l'option de formatage @code{QUOTE_NONNUMERIC} soit spécifiée (dans ce cas, les champs sans guillemets sont transformés en nombres flottants).

Un court exemple d'utilisation :

@example
>>> import csv
>>> with open('eggs.csv', newline='@w{'}) as csvfile:
...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
...     for row in spamreader:
...         print(', '.join(row))
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam
@end example
@end deffn

@geindex writer() (dans le module csv)
@anchor{library/csv csv writer}@anchor{471}
@deffn {Fonction} csv.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
@ref{1c02,,write()} method.  If `csvfile' is a file object, it should be opened with
@code{newline='@w{'}} @footnote{
Si @code{newline='@w{'}} n'est pas précisé, les caractères de fin de ligne embarqués dans des champs délimités par des guillemets ne seront pas interprétés correctement, et sur les plateformes qui utilisent @code{\r\n} comme marqueur de fin de ligne, un @code{\r} sera ajouté. Il devrait toujours être sûr de préciser @code{newline='@w{'}}, puisque le module `csv' gère lui-même les fins de lignes (@ref{d28,,universelles}).
}.  An optional `dialect'
parameter can be given which is used to define a set of parameters specific to a
particular CSV dialect.  It may be an instance of a subclass of the
@ref{1604,,Dialect} class or one of the strings returned by the
@ref{1797,,list_dialects()} function.  The other optional `fmtparams' keyword arguments
can be given to override individual formatting parameters in the current
dialect.  For full details about dialects and formatting parameters, see
the @ref{29dd,,Dialectes et paramètres de formatage} section. To make it
as easy as possible to interface with modules which implement the DB API, the
value @ref{660,,None} is written as the empty string.  While this isn't a
reversible transformation, it makes it easier to dump SQL NULL data values to
CSV files without preprocessing the data returned from a @code{cursor.fetch*} call.
All other non-string data are stringified with @ref{435,,str()} before being written.

Un court exemple d'utilisation :

@example
import csv
with open('eggs.csv', 'w', newline='@w{'}) as csvfile:
    spamwriter = csv.writer(csvfile, delimiter=' ',
                            quotechar='|', quoting=csv.QUOTE_MINIMAL)
    spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
    spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
@end example
@end deffn

@geindex register_dialect() (dans le module csv)
@anchor{library/csv csv register_dialect}@anchor{29de}
@deffn {Fonction} csv.register_dialect (name[, dialect[, **fmtparams]])

Associe `dialect' avec `name'.  `name' doit être une chaîne de caractères. Le dialecte peut être spécifié en passant une instance d'une sous-classe de @ref{1604,,Dialect}, des arguments nommés `fmtparams', ou les deux, avec les arguments nommés redéfinissant les paramètres du dialecte. Pour tous les détails sur les dialectes et paramètres de formatage, voir la section @ref{29dd,,Dialectes et paramètres de formatage}.
@end deffn

@geindex unregister_dialect() (dans le module csv)
@anchor{library/csv csv unregister_dialect}@anchor{1796}
@deffn {Fonction} csv.unregister_dialect (name)

Supprime le dialecte associé à `name' depuis le registre des dialectes.  Une @ref{29df,,Error} est levée si `name' n'est pas un nom de dialecte enregistré.
@end deffn

@geindex get_dialect() (dans le module csv)
@anchor{library/csv csv get_dialect}@anchor{1795}
@deffn {Fonction} csv.get_dialect (name)

Renvoie le dialecte associé à `name'.  Une @ref{29df,,Error} est levée si `name' n'est pas un nom de dialecte enregistré.  Cette fonction renvoie un objet @ref{1604,,Dialect} immuable.
@end deffn

@geindex list_dialects() (dans le module csv)
@anchor{library/csv csv list_dialects}@anchor{1797}
@deffn {Fonction} csv.list_dialects ()

Renvoie les noms de tous les dialectes enregistrés.
@end deffn

@geindex field_size_limit() (dans le module csv)
@anchor{library/csv csv field_size_limit}@anchor{1794}
@deffn {Fonction} csv.field_size_limit ([new_limit])

Renvoie la taille de champ maximale actuelle autorisée par l'analyseur. Si `new_limit' est donnée, elle devient la nouvelle limite.
@end deffn

Le module @ref{29,,csv} définit les classes suivantes :

@geindex DictReader (classe dans csv)
@anchor{library/csv csv DictReader}@anchor{9d3}
@deffn {Classe} csv.DictReader (f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

Crée un objet qui opère comme un lecteur ordinaire mais assemble les informations de chaque ligne dans un @ref{253,,dict} dont les clés sont données par le paramètre optionnel `fieldnames'.

The `fieldnames' parameter is a @ref{4db,,sequence}.  If `fieldnames' is
omitted, the values in the first row of file `f' will be used as the
fieldnames and will be omitted from the results. If
`fieldnames' is provided, they will be used and the first row will be
included in the results.  Regardless of how the fieldnames are determined,
the dictionary preserves their original ordering.

Si une ligne a plus de champs que `fieldnames', les données excédentaires sont mises dans une liste stockée dans le champ spécifié par `restkey' (@code{None} par défaut).  Si une ligne non-vide a moins de champs que `fieldnames', les valeurs manquantes sont remplacées par la valeur de `restval' (@code{None} par défaut).

Tous les autres arguments optionnels ou nommés sont passés à l'instance @ref{470,,reader} sous-jacente.

If the argument passed to `fieldnames' is an iterator, it will be coerced to a @ref{5fc,,list}.


Modifié dans la version 3.6: Les lignes renvoyées sont maintenant de type @code{OrderedDict}.



Modifié dans la version 3.8: Les lignes renvoyées sont maintenant de type @ref{253,,dict}.


Un court exemple d'utilisation :

@example
>>> import csv
>>> with open('names.csv', newline='@w{'}) as csvfile:
...     reader = csv.DictReader(csvfile)
...     for row in reader:
...         print(row['first_name'], row['last_name'])
...
Eric Idle
John Cleese

>>> print(row)
@{'first_name': 'John', 'last_name': 'Cleese'@}
@end example
@end deffn

@geindex DictWriter (classe dans csv)
@anchor{library/csv csv DictWriter}@anchor{11db}
@deffn {Classe} csv.DictWriter (f, fieldnames, restval='@w{'}, extrasaction='raise', dialect='excel', *args, **kwds)

Create an object which operates like a regular writer but maps dictionaries
onto output rows.  The `fieldnames' parameter is a @ref{1e,,sequence} of keys that identify the order in which values in the
dictionary passed to the @ref{dd7,,writerow()} method are written to file
`f'.  The optional `restval' parameter specifies the value to be
written if the dictionary is missing a key in `fieldnames'.  If the
dictionary passed to the @ref{dd7,,writerow()} method contains a key not found in
`fieldnames', the optional `extrasaction' parameter indicates what action to
take.
If it is set to @code{'raise'}, the default value, a @ref{1ff,,ValueError}
is raised.
If it is set to @code{'ignore'}, extra values in the dictionary are ignored.
Any other optional or keyword arguments are passed to the underlying
@ref{471,,writer} instance.

Notez que contrairement à la classe @ref{9d3,,DictReader}, le paramètre `fieldnames' de @ref{11db,,DictWriter} n'est pas optionnel.

If the argument passed to `fieldnames' is an iterator, it will be coerced to a @ref{5fc,,list}.

Un court exemple d'utilisation :

@example
import csv

with open('names.csv', 'w', newline='@w{'}) as csvfile:
    fieldnames = ['first_name', 'last_name']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

    writer.writeheader()
    writer.writerow(@{'first_name': 'Baked', 'last_name': 'Beans'@})
    writer.writerow(@{'first_name': 'Lovely', 'last_name': 'Spam'@})
    writer.writerow(@{'first_name': 'Wonderful', 'last_name': 'Spam'@})
@end example
@end deffn

@geindex Dialect (classe dans csv)
@anchor{library/csv csv Dialect}@anchor{1604}
@deffn {Classe} csv.Dialect

La classe @ref{1604,,Dialect} est une classe dont les attributs contiennent des informations sur la façon de gérer les guillemets, les espaces, les délimiteurs, etc. En raison de l’absence d’une spécification CSV stricte, différentes applications produisent des données CSV subtilement différentes. Les instances @ref{1604,,Dialect} définissent le comportement des instances @ref{470,,reader} et @ref{471,,writer}.

Tous les noms disponibles de @ref{1604,,Dialect} sont renvoyés par @ref{1797,,list_dialects()}, et ils peuvent être enregistrés avec des classes @ref{470,,reader} et @ref{471,,writer} spécifiques en passant par leur fonction d’initialisation (@code{__init__}) comme ici :

@example
import csv

with open('students.csv', 'w', newline='@w{'}) as csvfile:
    writer = csv.writer(csvfile, dialect='unix')
@end example
@end deffn

@geindex excel (classe dans csv)
@anchor{library/csv csv excel}@anchor{29e0}
@deffn {Classe} csv.excel

La classe @ref{29e0,,excel} définit les propriétés usuelles d'un fichier CSV généré par Excel.  Elle est enregistrée avec le nom de dialecte @code{'excel'}.
@end deffn

@geindex excel_tab (classe dans csv)
@anchor{library/csv csv excel_tab}@anchor{29e1}
@deffn {Classe} csv.excel_tab

La classe @ref{29e1,,excel_tab} définit les propriétés usuelles d'un fichier CSV généré par Excel avec des tabulations comme séparateurs.  Elle est enregistrée avec le nom de dialecte @code{'excel-tab'}.
@end deffn

@geindex unix_dialect (classe dans csv)
@anchor{library/csv csv unix_dialect}@anchor{11da}
@deffn {Classe} csv.unix_dialect

La classe @ref{11da,,unix_dialect} définit les propriétés usuelles d'un fichier CSV généré sur un système Unix, c'est-à-dire utilisant @code{'\n'} comme marqueur de fin de ligne et délimitant tous les champs par des guillemets.  Elle est enregistrée avec le nom de dialecte @code{'unix'}.


Ajouté dans la version 3.2.

@end deffn

@geindex Sniffer (classe dans csv)
@anchor{library/csv csv Sniffer}@anchor{29e2}
@deffn {Classe} csv.Sniffer

La classe @ref{29e2,,Sniffer} est utilisée pour déduire le format d'un fichier CSV.

La classe @ref{29e2,,Sniffer} fournit deux méthodes :

@geindex sniff() (méthode csv.Sniffer)
@anchor{library/csv csv Sniffer sniff}@anchor{29e3}
@deffn {Méthode} sniff (sample, delimiters=None)

Analyse l'extrait donné (`sample') et renvoie une sous-classe @ref{1604,,Dialect} reflétant les paramètres trouvés.  Si le paramètre optionnel `delimiters' est donné, il est interprété comme une chaîne contenant tous les caractères valides de séparation possibles.
@end deffn

@geindex has_header() (méthode csv.Sniffer)
@anchor{library/csv csv Sniffer has_header}@anchor{1830}
@deffn {Méthode} has_header (sample)

Analyse l'extrait de texte (présumé être au format CSV) et renvoie @ref{bfb,,True} si la première ligne semble être une série d'en-têtes de colonnes. En inspectant chaque colonne, l’un des deux critères clés sera pris en compte pour estimer si l’échantillon contient un en-tête :


@itemize -

@item 
les deuxième à n-ième lignes contiennent des valeurs numériques

@item 
les deuxième à n-ième lignes contiennent des chaînes dont la longueur d’au moins une valeur diffère de celle de l’en-tête putatif de cette colonne.
@end itemize

L'échantillon est composé des vingt lignes après la première ligne ; si plus de la moitié des colonnes + lignes répondent aux critères, @ref{bfb,,True} est renvoyé.
@end deffn

@cartouche
@quotation Note 
Cette méthode est une heuristique discutable et peut produire tant des faux-positifs que des faux-négatifs.
@end quotation
@end cartouche
@end deffn

Un exemple d'utilisation de @ref{29e2,,Sniffer} :

@example
with open('example.csv', newline='@w{'}) as csvfile:
    dialect = csv.Sniffer().sniff(csvfile.read(1024))
    csvfile.seek(0)
    reader = csv.reader(csvfile, dialect)
    # ... process CSV file contents here ...
@end example
@anchor{library/csv csv-constants}@anchor{29e4}
Le module @ref{29,,csv} définit les constantes suivantes :

@geindex QUOTE_ALL (dans le module csv)
@anchor{library/csv csv QUOTE_ALL}@anchor{29e5}
@deffn {Données} csv.QUOTE_ALL

Indique aux objets @ref{471,,writer} de délimiter tous les champs par des guillemets.
@end deffn

@geindex QUOTE_MINIMAL (dans le module csv)
@anchor{library/csv csv QUOTE_MINIMAL}@anchor{29e6}
@deffn {Données} csv.QUOTE_MINIMAL

Indique aux objets @ref{471,,writer} de ne délimiter ainsi que les champs contenant un caractère spécial comme `delimiter', `quotechar' ou n'importe quel caractère de `lineterminator'.
@end deffn

@geindex QUOTE_NONNUMERIC (dans le module csv)
@anchor{library/csv csv QUOTE_NONNUMERIC}@anchor{1574}
@deffn {Données} csv.QUOTE_NONNUMERIC

Indique aux objets @ref{471,,writer} de délimiter ainsi tous les champs non-numériques.

Instructs @ref{470,,reader} objects to convert all non-quoted fields to type `float'.
@end deffn

@geindex QUOTE_NONE (dans le module csv)
@anchor{library/csv csv QUOTE_NONE}@anchor{29e7}
@deffn {Données} csv.QUOTE_NONE

Indique aux objets @ref{471,,writer} de ne jamais délimiter les champs par des guillemets.  Quand le `delimiter' utilisé apparaît dans les données, il est précédé sur la sortie par un caractère `escapechar'.  Si `escapechar' n'est pas précisé, le transcripteur lèvera une @ref{29df,,Error} si un caractère nécessitant un échappement est rencontré.

Instructs @ref{470,,reader} objects to perform no special processing of quote characters.
@end deffn

@geindex QUOTE_NOTNULL (dans le module csv)
@anchor{library/csv csv QUOTE_NOTNULL}@anchor{46e}
@deffn {Données} csv.QUOTE_NOTNULL

Instructs @ref{471,,writer} objects to quote all fields which are not
@code{None}.  This is similar to @ref{29e5,,QUOTE_ALL}, except that if a
field value is @code{None} an empty (unquoted) string is written.

Instructs @ref{470,,reader} objects to interpret an empty (unquoted) field
as @code{None} and to otherwise behave as @ref{29e5,,QUOTE_ALL}.


Ajouté dans la version 3.12.

@end deffn

@geindex QUOTE_STRINGS (dans le module csv)
@anchor{library/csv csv QUOTE_STRINGS}@anchor{46f}
@deffn {Données} csv.QUOTE_STRINGS

Instructs @ref{471,,writer} objects to always place quotes around fields
which are strings.  This is similar to @ref{1574,,QUOTE_NONNUMERIC}, except that if a
field value is @code{None} an empty (unquoted) string is written.

Instructs @ref{470,,reader} objects to interpret an empty (unquoted) string as @code{None} and
to otherwise behave as @ref{1574,,QUOTE_NONNUMERIC}.


Ajouté dans la version 3.12.

@end deffn

Le module @ref{29,,csv} définit les exceptions suivantes :

@geindex Error
@anchor{library/csv csv Error}@anchor{29df}
@deffn {Exception} csv.Error

Levée par les fonctions du module quand une erreur détectée.
@end deffn

@node Dialectes et paramètres de formatage,Objets lecteurs,Contenu du module<3>,csv --- CSV File Reading and Writing
@anchor{library/csv csv-fmt-params}@anchor{29dd}@anchor{library/csv dialects-and-formatting-parameters}@anchor{29e8}
@subsubsection Dialectes et paramètres de formatage


To make it easier to specify the format of input and output records, specific
formatting parameters are grouped together into dialects.  A dialect is a
subclass of the @ref{1604,,Dialect} class containing various attributes
describing the format of the CSV file.  When creating @ref{470,,reader} or
@ref{471,,writer} objects, the programmer can specify a string or a subclass of
the @ref{1604,,Dialect} class as the dialect parameter.  In addition to, or instead
of, the `dialect' parameter, the programmer can also specify individual
formatting parameters, which have the same names as the attributes defined below
for the @ref{1604,,Dialect} class.

Les dialectes supportent les attributs suivants :

@geindex delimiter (attribut csv.Dialect)
@anchor{library/csv csv Dialect delimiter}@anchor{29e9}
@deffn {Attribut} Dialect.delimiter

Une chaîne d'un seul caractère utilisée pour séparer les champs.  Elle vaut @code{','} par défaut.
@end deffn

@geindex doublequote (attribut csv.Dialect)
@anchor{library/csv csv Dialect doublequote}@anchor{29ea}
@deffn {Attribut} Dialect.doublequote

Contrôle comment les caractères `quotechar' dans le champ doivent être retranscrits.  Quand ce paramètre vaut @ref{bfb,,True}, le caractère est doublé. Quand il vaut @ref{b25,,False}, le caractère `escapechar' est utilisé comme préfixe à `quotechar'.  Il vaut @ref{bfb,,True} par défaut.

En écriture, si `doublequote' vaut @ref{b25,,False} et qu'aucun `escapechar' n'est précisé, une @ref{29df,,Error} est levée si un `quotechar' est trouvé dans le champ.
@end deffn

@geindex escapechar (attribut csv.Dialect)
@anchor{library/csv csv Dialect escapechar}@anchor{29eb}
@deffn {Attribut} Dialect.escapechar

Une chaîne d'un seul caractère utilisée par le transcripteur pour échapper `delimiter' si `quoting' vaut @ref{29e7,,QUOTE_NONE}, et pour échapper `quotechar' si `doublequote' vaut @ref{b25,,False}. À la lecture, `escapechar' retire toute signification spéciale au caractère qui le suit. Elle vaut par défaut @ref{660,,None}, ce qui désactive l'échappement.


Modifié dans la version 3.11: Un @code{escapechar} vide n'est pas autorisé.

@end deffn

@geindex lineterminator (attribut csv.Dialect)
@anchor{library/csv csv Dialect lineterminator}@anchor{29ec}
@deffn {Attribut} Dialect.lineterminator

La chaîne utilisée pour terminer les lignes produites par un @ref{471,,writer}. Elle vaut par défaut @code{'\r\n'}.

@cartouche
@quotation Note 
La classe @ref{470,,reader} est codée en dur pour reconnaître @code{'\r'} et @code{'\n'} comme marqueurs de fin de ligne, et ignorer `lineterminator'. Ce comportement pourrait changer dans le futur.
@end quotation
@end cartouche
@end deffn

@geindex quotechar (attribut csv.Dialect)
@anchor{library/csv csv Dialect quotechar}@anchor{29ed}
@deffn {Attribut} Dialect.quotechar

Une chaîne d'un seul caractère utilisée pour délimiter les champs contenant des caractères spéciaux, comme `delimiter' ou `quotechar', ou contenant un caractère de fin de ligne.  Elle vaut @code{'"'} par défaut.


Modifié dans la version 3.11: Un @code{quotechar} vide n'est pas autorisé.

@end deffn

@geindex quoting (attribut csv.Dialect)
@anchor{library/csv csv Dialect quoting}@anchor{29ee}
@deffn {Attribut} Dialect.quoting

Controls when quotes should be generated by the writer and recognised by the
reader.  It can take on any of the @ref{29e4,,QUOTE_* constants}
and defaults to @ref{29e6,,QUOTE_MINIMAL}.
@end deffn

@geindex skipinitialspace (attribut csv.Dialect)
@anchor{library/csv csv Dialect skipinitialspace}@anchor{29ef}
@deffn {Attribut} Dialect.skipinitialspace

Quand il vaut @ref{bfb,,True}, les espaces suivant directement `delimiter' sont ignorés. Il vaut @ref{b25,,False} par défaut.
@end deffn

@geindex strict (attribut csv.Dialect)
@anchor{library/csv csv Dialect strict}@anchor{29f0}
@deffn {Attribut} Dialect.strict

Quand il vaut @code{True}, une exception @ref{29df,,Error} est levée lors de mauvaises entrées CSV. Il vaut @code{False} par défaut.
@end deffn

@node Objets lecteurs,Objets transcripteurs,Dialectes et paramètres de formatage,csv --- CSV File Reading and Writing
@anchor{library/csv id3}@anchor{29f1}@anchor{library/csv reader-objects}@anchor{29dc}
@subsubsection Objets lecteurs


Les objets lecteurs (instances de @ref{9d3,,DictReader} ou objets renvoyés par la fonction @ref{470,,reader()}) ont les méthodes publiques suivantes :

@geindex __next__() (méthode csv.csvreader)
@anchor{library/csv csv csvreader __next__}@anchor{29f2}
@deffn {Méthode} csvreader.__next__ ()

Renvoie la ligne suivante de l'objet itérable du lecteur en tant que liste (si l'objet est renvoyé depuis @ref{470,,reader()}) ou dictionnaire (si l'objet est un @ref{9d3,,DictReader}), analysé suivant la classe @ref{1604,,Dialect} utilisée. Généralement, vous devez appeler la méthode à l'aide de @code{next(reader)}.
@end deffn

Les objets lecteurs ont les attributs publics suivants :

@geindex dialect (attribut csv.csvreader)
@anchor{library/csv csv csvreader dialect}@anchor{29f3}
@deffn {Attribut} csvreader.dialect

Une description en lecture seule du dialecte utilisé par l'analyseur.
@end deffn

@geindex line_num (attribut csv.csvreader)
@anchor{library/csv csv csvreader line_num}@anchor{29f4}
@deffn {Attribut} csvreader.line_num

Le nombre de lignes lues depuis l'itérateur source. Ce n'est pas équivalent au nombre d'enregistrements renvoyés, puisque certains enregistrements peuvent s'étendre sur plusieurs lignes.
@end deffn

Les objets `DictReader' ont les attributs publics suivants :

@geindex fieldnames (attribut csv.DictReader)
@anchor{library/csv csv DictReader fieldnames}@anchor{29f5}
@deffn {Attribut} DictReader.fieldnames

S'il n'est pas passé comme paramètre à la création de l'objet, cet attribut est initialisé lors du premier accès ou quand le premier enregistrement est lu depuis le fichier.
@end deffn

@node Objets transcripteurs,Exemples<10>,Objets lecteurs,csv --- CSV File Reading and Writing
@anchor{library/csv writer-objects}@anchor{29f6}
@subsubsection Objets transcripteurs


@ref{471,,writer} objects (@ref{11db,,DictWriter} instances and objects returned by
the @ref{471,,writer()} function) have the following public methods.  A `row' must be
an iterable of strings or numbers for @ref{471,,writer} objects and a dictionary
mapping fieldnames to strings or numbers (by passing them through @ref{435,,str()}
first) for @ref{11db,,DictWriter} objects.  Note that complex numbers are written
out surrounded by parens. This may cause some problems for other programs which
read CSV files (assuming they support complex numbers at all).

@geindex writerow() (méthode csv.csvwriter)
@anchor{library/csv csv csvwriter writerow}@anchor{dd7}
@deffn {Méthode} csvwriter.writerow (row)

Écrit le paramètre `row' vers l’objet fichier du transcripteur, formaté selon la classe @ref{1604,,Dialect} utilisée. Renvoie la valeur de retour de l'appel à la méthode `write' de l'objet fichier sous-jacent.


Modifié dans la version 3.5: Ajout du support d'itérables arbitraires.

@end deffn

@geindex writerows() (méthode csv.csvwriter)
@anchor{library/csv csv csvwriter writerows}@anchor{29f7}
@deffn {Méthode} csvwriter.writerows (rows)

Écrit tous les éléments de `rows' (itérable d'objets `row' comme décrits précédemment) vers le fichier associé au transcripteur, formatés selon le dialecte utilisé.
@end deffn

Les objets transcripteurs ont l’attribut public suivant :

@geindex dialect (attribut csv.csvwriter)
@anchor{library/csv csv csvwriter dialect}@anchor{29f8}
@deffn {Attribut} csvwriter.dialect

Une description en lecture seule du dialecte utilisé par le transcripteur.
@end deffn

Les objets `DictWriter' ont la méthode publique suivante :

@geindex writeheader() (méthode csv.DictWriter)
@anchor{library/csv csv DictWriter writeheader}@anchor{11dc}
@deffn {Méthode} DictWriter.writeheader ()

Écrit une ligne avec le nom des en-têtes (comme définies dans le constructeur) dans l'objet fichier associé au transcripteur, formatée selon le dialecte utilisé. Renvoie la valeur de retour de l'appel @ref{dd7,,csvwriter.writerow()} utilisé en interne.


Ajouté dans la version 3.2.



Modifié dans la version 3.8: @ref{11dc,,writeheader()} renvoie maintenant aussi la valeur renvoyée par la méthode @ref{dd7,,csvwriter.writerow()} qu'il utilise en interne.

@end deffn

@node Exemples<10>,,Objets transcripteurs,csv --- CSV File Reading and Writing
@anchor{library/csv csv-examples}@anchor{29f9}@anchor{library/csv examples}@anchor{29fa}
@subsubsection Exemples


Le plus simple exemple de lecture d'un fichier CSV :

@example
import csv
with open('some.csv', newline='@w{'}) as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)
@end example

Lire un fichier avec un format alternatif :

@example
import csv
with open('passwd', newline='@w{'}) as f:
    reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
    for row in reader:
        print(row)
@end example

Le plus simple exemple d'écriture correspondant est :

@example
import csv
with open('some.csv', 'w', newline='@w{'}) as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)
@end example

Puisque @ref{505,,open()} est utilisée pour ouvrir un fichier CSV en lecture, le fichier sera par défaut décodé vers Unicode en utilisant l'encodage par défaut (voir @ref{2db,,locale.getencoding()}).  Pour décoder un fichier utilisant un encodage différent, utilisez l'argument @code{encoding} de `open' :

@example
import csv
with open('some.csv', newline='@w{'}, encoding='utf-8') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)
@end example

Cela s’applique également lors de l'écriture dans un autre encodage que celui par défaut du système : spécifiez l'encodage en argument lors de l'ouverture du fichier de sortie.

Enregistrer un nouveau dialecte :

@example
import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', newline='@w{'}) as f:
    reader = csv.reader(f, 'unixpwd')
@end example

Un exemple d'utilisation un peu plus avancé du lecteur --- attrapant et notifiant les erreurs :

@example
import csv, sys
filename = 'some.csv'
with open(filename, newline='@w{'}) as f:
    reader = csv.reader(f)
    try:
        for row in reader:
            print(row)
    except csv.Error as e:
        sys.exit('file @{@}, line @{@}: @{@}'.format(filename, reader.line_num, e))
@end example

Et bien que le module ne permette pas d'analyser directement des chaînes, cela peut être fait facilement :

@example
import csv
for row in csv.reader(['one,two,three']):
    print(row)
@end example

@subsubheading Notes


@node configparser --- Configuration file parser,tomllib --- Parse TOML files,csv --- CSV File Reading and Writing,Formats de fichiers
@anchor{library/configparser doc}@anchor{29fb}@anchor{library/configparser configparser-configuration-file-parser}@anchor{29fc}@anchor{library/configparser module-configparser}@anchor{22}
@subsection @code{configparser} --- Configuration file parser


@geindex module; configparser

`Code source :' Lib/configparser.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/configparser.py}

@geindex .ini;file
@geindex configuration;file
@geindex ini file
@geindex Windows ini file


__________________________________________________________________


Ce module fournit la classe @ref{1c3,,ConfigParser}. Cette classe implémente un langage de configuration basique, proche de ce que l'on peut trouver dans les fichiers `INI' de Microsoft Windows. Vous pouvez utiliser ce module pour écrire des programmes Python qui sont facilement configurables par l'utilisateur final.

@cartouche
@quotation Note 
Ce module `n'implémente pas' la version étendue de la syntaxe `INI' qui permet de lire ou d'écrire des valeurs dans la base de registre Windows en utilisant divers préfixes.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item Module @code{tomlib}

TOML est un format bien spécifié pour les fichiers de configuration d'application. Il est spécifiquement conçu pour être une version améliorée d'INI.

@item Module @ref{c3,,shlex}

Support for creating Unix shell-like mini-languages which can also
be used for application configuration files.

@item Module @ref{81,,json}

The @code{json} module implements a subset of JavaScript syntax which is
sometimes used for configuration, but does not support comments.
@end table


@c import configparser

@c import os
@c os.remove("example.ini")
@c os.remove("override.ini")

@menu
* Premiers pas:: 
* Types de données prises en charge:: 
* Valeurs de substitution:: 
* Structure des fichiers INI prise en change:: 
* Unnamed Sections:: 
* Interpolation des valeurs:: 
* Protocole d'accès associatif:: 
* Personnalisation du comportement de l'analyseur:: 
* Legacy API Examples:: 
* ConfigParser Objects:: 
* RawConfigParser Objects:: 
* Exceptions: Exceptions<8>. 

@end menu

@node Premiers pas,Types de données prises en charge,,configparser --- Configuration file parser
@anchor{library/configparser quick-start}@anchor{29fd}
@subsubsection Premiers pas


Prenons pour exemple un fichier de configuration très simple ressemblant à ceci :

@example
[DEFAULT]
ServerAliveInterval = 45
Compression = yes
CompressionLevel = 9
ForwardX11 = yes

[forge.example]
User = hg

[topsecret.server.example]
Port = 50022
ForwardX11 = no
@end example

La structure des fichiers `INI' est décrite dans la @ref{29fe,,section suivante}. En bref,  chaque fichier est constitué de sections, chacune des sections comprenant des clés associées à des valeurs. Les classes du module @ref{22,,configparser} peuvent écrire et lire de tels fichiers. Commençons par le code qui permet de générer le fichier ci-dessus.

@example
>>> import configparser
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = @{'ServerAliveInterval': '45',
...                      'Compression': 'yes',
...                      'CompressionLevel': '9'@}
>>> config['forge.example'] = @{@}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = @{@}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022'     # mutates the parser
>>> topsecret['ForwardX11'] = 'no'  # same here
>>> config['DEFAULT']['ForwardX11'] = 'yes'
>>> with open('example.ini', 'w') as configfile:
...   config.write(configfile)
...
@end example

Comme vous pouvez le voir, nous pouvons manipuler l'instance renvoyée par l'analyse du fichier de configuration comme s'il s'agissait d'un dictionnaire. Il y a des différences, comme @ref{29ff,,explicité ci-dessous}, mais le comportement de l'instance est très proche de ce que vous pourriez attendre d'un dictionnaire.

Nous venons de créer et sauvegarder un fichier de configuration. Voyons maintenant comment nous pouvons le lire et accéder aux données qu'il contient.

@example
>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' in config
True
>>> 'python.org' in config
False
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Compression']
'yes'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'no'
>>> topsecret['Port']
'50022'
>>> for key in config['forge.example']:  
...     print(key)
user
compressionlevel
serveraliveinterval
compression
forwardx11
>>> config['forge.example']['ForwardX11']
'yes'
@end example

Comme vous le voyez, l'API est assez simple à utiliser. La seule partie un peu magique concerne la section @code{DEFAULT}, qui fournit les valeurs par défaut pour toutes les autres sections @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}. Notez également que les clés à l’intérieur des sections ne sont pas sensibles à la casse et qu'elles sont stockées en minuscules. @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}.

Il est possible de lire plusieurs configurations dans un seul objet @ref{1c3,,ConfigParser}, où la configuration ajoutée la plus récemment a la priorité la plus élevée. Toutes les clés en conflit sont prises de la configuration la plus récente tandis que les anciennes clés déjà existantes sont mises de côté. L'exemple suivant lit un fichier @code{override.ini} qui prendra le dessus sur toutes les clés en conflit avec le fichier @code{exemple.ini}.

@example
[DEFAULT]
ServerAliveInterval = -1
@end example

@example
>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = @{'ServerAliveInterval': '-1'@}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1
@end example

Ce comportement est équivalent à un appel à @ref{141c,,ConfigParser.read()} avec plusieurs fichiers passés dans le paramètre `filenames'.

@node Types de données prises en charge,Valeurs de substitution,Premiers pas,configparser --- Configuration file parser
@anchor{library/configparser supported-datatypes}@anchor{2a01}
@subsubsection Types de données prises en charge


Les lecteurs de configuration n'essayent jamais de deviner le type des valeurs présentes dans les fichiers de configuration, et elles sont toujours stockées en tant que chaînes de caractères. Ainsi, si vous avez besoin d'un type différent, vous devez effectuer la conversion vous-même :

@example
>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9.0
@end example

Puisque que cette tâche doit être fréquemment accomplie, les lecteurs de configurations fournissent un ensemble d'accesseurs permettant de gérer les entiers, les flottants et les booléens plus facilement. Le cas des booléens est le plus pertinent. En effet, vous ne pouvez pas vous contenter d'utiliser la fonction @code{bool()} directement puisque @code{bool('False')} renvoie @code{True}. C'est pourquoi les lecteurs fournissent également la méthode @ref{2a02,,getboolean()}. Cette méthode n'est pas sensible à la casse et interprète correctement les valeurs booléennes associées aux chaînes de caractères comme @code{'yes'}-@code{'no'}, @code{'on'}-@code{'off'}, @code{'true'}-@code{'false'} et @code{'1'}-@code{'0'} @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}. Par exemple :

@example
>>> topsecret.getboolean('ForwardX11')
False
>>> config['forge.example'].getboolean('ForwardX11')
True
>>> config.getboolean('forge.example', 'Compression')
True
@end example

En plus de @ref{2a02,,getboolean()}, les lecteurs de configurations fournissent également des méthodes similaires comme @ref{2a03,,getint()} et @ref{2a04,,getfloat()}. Vous pouvez enregistrer vos propres convertisseurs et personnaliser ceux déjà fournis. @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}

@node Valeurs de substitution,Structure des fichiers INI prise en change,Types de données prises en charge,configparser --- Configuration file parser
@anchor{library/configparser fallback-values}@anchor{2a05}
@subsubsection Valeurs de substitution


As with a dictionary, you can use a section's @ref{124a,,get()} method to
provide fallback values:

@example
>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Cipher')
>>> topsecret.get('Cipher', '3des-cbc')
'3des-cbc'
@end example

Please note that default values have precedence over fallback values.
For instance, in our example the @code{'CompressionLevel'} key was
specified only in the @code{'DEFAULT'} section.  If we try to get it from
the section @code{'topsecret.server.example'}, we will always get the default,
even if we specify a fallback:

@example
>>> topsecret.get('CompressionLevel', '3')
'9'
@end example

One more thing to be aware of is that the parser-level @ref{124a,,get()} method
provides a custom, more complex interface, maintained for backwards
compatibility.  When using this method, a fallback value can be provided via
the @code{fallback} keyword-only argument:

@example
>>> config.get('forge.example', 'monster',
...            fallback='No such things as monsters')
'No such things as monsters'
@end example

L'argument @code{fallback} peut être utilisé de la même façon avec les méthodes @ref{2a03,,getint()}, @ref{2a04,,getfloat()} et @ref{2a02,,getboolean()}. Par exemple :

@example
>>> 'BatchMode' in topsecret
False
>>> topsecret.getboolean('BatchMode', fallback=True)
True
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
False
@end example

@node Structure des fichiers INI prise en change,Unnamed Sections,Valeurs de substitution,configparser --- Configuration file parser
@anchor{library/configparser supported-ini-file-structure}@anchor{29fe}
@subsubsection Structure des fichiers `INI' prise en change


A configuration file consists of sections, each led by a @code{[section]} header,
followed by key/value entries separated by a specific string (@code{=} or @code{:} by
default @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}).  By default, section names are case sensitive but keys are not
@footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}.  Leading and trailing whitespace is removed from keys and values.
Values can be omitted if the parser is configured to allow it @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
},
in which case the key/value delimiter may also be left
out.  Values can also span multiple lines, as long as they are indented deeper
than the first line of the value.  Depending on the parser's mode, blank lines
may be treated as parts of multiline values or ignored.

Par défaut, un nom de section valide peut-être n'importe quelle chaîne de caractères ne contenant pas le caractère @code{'\\n'}. Pour modifier cela, voir @ref{2a06,,ConfigParser.SECTCRE}.

The first section name may be omitted if the parser is configured to allow an
unnamed top level section with @code{allow_unnamed_section=True}. In this case,
the keys/values may be retrieved by @ref{2a07,,UNNAMED_SECTION} as in
@code{config[UNNAMED_SECTION]}.

Les fichiers de configuration peuvent contenir des commentaires, préfixés par des caractères spécifiques (@code{#} et @code{;} par défaut @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}). Les commentaires peuvent apparaître à l'emplacement d'une ligne vide, et peuvent aussi être indentés. @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}

Par exemple :

@example
[Simple Values]
key=value
spaces in keys=allowed
spaces in values=allowed as well
spaces around the delimiter = obviously
you can also use : to delimit keys from values

[All Values Are Strings]
values like this: 1000000
or this: 3.14159265359
are they treated as numbers? : no
integers, floats and booleans are held as: strings
can use the API to get converted values directly: true

[Multiline Values]
chorus: I'm a lumberjack, and I'm okay
    I sleep all night and I work all day

[No Values]
key_without_value
empty string value here =

[You can use comments]
# like this
; or this

# By default only in an empty line.
# Inline comments can be harmful because they prevent users
# from using the delimiting characters as parts of values.
# That being said, this can be customized.

    [Sections Can Be Indented]
        can_values_be_as_well = True
        does_that_mean_anything_special = False
        purpose = formatting for readability
        multiline_values = are
            handled just fine as
            long as they are indented
            deeper than the first line
            of a value
        # Did I mention we can indent comments, too?
@end example

@node Unnamed Sections,Interpolation des valeurs,Structure des fichiers INI prise en change,configparser --- Configuration file parser
@anchor{library/configparser id10}@anchor{2a08}@anchor{library/configparser unnamed-sections}@anchor{2a09}
@subsubsection Unnamed Sections


The name of the first section (or unique) may be omitted and values
retrieved by the @ref{2a07,,UNNAMED_SECTION} attribute.

@example
>>> config = """
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> unnamed = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'option')
'value'
@end example

@node Interpolation des valeurs,Protocole d'accès associatif,Unnamed Sections,configparser --- Configuration file parser
@anchor{library/configparser interpolation-of-values}@anchor{2a0a}
@subsubsection Interpolation des valeurs


La classe @ref{1c3,,ConfigParser} prend en charge l’interpolation, en plus des fonctionnalités de base. Cela signifie que les valeurs peuvent être traitées avant d'être renvoyées par les appels aux méthodes @code{get()}.

@geindex % (percent);interpolation in configuration files

@geindex BasicInterpolation (classe dans configparser)
@anchor{library/configparser configparser BasicInterpolation}@anchor{70c}
@deffn {Classe} configparser.BasicInterpolation

Implémentation par défaut utilisée par la classe @ref{1c3,,ConfigParser}. Celle-ci permet aux valeurs de contenir des chaînes de formatage se référant à d'autres valeurs dans la même section, ou bien à des valeurs dans la section spéciale par défaut @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}. D'autres valeurs par défaut peuvent être fournies au moment de l'initialisation de cette classe.

Par exemple :

@example
[Paths]
home_dir: /Users
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Pictures

[Escape]
# use a %% to escape the % sign (% is the only character that needs to be escaped):
gain: 80%%
@end example

Dans l'exemple ci-dessus, une classe @code{Configparser} dont l'attribut `interpolation' vaut @code{BasicInterpolation()} interprète la chaîne de caractères @code{%(home_dir)s} en utilisant la valeur de la clé @code{home_dir} (@code{/Users} dans ce cas). @code{%(my_dir)s} est interprétée comme @code{/Users/lumberjack}. Les interpolations sont effectuées à la volée. Ainsi, les clés utilisées comme référence à l’intérieur des chaînes de formatage peuvent être définies dans le fichier de configuration dans n'importe quel ordre.

Si l'attribut @code{interpolation} vaut @code{None}, le lecteur renvoie @code{%(my_dir)s/Pictures} comme valeur pour @code{my_pictures} et @code{%(home_dir)s/lumberjack} comme valeur pour @code{my_dir}.
@end deffn

@geindex $ (dollar);interpolation in configuration files

@geindex ExtendedInterpolation (classe dans configparser)
@anchor{library/configparser configparser ExtendedInterpolation}@anchor{70d}
@deffn {Classe} configparser.ExtendedInterpolation

Autre façon de gérer l'interpolation en utilisant une syntaxe plus avancée, utilisée par exemple par @code{zc.buildout}. Cette syntaxe étendue utilise la chaîne de formatage @code{@{section:option@}@}} pour désigner une valeur appartenant à une autre section. L'interpolation peut s'étendre sur plusieurs niveaux. Par commodité, si la partie @code{@{section@}} est absente, l'interpolation utilise la section courante par défaut (et, le cas échéant, les valeurs de la section par défaut spéciale).

Voici comment transformer la configuration ci-dessus avec la syntaxe d'interpolation étendue :

@example
[Paths]
home_dir: /Users
my_dir: $@{home_dir@}/lumberjack
my_pictures: $@{my_dir@}/Pictures

[Escape]
# use a $$ to escape the $ sign ($ is the only character that needs to be escaped):
cost: $$80
@end example

Vous pouvez également récupérer des valeurs appartenant aux autres sections :

@example
[Common]
home_dir: /Users
library_dir: /Library
system_dir: /System
macports_dir: /opt/local

[Frameworks]
Python: 3.2
path: $@{Common:system_dir@}/Library/Frameworks/

[Arthur]
nickname: Two Sheds
last_name: Jackson
my_dir: $@{Common:home_dir@}/twosheds
my_pictures: $@{my_dir@}/Pictures
python_dir: $@{Frameworks:path@}/Python/Versions/$@{Frameworks:Python@}
@end example
@end deffn

@node Protocole d'accès associatif,Personnalisation du comportement de l'analyseur,Interpolation des valeurs,configparser --- Configuration file parser
@anchor{library/configparser mapping-protocol-access}@anchor{29ff}
@subsubsection Protocole d'accès associatif



Ajouté dans la version 3.2.


Le terme « protocole d'accès associatif » est utilisé pour décrire la fonctionnalité qui permet d'utiliser des objets personnalisés comme s'il s'agissait de dictionnaires. Dans le cas du module @ref{22,,configparser}, l’implémentation du protocole utilise la notation @code{parser['section']['option']}.

En particulier, @code{parser['section']} renvoie un mandataire vers les données de la section correspondantes dans l'analyseur. Cela signifie que les valeurs ne sont pas copiées, mais prélevées depuis l'analyseur initial à la demande. Plus important encore, lorsque les valeurs sont changées dans un mandataire pour une section, elles sont en réalité changées dans l'analyseur initial.

Les objets du module @ref{22,,configparser} se comportent le plus possible comme des vrais dictionnaires. L'interface est complète et suit les définitions fournies par la classe abstraite  @ref{1090,,MutableMapping}. Cependant, il faut prendre en compte un certain nombre de différences :


@itemize *

@item 
Par défaut, toutes les clés des sections sont accessibles sans respect de la casse @footnote{
Config parsers allow for heavy customization.  If you are interested in
changing the behaviour outlined by the footnote reference, consult the
@ref{2a00,,Customizing Parser Behaviour} section.
}. Par exemple, @code{for option in parser["section"]} renvoie uniquement les clés telles que transformées par la méthode @code{optionxform}, c'est-à-dire des clés transformées en minuscules. De même, pour une section contenant la clé @code{a}, les deux expressions suivantes renvoient @code{True} :

@example
"a" in parser["section"]
"A" in parser["section"]
@end example

@item 
Toutes les sections incluent en plus les valeurs de la section @code{DEFAULTSECT}. Cela signifie qu'appeler @code{clear()} sur une section ne la fera pas forcément apparaître vide. En effet, les valeurs par défaut ne peuvent pas être supprimées de la section (car, techniquement, elles n'y sont pas présentes). Si vous détruisez une valeur par défaut qui a été écrasée dans une section, alors la valeur par défaut sera de nouveau visible. Essayer de détruire une valeur par défaut lève l'exception @ref{33a,,KeyError}.

@item 
La section @code{DEFAULTSECT} ne peut pas être supprimée :


@itemize *

@item 
l'exception @ref{1ff,,ValueError} est levée si on essaye de la supprimer ;

@item 
appeler @code{parser.clear()} la laisse intacte ;

@item 
appeler @code{parser.popitem()} ne la renvoie jamais.
@end itemize

@item 
Le deuxième argument de @code{parser.get(section, option, **kwargs)} n'est `pas' une valeur de substitution. Notez cependant que les méthodes @code{get()} fournies par les sections sont compatibles à la fois avec le protocole associatif et avec l'API classique de `configparser'.

@item 
La méthode @code{parser.items()} est compatible avec le protocole d'accès associatif et renvoie une liste de paires `section_name', `section_proxy', en incluant la section `DEFAULTSECT'. Cependant, cette méthode peut aussi être appelée avec des arguments : @code{parser.items(section, raw, vars)}. Dans ce cas, la méthode renvoie une liste de paires `option', `value' pour la section spécifiée, en interprétant les interpolations (à moins d'utiliser @code{raw=True}).
@end itemize

Le protocole d'accès est implémenté au-dessus de l'ancienne API. Ainsi, les sous-classes qui écrasent des méthodes de l'interface originale se comportent correctement du point de vue du protocole d'accès.

@node Personnalisation du comportement de l'analyseur,Legacy API Examples,Protocole d'accès associatif,configparser --- Configuration file parser
@anchor{library/configparser customizing-parser-behaviour}@anchor{2a00}
@subsubsection Personnalisation du comportement de l'analyseur


Il existe pratiquement autant de variations du format `INI' que d'applications qui l'utilisent. Le module @ref{22,,configparser} fait son possible pour gérer le plus grand nombre de variantes raisonnables du style `INI'. Le comportement par défaut est principalement contraint par des raisons historiques. De ce fait, il est très probable qu'il soit nécessaire de personnaliser certaines des fonctionnalités de ce module.

The most common way to change the way a specific config parser works is to use
the @code{__init__()} options:


@itemize *

@item 
`defaults', valeur par défaut : @code{None}

Cette option accepte un dictionnaire de paires clé—valeurs qui seront placées dans la section @code{DEFAULT} initialement. Ceci est une façon élégante de prendre en charge des fichiers de configuration qui n'ont pas besoin de spécifier de valeurs lorsque celles-ci sont identiques aux valeurs par défaut documentées.

Hint: if you want to specify default values for a specific section, use
@ref{2a0b,,read_dict()} before you read the actual file.

@item 
`dict_type', valeur par défaut : @ref{253,,dict}

Cette option influe de manière importante sur la façon dont le protocole d'accès associatif se comporte et ce à quoi ressemblent les fichiers de configuration une fois écrits. Avec un dictionnaire standard, les sections sont stockées dans l'ordre où elles ont été ajoutées à l'analyseur. Ceci est également vrai pour les options à l'intérieur des sections.

Si vous souhaitez classer les sections et les options lors de l'écriture par exemple, vous pouvez utiliser un type de dictionnaire différent.

À noter : il est possible d'ajouter un ensemble de paires clés—valeurs en une seule opération. L'ordre des clés est préservé si vous utilisez un dictionnaire standard pour cela. Par exemple :

@example
>>> parser = configparser.ConfigParser()
>>> parser.read_dict(@{'section1': @{'key1': 'value1',
...                                'key2': 'value2',
...                                'key3': 'value3'@},
...                   'section2': @{'keyA': 'valueA',
...                                'keyB': 'valueB',
...                                'keyC': 'valueC'@},
...                   'section3': @{'foo': 'x',
...                                'bar': 'y',
...                                'baz': 'z'@}
... @})
>>> parser.sections()
['section1', 'section2', 'section3']
>>> [option for option in parser['section3']]
['foo', 'bar', 'baz']
@end example

@item 
`allow_no_value', valeur par défaut : @code{False}

Certains fichiers de configurations sont connus pour contenir des options sans valeur associée, tout en se conformant à la syntaxe prise en charge par le module @ref{22,,configparser} par ailleurs. Pour indiquer que de telles valeurs sont acceptables, utilisez le paramètre `allow_no_value' lors de la construction de l'instance :

@example
>>> import configparser

>>> sample_config = """
... [mysqld]
...   user = mysql
...   pid-file = /var/run/mysqld/mysqld.pid
...   skip-external-locking
...   old_passwords = 1
...   skip-bdb
...   # we don't need ACID today
...   skip-innodb
... """
>>> config = configparser.ConfigParser(allow_no_value=True)
>>> config.read_string(sample_config)

>>> # Settings with values are treated as before:
>>> config["mysqld"]["user"]
'mysql'

>>> # Settings without values provide None:
>>> config["mysqld"]["skip-bdb"]

>>> # Settings which aren't specified still raise an error:
>>> config["mysqld"]["does-not-exist"]
Traceback (most recent call last):
  ...
KeyError: 'does-not-exist'
@end example

@item 
`delimiters', valeur par défaut : @code{('=', ':')}

Chaînes de caractères qui séparent les clés des valeurs à l'intérieur d'une section. La première occurrence d'une telle chaîne à l'intérieur d'une ligne est considérée comme un délimiteur. Cela signifie que les valeurs peuvent contenir certains des délimiteurs (mais pas les clés).

Voir aussi l'argument `space_around_delimiters' de la méthode @ref{2a0c,,ConfigParser.write()}.

@item 
`comment_prefixes' (préfixes de commentaire) — valeur par défaut : @code{('#', ';')}

@item 
`inline_comment_prefixes' (préfixes de commentaire en ligne) — valeur par défaut : @code{('#', ';')}

Les préfixes de commentaire indiquent le début d'un commentaire valide au sein d'un fichier de configuration. Ils ne peuvent être utilisés qu'à l'emplacement d'une ligne vide (potentiellement indentée). En revanche, les préfixes de commentaires en ligne peuvent être utilisés après n'importe quelle valeur valide (comme les noms des sections, les options et les lignes vides). Par défaut, les commentaires en ligne sont désactivés et les préfixes utilisés pour les commentaires à l'emplacement d'une ligne vide sont @code{'#'} et @code{';'}.


Modifié dans la version 3.2: Les précédentes versions du module @ref{22,,configparser} se comportent comme en utilisant @code{comment_prefixes=('#',';')} et @code{inline_comment_prefixes=(';',)}.


Notez que les analyseurs ne prennent pas en charge l'échappement des préfixes de commentaires. Ainsi, l'utilisation de `inline_comment_prefixes' peut empêcher les utilisateurs de spécifier des valeurs qui contiennent des caractères utilisés comme préfixe de commentaire. Dans le doute, il est recommandé de ne pas utiliser `inline_comment_prefixes'. Dans tous les cas, la seule façon de stocker des préfixes de commentaires au début d'une valeur multi lignes est d'interpoler ceux-ci, par exemple :

@example
>>> from configparser import ConfigParser, ExtendedInterpolation
>>> parser = ConfigParser(interpolation=ExtendedInterpolation())
>>> # the default BasicInterpolation could be used as well
>>> parser.read_string("""
... [DEFAULT]
... hash = #
...
... [hashes]
... shebang =
...   $@{hash@}!/usr/bin/env python
...   $@{hash@} -*- coding: utf-8 -*-
...
... extensions =
...   enabled_extension
...   another_extension
...   #disabled_by_comment
...   yet_another_extension
...
... interpolation not necessary = if # is not at line start
... even in multiline values = line #1
...   line #2
...   line #3
... """)
>>> print(parser['hashes']['shebang'])

#!/usr/bin/env python
# -*- coding: utf-8 -*-
>>> print(parser['hashes']['extensions'])

enabled_extension
another_extension
yet_another_extension
>>> print(parser['hashes']['interpolation not necessary'])
if # is not at line start
>>> print(parser['hashes']['even in multiline values'])
line #1
line #2
line #3
@end example

@item 
`scrict', valeur par défaut : @code{True}

When set to @code{True}, the parser will not allow for any section or option
duplicates while reading from a single source (using @ref{4ef,,read_file()},
@ref{2a0d,,read_string()} or @ref{2a0b,,read_dict()}).  It is recommended to use strict
parsers in new applications.


Modifié dans la version 3.2: Les versions précédentes du module @ref{22,,configparser} se comportent comme en utilisant @code{strict=False}.


@item 
`empty_lines_in_values', valeur par défaut : @code{True}

Du point de vue des analyseurs, les valeurs peuvent s'étendre sur plusieurs lignes à partir du moment où elles sont plus indentées que la clé qui les contient. Par défaut les analyseurs autorisent les lignes vides à faire partie de telles valeurs. Dans le même temps, les clés elles-mêmes peuvent être indentées de façon à rendre le fichier plus lisible. En conséquence, il est probable que l'utilisateur perde de vue la structure du fichier lorsque celui-ci devient long et complexe. Prenez par exemple :

@example
[Section]
key = multiline
  value with a gotcha

 this = is still a part of the multiline value of 'key'
@end example

Ceci est particulièrement problématique si l'utilisateur a configuré son éditeur pour utiliser une police à chasse variable. C'est pourquoi il est conseillé de ne pas prendre en charge les valeurs avec des lignes vides, à moins que votre application en ait besoin. Dans ce cas, les lignes vides sont toujours interprétées comme séparant des clés. Dans l'exemple ci-dessus, cela produit deux clés : @code{key} et @code{this}.

@item 
`default_section', valeur par défaut : @code{configparser.DEFAULTSECT} (autrement dit : @code{"DEFAULT"})

La convention permettant d’autoriser une section spéciale de valeurs par défaut pour d’autres sections ou à des fins d’interpolation est un concept puissant de cette bibliothèque, permettant aux utilisateurs de créer des configurations déclaratives complexes. Cette section est normalement appelée @code{"DEFAULT"}, mais elle peut être personnalisée pour pointer vers n’importe quel autre nom de section valide. Certaines autres valeurs typiques incluent : @code{"general"} ou @code{"common"}. Le nom fourni est utilisé pour reconnaître les sections par défaut lors de la lecture à partir de n’importe quelle source, et est utilisée lors de la réécriture de la configuration dans un fichier. Sa valeur actuelle peut être récupérée à l’aide de l’attribut @code{parser_instance.default_section}, et peut être modifiée au moment de l’exécution (c’est-à-dire pour convertir des fichiers d’un format à un autre).

@item 
`interpolation', valeur par défaut : @code{configparser.BasicInterpolation}

Le comportement d'interpolation peut être personnalisé en fournissant un gestionnaire personnalisé via l'argument `interpolation'. @code{None} peut être utilisé pour désactiver complètement l'interpolation. @code{ExtendedInterpolation()} fournit une variante plus avancée inspirée de @code{zc.buildout}. Plus d'informations sur le sujet dans la section @ref{2a0a,,dédiée de la documentation}. @code{RowConfigParser} vaut @code{None} par défaut.

@item 
`converters', valeur par défaut : non défini

Les analyseurs de configuration fournissent des fonctions de récupération de valeurs qui effectuent la conversion par type. Par défaut, @ref{2a03,,getint()}, @ref{2a04,,getfloat()} et @ref{2a02,,getboolean()} sont implémentées. Si vous désirez d’autres fonctions de récupération de valeurs, vous pouvez les définir dans une sous-classe ou transmettre un dictionnaire où chaque clé est le nom du convertisseur et chaque valeur est une fonction implémentant ladite conversion. Par exemple, passer @code{@{'decimal':decimal.Decimal@}} ajouterait @code{getdecimal()} à la fois sur l’analyseur et sur tous les proxys de section. En d’autres termes, il sera possible d’écrire à la fois @code{parser_instance.getdecimal('section', 'key', fallback=0)} et @code{parser_instance['section'].getdecimal('key', 0)}.

Si le convertisseur doit accéder à l'état de l'analyseur, il peut être implémenté en tant que méthode sur une sous-classe d'analyseur de configuration. Si le nom de cette méthode commence par @code{get}, elle sera disponible sur tous les proxys de section, sous la forme compatible avec un dictionnaire (voir l'exemple @code{getdecimal()} ci-dessus).
@end itemize

Une personnalisation plus avancée peut être obtenue en remplaçant les valeurs par défaut de ces attributs de l'analyseur. Les valeurs par défaut sont définies sur les classes, elles peuvent donc être remplacées par des sous-classes ou par des attributs d'instance.

@geindex BOOLEAN_STATES (attribut configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser BOOLEAN_STATES}@anchor{2a0e}
@deffn {Attribut} ConfigParser.BOOLEAN_STATES

Par défaut, la méthode @ref{2a02,,getboolean()} considère les valeurs suivantes comme vraies : @code{'1'}, @code{'yes'}, @code{'true'}, @code{'on'}, et les valeurs suivantes comme fausses : @code{'0'}, @code{'no'}, @code{'false'}, @code{'off'}. Vous pouvez changer ce comportement en spécifiant votre propre dictionnaire associant des chaînes de caractères à des valeurs booléennes. Par exemple :

@example
>>> custom = configparser.ConfigParser()
>>> custom['section1'] = @{'funky': 'nope'@}
>>> custom['section1'].getboolean('funky')
Traceback (most recent call last):
...
ValueError: Not a boolean: nope
>>> custom.BOOLEAN_STATES = @{'sure': True, 'nope': False@}
>>> custom['section1'].getboolean('funky')
False
@end example

Other typical Boolean pairs include @code{accept}/@code{reject} or
@code{enabled}/@code{disabled}.
@end deffn


@deffn {Méthode} ConfigParser.optionxform (option)

This method transforms option names on every read, get, or set
operation.  The default converts the name to lowercase.  This also
means that when a configuration file gets written, all keys will be
lowercase.  Override this method if that's unsuitable.
For example:

@example
>>> config = """
... [Section1]
... Key = Value
...
... [Section2]
... AnotherKey = Value
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> list(typical['Section1'].keys())
['key']
>>> list(typical['Section2'].keys())
['anotherkey']
>>> custom = configparser.RawConfigParser()
>>> custom.optionxform = lambda option: option
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Key']
>>> list(custom['Section2'].keys())
['AnotherKey']
@end example

@cartouche
@quotation Note 
The optionxform function transforms option names to a canonical form.
This should be an idempotent function: if the name is already in
canonical form, it should be returned unchanged.
@end quotation
@end cartouche
@end deffn

@geindex SECTCRE (attribut configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser SECTCRE}@anchor{2a06}
@deffn {Attribut} ConfigParser.SECTCRE

A compiled regular expression used to parse section headers.  The default
matches @code{[section]} to the name @code{"section"}.  Whitespace is considered
part of the section name, thus @code{[  larch  ]} will be read as a section of
name @code{"  larch  "}.  Override this attribute if that's unsuitable.  For
example:

@example
>>> import re
>>> config = """
... [Section 1]
... option = value
...
... [  Section 2  ]
... another = val
... """
>>> typical = configparser.ConfigParser()
>>> typical.read_string(config)
>>> typical.sections()
['Section 1', '  Section 2  ']
>>> custom = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Section 1', 'Section 2']
@end example

@cartouche
@quotation Note 
While ConfigParser objects also use an @code{OPTCRE} attribute for recognizing
option lines, it's not recommended to override it because that would
interfere with constructor options `allow_no_value' and `delimiters'.
@end quotation
@end cartouche
@end deffn

@node Legacy API Examples,ConfigParser Objects,Personnalisation du comportement de l'analyseur,configparser --- Configuration file parser
@anchor{library/configparser legacy-api-examples}@anchor{2a0f}
@subsubsection Legacy API Examples


Mainly because of backwards compatibility concerns, @ref{22,,configparser}
provides also a legacy API with explicit @code{get}/@code{set} methods.  While there
are valid use cases for the methods outlined below, mapping protocol access is
preferred for new projects.  The legacy API is at times more advanced,
low-level and downright counterintuitive.

An example of writing to a configuration file:

@example
import configparser

config = configparser.RawConfigParser()

# Please note that using RawConfigParser's set functions, you can assign
# non-string values to keys internally, but will receive an error when
# attempting to write to a file or when you get it in non-raw mode. Setting
# values using the mapping protocol or ConfigParser's set() does not allow
# such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')

# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'w') as configfile:
    config.write(configfile)
@end example

An example of reading the configuration file again:

@example
import configparser

config = configparser.RawConfigParser()
config.read('example.cfg')

# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print(a_float + an_int)

# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))
@end example

To get interpolation, use @ref{1c3,,ConfigParser}:

@example
import configparser

cfg = configparser.ConfigParser()
cfg.read('example.cfg')

# Set the optional *raw* argument of get() to True if you wish to disable
# interpolation in a single get operation.
print(cfg.get('Section1', 'foo', raw=False))  # -> "Python is fun!"
print(cfg.get('Section1', 'foo', raw=True))   # -> "%(bar)s is %(baz)s!"

# The optional *vars* argument is a dict with members that will take
# precedence in interpolation.
print(cfg.get('Section1', 'foo', vars=@{'bar': 'Documentation',
                                       'baz': 'evil'@}))

# The optional *fallback* argument can be used to provide a fallback value
print(cfg.get('Section1', 'foo'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'foo', fallback='Monty is not.'))
      # -> "Python is fun!"

print(cfg.get('Section1', 'monster', fallback='No such things as monsters.'))
      # -> "No such things as monsters."

# A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError
# but we can also use:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> None
@end example

Default values are available in both types of ConfigParsers.  They are used in
interpolation if an option used is not defined elsewhere.

@example
import configparser

# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = configparser.ConfigParser(@{'bar': 'Life', 'baz': 'hard'@})
config.read('example.cfg')

print(config.get('Section1', 'foo'))     # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo'))     # -> "Life is hard!"
@end example

@node ConfigParser Objects,RawConfigParser Objects,Legacy API Examples,configparser --- Configuration file parser
@anchor{library/configparser configparser-objects}@anchor{2a10}@anchor{library/configparser id13}@anchor{2a11}
@subsubsection ConfigParser Objects


@geindex ConfigParser (classe dans configparser)
@anchor{library/configparser configparser ConfigParser}@anchor{1c3}
@deffn {Classe} configparser.ConfigParser (defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters=@{@}, allow_unnamed_section=False)

The main configuration parser.  When `defaults' is given, it is initialized
into the dictionary of intrinsic defaults.  When `dict_type' is given, it
will be used to create the dictionary objects for the list of sections, for
the options within a section, and for the default values.

When `delimiters' is given, it is used as the set of substrings that
divide keys from values.  When `comment_prefixes' is given, it will be used
as the set of substrings that prefix comments in otherwise empty lines.
Comments can be indented.  When `inline_comment_prefixes' is given, it will
be used as the set of substrings that prefix comments in non-empty lines.

When `strict' is @code{True} (the default), the parser won't allow for
any section or option duplicates while reading from a single source (file,
string or dictionary), raising @ref{124d,,DuplicateSectionError} or
@ref{124e,,DuplicateOptionError}.  When `empty_lines_in_values' is @code{False}
(default: @code{True}), each empty line marks the end of an option.  Otherwise,
internal empty lines of a multiline option are kept as part of the value.
When `allow_no_value' is @code{True} (default: @code{False}), options without
values are accepted; the value held for these is @code{None} and they are
serialized without the trailing delimiter.

When `default_section' is given, it specifies the name for the special
section holding default values for other sections and interpolation purposes
(normally named @code{"DEFAULT"}).  This value can be retrieved and changed at
runtime using the @code{default_section} instance attribute. This won't
re-evaluate an already parsed config file, but will be used when writing
parsed settings to a new config file.

Interpolation behaviour may be customized by providing a custom handler
through the `interpolation' argument. @code{None} can be used to turn off
interpolation completely, @code{ExtendedInterpolation()} provides a more
advanced variant inspired by @code{zc.buildout}.  More on the subject in the
@ref{2a0a,,dedicated documentation section}.

All option names used in interpolation will be passed through the
@ref{2a12,,optionxform()} method just like any other option name reference.  For
example, using the default implementation of @ref{2a12,,optionxform()} (which
converts option names to lower case), the values @code{foo %(bar)s} and @code{foo
%(BAR)s} are equivalent.

When `converters' is given, it should be a dictionary where each key
represents the name of a type converter and each value is a callable
implementing the conversion from string to the desired datatype.  Every
converter gets its own corresponding @code{get*()} method on the parser
object and section proxies.

When `allow_unnamed_section' is @code{True} (default: @code{False}),
the first section name can be omitted. See the
@ref{2a09,,"Unnamed Sections" section}.

Il est possible de lire plusieurs configurations dans un seul objet @ref{1c3,,ConfigParser}, où la configuration ajoutée la plus récemment a la priorité la plus élevée. Toutes les clés en conflit sont prises de la configuration la plus récente tandis que les anciennes clés déjà existantes sont mises de côté. L'exemple suivant lit un fichier @code{override.ini} qui prendra le dessus sur toutes les clés en conflit avec le fichier @code{exemple.ini}.

@example
[DEFAULT]
ServerAliveInterval = -1
@end example

@example
>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = @{'ServerAliveInterval': '-1'@}
>>> with open('override.ini', 'w') as configfile:
...     config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'override.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1
@end example


Modifié dans la version 3.1: The default `dict_type' is @ref{5c5,,collections.OrderedDict}.



Modifié dans la version 3.2: `allow_no_value', `delimiters', `comment_prefixes', `strict',
`empty_lines_in_values', `default_section' and `interpolation' were
added.



Modifié dans la version 3.5: The `converters' argument was added.



Modifié dans la version 3.7: The `defaults' argument is read with @ref{2a0b,,read_dict()},
providing consistent behavior across the parser: non-string
keys and values are implicitly converted to strings.



Modifié dans la version 3.8: The default `dict_type' is @ref{253,,dict}, since it now preserves
insertion order.



Modifié dans la version 3.13: Raise a @ref{2a13,,MultilineContinuationError} when `allow_no_value' is
@code{True}, and a key without a value is continued with an indented line.



Modifié dans la version 3.13: The `allow_unnamed_section' argument was added.


@geindex defaults() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser defaults}@anchor{2a14}
@deffn {Méthode} defaults ()

Return a dictionary containing the instance-wide defaults.
@end deffn

@geindex sections() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser sections}@anchor{2a15}
@deffn {Méthode} sections ()

Return a list of the sections available; the `default section' is not
included in the list.
@end deffn

@geindex add_section() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser add_section}@anchor{124c}
@deffn {Méthode} add_section (section)

Add a section named `section' to the instance.  If a section by the given
name already exists, @ref{124d,,DuplicateSectionError} is raised.  If the
`default section' name is passed, @ref{1ff,,ValueError} is raised.  The name
of the section must be a string; if not, @ref{522,,TypeError} is raised.


Modifié dans la version 3.2: Non-string section names raise @ref{522,,TypeError}.

@end deffn

@geindex has_section() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser has_section}@anchor{2a16}
@deffn {Méthode} has_section (section)

Indicates whether the named `section' is present in the configuration.
The `default section' is not acknowledged.
@end deffn

@geindex options() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser options}@anchor{2a17}
@deffn {Méthode} options (section)

Return a list of options available in the specified `section'.
@end deffn

@geindex has_option() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser has_option}@anchor{2a18}
@deffn {Méthode} has_option (section, option)

If the given `section' exists, and contains the given `option', return
@ref{bfb,,True}; otherwise return @ref{b25,,False}.  If the specified
`section' is @ref{660,,None} or an empty string, DEFAULT is assumed.
@end deffn

@geindex read() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read}@anchor{141c}
@deffn {Méthode} read (filenames, encoding=None)

Attempt to read and parse an iterable of filenames, returning a list of
filenames which were successfully parsed.

If `filenames' is a string, a @ref{1bd,,bytes} object or a
@ref{29d,,path-like object}, it is treated as
a single filename.  If a file named in `filenames' cannot be opened, that
file will be ignored.  This is designed so that you can specify an
iterable of potential configuration file locations (for example, the
current directory, the user's home directory, and some system-wide
directory), and all existing configuration files in the iterable will be
read.

If none of the named files exist, the @ref{1c3,,ConfigParser}
instance will contain an empty dataset.  An application which requires
initial values to be loaded from a file should load the required file or
files using @ref{4ef,,read_file()} before calling @ref{141c,,read()} for any
optional files:

@example
import configparser, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            encoding='cp1250')
@end example


Modifié dans la version 3.2: Added the `encoding' parameter.
Previously, all files were read using the default encoding for @ref{505,,open()}.



Modifié dans la version 3.6.1: The `filenames' parameter accepts a @ref{29d,,path-like object}.



Modifié dans la version 3.7: The `filenames' parameter accepts a @ref{1bd,,bytes} object.

@end deffn

@geindex read_file() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read_file}@anchor{4ef}
@deffn {Méthode} read_file (f, source=None)

Read and parse configuration data from `f' which must be an iterable
yielding Unicode strings (for example files opened in text mode).

Optional argument `source' specifies the name of the file being read.  If
not given and `f' has a @code{name} attribute, that is used for
`source'; the default is @code{'<???>'}.


Ajouté dans la version 3.2: Replaces @code{readfp()}.

@end deffn

@geindex read_string() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read_string}@anchor{2a0d}
@deffn {Méthode} read_string (string, source='<string>')

Parse configuration data from a string.

Optional argument `source' specifies a context-specific name of the
string passed.  If not given, @code{'<string>'} is used.  This should
commonly be a filesystem path or a URL.


Ajouté dans la version 3.2.

@end deffn

@geindex read_dict() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser read_dict}@anchor{2a0b}
@deffn {Méthode} read_dict (dictionary, source='<dict>')

Load configuration from any object that provides a dict-like @code{items()}
method.  Keys are section names, values are dictionaries with keys and
values that should be present in the section.  If the used dictionary
type preserves order, sections and their keys will be added in order.
Values are automatically converted to strings.

Optional argument `source' specifies a context-specific name of the
dictionary passed.  If not given, @code{<dict>} is used.

This method can be used to copy state between parsers.


Ajouté dans la version 3.2.

@end deffn

@geindex get() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser get}@anchor{124a}
@deffn {Méthode} get (section, option, *, raw=False, vars=None[, fallback])

Get an `option' value for the named `section'.  If `vars' is provided, it
must be a dictionary.  The `option' is looked up in `vars' (if provided),
`section', and in `DEFAULTSECT' in that order.  If the key is not found
and `fallback' is provided, it is used as a fallback value.  @code{None} can
be provided as a `fallback' value.

All the @code{'%'} interpolations are expanded in the return values, unless
the `raw' argument is true.  Values for interpolation keys are looked up
in the same manner as the option.


Modifié dans la version 3.2: Arguments `raw', `vars' and `fallback' are keyword only to protect
users from trying to use the third argument as the `fallback' fallback
(especially when using the mapping protocol).

@end deffn

@geindex getint() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser getint}@anchor{2a03}
@deffn {Méthode} getint (section, option, *, raw=False, vars=None[, fallback])

A convenience method which coerces the `option' in the specified `section'
to an integer.  See @ref{124a,,get()} for explanation of `raw', `vars' and
`fallback'.
@end deffn

@geindex getfloat() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser getfloat}@anchor{2a04}
@deffn {Méthode} getfloat (section, option, *, raw=False, vars=None[, fallback])

A convenience method which coerces the `option' in the specified `section'
to a floating-point number.  See @ref{124a,,get()} for explanation of `raw',
`vars' and `fallback'.
@end deffn

@geindex getboolean() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser getboolean}@anchor{2a02}
@deffn {Méthode} getboolean (section, option, *, raw=False, vars=None[, fallback])

A convenience method which coerces the `option' in the specified `section'
to a Boolean value.  Note that the accepted values for the option are
@code{'1'}, @code{'yes'}, @code{'true'}, and @code{'on'}, which cause this method to
return @code{True}, and @code{'0'}, @code{'no'}, @code{'false'}, and @code{'off'}, which
cause it to return @code{False}.  These string values are checked in a
case-insensitive manner.  Any other value will cause it to raise
@ref{1ff,,ValueError}.  See @ref{124a,,get()} for explanation of `raw', `vars' and
`fallback'.
@end deffn

@geindex items() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser items}@anchor{2a19}
@deffn {Méthode} items (raw=False, vars=None)

@deffnx {Méthode} items (section, raw=False, vars=None)

When `section' is not given, return a list of `section_name',
`section_proxy' pairs, including DEFAULTSECT.

Otherwise, return a list of `name', `value' pairs for the options in the
given `section'.  Optional arguments have the same meaning as for the
@ref{124a,,get()} method.


Modifié dans la version 3.8: Items present in `vars' no longer appear in the result.  The previous
behaviour mixed actual parser options with variables provided for
interpolation.

@end deffn

@geindex set() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser set}@anchor{124b}
@deffn {Méthode} set (section, option, value)

If the given section exists, set the given option to the specified value;
otherwise raise @ref{2a1a,,NoSectionError}.  `option' and `value' must be
strings; if not, @ref{522,,TypeError} is raised.
@end deffn

@geindex write() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser write}@anchor{2a0c}
@deffn {Méthode} write (fileobject, space_around_delimiters=True)

Write a representation of the configuration to the specified @ref{11a0,,file object}, which must be opened in text mode (accepting strings).  This
representation can be parsed by a future @ref{141c,,read()} call.  If
`space_around_delimiters' is true, delimiters between
keys and values are surrounded by spaces.
@end deffn

@cartouche
@quotation Note 
Comments in the original configuration file are not preserved when
writing the configuration back.
What is considered a comment, depends on the given values for
`comment_prefix' and `inline_comment_prefix'.
@end quotation
@end cartouche

@geindex remove_option() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser remove_option}@anchor{2a1b}
@deffn {Méthode} remove_option (section, option)

Remove the specified `option' from the specified `section'.  If the
section does not exist, raise @ref{2a1a,,NoSectionError}.  If the option
existed to be removed, return @ref{bfb,,True}; otherwise return
@ref{b25,,False}.
@end deffn

@geindex remove_section() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser remove_section}@anchor{2a1c}
@deffn {Méthode} remove_section (section)

Remove the specified `section' from the configuration.  If the section in
fact existed, return @code{True}.  Otherwise return @code{False}.
@end deffn

@geindex optionxform() (méthode configparser.ConfigParser)
@anchor{library/configparser configparser ConfigParser optionxform}@anchor{2a12}
@deffn {Méthode} optionxform (option)

Transforms the option name `option' as found in an input file or as passed
in by client code to the form that should be used in the internal
structures.  The default implementation returns a lower-case version of
`option'; subclasses may override this or client code can set an attribute
of this name on instances to affect this behavior.

You don't need to subclass the parser to use this method, you can also
set it on an instance, to a function that takes a string argument and
returns a string.  Setting it to @code{str}, for example, would make option
names case sensitive:

@example
cfgparser = ConfigParser()
cfgparser.optionxform = str
@end example

Note that when reading configuration files, whitespace around the option
names is stripped before @ref{2a12,,optionxform()} is called.
@end deffn
@end deffn

@geindex UNNAMED_SECTION (dans le module configparser)
@anchor{library/configparser configparser UNNAMED_SECTION}@anchor{2a07}
@deffn {Données} configparser.UNNAMED_SECTION

A special object representing a section name used to reference the unnamed section (see @ref{2a09,,Unnamed Sections}).
@end deffn

@geindex MAX_INTERPOLATION_DEPTH (dans le module configparser)
@anchor{library/configparser configparser MAX_INTERPOLATION_DEPTH}@anchor{2a1d}
@deffn {Données} configparser.MAX_INTERPOLATION_DEPTH

The maximum depth for recursive interpolation for @ref{124a,,get()} when the `raw'
parameter is false.  This is relevant only when the default `interpolation'
is used.
@end deffn

@node RawConfigParser Objects,Exceptions<8>,ConfigParser Objects,configparser --- Configuration file parser
@anchor{library/configparser id15}@anchor{2a1e}@anchor{library/configparser rawconfigparser-objects}@anchor{2a1f}
@subsubsection RawConfigParser Objects


@geindex RawConfigParser (classe dans configparser)
@anchor{library/configparser configparser RawConfigParser}@anchor{f4f}
@deffn {Classe} configparser.RawConfigParser (defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters=@{@}, allow_unnamed_section=False)

Legacy variant of the @ref{1c3,,ConfigParser}.  It has interpolation
disabled by default and allows for non-string section names, option
names, and values via its unsafe @code{add_section} and @code{set} methods,
as well as the legacy @code{defaults=} keyword argument handling.


Modifié dans la version 3.2: `allow_no_value', `delimiters', `comment_prefixes', `strict',
`empty_lines_in_values', `default_section' and `interpolation' were
added.



Modifié dans la version 3.5: The `converters' argument was added.



Modifié dans la version 3.8: The default `dict_type' is @ref{253,,dict}, since it now preserves
insertion order.



Modifié dans la version 3.13: The `allow_unnamed_section' argument was added.


@cartouche
@quotation Note 
Consider using @ref{1c3,,ConfigParser} instead which checks types of
the values to be stored internally.  If you don't want interpolation, you
can use @code{ConfigParser(interpolation=None)}.
@end quotation
@end cartouche

@geindex add_section() (méthode configparser.RawConfigParser)
@anchor{library/configparser configparser RawConfigParser add_section}@anchor{2a20}
@deffn {Méthode} add_section (section)

Add a section named `section' to the instance.  If a section by the given
name already exists, @ref{124d,,DuplicateSectionError} is raised.  If the
`default section' name is passed, @ref{1ff,,ValueError} is raised.

Type of `section' is not checked which lets users create non-string named
sections.  This behaviour is unsupported and may cause internal errors.
@end deffn

@geindex set() (méthode configparser.RawConfigParser)
@anchor{library/configparser configparser RawConfigParser set}@anchor{2a21}
@deffn {Méthode} set (section, option, value)

If the given section exists, set the given option to the specified value;
otherwise raise @ref{2a1a,,NoSectionError}.  While it is possible to use
@ref{f4f,,RawConfigParser} (or @ref{1c3,,ConfigParser} with `raw' parameters
set to true) for `internal' storage of non-string values, full
functionality (including interpolation and output to files) can only be
achieved using string values.

This method lets users assign non-string values to keys internally.  This
behaviour is unsupported and will cause errors when attempting to write
to a file or get it in non-raw mode.  `Use the mapping protocol API'
which does not allow such assignments to take place.
@end deffn
@end deffn

@node Exceptions<8>,,RawConfigParser Objects,configparser --- Configuration file parser
@anchor{library/configparser exceptions}@anchor{2a22}
@subsubsection Exceptions


@geindex Error
@anchor{library/configparser configparser Error}@anchor{2a23}
@deffn {Exception} configparser.Error

Base class for all other @ref{22,,configparser} exceptions.
@end deffn

@geindex NoSectionError
@anchor{library/configparser configparser NoSectionError}@anchor{2a1a}
@deffn {Exception} configparser.NoSectionError

Exception raised when a specified section is not found.
@end deffn

@geindex DuplicateSectionError
@anchor{library/configparser configparser DuplicateSectionError}@anchor{124d}
@deffn {Exception} configparser.DuplicateSectionError

Exception raised if @ref{124c,,add_section()} is called with the name of a section
that is already present or in strict parsers when a section if found more
than once in a single input file, string or dictionary.


Modifié dans la version 3.2: Added the optional `source' and `lineno' attributes and parameters to
@code{__init__()}.

@end deffn

@geindex DuplicateOptionError
@anchor{library/configparser configparser DuplicateOptionError}@anchor{124e}
@deffn {Exception} configparser.DuplicateOptionError

Exception raised by strict parsers if a single option appears twice during
reading from a single file, string or dictionary. This catches misspellings
and case sensitivity-related errors, e.g. a dictionary may have two keys
representing the same case-insensitive configuration key.
@end deffn

@geindex NoOptionError
@anchor{library/configparser configparser NoOptionError}@anchor{2a24}
@deffn {Exception} configparser.NoOptionError

Exception raised when a specified option is not found in the specified
section.
@end deffn

@geindex InterpolationError
@anchor{library/configparser configparser InterpolationError}@anchor{2a25}
@deffn {Exception} configparser.InterpolationError

Base class for exceptions raised when problems occur performing string
interpolation.
@end deffn

@geindex InterpolationDepthError
@anchor{library/configparser configparser InterpolationDepthError}@anchor{2a26}
@deffn {Exception} configparser.InterpolationDepthError

Exception raised when string interpolation cannot be completed because the
number of iterations exceeds @ref{2a1d,,MAX_INTERPOLATION_DEPTH}.  Subclass of
@ref{2a25,,InterpolationError}.
@end deffn

@geindex InterpolationMissingOptionError
@anchor{library/configparser configparser InterpolationMissingOptionError}@anchor{2a27}
@deffn {Exception} configparser.InterpolationMissingOptionError

Exception raised when an option referenced from a value does not exist.
Subclass of @ref{2a25,,InterpolationError}.
@end deffn

@geindex InterpolationSyntaxError
@anchor{library/configparser configparser InterpolationSyntaxError}@anchor{2a28}
@deffn {Exception} configparser.InterpolationSyntaxError

Exception raised when the source text into which substitutions are made does
not conform to the required syntax.  Subclass of @ref{2a25,,InterpolationError}.
@end deffn

@geindex MissingSectionHeaderError
@anchor{library/configparser configparser MissingSectionHeaderError}@anchor{2a29}
@deffn {Exception} configparser.MissingSectionHeaderError

Exception raised when attempting to parse a file which has no section
headers.
@end deffn

@geindex ParsingError
@anchor{library/configparser configparser ParsingError}@anchor{4ee}
@deffn {Exception} configparser.ParsingError

Exception raised when errors occur attempting to parse a file.


Modifié dans la version 3.12: The @code{filename} attribute and @code{__init__()} constructor argument were
removed.  They have been available using the name @code{source} since 3.2.

@end deffn

@geindex MultilineContinuationError
@anchor{library/configparser configparser MultilineContinuationError}@anchor{2a13}
@deffn {Exception} configparser.MultilineContinuationError

Exception raised when a key without a corresponding value is continued with
an indented line.


Ajouté dans la version 3.13.

@end deffn

@subsubheading Notes


@node tomllib --- Parse TOML files,netrc --- netrc file processing,configparser --- Configuration file parser,Formats de fichiers
@anchor{library/tomllib doc}@anchor{2a2a}@anchor{library/tomllib module-tomllib}@anchor{fb}@anchor{library/tomllib tomllib-parse-toml-files}@anchor{2a2b}
@subsection @code{tomllib} --- Parse TOML files


@geindex module; tomllib


Ajouté dans la version 3.11.


`Source code:' Lib/tomllib@footnote{https://github.com/python/cpython/tree/3.13/Lib/tomllib}


__________________________________________________________________


This module provides an interface for parsing TOML 1.0.0 (Tom's Obvious Minimal
Language, https://toml.io@footnote{https://toml.io/en/}). This module does not
support writing TOML.


@subsubheading Voir aussi


The Tomli-W package@footnote{https://pypi.org/project/tomli-w/}
is a TOML writer that can be used in conjunction with this module,
providing a write API familiar to users of the standard library
@ref{8c,,marshal} and @ref{a5,,pickle} modules.



@subsubheading Voir aussi


The TOML Kit package@footnote{https://pypi.org/project/tomlkit/}
is a style-preserving TOML library with both read and write capability.
It is a recommended replacement for this module for editing already
existing TOML files.


Ce module définit les fonctions suivantes :

@geindex load() (dans le module tomllib)
@anchor{library/tomllib tomllib load}@anchor{2a2c}
@deffn {Fonction} tomllib.load (fp, /, *, parse_float=float)

Read a TOML file. The first argument should be a readable and binary file object.
Return a @ref{253,,dict}. Convert TOML types to Python using this
@ref{2a2d,,conversion table}.

`parse_float' will be called with the string of every TOML
float to be decoded.  By default, this is equivalent to @code{float(num_str)}.
This can be used to use another datatype or parser for TOML floats
(e.g. @ref{29a,,decimal.Decimal}). The callable must not return a
@ref{253,,dict} or a @ref{5fc,,list}, else a @ref{1ff,,ValueError} is raised.

A @ref{2a2e,,TOMLDecodeError} will be raised on an invalid TOML document.
@end deffn

@geindex loads() (dans le module tomllib)
@anchor{library/tomllib tomllib loads}@anchor{2a2f}
@deffn {Fonction} tomllib.loads (s, /, *, parse_float=float)

Load TOML from a @ref{435,,str} object. Return a @ref{253,,dict}. Convert TOML
types to Python using this @ref{2a2d,,conversion table}. The
`parse_float' argument has the same meaning as in @ref{2a2c,,load()}.

A @ref{2a2e,,TOMLDecodeError} will be raised on an invalid TOML document.
@end deffn

The following exceptions are available:

@geindex TOMLDecodeError
@anchor{library/tomllib tomllib TOMLDecodeError}@anchor{2a2e}
@deffn {Exception} tomllib.TOMLDecodeError

Subclass of @ref{1ff,,ValueError}.
@end deffn

@menu
* Exemples: Exemples<11>. 
* Conversion Table:: 

@end menu

@node Exemples<11>,Conversion Table,,tomllib --- Parse TOML files
@anchor{library/tomllib examples}@anchor{2a30}
@subsubsection Exemples


Parsing a TOML file:

@example
import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)
@end example

Parsing a TOML string:

@example
import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)
@end example

@node Conversion Table,,Exemples<11>,tomllib --- Parse TOML files
@anchor{library/tomllib conversion-table}@anchor{2a31}
@subsubsection Conversion Table

@anchor{library/tomllib toml-to-py-table}@anchor{2a2d}

@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

TOML

@tab

Python

@item

TOML document

@tab

`dict'

@item

`string'

@tab

`str'

@item

`int' (entier)

@tab

`int'

@item

`float' (nombre à virgule flottante)

@tab

float (configurable with `parse_float')

@item

`boolean'

@tab

`bool' (booléen)

@item

offset date-time

@tab

datetime.datetime (@code{tzinfo} attribute set to an instance of @code{datetime.timezone})

@item

local date-time

@tab

datetime.datetime (@code{tzinfo} attribute set to @code{None})

@item

local date

@tab

datetime.date

@item

local time

@tab

datetime.time

@item

`array'

@tab

liste

@item

table

@tab

`dict'

@item

inline table

@tab

`dict'

@item

array of tables

@tab

list of dicts

@end multitable


@node netrc --- netrc file processing,plistlib --- Generate and parse Apple plist files,tomllib --- Parse TOML files,Formats de fichiers
@anchor{library/netrc doc}@anchor{2a32}@anchor{library/netrc module-netrc}@anchor{9a}@anchor{library/netrc netrc-netrc-file-processing}@anchor{2a33}
@subsection @code{netrc} --- netrc file processing


@geindex module; netrc

`Code source :' Lib/netrc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/netrc.py}


__________________________________________________________________


La classe @ref{9a,,netrc} analyse et encapsule le format de fichier `netrc' utilisé par le programme Unix @code{ftp} et d'autres clients FTP.

@geindex netrc (classe dans netrc)
@anchor{library/netrc netrc netrc}@anchor{184f}
@deffn {Classe} netrc.netrc ([file])

Une instance de @ref{184f,,netrc} ou une instance de sous-classe encapsule les données à partir d'un fichier `netrc'. L'argument d'initialisation, s'il est présent, précise le fichier à analyser. Si aucun argument n'est donné, le fichier @code{.netrc} dans le répertoire d’accueil de l'utilisateur -- déterminé par @ref{a02,,os.path.expanduser()} -- est lu. Sinon, l'exception @ref{eae,,FileNotFoundError} sera levée. Les erreurs d'analyse lèveront @ref{2a34,,NetrcParseError} avec les informations de diagnostic, y compris le nom de fichier, le numéro de ligne, et le lexème. Si aucun argument n'est spécifié dans un système POSIX, la présence de mots de passe dans le fichier @code{.netrc} lèvera @ref{2a34,,NetrcParseError} si la propriété du fichier ou les permissions ne sont pas sécurisées (propriété d'un utilisateur autre que l'utilisateur exécutant le processus ou accessible en lecture ou en écriture par n'importe quel autre utilisateur). Le niveau de sécurité offert est ainsi équivalent à celui de ftp et d'autres programmes utilisant @code{netrc}.


Modifié dans la version 3.4: Ajout de la vérification d'autorisations POSIX.



Modifié dans la version 3.7: @ref{a02,,os.path.expanduser()} est utilisée pour trouver l'emplacement du fichier @code{netrc} lorsque `file' n'est pas passé en tant qu'argument.



Modifié dans la version 3.10: @ref{9a,,netrc} try UTF-8 encoding before using locale specific
encoding.
The entry in the netrc file no longer needs to contain all tokens.  The missing
tokens' value default to an empty string.  All the tokens and their values now
can contain arbitrary characters, like whitespace and non-ASCII characters.
If the login name is anonymous, it won't trigger the security check.

@end deffn

@geindex NetrcParseError
@anchor{library/netrc netrc NetrcParseError}@anchor{2a34}
@deffn {Exception} netrc.NetrcParseError

Exception raised by the @ref{184f,,netrc} class when syntactical errors are
encountered in source text.  Instances of this exception provide three
interesting attributes:

@geindex msg (attribut netrc.NetrcParseError)
@anchor{library/netrc netrc NetrcParseError msg}@anchor{2a35}
@deffn {Attribut} msg

Textual explanation of the error.
@end deffn

@geindex filename (attribut netrc.NetrcParseError)
@anchor{library/netrc netrc NetrcParseError filename}@anchor{2a36}
@deffn {Attribut} filename

The name of the source file.
@end deffn

@geindex lineno (attribut netrc.NetrcParseError)
@anchor{library/netrc netrc NetrcParseError lineno}@anchor{2a37}
@deffn {Attribut} lineno

The line number on which the error was found.
@end deffn
@end deffn

@menu
* Objets netrc:: 

@end menu

@node Objets netrc,,,netrc --- netrc file processing
@anchor{library/netrc id1}@anchor{2a38}@anchor{library/netrc netrc-objects}@anchor{2a39}
@subsubsection Objets `netrc'


Une instance @ref{184f,,netrc} a les méthodes suivantes :

@geindex authenticators() (méthode netrc.netrc)
@anchor{library/netrc netrc netrc authenticators}@anchor{2a3a}
@deffn {Méthode} netrc.authenticators (host)

Renvoie un triplet @code{(login, account, password)} pour s'authentifier auprès de l'hôte `host'. Si le fichier `netrc' ne contient pas d'entrée pour l'hôte donné, renvoie le triplet associé à l'entrée par défaut. Si aucun hôte correspondant ni aucune entrée par défaut n'est disponible, renvoie @code{None}.
@end deffn

@geindex __repr__() (méthode netrc.netrc)
@anchor{library/netrc netrc netrc __repr__}@anchor{2a3b}
@deffn {Méthode} netrc.__repr__ ()

Déverse les données de la classe sous forme de chaîne dans le format d'un fichier `netrc'. (Ceci ignore les commentaires et peut réorganiser les entrées).
@end deffn

Les instances de @ref{184f,,netrc} ont des variables d'instance publiques :

@geindex hosts (attribut netrc.netrc)
@anchor{library/netrc netrc netrc hosts}@anchor{2a3c}
@deffn {Attribut} netrc.hosts

Dictionnaire faisant correspondre les noms d'hôtes dans des triplets @code{(login, account, password)}. L'entrée par défaut, le cas échéant, est représentée en tant que pseudo-hôte par ce nom.
@end deffn

@geindex macros (attribut netrc.netrc)
@anchor{library/netrc netrc netrc macros}@anchor{2a3d}
@deffn {Attribut} netrc.macros

Dictionnaire faisant correspondre les noms de macro en listes de chaînes.
@end deffn

@node plistlib --- Generate and parse Apple plist files,,netrc --- netrc file processing,Formats de fichiers
@anchor{library/plistlib doc}@anchor{2a3e}@anchor{library/plistlib module-plistlib}@anchor{aa}@anchor{library/plistlib plistlib-generate-and-parse-apple-plist-files}@anchor{2a3f}
@subsection @code{plistlib} --- Generate and parse Apple @code{.plist} files


@geindex module; plistlib

@c (harvested from docstrings in the original file)

`Code source :' Lib/plistlib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/plistlib.py}

@geindex plist;file
@geindex property list


__________________________________________________________________


This module provides an interface for reading and writing the "property list"
files used by Apple, primarily on macOS and iOS. This module supports both binary
and XML plist files.

The property list (@code{.plist}) file format is a simple serialization supporting
basic object types, like dictionaries, lists, numbers and strings.  Usually the
top level object is a dictionary.

To write out and to parse a plist file, use the @ref{93e,,dump()} and
@ref{93c,,load()} functions.

To work with plist data in bytes or string objects, use @ref{93f,,dumps()}
and @ref{93d,,loads()}.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
(but only with string keys), @ref{1bd,,bytes}, @ref{528,,bytearray}
or @ref{1c7,,datetime.datetime} objects.


Modifié dans la version 3.4: New API, old API deprecated.  Support for binary format plists added.



Modifié dans la version 3.8: Support added for reading and writing @ref{a0f,,UID} tokens in binary plists as used
by NSKeyedArchiver and NSKeyedUnarchiver.



Modifié dans la version 3.9: Old API removed.



@subsubheading Voir aussi



@table @asis

@item PList manual page@footnote{https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/}

Apple's documentation of the file format.
@end table


Ce module définit les fonctions suivantes :

@geindex load() (dans le module plistlib)
@anchor{library/plistlib plistlib load}@anchor{93c}
@deffn {Fonction} plistlib.load (fp, *, fmt=None, dict_type=dict, aware_datetime=False)

Read a plist file. `fp' should be a readable and binary file object.
Return the unpacked root object (which usually is a
dictionary).

The `fmt' is the format of the file and the following values are valid:


@itemize *

@item 
@ref{660,,None}: Autodetect the file format

@item 
@ref{f64,,FMT_XML}: XML file format

@item 
@ref{f65,,FMT_BINARY}: Binary plist format
@end itemize

The `dict_type' is the type used for dictionaries that are read from the
plist file.

When `aware_datetime' is true, fields with type @code{datetime.datetime} will
be created as @ref{23ab,,aware object}, with
@code{tzinfo} as @ref{4d8,,datetime.UTC}.

XML data for the @ref{f64,,FMT_XML} format is parsed using the Expat parser
from @ref{125,,xml.parsers.expat} -- see its documentation for possible
exceptions on ill-formed XML.  Unknown elements will simply be ignored
by the plist parser.

The parser for the binary format raises @code{InvalidFileException}
when the file cannot be parsed.


Ajouté dans la version 3.4.



Modifié dans la version 3.13: The keyword-only parameter `aware_datetime' has been added.

@end deffn

@geindex loads() (dans le module plistlib)
@anchor{library/plistlib plistlib loads}@anchor{93d}
@deffn {Fonction} plistlib.loads (data, *, fmt=None, dict_type=dict, aware_datetime=False)

Load a plist from a bytes or string object. See @ref{93c,,load()} for an
explanation of the keyword arguments.


Ajouté dans la version 3.4.



Modifié dans la version 3.13: `data' can be a string when `fmt' equals @ref{f64,,FMT_XML}.

@end deffn

@geindex dump() (dans le module plistlib)
@anchor{library/plistlib plistlib dump}@anchor{93e}
@deffn {Fonction} plistlib.dump (value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False)

Write `value' to a plist file. `Fp' should be a writable, binary
file object.

The `fmt' argument specifies the format of the plist file and can be
one of the following values:


@itemize *

@item 
@ref{f64,,FMT_XML}: XML formatted plist file

@item 
@ref{f65,,FMT_BINARY}: Binary formatted plist file
@end itemize

When `sort_keys' is true (the default) the keys for dictionaries will be
written to the plist in sorted order, otherwise they will be written in
the iteration order of the dictionary.

When `skipkeys' is false (the default) the function raises @ref{522,,TypeError}
when a key of a dictionary is not a string, otherwise such keys are skipped.

When `aware_datetime' is true and any field with type @code{datetime.datetime}
is set as an @ref{23ab,,aware object}, it will convert to
UTC timezone before writing it.

A @ref{522,,TypeError} will be raised if the object is of an unsupported type or
a container that contains objects of unsupported types.

An @ref{86d,,OverflowError} will be raised for integer values that cannot
be represented in (binary) plist files.


Ajouté dans la version 3.4.



Modifié dans la version 3.13: The keyword-only parameter `aware_datetime' has been added.

@end deffn

@geindex dumps() (dans le module plistlib)
@anchor{library/plistlib plistlib dumps}@anchor{93f}
@deffn {Fonction} plistlib.dumps (value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False)

Return `value' as a plist-formatted bytes object. See
the documentation for @ref{93e,,dump()} for an explanation of the keyword
arguments of this function.


Ajouté dans la version 3.4.

@end deffn

The following classes are available:

@geindex UID (classe dans plistlib)
@anchor{library/plistlib plistlib UID}@anchor{a0f}
@deffn {Classe} plistlib.UID (data)

Wraps an @ref{254,,int}.  This is used when reading or writing NSKeyedArchiver
encoded data, which contains UID (see PList manual).

It has one attribute, @code{data}, which can be used to retrieve the int value
of the UID.  @code{data} must be in the range @code{0 <= data < 2**64}.


Ajouté dans la version 3.8.

@end deffn

The following constants are available:

@geindex FMT_XML (dans le module plistlib)
@anchor{library/plistlib plistlib FMT_XML}@anchor{f64}
@deffn {Données} plistlib.FMT_XML

The XML format for plist files.


Ajouté dans la version 3.4.

@end deffn

@geindex FMT_BINARY (dans le module plistlib)
@anchor{library/plistlib plistlib FMT_BINARY}@anchor{f65}
@deffn {Données} plistlib.FMT_BINARY

The binary format for plist files


Ajouté dans la version 3.4.

@end deffn

@menu
* Exemples: Exemples<12>. 

@end menu

@node Exemples<12>,,,plistlib --- Generate and parse Apple plist files
@anchor{library/plistlib examples}@anchor{2a40}
@subsubsection Exemples


Generating a plist:

@example
import datetime
import plistlib

pl = dict(
    aString = "Doodah",
    aList = ["A", "B", 12, 32.1, [1, 2, 3]],
    aFloat = 0.1,
    anInt = 728,
    aDict = dict(
        anotherString = "<hello & hi there!>",
        aThirdString = "M\xe4ssig, Ma\xdf",
        aTrueValue = True,
        aFalseValue = False,
    ),
    someData = b"<binary gunk>",
    someMoreData = b"<lots of binary gunk>" * 10,
    aDate = datetime.datetime.now()
)
print(plistlib.dumps(pl).decode())
@end example

Parsing a plist:

@example
import plistlib

plist = b"""<plist version="1.0">
<dict>
    <key>foo</key>
    <string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])
@end example

@node Service de cryptographie,Services génériques du système d'exploitation,Formats de fichiers,La bibliothèque standard
@anchor{library/crypto doc}@anchor{2a41}@anchor{library/crypto crypto}@anchor{2a42}@anchor{library/crypto cryptographic-services}@anchor{2a43}
@section Service de cryptographie


@geindex cryptography

The modules described in this chapter implement various algorithms of a
cryptographic nature.  They are available at the discretion of the installation.
Here's an overview:

@menu
* hashlib: hashlib --- Algorithmes de hachage sécurisés et synthèse de messages. Algorithmes de hachage sécurisés et synthèse de
                        messages
* hmac: hmac --- Keyed-Hashing for Message Authentication. Keyed-Hashing for Message Authentication
* secrets: secrets --- Generate secure random numbers for managing secrets. Generate secure random numbers for managing secrets

@end menu

@node hashlib --- Algorithmes de hachage sécurisés et synthèse de messages,hmac --- Keyed-Hashing for Message Authentication,,Service de cryptographie
@anchor{library/hashlib doc}@anchor{2a44}@anchor{library/hashlib hashlib-secure-hashes-and-message-digests}@anchor{2a45}@anchor{library/hashlib module-hashlib}@anchor{67}
@subsection @code{hashlib} --- Algorithmes de hachage sécurisés et synthèse de messages


@geindex module; hashlib

`Code source :' Lib/hashlib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/hashlib.py}

@geindex message digest@comma{} MD5
@geindex secure hash algorithm@comma{} SHA1@comma{} SHA2@comma{} SHA224@comma{} SHA256@comma{} SHA384@comma{} SHA512@comma{} SHA3@comma{} Shake@comma{} Blake2

@c import hashlib


__________________________________________________________________


Ce module implémente une interface commune à différents algorithmes de hachage sécurisés et de synthèse de messages. Sont inclus les algorithmes standards FIPS de hachage SHA1, SHA224, SHA256, SHA384, et SHA512 (définis dans le le standard FIPS 180-4@footnote{theFIPS180-4standard}), la série SHA-3 (définis dans le standard FIPS 202@footnote{theFIPS202standard}),  ainsi que l'algorithme MD5 de RSA (défini par la 
@geindex RFC; RFC 1321
RFC 1321@footnote{https://datatracker.ietf.org/doc/html/rfc1321.html}). Les termes « algorithmes de hachage sécurisé » et « algorithme de synthèse de message » sont interchangeables. Les anciens algorithmes étaient appelés « algorithmes de synthèse de messages ». Le terme moderne est « algorithme de hachage sécurisé ».

@cartouche
@quotation Note 
Si vous préférez utiliser les fonctions de hachage `adler32' ou `crc32', elles sont disponibles dans le module @ref{132,,zlib}.
@end quotation
@end cartouche

@menu
* Algorithmes de hachage:: 
* Utilisation:: 
* Constructeurs:: 
* Attributes:: 
* Objets de calcul d'empreinte:: 
* Empreintes de messages de taille variable SHAKE:: 
* Calcul d'empreinte (ou hachage) de fichiers: Calcul d'empreinte ou hachage de fichiers. 
* Dérivation de clé:: 
* BLAKE2:: 

@end menu

@node Algorithmes de hachage,Utilisation,,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib hash-algorithms}@anchor{2a46}@anchor{library/hashlib id1}@anchor{2a47}
@subsubsection Algorithmes de hachage


Il y a un constructeur nommé selon chaque type de calcul d'empreinte (`hash'). Tous renvoient un objet haché avec la même interface. Par exemple : utilisez @ref{2a48,,sha256()} pour créer un objet de calcul d'empreinte avec l'algorithme SHA-256. Vous pouvez maintenant utiliser cet objet avec des @ref{d1b,,objets octets-compatibles} (normalement des @ref{1bd,,bytes}) en utilisant la méthode @ref{2a49,,update}. À tout moment vous pouvez demander l'empreinte (aussi appelée le `digest' ou le condensat) de la concaténation des données fournies en utilisant les méthodes @ref{2a4a,,digest()} ou @ref{2a4b,,hexdigest()}.

pour de meilleures performances avec de multiples fils d'exécution, le @ref{158,,GIL} Python est relâché pour des données dont la taille est supérieure à 2047 octets lors de leur création ou leur mise à jour (méthode @ref{2a49,,.update}.).

@geindex OpenSSL;(use in module hashlib)

Les constructeurs pour les algorithmes de hachage qui sont toujours présents dans ce module sont @ref{2a4c,,sha1()}, @ref{2a4d,,sha224()}, @ref{2a48,,sha256()}, @ref{2a4e,,sha384()}, @ref{2a4f,,sha512()}, @ref{c90,,sha3_224()}, @ref{c91,,sha3_256()}, @ref{c92,,sha3_384()}, @ref{c93,,sha3_512()}, @ref{c94,,shake_128()}, @ref{c95,,shake_256()}, @ref{62d,,blake2b()}, et @ref{62e,,blake2s()}. @ref{2a50,,md5()} est normalement disponible aussi, mais il peut être manquant ou bloqué si vous utilisez une forme rare de Python « conforme FIPS ». Cette liste correspond au résultat de la fonction @ref{134a,,algorithms_guaranteed}.

Additional algorithms may also be available if your Python distribution's
@ref{67,,hashlib} was linked against a build of OpenSSL that provides others.
Others `are not guaranteed available' on all installations and will only be
accessible by name via @ref{18d4,,new()}.  See @ref{134b,,algorithms_available}.

@cartouche
@quotation Avertissement 
Certains algorithmes ont des faiblesses connues relatives à la collision (MD5 et SHA1 inclus). Se référer à @ref{2a51,,Fonction de hachage cryptographique} et à la section Voir aussi@footnote{https://en.wikipedia.org/wiki/Cryptographic_hash_function#Attacks_on_cryptographic_hash_algorithms} à la fin du document.
@end quotation
@end cartouche


Ajouté dans la version 3.6: les constructeurs SHA3 (Keccak) et SHAKE @ref{c90,,sha3_224()}, @ref{c91,,sha3_256()}, @ref{c92,,sha3_384()}, @ref{c93,,sha3_512()}, @ref{c94,,shake_128()}, @ref{c95,,shake_256()} ont été ajoutés. @ref{62d,,blake2b()} et @ref{62e,,blake2s()} ont été ajoutés.

@anchor{library/hashlib hashlib-usedforsecurity}@anchor{2a52}

Modifié dans la version 3.9: tous les constructeurs de `hashlib' prennent un argument mot-clé uniquement `usedforsecurity' avec la valeur par défaut @code{True}. Une valeur fausse permet l'utilisation d'algorithmes de hachage non sécurisés et bloqués dans des environnements restreints. @code{False} indique que l'algorithme de hachage ne sera pas utilisé dans un contexte de sécurité, par exemple en tant que fonction de compression à sens unique non cryptographique.



Modifié dans la version 3.9: `Hashlib' utilise désormais SHA3 et SHAKE d'OpenSSL s'il les fournit.



Modifié dans la version 3.12: For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked
OpenSSL does not provide we fall back to a verified implementation from
the HACL* project@footnote{https://github.com/hacl-star/hacl-star}.


@node Utilisation,Constructeurs,Algorithmes de hachage,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib usage}@anchor{2a53}
@subsubsection Utilisation


To obtain the digest of the byte string @code{b"Nobody inspects the spammish
repetition"}:

@example
>>> import hashlib
>>> m = hashlib.sha256()
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\x03\x1e\xdd@}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
>>> m.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
@end example

En plus condensé :

@example
>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
@end example

@node Constructeurs,Attributes,Utilisation,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib constructors}@anchor{2a54}
@subsubsection Constructeurs


@geindex new() (dans le module hashlib)
@anchor{library/hashlib hashlib new}@anchor{18d4}
@deffn {Fonction} hashlib.new (name[, data], *, usedforsecurity=True)

Is a generic constructor that takes the string `name' of the desired
algorithm as its first parameter.  It also exists to allow access to the
above listed hashes as well as any other algorithms that your OpenSSL
library may offer.
@end deffn

Using @ref{18d4,,new()} with an algorithm name:

@example
>>> h = hashlib.new('sha256')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
@end example

@geindex md5() (dans le module hashlib)
@anchor{library/hashlib hashlib md5}@anchor{2a50}
@deffn {Fonction} hashlib.md5 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha1() (dans le module hashlib)
@anchor{library/hashlib hashlib sha1}@anchor{2a4c}
@deffn {Fonction} hashlib.sha1 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha224() (dans le module hashlib)
@anchor{library/hashlib hashlib sha224}@anchor{2a4d}
@deffn {Fonction} hashlib.sha224 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha256() (dans le module hashlib)
@anchor{library/hashlib hashlib sha256}@anchor{2a48}
@deffn {Fonction} hashlib.sha256 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha384() (dans le module hashlib)
@anchor{library/hashlib hashlib sha384}@anchor{2a4e}
@deffn {Fonction} hashlib.sha384 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha512() (dans le module hashlib)
@anchor{library/hashlib hashlib sha512}@anchor{2a4f}
@deffn {Fonction} hashlib.sha512 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_224() (dans le module hashlib)
@anchor{library/hashlib hashlib sha3_224}@anchor{c90}
@deffn {Fonction} hashlib.sha3_224 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_256() (dans le module hashlib)
@anchor{library/hashlib hashlib sha3_256}@anchor{c91}
@deffn {Fonction} hashlib.sha3_256 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_384() (dans le module hashlib)
@anchor{library/hashlib hashlib sha3_384}@anchor{c92}
@deffn {Fonction} hashlib.sha3_384 ([data], *, usedforsecurity=True)
@end deffn

@geindex sha3_512() (dans le module hashlib)
@anchor{library/hashlib hashlib sha3_512}@anchor{c93}
@deffn {Fonction} hashlib.sha3_512 ([data], *, usedforsecurity=True)
@end deffn

Named constructors such as these are faster than passing an algorithm name to
@ref{18d4,,new()}.

@node Attributes,Objets de calcul d'empreinte,Constructeurs,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib attributes}@anchor{2a55}
@subsubsection Attributes


`Hashlib' fournit les constantes de module suivantes :

@geindex algorithms_guaranteed (dans le module hashlib)
@anchor{library/hashlib hashlib algorithms_guaranteed}@anchor{134a}
@deffn {Données} hashlib.algorithms_guaranteed

Ensemble contenant les noms des algorithmes de hachage garantis d'être implémentés par ce module sur toutes les plate-formes. Notez que `md5' est dans cette liste bien que certains éditeurs diffusent une implémentation Python dont la bibliothèque « compatible FIPS » le bloque.


Ajouté dans la version 3.2.

@end deffn

@geindex algorithms_available (dans le module hashlib)
@anchor{library/hashlib hashlib algorithms_available}@anchor{134b}
@deffn {Données} hashlib.algorithms_available

Ensemble contenant les noms des algorithmes de hachage disponibles dans l'interpréteur Python. Ces noms sont reconnus lorsqu'ils sont passés à la fonction @ref{18d4,,new()}.  @ref{134a,,algorithms_guaranteed} est toujours un sous-ensemble. Le même algorithme peut apparaître plusieurs fois dans cet ensemble sous un nom différent (grâce à OpenSSL).


Ajouté dans la version 3.2.

@end deffn

@node Objets de calcul d'empreinte,Empreintes de messages de taille variable SHAKE,Attributes,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib hash-objects}@anchor{2a56}
@subsubsection Objets de calcul d'empreinte


Les valeurs suivantes sont fournies en tant qu'attributs constants des objets de calcul d'empreintes renvoyés par les constructeurs :

@geindex hash.digest_size (dans le module hashlib)
@anchor{library/hashlib hashlib hash digest_size}@anchor{2a57}
@deffn {Données} hash.digest_size

La taille du `hash' résultant en octets.
@end deffn

@geindex hash.block_size (dans le module hashlib)
@anchor{library/hashlib hashlib hash block_size}@anchor{2a58}
@deffn {Données} hash.block_size

La taille interne d'un bloc de l'algorithme de hachage en octets.
@end deffn

L'objet de hachage possède les attributs suivants :

@geindex name (attribut hashlib.hash)
@anchor{library/hashlib hashlib hash name}@anchor{f33}
@deffn {Attribut} hash.name

Le nom canonique de cette fonction de hachage, toujours en minuscule et que vous pouvez toujours transmettre à la fonction @ref{18d4,,new()} pour créer un autre objet de calcul d'empreinte de ce type.


Modifié dans la version 3.4: l'attribut `name' est présent dans CPython depuis sa création, mais n'était pas spécifié formellement jusqu'à Python 3.4, il peut ne pas exister sur certaines plate-formes.

@end deffn

L'objet de calcul d'empreinte possède les méthodes suivantes :

@geindex update() (méthode hashlib.hash)
@anchor{library/hashlib hashlib hash update}@anchor{2a49}
@deffn {Méthode} hash.update (data)

Met à jour l'objet de hachage avec @ref{d1b,,bytes-like object}. Les appels répétés sont équivalents à un simple appel avec la concaténation de tous les arguments : @code{m.update(a); m.update(b)} est équivalent à @code{m.update(a+b)}.
@end deffn

@geindex digest() (méthode hashlib.hash)
@anchor{library/hashlib hashlib hash digest}@anchor{2a4a}
@deffn {Méthode} hash.digest ()

Renvoie l'empreinte (le `hash') des données passées à la méthode @ref{2a49,,update()}. C'est un objet de type `bytes' de taille @ref{2a57,,digest_size} qui contient des octets dans l'intervalle 0 à 255.
@end deffn

@geindex hexdigest() (méthode hashlib.hash)
@anchor{library/hashlib hashlib hash hexdigest}@anchor{2a4b}
@deffn {Méthode} hash.hexdigest ()

Comme la méthode @ref{2a4a,,digest()} sauf que l'empreinte renvoyée est une chaîne de caractères dont la longueur est double, contenant seulement des chiffres hexadécimaux. Elle peut être utilisée pour échanger sans risque des valeurs dans les `e-mails' ou dans les environnements non binaires.
@end deffn

@geindex copy() (méthode hashlib.hash)
@anchor{library/hashlib hashlib hash copy}@anchor{2a59}
@deffn {Méthode} hash.copy ()

Renvoie une copie ("clone") de l'objet de calcul de hachage. Cela peut être utilisé pour calculer efficacement des empreintes de données qui commencent par la même sous-chaine.
@end deffn

@node Empreintes de messages de taille variable SHAKE,Calcul d'empreinte ou hachage de fichiers,Objets de calcul d'empreinte,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib shake-variable-length-digests}@anchor{2a5a}
@subsubsection Empreintes de messages de taille variable SHAKE


@geindex shake_128() (dans le module hashlib)
@anchor{library/hashlib hashlib shake_128}@anchor{c94}
@deffn {Fonction} hashlib.shake_128 ([data], *, usedforsecurity=True)
@end deffn

@geindex shake_256() (dans le module hashlib)
@anchor{library/hashlib hashlib shake_256}@anchor{c95}
@deffn {Fonction} hashlib.shake_256 ([data], *, usedforsecurity=True)
@end deffn

Les algorithmes @ref{c94,,shake_128()} et @ref{c95,,shake_256()} produisent des empreintes (ou condensats) de longueur variable avec des @code{longueurs_en_bits // 2} jusqu'à 128 ou 256 bits. Leurs méthodes de calcul d'empreinte requièrent une longueur. Les longueurs maximales ne sont pas limitées par l'algorithme SHAKE.

@geindex digest() (méthode hashlib.shake)
@anchor{library/hashlib hashlib shake digest}@anchor{19c7}
@deffn {Méthode} shake.digest (length)

Renvoie l'empreinte des données passées à la méthode @ref{2a49,,update()}. C'est un objet de type `bytes' de taille `length' qui contient des octets dans l'intervalle 0 à 255.
@end deffn

@geindex hexdigest() (méthode hashlib.shake)
@anchor{library/hashlib hashlib shake hexdigest}@anchor{19c8}
@deffn {Méthode} shake.hexdigest (length)

Comme la méthode @ref{19c7,,digest()} sauf que l'empreinte renvoyée est une chaîne de caractères dont la longueur est double, contenant seulement des chiffres hexadécimaux. Elle peut être utilisée pour échanger sans risque des valeurs dans les `e-mails' ou dans les environnements non binaires.
@end deffn

Exemple :

@example
>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'
@end example

@node Calcul d'empreinte ou hachage de fichiers,Dérivation de clé,Empreintes de messages de taille variable SHAKE,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib file-hashing}@anchor{2a5b}
@subsubsection Calcul d'empreinte (ou hachage) de fichiers


Le module `hashlib' fournit une fonction utilitaire pour calculer efficacement l'empreinte (aussi appelée condensat) d'un fichier ou d'un objet fichier-compatible.

@geindex file_digest() (dans le module hashlib)
@anchor{library/hashlib hashlib file_digest}@anchor{62f}
@deffn {Fonction} hashlib.file_digest (fileobj, digest, /)

Renvoie un objet de calcul d'empreinte qui a été mis à jour avec le contenu de `fileobj'.

`fileobj' doit être un objet fichier-compatible ouvert en lecture en mode binaire. Sont acceptés les instances d'objets fichiers produites par la fonction native  @ref{505,,open()}, @ref{e8d,,BytesIO}, les objets connecteurs produits par  @ref{117d,,socket.socket.makefile()} et similaires. La fonction peut court-circuiter les entrées-sorties de Python et utiliser directement le descripteur de fichier de @ref{27cf,,fileno()}. Vous devez supposer que `fileobj' est dans un état inconnu après le retour de cette fonction ou si elle a levé une exception. C'est à l'appelant de fermer `fileobj'.

`digest' doit être un nom d'algorithme de hachage fourni en tant que `str', un constructeur de hachage ou un appelable qui renvoie un objet de hachage.

Exemple :

@example
>>> import io, hashlib, hmac
>>> with open(hashlib.__file__, "rb") as f:
...     digest = hashlib.file_digest(f, "sha256")
...
>>> digest.hexdigest()  
'...'
@end example

@example
>>> buf = io.BytesIO(b"somedata")
>>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)
>>> digest = hashlib.file_digest(buf, lambda: mac1)
@end example

@example
>>> digest is mac1
True
>>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)
>>> mac1.digest() == mac2.digest()
True
@end example


Ajouté dans la version 3.11.

@end deffn

@node Dérivation de clé,BLAKE2,Calcul d'empreinte ou hachage de fichiers,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib key-derivation}@anchor{2a5c}
@subsubsection Dérivation de clé


Les algorithmes de dérivation de clés et d'étirement de clés sont conçus pour le hachage sécurisé de mots de passe. Des algorithmes naïfs comme @code{sha1(password)} ne sont pas résistants aux attaques par force brute. Une bonne fonction de hachage doit être paramétrable, lente et inclure un salage@footnote{https://fr.wikipedia.org/wiki/Salage_(cryptographie)}.

@geindex pbkdf2_hmac() (dans le module hashlib)
@anchor{library/hashlib hashlib pbkdf2_hmac}@anchor{4f8}
@deffn {Fonction} hashlib.pbkdf2_hmac (hash_name, password, salt, iterations, dklen=None)

La fonction fournit une fonction de dérivation conforme à PKCS#5 (`Public Key Cryptographic Standards #5 v2.0'). Elle utilise HMAC comme fonction de génération d'un pseudo-aléa.

La chaîne de caractères `hash_name' est le nom de l'algorithme de hachage désiré pour le HMAC, par exemple @code{"sha1"} ou @code{"sha256"}. `password' et `salt' sont interprétés comme des tampons d'octets. Les applications et bibliothèques doivent limiter `password' à une longueur raisonnable (comme @code{1024}). `salt' doit être de 16 octets ou plus et provenir d'une source correcte, e.g. @ref{50c,,os.urandom()}.

Le nombre d'`itérations' doit être choisi en fonction de l'algorithme de hachage et de la puissance de calcul. À partir de 2022, des centaines de milliers d'itérations de SHA-256 sont suggérées. Pour savoir pourquoi et comment choisir ce qui convient le mieux à votre application, lisez `l'annexe A.2.2' du NIST-SP-800-132@footnote{https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf} (ressource en anglais). Les réponses contenues dans la question sur le site `stackexchange' nombre d'itérations recommandées lorsqu'on utilise pbkdf2@footnote{https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/} (page en anglais) expliquent tout en détail.

`dklen' est la longueur de la clé dérivée. Si `dklen' vaut @code{None} alors Python utilise la taille du condensat produit par l'algorithme de hachage `hash_name', par exemple 64 pour SHA-512.

@example
>>> from hashlib import pbkdf2_hmac
>>> our_app_iters = 500_000  # Application specific, read above.
>>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt' * 2, our_app_iters)
>>> dk.hex()
'15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'
@end example

Function only available when Python is compiled with OpenSSL.


Ajouté dans la version 3.4.



Modifié dans la version 3.12: Function now only available when Python is built with OpenSSL. The slow
pure Python implementation has been removed.

@end deffn

@geindex scrypt() (dans le module hashlib)
@anchor{library/hashlib hashlib scrypt}@anchor{c2c}
@deffn {Fonction} hashlib.scrypt (password, *, salt, n, r, p, maxmem=0, dklen=64)

La fonction fournit la fonction de dérivation de clé `scrypt' comme définie dans la 
@geindex RFC; RFC 7914
RFC 7914@footnote{https://datatracker.ietf.org/doc/html/rfc7914.html}.

`password' et `salt' doivent être des @ref{d1b,,objets octets-compatibles}. Les applications et bibliothèques doivent limiter `password' à une longueur raisonnable (par ex. 1024). `salt' doit être de 16 octets ou plus et provenir d'une source correcte, par ex. @ref{50c,,os.urandom()}.

`n' est le facteur de coût CPU/Mémoire, `r' la taille de bloc, `p' le facteur de parallélisation et `maxmem' limite l'utilisation de la mémoire (OpenSSL 1.1.0 limite à 32 Mio par défaut). `dklen' est la longueur de la clé dérivée en octets.


Ajouté dans la version 3.6.

@end deffn

@node BLAKE2,,Dérivation de clé,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages
@anchor{library/hashlib blake2}@anchor{2a5d}@anchor{library/hashlib hashlib-blake2}@anchor{1d1b}
@subsubsection BLAKE2


@geindex blake2b@comma{} blake2s

BLAKE2@footnote{https://www.blake2.net} est une fonction de hachage cryptographique définie dans la 
@geindex RFC; RFC 7693
RFC 7693@footnote{https://datatracker.ietf.org/doc/html/rfc7693.html} et disponible en deux versions :


@itemize *

@item 
`BLAKE2b', optimisée pour les plates-formes 64 bits et produisant des condensats de toutes tailles entre 1 et 64 octets,

@item 
`BLAKE2s', optimisée pour les plates-formes de 8 à 32 bits et produisant des empreintes de toutes tailles entre 1 et 32 octets.
@end itemize

BLAKE2 gère diverses fonctionnalités comme le `keyed mode' (plus rapide et plus simple que HMAC@footnote{https://en.wikipedia.org/wiki/Hash-based_message_authentication_code}), `salted hashing', `personalization' et le `tree hashing'.

Les objets de calcul d'empreinte de ce module suivent l'API des objets du module @ref{67,,hashlib} de la bibliothèque standard.

@menu
* Création d'objets de calcul d'empreinte:: 
* Constantes: Constantes<5>. 
* Exemples: Exemples<13>. 
* Crédits:: 

@end menu

@node Création d'objets de calcul d'empreinte,Constantes<5>,,BLAKE2
@anchor{library/hashlib creating-hash-objects}@anchor{2a5e}
@subsubsection Création d'objets de calcul d'empreinte


Les nouveaux objets de calcul d'empreinte sont créés en appelant les constructeurs :

@geindex blake2b() (dans le module hashlib)
@anchor{library/hashlib hashlib blake2b}@anchor{62d}
@deffn {Fonction} hashlib.blake2b (data=b'@w{'}, *, digest_size=64, key=b'@w{'}, salt=b'@w{'}, person=b'@w{'}, fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)
@end deffn

@geindex blake2s() (dans le module hashlib)
@anchor{library/hashlib hashlib blake2s}@anchor{62e}
@deffn {Fonction} hashlib.blake2s (data=b'@w{'}, *, digest_size=32, key=b'@w{'}, salt=b'@w{'}, person=b'@w{'}, fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)
@end deffn

Ces fonctions produisent l'objet de calcul d'empreinte correspondant aux algorithmes BLAKE2b ou BLAKE2s. Elles prennent ces paramètres optionnels :


@itemize *

@item 
`data' : morceau initial de données à hacher, qui doit être un @ref{d1b,,objet octets-compatible}. Il ne peut être passé que comme argument positionnel.

@item 
`digest_size' : taille en octets de l'empreinte produite.

@item 
`key' : clé pour les codes d'authentification de message `keyed hashing' (jusqu'à 64 octets pour BLAKE2b, jusqu'à 32 octets pour BLAKE2s).

@item 
`salt' : sel pour le hachage randomisé `randomized hashing' (jusqu'à 16 octets pour BLAKE2b, jusqu'à 8 octets pour BLAKE2s).

@item 
`person' : chaîne de personnalisation (jusqu'à 16 octets pour BLAKE2b, jusqu'à 8 octets pour BLAKE2s).
@end itemize

Le tableau suivant présente les limites des paramètres généraux (en octets) :


@multitable {xxxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxx} 
@headitem

Hash

@tab

digest_size

@tab

len(key)

@tab

len(salt)

@tab

len(person)

@item

BLAKE2b

@tab

64

@tab

64

@tab

16

@tab

16

@item

BLAKE2s

@tab

32

@tab

32

@tab

8

@tab

8

@end multitable


@cartouche
@quotation Note 
les spécifications de BLAKE2 définissent des longueurs constantes pour les sel et chaînes de personnalisation. Toutefois, par commodité, cette implémentation accepte des chaînes d'octets de n'importe quelle taille jusqu'à la longueur spécifiée. Si la longueur du paramètre est moindre par rapport à celle spécifiée, il est complété par des zéros. Ainsi, par exemple, @code{b'salt'} et @code{b'salt\x00'} sont la même valeur (ce n'est pas le cas pour `key').
@end quotation
@end cartouche

Ces tailles sont disponibles en tant que @ref{2a5f,,constantes} du module et décrites ci-dessous.

Les fonctions constructeurs acceptent aussi les paramètres suivants pour le calcul d'empreintes en mode arbre :


@itemize *

@item 
`fanout' : `étalement' (0 à 255, 0 si illimité, 1 correspond au mode séquentiel).

@item 
`depth' : profondeur maximale de l'arbre (1 à 255, 255 si illimité, 1 correspond au mode séquentiel).

@item 
`leaf_size' : taille maximale en octets d'une feuille (0 à @code{2**32-1}, 0 si illimité ou en mode séquentiel).

@item 
`node_offset' : décalage du nœud (0 à @code{2**64-1} pour BLAKE2b, 0 à @code{2**48-1} pour BLAKE2s, 0 pour la première feuille la plus à gauche, ou en mode séquentiel).

@item 
`node_depth' : profondeur du nœud (0 à 255, 0 pour les feuilles, ou en mode séquentiel).

@item 
`inner_size' : taille de l'empreinte interne (0 à 64 pour BLAKE2b, 0 à 32 pour BLAKE2s, 0 en mode séquentiel).

@item 
`last_node' : booléen indiquant si le nœud traité est le dernier (@code{False} pour le mode séquentiel).
@end itemize


@float Figure

@image{python-figures/hashlib-blake2-tree,,,Explication des paramètres du mode arbre.,png}

@end float


Voir la section 2.10 dans BLAKE2 specification@footnote{https://blake2.net/blake2_20130129.pdf} pour une approche globale du hachage en mode arbre.

@node Constantes<5>,Exemples<13>,Création d'objets de calcul d'empreinte,BLAKE2
@anchor{library/hashlib constants}@anchor{2a5f}
@subsubsection Constantes


@geindex blake2b.SALT_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2b SALT_SIZE}@anchor{2a60}
@deffn {Données} blake2b.SALT_SIZE
@end deffn

@geindex blake2s.SALT_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2s SALT_SIZE}@anchor{2a61}
@deffn {Données} blake2s.SALT_SIZE
@end deffn

Longueur du sel (longueur maximale acceptée par les constructeurs).

@geindex blake2b.PERSON_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2b PERSON_SIZE}@anchor{2a62}
@deffn {Données} blake2b.PERSON_SIZE
@end deffn

@geindex blake2s.PERSON_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2s PERSON_SIZE}@anchor{2a63}
@deffn {Données} blake2s.PERSON_SIZE
@end deffn

Longueur de la chaîne de personnalisation (longueur maximale acceptée par les constructeurs).

@geindex blake2b.MAX_KEY_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2b MAX_KEY_SIZE}@anchor{2a64}
@deffn {Données} blake2b.MAX_KEY_SIZE
@end deffn

@geindex blake2s.MAX_KEY_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2s MAX_KEY_SIZE}@anchor{2a65}
@deffn {Données} blake2s.MAX_KEY_SIZE
@end deffn

Taille maximale de clé.

@geindex blake2b.MAX_DIGEST_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2b MAX_DIGEST_SIZE}@anchor{2a66}
@deffn {Données} blake2b.MAX_DIGEST_SIZE
@end deffn

@geindex blake2s.MAX_DIGEST_SIZE (dans le module hashlib)
@anchor{library/hashlib hashlib blake2s MAX_DIGEST_SIZE}@anchor{2a67}
@deffn {Données} blake2s.MAX_DIGEST_SIZE
@end deffn

Taille maximale du message que peut fournir la fonction de hachage.

@node Exemples<13>,Crédits,Constantes<5>,BLAKE2
@anchor{library/hashlib examples}@anchor{2a68}
@subsubsection Exemples


@menu
* Hachage simple:: 
* Production de tailles d'empreintes différentes:: 
* Hachage avec clé – Code d'authentification de message:: 
* Hachage randomisé:: 
* Personnalisation: Personnalisation<2>. 
* Mode Arbre:: 

@end menu

@node Hachage simple,Production de tailles d'empreintes différentes,,Exemples<13>
@anchor{library/hashlib simple-hashing}@anchor{2a69}
@subsubsection Hachage simple


Pour calculer l'empreinte (ou `hash') d'une quantité de données, vous devez d'abord construire un objet de calcul d'empreinte en appelant la fonction constructeur appropriée (@ref{62d,,blake2b()} or @ref{62e,,blake2s()}), ensuite le mettre à jour avec les données en appelant la méthode @ref{2a49,,update()} sur l'objet, et, pour finir, récupérer l'empreinte du message en appelant la méthode @ref{2a4a,,digest()} (ou @ref{2a4b,,hexdigest()} pour les chaînes hexadécimales).

@example
>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

En plus court, vous pouvez passer directement au constructeur, comme argument positionnel, le premier morceau du message pour le mettre directement à jour :

@example
>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

Vous pouvez appeler la méthode @ref{2a49,,hash.update()} autant de fois que nécessaire pour mettre à jour l'empreinte de manière itérative :

@example
>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
...     h.update(item)
...
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
@end example

@node Production de tailles d'empreintes différentes,Hachage avec clé – Code d'authentification de message,Hachage simple,Exemples<13>
@anchor{library/hashlib using-different-digest-sizes}@anchor{2a6a}
@subsubsection Production de tailles d'empreintes différentes


BLAKE2 permet de configurer la taille des empreintes jusqu'à 64 octets pour BLAKE2b et jusqu'à 32 octets pour BLAKE2s. Par exemple, pour remplacer SHA-1 par BLAKE2b sans changer la taille de la sortie, nous pouvons dire à BLAKE2b de produire une empreinte de 20 octets :

@example
>>> from hashlib import blake2b
>>> h = blake2b(digest_size=20)
>>> h.update(b'Replacing SHA1 with the more secure function')
>>> h.hexdigest()
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
>>> h.digest_size
20
>>> len(h.digest())
20
@end example

Les objets de calcul d'empreinte initialisés avec des tailles d'empreintes différentes ont des sorties complètement différentes (les condensats courts `ne sont pas' des préfixes de condensats plus longs) ; BLAKE2b et BLAKE2s produisent des sorties différentes même si les longueurs de sortie sont les mêmes :

@example
>>> from hashlib import blake2b, blake2s
>>> blake2b(digest_size=10).hexdigest()
'6fa1d8fcfd719046d762'
>>> blake2b(digest_size=11).hexdigest()
'eb6ec15daf9546254f0809'
>>> blake2s(digest_size=10).hexdigest()
'1bf21a98c78a1c376ae9'
>>> blake2s(digest_size=11).hexdigest()
'567004bf96e4a25773ebf4'
@end example

@node Hachage avec clé – Code d'authentification de message,Hachage randomisé,Production de tailles d'empreintes différentes,Exemples<13>
@anchor{library/hashlib keyed-hashing}@anchor{2a6b}
@subsubsection Hachage avec clé – Code d'authentification de message


Le hachage avec clé (`keyed hashing' en anglais) est une alternative plus simple et plus rapide à un code d’authentification de message de hachage à clé@footnote{https://fr.wikipedia.org/wiki/Keyed-hash_message_authentication_code} (HMAC). BLAKE2 peut être utilisé de manière sécurisée dans le mode préfixe MAC grâce à la propriété d'indifférentiabilité héritée de BLAKE.

Cet exemple montre comment obtenir un code d'authentification de message de 128 bits (en hexadécimal) pour un message @code{b'message data'} avec la clé @code{b'pseudorandom key'} :

@example
>>> from hashlib import blake2b
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
>>> h.update(b'message data')
>>> h.hexdigest()
'3d363ff7401e02026f4a4687d4863ced'
@end example

Comme exemple pratique, une application web peut chiffrer symétriquement les `cookies' envoyés aux utilisateurs et les vérifier plus tard pour être certaine qu'ils n'ont pas été altérés :

@example
>>> from hashlib import blake2b
>>> from hmac import compare_digest
>>>
>>> SECRET_KEY = b'pseudorandomly generated server secret key'
>>> AUTH_SIZE = 16
>>>
>>> def sign(cookie):
...     h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
...     h.update(cookie)
...     return h.hexdigest().encode('utf-8')
>>>
>>> def verify(cookie, sig):
...     good_sig = sign(cookie)
...     return compare_digest(good_sig, sig)
>>>
>>> cookie = b'user-alice'
>>> sig = sign(cookie)
>>> print("@{0@},@{1@}".format(cookie.decode('utf-8'), sig))
user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
>>> verify(cookie, sig)
True
>>> verify(b'user-bob', sig)
False
>>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
False
@end example

Même s'il possède en natif la création de code d'authentification de message (MAC), BLAKE2 peut, bien sûr, être utilisé pour construire un HMAC en combinaison avec le module @ref{69,,hmac} :

@example
>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'
@end example

@node Hachage randomisé,Personnalisation<2>,Hachage avec clé – Code d'authentification de message,Exemples<13>
@anchor{library/hashlib randomized-hashing}@anchor{2a6c}
@subsubsection Hachage randomisé


En définissant le paramètre `salt' les utilisateurs peuvent introduire de l'aléatoire dans la fonction de hachage. Le hachage randomisé est utile pour se protéger des attaques par collisions sur les fonctions de hachage utilisées dans les signatures numériques.

@quotation

Le hachage aléatoire est conçu pour les situations où une partie, le préparateur du message, génère tout ou partie d'un message à signer par une seconde partie, le signataire du message. Si le préparateur du message est capable de trouver des collisions sur la fonction cryptographique de hachage (c.-à-d. deux messages produisant la même valeur une fois hachés), alors il peut préparer plusieurs versions du message, ayant un sens, qui produiront les mêmes empreintes et même signature mais avec des résultats différents (par exemple transférer 1 000 000 $ sur un compte plutôt que 10 $). Les fonctions cryptographiques de hachage ont été conçues avec comme but premier de résister aux collisions, mais la concentration actuelle d'attaques sur les fonctions de hachage peut avoir pour conséquence qu'une fonction de hachage donnée soit moins résistante qu'attendu. Le hachage aléatoire offre au signataire une protection supplémentaire en réduisant la probabilité que le préparateur puisse générer deux messages ou plus qui renverront la même empreinte lors du processus de génération de la signature — même s'il existe un moyen pratique de trouver des collisions sur la fonction de hachage. Toutefois, l'utilisation du hachage aléatoire peut réduire le niveau de sécurité fourni par une signature numérique si  tous les morceaux du message sont préparés par le signataire.

(NIST SP-800-106 "Randomized Hashing for Digital Signatures"@footnote{https://csrc.nist.gov/pubs/sp/800/106/final}, article en anglais)
@end quotation

Dans BLAKE2, le sel est passé une seule fois lors de l'initialisation de la fonction de hachage, plutôt qu'à chaque appel de la fonction de hachage.

@cartouche
@quotation Avertissement 
`Salted hashing' (ou un hachage simple) avec BLAKE2 ou toute autre fonction de hachage générique, comme SHA-256, ne convient pas pour obscurcir des mots de passe. Voir la FAQ BLAKE2@footnote{https://blake2.net/#qa} (page en anglais) pour plus d'informations.
@end quotation
@end cartouche


@example
>>> import os
>>> from hashlib import blake2b
>>> msg = b'some message'
>>> # Calculate the first hash with a random salt.
>>> salt1 = os.urandom(blake2b.SALT_SIZE)
>>> h1 = blake2b(salt=salt1)
>>> h1.update(msg)
>>> # Calculate the second hash with a different random salt.
>>> salt2 = os.urandom(blake2b.SALT_SIZE)
>>> h2 = blake2b(salt=salt2)
>>> h2.update(msg)
>>> # The digests are different.
>>> h1.digest() != h2.digest()
True
@end example

@node Personnalisation<2>,Mode Arbre,Hachage randomisé,Exemples<13>
@anchor{library/hashlib personalization}@anchor{2a6d}
@subsubsection Personnalisation


Parfois il est utile de forcer une fonction de hachage à produire différentes empreintes de message d'une même entrée pour différentes utilisations. Pour citer les auteurs de la fonction de hachage Skein :

@quotation

Nous recommandons que tous les développeurs d'application considèrent sérieusement de faire cela ; nous avons vu de nombreux protocoles où une empreinte était calculée à un endroit du protocole pour être utilisée à un autre endroit car deux calculs d'empreintes étaient réalisés sur des données similaires ou liées, et qu'un attaquant peut forcer une application à prendre en entrée la même empreinte. Personnaliser chaque fonction de hachage utilisée dans le protocole stoppe immédiatement ce genre d'attaque.

(The Skein Hash Function Family@footnote{https://www.schneier.com/wp-content/uploads/2016/02/skein.pdf}, p. 21, article en anglais)
@end quotation

BLAKE2 peut être personnalisé en passant des `bytes' à l'argument `person' :

@example
>>> from hashlib import blake2b
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'
@end example

La personnalisation et le `keyed mode' peuvent être utilisés ensemble pour dériver différentes clés à partir d'une seule.

@example
>>> from hashlib import blake2s
>>> from base64 import b64decode, b64encode
>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
>>> print(b64encode(enc_key).decode('utf-8'))
rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
>>> print(b64encode(mac_key).decode('utf-8'))
G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=
@end example

@node Mode Arbre,,Personnalisation<2>,Exemples<13>
@anchor{library/hashlib tree-mode}@anchor{2a6e}
@subsubsection Mode Arbre


L'exemple ci-dessous présente comment hacher un arbre minimal avec deux nœuds terminaux :

@example
  10
 /  \
00  01
@end example

Cet exemple utilise en interne des empreintes de 64 octets, et produit finalement des empreintes 32 octets :

@example
>>> from hashlib import blake2b
>>>
>>> FANOUT = 2
>>> DEPTH = 2
>>> LEAF_SIZE = 4096
>>> INNER_SIZE = 64
>>>
>>> buf = bytearray(6000)
>>>
>>> # Left leaf
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=0, last_node=False)
>>> # Right leaf
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=1, node_depth=0, last_node=True)
>>> # Root node
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=1, last_node=True)
>>> h10.update(h00.digest())
>>> h10.update(h01.digest())
>>> h10.hexdigest()
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'
@end example

@node Crédits,,Exemples<13>,BLAKE2
@anchor{library/hashlib credits}@anchor{2a6f}
@subsubsection Crédits


BLAKE2@footnote{https://www.blake2.net} a été conçu par `Jean-Philippe Aumasson', `Samuel Neves', `Zooko Wilcox-O'Hearn', et `Christian Winnerlein'. Il est basé la version BLAKE@footnote{https://web.archive.org/web/20200918190133/https://131002.net/blake/} qui a participé à la finale de la compétition du NIST SHA-3@footnote{https://en.wikipedia.org/wiki/Secure_Hash_Algorithms} créée par `Jean-Philippe Aumasson', `Luca Henzen', `Willi Meier', et `Raphael C.-W. Phan'.

Il utilise le cœur de l'algorithme de chiffrement de ChaCha@footnote{https://cr.yp.to/chacha.html} conçu par `Daniel J.  Bernstein'.

L'implémentation dans la bibliothèque standard est basée sur le module pyblake2@footnote{https://pythonhosted.org/pyblake2/}. Elle a été écrite par `Dmitry Chestnykh' et est basée sur l'implémentation C écrite par `Samuel Neves'. La documentation a été copiée depuis pyblake2@footnote{https://pythonhosted.org/pyblake2/} et écrite par `Dmitry Chestnykh'.

Le code C a été partiellement réécrit pour Python par `Christian Heimes'.

Le transfert dans le domaine public s'applique pour l'implémentation C de la fonction de hachage, ses extensions et cette documentation :

@quotation

Tout en restant dans les limites de la loi, le(s) auteur(s) a (ont) donné tous les droits d’auteur et droits connexes et voisins de ce logiciel au domaine public dans le monde entier. Ce logiciel est distribué sans aucune garantie.

Vous devriez recevoir avec ce logiciel une copie de la licence `CC0 Public Domain Dedication'. Sinon, voir @indicateurl{https://creativecommons.org/publicdomain/zero/1.0/}.
@end quotation

Les personnes suivantes ont aidé au développement ou contribué aux modifications du projet et au domaine public selon la licence Creative Commons Public Domain Dedication 1.0 Universal :


@itemize *

@item 
`Alexandr Sokolovskiy'
@end itemize
@anchor{library/hashlib hashlib-seealso}@anchor{2a51}

@subsubheading Voir aussi



@table @asis

@item Module @ref{69,,hmac}

Un module pour générer des codes d'authentification utilisant des `hash'.

@item Module @ref{e,,base64}

Un autre moyen d'encoder des `hash' binaires dans des environnements non binaires.

@item @indicateurl{https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf}

La publication FIPS 180-4 sur les algorithmes de hachage sécurisés.

@item @indicateurl{https://csrc.nist.gov/pubs/fips/202/final}

La publication FIPS 202 sur le standard SHA-3.

@item @indicateurl{https://www.blake2.net/}

Site officiel de BLAKE2.

@item @indicateurl{https://en.wikipedia.org/wiki/Cryptographic_hash_function}

Article Wikipedia contenant les informations relatives aux algorithmes ayant des problèmes et leur interprétation au regard de leur utilisation.

@item @indicateurl{https://www.ietf.org/rfc/rfc8018.txt}

PKCS #5 : Password-Based Cryptography Specification Version 2.1

@item @indicateurl{https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf}

Recommandations du NIST pour la dérivation de clé à partir de mot de passe (ressource en anglais).
@end table


@node hmac --- Keyed-Hashing for Message Authentication,secrets --- Generate secure random numbers for managing secrets,hashlib --- Algorithmes de hachage sécurisés et synthèse de messages,Service de cryptographie
@anchor{library/hmac doc}@anchor{2a70}@anchor{library/hmac hmac-keyed-hashing-for-message-authentication}@anchor{2a71}@anchor{library/hmac module-hmac}@anchor{69}
@subsection @code{hmac} --- Keyed-Hashing for Message Authentication


@geindex module; hmac

`Code source :' Lib/hmac.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/hmac.py}


__________________________________________________________________


Ce module implémente l'algorithme HMAC tel que décrit par la 
@geindex RFC; RFC 2104
RFC 2104@footnote{https://datatracker.ietf.org/doc/html/rfc2104.html}.

@geindex new() (dans le module hmac)
@anchor{library/hmac hmac new}@anchor{a8d}
@deffn {Fonction} hmac.new (key, msg=None, digestmod)

Renvoie un nouvel objet HMAC.  `key' est un objet `byte' ou `bytearray' représentant la clé secrète.  Si `msg' est présent, un appel à @code{update(msg)} est effectué. `digestmod' permet de choisir l’algorithme à utiliser par l’objet HMAC, il accepte un nom de fonction de hachage (peut être tout ce qui convient à @ref{18d4,,hashlib.new()}), un constructeur de fonction de hachage ou un module implémentant la PEP 247. Bien qu’il soit après `msg', `digestmod' est un paramètre obligatoire.


Modifié dans la version 3.4: Le paramètre `key' peut être un `byte' ou un objet `bytearray'. Le paramètre `msg' peut être de n'importe quel type pris en charge par @ref{67,,hashlib}. Le paramètre `digestmod' peut être le nom d'un algorithme de hachage.



Modifié dans la version 3.8: The `digestmod' argument is now required.  Pass it as a keyword
argument to avoid awkwardness when you do not have an initial `msg'.

@end deffn

@geindex digest() (dans le module hmac)
@anchor{library/hmac hmac digest}@anchor{b2c}
@deffn {Fonction} hmac.digest (key, msg, digest)

Renvoie le code d'authentification de `msg', pour la clé secrète `key' et à l'algorithme `digest' donné. La fonction est équivalente à @code{HMAC(key, msg, digest).digest()}, mais elle utilise une implémentation optimisée en C ou `inline', qui est plus rapide pour les messages dont la taille leur permet de tenir en mémoire vive. Les paramètres `key', `msg' et `digest' ont la même signification que pour @ref{a8d,,new()}.

Détail d'implémentation CPython, l'implémentation C optimisée n'est utilisée que lorsque le `digest' est une chaîne de caractères et le nom d'un algorithme de hachage implémenté dans OpenSSL.


Ajouté dans la version 3.7.

@end deffn

Un objet HMAC a les méthodes suivantes :

@geindex update() (méthode hmac.HMAC)
@anchor{library/hmac hmac HMAC update}@anchor{f35}
@deffn {Méthode} HMAC.update (msg)

Met à jour l'objet HMAC avec `msg'. Des appels répétés sont équivalents à un seul appel avec la concaténation de tous les arguments : @code{m.update(a); m.update(b)} est équivalent à @code{m.update(a + b)}.


Modifié dans la version 3.4: Le paramètre `msg' peut être de n'importe quel type géré par @ref{67,,hashlib}.

@end deffn

@geindex digest() (méthode hmac.HMAC)
@anchor{library/hmac hmac HMAC digest}@anchor{2a72}
@deffn {Méthode} HMAC.digest ()

Renvoie le condensat des octets passés à la méthode @ref{f35,,update()} jusque là. L'objet `bytes' renvoyé sera de la même longueur que la `digest_size' de la fonction de hachage donnée au constructeur. Il peut contenir des octets qui ne sont pas dans la table ASCII, y compris des octets NUL.

@cartouche
@quotation Avertissement 
When comparing the output of @ref{b2c,,digest()} to an externally supplied
digest during a verification routine, it is recommended to use the
@ref{10ab,,compare_digest()} function instead of the @code{==} operator
to reduce the vulnerability to timing attacks.
@end quotation
@end cartouche
@end deffn

@geindex hexdigest() (méthode hmac.HMAC)
@anchor{library/hmac hmac HMAC hexdigest}@anchor{2a73}
@deffn {Méthode} HMAC.hexdigest ()

Comme @ref{b2c,,digest()} sauf que ce condensat est renvoyé en tant que chaîne de caractères de taille doublée contenant seulement des chiffres hexadécimaux. Cela permet d’échanger le résultat sans problèmes par e-mail ou dans d'autres environnements ne gérant pas les données binaires.

@cartouche
@quotation Avertissement 
When comparing the output of @ref{2a73,,hexdigest()} to an externally supplied
digest during a verification routine, it is recommended to use the
@ref{10ab,,compare_digest()} function instead of the @code{==} operator
to reduce the vulnerability to timing attacks.
@end quotation
@end cartouche
@end deffn

@geindex copy() (méthode hmac.HMAC)
@anchor{library/hmac hmac HMAC copy}@anchor{2a74}
@deffn {Méthode} HMAC.copy ()

Renvoie une copie (un clone) de l'objet HMAC. C'est utile pour calculer de manière efficace les empreintes cryptographiques de chaînes de caractères qui ont en commun une sous-chaîne initiale.
@end deffn

Un objet `code d'authentification de message' (HMAC) possède les attributs suivants :

@geindex digest_size (attribut hmac.HMAC)
@anchor{library/hmac hmac HMAC digest_size}@anchor{f38}
@deffn {Attribut} HMAC.digest_size

La taille du code d'authentification (c.-à-d. de l'empreinte cryptographique) en octets.
@end deffn

@geindex block_size (attribut hmac.HMAC)
@anchor{library/hmac hmac HMAC block_size}@anchor{f36}
@deffn {Attribut} HMAC.block_size

La taille interne d'un bloc de l'algorithme de hachage en octets.


Ajouté dans la version 3.4.

@end deffn

@geindex name (attribut hmac.HMAC)
@anchor{library/hmac hmac HMAC name}@anchor{f37}
@deffn {Attribut} HMAC.name

Le nom canonique de ce HMAC, toujours en lettres minuscules, par exemple @code{hmac-md5}.


Ajouté dans la version 3.4.

@end deffn


Modifié dans la version 3.10: Removed the undocumented attributes @code{HMAC.digest_cons}, @code{HMAC.inner},
and @code{HMAC.outer}.


Ce module fournit également la fonction utilitaire suivante :

@geindex compare_digest() (dans le module hmac)
@anchor{library/hmac hmac compare_digest}@anchor{10ab}
@deffn {Fonction} hmac.compare_digest (a, b)

Renvoie @code{a == b}. Cette fonction a été conçue pour prévenir les attaques temporelles en évitant l'implémentation de courts-circuits basés sur le contenu, ce qui la rend appropriée pour de la cryptographie. `a' et `b' doivent être du même type : soit @ref{435,,str} (caractères ASCII seulement, comme retourné par @ref{2a73,,HMAC.hexdigest()} par exemple), ou @ref{d1b,,bytes-like object}.

@cartouche
@quotation Note 
Si `a' et `b' sont de longueurs différentes ou si une erreur se produit, une attaque temporelle pourrait en théorie obtenir des informations sur les types et longueurs de `a' et de `b', mais pas sur leurs valeurs.
@end quotation
@end cartouche


Ajouté dans la version 3.3.



Modifié dans la version 3.10: Cette fonction utilise la fonction @code{CRYPTO_memcmp()} de OpenSSL quand celle-ci est disponible.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{67,,hashlib}

Le module Python fournissant des fonctions de hachage sécurisé.
@end table


@node secrets --- Generate secure random numbers for managing secrets,,hmac --- Keyed-Hashing for Message Authentication,Service de cryptographie
@anchor{library/secrets doc}@anchor{2a75}@anchor{library/secrets module-secrets}@anchor{bf}@anchor{library/secrets secrets-generate-secure-random-numbers-for-managing-secrets}@anchor{2a76}
@subsection @code{secrets} --- Generate secure random numbers for managing secrets


@geindex module; secrets


Ajouté dans la version 3.6.


@c from secrets import *
@c __name__ = '<doctest>'

`Code source :' Lib/secrets.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/secrets.py}


__________________________________________________________________


Le module @ref{bf,,secrets} permet de générer des nombres aléatoires forts au sens de la cryptographie, adaptés à la gestion des mots de passe, à l'authentification des comptes, à la gestion des jetons de sécurité et des secrets associés.

Il faut préférer @ref{bf,,secrets} par rapport au générateur pseudo-aléatoire du module @ref{b7,,random}, ce dernier étant conçu pour la modélisation et la simulation, et non pour la sécurité ou la cryptographie.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 506
PEP 506@footnote{https://peps.python.org/pep-0506/}


@menu
* Nombres aléatoires:: 
* Génération de jetons:: 
* Autres fonctions:: 
* Recettes et bonnes pratiques:: 

@end menu

@node Nombres aléatoires,Génération de jetons,,secrets --- Generate secure random numbers for managing secrets
@anchor{library/secrets random-numbers}@anchor{2a77}
@subsubsection Nombres aléatoires


Le module @ref{bf,,secrets} fournit un accès à la source d'aléa la plus sûre disponible sur votre système d'exploitation.

@geindex SystemRandom (classe dans secrets)
@anchor{library/secrets secrets SystemRandom}@anchor{2a78}
@deffn {Classe} secrets.SystemRandom

Classe permettant de générer des nombres aléatoires à partir des sources d'aléa les plus sûres fournies par le système d'exploitation. Se référer à @ref{2662,,random.SystemRandom} pour plus de détails.
@end deffn

@geindex choice() (dans le module secrets)
@anchor{library/secrets secrets choice}@anchor{2a79}
@deffn {Fonction} secrets.choice (seq)

Return a randomly chosen element from a non-empty sequence.
@end deffn

@geindex randbelow() (dans le module secrets)
@anchor{library/secrets secrets randbelow}@anchor{2a7a}
@deffn {Fonction} secrets.randbelow (exclusive_upper_bound)

Return a random int in the range [0, `exclusive_upper_bound').
@end deffn

@geindex randbits() (dans le module secrets)
@anchor{library/secrets secrets randbits}@anchor{2a7b}
@deffn {Fonction} secrets.randbits (k)

Return a non-negative int with `k' random bits.
@end deffn

@node Génération de jetons,Autres fonctions,Nombres aléatoires,secrets --- Generate secure random numbers for managing secrets
@anchor{library/secrets generating-tokens}@anchor{2a7c}
@subsubsection Génération de jetons


Le module @ref{bf,,secrets} fournit des fonctions pour la génération sécurisée de jetons adaptés à la réinitialisation de mots de passe, à la production d'URLs difficiles à deviner, etc.

@geindex token_bytes() (dans le module secrets)
@anchor{library/secrets secrets token_bytes}@anchor{2667}
@deffn {Fonction} secrets.token_bytes ([nbytes=None])

Renvoie une chaîne d'octets aléatoire contenant `nbytes' octets. Si `nbytes' est @code{None} ou omis, une valeur par défaut raisonnable est utilisée.

@example
>>> token_bytes(16)  
b'\xebr\x17D*t\xae\xd4\xe3S\xb6\xe2\xebP1\x8b'
@end example
@end deffn

@geindex token_hex() (dans le module secrets)
@anchor{library/secrets secrets token_hex}@anchor{1739}
@deffn {Fonction} secrets.token_hex ([nbytes=None])

Renvoie une chaîne de caractères aléatoire en hexadécimal. La chaîne comporte `nbytes' octets aléatoires, chaque octet étant écrit sous la forme de deux chiffres hexadécimaux. Si `nbytes' est @code{None} ou omis, une valeur par défaut raisonnable est utilisée.

@example
>>> token_hex(16)  
'f9bf78b9a18ce6d46a0cd2b0b86df9da'
@end example
@end deffn

@geindex token_urlsafe() (dans le module secrets)
@anchor{library/secrets secrets token_urlsafe}@anchor{2a7d}
@deffn {Fonction} secrets.token_urlsafe ([nbytes=None])

Renvoie une chaîne de caractères aléatoire adaptée au format URL, contenant `nbytes' octets aléatoires. Le texte est encodé en base64, chaque octet produisant en moyenne 1,3 caractères. Si `nbytes' est @code{None} ou omis, une valeur par défaut raisonnable est utilisée.

@example
>>> token_urlsafe(16)  
'Drmhze6EPcv0fN_81Bj-nA'
@end example
@end deffn

@menu
* Combien d'octets mon jeton doit-il comporter ?:: 

@end menu

@node Combien d'octets mon jeton doit-il comporter ?,,,Génération de jetons
@anchor{library/secrets how-many-bytes-should-tokens-use}@anchor{2a7e}
@subsubsection Combien d'octets mon jeton doit-il comporter ?


Afin de se prémunir des attaques par force brute@footnote{https://fr.wikipedia.org/wiki/Attaque_par_force_brute}, les jetons doivent être suffisamment aléatoires. Malheureusement, l'augmentation de la puissance de calcul des ordinateurs leur permet de réaliser plus de tentatives dans le même laps de temps. De ce fait, le nombre de bits recommandé pour l'aléa augmente aussi. En 2015, une longueur de 32 octets (256 bits) aléatoires est généralement considérée suffisante pour les usages typiques du module @ref{bf,,secrets}.

Si vous souhaitez gérer la longueur des jetons par vous-même, vous pouvez spécifier la quantité d'aléa à introduire dans les jetons en passant un argument @ref{254,,int} aux différentes fonctions @code{token_*}. Cet argument indique alors le nombre d'octets aléatoires utilisés pour la création du jeton.

Sinon, si aucun argument n'est passé ou si celui-ci est @code{None}, les fonctions @code{token_*} utilisent une valeur par défaut raisonnable à la place.

@cartouche
@quotation Note 
Cette valeur par défaut est susceptible de changer à n'importe quel moment, y compris lors des mises à jour de maintenance.
@end quotation
@end cartouche

@node Autres fonctions,Recettes et bonnes pratiques,Génération de jetons,secrets --- Generate secure random numbers for managing secrets
@anchor{library/secrets other-functions}@anchor{2a7f}
@subsubsection Autres fonctions


@geindex compare_digest() (dans le module secrets)
@anchor{library/secrets secrets compare_digest}@anchor{2a80}
@deffn {Fonction} secrets.compare_digest (a, b)

Return @code{True} if strings or
@ref{d1b,,bytes-like objects}
`a' and `b' are equal, otherwise @code{False},
using a "constant-time compare" to reduce the risk of
timing attacks@footnote{https://codahale.com/a-lesson-in-timing-attacks/}.
See @ref{10ab,,hmac.compare_digest()} for additional details.
@end deffn

@node Recettes et bonnes pratiques,,Autres fonctions,secrets --- Generate secure random numbers for managing secrets
@anchor{library/secrets recipes-and-best-practices}@anchor{2a81}
@subsubsection Recettes et bonnes pratiques


Cette section expose les recettes et les bonnes pratiques d'utilisation de @ref{bf,,secrets} pour gérer un niveau minimal de sécurité.

Générer un mot de passe à huit caractères alphanumériques :

@example
import string
import secrets
alphabet = string.ascii_letters + string.digits
password = '@w{'}.join(secrets.choice(alphabet) for i in range(8))
@end example

@cartouche
@quotation Note 
Applications should not
@geindex Common Weakness Enumeration; CWE 257
store passwords in a recoverable format@footnote{https://cwe.mitre.org/data/definitions/257.html},
whether plain text or encrypted.  They should be salted and hashed
using a cryptographically strong one-way (irreversible) hash function.
@end quotation
@end cartouche

Générer un mot de passe alphanumérique à dix caractères contenant au moins un caractère en minuscule, au moins un caractère en majuscule et au moins trois chiffres :

@example
import string
import secrets
alphabet = string.ascii_letters + string.digits
while True:
    password = '@w{'}.join(secrets.choice(alphabet) for i in range(10))
    if (any(c.islower() for c in password)
            and any(c.isupper() for c in password)
            and sum(c.isdigit() for c in password) >= 3):
        break
@end example

Générer une phrase de passe dans le style xkcd@footnote{https://xkcd.com/936/} :

@example
import secrets
# On standard Linux systems, use a convenient dictionary file.
# Other platforms may need to provide their own word-list.
with open('/usr/share/dict/words') as f:
    words = [word.strip() for word in f]
    password = ' '.join(secrets.choice(words) for i in range(4))
@end example

Générer une URL temporaire difficile à deviner contenant un jeton de sécurité adapté à réinitialisation d'un mot de passe :

@example
import secrets
url = 'https://example.com/reset=' + secrets.token_urlsafe()
@end example

@c # This modeline must appear within the last ten lines of the file.
@c kate: indent-width 3; remove-trailing-space on; replace-tabs on; encoding utf-8;

@node Services génériques du système d'exploitation,Command Line Interface Libraries,Service de cryptographie,La bibliothèque standard
@anchor{library/allos doc}@anchor{2a82}@anchor{library/allos allos}@anchor{2a83}@anchor{library/allos generic-operating-system-services}@anchor{2a84}
@section Services génériques du système d'exploitation


Les modules documentés dans ce chapitre fournissent des interfaces vers des fonctionnalités communes à la grande majorité des systèmes d'exploitation, telles que les fichiers et l'horloge.  Bien que ces interfaces soient classiquement calquées sur les interfaces Unix ou C, elles sont aussi disponibles sur la plupart des autres systèmes. En voici un aperçu :

@menu
* os: os --- Miscellaneous operating system interfaces. Miscellaneous operating system interfaces
* io: io --- Core tools for working with streams. Core tools for working with streams
* time: time --- Time access and conversions. Time access and conversions
* logging: logging --- Logging facility for Python. Logging facility for Python
* logging.config: logging config --- Logging configuration. Logging configuration
* logging.handlers: logging handlers --- Logging handlers. Logging handlers
* platform: platform --- Access to underlying platform's identifying data. Access to underlying platform's identifying data
* errno: errno --- Standard errno system symbols. Standard errno system symbols
* ctypes: ctypes --- A foreign function library for Python. A foreign function library for Python

@end menu

@node os --- Miscellaneous operating system interfaces,io --- Core tools for working with streams,,Services génériques du système d'exploitation
@anchor{library/os doc}@anchor{2a85}@anchor{library/os module-os}@anchor{a0}@anchor{library/os os-miscellaneous-operating-system-interfaces}@anchor{2a86}
@subsection @code{os} --- Miscellaneous operating system interfaces


@geindex module; os

`Code source:' Lib/os.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/os.py}


__________________________________________________________________


Ce module fournit une façon portable d'utiliser les fonctionnalités dépendantes du système d'exploitation.  Si vous voulez simplement lire ou écrire un fichier, voir @ref{505,,open()}, si vous voulez manipuler les chemins de fichiers, voir le module @ref{a1,,os.path}, et si vous voulez lire toutes les lignes de tous les fichiers de la ligne de commande, voir le module @ref{5a,,fileinput}. Pour la création de fichiers et de répertoires temporaires, voir le module @ref{df,,tempfile}, et pour la manipulation de fichiers et de répertoires de haut niveau, voir le module @ref{c4,,shutil}.

Notes sur la disponibilité de ces fonctions :


@itemize *

@item 
La conception des modules natifs Python dépendants du système d'exploitation est qu'une même fonctionnalité utilise une même interface. Par exemple, la fonction @code{os.stat(path)} renvoie des informations sur les statistiques de `path' dans le même format (qui est originaire de l'interface POSIX).

@item 
Les extensions propres à un certain système d'exploitation sont également disponible par le module @ref{a0,,os}, mais les utiliser est bien entendu une menace pour la portabilité.

@item 
Toutes les fonctions acceptant les chemins ou noms de fichiers acceptent aussi bien des `bytes' que des `string', et si un chemin ou un nom de fichier est renvoyé, il sera du même type.

@item 
On VxWorks, os.popen, os.fork, os.execv and os.spawn*p* are not supported.

@item 
On WebAssembly platforms, Android and iOS, large parts of the @ref{a0,,os} module are
not available or behave differently. APIs related to processes (e.g.
@ref{195,,fork()}, @ref{10d9,,execve()}) and resources (e.g. @ref{10e1,,nice()})
are not available. Others like @ref{2a87,,getuid()} and @ref{2a88,,getpid()} are
emulated or stubs. WebAssembly platforms also lack support for signals (e.g.
@ref{133e,,kill()}, @ref{d85,,wait()}).
@end itemize

@cartouche
@quotation Note 
Toutes les fonctions de ce module lèvent une @ref{40d,,OSError} (ou une de ses sous-classes) dans le cas d'un chemin ou nom de fichier invalide ou inaccessible, ou si d'autres arguments sont de type correct mais non géré par le système d'exploitation.
@end quotation
@end cartouche

@geindex error
@anchor{library/os os error}@anchor{2a89}
@deffn {Exception} os.error

Un alias pour les exceptions natives @ref{40d,,OSError}.
@end deffn

@geindex name (dans le module os)
@anchor{library/os os name}@anchor{2a8a}
@deffn {Données} os.name

Le nom du module importé dépendant du système d'exploitation.  Les noms suivants ont actuellement été enregistrés : @code{'posix'}, @code{'nt'}, @code{'java'}.


@subsubheading Voir aussi


@ref{a7b,,sys.platform} has a finer granularity.  @ref{10f6,,os.uname()} gives
system-dependent version information.

Le module @ref{a9,,platform} fournit des vérifications détaillées pour l'identité du système.

@end deffn
@anchor{library/os os-filenames}@anchor{29d4}
@menu
* Noms de fichiers@comma{} arguments en ligne de commande@comma{} et variables d'environnement: Noms de fichiers arguments en ligne de commande et variables d'environnement. 
* Le mode UTF-8 de Python:: 
* Paramètres de processus:: 
* Création de fichiers objets:: 
* Opérations sur les descripteurs de fichiers:: 
* Fichiers et répertoires:: 
* Gestion des processus:: 
* Interface pour l'ordonnanceur:: 
* Diverses informations sur le système:: 
* Nombres aléatoires: Nombres aléatoires<2>. 

@end menu

@node Noms de fichiers arguments en ligne de commande et variables d'environnement,Le mode UTF-8 de Python,,os --- Miscellaneous operating system interfaces
@anchor{library/os file-names-command-line-arguments-and-environment-variables}@anchor{2a8b}@anchor{library/os filesystem-encoding}@anchor{273e}
@subsubsection Noms de fichiers, arguments en ligne de commande, et variables d'environnement


In Python, file names, command line arguments, and environment variables are
represented using the string type. On some systems, decoding these strings to
and from bytes is necessary before passing them to the operating system. Python
uses the @ref{525,,filesystem encoding and error handler} to perform this
conversion (see @ref{c47,,sys.getfilesystemencoding()}).

L'@ref{525,,encodage du système de fichiers et gestionnaire d'erreurs associé} sont configurés au démarrage de Python par la fonction @ref{77a,,PyConfig_Read()} : regardez @ref{3df,,filesystem_encoding} et @ref{3e0,,filesystem_errors} dans les membres de @ref{39d,,PyConfig}.


Modifié dans la version 3.1: On some systems, conversion using the file system encoding may fail. In this
case, Python uses the @ref{236b,,surrogateescape encoding error handler}, which means that undecodable bytes are replaced by a
Unicode character U+DC`xx' on decoding, and these are again
translated to the original byte on encoding.


The @ref{525,,file system encoding} must
guarantee to successfully decode all bytes below 128. If the file system
encoding fails to provide this guarantee, API functions can raise
@ref{1281,,UnicodeError}.

Voir aussi @ref{23f,,encodage régional}.

@node Le mode UTF-8 de Python,Paramètres de processus,Noms de fichiers arguments en ligne de commande et variables d'environnement,os --- Miscellaneous operating system interfaces
@anchor{library/os python-utf-8-mode}@anchor{2a8c}@anchor{library/os utf8-mode}@anchor{641}
@subsubsection Le mode UTF-8 de Python



Ajouté dans la version 3.7: Voir la 
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/} pour plus d'informations.


Le mode UTF-8 de Python ignore @ref{23f,,l'encodage régional} et rend obligatoire l'utilisation de l'encodage UTF-8:


@itemize *

@item 
Utiliser UTF-8 pour @ref{525,,l'encodage du système de fichiers}.

@item 
@ref{c47,,sys.getfilesystemencoding()} returns @code{'utf-8'}.

@item 
@ref{524,,locale.getpreferredencoding()} returns @code{'utf-8'} (the `do_setlocale'
argument has no effect).

@item 
@ref{527,,sys.stdin}, @ref{ac4,,sys.stdout} et @ref{926,,sys.stderr} utilisent tous l'UTF-8 pour l'encodage du texte, avec le @ref{1774,,gestionnaire d'erreurs} @code{surrogateescape} activé pour @ref{527,,sys.stdin} et @ref{ac4,,sys.stdout} (@ref{926,,sys.stderr} continue d'utiliser @code{backslashreplace} comme pour le mode par défaut où il prend en compte la configuration régionale).

@item 
Sur Unix, @ref{181f,,os.device_encoding()} renvoie @code{'utf-8'} au lieu de l'encodage du périphérique.
@end itemize

Notez que la configuration des flux standards en mode UTF-8 peut être surchargée par 
@geindex PYTHONIOENCODING
@geindex variable d'environnement; PYTHONIOENCODING
@ref{ff3,,PYTHONIOENCODING} (de la même manière qu'elles peuvent l'être dans le mode par défaut qui est configuré pour la région locale).

En raison des changements apportés à ces API de bas-niveau, les API de haut-niveau ont un comportement par défaut différent :


@itemize *

@item 
Les arguments en ligne de commande, les variables d'environnement et les noms de fichiers sont décodés en texte en utilisant l'UTF-8.

@item 
@ref{c42,,os.fsdecode()} and @ref{c43,,os.fsencode()} use the UTF-8 encoding.

@item 
@ref{505,,open()}, @ref{506,,io.open()}, and @ref{72a,,codecs.open()} use the UTF-8
encoding by default. However, they still use the strict error handler by
default so that attempting to open a binary file in text mode is likely
to raise an exception rather than producing nonsense data.
@end itemize

The @ref{641,,Python UTF-8 Mode} is enabled if the LC_CTYPE locale is
@code{C} or @code{POSIX} at Python startup (see the @ref{77a,,PyConfig_Read()}
function).

It can be enabled or disabled using the @ref{175,,-X utf8} command line
option and the 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8} environment variable.

If the 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8} environment variable is not set at all, then the
interpreter defaults to using the current locale settings, `unless' the current
locale is identified as a legacy ASCII-based locale (as described for
@geindex PYTHONCOERCECLOCALE
@geindex variable d'environnement; PYTHONCOERCECLOCALE
@ref{ac3,,PYTHONCOERCECLOCALE}), and locale coercion is either disabled or
fails. In such legacy locales, the interpreter will default to enabling UTF-8
mode unless explicitly instructed not to do so.

The Python UTF-8 Mode can only be enabled at the Python startup. Its value
can be read from @ref{677,,sys.flags.utf8_mode}.

See also the @ref{1dab,,UTF-8 mode on Windows}
and the @ref{525,,filesystem encoding and error handler}.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 686

@item PEP 686@footnote{https://peps.python.org/pep-0686/}

@ref{641,,Le mode UTF-8 de Python} sera par mis par défaut sur Python 3.15.
@end table


@node Paramètres de processus,Création de fichiers objets,Le mode UTF-8 de Python,os --- Miscellaneous operating system interfaces
@anchor{library/os os-procinfo}@anchor{2a8d}@anchor{library/os process-parameters}@anchor{2a8e}
@subsubsection Paramètres de processus


Ces fonctions et valeurs fournissent des informations et agissent sur le processus actuel et sur l'utilisateur.

@geindex ctermid() (dans le module os)
@anchor{library/os os ctermid}@anchor{2a8f}
@deffn {Fonction} os.ctermid ()

Renvoie l'identifiant de fichier correspondant au terminal contrôlant le processus.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex environ (dans le module os)
@anchor{library/os os environ}@anchor{1197}
@deffn {Données} os.environ

A @ref{1199,,mapping} object where keys and values are strings that represent
the process environment.  For example, @code{environ['HOME']} is the pathname
of your home directory (on some platforms), and is equivalent to
@code{getenv("HOME")} in C.

This mapping is captured the first time the @ref{a0,,os} module is imported,
typically during Python startup as part of processing @code{site.py}.  Changes
to the environment made after this time are not reflected in @ref{1197,,os.environ},
except for changes made by modifying @ref{1197,,os.environ} directly.

This mapping may be used to modify the environment as well as query the
environment.  @ref{909,,putenv()} will be called automatically when the mapping
is modified.

Sur Unix, les clefs et les valeurs utilisent @ref{c47,,sys.getfilesystemencoding()} et le gestionnaire d'erreurs @code{surrogateescape}. Utilisez @ref{11f4,,environb} si vous désirez utiliser un encodage différent.

On Windows, the keys are converted to uppercase. This also applies when
getting, setting, or deleting an item. For example,
@code{environ['monty'] = 'python'} maps the key @code{'MONTY'} to the value
@code{'python'}.

@cartouche
@quotation Note 
Calling @ref{909,,putenv()} directly does not change @ref{1197,,os.environ}, so it's better
to modify @ref{1197,,os.environ}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
On some platforms, including FreeBSD and macOS, setting @code{environ} may
cause memory leaks.  Refer to the system documentation for
@code{putenv()}.
@end quotation
@end cartouche

You can delete items in this mapping to unset environment variables.
@ref{908,,unsetenv()} will be called automatically when an item is deleted from
@ref{1197,,os.environ}, and when one of the @code{pop()} or @code{clear()} methods is
called.


Modifié dans la version 3.9: Mis à jour pour gérer les opérateurs `merge' (@code{|}) et `update' (@code{|=}) de 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn

@geindex environb (dans le module os)
@anchor{library/os os environb}@anchor{11f4}
@deffn {Données} os.environb

Bytes version of @ref{1197,,environ}: a @ref{1199,,mapping} object where both keys
and values are @ref{1bd,,bytes} objects representing the process environment.
@ref{1197,,environ} and @ref{11f4,,environb} are synchronized (modifying
@ref{11f4,,environb} updates @ref{1197,,environ}, and vice versa).

@ref{11f4,,environb} is only available if @ref{11f2,,supports_bytes_environ} is
@code{True}.


Ajouté dans la version 3.2.



Modifié dans la version 3.9: Mis à jour pour gérer les opérateurs `merge' (@code{|}) et `update' (@code{|=}) de 
@geindex Python Enhancement Proposals; PEP 584
PEP 584@footnote{https://peps.python.org/pep-0584/}.

@end deffn


@deffn {Fonction} os.chdir (path)

@deffnx {Fonction} os.fchdir (fd)

@deffnx {Fonction} os.getcwd ()

Ces fonctions sont décrites dans le chapitre @ref{2a90,,Fichiers et répertoires}.
@end deffn

@geindex fsencode() (dans le module os)
@anchor{library/os os fsencode}@anchor{c43}
@deffn {Fonction} os.fsencode (filename)

Encode @ref{29d,,path-like} `filename' to the
@ref{525,,filesystem encoding and error handler}; return @ref{1bd,,bytes}
unchanged.

@ref{c42,,fsdecode()} est la fonction inverse.


Ajouté dans la version 3.2.



Modifié dans la version 3.6: Ajout de la prise en charge des objets implémentant l'interface @ref{c3f,,os.PathLike}.

@end deffn

@geindex fsdecode() (dans le module os)
@anchor{library/os os fsdecode}@anchor{c42}
@deffn {Fonction} os.fsdecode (filename)

Decode the @ref{29d,,path-like} `filename' from the
@ref{525,,filesystem encoding and error handler}; return @ref{435,,str}
unchanged.

@ref{c43,,fsencode()} est la fonction inverse.


Ajouté dans la version 3.2.



Modifié dans la version 3.6: Ajout de la prise en charge des objets implémentant l'interface @ref{c3f,,os.PathLike}.

@end deffn

@geindex fspath() (dans le module os)
@anchor{library/os os fspath}@anchor{c41}
@deffn {Fonction} os.fspath (path)

Renvoie une représentation du chemin utilisable par le système de fichiers.

Si un objet @ref{435,,str} ou @ref{1bd,,bytes} est passé, il est renvoyé inchangé. Autrement, @ref{c40,,__fspath__()} est appelée et sa valeur renvoyée tant qu'elle est un objet @ref{435,,str} ou @ref{1bd,,bytes}. Dans tous les autres cas, une @ref{522,,TypeError} est levée.


Ajouté dans la version 3.6.

@end deffn

@geindex PathLike (classe dans os)
@anchor{library/os os PathLike}@anchor{c3f}
@deffn {Classe} os.PathLike

@ref{1193,,Classe mère abstraite} pour les objets représentant un chemin du système de fichiers, comme @ref{490,,pathlib.PurePath}.


Ajouté dans la version 3.6.


@geindex __fspath__() (méthode os.PathLike)
@anchor{library/os os PathLike __fspath__}@anchor{c40}
@deffn {Méthode} abstractmethod __fspath__ ()

Renvoie une représentation de l'objet utilisable par le système de fichiers.

La méthode ne devrait renvoyer que des objets @ref{435,,str} ou @ref{1bd,,bytes}, avec une préférence pour les @ref{435,,str}.
@end deffn
@end deffn

@geindex getenv() (dans le module os)
@anchor{library/os os getenv}@anchor{2a91}
@deffn {Fonction} os.getenv (key, default=None)

Return the value of the environment variable `key' as a string if it exists, or
`default' if it doesn't. `key' is a string. Note that
since @ref{2a91,,getenv()} uses @ref{1197,,os.environ}, the mapping of @ref{2a91,,getenv()} is
similarly also captured on import, and the function may not reflect
future environment changes.

Sur Unix, les clefs et les valeurs sont décodées avec @ref{c47,,sys.getfilesystemencoding()} et le gestionnaire d'erreurs @code{surrogateescape}. Utilisez @ref{11f3,,os.getenvb()} si vous voulez utiliser un encodage différent.

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex getenvb() (dans le module os)
@anchor{library/os os getenvb}@anchor{11f3}
@deffn {Fonction} os.getenvb (key, default=None)

Return the value of the environment variable `key' as bytes if it exists, or
`default' if it doesn't. `key' must be bytes. Note that
since @ref{11f3,,getenvb()} uses @ref{11f4,,os.environb}, the mapping of @ref{11f3,,getenvb()} is
similarly also captured on import, and the function may not reflect
future environment changes.

@ref{11f3,,getenvb()} is only available if @ref{11f2,,supports_bytes_environ}
is @code{True}.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.2.

@end deffn

@geindex get_exec_path() (dans le module os)
@anchor{library/os os get_exec_path}@anchor{2a92}
@deffn {Fonction} os.get_exec_path (env=None)

Renvoie la liste des dossiers qui seront parcourus pour trouver un exécutable, similaire à un shell lorsque il lance un processus. `env', quand spécifié, doit être un dictionnaire de variable d'environnement  afin d'y rechercher le PATH. Par défaut quand `env' est @code{None}, @ref{1197,,environ} est utilisé.


Ajouté dans la version 3.2.

@end deffn

@geindex getegid() (dans le module os)
@anchor{library/os os getegid}@anchor{2a93}
@deffn {Fonction} os.getegid ()

Renvoie l'identifiant du groupe effectif du processus actuel. Ça correspond au bit "`set id'" du fichier qui s'exécute dans le processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex geteuid() (dans le module os)
@anchor{library/os os geteuid}@anchor{1777}
@deffn {Fonction} os.geteuid ()

@geindex user;effective id

Renvoie l'identifiant de l'utilisateur effectif du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex getgid() (dans le module os)
@anchor{library/os os getgid}@anchor{2a94}
@deffn {Fonction} os.getgid ()

@geindex process;group

Renvoie l'identifiant de groupe réel du processus actuel.

@ref{1ce0,,Availability}: Unix.

The function is a stub on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.
@end deffn

@geindex getgrouplist() (dans le module os)
@anchor{library/os os getgrouplist}@anchor{10f4}
@deffn {Fonction} os.getgrouplist (user, group, /)

Return list of group ids that `user' belongs to. If `group' is not in the
list, it is included; typically, `group' is specified as the group ID
field from the password record for `user', because that group ID will
otherwise be potentially omitted.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.3.

@end deffn

@geindex getgroups() (dans le module os)
@anchor{library/os os getgroups}@anchor{2a95}
@deffn {Fonction} os.getgroups ()

Renvoie une liste d'identifiants de groupes additionnels associés au processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI.

@cartouche
@quotation Note 
On macOS, @ref{2a95,,getgroups()} behavior differs somewhat from
other Unix platforms. If the Python interpreter was built with a
deployment target of @code{10.5} or earlier, @ref{2a95,,getgroups()} returns
the list of effective group ids associated with the current user process;
this list is limited to a system-defined number of entries, typically 16,
and may be modified by calls to @ref{2a96,,setgroups()} if suitably privileged.
If built with a deployment target greater than @code{10.5},
@ref{2a95,,getgroups()} returns the current group access list for the user
associated with the effective user id of the process; the group access
list may change over the lifetime of the process, it is not affected by
calls to @ref{2a96,,setgroups()}, and its length is not limited to 16.  The
deployment target value, @code{MACOSX_DEPLOYMENT_TARGET}, can be
obtained with @ref{1014,,sysconfig.get_config_var()}.
@end quotation
@end cartouche
@end deffn

@geindex getlogin() (dans le module os)
@anchor{library/os os getlogin}@anchor{2a97}
@deffn {Fonction} os.getlogin ()

Renvoie le nom de l'utilisateur connecté sur le terminal contrôlant le processus. Dans la plupart des cas, il est plus utile d'utiliser @ref{40e,,getpass.getuser()} puisque cette fonction consulte les variables d'environnement 
@geindex LOGNAME
@geindex variable d'environnement; LOGNAME
@code{LOGNAME} et 
@geindex USERNAME
@geindex variable d'environnement; USERNAME
@code{USERNAME} pour savoir qui est l'utilisateur, et se replie finalement sur @code{pwd.getpwduid(os.getuid())[0]} pour avoir le nom lié à l'identifiant de l'utilisateur courant.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.
@end deffn

@geindex getpgid() (dans le module os)
@anchor{library/os os getpgid}@anchor{2a98}
@deffn {Fonction} os.getpgid (pid)

Renvoie l'identifiant de groupe de processus du processus de PID `pid'. Si `pid' vaut 0, l'identifiant de groupe de processus du processus actuel est renvoyé.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex getpgrp() (dans le module os)
@anchor{library/os os getpgrp}@anchor{2a99}
@deffn {Fonction} os.getpgrp ()

@geindex process;group

Renvoie l'identifiant du groupe de processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex getpid() (dans le module os)
@anchor{library/os os getpid}@anchor{2a88}
@deffn {Fonction} os.getpid ()

@geindex process;id

Renvoie l'identifiant du processus actuel.

The function is a stub on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.
@end deffn

@geindex getppid() (dans le module os)
@anchor{library/os os getppid}@anchor{15db}
@deffn {Fonction} os.getppid ()

@geindex process;id of parent

Renvoie l'identifiant du processus parent. Quand le processus parent est terminé, sur Unix, l'identifiant renvoyé est 1 pour le processus `init', sur Windows, c'est toujours le même id, qui peut déjà avoir été réutilisé par un autre processus.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.


Modifié dans la version 3.2: Prise en charge sur Windows.

@end deffn

@geindex getpriority() (dans le module os)
@anchor{library/os os getpriority}@anchor{10df}
@deffn {Fonction} os.getpriority (which, who)

@geindex process;scheduling priority

Récupère la priorité d'ordonnancement des programmes. La valeur `which' est une des constantes suivantes : @ref{2a9a,,PRIO_PROCESS}, @ref{2a9b,,PRIO_PGRP}, ou @ref{2a9c,,PRIO_USER}, et la valeur `who' est interprétée par rapport à `which' (un id de processus pour @ref{2a9a,,PRIO_PROCESS}, un id de groupe de processus pour @ref{2a9b,,PRIO_PGRP}, et un id d'utilisateur pour @ref{2a9c,,PRIO_USER}). Une valeur nulle pour `who' dénote (respectivement) le processus appelant, le groupe de processus du processus appelant, ou l'identifiant d'utilisateur réel du processus appelant.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.3.

@end deffn

@geindex PRIO_PROCESS (dans le module os)
@geindex PRIO_PGRP (dans le module os)
@geindex PRIO_USER (dans le module os)
@anchor{library/os os PRIO_PROCESS}@anchor{2a9a}
@deffn {Données} os.PRIO_PROCESS
@anchor{library/os os PRIO_PGRP}@anchor{2a9b}
@deffnx {Données} os.PRIO_PGRP
@anchor{library/os os PRIO_USER}@anchor{2a9c}
@deffnx {Données} os.PRIO_USER

Paramètres pour les fonctions @ref{10df,,getpriority()} et @ref{10e0,,setpriority()}.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.3.

@end deffn

@geindex PRIO_DARWIN_THREAD (dans le module os)
@geindex PRIO_DARWIN_PROCESS (dans le module os)
@geindex PRIO_DARWIN_BG (dans le module os)
@geindex PRIO_DARWIN_NONUI (dans le module os)
@anchor{library/os os PRIO_DARWIN_THREAD}@anchor{2a9d}
@deffn {Données} os.PRIO_DARWIN_THREAD
@anchor{library/os os PRIO_DARWIN_PROCESS}@anchor{2a9e}
@deffnx {Données} os.PRIO_DARWIN_PROCESS
@anchor{library/os os PRIO_DARWIN_BG}@anchor{2a9f}
@deffnx {Données} os.PRIO_DARWIN_BG
@anchor{library/os os PRIO_DARWIN_NONUI}@anchor{2aa0}
@deffnx {Données} os.PRIO_DARWIN_NONUI

Paramètres pour les fonctions @ref{10df,,getpriority()} et @ref{10e0,,setpriority()}.

@ref{1ce0,,Availability}: macOS


Ajouté dans la version 3.12.

@end deffn

@geindex getresuid() (dans le module os)
@anchor{library/os os getresuid}@anchor{12f4}
@deffn {Fonction} os.getresuid ()

Renvoie un triplet (`ruid', `euid', `suid') dénotant les identifiants de l'utilisateur réel, effectif et sauvé du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.2.

@end deffn

@geindex getresgid() (dans le module os)
@anchor{library/os os getresgid}@anchor{12f3}
@deffn {Fonction} os.getresgid ()

Renvoie un triplet (`rgid', `egid', `sgid') dénotant les identifiants des groupes de processus réel effectif, et sauvé du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.2.

@end deffn

@geindex getuid() (dans le module os)
@anchor{library/os os getuid}@anchor{2a87}
@deffn {Fonction} os.getuid ()

@geindex user;id

Renvoie l'identifiant réel du processus actuel.

@ref{1ce0,,Availability}: Unix.

The function is a stub on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.
@end deffn

@geindex initgroups() (dans le module os)
@anchor{library/os os initgroups}@anchor{12f7}
@deffn {Fonction} os.initgroups (username, gid, /)

Appelle la fonction système `initgroups' pour initialiser la liste des groupes d'accès des groupes dont `username' est membre, plus le groupe spécifié par `gid'.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.


Ajouté dans la version 3.2.

@end deffn

@geindex putenv() (dans le module os)
@anchor{library/os os putenv}@anchor{909}
@deffn {Fonction} os.putenv (key, value, /)

@geindex environment variables;setting

Assigne la chaîne de caractères `value' à la variable d'environnement `key'. De tels changements à l'environnement affectent les sous-processus lancés par @ref{1411,,os.system()}, @ref{a75,,popen()} ou @ref{195,,fork()} et @ref{2aa1,,execv()}.

Assignments to items in @ref{1197,,os.environ} are automatically translated into
corresponding calls to @ref{909,,putenv()}; however, calls to @ref{909,,putenv()}
don't update @ref{1197,,os.environ}, so it is actually preferable to assign to items
of @ref{1197,,os.environ}. This also applies to @ref{2a91,,getenv()} and @ref{11f3,,getenvb()}, which
respectively use @ref{1197,,os.environ} and @ref{11f4,,os.environb} in their implementations.

@cartouche
@quotation Note 
On some platforms, including FreeBSD and macOS, setting @code{environ} may
cause memory leaks. Refer to the system documentation for @code{putenv()}.
@end quotation
@end cartouche

Lève un @ref{1848,,événement d'audit} @code{os.putenv} avec les arguments @code{key}, @code{value}.


Modifié dans la version 3.9: The function is now always available.

@end deffn

@geindex setegid() (dans le module os)
@anchor{library/os os setegid}@anchor{2aa2}
@deffn {Fonction} os.setegid (egid, /)

Définit l'identifiant du groupe de processus effectif du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.
@end deffn

@geindex seteuid() (dans le module os)
@anchor{library/os os seteuid}@anchor{2aa3}
@deffn {Fonction} os.seteuid (euid, /)

Définit l'identifiant de l'utilisateur effectif du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.
@end deffn

@geindex setgid() (dans le module os)
@anchor{library/os os setgid}@anchor{2aa4}
@deffn {Fonction} os.setgid (gid, /)

Définit l'identifiant du groupe de processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.
@end deffn

@geindex setgroups() (dans le module os)
@anchor{library/os os setgroups}@anchor{2a96}
@deffn {Fonction} os.setgroups (groups, /)

Place `groups' dans la liste d'identifiants de groupes additionnels associée. `groups' doit être une séquence, et chaque élément doit être un nombre entier identifiant un groupe. Cette opération est typiquement disponible uniquement pour le super utilisateur.

@ref{1ce0,,Availability}: Unix, not WASI.

@cartouche
@quotation Note 
On macOS, the length of `groups' may not exceed the
system-defined maximum number of effective group ids, typically 16.
See the documentation for @ref{2a95,,getgroups()} for cases where it may not
return the same group list set by calling setgroups().
@end quotation
@end cartouche
@end deffn

@geindex setns() (dans le module os)
@anchor{library/os os setns}@anchor{174e}
@deffn {Fonction} os.setns (fd, nstype=0)

Reassociate the current thread with a Linux namespace.
See the @code{setns(2)@footnote{https://manpages.debian.org/setns(2)}} and @code{namespaces(7)@footnote{https://manpages.debian.org/namespaces(7)}} man pages for more
details.

If `fd' refers to a @code{/proc/`pid'/ns/} link, @code{setns()} reassociates the
calling thread with the namespace associated with that link,
and `nstype' may be set to one of the
@ref{2aa5,,CLONE_NEW* constants}
to impose constraints on the operation
(@code{0} means no constraints).

Since Linux 5.8, `fd' may refer to a PID file descriptor obtained from
@ref{464,,pidfd_open()}. In this case, @code{setns()} reassociates the calling thread
into one or more of the same namespaces as the thread referred to by `fd'.
This is subject to any constraints imposed by `nstype',
which is a bit mask combining one or more of the
@ref{2aa5,,CLONE_NEW* constants},
e.g. @code{setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID)}.
The caller's memberships in unspecified namespaces are left unchanged.

`fd' can be any object with a @ref{27cf,,fileno()} method, or a raw file descriptor.

This example reassociates the thread with the @code{init} process's network namespace:

@example
fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)
@end example

@ref{1ce0,,Availability}: Linux >= 3.0 with glibc >= 2.14.


Ajouté dans la version 3.12.



@subsubheading Voir aussi


The @ref{174f,,unshare()} function.

@end deffn

@geindex setpgrp() (dans le module os)
@anchor{library/os os setpgrp}@anchor{2aa6}
@deffn {Fonction} os.setpgrp ()

Call the system call @code{setpgrp()} or @code{setpgrp(0, 0)} depending on
which version is implemented (if any).  See the Unix manual for the semantics.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex setpgid() (dans le module os)
@anchor{library/os os setpgid}@anchor{2aa7}
@deffn {Fonction} os.setpgid (pid, pgrp, /)

Call the system call @code{setpgid()} to set the process group id of the
process with id `pid' to the process group with id `pgrp'.  See the Unix manual
for the semantics.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex setpriority() (dans le module os)
@anchor{library/os os setpriority}@anchor{10e0}
@deffn {Fonction} os.setpriority (which, who, priority)

@geindex process;scheduling priority

Définit la priorité d'ordonnancement des programmes. La valeur `which' est une des constantes suivantes : @ref{2a9a,,PRIO_PROCESS}, @ref{2a9b,,PRIO_PGRP}, ou @ref{2a9c,,PRIO_USER}, et `who' est interprété en fonction de `which' (un PID pour @ref{2a9a,,PRIO_PROCESS}, un identifiant de groupe de processus pour @ref{2a9b,,PRIO_PGRP}, et un identifiant d'utilisateur pour @ref{2a9c,,PRIO_USER}). Une valeur nulle pour `who' dénote (respectivement) le processus appelant, le groupe de processus du processus appelant, ou l'identifiant de l'utilisateur réel du processus appelant. `priority' est une valeur comprise entre @code{-20} et @code{19}. La priorité par défaut est 0 ; les priorités plus faibles amènent à un ordonnancement plus favorable.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.3.

@end deffn

@geindex setregid() (dans le module os)
@anchor{library/os os setregid}@anchor{2aa8}
@deffn {Fonction} os.setregid (rgid, egid, /)

Définit l'identifiant des groupes réel et effectif du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.
@end deffn

@geindex setresgid() (dans le module os)
@anchor{library/os os setresgid}@anchor{12f5}
@deffn {Fonction} os.setresgid (rgid, egid, sgid, /)

Définit l'identifiant des groupes réel, effectif et sauvé du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.


Ajouté dans la version 3.2.

@end deffn

@geindex setresuid() (dans le module os)
@anchor{library/os os setresuid}@anchor{12f6}
@deffn {Fonction} os.setresuid (ruid, euid, suid, /)

Définit l'identifiant des utilisateurs réel, effectif et sauvé du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.


Ajouté dans la version 3.2.

@end deffn

@geindex setreuid() (dans le module os)
@anchor{library/os os setreuid}@anchor{2aa9}
@deffn {Fonction} os.setreuid (ruid, euid, /)

Définit l'identifiant des utilisateurs réel et effectif du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.
@end deffn

@geindex getsid() (dans le module os)
@anchor{library/os os getsid}@anchor{2aaa}
@deffn {Fonction} os.getsid (pid, /)

Call the system call @code{getsid()}.  See the Unix manual for the semantics.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex setsid() (dans le module os)
@anchor{library/os os setsid}@anchor{1963}
@deffn {Fonction} os.setsid ()

Call the system call @code{setsid()}.  See the Unix manual for the semantics.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex setuid() (dans le module os)
@anchor{library/os os setuid}@anchor{2aab}
@deffn {Fonction} os.setuid (uid, /)

@geindex user;id@comma{} setting

Définit l'identifiant de l'utilisateur du processus actuel.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.
@end deffn

@c placed in this section since it relates to errno.... a little weak

@geindex strerror() (dans le module os)
@anchor{library/os os strerror}@anchor{2aac}
@deffn {Fonction} os.strerror (code, /)

Return the error message corresponding to the error code in `code'.
On platforms where @code{strerror()} returns @code{NULL} when given an unknown
error number, @ref{1ff,,ValueError} is raised.
@end deffn

@geindex supports_bytes_environ (dans le module os)
@anchor{library/os os supports_bytes_environ}@anchor{11f2}
@deffn {Données} os.supports_bytes_environ

@code{True} si le type natif de l'environnement du système d'exploitation est `bytes' (par exemple : @code{False} sur Windows).


Ajouté dans la version 3.2.

@end deffn

@geindex umask() (dans le module os)
@anchor{library/os os umask}@anchor{2aad}
@deffn {Fonction} os.umask (mask, /)

Définit le `umask' actuel et renvoie la valeur précédente.

The function is a stub on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.
@end deffn

@geindex uname() (dans le module os)
@anchor{library/os os uname}@anchor{10f6}
@deffn {Fonction} os.uname ()

@geindex gethostname() (in module socket)
@geindex gethostbyaddr() (in module socket)

Renvoie des informations identifiant le système d'exploitation actuel. La valeur de retour est un objet à cinq attributs :


@itemize *

@item 
@code{sysname} — nom du système d'exploitation

@item 
@code{nodename} — nom de la machine sur le réseau (dépendant de l'implémentation)

@item 
@code{release} — `release' du système d'exploitation

@item 
@code{version} — version du système d'exploitation

@item 
@code{machine} — identifiant du matériel
@end itemize

Pour la rétrocompatibilité, cet objet est également itérable, se comportant comme un quintuplet contenant @code{sysname}, @code{nodename}, @code{release}, @code{version}, et @code{machine} dans cet ordre.

Certains systèmes tronquent @code{nodename} à 8 caractères ou à la composante dominante. Un meilleur moyen de récupérer le nom de l'hôte est @ref{2aae,,socket.gethostname()} ou encore @code{socket.gethostbyaddr(socket.gethostname())}.

On macOS, iOS and Android, this returns the `kernel' name and version (i.e.,
@code{'Darwin'} on macOS and iOS; @code{'Linux'} on Android). @ref{19c0,,platform.uname()}
can be used to get the user-facing operating system name and version on iOS and
Android.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.3: Type de retour changé d'un quintuplet en un objet compatible avec le type `n'-uplet, avec des attributs nommés.

@end deffn

@geindex unsetenv() (dans le module os)
@anchor{library/os os unsetenv}@anchor{908}
@deffn {Fonction} os.unsetenv (key, /)

@geindex environment variables;deleting

Supprime la variable d'environnement appelée `key'. De tels changements à l'environnement affectent les sous-processus lancés avec @ref{1411,,os.system()}, @ref{a75,,popen()} ou @ref{195,,fork()} et @ref{2aa1,,execv()}.

Deletion of items in @ref{1197,,os.environ} is automatically translated into a
corresponding call to @ref{908,,unsetenv()}; however, calls to @ref{908,,unsetenv()}
don't update @ref{1197,,os.environ}, so it is actually preferable to delete items of
@ref{1197,,os.environ}.

Lève un @ref{1848,,événement d'audit} @code{os.unsetenv} avec l’argument @code{key}.


Modifié dans la version 3.9: The function is now always available and is also available on Windows.

@end deffn

@geindex unshare() (dans le module os)
@anchor{library/os os unshare}@anchor{174f}
@deffn {Fonction} os.unshare (flags)

Disassociate parts of the process execution context, and move them into a
newly created namespace.
See the @code{unshare(2)@footnote{https://manpages.debian.org/unshare(2)}}
man page for more details.
The `flags' argument is a bit mask, combining zero or more of the
@ref{2aa5,,CLONE_* constants},
that specifies which parts of the execution context should be
unshared from their existing associations and moved to a new namespace.
If the `flags' argument is @code{0}, no changes are made to the calling process's
execution context.

@ref{1ce0,,Availability}: Linux >= 2.6.16.


Ajouté dans la version 3.12.



@subsubheading Voir aussi


The @ref{174e,,setns()} function.

@end deffn
@anchor{library/os os-unshare-clone-flags}@anchor{2aa5}
Flags to the @ref{174f,,unshare()} function, if the implementation supports them.
See @code{unshare(2)@footnote{https://manpages.debian.org/unshare(2)}} in the Linux manual
for their exact effect and availability.

@geindex CLONE_FILES (dans le module os)
@geindex CLONE_FS (dans le module os)
@geindex CLONE_NEWCGROUP (dans le module os)
@geindex CLONE_NEWIPC (dans le module os)
@geindex CLONE_NEWNET (dans le module os)
@geindex CLONE_NEWNS (dans le module os)
@geindex CLONE_NEWPID (dans le module os)
@geindex CLONE_NEWTIME (dans le module os)
@geindex CLONE_NEWUSER (dans le module os)
@geindex CLONE_NEWUTS (dans le module os)
@geindex CLONE_SIGHAND (dans le module os)
@geindex CLONE_SYSVSEM (dans le module os)
@geindex CLONE_THREAD (dans le module os)
@geindex CLONE_VM (dans le module os)
@anchor{library/os os CLONE_FILES}@anchor{2aaf}
@deffn {Données} os.CLONE_FILES
@anchor{library/os os CLONE_FS}@anchor{2ab0}
@deffnx {Données} os.CLONE_FS
@anchor{library/os os CLONE_NEWCGROUP}@anchor{2ab1}
@deffnx {Données} os.CLONE_NEWCGROUP
@anchor{library/os os CLONE_NEWIPC}@anchor{2ab2}
@deffnx {Données} os.CLONE_NEWIPC
@anchor{library/os os CLONE_NEWNET}@anchor{2ab3}
@deffnx {Données} os.CLONE_NEWNET
@anchor{library/os os CLONE_NEWNS}@anchor{2ab4}
@deffnx {Données} os.CLONE_NEWNS
@anchor{library/os os CLONE_NEWPID}@anchor{2ab5}
@deffnx {Données} os.CLONE_NEWPID
@anchor{library/os os CLONE_NEWTIME}@anchor{2ab6}
@deffnx {Données} os.CLONE_NEWTIME
@anchor{library/os os CLONE_NEWUSER}@anchor{2ab7}
@deffnx {Données} os.CLONE_NEWUSER
@anchor{library/os os CLONE_NEWUTS}@anchor{2ab8}
@deffnx {Données} os.CLONE_NEWUTS
@anchor{library/os os CLONE_SIGHAND}@anchor{2ab9}
@deffnx {Données} os.CLONE_SIGHAND
@anchor{library/os os CLONE_SYSVSEM}@anchor{2aba}
@deffnx {Données} os.CLONE_SYSVSEM
@anchor{library/os os CLONE_THREAD}@anchor{2abb}
@deffnx {Données} os.CLONE_THREAD
@anchor{library/os os CLONE_VM}@anchor{2abc}
@deffnx {Données} os.CLONE_VM
@end deffn

@node Création de fichiers objets,Opérations sur les descripteurs de fichiers,Paramètres de processus,os --- Miscellaneous operating system interfaces
@anchor{library/os file-object-creation}@anchor{2abd}@anchor{library/os os-newstreams}@anchor{2abe}
@subsubsection Création de fichiers objets


These functions create new @ref{11a0,,file objects}.  (See also
@ref{d7f,,open()} for opening file descriptors.)

@geindex fdopen() (dans le module os)
@anchor{library/os os fdopen}@anchor{1eb7}
@deffn {Fonction} os.fdopen (fd, *args, **kwargs)

Renvoie un fichier objet ouvert connecté au descripteur de fichier `fd'. C'est un alias de la primitive @ref{505,,open()} et accepte les mêmes arguments. La seule différence est que le premier argument de @ref{1eb7,,fdopen()} doit toujours être un entier.
@end deffn

@node Opérations sur les descripteurs de fichiers,Fichiers et répertoires,Création de fichiers objets,os --- Miscellaneous operating system interfaces
@anchor{library/os file-descriptor-operations}@anchor{2abf}@anchor{library/os os-fd-ops}@anchor{2ac0}
@subsubsection Opérations sur les descripteurs de fichiers


Ces fonctions opèrent sur des flux d'entrées/sorties référencés par des descripteurs de fichiers.

Les descripteurs de fichiers sont de petits entiers correspondant à un fichier qui a été ouvert par le processus courant. Par exemple, l'entrée standard est habituellement le descripteur de fichier 0, la sortie standard est 1, et le flux standard d'erreur est 2. Les autres fichiers ouverts par un processus vont se voir assigner 3, 4, 5, etc. Le nom « descripteur de fichier » est légèrement trompeur : sur les plate-formes Unix, les connecteurs (`socket' en anglais) et les tubes (`pipe' en anglais) sont également référencés par des descripteurs.

La méthode @ref{27cf,,fileno()} peut être utilisée pour obtenir le descripteur de fichier associé à un @ref{11a0,,file object} quand nécessaire. Notez qu'utiliser le descripteur directement outrepasse les méthodes du fichier objet, ignorant donc des aspects tels que la mise en tampon interne des données.

@geindex close() (dans le module os)
@anchor{library/os os close}@anchor{b62}
@deffn {Fonction} os.close (fd)

Ferme le descripteur de fichier `fd'.

@cartouche
@quotation Note 
Cette fonction est destinée aux opérations d'entrées/sorties de bas niveau et doit être appliquée à un descripteur de fichier comme ceux donnés par @ref{d7f,,os.open()} ou @ref{1768,,pipe()}. Pour fermer un « fichier objet » renvoyé par la primitive @ref{505,,open()}, @ref{a75,,popen()} ou @ref{1eb7,,fdopen()}, il faut utiliser sa méthode @ref{1f3,,close()}.
@end quotation
@end cartouche
@end deffn

@geindex closerange() (dans le module os)
@anchor{library/os os closerange}@anchor{2ac1}
@deffn {Fonction} os.closerange (fd_low, fd_high, /)

Ferme tous les descripteurs de fichiers entre `fd_low' (inclus) jusque `fd_high' (exclus), en ignorant les erreurs. Équivalent (mais beaucoup plus rapide) à :

@example
for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass
@end example
@end deffn

@geindex copy_file_range() (dans le module os)
@anchor{library/os os copy_file_range}@anchor{2ac2}
@deffn {Fonction} os.copy_file_range (src, dst, count, offset_src=None, offset_dst=None)

Copy `count' bytes from file descriptor `src', starting from offset
`offset_src', to file descriptor `dst', starting from offset `offset_dst'.
If `offset_src' is @code{None}, then `src' is read from the current position;
respectively for `offset_dst'.

In Linux kernel older than 5.3, the files pointed to by `src' and `dst'
must reside in the same filesystem, otherwise an @ref{40d,,OSError} is
raised with @ref{2214,,errno} set to @ref{2ac3,,errno.EXDEV}.

This copy is done without the additional cost of transferring data
from the kernel to user space and then back into the kernel. Additionally,
some filesystems could implement extra optimizations, such as the use of
reflinks (i.e., two or more inodes that share pointers to the same
copy-on-write disk blocks; supported file systems include btrfs and XFS)
and server-side copy (in the case of NFS).

The function copies bytes between two file descriptors. Text options, like
the encoding and the line ending, are ignored.

La valeur de retour est le nombre d'octets copiés. Cela peut être moins que le nombre demandé.

@cartouche
@quotation Note 
On Linux, @ref{2ac2,,os.copy_file_range()} should not be used for copying a
range of a pseudo file from a special filesystem like procfs and sysfs.
It will always copy no bytes and return 0 as if the file was empty
because of a known Linux kernel issue.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Linux >= 4.5 with glibc >= 2.27.


Ajouté dans la version 3.8.

@end deffn

@geindex device_encoding() (dans le module os)
@anchor{library/os os device_encoding}@anchor{181f}
@deffn {Fonction} os.device_encoding (fd)

Renvoie une chaîne de caractères décrivant l'encodage du périphérique associé à `fd' s'il est connecté à un terminal, sinon renvoie @ref{660,,None}.

On Unix, if the @ref{641,,Python UTF-8 Mode} is enabled, return
@code{'UTF-8'} rather than the device encoding.


Modifié dans la version 3.10: On Unix, the function now implements the Python UTF-8 Mode.

@end deffn

@geindex dup() (dans le module os)
@anchor{library/os os dup}@anchor{196b}
@deffn {Fonction} os.dup (fd, /)

Renvoie une copie du descripteur de fichier `fd'. Le nouveau descripteur de fichier est @ref{ee4,,non-héritable}.

Sur Windows, quand un flux standard est dupliqué (0 : `stdin', 1 : `stdout', 2 : `stderr'), le nouveau descripteur de fichier est @ref{ee4,,héritable}.

@ref{1ce0,,Availability}: not WASI.


Modifié dans la version 3.4: Le nouveau descripteur de fichier est maintenant non-héritable.

@end deffn

@geindex dup2() (dans le module os)
@anchor{library/os os dup2}@anchor{b51}
@deffn {Fonction} os.dup2 (fd, fd2, inheritable=True)

Copie le descripteur de fichier `fd' dans `fd2', en fermant le second d'abord si nécessaire. Renvoie `fd2'. Le nouveau descripteur de fichier est @ref{ee4,,héritable} par défaut, ou non-héritable si `inheritable' vaut @code{False}.

@ref{1ce0,,Availability}: not WASI.


Modifié dans la version 3.4: Ajout du paramètre optionnel `inheritable'.



Modifié dans la version 3.7: Renvoie `fd2' en cas de succès. Auparavant, @code{None} était toujours renvoyé.

@end deffn

@geindex fchmod() (dans le module os)
@anchor{library/os os fchmod}@anchor{219}
@deffn {Fonction} os.fchmod (fd, mode)

Change le mode du fichier donné par `fd' en la valeur numérique `mode'. Voir la documentation de @ref{218,,chmod()} pour les valeurs possibles de `mode'. Depuis Python 3.3, c'est équivalent à @code{os.chmod(fd, mode)}.

Lève un @ref{1848,,événement d'audit} @code{os.chmod} avec les arguments @code{path}, @code{mode}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix, Windows.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.


Modifié dans la version 3.13: Added support on Windows.

@end deffn

@geindex fchown() (dans le module os)
@anchor{library/os os fchown}@anchor{d77}
@deffn {Fonction} os.fchown (fd, uid, gid)

Change le propriétaire et l'identifiant de groupe du fichier donné par `fd' en les valeurs numériques `uid' et `gid'. Pour laisser l'un des identifiants inchangés, mettez-le à @code{-1}. Voir @ref{10cf,,chown()}. Depuis Python 3.3, c'est équivalent à @code{os.chown(fd, uid, gid)}.

Lève un @ref{1848,,événement d'audit} @code{os.chown} avec les arguments @code{path}, @code{uid}, @code{gid}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.
@end deffn

@geindex fdatasync() (dans le module os)
@anchor{library/os os fdatasync}@anchor{d78}
@deffn {Fonction} os.fdatasync (fd)

Force l'écriture du fichier ayant le descripteur `fd' sur le disque. Ne force pas la mise à jour des méta-données.

@ref{1ce0,,Availability}: Unix.

@cartouche
@quotation Note 
Cette fonction n'est pas disponible sur MacOS.
@end quotation
@end cartouche
@end deffn

@geindex fpathconf() (dans le module os)
@anchor{library/os os fpathconf}@anchor{2ac4}
@deffn {Fonction} os.fpathconf (fd, name, /)

Renvoie les informations de la configuration du système pour un fichier ouvert. `name' spécifie la valeur de la configuration à récupérer, ça peut être une chaîne de caractères avec le nom d'une valeur système définie ; ces valeurs sont spécifiées dans certains standards (POSIX.1, Unix 95, Unix 98, et d'autres). Certaines plate-formes définissent des noms additionnels également. Les noms connus par le système d'exploitation sont donnés dans le dictionnaire @code{pathconf_names}. Pour les variables de configuration qui ne sont pas inclues dans ce `mapping', passer un entier pour `name' est également accepté.

Si `name' est une chaîne de caractères et n'est pas connu, une @ref{1ff,,ValueError} est levée. Si une valeur spécifique de `name' n'est pas gérée par le système hôte, même si elle est incluse dans @code{pathconf_names}, une @ref{40d,,OSError} est levée avec @ref{197d,,errno.EINVAL} pour code d'erreur.

Depuis Python 3.3, c'est équivalent à @code{os.pathconf(fd, name)}.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex fstat() (dans le module os)
@anchor{library/os os fstat}@anchor{d79}
@deffn {Fonction} os.fstat (fd)

Récupère le statut du descripteur de fichier `fd'. Renvoie un objet @ref{1475,,stat_result}.

Depuis Python 3.3, c'est équivalent à @code{os.stat(fd)}.


@subsubheading Voir aussi


La fonction @ref{48a,,stat()}.

@end deffn

@geindex fstatvfs() (dans le module os)
@anchor{library/os os fstatvfs}@anchor{d7a}
@deffn {Fonction} os.fstatvfs (fd, /)

Renvoie des informations sur le système de fichier contenant le fichier associé au descripteur `fd', comme @ref{10dc,,statvfs()}. Depuis Python 3.3, c'est équivalent à @code{os.statvfs(fd)}.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex fsync() (dans le module os)
@anchor{library/os os fsync}@anchor{d7b}
@deffn {Fonction} os.fsync (fd)

Force write of file with filedescriptor `fd' to disk.  On Unix, this calls the
native @code{fsync()} function; on Windows, the MS @code{_commit()} function.

Si vous débutez avec un @ref{11a0,,file object} Python mis en tampon `f', commencez par faire @code{f.flush()} et seulement ensuite @code{os.fsync(f.fileno())} pour être sûr que tous les tampons internes associés à `f' soient écrits sur le disque.

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex ftruncate() (dans le module os)
@anchor{library/os os ftruncate}@anchor{d7c}
@deffn {Fonction} os.ftruncate (fd, length, /)

Tronque le fichier correspondant au descripteur `fd' pour qu'il soit maximum long de `length' `bytes'. Depuis Python 3.3, c'est équivalent à @code{os.truncate(fd, length)}.

Lève un @ref{1848,,événement d'audit} @code{os.truncate} avec les arguments @code{fd}, @code{length}.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.5: Prise en charge de Windows

@end deffn

@geindex get_blocking() (dans le module os)
@anchor{library/os os get_blocking}@anchor{e26}
@deffn {Fonction} os.get_blocking (fd, /)

Récupère le mode bloquant du descripteur de fichier : @code{False} si l'indicateur @ref{e28,,O_NONBLOCK} est mis, et @code{True} si l'indicateur est effacé.

Voir également @ref{e27,,set_blocking()} et @ref{2ac5,,socket.socket.setblocking()}.

@ref{1ce0,,Availability}: Unix, Windows.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.

On Windows, this function is limited to pipes.


Ajouté dans la version 3.5.



Modifié dans la version 3.12: Added support for pipes on Windows.

@end deffn

@geindex grantpt() (dans le module os)
@anchor{library/os os grantpt}@anchor{160c}
@deffn {Fonction} os.grantpt (fd, /)

Grant access to the slave pseudo-terminal device associated with the
master pseudo-terminal device to which the file descriptor `fd' refers.
The file descriptor `fd' is not closed upon failure.

Calls the C standard library function @code{grantpt()}.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.13.

@end deffn

@geindex isatty() (dans le module os)
@anchor{library/os os isatty}@anchor{181e}
@deffn {Fonction} os.isatty (fd, /)

Renvoie @code{True} si le descripteur de fichier `fd' est ouvert et connecté à un périphérique TTY (ou compatible), sinon @code{False}.
@end deffn

@geindex lockf() (dans le module os)
@anchor{library/os os lockf}@anchor{10f3}
@deffn {Fonction} os.lockf (fd, cmd, len, /)

Applique, teste, ou retire un verrou POSIX sur un descripteur de fichier ouvert. `fd' est un descripteur de fichier ouvert. `cmd' spécifie la commande à utiliser (une des valeurs suivantes : @ref{2ac6,,F_LOCK}, @ref{2ac7,,F_TLOCK}, @ref{2ac8,,F_ULOCK}, ou @ref{2ac9,,F_TEST}). `len' spécifie la section du fichier à verrouiller.

Lève un @ref{1848,,événement d'audit} @code{os.lockf} avec les arguments @code{fd}, @code{cmd}, @code{len}.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex F_LOCK (dans le module os)
@geindex F_TLOCK (dans le module os)
@geindex F_ULOCK (dans le module os)
@geindex F_TEST (dans le module os)
@anchor{library/os os F_LOCK}@anchor{2ac6}
@deffn {Données} os.F_LOCK
@anchor{library/os os F_TLOCK}@anchor{2ac7}
@deffnx {Données} os.F_TLOCK
@anchor{library/os os F_ULOCK}@anchor{2ac8}
@deffnx {Données} os.F_ULOCK
@anchor{library/os os F_TEST}@anchor{2ac9}
@deffnx {Données} os.F_TEST

Indicateurs spécifiant quelle action @ref{10f3,,lockf()} va prendre.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex login_tty() (dans le module os)
@anchor{library/os os login_tty}@anchor{16e7}
@deffn {Fonction} os.login_tty (fd, /)

Prepare the tty of which fd is a file descriptor for a new login session.
Make the calling process a session leader; make the tty the controlling tty,
the stdin, the stdout, and the stderr of the calling process; close fd.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.11.

@end deffn

@geindex lseek() (dans le module os)
@anchor{library/os os lseek}@anchor{10f7}
@deffn {Fonction} os.lseek (fd, pos, whence, /)

Set the current position of file descriptor `fd' to position `pos', modified
by `whence', and return the new position in bytes relative to
the start of the file.
Valid values for `whence' are:


@itemize *

@item 
@ref{126b,,SEEK_SET} or @code{0} -- set `pos' relative to the beginning of the file

@item 
@ref{126c,,SEEK_CUR} or @code{1} -- set `pos' relative to the current file position

@item 
@ref{126d,,SEEK_END} or @code{2} -- set `pos' relative to the end of the file

@item 
@ref{2aca,,SEEK_HOLE} -- set `pos' to the next data location, relative to `pos'

@item 
@ref{2acb,,SEEK_DATA} -- set `pos' to the next data hole, relative to `pos'
@end itemize


Modifié dans la version 3.3: Add support for @code{SEEK_HOLE} and @code{SEEK_DATA}.

@end deffn

@geindex SEEK_SET (dans le module os)
@geindex SEEK_CUR (dans le module os)
@geindex SEEK_END (dans le module os)
@anchor{library/os os SEEK_SET}@anchor{126b}
@deffn {Données} os.SEEK_SET
@anchor{library/os os SEEK_CUR}@anchor{126c}
@deffnx {Données} os.SEEK_CUR
@anchor{library/os os SEEK_END}@anchor{126d}
@deffnx {Données} os.SEEK_END

Parameters to the @ref{10f7,,lseek()} function and the @ref{126a,,seek()}
method on @ref{11a0,,file-like objects},
for whence to adjust the file position indicator.


@table @asis

@item @ref{126b,,SEEK_SET}

Adjust the file position relative to the beginning of the file.

@item @ref{126c,,SEEK_CUR}

Adjust the file position relative to the current file position.

@item @ref{126d,,SEEK_END}

Adjust the file position relative to the end of the file.
@end table

Their values are 0, 1, and 2, respectively.
@end deffn

@geindex SEEK_HOLE (dans le module os)
@geindex SEEK_DATA (dans le module os)
@anchor{library/os os SEEK_HOLE}@anchor{2aca}
@deffn {Données} os.SEEK_HOLE
@anchor{library/os os SEEK_DATA}@anchor{2acb}
@deffnx {Données} os.SEEK_DATA

Parameters to the @ref{10f7,,lseek()} function and the @ref{126a,,seek()}
method on @ref{11a0,,file-like objects},
for seeking file data and holes on sparsely allocated files.


@table @asis

@item @code{SEEK_DATA}

Adjust the file offset to the next location containing data,
relative to the seek position.

@item @code{SEEK_HOLE}

Adjust the file offset to the next location containing a hole,
relative to the seek position.
A hole is defined as a sequence of zeros.
@end table

@cartouche
@quotation Note 
These operations only make sense for filesystems that support them.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Linux >= 3.1, macOS, Unix


Ajouté dans la version 3.3.

@end deffn

@geindex open() (dans le module os)
@anchor{library/os os open}@anchor{d7f}
@deffn {Fonction} os.open (path, flags, mode=0o777, *, dir_fd=None)

Ouvre le fichier `path' et met certains indicateurs selon `flags' et éventuellement son mode selon `mode'. Lors de l'évaluation de `code', ce `umask' actuel est d'abord masquée. Renvoie le descripteur de fichier du fichier nouvellement ouvert. Le nouveau descripteur de fichier est @ref{ee4,,non-héritable}.

Pour une description des indicateurs et des valeurs des modes, voir la documentation de la bibliothèque standard du C. Les constantes d'indicateurs (telles que @ref{2acc,,O_RDONLY} et @ref{2acd,,O_WRONLY}) sont définies dans le module @ref{a0,,os}. En particulier, sur Windows, ajouter @ref{2ace,,O_BINARY} est nécessaire pour ouvrir des fichiers en binaire.

Cette fonction prend en charge des @ref{10cb,,chemins relatifs à des descripteurs de répertoires} avec le paramètre `dir_fd'.

Lève un @ref{1848,,événement d'audit} @code{open} avec les arguments @code{path}, @code{mode}, @code{flags}.


Modifié dans la version 3.4: Le nouveau descripteur de fichier est maintenant non-héritable.


@cartouche
@quotation Note 
Cette fonction est destinée aux E/S de bas-niveau. Pour un usage normal, utilisez la primitive @ref{505,,open()} qui renvoie un @ref{11a0,,file object} avec les méthodes @code{read()} et @code{write()} (et plein d'autres). Pour envelopper un descripteur de fichier dans un fichier objet, utilisez @ref{1eb7,,fdopen()}.
@end quotation
@end cartouche


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

Les constantes suivantes sont optionnelles pour le paramètre `flag' à la fonction @ref{d7f,,open()}. Elles peuvent être combinées en utilisant l'opérateur bit-à-bit OR @code{|}. certains ne sont pas disponibles sur toutes les plate-formes. Pour une description sur leur disponibilité et leur usage, consultez la page de manuel Unix @code{open(2)@footnote{https://manpages.debian.org/open(2)}} ou la MSDN@footnote{https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx} sur Windows.

@geindex O_RDONLY (dans le module os)
@geindex O_WRONLY (dans le module os)
@geindex O_RDWR (dans le module os)
@geindex O_APPEND (dans le module os)
@geindex O_CREAT (dans le module os)
@geindex O_EXCL (dans le module os)
@geindex O_TRUNC (dans le module os)
@anchor{library/os os O_RDONLY}@anchor{2acc}
@deffn {Données} os.O_RDONLY
@anchor{library/os os O_WRONLY}@anchor{2acd}
@deffnx {Données} os.O_WRONLY
@anchor{library/os os O_RDWR}@anchor{2acf}
@deffnx {Données} os.O_RDWR
@anchor{library/os os O_APPEND}@anchor{2ad0}
@deffnx {Données} os.O_APPEND
@anchor{library/os os O_CREAT}@anchor{2ad1}
@deffnx {Données} os.O_CREAT
@anchor{library/os os O_EXCL}@anchor{27d3}
@deffnx {Données} os.O_EXCL
@anchor{library/os os O_TRUNC}@anchor{2ad2}
@deffnx {Données} os.O_TRUNC

Les constantes ci-dessus sont disponibles sur Unix et Windows.
@end deffn

@geindex O_DSYNC (dans le module os)
@geindex O_RSYNC (dans le module os)
@geindex O_SYNC (dans le module os)
@geindex O_NDELAY (dans le module os)
@geindex O_NONBLOCK (dans le module os)
@geindex O_NOCTTY (dans le module os)
@geindex O_CLOEXEC (dans le module os)
@anchor{library/os os O_DSYNC}@anchor{2ad3}
@deffn {Données} os.O_DSYNC
@anchor{library/os os O_RSYNC}@anchor{2ad4}
@deffnx {Données} os.O_RSYNC
@anchor{library/os os O_SYNC}@anchor{2ad5}
@deffnx {Données} os.O_SYNC
@anchor{library/os os O_NDELAY}@anchor{2ad6}
@deffnx {Données} os.O_NDELAY
@anchor{library/os os O_NONBLOCK}@anchor{e28}
@deffnx {Données} os.O_NONBLOCK
@anchor{library/os os O_NOCTTY}@anchor{2ad7}
@deffnx {Données} os.O_NOCTTY
@anchor{library/os os O_CLOEXEC}@anchor{1065}
@deffnx {Données} os.O_CLOEXEC

Les constantes ci-dessus sont uniquement disponibles sur Unix.


Modifié dans la version 3.3: Ajout de la constante @code{O_CLOCEXEC}.

@end deffn

@geindex O_BINARY (dans le module os)
@geindex O_NOINHERIT (dans le module os)
@geindex O_SHORT_LIVED (dans le module os)
@geindex O_TEMPORARY (dans le module os)
@geindex O_RANDOM (dans le module os)
@geindex O_SEQUENTIAL (dans le module os)
@geindex O_TEXT (dans le module os)
@anchor{library/os os O_BINARY}@anchor{2ace}
@deffn {Données} os.O_BINARY
@anchor{library/os os O_NOINHERIT}@anchor{2ad8}
@deffnx {Données} os.O_NOINHERIT
@anchor{library/os os O_SHORT_LIVED}@anchor{2ad9}
@deffnx {Données} os.O_SHORT_LIVED
@anchor{library/os os O_TEMPORARY}@anchor{2ada}
@deffnx {Données} os.O_TEMPORARY
@anchor{library/os os O_RANDOM}@anchor{2adb}
@deffnx {Données} os.O_RANDOM
@anchor{library/os os O_SEQUENTIAL}@anchor{2adc}
@deffnx {Données} os.O_SEQUENTIAL
@anchor{library/os os O_TEXT}@anchor{2add}
@deffnx {Données} os.O_TEXT

Les constantes ci-dessus sont uniquement disponibles sur Windows.
@end deffn

@geindex O_EVTONLY (dans le module os)
@geindex O_FSYNC (dans le module os)
@geindex O_SYMLINK (dans le module os)
@geindex O_NOFOLLOW_ANY (dans le module os)
@anchor{library/os os O_EVTONLY}@anchor{804}
@deffn {Données} os.O_EVTONLY
@anchor{library/os os O_FSYNC}@anchor{805}
@deffnx {Données} os.O_FSYNC
@anchor{library/os os O_SYMLINK}@anchor{806}
@deffnx {Données} os.O_SYMLINK
@anchor{library/os os O_NOFOLLOW_ANY}@anchor{807}
@deffnx {Données} os.O_NOFOLLOW_ANY

The above constants are only available on macOS.


Modifié dans la version 3.10: Add @ref{804,,O_EVTONLY}, @ref{805,,O_FSYNC}, @ref{806,,O_SYMLINK}
and @ref{807,,O_NOFOLLOW_ANY} constants.

@end deffn

@geindex O_ASYNC (dans le module os)
@geindex O_DIRECT (dans le module os)
@geindex O_DIRECTORY (dans le module os)
@geindex O_NOFOLLOW (dans le module os)
@geindex O_NOATIME (dans le module os)
@geindex O_PATH (dans le module os)
@geindex O_TMPFILE (dans le module os)
@geindex O_SHLOCK (dans le module os)
@geindex O_EXLOCK (dans le module os)
@anchor{library/os os O_ASYNC}@anchor{2ade}
@deffn {Données} os.O_ASYNC
@anchor{library/os os O_DIRECT}@anchor{2adf}
@deffnx {Données} os.O_DIRECT
@anchor{library/os os O_DIRECTORY}@anchor{2ae0}
@deffnx {Données} os.O_DIRECTORY
@anchor{library/os os O_NOFOLLOW}@anchor{2ae1}
@deffnx {Données} os.O_NOFOLLOW
@anchor{library/os os O_NOATIME}@anchor{2ae2}
@deffnx {Données} os.O_NOATIME
@anchor{library/os os O_PATH}@anchor{f5d}
@deffnx {Données} os.O_PATH
@anchor{library/os os O_TMPFILE}@anchor{f5e}
@deffnx {Données} os.O_TMPFILE
@anchor{library/os os O_SHLOCK}@anchor{13e5}
@deffnx {Données} os.O_SHLOCK
@anchor{library/os os O_EXLOCK}@anchor{13e6}
@deffnx {Données} os.O_EXLOCK

Les constantes ci-dessus sont des extensions et ne sont pas présentes si elles ne sont pas définies par la bibliothèque C.


Modifié dans la version 3.4: Ajout de @ref{f5d,,O_PATH} sur les systèmes qui le gèrent. Ajout de @ref{f5e,,O_TMPFILE}, uniquement disponible sur Linux Kernel 3.11 ou plus récent.

@end deffn

@geindex openpty() (dans le module os)
@anchor{library/os os openpty}@anchor{2ae3}
@deffn {Fonction} os.openpty ()

@geindex module;pty

Ouvre une nouvelle paire pseudo-terminal. Renvoie une paire de descripteurs de fichiers @code{(master, slave)} pour le PTY et le TTY respectivement. Les nouveaux descripteurs de fichiers sont @ref{ee4,,non-héritables}. Pour une approche (légèrement) plus portable, utilisez le module @ref{b0,,pty}.

@ref{1ce0,,Availability}: Unix, not WASI.


Modifié dans la version 3.4: Les nouveaux descripteurs de fichiers sont maintenant non-héritables.

@end deffn

@geindex pipe() (dans le module os)
@anchor{library/os os pipe}@anchor{1768}
@deffn {Fonction} os.pipe ()

Crée un `pipe' (un tube). Renvoie une paire de descripteurs de fichiers @code{(r, w)} utilisables respectivement pour lire et pour écrire. Les nouveaux descripteurs de fichiers sont @ref{ee4,,non-héritables}.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.4: Les nouveaux descripteurs de fichiers sont maintenant non-héritables.

@end deffn

@geindex pipe2() (dans le module os)
@anchor{library/os os pipe2}@anchor{10ca}
@deffn {Fonction} os.pipe2 (flags, /)

Crée un `pipe' avec `flags' mis atomiquement. `flags' peut être construit en appliquant l'opérateur @code{|} (OU) sur une ou plus de ces valeurs : @ref{e28,,O_NONBLOCK}, @ref{1065,,O_CLOEXEC}. Renvoie une paire de descripteurs de fichiers @code{(r, w)} utilisables respectivement pour lire et pour écrire.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.3.

@end deffn

@geindex posix_fallocate() (dans le module os)
@anchor{library/os os posix_fallocate}@anchor{d81}
@deffn {Fonction} os.posix_fallocate (fd, offset, len, /)

Assure que suffisamment d'espace sur le disque est alloué pour le fichier spécifié par `fd' partant de `offset' et continuant sur `len' bytes.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex posix_fadvise() (dans le module os)
@anchor{library/os os posix_fadvise}@anchor{d80}
@deffn {Fonction} os.posix_fadvise (fd, offset, len, advice, /)

Annonce une intention d'accéder à des données selon un motif spécifique, et donc permettant au noyau de faire des optimisations. Le conseil `advice' s'applique à la région spécifiée par `fd', démarrant à `offset' et continuant sur `len' bytes. `advice' est une des valeurs suivantes : @ref{2ae4,,POSIX_FADV_NORMAL}, @ref{2ae5,,POSIX_FADV_SEQUENTIAL}, @ref{2ae6,,POSIX_FADV_RANDOM}, @ref{2ae7,,POSIX_FADV_NOREUSE}, @ref{2ae8,,POSIX_FADV_WILLNEED}, ou @ref{2ae9,,POSIX_FADV_DONTNEED}.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex POSIX_FADV_NORMAL (dans le module os)
@geindex POSIX_FADV_SEQUENTIAL (dans le module os)
@geindex POSIX_FADV_RANDOM (dans le module os)
@geindex POSIX_FADV_NOREUSE (dans le module os)
@geindex POSIX_FADV_WILLNEED (dans le module os)
@geindex POSIX_FADV_DONTNEED (dans le module os)
@anchor{library/os os POSIX_FADV_NORMAL}@anchor{2ae4}
@deffn {Données} os.POSIX_FADV_NORMAL
@anchor{library/os os POSIX_FADV_SEQUENTIAL}@anchor{2ae5}
@deffnx {Données} os.POSIX_FADV_SEQUENTIAL
@anchor{library/os os POSIX_FADV_RANDOM}@anchor{2ae6}
@deffnx {Données} os.POSIX_FADV_RANDOM
@anchor{library/os os POSIX_FADV_NOREUSE}@anchor{2ae7}
@deffnx {Données} os.POSIX_FADV_NOREUSE
@anchor{library/os os POSIX_FADV_WILLNEED}@anchor{2ae8}
@deffnx {Données} os.POSIX_FADV_WILLNEED
@anchor{library/os os POSIX_FADV_DONTNEED}@anchor{2ae9}
@deffnx {Données} os.POSIX_FADV_DONTNEED

Indicateurs qui peuvent être utilisés dans `advice' dans la fonction @ref{d80,,posix_fadvise()} et qui spécifient le motif d'accès qui est censé être utilisé.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex pread() (dans le module os)
@anchor{library/os os pread}@anchor{b4d}
@deffn {Fonction} os.pread (fd, n, offset, /)

Lit au maximum `n' octets depuis le descripteur de fichier `fd' à la position `offset' sans modifier cette position.

Renvoie une chaîne d'octets contenant les octets lus, ou une chaîne d'octets vide si la fin du fichier pointé par `fd' est atteinte.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex posix_openpt() (dans le module os)
@anchor{library/os os posix_openpt}@anchor{160b}
@deffn {Fonction} os.posix_openpt (oflag, /)

Open and return a file descriptor for a master pseudo-terminal device.

Calls the C standard library function @code{posix_openpt()}. The `oflag'
argument is used to set file status flags and file access modes as
specified in the manual page of @code{posix_openpt()} of your system.

The returned file descriptor is @ref{ee4,,non-inheritable}.
If the value @ref{1065,,O_CLOEXEC} is available on the system, it is added to
`oflag'.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.13.

@end deffn

@geindex preadv() (dans le module os)
@anchor{library/os os preadv}@anchor{b4b}
@deffn {Fonction} os.preadv (fd, buffers, offset, flags=0, /)

Lit depuis un descripteur de fichier `fd', à la position `offset' dans des @ref{d1b,,objets bytes-compatibles} mutables `buffers', sans modifier la position dans le fichier. Les données sont transférées dans chaque tampon, jusqu'à ce qu'il soit plein, tour à tour.

L'argument `flags' contient un OU logique bit-à-bit de zéro ou plusieurs des indicateurs suivants :


@itemize -

@item 
@ref{2aea,,RWF_HIPRI}

@item 
@ref{2aeb,,RWF_NOWAIT}
@end itemize

Renvoie le nombre total d'octets réellement lus, qui peut être inférieur à la capacité totale de tous les objets.

Le système d'exploitation peut définir une limite (valeur @ref{2aec,,sysconf()} @code{'SC_IOV_MAX'}) sur le nombre de mémoires tampons pouvant être utilisées.

Combine les fonctionnalités de @ref{b4c,,os.readv()} et @ref{b4d,,os.pread()}.

@ref{1ce0,,Availability}: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.


Ajouté dans la version 3.7.

@end deffn

@geindex RWF_NOWAIT (dans le module os)
@anchor{library/os os RWF_NOWAIT}@anchor{2aeb}
@deffn {Données} os.RWF_NOWAIT

Ne pas attendre pour des données qui ne sont pas immédiatement disponibles. Si cette option est spécifiée, l'appel système retourne instantanément s'il doit lire les données du stockage sous-jacent ou attendre un verrou.

If some data was successfully read, it will return the number of bytes read.
If no bytes were read, it will return @code{-1} and set errno to
@ref{2225,,errno.EAGAIN}.

@ref{1ce0,,Availability}: Linux >= 4.14.


Ajouté dans la version 3.7.

@end deffn

@geindex RWF_HIPRI (dans le module os)
@anchor{library/os os RWF_HIPRI}@anchor{2aea}
@deffn {Données} os.RWF_HIPRI

Lecture/écriture haute priorité. Permet aux systèmes de fichiers de type bloc d'utiliser le `polling' du périphérique, qui fournit une latence inférieure, mais peut utiliser des ressources supplémentaires.

Actuellement, sous Linux, cette fonctionnalité est utilisable uniquement sur un descripteur de fichier ouvert à l'aide de l'option @ref{2adf,,O_DIRECT}.

@ref{1ce0,,Availability}: Linux >= 4.6.


Ajouté dans la version 3.7.

@end deffn

@geindex ptsname() (dans le module os)
@anchor{library/os os ptsname}@anchor{160e}
@deffn {Fonction} os.ptsname (fd, /)

Return the name of the slave pseudo-terminal device associated with the
master pseudo-terminal device to which the file descriptor `fd' refers.
The file descriptor `fd' is not closed upon failure.

Calls the reentrant C standard library function @code{ptsname_r()} if
it is available; otherwise, the C standard library function
@code{ptsname()}, which is not guaranteed to be thread-safe, is called.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.13.

@end deffn

@geindex pwrite() (dans le module os)
@anchor{library/os os pwrite}@anchor{b50}
@deffn {Fonction} os.pwrite (fd, str, offset, /)

Écrit la chaîne d'octets de `str' dans le descripteur de fichier `fd' à la position `offset' en laissant la position dans le fichier inchangée.

Renvoie le nombre d'octets effectivement écrits.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex pwritev() (dans le module os)
@anchor{library/os os pwritev}@anchor{b4e}
@deffn {Fonction} os.pwritev (fd, buffers, offset, flags=0, /)

Write the `buffers' contents to file descriptor `fd' at an offset `offset',
leaving the file offset unchanged.  `buffers' must be a sequence of
@ref{d1b,,bytes-like objects}. Buffers are processed in
array order. Entire contents of the first buffer is written before
proceeding to the second, and so on.

L'argument `flags' contient un OU logique bit-à-bit de zéro ou plusieurs des indicateurs suivants :


@itemize -

@item 
@ref{2aed,,RWF_DSYNC}

@item 
@ref{2aee,,RWF_SYNC}

@item 
@ref{18d3,,RWF_APPEND}
@end itemize

Renvoie le nombre total d'octets effectivement écrits.

Le système d'exploitation peut définir une limite (valeur @ref{2aec,,sysconf()} @code{'SC_IOV_MAX'}) sur le nombre de mémoires tampons pouvant être utilisées.

Combine les fonctionnalités de @code{os. writev()} et @code{os. pwrite()}.

@ref{1ce0,,Availability}: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.


Ajouté dans la version 3.7.

@end deffn

@geindex RWF_DSYNC (dans le module os)
@anchor{library/os os RWF_DSYNC}@anchor{2aed}
@deffn {Données} os.RWF_DSYNC

Provide a per-write equivalent of the @ref{2ad3,,O_DSYNC} @ref{d7f,,os.open()} flag.
This flag effect applies only to the data range written by the system call.

@ref{1ce0,,Availability}: Linux >= 4.7.


Ajouté dans la version 3.7.

@end deffn

@geindex RWF_SYNC (dans le module os)
@anchor{library/os os RWF_SYNC}@anchor{2aee}
@deffn {Données} os.RWF_SYNC

Provide a per-write equivalent of the @ref{2ad5,,O_SYNC} @ref{d7f,,os.open()} flag.
This flag effect applies only to the data range written by the system call.

@ref{1ce0,,Availability}: Linux >= 4.7.


Ajouté dans la version 3.7.

@end deffn

@geindex RWF_APPEND (dans le module os)
@anchor{library/os os RWF_APPEND}@anchor{18d3}
@deffn {Données} os.RWF_APPEND

Provide a per-write equivalent of the @ref{2ad0,,O_APPEND} @ref{d7f,,os.open()}
flag. This flag is meaningful only for @ref{b4e,,os.pwritev()}, and its
effect applies only to the data range written by the system call. The
`offset' argument does not affect the write operation; the data is always
appended to the end of the file. However, if the `offset' argument is
@code{-1}, the current file `offset' is updated.

@ref{1ce0,,Availability}: Linux >= 4.16.


Ajouté dans la version 3.10.

@end deffn

@geindex read() (dans le module os)
@anchor{library/os os read}@anchor{d82}
@deffn {Fonction} os.read (fd, n, /)

Lit au maximum `n' octets du descripteur de fichier `fd'.

Renvoie une chaîne d'octets contenant les octets lus, ou une chaîne d'octets vide si la fin du fichier pointé par `fd' est atteinte.

@cartouche
@quotation Note 
Cette fonction est destinée aux E/S bas niveau et doit être appliquée à un descripteur de fichier comme renvoyé par @ref{d7f,,os.open()} ou @ref{1768,,pipe()}. Pour lire dans un « fichier objet » renvoyé par la primitive @ref{505,,open()}, @ref{a75,,popen()} ou @ref{1eb7,,fdopen()}, ou par @code{stdin}, utilisez sa méthode @code{read()} ou @code{readline()}.
@end quotation
@end cartouche


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex sendfile() (dans le module os)
@anchor{library/os os sendfile}@anchor{afd}
@deffn {Fonction} os.sendfile (out_fd, in_fd, offset, count)

@deffnx {Fonction} os.sendfile (out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

Copy `count' bytes from file descriptor `in_fd' to file descriptor `out_fd'
starting at `offset'.
Return the number of bytes sent. When EOF is reached return @code{0}.

La première notation de fonction est prise en charge par toutes les plate-formes qui définissent @ref{afd,,sendfile()}.

On Linux, if `offset' is given as @code{None}, the bytes are read from the
current position of `in_fd' and the position of `in_fd' is updated.

The second case may be used on macOS and FreeBSD where `headers' and
`trailers' are arbitrary sequences of buffers that are written before and
after the data from `in_fd' is written. It returns the same as the first case.

On macOS and FreeBSD, a value of @code{0} for `count' specifies to send until
the end of `in_fd' is reached.

All platforms support sockets as `out_fd' file descriptor, and some platforms
allow other types (e.g. regular file, pipe) as well.

Les applications multiplateformes ne devraient pas utiliser les arguments  `headers', `trailers', et `flags'.

@ref{1ce0,,Availability}: Unix, not WASI.

@cartouche
@quotation Note 
Pour une interface de plus haut niveau de @ref{afd,,sendfile()}, voir @code{socket.socket.setfile()}.
@end quotation
@end cartouche


Ajouté dans la version 3.3.



Modifié dans la version 3.9: Les paramètres `out' et `in' ont été renommés `out_fd' et `in_fd'.

@end deffn

@geindex SF_NODISKIO (dans le module os)
@geindex SF_MNOWAIT (dans le module os)
@geindex SF_SYNC (dans le module os)
@anchor{library/os os SF_NODISKIO}@anchor{2aef}
@deffn {Données} os.SF_NODISKIO
@anchor{library/os os SF_MNOWAIT}@anchor{2af0}
@deffnx {Données} os.SF_MNOWAIT
@anchor{library/os os SF_SYNC}@anchor{2af1}
@deffnx {Données} os.SF_SYNC

Paramètres de la fonction @ref{afd,,sendfile()}, si l'implémentation les gère.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.3.

@end deffn

@geindex SF_NOCACHE (dans le module os)
@anchor{library/os os SF_NOCACHE}@anchor{2af2}
@deffn {Données} os.SF_NOCACHE

Parameter to the @ref{afd,,sendfile()} function, if the implementation supports
it. The data won't be cached in the virtual memory and will be freed afterwards.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.11.

@end deffn

@geindex set_blocking() (dans le module os)
@anchor{library/os os set_blocking}@anchor{e27}
@deffn {Fonction} os.set_blocking (fd, blocking, /)

Définit le mode bloquant d'un descripteur de fichier spécifié. Assigne l'indicateur @ref{e28,,O_NONBLOCK} si `blocking' vaut @code{False}, efface l'indicateur sinon.

Voir aussi @ref{e26,,get_blocking()} et @code{socket;socket.setblocking()}.

@ref{1ce0,,Availability}: Unix, Windows.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.

On Windows, this function is limited to pipes.


Ajouté dans la version 3.5.



Modifié dans la version 3.12: Added support for pipes on Windows.

@end deffn

@geindex splice() (dans le module os)
@anchor{library/os os splice}@anchor{803}
@deffn {Fonction} os.splice (src, dst, count, offset_src=None, offset_dst=None)

Transfer `count' bytes from file descriptor `src', starting from offset
`offset_src', to file descriptor `dst', starting from offset `offset_dst'.
At least one of the file descriptors must refer to a pipe. If `offset_src'
is @code{None}, then `src' is read from the current position; respectively for
`offset_dst'. The offset associated to the file descriptor that refers to a
pipe must be @code{None}. The files pointed to by `src' and `dst' must reside in
the same filesystem, otherwise an @ref{40d,,OSError} is raised with
@ref{2214,,errno} set to @ref{2ac3,,errno.EXDEV}.

Cette copie est faite sans le coût additionnel de transférer les données depuis le noyau vers l'espace utilisateur puis dans le sens inverse vers le noyau. En outre, certains systèmes de fichiers peuvent implémenter des optimisations supplémentaires. Cette copie est faite comme si les deux fichiers étaient ouverts en mode binaire.

Upon successful completion, returns the number of bytes spliced to or from
the pipe. A return value of 0 means end of input. If `src' refers to a
pipe, then this means that there was no data to transfer, and it would not
make sense to block because there are no writers connected to the write end
of the pipe.

@ref{1ce0,,Availability}: Linux >= 2.6.17 with glibc >= 2.5


Ajouté dans la version 3.10.

@end deffn

@geindex SPLICE_F_MOVE (dans le module os)
@geindex SPLICE_F_NONBLOCK (dans le module os)
@geindex SPLICE_F_MORE (dans le module os)
@anchor{library/os os SPLICE_F_MOVE}@anchor{2af3}
@deffn {Données} os.SPLICE_F_MOVE
@anchor{library/os os SPLICE_F_NONBLOCK}@anchor{2af4}
@deffnx {Données} os.SPLICE_F_NONBLOCK
@anchor{library/os os SPLICE_F_MORE}@anchor{2af5}
@deffnx {Données} os.SPLICE_F_MORE


Ajouté dans la version 3.10.

@end deffn

@geindex readv() (dans le module os)
@anchor{library/os os readv}@anchor{b4c}
@deffn {Fonction} os.readv (fd, buffers, /)

Lit depuis un descripteur de fichier `fd' dans une séquence d'@ref{d1b,,objets bytes-compatibles} mutables : `buffers'. Les données sont transférées dans chaque tampon, jusqu'à ce qu'il soit plein, tour à tour.

Renvoie le nombre total d'octets réellement lus, qui peut être inférieur à la capacité totale de tous les objets.

Le système d'exploitation peut définir une limite (valeur @ref{2aec,,sysconf()} @code{'SC_IOV_MAX'}) sur le nombre de mémoires tampons pouvant être utilisées.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex tcgetpgrp() (dans le module os)
@anchor{library/os os tcgetpgrp}@anchor{2af6}
@deffn {Fonction} os.tcgetpgrp (fd, /)

Renvoie le groupe de processus associé au terminal donné par `fd' (un descripteur de fichier ouvert comme renvoyé par @ref{d7f,,os.open()}).

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex tcsetpgrp() (dans le module os)
@anchor{library/os os tcsetpgrp}@anchor{2af7}
@deffn {Fonction} os.tcsetpgrp (fd, pg, /)

Place `pg' dans le groupe de processus associé au terminal donné par `fd' (un descripteur de fichier ouvert comme renvoyé par @ref{d7f,,os.open()}).

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex ttyname() (dans le module os)
@anchor{library/os os ttyname}@anchor{2af8}
@deffn {Fonction} os.ttyname (fd, /)

Renvoie une chaîne de caractères spécifiant le périphérique terminal associé au descripteur de fichier `fd'. Si `fd' n'est pas associé à un périphérique terminal, une exception est levée.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex unlockpt() (dans le module os)
@anchor{library/os os unlockpt}@anchor{160d}
@deffn {Fonction} os.unlockpt (fd, /)

Unlock the slave pseudo-terminal device associated with the master
pseudo-terminal device to which the file descriptor `fd' refers.
The file descriptor `fd' is not closed upon failure.

Calls the C standard library function @code{unlockpt()}.

@ref{1ce0,,Availability}: Unix, not WASI.


Ajouté dans la version 3.13.

@end deffn

@geindex write() (dans le module os)
@anchor{library/os os write}@anchor{d88}
@deffn {Fonction} os.write (fd, str, /)

Écrit la chaîne d'octets de `str' vers le descripteur de fichier `fd'.

Renvoie le nombre d'octets effectivement écrits.

@cartouche
@quotation Note 
Cette fonction est destinée aux entrées-sorties bas niveau et doit être appliquée à un descripteur de fichier comme renvoyé par @ref{d7f,,os.open()} ou @ref{1768,,pipe()}. Pour écrire dans un « fichier objet » renvoyé par la primitive @ref{505,,open()}, @ref{a75,,popen()}, ou par @ref{1eb7,,fdopen()}, ou par @ref{ac4,,sys.stdout} ou @ref{926,,sys.stderr}, utilisez sa méthode @code{write()}.
@end quotation
@end cartouche


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex writev() (dans le module os)
@anchor{library/os os writev}@anchor{b4f}
@deffn {Fonction} os.writev (fd, buffers, /)

Écrit le contenu de `buffers' vers le descripteur de fichier `fd'. `buffers' doit être une séquence d'@ref{d1b,,objets bytes-compatibles}. Les tampons sont traités dans l'ordre du tableau. Le contenu entier du premier tampon est écrit avant le traitement du second, etc.

Renvoie le nombre total d'octets effectivement écrits.

Le système d'exploitation peut définir une limite (valeur @ref{2aec,,sysconf()} @code{'SC_IOV_MAX'}) sur le nombre de mémoires tampons pouvant être utilisées.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@menu
* Demander la taille d'un terminal:: 
* Héritage de descripteurs de fichiers:: 

@end menu

@node Demander la taille d'un terminal,Héritage de descripteurs de fichiers,,Opérations sur les descripteurs de fichiers
@anchor{library/os querying-the-size-of-a-terminal}@anchor{2af9}@anchor{library/os terminal-size}@anchor{2afa}
@subsubsection Demander la taille d'un terminal



Ajouté dans la version 3.3.


@geindex get_terminal_size() (dans le module os)
@anchor{library/os os get_terminal_size}@anchor{10e2}
@deffn {Fonction} os.get_terminal_size (fd=STDOUT_FILENO, /)

Renvoie la taille du terminal comme un couple @code{(columns, lines)} de type @ref{27fc,,terminal_size}.

L'argument optionnel @code{fd} (par défaut  : @code{STDOUT_FILENO}, ou la sortie standard) spécifie le descripteur de fichier auquel la requête doit être envoyée.

Si le descripteur de fichier  n'est pas connecté à un terminal, une @ref{40d,,OSError} est levée.

@ref{10e3,,shutil.get_terminal_size()} est la fonction haut-niveau qui devrait normalement être utilisée, @code{os.get_terminal_size} en est l'implémentation bas-niveau.

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex terminal_size (classe dans os)
@anchor{library/os os terminal_size}@anchor{27fc}
@deffn {Classe} os.terminal_size

Une sous-classe de `tuple', contenant @code{(columns, lines)}, la taille du terminal.

@geindex columns (attribut os.terminal_size)
@anchor{library/os os terminal_size columns}@anchor{2afb}
@deffn {Attribut} columns

Longueur du terminal en caractères.
@end deffn

@geindex lines (attribut os.terminal_size)
@anchor{library/os os terminal_size lines}@anchor{2afc}
@deffn {Attribut} lines

Hauteur du terminal en caractères.
@end deffn
@end deffn

@node Héritage de descripteurs de fichiers,,Demander la taille d'un terminal,Opérations sur les descripteurs de fichiers
@anchor{library/os fd-inheritance}@anchor{ee4}@anchor{library/os inheritance-of-file-descriptors}@anchor{2afd}
@subsubsection Héritage de descripteurs de fichiers



Ajouté dans la version 3.4.


Un descripteur de fichier a un indicateur indiquant s'il peut être hérité par les processus-fils. Depuis Python 3.4, les descripteurs de fichiers créés par Python ne sont pas héritable par défaut.

Sur UNIX, les descripteurs de fichiers non-héritables sont fermés dans les processus-fils à l'exécution, les autres descripteurs sont hérités.

Sur Windows, les fichiers et identificateurs non-héritables sont fermés dans les processus-fils, à part les flux standards (descripteurs 0, 1, et 2 : `stdin', `stdout' et `stderr') qui sont toujours hérités. En utilisant les fonctions @ref{16bc,,spawn*}, tous les identificateurs héritables et les descripteurs de fichiers héritables sont hérités. En utilisant le module @ref{d5,,subprocess}, tous les descripteurs de fichiers (à part les flux standards) sont fermés, et les identificateurs héritables sont hérités seulement si le paramètre `close_fds' vaut @code{False}.

On WebAssembly platforms, the file descriptor cannot be modified.

@geindex get_inheritable() (dans le module os)
@anchor{library/os os get_inheritable}@anchor{ee5}
@deffn {Fonction} os.get_inheritable (fd, /)

Récupère le marqueur « héritable » (booléen) du descripteur de fichier spécifié.
@end deffn

@geindex set_inheritable() (dans le module os)
@anchor{library/os os set_inheritable}@anchor{ee6}
@deffn {Fonction} os.set_inheritable (fd, inheritable, /)

Définit le marqueur « héritable » du descripteur de fichier spécifié.
@end deffn

@geindex get_handle_inheritable() (dans le module os)
@anchor{library/os os get_handle_inheritable}@anchor{ee7}
@deffn {Fonction} os.get_handle_inheritable (handle, /)

Récupère le marqueur « héritable » (booléen) de l'identificateur spécifié.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex set_handle_inheritable() (dans le module os)
@anchor{library/os os set_handle_inheritable}@anchor{ee8}
@deffn {Fonction} os.set_handle_inheritable (handle, inheritable, /)

Définit le marqueur « héritable » de l'identificateur spécifié.

@ref{1ce0,,Availability}: Windows.
@end deffn

@node Fichiers et répertoires,Gestion des processus,Opérations sur les descripteurs de fichiers,os --- Miscellaneous operating system interfaces
@anchor{library/os files-and-directories}@anchor{2afe}@anchor{library/os os-file-dir}@anchor{2a90}
@subsubsection Fichiers et répertoires


Sur certaines plate-formes Unix, beaucoup de ces fonctions gèrent une ou plusieurs des fonctionnalités suivantes :
@anchor{library/os path-fd}@anchor{b4a}

@itemize *

@item 
`specifying a file descriptor:'
Normally the `path' argument provided to functions in the @ref{a0,,os} module
must be a string specifying a file path.  However, some functions now
alternatively accept an open file descriptor for their `path' argument.
The function will then operate on the file referred to by the descriptor.
(For POSIX systems, Python will call the variant of the function prefixed
with @code{f} (e.g. call @code{fchdir} instead of @code{chdir}).)

You can check whether or not `path' can be specified as a file descriptor
for a particular function on your platform using @ref{10dd,,os.supports_fd}.
If this functionality is unavailable, using it will raise a
@ref{225,,NotImplementedError}.

If the function also supports `dir_fd' or `follow_symlinks' arguments, it's
an error to specify one of those when supplying `path' as a file descriptor.
@end itemize
@anchor{library/os dir-fd}@anchor{10cb}

@itemize *

@item 
`paths relative to directory descriptors:' If `dir_fd' is not @code{None}, it
should be a file descriptor referring to a directory, and the path to operate
on should be relative; path will then be relative to that directory.  If the
path is absolute, `dir_fd' is ignored.  (For POSIX systems, Python will call
the variant of the function with an @code{at} suffix and possibly prefixed with
@code{f} (e.g. call @code{faccessat} instead of @code{access}).

You can check whether or not `dir_fd' is supported for a particular function
on your platform using @ref{10d8,,os.supports_dir_fd}.  If it's unavailable,
using it will raise a @ref{225,,NotImplementedError}.
@end itemize
@anchor{library/os follow-symlinks}@anchor{10cc}

@itemize *

@item 
`not following symlinks:' If `follow_symlinks' is
@code{False}, and the last element of the path to operate on is a symbolic link,
the function will operate on the symbolic link itself rather than the file
pointed to by the link.  (For POSIX systems, Python will call the @code{l...}
variant of the function.)

You can check whether or not `follow_symlinks' is supported for a particular
function on your platform using @ref{27e7,,os.supports_follow_symlinks}.
If it's unavailable, using it will raise a @ref{225,,NotImplementedError}.
@end itemize

@geindex access() (dans le module os)
@anchor{library/os os access}@anchor{10cd}
@deffn {Fonction} os.access (path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

Utilise l'`uid'/`gid' réel pour tester l'accès à `path'. Notez que la plupart des opérations utiliseront l'`uid'/`gid' effectif, dès lors cette méthode peut être utilisée dans un environnement `suid'/`sgid' pour tester si l'utilisateur invoquant a les droits d'accès pour accéder à `path'. `mode' devrait être @ref{2aff,,F_OK} pour tester l'existence de `path', ou il peut être le OR (OU inclusif) d'une ou plusieurs des constantes suivantes : @ref{2b00,,R_OK}, @ref{2b01,,W_OK}, et @ref{2b02,,X_OK} pour tester les permissions. Renvoie @ref{bfb,,True} si l'accès est permis, et @ref{b25,,False} s'il ne l'est pas. Voir la page de manuel Unix @code{access(2)@footnote{https://manpages.debian.org/access(2)}} pour plus d'informations.

Cette fonction peut gérer la spécification de @ref{10cb,,chemins relatifs vers des descripteurs de fichiers} et @ref{10cc,,le suivi des liens symboliques}.

Si `effective_id' vaut @code{True}, @ref{10cd,,access()} effectuera ses vérifications d'accès en utilisant l'`uid'/`gid' effectif à la place de l'`uid'/`gid' réel. `effective_ids' peut ne pas être géré sur votre plate-forme, vous pouvez vérifier s'il est disponible en utilisant @ref{10de,,os.supports_effective_ids}. S'il est indisponible, l'utiliser lèvera une @ref{225,,NotImplementedError}.

@cartouche
@quotation Note 
Utiliser @ref{10cd,,access()} pour vérifier si un utilisateur est autorisé (par exemple) à ouvrir un fichier avant d'effectivement le faire en utilisant @ref{505,,open()} crée une faille de sécurité : l'utilisateur peut exploiter le court intervalle de temps entre la vérification et l'ouverture du fichier pour le manipuler. Il est préférable d'utiliser les techniques @ref{2b03,,EAFP}. Par exemple :

@example
if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"
@end example

est mieux écrit comme suit :

@example
try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()
@end example
@end quotation
@end cartouche

@cartouche
@quotation Note 
Les opérations d'entrées/sorties peuvent échouer même quand @ref{10cd,,access()} indique qu'elles devraient réussir, particulièrement pour les opérations sur les systèmes de fichiers réseaux qui peuvent avoir une sémantique de permissions au-delà du modèle de bits de permission usuel POSIX.
@end quotation
@end cartouche


Modifié dans la version 3.3: Paramètres `dir_fd', `effective_ids', et `follow_symlinks' ajoutés.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex F_OK (dans le module os)
@geindex R_OK (dans le module os)
@geindex W_OK (dans le module os)
@geindex X_OK (dans le module os)
@anchor{library/os os F_OK}@anchor{2aff}
@deffn {Données} os.F_OK
@anchor{library/os os R_OK}@anchor{2b00}
@deffnx {Données} os.R_OK
@anchor{library/os os W_OK}@anchor{2b01}
@deffnx {Données} os.W_OK
@anchor{library/os os X_OK}@anchor{2b02}
@deffnx {Données} os.X_OK

Valeurs à passer au paramètre `mode' de @ref{10cd,,access()} pour tester respectivement l'existence, les droits de lecture, d'écriture et d'exécution.
@end deffn

@geindex chdir() (dans le module os)
@anchor{library/os os chdir}@anchor{5f8}
@deffn {Fonction} os.chdir (path)

@geindex directory;changing

Change le répertoire de travail actuel par `path'.

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}. Le descripteur doit référencer un répertoire ouvert, pas un fichier ouvert.

Cette fonction peut lever @ref{40d,,OSError} et des sous-classes telles que @ref{eae,,FileNotFoundError}, @ref{d30,,PermissionError} et @ref{1043,,NotADirectoryError}.

Lève un @ref{1848,,événement d'audit} @code{os.chdir} avec l'argument @code{path}.


Modifié dans la version 3.3: Prise en charge de la spécification de `path' par un descripteur de fichier sur certaines plate-formes.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex chflags() (dans le module os)
@anchor{library/os os chflags}@anchor{10ce}
@deffn {Fonction} os.chflags (path, flags, *, follow_symlinks=True)

Définit les marqueurs de `path' par la valeur numérique `flags'. `flags' peut prendre une combinaison (OU bit-à-bit) des valeurs suivantes (comme défini dans le module @ref{d0,,stat}) :


@itemize *

@item 
@ref{278e,,stat.UF_NODUMP}

@item 
@ref{278f,,stat.UF_IMMUTABLE}

@item 
@ref{2790,,stat.UF_APPEND}

@item 
@ref{2791,,stat.UF_OPAQUE}

@item 
@ref{2792,,stat.UF_NOUNLINK}

@item 
@ref{2793,,stat.UF_COMPRESSED}

@item 
@ref{2796,,stat.UF_HIDDEN}

@item 
@ref{279a,,stat.SF_ARCHIVED}

@item 
@ref{279b,,stat.SF_IMMUTABLE}

@item 
@ref{279c,,stat.SF_APPEND}

@item 
@ref{279e,,stat.SF_NOUNLINK}

@item 
@ref{279f,,stat.SF_SNAPSHOT}
@end itemize

Cette fonction prend en charge @ref{10cc,,le suivi des liens symboliques}.

Lève un @ref{1848,,événement d'audit} @code{os.chflags} avec les arguments @code{path}, @code{flags}.

@ref{1ce0,,Availability}: Unix, not WASI.


Modifié dans la version 3.3: Added the `follow_symlinks' parameter.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex chmod() (dans le module os)
@anchor{library/os os chmod}@anchor{218}
@deffn {Fonction} os.chmod (path, mode, *, dir_fd=None, follow_symlinks=True)

Change le mode de `path' par la valeur numérique `mode'. `mode' peut prendre une des valeurs suivantes (comme défini dans le module @ref{d0,,stat}) ou une combinaison (OU bit-à-bit) de ces valeurs :


@itemize *

@item 
@ref{277a,,stat.S_ISUID}

@item 
@ref{277b,,stat.S_ISGID}

@item 
@ref{277d,,stat.S_ENFMT}

@item 
@ref{277e,,stat.S_ISVTX}

@item 
@ref{278a,,stat.S_IREAD}

@item 
@ref{278b,,stat.S_IWRITE}

@item 
@ref{278c,,stat.S_IEXEC}

@item 
@ref{277f,,stat.S_IRWXU}

@item 
@ref{2780,,stat.S_IRUSR}

@item 
@ref{2781,,stat.S_IWUSR}

@item 
@ref{2782,,stat.S_IXUSR}

@item 
@ref{2783,,stat.S_IRWXG}

@item 
@ref{2784,,stat.S_IRGRP}

@item 
@ref{2785,,stat.S_IWGRP}

@item 
@ref{277c,,stat.S_IXGRP}

@item 
@ref{2786,,stat.S_IRWXO}

@item 
@ref{2787,,stat.S_IROTH}

@item 
@ref{2788,,stat.S_IWOTH}

@item 
@ref{2789,,stat.S_IXOTH}
@end itemize

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}, @ref{10cb,,les chemins relatifs à des descripteurs de répertoires}, et @ref{10cc,,le non-suivi des liens symboliques}.

@cartouche
@quotation Note 
Although Windows supports @ref{218,,chmod()}, you can only set the file's
read-only flag with it (via the @code{stat.S_IWRITE} and @code{stat.S_IREAD}
constants or a corresponding integer value).  All other bits are ignored.
The default value of `follow_symlinks' is @code{False} on Windows.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.
@end quotation
@end cartouche

Lève un @ref{1848,,événement d'audit} @code{os.chmod} avec les arguments @code{path}, @code{mode}, @code{dir_fd}.


Modifié dans la version 3.3: Prise en charge de la spécification de `path' par un répertoire ouvert et des arguments `dir_fd' et `follow_symlinks' ajoutés.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.13: Added support for a file descriptor and the `follow_symlinks' argument
on Windows.

@end deffn

@geindex chown() (dans le module os)
@anchor{library/os os chown}@anchor{10cf}
@deffn {Fonction} os.chown (path, uid, gid, *, dir_fd=None, follow_symlinks=True)

Change l'identifiant du propriétaire et du groupe de `path' par les valeurs numériques `uid' et `gid'. Pour laisser l'un de ces identifiants inchangé, le définir à @code{-1}.

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}, @ref{10cb,,les chemins relatifs à des descripteurs de répertoires}, et @ref{10cc,,le non-suivi des liens symboliques}.

Voir @ref{23d,,shutil.chown()} pour une fonction de plus haut-niveau qui accepte des noms en plus des identifiants numériques.

Lève un @ref{1848,,événement d'audit} @code{os.chown} avec les arguments @code{path}, @code{uid}, @code{gid}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.


Modifié dans la version 3.3: Prise en charge de la spécification de `path' par un répertoire ouvert et des arguments `dir_fd' et `follow_symlinks' ajoutés.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex chroot() (dans le module os)
@anchor{library/os os chroot}@anchor{1921}
@deffn {Fonction} os.chroot (path)

Change le répertoire racine du processus actuel par `path'.

@ref{1ce0,,Availability}: Unix, not WASI, not Android.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex fchdir() (dans le module os)
@anchor{library/os os fchdir}@anchor{d76}
@deffn {Fonction} os.fchdir (fd)

Change le répertoire de travail actuel par le répertoire représenté par le descripteur de fichier `fd'. Le descripteur doit référencer un répertoire ouvert, pas un fichier ouvert. Depuis Python 3.3, c'est équivalent à @code{os.chdir(fd)}.

Lève un @ref{1848,,événement d'audit} @code{os.chdir} avec l'argument @code{path}.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex getcwd() (dans le module os)
@anchor{library/os os getcwd}@anchor{1521}
@deffn {Fonction} os.getcwd ()

Renvoie une chaîne de caractères représentant le répertoire de travail actuel.
@end deffn

@geindex getcwdb() (dans le module os)
@anchor{library/os os getcwdb}@anchor{a7f}
@deffn {Fonction} os.getcwdb ()

Renvoie une chaîne de `bytes' représentant le répertoire de travail actuel.


Modifié dans la version 3.8: La fonction utilise maintenant l'encodage UTF-8 sur Windows, plutôt que la `page de code' ANSI : la 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} explique la raison. Cette fonction n'est plus obsolète sur Windows.

@end deffn

@geindex lchflags() (dans le module os)
@anchor{library/os os lchflags}@anchor{2b04}
@deffn {Fonction} os.lchflags (path, flags)

Définit les marqueurs de `path' par la valeur numérique `flags', comme @ref{10ce,,chflags()}, mais ne suit pas les liens symboliques. Depuis Python 3.3, c'est équivalent à @code{os.chflags(path, flags, follow_symlinks=False)}.

Lève un @ref{1848,,événement d'audit} @code{os.chflags} avec les arguments @code{path}, @code{flags}.

@ref{1ce0,,Availability}: Unix, not WASI.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex lchmod() (dans le module os)
@anchor{library/os os lchmod}@anchor{217}
@deffn {Fonction} os.lchmod (path, mode)

Change le mode de `path' par la valeur numérique `mode'. Si `path' est un lien symbolique, ça affecte le lien symbolique à la place de la cible. Voir la documentation pour les valeurs possibles de `mode' pour @ref{218,,chmod()}. Depuis Python 3.3, c'est équivalent à @code{os.chmod(path, mode, follow_symlinks=False)}.

@code{lchmod()} is not part of POSIX, but Unix implementations may have it if
changing the mode of symbolic links is supported.

Lève un @ref{1848,,événement d'audit} @code{os.chmod} avec les arguments @code{path}, @code{mode}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix, Windows, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.13: Added support on Windows.

@end deffn

@geindex lchown() (dans le module os)
@anchor{library/os os lchown}@anchor{2b05}
@deffn {Fonction} os.lchown (path, uid, gid)

Change les identifiants du propriétaire et du groupe de `path' par `uid' et `gid'. Cette fonction ne suivra pas les liens symboliques. Depuis Python 3.3, c'est équivalent à @code{os.chown(path, uid, gid, follow_symlinks=False)}.

Lève un @ref{1848,,événement d'audit} @code{os.chown} avec les arguments @code{path}, @code{uid}, @code{gid}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex link() (dans le module os)
@anchor{library/os os link}@anchor{10d0}
@deffn {Fonction} os.link (src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)

Crée un lien matériel appelé `dst' pointant sur `src'.

Cette fonction prend en charge la spécification `src_dir_fd' et/ou `dst_dir_fd' pour préciser @ref{10cb,,des chemins relatifs à des descripteurs de répertoires}, et @ref{10cc,,le non-suivi des liens symboliques}.

Lève un @ref{1848,,événement d'audit} @code{os.link} avec les arguments @code{src}, @code{dst}, @code{src_dir_ds}, @code{dst_dir_fd}.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.2: Prise en charge de Windows.



Modifié dans la version 3.3: Added the `src_dir_fd', `dst_dir_fd', and `follow_symlinks' parameters.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `src' et `dst'.

@end deffn

@geindex listdir() (dans le module os)
@anchor{library/os os listdir}@anchor{10da}
@deffn {Fonction} os.listdir (path='.')

Return a list containing the names of the entries in the directory given by
`path'.  The list is in arbitrary order, and does not include the special
entries @code{'.'} and @code{'..'} even if they are present in the directory.
If a file is removed from or added to the directory during the call of
this function, whether a name for that file be included is unspecified.

`path' peut être un @ref{29d,,path-like object}.  Si `path' est de type @code{bytes} (directement ou indirectement à travers une interface @ref{c3f,,PathLike}), les noms de fichiers renvoyés seront aussi de type @code{bytes} ; dans toutes les autres circonstances, ils seront de type @code{str}.

Cette fonction peut également gérer @ref{b4a,,la spécification de descripteurs de fichiers}. Le descripteur doit référencer un répertoire.

Lève un @ref{1848,,événement d'audit} @code{os.listdir} avec l'argument @code{path}.

@cartouche
@quotation Note 
Pour encoder des noms de fichiers de type @code{str} en @code{bytes}, utilisez la fonction @code{encode()}.
@end quotation
@end cartouche


@subsubheading Voir aussi


La fonction @ref{a4d,,scandir()} renvoie les entrées du répertoire ainsi que leurs attributs , offrant une meilleure performance pour beaucoup de cas utilisés fréquemment.



Modifié dans la version 3.2: Le paramètre `path' est devenu optionnel.



Modifié dans la version 3.3: Ajout de la possibilité de spécifier `path' comme descripteur de fichier ouvert.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex listdrives() (dans le module os)
@anchor{library/os os listdrives}@anchor{487}
@deffn {Fonction} os.listdrives ()

Return a list containing the names of drives on a Windows system.

A drive name typically looks like @code{'C:\\'}. Not every drive name
will be associated with a volume, and some may be inaccessible for
a variety of reasons, including permissions, network connectivity
or missing media. This function does not test for access.

May raise @ref{40d,,OSError} if an error occurs collecting the drive
names.

Raises an @ref{1848,,auditing event} @code{os.listdrives} with no arguments.

@ref{1ce0,,Availability}: Windows


Ajouté dans la version 3.12.

@end deffn

@geindex listmounts() (dans le module os)
@anchor{library/os os listmounts}@anchor{489}
@deffn {Fonction} os.listmounts (volume)

Return a list containing the mount points for a volume on a Windows
system.

`volume' must be represented as a GUID path, like those returned by
@ref{488,,os.listvolumes()}. Volumes may be mounted in multiple locations
or not at all. In the latter case, the list will be empty. Mount
points that are not associated with a volume will not be returned by
this function.

The mount points return by this function will be absolute paths, and
may be longer than the drive name.

Raises @ref{40d,,OSError} if the volume is not recognized or if an error
occurs collecting the paths.

Raises an @ref{1848,,auditing event} @code{os.listmounts} with argument @code{volume}.

@ref{1ce0,,Availability}: Windows


Ajouté dans la version 3.12.

@end deffn

@geindex listvolumes() (dans le module os)
@anchor{library/os os listvolumes}@anchor{488}
@deffn {Fonction} os.listvolumes ()

Return a list containing the volumes in the system.

Volumes are typically represented as a GUID path that looks like
@code{\\?\Volume@{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx@}\}. Files can
usually be accessed through a GUID path, permissions allowing.
However, users are generally not familiar with them, and so the
recommended use of this function is to retrieve mount points
using @ref{489,,os.listmounts()}.

May raise @ref{40d,,OSError} if an error occurs collecting the volumes.

Raises an @ref{1848,,auditing event} @code{os.listvolumes} with no arguments.

@ref{1ce0,,Availability}: Windows


Ajouté dans la version 3.12.

@end deffn

@geindex lstat() (dans le module os)
@anchor{library/os os lstat}@anchor{48b}
@deffn {Fonction} os.lstat (path, *, dir_fd=None)

Perform the equivalent of an @code{lstat()} system call on the given path.
Similar to @ref{48a,,stat()}, but does not follow symbolic links. Return a
@ref{1475,,stat_result} object.

Sur les plate-formes qui ne gérant pas les liens symboliques, c'est un alias pour @ref{48a,,stat()}.

Depuis Python 3.3, c'est équivalent à @code{os.stat(path, dir_fd=dir_fd, follow_symlinks=False)}.

Cette fonction peut également gérer @ref{10cb,,des chemins relatifs à des descripteurs de répertoires}.


@subsubheading Voir aussi


La fonction @ref{48a,,stat()}.



Modifié dans la version 3.2: Prise en charge des les liens symboliques sur Windows 6.0 (Vista).



Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.8: On Windows, now opens reparse points that represent another path
(name surrogates), including symbolic links and directory junctions.
Other kinds of reparse points are resolved by the operating system as
for @ref{48a,,stat()}.

@end deffn

@geindex mkdir() (dans le module os)
@anchor{library/os os mkdir}@anchor{21a}
@deffn {Fonction} os.mkdir (path, mode=0o777, *, dir_fd=None)

Crée un répertoire appelé `path' avec pour mode, la valeur numérique `mode'.

If the directory already exists, @ref{1009,,FileExistsError} is raised. If a parent
directory in the path does not exist, @ref{eae,,FileNotFoundError} is raised.
@anchor{library/os mkdir-modebits}@anchor{2b06}
Sous certains systèmes, `mode' est ignoré.  Quand il est utilisé, il lui est premièrement appliqué le masque courant `umask'. Si des bits autres que les 9 derniers sont activés (c.-à-d. les 3 derniers chiffres de la représentation octale de `mode'), leur signification sera dépendante de la plate-forme.  Sous certaines plate-formes, ils seront ignorés et vous devrez appeler explicitement @ref{218,,chmod()} pour les modifier.

On Windows, a `mode' of @code{0o700} is specifically handled to apply access
control to the new directory such that only the current user and
administrators have access. Other values of `mode' are ignored.

Cette fonction peut également gérer @ref{10cb,,des chemins relatifs à des descripteurs de répertoires}.

Il est également possible  de créer des répertoires temporaires, voir la fonction @ref{21c,,tempfile.mkdtemp()} du module @ref{df,,tempfile}.

Lève un @ref{1848,,événement d'audit} @code{os.mkdir} avec les arguments @code{path}, @code{mode}, @code{dir_fd}.


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.13: Windows now handles a `mode' of @code{0o700}.

@end deffn

@geindex makedirs() (dans le module os)
@anchor{library/os os makedirs}@anchor{21b}
@deffn {Fonction} os.makedirs (name, mode=0o777, exist_ok=False)

@geindex directory;creating
@geindex UNC paths;and os.makedirs()

Fonction de création récursive de répertoires. Comme @ref{21a,,mkdir()} mais crée tous les répertoires de niveau intermédiaire nécessaires pour contenir le répertoire « feuille ».

The `mode' parameter is passed to @ref{21a,,mkdir()} for creating the leaf
directory; see @ref{2b06,,the mkdir() description} for how it
is interpreted.  To set the file permission bits of any newly created parent
directories you can set the umask before invoking @ref{21b,,makedirs()}.  The
file permission bits of existing parent directories are not changed.

If `exist_ok' is @code{False} (the default), a @ref{1009,,FileExistsError} is
raised if the target directory already exists.

@cartouche
@quotation Note 
Un appel à @ref{21b,,makedirs()} est confus si les éléments du chemin à créer contiennent @ref{2b07,,pardir} (par exemple, @code{".."} sur les systèmes UNIX).
@end quotation
@end cartouche

Cette fonction gère les chemins UNC correctement.

Lève un @ref{1848,,événement d'audit} @code{os.mkdir} avec les arguments @code{path}, @code{mode}, @code{dir_fd}.


Modifié dans la version 3.2: Added the `exist_ok' parameter.



Modifié dans la version 3.4.1: Avant Python 3.4.1, si `exist_ok' valait @code{True} et le répertoire à créer existait, @ref{21b,,makedirs()} aurait levé une erreur si `mode' n'était pas équivalent au mode du répertoire existant. Puisque ce comportement n'était pas possible ) implémenter de manière sécurisée, il a été retiré pour Python 3.4.1. Voir bpo-21082@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=21082}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.7: The `mode' argument no longer affects the file permission bits of
newly created intermediate-level directories.

@end deffn

@geindex mkfifo() (dans le module os)
@anchor{library/os os mkfifo}@anchor{d7d}
@deffn {Fonction} os.mkfifo (path, mode=0o666, *, dir_fd=None)

Crée un FIFO (`First In, First Out', ou un tube (`pipe' en anglais) nommé) appelé `path' avec le mode numérique `mode'. La valeur actuelle de `umask' est d'abord masquée du mode.

Cette fonction peut également gérer @ref{10cb,,des chemins relatifs à des descripteurs de répertoires}.

Les FIFOs sont des tubes qui peuvent être accédés comme des fichiers normaux. Les FIFOs existent jusqu'à ce qu'ils soient retirés (par exemple, à l'aide de @ref{10d6,,os.unlink()}). Généralement, les FIFOs sont utilisé comme communication entre des processus de type « client » et « serveur » : le serveur ouvre le FIFO pour le lire, et le client l'ouvre pour écrire dedans. Notez que @ref{d7d,,mkfifo()} n'ouvre pas le FIFO — il crée juste un point de rendez-vous.

@ref{1ce0,,Availability}: Unix, not WASI.


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex mknod() (dans le module os)
@anchor{library/os os mknod}@anchor{d7e}
@deffn {Fonction} os.mknod (path, mode=0o600, device=0, *, dir_fd=None)

Crée un nœud du système de fichiers (fichier, périphérique, fichier spécial, ou tuyau nommé) appelée `path'. `mode' spécifie à la fois les permissions à utiliser et le type de nœud à créer, en étant combiné (OR bit-à-bit) avec l'une des valeurs suivantes : @code{stat.S_IFREG}, @code{stat.S_IFCHR}, @code{stat.S_IFBLK}, et @code{stat.S_IFIFO} (ces constantes sont disponibles dans le module @ref{d0,,stat}). Pour @code{stat.S_IFCHR} et @code{stat.S_IFBLK}, `device' définit le fichier spécial de périphérique tout juste créé (probablement en utilisant @ref{15a5,,os.makedev()}), sinon, cet argument est ignoré.

Cette fonction peut également gérer @ref{10cb,,des chemins relatifs à des descripteurs de répertoires}.

@ref{1ce0,,Availability}: Unix, not WASI.


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex major() (dans le module os)
@anchor{library/os os major}@anchor{15a3}
@deffn {Fonction} os.major (device, /)

Extract the device major number from a raw device number (usually the
@code{st_dev} or @code{st_rdev} field from @code{stat}).
@end deffn

@geindex minor() (dans le module os)
@anchor{library/os os minor}@anchor{15a4}
@deffn {Fonction} os.minor (device, /)

Extract the device minor number from a raw device number (usually the
@code{st_dev} or @code{st_rdev} field from @code{stat}).
@end deffn

@geindex makedev() (dans le module os)
@anchor{library/os os makedev}@anchor{15a5}
@deffn {Fonction} os.makedev (major, minor, /)

Compose un nombre de périphérique brut à partir des nombres de périphérique mineur et majeur.
@end deffn

@geindex pathconf() (dans le module os)
@anchor{library/os os pathconf}@anchor{10db}
@deffn {Fonction} os.pathconf (path, name)

Renvoie des informations sur la configurations relatives à un fichier déterminé. `name' spécifie la valeur de configuration à récupérer ; ce peut être une chaîne de caractères qui est le nom d'une valeur système particulière. Ces noms sont spécifiés dans certains standards (POSIX.1, Unix 95, Unix 98, etc). Certaines plate-formes définissent des noms supplémentaires également. Les noms connus du système d'exploitation hôte sont donnés dans le dictionnaire @code{pathconf_names}. Pour les variables de configuration non incluses dans ce `mapping', passer un entier pour `name' est également accepté.

Si `name' est une chaîne de caractères et n'est pas connu, une @ref{1ff,,ValueError} est levée. Si une valeur spécifique de `name' n'est pas gérée par le système hôte, même si elle est incluse dans @code{pathconf_names}, une @ref{40d,,OSError} est levée avec @ref{197d,,errno.EINVAL} pour code d'erreur.

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex pathconf_names (dans le module os)
@anchor{library/os os pathconf_names}@anchor{2b08}
@deffn {Données} os.pathconf_names

Dictionnaire liant les noms acceptés par les fonctions @ref{10db,,pathconf()} et @ref{2ac4,,fpathconf()} aux valeurs entières définies pour ces noms par le système d'exploitation hôte. Cette variable peut être utilisée pour déterminer l'ensemble des noms connus du système d'exploitation.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex readlink() (dans le module os)
@anchor{library/os os readlink}@anchor{90d}
@deffn {Fonction} os.readlink (path, *, dir_fd=None)

Renvoie une chaîne de caractères représentant le chemin vers lequel le lien symbolique pointe. Le résultat peut être soit un chemin relatif, soit un chemin absolu. S'il est relatif, il peut être converti en chemin absolu en utilisant @code{os.path.join(os.path.dirname(path), result)}.

Si `path' est une chaîne de caractères (directement ou indirectement à travers une interface @ref{c3f,,PathLike}), le résultat sera aussi une chaîne de caractères, et l'appel pourra lever une UnicodeDecodeError. Si `path' est une chaîne d'octets (directement ou indirectement), le résultat sera une chaîne d'octets.

Cette fonction peut également gérer @ref{10cb,,des chemins relatifs à des descripteurs de répertoires}.

Lorsque vous essayez de résoudre un chemin qui peut contenir des liens, utilisez @ref{222,,realpath()} pour gérer correctement la récursion et les différences de plate-forme.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.2: Prise en charge des les liens symboliques sur Windows 6.0 (Vista).



Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} sur Unix.



Modifié dans la version 3.8: Accepte un @ref{29d,,path-like object} et une chaine d’octets sous Windows.

Added support for directory junctions, and changed to return the
substitution path (which typically includes @code{\\?\} prefix) rather
than the optional "print name" field that was previously returned.

@end deffn

@geindex remove() (dans le module os)
@anchor{library/os os remove}@anchor{10d1}
@deffn {Fonction} os.remove (path, *, dir_fd=None)

Remove (delete) the file `path'.  If `path' is a directory, an
@ref{40d,,OSError} is raised.  Use @ref{10d4,,rmdir()} to remove directories.
If the file does not exist, a @ref{eae,,FileNotFoundError} is raised.

Cette fonction prend en charge @ref{10cb,,des chemins relatifs à des descripteurs de répertories}.

Sur Windows, tenter de retirer un fichier en cours d'utilisation cause la levée d'une exception, sur Unix, l'entrée du répertoire est supprimé mais l'espace de stockage alloué au fichier ne sera pas disponible avant que le fichier original ne soit plus utilisé.

La fonction est sémantiquement identique à @ref{10d6,,unlink()}.

Lève un @ref{1848,,événement d'audit} @code{os.remove} avec les arguments @code{path}, @code{dir_fd}.


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex removedirs() (dans le module os)
@anchor{library/os os removedirs}@anchor{2b09}
@deffn {Fonction} os.removedirs (name)

@geindex directory;deleting

Supprime des répertoires récursivement. Fonctionne comme @ref{10d4,,rmdir()} si ce n'est que si le répertoire feuille est retiré avec succès, @ref{2b09,,removedirs()} essaye de supprimer successivement chaque répertoire parent mentionné dans `path' jusqu'à ce qu'un erreur ne soit levée (ce qui est ignoré car la signification générale en est qu'un répertoire parent n'est pas vide). Par exemple, @code{os.removedirs('foo/bar/baz')} supprimera d'abord le répertoire @code{'foo/bar/baz'}, et ensuite supprimera @code{'foo/bar'} et puis @code{'foo'} s'ils sont vides. Lève une @ref{40d,,OSError} si le répertoire feuille n'a pas pu être supprimé avec succès.

Lève un @ref{1848,,événement d'audit} @code{os.remove} avec les arguments @code{path}, @code{dir_fd}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex rename() (dans le module os)
@anchor{library/os os rename}@anchor{10d2}
@deffn {Fonction} os.rename (src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Renomme le fichier ou le répertoire `src' en `dst'. Si `dst' existe, l'opération échoue avec une sous-classe @ref{40d,,OSError} dans un certain nombre de cas :

On Windows, if `dst' exists a @ref{1009,,FileExistsError} is always raised.
The operation may fail if `src' and `dst' are on different filesystems. Use
@ref{a4a,,shutil.move()} to support moves to a different filesystem.

On Unix, if `src' is a file and `dst' is a directory or vice-versa, an
@ref{1042,,IsADirectoryError} or a @ref{1043,,NotADirectoryError} will be raised
respectively.  If both are directories and `dst' is empty, `dst' will be
silently replaced.  If `dst' is a non-empty directory, an @ref{40d,,OSError}
is raised. If both are files, `dst' will be replaced silently if the user
has permission.  The operation may fail on some Unix flavors if `src' and
`dst' are on different filesystems.  If successful, the renaming will be an
atomic operation (this is a POSIX requirement).

Cette fonction prend en charge les spécifications `src_dir_fd' et/ou `dst_dir_fd' pour fournir @ref{10cb,,des chemins relatifs à des descripteurs de fichiers}.

Si vous désirez un écrasement multiplateformes de la destination, utilisez la fonction @ref{10d3,,replace()}.

Lève un @ref{1848,,événement d'audit} @code{os.rename} avec les arguments @code{src}, @code{dst}, @code{src_dir_ds}, @code{dst_dir_fd}.


Modifié dans la version 3.3: Added the `src_dir_fd' and `dst_dir_fd' parameters.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `src' et `dst'.

@end deffn

@geindex renames() (dans le module os)
@anchor{library/os os renames}@anchor{2b0a}
@deffn {Fonction} os.renames (old, new)

Fonction récursive de renommage de fichiers ou répertoires. Fonctionne comme @ref{10d2,,rename()}, si ce n'est que la création d'un répertoire intermédiaire nécessaire pour rendre le nouveau chemin correct est essayé en premier. Après le renommage, les répertoires correspondant aux segments de chemin les plus à droite de l'ancien nom seront élagués en utilisant @ref{2b09,,removedirs()}.

@cartouche
@quotation Note 
Cette fonction peut échouer avec la nouvelle structure de dictionnaire définie si vous n'avez pas les permissions nécessaires pour supprimer le répertoire ou fichier feuille.
@end quotation
@end cartouche

Lève un @ref{1848,,événement d'audit} @code{os.rename} avec les arguments @code{src}, @code{dst}, @code{src_dir_ds}, @code{dst_dir_fd}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `old' et `new'.

@end deffn

@geindex replace() (dans le module os)
@anchor{library/os os replace}@anchor{10d3}
@deffn {Fonction} os.replace (src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Rename the file or directory `src' to `dst'.  If `dst' is a non-empty directory,
@ref{40d,,OSError} will be raised.  If `dst' exists and is a file, it will
be replaced silently if the user has permission.  The operation may fail
if `src' and `dst' are on different filesystems.  If successful,
the renaming will be an atomic operation (this is a POSIX requirement).

Cette fonction prend en charge les spécifications `src_dir_fd' et/ou `dst_dir_fd' pour fournir @ref{10cb,,des chemins relatifs à des descripteurs de fichiers}.

Lève un @ref{1848,,événement d'audit} @code{os.rename} avec les arguments @code{src}, @code{dst}, @code{src_dir_ds}, @code{dst_dir_fd}.


Ajouté dans la version 3.3.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `src' et `dst'.

@end deffn

@geindex rmdir() (dans le module os)
@anchor{library/os os rmdir}@anchor{10d4}
@deffn {Fonction} os.rmdir (path, *, dir_fd=None)

Remove (delete) the directory `path'.  If the directory does not exist or is
not empty, a @ref{eae,,FileNotFoundError} or an @ref{40d,,OSError} is raised
respectively.  In order to remove whole directory trees,
@ref{2f5,,shutil.rmtree()} can be used.

Cette fonction prend en charge @ref{10cb,,des chemins relatifs à des descripteurs de répertories}.

Lève un @ref{1848,,événement d'audit} @code{os.rmdir} avec les arguments @code{path}, @code{dir_fd}.


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex scandir() (dans le module os)
@anchor{library/os os scandir}@anchor{a4d}
@deffn {Fonction} os.scandir (path='.')

Return an iterator of @ref{485,,os.DirEntry} objects corresponding to the
entries in the directory given by `path'. The entries are yielded in
arbitrary order, and the special entries @code{'.'} and @code{'..'} are not
included.  If a file is removed from or added to the directory after
creating the iterator, whether an entry for that file be included is
unspecified.

Utiliser @ref{a4d,,scandir()} plutôt que @ref{10da,,listdir()} peut significativement améliorer les performances des codes qui nécessitent aussi l'accès aux types des fichiers ou à leurs attributs, puisque les objets @ref{485,,os.DirEntry} exposent ces informations si le système d'exploitation les fournit en scannant le répertoire. Toutes les méthodes de @ref{485,,os.DirEntry} peuvent réaliser un appel système, mais @ref{2b0b,,is_dir()} et @ref{d71,,is_file()} n'en requièrent normalement un que pour les liens symboliques ; @ref{1683,,os.DirEntry.stat()} nécessite toujours un appel système sous Unix, mais seulement pour les liens symboliques sous Windows.

`path' peut être un @ref{29d,,path-like object}.  Si `path' est de type @code{bytes} (directement ou indirectement à travers une interface @ref{c3f,,PathLike}), le type des attributs @ref{2b0c,,name} et @ref{1605,,path} de chaque @ref{485,,os.DirEntry} sera @code{bytes} ; dans toutes les autres circonstances, ils seront de type @code{str}.

Cette fonction peut également gérer @ref{b4a,,la spécification de descripteurs de fichiers}. Le descripteur doit référencer un répertoire.

Lève un @ref{1848,,événement d'audit} @code{os.scandir} avec l'argument @code{path}.

L'itérateur @ref{a4d,,scandir()} gère le protocole @ref{5be,,context manager} et possède la méthode suivante :

@geindex close() (méthode os.scandir)
@anchor{library/os os scandir close}@anchor{caa}
@deffn {Méthode} scandir.close ()

Ferme l'itérateur et libère les ressources acquises.

Elle est appelée automatiquement quand l'itérateur est entièrement consommé ou collecté par le ramasse-miettes, ou quand une erreur survient durant l'itération.  Il est cependant conseillé de l'appeler explicitement ou d'utiliser l'instruction @ref{5bc,,with}.


Ajouté dans la version 3.6.

@end deffn

L'exemple suivant montre une utilisation simple de @ref{a4d,,scandir()} pour afficher tous les fichiers (à part les répertoires) dans le chemin donné par `path' et ne débutant pas par @code{'.'}. L'appel @code{entry.is_file()} ne va généralement pas faire d'appel système supplémentaire :

@example
with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)
@end example

@cartouche
@quotation Note 
On Unix-based systems, @ref{a4d,,scandir()} uses the system's
opendir()@footnote{https://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html}
and
readdir()@footnote{https://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html}
functions. On Windows, it uses the Win32
FindFirstFileW@footnote{https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx}
and
FindNextFileW@footnote{https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx}
functions.
@end quotation
@end cartouche


Ajouté dans la version 3.5.



Modifié dans la version 3.6: Added support for the @ref{5be,,context manager} protocol and the
@ref{caa,,close()} method.  If a @ref{a4d,,scandir()} iterator is neither
exhausted nor explicitly closed a @ref{241,,ResourceWarning} will be emitted
in its destructor.

La fonction accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.7: Ajout de la gestion des @ref{b4a,,descripteurs de fichiers} sur Unix.

@end deffn

@geindex DirEntry (classe dans os)
@anchor{library/os os DirEntry}@anchor{485}
@deffn {Classe} os.DirEntry

Objet donné par @ref{a4d,,scandir()} pour exposer le chemin du fichier et d'autres attributs de fichier d'une entrée du répertoire.

@ref{a4d,,scandir()} fournira autant d'informations que possible sans faire d'appels système additionnels. Quand un appel système @code{stat()} ou @code{lstat()} est réalisé, l'objet @code{os.DirEntry} mettra le résultat en cache.

Les instances @code{os.DirEntry} ne sont pas censées être stockées dans des structures de données à longue durée de vie ; si vous savez que les métadonnées du fichier ont changé ou si un certain temps s'est écoulé depuis l'appel à @ref{a4d,,scandir()}, appelez @code{os.stat(entry.path)} pour mettre à jour ces informations.

Puisque les méthodes de @code{os.DirEntry} peuvent réaliser des appels système, elles peuvent aussi lever des @ref{40d,,OSError}. Si vous avez besoin d'un contrôle fin des erreurs, vous pouvez attraper les @ref{40d,,OSError} en appelant les méthodes de @code{os.DirEntry} et les traiter comme il vous semble.

Pour être directement utilisable comme un @ref{29d,,path-like object}, @code{os.DirEntry} implémente l'interface @ref{c3f,,PathLike}.

Les attributs et méthodes des instances de @code{os.DirEntry} sont les suivants :

@geindex name (attribut os.DirEntry)
@anchor{library/os os DirEntry name}@anchor{2b0c}
@deffn {Attribut} name

Le nom de fichier de base de l'entrée, relatif à l'argument `path' de @ref{a4d,,scandir()}.

L'attribut @ref{2a8a,,name} sera de type @code{bytes} si l'argument `path' de @ref{a4d,,scandir()} est de type @code{bytes}, sinon il sera de type @code{str}. Utilisez @ref{c42,,fsdecode()} pour décoder des noms de fichiers de types `byte'.
@end deffn

@geindex path (attribut os.DirEntry)
@anchor{library/os os DirEntry path}@anchor{1605}
@deffn {Attribut} path

Le nom entier de l'entrée : équivalent à @code{os.path.join(scandir_path, entry.name)} où `scandir_path' est l'argument `path' de @ref{a4d,,scandir()}. Le chemin est absolu uniquement si l'argument `path' de @ref{a4d,,scandir()} était absolu. Si l'argument `path' à la fonction @ref{a4d,,scandir()} est un @ref{b4a,,descripteur de fichier} l'attribut @ref{a1,,path} sera égal à l'attribut @ref{2a8a,,name}.

L'attribut @ref{a1,,path} sera de type @code{bytes} si l'argument `path' de la fonction @ref{a4d,,scandir()} est de type @code{bytes}, sinon il sera de type @code{str}. Utilisez @ref{c42,,fsdecode()} pour décoder des noms de fichiers de type `bytes'.
@end deffn

@geindex inode() (méthode os.DirEntry)
@anchor{library/os os DirEntry inode}@anchor{1663}
@deffn {Méthode} inode ()

Renvoie le numéro d'`inode' de l'entrée.

Le résultat est mis en cache dans l'objet @code{os.DirEntry}. Utilisez @code{os.stat(entry.path, follow_symlinks=False).st_ino} pour obtenir l'information à jour.

Au premier appel non mis en cache, un appel système est requis sur Windows, mais pas sur Unix.
@end deffn

@geindex is_dir() (méthode os.DirEntry)
@anchor{library/os os DirEntry is_dir}@anchor{2b0b}
@deffn {Méthode} is_dir (*, follow_symlinks=True)

Renvoie @code{True} si cette entrée est un répertoire ou un lien symbolique pointant vers un répertoire ; renvoie @code{False} si l'entrée est (ou pointe vers) un autre type de fichier, ou s'il n'existe plus.

Si `follow_symlinks' vaut @code{False}, renvoie @code{True} uniquement si l'entrée est un répertoire (sans suivre les liens symboliques) ; renvoie @code{False} si l'entrée est n'importe quel autre type de fichier ou s'il n'existe plus.

Le résultat est mis en cache dans l'objet @code{os.DirEntry}, avec un cache séparé pour les valeurs @code{True} ou @code{False} de `follow_symlinks'. Appelez @ref{48a,,os.stat()} avec @ref{2761,,stat.S_ISDIR()} pour obtenir l'information à jour.

Au premier appel non mis en cache, aucun appel système n'est requis dans la plupart du temps. Spécifiquement, sans les liens symboliques, ni Windows, ni Unix ne requiert l'appel système, sauf sur certains systèmes de fichiers sur Unix, comme les système de fichiers de réseau qui renvoient @code{dirent.d_type == DT_UNKNOWN}. Si l'entrée est un lien symbolique, un appel système sera requis pour suivre le lien symbolique, à moins que `follow_symlinks' vaille @code{False}.

Cette méthode peut lever une @ref{40d,,OSError} tout comme une @ref{d30,,PermissionError}, mais @ref{eae,,FileNotFoundError} est interceptée et pas levée.
@end deffn

@geindex is_file() (méthode os.DirEntry)
@anchor{library/os os DirEntry is_file}@anchor{d71}
@deffn {Méthode} is_file (*, follow_symlinks=True)

Renvoie @code{True} si l'entrée est un fichier ou un lien symbolique pointant vers un fichier, renvoie @code{False} si l'entrée pointe est (ou pointe sur) sur un dossier ou sur un répertoire ou autre entrée non-fichier, ou s'il n'existe plus.

Si `follow_symlinks' vaut @code{False}, renvoie @code{True} uniquement si cette entrée est un fichier (sans suivre les liens symboliques). Renvoie @code{False} si l'entrée est un répertoire ou une autre entrée non-fichier, ou s'il n'existe plus.

Le résultat est mis en cache dans l'objet @code{os.DirEntry}. La mise en cache, les appels système réalisés, et les exceptions levées sont les mêmes que pour @ref{2b0b,,is_dir()}.
@end deffn

@geindex is_symlink() (méthode os.DirEntry)
@anchor{library/os os DirEntry is_symlink}@anchor{2b0d}
@deffn {Méthode} is_symlink ()

Renvoie @code{True} si l'entrée est un lien symbolique (même cassé). Renvoie @code{False} si l'entrée pinte vers un répertoire ou tout autre type de fichier, ou s'il n'existe plus.

Le résultat est mis en cache dans l'objet @code{os.DirEntry}. Appelez @ref{9fa,,os.path.islink()} pour obtenir l'information à jour.

Au premier appel non mis en cache, aucun appel système n'est requis. Spécifiquement, ni Windows ni Unix ne requiert d'appel système, excepté sur certains systèmes de fichiers Unix qui renvoient @code{dirent.d_type == DT_UNKNOWN}.

Cette méthode peut lever une @ref{40d,,OSError} tout comme une @ref{d30,,PermissionError}, mais @ref{eae,,FileNotFoundError} est interceptée et pas levée.
@end deffn

@geindex is_junction() (méthode os.DirEntry)
@anchor{library/os os DirEntry is_junction}@anchor{486}
@deffn {Méthode} is_junction ()

Return @code{True} if this entry is a junction (even if broken);
return @code{False} if the entry points to a regular directory, any kind
of file, a symlink, or if it doesn't exist anymore.

The result is cached on the @code{os.DirEntry} object. Call
@ref{48d,,os.path.isjunction()} to fetch up-to-date information.


Ajouté dans la version 3.12.

@end deffn

@geindex stat() (méthode os.DirEntry)
@anchor{library/os os DirEntry stat}@anchor{1683}
@deffn {Méthode} stat (*, follow_symlinks=True)

Renvoie un objet de type @code{stat.result} pour cette entrée. Cette méthode suit les liens symboliques par défaut. Pour avoir les statistiques sur un lien symbolique, ajouter l'argument @code{follow_symlinks=False}.

On Unix, this method always requires a system call. On Windows, it
only requires a system call if `follow_symlinks' is @code{True} and the
entry is a reparse point (for example, a symbolic link or directory
junction).

Sur Windows, les attributs @code{st_ino}, @code{st_dev} et @code{st_nlink} de la classe @ref{1475,,stat_result} sont toujours définis à 0. Appelez la fonction @ref{48a,,os.stat()} pour avoir ces attributs.

Le résultat est mis en cache dans l'objet @code{os.DirEntry}, avec un cache séparé pour les valeurs @code{True} ou @code{False} de `follow_symlinks'. Appelez @ref{48a,,os.stat()} pour obtenir l'information à jour.
@end deffn

Note that there is a nice correspondence between several attributes
and methods of @code{os.DirEntry} and of @ref{226,,pathlib.Path}.  In
particular, the @code{name} attribute has the same
meaning, as do the @code{is_dir()}, @code{is_file()}, @code{is_symlink()},
@code{is_junction()}, and @code{stat()} methods.


Ajouté dans la version 3.5.



Modifié dans la version 3.6: Prise en charge de l'interface @ref{c3f,,PathLike}.  Ajout du support des chemins @ref{1bd,,bytes} sous Windows.



Modifié dans la version 3.12: The @code{st_ctime} attribute of a stat result is deprecated on Windows.
The file creation time is properly available as @code{st_birthtime}, and
in the future @code{st_ctime} may be changed to return zero or the
metadata change time, if available.

@end deffn

@geindex stat() (dans le module os)
@anchor{library/os os stat}@anchor{48a}
@deffn {Fonction} os.stat (path, *, dir_fd=None, follow_symlinks=True)

Récupère le statut d'un fichier ou d'un descripteur de fichier. Réalise l'équivalent d'un appel système @code{stat()} sur le chemin donné. `path' peut être exprimé comme une chaîne de caractères ou d'octets -- directement ou indirectement à travers une interface @ref{c3f,,PathLike} -- ou comme un descripteur de fichier ouvert. Renvoie un objet @ref{1475,,stat_result}.

Cette fonction suit normalement les liens symboliques. Pour récupérer les informations d'un lien symbolique, ajoutez l'argument @code{follow_symlinks=False} ou utilisez la fonction @ref{48b,,lstat()}.

Cette fonction peut supporter la @ref{b4a,,spécification d'un descripteur de fichier} et @ref{10cc,,le non-suivi des liens symboliques}.

On Windows, passing @code{follow_symlinks=False} will disable following all
name-surrogate reparse points, which includes symlinks and directory
junctions. Other types of reparse points that do not resemble links or that
the operating system is unable to follow will be opened directly. When
following a chain of multiple links, this may result in the original link
being returned instead of the non-link that prevented full traversal. To
obtain stat results for the final path in this case, use the
@ref{222,,os.path.realpath()} function to resolve the path name as far as
possible and call @ref{48b,,lstat()} on the result. This does not apply to
dangling symlinks or junction points, which will raise the usual exceptions.

@geindex module;stat

Exemple :

@example
>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264
@end example


@subsubheading Voir aussi


les fonctions @ref{d79,,fstat()} et @ref{48b,,lstat()}.



Modifié dans la version 3.3: Added the `dir_fd' and `follow_symlinks' parameters,
specifying a file descriptor instead of a path.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.8: On Windows, all reparse points that can be resolved by the operating
system are now followed, and passing @code{follow_symlinks=False}
disables following all name surrogate reparse points. If the operating
system reaches a reparse point that it is not able to follow, `stat' now
returns the information for the original path as if
@code{follow_symlinks=False} had been specified instead of raising an error.

@end deffn

@geindex stat_result (classe dans os)
@anchor{library/os os stat_result}@anchor{1475}
@deffn {Classe} os.stat_result

Object whose attributes correspond roughly to the members of the
@code{stat} structure. It is used for the result of @ref{48a,,os.stat()},
@ref{d79,,os.fstat()} and @ref{48b,,os.lstat()}.

Attributs :

@geindex st_mode (attribut os.stat_result)
@anchor{library/os os stat_result st_mode}@anchor{2b0e}
@deffn {Attribut} st_mode

Mode du fichier : type du fichier et bits de mode du fichier (permissions).
@end deffn

@geindex st_ino (attribut os.stat_result)
@anchor{library/os os stat_result st_ino}@anchor{2b0f}
@deffn {Attribut} st_ino

Dépendant de la plateforme, mais lorsqu'il ne vaut pas zéro il identifie de manière unique le fichier pour une certaine valeur de @code{st_dev}. Typiquement :


@itemize *

@item 
le numéro d'`inode' sur Unix,

@item 
l’index de fichier@footnote{https://msdn.microsoft.com/fr-fr/library/aa363788} sur Windows
@end itemize
@end deffn

@geindex st_dev (attribut os.stat_result)
@anchor{library/os os stat_result st_dev}@anchor{2b10}
@deffn {Attribut} st_dev

Identifiant du périphérique sur lequel ce fichier se trouve.
@end deffn

@geindex st_nlink (attribut os.stat_result)
@anchor{library/os os stat_result st_nlink}@anchor{2b11}
@deffn {Attribut} st_nlink

Nombre de liens matériels.
@end deffn

@geindex st_uid (attribut os.stat_result)
@anchor{library/os os stat_result st_uid}@anchor{2b12}
@deffn {Attribut} st_uid

Identifiant d'utilisateur du propriétaire du fichier.
@end deffn

@geindex st_gid (attribut os.stat_result)
@anchor{library/os os stat_result st_gid}@anchor{2b13}
@deffn {Attribut} st_gid

Identifiant de groupe du propriétaire du fichier.
@end deffn

@geindex st_size (attribut os.stat_result)
@anchor{library/os os stat_result st_size}@anchor{2b14}
@deffn {Attribut} st_size

Taille du fichier en `bytes' si c'est un fichier normal ou un lien symbolique. La taille d'un lien symbolique est la longueur du nom de chemin qu'il contient sans le byte nul final.
@end deffn

Horodatages :

@geindex st_atime (attribut os.stat_result)
@anchor{library/os os stat_result st_atime}@anchor{2b15}
@deffn {Attribut} st_atime

Moment de l'accès le plus récent, exprimé en secondes.
@end deffn

@geindex st_mtime (attribut os.stat_result)
@anchor{library/os os stat_result st_mtime}@anchor{29a6}
@deffn {Attribut} st_mtime

Moment de la modification de contenu la plus récente, exprimé en secondes.
@end deffn

@geindex st_ctime (attribut os.stat_result)
@anchor{library/os os stat_result st_ctime}@anchor{2b16}
@deffn {Attribut} st_ctime

Time of most recent metadata change expressed in seconds.


Modifié dans la version 3.12: @code{st_ctime} is deprecated on Windows. Use @code{st_birthtime} for
the file creation time. In the future, @code{st_ctime} will contain
the time of the most recent metadata change, as for other platforms.

@end deffn

@geindex st_atime_ns (attribut os.stat_result)
@anchor{library/os os stat_result st_atime_ns}@anchor{2b17}
@deffn {Attribut} st_atime_ns

Moment de l'accès le plus récent, exprimé en nanosecondes, par un entier.


Ajouté dans la version 3.3.

@end deffn

@geindex st_mtime_ns (attribut os.stat_result)
@anchor{library/os os stat_result st_mtime_ns}@anchor{2b18}
@deffn {Attribut} st_mtime_ns

Moment de la modification de contenu la plus récente, exprimé en nanosecondes, par un entier.


Ajouté dans la version 3.3.

@end deffn

@geindex st_ctime_ns (attribut os.stat_result)
@anchor{library/os os stat_result st_ctime_ns}@anchor{2b19}
@deffn {Attribut} st_ctime_ns

Time of most recent metadata change expressed in nanoseconds as an
integer.


Ajouté dans la version 3.3.



Modifié dans la version 3.12: @code{st_ctime_ns} is deprecated on Windows. Use @code{st_birthtime_ns}
for the file creation time. In the future, @code{st_ctime} will contain
the time of the most recent metadata change, as for other platforms.

@end deffn

@geindex st_birthtime (attribut os.stat_result)
@anchor{library/os os stat_result st_birthtime}@anchor{2b1a}
@deffn {Attribut} st_birthtime

Time of file creation expressed in seconds. This attribute is not
always available, and may raise @ref{343,,AttributeError}.


Modifié dans la version 3.12: @code{st_birthtime} is now available on Windows.

@end deffn

@geindex st_birthtime_ns (attribut os.stat_result)
@anchor{library/os os stat_result st_birthtime_ns}@anchor{2b1b}
@deffn {Attribut} st_birthtime_ns

Time of file creation expressed in nanoseconds as an integer.
This attribute is not always available, and may raise
@ref{343,,AttributeError}.


Ajouté dans la version 3.12.

@end deffn

@cartouche
@quotation Note 
The exact meaning and resolution of the @ref{2b15,,st_atime},
@ref{29a6,,st_mtime}, @ref{2b16,,st_ctime} and @ref{2b1a,,st_birthtime} attributes
depend on the operating system and the file system. For example, on
Windows systems using the FAT32 file systems, @ref{29a6,,st_mtime} has
2-second resolution, and @ref{2b15,,st_atime} has only 1-day resolution.
See your operating system documentation for details.

Similarly, although @ref{2b17,,st_atime_ns}, @ref{2b18,,st_mtime_ns},
@ref{2b19,,st_ctime_ns} and @ref{2b1b,,st_birthtime_ns} are always expressed in
nanoseconds, many systems do not provide nanosecond precision.  On
systems that do provide nanosecond precision, the floating-point object
used to store @ref{2b15,,st_atime}, @ref{29a6,,st_mtime}, @ref{2b16,,st_ctime} and
@ref{2b1a,,st_birthtime} cannot preserve all of it, and as such will be
slightly inexact. If you need the exact timestamps you should always use
@ref{2b17,,st_atime_ns}, @ref{2b18,,st_mtime_ns}, @ref{2b19,,st_ctime_ns} and
@ref{2b1b,,st_birthtime_ns}.
@end quotation
@end cartouche

Sur certains systèmes Unix (tels que Linux), les attributs suivants peuvent également être disponibles :

@geindex st_blocks (attribut os.stat_result)
@anchor{library/os os stat_result st_blocks}@anchor{2b1c}
@deffn {Attribut} st_blocks

Nombre de blocs de 512 `bytes' alloués pour le fichier. Cette valeur peut être inférieure à @ref{2b14,,st_size}/512 quand le fichier a des trous.
@end deffn

@geindex st_blksize (attribut os.stat_result)
@anchor{library/os os stat_result st_blksize}@anchor{2b1d}
@deffn {Attribut} st_blksize

Taille de bloc « préférée » pour des entrées-sorties efficaces avec le système de fichiers. Écrire dans un fichier avec des blocs plus petits peut causer des modifications (lecture-écriture-réécriture) inefficaces.
@end deffn

@geindex st_rdev (attribut os.stat_result)
@anchor{library/os os stat_result st_rdev}@anchor{2b1e}
@deffn {Attribut} st_rdev

Type de périphérique si l'`inode' représente un périphérique.
@end deffn

@geindex st_flags (attribut os.stat_result)
@anchor{library/os os stat_result st_flags}@anchor{2b1f}
@deffn {Attribut} st_flags

Marqueurs définis par l'utilisateur pour le fichier.
@end deffn

Sur d'autres systèmes Unix (tels que FreeBSD), les attributs suivants peuvent être disponibles (mais peuvent être complétés uniquement lorsque le super-utilisateur `root' tente de les utiliser) :

@geindex st_gen (attribut os.stat_result)
@anchor{library/os os stat_result st_gen}@anchor{2b20}
@deffn {Attribut} st_gen

Nombre de génération de fichier.
@end deffn

Sur les systèmes Solaris et dérivés, les attributs suivants peuvent également être disponibles :

@geindex st_fstype (attribut os.stat_result)
@anchor{library/os os stat_result st_fstype}@anchor{b52}
@deffn {Attribut} st_fstype

Chaîne qui identifie de manière unique le type du système de fichiers qui contient le fichier.
@end deffn

On macOS systems, the following attributes may also be available:

@geindex st_rsize (attribut os.stat_result)
@anchor{library/os os stat_result st_rsize}@anchor{2b21}
@deffn {Attribut} st_rsize

Taillé réelle du fichier.
@end deffn

@geindex st_creator (attribut os.stat_result)
@anchor{library/os os stat_result st_creator}@anchor{2b22}
@deffn {Attribut} st_creator

Créateur du fichier.
@end deffn

@geindex st_type (attribut os.stat_result)
@anchor{library/os os stat_result st_type}@anchor{2b23}
@deffn {Attribut} st_type

Type du fichier.
@end deffn

On Windows systems, the following attributes are also available:

@geindex st_file_attributes (attribut os.stat_result)
@anchor{library/os os stat_result st_file_attributes}@anchor{e25}
@deffn {Attribut} st_file_attributes

Windows file attributes: @code{dwFileAttributes} member of the
@code{BY_HANDLE_FILE_INFORMATION} structure returned by
@code{GetFileInformationByHandle()}.
See the @code{FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE>}
constants in the @ref{d0,,stat} module.


Ajouté dans la version 3.5.

@end deffn

@geindex st_reparse_tag (attribut os.stat_result)
@anchor{library/os os stat_result st_reparse_tag}@anchor{2b24}
@deffn {Attribut} st_reparse_tag

When @ref{e25,,st_file_attributes} has the @ref{27ae,,FILE_ATTRIBUTE_REPARSE_POINT}
set, this field contains the tag identifying the type of reparse point.
See the @ref{27b3,,IO_REPARSE_TAG_*}
constants in the @ref{d0,,stat} module.
@end deffn

The standard module @ref{d0,,stat} defines functions and constants that are
useful for extracting information from a @code{stat} structure. (On
Windows, some items are filled with dummy values.)

For backward compatibility, a @ref{1475,,stat_result} instance is also
accessible as a tuple of at least 10 integers giving the most important (and
portable) members of the @code{stat} structure, in the order
@ref{2b0e,,st_mode}, @ref{2b0f,,st_ino}, @ref{2b10,,st_dev}, @ref{2b11,,st_nlink},
@ref{2b12,,st_uid}, @ref{2b13,,st_gid}, @ref{2b14,,st_size}, @ref{2b15,,st_atime},
@ref{29a6,,st_mtime}, @ref{2b16,,st_ctime}. More items may be added at the end by
some implementations. For compatibility with older Python versions,
accessing @ref{1475,,stat_result} as a tuple always returns integers.


Modifié dans la version 3.5: Windows renvoie maintenant l'index du fichier dans l'attribut @ref{2b0f,,st_ino}, lorsqu'il est disponible.



Modifié dans la version 3.7: Ajout de l'attribut @ref{b52,,st_fstype} sur Solaris et dérivés.



Modifié dans la version 3.8: Added the @ref{2b24,,st_reparse_tag} member on Windows.



Modifié dans la version 3.8: On Windows, the @ref{2b0e,,st_mode} member now identifies special
files as @code{S_IFCHR}, @code{S_IFIFO} or @code{S_IFBLK}
as appropriate.



Modifié dans la version 3.12: On Windows, @ref{2b16,,st_ctime} is deprecated. Eventually, it will
contain the last metadata change time, for consistency with other
platforms, but for now still contains creation time.
Use @ref{2b1a,,st_birthtime} for the creation time.

On Windows, @ref{2b0f,,st_ino} may now be up to 128 bits, depending
on the file system. Previously it would not be above 64 bits, and
larger file identifiers would be arbitrarily packed.

On Windows, @ref{2b1e,,st_rdev} no longer returns a value. Previously
it would contain the same as @ref{2b10,,st_dev}, which was incorrect.

Added the @ref{2b1a,,st_birthtime} member on Windows.

@end deffn

@geindex statvfs() (dans le module os)
@anchor{library/os os statvfs}@anchor{10dc}
@deffn {Fonction} os.statvfs (path)

Perform a @code{statvfs()} system call on the given path.  The return value is
an object whose attributes describe the filesystem on the given path, and
correspond to the members of the @code{statvfs} structure, namely:
@code{f_bsize}, @code{f_frsize}, @code{f_blocks}, @code{f_bfree},
@code{f_bavail}, @code{f_files}, @code{f_ffree}, @code{f_favail},
@code{f_flag}, @code{f_namemax}, @code{f_fsid}.

Deux constantes de module sont définies pour le champ-de-bits de l'attribut @code{f_flag} : si @code{SR_RDONLY} est activé, le système de fichiers est monté en lecture-seule, et si @code{ST_NOSUID} est activé, la sémantique des bits de `setuid' / `getuid' est désactivée ou non gérée.

Des constantes de module supplémentaires sont définies pour les systèmes basés sur GNU/glibc. Ces constantes sont @code{ST_NODEV} (interdit l'accès aux fichiers spéciaux du périphérique), @code{ST_NOEXEC} (interdit l'exécution de programmes), @code{ST_SYNCHRONOUS} (les écritures sont synchronisées en une fois), @code{ST_MANDLOCK} (permet les verrous impératifs sur un système de fichiers), @code{ST_WRITE} (écrit sur les fichiers/répertoires/liens symboliques), @code{ST_APPEND} (fichiers en ajout-seul), @code{ST_IMMUTABLE} (fichiers immuables), @code{ST_NOATIME} (ne met pas à jour les moments d'accès), @code{ST_NODIRATIME} (ne met pas à jour les moments d'accès aux répertoires), @code{ST_REALTIME} (Met `atime' à jour relativement à `mtime' / `ctime').

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.2: Ajout des constantes @code{ST_RDONLY} et @code{ST_NOSUID}.



Modifié dans la version 3.3: Ajout de la possibilité de spécifier `path' comme descripteur de fichier ouvert.



Modifié dans la version 3.4: Ajout des constantes @code{ST_NODEV}, @code{ST_NOEXEC}, @code{ST_SYNCHRONOUS}, @code{ST_MANDLOCK}, @code{ST_WRITE}, @code{ST_APPEND}, @code{ST_IMMUTABLE}, @code{ST_NOATIME}, @code{ST_NODIRATIME}, et @code{ST_RELATIME}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.7: Added the @code{f_fsid} attribute.

@end deffn

@geindex supports_dir_fd (dans le module os)
@anchor{library/os os supports_dir_fd}@anchor{10d8}
@deffn {Données} os.supports_dir_fd

A @ref{5c3,,set} object indicating which functions in the @ref{a0,,os}
module accept an open file descriptor for their `dir_fd' parameter.
Different platforms provide different features, and the underlying
functionality Python uses to implement the `dir_fd' parameter is not
available on all platforms Python supports.  For consistency's sake,
functions that may support `dir_fd' always allow specifying the
parameter, but will throw an exception if the functionality is used
when it's not locally available. (Specifying @code{None} for `dir_fd'
is always supported on all platforms.)

To check whether a particular function accepts an open file descriptor
for its `dir_fd' parameter, use the @code{in} operator on @code{supports_dir_fd}.
As an example, this expression evaluates to @code{True} if @ref{48a,,os.stat()}
accepts open file descriptors for `dir_fd' on the local platform:

@example
os.stat in os.supports_dir_fd
@end example

Actuellement, le paramètre `dir_fd' ne fonctionne que sur les plate-formes Unix. Il ne fonctionne jamais sur Windows.


Ajouté dans la version 3.3.

@end deffn

@geindex supports_effective_ids (dans le module os)
@anchor{library/os os supports_effective_ids}@anchor{10de}
@deffn {Données} os.supports_effective_ids

A @ref{5c3,,set} object indicating whether @ref{10cd,,os.access()} permits
specifying @code{True} for its `effective_ids' parameter on the local platform.
(Specifying @code{False} for `effective_ids' is always supported on all
platforms.)  If the local platform supports it, the collection will contain
@ref{10cd,,os.access()}; otherwise it will be empty.

This expression evaluates to @code{True} if @ref{10cd,,os.access()} supports
@code{effective_ids=True} on the local platform:

@example
os.access in os.supports_effective_ids
@end example

Currently `effective_ids' is only supported on Unix platforms;
it does not work on Windows.


Ajouté dans la version 3.3.

@end deffn

@geindex supports_fd (dans le module os)
@anchor{library/os os supports_fd}@anchor{10dd}
@deffn {Données} os.supports_fd

A @ref{5c3,,set} object indicating which functions in the
@ref{a0,,os} module permit specifying their `path' parameter as an open file
descriptor on the local platform.  Different platforms provide different
features, and the underlying functionality Python uses to accept open file
descriptors as `path' arguments is not available on all platforms Python
supports.

To determine whether a particular function permits specifying an open file
descriptor for its `path' parameter, use the @code{in} operator on
@code{supports_fd}. As an example, this expression evaluates to @code{True} if
@ref{5f8,,os.chdir()} accepts open file descriptors for `path' on your local
platform:

@example
os.chdir in os.supports_fd
@end example


Ajouté dans la version 3.3.

@end deffn

@geindex supports_follow_symlinks (dans le module os)
@anchor{library/os os supports_follow_symlinks}@anchor{27e7}
@deffn {Données} os.supports_follow_symlinks

A @ref{5c3,,set} object indicating which functions in the @ref{a0,,os} module
accept @code{False} for their `follow_symlinks' parameter on the local platform.
Different platforms provide different features, and the underlying
functionality Python uses to implement `follow_symlinks' is not available
on all platforms Python supports.  For consistency's sake, functions that
may support `follow_symlinks' always allow specifying the parameter, but
will throw an exception if the functionality is used when it's not locally
available.  (Specifying @code{True} for `follow_symlinks' is always supported
on all platforms.)

To check whether a particular function accepts @code{False} for its
`follow_symlinks' parameter, use the @code{in} operator on
@code{supports_follow_symlinks}.  As an example, this expression evaluates
to @code{True} if you may specify @code{follow_symlinks=False} when calling
@ref{48a,,os.stat()} on the local platform:

@example
os.stat in os.supports_follow_symlinks
@end example


Ajouté dans la version 3.3.

@end deffn

@geindex symlink() (dans le module os)
@anchor{library/os os symlink}@anchor{10d5}
@deffn {Fonction} os.symlink (src, dst, target_is_directory=False, *, dir_fd=None)

Crée un lien symbolique pointant vers `src' et appelé `dst'.

Sur Windows, un lien symbolique représente soit lien vers un fichier, soit lien vers un répertoire mais ne s'adapte pas dynamiquement au type de la cible. Si la cible existe le lien sera crée du même type que sa cible. Dans le cas où cible n'existe pas, si `target_is_directory' vaut @code{True} le lien symbolique sera créé comme un répertoire, sinon comme un fichier (par défaut). Sur les autres plateformes, `target_id_directory' est ignoré.

Cette fonction prend en charge @ref{10cb,,des chemins relatifs à des descripteurs de répertories}.

@cartouche
@quotation Note 
On newer versions of Windows 10, unprivileged accounts can create symlinks
if Developer Mode is enabled. When Developer Mode is not available/enabled,
the `SeCreateSymbolicLinkPrivilege' privilege is required, or the process
must be run as an administrator.

@ref{40d,,OSError} est levée quand la fonction est appelée par un utilisateur sans privilèges.
@end quotation
@end cartouche

Lève un @ref{1848,,événement d'audit} @code{os.symlink} avec les arguments @code{src}, @code{dst}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix, Windows.

The function is limited on WASI, see @ref{176f,,Plateformes WebAssembly} for more
information.


Modifié dans la version 3.2: Prise en charge des les liens symboliques sur Windows 6.0 (Vista).



Modifié dans la version 3.3: Added the `dir_fd' parameter, and now allow `target_is_directory'
on non-Windows platforms.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `src' et `dst'.



Modifié dans la version 3.8: Added support for unelevated symlinks on Windows with Developer Mode.

@end deffn

@geindex sync() (dans le module os)
@anchor{library/os os sync}@anchor{10f2}
@deffn {Fonction} os.sync ()

Force l'écriture de tout sur le disque.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex truncate() (dans le module os)
@anchor{library/os os truncate}@anchor{e29}
@deffn {Fonction} os.truncate (path, length)

Tronque le fichier correspondant à `path', afin qu'il soit au maximum long de `length' bytes.

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}.

Lève un @ref{1848,,événement d'audit} @code{os.truncate} avec les arguments @code{path}, @code{length}.

@ref{1ce0,,Availability}: Unix, Windows.


Ajouté dans la version 3.3.



Modifié dans la version 3.5: Prise en charge de Windows



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex unlink() (dans le module os)
@anchor{library/os os unlink}@anchor{10d6}
@deffn {Fonction} os.unlink (path, *, dir_fd=None)

Supprime (retire) le fichier `path'. Cette fonction est sémantiquement identique à @ref{10d1,,remove()}. Le nom @code{unlink} est un nom Unix traditionnel. Veuillez voir la documentation de @ref{10d1,,remove()} pour plus d'informations.

Lève un @ref{1848,,événement d'audit} @code{os.remove} avec les arguments @code{path}, @code{dir_fd}.


Modifié dans la version 3.3: Paramètre `dir_fd' ajouté.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex utime() (dans le module os)
@anchor{library/os os utime}@anchor{10d7}
@deffn {Fonction} os.utime (path, times=None, *[, ns], dir_fd=None, follow_symlinks=True)

Définit les derniers moments d'accès et de modification du fichier spécifiés par `path'.

La fonction @ref{10d7,,utime()} prend deux paramètres optionnels, `times' et `ns'. Ils spécifient le temps mis pour `path' et est utilisé comme suit :


@itemize -

@item 
Si `ns' est spécifié, ce doit être un couple de la forme @code{(atime_ns, mtime_ns)} où chaque membre est un entier qui exprime des nanosecondes.

@item 
Si `times' ne vaut pas @code{None}, ce doit être un couple de la forme @code{(atime, mtime)} où chaque membre est un entier ou une expression à virgule flottante.

@item 
Si `times' vaut @code{None}, et `ns' est non-spécifié. C'est équivalent à spécifier @code{ns = (atime_ns, mtime_ns)} où les deux moments sont le moment actuel.
@end itemize

Il est erroné de spécifier des `n'-uplets pour `times' et `ns' à la fois.

Note that the exact times you set here may not be returned by a subsequent
@ref{48a,,stat()} call, depending on the resolution with which your operating
system records access and modification times; see @ref{48a,,stat()}. The best
way to preserve exact times is to use the `st_atime_ns' and `st_mtime_ns'
fields from the @ref{48a,,os.stat()} result object with the `ns' parameter to
@ref{10d7,,utime()}.

Cette fonction prend en charge @ref{b4a,,la spécification d'un descripteur de fichier}, @ref{10cb,,les chemins relatifs à des descripteurs de répertoires}, et @ref{10cc,,le non-suivi des liens symboliques}.

Lève un @ref{1848,,événement d'audit} @code{os.utime} avec les arguments @code{path}, @code{times}, @code{ns}, @code{dir_fd}.


Modifié dans la version 3.3: Ajoute la prise en charge d'un descripteur de fichier pour `path' et des paramètres `dir_fd', `follow_symlinks' et `ns'.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex walk() (dans le module os)
@anchor{library/os os walk}@anchor{493}
@deffn {Fonction} os.walk (top, topdown=True, onerror=None, followlinks=False)

@geindex directory;walking
@geindex directory;traversal

Génère les noms de fichier dans un arbre de répertoire en parcourant l'arbre soit de bas-en-haut, soit de haut-en-bas. Pour chaque répertoire dans l'arbre enraciné en le répertoire `rop' (incluant ledit répertoire `top'), fournit un triplet @code{(dirpath, dirnames, filenames)}.

`dirpath' is a string, the path to the directory.  `dirnames' is a list of the
names of the subdirectories in `dirpath' (including symlinks to directories,
and excluding @code{'.'} and @code{'..'}).
`filenames' is a list of the names of the non-directory files in `dirpath'.
Note that the names in the lists contain no path components.  To get a full path
(which begins with `top') to a file or directory in `dirpath', do
@code{os.path.join(dirpath, name)}.  Whether or not the lists are sorted
depends on the file system.  If a file is removed from or added to the
`dirpath' directory during generating the lists, whether a name for that
file be included is unspecified.

Si l'argument optionnel `topdown' vaut @code{True} ou n'est pas spécifié, le triplet pour un répertoire est généré avant les triplets de tous ses sous-répertoires (les répertoires sont générés de haut-en-bas). Si `topdown' vaut @code{False}, le triplet pour un répertoire est généré après les triplets de tous ses sous-répertoires (les répertoires sont générés de bas-en-haut). Peu importe la valeur de `topdown', la liste des sous-répertoires est récupérée avant que les `n'-uplets pour le répertoires et ses sous-répertoires ne soient générés.

Quand `topdown' vaut @code{True}, l'appelant peut modifier la liste `dirnames' en place (par exemple en utilisant @ref{1734,,del} ou l'assignation par `slicing' (par tranches)) et @ref{493,,walk()} ne fera sa récursion que dans les sous-répertoires dont le nom reste dans `dirnames' ; cela peut être utilisé pour élaguer la recherche, imposer un ordre particulier de visite, ou encore pour informer @ref{493,,walk()} des répertoires créés par l'appelant ou renommés avant qu'il quitte @ref{493,,walk()} à nouveau. Modifier `dirnames' quand `topdown' vaut @code{False} n'a aucun effet dur le comportement du parcours parce qu'en mode bas-en-haut, les répertoires dans `dirnames' sont générés avant que `dirpath' ne soit lui-même généré.

Par défaut, les erreurs d'un appel à @ref{a4d,,scandir()} sont ignorées. Si l'argument optionnel `onerror' est spécifié, il doit être une fonction qui sera appelée avec un seul argument, une instance de @ref{40d,,OSError}. Elle peut rapporter l'erreur et continuer le parcours, ou lever l'exception pour avorter le parcours. Notez que le nom de fichier est disponible dans l'attribut @code{filename} de l'objet exception.

Par défaut, @ref{493,,walk()} ne parcourra pas les liens symboliques qui mènent à un répertoire. Définissez `followlinks' avec @code{True} pour visiter les répertoires pointés par des liens symboliques sur les systèmes qui le gère.

@cartouche
@quotation Note 
Soyez au courant que définir `followlinks' avec @code{True} peut mener à une récursion infinie si un lien pointe vers un répertoire parent de lui-même. @ref{493,,walk()} ne garde pas de trace des répertoires qu'il a déjà visité.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Si vous passez un chemin relatif, ne changer pas le répertoire de travail actuel entre deux exécutions de @ref{493,,walk()}. @ref{493,,walk()} ne change jamais le répertoire actuel, et suppose que l'appelant ne le fait pas non plus.
@end quotation
@end cartouche

Cet exemple affiche le nombre de bytes pris par des fichiers non-répertoires dans chaque répertoire à partir du répertoire de départ, si ce n'est qu'il ne cherche pas après un sous-répertoire CSV :

@example
import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories
@end example

Dans l'exemple suivant (simple implémentation d'un @ref{2f5,,shutil.rmtree()}), parcourir l'arbre de bas-en-haut est essentiel : @ref{10d4,,rmdir()} ne permet pas de supprimer un répertoire avant qu'un ne soit vide :

@example
# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)
@end example

Lève un @ref{1848,,événement d'audit} @code{os.walk} avec les arguments @code{top}, @code{topdown}, @code{onerror}, @code{followlinks}.


Modifié dans la version 3.5: Cette fonction appelle maintenant @ref{a4d,,os.scandir()} au lieu de @ref{10da,,os.listdir()}, ce qui la rend plus rapide en réduisant le nombre d'appels à @ref{48a,,os.stat()}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex fwalk() (dans le module os)
@anchor{library/os os fwalk}@anchor{b49}
@deffn {Fonction} os.fwalk (top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

@geindex directory;walking
@geindex directory;traversal

Se comporte exactement comme @ref{493,,walk()}, si ce n'est qu'il fournit un quadruplet @code{(dirpath, dirnames, filenames, dirfd)}, et gère @code{dir_fd}.

`dirpath', `dirnames' et `filenames' sont identiques à la sortie de @ref{493,,walk()} et `dirfd' est un descripteur de fichier faisant référence au répertoire `dirpath'.

Cette fonction prend toujours en charge @ref{10cb,,les chemins relatifs à des descripteurs de fichiers} et @ref{10cc,,le non-suivi des liens symboliques}. Notez cependant qu'à l'inverse des autres fonctions, la valeur par défaut de `follow_symlinks' pour @ref{493,,walk()} est @code{False}.

@cartouche
@quotation Note 
Puisque @ref{b49,,fwalk()} fournit des descripteurs de fichiers, ils ne sont valides que jusque la prochaine itération. Donc vous devriez les dupliquer (par exemple avec @ref{196b,,dup()}) si vous désirez les garder plus longtemps.
@end quotation
@end cartouche

Cet exemple affiche le nombre de bytes pris par des fichiers non-répertoires dans chaque répertoire à partir du répertoire de départ, si ce n'est qu'il ne cherche pas après un sous-répertoire CSV :

@example
import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories
@end example

Dans le prochain exemple, parcourir l'arbre de bas-en-haut est essentiel : @ref{10d4,,rmdir()} ne permet pas de supprimer un répertoire avant qu'il ne soit vide :

@example
# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)
@end example

Lève un @ref{1848,,événement d'audit} @code{os.fwalk} avec les arguments @code{top}, @code{topdown}, @code{onerror}, @code{follow_symlinks}, @code{dir_fd}.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.



Modifié dans la version 3.7: Ajout de la gestion des chemins de type @ref{1bd,,bytes}.

@end deffn

@geindex memfd_create() (dans le module os)
@anchor{library/os os memfd_create}@anchor{9f9}
@deffn {Fonction} os.memfd_create (name[, flags=os.MFD_CLOEXEC])

Create an anonymous file and return a file descriptor that refers to it.
`flags' must be one of the @code{os.MFD_*} constants available on the system
(or a bitwise ORed combination of them).  By default, the new file
descriptor is @ref{ee4,,non-inheritable}.

The name supplied in `name' is used as a filename and will be displayed as
the target of the corresponding symbolic link in the directory
@code{/proc/self/fd/}. The displayed name is always prefixed with @code{memfd:}
and serves only for debugging purposes. Names do not affect the behavior of
the file descriptor, and as such multiple files can have the same name
without any side effects.

@ref{1ce0,,Availability}: Linux >= 3.17 with glibc >= 2.27.


Ajouté dans la version 3.8.

@end deffn

@geindex MFD_CLOEXEC (dans le module os)
@geindex MFD_ALLOW_SEALING (dans le module os)
@geindex MFD_HUGETLB (dans le module os)
@geindex MFD_HUGE_SHIFT (dans le module os)
@geindex MFD_HUGE_MASK (dans le module os)
@geindex MFD_HUGE_64KB (dans le module os)
@geindex MFD_HUGE_512KB (dans le module os)
@geindex MFD_HUGE_1MB (dans le module os)
@geindex MFD_HUGE_2MB (dans le module os)
@geindex MFD_HUGE_8MB (dans le module os)
@geindex MFD_HUGE_16MB (dans le module os)
@geindex MFD_HUGE_32MB (dans le module os)
@geindex MFD_HUGE_256MB (dans le module os)
@geindex MFD_HUGE_512MB (dans le module os)
@geindex MFD_HUGE_1GB (dans le module os)
@geindex MFD_HUGE_2GB (dans le module os)
@geindex MFD_HUGE_16GB (dans le module os)
@anchor{library/os os MFD_CLOEXEC}@anchor{2b25}
@deffn {Données} os.MFD_CLOEXEC
@anchor{library/os os MFD_ALLOW_SEALING}@anchor{2b26}
@deffnx {Données} os.MFD_ALLOW_SEALING
@anchor{library/os os MFD_HUGETLB}@anchor{2b27}
@deffnx {Données} os.MFD_HUGETLB
@anchor{library/os os MFD_HUGE_SHIFT}@anchor{2b28}
@deffnx {Données} os.MFD_HUGE_SHIFT
@anchor{library/os os MFD_HUGE_MASK}@anchor{2b29}
@deffnx {Données} os.MFD_HUGE_MASK
@anchor{library/os os MFD_HUGE_64KB}@anchor{2b2a}
@deffnx {Données} os.MFD_HUGE_64KB
@anchor{library/os os MFD_HUGE_512KB}@anchor{2b2b}
@deffnx {Données} os.MFD_HUGE_512KB
@anchor{library/os os MFD_HUGE_1MB}@anchor{2b2c}
@deffnx {Données} os.MFD_HUGE_1MB
@anchor{library/os os MFD_HUGE_2MB}@anchor{2b2d}
@deffnx {Données} os.MFD_HUGE_2MB
@anchor{library/os os MFD_HUGE_8MB}@anchor{2b2e}
@deffnx {Données} os.MFD_HUGE_8MB
@anchor{library/os os MFD_HUGE_16MB}@anchor{2b2f}
@deffnx {Données} os.MFD_HUGE_16MB
@anchor{library/os os MFD_HUGE_32MB}@anchor{2b30}
@deffnx {Données} os.MFD_HUGE_32MB
@anchor{library/os os MFD_HUGE_256MB}@anchor{2b31}
@deffnx {Données} os.MFD_HUGE_256MB
@anchor{library/os os MFD_HUGE_512MB}@anchor{2b32}
@deffnx {Données} os.MFD_HUGE_512MB
@anchor{library/os os MFD_HUGE_1GB}@anchor{2b33}
@deffnx {Données} os.MFD_HUGE_1GB
@anchor{library/os os MFD_HUGE_2GB}@anchor{2b34}
@deffnx {Données} os.MFD_HUGE_2GB
@anchor{library/os os MFD_HUGE_16GB}@anchor{2b35}
@deffnx {Données} os.MFD_HUGE_16GB

These flags can be passed to @ref{9f9,,memfd_create()}.

@ref{1ce0,,Availability}: Linux >= 3.17 with glibc >= 2.27

The @code{MFD_HUGE*} flags are only available since Linux 4.14.


Ajouté dans la version 3.8.

@end deffn

@geindex eventfd() (dans le module os)
@anchor{library/os os eventfd}@anchor{802}
@deffn {Fonction} os.eventfd (initval[, flags=os.EFD_CLOEXEC])

Create and return an event file descriptor. The file descriptors supports
raw @ref{d82,,read()} and @ref{d88,,write()} with a buffer size of 8,
@ref{d8d,,select()}, @ref{2b36,,poll()} and similar. See man page
@code{eventfd(2)@footnote{https://manpages.debian.org/eventfd(2)}} for more information.  By default, the
new file descriptor is @ref{ee4,,non-inheritable}.

`initval' is the initial value of the event counter. The initial value
must be a 32 bit unsigned integer. Please note that the initial value is
limited to a 32 bit unsigned int although the event counter is an unsigned
64 bit integer with a maximum value of 2@w{^64}-2.

`flags' can be constructed from @ref{175c,,EFD_CLOEXEC},
@ref{175d,,EFD_NONBLOCK}, and @ref{175e,,EFD_SEMAPHORE}.

If @ref{175e,,EFD_SEMAPHORE} is specified and the event counter is non-zero,
@ref{2b37,,eventfd_read()} returns 1 and decrements the counter by one.

If @ref{175e,,EFD_SEMAPHORE} is not specified and the event counter is
non-zero, @ref{2b37,,eventfd_read()} returns the current event counter value and
resets the counter to zero.

If the event counter is zero and @ref{175d,,EFD_NONBLOCK} is not
specified, @ref{2b37,,eventfd_read()} blocks.

@ref{2b38,,eventfd_write()} increments the event counter. Write blocks if the
write operation would increment the counter to a value larger than
2@w{^64}-2.

Exemple :

@example
import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)
@end example

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.10.

@end deffn

@geindex eventfd_read() (dans le module os)
@anchor{library/os os eventfd_read}@anchor{2b37}
@deffn {Fonction} os.eventfd_read (fd)

Read value from an @ref{802,,eventfd()} file descriptor and return a 64 bit
unsigned int. The function does not verify that `fd' is an @ref{802,,eventfd()}.

@ref{1ce0,,Availability}: Linux >= 2.6.27


Ajouté dans la version 3.10.

@end deffn

@geindex eventfd_write() (dans le module os)
@anchor{library/os os eventfd_write}@anchor{2b38}
@deffn {Fonction} os.eventfd_write (fd, value)

Add value to an @ref{802,,eventfd()} file descriptor. `value' must be a 64 bit
unsigned int. The function does not verify that `fd' is an @ref{802,,eventfd()}.

@ref{1ce0,,Availability}: Linux >= 2.6.27


Ajouté dans la version 3.10.

@end deffn

@geindex EFD_CLOEXEC (dans le module os)
@anchor{library/os os EFD_CLOEXEC}@anchor{175c}
@deffn {Données} os.EFD_CLOEXEC

Set close-on-exec flag for new @ref{802,,eventfd()} file descriptor.

@ref{1ce0,,Availability}: Linux >= 2.6.27


Ajouté dans la version 3.10.

@end deffn

@geindex EFD_NONBLOCK (dans le module os)
@anchor{library/os os EFD_NONBLOCK}@anchor{175d}
@deffn {Données} os.EFD_NONBLOCK

Set @ref{e28,,O_NONBLOCK} status flag for new @ref{802,,eventfd()} file
descriptor.

@ref{1ce0,,Availability}: Linux >= 2.6.27


Ajouté dans la version 3.10.

@end deffn

@geindex EFD_SEMAPHORE (dans le module os)
@anchor{library/os os EFD_SEMAPHORE}@anchor{175e}
@deffn {Données} os.EFD_SEMAPHORE

Provide semaphore-like semantics for reads from an @ref{802,,eventfd()} file
descriptor. On read the internal counter is decremented by one.

@ref{1ce0,,Availability}: Linux >= 2.6.30


Ajouté dans la version 3.10.

@end deffn

@menu
* Timer File Descriptors:: 
* Attributs étendus pour Linux:: 

@end menu

@node Timer File Descriptors,Attributs étendus pour Linux,,Fichiers et répertoires
@anchor{library/os os-timerfd}@anchor{152}@anchor{library/os timer-file-descriptors}@anchor{2b39}
@subsubsection Timer File Descriptors



Ajouté dans la version 3.13.


These functions provide support for Linux's `timer file descriptor' API.
Naturally, they are all only available on Linux.

@geindex timerfd_create() (dans le module os)
@anchor{library/os os timerfd_create}@anchor{20e}
@deffn {Fonction} os.timerfd_create (clockid, /, *, flags=0)

Create and return a timer file descriptor (`timerfd').

The file descriptor returned by @ref{20e,,timerfd_create()} supports:


@itemize -

@item 
@ref{d82,,read()}

@item 
@ref{d8d,,select()}

@item 
@ref{2b36,,poll()}
@end itemize

The file descriptor's @ref{d82,,read()} method can be called with a buffer size
of 8. If the timer has already expired one or more times, @ref{d82,,read()}
returns the number of expirations with the host's endianness, which may be
converted to an @ref{254,,int} by @code{int.from_bytes(x, byteorder=sys.byteorder)}.

@ref{d8d,,select()} and @ref{2b36,,poll()} can be used to wait until
timer expires and the file descriptor is readable.

`clockid' must be a valid @ref{2b3a,,clock ID},
as defined in the @ref{ed,,time} module:


@itemize -

@item 
@ref{685,,time.CLOCK_REALTIME}

@item 
@ref{684,,time.CLOCK_MONOTONIC}

@item 
@ref{b7c,,time.CLOCK_BOOTTIME} (Since Linux 3.15 for timerfd_create)
@end itemize

If `clockid' is @ref{685,,time.CLOCK_REALTIME}, a settable system-wide
real-time clock is used. If system clock is changed, timer setting need
to be updated. To cancel timer when system clock is changed, see
@ref{216,,TFD_TIMER_CANCEL_ON_SET}.

If `clockid' is @ref{684,,time.CLOCK_MONOTONIC}, a non-settable monotonically
increasing clock is used. Even if the system clock is changed, the timer
setting will not be affected.

If `clockid' is @ref{b7c,,time.CLOCK_BOOTTIME}, same as @ref{684,,time.CLOCK_MONOTONIC}
except it includes any time that the system is suspended.

The file descriptor's behaviour can be modified by specifying a `flags' value.
Any of the following variables may used, combined using bitwise OR
(the @code{|} operator):


@itemize -

@item 
@ref{213,,TFD_NONBLOCK}

@item 
@ref{214,,TFD_CLOEXEC}
@end itemize

If @ref{213,,TFD_NONBLOCK} is not set as a flag, @ref{d82,,read()} blocks until
the timer expires. If it is set as a flag, @ref{d82,,read()} doesn't block, but
If there hasn't been an expiration since the last call to read,
@ref{d82,,read()} raises @ref{40d,,OSError} with @code{errno} is set to
@ref{2225,,errno.EAGAIN}.

@ref{214,,TFD_CLOEXEC} is always set by Python automatically.

The file descriptor must be closed with @ref{b62,,os.close()} when it is no
longer needed, or else the file descriptor will be leaked.


@subsubheading Voir aussi


The @code{timerfd_create(2)@footnote{https://manpages.debian.org/timerfd_create(2)}} man page.


@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex timerfd_settime() (dans le module os)
@anchor{library/os os timerfd_settime}@anchor{20f}
@deffn {Fonction} os.timerfd_settime (fd, /, *, flags=flags, initial=0.0, interval=0.0)

Alter a timer file descriptor's internal timer.
This function operates the same interval timer as @ref{210,,timerfd_settime_ns()}.

`fd' must be a valid timer file descriptor.

The timer's behaviour can be modified by specifying a `flags' value.
Any of the following variables may used, combined using bitwise OR
(the @code{|} operator):


@itemize -

@item 
@ref{215,,TFD_TIMER_ABSTIME}

@item 
@ref{216,,TFD_TIMER_CANCEL_ON_SET}
@end itemize

The timer is disabled by setting `initial' to zero (@code{0}).
If `initial' is equal to or greater than zero, the timer is enabled.
If `initial' is less than zero, it raises an @ref{40d,,OSError} exception
with @code{errno} set to @ref{197d,,errno.EINVAL}

By default the timer will fire when `initial' seconds have elapsed.
(If `initial' is zero, timer will fire immediately.)

However, if the @ref{215,,TFD_TIMER_ABSTIME} flag is set,
the timer will fire when the timer's clock
(set by `clockid' in @ref{20e,,timerfd_create()}) reaches `initial' seconds.

The timer's interval is set by the `interval' @ref{2eb,,float}.
If `interval' is zero, the timer only fires once, on the initial expiration.
If `interval' is greater than zero, the timer fires every time `interval'
seconds have elapsed since the previous expiration.
If `interval' is less than zero, it raises @ref{40d,,OSError} with @code{errno}
set to @ref{197d,,errno.EINVAL}

If the @ref{216,,TFD_TIMER_CANCEL_ON_SET} flag is set along with
@ref{215,,TFD_TIMER_ABSTIME} and the clock for this timer is
@ref{685,,time.CLOCK_REALTIME}, the timer is marked as cancelable if the
real-time clock is changed discontinuously. Reading the descriptor is
aborted with the error ECANCELED.

Linux manages system clock as UTC. A daylight-savings time transition is
done by changing time offset only and doesn't cause discontinuous system
clock change.

Discontinuous system clock change will be caused by the following events:


@itemize -

@item 
@code{settimeofday}

@item 
@code{clock_settime}

@item 
set the system date and time by @code{date} command
@end itemize

Return a two-item tuple of (@code{next_expiration}, @code{interval}) from
the previous timer state, before this function executed.


@subsubheading Voir aussi


@code{timerfd_create(2)@footnote{https://manpages.debian.org/timerfd_create(2)}}, @code{timerfd_settime(2)@footnote{https://manpages.debian.org/timerfd_settime(2)}},
@code{settimeofday(2)@footnote{https://manpages.debian.org/settimeofday(2)}}, @code{clock_settime(2)@footnote{https://manpages.debian.org/clock_settime(2)}},
and @code{date(1)@footnote{https://manpages.debian.org/date(1)}}.


@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex timerfd_settime_ns() (dans le module os)
@anchor{library/os os timerfd_settime_ns}@anchor{210}
@deffn {Fonction} os.timerfd_settime_ns (fd, /, *, flags=0, initial=0, interval=0)

Similar to @ref{20f,,timerfd_settime()}, but use time as nanoseconds.
This function operates the same interval timer as @ref{20f,,timerfd_settime()}.

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex timerfd_gettime() (dans le module os)
@anchor{library/os os timerfd_gettime}@anchor{211}
@deffn {Fonction} os.timerfd_gettime (fd, /)

Return a two-item tuple of floats (@code{next_expiration}, @code{interval}).

@code{next_expiration} denotes the relative time until next the timer next fires,
regardless of if the @ref{215,,TFD_TIMER_ABSTIME} flag is set.

@code{interval} denotes the timer's interval.
If zero, the timer will only fire once, after @code{next_expiration} seconds
have elapsed.


@subsubheading Voir aussi


@code{timerfd_gettime(2)@footnote{https://manpages.debian.org/timerfd_gettime(2)}}


@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex timerfd_gettime_ns() (dans le module os)
@anchor{library/os os timerfd_gettime_ns}@anchor{212}
@deffn {Fonction} os.timerfd_gettime_ns (fd, /)

Similar to @ref{211,,timerfd_gettime()}, but return time as nanoseconds.

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex TFD_NONBLOCK (dans le module os)
@anchor{library/os os TFD_NONBLOCK}@anchor{213}
@deffn {Données} os.TFD_NONBLOCK

A flag for the @ref{20e,,timerfd_create()} function,
which sets the @ref{e28,,O_NONBLOCK} status flag for the new timer file
descriptor. If @ref{213,,TFD_NONBLOCK} is not set as a flag, @ref{d82,,read()} blocks.

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex TFD_CLOEXEC (dans le module os)
@anchor{library/os os TFD_CLOEXEC}@anchor{214}
@deffn {Données} os.TFD_CLOEXEC

A flag for the @ref{20e,,timerfd_create()} function,
If @ref{214,,TFD_CLOEXEC} is set as a flag, set close-on-exec flag for new file
descriptor.

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex TFD_TIMER_ABSTIME (dans le module os)
@anchor{library/os os TFD_TIMER_ABSTIME}@anchor{215}
@deffn {Données} os.TFD_TIMER_ABSTIME

A flag for the @ref{20f,,timerfd_settime()} and @ref{210,,timerfd_settime_ns()} functions.
If this flag is set, `initial' is interpreted as an absolute value on the
timer's clock (in UTC seconds or nanoseconds since the Unix Epoch).

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@geindex TFD_TIMER_CANCEL_ON_SET (dans le module os)
@anchor{library/os os TFD_TIMER_CANCEL_ON_SET}@anchor{216}
@deffn {Données} os.TFD_TIMER_CANCEL_ON_SET

A flag for the @ref{20f,,timerfd_settime()} and @ref{210,,timerfd_settime_ns()}
functions along with @ref{215,,TFD_TIMER_ABSTIME}.
The timer is cancelled when the time of the underlying clock changes
discontinuously.

@ref{1ce0,,Availability}: Linux >= 2.6.27 with glibc >= 2.8


Ajouté dans la version 3.13.

@end deffn

@node Attributs étendus pour Linux,,Timer File Descriptors,Fichiers et répertoires
@anchor{library/os linux-extended-attributes}@anchor{2b3b}
@subsubsection Attributs étendus pour Linux



Ajouté dans la version 3.3.


Toutes ces fonctions ne sont disponibles que sur Linux.

@geindex getxattr() (dans le module os)
@anchor{library/os os getxattr}@anchor{10e4}
@deffn {Fonction} os.getxattr (path, attribute, *, follow_symlinks=True)

Renvoie la valeur de l'attribut étendu `attribute' du système de fichiers pour le chemin `path'. `attribute' peut être une chaîne de caractères ou d'octets (directement ou indirectement à travers une interface @ref{c3f,,PathLike}). Si c'est une chaîne de caractères, elle est encodée avec l'encodage du système de fichiers.

Cette fonction peut supporter la @ref{b4a,,spécification d'un descripteur de fichier} et @ref{10cc,,le non-suivi des liens symboliques}.

Lève un @ref{1848,,événement d'audit} @code{os.getxattr} avec les arguments @code{path}, @code{attribute}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `path' et `attribute'.

@end deffn

@geindex listxattr() (dans le module os)
@anchor{library/os os listxattr}@anchor{10e5}
@deffn {Fonction} os.listxattr (path=None, *, follow_symlinks=True)

Renvoie une liste d'attributs du système de fichiers étendu pour `path'. Les attributs dans le liste sont représentés par des chaînes de caractères et sont décodés avec l'encodage du système de fichier. Si `path' vaut @code{None}, @ref{10e5,,listxattr()} examinera le répertoire actuel.

Cette fonction peut supporter la @ref{b4a,,spécification d'un descripteur de fichier} et @ref{10cc,,le non-suivi des liens symboliques}.

Lève un @ref{1848,,événement d'audit} @code{os.listxattr} avec l'argument @code{path}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex removexattr() (dans le module os)
@anchor{library/os os removexattr}@anchor{10e6}
@deffn {Fonction} os.removexattr (path, attribute, *, follow_symlinks=True)

Removes the extended filesystem attribute `attribute' from `path'.
`attribute' should be bytes or str (directly or indirectly through the
@ref{c3f,,PathLike} interface). If it is a string, it is encoded
with the @ref{525,,filesystem encoding and error handler}.

Cette fonction peut supporter la @ref{b4a,,spécification d'un descripteur de fichier} et @ref{10cc,,le non-suivi des liens symboliques}.

Lève un @ref{1848,,événement d'audit} @code{os.removexattr} avec les arguments @code{path}, @code{attribute}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `path' et `attribute'.

@end deffn

@geindex setxattr() (dans le module os)
@anchor{library/os os setxattr}@anchor{10e7}
@deffn {Fonction} os.setxattr (path, attribute, value, flags=0, *, follow_symlinks=True)

Set the extended filesystem attribute `attribute' on `path' to `value'.
`attribute' must be a bytes or str with no embedded NULs (directly or
indirectly through the @ref{c3f,,PathLike} interface). If it is a str,
it is encoded with the @ref{525,,filesystem encoding and error handler}.  `flags' may be
@ref{2b3c,,XATTR_REPLACE} or @ref{2b3d,,XATTR_CREATE}. If @ref{2b3c,,XATTR_REPLACE} is
given and the attribute does not exist, @code{ENODATA} will be raised.
If @ref{2b3d,,XATTR_CREATE} is given and the attribute already exists, the
attribute will not be created and @code{EEXISTS} will be raised.

Cette fonction peut supporter la @ref{b4a,,spécification d'un descripteur de fichier} et @ref{10cc,,le non-suivi des liens symboliques}.

@cartouche
@quotation Note 
Un bogue des versions inférieures à 2.6.39 du noyau Linux faisait que les marqueurs de `flags'  étaient ignorés sur certains systèmes.
@end quotation
@end cartouche

Lève un @ref{1848,,événement d'audit} @code{os.setxattr} avec les arguments @code{path}, @code{attribute}, @code{value}, @code{flags}.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object} pour `path' et `attribute'.

@end deffn

@geindex XATTR_SIZE_MAX (dans le module os)
@anchor{library/os os XATTR_SIZE_MAX}@anchor{2b3e}
@deffn {Données} os.XATTR_SIZE_MAX

La taille maximum que peut faire la valeur d'un attribut étendu. Actuellement, c'est 64 KiB sur Lniux.
@end deffn

@geindex XATTR_CREATE (dans le module os)
@anchor{library/os os XATTR_CREATE}@anchor{2b3d}
@deffn {Données} os.XATTR_CREATE

C'est une valeur possible pour l'argument `flags' de @ref{10e7,,setxattr()}. Elle indique que l'opération doit créer un attribut.
@end deffn

@geindex XATTR_REPLACE (dans le module os)
@anchor{library/os os XATTR_REPLACE}@anchor{2b3c}
@deffn {Données} os.XATTR_REPLACE

C'est une valeur possible pour l'argument `flags' de @ref{10e7,,setxattr()}.Elle indique que l'opération doit remplacer un attribut existant.
@end deffn

@node Gestion des processus,Interface pour l'ordonnanceur,Fichiers et répertoires,os --- Miscellaneous operating system interfaces
@anchor{library/os os-process}@anchor{2b3f}@anchor{library/os process-management}@anchor{2b40}
@subsubsection Gestion des processus


Ces fonctions peuvent être utilisées pour créer et gérer des processus.

Les variantes des fonctions @ref{2b41,,exec*} prennent une liste d'arguments pour le nouveau programme chargé dans le processus. Dans tous les cas, le premier de ces arguments est passé au nouveau programme comme son propre nom plutôt que comme un argument qu'un utilisateur peut avoir tapé en ligne de commande. Pour les développeurs C, c'est l'argument @code{argv[0]} qui est passé à la fonction @code{main()} du programme. Par exemple, @code{os.execv('/bin/echo/', ['foo', 'bar'])} affichera uniquement @code{bar} sur la sortie standard ; @code{foo} semblera être ignoré.

@geindex abort() (dans le module os)
@anchor{library/os os abort}@anchor{2b42}
@deffn {Fonction} os.abort ()

Génère un signal @code{SIGABRT} au processus actuel. Sur Linux, le comportement par défaut est de produire un vidage système (`Core Dump') ; sur Windows, le processus renvoie immédiatement un code d'erreur @code{3}. Attention : appeler cette fonction n'appellera pas le gestionnaire de signal Python enregistré par @code{SIGABRT} à l'aide de @ref{1114,,signal.signal()}.
@end deffn

@geindex add_dll_directory() (dans le module os)
@anchor{library/os os add_dll_directory}@anchor{9d8}
@deffn {Fonction} os.add_dll_directory (path)

Ajoute un chemin aux chemins de recherche de DLL.

This search path is used when resolving dependencies for imported
extension modules (the module itself is resolved through
@ref{3ab,,sys.path}), and also by @ref{2a,,ctypes}.

Remove the directory by calling `close()' on the returned object
or using it in a @ref{5bc,,with} statement.

See the Microsoft documentation@footnote{https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5}
for more information about how DLLs are loaded.

Lève un @ref{1848,,événement d'audit} @code{os.add_dll_directory} avec l'argument @code{path}.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.8: Previous versions of CPython would resolve DLLs using the default
behavior for the current process. This led to inconsistencies,
such as only sometimes searching 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} or the current
working directory, and OS functions such as @code{AddDllDirectory}
having no effect.

In 3.8, the two primary ways DLLs are loaded now explicitly
override the process-wide behavior to ensure consistency. See the
@ref{a8c,,porting notes} for information on
updating libraries.

@end deffn

@geindex execl() (dans le module os)
@geindex execle() (dans le module os)
@geindex execlp() (dans le module os)
@geindex execlpe() (dans le module os)
@geindex execv() (dans le module os)
@geindex execve() (dans le module os)
@geindex execvp() (dans le module os)
@geindex execvpe() (dans le module os)
@anchor{library/os os execl}@anchor{2b41}
@deffn {Fonction} os.execl (path, arg0, arg1, ...)
@anchor{library/os os execle}@anchor{2b43}
@deffnx {Fonction} os.execle (path, arg0, arg1, ..., env)
@anchor{library/os os execlp}@anchor{2b44}
@deffnx {Fonction} os.execlp (file, arg0, arg1, ...)
@anchor{library/os os execlpe}@anchor{2b45}
@deffnx {Fonction} os.execlpe (file, arg0, arg1, ..., env)
@anchor{library/os os execv}@anchor{2aa1}
@deffnx {Fonction} os.execv (path, args)
@anchor{library/os os execve}@anchor{10d9}
@deffnx {Fonction} os.execve (path, args, env)
@anchor{library/os os execvp}@anchor{2b46}
@deffnx {Fonction} os.execvp (file, args)
@anchor{library/os os execvpe}@anchor{2b47}
@deffnx {Fonction} os.execvpe (file, args, env)

Ces fonctions exécutent toutes un nouveau programme, remplaçant le processus actuel, elles ne renvoient pas. Sur Unix, le nouvel exécutable est chargé dans le processus actuel, et aura le même identifiant de processus (PID) que l'appelant. Les erreurs seront reportées par des exceptions @ref{40d,,OSError}.

Le processus actuel est remplacé immédiatement. Les fichiers objets et descripteurs de fichiers ne sont pas purgés, donc s'il est possible que des données aient été mises en tampon pour ces fichiers, vous devriez les purger manuellement en utilisant @code{sys.stdout.flush()} ou @ref{d7b,,os.fsync()} avant d'appeler une fonction @ref{2b41,,exec*}.

The "l" and "v" variants of the @ref{2b41,,exec*} functions differ in how
command-line arguments are passed.  The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the @code{execl*()}
functions.  The "v" variants are good when the number of parameters is
variable, with the arguments being passed in a list or tuple as the `args'
parameter.  In either case, the arguments to the child process should start with
the name of the command being run, but this is not enforced.

The variants which include a "p" near the end (@ref{2b44,,execlp()},
@ref{2b45,,execlpe()}, @ref{2b46,,execvp()}, and @ref{2b47,,execvpe()}) will use the
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment variable to locate the program `file'.  When the
environment is being replaced (using one of the @ref{2b41,,exec*e} variants,
discussed in the next paragraph), the new environment is used as the source of
the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} variable. The other variants, @ref{2b41,,execl()}, @ref{2b43,,execle()},
@ref{2aa1,,execv()}, and @ref{10d9,,execve()}, will not use the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} variable to
locate the executable; `path' must contain an appropriate absolute or relative
path. Relative paths must include at least one slash, even on Windows, as
plain names will not be resolved.

Pour les fonctions @ref{2b43,,execle()}, @ref{2b45,,execlpe()}, @ref{10d9,,execve()}, et @ref{2b47,,execvpe()} (notez qu'elle finissent toutes par « e »), le paramètre `env' doit être un `mapping' qui est utilisé pour définir les variables d'environnement du nouveau processus (celles-ci sont utilisées à la place de l'environnement du nouveau processus). Les fonctions @ref{2b41,,execl()}, @ref{2b44,,execlp()}, @ref{2aa1,,execv()}, et @ref{2b46,,execvp()} causent toutes un héritage de l'environnement du processus actuel par le processus fils.

Pour @ref{10d9,,execve()}, sur certaines plate-formes, `path' peut également être spécifié par un descripteur de fichier ouvert. Cette fonctionnalité peut ne pas être gérée sur votre plate-forme. Vous pouvez vérifier si c'est disponible en utilisant @code{os._supports_fd}. Si c'est indisponible, l'utiliser lèvera une @ref{225,,NotImplementedError}.

Lève un @ref{1848,,événement d'audit} @code{os.exec} avec les arguments @code{path}, @code{args}, @code{env}.

@ref{1ce0,,Availability}: Unix, Windows, not WASI, not Android, not iOS.


Modifié dans la version 3.3: Added support for specifying `path' as an open file descriptor
for @ref{10d9,,execve()}.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex _exit() (dans le module os)
@anchor{library/os os _exit}@anchor{221f}
@deffn {Fonction} os._exit (n)

Quitte le processus avec le statut `n', sans appeler les gestionnaires de nettoyage, sans purger les tampons des fichiers, etc.

@cartouche
@quotation Note 
The standard way to exit is @ref{1327,,sys.exit(n)}.  @code{_exit()} should
normally only be used in the child process after a @ref{195,,fork()}.
@end quotation
@end cartouche
@end deffn

Les codes de sortie suivants sont définis et peuvent être utilisés avec @ref{221f,,_exit()}, mais ils ne sont pas nécessaires. Ils sont typiquement utilisés pour les programmes systèmes écrits en Python, comme un programme de gestion de l'exécution des commandes d'un serveur de mails.

@cartouche
@quotation Note 
Certaines de ces valeurs peuvent ne pas être disponibles sur toutes les plate-formes Unix étant donné qu'il en existe des variations. Ces constantes sont définies là où elles sont définies par la plate-forme sous-jacente.
@end quotation
@end cartouche

@geindex EX_OK (dans le module os)
@anchor{library/os os EX_OK}@anchor{2b48}
@deffn {Données} os.EX_OK

Exit code that means no error occurred. May be taken from the defined value of
@code{EXIT_SUCCESS} on some platforms. Generally has a value of zero.

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex EX_USAGE (dans le module os)
@anchor{library/os os EX_USAGE}@anchor{2b49}
@deffn {Données} os.EX_USAGE

Code de sortie signifiant que les commandes n'ont pas été utilisées correctement, comme quand le mauvais nombre d'arguments a été donné.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_DATAERR (dans le module os)
@anchor{library/os os EX_DATAERR}@anchor{2b4a}
@deffn {Données} os.EX_DATAERR

Code de sortie signifiant que les données en entrées étaient incorrectes.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_NOINPUT (dans le module os)
@anchor{library/os os EX_NOINPUT}@anchor{2b4b}
@deffn {Données} os.EX_NOINPUT

Code de sortie signifiant qu'un des fichiers d'entrée n'existe pas ou n'est pas lisible.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_NOUSER (dans le module os)
@anchor{library/os os EX_NOUSER}@anchor{2b4c}
@deffn {Données} os.EX_NOUSER

Code de sortie signifiant qu'un utilisateur spécifié n'existe pas.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_NOHOST (dans le module os)
@anchor{library/os os EX_NOHOST}@anchor{2b4d}
@deffn {Données} os.EX_NOHOST

Code de sortie signifiant qu'un hôte spécifié n'existe pas.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_UNAVAILABLE (dans le module os)
@anchor{library/os os EX_UNAVAILABLE}@anchor{2b4e}
@deffn {Données} os.EX_UNAVAILABLE

Code de sortie signifiant qu'un service requis n'est pas disponible.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_SOFTWARE (dans le module os)
@anchor{library/os os EX_SOFTWARE}@anchor{2b4f}
@deffn {Données} os.EX_SOFTWARE

Code de sortie signifiant qu'une erreur interne d'un programme a été détectée.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_OSERR (dans le module os)
@anchor{library/os os EX_OSERR}@anchor{2b50}
@deffn {Données} os.EX_OSERR

Code de sortie signifiant qu'une erreur du système d'exploitation a été détectée, comme l'incapacité à réaliser un `fork' ou à créer un tuyau (`pipe').

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_OSFILE (dans le module os)
@anchor{library/os os EX_OSFILE}@anchor{2b51}
@deffn {Données} os.EX_OSFILE

Code de sortie signifiant qu'un fichier n'existe pas, n'a pas pu être ouvert, ou avait une autre erreur.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_CANTCREAT (dans le module os)
@anchor{library/os os EX_CANTCREAT}@anchor{2b52}
@deffn {Données} os.EX_CANTCREAT

Code de sortie signifiant qu'un fichier spécifié par l'utilisateur n'a pas pu être créé.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_IOERR (dans le module os)
@anchor{library/os os EX_IOERR}@anchor{2b53}
@deffn {Données} os.EX_IOERR

Code de sortie signifiant qu'une erreur est apparue pendant une E/S sur un fichier.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_TEMPFAIL (dans le module os)
@anchor{library/os os EX_TEMPFAIL}@anchor{2b54}
@deffn {Données} os.EX_TEMPFAIL

Code de sortie signifiant qu'un échec temporaire est apparu. Cela indique quelque chose qui pourrait ne pas être une erreur, comme une connexion au réseau qui n'a pas pu être établie pendant une opération réessayable.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_PROTOCOL (dans le module os)
@anchor{library/os os EX_PROTOCOL}@anchor{2b55}
@deffn {Données} os.EX_PROTOCOL

Code de sortie signifiant qu'un protocole d'échange est illégal, invalide, ou non-compris.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_NOPERM (dans le module os)
@anchor{library/os os EX_NOPERM}@anchor{2b56}
@deffn {Données} os.EX_NOPERM

Code de sortie signifiant qu'il manque certaines permissions pour réaliser une opération (mais n'est pas destiné au problèmes de système de fichiers).

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_CONFIG (dans le module os)
@anchor{library/os os EX_CONFIG}@anchor{2b57}
@deffn {Données} os.EX_CONFIG

Code de sortie signifiant qu'une erreur de configuration est apparue.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex EX_NOTFOUND (dans le module os)
@anchor{library/os os EX_NOTFOUND}@anchor{2b58}
@deffn {Données} os.EX_NOTFOUND

Code de sortie signifiant quelque chose comme « une entrée n'a pas été trouvée ».

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex fork() (dans le module os)
@anchor{library/os os fork}@anchor{195}
@deffn {Fonction} os.fork ()

`Fork' un processus fils. Renvoie @code{0} dans le processus fils et le PID du processus fils dans le processus père. Si une erreur apparaît, une @ref{40d,,OSError} est levée.

Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using @code{fork()} from a thread.

Lève un @ref{1848,,évènement d'audit} @code{sys.fork} sans argument.

@cartouche
@quotation Avertissement 
If you use TLS sockets in an application calling @code{fork()}, see
the warning in the @ref{cf,,ssl} documentation.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{10a,,urllib.request}.
@end quotation
@end cartouche


Modifié dans la version 3.8: Calling @code{fork()} in a subinterpreter is no longer supported
(@ref{193,,RuntimeError} is raised).



Modifié dans la version 3.12: If Python is able to detect that your process has multiple
threads, @ref{195,,os.fork()} now raises a @ref{1a3,,DeprecationWarning}.

We chose to surface this as a warning, when detectable, to better
inform developers of a design problem that the POSIX platform
specifically notes as not supported. Even in code that
`appears' to work, it has never been safe to mix threading with
@ref{195,,os.fork()} on POSIX platforms. The CPython runtime itself has
always made API calls that are not safe for use in the child
process when threads existed in the parent (such as @code{malloc} and
@code{free}).

Users of macOS or users of libc or malloc implementations other
than those typically found in glibc to date are among those
already more likely to experience deadlocks running such code.

See this discussion on fork being incompatible with threads@footnote{https://discuss.python.org/t/33555}
for technical details of why we're surfacing this longstanding
platform compatibility problem to developers.


@ref{1ce0,,Availability}: POSIX, not WASI, not Android, not iOS.
@end deffn

@geindex forkpty() (dans le module os)
@anchor{library/os os forkpty}@anchor{196}
@deffn {Fonction} os.forkpty ()

`Fork' un processus fils, en utilisant un nouveau pseudo-terminal comme terminal contrôlant le fils. Renvoie une paire @code{(pid, fd)} où `pid' vaut @code{0} dans le fils et le PID du processus fils dans le parent, et `fd' est le descripteur de fichier de la partie maître du pseudo-terminal. Pour une approche plus portable, utilisez le module @ref{b0,,pty}. Si une erreur apparaît, une @ref{40d,,OSError} est levée.

Lève un @ref{1848,,évènement d'audit} @code{sys.forkpty} sans argument.

@cartouche
@quotation Avertissement 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{10a,,urllib.request}.
@end quotation
@end cartouche


Modifié dans la version 3.8: Calling @code{forkpty()} in a subinterpreter is no longer supported
(@ref{193,,RuntimeError} is raised).



Modifié dans la version 3.12: If Python is able to detect that your process has multiple
threads, this now raises a @ref{1a3,,DeprecationWarning}. See the
longer explanation on @ref{195,,os.fork()}.


@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex kill() (dans le module os)
@anchor{library/os os kill}@anchor{133e}
@deffn {Fonction} os.kill (pid, sig, /)

@geindex process;killing
@geindex process;signalling

Envoie le signal `sig' au processus `pid'. Les constantes pour les signaux spécifiques à la plate-forme hôte sont définies dans le module @ref{c5,,signal}.

Windows: The @ref{133f,,signal.CTRL_C_EVENT} and
@ref{1340,,signal.CTRL_BREAK_EVENT} signals are special signals which can
only be sent to console processes which share a common console window,
e.g., some subprocesses. Any other value for `sig' will cause the process
to be unconditionally killed by the TerminateProcess API, and the exit code
will be set to `sig'.

Voir également @ref{1111,,signal.pthread_kill()}.

Lève un @ref{1848,,événement d'audit} @code{os.kill} avec les arguments @code{pid}, @code{sig}.

@ref{1ce0,,Availability}: Unix, Windows, not WASI, not iOS.


Modifié dans la version 3.2: Prise en charge de Windows.

@end deffn

@geindex killpg() (dans le module os)
@anchor{library/os os killpg}@anchor{1964}
@deffn {Fonction} os.killpg (pgid, sig, /)

@geindex process;killing
@geindex process;signalling

Envoie le signal `sig' au groupe de processus `pgid'.

Lève un @ref{1848,,événement d'audit} @code{os.killpg} avec les arguments @code{pgid}, @code{sig}.

@ref{1ce0,,Availability}: Unix, not WASI, not iOS.
@end deffn

@geindex nice() (dans le module os)
@anchor{library/os os nice}@anchor{10e1}
@deffn {Fonction} os.nice (increment, /)

Ajoute `increment'  à la priorité du processus. Renvoie la nouvelle priorité.

@ref{1ce0,,Availability}: Unix, not WASI.
@end deffn

@geindex pidfd_open() (dans le module os)
@anchor{library/os os pidfd_open}@anchor{464}
@deffn {Fonction} os.pidfd_open (pid, flags=0)

Return a file descriptor referring to the process `pid' with `flags' set.
This descriptor can be used to perform process management without races
and signals.

See the @code{pidfd_open(2)@footnote{https://manpages.debian.org/pidfd_open(2)}} man page for more details.

@ref{1ce0,,Availability}: Linux >= 5.3, Android >= @ref{b78,,build-time} API level 31


Ajouté dans la version 3.9.


@geindex PIDFD_NONBLOCK (dans le module os)
@anchor{library/os os PIDFD_NONBLOCK}@anchor{484}
@deffn {Données} os.PIDFD_NONBLOCK

This flag indicates that the file descriptor will be non-blocking.
If the process referred to by the file descriptor has not yet terminated,
then an attempt to wait on the file descriptor using @code{waitid(2)@footnote{https://manpages.debian.org/waitid(2)}}
will immediately return the error @ref{2225,,EAGAIN} rather than blocking.
@end deffn

@ref{1ce0,,Availability}: Linux >= 5.10


Ajouté dans la version 3.12.

@end deffn

@geindex plock() (dans le module os)
@anchor{library/os os plock}@anchor{2b59}
@deffn {Fonction} os.plock (op, /)

Verrouille les segments du programme en mémoire. La valeur de `op' (définie dans @code{<sys/lock.h>}) détermine quels segments sont verrouillés.

@ref{1ce0,,Availability}: Unix, not WASI, not iOS.
@end deffn

@geindex popen() (dans le module os)
@anchor{library/os os popen}@anchor{a75}
@deffn {Fonction} os.popen (cmd, mode='r', buffering=-1)

Open a pipe to or from command `cmd'.
The return value is an open file object
connected to the pipe, which can be read or written depending on whether `mode'
is @code{'r'} (default) or @code{'w'}.
The `buffering' argument have the same meaning as
the corresponding argument to the built-in @ref{505,,open()} function. The
returned file object reads or writes text strings rather than bytes.

La méthode @code{close} renvoie @ref{660,,None} si le sous-processus s'est terminé avec succès, ou le code de retour du sous-processus s'il y a eu une erreur. Sur les systèmes POSIX, si le code de retour est positif, il représente la valeur de retour du processus décalée d'un byte sur la gauche. Si le code de retour est négatif, le processus le processus s'est terminé avec le signal donné par la négation de la valeur de retour. (Par exemple, la valeur de retour pourrait être @code{-signal.SIGKILL} si le sous-processus a été tué). Sur les systèmes Windows, la valeur de retour contient le code de retour du processus fils dans un entier signé .

On Unix, @ref{90a,,waitstatus_to_exitcode()} can be used to convert the @code{close}
method result (exit status) into an exit code if it is not @code{None}. On
Windows, the @code{close} method result is directly the exit code
(or @code{None}).

Ceci est implémenté en utilisant @ref{197,,subprocess.Popen}. Lisez la documentation de cette classe pour des méthodes plus puissantes pour gérer et communiquer avec des sous-processus.

@ref{1ce0,,Availability}: not WASI, not Android, not iOS.

@cartouche
@quotation Note 
The @ref{641,,Python UTF-8 Mode} affects encodings used
for `cmd' and pipe contents.

@ref{a75,,popen()} is a simple wrapper around @ref{197,,subprocess.Popen}.
Use @ref{197,,subprocess.Popen} or @ref{b74,,subprocess.run()} to
control options like encodings.
@end quotation
@end cartouche
@end deffn

@geindex posix_spawn() (dans le module os)
@anchor{library/os os posix_spawn}@anchor{21d}
@deffn {Fonction} os.posix_spawn (path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Wraps the @code{posix_spawn()} C library API for use from Python.

Most users should use @ref{b74,,subprocess.run()} instead of @ref{21d,,posix_spawn()}.

The positional-only arguments `path', `args', and `env' are similar to
@ref{10d9,,execve()}. `env' is allowed to be @code{None}, in which case current
process' environment is used.

The `path' parameter is the path to the executable file.  The `path' should
contain a directory.  Use @ref{19bd,,posix_spawnp()} to pass an executable file
without directory.

The `file_actions' argument may be a sequence of tuples describing actions
to take on specific file descriptors in the child process between the C
library implementation's @code{fork()} and @code{exec()} steps.
The first item in each tuple must be one of the three type indicator
listed below describing the remaining tuple elements:

@geindex POSIX_SPAWN_OPEN (dans le module os)
@anchor{library/os os POSIX_SPAWN_OPEN}@anchor{2b5a}
@deffn {Données} os.POSIX_SPAWN_OPEN

(@code{os.POSIX_SPAWN_OPEN}, `fd', `path', `flags', `mode')

Performs @code{os.dup2(os.open(path, flags, mode), fd)}.
@end deffn

@geindex POSIX_SPAWN_CLOSE (dans le module os)
@anchor{library/os os POSIX_SPAWN_CLOSE}@anchor{2b5b}
@deffn {Données} os.POSIX_SPAWN_CLOSE

(@code{os.POSIX_SPAWN_CLOSE}, `fd')

Performs @code{os.close(fd)}.
@end deffn

@geindex POSIX_SPAWN_DUP2 (dans le module os)
@anchor{library/os os POSIX_SPAWN_DUP2}@anchor{2b5c}
@deffn {Données} os.POSIX_SPAWN_DUP2

(@code{os.POSIX_SPAWN_DUP2}, `fd', `new_fd')

Performs @code{os.dup2(fd, new_fd)}.
@end deffn

@geindex POSIX_SPAWN_CLOSEFROM (dans le module os)
@anchor{library/os os POSIX_SPAWN_CLOSEFROM}@anchor{21e}
@deffn {Données} os.POSIX_SPAWN_CLOSEFROM

(@code{os.POSIX_SPAWN_CLOSEFROM}, `fd')

Performs @code{os.closerange(fd, INF)}.
@end deffn

These tuples correspond to the C library
@code{posix_spawn_file_actions_addopen()},
@code{posix_spawn_file_actions_addclose()},
@code{posix_spawn_file_actions_adddup2()}, and
@code{posix_spawn_file_actions_addclosefrom_np()} API calls used to prepare
for the @code{posix_spawn()} call itself.

The `setpgroup' argument will set the process group of the child to the value
specified. If the value specified is 0, the child's process group ID will be
made the same as its process ID. If the value of `setpgroup' is not set, the
child will inherit the parent's process group ID. This argument corresponds
to the C library @code{POSIX_SPAWN_SETPGROUP} flag.

If the `resetids' argument is @code{True} it will reset the effective UID and
GID of the child to the real UID and GID of the parent process. If the
argument is @code{False}, then the child retains the effective UID and GID of
the parent. In either case, if the set-user-ID and set-group-ID permission
bits are enabled on the executable file, their effect will override the
setting of the effective UID and GID. This argument corresponds to the C
library @code{POSIX_SPAWN_RESETIDS} flag.

If the `setsid' argument is @code{True}, it will create a new session ID
for @code{posix_spawn}. `setsid' requires @code{POSIX_SPAWN_SETSID}
or @code{POSIX_SPAWN_SETSID_NP} flag. Otherwise, @ref{225,,NotImplementedError}
is raised.

The `setsigmask' argument will set the signal mask to the signal set
specified. If the parameter is not used, then the child inherits the
parent's signal mask. This argument corresponds to the C library
@code{POSIX_SPAWN_SETSIGMASK} flag.

The `sigdef' argument will reset the disposition of all signals in the set
specified. This argument corresponds to the C library
@code{POSIX_SPAWN_SETSIGDEF} flag.

The `scheduler' argument must be a tuple containing the (optional) scheduler
policy and an instance of @ref{1529,,sched_param} with the scheduler parameters.
A value of @code{None} in the place of the scheduler policy indicates that is
not being provided. This argument is a combination of the C library
@code{POSIX_SPAWN_SETSCHEDPARAM} and @code{POSIX_SPAWN_SETSCHEDULER}
flags.

Lève un @ref{1848,,événement d'audit} @code{os.posix_spawn} avec les arguments @code{path}, @code{argv}, @code{env}.


Ajouté dans la version 3.8.



Modifié dans la version 3.13: `env' parameter accepts @code{None}.
@code{os.POSIX_SPAWN_CLOSEFROM} is available on platforms where
@code{posix_spawn_file_actions_addclosefrom_np()} exists.


@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex posix_spawnp() (dans le module os)
@anchor{library/os os posix_spawnp}@anchor{19bd}
@deffn {Fonction} os.posix_spawnp (path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Wraps the @code{posix_spawnp()} C library API for use from Python.

Similar to @ref{21d,,posix_spawn()} except that the system searches
for the `executable' file in the list of directories specified by the
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment variable (in the same way as for @code{execvp(3)}).

Lève un @ref{1848,,événement d'audit} @code{os.posix_spawn} avec les arguments @code{path}, @code{argv}, @code{env}.


Ajouté dans la version 3.8.


@ref{1ce0,,Availability}: POSIX, not WASI, not Android, not iOS.

See @ref{21d,,posix_spawn()} documentation.
@end deffn

@geindex register_at_fork() (dans le module os)
@anchor{library/os os register_at_fork}@anchor{2f4}
@deffn {Fonction} os.register_at_fork (*, before=None, after_in_parent=None, after_in_child=None)

Enregistre des appelables (`callables') à exécuter quand un nouveau processus enfant est crée avec @ref{195,,os.fork()} ou des APIs similaires de clonage de processus. Les paramètres sont optionnels et par mots-clé uniquement. Chacun spécifie un point d'appel différent.


@itemize *

@item 
`before' est une fonction appelée avant de `forker' un processus enfant.

@item 
`after_in_parent' est une fonction appelée depuis le processus parent après avoir `forké' un processus enfant.

@item 
`after_in_child' est une fonction appelée depuis le processus enfant.
@end itemize

Ces appels ne sont effectués que si le contrôle est censé retourner à l'interpréteur Python. Un lancement de @ref{d5,,subprocess} typique ne les déclenchera pas, car l'enfant ne ré-entre pas dans l'interpréteur.

Les fonctions enregistrées pour l'exécution avant le `fork' sont appelées dans l'ordre inverse à leur enregistrement. Les fonctions enregistrées pour l'exécution après le `fork' (soit dans le parent ou dans l'enfant) sont appelées dans l'ordre de leur enregistrement.

Notez que les appels à @code{fork()} faits par du code C de modules tiers peuvent ne pas appeler ces fonctions, à moins que ce code appelle explicitement @ref{bad,,PyOS_BeforeFork()}, @ref{bae,,PyOS_AfterFork_Parent()} et @ref{3f1,,PyOS_AfterFork_Child()}.

Il n'y a aucun moyen d'annuler l'enregistrement d'une fonction.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.


Ajouté dans la version 3.7.

@end deffn

@geindex spawnl() (dans le module os)
@geindex spawnle() (dans le module os)
@geindex spawnlp() (dans le module os)
@geindex spawnlpe() (dans le module os)
@geindex spawnv() (dans le module os)
@geindex spawnve() (dans le module os)
@geindex spawnvp() (dans le module os)
@geindex spawnvpe() (dans le module os)
@anchor{library/os os spawnl}@anchor{16bc}
@deffn {Fonction} os.spawnl (mode, path, ...)
@anchor{library/os os spawnle}@anchor{2b5d}
@deffnx {Fonction} os.spawnle (mode, path, ..., env)
@anchor{library/os os spawnlp}@anchor{2b5e}
@deffnx {Fonction} os.spawnlp (mode, file, ...)
@anchor{library/os os spawnlpe}@anchor{2b5f}
@deffnx {Fonction} os.spawnlpe (mode, file, ..., env)
@anchor{library/os os spawnv}@anchor{2b60}
@deffnx {Fonction} os.spawnv (mode, path, args)
@anchor{library/os os spawnve}@anchor{2b61}
@deffnx {Fonction} os.spawnve (mode, path, args, env)
@anchor{library/os os spawnvp}@anchor{2b62}
@deffnx {Fonction} os.spawnvp (mode, file, args)
@anchor{library/os os spawnvpe}@anchor{2b63}
@deffnx {Fonction} os.spawnvpe (mode, file, args, env)

Exécute le programme `path' dans un nouveau processus.

(Notez que le module @ref{d5,,subprocess} fournit des outils plus puissants pour générer de nouveaux processus et récupérer leur valeur de retour. Il est préférable d'utiliser ce module que ces fonctions. Voyez surtout la section @ref{1168,,Remplacer les fonctions plus anciennes par le module subprocess}.)

Si `mode' vaut @ref{2b64,,P_NOWAIT}, cette fonction renvoie le PID du nouveau processus, et si `mode' vaut @ref{2b65,,P_WAIT}, la fonction renvoie le code de sortie du processus s'il se termine normalement, ou @code{-signal} où `signal' est le signal qui a tué le processus. Sur Windows, le PID du processus sera en fait l'identificateur du processus (`process handle') et peut donc être utilisé avec la fonction @ref{d87,,waitpid()}.

Note on VxWorks, this function doesn't return @code{-signal} when the new process is
killed. Instead it raises OSError exception.

The "l" and "v" variants of the @ref{16bc,,spawn*} functions differ in how
command-line arguments are passed.  The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the
@code{spawnl*()} functions.  The "v" variants are good when the number of
parameters is variable, with the arguments being passed in a list or tuple as
the `args' parameter.  In either case, the arguments to the child process must
start with the name of the command being run.

Les variantes qui incluent un « p » vers la fin (@ref{2b5e,,spawnlp()}, @ref{2b5f,,spawnlpe()}, @ref{2b62,,spawnvp()}, et @ref{2b63,,spawnvpe()}) utiliseront la variable d'environnement 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} pour localiser le programme `file'. Quand l'environnement est remplacé (en utilisant une des variantes @ref{16bc,,spawn*e}, discutées dans le paragraphe suivant), le nouvel environnement est utilisé comme source de la variable d'environnement 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}. Les autres variantes @ref{16bc,,spawnl()}, @ref{2b5d,,spawnle()}, @ref{2b60,,spawnv()}, et @ref{2b61,,spawnve()} n'utiliseront pas la variable d'environnement 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} pour localiser l'exécutable. `path' doit contenir un chemin absolue ou relatif approprié.

Pour les fonctions @ref{2b5d,,spawnle()}, @ref{2b5f,,spawnlpe()}, @ref{2b61,,spawnve()}, et @ref{2b63,,spawnvpe()} (notez qu'elles finissent toutes par « e »), le paramètre `env' doit être un `mapping' qui est utilisé pour définir les variables d'environnement du nouveau processus (celles-ci sont utilisées à la place de l'environnement du nouveau processus). Les fonctions @ref{16bc,,spawnl()}, @ref{2b5e,,spawnlp()}, @ref{2b60,,spawnv()}, et @ref{2b62,,spawnvp()} causent toutes un héritage de l'environnement du processus actuel par le processus fils. Notez que les clefs et les valeurs du dictionnaire `env' doivent être des chaînes de caractères. Des valeurs invalides pour les clefs ou les valeurs met la fonction en échec et renvoie @code{127}.

Par exemple, les appels suivants à @ref{2b5e,,spawnlp()} et @ref{2b63,,spawnvpe()} sont équivalents :

@example
import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
@end example

Lève un @ref{1848,,événement d'audit} @code{os.spawn} avec les arguments @code{mode}, @code{path}, @code{args}, @code{env}.

@ref{1ce0,,Availability}: Unix, Windows, not WASI, not Android, not iOS.

@ref{2b5e,,spawnlp()}, @ref{2b5f,,spawnlpe()}, @ref{2b62,,spawnvp()}, et @ref{2b63,,spawnvpe()} ne sont pas disponibles sur Windows. @ref{2b5d,,spawnle()} et @ref{2b61,,spawnve()} ne sont pas sécurisés pour les appels concurrents (`thread-safe') sur Windows, il est conseillé d'utiliser le module @ref{d5,,subprocess} à la place.


Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex P_NOWAIT (dans le module os)
@geindex P_NOWAITO (dans le module os)
@anchor{library/os os P_NOWAIT}@anchor{2b64}
@deffn {Données} os.P_NOWAIT
@anchor{library/os os P_NOWAITO}@anchor{2b66}
@deffnx {Données} os.P_NOWAITO

Possible values for the `mode' parameter to the @ref{16bc,,spawn*} family of
functions.  If either of these values is given, the @ref{16bc,,spawn*} functions
will return as soon as the new process has been created, with the process id as
the return value.

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex P_WAIT (dans le module os)
@anchor{library/os os P_WAIT}@anchor{2b65}
@deffn {Données} os.P_WAIT

Possible value for the `mode' parameter to the @ref{16bc,,spawn*} family of
functions.  If this is given as `mode', the @ref{16bc,,spawn*} functions will not
return until the new process has run to completion and will return the exit code
of the process the run is successful, or @code{-signal} if a signal kills the
process.

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex P_DETACH (dans le module os)
@geindex P_OVERLAY (dans le module os)
@anchor{library/os os P_DETACH}@anchor{2b67}
@deffn {Données} os.P_DETACH
@anchor{library/os os P_OVERLAY}@anchor{2b68}
@deffnx {Données} os.P_OVERLAY

Valeurs possibles pour le paramètre `mode' de la famille de fonctions @ref{16bc,,spawn*}. Ces valeurs sont moins portables que celles listées plus haut. @ref{2b67,,P_DETACH} est similaire à @ref{2b64,,P_NOWAIT}, mais le nouveau processus est détaché de la console du processus appelant. Si @ref{2b68,,P_OVERLAY} est utilisé, le processus actuel sera remplacé. La fonction @ref{16bc,,spawn*} ne sort jamais.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex startfile() (dans le module os)
@anchor{library/os os startfile}@anchor{1859}
@deffn {Fonction} os.startfile (path[, operation][, arguments][, cwd][, show_cmd])

Lance un fichier avec son application associée.

When `operation' is not specified, this acts like double-clicking
the file in Windows Explorer, or giving the file name as an argument to the
@code{start} command from the interactive command shell: the file is opened
with whatever application (if any) its extension is associated.

When another `operation' is given, it must be a "command verb" that specifies
what should be done with the file. Common verbs documented by Microsoft are @code{'open'},
@code{'print'} and  @code{'edit'} (to be used on files) as well as @code{'explore'} and
@code{'find'} (to be used on directories).

When launching an application, specify `arguments' to be passed as a single
string. This argument may have no effect when using this function to launch a
document.

The default working directory is inherited, but may be overridden by the `cwd'
argument. This should be an absolute path. A relative `path' will be resolved
against this argument.

Use `show_cmd' to override the default window style. Whether this has any
effect will depend on the application being launched. Values are integers as
supported by the Win32 @code{ShellExecute()} function.

@ref{1859,,startfile()} returns as soon as the associated application is launched.
There is no option to wait for the application to close, and no way to retrieve
the application's exit status.  The `path' parameter is relative to the current
directory or `cwd'.  If you want to use an absolute path, make sure the first
character is not a slash (@code{'/'})  Use @ref{a3,,pathlib} or the
@ref{12f8,,os.path.normpath()} function to ensure that paths are properly encoded for
Win32.

To reduce interpreter startup overhead, the Win32 @code{ShellExecute()}
function is not resolved until this function is first called.  If the function
cannot be resolved, @ref{225,,NotImplementedError} will be raised.

Lève un @ref{1848,,événement d'audit} @code{os.startfile} avec les arguments @code{path}, @code{operation}.

Raises an @ref{1848,,auditing event} @code{os.startfile/2} with arguments @code{path}, @code{operation}, @code{arguments}, @code{cwd}, @code{show_cmd}.

@ref{1ce0,,Availability}: Windows.


Modifié dans la version 3.10: Added the `arguments', `cwd' and `show_cmd' arguments, and the
@code{os.startfile/2} audit event.

@end deffn

@geindex system() (dans le module os)
@anchor{library/os os system}@anchor{1411}
@deffn {Fonction} os.system (command)

Execute the command (a string) in a subshell.  This is implemented by calling
the Standard C function @code{system()}, and has the same limitations.
Changes to @ref{527,,sys.stdin}, etc. are not reflected in the environment of
the executed command. If `command' generates any output, it will be sent to
the interpreter standard output stream. The C standard does not
specify the meaning of the return value of the C function, so the return
value of the Python function is system-dependent.

On Unix, the return value is the exit status of the process encoded in the
format specified for @ref{d85,,wait()}.

Sur Windows, la valeur de retour est celle renvoyée par l'invite de commande système après avoir lancé `command'. L'invite de commande est donné par la variable d'environnement Windows 
@geindex COMSPEC
@geindex variable d'environnement; COMSPEC
@code{COMSPEC}. Elle vaut habituellement @code{cmd.exe}, qui renvoie l'état de sortie de la commande lancée. Sur les systèmes qui utilisent un invite de commande non-natif, consultez la documentation propre à l'invite.

Le module @ref{d5,,subprocess} fournit des outils plus puissants pour générer de nouveaux processus et pour récupérer leur résultat. Il est préférable d'utiliser ce module plutôt que d'utiliser cette fonction. Voir la section @ref{1168,,Remplacer les fonctions plus anciennes par le module subprocess} de la documentation du module @ref{d5,,subprocess} pour des informations plus précises et utiles.

On Unix, @ref{90a,,waitstatus_to_exitcode()} can be used to convert the result
(exit status) into an exit code. On Windows, the result is directly the exit
code.

Lève un @ref{1848,,évènement d'audit} @code{os.system} avec comme argument @code{command}.

@ref{1ce0,,Availability}: Unix, Windows, not WASI, not Android, not iOS.
@end deffn

@geindex times() (dans le module os)
@anchor{library/os os times}@anchor{10f5}
@deffn {Fonction} os.times ()

Renvoie les temps globaux actuels d'exécution du processus. La valeur de retour est un objet avec cinq attributs :


@itemize *

@item 
@code{user} - user time

@item 
@code{system} - system time

@item 
@code{children_user} - user time of all child processes

@item 
@code{children_system} - system time of all child processes

@item 
@code{elapsed} - elapsed real time since a fixed point in the past
@end itemize

For backwards compatibility, this object also behaves like a five-tuple
containing @code{user}, @code{system}, @code{children_user},
@code{children_system}, and @code{elapsed} in that order.

See the Unix manual page
@code{times(2)@footnote{https://manpages.debian.org/times(2)}} and times(3)@footnote{https://man.freebsd.org/cgi/man.cgi?time(3)} manual page on Unix or the GetProcessTimes MSDN@footnote{https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesstimes}
on Windows. On Windows, only @code{user} and @code{system} are known; the other attributes are zero.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.3: Type de retour changé d'un quintuplet en un objet compatible avec le type `n'-uplet, avec des attributs nommés.

@end deffn

@geindex wait() (dans le module os)
@anchor{library/os os wait}@anchor{d85}
@deffn {Fonction} os.wait ()

Attend qu'un processus fils soit complété, et renvoie une paire contenant son PID et son état de sortie : un nombre de 16 bits dont le `byte' de poids faible est le nombre correspondant au signal qui a tué le processus, et dont le `byte' de poids fort est le statut de sortie (si la signal vaut @code{0}). Le bit de poids fort du `byte' de poids faible est mis à 1 si un (fichier système) `core file' a été produit.

If there are no children that could be waited for, @ref{1041,,ChildProcessError}
is raised.

@ref{90a,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exit code.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.


@subsubheading Voir aussi


The other @code{wait*()} functions documented below can be used to wait for the
completion of a specific child process and have more options.
@ref{d87,,waitpid()} is the only one also available on Windows.

@end deffn

@geindex waitid() (dans le module os)
@anchor{library/os os waitid}@anchor{d86}
@deffn {Fonction} os.waitid (idtype, id, options, /)

Wait for the completion of a child process.

`idtype' can be @ref{2b69,,P_PID}, @ref{2b6a,,P_PGID}, @ref{2b6b,,P_ALL}, or (on Linux) @ref{907,,P_PIDFD}.
The interpretation of `id' depends on it; see their individual descriptions.

`options' is an OR combination of flags.  At least one of @ref{2b6c,,WEXITED},
@ref{2b6d,,WSTOPPED} or @ref{2b6e,,WCONTINUED} is required;
@ref{2b6f,,WNOHANG} and @ref{2b70,,WNOWAIT} are additional optional flags.

The return value is an object representing the data contained in the
@code{siginfo_t} structure with the following attributes:


@itemize *

@item 
@code{si_pid} (process ID)

@item 
@code{si_uid} (real user ID of the child)

@item 
@code{si_signo} (always @ref{2b71,,SIGCHLD})

@item 
@code{si_status} (the exit status or signal number, depending on @code{si_code})

@item 
@code{si_code} (see @ref{2b72,,CLD_EXITED} for possible values)
@end itemize

If @ref{2b6f,,WNOHANG} is specified and there are no matching children in the
requested state, @code{None} is returned.
Otherwise, if there are no matching children
that could be waited for, @ref{1041,,ChildProcessError} is raised.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.


Ajouté dans la version 3.3.



Modifié dans la version 3.13: This function is now available on macOS as well.

@end deffn

@geindex waitpid() (dans le module os)
@anchor{library/os os waitpid}@anchor{d87}
@deffn {Fonction} os.waitpid (pid, options, /)

Les détails de cette fonction diffèrent sur Unix et Windows.

Sur Unix : attend qu'un processus fils donné par son id de processus `pid' soit terminé, et renvoie une paire contenant son PID et son statut de sortie (encodé comme pour @ref{d85,,wait()}). La sémantique de cet appel est affecté par la valeur de l'argument entier `options', qui devrait valoir @code{0} pour les opérations normales.

Si `pid' est plus grand que @code{0}, @ref{d87,,waitpid()} introduit une requête pour des informations sur le statut du processus spécifié. Si `pid' vaut @code{0}, la requête est pour le statut de tous les fils dans le groupe de processus du processus actuel. Si `pid' vaut @code{-1}, la requête concerne tous les processus fils du processus actuel. Si `pid' est inférieur à @code{-1}, une requête est faite pour le statut de chaque processus du groupe de processus donné par @code{-pid} (la valeur absolue de `pid').

`options' is an OR combination of flags.  If it contains @ref{2b6f,,WNOHANG} and
there are no matching children in the requested state, @code{(0, 0)} is
returned.  Otherwise, if there are no matching children that could be waited
for, @ref{1041,,ChildProcessError} is raised.  Other options that can be used are
@ref{2b73,,WUNTRACED} and @ref{2b6e,,WCONTINUED}.

Sur Windows : attend que qu'un processus donné par l'identificateur de processus (`process handle') `pid' soit complété, et renvoie une paire contenant `pid' et son statut de sortie décalé de 8 bits vers la gauche (le décalage rend l'utilisation multiplateformes plus facile). Un `pid' inférieur ou égal à @code{0} n'a aucune signification particulière en Windows, et lève une exception. L'argument entier `options' n'a aucun effet. `pid' peut faire référence à tout processus dont l'identifiant est connu et pas nécessairement à un processus fils. Les fonctions @ref{16bc,,spawn*} appelées avec @ref{2b64,,P_NOWAIT} renvoient des identificateurs de processus appropriés.

@ref{90a,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exit code.

@ref{1ce0,,Availability}: Unix, Windows, not WASI, not Android, not iOS.


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex wait3() (dans le module os)
@anchor{library/os os wait3}@anchor{d83}
@deffn {Fonction} os.wait3 (options)

Similar to @ref{d87,,waitpid()}, except no process id argument is given and a
3-element tuple containing the child's process id, exit status indication,
and resource usage information is returned.  Refer to
@ref{13e7,,resource.getrusage()} for details on resource usage information.  The
`options' argument is the same as that provided to @ref{d87,,waitpid()} and
@ref{d84,,wait4()}.

@ref{90a,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exitcode.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex wait4() (dans le module os)
@anchor{library/os os wait4}@anchor{d84}
@deffn {Fonction} os.wait4 (pid, options)

Similar to @ref{d87,,waitpid()}, except a 3-element tuple, containing the child's
process id, exit status indication, and resource usage information is
returned.  Refer to @ref{13e7,,resource.getrusage()} for details on resource usage
information.  The arguments to @ref{d84,,wait4()} are the same as those provided
to @ref{d87,,waitpid()}.

@ref{90a,,waitstatus_to_exitcode()} can be used to convert the exit status into an
exitcode.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex P_PID (dans le module os)
@geindex P_PGID (dans le module os)
@geindex P_ALL (dans le module os)
@geindex P_PIDFD (dans le module os)
@anchor{library/os os P_PID}@anchor{2b69}
@deffn {Données} os.P_PID
@anchor{library/os os P_PGID}@anchor{2b6a}
@deffnx {Données} os.P_PGID
@anchor{library/os os P_ALL}@anchor{2b6b}
@deffnx {Données} os.P_ALL
@anchor{library/os os P_PIDFD}@anchor{907}
@deffnx {Données} os.P_PIDFD

These are the possible values for `idtype' in @ref{d86,,waitid()}. They affect
how `id' is interpreted:


@itemize *

@item 
@code{P_PID} - wait for the child whose PID is `id'.

@item 
@code{P_PGID} - wait for any child whose progress group ID is `id'.

@item 
@code{P_ALL} - wait for any child; `id' is ignored.

@item 
@code{P_PIDFD} - wait for the child identified by the file descriptor
`id' (a process file descriptor created with @ref{464,,pidfd_open()}).
@end itemize

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.

@cartouche
@quotation Note 
@code{P_PIDFD} is only available on Linux >= 5.4.
@end quotation
@end cartouche


Ajouté dans la version 3.3.



Ajouté dans la version 3.9: The @code{P_PIDFD} constant.

@end deffn

@geindex WCONTINUED (dans le module os)
@anchor{library/os os WCONTINUED}@anchor{2b6e}
@deffn {Données} os.WCONTINUED

This `options' flag for @ref{d87,,waitpid()}, @ref{d83,,wait3()}, @ref{d84,,wait4()}, and
@ref{d86,,waitid()} causes child processes to be reported if they have been
continued from a job control stop since they were last reported.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WEXITED (dans le module os)
@anchor{library/os os WEXITED}@anchor{2b6c}
@deffn {Données} os.WEXITED

This `options' flag for @ref{d86,,waitid()} causes child processes that have terminated to
be reported.

The other @code{wait*} functions always report children that have terminated,
so this option is not available for them.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.


Ajouté dans la version 3.3.

@end deffn

@geindex WSTOPPED (dans le module os)
@anchor{library/os os WSTOPPED}@anchor{2b6d}
@deffn {Données} os.WSTOPPED

This `options' flag for @ref{d86,,waitid()} causes child processes that have been stopped
by the delivery of a signal to be reported.

This option is not available for the other @code{wait*} functions.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.


Ajouté dans la version 3.3.

@end deffn

@geindex WUNTRACED (dans le module os)
@anchor{library/os os WUNTRACED}@anchor{2b73}
@deffn {Données} os.WUNTRACED

This `options' flag for @ref{d87,,waitpid()}, @ref{d83,,wait3()}, and @ref{d84,,wait4()} causes
child processes to also be reported if they have been stopped but their
current state has not been reported since they were stopped.

This option is not available for @ref{d86,,waitid()}.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WNOHANG (dans le module os)
@anchor{library/os os WNOHANG}@anchor{2b6f}
@deffn {Données} os.WNOHANG

This `options' flag causes @ref{d87,,waitpid()}, @ref{d83,,wait3()}, @ref{d84,,wait4()}, and
@ref{d86,,waitid()} to return right away if no child process status is available
immediately.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WNOWAIT (dans le module os)
@anchor{library/os os WNOWAIT}@anchor{2b70}
@deffn {Données} os.WNOWAIT

This `options' flag causes @ref{d86,,waitid()} to leave the child in a waitable state, so that
a later @code{wait*()} call can be used to retrieve the child status information again.

This option is not available for the other @code{wait*} functions.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex CLD_EXITED (dans le module os)
@geindex CLD_KILLED (dans le module os)
@geindex CLD_DUMPED (dans le module os)
@geindex CLD_TRAPPED (dans le module os)
@geindex CLD_STOPPED (dans le module os)
@geindex CLD_CONTINUED (dans le module os)
@anchor{library/os os CLD_EXITED}@anchor{2b72}
@deffn {Données} os.CLD_EXITED
@anchor{library/os os CLD_KILLED}@anchor{905}
@deffnx {Données} os.CLD_KILLED
@anchor{library/os os CLD_DUMPED}@anchor{2b74}
@deffnx {Données} os.CLD_DUMPED
@anchor{library/os os CLD_TRAPPED}@anchor{2b75}
@deffnx {Données} os.CLD_TRAPPED
@anchor{library/os os CLD_STOPPED}@anchor{906}
@deffnx {Données} os.CLD_STOPPED
@anchor{library/os os CLD_CONTINUED}@anchor{2b76}
@deffnx {Données} os.CLD_CONTINUED

These are the possible values for @code{si_code} in the result returned by
@ref{d86,,waitid()}.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.


Ajouté dans la version 3.3.



Modifié dans la version 3.9: Added @ref{905,,CLD_KILLED} and @ref{906,,CLD_STOPPED} values.

@end deffn

@geindex waitstatus_to_exitcode() (dans le module os)
@anchor{library/os os waitstatus_to_exitcode}@anchor{90a}
@deffn {Fonction} os.waitstatus_to_exitcode (status)

Convert a wait status to an exit code.

On Unix:


@itemize *

@item 
If the process exited normally (if @code{WIFEXITED(status)} is true),
return the process exit status (return @code{WEXITSTATUS(status)}):
result greater than or equal to 0.

@item 
If the process was terminated by a signal (if @code{WIFSIGNALED(status)} is
true), return @code{-signum} where `signum' is the number of the signal that
caused the process to terminate (return @code{-WTERMSIG(status)}):
result less than 0.

@item 
Otherwise, raise a @ref{1ff,,ValueError}.
@end itemize

On Windows, return `status' shifted right by 8 bits.

On Unix, if the process is being traced or if @ref{d87,,waitpid()} was called
with @ref{2b73,,WUNTRACED} option, the caller must first check if
@code{WIFSTOPPED(status)} is true. This function must not be called if
@code{WIFSTOPPED(status)} is true.


@subsubheading Voir aussi


@ref{2b77,,WIFEXITED()}, @ref{2b78,,WEXITSTATUS()}, @ref{2b79,,WIFSIGNALED()},
@ref{2b7a,,WTERMSIG()}, @ref{2b7b,,WIFSTOPPED()}, @ref{2b7c,,WSTOPSIG()} functions.


@ref{1ce0,,Availability}: Unix, Windows, not WASI, not Android, not iOS.


Ajouté dans la version 3.9.

@end deffn

Les fonctions suivantes prennent un code de statu tel que renvoyé par @ref{1411,,system()}, @ref{d85,,wait()}, ou @ref{d87,,waitpid()} en paramètre. Ils peuvent être utilisés pour déterminer la disposition d'un processus.

@geindex WCOREDUMP() (dans le module os)
@anchor{library/os os WCOREDUMP}@anchor{2b7d}
@deffn {Fonction} os.WCOREDUMP (status, /)

Renvoie @code{True} si un vidage système (`core dump') a été généré pour le processus, sinon, renvoie @code{False}.

This function should be employed only if @ref{2b79,,WIFSIGNALED()} is true.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFCONTINUED() (dans le module os)
@anchor{library/os os WIFCONTINUED}@anchor{2b7e}
@deffn {Fonction} os.WIFCONTINUED (status)

Return @code{True} if a stopped child has been resumed by delivery of
@ref{2b7f,,SIGCONT} (if the process has been continued from a job
control stop), otherwise return @code{False}.

See @ref{2b6e,,WCONTINUED} option.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFSTOPPED() (dans le module os)
@anchor{library/os os WIFSTOPPED}@anchor{2b7b}
@deffn {Fonction} os.WIFSTOPPED (status)

Return @code{True} if the process was stopped by delivery of a signal,
otherwise return @code{False}.

@ref{2b7b,,WIFSTOPPED()} only returns @code{True} if the @ref{d87,,waitpid()} call was
done using @ref{2b73,,WUNTRACED} option or when the process is being traced (see
@code{ptrace(2)@footnote{https://manpages.debian.org/ptrace(2)}}).

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFSIGNALED() (dans le module os)
@anchor{library/os os WIFSIGNALED}@anchor{2b79}
@deffn {Fonction} os.WIFSIGNALED (status)

Return @code{True} if the process was terminated by a signal, otherwise return
@code{False}.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WIFEXITED() (dans le module os)
@anchor{library/os os WIFEXITED}@anchor{2b77}
@deffn {Fonction} os.WIFEXITED (status)

Return @code{True} if the process exited terminated normally, that is,
by calling @code{exit()} or @code{_exit()}, or by returning from @code{main()};
otherwise return @code{False}.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WEXITSTATUS() (dans le module os)
@anchor{library/os os WEXITSTATUS}@anchor{2b78}
@deffn {Fonction} os.WEXITSTATUS (status)

Return the process exit status.

This function should be employed only if @ref{2b77,,WIFEXITED()} is true.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WSTOPSIG() (dans le module os)
@anchor{library/os os WSTOPSIG}@anchor{2b7c}
@deffn {Fonction} os.WSTOPSIG (status)

Renvoie le signal qui a causé l'arrêt du processus.

This function should be employed only if @ref{2b7b,,WIFSTOPPED()} is true.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@geindex WTERMSIG() (dans le module os)
@anchor{library/os os WTERMSIG}@anchor{2b7a}
@deffn {Fonction} os.WTERMSIG (status)

Return the number of the signal that caused the process to terminate.

This function should be employed only if @ref{2b79,,WIFSIGNALED()} is true.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.
@end deffn

@node Interface pour l'ordonnanceur,Diverses informations sur le système,Gestion des processus,os --- Miscellaneous operating system interfaces
@anchor{library/os interface-to-the-scheduler}@anchor{2b80}
@subsubsection Interface pour l'ordonnanceur


Ces fonctions contrôlent un processus se voit allouer du temps de processus par le système d'exploitation. Elles ne sont disponibles que sur certaines plate-formes Unix. Pour des informations plus détaillées, consultez les pages de manuels Unix.


Ajouté dans la version 3.3.


Les polices d'ordonnancement suivantes sont exposées si elles sont gérées par le système d'exploitation.

@geindex SCHED_OTHER (dans le module os)
@anchor{library/os os SCHED_OTHER}@anchor{2b81}
@deffn {Données} os.SCHED_OTHER

La police d'ordonnancement par défaut.
@end deffn

@geindex SCHED_BATCH (dans le module os)
@anchor{library/os os SCHED_BATCH}@anchor{2b82}
@deffn {Données} os.SCHED_BATCH

Police d'ordonnancement pour les processus intensifs en utilisation du processeur. Cette police essaye de préserver l'interactivité pour le reste de l'ordinateur.
@end deffn

@geindex SCHED_IDLE (dans le module os)
@anchor{library/os os SCHED_IDLE}@anchor{2b83}
@deffn {Données} os.SCHED_IDLE

Police d'ordonnancement pour les tâches de fond avec une priorité extrêmement faible.
@end deffn

@geindex SCHED_SPORADIC (dans le module os)
@anchor{library/os os SCHED_SPORADIC}@anchor{2b84}
@deffn {Données} os.SCHED_SPORADIC

Police d'ordonnancement pour des programmes serveurs sporadiques.
@end deffn

@geindex SCHED_FIFO (dans le module os)
@anchor{library/os os SCHED_FIFO}@anchor{2b85}
@deffn {Données} os.SCHED_FIFO

Une police d'ordonnancement `FIFO' (dernier arrivé, premier servi).
@end deffn

@geindex SCHED_RR (dans le module os)
@anchor{library/os os SCHED_RR}@anchor{2b86}
@deffn {Données} os.SCHED_RR

Une police d'ordonnancement `round-robin' (tourniquet).
@end deffn

@geindex SCHED_RESET_ON_FORK (dans le module os)
@anchor{library/os os SCHED_RESET_ON_FORK}@anchor{2b87}
@deffn {Données} os.SCHED_RESET_ON_FORK

Cette option peut combiner différentes politiques d'ordonnancement avec un OU bit-à-bit. Quand un processus avec cette option se dédouble, la politique d'ordonnancement et la priorité du processus fils sont remises aux valeurs par défaut.
@end deffn

@geindex sched_param (classe dans os)
@anchor{library/os os sched_param}@anchor{1529}
@deffn {Classe} os.sched_param (sched_priority)

Cette classe représente des paramètres d'ordonnancement réglables utilisés pour @ref{10ef,,sched_setparam()}, @ref{10f0,,sched_setscheduler()}, et @ref{10eb,,sched_getparam()}. Un objet de ce type est immuable.

Pour le moment, il n'y a qu'un seul paramètre possible :

@geindex sched_priority (attribut os.sched_param)
@anchor{library/os os sched_param sched_priority}@anchor{2b88}
@deffn {Attribut} sched_priority

La priorité d'ordonnancement pour une police d'ordonnancement.
@end deffn
@end deffn

@geindex sched_get_priority_min() (dans le module os)
@anchor{library/os os sched_get_priority_min}@anchor{10e9}
@deffn {Fonction} os.sched_get_priority_min (policy)

Récupère la valeur minimum pour une priorité pour la police `policy'. `policy' est une des constantes de police définies ci-dessus.
@end deffn

@geindex sched_get_priority_max() (dans le module os)
@anchor{library/os os sched_get_priority_max}@anchor{10e8}
@deffn {Fonction} os.sched_get_priority_max (policy)

Récupère la valeur maximum pour une priorité pour la police `policy'. `policy' est une des constantes de police définies ci-dessus.
@end deffn

@geindex sched_setscheduler() (dans le module os)
@anchor{library/os os sched_setscheduler}@anchor{10f0}
@deffn {Fonction} os.sched_setscheduler (pid, policy, param, /)

Définit la police d'ordonnancement pour le processus de PID `pid'. Un `pid' de @code{0} signifie le processus appelant. `policy' est une des constantes de police définies ci-dessus. `param' est une instance de la classe @ref{1529,,sched_param}.
@end deffn

@geindex sched_getscheduler() (dans le module os)
@anchor{library/os os sched_getscheduler}@anchor{10ec}
@deffn {Fonction} os.sched_getscheduler (pid, /)

Renvoie la police d'ordonnancement pour le processus de PID `pid'. Un `pid' de 0 signifie le processus appelant. Le résultat est une des constantes de police définies ci-dessus.
@end deffn

@geindex sched_setparam() (dans le module os)
@anchor{library/os os sched_setparam}@anchor{10ef}
@deffn {Fonction} os.sched_setparam (pid, param, /)

Set the scheduling parameters for the process with PID `pid'. A `pid' of 0 means
the calling process. `param' is a @ref{1529,,sched_param} instance.
@end deffn

@geindex sched_getparam() (dans le module os)
@anchor{library/os os sched_getparam}@anchor{10eb}
@deffn {Fonction} os.sched_getparam (pid, /)

Renvoie les paramètres d'ordonnancement dans une de @ref{1529,,sched_param} pour le processus de PID `pid'. Un `pid' de @code{0} signifie le processus appelant.
@end deffn

@geindex sched_rr_get_interval() (dans le module os)
@anchor{library/os os sched_rr_get_interval}@anchor{10ed}
@deffn {Fonction} os.sched_rr_get_interval (pid, /)

Renvoie le quantum de temps du `round-robin' (en secondes) pour le processus de PID `pid'. Un `pid' de @code{0} signifie le processus appelant.
@end deffn

@geindex sched_yield() (dans le module os)
@anchor{library/os os sched_yield}@anchor{10f1}
@deffn {Fonction} os.sched_yield ()

Abandonne volontairement le processeur.
@end deffn

@geindex sched_setaffinity() (dans le module os)
@anchor{library/os os sched_setaffinity}@anchor{10ee}
@deffn {Fonction} os.sched_setaffinity (pid, mask, /)

Restreint le processus de PID `pid'  (ou le processus actuel si `pid' vaut @code{0}) à un ensemble de CPUs. `mask' est un itérable d'entiers représentant l'ensemble de CPUs auquel le processus doit être restreint.
@end deffn

@geindex sched_getaffinity() (dans le module os)
@anchor{library/os os sched_getaffinity}@anchor{10ea}
@deffn {Fonction} os.sched_getaffinity (pid, /)

Return the set of CPUs the process with PID `pid' is restricted to.

If `pid' is zero, return the set of CPUs the calling thread of the current
process is restricted to.

See also the @ref{1bf,,process_cpu_count()} function.
@end deffn

@node Diverses informations sur le système,Nombres aléatoires<2>,Interface pour l'ordonnanceur,os --- Miscellaneous operating system interfaces
@anchor{library/os miscellaneous-system-information}@anchor{2b89}@anchor{library/os os-path}@anchor{2b8a}
@subsubsection Diverses informations sur le système


@geindex confstr() (dans le module os)
@anchor{library/os os confstr}@anchor{2b8b}
@deffn {Fonction} os.confstr (name, /)

Renvoie les valeurs de configuration en chaînes de caractères. `name' spécifie la valeur de configuration à récupérer. Ce peut être une chaîne de caractères représentant le nom d'une valeur système définie dans un nombre de standards (POSIX, Unix 95, Unix 98, et d'autres). Certaines plate-formes définissent des noms supplémentaires également. Les noms connus par le système d'exploitation hôte sont données dans les clefs du dictionnaire @code{confstr_names}. Pour les variables de configuration qui ne sont pas incluses dans ce `mapping', passer un entier pour `name' est également accepté.

Si la valeur de configuration spécifiée par `name' n'est pas définie, @code{None} est renvoyé.

Si `name' est une chaîne de caractères et n'est pas connue, une @ref{1ff,,ValueError} est levée. Si une valeur spécifique pour `name' n'est pas gérée par le système hôte, même si elle est incluse dans @code{confstr_names}, une @ref{40d,,OSError} est levée avec @ref{197d,,errno.EINVAL} pour numéro d'erreur.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex confstr_names (dans le module os)
@anchor{library/os os confstr_names}@anchor{2b8c}
@deffn {Données} os.confstr_names

Dictionnaire liant les noms acceptés par @ref{2b8b,,confstr()} aux valeurs entières définies pour ces noms par le système d'exploitation hôte. Cela peut être utilisé pour déterminer l'ensemble des noms connus du système.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex cpu_count() (dans le module os)
@anchor{library/os os cpu_count}@anchor{1c0}
@deffn {Fonction} os.cpu_count ()

Return the number of logical CPUs in the `system'. Returns @code{None} if
undetermined.

The @ref{1bf,,process_cpu_count()} function can be used to get the number of
logical CPUs usable by the calling thread of the `current process'.


Ajouté dans la version 3.4.



Modifié dans la version 3.13: If @ref{175,,-X cpu_count} is given or 
@geindex PYTHON_CPU_COUNT
@geindex variable d'environnement; PYTHON_CPU_COUNT
@ref{20d,,PYTHON_CPU_COUNT} is set,
@ref{1c0,,cpu_count()} returns the overridden value `n'.

@end deffn

@geindex getloadavg() (dans le module os)
@anchor{library/os os getloadavg}@anchor{156e}
@deffn {Fonction} os.getloadavg ()

Renvoie le nombre de processus dans la file d'exécution du système en moyenne dans les dernières 1, 5, et 15 minutes, ou lève une @ref{40d,,OSError} si la charge moyenne est impossible à récupérer.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex process_cpu_count() (dans le module os)
@anchor{library/os os process_cpu_count}@anchor{1bf}
@deffn {Fonction} os.process_cpu_count ()

Get the number of logical CPUs usable by the calling thread of the `current
process'. Returns @code{None} if undetermined. It can be less than
@ref{1c0,,cpu_count()} depending on the CPU affinity.

The @ref{1c0,,cpu_count()} function can be used to get the number of logical CPUs
in the `system'.

If @ref{175,,-X cpu_count} is given or 
@geindex PYTHON_CPU_COUNT
@geindex variable d'environnement; PYTHON_CPU_COUNT
@ref{20d,,PYTHON_CPU_COUNT} is set,
@ref{1bf,,process_cpu_count()} returns the overridden value `n'.

See also the @ref{10ea,,sched_getaffinity()} function.


Ajouté dans la version 3.13.

@end deffn

@geindex sysconf() (dans le module os)
@anchor{library/os os sysconf}@anchor{2aec}
@deffn {Fonction} os.sysconf (name, /)

Renvoie les valeurs de configuration en nombres entiers. Si la valeur de configuration définie par `name' n'est pas spécifiée, @code{-1} est renvoyé. Les commentaires concernant le paramètre `name' de @ref{2b8b,,confstr()} s'appliquent également ici, le dictionnaire qui fournit les informations sur les noms connus est donné par @code{sysconf_names}.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex sysconf_names (dans le module os)
@anchor{library/os os sysconf_names}@anchor{2b8d}
@deffn {Données} os.sysconf_names

Dictionnaire liant les noms acceptés par @ref{2aec,,sysconf()} aux valeurs entières définies pour ces noms par le système d'exploitation hôte. Cela peut être utilisé pour déterminer l'ensemble des noms connus du système.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.11: Add @code{'SC_MINSIGSTKSZ'} name.

@end deffn

Les valeurs suivantes sont utilisées pour gérer les opérations de manipulations de chemins. Elles sont définies pour toutes les plate-formes.

Des opérations de plus haut niveau sur les chemins sont définies dans le module @ref{a1,,os.path}.

@geindex . (dot);in pathnames

@geindex curdir (dans le module os)
@anchor{library/os os curdir}@anchor{275d}
@deffn {Données} os.curdir

La chaîne de caractère constante utilisée par le système d'exploitation pour référencer le répertoire actuel. Ça vaut @code{'.'} pour Windows et POSIX. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex ..;in pathnames

@geindex pardir (dans le module os)
@anchor{library/os os pardir}@anchor{2b07}
@deffn {Données} os.pardir

La chaîne de caractère constante utilisée par le système d'exploitation pour référencer le répertoire parent. Ça vaut @code{'..'} pour Windows et POSIX. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex / (slash);in pathnames

@geindex \ (backslash);in pathnames (Windows)

@geindex sep (dans le module os)
@anchor{library/os os sep}@anchor{655}
@deffn {Données} os.sep

Le caractère utilisé par le système d'exploitation pour séparer les composantes des chemins. C'est @code{'/'} pour POSIX, et @code{'\\'} pour Windows. Notez que ce n'est pas suffisant pour pouvoir analyser ou concaténer correctement des chemins (utilisez alors @ref{2757,,os.path.split()} et @ref{15bc,,os.path.join()}), mais ça peut s'avérer utile occasionnellement.  Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex / (slash);in pathnames

@geindex altsep (dans le module os)
@anchor{library/os os altsep}@anchor{656}
@deffn {Données} os.altsep

Un caractère alternatif utilisé par le système d'exploitation pour séparer les composantes des chemins, ou @code{None} si un seul séparateur existe. Ça vaut @code{'/'} sur Windows où @code{sep} est un antislash @code{'\'}. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex . (dot);in pathnames

@geindex extsep (dans le module os)
@anchor{library/os os extsep}@anchor{2b8e}
@deffn {Données} os.extsep

Le caractère qui sépare la base du nom d'un fichier et son extension. Par exemple, le @code{'.'} de @code{os.py}. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex ; (colon);path separator (POSIX)
@geindex ; (semicolon)

@geindex pathsep (dans le module os)
@anchor{library/os os pathsep}@anchor{1cd0}
@deffn {Données} os.pathsep

Le caractère conventionnellement utilisé par le système d'exploitation pour séparer la recherche des composantes de chemin (comme dans la variable d'environnement 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}). Cela vaut @code{':'} pour POSIX, ou @code{';'} pour Windows. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex defpath (dans le module os)
@anchor{library/os os defpath}@anchor{1990}
@deffn {Données} os.defpath

Le chemin de recherche par défaut utilisé par @ref{2b41,,exec*} et @ref{16bc,,spawn*} si l'environnement n'a pas une clef @code{'PATH'}. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex linesep (dans le module os)
@anchor{library/os os linesep}@anchor{2102}
@deffn {Données} os.linesep

La chaîne de caractères utilisée pour séparer (ou plutôt pour terminer) les lignes sur la plate-forme actuelle. Ce peut être un caractère unique (comme @code{'\n'} pour POSIX,) ou plusieurs caractères (comme @code{'\r\n'} pour Windows). N'utilisez pas `os.linesep' comme terminateur de ligne quand vous écrivez dans un fichier ouvert en mode `texte' (par défaut). Utilisez un unique @code{'\n'} à la place, sur toutes les plate-formes.
@end deffn

@geindex devnull (dans le module os)
@anchor{library/os os devnull}@anchor{19c1}
@deffn {Données} os.devnull

Le chemin de fichier du périphérique `null'. Par exemple : @code{'/dev/null'} pour POSIX, @code{'nul'} pour Windows. Également disponible par @ref{a1,,os.path}.
@end deffn

@geindex RTLD_LAZY (dans le module os)
@geindex RTLD_NOW (dans le module os)
@geindex RTLD_GLOBAL (dans le module os)
@geindex RTLD_LOCAL (dans le module os)
@geindex RTLD_NODELETE (dans le module os)
@geindex RTLD_NOLOAD (dans le module os)
@geindex RTLD_DEEPBIND (dans le module os)
@anchor{library/os os RTLD_LAZY}@anchor{10f8}
@deffn {Données} os.RTLD_LAZY
@anchor{library/os os RTLD_NOW}@anchor{10f9}
@deffnx {Données} os.RTLD_NOW
@anchor{library/os os RTLD_GLOBAL}@anchor{10fa}
@deffnx {Données} os.RTLD_GLOBAL
@anchor{library/os os RTLD_LOCAL}@anchor{10fb}
@deffnx {Données} os.RTLD_LOCAL
@anchor{library/os os RTLD_NODELETE}@anchor{10fc}
@deffnx {Données} os.RTLD_NODELETE
@anchor{library/os os RTLD_NOLOAD}@anchor{10fd}
@deffnx {Données} os.RTLD_NOLOAD
@anchor{library/os os RTLD_DEEPBIND}@anchor{10fe}
@deffnx {Données} os.RTLD_DEEPBIND

Marqueurs à utiliser avec les fonctions @ref{10ff,,setdlopenflags()} et @ref{14c6,,getdlopenflags()}. Voir les pages de manuel Unix @code{dlopen(3)@footnote{https://manpages.debian.org/dlopen(3)}} pour les différences de significations entre les marqueurs.


Ajouté dans la version 3.3.

@end deffn

@node Nombres aléatoires<2>,,Diverses informations sur le système,os --- Miscellaneous operating system interfaces
@anchor{library/os random-numbers}@anchor{2b8f}
@subsubsection Nombres aléatoires


@geindex getrandom() (dans le module os)
@anchor{library/os os getrandom}@anchor{cab}
@deffn {Fonction} os.getrandom (size, flags=0)

Obtient `size' octets aléatoires. La fonction renvoie éventuellement moins d'octets que demandé.

Ces octets peuvent être utilisés pour initialiser un générateur de nombres aléatoires dans l'espace utilisateur ou pour des raisons cryptographiques.

@code{getrandom()} se base sur l'entropie rassemblée depuis les pilotes des périphériques et autres sources de bruits de l'environnement. La lecture de grosses quantités de données aura un impact négatif sur les autres utilisateurs des périphériques @code{/dev/random} et @code{/dev/urandom}.

The flags argument is a bit mask that can contain zero or more of the
following values ORed together: @ref{2b90,,os.GRND_RANDOM} and
@ref{2b91,,GRND_NONBLOCK}.

See also the Linux getrandom() manual page@footnote{https://man7.org/linux/man-pages/man2/getrandom.2.html}.

@ref{1ce0,,Availability}: Linux >= 3.17.


Ajouté dans la version 3.6.

@end deffn

@geindex urandom() (dans le module os)
@anchor{library/os os urandom}@anchor{50c}
@deffn {Fonction} os.urandom (size, /)

Return a bytestring of `size' random bytes suitable for cryptographic use.

Cette fonction renvoie des octets aléatoires depuis un source spécifique à l'OS.  Les données renvoyées sont censées être suffisamment imprévisibles pour les applications cryptographiques, bien que la qualité dépende de l'implémentation du système.

Sous Linux, si l'appel système @code{getrandom()} est disponible, il est utilisé en mode bloquant : il bloque jusqu'à ce que la réserve d'entropie d'`urandom' soit initialisée (128 bits d'entropie sont collectés par le noyau). Voir la 
@geindex Python Enhancement Proposals; PEP 524
PEP 524@footnote{https://peps.python.org/pep-0524/} pour plus d'explications. Sous Linux, la fonction @ref{cab,,getrandom()} peut être utilisée pour obtenir des octets aléatoires en mode non-bloquant (avec l'option @ref{2b91,,GRND_NONBLOCK}) ou attendre jusqu'à ce que la réserve d'entropie d'`urandom' soit initialisée.

Sur un système de type UNIX, les octets aléatoires sont lus depuis le périphérique @code{/dev/urandom}. Si le périphérique @code{/dev/urandom} n'est pas disponible ou n'est pas lisible, l'exception @ref{225,,NotImplementedError} est levée.

On Windows, it will use @code{BCryptGenRandom()}.


@subsubheading Voir aussi


Le module @ref{bf,,secrets} fournit des fonctions de plus haut niveau. Pour une interface facile à utiliser du générateur de nombres aléatoires fourni par votre plate-forme, veuillez regarder @ref{2662,,random.SystemRandom}.



Modifié dans la version 3.5: Sur Linux 3.17 et plus récent, l'appel système @code{getrandom()} est maintenant utilisé quand il est disponible. Sur OpenBSD 5.6 et plus récent, la fonction C @code{getentropy()} est utilisée. Ces fonctions évitent l'utilisation interne d'un descripteur de fichier.



Modifié dans la version 3.5.2: Sous Linux, si l'appel système @code{getrandom()} bloque (la réserve d'entropie d'`urandom' n'est pas encore initialisée), réalise à la place une lecture de @code{/dev/urandom}.



Modifié dans la version 3.6: Sous Linux, @code{getrandom()} est maintenant utilisé en mode bloquant pour renforcer la sécurité.



Modifié dans la version 3.11: On Windows, @code{BCryptGenRandom()} is used instead of @code{CryptGenRandom()}
which is deprecated.

@end deffn

@geindex GRND_NONBLOCK (dans le module os)
@anchor{library/os os GRND_NONBLOCK}@anchor{2b91}
@deffn {Données} os.GRND_NONBLOCK

Par défaut, quand elle lit depuis @code{/dev/random}, @ref{cab,,getrandom()} bloque si aucun octet aléatoire n'est disponible, et quand elle lit depuis @code{/dev/urandom}, elle bloque si la réserve d'entropie n'a pas encore été initialisée.

Si l'option @ref{2b91,,GRND_NONBLOCK} est activée, @ref{cab,,getrandom()} ne bloque pas dans ces cas, mais lève immédiatement une @ref{1040,,BlockingIOError}.


Ajouté dans la version 3.6.

@end deffn

@geindex GRND_RANDOM (dans le module os)
@anchor{library/os os GRND_RANDOM}@anchor{2b90}
@deffn {Données} os.GRND_RANDOM

Si ce bit est activé, les octets aléatoires sont puisés depuis @code{/dev/random} plutôt que @code{/dev/urandom}.


Ajouté dans la version 3.6.

@end deffn

@node io --- Core tools for working with streams,time --- Time access and conversions,os --- Miscellaneous operating system interfaces,Services génériques du système d'exploitation
@anchor{library/io doc}@anchor{2b92}@anchor{library/io io-core-tools-for-working-with-streams}@anchor{2b93}@anchor{library/io module-io}@anchor{7e}
@subsection @code{io} --- Core tools for working with streams


@geindex module; io

`Code source:' Lib/io.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/io.py}


__________________________________________________________________


@menu
* Aperçu: Aperçu<2>. 
* Encodage de texte:: 
* Interface de haut niveau du module:: 
* Class hierarchy:: 
* Performances: Performances<3>. 

@end menu

@node Aperçu<2>,Encodage de texte,,io --- Core tools for working with streams
@anchor{library/io io-overview}@anchor{2100}@anchor{library/io overview}@anchor{2b94}
@subsubsection Aperçu


@geindex file object;io module

The @ref{7e,,io} module provides Python's main facilities for dealing with various
types of I/O.  There are three main types of I/O: `text I/O', `binary I/O'
and `raw I/O'.  These are generic categories, and various backing stores can
be used for each of them.  A concrete object belonging to any of these
categories is called a @ref{11a0,,file object}.  Other common terms are `stream'
and `file-like object'.

Independent of its category, each concrete stream object will also have
various capabilities: it can be read-only, write-only, or read-write. It can
also allow arbitrary random access (seeking forwards or backwards to any
location), or only sequential access (for example in the case of a socket or
pipe).

All streams are careful about the type of data you give to them.  For example
giving a @ref{435,,str} object to the @code{write()} method of a binary stream
will raise a @ref{522,,TypeError}.  So will giving a @ref{1bd,,bytes} object to the
@code{write()} method of a text stream.


Modifié dans la version 3.3: Operations that used to raise @ref{103b,,IOError} now raise @ref{40d,,OSError}, since
@ref{103b,,IOError} is now an alias of @ref{40d,,OSError}.


@menu
* Entrée/sortie de texte:: 
* Binary I/O:: 
* Raw I/O:: 

@end menu

@node Entrée/sortie de texte,Binary I/O,,Aperçu<2>
@anchor{library/io text-i-o}@anchor{2b95}
@subsubsection Entrée/sortie de texte


Text I/O expects and produces @ref{435,,str} objects.  This means that whenever
the backing store is natively made of bytes (such as in the case of a file),
encoding and decoding of data is made transparently as well as optional
translation of platform-specific newline characters.

The easiest way to create a text stream is with @ref{505,,open()}, optionally
specifying an encoding:

@example
f = open("myfile.txt", "r", encoding="utf-8")
@end example

Les flux de texte en mémoire sont également disponible sous forme d'objets @ref{f12,,StringIO} :

@example
f = io.StringIO("some initial text data")
@end example

L'API de flux textuel est décrite en détail dans la documentation de la classe @ref{680,,TextIOBase}.

@node Binary I/O,Raw I/O,Entrée/sortie de texte,Aperçu<2>
@anchor{library/io binary-i-o}@anchor{2b96}
@subsubsection Binary I/O


Binary I/O (also called `buffered I/O') expects
@ref{d1b,,bytes-like objects} and produces @ref{1bd,,bytes}
objects.  No encoding, decoding, or newline translation is performed.  This
category of streams can be used for all kinds of non-text data, and also when
manual control over the handling of text data is desired.

The easiest way to create a binary stream is with @ref{505,,open()} with @code{'b'} in
the mode string:

@example
f = open("myfile.jpg", "rb")
@end example

Les flux de texte en mémoire sont également disponible sous forme d'objets @ref{e8d,,BytesIO} :

@example
f = io.BytesIO(b"some initial binary data: \x00\x01")
@end example

L'API du flux binaire est décrite en détail dans la documentation de la classe @ref{67f,,BufferedIOBase}.

D'autres bibliothèques peuvent fournir des moyens supplémentaires pour créer des flux de texte ou flux binaire. Voir la méthode @ref{117d,,socket.socket.makefile()} par exemple.

@node Raw I/O,,Binary I/O,Aperçu<2>
@anchor{library/io raw-i-o}@anchor{2b97}
@subsubsection Raw I/O


Raw I/O (also called `unbuffered I/O') is generally used as a low-level
building-block for binary and text streams; it is rarely useful to directly
manipulate a raw stream from user code.  Nevertheless, you can create a raw
stream by opening a file in binary mode with buffering disabled:

@example
f = open("myfile.jpg", "rb", buffering=0)
@end example

The raw stream API is described in detail in the docs of @ref{10b2,,RawIOBase}.

@node Encodage de texte,Interface de haut niveau du module,Aperçu<2>,io --- Core tools for working with streams
@anchor{library/io io-text-encoding}@anchor{7a7}@anchor{library/io text-encoding}@anchor{2b98}
@subsubsection Encodage de texte


The default encoding of @ref{7a5,,TextIOWrapper} and @ref{505,,open()} is
locale-specific (@ref{2db,,locale.getencoding()}).

However, many developers forget to specify the encoding when opening text files
encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc...) since most Unix
platforms use UTF-8 locale by default. This causes bugs because the locale
encoding is not UTF-8 for most Windows users. For example:

@example
# May not work on Windows when non-ASCII characters in the file.
with open("README.md") as f:
    long_description = f.read()
@end example

Accordingly, it is highly recommended that you specify the encoding
explicitly when opening text files. If you want to use UTF-8, pass
@code{encoding="utf-8"}. To use the current locale encoding,
@code{encoding="locale"} is supported since Python 3.10.


@subsubheading Voir aussi



@table @asis

@item @ref{641,,Le mode UTF-8 de Python}

Le mode UTF-8 de Python peut être utilisé pour changer l'encodage par défaut en UTF-8 à partir d'un encodage local spécifique.

@geindex Python Enhancement Proposals; PEP 686

@item PEP 686@footnote{https://peps.python.org/pep-0686/}

@ref{641,,Le mode UTF-8 de Python} sera par mis par défaut sur Python 3.15.
@end table


@menu
* Opt-in EncodingWarning:: 

@end menu

@node Opt-in EncodingWarning,,,Encodage de texte
@anchor{library/io io-encoding-warning}@anchor{1ce1}@anchor{library/io opt-in-encodingwarning}@anchor{2b99}
@subsubsection Opt-in EncodingWarning



Ajouté dans la version 3.10: See 
@geindex Python Enhancement Proposals; PEP 597
PEP 597@footnote{https://peps.python.org/pep-0597/} for more details.


To find where the default locale encoding is used, you can enable
the @ref{175,,-X warn_default_encoding} command line option or set the
@geindex PYTHONWARNDEFAULTENCODING
@geindex variable d'environnement; PYTHONWARNDEFAULTENCODING
@ref{7a6,,PYTHONWARNDEFAULTENCODING} environment variable, which will
emit an @ref{1cc9,,EncodingWarning} when the default encoding is used.

If you are providing an API that uses @ref{505,,open()} or
@ref{7a5,,TextIOWrapper} and passes @code{encoding=None} as a parameter, you
can use @ref{1650,,text_encoding()} so that callers of the API will emit an
@ref{1cc9,,EncodingWarning} if they don't pass an @code{encoding}. However,
please consider using UTF-8 by default (i.e. @code{encoding="utf-8"}) for
new APIs.

@node Interface de haut niveau du module,Class hierarchy,Encodage de texte,io --- Core tools for working with streams
@anchor{library/io high-level-module-interface}@anchor{2b9a}
@subsubsection Interface de haut niveau du module


@geindex DEFAULT_BUFFER_SIZE (dans le module io)
@anchor{library/io io DEFAULT_BUFFER_SIZE}@anchor{1651}
@deffn {Données} io.DEFAULT_BUFFER_SIZE

An int containing the default buffer size used by the module's buffered I/O
classes.  @ref{505,,open()} uses the file's blksize (as obtained by
@ref{48a,,os.stat()}) if possible.
@end deffn

@geindex open() (dans le module io)
@anchor{library/io io open}@anchor{506}
@deffn {Fonction} io.open (file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

This is an alias for the builtin @ref{505,,open()} function.


This function raises an @ref{1848,,auditing event} @code{open} with
arguments `path', `mode' and `flags'. The `mode' and `flags'
arguments may have been modified or inferred from the original call.

@end deffn

@geindex open_code() (dans le module io)
@anchor{library/io io open_code}@anchor{16b2}
@deffn {Fonction} io.open_code (path)

Opens the provided file with mode @code{'rb'}. This function should be used
when the intent is to treat the contents as executable code.

`path' should be a @ref{435,,str} and an absolute path.

The behavior of this function may be overridden by an earlier call to the
@ref{16b4,,PyFile_SetOpenCodeHook()}. However, assuming that `path' is a
@ref{435,,str} and an absolute path, @code{open_code(path)} should always behave
the same as @code{open(path, 'rb')}. Overriding the behavior is intended for
additional validation or preprocessing of the file.


Ajouté dans la version 3.8.

@end deffn

@geindex text_encoding() (dans le module io)
@anchor{library/io io text_encoding}@anchor{1650}
@deffn {Fonction} io.text_encoding (encoding, stacklevel=2, /)

This is a helper function for callables that use @ref{505,,open()} or
@ref{7a5,,TextIOWrapper} and have an @code{encoding=None} parameter.

This function returns `encoding' if it is not @code{None}.
Otherwise, it returns @code{"locale"} or @code{"utf-8"} depending on
@ref{641,,UTF-8 Mode}.

This function emits an @ref{1cc9,,EncodingWarning} if
@ref{677,,sys.flags.warn_default_encoding} is true and `encoding'
is @code{None}. `stacklevel' specifies where the warning is emitted.
For example:

@example
def read_text(path, encoding=None):
    encoding = io.text_encoding(encoding)  # stacklevel=2
    with open(path, encoding) as f:
        return f.read()
@end example

In this example, an @ref{1cc9,,EncodingWarning} is emitted for the caller of
@code{read_text()}.

Voir @ref{7a7,,Encodage de texte} pour plus d'informations.


Ajouté dans la version 3.10.



Modifié dans la version 3.11: @ref{1650,,text_encoding()} returns "utf-8" when UTF-8 mode is enabled and
`encoding' is @code{None}.

@end deffn

@geindex BlockingIOError
@anchor{library/io io BlockingIOError}@anchor{2b9b}
@deffn {Exception} io.BlockingIOError

This is a compatibility alias for the builtin @ref{1040,,BlockingIOError}
exception.
@end deffn

@geindex UnsupportedOperation
@anchor{library/io io UnsupportedOperation}@anchor{1924}
@deffn {Exception} io.UnsupportedOperation

An exception inheriting @ref{40d,,OSError} and @ref{1ff,,ValueError} that is raised
when an unsupported operation is called on a stream.
@end deffn


@subsubheading Voir aussi



@table @asis

@item @ref{d8,,sys}

contains the standard IO streams: @ref{527,,sys.stdin}, @ref{ac4,,sys.stdout},
and @ref{926,,sys.stderr}.
@end table


@node Class hierarchy,Performances<3>,Interface de haut niveau du module,io --- Core tools for working with streams
@anchor{library/io class-hierarchy}@anchor{2b9c}
@subsubsection Class hierarchy


The implementation of I/O streams is organized as a hierarchy of classes.  First
@ref{1193,,abstract base classes} (ABCs), which are used to
specify the various categories of streams, then concrete classes providing the
standard stream implementations.

@cartouche
@quotation Note 
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes.  For
example, @ref{67f,,BufferedIOBase} provides unoptimized implementations of
@code{readinto()} and @code{readline()}.
@end quotation
@end cartouche

At the top of the I/O hierarchy is the abstract base class @ref{1f2,,IOBase}.  It
defines the basic interface to a stream.  Note, however, that there is no
separation between reading and writing to streams; implementations are allowed
to raise @ref{1924,,UnsupportedOperation} if they do not support a given operation.

The @ref{10b2,,RawIOBase} ABC extends @ref{1f2,,IOBase}.  It deals with the reading
and writing of bytes to a stream.  @ref{12ee,,FileIO} subclasses @ref{10b2,,RawIOBase}
to provide an interface to files in the machine's file system.

The @ref{67f,,BufferedIOBase} ABC extends @ref{1f2,,IOBase}.  It deals with
buffering on a raw binary stream (@ref{10b2,,RawIOBase}).  Its subclasses,
@ref{2103,,BufferedWriter}, @ref{11eb,,BufferedReader}, and @ref{2b9d,,BufferedRWPair}
buffer raw binary streams that are writable, readable, and both readable and writable,
respectively. @ref{2104,,BufferedRandom} provides a buffered interface to seekable streams.
Another @ref{67f,,BufferedIOBase} subclass, @ref{e8d,,BytesIO}, is a stream of
in-memory bytes.

The @ref{680,,TextIOBase} ABC extends @ref{1f2,,IOBase}.  It deals with
streams whose bytes represent text, and handles encoding and decoding to and
from strings.  @ref{7a5,,TextIOWrapper}, which extends @ref{680,,TextIOBase}, is a buffered text
interface to a buffered raw stream (@ref{67f,,BufferedIOBase}).  Finally,
@ref{f12,,StringIO} is an in-memory stream for text.

Argument names are not part of the specification, and only the arguments of
@ref{505,,open()} are intended to be used as keyword arguments.

The following table summarizes the ABCs provided by the @ref{7e,,io} module:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ABC

@tab

Inherits

@tab

Stub Methods

@tab

Méthodes et propriétés de Mixin

@item

@ref{1f2,,IOBase}

@tab

@tab

@code{fileno}, @code{seek}, et @code{truncate}

@tab

@code{close}, @code{closed}, @code{__enter__},
@code{__exit__}, @code{flush}, @code{isatty}, @code{__iter__},
@code{__next__}, @code{readable}, @code{readline},
@code{readlines}, @code{seekable}, @code{tell},
@code{writable}, and @code{writelines}

@item

@ref{10b2,,RawIOBase}

@tab

@ref{1f2,,IOBase}

@tab

@code{readinto} et @code{write}

@tab

Inherited @ref{1f2,,IOBase} methods, @code{read},
and @code{readall}

@item

@ref{67f,,BufferedIOBase}

@tab

@ref{1f2,,IOBase}

@tab

@code{detach}, @code{read}, @code{read1}, et @code{write}

@tab

Inherited @ref{1f2,,IOBase} methods, @code{readinto},
and @code{readinto1}

@item

@ref{680,,TextIOBase}

@tab

@ref{1f2,,IOBase}

@tab

@code{detach}, @code{read}, @code{readline}, et @code{write}

@tab

Inherited @ref{1f2,,IOBase} methods, @code{encoding},
@code{errors}, and @code{newlines}

@end multitable


@menu
* I/O Base Classes:: 
* Raw File I/O:: 
* Buffered Streams:: 
* Entrée/sortie de texte: Entrée/sortie de texte<2>. 

@end menu

@node I/O Base Classes,Raw File I/O,,Class hierarchy
@anchor{library/io i-o-base-classes}@anchor{2b9e}
@subsubsection I/O Base Classes


@geindex IOBase (classe dans io)
@anchor{library/io io IOBase}@anchor{1f2}
@deffn {Classe} io.IOBase

The abstract base class for all I/O classes.

This class provides empty abstract implementations for many methods
that derived classes can override selectively; the default
implementations represent a file that cannot be read, written or
seeked.

Even though @ref{1f2,,IOBase} does not declare @code{read()}
or @code{write()} because their signatures will vary, implementations and
clients should consider those methods part of the interface.  Also,
implementations may raise a @ref{1ff,,ValueError} (or @ref{1924,,UnsupportedOperation})
when operations they do not support are called.

The basic type used for binary data read from or written to a file is
@ref{1bd,,bytes}.  Other @ref{d1b,,bytes-like objects} are
accepted as method arguments too.  Text I/O classes work with @ref{435,,str} data.

Note that calling any method (even inquiries) on a closed stream is
undefined.  Implementations may raise @ref{1ff,,ValueError} in this case.

@ref{1f2,,IOBase} (and its subclasses) supports the iterator protocol, meaning
that an @ref{1f2,,IOBase} object can be iterated over yielding the lines in a
stream.  Lines are defined slightly differently depending on whether the
stream is a binary stream (yielding bytes), or a text stream (yielding
character strings).  See @ref{1307,,readline()} below.

@ref{1f2,,IOBase} is also a context manager and therefore supports the
@ref{5bc,,with} statement.  In this example, `file' is closed after the
@code{with} statement's suite is finished---even if an exception occurs:

@example
with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')
@end example

@ref{1f2,,IOBase} provides these data attributes and methods:

@geindex close() (méthode io.IOBase)
@anchor{library/io io IOBase close}@anchor{1f3}
@deffn {Méthode} close ()

Flush and close this stream. This method has no effect if the file is
already closed. Once the file is closed, any operation on the file
(e.g. reading or writing) will raise a @ref{1ff,,ValueError}.

As a convenience, it is allowed to call this method more than once;
only the first call, however, will have an effect.
@end deffn

@geindex closed (attribut io.IOBase)
@anchor{library/io io IOBase closed}@anchor{19ba}
@deffn {Attribut} closed

@code{True} if the stream is closed.
@end deffn

@geindex fileno() (méthode io.IOBase)
@anchor{library/io io IOBase fileno}@anchor{27cf}
@deffn {Méthode} fileno ()

Return the underlying file descriptor (an integer) of the stream if it
exists.  An @ref{40d,,OSError} is raised if the IO object does not use a file
descriptor.
@end deffn

@geindex flush() (méthode io.IOBase)
@anchor{library/io io IOBase flush}@anchor{2b9f}
@deffn {Méthode} flush ()

Flush the write buffers of the stream if applicable.  This does nothing
for read-only and non-blocking streams.
@end deffn

@geindex isatty() (méthode io.IOBase)
@anchor{library/io io IOBase isatty}@anchor{1c10}
@deffn {Méthode} isatty ()

Return @code{True} if the stream is interactive (i.e., connected to
a terminal/tty device).
@end deffn

@geindex readable() (méthode io.IOBase)
@anchor{library/io io IOBase readable}@anchor{2ba0}
@deffn {Méthode} readable ()

Return @code{True} if the stream can be read from.
If @code{False}, @code{read()} will raise @ref{40d,,OSError}.
@end deffn

@geindex readline() (méthode io.IOBase)
@anchor{library/io io IOBase readline}@anchor{1307}
@deffn {Méthode} readline (size=-1, /)

Read and return one line from the stream.  If `size' is specified, at
most `size' bytes will be read.

The line terminator is always @code{b'\n'} for binary files; for text files,
the `newline' argument to @ref{505,,open()} can be used to select the line
terminator(s) recognized.
@end deffn

@geindex readlines() (méthode io.IOBase)
@anchor{library/io io IOBase readlines}@anchor{22ba}
@deffn {Méthode} readlines (hint=-1, /)

Read and return a list of lines from the stream.  `hint' can be specified
to control the number of lines read: no more lines will be read if the
total size (in bytes/characters) of all lines so far exceeds `hint'.

`hint' values of @code{0} or less, as well as @code{None}, are treated as no
hint.

Note that it's already possible to iterate on file objects using @code{for
line in file: ...} without calling @code{file.readlines()}.
@end deffn

@geindex seek() (méthode io.IOBase)
@anchor{library/io io IOBase seek}@anchor{126a}
@deffn {Méthode} seek (offset, whence=os.SEEK_SET, /)

Change the stream position to the given byte `offset',
interpreted relative to the position indicated by `whence',
and return the new absolute position.
Values for `whence' are:


@itemize *

@item 
@ref{126b,,os.SEEK_SET} or @code{0} -- start of the stream (the default);
`offset' should be zero or positive

@item 
@ref{126c,,os.SEEK_CUR} or @code{1} -- current stream position;
`offset' may be negative

@item 
@ref{126d,,os.SEEK_END} or @code{2} -- end of the stream;
`offset' is usually negative
@end itemize


Ajouté dans la version 3.1: The @code{SEEK_*} constants.



Ajouté dans la version 3.3: Some operating systems could support additional values, like
@ref{2aca,,os.SEEK_HOLE} or @ref{2acb,,os.SEEK_DATA}. The valid values
for a file could depend on it being open in text or binary mode.

@end deffn

@geindex seekable() (méthode io.IOBase)
@anchor{library/io io IOBase seekable}@anchor{2ba1}
@deffn {Méthode} seekable ()

Return @code{True} if the stream supports random access.  If @code{False},
@ref{126a,,seek()}, @ref{2930,,tell()} and @ref{12ef,,truncate()} will raise @ref{40d,,OSError}.
@end deffn

@geindex tell() (méthode io.IOBase)
@anchor{library/io io IOBase tell}@anchor{2930}
@deffn {Méthode} tell ()

Return the current stream position.
@end deffn

@geindex truncate() (méthode io.IOBase)
@anchor{library/io io IOBase truncate}@anchor{12ef}
@deffn {Méthode} truncate (size=None, /)

Resize the stream to the given `size' in bytes (or the current position
if `size' is not specified).  The current stream position isn't changed.
This resizing can extend or reduce the current file size.  In case of
extension, the contents of the new file area depend on the platform
(on most systems, additional bytes are zero-filled).  The new file size
is returned.


Modifié dans la version 3.5: Windows will now zero-fill files when extending.

@end deffn

@geindex writable() (méthode io.IOBase)
@anchor{library/io io IOBase writable}@anchor{2ba2}
@deffn {Méthode} writable ()

Return @code{True} if the stream supports writing.  If @code{False},
@code{write()} and @ref{12ef,,truncate()} will raise @ref{40d,,OSError}.
@end deffn

@geindex writelines() (méthode io.IOBase)
@anchor{library/io io IOBase writelines}@anchor{22bb}
@deffn {Méthode} writelines (lines, /)

Write a list of lines to the stream.  Line separators are not added, so it
is usual for each of the lines provided to have a line separator at the
end.
@end deffn

@geindex __del__() (méthode io.IOBase)
@anchor{library/io io IOBase __del__}@anchor{2ba3}
@deffn {Méthode} __del__ ()

Prepare for object destruction. @ref{1f2,,IOBase} provides a default
implementation of this method that calls the instance's
@ref{1f3,,close()} method.
@end deffn
@end deffn

@geindex RawIOBase (classe dans io)
@anchor{library/io io RawIOBase}@anchor{10b2}
@deffn {Classe} io.RawIOBase

Base class for raw binary streams.  It inherits from @ref{1f2,,IOBase}.

Raw binary streams typically provide low-level access to an underlying OS
device or API, and do not try to encapsulate it in high-level primitives
(this functionality is done at a higher-level in buffered binary streams and text streams, described later
in this page).

@ref{10b2,,RawIOBase} provides these methods in addition to those from
@ref{1f2,,IOBase}:

@geindex read() (méthode io.RawIOBase)
@anchor{library/io io RawIOBase read}@anchor{e09}
@deffn {Méthode} read (size=-1, /)

Read up to `size' bytes from the object and return them.  As a convenience,
if `size' is unspecified or -1, all bytes until EOF are returned.
Otherwise, only one system call is ever made.  Fewer than `size' bytes may
be returned if the operating system call returns fewer than `size' bytes.

If 0 bytes are returned, and `size' was not 0, this indicates end of file.
If the object is in non-blocking mode and no bytes are available,
@code{None} is returned.

The default implementation defers to @ref{2ba4,,readall()} and
@ref{e0a,,readinto()}.
@end deffn

@geindex readall() (méthode io.RawIOBase)
@anchor{library/io io RawIOBase readall}@anchor{2ba4}
@deffn {Méthode} readall ()

Read and return all the bytes from the stream until EOF, using multiple
calls to the stream if necessary.
@end deffn

@geindex readinto() (méthode io.RawIOBase)
@anchor{library/io io RawIOBase readinto}@anchor{e0a}
@deffn {Méthode} readinto (b, /)

Read bytes into a pre-allocated, writable
@ref{d1b,,bytes-like object} `b', and return the
number of bytes read.  For example, `b' might be a @ref{528,,bytearray}.
If the object is in non-blocking mode and no bytes
are available, @code{None} is returned.
@end deffn

@geindex write() (méthode io.RawIOBase)
@anchor{library/io io RawIOBase write}@anchor{296f}
@deffn {Méthode} write (b, /)

Write the given @ref{d1b,,bytes-like object}, `b', to the
underlying raw stream, and return the number of
bytes written.  This can be less than the length of `b' in
bytes, depending on specifics of the underlying raw
stream, and especially if it is in non-blocking mode.  @code{None} is
returned if the raw stream is set not to block and no single byte could
be readily written to it.  The caller may release or mutate `b' after
this method returns, so the implementation should only access `b'
during the method call.
@end deffn
@end deffn

@geindex BufferedIOBase (classe dans io)
@anchor{library/io io BufferedIOBase}@anchor{67f}
@deffn {Classe} io.BufferedIOBase

Base class for binary streams that support some kind of buffering.
It inherits from @ref{1f2,,IOBase}.

The main difference with @ref{10b2,,RawIOBase} is that methods @ref{1306,,read()},
@ref{2ba5,,readinto()} and @ref{cc9,,write()} will try (respectively) to read as much
input as requested or to consume all given output, at the expense of
making perhaps more than one system call.

In addition, those methods can raise @ref{1040,,BlockingIOError} if the
underlying raw stream is in non-blocking mode and cannot take or give
enough data; unlike their @ref{10b2,,RawIOBase} counterparts, they will
never return @code{None}.

Besides, the @ref{1306,,read()} method does not have a default
implementation that defers to @ref{2ba5,,readinto()}.

A typical @ref{67f,,BufferedIOBase} implementation should not inherit from a
@ref{10b2,,RawIOBase} implementation, but wrap one, like
@ref{2103,,BufferedWriter} and @ref{11eb,,BufferedReader} do.

@ref{67f,,BufferedIOBase} provides or overrides these data attributes and
methods in addition to those from @ref{1f2,,IOBase}:

@geindex raw (attribut io.BufferedIOBase)
@anchor{library/io io BufferedIOBase raw}@anchor{2ba6}
@deffn {Attribut} raw

The underlying raw stream (a @ref{10b2,,RawIOBase} instance) that
@ref{67f,,BufferedIOBase} deals with.  This is not part of the
@ref{67f,,BufferedIOBase} API and may not exist on some implementations.
@end deffn

@geindex detach() (méthode io.BufferedIOBase)
@anchor{library/io io BufferedIOBase detach}@anchor{28f7}
@deffn {Méthode} detach ()

Sépare le flux brut sous-jacent du tampon et le renvoie.

After the raw stream has been detached, the buffer is in an unusable
state.

Some buffers, like @ref{e8d,,BytesIO}, do not have the concept of a single
raw stream to return from this method.  They raise
@ref{1924,,UnsupportedOperation}.


Ajouté dans la version 3.1.

@end deffn

@geindex read() (méthode io.BufferedIOBase)
@anchor{library/io io BufferedIOBase read}@anchor{1306}
@deffn {Méthode} read (size=-1, /)

Read and return up to `size' bytes.  If the argument is omitted, @code{None},
or negative, data is read and returned until EOF is reached.  An empty
@ref{1bd,,bytes} object is returned if the stream is already at EOF.

If the argument is positive, and the underlying raw stream is not
interactive, multiple raw reads may be issued to satisfy the byte count
(unless EOF is reached first).  But for interactive raw streams, at most
one raw read will be issued, and a short result does not imply that EOF is
imminent.

A @ref{1040,,BlockingIOError} is raised if the underlying raw stream is in
non blocking-mode, and has no data available at the moment.
@end deffn

@geindex read1() (méthode io.BufferedIOBase)
@anchor{library/io io BufferedIOBase read1}@anchor{28e7}
@deffn {Méthode} read1 (size=-1, /)

Read and return up to `size' bytes, with at most one call to the
underlying raw stream's @ref{e09,,read()} (or
@ref{e0a,,readinto()}) method.  This can be useful if you are
implementing your own buffering on top of a @ref{67f,,BufferedIOBase}
object.

If `size' is @code{-1} (the default), an arbitrary number of bytes are
returned (more than zero unless EOF is reached).
@end deffn

@geindex readinto() (méthode io.BufferedIOBase)
@anchor{library/io io BufferedIOBase readinto}@anchor{2ba5}
@deffn {Méthode} readinto (b, /)

Read bytes into a pre-allocated, writable
@ref{d1b,,bytes-like object} `b' and return the number of bytes read.
For example, `b' might be a @ref{528,,bytearray}.

Like @ref{1306,,read()}, multiple reads may be issued to the underlying raw
stream, unless the latter is interactive.

A @ref{1040,,BlockingIOError} is raised if the underlying raw stream is in non
blocking-mode, and has no data available at the moment.
@end deffn

@geindex readinto1() (méthode io.BufferedIOBase)
@anchor{library/io io BufferedIOBase readinto1}@anchor{e08}
@deffn {Méthode} readinto1 (b, /)

Read bytes into a pre-allocated, writable
@ref{d1b,,bytes-like object} `b', using at most one call to
the underlying raw stream's @ref{e09,,read()} (or
@ref{e0a,,readinto()}) method. Return the number of bytes read.

A @ref{1040,,BlockingIOError} is raised if the underlying raw stream is in non
blocking-mode, and has no data available at the moment.


Ajouté dans la version 3.5.

@end deffn

@geindex write() (méthode io.BufferedIOBase)
@anchor{library/io io BufferedIOBase write}@anchor{cc9}
@deffn {Méthode} write (b, /)

Write the given @ref{d1b,,bytes-like object}, `b', and return the number
of bytes written (always equal to the length of `b' in bytes, since if
the write fails an @ref{40d,,OSError} will be raised).  Depending on the
actual implementation, these bytes may be readily written to the
underlying stream, or held in a buffer for performance and latency
reasons.

When in non-blocking mode, a @ref{1040,,BlockingIOError} is raised if the
data needed to be written to the raw stream but it couldn't accept
all the data without blocking.

The caller may release or mutate `b' after this method returns,
so the implementation should only access `b' during the method call.
@end deffn
@end deffn

@node Raw File I/O,Buffered Streams,I/O Base Classes,Class hierarchy
@anchor{library/io raw-file-i-o}@anchor{2ba7}
@subsubsection Raw File I/O


@geindex FileIO (classe dans io)
@anchor{library/io io FileIO}@anchor{12ee}
@deffn {Classe} io.FileIO (name, mode='r', closefd=True, opener=None)

A raw binary stream representing an OS-level file containing bytes data.  It
inherits from @ref{10b2,,RawIOBase}.

The `name' can be one of two things:


@itemize *

@item 
a character string or @ref{1bd,,bytes} object representing the path to the
file which will be opened. In this case closefd must be @code{True} (the default)
otherwise an error will be raised.

@item 
an integer representing the number of an existing OS-level file descriptor
to which the resulting @ref{12ee,,FileIO} object will give access. When the
FileIO object is closed this fd will be closed as well, unless `closefd'
is set to @code{False}.
@end itemize

The `mode' can be @code{'r'}, @code{'w'}, @code{'x'} or @code{'a'} for reading
(default), writing, exclusive creation or appending. The file will be
created if it doesn't exist when opened for writing or appending; it will be
truncated when opened for writing. @ref{1009,,FileExistsError} will be raised if
it already exists when opened for creating. Opening a file for creating
implies writing, so this mode behaves in a similar way to @code{'w'}. Add a
@code{'+'} to the mode to allow simultaneous reading and writing.

The @ref{e09,,read()} (when called with a positive argument),
@ref{e0a,,readinto()} and @ref{296f,,write()} methods on this
class will only make one system call.

Un `opener' personnalisé peut être utilisé en fournissant un appelable à `opener'. Le descripteur de fichier de cet objet fichier sera alors obtenu en appelant `opener' avec (`file', `flags'). `opener' doit donner un descripteur de fichier ouvert (fournir @ref{d7f,,os.open} en temps qu'`opener' aura le même effet que donner @code{None}).

Il n'est @ref{ee4,,pas possible d'hériter du fichier} nouvellement créé.

See the @ref{505,,open()} built-in function for examples on using the `opener'
parameter.


Modifié dans la version 3.3: The `opener' parameter was added.
The @code{'x'} mode was added.



Modifié dans la version 3.4: Il n'est plus possible d'hériter de `file'.


@ref{12ee,,FileIO} provides these data attributes in addition to those from
@ref{10b2,,RawIOBase} and @ref{1f2,,IOBase}:

@geindex mode (attribut io.FileIO)
@anchor{library/io io FileIO mode}@anchor{2ba8}
@deffn {Attribut} mode

The mode as given in the constructor.
@end deffn

@geindex name (attribut io.FileIO)
@anchor{library/io io FileIO name}@anchor{2901}
@deffn {Attribut} name

Le nom du fichier. C'est le descripteur du fichier lorsqu'aucun nom n'est donné dans le constructeur.
@end deffn
@end deffn

@node Buffered Streams,Entrée/sortie de texte<2>,Raw File I/O,Class hierarchy
@anchor{library/io buffered-streams}@anchor{2ba9}
@subsubsection Buffered Streams


Buffered I/O streams provide a higher-level interface to an I/O device
than raw I/O does.

@geindex BytesIO (classe dans io)
@anchor{library/io io BytesIO}@anchor{e8d}
@deffn {Classe} io.BytesIO (initial_bytes=b'@w{'})

A binary stream using an in-memory bytes buffer.  It inherits from
@ref{67f,,BufferedIOBase}.  The buffer is discarded when the
@ref{1f3,,close()} method is called.

The optional argument `initial_bytes' is a @ref{d1b,,bytes-like object} that
contains initial data.

@ref{e8d,,BytesIO} provides or overrides these methods in addition to those
from @ref{67f,,BufferedIOBase} and @ref{1f2,,IOBase}:

@geindex getbuffer() (méthode io.BytesIO)
@anchor{library/io io BytesIO getbuffer}@anchor{11ce}
@deffn {Méthode} getbuffer ()

Return a readable and writable view over the contents of the buffer
without copying them.  Also, mutating the view will transparently
update the contents of the buffer:

@example
>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'
@end example

@cartouche
@quotation Note 
As long as the view exists, the @ref{e8d,,BytesIO} object cannot be
resized or closed.
@end quotation
@end cartouche


Ajouté dans la version 3.2.

@end deffn

@geindex getvalue() (méthode io.BytesIO)
@anchor{library/io io BytesIO getvalue}@anchor{28e5}
@deffn {Méthode} getvalue ()

Return @ref{1bd,,bytes} containing the entire contents of the buffer.
@end deffn

@geindex read1() (méthode io.BytesIO)
@anchor{library/io io BytesIO read1}@anchor{2baa}
@deffn {Méthode} read1 (size=-1, /)

In @ref{e8d,,BytesIO}, this is the same as @ref{1306,,read()}.


Modifié dans la version 3.7: The `size' argument is now optional.

@end deffn

@geindex readinto1() (méthode io.BytesIO)
@anchor{library/io io BytesIO readinto1}@anchor{2bab}
@deffn {Méthode} readinto1 (b, /)

In @ref{e8d,,BytesIO}, this is the same as @ref{2ba5,,readinto()}.


Ajouté dans la version 3.5.

@end deffn
@end deffn

@geindex BufferedReader (classe dans io)
@anchor{library/io io BufferedReader}@anchor{11eb}
@deffn {Classe} io.BufferedReader (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a readable, non
seekable @ref{10b2,,RawIOBase} raw binary stream.  It inherits from
@ref{67f,,BufferedIOBase}.

When reading data from this object, a larger amount of data may be
requested from the underlying raw stream, and kept in an internal buffer.
The buffered data can then be returned directly on subsequent reads.

The constructor creates a @ref{11eb,,BufferedReader} for the given readable
`raw' stream and `buffer_size'.  If `buffer_size' is omitted,
@ref{1651,,DEFAULT_BUFFER_SIZE} is used.

@ref{11eb,,BufferedReader} provides or overrides these methods in addition to
those from @ref{67f,,BufferedIOBase} and @ref{1f2,,IOBase}:

@geindex peek() (méthode io.BufferedReader)
@anchor{library/io io BufferedReader peek}@anchor{2bac}
@deffn {Méthode} peek (size=0, /)

Return bytes from the stream without advancing the position.  At most one
single read on the raw stream is done to satisfy the call. The number of
bytes returned may be less or more than requested.
@end deffn

@geindex read() (méthode io.BufferedReader)
@anchor{library/io io BufferedReader read}@anchor{2bad}
@deffn {Méthode} read (size=-1, /)

Read and return `size' bytes, or if `size' is not given or negative, until
EOF or if the read call would block in non-blocking mode.
@end deffn

@geindex read1() (méthode io.BufferedReader)
@anchor{library/io io BufferedReader read1}@anchor{2bae}
@deffn {Méthode} read1 (size=-1, /)

Read and return up to `size' bytes with only one call on the raw stream.
If at least one byte is buffered, only buffered bytes are returned.
Otherwise, one raw stream read call is made.


Modifié dans la version 3.7: The `size' argument is now optional.

@end deffn
@end deffn

@geindex BufferedWriter (classe dans io)
@anchor{library/io io BufferedWriter}@anchor{2103}
@deffn {Classe} io.BufferedWriter (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a writeable, non
seekable @ref{10b2,,RawIOBase} raw binary stream.  It inherits from
@ref{67f,,BufferedIOBase}.

When writing to this object, data is normally placed into an internal
buffer.  The buffer will be written out to the underlying @ref{10b2,,RawIOBase}
object under various conditions, including:


@itemize *

@item 
when the buffer gets too small for all pending data;

@item 
when @ref{2baf,,flush()} is called;

@item 
when a @ref{126a,,seek()} is requested (for @ref{2104,,BufferedRandom} objects);

@item 
when the @ref{2103,,BufferedWriter} object is closed or destroyed.
@end itemize

The constructor creates a @ref{2103,,BufferedWriter} for the given writeable
`raw' stream.  If the `buffer_size' is not given, it defaults to
@ref{1651,,DEFAULT_BUFFER_SIZE}.

@ref{2103,,BufferedWriter} provides or overrides these methods in addition to
those from @ref{67f,,BufferedIOBase} and @ref{1f2,,IOBase}:

@geindex flush() (méthode io.BufferedWriter)
@anchor{library/io io BufferedWriter flush}@anchor{2baf}
@deffn {Méthode} flush ()

Force bytes held in the buffer into the raw stream.  A
@ref{1040,,BlockingIOError} should be raised if the raw stream blocks.
@end deffn

@geindex write() (méthode io.BufferedWriter)
@anchor{library/io io BufferedWriter write}@anchor{2bb0}
@deffn {Méthode} write (b, /)

Write the @ref{d1b,,bytes-like object}, `b', and return the
number of bytes written.  When in non-blocking mode, a
@ref{1040,,BlockingIOError} is raised if the buffer needs to be written out but
the raw stream blocks.
@end deffn
@end deffn

@geindex BufferedRandom (classe dans io)
@anchor{library/io io BufferedRandom}@anchor{2104}
@deffn {Classe} io.BufferedRandom (raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream providing higher-level access to a seekable
@ref{10b2,,RawIOBase} raw binary stream.  It inherits from @ref{11eb,,BufferedReader}
and @ref{2103,,BufferedWriter}.

The constructor creates a reader and writer for a seekable raw stream, given
in the first argument.  If the `buffer_size' is omitted it defaults to
@ref{1651,,DEFAULT_BUFFER_SIZE}.

@ref{2104,,BufferedRandom} is capable of anything @ref{11eb,,BufferedReader} or
@ref{2103,,BufferedWriter} can do.  In addition, @ref{126a,,seek()} and
@ref{2930,,tell()} are guaranteed to be implemented.
@end deffn

@geindex BufferedRWPair (classe dans io)
@anchor{library/io io BufferedRWPair}@anchor{2b9d}
@deffn {Classe} io.BufferedRWPair (reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)

A buffered binary stream providing higher-level access to two non seekable
@ref{10b2,,RawIOBase} raw binary streams---one readable, the other writeable.
It inherits from @ref{67f,,BufferedIOBase}.

`reader' and `writer' are @ref{10b2,,RawIOBase} objects that are readable and
writeable respectively.  If the `buffer_size' is omitted it defaults to
@ref{1651,,DEFAULT_BUFFER_SIZE}.

@ref{2b9d,,BufferedRWPair} implements all of @ref{67f,,BufferedIOBase}'s methods
except for @ref{28f7,,detach()}, which raises
@ref{1924,,UnsupportedOperation}.

@cartouche
@quotation Avertissement 
@ref{2b9d,,BufferedRWPair} does not attempt to synchronize accesses to
its underlying raw streams.  You should not pass it the same object
as reader and writer; use @ref{2104,,BufferedRandom} instead.
@end quotation
@end cartouche
@end deffn

@node Entrée/sortie de texte<2>,,Buffered Streams,Class hierarchy
@anchor{library/io id1}@anchor{2bb1}
@subsubsection Entrée/sortie de texte


@geindex TextIOBase (classe dans io)
@anchor{library/io io TextIOBase}@anchor{680}
@deffn {Classe} io.TextIOBase

Base class for text streams.  This class provides a character and line based
interface to stream I/O.  It inherits from @ref{1f2,,IOBase}.

@ref{680,,TextIOBase} provides or overrides these data attributes and
methods in addition to those from @ref{1f2,,IOBase}:

@geindex encoding (attribut io.TextIOBase)
@anchor{library/io io TextIOBase encoding}@anchor{2bb2}
@deffn {Attribut} encoding

The name of the encoding used to decode the stream's bytes into
strings, and to encode strings into bytes.
@end deffn

@geindex errors (attribut io.TextIOBase)
@anchor{library/io io TextIOBase errors}@anchor{12ed}
@deffn {Attribut} errors

The error setting of the decoder or encoder.
@end deffn

@geindex newlines (attribut io.TextIOBase)
@anchor{library/io io TextIOBase newlines}@anchor{2bb3}
@deffn {Attribut} newlines

A string, a tuple of strings, or @code{None}, indicating the newlines
translated so far.  Depending on the implementation and the initial
constructor flags, this may not be available.
@end deffn

@geindex buffer (attribut io.TextIOBase)
@anchor{library/io io TextIOBase buffer}@anchor{1280}
@deffn {Attribut} buffer

The underlying binary buffer (a @ref{67f,,BufferedIOBase} instance) that
@ref{680,,TextIOBase} deals with.  This is not part of the
@ref{680,,TextIOBase} API and may not exist in some implementations.
@end deffn

@geindex detach() (méthode io.TextIOBase)
@anchor{library/io io TextIOBase detach}@anchor{2bb4}
@deffn {Méthode} detach ()

Separate the underlying binary buffer from the @ref{680,,TextIOBase} and
return it.

After the underlying buffer has been detached, the @ref{680,,TextIOBase} is
in an unusable state.

Some @ref{680,,TextIOBase} implementations, like @ref{f12,,StringIO}, may not
have the concept of an underlying buffer and calling this method will
raise @ref{1924,,UnsupportedOperation}.


Ajouté dans la version 3.1.

@end deffn

@geindex read() (méthode io.TextIOBase)
@anchor{library/io io TextIOBase read}@anchor{1c13}
@deffn {Méthode} read (size=-1, /)

Read and return at most `size' characters from the stream as a single
@ref{435,,str}.  If `size' is negative or @code{None}, reads until EOF.
@end deffn

@geindex readline() (méthode io.TextIOBase)
@anchor{library/io io TextIOBase readline}@anchor{1c4b}
@deffn {Méthode} readline (size=-1, /)

Read until newline or EOF and return a single @ref{435,,str}.  If the stream is
already at EOF, an empty string is returned.

If `size' is specified, at most `size' characters will be read.
@end deffn

@geindex seek() (méthode io.TextIOBase)
@anchor{library/io io TextIOBase seek}@anchor{2bb5}
@deffn {Méthode} seek (offset, whence=SEEK_SET, /)

Change the stream position to the given `offset'.  Behaviour depends on
the `whence' parameter.  The default value for `whence' is
@code{SEEK_SET}.


@itemize *

@item 
@code{SEEK_SET} or @code{0}: seek from the start of the stream
(the default); `offset' must either be a number returned by
@ref{2bb6,,TextIOBase.tell()}, or zero.  Any other `offset' value
produces undefined behaviour.

@item 
@code{SEEK_CUR} or @code{1}: "seek" to the current position;
`offset' must be zero, which is a no-operation (all other values
are unsupported).

@item 
@code{SEEK_END} or @code{2}: seek to the end of the stream;
`offset' must be zero (all other values are unsupported).
@end itemize

Return the new absolute position as an opaque number.


Ajouté dans la version 3.1: The @code{SEEK_*} constants.

@end deffn

@geindex tell() (méthode io.TextIOBase)
@anchor{library/io io TextIOBase tell}@anchor{2bb6}
@deffn {Méthode} tell ()

Return the current stream position as an opaque number.  The number
does not usually represent a number of bytes in the underlying
binary storage.
@end deffn

@geindex write() (méthode io.TextIOBase)
@anchor{library/io io TextIOBase write}@anchor{1c02}
@deffn {Méthode} write (s, /)

Write the string `s' to the stream and return the number of characters
written.
@end deffn
@end deffn

@geindex TextIOWrapper (classe dans io)
@anchor{library/io io TextIOWrapper}@anchor{7a5}
@deffn {Classe} io.TextIOWrapper (buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)

A buffered text stream providing higher-level access to a
@ref{67f,,BufferedIOBase} buffered binary stream.  It inherits from
@ref{680,,TextIOBase}.

`encoding' gives the name of the encoding that the stream will be decoded or
encoded with.  It defaults to @ref{2db,,locale.getencoding()}.
@code{encoding="locale"} can be used to specify the current locale's encoding
explicitly. See @ref{7a7,,Encodage de texte} for more information.

`errors' is an optional string that specifies how encoding and decoding
errors are to be handled.  Pass @code{'strict'} to raise a @ref{1ff,,ValueError}
exception if there is an encoding error (the default of @code{None} has the same
effect), or pass @code{'ignore'} to ignore errors.  (Note that ignoring encoding
errors can lead to data loss.)  @code{'replace'} causes a replacement marker
(such as @code{'?'}) to be inserted where there is malformed data.
@code{'backslashreplace'} causes malformed data to be replaced by a
backslashed escape sequence.  When writing, @code{'xmlcharrefreplace'}
(replace with the appropriate XML character reference)  or @code{'namereplace'}
(replace with @code{\N@{...@}} escape sequences) can be used.  Any other error
handling name that has been registered with
@ref{144d,,codecs.register_error()} is also valid.

@geindex universal newlines;io.TextIOWrapper class

`newline' controls how line endings are handled.  It can be @code{None},
@code{'@w{'}}, @code{'\n'}, @code{'\r'}, and @code{'\r\n'}.  It works as follows:


@itemize *

@item 
When reading input from the stream, if `newline' is @code{None},
@ref{d28,,universal newlines} mode is enabled.  Lines in the input can end in
@code{'\n'}, @code{'\r'}, or @code{'\r\n'}, and these are translated into @code{'\n'}
before being returned to the caller.  If `newline' is @code{'@w{'}}, universal
newlines mode is enabled, but line endings are returned to the caller
untranslated.  If `newline' has any of the other legal values, input lines
are only terminated by the given string, and the line ending is returned to
the caller untranslated.

@item 
Lors de l'écriture, si `newline' est @code{None}, chaque @code{'\n'} est remplacé par le séparateur de lignes par défaut du système @ref{2102,,os.linesep}.  Si `newline' est @code{*} ou @code{'\n'} aucun remplacent n'est effectué. Si `newline' est un autre caractère valide, chaque @code{'\n'} sera remplacé par la chaîne donnée.
@end itemize

If `line_buffering' is @code{True}, @ref{2b9f,,flush()} is implied when a call to
write contains a newline character or a carriage return.

If `write_through' is @code{True}, calls to @ref{cc9,,write()} are guaranteed
not to be buffered: any data written on the @ref{7a5,,TextIOWrapper}
object is immediately handled to its underlying binary `buffer'.


Modifié dans la version 3.3: Le paramètre `write_through' a été ajouté.



Modifié dans la version 3.3: The default `encoding' is now @code{locale.getpreferredencoding(False)}
instead of @code{locale.getpreferredencoding()}. Don't change temporary the
locale encoding using @ref{2da,,locale.setlocale()}, use the current locale
encoding instead of the user preferred encoding.



Modifié dans la version 3.10: The `encoding' argument now supports the @code{"locale"} dummy encoding name.


@ref{7a5,,TextIOWrapper} provides these data attributes and methods in
addition to those from @ref{680,,TextIOBase} and @ref{1f2,,IOBase}:

@geindex line_buffering (attribut io.TextIOWrapper)
@anchor{library/io io TextIOWrapper line_buffering}@anchor{2bb7}
@deffn {Attribut} line_buffering

Whether line buffering is enabled.
@end deffn

@geindex write_through (attribut io.TextIOWrapper)
@anchor{library/io io TextIOWrapper write_through}@anchor{2bb8}
@deffn {Attribut} write_through

Whether writes are passed immediately to the underlying binary
buffer.


Ajouté dans la version 3.7.

@end deffn

@geindex reconfigure() (méthode io.TextIOWrapper)
@anchor{library/io io TextIOWrapper reconfigure}@anchor{b37}
@deffn {Méthode} reconfigure (*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)

Reconfigure this text stream using new settings for `encoding',
`errors', `newline', `line_buffering' and `write_through'.

Parameters not specified keep current settings, except
@code{errors='strict'} is used when `encoding' is specified but
`errors' is not specified.

Il n'est pas possible de modifier l'encodage ou une nouvelle ligne si des données ont déjà été lues à partir du flux. En revanche, il est possible de modifier l'encodage après l'écriture.

Cette méthode effectue un nettoyage implicite du flux avant de définir les nouveaux paramètres.


Ajouté dans la version 3.7.



Modifié dans la version 3.11: La méthode prend en charge l'option @code{encoding="locale"}.

@end deffn

@geindex seek() (méthode io.TextIOWrapper)
@anchor{library/io io TextIOWrapper seek}@anchor{2bb9}
@deffn {Méthode} seek (cookie, whence=os.SEEK_SET, /)

Set the stream position.
Return the new stream position as an @ref{254,,int}.

Four operations are supported,
given by the following argument combinations:


@itemize *

@item 
@code{seek(0, SEEK_SET)}: Rewind to the start of the stream.

@item 
@code{seek(cookie, SEEK_SET)}: Restore a previous position;
`cookie' `must be' a number returned by @ref{2bba,,tell()}.

@item 
@code{seek(0, SEEK_END)}: Fast-forward to the end of the stream.

@item 
@code{seek(0, SEEK_CUR)}: Leave the current stream position unchanged.
@end itemize

Any other argument combinations are invalid,
and may raise exceptions.


@subsubheading Voir aussi


@ref{126b,,os.SEEK_SET}, @ref{126c,,os.SEEK_CUR}, and @ref{126d,,os.SEEK_END}.

@end deffn

@geindex tell() (méthode io.TextIOWrapper)
@anchor{library/io io TextIOWrapper tell}@anchor{2bba}
@deffn {Méthode} tell ()

Return the stream position as an opaque number.
The return value of @code{tell()} can be given as input to @ref{2bb9,,seek()},
to restore a previous stream position.
@end deffn
@end deffn

@geindex StringIO (classe dans io)
@anchor{library/io io StringIO}@anchor{f12}
@deffn {Classe} io.StringIO (initial_value='@w{'}, newline='\n')

A text stream using an in-memory text buffer.  It inherits from
@ref{680,,TextIOBase}.

The text buffer is discarded when the @ref{1f3,,close()} method is
called.

The initial value of the buffer can be set by providing `initial_value'.
If newline translation is enabled, newlines will be encoded as if by
@ref{1c02,,write()}.  The stream is positioned at the start of the
buffer which emulates opening an existing file in a @code{w+} mode, making it
ready for an immediate write from the beginning or for a write that
would overwrite the initial value.  To emulate opening a file in an @code{a+}
mode ready for appending, use @code{f.seek(0, io.SEEK_END)} to reposition the
stream at the end of the buffer.

The `newline' argument works like that of @ref{7a5,,TextIOWrapper},
except that when writing output to the stream, if `newline' is @code{None},
newlines are written as @code{\n} on all platforms.

@ref{f12,,StringIO} provides this method in addition to those from
@ref{680,,TextIOBase} and @ref{1f2,,IOBase}:

@geindex getvalue() (méthode io.StringIO)
@anchor{library/io io StringIO getvalue}@anchor{2bbb}
@deffn {Méthode} getvalue ()

Return a @ref{435,,str} containing the entire contents of the buffer.
Newlines are decoded as if by @ref{1c13,,read()}, although
the stream position is not changed.
@end deffn

Exemple d'utilisation :

@example
import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()
@end example
@end deffn

@geindex universal newlines;io.IncrementalNewlineDecoder class

@geindex IncrementalNewlineDecoder (classe dans io)
@anchor{library/io io IncrementalNewlineDecoder}@anchor{1652}
@deffn {Classe} io.IncrementalNewlineDecoder

A helper codec that decodes newlines for @ref{d28,,universal newlines} mode.
It inherits from @ref{2350,,codecs.IncrementalDecoder}.
@end deffn

@node Performances<3>,,Class hierarchy,io --- Core tools for working with streams
@anchor{library/io performance}@anchor{2bbc}
@subsubsection Performances


Cette section aborde les performances des implémentations concrètes d'Entrée/Sortie fournies.

@menu
* Binary I/O: Binary I/O<2>. 
* Entrée/sortie de texte: Entrée/sortie de texte<3>. 
* Fils d'exécution: Fils d'exécution<3>. 
* Réentrance:: 

@end menu

@node Binary I/O<2>,Entrée/sortie de texte<3>,,Performances<3>
@anchor{library/io id2}@anchor{2bbd}
@subsubsection Binary I/O


By reading and writing only large chunks of data even when the user asks for a
single byte, buffered I/O hides any inefficiency in calling and executing the
operating system's unbuffered I/O routines.  The gain depends on the OS and the
kind of I/O which is performed.  For example, on some modern OSes such as Linux,
unbuffered disk I/O can be as fast as buffered I/O.  The bottom line, however,
is that buffered I/O offers predictable performance regardless of the platform
and the backing device.  Therefore, it is almost always preferable to use
buffered I/O rather than unbuffered I/O for binary data.

@node Entrée/sortie de texte<3>,Fils d'exécution<3>,Binary I/O<2>,Performances<3>
@anchor{library/io id3}@anchor{2bbe}
@subsubsection Entrée/sortie de texte


Text I/O over a binary storage (such as a file) is significantly slower than
binary I/O over the same storage, because it requires conversions between
unicode and binary data using a character codec.  This can become noticeable
handling huge amounts of text data like large log files.  Also,
@ref{2bb6,,tell()} and @ref{2bb5,,seek()} are both quite slow
due to the reconstruction algorithm used.

@ref{f12,,StringIO}, however, is a native in-memory unicode container and will
exhibit similar speed to @ref{e8d,,BytesIO}.

@node Fils d'exécution<3>,Réentrance,Entrée/sortie de texte<3>,Performances<3>
@anchor{library/io multi-threading}@anchor{2bbf}
@subsubsection Fils d'exécution


@ref{12ee,,FileIO} objects are thread-safe to the extent that the operating system
calls (such as @code{read(2)@footnote{https://manpages.debian.org/read(2)}} under Unix) they wrap are thread-safe too.

Binary buffered objects (instances of @ref{11eb,,BufferedReader},
@ref{2103,,BufferedWriter}, @ref{2104,,BufferedRandom} and @ref{2b9d,,BufferedRWPair})
protect their internal structures using a lock; it is therefore safe to call
them from multiple threads at once.

les objets @ref{7a5,,TextIOWrapper} ne sont pas compatibles avec les programmes à fils d'exécutions multiples.

@node Réentrance,,Fils d'exécution<3>,Performances<3>
@anchor{library/io reentrancy}@anchor{2bc0}
@subsubsection Réentrance


Binary buffered objects (instances of @ref{11eb,,BufferedReader},
@ref{2103,,BufferedWriter}, @ref{2104,,BufferedRandom} and @ref{2b9d,,BufferedRWPair})
are not reentrant.  While reentrant calls will not happen in normal situations,
they can arise from doing I/O in a @ref{c5,,signal} handler.  If a thread tries to
re-enter a buffered object which it is already accessing, a @ref{193,,RuntimeError}
is raised.  Note this doesn't prohibit a different thread from entering the
buffered object.

The above implicitly extends to text files, since the @ref{505,,open()} function
will wrap a buffered object inside a @ref{7a5,,TextIOWrapper}.  This includes
standard streams and therefore affects the built-in @ref{f60,,print()} function as
well.

@node time --- Time access and conversions,logging --- Logging facility for Python,io --- Core tools for working with streams,Services génériques du système d'exploitation
@anchor{library/time doc}@anchor{2bc1}@anchor{library/time module-time}@anchor{ed}@anchor{library/time time-time-access-and-conversions}@anchor{2bc2}
@subsection @code{time} --- Time access and conversions


@geindex module; time


__________________________________________________________________


Ce module fournit différentes fonctions liées au temps. Pour les fonctionnalités associées, voir aussi les modules @ref{30,,datetime} et @ref{14,,calendar}.

Bien que ce module soit toujours disponible, toutes les fonctions ne sont pas disponibles sur toutes les plateformes. La plupart des fonctions définies dans ce module délèguent à des fonctions de même nom de la bibliothèque C. Il peut parfois être utile de consulter la documentation de la plate-forme, car la sémantique de ces fonctions peut varier.

Vous trouvez ci-dessous, mises en ordre, quelques explications relative à la terminologie et aux conventions.

@geindex epoch
@anchor{library/time epoch}@anchor{29a5}

@itemize *

@item 
L'`epoch' est le point de départ du temps, le résultat de @code{time.gmtime(0)} est le 1@w{^er} janvier 1970 à 00:00:00 (UTC) pour toutes les plateformes.
@end itemize

@geindex secondes depuis *epoch*


@itemize *

@item 
Le terme `secondes depuis *epoch*' désigne le nombre total de secondes écoulées depuis `epoch', souvent en excluant les secondes intercalaires (leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second}). Les secondes intercalaires sont exclues de ce total sur toutes les plates-formes conformes POSIX.
@end itemize

@geindex Year 2038


@itemize *

@item 
Les fonctions de ce module peuvent ne pas gérer les dates et heures antérieures à @ref{29a5,,epoch} ou dans un avenir lointain. Le seuil du futur est déterminé par la bibliothèque C ; pour les systèmes 32 bits, il s’agit généralement de 2038.
@end itemize

@geindex 2-digit years


@itemize *

@item 
La fonction @ref{13e3,,strptime()} peut analyser des années à 2 chiffres lorsque le format @code{%y} est spécifié. Lorsque les années à deux chiffres sont analysées, elles sont converties conformément aux normes POSIX et ISO C : les valeurs 69—99 correspondent à 1969—1999 et les valeurs 0—68 à 2000—2068.
@end itemize

@geindex UTC
@geindex Coordinated Universal Time
@geindex Greenwich Mean Time


@itemize *

@item 
UTC désigne le temps universel coordonné (`Coordinated Universal Time' en anglais), anciennement l'heure de Greenwich (ou GMT). L'acronyme UTC n'est pas une erreur mais un compromis entre l'anglais et le français.
@end itemize

@geindex Daylight Saving Time


@itemize *

@item 
Le DST (`Daylight Saving Time') correspond à l’heure d’été, un ajustement du fuseau horaire d’une heure (généralement) pendant une partie de l’année. Les règles de DST sont magiques (déterminées par la loi locale) et peuvent changer d’année en année. La bibliothèque C possède une table contenant les règles locales (souvent, elle est lue dans un fichier système par souci de souplesse) et constitue la seule source fiable.

@item 
La précision des diverses fonctions en temps réel peut être inférieure à celle suggérée par les unités dans lesquelles leur valeur ou leur argument est exprimé. Par exemple, sur la plupart des systèmes Unix, l’horloge ne « bat » que 50 ou 100 fois par seconde.

@item 
On the other hand, the precision of @ref{251,,time()} and @ref{688,,sleep()} is better
than their Unix equivalents: times are expressed as floating-point numbers,
@ref{251,,time()} returns the most accurate time available (using Unix
@code{gettimeofday()} where available), and @ref{688,,sleep()} will accept a time
with a nonzero fraction (Unix @code{select()} is used to implement this, where
available).

@item 
La valeur temporelle renvoyée par @ref{119d,,gmtime()}, @ref{14af,,localtime()} et @ref{13e3,,strptime()}, et acceptée par @ref{11c4,,asctime()}, @ref{11c5,,mktime()} et @ref{11c6,,strftime()}, est une séquence de 9 nombres entiers. Les valeurs de retour de @ref{119d,,gmtime()}, @ref{14af,,localtime()} et @ref{13e3,,strptime()} proposent également des noms d’attributs pour des champs individuels.

Voir @ref{cd8,,struct_time} pour une description de ces objets.


Modifié dans la version 3.3: The @ref{cd8,,struct_time} type was extended to provide
the @ref{2bc3,,tm_gmtoff} and @ref{2bc4,,tm_zone}
attributes when platform supports corresponding
@code{struct tm} members.



Modifié dans la version 3.6: The @ref{cd8,,struct_time} attributes
@ref{2bc3,,tm_gmtoff} and @ref{2bc4,,tm_zone}
are now available on all platforms.


@item 
Utilisez les fonctions suivantes pour convertir des représentations temporelles :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

De

@tab

À

@tab

Utilisez

@item

secondes depuis `epoch'

@tab

@ref{cd8,,struct_time} en UTC

@tab

@ref{119d,,gmtime()}

@item

secondes depuis `epoch'

@tab

@ref{cd8,,struct_time} en heure locale

@tab

@ref{14af,,localtime()}

@item

@ref{cd8,,struct_time} en UTC

@tab

secondes depuis `epoch'

@tab

@ref{245b,,calendar.timegm()}

@item

@ref{cd8,,struct_time} en heure locale

@tab

secondes depuis `epoch'

@tab

@ref{11c5,,mktime()}

@end multitable

@end itemize

@menu
* Fonctions: Fonctions<5>. 
* Constantes d’identification d’horloge:: 
* Constantes de fuseau horaire:: 

@end menu

@node Fonctions<5>,Constantes d’identification d’horloge,,time --- Time access and conversions
@anchor{library/time functions}@anchor{2bc5}@anchor{library/time time-functions}@anchor{2bc6}
@subsubsection Fonctions


@geindex asctime() (dans le module time)
@anchor{library/time time asctime}@anchor{11c4}
@deffn {Fonction} time.asctime ([t])

Convertit un `n'-uplet ou @ref{cd8,,struct_time} représentant une heure renvoyée par @ref{119d,,gmtime()} ou @ref{14af,,localtime()} en une chaîne de la forme suivante : @code{'Sun Jun 20 23:21:05 1993'}. Le numéro du jour est un champ de deux caractères complété par une espace si celui-ci n'a qu'un seul chiffre, par exemple : @code{'Wed Jun  9 04:26:40 1993'}.

Si `t' n’est pas fourni, l’heure actuelle renvoyée par @ref{14af,,localtime()} est utilisée. Les informations sur les paramètres régionaux ne sont pas utilisées par @ref{11c4,,asctime()}.

@cartouche
@quotation Note 
Contrairement à la fonction C du même nom, @ref{11c4,,asctime()} n’ajoute pas de caractère de fin de ligne.
@end quotation
@end cartouche
@end deffn

@geindex pthread_getcpuclockid() (dans le module time)
@anchor{library/time time pthread_getcpuclockid}@anchor{b80}
@deffn {Fonction} time.pthread_getcpuclockid (thread_id)

Renvoie le `clk_id' de l'horloge du temps CPU spécifique au fil d'exécution pour le `thread_id' spécifié.

Utilisez @ref{113a,,threading.get_ident()} ou l'attribut @ref{2bc7,,ident} de @ref{939,,threading.Thread} pour obtenir une valeur appropriée pour `thread_id'.

@cartouche
@quotation Avertissement 
Passer un `thread_id' invalide ou arrivé à expiration peut entraîner un comportement indéfini, tel qu’une erreur de segmentation.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Unix

Se reporter à la page de manuel @code{pthread_getcpuclockid(3)@footnote{https://manpages.debian.org/pthread_getcpuclockid(3)}} pour plus d’informations.


Ajouté dans la version 3.7.

@end deffn

@geindex clock_getres() (dans le module time)
@anchor{library/time time clock_getres}@anchor{113d}
@deffn {Fonction} time.clock_getres (clk_id)

Renvoie la résolution (précision) de l’horloge `clk_id'. Référez-vous à @ref{2b3a,,Constantes d’identification d’horloge} pour une liste des valeurs acceptées pour `clk_id'.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex clock_gettime() (dans le module time)
@anchor{library/time time clock_gettime}@anchor{113e}
@deffn {Fonction} time.clock_gettime (clk_id) -> float

Renvoie l’heure de l’horloge `clk_id'. Référez-vous à @ref{2b3a,,Constantes d’identification d’horloge} pour une liste des valeurs acceptées pour `clk_id'.

Use @ref{ad0,,clock_gettime_ns()} to avoid the precision loss caused by the
@ref{2eb,,float} type.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex clock_gettime_ns() (dans le module time)
@anchor{library/time time clock_gettime_ns}@anchor{ad0}
@deffn {Fonction} time.clock_gettime_ns (clk_id) -> int

Similaire à @ref{113e,,clock_gettime()} mais le temps renvoyé est exprimé en nanosecondes.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.7.

@end deffn

@geindex clock_settime() (dans le module time)
@anchor{library/time time clock_settime}@anchor{113f}
@deffn {Fonction} time.clock_settime (clk_id, time: float)

Définit l’heure de l’horloge `clk_id'. Actuellement, @ref{685,,CLOCK_REALTIME} est la seule valeur acceptée pour `clk_id'.

Use @ref{ad1,,clock_settime_ns()} to avoid the precision loss caused by the
@ref{2eb,,float} type.

@ref{1ce0,,Availability}: Unix, not Android, not iOS.


Ajouté dans la version 3.3.

@end deffn

@geindex clock_settime_ns() (dans le module time)
@anchor{library/time time clock_settime_ns}@anchor{ad1}
@deffn {Fonction} time.clock_settime_ns (clk_id, time: int)

Similaire à @ref{113f,,clock_settime()} mais définit l’heure avec des nanosecondes.

@ref{1ce0,,Availability}: Unix, not Android, not iOS.


Ajouté dans la version 3.7.

@end deffn

@geindex ctime() (dans le module time)
@anchor{library/time time ctime}@anchor{23d8}
@deffn {Fonction} time.ctime ([secs])

Convertit une heure exprimée en secondes depuis @ref{29a5,,epoch} en une chaîne représentant l’heure locale sous la forme suivante : @code{'Sun Jun 20 23:21:05 1993'}. Le numéro du jour est un champ de deux caractères complété par une espace si celui-ci n'a qu'un seul chiffre, par exemple : @code{'Wed Jun  9 04:26:40 1993'}.

Si `secs' n’est pas fourni ou vaut @ref{660,,None}, l’heure actuelle renvoyée par @ref{251,,time()} est utilisée. @code{ctime(secs)} est équivalent à @code{asctime(localtime(secs))}. Les informations sur les paramètres régionaux ne sont pas utilisées par @ref{23d8,,ctime()}.
@end deffn

@geindex get_clock_info() (dans le module time)
@anchor{library/time time get_clock_info}@anchor{113c}
@deffn {Fonction} time.get_clock_info (name)

Renvoie des informations sur l’horloge spécifiée en tant qu’objet d’espace de nom. Les noms d’horloge pris en charge et les fonctions correspondantes permettant de lire leur valeur sont les suivants :


@itemize *

@item 
@code{'monotonic'} : @ref{250,,time.monotonic()}

@item 
@code{'perf_counter'} : @ref{a76,,time.perf_counter()}

@item 
@code{'process_time'} : @ref{a77,,time.process_time()}

@item 
@code{'thread_time'} : @ref{923,,time.thread_time()}

@item 
@code{'time'} : @ref{251,,time.time()}
@end itemize

Le résultat a les attributs suivants :


@itemize -

@item 
`adjustable' : @code{True} si l’horloge peut être changée automatiquement (par exemple par un démon NTP) ou manuellement par l’administrateur système, @code{False} autrement

@item 
`implementation' : nom de la fonction C sous-jacente utilisée pour obtenir la valeur d’horloge. Voir @ref{2b3a,,Constantes d’identification d’horloge} pour les valeurs possibles.

@item 
`monotonic' : @code{True} si l’horloge ne peut pas revenir en arrière, @code{False} autrement

@item 
`resolution' : La résolution de l’horloge en secondes (@ref{2eb,,float})
@end itemize


Ajouté dans la version 3.3.

@end deffn

@geindex gmtime() (dans le module time)
@anchor{library/time time gmtime}@anchor{119d}
@deffn {Fonction} time.gmtime ([secs])

Convertit un temps exprimé en secondes depuis @ref{29a5,,epoch} en un @ref{cd8,,struct_time} au format UTC dans lequel le drapeau `dst' est toujours égal à zéro. Si `secs' n’est pas fourni ou vaut @ref{660,,None}, l’heure actuelle renvoyée par @ref{251,,time()} est utilisée. Les fractions de seconde sont ignorées. Voir ci-dessus pour une description de l’objet @ref{cd8,,struct_time}. Voir @ref{245b,,calendar.timegm()} pour l’inverse de cette fonction.
@end deffn

@geindex localtime() (dans le module time)
@anchor{library/time time localtime}@anchor{14af}
@deffn {Fonction} time.localtime ([secs])

Comme @ref{119d,,gmtime()} mais convertit le résultat en heure locale. Si `secs' n’est pas fourni ou vaut @ref{660,,None}, l’heure actuelle renvoyée par @ref{251,,time()} est utilisée. Le drapeau `dst' est mis à @code{1} lorsque l’heure d’été s’applique à l’heure indiquée.

@ref{14af,,localtime()} may raise @ref{86d,,OverflowError}, if the timestamp is
outside the range of values supported by the platform C @code{localtime()}
or @code{gmtime()} functions, and @ref{40d,,OSError} on @code{localtime()} or
@code{gmtime()} failure. It's common for this to be restricted to years
between 1970 and 2038.
@end deffn

@geindex mktime() (dans le module time)
@anchor{library/time time mktime}@anchor{11c5}
@deffn {Fonction} time.mktime (t)

This is the inverse function of @ref{14af,,localtime()}.  Its argument is the
@ref{cd8,,struct_time} or full 9-tuple (since the dst flag is needed; use @code{-1}
as the dst flag if it is unknown) which expresses the time in `local' time, not
UTC.  It returns a floating-point number, for compatibility with @ref{251,,time()}.
If the input value cannot be represented as a valid time, either
@ref{86d,,OverflowError} or @ref{1ff,,ValueError} will be raised (which depends on
whether the invalid value is caught by Python or the underlying C libraries).
The earliest date for which it can generate a time is platform-dependent.
@end deffn

@geindex monotonic() (dans le module time)
@anchor{library/time time monotonic}@anchor{250}
@deffn {Fonction} time.monotonic () -> float

Renvoie la valeur (en quelques fractions de secondes) d’une horloge monotone, c’est-à-dire une horloge qui ne peut pas revenir en arrière. L’horloge n’est pas affectée par les mises à jour de l’horloge système. Le point de référence de la valeur renvoyée n’est pas défini, de sorte que seule la différence entre les résultats d’appels consécutifs est valide.

Clock:


@itemize *

@item 
On Windows, call @code{QueryPerformanceCounter()} and
@code{QueryPerformanceFrequency()}.

@item 
On macOS, call @code{mach_absolute_time()} and @code{mach_timebase_info()}.

@item 
On HP-UX, call @code{gethrtime()}.

@item 
Call @code{clock_gettime(CLOCK_HIGHRES)} if available.

@item 
Otherwise, call @code{clock_gettime(CLOCK_MONOTONIC)}.
@end itemize

Use @ref{ad2,,monotonic_ns()} to avoid the precision loss caused by the
@ref{2eb,,float} type.


Ajouté dans la version 3.3.



Modifié dans la version 3.5: La fonction est maintenant toujours disponible et toujours à l’échelle du système.



Modifié dans la version 3.10: Sur macOS, la fonction est maintenant toujours à l’échelle du système.

@end deffn

@geindex monotonic_ns() (dans le module time)
@anchor{library/time time monotonic_ns}@anchor{ad2}
@deffn {Fonction} time.monotonic_ns () -> int

Similaire à @code{monotonique()}, mais le temps de retour est exprimé en nanosecondes.


Ajouté dans la version 3.7.

@end deffn

@geindex perf_counter() (dans le module time)
@anchor{library/time time perf_counter}@anchor{a76}
@deffn {Fonction} time.perf_counter () -> float

@geindex benchmarking

Renvoie la valeur (en quelques fractions de secondes) d’un compteur de performance, c’est-à-dire une horloge avec la résolution disponible la plus élevée possible pour mesurer une courte durée. Cela inclut le temps écoulé pendant le sommeil et concerne l’ensemble du système. Le point de référence de la valeur renvoyée n’est pas défini, de sorte que seule la différence entre les résultats d’appels consécutifs est valide.

`Particularité de l'implémentation CPython :' On CPython, use the same clock as @ref{250,,time.monotonic()} and is a
monotonic clock, i.e. a clock that cannot go backwards.

Use @ref{ad3,,perf_counter_ns()} to avoid the precision loss caused by the
@ref{2eb,,float} type.


Ajouté dans la version 3.3.



Modifié dans la version 3.10: On Windows, the function is now system-wide.



Modifié dans la version 3.13: Use the same clock as @ref{250,,time.monotonic()}.

@end deffn

@geindex perf_counter_ns() (dans le module time)
@anchor{library/time time perf_counter_ns}@anchor{ad3}
@deffn {Fonction} time.perf_counter_ns () -> int

Similaire à @ref{a76,,perf_counter()}, mais renvoie le temps en nanosecondes.


Ajouté dans la version 3.7.

@end deffn

@geindex process_time() (dans le module time)
@anchor{library/time time process_time}@anchor{a77}
@deffn {Fonction} time.process_time () -> float

@geindex CPU time
@geindex processor time
@geindex benchmarking

Return the value (in fractional seconds) of the sum of the system and user
CPU time of the current process.  It does not include time elapsed during
sleep.  It is process-wide by definition.  The reference point of the
returned value is undefined, so that only the difference between the results
of two calls is valid.

Use @ref{ad4,,process_time_ns()} to avoid the precision loss caused by the
@ref{2eb,,float} type.


Ajouté dans la version 3.3.

@end deffn

@geindex process_time_ns() (dans le module time)
@anchor{library/time time process_time_ns}@anchor{ad4}
@deffn {Fonction} time.process_time_ns () -> int

Similaire à @ref{a77,,process_time()} mais renvoie le temps en nanosecondes.


Ajouté dans la version 3.7.

@end deffn

@geindex sleep() (dans le module time)
@anchor{library/time time sleep}@anchor{688}
@deffn {Fonction} time.sleep (secs)

Suspend execution of the calling thread for the given number of seconds.
The argument may be a floating-point number to indicate a more precise sleep
time.

If the sleep is interrupted by a signal and no exception is raised by the
signal handler, the sleep is restarted with a recomputed timeout.

The suspension time may be longer than requested by an arbitrary amount,
because of the scheduling of other activity in the system.

On Windows, if `secs' is zero, the thread relinquishes the remainder of its
time slice to any other thread that is ready to run. If there are no other
threads ready to run, the function returns immediately, and the thread
continues execution.  On Windows 8.1 and newer the implementation uses
a high-resolution timer@footnote{https://learn.microsoft.com/windows-hardware/drivers/kernel/high-resolution-timers}
which provides resolution of 100 nanoseconds. If `secs' is zero, @code{Sleep(0)} is used.

Unix implementation:


@itemize *

@item 
Use @code{clock_nanosleep()} if available (resolution: 1 nanosecond);

@item 
Or use @code{nanosleep()} if available (resolution: 1 nanosecond);

@item 
Or use @code{select()} (resolution: 1 microsecond).
@end itemize

Raises an @ref{1848,,auditing event} @code{time.sleep} with argument @code{secs}.


Modifié dans la version 3.5: La fonction dort maintenant au moins `secondes' même si le sommeil est interrompu par un signal, sauf si le gestionnaire de signaux lève une exception (voir 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} pour la justification).



Modifié dans la version 3.11: On Unix, the @code{clock_nanosleep()} and @code{nanosleep()} functions are now
used if available. On Windows, a waitable timer is now used.



Modifié dans la version 3.13: Raises an auditing event.

@end deffn

@geindex % (percent);datetime format

@geindex strftime() (dans le module time)
@anchor{library/time time strftime}@anchor{11c6}
@deffn {Fonction} time.strftime (format[, t])

Convertit un `n'-uplet ou @ref{cd8,,struct_time} représentant une heure renvoyée par @ref{119d,,gmtime()} ou @ref{14af,,localtime()} en une chaîne spécifiée par l’argument `format'. Si `t' n’est pas fourni, l’heure actuelle renvoyée par @ref{14af,,localtime()} est utilisée. `format' doit être une chaîne. Si l’un des champs de `t' se situe en dehors de la plage autorisée, une @ref{1ff,,ValueError} est levée .

0 est un argument légal pour toute position dans le `n'-uplet temporel ; s’il est normalement illégal, la valeur est forcée à une valeur correcte.

Les directives suivantes peuvent être incorporées dans la chaîne `format'. Ils sont affichés sans la spécification facultative de largeur de champ ni de précision, et sont remplacés par les caractères indiqués dans le résultat de @ref{11c6,,strftime()} :


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Directive

@tab

Signification

@tab

Notes

@item

@code{%a}

@tab

Nom abrégé du jour de la semaine selon les paramètres régionaux.

@tab

@item

@code{%A}

@tab

Le nom de semaine complet de la région.

@tab

@item

@code{%b}

@tab

Nom abrégé du mois de la région.

@tab

@item

@code{%B}

@tab

Nom complet du mois de la région.

@tab

@item

@code{%c}

@tab

Représentation appropriée de la date et de l’heure selon les paramètres régionaux.

@tab

@item

@code{%d}

@tab

Jour du mois sous forme décimale [01,31].

@tab

@item

@code{%f}

@tab


@table @asis

@item Microseconds as a decimal number

[000000,999999].
@end table

@tab

(1)

@item

@code{%H}

@tab

Heure (horloge sur 24 heures) sous forme de nombre décimal [00,23].

@tab

@item

@code{%I}

@tab

Heure (horloge sur 12 heures) sous forme de nombre décimal [01,12].

@tab

@item

@code{%j}

@tab

Jour de l’année sous forme de nombre décimal [001,366].

@tab

@item

@code{%m}

@tab

Mois sous forme décimale [01,12].

@tab

@item

@code{%M}

@tab

Minutes sous forme décimale [00,59].

@tab

@item

@code{%p}

@tab

L’équivalent local de AM ou PM.

@tab

(2)

@item

@code{%S}

@tab

Secondes sous forme de nombre décimal [00,61].

@tab

(3)

@item

@code{%U}

@tab

Numéro de semaine de l’année (dimanche en tant que premier jour de la semaine) sous forme décimale [00,53]. Tous les jours d’une nouvelle année précédant le premier dimanche sont considérés comme appartenant à la semaine 0.

@tab

(4)

@item

@code{%u}

@tab

Day of the week (Monday is 1; Sunday is 7)
as a decimal number [1, 7].

@tab

@item

@code{%w}

@tab

Jour de la semaine sous forme de nombre décimal [0 (dimanche), 6].

@tab

@item

@code{%W}

@tab

Numéro de semaine de l’année (lundi comme premier jour de la semaine) sous forme décimale [00,53]. Tous les jours d’une nouvelle année précédant le premier lundi sont considérés comme appartenant à la semaine 0.

@tab

(4)

@item

@code{%x}

@tab

Représentation de la date appropriée par les paramètres régionaux.

@tab

@item

@code{%X}

@tab

Représentation locale de l'heure.

@tab

@item

@code{%y}

@tab

Année sans siècle comme un nombre décimal [00, 99].

@tab

@item

@code{%Y}

@tab

Année complète sur quatre chiffres.

@tab

@item

@code{%z}

@tab

Décalage de fuseau horaire indiquant une différence de temps positive ou négative par rapport à UTC / GMT de la forme `+HHMM' ou `-HHMM', où H représente les chiffres des heures décimales et M, les chiffres des minutes décimales [`-23:59', `+23:59'] @footnote{
L'utilisation de @code{%Z} est maintenant obsolète, mais l'échappement @code{%z} qui donne le décalage horaire jusqu'à la minute et dépendant des paramètres régionaux n'est pas pris en charge par toutes les bibliothèques C ANSI. En outre, une lecture stricte du standard 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} de 1982 milite pour une année à deux chiffres (%y plutôt que %Y), mais la pratique a migré vers des années à 4 chiffres de long avant l'année 2000. Après cela, la 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} est devenue obsolète et l'année à 4 chiffres a été recommandée pour la première fois par la 
@geindex RFC; RFC 1123
@uref{https://datatracker.ietf.org/doc/html/rfc1123.html,RFC 1123} puis rendue obligatoire par la 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}.
}

@tab

@item

@code{%Z}

@tab

Nom du fuseau horaire (pas de caractères s’il n’y a pas de fuseau horaire). Obsolète. @footnote{
L'utilisation de @code{%Z} est maintenant obsolète, mais l'échappement @code{%z} qui donne le décalage horaire jusqu'à la minute et dépendant des paramètres régionaux n'est pas pris en charge par toutes les bibliothèques C ANSI. En outre, une lecture stricte du standard 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} de 1982 milite pour une année à deux chiffres (%y plutôt que %Y), mais la pratique a migré vers des années à 4 chiffres de long avant l'année 2000. Après cela, la 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} est devenue obsolète et l'année à 4 chiffres a été recommandée pour la première fois par la 
@geindex RFC; RFC 1123
@uref{https://datatracker.ietf.org/doc/html/rfc1123.html,RFC 1123} puis rendue obligatoire par la 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}.
}

@tab

@item

@code{%G}

@tab

ISO 8601 year (similar to @code{%Y} but follows
the rules for the ISO 8601 calendar year).
The year starts with the week that contains
the first Thursday of the calendar year.

@tab

@item

@code{%V}

@tab

ISO 8601 week number (as a decimal number
[01,53]). The first week of the year is the
one that contains the first Thursday of the
year. Weeks start on Monday.

@tab

@item

@code{%%}

@tab

Un caractère @code{'%'} littéral.

@tab

@end multitable


Notes :


@enumerate 

@item 
The @code{%f} format directive only applies to @ref{13e3,,strptime()},
not to @ref{11c6,,strftime()}. However, see also @ref{1593,,datetime.datetime.strptime()} and
@ref{c7e,,datetime.datetime.strftime()} where the @code{%f} format directive
@ref{23a9,,applies to microseconds}.

@item 
Lorsqu’elle est utilisée avec la fonction @ref{13e3,,strptime()}, la directive @code{%p} n’affecte le champ d’heure en sortie que si la directive @code{%I} est utilisée pour analyser l’heure.
@end enumerate
@anchor{library/time leap-second}@anchor{2bc8}

@enumerate 3

@item 
La plage est en réalité de @code{0} à @code{61} ; la valeur @code{60} est valide dans les `timestamps' représentant des secondes intercalaires (leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second}) et la valeur @code{61} est prise en charge pour des raisons historiques.

@item 
Lorsqu’elles sont utilisées avec la fonction @ref{13e3,,strptime()}, @code{%U} et @code{%W} ne sont utilisées que dans les calculs lorsque le jour de la semaine et l’année sont spécifiés.
@end enumerate

Voici un exemple de format de date compatible avec celui spécifié dans la norme de courrier électronique Internet suivante 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}. @footnote{
L'utilisation de @code{%Z} est maintenant obsolète, mais l'échappement @code{%z} qui donne le décalage horaire jusqu'à la minute et dépendant des paramètres régionaux n'est pas pris en charge par toutes les bibliothèques C ANSI. En outre, une lecture stricte du standard 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} de 1982 milite pour une année à deux chiffres (%y plutôt que %Y), mais la pratique a migré vers des années à 4 chiffres de long avant l'année 2000. Après cela, la 
@geindex RFC; RFC 822
@uref{https://datatracker.ietf.org/doc/html/rfc822.html,RFC 822} est devenue obsolète et l'année à 4 chiffres a été recommandée pour la première fois par la 
@geindex RFC; RFC 1123
@uref{https://datatracker.ietf.org/doc/html/rfc1123.html,RFC 1123} puis rendue obligatoire par la 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}.
}

@example
>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'
@end example

Des directives supplémentaires peuvent être prises en charge sur certaines plates-formes, mais seules celles énumérées ici ont une signification normalisée par ANSI C. Pour voir la liste complète des codes de format pris en charge sur votre plate-forme, consultez la documentation @code{strftime(3)@footnote{https://manpages.debian.org/strftime(3)}}.

Sur certaines plates-formes, une spécification facultative de largeur et de précision de champ peut suivre immédiatement le @code{'%'} initial d’une directive dans l’ordre suivant ; ce n’est pas non plus portable. La largeur du champ est normalement 2 sauf pour @code{%j} où il est 3.
@end deffn

@geindex % (percent);datetime format

@geindex strptime() (dans le module time)
@anchor{library/time time strptime}@anchor{13e3}
@deffn {Fonction} time.strptime (string[, format])

Analyse une chaîne représentant une heure selon un format. La valeur renvoyée est une @ref{cd8,,struct_time} tel que renvoyé par @ref{119d,,gmtime()} ou @ref{14af,,localtime()}.

Le paramètre `format' utilise les mêmes directives que celles utilisées par @ref{11c6,,strftime()} ; la valeur par défaut est @code{"%a %b %d %H:%M:%S %Y"} qui correspond à la mise en forme renvoyée par @ref{23d8,,ctime()}. Si `string' ne peut pas être analysé selon `format', ou s’il contient trop de données après l’analyse, une exception @ref{1ff,,ValueError} est levée. Les valeurs par défaut utilisées pour renseigner les données manquantes lorsque des valeurs plus précises ne peuvent pas être inférées sont @code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)}. `string' et `format' doivent être des chaînes.

Par exemple :

@example
>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")   
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
@end example

La prise en charge de la directive @code{%Z} est basée sur les valeurs contenues dans @code{tzname} et sur le fait de savoir si @code{daylight} est vrai. Pour cette raison, il est spécifique à la plate-forme, à l’exception de la reconnaissance des heures UTC et GMT, qui sont toujours connues (et considérées comme des fuseaux horaires ne respectant pas l’heure d’été).

Seules les directives spécifiées dans la documentation sont prises en charge. Parce que @code{strftime()} peut être implémenté différemment sur chaque plate-forme, il peut parfois offrir plus de directives que celles listées. Mais @code{strptime()} est indépendant de toute plate-forme et ne supporte donc pas nécessairement toutes les directives disponibles qui ne sont pas documentées comme gérées.
@end deffn

@geindex struct_time (classe dans time)
@anchor{library/time time struct_time}@anchor{cd8}
@deffn {Classe} time.struct_time

Le type de la séquence de valeur temporelle renvoyé par @ref{119d,,gmtime()}, @ref{14af,,localtime()} et @ref{13e3,,strptime()}. Semblable à un @ref{639,,named tuple} : ses valeurs sont accessibles par index et par nom d’attribut. Les valeurs suivantes sont présentes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

Index

@tab

Attribut

@tab

Valeurs

@item

0

@tab

@geindex tm_year (attribut time.struct_time)
@anchor{library/time time struct_time tm_year}@anchor{14ae}
@deffn {Attribut} tm_year
@end deffn

@tab

(par exemple, 1993)

@item

1

@tab

@geindex tm_mon (attribut time.struct_time)
@anchor{library/time time struct_time tm_mon}@anchor{2bc9}
@deffn {Attribut} tm_mon
@end deffn

@tab

plage [1, 12]

@item

2

@tab

@geindex tm_mday (attribut time.struct_time)
@anchor{library/time time struct_time tm_mday}@anchor{2bca}
@deffn {Attribut} tm_mday
@end deffn

@tab

plage [1, 31]

@item

3

@tab

@geindex tm_hour (attribut time.struct_time)
@anchor{library/time time struct_time tm_hour}@anchor{2bcb}
@deffn {Attribut} tm_hour
@end deffn

@tab

plage [0, 23]

@item

4

@tab

@geindex tm_min (attribut time.struct_time)
@anchor{library/time time struct_time tm_min}@anchor{2bcc}
@deffn {Attribut} tm_min
@end deffn

@tab

plage [0, 59]

@item

5

@tab

@geindex tm_sec (attribut time.struct_time)
@anchor{library/time time struct_time tm_sec}@anchor{2bcd}
@deffn {Attribut} tm_sec
@end deffn

@tab

range [0, 61]; see @ref{2bc8,,Note (2)} in @ref{11c6,,strftime()}

@item

6

@tab

@geindex tm_wday (attribut time.struct_time)
@anchor{library/time time struct_time tm_wday}@anchor{2bce}
@deffn {Attribut} tm_wday
@end deffn

@tab

range [0, 6]; Monday is 0

@item

7

@tab

@geindex tm_yday (attribut time.struct_time)
@anchor{library/time time struct_time tm_yday}@anchor{2bcf}
@deffn {Attribut} tm_yday
@end deffn

@tab

plage [1, 366]

@item

8

@tab

@geindex tm_isdst (attribut time.struct_time)
@anchor{library/time time struct_time tm_isdst}@anchor{23e9}
@deffn {Attribut} tm_isdst
@end deffn

@tab

@code{0}, @code{1} or @code{-1} ; voir en bas

@item

N/A

@tab

@geindex tm_zone (attribut time.struct_time)
@anchor{library/time time struct_time tm_zone}@anchor{2bc4}
@deffn {Attribut} tm_zone
@end deffn

@tab

abréviation du nom du fuseau horaire

@item

N/A

@tab

@geindex tm_gmtoff (attribut time.struct_time)
@anchor{library/time time struct_time tm_gmtoff}@anchor{2bc3}
@deffn {Attribut} tm_gmtoff
@end deffn

@tab

décalage à l’est de UTC en secondes

@end multitable


Notez que contrairement à la structure C, la valeur du mois est une plage de [1, 12], pas de [0, 11].

Dans les appels à @ref{11c5,,mktime()}, @ref{23e9,,tm_isdst} peut être défini sur 1 lorsque l’heure d'été est en vigueur et sur 0 lorsque ce n’est pas le cas. Une valeur de @code{-1} indique que cela n’est pas connu et entraînera généralement le remplissage de l’état correct.

Lorsqu’un `n'-uplet de longueur incorrecte est passé à une fonction acceptant une @ref{cd8,,struct_time}, ou comportant des éléments de type incorrect, une exception @ref{522,,TypeError} est levé.
@end deffn

@geindex time() (dans le module time)
@anchor{library/time time time}@anchor{251}
@deffn {Fonction} time.time () -> float

Return the time in seconds since the @ref{29a5,,epoch} as a floating-point
number. The handling of leap seconds@footnote{https://en.wikipedia.org/wiki/Leap_second} is platform dependent.
On Windows and most Unix systems, the leap seconds are not counted towards
the time in seconds since the @ref{29a5,,epoch}. This is commonly referred to as Unix time@footnote{https://en.wikipedia.org/wiki/Unix_time}.

Note that even though the time is always returned as a floating-point
number, not all systems provide time with a better precision than 1 second.
While this function normally returns non-decreasing values, it can return a
lower value than a previous call if the system clock has been set back
between the two calls.

Le nombre renvoyé par @ref{251,,time()} peut être converti en un format d’heure plus courant (année, mois, jour, heure, etc.) en UTC en le transmettant à la fonction @ref{119d,,gmtime()} ou dans heure locale en le transmettant à la fonction @ref{14af,,localtime()}. Dans les deux cas, un objet @ref{cd8,,struct_time} est renvoyé, à partir duquel les composants de la date du calendrier peuvent être consultés en tant qu’attributs.

Clock:


@itemize *

@item 
On Windows, call @code{GetSystemTimeAsFileTime()}.

@item 
Call @code{clock_gettime(CLOCK_REALTIME)} if available.

@item 
Otherwise, call @code{gettimeofday()}.
@end itemize

Use @ref{ad5,,time_ns()} to avoid the precision loss caused by the @ref{2eb,,float}
type.
@end deffn

@geindex time_ns() (dans le module time)
@anchor{library/time time time_ns}@anchor{ad5}
@deffn {Fonction} time.time_ns () -> int

Similaire à @ref{251,,time()} mais renvoie le nombre de nanosecondes depuis @ref{29a5,,epoch} sous la forme d'un entier.


Ajouté dans la version 3.7.

@end deffn

@geindex thread_time() (dans le module time)
@anchor{library/time time thread_time}@anchor{923}
@deffn {Fonction} time.thread_time () -> float

@geindex CPU time
@geindex processor time
@geindex benchmarking

Renvoie la valeur (en quelques fractions de secondes) de la somme des temps processeur système et utilisateur du fil d'exécution en cours. Il ne comprend pas le temps écoulé pendant le sommeil. Il est spécifique au fil d'exécution par définition. Le point de référence de la valeur renvoyée est indéfini, de sorte que seule la différence entre les résultats d’appels consécutifs dans le même fil d'exécution est valide.

Use @ref{b7f,,thread_time_ns()} to avoid the precision loss caused by the
@ref{2eb,,float} type.

@ref{1ce0,,Availability}: Linux, Unix, Windows.

Systèmes prenant en charge @code{CLOCK_THREAD_CPUTIME_ID}.


Ajouté dans la version 3.7.

@end deffn

@geindex thread_time_ns() (dans le module time)
@anchor{library/time time thread_time_ns}@anchor{b7f}
@deffn {Fonction} time.thread_time_ns () -> int

Similaire à @ref{923,,thread_time()} mais renvoie le temps en nanosecondes.


Ajouté dans la version 3.7.

@end deffn

@geindex tzset() (dans le module time)
@anchor{library/time time tzset}@anchor{2bd0}
@deffn {Fonction} time.tzset ()

Réinitialise les règles de conversion de temps utilisées par les routines de la bibliothèque. La variable d’environnement 
@geindex TZ
@geindex variable d'environnement; TZ
@code{TZ} spécifie comment cela est effectué. La fonction définira également les variables @code{tzname} (à partir de la variable d’environnement 
@geindex TZ
@geindex variable d'environnement; TZ
@code{TZ}), @code{timezone} (secondes non DST à l’ouest de l’UTC), @code{altzone} (secondes DST à l’ouest de UTC) et @code{daylight} (à 0 si ce fuseau horaire ne comporte aucune règle d’heure d’été, ou non nul s’il existe une heure, passée, présente ou future lorsque l’heure d’été est appliquée).

@ref{1ce0,,Availability}: Unix.

@cartouche
@quotation Note 
Bien que dans de nombreux cas, la modification de la variable d’environnement 
@geindex TZ
@geindex variable d'environnement; TZ
@code{TZ} puisse affecter la sortie de fonctions telles que @ref{14af,,localtime()} sans appeler @ref{2bd0,,tzset()}, ce comportement n'est pas garanti.

La variable d’environnement 
@geindex TZ
@geindex variable d'environnement; TZ
@code{TZ} ne doit contenir aucun espace.
@end quotation
@end cartouche

Le format standard de la variable d’environnement 
@geindex TZ
@geindex variable d'environnement; TZ
@code{TZ} est (espaces ajoutés pour plus de clarté) :

@example
std offset [dst [offset [,start[/time], end[/time]]]]
@end example

Où les composants sont :


@table @asis

@item @code{std} et @code{dst}

Trois alphanumériques ou plus donnant les abréviations du fuseau horaire. Ceux-ci seront propagés dans `time.tzname'

@item @code{offset}

Le décalage a la forme suivante : @code{± hh[:mm[:ss]]}. Cela indique la valeur ajoutée à l’heure locale pour arriver à UTC. S'il est précédé d’un @code{'-'}, le fuseau horaire est à l’est du Premier Méridien ; sinon, c’est l’ouest. Si aucun décalage ne suit `dst', l’heure d’été est supposée être en avance d’une heure sur l’heure standard.

@item @code{start[/time], end[/time]}

Indique quand passer à DST et en revenir. Le format des dates de début et de fin est l’un des suivants :


@table @asis

@item @code{J@var{n}}

Le jour Julien `n' (1 <= `n' <= 365). Les jours bissextiles ne sont pas comptabilisés. Par conséquent, le 28 février est le 59@w{^e} jour et le 1@w{^er} mars est le 60@w{^e} jour de toutes les années.

@item @code{@var{n}}

Le jour Julien de base zéro (0 <= `n' <= 365). Les jours bissextiles sont comptés et il est possible de se référer au 29 février.

@item @code{M@var{m}.@var{n}.@var{d}}

Le `d' jour (0 <= `d' <= 6) de la semaine `n' du mois `m' de l’année (1 <= `n' <= 5, 1 <= `m' <= 12, où semaine 5 signifie “le `dernier' jour du mois `m'” pouvant se produire au cours de la quatrième ou de la cinquième semaine). La semaine 1 est la première semaine au cours de laquelle le `jour' se produit. Le jour zéro est un dimanche.
@end table

@code{time} a le même format que @code{offset} sauf qu’aucun signe de direction (@code{'-'} ou @code{'+'}) n’est autorisé. La valeur par défaut, si l’heure n’est pas spécifiée, est 02:00:00.
@end table

@example
>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'
@end example

Sur de nombreux systèmes Unix (y compris *BSD, Linux, Solaris et Darwin), il est plus pratique d’utiliser la base de données `zoneinfo' (@code{tzfile (5)@footnote{https://manpages.debian.org/tzfile (5)}}) du système pour spécifier les règles de fuseau horaire. Pour ce faire, définissez la variable d’environnement 
@geindex TZ
@geindex variable d'environnement; TZ
@code{TZ} sur le chemin du fichier de fuseau horaire requis, par rapport à la racine de la base de données du système `zoneinfo', généralement situé à @code{/usr/share/zoneinfo}. Par exemple, @code{'US/Eastern'}, @code{'Australia/Melbourne'}, @code{'Egypt'} ou @code{'Europe/Amsterdam'}.

@example
>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')
@end example
@end deffn

@node Constantes d’identification d’horloge,Constantes de fuseau horaire,Fonctions<5>,time --- Time access and conversions
@anchor{library/time clock-id-constants}@anchor{2bd1}@anchor{library/time time-clock-id-constants}@anchor{2b3a}
@subsubsection Constantes d’identification d’horloge


Ces constantes sont utilisées comme paramètres pour @ref{113d,,clock_getres()} et @ref{113e,,clock_gettime()}.

@geindex CLOCK_BOOTTIME (dans le module time)
@anchor{library/time time CLOCK_BOOTTIME}@anchor{b7c}
@deffn {Données} time.CLOCK_BOOTTIME

Identique à @ref{684,,CLOCK_MONOTONIC}, sauf qu'elle inclut également toute suspension du système.

Cela permet aux applications d’obtenir une horloge monotone tenant compte de la suspension sans avoir à gérer les complications de @ref{685,,CLOCK_REALTIME}, qui peuvent présenter des discontinuités si l’heure est modifiée à l’aide de @code{settimeofday()} ou similaire.

@ref{1ce0,,Availability}: Linux >= 2.6.39.


Ajouté dans la version 3.7.

@end deffn

@geindex CLOCK_HIGHRES (dans le module time)
@anchor{library/time time CLOCK_HIGHRES}@anchor{2bd2}
@deffn {Données} time.CLOCK_HIGHRES

Le système d’exploitation Solaris dispose d’une horloge @code{CLOCK_HIGHRES} qui tente d’utiliser une source matérielle optimale et peut donner une résolution proche de la nanoseconde. @code{CLOCK_HIGHRES} est l’horloge haute résolution non ajustable.

@ref{1ce0,,Availability}: Solaris.


Ajouté dans la version 3.3.

@end deffn

@geindex CLOCK_MONOTONIC (dans le module time)
@anchor{library/time time CLOCK_MONOTONIC}@anchor{684}
@deffn {Données} time.CLOCK_MONOTONIC

Horloge qui ne peut pas être réglée et représente l’heure monotone depuis un point de départ non spécifié.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex CLOCK_MONOTONIC_RAW (dans le module time)
@anchor{library/time time CLOCK_MONOTONIC_RAW}@anchor{2bd3}
@deffn {Données} time.CLOCK_MONOTONIC_RAW

Similaire à @ref{684,,CLOCK_MONOTONIC}, mais donne accès à une heure matérielle brute qui n’est pas soumise aux ajustements NTP.

@ref{1ce0,,Availability}: Linux >= 2.6.28, macOS >= 10.12.


Ajouté dans la version 3.3.

@end deffn

@geindex CLOCK_MONOTONIC_RAW_APPROX (dans le module time)
@anchor{library/time time CLOCK_MONOTONIC_RAW_APPROX}@anchor{2bd4}
@deffn {Données} time.CLOCK_MONOTONIC_RAW_APPROX

Similar to @ref{2bd3,,CLOCK_MONOTONIC_RAW}, but reads a value cached by
the system at context switch and hence has less accuracy.

@ref{1ce0,,Availability}: macOS >= 10.12.


Ajouté dans la version 3.13.

@end deffn

@geindex CLOCK_PROCESS_CPUTIME_ID (dans le module time)
@anchor{library/time time CLOCK_PROCESS_CPUTIME_ID}@anchor{2bd5}
@deffn {Données} time.CLOCK_PROCESS_CPUTIME_ID

Minuterie haute résolution par processus du CPU.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex CLOCK_PROF (dans le module time)
@anchor{library/time time CLOCK_PROF}@anchor{b7d}
@deffn {Données} time.CLOCK_PROF

Minuterie haute résolution par processus du CPU.

@ref{1ce0,,Availability}: FreeBSD, NetBSD >= 7, OpenBSD.


Ajouté dans la version 3.7.

@end deffn

@geindex CLOCK_TAI (dans le module time)
@anchor{library/time time CLOCK_TAI}@anchor{18fa}
@deffn {Données} time.CLOCK_TAI

Temps Atomique International@footnote{https://www.nist.gov/pml/time-and-frequency-division/nist-time-frequently-asked-questions-faq#tai} (article en anglais)

Le système doit avoir un tableau des secondes intercalaires pour pouvoir donner une réponse correcte. Les logiciels PTP ou NTP savent gérer un tableau des secondes intercalaires.

@ref{1ce0,,Availability}: Linux.


Ajouté dans la version 3.9.

@end deffn

@geindex CLOCK_THREAD_CPUTIME_ID (dans le module time)
@anchor{library/time time CLOCK_THREAD_CPUTIME_ID}@anchor{2bd6}
@deffn {Données} time.CLOCK_THREAD_CPUTIME_ID

Horloge de temps CPU spécifique au fil d'exécution.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@geindex CLOCK_UPTIME (dans le module time)
@anchor{library/time time CLOCK_UPTIME}@anchor{b7e}
@deffn {Données} time.CLOCK_UPTIME

Heure dont la valeur absolue correspond à l’heure à laquelle le système a été exécuté et non suspendu, fournissant une mesure précise du temps de disponibilité, à la fois absolue et à intervalle.

@ref{1ce0,,Availability}: FreeBSD, OpenBSD >= 5.5.


Ajouté dans la version 3.7.

@end deffn

@geindex CLOCK_UPTIME_RAW (dans le module time)
@anchor{library/time time CLOCK_UPTIME_RAW}@anchor{a31}
@deffn {Données} time.CLOCK_UPTIME_RAW

Horloge qui s'incrémente de manière monotone, en suivant le temps écoulé depuis un point arbitraire, n'est pas affectée par les ajustements de fréquence ou de temps et n'est pas incrémentée lorsque le système est en veille.

@ref{1ce0,,Availability}: macOS >= 10.12.


Ajouté dans la version 3.8.

@end deffn

@geindex CLOCK_UPTIME_RAW_APPROX (dans le module time)
@anchor{library/time time CLOCK_UPTIME_RAW_APPROX}@anchor{2bd7}
@deffn {Données} time.CLOCK_UPTIME_RAW_APPROX

Like @ref{a31,,CLOCK_UPTIME_RAW}, but the value is cached by the system
at context switches and therefore has less accuracy.

@ref{1ce0,,Availability}: macOS >= 10.12.


Ajouté dans la version 3.13.

@end deffn

La constante suivante est le seul paramètre pouvant être envoyé à @ref{113f,,clock_settime()}.

@geindex CLOCK_REALTIME (dans le module time)
@anchor{library/time time CLOCK_REALTIME}@anchor{685}
@deffn {Données} time.CLOCK_REALTIME

Horloge en temps réel à l’échelle du système. Le réglage de cette horloge nécessite des privilèges appropriés.

@ref{1ce0,,Availability}: Unix.


Ajouté dans la version 3.3.

@end deffn

@node Constantes de fuseau horaire,,Constantes d’identification d’horloge,time --- Time access and conversions
@anchor{library/time time-timezone-constants}@anchor{2bd8}@anchor{library/time timezone-constants}@anchor{2bd9}
@subsubsection Constantes de fuseau horaire


@geindex altzone (dans le module time)
@anchor{library/time time altzone}@anchor{2bda}
@deffn {Données} time.altzone

Décalage du fuseau horaire DST local, en secondes à l’ouest de UTC, s’il en est défini un. Cela est négatif si le fuseau horaire DST local est à l’est de UTC (comme en Europe occidentale, y compris le Royaume-Uni). Utilisez ceci uniquement si @code{daylight} est différent de zéro. Voir note ci-dessous.
@end deffn

@geindex daylight (dans le module time)
@anchor{library/time time daylight}@anchor{2bdb}
@deffn {Données} time.daylight

Non nul si un fuseau horaire DST est défini. Voir note ci-dessous.
@end deffn

@geindex timezone (dans le module time)
@anchor{library/time time timezone}@anchor{2bdc}
@deffn {Données} time.timezone

Décalage du fuseau horaire local (hors heure d’été), en secondes à l’ouest de l’UTC (négatif dans la plupart des pays d’Europe occidentale, positif aux États-Unis, nul au Royaume-Uni). Voir note ci-dessous.
@end deffn

@geindex tzname (dans le module time)
@anchor{library/time time tzname}@anchor{2bdd}
@deffn {Données} time.tzname

Une paire de chaînes : la première est le nom du fuseau horaire local autre que DST, la seconde est le nom du fuseau horaire DST local. Si aucun fuseau horaire DST n’est défini, la deuxième chaîne ne doit pas être utilisée. Voir note ci-dessous.
@end deffn

@cartouche
@quotation Note 
For the above Timezone constants (@ref{2bda,,altzone}, @ref{2bdb,,daylight}, @ref{2bdc,,timezone},
and @ref{2bdd,,tzname}), the value is determined by the timezone rules in effect
at module load time or the last time @ref{2bd0,,tzset()} is called and may be incorrect
for times in the past.  It is recommended to use the @ref{2bc3,,tm_gmtoff} and
@ref{2bc4,,tm_zone} results from @ref{14af,,localtime()} to obtain timezone information.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item Module @ref{30,,datetime}

Interface plus orientée objet vers les dates et les heures.

@item Module @ref{85,,locale}

Services d’internationalisation. Les paramètres régionaux affectent l’interprétation de nombreux spécificateurs de format dans @ref{11c6,,strftime()} et @ref{13e3,,strptime()}.

@item Module @ref{14,,calendar}

Fonctions générales liées au calendrier. @ref{245b,,timegm()} est l’inverse de @ref{119d,,gmtime()} à partir de ce module.
@end table


@subsubheading Notes


@node logging --- Logging facility for Python,logging config --- Logging configuration,time --- Time access and conversions,Services génériques du système d'exploitation
@anchor{library/logging doc}@anchor{2bde}@anchor{library/logging logging-logging-facility-for-python}@anchor{2bdf}@anchor{library/logging module-logging}@anchor{86}
@subsection @code{logging} --- Logging facility for Python


@geindex module; logging

`Code source :' Lib/logging/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/logging/__init__.py}

@geindex Errors;logging

@subsubheading Important



Cette page contient les informations de référence de l’API. Pour des tutoriels et des discussions sur des sujets plus avancés, voir


@itemize *

@item 
@ref{11d2,,Tutoriel de découverte}

@item 
@ref{11d3,,Tutoriel avancé}

@item 
@ref{11d4,,Recettes pour la journalisation}
@end itemize


__________________________________________________________________


Ce module définit les fonctions et les classes qui mettent en œuvre un système flexible d’enregistrement des événements pour les applications et les bibliothèques.

L'intérêt principal d'utiliser une API de journalisation fournie par un module de bibliothèque standard réside dans le fait que tous les modules Python peuvent participer à la journalisation, de sorte que le journal de votre application peut inclure vos propres messages et ceux de modules tiers.

Here's a simple example of idiomatic usage:

@example
# myapp.py
import logging
import mylib
logger = logging.getLogger(__name__)

def main():
    logging.basicConfig(filename='myapp.log', level=logging.INFO)
    logger.info('Started')
    mylib.do_something()
    logger.info('Finished')

if __name__ == '__main__':
    main()
@end example

@example
# mylib.py
import logging
logger = logging.getLogger(__name__)

def do_something():
    logger.info('Doing something')
@end example

Si vous exécutez `myapp.py', vous verrez ceci dans `myapp.log' :

@example
INFO:__main__:Started
INFO:mylib:Doing something
INFO:__main__:Finished
@end example

The key feature of this idiomatic usage is that the majority of code is simply
creating a module level logger with @code{getLogger(__name__)}, and using that
logger to do any needed logging. This is concise, while allowing downstream
code fine-grained control if needed. Logged messages to the module-level logger
get forwarded to handlers of loggers in higher-level modules, all the way up to
the highest-level logger known as the root logger; this approach is known as
hierarchical logging.

For logging to be useful, it needs to be configured: setting the levels and
destinations for each logger, potentially changing how specific modules log,
often based on command-line arguments or application configuration. In most
cases, like the one above, only the root logger needs to be so configured, since
all the lower level loggers at module level eventually forward their messages to
its handlers.  @ref{9ee,,basicConfig()} provides a quick way to configure
the root logger that handles many use cases.

Ce module offre de nombreuses fonctionnalités et une grande flexibilité. Si vous n'êtes pas familier avec la journalisation, la meilleure façon de l’appréhender est de consulter les tutoriels (`voir les liens ci-dessus et à droite').

The basic classes defined by the module, together with their attributes and
methods, are listed in the sections below.


@itemize *

@item 
les enregistreurs (`loggers' en anglais) exposent l'interface que le code de l'application utilise directement ;

@item 
les gestionnaires (`handlers') envoient les entrées de journal (créées par les `loggers') vers les destinations voulues ;

@item 
les filtres (`filters') fournissent un moyen de choisir plus finement quelles entrées de journal doivent être sorties ;

@item 
les formateurs (`formatters') définissent la structure de l'entrée de journal dans la sortie finale.
@end itemize

@menu
* Enregistreurs:: 
* Niveaux de journalisation:: 
* Gestionnaires:: 
* Formateurs:: 
* Filtres: Filtres<2>. 
* Objets LogRecord:: 
* LogRecord attributes:: 
* LoggerAdapter Objects:: 
* Thread Safety:: 
* Fonctions de niveau module:: 
* Module-Level Attributes:: 
* Integration with the warnings module:: 

@end menu

@node Enregistreurs,Niveaux de journalisation,,logging --- Logging facility for Python
@anchor{library/logging logger}@anchor{2be0}@anchor{library/logging logger-objects}@anchor{2be1}
@subsubsection Enregistreurs


Les enregistreurs ont les attributs et les méthodes suivants. Notez que les enregistreurs ne doivent `JAMAIS' être instanciés directement, mais toujours par la fonction au niveau du module @code{logging.getLogger(nom)}. Les appels à @ref{94d,,getLogger()} avec le même nom renvoient toujours une référence au même objet enregistreur.

The @code{name} is potentially a period-separated hierarchical value, like
@code{foo.bar.baz} (though it could also be just plain @code{foo}, for example).
Loggers that are further down in the hierarchical list are children of loggers
higher up in the list.  For example, given a logger with a name of @code{foo},
loggers with names of @code{foo.bar}, @code{foo.bar.baz}, and @code{foo.bam} are all
descendants of @code{foo}.  In addition, all loggers are descendants of the root
logger. The logger name hierarchy is analogous to the Python package hierarchy,
and identical to it if you organise your loggers on a per-module basis using
the recommended construction @code{logging.getLogger(__name__)}.  That's because
in a module, @code{__name__} is the module's name in the Python package namespace.

@geindex Logger (classe dans logging)
@anchor{library/logging logging Logger}@anchor{b3d}
@deffn {Classe} logging.Logger

@geindex name (attribut logging.Logger)
@anchor{library/logging logging Logger name}@anchor{2be2}
@deffn {Attribut} name

This is the logger's name, and is the value that was passed to @ref{94d,,getLogger()}
to obtain the logger.

@cartouche
@quotation Note 
This attribute should be treated as read-only.
@end quotation
@end cartouche
@end deffn

@geindex level (attribut logging.Logger)
@anchor{library/logging logging Logger level}@anchor{2be3}
@deffn {Attribut} level

The threshold of this logger, as set by the @ref{1445,,setLevel()} method.

@cartouche
@quotation Note 
Do not set this attribute directly - always use @ref{1445,,setLevel()},
which has checks for the level passed to it.
@end quotation
@end cartouche
@end deffn

@geindex parent (attribut logging.Logger)
@anchor{library/logging logging Logger parent}@anchor{2be4}
@deffn {Attribut} parent

The parent logger of this logger. It may change based on later instantiation
of loggers which are higher up in the namespace hierarchy.

@cartouche
@quotation Note 
This value should be treated as read-only.
@end quotation
@end cartouche
@end deffn

@geindex propagate (attribut logging.Logger)
@anchor{library/logging logging Logger propagate}@anchor{1447}
@deffn {Attribut} propagate

Si cet attribut est évalué comme vrai, les événements enregistrés dans cet enregistreur seront transmis aux gestionnaires des enregistreurs de niveau supérieur (parents), en plus des gestionnaires attachés à l'enregistreur. Les messages sont transmis directement aux gestionnaires des enregistreurs parents — ni le niveau ni les filtres des enregistreurs parentaux en question ne sont pris en compte.

S’il s’évalue comme faux, les messages de journalisation ne sont pas transmis aux gestionnaires des enregistreurs parents.

Spelling it out with an example: If the propagate attribute of the logger named
@code{A.B.C} evaluates to true, any event logged to @code{A.B.C} via a method call such as
@code{logging.getLogger('A.B.C').error(...)} will [subject to passing that logger's
level and filter settings] be passed in turn to any handlers attached to loggers
named @code{A.B}, @code{A} and the root logger, after first being passed to any handlers
attached to @code{A.B.C}. If any logger in the chain @code{A.B.C}, @code{A.B}, @code{A} has its
@code{propagate} attribute set to false, then that is the last logger whose handlers
are offered the event to handle, and propagation stops at that point.

Le constructeur fixe cet attribut à @code{True}.

@cartouche
@quotation Note 
si vous associez un gestionnaire à un enregistreur `et' à un ou plusieurs de ses parents, il peut émettre le même enregistrement plusieurs fois. En général, il est rare d'avoir besoin d'attacher un gestionnaire à plus d'un enregistreur — si vous l'attachez simplement à l'enregistreur approprié le plus haut possible dans la hiérarchie des enregistreurs, alors il voit tous les événements enregistrés par tous les enregistreurs descendants, à condition que leur paramètre de propagation soit laissé à @code{True}. La pratique la plus courante est de n'attacher les gestionnaires qu'à l'enregistreur racine et à laisser la propagation s'occuper du reste.
@end quotation
@end cartouche
@end deffn

@geindex handlers (attribut logging.Logger)
@anchor{library/logging logging Logger handlers}@anchor{2be5}
@deffn {Attribut} handlers

The list of handlers directly attached to this logger instance.

@cartouche
@quotation Note 
This attribute should be treated as read-only; it is normally changed via
the @ref{2be6,,addHandler()} and @ref{2be7,,removeHandler()} methods, which use locks to ensure
thread-safe operation.
@end quotation
@end cartouche
@end deffn

@geindex disabled (attribut logging.Logger)
@anchor{library/logging logging Logger disabled}@anchor{2be8}
@deffn {Attribut} disabled

This attribute disables handling of any events. It is set to @code{False} in the
initializer, and only changed by logging configuration code.

@cartouche
@quotation Note 
This attribute should be treated as read-only.
@end quotation
@end cartouche
@end deffn

@geindex setLevel() (méthode logging.Logger)
@anchor{library/logging logging Logger setLevel}@anchor{1445}
@deffn {Méthode} setLevel (level)

Fixe le seuil de l'enregistreur au niveau `level'. Les messages de journalisation qui sont moins graves que `level' sont ignorés ; les messages qui ont une gravité égale à `level' ou plus élevée sont traités par le ou les gestionnaires de l'enregistreur, à moins que le niveau d'un gestionnaire n'ait été fixé à un niveau de gravité plus élevé que `level'.

Lorsqu'un enregistreur est créé, son niveau est fixé à @ref{2be9,,NOTSET} (ce qui entraîne le traitement de tous les messages lorsque l'enregistreur est l'enregistreur racine, ou la délégation au parent lorsque l'enregistreur est un enregistreur non racine). Notez que l'enregistreur racine est créé avec le niveau @ref{1c81,,WARNING}.

Le terme « délégation au parent » signifie que si un enregistreur a un niveau de @code{NOTSET}, sa chaîne d’enregistreurs parents est parcourue jusqu'à ce qu'un parent ayant un niveau autre que @code{NOTSET} soit trouvé, ou que la racine soit atteinte.

Si un parent est trouvé avec un niveau autre que NOTSET, alors le niveau de ce parent est utilisé comme le niveau effectif de l'enregistreur d'où la recherche du parent a commencé. Ce niveau est utilisé pour déterminer comment un événement d'enregistrement est traité.

Si la racine est atteinte, et qu'elle a un niveau de NOTSET, alors tous les messages sont traités. Sinon, le niveau de la racine est utilisé comme niveau effectif.

Voir @ref{645,,Niveaux de journalisation} pour la liste des niveaux.


Modifié dans la version 3.2: le paramètre `level' peut désormais être une chaîne de caractères représentant le niveau de gravité (comme @code{'INFO'}) en plus des constantes entières (comme @ref{1c80,,INFO}). Notez cependant que les niveaux sont stockés en interne sous forme d'entiers, et que des méthodes telles que @ref{2bea,,getEffectiveLevel()} et @ref{12d4,,isEnabledFor()} renvoient et s'attendent à recevoir des entiers.

@end deffn

@geindex isEnabledFor() (méthode logging.Logger)
@anchor{library/logging logging Logger isEnabledFor}@anchor{12d4}
@deffn {Méthode} isEnabledFor (level)

Indique si un message de gravité `level' est traitable par cet enregistreur. Cette méthode vérifie d'abord le niveau de gravité du module défini par @code{logging.disable(level)} et ensuite le niveau effectif de l'enregistreur, déterminé par @ref{2bea,,getEffectiveLevel()}.
@end deffn

@geindex getEffectiveLevel() (méthode logging.Logger)
@anchor{library/logging logging Logger getEffectiveLevel}@anchor{2bea}
@deffn {Méthode} getEffectiveLevel ()

Indique le niveau effectif de l'enregistreur. Si une valeur autre que @ref{2be9,,NOTSET} a été définie en utilisant @ref{1445,,setLevel()}, elle est renvoyée. Sinon, la hiérarchie est parcourue vers la racine jusqu'à ce qu'une valeur autre que @ref{2be9,,NOTSET} soit trouvée, et cette valeur est renvoyée. La valeur renvoyée est un entier, par exemple @ref{1c7f,,logging.DEBUG}, @ref{1c80,,logging.INFO}, etc.
@end deffn

@geindex getChild() (méthode logging.Logger)
@anchor{library/logging logging Logger getChild}@anchor{12d2}
@deffn {Méthode} getChild (suffix)

Renvoie un enregistreur enfant de l'enregistreur, déterminé par `suffix'. Ainsi, @code{logging.getLogger('abc').getChild('def.ghi')} renvoie le même enregistreur que @code{logging.getLogger('abc.def.ghi')}. C'est une méthode destinée à simplifier la vie du développeur. Elle est très utile quand l’enregistreur parent est nommé en utilisant, par exemple, @code{__name__} plutôt qu'une chaîne de caractères littérale.


Ajouté dans la version 3.2.

@end deffn

@geindex getChildren() (méthode logging.Logger)
@anchor{library/logging logging Logger getChildren}@anchor{1755}
@deffn {Méthode} getChildren ()

Returns a set of loggers which are immediate children of this logger. So for
example @code{logging.getLogger().getChildren()} might return a set containing
loggers named @code{foo} and @code{bar}, but a logger named @code{foo.bar} wouldn't be
included in the set. Likewise, @code{logging.getLogger('foo').getChildren()} might
return a set including a logger named @code{foo.bar}, but it wouldn't include one
named @code{foo.bar.baz}.


Ajouté dans la version 3.12.

@end deffn

@geindex debug() (méthode logging.Logger)
@anchor{library/logging logging Logger debug}@anchor{e17}
@deffn {Méthode} debug (msg, *args, **kwargs)

Enregistre un message de niveau @ref{1c7f,,DEBUG} dans cet enregistreur. `msg' est la chaîne du message qui sera formatée avec `args' en utilisant l'opérateur de formatage. Cela signifie qu'il est possible de mettre des mots-clé dans la chaîne et de passer un dictionnaire en argument. Si `args' n'est pas fourni, aucun formatage « à la % » n'est appliqué.

Quatre mots-clés de `kwargs' sont analysés : `exc_info', `stack_info', `stacklevel' et `extra'.

Si la valeur booléenne de `exc_info' est vraie, les informations des exceptions sont ajoutées au message. Si `exc_info' est un `n'-uplet d'exception (au format identique aux valeurs renvoyées par @ref{675,,sys.exc_info()}) ou une instance d'exception, sa valeur est utilisée. Dans le cas contraire, les informations sur l'exception sont déterminées par un appel à @ref{675,,sys.exc_info()}.

Le deuxième argument par mot-clé optionnel est `stack_info', valant @code{False} par défaut. S'il est vrai, les informations de la pile d'appels sont ajoutées à l'entrée de journal, en incluant aussi l'appel à la fonction de journalisation. Ce ne sont pas les mêmes informations que celles affichées en définissant `exc_info' : les premières représentent les appels de fonctions successifs, du bas de la pile jusqu'à l'appel de la fonction de journalisation dans le fil d'exécution actuel, alors que les secondes portent des informations sur les appels successifs déclenchés par la levée d'une exception et la recherche de gestionnaires pour cette exception.

Il est possible de définir `stack_info' indépendamment de `exc_info', p. ex. pour s'assurer que l'exécution a atteint un certain point dans le code, même si aucune exception n'a été levée. La pile d'appels est alors affichée après la ligne d'en-tête suivante :

@example
Stack (most recent call last):
@end example

Elle imite la ligne @code{Traceback (most recent call last):} affichée avec la pile d'appels d'une exception.

Le troisième argument par mot-clé optionnel est `stacklevel', valant @code{1} par défaut. S'il est supérieur à 1, il correspond au nombre d'entrées dans la pile qui sont ignorées en déterminant le numéro de ligne et le nom de la fonction dans la classe @ref{fd1,,LogRecord} créée pour l'évènement de journalisation. C'est utile pour les utilitaires de journalisation car cela permet d'ignorer les informations (nom de fonction, fichier source et ligne) de l'utilitaire et de ne traiter que celles de l'appelant. Le nom de ce paramètre est le même que son équivalent dans le module @ref{111,,warnings}.

The fourth keyword argument is `extra' which can be used to pass a
dictionary which is used to populate the @ref{546,,__dict__} of the
@ref{fd1,,LogRecord}
created for the logging event with user-defined attributes. These custom
attributes can then be used as you like. For example, they could be
incorporated into logged messages. For example:

@example
FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = @{'clientip': '192.168.0.1', 'user': 'fbloggs'@}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)
@end example

affiche

@example
2006-02-08 22:20:02,165 192.168.0.1 fbloggs  Protocol problem: connection reset
@end example

Les clés du dictionnaire passé dans `extra' ne doivent pas être les mêmes que les clés utilisées par le système de journalisation. Voir la documentation de la classe @ref{1449,,Formatter} pour plus de précisions sur les clés utilisées par le système de journalisation.

Si vous choisissez d'utiliser des attributs dans les messages à journaliser, il faut être prudent. Ainsi, dans l'exemple précédent, le @ref{1449,,Formatter} a été configuré avec une chaîne qui attend `clientip' et `user' dans le dictionnaire d'attributs du @ref{fd1,,LogRecord}. S'ils sont manquants, le message n'est pas enregistré car une exception de formatage de chaîne est levée. Il faut alors toujours passer un dictionnaire `extra' avec ces clés.

Même si elle peut sembler gênante, cette fonctionnalité est nécessaire dans certains cas, comme sur des serveurs à fils d'exécution multiples, où le même code s'exécute dans des contextes différents et où les évènements significatifs dépendent du contexte (comme l'adresse IP du client et le nom d'utilisateur dans l'exemple précédent). Dans ces circonstances, il est clair que les classes @ref{1449,,Formatter}s spécialisées doivent être utilisées avec des @ref{1448,,Handler}s particuliers.

If no handler is attached to this logger (or any of its ancestors,
taking into account the relevant @ref{1447,,Logger.propagate} attributes),
the message will be sent to the handler set on @ref{11d7,,lastResort}.


Modifié dans la version 3.2: ajout du paramètre `stack_info'.



Modifié dans la version 3.5: le paramètre `exc_info' peut être une instance d'exception.



Modifié dans la version 3.8: ajout du paramètre `stacklevel'.

@end deffn

@geindex info() (méthode logging.Logger)
@anchor{library/logging logging Logger info}@anchor{2beb}
@deffn {Méthode} info (msg, *args, **kwargs)

Enregistre un message avec le niveau de gravité @ref{1c80,,INFO}. Les arguments ont la même signification que pour @ref{2bec,,debug()}.
@end deffn

@geindex warning() (méthode logging.Logger)
@anchor{library/logging logging Logger warning}@anchor{168d}
@deffn {Méthode} warning (msg, *args, **kwargs)

Enregistre un message avec le niveau de gravité @ref{1c81,,WARNING}. Les arguments ont la même signification que pour @ref{2bec,,debug()}.

@cartouche
@quotation Note 
Il existe une méthode obsolète @code{warn} qui est identique à @code{warning}. @code{warn} n'est plus maintenue, prière de ne plus l'utiliser et de la remplacer par @code{warning}.
@end quotation
@end cartouche
@end deffn

@geindex error() (méthode logging.Logger)
@anchor{library/logging logging Logger error}@anchor{2bed}
@deffn {Méthode} error (msg, *args, **kwargs)

Enregistre un message avec le niveau de gravité @ref{1c82,,ERROR}. Les arguments ont la même signification que pour @ref{2bec,,debug()}.
@end deffn

@geindex critical() (méthode logging.Logger)
@anchor{library/logging logging Logger critical}@anchor{e16}
@deffn {Méthode} critical (msg, *args, **kwargs)

Enregistre un message avec le niveau de gravité @ref{1c83,,CRITICAL}. Les arguments ont la même signification que pour @ref{2bec,,debug()}.
@end deffn

@geindex log() (méthode logging.Logger)
@anchor{library/logging logging Logger log}@anchor{e14}
@deffn {Méthode} log (level, msg, *args, **kwargs)

Enregistre un message avec le niveau de gravité `level'. Les arguments ont la même signification que pour @ref{2bec,,debug()}.
@end deffn

@geindex exception() (méthode logging.Logger)
@anchor{library/logging logging Logger exception}@anchor{e15}
@deffn {Méthode} exception (msg, *args, **kwargs)

Enregistre un message avec le niveau de gravité @ref{1c82,,ERROR}. Les arguments ont la même signification que pour @ref{2bec,,debug()}. Des informations sur l'exception sont ajoutées au message. Cette méthode doit être appelée depuis un gestionnaire d'exceptions.
@end deffn

@geindex addFilter() (méthode logging.Logger)
@anchor{library/logging logging Logger addFilter}@anchor{2bee}
@deffn {Méthode} addFilter (filter)

Ajoute le filtre `filter' à l'enregistreur.
@end deffn

@geindex removeFilter() (méthode logging.Logger)
@anchor{library/logging logging Logger removeFilter}@anchor{2bef}
@deffn {Méthode} removeFilter (filter)

Retire le filtre `filter' de cet enregistreur.
@end deffn

@geindex filter() (méthode logging.Logger)
@anchor{library/logging logging Logger filter}@anchor{2bf0}
@deffn {Méthode} filter (record)

Applique les filtres associés à l'enregistreur et renvoie @code{True} si l'entrée doit être traitée. Les filtres sont appliqués les uns après les autres, jusqu'à ce que l'un renvoie faux. Si ce n'est pas le cas, le traitement de l'entrée se poursuit (elle est alors passée aux gestionnaires). Si l'un d'entre eux renvoie faux, le traitement de l'entrée s'arrête.
@end deffn

@geindex addHandler() (méthode logging.Logger)
@anchor{library/logging logging Logger addHandler}@anchor{2be6}
@deffn {Méthode} addHandler (hdlr)

Ajoute le gestionnaire `hdlr' à l'enregistreur.
@end deffn

@geindex removeHandler() (méthode logging.Logger)
@anchor{library/logging logging Logger removeHandler}@anchor{2be7}
@deffn {Méthode} removeHandler (hdlr)

Retire le gestionnaire `hdlr' de l'enregistreur.
@end deffn

@geindex findCaller() (méthode logging.Logger)
@anchor{library/logging logging Logger findCaller}@anchor{2bf1}
@deffn {Méthode} findCaller (stack_info=False, stacklevel=1)

Détermine le fichier source et la ligne de l'appelant. Renvoie un quadruplet contenant le nom du fichier source, le numéro de ligne, le nom de la fonction et la pile d'appels. La pile vaut @code{None} si `stack_info' n'est pas @code{True}.

Le paramètre `stacklevel' est passé par le code appelant @ref{2bec,,debug()} (entre autres). S'il est supérieur à 1, `n'-1 entrées de la pile sont supprimées avant de renvoyer la pile. C'est pratique quand on appelle des APIs de journalisation à travers du code d'encapsulation car cela permet de retirer les informations sur ce code de l'entrée, tout en conservant celles sur le code au-dessus du code d'encapsulation.
@end deffn

@geindex handle() (méthode logging.Logger)
@anchor{library/logging logging Logger handle}@anchor{2bf2}
@deffn {Méthode} handle (record)

Traite une entrée en la passant à tous les gestionnaires de l'enregistreur et à tous ses parents (jusqu'à ce qu'un `propagate' soit faux). C'est pratique pour désérialiser les entrées reçues d'un connecteur et celles créées localement. Du filtrage au niveau de l'enregistreur est appliqué en appelant @ref{2bf0,,filter()}.
@end deffn

@geindex makeRecord() (méthode logging.Logger)
@anchor{library/logging logging Logger makeRecord}@anchor{2bf3}
@deffn {Méthode} makeRecord (name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)

Fabrique qui peut être redéfinie pour créer des instances de @ref{fd1,,LogRecord}.
@end deffn

@geindex hasHandlers() (méthode logging.Logger)
@anchor{library/logging logging Logger hasHandlers}@anchor{2bf4}
@deffn {Méthode} hasHandlers ()

Vérifie si l'enregistreur a des gestionnaires associés. Elle recherche les gestionnaires de l'enregistreur et ceux de ses parents. Renvoie @code{True} si au moins un gestionnaire a été trouvé et @code{False} sinon. Cette méthode arrête de remonter la hiérarchie dès qu'un enregistreur avec l'attribut `propagate' à faux est rencontré ­— cet enregistreur est alors le dernier dans lequel la méthode cherche des gestionnaires.


Ajouté dans la version 3.2.

@end deffn


Modifié dans la version 3.7: les enregistreurs peuvent être sérialisés et désérialisés.

@end deffn

@node Niveaux de journalisation,Gestionnaires,Enregistreurs,logging --- Logging facility for Python
@anchor{library/logging levels}@anchor{645}@anchor{library/logging logging-levels}@anchor{2bf5}
@subsubsection Niveaux de journalisation


Les valeurs numériques des niveaux de journalisation sont données dans le tableau suivant. Celles-ci n'ont d'intérêt que si vous voulez définir vos propres niveaux, avec des valeurs spécifiques par rapport aux niveaux prédéfinis. Si vous définissez un niveau avec la même valeur numérique, il écrase la valeur prédéfinie ; le nom prédéfini est perdu.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Niveau

@tab

Valeur numérique

@tab

What it means / When to use it

@item

@geindex NOTSET (dans le module logging)
@anchor{library/logging logging NOTSET}@anchor{2be9}
@deffn {Données} logging.NOTSET
@end deffn

@tab

0

@tab

When set on a logger, indicates that
ancestor loggers are to be consulted
to determine the effective level.
If that still resolves to
@code{NOTSET}, then all events
are logged. When set on a handler,
all events are handled.

@item

@geindex DEBUG (dans le module logging)
@anchor{library/logging logging DEBUG}@anchor{1c7f}
@deffn {Données} logging.DEBUG
@end deffn

@tab

10

@tab

Detailed information, typically only
of interest to a developer trying to
diagnose a problem.

@item

@geindex INFO (dans le module logging)
@anchor{library/logging logging INFO}@anchor{1c80}
@deffn {Données} logging.INFO
@end deffn

@tab

20

@tab

Confirmation que tout fonctionne comme prévu.

@item

@geindex WARNING (dans le module logging)
@anchor{library/logging logging WARNING}@anchor{1c81}
@deffn {Données} logging.WARNING
@end deffn

@tab

30

@tab

An indication that something
unexpected happened, or that a
problem might occur in the near
future (e.g. 'disk space low'). The
software is still working as
expected.

@item

@geindex ERROR (dans le module logging)
@anchor{library/logging logging ERROR}@anchor{1c82}
@deffn {Données} logging.ERROR
@end deffn

@tab

40

@tab

Du fait d'un problème plus sérieux, le logiciel n'a pas été capable de réaliser une tâche.

@item

@geindex CRITICAL (dans le module logging)
@anchor{library/logging logging CRITICAL}@anchor{1c83}
@deffn {Données} logging.CRITICAL
@end deffn

@tab

50

@tab

Une erreur sérieuse, indiquant que le programme lui-même pourrait être incapable de continuer à fonctionner.

@end multitable


@node Gestionnaires,Formateurs,Niveaux de journalisation,logging --- Logging facility for Python
@anchor{library/logging handler}@anchor{2bf6}@anchor{library/logging handler-objects}@anchor{2bf7}
@subsubsection Gestionnaires


Handlers have the following attributes and methods. Note that @ref{1448,,Handler}
is never instantiated directly; this class acts as a base for more useful
subclasses. However, the @code{__init__()} method in subclasses needs to call
@ref{2bf8,,Handler.__init__()}.

@geindex Handler (classe dans logging)
@anchor{library/logging logging Handler}@anchor{1448}
@deffn {Classe} logging.Handler

@geindex __init__() (méthode logging.Handler)
@anchor{library/logging logging Handler __init__}@anchor{2bf8}
@deffn {Méthode} __init__ (level=NOTSET)

Initialise l'objet @ref{1448,,Handler} en définissant le niveau de gravité, en initialisant la liste des filtres avec une liste vide et en créant un verrou (avec @ref{2bf9,,createLock()}) pour sérialiser l'accès au mécanisme d'E-S.
@end deffn

@geindex createLock() (méthode logging.Handler)
@anchor{library/logging logging Handler createLock}@anchor{2bf9}
@deffn {Méthode} createLock ()

Instancie un verrou qui peut être utilisé pour sérialiser l'accès au système d'E-S sous-jacent (qui peut ne pas être à fil d'exécution sécurisé).
@end deffn

@geindex acquire() (méthode logging.Handler)
@anchor{library/logging logging Handler acquire}@anchor{2bfa}
@deffn {Méthode} acquire ()

Acquiert le verrou créé par @ref{2bf9,,createLock()}.
@end deffn

@geindex release() (méthode logging.Handler)
@anchor{library/logging logging Handler release}@anchor{2bfb}
@deffn {Méthode} release ()

Relâche le verrou acquis par @ref{2bfa,,acquire()}.
@end deffn

@geindex setLevel() (méthode logging.Handler)
@anchor{library/logging logging Handler setLevel}@anchor{2bfc}
@deffn {Méthode} setLevel (level)

Ajuste le seuil déclenchement du gestionnaire au niveau `level'. Les messages de gravité moindre que `level' sont alors ignorés. Ce seuil est fixé à @ref{2be9,,NOTSET} lors de la création d'un gestionnaire (ce qui signifie que tous les messages seront traités).

Voir @ref{645,,Niveaux de journalisation} pour la liste des niveaux.


Modifié dans la version 3.2: le paramètre `level' peut être une chaîne de caractères, comme @code{'INFO'}, en plus d'une constante entière comme @ref{1c80,,INFO}.

@end deffn

@geindex setFormatter() (méthode logging.Handler)
@anchor{library/logging logging Handler setFormatter}@anchor{2bfd}
@deffn {Méthode} setFormatter (fmt)

Définit le @ref{1449,,Formatter} du gestionnaire à `fmt'.
@end deffn

@geindex addFilter() (méthode logging.Handler)
@anchor{library/logging logging Handler addFilter}@anchor{2bfe}
@deffn {Méthode} addFilter (filter)

Ajoute le filtre `filter' au gestionnaire.
@end deffn

@geindex removeFilter() (méthode logging.Handler)
@anchor{library/logging logging Handler removeFilter}@anchor{2bff}
@deffn {Méthode} removeFilter (filter)

Retire le filtre `filter' du gestionnaire.
@end deffn

@geindex filter() (méthode logging.Handler)
@anchor{library/logging logging Handler filter}@anchor{2c00}
@deffn {Méthode} filter (record)

Applique les filtres du gestionnaire à `record' et renvoie @code{True} si l'entrée doit être traitée. Les filtres sont appliqués l'un après l'autre, jusqu'à ce que l'un renvoie faux. Si aucun d'entre eux ne renvoie faux, l'entrée est enregistrée, sinon le gestionnaire ne traitera pas l'entrée.
@end deffn

@geindex flush() (méthode logging.Handler)
@anchor{library/logging logging Handler flush}@anchor{2c01}
@deffn {Méthode} flush ()

Oblige toutes les entrées à être traitées. Cette fonction ne fait rien de spécial et doit être redéfinie par les sous-classes.
@end deffn

@geindex close() (méthode logging.Handler)
@anchor{library/logging logging Handler close}@anchor{2c02}
@deffn {Méthode} close ()

Recycle toutes les ressources utilisées par le gestionnaire. Cette version ne fait rien de particulier mais elle retire le gestionnaire de la liste interne des gestionnaires à recycler à l'appel de @ref{2c03,,shutdown()}. Les sous-classes doivent appeler cette méthode depuis leur surcharge de @ref{2c02,,close()}.
@end deffn

@geindex handle() (méthode logging.Handler)
@anchor{library/logging logging Handler handle}@anchor{2c04}
@deffn {Méthode} handle (record)

Traite ou non `record' selon les filtres ajoutés au gestionnaire. Un verrou sur l'E-S. est mis en place durant l'écriture effective.
@end deffn

@geindex handleError() (méthode logging.Handler)
@anchor{library/logging logging Handler handleError}@anchor{2c05}
@deffn {Méthode} handleError (record)

This method should be called from handlers when an exception is encountered
during an @ref{2c06,,emit()} call. If the module-level attribute
@ref{11d6,,raiseExceptions} is @code{False}, exceptions get silently ignored. This is
what is mostly wanted for a logging system - most users will not care about
errors in the logging system, they are more interested in application
errors. You could, however, replace this with a custom handler if you wish.
The specified record is the one which was being processed when the exception
occurred. (The default value of @ref{11d6,,raiseExceptions} is @code{True}, as that is
more useful during development).
@end deffn

@geindex format() (méthode logging.Handler)
@anchor{library/logging logging Handler format}@anchor{2c07}
@deffn {Méthode} format (record)

Formate `record' avec le formateur défini. S'il n'y en a pas, le formateur par défaut du module est utilisé.
@end deffn

@geindex emit() (méthode logging.Handler)
@anchor{library/logging logging Handler emit}@anchor{2c06}
@deffn {Méthode} emit (record)

Journalise `record' « pour de bon ». Cette version doit être redéfinie par les sous-classes et lève donc une @ref{225,,NotImplementedError}.

@cartouche
@quotation Avertissement 
This method is called after a handler-level lock is acquired, which
is released after this method returns. When you override this method, note
that you should be careful when calling anything that invokes other parts of
the logging API which might do locking, because that might result in a
deadlock. Specifically:


@itemize *

@item 
Logging configuration APIs acquire the module-level lock, and then
individual handler-level locks as those handlers are configured.

@item 
Many logging APIs lock the module-level lock. If such an API is called
from this method, it could cause a deadlock if a configuration call is
made on another thread, because that thread will try to acquire the
module-level lock `before' the handler-level lock, whereas this thread
tries to acquire the module-level lock `after' the handler-level lock
(because in this method, the handler-level lock has already been acquired).
@end itemize
@end quotation
@end cartouche
@end deffn
@end deffn

Les gestionnaires de la bibliothèque standard sont répertoriés dans @ref{88,,logging.handlers}.

@node Formateurs,Filtres<2>,Gestionnaires,logging --- Logging facility for Python
@anchor{library/logging formatter-objects}@anchor{2c08}@anchor{library/logging id1}@anchor{2c09}
@subsubsection Formateurs


@geindex Formatter (classe dans logging)
@anchor{library/logging logging Formatter}@anchor{1449}
@deffn {Classe} logging.Formatter (fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Responsible for converting a @ref{fd1,,LogRecord} to an output string
to be interpreted by a human or external system.

@*Paramètres: 

@itemize *

@item 
@code{fmt} (@ref{435,,str}) -- A format string in the given `style' for
the logged output as a whole.
The possible mapping keys are drawn from the @ref{fd1,,LogRecord} object's
@ref{2c0a,,LogRecord attributes}.
If not specified, @code{'%(message)s'} is used,
which is just the logged message.

@item 
@code{datefmt} (@ref{435,,str}) -- A format string in the given `style' for
the date/time portion of the logged output.
If not specified, the default described in @ref{2c0b,,formatTime()} is used.

@item 
@code{style} (@ref{435,,str}) -- Can be one of @code{'%'}, @code{'@{'} or @code{'$'} and determines
how the format string will be merged with its data: using one of
@ref{6b7,,Formatage de chaines à la printf} (@code{%}), @ref{60c,,str.format()} (@code{@{})
or @ref{672,,string.Template} (@code{$}). This only applies to
`fmt' and `datefmt' (e.g. @code{'%(message)s'} versus @code{'@{message@}'}),
not to the actual log messages passed to the logging methods.
However, there are @ref{2c0c,,other ways}
to use @code{@{}- and @code{$}-formatting for log messages.

@item 
@code{validate} (@ref{451,,bool}) -- If @code{True} (the default), incorrect or mismatched
`fmt' and `style' will raise a @ref{1ff,,ValueError}; for example,
@code{logging.Formatter('%(asctime)s - %(message)s', style='@{')}.

@item 
@code{defaults} (@ref{253,,dict}@code{[}@ref{435,,str}@code{, }@code{Any}@code{]}) -- A dictionary with default values to use in custom fields.
For example,
@code{logging.Formatter('%(ip)s %(message)s', defaults=@{"ip": None@})}
@end itemize



Modifié dans la version 3.2: Added the `style' parameter.



Modifié dans la version 3.8: Added the `validate' parameter.



Modifié dans la version 3.10: Added the `defaults' parameter.


@geindex format() (méthode logging.Formatter)
@anchor{library/logging logging Formatter format}@anchor{2c0d}
@deffn {Méthode} format (record)

The record's attribute dictionary is used as the operand to a string
formatting operation. Returns the resulting string. Before formatting the
dictionary, a couple of preparatory steps are carried out. The `message'
attribute of the record is computed using `msg' % `args'. If the
formatting string contains @code{'(asctime)'}, @ref{2c0b,,formatTime()} is called
to format the event time. If there is exception information, it is
formatted using @ref{2c0e,,formatException()} and appended to the message. Note
that the formatted exception information is cached in attribute
`exc_text'. This is useful because the exception information can be
pickled and sent across the wire, but you should be careful if you have
more than one @ref{1449,,Formatter} subclass which customizes the formatting
of exception information. In this case, you will have to clear the cached
value (by setting the `exc_text' attribute to @code{None}) after a formatter
has done its formatting, so that the next formatter to handle the event
doesn't use the cached value, but recalculates it afresh.

If stack information is available, it's appended after the exception
information, using @ref{2c0f,,formatStack()} to transform it if necessary.
@end deffn

@geindex formatTime() (méthode logging.Formatter)
@anchor{library/logging logging Formatter formatTime}@anchor{2c0b}
@deffn {Méthode} formatTime (record, datefmt=None)

This method should be called from @ref{60a,,format()} by a formatter which
wants to make use of a formatted time. This method can be overridden in
formatters to provide for any specific requirement, but the basic behavior
is as follows: if `datefmt' (a string) is specified, it is used with
@ref{11c6,,time.strftime()} to format the creation time of the
record. Otherwise, the format '%Y-%m-%d %H:%M:%S,uuu' is used, where the
uuu part is a millisecond value and the other letters are as per the
@ref{11c6,,time.strftime()} documentation.  An example time in this format is
@code{2003-01-23 00:29:50,411}.  The resulting string is returned.

This function uses a user-configurable function to convert the creation
time to a tuple. By default, @ref{14af,,time.localtime()} is used; to change
this for a particular formatter instance, set the @code{converter} attribute
to a function with the same signature as @ref{14af,,time.localtime()} or
@ref{119d,,time.gmtime()}. To change it for all formatters, for example if you
want all logging times to be shown in GMT, set the @code{converter}
attribute in the @code{Formatter} class.


Modifié dans la version 3.3: Previously, the default format was hard-coded as in this example:
@code{2010-09-06 22:38:15,292} where the part before the comma is
handled by a strptime format string (@code{'%Y-%m-%d %H:%M:%S'}), and the
part after the comma is a millisecond value. Because strptime does not
have a format placeholder for milliseconds, the millisecond value is
appended using another format string, @code{'%s,%03d'} --- and both of these
format strings have been hardcoded into this method. With the change,
these strings are defined as class-level attributes which can be
overridden at the instance level when desired. The names of the
attributes are @code{default_time_format} (for the strptime format string)
and @code{default_msec_format} (for appending the millisecond value).



Modifié dans la version 3.9: The @code{default_msec_format} can be @code{None}.

@end deffn

@geindex formatException() (méthode logging.Formatter)
@anchor{library/logging logging Formatter formatException}@anchor{2c0e}
@deffn {Méthode} formatException (exc_info)

Formats the specified exception information (a standard exception tuple as
returned by @ref{675,,sys.exc_info()}) as a string. This default implementation
just uses @ref{839,,traceback.print_exception()}. The resulting string is
returned.
@end deffn

@geindex formatStack() (méthode logging.Formatter)
@anchor{library/logging logging Formatter formatStack}@anchor{2c0f}
@deffn {Méthode} formatStack (stack_info)

Formats the specified stack information (a string as returned by
@ref{e71,,traceback.print_stack()}, but with the last newline removed) as a
string. This default implementation just returns the input value.
@end deffn
@end deffn

@geindex BufferingFormatter (classe dans logging)
@anchor{library/logging logging BufferingFormatter}@anchor{2c10}
@deffn {Classe} logging.BufferingFormatter (linefmt=None)

A base formatter class suitable for subclassing when you want to format a
number of records. You can pass a @ref{1449,,Formatter} instance which you want
to use to format each line (that corresponds to a single record). If not
specified, the default formatter (which just outputs the event message) is
used as the line formatter.

@geindex formatHeader() (méthode logging.BufferingFormatter)
@anchor{library/logging logging BufferingFormatter formatHeader}@anchor{2c11}
@deffn {Méthode} formatHeader (records)

Return a header for a list of `records'. The base implementation just
returns the empty string. You will need to override this method if you
want specific behaviour, e.g. to show the count of records, a title or a
separator line.
@end deffn

@geindex formatFooter() (méthode logging.BufferingFormatter)
@anchor{library/logging logging BufferingFormatter formatFooter}@anchor{2c12}
@deffn {Méthode} formatFooter (records)

Return a footer for a list of `records'. The base implementation just
returns the empty string. You will need to override this method if you
want specific behaviour, e.g. to show the count of records or a separator
line.
@end deffn

@geindex format() (méthode logging.BufferingFormatter)
@anchor{library/logging logging BufferingFormatter format}@anchor{2c13}
@deffn {Méthode} format (records)

Return formatted text for a list of `records'. The base implementation
just returns the empty string if there are no records; otherwise, it
returns the concatenation of the header, each record formatted with the
line formatter, and the footer.
@end deffn
@end deffn

@node Filtres<2>,Objets LogRecord,Formateurs,logging --- Logging facility for Python
@anchor{library/logging filter}@anchor{2c14}@anchor{library/logging filter-objects}@anchor{2c15}
@subsubsection Filtres


@code{Filters} can be used by @code{Handlers} and @code{Loggers} for more sophisticated
filtering than is provided by levels. The base filter class only allows events
which are below a certain point in the logger hierarchy. For example, a filter
initialized with 'A.B' will allow events logged by loggers 'A.B', 'A.B.C',
'A.B.C.D', 'A.B.D' etc. but not 'A.BB', 'B.A.B' etc. If initialized with the
empty string, all events are passed.

@geindex Filter (classe dans logging)
@anchor{library/logging logging Filter}@anchor{11d8}
@deffn {Classe} logging.Filter (name='@w{'})

Returns an instance of the @ref{11d8,,Filter} class. If `name' is specified, it
names a logger which, together with its children, will have its events allowed
through the filter. If `name' is the empty string, allows every event.

@geindex filter() (méthode logging.Filter)
@anchor{library/logging logging Filter filter}@anchor{2c16}
@deffn {Méthode} filter (record)

Is the specified record to be logged? Returns false for no, true for
yes. Filters can either modify log records in-place or return a completely
different record instance which will replace the original
log record in any future processing of the event.
@end deffn
@end deffn

Note that filters attached to handlers are consulted before an event is
emitted by the handler, whereas filters attached to loggers are consulted
whenever an event is logged (using @ref{2bec,,debug()}, @ref{2c17,,info()},
etc.), before sending an event to handlers. This means that events which have
been generated by descendant loggers will not be filtered by a logger's filter
setting, unless the filter has also been applied to those descendant loggers.

You don't actually need to subclass @code{Filter}: you can pass any instance
which has a @code{filter} method with the same semantics.


Modifié dans la version 3.2: You don't need to create specialized @code{Filter} classes, or use other
classes with a @code{filter} method: you can use a function (or other
callable) as a filter. The filtering logic will check to see if the filter
object has a @code{filter} attribute: if it does, it's assumed to be a
@code{Filter} and its @ref{2c16,,filter()} method is called. Otherwise, it's
assumed to be a callable and called with the record as the single
parameter. The returned value should conform to that returned by
@ref{2c16,,filter()}.



Modifié dans la version 3.12: You can now return a @ref{fd1,,LogRecord} instance from filters to replace
the log record rather than modifying it in place. This allows filters attached to
a @ref{1448,,Handler} to modify the log record before it is emitted, without
having side effects on other handlers.


Although filters are used primarily to filter records based on more
sophisticated criteria than levels, they get to see every record which is
processed by the handler or logger they're attached to: this can be useful if
you want to do things like counting how many records were processed by a
particular logger or handler, or adding, changing or removing attributes in
the @ref{fd1,,LogRecord} being processed. Obviously changing the LogRecord needs
to be done with some care, but it does allow the injection of contextual
information into logs (see @ref{2c18,,Utilisation de filtres pour transmettre des informations contextuelles}).

@node Objets LogRecord,LogRecord attributes,Filtres<2>,logging --- Logging facility for Python
@anchor{library/logging log-record}@anchor{2c19}@anchor{library/logging logrecord-objects}@anchor{2c1a}
@subsubsection Objets LogRecord


@ref{fd1,,LogRecord} instances are created automatically by the @ref{b3d,,Logger}
every time something is logged, and can be created manually via
@ref{2c1b,,makeLogRecord()} (for example, from a pickled event received over the
wire).

@geindex LogRecord (classe dans logging)
@anchor{library/logging logging LogRecord}@anchor{fd1}
@deffn {Classe} logging.LogRecord (name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)

Contains all the information pertinent to the event being logged.

The primary information is passed in `msg' and `args',
which are combined using @code{msg % args} to create
the @code{message} attribute of the record.

@*Paramètres: 

@itemize *

@item 
@code{name} (@ref{435,,str}) -- The name of the logger used to log the event
represented by this @code{LogRecord}.
Note that the logger name in the @code{LogRecord}
will always have this value,
even though it may be emitted by a handler
attached to a different (ancestor) logger.

@item 
@code{level} (@ref{254,,int}) -- The @ref{645,,numeric level} of the logging event
(such as @code{10} for @code{DEBUG}, @code{20} for @code{INFO}, etc).
Note that this is converted to `two' attributes of the LogRecord:
@code{levelno} for the numeric value
and @code{levelname} for the corresponding level name.

@item 
@code{pathname} (@ref{435,,str}) -- The full string path of the source file
where the logging call was made.

@item 
@code{lineno} (@ref{254,,int}) -- The line number in the source file
where the logging call was made.

@item 
@code{msg} (@ref{697,,Any}) -- The event description message,
which can be a %-format string with placeholders for variable data,
or an arbitrary object (see @ref{2c1c,,Utilisation d'objets arbitraires comme messages}).

@item 
@code{args} (@ref{366,,tuple}@code{ | }@ref{253,,dict}@code{[}@ref{435,,str}@code{, }@ref{697,,Any}@code{]}) -- Variable data to merge into the `msg' argument
to obtain the event description.

@item 
@code{exc_info} (@ref{366,,tuple}@code{[}@ref{d36,,type}@code{[}@ref{5a5,,BaseException}@code{]}@code{, }@ref{5a5,,BaseException}@code{, }@ref{ae0,,types.TracebackType}@code{] }@code{| }@code{None}) -- An exception tuple with the current exception information,
as returned by @ref{675,,sys.exc_info()},
or @code{None} if no exception information is available.

@item 
@code{func} (@ref{435,,str}@code{ | }@code{None}) -- The name of the function or method
from which the logging call was invoked.

@item 
@code{sinfo} (@ref{435,,str}@code{ | }@code{None}) -- A text string representing stack information
from the base of the stack in the current thread,
up to the logging call.
@end itemize


@geindex getMessage() (méthode logging.LogRecord)
@anchor{library/logging logging LogRecord getMessage}@anchor{2c1d}
@deffn {Méthode} getMessage ()

Returns the message for this @ref{fd1,,LogRecord} instance after merging any
user-supplied arguments with the message. If the user-supplied message
argument to the logging call is not a string, @ref{435,,str()} is called on it to
convert it to a string. This allows use of user-defined classes as
messages, whose @code{__str__} method can return the actual format string to
be used.
@end deffn


Modifié dans la version 3.2: The creation of a @ref{fd1,,LogRecord} has been made more configurable by
providing a factory which is used to create the record. The factory can be
set using @ref{2c1e,,getLogRecordFactory()} and @ref{2c1f,,setLogRecordFactory()}
(see this for the factory's signature).


This functionality can be used to inject your own values into a
@ref{fd1,,LogRecord} at creation time. You can use the following pattern:

@example
old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)
@end example

With this pattern, multiple factories could be chained, and as long
as they don't overwrite each other's attributes or unintentionally
overwrite the standard attributes listed above, there should be no
surprises.
@end deffn

@node LogRecord attributes,LoggerAdapter Objects,Objets LogRecord,logging --- Logging facility for Python
@anchor{library/logging id2}@anchor{2c20}@anchor{library/logging logrecord-attributes}@anchor{2c0a}
@subsubsection LogRecord attributes


The LogRecord has a number of attributes, most of which are derived from the
parameters to the constructor. (Note that the names do not always correspond
exactly between the LogRecord constructor parameters and the LogRecord
attributes.) These attributes can be used to merge data from the record into
the format string. The following table lists (in alphabetical order) the
attribute names, their meanings and the corresponding placeholder in a %-style
format string.

If you are using @{@}-formatting (@ref{60c,,str.format()}), you can use
@code{@{attrname@}} as the placeholder in the format string. If you are using
$-formatting (@ref{672,,string.Template}), use the form @code{$@{attrname@}}. In
both cases, of course, replace @code{attrname} with the actual attribute name
you want to use.

In the case of @{@}-formatting, you can specify formatting flags by placing them
after the attribute name, separated from it with a colon. For example: a
placeholder of @code{@{msecs:03.0f@}} would format a millisecond value of @code{4} as
@code{004}. Refer to the @ref{60c,,str.format()} documentation for full details on
the options available to you.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribute name

@tab

Format

@tab

Description

@item

args

@tab

You shouldn't need to
format this yourself.

@tab

The tuple of arguments merged into @code{msg} to
produce @code{message}, or a dict whose values
are used for the merge (when there is only one
argument, and it is a dictionary).

@item

asctime

@tab

@code{%(asctime)s}

@tab

Human-readable time when the
@ref{fd1,,LogRecord} was created.  By default
this is of the form '2003-07-08 16:49:45,896'
(the numbers after the comma are millisecond
portion of the time).

@item

created

@tab

@code{%(created)f}

@tab

Time when the @ref{fd1,,LogRecord} was created
(as returned by @ref{ad5,,time.time_ns()} / 1e9).

@item

exc_info

@tab

You shouldn't need to
format this yourself.

@tab

Exception tuple (à la @code{sys.exc_info}) or,
if no exception has occurred, @code{None}.

@item

filename

@tab

@code{%(filename)s}

@tab

Filename portion of @code{pathname}.

@item

funcName

@tab

@code{%(funcName)s}

@tab

Name of function containing the logging call.

@item

levelname

@tab

@code{%(levelname)s}

@tab

Text logging level for the message
(@code{'DEBUG'}, @code{'INFO'}, @code{'WARNING'},
@code{'ERROR'}, @code{'CRITICAL'}).

@item

levelno

@tab

@code{%(levelno)s}

@tab

Numeric logging level for the message
(@ref{1c7f,,DEBUG}, @ref{1c80,,INFO},
@ref{1c81,,WARNING}, @ref{1c82,,ERROR},
@ref{1c83,,CRITICAL}).

@item

lineno

@tab

@code{%(lineno)d}

@tab

Source line number where the logging call was
issued (if available).

@item

message

@tab

@code{%(message)s}

@tab

The logged message, computed as @code{msg %
args}. This is set when
@ref{2c0d,,Formatter.format()} is invoked.

@item

module

@tab

@code{%(module)s}

@tab

Module (name portion of @code{filename}).

@item

msecs

@tab

@code{%(msecs)d}

@tab

Millisecond portion of the time when the
@ref{fd1,,LogRecord} was created.

@item

msg

@tab

You shouldn't need to
format this yourself.

@tab

The format string passed in the original
logging call. Merged with @code{args} to
produce @code{message}, or an arbitrary object
(see @ref{2c1c,,Utilisation d'objets arbitraires comme messages}).

@item

nom

@tab

@code{%(name)s}

@tab

Name of the logger used to log the call.

@item

pathname

@tab

@code{%(pathname)s}

@tab

Full pathname of the source file where the
logging call was issued (if available).

@item

process

@tab

@code{%(process)d}

@tab

Process ID (if available).

@item

processName

@tab

@code{%(processName)s}

@tab

Process name (if available).

@item

relativeCreated

@tab

@code{%(relativeCreated)d}

@tab

Time in milliseconds when the LogRecord was
created, relative to the time the logging
module was loaded.

@item

stack_info

@tab

You shouldn't need to
format this yourself.

@tab

Stack frame information (where available)
from the bottom of the stack in the current
thread, up to and including the stack frame
of the logging call which resulted in the
creation of this record.

@item

thread

@tab

@code{%(thread)d}

@tab

Thread ID (if available).

@item

threadName

@tab

@code{%(threadName)s}

@tab

Thread name (if available).

@item

taskName

@tab

@code{%(taskName)s}

@tab

@ref{4c2,,asyncio.Task} name (if available).

@end multitable



Modifié dans la version 3.1: `processName' was added.



Modifié dans la version 3.12: `taskName' was added.


@node LoggerAdapter Objects,Thread Safety,LogRecord attributes,logging --- Logging facility for Python
@anchor{library/logging logger-adapter}@anchor{2c21}@anchor{library/logging loggeradapter-objects}@anchor{2c22}
@subsubsection LoggerAdapter Objects


@ref{12d3,,LoggerAdapter} instances are used to conveniently pass contextual
information into logging calls. For a usage example, see the section on
@ref{2c23,,adding contextual information to your logging output}.

@geindex LoggerAdapter (classe dans logging)
@anchor{library/logging logging LoggerAdapter}@anchor{12d3}
@deffn {Classe} logging.LoggerAdapter (logger, extra, merge_extra=False)

Returns an instance of @ref{12d3,,LoggerAdapter} initialized with an
underlying @ref{b3d,,Logger} instance, a dict-like object (`extra'), and a
boolean (`merge_extra') indicating whether or not the `extra' argument of
individual log calls should be merged with the @ref{12d3,,LoggerAdapter} extra.
The default behavior is to ignore the `extra' argument of individual log
calls and only use the one of the @ref{12d3,,LoggerAdapter} instance

@geindex process() (méthode logging.LoggerAdapter)
@anchor{library/logging logging LoggerAdapter process}@anchor{2c24}
@deffn {Méthode} process (msg, kwargs)

Modifies the message and/or keyword arguments passed to a logging call in
order to insert contextual information. This implementation takes the object
passed as `extra' to the constructor and adds it to `kwargs' using key
'extra'. The return value is a (`msg', `kwargs') tuple which has the
(possibly modified) versions of the arguments passed in.
@end deffn

@geindex manager (attribut logging.LoggerAdapter)
@anchor{library/logging logging LoggerAdapter manager}@anchor{2c25}
@deffn {Attribut} manager

Delegates to the underlying @code{manager} on `logger'.
@end deffn

@geindex _log (attribut logging.LoggerAdapter)
@anchor{library/logging logging LoggerAdapter _log}@anchor{2c26}
@deffn {Attribut} _log

Delegates to the underlying @code{_log()} method on `logger'.
@end deffn

In addition to the above, @ref{12d3,,LoggerAdapter} supports the following
methods of @ref{b3d,,Logger}: @ref{e17,,debug()}, @ref{2beb,,info()},
@ref{168d,,warning()}, @ref{2bed,,error()}, @ref{e15,,exception()},
@ref{e16,,critical()}, @ref{e14,,log()}, @ref{12d4,,isEnabledFor()},
@ref{2bea,,getEffectiveLevel()}, @ref{1445,,setLevel()} and
@ref{2bf4,,hasHandlers()}. These methods have the same signatures as their
counterparts in @ref{b3d,,Logger}, so you can use the two types of instances
interchangeably.


Modifié dans la version 3.2: The @ref{12d4,,isEnabledFor()}, @ref{2bea,,getEffectiveLevel()},
@ref{1445,,setLevel()} and @ref{2bf4,,hasHandlers()} methods were added
to @ref{12d3,,LoggerAdapter}.  These methods delegate to the underlying logger.



Modifié dans la version 3.6: Attribute @code{manager} and method @code{_log()} were added, which
delegate to the underlying logger and allow adapters to be nested.



Modifié dans la version 3.13: The `merge_extra' argument was added.

@end deffn

@node Thread Safety,Fonctions de niveau module,LoggerAdapter Objects,logging --- Logging facility for Python
@anchor{library/logging thread-safety}@anchor{2c27}
@subsubsection Thread Safety


The logging module is intended to be thread-safe without any special work
needing to be done by its clients. It achieves this though using threading
locks; there is one lock to serialize access to the module's shared data, and
each handler also creates a lock to serialize access to its underlying I/O.

If you are implementing asynchronous signal handlers using the @ref{c5,,signal}
module, you may not be able to use logging from within such handlers. This is
because lock implementations in the @ref{ec,,threading} module are not always
re-entrant, and so cannot be invoked from such signal handlers.

@node Fonctions de niveau module,Module-Level Attributes,Thread Safety,logging --- Logging facility for Python
@anchor{library/logging module-level-functions}@anchor{2c28}
@subsubsection Fonctions de niveau module


In addition to the classes described above, there are a number of module-level
functions.

@geindex getLogger() (dans le module logging)
@anchor{library/logging logging getLogger}@anchor{94d}
@deffn {Fonction} logging.getLogger (name=None)

Return a logger with the specified name or, if name is @code{None}, return the
root logger of the hierarchy. If specified, the name is typically a
dot-separated hierarchical name like `'a'', `'a.b'' or `'a.b.c.d''. Choice
of these names is entirely up to the developer who is using logging, though
it is recommended that @code{__name__} be used unless you have a specific
reason for not doing that, as mentioned in @ref{2be0,,Enregistreurs}.

All calls to this function with a given name return the same logger instance.
This means that logger instances never need to be passed between different parts
of an application.
@end deffn

@geindex getLoggerClass() (dans le module logging)
@anchor{library/logging logging getLoggerClass}@anchor{2c29}
@deffn {Fonction} logging.getLoggerClass ()

Return either the standard @ref{b3d,,Logger} class, or the last class passed to
@ref{2c2a,,setLoggerClass()}. This function may be called from within a new class
definition, to ensure that installing a customized @ref{b3d,,Logger} class will
not undo customizations already applied by other code. For example:

@example
class MyLogger(logging.getLoggerClass()):
    # ... override behaviour here
@end example
@end deffn

@geindex getLogRecordFactory() (dans le module logging)
@anchor{library/logging logging getLogRecordFactory}@anchor{2c1e}
@deffn {Fonction} logging.getLogRecordFactory ()

Return a callable which is used to create a @ref{fd1,,LogRecord}.


Ajouté dans la version 3.2: This function has been provided, along with @ref{2c1f,,setLogRecordFactory()},
to allow developers more control over how the @ref{fd1,,LogRecord}
representing a logging event is constructed.


See @ref{2c1f,,setLogRecordFactory()} for more information about the how the
factory is called.
@end deffn

@geindex debug() (dans le module logging)
@anchor{library/logging logging debug}@anchor{2bec}
@deffn {Fonction} logging.debug (msg, *args, **kwargs)

This is a convenience function that calls @ref{e17,,Logger.debug()}, on the root
logger. The handling of the arguments is in every way identical
to what is described in that method.

The only difference is that if the root logger has no handlers, then
@ref{9ee,,basicConfig()} is called, prior to calling @code{debug} on the root logger.

For very short scripts or quick demonstrations of @code{logging} facilities,
@code{debug} and the other module-level functions may be convenient. However,
most programs will want to carefully and explicitly control the logging
configuration, and should therefore prefer creating a module-level logger and
calling @ref{e17,,Logger.debug()} (or other level-specific methods) on it, as
described at the beginnning of this documentation.
@end deffn

@geindex info() (dans le module logging)
@anchor{library/logging logging info}@anchor{2c17}
@deffn {Fonction} logging.info (msg, *args, **kwargs)

Logs a message with level @ref{1c80,,INFO} on the root logger. The arguments and behavior
are otherwise the same as for @ref{2bec,,debug()}.
@end deffn

@geindex warning() (dans le module logging)
@anchor{library/logging logging warning}@anchor{2f3}
@deffn {Fonction} logging.warning (msg, *args, **kwargs)

Logs a message with level @ref{1c81,,WARNING} on the root logger. The arguments and behavior
are otherwise the same as for @ref{2bec,,debug()}.

@cartouche
@quotation Note 
There is an obsolete function @code{warn} which is functionally
identical to @code{warning}. As @code{warn} is deprecated, please do not use
it - use @code{warning} instead.
@end quotation
@end cartouche
@end deffn

@geindex error() (dans le module logging)
@anchor{library/logging logging error}@anchor{2c2b}
@deffn {Fonction} logging.error (msg, *args, **kwargs)

Logs a message with level @ref{1c82,,ERROR} on the root logger. The arguments and behavior
are otherwise the same as for @ref{2bec,,debug()}.
@end deffn

@geindex critical() (dans le module logging)
@anchor{library/logging logging critical}@anchor{2c2c}
@deffn {Fonction} logging.critical (msg, *args, **kwargs)

Logs a message with level @ref{1c83,,CRITICAL} on the root logger. The arguments and behavior
are otherwise the same as for @ref{2bec,,debug()}.
@end deffn

@geindex exception() (dans le module logging)
@anchor{library/logging logging exception}@anchor{1446}
@deffn {Fonction} logging.exception (msg, *args, **kwargs)

Logs a message with level @ref{1c82,,ERROR} on the root logger. The arguments and behavior
are otherwise the same as for @ref{2bec,,debug()}. Exception info is added to the logging
message. This function should only be called from an exception handler.
@end deffn

@geindex log() (dans le module logging)
@anchor{library/logging logging log}@anchor{2c2d}
@deffn {Fonction} logging.log (level, msg, *args, **kwargs)

Logs a message with level `level' on the root logger. The arguments and behavior
are otherwise the same as for @ref{2bec,,debug()}.
@end deffn

@geindex disable() (dans le module logging)
@anchor{library/logging logging disable}@anchor{2c2e}
@deffn {Fonction} logging.disable (level=CRITICAL)

Provides an overriding level `level' for all loggers which takes precedence over
the logger's own level. When the need arises to temporarily throttle logging
output down across the whole application, this function can be useful. Its
effect is to disable all logging calls of severity `level' and below, so that
if you call it with a value of INFO, then all INFO and DEBUG events would be
discarded, whereas those of severity WARNING and above would be processed
according to the logger's effective level. If
@code{logging.disable(logging.NOTSET)} is called, it effectively removes this
overriding level, so that logging output again depends on the effective
levels of individual loggers.

Note that if you have defined any custom logging level higher than
@code{CRITICAL} (this is not recommended), you won't be able to rely on the
default value for the `level' parameter, but will have to explicitly supply a
suitable value.


Modifié dans la version 3.7: The `level' parameter was defaulted to level @code{CRITICAL}. See
bpo-28524@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=28524} for more information about this change.

@end deffn

@geindex addLevelName() (dans le module logging)
@anchor{library/logging logging addLevelName}@anchor{2c2f}
@deffn {Fonction} logging.addLevelName (level, levelName)

Associates level `level' with text `levelName' in an internal dictionary, which is
used to map numeric levels to a textual representation, for example when a
@ref{1449,,Formatter} formats a message. This function can also be used to define
your own levels. The only constraints are that all levels used must be
registered using this function, levels should be positive integers and they
should increase in increasing order of severity.

@cartouche
@quotation Note 
If you are thinking of defining your own levels, please see the
section on @ref{2c30,,Niveaux personnalisés}.
@end quotation
@end cartouche
@end deffn

@geindex getLevelNamesMapping() (dans le module logging)
@anchor{library/logging logging getLevelNamesMapping}@anchor{644}
@deffn {Fonction} logging.getLevelNamesMapping ()

Returns a mapping from level names to their corresponding logging levels. For example, the
string "CRITICAL" maps to @ref{1c83,,CRITICAL}. The returned mapping is copied from an internal
mapping on each call to this function.


Ajouté dans la version 3.11.

@end deffn

@geindex getLevelName() (dans le module logging)
@anchor{library/logging logging getLevelName}@anchor{2c31}
@deffn {Fonction} logging.getLevelName (level)

Returns the textual or numeric representation of logging level `level'.

If `level' is one of the predefined levels @ref{1c83,,CRITICAL}, @ref{1c82,,ERROR},
@ref{1c81,,WARNING}, @ref{1c80,,INFO} or @ref{1c7f,,DEBUG} then you get the
corresponding string. If you have associated levels with names using
@ref{2c2f,,addLevelName()} then the name you have associated with `level' is
returned. If a numeric value corresponding to one of the defined levels is
passed in, the corresponding string representation is returned.

The `level' parameter also accepts a string representation of the level such
as 'INFO'. In such cases, this functions returns the corresponding numeric
value of the level.

If no matching numeric or string value is passed in, the string
'Level %s' % level is returned.

@cartouche
@quotation Note 
Levels are internally integers (as they need to be compared in the
logging logic). This function is used to convert between an integer level
and the level name displayed in the formatted log output by means of the
@code{%(levelname)s} format specifier (see @ref{2c0a,,LogRecord attributes}), and
vice versa.
@end quotation
@end cartouche


Modifié dans la version 3.4: In Python versions earlier than 3.4, this function could also be passed a
text level, and would return the corresponding numeric value of the level.
This undocumented behaviour was considered a mistake, and was removed in
Python 3.4, but reinstated in 3.4.2 due to retain backward compatibility.

@end deffn

@geindex getHandlerByName() (dans le module logging)
@anchor{library/logging logging getHandlerByName}@anchor{1766}
@deffn {Fonction} logging.getHandlerByName (name)

Returns a handler with the specified `name', or @code{None} if there is no handler
with that name.


Ajouté dans la version 3.12.

@end deffn

@geindex getHandlerNames() (dans le module logging)
@anchor{library/logging logging getHandlerNames}@anchor{1687}
@deffn {Fonction} logging.getHandlerNames ()

Returns an immutable set of all known handler names.


Ajouté dans la version 3.12.

@end deffn

@geindex makeLogRecord() (dans le module logging)
@anchor{library/logging logging makeLogRecord}@anchor{2c1b}
@deffn {Fonction} logging.makeLogRecord (attrdict)

Creates and returns a new @ref{fd1,,LogRecord} instance whose attributes are
defined by `attrdict'. This function is useful for taking a pickled
@ref{fd1,,LogRecord} attribute dictionary, sent over a socket, and reconstituting
it as a @ref{fd1,,LogRecord} instance at the receiving end.
@end deffn

@geindex basicConfig() (dans le module logging)
@anchor{library/logging logging basicConfig}@anchor{9ee}
@deffn {Fonction} logging.basicConfig (**kwargs)

Does basic configuration for the logging system by creating a
@ref{11d5,,StreamHandler} with a default @ref{1449,,Formatter} and adding it to the
root logger. The functions @ref{2bec,,debug()}, @ref{2c17,,info()}, @ref{2f3,,warning()},
@ref{2c2b,,error()} and @ref{2c2c,,critical()} will call @ref{9ee,,basicConfig()} automatically
if no handlers are defined for the root logger.

This function does nothing if the root logger already has handlers
configured, unless the keyword argument `force' is set to @code{True}.

@cartouche
@quotation Note 
This function should be called from the main thread
before other threads are started. In versions of Python prior to
2.7.1 and 3.2, if this function is called from multiple threads,
it is possible (in rare circumstances) that a handler will be added
to the root logger more than once, leading to unexpected results
such as messages being duplicated in the log.
@end quotation
@end cartouche

The following keyword arguments are supported.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Format

@tab

Description

@item

`filename'

@tab

Specifies that a @ref{182c,,FileHandler} be
created, using the specified filename,
rather than a @ref{11d5,,StreamHandler}.

@item

`filemode'

@tab

If `filename' is specified, open the file
in this @ref{20ff,,mode}. Defaults
to @code{'a'}.

@item

`format'

@tab

Use the specified format string for the
handler. Defaults to attributes
@code{levelname}, @code{name} and @code{message}
separated by colons.

@item

`datefmt'

@tab

Use the specified date/time format, as
accepted by @ref{11c6,,time.strftime()}.

@item

`style'

@tab

If `format' is specified, use this style
for the format string. One of @code{'%'},
@code{'@{'} or @code{'$'} for @ref{6b7,,printf-style},
@ref{60c,,str.format()} or
@ref{672,,string.Template} respectively.
Defaults to @code{'%'}.

@item

`level'

@tab

Set the root logger level to the specified
@ref{645,,level}.

@item

`stream'

@tab

Use the specified stream to initialize the
@ref{11d5,,StreamHandler}. Note that this
argument is incompatible with `filename' -
if both are present, a @code{ValueError} is
raised.

@item

`handlers'

@tab

If specified, this should be an iterable of
already created handlers to add to the root
logger. Any handlers which don't already
have a formatter set will be assigned the
default formatter created in this function.
Note that this argument is incompatible
with `filename' or `stream' - if both
are present, a @code{ValueError} is raised.

@item

`force'

@tab

If this keyword argument is specified as
true, any existing handlers attached to the
root logger are removed and closed, before
carrying out the configuration as specified
by the other arguments.

@item

`encoding'

@tab

If this keyword argument is specified along
with `filename', its value is used when the
@ref{182c,,FileHandler} is created, and thus
used when opening the output file.

@item

`errors'

@tab

If this keyword argument is specified along
with `filename', its value is used when the
@ref{182c,,FileHandler} is created, and thus
used when opening the output file. If not
specified, the value 'backslashreplace' is
used. Note that if @code{None} is specified,
it will be passed as such to @ref{505,,open()},
which means that it will be treated the
same as passing 'errors'.

@end multitable



Modifié dans la version 3.2: The `style' argument was added.



Modifié dans la version 3.3: The `handlers' argument was added. Additional checks were added to
catch situations where incompatible arguments are specified (e.g.
`handlers' together with `stream' or `filename', or `stream'
together with `filename').



Modifié dans la version 3.8: The `force' argument was added.



Modifié dans la version 3.9: The `encoding' and `errors' arguments were added.

@end deffn

@geindex shutdown() (dans le module logging)
@anchor{library/logging logging shutdown}@anchor{2c03}
@deffn {Fonction} logging.shutdown ()

Informs the logging system to perform an orderly shutdown by flushing and
closing all handlers. This should be called at application exit and no
further use of the logging system should be made after this call.

When the logging module is imported, it registers this function as an exit
handler (see @ref{c,,atexit}), so normally there's no need to do that
manually.
@end deffn

@geindex setLoggerClass() (dans le module logging)
@anchor{library/logging logging setLoggerClass}@anchor{2c2a}
@deffn {Fonction} logging.setLoggerClass (klass)

Tells the logging system to use the class `klass' when instantiating a logger.
The class should define @code{__init__()} such that only a name argument is
required, and the @code{__init__()} should call @code{Logger.__init__()}. This
function is typically called before any loggers are instantiated by applications
which need to use custom logger behavior. After this call, as at any other
time, do not instantiate loggers directly using the subclass: continue to use
the @ref{94d,,logging.getLogger()} API to get your loggers.
@end deffn

@geindex setLogRecordFactory() (dans le module logging)
@anchor{library/logging logging setLogRecordFactory}@anchor{2c1f}
@deffn {Fonction} logging.setLogRecordFactory (factory)

Set a callable which is used to create a @ref{fd1,,LogRecord}.

@*Paramètres: 
@code{factory} -- The factory callable to be used to instantiate a log record.



Ajouté dans la version 3.2: This function has been provided, along with @ref{2c1e,,getLogRecordFactory()}, to
allow developers more control over how the @ref{fd1,,LogRecord} representing
a logging event is constructed.


The factory has the following signature:

@code{factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)}

@quotation

@*nom: 
The logger name.


@*level: 
The logging level (numeric).


@*fn: 
The full pathname of the file where the logging call was made.


@*lno: 
The line number in the file where the logging call was made.


@*msg: 
The logging message.


@*args: 
The arguments for the logging message.


@*exc_info: 
An exception tuple, or @code{None}.


@*func: 
The name of the function or method which invoked the logging
call.


@*sinfo: 
A stack traceback such as is provided by
@ref{e71,,traceback.print_stack()}, showing the call hierarchy.


@*kwargs: 
Additional keyword arguments.

@end quotation
@end deffn

@node Module-Level Attributes,Integration with the warnings module,Fonctions de niveau module,logging --- Logging facility for Python
@anchor{library/logging module-level-attributes}@anchor{2c32}
@subsubsection Module-Level Attributes


@geindex lastResort (dans le module logging)
@anchor{library/logging logging lastResort}@anchor{11d7}
@deffn {Attribut} logging.lastResort

A "handler of last resort" is available through this attribute. This
is a @ref{11d5,,StreamHandler} writing to @code{sys.stderr} with a level of
@code{WARNING}, and is used to handle logging events in the absence of any
logging configuration. The end result is to just print the message to
@code{sys.stderr}. This replaces the earlier error message saying that
"no handlers could be found for logger XYZ". If you need the earlier
behaviour for some reason, @code{lastResort} can be set to @code{None}.


Ajouté dans la version 3.2.

@end deffn

@geindex raiseExceptions (dans le module logging)
@anchor{library/logging logging raiseExceptions}@anchor{11d6}
@deffn {Attribut} logging.raiseExceptions

Used to see if exceptions during handling should be propagated.

Default: @code{True}.

If @ref{11d6,,raiseExceptions} is @code{False},
exceptions get silently ignored. This is what is mostly wanted
for a logging system - most users will not care about errors in
the logging system, they are more interested in application errors.
@end deffn

@node Integration with the warnings module,,Module-Level Attributes,logging --- Logging facility for Python
@anchor{library/logging integration-with-the-warnings-module}@anchor{2c33}
@subsubsection Integration with the warnings module


The @ref{2c34,,captureWarnings()} function can be used to integrate @ref{86,,logging}
with the @ref{111,,warnings} module.

@geindex captureWarnings() (dans le module logging)
@anchor{library/logging logging captureWarnings}@anchor{2c34}
@deffn {Fonction} logging.captureWarnings (capture)

This function is used to turn the capture of warnings by logging on and
off.

If `capture' is @code{True}, warnings issued by the @ref{111,,warnings} module will
be redirected to the logging system. Specifically, a warning will be
formatted using @ref{19a3,,warnings.formatwarning()} and the resulting string
logged to a logger named @code{'py.warnings'} with a severity of @ref{1c81,,WARNING}.

If `capture' is @code{False}, the redirection of warnings to the logging system
will stop, and warnings will be redirected to their original destinations
(i.e. those in effect before @code{captureWarnings(True)} was called).
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{87,,logging.config}

API de configuration pour le module de journalisation.

@item Module @ref{88,,logging.handlers}

Gestionnaires utiles inclus avec le module de journalisation.

@geindex Python Enhancement Proposals; PEP 282

@item PEP 282@footnote{https://peps.python.org/pep-0282/} - A Logging System

The proposal which described this feature for inclusion in the Python standard
library.

@item Original Python logging package@footnote{https://old.red-dove.com/python_logging.html}

This is the original source for the @ref{86,,logging} package.  The version of the
package available from this site is suitable for use with Python 1.5.2, 2.1.x
and 2.2.x, which do not include the @ref{86,,logging} package in the standard
library.
@end table


@node logging config --- Logging configuration,logging handlers --- Logging handlers,logging --- Logging facility for Python,Services génériques du système d'exploitation
@anchor{library/logging config doc}@anchor{2c35}@anchor{library/logging config logging-config-logging-configuration}@anchor{2c36}@anchor{library/logging config module-logging config}@anchor{87}
@subsection @code{logging.config} --- Logging configuration


@geindex module; logging.config

`Source code:' Lib/logging/config.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/logging/config.py}

@subsubheading Important



Cette page contient uniquement des informations de référence. Pour des tutoriels, veuillez consulter


@itemize *

@item 
@ref{11d2,,Tutoriel basique}

@item 
@ref{11d3,,Tutoriel avancé}

@item 
@ref{11d4,,Recettes pour la journalisation}
@end itemize


__________________________________________________________________


This section describes the API for configuring the logging module.

@menu
* Configuration functions:: 
* Security considerations:: 
* Configuration dictionary schema:: 
* Configuration file format:: 

@end menu

@node Configuration functions,Security considerations,,logging config --- Logging configuration
@anchor{library/logging config configuration-functions}@anchor{2c37}@anchor{library/logging config logging-config-api}@anchor{12cf}
@subsubsection Configuration functions


The following functions configure the logging module. They are located in the
@ref{87,,logging.config} module.  Their use is optional --- you can configure the
logging module using these functions or by making calls to the main API (defined
in @ref{86,,logging} itself) and defining handlers which are declared either in
@ref{86,,logging} or @ref{88,,logging.handlers}.

@geindex dictConfig() (dans le module logging.config)
@anchor{library/logging config logging config dictConfig}@anchor{118d}
@deffn {Fonction} logging.config.dictConfig (config)

Takes the logging configuration from a dictionary.  The contents of
this dictionary are described in @ref{2c38,,Configuration dictionary schema}
below.

If an error is encountered during configuration, this function will
raise a @ref{1ff,,ValueError}, @ref{522,,TypeError}, @ref{343,,AttributeError}
or @ref{40f,,ImportError} with a suitably descriptive message.  The
following is a (possibly incomplete) list of conditions which will
raise an error:


@itemize *

@item 
A @code{level} which is not a string or which is a string not
corresponding to an actual logging level.

@item 
A @code{propagate} value which is not a boolean.

@item 
An id which does not have a corresponding destination.

@item 
A non-existent handler id found during an incremental call.

@item 
An invalid logger name.

@item 
Inability to resolve to an internal or external object.
@end itemize

Parsing is performed by the @code{DictConfigurator} class, whose
constructor is passed the dictionary used for configuration, and
has a @code{configure()} method.  The @ref{87,,logging.config} module
has a callable attribute @code{dictConfigClass}
which is initially set to @code{DictConfigurator}.
You can replace the value of @code{dictConfigClass} with a
suitable implementation of your own.

@ref{118d,,dictConfig()} calls @code{dictConfigClass} passing
the specified dictionary, and then calls the @code{configure()} method on
the returned object to put the configuration into effect:

@example
def dictConfig(config):
    dictConfigClass(config).configure()
@end example

For example, a subclass of @code{DictConfigurator} could call
@code{DictConfigurator.__init__()} in its own @code{__init__()}, then
set up custom prefixes which would be usable in the subsequent
@code{configure()} call. @code{dictConfigClass} would be bound to
this new subclass, and then @ref{118d,,dictConfig()} could be called exactly as
in the default, uncustomized state.


Ajouté dans la version 3.2.

@end deffn

@geindex fileConfig() (dans le module logging.config)
@anchor{library/logging config logging config fileConfig}@anchor{b3f}
@deffn {Fonction} logging.config.fileConfig (fname, defaults=None, disable_existing_loggers=True, encoding=None)

Reads the logging configuration from a @ref{22,,configparser}-format file. The
format of the file should be as described in
@ref{2c39,,Configuration file format}.
This function can be called several times from an application, allowing an
end user to select from various pre-canned configurations (if the developer
provides a mechanism to present the choices and load the chosen
configuration).

It will raise @ref{eae,,FileNotFoundError} if the file
doesn't exist and @ref{193,,RuntimeError} if the file is invalid or
empty.

@*Paramètres: 

@itemize *

@item 
@code{fname} -- A filename, or a file-like object, or an instance derived
from @ref{f4f,,RawConfigParser}. If a
@code{RawConfigParser}-derived instance is passed, it is used as
is. Otherwise, a @ref{1c3,,ConfigParser} is
instantiated, and the configuration read by it from the
object passed in @code{fname}. If that has a @ref{b9,,readline()}
method, it is assumed to be a file-like object and read using
@ref{4ef,,read_file()}; otherwise,
it is assumed to be a filename and passed to
@ref{141c,,read()}.

@item 
@code{defaults} -- Defaults to be passed to the @code{ConfigParser} can be specified
in this argument.

@item 
@code{disable_existing_loggers} -- If specified as @code{False}, loggers which
exist when this call is made are left
enabled. The default is @code{True} because this
enables old behaviour in a
backward-compatible way. This behaviour is to
disable any existing non-root loggers unless
they or their ancestors are explicitly named
in the logging configuration.

@item 
@code{encoding} -- The encoding used to open file when `fname' is filename.
@end itemize



Modifié dans la version 3.4: An instance of a subclass of @ref{f4f,,RawConfigParser} is
  now accepted as a value for @code{fname}. This facilitates:

@quotation


@itemize *

@item 
Use of a configuration file where logging configuration is just part
of the overall application configuration.

@item 
Use of a configuration read from a file, and then modified by the using
application (e.g. based on command-line parameters or other aspects
of the runtime environment) before being passed to @code{fileConfig}.
@end itemize
@end quotation


Modifié dans la version 3.10: Added the `encoding' parameter.



Modifié dans la version 3.12: An exception will be thrown if the provided file
doesn't exist or is invalid or empty.


@end deffn

@geindex listen() (dans le module logging.config)
@anchor{library/logging config logging config listen}@anchor{f50}
@deffn {Fonction} logging.config.listen (port=DEFAULT_LOGGING_CONFIG_PORT, verify=None)

Starts up a socket server on the specified port, and listens for new
configurations. If no port is specified, the module's default
@code{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations will be
sent as a file suitable for processing by @ref{118d,,dictConfig()} or
@ref{b3f,,fileConfig()}. Returns a @ref{939,,Thread} instance on which
you can call @ref{2c3a,,start()} to start the server, and which
you can @ref{11c1,,join()} when appropriate. To stop the server,
call @ref{2c3b,,stopListening()}.

The @code{verify} argument, if specified, should be a callable which should
verify whether bytes received across the socket are valid and should be
processed. This could be done by encrypting and/or signing what is sent
across the socket, such that the @code{verify} callable can perform
signature verification and/or decryption. The @code{verify} callable is called
with a single argument - the bytes received across the socket - and should
return the bytes to be processed, or @code{None} to indicate that the bytes should
be discarded. The returned bytes could be the same as the passed in bytes
(e.g. when only verification is done), or they could be completely different
(perhaps if decryption were performed).

To send a configuration to the socket, read in the configuration file and
send it to the socket as a sequence of bytes preceded by a four-byte length
string packed in binary using @code{struct.pack('>L', n)}.
@anchor{library/logging config logging-eval-security}@anchor{2c3c}
@cartouche
@quotation Note 
Because portions of the configuration are passed through
@ref{17e,,eval()}, use of this function may open its users to a security risk.
While the function only binds to a socket on @code{localhost}, and so does
not accept connections from remote machines, there are scenarios where
untrusted code could be run under the account of the process which calls
@ref{f50,,listen()}. Specifically, if the process calling @ref{f50,,listen()} runs
on a multi-user machine where users cannot trust each other, then a
malicious user could arrange to run essentially arbitrary code in a
victim user's process, simply by connecting to the victim's
@ref{f50,,listen()} socket and sending a configuration which runs whatever
code the attacker wants to have executed in the victim's process. This is
especially easy to do if the default port is used, but not hard even if a
different port is used. To avoid the risk of this happening, use the
@code{verify} argument to @ref{f50,,listen()} to prevent unrecognised
configurations from being applied.
@end quotation
@end cartouche


Modifié dans la version 3.4: The @code{verify} argument was added.


@cartouche
@quotation Note 
If you want to send configurations to the listener which don't
disable existing loggers, you will need to use a JSON format for
the configuration, which will use @ref{118d,,dictConfig()} for configuration.
This method allows you to specify @code{disable_existing_loggers} as
@code{False} in the configuration you send.
@end quotation
@end cartouche
@end deffn

@geindex stopListening() (dans le module logging.config)
@anchor{library/logging config logging config stopListening}@anchor{2c3b}
@deffn {Fonction} logging.config.stopListening ()

Stops the listening server which was created with a call to @ref{f50,,listen()}.
This is typically called before calling @code{join()} on the return value from
@ref{f50,,listen()}.
@end deffn

@node Security considerations,Configuration dictionary schema,Configuration functions,logging config --- Logging configuration
@anchor{library/logging config security-considerations}@anchor{2c3d}
@subsubsection Security considerations


The logging configuration functionality tries to offer convenience, and in part this
is done by offering the ability to convert text in configuration files into Python
objects used in logging configuration - for example, as described in
@ref{2c3e,,User-defined objects}. However, these same mechanisms (importing
callables from user-defined modules and calling them with parameters from the
configuration) could be used to invoke any code you like, and for this reason you
should treat configuration files from untrusted sources with `extreme caution' and
satisfy yourself that nothing bad can happen if you load them, before actually loading
them.

@node Configuration dictionary schema,Configuration file format,Security considerations,logging config --- Logging configuration
@anchor{library/logging config configuration-dictionary-schema}@anchor{2c3f}@anchor{library/logging config logging-config-dictschema}@anchor{2c38}
@subsubsection Configuration dictionary schema


Describing a logging configuration requires listing the various
objects to create and the connections between them; for example, you
may create a handler named 'console' and then say that the logger
named 'startup' will send its messages to the 'console' handler.
These objects aren't limited to those provided by the @ref{86,,logging}
module because you might write your own formatter or handler class.
The parameters to these classes may also need to include external
objects such as @code{sys.stderr}.  The syntax for describing these
objects and connections is defined in @ref{2c40,,Object connections}
below.

@menu
* Dictionary Schema Details:: 
* Incremental Configuration:: 
* Object connections:: 
* User-defined objects:: 
* Handler configuration order:: 
* Access to external objects:: 
* Access to internal objects:: 
* Import resolution and custom importers:: 
* Configuring QueueHandler and QueueListener:: 

@end menu

@node Dictionary Schema Details,Incremental Configuration,,Configuration dictionary schema
@anchor{library/logging config dictionary-schema-details}@anchor{2c41}
@subsubsection Dictionary Schema Details


The dictionary passed to @ref{118d,,dictConfig()} must contain the following
keys:


@itemize *

@item 
`version' - to be set to an integer value representing the schema
version.  The only valid value at present is 1, but having this key
allows the schema to evolve while still preserving backwards
compatibility.
@end itemize

All other keys are optional, but if present they will be interpreted
as described below.  In all cases below where a 'configuring dict' is
mentioned, it will be checked for the special @code{'()'} key to see if a
custom instantiation is required.  If so, the mechanism described in
@ref{2c3e,,User-defined objects} below is used to create an instance;
otherwise, the context is used to determine what to instantiate.
@anchor{library/logging config logging-config-dictschema-formatters}@anchor{2c42}

@itemize *

@item 
`formatters' - the corresponding value will be a dict in which each
key is a formatter id and each value is a dict describing how to
configure the corresponding @ref{1449,,Formatter} instance.

The configuring dict is searched for the following optional keys
which correspond to the arguments passed to create a
@ref{1449,,Formatter} object:


@itemize *

@item 
@code{format}

@item 
@code{datefmt}

@item 
@code{style}

@item 
@code{validate} (since version >=3.8)

@item 
@code{defaults} (since version >=3.12)
@end itemize

An optional @code{class} key indicates the name of the formatter's
class (as a dotted module and class name).  The instantiation
arguments are as for @ref{1449,,Formatter}, thus this key is
most useful for instantiating a customised subclass of
@ref{1449,,Formatter}.  For example, the alternative class
might present exception tracebacks in an expanded or condensed
format.  If your formatter requires different or extra configuration
keys, you should use @ref{2c3e,,User-defined objects}.

@item 
`filters' - the corresponding value will be a dict in which each key
is a filter id and each value is a dict describing how to configure
the corresponding Filter instance.

The configuring dict is searched for the key @code{name} (defaulting to the
empty string) and this is used to construct a @ref{11d8,,logging.Filter}
instance.

@item 
`handlers' - the corresponding value will be a dict in which each
key is a handler id and each value is a dict describing how to
configure the corresponding Handler instance.

The configuring dict is searched for the following keys:


@itemize *

@item 
@code{class} (mandatory).  This is the fully qualified name of the
handler class.

@item 
@code{level} (optional).  The level of the handler.

@item 
@code{formatter} (optional).  The id of the formatter for this
handler.

@item 
@code{filters} (optional).  A list of ids of the filters for this
handler.


Modifié dans la version 3.11: @code{filters} can take filter instances in addition to ids.

@end itemize

All `other' keys are passed through as keyword arguments to the
handler's constructor.  For example, given the snippet:

@example
handlers:
  console:
    class : logging.StreamHandler
    formatter: brief
    level   : INFO
    filters: [allow_foo]
    stream  : ext://sys.stdout
  file:
    class : logging.handlers.RotatingFileHandler
    formatter: precise
    filename: logconfig.log
    maxBytes: 1024
    backupCount: 3
@end example

the handler with id @code{console} is instantiated as a
@ref{11d5,,logging.StreamHandler}, using @code{sys.stdout} as the underlying
stream.  The handler with id @code{file} is instantiated as a
@ref{1560,,logging.handlers.RotatingFileHandler} with the keyword arguments
@code{filename='logconfig.log', maxBytes=1024, backupCount=3}.

@item 
`loggers' - the corresponding value will be a dict in which each key
is a logger name and each value is a dict describing how to
configure the corresponding Logger instance.

The configuring dict is searched for the following keys:


@itemize *

@item 
@code{level} (optional).  The level of the logger.

@item 
@code{propagate} (optional).  The propagation setting of the logger.

@item 
@code{filters} (optional).  A list of ids of the filters for this
logger.


Modifié dans la version 3.11: @code{filters} can take filter instances in addition to ids.


@item 
@code{handlers} (optional).  A list of ids of the handlers for this
logger.
@end itemize

The specified loggers will be configured according to the level,
propagation, filters and handlers specified.

@item 
`root' - this will be the configuration for the root logger.
Processing of the configuration will be as for any logger, except
that the @code{propagate} setting will not be applicable.

@item 
`incremental' - whether the configuration is to be interpreted as
incremental to the existing configuration.  This value defaults to
@code{False}, which means that the specified configuration replaces the
existing configuration with the same semantics as used by the
existing @ref{b3f,,fileConfig()} API.

If the specified value is @code{True}, the configuration is processed
as described in the section on @ref{2c43,,Incremental Configuration}.

@item 
`disable_existing_loggers' - whether any existing non-root loggers are
to be disabled. This setting mirrors the parameter of the same name in
@ref{b3f,,fileConfig()}. If absent, this parameter defaults to @code{True}.
This value is ignored if `incremental' is @code{True}.
@end itemize

@node Incremental Configuration,Object connections,Dictionary Schema Details,Configuration dictionary schema
@anchor{library/logging config incremental-configuration}@anchor{2c44}@anchor{library/logging config logging-config-dict-incremental}@anchor{2c43}
@subsubsection Incremental Configuration


It is difficult to provide complete flexibility for incremental
configuration.  For example, because objects such as filters
and formatters are anonymous, once a configuration is set up, it is
not possible to refer to such anonymous objects when augmenting a
configuration.

Furthermore, there is not a compelling case for arbitrarily altering
the object graph of loggers, handlers, filters, formatters at
run-time, once a configuration is set up; the verbosity of loggers and
handlers can be controlled just by setting levels (and, in the case of
loggers, propagation flags).  Changing the object graph arbitrarily in
a safe way is problematic in a multi-threaded environment; while not
impossible, the benefits are not worth the complexity it adds to the
implementation.

Thus, when the @code{incremental} key of a configuration dict is present
and is @code{True}, the system will completely ignore any @code{formatters} and
@code{filters} entries, and process only the @code{level}
settings in the @code{handlers} entries, and the @code{level} and
@code{propagate} settings in the @code{loggers} and @code{root} entries.

Using a value in the configuration dict lets configurations to be sent
over the wire as pickled dicts to a socket listener. Thus, the logging
verbosity of a long-running application can be altered over time with
no need to stop and restart the application.

@node Object connections,User-defined objects,Incremental Configuration,Configuration dictionary schema
@anchor{library/logging config logging-config-dict-connections}@anchor{2c40}@anchor{library/logging config object-connections}@anchor{2c45}
@subsubsection Object connections


The schema describes a set of logging objects - loggers,
handlers, formatters, filters - which are connected to each other in
an object graph.  Thus, the schema needs to represent connections
between the objects.  For example, say that, once configured, a
particular logger has attached to it a particular handler.  For the
purposes of this discussion, we can say that the logger represents the
source, and the handler the destination, of a connection between the
two.  Of course in the configured objects this is represented by the
logger holding a reference to the handler.  In the configuration dict,
this is done by giving each destination object an id which identifies
it unambiguously, and then using the id in the source object's
configuration to indicate that a connection exists between the source
and the destination object with that id.

So, for example, consider the following YAML snippet:

@example
formatters:
  brief:
    # configuration for formatter with id 'brief' goes here
  precise:
    # configuration for formatter with id 'precise' goes here
handlers:
  h1: #This is an id
   # configuration of handler with id 'h1' goes here
   formatter: brief
  h2: #This is another id
   # configuration of handler with id 'h2' goes here
   formatter: precise
loggers:
  foo.bar.baz:
    # other configuration for logger 'foo.bar.baz'
    handlers: [h1, h2]
@end example

(Note: YAML used here because it's a little more readable than the
equivalent Python source form for the dictionary.)

The ids for loggers are the logger names which would be used
programmatically to obtain a reference to those loggers, e.g.
@code{foo.bar.baz}.  The ids for Formatters and Filters can be any string
value (such as @code{brief}, @code{precise} above) and they are transient,
in that they are only meaningful for processing the configuration
dictionary and used to determine connections between objects, and are
not persisted anywhere when the configuration call is complete.

The above snippet indicates that logger named @code{foo.bar.baz} should
have two handlers attached to it, which are described by the handler
ids @code{h1} and @code{h2}. The formatter for @code{h1} is that described by id
@code{brief}, and the formatter for @code{h2} is that described by id
@code{precise}.

@node User-defined objects,Handler configuration order,Object connections,Configuration dictionary schema
@anchor{library/logging config logging-config-dict-userdef}@anchor{2c3e}@anchor{library/logging config user-defined-objects}@anchor{2c46}
@subsubsection User-defined objects


The schema supports user-defined objects for handlers, filters and
formatters.  (Loggers do not need to have different types for
different instances, so there is no support in this configuration
schema for user-defined logger classes.)

Objects to be configured are described by dictionaries
which detail their configuration.  In some places, the logging system
will be able to infer from the context how an object is to be
instantiated, but when a user-defined object is to be instantiated,
the system will not know how to do this.  In order to provide complete
flexibility for user-defined object instantiation, the user needs
to provide a 'factory' - a callable which is called with a
configuration dictionary and which returns the instantiated object.
This is signalled by an absolute import path to the factory being
made available under the special key @code{'()'}.  Here's a concrete
example:

@example
formatters:
  brief:
    format: '%(message)s'
  default:
    format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
    datefmt: '%Y-%m-%d %H:%M:%S'
  custom:
      (): my.package.customFormatterFactory
      bar: baz
      spam: 99.9
      answer: 42
@end example

The above YAML snippet defines three formatters.  The first, with id
@code{brief}, is a standard @ref{1449,,logging.Formatter} instance with the
specified format string.  The second, with id @code{default}, has a
longer format and also defines the time format explicitly, and will
result in a @ref{1449,,logging.Formatter} initialized with those two format
strings.  Shown in Python source form, the @code{brief} and @code{default}
formatters have configuration sub-dictionaries:

@example
@{
  'format' : '%(message)s'
@}
@end example

et :

@example
@{
  'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
  'datefmt' : '%Y-%m-%d %H:%M:%S'
@}
@end example

respectively, and as these dictionaries do not contain the special key
@code{'()'}, the instantiation is inferred from the context: as a result,
standard @ref{1449,,logging.Formatter} instances are created.  The
configuration sub-dictionary for the third formatter, with id
@code{custom}, is:

@example
@{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42
@}
@end example

and this contains the special key @code{'()'}, which means that
user-defined instantiation is wanted.  In this case, the specified
factory callable will be used. If it is an actual callable it will be
used directly - otherwise, if you specify a string (as in the example)
the actual callable will be located using normal import mechanisms.
The callable will be called with the `remaining' items in the
configuration sub-dictionary as keyword arguments.  In the above
example, the formatter with id @code{custom} will be assumed to be
returned by the call:

@example
my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)
@end example

@cartouche
@quotation Avertissement 
The values for keys such as @code{bar}, @code{spam} and @code{answer} in
the above example should not be configuration dictionaries or references such
as @code{cfg://foo} or @code{ext://bar}, because they will not be processed by the
configuration machinery, but passed to the callable as-is.
@end quotation
@end cartouche

The key @code{'()'} has been used as the special key because it is not a
valid keyword parameter name, and so will not clash with the names of
the keyword arguments used in the call.  The @code{'()'} also serves as a
mnemonic that the corresponding value is a callable.


Modifié dans la version 3.11: The @code{filters} member of @code{handlers} and @code{loggers} can take
filter instances in addition to ids.


You can also specify a special key @code{'.'} whose value is a dictionary 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:

@example
@{
  '()' : 'my.package.customFormatterFactory',
  'bar' : 'baz',
  'spam' : 99.9,
  'answer' : 42,
  '.' @{
    'foo': 'bar',
    'baz': 'bozz'
  @}
@}
@end example

the returned formatter will have attribute @code{foo} set to @code{'bar'} and
attribute @code{baz} set to @code{'bozz'}.

@cartouche
@quotation Avertissement 
The values for attributes such as @code{foo} and @code{baz} in
the above example should not be configuration dictionaries or references such
as @code{cfg://foo} or @code{ext://bar}, because they will not be processed by the
configuration machinery, but set as attribute values as-is.
@end quotation
@end cartouche

@node Handler configuration order,Access to external objects,User-defined objects,Configuration dictionary schema
@anchor{library/logging config handler-config-dict-order}@anchor{2c47}@anchor{library/logging config handler-configuration-order}@anchor{2c48}
@subsubsection Handler configuration order


Handlers are configured in alphabetical order of their keys, and a configured
handler replaces the configuration dictionary in (a working copy of) the
@code{handlers} dictionary in the schema. If you use a construct such as
@code{cfg://handlers.foo}, then initially @code{handlers['foo']} points to the
configuration dictionary for the handler named @code{foo}, and later (once that
handler has been configured) it points to the configured handler instance.
Thus, @code{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
something like @code{cfg://handlers.foo} to be used in configuring a handler that
depends on handler @code{foo}. If that dependent handler were named @code{bar},
problems would result, because the configuration of @code{bar} would be attempted
before that of @code{foo}, and @code{foo} would not yet have been configured.
However, if the dependent handler were named @code{foobar}, it would be configured
after @code{foo}, with the result that @code{cfg://handlers.foo} would resolve to
configured handler @code{foo}, and not its configuration dictionary.

@node Access to external objects,Access to internal objects,Handler configuration order,Configuration dictionary schema
@anchor{library/logging config access-to-external-objects}@anchor{2c49}@anchor{library/logging config logging-config-dict-externalobj}@anchor{2c4a}
@subsubsection Access to external objects


There are times where a configuration needs to refer to objects
external to the configuration, for example @code{sys.stderr}.  If the
configuration dict is constructed using Python code, this is
straightforward, but a problem arises when the configuration is
provided via a text file (e.g. JSON, YAML).  In a text file, there is
no standard way to distinguish @code{sys.stderr} from the literal string
@code{'sys.stderr'}.  To facilitate this distinction, the configuration
system looks for certain special prefixes in string values and
treat them specially.  For example, if the literal string
@code{'ext://sys.stderr'} is provided as a value in the configuration,
then the @code{ext://} will be stripped off and the remainder of the
value processed using normal import mechanisms.

The handling of such prefixes is done in a way analogous to protocol
handling: there is a generic mechanism to look for prefixes which
match the regular expression @code{^(?P<prefix>[a-z]+)://(?P<suffix>.*)$}
whereby, if the @code{prefix} is recognised, the @code{suffix} is processed
in a prefix-dependent manner and the result of the processing replaces
the string value.  If the prefix is not recognised, then the string
value will be left as-is.

@node Access to internal objects,Import resolution and custom importers,Access to external objects,Configuration dictionary schema
@anchor{library/logging config access-to-internal-objects}@anchor{2c4b}@anchor{library/logging config logging-config-dict-internalobj}@anchor{2c4c}
@subsubsection Access to internal objects


As well as external objects, there is sometimes also a need to refer
to objects in the configuration.  This will be done implicitly by the
configuration system for things that it knows about.  For example, the
string value @code{'DEBUG'} for a @code{level} in a logger or handler will
automatically be converted to the value @code{logging.DEBUG}, and the
@code{handlers}, @code{filters} and @code{formatter} entries will take an
object id and resolve to the appropriate destination object.

However, a more generic mechanism is needed for user-defined
objects which are not known to the @ref{86,,logging} module.  For
example, consider @ref{2c4d,,logging.handlers.MemoryHandler}, which takes
a @code{target} argument which is another handler to delegate to. Since
the system already knows about this class, then in the configuration,
the given @code{target} just needs to be the object id of the relevant
target handler, and the system will resolve to the handler from the
id.  If, however, a user defines a @code{my.package.MyHandler} which has
an @code{alternate} handler, the configuration system would not know that
the @code{alternate} referred to a handler.  To cater for this, a generic
resolution system allows the user to specify:

@example
handlers:
  file:
    # configuration of file handler goes here

  custom:
    (): my.package.MyHandler
    alternate: cfg://handlers.file
@end example

The literal string @code{'cfg://handlers.file'} will be resolved in an
analogous way to strings with the @code{ext://} prefix, but looking
in the configuration itself rather than the import namespace.  The
mechanism allows access by dot or by index, in a similar way to
that provided by @code{str.format}.  Thus, given the following snippet:

@example
handlers:
  email:
    class: logging.handlers.SMTPHandler
    mailhost: localhost
    fromaddr: my_app@@domain.tld
    toaddrs:
      - support_team@@domain.tld
      - dev_team@@domain.tld
    subject: Houston, we have a problem.
@end example

in the configuration, the string @code{'cfg://handlers'} would resolve to
the dict with key @code{handlers}, the string @code{'cfg://handlers.email}
would resolve to the dict with key @code{email} in the @code{handlers} dict,
and so on.  The string @code{'cfg://handlers.email.toaddrs[1]} would
resolve to @code{'dev_team@@domain.tld'} and the string
@code{'cfg://handlers.email.toaddrs[0]'} would resolve to the value
@code{'support_team@@domain.tld'}. The @code{subject} value could be accessed
using either @code{'cfg://handlers.email.subject'} or, equivalently,
@code{'cfg://handlers.email[subject]'}.  The latter form only needs to be
used if the key contains spaces or non-alphanumeric characters. Please note
that the characters @code{[} and @code{]} are not allowed in the keys. If an
index value consists only of decimal digits, access will be attempted
using the corresponding integer value, falling back to the string
value if needed.

Given a string @code{cfg://handlers.myhandler.mykey.123}, this will
resolve to @code{config_dict['handlers']['myhandler']['mykey']['123']}.
If the string is specified as @code{cfg://handlers.myhandler.mykey[123]},
the system will attempt to retrieve the value from
@code{config_dict['handlers']['myhandler']['mykey'][123]}, and fall back
to @code{config_dict['handlers']['myhandler']['mykey']['123']} if that
fails.

@node Import resolution and custom importers,Configuring QueueHandler and QueueListener,Access to internal objects,Configuration dictionary schema
@anchor{library/logging config import-resolution-and-custom-importers}@anchor{2c4e}@anchor{library/logging config logging-import-resolution}@anchor{2c4f}
@subsubsection Import resolution and custom importers


Import resolution, by default, uses the builtin @ref{8c1,,__import__()} function
to do its importing. You may want to replace this with your own importing
mechanism: if so, you can replace the @code{importer} attribute of the
@code{DictConfigurator} or its superclass, the
@code{BaseConfigurator} class. However, you need to be
careful because of the way functions are accessed from classes via
descriptors. If you are using a Python callable to do your imports, and you
want to define it at class level rather than instance level, you need to wrap
it with @ref{40c,,staticmethod()}. For example:

@example
from importlib import import_module
from logging.config import BaseConfigurator

BaseConfigurator.importer = staticmethod(import_module)
@end example

You don't need to wrap with @ref{40c,,staticmethod()} if you're setting the import
callable on a configurator `instance'.

@node Configuring QueueHandler and QueueListener,,Import resolution and custom importers,Configuration dictionary schema
@anchor{library/logging config configure-queue}@anchor{1563}@anchor{library/logging config configuring-queuehandler-and-queuelistener}@anchor{2c50}
@subsubsection Configuring QueueHandler and QueueListener


If you want to configure a @ref{1765,,QueueHandler}, noting that this
is normally used in conjunction with a @ref{e19,,QueueListener}, you
can configure both together. After the configuration, the @code{QueueListener} instance
will be available as the @ref{2c51,,listener} attribute of
the created handler, and that in turn will be available to you using
@ref{1766,,getHandlerByName()} and passing the name you have used for the
@code{QueueHandler} in your configuration. The dictionary schema for configuring the pair
is shown in the example YAML snippet below.

@example
handlers:
  qhand:
    class: logging.handlers.QueueHandler
    queue: my.module.queue_factory
    listener: my.package.CustomListener
    handlers:
      - hand_name_1
      - hand_name_2
      ...
@end example

The @code{queue} and @code{listener} keys are optional.

If the @code{queue} key is present, the corresponding value can be one of the following:


@itemize *

@item 
An object implementing the @ref{2c52,,Queue.put_nowait}
and @ref{2c53,,Queue.get} public API. For instance, this may be
an actual instance of @ref{1365,,queue.Queue} or a subclass thereof, or a proxy
obtained by @ref{2c54,,multiprocessing.managers.SyncManager.Queue()}.

This is of course only possible if you are constructing or modifying
the configuration dictionary in code.

@item 
A string that resolves to a callable which, when called with no arguments, returns
the queue instance to use. That callable could be a @ref{1365,,queue.Queue} subclass
or a function which returns a suitable queue instance,
such as @code{my.module.queue_factory()}.

@item 
A dict with a @code{'()'} key which is constructed in the usual way as discussed in
@ref{2c3e,,User-defined objects}. The result of this construction should be a
@ref{1365,,queue.Queue} instance.
@end itemize

If the  @code{queue} key is absent, a standard unbounded @ref{1365,,queue.Queue} instance is
created and used.

If the @code{listener} key is present, the corresponding value can be one of the following:


@itemize *

@item 
A subclass of @ref{e19,,logging.handlers.QueueListener}. This is of course only
possible if you are constructing or modifying the configuration dictionary in
code.

@item 
A string which resolves to a class which is a subclass of @code{QueueListener}, such as
@code{'my.package.CustomListener'}.

@item 
A dict with a @code{'()'} key which is constructed in the usual way as discussed in
@ref{2c3e,,User-defined objects}. The result of this construction should be a
callable with the same signature as the @code{QueueListener} initializer.
@end itemize

If the @code{listener} key is absent, @ref{e19,,logging.handlers.QueueListener} is used.

The values under the @code{handlers} key are the names of other handlers in the
configuration (not shown in the above snippet) which will be passed to the queue
listener.

Any custom queue handler and listener classes will need to be defined with the same
initialization signatures as @ref{1765,,QueueHandler} and
@ref{e19,,QueueListener}.


Ajouté dans la version 3.12.


@node Configuration file format,,Configuration dictionary schema,logging config --- Logging configuration
@anchor{library/logging config configuration-file-format}@anchor{2c55}@anchor{library/logging config logging-config-fileformat}@anchor{2c39}
@subsubsection Configuration file format


The configuration file format understood by @ref{b3f,,fileConfig()} is based on
@ref{22,,configparser} functionality. The file must contain sections called
@code{[loggers]}, @code{[handlers]} and @code{[formatters]} which identify by name the
entities of each type which are defined in the file. For each such entity, there
is a separate section which identifies how that entity is configured.  Thus, for
a logger named @code{log01} in the @code{[loggers]} section, the relevant
configuration details are held in a section @code{[logger_log01]}. Similarly, a
handler called @code{hand01} in the @code{[handlers]} section will have its
configuration held in a section called @code{[handler_hand01]}, while a formatter
called @code{form01} in the @code{[formatters]} section will have its configuration
specified in a section called @code{[formatter_form01]}. The root logger
configuration must be specified in a section called @code{[logger_root]}.

@cartouche
@quotation Note 
The @ref{b3f,,fileConfig()} API is older than the @ref{118d,,dictConfig()} API and does
not provide functionality to cover certain aspects of logging. For example,
you cannot configure @ref{11d8,,Filter} objects, which provide for
filtering of messages beyond simple integer levels, using @ref{b3f,,fileConfig()}.
If you need to have instances of @ref{11d8,,Filter} in your logging
configuration, you will need to use @ref{118d,,dictConfig()}. Note that future
enhancements to configuration functionality will be added to
@ref{118d,,dictConfig()}, so it's worth considering transitioning to this newer
API when it's convenient to do so.
@end quotation
@end cartouche

Examples of these sections in the file are given below.

@example
[loggers]
keys=root,log02,log03,log04,log05,log06,log07

[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09

[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
@end example

The root logger must specify a level and a list of handlers. An example of a
root logger section is given below.

@example
[logger_root]
level=NOTSET
handlers=hand01
@end example

The @code{level} entry can be one of @code{DEBUG, INFO, WARNING, ERROR, CRITICAL} or
@code{NOTSET}. For the root logger only, @code{NOTSET} means that all messages will be
logged. Level values are @ref{20ee,,evaluated} in the context of the @code{logging}
package's namespace.

The @code{handlers} entry is a comma-separated list of handler names, which must
appear in the @code{[handlers]} section. These names must appear in the
@code{[handlers]} section and have corresponding sections in the configuration
file.

For loggers other than the root logger, some additional information is required.
This is illustrated by the following example.

@example
[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser
@end example

The @code{level} and @code{handlers} entries are interpreted as for the root logger,
except that if a non-root logger's level is specified as @code{NOTSET}, the system
consults loggers higher up the hierarchy to determine the effective level of the
logger. The @code{propagate} entry is set to 1 to indicate that messages must
propagate to handlers higher up the logger hierarchy from this logger, or 0 to
indicate that messages are `not' propagated to handlers up the hierarchy. The
@code{qualname} entry is the hierarchical channel name of the logger, that is to
say the name used by the application to get the logger.

Sections which specify handler configuration are exemplified by the following.

@example
[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)
@end example

The @code{class} entry indicates the handler's class (as determined by @ref{17e,,eval()}
in the @code{logging} package's namespace). The @code{level} is interpreted as for
loggers, and @code{NOTSET} is taken to mean 'log everything'.

The @code{formatter} entry indicates the key name of the formatter for this
handler. If blank, a default formatter (@code{logging._defaultFormatter}) is used.
If a name is specified, it must appear in the @code{[formatters]} section and have
a corresponding section in the configuration file.

The @code{args} entry, when @ref{20ee,,evaluated} in the context of the @code{logging}
package's namespace, is the list of arguments to the constructor for the handler
class. Refer to the constructors for the relevant handlers, or to the examples
below, to see how typical entries are constructed. If not provided, it defaults
to @code{()}.

The optional @code{kwargs} entry, when @ref{20ee,,evaluated} in the context of the
@code{logging} package's namespace, is the keyword argument dict to the constructor
for the handler class. If not provided, it defaults to @code{@{@}}.

@example
[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')

[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)

[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)

[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)

[handler_hand06]
class=handlers.NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '@w{'}, 'Application')

[handler_hand07]
class=handlers.SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@@abc', ['user1@@abc', 'user2@@xyz'], 'Logger Subject')
kwargs=@{'timeout': 10.0@}

[handler_hand08]
class=handlers.MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)

[handler_hand09]
class=handlers.HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')
kwargs=@{'secure': True@}
@end example

Sections which specify formatter configuration are typified by the following.

@example
[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s %(customfield)s
datefmt=
style=%
validate=True
defaults=@{'customfield': 'defaultvalue'@}
class=logging.Formatter
@end example

The arguments for the formatter configuration are the same as the keys
in the dictionary schema @ref{2c42,,formatters section}.

The @code{defaults} entry, when @ref{20ee,,evaluated} in the context of
the @code{logging} package's namespace, is a dictionary of default values for
custom formatting fields. If not provided, it defaults to @code{None}.

@cartouche
@quotation Note 
Due to the use of @ref{17e,,eval()} as described above, there are
potential security risks which result from using the @ref{f50,,listen()} to send
and receive configurations via sockets. The risks are limited to where
multiple users with no mutual trust run code on the same machine; see the
@ref{f50,,listen()} documentation for more information.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item Module @ref{86,,logging}

Référence d'API pour le module de journalisation.

@item Module @ref{88,,logging.handlers}

Gestionnaires utiles inclus avec le module de journalisation.
@end table


@node logging handlers --- Logging handlers,platform --- Access to underlying platform's identifying data,logging config --- Logging configuration,Services génériques du système d'exploitation
@anchor{library/logging handlers doc}@anchor{2c56}@anchor{library/logging handlers logging-handlers-logging-handlers}@anchor{2c57}@anchor{library/logging handlers module-logging handlers}@anchor{88}
@subsection @code{logging.handlers} --- Logging handlers


@geindex module; logging.handlers

`Code source :' Lib/logging/handlers.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/logging/handlers.py}

@subsubheading Important



Cette page contient uniquement des informations de référence. Pour des tutoriels, veuillez consulter


@itemize *

@item 
@ref{11d2,,Tutoriel basique}

@item 
@ref{11d3,,Tutoriel avancé}

@item 
@ref{11d4,,livre de recettes sur la journalisation}
@end itemize


__________________________________________________________________


Les gestionnaires suivants, très utiles, sont fournis dans le paquet. Notez que trois des gestionnaires (@ref{11d5,,StreamHandler}, @ref{182c,,FileHandler} et @ref{1262,,NullHandler}) sont en réalité définis dans le module @ref{86,,logging} lui-même, mais qu’ils sont documentés ici avec les autres gestionnaires.

@menu
* Gestionnaire à flux — StreamHandler:: 
* Gestionnaire à fichier — FileHandler:: 
* Gestionnaire à puits sans fond — NullHandler:: 
* Gestionnaire à fichier avec surveillance — WatchedFileHandler:: 
* Base des gestionnaires à roulement — BaseRotatingHandler:: 
* Gestionnaire à roulement de fichiers — RotatingFileHandler:: 
* Gestionnaire à roulement de fichiers périodique — TimedRotatingFileHandler:: 
* Gestionnaire à connecteur — SocketHandler:: 
* DatagramHandler:: 
* SysLogHandler:: 
* NTEventLogHandler:: 
* SMTPHandler:: 
* MemoryHandler:: 
* HTTPHandler:: 
* QueueHandler:: 
* QueueListener:: 

@end menu

@node Gestionnaire à flux — StreamHandler,Gestionnaire à fichier — FileHandler,,logging handlers --- Logging handlers
@anchor{library/logging handlers stream-handler}@anchor{2c58}@anchor{library/logging handlers streamhandler}@anchor{2c59}
@subsubsection Gestionnaire à flux — `StreamHandler'


La classe @ref{11d5,,StreamHandler}, du paquet @ref{86,,logging}, envoie les sorties de journalisation dans des flux tels que `sys.stdout', `sys.stderr' ou n’importe quel objet fichier-compatible (ou, plus précisément, tout objet qui gère les méthodes @code{write()} et @code{flush()}).

@geindex StreamHandler (classe dans logging)
@anchor{library/logging handlers logging StreamHandler}@anchor{11d5}
@deffn {Classe} logging.StreamHandler (stream=None)

Renvoie une nouvelle instance de la classe @ref{11d5,,StreamHandler}. Si `stream' est spécifié, l’instance l’utilise pour les sorties de journalisation ; autrement elle utilise `sys.stderr'.

@geindex emit() (méthode logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler emit}@anchor{2c5a}
@deffn {Méthode} emit (record)

Si un formateur est spécifié, il est utilisé pour formater l’enregistrement. L’enregistrement est ensuite écrit dans le flux, suivi par @ref{2c5b,,terminator}. Si une information d’exception est présente, elle est formatée en utilisant @ref{839,,traceback.print_exception()} puis ajoutée aux flux.
@end deffn

@geindex flush() (méthode logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler flush}@anchor{2c5c}
@deffn {Méthode} flush ()

Purge le flux en appelant sa méthode @ref{2c5c,,flush()}. Notez que la méthode @code{close()} est héritée de @ref{1448,,Handler} donc elle n'écrit rien. Par conséquent, un appel explicite à @ref{2c5c,,flush()} peut parfois s'avérer nécessaire.
@end deffn

@geindex setStream() (méthode logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler setStream}@anchor{b3e}
@deffn {Méthode} setStream (stream)

Définit le flux de l’instance à la valeur spécifiée, si elle est différente. L’ancien flux est purgé avant que le nouveau flux ne soit établi.

@*Paramètres: 
@code{stream} -- le flux que le gestionnaire doit utiliser.


@*Renvoie: 
the old stream, if the stream was changed, or @code{None} if it wasn't.



Ajouté dans la version 3.7.

@end deffn

@geindex terminator (attribut logging.StreamHandler)
@anchor{library/logging handlers logging StreamHandler terminator}@anchor{2c5b}
@deffn {Attribut} terminator

Chaine de caractères utilisée comme marqueur de fin lors de l’écriture formatée d'un enregistrement dans un flux. La valeur par défaut est @code{'\n'}.

Si vous ne voulez pas marquer de fin de ligne, il faut définir l’attribut @code{terminator} à la chaîne de caractères vide.

Dans des versions antérieures, le marqueur de fin était codé en dur sous la forme @code{'\n'}.


Ajouté dans la version 3.2.

@end deffn
@end deffn

@node Gestionnaire à fichier — FileHandler,Gestionnaire à puits sans fond — NullHandler,Gestionnaire à flux — StreamHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers file-handler}@anchor{2c5d}@anchor{library/logging handlers filehandler}@anchor{2c5e}
@subsubsection Gestionnaire à fichier — `FileHandler'


La classe @ref{182c,,FileHandler}, du paquet @ref{86,,logging}, envoie les sorties de journalisation dans un fichier. Elle hérite des fonctionnalités de sortie de @ref{11d5,,StreamHandler}.

@geindex FileHandler (classe dans logging)
@anchor{library/logging handlers logging FileHandler}@anchor{182c}
@deffn {Classe} logging.FileHandler (filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the @ref{182c,,FileHandler} class. The specified file is
opened and used as the stream for logging. If `mode' is not specified,
@code{'a'} is used.  If `encoding' is not @code{None}, it is used to open the file
with that encoding.  If `delay' is true, then file opening is deferred until the
first call to @ref{2c5f,,emit()}. By default, the file grows indefinitely. If
`errors' is specified, it's used to determine how encoding errors are handled.


Modifié dans la version 3.6: L'argument `filename' accepte les objets @ref{226,,Path} aussi bien que les chaînes de caractères.



Modifié dans la version 3.9: ajout du paramètre `errors'.


@geindex close() (méthode logging.FileHandler)
@anchor{library/logging handlers logging FileHandler close}@anchor{2c60}
@deffn {Méthode} close ()

Ferme le fichier.
@end deffn

@geindex emit() (méthode logging.FileHandler)
@anchor{library/logging handlers logging FileHandler emit}@anchor{2c5f}
@deffn {Méthode} emit (record)

Écrit l’enregistrement dans le fichier.

Note that if the file was closed due to logging shutdown at exit and the file
mode is 'w', the record will not be emitted (see bpo-42378@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=42378}).
@end deffn
@end deffn

@node Gestionnaire à puits sans fond — NullHandler,Gestionnaire à fichier avec surveillance — WatchedFileHandler,Gestionnaire à fichier — FileHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers null-handler}@anchor{2c61}@anchor{library/logging handlers nullhandler}@anchor{2c62}
@subsubsection Gestionnaire à puits sans fond — `NullHandler'



Ajouté dans la version 3.1.


La classe @ref{1262,,NullHandler}, située dans le paquet principal @ref{86,,logging}, ne produit aucun formatage ni sortie. C’est essentiellement un gestionnaire « fantôme » destiné aux développeurs de bibliothèques.

@geindex NullHandler (classe dans logging)
@anchor{library/logging handlers logging NullHandler}@anchor{1262}
@deffn {Classe} logging.NullHandler

Renvoie une nouvelle instance de la classe @ref{1262,,NullHandler}.

@geindex emit() (méthode logging.NullHandler)
@anchor{library/logging handlers logging NullHandler emit}@anchor{2c63}
@deffn {Méthode} emit (record)

Cette méthode ne fait rien.
@end deffn

@geindex handle() (méthode logging.NullHandler)
@anchor{library/logging handlers logging NullHandler handle}@anchor{2c64}
@deffn {Méthode} handle (record)

Cette méthode ne fait rien.
@end deffn

@geindex createLock() (méthode logging.NullHandler)
@anchor{library/logging handlers logging NullHandler createLock}@anchor{2c65}
@deffn {Méthode} createLock ()

Cette méthode renvoie @code{None} pour le verrou, étant donné qu’il n’y a aucun flux d'entrée-sortie sous-jacent dont l’accès doit être sérialisé.
@end deffn
@end deffn

Voir @ref{2c66,,Configuration de la journalisation pour une bibliothèque} pour plus d’information sur l'utilisation de @ref{1262,,NullHandler}.

@node Gestionnaire à fichier avec surveillance — WatchedFileHandler,Base des gestionnaires à roulement — BaseRotatingHandler,Gestionnaire à puits sans fond — NullHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers watched-file-handler}@anchor{2c67}@anchor{library/logging handlers watchedfilehandler}@anchor{2c68}
@subsubsection Gestionnaire à fichier avec surveillance — `WatchedFileHandler'


La classe @ref{2c69,,WatchedFileHandler}, du module @ref{88,,logging.handlers}, est une classe @code{FileHandler} qui surveille le fichier dans lequel elle écrit. Si le fichier est modifié, il est fermé et rouvert en utilisant le nom du fichier.

Le fichier peut être modifié par des programmes tels que `newsyslog' ou `logrotate' qui assurent le roulement des fichiers de journalisation. Ce gestionnaire, destiné à une utilisation sous Unix-Linux, surveille le fichier pour voir s’il a changé depuis la dernière écriture (un fichier est considéré comme modifié si son nœud d’index ou le périphérique auquel il est rattaché a changé). Si le fichier a changé, l’ancien flux vers ce fichier est fermé, et le fichier est ouvert pour établir un nouveau flux.

Ce gestionnaire n’est pas approprié pour une utilisation sous `Windows', car sous `Windows' les fichiers de journalisation ouverts ne peuvent être ni déplacés, ni renommés — la journalisation ouvre les fichiers avec des verrous exclusifs — de telle sorte qu’il n’y a pas besoin d’un tel gestionnaire. En outre, `ST_INO' n’est pas géré par `Windows' ; @ref{48a,,stat()} renvoie toujours zéro pour cette valeur.

@geindex WatchedFileHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers WatchedFileHandler}@anchor{2c69}
@deffn {Classe} logging.handlers.WatchedFileHandler (filename, mode='a', encoding=None, delay=False, errors=None)

Returns a new instance of the @ref{2c69,,WatchedFileHandler} class. The specified
file is opened and used as the stream for logging. If `mode' is not specified,
@code{'a'} is used.  If `encoding' is not @code{None}, it is used to open the file
with that encoding.  If `delay' is true, then file opening is deferred until the
first call to @ref{2c6a,,emit()}.  By default, the file grows indefinitely. If
`errors' is provided, it determines how encoding errors are handled.


Modifié dans la version 3.6: L'argument `filename' accepte les objets @ref{226,,Path} aussi bien que les chaînes de caractères.



Modifié dans la version 3.9: ajout du paramètre `errors'.


@geindex reopenIfNeeded() (méthode logging.handlers.WatchedFileHandler)
@anchor{library/logging handlers logging handlers WatchedFileHandler reopenIfNeeded}@anchor{ca4}
@deffn {Méthode} reopenIfNeeded ()

Vérifie si le fichier a changé. Si c’est le cas, le flux existant est purgé et fermé et le fichier est rouvert, généralement avant d'effectuer l’écriture de l'enregistrement dans le fichier.


Ajouté dans la version 3.6.

@end deffn

@geindex emit() (méthode logging.handlers.WatchedFileHandler)
@anchor{library/logging handlers logging handlers WatchedFileHandler emit}@anchor{2c6a}
@deffn {Méthode} emit (record)

Écrit l’enregistrement dans le fichier, mais appelle d’abord @ref{ca4,,reopenIfNeeded()} pour rouvrir le fichier s’il a changé.
@end deffn
@end deffn

@node Base des gestionnaires à roulement — BaseRotatingHandler,Gestionnaire à roulement de fichiers — RotatingFileHandler,Gestionnaire à fichier avec surveillance — WatchedFileHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers base-rotating-handler}@anchor{2c6b}@anchor{library/logging handlers baserotatinghandler}@anchor{2c6c}
@subsubsection Base des gestionnaires à roulement — `BaseRotatingHandler'


La classe @ref{2c6d,,BaseRotatingHandler}, du module @ref{88,,logging.handlers}, est la classe de base pour les gestionnaires à roulement, @ref{1560,,RotatingFileHandler} et @ref{f4c,,TimedRotatingFileHandler}. Il ne faut pas créer des instances de cette classe, mais surcharger ses attributs et méthodes.

@geindex BaseRotatingHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers BaseRotatingHandler}@anchor{2c6d}
@deffn {Classe} logging.handlers.BaseRotatingHandler (filename, mode, encoding=None, delay=False, errors=None)

Les paramètres sont les mêmes que pour @code{FileHandler}. Les attributs sont :

@geindex namer (attribut logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler namer}@anchor{2c6e}
@deffn {Attribut} namer

Si cet attribut est un qu’appelable, la méthode @ref{2c6f,,rotation_filename()} délègue sa logique à cet appelable. Les paramètres passés à l’appelable sont ceux passés à @ref{2c6f,,rotation_filename()}.

@cartouche
@quotation Note 
la fonction `namer' est appelée de nombreuses fois durant le roulement ; elle doit donc être aussi simple et rapide que possible. Elle doit aussi renvoyer toujours la même sortie pour une entrée donnée, autrement le comportement du roulement pourrait être différent de celui attendu.

It's also worth noting that care should be taken when using a namer to
preserve certain attributes in the filename which are used during rotation.
For example, @ref{1560,,RotatingFileHandler} expects to have a set of log files
whose names contain successive integers, so that rotation works as expected,
and @ref{f4c,,TimedRotatingFileHandler} deletes old log files (based on the
@code{backupCount} parameter passed to the handler's initializer) by determining
the oldest files to delete. For this to happen, the filenames should be
sortable using the date/time portion of the filename, and a namer needs to
respect this. (If a namer is wanted that doesn't respect this scheme, it will
need to be used in a subclass of @ref{f4c,,TimedRotatingFileHandler} which
overrides the @ref{2c70,,getFilesToDelete()} method to
fit in with the custom naming scheme.)
@end quotation
@end cartouche


Ajouté dans la version 3.3.

@end deffn

@geindex rotator (attribut logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotator}@anchor{2c71}
@deffn {Attribut} rotator

Si cet attribut est un appelable, il se substitue à la méthode @ref{2c72,,rotate()}. Les paramètres passés à l’appelable sont ceux passés à @ref{2c72,,rotate()}.


Ajouté dans la version 3.3.

@end deffn

@geindex rotation_filename() (méthode logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotation_filename}@anchor{2c6f}
@deffn {Méthode} rotation_filename (default_name)

Modifie le nom du fichier d’un fichier de journalisation lors du roulement.

Cette méthode sert à pouvoir produire un nom de fichier personnalisé.

L’implémentation par défaut appelle l’attribut `namer' du gestionnaire, si c’est un appelable, lui passant le nom par défaut. Si l’attribut n’est pas un appelable (le défaut est @code{None}), le nom est renvoyé tel quel.

@*Paramètres: 
@code{default_name} -- le nom par défaut du fichier de journalisation.



Ajouté dans la version 3.3.

@end deffn

@geindex rotate() (méthode logging.handlers.BaseRotatingHandler)
@anchor{library/logging handlers logging handlers BaseRotatingHandler rotate}@anchor{2c72}
@deffn {Méthode} rotate (source, dest)

Lors du roulement, effectue le roulement du journal courant.

L’implémentation par défaut appelle l’attribut `rotator' du gestionnaire, si c’est un appelable, lui passant les arguments `source' et `dest'. Si l’attribut n’est pas un appelable (le défaut est @code{None}), le nom de la source est simplement renommé avec la destination.

@*Paramètres: 

@itemize *

@item 
@code{source} -- le nom du fichier source. Il s’agit normalement du nom du fichier, par exemple @code{"test.log"}.

@item 
@code{dest} -- le nom du fichier de destination. Il s’agit normalement du nom donné à la source après le roulement, par exemple @code{"test.log.1"}.
@end itemize



Ajouté dans la version 3.3.

@end deffn
@end deffn

La raison d’être de ces attributs est de vous épargner la création d’une sous-classe — vous pouvez utiliser les mêmes appels pour des instances de @ref{1560,,RotatingFileHandler} et @ref{f4c,,TimedRotatingFileHandler}. Si l'appelable `namer' ou `rotator' lève une exception, elle est gérée de la même manière que n’importe quelle exception levée lors d'un appel à @code{emit()}, c'est-à-dire par la méthode @code{handleError()} du gestionnaire.

Si vous avez besoin de faire d’importantes modifications au processus de roulement, surchargez les méthodes.

Pour un exemple, voir @ref{2c73,,Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux}.

@node Gestionnaire à roulement de fichiers — RotatingFileHandler,Gestionnaire à roulement de fichiers périodique — TimedRotatingFileHandler,Base des gestionnaires à roulement — BaseRotatingHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers rotating-file-handler}@anchor{2c74}@anchor{library/logging handlers rotatingfilehandler}@anchor{2c75}
@subsubsection Gestionnaire à roulement de fichiers — `RotatingFileHandler'


La classe @ref{1560,,RotatingFileHandler}, du module @ref{88,,logging.handlers}, gère le roulement des fichiers de journalisation sur disque.

@geindex RotatingFileHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers RotatingFileHandler}@anchor{1560}
@deffn {Classe} logging.handlers.RotatingFileHandler (filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)

Renvoie une nouvelle instance de la classe @ref{1560,,RotatingFileHandler}. Le fichier spécifié est ouvert et utilisé comme flux de sortie pour la journalisation. Si `mode' n’est pas spécifié, @code{'a'} est utilisé. Si `encoding' n’est pas à @code{None}, il est utilisé pour ouvrir le fichier avec cet encodage. Si `delay' est à `true', alors l’ouverture du fichier est reportée au premier appel de @ref{2c76,,emit()}. Par défaut, le fichier croit indéfiniment. Si `errors' est spécifié, il détermine comment sont gérées les erreurs d’encodage.

Utilisez les valeurs `maxBytes' et `backupCount' pour autoriser le roulement du fichier (`rollover') à une taille prédéterminée. Quand la taille limite est sur le point d’être dépassée, le fichier est fermé et un nouveau fichier est automatiquement ouvert pour le remplacer. Un roulement se produit dès que le fichier de journalisation actuel atteint une taille proche de `maxBytes' ; si `maxBytes' ou `backupCount' est à 0, le roulement ne se produit jamais, donc en temps normal il convient de définir `backupCount' à au moins 1, et avoir une valeur de `maxBytes' non nulle. Quand `backupCount' est non nul, le système sauvegarde les anciens fichiers de journalisation en ajoutant à leur nom les suffixes @code{".1"}, @code{".2"} et ainsi de suite. Par exemple, avec un `backupCount' de 5 et @code{app.log} comme radical du fichier, on obtient @code{app.log}, @code{app.log.1}, @code{app.log.2}, jusqu’à @code{app.log.5}. Le fichier dans lequel on écrit est toujours @code{app.log}. Quand ce fichier est rempli, il est fermé et renommé en @code{app.log.1}, et si les fichiers @code{app.log.1}, @code{app.log.2}, etc. existent, alors ils sont renommés en @code{app.log.2}, @code{app.log.3} etc. respectivement.


Modifié dans la version 3.6: L'argument `filename' accepte les objets @ref{226,,Path} aussi bien que les chaînes de caractères.



Modifié dans la version 3.9: ajout du paramètre `errors'.


@geindex doRollover() (méthode logging.handlers.RotatingFileHandler)
@anchor{library/logging handlers logging handlers RotatingFileHandler doRollover}@anchor{2c77}
@deffn {Méthode} doRollover ()

Effectue un roulement, comme décrit ci-dessus.
@end deffn

@geindex emit() (méthode logging.handlers.RotatingFileHandler)
@anchor{library/logging handlers logging handlers RotatingFileHandler emit}@anchor{2c76}
@deffn {Méthode} emit (record)

Écrit l'enregistrement dans le fichier, effectuant un roulement au besoin comme décrit précédemment.
@end deffn
@end deffn

@node Gestionnaire à roulement de fichiers périodique — TimedRotatingFileHandler,Gestionnaire à connecteur — SocketHandler,Gestionnaire à roulement de fichiers — RotatingFileHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers timed-rotating-file-handler}@anchor{2c78}@anchor{library/logging handlers timedrotatingfilehandler}@anchor{2c79}
@subsubsection Gestionnaire à roulement de fichiers périodique — `TimedRotatingFileHandler'


La classe @ref{f4c,,TimedRotatingFileHandler} du module @ref{88,,logging.handlers} gère le roulement des fichiers de journalisation sur le disque selon un intervalle de temps spécifié.

@geindex TimedRotatingFileHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler}@anchor{f4c}
@deffn {Classe} logging.handlers.TimedRotatingFileHandler (filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)

Renvoie une nouvelle instance de la classe @ref{f4c,,TimedRotatingFileHandler}. Le fichier spécifié est ouvert et utilisé comme flux de sortie pour la journalisation. Au moment du roulement, elle met également à jour le suffixe du nom du fichier. L'intervalle entre les roulements est déterminé par les valeurs de `when' et `interval'.

Utilisez `when' pour spécifier le type de `interval'. Ses valeurs possibles sont décrites ci-dessous. Notez qu'elles ne sont pas sensibles à la casse.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Type d’intervalle

@tab

Rôle de `atTime'

@item

@code{'S'}

@tab

Secondes

@tab

Ignoré

@item

@code{'M'}

@tab

Minutes

@tab

Ignoré

@item

@code{'H'}

@tab

Heures

@tab

Ignoré

@item

@code{'D'}

@tab

Jours

@tab

Ignoré

@item

@code{'W0'-'W6'}

@tab

Jour de la semaine (0 = lundi)

@tab

Utilisé pour calculer le moment du roulement

@item

@code{'midnight'}

@tab

Roulement du fichier à minuit, si `atTime' n’est pas spécifié, sinon à l’heure `atTime'

@tab

Utilisé pour calculer le moment du roulement

@end multitable


Pour un roulement selon les jours de la semaine, mettez la valeur `W0' pour lundi, `W1' pour mardi, et ainsi de suite jusqu’à `W6' pour dimanche. Dans ce cas, la valeur indiquée pour `interval' n’est pas utilisée.

Le système sauvegarde les anciens fichiers de journalisation en ajoutant une extension au nom du fichier. Les extensions sont basées sur la date et l’heure, au format `strftime' @code{%Y-%m-%d_%H-%M-%S} ou le début de celui-ci, selon l’intervalle du roulement.

Le premier calcul de la date du prochain roulement (quand le gestionnaire est créé) dépend de la dernière date de modification d’un fichier de journalisation existant, ou à défaut de la date actuelle.

Si `utc' est vrai, les temps sont UTC, sinon l'heure locale est utilisée.

Si `backupCount' est non nul, au plus `backupCount' fichiers sont sauvegardés. Si des fichiers supplémentaires devaient être créés par le jeu du roulement, les plus vieux seraient supprimés. La logique de suppression détermine les fichiers à supprimer selon l'intervalle, donc changer cette valeur peut conduire à ce que certains fichiers anciens restent sur le disque.

Si `delay' est à `true', alors l’ouverture du fichier est reportée au premier appel de @ref{2c7a,,emit()}.

Si le roulement doit se produire « à minuit » ou « à un jour fixe de la semaine » et si `atTime' n'est pas @code{None}, ce doit être une instance de @code{datetime.time} qui définit l'heure de la journée à laquelle le roulement se produit. Dans ce cas, la valeur de `atTime' ne sert qu'à déterminer la date du roulement `initial', la date des roulements ultérieurs est déterminée par le calcul standard de l'intervalle.

Si `errors' est définit, il définit comment traiter les erreurs d'encodage.

@cartouche
@quotation Note 
la date du premier roulement est déterminée lors de l'initialisation du gestionnaire. Ce n'est que lors d'un roulement que la date du roulement suivant n'est déterminée, et un roulement n'a lieu que si des entrées doivent être journalisées. Gardez bien cela à l'esprit pour ne pas avoir de surprises. Par exemple, un gestionnaire avec un intervalle « d'une minute » ne produira pas nécessairement des fichiers avec des dates (dans le nom desdits fichiers) séparées d'une minute. Si une application génère des journaux plus fréquemment que toutes les minutes au cours de son exécution, alors `dans ce cas' vous obtiendrez des fichiers avec des temps séparés d'une minute. Si la même application ne produit une entrée de journal que toutes les cinq minutes, il y aura des sauts dans les dates des fichiers produits qui correspondront aux moments où rien n'a été produit (et donc où aucun roulement n'a eu lieu).
@end quotation
@end cartouche


Modifié dans la version 3.4: ajout du paramètre `atTime'.



Modifié dans la version 3.6: L'argument `filename' accepte les objets @ref{226,,Path} aussi bien que les chaînes de caractères.



Modifié dans la version 3.9: ajout du paramètre `errors'.


@geindex doRollover() (méthode logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler doRollover}@anchor{2c7b}
@deffn {Méthode} doRollover ()

Effectue un roulement, comme décrit ci-dessus.
@end deffn

@geindex emit() (méthode logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler emit}@anchor{2c7a}
@deffn {Méthode} emit (record)

Écrit l'enregistrement dans le fichier, effectuant un roulement au besoin comme décrit précédemment.
@end deffn

@geindex getFilesToDelete() (méthode logging.handlers.TimedRotatingFileHandler)
@anchor{library/logging handlers logging handlers TimedRotatingFileHandler getFilesToDelete}@anchor{2c70}
@deffn {Méthode} getFilesToDelete ()

Returns a list of filenames which should be deleted as part of rollover. These
are the absolute paths of the oldest backup log files written by the handler.
@end deffn
@end deffn

@node Gestionnaire à connecteur — SocketHandler,DatagramHandler,Gestionnaire à roulement de fichiers périodique — TimedRotatingFileHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers socket-handler}@anchor{2c7c}@anchor{library/logging handlers sockethandler}@anchor{2c7d}
@subsubsection Gestionnaire à connecteur — `SocketHandler'


The @ref{f4d,,SocketHandler} class, located in the @ref{88,,logging.handlers} module,
sends logging output to a network socket. The base class uses a TCP socket.

@geindex SocketHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers SocketHandler}@anchor{f4d}
@deffn {Classe} logging.handlers.SocketHandler (host, port)

Returns a new instance of the @ref{f4d,,SocketHandler} class intended to
communicate with a remote machine whose address is given by `host' and `port'.


Modifié dans la version 3.4: If @code{port} is specified as @code{None}, a Unix domain socket is created
using the value in @code{host} - otherwise, a TCP socket is created.


@geindex close() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler close}@anchor{2c7e}
@deffn {Méthode} close ()

Closes the socket.
@end deffn

@geindex emit() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler emit}@anchor{2c7f}
@deffn {Méthode} emit ()

Pickles the record's attribute dictionary and writes it to the socket in
binary format. If there is an error with the socket, silently drops the
packet. If the connection was previously lost, re-establishes the
connection. To unpickle the record at the receiving end into a
@ref{fd1,,LogRecord}, use the @ref{2c1b,,makeLogRecord()}
function.
@end deffn

@geindex handleError() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler handleError}@anchor{2c80}
@deffn {Méthode} handleError ()

Handles an error which has occurred during @ref{2c7f,,emit()}. The most likely
cause is a lost connection. Closes the socket so that we can retry on the
next event.
@end deffn

@geindex makeSocket() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler makeSocket}@anchor{2c81}
@deffn {Méthode} makeSocket ()

This is a factory method which allows subclasses to define the precise
type of socket they want. The default implementation creates a TCP socket
(@ref{12d1,,socket.SOCK_STREAM}).
@end deffn

@geindex makePickle() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler makePickle}@anchor{2c82}
@deffn {Méthode} makePickle (record)

Pickles the record's attribute dictionary in binary format with a length
prefix, and returns it ready for transmission across the socket. The
details of this operation are equivalent to:

@example
data = pickle.dumps(record_attr_dict, 1)
datalen = struct.pack('>L', len(data))
return datalen + data
@end example

Note that pickles aren't completely secure. If you are concerned about
security, you may want to override this method to implement a more secure
mechanism. For example, you can sign pickles using HMAC and then verify
them on the receiving end, or alternatively you can disable unpickling of
global objects on the receiving end.
@end deffn

@geindex send() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler send}@anchor{2c83}
@deffn {Méthode} send (packet)

Send a pickled byte-string `packet' to the socket. The format of the sent
byte-string is as described in the documentation for
@ref{2c82,,makePickle()}.

This function allows for partial sends, which can happen when the network
is busy.
@end deffn

@geindex createSocket() (méthode logging.handlers.SocketHandler)
@anchor{library/logging handlers logging handlers SocketHandler createSocket}@anchor{648}
@deffn {Méthode} createSocket ()

Tries to create a socket; on failure, uses an exponential back-off
algorithm.  On initial failure, the handler will drop the message it was
trying to send.  When subsequent messages are handled by the same
instance, it will not try connecting until some time has passed.  The
default parameters are such that the initial delay is one second, and if
after that delay the connection still can't be made, the handler will
double the delay each time up to a maximum of 30 seconds.

This behaviour is controlled by the following handler attributes:


@itemize *

@item 
@code{retryStart} (initial delay, defaulting to 1.0 seconds).

@item 
@code{retryFactor} (multiplier, defaulting to 2.0).

@item 
@code{retryMax} (maximum delay, defaulting to 30.0 seconds).
@end itemize

This means that if the remote listener starts up `after' the handler has
been used, you could lose messages (since the handler won't even attempt
a connection until the delay has elapsed, but just silently drop messages
during the delay period).
@end deffn
@end deffn

@node DatagramHandler,SysLogHandler,Gestionnaire à connecteur — SocketHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers datagram-handler}@anchor{2c84}@anchor{library/logging handlers datagramhandler}@anchor{2c85}
@subsubsection DatagramHandler


The @ref{f4e,,DatagramHandler} class, located in the @ref{88,,logging.handlers}
module, inherits from @ref{f4d,,SocketHandler} to support sending logging messages
over UDP sockets.

@geindex DatagramHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers DatagramHandler}@anchor{f4e}
@deffn {Classe} logging.handlers.DatagramHandler (host, port)

Returns a new instance of the @ref{f4e,,DatagramHandler} class intended to
communicate with a remote machine whose address is given by `host' and `port'.

@cartouche
@quotation Note 
As UDP is not a streaming protocol, there is no persistent connection
between an instance of this handler and `host'. For this reason, when using a
network socket, a DNS lookup might have to be made each time an event is
logged, which can introduce some latency into the system. If this affects you,
you can do a lookup yourself and initialize this handler using the looked-up IP
address rather than the hostname.
@end quotation
@end cartouche


Modifié dans la version 3.4: If @code{port} is specified as @code{None}, a Unix domain socket is created
using the value in @code{host} - otherwise, a UDP socket is created.


@geindex emit() (méthode logging.handlers.DatagramHandler)
@anchor{library/logging handlers logging handlers DatagramHandler emit}@anchor{2c86}
@deffn {Méthode} emit ()

Pickles the record's attribute dictionary and writes it to the socket in
binary format. If there is an error with the socket, silently drops the
packet. To unpickle the record at the receiving end into a
@ref{fd1,,LogRecord}, use the @ref{2c1b,,makeLogRecord()}
function.
@end deffn

@geindex makeSocket() (méthode logging.handlers.DatagramHandler)
@anchor{library/logging handlers logging handlers DatagramHandler makeSocket}@anchor{2c87}
@deffn {Méthode} makeSocket ()

The factory method of @ref{f4d,,SocketHandler} is here overridden to create
a UDP socket (@ref{12d0,,socket.SOCK_DGRAM}).
@end deffn

@geindex send() (méthode logging.handlers.DatagramHandler)
@anchor{library/logging handlers logging handlers DatagramHandler send}@anchor{2c88}
@deffn {Méthode} send (s)

Send a pickled byte-string to a socket. The format of the sent byte-string
is as described in the documentation for @ref{2c82,,SocketHandler.makePickle()}.
@end deffn
@end deffn

@node SysLogHandler,NTEventLogHandler,DatagramHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers syslog-handler}@anchor{2c89}@anchor{library/logging handlers sysloghandler}@anchor{2c8a}
@subsubsection SysLogHandler


The @ref{647,,SysLogHandler} class, located in the @ref{88,,logging.handlers} module,
supports sending logging messages to a remote or local Unix syslog.

@geindex SysLogHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers SysLogHandler}@anchor{647}
@deffn {Classe} logging.handlers.SysLogHandler (address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)

Returns a new instance of the @ref{647,,SysLogHandler} class intended to
communicate with a remote Unix machine whose address is given by `address' in
the form of a @code{(host, port)} tuple.  If `address' is not specified,
@code{('localhost', 514)} is used.  The address is used to open a socket.  An
alternative to providing a @code{(host, port)} tuple is providing an address as a
string, for example '/dev/log'. In this case, a Unix domain socket is used to
send the message to the syslog. If `facility' is not specified,
@code{LOG_USER} is used. The type of socket opened depends on the
`socktype' argument, which defaults to @ref{12d0,,socket.SOCK_DGRAM} and thus
opens a UDP socket. To open a TCP socket (for use with the newer syslog
daemons such as rsyslog), specify a value of @ref{12d1,,socket.SOCK_STREAM}.

Note that if your server is not listening on UDP port 514,
@ref{647,,SysLogHandler} may appear not to work. In that case, check what
address you should be using for a domain socket - it's system dependent.
For example, on Linux it's usually '/dev/log' but on OS/X it's
'/var/run/syslog'. You'll need to check your platform and use the
appropriate address (you may need to do this check at runtime if your
application needs to run on several platforms). On Windows, you pretty
much have to use the UDP option.

@cartouche
@quotation Note 
On macOS 12.x (Monterey), Apple has changed the behaviour of their
syslog daemon - it no longer listens on a domain socket. Therefore, you cannot
expect @ref{647,,SysLogHandler} to work on this system.

See gh-91070@footnote{https://github.com/python/cpython/issues/91070} for more information.
@end quotation
@end cartouche


Modifié dans la version 3.2: `socktype' was added.


@geindex close() (méthode logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler close}@anchor{2c8b}
@deffn {Méthode} close ()

Closes the socket to the remote host.
@end deffn

@geindex createSocket() (méthode logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler createSocket}@anchor{646}
@deffn {Méthode} createSocket ()

Tries to create a socket and, if it's not a datagram socket, connect it
to the other end. This method is called during handler initialization,
but it's not regarded as an error if the other end isn't listening at
this point - the method will be called again when emitting an event, if
there is no socket at that point.


Ajouté dans la version 3.11.

@end deffn

@geindex emit() (méthode logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler emit}@anchor{2c8c}
@deffn {Méthode} emit (record)

The record is formatted, and then sent to the syslog server. If exception
information is present, it is `not' sent to the server.


Modifié dans la version 3.2.1: (See: bpo-12168@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12168}.) In earlier versions, the message sent to the
syslog daemons was always terminated with a NUL byte, because early
versions of these daemons expected a NUL terminated message - even
though it's not in the relevant specification (
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html}). More recent
versions of these daemons don't expect the NUL byte but strip it off
if it's there, and even more recent daemons (which adhere more closely
to RFC 5424) pass the NUL byte on as part of the message.

To enable easier handling of syslog messages in the face of all these
differing daemon behaviours, the appending of the NUL byte has been
made configurable, through the use of a class-level attribute,
@code{append_nul}. This defaults to @code{True} (preserving the existing
behaviour) but can be set to @code{False} on a @code{SysLogHandler} instance
in order for that instance to `not' append the NUL terminator.



Modifié dans la version 3.3: (See: bpo-12419@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12419}.) In earlier versions, there was no facility for
an "ident" or "tag" prefix to identify the source of the message. This
can now be specified using a class-level attribute, defaulting to
@code{""} to preserve existing behaviour, but which can be overridden on
a @code{SysLogHandler} instance in order for that instance to prepend
the ident to every message handled. Note that the provided ident must
be text, not bytes, and is prepended to the message exactly as is.

@end deffn

@geindex encodePriority() (méthode logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler encodePriority}@anchor{2c8d}
@deffn {Méthode} encodePriority (facility, priority)

Encodes the facility and priority into an integer. You can pass in strings
or integers - if strings are passed, internal mapping dictionaries are
used to convert them to integers.

The symbolic @code{LOG_} values are defined in @ref{647,,SysLogHandler} and
mirror the values defined in the @code{sys/syslog.h} header file.

`Priorities'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Name (string)

@tab

Symbolic value

@item

@code{alert}

@tab

LOG_ALERT

@item

@code{crit} ou @code{critical}

@tab

LOG_CRIT

@item

@code{debug}

@tab

LOG_DEBUG

@item

@code{emerg} ou @code{panic}

@tab

LOG_EMERG

@item

@code{err} ou @code{error}

@tab

LOG_ERR

@item

@code{info}

@tab

LOG_INFO

@item

@code{notice}

@tab

LOG_NOTICE

@item

@code{warn} ou @code{warning}

@tab

LOG_WARNING

@end multitable


`Facilities'


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Name (string)

@tab

Symbolic value

@item

@code{auth}

@tab

LOG_AUTH

@item

@code{authpriv}

@tab

LOG_AUTHPRIV

@item

@code{cron}

@tab

LOG_CRON

@item

@code{daemon}

@tab

LOG_DAEMON

@item

@code{ftp}

@tab

LOG_FTP

@item

@code{kern}

@tab

LOG_KERN

@item

@code{lpr}

@tab

LOG_LPR

@item

@code{mail}

@tab

LOG_MAIL

@item

@code{news}

@tab

LOG_NEWS

@item

@code{syslog}

@tab

LOG_SYSLOG

@item

@code{user}

@tab

LOG_USER

@item

@code{uucp}

@tab

LOG_UUCP

@item

@code{local0}

@tab

LOG_LOCAL0

@item

@code{local1}

@tab

LOG_LOCAL1

@item

@code{local2}

@tab

LOG_LOCAL2

@item

@code{local3}

@tab

LOG_LOCAL3

@item

@code{local4}

@tab

LOG_LOCAL4

@item

@code{local5}

@tab

LOG_LOCAL5

@item

@code{local6}

@tab

LOG_LOCAL6

@item

@code{local7}

@tab

LOG_LOCAL7

@end multitable

@end deffn

@geindex mapPriority() (méthode logging.handlers.SysLogHandler)
@anchor{library/logging handlers logging handlers SysLogHandler mapPriority}@anchor{2c8e}
@deffn {Méthode} mapPriority (levelname)

Maps a logging level name to a syslog priority name.
You may need to override this if you are using custom levels, or
if the default algorithm is not suitable for your needs. The
default algorithm maps @code{DEBUG}, @code{INFO}, @code{WARNING}, @code{ERROR} and
@code{CRITICAL} to the equivalent syslog names, and all other level
names to 'warning'.
@end deffn
@end deffn

@node NTEventLogHandler,SMTPHandler,SysLogHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers nt-eventlog-handler}@anchor{2c8f}@anchor{library/logging handlers nteventloghandler}@anchor{2c90}
@subsubsection NTEventLogHandler


The @ref{2c91,,NTEventLogHandler} class, located in the @ref{88,,logging.handlers}
module, supports sending logging messages to a local Windows NT, Windows 2000 or
Windows XP event log. Before you can use it, you need Mark Hammond's Win32
extensions for Python installed.

@geindex NTEventLogHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers NTEventLogHandler}@anchor{2c91}
@deffn {Classe} logging.handlers.NTEventLogHandler (appname, dllname=None, logtype='Application')

Returns a new instance of the @ref{2c91,,NTEventLogHandler} class. The `appname' is
used to define the application name as it appears in the event log. An
appropriate registry entry is created using this name. The `dllname' should give
the fully qualified pathname of a .dll or .exe which contains message
definitions to hold in the log (if not specified, @code{'win32service.pyd'} is used
- this is installed with the Win32 extensions and contains some basic
placeholder message definitions. Note that use of these placeholders will make
your event logs big, as the entire message source is held in the log. If you
want slimmer logs, you have to pass in the name of your own .dll or .exe which
contains the message definitions you want to use in the event log). The
`logtype' is one of @code{'Application'}, @code{'System'} or @code{'Security'}, and
defaults to @code{'Application'}.

@geindex close() (méthode logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler close}@anchor{2c92}
@deffn {Méthode} close ()

At this point, you can remove the application name from the registry as a
source of event log entries. However, if you do this, you will not be able
to see the events as you intended in the Event Log Viewer - it needs to be
able to access the registry to get the .dll name. The current version does
not do this.
@end deffn

@geindex emit() (méthode logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler emit}@anchor{2c93}
@deffn {Méthode} emit (record)

Determines the message ID, event category and event type, and then logs
the message in the NT event log.
@end deffn

@geindex getEventCategory() (méthode logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler getEventCategory}@anchor{2c94}
@deffn {Méthode} getEventCategory (record)

Returns the event category for the record. Override this if you want to
specify your own categories. This version returns 0.
@end deffn

@geindex getEventType() (méthode logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler getEventType}@anchor{2c95}
@deffn {Méthode} getEventType (record)

Returns the event type for the record. Override this if you want to
specify your own types. This version does a mapping using the handler's
typemap attribute, which is set up in @code{__init__()} to a dictionary
which contains mappings for @code{DEBUG}, @code{INFO},
@code{WARNING}, @code{ERROR} and @code{CRITICAL}. If you are using
your own levels, you will either need to override this method or place a
suitable dictionary in the handler's `typemap' attribute.
@end deffn

@geindex getMessageID() (méthode logging.handlers.NTEventLogHandler)
@anchor{library/logging handlers logging handlers NTEventLogHandler getMessageID}@anchor{2c96}
@deffn {Méthode} getMessageID (record)

Returns the message ID for the record. If you are using your own messages,
you could do this by having the `msg' passed to the logger being an ID
rather than a format string. Then, in here, you could use a dictionary
lookup to get the message ID. This version returns 1, which is the base
message ID in @code{win32service.pyd}.
@end deffn
@end deffn

@node SMTPHandler,MemoryHandler,NTEventLogHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers smtp-handler}@anchor{2c97}@anchor{library/logging handlers smtphandler}@anchor{2c98}
@subsubsection SMTPHandler


The @ref{2c99,,SMTPHandler} class, located in the @ref{88,,logging.handlers} module,
supports sending logging messages to an email address via SMTP.

@geindex SMTPHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers SMTPHandler}@anchor{2c99}
@deffn {Classe} logging.handlers.SMTPHandler (mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None, timeout=1.0)

Returns a new instance of the @ref{2c99,,SMTPHandler} class. The instance is
initialized with the from and to addresses and subject line of the email. The
`toaddrs' should be a list of strings. To specify a non-standard SMTP port, use
the (host, port) tuple format for the `mailhost' argument. If you use a string,
the standard SMTP port is used. If your SMTP server requires authentication, you
can specify a (username, password) tuple for the `credentials' argument.

To specify the use of a secure protocol (TLS), pass in a tuple to the
`secure' argument. This will only be used when authentication credentials are
supplied. The tuple should be either an empty tuple, or a single-value tuple
with the name of a keyfile, or a 2-value tuple with the names of the keyfile
and certificate file. (This tuple is passed to the
@ref{1118,,smtplib.SMTP.starttls()} method.)

A timeout can be specified for communication with the SMTP server using the
`timeout' argument.


Modifié dans la version 3.3: Added the `timeout' parameter.


@geindex emit() (méthode logging.handlers.SMTPHandler)
@anchor{library/logging handlers logging handlers SMTPHandler emit}@anchor{2c9a}
@deffn {Méthode} emit (record)

Formats the record and sends it to the specified addressees.
@end deffn

@geindex getSubject() (méthode logging.handlers.SMTPHandler)
@anchor{library/logging handlers logging handlers SMTPHandler getSubject}@anchor{2c9b}
@deffn {Méthode} getSubject (record)

If you want to specify a subject line which is record-dependent, override
this method.
@end deffn
@end deffn

@node MemoryHandler,HTTPHandler,SMTPHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers memory-handler}@anchor{2c9c}@anchor{library/logging handlers memoryhandler}@anchor{2c9d}
@subsubsection MemoryHandler


The @ref{2c4d,,MemoryHandler} class, located in the @ref{88,,logging.handlers} module,
supports buffering of logging records in memory, periodically flushing them to a
`target' handler. Flushing occurs whenever the buffer is full, or when an
event of a certain severity or greater is seen.

@ref{2c4d,,MemoryHandler} is a subclass of the more general
@ref{2c9e,,BufferingHandler}, which is an abstract class. This buffers logging
records in memory. Whenever each record is added to the buffer, a check is made
by calling @code{shouldFlush()} to see if the buffer should be flushed.  If it
should, then @code{flush()} is expected to do the flushing.

@geindex BufferingHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers BufferingHandler}@anchor{2c9e}
@deffn {Classe} logging.handlers.BufferingHandler (capacity)

Initializes the handler with a buffer of the specified capacity. Here,
`capacity' means the number of logging records buffered.

@geindex emit() (méthode logging.handlers.BufferingHandler)
@anchor{library/logging handlers logging handlers BufferingHandler emit}@anchor{2c9f}
@deffn {Méthode} emit (record)

Append the record to the buffer. If @ref{2ca0,,shouldFlush()} returns true,
call @ref{2ca1,,flush()} to process the buffer.
@end deffn

@geindex flush() (méthode logging.handlers.BufferingHandler)
@anchor{library/logging handlers logging handlers BufferingHandler flush}@anchor{2ca1}
@deffn {Méthode} flush ()

For a @ref{2c9e,,BufferingHandler} instance, flushing means that it sets the
buffer to an empty list. This method can be overwritten to implement more useful
flushing behavior.
@end deffn

@geindex shouldFlush() (méthode logging.handlers.BufferingHandler)
@anchor{library/logging handlers logging handlers BufferingHandler shouldFlush}@anchor{2ca0}
@deffn {Méthode} shouldFlush (record)

Return @code{True} if the buffer is up to capacity. This method can be
overridden to implement custom flushing strategies.
@end deffn
@end deffn

@geindex MemoryHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers MemoryHandler}@anchor{2c4d}
@deffn {Classe} logging.handlers.MemoryHandler (capacity, flushLevel=ERROR, target=None, flushOnClose=True)

Returns a new instance of the @ref{2c4d,,MemoryHandler} class. The instance is
initialized with a buffer size of `capacity' (number of records buffered).
If `flushLevel' is not specified, @code{ERROR} is used. If no `target' is
specified, the target will need to be set using @ref{2ca2,,setTarget()} before this
handler does anything useful. If `flushOnClose' is specified as @code{False},
then the buffer is `not' flushed when the handler is closed. If not specified
or specified as @code{True}, the previous behaviour of flushing the buffer will
occur when the handler is closed.


Modifié dans la version 3.6: The `flushOnClose' parameter was added.


@geindex close() (méthode logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler close}@anchor{2ca3}
@deffn {Méthode} close ()

Calls @ref{2ca4,,flush()}, sets the target to @code{None} and clears the
buffer.
@end deffn

@geindex flush() (méthode logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler flush}@anchor{2ca4}
@deffn {Méthode} flush ()

For a @ref{2c4d,,MemoryHandler} instance, flushing means just sending the buffered
records to the target, if there is one. The buffer is also cleared when
buffered records are sent to the target. Override if you want different behavior.
@end deffn

@geindex setTarget() (méthode logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler setTarget}@anchor{2ca2}
@deffn {Méthode} setTarget (target)

Sets the target handler for this handler.
@end deffn

@geindex shouldFlush() (méthode logging.handlers.MemoryHandler)
@anchor{library/logging handlers logging handlers MemoryHandler shouldFlush}@anchor{2ca5}
@deffn {Méthode} shouldFlush (record)

Checks for buffer full or a record at the `flushLevel' or higher.
@end deffn
@end deffn

@node HTTPHandler,QueueHandler,MemoryHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers http-handler}@anchor{2ca6}@anchor{library/logging handlers httphandler}@anchor{2ca7}
@subsubsection HTTPHandler


The @ref{e18,,HTTPHandler} class, located in the @ref{88,,logging.handlers} module,
supports sending logging messages to a web server, using either @code{GET} or
@code{POST} semantics.

@geindex HTTPHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers HTTPHandler}@anchor{e18}
@deffn {Classe} logging.handlers.HTTPHandler (host, url, method='GET', secure=False, credentials=None, context=None)

Returns a new instance of the @ref{e18,,HTTPHandler} class. The `host' can be
of the form @code{host:port}, should you need to use a specific port number.  If
no `method' is specified, @code{GET} is used. If `secure' is true, a HTTPS
connection will be used. The `context' parameter may be set to a
@ref{291,,ssl.SSLContext} instance to configure the SSL settings used for the
HTTPS connection. If `credentials' is specified, it should be a 2-tuple
consisting of userid and password, which will be placed in a HTTP
'Authorization' header using Basic authentication. If you specify
credentials, you should also specify secure=True so that your userid and
password are not passed in cleartext across the wire.


Modifié dans la version 3.5: The `context' parameter was added.


@geindex mapLogRecord() (méthode logging.handlers.HTTPHandler)
@anchor{library/logging handlers logging handlers HTTPHandler mapLogRecord}@anchor{2ca8}
@deffn {Méthode} mapLogRecord (record)

Provides a dictionary, based on @code{record}, which is to be URL-encoded
and sent to the web server. The default implementation just returns
@code{record.__dict__}. This method can be overridden if e.g. only a
subset of @ref{fd1,,LogRecord} is to be sent to the web server, or
if more specific customization of what's sent to the server is required.
@end deffn

@geindex emit() (méthode logging.handlers.HTTPHandler)
@anchor{library/logging handlers logging handlers HTTPHandler emit}@anchor{2ca9}
@deffn {Méthode} emit (record)

Sends the record to the web server as a URL-encoded dictionary. The
@ref{2ca8,,mapLogRecord()} method is used to convert the record to the
dictionary to be sent.
@end deffn

@cartouche
@quotation Note 
Since preparing a record for sending it to a web server is not
the same as a generic formatting operation, using
@ref{2bfd,,setFormatter()} to specify a
@ref{1449,,Formatter} for a @ref{e18,,HTTPHandler} has no effect.
Instead of calling @ref{2c07,,format()}, this handler calls
@ref{2ca8,,mapLogRecord()} and then @ref{e7e,,urllib.parse.urlencode()} to encode the
dictionary in a form suitable for sending to a web server.
@end quotation
@end cartouche
@end deffn

@node QueueHandler,QueueListener,HTTPHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers queue-handler}@anchor{2caa}@anchor{library/logging handlers queuehandler}@anchor{2cab}
@subsubsection QueueHandler



Ajouté dans la version 3.2.


The @ref{1765,,QueueHandler} class, located in the @ref{88,,logging.handlers} module,
supports sending logging messages to a queue, such as those implemented in the
@ref{b5,,queue} or @ref{93,,multiprocessing} modules.

Along with the @ref{e19,,QueueListener} class, @ref{1765,,QueueHandler} can be used
to let handlers do their work on a separate thread from the one which does the
logging. This is important in web applications and also other service
applications where threads servicing clients need to respond as quickly as
possible, while any potentially slow operations (such as sending an email via
@ref{2c99,,SMTPHandler}) are done on a separate thread.

@geindex QueueHandler (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers QueueHandler}@anchor{1765}
@deffn {Classe} logging.handlers.QueueHandler (queue)

Returns a new instance of the @ref{1765,,QueueHandler} class. The instance is
initialized with the queue to send messages to. The `queue' can be any
queue-like object; it's used as-is by the @ref{2cac,,enqueue()} method, which
needs to know how to send messages to it. The queue is not `required' to
have the task tracking API, which means that you can use
@ref{b58,,SimpleQueue} instances for `queue'.

@cartouche
@quotation Note 
If you are using @ref{93,,multiprocessing}, you should avoid using
@ref{b58,,SimpleQueue} and instead use @ref{178a,,multiprocessing.Queue}.
@end quotation
@end cartouche

@geindex emit() (méthode logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler emit}@anchor{2cad}
@deffn {Méthode} emit (record)

Enqueues the result of preparing the LogRecord. Should an exception
occur (e.g. because a bounded queue has filled up), the
@ref{2c05,,handleError()} method is called to handle the
error. This can result in the record silently being dropped (if
@ref{11d6,,logging.raiseExceptions} is @code{False}) or a message printed to
@code{sys.stderr} (if @ref{11d6,,logging.raiseExceptions} is @code{True}).
@end deffn

@geindex prepare() (méthode logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler prepare}@anchor{2cae}
@deffn {Méthode} prepare (record)

Prepares a record for queuing. The object returned by this
method is enqueued.

The base implementation formats the record to merge the message,
arguments, exception and stack information, if present.  It also removes
unpickleable items from the record in-place. Specifically, it overwrites
the record's @code{msg} and @code{message} attributes with the merged
message (obtained by calling the handler's @ref{60a,,format()} method), and
sets the @code{args}, @code{exc_info} and @code{exc_text} attributes
to @code{None}.

You might want to override this method if you want to convert
the record to a dict or JSON string, or send a modified copy
of the record while leaving the original intact.

@cartouche
@quotation Note 
The base implementation formats the message with arguments, sets
the @code{message} and @code{msg} attributes to the formatted message and
sets the @code{args} and @code{exc_text} attributes to @code{None} to allow
pickling and to prevent further attempts at formatting. This means
that a handler on the @ref{e19,,QueueListener} side won't have the
information to do custom formatting, e.g. of exceptions. You may wish
to subclass @code{QueueHandler} and override this method to e.g. avoid
setting @code{exc_text} to @code{None}. Note that the @code{message} / @code{msg}
/ @code{args} changes are related to ensuring the record is pickleable,
and you might or might not be able to avoid doing that depending on
whether your @code{args} are pickleable. (Note that you may have to
consider not only your own code but also code in any libraries that
you use.)
@end quotation
@end cartouche
@end deffn

@geindex enqueue() (méthode logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler enqueue}@anchor{2cac}
@deffn {Méthode} enqueue (record)

Enqueues the record on the queue using @code{put_nowait()}; you may
want to override this if you want to use blocking behaviour, or a
timeout, or a customized queue implementation.
@end deffn

@geindex listener (attribut logging.handlers.QueueHandler)
@anchor{library/logging handlers logging handlers QueueHandler listener}@anchor{2c51}
@deffn {Attribut} listener

When created via configuration using @ref{118d,,dictConfig()}, this
attribute will contain a @ref{e19,,QueueListener} instance for use with this
handler. Otherwise, it will be @code{None}.


Ajouté dans la version 3.12.

@end deffn
@end deffn

@node QueueListener,,QueueHandler,logging handlers --- Logging handlers
@anchor{library/logging handlers queue-listener}@anchor{2caf}@anchor{library/logging handlers queuelistener}@anchor{2cb0}
@subsubsection QueueListener



Ajouté dans la version 3.2.


The @ref{e19,,QueueListener} class, located in the @ref{88,,logging.handlers}
module, supports receiving logging messages from a queue, such as those
implemented in the @ref{b5,,queue} or @ref{93,,multiprocessing} modules. The
messages are received from a queue in an internal thread and passed, on
the same thread, to one or more handlers for processing. While
@ref{e19,,QueueListener} is not itself a handler, it is documented here
because it works hand-in-hand with @ref{1765,,QueueHandler}.

Along with the @ref{1765,,QueueHandler} class, @ref{e19,,QueueListener} can be used
to let handlers do their work on a separate thread from the one which does the
logging. This is important in web applications and also other service
applications where threads servicing clients need to respond as quickly as
possible, while any potentially slow operations (such as sending an email via
@ref{2c99,,SMTPHandler}) are done on a separate thread.

@geindex QueueListener (classe dans logging.handlers)
@anchor{library/logging handlers logging handlers QueueListener}@anchor{e19}
@deffn {Classe} logging.handlers.QueueListener (queue, *handlers, respect_handler_level=False)

Returns a new instance of the @ref{e19,,QueueListener} class. The instance is
initialized with the queue to send messages to and a list of handlers which
will handle entries placed on the queue. The queue can be any queue-like
object; it's passed as-is to the @ref{2cb1,,dequeue()} method, which needs
to know how to get messages from it. The queue is not `required' to have the
task tracking API (though it's used if available), which means that you can
use @ref{b58,,SimpleQueue} instances for `queue'.

@cartouche
@quotation Note 
If you are using @ref{93,,multiprocessing}, you should avoid using
@ref{b58,,SimpleQueue} and instead use @ref{178a,,multiprocessing.Queue}.
@end quotation
@end cartouche

If @code{respect_handler_level} is @code{True}, a handler's level is respected
(compared with the level for the message) when deciding whether to pass
messages to that handler; otherwise, the behaviour is as in previous Python
versions - to always pass each message to each handler.


Modifié dans la version 3.5: The @code{respect_handler_level} argument was added.


@geindex dequeue() (méthode logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener dequeue}@anchor{2cb1}
@deffn {Méthode} dequeue (block)

Dequeues a record and return it, optionally blocking.

The base implementation uses @code{get()}. You may want to override this
method if you want to use timeouts or work with custom queue
implementations.
@end deffn

@geindex prepare() (méthode logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener prepare}@anchor{2cb2}
@deffn {Méthode} prepare (record)

Prepare a record for handling.

This implementation just returns the passed-in record. You may want to
override this method if you need to do any custom marshalling or
manipulation of the record before passing it to the handlers.
@end deffn

@geindex handle() (méthode logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener handle}@anchor{2cb3}
@deffn {Méthode} handle (record)

Handle a record.

This just loops through the handlers offering them the record
to handle. The actual object passed to the handlers is that which
is returned from @ref{2cb2,,prepare()}.
@end deffn

@geindex start() (méthode logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener start}@anchor{2cb4}
@deffn {Méthode} start ()

Starts the listener.

This starts up a background thread to monitor the queue for
LogRecords to process.
@end deffn

@geindex stop() (méthode logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener stop}@anchor{2cb5}
@deffn {Méthode} stop ()

Stops the listener.

This asks the thread to terminate, and then waits for it to do so.
Note that if you don't call this before your application exits, there
may be some records still left on the queue, which won't be processed.
@end deffn

@geindex enqueue_sentinel() (méthode logging.handlers.QueueListener)
@anchor{library/logging handlers logging handlers QueueListener enqueue_sentinel}@anchor{2cb6}
@deffn {Méthode} enqueue_sentinel ()

Writes a sentinel to the queue to tell the listener to quit. This
implementation uses @code{put_nowait()}.  You may want to override this
method if you want to use timeouts or work with custom queue
implementations.


Ajouté dans la version 3.3.

@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{86,,logging}

Référence d'API pour le module de journalisation.

@item Module @ref{87,,logging.config}

API de configuration pour le module de journalisation.
@end table


@node platform --- Access to underlying platform's identifying data,errno --- Standard errno system symbols,logging handlers --- Logging handlers,Services génériques du système d'exploitation
@anchor{library/platform doc}@anchor{2cb7}@anchor{library/platform module-platform}@anchor{a9}@anchor{library/platform platform-access-to-underlying-platform-s-identifying-data}@anchor{2cb8}
@subsection @code{platform} ---  Access to underlying platform's identifying data


@geindex module; platform

`Code source :' Lib/platform.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/platform.py}


__________________________________________________________________


@cartouche
@quotation Note 
Les spécificités des plateformes sont regroupées dans des sections triées par ordre alphabétique. Linux est inclus dans la section Unix.
@end quotation
@end cartouche

@menu
* Multiplateformes:: 
* Plateforme Java:: 
* Plateforme Windows:: 
* macOS Platform:: 
* iOS Platform:: 
* Plateformes Unix:: 
* Linux Platforms:: 
* Android Platform:: 

@end menu

@node Multiplateformes,Plateforme Java,,platform --- Access to underlying platform's identifying data
@anchor{library/platform cross-platform}@anchor{2cb9}
@subsubsection Multiplateformes


@geindex architecture() (dans le module platform)
@anchor{library/platform platform architecture}@anchor{1614}
@deffn {Fonction} platform.architecture (executable=sys.executable, bits='@w{'}, linkage='@w{'})

Interroge l'exécutable fourni (par défaut l'interpréteur Python) sur les informations de l'architecture.

Renvoie un `n'-uplet de @code{(bits, linkage)} qui contient de l'information sur l'architecture binaire et le format de lien. Les deux valeurs sont des chaînes de caractères.

Lorsqu'une valeur ne peut être déterminée, la valeur passée en paramètre est utilisée. Si la valeur passée à `bits' est @code{'@w{'}}, la valeur de @code{sizeof(pointer)} (ou @code{sizeof(long)} sur les versions Python antérieures à 1.5.2) est utilisée comme indicateur de la taille de pointeur prise en charge.

La fonction dépend de la commande @code{file} du système pour accomplir la tâche. @code{file} est disponible sur quasiment toutes les plateformes Unix ainsi que sur certaines plateformes hors de la famille Unix et l'exécutable doit pointer vers l'interpréteur Python. Des valeurs par défaut raisonnables sont utilisées lorsque les conditions précédentes ne sont pas atteintes.

@cartouche
@quotation Note 
On macOS (and perhaps other platforms), executable files may be
universal files containing multiple architectures.

To get at the "64-bitness" of the current interpreter, it is more
reliable to query the @ref{11a2,,sys.maxsize} attribute:

@example
is_64bits = sys.maxsize > 2**32
@end example
@end quotation
@end cartouche
@end deffn

@geindex machine() (dans le module platform)
@anchor{library/platform platform machine}@anchor{2cba}
@deffn {Fonction} platform.machine ()

Returns the machine type, e.g. @code{'AMD64'}. An empty string is returned if the
value cannot be determined.
@end deffn

@geindex node() (dans le module platform)
@anchor{library/platform platform node}@anchor{2cbb}
@deffn {Fonction} platform.node ()

Renvoie le nom de l'ordinateur sur le réseau (pas forcément pleinement qualifié). Une chaîne de caractères vide est renvoyée s'il ne peut pas être déterminé.
@end deffn

@geindex platform() (dans le module platform)
@anchor{library/platform platform platform}@anchor{16e3}
@deffn {Fonction} platform.platform (aliased=False, terse=False)

Renvoie une chaîne de caractère identifiant la plateforme avec le plus d'informations possible.

La valeur renvoyée est destinée à la `lecture humaine' plutôt que l'interprétation machine. Il est possible qu'elle soit différente selon la plateforme et c'est voulu.

Si `aliased' est vrai, la fonction utilisera des alias pour certaines plateformes qui utilisent des noms de système qui diffèrent de leurs noms communs. Par exemple, SunOS sera reconnu comme Solaris. La fonction @ref{2cbc,,system_alias()} est utilisée pour l'implémentation.

Si `terse' est vrai, la fonction ne renverra que l'information nécessaire à l'identification de la plateforme.


Modifié dans la version 3.8: Sur MacOS, la fonction essaie maintenant d'utiliser la fonction @ref{19c2,,mac_ver()} pour obtenir la version de MacOS plutôt que la version de Darwin : le résultat de @code{mac_ver} est utilisé si ce n'est pas une chaîne vide.

@end deffn

@geindex processor() (dans le module platform)
@anchor{library/platform platform processor}@anchor{2cbd}
@deffn {Fonction} platform.processor ()

Renvoie le (vrai) nom du processeur. Par exemple : @code{'amdk6'}.

Une chaîne de caractères vide est renvoyée si la valeur ne peut être déterminée. Prenez note que plusieurs plateformes ne fournissent pas cette information ou renvoient la même valeur que la fonction @ref{2cba,,machine()}. NetBSD agit ainsi.
@end deffn

@geindex python_build() (dans le module platform)
@anchor{library/platform platform python_build}@anchor{2cbe}
@deffn {Fonction} platform.python_build ()

Renvoie une paire @code{(buildno, builddate)} de chaîne de caractères identifiant la version et la date de compilation de Python.
@end deffn

@geindex python_compiler() (dans le module platform)
@anchor{library/platform platform python_compiler}@anchor{2cbf}
@deffn {Fonction} platform.python_compiler ()

Renvoie une chaîne de caractères identifiant le compilateur utilisé pour compiler Python.
@end deffn

@geindex python_branch() (dans le module platform)
@anchor{library/platform platform python_branch}@anchor{2cc0}
@deffn {Fonction} platform.python_branch ()

Renvoie la chaîne de caractères identifiant la branche du gestionnaire de versions de l'implémentation Python.
@end deffn

@geindex python_implementation() (dans le module platform)
@anchor{library/platform platform python_implementation}@anchor{2cc1}
@deffn {Fonction} platform.python_implementation ()

Renvoie une chaîne de caractères identifiant l'implémentation de Python. Des valeurs possibles sont : @code{CPython}, @code{IronPython}, @code{Jython}, @code{Pypy}.
@end deffn

@geindex python_revision() (dans le module platform)
@anchor{library/platform platform python_revision}@anchor{2cc2}
@deffn {Fonction} platform.python_revision ()

Renvoie la chaîne de caractères identifiant la révision du gestionnaire de versions de l'implémentation Python.
@end deffn

@geindex python_version() (dans le module platform)
@anchor{library/platform platform python_version}@anchor{2cc3}
@deffn {Fonction} platform.python_version ()

Renvoie la version de Python comme une chaîne de caractères @code{'major.minor.patchlevel'}.

Prenez note que la valeur renvoyée inclut toujours le `patchlevel' (valeur par défaut de 0) à la différence de @code{sys.version}.
@end deffn

@geindex python_version_tuple() (dans le module platform)
@anchor{library/platform platform python_version_tuple}@anchor{2cc4}
@deffn {Fonction} platform.python_version_tuple ()

Renvoie la version de Python comme un triplet de chaînes de caractères @code{(major, minor, patchlevel)}.

Prenez note que la valeur renvoyée inclut toujours le `patchlevel' (valeur par défaut de @code{'0'}) à la différence de @code{sys.version}.
@end deffn

@geindex release() (dans le module platform)
@anchor{library/platform platform release}@anchor{2cc5}
@deffn {Fonction} platform.release ()

Returns the system's release, e.g. @code{'2.2.0'} or @code{'NT'}. An empty string is
returned if the value cannot be determined.
@end deffn

@geindex system() (dans le module platform)
@anchor{library/platform platform system}@anchor{1de8}
@deffn {Fonction} platform.system ()

Renvoie le nom du système d'exploitation, tel que @code{'Linux'}, @code{'Darwin'}, @code{'Java'}, @code{'Windows'}. Une chaîne de caractères vide est renvoyée si le nom ne peut être déterminé.

On iOS and Android, this returns the user-facing OS name (i.e, @code{'iOS},
@code{'iPadOS'} or @code{'Android'}). To obtain the kernel name (@code{'Darwin'} or
@code{'Linux'}), use @ref{10f6,,os.uname()}.
@end deffn

@geindex system_alias() (dans le module platform)
@anchor{library/platform platform system_alias}@anchor{2cbc}
@deffn {Fonction} platform.system_alias (system, release, version)

Renvoie @code{(system, release, version)} avec des alias pour les noms communs de certains systèmes. Modifie aussi l'ordre de l'information pour éviter la confusion.
@end deffn

@geindex version() (dans le module platform)
@anchor{library/platform platform version}@anchor{2cc6}
@deffn {Fonction} platform.version ()

Renvoie la version de déploiement du système. Par exemple, @code{'#3 on degas'}. Une chaîne de caractères vide est renvoyée si aucune valeur ne peut être déterminée.

On iOS and Android, this is the user-facing OS version. To obtain the
Darwin or Linux kernel version, use @ref{10f6,,os.uname()}.
@end deffn

@geindex uname() (dans le module platform)
@anchor{library/platform platform uname}@anchor{19c0}
@deffn {Fonction} platform.uname ()

Interface de `uname' relativement portable. Renvoie un @ref{1c5,,namedtuple()} contenant six attributs : @ref{1de8,,system}, @ref{2cbb,,node}, @ref{2cc5,,release}, @ref{2cc6,,version}, @ref{2cba,,machine} et @ref{2cbd,,processor}.

@ref{2cbd,,processor} is resolved late, on demand.

Note: the first two attribute names differ from the names presented by
@ref{10f6,,os.uname()}, where they are named @code{sysname} and
@code{nodename}.

Les entrées qui ne peuvent pas être identifiées ont la valeur @code{'@w{'}}.


Modifié dans la version 3.3: Result changed from a tuple to a @ref{1c5,,namedtuple()}.



Modifié dans la version 3.9: @ref{2cbd,,processor} is resolved late instead of immediately.

@end deffn

@node Plateforme Java,Plateforme Windows,Multiplateformes,platform --- Access to underlying platform's identifying data
@anchor{library/platform java-platform}@anchor{2cc7}
@subsubsection Plateforme Java


@geindex java_ver() (dans le module platform)
@anchor{library/platform platform java_ver}@anchor{2a4}
@deffn {Fonction} platform.java_ver (release='@w{'}, vendor='@w{'}, vminfo=('@w{'}, '@w{'}, '@w{'}), osinfo=('@w{'}, '@w{'}, '@w{'}))

Version de l'interface pour Jython.

Renvoie un `n'-uplet @code{(release, vendor, vminfo, osinfo)}. `vminfo' est un triplet de valeur @code{(vm_name, vm_release, vm_vendor)} et `osinfo' est un triplet de valeur @code{(os_name, os_version, os_arch)}. Les valeurs indéterminables ont la valeur des paramètres par défaut (valeur de @code{'@w{'}} par défaut).


Deprecated since version 3.13, will be removed in version 3.15: It was largely untested, had a confusing API,
and was only useful for Jython support.

@end deffn

@node Plateforme Windows,macOS Platform,Plateforme Java,platform --- Access to underlying platform's identifying data
@anchor{library/platform windows-platform}@anchor{2cc8}
@subsubsection Plateforme Windows


@geindex win32_ver() (dans le module platform)
@anchor{library/platform platform win32_ver}@anchor{18eb}
@deffn {Fonction} platform.win32_ver (release='@w{'}, version='@w{'}, csd='@w{'}, ptype='@w{'})

Get additional version information from the Windows Registry and return a tuple
@code{(release, version, csd, ptype)} referring to OS release, version number,
CSD level (service pack) and OS type (multi/single processor). Values which
cannot be determined are set to the defaults given as parameters (which all
default to an empty string).

As a hint: `ptype' is @code{'Uniprocessor Free'} on single processor NT machines
and @code{'Multiprocessor Free'} on multi processor machines. The @code{'Free'} refers
to the OS version being free of debugging code. It could also state @code{'Checked'}
which means the OS version uses debugging code, i.e. code that checks arguments,
ranges, etc.
@end deffn

@geindex win32_edition() (dans le module platform)
@anchor{library/platform platform win32_edition}@anchor{2cc9}
@deffn {Fonction} platform.win32_edition ()

Returns a string representing the current Windows edition, or @code{None} if the
value cannot be determined.  Possible values include but are not limited to
@code{'Enterprise'}, @code{'IoTUAP'}, @code{'ServerStandard'}, and @code{'nanoserver'}.


Ajouté dans la version 3.8.

@end deffn

@geindex win32_is_iot() (dans le module platform)
@anchor{library/platform platform win32_is_iot}@anchor{2cca}
@deffn {Fonction} platform.win32_is_iot ()

Renvoie @code{True} si l'édition de Windows renvoyée par la fonction @ref{2cc9,,win32_edition()} est reconnue comme une édition IoT.


Ajouté dans la version 3.8.

@end deffn

@node macOS Platform,iOS Platform,Plateforme Windows,platform --- Access to underlying platform's identifying data
@anchor{library/platform macos-platform}@anchor{2ccb}
@subsubsection macOS Platform


@geindex mac_ver() (dans le module platform)
@anchor{library/platform platform mac_ver}@anchor{19c2}
@deffn {Fonction} platform.mac_ver (release='@w{'}, versioninfo=('@w{'}, '@w{'}, '@w{'}), machine='@w{'})

Get macOS version information and return it as tuple @code{(release, versioninfo,
machine)} with `versioninfo' being a tuple @code{(version, dev_stage,
non_release_version)}.

Les entrées qui ne peuvent pas être identifiées auront la valeur @code{'@w{'}}. Les membres du `n'-uplet sont tous des chaînes de caractères.
@end deffn

@node iOS Platform,Plateformes Unix,macOS Platform,platform --- Access to underlying platform's identifying data
@anchor{library/platform ios-platform}@anchor{2ccc}
@subsubsection iOS Platform


@geindex ios_ver() (dans le module platform)
@anchor{library/platform platform ios_ver}@anchor{1de7}
@deffn {Fonction} platform.ios_ver (system='@w{'}, release='@w{'}, model='@w{'}, is_simulator=False)

Get iOS version information and return it as a
@ref{1c5,,namedtuple()} with the following attributes:


@itemize *

@item 
@code{system} is the OS name; either @code{'iOS'} or @code{'iPadOS'}.

@item 
@code{release} is the iOS version number as a string (e.g., @code{'17.2'}).

@item 
@code{model} is the device model identifier; this will be a string like
@code{'iPhone13,2'} for a physical device, or @code{'iPhone'} on a simulator.

@item 
@code{is_simulator} is a boolean describing if the app is running on a
simulator or a physical device.
@end itemize

Entries which cannot be determined are set to the defaults given as
parameters.
@end deffn

@node Plateformes Unix,Linux Platforms,iOS Platform,platform --- Access to underlying platform's identifying data
@anchor{library/platform unix-platforms}@anchor{2ccd}
@subsubsection Plateformes Unix


@geindex libc_ver() (dans le module platform)
@anchor{library/platform platform libc_ver}@anchor{19bf}
@deffn {Fonction} platform.libc_ver (executable=sys.executable, lib='@w{'}, version='@w{'}, chunksize=16384)

Tente d'identifier la version de la bibliothèque standard C à laquelle le fichier exécutable (par défaut l'interpréteur Python) est lié. Renvoie une paire de chaînes de caractères @code{(lib, version)}. Les valeurs passées en paramètre seront retournées si la recherche échoue.

Prenez note que cette fonction a une connaissance profonde des méthodes utilisées par les versions de la bibliothèque standard C pour ajouter des symboles au fichier exécutable. Elle n'est probablement utilisable qu'avec des exécutables compilés avec @code{gcc}.

Le fichier est lu en blocs de `chunksize' octets.
@end deffn

@node Linux Platforms,Android Platform,Plateformes Unix,platform --- Access to underlying platform's identifying data
@anchor{library/platform linux-platforms}@anchor{2cce}
@subsubsection Linux Platforms


@geindex freedesktop_os_release() (dans le module platform)
@anchor{library/platform platform freedesktop_os_release}@anchor{810}
@deffn {Fonction} platform.freedesktop_os_release ()

Get operating system identification from @code{os-release} file and return
it as a dict. The @code{os-release} file is a freedesktop.org standard@footnote{https://www.freedesktop.org/software/systemd/man/os-release.html} and
is available in most Linux distributions. A noticeable exception is
Android and Android-based distributions.

Raises @ref{40d,,OSError} or subclass when neither @code{/etc/os-release} nor
@code{/usr/lib/os-release} can be read.

On success, the function returns a dictionary where keys and values are
strings. Values have their special characters like @code{"} and @code{$}
unquoted. The fields @code{NAME}, @code{ID}, and @code{PRETTY_NAME} are always
defined according to the standard. All other fields are optional. Vendors
may include additional fields.

Note that fields like @code{NAME}, @code{VERSION}, and @code{VARIANT} are strings
suitable for presentation to users. Programs should use fields like
@code{ID}, @code{ID_LIKE}, @code{VERSION_ID}, or @code{VARIANT_ID} to identify
Linux distributions.

Exemple :

@example
def get_like_distro():
    info = platform.freedesktop_os_release()
    ids = [info["ID"]]
    if "ID_LIKE" in info:
        # ids are space separated and ordered by precedence
        ids.extend(info["ID_LIKE"].split())
    return ids
@end example


Ajouté dans la version 3.10.

@end deffn

@node Android Platform,,Linux Platforms,platform --- Access to underlying platform's identifying data
@anchor{library/platform android-platform}@anchor{2ccf}
@subsubsection Android Platform


@geindex android_ver() (dans le module platform)
@anchor{library/platform platform android_ver}@anchor{15d5}
@deffn {Fonction} platform.android_ver (release='@w{'}, api_level=0, manufacturer='@w{'}, model='@w{'}, device='@w{'}, is_emulator=False)

Get Android device information. Returns a @ref{1c5,,namedtuple()}
with the following attributes. Values which cannot be determined are set to
the defaults given as parameters.


@itemize *

@item 
@code{release} - Android version, as a string (e.g. @code{"14"}).

@item 
@code{api_level} - API level of the running device, as an integer (e.g. @code{34}
for Android 14). To get the API level which Python was built against, see
@ref{b78,,sys.getandroidapilevel()}.

@item 
@code{manufacturer} - Manufacturer name@footnote{https://developer.android.com/reference/android/os/Build#MANUFACTURER}.

@item 
@code{model} - Model name@footnote{https://developer.android.com/reference/android/os/Build#MODEL} –
typically the marketing name or model number.

@item 
@code{device} - Device name@footnote{https://developer.android.com/reference/android/os/Build#DEVICE} –
typically the model number or a codename.

@item 
@code{is_emulator} - @code{True} if the device is an emulator; @code{False} if it's
a physical device.
@end itemize

Google maintains a list of known model and device names@footnote{https://storage.googleapis.com/play_public/supported_devices.html}.


Ajouté dans la version 3.13.

@end deffn

@node errno --- Standard errno system symbols,ctypes --- A foreign function library for Python,platform --- Access to underlying platform's identifying data,Services génériques du système d'exploitation
@anchor{library/errno doc}@anchor{2cd0}@anchor{library/errno errno-standard-errno-system-symbols}@anchor{2cd1}@anchor{library/errno module-errno}@anchor{56}
@subsection @code{errno} --- Standard errno system symbols


@geindex module; errno


__________________________________________________________________


This module makes available standard @code{errno} system symbols. The value of each
symbol is the corresponding integer value. The names and descriptions are
borrowed from @code{linux/include/errno.h}, which should be
all-inclusive.

@geindex errorcode (dans le module errno)
@anchor{library/errno errno errorcode}@anchor{2cd2}
@deffn {Données} errno.errorcode

Dictionnaire associant la valeur `errno' au nom de chaîne dans le système sous-jacent. Par exemple, @code{errno.errorcode[errno.EPERM]} correspond à @code{'EPERM'}.
@end deffn

Pour traduire un code d'erreur en message d'erreur, utilisez @ref{2aac,,os.strerror()}.

De la liste suivante, les symboles qui ne sont pas utilisés dans la plateforme actuelle ne sont pas définis par le module. La liste spécifique des symboles définis est disponible comme @code{errno.errorcode.keys()}. Les symboles disponibles font partie de cette liste :

@geindex EPERM (dans le module errno)
@anchor{library/errno errno EPERM}@anchor{175a}
@deffn {Données} errno.EPERM

Operation not permitted. This error is mapped to the exception
@ref{d30,,PermissionError}.
@end deffn

@geindex ENOENT (dans le module errno)
@anchor{library/errno errno ENOENT}@anchor{2231}
@deffn {Données} errno.ENOENT

No such file or directory. This error is mapped to the exception
@ref{eae,,FileNotFoundError}.
@end deffn

@geindex ESRCH (dans le module errno)
@anchor{library/errno errno ESRCH}@anchor{2235}
@deffn {Données} errno.ESRCH

No such process. This error is mapped to the exception
@ref{1044,,ProcessLookupError}.
@end deffn

@geindex EINTR (dans le module errno)
@anchor{library/errno errno EINTR}@anchor{d74}
@deffn {Données} errno.EINTR

Interrupted system call. This error is mapped to the exception
@ref{d75,,InterruptedError}.
@end deffn

@geindex EIO (dans le module errno)
@anchor{library/errno errno EIO}@anchor{2cd3}
@deffn {Données} errno.EIO

Erreur d'entrée-sortie
@end deffn

@geindex ENXIO (dans le module errno)
@anchor{library/errno errno ENXIO}@anchor{2cd4}
@deffn {Données} errno.ENXIO

Dispositif ou adresse inexistant
@end deffn

@geindex E2BIG (dans le module errno)
@anchor{library/errno errno E2BIG}@anchor{2cd5}
@deffn {Données} errno.E2BIG

Liste d'arguments trop longue
@end deffn

@geindex ENOEXEC (dans le module errno)
@anchor{library/errno errno ENOEXEC}@anchor{2cd6}
@deffn {Données} errno.ENOEXEC

Erreur de format d'exécution
@end deffn

@geindex EBADF (dans le module errno)
@anchor{library/errno errno EBADF}@anchor{948}
@deffn {Données} errno.EBADF

Mauvais descripteur de fichier
@end deffn

@geindex ECHILD (dans le module errno)
@anchor{library/errno errno ECHILD}@anchor{222a}
@deffn {Données} errno.ECHILD

No child processes. This error is mapped to the exception
@ref{1041,,ChildProcessError}.
@end deffn

@geindex EAGAIN (dans le module errno)
@anchor{library/errno errno EAGAIN}@anchor{2225}
@deffn {Données} errno.EAGAIN

Try again. This error is mapped to the exception @ref{1040,,BlockingIOError}.
@end deffn

@geindex ENOMEM (dans le module errno)
@anchor{library/errno errno ENOMEM}@anchor{2cd7}
@deffn {Données} errno.ENOMEM

Mémoire insuffisante
@end deffn

@geindex EACCES (dans le module errno)
@anchor{library/errno errno EACCES}@anchor{2234}
@deffn {Données} errno.EACCES

Permission denied.  This error is mapped to the exception
@ref{d30,,PermissionError}.
@end deffn

@geindex EFAULT (dans le module errno)
@anchor{library/errno errno EFAULT}@anchor{2cd8}
@deffn {Données} errno.EFAULT

Mauvaise adresse
@end deffn

@geindex ENOTBLK (dans le module errno)
@anchor{library/errno errno ENOTBLK}@anchor{2cd9}
@deffn {Données} errno.ENOTBLK

Dispositif de bloc requis
@end deffn

@geindex EBUSY (dans le module errno)
@anchor{library/errno errno EBUSY}@anchor{2cda}
@deffn {Données} errno.EBUSY

Dispositif ou ressource occupé
@end deffn

@geindex EEXIST (dans le module errno)
@anchor{library/errno errno EEXIST}@anchor{2230}
@deffn {Données} errno.EEXIST

File exists. This error is mapped to the exception
@ref{1009,,FileExistsError}.
@end deffn

@geindex EXDEV (dans le module errno)
@anchor{library/errno errno EXDEV}@anchor{2ac3}
@deffn {Données} errno.EXDEV

Lien inapproprié
@end deffn

@geindex ENODEV (dans le module errno)
@anchor{library/errno errno ENODEV}@anchor{2cdb}
@deffn {Données} errno.ENODEV

Dispositif inexistant
@end deffn

@geindex ENOTDIR (dans le module errno)
@anchor{library/errno errno ENOTDIR}@anchor{2233}
@deffn {Données} errno.ENOTDIR

Not a directory. This error is mapped to the exception
@ref{1043,,NotADirectoryError}.
@end deffn

@geindex EISDIR (dans le module errno)
@anchor{library/errno errno EISDIR}@anchor{2232}
@deffn {Données} errno.EISDIR

Is a directory. This error is mapped to the exception
@ref{1042,,IsADirectoryError}.
@end deffn

@geindex EINVAL (dans le module errno)
@anchor{library/errno errno EINVAL}@anchor{197d}
@deffn {Données} errno.EINVAL

Argument invalide
@end deffn

@geindex ENFILE (dans le module errno)
@anchor{library/errno errno ENFILE}@anchor{2cdc}
@deffn {Données} errno.ENFILE

Plus de descripteur de fichier disponible
@end deffn

@geindex EMFILE (dans le module errno)
@anchor{library/errno errno EMFILE}@anchor{2cdd}
@deffn {Données} errno.EMFILE

Trop de fichiers ouverts
@end deffn

@geindex ENOTTY (dans le module errno)
@anchor{library/errno errno ENOTTY}@anchor{2cde}
@deffn {Données} errno.ENOTTY

Opération de contrôle d'entrée-sortie invalide
@end deffn

@geindex ETXTBSY (dans le module errno)
@anchor{library/errno errno ETXTBSY}@anchor{2cdf}
@deffn {Données} errno.ETXTBSY

Fichier texte occupé
@end deffn

@geindex EFBIG (dans le module errno)
@anchor{library/errno errno EFBIG}@anchor{2ce0}
@deffn {Données} errno.EFBIG

Fichier trop grand
@end deffn

@geindex ENOSPC (dans le module errno)
@anchor{library/errno errno ENOSPC}@anchor{2ce1}
@deffn {Données} errno.ENOSPC

Plus de place sur le dispositif
@end deffn

@geindex ESPIPE (dans le module errno)
@anchor{library/errno errno ESPIPE}@anchor{2ce2}
@deffn {Données} errno.ESPIPE

Recherche invalide
@end deffn

@geindex EROFS (dans le module errno)
@anchor{library/errno errno EROFS}@anchor{2ce3}
@deffn {Données} errno.EROFS

Système de fichiers en lecture seule
@end deffn

@geindex EMLINK (dans le module errno)
@anchor{library/errno errno EMLINK}@anchor{2ce4}
@deffn {Données} errno.EMLINK

Trop de liens symboliques
@end deffn

@geindex EPIPE (dans le module errno)
@anchor{library/errno errno EPIPE}@anchor{222b}
@deffn {Données} errno.EPIPE

Broken pipe. This error is mapped to the exception
@ref{1045,,BrokenPipeError}.
@end deffn

@geindex EDOM (dans le module errno)
@anchor{library/errno errno EDOM}@anchor{2ce5}
@deffn {Données} errno.EDOM

Argument mathématique hors du domaine de définition de la fonction
@end deffn

@geindex ERANGE (dans le module errno)
@anchor{library/errno errno ERANGE}@anchor{2ce6}
@deffn {Données} errno.ERANGE

Résultat mathématique non représentable
@end deffn

@geindex EDEADLK (dans le module errno)
@anchor{library/errno errno EDEADLK}@anchor{2ce7}
@deffn {Données} errno.EDEADLK

Un interblocage se produirait sur cette ressource
@end deffn

@geindex ENAMETOOLONG (dans le module errno)
@anchor{library/errno errno ENAMETOOLONG}@anchor{2ce8}
@deffn {Données} errno.ENAMETOOLONG

Nom de fichier trop long
@end deffn

@geindex ENOLCK (dans le module errno)
@anchor{library/errno errno ENOLCK}@anchor{2ce9}
@deffn {Données} errno.ENOLCK

Plus de verrou de fichier disponible
@end deffn

@geindex ENOSYS (dans le module errno)
@anchor{library/errno errno ENOSYS}@anchor{175b}
@deffn {Données} errno.ENOSYS

Fonction non implémentée
@end deffn

@geindex ENOTEMPTY (dans le module errno)
@anchor{library/errno errno ENOTEMPTY}@anchor{2cea}
@deffn {Données} errno.ENOTEMPTY

Dossier non vide
@end deffn

@geindex ELOOP (dans le module errno)
@anchor{library/errno errno ELOOP}@anchor{2ceb}
@deffn {Données} errno.ELOOP

Trop de liens symboliques trouvés
@end deffn

@geindex EWOULDBLOCK (dans le module errno)
@anchor{library/errno errno EWOULDBLOCK}@anchor{2227}
@deffn {Données} errno.EWOULDBLOCK

Operation would block. This error is mapped to the exception
@ref{1040,,BlockingIOError}.
@end deffn

@geindex ENOMSG (dans le module errno)
@anchor{library/errno errno ENOMSG}@anchor{2cec}
@deffn {Données} errno.ENOMSG

Pas de message du type voulu
@end deffn

@geindex EIDRM (dans le module errno)
@anchor{library/errno errno EIDRM}@anchor{2ced}
@deffn {Données} errno.EIDRM

Identifiant supprimé
@end deffn

@geindex ECHRNG (dans le module errno)
@anchor{library/errno errno ECHRNG}@anchor{2cee}
@deffn {Données} errno.ECHRNG

Le numéro de canal est hors des limites
@end deffn

@geindex EL2NSYNC (dans le module errno)
@anchor{library/errno errno EL2NSYNC}@anchor{2cef}
@deffn {Données} errno.EL2NSYNC

Le niveau 2 n'est pas synchronisé
@end deffn

@geindex EL3HLT (dans le module errno)
@anchor{library/errno errno EL3HLT}@anchor{2cf0}
@deffn {Données} errno.EL3HLT

Niveau 3 stoppé
@end deffn

@geindex EL3RST (dans le module errno)
@anchor{library/errno errno EL3RST}@anchor{2cf1}
@deffn {Données} errno.EL3RST

Niveau 3 réinitialisé
@end deffn

@geindex ELNRNG (dans le module errno)
@anchor{library/errno errno ELNRNG}@anchor{2cf2}
@deffn {Données} errno.ELNRNG

Le numéro du lien est hors des limites
@end deffn

@geindex EUNATCH (dans le module errno)
@anchor{library/errno errno EUNATCH}@anchor{2cf3}
@deffn {Données} errno.EUNATCH

Le pilote de protocole n'est pas attaché
@end deffn

@geindex ENOCSI (dans le module errno)
@anchor{library/errno errno ENOCSI}@anchor{2cf4}
@deffn {Données} errno.ENOCSI

Pas de structure `CSI' disponible
@end deffn

@geindex EL2HLT (dans le module errno)
@anchor{library/errno errno EL2HLT}@anchor{2cf5}
@deffn {Données} errno.EL2HLT

Niveau 2 stoppé
@end deffn

@geindex EBADE (dans le module errno)
@anchor{library/errno errno EBADE}@anchor{2cf6}
@deffn {Données} errno.EBADE

Échange invalide
@end deffn

@geindex EBADR (dans le module errno)
@anchor{library/errno errno EBADR}@anchor{2cf7}
@deffn {Données} errno.EBADR

Descripteur de requête invalide
@end deffn

@geindex EXFULL (dans le module errno)
@anchor{library/errno errno EXFULL}@anchor{2cf8}
@deffn {Données} errno.EXFULL

Échange complet
@end deffn

@geindex ENOANO (dans le module errno)
@anchor{library/errno errno ENOANO}@anchor{2cf9}
@deffn {Données} errno.ENOANO

Pas de `anode'
@end deffn

@geindex EBADRQC (dans le module errno)
@anchor{library/errno errno EBADRQC}@anchor{2cfa}
@deffn {Données} errno.EBADRQC

Code de requête invalide
@end deffn

@geindex EBADSLT (dans le module errno)
@anchor{library/errno errno EBADSLT}@anchor{2cfb}
@deffn {Données} errno.EBADSLT

`Slot' invalide
@end deffn

@geindex EDEADLOCK (dans le module errno)
@anchor{library/errno errno EDEADLOCK}@anchor{2cfc}
@deffn {Données} errno.EDEADLOCK

Interblocage lors du verrouillage de fichier
@end deffn

@geindex EBFONT (dans le module errno)
@anchor{library/errno errno EBFONT}@anchor{2cfd}
@deffn {Données} errno.EBFONT

Mauvais format de fichier de police
@end deffn

@geindex ENOSTR (dans le module errno)
@anchor{library/errno errno ENOSTR}@anchor{2cfe}
@deffn {Données} errno.ENOSTR

Le périphérique n'est pas un flux
@end deffn

@geindex ENODATA (dans le module errno)
@anchor{library/errno errno ENODATA}@anchor{2cff}
@deffn {Données} errno.ENODATA

Pas de donnée disponible
@end deffn

@geindex ETIME (dans le module errno)
@anchor{library/errno errno ETIME}@anchor{2d00}
@deffn {Données} errno.ETIME

Délai maximal atteint
@end deffn

@geindex ENOSR (dans le module errno)
@anchor{library/errno errno ENOSR}@anchor{2d01}
@deffn {Données} errno.ENOSR

Pas assez de ressources de type flux
@end deffn

@geindex ENONET (dans le module errno)
@anchor{library/errno errno ENONET}@anchor{2d02}
@deffn {Données} errno.ENONET

Machine hors réseau
@end deffn

@geindex ENOPKG (dans le module errno)
@anchor{library/errno errno ENOPKG}@anchor{2d03}
@deffn {Données} errno.ENOPKG

Paquet non installé
@end deffn

@geindex EREMOTE (dans le module errno)
@anchor{library/errno errno EREMOTE}@anchor{2d04}
@deffn {Données} errno.EREMOTE

L'objet est distant
@end deffn

@geindex ENOLINK (dans le module errno)
@anchor{library/errno errno ENOLINK}@anchor{2d05}
@deffn {Données} errno.ENOLINK

Lien coupé
@end deffn

@geindex EADV (dans le module errno)
@anchor{library/errno errno EADV}@anchor{2d06}
@deffn {Données} errno.EADV

Erreur d'annonce
@end deffn

@geindex ESRMNT (dans le module errno)
@anchor{library/errno errno ESRMNT}@anchor{2d07}
@deffn {Données} errno.ESRMNT

Erreur `Srmount'
@end deffn

@geindex ECOMM (dans le module errno)
@anchor{library/errno errno ECOMM}@anchor{2d08}
@deffn {Données} errno.ECOMM

Erreur de communication lors de l'envoi
@end deffn

@geindex EPROTO (dans le module errno)
@anchor{library/errno errno EPROTO}@anchor{2d09}
@deffn {Données} errno.EPROTO

Erreur de protocole
@end deffn

@geindex EMULTIHOP (dans le module errno)
@anchor{library/errno errno EMULTIHOP}@anchor{2d0a}
@deffn {Données} errno.EMULTIHOP

Transfert à sauts multiples essayé
@end deffn

@geindex EDOTDOT (dans le module errno)
@anchor{library/errno errno EDOTDOT}@anchor{2d0b}
@deffn {Données} errno.EDOTDOT

erreur spécifique `RFS'
@end deffn

@geindex EBADMSG (dans le module errno)
@anchor{library/errno errno EBADMSG}@anchor{2d0c}
@deffn {Données} errno.EBADMSG

Pas un message de données
@end deffn

@geindex EOVERFLOW (dans le module errno)
@anchor{library/errno errno EOVERFLOW}@anchor{2d0d}
@deffn {Données} errno.EOVERFLOW

Valeur trop grande pour être stockée dans ce type de donnée
@end deffn

@geindex ENOTUNIQ (dans le module errno)
@anchor{library/errno errno ENOTUNIQ}@anchor{2d0e}
@deffn {Données} errno.ENOTUNIQ

Nom non-unique dans le réseau
@end deffn

@geindex EBADFD (dans le module errno)
@anchor{library/errno errno EBADFD}@anchor{2d0f}
@deffn {Données} errno.EBADFD

Descripteur de fichier en mauvais état
@end deffn

@geindex EREMCHG (dans le module errno)
@anchor{library/errno errno EREMCHG}@anchor{2d10}
@deffn {Données} errno.EREMCHG

Adresse distante changée
@end deffn

@geindex ELIBACC (dans le module errno)
@anchor{library/errno errno ELIBACC}@anchor{2d11}
@deffn {Données} errno.ELIBACC

Accès impossible à une bibliothèque partagée nécessaire
@end deffn

@geindex ELIBBAD (dans le module errno)
@anchor{library/errno errno ELIBBAD}@anchor{2d12}
@deffn {Données} errno.ELIBBAD

Accès à une bibliothèque partagée corrompue
@end deffn

@geindex ELIBSCN (dans le module errno)
@anchor{library/errno errno ELIBSCN}@anchor{2d13}
@deffn {Données} errno.ELIBSCN

Section `.lib' de `a.out' corrompue
@end deffn

@geindex ELIBMAX (dans le module errno)
@anchor{library/errno errno ELIBMAX}@anchor{2d14}
@deffn {Données} errno.ELIBMAX

Tentative de liaison entre trop de bibliothèques partagées
@end deffn

@geindex ELIBEXEC (dans le module errno)
@anchor{library/errno errno ELIBEXEC}@anchor{2d15}
@deffn {Données} errno.ELIBEXEC

Impossible d'exécuter directement une bibliothèque partagée
@end deffn

@geindex EILSEQ (dans le module errno)
@anchor{library/errno errno EILSEQ}@anchor{2d16}
@deffn {Données} errno.EILSEQ

Séquence de `bytes' illégale
@end deffn

@geindex ERESTART (dans le module errno)
@anchor{library/errno errno ERESTART}@anchor{2d17}
@deffn {Données} errno.ERESTART

Appel système interrompu qui devrait être relancé
@end deffn

@geindex ESTRPIPE (dans le module errno)
@anchor{library/errno errno ESTRPIPE}@anchor{2d18}
@deffn {Données} errno.ESTRPIPE

Erreur d’enchaînement de flux
@end deffn

@geindex EUSERS (dans le module errno)
@anchor{library/errno errno EUSERS}@anchor{2d19}
@deffn {Données} errno.EUSERS

Trop d'utilisateurs
@end deffn

@geindex ENOTSOCK (dans le module errno)
@anchor{library/errno errno ENOTSOCK}@anchor{2d1a}
@deffn {Données} errno.ENOTSOCK

Opération d'interface de connexion alors que ce n'est pas une interface de connexion
@end deffn

@geindex EDESTADDRREQ (dans le module errno)
@anchor{library/errno errno EDESTADDRREQ}@anchor{2d1b}
@deffn {Données} errno.EDESTADDRREQ

Adresse de destination obligatoire
@end deffn

@geindex EMSGSIZE (dans le module errno)
@anchor{library/errno errno EMSGSIZE}@anchor{2d1c}
@deffn {Données} errno.EMSGSIZE

Message trop long
@end deffn

@geindex EPROTOTYPE (dans le module errno)
@anchor{library/errno errno EPROTOTYPE}@anchor{2d1d}
@deffn {Données} errno.EPROTOTYPE

Mauvais type de protocole pour ce connecteur
@end deffn

@geindex ENOPROTOOPT (dans le module errno)
@anchor{library/errno errno ENOPROTOOPT}@anchor{2d1e}
@deffn {Données} errno.ENOPROTOOPT

Protocole pas disponible
@end deffn

@geindex EPROTONOSUPPORT (dans le module errno)
@anchor{library/errno errno EPROTONOSUPPORT}@anchor{2d1f}
@deffn {Données} errno.EPROTONOSUPPORT

Protocole non géré
@end deffn

@geindex ESOCKTNOSUPPORT (dans le module errno)
@anchor{library/errno errno ESOCKTNOSUPPORT}@anchor{2d20}
@deffn {Données} errno.ESOCKTNOSUPPORT

Type de connecteur non géré
@end deffn

@geindex EOPNOTSUPP (dans le module errno)
@anchor{library/errno errno EOPNOTSUPP}@anchor{2d21}
@deffn {Données} errno.EOPNOTSUPP

Opération non gérée par cette fin de lien
@end deffn

@geindex ENOTSUP (dans le module errno)
@anchor{library/errno errno ENOTSUP}@anchor{2d22}
@deffn {Données} errno.ENOTSUP

Operation not supported


Ajouté dans la version 3.2.

@end deffn

@geindex EPFNOSUPPORT (dans le module errno)
@anchor{library/errno errno EPFNOSUPPORT}@anchor{2d23}
@deffn {Données} errno.EPFNOSUPPORT

Famille de protocole non gérée
@end deffn

@geindex EAFNOSUPPORT (dans le module errno)
@anchor{library/errno errno EAFNOSUPPORT}@anchor{2d24}
@deffn {Données} errno.EAFNOSUPPORT

Famille d'adresses non gérée par ce protocole
@end deffn

@geindex EADDRINUSE (dans le module errno)
@anchor{library/errno errno EADDRINUSE}@anchor{2d25}
@deffn {Données} errno.EADDRINUSE

Adresse déjà utilisée
@end deffn

@geindex EADDRNOTAVAIL (dans le module errno)
@anchor{library/errno errno EADDRNOTAVAIL}@anchor{2d26}
@deffn {Données} errno.EADDRNOTAVAIL

Impossible d'assigner l'adresse demandée
@end deffn

@geindex ENETDOWN (dans le module errno)
@anchor{library/errno errno ENETDOWN}@anchor{2d27}
@deffn {Données} errno.ENETDOWN

Le réseau est désactivé
@end deffn

@geindex ENETUNREACH (dans le module errno)
@anchor{library/errno errno ENETUNREACH}@anchor{1995}
@deffn {Données} errno.ENETUNREACH

Réseau inaccessible
@end deffn

@geindex ENETRESET (dans le module errno)
@anchor{library/errno errno ENETRESET}@anchor{2d28}
@deffn {Données} errno.ENETRESET

Connexion annulée par le réseau
@end deffn

@geindex ECONNABORTED (dans le module errno)
@anchor{library/errno errno ECONNABORTED}@anchor{222d}
@deffn {Données} errno.ECONNABORTED

Software caused connection abort. This error is mapped to the
exception @ref{1046,,ConnectionAbortedError}.
@end deffn

@geindex ECONNRESET (dans le module errno)
@anchor{library/errno errno ECONNRESET}@anchor{222f}
@deffn {Données} errno.ECONNRESET

Connection reset by peer. This error is mapped to the exception
@ref{1048,,ConnectionResetError}.
@end deffn

@geindex ENOBUFS (dans le module errno)
@anchor{library/errno errno ENOBUFS}@anchor{1776}
@deffn {Données} errno.ENOBUFS

Plus d'espace tampon disponible
@end deffn

@geindex EISCONN (dans le module errno)
@anchor{library/errno errno EISCONN}@anchor{2d29}
@deffn {Données} errno.EISCONN

L'interface de connexion est déjà connectée
@end deffn

@geindex ENOTCONN (dans le module errno)
@anchor{library/errno errno ENOTCONN}@anchor{2d2a}
@deffn {Données} errno.ENOTCONN

L'interface de connexion n'est pas connectée
@end deffn

@geindex ESHUTDOWN (dans le module errno)
@anchor{library/errno errno ESHUTDOWN}@anchor{222c}
@deffn {Données} errno.ESHUTDOWN

Cannot send after transport endpoint shutdown. This error is mapped
to the exception @ref{1045,,BrokenPipeError}.
@end deffn

@geindex ETOOMANYREFS (dans le module errno)
@anchor{library/errno errno ETOOMANYREFS}@anchor{2d2b}
@deffn {Données} errno.ETOOMANYREFS

Trop de descripteurs : impossible d'effectuer la liaison
@end deffn

@geindex ETIMEDOUT (dans le module errno)
@anchor{library/errno errno ETIMEDOUT}@anchor{2236}
@deffn {Données} errno.ETIMEDOUT

Connection timed out. This error is mapped to the exception
@ref{81f,,TimeoutError}.
@end deffn

@geindex ECONNREFUSED (dans le module errno)
@anchor{library/errno errno ECONNREFUSED}@anchor{222e}
@deffn {Données} errno.ECONNREFUSED

Connection refused. This error is mapped to the exception
@ref{1047,,ConnectionRefusedError}.
@end deffn

@geindex EHOSTDOWN (dans le module errno)
@anchor{library/errno errno EHOSTDOWN}@anchor{2d2c}
@deffn {Données} errno.EHOSTDOWN

Hôte éteint
@end deffn

@geindex EHOSTUNREACH (dans le module errno)
@anchor{library/errno errno EHOSTUNREACH}@anchor{2d2d}
@deffn {Données} errno.EHOSTUNREACH

Pas de route vers l'hôte
@end deffn

@geindex EALREADY (dans le module errno)
@anchor{library/errno errno EALREADY}@anchor{2226}
@deffn {Données} errno.EALREADY

Operation already in progress. This error is mapped to the
exception @ref{1040,,BlockingIOError}.
@end deffn

@geindex EINPROGRESS (dans le module errno)
@anchor{library/errno errno EINPROGRESS}@anchor{2228}
@deffn {Données} errno.EINPROGRESS

Operation now in progress. This error is mapped to the exception
@ref{1040,,BlockingIOError}.
@end deffn

@geindex ESTALE (dans le module errno)
@anchor{library/errno errno ESTALE}@anchor{2d2e}
@deffn {Données} errno.ESTALE

Descripteur de fichier NFS corrompu
@end deffn

@geindex EUCLEAN (dans le module errno)
@anchor{library/errno errno EUCLEAN}@anchor{2d2f}
@deffn {Données} errno.EUCLEAN

La structure a besoin d'être nettoyée
@end deffn

@geindex ENOTNAM (dans le module errno)
@anchor{library/errno errno ENOTNAM}@anchor{2d30}
@deffn {Données} errno.ENOTNAM

N'est pas un fichier nommé du type `XENIX'
@end deffn

@geindex ENAVAIL (dans le module errno)
@anchor{library/errno errno ENAVAIL}@anchor{2d31}
@deffn {Données} errno.ENAVAIL

Pas de sémaphore `XENIX' disponible
@end deffn

@geindex EISNAM (dans le module errno)
@anchor{library/errno errno EISNAM}@anchor{2d32}
@deffn {Données} errno.EISNAM

Est un fichier nommé
@end deffn

@geindex EREMOTEIO (dans le module errno)
@anchor{library/errno errno EREMOTEIO}@anchor{2d33}
@deffn {Données} errno.EREMOTEIO

Erreur d'entrées-sorties distante
@end deffn

@geindex EDQUOT (dans le module errno)
@anchor{library/errno errno EDQUOT}@anchor{2d34}
@deffn {Données} errno.EDQUOT

Quota dépassé
@end deffn

@geindex EQFULL (dans le module errno)
@anchor{library/errno errno EQFULL}@anchor{2d35}
@deffn {Données} errno.EQFULL

Interface output queue is full


Ajouté dans la version 3.11.

@end deffn

@geindex ENOTCAPABLE (dans le module errno)
@anchor{library/errno errno ENOTCAPABLE}@anchor{174d}
@deffn {Données} errno.ENOTCAPABLE

Capabilities insufficient. This error is mapped to the exception
@ref{d30,,PermissionError}.

@ref{1ce0,,Availability}: WASI, FreeBSD


Ajouté dans la version 3.11.1.

@end deffn

@geindex ECANCELED (dans le module errno)
@anchor{library/errno errno ECANCELED}@anchor{2d36}
@deffn {Données} errno.ECANCELED

Operation canceled


Ajouté dans la version 3.2.

@end deffn

@geindex EOWNERDEAD (dans le module errno)
@anchor{library/errno errno EOWNERDEAD}@anchor{2d37}
@deffn {Données} errno.EOWNERDEAD

Owner died


Ajouté dans la version 3.2.

@end deffn

@geindex ENOTRECOVERABLE (dans le module errno)
@anchor{library/errno errno ENOTRECOVERABLE}@anchor{2d38}
@deffn {Données} errno.ENOTRECOVERABLE

State not recoverable


Ajouté dans la version 3.2.

@end deffn

@node ctypes --- A foreign function library for Python,,errno --- Standard errno system symbols,Services génériques du système d'exploitation
@anchor{library/ctypes doc}@anchor{2d39}@anchor{library/ctypes ctypes-a-foreign-function-library-for-python}@anchor{2d3a}@anchor{library/ctypes module-ctypes}@anchor{2a}
@subsection @code{ctypes} --- A foreign function library for Python


@geindex module; ctypes

`Source code:' Lib/ctypes@footnote{https://github.com/python/cpython/tree/3.13/Lib/ctypes}


__________________________________________________________________


@ref{2a,,ctypes} est une bibliothèque d'appel à des fonctions externes en python. Elle fournit des types de données compatibles avec le langage C et permet d'appeler des fonctions depuis des DLL ou des bibliothèques partagées, rendant ainsi possible l'interfaçage de ces bibliothèques avec du pur code Python.

@menu
* Didacticiel de ctypes:: 
* Référence du module:: 

@end menu

@node Didacticiel de ctypes,Référence du module,,ctypes --- A foreign function library for Python
@anchor{library/ctypes ctypes-ctypes-tutorial}@anchor{2d3b}@anchor{library/ctypes ctypes-tutorial}@anchor{2d3c}
@subsubsection Didacticiel de `ctypes'


Remarque : les exemples de code de ce didacticiel utilisent @ref{3a,,doctest} pour s'assurer de leur propre bon fonctionnement. Vu que certains de ces exemples ont un comportement différent en Linux, Windows ou macOS, ils contiennent des directives `doctest' dans les commentaires.

Remarque : le type @ref{2d3d,,c_int} du module apparaît dans certains de ces exemples. Sur les plates-formes où @code{sizeof(long) == sizeof(int)}, ce type est un alias de @ref{2d3e,,c_long}. Ne soyez donc pas surpris si @ref{2d3e,,c_long} s'affiche là où vous vous attendiez à @ref{2d3d,,c_int} — il s'agit bien du même type.

@menu
* Chargement des DLL:: 
* Accès aux fonctions des DLL chargées:: 
* Appel de fonctions:: 
* Types de données de base:: 
* Appel de fonctions@comma{} suite: Appel de fonctions suite. 
* Calling variadic functions:: 
* Appel de fonctions avec des types de données personnalisés:: 
* Définition du type des arguments nécessaires (prototypes de fonction): Définition du type des arguments nécessaires prototypes de fonction. 
* Types de sortie:: 
* Passage de pointeurs (passage de paramètres par référence): Passage de pointeurs passage de paramètres par référence. 
* Structures et unions:: 
* Alignement et boutisme des structures et des unions:: 
* Champs de bits dans les structures et les unions:: 
* Tableaux:: 
* Pointeurs:: 
* Conversions de type:: 
* Types incomplets:: 
* Fonctions de rappel:: 
* Accès aux variables exportées depuis une DLL:: 
* Pièges:: 
* Types de données à taille flottante:: 

@end menu

@node Chargement des DLL,Accès aux fonctions des DLL chargées,,Didacticiel de ctypes
@anchor{library/ctypes ctypes-loading-dynamic-link-libraries}@anchor{2d3f}@anchor{library/ctypes loading-dynamic-link-libraries}@anchor{2d40}
@subsubsection Chargement des DLL


@ref{2a,,ctypes} fournit l'objet `cdll' pour charger des bibliothèques à liens dynamiques (et les objets `windll' et `oledll' en Windows).

You load libraries by accessing them as attributes of these objects. `cdll'
loads libraries which export functions using the standard @code{cdecl} calling
convention, while `windll' libraries call functions using the @code{stdcall}
calling convention. `oledll' also uses the @code{stdcall} calling convention, and
assumes the functions return a Windows @code{HRESULT} error code. The error
code is used to automatically raise an @ref{40d,,OSError} exception when the
function call fails.


Modifié dans la version 3.3: En Windows, les erreurs levaient auparavant une @ref{103d,,WindowsError}, qui est maintenant un alias de @ref{40d,,OSError}.


Here are some examples for Windows. Note that @code{msvcrt} is the MS standard C
library containing most standard C functions, and uses the @code{cdecl} calling
convention:

@example
>>> from ctypes import *
>>> print(windll.kernel32)  
<WinDLL 'kernel32', handle ... at ...>
>>> print(cdll.msvcrt)      
<CDLL 'msvcrt', handle ... at ...>
>>> libc = cdll.msvcrt      
>>>
@end example

Windows ajoute le suffixe habituel @code{.dll} automatiquement.

@cartouche
@quotation Note 
Accéder à la bibliothèque standard C par @code{cdll.msvcrt} utilise une version obsolète de la bibliothèque qui peut avoir des problèmes de compatibilité avec celle que Python utilise. Si possible, mieux vaut utiliser la fonctionnalité native de Python, ou bien importer et utiliser le module @code{msvcrt}.
@end quotation
@end cartouche

On Linux, it is required to specify the filename `including' the extension to
load a library, so attribute access can not be used to load libraries. Either the
@ref{2d41,,LoadLibrary()} method of the dll loaders should be used,
or you should load the library by creating an instance of CDLL by calling
the constructor:

@example
>>> cdll.LoadLibrary("libc.so.6")  
<CDLL 'libc.so.6', handle ... at ...>
>>> libc = CDLL("libc.so.6")       
>>> libc                           
<CDLL 'libc.so.6', handle ... at ...>
>>>
@end example

@c XXX Add section for macOS.

@node Accès aux fonctions des DLL chargées,Appel de fonctions,Chargement des DLL,Didacticiel de ctypes
@anchor{library/ctypes accessing-functions-from-loaded-dlls}@anchor{2d42}@anchor{library/ctypes ctypes-accessing-functions-from-loaded-dlls}@anchor{2d43}
@subsubsection Accès aux fonctions des DLL chargées


Les fonctions sont alors des attributs des objets DLL :

@example
>>> libc.printf
<_FuncPtr object at 0x...>
>>> print(windll.kernel32.GetModuleHandleA)  
<_FuncPtr object at 0x...>
>>> print(windll.kernel32.MyOwnFunction)     
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "ctypes.py", line 239, in __getattr__
    func = _StdcallFuncPtr(name, self)
AttributeError: function 'MyOwnFunction' not found
>>>
@end example

Note that win32 system dlls like @code{kernel32} and @code{user32} often export ANSI
as well as UNICODE versions of a function. The UNICODE version is exported with
a @code{W} appended to the name, while the ANSI version is exported with an @code{A}
appended to the name. The win32 @code{GetModuleHandle} function, which returns a
`module handle' for a given module name, has the following C prototype, and a
macro is used to expose one of them as @code{GetModuleHandle} depending on whether
UNICODE is defined or not:

@example
/* ANSI version */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE version */
HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
@end example

`windll' n'en choisit pas une par magie, il faut accéder à la bonne en écrivant explicitement @code{GetModuleHandleA} ou @code{GetModuleHandleW} et en les appelant ensuite avec des objets octets ou avec des chaînes de caractères, respectivement.

Les DLL exportent parfois des fonctions dont les noms ne sont pas des identifiants Python valides, comme @code{"??2@@YAPAXI@@Z"}. Dans ce cas, il faut utiliser @ref{bbf,,getattr()} pour accéder à la fonction :

@example
>>> getattr(cdll.msvcrt, "??2@@YAPAXI@@Z")  
<_FuncPtr object at 0x...>
>>>
@end example

Sous Windows, certaines DLL exportent des fonctions à travers un indice plutôt qu'à travers un nom. On accède à une fonction en indiçant l'objet DLL avec son index :

@example
>>> cdll.kernel32[1]  
<_FuncPtr object at 0x...>
>>> cdll.kernel32[0]  
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "ctypes.py", line 310, in __getitem__
    func = _StdcallFuncPtr(name, self)
AttributeError: function ordinal 0 not found
>>>
@end example

@node Appel de fonctions,Types de données de base,Accès aux fonctions des DLL chargées,Didacticiel de ctypes
@anchor{library/ctypes calling-functions}@anchor{2d44}@anchor{library/ctypes ctypes-calling-functions}@anchor{2d45}
@subsubsection Appel de fonctions


You can call these functions like any other Python callable. This example uses
the @code{rand()} function, which takes no arguments and returns a pseudo-random integer:

@example
>>> print(libc.rand())  
1804289383
@end example

On Windows, you can call the @code{GetModuleHandleA()} function, which returns a win32 module
handle (passing @code{None} as single argument to call it with a @code{NULL} pointer):

@example
>>> print(hex(windll.kernel32.GetModuleHandleA(None)))  
0x1d000000
>>>
@end example

Une @ref{1ff,,ValueError} est levée quand on appelle une fonction @code{stdcall} avec la convention d'appel @code{cdecl} et vice-versa :

@example
>>> cdll.kernel32.GetModuleHandleA(None)  
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
>>>

>>> windll.msvcrt.printf(b"spam")  
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
>>>
@end example

Pour déterminer la convention d'appel, il faut consulter l'en-tête C ou la documentation de la fonction à appeler.

En Windows, @ref{2a,,ctypes} tire profit de la gestion structurée des exceptions (`structured exception handling') `win32' pour empêcher les plantages dus à des interruptions, afin de préserver la protection globale (`general protection faults') du système, lorsque des fonctions sont appelées avec un nombre incorrect d'arguments :

@example
>>> windll.kernel32.GetModuleHandleA(32)  
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: exception: access violation reading 0x00000020
>>>
@end example

Cependant, il y a suffisamment de façons de faire planter Python avec @ref{2a,,ctypes}, donc il faut être prudent dans tous les cas. Le module @ref{57,,faulthandler} est pratique pour déboguer les plantages (p. ex. dus à des erreurs de segmentation produites par des appels erronés à la bibliothèque C).

@code{None}, integers, bytes objects and (unicode) strings are the only native
Python objects that can directly be used as parameters in these function calls.
@code{None} is passed as a C @code{NULL} pointer, bytes objects and strings are passed
as pointer to the memory block that contains their data (char* or
wchar_t*).  Python integers are passed as the platform's default C
int type, their value is masked to fit into the C type.

Avant de poursuivre sur l'appel de fonctions avec d'autres types de paramètres, apprenons-en un peu plus sur les types de données de @ref{2a,,ctypes}.

@node Types de données de base,Appel de fonctions suite,Appel de fonctions,Didacticiel de ctypes
@anchor{library/ctypes ctypes-fundamental-data-types}@anchor{2d46}@anchor{library/ctypes fundamental-data-types}@anchor{2d47}
@subsubsection Types de données de base


@ref{2a,,ctypes} définit plusieurs types de donnée de base compatibles avec le C :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Types de `ctypes'

@tab

Type C

@tab

Type Python

@item

@ref{2d48,,c_bool}

@tab

_Bool

@tab

`bool' (1)

@item

@ref{2d49,,c_char}

@tab

char

@tab

objet octet (`bytes') de 1 caractère

@item

@ref{2d4a,,c_wchar}

@tab

@code{wchar_t}

@tab

chaîne de caractères (`string') de longueur 1

@item

@ref{16fe,,c_byte}

@tab

char

@tab

`int'

@item

@ref{16ff,,c_ubyte}

@tab

unsigned char

@tab

`int'

@item

@ref{2d4b,,c_short}

@tab

short

@tab

`int'

@item

@ref{2d4c,,c_ushort}

@tab

unsigned short

@tab

`int'

@item

@ref{2d3d,,c_int}

@tab

int

@tab

`int'

@item

@ref{2d4d,,c_uint}

@tab

unsigned int

@tab

`int'

@item

@ref{2d3e,,c_long}

@tab

long

@tab

`int'

@item

@ref{2d4e,,c_ulong}

@tab

unsigned long

@tab

`int'

@item

@ref{2d4f,,c_longlong}

@tab

__int64 or long long

@tab

`int'

@item

@ref{2d50,,c_ulonglong}

@tab

unsigned __int64 or
unsigned long long

@tab

`int'

@item

@ref{2d51,,c_size_t}

@tab

@code{size_t}

@tab

`int'

@item

@ref{121a,,c_ssize_t}

@tab

@code{ssize_t} or
@ref{a4e,,Py_ssize_t}

@tab

`int'

@item

@ref{1767,,c_time_t}

@tab

@code{time_t}

@tab

`int'

@item

@ref{2d52,,c_float}

@tab

float

@tab

`float'

@item

@ref{1888,,c_double}

@tab

double

@tab

`float'

@item

@ref{1889,,c_longdouble}

@tab

long double

@tab

`float'

@item

@ref{1670,,c_char_p}

@tab

char* (NUL terminated)

@tab

objet octet (`bytes') ou @code{None}

@item

@ref{1671,,c_wchar_p}

@tab

wchar_t* (NUL terminated)

@tab

chaîne de caractères (`string') ou @code{None}

@item

@ref{1672,,c_void_p}

@tab

void*

@tab

`int' ou @code{None}

@end multitable



@enumerate 

@item 
Le constructeur accepte n'importe quel objet convertible en booléen.
@end enumerate

Il est possible de créer chacun de ces types en les appelant avec une valeur d'initialisation du bon type et avec une valeur cohérente :

@example
>>> c_int()
c_long(0)
>>> c_wchar_p("Hello, World")
c_wchar_p(140018365411392)
>>> c_ushort(-3)
c_ushort(65533)
>>>
@end example

Ces types étant des mutables, leur valeur peut aussi être modifiée après coup :

@example
>>> i = c_int(42)
>>> print(i)
c_long(42)
>>> print(i.value)
42
>>> i.value = -99
>>> print(i.value)
-99
>>>
@end example

Affecter une nouvelle valeur à une instance de type pointeur — @ref{1670,,c_char_p}, @ref{1671,,c_wchar_p} et @ref{1672,,c_void_p} — change `la zone mémoire' sur laquelle elle pointe, et non `le contenu' de ce bloc mémoire (c'est logique parce que les objets octets sont immuables en Python) :

@example
>>> s = "Hello, World"
>>> c_s = c_wchar_p(s)
>>> print(c_s)
c_wchar_p(139966785747344)
>>> print(c_s.value)
Hello World
>>> c_s.value = "Hi, there"
>>> print(c_s)              # the memory location has changed
c_wchar_p(139966783348904)
>>> print(c_s.value)
Hi, there
>>> print(s)                # first object is unchanged
Hello, World
>>>
@end example

Cependant, prenez garde à ne pas en passer à des fonctions qui prennent en paramètre des pointeurs sur de la mémoire modifiable. S'il vous faut de la mémoire modifiable, `ctypes' fournit la fonction @ref{2d53,,create_string_buffer()} qui en crée de plusieurs façons. L'attribut @code{raw} permet d'accéder à (ou de modifier) un bloc mémoire ; l'attribut @code{value} permet d'y accéder comme à une chaîne de caractères terminée par NUL :

@example
>>> from ctypes import *
>>> p = create_string_buffer(3)            # create a 3 byte buffer, initialized to NUL bytes
>>> print(sizeof(p), repr(p.raw))
3 b'\x00\x00\x00'
>>> p = create_string_buffer(b"Hello")     # create a buffer containing a NUL terminated string
>>> print(sizeof(p), repr(p.raw))
6 b'Hello\x00'
>>> print(repr(p.value))
b'Hello'
>>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer
>>> print(sizeof(p), repr(p.raw))
10 b'Hello\x00\x00\x00\x00\x00'
>>> p.value = b"Hi"
>>> print(sizeof(p), repr(p.raw))
10 b'Hi\x00lo\x00\x00\x00\x00\x00'
>>>
@end example

The @ref{2d53,,create_string_buffer()} function replaces the old @code{c_buffer()}
function (which is still available as an alias).  To create a mutable memory
block containing unicode characters of the C type @code{wchar_t}, use the
@ref{195d,,create_unicode_buffer()} function.

@node Appel de fonctions suite,Calling variadic functions,Types de données de base,Didacticiel de ctypes
@anchor{library/ctypes calling-functions-continued}@anchor{2d54}@anchor{library/ctypes ctypes-calling-functions-continued}@anchor{2d55}
@subsubsection Appel de fonctions, suite


`printf' utilise la vraie sortie standard, et non @ref{ac4,,sys.stdout} ; les exemples suivants ne fonctionnent donc que dans une invite de commande et non depuis `IDLE' or `PythonWin' :

@example
>>> printf = libc.printf
>>> printf(b"Hello, %s\n", b"World!")
Hello, World!
14
>>> printf(b"Hello, %S\n", "World!")
Hello, World!
14
>>> printf(b"%d bottles of beer\n", 42)
42 bottles of beer
19
>>> printf(b"%f bottles of beer\n", 42.5)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert parameter 2
>>>
@end example

Comme mentionné plus haut, tous les types Python (les entiers, les chaînes de caractères et les objets octet exceptés) doivent être encapsulés dans leur type @ref{2a,,ctypes} correspondant pour pouvoir être convertis dans le type C requis :

@example
>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
An int 1234, a double 3.140000
31
>>>
@end example

@node Calling variadic functions,Appel de fonctions avec des types de données personnalisés,Appel de fonctions suite,Didacticiel de ctypes
@anchor{library/ctypes calling-variadic-functions}@anchor{2d56}@anchor{library/ctypes ctypes-calling-variadic-functions}@anchor{2d57}
@subsubsection Calling variadic functions


On a lot of platforms calling variadic functions through ctypes is exactly the same
as calling functions with a fixed number of parameters. On some platforms, and in
particular ARM64 for Apple Platforms, the calling convention for variadic functions
is different than that for regular functions.

On those platforms it is required to specify the @ref{2d58,,argtypes}
attribute for the regular, non-variadic, function arguments:

@example
libc.printf.argtypes = [ctypes.c_char_p]
@end example

Because specifying the attribute does not inhibit portability it is advised to always
specify @ref{2d58,,argtypes} for all variadic functions.

@node Appel de fonctions avec des types de données personnalisés,Définition du type des arguments nécessaires prototypes de fonction,Calling variadic functions,Didacticiel de ctypes
@anchor{library/ctypes calling-functions-with-your-own-custom-data-types}@anchor{2d59}@anchor{library/ctypes ctypes-calling-functions-with-own-custom-data-types}@anchor{2d5a}
@subsubsection Appel de fonctions avec des types de données personnalisés


You can also customize @ref{2a,,ctypes} argument conversion to allow instances of
your own classes be used as function arguments. @ref{2a,,ctypes} looks for an
@code{_as_parameter_} attribute and uses this as the function argument. The
attribute must be an integer, string, bytes, a @ref{2a,,ctypes} instance, or an
object with an @code{_as_parameter_} attribute:

@example
>>> class Bottles:
...     def __init__(self, number):
...         self._as_parameter_ = number
...
>>> bottles = Bottles(42)
>>> printf(b"%d bottles of beer\n", bottles)
42 bottles of beer
19
>>>
@end example

If you don't want to store the instance's data in the @code{_as_parameter_}
instance variable, you could define a @ref{192,,property} which makes the
attribute available on request.

@node Définition du type des arguments nécessaires prototypes de fonction,Types de sortie,Appel de fonctions avec des types de données personnalisés,Didacticiel de ctypes
@anchor{library/ctypes ctypes-specifying-required-argument-types}@anchor{2d5b}@anchor{library/ctypes specifying-the-required-argument-types-function-prototypes}@anchor{2d5c}
@subsubsection Définition du type des arguments nécessaires (prototypes de fonction)


It is possible to specify the required argument types of functions exported from
DLLs by setting the @ref{2d58,,argtypes} attribute.

@ref{2d58,,argtypes} must be a sequence of C data types (the @code{printf()} function is
probably not a good example here, because it takes a variable number and
different types of parameters depending on the format string, on the other hand
this is quite handy to experiment with this feature):

@example
>>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
>>> printf(b"String '%s', Int %d, Double %f\n", b"Hi", 10, 2.2)
String 'Hi', Int 10, Double 2.200000
37
>>>
@end example

Définir un format empêche de passer des arguments de type incompatible (comme le fait le prototype d'une fonction C) et tente de convertir les arguments en des types valides :

@example
>>> printf(b"%d %d %d", 1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be interpreted as ctypes.c_char_p
>>> printf(b"%s %d %f\n", b"X", 2, 3)
X 2 3.000000
13
>>>
@end example

If you have defined your own classes which you pass to function calls, you have
to implement a @ref{2d5d,,from_param()} class method for them to be able to use them
in the @ref{2d58,,argtypes} sequence. The @ref{2d5d,,from_param()} class method receives
the Python object passed to the function call, it should do a typecheck or
whatever is needed to make sure this object is acceptable, and then return the
object itself, its @code{_as_parameter_} attribute, or whatever you want to
pass as the C function argument in this case. Again, the result should be an
integer, string, bytes, a @ref{2a,,ctypes} instance, or an object with an
@code{_as_parameter_} attribute.

@node Types de sortie,Passage de pointeurs passage de paramètres par référence,Définition du type des arguments nécessaires prototypes de fonction,Didacticiel de ctypes
@anchor{library/ctypes ctypes-return-types}@anchor{2d5e}@anchor{library/ctypes return-types}@anchor{2d5f}
@subsubsection Types de sortie


@c from ctypes import CDLL, c_char, c_char_p
@c from ctypes.util import find_library
@c libc = CDLL(find_library('c'))
@c strchr = libc.strchr

By default functions are assumed to return the C int type.  Other
return types can be specified by setting the @ref{2d60,,restype} attribute of the
function object.

The C prototype of @code{time()} is @code{time_t time(time_t *)}. Because @code{time_t}
might be of a different type than the default return type int, you should
specify the @code{restype} attribute:

@example
>>> libc.time.restype = c_time_t
@end example

The argument types can be specified using @ref{2d58,,argtypes}:

@example
>>> libc.time.argtypes = (POINTER(c_time_t),)
@end example

To call the function with a @code{NULL} pointer as first argument, use @code{None}:

@example
>>> print(libc.time(None))  
1150640792
@end example

Here is a more advanced example, it uses the @code{strchr()} function, which expects
a string pointer and a char, and returns a pointer to a string:

@example
>>> strchr = libc.strchr
>>> strchr(b"abcdef", ord("d"))  
8059983
>>> strchr.restype = c_char_p    # c_char_p is a pointer to a string
>>> strchr(b"abcdef", ord("d"))
b'def'
>>> print(strchr(b"abcdef", ord("x")))
None
>>>
@end example

If you want to avoid the @ref{1e75,,ord("x")} calls above, you can set the
@ref{2d58,,argtypes} attribute, and the second argument will be converted from a
single character Python bytes object into a C char:

@example
>>> strchr.restype = c_char_p
>>> strchr.argtypes = [c_char_p, c_char]
>>> strchr(b"abcdef", b"d")
b'def'
>>> strchr(b"abcdef", b"def")
Traceback (most recent call last):
ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray or integer expected
>>> print(strchr(b"abcdef", b"x"))
None
>>> strchr(b"abcdef", b"d")
b'def'
>>>
@end example

You can also use a callable Python object (a function or a class for example) as
the @ref{2d60,,restype} attribute, if the foreign function returns an integer.  The
callable will be called with the `integer' the C function returns, and the
result of this call will be used as the result of your function call. This is
useful to check for error return values and automatically raise an exception:

@example
>>> GetModuleHandle = windll.kernel32.GetModuleHandleA  
>>> def ValidHandle(value):
...     if value == 0:
...         raise WinError()
...     return value
...
>>>
>>> GetModuleHandle.restype = ValidHandle  
>>> GetModuleHandle(None)  
486539264
>>> GetModuleHandle("something silly")  
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 3, in ValidHandle
OSError: [Errno 126] The specified module could not be found.
>>>
@end example

@code{WinError} appelle l'API Windows @code{FormatMessage()} pour obtenir une représentation de la chaîne de caractères qui correspond au code d'erreur, et `renvoie' une exception. @code{WinError} prend en paramètre — optionnel — le code d'erreur. Si celui-ci n'est pas passé, elle appelle @ref{2d61,,GetLastError()} pour le récupérer.

Please note that a much more powerful error checking mechanism is available
through the @ref{2d62,,errcheck} attribute;
see the reference manual for details.

@node Passage de pointeurs passage de paramètres par référence,Structures et unions,Types de sortie,Didacticiel de ctypes
@anchor{library/ctypes ctypes-passing-pointers}@anchor{2d63}@anchor{library/ctypes passing-pointers-or-passing-parameters-by-reference}@anchor{2d64}
@subsubsection Passage de pointeurs (passage de paramètres par référence)


Il arrive qu'une fonction C du code à interfacer requière un `pointeur' vers un certain type de donnée en paramètre, typiquement pour écrire à l'endroit correspondant ou si la donnée est trop grande pour pouvoir être passée par valeur. Ce mécanisme est appelé `passage de paramètres par référence'.

@ref{2a,,ctypes} contient la fonction @ref{2d65,,byref()} qui permet de passer des paramètres par référence. La fonction @ref{166e,,pointer()} a la même utilité, mais fait plus de travail car @ref{166e,,pointer()} construit un véritable objet pointeur. Ainsi, si vous n'avez pas besoin de cet objet dans votre code Python, utiliser @ref{2d65,,byref()} est plus performant :

@example
>>> i = c_int()
>>> f = c_float()
>>> s = create_string_buffer(b'\000' * 32)
>>> print(i.value, f.value, repr(s.value))
0 0.0 b'@w{'}
>>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",
...             byref(i), byref(f), s)
3
>>> print(i.value, f.value, repr(s.value))
1 3.1400001049 b'Hello'
>>>
@end example

@node Structures et unions,Alignement et boutisme des structures et des unions,Passage de pointeurs passage de paramètres par référence,Didacticiel de ctypes
@anchor{library/ctypes ctypes-structures-unions}@anchor{2d66}@anchor{library/ctypes structures-and-unions}@anchor{2d67}
@subsubsection Structures et unions


Structures and unions must derive from the @ref{1cf,,Structure} and @ref{160a,,Union}
base classes which are defined in the @ref{2a,,ctypes} module. Each subclass must
define a @ref{2d68,,_fields_} attribute.  @code{_fields_} must be a list of
`2-tuples', containing a `field name' and a `field type'.

Le type de champ doit être un type @ref{2a,,ctypes} comme @ref{2d3d,,c_int} ou un type @ref{2a,,ctypes} dérivé : structure, union, tableau ou pointeur.

Voici un exemple simple : une structure POINT qui contient deux entiers `x' et `y' et qui montre également comment instancier une structure avec le constructeur :

@example
>>> from ctypes import *
>>> class POINT(Structure):
...     _fields_ = [("x", c_int),
...                 ("y", c_int)]
...
>>> point = POINT(10, 20)
>>> print(point.x, point.y)
10 20
>>> point = POINT(y=5)
>>> print(point.x, point.y)
0 5
>>> POINT(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: too many initializers
>>>
@end example

Il est bien entendu possible de créer des structures plus complexes. Une structure peut elle-même contenir d'autres structures en prenant une structure comme type de champ.

Voici une structure RECT qui contient deux POINTs `upperleft' et `lowerright' :

@example
>>> class RECT(Structure):
...     _fields_ = [("upperleft", POINT),
...                 ("lowerright", POINT)]
...
>>> rc = RECT(point)
>>> print(rc.upperleft.x, rc.upperleft.y)
0 5
>>> print(rc.lowerright.x, rc.lowerright.y)
0 0
>>>
@end example

Une structure encapsulée peut être instanciée par un constructeur de plusieurs façons :

@example
>>> r = RECT(POINT(1, 2), POINT(3, 4))
>>> r = RECT((1, 2), (3, 4))
@end example

Il est possible de récupérer les @ref{1ef3,,descripteurs} des champs depuis la `classe'. Ils sont importants pour déboguer car ils contiennent des informations utiles :

@example
>>> print(POINT.x)
<Field type=c_long, ofs=0, size=4>
>>> print(POINT.y)
<Field type=c_long, ofs=4, size=4>
>>>
@end example
@anchor{library/ctypes ctypes-structureunion-alignment-byte-order}@anchor{2d69}
@cartouche
@quotation Avertissement 
@ref{2a,,ctypes} ne prend pas en charge le passage par valeur des unions ou des structures avec des champs de bits. Bien que cela puisse fonctionner sur des architectures 32 bits avec un jeu d'instructions x86, ce n'est pas garanti par la bibliothèque en général. Les unions et les structures avec des champs de bits doivent toujours être passées par pointeur.
@end quotation
@end cartouche

@node Alignement et boutisme des structures et des unions,Champs de bits dans les structures et les unions,Structures et unions,Didacticiel de ctypes
@anchor{library/ctypes structure-union-alignment-and-byte-order}@anchor{2d6a}
@subsubsection Alignement et boutisme des structures et des unions


By default, Structure and Union fields are aligned in the same way the C
compiler does it. It is possible to override this behavior by specifying a
@ref{2d6b,,_pack_} class attribute in the subclass definition.
This must be set to a positive integer and specifies the maximum alignment for the fields.
This is what @code{#pragma pack(n)} also does in MSVC.
It is also possible to set a minimum alignment for how the subclass itself is packed in the
same way @code{#pragma align(n)} works in MSVC.
This can be achieved by specifying a :@ref{1d0,,_align_} class attribute
in the subclass definition.

@ref{2a,,ctypes} suit le boutisme natif pour les `Structure' et les `Union'. Pour construire des structures avec un boutisme différent, utilisez les classes de base @ref{2d6c,,BigEndianStructure}, @ref{2d6d,,LittleEndianStructure}, @ref{17b4,,BigEndianUnion} ou @ref{17b5,,LittleEndianUnion}. Ces classes ne peuvent pas avoir de champ pointeur.

@node Champs de bits dans les structures et les unions,Tableaux,Alignement et boutisme des structures et des unions,Didacticiel de ctypes
@anchor{library/ctypes bit-fields-in-structures-and-unions}@anchor{2d6e}@anchor{library/ctypes ctypes-bit-fields-in-structures-unions}@anchor{2d6f}
@subsubsection Champs de bits dans les structures et les unions


It is possible to create structures and unions containing bit fields. Bit fields
are only possible for integer fields, the bit width is specified as the third
item in the @ref{2d68,,_fields_} tuples:

@example
>>> class Int(Structure):
...     _fields_ = [("first_16", c_int, 16),
...                 ("second_16", c_int, 16)]
...
>>> print(Int.first_16)
<Field type=c_long, ofs=0:0, bits=16>
>>> print(Int.second_16)
<Field type=c_long, ofs=0:16, bits=16>
>>>
@end example

@node Tableaux,Pointeurs,Champs de bits dans les structures et les unions,Didacticiel de ctypes
@anchor{library/ctypes arrays}@anchor{2d70}@anchor{library/ctypes ctypes-arrays}@anchor{2d71}
@subsubsection Tableaux


Les tableaux sont des séquences qui contiennent un nombre fixe d'instances du même type.

La meilleure façon de créer des tableaux consiste à multiplier le type de donnée par un entier positif :

@example
TenPointsArrayType = POINT * 10
@end example

Voici un exemple — un peu artificiel — d'une structure contenant, entre autres, 4 POINTs :

@example
>>> from ctypes import *
>>> class POINT(Structure):
...     _fields_ = ("x", c_int), ("y", c_int)
...
>>> class MyStruct(Structure):
...     _fields_ = [("a", c_int),
...                 ("b", c_float),
...                 ("point_array", POINT * 4)]
>>>
>>> print(len(MyStruct().point_array))
4
>>>
@end example

Comme d'habitude, on crée les instances en appelant la classe :

@example
arr = TenPointsArrayType()
for pt in arr:
    print(pt.x, pt.y)
@end example

Le code précédent affiche une suite de @code{0 0} car le contenu du tableau est initialisé avec des zéros.

Des valeurs d'initialisation du bon type peuvent être passées :

@example
>>> from ctypes import *
>>> TenIntegers = c_int * 10
>>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
>>> print(ii)
<c_long_Array_10 object at 0x...>
>>> for i in ii: print(i, end=" ")
...
1 2 3 4 5 6 7 8 9 10
>>>
@end example

@node Pointeurs,Conversions de type,Tableaux,Didacticiel de ctypes
@anchor{library/ctypes ctypes-pointers}@anchor{2d72}@anchor{library/ctypes pointers}@anchor{2d73}
@subsubsection Pointeurs


On crée une instance de pointeur en appelant la fonction @ref{166e,,pointer()} sur un type @ref{2a,,ctypes} :

@example
>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>
@end example

Les instances de pointeurs ont un attribut @ref{2d74,,contents} qui renvoie l'objet pointé (l'objet @code{i} ci-dessus) :

@example
>>> pi.contents
c_long(42)
>>>
@end example

Attention, @ref{2a,,ctypes} ne fait pas de ROI (retour de l'objet initial). Il crée un nouvel objet à chaque fois qu'on accède à un attribut :

@example
>>> pi.contents is i
False
>>> pi.contents is pi.contents
False
>>>
@end example

Affecter une autre instance de @ref{2d3d,,c_int} à l'attribut `contents' du pointeur fait pointer le pointeur vers l'adresse mémoire de cette nouvelle instance :

@example
>>> i = c_int(99)
>>> pi.contents = i
>>> pi.contents
c_long(99)
>>>
@end example

@c XXX Document dereferencing pointers, and that it is preferred over the
@c .contents attribute.

Il est possible d'indexer les pointeurs par des entiers :

@example
>>> pi[0]
99
>>>
@end example

Affecter à travers un indice change la valeur pointée :

@example
>>> print(i)
c_long(99)
>>> pi[0] = 22
>>> print(i)
c_long(22)
>>>
@end example

Si vous êtes sûr de vous, vous pouvez utiliser d'autres valeurs que 0, comme en C : il est ainsi possible de modifier une zone mémoire de votre choix. De manière générale cette fonctionnalité ne s'utilise que sur un pointeur renvoyé par une fonction C, pointeur que vous `savez' pointer vers un tableau et non sur un seul élément.

Sous le capot, la fonction @ref{166e,,pointer()} fait plus que simplement créer une instance de pointeur ; elle doit d'abord créer un type « pointeur sur… ». Cela s'effectue avec la fonction @ref{166f,,POINTER()}, qui prend en paramètre n'importe quel type @ref{2a,,ctypes} et renvoie un nouveau type :

@example
>>> PI = POINTER(c_int)
>>> PI
<class 'ctypes.LP_c_long'>
>>> PI(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: expected c_long instead of int
>>> PI(c_int(42))
<ctypes.LP_c_long object at 0x...>
>>>
@end example

Appeler le pointeur sur type sans arguments crée un pointeur @code{NULL}. Les pointeurs @code{NULL} s'évaluent à @code{False} :

@example
>>> null_ptr = POINTER(c_int)()
>>> print(bool(null_ptr))
False
>>>
@end example

@ref{2a,,ctypes} vérifie que le pointeur n'est pas @code{NULL} quand il en déréférence un (mais déréférencer des pointeurs non @code{NULL} invalides fait planter Python) :

@example
>>> null_ptr[0]
Traceback (most recent call last):
    ....
ValueError: NULL pointer access
>>>

>>> null_ptr[0] = 1234
Traceback (most recent call last):
    ....
ValueError: NULL pointer access
>>>
@end example

@node Conversions de type,Types incomplets,Pointeurs,Didacticiel de ctypes
@anchor{library/ctypes ctypes-type-conversions}@anchor{2d75}@anchor{library/ctypes type-conversions}@anchor{2d76}
@subsubsection Conversions de type


Usually, ctypes does strict type checking.  This means, if you have
@code{POINTER(c_int)} in the @ref{2d58,,argtypes} list of a function or as the type of
a member field in a structure definition, only instances of exactly the same
type are accepted.  There are some exceptions to this rule, where ctypes accepts
other objects.  For example, you can pass compatible array instances instead of
pointer types.  So, for @code{POINTER(c_int)}, ctypes accepts an array of c_int:

@example
>>> class Bar(Structure):
...     _fields_ = [("count", c_int), ("values", POINTER(c_int))]
...
>>> bar = Bar()
>>> bar.values = (c_int * 3)(1, 2, 3)
>>> bar.count = 3
>>> for i in range(bar.count):
...     print(bar.values[i])
...
1
2
3
>>>
@end example

In addition, if a function argument is explicitly declared to be a pointer type
(such as @code{POINTER(c_int)}) in @ref{2d58,,argtypes}, an object of the pointed
type (@code{c_int} in this case) can be passed to the function.  ctypes will apply
the required @ref{2d65,,byref()} conversion in this case automatically.

Pour mettre un champ de type `POINTER' à @code{NULL}, il faut lui affecter @code{None} :

@example
>>> bar.values = None
>>>
@end example

@c XXX list other conversions...

Parfois il faut gérer des incompatibilités entre les types. En C, il est possible de convertir un type en un autre. @ref{2a,,ctypes} fournit la fonction @ref{2d77,,cast()} qui permet la même chose. La structure @code{Bar} ci-dessus accepte des pointeurs @code{POINTER(c_int)} ou des tableaux de @ref{2d3d,,c_int} comme valeur pour le champ @code{values}, mais pas des instances d'autres types :

@example
>>> bar.values = (c_byte * 4)()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
>>>
@end example

C'est là que la fonction @ref{2d77,,cast()} intervient.

La fonction @ref{2d77,,cast()} permet de convertir une instance de `ctypes' en un pointeur vers un type de données `ctypes' différent. @ref{2d77,,cast()} prend deux paramètres : un objet `ctypes' qui est, ou qui peut être converti en, un certain pointeur et un type pointeur de `ctypes'. Elle renvoie une instance du second argument, qui pointe sur le même bloc mémoire que le premier argument :

@example
>>> a = (c_byte * 4)()
>>> cast(a, POINTER(c_int))
<ctypes.LP_c_long object at ...>
>>>
@end example

Ainsi, la fonction @ref{2d77,,cast()} permet de remplir le champ @code{values} de la structure @code{Bar} :

@example
>>> bar = Bar()
>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
>>> print(bar.values[0])
0
>>>
@end example

@node Types incomplets,Fonctions de rappel,Conversions de type,Didacticiel de ctypes
@anchor{library/ctypes ctypes-incomplete-types}@anchor{2d78}@anchor{library/ctypes incomplete-types}@anchor{2d79}
@subsubsection Types incomplets


Un `type incomplet' est une structure, une union ou un tableau dont les membres ne sont pas encore définis. C'est l'équivalent d'une déclaration avancée en C, où la définition est fournie plus tard :

@example
struct cell; /* forward declaration */

struct cell @{
    char *name;
    struct cell *next;
@};
@end example

Une traduction naïve, mais invalide, en code `ctypes' ressemblerait à ça :

@example
>>> class cell(Structure):
...     _fields_ = [("name", c_char_p),
...                 ("next", POINTER(cell))]
...
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in cell
NameError: name 'cell' is not defined
>>>
@end example

because the new @code{class cell} is not available in the class statement itself.
In @ref{2a,,ctypes}, we can define the @code{cell} class and set the
@ref{2d68,,_fields_} attribute later, after the class statement:

@example
>>> from ctypes import *
>>> class cell(Structure):
...     pass
...
>>> cell._fields_ = [("name", c_char_p),
...                  ("next", POINTER(cell))]
>>>
@end example

Essayons. Nous créons deux instances de @code{cell}, les faisons pointer l'une sur l'autre et enfin nous suivons quelques maillons de la chaîne de pointeurs :

@example
>>> c1 = cell()
>>> c1.name = b"foo"
>>> c2 = cell()
>>> c2.name = b"bar"
>>> c1.next = pointer(c2)
>>> c2.next = pointer(c1)
>>> p = c1
>>> for i in range(8):
...     print(p.name, end=" ")
...     p = p.next[0]
...
foo bar foo bar foo bar foo bar
>>>
@end example

@node Fonctions de rappel,Accès aux variables exportées depuis une DLL,Types incomplets,Didacticiel de ctypes
@anchor{library/ctypes callback-functions}@anchor{2d7a}@anchor{library/ctypes ctypes-callback-functions}@anchor{2d7b}
@subsubsection Fonctions de rappel


@ref{2a,,ctypes} permet de créer des pointeurs de fonctions appelables par des appelables Python. On les appelle parfois `fonctions de rappel'.

Tout d'abord, il faut créer une classe pour la fonction de rappel. La classe connaît la convention d'appel, le type de retour ainsi que le nombre et le type de paramètres que la fonction accepte.

La fabrique @ref{2d7c,,CFUNCTYPE()} crée un type pour les fonctions de rappel qui suivent la convention d'appel @code{cdecl}. En Windows, c'est la fabrique @ref{2d7d,,WINFUNCTYPE()} qui crée un type pour les fonctions de rappel qui suivent la convention d'appel @code{stdcall}.

Le premier paramètre de ces deux fonctions est le type de retour, et les suivants sont les types des arguments qu'attend la fonction de rappel.

I will present an example here which uses the standard C library's
@code{qsort()} function, that is used to sort items with the help of a callback
function.  @code{qsort()} will be used to sort an array of integers:

@example
>>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99)
>>> qsort = libc.qsort
>>> qsort.restype = None
>>>
@end example

@code{qsort()} must be called with a pointer to the data to sort, the number of
items in the data array, the size of one item, and a pointer to the comparison
function, the callback. The callback will then be called with two pointers to
items, and it must return a negative integer if the first item is smaller than
the second, a zero if they are equal, and a positive integer otherwise.

Ainsi notre fonction de rappel reçoit des pointeurs vers des entiers et doit renvoyer un entier. Créons d'abord le @code{type} pour la fonction de rappel :

@example
>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
>>>
@end example

Pour commencer, voici une fonction de rappel simple qui affiche les valeurs qu'on lui passe :

@example
>>> def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return 0
...
>>> cmp_func = CMPFUNC(py_cmp_func)
>>>
@end example

Résultat :

@example
>>> qsort(ia, len(ia), sizeof(c_int), cmp_func)  
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 5 7
py_cmp_func 1 7
>>>
@end example

À présent, comparons pour de vrai les deux entiers et renvoyons un résultat utile :

@example
>>> def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return a[0] - b[0]
...
>>>
>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) 
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>
@end example

Et comme il est facile de le voir, notre tableau est désormais classé :

@example
>>> for i in ia: print(i, end=" ")
...
1 5 7 33 99
>>>
@end example

Ces fonctions peuvent aussi être utilisées comme des décorateurs ; il est donc possible d'écrire :

@example
>>> @@CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
... def py_cmp_func(a, b):
...     print("py_cmp_func", a[0], b[0])
...     return a[0] - b[0]
...
>>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>
@end example

@cartouche
@quotation Note 
Prenez garde à bien conserver une référence à un objet @ref{2d7c,,CFUNCTYPE()} tant que celui-ci est utilisé par le code C. @ref{2a,,ctypes} ne le fait pas tout seul et, si vous ne le faites pas, le ramasse-miette pourrait les libérer, ce qui fera planter votre programme quand un appel sera fait.

Notez aussi que si la fonction de rappel est appelée dans un fil d'exécution créé hors de Python (p. ex. par du code externe qui appelle la fonction de rappel), `ctypes' crée un nouveau fil Python « creux » à chaque fois. Ce comportement est acceptable pour la plupart des cas d'utilisation, mais cela implique que les valeurs stockées avec @ref{16f9,,threading.local} ne seront `pas' persistantes d'un appel à l'autre, même si les appels proviennent du même fil d'exécution C.
@end quotation
@end cartouche

@node Accès aux variables exportées depuis une DLL,Pièges,Fonctions de rappel,Didacticiel de ctypes
@anchor{library/ctypes accessing-values-exported-from-dlls}@anchor{2d7e}@anchor{library/ctypes ctypes-accessing-values-exported-from-dlls}@anchor{2d7f}
@subsubsection Accès aux variables exportées depuis une DLL


Some shared libraries not only export functions, they also export variables. An
example in the Python library itself is the @ref{740,,Py_Version}, Python
runtime version number encoded in a single constant integer.

@ref{2a,,ctypes} can access values like this with the @ref{2d80,,in_dll()} class methods of
the type.  `pythonapi' is a predefined symbol giving access to the Python C
api:

@example
>>> version = ctypes.c_int.in_dll(ctypes.pythonapi, "Py_Version")
>>> print(hex(version.value))
0x30c00a0
@end example

Le pointeur @ref{2d81,,PyImport_FrozenModules} exposé par Python est un autre exemple complet de l'utilisation de pointeurs.

Citons la documentation :

@quotation

This pointer is initialized to point to an array of @ref{75f,,_frozen}
records, terminated by one whose members are all @code{NULL} or zero.  When a frozen
module is imported, it is searched in this table.  Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules.
@end quotation

Donc manipuler ce pointeur peut même se révéler utile. Pour limiter la taille de l'exemple, nous nous bornons à montrer comment lire ce tableau avec @ref{2a,,ctypes} :

@example
>>> from ctypes import *
>>>
>>> class struct_frozen(Structure):
...     _fields_ = [("name", c_char_p),
...                 ("code", POINTER(c_ubyte)),
...                 ("size", c_int),
...                 ("get_code", POINTER(c_ubyte)),  # Function pointer
...                ]
...
>>>
@end example

We have defined the @ref{75f,,_frozen} data type, so we can get the pointer
to the table:

@example
>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "_PyImport_FrozenBootstrap")
>>>
@end example

Puisque @code{table} est un @code{pointer} vers un tableau d'entrées de @code{struct_frozen}, il est possible d'itérer dessus, mais il faut être certain que la boucle se termine, car les pointeurs n'ont pas de taille. Tôt ou tard, il planterait probablement avec une erreur de segmentation ou autre, donc mieux vaut sortir de la boucle quand on lit l'entrée @code{NULL} :

@example
>>> for item in table:
...     if item.name is None:
...         break
...     print(item.name.decode("ascii"), item.size)
...
_frozen_importlib 31764
_frozen_importlib_external 41499
zipimport 12345
>>>
@end example

Le fait que le standard Python possède un module et un paquet figés (indiqués par la valeur négative du membre `size') est peu connu, cela ne sert qu'aux tests. Essayez avec @code{import __hello__} par exemple.

@node Pièges,Types de données à taille flottante,Accès aux variables exportées depuis une DLL,Didacticiel de ctypes
@anchor{library/ctypes ctypes-surprises}@anchor{2d82}@anchor{library/ctypes surprises}@anchor{2d83}
@subsubsection Pièges


Il y a quelques cas tordus dans @ref{2a,,ctypes} où on peut s'attendre à un résultat différent de la réalité.

Examinons l'exemple suivant :

@example
>>> from ctypes import *
>>> class POINT(Structure):
...     _fields_ = ("x", c_int), ("y", c_int)
...
>>> class RECT(Structure):
...     _fields_ = ("a", POINT), ("b", POINT)
...
>>> p1 = POINT(1, 2)
>>> p2 = POINT(3, 4)
>>> rc = RECT(p1, p2)
>>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
1 2 3 4
>>> # now swap the two points
>>> rc.a, rc.b = rc.b, rc.a
>>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
3 4 3 4
>>>
@end example

Diantre. On s'attendait certainement à ce que le dernier résultat affiche @code{3 4 1 2}. Que s'est-il passé ? Les étapes de la ligne @code{rc.a, rc.b = rc.b, rc.a} ci-dessus sont les suivantes :

@example
>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
>>>
@end example

Les objets @code{temp0} et @code{temp1} utilisent encore le tampon interne de l'objet @code{rc} ci-dessus. Donc exécuter @code{rc.a = temp0} copie le contenu du tampon de @code{temp0} dans celui de @code{rc}. Ce qui, par ricochet, modifie le contenu de @code{temp1}. Et donc, la dernière affectation, @code{rc.b = temp1}, n'a pas l'effet escompté.

Gardez en tête qu'accéder au sous-objet depuis une `Structure', une `Union' ou un `Array' ne copie `pas' le sous-objet, mais crée un objet interface qui accède au tampon sous-jacent de l'objet initial.

Un autre exemple de comportement `a priori' inattendu est le suivant :

@example
>>> s = c_char_p()
>>> s.value = b"abc def ghi"
>>> s.value
b'abc def ghi'
>>> s.value is s.value
False
>>>
@end example

@cartouche
@quotation Note 
La valeur d'une instance de @ref{1670,,c_char_p} ne peut être initialisée qu'avec un octet ou un entier.
@end quotation
@end cartouche

Pourquoi cela affiche-t'il @code{False} ? Les instances `ctypes' sont des objets qui contiennent un bloc mémoire et des @ref{1ef3,,descriptor} qui donnent accès au contenu du ce bloc. Stocker un objet Python dans le bloc mémoire ne stocke pas l'objet même ; seuls ses @code{contents} le sont. Accéder au @code{contents} crée un nouvel objet Python à chaque fois !

@node Types de données à taille flottante,,Pièges,Didacticiel de ctypes
@anchor{library/ctypes ctypes-variable-sized-data-types}@anchor{2d84}@anchor{library/ctypes variable-sized-data-types}@anchor{2d85}
@subsubsection Types de données à taille flottante


@ref{2a,,ctypes} assure la prise en charge des tableaux et des structures à taille flottante.

La fonction @ref{2d86,,resize()} permet de redimensionner la taille du tampon mémoire d'un objet `ctypes' existant. Cette fonction prend l'objet comme premier argument et la taille en octets désirée comme second. La taille du tampon mémoire ne peut pas être inférieure à celle occupée par un objet unitaire du type considéré. Une @ref{1ff,,ValueError} est levée si c'est le cas :

@example
>>> short_array = (c_short * 4)()
>>> print(sizeof(short_array))
8
>>> resize(short_array, 4)
Traceback (most recent call last):
    ...
ValueError: minimum size is 8
>>> resize(short_array, 32)
>>> sizeof(short_array)
32
>>> sizeof(type(short_array))
8
>>>
@end example

Cela dit, comment accéder aux éléments supplémentaires contenus dans le tableau ? Vu que le type ne connaît que 4 éléments, on obtient une erreur si l'on accède aux suivants :

@example
>>> short_array[:]
[0, 0, 0, 0]
>>> short_array[7]
Traceback (most recent call last):
    ...
IndexError: invalid index
>>>
@end example

Une autre approche pour utiliser des types de donnée à taille flottante avec @ref{2a,,ctypes} consiste à tirer profit de la nature intrinsèquement dynamique de Python et de (re)définir le type de donnée une fois que la taille demandée est connue, au cas-par-cas.

@node Référence du module,,Didacticiel de ctypes,ctypes --- A foreign function library for Python
@anchor{library/ctypes ctypes-ctypes-reference}@anchor{2d87}@anchor{library/ctypes ctypes-reference}@anchor{2d88}
@subsubsection Référence du module


@menu
* Recherche de bibliothèques partagées:: 
* Chargement des bibliothèques partagées:: 
* Fonctions externes:: 
* Prototypes de fonction:: 
* Fonctions utilitaires:: 
* Types de données: Types de données<3>. 
* Types de données de base: Types de données de base<2>. 
* Types de données dérivés de Structure:: 
* Tableaux et pointeurs:: 

@end menu

@node Recherche de bibliothèques partagées,Chargement des bibliothèques partagées,,Référence du module
@anchor{library/ctypes ctypes-finding-shared-libraries}@anchor{2d89}@anchor{library/ctypes finding-shared-libraries}@anchor{2d8a}
@subsubsection Recherche de bibliothèques partagées


Les langages compilés ont besoin d'accéder aux bibliothèques partagées au moment de la compilation, de l'édition de liens et pendant l'exécution du programme.

The purpose of the @ref{d37,,find_library()} function is to locate a library in a way
similar to what the compiler or runtime loader does (on platforms with several
versions of a shared library the most recent should be loaded), while the ctypes
library loaders act like when a program is run, and call the runtime loader
directly.

The @code{ctypes.util} module provides a function which can help to determine
the library to load.


@deffn {Données} ctypes.util.find_library (name)

Tente de trouver une bibliothèque et en renvoie le chemin. `name' est le nom de la bibliothèque sans préfixe — comme `lib' — ni suffixe — comme @code{.so}, @code{.dylib} ou un numéro de version (c.-à-d. la même forme que l'option POSIX de l'éditeur de lien @code{-l}). Si la fonction ne parvient pas à trouver de bibliothèque, elle renvoie @code{None}.
@end deffn

Le mode opératoire exact dépend du système.

On Linux, @ref{d37,,find_library()} tries to run external programs
(@code{/sbin/ldconfig}, @code{gcc}, @code{objdump} and @code{ld}) to find the library file.
It returns the filename of the library file.


Modifié dans la version 3.6: Sous Linux, si les autres moyens échouent, la fonction utilise la variable d'environnement @code{LD_LIBRARY_PATH} pour trouver la bibliothèque.


Voici quelques exemples :

@example
>>> from ctypes.util import find_library
>>> find_library("m")
'libm.so.6'
>>> find_library("c")
'libc.so.6'
>>> find_library("bz2")
'libbz2.so.1.0'
>>>
@end example

On macOS and Android, @ref{d37,,find_library()} uses the system's
standard naming schemes and paths to locate the library, and returns a full
pathname if successful:

@example
>>> from ctypes.util import find_library
>>> find_library("c")
'/usr/lib/libc.dylib'
>>> find_library("m")
'/usr/lib/libm.dylib'
>>> find_library("bz2")
'/usr/lib/libbz2.dylib'
>>> find_library("AGL")
'/System/Library/Frameworks/AGL.framework/AGL'
>>>
@end example

On Windows, @ref{d37,,find_library()} searches along the system search path, and
returns the full pathname, but since there is no predefined naming scheme a call
like @code{find_library("c")} will fail and return @code{None}.

If wrapping a shared library with @ref{2a,,ctypes}, it `may' be better to determine
the shared library name at development time, and hardcode that into the wrapper
module instead of using @ref{d37,,find_library()} to locate the library at runtime.

@node Chargement des bibliothèques partagées,Fonctions externes,Recherche de bibliothèques partagées,Référence du module
@anchor{library/ctypes ctypes-loading-shared-libraries}@anchor{2d8b}@anchor{library/ctypes loading-shared-libraries}@anchor{2d8c}
@subsubsection Chargement des bibliothèques partagées


Il y a plusieurs moyens de charger une bibliothèque partagée dans un processus Python. L'un d'entre eux consiste à instancier une des classes suivantes :

@geindex CDLL (classe dans ctypes)
@anchor{library/ctypes ctypes CDLL}@anchor{9d7}
@deffn {Classe} ctypes.CDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return
int.

En Windows, créer une instance de @ref{9d7,,CDLL} peut échouer, même si une DLL du bon nom existe. Quand une des dépendances de la DLL à charger ne peut pas être trouvée, une @ref{40d,,OSError} est levée avec le message `"[WinError 126] The specified module could not be found".' Ce message d'erreur ne contient pas le nom de la DLL manquante car l'API Windows ne fournit pas cette information. Cela rend l'erreur délicate à analyser ; pour la résoudre, il faut lister toutes les dépendances de la DLL et trouver celle qui manque en utilisant des outils de débogage et de traçage Windows.


Modifié dans la version 3.12: The `name' parameter can now be a @ref{29d,,path-like object}.

@end deffn


@subsubheading Voir aussi


DUMPBIN@footnote{https://docs.microsoft.com/cpp/build/reference/dependents} — un utilitaire Microsoft pour lister les dépendances d'une DLL.


@geindex OleDLL (classe dans ctypes)
@anchor{library/ctypes ctypes OleDLL}@anchor{1700}
@deffn {Classe} ctypes.OleDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Instances of this class represent loaded shared libraries,
functions in these libraries use the @code{stdcall} calling convention, and are
assumed to return the windows specific @ref{2d8d,,HRESULT} code.  @ref{2d8d,,HRESULT}
values contain information specifying whether the function call failed or
succeeded, together with additional error code.  If the return value signals a
failure, an @ref{40d,,OSError} is automatically raised.

@ref{1ce0,,Availability}: Windows


Modifié dans la version 3.3: @ref{103d,,WindowsError} used to be raised,
which is now an alias of @ref{40d,,OSError}.



Modifié dans la version 3.12: The `name' parameter can now be a @ref{29d,,path-like object}.

@end deffn

@geindex WinDLL (classe dans ctypes)
@anchor{library/ctypes ctypes WinDLL}@anchor{1701}
@deffn {Classe} ctypes.WinDLL (name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

Instances of this class represent loaded shared libraries,
functions in these libraries use the @code{stdcall} calling convention, and are
assumed to return int by default.

@ref{1ce0,,Availability}: Windows


Modifié dans la version 3.12: The `name' parameter can now be a @ref{29d,,path-like object}.

@end deffn

Le @ref{147,,verrou global de l'interpréteur} Python est relâché avant chaque appel d'une fonction exposée par ces bibliothèques et ré-activé après.

@geindex PyDLL (classe dans ctypes)
@anchor{library/ctypes ctypes PyDLL}@anchor{1702}
@deffn {Classe} ctypes.PyDLL (name, mode=DEFAULT_MODE, handle=None)

Cette classe est identique à @ref{9d7,,CDLL}, à ceci près que le GIL n'est `pas' relâché pendant l'appel de la fonction, et, qu'au terme de l'appel, le drapeau d'erreur Python est vérifié. Si celui-ci est activé, une exception Python est levée.

Donc, cette classe ne sert qu'à appeler les fonctions de l'API C de Python.


Modifié dans la version 3.12: The `name' parameter can now be a @ref{29d,,path-like object}.

@end deffn

All these classes can be instantiated by calling them with at least one
argument, the pathname of the shared library.  If you have an existing handle to
an already loaded shared library, it can be passed as the @code{handle} named
parameter, otherwise the underlying platform's @code{dlopen()} or
@code{LoadLibrary()} function is used to load the library into
the process, and to get a handle to it.

Le mode de chargement de la bibliothèque est défini par le paramètre `mode'. Pour plus de détails, référez-vous à l'entrée @code{dlopen(3)@footnote{https://manpages.debian.org/dlopen(3)}} du manuel. En Windows, `mode' est ignoré. Sur les systèmes POSIX, RTLD_NOW y est toujours ajouté. Ceci n'est pas configurable.

The `use_errno' parameter, when set to true, enables a ctypes mechanism that
allows accessing the system @ref{56,,errno} error number in a safe way.
@ref{2a,,ctypes} maintains a thread-local copy of the system's @ref{56,,errno}
variable; if you call foreign functions created with @code{use_errno=True} then the
@ref{56,,errno} value before the function call is swapped with the ctypes private
copy, the same happens immediately after the function call.

La fonction @ref{2d8e,,ctypes.get_errno()} renvoie la valeur de la copie privée de `ctypes'. La fonction @ref{2d8f,,ctypes.set_errno()} affecte une nouvelle valeur à la copie privée et renvoie l'ancienne valeur.

The `use_last_error' parameter, when set to true, enables the same mechanism for
the Windows error code which is managed by the @ref{2d61,,GetLastError()} and
@code{SetLastError()} Windows API functions; @ref{2d90,,ctypes.get_last_error()} and
@ref{2d91,,ctypes.set_last_error()} are used to request and change the ctypes private
copy of the windows error code.

The `winmode' parameter is used on Windows to specify how the library is loaded
(since `mode' is ignored). It takes any value that is valid for the Win32 API
@code{LoadLibraryEx} flags parameter. When omitted, the default is to use the
flags that result in the most secure DLL load, which avoids issues such as DLL
hijacking. Passing the full path to the DLL is the safest way to ensure the
correct library and dependencies are loaded.


Modifié dans la version 3.8: Ajout du paramètre `winmode'.



@deffn {Données} ctypes.RTLD_GLOBAL

Valeur possible pour le paramètre `mode'. Vaut zéro sur les plates-formes où ce drapeau n'est pas disponible.
@end deffn


@deffn {Données} ctypes.RTLD_LOCAL

Valeur possible pour le paramètre `mode'. Vaut `RTLD_GLOBAL' sur les plates-formes où ce drapeau n'est pas disponible.
@end deffn


@deffn {Données} ctypes.DEFAULT_MODE

Mode de chargement par défaut des bibliothèques partagées. Vaut `RTLD_GLOBAL' sur OSX 10.3 et `RTLD_LOCAL' sur les autres systèmes d'exploitation.
@end deffn

Les instances de ces classes n'ont pas de méthodes publiques ; on accède aux fonctions de la bibliothèque partagée par attribut ou par indiçage. Notez que les résultats des accès par attribut sont mis en cache, et donc des accès consécutifs renvoient à chaque fois le même objet. Accéder à une fonction par indice renvoie cependant chaque fois un nouvel objet :

@example
>>> from ctypes import CDLL
>>> libc = CDLL("libc.so.6")  # On Linux
>>> libc.time == libc.time
True
>>> libc['time'] == libc['time']
False
@end example

Les attributs publics suivants sont disponibles, leur nom commence par un tiret bas pour éviter les conflits avec les noms des fonctions exportées :

@geindex _handle (attribut ctypes.PyDLL)
@anchor{library/ctypes ctypes PyDLL _handle}@anchor{2d92}
@deffn {Attribut} PyDLL._handle

Le lien système d'accès à la bibliothèque.
@end deffn

@geindex _name (attribut ctypes.PyDLL)
@anchor{library/ctypes ctypes PyDLL _name}@anchor{2d93}
@deffn {Attribut} PyDLL._name

Nom de la bibliothèque donné au constructeur.
@end deffn

Shared libraries can also be loaded by using one of the prefabricated objects,
which are instances of the @ref{2d94,,LibraryLoader} class, either by calling the
@ref{2d41,,LoadLibrary()} method, or by retrieving the library as
attribute of the loader instance.

@geindex LibraryLoader (classe dans ctypes)
@anchor{library/ctypes ctypes LibraryLoader}@anchor{2d94}
@deffn {Classe} ctypes.LibraryLoader (dlltype)

Classe pour charger une bibliothèque partagée. `dlltype' doit être de type @ref{9d7,,CDLL}, @ref{1702,,PyDLL}, @ref{1701,,WinDLL} ou @ref{1700,,OleDLL}.

@code{__getattr__()} has special behavior: It allows loading a shared library by
accessing it as attribute of a library loader instance.  The result is cached,
so repeated attribute accesses return the same library each time.

@geindex LoadLibrary() (méthode ctypes.LibraryLoader)
@anchor{library/ctypes ctypes LibraryLoader LoadLibrary}@anchor{2d41}
@deffn {Méthode} LoadLibrary (name)

Charge une bibliothèque partagée dans le processus et la renvoie. Cette méthode renvoie toujours une nouvelle instance de la bibliothèque.
@end deffn
@end deffn

Plusieurs chargeurs sont fournis :


@deffn {Données} ctypes.cdll

Pour créer des instances de @ref{9d7,,CDLL}.
@end deffn


@deffn {Données} ctypes.windll

Creates @ref{1701,,WinDLL} instances.

@ref{1ce0,,Availability}: Windows
@end deffn


@deffn {Données} ctypes.oledll

Creates @ref{1700,,OleDLL} instances.

@ref{1ce0,,Availability}: Windows
@end deffn


@deffn {Données} ctypes.pydll

Pour créer des instances de @ref{1702,,PyDLL}.
@end deffn

Il existe un moyen rapide d'accéder directement à l'API C Python :


@deffn {Données} ctypes.pythonapi

An instance of @ref{1702,,PyDLL} that exposes Python C API functions as
attributes.  Note that all these functions are assumed to return C
int, which is of course not always the truth, so you have to assign
the correct @code{restype} attribute to use these functions.
@end deffn

Charger une bibliothèque à l'aide d'un de ces objets avec en argument @code{name}, le nom de la bibliothèque (une chaîne de caractères), lève un @ref{1848,,évènement d'audit} @code{ctypes.dlopen}.

Accéder à une fonction d'une bibliothèque lève un évènement d'audit @code{ctypes.dlsym} avec @code{library} (l'objet bibliothèque) et @code{name} (le nom du symbole — une chaîne de caractères ou un entier) comme arguments.

Si seul le lien sur la bibliothèque, et non l'objet, est disponible, accéder à une fonction lève l'évènement d'audit @code{ctypes.dlsym/handle} avec @code{handle} (le lien vers la bibliothèque) et @code{name} comme arguments.

@node Fonctions externes,Prototypes de fonction,Chargement des bibliothèques partagées,Référence du module
@anchor{library/ctypes ctypes-foreign-functions}@anchor{2d95}@anchor{library/ctypes foreign-functions}@anchor{2d96}
@subsubsection Fonctions externes


As explained in the previous section, foreign functions can be accessed as
attributes of loaded shared libraries.  The function objects created in this way
by default accept any number of arguments, accept any ctypes data instances as
arguments, and return the default result type specified by the library loader.

They are instances of a private local class @code{_FuncPtr} (not exposed
in @code{ctypes}) which inherits from the private @ref{2d97,,_CFuncPtr} class:

@example
>>> import ctypes
>>> lib = ctypes.CDLL(None)
>>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)
True
>>> lib._FuncPtr is ctypes._CFuncPtr
False
@end example

@geindex _CFuncPtr (classe dans ctypes)
@anchor{library/ctypes ctypes _CFuncPtr}@anchor{2d97}
@deffn {Classe} ctypes._CFuncPtr

Classe de base pour les fonctions externes C.

Une instance de fonction externe est également un type de donnée compatible avec le C ; elle représente un pointeur vers une fonction.

Son comportement peut-être personnalisé en réaffectant les attributs spécifiques de l'objet représentant la fonction externe.

@geindex restype (attribut ctypes._CFuncPtr)
@anchor{library/ctypes ctypes _CFuncPtr restype}@anchor{2d60}
@deffn {Attribut} restype

Assign a ctypes type to specify the result type of the foreign function.
Use @code{None} for void, a function not returning anything.

It is possible to assign a callable Python object that is not a ctypes
type, in this case the function is assumed to return a C int, and
the callable will be called with this integer, allowing further
processing or error checking.  Using this is deprecated, for more flexible
post processing or error checking use a ctypes data type as
@code{restype} and assign a callable to the @ref{2d62,,errcheck} attribute.
@end deffn

@geindex argtypes (attribut ctypes._CFuncPtr)
@anchor{library/ctypes ctypes _CFuncPtr argtypes}@anchor{2d58}
@deffn {Attribut} argtypes

Fait correspondre le type des arguments que la fonction accepte avec un `n'-uplet de types `ctypes'. Les fonctions qui utilisent la convention d'appel @code{stdcall} ne peuvent être appelées qu'avec le même nombre d'arguments que la taille du `n'-uplet mais les fonctions qui utilisent la convention d'appel C acceptent aussi des arguments additionnels non-définis.

When a foreign function is called, each actual argument is passed to the
@ref{2d5d,,from_param()} class method of the items in the @ref{2d58,,argtypes}
tuple, this method allows adapting the actual argument to an object that
the foreign function accepts.  For example, a @ref{1670,,c_char_p} item in
the @ref{2d58,,argtypes} tuple will convert a string passed as argument into
a bytes object using ctypes conversion rules.

New: It is now possible to put items in argtypes which are not ctypes
types, but each item must have a @ref{2d5d,,from_param()} method which returns a
value usable as argument (integer, string, ctypes instance).  This allows
defining adapters that can adapt custom objects as function parameters.
@end deffn

@geindex errcheck (attribut ctypes._CFuncPtr)
@anchor{library/ctypes ctypes _CFuncPtr errcheck}@anchor{2d62}
@deffn {Attribut} errcheck

Définit une fonction Python ou tout autre appelable qui sera appelé avec trois arguments ou plus :


@deffn {Fonction} callable (result, func, arguments)

`result' is what the foreign function returns, as specified by the
@code{restype} attribute.

`func' est l'objet représentant la fonction externe elle-même. Cet accesseur permet de réutiliser le même appelable pour vérifier le résultat de plusieurs fonctions ou de faire des actions supplémentaires après leur exécution.

`arguments' est le `n'-uplet qui contient les paramètres initiaux passés à la fonction, ceci permet de spécialiser le comportement des arguments utilisés.
@end deffn

L'objet renvoyé par cette fonction est celui renvoyé par l'appel de la fonction externe, mais il peut aussi vérifier la valeur du résultat et lever une exception si l'appel a échoué.
@end deffn
@end deffn

@geindex ArgumentError
@anchor{library/ctypes ctypes ArgumentError}@anchor{2d98}
@deffn {Exception} ctypes.ArgumentError

Exception levée quand un appel à la fonction externe ne peut pas convertir un des arguments qu'elle a reçus.
@end deffn


On Windows, when a foreign function call raises a system exception (for
example, due to an access violation), it will be captured and replaced with
a suitable Python exception. Further, an auditing event
@code{ctypes.set_exception} with argument @code{code} will be raised, allowing an
audit hook to replace the exception with its own.


Certaines manières d'appeler des fonction externes peuvent lever des évènements d'audit @code{ctypes.call_function} avec @code{function pointer} et @code{arguments} comme arguments.

@node Prototypes de fonction,Fonctions utilitaires,Fonctions externes,Référence du module
@anchor{library/ctypes ctypes-function-prototypes}@anchor{2d99}@anchor{library/ctypes function-prototypes}@anchor{2d9a}
@subsubsection Prototypes de fonction


Il est aussi possible de créer des fonctions externes en instanciant des prototypes de fonction. Les prototypes de fonction ressemblent beaucoup aux prototypes de fonctions en C ; ils décrivent une fonction (type de retour, type des arguments, convention d'appel) sans préciser son implémentation. Les fabriques de fonctions prennent en entrée le type de retour et le type des arguments de la fonction, et peuvent être utilisées comme des décorateurs-fabrique et ainsi s'appliquer à des fonctions avec la syntaxe @code{@@décorateur}. Ceci est illustré dans la section @ref{2d7b,,Fonctions de rappel}.

@geindex CFUNCTYPE() (dans le module ctypes)
@anchor{library/ctypes ctypes CFUNCTYPE}@anchor{2d7c}
@deffn {Fonction} ctypes.CFUNCTYPE (restype, *argtypes, use_errno=False, use_last_error=False)

Renvoie un prototype de fonction qui crée des fonctions qui suivent la convention d'appel standard C. Les fonctions libèreront le GIL lors de leur exécution. Si `use_errno' est vrai, la copie privée `ctypes' de la variable système @ref{56,,errno} est échangée avec la vraie valeur de @ref{56,,errno} avant et après l'appel ; `use_last_error' a le même effet sous Windows.
@end deffn

@geindex WINFUNCTYPE() (dans le module ctypes)
@anchor{library/ctypes ctypes WINFUNCTYPE}@anchor{2d7d}
@deffn {Fonction} ctypes.WINFUNCTYPE (restype, *argtypes, use_errno=False, use_last_error=False)

The returned function prototype creates functions that use the
@code{stdcall} calling convention.  The function will
release the GIL during the call.  `use_errno' and `use_last_error' have the
same meaning as above.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex PYFUNCTYPE() (dans le module ctypes)
@anchor{library/ctypes ctypes PYFUNCTYPE}@anchor{2d9b}
@deffn {Fonction} ctypes.PYFUNCTYPE (restype, *argtypes)

Renvoie un prototype de fonction qui crée des fonctions qui suivent la convention d'appel Python. Les fonctions ne libèreront `pas' le GIL lors de leur exécution.
@end deffn

Il y a plusieurs façons d'instancier les prototypes de fonction créés par ces fabriques, selon le type et le nombre de paramètres de l'appel :


@deffn {Fonction} prototype (address)

Renvoie une fonction externe sur l'adresse donnée sous la forme d'un entier.
@end deffn


@deffn {Fonction} prototype (callable)

Crée une fonction appelable depuis du code C (une fonction de rappel) d'un appelable Python donné en paramètre.
@end deffn


@deffn {Fonction} prototype (func_spec[, paramflags])

Renvoie une fonction externe exposée par une bibliothèque partagée. `func_spec' est un couple @code{(nom_ou_indice, bibliothèque)}. Le premier élément est le nom de la fonction à passer comme une chaîne ou bien son indice (dans la table des symboles) à passer comme un entier. Le second élément est l'instance de la bibliothèque partagée.
@end deffn


@deffn {Fonction} prototype (vtbl_index, name[, paramflags[, iid]])

Renvoie une fonction qui appelle une méthode COM. `vtbl_index' est l'indice de la fonction dans la table virtuelle, un petit entier positif. `name' est le nom de la méthode COM. `iid' est un pointeur optionnel vers l'identificateur de plateforme, qui est utilisé dans la remontée d'erreurs étendue.

COM methods use a special calling convention: They require a pointer to
the COM interface as first argument, in addition to those parameters that
are specified in the @code{argtypes} tuple.
@end deffn

Le paramètre optionnel `paramflags' crée une fabrique de fonction externes avec des fonctionnalités supplémentaires par rapport à celles décrites ci-dessus.

`paramflags' must be a tuple of the same length as @ref{2d58,,argtypes}.

Chaque élément de ce `n'-uplet contient des informations supplémentaires sur le paramètre correspondant. Ce doit être aussi un `n'-uplet, avec un, deux ou trois éléments.

Le premier élément est un entier qui contient une combinaison de drapeaux qui précisent le sens des paramètres (entrée ou sortie) :

@quotation


@table @asis

@item 1

Paramètre d'entrée.

@item 2

Paramètre de sortie. La fonction externe va modifier cette valeur.

@item 4

Paramètre d'entrée, valant 0 par défaut.
@end table
@end quotation

Le deuxième élément (optionnel) est une chaîne de caractères représentant le nom du paramètre. Si cet élément est donné, la fonction externe pourra être appelée avec des paramètres nommés.

Le troisième élément (optionnel) est la valeur par défaut du paramètre.

The following example demonstrates how to wrap the Windows @code{MessageBoxW} function so
that it supports default parameters and named arguments. The C declaration from
the windows header file is this:

@example
WINUSERAPI int WINAPI
MessageBoxW(
    HWND hWnd,
    LPCWSTR lpText,
    LPCWSTR lpCaption,
    UINT uType);
@end example

L'encapsulation @ref{2a,,ctypes} correspondante est alors :

@example
>>> from ctypes import c_int, WINFUNCTYPE, windll
>>> from ctypes.wintypes import HWND, LPCWSTR, UINT
>>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)
>>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", "Hello from ctypes"), (1, "flags", 0)
>>> MessageBox = prototype(("MessageBoxW", windll.user32), paramflags)
@end example

La fonction @code{MessageBox} peut désormais être appelée des manières suivantes :

@example
>>> MessageBox()
>>> MessageBox(text="Spam, spam, spam")
>>> MessageBox(flags=2, text="foo bar")
@end example

L'exemple qui suit traite des paramètres en sortie. La fonction win32 @code{GetWindowRect} donne les dimensions d'une fenêtre en les copiant dans une structure @code{RECT} que l'appelant doit fournir. Sa déclaration en C est :

@example
WINUSERAPI BOOL WINAPI
GetWindowRect(
     HWND hWnd,
     LPRECT lpRect);
@end example

L'encapsulation @ref{2a,,ctypes} correspondante est alors :

@example
>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
>>> from ctypes.wintypes import BOOL, HWND, RECT
>>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
>>> paramflags = (1, "hwnd"), (2, "lprect")
>>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
>>>
@end example

Les fonctions avec des paramètres en sortie renvoient automatiquement la valeur du paramètre de sortie s'il n'y en a qu'un seul, ou un `n'-uplet avec les valeurs de sortie de chaque paramètre s'il y en a plusieurs. Ici, la fonction `GetWindowRect' renvoie donc une instance de `RECT' quand elle est appelée.

Output parameters can be combined with the @ref{2d62,,errcheck} protocol to do
further output processing and error checking.  The win32 @code{GetWindowRect} api
function returns a @code{BOOL} to signal success or failure, so this function could
do the error checking, and raises an exception when the api call failed:

@example
>>> def errcheck(result, func, args):
...     if not result:
...         raise WinError()
...     return args
...
>>> GetWindowRect.errcheck = errcheck
>>>
@end example

If the @ref{2d62,,errcheck} function returns the argument tuple it receives
unchanged, @ref{2a,,ctypes} continues the normal processing it does on the output
parameters.  If you want to return a tuple of window coordinates instead of a
@code{RECT} instance, you can retrieve the fields in the function and return them
instead, the normal processing will no longer take place:

@example
>>> def errcheck(result, func, args):
...     if not result:
...         raise WinError()
...     rc = args[1]
...     return rc.left, rc.top, rc.bottom, rc.right
...
>>> GetWindowRect.errcheck = errcheck
>>>
@end example

@node Fonctions utilitaires,Types de données<3>,Prototypes de fonction,Référence du module
@anchor{library/ctypes ctypes-utility-functions}@anchor{2d9c}@anchor{library/ctypes utility-functions}@anchor{2d9d}
@subsubsection Fonctions utilitaires


@geindex addressof() (dans le module ctypes)
@anchor{library/ctypes ctypes addressof}@anchor{2d9e}
@deffn {Fonction} ctypes.addressof (obj)

Returns the address of the memory buffer as integer.  `obj' must be an
instance of a ctypes type.

Raises an @ref{1848,,auditing event} @code{ctypes.addressof} with argument @code{obj}.
@end deffn

@geindex alignment() (dans le module ctypes)
@anchor{library/ctypes ctypes alignment}@anchor{2d9f}
@deffn {Fonction} ctypes.alignment (obj_or_type)

Returns the alignment requirements of a ctypes type. `obj_or_type' must be a
ctypes type or instance.
@end deffn

@geindex byref() (dans le module ctypes)
@anchor{library/ctypes ctypes byref}@anchor{2d65}
@deffn {Fonction} ctypes.byref (obj[, offset])

Returns a light-weight pointer to `obj', which must be an instance of a
ctypes type.  `offset' defaults to zero, and must be an integer that will be
added to the internal pointer value.

@code{byref(obj, offset)} corresponds to this C code:

@example
(((char *)&obj) + offset)
@end example

The returned object can only be used as a foreign function call parameter.
It behaves similar to @code{pointer(obj)}, but the construction is a lot faster.
@end deffn

@geindex cast() (dans le module ctypes)
@anchor{library/ctypes ctypes cast}@anchor{2d77}
@deffn {Fonction} ctypes.cast (obj, type)

This function is similar to the cast operator in C. It returns a new instance
of `type' which points to the same memory block as `obj'.  `type' must be a
pointer type, and `obj' must be an object that can be interpreted as a
pointer.
@end deffn

@geindex create_string_buffer() (dans le module ctypes)
@anchor{library/ctypes ctypes create_string_buffer}@anchor{2d53}
@deffn {Fonction} ctypes.create_string_buffer (init_or_size, size=None)

This function creates a mutable character buffer. The returned object is a
ctypes array of @ref{2d49,,c_char}.

`init_or_size' must be an integer which specifies the size of the array, or a
bytes object which will be used to initialize the array items.

If a bytes object is specified as first argument, the buffer is made one item
larger than its length so that the last element in the array is a NUL
termination character. An integer can be passed as second argument which allows
specifying the size of the array if the length of the bytes should not be used.

Raises an @ref{1848,,auditing event} @code{ctypes.create_string_buffer} with arguments @code{init}, @code{size}.
@end deffn

@geindex create_unicode_buffer() (dans le module ctypes)
@anchor{library/ctypes ctypes create_unicode_buffer}@anchor{195d}
@deffn {Fonction} ctypes.create_unicode_buffer (init_or_size, size=None)

This function creates a mutable unicode character buffer. The returned object is
a ctypes array of @ref{2d4a,,c_wchar}.

`init_or_size' must be an integer which specifies the size of the array, or a
string which will be used to initialize the array items.

If a string is specified as first argument, the buffer is made one item
larger than the length of the string so that the last element in the array is a
NUL termination character. An integer can be passed as second argument which
allows specifying the size of the array if the length of the string should not
be used.

Raises an @ref{1848,,auditing event} @code{ctypes.create_unicode_buffer} with arguments @code{init}, @code{size}.
@end deffn

@geindex DllCanUnloadNow() (dans le module ctypes)
@anchor{library/ctypes ctypes DllCanUnloadNow}@anchor{2da0}
@deffn {Fonction} ctypes.DllCanUnloadNow ()

This function is a hook which allows implementing in-process
COM servers with ctypes.  It is called from the DllCanUnloadNow function that
the _ctypes extension dll exports.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex DllGetClassObject() (dans le module ctypes)
@anchor{library/ctypes ctypes DllGetClassObject}@anchor{2da1}
@deffn {Fonction} ctypes.DllGetClassObject ()

This function is a hook which allows implementing in-process
COM servers with ctypes.  It is called from the DllGetClassObject function
that the @code{_ctypes} extension dll exports.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex find_library() (dans le module ctypes.util)
@anchor{library/ctypes ctypes util find_library}@anchor{d37}
@deffn {Fonction} ctypes.util.find_library (name)

Try to find a library and return a pathname.  `name' is the library name
without any prefix like @code{lib}, suffix like @code{.so}, @code{.dylib} or version
number (this is the form used for the posix linker option @code{-l}).  If
no library can be found, returns @code{None}.

Le mode opératoire exact dépend du système.
@end deffn

@geindex find_msvcrt() (dans le module ctypes.util)
@anchor{library/ctypes ctypes util find_msvcrt}@anchor{2da2}
@deffn {Fonction} ctypes.util.find_msvcrt ()

Returns the filename of the VC runtime library used by Python,
and by the extension modules.  If the name of the library cannot be
determined, @code{None} is returned.

If you need to free memory, for example, allocated by an extension module
with a call to the @code{free(void *)}, it is important that you use the
function in the same library that allocated the memory.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex FormatError() (dans le module ctypes)
@anchor{library/ctypes ctypes FormatError}@anchor{2da3}
@deffn {Fonction} ctypes.FormatError ([code])

Returns a textual description of the error code `code'.  If no
error code is specified, the last error code is used by calling the Windows
api function GetLastError.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex GetLastError() (dans le module ctypes)
@anchor{library/ctypes ctypes GetLastError}@anchor{2d61}
@deffn {Fonction} ctypes.GetLastError ()

Returns the last error code set by Windows in the calling thread.
This function calls the Windows @code{GetLastError()} function directly,
it does not return the ctypes-private copy of the error code.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex get_errno() (dans le module ctypes)
@anchor{library/ctypes ctypes get_errno}@anchor{2d8e}
@deffn {Fonction} ctypes.get_errno ()

Returns the current value of the ctypes-private copy of the system
@ref{56,,errno} variable in the calling thread.

Raises an @ref{1848,,auditing event} @code{ctypes.get_errno} with no arguments.
@end deffn

@geindex get_last_error() (dans le module ctypes)
@anchor{library/ctypes ctypes get_last_error}@anchor{2d90}
@deffn {Fonction} ctypes.get_last_error ()

Returns the current value of the ctypes-private copy of the system
@code{LastError} variable in the calling thread.

@ref{1ce0,,Availability}: Windows

Raises an @ref{1848,,auditing event} @code{ctypes.get_last_error} with no arguments.
@end deffn

@geindex memmove() (dans le module ctypes)
@anchor{library/ctypes ctypes memmove}@anchor{2da4}
@deffn {Fonction} ctypes.memmove (dst, src, count)

Same as the standard C memmove library function: copies `count' bytes from
`src' to `dst'. `dst' and `src' must be integers or ctypes instances that can
be converted to pointers.
@end deffn

@geindex memset() (dans le module ctypes)
@anchor{library/ctypes ctypes memset}@anchor{2da5}
@deffn {Fonction} ctypes.memset (dst, c, count)

Same as the standard C memset library function: fills the memory block at
address `dst' with `count' bytes of value `c'. `dst' must be an integer
specifying an address, or a ctypes instance.
@end deffn

@geindex POINTER() (dans le module ctypes)
@anchor{library/ctypes ctypes POINTER}@anchor{166f}
@deffn {Fonction} ctypes.POINTER (type, /)

Create and return a new ctypes pointer type. Pointer types are cached and
reused internally, so calling this function repeatedly is cheap.
`type' must be a ctypes type.
@end deffn

@geindex pointer() (dans le module ctypes)
@anchor{library/ctypes ctypes pointer}@anchor{166e}
@deffn {Fonction} ctypes.pointer (obj, /)

Create a new pointer instance, pointing to `obj'.
The returned object is of the type @code{POINTER(type(obj))}.

Note: If you just want to pass a pointer to an object to a foreign function
call, you should use @code{byref(obj)} which is much faster.
@end deffn

@geindex resize() (dans le module ctypes)
@anchor{library/ctypes ctypes resize}@anchor{2d86}
@deffn {Fonction} ctypes.resize (obj, size)

This function resizes the internal memory buffer of `obj', which must be an
instance of a ctypes type.  It is not possible to make the buffer smaller
than the native size of the objects type, as given by @code{sizeof(type(obj))},
but it is possible to enlarge the buffer.
@end deffn

@geindex set_errno() (dans le module ctypes)
@anchor{library/ctypes ctypes set_errno}@anchor{2d8f}
@deffn {Fonction} ctypes.set_errno (value)

Set the current value of the ctypes-private copy of the system @ref{56,,errno}
variable in the calling thread to `value' and return the previous value.

Raises an @ref{1848,,auditing event} @code{ctypes.set_errno} with argument @code{errno}.
@end deffn

@geindex set_last_error() (dans le module ctypes)
@anchor{library/ctypes ctypes set_last_error}@anchor{2d91}
@deffn {Fonction} ctypes.set_last_error (value)

Sets the current value of the ctypes-private copy of the system
@code{LastError} variable in the calling thread to `value' and return the
previous value.

@ref{1ce0,,Availability}: Windows

Raises an @ref{1848,,auditing event} @code{ctypes.set_last_error} with argument @code{error}.
@end deffn

@geindex sizeof() (dans le module ctypes)
@anchor{library/ctypes ctypes sizeof}@anchor{2da6}
@deffn {Fonction} ctypes.sizeof (obj_or_type)

Returns the size in bytes of a ctypes type or instance memory buffer.
Does the same as the C @code{sizeof} operator.
@end deffn

@geindex string_at() (dans le module ctypes)
@anchor{library/ctypes ctypes string_at}@anchor{2da7}
@deffn {Fonction} ctypes.string_at (ptr, size=-1)

Return the byte string at `void *ptr'.
If `size' is specified, it is used as size, otherwise the string is assumed
to be zero-terminated.

Raises an @ref{1848,,auditing event} @code{ctypes.string_at} with arguments @code{ptr}, @code{size}.
@end deffn

@geindex WinError() (dans le module ctypes)
@anchor{library/ctypes ctypes WinError}@anchor{2da8}
@deffn {Fonction} ctypes.WinError (code=None, descr=None)

This function is probably the worst-named thing in ctypes. It
creates an instance of @ref{40d,,OSError}.  If `code' is not specified,
@code{GetLastError} is called to determine the error code. If `descr' is not
specified, @ref{2da3,,FormatError()} is called to get a textual description of the
error.

@ref{1ce0,,Availability}: Windows


Modifié dans la version 3.3: An instance of @ref{103d,,WindowsError} used to be created, which is now an
alias of @ref{40d,,OSError}.

@end deffn

@geindex wstring_at() (dans le module ctypes)
@anchor{library/ctypes ctypes wstring_at}@anchor{2da9}
@deffn {Fonction} ctypes.wstring_at (ptr, size=-1)

Return the wide-character string at `void *ptr'.
If `size' is specified, it is used as the number of
characters of the string, otherwise the string is assumed to be
zero-terminated.

Raises an @ref{1848,,auditing event} @code{ctypes.wstring_at} with arguments @code{ptr}, @code{size}.
@end deffn

@node Types de données<3>,Types de données de base<2>,Fonctions utilitaires,Référence du module
@anchor{library/ctypes ctypes-data-types}@anchor{2daa}@anchor{library/ctypes data-types}@anchor{2dab}
@subsubsection Types de données


@geindex _CData (classe dans ctypes)
@anchor{library/ctypes ctypes _CData}@anchor{2dac}
@deffn {Classe} ctypes._CData

This non-public class is the common base class of all ctypes data types.
Among other things, all ctypes type instances contain a memory block that
hold C compatible data; the address of the memory block is returned by the
@ref{2d9e,,addressof()} helper function. Another instance variable is exposed as
@ref{2dad,,_objects}; this contains other Python objects that need to be kept
alive in case the memory block contains pointers.

Common methods of ctypes data types, these are all class methods (to be
exact, they are methods of the @ref{1f09,,metaclass}):

@geindex from_buffer() (méthode ctypes._CData)
@anchor{library/ctypes ctypes _CData from_buffer}@anchor{2dae}
@deffn {Méthode} from_buffer (source[, offset])

This method returns a ctypes instance that shares the buffer of the
`source' object.  The `source' object must support the writeable buffer
interface.  The optional `offset' parameter specifies an offset into the
source buffer in bytes; the default is zero.  If the source buffer is not
large enough a @ref{1ff,,ValueError} is raised.

Raises an @ref{1848,,auditing event} @code{ctypes.cdata/buffer} with arguments @code{pointer}, @code{size}, @code{offset}.
@end deffn

@geindex from_buffer_copy() (méthode ctypes._CData)
@anchor{library/ctypes ctypes _CData from_buffer_copy}@anchor{2daf}
@deffn {Méthode} from_buffer_copy (source[, offset])

This method creates a ctypes instance, copying the buffer from the
`source' object buffer which must be readable.  The optional `offset'
parameter specifies an offset into the source buffer in bytes; the default
is zero.  If the source buffer is not large enough a @ref{1ff,,ValueError} is
raised.

Raises an @ref{1848,,auditing event} @code{ctypes.cdata/buffer} with arguments @code{pointer}, @code{size}, @code{offset}.
@end deffn

@geindex from_address() (méthode ctypes._CData)
@anchor{library/ctypes ctypes _CData from_address}@anchor{2db0}
@deffn {Méthode} from_address (address)

This method returns a ctypes type instance using the memory specified by
`address' which must be an integer.


This method, and others that indirectly call this method, raises an
@ref{1848,,auditing event} @code{ctypes.cdata} with argument
@code{address}.

@end deffn

@geindex from_param() (méthode ctypes._CData)
@anchor{library/ctypes ctypes _CData from_param}@anchor{2d5d}
@deffn {Méthode} from_param (obj)

This method adapts `obj' to a ctypes type.  It is called with the actual
object used in a foreign function call when the type is present in the
foreign function's @ref{2d58,,argtypes} tuple;
it must return an object that can be used as a function call parameter.

All ctypes data types have a default implementation of this classmethod
that normally returns `obj' if that is an instance of the type.  Some
types accept other objects as well.
@end deffn

@geindex in_dll() (méthode ctypes._CData)
@anchor{library/ctypes ctypes _CData in_dll}@anchor{2d80}
@deffn {Méthode} in_dll (library, name)

This method returns a ctypes type instance exported by a shared
library. `name' is the name of the symbol that exports the data, `library'
is the loaded shared library.
@end deffn

Common instance variables of ctypes data types:

@geindex _b_base_ (attribut ctypes._CData)
@anchor{library/ctypes ctypes _CData _b_base_}@anchor{2db1}
@deffn {Attribut} _b_base_

Sometimes ctypes data instances do not own the memory block they contain,
instead they share part of the memory block of a base object.  The
@ref{2db1,,_b_base_} read-only member is the root ctypes object that owns the
memory block.
@end deffn

@geindex _b_needsfree_ (attribut ctypes._CData)
@anchor{library/ctypes ctypes _CData _b_needsfree_}@anchor{2db2}
@deffn {Attribut} _b_needsfree_

This read-only variable is true when the ctypes data instance has
allocated the memory block itself, false otherwise.
@end deffn

@geindex _objects (attribut ctypes._CData)
@anchor{library/ctypes ctypes _CData _objects}@anchor{2dad}
@deffn {Attribut} _objects

This member is either @code{None} or a dictionary containing Python objects
that need to be kept alive so that the memory block contents is kept
valid.  This object is only exposed for debugging; never modify the
contents of this dictionary.
@end deffn
@end deffn

@node Types de données de base<2>,Types de données dérivés de Structure,Types de données<3>,Référence du module
@anchor{library/ctypes ctypes-fundamental-data-types-2}@anchor{2db3}@anchor{library/ctypes id1}@anchor{2db4}
@subsubsection Types de données de base


@geindex _SimpleCData (classe dans ctypes)
@anchor{library/ctypes ctypes _SimpleCData}@anchor{2db5}
@deffn {Classe} ctypes._SimpleCData

This non-public class is the base class of all fundamental ctypes data
types. It is mentioned here because it contains the common attributes of the
fundamental ctypes data types.  @ref{2db5,,_SimpleCData} is a subclass of
@ref{2dac,,_CData}, so it inherits their methods and attributes. ctypes data
types that are not and do not contain pointers can now be pickled.

Instances have a single attribute:

@geindex value (attribut ctypes._SimpleCData)
@anchor{library/ctypes ctypes _SimpleCData value}@anchor{2db6}
@deffn {Attribut} value

This attribute contains the actual value of the instance. For integer and
pointer types, it is an integer, for character types, it is a single
character bytes object or string, for character pointer types it is a
Python bytes object or string.

When the @code{value} attribute is retrieved from a ctypes instance, usually
a new object is returned each time.  @ref{2a,,ctypes} does `not' implement
original object return, always a new object is constructed.  The same is
true for all other ctypes object instances.
@end deffn
@end deffn

Fundamental data types, when returned as foreign function call results, or, for
example, by retrieving structure field members or array items, are transparently
converted to native Python types.  In other words, if a foreign function has a
@ref{2d60,,restype} of @ref{1670,,c_char_p}, you will always receive a Python bytes
object, `not' a @ref{1670,,c_char_p} instance.

@c XXX above is false, it actually returns a Unicode string

Subclasses of fundamental data types do `not' inherit this behavior. So, if a
foreign functions @code{restype} is a subclass of @ref{1672,,c_void_p}, you will
receive an instance of this subclass from the function call. Of course, you can
get the value of the pointer by accessing the @code{value} attribute.

These are the fundamental ctypes data types:

@geindex c_byte (classe dans ctypes)
@anchor{library/ctypes ctypes c_byte}@anchor{16fe}
@deffn {Classe} ctypes.c_byte

Represents the C signed char datatype, and interprets the value as
small integer.  The constructor accepts an optional integer initializer; no
overflow checking is done.
@end deffn

@geindex c_char (classe dans ctypes)
@anchor{library/ctypes ctypes c_char}@anchor{2d49}
@deffn {Classe} ctypes.c_char

Represents the C char datatype, and interprets the value as a single
character.  The constructor accepts an optional string initializer, the
length of the string must be exactly one character.
@end deffn

@geindex c_char_p (classe dans ctypes)
@anchor{library/ctypes ctypes c_char_p}@anchor{1670}
@deffn {Classe} ctypes.c_char_p

Represents the C char* datatype when it points to a zero-terminated
string.  For a general character pointer that may also point to binary data,
@code{POINTER(c_char)} must be used.  The constructor accepts an integer
address, or a bytes object.
@end deffn

@geindex c_double (classe dans ctypes)
@anchor{library/ctypes ctypes c_double}@anchor{1888}
@deffn {Classe} ctypes.c_double

Represents the C double datatype.  The constructor accepts an
optional float initializer.
@end deffn

@geindex c_longdouble (classe dans ctypes)
@anchor{library/ctypes ctypes c_longdouble}@anchor{1889}
@deffn {Classe} ctypes.c_longdouble

Represents the C long double datatype.  The constructor accepts an
optional float initializer.  On platforms where @code{sizeof(long double) ==
sizeof(double)} it is an alias to @ref{1888,,c_double}.
@end deffn

@geindex c_float (classe dans ctypes)
@anchor{library/ctypes ctypes c_float}@anchor{2d52}
@deffn {Classe} ctypes.c_float

Represents the C float datatype.  The constructor accepts an
optional float initializer.
@end deffn

@geindex c_int (classe dans ctypes)
@anchor{library/ctypes ctypes c_int}@anchor{2d3d}
@deffn {Classe} ctypes.c_int

Represents the C signed int datatype.  The constructor accepts an
optional integer initializer; no overflow checking is done.  On platforms
where @code{sizeof(int) == sizeof(long)} it is an alias to @ref{2d3e,,c_long}.
@end deffn

@geindex c_int8 (classe dans ctypes)
@anchor{library/ctypes ctypes c_int8}@anchor{2db7}
@deffn {Classe} ctypes.c_int8

Represents the C 8-bit signed int datatype.  Usually an alias for
@ref{16fe,,c_byte}.
@end deffn

@geindex c_int16 (classe dans ctypes)
@anchor{library/ctypes ctypes c_int16}@anchor{2db8}
@deffn {Classe} ctypes.c_int16

Represents the C 16-bit signed int datatype.  Usually an alias for
@ref{2d4b,,c_short}.
@end deffn

@geindex c_int32 (classe dans ctypes)
@anchor{library/ctypes ctypes c_int32}@anchor{2db9}
@deffn {Classe} ctypes.c_int32

Represents the C 32-bit signed int datatype.  Usually an alias for
@ref{2d3d,,c_int}.
@end deffn

@geindex c_int64 (classe dans ctypes)
@anchor{library/ctypes ctypes c_int64}@anchor{2dba}
@deffn {Classe} ctypes.c_int64

Represents the C 64-bit signed int datatype.  Usually an alias for
@ref{2d4f,,c_longlong}.
@end deffn

@geindex c_long (classe dans ctypes)
@anchor{library/ctypes ctypes c_long}@anchor{2d3e}
@deffn {Classe} ctypes.c_long

Represents the C signed long datatype.  The constructor accepts an
optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_longlong (classe dans ctypes)
@anchor{library/ctypes ctypes c_longlong}@anchor{2d4f}
@deffn {Classe} ctypes.c_longlong

Represents the C signed long long datatype.  The constructor accepts
an optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_short (classe dans ctypes)
@anchor{library/ctypes ctypes c_short}@anchor{2d4b}
@deffn {Classe} ctypes.c_short

Represents the C signed short datatype.  The constructor accepts an
optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_size_t (classe dans ctypes)
@anchor{library/ctypes ctypes c_size_t}@anchor{2d51}
@deffn {Classe} ctypes.c_size_t

Represents the C @code{size_t} datatype.
@end deffn

@geindex c_ssize_t (classe dans ctypes)
@anchor{library/ctypes ctypes c_ssize_t}@anchor{121a}
@deffn {Classe} ctypes.c_ssize_t

Represents the C @code{ssize_t} datatype.


Ajouté dans la version 3.2.

@end deffn

@geindex c_time_t (classe dans ctypes)
@anchor{library/ctypes ctypes c_time_t}@anchor{1767}
@deffn {Classe} ctypes.c_time_t

Represents the C @code{time_t} datatype.


Ajouté dans la version 3.12.

@end deffn

@geindex c_ubyte (classe dans ctypes)
@anchor{library/ctypes ctypes c_ubyte}@anchor{16ff}
@deffn {Classe} ctypes.c_ubyte

Represents the C unsigned char datatype, it interprets the value as
small integer.  The constructor accepts an optional integer initializer; no
overflow checking is done.
@end deffn

@geindex c_uint (classe dans ctypes)
@anchor{library/ctypes ctypes c_uint}@anchor{2d4d}
@deffn {Classe} ctypes.c_uint

Represents the C unsigned int datatype.  The constructor accepts an
optional integer initializer; no overflow checking is done.  On platforms
where @code{sizeof(int) == sizeof(long)} it is an alias for @ref{2d4e,,c_ulong}.
@end deffn

@geindex c_uint8 (classe dans ctypes)
@anchor{library/ctypes ctypes c_uint8}@anchor{2dbb}
@deffn {Classe} ctypes.c_uint8

Represents the C 8-bit unsigned int datatype.  Usually an alias for
@ref{16ff,,c_ubyte}.
@end deffn

@geindex c_uint16 (classe dans ctypes)
@anchor{library/ctypes ctypes c_uint16}@anchor{2dbc}
@deffn {Classe} ctypes.c_uint16

Represents the C 16-bit unsigned int datatype.  Usually an alias for
@ref{2d4c,,c_ushort}.
@end deffn

@geindex c_uint32 (classe dans ctypes)
@anchor{library/ctypes ctypes c_uint32}@anchor{2dbd}
@deffn {Classe} ctypes.c_uint32

Represents the C 32-bit unsigned int datatype.  Usually an alias for
@ref{2d4d,,c_uint}.
@end deffn

@geindex c_uint64 (classe dans ctypes)
@anchor{library/ctypes ctypes c_uint64}@anchor{2dbe}
@deffn {Classe} ctypes.c_uint64

Represents the C 64-bit unsigned int datatype.  Usually an alias for
@ref{2d50,,c_ulonglong}.
@end deffn

@geindex c_ulong (classe dans ctypes)
@anchor{library/ctypes ctypes c_ulong}@anchor{2d4e}
@deffn {Classe} ctypes.c_ulong

Represents the C unsigned long datatype.  The constructor accepts an
optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_ulonglong (classe dans ctypes)
@anchor{library/ctypes ctypes c_ulonglong}@anchor{2d50}
@deffn {Classe} ctypes.c_ulonglong

Represents the C unsigned long long datatype.  The constructor
accepts an optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_ushort (classe dans ctypes)
@anchor{library/ctypes ctypes c_ushort}@anchor{2d4c}
@deffn {Classe} ctypes.c_ushort

Represents the C unsigned short datatype.  The constructor accepts
an optional integer initializer; no overflow checking is done.
@end deffn

@geindex c_void_p (classe dans ctypes)
@anchor{library/ctypes ctypes c_void_p}@anchor{1672}
@deffn {Classe} ctypes.c_void_p

Represents the C void* type.  The value is represented as integer.
The constructor accepts an optional integer initializer.
@end deffn

@geindex c_wchar (classe dans ctypes)
@anchor{library/ctypes ctypes c_wchar}@anchor{2d4a}
@deffn {Classe} ctypes.c_wchar

Represents the C @code{wchar_t} datatype, and interprets the value as a
single character unicode string.  The constructor accepts an optional string
initializer, the length of the string must be exactly one character.
@end deffn

@geindex c_wchar_p (classe dans ctypes)
@anchor{library/ctypes ctypes c_wchar_p}@anchor{1671}
@deffn {Classe} ctypes.c_wchar_p

Represents the C wchar_t* datatype, which must be a pointer to a
zero-terminated wide character string.  The constructor accepts an integer
address, or a string.
@end deffn

@geindex c_bool (classe dans ctypes)
@anchor{library/ctypes ctypes c_bool}@anchor{2d48}
@deffn {Classe} ctypes.c_bool

Represent the C bool datatype (more accurately, _Bool from
C99).  Its value can be @code{True} or @code{False}, and the constructor accepts any object
that has a truth value.
@end deffn

@geindex HRESULT (classe dans ctypes)
@anchor{library/ctypes ctypes HRESULT}@anchor{2d8d}
@deffn {Classe} ctypes.HRESULT

Represents a @code{HRESULT} value, which contains success or
error information for a function or method call.

@ref{1ce0,,Availability}: Windows
@end deffn

@geindex py_object (classe dans ctypes)
@anchor{library/ctypes ctypes py_object}@anchor{13ee}
@deffn {Classe} ctypes.py_object

Represents the C @ref{32f,,PyObject}* datatype.  Calling this without an
argument creates a @code{NULL} @ref{32f,,PyObject}* pointer.
@end deffn

The @code{ctypes.wintypes} module provides quite some other Windows specific
data types, for example @code{HWND}, @code{WPARAM}, or @code{DWORD}.
Some useful structures like @code{MSG} or @code{RECT} are also defined.

@node Types de données dérivés de Structure,Tableaux et pointeurs,Types de données de base<2>,Référence du module
@anchor{library/ctypes ctypes-structured-data-types}@anchor{2dbf}@anchor{library/ctypes structured-data-types}@anchor{2dc0}
@subsubsection Types de données dérivés de Structure


@geindex Union (classe dans ctypes)
@anchor{library/ctypes ctypes Union}@anchor{160a}
@deffn {Classe} ctypes.Union (*args, **kw)

Abstract base class for unions in native byte order.
@end deffn

@geindex BigEndianUnion (classe dans ctypes)
@anchor{library/ctypes ctypes BigEndianUnion}@anchor{17b4}
@deffn {Classe} ctypes.BigEndianUnion (*args, **kw)

Abstract base class for unions in `big endian' byte order.


Ajouté dans la version 3.11.

@end deffn

@geindex LittleEndianUnion (classe dans ctypes)
@anchor{library/ctypes ctypes LittleEndianUnion}@anchor{17b5}
@deffn {Classe} ctypes.LittleEndianUnion (*args, **kw)

Abstract base class for unions in `little endian' byte order.


Ajouté dans la version 3.11.

@end deffn

@geindex BigEndianStructure (classe dans ctypes)
@anchor{library/ctypes ctypes BigEndianStructure}@anchor{2d6c}
@deffn {Classe} ctypes.BigEndianStructure (*args, **kw)

Abstract base class for structures in `big endian' byte order.
@end deffn

@geindex LittleEndianStructure (classe dans ctypes)
@anchor{library/ctypes ctypes LittleEndianStructure}@anchor{2d6d}
@deffn {Classe} ctypes.LittleEndianStructure (*args, **kw)

Abstract base class for structures in `little endian' byte order.
@end deffn

Structures and unions with non-native byte order cannot contain pointer type
fields, or any other data types containing pointer type fields.

@geindex Structure (classe dans ctypes)
@anchor{library/ctypes ctypes Structure}@anchor{1cf}
@deffn {Classe} ctypes.Structure (*args, **kw)

Abstract base class for structures in `native' byte order.

Concrete structure and union types must be created by subclassing one of these
types, and at least define a @ref{2d68,,_fields_} class variable. @ref{2a,,ctypes} will
create @ref{1ef3,,descriptor}s which allow reading and writing the fields by direct
attribute accesses.  These are the

@geindex _fields_ (attribut ctypes.Structure)
@anchor{library/ctypes ctypes Structure _fields_}@anchor{2d68}
@deffn {Attribut} _fields_

A sequence defining the structure fields.  The items must be 2-tuples or
3-tuples.  The first item is the name of the field, the second item
specifies the type of the field; it can be any ctypes data type.

For integer type fields like @ref{2d3d,,c_int}, a third optional item can be
given.  It must be a small positive integer defining the bit width of the
field.

Field names must be unique within one structure or union.  This is not
checked, only one field can be accessed when names are repeated.

It is possible to define the @ref{2d68,,_fields_} class variable `after' the
class statement that defines the Structure subclass, this allows creating
data types that directly or indirectly reference themselves:

@example
class List(Structure):
    pass
List._fields_ = [("pnext", POINTER(List)),
                 ...
                ]
@end example

The @ref{2d68,,_fields_} class variable must, however, be defined before the
type is first used (an instance is created, @ref{2da6,,sizeof()} is called on it,
and so on).  Later assignments to the @ref{2d68,,_fields_} class variable will
raise an AttributeError.

It is possible to define sub-subclasses of structure types, they inherit
the fields of the base class plus the @ref{2d68,,_fields_} defined in the
sub-subclass, if any.
@end deffn

@geindex _pack_ (attribut ctypes.Structure)
@anchor{library/ctypes ctypes Structure _pack_}@anchor{2d6b}
@deffn {Attribut} _pack_

An optional small integer that allows overriding the alignment of
structure fields in the instance.  @ref{2d6b,,_pack_} must already be defined
when @ref{2d68,,_fields_} is assigned, otherwise it will have no effect.
Setting this attribute to 0 is the same as not setting it at all.
@end deffn

@geindex _align_ (attribut ctypes.Structure)
@anchor{library/ctypes ctypes Structure _align_}@anchor{1d0}
@deffn {Attribut} _align_

An optional small integer that allows overriding the alignment of
the structure when being packed or unpacked to/from memory.
Setting this attribute to 0 is the same as not setting it at all.


Ajouté dans la version 3.13.

@end deffn

@geindex _anonymous_ (attribut ctypes.Structure)
@anchor{library/ctypes ctypes Structure _anonymous_}@anchor{2dc1}
@deffn {Attribut} _anonymous_

An optional sequence that lists the names of unnamed (anonymous) fields.
@ref{2dc1,,_anonymous_} must be already defined when @ref{2d68,,_fields_} is
assigned, otherwise it will have no effect.

The fields listed in this variable must be structure or union type fields.
@ref{2a,,ctypes} will create descriptors in the structure type that allows
accessing the nested fields directly, without the need to create the
structure or union field.

Here is an example type (Windows):

@example
class _U(Union):
    _fields_ = [("lptdesc", POINTER(TYPEDESC)),
                ("lpadesc", POINTER(ARRAYDESC)),
                ("hreftype", HREFTYPE)]

class TYPEDESC(Structure):
    _anonymous_ = ("u",)
    _fields_ = [("u", _U),
                ("vt", VARTYPE)]
@end example

The @code{TYPEDESC} structure describes a COM data type, the @code{vt} field
specifies which one of the union fields is valid.  Since the @code{u} field
is defined as anonymous field, it is now possible to access the members
directly off the TYPEDESC instance. @code{td.lptdesc} and @code{td.u.lptdesc}
are equivalent, but the former is faster since it does not need to create
a temporary union instance:

@example
td = TYPEDESC()
td.vt = VT_PTR
td.lptdesc = POINTER(some_type)
td.u.lptdesc = POINTER(some_type)
@end example
@end deffn

It is possible to define sub-subclasses of structures, they inherit the
fields of the base class.  If the subclass definition has a separate
@ref{2d68,,_fields_} variable, the fields specified in this are appended to the
fields of the base class.

Structure and union constructors accept both positional and keyword
arguments.  Positional arguments are used to initialize member fields in the
same order as they are appear in @ref{2d68,,_fields_}.  Keyword arguments in the
constructor are interpreted as attribute assignments, so they will initialize
@ref{2d68,,_fields_} with the same name, or create new attributes for names not
present in @ref{2d68,,_fields_}.
@end deffn

@node Tableaux et pointeurs,,Types de données dérivés de Structure,Référence du module
@anchor{library/ctypes arrays-and-pointers}@anchor{2dc2}@anchor{library/ctypes ctypes-arrays-pointers}@anchor{2dc3}
@subsubsection Tableaux et pointeurs


@geindex Array (classe dans ctypes)
@anchor{library/ctypes ctypes Array}@anchor{19b8}
@deffn {Classe} ctypes.Array (*args)

Classe de base abstraite pour les `arrays'.

The recommended way to create concrete array types is by multiplying any
@ref{2a,,ctypes} data type with a non-negative integer.  Alternatively, you can subclass
this type and define @ref{2dc4,,_length_} and @ref{2dc5,,_type_} class variables.
Array elements can be read and written using standard
subscript and slice accesses; for slice reads, the resulting object is
`not' itself an @ref{19b8,,Array}.

@geindex _length_ (attribut ctypes.Array)
@anchor{library/ctypes ctypes Array _length_}@anchor{2dc4}
@deffn {Attribut} _length_

A positive integer specifying the number of elements in the array.
Out-of-range subscripts result in an @ref{14eb,,IndexError}. Will be
returned by @ref{619,,len()}.
@end deffn

@geindex _type_ (attribut ctypes.Array)
@anchor{library/ctypes ctypes Array _type_}@anchor{2dc5}
@deffn {Attribut} _type_

Spécifie le type de chaque élément de l'`array'.
@end deffn

Array subclass constructors accept positional arguments, used to
initialize the elements in order.
@end deffn

@geindex ARRAY() (dans le module ctypes)
@anchor{library/ctypes ctypes ARRAY}@anchor{299}
@deffn {Fonction} ctypes.ARRAY (type, length)

Create an array.
Equivalent to @code{type * length}, where `type' is a
@ref{2a,,ctypes} data type and `length' an integer.

This function is @ref{206,,soft deprecated} in favor of multiplication.
There are no plans to remove it.
@end deffn

@geindex _Pointer (classe dans ctypes)
@anchor{library/ctypes ctypes _Pointer}@anchor{2dc6}
@deffn {Classe} ctypes._Pointer

Private, abstract base class for pointers.

Concrete pointer types are created by calling @ref{166f,,POINTER()} with the
type that will be pointed to; this is done automatically by
@ref{166e,,pointer()}.

If a pointer points to an array, its elements can be read and
written using standard subscript and slice accesses.  Pointer objects
have no size, so @ref{619,,len()} will raise @ref{522,,TypeError}.  Negative
subscripts will read from the memory `before' the pointer (as in C), and
out-of-range subscripts will probably crash with an access violation (if
you're lucky).

@geindex _type_ (attribut ctypes._Pointer)
@anchor{library/ctypes ctypes _Pointer _type_}@anchor{2dc7}
@deffn {Attribut} _type_

Specifies the type pointed to.
@end deffn

@geindex contents (attribut ctypes._Pointer)
@anchor{library/ctypes ctypes _Pointer contents}@anchor{2d74}
@deffn {Attribut} contents

Returns the object to which to pointer points.  Assigning to this
attribute changes the pointer to point to the assigned object.
@end deffn
@end deffn

@node Command Line Interface Libraries,Exécution concourante,Services génériques du système d'exploitation,La bibliothèque standard
@anchor{library/cmdlinelibs doc}@anchor{2dc8}@anchor{library/cmdlinelibs cmdlinelibs}@anchor{2dc9}@anchor{library/cmdlinelibs command-line-interface-libraries}@anchor{2dca}
@section Command Line Interface Libraries


The modules described in this chapter assist with implementing
command line and terminal interfaces for applications.

Here's an overview:

@menu
* argparse: argparse --- Parser for command-line options arguments and subcommands. Parser for command-line options, arguments and
                        subcommands
* optparse: optparse --- Parser for command line options. Parser for command line options
* getpass: getpass --- Portable password input. Portable password input
* fileinput: fileinput --- Iterate over lines from multiple input streams. Iterate over lines from multiple input streams
* curses: curses --- Terminal handling for character-cell displays. Terminal handling for character-cell displays
* curses.textpad: curses textpad --- Text input widget for curses programs. Text input widget for curses programs
* curses.ascii: curses ascii --- Utilities for ASCII characters. Utilities for ASCII characters
* curses.panel: curses panel --- A panel stack extension for curses. A panel stack extension for curses

@end menu

@node argparse --- Parser for command-line options arguments and subcommands,optparse --- Parser for command line options,,Command Line Interface Libraries
@anchor{library/argparse doc}@anchor{2dcb}@anchor{library/argparse argparse-parser-for-command-line-options-arguments-and-subcommands}@anchor{2dcc}@anchor{library/argparse module-argparse}@anchor{6}
@subsection @code{argparse} --- Parser for command-line options, arguments and subcommands


@geindex module; argparse


Ajouté dans la version 3.2.


`Code source:' Lib/argparse.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/argparse.py}

@cartouche
@quotation Note 
While @ref{6,,argparse} is the default recommended standard library module
for implementing basic command line applications, authors with more
exacting requirements for exactly how their command line applications
behave may find it doesn't provide the necessary level of control.
Refer to @ref{2dcd,,Choosing an argument parsing library} for alternatives to
consider when @code{argparse} doesn't support behaviors that the application
requires (such as entirely disabling support for interspersed options and
positional arguments, or accepting option parameter values that start
with @code{-} even when they correspond to another defined option).
@end quotation
@end cartouche


__________________________________________________________________


@subsubheading Tutoriel



Cette page est la référence de l'API. Pour une introduction plus en douceur à l'analyse des arguments de la ligne de commande, regardez @ref{2dce,,le tutoriel argparse}.

The @code{argparse} module makes it easy to write user-friendly command-line
interfaces. The program defines what arguments it requires, and @code{argparse}
will figure out how to parse those out of @ref{1243,,sys.argv}.  The @code{argparse}
module also automatically generates help and usage messages.  The module
will also issue errors when users give the program invalid arguments.

The @code{argparse} module's support for command-line interfaces is built
around an instance of @ref{523,,argparse.ArgumentParser}.  It is a container for
argument specifications and has options that apply to the parser as whole:

@example
parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')
@end example

La méthode @ref{19c,,ArgumentParser.add_argument()} permet de définir les arguments de l'analyseur. Ceux-ci peuvent être des arguments positionnels, des arguments optionnels ou des drapeaux (qui sont alors traduits en valeurs booléennes). Les arguments ont la possibilité d'être complétés par des valeurs :

@example
parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag
@end example

La méthode @ref{2dcf,,ArgumentParser.parse_args()} lance l'analyseur et stocke les résultats dans un objet @ref{2dd0,,argparse.Namespace} :

@example
args = parser.parse_args()
print(args.filename, args.count, args.verbose)
@end example

@cartouche
@quotation Note 
If you're looking for a guide about how to upgrade @ref{9f,,optparse} code
to @code{argparse}, see @ref{118b,,Upgrading Optparse Code}.
@end quotation
@end cartouche

@menu
* Objets ArgumentParser:: 
* La méthode add_argument(): La méthode add_argument. 
* La méthode parse_args(): La méthode parse_args. 
* Autres outils:: 
* Exceptions: Exceptions<9>. 

@end menu

@node Objets ArgumentParser,La méthode add_argument,,argparse --- Parser for command-line options arguments and subcommands
@anchor{library/argparse argumentparser-objects}@anchor{2dd1}
@subsubsection Objets @code{ArgumentParser}


@geindex ArgumentParser (classe dans argparse)
@anchor{library/argparse argparse ArgumentParser}@anchor{523}
@deffn {Classe} argparse.ArgumentParser (prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Crée un nouvel objet @ref{523,,ArgumentParser}. Tous les paramètres doivent être passés en arguments nommés. Chaque paramètre a sa propre description détaillée ci-dessous, mais en résumé ils sont :


@itemize *

@item 
@ref{2dd2,,prog} – Nom du programme (par défaut : @code{os.path.basename(sys.argv[0])}) ;

@item 
@ref{2dd3,,usage} – Chaîne décrivant l'utilisation du programme (par défaut : générée à partir des arguments ajoutés à l'analyseur) ;

@item 
@ref{2dd4,,description} – Texte à afficher au dessus de l'aide pour les arguments (vide par défaut) ;

@item 
@ref{2dd5,,epilog} – Texte à afficher après l'aide des arguments (vide par défaut) ;

@item 
@ref{2dd6,,parents} – Liste d'objets @ref{523,,ArgumentParser} contenant des arguments qui devraient aussi être inclus ;

@item 
@ref{2dd7,,formatter_class} – Classe pour personnaliser la sortie du message d'aide ;

@item 
@ref{2dd8,,prefix_chars} – Jeu de caractères qui précède les arguments optionnels (par défaut : @code{'-'}) ;

@item 
@ref{2dd9,,fromfile_prefix_chars} – Jeu de caractères qui précède les fichiers d'où des arguments additionnels doivent être lus (par défaut : @code{None}) ;

@item 
@ref{2dda,,argument_default} – Valeur globale par défaut pour les arguments (par défaut : @code{None}) ;

@item 
@ref{2ddb,,conflict_handler} – Stratégie pour résoudre les conflits entre les arguments optionnels (non-nécessaire en général) ;

@item 
@ref{2ddc,,add_help} – Ajoute une option d'aide @code{-h/--help} à l'analyseur (par défaut : @code{True}) ;

@item 
@ref{dad,,allow_abbrev} – Permet l'acceptation d'abréviations non-ambigües pour les options longues (par défaut : @code{True}) ;

@item 
@ref{2ddd,,exit_on_error} - Determines whether or not @code{ArgumentParser} exits with
error info when an error occurs. (default: @code{True})
@end itemize


Modifié dans la version 3.5: Le paramètre `allow_abbrev' est ajouté.



Modifié dans la version 3.8: Dans les versions précédentes, `allow_abbrev' désactivait aussi le regroupement de plusieurs options courtes telles que @code{-vv} pour signifier @code{-v -v}.



Modifié dans la version 3.9: Le paramètre `exit_on_error' est ajouté.

@end deffn

Les sections suivantes décrivent comment chacune de ces options sont utilisées.

@menu
* Le paramètre prog:: 
* Le paramètre usage:: 
* Le paramètre description:: 
* Le paramètre epilog:: 
* Le paramètre parents:: 
* Le paramètre formatter_class:: 
* Le paramètre prefix_chars:: 
* Le paramètre fromfile_prefix_chars:: 
* Le paramètre argument_default:: 
* Le paramètre allow_abbrev:: 
* Le paramètre conflict_handler:: 
* Le paramètre add_help:: 
* Le paramètre exit_on_error:: 

@end menu

@node Le paramètre prog,Le paramètre usage,,Objets ArgumentParser
@anchor{library/argparse id1}@anchor{2dde}@anchor{library/argparse prog}@anchor{2dd2}
@subsubsection Le paramètre `prog'


By default, @ref{523,,ArgumentParser} calculates the name of the program
to display in help messages depending on the way the Python interpreter was run:


@itemize *

@item 
The @ref{2753,,base name} of @code{sys.argv[0]} if a file was
passed as argument.

@item 
The Python interpreter name followed by @code{sys.argv[0]} if a directory or
a zipfile was passed as argument.

@item 
The Python interpreter name followed by @code{-m} followed by the
module or package name if the @ref{5cb,,-m} option was used.
@end itemize

This default is almost always desirable because it will make the help messages
match the string that was used to invoke the program on the command line.
However, to change this default behavior, another value can be supplied using
the @code{prog=} argument to @ref{523,,ArgumentParser}:

@example
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit
@end example

Prenez note que le nom du programme, peu importe s'il provient de @code{sys.argv[0]} ou de l'argument @code{prog=}, est accessible aux messages d'aide grâce au spécificateur de formatage @code{%(prog)s}.

@example
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program
@end example

@node Le paramètre usage,Le paramètre description,Le paramètre prog,Objets ArgumentParser
@anchor{library/argparse usage}@anchor{2dd3}
@subsubsection Le paramètre `usage'


By default, @ref{523,,ArgumentParser} calculates the usage message from the
arguments it contains. The default message can be overridden with the
@code{usage=} keyword argument:

@example
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help
@end example

Le spécificateur de formatage @code{%(prog)s} est disponible pour insérer le nom du programme dans vos messages d'utilisation.

@node Le paramètre description,Le paramètre epilog,Le paramètre usage,Objets ArgumentParser
@anchor{library/argparse description}@anchor{2dd4}@anchor{library/argparse id2}@anchor{2ddf}
@subsubsection Le paramètre `description'


Most calls to the @ref{523,,ArgumentParser} constructor will use the
@code{description=} keyword argument.  This argument gives a brief description of
what the program does and how it works.  In help messages, the description is
displayed between the command-line usage string and the help messages for the
various arguments.

Par défaut, la description est sujette au retour à la ligne automatique pour se conformer à l'espace disponible. Pour changer ce comportement, voyez l'argument @ref{2dd7,,formatter_class}.

@node Le paramètre epilog,Le paramètre parents,Le paramètre description,Objets ArgumentParser
@anchor{library/argparse epilog}@anchor{2dd5}
@subsubsection Le paramètre `epilog'


Certains programmes aiment afficher un texte supplémentaire après la description des arguments. Un tel texte peut être spécifié grâce à l'argument @code{epilog=} du constructeur d'@ref{523,,ArgumentParser} :

@example
>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

options:
 -h, --help  show this help message and exit

And that's how you'd foo a bar
@end example

De même que pour l'argument @ref{2dd4,,description}, le texte passé à @code{epilog=} est sujet au retour à la ligne automatique. Ce comportement peut être ajusté grâce à l'argument @ref{2dd7,,formatter_class} du constructeur d'@ref{523,,ArgumentParser}.

@node Le paramètre parents,Le paramètre formatter_class,Le paramètre epilog,Objets ArgumentParser
@anchor{library/argparse parents}@anchor{2dd6}
@subsubsection Le paramètre `parents'


Parfois, plusieurs analyseurs partagent un jeu commun d'arguments. Plutôt que de répéter les définitions de ces arguments, un analyseur commun qui contient tous les arguments partagés peut être utilisé, puis passé à l'argument @code{parents=} du constructeur d'@ref{523,,ArgumentParser}. L'argument @code{parents=} accepte une liste d'objets @ref{523,,ArgumentParser}, accumule toutes les actions positionnelles et optionnelles de ces objets, puis les ajoute à l'instance d'@ref{523,,ArgumentParser} en cours de création :

@example
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
@end example

Prenez note que la majorité des analyseurs parents doivent définir @code{add_help=False}. Autrement, le constructeur d'@ref{523,,ArgumentParser} va voir plus d'une option @code{-h/--help} (une pour le parent et une pour l'instance en cours de création) et va lever une erreur.

@cartouche
@quotation Note 
Vous devez initialiser complètement les analyseurs avant de les passer à @code{parents=}. Si vous changez les analyseurs parents après la création de l'analyseur enfant, ces changements ne sont pas répercutés sur l'enfant.
@end quotation
@end cartouche

@node Le paramètre formatter_class,Le paramètre prefix_chars,Le paramètre parents,Objets ArgumentParser
@anchor{library/argparse formatter-class}@anchor{2dd7}@anchor{library/argparse id3}@anchor{2de0}
@subsubsection Le paramètre `formatter_class'


Les objets @ref{523,,ArgumentParser} permettent la personnalisation de la mise en page des messages d'aide en spécifiant une classe de formatage alternative. Il y a actuellement quatre classes de formatage :

@geindex RawDescriptionHelpFormatter (classe dans argparse)
@geindex RawTextHelpFormatter (classe dans argparse)
@geindex ArgumentDefaultsHelpFormatter (classe dans argparse)
@geindex MetavarTypeHelpFormatter (classe dans argparse)
@anchor{library/argparse argparse RawDescriptionHelpFormatter}@anchor{2de1}
@deffn {Classe} argparse.RawDescriptionHelpFormatter
@anchor{library/argparse argparse RawTextHelpFormatter}@anchor{2de2}
@deffnx {Classe} argparse.RawTextHelpFormatter
@anchor{library/argparse argparse ArgumentDefaultsHelpFormatter}@anchor{1829}
@deffnx {Classe} argparse.ArgumentDefaultsHelpFormatter
@anchor{library/argparse argparse MetavarTypeHelpFormatter}@anchor{2de3}
@deffnx {Classe} argparse.MetavarTypeHelpFormatter
@end deffn

@ref{2de1,,RawDescriptionHelpFormatter} et @ref{2de2,,RawTextHelpFormatter} vous donnent plus de contrôle sur comment les descriptions textuelles sont affichées. Par défaut, les contenus de @ref{2dd4,,description} et @ref{2dd5,,epilog} des objets @ref{523,,ArgumentParser} font l'objet du retour à la ligne automatique dans les messages d'aide :

@example
>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='@w{'}'this description
...         was indented weird
...             but that is okay'@w{'}',
...     epilog='@w{'}'
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines'@w{'}')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

options:
 -h, --help  show this help message and exit

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
@end example

Passer @ref{2de1,,RawDescriptionHelpFormatter} à @code{formatter_class=} indique que les textes de @ref{2dd4,,description} et d'@ref{2dd5,,epilog} ont déjà été formatés correctement et qu'ils ne doivent pas faire l'objet d'un retour à la ligne automatique :

@example
>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('@w{'}'\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '@w{'}'))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

options:
 -h, --help  show this help message and exit
@end example

@ref{2de2,,RawTextHelpFormatter} maintains whitespace for all sorts of help text,
including argument descriptions. However, multiple newlines are replaced with
one. If you wish to preserve multiple blank lines, add spaces between the
newlines.

@ref{1829,,ArgumentDefaultsHelpFormatter} ajoute automatiquement l'information sur les valeurs par défaut aux messages d'aide de tous les arguments :

@example
>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)
@end example

@ref{2de3,,MetavarTypeHelpFormatter} utilise le nom du @ref{2de4,,type} de l'argument pour chacun des arguments comme nom d'affichage pour leurs valeurs (contrairement au formateur standard qui utilise @ref{2de5,,dest}) :

@example
>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

options:
  -h, --help  show this help message and exit
  --foo int
@end example

@node Le paramètre prefix_chars,Le paramètre fromfile_prefix_chars,Le paramètre formatter_class,Objets ArgumentParser
@anchor{library/argparse prefix-chars}@anchor{2dd8}
@subsubsection Le paramètre `prefix_chars'


Most command-line options will use @code{-} as the prefix, e.g. @code{-f/--foo}.
Parsers that need to support different or additional prefix
characters, e.g. for options
like @code{+f} or @code{/foo}, may specify them using the @code{prefix_chars=} argument
to the @ref{523,,ArgumentParser} constructor:

@example
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
@end example

La valeur par défaut de @code{prefix_chars=} est @code{'-'}. Passer un jeu de caractères qui n'inclut pas @code{-} provoquera le refus des options comme @code{-f/--foo}.

@node Le paramètre fromfile_prefix_chars,Le paramètre argument_default,Le paramètre prefix_chars,Objets ArgumentParser
@anchor{library/argparse fromfile-prefix-chars}@anchor{2dd9}
@subsubsection Le paramètre `fromfile_prefix_chars'


Parfois, par exemple quand on traite une liste d'arguments particulièrement longue, il est logique de stocker la liste d'arguments dans un fichier plutôt que de la saisir sur la ligne de commande. Si un jeu de caractères est passé à l'argument @code{fromfile_prefix_chars=} du constructeur de @ref{523,,ArgumentParser}, alors les arguments qui commencent par l'un des caractères spécifiés sont traités comme des fichiers et sont remplacés par les arguments contenus dans ces fichiers. Par exemple :

@example
>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@@args.txt'])
Namespace(f='bar')
@end example

Par défaut, les arguments lus à partir d'un fichier doivent être chacun sur une nouvelle ligne (voir aussi @ref{2de6,,convert_arg_line_to_args()}) et ils sont traités comme s'ils étaient au même emplacement que le fichier original référençant les arguments de la ligne de commande. Ainsi dans l'exemple ci-dessus, l'expression @code{['-f', 'foo', '@@args.txt']} est équivalente à l'expression @code{['-f', 'foo', '-f', 'bar']}.

@ref{523,,ArgumentParser} uses @ref{525,,filesystem encoding and error handler}
to read the file containing arguments.

Par défaut, l'argument @code{fromfile_prefix_chars=} est @code{None}, ce qui signifie que les arguments ne sont pas traités en tant que références à des fichiers.


Modifié dans la version 3.12: @ref{523,,ArgumentParser} changed encoding and errors to read arguments files
from default (e.g. @ref{524,,locale.getpreferredencoding(False)}
and @code{"strict"}) to the @ref{525,,filesystem encoding and error handler}.
Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.


@node Le paramètre argument_default,Le paramètre allow_abbrev,Le paramètre fromfile_prefix_chars,Objets ArgumentParser
@anchor{library/argparse argument-default}@anchor{2dda}
@subsubsection Le paramètre `argument_default'


Généralement, les valeurs par défaut des arguments sont définies soit en passant la valeur désirée à @ref{19c,,add_argument()} soit par un appel à la méthode @ref{2de7,,set_defaults()}. Cette méthode accepte un ensemble de paires nom-valeur. Il est parfois pertinent de configurer une valeur par défaut pour tous les arguments d'un analyseur. On peut activer ce comportement en passant la valeur désirée à l'argument nommé @code{argument_default=} du constructeur de @ref{523,,ArgumentParser}. Par exemple, pour supprimer globalement la création d'attributs pendant l'appel de @ref{2dcf,,parse_args()}, on fournit @code{argument_default=SUPPRESS} :

@example
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
@end example

@node Le paramètre allow_abbrev,Le paramètre conflict_handler,Le paramètre argument_default,Objets ArgumentParser
@anchor{library/argparse allow-abbrev}@anchor{dad}@anchor{library/argparse id4}@anchor{2de8}
@subsubsection Le paramètre `allow_abbrev'


En temps normal, lorsque vous passez une liste d'arguments à la méthode @ref{2dcf,,parse_args()} d'@ref{523,,ArgumentParser} @ref{dac,,elle accepte les abréviations} des options longues.

Cette fonctionnalité peut être désactivée en passant @code{False} à @code{allow_abbrev} :

@example
>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon
@end example


Ajouté dans la version 3.5.


@node Le paramètre conflict_handler,Le paramètre add_help,Le paramètre allow_abbrev,Objets ArgumentParser
@anchor{library/argparse conflict-handler}@anchor{2ddb}
@subsubsection Le paramètre `conflict_handler'


Les objets @ref{523,,ArgumentParser} ne peuvent pas avoir plus d'une option avec la même chaîne d'option. Par défaut, les objets @ref{523,,ArgumentParser} lèvent une exception si on essaie de créer un argument avec une chaîne d'option qui est déjà utilisée :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo
@end example

Parfois, par exemple si on utilise des analyseurs @ref{2dd6,,parents}, il est souhaitable de surcharger les anciens arguments qui partagent la même chaîne d'option. Pour obtenir ce comportement, vous devez passer @code{'resolve'} à l'argument @code{conflict_handler=} du constructeur d'@ref{523,,ArgumentParser} :

@example
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

options:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help
@end example

Prenez note que les objets @ref{523,,ArgumentParser} n'enlèvent une action que si toutes ses chaînes d'options sont surchargées. Ainsi dans l'exemple ci-dessus, l'action @code{-f/--foo} du parent est conservée comme l'action @code{-f} puisque @code{--foo} est la seule chaîne d'options qui a été surchargée.

@node Le paramètre add_help,Le paramètre exit_on_error,Le paramètre conflict_handler,Objets ArgumentParser
@anchor{library/argparse add-help}@anchor{2ddc}
@subsubsection Le paramètre `add_help'


By default, @ref{523,,ArgumentParser} objects add an option which simply displays
the parser's help message. If @code{-h} or @code{--help} is supplied at the command
line, the @code{ArgumentParser} help will be printed.

Il est parfois utile de désactiver l'ajout de cette option d'aide. Pour ce faire, vous devez passer @code{False} à l'argument @code{add_help=} du constructeur d'@ref{523,,ArgumentParser} :

@example
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

options:
 --foo FOO  foo help
@end example

En général, l'option d'aide est @code{-h/--help}. L'exception à cette règle est quand une valeur est passée à @code{prefix_chars=} et qu'elle n'inclue pas @code{-}, auquel cas, @code{-h} et @code{--help} ne sont pas des options valides. Dans ce cas, le premier caractère de @code{prefix_chars} est utilisé comme préfixe des options d'aide :

@example
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

options:
  +h, ++help  show this help message and exit
@end example

@node Le paramètre exit_on_error,,Le paramètre add_help,Objets ArgumentParser
@anchor{library/argparse exit-on-error}@anchor{2ddd}
@subsubsection Le paramètre `exit_on_error'


Normally, when you pass an invalid argument list to the @ref{2dcf,,parse_args()}
method of an @ref{523,,ArgumentParser}, it will print a `message' to @ref{926,,sys.stderr} and exit with a status
code of 2.

Si vous souhaitez intercepter les erreurs manuellement, la fonctionnalité peut être activée en assignant @code{False} à @code{exit_on_error} :

@example
>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError
@end example


Ajouté dans la version 3.9.


@node La méthode add_argument,La méthode parse_args,Objets ArgumentParser,argparse --- Parser for command-line options arguments and subcommands
@anchor{library/argparse the-add-argument-method}@anchor{2de9}
@subsubsection La méthode `add_argument()'


@geindex add_argument() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_argument}@anchor{19c}
@deffn {Méthode} ArgumentParser.add_argument (name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])

Définie comment une option de ligne de commande doit être analysée. Chacun des paramètres est décrit plus en détails ci-bas, mais en résumé ils sont :


@itemize *

@item 
@ref{2dea,,name or flags} - Either a name or a list of option strings, e.g. @code{'foo'}
or @code{'-f', '--foo'}.

@item 
@ref{2deb,,action} – Type élémentaire de l'action à entreprendre quand cet argument est reconnu sur la ligne de commande ;

@item 
@ref{1533,,nargs} – Nombre d'arguments de la ligne de commande à capturer ;

@item 
@ref{2dec,,const} – Valeur constante requise par certains choix d'@ref{2deb,,action} et de @ref{1533,,nargs} ;

@item 
@ref{2ded,,default} – Valeur produite si l'argument est absent de la ligne de commande et absent de l'objet @code{namespace} ;

@item 
@ref{2de4,,type} – Type vers lequel l'argument sur la ligne de commande doit être converti ;

@item 
@ref{1530,,choices} – La séquence de valeurs autorisées pour cet argument ;

@item 
@ref{2dee,,required} – @code{True} si l'option sur la ligne de commande est obligatoire (ne s'applique qu'aux arguments optionnels) ;

@item 
@ref{2def,,help} – Brève description de ce que fait l'argument ;

@item 
@ref{2df0,,metavar} – Nom de l'argument dans les messages d'utilisations ;

@item 
@ref{2de5,,dest} – Nom de l'attribut qui est ajouté à l'objet retourné par @ref{2dcf,,parse_args()}.

@item 
@ref{2df1,,deprecated} - Whether or not use of the argument is deprecated.
@end itemize
@end deffn

Les sections suivantes décrivent comment chacune de ces options sont utilisées.

@menu
* Le paramètre name_or_flags:: 
* Le paramètre action:: 
* Le paramètre nargs:: 
* Le paramètre const:: 
* Le paramètre default:: 
* Le paramètre type:: 
* Le paramètre choices:: 
* Le paramètre required:: 
* Le paramètre help:: 
* Le paramètre metavar:: 
* Le paramètre dest:: 
* deprecated:: 
* Classes Action:: 

@end menu

@node Le paramètre name_or_flags,Le paramètre action,,La méthode add_argument
@anchor{library/argparse id5}@anchor{2df2}@anchor{library/argparse name-or-flags}@anchor{2dea}
@subsubsection Le paramètre `name_or_flags'


La méthode @ref{19c,,add_argument()} doit savoir s'il s'agit d'un argument optionnel (tel que @code{-f} ou @code{--foo}) ou d'un argument positionnel (tel qu'une liste de noms de fichiers) qui est attendu. Le premier argument passé à @ref{19c,,add_argument()} doit donc être soit une série de drapeaux, soit le nom de l'argument.

Par exemple, un argument optionnel est créé comme suit :

@example
>>> parser.add_argument('-f', '--foo')
@end example

alors qu'un argument positionnel est créé comme suit :

@example
>>> parser.add_argument('bar')
@end example

Lors le l'appel de @ref{2dcf,,parse_args()}, les arguments qui commencent par le préfixe @code{-} sont présumés optionnels et tous les autres sont présumés positionnels :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar
@end example

@node Le paramètre action,Le paramètre nargs,Le paramètre name_or_flags,La méthode add_argument
@anchor{library/argparse action}@anchor{2deb}@anchor{library/argparse id6}@anchor{2df3}
@subsubsection Le paramètre `action'


Les objets @ref{523,,ArgumentParser} associent les arguments de la ligne de commande avec des actions. Ces actions peuvent soumettre les arguments de la ligne de commande auxquels elles sont associées à un traitement arbitraire, mais la majorité des actions se contentent d'ajouter un attribut à l'objet renvoyé par @ref{2dcf,,parse_args()}. L'argument nommé @code{action} indique comment l'argument de la ligne de commande est traité. Les actions natives sont :


@itemize *

@item 
@code{'store'} - This just stores the argument's value.  This is the default
action.

@item 
@code{'store_const'} – Stocke la valeur passée à l'argument nommé @ref{2dec,,const}. La valeur par défaut de @ref{2dec,,const} est @code{None}. L'action @code{'store_const'} est généralement utilisée avec des arguments optionnels représentant un drapeau ou une condition similaire. Par exemple :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
@end example

@item 
@code{'store_true'} and @code{'store_false'} - These are special cases of
@code{'store_const'} used for storing the values @code{True} and @code{False}
respectively.  In addition, they create default values of @code{False} and
@code{True} respectively:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)
@end example

@item 
@code{'append'} – Stocke une liste et ajoute la valeur de son argument à cette liste. Il est donc généralement utile d'accepter la répétition de cet argument. Si une valeur par défaut est précisée, alors cette valeur est également présente dans la liste et précède les valeurs passées sur la ligne de commande :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
@end example

@item 
@code{'append_const'} – Stocke une liste et ajoute la valeur de son argument @ref{2dec,,const} à cette liste. Notez que la valeur par défaut de l'argument @ref{2dec,,const} est @code{None}. L'action @code{'append_const'} est pratique quand plusieurs arguments ont besoin de stocker des constantes dans une seule liste. Par exemple :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])
@end example

@item 
@code{'extend'} - This stores a list and appends each item from the multi-value
argument list to it.
The @code{'extend'} action is typically used with the @ref{1533,,nargs} keyword argument
value @code{'+'} or @code{'*'}.
Note that when @ref{1533,,nargs} is @code{None} (the default) or @code{'?'}, each
character of the argument string will be appended to the list.
Example usage:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])
@end example


Ajouté dans la version 3.8.


@item 
@code{'count'} – Compte le nombre d'occurrences de l'argument nommé. Ceci est pratique, par exemple, pour augmenter le niveau de verbosité :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
@end example

Prenez note que la valeur de `default' est @code{None} à moins qu'elle soit explicitement définie à @code{0}.

@item 
@code{'help'} – Affiche le message d'aide complet pour toutes les options de l'analyseur puis termine l'exécution. Une action @code{help} est automatiquement ajoutée à l'analyseur par défaut. Consultez @ref{523,,ArgumentParser} pour les détails de la création du contenu de l'aide.

@item 
@code{'version'} – Affiche la version du programme puis termine l'exécution. Cette action requiert l'argument nommé @code{version=} dans l'appel à @ref{19c,,add_argument()} :

@example
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0
@end example
@end itemize

Only actions that consume command-line arguments (e.g. @code{'store'},
@code{'append'} or @code{'extend'}) can be used with positional arguments.

@geindex BooleanOptionalAction (classe dans argparse)
@anchor{library/argparse argparse BooleanOptionalAction}@anchor{17e3}
@deffn {Classe} argparse.BooleanOptionalAction

You may also specify an arbitrary action by passing an @ref{178d,,Action} subclass or
other object that implements the same interface. The @code{BooleanOptionalAction}
is available in @code{argparse} and adds support for boolean actions such as
@code{--foo} and @code{--no-foo}:

@example
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)
@end example


Ajouté dans la version 3.9.

@end deffn

The recommended way to create a custom action is to extend @ref{178d,,Action},
overriding the @code{__call__()} method and optionally the @code{__init__()} and
@code{format_usage()} methods. You can also register custom actions using the
@ref{2df4,,register()} method and reference them by their registered name.

Un exemple d'action personnalisée :

@example
>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
@end example

Pour plus d'information, voir @ref{178d,,Action}.

@node Le paramètre nargs,Le paramètre const,Le paramètre action,La méthode add_argument
@anchor{library/argparse id7}@anchor{2df5}@anchor{library/argparse nargs}@anchor{1533}
@subsubsection Le paramètre `nargs'


@ref{523,,ArgumentParser} objects usually associate a single command-line argument with a
single action to be taken.  The @code{nargs} keyword argument associates a
different number of command-line arguments with a single action.
See also @ref{2df6,,Specifying ambiguous arguments}. The supported values are:


@itemize *

@item 
@code{N} (un entier). @code{N} arguments de la ligne de commande sont capturés ensemble et stockés dans une liste. Par exemple :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
@end example

Prenez note que @code{nargs=1} produit une liste avec un seul élément. Ceci est différent du comportement par défaut qui produit l'élément directement (comme un scalaire).
@end itemize

@geindex ? (question mark);in argparse module


@itemize *

@item 
@code{'?'}. Un argument de la ligne de commande est capturé et produit directement. Si aucun argument n'est présent sur la ligne de commande, la valeur de @ref{2ded,,default} est produite. Prenez note que pour les arguments optionnels, il est aussi possible que la chaîne d'option soit présente mais qu'elle ne soit pas suivie d'un argument. Dans ce cas, la valeur de @ref{2dec,,const} est produite. Voici quelques exemples pour illustrer ceci :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')
@end example

@code{nargs='?'} est fréquemment utilisé pour accepter des fichiers d'entrée et de sortie optionnels :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
...                     default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
...                     default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<_io.TextIOWrapper name='input.txt' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='output.txt' encoding='UTF-8'>)
>>> parser.parse_args([])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>,
          outfile=<_io.TextIOWrapper name='<stdout>' encoding='UTF-8'>)
@end example
@end itemize

@geindex * (asterisk);in argparse module


@itemize *

@item 
@code{'*'}. Tous les arguments présents sur la ligne de commande sont capturés dans une liste. Prenez note qu'il n'est pas logique d'avoir plus d'un argument positionnel avec @code{nargs='*'}, mais il est par contre possible d'avoir plusieurs arguments optionnels qui spécifient @code{nargs='*'}. Par exemple :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
@end example
@end itemize

@geindex + (plus);in argparse module


@itemize *

@item 
@code{'+'}. Comme pour @code{'*'}, tous les arguments présents sur la ligne de commande sont capturés dans une liste. De plus, un message d'erreur est produit s'il n'y a pas au moins un argument présent sur la ligne de commande. Par exemple :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo
@end example
@end itemize

If the @code{nargs} keyword argument is not provided, the number of arguments consumed
is determined by the @ref{2deb,,action}.  Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
Actions that do not consume command-line arguments (e.g.
@code{'store_const'}) set @code{nargs=0}.

@node Le paramètre const,Le paramètre default,Le paramètre nargs,La méthode add_argument
@anchor{library/argparse const}@anchor{2dec}@anchor{library/argparse id8}@anchor{2df7}
@subsubsection Le paramètre `const'


L'argument @code{const} d'@ref{19c,,add_argument()} est utilisé pour stocker une constante qui n'est pas lue depuis la ligne de commande mais qui est requise par certaines actions d'@ref{523,,ArgumentParser}. Les deux utilisations les plus communes sont :


@itemize *

@item 
quand @ref{19c,,add_argument()} est appelée avec @code{action='store_const'} ou @code{action='append_const'}, ces actions ajoutent la valeur de @code{const} à l'un des attributs de l'objet renvoyé par @ref{2dcf,,parse_args()}. Consultez la description d'@ref{2deb,,action} pour voir quelques exemples. La valeur de @code{const} est @code{None} par défaut pour @ref{19c,,add_argument()} ;

@item 
appeler la méthode @ref{19c,,add_argument()} avec des chaînes d'options (telles @code{-f}, @code{--foo} ou avec @code{nargs='?'}) crée un argument optionnel auquel peut être attribué une valeur. Si celle-ci est omise, l'analyseur prend @code{None} comme la valeur de @code{const}. La description de @ref{1533,,nargs} offre quelques exemples.
@end itemize


Modifié dans la version 3.11: @code{const=None} par défaut, y compris avec @code{action='append_const'} ou @code{action='store_const'}.


@node Le paramètre default,Le paramètre type,Le paramètre const,La méthode add_argument
@anchor{library/argparse default}@anchor{2ded}@anchor{library/argparse id9}@anchor{2df8}
@subsubsection Le paramètre `default'


Tous les arguments optionnels et certains arguments positionnels peuvent être omis à la ligne de commande. L'argument nommé @code{default} de la méthode @ref{19c,,add_argument()} (qui vaut @code{None} par défaut), indique quelle valeur est utilisée si l'argument est absent de la ligne de commande. Pour les arguments optionnels, la valeur de @code{default} est utilisée si la chaîne d'option n'est pas présente sur la ligne de commande :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)
@end example

If the target namespace already has an attribute set, the action `default'
will not overwrite it:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
@end example

Si la valeur de @code{default} est une chaîne, l'analyseur analyse cette valeur comme si c'était un argument de la ligne de commande. En particulier, l'analyseur applique la conversion définie par l'argument @ref{2de4,,type} (si elle est fournie) avant d'affecter l'attribut à l'objet @ref{2dd0,,Namespace} renvoyé. Autrement, l'analyseur utilise la valeur telle qu'elle :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
@end example

Pour les arguments positionnels pour lesquels @ref{1533,,nargs} est @code{?} ou @code{*}, la valeur de @code{default} est utilisée quand l'argument est absent de la ligne de commande :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)
@end example

For @ref{2dee,,required} arguments, the @code{default} value is ignored. For example, this
applies to positional arguments with @ref{1533,,nargs} values other than @code{?} or @code{*},
or optional arguments marked as @code{required=True}.

Si vous passez @code{default=argparse.SUPPRESS}, aucun attribut n'est ajouté à l'objet @code{Namespace} quand l'argument est absent de la ligne de commande :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')
@end example

@node Le paramètre type,Le paramètre choices,Le paramètre default,La méthode add_argument
@anchor{library/argparse argparse-type}@anchor{2df9}@anchor{library/argparse type}@anchor{2de4}
@subsubsection Le paramètre `type'


Par défaut, l'analyseur capture les arguments de la ligne de commande comme des chaînes. Très souvent par contre, on désire interpréter les chaînes de la ligne de commande comme un autre type, tel que @ref{2eb,,float} ou @ref{254,,int}. L'argument nommé @code{type} d'@ref{19c,,add_argument()} nous permet de faire les vérifications et les conversions de type nécessaires.

Si l'argument nommé @ref{2de4,,type} est utilisé en conjonction avec l'argument nommé @ref{2ded,,default}, le convertisseur de type n'est appliqué que si la valeur par défaut est une chaîne.

The argument to @code{type} can be a callable that accepts a single string or
the name of a registered type (see @ref{2df4,,register()})
If the function raises @ref{2dfa,,ArgumentTypeError}, @ref{522,,TypeError}, or
@ref{1ff,,ValueError}, the exception is caught and a nicely formatted error
message is displayed. Other exception types are not handled.

Les types et les fonctions natives peuvent être utilisés comme convertisseurs de types :

@example
import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
@end example

Des fonctions définies par l'utilisateur peuvent aussi être utilisées :

@example
>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
@end example

La fonction @ref{451,,bool()} est déconseillée comme convertisseur de type. Son comportement se limite à convertir les chaînes vides à @code{False} et les chaînes non-vides à @code{True}. Ce n'est généralement pas le résultat désiré.

En général, l'argument nommé @code{type} est un raccourci qui ne devrait être utilisé que pour les conversions simples qui ne peuvent lever qu'une des trois exceptions gérées. Les conversions qui demandent un traitement d'erreurs plus intéressant ou une gestion de ressources devraient être effectuées plus tard dans l’exécution suivant l'analyse des arguments.

Par exemple, les conversions de documents `JSON' ou `YAML' ont des cas d'erreurs complexes qui requièrent un meilleur signalement que ce qui est fourni par l'argument nommé @code{type}. Une exception @ref{e0d,,JSONDecodeError} ne serait pas adéquatement formatée et une exception @ref{eae,,FileNotFoundError} ne serait pas du tout traitée.

Even @ref{f06,,FileType} has its limitations for use with the @code{type}
keyword.  If one argument uses @ref{f06,,FileType} and then a
subsequent argument fails, an error is reported but the file is not
automatically closed.  In this case, it would be better to wait until after
the parser has run and then use the @ref{5bc,,with}-statement to manage the
files.

Pour les vérificateurs de types qui ne font que tester l'appartenance à un ensemble de valeurs, pensez plutôt à utiliser l'argument nommé @ref{1530,,choices}.

@node Le paramètre choices,Le paramètre required,Le paramètre type,La méthode add_argument
@anchor{library/argparse choices}@anchor{1530}@anchor{library/argparse id10}@anchor{2dfb}
@subsubsection Le paramètre `choices'


Certains arguments de la ligne de commande doivent être choisis parmi un ensemble prédéfini de valeurs. Celles-ci doivent être déclarées dans la séquence passée à l'argument `choices' de la méthode @ref{19c,,add_argument()}. Un message d'erreur est alors affiché si l'utilisateur passe un argument qui n'est pas parmi les valeurs acceptables :

@example
>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] @{rock,paper,scissors@}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')
@end example

Note that inclusion in the `choices' sequence is checked after any @ref{2de4,,type}
conversions have been performed, so the type of the objects in the `choices'
sequence should match the @ref{2de4,,type} specified.

N'importe quel séquence peut être utilisée comme valeur de `choices', dont les objets de type @ref{5fc,,list}, @ref{5c3,,set} ou des conteneurs personnalisés.

L'utilisation d'@ref{61b,,enum.Enum} est déconseillée, car il est difficile de contrôler son apparence dans les messages d'usage, d'aide et d'erreur.

Les choix formatés écrasent la valeur par défaut de `metavar' qui est normalement dérivée de `dest'. C'est en général le comportement recherché car l'utilisateur ne voit jamais le paramètre `dest'. Si cet affichage n'est pas souhaité (comme lorsque les choix sont trop nombreux) spécifiez simplement @ref{2df0,,metavar} de façon explicite.

@node Le paramètre required,Le paramètre help,Le paramètre choices,La méthode add_argument
@anchor{library/argparse id11}@anchor{2dfc}@anchor{library/argparse required}@anchor{2dee}
@subsubsection Le paramètre `required'


In general, the @code{argparse} module assumes that flags like @code{-f} and @code{--bar}
indicate `optional' arguments, which can always be omitted at the command line.
To make an option `required', @code{True} can be specified for the @code{required=}
keyword argument to @ref{19c,,add_argument()}:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo
@end example

Tel qu'illustré dans l'exemple, quand l'option est marquée comme @code{required}, @ref{2dcf,,parse_args()} mentionne une erreur si l'option est absente de la ligne de commande.

@cartouche
@quotation Note 
En général, les options obligatoires manifestent un style boiteux, car les utilisateurs s'attendent à ce que les `options' soient `optionnelles'. Elles devraient donc être évitées si possible.
@end quotation
@end cartouche

@node Le paramètre help,Le paramètre metavar,Le paramètre required,La méthode add_argument
@anchor{library/argparse help}@anchor{2def}@anchor{library/argparse id12}@anchor{2dfd}
@subsubsection Le paramètre `help'


The @code{help} value is a string containing a brief description of the argument.
When a user requests help (usually by using @code{-h} or @code{--help} at the
command line), these @code{help} descriptions will be displayed with each
argument.

La chaîne @code{help} peut contenir des définitions de formatage permettant d'éviter la répétition de contenu tel que le nom du programme et la valeur par défaut de l'argument (voir @ref{2ded,,default}). Les définitions disponibles comprennent entre autres le nom du programme, @code{%(prog)s}, et la plupart des arguments nommés d'@ref{19c,,add_argument()}, tels que @code{%(default)s}, @code{%(type)s}, etc :

@example
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

options:
 -h, --help  show this help message and exit
@end example

Comme la chaîne d'aide utilise le caractère @code{%} pour le formatage, si vous désirez afficher un @code{%} littéral dans la chaîne d'aide, vous devez en faire l’échappement avec @code{%%}.

@code{argparse} supports silencing the help entry for certain options, by
setting the @code{help} value to @code{argparse.SUPPRESS}:

@example
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

options:
  -h, --help  show this help message and exit
@end example

@node Le paramètre metavar,Le paramètre dest,Le paramètre help,La méthode add_argument
@anchor{library/argparse id13}@anchor{2dfe}@anchor{library/argparse metavar}@anchor{2df0}
@subsubsection Le paramètre `metavar'


When @ref{523,,ArgumentParser} generates help messages, it needs some way to refer
to each expected argument.  By default, @code{ArgumentParser} objects use the @ref{2de5,,dest}
value as the "name" of each object.  By default, for positional argument
actions, the @ref{2de5,,dest} value is used directly, and for optional argument actions,
the @ref{2de5,,dest} value is uppercased.  So, a single positional argument with
@code{dest='bar'} will be referred to as @code{bar}. A single
optional argument @code{--foo} that should be followed by a single command-line argument
will be referred to as @code{FOO}.  An example:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

options:
 -h, --help  show this help message and exit
 --foo FOO
@end example

Un nom alternatif peut être fourni à @code{metavar} :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

options:
 -h, --help  show this help message and exit
 --foo YYY
@end example

Prenez note que @code{metavar} ne change que le nom `affiché'. Le nom de l'attribut ajouté à l'objet renvoyé par @ref{2dcf,,parse_args()} est toujours déterminé par la valeur de @ref{2de5,,dest}.

Certaines valeurs de @code{nargs} peuvent provoquer l'affichage de @code{metavar} plus d'une fois. Passer un `n-uplet' à @code{metavar} indique les différents noms à afficher pour chacun des arguments :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz
@end example

@node Le paramètre dest,deprecated,Le paramètre metavar,La méthode add_argument
@anchor{library/argparse dest}@anchor{2de5}@anchor{library/argparse id14}@anchor{2dff}
@subsubsection Le paramètre `dest'


La plupart des actions d'@ref{523,,ArgumentParser} ajoutent une valeur dans un attribut de l'objet renvoyé par @ref{2dcf,,parse_args()}. Le nom de l'attribut est déterminé par l'argument nommé @code{dest} d'@ref{19c,,add_argument()}. Pour les arguments positionnels, @code{dest} est généralement le premier argument d'@ref{19c,,add_argument()} :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')
@end example

Pour les actions d'arguments optionnels, la valeur de @code{dest} est généralement inférée des chaînes d'options. @ref{523,,ArgumentParser} génère la valeur de @code{dest} en retirant le préfixe @code{--} de la première chaîne d'options longues. Si aucune n'est fournie, @code{dest} est alors dérivée de la première chaîne d'options courtes sans le préfixe @code{-}. Tous les @code{-} suivants sont convertis en @code{_} pour s'assurer que la chaîne est un nom d'attribut valide. Les exemples suivants illustrent ce comportement :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')
@end example

@code{dest} vous permet de fournir un nom d'attribut personnalisé :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
@end example

@node deprecated,Classes Action,Le paramètre dest,La méthode add_argument
@anchor{library/argparse deprecated}@anchor{2df1}@anchor{library/argparse id15}@anchor{2e00}
@subsubsection deprecated


During a project's lifetime, some arguments may need to be removed from the
command line. Before removing them, you should inform
your users that the arguments are deprecated and will be removed.
The @code{deprecated} keyword argument of
@ref{19c,,add_argument()}, which defaults to @code{False},
specifies if the argument is deprecated and will be removed
in the future.
For arguments, if @code{deprecated} is @code{True}, then a warning will be
printed to @ref{926,,sys.stderr} when the argument is used:

@example
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])  
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)
@end example


Ajouté dans la version 3.13.


@node Classes Action,,deprecated,La méthode add_argument
@anchor{library/argparse action-classes}@anchor{2e01}
@subsubsection Classes Action


@code{Action} classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows
this API may be passed as the @code{action} parameter to
@ref{19c,,add_argument()}.

@geindex Action (classe dans argparse)
@anchor{library/argparse argparse Action}@anchor{178d}
@deffn {Classe} argparse.Action (option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

@code{Action} objects are used by an @ref{523,,ArgumentParser} to represent the information
needed to parse a single argument from one or more strings from the
command line. The @code{Action} class must accept the two positional arguments
plus any keyword arguments passed to @ref{19c,,ArgumentParser.add_argument()}
except for the @code{action} itself.

Instances of @code{Action} (or return value of any callable to the
@code{action} parameter) should have attributes @code{dest},
@code{option_strings}, @code{default}, @code{type}, @code{required},
@code{help}, etc. defined. The easiest way to ensure these attributes
are defined is to call @code{Action.__init__()}.

@geindex __call__() (méthode argparse.Action)
@anchor{library/argparse argparse Action __call__}@anchor{2e02}
@deffn {Méthode} __call__ (parser, namespace, values, option_string=None)

@code{Action} instances should be callable, so subclasses must override the
@code{__call__()} method, which should accept four parameters:


@itemize *

@item 
`parser' - The @ref{523,,ArgumentParser} object which contains this action.

@item 
`namespace' - The @ref{2dd0,,Namespace} object that will be returned by
@ref{2dcf,,parse_args()}.  Most actions add an attribute to this
object using @ref{20e1,,setattr()}.

@item 
`values' - The associated command-line arguments, with any type conversions
applied.  Type conversions are specified with the @ref{2de4,,type} keyword argument to
@ref{19c,,add_argument()}.

@item 
`option_string' - The option string that was used to invoke this action.
The @code{option_string} argument is optional, and will be absent if the action
is associated with a positional argument.
@end itemize

The @code{__call__()} method may perform arbitrary actions, but will typically set
attributes on the @code{namespace} based on @code{dest} and @code{values}.
@end deffn

@geindex format_usage() (méthode argparse.Action)
@anchor{library/argparse argparse Action format_usage}@anchor{2e03}
@deffn {Méthode} format_usage ()

@code{Action} subclasses can define a @code{format_usage()} method that takes no argument
and return a string which will be used when printing the usage of the program.
If such method is not provided, a sensible default will be used.
@end deffn
@end deffn

@node La méthode parse_args,Autres outils,La méthode add_argument,argparse --- Parser for command-line options arguments and subcommands
@anchor{library/argparse the-parse-args-method}@anchor{2e04}
@subsubsection La méthode `parse_args()'


@geindex parse_args() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_args}@anchor{2dcf}
@deffn {Méthode} ArgumentParser.parse_args (args=None, namespace=None)

Convertie les chaînes d'arguments en objets et les assigne comme attributs de l'espace de nommage @code{namespace}. Renvoie un objet @code{namespace} rempli.

Previous calls to @ref{19c,,add_argument()} determine exactly what objects are
created and how they are assigned. See the documentation for
@code{add_argument()} for details.


@itemize *

@item 
@ref{2e05,,args} – Liste de chaînes à analyser. La valeur par défaut est récupérée dans @ref{1243,,sys.argv}.

@item 
@ref{2e06,,namespace} – Un objet pour recevoir les attributs. Par défaut, une nouvelle instance (vide) de @ref{2dd0,,Namespace}.
@end itemize
@end deffn

@menu
* Syntaxe de la valeur des options:: 
* Arguments invalides:: 
* Arguments contenant -:: 
* Arguments abrégés (par comparaison de leurs préfixes): Arguments abrégés par comparaison de leurs préfixes. 
* Au-delà de sys.argv: Au-delà de sys argv. 
* L'objet Namespace:: 

@end menu

@node Syntaxe de la valeur des options,Arguments invalides,,La méthode parse_args
@anchor{library/argparse option-value-syntax}@anchor{2e07}
@subsubsection Syntaxe de la valeur des options


La méthode @ref{2dcf,,parse_args()} offre plusieurs façons d'indiquer la valeur d'une option si elle en prend une. Dans le cas le plus simple, l'option et sa valeur sont passées en tant que deux arguments distincts :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)
@end example

Pour les options longues (les options qui ont un nom de plus d'un caractère), l'option et sa valeur peuvent être passées comme un seul argument de la ligne de commande en utilisant @code{=} comme séparateur :

@example
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
@end example

Pour les options courtes (un seul caractère), l'option et sa valeur peuvent être concaténées :

@example
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
@end example

Plusieurs options courtes peuvent être groupées ensemble après un seul préfixe @code{-} pour autant que seule la dernière, au maximum, ne nécessite une valeur :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')
@end example

@node Arguments invalides,Arguments contenant -,Syntaxe de la valeur des options,La méthode parse_args
@anchor{library/argparse invalid-arguments}@anchor{2e08}
@subsubsection Arguments invalides


Quand elle fait l'analyse de la ligne de commande, la méthode @ref{2dcf,,parse_args()} vérifie plusieurs erreurs possibles : entre autres, options ambigües, types invalides, options invalides, nombre incorrect d'arguments positionnels, etc. Quand une erreur est rencontrée, elle affiche l'erreur accompagnée du message d'aide puis termine l'exécution :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
@end example

@node Arguments contenant -,Arguments abrégés par comparaison de leurs préfixes,Arguments invalides,La méthode parse_args
@anchor{library/argparse arguments-containing}@anchor{2e09}
@subsubsection Arguments contenant @code{-}


La méthode @ref{2dcf,,parse_args()} tente de signaler une erreur quand l'utilisateur s'est clairement trompé. Par contre, certaines situations sont intrinsèquement ambigües. Par exemple, l'argument de la ligne de commande @code{-1} peut aussi bien être une tentative de spécifier une option qu'une tentative de passer un argument positionnel. La méthode @ref{2dcf,,parse_args()} est prudente : les arguments positionnels ne peuvent commencer par @code{-} que s'ils ont l'apparence d'un nombre négatif et que l'analyseur ne contient aucune option qui a l'apparence d'un nombre négatif :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
@end example

Si l'utilisateur a des arguments positionnels qui commencent par @code{-} et qui n'ont pas l'apparence d'un nombre négatif, il peut insérer le pseudo-argument @code{'--'} qui indique à @ref{2dcf,,parse_args()} de traiter tout ce qui suit comme un argument positionnel :

@example
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
@end example

See also @ref{2df6,,the argparse howto on ambiguous arguments}
for more details.

@node Arguments abrégés par comparaison de leurs préfixes,Au-delà de sys argv,Arguments contenant -,La méthode parse_args
@anchor{library/argparse argument-abbreviations-prefix-matching}@anchor{2e0a}@anchor{library/argparse prefix-matching}@anchor{dac}
@subsubsection Arguments abrégés (par comparaison de leurs préfixes)


Par défaut, la méthode @ref{2dcf,,parse_args()} accepte que les options longues soient @ref{dad,,abrégées} par un préfixe pour autant que l’abréviation soit non-ambigüe, c'est-à-dire qu'elle ne corresponde à aucune autre option :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon
@end example

Une erreur est générée pour les arguments qui peuvent produire plus d'une option. Ce comportement peut être désactivé en passant @code{False} à @ref{dad,,Le paramètre allow_abbrev}.

@node Au-delà de sys argv,L'objet Namespace,Arguments abrégés par comparaison de leurs préfixes,La méthode parse_args
@anchor{library/argparse args}@anchor{2e05}@anchor{library/argparse beyond-sys-argv}@anchor{2e0b}
@subsubsection Au-delà de @code{sys.argv}


Sometimes it may be useful to have an @ref{523,,ArgumentParser} parse arguments other than those
of @ref{1243,,sys.argv}.  This can be accomplished by passing a list of strings to
@ref{2dcf,,parse_args()}.  This is useful for testing at the
interactive prompt:

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
@end example

@node L'objet Namespace,,Au-delà de sys argv,La méthode parse_args
@anchor{library/argparse namespace}@anchor{2e06}@anchor{library/argparse the-namespace-object}@anchor{2e0c}
@subsubsection L'objet @code{Namespace}


@geindex Namespace (classe dans argparse)
@anchor{library/argparse argparse Namespace}@anchor{2dd0}
@deffn {Classe} argparse.Namespace

Classe rudimentaire utilisée par défaut par @ref{2dcf,,parse_args()} pour créer un objet qui stocke les attributs. Cet objet est renvoyé par @code{ArgumentParser.parse_args}.

Cette classe est délibérément rudimentaire : une sous-classe d'@ref{a7a,,object} avec une représentation textuelle intelligible. Si vous préférez une vue `dict-compatible', vous devez utiliser @ref{19d0,,vars()} (un idiome Python classique) :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
@{'foo': 'BAR'@}
@end example

Il est parfois utile de demander à @ref{523,,ArgumentParser} de faire l'affectation des attributs sur un objet existant plutôt que de faire la création d'un nouvel objet @ref{2dd0,,Namespace}. Ceci peut être réalisé avec l'argument nommé @code{namespace=} :

@example
>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
@end example
@end deffn

@node Autres outils,Exceptions<9>,La méthode parse_args,argparse --- Parser for command-line options arguments and subcommands
@anchor{library/argparse other-utilities}@anchor{2e0d}
@subsubsection Autres outils


@menu
* Sous commandes:: 
* Objets FileType:: 
* Groupes d'arguments:: 
* Exclusion mutuelle:: 
* Valeurs par défaut de l'analyseur:: 
* Afficher l'aide:: 
* Analyse partielle:: 
* Personnaliser le parsing de fichiers:: 
* Méthodes d'interruptions:: 
* Analyse entremêlée:: 
* Registering custom types or actions:: 

@end menu

@node Sous commandes,Objets FileType,,Autres outils
@anchor{library/argparse sub-commands}@anchor{2e0e}
@subsubsection Sous commandes


@geindex add_subparsers() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_subparsers}@anchor{c05}
@deffn {Méthode} ArgumentParser.add_subparsers (*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])

Many programs split up their functionality into a number of subcommands,
for example, the @code{svn} program can invoke subcommands like @code{svn
checkout}, @code{svn update}, and @code{svn commit}.  Splitting up functionality
this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments.
@ref{523,,ArgumentParser} supports the creation of such subcommands with the
@code{add_subparsers()} method.  The @code{add_subparsers()} method is normally
called with no arguments and returns a special action object.  This object
has a single method, @code{add_parser()}, which takes a
command name and any @code{ArgumentParser} constructor arguments, and
returns an @code{ArgumentParser} object that can be modified as usual.

Description des paramètres :


@itemize *

@item 
`title' - title for the sub-parser group in help output; by default
"subcommands" if description is provided, otherwise uses title for
positional arguments

@item 
`description' - description for the sub-parser group in help output, by
default @code{None}

@item 
`prog' - usage information that will be displayed with sub-command help,
by default the name of the program and any positional arguments before the
subparser argument

@item 
`parser_class' - class which will be used to create sub-parser instances, by
default the class of the current parser (e.g. @ref{523,,ArgumentParser})

@item 
@ref{2deb,,action} – action à entreprendre quand cet argument est reconnu sur la ligne de commande ;

@item 
@ref{2de5,,dest} – nom de l'attribut sous lequel la sous-commande est stockée ; par défaut : @code{None} et aucune valeur n'est stockée ;

@item 
@ref{2dee,,required} – @code{True} si la sous-commande est obligatoire ; par défaut : @code{False} (ajouté dans 3.7) ;

@item 
@ref{2def,,help} – message d'aide pour le groupe du sous-analyseur dans la sortie d'aide ; par défaut : @code{None} ;

@item 
@ref{2df0,,metavar} - string presenting available subcommands in help; by default it
is @code{None} and presents subcommands in form @{cmd1, cmd2, ..@}
@end itemize

Quelques exemples d'utilisation :

@example
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='subcommand help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)
@end example

Prenez note que l'objet renvoyé par @ref{2dcf,,parse_args()} ne contient que les attributs reconnus par l'analyseur principal et le sous-analyseur sélectionné par la ligne de commande. Les autres sous-analyseurs n'ont pas d'influence sur l'objet renvoyé. Ainsi dans l'exemple précédent, quand la commande @code{a} est donnée, seuls les attributs @code{foo} et @code{bar} sont présents alors que la commande @code{b} présente les attributs @code{foo} et @code{baz}.

Similarly, when a help message is requested from a subparser, only the help
for that particular parser will be printed.  The help message will not
include parent parser or sibling parser messages.  (A help message for each
subparser command, however, can be given by supplying the @code{help=} argument
to @code{add_parser()} as above.)

@example
>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] @{a,b@} ...

positional arguments:
  @{a,b@}   subcommand help
    a     a help
    b     b help

options:
  -h, --help  show this help message and exit
  --foo   foo help

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

options:
  -h, --help  show this help message and exit

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz @{X,Y,Z@}]

options:
  -h, --help     show this help message and exit
  --baz @{X,Y,Z@}  baz help
@end example

La méthode @ref{c05,,add_subparsers()} accepte les arguments nommés @code{title} et @code{description}. Quand au moins l'un des deux est présent, les commandes du sous-analyseur sont affichées dans leur propre groupe dans la sortie d'aide. Par exemple :

@example
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] @{foo,bar@} ...

options:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  @{foo,bar@}   additional help
@end example

Furthermore, @code{add_parser()} supports an additional
`aliases' argument,
which allows multiple strings to refer to the same subparser. This example,
like @code{svn}, aliases @code{co} as a shorthand for @code{checkout}:

@example
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')
@end example

@code{add_parser()} supports also an additional
`deprecated' argument, which allows to deprecate the subparser.

@example
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> run = subparsers.add_parser('run')
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> parser.parse_args(['fly'])  
chicken.py: warning: command 'fly' is deprecated
Namespace()
@end example


Ajouté dans la version 3.13.


One particularly effective way of handling subcommands is to combine the use
of the @ref{c05,,add_subparsers()} method with calls to @ref{2de7,,set_defaults()} so
that each subparser knows which Python function it should execute.  For
example:

@example
>>> # subcommand functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))
@end example

Ainsi, vous pouvez laisser à @ref{2dcf,,parse_args()} la responsabilité de faire appel à la bonne fonction après avoir analysé les arguments. Associer fonctions et actions est en général la façon la plus facile de gérer des actions différentes pour chacun de vos sous-analyseurs. Par contre, si vous avez besoin de consulter le nom du sous-analyseur qui a été invoqué, vous pouvez utiliser l'argument nommé @code{dest} d'@ref{c05,,add_subparsers()} :

@example
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')
@end example


Modifié dans la version 3.7: New `required' keyword-only parameter.

@end deffn

@node Objets FileType,Groupes d'arguments,Sous commandes,Autres outils
@anchor{library/argparse filetype-objects}@anchor{2e0f}
@subsubsection Objets @code{FileType}


@geindex FileType (classe dans argparse)
@anchor{library/argparse argparse FileType}@anchor{f06}
@deffn {Classe} argparse.FileType (mode='r', bufsize=-1, encoding=None, errors=None)

Le type fabrique @ref{f06,,FileType} crée des objets qui peuvent être passés à l'argument @code{type} d'@ref{19c,,ArgumentParser.add_argument()}. Les arguments qui ont comme @code{type} un objet @ref{f06,,FileType} ouvrent les arguments de la ligne de commande en tant que fichiers avec les options spécifiées : mode, taille du tampon, encodage et gestion des erreurs (voir la fonction @ref{505,,open()} pour plus de détails) :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)
@end example

Les objets @code{FileType} reconnaissent le pseudo-argument @code{'-'} et le convertissent automatiquement vers @ref{527,,sys.stdin} pour les objets @ref{f06,,FileType} ouverts en lecture, et vers @ref{ac4,,sys.stdout} pour les objets @ref{f06,,FileType} ouverts en écriture :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)
@end example


Modifié dans la version 3.4: Added the `encodings' and `errors' parameters.

@end deffn

@node Groupes d'arguments,Exclusion mutuelle,Objets FileType,Autres outils
@anchor{library/argparse argument-groups}@anchor{2e10}
@subsubsection Groupes d'arguments


@geindex add_argument_group() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_argument_group}@anchor{2e11}
@deffn {Méthode} ArgumentParser.add_argument_group (title=None, description=None, *[, argument_default][, conflict_handler])

By default, @ref{523,,ArgumentParser} groups command-line arguments into
"positional arguments" and "options" when displaying help
messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the
@code{add_argument_group()} method:

@example
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help
@end example

The @ref{2e11,,add_argument_group()} method returns an argument group object which
has an @ref{19c,,add_argument()} method just like a regular
@ref{523,,ArgumentParser}.  When an argument is added to the group, the parser
treats it just like a normal argument, but displays the argument in a
separate group for help messages.  The @code{add_argument_group()} method
accepts `title' and `description' arguments which can be used to
customize this display:

@example
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help
@end example

The optional, keyword-only parameters @ref{2dda,,argument_default} and @ref{2ddb,,conflict_handler}
allow for finer-grained control of the behavior of the argument group. These
parameters have the same meaning as in the @ref{523,,ArgumentParser} constructor,
but apply specifically to the argument group rather than the entire parser.

Prenez note que tout argument qui n'est pas dans l'un de vos groupes est affiché dans l'une des sections usuelles `positional arguments' et `optional arguments'.


Modifié dans la version 3.11: Appeler @ref{2e11,,add_argument_group()} sur un groupe d'arguments est obsolète. Cet emploi n'a jamais été pris en charge et ne fonctionne pas dans tous les cas. La présence de cette fonction dans l'API est purement accidentelle et celle-ci disparaîtra.

@end deffn

@node Exclusion mutuelle,Valeurs par défaut de l'analyseur,Groupes d'arguments,Autres outils
@anchor{library/argparse mutual-exclusion}@anchor{2e12}
@subsubsection Exclusion mutuelle


@geindex add_mutually_exclusive_group() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser add_mutually_exclusive_group}@anchor{2e13}
@deffn {Méthode} ArgumentParser.add_mutually_exclusive_group (required=False)

Create a mutually exclusive group. @code{argparse} will make sure that only
one of the arguments in the mutually exclusive group was present on the
command line:

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo
@end example

La méthode @ref{2e13,,add_mutually_exclusive_group()} accepte aussi l'argument @code{required} pour indiquer qu'au moins un des arguments mutuellement exclusifs est nécessaire :

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required
@end example

Note that currently mutually exclusive argument groups do not support the
`title' and `description' arguments of
@ref{2e11,,add_argument_group()}. However, a mutually exclusive
group can be added to an argument group that has a title and description.
For example:

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

options:
  -h, --help  show this help message and exit

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help
@end example


Modifié dans la version 3.11: Appeler @ref{2e11,,add_argument_group()} ou @ref{2e13,,add_mutually_exclusive_group()} sur un groupe mutuellement exclusif est obsolète. Cet emploi n'a jamais été pris en charge et ne fonctionne pas dans tous les cas. La présence de cette fonction dans l'API est purement accidentelle et celle-ci disparaîtra.

@end deffn

@node Valeurs par défaut de l'analyseur,Afficher l'aide,Exclusion mutuelle,Autres outils
@anchor{library/argparse parser-defaults}@anchor{2e14}
@subsubsection Valeurs par défaut de l'analyseur


@geindex set_defaults() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser set_defaults}@anchor{2de7}
@deffn {Méthode} ArgumentParser.set_defaults (**kwargs)

Dans la majorité des cas, les attributs de l'objet renvoyé par @ref{2dcf,,parse_args()} sont entièrement définis par l'inspection des arguments de la ligne de commande et par les actions des arguments. La méthode @ref{2de7,,set_defaults()} permet l'ajout d'attributs additionnels qui sont définis sans nécessiter l'inspection de la ligne de commande :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)
@end example

Prenez note que les valeurs par défaut au niveau de l'analyseur ont précédence sur les valeurs par défaut au niveau de l'argument :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')
@end example

Les valeurs par défaut au niveau de l'analyseur sont particulièrement utiles quand on travaille avec plusieurs analyseurs. Voir la méthode @ref{c05,,add_subparsers()} pour un exemple de cette utilisation.
@end deffn

@geindex get_default() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser get_default}@anchor{2e15}
@deffn {Méthode} ArgumentParser.get_default (dest)

Renvoie la valeur par défaut d'un attribut de l'objet @code{Namespace} tel qu'il a été défini soit par @ref{19c,,add_argument()} ou par @ref{2de7,,set_defaults()} :

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'
@end example
@end deffn

@node Afficher l'aide,Analyse partielle,Valeurs par défaut de l'analyseur,Autres outils
@anchor{library/argparse printing-help}@anchor{2e16}
@subsubsection Afficher l'aide


Pour la majorité des applications, @ref{2dcf,,parse_args()} se charge du formatage et de l'affichage des messages d'erreur et d'utilisation. Plusieurs méthodes de formatage sont toutefois disponibles :

@geindex print_usage() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser print_usage}@anchor{2e17}
@deffn {Méthode} ArgumentParser.print_usage (file=None)

Affiche une brève description sur la façon d'invoquer l'@ref{523,,ArgumentParser} depuis la ligne de commande. Si @code{file} est @code{None}, utilise @ref{ac4,,sys.stdout}.
@end deffn

@geindex print_help() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser print_help}@anchor{2e18}
@deffn {Méthode} ArgumentParser.print_help (file=None)

Affiche un message d'aide qui inclut l'utilisation du programme et l'information sur les arguments répertoriés dans l'@ref{523,,ArgumentParser}. Si @code{file} est @code{None}, utilise @ref{ac4,,sys.stdout}.
@end deffn

Des variantes de ces méthodes sont fournies pour renvoyer la chaîne plutôt que de l'afficher :

@geindex format_usage() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser format_usage}@anchor{1959}
@deffn {Méthode} ArgumentParser.format_usage ()

Renvoie une chaîne contenant une brève description sur la façon d'invoquer l'@ref{523,,ArgumentParser} depuis la ligne de commande.
@end deffn

@geindex format_help() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser format_help}@anchor{2e19}
@deffn {Méthode} ArgumentParser.format_help ()

Renvoie une chaîne représentant un message d'aide qui inclut des informations sur l'utilisation du programme et sur les arguments définis dans l'@ref{523,,ArgumentParser}.
@end deffn

@node Analyse partielle,Personnaliser le parsing de fichiers,Afficher l'aide,Autres outils
@anchor{library/argparse partial-parsing}@anchor{2e1a}
@subsubsection Analyse partielle


@geindex parse_known_args() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_known_args}@anchor{2e1b}
@deffn {Méthode} ArgumentParser.parse_known_args (args=None, namespace=None)

Parfois, un script n'analyse que quelques-uns des arguments de la ligne de commande avant de passer les arguments non-traités à un autre script ou programme. La méthode @ref{2e1b,,parse_known_args()} est utile dans ces cas. Elle fonctionne similairement à @ref{2dcf,,parse_args()}, mais elle ne lève pas d'erreur quand des arguments non-reconnus sont présents. Au lieu, elle renvoie une paire de valeurs : l'objet @code{Namespace} rempli et la liste des arguments non-traités.

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
@end example
@end deffn

@cartouche
@quotation Avertissement 
Les règles d'@ref{dac,,acceptation des abréviations} sont applicables à @ref{2e1b,,parse_known_args()}. L'analyseur peut ainsi capturer une option même si elle n'est que le préfixe d'une option reconnue plutôt que de la laisser dans la liste des arguments non-traités.
@end quotation
@end cartouche

@node Personnaliser le parsing de fichiers,Méthodes d'interruptions,Analyse partielle,Autres outils
@anchor{library/argparse customizing-file-parsing}@anchor{2e1c}
@subsubsection Personnaliser le `parsing' de fichiers


@geindex convert_arg_line_to_args() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser convert_arg_line_to_args}@anchor{2de6}
@deffn {Méthode} ArgumentParser.convert_arg_line_to_args (arg_line)

Les arguments qui proviennent d'un fichier sont lus un par ligne. La méthode @ref{2de6,,convert_arg_line_to_args()} peut être surchargée pour accomplir un traitement plus élaboré. Voir aussi l'argument nommé @code{fromfile_prefix_chars} du constructeur d'@ref{523,,ArgumentParser}.

La méthode @code{convert_arg_line_to_args} accepte un seul argument, @code{arg_line}, qui est une chaîne lue dans le fichier d'arguments. Elle renvoie une liste d'arguments analysés dans cette chaîne. La méthode est appelée une fois pour chaque ligne lue du fichier d'arguments. L'ordre est préservé.

Une surcharge utile de cette méthode est de permettre à chaque mot délimité par des espaces d'être traité comme un argument. L'exemple suivant illustre comment réaliser ceci :

@example
class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()
@end example
@end deffn

@node Méthodes d'interruptions,Analyse entremêlée,Personnaliser le parsing de fichiers,Autres outils
@anchor{library/argparse exiting-methods}@anchor{2e1d}
@subsubsection Méthodes d'interruptions


@geindex exit() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser exit}@anchor{2e1e}
@deffn {Méthode} ArgumentParser.exit (status=0, message=None)

This method terminates the program, exiting with the specified `status'
and, if given, it prints a `message' to @ref{926,,sys.stderr} before that.
The user can override this method to handle these steps differently:

@example
class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: @{message@}')
        exit(status)
@end example
@end deffn

@geindex error() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser error}@anchor{2e1f}
@deffn {Méthode} ArgumentParser.error (message)

This method prints a usage message, including the `message', to
@ref{926,,sys.stderr} and terminates the program with a status code of 2.
@end deffn

@node Analyse entremêlée,Registering custom types or actions,Méthodes d'interruptions,Autres outils
@anchor{library/argparse intermixed-parsing}@anchor{2e20}
@subsubsection Analyse entremêlée


@geindex parse_intermixed_args() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_intermixed_args}@anchor{aee}
@deffn {Méthode} ArgumentParser.parse_intermixed_args (args=None, namespace=None)
@end deffn

@geindex parse_known_intermixed_args() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser parse_known_intermixed_args}@anchor{2e21}
@deffn {Méthode} ArgumentParser.parse_known_intermixed_args (args=None, namespace=None)

De nombreuses commandes Unix permettent à l'utilisateur d'entremêler les arguments optionnels et les arguments positionnels. Les méthodes @ref{aee,,parse_intermixed_args()} et @ref{2e21,,parse_known_intermixed_args()} permettent ce style d'analyse.

These parsers do not support all the @code{argparse} features, and will raise
exceptions if unsupported features are used.  In particular, subparsers,
and mutually exclusive groups that include both
optionals and positionals are not supported.

L'exemple suivant illustre la différence entre @ref{2e1b,,parse_known_args()} et @ref{aee,,parse_intermixed_args()} : le premier renvoie @code{['2', '3']} comme arguments non-traités alors que le second capture tous les arguments positionnels dans @code{rest}

@example
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])
@end example

@ref{2e21,,parse_known_intermixed_args()} renvoie une paire de valeurs : l'objet @code{Namespace} rempli et une liste de chaînes d'arguments non-traités. @ref{aee,,parse_intermixed_args()} lève une erreur s'il reste des chaînes d'arguments non-traités.


Ajouté dans la version 3.7.

@end deffn

@node Registering custom types or actions,,Analyse entremêlée,Autres outils
@anchor{library/argparse registering-custom-types-or-actions}@anchor{2e22}
@subsubsection Registering custom types or actions


@geindex register() (méthode argparse.ArgumentParser)
@anchor{library/argparse argparse ArgumentParser register}@anchor{2df4}
@deffn {Méthode} ArgumentParser.register (registry_name, value, object)

Sometimes it's desirable to use a custom string in error messages to provide
more user-friendly output. In these cases, @code{register()} can be used to
register custom actions or types with a parser and allow you to reference the
type by their registered name instead of their callable name.

The @code{register()} method accepts three arguments - a `registry_name',
specifying the internal registry where the object will be stored (e.g.,
@code{action}, @code{type}), `value', which is the key under which the object will
be registered, and object, the callable to be registered.

The following example shows how to register a custom type with a parser:

@example
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
>>> parser.add_argument('--foo', type='hexadecimal integer')
_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args(['--foo', '0xFA'])
Namespace(foo=250)
>>> parser.parse_args(['--foo', '1.2'])
usage: PROG [-h] [--foo FOO]
PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'
@end example
@end deffn

@node Exceptions<9>,,Autres outils,argparse --- Parser for command-line options arguments and subcommands
@anchor{library/argparse exceptions}@anchor{2e23}
@subsubsection Exceptions


@geindex ArgumentError
@anchor{library/argparse argparse ArgumentError}@anchor{2e24}
@deffn {Exception} argparse.ArgumentError

An error from creating or using an argument (optional or positional).

The string value of this exception is the message, augmented with
information about the argument that caused it.
@end deffn

@geindex ArgumentTypeError
@anchor{library/argparse argparse ArgumentTypeError}@anchor{2dfa}
@deffn {Exception} argparse.ArgumentTypeError

Raised when something goes wrong converting a command line string to a type.
@end deffn

@subsubheading Guides et tutoriels


@menu
* Tutoriel argparse:: 
* Migrating optparse code to argparse:: 

@end menu

@node Tutoriel argparse,Migrating optparse code to argparse,,Exceptions<9>
@anchor{howto/argparse doc}@anchor{2e25}@anchor{howto/argparse argparse-tutorial}@anchor{2dce}@anchor{howto/argparse id1}@anchor{2e26}
@subsubsection Tutoriel `argparse'


@*auteur: 
Tshepang Mbambo


Ce tutoriel est destiné à être une introduction en douceur à @ref{6,,argparse}, le module d'analyse de ligne de commande recommandé dans la bibliothèque standard de Python.

@cartouche
@quotation Note 
The standard library includes two other libraries directly related
to command-line parameter processing: the lower level @ref{9f,,optparse}
module (which may require more code to configure for a given application,
but also allows an application to request behaviors that @code{argparse}
doesn't support), and the very low level @ref{60,,getopt} (which specifically
serves as an equivalent to the @code{getopt()} family of functions
available to C programmers).
While neither of those modules is covered directly in this guide, many of
the core concepts in @code{argparse} first originated in @code{optparse}, so
some aspects of this tutorial will also be relevant to @code{optparse} users.
@end quotation
@end cartouche

@menu
* Concepts:: 
* Les bases:: 
* Introduction aux arguments positionnels:: 
* Introduction aux arguments optionnels:: 
* Combinaison d'arguments positionnels et optionnels:: 
* Aller un peu plus loin:: 
* How to translate the argparse output:: 
* Custom type converters:: 
* Conclusion:: 

@end menu

@node Concepts,Les bases,,Tutoriel argparse
@anchor{howto/argparse concepts}@anchor{2e27}
@subsubsection Concepts


Commençons par l'utilisation de la commande @code{ls} pour voir le type de fonctionnalité que nous allons étudier dans ce tutoriel d'introduction :

@example
$ ls
cpython  devguide  prog.py  pypy  rm-unused-function.patch
$ ls pypy
ctypes_configure  demo  dotviewer  include  lib_pypy  lib-python ...
$ ls -l
total 20
drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython
drwxr-xr-x  4 wena wena 4096 Feb  8 12:04 devguide
-rwxr-xr-x  1 wena wena  535 Feb 19 00:05 prog.py
drwxr-xr-x 14 wena wena 4096 Feb  7 00:59 pypy
-rw-r--r--  1 wena wena  741 Feb 18 01:01 rm-unused-function.patch
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...
@end example

Quelques concepts que l'on peut apprendre avec les quatre commandes :


@itemize *

@item 
La commande @code{ls} est utile quand elle est exécutée sans aucun paramètre. Elle affiche par défaut le contenu du dossier courant.

@item 
Si l'on veut plus que ce qui est proposé par défaut, il faut l'indiquer. Dans le cas présent, on veut afficher un dossier différent : @code{pypy}. Ce que l'on a fait c'est spécifier un argument positionnel. C'est appelé ainsi car cela permet au programme de savoir quoi faire avec la valeur en se basant seulement sur sa position dans la ligne de commande. Ce concept est plus pertinent pour une commande comme @code{cp} dont l'usage de base est @code{cp SRC DEST}. Le premier argument est `ce que vous voulez copier' et le second est `où vous voulez le copier'.

@item 
Maintenant, supposons que l'on veuille changer la façon dont le programme agit. Dans notre exemple, on affiche plus d'information pour chaque ficher que simplement leur nom. Dans ce cas, @code{-l} est un argument facultatif.

@item 
C'est un fragment du texte d'aide. Cela peut être très utile quand on tombe sur un programme que l'on à jamais utilisé auparavant car on peut comprendre son fonctionnement simplement en lisant l'aide associée.
@end itemize

@node Les bases,Introduction aux arguments positionnels,Concepts,Tutoriel argparse
@anchor{howto/argparse the-basics}@anchor{2e28}
@subsubsection Les bases


Commençons par un exemple très simple qui ne fait (quasiment) rien :

@example
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
@end example

Ce qui suit est le résultat de l'exécution du code :

@example
$ python prog.py
$ python prog.py --help
usage: prog.py [-h]

options:
  -h, --help  show this help message and exit
$ python prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo
@end example

Voilà ce qu'il se passe :


@itemize *

@item 
Exécuter le script sans aucun paramètre a pour effet de ne rien afficher sur la sortie d'erreur. Ce n'est pas très utile.

@item 
Le deuxième commence à montrer l'intérêt du module @ref{6,,argparse}. On n'a quasiment rien fait mais on a déjà un beau message d'aide.

@item 
L'option @code{--help}, que l'on peut aussi raccourcir en @code{-h}, est la seule option que l'on a gratuitement (pas besoin de la préciser). Préciser quoi que ce soit d'autre entraîne une erreur. Mais même dans ce cas, on reçoit aussi un message utile, toujours gratuitement.
@end itemize

@node Introduction aux arguments positionnels,Introduction aux arguments optionnels,Les bases,Tutoriel argparse
@anchor{howto/argparse introducing-positional-arguments}@anchor{2e29}
@subsubsection Introduction aux arguments positionnels


Un exemple :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print(args.echo)
@end example

On exécute le code :

@example
$ python prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python prog.py --help
usage: prog.py [-h] echo

positional arguments:
  echo

options:
  -h, --help  show this help message and exit
$ python prog.py foo
foo
@end example

Voilà ce qu'il se passe :


@itemize *

@item 
We've added the @ref{19c,,add_argument()} method, which is what we use to specify
which command-line options the program is willing to accept. In this case,
I've named it @code{echo} so that it's in line with its function.

@item 
Utiliser le programme nécessite maintenant que l'on précise un paramètre.

@item 
The @ref{2dcf,,parse_args()} method actually returns some data from the
options specified, in this case, @code{echo}.

@item 
La variable est comme une forme de 'magie'  que @ref{6,,argparse}  effectue gratuitement (c.-à-d. pas besoin de préciser dans quelle variable la valeur est stockée). Vous aurez aussi remarqué que le nom est le même que l'argument en chaîne de caractères donné à la méthode : @code{echo}.
@end itemize

Notez cependant que, même si l'affichage d'aide paraît bien , il n'est pas aussi utile qu'il pourrait l'être. Par exemple, on peut lire que @code{echo} est un argument positionnel mais on ne peut pas savoir ce que cela fait autrement qu'en le devinant ou en lisant le code source. Donc, rendons-le un peu plus utile :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print(args.echo)
@end example

Et on obtient :

@example
$ python prog.py -h
usage: prog.py [-h] echo

positional arguments:
  echo        echo the string you use here

options:
  -h, --help  show this help message and exit
@end example

À présent, que diriez-vous de faire quelque chose d'encore plus utile :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number")
args = parser.parse_args()
print(args.square**2)
@end example

Ce qui suit est le résultat de l'exécution du code :

@example
$ python prog.py 4
Traceback (most recent call last):
  File "prog.py", line 5, in <module>
    print(args.square**2)
TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'
@end example

Cela n'a pas très bien fonctionné. C'est parce que @ref{6,,argparse} traite les paramètres que l'on donne comme des chaînes de caractères à moins qu'on ne lui indique de faire autrement. Donc, disons à @ref{6,,argparse} de traiter cette entrée comme un entier :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number",
                    type=int)
args = parser.parse_args()
print(args.square**2)
@end example

Ce qui suit est le résultat de l'exécution du code :

@example
$ python prog.py 4
16
$ python prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'
@end example

Cela a bien fonctionné. Maintenant le programme va même s'arrêter si l'entrée n'est pas légale avant de procéder à l'exécution.

@node Introduction aux arguments optionnels,Combinaison d'arguments positionnels et optionnels,Introduction aux arguments positionnels,Tutoriel argparse
@anchor{howto/argparse introducing-optional-arguments}@anchor{2e2a}
@subsubsection Introduction aux arguments optionnels


Jusqu'à maintenant, on a joué avec les arguments positionnels. Regardons comment ajouter des paramètres optionnels :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
    print("verbosity turned on")
@end example

Et le résultat :

@example
$ python prog.py --verbosity 1
verbosity turned on
$ python prog.py
$ python prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]

options:
  -h, --help            show this help message and exit
  --verbosity VERBOSITY
                        increase output verbosity
$ python prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument
@end example

Voilà ce qu'il se passe :


@itemize *

@item 
Le programme est écrit de sorte qu'il n'affiche rien sauf si l'option @code{--verbosity} est précisée.

@item 
To show that the option is actually optional, there is no error when running
the program without it. Note that by default, if an optional argument isn't
used, the relevant variable, in this case @code{args.verbosity}, is
given @code{None} as a value, which is the reason it fails the truth
test of the @ref{2e7,,if} statement.

@item 
Le message d'aide est quelque peu différent.

@item 
Quand on utilise l'option @code{--verbosity} on doit aussi préciser une valeur, n'importe laquelle.
@end itemize

L'exemple ci-dessus accepte des valeurs entières arbitraires pour @code{--verbosity} mais pour notre programme simple seule deux valeurs sont réellement utiles : @code{True} et @code{False}. Modifions le code en accord avec cela :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbose", help="increase output verbosity",
                    action="store_true")
args = parser.parse_args()
if args.verbose:
    print("verbosity turned on")
@end example

Et le résultat :

@example
$ python prog.py --verbose
verbosity turned on
$ python prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python prog.py --help
usage: prog.py [-h] [--verbose]

options:
  -h, --help  show this help message and exit
  --verbose   increase output verbosity
@end example

Voilà ce qu'il se passe :


@itemize *

@item 
The option is now more of a flag than something that requires a value.
We even changed the name of the option to match that idea.
Note that we now specify a new keyword, @code{action}, and give it the value
@code{"store_true"}. This means that, if the option is specified,
assign the value @code{True} to @code{args.verbose}.
Not specifying it implies @code{False}.

@item 
Dans l'esprit de ce que sont vraiment les options, pas des paramètres, il se plaint quand vous tentez de préciser une valeur.

@item 
Notez que l'aide est différente.
@end itemize

@menu
* Les paramètres raccourcis:: 

@end menu

@node Les paramètres raccourcis,,,Introduction aux arguments optionnels
@anchor{howto/argparse short-options}@anchor{2e2b}
@subsubsection Les paramètres raccourcis


Si vous êtes familier avec l'utilisation de la ligne de commande, vous avez dû remarquer que je n'ai pour l'instant rien dit au sujet des versions raccourcies des paramètres. C'est très simple :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbose", help="increase output verbosity",
                    action="store_true")
args = parser.parse_args()
if args.verbose:
    print("verbosity turned on")
@end example

Et voilà :

@example
$ python prog.py -v
verbosity turned on
$ python prog.py --help
usage: prog.py [-h] [-v]

options:
  -h, --help     show this help message and exit
  -v, --verbose  increase output verbosity
@end example

Notez que la nouvelle option est aussi indiquée dans l'aide.

@node Combinaison d'arguments positionnels et optionnels,Aller un peu plus loin,Introduction aux arguments optionnels,Tutoriel argparse
@anchor{howto/argparse combining-positional-and-optional-arguments}@anchor{2e2c}
@subsubsection Combinaison d'arguments positionnels et optionnels


Notre programme continue de croître en complexité :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbose", action="store_true",
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbose:
    print(f"the square of @{args.square@} equals @{answer@}")
else:
    print(answer)
@end example

Et voilà le résultat :

@example
$ python prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python prog.py 4
16
$ python prog.py 4 --verbose
the square of 4 equals 16
$ python prog.py --verbose 4
the square of 4 equals 16
@end example


@itemize *

@item 
Nous avons ajouté un argument nommé, d'où le message d'erreur.

@item 
Notez que l'ordre importe peu.
@end itemize

Qu'en est-il si nous donnons à ce programme la possibilité d'avoir plusieurs niveaux de verbosité, et que celui-ci les prend en compte :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int,
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
    print(f"the square of @{args.square@} equals @{answer@}")
elif args.verbosity == 1:
    print(f"@{args.square@}^2 == @{answer@}")
else:
    print(answer)
@end example

Et le résultat :

@example
$ python prog.py 4
16
$ python prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python prog.py 4 -v 1
4^2 == 16
$ python prog.py 4 -v 2
the square of 4 equals 16
$ python prog.py 4 -v 3
16
@end example

Tout semble bon sauf le dernier, qui montre que notre programme contient un bogue. Corrigeons cela en restreignant les valeurs que @code{--verbosity} accepte :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
    print(f"the square of @{args.square@} equals @{answer@}")
elif args.verbosity == 1:
    print(f"@{args.square@}^2 == @{answer@}")
else:
    print(answer)
@end example

Et le résultat :

@example
$ python prog.py 4 -v 3
usage: prog.py [-h] [-v @{0,1,2@}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python prog.py 4 -h
usage: prog.py [-h] [-v @{0,1,2@}] square

positional arguments:
  square                display a square of a given number

options:
  -h, --help            show this help message and exit
  -v, --verbosity @{0,1,2@}
                        increase output verbosity
@end example

Notez que ce changement est pris en compte à la fois dans le message d'erreur et dans le texte d'aide.

Essayons maintenant une approche différente pour jouer sur la verbosité, ce qui arrive fréquemment. Cela correspond également à comment le programme CPython gère ses propres paramètres de verbosité (jetez un œil sur la sortie de la commande @code{python --help}) :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display the square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
    print(f"the square of @{args.square@} equals @{answer@}")
elif args.verbosity == 1:
    print(f"@{args.square@}^2 == @{answer@}")
else:
    print(answer)
@end example

Nous avons introduit une autre action, @code{"count"}, pour compter le nombre d’occurrences d'une option en particulier :

@example
$ python prog.py 4
16
$ python prog.py 4 -v
4^2 == 16
$ python prog.py 4 -vv
the square of 4 equals 16
$ python prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python prog.py 4 -h
usage: prog.py [-h] [-v] square

positional arguments:
  square           display a square of a given number

options:
  -h, --help       show this help message and exit
  -v, --verbosity  increase output verbosity
$ python prog.py 4 -vvv
16
@end example


@itemize *

@item 
Oui, c'est maintenant d'avantage une option (similaire à @code{action="store_true"}) de la version précédente de notre script. Cela devrait expliquer le message d'erreur.

@item 
Cela se comporte de la même manière que l'action @code{"store_true"}.

@item 
Maintenant voici une démonstration de ce que l'action @code{"count"} fait. Vous avez sûrement vu ce genre d'utilisation auparavant.

@item 
Et si vous ne spécifiez pas l'option @code{-v}, cette option prendra la valeur @code{None}.

@item 
Comme on s'y attend, en spécifiant l'option dans sa forme longue, on devrait obtenir la même sortie.

@item 
Malheureusement, notre sortie d'aide n'est pas très informative à propos des nouvelles possibilités de notre programme, mais cela peut toujours être corrigé en améliorant sa documentation (en utilisant l'argument @code{help}).

@item 
La dernière sortie du programme montre que celui-ci contient un bogue.
@end itemize

Corrigeons :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2

# bugfix: replace == with >=
if args.verbosity >= 2:
    print(f"the square of @{args.square@} equals @{answer@}")
elif args.verbosity >= 1:
    print(f"@{args.square@}^2 == @{answer@}")
else:
    print(answer)
@end example

Et c'est ce que ça donne :

@example
$ python prog.py 4 -vvv
the square of 4 equals 16
$ python prog.py 4 -vvvv
the square of 4 equals 16
$ python prog.py 4
Traceback (most recent call last):
  File "prog.py", line 11, in <module>
    if args.verbosity >= 2:
TypeError: '>=' not supported between instances of 'NoneType' and 'int'
@end example


@itemize *

@item 
Les premières exécutions du programme sont correctes, et le bogue que nous avons eu est corrigé. Cela dit, nous voulons que n'importe quelle valeur >= 2 rende le programme aussi verbeux que possible.

@item 
La troisième sortie de programme n'est pas si bien que ça.
@end itemize

Corrigeons ce bogue :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
                    help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count", default=0,
                    help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity >= 2:
    print(f"the square of @{args.square@} equals @{answer@}")
elif args.verbosity >= 1:
    print(f"@{args.square@}^2 == @{answer@}")
else:
    print(answer)
@end example

Nous venons juste d'introduire un nouveau mot clef, @code{default}. Nous l'avons définit à @code{0} pour le rendre comparable aux autres valeurs. Rappelez-vous que par défaut, si un argument optionnel n'est pas spécifié, il sera définit à @code{None}, et ne pourra pas être comparé à une valeur de type entier (une erreur @ref{522,,TypeError} serait alors levée).

Et :

@example
$ python prog.py 4
16
@end example

Vous pouvez aller assez loin seulement avec ce que nous avons appris jusqu'à maintenant, et nous n'avons qu’aperçu la surface. Le module @ref{6,,argparse} est très puissant, et nous allons l'explorer un peu plus avant la fin de ce tutoriel.

@node Aller un peu plus loin,How to translate the argparse output,Combinaison d'arguments positionnels et optionnels,Tutoriel argparse
@anchor{howto/argparse getting-a-little-more-advanced}@anchor{2e2d}
@subsubsection Aller un peu plus loin


Qu'en est-il si nous souhaitons étendre notre mini programme pour le rendre capable de calculer d'autres puissances, et pas seulement des carrés :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
    print(f"@{args.x@} to the power @{args.y@} equals @{answer@}")
elif args.verbosity >= 1:
    print(f"@{args.x@}^@{args.y@} == @{answer@}")
else:
    print(answer)
@end example

Sortie :

@example
$ python prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python prog.py -h
usage: prog.py [-h] [-v] x y

positional arguments:
  x                the base
  y                the exponent

options:
  -h, --help       show this help message and exit
  -v, --verbosity
$ python prog.py 4 2 -v
4^2 == 16
@end example

Il est à noter que jusqu'à présent nous avons utilisé le niveau de verbosité pour `changer' le texte qui est affiché. L'exemple suivant au contraire utilise le niveau de verbosité pour afficher `plus' de texte à la place :

@example
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
    print(f"Running '@{__file__@}'")
if args.verbosity >= 1:
    print(f"@{args.x@}^@{args.y@} == ", end="")
print(answer)
@end example

Sortie :

@example
$ python prog.py 4 2
16
$ python prog.py 4 2 -v
4^2 == 16
$ python prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16
@end example

@menu
* Specifying ambiguous arguments:: 
* Paramètres en conflit:: 

@end menu

@node Specifying ambiguous arguments,Paramètres en conflit,,Aller un peu plus loin
@anchor{howto/argparse id2}@anchor{2e2e}@anchor{howto/argparse specifying-ambiguous-arguments}@anchor{2df6}
@subsubsection Specifying ambiguous arguments


When there is ambiguity in deciding whether an argument is positional or for an
argument, @code{--} can be used to tell @ref{2dcf,,parse_args()} that
everything after that is a positional argument:

@example
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-n', nargs='+')
>>> parser.add_argument('args', nargs='*')

>>> # ambiguous, so parse_args assumes it's an option
>>> parser.parse_args(['-f'])
usage: PROG [-h] [-n N [N ...]] [args ...]
PROG: error: unrecognized arguments: -f

>>> parser.parse_args(['--', '-f'])
Namespace(args=['-f'], n=None)

>>> # ambiguous, so the -n option greedily accepts arguments
>>> parser.parse_args(['-n', '1', '2', '3'])
Namespace(args=[], n=['1', '2', '3'])

>>> parser.parse_args(['-n', '1', '--', '2', '3'])
Namespace(args=['2', '3'], n=['1'])
@end example

@node Paramètres en conflit,,Specifying ambiguous arguments,Aller un peu plus loin
@anchor{howto/argparse conflicting-options}@anchor{2e2f}
@subsubsection Paramètres en conflit


So far, we have been working with two methods of an
@ref{523,,argparse.ArgumentParser} instance. Let's introduce a third one,
@ref{2e13,,add_mutually_exclusive_group()}. It allows for us to specify options that
conflict with each other. Let's also change the rest of the program so that
the new functionality makes more sense:
we'll introduce the @code{--quiet} option,
which will be the opposite of the @code{--verbose} one:

@example
import argparse

parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y

if args.quiet:
    print(answer)
elif args.verbose:
    print(f"@{args.x@} to the power @{args.y@} equals @{answer@}")
else:
    print(f"@{args.x@}^@{args.y@} == @{answer@}")
@end example

Notre programme est maintenant plus simple, et nous avons perdu des fonctionnalités pour faire cette démonstration. Peu importe, voici la sortie du programme :

@example
$ python prog.py 4 2
4^2 == 16
$ python prog.py 4 2 -q
16
$ python prog.py 4 2 -v
4 to the power 2 equals 16
$ python prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
@end example

Cela devrait être facile à suivre. J'ai ajouté cette dernière sortie pour que vous puissiez voir le genre de flexibilité que vous pouvez avoir, par exemple pour faire un mélange entre des paramètres courts et longs.

Avant d'en finir, vous voudrez certainement dire à vos utilisateurs quel est le but principal de votre programme, juste dans le cas ou ils ne le sauraient pas :

@example
import argparse

parser = argparse.ArgumentParser(description="calculate X to the power of Y")
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y

if args.quiet:
    print(answer)
elif args.verbose:
    print(f"@{args.x@} to the power @{args.y@} equals @{answer@}")
else:
    print(f"@{args.x@}^@{args.y@} == @{answer@}")
@end example

Notez cette nuance dans le texte d'utilisation. Les options @code{[-v | -q]} nous disent que nous pouvons utiliser au choix @code{-v} ou @code{-q}, mais pas les deux ensemble :

@example
$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y

calculate X to the power of Y

positional arguments:
  x              the base
  y              the exponent

options:
  -h, --help     show this help message and exit
  -v, --verbose
  -q, --quiet
@end example

@node How to translate the argparse output,Custom type converters,Aller un peu plus loin,Tutoriel argparse
@anchor{howto/argparse how-to-translate-the-argparse-output}@anchor{2e30}
@subsubsection How to translate the argparse output


The output of the @ref{6,,argparse} module such as its help text and error
messages are all made translatable using the @ref{62,,gettext} module. This
allows applications to easily localize messages produced by
@ref{6,,argparse}. See also @ref{2e31,,Internationaliser vos programmes et modules}.

For instance, in this @ref{6,,argparse} output:

@example
$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y

calculate X to the power of Y

positional arguments:
  x              the base
  y              the exponent

options:
  -h, --help     show this help message and exit
  -v, --verbose
  -q, --quiet
@end example

The strings @code{usage:}, @code{positional arguments:}, @code{options:} and
@code{show this help message and exit} are all translatable.

In order to translate these strings, they must first be extracted
into a @code{.po} file. For example, using Babel@footnote{https://babel.pocoo.org/},
run this command:

@example
$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py
@end example

This command will extract all translatable strings from the @ref{6,,argparse}
module and output them into a file named @code{messages.po}. This command assumes
that your Python installation is in @code{/usr/lib}.

You can find out the location of the @ref{6,,argparse} module on your system
using this script:

@example
import argparse
print(argparse.__file__)
@end example

Once the messages in the @code{.po} file are translated and the translations are
installed using @ref{62,,gettext}, @ref{6,,argparse} will be able to display the
translated messages.

To translate your own strings in the @ref{6,,argparse} output, use @ref{62,,gettext}.

@node Custom type converters,Conclusion,How to translate the argparse output,Tutoriel argparse
@anchor{howto/argparse custom-type-converters}@anchor{2e32}
@subsubsection Custom type converters


The @ref{6,,argparse} module allows you to specify custom type converters for
your command-line arguments. This allows you to modify user input before it's
stored in the @ref{2dd0,,argparse.Namespace}. This can be useful when you need to
pre-process the input before it is used in your program.

When using a custom type converter, you can use any callable that takes a
single string argument (the argument value) and returns the converted value.
However, if you need to handle more complex scenarios, you can use a custom
action class with the `action' parameter instead.

For example, let's say you want to handle arguments with different prefixes and
process them accordingly:

@example
import argparse

parser = argparse.ArgumentParser(prefix_chars='-+')

parser.add_argument('-a', metavar='<value>', action='append',
                    type=lambda x: ('-', x))
parser.add_argument('+a', metavar='<value>', action='append',
                    type=lambda x: ('+', x))

args = parser.parse_args()
print(args)
@end example

Sortie :

@example
$ python prog.py -a value1 +a value2
Namespace(a=[('-', 'value1'), ('+', 'value2')])
@end example

In this example, we:


@itemize *

@item 
Created a parser with custom prefix characters using the @code{prefix_chars}
parameter.

@item 
Defined two arguments, @code{-a} and @code{+a}, which used the @code{type} parameter to
create custom type converters to store the value in a tuple with the prefix.
@end itemize

Without the custom type converters, the arguments would have treated the @code{-a}
and @code{+a} as the same argument, which would have been undesirable. By using custom
type converters, we were able to differentiate between the two arguments.

@node Conclusion,,Custom type converters,Tutoriel argparse
@anchor{howto/argparse conclusion}@anchor{2e33}
@subsubsection Conclusion


Le module @ref{6,,argparse} offre bien plus que ce qui est montré ici. Sa documentation est assez détaillée, complète et pleine d'exemples. En ayant accompli ce tutoriel, vous pourrez facilement comprendre cette documentation sans vous sentir dépassé.
@anchor{howto/argparse-optparse upgrading-optparse-code}@anchor{118b}
@node Migrating optparse code to argparse,,Tutoriel argparse,Exceptions<9>
@anchor{howto/argparse-optparse doc}@anchor{2e34}@anchor{howto/argparse-optparse migrating-optparse-code}@anchor{2e35}@anchor{howto/argparse-optparse migrating-optparse-code-to-argparse}@anchor{2e36}
@subsubsection Migrating @code{optparse} code to @code{argparse}


The @ref{6,,argparse} module offers several higher level features not natively
provided by the @ref{9f,,optparse} module, including:


@itemize *

@item 
gère les arguments positionnels ;

@item 
Supporting subcommands.

@item 
permet d'utiliser les alternatives @code{+} ou @code{/} comme préfixes d'option ;

@item 
prend en charge la répétition de valeurs (zéro ou plus, un ou plus) ;

@item 
fournit des messages d'aide plus complets ;

@item 
fournit une interface plus simple pour les types et les actions personnalisés.
@end itemize

Originally, the @ref{6,,argparse} module attempted to maintain compatibility
with @ref{9f,,optparse}.  However, the fundamental design differences between
supporting declarative command line option processing (while leaving positional
argument processing to application code), and supporting both named options
and positional arguments in the declarative interface mean that the
API has diverged from that of @code{optparse} over time.

As described in @ref{2dcd,,Choosing an argument parsing library}, applications that are
currently using @ref{9f,,optparse} and are happy with the way it works can
just continue to use @code{optparse}.

Application developers that are considering migrating should also review
the list of intrinsic behavioural differences described in that section
before deciding whether or not migration is desirable.

For applications that do choose to migrate from @ref{9f,,optparse} to @ref{6,,argparse},
the following suggestions should be helpful:


@itemize *

@item 
remplacer tous les appels à @ref{2e37,,optparse.OptionParser.add_option()} par des appels à @ref{19c,,ArgumentParser.add_argument()} ;

@item 
remplacer @code{(options, args) = parser.parse_args()} par @code{args = parser.parse_args()} et ajouter des appels à @ref{19c,,ArgumentParser.add_argument()} pour les arguments positionnels. Prenez note que les valeurs précédemment appelées @code{options} sont appelées @code{args} dans le contexte d'@ref{6,,argparse} ;

@item 
remplacer @ref{2e38,,optparse.OptionParser.disable_interspersed_args()} en appelant @ref{aee,,parse_intermixed_args()} plutôt que @ref{2dcf,,parse_args()} ;

@item 
remplacer les actions de rappel (`callback actions' en anglais) et les arguments nommés @code{callback_*} par des arguments @code{type} et @code{actions} ;

@item 
remplacer les chaînes représentant le nom des types pour l'argument nommé @code{type} par les objets types correspondants (par exemple : @code{int}, @code{float}, @code{complex}, etc) ;

@item 
remplacer @ref{2e39,,optparse.Values} par @ref{2dd0,,Namespace} ; et @ref{2e3a,,optparse.OptionError} et @ref{2e3b,,optparse.OptionValueError} par @ref{2e24,,ArgumentError} ;

@item 
remplacer les chaînes avec des arguments de formatage implicite (tels que @code{%default} ou @code{%prog}) par la syntaxe standard de Python pour l'interpolation d'un dictionnaire dans les chaînes de formatage (c'est-à-dire @code{%(default)s} et @code{%(prog)s}) ;

@item 
remplacer l'argument @code{version} du constructeur d'@code{OptionParser} par un appel à @code{parser.add_argument('--version', action='version', version='<la version>')}.
@end itemize

@node optparse --- Parser for command line options,getpass --- Portable password input,argparse --- Parser for command-line options arguments and subcommands,Command Line Interface Libraries
@anchor{library/optparse doc}@anchor{2e3c}@anchor{library/optparse module-optparse}@anchor{9f}@anchor{library/optparse optparse-parser-for-command-line-options}@anchor{2e3d}
@subsection @code{optparse} --- Parser for command line options


@geindex module; optparse

`Code source :' Lib/optparse.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/optparse.py}


__________________________________________________________________


@menu
* Choosing an argument parsing library:: 
* Introduction: Introduction<7>. 
* Background:: 
* Tutoriel: Tutoriel<2>. 
* Reference Guide:: 
* Option Callbacks:: 
* Extending optparse:: 
* Exceptions: Exceptions<10>. 

@end menu

@node Choosing an argument parsing library,Introduction<7>,,optparse --- Parser for command line options
@anchor{library/optparse choosing-an-argument-parser}@anchor{2dcd}@anchor{library/optparse choosing-an-argument-parsing-library}@anchor{2e3e}
@subsubsection Choosing an argument parsing library


The standard library includes three argument parsing libraries:


@itemize *

@item 
@ref{60,,getopt}: a module that closely mirrors the procedural C @code{getopt} API.
Included in the standard library since before the initial Python 1.0 release.

@item 
@ref{9f,,optparse}: a declarative replacement for @code{getopt} that
provides equivalent functionality without requiring each application
to implement its own procedural option parsing logic. Included
in the standard library since the Python 2.3 release.

@item 
@ref{6,,argparse}: a more opinionated alternative to @code{optparse} that
provides more functionality by default, at the expense of reduced application
flexibility in controlling exactly how arguments are processed. Included in
the standard library since the Python 2.7 and Python 3.2 releases.
@end itemize

In the absence of more specific argument parsing design constraints, @ref{6,,argparse}
is the recommended choice for implementing command line applications, as it offers
the highest level of baseline functionality with the least application level code.

@ref{60,,getopt} is retained almost entirely for backwards compatibility reasons.
However, it also serves a niche use case as a tool for prototyping and testing
command line argument handling in @code{getopt}-based C applications.

@ref{9f,,optparse} should be considered as an alternative to @ref{6,,argparse} in the
following cases:


@itemize *

@item 
an application is already using @ref{9f,,optparse} and doesn't want to risk the
subtle behavioural changes that may arise when migrating to @ref{6,,argparse}

@item 
the application requires additional control over the way options and
positional parameters are interleaved on the command line (including
the ability to disable the interleaving feature completely)

@item 
the application requires additional control over the incremental parsing
of command line elements (while @code{argparse} does support this, the
exact way it works in practice is undesirable for some use cases)

@item 
the application requires additional control over the handling of options
which accept parameter values that may start with @code{-} (such as delegated
options to be passed to invoked subprocesses)

@item 
the application requires some other command line parameter processing
behavior which @code{argparse} does not support, but which can be implemented
in terms of the lower level interface offered by @code{optparse}
@end itemize

These considerations also mean that @ref{9f,,optparse} is likely to provide a
better foundation for library authors writing third party command line
argument processing libraries.

As a concrete example, consider the following two command line argument
parsing configurations, the first using @code{optparse}, and the second
using @code{argparse}:

@example
import optparse

if __name__ == '__main__':
    parser = optparse.OptionParser()
    parser.add_option('-o', '--output')
    parser.add_option('-v', dest='verbose', action='store_true')
    opts, args = parser.parse_args()
    process(args, output=opts.output, verbose=opts.verbose)
@end example

@example
import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    parser.add_argument('rest', nargs='*')
    args = parser.parse_args()
    process(args.rest, output=args.output, verbose=args.verbose)
@end example

The most obvious difference is that in the @code{optparse} version, the non-option
arguments are processed separately by the application after the option processing
is complete. In the @code{argparse} version, positional arguments are declared and
processed in the same way as the named options.

However, the @code{argparse} version will also handle some parameter combination
differently from the way the @code{optparse} version would handle them.
For example (amongst other differences):


@itemize *

@item 
supplying @code{-o -v} gives @code{output="-v"} and @code{verbose=False}
when using @code{optparse}, but a usage error with @code{argparse}
(complaining that no value has been supplied for @code{-o/--output},
since @code{-v} is interpreted as meaning the verbosity flag)

@item 
similarly, supplying @code{-o --} gives @code{output="--"} and @code{args=()}
when using @code{optparse}, but a usage error with @code{argparse}
(also complaining that no value has been supplied for @code{-o/--output},
since @code{--} is interpreted as terminating the option processing
and treating all remaining values as positional arguments)

@item 
supplying @code{-o=foo} gives @code{output="=foo"} when using @code{optparse},
but gives @code{output="foo"} with @code{argparse} (since @code{=} is special
cased as an alternative separator for option parameter values)
@end itemize

Whether these differing behaviors in the @code{argparse} version are
considered desirable or a problem will depend on the specific command line
application use case.


@subsubheading Voir aussi


click@footnote{https://pypi.org/project/click/} is a third party argument processing library (originally
based on @code{optparse}), which allows command line applications to be
developed as a set of decorated command implementation functions.

Other third party libraries, such as typer@footnote{https://pypi.org/project/typer/} or msgspec-click@footnote{https://pypi.org/project/msgspec-click/},
allow command line interfaces to be specified in ways that more effectively
integrate with static checking of Python type annotations.


@node Introduction<7>,Background,Choosing an argument parsing library,optparse --- Parser for command line options
@anchor{library/optparse introduction}@anchor{2e3f}
@subsubsection Introduction


@ref{9f,,optparse} is a more convenient, flexible, and powerful library for parsing
command-line options than the minimalist @ref{60,,getopt} module.
@ref{9f,,optparse} uses a more declarative style of command-line parsing:
you create an instance of @ref{1483,,OptionParser},
populate it with options, and parse the command line.
@ref{9f,,optparse} allows users to specify options in the conventional
GNU/POSIX syntax, and additionally generates usage and help messages for you.

Here's an example of using @ref{9f,,optparse} in a simple script:

@example
from optparse import OptionParser
...
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
                  help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", default=True,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()
@end example

With these few lines of code, users of your script can now do the "usual thing"
on the command-line, for example:

@example
<yourscript> --file=outfile -q
@end example

As it parses the command line, @ref{9f,,optparse} sets attributes of the
@code{options} object returned by @ref{1484,,parse_args()} based on user-supplied
command-line values.  When @ref{1484,,parse_args()} returns from parsing this command
line, @code{options.filename} will be @code{"outfile"} and @code{options.verbose} will be
@code{False}.  @ref{9f,,optparse} supports both long and short options, allows short
options to be merged together, and allows options to be associated with their
arguments in a variety of ways.  Thus, the following command lines are all
equivalent to the above example:

@example
<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile
@end example

Additionally, users can run one of the following

@example
<yourscript> -h
<yourscript> --help
@end example

and @ref{9f,,optparse} will print out a brief summary of your script's options:

@example
Usage: <yourscript> [options]

Options:
  -h, --help            show this help message and exit
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout
@end example

where the value of `yourscript' is determined at runtime (normally from
@code{sys.argv[0]}).

@node Background,Tutoriel<2>,Introduction<7>,optparse --- Parser for command line options
@anchor{library/optparse background}@anchor{2e40}@anchor{library/optparse optparse-background}@anchor{2e41}
@subsubsection Background


@ref{9f,,optparse} was explicitly designed to encourage the creation of programs
with straightforward command-line interfaces that follow the conventions
established by the @code{getopt()} family of functions available to C developers.
To that end, it supports only the most common command-line syntax and semantics
conventionally used under Unix.  If you are unfamiliar with these conventions,
reading this section will allow you to acquaint yourself with them.

@menu
* Terminology:: 
* What are options for?:: 
* What are positional arguments for?:: 

@end menu

@node Terminology,What are options for?,,Background
@anchor{library/optparse optparse-terminology}@anchor{2e42}@anchor{library/optparse terminology}@anchor{2e43}
@subsubsection Terminology



@table @asis

@item argument

a string entered on the command-line, and passed by the shell to @code{execl()}
or @code{execv()}.  In Python, arguments are elements of @code{sys.argv[1:]}
(@code{sys.argv[0]} is the name of the program being executed).  Unix shells
also use the term "word".

It is occasionally desirable to substitute an argument list other than
@code{sys.argv[1:]}, so you should read "argument" as "an element of
@code{sys.argv[1:]}, or of some other list provided as a substitute for
@code{sys.argv[1:]}".

@item option

an argument used to supply extra information to guide or customize the
execution of a program.  There are many different syntaxes for options; the
traditional Unix syntax is a hyphen ("-") followed by a single letter,
e.g. @code{-x} or @code{-F}.  Also, traditional Unix syntax allows multiple
options to be merged into a single argument, e.g. @code{-x -F} is equivalent
to @code{-xF}.  The GNU project introduced @code{--} followed by a series of
hyphen-separated words, e.g. @code{--file} or @code{--dry-run}.  These are the
only two option syntaxes provided by @ref{9f,,optparse}.

Some other option syntaxes that the world has seen include:


@itemize *

@item 
a hyphen followed by a few letters, e.g. @code{-pf} (this is `not' the same
as multiple options merged into a single argument)

@item 
a hyphen followed by a whole word, e.g. @code{-file} (this is technically
equivalent to the previous syntax, but they aren't usually seen in the same
program)

@item 
a plus sign followed by a single letter, or a few letters, or a word, e.g.
@code{+f}, @code{+rgb}

@item 
a slash followed by a letter, or a few letters, or a word, e.g. @code{/f},
@code{/file}
@end itemize

These option syntaxes are not supported by @ref{9f,,optparse}, and they never
will be.  This is deliberate: the first three are non-standard on any
environment, and the last only makes sense if you're exclusively targeting
Windows or certain legacy platforms (e.g. VMS, MS-DOS).

@item option argument

an argument that follows an option, is closely associated with that option,
and is consumed from the argument list when that option is. With
@ref{9f,,optparse}, option arguments may either be in a separate argument from
their option:

@example
-f foo
--file foo
@end example

or included in the same argument:

@example
-ffoo
--file=foo
@end example

Typically, a given option either takes an argument or it doesn't. Lots of
people want an "optional option arguments" feature, meaning that some options
will take an argument if they see it, and won't if they don't.  This is
somewhat controversial, because it makes parsing ambiguous: if @code{-a} takes
an optional argument and @code{-b} is another option entirely, how do we
interpret @code{-ab}?  Because of this ambiguity, @ref{9f,,optparse} does not
support this feature.

@item argument positionnel

something leftover in the argument list after options have been parsed, i.e.
after options and their arguments have been parsed and removed from the
argument list.

@item required option

an option that must be supplied on the command-line; note that the phrase
"required option" is self-contradictory in English.  @ref{9f,,optparse} doesn't
prevent you from implementing required options, but doesn't give you much
help at it either.
@end table

For example, consider this hypothetical command-line:

@example
prog -v --report report.txt foo bar
@end example

@code{-v} and @code{--report} are both options.  Assuming that @code{--report}
takes one argument, @code{report.txt} is an option argument.  @code{foo} and
@code{bar} are positional arguments.

@node What are options for?,What are positional arguments for?,Terminology,Background
@anchor{library/optparse optparse-what-options-for}@anchor{2e44}@anchor{library/optparse what-are-options-for}@anchor{2e45}
@subsubsection What are options for?


Options are used to provide extra information to tune or customize the execution
of a program.  In case it wasn't clear, options are usually `optional'.  A
program should be able to run just fine with no options whatsoever.  (Pick a
random program from the Unix or GNU toolsets.  Can it run without any options at
all and still make sense?  The main exceptions are @code{find}, @code{tar}, and
@code{dd}---all of which are mutant oddballs that have been rightly criticized
for their non-standard syntax and confusing interfaces.)

Lots of people want their programs to have "required options".  Think about it.
If it's required, then it's `not optional'!  If there is a piece of information
that your program absolutely requires in order to run successfully, that's what
positional arguments are for.

As an example of good command-line interface design, consider the humble @code{cp}
utility, for copying files.  It doesn't make much sense to try to copy files
without supplying a destination and at least one source. Hence, @code{cp} fails if
you run it with no arguments.  However, it has a flexible, useful syntax that
does not require any options at all:

@example
cp SOURCE DEST
cp SOURCE ... DEST-DIR
@end example

You can get pretty far with just that.  Most @code{cp} implementations provide a
bunch of options to tweak exactly how the files are copied: you can preserve
mode and modification time, avoid following symlinks, ask before clobbering
existing files, etc.  But none of this distracts from the core mission of
@code{cp}, which is to copy either one file to another, or several files to another
directory.

@node What are positional arguments for?,,What are options for?,Background
@anchor{library/optparse optparse-what-positional-arguments-for}@anchor{2e46}@anchor{library/optparse what-are-positional-arguments-for}@anchor{2e47}
@subsubsection What are positional arguments for?


Positional arguments are for those pieces of information that your program
absolutely, positively requires to run.

A good user interface should have as few absolute requirements as possible.  If
your program requires 17 distinct pieces of information in order to run
successfully, it doesn't much matter `how' you get that information from the
user---most people will give up and walk away before they successfully run the
program.  This applies whether the user interface is a command-line, a
configuration file, or a GUI: if you make that many demands on your users, most
of them will simply give up.

In short, try to minimize the amount of information that users are absolutely
required to supply---use sensible defaults whenever possible.  Of course, you
also want to make your programs reasonably flexible.  That's what options are
for.  Again, it doesn't matter if they are entries in a config file, widgets in
the "Preferences" dialog of a GUI, or command-line options---the more options
you implement, the more flexible your program is, and the more complicated its
implementation becomes.  Too much flexibility has drawbacks as well, of course;
too many options can overwhelm users and make your code much harder to maintain.

@node Tutoriel<2>,Reference Guide,Background,optparse --- Parser for command line options
@anchor{library/optparse optparse-tutorial}@anchor{2e48}@anchor{library/optparse tutorial}@anchor{2e49}
@subsubsection Tutoriel


While @ref{9f,,optparse} is quite flexible and powerful, it's also straightforward
to use in most cases.  This section covers the code patterns that are common to
any @ref{9f,,optparse}-based program.

First, you need to import the OptionParser class; then, early in the main
program, create an OptionParser instance:

@example
from optparse import OptionParser
...
parser = OptionParser()
@end example

Then you can start defining options.  The basic syntax is:

@example
parser.add_option(opt_str, ...,
                  attr=value, ...)
@end example

Each option has one or more option strings, such as @code{-f} or @code{--file},
and several option attributes that tell @ref{9f,,optparse} what to expect and what
to do when it encounters that option on the command line.

Typically, each option will have one short option string and one long option
string, e.g.:

@example
parser.add_option("-f", "--file", ...)
@end example

You're free to define as many short option strings and as many long option
strings as you like (including zero), as long as there is at least one option
string overall.

The option strings passed to @ref{2e37,,OptionParser.add_option()} are effectively
labels for the
option defined by that call.  For brevity, we will frequently refer to
`encountering an option' on the command line; in reality, @ref{9f,,optparse}
encounters `option strings' and looks up options from them.

Once all of your options are defined, instruct @ref{9f,,optparse} to parse your
program's command line:

@example
(options, args) = parser.parse_args()
@end example

(If you like, you can pass a custom argument list to @ref{1484,,parse_args()}, but
that's rarely necessary: by default it uses @code{sys.argv[1:]}.)

@ref{1484,,parse_args()} returns two values:


@itemize *

@item 
@code{options}, an object containing values for all of your options---e.g. if
@code{--file} takes a single string argument, then @code{options.file} will be the
filename supplied by the user, or @code{None} if the user did not supply that
option

@item 
@code{args}, the list of positional arguments leftover after parsing options
@end itemize

This tutorial section only covers the four most important option attributes:
@ref{2e4a,,action}, @ref{2e4b,,type}, @ref{2e4c,,dest}
(destination), and @ref{2e4d,,help}. Of these, @ref{2e4a,,action} is the
most fundamental.

@menu
* Understanding option actions:: 
* The store action:: 
* Handling boolean (flag) options: Handling boolean flag options. 
* Other actions:: 
* Valeurs par défaut:: 
* Generating help:: 
* Printing a version string:: 
* How optparse handles errors:: 
* Putting it all together:: 

@end menu

@node Understanding option actions,The store action,,Tutoriel<2>
@anchor{library/optparse optparse-understanding-option-actions}@anchor{2e4e}@anchor{library/optparse understanding-option-actions}@anchor{2e4f}
@subsubsection Understanding option actions


Actions tell @ref{9f,,optparse} what to do when it encounters an option on the
command line.  There is a fixed set of actions hard-coded into @ref{9f,,optparse};
adding new actions is an advanced topic covered in section
@ref{2e50,,Extending optparse}.  Most actions tell @ref{9f,,optparse} to store
a value in some variable---for example, take a string from the command line and
store it in an attribute of @code{options}.

If you don't specify an option action, @ref{9f,,optparse} defaults to @code{store}.

@node The store action,Handling boolean flag options,Understanding option actions,Tutoriel<2>
@anchor{library/optparse optparse-store-action}@anchor{2e51}@anchor{library/optparse the-store-action}@anchor{2e52}
@subsubsection The store action


The most common option action is @code{store}, which tells @ref{9f,,optparse} to take
the next argument (or the remainder of the current argument), ensure that it is
of the correct type, and store it to your chosen destination.

Par exemple :

@example
parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")
@end example

Now let's make up a fake command line and ask @ref{9f,,optparse} to parse it:

@example
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
@end example

When @ref{9f,,optparse} sees the option string @code{-f}, it consumes the next
argument, @code{foo.txt}, and stores it in @code{options.filename}.  So, after this
call to @ref{1484,,parse_args()}, @code{options.filename} is @code{"foo.txt"}.

Some other option types supported by @ref{9f,,optparse} are @code{int} and @code{float}.
Here's an option that expects an integer argument:

@example
parser.add_option("-n", type="int", dest="num")
@end example

Note that this option has no long option string, which is perfectly acceptable.
Also, there's no explicit action, since the default is @code{store}.

Let's parse another fake command-line.  This time, we'll jam the option argument
right up against the option: since @code{-n42} (one argument) is equivalent to
@code{-n 42} (two arguments), the code

@example
(options, args) = parser.parse_args(["-n42"])
print(options.num)
@end example

affichera @code{42}.

If you don't specify a type, @ref{9f,,optparse} assumes @code{string}.  Combined with
the fact that the default action is @code{store}, that means our first example can
be a lot shorter:

@example
parser.add_option("-f", "--file", dest="filename")
@end example

If you don't supply a destination, @ref{9f,,optparse} figures out a sensible
default from the option strings: if the first long option string is
@code{--foo-bar}, then the default destination is @code{foo_bar}.  If there are no
long option strings, @ref{9f,,optparse} looks at the first short option string: the
default destination for @code{-f} is @code{f}.

@ref{9f,,optparse} also includes the built-in @code{complex} type.  Adding
types is covered in section @ref{2e50,,Extending optparse}.

@node Handling boolean flag options,Other actions,The store action,Tutoriel<2>
@anchor{library/optparse handling-boolean-flag-options}@anchor{2e53}@anchor{library/optparse optparse-handling-boolean-options}@anchor{2e54}
@subsubsection Handling boolean (flag) options


Flag options---set a variable to true or false when a particular option is
seen---are quite common.  @ref{9f,,optparse} supports them with two separate actions,
@code{store_true} and @code{store_false}.  For example, you might have a @code{verbose}
flag that is turned on with @code{-v} and off with @code{-q}:

@example
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
@end example

Here we have two different options with the same destination, which is perfectly
OK.  (It just means you have to be a bit careful when setting default
values---see below.)

When @ref{9f,,optparse} encounters @code{-v} on the command line, it sets
@code{options.verbose} to @code{True}; when it encounters @code{-q},
@code{options.verbose} is set to @code{False}.

@node Other actions,Valeurs par défaut,Handling boolean flag options,Tutoriel<2>
@anchor{library/optparse optparse-other-actions}@anchor{2e55}@anchor{library/optparse other-actions}@anchor{2e56}
@subsubsection Other actions


Some other actions supported by @ref{9f,,optparse} are:


@table @asis

@item @code{"store_const"}

store a constant value, pre-set via @ref{2e57,,Option.const}

@item @code{"append"}

append this option's argument to a list

@item @code{"count"}

increment a counter by one

@item @code{"callback"}

call a specified function
@end table

These are covered in section @ref{2e58,,Reference Guide},
and section @ref{2e59,,Option Callbacks}.

@node Valeurs par défaut,Generating help,Other actions,Tutoriel<2>
@anchor{library/optparse default-values}@anchor{2e5a}@anchor{library/optparse optparse-default-values}@anchor{2e5b}
@subsubsection Valeurs par défaut


All of the above examples involve setting some variable (the "destination") when
certain command-line options are seen.  What happens if those options are never
seen?  Since we didn't supply any defaults, they are all set to @code{None}.  This
is usually fine, but sometimes you want more control.  @ref{9f,,optparse} lets you
supply a default value for each destination, which is assigned before the
command line is parsed.

First, consider the verbose/quiet example.  If we want @ref{9f,,optparse} to set
@code{verbose} to @code{True} unless @code{-q} is seen, then we can do this:

@example
parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")
@end example

Since default values apply to the `destination' rather than to any particular
option, and these two options happen to have the same destination, this is
exactly equivalent:

@example
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)
@end example

Consider this:

@example
parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)
@end example

Again, the default value for @code{verbose} will be @code{True}: the last default
value supplied for any particular destination is the one that counts.

A clearer way to specify default values is the @code{set_defaults()} method of
OptionParser, which you can call at any time before calling
@ref{1484,,parse_args()}:

@example
parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()
@end example

As before, the last value specified for a given option destination is the one
that counts.  For clarity, try to use one method or the other of setting default
values, not both.

@node Generating help,Printing a version string,Valeurs par défaut,Tutoriel<2>
@anchor{library/optparse generating-help}@anchor{2e5c}@anchor{library/optparse optparse-generating-help}@anchor{2e5d}
@subsubsection Generating help


@ref{9f,,optparse}'s ability to generate help and usage text automatically is
useful for creating user-friendly command-line interfaces.  All you have to do
is supply a @ref{2e4d,,help} value for each option, and optionally a short
usage message for your whole program.  Here's an OptionParser populated with
user-friendly (documented) options:

@example
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=True,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose",
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
                  metavar="FILE", help="write output to FILE")
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: novice, intermediate, "
                       "or expert [default: %default]")
@end example

If @ref{9f,,optparse} encounters either @code{-h} or @code{--help} on the
command-line, or if you just call @code{parser.print_help()}, it prints the
following to standard output:

@example
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]
@end example

(If the help output is triggered by a help option, @ref{9f,,optparse} exits after
printing the help text.)

There's a lot going on here to help @ref{9f,,optparse} generate the best possible
help message:


@itemize *

@item 
the script defines its own usage message:

@example
usage = "usage: %prog [options] arg1 arg2"
@end example

@ref{9f,,optparse} expands @code{%prog} in the usage string to the name of the
current program, i.e. @code{os.path.basename(sys.argv[0])}.  The expanded string
is then printed before the detailed option help.

If you don't supply a usage string, @ref{9f,,optparse} uses a bland but sensible
default: @code{"Usage: %prog [options]"}, which is fine if your script doesn't
take any positional arguments.

@item 
every option defines a help string, and doesn't worry about
line-wrapping---@ref{9f,,optparse} takes care of wrapping lines and making
the help output look good.

@item 
options that take a value indicate this fact in their automatically generated
help message, e.g. for the "mode" option:

@example
-m MODE, --mode=MODE
@end example

Here, "MODE" is called the meta-variable: it stands for the argument that the
user is expected to supply to @code{-m}/@code{--mode}.  By default,
@ref{9f,,optparse} converts the destination variable name to uppercase and uses
that for the meta-variable.  Sometimes, that's not what you want---for
example, the @code{--filename} option explicitly sets @code{metavar="FILE"},
resulting in this automatically generated option description:

@example
-f FILE, --filename=FILE
@end example

This is important for more than just saving space, though: the manually
written help text uses the meta-variable @code{FILE} to clue the user in that
there's a connection between the semi-formal syntax @code{-f FILE} and the informal
semantic description "write output to FILE". This is a simple but effective
way to make your help text a lot clearer and more useful for end users.

@item 
options that have a default value can include @code{%default} in the help
string---@ref{9f,,optparse} will replace it with @ref{435,,str()} of the option's
default value.  If an option has no default value (or the default value is
@code{None}), @code{%default} expands to @code{none}.
@end itemize

@menu
* Grouping Options:: 

@end menu

@node Grouping Options,,,Generating help
@anchor{library/optparse grouping-options}@anchor{2e5e}
@subsubsection Grouping Options


When dealing with many options, it is convenient to group these options for
better help output.  An @ref{1483,,OptionParser} can contain several option groups,
each of which can contain several options.

An option group is obtained using the class @ref{2e5f,,OptionGroup}:

@geindex OptionGroup (classe dans optparse)
@anchor{library/optparse optparse OptionGroup}@anchor{2e5f}
@deffn {Classe} optparse.OptionGroup (parser, title, description=None)

where


@itemize *

@item 
parser is the @ref{1483,,OptionParser} instance the group will be inserted in
to

@item 
title is the group title

@item 
description, optional, is a long description of the group
@end itemize
@end deffn

@ref{2e5f,,OptionGroup} inherits from @code{OptionContainer} (like
@ref{1483,,OptionParser}) and so the @code{add_option()} method can be used to add
an option to the group.

Once all the options are declared, using the @ref{1483,,OptionParser} method
@code{add_option_group()} the group is added to the previously defined parser.

Continuing with the parser defined in the previous section, adding an
@ref{2e5f,,OptionGroup} to a parser is easy:

@example
group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk.  "
                    "It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
@end example

This would result in the following help output:

@example
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]

  Dangerous Options:
    Caution: use these options at your own risk.  It is believed that some
    of them bite.

    -g                  Group option.
@end example

A bit more complete example might involve using more than one group: still
extending the previous example:

@example
group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk.  "
                    "It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)

group = OptionGroup(parser, "Debug Options")
group.add_option("-d", "--debug", action="store_true",
                 help="Print debug information")
group.add_option("-s", "--sql", action="store_true",
                 help="Print all SQL statements executed")
group.add_option("-e", action="store_true", help="Print every action done")
parser.add_option_group(group)
@end example

that results in the following output:

@example
Usage: <yourscript> [options] arg1 arg2

Options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or expert
                        [default: intermediate]

  Dangerous Options:
    Caution: use these options at your own risk.  It is believed that some
    of them bite.

    -g                  Group option.

  Debug Options:
    -d, --debug         Print debug information
    -s, --sql           Print all SQL statements executed
    -e                  Print every action done
@end example

Another interesting method, in particular when working programmatically with
option groups is:

@geindex get_option_group() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_option_group}@anchor{2e60}
@deffn {Méthode} OptionParser.get_option_group (opt_str)

Return the @ref{2e5f,,OptionGroup} to which the short or long option
string `opt_str' (e.g. @code{'-o'} or @code{'--option'}) belongs. If
there's no such @ref{2e5f,,OptionGroup}, return @code{None}.
@end deffn

@node Printing a version string,How optparse handles errors,Generating help,Tutoriel<2>
@anchor{library/optparse optparse-printing-version-string}@anchor{2e61}@anchor{library/optparse printing-a-version-string}@anchor{2e62}
@subsubsection Printing a version string


Similar to the brief usage string, @ref{9f,,optparse} can also print a version
string for your program.  You have to supply the string as the @code{version}
argument to OptionParser:

@example
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
@end example

@code{%prog} is expanded just like it is in @code{usage}.  Apart from that,
@code{version} can contain anything you like.  When you supply it, @ref{9f,,optparse}
automatically adds a @code{--version} option to your parser. If it encounters
this option on the command line, it expands your @code{version} string (by
replacing @code{%prog}), prints it to stdout, and exits.

For example, if your script is called @code{/usr/bin/foo}:

@example
$ /usr/bin/foo --version
foo 1.0
@end example

The following two methods can be used to print and get the @code{version} string:

@geindex print_version() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser print_version}@anchor{2e63}
@deffn {Méthode} OptionParser.print_version (file=None)

Print the version message for the current program (@code{self.version}) to
`file' (default stdout).  As with @ref{2e64,,print_usage()}, any occurrence
of @code{%prog} in @code{self.version} is replaced with the name of the current
program.  Does nothing if @code{self.version} is empty or undefined.
@end deffn

@geindex get_version() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_version}@anchor{2e65}
@deffn {Méthode} OptionParser.get_version ()

Same as @ref{2e63,,print_version()} but returns the version string instead of
printing it.
@end deffn

@node How optparse handles errors,Putting it all together,Printing a version string,Tutoriel<2>
@anchor{library/optparse how-optparse-handles-errors}@anchor{2e66}@anchor{library/optparse optparse-how-optparse-handles-errors}@anchor{2e67}
@subsubsection How @code{optparse} handles errors


There are two broad classes of errors that @ref{9f,,optparse} has to worry about:
programmer errors and user errors.  Programmer errors are usually erroneous
calls to @ref{2e37,,OptionParser.add_option()}, e.g. invalid option strings, unknown
option attributes, missing option attributes, etc.  These are dealt with in the
usual way: raise an exception (either @ref{2e3a,,optparse.OptionError} or
@ref{522,,TypeError}) and let the program crash.

Handling user errors is much more important, since they are guaranteed to happen
no matter how stable your code is.  @ref{9f,,optparse} can automatically detect
some user errors, such as bad option arguments (passing @code{-n 4x} where
@code{-n} takes an integer argument), missing arguments (@code{-n} at the end
of the command line, where @code{-n} takes an argument of any type).  Also,
you can call @code{OptionParser.error()} to signal an application-defined error
condition:

@example
(options, args) = parser.parse_args()
...
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")
@end example

In either case, @ref{9f,,optparse} handles the error the same way: it prints the
program's usage message and an error message to standard error and exits with
error status 2.

Consider the first example above, where the user passes @code{4x} to an option
that takes an integer:

@example
$ /usr/bin/foo -n 4x
Usage: foo [options]

foo: error: option -n: invalid integer value: '4x'
@end example

Or, where the user fails to pass a value at all:

@example
$ /usr/bin/foo -n
Usage: foo [options]

foo: error: -n option requires an argument
@end example

@ref{9f,,optparse}-generated error messages take care always to mention the
option involved in the error; be sure to do the same when calling
@code{OptionParser.error()} from your application code.

If @ref{9f,,optparse}'s default error-handling behaviour does not suit your needs,
you'll need to subclass OptionParser and override its @code{exit()}
and/or @code{error()} methods.

@node Putting it all together,,How optparse handles errors,Tutoriel<2>
@anchor{library/optparse optparse-putting-it-all-together}@anchor{2e68}@anchor{library/optparse putting-it-all-together}@anchor{2e69}
@subsubsection Putting it all together


Here's what @ref{9f,,optparse}-based scripts usually look like:

@example
from optparse import OptionParser
...
def main():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", dest="filename",
                      help="read data from FILENAME")
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose")
    ...
    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")
    if options.verbose:
        print("reading %s..." % options.filename)
    ...

if __name__ == "__main__":
    main()
@end example

@node Reference Guide,Option Callbacks,Tutoriel<2>,optparse --- Parser for command line options
@anchor{library/optparse optparse-reference-guide}@anchor{2e58}@anchor{library/optparse reference-guide}@anchor{2e6a}
@subsubsection Reference Guide


@menu
* Creating the parser:: 
* Populating the parser:: 
* Defining options:: 
* Option attributes:: 
* Standard option actions:: 
* Standard option types:: 
* Analyse des arguments:: 
* Querying and manipulating your option parser:: 
* Conflicts between options:: 
* Nettoyage:: 
* Other methods:: 

@end menu

@node Creating the parser,Populating the parser,,Reference Guide
@anchor{library/optparse creating-the-parser}@anchor{2e6b}@anchor{library/optparse optparse-creating-parser}@anchor{2e6c}
@subsubsection Creating the parser


The first step in using @ref{9f,,optparse} is to create an OptionParser instance.

@geindex OptionParser (classe dans optparse)
@anchor{library/optparse optparse OptionParser}@anchor{1483}
@deffn {Classe} optparse.OptionParser (...)

The OptionParser constructor has no required arguments, but a number of
optional keyword arguments.  You should always pass them as keyword
arguments, i.e. do not rely on the order in which the arguments are declared.


@table @asis

@item @code{usage} (default: @code{"%prog [options]"})

The usage summary to print when your program is run incorrectly or with a
help option.  When @ref{9f,,optparse} prints the usage string, it expands
@code{%prog} to @code{os.path.basename(sys.argv[0])} (or to @code{prog} if you
passed that keyword argument).  To suppress a usage message, pass the
special value @code{optparse.SUPPRESS_USAGE}.

@item @code{option_list} (default: @code{[]})

A list of Option objects to populate the parser with.  The options in
@code{option_list} are added after any options in @code{standard_option_list} (a
class attribute that may be set by OptionParser subclasses), but before
any version or help options. Deprecated; use @ref{2e37,,add_option()} after
creating the parser instead.

@item @code{option_class} (default: optparse.Option)

Class to use when adding options to the parser in @ref{2e37,,add_option()}.

@item @code{version} (default: @code{None})

A version string to print when the user supplies a version option. If you
supply a true value for @code{version}, @ref{9f,,optparse} automatically adds a
version option with the single option string @code{--version}.  The
substring @code{%prog} is expanded the same as for @code{usage}.

@item @code{conflict_handler} (default: @code{"error"})

Specifies what to do when options with conflicting option strings are
added to the parser; see section
@ref{2e6d,,Conflicts between options}.

@item @code{description} (default: @code{None})

A paragraph of text giving a brief overview of your program.
@ref{9f,,optparse} reformats this paragraph to fit the current terminal width
and prints it when the user requests help (after @code{usage}, but before the
list of options).

@item @code{formatter} (default: a new @code{IndentedHelpFormatter})

An instance of optparse.HelpFormatter that will be used for printing help
text.  @ref{9f,,optparse} provides two concrete classes for this purpose:
IndentedHelpFormatter and TitledHelpFormatter.

@item @code{add_help_option} (default: @code{True})

If true, @ref{9f,,optparse} will add a help option (with option strings @code{-h}
and @code{--help}) to the parser.

@item @code{prog}

The string to use when expanding @code{%prog} in @code{usage} and @code{version}
instead of @code{os.path.basename(sys.argv[0])}.

@item @code{epilog} (default: @code{None})

A paragraph of help text to print after the option help.
@end table
@end deffn

@node Populating the parser,Defining options,Creating the parser,Reference Guide
@anchor{library/optparse optparse-populating-parser}@anchor{2e6e}@anchor{library/optparse populating-the-parser}@anchor{2e6f}
@subsubsection Populating the parser


There are several ways to populate the parser with options.  The preferred way
is by using @ref{2e37,,OptionParser.add_option()}, as shown in section
@ref{2e48,,Tutoriel}.  @code{add_option()} can be called in one of two ways:


@itemize *

@item 
pass it an Option instance (as returned by @code{make_option()})

@item 
pass it any combination of positional and keyword arguments that are
acceptable to @code{make_option()} (i.e., to the Option constructor), and it
will create the Option instance for you
@end itemize

The other alternative is to pass a list of pre-constructed Option instances to
the OptionParser constructor, as in:

@example
option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)
@end example

(@code{make_option()} is a factory function for creating Option instances;
currently it is an alias for the Option constructor.  A future version of
@ref{9f,,optparse} may split Option into several classes, and @code{make_option()}
will pick the right class to instantiate.  Do not instantiate Option directly.)

@node Defining options,Option attributes,Populating the parser,Reference Guide
@anchor{library/optparse defining-options}@anchor{2e70}@anchor{library/optparse optparse-defining-options}@anchor{2e71}
@subsubsection Defining options


Each Option instance represents a set of synonymous command-line option strings,
e.g. @code{-f} and @code{--file}.  You can specify any number of short or
long option strings, but you must specify at least one overall option string.

The canonical way to create an @ref{2e72,,Option} instance is with the
@code{add_option()} method of @ref{1483,,OptionParser}.

@geindex add_option() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser add_option}@anchor{2e37}
@deffn {Méthode} OptionParser.add_option (option)

@deffnx {Méthode} OptionParser.add_option (*opt_str, attr=value, ...)

To define an option with only a short option string:

@example
parser.add_option("-f", attr=value, ...)
@end example

And to define an option with only a long option string:

@example
parser.add_option("--foo", attr=value, ...)
@end example

The keyword arguments define attributes of the new Option object.  The most
important option attribute is @ref{2e4a,,action}, and it largely
determines which other attributes are relevant or required.  If you pass
irrelevant option attributes, or fail to pass required ones, @ref{9f,,optparse}
raises an @ref{2e3a,,OptionError} exception explaining your mistake.

An option's `action' determines what @ref{9f,,optparse} does when it encounters
this option on the command-line.  The standard option actions hard-coded into
@ref{9f,,optparse} are:


@table @asis

@item @code{"store"}

store this option's argument (default)

@item @code{"store_const"}

store a constant value, pre-set via @ref{2e57,,Option.const}

@item @code{"store_true"}

store @code{True}

@item @code{"store_false"}

store @code{False}

@item @code{"append"}

append this option's argument to a list

@item @code{"append_const"}

append a constant value to a list, pre-set via @ref{2e57,,Option.const}

@item @code{"count"}

increment a counter by one

@item @code{"callback"}

call a specified function

@item @code{"help"}

print a usage message including all options and the documentation for them
@end table

(If you don't supply an action, the default is @code{"store"}.  For this action,
you may also supply @ref{2e4b,,type} and @ref{2e4c,,dest} option
attributes; see @ref{2e73,,Standard option actions}.)
@end deffn

As you can see, most actions involve storing or updating a value somewhere.
@ref{9f,,optparse} always creates a special object for this, conventionally called
@code{options}, which is an instance of @ref{2e39,,optparse.Values}.

@geindex Values (classe dans optparse)
@anchor{library/optparse optparse Values}@anchor{2e39}
@deffn {Classe} optparse.Values

An object holding parsed argument names and values as attributes.
Normally created by calling when calling @ref{1484,,OptionParser.parse_args()},
and can be overridden by a custom subclass passed to the `values' argument of
@ref{1484,,OptionParser.parse_args()} (as described in @ref{2e74,,Analyse des arguments}).
@end deffn

Option
arguments (and various other values) are stored as attributes of this object,
according to the @ref{2e4c,,dest} (destination) option attribute.

For example, when you call

@example
parser.parse_args()
@end example

one of the first things @ref{9f,,optparse} does is create the @code{options} object:

@example
options = Values()
@end example

If one of the options in this parser is defined with

@example
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
@end example

and the command-line being parsed includes any of the following:

@example
-ffoo
-f foo
--file=foo
--file foo
@end example

then @ref{9f,,optparse}, on seeing this option, will do the equivalent of

@example
options.filename = "foo"
@end example

The @ref{2e4b,,type} and @ref{2e4c,,dest} option attributes are almost
as important as @ref{2e4a,,action}, but @ref{2e4a,,action} is the only
one that makes sense for `all' options.

@node Option attributes,Standard option actions,Defining options,Reference Guide
@anchor{library/optparse option-attributes}@anchor{2e75}@anchor{library/optparse optparse-option-attributes}@anchor{2e76}
@subsubsection Option attributes


@geindex Option (classe dans optparse)
@anchor{library/optparse optparse Option}@anchor{2e72}
@deffn {Classe} optparse.Option

A single command line argument,
with various attributes passed by keyword to the constructor.
Normally created with @ref{2e37,,OptionParser.add_option()} rather than directly,
and can be overridden by a custom class via the `option_class' argument
to @ref{1483,,OptionParser}.
@end deffn

The following option attributes may be passed as keyword arguments to
@ref{2e37,,OptionParser.add_option()}.  If you pass an option attribute that is not
relevant to a particular option, or fail to pass a required option attribute,
@ref{9f,,optparse} raises @ref{2e3a,,OptionError}.

@geindex action (attribut optparse.Option)
@anchor{library/optparse optparse Option action}@anchor{2e4a}
@deffn {Attribut} Option.action

(default: @code{"store"})

Determines @ref{9f,,optparse}'s behaviour when this option is seen on the
command line; the available options are documented @ref{2e73,,here}.
@end deffn

@geindex type (attribut optparse.Option)
@anchor{library/optparse optparse Option type}@anchor{2e4b}
@deffn {Attribut} Option.type

(default: @code{"string"})

The argument type expected by this option (e.g., @code{"string"} or @code{"int"});
the available option types are documented @ref{2e77,,here}.
@end deffn

@geindex dest (attribut optparse.Option)
@anchor{library/optparse optparse Option dest}@anchor{2e4c}
@deffn {Attribut} Option.dest

(default: derived from option strings)

If the option's action implies writing or modifying a value somewhere, this
tells @ref{9f,,optparse} where to write it: @ref{2e4c,,dest} names an
attribute of the @code{options} object that @ref{9f,,optparse} builds as it parses
the command line.
@end deffn

@geindex default (attribut optparse.Option)
@anchor{library/optparse optparse Option default}@anchor{2e78}
@deffn {Attribut} Option.default

The value to use for this option's destination if the option is not seen on
the command line.  See also @ref{2e79,,OptionParser.set_defaults()}.
@end deffn

@geindex nargs (attribut optparse.Option)
@anchor{library/optparse optparse Option nargs}@anchor{2e7a}
@deffn {Attribut} Option.nargs

(default: 1)

How many arguments of type @ref{2e4b,,type} should be consumed when this
option is seen.  If > 1, @ref{9f,,optparse} will store a tuple of values to
@ref{2e4c,,dest}.
@end deffn

@geindex const (attribut optparse.Option)
@anchor{library/optparse optparse Option const}@anchor{2e57}
@deffn {Attribut} Option.const

For actions that store a constant value, the constant value to store.
@end deffn

@geindex choices (attribut optparse.Option)
@anchor{library/optparse optparse Option choices}@anchor{2e7b}
@deffn {Attribut} Option.choices

For options of type @code{"choice"}, the list of strings the user may choose
from.
@end deffn

@geindex callback (attribut optparse.Option)
@anchor{library/optparse optparse Option callback}@anchor{2e7c}
@deffn {Attribut} Option.callback

For options with action @code{"callback"}, the callable to call when this option
is seen.  See section @ref{2e59,,Option Callbacks} for detail on the
arguments passed to the callable.
@end deffn

@geindex callback_args (attribut optparse.Option)
@geindex callback_kwargs (attribut optparse.Option)
@anchor{library/optparse optparse Option callback_args}@anchor{2e7d}
@deffn {Attribut} Option.callback_args
@anchor{library/optparse optparse Option callback_kwargs}@anchor{2e7e}
@deffnx {Attribut} Option.callback_kwargs

Additional positional and keyword arguments to pass to @code{callback} after the
four standard callback arguments.
@end deffn

@geindex help (attribut optparse.Option)
@anchor{library/optparse optparse Option help}@anchor{2e4d}
@deffn {Attribut} Option.help

Help text to print for this option when listing all available options after
the user supplies a @ref{2e4d,,help} option (such as @code{--help}).  If
no help text is supplied, the option will be listed without help text.  To
hide this option, use the special value @code{optparse.SUPPRESS_HELP}.
@end deffn

@geindex metavar (attribut optparse.Option)
@anchor{library/optparse optparse Option metavar}@anchor{2e7f}
@deffn {Attribut} Option.metavar

(default: derived from option strings)

Stand-in for the option argument(s) to use when printing help text.  See
section @ref{2e48,,Tutoriel} for an example.
@end deffn

@node Standard option actions,Standard option types,Option attributes,Reference Guide
@anchor{library/optparse optparse-standard-option-actions}@anchor{2e73}@anchor{library/optparse standard-option-actions}@anchor{2e80}
@subsubsection Standard option actions


The various option actions all have slightly different requirements and effects.
Most actions have several relevant option attributes which you may specify to
guide @ref{9f,,optparse}'s behaviour; a few have required attributes, which you
must specify for any option using that action.


@itemize *

@item 
@code{"store"} [relevant: @ref{2e4b,,type}, @ref{2e4c,,dest},
@ref{2e7a,,nargs}, @ref{2e7b,,choices}]

The option must be followed by an argument, which is converted to a value
according to @ref{2e4b,,type} and stored in @ref{2e4c,,dest}.  If
@ref{2e7a,,nargs} > 1, multiple arguments will be consumed from the
command line; all will be converted according to @ref{2e4b,,type} and
stored to @ref{2e4c,,dest} as a tuple.  See the
@ref{2e77,,Standard option types} section.

If @ref{2e7b,,choices} is supplied (a list or tuple of strings), the type
defaults to @code{"choice"}.

If @ref{2e4b,,type} is not supplied, it defaults to @code{"string"}.

If @ref{2e4c,,dest} is not supplied, @ref{9f,,optparse} derives a destination
from the first long option string (e.g., @code{--foo-bar} implies
@code{foo_bar}). If there are no long option strings, @ref{9f,,optparse} derives a
destination from the first short option string (e.g., @code{-f} implies @code{f}).

Exemple :

@example
parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")
@end example

As it parses the command line

@example
-f foo.txt -p 1 -3.5 4 -fbar.txt
@end example

@ref{9f,,optparse} will set

@example
options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"
@end example

@item 
@code{"store_const"} [required: @ref{2e57,,const}; relevant:
@ref{2e4c,,dest}]

The value @ref{2e57,,const} is stored in @ref{2e4c,,dest}.

Exemple :

@example
parser.add_option("-q", "--quiet",
                  action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
                  action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
                  action="store_const", const=2, dest="verbose")
@end example

If @code{--noisy} is seen, @ref{9f,,optparse} will set

@example
options.verbose = 2
@end example

@item 
@code{"store_true"} [relevant: @ref{2e4c,,dest}]

A special case of @code{"store_const"} that stores @code{True} to
@ref{2e4c,,dest}.

@item 
@code{"store_false"} [relevant: @ref{2e4c,,dest}]

Like @code{"store_true"}, but stores @code{False}.

Exemple :

@example
parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")
@end example

@item 
@code{"append"} [relevant: @ref{2e4b,,type}, @ref{2e4c,,dest},
@ref{2e7a,,nargs}, @ref{2e7b,,choices}]

The option must be followed by an argument, which is appended to the list in
@ref{2e4c,,dest}.  If no default value for @ref{2e4c,,dest} is
supplied, an empty list is automatically created when @ref{9f,,optparse} first
encounters this option on the command-line.  If @ref{2e7a,,nargs} > 1,
multiple arguments are consumed, and a tuple of length @ref{2e7a,,nargs}
is appended to @ref{2e4c,,dest}.

The defaults for @ref{2e4b,,type} and @ref{2e4c,,dest} are the same as
for the @code{"store"} action.

Exemple :

@example
parser.add_option("-t", "--tracks", action="append", type="int")
@end example

If @code{-t3} is seen on the command-line, @ref{9f,,optparse} does the equivalent
of:

@example
options.tracks = []
options.tracks.append(int("3"))
@end example

If, a little later on, @code{--tracks=4} is seen, it does:

@example
options.tracks.append(int("4"))
@end example

The @code{append} action calls the @code{append} method on the current value of the
option.  This means that any default value specified must have an @code{append}
method.  It also means that if the default value is non-empty, the default
elements will be present in the parsed value for the option, with any values
from the command line appended after those default values:

@example
>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']
@end example

@item 
@code{"append_const"} [required: @ref{2e57,,const}; relevant:
@ref{2e4c,,dest}]

Like @code{"store_const"}, but the value @ref{2e57,,const} is appended to
@ref{2e4c,,dest}; as with @code{"append"}, @ref{2e4c,,dest} defaults to
@code{None}, and an empty list is automatically created the first time the option
is encountered.

@item 
@code{"count"} [relevant: @ref{2e4c,,dest}]

Increment the integer stored at @ref{2e4c,,dest}.  If no default value is
supplied, @ref{2e4c,,dest} is set to zero before being incremented the
first time.

Exemple :

@example
parser.add_option("-v", action="count", dest="verbosity")
@end example

The first time @code{-v} is seen on the command line, @ref{9f,,optparse} does the
equivalent of:

@example
options.verbosity = 0
options.verbosity += 1
@end example

Every subsequent occurrence of @code{-v} results in

@example
options.verbosity += 1
@end example

@item 
@code{"callback"} [required: @ref{2e7c,,callback}; relevant:
@ref{2e4b,,type}, @ref{2e7a,,nargs}, @ref{2e7d,,callback_args},
@ref{2e7e,,callback_kwargs}]

Call the function specified by @ref{2e7c,,callback}, which is called as

@example
func(option, opt_str, value, parser, *args, **kwargs)
@end example

See section @ref{2e59,,Option Callbacks} for more detail.

@item 
@code{"help"}

Prints a complete help message for all the options in the current option
parser.  The help message is constructed from the @code{usage} string passed to
OptionParser's constructor and the @ref{2e4d,,help} string passed to every
option.

If no @ref{2e4d,,help} string is supplied for an option, it will still be
listed in the help message.  To omit an option entirely, use the special value
@code{optparse.SUPPRESS_HELP}.

@ref{9f,,optparse} automatically adds a @ref{2e4d,,help} option to all
OptionParsers, so you do not normally need to create one.

Exemple :

@example
from optparse import OptionParser, SUPPRESS_HELP

# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
parser = OptionParser(add_help_option=False)

parser.add_option("-h", "--help", action="help")
parser.add_option("-v", action="store_true", dest="verbose",
                  help="Be moderately verbose")
parser.add_option("--file", dest="filename",
                  help="Input file to read data from")
parser.add_option("--secret", help=SUPPRESS_HELP)
@end example

If @ref{9f,,optparse} sees either @code{-h} or @code{--help} on the command line,
it will print something like the following help message to stdout (assuming
@code{sys.argv[0]} is @code{"foo.py"}):

@example
Usage: foo.py [options]

Options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from
@end example

After printing the help message, @ref{9f,,optparse} terminates your process with
@code{sys.exit(0)}.

@item 
@code{"version"}

Prints the version number supplied to the OptionParser to stdout and exits.
The version number is actually formatted and printed by the
@code{print_version()} method of OptionParser.  Generally only relevant if the
@code{version} argument is supplied to the OptionParser constructor.  As with
@ref{2e4d,,help} options, you will rarely create @code{version} options,
since @ref{9f,,optparse} automatically adds them when needed.
@end itemize

@node Standard option types,Analyse des arguments,Standard option actions,Reference Guide
@anchor{library/optparse optparse-standard-option-types}@anchor{2e77}@anchor{library/optparse standard-option-types}@anchor{2e81}
@subsubsection Standard option types


@ref{9f,,optparse} has five built-in option types: @code{"string"}, @code{"int"},
@code{"choice"}, @code{"float"} and @code{"complex"}.  If you need to add new
option types, see section @ref{2e50,,Extending optparse}.

Arguments to string options are not checked or converted in any way: the text on
the command line is stored in the destination (or passed to the callback) as-is.

Integer arguments (type @code{"int"}) are parsed as follows:


@itemize *

@item 
if the number starts with @code{0x}, it is parsed as a hexadecimal number

@item 
if the number starts with @code{0}, it is parsed as an octal number

@item 
if the number starts with @code{0b}, it is parsed as a binary number

@item 
otherwise, the number is parsed as a decimal number
@end itemize

The conversion is done by calling @ref{254,,int()} with the appropriate base (2, 8,
10, or 16).  If this fails, so will @ref{9f,,optparse}, although with a more useful
error message.

@code{"float"} and @code{"complex"} option arguments are converted directly with
@ref{2eb,,float()} and @ref{2ec,,complex()}, with similar error-handling.

@code{"choice"} options are a subtype of @code{"string"} options.  The
@ref{2e7b,,choices} option attribute (a sequence of strings) defines the
set of allowed option arguments.  @code{optparse.check_choice()} compares
user-supplied option arguments against this master list and raises
@ref{2e3b,,OptionValueError} if an invalid string is given.

@node Analyse des arguments,Querying and manipulating your option parser,Standard option types,Reference Guide
@anchor{library/optparse optparse-parsing-arguments}@anchor{2e74}@anchor{library/optparse parsing-arguments}@anchor{2e82}
@subsubsection Analyse des arguments


The whole point of creating and populating an OptionParser is to call its
@ref{1484,,parse_args()} method.

@geindex parse_args() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser parse_args}@anchor{1484}
@deffn {Méthode} OptionParser.parse_args (args=None, values=None)

Parse the command-line options found in `args'.

The input parameters are


@table @asis

@item @code{args}

the list of arguments to process (default: @code{sys.argv[1:]})

@item @code{values}

a @ref{2e39,,Values} object to store option arguments in (default: a
new instance of @ref{2e39,,Values}) -- if you give an existing object, the
option defaults will not be initialized on it
@end table

and the return value is a pair @code{(options, args)} where


@table @asis

@item @code{options}

the same object that was passed in as `values', or the @code{optparse.Values}
instance created by @ref{9f,,optparse}

@item @code{args}

the leftover positional arguments after all options have been processed
@end table
@end deffn

The most common usage is to supply neither keyword argument.  If you supply
@code{values}, it will be modified with repeated @ref{20e1,,setattr()} calls (roughly one
for every option argument stored to an option destination) and returned by
@ref{1484,,parse_args()}.

If @ref{1484,,parse_args()} encounters any errors in the argument list, it calls the
OptionParser's @code{error()} method with an appropriate end-user error message.
This ultimately terminates your process with an exit status of 2 (the
traditional Unix exit status for command-line errors).

@node Querying and manipulating your option parser,Conflicts between options,Analyse des arguments,Reference Guide
@anchor{library/optparse optparse-querying-manipulating-option-parser}@anchor{2e83}@anchor{library/optparse querying-and-manipulating-your-option-parser}@anchor{2e84}
@subsubsection Querying and manipulating your option parser


The default behavior of the option parser can be customized slightly, and you
can also poke around your option parser and see what's there.  OptionParser
provides several methods to help you out:

@geindex disable_interspersed_args() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser disable_interspersed_args}@anchor{2e38}
@deffn {Méthode} OptionParser.disable_interspersed_args ()

Set parsing to stop on the first non-option.  For example, if @code{-a} and
@code{-b} are both simple options that take no arguments, @ref{9f,,optparse}
normally accepts this syntax:

@example
prog -a arg1 -b arg2
@end example

and treats it as equivalent to

@example
prog -a -b arg1 arg2
@end example

To disable this feature, call @ref{2e38,,disable_interspersed_args()}.  This
restores traditional Unix syntax, where option parsing stops with the first
non-option argument.

Use this if you have a command processor which runs another command which has
options of its own and you want to make sure these options don't get
confused.  For example, each command might have a different set of options.
@end deffn

@geindex enable_interspersed_args() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser enable_interspersed_args}@anchor{2e85}
@deffn {Méthode} OptionParser.enable_interspersed_args ()

Set parsing to not stop on the first non-option, allowing interspersing
switches with command arguments.  This is the default behavior.
@end deffn

@geindex get_option() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_option}@anchor{2e86}
@deffn {Méthode} OptionParser.get_option (opt_str)

Returns the Option instance with the option string `opt_str', or @code{None} if
no options have that option string.
@end deffn

@geindex has_option() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser has_option}@anchor{2e87}
@deffn {Méthode} OptionParser.has_option (opt_str)

Return @code{True} if the OptionParser has an option with option string `opt_str'
(e.g., @code{-q} or @code{--verbose}).
@end deffn

@geindex remove_option() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser remove_option}@anchor{2e88}
@deffn {Méthode} OptionParser.remove_option (opt_str)

If the @ref{1483,,OptionParser} has an option corresponding to `opt_str', that
option is removed.  If that option provided any other option strings, all of
those option strings become invalid. If `opt_str' does not occur in any
option belonging to this @ref{1483,,OptionParser}, raises @ref{1ff,,ValueError}.
@end deffn

@node Conflicts between options,Nettoyage,Querying and manipulating your option parser,Reference Guide
@anchor{library/optparse conflicts-between-options}@anchor{2e89}@anchor{library/optparse optparse-conflicts-between-options}@anchor{2e6d}
@subsubsection Conflicts between options


If you're not careful, it's easy to define options with conflicting option
strings:

@example
parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)
@end example

(This is particularly true if you've defined your own OptionParser subclass with
some standard options.)

Every time you add an option, @ref{9f,,optparse} checks for conflicts with existing
options.  If it finds any, it invokes the current conflict-handling mechanism.
You can set the conflict-handling mechanism either in the constructor:

@example
parser = OptionParser(..., conflict_handler=handler)
@end example

or with a separate call:

@example
parser.set_conflict_handler(handler)
@end example

The available conflict handlers are:

@quotation


@table @asis

@item @code{"error"} (default)

assume option conflicts are a programming error and raise
@ref{2e8a,,OptionConflictError}

@item @code{"resolve"}

resolve option conflicts intelligently (see below)
@end table
@end quotation

As an example, let's define an @ref{1483,,OptionParser} that resolves conflicts
intelligently and add conflicting options to it:

@example
parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
@end example

At this point, @ref{9f,,optparse} detects that a previously added option is already
using the @code{-n} option string.  Since @code{conflict_handler} is @code{"resolve"},
it resolves the situation by removing @code{-n} from the earlier option's list of
option strings.  Now @code{--dry-run} is the only way for the user to activate
that option.  If the user asks for help, the help message will reflect that:

@example
Options:
  --dry-run     do no harm
  ...
  -n, --noisy   be noisy
@end example

It's possible to whittle away the option strings for a previously added option
until there are none left, and the user has no way of invoking that option from
the command-line.  In that case, @ref{9f,,optparse} removes that option completely,
so it doesn't show up in help text or anywhere else. Carrying on with our
existing OptionParser:

@example
parser.add_option("--dry-run", ..., help="new dry-run option")
@end example

At this point, the original @code{-n}/@code{--dry-run} option is no longer
accessible, so @ref{9f,,optparse} removes it, leaving this help text:

@example
Options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option
@end example

@node Nettoyage,Other methods,Conflicts between options,Reference Guide
@anchor{library/optparse cleanup}@anchor{2e8b}@anchor{library/optparse optparse-cleanup}@anchor{2e8c}
@subsubsection Nettoyage


OptionParser instances have several cyclic references.  This should not be a
problem for Python's garbage collector, but you may wish to break the cyclic
references explicitly by calling @code{destroy()} on your
OptionParser once you are done with it.  This is particularly useful in
long-running applications where large object graphs are reachable from your
OptionParser.

@node Other methods,,Nettoyage,Reference Guide
@anchor{library/optparse optparse-other-methods}@anchor{2e8d}@anchor{library/optparse other-methods}@anchor{2e8e}
@subsubsection Other methods


OptionParser supports several other public methods:

@geindex set_usage() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser set_usage}@anchor{2e8f}
@deffn {Méthode} OptionParser.set_usage (usage)

Set the usage string according to the rules described above for the @code{usage}
constructor keyword argument.  Passing @code{None} sets the default usage
string; use @code{optparse.SUPPRESS_USAGE} to suppress a usage message.
@end deffn

@geindex print_usage() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser print_usage}@anchor{2e64}
@deffn {Méthode} OptionParser.print_usage (file=None)

Print the usage message for the current program (@code{self.usage}) to `file'
(default stdout).  Any occurrence of the string @code{%prog} in @code{self.usage}
is replaced with the name of the current program.  Does nothing if
@code{self.usage} is empty or not defined.
@end deffn

@geindex get_usage() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser get_usage}@anchor{2e90}
@deffn {Méthode} OptionParser.get_usage ()

Same as @ref{2e64,,print_usage()} but returns the usage string instead of
printing it.
@end deffn

@geindex set_defaults() (méthode optparse.OptionParser)
@anchor{library/optparse optparse OptionParser set_defaults}@anchor{2e79}
@deffn {Méthode} OptionParser.set_defaults (dest=value, ...)

Set default values for several option destinations at once.  Using
@ref{2e79,,set_defaults()} is the preferred way to set default values for options,
since multiple options can share the same destination.  For example, if
several "mode" options all set the same destination, any one of them can set
the default, and the last one wins:

@example
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced",
                  default="novice")    # overridden below
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice",
                  default="advanced")  # overrides above setting
@end example

To avoid this confusion, use @ref{2e79,,set_defaults()}:

@example
parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice")
@end example
@end deffn

@node Option Callbacks,Extending optparse,Reference Guide,optparse --- Parser for command line options
@anchor{library/optparse option-callbacks}@anchor{2e91}@anchor{library/optparse optparse-option-callbacks}@anchor{2e59}
@subsubsection Option Callbacks


When @ref{9f,,optparse}'s built-in actions and types aren't quite enough for your
needs, you have two choices: extend @ref{9f,,optparse} or define a callback option.
Extending @ref{9f,,optparse} is more general, but overkill for a lot of simple
cases.  Quite often a simple callback is all you need.

There are two steps to defining a callback option:


@itemize *

@item 
define the option itself using the @code{"callback"} action

@item 
write the callback; this is a function (or method) that takes at least four
arguments, as described below
@end itemize

@menu
* Defining a callback option:: 
* How callbacks are called:: 
* Raising errors in a callback:: 
* Callback example 1; trivial callback: Callback example 1 trivial callback. 
* Callback example 2; check option order: Callback example 2 check option order. 
* Callback example 3; check option order (generalized): Callback example 3 check option order generalized. 
* Callback example 4; check arbitrary condition: Callback example 4 check arbitrary condition. 
* Callback example 5; fixed arguments: Callback example 5 fixed arguments. 
* Callback example 6; variable arguments: Callback example 6 variable arguments. 

@end menu

@node Defining a callback option,How callbacks are called,,Option Callbacks
@anchor{library/optparse defining-a-callback-option}@anchor{2e92}@anchor{library/optparse optparse-defining-callback-option}@anchor{2e93}
@subsubsection Defining a callback option


As always, the easiest way to define a callback option is by using the
@ref{2e37,,OptionParser.add_option()} method.  Apart from @ref{2e4a,,action}, the
only option attribute you must specify is @code{callback}, the function to call:

@example
parser.add_option("-c", action="callback", callback=my_callback)
@end example

@code{callback} is a function (or other callable object), so you must have already
defined @code{my_callback()} when you create this callback option. In this simple
case, @ref{9f,,optparse} doesn't even know if @code{-c} takes any arguments,
which usually means that the option takes no arguments---the mere presence of
@code{-c} on the command-line is all it needs to know.  In some
circumstances, though, you might want your callback to consume an arbitrary
number of command-line arguments.  This is where writing callbacks gets tricky;
it's covered later in this section.

@ref{9f,,optparse} always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via
@ref{2e7d,,callback_args} and @ref{2e7e,,callback_kwargs}.  Thus, the
minimal callback function signature is:

@example
def my_callback(option, opt, value, parser):
@end example

The four arguments to a callback are described below.

There are several other option attributes that you can supply when you define a
callback option:


@table @asis

@item @ref{2e4b,,type}

has its usual meaning: as with the @code{"store"} or @code{"append"} actions, it
instructs @ref{9f,,optparse} to consume one argument and convert it to
@ref{2e4b,,type}.  Rather than storing the converted value(s) anywhere,
though, @ref{9f,,optparse} passes it to your callback function.

@item @ref{2e7a,,nargs}

also has its usual meaning: if it is supplied and > 1, @ref{9f,,optparse} will
consume @ref{2e7a,,nargs} arguments, each of which must be convertible to
@ref{2e4b,,type}.  It then passes a tuple of converted values to your
callback.

@item @ref{2e7d,,callback_args}

a tuple of extra positional arguments to pass to the callback

@item @ref{2e7e,,callback_kwargs}

a dictionary of extra keyword arguments to pass to the callback
@end table

@node How callbacks are called,Raising errors in a callback,Defining a callback option,Option Callbacks
@anchor{library/optparse how-callbacks-are-called}@anchor{2e94}@anchor{library/optparse optparse-how-callbacks-called}@anchor{2e95}
@subsubsection How callbacks are called


All callbacks are called as follows:

@example
func(option, opt_str, value, parser, *args, **kwargs)
@end example

where


@table @asis

@item @code{option}

is the Option instance that's calling the callback

@item @code{opt_str}

is the option string seen on the command-line that's triggering the callback.
(If an abbreviated long option was used, @code{opt_str} will be the full,
canonical option string---e.g. if the user puts @code{--foo} on the
command-line as an abbreviation for @code{--foobar}, then @code{opt_str} will be
@code{"--foobar"}.)

@item @code{value}

is the argument to this option seen on the command-line.  @ref{9f,,optparse} will
only expect an argument if @ref{2e4b,,type} is set; the type of @code{value} will be
the type implied by the option's type.  If @ref{2e4b,,type} for this option is
@code{None} (no argument expected), then @code{value} will be @code{None}.  If @ref{2e7a,,nargs}
> 1, @code{value} will be a tuple of values of the appropriate type.

@item @code{parser}

is the OptionParser instance driving the whole thing, mainly useful because
you can access some other interesting data through its instance attributes:


@table @asis

@item @code{parser.largs}

the current list of leftover arguments, ie. arguments that have been
consumed but are neither options nor option arguments. Feel free to modify
@code{parser.largs}, e.g. by adding more arguments to it.  (This list will
become @code{args}, the second return value of @ref{1484,,parse_args()}.)

@item @code{parser.rargs}

the current list of remaining arguments, ie. with @code{opt_str} and
@code{value} (if applicable) removed, and only the arguments following them
still there.  Feel free to modify @code{parser.rargs}, e.g. by consuming more
arguments.

@item @code{parser.values}

the object where option values are by default stored (an instance of
optparse.OptionValues).  This lets callbacks use the same mechanism as the
rest of @ref{9f,,optparse} for storing option values; you don't need to mess
around with globals or closures.  You can also access or modify the
value(s) of any options already encountered on the command-line.
@end table

@item @code{args}

is a tuple of arbitrary positional arguments supplied via the
@ref{2e7d,,callback_args} option attribute.

@item @code{kwargs}

is a dictionary of arbitrary keyword arguments supplied via
@ref{2e7e,,callback_kwargs}.
@end table

@node Raising errors in a callback,Callback example 1 trivial callback,How callbacks are called,Option Callbacks
@anchor{library/optparse optparse-raising-errors-in-callback}@anchor{2e96}@anchor{library/optparse raising-errors-in-a-callback}@anchor{2e97}
@subsubsection Raising errors in a callback


The callback function should raise @ref{2e3b,,OptionValueError} if there are any
problems with the option or its argument(s).  @ref{9f,,optparse} catches this and
terminates the program, printing the error message you supply to stderr.  Your
message should be clear, concise, accurate, and mention the option at fault.
Otherwise, the user will have a hard time figuring out what they did wrong.

@node Callback example 1 trivial callback,Callback example 2 check option order,Raising errors in a callback,Option Callbacks
@anchor{library/optparse callback-example-1-trivial-callback}@anchor{2e98}@anchor{library/optparse optparse-callback-example-1}@anchor{2e99}
@subsubsection Callback example 1: trivial callback


Here's an example of a callback option that takes no arguments, and simply
records that the option was seen:

@example
def record_foo_seen(option, opt_str, value, parser):
    parser.values.saw_foo = True

parser.add_option("--foo", action="callback", callback=record_foo_seen)
@end example

Of course, you could do that with the @code{"store_true"} action.

@node Callback example 2 check option order,Callback example 3 check option order generalized,Callback example 1 trivial callback,Option Callbacks
@anchor{library/optparse callback-example-2-check-option-order}@anchor{2e9a}@anchor{library/optparse optparse-callback-example-2}@anchor{2e9b}
@subsubsection Callback example 2: check option order


Here's a slightly more interesting example: record the fact that @code{-a} is
seen, but blow up if it comes after @code{-b} in the command-line.

@example
def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use -a after -b")
    parser.values.a = 1
...
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
@end example

@node Callback example 3 check option order generalized,Callback example 4 check arbitrary condition,Callback example 2 check option order,Option Callbacks
@anchor{library/optparse callback-example-3-check-option-order-generalized}@anchor{2e9c}@anchor{library/optparse optparse-callback-example-3}@anchor{2e9d}
@subsubsection Callback example 3: check option order (generalized)


If you want to reuse this callback for several similar options (set a flag, but
blow up if @code{-b} has already been seen), it needs a bit of work: the error
message and the flag that it sets must be generalized.

@example
def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt_str)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')
@end example

@node Callback example 4 check arbitrary condition,Callback example 5 fixed arguments,Callback example 3 check option order generalized,Option Callbacks
@anchor{library/optparse callback-example-4-check-arbitrary-condition}@anchor{2e9e}@anchor{library/optparse optparse-callback-example-4}@anchor{2e9f}
@subsubsection Callback example 4: check arbitrary condition


Of course, you could put any condition in there---you're not limited to checking
the values of already-defined options.  For example, if you have options that
should not be called when the moon is full, all you have to do is this:

@example
def check_moon(option, opt_str, value, parser):
    if is_moon_full():
        raise OptionValueError("%s option invalid when moon is full"
                               % opt_str)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")
@end example

(The definition of @code{is_moon_full()} is left as an exercise for the reader.)

@node Callback example 5 fixed arguments,Callback example 6 variable arguments,Callback example 4 check arbitrary condition,Option Callbacks
@anchor{library/optparse callback-example-5-fixed-arguments}@anchor{2ea0}@anchor{library/optparse optparse-callback-example-5}@anchor{2ea1}
@subsubsection Callback example 5: fixed arguments


Things get slightly more interesting when you define callback options that take
a fixed number of arguments.  Specifying that a callback option takes arguments
is similar to defining a @code{"store"} or @code{"append"} option: if you define
@ref{2e4b,,type}, then the option takes one argument that must be
convertible to that type; if you further define @ref{2e7a,,nargs}, then the
option takes @ref{2e7a,,nargs} arguments.

Here's an example that just emulates the standard @code{"store"} action:

@example
def store_value(option, opt_str, value, parser):
    setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")
@end example

Note that @ref{9f,,optparse} takes care of consuming 3 arguments and converting
them to integers for you; all you have to do is store them.  (Or whatever;
obviously you don't need a callback for this example.)

@node Callback example 6 variable arguments,,Callback example 5 fixed arguments,Option Callbacks
@anchor{library/optparse callback-example-6-variable-arguments}@anchor{2ea2}@anchor{library/optparse optparse-callback-example-6}@anchor{2ea3}
@subsubsection Callback example 6: variable arguments


Things get hairy when you want an option to take a variable number of arguments.
For this case, you must write a callback, as @ref{9f,,optparse} doesn't provide any
built-in capabilities for it.  And you have to deal with certain intricacies of
conventional Unix command-line parsing that @ref{9f,,optparse} normally handles for
you.  In particular, callbacks should implement the conventional rules for bare
@code{--} and @code{-} arguments:


@itemize *

@item 
either @code{--} or @code{-} can be option arguments

@item 
bare @code{--} (if not the argument to some option): halt command-line
processing and discard the @code{--}

@item 
bare @code{-} (if not the argument to some option): halt command-line
processing but keep the @code{-} (append it to @code{parser.largs})
@end itemize

If you want an option that takes a variable number of arguments, there are
several subtle, tricky issues to worry about.  The exact implementation you
choose will be based on which trade-offs you're willing to make for your
application (which is why @ref{9f,,optparse} doesn't support this sort of thing
directly).

Nevertheless, here's a stab at a callback for an option with variable
arguments:

@example
def vararg_callback(option, opt_str, value, parser):
    assert value is None
    value = []

    def floatable(str):
        try:
            float(str)
            return True
        except ValueError:
            return False

    for arg in parser.rargs:
        # stop on --foo like options
        if arg[:2] == "--" and len(arg) > 2:
            break
        # stop on -a, but not on -3 or -3.0
        if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
            break
        value.append(arg)

    del parser.rargs[:len(value)]
    setattr(parser.values, option.dest, value)

...
parser.add_option("-c", "--callback", dest="vararg_attr",
                  action="callback", callback=vararg_callback)
@end example

@node Extending optparse,Exceptions<10>,Option Callbacks,optparse --- Parser for command line options
@anchor{library/optparse extending-optparse}@anchor{2ea4}@anchor{library/optparse optparse-extending-optparse}@anchor{2e50}
@subsubsection Extending @code{optparse}


Since the two major controlling factors in how @ref{9f,,optparse} interprets
command-line options are the action and type of each option, the most likely
direction of extension is to add new actions and new types.

@menu
* Adding new types:: 
* Adding new actions:: 

@end menu

@node Adding new types,Adding new actions,,Extending optparse
@anchor{library/optparse adding-new-types}@anchor{2ea5}@anchor{library/optparse optparse-adding-new-types}@anchor{2ea6}
@subsubsection Adding new types


To add new types, you need to define your own subclass of @ref{9f,,optparse}'s
@ref{2e72,,Option} class.  This class has a couple of attributes that define
@ref{9f,,optparse}'s types: @ref{2ea7,,TYPES} and @ref{2ea8,,TYPE_CHECKER}.

@geindex TYPES (attribut optparse.Option)
@anchor{library/optparse optparse Option TYPES}@anchor{2ea7}
@deffn {Attribut} Option.TYPES

A tuple of type names; in your subclass, simply define a new tuple
@ref{2ea7,,TYPES} that builds on the standard one.
@end deffn

@geindex TYPE_CHECKER (attribut optparse.Option)
@anchor{library/optparse optparse Option TYPE_CHECKER}@anchor{2ea8}
@deffn {Attribut} Option.TYPE_CHECKER

A dictionary mapping type names to type-checking functions.  A type-checking
function has the following signature:

@example
def check_mytype(option, opt, value)
@end example

where @code{option} is an @ref{2e72,,Option} instance, @code{opt} is an option string
(e.g., @code{-f}), and @code{value} is the string from the command line that must
be checked and converted to your desired type.  @code{check_mytype()} should
return an object of the hypothetical type @code{mytype}.  The value returned by
a type-checking function will wind up in the OptionValues instance returned
by @ref{1484,,OptionParser.parse_args()}, or be passed to a callback as the
@code{value} parameter.

Your type-checking function should raise @ref{2e3b,,OptionValueError} if it
encounters any problems.  @ref{2e3b,,OptionValueError} takes a single string
argument, which is passed as-is to @ref{1483,,OptionParser}'s @code{error()}
method, which in turn prepends the program name and the string @code{"error:"}
and prints everything to stderr before terminating the process.
@end deffn

Here's a silly example that demonstrates adding a @code{"complex"} option type to
parse Python-style complex numbers on the command line.  (This is even sillier
than it used to be, because @ref{9f,,optparse} 1.3 added built-in support for
complex numbers, but never mind.)

First, the necessary imports:

@example
from copy import copy
from optparse import Option, OptionValueError
@end example

You need to define your type-checker first, since it's referred to later (in the
@ref{2ea8,,TYPE_CHECKER} class attribute of your Option subclass):

@example
def check_complex(option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))
@end example

Finally, the Option subclass:

@example
class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex
@end example

(If we didn't make a @ref{25,,copy()} of @ref{2ea8,,Option.TYPE_CHECKER}, we would end
up modifying the @ref{2ea8,,TYPE_CHECKER} attribute of @ref{9f,,optparse}'s
Option class.  This being Python, nothing stops you from doing that except good
manners and common sense.)

That's it!  Now you can write a script that uses the new option type just like
any other @ref{9f,,optparse}-based script, except you have to instruct your
OptionParser to use MyOption instead of Option:

@example
parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")
@end example

Alternately, you can build your own option list and pass it to OptionParser; if
you don't use @code{add_option()} in the above way, you don't need to tell
OptionParser which option class to use:

@example
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
@end example

@node Adding new actions,,Adding new types,Extending optparse
@anchor{library/optparse adding-new-actions}@anchor{2ea9}@anchor{library/optparse optparse-adding-new-actions}@anchor{2eaa}
@subsubsection Adding new actions


Adding new actions is a bit trickier, because you have to understand that
@ref{9f,,optparse} has a couple of classifications for actions:


@table @asis

@item "store" actions

actions that result in @ref{9f,,optparse} storing a value to an attribute of the
current OptionValues instance; these options require a @ref{2e4c,,dest}
attribute to be supplied to the Option constructor.

@item "typed" actions

actions that take a value from the command line and expect it to be of a
certain type; or rather, a string that can be converted to a certain type.
These options require a @ref{2e4b,,type} attribute to the Option
constructor.
@end table

These are overlapping sets: some default "store" actions are @code{"store"},
@code{"store_const"}, @code{"append"}, and @code{"count"}, while the default "typed"
actions are @code{"store"}, @code{"append"}, and @code{"callback"}.

When you add an action, you need to categorize it by listing it in at least one
of the following class attributes of Option (all are lists of strings):

@geindex ACTIONS (attribut optparse.Option)
@anchor{library/optparse optparse Option ACTIONS}@anchor{2eab}
@deffn {Attribut} Option.ACTIONS

All actions must be listed in ACTIONS.
@end deffn

@geindex STORE_ACTIONS (attribut optparse.Option)
@anchor{library/optparse optparse Option STORE_ACTIONS}@anchor{2eac}
@deffn {Attribut} Option.STORE_ACTIONS

"store" actions are additionally listed here.
@end deffn

@geindex TYPED_ACTIONS (attribut optparse.Option)
@anchor{library/optparse optparse Option TYPED_ACTIONS}@anchor{2ead}
@deffn {Attribut} Option.TYPED_ACTIONS

"typed" actions are additionally listed here.
@end deffn

@geindex ALWAYS_TYPED_ACTIONS (attribut optparse.Option)
@anchor{library/optparse optparse Option ALWAYS_TYPED_ACTIONS}@anchor{2eae}
@deffn {Attribut} Option.ALWAYS_TYPED_ACTIONS

Actions that always take a type (i.e. whose options always take a value) are
additionally listed here.  The only effect of this is that @ref{9f,,optparse}
assigns the default type, @code{"string"}, to options with no explicit type
whose action is listed in @ref{2eae,,ALWAYS_TYPED_ACTIONS}.
@end deffn

In order to actually implement your new action, you must override Option's
@code{take_action()} method and add a case that recognizes your action.

For example, let's add an @code{"extend"} action.  This is similar to the standard
@code{"append"} action, but instead of taking a single value from the command-line
and appending it to an existing list, @code{"extend"} will take multiple values in
a single comma-delimited string, and extend an existing list with them.  That
is, if @code{--names} is an @code{"extend"} option of type @code{"string"}, the command
line

@example
--names=foo,bar --names blah --names ding,dong
@end example

would result in a list

@example
["foo", "bar", "blah", "ding", "dong"]
@end example

Again we define a subclass of Option:

@example
class MyOption(Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)

    def take_action(self, action, dest, opt, value, values, parser):
        if action == "extend":
            lvalue = value.split(",")
            values.ensure_value(dest, []).extend(lvalue)
        else:
            Option.take_action(
                self, action, dest, opt, value, values, parser)
@end example

Features of note:


@itemize *

@item 
@code{"extend"} both expects a value on the command-line and stores that value
somewhere, so it goes in both @ref{2eac,,STORE_ACTIONS} and
@ref{2ead,,TYPED_ACTIONS}.

@item 
to ensure that @ref{9f,,optparse} assigns the default type of @code{"string"} to
@code{"extend"} actions, we put the @code{"extend"} action in
@ref{2eae,,ALWAYS_TYPED_ACTIONS} as well.

@item 
@code{MyOption.take_action()} implements just this one new action, and passes
control back to @code{Option.take_action()} for the standard @ref{9f,,optparse}
actions.

@item 
@code{values} is an instance of the optparse_parser.Values class, which provides
the very useful @code{ensure_value()} method. @code{ensure_value()} is
essentially @ref{bbf,,getattr()} with a safety valve; it is called as

@example
values.ensure_value(attr, value)
@end example

If the @code{attr} attribute of @code{values} doesn't exist or is @code{None}, then
ensure_value() first sets it to @code{value}, and then returns @code{value}. This is
very handy for actions like @code{"extend"}, @code{"append"}, and @code{"count"}, all
of which accumulate data in a variable and expect that variable to be of a
certain type (a list for the first two, an integer for the latter).  Using
@code{ensure_value()} means that scripts using your action don't have to worry
about setting a default value for the option destinations in question; they
can just leave the default as @code{None} and @code{ensure_value()} will take care of
getting it right when it's needed.
@end itemize

@node Exceptions<10>,,Extending optparse,optparse --- Parser for command line options
@anchor{library/optparse exceptions}@anchor{2eaf}
@subsubsection Exceptions


@geindex OptionError
@anchor{library/optparse optparse OptionError}@anchor{2e3a}
@deffn {Exception} optparse.OptionError

Raised if an @ref{2e72,,Option} instance is created with invalid or
inconsistent arguments.
@end deffn

@geindex OptionConflictError
@anchor{library/optparse optparse OptionConflictError}@anchor{2e8a}
@deffn {Exception} optparse.OptionConflictError

Raised if conflicting options are added to an @ref{1483,,OptionParser}.
@end deffn

@geindex OptionValueError
@anchor{library/optparse optparse OptionValueError}@anchor{2e3b}
@deffn {Exception} optparse.OptionValueError

Raised if an invalid option value is encountered on the command line.
@end deffn

@geindex BadOptionError
@anchor{library/optparse optparse BadOptionError}@anchor{2eb0}
@deffn {Exception} optparse.BadOptionError

Raised if an invalid option is passed on the command line.
@end deffn

@geindex AmbiguousOptionError
@anchor{library/optparse optparse AmbiguousOptionError}@anchor{2eb1}
@deffn {Exception} optparse.AmbiguousOptionError

Raised if an ambiguous option is passed on the command line.
@end deffn

@node getpass --- Portable password input,fileinput --- Iterate over lines from multiple input streams,optparse --- Parser for command line options,Command Line Interface Libraries
@anchor{library/getpass doc}@anchor{2eb2}@anchor{library/getpass getpass-portable-password-input}@anchor{2eb3}@anchor{library/getpass module-getpass}@anchor{61}
@subsection @code{getpass} --- Portable password input


@geindex module; getpass

@c Windows (& Mac?) support by Guido van Rossum.

`Source code:' Lib/getpass.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/getpass.py}


__________________________________________________________________


@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Le module @ref{61,,getpass} fournit 2 fonctions :

@geindex getpass() (dans le module getpass)
@anchor{library/getpass getpass getpass}@anchor{2eb4}
@deffn {Fonction} getpass.getpass (prompt='Password: ', stream=None)

Affiche une demande de mot de passe sans renvoyer d'écho. L'utilisateur est invité en utilisant la string `prompt', avec en valeur par défaut @code{'Password: '}. Avec Unix, l'invite est écrite dans l'objet fichier `stream' en utilisant si besoin le `replace error handler'. `stream' sera par défaut le terminal de contrôle (@code{/dev/tty}), ou si celui ci n'est pas disponible ce sera @code{sys.stderr} (cet argument sera ignoré sur Windows).

Si aucune saisie en mode sans affichage n'est disponible, @code{getpass()} se résoudra à afficher un message d'avertissement vers `stream', puis lire l'entrée depuis @code{sys.stdin}, en levant une @ref{2eb5,,GetPassWarning}.

@cartouche
@quotation Note 
Si vous appelez `getpass' depuis IDLE, la saisie peut être faite dans le terminal depuis lequel IDLE a été lancé, plutôt que dans la fenêtre d'IDLE.
@end quotation
@end cartouche
@end deffn

@geindex GetPassWarning
@anchor{library/getpass getpass GetPassWarning}@anchor{2eb5}
@deffn {Exception} getpass.GetPassWarning

Une sous classe d'exception @ref{223a,,UserWarning} est levée quand le mot de passe saisi pourrait être affiché.
@end deffn

@geindex getuser() (dans le module getpass)
@anchor{library/getpass getpass getuser}@anchor{40e}
@deffn {Fonction} getpass.getuser ()

Renvoie le `login name' de l'utilisateur.

This function checks the environment variables 
@geindex LOGNAME
@geindex variable d'environnement; LOGNAME
@code{LOGNAME},
@geindex USER
@geindex variable d'environnement; USER
@code{USER}, @code{LNAME} and 
@geindex USERNAME
@geindex variable d'environnement; USERNAME
@code{USERNAME}, in order, and
returns the value of the first one which is set to a non-empty string.  If
none are set, the login name from the password database is returned on
systems which support the @ref{b1,,pwd} module, otherwise, an @ref{40d,,OSError}
is raised.

In general, this function should be preferred over @ref{2a97,,os.getlogin()}.


Modifié dans la version 3.13: Previously, various exceptions beyond just @ref{40d,,OSError} were raised.

@end deffn

@node fileinput --- Iterate over lines from multiple input streams,curses --- Terminal handling for character-cell displays,getpass --- Portable password input,Command Line Interface Libraries
@anchor{library/fileinput doc}@anchor{2eb6}@anchor{library/fileinput fileinput-iterate-over-lines-from-multiple-input-streams}@anchor{2eb7}@anchor{library/fileinput module-fileinput}@anchor{5a}
@subsection @code{fileinput} --- Iterate over lines from multiple input streams


@geindex module; fileinput

`Code source :' Lib/fileinput.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/fileinput.py}


__________________________________________________________________


Ce module offre une classe auxiliaire et des fonctions pour lire facilement l'entrée standard ou bien les fichiers d'une liste. Si vous n'avez besoin de lire ou écrire qu'un seul fichier, il suffit de @ref{505,,open()}.

Ce module s'utilise le plus couramment comme ceci :

@example
import fileinput
for line in fileinput.input(encoding="utf-8"):
    process(line)
@end example

Ce code traite une à une les lignes des fichiers de @code{sys.argv[1:]}. Si cette liste est vide (pas d'argument en ligne de commande), il lit l'entrée standard. Le nom de fichier @code{'-'} est équivalent à l'entrée standard (les arguments facultatifs `mode' et `openhook' sont ignorés dans ce cas). On peut aussi passer la liste des fichiers comme argument à @ref{7e9,,input()}, voire un nom de fichier unique.

Par défaut, tous les fichiers sont ouverts en mode texte. On peut changer ce comportement à l'aide du paramètre `mode' de la fonction @ref{7e9,,input()} ou du constructeur de @ref{721,,FileInput}. Si une erreur d'entrée-sortie se produit durant l'ouverture ou la lecture d'un fichier, l'exception @ref{40d,,OSError} est levée.


Modifié dans la version 3.3: @ref{103b,,IOError} était levée auparavant, elle est devenue un alias de @ref{40d,,OSError}.


Si @code{sys.stdin} apparaît plus d'une fois dans la liste, toutes les lignes sont consommées dès la première fois, sauf éventuellement en cas d'usage interactif ou si le flux d'entrée standard a été modifié dans l'intervalle (par exemple avec @code{sys.stdin.seek(0)}).

Les fichiers vides sont ouverts et refermés immédiatement. Ils ne sont pas détectables dans la liste des fichiers, sauf éventuellement dans le cas où le dernier fichier est vide.

Les caractères de saut de ligne sont préservés, donc toutes les lignes se terminent par un saut de ligne, sauf éventuellement la dernière ligne d'un fichier.

You can control how files are opened by providing an opening hook via the
`openhook' parameter to @ref{7e9,,fileinput.input()} or @ref{721,,FileInput()}. The
hook must be a function that takes two arguments, `filename' and `mode', and
returns an accordingly opened file-like object. If `encoding' and/or `errors'
are specified, they will be passed to the hook as additional keyword arguments.
This module provides a @ref{7ea,,hook_compressed()} to support compressed files.

La fonction suivante constitue l'interface principale du module :

@geindex input() (dans le module fileinput)
@anchor{library/fileinput fileinput input}@anchor{7e9}
@deffn {Fonction} fileinput.input (files=None, inplace=False, backup='@w{'}, *, mode='r', openhook=None, encoding=None, errors=None)

Crée une instance de @ref{721,,FileInput}, qui devient l'état global pour toutes les fonctions du module. Elle est également renvoyée afin que l'utilisateur puisse la parcourir comme un objet itérable. Tous les paramètres de cette fonction sont transmis au constructeur de @ref{721,,FileInput}.

Les instances de @ref{721,,FileInput} peuvent s'utiliser comme gestionnaires de contexte, avec l'instruction @ref{5bc,,with}. Dans le code suivant, `input' est fermé lorsque le bloc @code{with} se termine, y compris si une exception l'a interrompu :

@example
with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f:
    for line in f:
        process(line)
@end example


Modifié dans la version 3.2: prise en charge du protocole de gestionnaire de contexte.



Modifié dans la version 3.8: les paramètres `mode' et `openhook' doivent être nommés.



Modifié dans la version 3.10: The keyword-only parameter `encoding' and `errors' are added.

@end deffn

Toutes les fonctions suivantes font appel à l'état global du module mis en place par @ref{7e9,,fileinput.input()}. L'absence de cet état déclenche l'exception @ref{193,,RuntimeError}.

@geindex filename() (dans le module fileinput)
@anchor{library/fileinput fileinput filename}@anchor{2eb8}
@deffn {Fonction} fileinput.filename ()

Renvoie le nom du fichier en train d'être lu, ou @code{None} avant la lecture de la toute première ligne.
@end deffn

@geindex fileno() (dans le module fileinput)
@anchor{library/fileinput fileinput fileno}@anchor{13e4}
@deffn {Fonction} fileinput.fileno ()

Renvoie le descripteur de fichier (sous forme d'entier) utilisé pour lire le fichier courant. Si aucun fichier n'est ouvert (avant la première ligne et entre les fichiers), le résultat est @code{-1}.
@end deffn

@geindex lineno() (dans le module fileinput)
@anchor{library/fileinput fileinput lineno}@anchor{2eb9}
@deffn {Fonction} fileinput.lineno ()

Renvoie le numéro de la ligne qui vient d'être lue, en commençant par la première ligne du premier fichier. Avant cette toute première ligne, renvoie @code{0}. Après la dernière ligne du dernier fichier, renvoie le numéro de cette ligne.
@end deffn

@geindex filelineno() (dans le module fileinput)
@anchor{library/fileinput fileinput filelineno}@anchor{2eba}
@deffn {Fonction} fileinput.filelineno ()

Renvoie le numéro de ligne relatif au fichier courant. Avant la toute première ligne, renvoie @code{0}. Après la toute dernière ligne, renvoie le numéro de cette ligne par rapport à son fichier source.
@end deffn

@geindex isfirstline() (dans le module fileinput)
@anchor{library/fileinput fileinput isfirstline}@anchor{2ebb}
@deffn {Fonction} fileinput.isfirstline ()

Renvoie @code{True} ou @code{False} selon que la ligne qui vient d'être lue est la première du fichier.
@end deffn

@geindex isstdin() (dans le module fileinput)
@anchor{library/fileinput fileinput isstdin}@anchor{2ebc}
@deffn {Fonction} fileinput.isstdin ()

@code{True} ou @code{False} selon que la dernière ligne lue provenait de @code{sys.stdin} ou non.
@end deffn

@geindex nextfile() (dans le module fileinput)
@anchor{library/fileinput fileinput nextfile}@anchor{2ebd}
@deffn {Fonction} fileinput.nextfile ()

Ferme le fichier courant et laisse la lecture se poursuivre au début du suivant (ou se terminer si c'était le dernier fichier ; dans ce cas cette fonction ne fait rien). Les lignes court-circuitées ne comptent pas dans les numéros des lignes des fichiers suivants. Le nom du fichier courant n'est pas modifié immédiatement, mais seulement après que la première ligne du fichier suivant a été lue. Cette fonction n'a pas d'effet avant la lecture de la première ligne (elle ne peut pas sauter le premier fichier).
@end deffn

@geindex close() (dans le module fileinput)
@anchor{library/fileinput fileinput close}@anchor{2ebe}
@deffn {Fonction} fileinput.close ()

Ferme le fichier courant et termine la lecture en sautant les fichiers suivants.
@end deffn

La classe qui implémente ce comportement du module est publique. On peut en créer des classes filles :

@geindex FileInput (classe dans fileinput)
@anchor{library/fileinput fileinput FileInput}@anchor{721}
@deffn {Classe} fileinput.FileInput (files=None, inplace=False, backup='@w{'}, *, mode='r', openhook=None, encoding=None, errors=None)

Class @ref{721,,FileInput} is the implementation; its methods @ref{2eb8,,filename()},
@ref{13e4,,fileno()}, @ref{2eb9,,lineno()}, @ref{2eba,,filelineno()}, @ref{2ebb,,isfirstline()},
@ref{2ebc,,isstdin()}, @ref{2ebd,,nextfile()} and @ref{2ebe,,close()} correspond to the
functions of the same name in the module. In addition it is @ref{1205,,iterable}
and has a @ref{1c4b,,readline()} method which returns the next
input line. The sequence must be accessed in strictly sequential order;
random access and @ref{1c4b,,readline()} cannot be mixed.

With `mode' you can specify which file mode will be passed to @ref{505,,open()}. It
must be one of @code{'r'} and @code{'rb'}.

S'il est fourni, l'argument `openhook' est une fonction. Elle est appelée avec les paramètres `filename' et `mode', et renvoie un objet fichier-compatible ouvert selon `mode'. Notez que `openhook' et `inplace' sont mutuellement exclusifs.

You can specify `encoding' and `errors' that is passed to @ref{505,,open()} or `openhook'.

Les objets @ref{721,,FileInput} peuvent aussi fonctionner comme gestionnaires de contexte dans un bloc @ref{5bc,,with}. Dans l'exemple suivant, `input' est fermé à la fin du bloc @code{with}, même arrêté par une exception :

@example
with FileInput(files=('spam.txt', 'eggs.txt')) as input:
    process(input)
@end example


Modifié dans la version 3.2: prise en charge du protocole de gestionnaire de contexte.



Modifié dans la version 3.8: les paramètres `mode' et `openhook' doivent impérativement être nommés.



Modifié dans la version 3.10: The keyword-only parameter `encoding' and `errors' are added.



Modifié dans la version 3.11: The @code{'rU'} and @code{'U'} modes and the @code{__getitem__()} method have
been removed.

@end deffn

`Filtrage sur place optionnel :' si @code{inplace=True} est passé à @ref{7e9,,fileinput.input()} ou au constructeur de @ref{721,,FileInput}, chaque fichier d'entrée est déplacé vers une sauvegarde et la sortie standard est redirigée vers le fichier lui-même, ce qui permet d'écrire des filtres qui modifient directement les fichiers existants. Si le paramètre `backup' est fourni, il donne l'extension des fichiers de sauvegarde. Dans ce cas, la sauvegarde est conservée après l'opération. Par défaut, les fichiers de sauvegarde ont l'extension @code{'.bak'} et sont supprimés dès que le fichier de sortie est fermé. Si un fichier existe avec le même nom que la sauvegarde, il est écrasé. Le filtrage sur place ne fait rien pour l'entrée standard.

Les deux fonctions suivantes fournissent des valeurs prédéfinies pour `openhook' :

@geindex hook_compressed() (dans le module fileinput)
@anchor{library/fileinput fileinput hook_compressed}@anchor{7ea}
@deffn {Fonction} fileinput.hook_compressed (filename, mode, *, encoding=None, errors=None)

Ouvre de façon transparente les fichiers compressés avec gzip ou bzip2, à l'aide des modules @ref{66,,gzip} et @ref{13,,bz2}. Les fichiers compressés sont reconnus aux extensions @code{'.gz'} et @code{'.bz2'}. Tous les fichiers qui n'ont pas l'une de ces deux extensions sont ouverts normalement (avec @ref{505,,open()}, sans décompression).

The `encoding' and `errors' values are passed to @ref{7a5,,io.TextIOWrapper}
for compressed files and open for normal files.

Usage example:  @code{fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")}


Modifié dans la version 3.10: The keyword-only parameter `encoding' and `errors' are added.

@end deffn

@geindex hook_encoded() (dans le module fileinput)
@anchor{library/fileinput fileinput hook_encoded}@anchor{c8e}
@deffn {Fonction} fileinput.hook_encoded (encoding, errors=None)

Renvoie une fonction qui ouvre les fichiers en passant à @ref{505,,open()} les arguments `encoding' et `errors'. Le résultat peut être exploité à travers le point d'entrée automatique `openhook'.

Exemple d'utilisation : @code{fi = fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", "surrogateescape"))}.


Modifié dans la version 3.6: ajout du paramètre facultatif `errors'.



Obsolète depuis la version 3.10: This function is deprecated since @ref{7e9,,fileinput.input()} and @ref{721,,FileInput}
now have `encoding' and `errors' parameters.

@end deffn

@node curses --- Terminal handling for character-cell displays,curses textpad --- Text input widget for curses programs,fileinput --- Iterate over lines from multiple input streams,Command Line Interface Libraries
@anchor{library/curses doc}@anchor{2ebf}@anchor{library/curses curses-terminal-handling-for-character-cell-displays}@anchor{2ec0}@anchor{library/curses module-curses}@anchor{2b}
@subsection @code{curses} --- Terminal handling for character-cell displays


@geindex module; curses

`Source code:' Lib/curses@footnote{https://github.com/python/cpython/tree/3.13/Lib/curses}


__________________________________________________________________


The @ref{2b,,curses} module provides an interface to the curses library, the
de-facto standard for portable advanced terminal handling.

While curses is most widely used in the Unix environment, versions are available
for Windows, DOS, and possibly other systems as well.  This extension module is
designed to match the API of ncurses, an open-source curses library hosted on
Linux and the BSD variants of Unix.

@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@cartouche
@quotation Note 
Whenever the documentation mentions a `character' it can be specified
as an integer, a one-character Unicode string or a one-byte byte string.

Whenever the documentation mentions a `character string' it can be specified
as a Unicode string or a byte string.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item Module @ref{2c,,curses.ascii}

Utilities for working with ASCII characters, regardless of your locale settings.

@item Module @ref{2d,,curses.panel}

A panel stack extension that adds depth to  curses windows.

@item Module @ref{2e,,curses.textpad}

Editable text widget for curses supporting  @code{Emacs}-like bindings.

@item @ref{2ec1,,Programmation Curses avec Python}

Tutorial material on using curses with Python, by Andrew Kuchling and Eric
Raymond.
@end table


@menu
* Fonctions: Fonctions<6>. 
* Window Objects:: 
* Constantes: Constantes<6>. 

@end menu

@node Fonctions<6>,Window Objects,,curses --- Terminal handling for character-cell displays
@anchor{library/curses curses-functions}@anchor{2ec2}@anchor{library/curses functions}@anchor{2ec3}
@subsubsection Fonctions


The module @ref{2b,,curses} defines the following exception:

@geindex error
@anchor{library/curses curses error}@anchor{2ec4}
@deffn {Exception} curses.error

Exception raised when a curses library function returns an error.
@end deffn

@cartouche
@quotation Note 
Whenever `x' or `y' arguments to a function or a method are optional, they
default to the current cursor location. Whenever `attr' is optional, it defaults
to @ref{2ec5,,A_NORMAL}.
@end quotation
@end cartouche

The module @ref{2b,,curses} defines the following functions:

@geindex baudrate() (dans le module curses)
@anchor{library/curses curses baudrate}@anchor{2ec6}
@deffn {Fonction} curses.baudrate ()

Return the output speed of the terminal in bits per second.  On software
terminal emulators it will have a fixed high value. Included for historical
reasons; in former times, it was used to  write output loops for time delays and
occasionally to change interfaces depending on the line speed.
@end deffn

@geindex beep() (dans le module curses)
@anchor{library/curses curses beep}@anchor{2ec7}
@deffn {Fonction} curses.beep ()

Emit a short attention sound.
@end deffn

@geindex can_change_color() (dans le module curses)
@anchor{library/curses curses can_change_color}@anchor{2ec8}
@deffn {Fonction} curses.can_change_color ()

Return @code{True} or @code{False}, depending on whether the programmer can change the colors
displayed by the terminal.
@end deffn

@geindex cbreak() (dans le module curses)
@anchor{library/curses curses cbreak}@anchor{2ec9}
@deffn {Fonction} curses.cbreak ()

Enter cbreak mode.  In cbreak mode (sometimes called "rare" mode) normal tty
line buffering is turned off and characters are available to be read one by one.
However, unlike raw mode, special characters (interrupt, quit, suspend, and flow
control) retain their effects on the tty driver and calling program.  Calling
first @ref{2eca,,raw()} then @ref{2ec9,,cbreak()} leaves the terminal in cbreak mode.
@end deffn

@geindex color_content() (dans le module curses)
@anchor{library/curses curses color_content}@anchor{7db}
@deffn {Fonction} curses.color_content (color_number)

Return the intensity of the red, green, and blue (RGB) components in the color
`color_number', which must be between @code{0} and @code{COLORS - 1}.  Return a 3-tuple,
containing the R,G,B values for the given color, which will be between
@code{0} (no component) and @code{1000} (maximum amount of component).
@end deffn

@geindex color_pair() (dans le module curses)
@anchor{library/curses curses color_pair}@anchor{2ecb}
@deffn {Fonction} curses.color_pair (pair_number)

Return the attribute value for displaying text in the specified color pair.
Only the first 256 color pairs are supported. This
attribute value can be combined with @ref{2ecc,,A_STANDOUT}, @ref{2ecd,,A_REVERSE},
and the other @code{A_*} attributes.  @ref{2ece,,pair_number()} is the counterpart
to this function.
@end deffn

@geindex curs_set() (dans le module curses)
@anchor{library/curses curses curs_set}@anchor{2ecf}
@deffn {Fonction} curses.curs_set (visibility)

Set the cursor state.  `visibility' can be set to @code{0}, @code{1}, or @code{2}, for invisible,
normal, or very visible.  If the terminal supports the visibility requested, return the
previous cursor state; otherwise raise an exception.  On many
terminals, the "visible" mode is an underline cursor and the "very visible" mode
is a block cursor.
@end deffn

@geindex def_prog_mode() (dans le module curses)
@anchor{library/curses curses def_prog_mode}@anchor{2ed0}
@deffn {Fonction} curses.def_prog_mode ()

Save the current terminal mode as the "program" mode, the mode when the running
program is using curses.  (Its counterpart is the "shell" mode, for when the
program is not in curses.)  Subsequent calls to @ref{2ed1,,reset_prog_mode()} will
restore this mode.
@end deffn

@geindex def_shell_mode() (dans le module curses)
@anchor{library/curses curses def_shell_mode}@anchor{2ed2}
@deffn {Fonction} curses.def_shell_mode ()

Save the current terminal mode as the "shell" mode, the mode when the running
program is not using curses.  (Its counterpart is the "program" mode, when the
program is using curses capabilities.) Subsequent calls to
@ref{2ed3,,reset_shell_mode()} will restore this mode.
@end deffn

@geindex delay_output() (dans le module curses)
@anchor{library/curses curses delay_output}@anchor{2ed4}
@deffn {Fonction} curses.delay_output (ms)

Insert an `ms' millisecond pause in output.
@end deffn

@geindex doupdate() (dans le module curses)
@anchor{library/curses curses doupdate}@anchor{2ed5}
@deffn {Fonction} curses.doupdate ()

Update the physical screen.  The curses library keeps two data structures, one
representing the current physical screen contents and a virtual screen
representing the desired next state.  The @ref{2ed5,,doupdate()} ground updates the
physical screen to match the virtual screen.

The virtual screen may be updated by a @ref{2ed6,,noutrefresh()} call after write
operations such as @ref{2ed7,,addstr()} have been performed on a window.  The normal
@ref{2ed8,,refresh()} call is simply @code{noutrefresh()} followed by @code{doupdate()};
if you have to update multiple windows, you can speed performance and perhaps
reduce screen flicker by issuing @code{noutrefresh()} calls on all windows,
followed by a single @code{doupdate()}.
@end deffn

@geindex echo() (dans le module curses)
@anchor{library/curses curses echo}@anchor{2ed9}
@deffn {Fonction} curses.echo ()

Enter echo mode.  In echo mode, each character input is echoed to the screen as
it is entered.
@end deffn

@geindex endwin() (dans le module curses)
@anchor{library/curses curses endwin}@anchor{2eda}
@deffn {Fonction} curses.endwin ()

De-initialize the library, and return terminal to normal status.
@end deffn

@geindex erasechar() (dans le module curses)
@anchor{library/curses curses erasechar}@anchor{2edb}
@deffn {Fonction} curses.erasechar ()

Return the user's current erase character as a one-byte bytes object.  Under Unix operating systems this
is a property of the controlling tty of the curses program, and is not set by
the curses library itself.
@end deffn

@geindex filter() (dans le module curses)
@anchor{library/curses curses filter}@anchor{2edc}
@deffn {Fonction} curses.filter ()

The @ref{2edc,,filter()} routine, if used, must be called before @ref{1528,,initscr()} is
called.  The effect is that, during those calls, 
@geindex LINES
@geindex variable d'environnement; LINES
@code{LINES} is set to @code{1}; the
capabilities @code{clear}, @code{cup}, @code{cud}, @code{cud1}, @code{cuu1}, @code{cuu}, @code{vpa} are disabled; and the @code{home}
string is set to the value of @code{cr}. The effect is that the cursor is confined to
the current line, and so are screen updates.  This may be used for enabling
character-at-a-time  line editing without touching the rest of the screen.
@end deffn

@geindex flash() (dans le module curses)
@anchor{library/curses curses flash}@anchor{2edd}
@deffn {Fonction} curses.flash ()

Flash the screen.  That is, change it to reverse-video and then change it back
in a short interval.  Some people prefer such as 'visible bell' to the audible
attention signal produced by @ref{2ec7,,beep()}.
@end deffn

@geindex flushinp() (dans le module curses)
@anchor{library/curses curses flushinp}@anchor{2ede}
@deffn {Fonction} curses.flushinp ()

Flush all input buffers.  This throws away any  typeahead  that  has been typed
by the user and has not yet been processed by the program.
@end deffn

@geindex getmouse() (dans le module curses)
@anchor{library/curses curses getmouse}@anchor{2edf}
@deffn {Fonction} curses.getmouse ()

After @ref{2ee0,,getch()} returns @ref{2ee1,,KEY_MOUSE} to signal a mouse event, this
method should be called to retrieve the queued mouse event, represented as a
5-tuple @code{(id, x, y, z, bstate)}. `id' is an ID value used to distinguish
multiple devices, and `x', `y', `z' are the event's coordinates.  (`z' is
currently unused.)  `bstate' is an integer value whose bits will be set to
indicate the type of event, and will be the bitwise OR of one or more of the
following constants, where `n' is the button number from 1 to 5:
@ref{2ee2,,BUTTONn_PRESSED}, @ref{2ee3,,BUTTONn_RELEASED}, @ref{2ee4,,BUTTONn_CLICKED},
@ref{2ee5,,BUTTONn_DOUBLE_CLICKED}, @ref{2ee6,,BUTTONn_TRIPLE_CLICKED},
@ref{2ee7,,BUTTON_SHIFT}, @ref{2ee8,,BUTTON_CTRL}, @ref{2ee9,,BUTTON_ALT}.


Modifié dans la version 3.10: The @code{BUTTON5_*} constants are now exposed if they are provided by the
underlying curses library.

@end deffn

@geindex getsyx() (dans le module curses)
@anchor{library/curses curses getsyx}@anchor{2eea}
@deffn {Fonction} curses.getsyx ()

Return the current coordinates of the virtual screen cursor as a tuple
@code{(y, x)}.  If @ref{2eeb,,leaveok} is currently @code{True}, then return @code{(-1, -1)}.
@end deffn

@geindex getwin() (dans le module curses)
@anchor{library/curses curses getwin}@anchor{2eec}
@deffn {Fonction} curses.getwin (file)

Read window related data stored in the file by an earlier @ref{2eed,,window.putwin()} call.
The routine then creates and initializes a new window using that data, returning
the new window object.
@end deffn

@geindex has_colors() (dans le module curses)
@anchor{library/curses curses has_colors}@anchor{2eee}
@deffn {Fonction} curses.has_colors ()

Return @code{True} if the terminal can display colors; otherwise, return @code{False}.
@end deffn

@geindex has_extended_color_support() (dans le module curses)
@anchor{library/curses curses has_extended_color_support}@anchor{7df}
@deffn {Fonction} curses.has_extended_color_support ()

Return @code{True} if the module supports extended colors; otherwise, return
@code{False}. Extended color support allows more than 256 color pairs for
terminals that support more than 16 colors (e.g. xterm-256color).

Extended color support requires ncurses version 6.1 or later.


Ajouté dans la version 3.10.

@end deffn

@geindex has_ic() (dans le module curses)
@anchor{library/curses curses has_ic}@anchor{2eef}
@deffn {Fonction} curses.has_ic ()

Return @code{True} if the terminal has insert- and delete-character capabilities.
This function is included for historical reasons only, as all modern software
terminal emulators have such capabilities.
@end deffn

@geindex has_il() (dans le module curses)
@anchor{library/curses curses has_il}@anchor{2ef0}
@deffn {Fonction} curses.has_il ()

Return @code{True} if the terminal has insert- and delete-line capabilities, or can
simulate  them  using scrolling regions. This function is included for
historical reasons only, as all modern software terminal emulators have such
capabilities.
@end deffn

@geindex has_key() (dans le module curses)
@anchor{library/curses curses has_key}@anchor{2ef1}
@deffn {Fonction} curses.has_key (ch)

Take a key value `ch', and return @code{True} if the current terminal type recognizes
a key with that value.
@end deffn

@geindex halfdelay() (dans le module curses)
@anchor{library/curses curses halfdelay}@anchor{2ef2}
@deffn {Fonction} curses.halfdelay (tenths)

Used for half-delay mode, which is similar to cbreak mode in that characters
typed by the user are immediately available to the program. However, after
blocking for `tenths' tenths of seconds, raise an exception if nothing has
been typed.  The value of `tenths' must be a number between @code{1} and @code{255}.  Use
@ref{2ef3,,nocbreak()} to leave half-delay mode.
@end deffn

@geindex init_color() (dans le module curses)
@anchor{library/curses curses init_color}@anchor{7dc}
@deffn {Fonction} curses.init_color (color_number, r, g, b)

Change the definition of a color, taking the number of the color to be changed
followed by three RGB values (for the amounts of red, green, and blue
components).  The value of `color_number' must be between @code{0} and
@code{COLORS - 1}.  Each of `r', `g', `b', must be a value between @code{0} and
@code{1000}.  When @ref{7dc,,init_color()} is used, all occurrences of that color on the
screen immediately change to the new definition.  This function is a no-op on
most terminals; it is active only if @ref{2ec8,,can_change_color()} returns @code{True}.
@end deffn

@geindex init_pair() (dans le module curses)
@anchor{library/curses curses init_pair}@anchor{7dd}
@deffn {Fonction} curses.init_pair (pair_number, fg, bg)

Change the definition of a color-pair.  It takes three arguments: the number of
the color-pair to be changed, the foreground color number, and the background
color number.  The value of `pair_number' must be between @code{1} and
@code{COLOR_PAIRS - 1} (the @code{0} color pair is wired to white on black and cannot
be changed).  The value of `fg' and `bg' arguments must be between @code{0} and
@code{COLORS - 1}, or, after calling @ref{2ef4,,use_default_colors()}, @code{-1}.
If the color-pair was previously initialized, the screen is
refreshed and all occurrences of that color-pair are changed to the new
definition.
@end deffn

@geindex initscr() (dans le module curses)
@anchor{library/curses curses initscr}@anchor{1528}
@deffn {Fonction} curses.initscr ()

Initialize the library. Return a @ref{2ef5,,window} object
which represents the whole screen.

@cartouche
@quotation Note 
If there is an error opening the terminal, the underlying curses library may
cause the interpreter to exit.
@end quotation
@end cartouche
@end deffn

@geindex is_term_resized() (dans le module curses)
@anchor{library/curses curses is_term_resized}@anchor{2ef6}
@deffn {Fonction} curses.is_term_resized (nlines, ncols)

Return @code{True} if @ref{1532,,resize_term()} would modify the window structure,
@code{False} otherwise.
@end deffn

@geindex isendwin() (dans le module curses)
@anchor{library/curses curses isendwin}@anchor{2ef7}
@deffn {Fonction} curses.isendwin ()

Return @code{True} if @ref{2eda,,endwin()} has been called (that is, the  curses library has
been deinitialized).
@end deffn

@geindex keyname() (dans le module curses)
@anchor{library/curses curses keyname}@anchor{2ef8}
@deffn {Fonction} curses.keyname (k)

Return the name of the key numbered `k' as a bytes object.  The name of a key generating printable
ASCII character is the key's character.  The name of a control-key combination
is a two-byte bytes object consisting of a caret (@code{b'^'}) followed by the corresponding
printable ASCII character.  The name of an alt-key combination (128--255) is a
bytes object consisting of the prefix @code{b'M-'} followed by the name of the corresponding
ASCII character.
@end deffn

@geindex killchar() (dans le module curses)
@anchor{library/curses curses killchar}@anchor{2ef9}
@deffn {Fonction} curses.killchar ()

Return the user's current line kill character as a one-byte bytes object. Under Unix operating systems
this is a property of the controlling tty of the curses program, and is not set
by the curses library itself.
@end deffn

@geindex longname() (dans le module curses)
@anchor{library/curses curses longname}@anchor{2efa}
@deffn {Fonction} curses.longname ()

Return a bytes object containing the terminfo long name field describing the current
terminal.  The maximum length of a verbose description is 128 characters.  It is
defined only after the call to @ref{1528,,initscr()}.
@end deffn

@geindex meta() (dans le module curses)
@anchor{library/curses curses meta}@anchor{2efb}
@deffn {Fonction} curses.meta (flag)

If `flag' is @code{True}, allow 8-bit characters to be input.  If
`flag' is @code{False},  allow only 7-bit chars.
@end deffn

@geindex mouseinterval() (dans le module curses)
@anchor{library/curses curses mouseinterval}@anchor{2efc}
@deffn {Fonction} curses.mouseinterval (interval)

Set the maximum time in milliseconds that can elapse between press and release
events in order for them to be recognized as a click, and return the previous
interval value.  The default value is 200 milliseconds, or one fifth of a second.
@end deffn

@geindex mousemask() (dans le module curses)
@anchor{library/curses curses mousemask}@anchor{2efd}
@deffn {Fonction} curses.mousemask (mousemask)

Set the mouse events to be reported, and return a tuple @code{(availmask,
oldmask)}.   `availmask' indicates which of the specified mouse events can be
reported; on complete failure it returns @code{0}.  `oldmask' is the previous value of
the given window's mouse event mask.  If this function is never called, no mouse
events are ever reported.
@end deffn

@geindex napms() (dans le module curses)
@anchor{library/curses curses napms}@anchor{1527}
@deffn {Fonction} curses.napms (ms)

Sleep for `ms' milliseconds.
@end deffn

@geindex newpad() (dans le module curses)
@anchor{library/curses curses newpad}@anchor{2efe}
@deffn {Fonction} curses.newpad (nlines, ncols)

Create and return a pointer to a new pad data structure with the given number
of lines and columns.  Return a pad as a window object.

A pad is like a window, except that it is not restricted by the screen size, and
is not necessarily associated with a particular part of the screen.  Pads can be
used when a large window is needed, and only a part of the window will be on the
screen at one time.  Automatic refreshes of pads (such as from scrolling or
echoing of input) do not occur.  The @ref{2ed8,,refresh()} and @ref{2ed6,,noutrefresh()}
methods of a pad require 6 arguments to specify the part of the pad to be
displayed and the location on the screen to be used for the display. The
arguments are `pminrow', `pmincol', `sminrow', `smincol', `smaxrow', `smaxcol'; the `p'
arguments refer to the upper left corner of the pad region to be displayed and
the `s' arguments define a clipping box on the screen within which the pad region
is to be displayed.
@end deffn

@geindex newwin() (dans le module curses)
@anchor{library/curses curses newwin}@anchor{2eff}
@deffn {Fonction} curses.newwin (nlines, ncols)

@deffnx {Fonction} curses.newwin (nlines, ncols, begin_y, begin_x)

Return a new @ref{2ef5,,window}, whose left-upper corner
is at  @code{(begin_y, begin_x)}, and whose height/width is  `nlines'/`ncols'.

By default, the window will extend from the  specified position to the lower
right corner of the screen.
@end deffn

@geindex nl() (dans le module curses)
@anchor{library/curses curses nl}@anchor{2f00}
@deffn {Fonction} curses.nl ()

Enter newline mode.  This mode translates the return key into newline on input,
and translates newline into return and line-feed on output. Newline mode is
initially on.
@end deffn

@geindex nocbreak() (dans le module curses)
@anchor{library/curses curses nocbreak}@anchor{2ef3}
@deffn {Fonction} curses.nocbreak ()

Leave cbreak mode.  Return to normal "cooked" mode with line buffering.
@end deffn

@geindex noecho() (dans le module curses)
@anchor{library/curses curses noecho}@anchor{2f01}
@deffn {Fonction} curses.noecho ()

Leave echo mode.  Echoing of input characters is turned off.
@end deffn

@geindex nonl() (dans le module curses)
@anchor{library/curses curses nonl}@anchor{2f02}
@deffn {Fonction} curses.nonl ()

Leave newline mode.  Disable translation of return into newline on input, and
disable low-level translation of newline into newline/return on output (but this
does not change the behavior of @code{addch('\n')}, which always does the
equivalent of return and line feed on the virtual screen).  With translation
off, curses can sometimes speed up vertical motion a little; also, it will be
able to detect the return key on input.
@end deffn

@geindex noqiflush() (dans le module curses)
@anchor{library/curses curses noqiflush}@anchor{2f03}
@deffn {Fonction} curses.noqiflush ()

When the @code{noqiflush()} routine is used, normal flush of input and output queues
associated with the @code{INTR}, @code{QUIT} and @code{SUSP} characters will not be done.  You may
want to call @code{noqiflush()} in a signal handler if you want output to
continue as though the interrupt had not occurred, after the handler exits.
@end deffn

@geindex noraw() (dans le module curses)
@anchor{library/curses curses noraw}@anchor{2f04}
@deffn {Fonction} curses.noraw ()

Leave raw mode. Return to normal "cooked" mode with line buffering.
@end deffn

@geindex pair_content() (dans le module curses)
@anchor{library/curses curses pair_content}@anchor{7de}
@deffn {Fonction} curses.pair_content (pair_number)

Return a tuple @code{(fg, bg)} containing the colors for the requested color pair.
The value of `pair_number' must be between @code{0} and @code{COLOR_PAIRS - 1}.
@end deffn

@geindex pair_number() (dans le module curses)
@anchor{library/curses curses pair_number}@anchor{2ece}
@deffn {Fonction} curses.pair_number (attr)

Return the number of the color-pair set by the attribute value `attr'.
@ref{2ecb,,color_pair()} is the counterpart to this function.
@end deffn

@geindex putp() (dans le module curses)
@anchor{library/curses curses putp}@anchor{2f05}
@deffn {Fonction} curses.putp (str)

Equivalent to @code{tputs(str, 1, putchar)}; emit the value of a specified
terminfo capability for the current terminal.  Note that the output of @ref{2f05,,putp()}
always goes to standard output.
@end deffn

@geindex qiflush() (dans le module curses)
@anchor{library/curses curses qiflush}@anchor{2f06}
@deffn {Fonction} curses.qiflush ([flag])

If `flag' is @code{False}, the effect is the same as calling @ref{2f03,,noqiflush()}. If
`flag' is @code{True}, or no argument is provided, the queues will be flushed when
these control characters are read.
@end deffn

@geindex raw() (dans le module curses)
@anchor{library/curses curses raw}@anchor{2eca}
@deffn {Fonction} curses.raw ()

Enter raw mode.  In raw mode, normal line buffering and  processing of
interrupt, quit, suspend, and flow control keys are turned off; characters are
presented to curses input functions one by one.
@end deffn

@geindex reset_prog_mode() (dans le module curses)
@anchor{library/curses curses reset_prog_mode}@anchor{2ed1}
@deffn {Fonction} curses.reset_prog_mode ()

Restore the  terminal  to "program" mode, as previously saved  by
@ref{2ed0,,def_prog_mode()}.
@end deffn

@geindex reset_shell_mode() (dans le module curses)
@anchor{library/curses curses reset_shell_mode}@anchor{2ed3}
@deffn {Fonction} curses.reset_shell_mode ()

Restore the  terminal  to "shell" mode, as previously saved  by
@ref{2ed2,,def_shell_mode()}.
@end deffn

@geindex resetty() (dans le module curses)
@anchor{library/curses curses resetty}@anchor{2f07}
@deffn {Fonction} curses.resetty ()

Restore the state of the terminal modes to what it was at the last call to
@ref{2f08,,savetty()}.
@end deffn

@geindex resize_term() (dans le module curses)
@anchor{library/curses curses resize_term}@anchor{1532}
@deffn {Fonction} curses.resize_term (nlines, ncols)

Backend function used by @ref{1531,,resizeterm()}, performing most of the work;
when resizing the windows, @ref{1532,,resize_term()} blank-fills the areas that are
extended.  The calling application should fill in these areas with
appropriate data.  The @code{resize_term()} function attempts to resize all
windows.  However, due to the calling convention of pads, it is not possible
to resize these without additional interaction with the application.
@end deffn

@geindex resizeterm() (dans le module curses)
@anchor{library/curses curses resizeterm}@anchor{1531}
@deffn {Fonction} curses.resizeterm (nlines, ncols)

Resize the standard and current windows to the specified dimensions, and
adjusts other bookkeeping data used by the curses library that record the
window dimensions (in particular the SIGWINCH handler).
@end deffn

@geindex savetty() (dans le module curses)
@anchor{library/curses curses savetty}@anchor{2f08}
@deffn {Fonction} curses.savetty ()

Save the current state of the terminal modes in a buffer, usable by
@ref{2f07,,resetty()}.
@end deffn

@geindex get_escdelay() (dans le module curses)
@anchor{library/curses curses get_escdelay}@anchor{8dd}
@deffn {Fonction} curses.get_escdelay ()

Retrieves the value set by @ref{8de,,set_escdelay()}.


Ajouté dans la version 3.9.

@end deffn

@geindex set_escdelay() (dans le module curses)
@anchor{library/curses curses set_escdelay}@anchor{8de}
@deffn {Fonction} curses.set_escdelay (ms)

Sets the number of milliseconds to wait after reading an escape character,
to distinguish between an individual escape character entered on the
keyboard from escape sequences sent by cursor and function keys.


Ajouté dans la version 3.9.

@end deffn

@geindex get_tabsize() (dans le module curses)
@anchor{library/curses curses get_tabsize}@anchor{8df}
@deffn {Fonction} curses.get_tabsize ()

Retrieves the value set by @ref{8e0,,set_tabsize()}.


Ajouté dans la version 3.9.

@end deffn

@geindex set_tabsize() (dans le module curses)
@anchor{library/curses curses set_tabsize}@anchor{8e0}
@deffn {Fonction} curses.set_tabsize (size)

Sets the number of columns used by the curses library when converting a tab
character to spaces as it adds the tab to a window.


Ajouté dans la version 3.9.

@end deffn

@geindex setsyx() (dans le module curses)
@anchor{library/curses curses setsyx}@anchor{2f09}
@deffn {Fonction} curses.setsyx (y, x)

Set the virtual screen cursor to `y', `x'. If `y' and `x' are both @code{-1}, then
@ref{2eeb,,leaveok} is set @code{True}.
@end deffn

@geindex setupterm() (dans le module curses)
@anchor{library/curses curses setupterm}@anchor{2f0a}
@deffn {Fonction} curses.setupterm (term=None, fd=-1)

Initialize the terminal.  `term' is a string giving
the terminal name, or @code{None}; if omitted or @code{None}, the value of the
@geindex TERM
@geindex variable d'environnement; TERM
@code{TERM} environment variable will be used.  `fd' is the
file descriptor to which any initialization sequences will be sent; if not
supplied or @code{-1}, the file descriptor for @code{sys.stdout} will be used.
@end deffn

@geindex start_color() (dans le module curses)
@anchor{library/curses curses start_color}@anchor{2f0b}
@deffn {Fonction} curses.start_color ()

Must be called if the programmer wants to use colors, and before any other color
manipulation routine is called.  It is good practice to call this routine right
after @ref{1528,,initscr()}.

@ref{2f0b,,start_color()} initializes eight basic colors (black, red,  green, yellow,
blue, magenta, cyan, and white), and two global variables in the @ref{2b,,curses}
module, @ref{2f0c,,COLORS} and @ref{2f0d,,COLOR_PAIRS}, containing the maximum number
of colors and color-pairs the terminal can support.  It also restores the colors
on the terminal to the values they had when the terminal was just turned on.
@end deffn

@geindex termattrs() (dans le module curses)
@anchor{library/curses curses termattrs}@anchor{2f0e}
@deffn {Fonction} curses.termattrs ()

Return a logical OR of all video attributes supported by the terminal.  This
information is useful when a curses program needs complete control over the
appearance of the screen.
@end deffn

@geindex termname() (dans le module curses)
@anchor{library/curses curses termname}@anchor{2f0f}
@deffn {Fonction} curses.termname ()

Return the value of the environment variable 
@geindex TERM
@geindex variable d'environnement; TERM
@code{TERM}, as a bytes object,
truncated to 14 characters.
@end deffn

@geindex tigetflag() (dans le module curses)
@anchor{library/curses curses tigetflag}@anchor{2f10}
@deffn {Fonction} curses.tigetflag (capname)

Return the value of the Boolean capability corresponding to the terminfo
capability name `capname' as an integer.  Return the value @code{-1} if `capname' is not a
Boolean capability, or @code{0} if it is canceled or absent from the terminal
description.
@end deffn

@geindex tigetnum() (dans le module curses)
@anchor{library/curses curses tigetnum}@anchor{2f11}
@deffn {Fonction} curses.tigetnum (capname)

Return the value of the numeric capability corresponding to the terminfo
capability name `capname' as an integer.  Return the value @code{-2} if `capname' is not a
numeric capability, or @code{-1} if it is canceled or absent from the terminal
description.
@end deffn

@geindex tigetstr() (dans le module curses)
@anchor{library/curses curses tigetstr}@anchor{2f12}
@deffn {Fonction} curses.tigetstr (capname)

Return the value of the string capability corresponding to the terminfo
capability name `capname' as a bytes object.  Return @code{None} if `capname'
is not a terminfo "string capability", or is canceled or absent from the
terminal description.
@end deffn

@geindex tparm() (dans le module curses)
@anchor{library/curses curses tparm}@anchor{2f13}
@deffn {Fonction} curses.tparm (str[, ...])

Instantiate the bytes object `str' with the supplied parameters, where `str' should
be a parameterized string obtained from the terminfo database.  E.g.
@code{tparm(tigetstr("cup"), 5, 3)} could result in @code{b'\033[6;4H'}, the exact
result depending on terminal type.
@end deffn

@geindex typeahead() (dans le module curses)
@anchor{library/curses curses typeahead}@anchor{2f14}
@deffn {Fonction} curses.typeahead (fd)

Specify that the file descriptor `fd' be used for typeahead checking.  If `fd'
is @code{-1}, then no typeahead checking is done.

The curses library does "line-breakout optimization" by looking for typeahead
periodically while updating the screen.  If input is found, and it is coming
from a tty, the current update is postponed until refresh or doupdate is called
again, allowing faster response to commands typed in advance. This function
allows specifying a different file descriptor for typeahead checking.
@end deffn

@geindex unctrl() (dans le module curses)
@anchor{library/curses curses unctrl}@anchor{2f15}
@deffn {Fonction} curses.unctrl (ch)

Return a bytes object which is a printable representation of the character `ch'.
Control characters are represented as a caret followed by the character, for
example as @code{b'^C'}. Printing characters are left as they are.
@end deffn

@geindex ungetch() (dans le module curses)
@anchor{library/curses curses ungetch}@anchor{2f16}
@deffn {Fonction} curses.ungetch (ch)

Push `ch' so the next @ref{2ee0,,getch()} will return it.

@cartouche
@quotation Note 
Only one `ch' can be pushed before @code{getch()} is called.
@end quotation
@end cartouche
@end deffn

@geindex update_lines_cols() (dans le module curses)
@anchor{library/curses curses update_lines_cols}@anchor{dd9}
@deffn {Fonction} curses.update_lines_cols ()

Update the @ref{1695,,LINES} and @ref{1696,,COLS} module variables.
Useful for detecting manual screen resize.


Ajouté dans la version 3.5.

@end deffn

@geindex unget_wch() (dans le module curses)
@anchor{library/curses curses unget_wch}@anchor{1081}
@deffn {Fonction} curses.unget_wch (ch)

Push `ch' so the next @ref{1080,,get_wch()} will return it.

@cartouche
@quotation Note 
Only one `ch' can be pushed before @code{get_wch()} is called.
@end quotation
@end cartouche


Ajouté dans la version 3.3.

@end deffn

@geindex ungetmouse() (dans le module curses)
@anchor{library/curses curses ungetmouse}@anchor{2f17}
@deffn {Fonction} curses.ungetmouse (id, x, y, z, bstate)

Push a @ref{2ee1,,KEY_MOUSE} event onto the input queue, associating the given
state data with it.
@end deffn

@geindex use_env() (dans le module curses)
@anchor{library/curses curses use_env}@anchor{2f18}
@deffn {Fonction} curses.use_env (flag)

If used, this function should be called before @ref{1528,,initscr()} or newterm are
called.  When `flag' is @code{False}, the values of lines and columns specified in the
terminfo database will be used, even if environment variables 
@geindex LINES
@geindex variable d'environnement; LINES
@code{LINES}
and 
@geindex COLUMNS
@geindex variable d'environnement; COLUMNS
@code{COLUMNS} (used by default) are set, or if curses is running in a
window (in which case default behavior would be to use the window size if
@geindex LINES
@geindex variable d'environnement; LINES
@code{LINES} and 
@geindex COLUMNS
@geindex variable d'environnement; COLUMNS
@code{COLUMNS} are not set).
@end deffn

@geindex use_default_colors() (dans le module curses)
@anchor{library/curses curses use_default_colors}@anchor{2ef4}
@deffn {Fonction} curses.use_default_colors ()

Allow use of default values for colors on terminals supporting this feature. Use
this to support transparency in your application.  The default color is assigned
to the color number @code{-1}. After calling this function,  @code{init_pair(x,
curses.COLOR_RED, -1)} initializes, for instance, color pair `x' to a red
foreground color on the default background.
@end deffn

@geindex wrapper() (dans le module curses)
@anchor{library/curses curses wrapper}@anchor{a6e}
@deffn {Fonction} curses.wrapper (func, /, *args, **kwargs)

Initialize curses and call another callable object, `func', which should be the
rest of your curses-using application.  If the application raises an exception,
this function will restore the terminal to a sane state before re-raising the
exception and generating a traceback.  The callable object `func' is then passed
the main window 'stdscr' as its first argument, followed by any other arguments
passed to @code{wrapper()}.  Before calling `func', @code{wrapper()} turns on
cbreak mode, turns off echo, enables the terminal keypad, and initializes colors
if the terminal has color support.  On exit (whether normally or by exception)
it restores cooked mode, turns on echo, and disables the terminal keypad.
@end deffn

@node Window Objects,Constantes<6>,Fonctions<6>,curses --- Terminal handling for character-cell displays
@anchor{library/curses curses-window-objects}@anchor{2ef5}@anchor{library/curses window-objects}@anchor{2f19}
@subsubsection Window Objects


Window objects, as returned by @ref{1528,,initscr()} and @ref{2eff,,newwin()} above, have
the following methods and attributes:

@geindex addch() (méthode curses.window)
@anchor{library/curses curses window addch}@anchor{2f1a}
@deffn {Méthode} window.addch (ch[, attr])

@deffnx {Méthode} window.addch (y, x, ch[, attr])

Paint character `ch' at @code{(y, x)} with attributes `attr', overwriting any
character previously painted at that location.  By default, the character
position and attributes are the current settings for the window object.

@cartouche
@quotation Note 
Writing outside the window, subwindow, or pad raises a @ref{2ec4,,curses.error}.
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the character is printed.
@end quotation
@end cartouche
@end deffn

@geindex addnstr() (méthode curses.window)
@anchor{library/curses curses window addnstr}@anchor{2f1b}
@deffn {Méthode} window.addnstr (str, n[, attr])

@deffnx {Méthode} window.addnstr (y, x, str, n[, attr])

Paint at most `n' characters of the character string `str' at
@code{(y, x)} with attributes
`attr', overwriting anything previously on the display.
@end deffn

@geindex addstr() (méthode curses.window)
@anchor{library/curses curses window addstr}@anchor{2ed7}
@deffn {Méthode} window.addstr (str[, attr])

@deffnx {Méthode} window.addstr (y, x, str[, attr])

Paint the character string `str' at @code{(y, x)} with attributes
`attr', overwriting anything previously on the display.

@cartouche
@quotation Note 

@itemize *

@item 
Writing outside the window, subwindow, or pad raises @ref{2ec4,,curses.error}.
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the string is printed.

@item 
A bug in ncurses@footnote{https://bugs.python.org/issue35924}, the backend
for this Python module, can cause SegFaults when resizing windows. This
is fixed in ncurses-6.1-20190511.  If you are stuck with an earlier
ncurses, you can avoid triggering this if you do not call @ref{2ed7,,addstr()}
with a `str' that has embedded newlines.  Instead, call @ref{2ed7,,addstr()}
separately for each line.
@end itemize
@end quotation
@end cartouche
@end deffn

@geindex attroff() (méthode curses.window)
@anchor{library/curses curses window attroff}@anchor{2f1c}
@deffn {Méthode} window.attroff (attr)

Remove attribute `attr' from the "background" set applied to all writes to the
current window.
@end deffn

@geindex attron() (méthode curses.window)
@anchor{library/curses curses window attron}@anchor{2f1d}
@deffn {Méthode} window.attron (attr)

Add attribute `attr' from the "background" set applied to all writes to the
current window.
@end deffn

@geindex attrset() (méthode curses.window)
@anchor{library/curses curses window attrset}@anchor{2f1e}
@deffn {Méthode} window.attrset (attr)

Set the "background" set of attributes to `attr'.  This set is initially
@code{0} (no attributes).
@end deffn

@geindex bkgd() (méthode curses.window)
@anchor{library/curses curses window bkgd}@anchor{2f1f}
@deffn {Méthode} window.bkgd (ch[, attr])

Set the background property of the window to the character `ch', with
attributes `attr'.  The change is then applied to every character position in
that window:


@itemize *

@item 
The attribute of every character in the window  is changed to the new
background attribute.

@item 
Wherever  the  former background character appears, it is changed to the new
background character.
@end itemize
@end deffn

@geindex bkgdset() (méthode curses.window)
@anchor{library/curses curses window bkgdset}@anchor{2f20}
@deffn {Méthode} window.bkgdset (ch[, attr])

Set the window's background.  A window's background consists of a character and
any combination of attributes.  The attribute part of the background is combined
(OR'ed) with all non-blank characters that are written into the window.  Both
the character and attribute parts of the background are combined with the blank
characters.  The background becomes a property of the character and moves with
the character through any scrolling and insert/delete line/character operations.
@end deffn

@geindex border() (méthode curses.window)
@anchor{library/curses curses window border}@anchor{2f21}
@deffn {Méthode} window.border ([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

Draw a border around the edges of the window. Each parameter specifies  the
character to use for a specific part of the border; see the table below for more
details.

@cartouche
@quotation Note 
A @code{0} value for any parameter will cause the default character to be used for
that parameter.  Keyword parameters can `not' be used.  The defaults are listed
in this table:
@end quotation
@end cartouche


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Paramètre

@tab

Description

@tab

Valeur par défaut

@item

`ls'

@tab

Left side

@tab

@ref{2f22,,ACS_VLINE}

@item

`rs'

@tab

Right side

@tab

@ref{2f22,,ACS_VLINE}

@item

`ts'

@tab

Top

@tab

@ref{2f23,,ACS_HLINE}

@item

`bs'

@tab

Bottom

@tab

@ref{2f23,,ACS_HLINE}

@item

`tl'

@tab

Upper-left corner

@tab

@ref{2f24,,ACS_ULCORNER}

@item

`tr'

@tab

Upper-right corner

@tab

@ref{2f25,,ACS_URCORNER}

@item

`bl'

@tab

Bottom-left corner

@tab

@ref{2f26,,ACS_LLCORNER}

@item

`br'

@tab

Bottom-right corner

@tab

@ref{2f27,,ACS_LRCORNER}

@end multitable

@end deffn

@geindex box() (méthode curses.window)
@anchor{library/curses curses window box}@anchor{2f28}
@deffn {Méthode} window.box ([vertch, horch])

Similar to @ref{2f21,,border()}, but both `ls' and `rs' are `vertch' and both `ts' and
`bs' are `horch'.  The default corner characters are always used by this function.
@end deffn

@geindex chgat() (méthode curses.window)
@anchor{library/curses curses window chgat}@anchor{2f29}
@deffn {Méthode} window.chgat (attr)

@deffnx {Méthode} window.chgat (num, attr)

@deffnx {Méthode} window.chgat (y, x, attr)

@deffnx {Méthode} window.chgat (y, x, num, attr)

Set the attributes of `num' characters at the current cursor position, or at
position @code{(y, x)} if supplied. If `num' is not given or is @code{-1},
the attribute will be set on all the characters to the end of the line.  This
function moves cursor to position @code{(y, x)} if supplied. The changed line
will be touched using the @ref{2f2a,,touchline()} method so that the contents will
be redisplayed by the next window refresh.
@end deffn

@geindex clear() (méthode curses.window)
@anchor{library/curses curses window clear}@anchor{2f2b}
@deffn {Méthode} window.clear ()

Like @ref{2f2c,,erase()}, but also cause the whole window to be repainted upon next
call to @ref{2ed8,,refresh()}.
@end deffn

@geindex clearok() (méthode curses.window)
@anchor{library/curses curses window clearok}@anchor{2f2d}
@deffn {Méthode} window.clearok (flag)

If `flag' is @code{True}, the next call to @ref{2ed8,,refresh()} will clear the window
completely.
@end deffn

@geindex clrtobot() (méthode curses.window)
@anchor{library/curses curses window clrtobot}@anchor{2f2e}
@deffn {Méthode} window.clrtobot ()

Erase from cursor to the end of the window: all lines below the cursor are
deleted, and then the equivalent of @ref{2f2f,,clrtoeol()} is performed.
@end deffn

@geindex clrtoeol() (méthode curses.window)
@anchor{library/curses curses window clrtoeol}@anchor{2f2f}
@deffn {Méthode} window.clrtoeol ()

Erase from cursor to the end of the line.
@end deffn

@geindex cursyncup() (méthode curses.window)
@anchor{library/curses curses window cursyncup}@anchor{2f30}
@deffn {Méthode} window.cursyncup ()

Update the current cursor position of all the ancestors of the window to
reflect the current cursor position of the window.
@end deffn

@geindex delch() (méthode curses.window)
@anchor{library/curses curses window delch}@anchor{2f31}
@deffn {Méthode} window.delch ([y, x])

Delete any character at @code{(y, x)}.
@end deffn

@geindex deleteln() (méthode curses.window)
@anchor{library/curses curses window deleteln}@anchor{2f32}
@deffn {Méthode} window.deleteln ()

Delete the line under the cursor. All following lines are moved up by one line.
@end deffn

@geindex derwin() (méthode curses.window)
@anchor{library/curses curses window derwin}@anchor{2f33}
@deffn {Méthode} window.derwin (begin_y, begin_x)

@deffnx {Méthode} window.derwin (nlines, ncols, begin_y, begin_x)

An abbreviation for "derive window", @ref{2f33,,derwin()} is the same as calling
@ref{2f34,,subwin()}, except that `begin_y' and `begin_x' are relative to the origin
of the window, rather than relative to the entire screen.  Return a window
object for the derived window.
@end deffn

@geindex echochar() (méthode curses.window)
@anchor{library/curses curses window echochar}@anchor{2f35}
@deffn {Méthode} window.echochar (ch[, attr])

Add character `ch' with attribute `attr', and immediately  call @ref{2ed8,,refresh()}
on the window.
@end deffn

@geindex enclose() (méthode curses.window)
@anchor{library/curses curses window enclose}@anchor{1865}
@deffn {Méthode} window.enclose (y, x)

Test whether the given pair of screen-relative character-cell coordinates are
enclosed by the given window, returning @code{True} or @code{False}.  It is useful for
determining what subset of the screen windows enclose the location of a mouse
event.


Modifié dans la version 3.10: Previously it returned @code{1} or @code{0} instead of @code{True} or @code{False}.

@end deffn

@geindex encoding (attribut curses.window)
@anchor{library/curses curses window encoding}@anchor{107f}
@deffn {Attribut} window.encoding

Encoding used to encode method arguments (Unicode strings and characters).
The encoding attribute is inherited from the parent window when a subwindow
is created, for example with @ref{2f34,,window.subwin()}.
By default, current locale encoding is used (see @ref{2db,,locale.getencoding()}).


Ajouté dans la version 3.3.

@end deffn

@geindex erase() (méthode curses.window)
@anchor{library/curses curses window erase}@anchor{2f2c}
@deffn {Méthode} window.erase ()

Clear the window.
@end deffn

@geindex getbegyx() (méthode curses.window)
@anchor{library/curses curses window getbegyx}@anchor{2f36}
@deffn {Méthode} window.getbegyx ()

Return a tuple @code{(y, x)} of coordinates of upper-left corner.
@end deffn

@geindex getbkgd() (méthode curses.window)
@anchor{library/curses curses window getbkgd}@anchor{2f37}
@deffn {Méthode} window.getbkgd ()

Return the given window's current background character/attribute pair.
@end deffn

@geindex getch() (méthode curses.window)
@anchor{library/curses curses window getch}@anchor{2ee0}
@deffn {Méthode} window.getch ([y, x])

Get a character. Note that the integer returned does `not' have to be in ASCII
range: function keys, keypad keys and so on are represented by numbers higher
than 255.  In no-delay mode, return @code{-1} if there is no input, otherwise
wait until a key is pressed.
@end deffn

@geindex get_wch() (méthode curses.window)
@anchor{library/curses curses window get_wch}@anchor{1080}
@deffn {Méthode} window.get_wch ([y, x])

Get a wide character. Return a character for most keys, or an integer for
function keys, keypad keys, and other special keys.
In no-delay mode, raise an exception if there is no input.


Ajouté dans la version 3.3.

@end deffn

@geindex getkey() (méthode curses.window)
@anchor{library/curses curses window getkey}@anchor{2f38}
@deffn {Méthode} window.getkey ([y, x])

Get a character, returning a string instead of an integer, as @ref{2ee0,,getch()}
does. Function keys, keypad keys and other special keys return a multibyte
string containing the key name.  In no-delay mode, raise an exception if
there is no input.
@end deffn

@geindex getmaxyx() (méthode curses.window)
@anchor{library/curses curses window getmaxyx}@anchor{2f39}
@deffn {Méthode} window.getmaxyx ()

Return a tuple @code{(y, x)} of the height and width of the window.
@end deffn

@geindex getparyx() (méthode curses.window)
@anchor{library/curses curses window getparyx}@anchor{2f3a}
@deffn {Méthode} window.getparyx ()

Return the beginning coordinates of this window relative to its parent window
as a tuple @code{(y, x)}.  Return @code{(-1, -1)} if this window has no
parent.
@end deffn

@geindex getstr() (méthode curses.window)
@anchor{library/curses curses window getstr}@anchor{2f3b}
@deffn {Méthode} window.getstr ()

@deffnx {Méthode} window.getstr (n)

@deffnx {Méthode} window.getstr (y, x)

@deffnx {Méthode} window.getstr (y, x, n)

Read a bytes object from the user, with primitive line editing capacity.
@end deffn

@geindex getyx() (méthode curses.window)
@anchor{library/curses curses window getyx}@anchor{2f3c}
@deffn {Méthode} window.getyx ()

Return a tuple @code{(y, x)} of current cursor position  relative to the window's
upper-left corner.
@end deffn

@geindex hline() (méthode curses.window)
@anchor{library/curses curses window hline}@anchor{2f3d}
@deffn {Méthode} window.hline (ch, n)

@deffnx {Méthode} window.hline (y, x, ch, n)

Display a horizontal line starting at @code{(y, x)} with length `n' consisting of
the character `ch'.
@end deffn

@geindex idcok() (méthode curses.window)
@anchor{library/curses curses window idcok}@anchor{2f3e}
@deffn {Méthode} window.idcok (flag)

If `flag' is @code{False}, curses no longer considers using the hardware insert/delete
character feature of the terminal; if `flag' is @code{True}, use of character insertion
and deletion is enabled.  When curses is first initialized, use of character
insert/delete is enabled by default.
@end deffn

@geindex idlok() (méthode curses.window)
@anchor{library/curses curses window idlok}@anchor{2f3f}
@deffn {Méthode} window.idlok (flag)

If `flag' is @code{True}, @ref{2b,,curses} will try and use hardware line
editing facilities. Otherwise, line insertion/deletion are disabled.
@end deffn

@geindex immedok() (méthode curses.window)
@anchor{library/curses curses window immedok}@anchor{2f40}
@deffn {Méthode} window.immedok (flag)

If `flag' is @code{True}, any change in the window image automatically causes the
window to be refreshed; you no longer have to call @ref{2ed8,,refresh()} yourself.
However, it may degrade performance considerably, due to repeated calls to
wrefresh.  This option is disabled by default.
@end deffn

@geindex inch() (méthode curses.window)
@anchor{library/curses curses window inch}@anchor{2f41}
@deffn {Méthode} window.inch ([y, x])

Return the character at the given position in the window. The bottom 8 bits are
the character proper, and upper bits are the attributes.
@end deffn

@geindex insch() (méthode curses.window)
@anchor{library/curses curses window insch}@anchor{2f42}
@deffn {Méthode} window.insch (ch[, attr])

@deffnx {Méthode} window.insch (y, x, ch[, attr])

Paint character `ch' at @code{(y, x)} with attributes `attr', moving the line from
position `x' right by one character.
@end deffn

@geindex insdelln() (méthode curses.window)
@anchor{library/curses curses window insdelln}@anchor{2f43}
@deffn {Méthode} window.insdelln (nlines)

Insert `nlines' lines into the specified window above the current line.  The
`nlines' bottom lines are lost.  For negative `nlines', delete `nlines' lines
starting with the one under the cursor, and move the remaining lines up.  The
bottom `nlines' lines are cleared.  The current cursor position remains the
same.
@end deffn

@geindex insertln() (méthode curses.window)
@anchor{library/curses curses window insertln}@anchor{2f44}
@deffn {Méthode} window.insertln ()

Insert a blank line under the cursor. All following lines are moved down by one
line.
@end deffn

@geindex insnstr() (méthode curses.window)
@anchor{library/curses curses window insnstr}@anchor{2f45}
@deffn {Méthode} window.insnstr (str, n[, attr])

@deffnx {Méthode} window.insnstr (y, x, str, n[, attr])

Insert a character string (as many characters as will fit on the line) before
the character under the cursor, up to `n' characters.   If `n' is zero or
negative, the entire string is inserted. All characters to the right of the
cursor are shifted right, with the rightmost characters on the line being lost.
The cursor position does not change (after moving to `y', `x', if specified).
@end deffn

@geindex insstr() (méthode curses.window)
@anchor{library/curses curses window insstr}@anchor{2f46}
@deffn {Méthode} window.insstr (str[, attr])

@deffnx {Méthode} window.insstr (y, x, str[, attr])

Insert a character string (as many characters as will fit on the line) before
the character under the cursor.  All characters to the right of the cursor are
shifted right, with the rightmost characters on the line being lost.  The cursor
position does not change (after moving to `y', `x', if specified).
@end deffn

@geindex instr() (méthode curses.window)
@anchor{library/curses curses window instr}@anchor{2f47}
@deffn {Méthode} window.instr ([n])

@deffnx {Méthode} window.instr (y, x[, n])

Return a bytes object of characters, extracted from the window starting at the
current cursor position, or at `y', `x' if specified. Attributes are stripped
from the characters.  If `n' is specified, @ref{2f47,,instr()} returns a string
at most `n' characters long (exclusive of the trailing NUL).
@end deffn

@geindex is_linetouched() (méthode curses.window)
@anchor{library/curses curses window is_linetouched}@anchor{2f48}
@deffn {Méthode} window.is_linetouched (line)

Return @code{True} if the specified line was modified since the last call to
@ref{2ed8,,refresh()}; otherwise return @code{False}.  Raise a @ref{2ec4,,curses.error}
exception if `line' is not valid for the given window.
@end deffn

@geindex is_wintouched() (méthode curses.window)
@anchor{library/curses curses window is_wintouched}@anchor{2f49}
@deffn {Méthode} window.is_wintouched ()

Return @code{True} if the specified window was modified since the last call to
@ref{2ed8,,refresh()}; otherwise return @code{False}.
@end deffn

@geindex keypad() (méthode curses.window)
@anchor{library/curses curses window keypad}@anchor{2f4a}
@deffn {Méthode} window.keypad (flag)

If `flag' is @code{True}, escape sequences generated by some keys (keypad,  function keys)
will be interpreted by @ref{2b,,curses}. If `flag' is @code{False}, escape sequences will be
left as is in the input stream.
@end deffn

@geindex leaveok() (méthode curses.window)
@anchor{library/curses curses window leaveok}@anchor{2eeb}
@deffn {Méthode} window.leaveok (flag)

If `flag' is @code{True}, cursor is left where it is on update, instead of being at "cursor
position."  This reduces cursor movement where possible. If possible the cursor
will be made invisible.

If `flag' is @code{False}, cursor will always be at "cursor position" after an update.
@end deffn

@geindex move() (méthode curses.window)
@anchor{library/curses curses window move}@anchor{2f4b}
@deffn {Méthode} window.move (new_y, new_x)

Move cursor to @code{(new_y, new_x)}.
@end deffn

@geindex mvderwin() (méthode curses.window)
@anchor{library/curses curses window mvderwin}@anchor{2f4c}
@deffn {Méthode} window.mvderwin (y, x)

Move the window inside its parent window.  The screen-relative parameters of
the window are not changed.  This routine is used to display different parts of
the parent window at the same physical position on the screen.
@end deffn

@geindex mvwin() (méthode curses.window)
@anchor{library/curses curses window mvwin}@anchor{2f4d}
@deffn {Méthode} window.mvwin (new_y, new_x)

Move the window so its upper-left corner is at @code{(new_y, new_x)}.
@end deffn

@geindex nodelay() (méthode curses.window)
@anchor{library/curses curses window nodelay}@anchor{2f4e}
@deffn {Méthode} window.nodelay (flag)

If `flag' is @code{True}, @ref{2ee0,,getch()} will be non-blocking.
@end deffn

@geindex notimeout() (méthode curses.window)
@anchor{library/curses curses window notimeout}@anchor{2f4f}
@deffn {Méthode} window.notimeout (flag)

If `flag' is @code{True}, escape sequences will not be timed out.

If `flag' is @code{False}, after a few milliseconds, an escape sequence will not be
interpreted, and will be left in the input stream as is.
@end deffn

@geindex noutrefresh() (méthode curses.window)
@anchor{library/curses curses window noutrefresh}@anchor{2ed6}
@deffn {Méthode} window.noutrefresh ()

Mark for refresh but wait.  This function updates the data structure
representing the desired state of the window, but does not force an update of
the physical screen.  To accomplish that, call  @ref{2ed5,,doupdate()}.
@end deffn

@geindex overlay() (méthode curses.window)
@anchor{library/curses curses window overlay}@anchor{2f50}
@deffn {Méthode} window.overlay (destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

Overlay the window on top of `destwin'. The windows need not be the same size,
only the overlapping region is copied. This copy is non-destructive, which means
that the current background character does not overwrite the old contents of
`destwin'.

To get fine-grained control over the copied region, the second form of
@ref{2f50,,overlay()} can be used. `sminrow' and `smincol' are the upper-left
coordinates of the source window, and the other variables mark a rectangle in
the destination window.
@end deffn

@geindex overwrite() (méthode curses.window)
@anchor{library/curses curses window overwrite}@anchor{2f51}
@deffn {Méthode} window.overwrite (destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

Overwrite the window on top of `destwin'. The windows need not be the same size,
in which case only the overlapping region is copied. This copy is destructive,
which means that the current background character overwrites the old contents of
`destwin'.

To get fine-grained control over the copied region, the second form of
@ref{2f51,,overwrite()} can be used. `sminrow' and `smincol' are the upper-left
coordinates of the source window, the other variables mark a rectangle in the
destination window.
@end deffn

@geindex putwin() (méthode curses.window)
@anchor{library/curses curses window putwin}@anchor{2eed}
@deffn {Méthode} window.putwin (file)

Write all data associated with the window into the provided file object.  This
information can be later retrieved using the @ref{2eec,,getwin()} function.
@end deffn

@geindex redrawln() (méthode curses.window)
@anchor{library/curses curses window redrawln}@anchor{2f52}
@deffn {Méthode} window.redrawln (beg, num)

Indicate that the `num' screen lines, starting at line `beg', are corrupted and
should be completely redrawn on the next @ref{2ed8,,refresh()} call.
@end deffn

@geindex redrawwin() (méthode curses.window)
@anchor{library/curses curses window redrawwin}@anchor{2f53}
@deffn {Méthode} window.redrawwin ()

Touch the entire window, causing it to be completely redrawn on the next
@ref{2ed8,,refresh()} call.
@end deffn

@geindex refresh() (méthode curses.window)
@anchor{library/curses curses window refresh}@anchor{2ed8}
@deffn {Méthode} window.refresh ([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])

Update the display immediately (sync actual screen with previous
drawing/deleting methods).

The 6 optional arguments can only be specified when the window is a pad created
with @ref{2efe,,newpad()}.  The additional parameters are needed to indicate what part
of the pad and screen are involved. `pminrow' and `pmincol' specify the upper
left-hand corner of the rectangle to be displayed in the pad.  `sminrow',
`smincol', `smaxrow', and `smaxcol' specify the edges of the rectangle to be
displayed on the screen.  The lower right-hand corner of the rectangle to be
displayed in the pad is calculated from the screen coordinates, since the
rectangles must be the same size.  Both rectangles must be entirely contained
within their respective structures.  Negative values of `pminrow', `pmincol',
`sminrow', or `smincol' are treated as if they were zero.
@end deffn

@geindex resize() (méthode curses.window)
@anchor{library/curses curses window resize}@anchor{2f54}
@deffn {Méthode} window.resize (nlines, ncols)

Reallocate storage for a curses window to adjust its dimensions to the
specified values.  If either dimension is larger than the current values, the
window's data is filled with blanks that have the current background
rendition (as set by @ref{2f20,,bkgdset()}) merged into them.
@end deffn

@geindex scroll() (méthode curses.window)
@anchor{library/curses curses window scroll}@anchor{2f55}
@deffn {Méthode} window.scroll ([lines=1])

Scroll the screen or scrolling region upward by `lines' lines.
@end deffn

@geindex scrollok() (méthode curses.window)
@anchor{library/curses curses window scrollok}@anchor{2f56}
@deffn {Méthode} window.scrollok (flag)

Control what happens when the cursor of a window is moved off the edge of the
window or scrolling region, either as a result of a newline action on the bottom
line, or typing the last character of the last line.  If `flag' is @code{False}, the
cursor is left on the bottom line.  If `flag' is @code{True}, the window is scrolled up
one line.  Note that in order to get the physical scrolling effect on the
terminal, it is also necessary to call @ref{2f3f,,idlok()}.
@end deffn

@geindex setscrreg() (méthode curses.window)
@anchor{library/curses curses window setscrreg}@anchor{2f57}
@deffn {Méthode} window.setscrreg (top, bottom)

Set the scrolling region from line `top' to line `bottom'. All scrolling actions
will take place in this region.
@end deffn

@geindex standend() (méthode curses.window)
@anchor{library/curses curses window standend}@anchor{2f58}
@deffn {Méthode} window.standend ()

Turn off the standout attribute.  On some terminals this has the side effect of
turning off all attributes.
@end deffn

@geindex standout() (méthode curses.window)
@anchor{library/curses curses window standout}@anchor{2f59}
@deffn {Méthode} window.standout ()

Turn on attribute `A_STANDOUT'.
@end deffn

@geindex subpad() (méthode curses.window)
@anchor{library/curses curses window subpad}@anchor{2f5a}
@deffn {Méthode} window.subpad (begin_y, begin_x)

@deffnx {Méthode} window.subpad (nlines, ncols, begin_y, begin_x)

Return a sub-window, whose upper-left corner is at @code{(begin_y, begin_x)}, and
whose width/height is `ncols'/`nlines'.
@end deffn

@geindex subwin() (méthode curses.window)
@anchor{library/curses curses window subwin}@anchor{2f34}
@deffn {Méthode} window.subwin (begin_y, begin_x)

@deffnx {Méthode} window.subwin (nlines, ncols, begin_y, begin_x)

Return a sub-window, whose upper-left corner is at @code{(begin_y, begin_x)}, and
whose width/height is `ncols'/`nlines'.

By default, the sub-window will extend from the specified position to the lower
right corner of the window.
@end deffn

@geindex syncdown() (méthode curses.window)
@anchor{library/curses curses window syncdown}@anchor{2f5b}
@deffn {Méthode} window.syncdown ()

Touch each location in the window that has been touched in any of its ancestor
windows.  This routine is called by @ref{2ed8,,refresh()}, so it should almost never
be necessary to call it manually.
@end deffn

@geindex syncok() (méthode curses.window)
@anchor{library/curses curses window syncok}@anchor{2f5c}
@deffn {Méthode} window.syncok (flag)

If `flag' is @code{True}, then @ref{2f5d,,syncup()} is called automatically
whenever there is a change in the window.
@end deffn

@geindex syncup() (méthode curses.window)
@anchor{library/curses curses window syncup}@anchor{2f5d}
@deffn {Méthode} window.syncup ()

Touch all locations in ancestors of the window that have been changed in  the
window.
@end deffn

@geindex timeout() (méthode curses.window)
@anchor{library/curses curses window timeout}@anchor{2f5e}
@deffn {Méthode} window.timeout (delay)

Set blocking or non-blocking read behavior for the window.  If `delay' is
negative, blocking read is used (which will wait indefinitely for input).  If
`delay' is zero, then non-blocking read is used, and @ref{2ee0,,getch()} will
return @code{-1} if no input is waiting.  If `delay' is positive, then
@ref{2ee0,,getch()} will block for `delay' milliseconds, and return @code{-1} if there is
still no input at the end of that time.
@end deffn

@geindex touchline() (méthode curses.window)
@anchor{library/curses curses window touchline}@anchor{2f2a}
@deffn {Méthode} window.touchline (start, count[, changed])

Pretend `count' lines have been changed, starting with line `start'.  If
`changed' is supplied, it specifies whether the affected lines are marked as
having been changed (`changed'@code{=True}) or unchanged (`changed'@code{=False}).
@end deffn

@geindex touchwin() (méthode curses.window)
@anchor{library/curses curses window touchwin}@anchor{2f5f}
@deffn {Méthode} window.touchwin ()

Pretend the whole window has been changed, for purposes of drawing
optimizations.
@end deffn

@geindex untouchwin() (méthode curses.window)
@anchor{library/curses curses window untouchwin}@anchor{2f60}
@deffn {Méthode} window.untouchwin ()

Mark all lines in  the  window  as unchanged since the last call to
@ref{2ed8,,refresh()}.
@end deffn

@geindex vline() (méthode curses.window)
@anchor{library/curses curses window vline}@anchor{1717}
@deffn {Méthode} window.vline (ch, n[, attr])

@deffnx {Méthode} window.vline (y, x, ch, n[, attr])

Display a vertical line starting at @code{(y, x)} with length `n' consisting of the
character `ch' with attributes `attr'.
@end deffn

@node Constantes<6>,,Window Objects,curses --- Terminal handling for character-cell displays
@anchor{library/curses constants}@anchor{2f61}
@subsubsection Constantes


The @ref{2b,,curses} module defines the following data members:

@geindex ERR (dans le module curses)
@anchor{library/curses curses ERR}@anchor{2f62}
@deffn {Données} curses.ERR

Some curses routines  that  return  an integer, such as @ref{2ee0,,getch()}, return
@ref{2f62,,ERR} upon failure.
@end deffn

@geindex OK (dans le module curses)
@anchor{library/curses curses OK}@anchor{2f63}
@deffn {Données} curses.OK

Some curses routines  that  return  an integer, such as  @ref{1527,,napms()}, return
@ref{2f63,,OK} upon success.
@end deffn

@geindex version (dans le module curses)
@anchor{library/curses curses version}@anchor{2f64}
@deffn {Données} curses.version
@end deffn

@geindex __version__ (dans le module curses)
@anchor{library/curses curses __version__}@anchor{2f65}
@deffn {Données} curses.__version__

A bytes object representing the current version of the module.
@end deffn

@geindex ncurses_version (dans le module curses)
@anchor{library/curses curses ncurses_version}@anchor{9d5}
@deffn {Données} curses.ncurses_version

A named tuple containing the three components of the ncurses library
version: `major', `minor', and `patch'.  All values are integers.  The
components can also be accessed by name,  so @code{curses.ncurses_version[0]}
is equivalent to @code{curses.ncurses_version.major} and so on.

Availability: if the ncurses library is used.


Ajouté dans la version 3.8.

@end deffn

@geindex COLORS (dans le module curses)
@anchor{library/curses curses COLORS}@anchor{2f0c}
@deffn {Données} curses.COLORS

The maximum number of colors the terminal can support.
It is defined only after the call to @ref{2f0b,,start_color()}.
@end deffn

@geindex COLOR_PAIRS (dans le module curses)
@anchor{library/curses curses COLOR_PAIRS}@anchor{2f0d}
@deffn {Données} curses.COLOR_PAIRS

The maximum number of color pairs the terminal can support.
It is defined only after the call to @ref{2f0b,,start_color()}.
@end deffn

@geindex COLS (dans le module curses)
@anchor{library/curses curses COLS}@anchor{1696}
@deffn {Données} curses.COLS

The width of the screen, i.e., the number of columns.
It is defined only after the call to @ref{1528,,initscr()}.
Updated by @ref{dd9,,update_lines_cols()}, @ref{1531,,resizeterm()} and
@ref{1532,,resize_term()}.
@end deffn

@geindex LINES (dans le module curses)
@anchor{library/curses curses LINES}@anchor{1695}
@deffn {Données} curses.LINES

The height of the screen, i.e., the number of lines.
It is defined only after the call to @ref{1528,,initscr()}.
Updated by @ref{dd9,,update_lines_cols()}, @ref{1531,,resizeterm()} and
@ref{1532,,resize_term()}.
@end deffn

Some constants are available to specify character cell attributes.
The exact constants available are system dependent.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Signification

@item

@geindex A_ALTCHARSET (dans le module curses)
@anchor{library/curses curses A_ALTCHARSET}@anchor{2f66}
@deffn {Données} curses.A_ALTCHARSET
@end deffn

@tab

Alternate character set mode

@item

@geindex A_BLINK (dans le module curses)
@anchor{library/curses curses A_BLINK}@anchor{2f67}
@deffn {Données} curses.A_BLINK
@end deffn

@tab

Blink mode

@item

@geindex A_BOLD (dans le module curses)
@anchor{library/curses curses A_BOLD}@anchor{2f68}
@deffn {Données} curses.A_BOLD
@end deffn

@tab

Bold mode

@item

@geindex A_DIM (dans le module curses)
@anchor{library/curses curses A_DIM}@anchor{2f69}
@deffn {Données} curses.A_DIM
@end deffn

@tab

Dim mode

@item

@geindex A_INVIS (dans le module curses)
@anchor{library/curses curses A_INVIS}@anchor{2f6a}
@deffn {Données} curses.A_INVIS
@end deffn

@tab

Invisible or blank mode

@item

@geindex A_ITALIC (dans le module curses)
@anchor{library/curses curses A_ITALIC}@anchor{2f6b}
@deffn {Données} curses.A_ITALIC
@end deffn

@tab

Italic mode

@item

@geindex A_NORMAL (dans le module curses)
@anchor{library/curses curses A_NORMAL}@anchor{2ec5}
@deffn {Données} curses.A_NORMAL
@end deffn

@tab

Attribut normal

@item

@geindex A_PROTECT (dans le module curses)
@anchor{library/curses curses A_PROTECT}@anchor{2f6c}
@deffn {Données} curses.A_PROTECT
@end deffn

@tab

Protected mode

@item

@geindex A_REVERSE (dans le module curses)
@anchor{library/curses curses A_REVERSE}@anchor{2ecd}
@deffn {Données} curses.A_REVERSE
@end deffn

@tab

Reverse background and
foreground colors

@item

@geindex A_STANDOUT (dans le module curses)
@anchor{library/curses curses A_STANDOUT}@anchor{2ecc}
@deffn {Données} curses.A_STANDOUT
@end deffn

@tab

Standout mode

@item

@geindex A_UNDERLINE (dans le module curses)
@anchor{library/curses curses A_UNDERLINE}@anchor{2f6d}
@deffn {Données} curses.A_UNDERLINE
@end deffn

@tab

Underline mode

@item

@geindex A_HORIZONTAL (dans le module curses)
@anchor{library/curses curses A_HORIZONTAL}@anchor{2f6e}
@deffn {Données} curses.A_HORIZONTAL
@end deffn

@tab

Horizontal highlight

@item

@geindex A_LEFT (dans le module curses)
@anchor{library/curses curses A_LEFT}@anchor{2f6f}
@deffn {Données} curses.A_LEFT
@end deffn

@tab

Left highlight

@item

@geindex A_LOW (dans le module curses)
@anchor{library/curses curses A_LOW}@anchor{2f70}
@deffn {Données} curses.A_LOW
@end deffn

@tab

Low highlight

@item

@geindex A_RIGHT (dans le module curses)
@anchor{library/curses curses A_RIGHT}@anchor{2f71}
@deffn {Données} curses.A_RIGHT
@end deffn

@tab

Right highlight

@item

@geindex A_TOP (dans le module curses)
@anchor{library/curses curses A_TOP}@anchor{2f72}
@deffn {Données} curses.A_TOP
@end deffn

@tab

Top highlight

@item

@geindex A_VERTICAL (dans le module curses)
@anchor{library/curses curses A_VERTICAL}@anchor{2f73}
@deffn {Données} curses.A_VERTICAL
@end deffn

@tab

Vertical highlight

@end multitable



Ajouté dans la version 3.7: @code{A_ITALIC} was added.


Several constants are available to extract corresponding attributes returned
by some methods.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Bit-mask

@tab

Signification

@item

@geindex A_ATTRIBUTES (dans le module curses)
@anchor{library/curses curses A_ATTRIBUTES}@anchor{2f74}
@deffn {Données} curses.A_ATTRIBUTES
@end deffn

@tab

Bit-mask to extract
attributes

@item

@geindex A_CHARTEXT (dans le module curses)
@anchor{library/curses curses A_CHARTEXT}@anchor{2f75}
@deffn {Données} curses.A_CHARTEXT
@end deffn

@tab

Bit-mask to extract a
character

@item

@geindex A_COLOR (dans le module curses)
@anchor{library/curses curses A_COLOR}@anchor{2f76}
@deffn {Données} curses.A_COLOR
@end deffn

@tab

Bit-mask to extract
color-pair field information

@end multitable


Keys are referred to by integer constants with names starting with  @code{KEY_}.
The exact keycaps available are system dependent.

@c XXX this table is far too large! should it be alphabetized?


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Key constant

@tab

Clé

@item

@geindex KEY_MIN (dans le module curses)
@anchor{library/curses curses KEY_MIN}@anchor{2f77}
@deffn {Données} curses.KEY_MIN
@end deffn

@tab

Minimum key value

@item

@geindex KEY_BREAK (dans le module curses)
@anchor{library/curses curses KEY_BREAK}@anchor{2f78}
@deffn {Données} curses.KEY_BREAK
@end deffn

@tab

Break key (unreliable)

@item

@geindex KEY_DOWN (dans le module curses)
@anchor{library/curses curses KEY_DOWN}@anchor{2f79}
@deffn {Données} curses.KEY_DOWN
@end deffn

@tab

Down-arrow

@item

@geindex KEY_UP (dans le module curses)
@anchor{library/curses curses KEY_UP}@anchor{2f7a}
@deffn {Données} curses.KEY_UP
@end deffn

@tab

Up-arrow

@item

@geindex KEY_LEFT (dans le module curses)
@anchor{library/curses curses KEY_LEFT}@anchor{2f7b}
@deffn {Données} curses.KEY_LEFT
@end deffn

@tab

Left-arrow

@item

@geindex KEY_RIGHT (dans le module curses)
@anchor{library/curses curses KEY_RIGHT}@anchor{2f7c}
@deffn {Données} curses.KEY_RIGHT
@end deffn

@tab

Right-arrow

@item

@geindex KEY_HOME (dans le module curses)
@anchor{library/curses curses KEY_HOME}@anchor{2f7d}
@deffn {Données} curses.KEY_HOME
@end deffn

@tab

Home key (upward+left arrow)

@item

@geindex KEY_BACKSPACE (dans le module curses)
@anchor{library/curses curses KEY_BACKSPACE}@anchor{2f7e}
@deffn {Données} curses.KEY_BACKSPACE
@end deffn

@tab

Backspace (unreliable)

@item

@geindex KEY_F0 (dans le module curses)
@anchor{library/curses curses KEY_F0}@anchor{2f7f}
@deffn {Données} curses.KEY_F0
@end deffn

@tab

Function keys.  Up to 64 function keys are
supported.

@item

@geindex KEY_Fn (dans le module curses)
@anchor{library/curses curses KEY_Fn}@anchor{2f80}
@deffn {Données} curses.KEY_Fn
@end deffn

@tab

Value of function key `n'

@item

@geindex KEY_DL (dans le module curses)
@anchor{library/curses curses KEY_DL}@anchor{2f81}
@deffn {Données} curses.KEY_DL
@end deffn

@tab

Delete line

@item

@geindex KEY_IL (dans le module curses)
@anchor{library/curses curses KEY_IL}@anchor{2f82}
@deffn {Données} curses.KEY_IL
@end deffn

@tab

Insert line

@item

@geindex KEY_DC (dans le module curses)
@anchor{library/curses curses KEY_DC}@anchor{2f83}
@deffn {Données} curses.KEY_DC
@end deffn

@tab

Delete character

@item

@geindex KEY_IC (dans le module curses)
@anchor{library/curses curses KEY_IC}@anchor{2f84}
@deffn {Données} curses.KEY_IC
@end deffn

@tab

Insert char or enter insert mode

@item

@geindex KEY_EIC (dans le module curses)
@anchor{library/curses curses KEY_EIC}@anchor{2f85}
@deffn {Données} curses.KEY_EIC
@end deffn

@tab

Exit insert char mode

@item

@geindex KEY_CLEAR (dans le module curses)
@anchor{library/curses curses KEY_CLEAR}@anchor{2f86}
@deffn {Données} curses.KEY_CLEAR
@end deffn

@tab

Clear screen

@item

@geindex KEY_EOS (dans le module curses)
@anchor{library/curses curses KEY_EOS}@anchor{2f87}
@deffn {Données} curses.KEY_EOS
@end deffn

@tab

Clear to end of screen

@item

@geindex KEY_EOL (dans le module curses)
@anchor{library/curses curses KEY_EOL}@anchor{2f88}
@deffn {Données} curses.KEY_EOL
@end deffn

@tab

Clear to end of line

@item

@geindex KEY_SF (dans le module curses)
@anchor{library/curses curses KEY_SF}@anchor{2f89}
@deffn {Données} curses.KEY_SF
@end deffn

@tab

Scroll 1 line forward

@item

@geindex KEY_SR (dans le module curses)
@anchor{library/curses curses KEY_SR}@anchor{2f8a}
@deffn {Données} curses.KEY_SR
@end deffn

@tab

Scroll 1 line backward (reverse)

@item

@geindex KEY_NPAGE (dans le module curses)
@anchor{library/curses curses KEY_NPAGE}@anchor{2f8b}
@deffn {Données} curses.KEY_NPAGE
@end deffn

@tab

Next page

@item

@geindex KEY_PPAGE (dans le module curses)
@anchor{library/curses curses KEY_PPAGE}@anchor{2f8c}
@deffn {Données} curses.KEY_PPAGE
@end deffn

@tab

Previous page

@item

@geindex KEY_STAB (dans le module curses)
@anchor{library/curses curses KEY_STAB}@anchor{2f8d}
@deffn {Données} curses.KEY_STAB
@end deffn

@tab

Set tab

@item

@geindex KEY_CTAB (dans le module curses)
@anchor{library/curses curses KEY_CTAB}@anchor{2f8e}
@deffn {Données} curses.KEY_CTAB
@end deffn

@tab

Clear tab

@item

@geindex KEY_CATAB (dans le module curses)
@anchor{library/curses curses KEY_CATAB}@anchor{2f8f}
@deffn {Données} curses.KEY_CATAB
@end deffn

@tab

Clear all tabs

@item

@geindex KEY_ENTER (dans le module curses)
@anchor{library/curses curses KEY_ENTER}@anchor{2f90}
@deffn {Données} curses.KEY_ENTER
@end deffn

@tab

Enter or send (unreliable)

@item

@geindex KEY_SRESET (dans le module curses)
@anchor{library/curses curses KEY_SRESET}@anchor{2f91}
@deffn {Données} curses.KEY_SRESET
@end deffn

@tab

Soft (partial) reset (unreliable)

@item

@geindex KEY_RESET (dans le module curses)
@anchor{library/curses curses KEY_RESET}@anchor{2f92}
@deffn {Données} curses.KEY_RESET
@end deffn

@tab

Reset or hard reset (unreliable)

@item

@geindex KEY_PRINT (dans le module curses)
@anchor{library/curses curses KEY_PRINT}@anchor{2f93}
@deffn {Données} curses.KEY_PRINT
@end deffn

@tab

Print

@item

@geindex KEY_LL (dans le module curses)
@anchor{library/curses curses KEY_LL}@anchor{2f94}
@deffn {Données} curses.KEY_LL
@end deffn

@tab

Home down or bottom (lower left)

@item

@geindex KEY_A1 (dans le module curses)
@anchor{library/curses curses KEY_A1}@anchor{2f95}
@deffn {Données} curses.KEY_A1
@end deffn

@tab

Upper left of keypad

@item

@geindex KEY_A3 (dans le module curses)
@anchor{library/curses curses KEY_A3}@anchor{2f96}
@deffn {Données} curses.KEY_A3
@end deffn

@tab

Upper right of keypad

@item

@geindex KEY_B2 (dans le module curses)
@anchor{library/curses curses KEY_B2}@anchor{2f97}
@deffn {Données} curses.KEY_B2
@end deffn

@tab

Center of keypad

@item

@geindex KEY_C1 (dans le module curses)
@anchor{library/curses curses KEY_C1}@anchor{2f98}
@deffn {Données} curses.KEY_C1
@end deffn

@tab

Lower left of keypad

@item

@geindex KEY_C3 (dans le module curses)
@anchor{library/curses curses KEY_C3}@anchor{2f99}
@deffn {Données} curses.KEY_C3
@end deffn

@tab

Lower right of keypad

@item

@geindex KEY_BTAB (dans le module curses)
@anchor{library/curses curses KEY_BTAB}@anchor{2f9a}
@deffn {Données} curses.KEY_BTAB
@end deffn

@tab

Back tab

@item

@geindex KEY_BEG (dans le module curses)
@anchor{library/curses curses KEY_BEG}@anchor{2f9b}
@deffn {Données} curses.KEY_BEG
@end deffn

@tab

Beg (beginning)

@item

@geindex KEY_CANCEL (dans le module curses)
@anchor{library/curses curses KEY_CANCEL}@anchor{2f9c}
@deffn {Données} curses.KEY_CANCEL
@end deffn

@tab

Cancel

@item

@geindex KEY_CLOSE (dans le module curses)
@anchor{library/curses curses KEY_CLOSE}@anchor{2f9d}
@deffn {Données} curses.KEY_CLOSE
@end deffn

@tab

`Close'

@item

@geindex KEY_COMMAND (dans le module curses)
@anchor{library/curses curses KEY_COMMAND}@anchor{2f9e}
@deffn {Données} curses.KEY_COMMAND
@end deffn

@tab

Cmd (command)

@item

@geindex KEY_COPY (dans le module curses)
@anchor{library/curses curses KEY_COPY}@anchor{2f9f}
@deffn {Données} curses.KEY_COPY
@end deffn

@tab

`Copy'

@item

@geindex KEY_CREATE (dans le module curses)
@anchor{library/curses curses KEY_CREATE}@anchor{2fa0}
@deffn {Données} curses.KEY_CREATE
@end deffn

@tab

Create

@item

@geindex KEY_END (dans le module curses)
@anchor{library/curses curses KEY_END}@anchor{2fa1}
@deffn {Données} curses.KEY_END
@end deffn

@tab

End

@item

@geindex KEY_EXIT (dans le module curses)
@anchor{library/curses curses KEY_EXIT}@anchor{2fa2}
@deffn {Données} curses.KEY_EXIT
@end deffn

@tab

`Exit'

@item

@geindex KEY_FIND (dans le module curses)
@anchor{library/curses curses KEY_FIND}@anchor{2fa3}
@deffn {Données} curses.KEY_FIND
@end deffn

@tab

Find

@item

@geindex KEY_HELP (dans le module curses)
@anchor{library/curses curses KEY_HELP}@anchor{2fa4}
@deffn {Données} curses.KEY_HELP
@end deffn

@tab

Help

@item

@geindex KEY_MARK (dans le module curses)
@anchor{library/curses curses KEY_MARK}@anchor{2fa5}
@deffn {Données} curses.KEY_MARK
@end deffn

@tab

Mark

@item

@geindex KEY_MESSAGE (dans le module curses)
@anchor{library/curses curses KEY_MESSAGE}@anchor{2fa6}
@deffn {Données} curses.KEY_MESSAGE
@end deffn

@tab

Message

@item

@geindex KEY_MOVE (dans le module curses)
@anchor{library/curses curses KEY_MOVE}@anchor{2fa7}
@deffn {Données} curses.KEY_MOVE
@end deffn

@tab

Move

@item

@geindex KEY_NEXT (dans le module curses)
@anchor{library/curses curses KEY_NEXT}@anchor{2fa8}
@deffn {Données} curses.KEY_NEXT
@end deffn

@tab

Next

@item

@geindex KEY_OPEN (dans le module curses)
@anchor{library/curses curses KEY_OPEN}@anchor{2fa9}
@deffn {Données} curses.KEY_OPEN
@end deffn

@tab

Open

@item

@geindex KEY_OPTIONS (dans le module curses)
@anchor{library/curses curses KEY_OPTIONS}@anchor{2faa}
@deffn {Données} curses.KEY_OPTIONS
@end deffn

@tab

Options

@item

@geindex KEY_PREVIOUS (dans le module curses)
@anchor{library/curses curses KEY_PREVIOUS}@anchor{2fab}
@deffn {Données} curses.KEY_PREVIOUS
@end deffn

@tab

Prev (previous)

@item

@geindex KEY_REDO (dans le module curses)
@anchor{library/curses curses KEY_REDO}@anchor{2fac}
@deffn {Données} curses.KEY_REDO
@end deffn

@tab

`Redo'

@item

@geindex KEY_REFERENCE (dans le module curses)
@anchor{library/curses curses KEY_REFERENCE}@anchor{2fad}
@deffn {Données} curses.KEY_REFERENCE
@end deffn

@tab

Ref (reference)

@item

@geindex KEY_REFRESH (dans le module curses)
@anchor{library/curses curses KEY_REFRESH}@anchor{2fae}
@deffn {Données} curses.KEY_REFRESH
@end deffn

@tab

Refresh

@item

@geindex KEY_REPLACE (dans le module curses)
@anchor{library/curses curses KEY_REPLACE}@anchor{2faf}
@deffn {Données} curses.KEY_REPLACE
@end deffn

@tab

Replace

@item

@geindex KEY_RESTART (dans le module curses)
@anchor{library/curses curses KEY_RESTART}@anchor{2fb0}
@deffn {Données} curses.KEY_RESTART
@end deffn

@tab

Restart

@item

@geindex KEY_RESUME (dans le module curses)
@anchor{library/curses curses KEY_RESUME}@anchor{2fb1}
@deffn {Données} curses.KEY_RESUME
@end deffn

@tab

Resume

@item

@geindex KEY_SAVE (dans le module curses)
@anchor{library/curses curses KEY_SAVE}@anchor{2fb2}
@deffn {Données} curses.KEY_SAVE
@end deffn

@tab

`Save'

@item

@geindex KEY_SBEG (dans le module curses)
@anchor{library/curses curses KEY_SBEG}@anchor{2fb3}
@deffn {Données} curses.KEY_SBEG
@end deffn

@tab

Shifted Beg (beginning)

@item

@geindex KEY_SCANCEL (dans le module curses)
@anchor{library/curses curses KEY_SCANCEL}@anchor{2fb4}
@deffn {Données} curses.KEY_SCANCEL
@end deffn

@tab

Shifted Cancel

@item

@geindex KEY_SCOMMAND (dans le module curses)
@anchor{library/curses curses KEY_SCOMMAND}@anchor{2fb5}
@deffn {Données} curses.KEY_SCOMMAND
@end deffn

@tab

Shifted Command

@item

@geindex KEY_SCOPY (dans le module curses)
@anchor{library/curses curses KEY_SCOPY}@anchor{2fb6}
@deffn {Données} curses.KEY_SCOPY
@end deffn

@tab

Shifted Copy

@item

@geindex KEY_SCREATE (dans le module curses)
@anchor{library/curses curses KEY_SCREATE}@anchor{2fb7}
@deffn {Données} curses.KEY_SCREATE
@end deffn

@tab

Shifted Create

@item

@geindex KEY_SDC (dans le module curses)
@anchor{library/curses curses KEY_SDC}@anchor{2fb8}
@deffn {Données} curses.KEY_SDC
@end deffn

@tab

Shifted Delete char

@item

@geindex KEY_SDL (dans le module curses)
@anchor{library/curses curses KEY_SDL}@anchor{2fb9}
@deffn {Données} curses.KEY_SDL
@end deffn

@tab

Shifted Delete line

@item

@geindex KEY_SELECT (dans le module curses)
@anchor{library/curses curses KEY_SELECT}@anchor{2fba}
@deffn {Données} curses.KEY_SELECT
@end deffn

@tab

Select

@item

@geindex KEY_SEND (dans le module curses)
@anchor{library/curses curses KEY_SEND}@anchor{2fbb}
@deffn {Données} curses.KEY_SEND
@end deffn

@tab

Shifted End

@item

@geindex KEY_SEOL (dans le module curses)
@anchor{library/curses curses KEY_SEOL}@anchor{2fbc}
@deffn {Données} curses.KEY_SEOL
@end deffn

@tab

Shifted Clear line

@item

@geindex KEY_SEXIT (dans le module curses)
@anchor{library/curses curses KEY_SEXIT}@anchor{2fbd}
@deffn {Données} curses.KEY_SEXIT
@end deffn

@tab

Shifted Exit

@item

@geindex KEY_SFIND (dans le module curses)
@anchor{library/curses curses KEY_SFIND}@anchor{2fbe}
@deffn {Données} curses.KEY_SFIND
@end deffn

@tab

Shifted Find

@item

@geindex KEY_SHELP (dans le module curses)
@anchor{library/curses curses KEY_SHELP}@anchor{2fbf}
@deffn {Données} curses.KEY_SHELP
@end deffn

@tab

Shifted Help

@item

@geindex KEY_SHOME (dans le module curses)
@anchor{library/curses curses KEY_SHOME}@anchor{2fc0}
@deffn {Données} curses.KEY_SHOME
@end deffn

@tab

Shifted Home

@item

@geindex KEY_SIC (dans le module curses)
@anchor{library/curses curses KEY_SIC}@anchor{2fc1}
@deffn {Données} curses.KEY_SIC
@end deffn

@tab

Shifted Input

@item

@geindex KEY_SLEFT (dans le module curses)
@anchor{library/curses curses KEY_SLEFT}@anchor{2fc2}
@deffn {Données} curses.KEY_SLEFT
@end deffn

@tab

Shifted Left arrow

@item

@geindex KEY_SMESSAGE (dans le module curses)
@anchor{library/curses curses KEY_SMESSAGE}@anchor{2fc3}
@deffn {Données} curses.KEY_SMESSAGE
@end deffn

@tab

Shifted Message

@item

@geindex KEY_SMOVE (dans le module curses)
@anchor{library/curses curses KEY_SMOVE}@anchor{2fc4}
@deffn {Données} curses.KEY_SMOVE
@end deffn

@tab

Shifted Move

@item

@geindex KEY_SNEXT (dans le module curses)
@anchor{library/curses curses KEY_SNEXT}@anchor{2fc5}
@deffn {Données} curses.KEY_SNEXT
@end deffn

@tab

Shifted Next

@item

@geindex KEY_SOPTIONS (dans le module curses)
@anchor{library/curses curses KEY_SOPTIONS}@anchor{2fc6}
@deffn {Données} curses.KEY_SOPTIONS
@end deffn

@tab

Shifted Options

@item

@geindex KEY_SPREVIOUS (dans le module curses)
@anchor{library/curses curses KEY_SPREVIOUS}@anchor{2fc7}
@deffn {Données} curses.KEY_SPREVIOUS
@end deffn

@tab

Shifted Prev

@item

@geindex KEY_SPRINT (dans le module curses)
@anchor{library/curses curses KEY_SPRINT}@anchor{2fc8}
@deffn {Données} curses.KEY_SPRINT
@end deffn

@tab

Shifted Print

@item

@geindex KEY_SREDO (dans le module curses)
@anchor{library/curses curses KEY_SREDO}@anchor{2fc9}
@deffn {Données} curses.KEY_SREDO
@end deffn

@tab

Shifted Redo

@item

@geindex KEY_SREPLACE (dans le module curses)
@anchor{library/curses curses KEY_SREPLACE}@anchor{2fca}
@deffn {Données} curses.KEY_SREPLACE
@end deffn

@tab

Shifted Replace

@item

@geindex KEY_SRIGHT (dans le module curses)
@anchor{library/curses curses KEY_SRIGHT}@anchor{2fcb}
@deffn {Données} curses.KEY_SRIGHT
@end deffn

@tab

Shifted Right arrow

@item

@geindex KEY_SRSUME (dans le module curses)
@anchor{library/curses curses KEY_SRSUME}@anchor{2fcc}
@deffn {Données} curses.KEY_SRSUME
@end deffn

@tab

Shifted Resume

@item

@geindex KEY_SSAVE (dans le module curses)
@anchor{library/curses curses KEY_SSAVE}@anchor{2fcd}
@deffn {Données} curses.KEY_SSAVE
@end deffn

@tab

Shifted Save

@item

@geindex KEY_SSUSPEND (dans le module curses)
@anchor{library/curses curses KEY_SSUSPEND}@anchor{2fce}
@deffn {Données} curses.KEY_SSUSPEND
@end deffn

@tab

Shifted Suspend

@item

@geindex KEY_SUNDO (dans le module curses)
@anchor{library/curses curses KEY_SUNDO}@anchor{2fcf}
@deffn {Données} curses.KEY_SUNDO
@end deffn

@tab

Shifted Undo

@item

@geindex KEY_SUSPEND (dans le module curses)
@anchor{library/curses curses KEY_SUSPEND}@anchor{2fd0}
@deffn {Données} curses.KEY_SUSPEND
@end deffn

@tab

Suspend

@item

@geindex KEY_UNDO (dans le module curses)
@anchor{library/curses curses KEY_UNDO}@anchor{2fd1}
@deffn {Données} curses.KEY_UNDO
@end deffn

@tab

`Undo'

@item

@geindex KEY_MOUSE (dans le module curses)
@anchor{library/curses curses KEY_MOUSE}@anchor{2ee1}
@deffn {Données} curses.KEY_MOUSE
@end deffn

@tab

Mouse event has occurred

@item

@geindex KEY_RESIZE (dans le module curses)
@anchor{library/curses curses KEY_RESIZE}@anchor{2fd2}
@deffn {Données} curses.KEY_RESIZE
@end deffn

@tab

Terminal resize event

@item

@geindex KEY_MAX (dans le module curses)
@anchor{library/curses curses KEY_MAX}@anchor{2fd3}
@deffn {Données} curses.KEY_MAX
@end deffn

@tab

Maximum key value

@end multitable


On VT100s and their software emulations, such as X terminal emulators, there are
normally at least four function keys (@ref{2f80,,KEY_F1}, @ref{2f80,,KEY_F2},
@ref{2f80,,KEY_F3}, @ref{2f80,,KEY_F4}) available, and the arrow keys mapped to
@ref{2f7a,,KEY_UP}, @ref{2f79,,KEY_DOWN}, @ref{2f7b,,KEY_LEFT} and @ref{2f7c,,KEY_RIGHT} in
the obvious way.  If your machine has a PC keyboard, it is safe to expect arrow
keys and twelve function keys (older PC keyboards may have only ten function
keys); also, the following keypad mappings are standard:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 
@headitem

Keycap

@tab

Constante

@item

@code{Insert}

@tab

KEY_IC

@item

@code{Delete}

@tab

KEY_DC

@item

@code{Home}

@tab

KEY_HOME

@item

@code{End}

@tab

KEY_END

@item

@code{Page Up}

@tab

KEY_PPAGE

@item

@code{Page Down}

@tab

KEY_NPAGE

@end multitable

@anchor{library/curses curses-acs-codes}@anchor{2fd4}
The following table lists characters from the alternate character set. These are
inherited from the VT100 terminal, and will generally be  available on software
emulations such as X terminals.  When there is no graphic available, curses
falls back on a crude printable ASCII approximation.

@cartouche
@quotation Note 
These are available only after @ref{1528,,initscr()} has  been called.
@end quotation
@end cartouche


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ACS code

@tab

Signification

@item

@geindex ACS_BBSS (dans le module curses)
@anchor{library/curses curses ACS_BBSS}@anchor{2fd5}
@deffn {Données} curses.ACS_BBSS
@end deffn

@tab

alternate name for upper right corner

@item

@geindex ACS_BLOCK (dans le module curses)
@anchor{library/curses curses ACS_BLOCK}@anchor{2fd6}
@deffn {Données} curses.ACS_BLOCK
@end deffn

@tab

solid square block

@item

@geindex ACS_BOARD (dans le module curses)
@anchor{library/curses curses ACS_BOARD}@anchor{2fd7}
@deffn {Données} curses.ACS_BOARD
@end deffn

@tab

board of squares

@item

@geindex ACS_BSBS (dans le module curses)
@anchor{library/curses curses ACS_BSBS}@anchor{2fd8}
@deffn {Données} curses.ACS_BSBS
@end deffn

@tab

alternate name for horizontal line

@item

@geindex ACS_BSSB (dans le module curses)
@anchor{library/curses curses ACS_BSSB}@anchor{2fd9}
@deffn {Données} curses.ACS_BSSB
@end deffn

@tab

alternate name for upper left corner

@item

@geindex ACS_BSSS (dans le module curses)
@anchor{library/curses curses ACS_BSSS}@anchor{2fda}
@deffn {Données} curses.ACS_BSSS
@end deffn

@tab

alternate name for top tee

@item

@geindex ACS_BTEE (dans le module curses)
@anchor{library/curses curses ACS_BTEE}@anchor{2fdb}
@deffn {Données} curses.ACS_BTEE
@end deffn

@tab

bottom tee

@item

@geindex ACS_BULLET (dans le module curses)
@anchor{library/curses curses ACS_BULLET}@anchor{2fdc}
@deffn {Données} curses.ACS_BULLET
@end deffn

@tab

bullet

@item

@geindex ACS_CKBOARD (dans le module curses)
@anchor{library/curses curses ACS_CKBOARD}@anchor{2fdd}
@deffn {Données} curses.ACS_CKBOARD
@end deffn

@tab

checker board (stipple)

@item

@geindex ACS_DARROW (dans le module curses)
@anchor{library/curses curses ACS_DARROW}@anchor{2fde}
@deffn {Données} curses.ACS_DARROW
@end deffn

@tab

arrow pointing down

@item

@geindex ACS_DEGREE (dans le module curses)
@anchor{library/curses curses ACS_DEGREE}@anchor{2fdf}
@deffn {Données} curses.ACS_DEGREE
@end deffn

@tab

degree symbol

@item

@geindex ACS_DIAMOND (dans le module curses)
@anchor{library/curses curses ACS_DIAMOND}@anchor{2fe0}
@deffn {Données} curses.ACS_DIAMOND
@end deffn

@tab

diamond

@item

@geindex ACS_GEQUAL (dans le module curses)
@anchor{library/curses curses ACS_GEQUAL}@anchor{2fe1}
@deffn {Données} curses.ACS_GEQUAL
@end deffn

@tab

greater-than-or-equal-to

@item

@geindex ACS_HLINE (dans le module curses)
@anchor{library/curses curses ACS_HLINE}@anchor{2f23}
@deffn {Données} curses.ACS_HLINE
@end deffn

@tab

horizontal line

@item

@geindex ACS_LANTERN (dans le module curses)
@anchor{library/curses curses ACS_LANTERN}@anchor{2fe2}
@deffn {Données} curses.ACS_LANTERN
@end deffn

@tab

lantern symbol

@item

@geindex ACS_LARROW (dans le module curses)
@anchor{library/curses curses ACS_LARROW}@anchor{2fe3}
@deffn {Données} curses.ACS_LARROW
@end deffn

@tab

left arrow

@item

@geindex ACS_LEQUAL (dans le module curses)
@anchor{library/curses curses ACS_LEQUAL}@anchor{2fe4}
@deffn {Données} curses.ACS_LEQUAL
@end deffn

@tab

less-than-or-equal-to

@item

@geindex ACS_LLCORNER (dans le module curses)
@anchor{library/curses curses ACS_LLCORNER}@anchor{2f26}
@deffn {Données} curses.ACS_LLCORNER
@end deffn

@tab

lower left-hand corner

@item

@geindex ACS_LRCORNER (dans le module curses)
@anchor{library/curses curses ACS_LRCORNER}@anchor{2f27}
@deffn {Données} curses.ACS_LRCORNER
@end deffn

@tab

lower right-hand corner

@item

@geindex ACS_LTEE (dans le module curses)
@anchor{library/curses curses ACS_LTEE}@anchor{2fe5}
@deffn {Données} curses.ACS_LTEE
@end deffn

@tab

left tee

@item

@geindex ACS_NEQUAL (dans le module curses)
@anchor{library/curses curses ACS_NEQUAL}@anchor{2fe6}
@deffn {Données} curses.ACS_NEQUAL
@end deffn

@tab

not-equal sign

@item

@geindex ACS_PI (dans le module curses)
@anchor{library/curses curses ACS_PI}@anchor{2fe7}
@deffn {Données} curses.ACS_PI
@end deffn

@tab

letter pi

@item

@geindex ACS_PLMINUS (dans le module curses)
@anchor{library/curses curses ACS_PLMINUS}@anchor{2fe8}
@deffn {Données} curses.ACS_PLMINUS
@end deffn

@tab

plus-or-minus sign

@item

@geindex ACS_PLUS (dans le module curses)
@anchor{library/curses curses ACS_PLUS}@anchor{2fe9}
@deffn {Données} curses.ACS_PLUS
@end deffn

@tab

big plus sign

@item

@geindex ACS_RARROW (dans le module curses)
@anchor{library/curses curses ACS_RARROW}@anchor{2fea}
@deffn {Données} curses.ACS_RARROW
@end deffn

@tab

right arrow

@item

@geindex ACS_RTEE (dans le module curses)
@anchor{library/curses curses ACS_RTEE}@anchor{2feb}
@deffn {Données} curses.ACS_RTEE
@end deffn

@tab

right tee

@item

@geindex ACS_S1 (dans le module curses)
@anchor{library/curses curses ACS_S1}@anchor{2fec}
@deffn {Données} curses.ACS_S1
@end deffn

@tab

scan line 1

@item

@geindex ACS_S3 (dans le module curses)
@anchor{library/curses curses ACS_S3}@anchor{2fed}
@deffn {Données} curses.ACS_S3
@end deffn

@tab

scan line 3

@item

@geindex ACS_S7 (dans le module curses)
@anchor{library/curses curses ACS_S7}@anchor{2fee}
@deffn {Données} curses.ACS_S7
@end deffn

@tab

scan line 7

@item

@geindex ACS_S9 (dans le module curses)
@anchor{library/curses curses ACS_S9}@anchor{2fef}
@deffn {Données} curses.ACS_S9
@end deffn

@tab

scan line 9

@item

@geindex ACS_SBBS (dans le module curses)
@anchor{library/curses curses ACS_SBBS}@anchor{2ff0}
@deffn {Données} curses.ACS_SBBS
@end deffn

@tab

alternate name for lower right corner

@item

@geindex ACS_SBSB (dans le module curses)
@anchor{library/curses curses ACS_SBSB}@anchor{2ff1}
@deffn {Données} curses.ACS_SBSB
@end deffn

@tab

alternate name for vertical line

@item

@geindex ACS_SBSS (dans le module curses)
@anchor{library/curses curses ACS_SBSS}@anchor{2ff2}
@deffn {Données} curses.ACS_SBSS
@end deffn

@tab

alternate name for right tee

@item

@geindex ACS_SSBB (dans le module curses)
@anchor{library/curses curses ACS_SSBB}@anchor{2ff3}
@deffn {Données} curses.ACS_SSBB
@end deffn

@tab

alternate name for lower left corner

@item

@geindex ACS_SSBS (dans le module curses)
@anchor{library/curses curses ACS_SSBS}@anchor{2ff4}
@deffn {Données} curses.ACS_SSBS
@end deffn

@tab

alternate name for bottom tee

@item

@geindex ACS_SSSB (dans le module curses)
@anchor{library/curses curses ACS_SSSB}@anchor{2ff5}
@deffn {Données} curses.ACS_SSSB
@end deffn

@tab

alternate name for left tee

@item

@geindex ACS_SSSS (dans le module curses)
@anchor{library/curses curses ACS_SSSS}@anchor{2ff6}
@deffn {Données} curses.ACS_SSSS
@end deffn

@tab

alternate name for crossover or big plus

@item

@geindex ACS_STERLING (dans le module curses)
@anchor{library/curses curses ACS_STERLING}@anchor{2ff7}
@deffn {Données} curses.ACS_STERLING
@end deffn

@tab

pound sterling

@item

@geindex ACS_TTEE (dans le module curses)
@anchor{library/curses curses ACS_TTEE}@anchor{2ff8}
@deffn {Données} curses.ACS_TTEE
@end deffn

@tab

top tee

@item

@geindex ACS_UARROW (dans le module curses)
@anchor{library/curses curses ACS_UARROW}@anchor{2ff9}
@deffn {Données} curses.ACS_UARROW
@end deffn

@tab

up arrow

@item

@geindex ACS_ULCORNER (dans le module curses)
@anchor{library/curses curses ACS_ULCORNER}@anchor{2f24}
@deffn {Données} curses.ACS_ULCORNER
@end deffn

@tab

upper left corner

@item

@geindex ACS_URCORNER (dans le module curses)
@anchor{library/curses curses ACS_URCORNER}@anchor{2f25}
@deffn {Données} curses.ACS_URCORNER
@end deffn

@tab

upper right corner

@item

@geindex ACS_VLINE (dans le module curses)
@anchor{library/curses curses ACS_VLINE}@anchor{2f22}
@deffn {Données} curses.ACS_VLINE
@end deffn

@tab

vertical line

@end multitable


The following table lists mouse button constants used by @ref{2edf,,getmouse()}:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mouse button constant

@tab

Signification

@item

@geindex BUTTONn_PRESSED (dans le module curses)
@anchor{library/curses curses BUTTONn_PRESSED}@anchor{2ee2}
@deffn {Données} curses.BUTTONn_PRESSED
@end deffn

@tab

Mouse button `n' pressed

@item

@geindex BUTTONn_RELEASED (dans le module curses)
@anchor{library/curses curses BUTTONn_RELEASED}@anchor{2ee3}
@deffn {Données} curses.BUTTONn_RELEASED
@end deffn

@tab

Mouse button `n' released

@item

@geindex BUTTONn_CLICKED (dans le module curses)
@anchor{library/curses curses BUTTONn_CLICKED}@anchor{2ee4}
@deffn {Données} curses.BUTTONn_CLICKED
@end deffn

@tab

Mouse button `n' clicked

@item

@geindex BUTTONn_DOUBLE_CLICKED (dans le module curses)
@anchor{library/curses curses BUTTONn_DOUBLE_CLICKED}@anchor{2ee5}
@deffn {Données} curses.BUTTONn_DOUBLE_CLICKED
@end deffn

@tab

Mouse button `n' double clicked

@item

@geindex BUTTONn_TRIPLE_CLICKED (dans le module curses)
@anchor{library/curses curses BUTTONn_TRIPLE_CLICKED}@anchor{2ee6}
@deffn {Données} curses.BUTTONn_TRIPLE_CLICKED
@end deffn

@tab

Mouse button `n' triple clicked

@item

@geindex BUTTON_SHIFT (dans le module curses)
@anchor{library/curses curses BUTTON_SHIFT}@anchor{2ee7}
@deffn {Données} curses.BUTTON_SHIFT
@end deffn

@tab

Shift was down during button state change

@item

@geindex BUTTON_CTRL (dans le module curses)
@anchor{library/curses curses BUTTON_CTRL}@anchor{2ee8}
@deffn {Données} curses.BUTTON_CTRL
@end deffn

@tab

Control was down during button state change

@item

@geindex BUTTON_ALT (dans le module curses)
@anchor{library/curses curses BUTTON_ALT}@anchor{2ee9}
@deffn {Données} curses.BUTTON_ALT
@end deffn

@tab

Control was down during button state change

@end multitable



Modifié dans la version 3.10: The @code{BUTTON5_*} constants are now exposed if they are provided by the
underlying curses library.


The following table lists the predefined colors:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Color

@item

@geindex COLOR_BLACK (dans le module curses)
@anchor{library/curses curses COLOR_BLACK}@anchor{2ffa}
@deffn {Données} curses.COLOR_BLACK
@end deffn

@tab

Black

@item

@geindex COLOR_BLUE (dans le module curses)
@anchor{library/curses curses COLOR_BLUE}@anchor{2ffb}
@deffn {Données} curses.COLOR_BLUE
@end deffn

@tab

Blue

@item

@geindex COLOR_CYAN (dans le module curses)
@anchor{library/curses curses COLOR_CYAN}@anchor{2ffc}
@deffn {Données} curses.COLOR_CYAN
@end deffn

@tab

Cyan (light greenish blue)

@item

@geindex COLOR_GREEN (dans le module curses)
@anchor{library/curses curses COLOR_GREEN}@anchor{2ffd}
@deffn {Données} curses.COLOR_GREEN
@end deffn

@tab

Green

@item

@geindex COLOR_MAGENTA (dans le module curses)
@anchor{library/curses curses COLOR_MAGENTA}@anchor{2ffe}
@deffn {Données} curses.COLOR_MAGENTA
@end deffn

@tab

Magenta (purplish red)

@item

@geindex COLOR_RED (dans le module curses)
@anchor{library/curses curses COLOR_RED}@anchor{2fff}
@deffn {Données} curses.COLOR_RED
@end deffn

@tab

Red

@item

@geindex COLOR_WHITE (dans le module curses)
@anchor{library/curses curses COLOR_WHITE}@anchor{3000}
@deffn {Données} curses.COLOR_WHITE
@end deffn

@tab

White

@item

@geindex COLOR_YELLOW (dans le module curses)
@anchor{library/curses curses COLOR_YELLOW}@anchor{3001}
@deffn {Données} curses.COLOR_YELLOW
@end deffn

@tab

Yellow

@end multitable


@node curses textpad --- Text input widget for curses programs,curses ascii --- Utilities for ASCII characters,curses --- Terminal handling for character-cell displays,Command Line Interface Libraries
@anchor{library/curses curses-textpad-text-input-widget-for-curses-programs}@anchor{3002}@anchor{library/curses module-curses textpad}@anchor{2e}
@subsection @code{curses.textpad} --- Text input widget for curses programs


@geindex module; curses.textpad

The @ref{2e,,curses.textpad} module provides a @ref{3003,,Textbox} class that handles
elementary text editing in a curses window, supporting a set of keybindings
resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
FrameMaker, and many other programs).  The module also provides a
rectangle-drawing function useful for framing text boxes or for other purposes.

The module @ref{2e,,curses.textpad} defines the following function:

@geindex rectangle() (dans le module curses.textpad)
@anchor{library/curses curses textpad rectangle}@anchor{3004}
@deffn {Fonction} curses.textpad.rectangle (win, uly, ulx, lry, lrx)

Draw a rectangle.  The first argument must be a window object; the remaining
arguments are coordinates relative to that window.  The second and third
arguments are the y and x coordinates of the upper left hand corner of the
rectangle to be drawn; the fourth and fifth arguments are the y and x
coordinates of the lower right hand corner. The rectangle will be drawn using
VT100/IBM PC forms characters on terminals that make this possible (including
xterm and most other software terminal emulators).  Otherwise it will be drawn
with ASCII  dashes, vertical bars, and plus signs.
@end deffn

@menu
* Textbox objects:: 

@end menu

@node Textbox objects,,,curses textpad --- Text input widget for curses programs
@anchor{library/curses curses-textpad-objects}@anchor{3005}@anchor{library/curses textbox-objects}@anchor{3006}
@subsubsection Textbox objects


You can instantiate a @ref{3003,,Textbox} object as follows:

@geindex Textbox (classe dans curses.textpad)
@anchor{library/curses curses textpad Textbox}@anchor{3003}
@deffn {Classe} curses.textpad.Textbox (win)

Return a textbox widget object.  The `win' argument should be a curses
@ref{2ef5,,window} object in which the textbox is to
be contained. The edit cursor of the textbox is initially located at the
upper left hand corner of the containing window, with coordinates @code{(0, 0)}.
The instance's @ref{3007,,stripspaces} flag is initially on.

@ref{3003,,Textbox} objects have the following methods:

@geindex edit() (méthode curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox edit}@anchor{3008}
@deffn {Méthode} edit ([validator])

This is the entry point you will normally use.  It accepts editing
keystrokes until one of the termination keystrokes is entered.  If
`validator' is supplied, it must be a function.  It will be called for
each keystroke entered with the keystroke as a parameter; command dispatch
is done on the result. This method returns the window contents as a
string; whether blanks in the window are included is affected by the
@ref{3007,,stripspaces} attribute.
@end deffn

@geindex do_command() (méthode curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox do_command}@anchor{3009}
@deffn {Méthode} do_command (ch)

Process a single command keystroke.  Here are the supported special
keystrokes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Keystroke

@tab

Action

@item

@code{Control-A}

@tab

Go to left edge of window.

@item

@code{Control-B}

@tab

Cursor left, wrapping to previous line if
appropriate.

@item

@code{Control-D}

@tab

Delete character under cursor.

@item

@code{Control-E}

@tab

Go to right edge (stripspaces off) or end
of line (stripspaces on).

@item

@code{Control-F}

@tab

Cursor right, wrapping to next line when
appropriate.

@item

@code{Control-G}

@tab

Terminate, returning the window contents.

@item

@code{Control-H}

@tab

Delete character backward.

@item

@code{Control-J}

@tab

Terminate if the window is 1 line,
otherwise insert newline.

@item

@code{Control-K}

@tab

If line is blank, delete it, otherwise
clear to end of line.

@item

@code{Control-L}

@tab

Refresh screen.

@item

@code{Control-N}

@tab

Cursor down; move down one line.

@item

@code{Control-O}

@tab

Insert a blank line at cursor location.

@item

@code{Control-P}

@tab

Cursor up; move up one line.

@end multitable


Move operations do nothing if the cursor is at an edge where the movement
is not possible.  The following synonyms are supported where possible:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Keystroke

@item

@ref{2f7b,,KEY_LEFT}

@tab

@code{Control-B}

@item

@ref{2f7c,,KEY_RIGHT}

@tab

@code{Control-F}

@item

@ref{2f7a,,KEY_UP}

@tab

@code{Control-P}

@item

@ref{2f79,,KEY_DOWN}

@tab

@code{Control-N}

@item

@ref{2f7e,,KEY_BACKSPACE}

@tab

@code{Control-h}

@end multitable


All other keystrokes are treated as a command to insert the given
character and move right (with line wrapping).
@end deffn

@geindex gather() (méthode curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox gather}@anchor{300a}
@deffn {Méthode} gather ()

Return the window contents as a string; whether blanks in the
window are included is affected by the @ref{3007,,stripspaces} member.
@end deffn

@geindex stripspaces (attribut curses.textpad.Textbox)
@anchor{library/curses curses textpad Textbox stripspaces}@anchor{3007}
@deffn {Attribut} stripspaces

This attribute is a flag which controls the interpretation of blanks in
the window.  When it is on, trailing blanks on each line are ignored; any
cursor motion that would land the cursor on a trailing blank goes to the
end of that line instead, and trailing blanks are stripped when the window
contents are gathered.
@end deffn
@end deffn

@node curses ascii --- Utilities for ASCII characters,curses panel --- A panel stack extension for curses,curses textpad --- Text input widget for curses programs,Command Line Interface Libraries
@anchor{library/curses ascii doc}@anchor{300b}@anchor{library/curses ascii curses-ascii-utilities-for-ascii-characters}@anchor{300c}@anchor{library/curses ascii module-curses ascii}@anchor{2c}
@subsection @code{curses.ascii} --- Utilities for ASCII characters


@geindex module; curses.ascii

`Source code:' Lib/curses/ascii.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/curses/ascii.py}


__________________________________________________________________


The @ref{2c,,curses.ascii} module supplies name constants for ASCII characters and
functions to test membership in various ASCII character classes.  The constants
supplied are names for control characters as follows:


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Nom

@tab

Signification

@item

@geindex NUL (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii NUL}@anchor{300d}
@deffn {Données} curses.ascii.NUL
@end deffn

@tab

@item

@geindex SOH (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii SOH}@anchor{300e}
@deffn {Données} curses.ascii.SOH
@end deffn

@tab

Start of heading, console interrupt

@item

@geindex STX (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii STX}@anchor{300f}
@deffn {Données} curses.ascii.STX
@end deffn

@tab

Start of text

@item

@geindex ETX (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ETX}@anchor{3010}
@deffn {Données} curses.ascii.ETX
@end deffn

@tab

End of text

@item

@geindex EOT (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii EOT}@anchor{3011}
@deffn {Données} curses.ascii.EOT
@end deffn

@tab

End of transmission

@item

@geindex ENQ (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ENQ}@anchor{3012}
@deffn {Données} curses.ascii.ENQ
@end deffn

@tab

Enquiry, goes with @ref{3013,,ACK} flow control

@item

@geindex ACK (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ACK}@anchor{3013}
@deffn {Données} curses.ascii.ACK
@end deffn

@tab

Acknowledgement

@item

@geindex BEL (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii BEL}@anchor{3014}
@deffn {Données} curses.ascii.BEL
@end deffn

@tab

Bell

@item

@geindex BS (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii BS}@anchor{3015}
@deffn {Données} curses.ascii.BS
@end deffn

@tab

Backspace

@item

@geindex TAB (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii TAB}@anchor{3016}
@deffn {Données} curses.ascii.TAB
@end deffn

@tab

Tab

@item

@geindex HT (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii HT}@anchor{3017}
@deffn {Données} curses.ascii.HT
@end deffn

@tab

Alias for @ref{3016,,TAB}: "Horizontal tab"

@item

@geindex LF (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii LF}@anchor{3018}
@deffn {Données} curses.ascii.LF
@end deffn

@tab

Line feed

@item

@geindex NL (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii NL}@anchor{3019}
@deffn {Données} curses.ascii.NL
@end deffn

@tab

Alias for @ref{3018,,LF}: "New line"

@item

@geindex VT (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii VT}@anchor{301a}
@deffn {Données} curses.ascii.VT
@end deffn

@tab

Vertical tab

@item

@geindex FF (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii FF}@anchor{301b}
@deffn {Données} curses.ascii.FF
@end deffn

@tab

Form feed

@item

@geindex CR (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii CR}@anchor{301c}
@deffn {Données} curses.ascii.CR
@end deffn

@tab

Retour chariot

@item

@geindex SO (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii SO}@anchor{301d}
@deffn {Données} curses.ascii.SO
@end deffn

@tab

Shift-out, begin alternate character set

@item

@geindex SI (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii SI}@anchor{301e}
@deffn {Données} curses.ascii.SI
@end deffn

@tab

Shift-in, resume default character set

@item

@geindex DLE (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii DLE}@anchor{301f}
@deffn {Données} curses.ascii.DLE
@end deffn

@tab

Data-link escape

@item

@geindex DC1 (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii DC1}@anchor{3020}
@deffn {Données} curses.ascii.DC1
@end deffn

@tab

XON, for flow control

@item

@geindex DC2 (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii DC2}@anchor{3021}
@deffn {Données} curses.ascii.DC2
@end deffn

@tab

Device control 2, block-mode flow control

@item

@geindex DC3 (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii DC3}@anchor{3022}
@deffn {Données} curses.ascii.DC3
@end deffn

@tab

XOFF, for flow control

@item

@geindex DC4 (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii DC4}@anchor{3023}
@deffn {Données} curses.ascii.DC4
@end deffn

@tab

Device control 4

@item

@geindex NAK (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii NAK}@anchor{3024}
@deffn {Données} curses.ascii.NAK
@end deffn

@tab

Negative acknowledgement

@item

@geindex SYN (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii SYN}@anchor{3025}
@deffn {Données} curses.ascii.SYN
@end deffn

@tab

Synchronous idle

@item

@geindex ETB (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ETB}@anchor{3026}
@deffn {Données} curses.ascii.ETB
@end deffn

@tab

End transmission block

@item

@geindex CAN (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii CAN}@anchor{3027}
@deffn {Données} curses.ascii.CAN
@end deffn

@tab

Cancel

@item

@geindex EM (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii EM}@anchor{3028}
@deffn {Données} curses.ascii.EM
@end deffn

@tab

End of medium

@item

@geindex SUB (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii SUB}@anchor{3029}
@deffn {Données} curses.ascii.SUB
@end deffn

@tab

Substitute

@item

@geindex ESC (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ESC}@anchor{302a}
@deffn {Données} curses.ascii.ESC
@end deffn

@tab

Escape

@item

@geindex FS (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii FS}@anchor{302b}
@deffn {Données} curses.ascii.FS
@end deffn

@tab

Séparateur de fichiers

@item

@geindex GS (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii GS}@anchor{302c}
@deffn {Données} curses.ascii.GS
@end deffn

@tab

Séparateur de groupe

@item

@geindex RS (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii RS}@anchor{302d}
@deffn {Données} curses.ascii.RS
@end deffn

@tab

Record separator, block-mode terminator

@item

@geindex US (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii US}@anchor{302e}
@deffn {Données} curses.ascii.US
@end deffn

@tab

Unit separator

@item

@geindex SP (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii SP}@anchor{302f}
@deffn {Données} curses.ascii.SP
@end deffn

@tab

Space

@item

@geindex DEL (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii DEL}@anchor{3030}
@deffn {Données} curses.ascii.DEL
@end deffn

@tab

Delete

@end multitable


Note that many of these have little practical significance in modern usage.  The
mnemonics derive from teleprinter conventions that predate digital computers.

The module supplies the following functions, patterned on those in the standard
C library:

@geindex isalnum() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isalnum}@anchor{3031}
@deffn {Fonction} curses.ascii.isalnum (c)

Checks for an ASCII alphanumeric character; it is equivalent to @code{isalpha(c) or
isdigit(c)}.
@end deffn

@geindex isalpha() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isalpha}@anchor{3032}
@deffn {Fonction} curses.ascii.isalpha (c)

Checks for an ASCII alphabetic character; it is equivalent to @code{isupper(c) or
islower(c)}.
@end deffn

@geindex isascii() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isascii}@anchor{3033}
@deffn {Fonction} curses.ascii.isascii (c)

Checks for a character value that fits in the 7-bit ASCII set.
@end deffn

@geindex isblank() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isblank}@anchor{3034}
@deffn {Fonction} curses.ascii.isblank (c)

Checks for an ASCII whitespace character; space or horizontal tab.
@end deffn

@geindex iscntrl() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii iscntrl}@anchor{3035}
@deffn {Fonction} curses.ascii.iscntrl (c)

Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f).
@end deffn

@geindex isdigit() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isdigit}@anchor{3036}
@deffn {Fonction} curses.ascii.isdigit (c)

Checks for an ASCII decimal digit, @code{'0'} through @code{'9'}.  This is equivalent
to @code{c in string.digits}.
@end deffn

@geindex isgraph() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isgraph}@anchor{3037}
@deffn {Fonction} curses.ascii.isgraph (c)

Checks for ASCII any printable character except space.
@end deffn

@geindex islower() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii islower}@anchor{3038}
@deffn {Fonction} curses.ascii.islower (c)

Checks for an ASCII lower-case character.
@end deffn

@geindex isprint() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isprint}@anchor{3039}
@deffn {Fonction} curses.ascii.isprint (c)

Checks for any ASCII printable character including space.
@end deffn

@geindex ispunct() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ispunct}@anchor{303a}
@deffn {Fonction} curses.ascii.ispunct (c)

Checks for any printable ASCII character which is not a space or an alphanumeric
character.
@end deffn

@geindex isspace() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isspace}@anchor{303b}
@deffn {Fonction} curses.ascii.isspace (c)

Checks for ASCII white-space characters; space, line feed, carriage return, form
feed, horizontal tab, vertical tab.
@end deffn

@geindex isupper() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isupper}@anchor{303c}
@deffn {Fonction} curses.ascii.isupper (c)

Checks for an ASCII uppercase letter.
@end deffn

@geindex isxdigit() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isxdigit}@anchor{303d}
@deffn {Fonction} curses.ascii.isxdigit (c)

Checks for an ASCII hexadecimal digit.  This is equivalent to @code{c in
string.hexdigits}.
@end deffn

@geindex isctrl() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii isctrl}@anchor{303e}
@deffn {Fonction} curses.ascii.isctrl (c)

Checks for an ASCII control character (ordinal values 0 to 31).
@end deffn

@geindex ismeta() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ismeta}@anchor{303f}
@deffn {Fonction} curses.ascii.ismeta (c)

Checks for a non-ASCII character (ordinal values 0x80 and above).
@end deffn

These functions accept either integers or single-character strings; when the argument is a
string, it is first converted using the built-in function @ref{1e75,,ord()}.

Note that all these functions check ordinal bit values derived from the
character of the string you pass in; they do not actually know anything about
the host machine's character encoding.

The following two functions take either a single-character string or integer
byte value; they return a value of the same type.

@geindex ascii() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ascii}@anchor{3040}
@deffn {Fonction} curses.ascii.ascii (c)

Return the ASCII value corresponding to the low 7 bits of `c'.
@end deffn

@geindex ctrl() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii ctrl}@anchor{3041}
@deffn {Fonction} curses.ascii.ctrl (c)

Return the control character corresponding to the given character (the character
bit value is bitwise-anded with 0x1f).
@end deffn

@geindex alt() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii alt}@anchor{3042}
@deffn {Fonction} curses.ascii.alt (c)

Return the 8-bit character corresponding to the given ASCII character (the
character bit value is bitwise-ored with 0x80).
@end deffn

The following function takes either a single-character string or integer value;
it returns a string.

@geindex ^ (caret);in curses module
@geindex ! (exclamation);in curses module

@geindex unctrl() (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii unctrl}@anchor{3043}
@deffn {Fonction} curses.ascii.unctrl (c)

Return a string representation of the ASCII character `c'.  If `c' is printable,
this string is the character itself.  If the character is a control character
(0x00--0x1f) the string consists of a caret (@code{'^'}) followed by the
corresponding uppercase letter. If the character is an ASCII delete (0x7f) the
string is @code{'^?'}.  If the character has its meta bit (0x80) set, the meta bit
is stripped, the preceding rules applied, and @code{'!'} prepended to the result.
@end deffn

@geindex controlnames (dans le module curses.ascii)
@anchor{library/curses ascii curses ascii controlnames}@anchor{3044}
@deffn {Données} curses.ascii.controlnames

A 33-element string array that contains the ASCII mnemonics for the thirty-two
ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic
@code{SP} for the space character.
@end deffn

@node curses panel --- A panel stack extension for curses,,curses ascii --- Utilities for ASCII characters,Command Line Interface Libraries
@anchor{library/curses panel doc}@anchor{3045}@anchor{library/curses panel curses-panel-a-panel-stack-extension-for-curses}@anchor{3046}@anchor{library/curses panel module-curses panel}@anchor{2d}
@subsection @code{curses.panel} --- A panel stack extension for curses


@geindex module; curses.panel


__________________________________________________________________


Panels are windows with the added feature of depth, so they can be stacked on
top of each other, and only the visible portions of each window will be
displayed.  Panels can be added, moved up or down in the stack, and removed.

@menu
* Fonctions: Fonctions<7>. 
* Panel Objects:: 

@end menu

@node Fonctions<7>,Panel Objects,,curses panel --- A panel stack extension for curses
@anchor{library/curses panel cursespanel-functions}@anchor{3047}@anchor{library/curses panel functions}@anchor{3048}
@subsubsection Fonctions


The module @ref{2d,,curses.panel} defines the following functions:

@geindex bottom_panel() (dans le module curses.panel)
@anchor{library/curses panel curses panel bottom_panel}@anchor{3049}
@deffn {Fonction} curses.panel.bottom_panel ()

Returns the bottom panel in the panel stack.
@end deffn

@geindex new_panel() (dans le module curses.panel)
@anchor{library/curses panel curses panel new_panel}@anchor{304a}
@deffn {Fonction} curses.panel.new_panel (win)

Returns a panel object, associating it with the given window `win'. Be aware
that you need to keep the returned panel object referenced explicitly.  If you
don't, the panel object is garbage collected and removed from the panel stack.
@end deffn

@geindex top_panel() (dans le module curses.panel)
@anchor{library/curses panel curses panel top_panel}@anchor{304b}
@deffn {Fonction} curses.panel.top_panel ()

Returns the top panel in the panel stack.
@end deffn

@geindex update_panels() (dans le module curses.panel)
@anchor{library/curses panel curses panel update_panels}@anchor{304c}
@deffn {Fonction} curses.panel.update_panels ()

Updates the virtual screen after changes in the panel stack. This does not call
@ref{2ed5,,curses.doupdate()}, so you'll have to do this yourself.
@end deffn

@node Panel Objects,,Fonctions<7>,curses panel --- A panel stack extension for curses
@anchor{library/curses panel curses-panel-objects}@anchor{304d}@anchor{library/curses panel panel-objects}@anchor{304e}
@subsubsection Panel Objects


Panel objects, as returned by @ref{304a,,new_panel()} above, are windows with a
stacking order. There's always a window associated with a panel which determines
the content, while the panel methods are responsible for the window's depth in
the panel stack.

Panel objects have the following methods:

@geindex above() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel above}@anchor{304f}
@deffn {Méthode} Panel.above ()

Returns the panel above the current panel.
@end deffn

@geindex below() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel below}@anchor{3050}
@deffn {Méthode} Panel.below ()

Returns the panel below the current panel.
@end deffn

@geindex bottom() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel bottom}@anchor{3051}
@deffn {Méthode} Panel.bottom ()

Push the panel to the bottom of the stack.
@end deffn

@geindex hidden() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel hidden}@anchor{3052}
@deffn {Méthode} Panel.hidden ()

Returns @code{True} if the panel is hidden (not visible), @code{False} otherwise.
@end deffn

@geindex hide() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel hide}@anchor{3053}
@deffn {Méthode} Panel.hide ()

Hide the panel. This does not delete the object, it just makes the window on
screen invisible.
@end deffn

@geindex move() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel move}@anchor{3054}
@deffn {Méthode} Panel.move (y, x)

Move the panel to the screen coordinates @code{(y, x)}.
@end deffn

@geindex replace() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel replace}@anchor{3055}
@deffn {Méthode} Panel.replace (win)

Change the window associated with the panel to the window `win'.
@end deffn

@geindex set_userptr() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel set_userptr}@anchor{3056}
@deffn {Méthode} Panel.set_userptr (obj)

Set the panel's user pointer to `obj'. This is used to associate an arbitrary
piece of data with the panel, and can be any Python object.
@end deffn

@geindex show() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel show}@anchor{3057}
@deffn {Méthode} Panel.show ()

Display the panel (which might have been hidden).
@end deffn

@geindex top() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel top}@anchor{3058}
@deffn {Méthode} Panel.top ()

Push panel to the top of the stack.
@end deffn

@geindex userptr() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel userptr}@anchor{3059}
@deffn {Méthode} Panel.userptr ()

Returns the user pointer for the panel.  This might be any Python object.
@end deffn

@geindex window() (méthode curses.panel.Panel)
@anchor{library/curses panel curses panel Panel window}@anchor{305a}
@deffn {Méthode} Panel.window ()

Returns the window object associated with the panel.
@end deffn

@node Exécution concourante,Réseau et communication entre processus,Command Line Interface Libraries,La bibliothèque standard
@anchor{library/concurrency doc}@anchor{305b}@anchor{library/concurrency concurrency}@anchor{305c}@anchor{library/concurrency concurrent-execution}@anchor{305d}
@section Exécution concourante


Les modules documentés dans ce chapitre fournissent des outils d'exécution concourante de code. Le choix de l'outil approprié dépend de la tâche à exécuter (limitée par le CPU (`CPU bound'), ou limitée la vitesse des entrées-sorties (`IO bound')) et du style de développement désiré (coopération gérée par des évènements ou multitâche préemptif). En voici un survol :

@menu
* threading: threading --- Thread-based parallelism. Thread-based parallelism
* multiprocessing: multiprocessing --- Process-based parallelism. Process-based parallelism
* multiprocessing.shared_memory: multiprocessing shared_memory --- Shared memory for direct access across processes. Shared memory for direct access across
                                 processes
* The concurrent package:: 
* concurrent.futures: concurrent futures --- Launching parallel tasks. Launching parallel tasks
* subprocess: subprocess --- Subprocess management. Subprocess management
* sched: sched --- Event scheduler. Event scheduler
* queue: queue --- A synchronized queue class. A synchronized queue class
* contextvars: contextvars --- Context Variables. Context Variables
* _thread: _thread --- Low-level threading API. Low-level threading API

@end menu

@node threading --- Thread-based parallelism,multiprocessing --- Process-based parallelism,,Exécution concourante
@anchor{library/threading doc}@anchor{305e}@anchor{library/threading module-threading}@anchor{ec}@anchor{library/threading threading-thread-based-parallelism}@anchor{305f}
@subsection @code{threading} --- Thread-based parallelism


@geindex module; threading

`Code source :' Lib/threading.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/threading.py}


__________________________________________________________________


This module constructs higher-level threading interfaces on top of the lower
level @ref{2,,_thread} module.


Modifié dans la version 3.7: Ce module était auparavant optionnel, il est maintenant toujours disponible.



@subsubheading Voir aussi


@ref{72c,,concurrent.futures.ThreadPoolExecutor} offers a higher level interface
to push tasks to a background thread without blocking execution of the
calling thread, while still being able to retrieve their results when needed.

@ref{b5,,queue} provides a thread-safe interface for exchanging data between
running threads.

@ref{a,,asyncio} offers an alternative approach to achieving task level
concurrency without requiring the use of multiple operating system threads.


@cartouche
@quotation Note 
In the Python 2.x series, this module contained @code{camelCase} names
for some methods and functions. These are deprecated as of Python 3.10,
but they are still supported for compatibility with Python 2.5 and lower.
@end quotation
@end cartouche

`Particularité de l'implémentation CPython :' In CPython, due to the @ref{147,,Global Interpreter Lock}, only one thread
can execute Python code at once (even though certain performance-oriented
libraries might overcome this limitation).
If you want your application to make better use of the computational
resources of multi-core machines, you are advised to use
@ref{93,,multiprocessing} or @ref{8db,,concurrent.futures.ProcessPoolExecutor}.
However, threading is still an appropriate model if you want to run
multiple I/O-bound tasks simultaneously.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Ce module définit les fonctions suivantes :

@geindex active_count() (dans le module threading)
@anchor{library/threading threading active_count}@anchor{2ff}
@deffn {Fonction} threading.active_count ()

Renvoie le nombre d'objets @ref{939,,Thread} actuellement vivants. Le compte renvoyé est égal à la longueur de la liste renvoyée par @ref{1833,,enumerate()}.

The function @code{activeCount} is a deprecated alias for this function.
@end deffn

@geindex current_thread() (dans le module threading)
@anchor{library/threading threading current_thread}@anchor{2fe}
@deffn {Fonction} threading.current_thread ()

Renvoie l'objet @ref{939,,Thread} courant, correspondant au fil de contrôle de l'appelant. Si le fil de contrôle de l'appelant n'a pas été créé via le module @code{Thread}, un objet `thread' factice aux fonctionnalités limitées est renvoyé.

The function @code{currentThread} is a deprecated alias for this function.
@end deffn

@geindex excepthook() (dans le module threading)
@anchor{library/threading threading excepthook}@anchor{835}
@deffn {Fonction} threading.excepthook (args, /)

Gère les exceptions non-attrapées levées par @ref{a2b,,Thread.run()}.

L'argument `arg' a les attributs suivants :


@itemize *

@item 
`exc_type' : le type de l'exception ;

@item 
`exc_value': la valeur de l'exception, peut être @code{None} ;

@item 
`exc_traceback' : la pile d'appels pour cette exception, peut être @code{None} ;

@item 
`thread': le fil d'exécution ayant levé l'exception, peut être @code{None}.
@end itemize

Si `exc_type' est @ref{d2e,,SystemExit}, l'exception est ignorée silencieusement. Toutes les autres sont affichées sur @ref{926,,sys.stderr}.

Si cette fonction lève une exception, @ref{7f5,,sys.excepthook()} est appelée pour la gérer.

La fonction @ref{835,,threading.excepthook()} peut être surchargée afin de contrôler comment les exceptions non-attrapées levées par @ref{a2b,,Thread.run()} sont gérées.

Stocker `exc_value' en utilisant une fonction de rappel personnalisée peut créer un cycle de références. `exc_value' doit être nettoyée explicitement pour casser ce cycle lorsque l'exception n'est plus nécessaire.

Stocker `thread' en utilisant une fonction de rappel personnalisée peut le ressusciter, si c'est un objet en cours de finalisation. Évitez de stocker `thread' après la fin de la fonction de rappel, pour éviter de ressusciter des objets.


@subsubheading Voir aussi


@ref{7f5,,sys.excepthook()} gère les exceptions qui n'ont pas été attrapées.



Ajouté dans la version 3.8.

@end deffn

@geindex __excepthook__ (dans le module threading)
@anchor{library/threading threading __excepthook__}@anchor{834}
@deffn {Données} threading.__excepthook__

Holds the original value of @ref{835,,threading.excepthook()}. It is saved so that the
original value can be restored in case they happen to get replaced with
broken or alternative objects.


Ajouté dans la version 3.10.

@end deffn

@geindex get_ident() (dans le module threading)
@anchor{library/threading threading get_ident}@anchor{113a}
@deffn {Fonction} threading.get_ident ()

Renvoie l'« identifiant de fil »  du fil d'exécution courant. C'est un entier non nul. Sa valeur n'a pas de signification directe ; il est destiné à être utilisé comme valeur magique opaque, par exemple comme clef de dictionnaire de données pour chaque fil. Les identificateurs de fils peuvent être recyclés lorsqu'un fil se termine et qu'un autre fil est créé.


Ajouté dans la version 3.3.

@end deffn

@geindex get_native_id() (dans le module threading)
@anchor{library/threading threading get_native_id}@anchor{a2c}
@deffn {Fonction} threading.get_native_id ()

Renvoie l'identifiant natif complet assigné par le noyau du fil d'exécution actuel. C'est un entier non négatif. Sa valeur peut uniquement être utilisée pour identifier ce fil d'exécution à l'échelle du système (jusqu'à ce que le fil d'exécution se termine, après quoi la valeur peut être recyclée par le système d'exploitation).

@ref{1ce0,,Availability}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.


Ajouté dans la version 3.8.



Modifié dans la version 3.13: Added support for GNU/kFreeBSD.

@end deffn

@geindex enumerate() (dans le module threading)
@anchor{library/threading threading enumerate}@anchor{1833}
@deffn {Fonction} threading.enumerate ()

Return a list of all @ref{939,,Thread} objects currently active.  The list
includes daemonic threads and dummy thread objects created by
@ref{2fe,,current_thread()}.  It excludes terminated threads and threads
that have not yet been started.  However, the main thread is always part
of the result, even when terminated.
@end deffn

@geindex main_thread() (dans le module threading)
@anchor{library/threading threading main_thread}@anchor{fbd}
@deffn {Fonction} threading.main_thread ()

Renvoie l'objet fil d'exécution @ref{939,,Thread} principal. Dans des conditions normales, le fil principal est le fil à partir duquel l'interpréteur Python a été lancé.


Ajouté dans la version 3.4.

@end deffn

@geindex settrace() (dans le module threading)
@anchor{library/threading threading settrace}@anchor{832}
@deffn {Fonction} threading.settrace (func)

@geindex trace function

Attache une fonction de traçage pour tous les fils d'exécution démarrés depuis le module @code{Thread}. La fonction `func' est passée à @ref{14b6,,sys.settrace()} pour chaque fil, avant que sa méthode @ref{a2b,,run()} soit appelée.
@end deffn

@geindex settrace_all_threads() (dans le module threading)
@anchor{library/threading threading settrace_all_threads}@anchor{4b1}
@deffn {Fonction} threading.settrace_all_threads (func)

Set a trace function for all threads started from the @ref{ec,,threading} module
and all Python threads that are currently executing.

The `func' will be passed to  @ref{14b6,,sys.settrace()} for each thread, before its
@ref{a2b,,run()} method is called.


Ajouté dans la version 3.12.

@end deffn

@geindex gettrace() (dans le module threading)
@anchor{library/threading threading gettrace}@anchor{830}
@deffn {Fonction} threading.gettrace ()

@geindex trace function
@geindex debugger

Renvoie la fonction de traçage tel que définie par @ref{832,,settrace()}.


Ajouté dans la version 3.10.

@end deffn

@geindex setprofile() (dans le module threading)
@anchor{library/threading threading setprofile}@anchor{833}
@deffn {Fonction} threading.setprofile (func)

@geindex profile function

Attache une fonction de profilage pour tous les fils d'exécution démarrés depuis le module @code{Threading}. La fonction `func' est passée à @ref{14b5,,sys.setprofile()} pour chaque fil, avant que sa méthode @ref{a2b,,run()} soit appelée.
@end deffn

@geindex setprofile_all_threads() (dans le module threading)
@anchor{library/threading threading setprofile_all_threads}@anchor{4b2}
@deffn {Fonction} threading.setprofile_all_threads (func)

Set a profile function for all threads started from the @ref{ec,,threading} module
and all Python threads that are currently executing.

The `func' will be passed to  @ref{14b5,,sys.setprofile()} for each thread, before its
@ref{a2b,,run()} method is called.


Ajouté dans la version 3.12.

@end deffn

@geindex getprofile() (dans le module threading)
@anchor{library/threading threading getprofile}@anchor{831}
@deffn {Fonction} threading.getprofile ()

@geindex profile function

Renvoie la fonction de profilage tel que défini par @ref{833,,setprofile()}.


Ajouté dans la version 3.10.

@end deffn

@geindex stack_size() (dans le module threading)
@anchor{library/threading threading stack_size}@anchor{3060}
@deffn {Fonction} threading.stack_size ([size])

Renvoie la taille de la pile d'exécution utilisée lors de la création de nouveaux fils d'exécution. L'argument optionnel `size' spécifie la taille de pile à utiliser pour les fils créés ultérieurement, et doit être 0 (pour utiliser la taille de la plate-forme ou la valeur configurée par défaut) ou un entier positif supérieur ou égal à 32 768 (32 Kio). Si `size' n'est pas spécifié, 0 est utilisé. Si la modification de la taille de la pile de fils n'est pas prise en charge, une @ref{193,,RuntimeError} est levée. Si la taille de pile spécifiée n'est pas valide, une @ref{1ff,,ValueError} est levée et la taille de pile n'est pas modifiée. 32 Kio est actuellement la valeur minimale de taille de pile prise en charge pour garantir un espace de pile suffisant pour l'interpréteur lui-même. Notez que certaines plates-formes peuvent avoir des restrictions particulières sur les valeurs de taille de la pile, telles que l'exigence d'une taille de pile minimale > 32 Kio ou d'une allocation en multiples de la taille de page de la mémoire du système – la documentation de la plate-forme devrait être consultée pour plus d'informations (4 Kio sont courantes ; en l'absence de renseignements plus spécifiques, l'approche proposée est l'utilisation de multiples de 4 096 pour la taille de la pile).

@ref{1ce0,,Availability}: Windows, pthreads.

Unix platforms with POSIX threads support.
@end deffn

Ce module définit également la constante suivante :

@geindex TIMEOUT_MAX (dans le module threading)
@anchor{library/threading threading TIMEOUT_MAX}@anchor{3061}
@deffn {Données} threading.TIMEOUT_MAX

La valeur maximale autorisée pour le paramètre `timeout' des fonctions bloquantes (@ref{683,,Lock.acquire()}, @ref{e66,,RLock.acquire()}, @ref{183f,,Condition.wait()}, etc.). Spécifier un délai d'attente supérieur à cette valeur lève une @ref{86d,,OverflowError}.


Ajouté dans la version 3.2.

@end deffn

Ce module définit un certain nombre de classes, qui sont détaillées dans les sections ci-dessous.

La conception de ce module est librement basée sur le modèle des fils d'exécution de Java. Cependant, là où Java fait des verrous et des variables de condition le comportement de base de chaque objet, ils sont des objets séparés en Python. La classe Python @ref{939,,Thread} prend en charge un sous-ensemble du comportement de la classe `Thread' de Java ; actuellement, il n'y a aucune priorité, aucun groupe de fils d'exécution, et les fils ne peuvent être détruits, arrêtés, suspendus, repris ni interrompus. Les méthodes statiques de la classe `Thread' de Java, lorsqu'elles sont implémentées, correspondent à des fonctions au niveau du module.

Toutes les méthodes décrites ci-dessous sont exécutées de manière atomique.

@menu
* Données locales au fil d'exécution:: 
* Objets Threads:: 
* Verrous:: 
* RLock Objects:: 
* Condition Objects:: 
* Semaphore Objects:: 
* Event Objects:: 
* Timer Objects:: 
* Barrier Objects:: 
* Using locks@comma{} conditions@comma{} and semaphores in the with statement: Using locks conditions and semaphores in the with statement. 

@end menu

@node Données locales au fil d'exécution,Objets Threads,,threading --- Thread-based parallelism
@anchor{library/threading thread-local-data}@anchor{3062}
@subsubsection Données locales au fil d'exécution


Les données locales au fil d'exécution (`thread-local data') sont des données dont les valeurs sont propres à chaque fil. Pour gérer les données locales au fil, il suffit de créer une instance de @ref{16f9,,local} (ou une sous-classe) et d'y stocker des données :

@example
mydata = threading.local()
mydata.x = 1
@end example

Les valeurs dans l'instance sont différentes pour des `threads' différents.

@geindex local (classe dans threading)
@anchor{library/threading threading local}@anchor{16f9}
@deffn {Classe} threading.local

Classe qui représente les données locales au fil d'exécution.

For more details and extensive examples, see the documentation string of the
@code{_threading_local} module: Lib/_threading_local.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/_threading_local.py}.
@end deffn

@node Objets Threads,Verrous,Données locales au fil d'exécution,threading --- Thread-based parallelism
@anchor{library/threading id1}@anchor{3063}@anchor{library/threading thread-objects}@anchor{3064}
@subsubsection Objets `Threads'


The @ref{939,,Thread} class represents an activity that is run in a separate
thread of control.  There are two ways to specify the activity: by passing a
callable object to the constructor, or by overriding the @ref{a2b,,run()}
method in a subclass.  No other methods (except for the constructor) should be
overridden in a subclass.  In other words, `only'  override the
@code{__init__()} and @ref{a2b,,run()} methods of this class.

Une fois qu'un objet fil d'exécution est créé, son activité doit être lancée en appelant la méthode @ref{2c3a,,start()} du fil. Ceci invoque la méthode @ref{a2b,,run()} dans un fil d'exécution séparé.

Une fois que l'activité du fil d'exécution est lancée, le fil est considéré comme « vivant ». Il cesse d'être vivant lorsque sa méthode @ref{a2b,,run()} se termine – soit normalement, soit en levant une exception non gérée. La méthode @ref{93a,,is_alive()} teste si le fil est vivant.

D'autres fils d'exécution peuvent appeler la méthode @ref{11c1,,join()} d'un fil. Ceci bloque le fil appelant jusqu'à ce que le fil dont la méthode @ref{11c1,,join()} est appelée soit terminé.

Un fil d'exécution a un nom. Le nom peut être passé au constructeur, et lu ou modifié via l'attribut @ref{2fd,,name}.

Si la méthode @ref{a2b,,run()} lève une exception, @ref{835,,threading.excepthook()} est appelée pour s'en occuper. Par défaut, @ref{835,,threading.excepthook()} ignore silencieusement @ref{d2e,,SystemExit}.

Un fil d'exécution peut être marqué comme « fil démon ». Un programme Python se termine quand il ne reste plus que des fils démons. La valeur initiale est héritée du fil d'exécution qui l'a créé. Cette option peut être définie par la propriété @ref{2fb,,daemon} ou par l'argument `daemon' du constructeur.

@cartouche
@quotation Note 
Les fils d'exécution démons sont brusquement terminés à l'arrêt du programme Python. Leurs ressources (fichiers ouverts, transactions de base de données, etc.) peuvent ne pas être libérées correctement. Si vous voulez que vos fils s'arrêtent proprement, faites en sorte qu'ils ne soient pas démoniques et utilisez un mécanisme de signalisation approprié tel qu'un objet évènement @ref{1138,,Event}.
@end quotation
@end cartouche

Il y a un objet "fil principal", qui correspond au fil de contrôle initial dans le programme Python. Ce n'est pas un fil démon.

There is the possibility that "dummy thread objects" are created. These are
thread objects corresponding to "alien threads", which are threads of control
started outside the threading module, such as directly from C code.  Dummy
thread objects have limited functionality; they are always considered alive and
daemonic, and cannot be @ref{3065,,joined}.  They are never deleted,
since it is impossible to detect the termination of alien threads.

@geindex Thread (classe dans threading)
@anchor{library/threading threading Thread}@anchor{939}
@deffn {Classe} threading.Thread (group=None, target=None, name=None, args=(), kwargs=@{@}, *, daemon=None)

Ce constructeur doit toujours être appelé avec des arguments nommés. Les arguments sont :

`group' should be @code{None}; reserved for future extension when a
@code{ThreadGroup} class is implemented.

`target' est l'objet appelable qui doit être invoqué par la méthode @ref{a2b,,run()}. La valeur par défaut est @code{None}, ce qui signifie que rien n'est appelé.

`name' is the thread name. By default, a unique name is constructed
of the form "Thread-`N'" where `N' is a small decimal number,
or "Thread-`N' (target)" where "target" is @code{target.__name__} if the
`target' argument is specified.

`args' is a list or tuple of arguments for the target invocation.  Defaults to @code{()}.

`kwargs' est un dictionnaire d'arguments nommés pour l'invocation de l'objet appelable. La valeur par défaut est @code{@{@}}.

S'il ne vaut pas @code{None}, `daemon' définit explicitement si le fil d'exécution est démonique ou pas. S'il vaut @code{None} (par défaut), la valeur est héritée du fil courant.

Si la sous-classe réimplémente le constructeur, elle doit s'assurer d'appeler le constructeur de la classe de base (@code{Thread.__init__()}) avant de faire autre chose au fil d'exécution.


Modifié dans la version 3.3: Added the `daemon' parameter.



Modifié dans la version 3.10: Use the `target' name if `name' argument is omitted.


@geindex start() (méthode threading.Thread)
@anchor{library/threading threading Thread start}@anchor{2c3a}
@deffn {Méthode} start ()

Lance l'activité du fil d'exécution.

Elle ne doit être appelée qu'une fois par objet de fil. Elle fait en sorte que la méthode @ref{a2b,,run()} de l'objet soit invoquée dans un fil d'exécution.

Cette méthode lève une @ref{193,,RuntimeError} si elle est appelée plus d'une fois sur le même objet fil d'exécution.
@end deffn

@geindex run() (méthode threading.Thread)
@anchor{library/threading threading Thread run}@anchor{a2b}
@deffn {Méthode} run ()

Méthode représentant l'activité du fil d'exécution.

Vous pouvez remplacer cette méthode dans une sous-classe.  La méthode standard @ref{a2b,,run()} invoque l'objet appelable passé au constructeur de l'objet en tant qu'argument `target', le cas échéant, avec des arguments positionnels et des arguments nommés tirés respectivement des arguments `args' et `kwargs'.

Using list or tuple as the `args' argument which passed to the @ref{939,,Thread}
could achieve the same effect.

Example:

@example
>>> from threading import Thread
>>> t = Thread(target=print, args=[1])
>>> t.run()
1
>>> t = Thread(target=print, args=(1,))
>>> t.run()
1
@end example
@end deffn

@geindex join() (méthode threading.Thread)
@anchor{library/threading meth-thread-join}@anchor{3065}@anchor{library/threading threading Thread join}@anchor{11c1}
@deffn {Méthode} join (timeout=None)

Attend que le fil d'exécution se termine. Ceci bloque le fil appelant jusqu'à ce que le fil dont la méthode @ref{11c1,,join()} est appelée se termine – soit normalement, soit par une exception non gérée – ou jusqu'à ce que le délai optionnel `timeout' soit atteint.

When the `timeout' argument is present and not @code{None}, it should be a
floating-point number specifying a timeout for the operation in seconds
(or fractions thereof). As @ref{11c1,,join()} always returns @code{None},
you must call @ref{93a,,is_alive()} after @ref{11c1,,join()} to
decide whether a timeout happened -- if the thread is still alive, the
@ref{11c1,,join()} call timed out.

Lorsque l'argument `timeout' n'est pas présent ou vaut @code{None}, l'opération se bloque jusqu'à ce que le fil d'exécution se termine.

A thread can be joined many times.

@ref{11c1,,join()} lève une @ref{193,,RuntimeError} si une tentative est faite pour attendre le fil d'exécution courant car cela conduirait à un interblocage (`deadlock' en anglais). Attendre via @ref{11c1,,join()} un fil d'exécution avant son lancement est aussi une erreur et, si vous tentez de le faire, lève la même exception.
@end deffn

@geindex name (attribut threading.Thread)
@anchor{library/threading threading Thread name}@anchor{2fd}
@deffn {Attribut} name

Une chaîne de caractères utilisée à des fins d'identification seulement. Elle n'a pas de sémantique. Plusieurs fils d'exécution peuvent porter le même nom.  Le nom initial est défini par le constructeur.
@end deffn

@geindex getName() (méthode threading.Thread)
@geindex setName() (méthode threading.Thread)
@anchor{library/threading threading Thread getName}@anchor{3066}
@deffn {Méthode} getName ()
@anchor{library/threading threading Thread setName}@anchor{2fc}
@deffnx {Méthode} setName ()

Deprecated getter/setter API for @ref{2fd,,name}; use it directly as a
property instead.


Obsolète depuis la version 3.10.

@end deffn

@geindex ident (attribut threading.Thread)
@anchor{library/threading threading Thread ident}@anchor{2bc7}
@deffn {Attribut} ident

« L'identificateur de fil d'exécution » de ce fil ou @code{None} si le fil n'a pas été lancé. C'est un entier non nul. Voyez également la fonction @ref{113a,,get_ident()}. Les identificateurs de fils peuvent être recyclés lorsqu'un fil se termine et qu'un autre fil est créé. L'identifiant est disponible même après que le fil ait terminé.
@end deffn

@geindex native_id (attribut threading.Thread)
@anchor{library/threading threading Thread native_id}@anchor{a2d}
@deffn {Attribut} native_id

The Thread ID (@code{TID}) of this thread, as assigned by the OS (kernel).
This is a non-negative integer, or @code{None} if the thread has not
been started. See the @ref{a2c,,get_native_id()} function.
This value may be used to uniquely identify this particular thread
system-wide (until the thread terminates, after which the value
may be recycled by the OS).

@cartouche
@quotation Note 
Tout comme pour les `Process IDs', les `Thread IDs' ne sont valides (garantis uniques sur le système) uniquement du démarrage du fil à sa fin.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.


Ajouté dans la version 3.8.

@end deffn

@geindex is_alive() (méthode threading.Thread)
@anchor{library/threading threading Thread is_alive}@anchor{93a}
@deffn {Méthode} is_alive ()

Renvoie si le fil d'exécution est vivant ou pas.

Cette méthode renvoie @code{True} depuis juste avant le démarrage de la méthode @ref{a2b,,run()} et jusqu'à juste après la terminaison de la méthode @ref{a2b,,run()}. La fonction @ref{1833,,enumerate()} du module renvoie une liste de tous les fils d'exécution vivants.
@end deffn

@geindex daemon (attribut threading.Thread)
@anchor{library/threading threading Thread daemon}@anchor{2fb}
@deffn {Attribut} daemon

A boolean value indicating whether this thread is a daemon thread (@code{True})
or not (@code{False}).  This must be set before @ref{2c3a,,start()} is called,
otherwise @ref{193,,RuntimeError} is raised.  Its initial value is inherited
from the creating thread; the main thread is not a daemon thread and
therefore all threads created in the main thread default to
@ref{2fb,,daemon} = @code{False}.

Le programme Python se termine lorsqu'il ne reste plus de fils d'exécution non-démons vivants.
@end deffn

@geindex isDaemon() (méthode threading.Thread)
@geindex setDaemon() (méthode threading.Thread)
@anchor{library/threading threading Thread isDaemon}@anchor{3067}
@deffn {Méthode} isDaemon ()
@anchor{library/threading threading Thread setDaemon}@anchor{2fa}
@deffnx {Méthode} setDaemon ()

Deprecated getter/setter API for @ref{2fb,,daemon}; use it directly as a
property instead.


Obsolète depuis la version 3.10.

@end deffn
@end deffn

@node Verrous,RLock Objects,Objets Threads,threading --- Thread-based parallelism
@anchor{library/threading id2}@anchor{3068}@anchor{library/threading lock-objects}@anchor{3069}
@subsubsection Verrous


Un verrou primitif n'appartient pas à un fil d'exécution lorsqu'il est verrouillé. En Python, c'est actuellement la méthode de synchronisation la plus bas-niveau qui soit disponible, implémentée directement par le module d'extension @ref{2,,_thread}.

Un verrou primitif est soit « verrouillé » soit « déverrouillé ». Il est créé dans un état déverrouillé. Il a deux méthodes, @ref{683,,acquire()} et @ref{12a0,,release()}. Lorsque l'état est déverrouillé, @ref{683,,acquire()} verrouille et se termine immédiatement. Lorsque l'état est verrouillé, @ref{683,,acquire()} bloque jusqu'à ce qu'un appel à @ref{12a0,,release()} provenant d'un autre fil d'exécution le déverrouille. À ce moment @ref{683,,acquire()} le verrouille à nouveau et rend la main. La méthode @ref{12a0,,release()} ne doit être appelée que si le verrou est verrouillé, elle le déverrouille alors et se termine immédiatement. Déverrouiller un verrou qui n'est pas verrouillé provoque une @ref{193,,RuntimeError}.

Locks also support the @ref{306a,,context management protocol}.

When more than one thread is blocked in @ref{683,,acquire()} waiting for the
state to turn to unlocked, only one thread proceeds when a @ref{12a0,,release()}
call resets the state to unlocked; which one of the waiting threads proceeds
is not defined, and may vary across implementations.

All methods are executed atomically.

@geindex Lock (classe dans threading)
@anchor{library/threading threading Lock}@anchor{1600}
@deffn {Classe} threading.Lock

The class implementing primitive lock objects.  Once a thread has acquired a
lock, subsequent attempts to acquire it block, until it is released; any
thread may release it.


Modifié dans la version 3.13: @code{Lock} is now a class. In earlier Pythons, @code{Lock} was a factory
function which returned an instance of the underlying private lock
type.


@geindex acquire() (méthode threading.Lock)
@anchor{library/threading threading Lock acquire}@anchor{683}
@deffn {Méthode} acquire (blocking=True, timeout=-1)

Acquiert un verrou, bloquant ou non bloquant.

When invoked with the `blocking' argument set to @code{True} (the default),
block until the lock is unlocked, then set it to locked and return @code{True}.

When invoked with the `blocking' argument set to @code{False}, do not block.
If a call with `blocking' set to @code{True} would block, return @code{False}
immediately; otherwise, set the lock to locked and return @code{True}.

When invoked with the floating-point `timeout' argument set to a positive
value, block for at most the number of seconds specified by `timeout'
and as long as the lock cannot be acquired.  A `timeout' argument of @code{-1}
specifies an unbounded wait.  It is forbidden to specify a `timeout'
when `blocking' is @code{False}.

The return value is @code{True} if the lock is acquired successfully,
@code{False} if not (for example if the `timeout' expired).


Modifié dans la version 3.2: Le paramètre `timeout' est nouveau.



Modifié dans la version 3.2: Lock acquisition can now be interrupted by signals on POSIX if the
underlying threading implementation supports it.

@end deffn

@geindex release() (méthode threading.Lock)
@anchor{library/threading threading Lock release}@anchor{12a0}
@deffn {Méthode} release ()

Release a lock.  This can be called from any thread, not only the thread
which has acquired the lock.

When the lock is locked, reset it to unlocked, and return.  If any other threads
are blocked waiting for the lock to become unlocked, allow exactly one of them
to proceed.

Lorsqu'elle est invoquée sur un verrou déverrouillé, une @ref{193,,RuntimeError} est levée.

Il n'y a pas de valeur de retour.
@end deffn

@geindex locked() (méthode threading.Lock)
@anchor{library/threading threading Lock locked}@anchor{306b}
@deffn {Méthode} locked ()

Return @code{True} if the lock is acquired.
@end deffn
@end deffn

@node RLock Objects,Condition Objects,Verrous,threading --- Thread-based parallelism
@anchor{library/threading id3}@anchor{306c}@anchor{library/threading rlock-objects}@anchor{306d}
@subsubsection RLock Objects


A reentrant lock is a synchronization primitive that may be acquired multiple
times by the same thread.  Internally, it uses the concepts of "owning thread"
and "recursion level" in addition to the locked/unlocked state used by primitive
locks.  In the locked state, some thread owns the lock; in the unlocked state,
no thread owns it.

Threads call a lock's @ref{e66,,acquire()} method to lock it,
and its @ref{12a0,,release()} method to unlock it.

@cartouche
@quotation Note 
Reentrant locks support the @ref{306a,,context management protocol},
so it is recommended to use @ref{5bc,,with} instead of manually calling
@ref{e66,,acquire()} and @ref{306e,,release()}
to handle acquiring and releasing the lock for a block of code.
@end quotation
@end cartouche

RLock's @ref{e66,,acquire()}/@ref{306e,,release()} call pairs may be nested,
unlike Lock's @ref{683,,acquire()}/@ref{12a0,,release()}. Only the final
@ref{306e,,release()} (the @ref{12a0,,release()} of the outermost pair) resets
the lock to an unlocked state and allows another thread blocked in
@ref{e66,,acquire()} to proceed.

@ref{e66,,acquire()}/@ref{306e,,release()} must be used in pairs: each acquire
must have a release in the thread that has acquired the lock. Failing to
call release as many times the lock has been acquired can lead to deadlock.

@geindex RLock (classe dans threading)
@anchor{library/threading threading RLock}@anchor{2dc}
@deffn {Classe} threading.RLock

This class implements reentrant lock objects.  A reentrant lock must be
released by the thread that acquired it.  Once a thread has acquired a
reentrant lock, the same thread may acquire it again without blocking; the
thread must release it once for each time it has acquired it.

Note that @code{RLock} is actually a factory function which returns an instance
of the most efficient version of the concrete RLock class that is supported
by the platform.

@geindex acquire() (méthode threading.RLock)
@anchor{library/threading threading RLock acquire}@anchor{e66}
@deffn {Méthode} acquire (blocking=True, timeout=-1)

Acquiert un verrou, bloquant ou non bloquant.


@subsubheading Voir aussi



@table @asis

@item @ref{306a,,Using RLock as a context manager}

Recommended over manual @code{acquire()} and @ref{306e,,release()} calls
whenever practical.
@end table


When invoked with the `blocking' argument set to @code{True} (the default):

@quotation


@itemize *

@item 
If no thread owns the lock, acquire the lock and return immediately.

@item 
If another thread owns the lock, block until we are able to acquire
lock, or `timeout', if set to a positive float value.

@item 
If the same thread owns the lock, acquire the lock again, and
return immediately. This is the difference between @ref{1600,,Lock} and
@code{RLock}; @ref{1600,,Lock} handles this case the same as the previous,
blocking until the lock can be acquired.
@end itemize
@end quotation

When invoked with the `blocking' argument set to @code{False}:

@quotation


@itemize *

@item 
If no thread owns the lock, acquire the lock and return immediately.

@item 
If another thread owns the lock, return immediately.

@item 
If the same thread owns the lock, acquire the lock again and return
immediately.
@end itemize
@end quotation

In all cases, if the thread was able to acquire the lock, return @code{True}.
If the thread was unable to acquire the lock (i.e. if not blocking or
the timeout was reached) return @code{False}.

If called multiple times, failing to call @ref{306e,,release()} as many times
may lead to deadlock. Consider using @code{RLock} as a context manager rather than
calling acquire/release directly.


Modifié dans la version 3.2: Le paramètre `timeout' est nouveau.

@end deffn

@geindex release() (méthode threading.RLock)
@anchor{library/threading threading RLock release}@anchor{306e}
@deffn {Méthode} release ()

Release a lock, decrementing the recursion level.  If after the decrement it is
zero, reset the lock to unlocked (not owned by any thread), and if any other
threads are blocked waiting for the lock to become unlocked, allow exactly one
of them to proceed.  If after the decrement the recursion level is still
nonzero, the lock remains locked and owned by the calling thread.

Only call this method when the calling thread owns the lock. A
@ref{193,,RuntimeError} is raised if this method is called when the lock is
not acquired.

Il n'y a pas de valeur de retour.
@end deffn
@end deffn

@node Condition Objects,Semaphore Objects,RLock Objects,threading --- Thread-based parallelism
@anchor{library/threading condition-objects}@anchor{306f}@anchor{library/threading id4}@anchor{3070}
@subsubsection Condition Objects


A condition variable is always associated with some kind of lock; this can be
passed in or one will be created by default.  Passing one in is useful when
several condition variables must share the same lock.  The lock is part of
the condition object: you don't have to track it separately.

A condition variable obeys the @ref{306a,,context management protocol}:
using the @code{with} statement acquires the associated lock for the duration of
the enclosed block.  The @ref{3071,,acquire()} and
@ref{3072,,release()} methods also call the corresponding methods of
the associated lock.

Other methods must be called with the associated lock held.  The
@ref{183f,,wait()} method releases the lock, and then blocks until
another thread awakens it by calling @ref{176a,,notify()} or
@ref{2f8,,notify_all()}.  Once awakened, @ref{183f,,wait()}
re-acquires the lock and returns.  It is also possible to specify a timeout.

The @ref{176a,,notify()} method wakes up one of the threads waiting for
the condition variable, if any are waiting.  The @ref{2f8,,notify_all()}
method wakes up all threads waiting for the condition variable.

Note: the @ref{176a,,notify()} and @ref{2f8,,notify_all()} methods
don't release the lock; this means that the thread or threads awakened will
not return from their @ref{183f,,wait()} call immediately, but only when
the thread that called @ref{176a,,notify()} or @ref{2f8,,notify_all()}
finally relinquishes ownership of the lock.

The typical programming style using condition variables uses the lock to
synchronize access to some shared state; threads that are interested in a
particular change of state call @ref{183f,,wait()} repeatedly until they
see the desired state, while threads that modify the state call
@ref{176a,,notify()} or @ref{2f8,,notify_all()} when they change
the state in such a way that it could possibly be a desired state for one
of the waiters.  For example, the following code is a generic
producer-consumer situation with unlimited buffer capacity:

@example
# Consume one item
with cv:
    while not an_item_is_available():
        cv.wait()
    get_an_available_item()

# Produce one item
with cv:
    make_an_item_available()
    cv.notify()
@end example

The @code{while} loop checking for the application's condition is necessary
because @ref{183f,,wait()} can return after an arbitrary long time,
and the condition which prompted the @ref{176a,,notify()} call may
no longer hold true.  This is inherent to multi-threaded programming.  The
@ref{3073,,wait_for()} method can be used to automate the condition
checking, and eases the computation of timeouts:

@example
# Consume an item
with cv:
    cv.wait_for(an_item_is_available)
    get_an_available_item()
@end example

To choose between @ref{176a,,notify()} and @ref{2f8,,notify_all()},
consider whether one state change can be interesting for only one or several
waiting threads.  E.g. in a typical producer-consumer situation, adding one
item to the buffer only needs to wake up one consumer thread.

@geindex Condition (classe dans threading)
@anchor{library/threading threading Condition}@anchor{1135}
@deffn {Classe} threading.Condition (lock=None)

This class implements condition variable objects.  A condition variable
allows one or more threads to wait until they are notified by another thread.

If the `lock' argument is given and not @code{None}, it must be a @ref{1600,,Lock}
or @ref{2dc,,RLock} object, and it is used as the underlying lock.  Otherwise,
a new @ref{2dc,,RLock} object is created and used as the underlying lock.


Modifié dans la version 3.3: changed from a factory function to a class.


@geindex acquire() (méthode threading.Condition)
@anchor{library/threading threading Condition acquire}@anchor{3071}
@deffn {Méthode} acquire (*args)

Acquire the underlying lock. This method calls the corresponding method on
the underlying lock; the return value is whatever that method returns.
@end deffn

@geindex release() (méthode threading.Condition)
@anchor{library/threading threading Condition release}@anchor{3072}
@deffn {Méthode} release ()

Release the underlying lock. This method calls the corresponding method on
the underlying lock; there is no return value.
@end deffn

@geindex wait() (méthode threading.Condition)
@anchor{library/threading threading Condition wait}@anchor{183f}
@deffn {Méthode} wait (timeout=None)

Wait until notified or until a timeout occurs. If the calling thread has
not acquired the lock when this method is called, a @ref{193,,RuntimeError} is
raised.

This method releases the underlying lock, and then blocks until it is
awakened by a @ref{176a,,notify()} or @ref{2f8,,notify_all()} call for the same
condition variable in another thread, or until the optional timeout
occurs.  Once awakened or timed out, it re-acquires the lock and returns.

When the `timeout' argument is present and not @code{None}, it should be a
floating-point number specifying a timeout for the operation in seconds
(or fractions thereof).

When the underlying lock is an @ref{2dc,,RLock}, it is not released using
its @ref{3072,,release()} method, since this may not actually unlock the lock
when it was acquired multiple times recursively.  Instead, an internal
interface of the @ref{2dc,,RLock} class is used, which really unlocks it
even when it has been recursively acquired several times. Another internal
interface is then used to restore the recursion level when the lock is
reacquired.

The return value is @code{True} unless a given `timeout' expired, in which
case it is @code{False}.


Modifié dans la version 3.2: Previously, the method always returned @code{None}.

@end deffn

@geindex wait_for() (méthode threading.Condition)
@anchor{library/threading threading Condition wait_for}@anchor{3073}
@deffn {Méthode} wait_for (predicate, timeout=None)

Wait until a condition evaluates to true.  `predicate' should be a
callable which result will be interpreted as a boolean value.
A `timeout' may be provided giving the maximum time to wait.

This utility method may call @ref{183f,,wait()} repeatedly until the predicate
is satisfied, or until a timeout occurs. The return value is
the last return value of the predicate and will evaluate to
@code{False} if the method timed out.

Ignoring the timeout feature, calling this method is roughly equivalent to
writing:

@example
while not predicate():
    cv.wait()
@end example

Therefore, the same rules apply as with @ref{183f,,wait()}: The lock must be
held when called and is re-acquired on return.  The predicate is evaluated
with the lock held.


Ajouté dans la version 3.2.

@end deffn

@geindex notify() (méthode threading.Condition)
@anchor{library/threading threading Condition notify}@anchor{176a}
@deffn {Méthode} notify (n=1)

By default, wake up one thread waiting on this condition, if any.  If the
calling thread has not acquired the lock when this method is called, a
@ref{193,,RuntimeError} is raised.

This method wakes up at most `n' of the threads waiting for the condition
variable; it is a no-op if no threads are waiting.

The current implementation wakes up exactly `n' threads, if at least `n'
threads are waiting.  However, it's not safe to rely on this behavior.
A future, optimized implementation may occasionally wake up more than
`n' threads.

Note: an awakened thread does not actually return from its @ref{183f,,wait()}
call until it can reacquire the lock.  Since @ref{176a,,notify()} does not
release the lock, its caller should.
@end deffn

@geindex notify_all() (méthode threading.Condition)
@anchor{library/threading threading Condition notify_all}@anchor{2f8}
@deffn {Méthode} notify_all ()

Wake up all threads waiting on this condition.  This method acts like
@ref{176a,,notify()}, but wakes up all waiting threads instead of one. If the
calling thread has not acquired the lock when this method is called, a
@ref{193,,RuntimeError} is raised.

The method @code{notifyAll} is a deprecated alias for this method.
@end deffn
@end deffn

@node Semaphore Objects,Event Objects,Condition Objects,threading --- Thread-based parallelism
@anchor{library/threading id5}@anchor{3074}@anchor{library/threading semaphore-objects}@anchor{3075}
@subsubsection Semaphore Objects


This is one of the oldest synchronization primitives in the history of computer
science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
used the names @code{P()} and @code{V()} instead of @ref{1232,,acquire()} and
@ref{3076,,release()}).

A semaphore manages an internal counter which is decremented by each
@ref{1232,,acquire()} call and incremented by each @ref{3076,,release()}
call.  The counter can never go below zero; when @ref{1232,,acquire()}
finds that it is zero, it blocks, waiting until some other thread calls
@ref{3076,,release()}.

Semaphores also support the @ref{306a,,context management protocol}.

@geindex Semaphore (classe dans threading)
@anchor{library/threading threading Semaphore}@anchor{1136}
@deffn {Classe} threading.Semaphore (value=1)

This class implements semaphore objects.  A semaphore manages an atomic
counter representing the number of @ref{3076,,release()} calls minus the number of
@ref{1232,,acquire()} calls, plus an initial value.  The @ref{1232,,acquire()} method
blocks if necessary until it can return without making the counter negative.
If not given, `value' defaults to 1.

The optional argument gives the initial `value' for the internal counter; it
defaults to @code{1}. If the `value' given is less than 0, @ref{1ff,,ValueError} is
raised.


Modifié dans la version 3.3: changed from a factory function to a class.


@geindex acquire() (méthode threading.Semaphore)
@anchor{library/threading threading Semaphore acquire}@anchor{1232}
@deffn {Méthode} acquire (blocking=True, timeout=None)

Acquiert un sémaphore.

When invoked without arguments:


@itemize *

@item 
If the internal counter is larger than zero on entry, decrement it by
one and return @code{True} immediately.

@item 
If the internal counter is zero on entry, block until awoken by a call to
@ref{3076,,release()}.  Once awoken (and the counter is greater
than 0), decrement the counter by 1 and return @code{True}.  Exactly one
thread will be awoken by each call to @ref{3076,,release()}.  The
order in which threads are awoken should not be relied on.
@end itemize

When invoked with `blocking' set to @code{False}, do not block.  If a call
without an argument would block, return @code{False} immediately; otherwise, do
the same thing as when called without arguments, and return @code{True}.

When invoked with a `timeout' other than @code{None}, it will block for at
most `timeout' seconds.  If acquire does not complete successfully in
that interval, return @code{False}.  Return @code{True} otherwise.


Modifié dans la version 3.2: Le paramètre `timeout' est nouveau.

@end deffn

@geindex release() (méthode threading.Semaphore)
@anchor{library/threading threading Semaphore release}@anchor{3076}
@deffn {Méthode} release (n=1)

Release a semaphore, incrementing the internal counter by `n'.  When it
was zero on entry and other threads are waiting for it to become larger
than zero again, wake up `n' of those threads.


Modifié dans la version 3.9: Added the `n' parameter to release multiple waiting threads at once.

@end deffn
@end deffn

@geindex BoundedSemaphore (classe dans threading)
@anchor{library/threading threading BoundedSemaphore}@anchor{1137}
@deffn {Classe} threading.BoundedSemaphore (value=1)

Class implementing bounded semaphore objects.  A bounded semaphore checks to
make sure its current value doesn't exceed its initial value.  If it does,
@ref{1ff,,ValueError} is raised. In most situations semaphores are used to guard
resources with limited capacity.  If the semaphore is released too many times
it's a sign of a bug.  If not given, `value' defaults to 1.


Modifié dans la version 3.3: changed from a factory function to a class.

@end deffn

@menu
* Semaphore Example:: 

@end menu

@node Semaphore Example,,,Semaphore Objects
@anchor{library/threading semaphore-example}@anchor{3077}@anchor{library/threading semaphore-examples}@anchor{3078}
@subsubsection @code{Semaphore} Example


Semaphores are often used to guard resources with limited capacity, for example,
a database server.  In any situation where the size of the resource is fixed,
you should use a bounded semaphore.  Before spawning any worker threads, your
main thread would initialize the semaphore:

@example
maxconnections = 5
# ...
pool_sema = BoundedSemaphore(value=maxconnections)
@end example

Once spawned, worker threads call the semaphore's acquire and release methods
when they need to connect to the server:

@example
with pool_sema:
    conn = connectdb()
    try:
        # ... use connection ...
    finally:
        conn.close()
@end example

The use of a bounded semaphore reduces the chance that a programming error which
causes the semaphore to be released more than it's acquired will go undetected.

@node Event Objects,Timer Objects,Semaphore Objects,threading --- Thread-based parallelism
@anchor{library/threading event-objects}@anchor{3079}@anchor{library/threading id6}@anchor{307a}
@subsubsection Event Objects


This is one of the simplest mechanisms for communication between threads: one
thread signals an event and other threads wait for it.

An event object manages an internal flag that can be set to true with the
@ref{307b,,set()} method and reset to false with the @ref{307c,,clear()}
method.  The @ref{1304,,wait()} method blocks until the flag is true.

@geindex Event (classe dans threading)
@anchor{library/threading threading Event}@anchor{1138}
@deffn {Classe} threading.Event

Class implementing event objects.  An event manages a flag that can be set to
true with the @ref{307b,,set()} method and reset to false with the
@ref{307c,,clear()} method.  The @ref{1304,,wait()} method blocks until the flag is true.
The flag is initially false.


Modifié dans la version 3.3: changed from a factory function to a class.


@geindex is_set() (méthode threading.Event)
@anchor{library/threading threading Event is_set}@anchor{2f9}
@deffn {Méthode} is_set ()

Return @code{True} if and only if the internal flag is true.

The method @code{isSet} is a deprecated alias for this method.
@end deffn

@geindex set() (méthode threading.Event)
@anchor{library/threading threading Event set}@anchor{307b}
@deffn {Méthode} set ()

Set the internal flag to true. All threads waiting for it to become true
are awakened. Threads that call @ref{1304,,wait()} once the flag is true will
not block at all.
@end deffn

@geindex clear() (méthode threading.Event)
@anchor{library/threading threading Event clear}@anchor{307c}
@deffn {Méthode} clear ()

Reset the internal flag to false. Subsequently, threads calling
@ref{1304,,wait()} will block until @ref{307b,,set()} is called to set the internal
flag to true again.
@end deffn

@geindex wait() (méthode threading.Event)
@anchor{library/threading threading Event wait}@anchor{1304}
@deffn {Méthode} wait (timeout=None)

Block as long as the internal flag is false and the timeout, if given,
has not expired. The return value represents the
reason that this blocking method returned; @code{True} if returning because
the internal flag is set to true, or @code{False} if a timeout is given and
the internal flag did not become true within the given wait time.

When the timeout argument is present and not @code{None}, it should be a
floating-point number specifying a timeout for the operation in seconds,
or fractions thereof.


Modifié dans la version 3.1: Previously, the method always returned @code{None}.

@end deffn
@end deffn

@node Timer Objects,Barrier Objects,Event Objects,threading --- Thread-based parallelism
@anchor{library/threading id7}@anchor{307d}@anchor{library/threading timer-objects}@anchor{307e}
@subsubsection Timer Objects


This class represents an action that should be run only after a certain amount
of time has passed --- a timer.  @ref{1139,,Timer} is a subclass of @ref{939,,Thread}
and as such also functions as an example of creating custom threads.

Timers are started, as with threads, by calling their @ref{2c3a,,Timer.start}
method.  The timer can be stopped (before its action has begun) by calling the
@ref{307f,,cancel()} method.  The interval the timer will wait before
executing its action may not be exactly the same as the interval specified by
the user.

Par exemple :

@example
def hello():
    print("hello, world")

t = Timer(30.0, hello)
t.start()  # after 30 seconds, "hello, world" will be printed
@end example

@geindex Timer (classe dans threading)
@anchor{library/threading threading Timer}@anchor{1139}
@deffn {Classe} threading.Timer (interval, function, args=None, kwargs=None)

Create a timer that will run `function' with arguments `args' and  keyword
arguments `kwargs', after `interval' seconds have passed.
If `args' is @code{None} (the default) then an empty list will be used.
If `kwargs' is @code{None} (the default) then an empty dict will be used.


Modifié dans la version 3.3: changed from a factory function to a class.


@geindex cancel() (méthode threading.Timer)
@anchor{library/threading threading Timer cancel}@anchor{307f}
@deffn {Méthode} cancel ()

Stop the timer, and cancel the execution of the timer's action.  This will
only work if the timer is still in its waiting stage.
@end deffn
@end deffn

@node Barrier Objects,Using locks conditions and semaphores in the with statement,Timer Objects,threading --- Thread-based parallelism
@anchor{library/threading barrier-objects}@anchor{3080}
@subsubsection Barrier Objects



Ajouté dans la version 3.2.


This class provides a simple synchronization primitive for use by a fixed number
of threads that need to wait for each other.  Each of the threads tries to pass
the barrier by calling the @ref{3081,,wait()} method and will block until
all of the threads have made their @ref{3081,,wait()} calls. At this point,
the threads are released simultaneously.

The barrier can be reused any number of times for the same number of threads.

As an example, here is a simple way to synchronize a client and server thread:

@example
b = Barrier(2, timeout=5)

def server():
    start_server()
    b.wait()
    while True:
        connection = accept_connection()
        process_server_connection(connection)

def client():
    b.wait()
    while True:
        connection = make_connection()
        process_client_connection(connection)
@end example

@geindex Barrier (classe dans threading)
@anchor{library/threading threading Barrier}@anchor{11c0}
@deffn {Classe} threading.Barrier (parties, action=None, timeout=None)

Create a barrier object for `parties' number of threads.  An `action', when
provided, is a callable to be called by one of the threads when they are
released.  `timeout' is the default timeout value if none is specified for
the @ref{3081,,wait()} method.

@geindex wait() (méthode threading.Barrier)
@anchor{library/threading threading Barrier wait}@anchor{3081}
@deffn {Méthode} wait (timeout=None)

Pass the barrier.  When all the threads party to the barrier have called
this function, they are all released simultaneously.  If a `timeout' is
provided, it is used in preference to any that was supplied to the class
constructor.

The return value is an integer in the range 0 to `parties' -- 1, different
for each thread.  This can be used to select a thread to do some special
housekeeping, e.g.:

@example
i = barrier.wait()
if i == 0:
    # Only one thread needs to print this
    print("passed the barrier")
@end example

If an `action' was provided to the constructor, one of the threads will
have called it prior to being released.  Should this call raise an error,
the barrier is put into the broken state.

If the call times out, the barrier is put into the broken state.

This method may raise a @ref{11c2,,BrokenBarrierError} exception if the
barrier is broken or reset while a thread is waiting.
@end deffn

@geindex reset() (méthode threading.Barrier)
@anchor{library/threading threading Barrier reset}@anchor{3082}
@deffn {Méthode} reset ()

Return the barrier to the default, empty state.  Any threads waiting on it
will receive the @ref{11c2,,BrokenBarrierError} exception.

Note that using this function may require some external
synchronization if there are other threads whose state is unknown.  If a
barrier is broken it may be better to just leave it and create a new one.
@end deffn

@geindex abort() (méthode threading.Barrier)
@anchor{library/threading threading Barrier abort}@anchor{3083}
@deffn {Méthode} abort ()

Put the barrier into a broken state.  This causes any active or future
calls to @ref{3081,,wait()} to fail with the @ref{11c2,,BrokenBarrierError}.  Use
this for example if one of the threads needs to abort, to avoid deadlocking the
application.

It may be preferable to simply create the barrier with a sensible
`timeout' value to automatically guard against one of the threads going
awry.
@end deffn

@geindex parties (attribut threading.Barrier)
@anchor{library/threading threading Barrier parties}@anchor{3084}
@deffn {Attribut} parties

The number of threads required to pass the barrier.
@end deffn

@geindex n_waiting (attribut threading.Barrier)
@anchor{library/threading threading Barrier n_waiting}@anchor{3085}
@deffn {Attribut} n_waiting

The number of threads currently waiting in the barrier.
@end deffn

@geindex broken (attribut threading.Barrier)
@anchor{library/threading threading Barrier broken}@anchor{3086}
@deffn {Attribut} broken

Booléen qui vaut @code{True} si la barrière est rompue.
@end deffn
@end deffn

@geindex BrokenBarrierError
@anchor{library/threading threading BrokenBarrierError}@anchor{11c2}
@deffn {Exception} threading.BrokenBarrierError

Cette exception, une sous-classe de @ref{193,,RuntimeError}, est déclenchée lorsque l'objet @ref{11c0,,Barrier} est réinitialisé ou cassé.
@end deffn

@node Using locks conditions and semaphores in the with statement,,Barrier Objects,threading --- Thread-based parallelism
@anchor{library/threading using-locks-conditions-and-semaphores-in-the-with-statement}@anchor{3087}@anchor{library/threading with-locks}@anchor{306a}
@subsubsection Using locks, conditions, and semaphores in the @code{with} statement


All of the objects provided by this module that have @code{acquire} and
@code{release} methods can be used as context managers for a @ref{5bc,,with}
statement.  The @code{acquire} method will be called when the block is
entered, and @code{release} will be called when the block is exited.  Hence,
the following snippet:

@example
with some_lock:
    # do something...
@end example

est équivalente à :

@example
some_lock.acquire()
try:
    # do something...
finally:
    some_lock.release()
@end example

Currently, @ref{1600,,Lock}, @ref{2dc,,RLock}, @ref{1135,,Condition},
@ref{1136,,Semaphore}, and @ref{1137,,BoundedSemaphore} objects may be used as
@ref{5bc,,with} statement context managers.

@node multiprocessing --- Process-based parallelism,multiprocessing shared_memory --- Shared memory for direct access across processes,threading --- Thread-based parallelism,Exécution concourante
@anchor{library/multiprocessing doc}@anchor{3088}@anchor{library/multiprocessing module-multiprocessing}@anchor{93}@anchor{library/multiprocessing multiprocessing-process-based-parallelism}@anchor{3089}
@subsection @code{multiprocessing} --- Process-based parallelism


@geindex module; multiprocessing

`Code source  :' Lib/multiprocessing/@footnote{https://github.com/python/cpython/tree/3.13/Lib/multiprocessing/}


__________________________________________________________________


@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@menu
* Introduction: Introduction<8>. 
* Référence:: 
* Lignes directrices de programmation:: 
* Exemples: Exemples<14>. 

@end menu

@node Introduction<8>,Référence,,multiprocessing --- Process-based parallelism
@anchor{library/multiprocessing introduction}@anchor{308a}
@subsubsection Introduction


@ref{93,,multiprocessing} is a package that supports spawning processes using an
API similar to the @ref{ec,,threading} module.  The @ref{93,,multiprocessing} package
offers both local and remote concurrency, effectively side-stepping the
@ref{147,,Global Interpreter Lock} by using
subprocesses instead of threads.  Due
to this, the @ref{93,,multiprocessing} module allows the programmer to fully
leverage multiple processors on a given machine.  It runs on both POSIX and
Windows.

Le module @ref{93,,multiprocessing} introduit aussi des API sans analogues dans le module @ref{ec,,threading}. Un exemple est l'objet @ref{f56,,Pool} qui offre un moyen simple de paralléliser l'exécution d'une fonction sur plusieurs valeurs d'entrée, en distribuant ces valeurs entre les processus (parallélisme de données). L'exemple suivant présente la manière classique de définir une telle fonction dans un module afin que les processus fils puissent importer ce module avec succès. Cet exemple basique de parallélisme de données, utilisant @ref{f56,,Pool},

@example
from multiprocessing import Pool

def f(x):
    return x*x

if __name__ == '__main__':
    with Pool(5) as p:
        print(p.map(f, [1, 2, 3]))
@end example

affiche sur la sortie standard

@example
[1, 4, 9]
@end example


@subsubheading Voir aussi


@ref{8db,,concurrent.futures.ProcessPoolExecutor} offers a higher level interface
to push tasks to a background process without blocking execution of the
calling process. Compared to using the @ref{f56,,Pool}
interface directly, the @ref{21,,concurrent.futures} API more readily allows
the submission of work to the underlying process pool to be separated from
waiting for the results.


@menu
* La classe Process:: 
* Contextes et méthodes de démarrage:: 
* Échange d'objets entre les processus:: 
* Synchronisation entre processus:: 
* Partager un état entre les processus:: 
* Utiliser un pool de workers:: 

@end menu

@node La classe Process,Contextes et méthodes de démarrage,,Introduction<8>
@anchor{library/multiprocessing the-process-class}@anchor{308b}
@subsubsection La classe @code{Process}


Dans le module @ref{93,,multiprocessing}, les processus sont instanciés en créant un objet @ref{b47,,Process} et en appelant sa méthode @ref{308c,,start()}. La classe @ref{b47,,Process} suit la même API que @ref{939,,threading.Thread}. Un exemple trivial d'un programme multi-processus est

@example
from multiprocessing import Process

def f(name):
    print('hello', name)

if __name__ == '__main__':
    p = Process(target=f, args=('bob',))
    p.start()
    p.join()
@end example

Voici un exemple plus étoffé qui affiche les identifiants des processus créés :

@example
from multiprocessing import Process
import os

def info(title):
    print(title)
    print('module name:', __name__)
    print('parent process:', os.getppid())
    print('process id:', os.getpid())

def f(name):
    info('function f')
    print('hello', name)

if __name__ == '__main__':
    info('main line')
    p = Process(target=f, args=('bob',))
    p.start()
    p.join()
@end example

La nécessité de la ligne @code{if __name__ == '__main__'} est expliquée dans la section @ref{308d,,Lignes directrices de programmation}.

@node Contextes et méthodes de démarrage,Échange d'objets entre les processus,La classe Process,Introduction<8>
@anchor{library/multiprocessing contexts-and-start-methods}@anchor{308e}@anchor{library/multiprocessing multiprocessing-start-methods}@anchor{2c6}
@subsubsection Contextes et méthodes de démarrage


Selon la plateforme, @ref{93,,multiprocessing} gère trois manières de démarrer un processus. Ces `méthodes de démarrage' sont

@quotation


@table @asis

@item `spawn'

The parent process starts a fresh Python interpreter process.  The
child process will only inherit those resources necessary to run
the process object's @ref{308f,,run()} method.  In particular,
unnecessary file descriptors and handles from the parent process
will not be inherited.  Starting a process using this method is
rather slow compared to using `fork' or `forkserver'.

Available on POSIX and Windows platforms.  The default on Windows and macOS.

@item `fork'

Le processus parent utilise @ref{195,,os.fork()} pour `forker' l'interpréteur Python. Le processus fils, quand il démarre, est effectivement identique au processus parent. Toutes les ressources du parent sont héritées par le fils. Notez qu'il est problématique de `forker' sans danger un processus `multi-threadé'.

Available on POSIX systems.  Currently the default on POSIX except macOS.

@cartouche
@quotation Note 
The default start method will change away from `fork' in Python 3.14.
Code that requires `fork' should explicitly specify that via
@ref{2c4,,get_context()} or @ref{2c5,,set_start_method()}.
@end quotation
@end cartouche


Modifié dans la version 3.12: If Python is able to detect that your process has multiple threads, the
@ref{195,,os.fork()} function that this start method calls internally will
raise a @ref{1a3,,DeprecationWarning}. Use a different start method.
See the @ref{195,,os.fork()} documentation for further explanation.


@item `forkserver'

When the program starts and selects the `forkserver' start method,
a server process is spawned.  From then on, whenever a new process
is needed, the parent process connects to the server and requests
that it fork a new process.  The fork server process is single threaded
unless system libraries or preloaded imports spawn threads as a
side-effect so it is generally safe for it to use @ref{195,,os.fork()}.
No unnecessary resources are inherited.

Available on POSIX platforms which support passing file descriptors
over Unix pipes such as Linux.
@end table
@end quotation


Modifié dans la version 3.4: `spawn' added on all POSIX platforms, and `forkserver' added for
some POSIX platforms.
Child processes no longer inherit all of the parents inheritable
handles on Windows.



Modifié dans la version 3.8: On macOS, the `spawn' start method is now the default.  The `fork' start
method should be considered unsafe as it can lead to crashes of the
subprocess as macOS system libraries may start threads. See bpo-33725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33725}.


On POSIX using the `spawn' or `forkserver' start methods will also
start a `resource tracker' process which tracks the unlinked named
system resources (such as named semaphores or
@ref{15e2,,SharedMemory} objects) created
by processes of the program.  When all processes
have exited the resource tracker unlinks any remaining tracked object.
Usually there should be none, but if a process was killed by a signal
there may be some "leaked" resources.  (Neither leaked semaphores nor shared
memory segments will be automatically unlinked until the next reboot. This is
problematic for both objects because the system allows only a limited number of
named semaphores, and shared memory segments occupy some space in the main
memory.)

Pour sélectionner une méthode de démarrage, utilisez la fonction @ref{2c5,,set_start_method()} dans la clause @code{if __name__ == '__main__'} du module principal. Par exemple :

@example
import multiprocessing as mp

def foo(q):
    q.put('hello')

if __name__ == '__main__':
    mp.set_start_method('spawn')
    q = mp.Queue()
    p = mp.Process(target=foo, args=(q,))
    p.start()
    print(q.get())
    p.join()
@end example

@ref{2c5,,set_start_method()} ne doit pas être utilisée plus d'une fois dans le programme.

Alternativement, vous pouvez utiliser @ref{2c4,,get_context()} pour obtenir un contexte. Les contextes ont la même API que le module `multiprocessing', et permettent l'utilisation de plusieurs méthodes de démarrage dans un même programme.

@example
import multiprocessing as mp

def foo(q):
    q.put('hello')

if __name__ == '__main__':
    ctx = mp.get_context('spawn')
    q = ctx.Queue()
    p = ctx.Process(target=foo, args=(q,))
    p.start()
    print(q.get())
    p.join()
@end example

Notez que les objets relatifs à un contexte ne sont pas forcément compatibles avec les processus d'un contexte différent. En particulier, les verrous créés avec le contexte `fork' ne peuvent pas être passés aux processus lancés avec les méthodes `spawn' ou `forkserver'.

Une bibliothèque qui veut utiliser une méthode de démarrage particulière devrait probablement faire appel à @ref{2c4,,get_context()} pour éviter d'interférer avec le choix de l'utilisateur de la bibliothèque.

@cartouche
@quotation Avertissement 
The @code{'spawn'} and @code{'forkserver'} start methods generally cannot
be used with "frozen" executables (i.e., binaries produced by
packages like `PyInstaller' and `cx_Freeze') on POSIX systems.
The @code{'fork'} start method may work if code does not use threads.
@end quotation
@end cartouche

@node Échange d'objets entre les processus,Synchronisation entre processus,Contextes et méthodes de démarrage,Introduction<8>
@anchor{library/multiprocessing exchanging-objects-between-processes}@anchor{3090}
@subsubsection Échange d'objets entre les processus


@ref{93,,multiprocessing} gère deux types de canaux de communication entre les processus :

`Files' (`queues')

@quotation

La classe @ref{178a,,Queue} est un clone assez proche de @ref{1365,,queue.Queue}. Par exemple :

@example
from multiprocessing import Process, Queue

def f(q):
    q.put([42, None, 'hello'])

if __name__ == '__main__':
    q = Queue()
    p = Process(target=f, args=(q,))
    p.start()
    print(q.get())    # prints "[42, None, 'hello']"
    p.join()
@end example

Queues are thread and process safe.
Any object put into a @ref{93,,multiprocessing} queue will be serialized.
@end quotation

`Tubes' (`pipes')

@quotation

La fonction @ref{3091,,Pipe()} renvoie une paire d'objets de connexion connectés à un tube qui est par défaut duplex (à double sens). Par exemple :

@example
from multiprocessing import Process, Pipe

def f(conn):
    conn.send([42, None, 'hello'])
    conn.close()

if __name__ == '__main__':
    parent_conn, child_conn = Pipe()
    p = Process(target=f, args=(child_conn,))
    p.start()
    print(parent_conn.recv())   # prints "[42, None, 'hello']"
    p.join()
@end example

Les deux objets de connexion renvoyés par @ref{3091,,Pipe()} représentent les deux extrémités d'un tube. Chaque objet de connexion possède (entre autres) des méthodes @code{send()} et @code{recv()}. Notez que les données d'un tube peuvent être corrompues si deux processus (ou fils d'exécution) essaient de lire ou d'écrire sur la même extrémité du tube en même temps. Bien évidemment, deux processus peuvent utiliser les deux extrémités différentes en même temps sans risque de corruption.

The @code{send()} method serializes the object and
@code{recv()} re-creates the object.
@end quotation

@node Synchronisation entre processus,Partager un état entre les processus,Échange d'objets entre les processus,Introduction<8>
@anchor{library/multiprocessing synchronization-between-processes}@anchor{3092}
@subsubsection Synchronisation entre processus


@ref{93,,multiprocessing} contient des équivalents à toutes les primitives de synchronisation de @ref{ec,,threading}. Par exemple il est possible d'utiliser un verrou pour s'assurer qu'un seul processus à la fois écrit sur la sortie standard :

@example
from multiprocessing import Process, Lock

def f(l, i):
    l.acquire()
    try:
        print('hello world', i)
    finally:
        l.release()

if __name__ == '__main__':
    lock = Lock()

    for num in range(10):
        Process(target=f, args=(lock, num)).start()
@end example

Sans le verrou, les sorties des différents processus risquent d'être mélangées.

@node Partager un état entre les processus,Utiliser un pool de workers,Synchronisation entre processus,Introduction<8>
@anchor{library/multiprocessing sharing-state-between-processes}@anchor{3093}
@subsubsection Partager un état entre les processus


Comme mentionné plus haut, il est généralement préférable d'éviter autant que possible d'utiliser des états partagés en programmation concurrente. C'est particulièrement vrai quand plusieurs processus sont utilisés.

Cependant, si vous devez réellement partager des données, @ref{93,,multiprocessing} permet de le faire de deux manières.

`Mémoire partagée'

@quotation

Les données peuvent être stockées dans une mémoire partagée en utilisant des @ref{3094,,Value} ou des @ref{3095,,Array}. Par exemple, le code suivant

@example
from multiprocessing import Process, Value, Array

def f(n, a):
    n.value = 3.1415927
    for i in range(len(a)):
        a[i] = -a[i]

if __name__ == '__main__':
    num = Value('d', 0.0)
    arr = Array('i', range(10))

    p = Process(target=f, args=(num, arr))
    p.start()
    p.join()

    print(num.value)
    print(arr[:])
@end example

affiche

@example
3.1415927
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
@end example

Les arguments @code{'d'} et @code{'i'} utilisés à la création des @code{num} et @code{arr} sont des codes de types identiques à ceux du module @ref{7,,array} : @code{'d'} indique un flottant double-précision et @code{'i'} indique un entier signé. Ces objets peuvent être partagés sans problème entre processus ou fils d’exécution.

Pour plus de flexibilité dans l'utilisation de mémoire partagée, vous pouvez utiliser le module @ref{99,,multiprocessing.sharedctypes} qui permet la création d'objets arbitraires `ctypes' alloués depuis la mémoire partagée.
@end quotation

`Processus serveur'

@quotation

Un objet gestionnaire renvoyé par @ref{ca8,,Manager()} contrôle un processus serveur qui détient les objets Python et autorise les autres processus à les manipuler à l'aide de mandataires.

Un gestionnaire renvoyé par @ref{ca8,,Manager()} prend en charge les types @ref{5fc,,list}, @ref{253,,dict}, @ref{3096,,Namespace}, @ref{1522,,Lock}, @ref{1523,,RLock}, @ref{3097,,Semaphore}, @ref{3098,,BoundedSemaphore}, @ref{3099,,Condition}, @ref{17f1,,Event}, @ref{309a,,Barrier}, @ref{178a,,Queue}, @ref{3094,,Value} et @ref{3095,,Array}. Par exemple,

@example
from multiprocessing import Process, Manager

def f(d, l):
    d[1] = '1'
    d['2'] = 2
    d[0.25] = None
    l.reverse()

if __name__ == '__main__':
    with Manager() as manager:
        d = manager.dict()
        l = manager.list(range(10))

        p = Process(target=f, args=(d, l))
        p.start()
        p.join()

        print(d)
        print(l)
@end example

affiche

@example
@{0.25: None, 1: '1', '2': 2@}
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
@end example

Les processus serveurs de gestionnaires sont plus flexibles que les mémoires partagées parce qu'ils peuvent gérer des types d'objets arbitraires. Aussi, un gestionnaire unique peut être partagé par les processus sur différentes machines à travers le réseau. Cependant, ils sont plus lents que les mémoires partagées.
@end quotation

@node Utiliser un pool de workers,,Partager un état entre les processus,Introduction<8>
@anchor{library/multiprocessing using-a-pool-of-workers}@anchor{309b}
@subsubsection Utiliser un pool de `workers'


La classe @ref{f56,,Pool} représente un pool de processus de travail. Elle possède des méthodes qui permettent aux tâches d'être déchargées vers les processus de travail de différentes manières.

Par exemple :

@example
from multiprocessing import Pool, TimeoutError
import time
import os

def f(x):
    return x*x

if __name__ == '__main__':
    # start 4 worker processes
    with Pool(processes=4) as pool:

        # print "[0, 1, 4,..., 81]"
        print(pool.map(f, range(10)))

        # print same numbers in arbitrary order
        for i in pool.imap_unordered(f, range(10)):
            print(i)

        # evaluate "f(20)" asynchronously
        res = pool.apply_async(f, (20,))      # runs in *only* one process
        print(res.get(timeout=1))             # prints "400"

        # evaluate "os.getpid()" asynchronously
        res = pool.apply_async(os.getpid, ()) # runs in *only* one process
        print(res.get(timeout=1))             # prints the PID of that process

        # launching multiple evaluations asynchronously *may* use more processes
        multiple_results = [pool.apply_async(os.getpid, ()) for i in range(4)]
        print([res.get(timeout=1) for res in multiple_results])

        # make a single worker sleep for 10 seconds
        res = pool.apply_async(time.sleep, (10,))
        try:
            print(res.get(timeout=1))
        except TimeoutError:
            print("We lacked patience and got a multiprocessing.TimeoutError")

        print("For the moment, the pool remains available for more work")

    # exiting the 'with'-block has stopped the pool
    print("Now the pool is closed and no longer available")
@end example

Notez que les méthodes d'un pool ne doivent être utilisées que par le processus qui l'a créée.

@cartouche
@quotation Note 
Functionality within this package requires that the @code{__main__} module be
importable by the children. This is covered in @ref{308d,,Lignes directrices de programmation}
however it is worth pointing out here. This means that some examples, such
as the @ref{f56,,multiprocessing.pool.Pool} examples will not work in the
interactive interpreter. For example:

@example
>>> from multiprocessing import Pool
>>> p = Pool(5)
>>> def f(x):
...     return x*x
...
>>> with p:
...     p.map(f, [1,2,3])
Process PoolWorker-1:
Process PoolWorker-2:
Process PoolWorker-3:
Traceback (most recent call last):
Traceback (most recent call last):
Traceback (most recent call last):
AttributeError: Can't get attribute 'f' on <module '__main__' (<class '_frozen_importlib.BuiltinImporter'>)>
AttributeError: Can't get attribute 'f' on <module '__main__' (<class '_frozen_importlib.BuiltinImporter'>)>
AttributeError: Can't get attribute 'f' on <module '__main__' (<class '_frozen_importlib.BuiltinImporter'>)>
@end example

Si vous essayez ce code, il affichera trois traces d'appels complètes entrelacées de manière semi-aléatoire, et vous devrez vous débrouiller pour arrêter le processus maître.
@end quotation
@end cartouche

@node Référence,Lignes directrices de programmation,Introduction<8>,multiprocessing --- Process-based parallelism
@anchor{library/multiprocessing reference}@anchor{309c}
@subsubsection Référence


Le paquet @ref{93,,multiprocessing} reproduit en grande partie l'API du module @ref{ec,,threading}.

@menu
* Process et exceptions:: 
* Tubes (pipes) et files (queues): Tubes pipes et files queues. 
* Divers: Divers<3>. 
* Objets de connexions:: 
* Primitives de synchronisation:: 
* Objets ctypes partagés:: 
* Gestionnaires: Gestionnaires<2>. 
* Objets mandataires:: 
* Pools de processus:: 
* Auditeurs et Clients:: 
* Clés d'authentification:: 
* Journalisation: Journalisation<2>. 
* Le module multiprocessing.dummy: Le module multiprocessing dummy. 

@end menu

@node Process et exceptions,Tubes pipes et files queues,,Référence
@anchor{library/multiprocessing process-and-exceptions}@anchor{309d}
@subsubsection @code{Process} et exceptions


@geindex Process (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Process}@anchor{b47}
@deffn {Classe} multiprocessing.Process (group=None, target=None, name=None, args=(), kwargs=@{@}, *, daemon=None)

Les objets `process' représentent une activité exécutée dans un processus séparé. La classe @ref{b47,,Process} a des équivalents à toutes les méthodes de @ref{939,,threading.Thread}.

The constructor should always be called with keyword arguments. `group'
should always be @code{None}; it exists solely for compatibility with
@ref{939,,threading.Thread}.  `target' is the callable object to be invoked by
the @ref{308f,,run()} method.  It defaults to @code{None}, meaning nothing is
called. `name' is the process name (see @ref{309e,,name} for more details).
`args' is the argument tuple for the target invocation.  `kwargs' is a
dictionary of keyword arguments for the target invocation.  If provided,
the keyword-only `daemon' argument sets the process @ref{309f,,daemon} flag
to @code{True} or @code{False}.  If @code{None} (the default), this flag will be
inherited from the creating process.

By default, no arguments are passed to `target'. The `args' argument,
which defaults to @code{()}, can be used to specify a list or tuple of the arguments
to pass to `target'.

Si une sous-classe redéfinit le constructeur, elle doit s'assurer d'invoquer le constructeur de la classe de base (@code{Process.__init__()}) avant de faire autre chose du processus.


Modifié dans la version 3.3: Added the `daemon' parameter.


@geindex run() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process run}@anchor{308f}
@deffn {Méthode} run ()

Méthode représentant l'activité du processus.

Vous pouvez redéfinir cette méthode dans une sous-classe. La méthode standard @ref{308f,,run()} invoque l'objet appelable passé au constructeur comme argument `target', si fourni, avec les arguments séquentiels et nommés respectivement pris depuis les paramètres `args' et `kwargs'.

Using a list or tuple as the `args' argument passed to @ref{b47,,Process}
achieves the same effect.

Example:

@example
>>> from multiprocessing import Process
>>> p = Process(target=print, args=[1])
>>> p.run()
1
>>> p = Process(target=print, args=(1,))
>>> p.run()
1
@end example
@end deffn

@geindex start() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process start}@anchor{308c}
@deffn {Méthode} start ()

Démarre l'activité du processus.

Elle doit être appelée au plus une fois par objet processus. Elle s'arrange pour que la méthode @ref{308f,,run()} de l'objet soit invoquée dans un processus séparé.
@end deffn

@geindex join() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process join}@anchor{30a0}
@deffn {Méthode} join ([timeout])

Si l'argument optionnel `timeout' est @code{None} (par défaut), la méthode bloque jusqu'à ce que le processus dont la méthode @ref{30a0,,join()} a été appelée se termine. Si `timeout' est un nombre positif, elle bloque au maximum pendant `timeout' secondes. Notez que la méthode renvoie @code{None} si le processus se termine ou si le temps d'exécution expire. Vérifiez l'attribut @ref{30a1,,exitcode} du processus pour déterminer s'il s'est terminé.

`join' peut être appelée plusieurs fois sur un même processus.

Un processus ne peut pas s'attendre lui-même car cela causerait un interblocage. C'est une erreur d'essayer d'attendre un processus avant qu'il ne soit démarré.
@end deffn

@geindex name (attribut multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process name}@anchor{309e}
@deffn {Attribut} name

Le nom du processus. Le nom est une chaîne de caractères utilisée uniquement pour l'identification du processus. Il n'a pas de sémantique. Plusieurs processus peuvent avoir le même nom.

Le nom initial est déterminé par le constructeur. Si aucun nom explicite n'est fourni au constructeur, un nom de la forme « Process-N@w{[1]}:N@w{[2]}:...:N@w{[k]} » est construit, où chaque N@w{[k]} est le N@w{^e} fils de son parent.
@end deffn

@geindex is_alive() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process is_alive}@anchor{30a2}
@deffn {Méthode} is_alive ()

Renvoie vrai si le processus est en vie, faux sinon.

Grossièrement, un objet processus est en vie depuis le moment où la méthode @ref{308c,,start()} finit de s'exécuter jusqu'à ce que le processus fils se termine.
@end deffn

@geindex daemon (attribut multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process daemon}@anchor{309f}
@deffn {Attribut} daemon

L'option `daemon' du processus, une valeur booléenne. L'option doit être réglée avant que la méthode @ref{308c,,start()} ne soit appelée.

La valeur initiale est héritée par le processus créateur.

Quand un processus se ferme, il tente de terminer tous ses processus fils `daemon'.

Notez qu'un processus `daemon' n'est pas autorisé à créer des processus fils. Sinon un processus `daemon' laisserait ses fils orphelins lorsqu'il se termine par la fermeture de son parent. De plus, ce `ne sont pas' des `daemons' ou services Unix, ce sont des processus normaux qui seront terminés (et non attendus) si un processus non `daemon' se ferme.
@end deffn

En plus de l'API @ref{939,,threading.Thread}, les objets @ref{b47,,Process} supportent aussi les attributs et méthodes suivants :

@geindex pid (attribut multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process pid}@anchor{30a3}
@deffn {Attribut} pid

Renvoie l'ID du processus. Avant que le processus ne soit lancé, la valeur est @code{None}.
@end deffn

@geindex exitcode (attribut multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process exitcode}@anchor{30a1}
@deffn {Attribut} exitcode

The child's exit code.  This will be @code{None} if the process has not yet
terminated.

If the child's @ref{308f,,run()} method returned normally, the exit code
will be 0.  If it terminated via @ref{1327,,sys.exit()} with an integer
argument `N', the exit code will be `N'.

If the child terminated due to an exception not caught within
@ref{308f,,run()}, the exit code will be 1.  If it was terminated by
signal `N', the exit code will be the negative value `-N'.
@end deffn

@geindex authkey (attribut multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process authkey}@anchor{30a4}
@deffn {Attribut} authkey

La clé d'authentification du processus (une chaîne d'octets).

Quand @ref{93,,multiprocessing} est initialisé, une chaîne aléatoire est assignée au processus principal, en utilisant @ref{50c,,os.urandom()}.

Quand un objet @ref{b47,,Process} est créé, il hérité de la clé d'authentification de son parent, bien que cela puisse être changé à l'aide du paramètre @ref{30a4,,authkey} pour une autre chaîne d'octets.

Voir @ref{30a5,,Clés d'authentification}.
@end deffn

@geindex sentinel (attribut multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process sentinel}@anchor{10c2}
@deffn {Attribut} sentinel

Un identifiant numérique de l'objet système qui devient « prêt » quand le processus se termine.

You can use this value if you want to wait on several events at
once using @ref{10c1,,multiprocessing.connection.wait()}.  Otherwise
calling @ref{30a0,,join()} is simpler.

On Windows, this is an OS handle usable with the @code{WaitForSingleObject}
and @code{WaitForMultipleObjects} family of API calls.  On POSIX, this is
a file descriptor usable with primitives from the @ref{c0,,select} module.


Ajouté dans la version 3.3.

@end deffn

@geindex terminate() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process terminate}@anchor{30a6}
@deffn {Méthode} terminate ()

Terminate the process.  On POSIX this is done using the @ref{1396,,SIGTERM} signal;
on Windows @code{TerminateProcess()} is used.  Note that exit handlers and
finally clauses, etc., will not be executed.

Notez que les descendants du processus ne sont `pas' terminés – ils deviendront simplement orphelins.

@cartouche
@quotation Avertissement 
Si cette méthode est utilisée quand le processus associé utilise un tube ou une file, alors le tube ou la file sont susceptibles d'être corrompus et peuvent devenir inutilisables par les autres processus. De façon similaire, si le processus a acquis un verrou, un sémaphore ou autre, alors le terminer est susceptible de provoquer des blocages dans les autres processus.
@end quotation
@end cartouche
@end deffn

@geindex kill() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process kill}@anchor{b46}
@deffn {Méthode} kill ()

Same as @ref{30a6,,terminate()} but using the @code{SIGKILL} signal on POSIX.


Ajouté dans la version 3.7.

@end deffn

@geindex close() (méthode multiprocessing.Process)
@anchor{library/multiprocessing multiprocessing Process close}@anchor{b45}
@deffn {Méthode} close ()

Ferme l'objet @ref{b47,,Process}, libérant toutes les ressources qui lui sont associées. Une @ref{1ff,,ValueError} est levée si le processus sous-jacent tourne toujours. Une fois que @ref{b45,,close()} se termine avec succès, la plupart des autres méthodes et attributs des objets @ref{b47,,Process} lèveront une @ref{1ff,,ValueError}.


Ajouté dans la version 3.7.

@end deffn

Notez que les méthodes @ref{308c,,start()}, @ref{30a0,,join()}, @ref{30a2,,is_alive()}, @ref{30a6,,terminate()} et @ref{30a1,,exitcode} ne doivent être appelées que par le processus ayant créé l'objet `process'.

Exemple d'utilisation de quelques méthodes de @ref{b47,,Process} :

@example
>>> import multiprocessing, time, signal
>>> mp_context = multiprocessing.get_context('spawn')
>>> p = mp_context.Process(target=time.sleep, args=(1000,))
>>> print(p, p.is_alive())
<...Process ... initial> False
>>> p.start()
>>> print(p, p.is_alive())
<...Process ... started> True
>>> p.terminate()
>>> time.sleep(0.1)
>>> print(p, p.is_alive())
<...Process ... stopped exitcode=-SIGTERM> False
>>> p.exitcode == -signal.SIGTERM
True
@end example
@end deffn

@geindex ProcessError
@anchor{library/multiprocessing multiprocessing ProcessError}@anchor{30a7}
@deffn {Exception} multiprocessing.ProcessError

La classe de base de toutes les exceptions de @ref{93,,multiprocessing}.
@end deffn

@geindex BufferTooShort
@anchor{library/multiprocessing multiprocessing BufferTooShort}@anchor{30a8}
@deffn {Exception} multiprocessing.BufferTooShort

Exception raised by @code{Connection.recv_bytes_into()} when the supplied
buffer object is too small for the message read.

Si @code{e} est une instance de @ref{30a8,,BufferTooShort} alors @code{e.args[0]} donnera un message sous forme d'une chaîne d'octets.
@end deffn

@geindex AuthenticationError
@anchor{library/multiprocessing multiprocessing AuthenticationError}@anchor{30a9}
@deffn {Exception} multiprocessing.AuthenticationError

Levée quand il y a une erreur d'authentification.
@end deffn

@geindex TimeoutError
@anchor{library/multiprocessing multiprocessing TimeoutError}@anchor{30aa}
@deffn {Exception} multiprocessing.TimeoutError

Levée par les méthodes avec temps d'exécution limité, quand ce temps expire.
@end deffn

@node Tubes pipes et files queues,Divers<3>,Process et exceptions,Référence
@anchor{library/multiprocessing pipes-and-queues}@anchor{30ab}
@subsubsection Tubes (`pipes') et files (`queues')


Quand plusieurs processus travaillent ensemble, il est souvent nécessaire de les faire communiquer entre eux pour éviter d'avoir à utiliser des primitives de synchronisation comme les verrous.

Pour échanger des messages vous pouvez utiliser un @ref{3091,,Pipe()} (pour une connexion entre deux processus) ou une file (qui autorise de plusieurs producteurs et consommateurs).

Les types @ref{178a,,Queue}, @ref{901,,SimpleQueue} et @ref{30ac,,JoinableQueue} sont des files @abbr{FIFO} multi-producteurs et multi-consommateurs modelées sur la classe @ref{1365,,queue.Queue} de la bibliothèque standard. Elles diffèrent par l'absence dans @ref{178a,,Queue} des méthodes @ref{30ad,,task_done()} et @ref{30ae,,join()} introduites dans la classe @ref{1365,,queue.Queue} par Python 2.5.

Si vous utilisez @ref{30ac,,JoinableQueue} alors vous `devez' appeler @ref{30af,,JoinableQueue.task_done()} pour chaque tâche retirée de la file, sans quoi le sémaphore utilisé pour compter le nombre de tâches non accomplies pourra éventuellement déborder, levant une exception.

One difference from other Python queue implementations, is that @ref{93,,multiprocessing}
queues serializes all objects that are put into them using @ref{a5,,pickle}.
The object return by the get method is a re-created object that does not share memory
with the original object.

Notez que vous pouvez aussi créer une file partagée en utilisant un objet gestionnaire – voir @ref{30b0,,Gestionnaires}.

@cartouche
@quotation Note 
@ref{93,,multiprocessing} utilise les exceptions habituelles @ref{30b1,,queue.Empty} et @ref{30b2,,queue.Full} pour signaler un dépassement du temps maximal autorisé. Elles ne sont pas disponibles dans l'espace de nommage @ref{93,,multiprocessing} donc vous devez les importer depuis le module @ref{b5,,queue}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Quand un objet est placé dans une file, l'objet est sérialisé par `pickle' et un fil d'exécution en arrière-plan transmettra ensuite les données sérialisées sur un tube sous-jacent. Cela a certaines conséquences qui peuvent être un peu surprenantes, mais ne devrait causer aucune difficulté pratique — si elles vous embêtent vraiment, alors vous pouvez à la place utiliser une file créée avec un @ref{30b0,,manager}.


@enumerate 

@item 
Après avoir placé un objet dans une file vide il peut y avoir un délai infinitésimal avant que la méthode @ref{1583,,empty()} de la file renvoie @ref{b25,,False} et que @ref{30b3,,get_nowait()} renvoie une valeur sans lever de @ref{30b1,,queue.Empty}.

@item 
Si plusieurs processus placent des objets dans la file, il est possible pour les objets d'être reçus de l'autre côté dans le désordre. Cependant, les objets placés par un même processus seront toujours récupérés dans l'ordre d'insertion.
@end enumerate
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Si un processus est tué à l'aide de @ref{30a6,,Process.terminate()} ou @ref{133e,,os.kill()} pendant qu'il tente d'utiliser une @ref{178a,,Queue}, alors les données de la file peuvent être corrompues. Cela peut par la suite causer des levées d'exceptions dans les autres processus quand ils tenteront d'utiliser la file.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Comme mentionné plus haut, si un processus fils a placé des éléments dans la file (et qu'il n'a pas utilisé @ref{30b4,,JoinableQueue.cancel_join_thread}), alors le processus ne se terminera pas tant que les éléments placés dans le tampon n'auront pas été transmis au tube.

Cela signifie que si vous essayez d'attendre ce processus vous pouvez obtenir un interblocage, à moins que vous ne soyez sûr que tous les éléments placés dans la file ont été consommés. De même, si le processus fils n'est pas un `daemon' alors le processus parent pourrait bloquer à la fermeture quand il tentera d'attendre tous ses fils non `daemons'.

Notez que la file créée à l'aide d'un gestionnaire n'a pas ce problème. Voir @ref{308d,,Lignes directrices de programmation}.
@end quotation
@end cartouche

Pour un exemple d'utilisation de files pour de la communication entre les processus, voir @ref{30b5,,Exemples}.

@geindex Pipe() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing Pipe}@anchor{3091}
@deffn {Fonction} multiprocessing.Pipe ([duplex])

Renvoie une paire @code{(conn1, conn2)} d'objets @ref{1633,,Connection} représentant les extrémités d'un tube.

Si `duplex' vaut @code{True} (par défaut), alors le tube est bidirectionnel. Si `duplex' vaut @code{False} il est unidirectionnel : @code{conn1} ne peut être utilisé que pour recevoir des messages et @code{conn2} que pour en envoyer.

The @code{send()} method serializes the object using
@ref{a5,,pickle} and the @code{recv()} re-creates the object.
@end deffn

@geindex Queue (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Queue}@anchor{178a}
@deffn {Classe} multiprocessing.Queue ([maxsize])

Renvoie une file partagée entre les processus utilisant un tube et quelques verrous / sémaphores. Quand un processus place initialement un élément sur la file, un fil d'exécution `chargeur' est démarré pour transférer les objets du tampon vers le tube.

Les exceptions habituelles @ref{30b1,,queue.Empty} et @ref{30b2,,queue.Full} du module @ref{b5,,queue} de la bibliothèque standard sont levées pour signaler les `timeouts'.

@ref{178a,,Queue} implémente toutes les méthodes de @ref{1365,,queue.Queue} à l'exception de @ref{30ad,,task_done()} et @ref{30ae,,join()}.

@geindex qsize() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue qsize}@anchor{30b6}
@deffn {Méthode} qsize ()

Renvoie la taille approximative de la file. Ce nombre n'est pas fiable en raison des problématiques de `multithreading' et `multiprocessing'.

Note that this may raise @ref{225,,NotImplementedError} on platforms like
macOS where @code{sem_getvalue()} is not implemented.
@end deffn

@geindex empty() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue empty}@anchor{1583}
@deffn {Méthode} empty ()

Renvoie @code{True} si la file est vide, @code{False} sinon. Cette valeur n'est pas fiable en raison des problématiques de `multithreading' et `multiprocessing'.

May raise an @ref{40d,,OSError} on closed queues. (not guaranteed)
@end deffn

@geindex full() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue full}@anchor{30b7}
@deffn {Méthode} full ()

Renvoie @code{True} si la file est pleine, @code{False} sinon. Cette valeur n'est pas fiable en raison des problématiques de `multithreading' et `multiprocessing'.
@end deffn

@geindex put() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue put}@anchor{19ca}
@deffn {Méthode} put (obj[, block[, timeout]])

Place `obj' dans la file. Si l'argument optionnel `block' vaut @code{True} (par défaut) est que `timeout' est @code{None} (par défaut), bloque jusqu'à ce qu'une place libre soit disponible. Si `timeout' est un nombre positif, la méthode bloquera au maximum `timeout' secondes et lève une exception @ref{30b2,,queue.Full} si aucune place libre n'a été trouvée dans le temps imparti. Autrement (`block' vaut @code{False}), place un élément dans la file si une place libre est immédiatement disponible, ou lève une exception @ref{30b2,,queue.Full} dans le cas contraire (`timeout' est ignoré dans ce cas).


Modifié dans la version 3.8: si la file a été marquée comme fermée, une @ref{1ff,,ValueError} est levée. Auparavant, une @ref{694,,AssertionError} était levée.

@end deffn

@geindex put_nowait() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue put_nowait}@anchor{30b8}
@deffn {Méthode} put_nowait (obj)

Équivalent à @code{put(obj, False)}.
@end deffn

@geindex get() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue get}@anchor{19cb}
@deffn {Méthode} get ([block[, timeout]])

Retire et renvoie un élément de la file. Si l'argument optionnel `block' vaut @code{True} (par défaut) et que `timeout' est @code{None} (par défaut), bloque jusqu'à ce qu'un élément soit disponible. Si `timeout' (le délai maximal autorisé) est un nombre positif, la méthode bloque au maximum `timeout' secondes et lève une exception @ref{30b1,,queue.Empty} si aucun élément n'est disponible dans le temps imparti. Autrement (`block' vaut @code{False}), renvoie un élément s'il est immédiatement disponible, ou lève une exception @ref{30b1,,queue.Empty} dans le cas contraire (`timeout' est ignoré dans ce cas).


Modifié dans la version 3.8: si la file a été marquée comme terminée, une @ref{1ff,,ValueError} est levée. Auparavant, une @ref{40d,,OSError}. était levée.

@end deffn

@geindex get_nowait() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue get_nowait}@anchor{30b3}
@deffn {Méthode} get_nowait ()

Équivalent à @code{get(False)}.
@end deffn

@ref{178a,,multiprocessing.Queue} possède quelques méthodes additionnelles non présentes dans @ref{1365,,queue.Queue}. Ces méthodes ne sont habituellement pas nécessaires pour la plupart des codes :

@geindex close() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue close}@anchor{178b}
@deffn {Méthode} close ()

Indique que plus aucune donnée ne peut être placée sur la file par le processus courant. Le fil d'exécution en arrière-plan se terminera quand il aura transféré toutes les données du tampon vers le tube. Elle est appelée automatiquement quand la file est collectée par le ramasse-miettes.
@end deffn

@geindex join_thread() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue join_thread}@anchor{30b9}
@deffn {Méthode} join_thread ()

Attend le fil d'exécution d'arrière-plan. Elle peut seulement être utilisée une fois que @ref{178b,,close()} a été appelée. Elle bloque jusqu'à ce que le fil d'arrière-plan se termine, assurant que toutes les données du tampon ont été transmises au tube.

Par défaut si un processus n'est pas le créateur de la file alors à la fermeture elle essaie d'attendre le fil d'exécution d'arrière-plan de la file. Le processus peut appeler @ref{30b4,,cancel_join_thread()} pour que @ref{30b9,,join_thread()} ne fasse rien.
@end deffn

@geindex cancel_join_thread() (méthode multiprocessing.Queue)
@anchor{library/multiprocessing multiprocessing Queue cancel_join_thread}@anchor{30b4}
@deffn {Méthode} cancel_join_thread ()

Empêche @ref{30b9,,join_thread()} de bloquer. En particulier, cela empêche le fil d'arrière-plan d'être attendu automatiquement quand le processus se ferme – voir @ref{30b9,,join_thread()}.

Un meilleur nom pour cette méthode pourrait être @code{allow_exit_without_flush()}. Cela peut provoquer des pertes de données placées dans la file, et il est très rare d'avoir besoin de l'utiliser. Elle n'est là que si vous souhaitez terminer immédiatement le processus sans transférer les données du tampon, et que vous êtes prêt à perdre des données.
@end deffn

@cartouche
@quotation Note 
Le fonctionnement de cette classe requiert une implémentation de sémaphore partagé sur le système d'exploitation hôte. Sans cela, la fonctionnalité est désactivée et la tentative d'instancier une @ref{178a,,Queue} lève une @ref{40f,,ImportError}. Voir bpo-3770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3770} pour plus d'informations. Cette remarque reste valable pour les autres types de files spécialisées définies par la suite.
@end quotation
@end cartouche
@end deffn

@geindex SimpleQueue (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing SimpleQueue}@anchor{901}
@deffn {Classe} multiprocessing.SimpleQueue

Un type de @ref{178a,,Queue} simplifié, très proche d'un @ref{3091,,Pipe} avec verrou.

@geindex close() (méthode multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue close}@anchor{902}
@deffn {Méthode} close ()

Ferme la file : libère les ressources internes.

Une file ne doit plus être utilisée après sa fermeture. Par exemple, les méthodes @ref{30ba,,get()}, @ref{30bb,,put()} et @ref{1584,,empty()} ne doivent plus être appelées.


Ajouté dans la version 3.9.

@end deffn

@geindex empty() (méthode multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue empty}@anchor{1584}
@deffn {Méthode} empty ()

Renvoie @code{True} si la file est vide, @code{False} sinon.

Always raises an @ref{40d,,OSError} if the SimpleQueue is closed.
@end deffn

@geindex get() (méthode multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue get}@anchor{30ba}
@deffn {Méthode} get ()

Supprime et renvoie un élément de la file.
@end deffn

@geindex put() (méthode multiprocessing.SimpleQueue)
@anchor{library/multiprocessing multiprocessing SimpleQueue put}@anchor{30bb}
@deffn {Méthode} put (item)

Place `item' dans la file.
@end deffn
@end deffn

@geindex JoinableQueue (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing JoinableQueue}@anchor{30ac}
@deffn {Classe} multiprocessing.JoinableQueue ([maxsize])

@ref{30ac,,JoinableQueue}, une sous-classe de @ref{178a,,Queue}, est une file qui ajoute des méthodes @ref{30af,,task_done()} et @ref{30bc,,join()}.

@geindex task_done() (méthode multiprocessing.JoinableQueue)
@anchor{library/multiprocessing multiprocessing JoinableQueue task_done}@anchor{30af}
@deffn {Méthode} task_done ()

Indique qu'une tâche précédemment placée dans la file est achevée. Utilisée par les consommateurs de la file. Pour chaque @ref{19cb,,get()} utilisée pour récupérer une tâche, un appel ultérieur à @ref{30af,,task_done()} indique à la file que le traitement de la tâche est terminé.

Si un @ref{30ae,,join()} est actuellement bloquant, il se débloquera quand tous les éléments auront été traités (signifiant qu'un appel à @ref{30af,,task_done()} a été reçu pour chaque élément ayant été placé via @ref{19ca,,put()} dans la file).

Lève une exception @ref{1ff,,ValueError} si appelée plus de fois qu'il y avait d'éléments dans la file.
@end deffn

@geindex join() (méthode multiprocessing.JoinableQueue)
@anchor{library/multiprocessing multiprocessing JoinableQueue join}@anchor{30bc}
@deffn {Méthode} join ()

Bloque jusqu'à ce que tous les éléments de la file aient été récupérés et traités.

Le compteur des tâches non accomplies augmente chaque fois qu'un élément est ajouté à la file. Le compteur redescend chaque fois qu'un consommateur appelle @ref{30af,,task_done()} pour indiquer qu'un élément a été récupéré et que tout le travail qui le concerne est complété. Quand le compteur des tâches non accomplies atteint zéro, @ref{30ae,,join()} est débloquée.
@end deffn
@end deffn

@node Divers<3>,Objets de connexions,Tubes pipes et files queues,Référence
@anchor{library/multiprocessing miscellaneous}@anchor{30bd}
@subsubsection Divers


@geindex active_children() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing active_children}@anchor{30be}
@deffn {Fonction} multiprocessing.active_children ()

Renvoie la liste de tous les fils vivants du processus courant.

Appeler cette méthode provoque l'effet de bord d'attendre tout processus qui n'a pas encore terminé.
@end deffn

@geindex cpu_count() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing cpu_count}@anchor{f5a}
@deffn {Fonction} multiprocessing.cpu_count ()

Renvoie le nombre de CPUs sur le système.

This number is not equivalent to the number of CPUs the current process can
use.  The number of usable CPUs can be obtained with
@ref{1bf,,os.process_cpu_count()} (or @code{len(os.sched_getaffinity(0))}).

Une @ref{225,,NotImplementedError} est levée quand il est impossible de déterminer ce nombre.


@subsubheading Voir aussi


@ref{1c0,,os.cpu_count()}
@ref{1bf,,os.process_cpu_count()}



Modifié dans la version 3.13: The return value can also be overridden using the
@ref{175,,-X cpu_count} flag or 
@geindex PYTHON_CPU_COUNT
@geindex variable d'environnement; PYTHON_CPU_COUNT
@ref{20d,,PYTHON_CPU_COUNT} as this is
merely a wrapper around the @ref{a0,,os} cpu count APIs.

@end deffn

@geindex current_process() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing current_process}@anchor{30bf}
@deffn {Fonction} multiprocessing.current_process ()

Renvoie l'objet @ref{b47,,Process} correspondant au processus courant.

Un analogue à @ref{2fe,,threading.current_thread()}.
@end deffn

@geindex parent_process() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing parent_process}@anchor{30c0}
@deffn {Fonction} multiprocessing.parent_process ()

Renvoie l'objet @ref{b47,,Process} correspondant au processus père de @ref{30bf,,current_process()}. Pour le processus maître, @code{parent_process} vaut @code{None}.


Ajouté dans la version 3.8.

@end deffn

@geindex freeze_support() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing freeze_support}@anchor{30c1}
@deffn {Fonction} multiprocessing.freeze_support ()

Ajoute le support des programmes utilisant @ref{93,,multiprocessing} qui ont été figés pour produire un exécutable Windows (testé avec `py2exe', `PyInstaller' et `cx_Freeze').

Cette fonction doit être appelée juste après la ligne @code{if __name__ == '__main__'} du module principal. Par exemple :

@example
from multiprocessing import Process, freeze_support

def f():
    print('hello world!')

if __name__ == '__main__':
    freeze_support()
    Process(target=f).start()
@end example

Si la ligne @code{freeze_support()} est omise, alors tenter de lancer l'exécutable figé lève une @ref{193,,RuntimeError}.

Appeler @code{freeze_support()} n'a pas d'effet quand elle est invoquée sur un système d'exploitation autre que Windows. De plus, si le module est lancé normalement par l'interpréteur Python sous Windows (le programme n'a pas été figé), alors @code{freeze_support()} n'a pas d'effet.
@end deffn

@geindex get_all_start_methods() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing get_all_start_methods}@anchor{f54}
@deffn {Fonction} multiprocessing.get_all_start_methods ()

Returns a list of the supported start methods, the first of which
is the default.  The possible start methods are @code{'fork'},
@code{'spawn'} and @code{'forkserver'}.  Not all platforms support all
methods.  See @ref{2c6,,Contextes et méthodes de démarrage}.


Ajouté dans la version 3.4.

@end deffn

@geindex get_context() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing get_context}@anchor{2c4}
@deffn {Fonction} multiprocessing.get_context (method=None)

Renvoie un contexte ayant les mêmes attributs que le module @ref{93,,multiprocessing}.

If `method' is @code{None} then the default context is returned.
Otherwise `method' should be @code{'fork'}, @code{'spawn'},
@code{'forkserver'}.  @ref{1ff,,ValueError} is raised if the specified
start method is not available.  See @ref{2c6,,Contextes et méthodes de démarrage}.


Ajouté dans la version 3.4.

@end deffn

@geindex get_start_method() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing get_start_method}@anchor{f55}
@deffn {Fonction} multiprocessing.get_start_method (allow_none=False)

Renvoie le nom de la méthode de démarrage utilisée pour démarrer le processus.

Si le nom de la méthode n'a pas été fixé et que `allow_none' est faux, alors la méthode de démarrage est réglée à celle par défaut et son nom est renvoyé. Si la méthode n'a pas été fixée et que `allow_none' est vrai, @code{None} est renvoyé.

The return value can be @code{'fork'}, @code{'spawn'}, @code{'forkserver'}
or @code{None}.  See @ref{2c6,,Contextes et méthodes de démarrage}.


Ajouté dans la version 3.4.



Modifié dans la version 3.8: sur macOS, la méthode de démarrage `spawn' est maintenant la méthode par défaut. La méthode de démarrage `fork' doit être considérée comme dangereuse car elle peut entraîner des plantages du sous-processus. Voir bpo-33725@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33725}.

@end deffn

@geindex set_executable() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing set_executable}@anchor{1793}
@deffn {Fonction} multiprocessing.set_executable (executable)

Set the path of the Python interpreter to use when starting a child process.
(By default @ref{3af,,sys.executable} is used).  Embedders will probably need to
do some thing like

@example
set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
@end example

avant de pouvoir créer des processus fils.


Modifié dans la version 3.4: Now supported on POSIX when the @code{'spawn'} start method is used.



Modifié dans la version 3.11: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex set_forkserver_preload() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing set_forkserver_preload}@anchor{1520}
@deffn {Fonction} multiprocessing.set_forkserver_preload (module_names)

Set a list of module names for the forkserver main process to attempt to
import so that their already imported state is inherited by forked
processes. Any @ref{40f,,ImportError} when doing so is silently ignored.
This can be used as a performance enhancement to avoid repeated work
in every process.

For this to work, it must be called before the forkserver process has been
launched (before creating a @code{Pool} or starting a @ref{b47,,Process}).

Only meaningful when using the @code{'forkserver'} start method.
See @ref{2c6,,Contextes et méthodes de démarrage}.


Ajouté dans la version 3.4.

@end deffn

@geindex set_start_method() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing set_start_method}@anchor{2c5}
@deffn {Fonction} multiprocessing.set_start_method (method, force=False)

Set the method which should be used to start child processes.
The `method' argument can be @code{'fork'}, @code{'spawn'} or @code{'forkserver'}.
Raises @ref{193,,RuntimeError} if the start method has already been set and `force'
is not @code{True}.  If `method' is @code{None} and `force' is @code{True} then the start
method is set to @code{None}.  If `method' is @code{None} and `force' is @code{False}
then the context is set to the default context.

Notez que cette fonction ne devrait être appelée qu'une fois au plus, et l'appel devrait être protégé à l'intérieur d'une clause @code{if __name__ == '__main__'} dans le module principal.

See @ref{2c6,,Contextes et méthodes de démarrage}.


Ajouté dans la version 3.4.

@end deffn

@cartouche
@quotation Note 
@ref{93,,multiprocessing} ne contient pas d'analogues à @ref{2ff,,threading.active_count()}, @ref{1833,,threading.enumerate()}, @ref{832,,threading.settrace()}, @ref{833,,threading.setprofile()}, @ref{1139,,threading.Timer}, ou @ref{16f9,,threading.local}.
@end quotation
@end cartouche

@node Objets de connexions,Primitives de synchronisation,Divers<3>,Référence
@anchor{library/multiprocessing connection-objects}@anchor{30c2}
@subsubsection Objets de connexions


Les objets de connexion autorisent l'envoi et la réception d'objets sérialisables ou de chaînes de caractères. Ils peuvent être vus comme des interfaces de connexion (`sockets') connectées orientées messages.

Les objets de connexion sont habituellement créés via @ref{3091,,Pipe} – voir aussi @ref{30c3,,Auditeurs et Clients}.

@geindex Connection (classe dans multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection Connection}@anchor{1633}
@deffn {Classe} multiprocessing.connection.Connection

@geindex send() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection send}@anchor{30c4}
@deffn {Méthode} send (obj)

Envoie un objet sur l'autre extrémité de la connexion, qui devra être lu avec @ref{30c5,,recv()}.

L'objet doit être sérialisable. Les `pickles' très larges (approximativement 32 Mo+, bien que cela dépende de l'OS) pourront lever une exception @ref{1ff,,ValueError}.
@end deffn

@geindex recv() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection recv}@anchor{30c5}
@deffn {Méthode} recv ()

Renvoie un objet envoyé depuis l'autre extrémité de la connexion en utilisant @ref{30c4,,send()}. Bloque jusqu'à ce que quelque chose soit reçu. Lève une @ref{12b7,,EOFError} s'il n'y a plus rien à recevoir et que l'autre extrémité a été fermée.
@end deffn

@geindex fileno() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection fileno}@anchor{30c6}
@deffn {Méthode} fileno ()

Renvoie le descripteur de fichier ou identifiant utilisé par la connexion.
@end deffn

@geindex close() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection close}@anchor{30c7}
@deffn {Méthode} close ()

Ferme la connexion.

Elle est appelée automatiquement quand la connexion est collectée par le ramasse-miettes.
@end deffn

@geindex poll() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection poll}@anchor{30c8}
@deffn {Méthode} poll ([timeout])

Renvoie vrai ou faux selon si des données sont disponibles à la lecture.

Si `timeout' n'est pas spécifié la méthode renverra immédiatement. Si `timeout' est un nombre alors il spécifie le temps maximum de blocage en secondes. Si `timeout' est @code{None}, un temps d'attente infini est utilisé.

Notez que plusieurs objets de connexions peuvent être attendus en même temps à l'aide de @ref{10c1,,multiprocessing.connection.wait()}.
@end deffn

@geindex send_bytes() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection send_bytes}@anchor{30c9}
@deffn {Méthode} send_bytes (buffer[, offset[, size]])

Envoie des données binaires depuis un @ref{d1b,,bytes-like object} comme un message complet.

Si `offset' est fourni, les données sont lues depuis cette position dans le tampon `buffer'. Si `size' est fourni, il indique le nombre d'octets qui seront lus depuis `buffer'. Les tampons très larges (approximativement 32 MiB+, bien que cela dépende de l'OS) pourront lever une exception @ref{1ff,,ValueError}.
@end deffn

@geindex recv_bytes() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection recv_bytes}@anchor{30ca}
@deffn {Méthode} recv_bytes ([maxlength])

Renvoie un message complet de données binaires envoyées depuis l'autre extrémité de la connexion comme une chaîne de caractères. Bloque jusqu'à ce qu'il y ait quelque chose à recevoir. Lève une @ref{12b7,,EOFError} s'il ne reste rien à recevoir et que l'autre côté de la connexion a été fermé.

Si `maxlength' est précisé que que le message est plus long que `maxlength' alors une @ref{40d,,OSError} est levée et la connexion n'est plus lisible.


Modifié dans la version 3.3: Cette fonction levait auparavant une @ref{103b,,IOError}, qui est maintenant un alias pour @ref{40d,,OSError}.

@end deffn

@geindex recv_bytes_into() (méthode multiprocessing.connection.Connection)
@anchor{library/multiprocessing multiprocessing connection Connection recv_bytes_into}@anchor{30cb}
@deffn {Méthode} recv_bytes_into (buffer[, offset])

Lit et stocke dans `buffer' un message complet de données binaires envoyées depuis l'autre extrémité de la connexion et renvoie le nombre d'octets du message. Bloque jusqu'à ce qu'il y ait quelque chose à recevoir. Lève une @ref{12b7,,EOFError} s'il ne reste rien à recevoir et que l'autre côté de la connexion a été fermé.

`buffer' doit être un @ref{d1b,,bytes-like object} accessible en écriture. Si `offset' est donné, le message sera écrit dans le tampon à partir de cette position. `offset' doit être un entier positif, inférieur à la taille de `buffer' (en octets).

Si le tampon est trop petit une exception @code{BufferTooShort} est levée et le message complet est accessible via @code{e.args[0]} où @code{e} est l'instance de l'exception.
@end deffn


Modifié dans la version 3.3: Les objets de connexions eux-mêmes peuvent maintenant être transférés entre les processus en utilisant @ref{30c4,,Connection.send()} et @ref{30c5,,Connection.recv()}.

Connection objects also now support the context management protocol -- see
@ref{1f42,,Le type gestionnaire de contexte}.  @ref{21d0,,__enter__()} returns the
connection object, and @ref{21d1,,__exit__()} calls @ref{30c7,,close()}.

@end deffn

Par exemple :

@example
>>> from multiprocessing import Pipe
>>> a, b = Pipe()
>>> a.send([1, 'hello', None])
>>> b.recv()
[1, 'hello', None]
>>> b.send_bytes(b'thank you')
>>> a.recv_bytes()
b'thank you'
>>> import array
>>> arr1 = array.array('i', range(5))
>>> arr2 = array.array('i', [0] * 10)
>>> a.send_bytes(arr1)
>>> count = b.recv_bytes_into(arr2)
>>> assert count == len(arr1) * arr1.itemsize
>>> arr2
array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])
@end example
@anchor{library/multiprocessing multiprocessing-recv-pickle-security}@anchor{30cc}
@cartouche
@quotation Avertissement 
La méthode @ref{30c5,,Connection.recv()} désérialise automatiquement les données qu'elle reçoit, ce qui peut être un risque de sécurité à moins que vous ne fassiez réellement confiance au processus émetteur du message.

Par conséquent, à moins que l'objet de connexion soit instancié par @code{Pipe()}, vous ne devriez uniquement utiliser les méthodes @ref{30c5,,recv()} et @ref{30c4,,send()} après avoir effectué une quelconque forme d'authentification. Voir @ref{30a5,,Clés d'authentification}.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Si un processus est tué pendant qu'il essaye de lire ou écrire sur le tube, alors les données du tube ont des chances d'être corrompues, parce qu'il devient impossible d'être sûr d'où se trouvent les bornes du message.
@end quotation
@end cartouche

@node Primitives de synchronisation,Objets ctypes partagés,Objets de connexions,Référence
@anchor{library/multiprocessing synchronization-primitives}@anchor{30cd}
@subsubsection Primitives de synchronisation


Généralement les primitives de synchronisation ne sont pas nécessaire dans un programme multi-processus comme elles le sont dans un programme multi-fils d'exécution. Voir la documentation du module @ref{ec,,threading}.

Notez que vous pouvez aussi créer des primitives de synchronisation en utilisant un objet gestionnaire – voir @ref{30b0,,Gestionnaires}.

@geindex Barrier (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Barrier}@anchor{309a}
@deffn {Classe} multiprocessing.Barrier (parties[, action[, timeout]])

Un objet barrière : un clone de @ref{11c0,,threading.Barrier}.


Ajouté dans la version 3.3.

@end deffn

@geindex BoundedSemaphore (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing BoundedSemaphore}@anchor{3098}
@deffn {Classe} multiprocessing.BoundedSemaphore ([value])

Un objet sémaphore lié : un analogue proche de @ref{1137,,threading.BoundedSemaphore}.

Une seule différence existe avec son proche analogue : le premier argument de sa méthode @code{acquire} est appelé `block', pour la cohérence avec @ref{30ce,,Lock.acquire()}.

@cartouche
@quotation Note 
Sur macOS, elle n'est pas distinguable de la classe @ref{3097,,Semaphore} parce que @code{sem_getvalue()} n'est pas implémentée sur cette plateforme.
@end quotation
@end cartouche
@end deffn

@geindex Condition (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Condition}@anchor{3099}
@deffn {Classe} multiprocessing.Condition ([lock])

Une variable conditionnelle : un alias pour @ref{1135,,threading.Condition}.

Si `lock' est spécifié il doit être un objet @ref{1522,,Lock} ou @ref{1523,,RLock} du module @ref{93,,multiprocessing}.


Modifié dans la version 3.3: La méthode @ref{3073,,wait_for()} a été ajoutée.

@end deffn

@geindex Event (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Event}@anchor{17f1}
@deffn {Classe} multiprocessing.Event

Un clone de @ref{1138,,threading.Event}.
@end deffn

@geindex Lock (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Lock}@anchor{1522}
@deffn {Classe} multiprocessing.Lock

Un verrou non récursif : un analogue proche de @ref{1600,,threading.Lock}. Une fois que le processus ou le fil d'exécution a acquis un verrou, les tentatives suivantes d'acquisition depuis n'importe quel processus ou fil d'exécution bloqueront jusqu'à ce qu'il soit libéré ; n'importe quel processus ou fil peut le libérer. Les concepts et comportements de @ref{1600,,threading.Lock} qui s'appliquent aux fils d'exécution sont répliqués ici dans @ref{1522,,multiprocessing.Lock} et s'appliquent aux processus et aux fils d'exécution, à l'exception de ce qui est indiqué.

Notez que @ref{1522,,Lock} est en fait une fonction `factory' qui renvoie une instance de @code{multiprocessing.synchronize.Lock} initialisée avec un contexte par défaut.

@ref{1522,,Lock} supporte le protocole @ref{5be,,context manager} et peut ainsi être utilisé avec une instruction @ref{5bc,,with}.

@geindex acquire() (méthode multiprocessing.Lock)
@anchor{library/multiprocessing multiprocessing Lock acquire}@anchor{30ce}
@deffn {Méthode} acquire (block=True, timeout=None)

Acquiert un verrou, bloquant ou non bloquant.

Avec l'argument `block' à @code{True} (par défaut), l'appel de méthode bloquera jusqu'à ce que le verrou soit dans déverrouillé, puis le verrouillera avant de renvoyer @code{True}. Notez que le nom de ce premier argument diffère de celui de @ref{683,,threading.Lock.acquire()}.

Avec l'argument `block' à @code{False}, l'appel de méthode ne bloque pas. Si le verrou est actuellement verrouillé, renvoie @code{False} ; autrement verrouille le verrou et renvoie @code{True}.

Quand invoqué avec un nombre flottant positif comme `timeout', bloque au maximum pendant ce nombre spécifié de secondes, tant que le verrou ne peut être acquis. Les invocations avec une valeur de `timeout' négatives sont équivalents à zéro. Les invocations avec un `timeout' à @code{None} (par défaut) correspondent à un délai d'attente infini. Notez que le traitement des valeurs de `timeout' négatives et @code{None} diffère du comportement implémenté dans @ref{683,,threading.Lock.acquire()}. L'argument `timeout' n'a pas d'implication pratique si l'argument `block' est mis ) @code{False} et est alors ignoré. Renvoie @code{True} si le verrou a été acquis et @code{False} si le temps de `timeout' a expiré.
@end deffn

@geindex release() (méthode multiprocessing.Lock)
@anchor{library/multiprocessing multiprocessing Lock release}@anchor{30cf}
@deffn {Méthode} release ()

Libère un verrou. Elle peut être appelée depuis n'importe quel processus ou fil d'exécution, pas uniquement le processus ou le fil qui a acquis le verrou à l'origine.

Le comportement est le même que @ref{12a0,,threading.Lock.release()} excepté que lorsque la méthode est appelée sur un verrou déverrouillé, une @ref{1ff,,ValueError} est levée.
@end deffn
@end deffn

@geindex RLock (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing RLock}@anchor{1523}
@deffn {Classe} multiprocessing.RLock

Un objet verrou récursif : un analogue proche de @ref{2dc,,threading.RLock}. Un verrou récursif doit être libéré par le processus ou le fil d'exécution qui l'a acquis. Quand un processus ou un fil acquiert un verrou récursif, le même processus/fil peut l'acquérir à nouveau sans bloquer ; le processus/fil doit le libérer autant de fois qu'il l'acquiert.

Notez que @ref{1523,,RLock} est en fait une fonction `factory' qui renvoie une instance de @code{multiprocessing.synchronize.RLock} initialisée avec un contexte par défaut.

@ref{1523,,RLock} supporte le protocole @ref{5be,,context manager} et peut ainsi être utilisée avec une instruction @ref{5bc,,with}.

@geindex acquire() (méthode multiprocessing.RLock)
@anchor{library/multiprocessing multiprocessing RLock acquire}@anchor{30d0}
@deffn {Méthode} acquire (block=True, timeout=None)

Acquiert un verrou, bloquant ou non bloquant.

Quand invoqué avec l'argument `block' à @code{True}, bloque jusqu'à ce que le verrou soit déverrouillé (n'appartenant à aucun processus ou fil d'exécution) sauf s'il appartient déjà au processus ou fil d'exécution courant. Le processus ou fil d'exécution courant prend la possession du verrou (s'il ne l'a pas déjà) et incrémente d'un le niveau de récursion du verrou, renvoyant ainsi @code{True}. Notez qu'il y a plusieurs différences dans le comportement de ce premier argument comparé à l'implémentation de @ref{e66,,threading.RLock.acquire()}, à commencer par le nom de l'argument lui-même.

Quand invoqué avec l'argument `block' à @code{False}, ne bloque pas. Si le verrou est déjà acquis (et possédé) par un autre processus ou fil d'exécution, le processus/fil courant n'en prend pas la possession et le niveau de récursion n'est pas incrémenté, résultant en une valeur de retour à @code{False}. Si le verrou est déverrouillé, le processus/fil courant en prend possession et incrémente son niveau de récursion, renvoyant @code{True}.

L'usage et les comportements de l'argument `timeout' sont les mêmes que pour @ref{30ce,,Lock.acquire()}. Notez que certains de ces comportements diffèrent par rapport à ceux implémentés par @ref{e66,,threading.RLock.acquire()}.
@end deffn

@geindex release() (méthode multiprocessing.RLock)
@anchor{library/multiprocessing multiprocessing RLock release}@anchor{30d1}
@deffn {Méthode} release ()

Libère un verrou, décrémentant son niveau de récursion. Si après la décrémentation le niveau de récursion est zéro, réinitialise le verrou à un état déverrouillé (n'appartenant à aucun processus ou fil d'exécution) et si des processus/fils attendent que le verrou se déverrouillé, autorise un seul d'entre-eux à continuer. Si après cette décrémentation le niveau de récursion est toujours strictement positif, le verrou reste verrouillé et propriété du processus/fil appelant.

N'appelez cette méthode que si le processus ou fil d'exécution appelant est propriétaire du verrou. Une @ref{694,,AssertionError} est levée si cette méthode est appelée par un processus/fil autre que le propriétaire ou si le verrou n'est pas verrouillé (possédé). Notez que le type d'exception levé dans cette situation diffère du comportement de @ref{306e,,threading.RLock.release()}.
@end deffn
@end deffn

@geindex Semaphore (classe dans multiprocessing)
@anchor{library/multiprocessing multiprocessing Semaphore}@anchor{3097}
@deffn {Classe} multiprocessing.Semaphore ([value])

Un objet sémaphore, proche analogue de @ref{1136,,threading.Semaphore}.

Une seule différence existe avec son proche analogue : le premier argument de sa méthode @code{acquire} est appelé `block', pour la cohérence avec @ref{30ce,,Lock.acquire()}.
@end deffn

@cartouche
@quotation Note 
Sous macOS, @code{sem_timedwait} n'est pas pris en charge, donc appeler @code{acquire()} avec un temps d'exécution limité émule le comportement de cette fonction en utilisant une boucle d'attente.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Certaines des fonctionnalités de ce paquet requièrent une implémentation fonctionnelle de sémaphores partagés sur le système hôte. Sans cela, le module @code{multiprocessing.synchronize} sera désactivé, et les tentatives de l'importer lèveront une @ref{40f,,ImportError}. Voir bpo-3770@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=3770} pour plus d'informations.
@end quotation
@end cartouche

@node Objets ctypes partagés,Gestionnaires<2>,Primitives de synchronisation,Référence
@anchor{library/multiprocessing shared-ctypes-objects}@anchor{30d2}
@subsubsection Objets @code{ctypes} partagés


Il est possible de créer des objets partagés utilisant une mémoire partagée pouvant être héritée par les processus fils.

@geindex Value() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing Value}@anchor{3094}
@deffn {Fonction} multiprocessing.Value (typecode_or_type, *args, lock=True)

Renvoie un objet @ref{2a,,ctypes} alloué depuis la mémoire partagée. Par défaut la valeur de retour est en fait un `wrapper' synchronisé autour de l'objet. L'objet en lui-même est accessible par l'attribut `value' de l'une @ref{3094,,Value}.

`typecode_or_type' détermine le type de l'objet renvoyé : il s'agit soit d'un type `ctype' soit d'un caractère `typecode' tel qu'utilisé par le module @ref{7,,array}. `*args' est passé au constructeur de ce type.

Si `lock' vaut @code{True} (par défaut), alors un nouveau verrou récursif est créé pour synchroniser l'accès à la valeur. Si `lock' est un objet @ref{1522,,Lock} ou @ref{1523,,RLock} alors il sera utilisé pour synchroniser l'accès à la valeur. Si `lock' vaut @code{False}, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « `process-safe' ».

Les opérations telles que @code{+=} qui impliquent une lecture et une écriture ne sont pas atomiques. Ainsi si vous souhaitez par exemple réaliser une incrémentation atomique sur une valeur partagée, vous ne pouvez pas simplement faire

@example
counter.value += 1
@end example

En supposant que le verrou associé est récursif (ce qui est le cas par défaut), vous pouvez à la place faire

@example
with counter.get_lock():
    counter.value += 1
@end example

Notez que `lock' est un argument `keyword-only'.
@end deffn

@geindex Array() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing Array}@anchor{3095}
@deffn {Fonction} multiprocessing.Array (typecode_or_type, size_or_initializer, *, lock=True)

Renvoie un tableau `ctypes' alloué depuis la mémoire partagée. Par défaut la valeur de retour est en fait un `wrapper' synchronisé autour du tableau.

`typecode_or_type' détermine le type des éléments du tableau renvoyé : il s'agit soit d'un type `ctype' soit d'un caractère `typecode' tel qu'utilisé par le module @ref{7,,array}. Si `size_or_initialize' est un entier, alors il détermine la taille du tableau, et le tableau sera initialisé avec des zéros. Autrement, `size*or_initializer' est une séquence qui sera utilisée pour initialiser le tableau et dont la taille détermine celle du tableau.

Si `lock' vaut @code{True} (par défaut), alors un nouveau verrou est créé pour synchroniser l'accès à la valeur. Si `lock' est un objet @ref{1522,,Lock} ou @ref{1523,,RLock} alors il sera utilisé pour synchroniser l'accès à la valeur. Si `lock' vaut @code{False}, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « `process-safe' ».

Notez que `lock' est un argument `keyword-only'.

Notez qu'un tableau de @ref{2d49,,ctypes.c_char} a ses attributs `value' et `raw' qui permettent de l'utiliser pour stocker et récupérer des chaînes de caractères.
@end deffn

@menu
* Le module multiprocessing.sharedctypes: Le module multiprocessing sharedctypes. 

@end menu

@node Le module multiprocessing sharedctypes,,,Objets ctypes partagés
@anchor{library/multiprocessing module-multiprocessing sharedctypes}@anchor{99}@anchor{library/multiprocessing the-multiprocessing-sharedctypes-module}@anchor{30d3}
@subsubsection Le module @code{multiprocessing.sharedctypes}


@geindex module; multiprocessing.sharedctypes

Le module @ref{99,,multiprocessing.sharedctypes} fournit des fonctions pour allouer des objets @ref{2a,,ctypes} depuis la mémoire partagée, qui peuvent être hérités par les processus fils.

@cartouche
@quotation Note 
Bien qu'il soit possible de stocker un pointeur en mémoire partagée, rappelez-vous qu'un pointer référence un emplacement dans l'espace d'adressage d'un processus particulier. Ainsi, ce pointeur a de fortes chances d'être invalide dans le contexte d'un autre processus et déréférencer le pointeur depuis ce second processus peut causer un plantage.
@end quotation
@end cartouche

@geindex RawArray() (dans le module multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes RawArray}@anchor{30d4}
@deffn {Fonction} multiprocessing.sharedctypes.RawArray (typecode_or_type, size_or_initializer)

Renvoie un tableau `ctypes' alloué depuis la mémoire partagée.

`typecode_or_type' détermine le type des éléments du tableau renvoyé : il s'agit soit d'un type `ctype' soit d'un caractère codant le type des éléments du tableau (`typecode') tel qu'utilisé par le module @ref{7,,array}. Si `size_or_initialize' est un entier, alors il détermine la taille du tableau, et le tableau sera initialisé avec des zéros. Autrement, `size_or_initializer' est une séquence qui sera utilisée pour initialiser le tableau et dont la taille détermine celle du tableau.

Notez que définir ou récupérer un élément est potentiellement non atomique – utilisez plutôt @ref{30d5,,Array()} pour vous assurer de synchroniser automatiquement avec un verrou.
@end deffn

@geindex RawValue() (dans le module multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes RawValue}@anchor{30d6}
@deffn {Fonction} multiprocessing.sharedctypes.RawValue (typecode_or_type, *args)

Renvoie un objet `ctypes' alloué depuis la mémoire partagée.

`typecode_or_type' détermine le type de l'objet renvoyé : il s'agit soit d'un type `ctype' soit d'un caractère `typecode' tel qu'utilisé par le module @ref{7,,array}. `*args' est passé au constructeur de ce type.

Notez que définir ou récupérer un élément est potentiellement non atomique – utilisez plutôt @ref{30d7,,Value()} pour vous assurer de synchroniser automatiquement avec un verrou.

Notez qu'un tableau de @ref{2d49,,ctypes.c_char} a ses attributs `value' et `raw' qui permettent de l'utiliser pour stocker et récupérer des chaînes de caractères – voir la documentation de @ref{2a,,ctypes}.
@end deffn

@geindex Array() (dans le module multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes Array}@anchor{30d5}
@deffn {Fonction} multiprocessing.sharedctypes.Array (typecode_or_type, size_or_initializer, *, lock=True)

Identique à @ref{30d4,,RawArray()} à l'exception que suivant la valeur de `lock' un `wrapper' de synchronisation `process-safe' pourra être renvoyé à la place d'un tableau `ctypes' brut.

Si `lock' vaut @code{True} (par défaut), alors un nouveau verrou est créé pour synchroniser l'accès à la valeur. Si `lock' est un objet @ref{1522,,Lock} ou @ref{1523,,RLock} alors il sera utilisé pour synchroniser l'accès à la valeur. Si `lock' vaut @code{False}, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « `process-safe' ».

Notez que `lock' est un argument `keyword-only'.
@end deffn

@geindex Value() (dans le module multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes Value}@anchor{30d7}
@deffn {Fonction} multiprocessing.sharedctypes.Value (typecode_or_type, *args, lock=True)

Identique à @ref{30d6,,RawValue()} à l'exception que suivant la valeur de `lock' un `wrapper' de synchronisation `process-safe' pourra être renvoyé à la place d'un objet `ctypes' brut.

Si `lock' vaut @code{True} (par défaut), alors un nouveau verrou est créé pour synchroniser l'accès à la valeur. Si `lock' est un objet @ref{1522,,Lock} ou @ref{1523,,RLock} alors il sera utilisé pour synchroniser l'accès à la valeur. Si `lock' vaut @code{False}, l'accès à l'objet renvoyé ne sera pas automatiquement protégé par un verrou, donc il ne sera pas forcément « `process-safe' ».

Notez que `lock' est un argument `keyword-only'.
@end deffn

@geindex copy() (dans le module multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes copy}@anchor{30d8}
@deffn {Fonction} multiprocessing.sharedctypes.copy (obj)

Renvoie un objet `ctypes' alloué depuis la mémoire partagée, qui est une copie de l'objet `ctypes' `obj'.
@end deffn

@geindex synchronized() (dans le module multiprocessing.sharedctypes)
@anchor{library/multiprocessing multiprocessing sharedctypes synchronized}@anchor{e1e}
@deffn {Fonction} multiprocessing.sharedctypes.synchronized (obj[, lock])

Renvoie un `wrapper' `process-safe' autour de l'objet `ctypes' qui utilise `lock' pour synchroniser l'accès. Si `lock' est @code{None} (par défaut), un objet @ref{1523,,multiprocessing.RLock} est créé automatiquement.

Un `wrapper' synchronisé aura deux méthodes en plus de celles de l'objet qu'il enveloppe : @code{get_obj()} renvoie l'objet `wrappé' et @code{get_lock()} renvoie le verrou utilisé pour la synchronisation.

Notez qu'accéder à l'objet `ctypes' à travers le `wrapper' peut s'avérer beaucoup plus lent qu'accéder directement à l'objet `ctypes' brut.


Modifié dans la version 3.5: Les objets synchronisés supportent le protocole @ref{5be,,context manager}.

@end deffn

Le tableau ci-dessous compare la syntaxe de création des objets `ctypes' partagés depuis une mémoire partagée avec la syntaxe normale `ctypes'. (Dans le tableau, @code{MyStruct} est une sous-classe quelconque de @ref{1cf,,ctypes.Structure}.)


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

ctypes

@tab

`sharedctypes' utilisant un type

@tab

`sharedctypes' utilisant un `typecode'

@item

c_double(2.4)

@tab

RawValue(c_double, 2.4)

@tab

RawValue('d', 2.4)

@item

MyStruct(4, 6)

@tab

RawValue(MyStruct, 4, 6)

@tab

@item

(c_short * 7)()

@tab

RawArray(c_short, 7)

@tab

RawArray('h', 7)

@item

(c_int * 3)(9, 2, 8)

@tab

RawArray(c_int, (9, 2, 8))

@tab

RawArray('i', (9, 2, 8))

@end multitable


Ci-dessous un exemple où des objets `ctypes' sont modifiés par un processus fils :

@example
from multiprocessing import Process, Lock
from multiprocessing.sharedctypes import Value, Array
from ctypes import Structure, c_double

class Point(Structure):
    _fields_ = [('x', c_double), ('y', c_double)]

def modify(n, x, s, A):
    n.value **= 2
    x.value **= 2
    s.value = s.value.upper()
    for a in A:
        a.x **= 2
        a.y **= 2

if __name__ == '__main__':
    lock = Lock()

    n = Value('i', 7)
    x = Value(c_double, 1.0/3.0, lock=False)
    s = Array('c', b'hello world', lock=lock)
    A = Array(Point, [(1.875,-6.25), (-5.75,2.0), (2.375,9.5)], lock=lock)

    p = Process(target=modify, args=(n, x, s, A))
    p.start()
    p.join()

    print(n.value)
    print(x.value)
    print(s.value)
    print([(a.x, a.y) for a in A])
@end example

Les résultats affichés sont

@example
49
0.1111111111111111
HELLO WORLD
[(3.515625, 39.0625), (33.0625, 4.0), (5.640625, 90.25)]
@end example

@node Gestionnaires<2>,Objets mandataires,Objets ctypes partagés,Référence
@anchor{library/multiprocessing managers}@anchor{30d9}@anchor{library/multiprocessing multiprocessing-managers}@anchor{30b0}
@subsubsection Gestionnaires


Les gestionnaires fournissent un moyen de créer des données qui peuvent être partagées entre les différents processus, incluant le partage à travers le réseau entre des processus tournant sur des machines différentes. Un objet gestionnaire contrôle un processus serveur qui gère les `shared objects'. Les autres processus peuvent accéder aux objets partagés à l'aide de mandataires.

@geindex built-in function; multiprocessing.Manager()
@anchor{library/multiprocessing multiprocessing Manager}@anchor{ca8}
@deffn {Fonction} multiprocessing.Manager ()

Renvoie un objet @ref{30da,,SyncManager} démarré qui peut être utilisé pour partager des objets entre les processus. L'objet gestionnaire renvoyé correspond à un processus fils instancié et possède des méthodes pour créer des objets partagés et renvoyer les mandataires correspondants.
@end deffn

@geindex module; multiprocessing.managers
@anchor{library/multiprocessing module-multiprocessing managers}@anchor{96}
Les processus gestionnaires seront arrêtés dès qu'ils seront collectés par le ramasse-miettes ou que leur processus parent se terminera. Les classes gestionnaires sont définies dans le module @ref{96,,multiprocessing.managers} :

@geindex BaseManager (classe dans multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers BaseManager}@anchor{30db}
@deffn {Classe} multiprocessing.managers.BaseManager (address=None, authkey=None, serializer='pickle', ctx=None, *, shutdown_timeout=1.0)

Crée un objet `BaseManager'.

Une fois créé il faut appeler @ref{30dc,,start()} ou  @code{get_server().serve_forever()} pour assurer que l'objet gestionnaire référence un processus gestionnaire démarré.

`address' est l'adresse sur laquelle le processus gestionnaire écoute pour de nouvelles connexions. Si `address' est @code{None}, une adresse arbitraire est choisie.

`authkey' est la clé d'authentification qui sera utilisée pour vérifier la validité des connexions entrantes sur le processus serveur. Si `authkey' est @code{None} alors @code{current_process().authkey} est utilisée. Autrement `authkey' est utilisée et doit être une chaîne d'octets.

`serializer' must be @code{'pickle'} (use @ref{a5,,pickle} serialization) or
@code{'xmlrpclib'} (use @ref{12d,,xmlrpc.client} serialization).

`ctx' is a context object, or @code{None} (use the current context). See the
@code{get_context()} function.

`shutdown_timeout' is a timeout in seconds used to wait until the process
used by the manager completes in the @ref{30dd,,shutdown()} method. If the
shutdown times out, the process is terminated. If terminating the process
also times out, the process is killed.


Modifié dans la version 3.11: Added the `shutdown_timeout' parameter.


@geindex start() (méthode multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager start}@anchor{30dc}
@deffn {Méthode} start ([initializer[, initargs]])

Démarre un sous-processus pour démarrer le gestionnaire. Si `initializer' n'est pas @code{None} alors le sous-processus appellera @code{initializer(*initargs)} quand il démarrera.
@end deffn

@geindex get_server() (méthode multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager get_server}@anchor{30de}
@deffn {Méthode} get_server ()

Renvoie un objet @code{Server} qui représente le serveur sous le contrôle du gestionnaire. L'objet @code{Server} supporte la méthode @code{serve_forever()} :

@example
>>> from multiprocessing.managers import BaseManager
>>> manager = BaseManager(address=('@w{'}, 50000), authkey=b'abc')
>>> server = manager.get_server()
>>> server.serve_forever()
@end example

@code{Server} possède en plus un attribut @ref{30df,,address}.
@end deffn

@geindex connect() (méthode multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager connect}@anchor{30e0}
@deffn {Méthode} connect ()

Connecte un objet gestionnaire local au processus gestionnaire distant :

@example
>>> from multiprocessing.managers import BaseManager
>>> m = BaseManager(address=('127.0.0.1', 50000), authkey=b'abc')
>>> m.connect()
@end example
@end deffn

@geindex shutdown() (méthode multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager shutdown}@anchor{30dd}
@deffn {Méthode} shutdown ()

Stoppe le processus utilisé par le gestionnaire. Cela est disponible uniquement si @ref{30dc,,start()} a été utilisée pour démarrer le processus serveur.

Cette méthode peut être appelée plusieurs fois.
@end deffn

@geindex register() (méthode multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager register}@anchor{30e1}
@deffn {Méthode} register (typeid[, callable[, proxytype[, exposed[, method_to_typeid[, create_method]]]]])

Une méthode de classe qui peut être utilisée pour enregistrer un type ou un appelable avec la classe gestionnaire.

`typeif' est un « `type identifier' » qui est utilisé pour identifier un type particulier d'objet partagé. Cela doit être une chaîne de caractères.

`callable' est un objet appelable utilisé pour créer les objets avec cet identifiant de type. Si une instance de gestionnaire prévoit de se connecter au serveur en utilisant sa méthode @ref{30e0,,connect()} ou si l'argument `create_method' vaut @code{False} alors cet argument peut être laissé à @code{None}.

`proxytype' est une sous-classe de @ref{30e2,,BaseProxy} utilisée pour créer des mandataires autour des objets partagés avec ce `typeid'. S'il est @code{None}, une classe mandataire sera créée automatiquement.

`exposed' est utilisé pour préciser une séquence de noms de méthodes dont les mandataires pour ce `typeid' doivent être autorisés à accéder via @ref{30e3,,BaseProxy._callmethod()}. (Si `exposed' est @code{None} alors @code{proxytype._exposed_} est utilisé à la place s'il existe.) Dans le cas où aucune liste `exposed' n'est précisée, toutes les « méthodes publiques » de l'objet partagé seront accessibles. (Ici une « méthode publique » signifie n'importe quel attribut qui possède une méthode @ref{543,,__call__()} et dont le nom ne commence pas par un @code{'_'}.)

`method_to_typeid' est un tableau associatif utilisé pour préciser le type de retour de ces méthodes exposées qui doivent renvoyer un mandataire. Il associé un nom de méthode à une chaîne de caractères `typeid'. (Si `method_to_typeid' est @code{None}, @code{proxytype._method_to_typeid_} est utilisé à la place s'il existe). Si le nom d'une méthode n'est pas une clé de ce tableau associatif ou si la valeur associée est @code{None}, l'objet renvoyé par la méthode sera une copie de la valeur.

`create_method' détermine si une méthode devrait être créée avec le nom `typeid', qui peut être utilisée pour indiquer au processus serveur de créer un nouvel objet partagé et d'en renvoyer un mandataire. a valeur par défaut est @code{True}.
@end deffn

Les instances de @ref{30db,,BaseManager} ont aussi une propriété en lecture seule :

@geindex address (attribut multiprocessing.managers.BaseManager)
@anchor{library/multiprocessing multiprocessing managers BaseManager address}@anchor{30df}
@deffn {Attribut} address

L'adresse utilisée par le gestionnaire.
@end deffn


Modifié dans la version 3.3: Les objets gestionnaires supportent le protocole des gestionnaires de contexte – voir @ref{1f42,,Le type gestionnaire de contexte}. @ref{21d0,,__enter__()} démarre le processus serveur (s'il n'a pas déjà été démarré) et renvoie l'objet gestionnaire. @ref{21d1,,__exit__()} appelle @ref{30dd,,shutdown()}.

Dans les versions précédentes @ref{21d0,,__enter__()} ne démarrait pas le processus serveur du gestionnaire s'il n'était pas déjà démarré.

@end deffn

@geindex SyncManager (classe dans multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers SyncManager}@anchor{30da}
@deffn {Classe} multiprocessing.managers.SyncManager

Une sous-classe de @ref{30db,,BaseManager} qui peut être utilisée pour la synchronisation entre processus. Des objets de ce type sont renvoyés par @ref{ca8,,multiprocessing.Manager()}.

Ces méthodes créent et renvoient des @ref{ca7,,Objets mandataires} pour un certain nombre de types de données communément utilisés pour être synchronisés entre les processus. Elles incluent notamment des listes et dictionnaires partagés.

@geindex Barrier() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Barrier}@anchor{30e4}
@deffn {Méthode} Barrier (parties[, action[, timeout]])

Crée un objet @ref{11c0,,threading.Barrier} partagé et renvoie un mandataire pour cet objet.


Ajouté dans la version 3.3.

@end deffn

@geindex BoundedSemaphore() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager BoundedSemaphore}@anchor{30e5}
@deffn {Méthode} BoundedSemaphore ([value])

Crée un objet @ref{1137,,threading.BoundedSemaphore} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex Condition() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Condition}@anchor{30e6}
@deffn {Méthode} Condition ([lock])

Crée un objet @ref{1135,,threading.Condition} partagé et renvoie un mandataire pour cet objet.

Si `lock' est fourni alors il doit être un mandataire pour un objet @ref{1600,,threading.Lock} ou @ref{2dc,,threading.RLock}.


Modifié dans la version 3.3: La méthode @ref{3073,,wait_for()} a été ajoutée.

@end deffn

@geindex Event() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Event}@anchor{30e7}
@deffn {Méthode} Event ()

Crée un objet @ref{1138,,threading.Event} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex Lock() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Lock}@anchor{30e8}
@deffn {Méthode} Lock ()

Crée un objet @ref{1600,,threading.Lock} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex Namespace() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Namespace}@anchor{30e9}
@deffn {Méthode} Namespace ()

Crée un objet @ref{3096,,Namespace} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex Queue() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Queue}@anchor{2c54}
@deffn {Méthode} Queue ([maxsize])

Crée un objet @ref{1365,,queue.Queue} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex RLock() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager RLock}@anchor{30ea}
@deffn {Méthode} RLock ()

Crée un objet @ref{2dc,,threading.RLock} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex Semaphore() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Semaphore}@anchor{30eb}
@deffn {Méthode} Semaphore ([value])

Crée un objet @ref{1136,,threading.Semaphore} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex Array() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Array}@anchor{30ec}
@deffn {Méthode} Array (typecode, sequence)

Crée un tableau et renvoie un mandataire pour cet objet.
@end deffn

@geindex Value() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager Value}@anchor{30ed}
@deffn {Méthode} Value (typecode, value)

Crée un objet avec un attribut @code{value} accessible en écriture et renvoie un mandataire pour cet objet.
@end deffn

@geindex dict() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager dict}@anchor{30ee}
@deffn {Méthode} dict ()

@deffnx {Méthode} dict (mapping)

@deffnx {Méthode} dict (sequence)

Crée un objet @ref{253,,dict} partagé et renvoie un mandataire pour cet objet.
@end deffn

@geindex list() (méthode multiprocessing.managers.SyncManager)
@anchor{library/multiprocessing multiprocessing managers SyncManager list}@anchor{30ef}
@deffn {Méthode} list ()

@deffnx {Méthode} list (sequence)

Crée un objet @ref{5fc,,list} partagé et renvoie un mandataire pour cet objet.
@end deffn


Modifié dans la version 3.6: Les objets partagés peuvent être imbriqués. Par exemple, un conteneur partagé tel qu'une liste partagée peu contenir d'autres objets partagés qui seront aussi gérés et synchronisés par le @ref{30da,,SyncManager}.

@end deffn

@geindex Namespace (classe dans multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers Namespace}@anchor{3096}
@deffn {Classe} multiprocessing.managers.Namespace

Un type qui peut être enregistré avec @ref{30da,,SyncManager}.

Un espace de nommage n'a pas de méthodes publiques, mais possède des attributs accessibles en écriture. Sa représentation montre les valeurs de ses attributs.

Cependant, en utilisant un mandataire pour un espace de nommage, un attribut débutant par @code{'_'} est un attribut du mandataire et non de l'objet cible :

@example
>>> mp_context = multiprocessing.get_context('spawn')
>>> manager = mp_context.Manager()
>>> Global = manager.Namespace()
>>> Global.x = 10
>>> Global.y = 'hello'
>>> Global._z = 12.3    # this is an attribute of the proxy
>>> print(Global)
Namespace(x=10, y='hello')
@end example
@end deffn

@menu
* Gestionnaires personnalisés:: 
* Utiliser un gestionnaire distant:: 

@end menu

@node Gestionnaires personnalisés,Utiliser un gestionnaire distant,,Gestionnaires<2>
@anchor{library/multiprocessing customized-managers}@anchor{30f0}
@subsubsection Gestionnaires personnalisés


Pour créer son propre gestionnaire, il faut créer une sous-classe de @ref{30db,,BaseManager} et utiliser la méthode de classe @ref{30e1,,register()} pour enregistrer de nouveaux types ou `callables' au gestionnaire. Par exemple :

@example
from multiprocessing.managers import BaseManager

class MathsClass:
    def add(self, x, y):
        return x + y
    def mul(self, x, y):
        return x * y

class MyManager(BaseManager):
    pass

MyManager.register('Maths', MathsClass)

if __name__ == '__main__':
    with MyManager() as manager:
        maths = manager.Maths()
        print(maths.add(4, 3))         # prints 7
        print(maths.mul(7, 8))         # prints 56
@end example

@node Utiliser un gestionnaire distant,,Gestionnaires personnalisés,Gestionnaires<2>
@anchor{library/multiprocessing using-a-remote-manager}@anchor{30f1}
@subsubsection Utiliser un gestionnaire distant


Il est possible de lancer un serveur gestionnaire sur une machine et d'avoir des clients l'utilisant sur d'autres machines (en supposant que les pare-feus impliqués l'autorisent).

Exécuter les commandes suivantes crée un serveur pour une file simple partagée à laquelle des clients distants peuvent accéder :

@example
>>> from multiprocessing.managers import BaseManager
>>> from queue import Queue
>>> queue = Queue()
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue', callable=lambda:queue)
>>> m = QueueManager(address=('@w{'}, 50000), authkey=b'abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()
@end example

Un client peut accéder au serveur comme suit :

@example
>>> from multiprocessing.managers import BaseManager
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue')
>>> m = QueueManager(address=('foo.bar.org', 50000), authkey=b'abracadabra')
>>> m.connect()
>>> queue = m.get_queue()
>>> queue.put('hello')
@end example

Un autre client peut aussi l'utiliser :

@example
>>> from multiprocessing.managers import BaseManager
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue')
>>> m = QueueManager(address=('foo.bar.org', 50000), authkey=b'abracadabra')
>>> m.connect()
>>> queue = m.get_queue()
>>> queue.get()
'hello'
@end example

Les processus locaux peuvent aussi accéder à cette file, utilisant le code précédent sur le client pour y accéder à distance :

@example
>>> from multiprocessing import Process, Queue
>>> from multiprocessing.managers import BaseManager
>>> class Worker(Process):
...     def __init__(self, q):
...         self.q = q
...         super().__init__()
...     def run(self):
...         self.q.put('local hello')
...
>>> queue = Queue()
>>> w = Worker(queue)
>>> w.start()
>>> class QueueManager(BaseManager): pass
...
>>> QueueManager.register('get_queue', callable=lambda: queue)
>>> m = QueueManager(address=('@w{'}, 50000), authkey=b'abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()
@end example

@node Objets mandataires,Pools de processus,Gestionnaires<2>,Référence
@anchor{library/multiprocessing multiprocessing-proxy-objects}@anchor{ca7}@anchor{library/multiprocessing proxy-objects}@anchor{30f2}
@subsubsection Objets mandataires


Un mandataire est un objet qui `référence' un objet partagé appartenant (supposément) à un processus différent. L'objet partagé est appelé le `référent' du mandataire. Plusieurs mandataires peuvent avoir un même référent.

Un mandataire possède des méthodes qui appellent les méthodes correspondantes du référent (bien que toutes les méthodes du référent ne soient pas nécessairement accessibles à travers le mandataire). De cette manière, un mandataire peut être utilisé comme le serait sont référent :

@example
>>> mp_context = multiprocessing.get_context('spawn')
>>> manager = mp_context.Manager()
>>> l = manager.list([i*i for i in range(10)])
>>> print(l)
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
>>> print(repr(l))
<ListProxy object, typeid 'list' at 0x...>
>>> l[4]
16
>>> l[2:5]
[4, 9, 16]
@end example

Notez qu'appliquer @ref{435,,str()} à un mandataire renvoie la représentation du référent, alors que @ref{7e7,,repr()} renvoie celle du mandataire.

Une fonctionnalité importantes des objets mandataires est qu'ils sont sérialisables et peuvent donc être échangés entre les processus. Ainsi, un référent peut contenir des @ref{ca7,,Objets mandataires}. Cela permet d'imbriquer des listes et dictionnaires gérés ainsi que d'autres @ref{ca7,,Objets mandataires} :

@example
>>> a = manager.list()
>>> b = manager.list()
>>> a.append(b)         # referent of a now contains referent of b
>>> print(a, b)
[<ListProxy object, typeid 'list' at ...>] []
>>> b.append('hello')
>>> print(a[0], b)
['hello'] ['hello']
@end example

De même, les mandataires de listes et dictionnaires peuvent être imbriqués dans d'autres :

@example
>>> l_outer = manager.list([ manager.dict() for i in range(2) ])
>>> d_first_inner = l_outer[0]
>>> d_first_inner['a'] = 1
>>> d_first_inner['b'] = 2
>>> l_outer[1]['c'] = 3
>>> l_outer[1]['z'] = 26
>>> print(l_outer[0])
@{'a': 1, 'b': 2@}
>>> print(l_outer[1])
@{'c': 3, 'z': 26@}
@end example

Si des objets standards (non `proxyfiés') @ref{5fc,,list} ou @ref{253,,dict} sont contenus dans un référent, les modifications sur ces valeurs mutables ne seront pas propagées à travers le gestionnaire parce que le mandataire n'a aucun moyen de savoir quand les valeurs contenues sont modifiées. Cependant, stocker une valeur dans un conteneur mandataire (qui déclenche un appel à @code{__setitem__} sur le mandataire) propage bien la modification à travers le gestionnaire et modifie effectivement l'élément, il est ainsi possible de réassigner la valeur modifiée au conteneur mandataire :

@example
# create a list proxy and append a mutable object (a dictionary)
lproxy = manager.list()
lproxy.append(@{@})
# now mutate the dictionary
d = lproxy[0]
d['a'] = 1
d['b'] = 2
# at this point, the changes to d are not yet synced, but by
# updating the dictionary, the proxy is notified of the change
lproxy[0] = d
@end example

Cette approche est peut-être moins pratique que d'utiliser des @ref{ca7,,Objets mandataires} imbriqués pour la majorité des cas d'utilisation, mais démontre aussi un certain niveau de contrôle sur la synchronisation.

@cartouche
@quotation Note 
Les types de mandataires de @ref{93,,multiprocessing} n'implémentent rien pour la comparaison par valeurs. Par exemple, on a :

@example
>>> manager.list([1,2,3]) == [1,2,3]
False
@end example

Il faut à la place simplement utiliser une copie du référent pour faire les comparaisons.
@end quotation
@end cartouche

@geindex BaseProxy (classe dans multiprocessing.managers)
@anchor{library/multiprocessing multiprocessing managers BaseProxy}@anchor{30e2}
@deffn {Classe} multiprocessing.managers.BaseProxy

Les objets mandataires sont des instances de sous-classes de @ref{30e2,,BaseProxy}.

@geindex _callmethod() (méthode multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy _callmethod}@anchor{30e3}
@deffn {Méthode} _callmethod (methodname[, args[, kwds]])

Appelle et renvoie le résultat d'une méthode du référent du mandataire.

Si @code{proxy} est un mandataire sont le référent est @code{obj}, alors l'expression

@example
proxy._callmethod(methodname, args, kwds)
@end example

s'évalue comme

@example
getattr(obj, methodname)(*args, **kwds)
@end example

dans le processus du gestionnaire.

La valeur renvoyée sera une copie du résultat de l'appel ou un mandataire sur un nouvel objet partagé – voir l'a documentation de l'argument `method_to_typeid' de @ref{30e1,,BaseManager.register()}.

Si une exception est levée par l'appel, elle est relayée par @ref{30e3,,_callmethod()}. Si une autre exception est levée par le processus du gestionnaire, elle est convertie en une @code{RemoteError} et est levée par @ref{30e3,,_callmethod()}.

Notez en particulier qu'une exception est levée si `methodname' n'est pas `exposée'.

Un exemple d'utilisation de @ref{30e3,,_callmethod()} :

@example
>>> l = manager.list(range(10))
>>> l._callmethod('__len__')
10
>>> l._callmethod('__getitem__', (slice(2, 7),)) # equivalent to l[2:7]
[2, 3, 4, 5, 6]
>>> l._callmethod('__getitem__', (20,))          # equivalent to l[20]
Traceback (most recent call last):
...
IndexError: list index out of range
@end example
@end deffn

@geindex _getvalue() (méthode multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy _getvalue}@anchor{30f3}
@deffn {Méthode} _getvalue ()

Renvoie une copie du référent.

Si le référent n'est pas sérialisable, une exception est levée.
@end deffn

@geindex __repr__() (méthode multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy __repr__}@anchor{30f4}
@deffn {Méthode} __repr__ ()

Renvoie la représentation de l'objet mandataire.
@end deffn

@geindex __str__() (méthode multiprocessing.managers.BaseProxy)
@anchor{library/multiprocessing multiprocessing managers BaseProxy __str__}@anchor{30f5}
@deffn {Méthode} __str__ ()

Renvoie la représentation du référent.
@end deffn
@end deffn

@menu
* Nettoyage: Nettoyage<2>. 

@end menu

@node Nettoyage<2>,,,Objets mandataires
@anchor{library/multiprocessing cleanup}@anchor{30f6}
@subsubsection Nettoyage


Un mandataire utilise un `callback' sous une référence faible de façon à ce que quand il est collecté par le ramasse-miettes, il se désenregistre auprès du gestionnaire qui possède le référent.

Un objet partagé est supprimé par le processus gestionnaire quand plus aucun mandataire ne le référence.

@node Pools de processus,Auditeurs et Clients,Objets mandataires,Référence
@anchor{library/multiprocessing module-multiprocessing pool}@anchor{97}@anchor{library/multiprocessing process-pools}@anchor{30f7}
@subsubsection Pools de processus


@geindex module; multiprocessing.pool

On peut créer un pool de processus qui exécuteront les tâches qui lui seront soumises avec la classe @ref{f56,,Pool}.

@geindex Pool (classe dans multiprocessing.pool)
@anchor{library/multiprocessing multiprocessing pool Pool}@anchor{f56}
@deffn {Classe} multiprocessing.pool.Pool ([processes[, initializer[, initargs[, maxtasksperchild[, context]]]]])

Un objet `process pool' qui contrôle un pool de processus `workers' auquel sont soumises des tâches. Il supporte les résultats asynchrones avec des `timeouts' et des `callbacks'  et possède une implémentation parallèle de `map'.

`processes' is the number of worker processes to use.  If `processes' is
@code{None} then the number returned by @ref{1bf,,os.process_cpu_count()} is used.

Si `initializer' n'est pas @code{None}, chaque processus `worker' appellera @code{initializer(*initargs)} en démarrant.

`maxtasksperchild' est le nombre de tâches qu'un processus `worker' peut accomplir avant de se fermer et d'être remplacé par un `worker' frais, pour permettre aux ressources inutilisées d'être libérées. Par défaut `maxtasksperchild' est @code{None}, ce qui signifie que le `worker' vit aussi longtemps que le pool.

`context' peut être utilisé pour préciser le contexte utilisé pour démarrer les processus `workers'. Habituellement un pool est créé à l'aide de la fonction @code{multiprocessing.Pool()} ou de la méthode @ref{f56,,Pool()} d'un objet de contexte. Dans les deux cas `context' est réglé de façon appropriée.

Notez que les méthodes de l'objet `pool' ne doivent être appelées que par le processus qui l'a créé.

@cartouche
@quotation Avertissement 
Les objets @ref{97,,multiprocessing.pool} ont des ressources internes qui doivent être correctement gérées (comme toute autre ressource) en utilisant le pool comme gestionnaire de contexte ou en appelant @ref{30f8,,close()} et @ref{30f9,,terminate()} manuellement. Si cela n'est pas fait, le processus peut être bloqué à la finalisation.

Notez qu'il n'est `pas' correct de compter sur le ramasse-miette pour détruire le pool car CPython ne garantit pas que le `finalizer' du pool est appelé (voir @ref{1ee3,,object.__del__()} pour plus d'informations).
@end quotation
@end cartouche


Modifié dans la version 3.2: Added the `maxtasksperchild' parameter.



Modifié dans la version 3.4: Added the `context' parameter.



Modifié dans la version 3.13: `processes' uses @ref{1bf,,os.process_cpu_count()} by default, instead of
@ref{1c0,,os.cpu_count()}.


@cartouche
@quotation Note 
Les processus `workers' à l'intérieur d'une @ref{f56,,Pool} vivent par défaut aussi longtemps que la file de travail du pool. Un modèle fréquent chez d'autres systèmes (tels qu'Apache, `mod_wsgi', etc.) pour libérer les ressources détenues par les `workers' est d'autoriser un `worker' dans le pool à accomplir seulement une certaine charge de travail avant de se fermer, se retrouvant nettoyé et remplacé par un nouveau processus fraîchement lancé. L'argument `maxtasksperchild' de @ref{f56,,Pool} expose cette fonctionnalité à l'utilisateur final.
@end quotation
@end cartouche

@geindex apply() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool apply}@anchor{30fa}
@deffn {Méthode} apply (func[, args[, kwds]])

Appelle `func' avec les arguments `args' et les arguments nommés `kwds'. Bloque jusqu'à ce que que le résultat soit prêt. En raison de ce blocage, @ref{30fb,,apply_async()} est préférable pour exécuter du travail en parallèle. De plus, `func' est exécutée sur un seul des `workers' du pool.
@end deffn

@geindex apply_async() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool apply_async}@anchor{30fb}
@deffn {Méthode} apply_async (func[, args[, kwds[, callback[, error_callback]]]])

Une variante de la méthode @ref{30fa,,apply()} qui renvoie un objet @ref{30fc,,AsyncResult}.

Si `callback' est précisé alors ce doit être un objet appelable qui accepte un seul argument. Quand le résultat est prêt, `callback' est appelé avec ce résultat, si l'appel n'échoue pas auquel cas `error_callback' est appelé à la place.

Si `error_callback' est précisé alors ce doit être un objet appelable qui accepte un seul argument. Si la fonction cible échoue, alors `error_callback' est appelé avec l'instance de l'exception.

Les `callbacks' doivent se terminer immédiatement, autrement le fil d'exécution qui gère les résultats se retrouverait bloqué.
@end deffn

@geindex map() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool map}@anchor{10c6}
@deffn {Méthode} map (func, iterable[, chunksize])

Un équivalent parallèle de la fonction native @ref{84e,,map()} (qui ne prend qu'un seul argument `itérable' ; pour en passer plusieurs, référez-vous à @ref{10c3,,starmap()}). Elle bloque jusqu'à ce que le résultat soit prêt.

La méthode découpe l'itérable en un nombre de morceaux qu'elle envoie au pool de processus comme des tâches séparées. La taille (approximative) de ces morceaux peut être précisée en passant à `chunksize' un entier positif.

Notez que cela peut entraîner une grosse consommation de mémoire pour les itérables très longs. Envisagez d'utiliser @ref{30fd,,imap()} ou @ref{30fe,,imap_unordered()} avec l'option `chunksize' explicite pour une meilleure efficacité.
@end deffn

@geindex map_async() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool map_async}@anchor{10c7}
@deffn {Méthode} map_async (func, iterable[, chunksize[, callback[, error_callback]]])

Une variante de la méthode @ref{10c6,,map()} qui renvoie un objet @ref{30fc,,AsyncResult}.

Si `callback' est précisé alors ce doit être un objet appelable qui accepte un seul argument. Quand le résultat est prêt, `callback' est appelé avec ce résultat, si l'appel n'échoue pas auquel cas `error_callback' est appelé à la place.

Si `error_callback' est précisé alors ce doit être un objet appelable qui accepte un seul argument. Si la fonction cible échoue, alors `error_callback' est appelé avec l'instance de l'exception.

Les `callbacks' doivent se terminer immédiatement, autrement le fil d'exécution qui gère les résultats se retrouverait bloqué.
@end deffn

@geindex imap() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool imap}@anchor{30fd}
@deffn {Méthode} imap (func, iterable[, chunksize])

Une version paresseuse de @ref{10c6,,map()}.

L'argument `chunksize' est le même que celui utilisé par la méthode @ref{10c6,,map()}. Pour de très longs itérables, utiliser une grande valeur pour `chunksize' peut faire s'exécuter la tâche `beaucoup' plus rapidement qu'en utilisant la valeur par défaut de @code{1}.

Aussi, si `chucksize' vaut @code{1} alors la méthode @code{next()} de l'itérateur renvoyé par @ref{30fd,,imap()} prend un paramètre optionnel `timeout' : @code{next(timeout)} lève une @ref{30aa,,multiprocessing.TimeoutError} si le résultat ne peut pas être renvoyé avant `timeout' secondes.
@end deffn

@geindex imap_unordered() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool imap_unordered}@anchor{30fe}
@deffn {Méthode} imap_unordered (func, iterable[, chunksize])

Identique à @ref{30fd,,imap()} si ce n'est que l'ordre des résultats de l'itérateur renvoyé doit être considéré comme arbitraire. (L'ordre n'est garanti que quand il n'y a qu'un `worker'.)
@end deffn

@geindex starmap() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool starmap}@anchor{10c3}
@deffn {Méthode} starmap (func, iterable[, chunksize])

Like @ref{10c6,,map()} except that the
elements of the `iterable' are expected to be iterables that are
unpacked as arguments.

Par conséquent un `iterable' @code{[(1,2), (3, 4)]} donnera pour résultat @code{[func(1,2), func(3,4)]}.


Ajouté dans la version 3.3.

@end deffn

@geindex starmap_async() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool starmap_async}@anchor{10c4}
@deffn {Méthode} starmap_async (func, iterable[, chunksize[, callback[, error_callback]]])

Une combinaison de @ref{10c3,,starmap()} et @ref{10c7,,map_async()} qui itère sur `iterable' (composé d'itérables) et appelle `func' pour chaque itérable dépaqueté. Renvoie l'objet résultat.


Ajouté dans la version 3.3.

@end deffn

@geindex close() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool close}@anchor{30f8}
@deffn {Méthode} close ()

Empêche de nouvelles tâches d'être envoyées à la `pool'. Les processus `workers' se terminent une fois que toutes les tâches ont été complétées.
@end deffn

@geindex terminate() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool terminate}@anchor{30f9}
@deffn {Méthode} terminate ()

Stoppe immédiatement les processus `workers' sans finaliser les travaux courants. Quand l'objet `pool' est collecté par le ramasse-miettes, sa méthode @ref{30f9,,terminate()} est appelée immédiatement.
@end deffn

@geindex join() (méthode multiprocessing.pool.Pool)
@anchor{library/multiprocessing multiprocessing pool Pool join}@anchor{30ff}
@deffn {Méthode} join ()

Attend que les processus `workers' se terminent. Il est nécessaire d'appeler @ref{30f8,,close()} ou @ref{30f9,,terminate()} avant d'utiliser @ref{30ff,,join()}.
@end deffn


Modifié dans la version 3.3: Les pools de `workers' supportent maintenant le protocole des gestionnaires de contexte – voir @ref{1f42,,Le type gestionnaire de contexte}. @ref{21d0,,__enter__()} renvoie l'objet `pool' et @ref{21d1,,__exit__()} appelle @ref{30f9,,terminate()}.

@end deffn

@geindex AsyncResult (classe dans multiprocessing.pool)
@anchor{library/multiprocessing multiprocessing pool AsyncResult}@anchor{30fc}
@deffn {Classe} multiprocessing.pool.AsyncResult

La classe des résultats renvoyés par @ref{30fb,,Pool.apply_async()} et @ref{10c7,,Pool.map_async()}.

@geindex get() (méthode multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult get}@anchor{3100}
@deffn {Méthode} get ([timeout])

Renvoie le résultat quand il arrive. Si `timeout' n'est pas @code{None} et que le résultat n'arrive pas avant `timeout' secondes, une @ref{30aa,,multiprocessing.TimeoutError} est levée. Si l'appel distance lève une exception, alors elle est relayée par @ref{3100,,get()}.
@end deffn

@geindex wait() (méthode multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult wait}@anchor{3101}
@deffn {Méthode} wait ([timeout])

Attend que le résultat soit disponible ou que `timeout' secondes s'écoulent.
@end deffn

@geindex ready() (méthode multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult ready}@anchor{3102}
@deffn {Méthode} ready ()

Renvoie @code{True} ou @code{False} suivant si la tâche est accomplie.
@end deffn

@geindex successful() (méthode multiprocessing.pool.AsyncResult)
@anchor{library/multiprocessing multiprocessing pool AsyncResult successful}@anchor{3103}
@deffn {Méthode} successful ()

Renvoie @code{True} ou @code{False} suivant si la tâche est accomplie sans lever d'exception. Lève une @ref{1ff,,ValueError} si le résultat n'est pas prêt.


Modifié dans la version 3.7: Si le résultat n'est pas prêt, une @ref{1ff,,ValueError} est levée au lieu d'une @ref{694,,AssertionError} auparavant.

@end deffn
@end deffn

Les exemples suivants présentent l'utilisation d'un pool de `workers' :

@example
from multiprocessing import Pool
import time

def f(x):
    return x*x

if __name__ == '__main__':
    with Pool(processes=4) as pool:         # start 4 worker processes
        result = pool.apply_async(f, (10,)) # evaluate "f(10)" asynchronously in a single process
        print(result.get(timeout=1))        # prints "100" unless your computer is *very* slow

        print(pool.map(f, range(10)))       # prints "[0, 1, 4,..., 81]"

        it = pool.imap(f, range(10))
        print(next(it))                     # prints "0"
        print(next(it))                     # prints "1"
        print(it.next(timeout=1))           # prints "4" unless your computer is *very* slow

        result = pool.apply_async(time.sleep, (10,))
        print(result.get(timeout=1))        # raises multiprocessing.TimeoutError
@end example

@node Auditeurs et Clients,Clés d'authentification,Pools de processus,Référence
@anchor{library/multiprocessing listeners-and-clients}@anchor{3104}@anchor{library/multiprocessing module-multiprocessing connection}@anchor{94}@anchor{library/multiprocessing multiprocessing-listeners-clients}@anchor{30c3}
@subsubsection Auditeurs et Clients


@geindex module; multiprocessing.connection

Habituellement l'échange de messages entre processus est réalisé en utilisant des files ou des objets @ref{1633,,Connection} renvoyés par @ref{3091,,Pipe()}.

Cependant, le module @ref{94,,multiprocessing.connection} permet un peu plus de flexibilité. Il fournit un message de plus haut-niveau orienté API pour gérer  des connecteurs ou des tubes nommés sous Windows. Il gère aussi l'authentification par condensat (`digest authentication' en anglais) en utilisant le module @ref{69,,hmac}, et pour interroger de multiples connexions en même temps.

@geindex deliver_challenge() (dans le module multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection deliver_challenge}@anchor{3105}
@deffn {Fonction} multiprocessing.connection.deliver_challenge (connection, authkey)

Envoie un message généré aléatoirement à l'autre extrémité de la connexion et attend une réponse.

Si la réponse correspond au condensat du message avec la clé `authkey', alors un message de bienvenue est envoyé à l'autre extrémité de la connexion. Autrement, une @ref{30a9,,AuthenticationError} est levée.
@end deffn

@geindex answer_challenge() (dans le module multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection answer_challenge}@anchor{3106}
@deffn {Fonction} multiprocessing.connection.answer_challenge (connection, authkey)

Reçoit un message, calcule le condensat du message en utilisant la clé `authkey', et envoie le condensat en réponse.

Si un message de bienvenue n'est pas reçu, une @ref{30a9,,AuthenticationError} est levée.
@end deffn

@geindex Client() (dans le module multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection Client}@anchor{3107}
@deffn {Fonction} multiprocessing.connection.Client (address[, family[, authkey]])

Essaie d'établir une connexion avec l'auditeur qui utilise l'adresse `address', renvoie une @ref{1633,,Connection}.

Le type de la connexion est déterminé par l'argument `family', mais il peut généralement être omis puisqu'il peut être inféré depuis le format d'`address'. (Voir @ref{3108,,Formats d'adresses})

If `authkey' is given and not @code{None}, it should be a byte string and will be
used as the secret key for an HMAC-based authentication challenge. No
authentication is done if `authkey' is @code{None}.
@ref{30a9,,AuthenticationError} is raised if authentication fails.
See @ref{30a5,,Clés d'authentification}.
@end deffn

@geindex Listener (classe dans multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection Listener}@anchor{1632}
@deffn {Classe} multiprocessing.connection.Listener ([address[, family[, backlog[, authkey]]]])

Une enveloppe autour d'un connecteur lié ou un tube nommé sous Windows qui écoute pour des connexions.

`address' est l'adresse à utiliser par le connecteur lié ou le tube nommé de l'objet auditeur.

@cartouche
@quotation Note 
Si une adresse '0.0.0.0' est utilisée, l'adresse ne sera pas un point d'accès connectable sous Windows. Si vous avez besoin d'un point d'accès connectable, utilisez '127.0.0.1'.
@end quotation
@end cartouche

`family' est le type de connecteur (ou tube nommé) à utiliser. Cela peut être l'une des chaînes @code{'AF_INET'} (pour un connecteur TCP), @code{'AF_UNIX'} (pour un connecteur Unix) ou @code{'AF_PIPE'} (pour un tube nommé sous Windows). Seulement le premier d'entre eux est garanti d'être disponible. Si `family' est @code{None}, la famille est inférée depuis le format d'`address'. Si `address' est aussi @code{None}, la famille par défaut est utilisée. La famille par défaut est supposée être la plus rapide disponible. Voir @ref{3108,,Formats d'adresses}. Notez que si la `family' est @code{'AF_UNIX'} et qu'`address' est @code{None}, le connecteur est créé dans un répertoire temporaire privé créé avec @ref{27cd,,tempfile.mkstemp()}.

Si l'objet auditeur utilise un connecteur alors `backlog' (1 par défaut) est passé à la méthode @ref{e47,,listen()} du connecteur une fois qu'il a été lié.

If `authkey' is given and not @code{None}, it should be a byte string and will be
used as the secret key for an HMAC-based authentication challenge. No
authentication is done if `authkey' is @code{None}.
@ref{30a9,,AuthenticationError} is raised if authentication fails.
See @ref{30a5,,Clés d'authentification}.

@geindex accept() (méthode multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener accept}@anchor{15e9}
@deffn {Méthode} accept ()

Accepte une connexion sur le connecteur lié ou le tube nommé de l'objet auditeur et renvoie un objet @ref{1633,,Connection}. Si la tentative d'authentification échoue, une @ref{30a9,,AuthenticationError} est levée.
@end deffn

@geindex close() (méthode multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener close}@anchor{3109}
@deffn {Méthode} close ()

Ferme le connecteur lié ou le tube nommé de l'objet auditeur. La méthode est appelée automatiquement quand l'auditeur est collecté par le ramasse-miettes. Il est cependant conseillé de l'appeler explicitement.
@end deffn

Les objets auditeurs ont aussi les propriétés en lecture seule suivantes :

@geindex address (attribut multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener address}@anchor{310a}
@deffn {Attribut} address

L'adresse utilisée par l'objet auditeur.
@end deffn

@geindex last_accepted (attribut multiprocessing.connection.Listener)
@anchor{library/multiprocessing multiprocessing connection Listener last_accepted}@anchor{310b}
@deffn {Attribut} last_accepted

L'adresse depuis laquelle a été établie la dernière connexion. @code{None} si aucune n'est disponible.
@end deffn


Modifié dans la version 3.3: Les objets auditeurs supportent maintenant le protocole des gestionnaires de contexte – voir @ref{1f42,,Le type gestionnaire de contexte}. @ref{21d0,,__enter__()} renvoie l'objet auditeur, et @ref{21d1,,__exit__()} appelle @ref{3109,,close()}.

@end deffn

@geindex wait() (dans le module multiprocessing.connection)
@anchor{library/multiprocessing multiprocessing connection wait}@anchor{10c1}
@deffn {Fonction} multiprocessing.connection.wait (object_list, timeout=None)

Attend qu'un objet d'`object_list' soit prêt. Renvoie la liste de ces objets d'`object_list' qui sont prêts. Si `timeout' est un nombre flottant, l'appel bloquera au maximum ce nombre de secondes. Si `timeout' est @code{None}, l'appelle bloquera pour une durée non limitée. Un `timeout' négatif est équivalent à un `timeout' nul.

For both POSIX and Windows, an object can appear in `object_list' if
it is


@itemize *

@item 
un objet @ref{1633,,Connection} accessible en lecture ;

@item 
un objet @ref{d8e,,socket.socket} connecté et accessible en lecture ; ou

@item 
l'attribut @ref{10c2,,sentinel} d'un objet @ref{b47,,Process}.
@end itemize

Une connexion (`socket' en anglais) est prête quand il y a des données disponibles en lecture dessus, ou que l'autre extrémité a été fermée.

`POSIX': @code{wait(object_list, timeout)} almost equivalent
@code{select.select(object_list, [], [], timeout)}.  The difference is
that, if @ref{d8d,,select.select()} is interrupted by a signal, it can
raise @ref{40d,,OSError} with an error number of @code{EINTR}, whereas
@ref{10c1,,wait()} will not.

`Windows': An item in `object_list' must either be an integer
handle which is waitable (according to the definition used by the
documentation of the Win32 function @code{WaitForMultipleObjects()})
or it can be an object with a @ref{27cf,,fileno()} method which returns a
socket handle or pipe handle.  (Note that pipe handles and socket
handles are `not' waitable handles.)


Ajouté dans la version 3.3.

@end deffn

`Exemples'

Le code serveur suivant crée un auditeur qui utilise @code{'secret password'} comme clé d'authentification. Il attend ensuite une connexion et envoie les données au client :

@example
from multiprocessing.connection import Listener
from array import array

address = ('localhost', 6000)     # family is deduced to be 'AF_INET'

with Listener(address, authkey=b'secret password') as listener:
    with listener.accept() as conn:
        print('connection accepted from', listener.last_accepted)

        conn.send([2.25, None, 'junk', float])

        conn.send_bytes(b'hello')

        conn.send_bytes(array('i', [42, 1729]))
@end example

Le code suivant se connecte au serveur et en reçoit des données :

@example
from multiprocessing.connection import Client
from array import array

address = ('localhost', 6000)

with Client(address, authkey=b'secret password') as conn:
    print(conn.recv())                  # => [2.25, None, 'junk', float]

    print(conn.recv_bytes())            # => 'hello'

    arr = array('i', [0, 0, 0, 0, 0])
    print(conn.recv_bytes_into(arr))    # => 8
    print(arr)                          # => array('i', [42, 1729, 0, 0, 0])
@end example

Le code suivant utilise @ref{10c1,,wait()} pour attendre des messages depuis plusieurs processus à la fois :

@example
from multiprocessing import Process, Pipe, current_process
from multiprocessing.connection import wait

def foo(w):
    for i in range(10):
        w.send((i, current_process().name))
    w.close()

if __name__ == '__main__':
    readers = []

    for i in range(4):
        r, w = Pipe(duplex=False)
        readers.append(r)
        p = Process(target=foo, args=(w,))
        p.start()
        # We close the writable end of the pipe now to be sure that
        # p is the only process which owns a handle for it.  This
        # ensures that when p closes its handle for the writable end,
        # wait() will promptly report the readable end as being ready.
        w.close()

    while readers:
        for r in wait(readers):
            try:
                msg = r.recv()
            except EOFError:
                readers.remove(r)
            else:
                print(msg)
@end example

@menu
* Formats d'adresses:: 

@end menu

@node Formats d'adresses,,,Auditeurs et Clients
@anchor{library/multiprocessing address-formats}@anchor{310c}@anchor{library/multiprocessing multiprocessing-address-formats}@anchor{3108}
@subsubsection Formats d'adresses



@itemize *

@item 
une adresse @code{'AF_INET'} est une paire de la forme @code{(hostname, port)} où `hostname' est une chaîne et `port' un entier ;

@item 
une adresse @code{'AF_UNIX'} est une chaîne représentant un nom de fichier sur le système de fichiers ;

@item 
An @code{'AF_PIPE'} address is a string of the form
@code{r'\\.\pipe\@var{PipeName}'}.  To use @ref{3107,,Client()} to connect to a named
pipe on a remote computer called `ServerName' one should use an address of the
form @code{r'\\@var{ServerName}\pipe\@var{PipeName}'} instead.
@end itemize

Notez que toute chaîne commençant par deux antislashs est considérée par défaut comme l'adresse d'un @code{'AF_PIPE'} plutôt qu'une adresse @code{'AF_UNIX'}.

@node Clés d'authentification,Journalisation<2>,Auditeurs et Clients,Référence
@anchor{library/multiprocessing authentication-keys}@anchor{310d}@anchor{library/multiprocessing multiprocessing-auth-keys}@anchor{30a5}
@subsubsection Clés d'authentification


Quand @ref{30c5,,Connection.recv} est utilisée, les données reçues sont automatiquement désérialisées par `pickle'. Malheureusement désérialiser des données depuis une source non sûre constitue un risque de sécurité. Par conséquent @ref{1632,,Listener} et @ref{3107,,Client()} utilisent le module @ref{69,,hmac} pour fournir une authentification par condensat.

Une clé d'authentification est une chaîne d'octets qui peut être vue comme un mot de passe : quand une connexion est établie, les deux interlocuteurs vont demander à l'autre une preuve qu'il connaît la clé d'authentification. (Démontrer que les deux utilisent la même clé n'implique `pas' d'échanger la clé sur la connexion.)

Si l'authentification est requise et qu'aucune clé n'est spécifiée alors la valeur de retour de @code{current_process().authkey} est utilisée (voir @ref{b47,,Process}). Celle valeur est automatiquement héritée par tout objet @ref{b47,,Process} créé par le processus courant. Cela signifie que (par défaut) tous les processus d'un programme multi-processus partageront une clé d'authentification unique qui peut être utilisée pour mettre en place des connexions entre-eux.

Des clés d'authentification adaptées peuvent aussi être générées par @ref{50c,,os.urandom()}.

@node Journalisation<2>,Le module multiprocessing dummy,Clés d'authentification,Référence
@anchor{library/multiprocessing logging}@anchor{310e}
@subsubsection Journalisation


Un certain support de la journalisation est disponible. Notez cependant que le le paquet @ref{86,,logging} n'utilise pas de verrous partagés entre les processus et il est donc possible (dépendant du type de gestionnaire) que les messages de différents processus soient mélangés.

@geindex get_logger() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing get_logger}@anchor{310f}
@deffn {Fonction} multiprocessing.get_logger ()

Renvoie le journaliseur utilisé par @ref{93,,multiprocessing}. Si nécessaire, un nouveau sera créé.

When first created the logger has level @ref{2be9,,logging.NOTSET} and no
default handler. Messages sent to this logger will not by default propagate
to the root logger.

Notez que sous Windows les processus fils n'hériteront que du niveau du journaliseur du processus parent – toute autre personnalisation du journaliseur ne sera pas héritée.
@end deffn

@geindex log_to_stderr() (dans le module multiprocessing)
@anchor{library/multiprocessing multiprocessing log_to_stderr}@anchor{3110}
@deffn {Fonction} multiprocessing.log_to_stderr (level=None)

This function performs a call to @ref{310f,,get_logger()} but in addition to
returning the logger created by get_logger, it adds a handler which sends
output to @ref{926,,sys.stderr} using format
@code{'[%(levelname)s/%(processName)s] %(message)s'}.
You can modify @code{levelname} of the logger by passing a @code{level} argument.
@end deffn

L'exemple ci-dessous présente une session avec la journalisation activée :

@example
>>> import multiprocessing, logging
>>> logger = multiprocessing.log_to_stderr()
>>> logger.setLevel(logging.INFO)
>>> logger.warning('doomed')
[WARNING/MainProcess] doomed
>>> m = multiprocessing.Manager()
[INFO/SyncManager-...] child process calling self.run()
[INFO/SyncManager-...] created temp directory /.../pymp-...
[INFO/SyncManager-...] manager serving at '/.../listener-...'
>>> del m
[INFO/MainProcess] sending shutdown message to manager
[INFO/SyncManager-...] manager exiting with exitcode 0
@end example

Pour un tableau complet des niveaux de journalisation, voir le module @ref{86,,logging}.

@node Le module multiprocessing dummy,,Journalisation<2>,Référence
@anchor{library/multiprocessing module-multiprocessing dummy}@anchor{95}@anchor{library/multiprocessing the-multiprocessing-dummy-module}@anchor{3111}
@subsubsection Le module @code{multiprocessing.dummy}


@geindex module; multiprocessing.dummy

@ref{95,,multiprocessing.dummy} réplique toute l'API de @ref{93,,multiprocessing} mais n'est rien de plus qu'une interface autour du module @ref{ec,,threading}.

En particulier, la fonction @code{Pool} du module @ref{95,,multiprocessing.dummy} renvoie une instance de @ref{189e,,ThreadPool}, qui est une sous-classe de @ref{f56,,Pool}. Elle a la même interface, mais elle utilise un pool de fils d'exécution plutôt qu'un pool de processus.

@geindex ThreadPool (classe dans multiprocessing.pool)
@anchor{library/multiprocessing multiprocessing pool ThreadPool}@anchor{189e}
@deffn {Classe} multiprocessing.pool.ThreadPool ([processes[, initializer[, initargs]]])

Un objet qui contrôle un pool de fils d'exécution auquel des tâches peuvent être envoyées. L'interface des instances de @ref{189e,,ThreadPool} est entièrement compatible avec celle des instances de @ref{f56,,Pool}, et leur ressources doivent être aussi correctement gérées, soit en utilisant le pool avec un contexte, soit en appelant explicitement @ref{30f8,,close()} et @ref{30f9,,terminate()}.

`processes' is the number of worker threads to use.  If `processes' is
@code{None} then the number returned by @ref{1bf,,os.process_cpu_count()} is used.

Si `initializer' n'est pas @code{None}, chaque processus `worker' appellera @code{initializer(*initargs)} en démarrant.

À la différence de @ref{f56,,Pool}, `maxtasksperchild' et `context' ne peuvent pas être passés en arguments.

@cartouche
@quotation Note 
La classe @ref{189e,,ThreadPool} a la même interface que la classe @ref{f56,,Pool}, dont l'implémentation repose sur un pool de processus, et a été introduite avant le module @ref{21,,concurrent.futures}. Par conséquent elle implémente des opérations qui n'ont pas vraiment de sens pour un pool implémenté avec des fils d'exécution et possède son propre type pour représenter le statut de tâches asynchrones, @ref{30fc,,AsyncResult}, qui n'est pas géré par les autres modules.

Il est souvent plus judicieux d'utiliser @ref{72c,,concurrent.futures.ThreadPoolExecutor} qui a une interface plus simple, qui a été pensée dès l'origine pour les fils d'exécution et qui renvoie des instances de @ref{118f,,concurrent.futures.Future} qui sont compatibles avec de nombreux modules, dont @ref{a,,asyncio}.
@end quotation
@end cartouche
@end deffn

@node Lignes directrices de programmation,Exemples<14>,Référence,multiprocessing --- Process-based parallelism
@anchor{library/multiprocessing multiprocessing-programming}@anchor{308d}@anchor{library/multiprocessing programming-guidelines}@anchor{3112}
@subsubsection Lignes directrices de programmation


Il y a certaines lignes directrices et idiomes à respecter pour utiliser @ref{93,,multiprocessing}.

@menu
* Toutes les méthodes de démarrage:: 
* Les méthodes de démarrage spawn et forkserver:: 

@end menu

@node Toutes les méthodes de démarrage,Les méthodes de démarrage spawn et forkserver,,Lignes directrices de programmation
@anchor{library/multiprocessing all-start-methods}@anchor{3113}
@subsubsection Toutes les méthodes de démarrage


Les règles suivantes s'appliquent aux méthodes de démarrage.

Éviter les états partagés

@quotation

Autant que possible, il faut éviter de transférer de gros volumes de données entre les processus.

Il est souvent plus judicieux de se borner à utiliser des files et des tubes pour gérer la communication entre processus plutôt que d'utiliser des primitives de synchronisation plus bas-niveau.
@end quotation

Sérialisation

@quotation

Assurez-vous que les arguments passés aux méthodes des mandataires soient sérialisables (`pickables').
@end quotation

Sûreté des mandataires à travers les fils d'exécution

@quotation

N'utilisez pas d'objet mandataire depuis plus d'un fil d'exécution à moins que vous ne le protégiez avec un verrou.

Il n'y a jamais de problème à avoir plusieurs processus qui utilisent un `même' mandataire.
@end quotation

Attendre les processus zombies

@quotation

On POSIX when a process finishes but has not been joined it becomes a zombie.
There should never be very many because each time a new process starts (or
@ref{30be,,active_children()} is called) all completed processes
which have not yet been joined will be joined.  Also calling a finished
process's @ref{30a2,,Process.is_alive} will
join the process.  Even so it is probably good
practice to explicitly join all the processes that you start.
@end quotation

Mieux vaut hériter que sérialiser - désérialiser

@quotation

Quand vous utilisez les méthodes de démarrage `spawn' ou `forkserver', de nombreux types de @ref{93,,multiprocessing} nécessitent d'être sérialisés pour que les processus fils puissent les utiliser. Cependant, il faut généralement éviter d'envoyer des objets partagés aux autres processus en utilisant des tubes ou des files. Vous devez plutôt vous arranger pour qu'un processus qui nécessite l'accès à une ressource partagée créée autre part qu'il en hérite depuis un de ses processus ancêtres.
@end quotation

Éviter de terminer les processus

@quotation

Utiliser la méthode @ref{30a6,,Process.terminate} pour stopper un processus risque de casser ou de rendre indisponible aux autres processus des ressources partagées (comme des verrous, sémaphores, tubes et files) actuellement utilisées par le processus.

Il est donc préférable de n'utiliser @ref{30a6,,Process.terminate} que sur les processus qui n'utilisent jamais de ressources partagées.
@end quotation

Attendre les processus qui utilisent des files

@quotation

Gardez à l'esprit qu'un processus qui a placé des éléments dans une file attend que tous les éléments mis en tampon soient consommés par le fil d'exécution « chargeur » du tube sous-jacent avant de se terminer (le processus fils peut appeler la méthode @ref{30b4,,Queue.cancel_join_thread} de la queue pour éviter ce comportement).

Cela signifie que chaque fois que vous utilisez une file, vous devez vous assurer que tous les éléments qui y ont été placés ont été effectivement supprimés avant que le processus ne soit attendu. Autrement vous ne pouvez pas être sûr que les processus qui ont placé des éléments dans la file se termineront. Souvenez-vous aussi que tous les processus non `daemons' sont attendus automatiquement.

L'exemple suivant provoque un interblocage :

@example
from multiprocessing import Process, Queue

def f(q):
    q.put('X' * 1000000)

if __name__ == '__main__':
    queue = Queue()
    p = Process(target=f, args=(queue,))
    p.start()
    p.join()                    # this deadlocks
    obj = queue.get()
@end example

Une solution ici consiste à intervertir les deux dernières lignes (ou simplement à supprimer la ligne @code{p.join()}).
@end quotation

Passer explicitement les ressources aux processus fils

@quotation

On POSIX using the `fork' start method, a child process can make
use of a shared resource created in a parent process using a
global resource.  However, it is better to pass the object as an
argument to the constructor for the child process.

En plus de rendre le code (potentiellement) compatible avec Windows et les autres méthodes de démarrage, cela assure aussi que tant que le processus fils est en vie, l'objet ne sera pas collecté par le ramasse-miettes du processus parent. Cela peut être important si certaines ressources sont libérées quand l'objet est collecté par le ramasse-miettes du processus parent.

Donc par exemple

@example
from multiprocessing import Process, Lock

def f():
    ... do something using "lock" ...

if __name__ == '__main__':
    lock = Lock()
    for i in range(10):
        Process(target=f).start()
@end example

devrait être réécrit comme

@example
from multiprocessing import Process, Lock

def f(l):
    ... do something using "l" ...

if __name__ == '__main__':
    lock = Lock()
    for i in range(10):
        Process(target=f, args=(lock,)).start()
@end example
@end quotation

Faire attention à remplacer @ref{527,,sys.stdin} par un objet simili-fichier

@quotation

À l'origine, @ref{93,,multiprocessing} appelait inconditionnellement :

@example
os.close(sys.stdin.fileno())
@end example

dans la méthode @code{multiprocessing.Process._bootstrap()} — cela provoquait des problèmes avec les processus imbriqués. Cela peut être changé en :

@example
sys.stdin.close()
sys.stdin = open(os.open(os.devnull, os.O_RDONLY), closefd=False)
@end example

Which solves the fundamental issue of processes colliding with each other
resulting in a bad file descriptor error, but introduces a potential danger
to applications which replace @ref{527,,sys.stdin()} with a "file-like object"
with output buffering.  This danger is that if multiple processes call
@ref{1f3,,close()} on this file-like object, it could result in the same
data being flushed to the object multiple times, resulting in corruption.

Si vous écrivez un objet simili-fichier et implémentez votre propre cache, vous pouvez le rendre sûr pour les `forks' en stockant le `pid' chaque fois que vous ajoutez des données au cache, et annulez le cache quand le `pid' change. Par exemple :

@example
@@property
def cache(self):
    pid = os.getpid()
    if pid != self._pid:
        self._pid = pid
        self._cache = []
    return self._cache
@end example

Pour plus d'informations, voir bpo-5155@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5155}, bpo-5313@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5313} et bpo-5331@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=5331}
@end quotation

@node Les méthodes de démarrage spawn et forkserver,,Toutes les méthodes de démarrage,Lignes directrices de programmation
@anchor{library/multiprocessing the-spawn-and-forkserver-start-methods}@anchor{3114}
@subsubsection Les méthodes de démarrage `spawn' et `forkserver'


There are a few extra restrictions which don't apply to the `fork'
start method.

Contraintes supplémentaires sur la sérialisation

@quotation

Assurez-vous que tous les argument de @code{Process.__init__()} sont sérialisables avec `pickle'. Aussi, si vous héritez de @ref{b47,,Process}, assurez-vous que toutes les instances sont sérialisables quand la méthode @ref{308c,,Process.start} est appelée.
@end quotation

Variables globales

@quotation

Gardez en tête que si le code exécuté dans un processus fils essaie d'accéder à une variable globale, alors la valeur qu'il voit (s'il y en a une) pourrait ne pas être la même que la valeur du processus parent au moment même où @ref{308c,,Process.start} est appelée.

Cependant, les variables globales qui sont juste des constantes de modules ne posent pas de problèmes.
@end quotation
@anchor{library/multiprocessing multiprocessing-safe-main-import}@anchor{3115}
Importation sécurisée du module principal

@quotation

Make sure that the main module can be safely imported by a new Python
interpreter without causing unintended side effects (such as starting a new
process).

Par exemple, utiliser la méthode de démarrage `spawn' ou `forkserver' pour lancer le module suivant échouerait avec une @ref{193,,RuntimeError} :

@example
from multiprocessing import Process

def foo():
    print('hello')

p = Process(target=foo)
p.start()
@end example

Vous devriez plutôt protéger le « point d'entrée » du programme en utilisant @code{if __name__ == '__main__':} comme suit :

@example
from multiprocessing import Process, freeze_support, set_start_method

def foo():
    print('hello')

if __name__ == '__main__':
    freeze_support()
    set_start_method('spawn')
    p = Process(target=foo)
    p.start()
@end example

(La ligne @code{freeze_support()} peut être omise si le programme est uniquement lancé normalement et pas figé.)

Cela permet aux interpréteurs Python fraîchement instanciés d'importer en toute sécurité le module et d'exécution ensuite la fonction @code{foo()}.

Des restrictions similaires s'appliquent si un pool ou un gestionnaire est créé dans le module principal.
@end quotation

@node Exemples<14>,,Lignes directrices de programmation,multiprocessing --- Process-based parallelism
@anchor{library/multiprocessing examples}@anchor{3116}@anchor{library/multiprocessing multiprocessing-examples}@anchor{30b5}
@subsubsection Exemples


Démonstration de comment créer et utiliser des gestionnaires et mandataires personnalisés :

@example
from multiprocessing import freeze_support
from multiprocessing.managers import BaseManager, BaseProxy
import operator

##

class Foo:
    def f(self):
        print('you called Foo.f()')
    def g(self):
        print('you called Foo.g()')
    def _h(self):
        print('you called Foo._h()')

# A simple generator function
def baz():
    for i in range(10):
        yield i*i

# Proxy type for generator objects
class GeneratorProxy(BaseProxy):
    _exposed_ = ['__next__']
    def __iter__(self):
        return self
    def __next__(self):
        return self._callmethod('__next__')

# Function to return the operator module
def get_operator_module():
    return operator

##

class MyManager(BaseManager):
    pass

# register the Foo class; make `f()` and `g()` accessible via proxy
MyManager.register('Foo1', Foo)

# register the Foo class; make `g()` and `_h()` accessible via proxy
MyManager.register('Foo2', Foo, exposed=('g', '_h'))

# register the generator function baz; use `GeneratorProxy` to make proxies
MyManager.register('baz', baz, proxytype=GeneratorProxy)

# register get_operator_module(); make public functions accessible via proxy
MyManager.register('operator', get_operator_module)

##

def test():
    manager = MyManager()
    manager.start()

    print('-' * 20)

    f1 = manager.Foo1()
    f1.f()
    f1.g()
    assert not hasattr(f1, '_h')
    assert sorted(f1._exposed_) == sorted(['f', 'g'])

    print('-' * 20)

    f2 = manager.Foo2()
    f2.g()
    f2._h()
    assert not hasattr(f2, 'f')
    assert sorted(f2._exposed_) == sorted(['g', '_h'])

    print('-' * 20)

    it = manager.baz()
    for i in it:
        print('<%d>' % i, end=' ')
    print()

    print('-' * 20)

    op = manager.operator()
    print('op.add(23, 45) =', op.add(23, 45))
    print('op.pow(2, 94) =', op.pow(2, 94))
    print('op._exposed_ =', op._exposed_)

##

if __name__ == '__main__':
    freeze_support()
    test()
@end example

En utilisant @ref{f56,,Pool} :

@example
import multiprocessing
import time
import random
import sys

#
# Functions used by test code
#

def calculate(func, args):
    result = func(*args)
    return '%s says that %s%s = %s' % (
        multiprocessing.current_process().name,
        func.__name__, args, result
        )

def calculatestar(args):
    return calculate(*args)

def mul(a, b):
    time.sleep(0.5 * random.random())
    return a * b

def plus(a, b):
    time.sleep(0.5 * random.random())
    return a + b

def f(x):
    return 1.0 / (x - 5.0)

def pow3(x):
    return x ** 3

def noop(x):
    pass

#
# Test code
#

def test():
    PROCESSES = 4
    print('Creating pool with %d processes\n' % PROCESSES)

    with multiprocessing.Pool(PROCESSES) as pool:
        #
        # Tests
        #

        TASKS = [(mul, (i, 7)) for i in range(10)] + \
                [(plus, (i, 8)) for i in range(10)]

        results = [pool.apply_async(calculate, t) for t in TASKS]
        imap_it = pool.imap(calculatestar, TASKS)
        imap_unordered_it = pool.imap_unordered(calculatestar, TASKS)

        print('Ordered results using pool.apply_async():')
        for r in results:
            print('\t', r.get())
        print()

        print('Ordered results using pool.imap():')
        for x in imap_it:
            print('\t', x)
        print()

        print('Unordered results using pool.imap_unordered():')
        for x in imap_unordered_it:
            print('\t', x)
        print()

        print('Ordered results using pool.map() --- will block till complete:')
        for x in pool.map(calculatestar, TASKS):
            print('\t', x)
        print()

        #
        # Test error handling
        #

        print('Testing error handling:')

        try:
            print(pool.apply(f, (5,)))
        except ZeroDivisionError:
            print('\tGot ZeroDivisionError as expected from pool.apply()')
        else:
            raise AssertionError('expected ZeroDivisionError')

        try:
            print(pool.map(f, list(range(10))))
        except ZeroDivisionError:
            print('\tGot ZeroDivisionError as expected from pool.map()')
        else:
            raise AssertionError('expected ZeroDivisionError')

        try:
            print(list(pool.imap(f, list(range(10)))))
        except ZeroDivisionError:
            print('\tGot ZeroDivisionError as expected from list(pool.imap())')
        else:
            raise AssertionError('expected ZeroDivisionError')

        it = pool.imap(f, list(range(10)))
        for i in range(10):
            try:
                x = next(it)
            except ZeroDivisionError:
                if i == 5:
                    pass
            except StopIteration:
                break
            else:
                if i == 5:
                    raise AssertionError('expected ZeroDivisionError')

        assert i == 9
        print('\tGot ZeroDivisionError as expected from IMapIterator.next()')
        print()

        #
        # Testing timeouts
        #

        print('Testing ApplyResult.get() with timeout:', end=' ')
        res = pool.apply_async(calculate, TASKS[0])
        while 1:
            sys.stdout.flush()
            try:
                sys.stdout.write('\n\t%s' % res.get(0.02))
                break
            except multiprocessing.TimeoutError:
                sys.stdout.write('.')
        print()
        print()

        print('Testing IMapIterator.next() with timeout:', end=' ')
        it = pool.imap(calculatestar, TASKS)
        while 1:
            sys.stdout.flush()
            try:
                sys.stdout.write('\n\t%s' % it.next(0.02))
            except StopIteration:
                break
            except multiprocessing.TimeoutError:
                sys.stdout.write('.')
        print()
        print()


if __name__ == '__main__':
    multiprocessing.freeze_support()
    test()
@end example

Un exemple montrant comment utiliser des files pour alimenter en tâches une collection de processus `workers' et collecter les résultats :

@example
import time
import random

from multiprocessing import Process, Queue, current_process, freeze_support

#
# Function run by worker processes
#

def worker(input, output):
    for func, args in iter(input.get, 'STOP'):
        result = calculate(func, args)
        output.put(result)

#
# Function used to calculate result
#

def calculate(func, args):
    result = func(*args)
    return '%s says that %s%s = %s' % \
        (current_process().name, func.__name__, args, result)

#
# Functions referenced by tasks
#

def mul(a, b):
    time.sleep(0.5*random.random())
    return a * b

def plus(a, b):
    time.sleep(0.5*random.random())
    return a + b

#
#
#

def test():
    NUMBER_OF_PROCESSES = 4
    TASKS1 = [(mul, (i, 7)) for i in range(20)]
    TASKS2 = [(plus, (i, 8)) for i in range(10)]

    # Create queues
    task_queue = Queue()
    done_queue = Queue()

    # Submit tasks
    for task in TASKS1:
        task_queue.put(task)

    # Start worker processes
    for i in range(NUMBER_OF_PROCESSES):
        Process(target=worker, args=(task_queue, done_queue)).start()

    # Get and print results
    print('Unordered results:')
    for i in range(len(TASKS1)):
        print('\t', done_queue.get())

    # Add more tasks using `put()`
    for task in TASKS2:
        task_queue.put(task)

    # Get and print some more results
    for i in range(len(TASKS2)):
        print('\t', done_queue.get())

    # Tell child processes to stop
    for i in range(NUMBER_OF_PROCESSES):
        task_queue.put('STOP')


if __name__ == '__main__':
    freeze_support()
    test()
@end example

@node multiprocessing shared_memory --- Shared memory for direct access across processes,The concurrent package,multiprocessing --- Process-based parallelism,Exécution concourante
@anchor{library/multiprocessing shared_memory doc}@anchor{3117}@anchor{library/multiprocessing shared_memory module-multiprocessing shared_memory}@anchor{98}@anchor{library/multiprocessing shared_memory multiprocessing-shared-memory-shared-memory-for-direct-access-across-processes}@anchor{3118}
@subsection @code{multiprocessing.shared_memory} --- Shared memory for direct access across processes


@geindex module; multiprocessing.shared_memory

`Code source :' Lib/multiprocessing/shared_memory.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/multiprocessing/shared_memory.py}


Ajouté dans la version 3.8.


@geindex Shared Memory
@geindex POSIX Shared Memory
@geindex Named Shared Memory


__________________________________________________________________


This module provides a class, @ref{15e2,,SharedMemory}, for the allocation
and management of shared memory to be accessed by one or more processes
on a multicore or symmetric multiprocessor (SMP) machine.  To assist with
the life-cycle management of shared memory especially across distinct
processes, a @ref{30db,,BaseManager} subclass,
@ref{3119,,SharedMemoryManager}, is also provided in the
@ref{96,,multiprocessing.managers} module.

In this module, shared memory refers to "POSIX style" shared memory blocks
(though is not necessarily implemented explicitly as such) and does not refer
to "distributed shared memory".  This style of shared memory permits distinct
processes to potentially read and write to a common (or shared) region of
volatile memory.  Processes are conventionally limited to only have access to
their own process memory space but shared memory permits the sharing
of data between processes, avoiding the need to instead send messages between
processes containing that data.  Sharing data directly via memory can provide
significant performance benefits compared to sharing data via disk or socket
or other communications requiring the serialization/deserialization and
copying of data.

@geindex SharedMemory (classe dans multiprocessing.shared_memory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory}@anchor{15e2}
@deffn {Classe} multiprocessing.shared_memory.SharedMemory (name=None, create=False, size=0, *, track=True)

Create an instance of the @code{SharedMemory} class for either
creating a new shared memory block or attaching to an existing shared
memory block.  Each shared memory block is assigned a unique name.
In this way, one process can create a shared memory block with a
particular name and a different process can attach to that same shared
memory block using that same name.

As a resource for sharing data across processes, shared memory blocks
may outlive the original process that created them.  When one process
no longer needs access to a shared memory block that might still be
needed by other processes, the @ref{311a,,close()} method should be called.
When a shared memory block is no longer needed by any process, the
@ref{311b,,unlink()} method should be called to ensure proper cleanup.

@*Paramètres: 

@itemize *

@item 
@code{name} (@ref{435,,str}@code{ | }@code{None}) -- The unique name for the requested shared memory, specified as a string.
When creating a new shared memory block, if @code{None} (the default)
is supplied for the name, a novel name will be generated.

@item 
@code{create} (@ref{451,,bool}) -- Control whether a new shared memory block is created (@code{True})
or an existing shared memory block is attached (@code{False}).

@item 
@code{size} (@ref{254,,int}) -- The requested number of bytes when creating a new shared memory block.
Because some platforms choose to allocate chunks of memory
based upon that platform's memory page size, the exact size of the shared
memory block may be larger or equal to the size requested.
When attaching to an existing shared memory block,
the `size' parameter is ignored.

@item 
@code{track} (@ref{451,,bool}) -- When @code{True}, register the shared memory block with a resource
tracker process on platforms where the OS does not do this automatically.
The resource tracker ensures proper cleanup of the shared memory even
if all other processes with access to the memory exit without doing so.
Python processes created from a common ancestor using @ref{93,,multiprocessing}
facilities share a single resource tracker process, and the lifetime of
shared memory segments is handled automatically among these processes.
Python processes created in any other way will receive their own
resource tracker when accessing shared memory with `track' enabled.
This will cause the shared memory to be deleted by the resource tracker
of the first process that terminates.
To avoid this issue, users of @ref{d5,,subprocess} or standalone Python
processes should set `track' to @code{False} when there is already another
process in place that does the bookkeeping.
`track' is ignored on Windows, which has its own tracking and
automatically deletes shared memory when all handles to it have been closed.
@end itemize



Modifié dans la version 3.13: Added the `track' parameter.


@geindex close() (méthode multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory close}@anchor{311a}
@deffn {Méthode} close ()

Close the file descriptor/handle to the shared memory from this
instance.  @ref{311a,,close()} should be called once access to the shared
memory block from this instance is no longer needed.  Depending
on operating system, the underlying memory may or may not be freed
even if all handles to it have been closed.  To ensure proper cleanup,
use the @ref{311b,,unlink()} method.
@end deffn

@geindex unlink() (méthode multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory unlink}@anchor{311b}
@deffn {Méthode} unlink ()

Delete the underlying shared memory block.  This should be called only
once per shared memory block regardless of the number of handles to it,
even in other processes.
@ref{311b,,unlink()} and @ref{311a,,close()} can be called in any order, but
trying to access data inside a shared memory block after @ref{311b,,unlink()}
may result in memory access errors, depending on platform.

This method has no effect on Windows, where the only way to delete a
shared memory block is to close all handles.
@end deffn

@geindex buf (attribut multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory buf}@anchor{311c}
@deffn {Attribut} buf

Une `memoryview' du contenu du bloc de mémoire partagée.
@end deffn

@geindex name (attribut multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory name}@anchor{311d}
@deffn {Attribut} name

Nom unique du bloc de mémoire partagée (lecture seule).
@end deffn

@geindex size (attribut multiprocessing.shared_memory.SharedMemory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory SharedMemory size}@anchor{311e}
@deffn {Attribut} size

Taille en octets du bloc de mémoire partagée (lecture seule).
@end deffn
@end deffn

L'exemple qui suit montre un exemple d'utilisation bas niveau d'instances de @ref{15e2,,SharedMemory} :

@example
>>> from multiprocessing import shared_memory
>>> shm_a = shared_memory.SharedMemory(create=True, size=10)
>>> type(shm_a.buf)
<class 'memoryview'>
>>> buffer = shm_a.buf
>>> len(buffer)
10
>>> buffer[:4] = bytearray([22, 33, 44, 55])  # Modify multiple at once
>>> buffer[4] = 100                           # Modify single byte at a time
>>> # Attach to an existing shared memory block
>>> shm_b = shared_memory.SharedMemory(shm_a.name)
>>> import array
>>> array.array('b', shm_b.buf[:5])  # Copy the data into a new array.array
array('b', [22, 33, 44, 55, 100])
>>> shm_b.buf[:5] = b'howdy'  # Modify via shm_b using bytes
>>> bytes(shm_a.buf[:5])      # Access via shm_a
b'howdy'
>>> shm_b.close()   # Close each SharedMemory instance
>>> shm_a.close()
>>> shm_a.unlink()  # Call unlink only once to release the shared memory
@end example

The following example demonstrates a practical use of the @ref{15e2,,SharedMemory}
class with NumPy arrays@footnote{https://numpy.org/}, accessing the
same @code{numpy.ndarray} from two distinct Python shells:

@example
>>> # In the first Python interactive shell
>>> import numpy as np
>>> a = np.array([1, 1, 2, 3, 5, 8])  # Start with an existing NumPy array
>>> from multiprocessing import shared_memory
>>> shm = shared_memory.SharedMemory(create=True, size=a.nbytes)
>>> # Now create a NumPy array backed by shared memory
>>> b = np.ndarray(a.shape, dtype=a.dtype, buffer=shm.buf)
>>> b[:] = a[:]  # Copy the original data into shared memory
>>> b
array([1, 1, 2, 3, 5, 8])
>>> type(b)
<class 'numpy.ndarray'>
>>> type(a)
<class 'numpy.ndarray'>
>>> shm.name  # We did not specify a name so one was chosen for us
'psm_21467_46075'

>>> # In either the same shell or a new Python shell on the same machine
>>> import numpy as np
>>> from multiprocessing import shared_memory
>>> # Attach to the existing shared memory block
>>> existing_shm = shared_memory.SharedMemory(name='psm_21467_46075')
>>> # Note that a.shape is (6,) and a.dtype is np.int64 in this example
>>> c = np.ndarray((6,), dtype=np.int64, buffer=existing_shm.buf)
>>> c
array([1, 1, 2, 3, 5, 8])
>>> c[-1] = 888
>>> c
array([  1,   1,   2,   3,   5, 888])

>>> # Back in the first Python interactive shell, b reflects this change
>>> b
array([  1,   1,   2,   3,   5, 888])

>>> # Clean up from within the second Python shell
>>> del c  # Unnecessary; merely emphasizing the array is no longer used
>>> existing_shm.close()

>>> # Clean up from within the first Python shell
>>> del b  # Unnecessary; merely emphasizing the array is no longer used
>>> shm.close()
>>> shm.unlink()  # Free and release the shared memory block at the very end
@end example

@geindex SharedMemoryManager (classe dans multiprocessing.managers)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager}@anchor{3119}
@deffn {Classe} multiprocessing.managers.SharedMemoryManager ([address[, authkey]])

A subclass of @ref{30db,,multiprocessing.managers.BaseManager} which can be
used for the management of shared memory blocks across processes.

A call to @ref{30dc,,start()} on a
@code{SharedMemoryManager} instance causes a new process to be started.
This new process's sole purpose is to manage the life cycle
of all shared memory blocks created through it.  To trigger the release
of all shared memory blocks managed by that process, call
@ref{30dd,,shutdown()} on the instance.
This triggers a @ref{311b,,unlink()} call
on all of the @ref{311f,,SharedMemory} objects managed by that process and then
stops the process itself.  By creating @code{SharedMemory} instances
through a @code{SharedMemoryManager}, we avoid the need to manually track
and trigger the freeing of shared memory resources.

Cette classe fournit des méthodes pour créer et renvoyer des instances de @ref{311f,,SharedMemory} et pour créer des objets compatibles liste (@ref{3120,,ShareableList}) basés sur la mémoire partagée.

Refer to @ref{30db,,BaseManager} for a description
of the inherited `address' and `authkey' optional input arguments and how
they may be used to connect to an existing @code{SharedMemoryManager} service
from other processes.

@geindex SharedMemory() (méthode multiprocessing.managers.SharedMemoryManager)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager SharedMemory}@anchor{311f}
@deffn {Méthode} SharedMemory (size)

Create and return a new @ref{311f,,SharedMemory} object with the
specified `size' in bytes.
@end deffn

@geindex ShareableList() (méthode multiprocessing.managers.SharedMemoryManager)
@anchor{library/multiprocessing shared_memory multiprocessing managers SharedMemoryManager ShareableList}@anchor{3120}
@deffn {Méthode} ShareableList (sequence)

Create and return a new @ref{3120,,ShareableList} object, initialized
by the values from the input `sequence'.
@end deffn
@end deffn

The following example demonstrates the basic mechanisms of a
@ref{3119,,SharedMemoryManager}:

@example
>>> from multiprocessing.managers import SharedMemoryManager
>>> smm = SharedMemoryManager()
>>> smm.start()  # Start the process that manages the shared memory blocks
>>> sl = smm.ShareableList(range(4))
>>> sl
ShareableList([0, 1, 2, 3], name='psm_6572_7512')
>>> raw_shm = smm.SharedMemory(size=128)
>>> another_sl = smm.ShareableList('alpha')
>>> another_sl
ShareableList(['a', 'l', 'p', 'h', 'a'], name='psm_6572_12221')
>>> smm.shutdown()  # Calls unlink() on sl, raw_shm, and another_sl
@end example

The following example depicts a potentially more convenient pattern for using
@ref{3119,,SharedMemoryManager} objects via the
@ref{5bc,,with} statement to ensure that all shared memory blocks are released
after they are no longer needed:

@example
>>> with SharedMemoryManager() as smm:
...     sl = smm.ShareableList(range(2000))
...     # Divide the work among two processes, storing partial results in sl
...     p1 = Process(target=do_work, args=(sl, 0, 1000))
...     p2 = Process(target=do_work, args=(sl, 1000, 2000))
...     p1.start()
...     p2.start()  # A multiprocessing.Pool might be more efficient
...     p1.join()
...     p2.join()   # Wait for all work to complete in both processes
...     total_result = sum(sl)  # Consolidate the partial results now in sl
@end example

When using a @ref{3119,,SharedMemoryManager}
in a @ref{5bc,,with} statement, the shared memory blocks created using that
manager are all released when the @code{with} statement's code block
finishes execution.

@geindex ShareableList (classe dans multiprocessing.shared_memory)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList}@anchor{18fd}
@deffn {Classe} multiprocessing.shared_memory.ShareableList (sequence=None, *, name=None)

Provide a mutable list-like object where all values stored within are
stored in a shared memory block.
This constrains storable values to the following built-in data types:


@itemize *

@item 
@ref{254,,int} (signed 64-bit)

@item 
@ref{2eb,,float}

@item 
@ref{451,,bool}

@item 
@ref{435,,str} (less than 10M bytes each when encoded as UTF-8)

@item 
@ref{1bd,,bytes} (less than 10M bytes each)

@item 
@code{None}
@end itemize

It also notably differs from the built-in @ref{5fc,,list} type
in that these lists can not change their overall length
(i.e. no @code{append()}, @code{insert()}, etc.) and do not
support the dynamic creation of new @code{ShareableList} instances
via slicing.

`sequence' is used in populating a new @code{ShareableList} full of values.
Set to @code{None} to instead attach to an already existing
@code{ShareableList} by its unique shared memory name.

`name' is the unique name for the requested shared memory, as described
in the definition for @ref{15e2,,SharedMemory}.  When attaching to an
existing @code{ShareableList}, specify its shared memory block's unique
name while leaving `sequence' set to @code{None}.

@cartouche
@quotation Note 
A known issue exists for @ref{1bd,,bytes} and @ref{435,,str} values.
If they end with @code{\x00} nul bytes or characters, those may be
`silently stripped' when fetching them by index from the
@code{ShareableList}. This @code{.rstrip(b'\x00')} behavior is
considered a bug and may go away in the future. See gh-106939@footnote{https://github.com/python/cpython/issues/106939}.
@end quotation
@end cartouche

For applications where rstripping of trailing nulls is a problem,
work around it by always unconditionally appending an extra non-0
byte to the end of such values when storing and unconditionally
removing it when fetching:

@example
>>> from multiprocessing import shared_memory
>>> nul_bug_demo = shared_memory.ShareableList(['?\x00', b'\x03\x02\x01\x00\x00\x00'])
>>> nul_bug_demo[0]
'?'
>>> nul_bug_demo[1]
b'\x03\x02\x01'
>>> nul_bug_demo.shm.unlink()
>>> padded = shared_memory.ShareableList(['?\x00\x07', b'\x03\x02\x01\x00\x00\x00\x07'])
>>> padded[0][:-1]
'?\x00'
>>> padded[1][:-1]
b'\x03\x02\x01\x00\x00\x00'
>>> padded.shm.unlink()
@end example

@geindex count() (méthode multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList count}@anchor{3121}
@deffn {Méthode} count (value)

Return the number of occurrences of `value'.
@end deffn

@geindex index() (méthode multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList index}@anchor{3122}
@deffn {Méthode} index (value)

Return first index position of `value'.
Raise @ref{1ff,,ValueError} if `value' is not present.
@end deffn

@geindex format (attribut multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList format}@anchor{3123}
@deffn {Attribut} format

Attribut en lecture seule contenant le format d’agrégation @ref{d4,,struct} utilisé par les valeurs déjà stockées.
@end deffn

@geindex shm (attribut multiprocessing.shared_memory.ShareableList)
@anchor{library/multiprocessing shared_memory multiprocessing shared_memory ShareableList shm}@anchor{3124}
@deffn {Attribut} shm

Instance de @ref{15e2,,SharedMemory} dans laquelle les valeurs sont stockées.
@end deffn
@end deffn

L'exemple qui suit illustre un cas d'usage de base d'une instance de @ref{18fd,,ShareableList} :

@example
>>> from multiprocessing import shared_memory
>>> a = shared_memory.ShareableList(['howdy', b'HoWdY', -273.154, 100, None, True, 42])
>>> [ type(entry) for entry in a ]
[<class 'str'>, <class 'bytes'>, <class 'float'>, <class 'int'>, <class 'NoneType'>, <class 'bool'>, <class 'int'>]
>>> a[2]
-273.154
>>> a[2] = -78.5
>>> a[2]
-78.5
>>> a[2] = 'dry ice'  # Changing data types is supported as well
>>> a[2]
'dry ice'
>>> a[2] = 'larger than previously allocated storage space'
Traceback (most recent call last):
  ...
ValueError: exceeds available storage for existing str
>>> a[2]
'dry ice'
>>> len(a)
7
>>> a.index(42)
6
>>> a.count(b'howdy')
0
>>> a.count(b'HoWdY')
1
>>> a.shm.close()
>>> a.shm.unlink()
>>> del a  # Use of a ShareableList after call to unlink() is unsupported
@end example

L'exemple ci-dessous montre comment un, deux ou un grand nombre de processus peuvent accéder à une @ref{18fd,,ShareableList} commune à partir du nom du bloc mémoire partagé sous-jacent :

@example
>>> b = shared_memory.ShareableList(range(5))         # In a first process
>>> c = shared_memory.ShareableList(name=b.shm.name)  # In a second process
>>> c
ShareableList([0, 1, 2, 3, 4], name='...')
>>> c[-1] = -999
>>> b[-1]
-999
>>> b.shm.close()
>>> c.shm.close()
>>> c.shm.unlink()
@end example

The following examples demonstrates that @ref{18fd,,ShareableList}
(and underlying @ref{15e2,,SharedMemory}) objects
can be pickled and unpickled if needed.
Note, that it will still be the same shared object.
This happens, because the deserialized object has
the same unique name and is just attached to an existing
object with the same name (if the object is still alive):

@example
>>> import pickle
>>> from multiprocessing import shared_memory
>>> sl = shared_memory.ShareableList(range(10))
>>> list(sl)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@end example

@example
>>> deserialized_sl = pickle.loads(pickle.dumps(sl))
>>> list(deserialized_sl)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@end example

@example
>>> sl[0] = -1
>>> deserialized_sl[1] = -2
>>> list(sl)
[-1, -2, 2, 3, 4, 5, 6, 7, 8, 9]
>>> list(deserialized_sl)
[-1, -2, 2, 3, 4, 5, 6, 7, 8, 9]
@end example

@example
>>> sl.shm.close()
>>> sl.shm.unlink()
@end example

@node The concurrent package,concurrent futures --- Launching parallel tasks,multiprocessing shared_memory --- Shared memory for direct access across processes,Exécution concourante
@anchor{library/concurrent doc}@anchor{3125}@anchor{library/concurrent the-concurrent-package}@anchor{3126}
@subsection The @code{concurrent} package


Il n'y a actuellement qu'un module dans ce paquet :


@itemize *

@item 
@ref{21,,concurrent.futures} -- Lancer des tâches en parallèle
@end itemize

@node concurrent futures --- Launching parallel tasks,subprocess --- Subprocess management,The concurrent package,Exécution concourante
@anchor{library/concurrent futures doc}@anchor{3127}@anchor{library/concurrent futures concurrent-futures-launching-parallel-tasks}@anchor{3128}@anchor{library/concurrent futures module-concurrent futures}@anchor{21}
@subsection @code{concurrent.futures} --- Launching parallel tasks


@geindex module; concurrent.futures


Ajouté dans la version 3.2.


`Source code:' Lib/concurrent/futures/thread.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/concurrent/futures/thread.py}
and Lib/concurrent/futures/process.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/concurrent/futures/process.py}


__________________________________________________________________


The @ref{21,,concurrent.futures} module provides a high-level interface for
asynchronously executing callables.

The asynchronous execution can be performed with threads, using
@ref{72c,,ThreadPoolExecutor}, or separate processes, using
@ref{8db,,ProcessPoolExecutor}.  Both implement the same interface, which is
defined by the abstract @ref{3129,,Executor} class.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@menu
* Executor Objects:: 
* ThreadPoolExecutor:: 
* ProcessPoolExecutor:: 
* Future Objects:: 
* Module Functions:: 
* Exception classes:: 

@end menu

@node Executor Objects,ThreadPoolExecutor,,concurrent futures --- Launching parallel tasks
@anchor{library/concurrent futures executor-objects}@anchor{312a}
@subsubsection Executor Objects


@geindex Executor (classe dans concurrent.futures)
@anchor{library/concurrent futures concurrent futures Executor}@anchor{3129}
@deffn {Classe} concurrent.futures.Executor

An abstract class that provides methods to execute calls asynchronously.  It
should not be used directly, but through its concrete subclasses.

@geindex submit() (méthode concurrent.futures.Executor)
@anchor{library/concurrent futures concurrent futures Executor submit}@anchor{a70}
@deffn {Méthode} submit (fn, /, *args, **kwargs)

Schedules the callable, `fn', to be executed as @code{fn(*args, **kwargs)}
and returns a @ref{118f,,Future} object representing the execution of the
callable.

@example
with ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(pow, 323, 1235)
    print(future.result())
@end example
@end deffn

@geindex map() (méthode concurrent.futures.Executor)
@anchor{library/concurrent futures concurrent futures Executor map}@anchor{dd1}
@deffn {Méthode} map (fn, *iterables, timeout=None, chunksize=1)

Similar to @ref{84e,,map(fn@comma{} *iterables)} except:


@itemize *

@item 
the `iterables' are collected immediately rather than lazily;

@item 
`fn' is executed asynchronously and several calls to
`fn' may be made concurrently.
@end itemize

The returned iterator raises a @ref{81f,,TimeoutError}
if @ref{12ab,,__next__()} is called and the result isn't available
after `timeout' seconds from the original call to @ref{dd1,,Executor.map()}.
`timeout' can be an int or a float.  If `timeout' is not specified or
@code{None}, there is no limit to the wait time.

If a `fn' call raises an exception, then that exception will be
raised when its value is retrieved from the iterator.

When using @ref{8db,,ProcessPoolExecutor}, this method chops `iterables'
into a number of chunks which it submits to the pool as separate
tasks.  The (approximate) size of these chunks can be specified by
setting `chunksize' to a positive integer.  For very long iterables,
using a large value for `chunksize' can significantly improve
performance compared to the default size of 1.  With
@ref{72c,,ThreadPoolExecutor}, `chunksize' has no effect.


Modifié dans la version 3.5: Added the `chunksize' argument.

@end deffn

@geindex shutdown() (méthode concurrent.futures.Executor)
@anchor{library/concurrent futures concurrent futures Executor shutdown}@anchor{8da}
@deffn {Méthode} shutdown (wait=True, *, cancel_futures=False)

Signal the executor that it should free any resources that it is using
when the currently pending futures are done executing.  Calls to
@ref{a70,,Executor.submit()} and @ref{dd1,,Executor.map()} made after shutdown will
raise @ref{193,,RuntimeError}.

If `wait' is @code{True} then this method will not return until all the
pending futures are done executing and the resources associated with the
executor have been freed.  If `wait' is @code{False} then this method will
return immediately and the resources associated with the executor will be
freed when all pending futures are done executing.  Regardless of the
value of `wait', the entire Python program will not exit until all
pending futures are done executing.

If `cancel_futures' is @code{True}, this method will cancel all pending
futures that the executor has not started running. Any futures that
are completed or running won't be cancelled, regardless of the value
of `cancel_futures'.

If both `cancel_futures' and `wait' are @code{True}, all futures that the
executor has started running will be completed prior to this method
returning. The remaining futures are cancelled.

You can avoid having to call this method explicitly if you use the
@ref{5bc,,with} statement, which will shutdown the @ref{3129,,Executor}
(waiting as if @ref{8da,,Executor.shutdown()} were called with `wait' set to
@code{True}):

@example
import shutil
with ThreadPoolExecutor(max_workers=4) as e:
    e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
    e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
    e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
    e.submit(shutil.copy, 'src4.txt', 'dest4.txt')
@end example


Modifié dans la version 3.9: Added `cancel_futures'.

@end deffn
@end deffn

@node ThreadPoolExecutor,ProcessPoolExecutor,Executor Objects,concurrent futures --- Launching parallel tasks
@anchor{library/concurrent futures threadpoolexecutor}@anchor{312b}
@subsubsection ThreadPoolExecutor


@ref{72c,,ThreadPoolExecutor} is an @ref{3129,,Executor} subclass that uses a pool of
threads to execute calls asynchronously.

Deadlocks can occur when the callable associated with a @ref{118f,,Future} waits on
the results of another @ref{118f,,Future}.  For example:

@example
import time
def wait_on_b():
    time.sleep(5)
    print(b.result())  # b will never complete because it is waiting on a.
    return 5

def wait_on_a():
    time.sleep(5)
    print(a.result())  # a will never complete because it is waiting on b.
    return 6


executor = ThreadPoolExecutor(max_workers=2)
a = executor.submit(wait_on_b)
b = executor.submit(wait_on_a)
@end example

Et :

@example
def wait_on_future():
    f = executor.submit(pow, 5, 2)
    # This will never complete because there is only one worker thread and
    # it is executing this function.
    print(f.result())

executor = ThreadPoolExecutor(max_workers=1)
executor.submit(wait_on_future)
@end example

@geindex ThreadPoolExecutor (classe dans concurrent.futures)
@anchor{library/concurrent futures concurrent futures ThreadPoolExecutor}@anchor{72c}
@deffn {Classe} concurrent.futures.ThreadPoolExecutor (max_workers=None, thread_name_prefix='@w{'}, initializer=None, initargs=())

An @ref{3129,,Executor} subclass that uses a pool of at most `max_workers'
threads to execute calls asynchronously.

All threads enqueued to @code{ThreadPoolExecutor} will be joined before the
interpreter can exit. Note that the exit handler which does this is
executed `before' any exit handlers added using @code{atexit}. This means
exceptions in the main thread must be caught and handled in order to
signal threads to exit gracefully. For this reason, it is recommended
that @code{ThreadPoolExecutor} not be used for long-running tasks.

`initializer' is an optional callable that is called at the start of
each worker thread; `initargs' is a tuple of arguments passed to the
initializer.  Should `initializer' raise an exception, all currently
pending jobs will raise a @ref{312c,,BrokenThreadPool},
as well as any attempt to submit more jobs to the pool.


Modifié dans la version 3.5: If `max_workers' is @code{None} or
not given, it will default to the number of processors on the machine,
multiplied by @code{5}, assuming that @ref{72c,,ThreadPoolExecutor} is often
used to overlap I/O instead of CPU work and the number of workers
should be higher than the number of workers
for @ref{8db,,ProcessPoolExecutor}.



Modifié dans la version 3.6: Added the `thread_name_prefix' parameter to allow users to
control the @ref{939,,threading.Thread} names for worker threads created by
the pool for easier debugging.



Modifié dans la version 3.7: Added the `initializer' and `initargs' arguments.



Modifié dans la version 3.8: Default value of `max_workers' is changed to @code{min(32, os.cpu_count() + 4)}.
This default value preserves at least 5 workers for I/O bound tasks.
It utilizes at most 32 CPU cores for CPU bound tasks which release the GIL.
And it avoids using very large resources implicitly on many-core machines.

ThreadPoolExecutor now reuses idle worker threads before starting
`max_workers' worker threads too.



Modifié dans la version 3.13: Default value of `max_workers' is changed to
@code{min(32, (os.process_cpu_count() or 1) + 4)}.

@end deffn

@menu
* ThreadPoolExecutor Example:: 

@end menu

@node ThreadPoolExecutor Example,,,ThreadPoolExecutor
@anchor{library/concurrent futures id1}@anchor{312d}@anchor{library/concurrent futures threadpoolexecutor-example}@anchor{1190}
@subsubsection ThreadPoolExecutor Example


@example
import concurrent.futures
import urllib.request

URLS = ['http://www.foxnews.com/',
        'http://www.cnn.com/',
        'http://europe.wsj.com/',
        'http://www.bbc.co.uk/',
        'http://nonexistent-subdomain.python.org/']

# Retrieve a single page and report the URL and contents
def load_url(url, timeout):
    with urllib.request.urlopen(url, timeout=timeout) as conn:
        return conn.read()

# We can use a with statement to ensure threads are cleaned up promptly
with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
    # Start the load operations and mark each future with its URL
    future_to_url = @{executor.submit(load_url, url, 60): url for url in URLS@}
    for future in concurrent.futures.as_completed(future_to_url):
        url = future_to_url[future]
        try:
            data = future.result()
        except Exception as exc:
            print('%r generated an exception: %s' % (url, exc))
        else:
            print('%r page is %d bytes' % (url, len(data)))
@end example

@node ProcessPoolExecutor,Future Objects,ThreadPoolExecutor,concurrent futures --- Launching parallel tasks
@anchor{library/concurrent futures processpoolexecutor}@anchor{312e}
@subsubsection ProcessPoolExecutor


The @ref{8db,,ProcessPoolExecutor} class is an @ref{3129,,Executor} subclass that
uses a pool of processes to execute calls asynchronously.
@ref{8db,,ProcessPoolExecutor} uses the @ref{93,,multiprocessing} module, which
allows it to side-step the @ref{147,,Global Interpreter Lock} but also means that
only picklable objects can be executed and returned.

The @code{__main__} module must be importable by worker subprocesses. This means
that @ref{8db,,ProcessPoolExecutor} will not work in the interactive interpreter.

Calling @ref{3129,,Executor} or @ref{118f,,Future} methods from a callable submitted
to a @ref{8db,,ProcessPoolExecutor} will result in deadlock.

@geindex ProcessPoolExecutor (classe dans concurrent.futures)
@anchor{library/concurrent futures concurrent futures ProcessPoolExecutor}@anchor{8db}
@deffn {Classe} concurrent.futures.ProcessPoolExecutor (max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)

An @ref{3129,,Executor} subclass that executes calls asynchronously using a pool
of at most `max_workers' processes.  If `max_workers' is @code{None} or not
given, it will default to @ref{1bf,,os.process_cpu_count()}.
If `max_workers' is less than or equal to @code{0}, then a @ref{1ff,,ValueError}
will be raised.
On Windows, `max_workers' must be less than or equal to @code{61}. If it is not
then @ref{1ff,,ValueError} will be raised. If `max_workers' is @code{None}, then
the default chosen will be at most @code{61}, even if more processors are
available.
`mp_context' can be a @ref{93,,multiprocessing} context or @code{None}. It will be
used to launch the workers. If `mp_context' is @code{None} or not given, the
default @ref{93,,multiprocessing} context is used.
See @ref{2c6,,Contextes et méthodes de démarrage}.

`initializer' is an optional callable that is called at the start of
each worker process; `initargs' is a tuple of arguments passed to the
initializer.  Should `initializer' raise an exception, all currently
pending jobs will raise a @ref{312f,,BrokenProcessPool},
as well as any attempt to submit more jobs to the pool.

`max_tasks_per_child' is an optional argument that specifies the maximum
number of tasks a single process can execute before it will exit and be
replaced with a fresh worker process. By default `max_tasks_per_child' is
@code{None} which means worker processes will live as long as the pool. When
a max is specified, the "spawn" multiprocessing start method will be used by
default in absence of a `mp_context' parameter. This feature is incompatible
with the "fork" start method.


Modifié dans la version 3.3: When one of the worker processes terminates abruptly, a
@ref{312f,,BrokenProcessPool} error is now raised.
Previously, behaviour
was undefined but operations on the executor or its futures would often
freeze or deadlock.



Modifié dans la version 3.7: The `mp_context' argument was added to allow users to control the
start_method for worker processes created by the pool.

Added the `initializer' and `initargs' arguments.

@cartouche
@quotation Note 
The default @ref{93,,multiprocessing} start method
(see @ref{2c6,,Contextes et méthodes de démarrage}) will change away from
`fork' in Python 3.14.  Code that requires `fork' be used for their
@ref{8db,,ProcessPoolExecutor} should explicitly specify that by
passing a @code{mp_context=multiprocessing.get_context("fork")}
parameter.
@end quotation
@end cartouche



Modifié dans la version 3.11: The `max_tasks_per_child' argument was added to allow users to
control the lifetime of workers in the pool.



Modifié dans la version 3.12: On POSIX systems, if your application has multiple threads and the
@ref{93,,multiprocessing} context uses the @code{"fork"} start method:
The @ref{195,,os.fork()} function called internally to spawn workers may raise a
@ref{1a3,,DeprecationWarning}. Pass a `mp_context' configured to use a
different start method. See the @ref{195,,os.fork()} documentation for
further explanation.



Modifié dans la version 3.13: `max_workers' uses @ref{1bf,,os.process_cpu_count()} by default, instead of
@ref{1c0,,os.cpu_count()}.

@end deffn

@menu
* ProcessPoolExecutor Example:: 

@end menu

@node ProcessPoolExecutor Example,,,ProcessPoolExecutor
@anchor{library/concurrent futures id2}@anchor{3130}@anchor{library/concurrent futures processpoolexecutor-example}@anchor{1191}
@subsubsection ProcessPoolExecutor Example


@example
import concurrent.futures
import math

PRIMES = [
    112272535095293,
    112582705942171,
    112272535095293,
    115280095190773,
    115797848077099,
    1099726899285419]

def is_prime(n):
    if n < 2:
        return False
    if n == 2:
        return True
    if n % 2 == 0:
        return False

    sqrt_n = int(math.floor(math.sqrt(n)))
    for i in range(3, sqrt_n + 1, 2):
        if n % i == 0:
            return False
    return True

def main():
    with concurrent.futures.ProcessPoolExecutor() as executor:
        for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):
            print('%d is prime: %s' % (number, prime))

if __name__ == '__main__':
    main()
@end example

@node Future Objects,Module Functions,ProcessPoolExecutor,concurrent futures --- Launching parallel tasks
@anchor{library/concurrent futures future-objects}@anchor{3131}
@subsubsection Future Objects


The @ref{118f,,Future} class encapsulates the asynchronous execution of a callable.
@ref{118f,,Future} instances are created by @ref{a70,,Executor.submit()}.

@geindex Future (classe dans concurrent.futures)
@anchor{library/concurrent futures concurrent futures Future}@anchor{118f}
@deffn {Classe} concurrent.futures.Future

Encapsulates the asynchronous execution of a callable.  @ref{118f,,Future}
instances are created by @ref{a70,,Executor.submit()} and should not be created
directly except for testing.

@geindex cancel() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future cancel}@anchor{3132}
@deffn {Méthode} cancel ()

Attempt to cancel the call.  If the call is currently being executed or
finished running and cannot be cancelled then the method will return
@code{False}, otherwise the call will be cancelled and the method will
return @code{True}.
@end deffn

@geindex cancelled() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future cancelled}@anchor{3133}
@deffn {Méthode} cancelled ()

Return @code{True} if the call was successfully cancelled.
@end deffn

@geindex running() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future running}@anchor{3134}
@deffn {Méthode} running ()

Return @code{True} if the call is currently being executed and cannot be
cancelled.
@end deffn

@geindex done() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future done}@anchor{3135}
@deffn {Méthode} done ()

Return @code{True} if the call was successfully cancelled or finished
running.
@end deffn

@geindex result() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future result}@anchor{3136}
@deffn {Méthode} result (timeout=None)

Return the value returned by the call. If the call hasn't yet completed
then this method will wait up to `timeout' seconds.  If the call hasn't
completed in `timeout' seconds, then a
@ref{81f,,TimeoutError} will be raised. `timeout' can be
an int or float.  If `timeout' is not specified or @code{None}, there is no
limit to the wait time.

If the future is cancelled before completing then @ref{9c8,,CancelledError}
will be raised.

If the call raised an exception, this method will raise the same exception.
@end deffn

@geindex exception() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future exception}@anchor{3137}
@deffn {Méthode} exception (timeout=None)

Return the exception raised by the call.  If the call hasn't yet
completed then this method will wait up to `timeout' seconds.  If the
call hasn't completed in `timeout' seconds, then a
@ref{81f,,TimeoutError} will be raised.  `timeout' can be
an int or float.  If `timeout' is not specified or @code{None}, there is no
limit to the wait time.

If the future is cancelled before completing then @ref{9c8,,CancelledError}
will be raised.

If the call completed without raising, @code{None} is returned.
@end deffn

@geindex add_done_callback() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future add_done_callback}@anchor{3138}
@deffn {Méthode} add_done_callback (fn)

Attaches the callable `fn' to the future.  `fn' will be called, with the
future as its only argument, when the future is cancelled or finishes
running.

Added callables are called in the order that they were added and are
always called in a thread belonging to the process that added them.  If
the callable raises an @ref{9c7,,Exception} subclass, it will be logged and
ignored.  If the callable raises a @ref{5a5,,BaseException} subclass, the
behavior is undefined.

If the future has already completed or been cancelled, `fn' will be
called immediately.
@end deffn

The following @ref{118f,,Future} methods are meant for use in unit tests and
@ref{3129,,Executor} implementations.

@geindex set_running_or_notify_cancel() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future set_running_or_notify_cancel}@anchor{3139}
@deffn {Méthode} set_running_or_notify_cancel ()

This method should only be called by @ref{3129,,Executor} implementations
before executing the work associated with the @ref{118f,,Future} and by unit
tests.

If the method returns @code{False} then the @ref{118f,,Future} was cancelled,
i.e. @ref{3132,,Future.cancel()} was called and returned @code{True}.  Any threads
waiting on the @ref{118f,,Future} completing (i.e. through
@ref{15d6,,as_completed()} or @ref{17f0,,wait()}) will be woken up.

If the method returns @code{True} then the @ref{118f,,Future} was not cancelled
and has been put in the running state, i.e. calls to
@ref{3134,,Future.running()} will return @code{True}.

This method can only be called once and cannot be called after
@ref{313a,,Future.set_result()} or @ref{313b,,Future.set_exception()} have been
called.
@end deffn

@geindex set_result() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future set_result}@anchor{313a}
@deffn {Méthode} set_result (result)

Sets the result of the work associated with the @ref{118f,,Future} to
`result'.

This method should only be used by @ref{3129,,Executor} implementations and
unit tests.


Modifié dans la version 3.8: This method raises
@ref{1594,,concurrent.futures.InvalidStateError} if the @ref{118f,,Future} is
already done.

@end deffn

@geindex set_exception() (méthode concurrent.futures.Future)
@anchor{library/concurrent futures concurrent futures Future set_exception}@anchor{313b}
@deffn {Méthode} set_exception (exception)

Sets the result of the work associated with the @ref{118f,,Future} to the
@ref{9c7,,Exception} `exception'.

This method should only be used by @ref{3129,,Executor} implementations and
unit tests.


Modifié dans la version 3.8: This method raises
@ref{1594,,concurrent.futures.InvalidStateError} if the @ref{118f,,Future} is
already done.

@end deffn
@end deffn

@node Module Functions,Exception classes,Future Objects,concurrent futures --- Launching parallel tasks
@anchor{library/concurrent futures module-functions}@anchor{313c}
@subsubsection Module Functions


@geindex wait() (dans le module concurrent.futures)
@anchor{library/concurrent futures concurrent futures wait}@anchor{17f0}
@deffn {Fonction} concurrent.futures.wait (fs, timeout=None, return_when=ALL_COMPLETED)

Wait for the @ref{118f,,Future} instances (possibly created by different
@ref{3129,,Executor} instances) given by `fs' to complete. Duplicate futures
given to `fs' are removed and will be returned only once. Returns a named
2-tuple of sets.  The first set, named @code{done}, contains the futures that
completed (finished or cancelled futures) before the wait completed.  The
second set, named @code{not_done}, contains the futures that did not complete
(pending or running futures).

`timeout' can be used to control the maximum number of seconds to wait before
returning.  `timeout' can be an int or float.  If `timeout' is not specified
or @code{None}, there is no limit to the wait time.

`return_when' indique quand la fonction doit se terminer. Il peut prendre les valeurs suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Description

@item

@geindex FIRST_COMPLETED (dans le module concurrent.futures)
@anchor{library/concurrent futures concurrent futures FIRST_COMPLETED}@anchor{313d}
@deffn {Données} concurrent.futures.FIRST_COMPLETED
@end deffn

@tab

La fonction se termine lorsque n'importe quel futur se termine ou est annulé.

@item

@geindex FIRST_EXCEPTION (dans le module concurrent.futures)
@anchor{library/concurrent futures concurrent futures FIRST_EXCEPTION}@anchor{313e}
@deffn {Données} concurrent.futures.FIRST_EXCEPTION
@end deffn

@tab

The function will return when any future finishes by raising an
exception. If no future raises an exception
then it is equivalent to @ref{313f,,ALL_COMPLETED}.

@item

@geindex ALL_COMPLETED (dans le module concurrent.futures)
@anchor{library/concurrent futures concurrent futures ALL_COMPLETED}@anchor{313f}
@deffn {Données} concurrent.futures.ALL_COMPLETED
@end deffn

@tab

La fonction se termine lorsque les `futurs' sont tous finis ou annulés.

@end multitable

@end deffn

@geindex as_completed() (dans le module concurrent.futures)
@anchor{library/concurrent futures concurrent futures as_completed}@anchor{15d6}
@deffn {Fonction} concurrent.futures.as_completed (fs, timeout=None)

Returns an iterator over the @ref{118f,,Future} instances (possibly created by
different @ref{3129,,Executor} instances) given by `fs' that yields futures as
they complete (finished or cancelled futures). Any futures given by `fs' that
are duplicated will be returned once. Any futures that completed before
@ref{15d6,,as_completed()} is called will be yielded first.  The returned iterator
raises a @ref{81f,,TimeoutError} if @ref{12ab,,__next__()}
is called and the result isn't available after `timeout' seconds from the
original call to @ref{15d6,,as_completed()}.  `timeout' can be an int or float. If
`timeout' is not specified or @code{None}, there is no limit to the wait time.
@end deffn


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 3148

@item PEP 3148@footnote{https://peps.python.org/pep-3148/} -- futures - execute computations asynchronously

The proposal which described this feature for inclusion in the Python
standard library.
@end table


@node Exception classes,,Module Functions,concurrent futures --- Launching parallel tasks
@anchor{library/concurrent futures exception-classes}@anchor{3140}
@subsubsection Exception classes


@geindex CancelledError
@anchor{library/concurrent futures concurrent futures CancelledError}@anchor{9c8}
@deffn {Exception} concurrent.futures.CancelledError

Raised when a future is cancelled.
@end deffn

@geindex TimeoutError
@anchor{library/concurrent futures concurrent futures TimeoutError}@anchor{3141}
@deffn {Exception} concurrent.futures.TimeoutError

A deprecated alias of @ref{81f,,TimeoutError},
raised when a future operation exceeds the given timeout.


Modifié dans la version 3.11: cette classe est devenue un alias de @ref{81f,,TimeoutError}.

@end deffn

@geindex BrokenExecutor
@anchor{library/concurrent futures concurrent futures BrokenExecutor}@anchor{3142}
@deffn {Exception} concurrent.futures.BrokenExecutor

Derived from @ref{193,,RuntimeError}, this exception class is raised
when an executor is broken for some reason, and cannot be used
to submit or execute new tasks.


Ajouté dans la version 3.7.

@end deffn

@geindex InvalidStateError
@anchor{library/concurrent futures concurrent futures InvalidStateError}@anchor{1594}
@deffn {Exception} concurrent.futures.InvalidStateError

Raised when an operation is performed on a future that is not allowed
in the current state.


Ajouté dans la version 3.8.

@end deffn

@geindex BrokenThreadPool
@anchor{library/concurrent futures concurrent futures thread BrokenThreadPool}@anchor{312c}
@deffn {Exception} concurrent.futures.thread.BrokenThreadPool

Derived from @ref{3142,,BrokenExecutor}, this exception
class is raised when one of the workers
of a @ref{72c,,ThreadPoolExecutor}
has failed initializing.


Ajouté dans la version 3.7.

@end deffn

@geindex BrokenProcessPool
@anchor{library/concurrent futures concurrent futures process BrokenProcessPool}@anchor{312f}
@deffn {Exception} concurrent.futures.process.BrokenProcessPool

Derived from @ref{3142,,BrokenExecutor} (formerly
@ref{193,,RuntimeError}), this exception class is raised when one of the
workers of a @ref{8db,,ProcessPoolExecutor}
has terminated in a non-clean
fashion (for example, if it was killed from the outside).


Ajouté dans la version 3.3.

@end deffn

@node subprocess --- Subprocess management,sched --- Event scheduler,concurrent futures --- Launching parallel tasks,Exécution concourante
@anchor{library/subprocess doc}@anchor{3143}@anchor{library/subprocess module-subprocess}@anchor{d5}@anchor{library/subprocess subprocess-subprocess-management}@anchor{3144}
@subsection @code{subprocess} --- Subprocess management


@geindex module; subprocess

`Code source :' Lib/subprocess.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/subprocess.py}


__________________________________________________________________


Le module @ref{d5,,subprocess} vous permet de lancer de nouveaux processus, les connecter à des tubes d'entrée/sortie/erreur, et d'obtenir leurs codes de retour.  Ce module a l'intention de remplacer plusieurs anciens modules et fonctions :

@example
os.system
os.spawn*
@end example

De plus amples informations sur comment le module @ref{d5,,subprocess} peut être utilisé pour remplacer ces modules et fonctions peuvent être trouvées dans les sections suivantes.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 324
PEP 324@footnote{https://peps.python.org/pep-0324/} -- PEP proposant le module `subprocess'


@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@menu
* Utiliser le module subprocess:: 
* Considérations de sécurité:: 
* Objets Popen:: 
* Utilitaires Popen pour Windows:: 
* Ancienne interface (API) haut-niveau: Ancienne interface API haut-niveau. 
* Remplacer les fonctions plus anciennes par le module subprocess:: 
* Remplacement des fonctions originales d'invocation du shell:: 
* Notes: Notes<2>. 

@end menu

@node Utiliser le module subprocess,Considérations de sécurité,,subprocess --- Subprocess management
@anchor{library/subprocess using-the-subprocess-module}@anchor{3145}
@subsubsection Utiliser le module @code{subprocess}


L'approche recommandée pour invoquer un sous-processus est d'utiliser la fonction @ref{b74,,run()} pour tous les cas d'utilisation qu'elle gère. Pour les cas d'utilisation plus avancés, l'interface inhérente @ref{197,,Popen} peut être utilisée directement.

@geindex run() (dans le module subprocess)
@anchor{library/subprocess subprocess run}@anchor{b74}
@deffn {Fonction} subprocess.run (args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)

Lance la commande décrite par `args'.  Attend que la commande se termine, puis renvoie une instance @ref{e5c,,CompletedProcess}.

Les arguments présentés ci-dessus sont simplement les plus utilisés, décrits ci-dessous dans la section @ref{3146,,Arguments fréquemment utilisés} (d'où l'utilisation de la notation `keyword-only' dans la signature abrégée). La signature complète de la fonction est sensiblement la même que celle du constructeur de @ref{197,,Popen}, à l'exception de `timeout', `input', `check' et `capture_output', tous les arguments donnés à cette fonction passent à travers cette interface.

If `capture_output' is true, stdout and stderr will be captured.
When used, the internal @ref{197,,Popen} object is automatically created with
`stdout' and `stderr' both set to @ref{b75,,PIPE}.
The `stdout' and `stderr' arguments may not be supplied at the same time as `capture_output'.
If you wish to capture and combine both streams into one,
set `stdout' to @ref{b75,,PIPE}
and `stderr' to @ref{3147,,STDOUT},
instead of using `capture_output'.

A `timeout' may be specified in seconds, it is internally passed on to
@ref{3148,,Popen.communicate()}. If the timeout expires, the child process will be
killed and waited for. The @ref{3149,,TimeoutExpired} exception will be
re-raised after the child process has terminated. The initial process
creation itself cannot be interrupted on many platform APIs so you are not
guaranteed to see a timeout exception until at least after however long
process creation takes.

The `input' argument is passed to @ref{3148,,Popen.communicate()} and thus to the
subprocess's stdin.  If used it must be a byte sequence, or a string if
`encoding' or `errors' is specified or `text' is true.  When
used, the internal @ref{197,,Popen} object is automatically created with
`stdin' set to @ref{b75,,PIPE},
and the `stdin' argument may not be used as well.

Si `check' est vrai, et que le processus s'arrête avec un code de statut non nul, une exception @ref{1302,,CalledProcessError} est levée.  Les attributs de cette exception contiennent les arguments, le code de statut, et les sorties standard et d'erreur si elles ont été capturées.

Si `encoding' ou `errors' sont spécifiés, ou `text' est vrai, les fichiers pour les entrées et sorties sont ouverts en mode texte en utilisant les paramètres `encoding' et `errors' spécifiés, ou les valeurs par défaut de @ref{7a5,,io.TextIOWrapper}. L'argument `universal_newlines' est équivalent à `text' et est fourni pour la rétrocompatibilité. Par défaut, les fichiers sont ouverts en mode binaire.

If `env' is not @code{None}, it must be a mapping that defines the environment
variables for the new process; these are used instead of the default
behavior of inheriting the current process' environment. It is passed
directly to @ref{197,,Popen}. This mapping can be str to str on any platform
or bytes to bytes on POSIX platforms much like @ref{1197,,os.environ} or
@ref{11f4,,os.environb}.

Exemples :

@example
>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'@w{'})
@end example


Ajouté dans la version 3.5.



Modifié dans la version 3.6: Ajout des paramètres `encoding' et `errors'



Modifié dans la version 3.7: Ajout du paramètre `text', qui agit comme un alias plus compréhensible de `universal_newlines'. Ajout du paramètre `capture_output'.



Modifié dans la version 3.12: Changed Windows shell search order for @code{shell=True}. The current
directory and @code{%PATH%} are replaced with @code{%COMSPEC%} and
@code{%SystemRoot%\System32\cmd.exe}. As a result, dropping a
malicious program named @code{cmd.exe} into a current directory no
longer works.

@end deffn

@geindex CompletedProcess (classe dans subprocess)
@anchor{library/subprocess subprocess CompletedProcess}@anchor{e5c}
@deffn {Classe} subprocess.CompletedProcess

La valeur de retour de @ref{b74,,run()}, représentant un processus qui s'est terminé.

@geindex args (attribut subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess args}@anchor{314a}
@deffn {Attribut} args

Les arguments utilisés pour lancer le processus. Cela peut être une liste ou une chaîne de caractères.
@end deffn

@geindex returncode (attribut subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess returncode}@anchor{314b}
@deffn {Attribut} returncode

Le code de statut du processus fils.  Typiquement, un code de statut de 0 indique qu'il s'est exécuté avec succès.

Une valeur négative @code{-N} indique que le processus enfant a été terminé par un signal @code{N} (seulement sur les systèmes `POSIX').
@end deffn

@geindex stdout (attribut subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess stdout}@anchor{314c}
@deffn {Attribut} stdout

La sortie standard capturée du processus enfant. Une séquence de `bytes', ou une chaîne de caractères si @ref{b74,,run()} a été appelée avec `encoding', `errors' ou `text=True'. Vaut @code{None} si la sortie standard n'était pas capturée.

Si vous avez lancé le processus avec @code{stderr=subprocess.STDOUT}, les sorties standard et d'erreur seront combinées dans cet attribut, et @ref{314d,,stderr} sera mis à @code{None}.
@end deffn

@geindex stderr (attribut subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess stderr}@anchor{314d}
@deffn {Attribut} stderr

La sortie d'erreur capturée du processus enfant. Une séquence de `bytes', ou une chaîne de caractères si @ref{b74,,run()} a été appelée avec `encoding', `errors' ou `text=True'. Vaut @code{None} si la sortie d'erreur n'était pas capturée.
@end deffn

@geindex check_returncode() (méthode subprocess.CompletedProcess)
@anchor{library/subprocess subprocess CompletedProcess check_returncode}@anchor{314e}
@deffn {Méthode} check_returncode ()

Si @ref{314b,,returncode} n'est pas nul, lève une @ref{1302,,CalledProcessError}.
@end deffn


Ajouté dans la version 3.5.

@end deffn

@geindex DEVNULL (dans le module subprocess)
@anchor{library/subprocess subprocess DEVNULL}@anchor{112e}
@deffn {Données} subprocess.DEVNULL

Valeur spéciale qui peut être utilisée pour les arguments `stdin', `stdout' ou `stderr' de @ref{197,,Popen} et qui indique que le fichier spécial @ref{19c1,,os.devnull} sera utilisé.


Ajouté dans la version 3.3.

@end deffn

@geindex PIPE (dans le module subprocess)
@anchor{library/subprocess subprocess PIPE}@anchor{b75}
@deffn {Données} subprocess.PIPE

Valeur spéciale qui peut être utilisée pour les arguments `stdin', `stdout' ou `stderr' de @ref{197,,Popen} et qui indique qu'un tube vers le flux standard doit être ouvert.  Surtout utile avec @ref{3148,,Popen.communicate()}.
@end deffn

@geindex STDOUT (dans le module subprocess)
@anchor{library/subprocess subprocess STDOUT}@anchor{3147}
@deffn {Données} subprocess.STDOUT

Valeur spéciale qui peut être utilisée pour l'argument `stderr' de @ref{197,,Popen} et qui indique que la sortie d'erreur doit être redirigée vers le même descripteur que la sortie standard.
@end deffn

@geindex SubprocessError
@anchor{library/subprocess subprocess SubprocessError}@anchor{314f}
@deffn {Exception} subprocess.SubprocessError

Classe de base à toutes les autres exceptions du module.


Ajouté dans la version 3.3.

@end deffn

@geindex TimeoutExpired
@anchor{library/subprocess subprocess TimeoutExpired}@anchor{3149}
@deffn {Exception} subprocess.TimeoutExpired

Sous-classe de @ref{314f,,SubprocessError}, levée quand un `timeout' expire pendant l'attente d'un processus enfant.

@geindex cmd (attribut subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired cmd}@anchor{3150}
@deffn {Attribut} cmd

La commande utilisée pour instancier le processus fils.
@end deffn

@geindex timeout (attribut subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired timeout}@anchor{3151}
@deffn {Attribut} timeout

Le `timeout' en secondes.
@end deffn

@geindex output (attribut subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired output}@anchor{3152}
@deffn {Attribut} output

Sortie du processus enfant si elle a été récupérée par @ref{b74,,run()} ou @ref{fac,,check_output()}. Sinon, @code{None}. La sortie est toujours de type @ref{1bd,,bytes} quand elle est récupérée, que le paramètre @code{text} soit mis à @code{True} ou non. Si la sortie est vide, cette dernière peut être @code{None} au lieu de @code{b'@w{'}}.
@end deffn

@geindex stdout (attribut subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired stdout}@anchor{3153}
@deffn {Attribut} stdout

Alias pour `output', afin d'avoir une symétrie avec @ref{3154,,stderr}.
@end deffn

@geindex stderr (attribut subprocess.TimeoutExpired)
@anchor{library/subprocess subprocess TimeoutExpired stderr}@anchor{3154}
@deffn {Attribut} stderr

Stderr output of the child process if it was captured by @ref{b74,,run()}.
Otherwise, @code{None}.  This is always @ref{1bd,,bytes} when stderr output
was captured regardless of the @code{text=True} setting.  It may remain
@code{None} instead of @code{b'@w{'}} when no stderr output was observed.
@end deffn


Ajouté dans la version 3.3.



Modifié dans la version 3.5: Ajout des attributs `stdout' et `stderr'

@end deffn

@geindex CalledProcessError
@anchor{library/subprocess subprocess CalledProcessError}@anchor{1302}
@deffn {Exception} subprocess.CalledProcessError

Subclass of @ref{314f,,SubprocessError}, raised when a process run by
@ref{3155,,check_call()}, @ref{fac,,check_output()}, or @ref{b74,,run()} (with @code{check=True})
returns a non-zero exit status.

@geindex returncode (attribut subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError returncode}@anchor{3156}
@deffn {Attribut} returncode

Code de statut du processus fils.  Si le processus a été arrêté par un signal, le code sera négatif et correspondra à l'opposé du numéro de signal.
@end deffn

@geindex cmd (attribut subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError cmd}@anchor{3157}
@deffn {Attribut} cmd

La commande utilisée pour instancier le processus fils.
@end deffn

@geindex output (attribut subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError output}@anchor{3158}
@deffn {Attribut} output

La sortie du processus fils, si capturée par @ref{b74,,run()} ou @ref{fac,,check_output()}.  Autrement, @code{None}.
@end deffn

@geindex stdout (attribut subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError stdout}@anchor{3159}
@deffn {Attribut} stdout

Alias pour `output', afin d'avoir une symétrie avec @ref{315a,,stderr}.
@end deffn

@geindex stderr (attribut subprocess.CalledProcessError)
@anchor{library/subprocess subprocess CalledProcessError stderr}@anchor{315a}
@deffn {Attribut} stderr

La sortie d'erreur du processus fils, si capturée par @ref{b74,,run()}. Autrement, @code{None}.
@end deffn


Modifié dans la version 3.5: Ajout des attributs `stdout' et `stderr'

@end deffn

@menu
* Arguments fréquemment utilisés:: 
* Constructeur de Popen:: 
* Exceptions: Exceptions<11>. 

@end menu

@node Arguments fréquemment utilisés,Constructeur de Popen,,Utiliser le module subprocess
@anchor{library/subprocess frequently-used-arguments}@anchor{3146}@anchor{library/subprocess id1}@anchor{315b}
@subsubsection Arguments fréquemment utilisés


Pour gérer un large ensemble de cas, le constructeur de @ref{197,,Popen} (et les fonctions de convenance) acceptent de nombreux arguments optionnels. Pour les cas d'utilisation les plus typiques, beaucoup de ces arguments peuvent sans problème être laissés à leurs valeurs par défaut. Les arguments les plus communément nécessaires sont :

@quotation

`args' est requis pour tous les appels et doit être une chaîne de caractères ou une séquence d'arguments du programme. Il est généralement préférable de fournir une séquence d'arguments, puisque cela permet au module de s'occuper des potentiels échappements ou guillemets autour des arguments (p. ex. pour permettre des espaces dans des noms de fichiers). Si l'argument est passé comme une simple chaîne, soit `shell' doit valoir @ref{bfb,,True} (voir ci-dessous) soit la chaîne doit simplement contenir le nom du programme à exécuter sans spécifier d'arguments supplémentaires.

`stdin', `stdout' and `stderr' specify the executed program's standard input,
standard output and standard error file handles, respectively.  Valid values
are @code{None}, @ref{b75,,PIPE}, @ref{112e,,DEVNULL}, an existing file descriptor (a
positive integer), and an existing @ref{11a0,,file object} with a valid file
descriptor.  With the default settings of @code{None}, no redirection will
occur.  @ref{b75,,PIPE} indicates that a new pipe to the child should be
created.  @ref{112e,,DEVNULL} indicates that the special file @ref{19c1,,os.devnull}
will be used.  Additionally, `stderr' can be @ref{3147,,STDOUT}, which indicates
that the stderr data from the child process should be captured into the same
file handle as for `stdout'.

@geindex universal newlines;subprocess module

Si `encoding' ou `errors' sont spécifiés, ou si `text' (aussi appelé `universal_newlines') est vrai, les fichiers `stdin', `stdout' et `stderr' seront ouverts en mode texte en utilisant les `encoding' et `errors' spécifiés à l'appel, ou les valeurs par défaut de @ref{7a5,,io.TextIOWrapper}.

Pour `stdin', les caractères de fin de ligne @code{'\n'} de l'entrée seront convertis vers des séparateurs de ligne par défaut @ref{2102,,os.linesep}. Pour `stdout' et `stderr', toutes les fins de lignes des sorties seront converties vers @code{'\n'}.  Pour plus d'informations, voir la documentation de la classe @ref{7a5,,io.TextIOWrapper} quand l'argument `newline' du constructeur est @code{None}.

Si le mode texte n'est pas utilisé, `stdin', `stdout' et `stderr' seront ouverts comme des flux binaires. Aucune conversion d'encodage ou de fins de ligne ne sera réalisée.


Modifié dans la version 3.6: Added the `encoding' and `errors' parameters.



Modifié dans la version 3.7: Ajout du paramètre `text' comme alias de `universal_newlines'.


@cartouche
@quotation Note 
L'attribut `newlines' des objets @ref{315c,,Popen.stdin}, @ref{315d,,Popen.stdout} et @ref{315e,,Popen.stderr} ne sont pas mis à jour par la méthode @ref{3148,,Popen.communicate()}.
@end quotation
@end cartouche

Si `shell' vaut @code{True}, la commande spécifiée sera exécutée à travers un `shell'.  Cela peut être utile si vous utilisez Python pour le contrôle de flot qu'il propose par rapport à beaucoup de `shells' système et voulez tout de même profiter des autres fonctionnalités des `shells' telles que les tubes (`pipes'), les motifs de fichiers, l'expansion des variables d'environnement, et l'expansion du @code{~} vers le répertoire d’accueil de l'utilisateur. Cependant, notez que Python lui-même propose l'implémentation de beaucoup de ces fonctionnalités (en particulier @ref{63,,glob}, @ref{5b,,fnmatch}, @ref{493,,os.walk()}, @ref{1390,,os.path.expandvars()}, @ref{a02,,os.path.expanduser()} et @ref{c4,,shutil}).


Modifié dans la version 3.3: Quand `universal_newlines' vaut @code{True}, la classe utilise l'encodage @ref{524,,locale.getpreferredencoding(False)} plutôt que @code{locale.getpreferredencoding()}.  Voir la classe @ref{7a5,,io.TextIOWrapper} pour plus d'informations sur ce changement.


@cartouche
@quotation Note 
Lire la section @ref{315f,,Security Considerations} avant d'utiliser @code{shell=True}.
@end quotation
@end cartouche
@end quotation

Ces options, ainsi que toutes les autres, sont décrites plus en détails dans la documentation du constructeur de @ref{197,,Popen}.

@node Constructeur de Popen,Exceptions<11>,Arguments fréquemment utilisés,Utiliser le module subprocess
@anchor{library/subprocess popen-constructor}@anchor{3160}
@subsubsection Constructeur de `Popen'


La création et la gestion sous-jacentes des processus est gérée par la classe @ref{197,,Popen}. Elle offre beaucoup de flexibilité de façon à ce que les développeurs soient capables de gérer les cas d'utilisation les moins communs, non couverts par les fonctions de convenance.

@geindex Popen (classe dans subprocess)
@anchor{library/subprocess subprocess Popen}@anchor{197}
@deffn {Classe} subprocess.Popen (args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None, pipesize=-1, process_group=None)

Execute a child program in a new process.  On POSIX, the class uses
@ref{2b47,,os.execvpe()}-like behavior to execute the child program.  On Windows,
the class uses the Windows @code{CreateProcess()} function.  The arguments to
@ref{197,,Popen} are as follows.

`args' peut être une séquence d'arguments du programme, une chaîne seule ou un @ref{29d,,objet chemin}. Par défaut, le programme à exécuter est le premier élément de `args' si `args' est une séquence. Si `args' est une chaîne de caractères, l'interprétation dépend de la plateforme et est décrite plus bas. Voir les arguments `shell' et `executable' pour d'autres différences avec le comportement par défaut. Sans autre indication, il est recommandé de passer `args' comme une séquence.

@cartouche
@quotation Avertissement 
For maximum reliability, use a fully qualified path for the executable.
To search for an unqualified name on 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}, use
@ref{49d,,shutil.which()}. On all platforms, passing @ref{3af,,sys.executable}
is the recommended way to launch the current Python interpreter again,
and use the @code{-m} command-line format to launch an installed module.

Resolving the path of `executable' (or the first item of `args') is
platform dependent. For POSIX, see @ref{2b47,,os.execvpe()}, and note that
when resolving or searching for the executable path, `cwd' overrides the
current working directory and `env' can override the @code{PATH}
environment variable. For Windows, see the documentation of the
@code{lpApplicationName} and @code{lpCommandLine} parameters of WinAPI
@code{CreateProcess}, and note that when resolving or searching for the
executable path with @code{shell=False}, `cwd' does not override the
current working directory and `env' cannot override the @code{PATH}
environment variable. Using a full path avoids all of these variations.
@end quotation
@end cartouche

Exemple de passage d'arguments, sous forme de séquence, à un autre programme:

@example
Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])
@end example

Sur les systèmes `POSIX', si `args' est une chaîne, elle est interprétée comme le nom ou le chemin du programme à exécuter.  Cependant, cela ne peut être fait que si le programme est passé sans arguments.

@cartouche
@quotation Note 
Transformer une commande shell en une séquence de commandes peut ne pas être évident. @ref{526,,shlex.split()} permet d'illustrer comment séquencer une commande correctement pour `args':

@example
>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!
@end example

Notez en particulier que les options (comme `-input') et arguments (comme `eggs.txt') qui sont séparés par des espaces dans le `shell' iront dans des éléments séparés de la liste, alors que les arguments qui nécessitent des guillemets et échappements quand utilisés dans le `shell' (comme les noms de fichiers contenant des espaces ou la commande `echo' montrée plus haut) forment des éléments uniques.
@end quotation
@end cartouche

Sous Windows, si `args' est une séquence, elle sera convertie vers une chaîne de caractères de la manière décrite dans @ref{3161,,Convertir une séquence d'arguments vers une chaîne de caractères sous Windows}.  Cela fonctionne ainsi parce que la fonction @code{CreateProcess()} opère sur des chaînes.


Modifié dans la version 3.6: Le paramètre `args' accepte un @ref{29d,,objet chemin} si `shell' vaut @code{False} et une séquence contenant des objets fichier sur POSIX.



Modifié dans la version 3.8: Le paramètre `args' accepte un @ref{29d,,objet chemin} si `shell' vaut @code{False} et une séquence contenant des chaines d'octets et des objets chemins sur Windows.


L'argument `shell' (qui vaut @code{False} par défaut) spécifie s'il faut utiliser un `shell' comme programme à exécuter.  Si `shell' vaut @code{True}, il est recommandé de passer `args' comme une chaîne de caractères plutôt qu'une séquence.

Sur les systèmes POSIX avec @code{shell=True}, le `shell' par défaut est @code{/bin/sh}.  Si `args' est une chaîne de caractères, la chaîne spécifie la commande à exécuter à travers le `shell'.  Cela signifie que la chaîne doit être formatée exactement comme elle le serait si elle était tapée dans l'invite de commandes du `shell'.  Cela inclut, par exemple, les guillemets ou les `backslashs' échappant les noms de fichiers contenant des espaces.  Si `args' est une séquence, le premier élément spécifie la commande, et les éléments supplémentaires seront traités comme des arguments additionnels à passer au `shell' lui-même.  Pour ainsi dire, @ref{197,,Popen} réalise l'équivalent de :

@example
Popen(['/bin/sh', '-c', args[0], args[1], ...])
@end example

Sous Windows avec @code{shell=True}, la variable d'environnement 
@geindex COMSPEC
@geindex variable d'environnement; COMSPEC
@code{COMSPEC} spécifie le `shell' par défaut.  La seule raison pour laquelle vous devriez spécifier @code{shell=True} sous Windows est quand la commande que vous souhaitez exécuter est une `built-in' du `shell' (p. ex. @code{dir} ou @code{copy}).  Vous n'avez pas besoin de @code{shell=True} pour lancer un fichier batch ou un exécutable console.

@cartouche
@quotation Note 
Lire la section @ref{315f,,Security Considerations} avant d'utiliser @code{shell=True}.
@end quotation
@end cartouche

`bufsize' sera fourni comme l'argument correspondant à la fonction @ref{505,,open()}, lors de la création des objets de fichiers pour les tubes `stdin'/`stdout'/`stderr' :


@itemize -

@item 
@code{0} means unbuffered (read and write are one
system call and can return short)

@item 
@code{1} means line buffered
(only usable if @code{text=True} or @code{universal_newlines=True})

@item 
toutes les autres valeurs positives indiquent d'utiliser un tampon d'approximativement cette taille ;

@item 
un `bufsize' négatif (par défaut) indique au système d'utiliser la valeur par défaut `io.DEFAULT_BUFFER_SIZE'.
@end itemize


Modifié dans la version 3.3.1: `bufsize' now defaults to -1 to enable buffering by default to match the
behavior that most code expects.  In versions prior to Python 3.2.4 and
3.3.1 it incorrectly defaulted to @code{0} which was unbuffered
and allowed short reads.  This was unintentional and did not match the
behavior of Python 2 as most code expected.


L'argument `executable' spécifie un programme de remplacement à exécuter.  Il est très rarement nécessaire.  Quand @code{shell=False}, `executable' remplace le programme à exécuter spécifié par `args'.  Cependant, les arguments originels d'`args' sont toujours passés au programme.  La plupart des programmes traitent le programme spécifié par `args' comme le nom de la commande, qui peut être différent du programme réellement exécuté.  Sur les systèmes POSIX, le nom tiré d'`args' devient le nom affiché pour l'exécutable dans des utilitaires tels que @code{ps}.  Si @code{shell=True}, sur les systèmes POSIX, l'argument `executable' précise le `shell' à utiliser plutôt que @code{/bin/sh} par défaut.


Modifié dans la version 3.6: le paramètre `executable' accepte un @ref{29d,,objet chemin} sur les systèmes POSIX.



Modifié dans la version 3.8: le paramètre `executable' accepte un objet `bytes' ou un @ref{29d,,objet chemin} sur Windows.



Modifié dans la version 3.12: Changed Windows shell search order for @code{shell=True}. The current
directory and @code{%PATH%} are replaced with @code{%COMSPEC%} and
@code{%SystemRoot%\System32\cmd.exe}. As a result, dropping a
malicious program named @code{cmd.exe} into a current directory no
longer works.


`stdin', `stdout' and `stderr' specify the executed program's standard input,
standard output and standard error file handles, respectively.  Valid values
are @code{None}, @ref{b75,,PIPE}, @ref{112e,,DEVNULL}, an existing file descriptor (a
positive integer), and an existing @ref{11a0,,file object} with a valid file
descriptor.  With the default settings of @code{None}, no redirection will
occur.  @ref{b75,,PIPE} indicates that a new pipe to the child should be
created.  @ref{112e,,DEVNULL} indicates that the special file @ref{19c1,,os.devnull}
will be used.  Additionally, `stderr' can be @ref{3147,,STDOUT}, which indicates
that the stderr data from the applications should be captured into the same
file handle as for `stdout'.

Si un objet appelable est passé à `preexec_fn', cet objet sera appelé dans le processus enfant juste avant d'exécuter le programme.  (POSIX seulement)

@cartouche
@quotation Avertissement 
The `preexec_fn' parameter is NOT SAFE to use in the presence of threads
in your application.  The child process could deadlock before exec is
called.
@end quotation
@end cartouche

@cartouche
@quotation Note 
If you need to modify the environment for the child use the `env'
parameter rather than doing it in a `preexec_fn'.
The `start_new_session' and `process_group' parameters should take the place of
code using `preexec_fn' to call @ref{1963,,os.setsid()} or @ref{2aa7,,os.setpgid()} in the child.
@end quotation
@end cartouche


Modifié dans la version 3.8: Le paramètre `preexec_fn' n'est plus pris en charge dans les sous-interpréteurs. L'utilisation de ce paramètre lève @ref{193,,RuntimeError}. Cette nouvelle restriction peut affecter les applications déployées avec `mod_wsgi', `uWSGI' et d'autres environnements qui peuvent embarquer Python.


If `close_fds' is true, all file descriptors except @code{0}, @code{1} and
@code{2} will be closed before the child process is executed.  Otherwise
when `close_fds' is false, file descriptors obey their inheritable flag
as described in @ref{ee4,,Héritage de descripteurs de fichiers}.

Sur Windows, si `close_fds' est vrai, alors aucun descripteur n'est hérité par le processus enfant à moins d'être explicitement passé dans l'élément @code{handle_list} de @ref{bfc,,STARTUPINFO.lpAttributeList}, ou par redirection des descripteurs standards.


Modifié dans la version 3.2: La valeur par défaut de `close_fds' n'est plus @ref{b25,,False}, comme décrit ci-dessus.



Modifié dans la version 3.7: Sur Windows, la valeur par défaut de `close_fds' a été changée de @ref{b25,,False} à @ref{bfb,,True} lors d'une redirection des descripteurs standards. Il est maintenant possible de donner la valeur @ref{bfb,,True} à `close_fds' lors d'une redirection de descripteurs standards.


`pass_fds' est une séquence optionnelle de descripteurs de fichiers à garder ouverts entre le parent et l'enfant.  Fournir `pass_fds' force `close_fds' à valoir @ref{bfb,,True}. (POSIX seulement)


Modifié dans la version 3.2: Ajout du paramètre `pass_fds'.


If `cwd' is not @code{None}, the function changes the working directory to
`cwd' before executing the child.  `cwd' can be a string, bytes or
@ref{29d,,path-like} object.  On POSIX, the function
looks for `executable' (or for the first item in `args') relative to `cwd'
if the executable path is a relative path.


Modifié dans la version 3.6: le paramètre `cwd' accepte un @ref{29d,,objet chemin} sur les systèmes POSIX.



Modifié dans la version 3.7: le paramètre `cwd' accepte un @ref{29d,,objet chemin} sur Windows.



Modifié dans la version 3.8: le paramètre `cwd' accepte une séquence d'octets sur Windows


Si `restore_signals' est vrai (par défaut), tous les signaux que Python a mis à `SIG_IGN' sont restaurés à `SIG_DFL' dans le processus fils avant l'appel à `exec'.  Actuellement, cela inclut les signaux `SIGPIPE', `SIGXFZ' et `SIGXFSZ'.  (POSIX seulement)


Modifié dans la version 3.2: Ajout de `restore_signals'.


If `start_new_session' is true the @code{setsid()} system call will be made in the
child process prior to the execution of the subprocess.

@ref{1ce0,,Availability}: POSIX


Modifié dans la version 3.2: Ajout de `start_new_session'.


If `process_group' is a non-negative integer, the @code{setpgid(0, value)} system call will
be made in the child process prior to the execution of the subprocess.

@ref{1ce0,,Availability}: POSIX


Modifié dans la version 3.11: `process_group' was added.


If `group' is not @code{None}, the setregid() system call will be made in the
child process prior to the execution of the subprocess. If the provided
value is a string, it will be looked up via @ref{3162,,grp.getgrnam()} and
the value in @code{gr_gid} will be used. If the value is an integer, it
will be passed verbatim. (POSIX only)

@ref{1ce0,,Availability}: POSIX


Ajouté dans la version 3.9.


If `extra_groups' is not @code{None}, the setgroups() system call will be
made in the child process prior to the execution of the subprocess.
Strings provided in `extra_groups' will be looked up via
@ref{3162,,grp.getgrnam()} and the values in @code{gr_gid} will be used.
Integer values will be passed verbatim. (POSIX only)

@ref{1ce0,,Availability}: POSIX


Ajouté dans la version 3.9.


If `user' is not @code{None}, the setreuid() system call will be made in the
child process prior to the execution of the subprocess. If the provided
value is a string, it will be looked up via @ref{3163,,pwd.getpwnam()} and
the value in @code{pw_uid} will be used. If the value is an integer, it will
be passed verbatim. (POSIX only)

@ref{1ce0,,Availability}: POSIX


Ajouté dans la version 3.9.


If `umask' is not negative, the umask() system call will be made in the
child process prior to the execution of the subprocess.

@ref{1ce0,,Availability}: POSIX


Ajouté dans la version 3.9.


If `env' is not @code{None}, it must be a mapping that defines the environment
variables for the new process; these are used instead of the default
behavior of inheriting the current process' environment. This mapping can be
str to str on any platform or bytes to bytes on POSIX platforms much like
@ref{1197,,os.environ} or @ref{11f4,,os.environb}.

@cartouche
@quotation Note 
Si spécifié, `env' doit fournir chaque variable requise pour l'exécution du programme.  Sous Windows, afin d'exécuter un side-by-side assembly@footnote{https://en.wikipedia.org/wiki/Side-by-Side_Assembly}, l'environnement `env' spécifié `doit' contenir une variable 
@geindex SystemRoot
@geindex variable d'environnement; SystemRoot
@code{SystemRoot} valide.
@end quotation
@end cartouche

If `encoding' or `errors' are specified, or `text' is true, the file objects
`stdin', `stdout' and `stderr' are opened in text mode with the specified
`encoding' and `errors', as described above in @ref{3146,,Arguments fréquemment utilisés}.
The `universal_newlines' argument is equivalent  to `text' and is provided
for backwards compatibility. By default, file objects are opened in binary mode.


Ajouté dans la version 3.6: Ajout d'`encoding' et `errors'.



Ajouté dans la version 3.7: `text' a été ajouté comme un alias plus lisible de `universal_newlines'.


If given, `startupinfo' will be a @ref{3164,,STARTUPINFO} object, which is
passed to the underlying @code{CreateProcess} function.

If given, `creationflags', can be one or more of the following flags:


@itemize *

@item 
@ref{3165,,CREATE_NEW_CONSOLE}

@item 
@ref{3166,,CREATE_NEW_PROCESS_GROUP}

@item 
@ref{3167,,ABOVE_NORMAL_PRIORITY_CLASS}

@item 
@ref{3168,,BELOW_NORMAL_PRIORITY_CLASS}

@item 
@ref{3169,,HIGH_PRIORITY_CLASS}

@item 
@ref{316a,,IDLE_PRIORITY_CLASS}

@item 
@ref{316b,,NORMAL_PRIORITY_CLASS}

@item 
@ref{316c,,REALTIME_PRIORITY_CLASS}

@item 
@ref{316d,,CREATE_NO_WINDOW}

@item 
@ref{316e,,DETACHED_PROCESS}

@item 
@ref{316f,,CREATE_DEFAULT_ERROR_MODE}

@item 
@ref{3170,,CREATE_BREAKAWAY_FROM_JOB}
@end itemize

`pipesize' can be used to change the size of the pipe when
@ref{b75,,PIPE} is used for `stdin', `stdout' or `stderr'. The size of the pipe
is only changed on platforms that support this (only Linux at this time of
writing). Other platforms will ignore this parameter.


Modifié dans la version 3.10: Added the `pipesize' parameter.


Les objets `Popen' sont gérés comme gestionnaires de contexte avec l'instruction @ref{5bc,,with} : à la sortie, les descripteurs de fichiers standards sont fermés, et le processus est attendu

@example
with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())
@end example

`Popen' et les autres fonctions dans ce module qui l'utilisent lèvent un @ref{1848,,évènement d'audit} @code{subprocess.Popen} avec comme arguments @code{executable}, @code{args}, @code{cwd} et @code{env}. La valeur pour @code{args} peut être une simple chaîne de caractères ou une liste de chaînes, en fonction de la plateforme.


Modifié dans la version 3.2: Ajout de la gestion des gestionnaires de contexte.



Modifié dans la version 3.6: Le destructeur de `Popen' émet maintenant un avertissement @ref{241,,ResourceWarning} si le processus fils est toujours en cours d'exécution.



Modifié dans la version 3.8: `Popen' peut utiliser @ref{21d,,os.posix_spawn()} dans certains cas pour de meilleures performances. Sur le sous-système Linux de Windows et sur `QEMU' en mode utilisateur, le constructeur de `Popen' utilisant @ref{21d,,os.posix_spawn()} ne lève plus d'exception sur les erreurs comme programme manquant, mais le processus enfant échoue avec un @ref{1936,,returncode} différent de zéro.

@end deffn

@node Exceptions<11>,,Constructeur de Popen,Utiliser le module subprocess
@anchor{library/subprocess exceptions}@anchor{3171}
@subsubsection Exceptions


Les exceptions levées dans le processus fils, avant que le nouveau programme ait commencé à s'exécuter, seront ré-levées dans le parent.

The most common exception raised is @ref{40d,,OSError}.  This occurs, for example,
when trying to execute a non-existent file.  Applications should prepare for
@ref{40d,,OSError} exceptions. Note that, when @code{shell=True}, @ref{40d,,OSError}
will be raised by the child only if the selected shell itself was not found.
To determine if the shell failed to find the requested application, it is
necessary to check the return code or output from the subprocess.

Une @ref{1ff,,ValueError} sera levée si @ref{197,,Popen} est appelé avec des arguments invalides.

@ref{3155,,check_call()} et @ref{fac,,check_output()} lèveront une @ref{1302,,CalledProcessError} si le processus appelé renvoie un code de retour non nul.

All of the functions and methods that accept a `timeout' parameter, such as
@ref{b74,,run()} and @ref{3148,,Popen.communicate()} will raise @ref{3149,,TimeoutExpired} if
the timeout expires before the process exits.

Toutes les exceptions définies dans ce module héritent de @ref{314f,,SubprocessError}.


Ajouté dans la version 3.3: Ajout de la classe de base @ref{314f,,SubprocessError}.


@node Considérations de sécurité,Objets Popen,Utiliser le module subprocess,subprocess --- Subprocess management
@anchor{library/subprocess security-considerations}@anchor{315f}@anchor{library/subprocess subprocess-security}@anchor{3172}
@subsubsection Considérations de sécurité


Unlike some other popen functions, this library will not
implicitly choose to call a system shell.  This means that all characters,
including shell metacharacters, can safely be passed to child processes.
If the shell is invoked explicitly, via @code{shell=True}, it is the application's
responsibility to ensure that all whitespace and metacharacters are
quoted appropriately to avoid
shell injection@footnote{https://en.wikipedia.org/wiki/Shell_injection#Shell_injection}
vulnerabilities. On @ref{3173,,some platforms}, it is possible
to use @ref{27a,,shlex.quote()} for this escaping.

On Windows, batch files (@code{*.bat} or @code{*.cmd}) may be launched by the
operating system in a system shell regardless of the arguments passed to this
library. This could result in arguments being parsed according to shell rules,
but without any escaping added by Python. If you are intentionally launching a
batch file with arguments from untrusted sources, consider passing
@code{shell=True} to allow Python to escape special characters. See gh-114539@footnote{https://github.com/python/cpython/issues/114539}
for additional discussion.

@node Objets Popen,Utilitaires Popen pour Windows,Considérations de sécurité,subprocess --- Subprocess management
@anchor{library/subprocess popen-objects}@anchor{3174}
@subsubsection Objets `Popen'


Les instances de la classe @ref{197,,Popen} possèdent les méthodes suivantes :

@geindex poll() (méthode subprocess.Popen)
@anchor{library/subprocess subprocess Popen poll}@anchor{3175}
@deffn {Méthode} Popen.poll ()

Vérifie que le processus enfant s'est terminé.  Modifie et renvoie l'attribut @ref{1936,,returncode}, sinon, renvoie @code{None}.
@end deffn

@geindex wait() (méthode subprocess.Popen)
@anchor{library/subprocess subprocess Popen wait}@anchor{cd2}
@deffn {Méthode} Popen.wait (timeout=None)

Attend qu'un processus enfant se termine.  Modifie l'attribut @ref{1936,,returncode} et le renvoie.

Si le processus ne se termine pas après le nombre de secondes spécifié par `timeout', une exception @ref{3149,,TimeoutExpired} est levée.  Cela ne pose aucun problème d'attraper cette exception et de réessayer d'attendre.

@cartouche
@quotation Note 
Cela provoquera un blocage (`deadlock') lors de l'utilisation de @code{stdout=PIPE} ou @code{stderr=PIPE} si le processus fils génère tellement de données sur le tube qu'il le bloque, en attente que le système d'exploitation permette au tampon du tube d'accepter plus de données.  Utilisez @ref{3148,,Popen.communicate()} pour éviter ce problème lors de l'utilisation de tubes.
@end quotation
@end cartouche

@cartouche
@quotation Note 
When the @code{timeout} parameter is not @code{None}, then (on POSIX) the
function is implemented using a busy loop (non-blocking call and short
sleeps). Use the @ref{a,,asyncio} module for an asynchronous wait: see
@ref{a65,,asyncio.create_subprocess_exec}.
@end quotation
@end cartouche


Modifié dans la version 3.3: Ajout de `timeout'.

@end deffn

@geindex communicate() (méthode subprocess.Popen)
@anchor{library/subprocess subprocess Popen communicate}@anchor{3148}
@deffn {Méthode} Popen.communicate (input=None, timeout=None)

Interact with process: Send data to stdin.  Read data from stdout and stderr,
until end-of-file is reached.  Wait for process to terminate and set the
@ref{1936,,returncode} attribute.  The optional `input' argument should be
data to be sent to the child process, or @code{None}, if no data should be sent
to the child.  If streams were opened in text mode, `input' must be a string.
Otherwise, it must be bytes.

@ref{3148,,communicate()} renvoie une paire @code{(stdout_data, stderr_data)}. Les données seront des chaînes de caractères si les flux sont ouverts en mode texte, et des objets `bytes' dans le cas contraire.

Notez que si vous souhaitez envoyer des données sur l'entrée standard du processus, vous devez créer l'objet `Popen' avec @code{stdin=PIPE}.  Similairement, pour obtenir autre chose que @code{None} dans le `n'-uplet résultant, vous devez aussi préciser @code{stdout=PIPE} et/ou @code{stderr=PIPE}.

Si le processus ne se termine pas après `timeout' secondes, une exception @ref{3149,,TimeoutExpired} est levée.  Attraper cette exception et retenter la communication ne fait perdre aucune donnée de sortie.

Le processus enfant n'est pas tué si le `timeout' expire, donc afin de nettoyer proprement le tout, une application polie devrait tuer le processus fils et terminer la communication :

@example
proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()
@end example

@cartouche
@quotation Note 
Les données lues sont mises en cache en mémoire, donc n'utilisez pas cette méthode si la taille des données est importante voire illimitée.
@end quotation
@end cartouche


Modifié dans la version 3.3: Ajout de `timeout'.

@end deffn

@geindex send_signal() (méthode subprocess.Popen)
@anchor{library/subprocess subprocess Popen send_signal}@anchor{1395}
@deffn {Méthode} Popen.send_signal (signal)

Envoie le signal `signal' au fils.

Do nothing if the process completed.

@cartouche
@quotation Note 
On Windows, SIGTERM is an alias for @ref{1393,,terminate()}. CTRL_C_EVENT and
CTRL_BREAK_EVENT can be sent to processes started with a `creationflags'
parameter which includes @code{CREATE_NEW_PROCESS_GROUP}.
@end quotation
@end cartouche
@end deffn

@geindex terminate() (méthode subprocess.Popen)
@anchor{library/subprocess subprocess Popen terminate}@anchor{1393}
@deffn {Méthode} Popen.terminate ()

Stop the child. On POSIX OSs the method sends @ref{1396,,SIGTERM} to the
child. On Windows the Win32 API function @code{TerminateProcess()} is called
to stop the child.
@end deffn

@geindex kill() (méthode subprocess.Popen)
@anchor{library/subprocess subprocess Popen kill}@anchor{1394}
@deffn {Méthode} Popen.kill ()

Tue le processus fils. Sur les systèmes POSIX, la fonction envoie un signal `SIGKILL' au fils. Sous Windows, @ref{1394,,kill()} est un alias pour @ref{1393,,terminate()}.
@end deffn

The following attributes are also set by the class for you to access.
Reassigning them to new values is unsupported:

@geindex args (attribut subprocess.Popen)
@anchor{library/subprocess subprocess Popen args}@anchor{3176}
@deffn {Attribut} Popen.args

L'argument `args' tel que passé à @ref{197,,Popen} -- une séquence d'arguments du programme ou une simple chaîne de caractères.


Ajouté dans la version 3.3.

@end deffn

@geindex stdin (attribut subprocess.Popen)
@anchor{library/subprocess subprocess Popen stdin}@anchor{315c}
@deffn {Attribut} Popen.stdin

If the `stdin' argument was @ref{b75,,PIPE}, this attribute is a writeable
stream object as returned by @ref{505,,open()}. If the `encoding' or `errors'
arguments were specified or the `text' or `universal_newlines' argument
was @code{True}, the stream is a text stream, otherwise it is a byte stream.
If the `stdin' argument was not @ref{b75,,PIPE}, this attribute is @code{None}.
@end deffn

@geindex stdout (attribut subprocess.Popen)
@anchor{library/subprocess subprocess Popen stdout}@anchor{315d}
@deffn {Attribut} Popen.stdout

If the `stdout' argument was @ref{b75,,PIPE}, this attribute is a readable
stream object as returned by @ref{505,,open()}. Reading from the stream provides
output from the child process. If the `encoding' or `errors' arguments were
specified or the `text' or `universal_newlines' argument was @code{True}, the
stream is a text stream, otherwise it is a byte stream. If the `stdout'
argument was not @ref{b75,,PIPE}, this attribute is @code{None}.
@end deffn

@geindex stderr (attribut subprocess.Popen)
@anchor{library/subprocess subprocess Popen stderr}@anchor{315e}
@deffn {Attribut} Popen.stderr

If the `stderr' argument was @ref{b75,,PIPE}, this attribute is a readable
stream object as returned by @ref{505,,open()}. Reading from the stream provides
error output from the child process. If the `encoding' or `errors' arguments
were specified or the `text' or `universal_newlines' argument was @code{True}, the
stream is a text stream, otherwise it is a byte stream. If the `stderr' argument
was not @ref{b75,,PIPE}, this attribute is @code{None}.
@end deffn

@cartouche
@quotation Avertissement 
Utilisez @ref{3148,,communicate()} plutôt que @ref{315c,,.stdin.write}, @ref{315d,,.stdout.read} ou @ref{315e,,.stderr.read} pour empêcher les `deadlocks' dus au remplissage des tampons des tubes de l'OS et bloquant le processus enfant.
@end quotation
@end cartouche

@geindex pid (attribut subprocess.Popen)
@anchor{library/subprocess subprocess Popen pid}@anchor{3177}
@deffn {Attribut} Popen.pid

L'identifiant de processus du processus enfant.

Notez que si vous passez l'argument `shell' à @code{True}, il s'agit alors de l'identifiant du `shell' instancié.
@end deffn

@geindex returncode (attribut subprocess.Popen)
@anchor{library/subprocess subprocess Popen returncode}@anchor{1936}
@deffn {Attribut} Popen.returncode

The child return code. Initially @code{None}, @ref{1936,,returncode} is set by
a call to the @ref{3175,,poll()}, @ref{cd2,,wait()}, or @ref{3148,,communicate()} methods
if they detect that the process has terminated.

A @code{None} value indicates that the process hadn't yet terminated at the
time of the last method call.

Une valeur négative @code{-N} indique que le processus enfant a été terminé par un signal @code{N} (seulement sur les systèmes `POSIX').
@end deffn

@node Utilitaires Popen pour Windows,Ancienne interface API haut-niveau,Objets Popen,subprocess --- Subprocess management
@anchor{library/subprocess windows-popen-helpers}@anchor{3178}
@subsubsection Utilitaires `Popen' pour Windows


La classe @ref{3164,,STARTUPINFO} et les constantes suivantes sont seulement disponibles sous Windows.

@geindex STARTUPINFO (classe dans subprocess)
@anchor{library/subprocess subprocess STARTUPINFO}@anchor{3164}
@deffn {Classe} subprocess.STARTUPINFO (*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

Une gestion partielle de la structure STARTUPINFO@footnote{https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx} est utilisée lors de la création d'un objet @ref{197,,Popen}. Les attributs ci-dessous peuvent être passés en tant que paramètres `keyword-only'.


Modifié dans la version 3.7: Ajout de la gestion des paramètres `keyword-only'.


@geindex dwFlags (attribut subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO dwFlags}@anchor{3179}
@deffn {Attribut} dwFlags

Un champ de bits déterminant si certains attributs @ref{3164,,STARTUPINFO} sont utilisés quand le processus crée une fenêtre

@example
si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW
@end example
@end deffn

@geindex hStdInput (attribut subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO hStdInput}@anchor{317a}
@deffn {Attribut} hStdInput

Si @ref{3179,,dwFlags} spécifie @ref{317b,,STARTF_USESTDHANDLES}, cet attribut est le descripteur d'entrée standard du processus. Si @ref{317b,,STARTF_USESTDHANDLES} n'est pas spécifié, l'entrée standard par défaut est le tampon du clavier.
@end deffn

@geindex hStdOutput (attribut subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO hStdOutput}@anchor{317c}
@deffn {Attribut} hStdOutput

Si @ref{3179,,dwFlags} spécifie @ref{317b,,STARTF_USESTDHANDLES}, cet attribut est le descripteur de sortie standard du processus. Autrement, l'attribut est ignoré et la sortie standard par défaut est le tampon de la console.
@end deffn

@geindex hStdError (attribut subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO hStdError}@anchor{317d}
@deffn {Attribut} hStdError

Si @ref{3179,,dwFlags} spécifie @ref{317b,,STARTF_USESTDHANDLES}, cet attribut est le descripteur de sortie d'erreur du processus. Autrement, l'attribut est ignoré et la sortie d'erreur par défaut est le tampon de la console.
@end deffn

@geindex wShowWindow (attribut subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO wShowWindow}@anchor{317e}
@deffn {Attribut} wShowWindow

Si @ref{3179,,dwFlags} spécifie @ref{317f,,STARTF_USESHOWWINDOW}, cet attribut peut-être n'importe quel attribut valide pour le paramètre @code{nCmdShow} de la fonction ShowWindow@footnote{https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx}, à l'exception de @code{SW_SHOWDEFAULT}. Autrement, cet attribut est ignoré.

@ref{3180,,SW_HIDE} est fourni pour cet attribut. Il est utilisé quand @ref{197,,Popen} est appelée avec @code{shell=True}.
@end deffn

@geindex lpAttributeList (attribut subprocess.STARTUPINFO)
@anchor{library/subprocess subprocess STARTUPINFO lpAttributeList}@anchor{bfc}
@deffn {Attribut} lpAttributeList

Dictionnaire des attributs supplémentaires pour la création d'un processus comme donnés dans @code{STARTUPINFOEX}, lisez UpdateProcThreadAttribute@footnote{https://msdn.microsoft.com/en-us/library/windows/desktop/ms686880(v=vs.85).aspx} (ressource en anglais).

Attributs gérés :


@table @asis

@item `handle_list'

Séquence des descripteurs qui hérités du parent. `close_fds' doit être vrai si la séquence n'est pas vide.

Les descripteurs doivent être temporairement héritables par @ref{ee8,,os.set_handle_inheritable()} quand ils sont passés au constructeur @ref{197,,Popen}, sinon @ref{40d,,OSError} est levée avec l'erreur Windows @code{ERROR_INVALID_PARAMETER} (87).

@cartouche
@quotation Avertissement 
Dans un processus avec plusieurs fils d'exécution, faites très attention à éviter la fuite de descripteurs qui sont marqués comme héritables quand vous combinez ceci avec des appels concurrents vers des fonctions de création d'autres processus qui héritent de tous les descripteurs (telle que @ref{1411,,os.system()}).
@end quotation
@end cartouche
@end table


Ajouté dans la version 3.7.

@end deffn
@end deffn

@menu
* Constantes Windows:: 

@end menu

@node Constantes Windows,,,Utilitaires Popen pour Windows
@anchor{library/subprocess windows-constants}@anchor{3181}
@subsubsection Constantes Windows


Le module @ref{d5,,subprocess} expose les constantes suivantes.

@geindex STD_INPUT_HANDLE (dans le module subprocess)
@anchor{library/subprocess subprocess STD_INPUT_HANDLE}@anchor{3182}
@deffn {Données} subprocess.STD_INPUT_HANDLE

Le périphérique d'entrée standard. Initialement, il s'agit du tampon de la console d'entrée, @code{CONIN$}.
@end deffn

@geindex STD_OUTPUT_HANDLE (dans le module subprocess)
@anchor{library/subprocess subprocess STD_OUTPUT_HANDLE}@anchor{3183}
@deffn {Données} subprocess.STD_OUTPUT_HANDLE

Le périphérique de sortie standard. Initialement, il s'agit du tampon de l'écran de console actif, @code{CONOUT$}.
@end deffn

@geindex STD_ERROR_HANDLE (dans le module subprocess)
@anchor{library/subprocess subprocess STD_ERROR_HANDLE}@anchor{3184}
@deffn {Données} subprocess.STD_ERROR_HANDLE

Le périphérique de sortie d'erreur. Initialement, il s'agit du tampon de l'écran de console actif, @code{CONOUT$}.
@end deffn

@geindex SW_HIDE (dans le module subprocess)
@anchor{library/subprocess subprocess SW_HIDE}@anchor{3180}
@deffn {Données} subprocess.SW_HIDE

Cache la fenêtre. Une autre fenêtre sera activée.
@end deffn

@geindex STARTF_USESTDHANDLES (dans le module subprocess)
@anchor{library/subprocess subprocess STARTF_USESTDHANDLES}@anchor{317b}
@deffn {Données} subprocess.STARTF_USESTDHANDLES

Spécifie que les attributs @ref{317a,,STARTUPINFO.hStdInput}, @ref{317c,,STARTUPINFO.hStdOutput} et @ref{317d,,STARTUPINFO.hStdError} contiennent des informations additionnelles.
@end deffn

@geindex STARTF_USESHOWWINDOW (dans le module subprocess)
@anchor{library/subprocess subprocess STARTF_USESHOWWINDOW}@anchor{317f}
@deffn {Données} subprocess.STARTF_USESHOWWINDOW

Spécifie que l'attribut @ref{317e,,STARTUPINFO.wShowWindow} contient des informations additionnelles.
@end deffn

@geindex STARTF_FORCEONFEEDBACK (dans le module subprocess)
@anchor{library/subprocess subprocess STARTF_FORCEONFEEDBACK}@anchor{3185}
@deffn {Données} subprocess.STARTF_FORCEONFEEDBACK

A @ref{3179,,STARTUPINFO.dwFlags} parameter to specify that the
`Working in Background' mouse cursor will be displayed while a
process is launching. This is the default behavior for GUI
processes.


Ajouté dans la version 3.13.

@end deffn

@geindex STARTF_FORCEOFFFEEDBACK (dans le module subprocess)
@anchor{library/subprocess subprocess STARTF_FORCEOFFFEEDBACK}@anchor{3186}
@deffn {Données} subprocess.STARTF_FORCEOFFFEEDBACK

A @ref{3179,,STARTUPINFO.dwFlags} parameter to specify that the mouse
cursor will not be changed when launching a process.


Ajouté dans la version 3.13.

@end deffn

@geindex CREATE_NEW_CONSOLE (dans le module subprocess)
@anchor{library/subprocess subprocess CREATE_NEW_CONSOLE}@anchor{3165}
@deffn {Données} subprocess.CREATE_NEW_CONSOLE

Le nouveau processus instancie une nouvelle console, plutôt que d'hériter de celle de son père (par défaut).
@end deffn

@geindex CREATE_NEW_PROCESS_GROUP (dans le module subprocess)
@anchor{library/subprocess subprocess CREATE_NEW_PROCESS_GROUP}@anchor{3166}
@deffn {Données} subprocess.CREATE_NEW_PROCESS_GROUP

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier si un nouveau groupe de processus doit être créé. Cette option est nécessaire pour utiliser @ref{133e,,os.kill()} sur le sous-processus.

L'option est ignorée si @ref{3165,,CREATE_NEW_CONSOLE} est spécifié.
@end deffn

@geindex ABOVE_NORMAL_PRIORITY_CLASS (dans le module subprocess)
@anchor{library/subprocess subprocess ABOVE_NORMAL_PRIORITY_CLASS}@anchor{3167}
@deffn {Données} subprocess.ABOVE_NORMAL_PRIORITY_CLASS

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un processus aura une priorité au-dessus de la moyenne.


Ajouté dans la version 3.7.

@end deffn

@geindex BELOW_NORMAL_PRIORITY_CLASS (dans le module subprocess)
@anchor{library/subprocess subprocess BELOW_NORMAL_PRIORITY_CLASS}@anchor{3168}
@deffn {Données} subprocess.BELOW_NORMAL_PRIORITY_CLASS

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un processus aura une priorité au-dessous de la moyenne.


Ajouté dans la version 3.7.

@end deffn

@geindex HIGH_PRIORITY_CLASS (dans le module subprocess)
@anchor{library/subprocess subprocess HIGH_PRIORITY_CLASS}@anchor{3169}
@deffn {Données} subprocess.HIGH_PRIORITY_CLASS

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un processus aura une priorité haute.


Ajouté dans la version 3.7.

@end deffn

@geindex IDLE_PRIORITY_CLASS (dans le module subprocess)
@anchor{library/subprocess subprocess IDLE_PRIORITY_CLASS}@anchor{316a}
@deffn {Données} subprocess.IDLE_PRIORITY_CLASS

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un processus aura la priorité la plus basse (inactif ou `idle').


Ajouté dans la version 3.7.

@end deffn

@geindex NORMAL_PRIORITY_CLASS (dans le module subprocess)
@anchor{library/subprocess subprocess NORMAL_PRIORITY_CLASS}@anchor{316b}
@deffn {Données} subprocess.NORMAL_PRIORITY_CLASS

A @ref{197,,Popen} @code{creationflags} parameter to specify that a new process
will have a normal priority. (default)


Ajouté dans la version 3.7.

@end deffn

@geindex REALTIME_PRIORITY_CLASS (dans le module subprocess)
@anchor{library/subprocess subprocess REALTIME_PRIORITY_CLASS}@anchor{316c}
@deffn {Données} subprocess.REALTIME_PRIORITY_CLASS

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu’un nouveau processus aura une priorité en temps réel. Vous ne devriez presque JAMAIS utiliser @code{REALTIME_PRIORITY_CLASS}, car cela interrompt les fils d’exécution système qui gèrent les entrées de la souris, du clavier et `flush' le cache de disque en arrière-plan. Cette classe peut convenir aux applications qui « parlent » directement au matériel ou qui effectuent de brèves tâches nécessitant des interruptions limitées.


Ajouté dans la version 3.7.

@end deffn

@geindex CREATE_NO_WINDOW (dans le module subprocess)
@anchor{library/subprocess subprocess CREATE_NO_WINDOW}@anchor{316d}
@deffn {Données} subprocess.CREATE_NO_WINDOW

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un processus ne créera pas une nouvelle fenêtre.


Ajouté dans la version 3.7.

@end deffn

@geindex DETACHED_PROCESS (dans le module subprocess)
@anchor{library/subprocess subprocess DETACHED_PROCESS}@anchor{316e}
@deffn {Données} subprocess.DETACHED_PROCESS

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un nouveau processus n'héritera pas de la console du processus parent. Cette valeur ne peut pas être utilisée avec CREATE_NEW_CONSOLE.


Ajouté dans la version 3.7.

@end deffn

@geindex CREATE_DEFAULT_ERROR_MODE (dans le module subprocess)
@anchor{library/subprocess subprocess CREATE_DEFAULT_ERROR_MODE}@anchor{316f}
@deffn {Données} subprocess.CREATE_DEFAULT_ERROR_MODE

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un nouveau processus n'hérite pas du mode de gestion des erreurs du processus appelant. À la place, le nouveau processus acquiert le mode d'erreur par défaut. Cette fonctionnalité est particulièrement utile pour les applications `shell' avec de multiples fils d'exécution qui s'exécutent avec les erreurs irréversibles désactivées.


Ajouté dans la version 3.7.

@end deffn

@geindex CREATE_BREAKAWAY_FROM_JOB (dans le module subprocess)
@anchor{library/subprocess subprocess CREATE_BREAKAWAY_FROM_JOB}@anchor{3170}
@deffn {Données} subprocess.CREATE_BREAKAWAY_FROM_JOB

Paramètre @code{creationflags} de @ref{197,,Popen} pour spécifier qu'un processus n'est pas associé au `job'.


Ajouté dans la version 3.7.

@end deffn

@node Ancienne interface API haut-niveau,Remplacer les fonctions plus anciennes par le module subprocess,Utilitaires Popen pour Windows,subprocess --- Subprocess management
@anchor{library/subprocess call-function-trio}@anchor{3187}@anchor{library/subprocess older-high-level-api}@anchor{3188}
@subsubsection Ancienne interface (`API') haut-niveau


Avant Python 3.5, ces trois fonctions représentaient l'API haut-niveau de `subprocess'. Vous pouvez maintenant utiliser @ref{b74,,run()} dans de nombreux cas, mais beaucoup de codes existant font appel à ces trois fonctions.

@geindex call() (dans le module subprocess)
@anchor{library/subprocess subprocess call}@anchor{b76}
@deffn {Fonction} subprocess.call (args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Lance la commande décrite par `args', attend qu'elle se termine, et renvoie son attribut @ref{1936,,returncode}.

Le code ayant besoin de capturer `stdout' ou `stderr' doit plutôt utiliser :@ref{b74,,run()} :

@example
run(...).returncode
@end example

Pour supprimer `stdout' ou `stderr', passez la valeur @ref{112e,,DEVNULL}.

Les arguments montrés plus haut sont sûrement les plus communs. La signature complète de la fonction est en grande partie la même que le constructeur de @ref{197,,Popen} : cette fonction passe tous les arguments fournis autre que `timeout' directement à travers cette interface.

@cartouche
@quotation Note 
N'utilisez pas @code{stdout=PIPE} ou @code{stderr=PIPE} avec cette fonction.  Le processus enfant bloquera s'il génère assez de données pour remplir le tampon du tube de l'OS, puisque les tubes ne seront jamais lus.
@end quotation
@end cartouche


Modifié dans la version 3.3: Ajout de `timeout'.



Modifié dans la version 3.12: Changed Windows shell search order for @code{shell=True}. The current
directory and @code{%PATH%} are replaced with @code{%COMSPEC%} and
@code{%SystemRoot%\System32\cmd.exe}. As a result, dropping a
malicious program named @code{cmd.exe} into a current directory no
longer works.

@end deffn

@geindex check_call() (dans le module subprocess)
@anchor{library/subprocess subprocess check_call}@anchor{3155}
@deffn {Fonction} subprocess.check_call (args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Run command with arguments.  Wait for command to complete. If the return
code was zero then return, otherwise raise @ref{1302,,CalledProcessError}. The
@ref{1302,,CalledProcessError} object will have the return code in the
@ref{3156,,returncode} attribute.
If @ref{3155,,check_call()} was unable to start the process it will propagate the exception
that was raised.

Le code ayant besoin de capturer `stdout' ou `stderr' doit plutôt utiliser :@ref{b74,,run()} :

@example
run(..., check=True)
@end example

Pour supprimer `stdout' ou `stderr', passez la valeur @ref{112e,,DEVNULL}.

Les arguments montrés plus haut sont sûrement les plus communs. La signature complète de la fonction est en grande partie la même que le constructeur de @ref{197,,Popen} : cette fonction passe tous les arguments fournis autre que `timeout' directement à travers cette interface.

@cartouche
@quotation Note 
N'utilisez pas @code{stdout=PIPE} ou @code{stderr=PIPE} avec cette fonction.  Le processus enfant bloquera s'il génère assez de données pour remplir le tampon du tube de l'OS, puisque les tubes ne seront jamais lus.
@end quotation
@end cartouche


Modifié dans la version 3.3: Ajout de `timeout'.



Modifié dans la version 3.12: Changed Windows shell search order for @code{shell=True}. The current
directory and @code{%PATH%} are replaced with @code{%COMSPEC%} and
@code{%SystemRoot%\System32\cmd.exe}. As a result, dropping a
malicious program named @code{cmd.exe} into a current directory no
longer works.

@end deffn

@geindex check_output() (dans le module subprocess)
@anchor{library/subprocess subprocess check_output}@anchor{fac}
@deffn {Fonction} subprocess.check_output (args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)

Lance la commande avec les arguments et renvoie sa sortie.

Si le code de retour est non-nul, la fonction lève une @ref{1302,,CalledProcessError}. L'objet @ref{1302,,CalledProcessError} contiendra le code de retour dans son attribut @ref{3156,,returncode}, et la sortie du programme dans son attribut @ref{3158,,output}.

C’est équivalent à :

@example
run(..., check=True, stdout=PIPE).stdout
@end example

The arguments shown above are merely some common ones.
The full function signature is largely the same as that of @ref{b74,,run()} -
most arguments are passed directly through to that interface.
One API deviation from @ref{b74,,run()} behavior exists: passing @code{input=None}
will behave the same as @code{input=b'@w{'}} (or @code{input='@w{'}}, depending on other
arguments) rather than using the parent's standard input file handle.

Par défaut, cette fonction renvoie les données encodées sous forme de `bytes'. Le réel encodage des données de sortie peut dépendre de la commande invoquée, donc le décodage du texte devra souvent être géré au niveau de l'application.

Ce comportement peut être redéfini en mettant `text', `encoding', `errors', ou `universal_newlines' à @code{True} comme décrit dans @ref{3146,,Arguments fréquemment utilisés} et @ref{b74,,run()}.

Pour capturer aussi la sortie d'erreur dans le résultat, utilisez @code{stderr=subprocess.STDOUT} :

@example
>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'
@end example


Ajouté dans la version 3.1.



Modifié dans la version 3.3: Ajout de `timeout'.



Modifié dans la version 3.4: Ajout de la gestion de l'argument nommé `input'.



Modifié dans la version 3.6: Ajout d'`encoding' et `errors'. Consultez @ref{b74,,run()} pour plus d'informations.



Ajouté dans la version 3.7: `text' a été ajouté comme un alias plus lisible de `universal_newlines'.



Modifié dans la version 3.12: Changed Windows shell search order for @code{shell=True}. The current
directory and @code{%PATH%} are replaced with @code{%COMSPEC%} and
@code{%SystemRoot%\System32\cmd.exe}. As a result, dropping a
malicious program named @code{cmd.exe} into a current directory no
longer works.

@end deffn

@node Remplacer les fonctions plus anciennes par le module subprocess,Remplacement des fonctions originales d'invocation du shell,Ancienne interface API haut-niveau,subprocess --- Subprocess management
@anchor{library/subprocess replacing-older-functions-with-the-subprocess-module}@anchor{3189}@anchor{library/subprocess subprocess-replacements}@anchor{1168}
@subsubsection Remplacer les fonctions plus anciennes par le module @code{subprocess}


Dans cette section, « a devient b » signifie que b peut être utilisée en remplacement de a.

@cartouche
@quotation Note 
Toutes les fonctions « a » dans cette section échouent (plus ou moins) silencieusement si le programme à exécuter ne peut être trouvé ; les fonctions « b » de remplacement lèvent à la place une @ref{40d,,OSError}.

De plus, les remplacements utilisant @ref{fac,,check_output()} échoueront avec une @ref{1302,,CalledProcessError} si l'opération requise produit un code de retour non-nul. La sortie est toujours disponible par l'attribut @ref{3158,,output} de l'exception levée.
@end quotation
@end cartouche

Dans les exemples suivants, nous supposons que les fonctions utilisées ont déjà été importées depuis le module @ref{d5,,subprocess}.

@menu
* Remplacement de la substitution de commandes de terminal /bin/sh:: 
* Remplacer les pipes du shell:: 
* Remplacer os.system(): Remplacer os system. 
* Remplacer les fonctions de la famille os.spawn: Remplacer les fonctions de la famille os spawn. 
* Remplacer os.popen()@comma{} os.popen2()@comma{} os.popen3(): Remplacer os popen os popen2 os popen3. 
* Replacing functions from the popen2 module:: 

@end menu

@node Remplacement de la substitution de commandes de terminal /bin/sh,Remplacer les pipes du shell,,Remplacer les fonctions plus anciennes par le module subprocess
@anchor{library/subprocess replacing-bin-sh-shell-command-substitution}@anchor{318a}
@subsubsection Remplacement de la substitution de commandes de terminal @code{/bin/sh}


@example
output=$(mycmd myarg)
@end example

devient :

@example
output = check_output(["mycmd", "myarg"])
@end example

@node Remplacer les pipes du shell,Remplacer os system,Remplacement de la substitution de commandes de terminal /bin/sh,Remplacer les fonctions plus anciennes par le module subprocess
@anchor{library/subprocess replacing-shell-pipeline}@anchor{318b}
@subsubsection Remplacer les `pipes' du `shell'


@example
output=$(dmesg | grep hda)
@end example

devient :

@example
p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]
@end example

L'appel à @code{p1.stdout.close()} après le démarrage de `p2' est important pour que `p1' reçoive un `SIGPIPE' si `p2' se termine avant lui.

Alternativement, pour des entrées fiables, la gestion des tubes du `shell' peut directement être utilisé :

@example
output=$(dmesg | grep hda)
@end example

devient :

@example
output = check_output("dmesg | grep hda", shell=True)
@end example

@node Remplacer os system,Remplacer les fonctions de la famille os spawn,Remplacer les pipes du shell,Remplacer les fonctions plus anciennes par le module subprocess
@anchor{library/subprocess replacing-os-system}@anchor{318c}
@subsubsection Remplacer @code{os.system()}


@example
sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)
@end example

Notes :


@itemize *

@item 
Appeler le programme à travers un `shell' n'est habituellement pas requis.

@item 
The @ref{b76,,call()} return value is encoded differently to that of
@ref{1411,,os.system()}.

@item 
The @ref{1411,,os.system()} function ignores SIGINT and SIGQUIT signals while
the command is running, but the caller must do this separately when
using the @ref{d5,,subprocess} module.
@end itemize

Un exemple plus réaliste ressemblerait à cela :

@example
try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)
@end example

@node Remplacer les fonctions de la famille os spawn,Remplacer os popen os popen2 os popen3,Remplacer os system,Remplacer les fonctions plus anciennes par le module subprocess
@anchor{library/subprocess replacing-the-os-spawn-family}@anchor{318d}
@subsubsection Remplacer les fonctions de la famille @code{os.spawn}


Exemple avec `P_NOWAIT' :

@example
pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid
@end example

Exemple avec `P_WAIT' :

@example
retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])
@end example

Exemple avec un tableau :

@example
os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])
@end example

Exemple en passant un environnement :

@example
os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env=@{"PATH": "/usr/bin"@})
@end example

@node Remplacer os popen os popen2 os popen3,Replacing functions from the popen2 module,Remplacer les fonctions de la famille os spawn,Remplacer les fonctions plus anciennes par le module subprocess
@anchor{library/subprocess replacing-os-popen-os-popen2-os-popen3}@anchor{318e}
@subsubsection Remplacer @code{os.popen()}, @code{os.popen2()}, @code{os.popen3()}


@example
(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)
@end example

@example
(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)
@end example

@example
(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
@end example

La gestion du code de retour se traduit comme suit :

@example
pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")
@end example

@node Replacing functions from the popen2 module,,Remplacer os popen os popen2 os popen3,Remplacer les fonctions plus anciennes par le module subprocess
@anchor{library/subprocess replacing-functions-from-the-popen2-module}@anchor{318f}
@subsubsection Replacing functions from the @code{popen2} module


@cartouche
@quotation Note 
Si l'argument `cmd' des fonctions de `popen2' est une chaîne de caractères, la commande est exécutée à travers `/bin/sh'.  Si c'est une liste, la commande est directement exécutée.
@end quotation
@end cartouche

@example
(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
@end example

@example
(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
@end example

@code{popen2.Popen3} et @code{popen2.Popen4} fonctionnent basiquement comme @ref{197,,subprocess.Popen}, excepté que :


@itemize *

@item 
@ref{197,,Popen} lève une exception si l'exécution échoue.

@item 
L'argument `capturestderr' est remplacé par `stderr'.

@item 
@code{stdin=PIPE} et @code{stdout=PIPE} doivent être spécifiés.

@item 
`popen2' ferme tous les descripteurs de fichiers par défaut, mais vous devez spécifier @code{close_fds=True} avec @ref{197,,Popen} pour garantir ce comportement sur toutes les plateformes ou les anciennes versions de Python.
@end itemize

@node Remplacement des fonctions originales d'invocation du shell,Notes<2>,Remplacer les fonctions plus anciennes par le module subprocess,subprocess --- Subprocess management
@anchor{library/subprocess legacy-shell-invocation-functions}@anchor{3190}
@subsubsection Remplacement des fonctions originales d'invocation du `shell'


Ce module fournit aussi les fonctions suivantes héritées du module @code{commands} de Python 2.x. Ces opérations invoquent implicitement le `shell' du système et n'apportent aucune des garanties décrites ci-dessus par rapport à la sécurité ou la cohérence de la gestion des exceptions.

@geindex getstatusoutput() (dans le module subprocess)
@anchor{library/subprocess subprocess getstatusoutput}@anchor{fad}
@deffn {Fonction} subprocess.getstatusoutput (cmd, *, encoding=None, errors=None)

Renvoie les valeurs @code{(exitcode, output)} de l'exécution de `cmd' dans un `shell'.

Execute the string `cmd' in a shell with @code{Popen.check_output()} and
return a 2-tuple @code{(exitcode, output)}.
`encoding' and `errors' are used to decode output;
see the notes on @ref{3146,,Arguments fréquemment utilisés} for more details.

Si la sortie se termine par un caractère de fin de ligne, ce dernier est supprimé. Le code de statut de la commande peut être interprété comme le code de retour de `subprocess'.  Par exemple :

@example
>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(127, 'sh: /bin/junk: not found')
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '@w{'})
@end example

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.3.4: Ajout de la gestion de Windows.

La fonction renvoie maintenant @code{(exitcode, output)} plutôt que @code{(status, output)} comme dans les versions de Python 3.3.3 ou antérieures.  `exitcode' vaut la même valeur que @ref{1936,,returncode}.



Modifié dans la version 3.11: Added the `encoding' and `errors' parameters.

@end deffn

@geindex getoutput() (dans le module subprocess)
@anchor{library/subprocess subprocess getoutput}@anchor{1789}
@deffn {Fonction} subprocess.getoutput (cmd, *, encoding=None, errors=None)

Renvoie la sortie (standard et d'erreur) de l'exécution de `cmd' dans un `shell'.

Comme @ref{fad,,getstatusoutput()}, à l'exception que le code de statut est ignoré et que la valeur de retour est une chaîne contenant la sortie de la commande.  Exemple :

@example
>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'
@end example

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.3.4: Ajout de la gestion de Windows



Modifié dans la version 3.11: Added the `encoding' and `errors' parameters.

@end deffn

@node Notes<2>,,Remplacement des fonctions originales d'invocation du shell,subprocess --- Subprocess management
@anchor{library/subprocess notes}@anchor{3191}
@subsubsection Notes


@menu
* Convertir une séquence d'arguments vers une chaîne de caractères sous Windows:: 
* Disabling use of vfork() or posix_spawn(): Disabling use of vfork or posix_spawn. 

@end menu

@node Convertir une séquence d'arguments vers une chaîne de caractères sous Windows,Disabling use of vfork or posix_spawn,,Notes<2>
@anchor{library/subprocess converting-an-argument-sequence-to-a-string-on-windows}@anchor{3192}@anchor{library/subprocess converting-argument-sequence}@anchor{3161}
@subsubsection Convertir une séquence d'arguments vers une chaîne de caractères sous Windows


Sous Windows, une séquence `args' est convertie vers une chaîne qui peut être analysée avec les règles suivantes (qui correspondent aux règles utilisées par l'environnement `MS C') :


@enumerate 

@item 
Les arguments sont délimités par des espacements, qui peuvent être des espaces ou des tabulations.

@item 
Une chaîne entourée de double guillemets est interprétée comme un argument seul, qu'elle contienne ou non des espacements.  Une chaîne entre guillemets peut être intégrée dans un argument.

@item 
Un guillemet double précédé d'un `backslash' est interprété comme un guillemet double littéral.

@item 
Les `backslashs' sont interprétés littéralement, à moins qu'ils précèdent immédiatement un guillemet double.

@item 
Si des `backslashs' précèdent directement un guillemet double, toute paire de `backslashs' est interprétée comme un `backslash' littéral.  Si le nombre de `backslashs' est impair, le dernier `backslash' échappe le prochain guillemet double comme décrit en règle 3.
@end enumerate


@subsubheading Voir aussi



@table @asis

@item @ref{c3,,shlex}

Module qui fournit des fonctions pour analyser et échapper les lignes de commandes.
@end table

@anchor{library/subprocess disable-vfork}@anchor{3193}
@node Disabling use of vfork or posix_spawn,,Convertir une séquence d'arguments vers une chaîne de caractères sous Windows,Notes<2>
@anchor{library/subprocess disable-posix-spawn}@anchor{3194}@anchor{library/subprocess disabling-use-of-vfork-or-posix-spawn}@anchor{3195}
@subsubsection Disabling use of @code{vfork()} or @code{posix_spawn()}


On Linux, @ref{d5,,subprocess} defaults to using the @code{vfork()} system call
internally when it is safe to do so rather than @code{fork()}. This greatly
improves performance.

If you ever encounter a presumed highly unusual situation where you need to
prevent @code{vfork()} from being used by Python, you can set the
@code{subprocess._USE_VFORK} attribute to a false value.

@example
subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.
@end example

Setting this has no impact on use of @code{posix_spawn()} which could use
@code{vfork()} internally within its libc implementation.  There is a similar
@code{subprocess._USE_POSIX_SPAWN} attribute if you need to prevent use of
that.

@example
subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.
@end example

It is safe to set these to false on any Python version. They will have no
effect on older versions when unsupported. Do not assume the attributes are
available to read. Despite their names, a true value does not indicate that the
corresponding function will be used, only that it may be.

Please file issues any time you have to use these private knobs with a way to
reproduce the issue you were seeing. Link to that issue from a comment in your
code.


Ajouté dans la version 3.8: @code{_USE_POSIX_SPAWN}



Ajouté dans la version 3.11: @code{_USE_VFORK}


@node sched --- Event scheduler,queue --- A synchronized queue class,subprocess --- Subprocess management,Exécution concourante
@anchor{library/sched doc}@anchor{3196}@anchor{library/sched module-sched}@anchor{be}@anchor{library/sched sched-event-scheduler}@anchor{3197}
@subsection @code{sched} --- Event scheduler


@geindex module; sched

`Code source :' Lib/sched.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/sched.py}

@geindex event scheduling


__________________________________________________________________


The @ref{be,,sched} module defines a class which implements a general purpose event
scheduler:

@geindex scheduler (classe dans sched)
@anchor{library/sched sched scheduler}@anchor{1107}
@deffn {Classe} sched.scheduler (timefunc=time.monotonic, delayfunc=time.sleep)

The @ref{1107,,scheduler} class defines a generic interface to scheduling events.
It needs two functions to actually deal with the "outside world" --- `timefunc'
should be callable without arguments, and return  a number (the "time", in any
units whatsoever).  The `delayfunc' function should be callable with one
argument, compatible with the output of `timefunc', and should delay that many
time units. `delayfunc' will also be called with the argument @code{0} after each
event is run to allow other threads an opportunity to run in multi-threaded
applications.


Modifié dans la version 3.3: `timefunc' and `delayfunc' parameters are optional.



Modifié dans la version 3.3: @ref{1107,,scheduler} class can be safely used in multi-threaded
environments.

@end deffn

Exemple :

@example
>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(a='default'):
...     print("From print_time", time.time(), a)
...
>>> def print_some_times():
...     print(time.time())
...     s.enter(10, 1, print_time)
...     s.enter(5, 2, print_time, argument=('positional',))
...     # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative
...     s.enter(5, 1, print_time, kwargs=@{'a': 'keyword'@})
...     s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",))
...     s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",))
...     s.run()
...     print(time.time())
...
>>> print_some_times()
1652342830.3640375
From print_time 1652342830.3642538 second enterabs
From print_time 1652342830.3643398 first enterabs
From print_time 1652342835.3694863 positional
From print_time 1652342835.3696074 keyword
From print_time 1652342840.369612 default
1652342840.3697174
@end example

@menu
* Scheduler Objects:: 

@end menu

@node Scheduler Objects,,,sched --- Event scheduler
@anchor{library/sched id1}@anchor{3198}@anchor{library/sched scheduler-objects}@anchor{3199}
@subsubsection Scheduler Objects


@ref{1107,,scheduler} instances have the following methods and attributes:

@geindex enterabs() (méthode sched.scheduler)
@anchor{library/sched sched scheduler enterabs}@anchor{1109}
@deffn {Méthode} scheduler.enterabs (time, priority, action, argument=(), kwargs=@{@})

Schedule a new event. The `time' argument should be a numeric type compatible
with the return value of the `timefunc' function passed  to the constructor.
Events scheduled for the same `time' will be executed in the order of their
`priority'. A lower number represents a higher priority.

Executing the event means executing @code{action(*argument, **kwargs)}.
`argument' is a sequence holding the positional arguments for `action'.
`kwargs' is a dictionary holding the keyword arguments for `action'.

Return value is an event which may be used for later cancellation of the event
(see @ref{18bd,,cancel()}).


Modifié dans la version 3.3: `argument' parameter is optional.



Modifié dans la version 3.3: `kwargs' parameter was added.

@end deffn

@geindex enter() (méthode sched.scheduler)
@anchor{library/sched sched scheduler enter}@anchor{1108}
@deffn {Méthode} scheduler.enter (delay, priority, action, argument=(), kwargs=@{@})

Schedule an event for `delay' more time units. Other than the relative time, the
other arguments, the effect and the return value are the same as those for
@ref{1109,,enterabs()}.


Modifié dans la version 3.3: `argument' parameter is optional.



Modifié dans la version 3.3: `kwargs' parameter was added.

@end deffn

@geindex cancel() (méthode sched.scheduler)
@anchor{library/sched sched scheduler cancel}@anchor{18bd}
@deffn {Méthode} scheduler.cancel (event)

Remove the event from the queue. If `event' is not an event currently in the
queue, this method will raise a @ref{1ff,,ValueError}.
@end deffn

@geindex empty() (méthode sched.scheduler)
@anchor{library/sched sched scheduler empty}@anchor{319a}
@deffn {Méthode} scheduler.empty ()

Return @code{True} if the event queue is empty.
@end deffn

@geindex run() (méthode sched.scheduler)
@anchor{library/sched sched scheduler run}@anchor{1106}
@deffn {Méthode} scheduler.run (blocking=True)

Run all scheduled events. This method will wait  (using the `delayfunc'
function passed to the constructor) for the next event, then execute it and so
on until there are no more scheduled events.

If `blocking' is false executes the scheduled events due to expire soonest
(if any) and then return the deadline of the next scheduled call in the
scheduler (if any).

Either `action' or `delayfunc' can raise an exception.  In either case, the
scheduler will maintain a consistent state and propagate the exception.  If an
exception is raised by `action', the event will not be attempted in future calls
to @ref{1106,,run()}.

If a sequence of events takes longer to run than the time available before the
next event, the scheduler will simply fall behind.  No events will be dropped;
the calling code is responsible for canceling  events which are no longer
pertinent.


Modifié dans la version 3.3: `blocking' parameter was added.

@end deffn

@geindex queue (attribut sched.scheduler)
@anchor{library/sched sched scheduler queue}@anchor{319b}
@deffn {Attribut} scheduler.queue

Read-only attribute returning a list of upcoming events in the order they
will be run.  Each event is shown as a @ref{639,,named tuple} with the
following fields:  time, priority, action, argument, kwargs.
@end deffn

@node queue --- A synchronized queue class,contextvars --- Context Variables,sched --- Event scheduler,Exécution concourante
@anchor{library/queue doc}@anchor{319c}@anchor{library/queue module-queue}@anchor{b5}@anchor{library/queue queue-a-synchronized-queue-class}@anchor{319d}
@subsection @code{queue} --- A synchronized queue class


@geindex module; queue

`Code source :' Lib/queue.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/queue.py}


__________________________________________________________________


Le module @ref{b5,,queue} implémente des files multi-productrices et multi-consommatrices. C'est particulièrement utile en programmation `multi-thread', lorsque les informations doivent être échangées sans risques entre plusieurs `threads'. La classe @ref{1365,,Queue} de ce module implémente tout le verrouillage nécessaire.

The module implements three types of queue, which differ only in the order in
which the entries are retrieved.  In a @abbr{FIFO}
queue, the first tasks added are the first retrieved.  In a
@abbr{LIFO} queue, the most recently added entry is
the first retrieved (operating like a stack).  With a priority queue,
the entries are kept sorted (using the @ref{68,,heapq} module) and the
lowest valued entry is retrieved first.

En interne, ces trois types de files utilisent des verrous pour bloquer temporairement des fils d'exécution concurrents. Cependant, ils n'ont pas été conçus pour être réentrants au sein d'un fil d'exécution.

Le module implémente aussi une @abbr{FIFO} basique, @ref{b58,,SimpleQueue}, dont l’implémentation spécialisée fournit plus de garanties au détriment des fonctionnalités.

Le module @ref{b5,,queue} définit les classes et les exceptions suivantes :

@geindex Queue (classe dans queue)
@anchor{library/queue queue Queue}@anchor{1365}
@deffn {Classe} queue.Queue (maxsize=0)

Constructeur pour une file @abbr{FIFO}. `maxsize' est un entier définissant le nombre maximal d'éléments pouvant être mis dans la file. L'insertion sera bloquée lorsque cette borne supérieure sera atteinte, jusqu'à ce que des éléments de la file soient consommés. Si `maxsize' est inférieur ou égal à 0, la taille de la file sera infinie.
@end deffn

@geindex LifoQueue (classe dans queue)
@anchor{library/queue queue LifoQueue}@anchor{21df}
@deffn {Classe} queue.LifoQueue (maxsize=0)

Constructeur pour une file @abbr{LIFO}. `maxsize' est un entier définissant le nombre maximal d'éléments pouvant être mis dans la file. L'insertion sera bloquée lorsque cette borne supérieure sera atteinte, jusqu'à ce que des éléments de la file soient consommés. Si `maxsize' est inférieur ou égal à 0, la taille de la file sera infinie.
@end deffn

@geindex PriorityQueue (classe dans queue)
@anchor{library/queue queue PriorityQueue}@anchor{21e0}
@deffn {Classe} queue.PriorityQueue (maxsize=0)

Constructeur pour une file de priorité. `maxsize' est un entier définissant le nombre maximal d'éléments pouvant être mis dans la file. L'insertion sera bloquée lorsque cette borne supérieure sera atteinte, jusqu'à ce que des éléments soient consommés. Si `maxsize' est inférieur ou égal à 0, la taille de la file sera infinie.

The lowest valued entries are retrieved first (the lowest valued entry is the
one that would be returned by @code{min(entries)}).  A typical pattern for
entries is a tuple in the form: @code{(priority_number, data)}.

Si les éléments de `data' ne sont pas comparables, les données peuvent être enveloppées dans une classe qui ignore l'élément de données et ne compare que l'ordre de priorité :

@example
from dataclasses import dataclass, field
from typing import Any

@@dataclass(order=True)
class PrioritizedItem:
    priority: int
    item: Any=field(compare=False)
@end example
@end deffn

@geindex SimpleQueue (classe dans queue)
@anchor{library/queue queue SimpleQueue}@anchor{b58}
@deffn {Classe} queue.SimpleQueue

Constructeur d'une file illimitée @abbr{FIFO}. Les simples files d'attente ne possèdent pas de fonctionnalités avancées telles que le suivi des tâches.


Ajouté dans la version 3.7.

@end deffn

@geindex Empty
@anchor{library/queue queue Empty}@anchor{30b1}
@deffn {Exception} queue.Empty

Exception levée lorsque la méthode non bloquante @ref{2c53,,get()} (ou @ref{319e,,get_nowait()}) est appelée sur l'objet @ref{1365,,Queue} vide.
@end deffn

@geindex Full
@anchor{library/queue queue Full}@anchor{30b2}
@deffn {Exception} queue.Full

Exception levée lorsque la méthode non bloquante @ref{319f,,put()} (ou @ref{2c52,,put_nowait()}) est appelée sur un objet @ref{1365,,Queue} plein.
@end deffn

@geindex ShutDown
@anchor{library/queue queue ShutDown}@anchor{238}
@deffn {Exception} queue.ShutDown

Exception raised when @ref{319f,,put()} or @ref{2c53,,get()} is called on
a @ref{1365,,Queue} object which has been shut down.


Ajouté dans la version 3.13.

@end deffn

@menu
* Objets Queue:: 
* Objets SimpleQueue:: 

@end menu

@node Objets Queue,Objets SimpleQueue,,queue --- A synchronized queue class
@anchor{library/queue queue-objects}@anchor{31a0}@anchor{library/queue queueobjects}@anchor{31a1}
@subsubsection Objets @code{Queue}


Les objets `Queue' (@ref{1365,,Queue}, @ref{21df,,LifoQueue} ou @ref{21e0,,PriorityQueue}) fournissent les méthodes publiques décrites ci-dessous.

@geindex qsize() (méthode queue.Queue)
@anchor{library/queue queue Queue qsize}@anchor{31a2}
@deffn {Méthode} Queue.qsize ()

Renvoie la taille approximative de la file.  Notez que @code{qsize() > 0} ne garantit pas qu'un @code{get()} ultérieur ne sera pas bloquant et que @code{qsize() < maxsize} ne garantit pas non plus qu'un @code{put()} ne sera pas bloquant.
@end deffn

@geindex empty() (méthode queue.Queue)
@anchor{library/queue queue Queue empty}@anchor{31a3}
@deffn {Méthode} Queue.empty ()

Renvoie @code{True} si la file est vide, @code{False} sinon.  Si @code{empty()} renvoie @code{True}, cela ne garantit pas qu'un appel ultérieur à @code{put()} ne sera pas bloquant.  Similairement, si @code{empty()} renvoie @code{False}, cela ne garantit pas qu'un appel ultérieur à @code{get()} ne sera pas bloquant.
@end deffn

@geindex full() (méthode queue.Queue)
@anchor{library/queue queue Queue full}@anchor{31a4}
@deffn {Méthode} Queue.full ()

Renvoie @code{True} si la file est pleine, @code{False} sinon.  Si @code{full()} renvoie @code{True}, cela ne garantit pas qu'un appel ultérieur à @code{get()} ne sera pas bloquant.  Similairement, si @code{full()} retourne @code{False}, cela ne garantit pas qu'un appel ultérieur à @code{put()} ne sera pas bloquant.
@end deffn

@geindex put() (méthode queue.Queue)
@anchor{library/queue queue Queue put}@anchor{319f}
@deffn {Méthode} Queue.put (item, block=True, timeout=None)

Put `item' into the queue.  If optional args `block' is true and `timeout' is
@code{None} (the default), block if necessary until a free slot is available.  If
`timeout' is a positive number, it blocks at most `timeout' seconds and raises
the @ref{30b2,,Full} exception if no free slot was available within that time.
Otherwise (`block' is false), put an item on the queue if a free slot is
immediately available, else raise the @ref{30b2,,Full} exception (`timeout' is
ignored in that case).

Raises @ref{238,,ShutDown} if the queue has been shut down.
@end deffn

@geindex put_nowait() (méthode queue.Queue)
@anchor{library/queue queue Queue put_nowait}@anchor{2c52}
@deffn {Méthode} Queue.put_nowait (item)

Equivalent to @code{put(item, block=False)}.
@end deffn

@geindex get() (méthode queue.Queue)
@anchor{library/queue queue Queue get}@anchor{2c53}
@deffn {Méthode} Queue.get (block=True, timeout=None)

Retire et renvoie un élément de la file. Si les arguments optionnels `block' et `timeout' valent respectivement @code{True} et @code{None} (les valeurs par défaut), la méthode bloque si nécessaire jusqu'à ce qu'un élément soit disponible. Si `timeout' est un entier positif, elle bloque au plus `timeout' secondes et lève l'exception @ref{30b1,,Empty} s'il n'y avait pas d'élément disponible pendant cette période de temps. Sinon (`block' vaut @code{False}), elle renvoie un élément s'il y en a un immédiatement disponible. Si ce n'est pas le cas, elle lève l'exception @ref{30b1,,Empty} (`timeout' est ignoré dans ce cas).

Prior to 3.0 on POSIX systems, and for all versions on Windows, if
`block' is true and `timeout' is @code{None}, this operation goes into
an uninterruptible wait on an underlying lock.  This means that no exceptions
can occur, and in particular a SIGINT will not trigger a @ref{9bf,,KeyboardInterrupt}.

Raises @ref{238,,ShutDown} if the queue has been shut down and is empty, or if
the queue has been shut down immediately.
@end deffn

@geindex get_nowait() (méthode queue.Queue)
@anchor{library/queue queue Queue get_nowait}@anchor{319e}
@deffn {Méthode} Queue.get_nowait ()

Équivalent à @code{get(False)}.
@end deffn

Deux méthodes sont proposées afin de savoir si les tâches mises dans la file ont été entièrement traitées par les fils d'exécution consommateurs du démon.

@geindex task_done() (méthode queue.Queue)
@anchor{library/queue queue Queue task_done}@anchor{30ad}
@deffn {Méthode} Queue.task_done ()

Indique qu'une tâche précédemment mise dans la file est terminée. Utilisé par les fils d'exécution consommateurs de la file. Pour chaque appel à @ref{2c53,,get()} effectué afin de récupérer une tâche, un appel ultérieur à @ref{30ad,,task_done()} informe la file que le traitement de la tâche est terminé.

Si un @ref{30ae,,join()} est actuellement bloquant, on reprendra lorsque tous les éléments auront été traités (ce qui signifie qu'un appel à @ref{30ad,,task_done()} a été effectué pour chaque élément qui a été @ref{319f,,put()} dans la file).

@code{shutdown(immediate=True)} calls @ref{30ad,,task_done()} for each remaining item
in the queue.

Lève une exception @ref{1ff,,ValueError} si appelée plus de fois qu'il y avait d'éléments dans la file.
@end deffn

@geindex join() (méthode queue.Queue)
@anchor{library/queue queue Queue join}@anchor{30ae}
@deffn {Méthode} Queue.join ()

Bloque jusqu'à ce que tous les éléments de la file aient été obtenus et traités.

The count of unfinished tasks goes up whenever an item is added to the queue.
The count goes down whenever a consumer thread calls @ref{30ad,,task_done()} to
indicate that the item was retrieved and all work on it is complete.  When the
count of unfinished tasks drops to zero, @ref{30ae,,join()} unblocks.
@end deffn

Exemple montrant comment attendre que les tâches mises dans la file soient terminées :

@example
import threading
import queue

q = queue.Queue()

def worker():
    while True:
        item = q.get()
        print(f'Working on @{item@}')
        print(f'Finished @{item@}')
        q.task_done()

# Turn-on the worker thread.
threading.Thread(target=worker, daemon=True).start()

# Send thirty task requests to the worker.
for item in range(30):
    q.put(item)

# Block until all tasks are done.
q.join()
print('All work completed')
@end example

@menu
* Terminating queues:: 

@end menu

@node Terminating queues,,,Objets Queue
@anchor{library/queue terminating-queues}@anchor{31a5}
@subsubsection Terminating queues


@ref{1365,,Queue} objects can be made to prevent further interaction by shutting
them down.

@geindex shutdown() (méthode queue.Queue)
@anchor{library/queue queue Queue shutdown}@anchor{237}
@deffn {Méthode} Queue.shutdown (immediate=False)

Shut down the queue, making @ref{2c53,,get()} and @ref{319f,,put()} raise
@ref{238,,ShutDown}.

By default, @ref{2c53,,get()} on a shut down queue will only raise once the
queue is empty. Set `immediate' to true to make @ref{2c53,,get()} raise
immediately instead.

All blocked callers of @ref{319f,,put()} and @ref{2c53,,get()} will be
unblocked. If `immediate' is true, a task will be marked as done for each
remaining item in the queue, which may unblock callers of
@ref{30ae,,join()}.


Ajouté dans la version 3.13.

@end deffn

@node Objets SimpleQueue,,Objets Queue,queue --- A synchronized queue class
@anchor{library/queue simplequeue-objects}@anchor{31a6}
@subsubsection Objets @code{SimpleQueue}


Les objets @ref{b58,,SimpleQueue} fournissent les méthodes publiques décrites ci-dessous.

@geindex qsize() (méthode queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue qsize}@anchor{31a7}
@deffn {Méthode} SimpleQueue.qsize ()

Renvoie la taille approximative de la file. Notez que @code{qsize() > 0} ne garantit pas qu'un @code{get()} ultérieur ne soit pas bloquant.
@end deffn

@geindex empty() (méthode queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue empty}@anchor{31a8}
@deffn {Méthode} SimpleQueue.empty ()

Return @code{True} if the queue is empty, @code{False} otherwise.  If empty()
returns @code{False} it doesn't guarantee that a subsequent call to get()
will not block.
@end deffn

@geindex put() (méthode queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue put}@anchor{31a9}
@deffn {Méthode} SimpleQueue.put (item, block=True, timeout=None)

Met `item' dans la file. La méthode ne bloque jamais et aboutit toujours (sauf en cas de potentielles erreurs de bas niveau, telles qu'un échec d'allocation de mémoire). Les arguments optionnels `block' et `timeout' sont ignorés et fournis uniquement pour la compatibilité avec @ref{319f,,Queue.put()}.

`Particularité de l'implémentation CPython :' This method has a C implementation which is reentrant.  That is, a
@code{put()} or @code{get()} call can be interrupted by another @code{put()}
call in the same thread without deadlocking or corrupting internal
state inside the queue.  This makes it appropriate for use in
destructors such as @code{__del__} methods or @ref{113,,weakref} callbacks.
@end deffn

@geindex put_nowait() (méthode queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue put_nowait}@anchor{31aa}
@deffn {Méthode} SimpleQueue.put_nowait (item)

Equivalent to @code{put(item, block=False)}, provided for compatibility with
@ref{2c52,,Queue.put_nowait()}.
@end deffn

@geindex get() (méthode queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue get}@anchor{31ab}
@deffn {Méthode} SimpleQueue.get (block=True, timeout=None)

Retire et renvoie un élément de la file. Si les arguments optionnels `block' et `timeout' valent respectivement @code{True} et @code{None} (les valeurs par défaut), la méthode bloque si nécessaire jusqu'à ce qu'un élément soit disponible. Si `timeout' est un entier positif, elle bloque au plus `timeout' secondes et lève l'exception @ref{30b1,,Empty} s'il n'y avait pas d'élément disponible pendant cette période de temps. Sinon (`block' vaut @code{False}), elle renvoie un élément s'il y en a un immédiatement disponible. Si ce n'est pas le cas, elle lève l'exception @ref{30b1,,Empty} (`timeout' est ignoré dans ce cas).
@end deffn

@geindex get_nowait() (méthode queue.SimpleQueue)
@anchor{library/queue queue SimpleQueue get_nowait}@anchor{31ac}
@deffn {Méthode} SimpleQueue.get_nowait ()

Équivalent à @code{get(False)}.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Classe @ref{178a,,multiprocessing.Queue}

Une file à utiliser dans un contexte multi-processus (plutôt que `multi-thread').
@end table

@ref{5c6,,collections.deque} est une implémentation alternative de file non bornée avec des méthodes @ref{2490,,append()} et @ref{2496,,popleft()} rapides et atomiques ne nécessitant pas de verrouillage et prenant également en charge l'indexation.


@node contextvars --- Context Variables,_thread --- Low-level threading API,queue --- A synchronized queue class,Exécution concourante
@anchor{library/contextvars doc}@anchor{31ad}@anchor{library/contextvars contextvars-context-variables}@anchor{31ae}@anchor{library/contextvars module-contextvars}@anchor{24}
@subsection @code{contextvars} --- Context Variables


@geindex module; contextvars


__________________________________________________________________


Ce module fournit des API pour gérer, stocker et accéder à l'état local de contexte. La classe @ref{31af,,ContextVar} est utilisée pour déclarer et travailler avec les `Variables de contexte'. La fonction @ref{31b0,,copy_context()} et la classe @ref{152f,,Context} doivent être utilisées pour la gestion du contexte actuel dans les cadriciels asynchrones.

Context managers that have state should use Context Variables
instead of @ref{16f9,,threading.local()} to prevent their state from
bleeding to other code unexpectedly, when used in concurrent code.

Voir aussi 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} pour plus de détails.


Ajouté dans la version 3.7.


@menu
* Variables de contexte:: 
* Gestion de contexte manuelle:: 
* Gestion avec asyncio:: 

@end menu

@node Variables de contexte,Gestion de contexte manuelle,,contextvars --- Context Variables
@anchor{library/contextvars context-variables}@anchor{31b1}
@subsubsection Variables de contexte


@geindex ContextVar (classe dans contextvars)
@anchor{library/contextvars contextvars ContextVar}@anchor{31af}
@deffn {Classe} contextvars.ContextVar (name[, *, default])

Cette classe est utilisée pour déclarer une nouvelle variable de contexte, p. ex :

@example
var: ContextVar[int] = ContextVar('var', default=42)
@end example

Le paramètre requis `name' est utilisé à des fins d'introspection et de débogage.

Le paramètre nommé `default' est renvoyé par @ref{31b2,,ContextVar.get()} quand aucune valeur n'est trouvée dans le contexte actuel pour la variable.

`Important :' les variables de contexte doivent être créées au plus haut niveau du module et jamais dans des fermetures (`closures'). Les objets @ref{152f,,Context} maintiennent des références fortes aux variables de contexte ce qui empêche que les variables de contexte soient correctement nettoyées par le ramasse-miette.

@geindex name (attribut contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar name}@anchor{31b3}
@deffn {Attribut} name

Nom de la variable. Cette propriété est en lecture seule.


Ajouté dans la version 3.7.1.

@end deffn

@geindex get() (méthode contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar get}@anchor{31b2}
@deffn {Méthode} get ([default])

Renvoie la valeur de la variable de contexte pour le contexte actuel.

S'il n'y a pas de valeur pour la variable dans le contexte actuel, la méthode :


@itemize *

@item 
renvoie la valeur de l'argument `default' passé à la méthode, s'il a été fourni ;

@item 
ou renvoie la valeur par défaut de la variable de contexte, si elle a été créée avec une valeur par défaut ;

@item 
ou lève une erreur @ref{2155,,LookupError}.
@end itemize
@end deffn

@geindex set() (méthode contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar set}@anchor{31b4}
@deffn {Méthode} set (value)

Assigne une nouvelle valeur à la variable de contexte dans le contexte actuel.

L'argument requis `value' est la nouvelle valeur pour la variable de contexte.

Renvoie un objet @ref{31b5,,Token} qui peut être utilisé pour rétablir la variable à sa valeur précédente par la méthode @ref{31b6,,ContextVar.reset()}.
@end deffn

@geindex reset() (méthode contextvars.ContextVar)
@anchor{library/contextvars contextvars ContextVar reset}@anchor{31b6}
@deffn {Méthode} reset (token)

Réinitialise la variable de contexte à la valeur qu'elle avait avant l'appel de @ref{31b4,,ContextVar.set()} qui a créé le `token'.

Par exemple :

@example
var = ContextVar('var')

token = var.set('new value')
# code that uses 'var'; var.get() returns 'new value'.
var.reset(token)

# After the reset call the var has no value again, so
# var.get() would raise a LookupError.
@end example
@end deffn
@end deffn

@geindex Token (classe dans contextvars)
@anchor{library/contextvars contextvars Token}@anchor{31b5}
@deffn {Classe} contextvars.Token

Les objets `Token' sont renvoyés par la méthode @ref{31b4,,ContextVar.set()}. Ils peuvent être passés à la méthode @ref{31b6,,ContextVar.reset()} pour réaffecter la valeur de la variable à ce qu'elle était avant le `set' correspondant.

@geindex var (attribut contextvars.Token)
@anchor{library/contextvars contextvars Token var}@anchor{31b7}
@deffn {Attribut} var

Propriété en lecture seule. Pointe vers l'objet @ref{31af,,ContextVar} qui a créé le token.
@end deffn

@geindex old_value (attribut contextvars.Token)
@anchor{library/contextvars contextvars Token old_value}@anchor{31b8}
@deffn {Attribut} old_value

A read-only property.  Set to the value the variable had before
the @ref{31b4,,ContextVar.set()} method call that created the token.
It points to @ref{31b9,,Token.MISSING} if the variable was not set
before the call.
@end deffn

@geindex MISSING (attribut contextvars.Token)
@anchor{library/contextvars contextvars Token MISSING}@anchor{31b9}
@deffn {Attribut} MISSING

Objet marqueur utilisé par @ref{31b8,,Token.old_value}.
@end deffn
@end deffn

@node Gestion de contexte manuelle,Gestion avec asyncio,Variables de contexte,contextvars --- Context Variables
@anchor{library/contextvars manual-context-management}@anchor{31ba}
@subsubsection Gestion de contexte manuelle


@geindex copy_context() (dans le module contextvars)
@anchor{library/contextvars contextvars copy_context}@anchor{31b0}
@deffn {Fonction} contextvars.copy_context ()

Renvoie une copie de l'objet @ref{152f,,Context} actuel.

Le fragment de code qui suit obtient une copie du contexte actuel et affiche toutes les variables avec leurs valeurs définies dans ce contexte :

@example
ctx: Context = copy_context()
print(list(ctx.items()))
@end example

The function has an `O'(1) complexity, i.e. works equally fast for
contexts with a few context variables and for contexts that have
a lot of them.
@end deffn

@geindex Context (classe dans contextvars)
@anchor{library/contextvars contextvars Context}@anchor{152f}
@deffn {Classe} contextvars.Context

Tableau associatif entre @ref{31af,,ContextVars} et leurs valeurs.

@code{Context()} crée un contexte vide ne contenant aucune valeur. Pour obtenir une copie du contexte actuel, utilisez la fonction @ref{31b0,,copy_context()}.

Each thread has its own effective stack of @code{Context} objects.  The
@ref{1538,,current context} is the @code{Context} object at the top of the
current thread's stack.  All @code{Context} objects in the stacks are
considered to be `entered'.

`Entering' a context, which can be done by calling its @ref{158f,,run()}
method, makes the context the current context by pushing it onto the top of
the current thread's context stack.

`Exiting' from the current context, which can be done by returning from the
callback passed to the @ref{158f,,run()} method, restores the current
context to what it was before the context was entered by popping the context
off the top of the context stack.

Since each thread has its own context stack, @ref{31af,,ContextVar} objects
behave in a similar fashion to @ref{16f9,,threading.local()} when values are
assigned in different threads.

Attempting to enter an already entered context, including contexts entered in
other threads, raises a @ref{193,,RuntimeError}.

After exiting a context, it can later be re-entered (from any thread).

Any changes to @ref{31af,,ContextVar} values via the @ref{31b4,,ContextVar.set()}
method are recorded in the current context.  The @ref{31b2,,ContextVar.get()}
method returns the value associated with the current context.  Exiting a
context effectively reverts any changes made to context variables while the
context was entered (if needed, the values can be restored by re-entering the
context).

`Context' implémente l'interface @ref{8b7,,collections.abc.Mapping}.

@geindex run() (méthode contextvars.Context)
@anchor{library/contextvars contextvars Context run}@anchor{158f}
@deffn {Méthode} run (callable, *args, **kwargs)

Enters the Context, executes @code{callable(*args, **kwargs)}, then exits the
Context.  Returns `callable''s return value, or propagates an exception if
one occurred.

Example:

@example
import contextvars

var = contextvars.ContextVar('var')
var.set('spam')
print(var.get())  # 'spam'

ctx = contextvars.copy_context()

def main():
    # 'var' was set to 'spam' before
    # calling 'copy_context()' and 'ctx.run(main)', so:
    print(var.get())  # 'spam'
    print(ctx[var])  # 'spam'

    var.set('ham')

    # Now, after setting 'var' to 'ham':
    print(var.get())  # 'ham'
    print(ctx[var])  # 'ham'

# Any changes that the 'main' function makes to 'var'
# will be contained in 'ctx'.
ctx.run(main)

# The 'main()' function was run in the 'ctx' context,
# so changes to 'var' are contained in it:
print(ctx[var])  # 'ham'

# However, outside of 'ctx', 'var' is still set to 'spam':
print(var.get())  # 'spam'
@end example

@c spam
@c spam
@c spam
@c ham
@c ham
@c ham
@c spam
@end deffn

@geindex copy() (méthode contextvars.Context)
@anchor{library/contextvars contextvars Context copy}@anchor{31bb}
@deffn {Méthode} copy ()

Renvoie une copie superficielle de l'objet de contexte.
@end deffn


@deffn {Describe} var in context

Renvoie @code{True} si le `context' a une valeur pour `var' ; sinon renvoie @code{False}.
@end deffn


@deffn {Describe} context[var]

Renvoie la valeur de la variable @ref{31af,,ContextVar} `var'. Si la variable n'est pas définie dans l'objet de contexte, une @ref{33a,,KeyError} est levée.
@end deffn

@geindex get() (méthode contextvars.Context)
@anchor{library/contextvars contextvars Context get}@anchor{31bc}
@deffn {Méthode} get (var[, default])

Renvoie la valeur de `var' si `var' possède une valeur dans l'objet de contexte. Renvoie `default' sinon (ou @code{None} si `default' n'est pas donné).
@end deffn


@deffn {Describe} iter(context)

Renvoie un itérateur sur les variables stockées dans l'objet de contexte.
@end deffn


@deffn {Describe} len(proxy)

Renvoie le nombre de variables définies dans l'objet de contexte.
@end deffn

@geindex keys() (méthode contextvars.Context)
@anchor{library/contextvars contextvars Context keys}@anchor{31bd}
@deffn {Méthode} keys ()

Renvoie une liste de toutes les variables dans l'objet de contexte.
@end deffn

@geindex values() (méthode contextvars.Context)
@anchor{library/contextvars contextvars Context values}@anchor{31be}
@deffn {Méthode} values ()

Renvoie une liste de toutes les valeurs des variables dans l'objet de contexte.
@end deffn

@geindex items() (méthode contextvars.Context)
@anchor{library/contextvars contextvars Context items}@anchor{31bf}
@deffn {Méthode} items ()

Renvoie une liste de paires contenant toutes les variables et leurs valeurs dans l'objet de contexte.
@end deffn
@end deffn

@node Gestion avec asyncio,,Gestion de contexte manuelle,contextvars --- Context Variables
@anchor{library/contextvars asyncio-support}@anchor{31c0}
@subsubsection Gestion avec `asyncio'


@ref{a,,asyncio} gère nativement les variables de contexte et elles sont prêtes à être utilisées sans configuration supplémentaire. Par exemple, voici un serveur `echo' simple qui utilise une variable de contexte pour que l’adresse d'un client distant soit disponible dans le `Task' qui gère ce client :

@example
import asyncio
import contextvars

client_addr_var = contextvars.ContextVar('client_addr')

def render_goodbye():
    # The address of the currently handled client can be accessed
    # without passing it explicitly to this function.

    client_addr = client_addr_var.get()
    return f'Good bye, client @@ @{client_addr@}\r\n'.encode()

async def handle_request(reader, writer):
    addr = writer.transport.get_extra_info('socket').getpeername()
    client_addr_var.set(addr)

    # In any code that we call is now possible to get
    # client's address by calling 'client_addr_var.get()'.

    while True:
        line = await reader.readline()
        print(line)
        if not line.strip():
            break

    writer.write(b'HTTP/1.1 200 OK\r\n')  # status line
    writer.write(b'\r\n')  # headers
    writer.write(render_goodbye())  # body
    writer.close()

async def main():
    srv = await asyncio.start_server(
        handle_request, '127.0.0.1', 8081)

    async with srv:
        await srv.serve_forever()

asyncio.run(main())

# To test it you can use telnet or curl:
#     telnet 127.0.0.1 8081
#     curl 127.0.0.1:8081
@end example

Les modules suivants servent de fondation pour certains services cités ci-dessus :

@node _thread --- Low-level threading API,,contextvars --- Context Variables,Exécution concourante
@anchor{library/_thread doc}@anchor{31c1}@anchor{library/_thread module-_thread}@anchor{2}@anchor{library/_thread thread-low-level-threading-api}@anchor{31c2}
@subsection @code{_thread} --- Low-level threading API


@geindex module; _thread

@geindex light-weight processes
@geindex processes@comma{} light-weight
@geindex binary semaphores
@geindex semaphores@comma{} binary


__________________________________________________________________


Ce module fournit les primitives de bas niveau pour travailler avec de multiples fils d'exécution (aussi appelés `light-weight processes' ou `tasks') — plusieurs fils d'exécution de contrôle partagent leur espace de données global. Pour la synchronisation, de simples verrous (aussi appelés des `mutexes' ou des `binary semaphores') sont fournis. Le module @ref{ec,,threading} fournit une API de fils d'exécution de haut niveau, plus facile à utiliser et construite à partir de ce module.

@geindex pthreads
@geindex threads;POSIX


Modifié dans la version 3.7: Ce module était optionnel, il est maintenant toujours disponible.


Ce module définit les constantes et les fonctions suivantes :

@geindex error
@anchor{library/_thread thread error}@anchor{31c3}
@deffn {Exception} _thread.error

Levée lors d'erreurs spécifiques aux fils d'exécution.


Modifié dans la version 3.3: Ceci est à présent un synonyme de l'exception native @ref{193,,RuntimeError}.

@end deffn

@geindex LockType (dans le module _thread)
@anchor{library/_thread thread LockType}@anchor{31c4}
@deffn {Données} _thread.LockType

C'est le type d'objets verrous.
@end deffn

@geindex start_new_thread() (dans le module _thread)
@anchor{library/_thread thread start_new_thread}@anchor{194}
@deffn {Fonction} _thread.start_new_thread (function, args[, kwargs])

Démarre un nouveau fils d'exécution et renvoie son identifiant. Ce fil d'exécution exécute la fonction `function' avec la liste d'arguments `args' (qui doit être un `n'-uplet). L'argument optionnel `kwargs' spécifie un dictionnaire d'arguments nommés.

Au renvoi de la fonction, le fil d'exécution quitte silencieusement.

Lorsque la fonction se termine avec une exception non gérée, @ref{1f4,,sys.unraisablehook()} est appelée pour gérer cette dernière. L'attribut `object' de l'argument `hook' est `function'. Par défaut, la trace d'appels est affichée puis le fil d'exécution se termine (mais les autres fils d'exécution continuent de s'exécuter).

Lorsque la fonction lève l'exception @ref{d2e,,SystemExit}, elle est ignorée silencieusement.

Raises an @ref{1848,,auditing event} @code{_thread.start_new_thread} with arguments @code{function}, @code{args}, @code{kwargs}.


Modifié dans la version 3.8: @ref{1f4,,sys.unraisablehook()} est maintenant utilisée pour s'occuper des exceptions non gérées.

@end deffn

@geindex interrupt_main() (dans le module _thread)
@anchor{library/_thread thread interrupt_main}@anchor{82d}
@deffn {Fonction} _thread.interrupt_main (signum=signal.SIGINT, /)

Simule l'effet d'un signal arrivant au fil d'exécution principal. Un fil d'exécution peut utiliser cette fonction pour interrompre le fil d'exécution principal, bien qu'une interruption immédiate ne soit pas garantie.

If given, `signum' is the number of the signal to simulate.
If `signum' is not given, @ref{82e,,signal.SIGINT} is simulated.

If the given signal isn't handled by Python (it was set to
@ref{17af,,signal.SIG_DFL} or @ref{17ae,,signal.SIG_IGN}), this function does
nothing.


Modifié dans la version 3.10: Ajout du paramètre `signum' pour modifier le numéro du signal.


@cartouche
@quotation Note 
Cette fonction n'émet pas vraiment le signal, mais programme un appel du gestionnaire associé (à condition qu'il existe). Pour émettre réellement le signal, utilisez @ref{1790,,signal.raise_signal()}.
@end quotation
@end cartouche
@end deffn

@geindex exit() (dans le module _thread)
@anchor{library/_thread thread exit}@anchor{31c5}
@deffn {Fonction} _thread.exit ()

Lève une exception @ref{d2e,,SystemExit}. Quand elle n'est pas interceptée, le fil d'exécution se terminera silencieusement.
@end deffn

@c function:: exit_prog(status)
@c 
@c    Exit all threads and report the value of the integer argument
@c    *status* as the exit status of the entire program.
@c    **Caveat:** code in pending :keyword:`finally` clauses, in this thread
@c    or in other threads, is not executed.

@geindex allocate_lock() (dans le module _thread)
@anchor{library/_thread thread allocate_lock}@anchor{31c6}
@deffn {Fonction} _thread.allocate_lock ()

Renvoie un nouveau verrou. Les méthodes des verrous sont décrites ci-dessous. Le verrou est initialement déverrouillé.
@end deffn

@geindex get_ident() (dans le module _thread)
@anchor{library/_thread thread get_ident}@anchor{31c7}
@deffn {Fonction} _thread.get_ident ()

Renvoie l'« identifiant de fil »  du fil d'exécution courant. C'est un entier non nul. Sa valeur n'a pas de signification directe ; il est destiné à être utilisé comme `cookie' magique, par exemple pour indexer un dictionnaire de données pour chaque fil. Les identifiants de fils peuvent être recyclés lorsqu'un fil d'exécution se termine et qu'un autre fil est créé.
@end deffn

@geindex get_native_id() (dans le module _thread)
@anchor{library/_thread thread get_native_id}@anchor{31c8}
@deffn {Fonction} _thread.get_native_id ()

Renvoie l'identifiant natif complet assigné par le noyau du fil d'exécution actuel. C'est un entier non négatif. Sa valeur peut uniquement être utilisée pour identifier ce fil d'exécution à l'échelle du système (jusqu'à ce que le fil d'exécution se termine, après quoi la valeur peut être recyclée par le système d'exploitation).

@ref{1ce0,,Availability}: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.


Ajouté dans la version 3.8.



Modifié dans la version 3.13: Added support for GNU/kFreeBSD.

@end deffn

@geindex stack_size() (dans le module _thread)
@anchor{library/_thread thread stack_size}@anchor{31c9}
@deffn {Fonction} _thread.stack_size ([size])

Renvoie la taille de la pile d'exécution utilisée lors de la création de nouveaux fils d'exécution. L'argument optionnel `size' spécifie la taille de pile à utiliser pour les fils créés ultérieurement, et doit être à 0 (pour utiliser la taille de la plate-forme ou la valeur configurée par défaut) ou un entier positif supérieur ou égal à 32 768 (32 Kio). Si `size' n'est pas spécifié, 0 est utilisé. Si la modification de la taille de la pile de fils n'est pas prise en charge, une exception @ref{193,,RuntimeError} est levée. Si la taille de la pile spécifiée n'est pas valide, une exception @ref{1ff,,ValueError} est levée et la taille de la pile n'est pas modifiée. 32 Kio est actuellement la valeur minimale de taille de la pile prise en charge pour garantir un espace de pile suffisant pour l'interpréteur lui-même. Notez que certaines plates-formes peuvent avoir des restrictions particulières sur les valeurs de taille de la pile, telles que l'exigence d'une taille de pile minimale > 32 Kio ou d'une allocation en multiples de la taille de page de la mémoire du système – la documentation de la plate-forme devrait être consultée pour plus d'informations (4 Kio sont courants ; en l'absence de renseignements plus spécifiques, l'approche suggérée est l'utilisation de multiples de 4 096 octets pour la taille de la pile).

@ref{1ce0,,Availability}: Windows, pthreads.

Unix platforms with POSIX threads support.
@end deffn

@geindex TIMEOUT_MAX (dans le module _thread)
@anchor{library/_thread thread TIMEOUT_MAX}@anchor{31ca}
@deffn {Données} _thread.TIMEOUT_MAX

The maximum value allowed for the `timeout' parameter of
@ref{683,,Lock.acquire}. Specifying a timeout greater
than this value will raise an @ref{86d,,OverflowError}.


Ajouté dans la version 3.2.

@end deffn

Les verrous ont les méthodes suivantes :

@geindex acquire() (méthode _thread.lock)
@anchor{library/_thread thread lock acquire}@anchor{31cb}
@deffn {Méthode} lock.acquire (blocking=True, timeout=-1)

Sans aucun argument optionnel, cette méthode acquiert le verrou inconditionnellement, et si nécessaire attend jusqu'à ce qu'il soit relâché par un autre fil d'exécution (un seul fil d'exécution à la fois peut acquérir le verrou — c'est leur raison d'être).

If the `blocking' argument is present, the action depends on its
value: if it is false, the lock is only acquired if it can be acquired
immediately without waiting, while if it is true, the lock is acquired
unconditionally as above.

If the floating-point `timeout' argument is present and positive, it
specifies the maximum wait time in seconds before returning.  A negative
`timeout' argument specifies an unbounded wait.  You cannot specify
a `timeout' if `blocking' is false.

La valeur renvoyée est @code{True} si le verrou est acquis avec succès, sinon @code{False}.


Modifié dans la version 3.2: Le paramètre `timeout' est nouveau.



Modifié dans la version 3.2: Le verrou acquis peut maintenant être interrompu par des signaux sur POSIX.

@end deffn

@geindex release() (méthode _thread.lock)
@anchor{library/_thread thread lock release}@anchor{31cc}
@deffn {Méthode} lock.release ()

Relâche le verrou. Le verrou doit avoir été acquis plus tôt, mais pas nécessairement par le même fil d'exécution.
@end deffn

@geindex locked() (méthode _thread.lock)
@anchor{library/_thread thread lock locked}@anchor{31cd}
@deffn {Méthode} lock.locked ()

Renvoie le statut du verrou : @code{True} s'il a été acquis par certains fils d'exécution, sinon @code{False}.
@end deffn

En plus de ces méthodes, les objets verrous peuvent aussi être utilisés via l'instruction @ref{5bc,,with}, e.g :

@example
import _thread

a_lock = _thread.allocate_lock()

with a_lock:
    print("a_lock is locked while this executes")
@end example

`Avertissements :'

@geindex module;signal


@itemize *

@item 
Interrupts always go to the main thread (the @ref{9bf,,KeyboardInterrupt}
exception will be received by that thread.)

@item 
Appeler la fonction @ref{1327,,sys.exit()} ou lever l'exception @ref{d2e,,SystemExit} est équivalent à appeler la fonction @ref{31c5,,_thread.exit()}.

@item 
It is platform-dependent whether the @ref{683,,acquire()} method
on a lock can be interrupted (so that the @ref{9bf,,KeyboardInterrupt} exception
will happen immediately, rather than only after the lock has been acquired or
the operation has timed out). It can be interrupted on POSIX, but not on
Windows.

@item 
Quand le fil d'exécution principal s'arrête, il est défini par le système si les autres fils d'exécution survivent. Sur beaucoup de systèmes, ils sont tués sans l'exécution des clauses @ref{6d3,,try}… @ref{9b8,,finally} ou l'exécution des destructeurs d'objets.
@end itemize

@node Réseau et communication entre processus,Traitement des données provenant d'Internet,Exécution concourante,La bibliothèque standard
@anchor{library/ipc doc}@anchor{31ce}@anchor{library/ipc ipc}@anchor{31cf}@anchor{library/ipc networking-and-interprocess-communication}@anchor{31d0}
@section Réseau et communication entre processus


Les modules décrits dans ce chapitre fournissent différents mécanismes de mise en réseau et de communication entre processus.

Certains de ces modules ne fonctionnent que pour deux processus sur une seule machine, comme les modules @ref{c5,,signal} et @ref{8f,,mmap}.  D'autres gèrent des protocoles réseaux que deux processus, ou plus, peuvent utiliser pour communiquer entre différentes machines.

La liste des modules documentés dans ce chapitre est :

@menu
* asyncio: asyncio --- Asynchronous I/O. Asynchronous I/O
* socket: socket --- Low-level networking interface. Low-level networking interface
* ssl: ssl --- TLS/SSL wrapper for socket objects. TLS/SSL wrapper for socket objects
* select: select --- Waiting for I/O completion. Waiting for I/O completion
* selectors: selectors --- High-level I/O multiplexing. High-level I/O multiplexing
* signal: signal --- Set handlers for asynchronous events. Set handlers for asynchronous events
* mmap: mmap --- Memory-mapped file support. Memory-mapped file support

@end menu

@node asyncio --- Asynchronous I/O,socket --- Low-level networking interface,,Réseau et communication entre processus
@anchor{library/asyncio doc}@anchor{31d1}@anchor{library/asyncio asyncio-asynchronous-i-o}@anchor{31d2}@anchor{library/asyncio module-asyncio}@anchor{a}
@subsection @code{asyncio} --- Asynchronous I/O


@geindex module; asyncio


__________________________________________________________________


@subsubheading Hello World !



@example
import asyncio

async def main():
    print('Hello ...')
    await asyncio.sleep(1)
    print('... World!')

asyncio.run(main())
@end example

@code{asyncio} est une bibliothèque permettant de faire de la programmation asynchrone en utilisant la syntaxe `async'/`await'.

@code{asyncio} constitue la base de nombreux cadriciels (`frameworks') Python asynchrones qui fournissent des utilitaires réseau et des serveurs web performants, des bibliothèques de connexion à des bases de données, des files d'exécution distribuées, etc.

@code{asyncio} est souvent le bon choix pour écrire du code réseau de haut-niveau et tributaire des entrées-sorties (`IO-bound').

@code{asyncio} fournit des interfaces de programmation `haut-niveau' pour :


@itemize *

@item 
@ref{31d3,,exécuter des coroutines Python} de manière concurrente et d'avoir le contrôle total sur leur exécution ;

@item 
effectuer @ref{31d4,,des entrées/sorties réseau et de la communication inter-processus} ;

@item 
contrôler des @ref{31d5,,sous-processus} ;

@item 
distribuer des tâches avec des @ref{31d6,,queues} ;

@item 
@ref{31d7,,synchroniser} du code s'exécutant de manière concurrente ;
@end itemize

En plus, il existe des bibliothèques de `bas-niveau' pour que les `développeurs de bibliothèques et de frameworks' puissent :


@itemize *

@item 
create and manage @ref{d66,,event loops}, which
provide asynchronous APIs for @ref{31d8,,networking},
running @ref{31d9,,subprocesses},
handling @ref{31da,,OS signals}, etc;

@item 
implémenter des protocoles efficaces à l'aide de @ref{31db,,transports} ;

@item 
@ref{31dc,,lier} des bibliothèques basées sur les fonctions de rappel et développer avec la syntaxe `async'/`await'.
@end itemize

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.
@anchor{library/asyncio asyncio-cli}@anchor{31dd}
@subsubheading asyncio REPL


You can experiment with an @code{asyncio} concurrent context in the @ref{169,,REPL}:

@example
$ python -m asyncio
asyncio REPL ...
Use "await" directly instead of "asyncio.run()".
Type "help", "copyright", "credits" or "license" for more information.
>>> import asyncio
>>> await asyncio.sleep(10, result='hello')
'hello'
@end example

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_stdin} sans argument.


Modifié dans la version 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20)
Emits audit events.



Modifié dans la version 3.13: Uses PyREPL if possible, in which case 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} is
also executed. Emits audit events.


@c We use the "rubric" directive here to avoid creating
@c the "Reference" subsection in the TOC.

@subsubheading Sommaire


@menu
* Exécuteurs (runners): Exécuteurs runners. 
* Coroutines et tâches:: 
* Flux (streams): Flux streams. 
* Primitives de synchronisation: Primitives de synchronisation<2>. 
* Sous-processus:: 
* Files d'attente (queues): Files d'attente queues. 
* Exceptions: Exceptions<13>. 
* Boucle d'évènements:: 
* Futures:: 
* Transports et Protocoles:: 
* Politiques:: 
* Prise en charge de la plate-forme:: 
* Extension:: 
* Index de l'API de haut niveau:: 
* Index de l'API de bas niveau:: 
* Programmer avec asyncio:: 

@end menu

@node Exécuteurs runners,Coroutines et tâches,,asyncio --- Asynchronous I/O
@anchor{library/asyncio-runner doc}@anchor{31de}@anchor{library/asyncio-runner runners}@anchor{31df}
@subsubsection Exécuteurs (`runners')


`Code source :' Lib/asyncio/runners.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/runners.py}

Cette section décrit les primitives `asyncio' de haut niveau pour exécuter du code asynchrone.

Elles sont construites au-dessus d'une @ref{d66,,boucle d'événements} dans le but de simplifier l'utilisation du code asynchrone pour les scénarios les plus courants.

@menu
* Exécution d'un programme asynchrone:: 
* Gestionnaire de contexte de l'exécuteur:: 
* Gestion de l'interruption par le clavier:: 

@end menu

@node Exécution d'un programme asynchrone,Gestionnaire de contexte de l'exécuteur,,Exécuteurs runners
@anchor{library/asyncio-runner running-an-asyncio-program}@anchor{31e0}
@subsubsection Exécution d'un programme asynchrone


@geindex run() (dans le module asyncio)
@anchor{library/asyncio-runner asyncio run}@anchor{466}
@deffn {Fonction} asyncio.run (coro, *, debug=None, loop_factory=None)

Exécute la @ref{47b,,coroutine} `coro' et renvoie le résultat.

This function runs the passed coroutine, taking care of
managing the asyncio event loop, `finalizing asynchronous
generators', and closing the executor.

Cette fonction ne peut pas être appelée lorsqu'une autre boucle d'événement asynchrone est en cours d'exécution dans le même fil d'exécution.

Si `debug' vaut @code{True}, la boucle d'événements est exécutée en mode débogage. @code{False} désactive explicitement le mode débogage. @code{None} est utilisée pour respecter les paramètres globaux définis par @ref{1cdb,,Mode débogage}.

If `loop_factory' is not @code{None}, it is used to create a new event loop;
otherwise @ref{31e1,,asyncio.new_event_loop()} is used. The loop is closed at the end.
This function should be used as a main entry point for asyncio programs,
and should ideally only be called once. It is recommended to use
`loop_factory' to configure the event loop instead of policies.
Passing @ref{167f,,asyncio.EventLoop} allows running asyncio without the
policy system.

The executor is given a timeout duration of 5 minutes to shutdown.
If the executor hasn't finished within that duration, a warning is
emitted and the executor is closed.

Exemple :

@example
async def main():
    await asyncio.sleep(1)
    print('hello')

asyncio.run(main())
@end example


Ajouté dans la version 3.7.



Modifié dans la version 3.9: mise à jour pour utiliser @ref{8d4,,loop.shutdown_default_executor()}.



Modifié dans la version 3.10: `debug' vaut @code{None} par défaut pour respecter les paramètres du mode de débogage global.



Modifié dans la version 3.12: Added `loop_factory' parameter.

@end deffn

@node Gestionnaire de contexte de l'exécuteur,Gestion de l'interruption par le clavier,Exécution d'un programme asynchrone,Exécuteurs runners
@anchor{library/asyncio-runner runner-context-manager}@anchor{31e2}
@subsubsection Gestionnaire de contexte de l'exécuteur


@geindex Runner (classe dans asyncio)
@anchor{library/asyncio-runner asyncio Runner}@anchor{5eb}
@deffn {Classe} asyncio.Runner (*, debug=None, loop_factory=None)

Gestionnaire de contexte englobant `plusieurs' appels de fonctions asynchrones dans le même contexte.

Parfois, plusieurs fonctions asynchrones de niveau supérieur doivent être appelées dans la même @ref{d66,,boucle d'événements} et le même @ref{152f,,contextvars.Context}.

Si `debug' vaut @code{True}, la boucle d'événements est exécutée en mode débogage. @code{False} désactive explicitement le mode débogage. @code{None} est utilisée pour respecter les paramètres globaux définis par @ref{1cdb,,Mode débogage}.

`loop_factory' peut être utilisée pour remplacer la création de la boucle. `loop_factory' a la responsabilité de définir la boucle créée comme boucle courante. Par défaut @ref{31e1,,asyncio.new_event_loop()} est utilisée et définie comme boucle d'événements actuelle avec @ref{1758,,asyncio.set_event_loop()} si `loop_factory' vaut @code{None}.

Basically, @ref{466,,asyncio.run()} example can be rewritten with the runner usage:

@example
async def main():
    await asyncio.sleep(1)
    print('hello')

with asyncio.Runner() as runner:
    runner.run(main())
@end example


Ajouté dans la version 3.11.


@geindex run() (méthode asyncio.Runner)
@anchor{library/asyncio-runner asyncio Runner run}@anchor{1636}
@deffn {Méthode} run (coro, *, context=None)

Exécute la @ref{47b,,coroutine} `coro' dans la boucle d'événements en cours.

Renvoie le résultat de la coroutine ou lève les exceptions afférentes.

L'argument (uniquement nommé) facultatif `context' permet de spécifier un @ref{152f,,contextvars.Context} personnalisé pour la coroutine à exécuter. Le contexte par défaut de l'exécuteur est utilisé si `context' est @code{None}.

Cette fonction ne peut pas être appelée lorsqu'une autre boucle d'événement asynchrone est en cours d'exécution dans le même fil d'exécution.
@end deffn

@geindex close() (méthode asyncio.Runner)
@anchor{library/asyncio-runner asyncio Runner close}@anchor{31e3}
@deffn {Méthode} close ()

Termine l'exécuteur.

Finalise les générateurs asynchrones, arrête l'exécuteur par défaut, ferme la boucle d'événements et libère le @ref{152f,,contextvars.Context} en cours.
@end deffn

@geindex get_loop() (méthode asyncio.Runner)
@anchor{library/asyncio-runner asyncio Runner get_loop}@anchor{31e4}
@deffn {Méthode} get_loop ()

Renvoie la boucle d'événements associée à l'instance de l'exécuteur.
@end deffn

@cartouche
@quotation Note 
@ref{5eb,,Runner} utilise la stratégie d'initialisation paresseuse, son constructeur n'initialise pas les structures de bas niveau sous-jacentes.

La  boucle d'événements `loop' et le `context' intégrés sont créés à l'entrée du corps de @ref{5bc,,with} ou au premier appel de @ref{466,,run()} ou @ref{31e4,,get_loop()}.
@end quotation
@end cartouche
@end deffn

@node Gestion de l'interruption par le clavier,,Gestionnaire de contexte de l'exécuteur,Exécuteurs runners
@anchor{library/asyncio-runner handling-keyboard-interruption}@anchor{31e5}
@subsubsection Gestion de l'interruption par le clavier



Ajouté dans la version 3.11.


Lorsque @ref{82e,,signal.SIGINT} est déclenché par @code{Ctrl-C}, l'exception @ref{9bf,,KeyboardInterrupt} est levée par défaut dans le fils d'exécution principal. Cependant, cela ne fonctionne pas avec @ref{a,,asyncio} car cela peut interrompre le fonctionnement interne de `asyncio' et empêcher le programme de se terminer.

Pour contrer ce problème, @ref{a,,asyncio} gère @ref{82e,,signal.SIGINT} comme suit :


@enumerate 

@item 
@ref{1636,,asyncio.Runner.run()} installe un gestionnaire @ref{82e,,signal.SIGINT} personnalisé avant l'exécution de tout code utilisateur et le supprime à la sortie de la fonction.

@item 
Le @ref{5eb,,Runner} crée la tâche principale pour la coroutine transmise pour son exécution.

@item 
Lorsque @ref{82e,,signal.SIGINT} est déclenché par @code{Ctrl-C}, le gestionnaire de signal personnalisé annule la tâche principale en appelant @ref{1b5,,asyncio.Task.cancel()} qui lève @ref{1b6,,asyncio.CancelledError} à l'intérieur de la tâche principale. Cela entraîne la remontée dans la pile Python, les blocs @code{try/except} et @code{try/finally} peuvent être utilisés pour le nettoyage des ressources. Une fois la tâche principale annulée, @ref{1636,,asyncio.Runner.run()} lève @ref{9bf,,KeyboardInterrupt}.

@item 
Un utilisateur peut écrire une boucle tellement petite qu'elle ne peut pas être interrompue par @ref{1b5,,asyncio.Task.cancel()} ; dans ce cas la seconde suivante @code{Ctrl-C} lève immédiatement le @ref{9bf,,KeyboardInterrupt} sans annuler la tâche principale.
@end enumerate

@node Coroutines et tâches,Flux streams,Exécuteurs runners,asyncio --- Asynchronous I/O
@anchor{library/asyncio-task doc}@anchor{31e6}@anchor{library/asyncio-task coroutines-and-tasks}@anchor{31e7}
@subsubsection Coroutines et tâches


Cette section donne un aperçu des API de haut-niveau du module `asyncio' pour utiliser les coroutines et les tâches.

@menu
* Coroutines: Coroutines<3>. 
* Attendables:: 
* Création de tâches:: 
* Annulation de tâche:: 
* Groupes de tâches:: 
* Attente:: 
* Exécution de tâches de manière concurrente:: 
* Eager Task Factory:: 
* Protection contre l'annulation:: 
* Délais d'attente:: 
* Primitives d'attente:: 
* Exécution dans des fils d'exécution (threads): Exécution dans des fils d'exécution threads. 
* Planification depuis d'autres fils d'exécution:: 
* Introspection:: 
* Objets Task:: 

@end menu

@node Coroutines<3>,Attendables,,Coroutines et tâches
@anchor{library/asyncio-task coroutine}@anchor{31d3}@anchor{library/asyncio-task coroutines}@anchor{31e8}
@subsubsection Coroutines


`Code source :' Lib/asyncio/coroutines.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/coroutines.py}


__________________________________________________________________


Les @ref{47b,,coroutines} déclarées avec la syntaxe `async/await' sont la manière privilégiée d’écrire des applications asynchrones. Par exemple, l’extrait de code suivant affiche « hello », attend une seconde et affiche ensuite « world » :

@example
>>> import asyncio

>>> async def main():
...     print('hello')
...     await asyncio.sleep(1)
...     print('world')

>>> asyncio.run(main())
hello
world
@end example

Remarquez que simplement appeler une coroutine ne la planifie pas pour exécution :

@example
>>> main()
<coroutine object main at 0x1053bb7c8>
@end example

Pour réellement exécuter une coroutine, `asyncio' fournit les mécanismes suivants :


@itemize *

@item 
La fonction @ref{466,,asyncio.run()} pour exécuter la fonction « main() », le point d'entrée de haut-niveau (voir l'exemple ci-dessus).

@item 
Attendre une coroutine. Le morceau de code suivant attend une seconde, affiche « hello », attend 2 secondes `supplémentaires', puis affiche enfin « world » :

@example
import asyncio
import time

async def say_after(delay, what):
    await asyncio.sleep(delay)
    print(what)

async def main():
    print(f"started at @{time.strftime('%X')@}")

    await say_after(1, 'hello')
    await say_after(2, 'world')

    print(f"finished at @{time.strftime('%X')@}")

asyncio.run(main())
@end example

Sortie attendue :

@example
started at 17:13:52
hello
world
finished at 17:13:55
@end example

@item 
La fonction @ref{5e7,,asyncio.create_task()} pour exécuter de manière concurrente des coroutines en tant que @ref{4c2,,tâches} `asyncio'.

Modifions l'exemple ci-dessus et lançons deux coroutines @code{say_after} `de manière concurrente' :

@example
async def main():
    task1 = asyncio.create_task(
        say_after(1, 'hello'))

    task2 = asyncio.create_task(
        say_after(2, 'world'))

    print(f"started at @{time.strftime('%X')@}")

    # Wait until both tasks are completed (should take
    # around 2 seconds.)
    await task1
    await task2

    print(f"finished at @{time.strftime('%X')@}")
@end example

La sortie attendue montre à présent que ce code s'exécute une seconde plus rapidement que le précédent :

@example
started at 17:14:32
hello
world
finished at 17:14:34
@end example

@item 
La classe @ref{1b3,,asyncio.TaskGroup} fournit une alternative plus moderne à @ref{5e7,,create_task()}. En utilisant cette API, le dernier exemple devient :

@example
async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(
            say_after(1, 'hello'))

        task2 = tg.create_task(
            say_after(2, 'world'))

        print(f"started at @{time.strftime('%X')@}")

    # The await is implicit when the context manager exits.

    print(f"finished at @{time.strftime('%X')@}")
@end example

Le temps d'exécution et la sortie doivent être les mêmes que pour la version précédente.


Ajouté dans la version 3.11: @ref{1b3,,asyncio.TaskGroup}.

@end itemize

@node Attendables,Création de tâches,Coroutines<3>,Coroutines et tâches
@anchor{library/asyncio-task asyncio-awaitables}@anchor{31e9}@anchor{library/asyncio-task awaitables}@anchor{31ea}
@subsubsection `Attendables'


Un objet est dit `attendable' (`awaitable' en anglais, c.-à-d. qui peut être attendu) s'il peut être utilisé dans une expression @ref{1b7,,await}. Beaucoup d'API d'`asyncio' sont conçues pour accepter des `attendables'.

Il existe trois types principaux d'`attendables' : les `coroutines', les `tâches' et les `futurs'.

@subsubheading Coroutines


Les coroutines sont des `awaitables' et peuvent donc être attendues par d'autres coroutines :

@example
import asyncio

async def nested():
    return 42

async def main():
    # Nothing happens if we just call "nested()".
    # A coroutine object is created but not awaited,
    # so it *won't run at all*.
    nested()  # will raise a "RuntimeWarning".

    # Let's do it differently now and await it:
    print(await nested())  # will print "42".

asyncio.run(main())
@end example

@cartouche
@quotation Important 
dans cette documentation, le terme « coroutine » est utilisé pour désigner deux concepts voisins :


@itemize *

@item 
une `fonction coroutine' : une fonction @ref{5bb,,async def} ;

@item 
un `objet coroutine' : un objet renvoyé par une `fonction coroutine'.
@end itemize
@end quotation
@end cartouche

@subsubheading Tâches


Les `tâches' servent à planifier des coroutines de façon à ce qu'elles s'exécutent de manière concurrente.

Lorsqu'une coroutine est encapsulée dans une `tâche' à l'aide de fonctions comme @ref{5e7,,asyncio.create_task()}, la coroutine est automatiquement planifiée pour s'exécuter prochainement :

@example
import asyncio

async def nested():
    return 42

async def main():
    # Schedule nested() to run soon concurrently
    # with "main()".
    task = asyncio.create_task(nested())

    # "task" can now be used to cancel "nested()", or
    # can simply be awaited to wait until it is complete:
    await task

asyncio.run(main())
@end example

@subsubheading Futurs


Un @ref{bbb,,Future} est un objet `attendable' spécial de `bas-niveau', qui représente le `résultat final' d'une opération asynchrone.

Quand un objet `Future' est `attendu', cela signifie que la coroutine attendra que ce futur soit résolu à un autre endroit.

Les objets `Future' d'`asyncio' sont nécessaires pour permettre l'exécution de code basé sur les fonctions de rappel avec la syntaxe `async' / `await'.

Il est normalement `inutile' de créer des objets `Future' dans la couche applicative du code.

Les objets `Future', parfois exposés par des bibliothèques et quelques API d'`asyncio', peuvent être attendus :

@example
async def main():
    await function_that_returns_a_future_object()

    # this is also valid:
    await asyncio.gather(
        function_that_returns_a_future_object(),
        some_python_coroutine()
    )
@end example

@ref{8d6,,loop.run_in_executor()} est l'exemple typique d'une fonction bas-niveau renvoyant un objet `Future'.

@node Création de tâches,Annulation de tâche,Attendables,Coroutines et tâches
@anchor{library/asyncio-task creating-tasks}@anchor{31eb}
@subsubsection Création de tâches


`Code source :' Lib/asyncio/tasks.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/tasks.py}


__________________________________________________________________


@geindex create_task() (dans le module asyncio)
@anchor{library/asyncio-task asyncio create_task}@anchor{5e7}
@deffn {Fonction} asyncio.create_task (coro, *, name=None, context=None)

Encapsule la @ref{31d3,,coroutine} `coro' dans une tâche et la planifie pour exécution. Renvoie l'objet @ref{4c2,,Task}.

Si `name' n’est pas @code{None}, il est défini comme le nom de la tâche en utilisant @ref{9cb,,Task.set_name()}.

L'argument (uniquement nommé) facultatif `context' permet de spécifier un @ref{152f,,contextvars.Context} personnalisé pour la coroutine à exécuter. La copie de contexte actuelle est créée lorsqu'aucun `context' n'est fourni.

La tâche est exécutée dans la boucle renvoyée par @ref{af9,,get_running_loop()} ; @ref{193,,RuntimeError} est levée s'il n'y a pas de boucle en cours d'exécution dans le fil actuel.

@cartouche
@quotation Note 
@ref{1ba,,asyncio.TaskGroup.create_task()} is a new alternative
leveraging structural concurrency; it allows for waiting
for a group of related tasks with strong safety guarantees.
@end quotation
@end cartouche

@cartouche
@quotation Important 
gardez une référence au résultat de cette fonction, pour éviter qu'une tâche ne disparaisse en cours d'exécution. La boucle d'événements ne conserve que les références faibles aux tâches. Une tâche qui n'est pas référencée ailleurs peut être supprimée par le ramasse-miettes à tout moment, même avant qu'elle ne soit terminée. Pour créer des tâches d'arrière-plan fiables de type « lance et oublie », rassemblez-les dans une collection :

@example
background_tasks = set()

for i in range(10):
    task = asyncio.create_task(some_coro(param=i))

    # Add task to the set. This creates a strong reference.
    background_tasks.add(task)

    # To prevent keeping references to finished tasks forever,
    # make each task remove its own reference from the set after
    # completion:
    task.add_done_callback(background_tasks.discard)
@end example
@end quotation
@end cartouche


Ajouté dans la version 3.7.



Modifié dans la version 3.8: ajout du paramètre `name'.



Modifié dans la version 3.11: ajout du paramètre `context'.

@end deffn

@node Annulation de tâche,Groupes de tâches,Création de tâches,Coroutines et tâches
@anchor{library/asyncio-task task-cancellation}@anchor{31ec}
@subsubsection Annulation de tâche


Les tâches peuvent être annulées facilement et en toute sécurité. Lorsqu'une tâche est annulée, @ref{1b6,,asyncio.CancelledError} est levée dans la tâche à la première occasion.

Il est recommandé que les coroutines utilisent des blocs @code{try/finally} pour exécuter de manière robuste la logique de nettoyage. Dans le cas où @ref{1b6,,asyncio.CancelledError} est explicitement interceptée, elle devrait généralement être propagée lorsque le nettoyage est terminé. @ref{1b6,,asyncio.CancelledError} sous-classe directement @ref{5a5,,BaseException} donc la plupart du code n'a pas besoin d'en être conscient.

Les composants `asyncio' qui permettent la concurrence structurée, comme @ref{1b3,,asyncio.TaskGroup} et @ref{5e9,,asyncio.timeout()}, sont implémentés en utilisant l'annulation en interne et peuvent mal se comporter si une coroutine ne propage pas @ref{1b6,,asyncio.CancelledError}. De même, le code utilisateur ne doit généralement pas appeler @ref{1b9,,uncancel}. Cependant, dans les cas où la suppression de @ref{1b6,,asyncio.CancelledError} est vraiment souhaitée, il est également nécessaire d'appeler @code{uncancel()} pour supprimer complètement l'état d'annulation.

@node Groupes de tâches,Attente,Annulation de tâche,Coroutines et tâches
@anchor{library/asyncio-task task-groups}@anchor{31ed}@anchor{library/asyncio-task taskgroups}@anchor{31ee}
@subsubsection Groupes de tâches


Les groupes de tâches combinent une API de création de tâches avec un moyen pratique et fiable d'attendre la fin de toutes les tâches du groupe.

@geindex TaskGroup (classe dans asyncio)
@anchor{library/asyncio-task asyncio TaskGroup}@anchor{1b3}
@deffn {Classe} asyncio.TaskGroup

@ref{5e6,,Gestionnaire de contexte asynchrone} responsable d’un groupe de tâches. Des tâches peuvent être ajoutées au groupe en utilisant @ref{5e7,,create_task()}. Toutes les tâches sont attendues à la sortie du gestionnaire de contexte.


Ajouté dans la version 3.11.


@geindex create_task() (méthode asyncio.TaskGroup)
@anchor{library/asyncio-task asyncio TaskGroup create_task}@anchor{1ba}
@deffn {Méthode} create_task (coro, *, name=None, context=None)

Create a task in this task group.
The signature matches that of @ref{5e7,,asyncio.create_task()}.
If the task group is inactive (e.g. not yet entered,
already finished, or in the process of shutting down),
we will close the given @code{coro}.


Modifié dans la version 3.13: Close the given coroutine if the task group is not active.

@end deffn
@end deffn

Exemple :

@example
async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(some_coro(...))
        task2 = tg.create_task(another_coro(...))
    print(f"Both tasks have completed now: @{task1.result()@}, @{task2.result()@}")
@end example

L'instruction @code{async with} attend la fin de toutes les tâches du groupe. Lors de l'attente, de nouvelles tâches peuvent encore être ajoutées au groupe (par exemple, en passant @code{tg} dans l'une des coroutines et en appelant @code{tg.create_task()} dans cette coroutine). Une fois que la dernière tâche est terminée et que le bloc @code{async with} est quitté, aucune nouvelle tâche ne peut être ajoutée au groupe.

La première fois que l'une des tâches appartenant au groupe échoue avec une exception autre que @ref{1b6,,asyncio.CancelledError}, les tâches restantes du groupe sont annulées. Aucune autre tâche ne peut alors être ajoutée au groupe. À ce stade, si le corps de l'instruction @code{async with} est toujours actif (par exemple, @ref{15b3,,__aexit__()} n'a pas encore été appelé), la tâche contenant directement l'instruction @code{async with} est également annulée. Le résultat @ref{1b6,,asyncio.CancelledError} interrompt un @code{await}, mais il ne sort pas de l'instruction @code{async with} englobante.

Une fois toutes les tâches terminées, si des tâches ont échoué avec une exception autre que @ref{1b6,,asyncio.CancelledError}, ces exceptions sont combinées dans un @ref{1b4,,ExceptionGroup} ou @ref{25c,,BaseExceptionGroup} (selon le cas ; voir leur documentation) qui est ensuite levé.

Deux exceptions de base sont traitées spécialement : si une tâche échoue avec @ref{9bf,,KeyboardInterrupt} ou @ref{d2e,,SystemExit}, le groupe de tâches annule toujours les tâches restantes et les attend, mais alors la @ref{9bf,,KeyboardInterrupt} ou la @ref{d2e,,SystemExit} initiale est levée à nouveau au lieu de @ref{1b4,,ExceptionGroup} ou @ref{25c,,BaseExceptionGroup}.

Si le corps de l'instruction @code{async with} se termine avec une exception (donc @ref{15b3,,__aexit__()} est appelé avec un ensemble d'exceptions), cela est traité de la même manière que si l'une des tâches échouait : les tâches restantes sont annulées puis attendues, et les exceptions de non-annulation sont regroupées dans un groupe d'exceptions et levées. L'exception transmise à @ref{15b3,,__aexit__()}, à moins qu'il ne s'agisse de @ref{1b6,,asyncio.CancelledError}, est également incluse dans le groupe d'exceptions. Le même cas spécial concerne @ref{9bf,,KeyboardInterrupt} et @ref{d2e,,SystemExit} comme dans le paragraphe précédent.

Task groups are careful not to mix up the internal cancellation used to
"wake up" their @ref{15b3,,__aexit__()} with cancellation requests
for the task in which they are running made by other parties.
In particular, when one task group is syntactically nested in another,
and both experience an exception in one of their child tasks simultaneously,
the inner task group will process its exceptions, and then the outer task group
will receive another cancellation and process its own exceptions.

In the case where a task group is cancelled externally and also must
raise an @ref{1b4,,ExceptionGroup}, it will call the parent task's
@ref{1b5,,cancel()} method. This ensures that a
@ref{1b6,,asyncio.CancelledError} will be raised at the next
@ref{1b7,,await}, so the cancellation is not lost.

Task groups preserve the cancellation count
reported by @ref{1b8,,asyncio.Task.cancelling()}.


Modifié dans la version 3.13: Improved handling of simultaneous internal and external cancellations
and correct preservation of cancellation counts.


@menu
* Terminating a Task Group:: 

@end menu

@node Terminating a Task Group,,,Groupes de tâches
@anchor{library/asyncio-task terminating-a-task-group}@anchor{31ef}
@subsubsection Terminating a Task Group


While terminating a task group is not natively supported by the standard
library, termination can be achieved by adding an exception-raising task
to the task group and ignoring the raised exception:

@example
import asyncio
from asyncio import TaskGroup

class TerminateTaskGroup(Exception):
    """Exception raised to terminate a task group."""

async def force_terminate_task_group():
    """Used to force termination of a task group."""
    raise TerminateTaskGroup()

async def job(task_id, sleep_time):
    print(f'Task @{task_id@}: start')
    await asyncio.sleep(sleep_time)
    print(f'Task @{task_id@}: done')

async def main():
    try:
        async with TaskGroup() as group:
            # spawn some tasks
            group.create_task(job(1, 0.5))
            group.create_task(job(2, 1.5))
            # sleep for 1 second
            await asyncio.sleep(1)
            # add an exception-raising task to force the group to terminate
            group.create_task(force_terminate_task_group())
    except* TerminateTaskGroup:
        pass

asyncio.run(main())
@end example

Expected output:

@example
Task 1: start
Task 2: start
Task 1: done
@end example

@node Attente,Exécution de tâches de manière concurrente,Groupes de tâches,Coroutines et tâches
@anchor{library/asyncio-task sleeping}@anchor{31f0}
@subsubsection Attente


@geindex sleep() (dans le module asyncio)
@anchor{library/asyncio-task asyncio sleep}@anchor{a5d}
@deffn {Fonction} coroutine asyncio.sleep (delay, result=None)

Attend pendant `delay' secondes.

Si `result' est spécifié, il est renvoyé à l'appelant quand la coroutine se termine.

@code{sleep()} suspend systématiquement la tâche courante, ce qui permet aux autres tâches de s'exécuter.

Définir le délai sur 0 fournit un chemin optimisé pour permettre à d'autres tâches de s'exécuter. Cela peut être utilisé par les fonctions de longue durée pour éviter de bloquer la boucle d'événements pendant toute la durée de l'appel de fonction.
@anchor{library/asyncio-task asyncio-example-sleep}@anchor{31f1}
Exemple d'une coroutine affichant la date toutes les secondes pendant 5 secondes :

@example
import asyncio
import datetime

async def display_date():
    loop = asyncio.get_running_loop()
    end_time = loop.time() + 5.0
    while True:
        print(datetime.datetime.now())
        if (loop.time() + 1.0) >= end_time:
            break
        await asyncio.sleep(1)

asyncio.run(display_date())
@end example


Modifié dans la version 3.10: le paramètre `loop' a été enlevé.



Modifié dans la version 3.13: Raises @ref{1ff,,ValueError} if `delay' is @ref{64e,,nan}.

@end deffn

@node Exécution de tâches de manière concurrente,Eager Task Factory,Attente,Coroutines et tâches
@anchor{library/asyncio-task running-tasks-concurrently}@anchor{31f2}
@subsubsection Exécution de tâches de manière concurrente


@geindex gather() (dans le module asyncio)
@anchor{library/asyncio-task asyncio gather}@anchor{5e8}
@deffn {Fonction} awaitable asyncio.gather (*aws, return_exceptions=False)

Exécute les objets @ref{31e9,,awaitable} de la séquence `aws', `de manière concurrente'.

Si un `attendable' de `aws' est une coroutine, celui-ci est automatiquement planifié comme une tâche `Task'.

Si tous les `awaitables' s'achèvent avec succès, le résultat est la liste des valeurs renvoyées. L'ordre de cette liste correspond à l'ordre des `awaitables' dans `aws'.

Si `return_exceptions' vaut @code{False} (valeur par défaut), la première exception levée est immédiatement propagée vers la tâche en attente dans le @code{gather()}. Les autres `attendables' dans la séquence `aws' `ne sont pas annulés' et poursuivent leur exécution.

Si `return_exceptions' vaut @code{True}, les exceptions sont traitées de la même manière que les exécutions normales, et incluses dans la liste des résultats.

Si @code{gather()} est `annulé', tous les `awaitables' en cours (ceux qui n'ont pas encore fini de s'exécuter) sont également `annulés'.

Si n'importe quel `Task' ou `Future' de la séquence `aws' est `annulé', il est traité comme s'il avait levé @ref{1b6,,CancelledError} — l'appel à @code{gather()} n'est alors `pas' annulé. Ceci permet d'empêcher que l'annulation d'une tâche ou d'un futur entraîne l'annulation des autres tâches ou futurs.

@cartouche
@quotation Note 
A new alternative to create and run tasks concurrently and
wait for their completion is @ref{1b3,,asyncio.TaskGroup}. `TaskGroup'
provides stronger safety guarantees than `gather' for scheduling a nesting of subtasks:
if a task (or a subtask, a task scheduled by a task)
raises an exception, `TaskGroup' will, while `gather' will not,
cancel the remaining scheduled tasks).
@end quotation
@end cartouche
@anchor{library/asyncio-task asyncio-example-gather}@anchor{31f3}
Exemple :

@example
import asyncio

async def factorial(name, number):
    f = 1
    for i in range(2, number + 1):
        print(f"Task @{name@}: Compute factorial(@{number@}), currently i=@{i@}...")
        await asyncio.sleep(1)
        f *= i
    print(f"Task @{name@}: factorial(@{number@}) = @{f@}")
    return f

async def main():
    # Schedule three calls *concurrently*:
    L = await asyncio.gather(
        factorial("A", 2),
        factorial("B", 3),
        factorial("C", 4),
    )
    print(L)

asyncio.run(main())

# Expected output:
#
#     Task A: Compute factorial(2), currently i=2...
#     Task B: Compute factorial(3), currently i=2...
#     Task C: Compute factorial(4), currently i=2...
#     Task A: factorial(2) = 2
#     Task B: Compute factorial(3), currently i=3...
#     Task C: Compute factorial(4), currently i=3...
#     Task B: factorial(3) = 6
#     Task C: Compute factorial(4), currently i=4...
#     Task C: factorial(4) = 24
#     [2, 6, 24]
@end example

@cartouche
@quotation Note 
If `return_exceptions' is false, cancelling gather() after it
has been marked done won't cancel any submitted awaitables.
For instance, gather can be marked done after propagating an
exception to the caller, therefore, calling @code{gather.cancel()}
after catching an exception (raised by one of the awaitables) from
gather won't cancel any other awaitables.
@end quotation
@end cartouche


Modifié dans la version 3.7: Si `gather' est lui-même annulé, l'annulation est propagée indépendamment de `return_exceptions'.



Modifié dans la version 3.10: le paramètre `loop' a été enlevé.



Obsolète depuis la version 3.10: Un avertissement d'obsolescence est émis si aucun argument positionnel n'est fourni ou si tous les arguments positionnels ne sont pas des objets de type Future et qu'il n'y a pas de boucle d'événements en cours d'exécution.

@end deffn

@node Eager Task Factory,Protection contre l'annulation,Exécution de tâches de manière concurrente,Coroutines et tâches
@anchor{library/asyncio-task eager-task-factory}@anchor{31f4}@anchor{library/asyncio-task id1}@anchor{31f5}
@subsubsection Eager Task Factory


@geindex eager_task_factory() (dans le module asyncio)
@anchor{library/asyncio-task asyncio eager_task_factory}@anchor{461}
@deffn {Fonction} asyncio.eager_task_factory (loop, coro, *, name=None, context=None)

A task factory for eager task execution.

When using this factory (via @ref{db3,,loop.set_task_factory(asyncio.eager_task_factory)}),
coroutines begin execution synchronously during @ref{4c2,,Task} construction.
Tasks are only scheduled on the event loop if they block.
This can be a performance improvement as the overhead of loop scheduling
is avoided for coroutines that complete synchronously.

A common example where this is beneficial is coroutines which employ
caching or memoization to avoid actual I/O when possible.

@cartouche
@quotation Note 
Immediate execution of the coroutine is a semantic change.
If the coroutine returns or raises, the task is never scheduled
to the event loop. If the coroutine execution blocks, the task is
scheduled to the event loop. This change may introduce behavior
changes to existing applications. For example,
the application's task execution order is likely to change.
@end quotation
@end cartouche


Ajouté dans la version 3.12.

@end deffn

@geindex create_eager_task_factory() (dans le module asyncio)
@anchor{library/asyncio-task asyncio create_eager_task_factory}@anchor{462}
@deffn {Fonction} asyncio.create_eager_task_factory (custom_task_constructor)

Create an eager task factory, similar to @ref{461,,eager_task_factory()},
using the provided `custom_task_constructor' when creating a new task instead
of the default @ref{4c2,,Task}.

`custom_task_constructor' must be a `callable' with the signature matching
the signature of @ref{4c2,,Task.__init__}.
The callable must return a @ref{4c2,,asyncio.Task}-compatible object.

This function returns a `callable' intended to be used as a task factory of an
event loop via @ref{db3,,loop.set_task_factory(factory)}).


Ajouté dans la version 3.12.

@end deffn

@node Protection contre l'annulation,Délais d'attente,Eager Task Factory,Coroutines et tâches
@anchor{library/asyncio-task shielding-from-cancellation}@anchor{31f6}
@subsubsection Protection contre l'annulation


@geindex shield() (dans le module asyncio)
@anchor{library/asyncio-task asyncio shield}@anchor{a5e}
@deffn {Fonction} awaitable asyncio.shield (aw)

Empêche qu'un objet @ref{31e9,,awaitable} puisse être @ref{1b5,,annulé}.

Si `aw' est une coroutine, elle est planifiée automatiquement comme une tâche.

L'instruction :

@example
task = asyncio.create_task(something())
res = await shield(task)
@end example

est équivalente à :

@example
res = await something()
@end example

`à la différence près' que, si la coroutine qui la contient est annulée, la tâche s'exécutant dans @code{something()} n'est pas annulée. Du point de vue de @code{something()}, il n'y a pas eu d'annulation. Cependant, son appelant est bien annulé, donc l'expression `await' lève bien une @ref{1b6,,CancelledError}.

Si @code{something()} est annulée d'une autre façon (c.-à-d. depuis elle-même) ceci annule également @code{shield()}.

Pour ignorer complètement l'annulation (déconseillé), la fonction @code{shield()} peut être combinée à une clause `try' / `except', comme dans le code ci-dessous :

@example
task = asyncio.create_task(something())
try:
    res = await shield(task)
except CancelledError:
    res = None
@end example

@cartouche
@quotation Important 
sauvegardez une référence aux tâches passées à cette fonction, pour éviter qu'une tâche ne disparaisse en cours d'exécution. La boucle d'événements ne conserve que les références faibles aux tâches. Une tâche qui n'est pas référencée ailleurs peut faire l'objet d'une suppression par le ramasse-miettes à tout moment, même avant qu'elle ne soit terminée.
@end quotation
@end cartouche


Modifié dans la version 3.10: le paramètre `loop' a été enlevé.



Obsolète depuis la version 3.10: un avertissement d'obsolescence est émis si `aw' n'est pas un objet de type `future' et qu'il n'y a pas de boucle d'événement en cours d'exécution.

@end deffn

@node Délais d'attente,Primitives d'attente,Protection contre l'annulation,Coroutines et tâches
@anchor{library/asyncio-task timeouts}@anchor{31f7}
@subsubsection Délais d'attente


@geindex timeout() (dans le module asyncio)
@anchor{library/asyncio-task asyncio timeout}@anchor{5e9}
@deffn {Fonction} asyncio.timeout (delay)

Return an @ref{5e6,,asynchronous context manager}
that can be used to limit the amount of time spent waiting on
something.

`delay' peut-être soit @code{None}, soit le nombre de secondes (entier ou décimal) d'attente. Si `delay' vaut @code{None}, aucune limite n'est appliquée ; cela peut être utile lorsque le délai d'attente est inconnu au moment de la création du gestionnaire de contexte.

Dans les deux cas, le gestionnaire de contexte peut être redéfini après sa création en utilisant @ref{31f8,,Timeout.reschedule()}.

Exemple :

@example
async def main():
    async with asyncio.timeout(10):
        await long_running_task()
@end example

If @code{long_running_task} takes more than 10 seconds to complete,
the context manager will cancel the current task and handle
the resulting @ref{1b6,,asyncio.CancelledError} internally, transforming it
into a @ref{81f,,TimeoutError} which can be caught and handled.

@cartouche
@quotation Note 
The @ref{5e9,,asyncio.timeout()} context manager is what transforms
the @ref{1b6,,asyncio.CancelledError} into a @ref{81f,,TimeoutError},
which means the @ref{81f,,TimeoutError} can only be caught
`outside' of the context manager.
@end quotation
@end cartouche

Example of catching @ref{81f,,TimeoutError}:

@example
async def main():
    try:
        async with asyncio.timeout(10):
            await long_running_task()
    except TimeoutError:
        print("The long operation timed out, but we've handled it.")

    print("This statement will run regardless.")
@end example

Le gestionnaire de contexte produit par @ref{5e9,,asyncio.timeout()} peut être reprogrammé à une échéance différente et inspecté.

@geindex Timeout (classe dans asyncio)
@anchor{library/asyncio-task asyncio Timeout}@anchor{1654}
@deffn {Classe} asyncio.Timeout (when)

@ref{5e6,,Gestionnaire de contexte asynchrone} pour annuler les coroutines en retard.

@code{when} doit être un temps absolu au bout duquel le contexte doit expirer, tel que mesuré par l'horloge de la boucle d'événements :


@itemize -

@item 
Si @code{when} vaut @code{None}, le délai maximal ne se déclenche jamais.

@item 
Si @code{when < loop.time()}, le délai maximal se déclenche à la prochaine itération de la boucle d'événement.
@end itemize

@quotation

@geindex when() (méthode asyncio.Timeout)
@anchor{library/asyncio-task asyncio Timeout when}@anchor{31f9}
@deffn {Méthode} when () -> float | None

Renvoie la limite de temps d'exécution définie actuellement, ou @code{None} s'il n'y en a pas.
@end deffn

@geindex reschedule() (méthode asyncio.Timeout)
@anchor{library/asyncio-task asyncio Timeout reschedule}@anchor{31f8}
@deffn {Méthode} reschedule (when: float | None)

Reprogramme le délai d'attente.
@end deffn

@geindex expired() (méthode asyncio.Timeout)
@anchor{library/asyncio-task asyncio Timeout expired}@anchor{31fa}
@deffn {Méthode} expired () -> bool

Renvoie si le gestionnaire de contexte a dépassé son délai (c.-à-d. s'il a expiré).
@end deffn
@end quotation
@end deffn

Exemple :

@example
async def main():
    try:
        # We do not know the timeout when starting, so we pass `@w{`}None`@w{`}.
        async with asyncio.timeout(None) as cm:
            # We know the timeout now, so we reschedule it.
            new_deadline = get_running_loop().time() + 10
            cm.reschedule(new_deadline)

            await long_running_task()
    except TimeoutError:
        pass

    if cm.expired():
        print("Looks like we haven't finished on time.")
@end example

Les gestionnaires de contexte de délai maximal peuvent être imbriqués en toute sécurité.


Ajouté dans la version 3.11.

@end deffn

@geindex timeout_at() (dans le module asyncio)
@anchor{library/asyncio-task asyncio timeout_at}@anchor{17b0}
@deffn {Fonction} asyncio.timeout_at (when)

Semblable à @ref{5e9,,asyncio.timeout()}, sauf que `when' est le temps absolu pour arrêter d'attendre, ou @code{None}.

Exemple :

@example
async def main():
    loop = get_running_loop()
    deadline = loop.time() + 20
    try:
        async with asyncio.timeout_at(deadline):
            await long_running_task()
    except TimeoutError:
        print("The long operation timed out, but we've handled it.")

    print("This statement will run regardless.")
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex wait_for() (dans le module asyncio)
@anchor{library/asyncio-task asyncio wait_for}@anchor{5ea}
@deffn {Fonction} coroutine asyncio.wait_for (aw, timeout)

Attend la fin de l'@ref{31e9,,awaitable} `aw' avec délai d'attente.

Si `aw' est une coroutine, elle est planifiée automatiquement comme une tâche.

`timeout' peut-être soit @code{None}, soit le nombre de secondes (entier ou décimal) d'attente. Si `timeout' vaut @code{None}, la fonction s'interrompt jusqu'à ce que le futur s'achève.

Si le délai d'attente maximal est dépassé, la tâche est annulée et l'exception @ref{81f,,TimeoutError} est levée.

Pour empêcher @ref{1b5,,l'annulation} de la tâche, il est nécessaire de l'encapsuler dans une fonction @ref{a5e,,shield()}.

Cette fonction attend que le futur soit réellement annulé, donc le temps d'attente total peut être supérieur à `timeout'. Si une exception se produit lors de l'annulation, elle est propagée.

Si l'attente est annulée, le futur `aw' est également annulé.
@anchor{library/asyncio-task asyncio-example-waitfor}@anchor{31fb}
Exemple :

@example
async def eternity():
    # Sleep for one hour
    await asyncio.sleep(3600)
    print('yay!')

async def main():
    # Wait for at most 1 second
    try:
        await asyncio.wait_for(eternity(), timeout=1.0)
    except TimeoutError:
        print('timeout!')

asyncio.run(main())

# Expected output:
#
#     timeout!
@end example


Modifié dans la version 3.7: Si le dépassement du délai d'attente maximal provoque l'annulation de `aw', @code{wait_for} attend que `aw' soit annulée. Auparavant, l'exception @ref{81f,,TimeoutError} était immédiatement levée.



Modifié dans la version 3.10: le paramètre `loop' a été enlevé.



Modifié dans la version 3.11: Raises @ref{81f,,TimeoutError} instead of @ref{16ce,,asyncio.TimeoutError}.

@end deffn

@node Primitives d'attente,Exécution dans des fils d'exécution threads,Délais d'attente,Coroutines et tâches
@anchor{library/asyncio-task waiting-primitives}@anchor{31fc}
@subsubsection Primitives d'attente


@geindex wait() (dans le module asyncio)
@anchor{library/asyncio-task asyncio wait}@anchor{469}
@deffn {Fonction} coroutine asyncio.wait (aws, *, timeout=None, return_when=ALL_COMPLETED)

Exécute les instances @ref{bbb,,Future} et @ref{4c2,,Task} de l'itérable `aws' de manière concurrente, et s'interrompt jusqu'à ce que la condition décrite dans `return_when' soit vraie.

The `aws' iterable must not be empty.

Renvoie deux ensembles de `Tasks' / `Futures' : @code{(done, pending)}.

Utilisation :

@example
done, pending = await asyncio.wait(aws)
@end example

`timeout' (entier ou décimal), si précisé, peut-être utilisé pour contrôler le nombre maximal de secondes d'attente avant de se terminer.

Cette fonction ne lève pas @ref{81f,,TimeoutError}. Les futurs et les tâches qui ne sont pas finis quand le délai d'attente maximal est dépassé sont tout simplement renvoyés dans le second ensemble.

`return_when' indique quand la fonction doit se terminer. Il peut prendre les valeurs suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Description

@item

@geindex FIRST_COMPLETED (dans le module asyncio)
@anchor{library/asyncio-task asyncio FIRST_COMPLETED}@anchor{31fd}
@deffn {Données} asyncio.FIRST_COMPLETED
@end deffn

@tab

La fonction se termine lorsque n'importe quel futur se termine ou est annulé.

@item

@geindex FIRST_EXCEPTION (dans le module asyncio)
@anchor{library/asyncio-task asyncio FIRST_EXCEPTION}@anchor{31fe}
@deffn {Données} asyncio.FIRST_EXCEPTION
@end deffn

@tab

The function will return when any future finishes by raising an
exception. If no future raises an exception
then it is equivalent to @ref{31ff,,ALL_COMPLETED}.

@item

@geindex ALL_COMPLETED (dans le module asyncio)
@anchor{library/asyncio-task asyncio ALL_COMPLETED}@anchor{31ff}
@deffn {Données} asyncio.ALL_COMPLETED
@end deffn

@tab

La fonction se termine lorsque les `futurs' sont tous finis ou annulés.

@end multitable


À la différence de @ref{5ea,,wait_for()}, @code{wait()} n'annule pas les futurs quand le délai d'attente est dépassé.


Modifié dans la version 3.10: le paramètre `loop' a été enlevé.



Modifié dans la version 3.11: Passer directement des objets coroutines à @code{wait()} est interdit.



Modifié dans la version 3.12: Added support for generators yielding tasks.

@end deffn

@geindex as_completed() (dans le module asyncio)
@anchor{library/asyncio-task asyncio as_completed}@anchor{1a8}
@deffn {Fonction} asyncio.as_completed (aws, *, timeout=None)

Run @ref{31e9,,awaitable objects} in the `aws' iterable
concurrently. The returned object can be iterated to obtain the results
of the awaitables as they finish.

The object returned by @code{as_completed()} can be iterated as an
@ref{1a9,,asynchronous iterator} or a plain @ref{1aa,,iterator}. When asynchronous
iteration is used, the originally-supplied awaitables are yielded if they
are tasks or futures. This makes it easy to correlate previously-scheduled
tasks with their results. Example:

@example
ipv4_connect = create_task(open_connection("127.0.0.1", 80))
ipv6_connect = create_task(open_connection("::1", 80))
tasks = [ipv4_connect, ipv6_connect]

async for earliest_connect in as_completed(tasks):
    # earliest_connect is done. The result can be obtained by
    # awaiting it or calling earliest_connect.result()
    reader, writer = await earliest_connect

    if earliest_connect is ipv6_connect:
        print("IPv6 connection established.")
    else:
        print("IPv4 connection established.")
@end example

During asynchronous iteration, implicitly-created tasks will be yielded for
supplied awaitables that aren't tasks or futures.

When used as a plain iterator, each iteration yields a new coroutine that
returns the result or raises the exception of the next completed awaitable.
This pattern is compatible with Python versions older than 3.13:

@example
ipv4_connect = create_task(open_connection("127.0.0.1", 80))
ipv6_connect = create_task(open_connection("::1", 80))
tasks = [ipv4_connect, ipv6_connect]

for next_connect in as_completed(tasks):
    # next_connect is not one of the original task objects. It must be
    # awaited to obtain the result value or raise the exception of the
    # awaitable that finishes next.
    reader, writer = await next_connect
@end example

A @ref{81f,,TimeoutError} is raised if the timeout occurs before all awaitables
are done. This is raised by the @code{async for} loop during asynchronous
iteration or by the coroutines yielded during plain iteration.


Modifié dans la version 3.10: le paramètre `loop' a été enlevé.



Obsolète depuis la version 3.10: Un avertissement d'obsolescence est émis si tous les objets en attente dans l'itérable `aws' ne sont pas des objets de type `Future' et qu'il n'y a pas de boucle d'événement en cours d'exécution.



Modifié dans la version 3.12: Added support for generators yielding tasks.



Modifié dans la version 3.13: The result can now be used as either an @ref{1a9,,asynchronous iterator}
or as a plain @ref{1aa,,iterator} (previously it was only a plain iterator).

@end deffn

@node Exécution dans des fils d'exécution threads,Planification depuis d'autres fils d'exécution,Primitives d'attente,Coroutines et tâches
@anchor{library/asyncio-task running-in-threads}@anchor{3200}
@subsubsection Exécution dans des fils d'exécution (`threads')


@geindex to_thread() (dans le module asyncio)
@anchor{library/asyncio-task asyncio to_thread}@anchor{8d5}
@deffn {Fonction} coroutine asyncio.to_thread (func, /, *args, **kwargs)

Exécute la fonction `func' de manière asynchrone dans un fil d'exécution séparé.

Tous les `*args' et `**kwargs' fournis à cette fonction sont directement passés à `func'. De plus, le @ref{152f,,contextvars.Context} actuel est propagé, ce qui permet d'accéder aux variables de contexte du fil de boucle d'événements dans le fil séparé.

Renvoie une coroutine qui peut être attendue pour obtenir le résultat éventuel de `func'.

Cette fonction coroutine est principalement destinée à être utilisée pour exécuter des fonctions/méthodes faisant beaucoup d'entrées-sorties et qui bloqueraient autrement la boucle d'événements si elles étaient exécutées dans le fil d'exécution principal. Par exemple :

@example
def blocking_io():
    print(f"start blocking_io at @{time.strftime('%X')@}")
    # Note that time.sleep() can be replaced with any blocking
    # IO-bound operation, such as file operations.
    time.sleep(1)
    print(f"blocking_io complete at @{time.strftime('%X')@}")

async def main():
    print(f"started main at @{time.strftime('%X')@}")

    await asyncio.gather(
        asyncio.to_thread(blocking_io),
        asyncio.sleep(1))

    print(f"finished main at @{time.strftime('%X')@}")


asyncio.run(main())

# Expected output:
#
# started main at 19:50:53
# start blocking_io at 19:50:53
# blocking_io complete at 19:50:54
# finished main at 19:50:54
@end example

Appeler directement @code{blocking_io()} dans n'importe quelle coroutine bloquerait la boucle d'événements pendant sa durée, ce qui entraînerait une seconde supplémentaire de temps d'exécution. Au lieu de cela, en utilisant @code{asyncio.to_thread()}, nous pouvons l'exécuter dans un fil d'exécution séparé sans bloquer la boucle d'événements.

@cartouche
@quotation Note 
en raison du @ref{158,,GIL}, @code{asyncio.to_thread()} ne peut généralement être utilisée que pour rendre les fonctions faisant beaucoup d'entrées-sorties non bloquantes. Cependant, pour les modules d'extension qui relâchent le GIL ou les implémentations Python alternatives qui n'en ont pas, @code{asyncio.to_thread()} peut également être utilisée pour les fonctions qui sollicitent beaucoup le processeur.
@end quotation
@end cartouche


Ajouté dans la version 3.9.

@end deffn

@node Planification depuis d'autres fils d'exécution,Introspection,Exécution dans des fils d'exécution threads,Coroutines et tâches
@anchor{library/asyncio-task scheduling-from-other-threads}@anchor{3201}
@subsubsection Planification depuis d'autres fils d'exécution


@geindex run_coroutine_threadsafe() (dans le module asyncio)
@anchor{library/asyncio-task asyncio run_coroutine_threadsafe}@anchor{86e}
@deffn {Fonction} asyncio.run_coroutine_threadsafe (coro, loop)

Enregistre une coroutine dans la boucle d'exécution actuelle. Cette opération est compatible avec les programmes à multiples fils d'exécution (`thread-safe').

Renvoie un @ref{118f,,concurrent.futures.Future} pour attendre le résultat d'un autre fil d'exécution du système d'exploitation.

Cette fonction est faite pour être appelée par un fil d'exécution distinct de celui dans laquelle la boucle d'événement s'exécute. Exemple :

@example
# Create a coroutine
coro = asyncio.sleep(1, result=3)

# Submit the coroutine to a given loop
future = asyncio.run_coroutine_threadsafe(coro, loop)

# Wait for the result with an optional timeout argument
assert future.result(timeout) == 3
@end example

Si une exception est levée dans une coroutine, le futur renvoyé en sera averti. Elle peut également être utilisée pour annuler la tâche de la boucle d'événement :

@example
try:
    result = future.result(timeout)
except TimeoutError:
    print('The coroutine took too long, cancelling the task...')
    future.cancel()
except Exception as exc:
    print(f'The coroutine raised an exception: @{exc!r@}')
else:
    print(f'The coroutine returned: @{result!r@}')
@end example

Voir la section @ref{3202,,exécution concurrente et multi-fils d'exécution} de la documentation.

À la différence des autres fonctions d'`asyncio', cette fonction requiert que `loop' soit passé de manière explicite.


Ajouté dans la version 3.5.1.

@end deffn

@node Introspection,Objets Task,Planification depuis d'autres fils d'exécution,Coroutines et tâches
@anchor{library/asyncio-task introspection}@anchor{3203}
@subsubsection Introspection


@geindex current_task() (dans le module asyncio)
@anchor{library/asyncio-task asyncio current_task}@anchor{467}
@deffn {Fonction} asyncio.current_task (loop=None)

Renvoie l'instance de la @ref{4c2,,Task} en cours d'exécution, ou @code{None} s'il n'y a pas de tâche en cours.

Si `loop' vaut @code{None}, @ref{af9,,get_running_loop()} est appelée pour récupérer la boucle en cours d'exécution.


Ajouté dans la version 3.7.

@end deffn

@geindex all_tasks() (dans le module asyncio)
@anchor{library/asyncio-task asyncio all_tasks}@anchor{943}
@deffn {Fonction} asyncio.all_tasks (loop=None)

Renvoie l'ensemble des @ref{4c2,,Task} non terminés en cours d'exécution dans la boucle.

Si `loop' vaut @code{None}, @ref{af9,,get_running_loop()} est appelée pour récupérer la boucle en cours d'exécution.


Ajouté dans la version 3.7.

@end deffn

@geindex iscoroutine() (dans le module asyncio)
@anchor{library/asyncio-task asyncio iscoroutine}@anchor{468}
@deffn {Fonction} asyncio.iscoroutine (obj)

Renvoie @code{True} si `obj' est un objet coroutine.


Ajouté dans la version 3.4.

@end deffn

@node Objets Task,,Introspection,Coroutines et tâches
@anchor{library/asyncio-task task-object}@anchor{3204}
@subsubsection Objets `Task'


@geindex Task (classe dans asyncio)
@anchor{library/asyncio-task asyncio Task}@anchor{4c2}
@deffn {Classe} asyncio.Task (coro, *, loop=None, name=None, context=None, eager_start=False)

Objet compatible avec @ref{bbb,,Future} qui exécute une @ref{31d3,,coroutine} Python. Cet objet n'est pas utilisable dans des programmes à fils d'exécution multiples.

Les tâches servent à exécuter des coroutines dans des boucles d'événements. Si une coroutine attend un futur, la tâche interrompt son exécution et attend la fin de ce `futur'. Quand celui-ci est terminé, l'exécution de la coroutine encapsulée reprend.

Les boucles d'événement fonctionnent de manière `coopérative' : une boucle d'événement exécute une tâche à la fois. Quand une tâche attend la fin d'un futur, la boucle d'événement exécute d'autres tâches, des fonctions de rappel, ou effectue des opérations d'entrées-sorties.

La fonction de haut niveau @ref{5e7,,asyncio.create_task()} et les fonctions de bas-niveau @ref{9ca,,loop.create_task()} ou @ref{c64,,ensure_future()} permettent de créer des tâches. Il est déconseillé d'instancier manuellement des objets `Task'.

La méthode @ref{1b5,,cancel()} d'une tâche en cours d'exécution permet d'annuler celle-ci. L'appel de cette méthode force la tâche à lever l'exception @ref{1b6,,CancelledError} dans la coroutine encapsulée. Si la coroutine attendait un `futur' au moment de l'annulation, celui-ci est annulé.

La méthode @ref{3205,,cancelled()} permet de vérifier si la tâche a été annulée. Elle renvoie @code{True} si la coroutine encapsulée n'a pas ignoré l'exception @ref{1b6,,CancelledError} et a bien été annulée.

@ref{4c2,,asyncio.Task} hérite de @ref{bbb,,Future}, de toute son API, à l'exception de @ref{3206,,Future.set_result()} et de @ref{3207,,Future.set_exception()}.

An optional keyword-only `context' argument allows specifying a
custom @ref{152f,,contextvars.Context} for the `coro' to run in.
If no `context' is provided, the Task copies the current context
and later runs its coroutine in the copied context.

An optional keyword-only `eager_start' argument allows eagerly starting
the execution of the @ref{4c2,,asyncio.Task} at task creation time.
If set to @code{True} and the event loop is running, the task will start
executing the coroutine immediately, until the first time the coroutine
blocks. If the coroutine returns or raises without blocking, the task
will be finished eagerly and will skip scheduling to the event loop.


Modifié dans la version 3.7: ajout du support du module @ref{24,,contextvars}.



Modifié dans la version 3.8: ajout du paramètre `name'.



Obsolète depuis la version 3.10: un avertissement d'obsolescence est émis si `loop' n'est pas spécifié et qu'il n'y a pas de boucle d'événement en cours d'exécution.



Modifié dans la version 3.11: ajout du paramètre `context'.



Modifié dans la version 3.12: Added the `eager_start' parameter.


@geindex done() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task done}@anchor{3208}
@deffn {Méthode} done ()

Renvoie @code{True} si la tâche est `achevée'.

Une tâche est dite `achevée' quand la coroutine encapsulée a soit renvoyé une valeur, soit levé une exception, ou que la tâche a été annulée.
@end deffn

@geindex result() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task result}@anchor{3209}
@deffn {Méthode} result ()

Renvoie le résultat de la tâche.

Si la tâche est `achevée', le résultat de la coroutine encapsulée est renvoyé (sinon, dans le cas où la coroutine a levé une exception, cette exception est de nouveau levée).

Si la tâche a été `annulée', cette méthode lève une exception @ref{1b6,,CancelledError}.

If the Task's result isn't yet available, this method raises
an @ref{320a,,InvalidStateError} exception.
@end deffn

@geindex exception() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task exception}@anchor{320b}
@deffn {Méthode} exception ()

Renvoie l'exception de la tâche.

Si la coroutine encapsulée lève une exception, cette exception est renvoyée. Si la coroutine s'est exécutée normalement, cette méthode renvoie @code{None}.

Si la tâche a été `annulée', cette méthode lève une exception @ref{1b6,,CancelledError}.

Si la tâche n'est pas encore `achevée', cette méthode lève une exception @ref{320a,,InvalidStateError}.
@end deffn

@geindex add_done_callback() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task add_done_callback}@anchor{320c}
@deffn {Méthode} add_done_callback (callback, *, context=None)

Ajoute une fonction de rappel qui sera exécutée quand la tâche sera `achevée'.

Cette méthode ne doit être utilisée que dans du code basé sur les fonctions de rappel de bas-niveau.

Se référer à la documentation de @ref{af6,,Future.add_done_callback()} pour plus de détails.
@end deffn

@geindex remove_done_callback() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task remove_done_callback}@anchor{320d}
@deffn {Méthode} remove_done_callback (callback)

Retire `callback' de la liste de fonctions de rappel.

Cette méthode ne doit être utilisée que dans du code basé sur les fonctions de rappel de bas-niveau.

Se référer à la documentation de @ref{152b,,Future.remove_done_callback()} pour plus de détails.
@end deffn

@geindex get_stack() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_stack}@anchor{320e}
@deffn {Méthode} get_stack (*, limit=None)

Renvoie une liste représentant la pile d'appels de la tâche.

Si la coroutine encapsulée n'est pas terminée, cette fonction renvoie la pile d'appels à partir de l'endroit où celle-ci est interrompue. Si la coroutine s'est terminée normalement ou a été annulée, cette fonction renvoie une liste vide. Si la coroutine a été terminée par une exception, ceci renvoie la pile d'erreurs.

La pile est toujours affichée de l'appelant à l'appelé.

Une seule ligne est renvoyée si la coroutine est suspendue.

L'argument facultatif `limit' définit le nombre maximal d'appels à renvoyer ; par défaut, tous sont renvoyés. L'ordre de la liste diffère selon la nature de celle-ci : les appels les plus récents d'une pile d'appels sont renvoyés, si la pile est une pile d'erreurs, ce sont les appels les plus anciens qui le sont (dans un souci de cohérence avec le module `traceback').
@end deffn

@geindex print_stack() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task print_stack}@anchor{16ed}
@deffn {Méthode} print_stack (*, limit=None, file=None)

Affiche la pile d'appels ou d'erreurs de la tâche.

Le format de sortie des appels produits par @ref{320e,,get_stack()} est similaire à celui du module `traceback'.

Le paramètre `limit' est directement passé à @ref{320e,,get_stack()}.

Le paramètre `file' est un flux d'entrées-sorties sur lequel le résultat est écrit ; par défaut, @ref{ac4,,sys.stdout}.
@end deffn

@geindex get_coro() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_coro}@anchor{9c9}
@deffn {Méthode} get_coro ()

Renvoie l’objet `coroutine' encapsulé par la @ref{4c2,,Task}.

@cartouche
@quotation Note 
This will return @code{None} for Tasks which have already
completed eagerly. See the @ref{31f4,,Eager Task Factory}.
@end quotation
@end cartouche


Ajouté dans la version 3.8.



Modifié dans la version 3.12: Newly added eager task execution means result may be @code{None}.

@end deffn

@geindex get_context() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_context}@anchor{320f}
@deffn {Méthode} get_context ()

Return the @ref{152f,,contextvars.Context} object
associated with the task.


Ajouté dans la version 3.12.

@end deffn

@geindex get_name() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task get_name}@anchor{9cc}
@deffn {Méthode} get_name ()

Renvoie le nom de la tâche.

Si aucun nom n’a été explicitement assigné à la tâche, l’implémentation par défaut d’une `Task' `asyncio' génère un nom par défaut durant l’instanciation.


Ajouté dans la version 3.8.

@end deffn

@geindex set_name() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task set_name}@anchor{9cb}
@deffn {Méthode} set_name (value)

Définit le nom de la tâche.

L’argument `value' peut être n’importe quel objet qui sera ensuite converti en chaine de caractères.

Dans l’implémentation par défaut de `Task', le nom sera visible dans le résultat de @ref{7e7,,repr()} d’un objet `Task'.


Ajouté dans la version 3.8.

@end deffn

@geindex cancel() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task cancel}@anchor{1b5}
@deffn {Méthode} cancel (msg=None)

Demande l'annulation d'une tâche.

Provisionne la levée de l'exception @ref{1b6,,CancelledError} dans la coroutine encapsulée. L'exception sera levée au prochain cycle de la boucle d'exécution.

La coroutine peut alors faire le ménage ou même ignorer la requête en supprimant l'exception à l'aide d'un bloc @ref{6d3,,try} … … @code{except CancelledError} … @ref{9b8,,finally}. Par conséquent, contrairement à @ref{17a8,,Future.cancel()}, @ref{1b5,,Task.cancel()} ne garantit pas que la tâche sera annulée, bien qu'ignorer totalement une annulation ne soit ni une pratique courante, ni encouragé. Si la coroutine décide néanmoins de supprimer l'annulation, elle doit appeler @ref{1b9,,Task.uncancel()} en plus d'intercepter l'exception.


Modifié dans la version 3.9: ajout du paramètre `msg'.



Modifié dans la version 3.11: le paramètre @code{msg} est propagé de la tâche annulée vers celle qui l'attend.

@anchor{library/asyncio-task asyncio-example-task-cancel}@anchor{3210}
L'exemple ci-dessous illustre comment une coroutine peut intercepter une requête d'annulation :

@example
async def cancel_me():
    print('cancel_me(): before sleep')

    try:
        # Wait for 1 hour
        await asyncio.sleep(3600)
    except asyncio.CancelledError:
        print('cancel_me(): cancel sleep')
        raise
    finally:
        print('cancel_me(): after sleep')

async def main():
    # Create a "cancel_me" Task
    task = asyncio.create_task(cancel_me())

    # Wait for 1 second
    await asyncio.sleep(1)

    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("main(): cancel_me is cancelled now")

asyncio.run(main())

# Expected output:
#
#     cancel_me(): before sleep
#     cancel_me(): cancel sleep
#     cancel_me(): after sleep
#     main(): cancel_me is cancelled now
@end example
@end deffn

@geindex cancelled() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task cancelled}@anchor{3205}
@deffn {Méthode} cancelled ()

Renvoie @code{True} si la tâche est `annulée'.

La tâche est `annulée' quand l'annulation a été demandée avec @ref{1b5,,cancel()} et la coroutine encapsulée a propagé l'exception @ref{1b6,,CancelledError} qui a été levée en son sein.
@end deffn

@geindex uncancel() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task uncancel}@anchor{1b9}
@deffn {Méthode} uncancel ()

Décrémente le nombre de demandes d'annulation pour cette tâche.

Renvoie le nombre restant de demandes d'annulation.

Notez qu'une fois l'exécution d'une tâche annulée terminée, les appels ultérieurs à @ref{1b9,,uncancel()} ne font rien.


Ajouté dans la version 3.11.


Cette méthode est utilisée par les composants internes d'`asyncio' et elle ne devrait pas être utilisée par le code de l'utilisateur final. En particulier, si une tâche est annulée avec succès, cela permet aux structures permettant le multi-fils tels que @ref{31ee,,Groupes de tâches} et @ref{5e9,,asyncio.timeout()} de continuer à s'exécuter, isolant l'annulation au bloc concerné. Par exemple :

@example
async def make_request_with_timeout():
    try:
        async with asyncio.timeout(1):
            # Structured block affected by the timeout:
            await make_request()
            await make_another_request()
    except TimeoutError:
        log("There was a timeout")
    # Outer code not affected by the timeout:
    await unrelated_code()
@end example

Alors que le bloc avec @code{make_request()} et @code{make_another_request()} peut être annulé en raison du délai d'attente, @code{unrelated_code()} devrait continuer à s'exécuter même en cas d'atteinte du délai maximal. Ceci est implémenté avec @ref{1b9,,uncancel()}. Les gestionnaires de contexte @ref{1b3,,TaskGroup} utilisent @ref{1b9,,uncancel()} de la même manière.

If end-user code is, for some reason, suppressing cancellation by
catching @ref{1b6,,CancelledError}, it needs to call this method to remove
the cancellation state.

When this method decrements the cancellation count to zero,
the method checks if a previous @ref{1b5,,cancel()} call had arranged
for @ref{1b6,,CancelledError} to be thrown into the task.
If it hasn't been thrown yet, that arrangement will be
rescinded (by resetting the internal @code{_must_cancel} flag).
@end deffn


Modifié dans la version 3.13: Changed to rescind pending cancellation requests upon reaching zero.


@geindex cancelling() (méthode asyncio.Task)
@anchor{library/asyncio-task asyncio Task cancelling}@anchor{1b8}
@deffn {Méthode} cancelling ()

Renvoie le nombre de demandes d'annulation en attente à cette tâche, c'est-à-dire le nombre d'appels à @ref{1b5,,cancel()} moins le nombre d'appels à @ref{1b9,,uncancel()}.

Notez que si ce nombre est supérieur à zéro mais que la tâche est toujours en cours d'exécution, @ref{3205,,cancelled()} renvoie toujours @code{False}. En effet, ce nombre peut être réduit en appelant @ref{1b9,,uncancel()}, ce qui peut empêcher en fin de compte la tâche d'être annulée si les demandes d'annulation tombent à zéro.

Cette méthode est utilisée par les composants internes d'`asyncio' et ne devrait pas être utilisée par le code de l'utilisateur final. Voir @ref{1b9,,uncancel()} pour plus de détails.


Ajouté dans la version 3.11.

@end deffn
@end deffn

@node Flux streams,Primitives de synchronisation<2>,Coroutines et tâches,asyncio --- Asynchronous I/O
@anchor{library/asyncio-stream doc}@anchor{3211}@anchor{library/asyncio-stream asyncio-streams}@anchor{31d4}@anchor{library/asyncio-stream streams}@anchor{3212}
@subsubsection Flux (`streams')


`Code source :' Lib/asyncore.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncore.py}


__________________________________________________________________


Les flux sont des primitives de haut niveau compatibles avec `async'/`await' pour utiliser les connexions réseau. Les flux permettent d'envoyer et de recevoir des données sans utiliser de fonctions de rappel ou des protocoles de bas niveau.
@anchor{library/asyncio-stream asyncio-example-stream}@anchor{3213}
Voici un exemple de client « écho TCP » écrit en utilisant les flux `asyncio' :

@example
import asyncio

async def tcp_echo_client(message):
    reader, writer = await asyncio.open_connection(
        '127.0.0.1', 8888)

    print(f'Send: @{message!r@}')
    writer.write(message.encode())
    await writer.drain()

    data = await reader.read(100)
    print(f'Received: @{data.decode()!r@}')

    print('Close the connection')
    writer.close()
    await writer.wait_closed()

asyncio.run(tcp_echo_client('Hello World!'))
@end example

Voir également la section @ref{3214,,Exemples} ci-dessous.

@subsubheading Fonctions de flux


Les fonctions `asyncio' de haut niveau suivantes peuvent être utilisées pour créer et utiliser des flux :

@geindex open_connection() (dans le module asyncio)
@anchor{library/asyncio-stream asyncio open_connection}@anchor{b06}
@deffn {Fonction} coroutine asyncio.open_connection (host=None, port=None, *, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None)

Établit une connexion réseau et renvoie une paire d'objets @code{(lecteur, écrivain)}.

Les objets `lecteur' et `écrivain' renvoyés sont des instances des classes @ref{1853,,StreamReader} et @ref{1689,,StreamWriter}.

`limit' détermine la limite de taille de tampon utilisée par l'instance @ref{1853,,StreamReader} renvoyée. Par défaut, `limit' est fixée à 64 Kio.

Le reste des arguments est passé directement à @ref{5ee,,loop.create_connection()}.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur réseau au @ref{1689,,StreamWriter} créé. Pour fermer le connecteur, appelez sa méthode @ref{3215,,close()}.
@end quotation
@end cartouche


Modifié dans la version 3.7: ajout du paramètre `ssl_handshake_timeout'.



Modifié dans la version 3.8: Added the `happy_eyeballs_delay' and `interleave' parameters.



Modifié dans la version 3.10: suppression du paramètre `loop'.



Modifié dans la version 3.11: ajout du paramètre `ssl_shutdown_timeout'.

@end deffn

@geindex start_server() (dans le module asyncio)
@anchor{library/asyncio-stream asyncio start_server}@anchor{b07}
@deffn {Fonction} coroutine asyncio.start_server (client_connected_cb, host=None, port=None, *, limit=None, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, keep_alive=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Démarre un serveur de connexions

La fonction de rappel `client_connected_cb' est appelée chaque fois qu'une nouvelle connexion client est établie. Elle reçoit une paire d'arguments @code{(lecteur, écrivain)}, instances des classes @ref{1853,,StreamReader} et @ref{1689,,StreamWriter}.

`client_connected_cb' peut être un simple appelable ou une fonction @ref{31d3,,coroutine} ; s'il s'agit d'une fonction coroutine, elle sera automatiquement planifiée en tant que @ref{4c2,,Task}.

`limit' détermine la limite de taille de tampon utilisée par l'instance @ref{1853,,StreamReader} renvoyée. Par défaut, `limit' est fixée à 64 Kio.

Le reste des arguments est passé directement à @ref{b01,,loop.create_server()}.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur au serveur créé. Pour fermer le connecteur, appelez la méthode @ref{3216,,close()} du serveur.
@end quotation
@end cartouche


Modifié dans la version 3.7: ajout des paramètres `ssl_handshake_timeout' et `start_serving'.



Modifié dans la version 3.10: suppression du paramètre `loop'.



Modifié dans la version 3.11: ajout du paramètre `ssl_shutdown_timeout'.



Modifié dans la version 3.13: Added the `keep_alive' parameter.

@end deffn

@subsubheading Connecteurs Unix (`sockets')


@geindex open_unix_connection() (dans le module asyncio)
@anchor{library/asyncio-stream asyncio open_unix_connection}@anchor{3217}
@deffn {Fonction} coroutine asyncio.open_unix_connection (path=None, *, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Ouvre un connecteur Unix et renvoie une paire de @code{(lecteur, écrivain)}.

Similaire à @ref{b06,,open_connection()} mais fonctionne sur les connecteurs Unix.

Voir aussi la documentation de @ref{3218,,loop.create_unix_connection()}.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur réseau au @ref{1689,,StreamWriter} créé. Pour fermer le connecteur, appelez sa méthode @ref{3215,,close()}.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.7: ajout du paramètre `ssl_handshake_timeout'. Le paramètre `path' peut désormais être un @ref{29d,,objet simili-chemin}



Modifié dans la version 3.10: suppression du paramètre `loop'.



Modifié dans la version 3.11: ajout du paramètre `ssl_shutdown_timeout'.

@end deffn

@geindex start_unix_server() (dans le module asyncio)
@anchor{library/asyncio-stream asyncio start_unix_server}@anchor{3219}
@deffn {Fonction} coroutine asyncio.start_unix_server (client_connected_cb, path=None, *, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Démarre un connecteur Unix en mode serveur.

Similaire à @ref{b07,,start_server()} mais fonctionne avec les connecteurs Unix.

Voir aussi la documentation de @ref{1ac,,loop.create_unix_server()}.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur au serveur créé. Pour fermer le connecteur, appelez la méthode @ref{3216,,close()} du serveur.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.7: ajout des paramètres `ssl_handshake_timeout' et `start_serving'. Le paramètre `chemin' peut désormais être un @ref{29d,,simili-chemin}.



Modifié dans la version 3.10: suppression du paramètre `loop'.



Modifié dans la version 3.11: ajout du paramètre `ssl_shutdown_timeout'.

@end deffn

@menu
* Flux lecteurs (StreamReader): Flux lecteurs StreamReader. 
* Flux écrivains (StreamWriter): Flux écrivains StreamWriter. 
* Exemples: Exemples<15>. 

@end menu

@node Flux lecteurs StreamReader,Flux écrivains StreamWriter,,Flux streams
@anchor{library/asyncio-stream streamreader}@anchor{321a}
@subsubsection Flux lecteurs (`StreamReader')


@geindex StreamReader (classe dans asyncio)
@anchor{library/asyncio-stream asyncio StreamReader}@anchor{1853}
@deffn {Classe} asyncio.StreamReader

Représente un objet lecteur qui fournit des API pour lire les données du flux d'entrée-sortie. En tant que @ref{d65,,itérable asynchrone}, l'objet prend en charge l'instruction @ref{a99,,async for}.

Il n'est pas recommandé d'instancier directement les objets `StreamReader' ; utilisez @ref{b06,,open_connection()} et @ref{b07,,start_server()} à la place.

@geindex feed_eof() (méthode asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader feed_eof}@anchor{321b}
@deffn {Méthode} feed_eof ()

Acknowledge the EOF.
@end deffn

@geindex read() (méthode asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader read}@anchor{321c}
@deffn {Méthode} coroutine read (n=-1)

Lit jusqu'à `n' octets du flux.

Si `n' n'est pas fourni ou défini à @code{-1}, lit jusqu'à `EOF', puis renvoie tous les @ref{1bd,,bytes} lus. Si `EOF' a été reçu et que le tampon interne est vide, renvoie un objet @code{bytes} vide.

Si `n' vaut @code{0}, renvoie immédiatement un objet @code{bytes} vide.

Si `n' est positif, renvoie au plus `n' @code{bytes} disponibles dès qu'au moins 1 octet est disponible dans le tampon interne. Si `EOF' est reçu avant qu'aucun octet ne soit lu, renvoie un objet @code{bytes} vide.
@end deffn

@geindex readline() (méthode asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader readline}@anchor{321d}
@deffn {Méthode} coroutine readline ()

Lit une ligne, où une « ligne » est une séquence d'octets se terminant par @code{\n}.

Si `EOF' est reçu et @code{\n} n'a pas été trouvé, la méthode renvoie des données partiellement lues.

Si `EOF' est reçu et que le tampon interne est vide, renvoie un objet @code{bytes} vide.
@end deffn

@geindex readexactly() (méthode asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader readexactly}@anchor{c69}
@deffn {Méthode} coroutine readexactly (n)

Lit exactement `n' octets.

Lève une @ref{18ad,,IncompleteReadError} si `EOF' est atteint avant que `n' octets ne puissent être lus. Utilisez l'attribut @ref{321e,,IncompleteReadError.partial} pour obtenir les données partiellement lues.
@end deffn

@geindex readuntil() (méthode asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader readuntil}@anchor{1b2}
@deffn {Méthode} coroutine readuntil (separator=b'\n')

Lit les données du flux jusqu'à ce que le `separator' soit trouvé.

En cas de succès, les données et le séparateur sont supprimés du tampon interne (consommés). Les données renvoyées incluent le séparateur à la fin.

Si la quantité de données lues dépasse la limite de flux configurée, une exception @ref{321f,,LimitOverrunError} est levée et les données sont laissées dans le tampon interne et peuvent être lues à nouveau.

Si `EOF' est atteint avant que le séparateur complet ne soit trouvé, une exception @ref{18ad,,IncompleteReadError} est levée  et le tampon interne est réinitialisé. L'attribut @ref{321e,,IncompleteReadError.partial} peut contenir une partie du séparateur.

The `separator' may also be a tuple of separators. In this
case the return value will be the shortest possible that has any
separator as the suffix. For the purposes of @ref{321f,,LimitOverrunError},
the shortest possible separator is considered to be the one that
matched.


Ajouté dans la version 3.5.2.



Modifié dans la version 3.13: The `separator' parameter may now be a @ref{366,,tuple} of
separators.

@end deffn

@geindex at_eof() (méthode asyncio.StreamReader)
@anchor{library/asyncio-stream asyncio StreamReader at_eof}@anchor{3220}
@deffn {Méthode} at_eof ()

Renvoie @code{True} si le tampon est vide et que @ref{321b,,feed_eof()} a été appelée.
@end deffn
@end deffn

@node Flux écrivains StreamWriter,Exemples<15>,Flux lecteurs StreamReader,Flux streams
@anchor{library/asyncio-stream streamwriter}@anchor{3221}
@subsubsection Flux écrivains (`StreamWriter')


@geindex StreamWriter (classe dans asyncio)
@anchor{library/asyncio-stream asyncio StreamWriter}@anchor{1689}
@deffn {Classe} asyncio.StreamWriter

Représente un objet écrivain qui fournit des API pour écrire des données dans le flux d'entrée-sortie.

Il n'est pas recommandé d'instancier directement les objets `StreamWriter' ; utilisez @ref{b06,,open_connection()} et @ref{b07,,start_server()} à la place.

@geindex write() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter write}@anchor{3222}
@deffn {Méthode} write (data)

La méthode tente d'écrire immédiatement les `data' dans le connecteur sous-jacent. Si cela échoue, les données sont mises en file d'attente dans un tampon d'écriture interne jusqu'à ce qu'elles puissent être envoyées.

La méthode doit être utilisée avec la méthode @code{drain()} :

@example
stream.write(data)
await stream.drain()
@end example
@end deffn

@geindex writelines() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter writelines}@anchor{3223}
@deffn {Méthode} writelines (data)

La méthode écrit immédiatement une liste (ou tout itérable) d'octets dans le connecteur sous-jacent. Si cela échoue, les données sont mises en file d'attente dans un tampon d'écriture interne jusqu'à ce qu'elles puissent être envoyées.

La méthode doit être utilisée avec la méthode @code{drain()} :

@example
stream.writelines(lines)
await stream.drain()
@end example
@end deffn

@geindex close() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter close}@anchor{3215}
@deffn {Méthode} close ()

La méthode ferme le flux et le connecteur sous-jacent.

La méthode doit être utilisée, bien que ce ne soit pas obligatoire, avec la méthode @code{wait_closed()} :

@example
stream.close()
await stream.wait_closed()
@end example
@end deffn

@geindex can_write_eof() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter can_write_eof}@anchor{3224}
@deffn {Méthode} can_write_eof ()

Renvoie @code{True} si le transport sous-jacent gère la méthode @ref{3225,,write_eof()}, @code{False} sinon.
@end deffn

@geindex write_eof() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter write_eof}@anchor{3225}
@deffn {Méthode} write_eof ()

Ferme le flux en écriture après le vidage des données d'écriture en mémoire tampon.
@end deffn

@geindex transport (attribut asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter transport}@anchor{3226}
@deffn {Attribut} transport

Renvoie le transport asynchrone sous-jacent.
@end deffn

@geindex get_extra_info() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter get_extra_info}@anchor{3227}
@deffn {Méthode} get_extra_info (name, default=None)

Donne accès aux informations de transport facultatives ; voir @ref{a8a,,BaseTransport.get_extra_info()} pour plus de détails.
@end deffn

@geindex drain() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter drain}@anchor{173c}
@deffn {Méthode} coroutine drain ()

Attend qu'il soit approprié de reprendre l'écriture dans le flux. Par exemple :

@example
writer.write(data)
await writer.drain()
@end example

Il s'agit d'une méthode de contrôle de flux qui interagit avec le tampon d'écriture entrée-sortie sous-jacent. Lorsque la taille du tampon atteint la limite haute, `drain()' bloque jusqu'à ce que la taille du tampon soit drainée jusqu'à la limite basse et que l'écriture puisse reprendre. Lorsqu'il n'y a rien à attendre, @ref{173c,,drain()} termine immédiatement.
@end deffn

@geindex start_tls() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter start_tls}@anchor{5ef}
@deffn {Méthode} coroutine start_tls (sslcontext, *, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Bascule la connexion basée sur le flux existant vers TLS.

Paramètres :


@itemize *

@item 
`sslcontext' : une instance configurée de @ref{291,,SSLContext}.

@item 
`server_hostname' : définit ou remplace le nom d'hôte auquel le certificat du serveur cible sera comparé.

@item 
`ssl_handshake_timeout' est le temps en secondes à attendre pour que la poignée de main TLS se termine avant d'abandonner la connexion. @code{60.0} secondes si @code{None} (par défaut).

@item 
`ssl_shutdown_timeout' is the time in seconds to wait for the SSL shutdown
to complete before aborting the connection. @code{30.0} seconds if @code{None}
(default).
@end itemize


Ajouté dans la version 3.11.



Modifié dans la version 3.12: ajout du paramètre `ssl_shutdown_timeout'.

@end deffn

@geindex is_closing() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter is_closing}@anchor{afb}
@deffn {Méthode} is_closing ()

Renvoie @code{True} si le flux est fermé ou en cours de fermeture.


Ajouté dans la version 3.7.

@end deffn

@geindex wait_closed() (méthode asyncio.StreamWriter)
@anchor{library/asyncio-stream asyncio StreamWriter wait_closed}@anchor{afa}
@deffn {Méthode} coroutine wait_closed ()

Attend que le flux soit fermé.

Doit être appelée après @ref{3215,,close()} pour attendre que la connexion sous-jacente soit fermée, en s'assurant que toutes les données ont été vidées avant, par exemple, de quitter le programme.


Ajouté dans la version 3.7.

@end deffn
@end deffn

@node Exemples<15>,,Flux écrivains StreamWriter,Flux streams
@anchor{library/asyncio-stream examples}@anchor{3214}
@subsubsection Exemples


@menu
* Client d'écho TCP utilisant des flux:: 
* Serveur d'écho TCP utilisant des flux:: 
* Récupération des en-têtes HTTP:: 
* Ouverture d'un connecteur pour attendre les données à l'aide de flux:: 

@end menu

@node Client d'écho TCP utilisant des flux,Serveur d'écho TCP utilisant des flux,,Exemples<15>
@anchor{library/asyncio-stream asyncio-tcp-echo-client-streams}@anchor{3228}@anchor{library/asyncio-stream tcp-echo-client-using-streams}@anchor{3229}
@subsubsection Client d'écho TCP utilisant des flux


Client d'écho TCP utilisant la fonction @ref{b06,,asyncio.open_connection()} :

@example
import asyncio

async def tcp_echo_client(message):
    reader, writer = await asyncio.open_connection(
        '127.0.0.1', 8888)

    print(f'Send: @{message!r@}')
    writer.write(message.encode())
    await writer.drain()

    data = await reader.read(100)
    print(f'Received: @{data.decode()!r@}')

    print('Close the connection')
    writer.close()
    await writer.wait_closed()

asyncio.run(tcp_echo_client('Hello World!'))
@end example


@subsubheading Voir aussi


L'exemple @ref{322a,,Client écho en TCP} utilise la méthode de bas niveau @ref{5ee,,loop.create_connection()}.


@node Serveur d'écho TCP utilisant des flux,Récupération des en-têtes HTTP,Client d'écho TCP utilisant des flux,Exemples<15>
@anchor{library/asyncio-stream asyncio-tcp-echo-server-streams}@anchor{322b}@anchor{library/asyncio-stream tcp-echo-server-using-streams}@anchor{322c}
@subsubsection Serveur d'écho TCP utilisant des flux


Serveur d'écho TCP utilisant la fonction @ref{b07,,asyncio.start_server()} :

@example
import asyncio

async def handle_echo(reader, writer):
    data = await reader.read(100)
    message = data.decode()
    addr = writer.get_extra_info('peername')

    print(f"Received @{message!r@} from @{addr!r@}")

    print(f"Send: @{message!r@}")
    writer.write(data)
    await writer.drain()

    print("Close the connection")
    writer.close()
    await writer.wait_closed()

async def main():
    server = await asyncio.start_server(
        handle_echo, '127.0.0.1', 8888)

    addrs = ', '.join(str(sock.getsockname()) for sock in server.sockets)
    print(f'Serving on @{addrs@}')

    async with server:
        await server.serve_forever()

asyncio.run(main())
@end example


@subsubheading Voir aussi


L'exemple de @ref{322d,,Serveur écho en TCP} utilise la méthode @ref{b01,,loop.create_server()}.


@node Récupération des en-têtes HTTP,Ouverture d'un connecteur pour attendre les données à l'aide de flux,Serveur d'écho TCP utilisant des flux,Exemples<15>
@anchor{library/asyncio-stream get-http-headers}@anchor{322e}
@subsubsection Récupération des en-têtes HTTP


Exemple simple d'interrogation des en-têtes HTTP de l'URL transmise sur la ligne de commande :

@example
import asyncio
import urllib.parse
import sys

async def print_http_headers(url):
    url = urllib.parse.urlsplit(url)
    if url.scheme == 'https':
        reader, writer = await asyncio.open_connection(
            url.hostname, 443, ssl=True)
    else:
        reader, writer = await asyncio.open_connection(
            url.hostname, 80)

    query = (
        f"HEAD @{url.path or '/'@} HTTP/1.0\r\n"
        f"Host: @{url.hostname@}\r\n"
        f"\r\n"
    )

    writer.write(query.encode('latin-1'))
    while True:
        line = await reader.readline()
        if not line:
            break

        line = line.decode('latin1').rstrip()
        if line:
            print(f'HTTP header> @{line@}')

    # Ignore the body, close the socket
    writer.close()
    await writer.wait_closed()

url = sys.argv[1]
asyncio.run(print_http_headers(url))
@end example

Utilisation :

@example
python example.py http://example.com/path/page.html
@end example

ou avec HTTPS :

@example
python example.py https://example.com/path/page.html
@end example

@node Ouverture d'un connecteur pour attendre les données à l'aide de flux,,Récupération des en-têtes HTTP,Exemples<15>
@anchor{library/asyncio-stream asyncio-example-create-connection-streams}@anchor{322f}@anchor{library/asyncio-stream register-an-open-socket-to-wait-for-data-using-streams}@anchor{3230}
@subsubsection Ouverture d'un connecteur pour attendre les données à l'aide de flux


Coroutine attendant qu'un connecteur reçoive des données en utilisant la fonction @ref{b06,,open_connection()} :

@example
import asyncio
import socket

async def wait_for_data():
    # Get a reference to the current event loop because
    # we want to access low-level APIs.
    loop = asyncio.get_running_loop()

    # Create a pair of connected sockets.
    rsock, wsock = socket.socketpair()

    # Register the open socket to wait for data.
    reader, writer = await asyncio.open_connection(sock=rsock)

    # Simulate the reception of data from the network
    loop.call_soon(wsock.send, 'abc'.encode())

    # Wait for data
    data = await reader.read(100)

    # Got data, we are done: close the socket
    print("Received:", data.decode())
    writer.close()
    await writer.wait_closed()

    # Close the second socket
    wsock.close()

asyncio.run(wait_for_data())
@end example


@subsubheading Voir aussi


L'exemple @ref{3231,,Connexion de connecteurs existants} utilise un protocole de bas niveau et la méthode @ref{5ee,,loop.create_connection()}.

L'exemple @ref{3232,,Surveillance des événements de lecture pour un descripteur de fichier} utilise la méthode de bas niveau @ref{3233,,loop.add_reader()} pour surveiller un descripteur de fichier.


@node Primitives de synchronisation<2>,Sous-processus,Flux streams,asyncio --- Asynchronous I/O
@anchor{library/asyncio-sync doc}@anchor{3234}@anchor{library/asyncio-sync asyncio-sync}@anchor{31d7}@anchor{library/asyncio-sync synchronization-primitives}@anchor{3235}
@subsubsection Primitives de synchronisation


`Code source :' Lib/asyncio/locks.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/locks.py}


__________________________________________________________________


Les primitives de synchronisation `asyncio' sont conçues pour être similaires à celles du module @ref{ec,,threading} avec deux mises en garde importantes :


@itemize *

@item 
les primitives `asyncio' ne sont pas `thread-safe', elles ne doivent donc pas être utilisées pour la synchronisation des fils d'exécution du système d'exploitation (utilisez @ref{ec,,threading} pour cela) ;

@item 
les méthodes de ces primitives de synchronisation n'acceptent pas l'argument `timeout' ; utilisez la fonction @ref{5ea,,asyncio.wait_for()} pour effectuer des opérations avec des délais d'attente.
@end itemize

`asyncio' possède les primitives de synchronisation de base suivantes :


@itemize *

@item 
@ref{a5f,,Lock}

@item 
@ref{a60,,Event}

@item 
@ref{a61,,Condition}

@item 
@ref{a62,,Semaphore}

@item 
@ref{a63,,BoundedSemaphore}

@item 
@ref{5ec,,Barrier}
@end itemize


__________________________________________________________________


@menu
* Verrou (lock): Verrou lock. 
* Événement (Event): Événement Event. 
* Condition:: 
* Sémaphore:: 
* Sémaphore capé (BoundedSemaphore): Sémaphore capé BoundedSemaphore. 
* Barrière (Barrier): Barrière Barrier. 

@end menu

@node Verrou lock,Événement Event,,Primitives de synchronisation<2>
@anchor{library/asyncio-sync lock}@anchor{3236}
@subsubsection Verrou (`lock')


@geindex Lock (classe dans asyncio)
@anchor{library/asyncio-sync asyncio Lock}@anchor{a5f}
@deffn {Classe} asyncio.Lock

Implémente un verrou exclusif (`mutex') pour les tâches asynchrones. Ce n'est pas compatible avec les programmes à fils d'exécution multiples.

Un verrou `asyncio' peut être utilisé pour garantir un accès exclusif à une ressource partagée.

La meilleure façon d'utiliser un verrou est une instruction @ref{5bf,,async with}

@example
lock = asyncio.Lock()

# ... later
async with lock:
    # access shared state
@end example

ce qui équivaut à :

@example
lock = asyncio.Lock()

# ... later
await lock.acquire()
try:
    # access shared state
finally:
    lock.release()
@end example


Modifié dans la version 3.10: suppression du paramètre `loop'.


@geindex acquire() (méthode asyncio.Lock)
@anchor{library/asyncio-sync asyncio Lock acquire}@anchor{3237}
@deffn {Méthode} coroutine acquire ()

Verrouille (ou acquiert) le verrou.

Cette méthode attend que le verrou soit déverrouillé (`unlocked'), le verrouille (positionné sur `locked') et renvoie @code{True}.

Lorsque plus d'une coroutine est bloquée dans @ref{3237,,acquire()} en attendant que le verrou soit déverrouillé, seule une coroutine continue finalement.

L'acquisition d'un verrou est `équitable' : la coroutine qui acquiert le verrou est celle qui était la première à attendre le verrou.
@end deffn

@geindex release() (méthode asyncio.Lock)
@anchor{library/asyncio-sync asyncio Lock release}@anchor{3238}
@deffn {Méthode} release ()

Libère le verrou.

Lorsque le verrou est verrouillé, le déverrouille et termine.

Si le verrou est déjà déverrouillé, une @ref{193,,RuntimeError} est levée.
@end deffn

@geindex locked() (méthode asyncio.Lock)
@anchor{library/asyncio-sync asyncio Lock locked}@anchor{3239}
@deffn {Méthode} locked ()

Renvoie @code{True} si le verrou est verrouillé.
@end deffn
@end deffn

@node Événement Event,Condition,Verrou lock,Primitives de synchronisation<2>
@anchor{library/asyncio-sync event}@anchor{323a}
@subsubsection Événement (`Event')


@geindex Event (classe dans asyncio)
@anchor{library/asyncio-sync asyncio Event}@anchor{a60}
@deffn {Classe} asyncio.Event

Objet événement. Non compatible avec les programmes à plusieurs fils d'exécution.

Un événement asynchrone peut être utilisé pour notifier plusieurs tâches asynchrones qu'un événement s'est produit.

Un objet `Event' gère un drapeau interne qui peut être activé (ou mis à `vrai') avec la méthode @ref{323b,,set()} et désactivé (ou mis à `faux') avec la méthode @ref{323c,,clear()}. La méthode @ref{323d,,wait()} se bloque jusqu'à ce que l'indicateur soit activé. L'indicateur est initialement désactivé.


Modifié dans la version 3.10: suppression du paramètre `loop'.

@anchor{library/asyncio-sync asyncio-example-sync-event}@anchor{323e}
Exemple :

@example
async def waiter(event):
    print('waiting for it ...')
    await event.wait()
    print('... got it!')

async def main():
    # Create an Event object.
    event = asyncio.Event()

    # Spawn a Task to wait until 'event' is set.
    waiter_task = asyncio.create_task(waiter(event))

    # Sleep for 1 second and set the event.
    await asyncio.sleep(1)
    event.set()

    # Wait until the waiter task is finished.
    await waiter_task

asyncio.run(main())
@end example

@geindex wait() (méthode asyncio.Event)
@anchor{library/asyncio-sync asyncio Event wait}@anchor{323d}
@deffn {Méthode} coroutine wait ()

Attend que l'évènement soit activé.

Si l'événement est activé (`vrai'), renvoie @code{True} immédiatement. Sinon bloque jusqu'à ce qu'une autre tâche appelle @ref{323b,,set()}.
@end deffn

@geindex set() (méthode asyncio.Event)
@anchor{library/asyncio-sync asyncio Event set}@anchor{323b}
@deffn {Méthode} set ()

Active l'événement.

Toutes les tâches en attente de l'événement sont immédiatement réveillées.
@end deffn

@geindex clear() (méthode asyncio.Event)
@anchor{library/asyncio-sync asyncio Event clear}@anchor{323c}
@deffn {Méthode} clear ()

Efface (désactive) l'événement.

Les tâches en attente sur @ref{323d,,wait()} seront désormais bloquées jusqu'à ce que la méthode @ref{323b,,set()} soit à nouveau appelée.
@end deffn

@geindex is_set() (méthode asyncio.Event)
@anchor{library/asyncio-sync asyncio Event is_set}@anchor{323f}
@deffn {Méthode} is_set ()

Renvoie @code{True} si l'évènement est actif.
@end deffn
@end deffn

@node Condition,Sémaphore,Événement Event,Primitives de synchronisation<2>
@anchor{library/asyncio-sync condition}@anchor{3240}
@subsubsection Condition


@geindex Condition (classe dans asyncio)
@anchor{library/asyncio-sync asyncio Condition}@anchor{a61}
@deffn {Classe} asyncio.Condition (lock=None)

Objet Condition. Non compatible avec les programmes à plusieurs fils d'exécution.

Une primitive de condition asynchrone peut être utilisée par une tâche pour attendre qu'un événement se produise, puis obtenir un accès exclusif à une ressource partagée.

Essentiellement, un objet `Condition' combine les fonctionnalités d'un @ref{a60,,Event} et d'un @ref{a5f,,Lock}. Il est possible que plusieurs objets `Condition' partagent un seul verrou, ce qui permet de coordonner l'accès exclusif à une ressource partagée entre différentes tâches intéressées par des états particuliers de cette ressource partagée.

L'argument optionnel `lock' doit être un objet @ref{a5f,,Lock} ou @code{None}. Dans ce dernier cas, un nouvel objet `Lock' est créé automatiquement.


Modifié dans la version 3.10: suppression du paramètre `loop'.


La meilleure façon d'utiliser une `Condition' est une instruction @ref{5bf,,async with}

@example
cond = asyncio.Condition()

# ... later
async with cond:
    await cond.wait()
@end example

ce qui équivaut à :

@example
cond = asyncio.Condition()

# ... later
await cond.acquire()
try:
    await cond.wait()
finally:
    cond.release()
@end example

@geindex acquire() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition acquire}@anchor{3241}
@deffn {Méthode} coroutine acquire ()

Verrouille le verrou sous-jacent.

Cette méthode attend que le verrou sous-jacent soit déverrouillé, le verrouille et renvoie @code{True}.
@end deffn

@geindex notify() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition notify}@anchor{1603}
@deffn {Méthode} notify (n=1)

Wake up `n' tasks (1 by default) waiting on this
condition.  If fewer than `n' tasks are waiting they are all awakened.

Le verrou doit être verrouillé avant que cette méthode ne soit appelée et libéré peu de temps après. S'il est appelé avec un verrou déverrouillé, une erreur @ref{193,,RuntimeError} est levée.
@end deffn

@geindex locked() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition locked}@anchor{3242}
@deffn {Méthode} locked ()

Renvoie @code{True} si le verrou sous-jacent est verrouillé.
@end deffn

@geindex notify_all() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition notify_all}@anchor{3243}
@deffn {Méthode} notify_all ()

Réveille toutes les tâches en attente sur cette condition.

Cette méthode agit comme @ref{1603,,notify()}, mais réveille toutes les tâches en attente.

Le verrou doit être verrouillé avant que cette méthode ne soit appelée et libéré peu de temps après. S'il est appelé avec un verrou déverrouillé, une erreur @ref{193,,RuntimeError} est levée.
@end deffn

@geindex release() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition release}@anchor{3244}
@deffn {Méthode} release ()

Libère le verrou sous-jacent.

Lorsqu'elle est invoquée sur un verrou déverrouillé, une @ref{193,,RuntimeError} est levée.
@end deffn

@geindex wait() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition wait}@anchor{162e}
@deffn {Méthode} coroutine wait ()

Attend d'être notifié.

Si la tâche appelante n'a pas verrouillé le verrou lorsque cette méthode est appelée, une @ref{193,,RuntimeError} est levée.

Cette méthode libère le verrou sous-jacent, puis se bloque jusqu'à ce qu'elle soit réveillée par un appel @ref{1603,,notify()} ou @ref{3243,,notify_all()}. Une fois réveillée, la `Condition' verrouille à nouveau son verrou et cette méthode renvoie @code{True}.

Note that a task `may' return from this call spuriously,
which is why the caller should always re-check the state
and be prepared to @ref{162e,,wait()} again. For this reason, you may
prefer to use @ref{3245,,wait_for()} instead.
@end deffn

@geindex wait_for() (méthode asyncio.Condition)
@anchor{library/asyncio-sync asyncio Condition wait_for}@anchor{3245}
@deffn {Méthode} coroutine wait_for (predicate)

Attend jusqu'à ce qu'un prédicat devienne vrai.

The predicate must be a callable which result will be
interpreted as a boolean value.  The method will repeatedly
@ref{162e,,wait()} until the predicate evaluates to `true'. The final value is the
return value.
@end deffn
@end deffn

@node Sémaphore,Sémaphore capé BoundedSemaphore,Condition,Primitives de synchronisation<2>
@anchor{library/asyncio-sync semaphore}@anchor{3246}
@subsubsection Sémaphore


@geindex Semaphore (classe dans asyncio)
@anchor{library/asyncio-sync asyncio Semaphore}@anchor{a62}
@deffn {Classe} asyncio.Semaphore (value=1)

Objet `Sémaphore'. Non compatible avec les programmes à plusieurs fils d'exécution.

Un sémaphore gère un compteur interne qui est décrémenté à chaque appel @ref{162f,,acquire()} et incrémenté à chaque appel @ref{3247,,release()}. Le compteur ne peut jamais descendre en dessous de zéro ; quand @ref{162f,,acquire()} trouve qu'il est égal à zéro, il se bloque, en attendant qu'une tâche appelle @ref{3247,,release()}.

L'argument optionnel `value' donne la valeur initiale du compteur interne (@code{1} par défaut). Si la valeur donnée est inférieure à @code{0} une @ref{1ff,,ValueError} est levée.


Modifié dans la version 3.10: suppression du paramètre `loop'.


La meilleure façon d'utiliser un sémaphore est une instruction @ref{5bf,,async with}

@example
sem = asyncio.Semaphore(10)

# ... later
async with sem:
    # work with shared resource
@end example

ce qui équivaut à :

@example
sem = asyncio.Semaphore(10)

# ... later
await sem.acquire()
try:
    # work with shared resource
finally:
    sem.release()
@end example

@geindex acquire() (méthode asyncio.Semaphore)
@anchor{library/asyncio-sync asyncio Semaphore acquire}@anchor{162f}
@deffn {Méthode} coroutine acquire ()

Acquiert un sémaphore.

Si le compteur interne est supérieur à zéro, le décrémente d'une unité et renvoie @code{True} immédiatement. Si c'est zéro, attend que @ref{3247,,release()} soit appelée et renvoie @code{True}.
@end deffn

@geindex locked() (méthode asyncio.Semaphore)
@anchor{library/asyncio-sync asyncio Semaphore locked}@anchor{3248}
@deffn {Méthode} locked ()

Renvoie @code{True} si le sémaphore ne peut pas être acquis immédiatement.
@end deffn

@geindex release() (méthode asyncio.Semaphore)
@anchor{library/asyncio-sync asyncio Semaphore release}@anchor{3247}
@deffn {Méthode} release ()

Relâche un sémaphore, incrémentant le compteur interne d'une unité. Peut réveiller une tâche en attente d'acquisition du sémaphore.

Contrairement à @ref{a63,,BoundedSemaphore}, @ref{a62,,Semaphore} permet de faire plus d'appels @code{release()} que d'appels @code{acquire()}.
@end deffn
@end deffn

@node Sémaphore capé BoundedSemaphore,Barrière Barrier,Sémaphore,Primitives de synchronisation<2>
@anchor{library/asyncio-sync boundedsemaphore}@anchor{3249}
@subsubsection Sémaphore capé (`BoundedSemaphore')


@geindex BoundedSemaphore (classe dans asyncio)
@anchor{library/asyncio-sync asyncio BoundedSemaphore}@anchor{a63}
@deffn {Classe} asyncio.BoundedSemaphore (value=1)

Objet sémaphore capé. Non compatible avec les programmes à plusieurs fils d'exécution.

`Bounded Semaphore' est une version de @ref{a62,,Semaphore} qui lève une @ref{1ff,,ValueError} dans @ref{3247,,release()} s'il augmente le compteur interne au-dessus de la `value' initiale.


Modifié dans la version 3.10: suppression du paramètre `loop'.

@end deffn

@node Barrière Barrier,,Sémaphore capé BoundedSemaphore,Primitives de synchronisation<2>
@anchor{library/asyncio-sync barrier}@anchor{324a}
@subsubsection Barrière (`Barrier')


@geindex Barrier (classe dans asyncio)
@anchor{library/asyncio-sync asyncio Barrier}@anchor{5ec}
@deffn {Classe} asyncio.Barrier (parties)

Objet barrière. Non compatible avec les programmes à plusieurs fils d'exécution.

Une barrière est une simple primitive de synchronisation qui permet de bloquer jusqu'à ce que `parties' tâches l'attendent. Les tâches attendent sur la méthode @ref{324b,,wait()} et sont bloquées jusqu'à ce que le nombre spécifié de tâches attendent sur @ref{324b,,wait()}. À ce stade, toutes les tâches en attente se débloquent simultanément.

@ref{5bf,,async with} peut être utilisé comme alternative à l'attente sur @ref{324b,,wait()}.

La barrière peut être réutilisée un nombre illimité de fois.
@anchor{library/asyncio-sync asyncio-example-barrier}@anchor{324c}
Exemple :

@example
async def example_barrier():
   # barrier with 3 parties
   b = asyncio.Barrier(3)

   # create 2 new waiting tasks
   asyncio.create_task(b.wait())
   asyncio.create_task(b.wait())

   await asyncio.sleep(0)
   print(b)

   # The third .wait() call passes the barrier
   await b.wait()
   print(b)
   print("barrier passed")

   await asyncio.sleep(0)
   print(b)

asyncio.run(example_barrier())
@end example

Le résultat de cet exemple est :

@example
<asyncio.locks.Barrier object at 0x... [filling, waiters:2/3]>
<asyncio.locks.Barrier object at 0x... [draining, waiters:0/3]>
barrier passed
<asyncio.locks.Barrier object at 0x... [filling, waiters:0/3]>
@end example


Ajouté dans la version 3.11.


@geindex wait() (méthode asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier wait}@anchor{324b}
@deffn {Méthode} coroutine wait ()

Passe la barrière. Lorsque toutes les tâches bloquées à la barrière ont appelé cette fonction, elles sont toutes débloquées simultanément.

Lorsqu'une tâche en attente ou bloquée à la barrière est annulée, cette tâche sort de la barrière qui reste dans le même état. Si la barrière est en cours de « remplissage », le nombre de tâche en attente diminue de 1.

La valeur de retour est un entier compris entre 0 et @code{parties-1}, différent pour chaque tâche. Cela peut être utilisé pour sélectionner une tâche qui fera du ménage, par exemple :

@example
...
async with barrier as position:
   if position == 0:
      # Only one task prints this
      print('End of *draining phase*')
@end example

Cette méthode peut lever une exception @ref{5ed,,BrokenBarrierError} si la barrière est brisée ou réinitialisée alors qu'une tâche est en attente. Cela peut lever une @ref{1b6,,CancelledError} si une tâche est annulée.
@end deffn

@geindex reset() (méthode asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier reset}@anchor{324d}
@deffn {Méthode} coroutine reset ()

Ramène la barrière à l'état vide par défaut. Toutes les tâches en attente reçoivent l'exception @ref{5ed,,BrokenBarrierError}.

Si une barrière est brisée, il peut être préférable de la quitter et d'en créer une nouvelle.
@end deffn

@geindex abort() (méthode asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier abort}@anchor{324e}
@deffn {Méthode} coroutine abort ()

Put the barrier into a broken state.  This causes any active or future
calls to @ref{324b,,wait()} to fail with the @ref{5ed,,BrokenBarrierError}.
Use this for example if one of the tasks needs to abort, to avoid infinite
waiting tasks.
@end deffn

@geindex parties (attribut asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier parties}@anchor{324f}
@deffn {Attribut} parties

Le nombre de tâches nécessaires pour franchir la barrière.
@end deffn

@geindex n_waiting (attribut asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier n_waiting}@anchor{3250}
@deffn {Attribut} n_waiting

Le nombre de tâches actuellement en attente à la barrière pendant le remplissage.
@end deffn

@geindex broken (attribut asyncio.Barrier)
@anchor{library/asyncio-sync asyncio Barrier broken}@anchor{3251}
@deffn {Attribut} broken

Booléen qui vaut @code{True} si la barrière est rompue.
@end deffn
@end deffn

@geindex BrokenBarrierError
@anchor{library/asyncio-sync asyncio BrokenBarrierError}@anchor{5ed}
@deffn {Exception} asyncio.BrokenBarrierError

Cette exception, une sous-classe de @ref{193,,RuntimeError}, est déclenchée lorsque l'objet @ref{5ec,,Barrier} est réinitialisé ou cassé.
@end deffn


__________________________________________________________________



Modifié dans la version 3.9: l'acquisition d'un verrou en utilisant @code{wait lock} ou @code{yield from lock} ou @ref{5bc,,with} (@code{with await lock}, @code{with (yield from lock)}) a été supprimée. Utilisez @code{async with lock} à la place.


@node Sous-processus,Files d'attente queues,Primitives de synchronisation<2>,asyncio --- Asynchronous I/O
@anchor{library/asyncio-subprocess doc}@anchor{3252}@anchor{library/asyncio-subprocess asyncio-subprocess}@anchor{31d5}@anchor{library/asyncio-subprocess subprocesses}@anchor{3253}
@subsubsection Sous-processus


`Code source :' Lib/asyncio/subprocess.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/subprocess.py}, Lib/asyncio/base_subprocess.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/base_subprocess.py}


__________________________________________________________________


Cette section décrit des API de haut niveau de `asyncio' pour créer et gérer des sous-processus via @code{async}/@code{await}.
@anchor{library/asyncio-subprocess asyncio-example-subprocess-shell}@anchor{3254}
Voici un exemple de comment `asyncio' peut lancer une commande shell et obtenir son résultat :

@example
import asyncio

async def run(cmd):
    proc = await asyncio.create_subprocess_shell(
        cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE)

    stdout, stderr = await proc.communicate()

    print(f'[@{cmd!r@} exited with @{proc.returncode@}]')
    if stdout:
        print(f'[stdout]\n@{stdout.decode()@}')
    if stderr:
        print(f'[stderr]\n@{stderr.decode()@}')

asyncio.run(run('ls /zzz'))
@end example

affiche :

@example
['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory
@end example

Puisque toutes les fonctions à sous-processus d'`asyncio' sont synchrones et qu'`asyncio' fournit de nombreux outils pour travailler avec de telles fonctions, il est facile d'exécuter et de surveiller de nombreux processus  en parallèle. Il est en effet trivial de modifier l'exemple ci-dessus pour exécuter plusieurs commandes simultanément :

@example
async def main():
    await asyncio.gather(
        run('ls /zzz'),
        run('sleep 1; echo "hello"'))

asyncio.run(main())
@end example

Voir également la section @ref{3255,,Exemples}.

@menu
* Créer des sous-processus:: 
* Constantes: Constantes<7>. 
* Interagir avec les sous-processus:: 

@end menu

@node Créer des sous-processus,Constantes<7>,,Sous-processus
@anchor{library/asyncio-subprocess creating-subprocesses}@anchor{3256}
@subsubsection Créer des sous-processus


@geindex create_subprocess_exec() (dans le module asyncio)
@anchor{library/asyncio-subprocess asyncio create_subprocess_exec}@anchor{a65}
@deffn {Fonction} coroutine asyncio.create_subprocess_exec (program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

Crée un sous-processus.

The `limit' argument sets the buffer limit for @ref{1853,,StreamReader}
wrappers for @code{Process.stdout} and @code{Process.stderr}
(if @ref{b75,,subprocess.PIPE} is passed to `stdout' and `stderr' arguments).

Renvoie une instance de @ref{3257,,Process}.

Voir la documentation de @ref{3258,,loop.subprocess_exec()} pour d'autres paramètres.


Modifié dans la version 3.10: suppression du paramètre `loop'.

@end deffn

@geindex create_subprocess_shell() (dans le module asyncio)
@anchor{library/asyncio-subprocess asyncio create_subprocess_shell}@anchor{a66}
@deffn {Fonction} coroutine asyncio.create_subprocess_shell (cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

Exécute la commande `cmd' dans un `shell'.

The `limit' argument sets the buffer limit for @ref{1853,,StreamReader}
wrappers for @code{Process.stdout} and @code{Process.stderr}
(if @ref{b75,,subprocess.PIPE} is passed to `stdout' and `stderr' arguments).

Renvoie une instance de @ref{3257,,Process}.

Voir la documentation de @ref{3259,,loop.subprocess_shell()} pour d'autres paramètres.

@cartouche
@quotation Important 
Il est de la responsabilité de l'application de s'assurer que tous les espaces et les caractères spéciaux sont correctement mis entre guillemets pour éviter les vulnérabilités de type injection de code@footnote{https://en.wikipedia.org/wiki/Shell_injection#Shell_injection}. La fonction @ref{27a,,shlex.quote()} peut être utilisée pour l’échappement des espaces et caractères spéciaux dans les chaînes utilisées pour construire des commandes shell.
@end quotation
@end cartouche


Modifié dans la version 3.10: suppression du paramètre `loop'.

@end deffn

@cartouche
@quotation Note 
les sous-processus sont disponibles pour Windows si un @ref{5f4,,ProactorEventLoop} est utilisé. Voir @ref{325a,,Support des sous-processus sous Windows} pour plus de précisions.
@end quotation
@end cartouche


@subsubheading Voir aussi


`asyncio' propose aussi les API de « bas niveau » suivantes pour travailler avec les sous-processus : @ref{3258,,loop.subprocess_exec()}, @ref{3259,,loop.subprocess_shell()}, @ref{325b,,loop.connect_read_pipe()}, @ref{325c,,loop.connect_write_pipe()}, ainsi que les @ref{325d,,Transports entre sous-processus} et @ref{325e,,Protocoles liés aux sous-processus}.


@node Constantes<7>,Interagir avec les sous-processus,Créer des sous-processus,Sous-processus
@anchor{library/asyncio-subprocess constants}@anchor{325f}
@subsubsection Constantes


@geindex asyncio.subprocess.PIPE (variable de base)
@anchor{library/asyncio-subprocess asyncio subprocess PIPE}@anchor{3260}
@deffn {Données} asyncio.subprocess.PIPE

Peut être passé aux paramètres  `stdin', `stdout' ou `stderr'.

Si `PIPE' est passé au paramètre `stdin', l'attribut @ref{3261,,Process.stdin} ne pointera pas vers une instance de @code{StreamWriter}.

Si `PIPE' est passé au paramètre `stdout' ou `stderr', l'attribut @ref{3262,,Process.stdout} et @ref{3263,,Process.stderr} pointeront vers des instances de @code{StreamReader}.
@end deffn

@geindex asyncio.subprocess.STDOUT (variable de base)
@anchor{library/asyncio-subprocess asyncio subprocess STDOUT}@anchor{3264}
@deffn {Données} asyncio.subprocess.STDOUT

Une valeur spéciale qui peut être passée au paramètre `stderr' et qui indique que la sortie d'erreur doit être redirigée vers la sortie standard.
@end deffn

@geindex asyncio.subprocess.DEVNULL (variable de base)
@anchor{library/asyncio-subprocess asyncio subprocess DEVNULL}@anchor{3265}
@deffn {Données} asyncio.subprocess.DEVNULL

Une valeur spéciale qui peut être passée à l'argument `stdin', `stdout' ou `stderr' des fonctions créant des processus. Elle implique l'utilisation du fichier @ref{19c1,,os.devnull} pour le flux correspondant du processus.
@end deffn

@node Interagir avec les sous-processus,,Constantes<7>,Sous-processus
@anchor{library/asyncio-subprocess interacting-with-subprocesses}@anchor{3266}
@subsubsection Interagir avec les sous-processus


Les fonctions @ref{a65,,create_subprocess_exec()} et @ref{a66,,create_subprocess_shell()} renvoient des instances de la classe `Process'. `Process' est une enveloppe de haut niveau qui permet de communiquer avec les sous-processus et de surveiller leur achèvement.

@geindex asyncio.subprocess.Process (classe de base)
@anchor{library/asyncio-subprocess asyncio subprocess Process}@anchor{3257}
@deffn {Classe} asyncio.subprocess.Process

Objet qui encapsule les processus du système d'exploitation créés par les fonctions @code{create_subprocess_exec()} et @code{create_subprocess_shell()}.

Cette classe est conçue pour avoir une API similaire à la classe @ref{197,,subprocess.Popen}, mais il existe quelques différences notables :


@itemize *

@item 
contrairement à `Popen', les instances Process n'ont pas d'équivalent à la méthode @ref{3175,,poll()} ;

@item 
les méthodes @ref{16b9,,communicate()} et @ref{3267,,wait()} n'ont pas de paramètre `timeout' : utilisez la fonction @ref{5ea,,wait_for()} ;

@item 
@ref{3267,,asyncio.subprocess.Process.wait()} est asynchrone, tandis que la méthode @ref{cd2,,subprocess.Popen.wait()} est implémentée comme une boucle bloquante ;

@item 
le paramètre `universal_newlines' n'est pas pris en charge.
@end itemize

Cette classe n'est @ref{3202,,pas conçue pour un contexte multi-fils}.

Voir aussi la section @ref{3268,,sous-processus et fils d'exécution}.

@geindex wait() (méthode asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process wait}@anchor{3267}
@deffn {Méthode} coroutine wait ()

Attend que le sous processus s'arrête.

Définit et renvoie l'attribut @ref{3269,,returncode}.

@cartouche
@quotation Note 
cette méthode peut générer un interblocage quand @code{stdout=PIPE} ou @code{stderr=PIPE} est utilisé et que le sous-processus génère tellement de sorties qu'il se bloque, dans l'attente que le tampon du tube côté OS accepte des données supplémentaires. Pour éviter cette situation, choisissez la méthode @ref{16b9,,communicate()} quand vous utilisez des tubes.
@end quotation
@end cartouche
@end deffn

@geindex communicate() (méthode asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process communicate}@anchor{16b9}
@deffn {Méthode} coroutine communicate (input=None)

Interagit avec le processus :


@enumerate 

@item 
envoie des données sur le `stdin' (si `input' n'est pas @code{None}) ;

@item 
closes `stdin';

@item 
lit les données sur `stdout' et `stderr', jusqu'à ce que le EOF soit atteint ;

@item 
attend que le processus s'arrête.
@end enumerate

Le paramètre optionnel `input' (objet de type @ref{1bd,,bytes}) représente les données transmises au sous-processus.

Renvoie un `n'-uplet @code{(stdout_data, stderr_data)}.

Si l'une des exceptions @ref{1045,,BrokenPipeError} ou @ref{1048,,ConnectionResetError} est levée lors de l'écriture de `input' dans `stdin', l'exception est ignorée. Cette condition se produit lorsque le processus se termine avant que toutes les données ne soient écrites dans `stdin'.

Si vous souhaitez envoyer des données au processus `stdin', le processus doit être créé avec @code{stdin=PIPE}. De même, pour obtenir autre chose que @code{None} dans le `n'-uplet résultat, le processus doit être créé avec les arguments @code{stdout=PIPE} et/ou @code{stderr=PIPE}.

Notez que les données lues sont mises en cache en mémoire, donc n'utilisez pas cette méthode si la taille des données est importante voire illimitée.


Modifié dans la version 3.12: `stdin' gets closed when @cite{input=None} too.

@end deffn

@geindex send_signal() (méthode asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process send_signal}@anchor{1580}
@deffn {Méthode} send_signal (signal)

Envoie le signal `signal' au sous-processus.

@cartouche
@quotation Note 
On Windows, @ref{1396,,SIGTERM} is an alias for @ref{326a,,terminate()}.
@code{CTRL_C_EVENT} and @code{CTRL_BREAK_EVENT} can be sent to processes
started with a `creationflags' parameter which includes
@code{CREATE_NEW_PROCESS_GROUP}.
@end quotation
@end cartouche
@end deffn

@geindex terminate() (méthode asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process terminate}@anchor{326a}
@deffn {Méthode} terminate ()

Arrête le sous-processus.

On POSIX systems this method sends @ref{1396,,SIGTERM} to the
child process.

On Windows the Win32 API function @code{TerminateProcess()} is
called to stop the child process.
@end deffn

@geindex kill() (méthode asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process kill}@anchor{326b}
@deffn {Méthode} kill ()

Arrête le sous-processus.

Sur les systèmes POSIX, cette méthode envoie @ref{1396,,signal.SIGTERM} au sous-processus.

Sous Windows, cette méthode est un alias pour @ref{326a,,terminate()}.
@end deffn

@geindex stdin (attribut asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process stdin}@anchor{3261}
@deffn {Attribut} stdin

Flux d'entrée standard (@code{StreamWriter}) ou @code{None} si le processus a été créé avec @code{stdin=None}.
@end deffn

@geindex stdout (attribut asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process stdout}@anchor{3262}
@deffn {Attribut} stdout

Flux de sortie standard (@code{StreamReader}) ou @code{None} si le processus a été créé avec @code{stdout=None}.
@end deffn

@geindex stderr (attribut asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process stderr}@anchor{3263}
@deffn {Attribut} stderr

Flux d'erreur standard (@code{StreamReader}) ou @code{None} si le processus a été créé avec @code{stderr=None}.
@end deffn

@cartouche
@quotation Avertissement 
utilisez la méthode @ref{16b9,,communicate()} plutôt que @ref{3261,,process.stdin.write()}, @ref{3262,,wait process.stdout.read()} ou @ref{3263,,wait process.stderr.read()}. Cela évite les interblocages dus aux flux qui interrompent la lecture ou l'écriture et bloquent le processus enfant.
@end quotation
@end cartouche

@geindex pid (attribut asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process pid}@anchor{326c}
@deffn {Attribut} pid

Numéro d'identification du processus (PID, pour `Process Identification Number' en anglais).

Notez que pour les processus créés par la fonction @code{create_subprocess_shell()}, cet attribut est le PID du shell généré.
@end deffn

@geindex returncode (attribut asyncio.subprocess.Process)
@anchor{library/asyncio-subprocess asyncio subprocess Process returncode}@anchor{3269}
@deffn {Attribut} returncode

Code de retour du processus quand il se termine.

Une valeur @code{None} indique que le processus n'est pas encore terminé.

Une valeur négative @code{-N} indique que le sous-processus a été terminé par le signal @code{N} (seulement sur les systèmes `POSIX').
@end deffn
@end deffn

@menu
* Sous-processus et fils d'exécution:: 
* Exemples: Exemples<16>. 

@end menu

@node Sous-processus et fils d'exécution,Exemples<16>,,Interagir avec les sous-processus
@anchor{library/asyncio-subprocess asyncio-subprocess-threads}@anchor{3268}@anchor{library/asyncio-subprocess subprocess-and-threads}@anchor{326d}
@subsubsection Sous-processus et fils d'exécution


La boucle d'événement asynchrone standard prend en charge l'exécution de sous-processus à partir de différents fils d'exécution par défaut.

Sous Windows, les sous-processus sont fournis par @ref{5f4,,ProactorEventLoop} uniquement (par défaut), @ref{5f3,,SelectorEventLoop} ne prend pas en charge les sous-processus.

Sous UNIX, les `observateurs d'enfants (child watchers)' sont utilisés pour l'attente de fin de sous-processus, voir @ref{326e,,Observateurs de processus} pour plus d'informations.


Modifié dans la version 3.8: UNIX est passé à l'utilisation de @ref{465,,ThreadedChildWatcher} pour générer des sous-processus à partir de différents threads sans aucune limitation.

Instancier un sous-processus avec un observateur enfant actuel `inactif' lève l'exception @ref{193,,RuntimeError}.


Notez que ces implémentations alternatives de la boucle d'événements peuvent comporter leurs propres limitations. Veuillez vous référer à leur documentation.


@subsubheading Voir aussi


la section @ref{3202,,Exécution concurrente et multi-fils d'exécution}.


@node Exemples<16>,,Sous-processus et fils d'exécution,Interagir avec les sous-processus
@anchor{library/asyncio-subprocess examples}@anchor{3255}
@subsubsection Exemples


Un exemple utilisant la classe @ref{3257,,Process} pour contrôler un sous-processus et la classe @ref{1853,,StreamReader} pour lire sa sortie standard.
@anchor{library/asyncio-subprocess asyncio-example-create-subprocess-exec}@anchor{326f}
Le sous-processus est créé par la fonction @ref{a65,,create_subprocess_exec()} :

@example
import asyncio
import sys

async def get_date():
    code = 'import datetime; print(datetime.datetime.now())'

    # Create the subprocess; redirect the standard output
    # into a pipe.
    proc = await asyncio.create_subprocess_exec(
        sys.executable, '-c', code,
        stdout=asyncio.subprocess.PIPE)

    # Read one line of output.
    data = await proc.stdout.readline()
    line = data.decode('ascii').rstrip()

    # Wait for the subprocess exit.
    await proc.wait()
    return line

date = asyncio.run(get_date())
print(f"Current date: @{date@}")
@end example

Voir également @ref{3270,,le même exemple}, écrit en utilisant des API de bas niveau.

@node Files d'attente queues,Exceptions<13>,Sous-processus,asyncio --- Asynchronous I/O
@anchor{library/asyncio-queue doc}@anchor{3271}@anchor{library/asyncio-queue asyncio-queues}@anchor{31d6}@anchor{library/asyncio-queue queues}@anchor{3272}
@subsubsection Files d'attente (`queues')


`Code source :' Lib/asyncore.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncore.py}


__________________________________________________________________


Les files d'attente `asyncio' sont conçues pour être similaires aux classes du module @ref{b5,,queue}. Bien que les files d'attente `asyncio' ne soient pas compatibles avec les programmes à multiples fils d'exécution, elles sont conçues pour être utilisées spécifiquement dans le code `async/await'.

Notez que les méthodes des files d'attente `asyncio' n'ont pas de paramètre `timeout' ; utilisez la fonction @ref{5ea,,asyncio.wait_for()} pour effectuer des opérations de file d'attente avec un délai d'attente.

Voir également la section @ref{3273,,Exemples} ci-dessous.

@menu
* File d'attente (queue): File d'attente queue. 
* File avec priorité:: 
* Pile (LIFO): Pile LIFO. 
* Exceptions: Exceptions<12>. 
* Exemples: Exemples<17>. 

@end menu

@node File d'attente queue,File avec priorité,,Files d'attente queues
@anchor{library/asyncio-queue queue}@anchor{3274}
@subsubsection File d'attente (`queue')


@geindex Queue (classe dans asyncio)
@anchor{library/asyncio-queue asyncio Queue}@anchor{a64}
@deffn {Classe} asyncio.Queue (maxsize=0)

File d'attente premier entré, premier sorti (FIFO pour `fist in, first out').

Si `maxsize' est inférieur ou égal à zéro, la taille de la file d'attente est infinie. Si c'est un entier supérieur à @code{0}, alors @code{await put()} se bloque lorsque la file d'attente atteint `maxsize' jusqu'à ce qu'un élément soit supprimé par @ref{3275,,get()}.

Contrairement à la bibliothèque standard multi-fils @ref{b5,,queue}, la taille de la file d'attente est toujours connue et peut être renvoyée en appelant la méthode @ref{3276,,qsize()}.


Modifié dans la version 3.10: suppression du paramètre `loop'.


Cette classe n'est @ref{3202,,pas compatible avec les fils d'exécution multiples}.

@geindex maxsize (attribut asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue maxsize}@anchor{3277}
@deffn {Attribut} maxsize

Nombre d'éléments autorisés dans la file d'attente.
@end deffn

@geindex empty() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue empty}@anchor{3278}
@deffn {Méthode} empty ()

Renvoie @code{True} si la file d'attente est vide, @code{False} sinon.
@end deffn

@geindex full() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue full}@anchor{3279}
@deffn {Méthode} full ()

Renvoie @code{True} s'il y a @ref{3277,,maxsize} éléments dans la file d'attente.

If the queue was initialized with @code{maxsize=0} (the default),
then @ref{3279,,full()} never returns @code{True}.
@end deffn

@geindex get() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue get}@anchor{3275}
@deffn {Méthode} coroutine get ()

Supprime et renvoie un élément de la file d'attente. Si la file d'attente est vide, attend qu'un élément soit disponible.

Raises @ref{1af,,QueueShutDown} if the queue has been shut down and
is empty, or if the queue has been shut down immediately.
@end deffn

@geindex get_nowait() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue get_nowait}@anchor{327a}
@deffn {Méthode} get_nowait ()

Renvoie un élément s'il y en a un immédiatement disponible, sinon lève @ref{327b,,QueueEmpty}.
@end deffn

@geindex join() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue join}@anchor{db5}
@deffn {Méthode} coroutine join ()

Bloque jusqu'à ce que tous les éléments de la file d'attente aient été récupérés et traités.

Le nombre de tâches inachevées augmente chaque fois qu'un élément est ajouté à la file. Ce nombre diminue chaque fois qu'un fil d'exécution consommateur appelle @ref{db6,,task_done()} pour indiquer que l'élément a été extrait et que tout le travail à effectuer dessus est terminé. Lorsque le nombre de tâches non terminées devient nul, @ref{db5,,join()} débloque.
@end deffn

@geindex put() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue put}@anchor{327c}
@deffn {Méthode} coroutine put (item)

Met un élément dans la file d'attente. Si la file d'attente est pleine, attend qu'un emplacement libre soit disponible avant d'ajouter l'élément.

Raises @ref{1af,,QueueShutDown} if the queue has been shut down.
@end deffn

@geindex put_nowait() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue put_nowait}@anchor{327d}
@deffn {Méthode} put_nowait (item)

Ajoute un élément dans la file d'attente sans bloquer.

Si aucun emplacement libre n'est immédiatement disponible, lève @ref{327e,,QueueFull}.
@end deffn

@geindex qsize() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue qsize}@anchor{3276}
@deffn {Méthode} qsize ()

Renvoie le nombre d'éléments dans la file d'attente.
@end deffn

@geindex shutdown() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue shutdown}@anchor{1ae}
@deffn {Méthode} shutdown (immediate=False)

Shut down the queue, making @ref{3275,,get()} and @ref{327c,,put()}
raise @ref{1af,,QueueShutDown}.

By default, @ref{3275,,get()} on a shut down queue will only
raise once the queue is empty. Set `immediate' to true to make
@ref{3275,,get()} raise immediately instead.

All blocked callers of @ref{327c,,put()} and @ref{3275,,get()}
will be unblocked. If `immediate' is true, a task will be marked
as done for each remaining item in the queue, which may unblock
callers of @ref{db5,,join()}.


Ajouté dans la version 3.13.

@end deffn

@geindex task_done() (méthode asyncio.Queue)
@anchor{library/asyncio-queue asyncio Queue task_done}@anchor{db6}
@deffn {Méthode} task_done ()

Indique qu'une tâche précédemment mise en file d'attente est terminée.

Utilisé par les consommateurs de file d'attente. Pour chaque @ref{3275,,get()} utilisé pour récupérer une tâche, un appel ultérieur à @ref{db6,,task_done()} indique à la file d'attente que le traitement de la tâche est terminé.

Si un @ref{db5,,join()} est actuellement bloquant, on reprendra lorsque tous les éléments auront été traités (ce qui signifie qu'un appel à @ref{db6,,task_done()} a été effectué pour chaque élément qui a été @code{put()} dans la file).

@code{shutdown(immediate=True)} calls @ref{db6,,task_done()} for each
remaining item in the queue.

Lève une exception @ref{1ff,,ValueError} si elle est appelée plus de fois qu'il n'y avait d'éléments dans la file.
@end deffn
@end deffn

@node File avec priorité,Pile LIFO,File d'attente queue,Files d'attente queues
@anchor{library/asyncio-queue priority-queue}@anchor{327f}
@subsubsection File avec priorité


@geindex PriorityQueue (classe dans asyncio)
@anchor{library/asyncio-queue asyncio PriorityQueue}@anchor{3280}
@deffn {Classe} asyncio.PriorityQueue

Une variante de @ref{a64,,Queue} ; récupère les entrées par ordre de priorité (la plus basse en premier).

Les entrées sont généralement des `n'-uplets de la forme @code{(priority_number, data)}.
@end deffn

@node Pile LIFO,Exceptions<12>,File avec priorité,Files d'attente queues
@anchor{library/asyncio-queue lifo-queue}@anchor{3281}
@subsubsection Pile (LIFO)


@geindex LifoQueue (classe dans asyncio)
@anchor{library/asyncio-queue asyncio LifoQueue}@anchor{3282}
@deffn {Classe} asyncio.LifoQueue

Une variante de @ref{a64,,Queue} qui récupère en premier les entrées les plus récemment ajoutées (dernier entré, premier sorti).
@end deffn

@node Exceptions<12>,Exemples<17>,Pile LIFO,Files d'attente queues
@anchor{library/asyncio-queue exceptions}@anchor{3283}
@subsubsection Exceptions


@geindex QueueEmpty
@anchor{library/asyncio-queue asyncio QueueEmpty}@anchor{327b}
@deffn {Exception} asyncio.QueueEmpty

Cette exception est levée  lorsque la méthode @ref{327a,,get_nowait()} est appelée sur une file d'attente vide.
@end deffn

@geindex QueueFull
@anchor{library/asyncio-queue asyncio QueueFull}@anchor{327e}
@deffn {Exception} asyncio.QueueFull

Exception levée lorsque la méthode @ref{327d,,put_nowait()} est appelée sur une file d'attente qui a atteint sa `maxsize'.
@end deffn

@geindex QueueShutDown
@anchor{library/asyncio-queue asyncio QueueShutDown}@anchor{1af}
@deffn {Exception} asyncio.QueueShutDown

Exception raised when @ref{327c,,put()} or @ref{3275,,get()} is
called on a queue which has been shut down.


Ajouté dans la version 3.13.

@end deffn

@node Exemples<17>,,Exceptions<12>,Files d'attente queues
@anchor{library/asyncio-queue examples}@anchor{3273}
@subsubsection Exemples

@anchor{library/asyncio-queue asyncio-example-queue-dist}@anchor{3284}
Les files d'attente peuvent être utilisées pour répartir la charge de travail entre plusieurs tâches simultanées :

@example
import asyncio
import random
import time


async def worker(name, queue):
    while True:
        # Get a "work item" out of the queue.
        sleep_for = await queue.get()

        # Sleep for the "sleep_for" seconds.
        await asyncio.sleep(sleep_for)

        # Notify the queue that the "work item" has been processed.
        queue.task_done()

        print(f'@{name@} has slept for @{sleep_for:.2f@} seconds')


async def main():
    # Create a queue that we will use to store our "workload".
    queue = asyncio.Queue()

    # Generate random timings and put them into the queue.
    total_sleep_time = 0
    for _ in range(20):
        sleep_for = random.uniform(0.05, 1.0)
        total_sleep_time += sleep_for
        queue.put_nowait(sleep_for)

    # Create three worker tasks to process the queue concurrently.
    tasks = []
    for i in range(3):
        task = asyncio.create_task(worker(f'worker-@{i@}', queue))
        tasks.append(task)

    # Wait until the queue is fully processed.
    started_at = time.monotonic()
    await queue.join()
    total_slept_for = time.monotonic() - started_at

    # Cancel our worker tasks.
    for task in tasks:
        task.cancel()
    # Wait until all worker tasks are cancelled.
    await asyncio.gather(*tasks, return_exceptions=True)

    print('====')
    print(f'3 workers slept in parallel for @{total_slept_for:.2f@} seconds')
    print(f'total expected sleep time: @{total_sleep_time:.2f@} seconds')


asyncio.run(main())
@end example

@node Exceptions<13>,Boucle d'évènements,Files d'attente queues,asyncio --- Asynchronous I/O
@anchor{library/asyncio-exceptions doc}@anchor{3285}@anchor{library/asyncio-exceptions asyncio-exceptions}@anchor{3286}@anchor{library/asyncio-exceptions exceptions}@anchor{3287}
@subsubsection Exceptions


`Code source :' Lib/asyncio/exceptions.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/exceptions.py}


__________________________________________________________________


@geindex TimeoutError
@anchor{library/asyncio-exceptions asyncio TimeoutError}@anchor{16ce}
@deffn {Exception} asyncio.TimeoutError

Alias obsolète de @ref{81f,,TimeoutError}, levée lorsque l'opération a dépassé le délai donné.


Modifié dans la version 3.11: cette classe est devenue un alias de @ref{81f,,TimeoutError}.

@end deffn

@geindex CancelledError
@anchor{library/asyncio-exceptions asyncio CancelledError}@anchor{1b6}
@deffn {Exception} asyncio.CancelledError

L'opération a été annulée.

Cette exception peut être interceptée pour effectuer des opérations personnalisées lorsque des tâches asynchrones sont annulées. Dans presque toutes les situations, l'exception doit être relancée.


Modifié dans la version 3.8: @ref{1b6,,CancelledError} is now a subclass of @ref{5a5,,BaseException} rather than @ref{9c7,,Exception}.

@end deffn

@geindex InvalidStateError
@anchor{library/asyncio-exceptions asyncio InvalidStateError}@anchor{320a}
@deffn {Exception} asyncio.InvalidStateError

État interne non valide de @ref{4c2,,Task} ou @ref{bbb,,Future}.

Peut être levée dans des situations telles que la définition d'une valeur de résultat pour un objet `Future' qui a déjà une valeur de résultat définie.
@end deffn

@geindex SendfileNotAvailableError
@anchor{library/asyncio-exceptions asyncio SendfileNotAvailableError}@anchor{3288}
@deffn {Exception} asyncio.SendfileNotAvailableError

L'appel système `sendfile' n'est pas disponible pour le connecteur ou le type de fichier donné.

Sous-classe de @ref{193,,RuntimeError}.
@end deffn

@geindex IncompleteReadError
@anchor{library/asyncio-exceptions asyncio IncompleteReadError}@anchor{18ad}
@deffn {Exception} asyncio.IncompleteReadError

L'opération de lecture demandée s'est terminée avant d'être complète.

Levée par les API de @ref{31d4,,flux asyncio}.

Cette exception est une sous-classe de @ref{12b7,,EOFError}.

@geindex expected (attribut asyncio.IncompleteReadError)
@anchor{library/asyncio-exceptions asyncio IncompleteReadError expected}@anchor{3289}
@deffn {Attribut} expected

Nombre total (@ref{254,,int}) d'octets attendus.
@end deffn

@geindex partial (attribut asyncio.IncompleteReadError)
@anchor{library/asyncio-exceptions asyncio IncompleteReadError partial}@anchor{321e}
@deffn {Attribut} partial

Chaîne de @ref{1bd,,bytes} lue avant que la fin du flux ne soit atteinte.
@end deffn
@end deffn

@geindex LimitOverrunError
@anchor{library/asyncio-exceptions asyncio LimitOverrunError}@anchor{321f}
@deffn {Exception} asyncio.LimitOverrunError

La limite de taille de tampon a été atteinte lors de la recherche d'un séparateur.

Levée par les API @ref{31d4,,flux asyncio}.

@geindex consumed (attribut asyncio.LimitOverrunError)
@anchor{library/asyncio-exceptions asyncio LimitOverrunError consumed}@anchor{328a}
@deffn {Attribut} consumed

Nombre total d'octets à consommer.
@end deffn
@end deffn

@node Boucle d'évènements,Futures,Exceptions<13>,asyncio --- Asynchronous I/O
@anchor{library/asyncio-eventloop doc}@anchor{328b}@anchor{library/asyncio-eventloop asyncio-event-loop}@anchor{d66}@anchor{library/asyncio-eventloop event-loop}@anchor{328c}
@subsubsection Boucle d'évènements


`Code source :' Lib/asyncio/events.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/events.py}, Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/base_events.py}


__________________________________________________________________


@subsubheading Préface


La boucle d'événements est au cœur de chaque application `asyncio'. Les boucles d'événements exécutent des tâches et des rappels asynchrones, effectuent des opérations d'entrée-sorite réseau et exécutent des sous-processus.

Les développeurs d'applications doivent généralement utiliser les fonctions `asyncio' de haut niveau, telles que @ref{466,,asyncio.run()}, et ne doivent que rarement référencer l'objet boucle ou appeler ses méthodes. Cette section est principalement destinée aux auteurs de code, de bibliothèques et de cadriciels de bas niveau, qui ont besoin d'un contrôle plus précis sur le comportement de la boucle d'événements.

@subsubheading Obtention d'une boucle d'évènements


Les fonctions de bas niveau suivantes peuvent être utilisées pour obtenir, définir ou créer une boucle d'événements :

@geindex get_running_loop() (dans le module asyncio)
@anchor{library/asyncio-eventloop asyncio get_running_loop}@anchor{af9}
@deffn {Fonction} asyncio.get_running_loop ()

Renvoie la boucle d'événements en cours d'exécution dans le fil actuel du système d'exploitation.

Lève une @ref{193,,RuntimeError} s'il n'y a pas de boucle d'événements en cours d'exécution.

Cette fonction ne peut être appelée qu'à partir d'une coroutine ou d'une fonction de rappel.


Ajouté dans la version 3.7.

@end deffn

@geindex get_event_loop() (dans le module asyncio)
@anchor{library/asyncio-eventloop asyncio get_event_loop}@anchor{2bf}
@deffn {Fonction} asyncio.get_event_loop ()

Arrête l'exécution de la boucle d'évènements.

Lorsqu'elle est appelée depuis une coroutine ou une fonction de rappel (par exemple planifiée avec `call_soon' ou une API similaire), cette fonction renvoie toujours la boucle d'événement en cours.

S'il n'y a pas de boucle d'événement en cours d'exécution, la fonction renvoie le résultat de l'appel @code{get_event_loop_policy().get_event_loop()}.

Étant donné que cette fonction a un comportement plutôt complexe (en particulier lorsque des politiques de boucle d'événements personnalisées sont utilisées), l'utilisation de la fonction @ref{af9,,get_running_loop()} est préférable à @ref{2bf,,get_event_loop()} dans les coroutines et les fonctions de rappel.

Comme indiqué ci-dessus, envisagez d'utiliser la fonction de haut niveau @ref{466,,asyncio.run()}, au lieu d'utiliser ces fonctions de bas niveau pour créer et fermer manuellement une boucle d'événements.


Obsolète depuis la version 3.12: Deprecation warning is emitted if there is no current event loop.
In some future Python release this will become an error.

@end deffn

@geindex set_event_loop() (dans le module asyncio)
@anchor{library/asyncio-eventloop asyncio set_event_loop}@anchor{1758}
@deffn {Fonction} asyncio.set_event_loop (loop)

Définit `loop' comme boucle d'événements actuelle pour le fil d'exécution actuel du système d'exploitation.
@end deffn

@geindex new_event_loop() (dans le module asyncio)
@anchor{library/asyncio-eventloop asyncio new_event_loop}@anchor{31e1}
@deffn {Fonction} asyncio.new_event_loop ()

Crée et renvoie un nouvel objet de boucle d'événements.
@end deffn

Notez que le comportement des fonctions @ref{2bf,,get_event_loop()}, @ref{1758,,set_event_loop()} et @ref{31e1,,new_event_loop()} peut être modifié en @ref{328d,,définissant une politique de boucle d'événement personnalisée}.

@subsubheading Sommaire


Cette page de documentation contient les sections suivantes :


@itemize *

@item 
la section @ref{328e,,Event Loop Methods} est la documentation de référence des API de boucle d'événements ;

@item 
la section @ref{328f,,Callback Handles} documente les instances @ref{1a31,,Handle} et @ref{16fb,,TimerHandle} qui sont renvoyées par les méthodes de planification telles que @ref{af2,,loop.call_soon()} et @ref{af4,,loop.call_later()} ;

@item 
la section @ref{3290,,Server Objects} documente les types renvoyés par les méthodes de boucle d'événements comme @ref{b01,,loop.create_server()} ;

@item 
la section @ref{3291,,Event Loop Implementations} documente les classes @ref{5f3,,SelectorEventLoop} et @ref{5f4,,ProactorEventLoop} ;

@item 
la section @ref{3292,,Exemples} montre comment travailler avec certaines API de boucle d'événements.
@end itemize

@menu
* Méthodes de la boucle d'évènements:: 
* Fonctions de rappel sur des descripteurs:: 
* Objets Serveur:: 
* Implémentations de boucle d'évènements:: 
* Exemples: Exemples<18>. 

@end menu

@node Méthodes de la boucle d'évènements,Fonctions de rappel sur des descripteurs,,Boucle d'évènements
@anchor{library/asyncio-eventloop asyncio-event-loop-methods}@anchor{3293}@anchor{library/asyncio-eventloop event-loop-methods}@anchor{328e}
@subsubsection Méthodes de la boucle d'évènements


Les boucles d'événements ont des API `de bas niveau' pour les éléments suivants :

@menu
* Démarrer et arrêter une boucle d'évènements:: 
* Planification des fonctions de rappel:: 
* Planification des rappels différés:: 
* Création de Futures et des tâches:: 
* Création de connexions:: 
* Création de serveurs:: 
* Transfert de fichiers:: 
* Passage du flux en TLS:: 
* Surveillance de descripteur de fichier:: 
* Travail direct avec des objets socket:: 
* DNS:: 
* Travail avec des tubes (pipes): Travail avec des tubes pipes. 
* Signaux Unix:: 
* Exécution de code dans des pools de threads ou de processus:: 
* API de gestion d'erreur:: 
* Activation du mode débogage:: 
* Exécution de sous-processus:: 

@end menu

@node Démarrer et arrêter une boucle d'évènements,Planification des fonctions de rappel,,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop running-and-stopping-the-loop}@anchor{3294}
@subsubsection Démarrer et arrêter une boucle d'évènements


@geindex run_until_complete() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop run_until_complete}@anchor{c65}
@deffn {Méthode} loop.run_until_complete (future)

Lance la boucle jusqu'à ce que `future' (une instance de @ref{bbb,,Future}) soit terminée.

Si l'argument est un objet @ref{31d3,,coroutine}, il est implicitement programmé pour s'exécuter en tant que @ref{4c2,,asyncio.Task}.

Renvoie le résultat du `Future' ou lève son exception.
@end deffn

@geindex run_forever() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop run_forever}@anchor{3295}
@deffn {Méthode} loop.run_forever ()

Exécute la boucle d'événement jusqu'à ce que @ref{c6a,,stop()} soit appelée.

If @ref{c6a,,stop()} is called before @ref{3295,,run_forever()} is called,
the loop will poll the I/O selector once with a timeout of zero,
run all callbacks scheduled in response to I/O events (and
those that were already scheduled), and then exit.

Si @ref{c6a,,stop()} est appelée pendant que @ref{3295,,run_forever()} est en cours d'exécution, la boucle exécute le lot actuel de rappels puis se termine. Notez que les nouveaux rappels programmés par fonctions de rappel ne s'exécuteront pas dans ce cas ; à la place, ils s'exécuteront la prochaine fois que @ref{3295,,run_forever()} ou @ref{c65,,run_until_complete()} sera appelée.
@end deffn

@geindex stop() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop stop}@anchor{c6a}
@deffn {Méthode} loop.stop ()

Arrête l'exécution de la boucle d'évènements.
@end deffn

@geindex is_running() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop is_running}@anchor{3296}
@deffn {Méthode} loop.is_running ()

Renvoie @code{True} si la boucle d'évènements est démarrée.
@end deffn

@geindex is_closed() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop is_closed}@anchor{db1}
@deffn {Méthode} loop.is_closed ()

Renvoie @code{True} si la boucle d'évènements est arrêtée.
@end deffn

@geindex close() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop close}@anchor{3297}
@deffn {Méthode} loop.close ()

Arrête la boucle d'évènements.

La boucle ne doit pas être en cours d'exécution lorsque cette fonction est appelée. Tous les rappels en attente seront ignorés.

Cette méthode efface toutes les files d'attente et arrête l'exécuteur, mais n'attend pas que l'exécuteur se termine.

Cette méthode est idempotente et irréversible. Aucune autre méthode ne doit être appelée après la fermeture de la boucle d'événements.
@end deffn

@geindex shutdown_asyncgens() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop shutdown_asyncgens}@anchor{c6b}
@deffn {Méthode} coroutine loop.shutdown_asyncgens ()

Schedule all currently open @ref{1fba,,asynchronous generator} objects to
close with an @ref{8c5,,aclose()} call.  After calling this method,
the event loop will issue a warning if a new asynchronous generator
is iterated. This should be used to reliably finalize all scheduled
asynchronous generators.

Notez qu'il n'est pas nécessaire d'appeler cette fonction lorsque @ref{466,,asyncio.run()} est utilisée.

Exemple :

@example
try:
    loop.run_forever()
finally:
    loop.run_until_complete(loop.shutdown_asyncgens())
    loop.close()
@end example


Ajouté dans la version 3.6.

@end deffn

@geindex shutdown_default_executor() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop shutdown_default_executor}@anchor{8d4}
@deffn {Méthode} coroutine loop.shutdown_default_executor (timeout=None)

Planifie la fermeture de l'exécuteur par défaut et attend que tous les fils se rejoignent dans le @ref{72c,,ThreadPoolExecutor}. Une fois cette méthode appelée, l'utilisation de l'exécuteur par défaut avec @ref{8d6,,loop.run_in_executor()} lève une @ref{193,,RuntimeError}.

The `timeout' parameter specifies the amount of time
(in @ref{2eb,,float} seconds) the executor will be given to finish joining.
With the default, @code{None},
the executor is allowed an unlimited amount of time.

If the `timeout' is reached, a @ref{1bb,,RuntimeWarning} is emitted
and the default executor is terminated
without waiting for its threads to finish joining.

@cartouche
@quotation Note 
n'appelez pas cette méthode lorsque vous utilisez @ref{466,,asyncio.run()}, car cette dernière gère automatiquement l'arrêt de l'exécuteur par défaut.
@end quotation
@end cartouche


Ajouté dans la version 3.9.



Modifié dans la version 3.12: Added the `timeout' parameter.

@end deffn

@node Planification des fonctions de rappel,Planification des rappels différés,Démarrer et arrêter une boucle d'évènements,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop scheduling-callbacks}@anchor{3298}
@subsubsection Planification des fonctions de rappel


@geindex call_soon() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_soon}@anchor{af2}
@deffn {Méthode} loop.call_soon (callback, *args, context=None)

Définit la @ref{2893,,fonction de rappel} `callback' à appeler avec les arguments `args' à la prochaine itération de la boucle d'événements.

Renvoie une instance de @ref{1a31,,asyncio.Handle}, qui pourra être utilisée ultérieurement pour annuler le rappel.

Les fonctions de rappels sont appelées dans l'ordre dans lequel elles sont enregistrées. Chaque fonction de rappel sera appelée exactement une fois.

L'argument facultatif nommé uniquement `context' spécifie un @ref{152f,,contextvars.Context} personnalisé pour le `callback' à exécuter. Les rappels utilisent le contexte actuel lorsqu'aucun `context' n'est fourni.

Contrairement à @ref{af3,,call_soon_threadsafe()}, cette méthode n'est pas compatible avec les programmes à fils d'exécution multiples.
@end deffn

@geindex call_soon_threadsafe() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_soon_threadsafe}@anchor{af3}
@deffn {Méthode} loop.call_soon_threadsafe (callback, *args, context=None)

Une variante compatible avec les programmes à fils d'exécution multiples de @ref{af2,,call_soon()}. Lors de la planification de rappels à partir d'un autre fil d'exécution, cette fonction `doit' être utilisée, puisque @ref{af2,,call_soon()} n'est pas thread-safe.

Lève @ref{193,,RuntimeError} si elle est appelée sur une boucle qui a été fermée. Cela peut se produire sur un fil secondaire lorsque l'application principale se ferme.

Voir la section @ref{3202,,exécution concurrente et multi-fils d'exécution} de la documentation.


Modifié dans la version 3.7: le paramètre nommé uniquement `context' a été ajouté. Voir 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} pour plus de détails.

@end deffn
@anchor{library/asyncio-eventloop asyncio-pass-keywords}@anchor{3299}
@cartouche
@quotation Note 
la plupart des fonctions d'ordonnancement @ref{a,,asyncio} n'autorisent pas le passage d'arguments nommés. Pour le faire, utilisez @ref{40a,,functools.partial()}

@example
# will schedule "print("Hello", flush=True)"
loop.call_soon(
    functools.partial(print, "Hello", flush=True))
@end example

L'utilisation d'objets partiels est généralement plus pratique que l'utilisation de lambdas, car `asyncio' peut mieux rendre les objets partiels dans les messages de débogage et d'erreur.
@end quotation
@end cartouche

@node Planification des rappels différés,Création de Futures et des tâches,Planification des fonctions de rappel,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop asyncio-delayed-calls}@anchor{329a}@anchor{library/asyncio-eventloop scheduling-delayed-callbacks}@anchor{329b}
@subsubsection Planification des rappels différés


La boucle d'événements fournit des mécanismes pour programmer les fonctions de rappel à appeler à un moment donné dans le futur. La boucle d'événements utilise des horloges monotones pour suivre le temps.

@geindex call_later() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_later}@anchor{af4}
@deffn {Méthode} loop.call_later (delay, callback, *args, context=None)

Planifie le rappel `callback' à appeler après `delay' secondes (peut être un entier ou un flottant).

Une instance de @ref{16fb,,asyncio.TimerHandle} est renvoyée et peut être utilisée pour annuler le rappel.

`callback' sera appelé exactement une fois. Si deux rappels sont programmés exactement à la même heure, l'ordre dans lequel ils sont appelés n'est pas défini.

L'argument positionnel facultatif `args' sera transmis au rappel lorsqu'il sera appelé. Si vous voulez que le rappel soit appelé avec des arguments nommés, utilisez @ref{40a,,functools.partial()}.

Un argument facultatif `context' nommé uniquement permet de spécifier un @ref{152f,,contextvars.Context} personnalisé pour le `callback' à exécuter. Le contexte actuel est utilisé lorsqu'aucun `context' n'est fourni.


Modifié dans la version 3.7: le paramètre nommé uniquement `context' a été ajouté. Voir 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} pour plus de détails.



Modifié dans la version 3.8: dans Python 3.7 et versions antérieures avec l'implémentation de la boucle d'événements par défaut, le `delay' ne pouvait pas dépasser un jour. Cela a été corrigé dans Python 3.8.

@end deffn

@geindex call_at() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_at}@anchor{af5}
@deffn {Méthode} loop.call_at (when, callback, *args, context=None)

Planifie l'appel de `callback' à l'horodatage absolu donné `when' (un `int' ou un `float'), en utilisant la même référence de temps que @ref{329c,,loop.time()}.

Le comportement de cette méthode est le même que @ref{af4,,call_later()}.

Une instance de @ref{16fb,,asyncio.TimerHandle} est renvoyée et peut être utilisée pour annuler le rappel.


Modifié dans la version 3.7: le paramètre nommé uniquement `context' a été ajouté. Voir 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} pour plus de détails.



Modifié dans la version 3.8: dans Python 3.7 et versions antérieures avec l'implémentation de la boucle d'événements par défaut, la différence entre `when' et l'heure actuelle ne pouvait pas dépasser un jour. Cela a été corrigé dans Python 3.8.

@end deffn

@geindex time() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop time}@anchor{329c}
@deffn {Méthode} loop.time ()

Renvoie l'heure actuelle, sous la forme d'une valeur @ref{2eb,,float}, selon l'horloge monotone interne de la boucle d'événements.
@end deffn

@cartouche
@quotation Note 

Modifié dans la version 3.8: dans Python 3.7 et les versions antérieures, les délais d'expiration (relatif `delay' ou absolu `when') ne doivent pas dépasser un jour. Cela a été corrigé dans Python 3.8.

@end quotation
@end cartouche


@subsubheading Voir aussi


la fonction @ref{a5d,,asyncio.sleep()}.


@node Création de Futures et des tâches,Création de connexions,Planification des rappels différés,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop creating-futures-and-tasks}@anchor{329d}
@subsubsection Création de `Futures' et des tâches


@geindex create_future() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_future}@anchor{c67}
@deffn {Méthode} loop.create_future ()

Crée un objet @ref{bbb,,asyncio.Future} attaché à la boucle d'événements.

C'est la méthode préférée pour créer des `Futures' avec `asyncio'. Cela permet aux boucles d'événements tierces de fournir des implémentations alternatives de l'objet `Future' (avec de meilleures performances ou instrumentation).


Ajouté dans la version 3.5.2.

@end deffn

@geindex create_task() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_task}@anchor{9ca}
@deffn {Méthode} loop.create_task (coro, *, name=None, context=None)

Planifie l'exécution de @ref{31d3,,coroutine} `coro'. Renvoie un objet @ref{4c2,,Task}.

Les boucles d'événements tierces peuvent utiliser leur propre sous-classe de @ref{4c2,,Task} pour l'interopérabilité. Dans ce cas, le type de résultat est une sous-classe de @ref{4c2,,Task}.

Si l'argument `name' est fourni et non @code{None}, il est défini comme le nom de la tâche en utilisant @ref{9cb,,Task.set_name()}.

Argument facultatif `context' nommé uniquement qui permet de spécifier un @ref{152f,,contextvars.Context} personnalisé pour la `coro' à exécuter. La copie de contexte actuel est créée lorsqu'aucun `context' n'est fourni.


Modifié dans la version 3.8: ajout du paramètre @code{name}.



Modifié dans la version 3.11: ajout du paramètre @code{context}.

@end deffn

@geindex set_task_factory() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_task_factory}@anchor{db3}
@deffn {Méthode} loop.set_task_factory (factory)

Définit une fabrique de tâches qui sera utilisée par @ref{9ca,,loop.create_task()}.

Si `factory' est @code{None}, la fabrique de tâches par défaut sera définie. Sinon, `factory' doit être un `appelable' avec la signature correspondant à @code{(loop, coro, context=None)}, où `loop' est une référence à la boucle d'événements active et `coro' est un objet coroutine . L'appelable doit renvoyer un objet compatible avec @ref{bbb,,asyncio.Future}.
@end deffn

@geindex get_task_factory() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop get_task_factory}@anchor{db4}
@deffn {Méthode} loop.get_task_factory ()

Renvoie une fabrique de tâches ou @code{None} si celle par défaut est utilisée.
@end deffn

@node Création de connexions,Création de serveurs,Création de Futures et des tâches,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop opening-network-connections}@anchor{329e}
@subsubsection Création de connexions


@geindex create_connection() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_connection}@anchor{5ee}
@deffn {Méthode} coroutine loop.create_connection (protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None, all_errors=False)

Ouvre un flux de transport connecté à l'adresse spécifiée par `host' et `port'.

The socket family can be either @ref{17ab,,AF_INET} or
@ref{17ac,,AF_INET6} depending on `host' (or the `family'
argument, if provided).

The socket type will be @ref{12d1,,SOCK_STREAM}.

`protocol_factory' doit être un appelable renvoyant un protocole gérant le @ref{329f,,protocole asyncio}.

Cette méthode tente d'établir la connexion en arrière-plan. En cas de succès, elle renvoie une paire @code{(transport, protocol)}.

Le synopsis chronologique de l'opération sous-jacente est le suivant :


@enumerate 

@item 
La connexion est établie et un @ref{32a0,,transport asyncio} est créé pour cela.

@item 
`protocol_factory' est appelée sans arguments et doit renvoyer une instance de @ref{329f,,protocol asyncio}.

@item 
L'instance de protocole est couplée au transport en appelant sa méthode @ref{32a1,,connection_made()}.

@item 
Un `n'-uplet @code{(transport, protocol)} est renvoyé en cas de succès.
@end enumerate

Le transport créé est un flux bidirectionnel dépendant de l'implémentation.

Autres arguments :


@itemize *

@item 
`ssl' : s'il est donné et non faux, un transport SSL/TLS est créé (par défaut un transport TCP simple est créé). Si `ssl' est un objet @ref{291,,ssl.SSLContext}, ce contexte est utilisé pour créer le transport ; si `ssl' est @ref{bfb,,True}, un contexte par défaut renvoyé par @ref{154,,ssl.create_default_context()} est utilisé.


@subsubheading Voir aussi


@ref{32a2,,Considérations sur la sécurité SSL/TLS}


@item 
`server_hostname' définit ou remplace le nom d'hôte auquel le certificat du serveur cible sera comparé. Ne doit être passé que si `ssl' n'est pas @code{None}. Par défaut, la valeur de l'argument `host' est utilisée. Si `host' est vide, il n'y a pas de valeur par défaut et vous devez transmettre une valeur pour `server_hostname'. Si `server_hostname' est une chaîne vide, la correspondance du nom d'hôte est désactivée (ce qui constitue un risque de sécurité sérieux, permettant des attaques potentielles de type « homme du milieu »).

@item 
`family', `proto', `flags' sont facultatifs et sont la famille d'adresse, le protocole et les drapeaux à transmettre à `getaddrinfo()' pour la résolution de `host'. S'ils sont fournis, ils doivent tous être des entiers provenant des constantes du module @ref{cb,,socket}.

@item 
`happy_eyeballs_delay', s'il est fourni, active Happy Eyeballs pour cette connexion. Il doit s'agir d'un nombre à virgule flottante représentant le temps d'attente en secondes pour qu'une tentative de connexion se termine, avant de démarrer la prochaine tentative en parallèle. Il s'agit du « délai de tentative de connexion » tel que défini dans la 
@geindex RFC; RFC 8305
RFC 8305@footnote{https://datatracker.ietf.org/doc/html/rfc8305.html}. Une valeur par défaut raisonnable recommandée par la RFC est @code{0.25} (250 millisecondes).

@item 
`interleave' contrôle la réorganisation des adresses lorsqu'un nom d'hôte se résout en plusieurs adresses IP. S'il vaut @code{0} ou n'est pas spécifié, aucune réorganisation n'est effectuée et les adresses sont essayées dans l'ordre renvoyé par @ref{c02,,getaddrinfo()}. Si un entier positif est spécifié, les adresses sont entrelacées par famille d'adresses et l'entier donné est interprété comme "First Address Family Count" tel que défini dans la 
@geindex RFC; RFC 8305
RFC 8305@footnote{https://datatracker.ietf.org/doc/html/rfc8305.html}. La valeur par défaut est @code{0} si `happy_eyeballs_delay' n'est pas spécifié, et @code{1} si c'est le cas.

@item 
`sock', s'il est fourni, doit être un objet @ref{d8e,,socket.socket} existant et déjà connecté à utiliser par le transport. Si `sock' est donné, aucun des `host', `port', `family', `proto', `flags', `happy_eyeballs_delay', `interleave' et `local_addr' ne doit être spécifié.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur au transport créé. Pour fermer le connecteur, appelez la méthode @ref{32a3,,close()} du transport.
@end quotation
@end cartouche

@item 
`local_addr', s'il est fourni, est un `n'-uplet @code{(local_host, local_port)} utilisé pour lier le connecteur localement. `local_host' et `local_port' sont recherchés en utilisant @code{getaddrinfo()}, de la même manière que `host' et `port'.

@item 
`ssl_handshake_timeout' est (pour une connexion TLS) le temps en secondes à attendre que la poignée de main TLS se termine avant d'abandonner la connexion. @code{60.0} secondes si @code{None} (par défaut).

@item 
`ssl_shutdown_timeout' est le temps en secondes à attendre que l'arrêt SSL se termine avant d'abandonner la connexion. @code{30.0} secondes si @code{None} (par défaut).

@item 
`all_errors' determines what exceptions are raised when a connection cannot
be created. By default, only a single @code{Exception} is raised: the first
exception if there is only one or all errors have same message, or a single
@code{OSError} with the error messages combined. When @code{all_errors} is @code{True},
an @code{ExceptionGroup} will be raised containing all exceptions (even if there
is only one).
@end itemize


Modifié dans la version 3.5: ajout de la prise en charge de SSL/TLS dans @ref{5f4,,ProactorEventLoop}.



Modifié dans la version 3.6: The socket option @ref{32a4,,socket.TCP_NODELAY} is set by default
for all TCP connections.



Modifié dans la version 3.7: ajout du paramètre `ssl handshake timeout'



Modifié dans la version 3.8: ajout des paramètres `happy_eyeballs_delay' et `interleave'.

Algorithme Happy Eyeballs : « succès avec les hôtes à double pile ». Lorsque le chemin et le protocole IPv4 d'un serveur fonctionnent, mais que le chemin et le protocole IPv6 du serveur ne fonctionnent pas, une application cliente à double pile subit un retard de connexion important par rapport à un client IPv4 uniquement. Ceci n'est pas souhaitable car cela entraîne une moins bonne expérience utilisateur pour le client à double pile. Ce document spécifie les exigences pour les algorithmes qui réduisent ce délai visible par l'utilisateur et fournit un algorithme correspondant.

For more information: @indicateurl{https://datatracker.ietf.org/doc/html/rfc6555}



Modifié dans la version 3.11: ajout du paramètre `ssl shutdown timeout'



Modifié dans la version 3.12: `all_errors' was added.



@subsubheading Voir aussi


la fonction @ref{b06,,open_connection()} est une API alternative de haut niveau. Elle renvoie une paire de (@ref{1853,,StreamReader}, @ref{1689,,StreamWriter}) qui peut être utilisée directement dans le code `async/wait'.

@end deffn

@geindex create_datagram_endpoint() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_datagram_endpoint}@anchor{71d}
@deffn {Méthode} coroutine loop.create_datagram_endpoint (protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_port=None, allow_broadcast=None, sock=None)

Création d'une connexion par datagramme

The socket family can be either @ref{17ab,,AF_INET},
@ref{17ac,,AF_INET6}, or @ref{17ad,,AF_UNIX},
depending on `host' (or the `family' argument, if provided).

The socket type will be @ref{12d0,,SOCK_DGRAM}.

`protocol_factory' doit être un appelable gérant le @ref{329f,,protocole asyncio}.

Un `n'-uplet @code{(transport, protocol)} est renvoyé en cas de succès.

Autres arguments :


@itemize *

@item 
`local_addr', s'il est fourni, est un `n'-uplet @code{(local_host, local_port)} utilisé pour lier le connecteur localement. Le `local_host' et le `local_port' sont recherchés en utilisant @ref{c02,,getaddrinfo()}.

@item 
`remote_addr', s'il est fourni, est un `n'-uplet @code{(remote_host, remote_port)} utilisé pour se connecter à une adresse distante. Le `remote_host' et le `remote_port' sont recherchés en utilisant @ref{c02,,getaddrinfo()}.

@item 
`family', `proto', `flags' sont facultatifs et représentent la famille d'adresse, le protocole et les drapeaux à transmettre à @ref{c02,,getaddrinfo()} pour la résolution `host'. S'ils sont fournis, ils doivent tous être des entiers provenant des constantes du module @ref{cb,,socket}.

@item 
`reuse_port' tells the kernel to allow this endpoint to be bound to the
same port as other existing endpoints are bound to, so long as they all
set this flag when being created. This option is not supported on Windows
and some Unixes. If the @ref{32a4,,socket.SO_REUSEPORT} constant is not
defined then this capability is unsupported.

@item 
`allow_broadcast' indique au noyau d'autoriser ce point de terminaison à envoyer des messages à l'adresse de `broadcast'.

@item 
`sock' peut éventuellement être spécifié afin d'utiliser un objet @ref{d8e,,socket.socket} préexistant, déjà connecté, à utiliser par le transport. Si spécifié, `local_addr' et `remote_addr' doivent être omis (doit être @ref{660,,None}).

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur au transport créé. Pour fermer le connecteur, appelez la méthode @ref{32a3,,close()} du transport.
@end quotation
@end cartouche
@end itemize

Voir les exemples @ref{32a5,,Client écho en UDP} et @ref{32a6,,Serveur écho en UDP}.


Modifié dans la version 3.4.4: les paramètres `family', `proto', `flags', `reuse_address', `reuse_port', `allow_broadcast' et `sock' ont été ajoutés.



Modifié dans la version 3.8: prise en charge sur Windows.



Modifié dans la version 3.8.1: The `reuse_address' parameter is no longer supported, as using
@ref{32a4,,socket.SO_REUSEADDR}
poses a significant security concern for
UDP. Explicitly passing @code{reuse_address=True} will raise an exception.

Lorsque plusieurs processus avec des UID différents attribuent des connecteurs à une adresse de connecteur UDP identique avec @code{SO_REUSEADDR}, les paquets entrants peuvent être distribués de manière aléatoire entre les connecteurs.

For supported platforms, `reuse_port' can be used as a replacement for
similar functionality. With `reuse_port',
@ref{32a4,,socket.SO_REUSEPORT}
is used instead, which specifically
prevents processes with differing UIDs from assigning sockets to the same
socket address.



Modifié dans la version 3.11: The `reuse_address' parameter, disabled since Python 3.8.1,
3.7.6 and 3.6.10, has been entirely removed.

@end deffn

@geindex create_unix_connection() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_unix_connection}@anchor{3218}
@deffn {Méthode} coroutine loop.create_unix_connection (protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Crée une connexion Unix

The socket family will be @ref{17ad,,AF_UNIX}; socket
type will be @ref{12d1,,SOCK_STREAM}.

Un `n'-uplet @code{(transport, protocol)} est renvoyé en cas de succès.

`path' est le nom d'un connecteur de domaine Unix et est obligatoire, sauf si un paramètre `sock' est spécifié. Les connecteurs Unix abstraits, les chemins @ref{435,,str}, @ref{1bd,,bytes} et @ref{226,,Path} sont pris en charge.

Voir la documentation de la méthode @ref{5ee,,loop.create_connection()} pour plus d'informations sur les arguments de cette méthode.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.7: ajout du paramètre `ssl_handshake_timeout'. Le paramètre `chemin' peut désormais être un @ref{29d,,objet simili-chemin}.



Modifié dans la version 3.11: ajout du paramètre `ssl shutdown timeout'

@end deffn

@node Création de serveurs,Transfert de fichiers,Création de connexions,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop creating-network-servers}@anchor{32a7}
@subsubsection Création de serveurs


@geindex create_server() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop loop-create-server}@anchor{31d8}@anchor{library/asyncio-eventloop asyncio loop create_server}@anchor{b01}
@deffn {Méthode} coroutine loop.create_server (protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, keep_alive=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

Create a TCP server (socket type @ref{12d1,,SOCK_STREAM}) listening
on `port' of the `host' address.

Renvoie un objet @ref{b00,,Server}.

Arguments :


@itemize *

@item 
`protocol_factory' doit être un appelable gérant le @ref{329f,,protocole asyncio}.

@item 
Le paramètre `host' peut être défini sur plusieurs types qui déterminent où le serveur écoute :


@itemize -

@item 
Si `host' est une chaîne, le serveur TCP est lié à une seule interface réseau spécifiée par `host'.

@item 
Si `host' est une séquence de chaînes, le serveur TCP est lié à toutes les interfaces réseau spécifiées par la séquence.

@item 
Si `host' est une chaîne vide ou @code{None}, toutes les interfaces sont prises en compte et une liste de plusieurs connecteurs est renvoyée (probablement une pour IPv4 et une autre pour IPv6).
@end itemize

@item 
Le paramètre `port' peut être défini pour spécifier sur quel port le serveur doit écouter. Si @code{0} ou @code{None} (la valeur par défaut), un port inutilisé aléatoire est sélectionné (notez que si `host' se résout en plusieurs interfaces réseau, un port aléatoire différent est sélectionné pour chaque interface).

@item 
`family' can be set to either @ref{17ab,,socket.AF_INET} or
@ref{17ac,,AF_INET6} to force the socket to use IPv4 or IPv6.
If not set, the `family' will be determined from host name
(defaults to @ref{32a8,,AF_UNSPEC}).

@item 
`flags' est un masque de bits pour @ref{c02,,getaddrinfo()}.

@item 
`sock' peut éventuellement être spécifié afin d'utiliser un objet connecteur préexistant. S'il est spécifié, `host' et `port' ne doivent pas être spécifiés.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur au serveur créé. Pour fermer le connecteur, appelez la méthode @ref{3216,,close()} du serveur.
@end quotation
@end cartouche

@item 
`backlog' est le nombre maximum de connexions en file d'attente passées à @ref{e47,,listen()} (par défaut à 100).

@item 
`ssl' peut être défini sur une instance @ref{291,,SSLContext} pour activer TLS sur les connexions acceptées.

@item 
`reuse_address' indique au noyau de réutiliser un connecteur local dans l'état @code{TIME_WAIT}, sans attendre l'expiration de son délai d'attente naturel. S'il n'est pas spécifié, il est automatiquement défini sur @code{True} sous Unix.

@item 
`reuse_port' indique au noyau d'autoriser ce point de terminaison à être lié au même port que les autres points de terminaison existants, tant qu'ils définissent tous cet indicateur lors de leur création. Cette option n'est pas prise en charge sous Windows.

@item 
`keep_alive' set to @code{True} keeps connections active by enabling the
periodic transmission of messages.
@end itemize


Modifié dans la version 3.13: Added the `keep_alive' parameter.



@itemize *

@item 
`ssl_handshake_timeout' est (pour un serveur TLS) le temps en secondes à attendre que la poignée de main TLS se termine avant d'abandonner la connexion. @code{60.0} secondes si @code{None} (par défaut).

@item 
`ssl_shutdown_timeout' est le temps en secondes à attendre que l'arrêt SSL se termine avant d'abandonner la connexion. @code{30.0} secondes si @code{None} (par défaut).

@item 
`start_serving' défini à @code{True} (valeur par défaut) fait que le serveur créé commence immédiatement à accepter les connexions. Lorsqu'il est défini sur @code{False}, l'utilisateur doit attendre sur @ref{b02,,Server.start_serving()} ou @ref{b03,,Server.serve_forever()} pour que le serveur commence à accepter les connexions.
@end itemize


Modifié dans la version 3.5: ajout de la prise en charge de SSL/TLS dans @ref{5f4,,ProactorEventLoop}.



Modifié dans la version 3.5.1: le paramètre `host' peut être une séquence de chaînes.



Modifié dans la version 3.6: Added `ssl_handshake_timeout' and `start_serving' parameters.
The socket option @ref{32a4,,socket.TCP_NODELAY} is set by default
for all TCP connections.



Modifié dans la version 3.11: ajout du paramètre `ssl shutdown timeout'



@subsubheading Voir aussi


la fonction @ref{b07,,start_server()} est une API alternative de niveau supérieur qui renvoie une paire de @ref{1853,,StreamReader} et @ref{1689,,StreamWriter} qui peut être utilisée dans un code `async/wait'.

@end deffn

@geindex create_unix_server() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop create_unix_server}@anchor{1ac}
@deffn {Méthode} coroutine loop.create_unix_server (protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True, cleanup_socket=True)

Similar to @ref{b01,,loop.create_server()} but works with the
@ref{17ad,,AF_UNIX} socket family.

`path' est le nom d'un connecteur de domaine Unix et est obligatoire, sauf si un argument `sock' est fourni. Les connecteurs Unix abstraits, les chemins @ref{435,,str}, @ref{1bd,,bytes} et @ref{226,,Path} sont pris en charge.

If `cleanup_socket' is true then the Unix socket will automatically
be removed from the filesystem when the server is closed, unless the
socket has been replaced after the server has been created.

Voir la documentation de la méthode @ref{b01,,loop.create_server()} pour plus d'informations sur les arguments de cette méthode.

@ref{1ce0,,Availability}: Unix.


Modifié dans la version 3.7: ajout des paramètres `ssl_handshake_timeout' et `start_serving'. Le paramètre `path' peut maintenant être un objet @ref{226,,Path}.



Modifié dans la version 3.11: ajout du paramètre `ssl shutdown timeout'



Modifié dans la version 3.13: Added the `cleanup_socket' parameter.

@end deffn

@geindex connect_accepted_socket() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop connect_accepted_socket}@anchor{b08}
@deffn {Méthode} coroutine loop.connect_accepted_socket (protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Enveloppe une connexion déjà acceptée dans une paire transport/protocole.

Cette méthode peut être utilisée par les serveurs qui acceptent les connexions en dehors d'`asyncio' mais qui utilisent `asyncio' pour les gérer.

Paramètres :


@itemize *

@item 
`protocol_factory' doit être un appelable gérant le @ref{329f,,protocole asyncio}.

@item 
`sock' est un objet connecteur préexistant renvoyé par @ref{d8f,,socket.accept}.

@cartouche
@quotation Note 
l'argument `sock' transfère la propriété du connecteur au transport créé. Pour fermer le connecteur, appelez la méthode @ref{32a3,,close()} du transport.
@end quotation
@end cartouche

@item 
`ssl' peut être défini sur une @ref{291,,SSLContext} pour activer SSL sur les connexions acceptées.

@item 
`ssl_handshake_timeout' est (pour une connexion SSL) le temps en secondes à attendre que la poignée de main SSL se termine avant d'abandonner la connexion. @code{60.0} secondes si @code{None} (par défaut).

@item 
`ssl_shutdown_timeout' est le temps en secondes à attendre que l'arrêt SSL se termine avant d'abandonner la connexion. @code{30.0} secondes si @code{None} (par défaut).
@end itemize

Renvoie une paire @code{(transport, protocole)}.


Ajouté dans la version 3.5.3.



Modifié dans la version 3.7: ajout du paramètre `ssl handshake timeout'



Modifié dans la version 3.11: ajout du paramètre `ssl shutdown timeout'

@end deffn

@node Transfert de fichiers,Passage du flux en TLS,Création de serveurs,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop transferring-files}@anchor{32a9}
@subsubsection Transfert de fichiers


@geindex sendfile() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sendfile}@anchor{32aa}
@deffn {Méthode} coroutine loop.sendfile (transport, file, offset=0, count=None, *, fallback=True)

Envoie `file' via `transport'. Renvoie le nombre total d'octets envoyés.

La méthode utilise @ref{afd,,os.sendfile()} (hautes performances) si elle est disponible.

`file' doit être un objet fichier normal ouvert en mode binaire.

`offset' indique où commencer la lecture du fichier. Si spécifié, `count' est le nombre total d'octets à transmettre, par opposition à l'envoi du fichier jusqu'à ce que EOF soit atteint. La position du fichier est toujours mise à jour, même lorsque cette méthode génère une erreur. @ref{2930,,file.tell()} peut être utilisée pour obtenir le nombre d'octets réellement envoyés.

`fallback' défini sur @code{True} permet à `asyncio' de lire et d'envoyer manuellement le fichier lorsque la plateforme ne prend pas en charge l'appel système `sendfile' (par exemple, Windows ou connecteur SSL sous Unix).

Lève @ref{3288,,SendfileNotAvailableError} si le système ne prend pas en charge l'appel système `sendfile' et que `fallback' est @code{False}.


Ajouté dans la version 3.7.

@end deffn

@node Passage du flux en TLS,Surveillance de descripteur de fichier,Transfert de fichiers,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop tls-upgrade}@anchor{32ab}
@subsubsection Passage du flux en TLS


@geindex start_tls() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop start_tls}@anchor{af7}
@deffn {Méthode} coroutine loop.start_tls (transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

Convertit une connexion existante en connexion TLS.

Crée une instance de codeur-décodeur TLS et l'insère entre le `transport' et le `protocol'. Le codeur-décodeur implémente à la fois le protocole vers le `transport' et le transport vers le `protocol'.

Renvoie l'instance à deux interfaces créée. Après `await', le `protocol' doit cesser d'utiliser le `transport' d'origine et communiquer avec l'objet renvoyé uniquement parce que le codeur met en cache les données côté `protocol' et échange sporadiquement des paquets de session TLS supplémentaires avec `transport'.

In some situations (e.g. when the passed transport is already closing) this
may return @code{None}.

Paramètres :


@itemize *

@item 
`transport' et `protocol' que des méthodes comme @ref{b01,,create_server()} et @ref{5ee,,create_connection()} renvoient.

@item 
`sslcontext' : une instance configurée de @ref{291,,SSLContext}.

@item 
`server_side' passe à @code{True} lorsqu'une connexion côté serveur est mise à jour (comme celle créée par @ref{b01,,create_server()}).

@item 
`server_hostname' : définit ou remplace le nom d'hôte auquel le certificat du serveur cible est comparé.

@item 
`ssl_handshake_timeout' est (pour une connexion TLS) le temps en secondes à attendre que la poignée de main TLS se termine avant d'abandonner la connexion. @code{60.0} secondes si @code{None} (par défaut).

@item 
`ssl_shutdown_timeout' est le temps en secondes à attendre que l'arrêt SSL se termine avant d'abandonner la connexion. @code{30.0} secondes si @code{None} (par défaut).
@end itemize


Ajouté dans la version 3.7.



Modifié dans la version 3.11: ajout du paramètre `ssl shutdown timeout'

@end deffn

@node Surveillance de descripteur de fichier,Travail direct avec des objets socket,Passage du flux en TLS,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop watching-file-descriptors}@anchor{32ac}
@subsubsection Surveillance de descripteur de fichier


@geindex add_reader() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop add_reader}@anchor{3233}
@deffn {Méthode} loop.add_reader (fd, callback, *args)

Commence à surveiller la disponibilité en lecture du descripteur de fichier `fd' et appelle `callback' avec les arguments spécifiés une fois que `fd' est disponible en lecture.
@end deffn

@geindex remove_reader() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop remove_reader}@anchor{32ad}
@deffn {Méthode} loop.remove_reader (fd)

Arrête de surveiller le descripteur de fichier `fd' pour la disponibilité en lecture. Renvoie @code{True} si `fd' était précédemment surveillé pour les lectures.
@end deffn

@geindex add_writer() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop add_writer}@anchor{32ae}
@deffn {Méthode} loop.add_writer (fd, callback, *args)

Commence à surveiller le descripteur de fichier `fd' pour la disponibilité en écriture et appelle `callback' avec les arguments spécifiés une fois que `fd' est disponible en écriture.

Utilisez @ref{40a,,functools.partial()} pour @ref{3299,,passer des arguments nommés} à `callback'.
@end deffn

@geindex remove_writer() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop remove_writer}@anchor{32af}
@deffn {Méthode} loop.remove_writer (fd)

Arrête de surveiller le descripteur de fichier `fd' pour la disponibilité en écriture. Renvoie @code{True} si `fd' était précédemment surveillé pour les écritures.
@end deffn

Voir aussi la section @ref{32b0,,Prise en charge de la plate-forme} pour certaines limitations de ces méthodes.

@node Travail direct avec des objets socket,DNS,Surveillance de descripteur de fichier,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop working-with-socket-objects-directly}@anchor{32b1}
@subsubsection Travail direct avec des objets `socket'


En général, les implémentations de protocole qui utilisent des API basées sur le transport telles que @ref{5ee,,loop.create_connection()} et @ref{b01,,loop.create_server()} sont plus rapides que les implémentations qui fonctionnent directement avec les `sockets'. Cependant, il existe des cas d'utilisation où les performances ne sont pas critiques, et travailler directement avec les objets @ref{d8e,,socket} est plus pratique.

@geindex sock_recv() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recv}@anchor{bff}
@deffn {Méthode} coroutine loop.sock_recv (sock, nbytes)

Reçoit jusqu'à `nbytes' de `sock'. Version asynchrone de @ref{d91,,socket.recv()}.

Renvoie les données reçues sous la forme d'un objet bytes.

Le connecteur `sock' ne doit pas être bloquant.


Modifié dans la version 3.7: même si cette méthode a toujours été documentée en tant que méthode coroutine, les versions antérieures à Python 3.7 renvoyaient un @ref{bbb,,Future}. Depuis Python 3.7, il s'agit d'une méthode @code{async def}.

@end deffn

@geindex sock_recv_into() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recv_into}@anchor{af8}
@deffn {Méthode} coroutine loop.sock_recv_into (sock, buf)

Reçoit les données de `sock' dans le tampon `buf'. Basée sur le modèle de la méthode bloquante @ref{12fb,,socket.recv_into()}.

Renvoie le nombre d'octets écrits dans le tampon.

Le connecteur `sock' ne doit pas être bloquant.


Ajouté dans la version 3.7.

@end deffn

@geindex sock_recvfrom() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recvfrom}@anchor{5f1}
@deffn {Méthode} coroutine loop.sock_recvfrom (sock, bufsize)

Reçoit un datagramme jusqu'à `bufsize' de `sock'. Version asynchrone de @ref{d92,,socket.recvfrom()}.

Renvoie un `n'-uplet (données reçues, adresse distante).

Le connecteur `sock' ne doit pas être bloquant.


Ajouté dans la version 3.11.

@end deffn

@geindex sock_recvfrom_into() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_recvfrom_into}@anchor{5f2}
@deffn {Méthode} coroutine loop.sock_recvfrom_into (sock, buf, nbytes=0)

Reçoit un datagramme jusqu'à `nbytes' de `sock' vers `buf'. Version asynchrone de @ref{12fc,,socket.recvfrom_into()}.

Renvoie un `n'-uplet (nombre d'octets reçus, adresse distante).

Le connecteur `sock' ne doit pas être bloquant.


Ajouté dans la version 3.11.

@end deffn

@geindex sock_sendall() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_sendall}@anchor{c00}
@deffn {Méthode} coroutine loop.sock_sendall (sock, data)

Envoie les données `data' au connecteur `sock'. Version asynchrone de @ref{d95,,socket.sendall()}.

Cette méthode continue d'envoyer des données au connecteur jusqu'à ce que toutes les `data' aient été envoyées ou qu'une erreur se produise. @code{None} est renvoyé en cas de succès. En cas d'erreur, une exception est levée. De plus, il n'existe aucun moyen de déterminer la quantité de données, le cas échéant, qui a été traitée avec succès par l'extrémité réceptrice de la connexion.

Le connecteur `sock' ne doit pas être bloquant.


Modifié dans la version 3.7: même si la méthode a toujours été documentée en tant que méthode coroutine, avant Python 3.7, elle renvoyait un @ref{bbb,,Future}. Depuis Python 3.7, il s'agit d'une méthode @code{async def}.

@end deffn

@geindex sock_sendto() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_sendto}@anchor{5f0}
@deffn {Méthode} coroutine loop.sock_sendto (sock, data, address)

Envoie un datagramme de `sock' à `address'. Version asynchrone de @ref{d96,,socket.sendto()}.

Renvoie le nombre d'octets envoyés.

Le connecteur `sock' ne doit pas être bloquant.


Ajouté dans la version 3.11.

@end deffn

@geindex sock_connect() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_connect}@anchor{db7}
@deffn {Méthode} coroutine loop.sock_connect (sock, address)

Connecte `sock' à un connecteur distant situé à `address'.

Version asynchrone de @ref{d90,,socket.connect()}.

Le connecteur `sock' ne doit pas être bloquant.


Modifié dans la version 3.5.2: @code{address} n'a plus besoin d'être résolu. @code{sock_connect} essaie de vérifier si `address' est déjà résolue en appelant @ref{94f,,socket.inet_pton()}. Sinon, @ref{c02,,loop.getaddrinfo()} est utilisé pour résoudre `address'.



@subsubheading Voir aussi


@ref{5ee,,loop.create_connection()} et @ref{b06,,asyncio.open_connection()}.

@end deffn

@geindex sock_accept() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_accept}@anchor{c01}
@deffn {Méthode} coroutine loop.sock_accept (sock)

Accepte une connexion. Basée sur le modèle de la méthode bloquante @ref{d8f,,socket.accept()}.

Le connecteur doit être lié à une adresse et écouter les connexions. La valeur de retour est une paire @code{(conn, adresse)} où `conn' est un `nouvel' objet socket utilisable pour envoyer et recevoir des données sur la connexion, et `adresse' est l'adresse liée au connecteur de l'autre côté de la connexion.

Le connecteur `sock' ne doit pas être bloquant.


Modifié dans la version 3.7: même si la méthode a toujours été documentée en tant que méthode coroutine, avant Python 3.7, elle renvoyait un @ref{bbb,,Future}. Depuis Python 3.7, il s'agit d'une méthode @code{async def}.



@subsubheading Voir aussi


@ref{b01,,loop.create_server()} et @ref{b07,,start_server()}.

@end deffn

@geindex sock_sendfile() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop sock_sendfile}@anchor{afc}
@deffn {Méthode} coroutine loop.sock_sendfile (sock, file, offset=0, count=None, *, fallback=True)

Envoie le fichier en utilisant @ref{afd,,os.sendfile} (haute performance) si possible. Renvoie le nombre total d'octets envoyés.

Version asynchrone de @ref{e46,,socket.sendfile()}.

`sock' doit être un @ref{12d1,,socket.SOCK_STREAM} @ref{d8e,,socket} non bloquant.

`file' doit être un objet fichier normal ouvert en mode binaire.

`offset' indique où commencer la lecture du fichier. Si spécifié, `count' est le nombre total d'octets à transmettre, par opposition à l'envoi du fichier jusqu'à ce que EOF soit atteint. La position du fichier est toujours mise à jour, même lorsque cette méthode génère une erreur. @ref{2930,,file.tell()} peut être utilisée pour obtenir le nombre d'octets réellement envoyés.

`fallback', lorsqu'il est défini à @code{True}, permet à `asyncio' de lire et d'envoyer manuellement le fichier lorsque la plateforme ne prend pas en charge l'appel système `sendfile' (par exemple, Windows ou connecteur SSL sous Unix).

Lève une @ref{3288,,SendfileNotAvailableError} si le système ne prend pas en charge l'appel système `sendfile' et que `fallback' est @code{False}.

Le connecteur `sock' ne doit pas être bloquant.


Ajouté dans la version 3.7.

@end deffn

@node DNS,Travail avec des tubes pipes,Travail direct avec des objets socket,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop dns}@anchor{32b2}
@subsubsection DNS


@geindex getaddrinfo() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop getaddrinfo}@anchor{c02}
@deffn {Méthode} coroutine loop.getaddrinfo (host, port, *, family=0, type=0, proto=0, flags=0)

Version asynchrone de @ref{16e0,,socket.getaddrinfo()}.
@end deffn

@geindex getnameinfo() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop getnameinfo}@anchor{c03}
@deffn {Méthode} coroutine loop.getnameinfo (sockaddr, flags=0)

Version asynchrone de @ref{164d,,socket.getnameinfo()}.
@end deffn

@cartouche
@quotation Note 
Both `getaddrinfo' and `getnameinfo' internally utilize their synchronous
versions through the loop's default thread pool executor.
When this executor is saturated, these methods may experience delays,
which higher-level networking libraries may report as increased timeouts.
To mitigate this, consider using a custom executor for other user tasks,
or setting a default executor with a larger number of workers.
@end quotation
@end cartouche


Modifié dans la version 3.7: les méthodes `getaddrinfo' et `getnameinfo' ont toujours été documentées pour renvoyer une coroutine, mais avant Python 3.7, elles renvoyaient en fait des objets @ref{bbb,,asyncio.Future}. À partir de Python 3.7, les deux méthodes sont des coroutines.


@node Travail avec des tubes pipes,Signaux Unix,DNS,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop working-with-pipes}@anchor{32b3}
@subsubsection Travail avec des tubes (`pipes')


@geindex connect_read_pipe() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop connect_read_pipe}@anchor{325b}
@deffn {Méthode} coroutine loop.connect_read_pipe (protocol_factory, pipe)

Branche l'extrémité en lecture du tube `pipe' à la boucle d'évènements.

`protocol_factory' doit être un appelable renvoyant un protocole gérant le @ref{329f,,protocole asyncio}.

`pipe' est un @ref{11a0,,simili-fichier}.

Renvoie la paire @code{(transport, protocol)}, où `transport' prend en charge l'interface @ref{32b4,,ReadTransport} et `protocol' est un objet instancié par `protocol_factory'.

Avec la boucle d'événements @ref{5f3,,SelectorEventLoop}, le `pipe' est mis en mode non bloquant.
@end deffn

@geindex connect_write_pipe() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop connect_write_pipe}@anchor{325c}
@deffn {Méthode} coroutine loop.connect_write_pipe (protocol_factory, pipe)

Branche l'extrémité en écriture de `pipe' à la boucle d'évènements.

`protocol_factory' doit être un appelable renvoyant un protocole gérant le @ref{329f,,protocole asyncio}.

`pipe' est un @ref{11a0,,simili-fichier}.

Renvoie la paire @code{(transport, protocol)}, où `transport' prend en charge l'interface @ref{32b5,,WriteTransport} et `protocol' est un objet instancié par `protocol_factory'.

Avec la boucle d'événements @ref{5f3,,SelectorEventLoop}, le `pipe' est mis en mode non bloquant.
@end deffn

@cartouche
@quotation Note 
@ref{5f3,,SelectorEventLoop} ne prend pas en charge les méthodes ci-dessus sous Windows. Utilisez @ref{5f4,,ProactorEventLoop} à la place pour Windows.
@end quotation
@end cartouche


@subsubheading Voir aussi


les méthodes @ref{3258,,loop.subprocess_exec()} et @ref{3259,,loop.subprocess_shell()}.


@node Signaux Unix,Exécution de code dans des pools de threads ou de processus,Travail avec des tubes pipes,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop unix-signals}@anchor{32b6}
@subsubsection Signaux Unix


@geindex add_signal_handler() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop loop-add-signal-handler}@anchor{31da}@anchor{library/asyncio-eventloop asyncio loop add_signal_handler}@anchor{32b7}
@deffn {Méthode} loop.add_signal_handler (signum, callback, *args)

Définit `callback' comme gestionnaire du signal `signum'.

La fonction de rappel sera appelée par `loop', avec d'autres rappels en file d'attente et des coroutines exécutables de cette boucle d'événements. Contrairement aux gestionnaires de signaux enregistrés à l'aide de @ref{1114,,signal.signal()}, un rappel enregistré avec cette fonction est autorisé à interagir avec la boucle d'événements.

Lève une @ref{1ff,,ValueError} si le numéro de signal est invalide ou non attrapable. Lève une @ref{193,,RuntimeError} s'il y a un problème lors de la configuration du gestionnaire.

Utilisez @ref{40a,,functools.partial()} pour @ref{3299,,passer des arguments nommés} à `callback'.

Comme @ref{1114,,signal.signal()}, cette fonction doit être invoquée dans le fil d'exécution principal.
@end deffn

@geindex remove_signal_handler() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop remove_signal_handler}@anchor{32b8}
@deffn {Méthode} loop.remove_signal_handler (sig)

Supprime le gestionnaire du signal `sig'.

Renvoie @code{True} si le gestionnaire de signal a été supprimé, ou @code{False} si aucun gestionnaire n'a été défini pour le signal donné.

@ref{1ce0,,Availability}: Unix.
@end deffn


@subsubheading Voir aussi


le module @ref{c5,,signal}.


@node Exécution de code dans des pools de threads ou de processus,API de gestion d'erreur,Signaux Unix,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop executing-code-in-thread-or-process-pools}@anchor{32b9}
@subsubsection Exécution de code dans des pools de threads ou de processus


@geindex run_in_executor() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop run_in_executor}@anchor{8d6}
@deffn {Méthode} awaitable loop.run_in_executor (executor, func, *args)

Fait en sorte que `func' soit appelée dans l'exécuteur spécifié.

The `executor' argument should be an @ref{3129,,concurrent.futures.Executor}
instance. The default executor is used if `executor' is @code{None}.
The default executor can be set by @ref{72d,,loop.set_default_executor()},
otherwise, a @ref{72c,,concurrent.futures.ThreadPoolExecutor} will be
lazy-initialized and used by @ref{8d6,,run_in_executor()} if needed.

Exemple :

@example
import asyncio
import concurrent.futures

def blocking_io():
    # File operations (such as logging) can block the
    # event loop: run them in a thread pool.
    with open('/dev/urandom', 'rb') as f:
        return f.read(100)

def cpu_bound():
    # CPU-bound operations will block the event loop:
    # in general it is preferable to run them in a
    # process pool.
    return sum(i * i for i in range(10 ** 7))

async def main():
    loop = asyncio.get_running_loop()

    ## Options:

    # 1. Run in the default loop's executor:
    result = await loop.run_in_executor(
        None, blocking_io)
    print('default thread pool', result)

    # 2. Run in a custom thread pool:
    with concurrent.futures.ThreadPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, blocking_io)
        print('custom thread pool', result)

    # 3. Run in a custom process pool:
    with concurrent.futures.ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(
            pool, cpu_bound)
        print('custom process pool', result)

if __name__ == '__main__':
    asyncio.run(main())
@end example

Notez que la garde du point d'entrée (@code{if __name__ == '__main__'}) est requis pour l'option 3 en raison des particularités de @ref{93,,multiprocessing}, qui est utilisé par @ref{8db,,ProcessPoolExecutor}. Voir @ref{3115,,Importation sécurisée du module principal}.

Cette méthode renvoie un objet @ref{bbb,,asyncio.Future}.

Utilisez @ref{40a,,functools.partial()} pour @ref{3299,,passer des arguments nommés} à `func'.


Modifié dans la version 3.5.3: @ref{8d6,,loop.run_in_executor()} ne configure plus le @code{max_workers} de l'exécuteur de pool de threads qu'il crée, laissant à la place à l'exécuteur de pool de threads (@ref{72c,,ThreadPoolExecutor}) le soin de définir le défaut.

@end deffn

@geindex set_default_executor() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_default_executor}@anchor{72d}
@deffn {Méthode} loop.set_default_executor (executor)

Définit `executor' comme exécuteur par défaut utilisé par @ref{8d6,,run_in_executor()}. `executor' doit être une instance de @ref{72c,,ThreadPoolExecutor}.


Modifié dans la version 3.11: `executor' doit être une instance de @ref{72c,,ThreadPoolExecutor}.

@end deffn

@node API de gestion d'erreur,Activation du mode débogage,Exécution de code dans des pools de threads ou de processus,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop error-handling-api}@anchor{32ba}
@subsubsection API de gestion d'erreur


Permet de personnaliser la façon dont les exceptions sont gérées dans la boucle d'événements.

@geindex set_exception_handler() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_exception_handler}@anchor{32bb}
@deffn {Méthode} loop.set_exception_handler (handler)

Définit `handler' comme nouveau gestionnaire d'exceptions de boucle d'événements.

Si `handler' est @code{None}, le gestionnaire d'exceptions par défaut est activé. Sinon, `handler' doit être un appelable avec la signature correspondant à @code{(loop, context)}, où @code{loop} est une référence à la boucle d'événements active et @code{context} est un @code{dict} contenant les détails de l'exception (voir la documentation @ref{32bc,,call_exception_handler()} pour plus de détails sur le contexte).

If the handler is called on behalf of a @ref{4c2,,Task} or
@ref{1a31,,Handle}, it is run in the
@ref{152f,,contextvars.Context} of that task or callback handle.


Modifié dans la version 3.12: The handler may be called in the @ref{152f,,Context}
of the task or handle where the exception originated.

@end deffn

@geindex get_exception_handler() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop get_exception_handler}@anchor{c68}
@deffn {Méthode} loop.get_exception_handler ()

Renvoie le gestionnaire d'exceptions actuel ou @code{None} si aucun gestionnaire d'exceptions personnalisé n'a été défini.


Ajouté dans la version 3.5.2.

@end deffn

@geindex default_exception_handler() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop default_exception_handler}@anchor{32bd}
@deffn {Méthode} loop.default_exception_handler (context)

Gestionnaire d'exception par défaut.

Appelée lorsqu'une exception se produit et qu'aucun gestionnaire d'exception n'est défini. Elle peut être appelée par un gestionnaire d'exceptions personnalisé qui souhaite s'en remettre au comportement du gestionnaire par défaut.

Le paramètre `context' a la même signification que dans @ref{32bc,,call_exception_handler()}.
@end deffn

@geindex call_exception_handler() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop call_exception_handler}@anchor{32bc}
@deffn {Méthode} loop.call_exception_handler (context)

Appelle le gestionnaire d'exception de la boucle d'évènements actuelle.

`context' est un objet @code{dict} contenant les clés suivantes (de nouvelles clés pourront être introduites dans les futures versions de Python) :


@itemize *

@item 
'message' : message d'erreur ;

@item 
'exception' (facultatif) : objet exception ;

@item 
'future' (facultatif) : instance de @ref{bbb,,asyncio.Future} ;

@item 
'task' (facultatif) : instance de @ref{4c2,,asyncio.Task} ;

@item 
`'handle'' (facultatif) : instance de @ref{1a31,,asyncio.Handle} ;

@item 
`'protocol'' (facultatif) : instance de @ref{329f,,protocole asyncio} ;

@item 
'transport' (facultatif) : instance de @ref{32a0,,transport asyncio} ;

@item 
'socket' (facultatif) : instance de @ref{d8e,,socket.socket} ;

@item 

@table @asis

@item `'asyncgen'' (facultatif) : générateur asynchrone qui a causé

l'exception
@end table
@end itemize

@cartouche
@quotation Note 
This method should not be overloaded in subclassed
event loops.  For custom exception handling, use
the @ref{32bb,,set_exception_handler()} method.
@end quotation
@end cartouche
@end deffn

@node Activation du mode débogage,Exécution de sous-processus,API de gestion d'erreur,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop enabling-debug-mode}@anchor{32be}
@subsubsection Activation du mode débogage


@geindex get_debug() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop get_debug}@anchor{db0}
@deffn {Méthode} loop.get_debug ()

Obtient le mode de débogage (@ref{451,,bool}) de la boucle d'événements.

La valeur par défaut est @code{True} si la variable d'environnement 
@geindex PYTHONASYNCIODEBUG
@geindex variable d'environnement; PYTHONASYNCIODEBUG
@ref{1cda,,PYTHONASYNCIODEBUG} est définie sur une chaîne non vide, @code{False} sinon.
@end deffn

@geindex set_debug() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop set_debug}@anchor{daf}
@deffn {Méthode} loop.set_debug (enabled: bool)

Active le mode débogage pour la boucle d'évènements.


Modifié dans la version 3.7: le nouveau @ref{1f5,,mode de développement Python} peut désormais également être utilisé pour activer le mode de débogage.

@end deffn

@geindex slow_callback_duration (attribut asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop slow_callback_duration}@anchor{32bf}
@deffn {Attribut} loop.slow_callback_duration

This attribute can be used to set the
minimum execution duration in seconds that is considered "slow".
When debug mode is enabled, "slow" callbacks are logged.

Default value is 100 milliseconds.
@end deffn


@subsubheading Voir aussi


le @ref{1cdb,,mode debogage d'asyncio}.


@node Exécution de sous-processus,,Activation du mode débogage,Méthodes de la boucle d'évènements
@anchor{library/asyncio-eventloop running-subprocesses}@anchor{32c0}
@subsubsection Exécution de sous-processus


Les méthodes décrites dans ces sous-sections sont de bas niveau. Dans le code `async/await' normal, pensez à utiliser les fonctions de commodité de haut niveau @ref{a66,,asyncio.create_subprocess_shell()} et @ref{a65,,asyncio.create_subprocess_exec()} à la place.

@cartouche
@quotation Note 
sous Windows, la boucle d'événements par défaut @ref{5f4,,ProactorEventLoop} prend en charge les sous-processus, contrairement à @ref{5f3,,SelectorEventLoop}. Voir @ref{325a,,Prise en charge des sous-processus sous Windows} pour plus de détails.
@end quotation
@end cartouche

@geindex subprocess_exec() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop loop-subprocess-exec}@anchor{31d9}@anchor{library/asyncio-eventloop asyncio loop subprocess_exec}@anchor{3258}
@deffn {Méthode} coroutine loop.subprocess_exec (protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Crée un sous-processus à partir d'un ou plusieurs arguments de chaîne spécifiés par `args'.

`args' doit être une liste de chaînes représentée par :


@itemize *

@item 
@ref{435,,str} ;

@item 
ou @ref{1bd,,bytes}, encodés selon l'@ref{273e,,encodage du système de fichiers}.
@end itemize

La première chaîne spécifie l'exécutable du programme et les chaînes restantes spécifient les arguments. Ensemble, les arguments de chaîne forment le @code{argv} du programme.

C'est similaire à la classe standard de la bibliothèque @ref{197,,subprocess.Popen} appelée avec @code{shell=False} et la liste des chaînes passées en premier argument ; cependant, où @ref{197,,Popen} prend un seul argument qui est une liste de chaînes, `subprocess_exec' prend plusieurs arguments de chaînes.

Le `protocol_factory' doit être un appelable renvoyant une sous-classe de la classe @ref{32c1,,asyncio.SubprocessProtocol}.

Autres paramètres :


@itemize *

@item 
`stdin' peut être l'un de ces éléments :


@itemize *

@item 
a file-like object

@item 
an existing file descriptor (a positive integer), for example those created with @ref{1768,,os.pipe()}

@item 
la constante @ref{b75,,subprocess.PIPE} (par défaut) qui va créer un nouveau tube et le connecter,

@item 
la valeur @code{None} qui fera que le sous-processus héritera du descripteur de fichier de ce processus,

@item 
la constante @ref{112e,,subprocess.DEVNULL} qui indique que le fichier spécial @ref{19c1,,os.devnull} sera utilisé.
@end itemize

@item 
`stdout' peut être l'un de ces éléments :


@itemize *

@item 
a file-like object

@item 
la constante @ref{b75,,subprocess.PIPE} (par défaut) qui va créer un nouveau tube et le connecter,

@item 
la valeur @code{None} qui fera que le sous-processus héritera du descripteur de fichier de ce processus,

@item 
la constante @ref{112e,,subprocess.DEVNULL} qui indique que le fichier spécial @ref{19c1,,os.devnull} sera utilisé.
@end itemize

@item 
`stderr' peut être l'un de ces éléments :


@itemize *

@item 
a file-like object

@item 
la constante @ref{b75,,subprocess.PIPE} (par défaut) qui va créer un nouveau tube et le connecter,

@item 
la valeur @code{None} qui fera que le sous-processus héritera du descripteur de fichier de ce processus,

@item 
la constante @ref{112e,,subprocess.DEVNULL} qui indique que le fichier spécial @ref{19c1,,os.devnull} sera utilisé.

@item 
la constante @ref{3147,,subprocess.STDOUT} qui connectera le flux d'erreur standard au flux de sortie standard du processus.
@end itemize

@item 
Tous les autres arguments nommés sont passés à @ref{197,,subprocess.Popen} sans interprétation, à l'exception de `bufsize', `universal_newlines', `shell', `text', `encoding' et `errors', qui ne doivent pas être spécifiés du tout.

L'API de sous-processus @code{asyncio} ne prend pas en charge le décodage des flux sous forme de texte. @ref{8c3,,bytes.decode()} peut être utilisée pour convertir les octets renvoyés par le flux en texte.
@end itemize

If a file-like object passed as `stdin', `stdout' or `stderr' represents a
pipe, then the other side of this pipe should be registered with
@ref{325c,,connect_write_pipe()} or @ref{325b,,connect_read_pipe()} for use
with the event loop.

Voir le constructeur de la classe @ref{197,,subprocess.Popen} pour la documentation sur les autres arguments.

Renvoie une paire @code{(transport, protocol)}, où `transport' est conforme à la classe de base @ref{32c2,,asyncio.SubprocessTransport} et `protocol' est un objet instancié par `protocol_factory'.
@end deffn

@geindex subprocess_shell() (méthode asyncio.loop)
@anchor{library/asyncio-eventloop asyncio loop subprocess_shell}@anchor{3259}
@deffn {Méthode} coroutine loop.subprocess_shell (protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

Crée un sous-processus à partir de `cmd', qui peut être une chaîne @ref{435,,str} ou une chaîne @ref{1bd,,bytes} encodée avec l'@ref{273e,,encodage du système de fichiers}, en utilisant la syntaxe "shell" de la plate-forme.

C'est similaire à la classe standard de la bibliothèque @ref{197,,subprocess.Popen} appelée avec @code{shell=True}.

Le `protocol_factory' doit être un appelable renvoyant une sous-classe de la classe @ref{32c1,,SubprocessProtocol}.

Voir @ref{3258,,subprocess_exec()} pour plus de détails sur les arguments restants.

Renvoie une paire @code{(transport, protocol)}, où `transport' est conforme à la classe de base @ref{32c2,,SubprocessTransport} et `protocol' est un objet instancié par `protocol_factory'.
@end deffn

@cartouche
@quotation Note 
il est de la responsabilité de l'application de s'assurer que tous les espaces blancs et les caractères spéciaux sont correctement échappés pour éviter les vulnérabilités d'injection de shell@footnote{https://en.wikipedia.org/wiki/Shell_injection#Shell_injection}. La fonction @ref{27a,,shlex.quote()} peut être utilisée pour échapper correctement les espaces blancs et les caractères spéciaux dans les chaînes qui seront utilisées pour construire des commandes shell.
@end quotation
@end cartouche

@node Fonctions de rappel sur des descripteurs,Objets Serveur,Méthodes de la boucle d'évènements,Boucle d'évènements
@anchor{library/asyncio-eventloop callback-handles}@anchor{328f}
@subsubsection Fonctions de rappel sur des descripteurs


@geindex Handle (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio Handle}@anchor{1a31}
@deffn {Classe} asyncio.Handle

Objet encapsulant une fonction de rappel renvoyé par @ref{af2,,loop.call_soon()}, @ref{af3,,loop.call_soon_threadsafe()}.

@geindex get_context() (méthode asyncio.Handle)
@anchor{library/asyncio-eventloop asyncio Handle get_context}@anchor{32c3}
@deffn {Méthode} get_context ()

Return the @ref{152f,,contextvars.Context} object
associated with the handle.


Ajouté dans la version 3.12.

@end deffn

@geindex cancel() (méthode asyncio.Handle)
@anchor{library/asyncio-eventloop asyncio Handle cancel}@anchor{32c4}
@deffn {Méthode} cancel ()

Annule le rappel. Si le rappel a déjà été annulé ou exécuté, cette méthode n'a aucun effet.
@end deffn

@geindex cancelled() (méthode asyncio.Handle)
@anchor{library/asyncio-eventloop asyncio Handle cancelled}@anchor{b09}
@deffn {Méthode} cancelled ()

Renvoie @code{True} si la fonction de rappel a été annulée.


Ajouté dans la version 3.7.

@end deffn
@end deffn

@geindex TimerHandle (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio TimerHandle}@anchor{16fb}
@deffn {Classe} asyncio.TimerHandle

Objet encapsulant la fonction de rappel renvoyé par @ref{af4,,loop.call_later()} et @ref{af5,,loop.call_at()}.

Cette classe est une sous-classe de @ref{1a31,,Handle}.

@geindex when() (méthode asyncio.TimerHandle)
@anchor{library/asyncio-eventloop asyncio TimerHandle when}@anchor{b05}
@deffn {Méthode} when ()

Renvoie une heure de rappel planifiée sous forme de @ref{2eb,,float} secondes.

L'heure est un horodatage absolu, utilisant la même référence de temps que @ref{329c,,loop.time()}.


Ajouté dans la version 3.7.

@end deffn
@end deffn

@node Objets Serveur,Implémentations de boucle d'évènements,Fonctions de rappel sur des descripteurs,Boucle d'évènements
@anchor{library/asyncio-eventloop server-objects}@anchor{3290}
@subsubsection Objets Serveur


Les objets serveur sont créés par les fonctions @ref{b01,,loop.create_server()}, @ref{1ac,,loop.create_unix_server()}, @ref{b07,,start_server()} et @ref{3219,,start_unix_server()}.

Do not instantiate the @ref{b00,,Server} class directly.

@geindex Server (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio Server}@anchor{b00}
@deffn {Classe} asyncio.Server

Les objets `Server' sont des gestionnaires de contexte asynchrones. Lorsqu'il est utilisé dans une instruction @code{async with}, il est garanti que l'objet Serveur est fermé et n'accepte pas de nouvelle connexion lorsque l'instruction @code{async with} est terminée :

@example
srv = await loop.create_server(...)

async with srv:
    # some code

# At this point, srv is closed and no longer accepts new connections.
@end example


Modifié dans la version 3.7: l'objet serveur est un gestionnaire de contexte asynchrone depuis Python 3.7.



Modifié dans la version 3.11: This class was exposed publicly as @code{asyncio.Server} in Python 3.9.11, 3.10.3 and 3.11.


@geindex close() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server close}@anchor{3216}
@deffn {Méthode} close ()

Arrête le serveur : ferme les connecteurs d'écoute et définit l'attribut @ref{c04,,sockets} à @code{None}.

Les connecteurs qui représentent les connexions client entrantes existantes restent ouvertes.

The server is closed asynchronously; use the @ref{1653,,wait_closed()}
coroutine to wait until the server is closed (and no more
connections are active).
@end deffn

@geindex close_clients() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server close_clients}@anchor{1b0}
@deffn {Méthode} close_clients ()

Close all existing incoming client connections.

Calls @ref{32a3,,close()} on all associated
transports.

@ref{3216,,close()} should be called before @ref{1b0,,close_clients()} when
closing the server to avoid races with new clients connecting.


Ajouté dans la version 3.13.

@end deffn

@geindex abort_clients() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server abort_clients}@anchor{1b1}
@deffn {Méthode} abort_clients ()

Close all existing incoming client connections immediately,
without waiting for pending operations to complete.

Calls @ref{32c5,,abort()} on all associated
transports.

@ref{3216,,close()} should be called before @ref{1b1,,abort_clients()} when
closing the server to avoid races with new clients connecting.


Ajouté dans la version 3.13.

@end deffn

@geindex get_loop() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server get_loop}@anchor{aff}
@deffn {Méthode} get_loop ()

Renvoie la boucle d'événement associée à l'objet serveur.


Ajouté dans la version 3.7.

@end deffn

@geindex start_serving() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server start_serving}@anchor{b02}
@deffn {Méthode} coroutine start_serving ()

Commence à accepter les connexions.

Cette méthode est idempotente, elle peut donc être appelée lorsque le serveur est déjà en service.

Le paramètre nommé `start_serving' de @ref{b01,,loop.create_server()} et @ref{b07,,asyncio.start_server()} permet de créer un objet `Server' qui n'accepte pas les connexions initialement. Dans ce cas, @code{Server.start_serving()} ou @ref{b03,,Server.serve_forever()} peut être utilisée pour que le serveur commence à accepter les connexions.


Ajouté dans la version 3.7.

@end deffn

@geindex serve_forever() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server serve_forever}@anchor{b03}
@deffn {Méthode} coroutine serve_forever ()

Commence à accepter les connexions jusqu'à ce que la coroutine soit annulée. L'annulation de la tâche @code{serve_forever} provoque la fermeture du serveur.

Cette méthode peut être appelée si le serveur accepte déjà les connexions. Une seule tâche @code{serve_forever} peut exister par objet `Server'.

Exemple :

@example
async def client_connected(reader, writer):
    # Communicate with the client with
    # reader/writer streams.  For example:
    await reader.readline()

async def main(host, port):
    srv = await asyncio.start_server(
        client_connected, host, port)
    await srv.serve_forever()

asyncio.run(main('127.0.0.1', 0))
@end example


Ajouté dans la version 3.7.

@end deffn

@geindex is_serving() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server is_serving}@anchor{b04}
@deffn {Méthode} is_serving ()

Renvoie @code{True} si le serveur accepte de nouvelles connexions.


Ajouté dans la version 3.7.

@end deffn

@geindex wait_closed() (méthode asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server wait_closed}@anchor{1653}
@deffn {Méthode} coroutine wait_closed ()

Wait until the @ref{3216,,close()} method completes and all active
connections have finished.
@end deffn

@geindex sockets (attribut asyncio.Server)
@anchor{library/asyncio-eventloop asyncio Server sockets}@anchor{c04}
@deffn {Attribut} sockets

List of socket-like objects, @code{asyncio.trsock.TransportSocket}, which
the server is listening on.


Modifié dans la version 3.7: avant Python 3.7, @code{Server.sockets} renvoyait directement une liste interne de sockets de serveur. En 3.7, une copie de cette liste est renvoyée.

@end deffn
@end deffn
@anchor{library/asyncio-eventloop asyncio-event-loops}@anchor{32c6}
@node Implémentations de boucle d'évènements,Exemples<18>,Objets Serveur,Boucle d'évènements
@anchor{library/asyncio-eventloop asyncio-event-loop-implementations}@anchor{32c7}@anchor{library/asyncio-eventloop event-loop-implementations}@anchor{3291}
@subsubsection Implémentations de boucle d'évènements


`asyncio' est livré avec deux implémentations de boucles d'événements différentes : @ref{5f3,,SelectorEventLoop} et @ref{5f4,,ProactorEventLoop}.

By default asyncio is configured to use @ref{167f,,EventLoop}.

@geindex SelectorEventLoop (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio SelectorEventLoop}@anchor{5f3}
@deffn {Classe} asyncio.SelectorEventLoop

A subclass of @ref{94c,,AbstractEventLoop} based on the
@ref{c1,,selectors} module.

Utilise le `sélecteur' le plus efficace disponible pour la plate-forme donnée. Il est également possible de configurer manuellement l'implémentation exacte du sélecteur à utiliser :

@example
import asyncio
import selectors

class MyPolicy(asyncio.DefaultEventLoopPolicy):
   def new_event_loop(self):
      selector = selectors.SelectSelector()
      return asyncio.SelectorEventLoop(selector)

asyncio.set_event_loop_policy(MyPolicy())
@end example

@ref{1ce0,,Availability}: Unix, Windows.
@end deffn

@geindex ProactorEventLoop (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio ProactorEventLoop}@anchor{5f4}
@deffn {Classe} asyncio.ProactorEventLoop

A subclass of @ref{94c,,AbstractEventLoop} for Windows that uses "I/O Completion Ports" (IOCP).

@ref{1ce0,,Availability}: Windows.


@subsubheading Voir aussi


MSDN documentation on I/O Completion Ports@footnote{https://learn.microsoft.com/windows/win32/fileio/i-o-completion-ports}.

@end deffn

@geindex EventLoop (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio EventLoop}@anchor{167f}
@deffn {Classe} asyncio.EventLoop

@quotation

An alias to the most efficient available subclass of @ref{94c,,AbstractEventLoop} for the given
platform.

It is an alias to @ref{5f3,,SelectorEventLoop} on Unix and @ref{5f4,,ProactorEventLoop} on Windows.
@end quotation


Ajouté dans la version 3.13.

@end deffn

@geindex AbstractEventLoop (classe dans asyncio)
@anchor{library/asyncio-eventloop asyncio AbstractEventLoop}@anchor{94c}
@deffn {Classe} asyncio.AbstractEventLoop

Classe mère abstraite pour les boucles d'événements conforme à `asyncio'.

La section @ref{3293,,Méthodes de la boucle d'évènements} liste toutes les méthodes qu'une implémentation alternative de @code{AbstractEventLoop} doit définir.
@end deffn

@node Exemples<18>,,Implémentations de boucle d'évènements,Boucle d'évènements
@anchor{library/asyncio-eventloop examples}@anchor{3292}
@subsubsection Exemples


Notez que tous les exemples de cette section montrent `à dessein' comment utiliser les API de boucle d'événement de bas niveau, telles que @ref{3295,,loop.run_forever()} et @ref{af2,,loop.call_soon()}. Les applications `asyncio' modernes ont rarement besoin d'être écrites de cette façon ; pensez à utiliser les fonctions de haut niveau comme @ref{466,,asyncio.run()}.

@menu
* "Hello World" avec call_soon(): "Hello World" avec call_soon. 
* Affichage de la date actuelle avec call_later(): Affichage de la date actuelle avec call_later. 
* Surveillance des événements de lecture pour un descripteur de fichier:: 
* Gestion des signaux SIGINT et SIGTERM:: 

@end menu

@node "Hello World" avec call_soon,Affichage de la date actuelle avec call_later,,Exemples<18>
@anchor{library/asyncio-eventloop asyncio-example-lowlevel-helloworld}@anchor{32c8}@anchor{library/asyncio-eventloop hello-world-with-call-soon}@anchor{32c9}
@subsubsection "Hello World" avec @code{call_soon()}


Un exemple utilisant la méthode @ref{af2,,loop.call_soon()} pour programmer un rappel. Le rappel affiche @code{"Hello World"} puis arrête la boucle d'événements :

@example
import asyncio

def hello_world(loop):
    """A callback to print 'Hello World' and stop the event loop"""
    print('Hello World')
    loop.stop()

loop = asyncio.new_event_loop()

# Schedule a call to hello_world()
loop.call_soon(hello_world, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()
@end example


@subsubheading Voir aussi


un exemple similaire de @ref{31d3,,Hello World} créé avec une coroutine et la fonction @ref{466,,run()}.


@node Affichage de la date actuelle avec call_later,Surveillance des événements de lecture pour un descripteur de fichier,"Hello World" avec call_soon,Exemples<18>
@anchor{library/asyncio-eventloop asyncio-example-call-later}@anchor{32ca}@anchor{library/asyncio-eventloop display-the-current-date-with-call-later}@anchor{32cb}
@subsubsection Affichage de la date actuelle avec @code{call_later()}


Un exemple de rappel affichant la date actuelle toutes les secondes. Le rappel utilise la méthode @ref{af4,,loop.call_later()} pour se re-planifier après 5 secondes, puis arrête la boucle d'événements :

@example
import asyncio
import datetime

def display_date(end_time, loop):
    print(datetime.datetime.now())
    if (loop.time() + 1.0) < end_time:
        loop.call_later(1, display_date, end_time, loop)
    else:
        loop.stop()

loop = asyncio.new_event_loop()

# Schedule the first call to display_date()
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)

# Blocking call interrupted by loop.stop()
try:
    loop.run_forever()
finally:
    loop.close()
@end example


@subsubheading Voir aussi


un exemple similaire de @ref{31f1,,date actuelle} créé avec une coroutine et la fonction @ref{466,,run()}.


@node Surveillance des événements de lecture pour un descripteur de fichier,Gestion des signaux SIGINT et SIGTERM,Affichage de la date actuelle avec call_later,Exemples<18>
@anchor{library/asyncio-eventloop asyncio-example-watch-fd}@anchor{3232}@anchor{library/asyncio-eventloop watch-a-file-descriptor-for-read-events}@anchor{32cc}
@subsubsection Surveillance des événements de lecture pour un descripteur de fichier


Attend qu'un descripteur de fichier reçoive des données en utilisant la méthode @ref{3233,,loop.add_reader()} puis ferme la boucle d'événements :

@example
import asyncio
from socket import socketpair

# Create a pair of connected file descriptors
rsock, wsock = socketpair()

loop = asyncio.new_event_loop()

def reader():
    data = rsock.recv(100)
    print("Received:", data.decode())

    # We are done: unregister the file descriptor
    loop.remove_reader(rsock)

    # Stop the event loop
    loop.stop()

# Register the file descriptor for read event
loop.add_reader(rsock, reader)

# Simulate the reception of data from the network
loop.call_soon(wsock.send, 'abc'.encode())

try:
    # Run the event loop
    loop.run_forever()
finally:
    # We are done. Close sockets and the event loop.
    rsock.close()
    wsock.close()
    loop.close()
@end example


@subsubheading Voir aussi



@itemize *

@item 
un @ref{3231,,exemple} similaire utilisant les transports, les protocoles et la méthode @ref{5ee,,loop.create_connection()},

@item 
un autre @ref{322f,,exemple} utilisant la fonction et les flux de haut niveau @ref{b06,,asyncio.open_connection()}.
@end itemize


@node Gestion des signaux SIGINT et SIGTERM,,Surveillance des événements de lecture pour un descripteur de fichier,Exemples<18>
@anchor{library/asyncio-eventloop asyncio-example-unix-signals}@anchor{32cd}@anchor{library/asyncio-eventloop set-signal-handlers-for-sigint-and-sigterm}@anchor{32ce}
@subsubsection Gestion des signaux `SIGINT' et `SIGTERM'


(Cet exemple ne fonctionne que sur Unix.)

Register handlers for signals @ref{82e,,SIGINT} and @ref{1396,,SIGTERM}
using the @ref{32b7,,loop.add_signal_handler()} method:

@example
import asyncio
import functools
import os
import signal

def ask_exit(signame, loop):
    print("got signal %s: exit" % signame)
    loop.stop()

async def main():
    loop = asyncio.get_running_loop()

    for signame in @{'SIGINT', 'SIGTERM'@}:
        loop.add_signal_handler(
            getattr(signal, signame),
            functools.partial(ask_exit, signame, loop))

    await asyncio.sleep(3600)

print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
print(f"pid @{os.getpid()@}: send SIGINT or SIGTERM to exit.")

asyncio.run(main())
@end example

@node Futures,Transports et Protocoles,Boucle d'évènements,asyncio --- Asynchronous I/O
@anchor{library/asyncio-future doc}@anchor{32cf}@anchor{library/asyncio-future asyncio-futures}@anchor{31dc}@anchor{library/asyncio-future futures}@anchor{32d0}
@subsubsection Futures


`Code source :' Lib/asyncio/futures.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/futures.py}, Lib/asyncio/base_futures.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/base_futures.py}


__________________________________________________________________


Les objets `Future' sont utilisés comme passerelles entre du `code bas niveau basé sur des fonctions de rappel' et du code haut niveau utilisant `async' et `await'.

@menu
* Fonctions pour Future:: 
* Objet Future:: 

@end menu

@node Fonctions pour Future,Objet Future,,Futures
@anchor{library/asyncio-future future-functions}@anchor{32d1}
@subsubsection Fonctions pour `Future'


@geindex isfuture() (dans le module asyncio)
@anchor{library/asyncio-future asyncio isfuture}@anchor{32d2}
@deffn {Fonction} asyncio.isfuture (obj)

Renvoie @code{True} si `obj' est soit :


@itemize *

@item 
une instance de @ref{bbb,,asyncio.Future} ;

@item 
une instance de @ref{4c2,,asyncio.Task} ;

@item 
un objet se comportant comme `Future' et possédant un attribut @code{_asyncio_future_blocking}.
@end itemize


Ajouté dans la version 3.5.

@end deffn

@geindex ensure_future() (dans le module asyncio)
@anchor{library/asyncio-future asyncio ensure_future}@anchor{c64}
@deffn {Fonction} asyncio.ensure_future (obj, *, loop=None)

Renvoie :


@itemize *

@item 
l'objet `obj' tel quel si c'est un objet @ref{bbb,,Future}, @ref{4c2,,Task} ou se comportant comme un `Future'. @ref{32d2,,isfuture()} est utilisée pour le test ;

@item 
un objet @ref{4c2,,Task} encapsulant `obj' si ce dernier est une coroutine (@ref{468,,iscoroutine()} est utilisée pour le test). Dans ce cas, l’exécution de la coroutine sera planifiée par @code{ensure_future()} ;

@item 
un objet @ref{4c2,,Task} qui attendra (`await') `obj' si ce dernier peut être attendu (`awaitable'). @ref{468,,iscoroutine()} est utilisée pour le test.
@end itemize

Si `obj' ne correspond à aucun des critères ci-dessus, une exception @ref{522,,TypeError} est levée.

@cartouche
@quotation Important 
Voir aussi la fonction @ref{5e7,,create_task()} qui est la manière privilégiée pour créer des nouvelles tâches.

Gardez une référence au résultat de cette fonction pour éviter de voir une tâche disparaitre au milieu de son exécution.
@end quotation
@end cartouche


Modifié dans la version 3.5.1: La fonction accepte n'importe quel objet @ref{1ab,,awaitable}.



Obsolète depuis la version 3.10: Un @code{DeprecationWarning} est levé si `obj' n'est pas un objet se comportant comme un `Future', si `loop' n'est pas spécifié et s'il n'y a pas de boucle d'évènements en cours d'exécution.

@end deffn

@geindex wrap_future() (dans le module asyncio)
@anchor{library/asyncio-future asyncio wrap_future}@anchor{1852}
@deffn {Fonction} asyncio.wrap_future (future, *, loop=None)

Encapsule un objet @ref{118f,,concurrent.futures.Future} dans un objet @ref{bbb,,asyncio.Future}.


Obsolète depuis la version 3.10: Un @code{DeprecationWarning} est levé si `future' n'est pas un objet se comportant comme un `Future', si `loop' n'est pas spécifié et s'il n'y a pas de boucle d'évènements en cours d'exécution.

@end deffn

@node Objet Future,,Fonctions pour Future,Futures
@anchor{library/asyncio-future future-object}@anchor{32d3}
@subsubsection Objet `Future'


@geindex Future (classe dans asyncio)
@anchor{library/asyncio-future asyncio Future}@anchor{bbb}
@deffn {Classe} asyncio.Future (*, loop=None)

Un `Future' représente le résultat final d'une opération asynchrone. Il n'est pas conçu pour pouvoir être utilisé par plusieurs fils d'exécution.

`Future' est un objet qui peut être attendu (@ref{1ab,,awaitable}). Les coroutines peuvent attendre les objets `Future' jusqu'à ce qu'ils renvoient un résultat, ils lèvent une exception ou qu'ils soient annulés. Un `Future' peut être attendu plusieurs fois et le résultat est le même.

Les `Futures' sont habituellement utilisés pour permettre à du code bas niveau basé sur des fonctions de rappel (par exemple : les protocoles utilisant `asyncio' @ref{31db,,transports}) d'interagir avec du code haut niveau utilisant `async' et `await'.

Une bonne règle empirique est de ne jamais exposer des objets `Future' dans des `API' destinées à l'utilisateur. La façon privilégiée de créer des objets `Future' est d'appeler la méthode @ref{c67,,loop.create_future()}. Cela permet aux implémentations alternatives de la boucle d'évènements d'utiliser leur propre implémentation de l'objet `Future'.


Modifié dans la version 3.7: Ajout du support du module @ref{24,,contextvars}.



Obsolète depuis la version 3.10: Un @code{DeprecationWarning} est levé si `loop' n'est pas spécifié et s'il n'y a pas de boucle d'évènements en cours d'exécution.


@geindex result() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future result}@anchor{32d4}
@deffn {Méthode} result ()

Renvoie le résultat du `Future'.

Si le `Future' est « terminé » et a un résultat défini par la méthode @ref{3206,,set_result()}, ce résultat est renvoyé.

Si le `Future' est « terminé » et a une exception définie par la méthode @ref{3207,,set_exception()}, cette méthode lève l'exception.

Si le `Future' a été `annulé', cette méthode lève une exception @ref{1b6,,CancelledError}.

If the Future's result isn't yet available, this method raises
an @ref{320a,,InvalidStateError} exception.
@end deffn

@geindex set_result() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future set_result}@anchor{3206}
@deffn {Méthode} set_result (result)

Marque le `Future' comme « terminé » et définit son résultat.

Raises an @ref{320a,,InvalidStateError} error if the Future is
already `done'.
@end deffn

@geindex set_exception() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future set_exception}@anchor{3207}
@deffn {Méthode} set_exception (exception)

Marque le `Future' comme « terminé » et définit une exception.

Raises an @ref{320a,,InvalidStateError} error if the Future is
already `done'.
@end deffn

@geindex done() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future done}@anchor{32d5}
@deffn {Méthode} done ()

Renvoie @code{True} si le `Future' est « terminé ».

Un `Future' est « terminé » s'il a été « annulé » ou si un résultat ou une exception a été définie par les méthodes @ref{3206,,set_result()} ou @ref{3207,,set_exception()}.
@end deffn

@geindex cancelled() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future cancelled}@anchor{32d6}
@deffn {Méthode} cancelled ()

Renvoie @code{True} si le `Future' a été « annulé ».

Cette méthode est habituellement utilisée pour vérifier qu'un `Future' n'est pas « annulé » avant de définir un résultat ou une exception pour celui-ci :

@example
if not fut.cancelled():
    fut.set_result(42)
@end example
@end deffn

@geindex add_done_callback() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future add_done_callback}@anchor{af6}
@deffn {Méthode} add_done_callback (callback, *, context=None)

Ajoute une fonction de rappel à exécuter lorsque le `Future' est « terminé ».

L'argument `callback' est appelé avec l'objet `Future' comme seul argument.

Si le `Future' est déjà « terminé » lorsque la méthode est appelée, l'exécution de la fonction de rappel est planifiée avec @ref{af2,,loop.call_soon()}.

L'argument nommé optionnel `context' permet de spécifier une classe @ref{152f,,contextvars.Context} personnalisée dans laquelle la fonction de rappel s’exécutera. Le contexte actuel est utilisé si `context' n'est pas fourni.

@ref{40a,,functools.partial()} peut être utilisée pour passer des paramètres à la fonction de rappel :

@example
# Call 'print("Future:", fut)' when "fut" is done.
fut.add_done_callback(
    functools.partial(print, "Future:"))
@end example


Modifié dans la version 3.7: Ajout de l'argument nommé `context'. Voir 
@geindex Python Enhancement Proposals; PEP 567
PEP 567@footnote{https://peps.python.org/pep-0567/} pour plus de détails.

@end deffn

@geindex remove_done_callback() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future remove_done_callback}@anchor{152b}
@deffn {Méthode} remove_done_callback (callback)

Retire `callback' de la liste de fonctions de rappel.

Renvoie le nombre de fonctions de rappel retiré. La méthode renvoie généralement 1, à moins que la fonction ait été ajoutée plus d'une fois.
@end deffn

@geindex cancel() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future cancel}@anchor{17a8}
@deffn {Méthode} cancel (msg=None)

Annule le `Future' et planifie l'exécution des fonctions de rappel.

Si le `Future' est déjà « terminé » ou « annulé », renvoie @code{False}. Autrement, change l'état du `Future' à « annulé », planifie l'exécution des fonctions de rappel et renvoie @code{True}.


Modifié dans la version 3.9: Ajout du paramètre `msg'.

@end deffn

@geindex exception() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future exception}@anchor{32d7}
@deffn {Méthode} exception ()

Renvoie l'exception définie pour ce `Future'.

L'exception, ou @code{None} si aucune exception n'a été définie, est renvoyé seulement si le `Future' est « terminé ».

Si le `Future' a été `annulé', cette méthode lève une exception @ref{1b6,,CancelledError}.

Si le `Future' n'est pas encore « terminé », cette méthode lève une exception @ref{320a,,InvalidStateError}.
@end deffn

@geindex get_loop() (méthode asyncio.Future)
@anchor{library/asyncio-future asyncio Future get_loop}@anchor{afe}
@deffn {Méthode} get_loop ()

Renvoie la boucle d'évènements à laquelle le `Future' est attaché.


Ajouté dans la version 3.7.

@end deffn
@end deffn
@anchor{library/asyncio-future asyncio-example-future}@anchor{32d8}
Cet exemple crée un objet `Future', puis crée et planifie l’exécution d'une tâche asynchrone qui définira le résultat du `Future' et attend jusqu'à ce que le `Future' ait un résultat :

@example
async def set_after(fut, delay, value):
    # Sleep for *delay* seconds.
    await asyncio.sleep(delay)

    # Set *value* as a result of *fut* Future.
    fut.set_result(value)

async def main():
    # Get the current event loop.
    loop = asyncio.get_running_loop()

    # Create a new Future object.
    fut = loop.create_future()

    # Run "set_after()" coroutine in a parallel Task.
    # We are using the low-level "loop.create_task()" API here because
    # we already have a reference to the event loop at hand.
    # Otherwise we could have just used "asyncio.create_task()".
    loop.create_task(
        set_after(fut, 1, '... world'))

    print('hello ...')

    # Wait until *fut* has a result (1 second) and print it.
    print(await fut)

asyncio.run(main())
@end example

@cartouche
@quotation Important 
L'objet `Future' est conçu pour imiter la classe @ref{118f,,concurrent.futures.Future}. Les principales différences sont :


@itemize -

@item 
contrairement au `Future asyncio', les instances de @ref{118f,,concurrent.futures.Future} ne peuvent pas être attendues ;

@item 
@ref{32d4,,asyncio.Future.result()} et @ref{32d7,,asyncio.Future.exception()} n'acceptent pas d'argument `timeout' ;

@item 
@ref{32d4,,asyncio.Future.result()} et @ref{32d7,,asyncio.Future.exception()} lèvent une exception @ref{320a,,InvalidStateError} lorsque le `Future' n'est pas « terminé » ;

@item 
les fonctions de rappel enregistrées à l'aide de @ref{af6,,asyncio.Future.add_done_callback()} ne sont pas exécutées immédiatement mais planifiées avec @ref{af2,,loop.call_soon()} ;

@item 
les `Future asyncio' ne sont pas compatibles avec les fonctions @ref{17f0,,concurrent.futures.wait()} et @ref{15d6,,concurrent.futures.as_completed()} ;

@item 
@ref{17a8,,asyncio.Future.cancel()} accepts an optional @code{msg} argument,
but @ref{3132,,concurrent.futures.Future.cancel()} does not.
@end itemize
@end quotation
@end cartouche

@node Transports et Protocoles,Politiques,Futures,asyncio --- Asynchronous I/O
@anchor{library/asyncio-protocol doc}@anchor{32d9}@anchor{library/asyncio-protocol asyncio-transports-protocols}@anchor{31db}@anchor{library/asyncio-protocol transports-and-protocols}@anchor{32da}
@subsubsection Transports et Protocoles


@subsubheading Préface


Les transports et les protocoles sont utilisés par les API de boucle d'événements `de bas niveau' telles que @ref{5ee,,loop.create_connection()}. Ils utilisent un style de programmation basé sur les fonctions de rappel et permettent des implémentations hautes performances de protocoles réseau (par exemple, HTTP) ou de communication inter-processus (`IPC').

Avant tout, les transports et les protocoles ne doivent être utilisés que dans des bibliothèques et des cadriciels et jamais dans des applications asynchrones de haut niveau.

Cette page de documentation couvre à la fois @ref{32db,,Transports} et @ref{32dc,,Protocoles}.

@subsubheading Introduction


Au plus haut niveau, le transport concerne `comment' les octets sont transmis, tandis que le protocole détermine `quels' octets transmettre (et dans une certaine mesure quand).

Pour l'écrire autrement : un transport est une abstraction pour un connecteur (`socket' ou tout autre point de terminaison d'entrée-sortie) tandis qu'un protocole est une abstraction pour une application, du point de vue du transport.

Encore une autre vue est que les interfaces de transport et de protocole définissent ensemble une interface abstraite pour utiliser les entrées-sorties réseau et les entrées-sorties inter-processus.

Il existe toujours une relation 1:1 entre les objets de transport et de protocole : le protocole appelle les méthodes de transport pour envoyer des données, tandis que le transport appelle les méthodes de protocole pour lui transmettre les données reçues.

La plupart des méthodes de boucles d'événements orientées connexion (telles que @ref{5ee,,loop.create_connection()}) acceptent généralement un argument `protocol_factory' utilisé pour créer un objet `Protocol' pour une connexion acceptée, représentée par un objet `Transport'. De telles méthodes renvoient généralement un `n'-uplet @code{(transport, protocol)}.

@subsubheading Sommaire


Cette page de documentation contient les sections suivantes :


@itemize *

@item 
La section @ref{32db,,Transports} documente les classes `asyncio' @ref{32dd,,BaseTransport}, @ref{32b4,,ReadTransport}, @ref{32b5,,WriteTransport}, @ref{32de,,Transport}, @ref{173a,,DatagramTransport} et @ref{32c2,,SubprocessTransport}.

@item 
La section @ref{32dc,,Protocols} documente les classes `asyncio' @ref{32df,,BaseProtocol}, @ref{32e0,,Protocol}, @ref{a8b,,BufferedProtocol}, @ref{6b9,,DatagramProtocol} et @ref{32c1,,SubprocessProtocol}.

@item 
La section @ref{32e1,,Examples} montre comment utiliser les transports, les protocoles et les API de boucle d'événements de bas niveau.
@end itemize

@menu
* Transports:: 
* Protocoles:: 
* Exemples: Exemples<19>. 

@end menu

@node Transports,Protocoles,,Transports et Protocoles
@anchor{library/asyncio-protocol asyncio-transport}@anchor{32a0}@anchor{library/asyncio-protocol transports}@anchor{32db}
@subsubsection Transports


`Code source :' Lib/asyncio/transports.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/transports.py}


__________________________________________________________________


Les transports sont des classes fournies par @ref{a,,asyncio} afin d'abstraire différents types de canaux de communication.

Les objets de transport sont toujours instanciés par une @ref{d66,,boucle d'événements asyncio}.

`asyncio' implémente les transports pour TCP, UDP, SSL et les tubes de sous-processus. Les méthodes disponibles sur un transport dépendent du type de transport.

Les classes de transport ne sont @ref{3202,,pas compatibles avec les fils d'exécution multiples}.

@menu
* Hiérarchie des transports:: 
* Classe de base des Transports:: 
* Transports en lecture seule:: 
* Transports en lecture-écriture:: 
* Transports par datagrammes:: 
* Transports entre sous-processus:: 

@end menu

@node Hiérarchie des transports,Classe de base des Transports,,Transports
@anchor{library/asyncio-protocol transports-hierarchy}@anchor{32e2}
@subsubsection Hiérarchie des transports


@geindex BaseTransport (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio BaseTransport}@anchor{32dd}
@deffn {Classe} asyncio.BaseTransport

Classe de base pour tous les transports. Contient des méthodes partagées par tous les transports `asyncio'.
@end deffn

@geindex WriteTransport (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio WriteTransport}@anchor{32b5}
@deffn {Classe} asyncio.WriteTransport (BaseTransport)

Transport de base pour les connexions en écriture seule.

Les instances de la classe `WriteTransport' sont renvoyées par la méthode de boucle d'événements @ref{325c,,loop.connect_write_pipe()} et sont également utilisées par les méthodes liées aux sous-processus comme @ref{3258,,loop.subprocess_exec()}.
@end deffn

@geindex ReadTransport (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio ReadTransport}@anchor{32b4}
@deffn {Classe} asyncio.ReadTransport (BaseTransport)

Transport de base pour les connexions en lecture seule.

Les instances de la classe `ReadTransport' sont renvoyées par la méthode de boucle d'événements @ref{325b,,loop.connect_read_pipe()} et sont également utilisées par les méthodes liées aux sous-processus comme @ref{3258,,loop.subprocess_exec()}.
@end deffn

@geindex Transport (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio Transport}@anchor{32de}
@deffn {Classe} asyncio.Transport (WriteTransport, ReadTransport)

Interface représentant un transport bidirectionnel, comme une connexion TCP.

L'utilisateur n'instancie pas un transport directement ; il appelle une fonction utilitaire, lui transmettant une fabrique de protocoles et d'autres informations nécessaires pour créer le transport et le protocole.

Les instances de la classe `Transport' sont renvoyées ou utilisées par des méthodes de boucle d'événements comme @ref{5ee,,loop.create_connection()}, @ref{3218,,loop.create_unix_connection()}, @ref{b01,,loop.create_server()}, @ref{32aa,,loop.sendfile()}, etc.
@end deffn

@geindex DatagramTransport (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio DatagramTransport}@anchor{173a}
@deffn {Classe} asyncio.DatagramTransport (BaseTransport)

Transport pour les connexions par datagrammes (UDP).

Les instances de la classe `DatagramTransport' sont renvoyées par la méthode de boucle d'événements @ref{71d,,loop.create_datagram_endpoint()}.
@end deffn

@geindex SubprocessTransport (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio SubprocessTransport}@anchor{32c2}
@deffn {Classe} asyncio.SubprocessTransport (BaseTransport)

Abstraction pour représenter une connexion entre un parent et son processus enfant au niveau du système d'exploitation.

Les instances de la classe `SubprocessTransport' sont renvoyées par les méthodes de boucle d'événements @ref{3259,,loop.subprocess_shell()} et @ref{3258,,loop.subprocess_exec()}.
@end deffn

@node Classe de base des Transports,Transports en lecture seule,Hiérarchie des transports,Transports
@anchor{library/asyncio-protocol base-transport}@anchor{32e3}
@subsubsection Classe de base des Transports


@geindex close() (méthode asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport close}@anchor{32a3}
@deffn {Méthode} BaseTransport.close ()

Ferme le transport.

Si le transport a une mémoire tampon pour les données sortantes, les données mises en mémoire tampon seront vidées de manière asynchrone. Aucune autre donnée ne sera reçue. Une fois que toutes les données mises en mémoire tampon ont été vidées, la méthode @ref{32e4,,protocol.connection_lost()} sera appelée avec @ref{660,,None} comme argument. Le transport ne doit pas être utilisé une fois qu'il est fermé.
@end deffn

@geindex is_closing() (méthode asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport is_closing}@anchor{c66}
@deffn {Méthode} BaseTransport.is_closing ()

Renvoie @code{True} si le transport se ferme ou est fermé.
@end deffn

@geindex get_extra_info() (méthode asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport get_extra_info}@anchor{a8a}
@deffn {Méthode} BaseTransport.get_extra_info (name, default=None)

Renvoie des informations sur le transport ou les ressources sous-jacentes qu'il utilise.

`name' est une chaîne représentant l'information spécifique au transport à obtenir.

`default' est la valeur à renvoyer si les informations ne sont pas disponibles ou si le transport ne prend pas en charge l'implémentation de boucle d'événements tierce donnée ou la plateforme actuelle.

Par exemple, le code suivant tente d'obtenir l'objet `socket' sous-jacent du transport :

@example
sock = transport.get_extra_info('socket')
if sock is not None:
    print(sock.getsockopt(...))
@end example

Catégories d'informations pouvant être interrogées sur certains transports :


@itemize *

@item 
`socket' :


@itemize -

@item 
@code{'peername'} : l'adresse distante à laquelle le `socket' est connecté, résultat de @ref{32e5,,socket.socket.getpeername()} (@code{None} en cas d'erreur)

@item 
@code{'socket'} : Instance de @ref{d8e,,socket.socket}

@item 
@code{'sockname'} : la propre adresse du connecteur, résultat de @ref{32e6,,socket.socket.getsockname()}
@end itemize

@item 
Connecteur (`socket') SSL :


@itemize -

@item 
@code{'compression'} : l'algorithme de compression utilisé (chaîne de caractères), ou @code{None} si la connexion n'est pas compressée ; résultat de @ref{1125,,ssl.SSLSocket.compression()}

@item 
@code{'cipher'} : un `n'-uplet à trois valeurs contenant le nom du chiffrement utilisé, la version du protocole SSL qui définit son utilisation et le nombre de bits secrets utilisés ; résultat de @ref{32e7,,ssl.SSLSocket.cipher()}

@item 
@code{'peercert'} : certificat du pair ; résultat de @ref{fa2,,ssl.SSLSocket.getpeercert()}

@item 
@code{sslcontext'} : instance de @ref{291,,ssl.SSLContext}

@item 
@code{'ssl_object'} : instance de @ref{b6f,,ssl.SSLObject} ou de @ref{8d7,,ssl.SSLSocket}
@end itemize

@item 
tube :


@itemize -

@item 
@code{'pipe'} : objet `pipe'
@end itemize

@item 
sous-processus :


@itemize -

@item 
@code{'sous-processus'} : instance de @ref{197,,subprocess.Popen}
@end itemize
@end itemize
@end deffn

@geindex set_protocol() (méthode asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport set_protocol}@anchor{32e8}
@deffn {Méthode} BaseTransport.set_protocol (protocol)

Change le protocole.

La commutation de protocole ne doit être effectuée que lorsque les deux protocoles sont documentés pour prendre en charge la commutation.
@end deffn

@geindex get_protocol() (méthode asyncio.BaseTransport)
@anchor{library/asyncio-protocol asyncio BaseTransport get_protocol}@anchor{32e9}
@deffn {Méthode} BaseTransport.get_protocol ()

Renvoie le protocole courant.
@end deffn

@node Transports en lecture seule,Transports en lecture-écriture,Classe de base des Transports,Transports
@anchor{library/asyncio-protocol read-only-transports}@anchor{32ea}
@subsubsection Transports en lecture seule


@geindex is_reading() (méthode asyncio.ReadTransport)
@anchor{library/asyncio-protocol asyncio ReadTransport is_reading}@anchor{b0a}
@deffn {Méthode} ReadTransport.is_reading ()

Renvoie @code{True} si le transport reçoit de nouvelles données.


Ajouté dans la version 3.7.

@end deffn

@geindex pause_reading() (méthode asyncio.ReadTransport)
@anchor{library/asyncio-protocol asyncio ReadTransport pause_reading}@anchor{b0c}
@deffn {Méthode} ReadTransport.pause_reading ()

Met en pause l'extrémité de réception du transport. Aucune donnée ne sera transmise à la méthode @ref{171b,,protocol.data_received()} du protocole jusqu'à ce que @ref{b0b,,resume_reading()} soit appelée.


Modifié dans la version 3.7: la méthode est idempotente, c'est-à-dire qu'elle peut être appelée lorsque le transport est déjà en pause ou fermé.

@end deffn

@geindex resume_reading() (méthode asyncio.ReadTransport)
@anchor{library/asyncio-protocol asyncio ReadTransport resume_reading}@anchor{b0b}
@deffn {Méthode} ReadTransport.resume_reading ()

Reprend la réception. La méthode @ref{171b,,protocol.data_received()} du protocole sera appelée à nouveau si certaines données sont disponibles pour la lecture.


Modifié dans la version 3.7: la méthode est idempotente, c'est-à-dire qu'elle peut être appelée alors que le transport est déjà en train de lire.

@end deffn

@node Transports en lecture-écriture,Transports par datagrammes,Transports en lecture seule,Transports
@anchor{library/asyncio-protocol write-only-transports}@anchor{32eb}
@subsubsection Transports en lecture-écriture


@geindex abort() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport abort}@anchor{32c5}
@deffn {Méthode} WriteTransport.abort ()

Ferme le transport immédiatement, sans attendre la fin des opérations en attente. Les données mises en mémoire tampon sont perdues. Aucune autre donnée ne sera reçue. La méthode @ref{32e4,,protocol.connection_lost()} du protocole sera éventuellement appelée avec @ref{660,,None} comme argument.
@end deffn

@geindex can_write_eof() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport can_write_eof}@anchor{32ec}
@deffn {Méthode} WriteTransport.can_write_eof ()

Renvoie @ref{bfb,,True} si le transport gère @ref{32ed,,write_eof()}, @ref{b25,,False} sinon.
@end deffn

@geindex get_write_buffer_size() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport get_write_buffer_size}@anchor{32ee}
@deffn {Méthode} WriteTransport.get_write_buffer_size ()

Renvoie la taille actuelle du tampon de sortie utilisé par le transport.
@end deffn

@geindex get_write_buffer_limits() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport get_write_buffer_limits}@anchor{db2}
@deffn {Méthode} WriteTransport.get_write_buffer_limits ()

Obtient les seuils `high' et `low' pour le contrôle du flux d'écriture. Renvoie un `n'-uplet @code{(low, high)} où `low' et `high' sont des nombres positifs d'octets.

Utilisez @ref{32ef,,set_write_buffer_limits()} pour définir les limites.


Ajouté dans la version 3.4.2.

@end deffn

@geindex set_write_buffer_limits() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport set_write_buffer_limits}@anchor{32ef}
@deffn {Méthode} WriteTransport.set_write_buffer_limits (high=None, low=None)

Définit les seuils `high' et `low' pour le contrôle du flux d'écriture.

Ces deux valeurs (mesurées en nombre d'octets) contrôlent quand les méthodes @ref{32f0,,protocol.pause_writing()} et @ref{32f1,,protocol.resume_writing()} du protocole sont appelées. S'il est spécifié, le seuil bas doit être inférieur ou égal au seuil haut. Ni `high' ni `low' ne peuvent être négatifs.

@ref{32f0,,pause_writing()} est appelée lorsque la taille du tampon devient supérieure ou égale à la valeur `high'. Si l'écriture a été interrompue, @ref{32f1,,resume_writing()} est appelée lorsque la taille du tampon devient inférieure ou égale à la valeur `low'.

Les valeurs par défaut sont spécifiques à l'implémentation. Si seul le seuil supérieur est donné, le seuil bas prend par défaut une valeur spécifique à l'implémentation inférieure ou égale au seuil supérieur. Définir `high' sur zéro force également `low' sur zéro et provoque l'appel de @ref{32f0,,pause_writing()} chaque fois que le tampon devient non vide. Définir `low' sur zéro entraîne l'appel de @ref{32f1,,resume_writing()} uniquement une fois que le tampon est vide. L'utilisation de zéro pour l'un ou l'autre seuil est généralement sous-optimal car cela réduit les possibilités d'effectuer des entrées-sorties et des calculs simultanément.

Utilisez @ref{db2,,get_write_buffer_limits()} pour obtenir les limites.
@end deffn

@geindex write() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport write}@anchor{32f2}
@deffn {Méthode} WriteTransport.write (data)

Écrit des octets de `data' sur le transport.

Cette méthode ne bloque pas ; elle met les données en mémoire tampon et s'arrange pour qu'elles soient envoyées de manière asynchrone.
@end deffn

@geindex writelines() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport writelines}@anchor{150a}
@deffn {Méthode} WriteTransport.writelines (list_of_data)

Écrit une liste (ou tout itérable) d'octets de données dans le transport. Ceci est fonctionnellement équivalent à appeler @ref{32f2,,write()} sur chaque élément produit par l'itérable, mais peut être implémentée plus efficacement.
@end deffn

@geindex write_eof() (méthode asyncio.WriteTransport)
@anchor{library/asyncio-protocol asyncio WriteTransport write_eof}@anchor{32ed}
@deffn {Méthode} WriteTransport.write_eof ()

Ferme l'extrémité d'écriture du transport après avoir vidé toutes les données mises en mémoire tampon. Des données peuvent encore être reçues.

Cette méthode peut lever @ref{225,,NotImplementedError} si le transport (par exemple SSL) ne prend pas en charge les connexions semi-fermées.
@end deffn

@node Transports par datagrammes,Transports entre sous-processus,Transports en lecture-écriture,Transports
@anchor{library/asyncio-protocol datagram-transports}@anchor{32f3}
@subsubsection Transports par datagrammes


@geindex sendto() (méthode asyncio.DatagramTransport)
@anchor{library/asyncio-protocol asyncio DatagramTransport sendto}@anchor{1ad}
@deffn {Méthode} DatagramTransport.sendto (data, addr=None)

Envoie les octets `data' au pair distant indiqué par `addr' (une adresse cible dépendante du transport). Si `addr' est @ref{660,,None}, les données sont envoyées à l'adresse cible indiquée lors de la création du transport.

Cette méthode ne bloque pas ; elle met les données en mémoire tampon et s'arrange pour qu'elles soient envoyées de manière asynchrone.


Modifié dans la version 3.13: This method can be called with an empty bytes object to send a
zero-length datagram. The buffer size calculation used for flow
control is also updated to account for the datagram header.

@end deffn

@geindex abort() (méthode asyncio.DatagramTransport)
@anchor{library/asyncio-protocol asyncio DatagramTransport abort}@anchor{32f4}
@deffn {Méthode} DatagramTransport.abort ()

Ferme le transport immédiatement, sans attendre la fin des opérations en attente. Les données mises en mémoire tampon sont perdues. Aucune autre donnée ne sera reçue. La méthode @ref{32e4,,protocol.connection_lost()} du protocole sera éventuellement appelée avec @ref{660,,None} comme argument.
@end deffn

@node Transports entre sous-processus,,Transports par datagrammes,Transports
@anchor{library/asyncio-protocol asyncio-subprocess-transports}@anchor{325d}@anchor{library/asyncio-protocol subprocess-transports}@anchor{32f5}
@subsubsection Transports entre sous-processus


@geindex get_pid() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_pid}@anchor{32f6}
@deffn {Méthode} SubprocessTransport.get_pid ()

Renvoie l'identifiant du sous processus sous la forme d'un nombre entier.
@end deffn

@geindex get_pipe_transport() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_pipe_transport}@anchor{32f7}
@deffn {Méthode} SubprocessTransport.get_pipe_transport (fd)

Renvoie le transport pour le canal de communication correspondant au descripteur de fichier `fd' donné sous forme d'un entier :


@itemize *

@item 
@code{0} : transport de flux en lecture de l'entrée standard (`stdin'), ou @ref{660,,None} si le sous-processus n'a pas été créé avec @code{stdin=PIPE}

@item 
@code{1} : transport de flux en écriture de la sortie standard (`stdout'), ou @ref{660,,None} si le sous-processus n'a pas été créé avec @code{stdout=PIPE}

@item 
@code{2} : transport de flux en écriture de l'erreur standard (`stderr'), ou @ref{660,,None} si le sous-processus n'a pas été créé avec @code{stderr=PIPE}

@item 
autre `fd' : @ref{660,,None}
@end itemize
@end deffn

@geindex get_returncode() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport get_returncode}@anchor{32f8}
@deffn {Méthode} SubprocessTransport.get_returncode ()

Renvoie le code de retour du sous-processus sous la forme d'un entier ou @ref{660,,None} s'il n'a pas été renvoyé, ce qui est similaire à l'attribut @ref{1936,,subprocess.Popen.returncode}.
@end deffn

@geindex kill() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport kill}@anchor{32f9}
@deffn {Méthode} SubprocessTransport.kill ()

Tue le sous-processus.

Sur les systèmes POSIX, la fonction envoie SIGKILL au sous-processus. Sous Windows, cette méthode est un alias pour @ref{32fa,,terminate()}.

Voir aussi @ref{1394,,subprocess.Popen.kill()}.
@end deffn

@geindex send_signal() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport send_signal}@anchor{32fb}
@deffn {Méthode} SubprocessTransport.send_signal (signal)

Envoie le numéro de `signal' au sous-processus, comme dans @ref{1395,,subprocess.Popen.send_signal()}.
@end deffn

@geindex terminate() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport terminate}@anchor{32fa}
@deffn {Méthode} SubprocessTransport.terminate ()

Termine le sous-processus.

On POSIX systems, this method sends @ref{1396,,SIGTERM} to the subprocess.
On Windows, the Windows API function @code{TerminateProcess()} is called to
stop the subprocess.

Voir aussi @ref{1393,,subprocess.Popen.terminate()}.
@end deffn

@geindex close() (méthode asyncio.SubprocessTransport)
@anchor{library/asyncio-protocol asyncio SubprocessTransport close}@anchor{32fc}
@deffn {Méthode} SubprocessTransport.close ()

Tue le sous-processus en appelant la méthode @ref{32f9,,kill()}.

Si le sous-processus n'est pas encore terminé, ferme les transports des tubes `stdin', `stdout' et `stderr'.
@end deffn

@node Protocoles,Exemples<19>,Transports,Transports et Protocoles
@anchor{library/asyncio-protocol asyncio-protocol}@anchor{329f}@anchor{library/asyncio-protocol protocols}@anchor{32dc}
@subsubsection Protocoles


`Code source :' Lib/asyncio/protocols.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/protocols.py}


__________________________________________________________________


`asyncio' fournit un ensemble de classes mères abstraites qui doivent être utilisées pour implémenter des protocoles réseau. Ces classes sont destinées à être utilisées avec les @ref{32a0,,transports}.

Les sous-classes des classes mères abstraites de protocole peuvent implémenter certaines ou toutes les méthodes. Toutes ces méthodes sont des rappels : elles sont appelées par des transports sur certains événements, par exemple lors de la réception de certaines données. Une méthode de protocole de base doit être appelée par le transport correspondant.

@menu
* Protocoles de base:: 
* Protocoles de base: Protocoles de base<2>. 
* Protocoles connectés:: 
* Protocoles connectés avec tampon:: 
* Protocoles par datagrammes (non connectés): Protocoles par datagrammes non connectés. 
* Protocoles liés aux sous-processus:: 

@end menu

@node Protocoles de base,Protocoles de base<2>,,Protocoles
@anchor{library/asyncio-protocol base-protocols}@anchor{32fd}
@subsubsection Protocoles de base


@geindex BaseProtocol (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio BaseProtocol}@anchor{32df}
@deffn {Classe} asyncio.BaseProtocol

Protocole de base avec des méthodes partagées par tous les protocoles.
@end deffn

@geindex Protocol (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio Protocol}@anchor{32e0}
@deffn {Classe} asyncio.Protocol (BaseProtocol)

Classe mère pour l'implémentation des protocoles de streaming (TCP, sockets Unix, etc.).
@end deffn

@geindex BufferedProtocol (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio BufferedProtocol}@anchor{a8b}
@deffn {Classe} asyncio.BufferedProtocol (BaseProtocol)

Classe mère pour implémenter des protocoles de streaming avec contrôle manuel du tampon de réception.
@end deffn

@geindex DatagramProtocol (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio DatagramProtocol}@anchor{6b9}
@deffn {Classe} asyncio.DatagramProtocol (BaseProtocol)

Classe mère pour l'implémentation des protocoles par datagrammes (UDP).
@end deffn

@geindex SubprocessProtocol (classe dans asyncio)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol}@anchor{32c1}
@deffn {Classe} asyncio.SubprocessProtocol (BaseProtocol)

Classe mère pour implémenter des protocoles communiquant avec des processus enfants (canaux unidirectionnels).
@end deffn

@node Protocoles de base<2>,Protocoles connectés,Protocoles de base,Protocoles
@anchor{library/asyncio-protocol base-protocol}@anchor{32fe}
@subsubsection Protocoles de base


Tous les protocoles asynchrones peuvent implémenter des rappels pour les protocoles de base.

@subsubheading Rappels pour les connexions


Les méthodes de rappel pour les connexions concernent tous les protocoles, exactement une fois par connexion réussie. Tous les autres rappels de protocole ne peuvent être appelés qu'entre ces deux méthodes.

@geindex connection_made() (méthode asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol connection_made}@anchor{32a1}
@deffn {Méthode} BaseProtocol.connection_made (transport)

Appelée lorsqu'une connexion est établie.

L'argument `transport' est le transport représentant la connexion. Le protocole est chargé de stocker la référence à son transport.
@end deffn

@geindex connection_lost() (méthode asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol connection_lost}@anchor{32e4}
@deffn {Méthode} BaseProtocol.connection_lost (exc)

Appelée lorsqu'une connexion est perdue ou fermée.

L'argument est soit un objet exception soit @ref{660,,None}. Ce dernier signifie qu'un EOF régulier est reçu, ou que la connexion a été interrompue ou fermée par ce côté de la connexion.
@end deffn

@subsubheading Rappels pour le contrôle de flux


Les méthodes de rappel pour le contrôle de flux concernent les transports et sont utilisés pour suspendre ou reprendre l'écriture effectuée par le protocole.

Voir la documentation de la méthode @ref{32ef,,set_write_buffer_limits()} pour plus de détails.

@geindex pause_writing() (méthode asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol pause_writing}@anchor{32f0}
@deffn {Méthode} BaseProtocol.pause_writing ()

Appelée lorsque la mémoire tampon du transport dépasse la limite supérieure.
@end deffn

@geindex resume_writing() (méthode asyncio.BaseProtocol)
@anchor{library/asyncio-protocol asyncio BaseProtocol resume_writing}@anchor{32f1}
@deffn {Méthode} BaseProtocol.resume_writing ()

Appelée lorsque la mémoire tampon du transport passe sous le seuil bas.
@end deffn

Si la taille du tampon est égale au seuil haut, @ref{32f0,,pause_writing()} n'est pas appelée : la taille du tampon doit être strictement supérieure.

Inversement, @ref{32f1,,resume_writing()} est appelée lorsque la taille du tampon est égale ou inférieure au seuil bas. Ces conditions de fin sont importantes pour s'assurer que les choses se déroulent comme prévu lorsque l'un ou l'autre seuil est à zéro.

@node Protocoles connectés,Protocoles connectés avec tampon,Protocoles de base<2>,Protocoles
@anchor{library/asyncio-protocol streaming-protocols}@anchor{32ff}
@subsubsection Protocoles connectés


Les méthodes d'événement, telles que @ref{b01,,loop.create_server()}, @ref{1ac,,loop.create_unix_server()}, @ref{5ee,,loop.create_connection()}, @ref{3218,,loop.create_unix_connection()}, @ref{b08,,loop.connect_accepted_socket()}, @ref{325b,,loop.connect_read_pipe()} et @ref{325c,,loop.connect_write_pipe()} acceptent les fabriques qui renvoient des protocoles connectés.

@geindex data_received() (méthode asyncio.Protocol)
@anchor{library/asyncio-protocol asyncio Protocol data_received}@anchor{171b}
@deffn {Méthode} Protocol.data_received (data)

Appelée lorsque certaines données sont reçues. `data' est un objet bytes non vide contenant les données entrantes.

Le fait que les données soient mises en mémoire tampon, fragmentées ou réassemblées dépend du transport. En général, vous ne devez pas vous fier à une sémantique spécifique et plutôt rendre votre analyse générique et flexible. Cependant, les données sont toujours reçues dans le bon ordre.

La méthode peut être appelée un nombre arbitraire de fois lorsqu'une connexion est ouverte.

Cependant, @ref{3300,,protocol.eof_received()} est appelée au plus une fois. Une fois que @code{eof_received()} est appelée, @code{data_received()} n'est plus appelée.
@end deffn

@geindex eof_received() (méthode asyncio.Protocol)
@anchor{library/asyncio-protocol asyncio Protocol eof_received}@anchor{3300}
@deffn {Méthode} Protocol.eof_received ()

Appelée lorsque l'autre extrémité signale qu'il n'enverra plus de données (par exemple en appelant @ref{32ed,,transport.write_eof()}, si l'autre extrémité utilise également `asyncio').

Cette méthode peut renvoyer une valeur évaluée à faux (y compris @code{None}), auquel cas le transport se ferme de lui-même. À l'inverse, si cette méthode renvoie une valeur évaluée à vrai, le protocole utilisé détermine s'il faut fermer le transport. Puisque l'implémentation par défaut renvoie @code{None}, elle ferme implicitement la connexion.

Certains transports, y compris SSL, ne prennent pas en charge les connexions semi-fermées, auquel cas renvoyer `True' à partir de cette méthode entraîne la fermeture de la connexion.
@end deffn

Machine à états :

@example
start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end
@end example

@node Protocoles connectés avec tampon,Protocoles par datagrammes non connectés,Protocoles connectés,Protocoles
@anchor{library/asyncio-protocol buffered-streaming-protocols}@anchor{3301}
@subsubsection Protocoles connectés avec tampon



Ajouté dans la version 3.7.


Les protocoles avec mise en mémoire tampon peuvent être utilisés avec n'importe quelle méthode de boucle d'événements prenant en charge les @ref{32ff,,protocoles connectés}.

Les implémentations de @code{BufferedProtocol} permettent une allocation et un contrôle manuels explicites du tampon de réception. Les boucles d'événements peuvent alors utiliser le tampon fourni par le protocole pour éviter les copies de données inutiles. Cela peut entraîner une amélioration notable des performances pour les protocoles qui reçoivent de grandes quantités de données. Des implémentations de protocole sophistiquées peuvent réduire considérablement le nombre d'allocations de mémoire tampon.

Les méthodes de rappel suivantes sont appelées sur les instances @ref{a8b,,BufferedProtocol} :

@geindex get_buffer() (méthode asyncio.BufferedProtocol)
@anchor{library/asyncio-protocol asyncio BufferedProtocol get_buffer}@anchor{3302}
@deffn {Méthode} BufferedProtocol.get_buffer (sizehint)

Appelée pour allouer un nouveau tampon de réception.

`sizehint' est la taille minimale recommandée pour le tampon renvoyé. Il est acceptable de renvoyer des tampons plus petits ou plus grands que ce que suggère `sizehint'. Lorsqu'il est défini à −1, la taille du tampon peut être arbitraire. C'est une erreur de renvoyer un tampon de taille nulle.

@code{get_buffer()} doit renvoyer un objet implémentant le @ref{38e,,protocole tampon}.
@end deffn

@geindex buffer_updated() (méthode asyncio.BufferedProtocol)
@anchor{library/asyncio-protocol asyncio BufferedProtocol buffer_updated}@anchor{3303}
@deffn {Méthode} BufferedProtocol.buffer_updated (nbytes)

Appelée lorsque le tampon a été mis à jour avec les données reçues.

`nbytes' est le nombre total d'octets qui ont été écrits dans la mémoire tampon.
@end deffn

@geindex eof_received() (méthode asyncio.BufferedProtocol)
@anchor{library/asyncio-protocol asyncio BufferedProtocol eof_received}@anchor{3304}
@deffn {Méthode} BufferedProtocol.eof_received ()

Voir la documentation de la méthode @ref{3300,,protocol.eof_received()}.
@end deffn

@ref{3302,,get_buffer()} peut être appelée un nombre arbitraire de fois pendant une connexion. Cependant, @ref{3300,,protocol.eof_received()} est appelée au plus une fois et, si elle est appelée, @ref{3302,,get_buffer()} et @ref{3303,,buffer_updated()} ne seront pas appelées après.

Machine à états :

@example
start -> connection_made
    [-> get_buffer
        [-> buffer_updated]?
    ]*
    [-> eof_received]?
-> connection_lost -> end
@end example

@node Protocoles par datagrammes non connectés,Protocoles liés aux sous-processus,Protocoles connectés avec tampon,Protocoles
@anchor{library/asyncio-protocol datagram-protocols}@anchor{3305}
@subsubsection Protocoles par datagrammes (non connectés)


Les instances du protocole par datagrammes doivent être construites par des fabriques de protocole transmises à la méthode @ref{71d,,loop.create_datagram_endpoint()}.

@geindex datagram_received() (méthode asyncio.DatagramProtocol)
@anchor{library/asyncio-protocol asyncio DatagramProtocol datagram_received}@anchor{3306}
@deffn {Méthode} DatagramProtocol.datagram_received (data, addr)

Appelée lorsqu'un datagramme est reçu. `data' est un objet bytes contenant les données entrantes. `addr' est l'adresse du pair qui envoie les données ; le format exact dépend du transport.
@end deffn

@geindex error_received() (méthode asyncio.DatagramProtocol)
@anchor{library/asyncio-protocol asyncio DatagramProtocol error_received}@anchor{3307}
@deffn {Méthode} DatagramProtocol.error_received (exc)

Appelée lorsqu'une opération d'envoi ou de réception précédente lève une @ref{40d,,OSError}. `exc' est l'instance @ref{40d,,OSError}.

Cette méthode est appelée dans de rares cas, lorsque le transport (par exemple UDP) détecte qu'un datagramme n'a pas pu être livré à son destinataire. Cependant, il est courant que les datagrammes qui ne peuvent être acheminés soient supprimés silencieusement.
@end deffn

@cartouche
@quotation Note 
Sur les systèmes BSD (macOS, FreeBSD, etc.), le contrôle de flux n'est pas pris en charge pour les protocoles par datagrammes, car il n'existe aucun moyen fiable de détecter les échecs d'envoi causés par l'écriture d'un trop grand nombre de paquets.

Le connecteur apparaît toujours « prêt » et les paquets en excès sont supprimés. Une @ref{40d,,OSError} avec @code{errno} définie sur @ref{1776,,errno.ENOBUFS} peut être levée ou non ; si elle est levée, c'est communiqué à @ref{3307,,DatagramProtocol.error_received()} et ignoré dans le cas contraire.
@end quotation
@end cartouche

@node Protocoles liés aux sous-processus,,Protocoles par datagrammes non connectés,Protocoles
@anchor{library/asyncio-protocol asyncio-subprocess-protocols}@anchor{325e}@anchor{library/asyncio-protocol subprocess-protocols}@anchor{3308}
@subsubsection Protocoles liés aux sous-processus


Les instances de protocole de sous-processus doivent être construites par des fabriques de protocole transmises aux méthodes @ref{3258,,loop.subprocess_exec()} et @ref{3259,,loop.subprocess_shell()}.

@geindex pipe_data_received() (méthode asyncio.SubprocessProtocol)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol pipe_data_received}@anchor{1752}
@deffn {Méthode} SubprocessProtocol.pipe_data_received (fd, data)

Appelée lorsqu'un processus enfant écrit sur sa sortie d'erreur ou sa sortie standard.

`fd' est l'entier représentant le descripteur de fichier du tube.

`data' est un objet bytes non vide contenant les données reçues.
@end deffn

@geindex pipe_connection_lost() (méthode asyncio.SubprocessProtocol)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol pipe_connection_lost}@anchor{3309}
@deffn {Méthode} SubprocessProtocol.pipe_connection_lost (fd, exc)

Appelé lorsqu'un des tubes de communication avec un sous-processus est fermé.

`fd' est l'entier représentant le descripteur de fichier qui a été fermé.
@end deffn

@geindex process_exited() (méthode asyncio.SubprocessProtocol)
@anchor{library/asyncio-protocol asyncio SubprocessProtocol process_exited}@anchor{1751}
@deffn {Méthode} SubprocessProtocol.process_exited ()

Appelée lorsqu'un processus enfant se termine.

It can be called before @ref{1752,,pipe_data_received()} and
@ref{3309,,pipe_connection_lost()} methods.
@end deffn

@node Exemples<19>,,Protocoles,Transports et Protocoles
@anchor{library/asyncio-protocol examples}@anchor{32e1}
@subsubsection Exemples


@menu
* Serveur écho en TCP:: 
* Client écho en TCP:: 
* Serveur écho en UDP:: 
* Client écho en UDP:: 
* Connexion de connecteurs existants:: 
* loop.subprocess_exec() et SubprocessProtocol: loop subprocess_exec et SubprocessProtocol. 

@end menu

@node Serveur écho en TCP,Client écho en TCP,,Exemples<19>
@anchor{library/asyncio-protocol asyncio-example-tcp-echo-server-protocol}@anchor{322d}@anchor{library/asyncio-protocol tcp-echo-server}@anchor{330a}
@subsubsection Serveur `écho' en TCP


Crée un serveur d'écho TCP en utilisant la méthode @ref{b01,,loop.create_server()}, renvoie les données reçues et ferme la connexion :

@example
import asyncio


class EchoServerProtocol(asyncio.Protocol):
    def connection_made(self, transport):
        peername = transport.get_extra_info('peername')
        print('Connection from @{@}'.format(peername))
        self.transport = transport

    def data_received(self, data):
        message = data.decode()
        print('Data received: @{!r@}'.format(message))

        print('Send: @{!r@}'.format(message))
        self.transport.write(data)

        print('Close the client socket')
        self.transport.close()


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    server = await loop.create_server(
        EchoServerProtocol,
        '127.0.0.1', 8888)

    async with server:
        await server.serve_forever()


asyncio.run(main())
@end example


@subsubheading Voir aussi


L'exemple @ref{322b,,Serveur d'écho TCP utilisant des flux} utilise la fonction de haut niveau @ref{b07,,asyncio.start_server()}.


@node Client écho en TCP,Serveur écho en UDP,Serveur écho en TCP,Exemples<19>
@anchor{library/asyncio-protocol asyncio-example-tcp-echo-client-protocol}@anchor{322a}@anchor{library/asyncio-protocol tcp-echo-client}@anchor{330b}
@subsubsection Client `écho' en TCP


Client d'écho TCP utilisant la méthode @ref{5ee,,loop.create_connection()} envoie des données et attend que la connexion soit fermée :

@example
import asyncio


class EchoClientProtocol(asyncio.Protocol):
    def __init__(self, message, on_con_lost):
        self.message = message
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        transport.write(self.message.encode())
        print('Data sent: @{!r@}'.format(self.message))

    def data_received(self, data):
        print('Data received: @{!r@}'.format(data.decode()))

    def connection_lost(self, exc):
        print('The server closed the connection')
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    on_con_lost = loop.create_future()
    message = 'Hello World!'

    transport, protocol = await loop.create_connection(
        lambda: EchoClientProtocol(message, on_con_lost),
        '127.0.0.1', 8888)

    # Wait until the protocol signals that the connection
    # is lost and close the transport.
    try:
        await on_con_lost
    finally:
        transport.close()


asyncio.run(main())
@end example


@subsubheading Voir aussi


L'exemple @ref{3228,,Client d'écho TCP utilisant des flux} utilise la fonction de haut niveau @ref{b06,,asyncio.open_connection()}.


@node Serveur écho en UDP,Client écho en UDP,Client écho en TCP,Exemples<19>
@anchor{library/asyncio-protocol asyncio-udp-echo-server-protocol}@anchor{32a6}@anchor{library/asyncio-protocol udp-echo-server}@anchor{330c}
@subsubsection Serveur `écho' en UDP


Serveur d'écho UDP, utilisant la méthode @ref{71d,,loop.create_datagram_endpoint()}, qui renvoie les données reçues :

@example
import asyncio


class EchoServerProtocol:
    def connection_made(self, transport):
        self.transport = transport

    def datagram_received(self, data, addr):
        message = data.decode()
        print('Received %r from %s' % (message, addr))
        print('Send %r to %s' % (message, addr))
        self.transport.sendto(data, addr)


async def main():
    print("Starting UDP server")

    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    # One protocol instance will be created to serve all
    # client requests.
    transport, protocol = await loop.create_datagram_endpoint(
        EchoServerProtocol,
        local_addr=('127.0.0.1', 9999))

    try:
        await asyncio.sleep(3600)  # Serve for 1 hour.
    finally:
        transport.close()


asyncio.run(main())
@end example

@node Client écho en UDP,Connexion de connecteurs existants,Serveur écho en UDP,Exemples<19>
@anchor{library/asyncio-protocol asyncio-udp-echo-client-protocol}@anchor{32a5}@anchor{library/asyncio-protocol udp-echo-client}@anchor{330d}
@subsubsection Client `écho' en UDP


Client d'écho UDP, utilisant la méthode @ref{71d,,loop.create_datagram_endpoint()}, qui envoie des données et ferme le transport lorsqu'il reçoit la réponse :

@example
import asyncio


class EchoClientProtocol:
    def __init__(self, message, on_con_lost):
        self.message = message
        self.on_con_lost = on_con_lost
        self.transport = None

    def connection_made(self, transport):
        self.transport = transport
        print('Send:', self.message)
        self.transport.sendto(self.message.encode())

    def datagram_received(self, data, addr):
        print("Received:", data.decode())

        print("Close the socket")
        self.transport.close()

    def error_received(self, exc):
        print('Error received:', exc)

    def connection_lost(self, exc):
        print("Connection closed")
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    on_con_lost = loop.create_future()
    message = "Hello World!"

    transport, protocol = await loop.create_datagram_endpoint(
        lambda: EchoClientProtocol(message, on_con_lost),
        remote_addr=('127.0.0.1', 9999))

    try:
        await on_con_lost
    finally:
        transport.close()


asyncio.run(main())
@end example

@node Connexion de connecteurs existants,loop subprocess_exec et SubprocessProtocol,Client écho en UDP,Exemples<19>
@anchor{library/asyncio-protocol asyncio-example-create-connection}@anchor{3231}@anchor{library/asyncio-protocol connecting-existing-sockets}@anchor{330e}
@subsubsection Connexion de connecteurs existants


Attend qu'un connecteur reçoive des données en utilisant la méthode @ref{5ee,,loop.create_connection()} avec un protocole :

@example
import asyncio
import socket


class MyProtocol(asyncio.Protocol):

    def __init__(self, on_con_lost):
        self.transport = None
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        self.transport = transport

    def data_received(self, data):
        print("Received:", data.decode())

        # We are done: close the transport;
        # connection_lost() will be called automatically.
        self.transport.close()

    def connection_lost(self, exc):
        # The socket has been closed
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()
    on_con_lost = loop.create_future()

    # Create a pair of connected sockets
    rsock, wsock = socket.socketpair()

    # Register the socket to wait for data.
    transport, protocol = await loop.create_connection(
        lambda: MyProtocol(on_con_lost), sock=rsock)

    # Simulate the reception of data from the network.
    loop.call_soon(wsock.send, 'abc'.encode())

    try:
        await protocol.on_con_lost
    finally:
        transport.close()
        wsock.close()

asyncio.run(main())
@end example


@subsubheading Voir aussi


L'exemple @ref{3232,,Surveillance des événements de lecture pour un descripteur de fichier} utilise la méthode de bas niveau @ref{3233,,loop.add_reader()} pour enregistrer un descripteur de fichier.

L'exemple @ref{322f,,Ouverture d'un connecteur pour attendre les données à l'aide de flux} utilise des flux de haut niveau créés par la fonction @ref{b06,,open_connection()} dans une coroutine.


@node loop subprocess_exec et SubprocessProtocol,,Connexion de connecteurs existants,Exemples<19>
@anchor{library/asyncio-protocol asyncio-example-subprocess-proto}@anchor{3270}@anchor{library/asyncio-protocol loop-subprocess-exec-and-subprocessprotocol}@anchor{330f}
@subsubsection `loop.subprocess_exec()' et `SubprocessProtocol'


Un exemple de protocole de sous-processus utilisé pour obtenir la sortie d'un sous-processus et attendre la sortie du sous-processus.

Le sous-processus est créé par la méthode @ref{3258,,loop.subprocess_exec()} :

@example
import asyncio
import sys

class DateProtocol(asyncio.SubprocessProtocol):
    def __init__(self, exit_future):
        self.exit_future = exit_future
        self.output = bytearray()
        self.pipe_closed = False
        self.exited = False

    def pipe_connection_lost(self, fd, exc):
        self.pipe_closed = True
        self.check_for_exit()

    def pipe_data_received(self, fd, data):
        self.output.extend(data)

    def process_exited(self):
        self.exited = True
        # process_exited() method can be called before
        # pipe_connection_lost() method: wait until both methods are
        # called.
        self.check_for_exit()

    def check_for_exit(self):
        if self.pipe_closed and self.exited:
            self.exit_future.set_result(True)

async def get_date():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    code = 'import datetime; print(datetime.datetime.now())'
    exit_future = asyncio.Future(loop=loop)

    # Create the subprocess controlled by DateProtocol;
    # redirect the standard output into a pipe.
    transport, protocol = await loop.subprocess_exec(
        lambda: DateProtocol(exit_future),
        sys.executable, '-c', code,
        stdin=None, stderr=None)

    # Wait for the subprocess exit using the process_exited()
    # method of the protocol.
    await exit_future

    # Close the stdout pipe.
    transport.close()

    # Read the output which was collected by the
    # pipe_data_received() method of the protocol.
    data = bytes(protocol.output)
    return data.decode('ascii').rstrip()

date = asyncio.run(get_date())
print(f"Current date: @{date@}")
@end example

Voir aussi le @ref{326f,,même exemple} écrit à l'aide d'API de haut niveau.

@node Politiques,Prise en charge de la plate-forme,Transports et Protocoles,asyncio --- Asynchronous I/O
@anchor{library/asyncio-policy doc}@anchor{3310}@anchor{library/asyncio-policy asyncio-policies}@anchor{328d}@anchor{library/asyncio-policy policies}@anchor{3311}
@subsubsection Politiques


Une politique de boucle d'événements est un objet global utilisé pour obtenir et définir la @ref{d66,,boucle d'événements} actuelle, ainsi que créer de nouvelles boucles d'événements. La politique par défaut peut être @ref{3312,,remplacée} par des @ref{3313,,alternatives intégrées} afin d'utiliser d'autres implémentations de boucles d'événements, ou remplacée par une @ref{3314,,politique personnalisée} qui peut remplacer ces comportements.

Un @ref{3315,,objet politique} définit la notion de `contexte' et gère une boucle d'événement distincte par contexte. Ceci est valable fil par fil d'exécution par défaut, bien que les politiques personnalisées puissent définir le `contexte' différemment.

En utilisant une politique de boucle d'événement personnalisée, le comportement des fonctions @ref{2bf,,get_event_loop()}, @ref{1758,,set_event_loop()} et @ref{31e1,,new_event_loop()} peut être personnalisé.

Les objets politiques doivent implémenter les API définies dans la classe mère abstraite @ref{3316,,AbstractEventLoopPolicy}.

@menu
* Obtenir et définir la politique:: 
* Objets politiques:: 
* Observateurs de processus:: 
* Politiques personnalisées:: 

@end menu

@node Obtenir et définir la politique,Objets politiques,,Politiques
@anchor{library/asyncio-policy asyncio-policy-get-set}@anchor{3312}@anchor{library/asyncio-policy getting-and-setting-the-policy}@anchor{3317}
@subsubsection Obtenir et définir la politique


Les fonctions suivantes peuvent être utilisées pour obtenir et définir la politique du processus en cours :

@geindex get_event_loop_policy() (dans le module asyncio)
@anchor{library/asyncio-policy asyncio get_event_loop_policy}@anchor{3318}
@deffn {Fonction} asyncio.get_event_loop_policy ()

Renvoie la politique actuelle à l'échelle du processus.
@end deffn

@geindex set_event_loop_policy() (dans le module asyncio)
@anchor{library/asyncio-policy asyncio set_event_loop_policy}@anchor{3319}
@deffn {Fonction} asyncio.set_event_loop_policy (policy)

Définit la politique actuelle sur l'ensemble du processus sur `policy'.

Si `policy' est définie sur @code{None}, la politique par défaut est restaurée.
@end deffn

@node Objets politiques,Observateurs de processus,Obtenir et définir la politique,Politiques
@anchor{library/asyncio-policy asyncio-policy-objects}@anchor{3315}@anchor{library/asyncio-policy policy-objects}@anchor{331a}
@subsubsection Objets politiques


La classe mère abstraite de la politique de boucle d'événements est définie comme suit :

@geindex AbstractEventLoopPolicy (classe dans asyncio)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy}@anchor{3316}
@deffn {Classe} asyncio.AbstractEventLoopPolicy

Une classe de base abstraite pour les politiques `asyncio'.

@geindex get_event_loop() (méthode asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy get_event_loop}@anchor{331b}
@deffn {Méthode} get_event_loop ()

Récupère la boucle d'évènements pour le contexte actuel.

Renvoie un objet de boucle d'événements en implémentant l'interface @ref{94c,,AbstractEventLoop}.

Cette méthode ne devrait jamais renvoyer @code{None}.


Modifié dans la version 3.6.

@end deffn

@geindex set_event_loop() (méthode asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy set_event_loop}@anchor{331c}
@deffn {Méthode} set_event_loop (loop)

Définit la boucle d'événements du contexte actuel sur `loop'.
@end deffn

@geindex new_event_loop() (méthode asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy new_event_loop}@anchor{331d}
@deffn {Méthode} new_event_loop ()

Crée et renvoie un nouvel objet de boucle d'événements.

Cette méthode ne devrait jamais renvoyer @code{None}.
@end deffn

@geindex get_child_watcher() (méthode asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy get_child_watcher}@anchor{2be}
@deffn {Méthode} get_child_watcher ()

Récupère un objet observateur du processus enfant.

Renvoie un objet observateur implémentant l'interface @ref{2b9,,AbstractChildWatcher}.

Cette fonction est spécifique à Unix.


Obsolète depuis la version 3.12.

@end deffn

@geindex set_child_watcher() (méthode asyncio.AbstractEventLoopPolicy)
@anchor{library/asyncio-policy asyncio AbstractEventLoopPolicy set_child_watcher}@anchor{2bd}
@deffn {Méthode} set_child_watcher (watcher)

Définit l'observateur du processus enfant actuel à `watcher'.

Cette fonction est spécifique à Unix.


Obsolète depuis la version 3.12.

@end deffn
@end deffn
@anchor{library/asyncio-policy asyncio-policy-builtin}@anchor{3313}
`asyncio' est livré avec les politiques intégrées suivantes :

@geindex DefaultEventLoopPolicy (classe dans asyncio)
@anchor{library/asyncio-policy asyncio DefaultEventLoopPolicy}@anchor{331e}
@deffn {Classe} asyncio.DefaultEventLoopPolicy

La politique `asyncio' par défaut. Utilise @ref{5f3,,SelectorEventLoop} sur les plates-formes Unix et @ref{5f4,,ProactorEventLoop} sur Windows.

Il n'est pas nécessaire d'installer la politique par défaut manuellement. `asyncio' est configuré pour utiliser automatiquement la politique par défaut.


Modifié dans la version 3.8: Sous Windows, @ref{5f4,,ProactorEventLoop} est désormais utilisée par défaut.



Obsolète depuis la version 3.12: The @ref{2bf,,get_event_loop()} method of the default asyncio policy now emits
a @ref{1a3,,DeprecationWarning} if there is no current event loop set and it
decides to create one.
In some future Python release this will become an error.

@end deffn

@geindex WindowsSelectorEventLoopPolicy (classe dans asyncio)
@anchor{library/asyncio-policy asyncio WindowsSelectorEventLoopPolicy}@anchor{331f}
@deffn {Classe} asyncio.WindowsSelectorEventLoopPolicy

Politique de boucle d'événements alternative utilisant l'implémentation de la boucle d'événements @ref{5f4,,ProactorEventLoop}.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex WindowsProactorEventLoopPolicy (classe dans asyncio)
@anchor{library/asyncio-policy asyncio WindowsProactorEventLoopPolicy}@anchor{3320}
@deffn {Classe} asyncio.WindowsProactorEventLoopPolicy

Politique de boucle d'événements alternative utilisant l'implémentation de la boucle d'événements @ref{5f4,,ProactorEventLoop}.

@ref{1ce0,,Availability}: Windows.
@end deffn

@node Observateurs de processus,Politiques personnalisées,Objets politiques,Politiques
@anchor{library/asyncio-policy asyncio-watchers}@anchor{326e}@anchor{library/asyncio-policy process-watchers}@anchor{3321}
@subsubsection Observateurs de processus


Un observateur de processus permet de personnaliser la manière dont une boucle d'événements surveille les processus enfants sous Unix. Plus précisément, la boucle d'événements a besoin de savoir quand un processus enfant s'est terminé.

Dans `asyncio', les processus enfants sont créés avec les fonctions @ref{a65,,create_subprocess_exec()} et @ref{3258,,loop.subprocess_exec()}.

`asyncio' définit la classe mère abstraite @ref{2b9,,AbstractChildWatcher}, que les observateurs enfants doivent implémenter et possède quatre implémentations différentes : @ref{465,,ThreadedChildWatcher} (configurée pour être utilisé par défaut), @ref{2b7,,MultiLoopChildWatcher}, @ref{2ba,,SafeChildWatcher} et @ref{2b8,,FastChildWatcher}.

Voir aussi la section @ref{3268,,sous-processus et fils d'exécution}.

Les deux fonctions suivantes peuvent être utilisées pour personnaliser l'implémentation de l'observateur de processus enfant utilisé par la boucle d'événements `asyncio' :

@geindex get_child_watcher() (dans le module asyncio)
@anchor{library/asyncio-policy asyncio get_child_watcher}@anchor{2bc}
@deffn {Fonction} asyncio.get_child_watcher ()

Renvoie l'observateur enfant actuel pour la politique actuelle.


Obsolète depuis la version 3.12.

@end deffn

@geindex set_child_watcher() (dans le module asyncio)
@anchor{library/asyncio-policy asyncio set_child_watcher}@anchor{2bb}
@deffn {Fonction} asyncio.set_child_watcher (watcher)

Définit l'observateur enfant actuel à `watcher' pour la politique actuelle. `watcher' doit implémenter les méthodes définies dans la classe de base @ref{2b9,,AbstractChildWatcher}.


Obsolète depuis la version 3.12.

@end deffn

@cartouche
@quotation Note 
Les implémentations de boucles d'événements tierces peuvent ne pas prendre en charge les observateurs enfants personnalisés. Pour ces boucles d'événements, utiliser @ref{2bb,,set_child_watcher()} pourrait être interdit ou n'avoir aucun effet.
@end quotation
@end cartouche

@geindex AbstractChildWatcher (classe dans asyncio)
@anchor{library/asyncio-policy asyncio AbstractChildWatcher}@anchor{2b9}
@deffn {Classe} asyncio.AbstractChildWatcher

@geindex add_child_handler() (méthode asyncio.AbstractChildWatcher)
@anchor{library/asyncio-policy asyncio AbstractChildWatcher add_child_handler}@anchor{3322}
@deffn {Méthode} add_child_handler (pid, callback, *args)

Enregistre un nouveau gestionnaire.

Organise l'appel de @code{callback(pid, returncode, * args)} lorsqu'un processus dont le `PID' est égal à `pid' se termine. La spécification d'un autre rappel pour le même processus remplace le gestionnaire précédent.

L'appelable `callback' doit être compatible avec les programmes à fils d'exécution multiples.
@end deffn

@geindex remove_child_handler() (méthode asyncio.AbstractChildWatcher)
@anchor{library/asyncio-policy asyncio AbstractChildWatcher remove_child_handler}@anchor{3323}
@deffn {Méthode} remove_child_handler (pid)

Supprime le gestionnaire de processus avec un PID égal à `pid'.

La fonction renvoie @code{True} si le gestionnaire a été supprimé avec succès, @code{False} s'il n'y a rien à supprimer.
@end deffn

@geindex attach_loop() (méthode asyncio.AbstractChildWatcher)
@anchor{library/asyncio-policy asyncio AbstractChildWatcher attach_loop}@anchor{1759}
@deffn {Méthode} attach_loop (loop)

Attache l'observateur à une boucle d'événement.

Si l'observateur était précédemment attaché à une boucle d'événements, il est d'abord détaché avant d'être rattaché à la nouvelle boucle.

Remarque : la boucle peut être @code{None}.
@end deffn

@geindex is_active() (méthode asyncio.AbstractChildWatcher)
@anchor{library/asyncio-policy asyncio AbstractChildWatcher is_active}@anchor{3324}
@deffn {Méthode} is_active ()

Renvoie @code{True} si l'observateur est prêt à être utilisé.

La création d'un sous-processus avec un observateur enfant actuel `inactif' lève une @ref{193,,RuntimeError}.


Ajouté dans la version 3.8.

@end deffn

@geindex close() (méthode asyncio.AbstractChildWatcher)
@anchor{library/asyncio-policy asyncio AbstractChildWatcher close}@anchor{3325}
@deffn {Méthode} close ()

Ferme l'observateur.

Cette méthode doit être appelée pour s'assurer que les ressources sous-jacentes sont nettoyées.
@end deffn


Obsolète depuis la version 3.12.

@end deffn

@geindex ThreadedChildWatcher (classe dans asyncio)
@anchor{library/asyncio-policy asyncio ThreadedChildWatcher}@anchor{465}
@deffn {Classe} asyncio.ThreadedChildWatcher

Cette implémentation démarre un nouveau fil d'exécution en attente pour chaque génération de sous-processus.

Il fonctionne de manière fiable même lorsque la boucle d'événements `asyncio' est exécutée dans un fil d'exécution non principal.

There is no noticeable overhead when handling a big number of children (`O'(1) each
time a child terminates), but starting a thread per process requires extra memory.

Cet observateur est utilisé par défaut.


Ajouté dans la version 3.8.

@end deffn

@geindex MultiLoopChildWatcher (classe dans asyncio)
@anchor{library/asyncio-policy asyncio MultiLoopChildWatcher}@anchor{2b7}
@deffn {Classe} asyncio.MultiLoopChildWatcher

Cette implémentation enregistre un gestionnaire de signal @code{SIGCHLD} lors de l'instanciation. Cela peut casser le code tiers qui installe un gestionnaire personnalisé pour le signal @code{SIGCHLD}.

L'observateur évite de perturber un autre code qui crée des processus en interrogeant explicitement chaque processus sur un signal @code{SIGCHLD}.

Il n'y a aucune limitation pour l'exécution de sous-processus à partir de différents fils d'exécution une fois l'observateur installé.

The solution is safe but it has a significant overhead when
handling a big number of processes (`O'(`n') each time a
@code{SIGCHLD} is received).


Ajouté dans la version 3.8.



Obsolète depuis la version 3.12.

@end deffn

@geindex SafeChildWatcher (classe dans asyncio)
@anchor{library/asyncio-policy asyncio SafeChildWatcher}@anchor{2ba}
@deffn {Classe} asyncio.SafeChildWatcher

Cette implémentation utilise une boucle d'événements active du fil d'exécution principal pour gérer le signal @code{SIGCHLD}. Si le fil d'exécution principal n'a pas de boucle d'événements en cours d'exécution, un autre fil ne pourra pas générer de sous-processus (une @ref{193,,RuntimeError} est levée).

L'observateur évite de perturber un autre code qui crée des processus en interrogeant explicitement chaque processus sur un signal @code{SIGCHLD}.

This solution is as safe as @ref{2b7,,MultiLoopChildWatcher} and has the same `O'(`n')
complexity but requires a running event loop in the main thread to work.


Obsolète depuis la version 3.12.

@end deffn

@geindex FastChildWatcher (classe dans asyncio)
@anchor{library/asyncio-policy asyncio FastChildWatcher}@anchor{2b8}
@deffn {Classe} asyncio.FastChildWatcher

Cette implémentation récupère tous les processus terminés en appelant directement @code{os.waitpid(-1)}, cassant éventuellement un autre code qui génère des processus et attend leur fin.

There is no noticeable overhead when handling a big number of
children (`O'(1) each time a child terminates).

Cette solution nécessite une boucle d'événements en cours d'exécution dans le fil d'exécution principal pour fonctionner, comme @ref{2ba,,SafeChildWatcher}.


Obsolète depuis la version 3.12.

@end deffn

@geindex PidfdChildWatcher (classe dans asyncio)
@anchor{library/asyncio-policy asyncio PidfdChildWatcher}@anchor{463}
@deffn {Classe} asyncio.PidfdChildWatcher

Cette implémentation interroge les descripteurs de fichiers de processus (`pidfds') pour attendre la fin du processus enfant. À certains égards, @ref{463,,PidfdChildWatcher} est une implémentation d'observateur d'enfants `Goldilocks'. Elle ne nécessite ni signaux ni threads, n'interfère avec aucun processus lancé en dehors de la boucle d'événements et évolue de manière linéaire avec le nombre de sous-processus lancés par la boucle d'événements. Le principal inconvénient est que les `pidfds' sont spécifiques à Linux et ne fonctionnent que sur les noyaux récents (5.3+).


Ajouté dans la version 3.9.

@end deffn

@node Politiques personnalisées,,Observateurs de processus,Politiques
@anchor{library/asyncio-policy asyncio-custom-policies}@anchor{3314}@anchor{library/asyncio-policy custom-policies}@anchor{3326}
@subsubsection Politiques personnalisées


Pour implémenter une nouvelle politique de boucle d’événements, il est recommandé de sous-classer @ref{331e,,DefaultEventLoopPolicy} et de réimplémenter les méthodes pour lesquelles un comportement personnalisé est souhaité, par exemple :

@example
class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):

    def get_event_loop(self):
        """Get the event loop.

        This may be None or an instance of EventLoop.
        """
        loop = super().get_event_loop()
        # Do something with loop ...
        return loop

asyncio.set_event_loop_policy(MyEventLoopPolicy())
@end example

@node Prise en charge de la plate-forme,Extension,Politiques,asyncio --- Asynchronous I/O
@anchor{library/asyncio-platforms doc}@anchor{3327}@anchor{library/asyncio-platforms asyncio-platform-support}@anchor{32b0}@anchor{library/asyncio-platforms platform-support}@anchor{3328}
@subsubsection Prise en charge de la plate-forme


Le module @ref{a,,asyncio} est conçu pour être portable, mais certaines plates-formes présentent des différences et des limitations subtiles en raison de l'architecture et des capacités sous-jacentes des plates-formes.

@menu
* Toutes plateformes:: 
* Windows: Windows<75>. 
* macOS: macOS<47>. 

@end menu

@node Toutes plateformes,Windows<75>,,Prise en charge de la plate-forme
@anchor{library/asyncio-platforms all-platforms}@anchor{3329}
@subsubsection Toutes plateformes



@itemize *

@item 
@ref{3233,,loop.add_reader()} et @ref{32ae,,loop.add_writer()} ne peuvent pas être utilisées pour surveiller les entrées-sorties de fichiers.
@end itemize

@node Windows<75>,macOS<47>,Toutes plateformes,Prise en charge de la plate-forme
@anchor{library/asyncio-platforms windows}@anchor{332a}
@subsubsection Windows


`Code source :' Lib/asyncio/proactor_events.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/proactor_events.py}, Lib/asyncio/windows_events.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/windows_events.py}, Lib/asyncio/windows_utils.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/windows_utils.py}


__________________________________________________________________



Modifié dans la version 3.8: sous Windows, @ref{5f4,,ProactorEventLoop} est désormais la boucle d'événements par défaut.


Aucune boucle d'événements sous Windows ne prend en charge les méthodes suivantes :


@itemize *

@item 
@ref{3218,,loop.create_unix_connection()} and
@ref{1ac,,loop.create_unix_server()} are not supported.
The @ref{17ad,,socket.AF_UNIX} socket family is specific to Unix.

@item 
@ref{32b7,,loop.add_signal_handler()} et @ref{32b8,,loop.remove_signal_handler()} ne sont pas prises en charge.
@end itemize

@ref{5f3,,SelectorEventLoop} a les limitations suivantes :


@itemize *

@item 
@ref{332b,,SelectSelector} est utilisée pour attendre les événements de connecteur (`sockets') : elle prend en charge les connecteurs et est limitée à 512 connecteurs.

@item 
@ref{3233,,loop.add_reader()} et @ref{32ae,,loop.add_writer()} n'acceptent que les descripteurs de connecteur (par exemple, les descripteurs de tube fichier ne sont pas pris en charge).

@item 
Les tubes ne sont pas pris en charge, donc les méthodes @ref{325b,,loop.connect_read_pipe()} et @ref{325c,,loop.connect_write_pipe()} ne sont pas implémentées.

@item 
Les @ref{31d5,,sous-processus} ne sont pas pris en charge, c'est-à-dire que les méthodes @ref{3258,,loop.subprocess_exec()} et @ref{3259,,loop.subprocess_shell()} ne sont pas implémentées.
@end itemize

@ref{5f4,,ProactorEventLoop} a les limitations suivantes :


@itemize *

@item 
Les méthodes @ref{3233,,loop.add_reader()} et @ref{32ae,,loop.add_writer()} ne sont pas prises en charge.
@end itemize

La résolution de l'horloge monotone sous Windows est généralement d'environ 15,6 millisecondes. La meilleure résolution est de 0,5 milliseconde. La résolution dépend du matériel (disponibilité de HPET@footnote{https://fr.wikipedia.org/wiki/High_Precision_Event_Timer}) et de la configuration de Windows.

@menu
* Prise en charge des sous-processus sous Windows:: 

@end menu

@node Prise en charge des sous-processus sous Windows,,,Windows<75>
@anchor{library/asyncio-platforms asyncio-windows-subprocess}@anchor{325a}@anchor{library/asyncio-platforms subprocess-support-on-windows}@anchor{332c}
@subsubsection Prise en charge des sous-processus sous Windows


Sous Windows, la boucle d'événements par défaut @ref{5f4,,ProactorEventLoop} prend en charge les sous-processus, contrairement à @ref{5f3,,SelectorEventLoop}.

La fonction @ref{2bd,,policy.set_child_watcher()} n'est pas non plus prise en charge, car @ref{5f4,,ProactorEventLoop} a un mécanisme différent pour surveiller les processus enfants.

@node macOS<47>,,Windows<75>,Prise en charge de la plate-forme
@anchor{library/asyncio-platforms macos}@anchor{332d}
@subsubsection macOS


Les versions modernes de macOS sont entièrement prises en charge.

@subsubheading macOS ≤ 10.8


Sur macOS 10.6, 10.7 et 10.8, la boucle d'événements par défaut utilise @ref{332e,,selectors.KqueueSelector}, qui ne prend pas en charge les périphériques de caractères sur ces versions. La @ref{5f3,,SelectorEventLoop} peut être configurée manuellement pour utiliser @ref{332b,,SelectSelector} ou @ref{bc4,,PollSelector} pour prendre en charge les périphériques de caractères sur ces anciennes versions de macOS. Par exemple :

@example
import asyncio
import selectors

selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)
@end example

@node Extension,Index de l'API de haut niveau,Prise en charge de la plate-forme,asyncio --- Asynchronous I/O
@anchor{library/asyncio-extending doc}@anchor{332f}@anchor{library/asyncio-extending extending}@anchor{3330}
@subsubsection Extension


La direction principale pour l'extension d'@ref{a,,asyncio} est l'écriture de classes `event loop' personnalisées. `Asyncio' a des assistants qui peuvent être utilisés pour simplifier cette tâche.

@cartouche
@quotation Note 
la réutilisation du code asynchrone existant doit se faire avec prudence, une nouvelle version de Python est libre de rompre la compatibilité descendante dans la partie `interne' de l'API.
@end quotation
@end cartouche

@menu
* Écriture d'une boucle d'événements personnalisée:: 
* Constructeurs privés Future et Task:: 
* Prise en charge de la durée de vie des tâches:: 

@end menu

@node Écriture d'une boucle d'événements personnalisée,Constructeurs privés Future et Task,,Extension
@anchor{library/asyncio-extending writing-a-custom-event-loop}@anchor{3331}
@subsubsection Écriture d'une boucle d'événements personnalisée


@ref{94c,,asyncio.AbstractEventLoop} déclare de très nombreuses méthodes. Les mettre en œuvre à partir de zéro est un travail fastidieux.

Une boucle d'événements peut obtenir gratuitement l'implémentation de nombreuses méthodes courantes en héritant de @code{asyncio.BaseEventLoop}.

Le successeur doit, pour ce qui le concerne, implémenter un ensemble de méthodes `privées' déclarées mais non implémentées dans @code{asyncio.BaseEventLoop}.

Par exemple, @code{loop.create_connection()} vérifie les arguments, résout les adresses DNS et appelle @code{loop._make_socket_transport()} qui doit être implémentée par la classe héritée. La méthode @code{_make_socket_transport()} n'est pas documentée et est considérée comme une API `interne'.

@node Constructeurs privés Future et Task,Prise en charge de la durée de vie des tâches,Écriture d'une boucle d'événements personnalisée,Extension
@anchor{library/asyncio-extending future-and-task-private-constructors}@anchor{3332}
@subsubsection Constructeurs privés `Future' et `Task'


@ref{bbb,,asyncio.Future} et @ref{4c2,,asyncio.Task} ne doivent jamais être créées directement, veuillez utiliser les correspondances @ref{c67,,loop.create_future()} et @ref{9ca,,loop.create_task()}, ou les fabriques @ref{5e7,,asyncio.create_task()} à la place.

Cependant, les `boucles d'événements' tierces peuvent `réutiliser' les implémentations de `Future' et de `Task' intégrées dans le but d'obtenir gratuitement un code complexe et hautement optimisé.

À cette fin, les constructeurs `privés' suivants sont répertoriés :

@geindex __init__() (méthode asyncio.Future)
@anchor{library/asyncio-extending asyncio Future __init__}@anchor{3333}
@deffn {Méthode} Future.__init__ (*, loop=None)

Crée une instance de la `future' native.

`loop' est une instance de boucle d'événements facultative.
@end deffn

@geindex __init__() (méthode asyncio.Task)
@anchor{library/asyncio-extending asyncio Task __init__}@anchor{3334}
@deffn {Méthode} Task.__init__ (coro, *, loop=None, name=None, context=None)

Crée une instance de la `Task' native.

`loop' est une instance de boucle d'événements facultative. Le reste des arguments est décrit dans la description de @ref{9ca,,loop.create_task()}.


Modifié dans la version 3.11: l'argument `contexte' a été ajouté.

@end deffn

@node Prise en charge de la durée de vie des tâches,,Constructeurs privés Future et Task,Extension
@anchor{library/asyncio-extending task-lifetime-support}@anchor{3335}
@subsubsection Prise en charge de la durée de vie des tâches


A third party task implementation should call the following functions to keep a task
visible by @ref{943,,asyncio.all_tasks()} and @ref{467,,asyncio.current_task()}:

@geindex _register_task() (dans le module asyncio)
@anchor{library/asyncio-extending asyncio _register_task}@anchor{3336}
@deffn {Fonction} asyncio._register_task (task)

Enregistre une nouvelle `tâche' comme gérée par `asyncio'.

Appelez la fonction à partir d'un constructeur de tâche.
@end deffn

@geindex _unregister_task() (dans le module asyncio)
@anchor{library/asyncio-extending asyncio _unregister_task}@anchor{3337}
@deffn {Fonction} asyncio._unregister_task (task)

Désinscrit une `tâche' des structures internes `asyncio'.

La fonction doit être appelée lorsqu'une tâche est sur le point de se terminer.
@end deffn

@geindex _enter_task() (dans le module asyncio)
@anchor{library/asyncio-extending asyncio _enter_task}@anchor{3338}
@deffn {Fonction} asyncio._enter_task (loop, task)

Bascule la tâche en cours vers l'argument `task'.

Appelez la fonction juste avant d'exécuter une partie de la `coroutine' intégrée (@ref{1f4e,,coroutine.send()} ou @ref{4e1,,coroutine.throw()}).
@end deffn

@geindex _leave_task() (dans le module asyncio)
@anchor{library/asyncio-extending asyncio _leave_task}@anchor{3339}
@deffn {Fonction} asyncio._leave_task (loop, task)

Rebascule la tâche en cours de `task' à @code{None}.

Appelez la fonction juste après l'exécution de @ref{1f4e,,coroutine.send()} ou @ref{4e1,,coroutine.throw()}.
@end deffn

@node Index de l'API de haut niveau,Index de l'API de bas niveau,Extension,asyncio --- Asynchronous I/O
@anchor{library/asyncio-api-index doc}@anchor{864}@anchor{library/asyncio-api-index high-level-api-index}@anchor{333a}
@subsubsection Index de l'API de haut niveau


Cette page répertorie toutes les API `async/await' de haut niveau disponibles dans l'API `asyncio'.

@menu
* Tâches:: 
* Files d'attente:: 
* Sous-processus: Sous-processus<2>. 
* Flux (streams): Flux streams<2>. 
* Synchronisation:: 
* Exceptions: Exceptions<14>. 

@end menu

@node Tâches,Files d'attente,,Index de l'API de haut niveau
@anchor{library/asyncio-api-index tasks}@anchor{333b}
@subsubsection Tâches


Utilitaires pour exécuter des programmes asynchrones, créer des tâches et attendre plusieurs choses avec des délais maximaux d'attente.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{466,,run()}

@tab

Crée une boucle d'événements, exécute une coroutine, ferme la boucle.

@item

@ref{5eb,,Runner}

@tab

Gestionnaire de contexte qui simplifie plusieurs appels de fonction asynchrones.

@item

@ref{4c2,,Task}

@tab

Objet de tâche.

@item

@ref{1b3,,TaskGroup}

@tab

Gestionnaire de contexte pour un groupe de tâches. Fournit un moyen pratique et fiable d'attendre la fin de toutes les tâches du groupe.

@item

@ref{5e7,,create_task()}

@tab

Démarre une tâche asynchrone, puis la renvoie.

@item

@ref{467,,current_task()}

@tab

Renvoie la tâche actuelle.

@item

@ref{943,,all_tasks()}

@tab

Renvoie toutes les tâches qui ne sont pas encore terminées pour une boucle d'événements.

@item

@code{await} @ref{a5d,,sleep()}

@tab

Dort quelques secondes.

@item

@code{await} @ref{5e8,,gather()}

@tab

Planifie et attend des choses concurrentes.

@item

@code{await} @ref{5ea,,wait_for()}

@tab

Exécute avec un délai d'attente.

@item

@code{await} @ref{a5e,,shield()}

@tab

Empêche l'annulation.

@item

@code{await} @ref{469,,wait()}

@tab

Surveille l'achèvement.

@item

@ref{5e9,,timeout()}

@tab

Exécute avec un délai d'attente. Utile dans les cas où @code{wait_for} ne convient pas.

@item

@ref{8d5,,to_thread()}

@tab

Exécute de manière asynchrone une fonction dans un fil d'exécution séparé.

@item

@ref{86e,,run_coroutine_threadsafe()}

@tab

Planifie une coroutine à partir d'un autre fil d'exécution.

@item

@code{for in} @ref{1a8,,as_completed()}

@tab

Surveille l'achèvement avec une boucle @code{for}.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{31f3,,Utilisation d'asyncio.gather() pour exécuter des choses en parallèle}.

@item 
@ref{31fb,,Utilisation d'asyncio.wait_for() pour appliquer un délai d'attente}.

@item 
@ref{3210,,Annulation}.

@item 
@ref{31f1,,Utilisation d'asyncio.sleep()}.

@item 
Voir aussi la page de @ref{31d3,,documentation de Tasks}.
@end itemize

@node Files d'attente,Sous-processus<2>,Tâches,Index de l'API de haut niveau
@anchor{library/asyncio-api-index queues}@anchor{333c}
@subsubsection Files d'attente


Les files d'attente doivent être utilisées pour répartir le travail entre plusieurs tâches asynchrones, implémenter des pools de connexions et des modèles `pub'/`sub'.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{a64,,Queue}

@tab

File d'attente FIFO (premier entré, premier sorti).

@item

@ref{3280,,PriorityQueue}

@tab

File d'attente avec gestion des priorités.

@item

@ref{3282,,LifoQueue}

@tab

Pile LIFO (dernier entré, premier sorti).

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{3284,,Utilisation d'asyncio.Queue pour répartir la charge de travail entre plusieurs tâches}.

@item 
Voir aussi la page de @ref{31d6,,documentation des Queues}.
@end itemize

@node Sous-processus<2>,Flux streams<2>,Files d'attente,Index de l'API de haut niveau
@anchor{library/asyncio-api-index subprocesses}@anchor{333d}
@subsubsection Sous-processus


Utilitaires pour générer des sous-processus et exécuter des commandes shell.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{a65,,create_subprocess_exec()}

@tab

Crée un sous-processus.

@item

@code{await} @ref{a66,,create_subprocess_shell()}

@tab

Exécute une commande shell.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{3254,,Exécution d'une commande shell}.

@item 
Voir aussi la documentation des @ref{31d5,,API subprocess}.
@end itemize

@node Flux streams<2>,Synchronisation,Sous-processus<2>,Index de l'API de haut niveau
@anchor{library/asyncio-api-index streams}@anchor{333e}
@subsubsection Flux (`streams')


API de haut niveau pour travailler avec les entrées-sorties réseau.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{b06,,open_connection()}

@tab

Établit une connexion TCP.

@item

@code{await} @ref{3217,,open_unix_connection()}

@tab

Établit une connexion sur un connecteur Unix.

@item

@code{await} @ref{b07,,start_server()}

@tab

Démarre un serveur TCP.

@item

@code{await} @ref{3219,,start_unix_server()}

@tab

Démarre un serveur de socket Unix.

@item

@ref{1853,,StreamReader}

@tab

Objet `async/await' de haut niveau pour recevoir des données réseau.

@item

@ref{1689,,StreamWriter}

@tab

Objet `async/await' de haut niveau pour envoyer des données réseau.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{3213,,Exemple de client TCP}.

@item 
Voir aussi la documentation des @ref{31d4,,API streams}.
@end itemize

@node Synchronisation,Exceptions<14>,Flux streams<2>,Index de l'API de haut niveau
@anchor{library/asyncio-api-index synchronization}@anchor{333f}
@subsubsection Synchronisation


Primitives de synchronisation de type thread qui peuvent être utilisées dans les tâches.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{a5f,,Lock}

@tab

Verrou mutex.

@item

@ref{a60,,Event}

@tab

Objet événement.

@item

@ref{a61,,Condition}

@tab

Objet condition.

@item

@ref{a62,,Semaphore}

@tab

Sémaphore.

@item

@ref{a63,,BoundedSemaphore}

@tab

Sémaphore avec des bornes.

@item

@ref{5ec,,Barrier}

@tab

Objet barrière.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{323e,,Utilisation d'asyncio.Event}.

@item 
@ref{324c,,Utilisation d'asyncio.Barrier}.

@item 
Voir aussi la documentation des @ref{31d7,,primitives asyncio de synchronisation}.
@end itemize

@node Exceptions<14>,,Synchronisation,Index de l'API de haut niveau
@anchor{library/asyncio-api-index exceptions}@anchor{3340}
@subsubsection Exceptions



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1b6,,asyncio.CancelledError}

@tab

Levée lorsqu'une tâche est annulée. Voir aussi @ref{1b5,,Task.cancel()}.

@item

@ref{5ed,,asyncio.BrokenBarrierError}

@tab

Levée lorsqu'une barrière est brisée. Voir aussi @ref{324b,,Barrier.wait()}.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{3210,,Utilisation de CancelledError pour exécuter le code sur la demande d'annulation}.

@item 
Voir aussi la liste complète des @ref{3286,,exceptions spécifiques asyncio}.
@end itemize

@node Index de l'API de bas niveau,Programmer avec asyncio,Index de l'API de haut niveau,asyncio --- Asynchronous I/O
@anchor{library/asyncio-llapi-index doc}@anchor{3341}@anchor{library/asyncio-llapi-index low-level-api-index}@anchor{3342}
@subsubsection Index de l'API de bas niveau


Cette page répertorie toutes les API asynchrones de bas niveau.

@menu
* Obtenir une boucle d'évènements:: 
* Méthodes de la boucle d'évènements: Méthodes de la boucle d'évènements<2>. 
* Transports: Transports<2>. 
* Protocoles: Protocoles<2>. 
* Politiques de boucle d'événements:: 

@end menu

@node Obtenir une boucle d'évènements,Méthodes de la boucle d'évènements<2>,,Index de l'API de bas niveau
@anchor{library/asyncio-llapi-index obtaining-the-event-loop}@anchor{3343}
@subsubsection Obtenir une boucle d'évènements



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{af9,,asyncio.get_running_loop()}

@tab

La fonction `préférée' pour obtenir la boucle d'événements en cours d'exécution.

@item

@ref{2bf,,asyncio.get_event_loop()}

@tab

Renvoie une instance de boucle d'événements (en cours d'exécution ou actuelle via la politique actuelle).

@item

@ref{1758,,asyncio.set_event_loop()}

@tab

Définit la boucle d'événements comme actuelle via la politique actuelle.

@item

@ref{31e1,,asyncio.new_event_loop()}

@tab

Crée une nouvelle boucle d'événements.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{32d8,,Utilisation d'asyncio.get_running_loop()}.
@end itemize

@node Méthodes de la boucle d'évènements<2>,Transports<2>,Obtenir une boucle d'évènements,Index de l'API de bas niveau
@anchor{library/asyncio-llapi-index event-loop-methods}@anchor{3344}
@subsubsection Méthodes de la boucle d'évènements


Voir aussi la section principale de la documentation sur les @ref{3293,,Méthodes de la boucle d'évènements}.

@subsubheading Cycle de vie



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{c65,,loop.run_until_complete()}

@tab

Exécute un Future/Task/awaitable jusqu'à ce qu'il soit terminé.

@item

@ref{3295,,loop.run_forever()}

@tab

Exécute la boucle d'événements pour toujours.

@item

@ref{c6a,,loop.stop()}

@tab

Arrête l'exécution de la boucle d'évènements.

@item

@ref{3297,,loop.close()}

@tab

Arrête la boucle d'évènements.

@item

@ref{3296,,loop.is_running()}

@tab

Renvoie @code{True} si la boucle d'événements est en cours d'exécution.

@item

@ref{db1,,loop.is_closed()}

@tab

Renvoie @code{True} si la boucle d'évènements est arrêtée.

@item

@code{await} @ref{c6b,,loop.shutdown_asyncgens()}

@tab

Ferme les générateurs asynchrones.

@end multitable


@subsubheading Débogage



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{daf,,loop.set_debug()}

@tab

Active ou désactive le mode débogage.

@item

@ref{db0,,loop.get_debug()}

@tab

Renvoie le mode de débogage actuel.

@end multitable


@subsubheading Planification des rappels



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{af2,,loop.call_soon()}

@tab

Invoque un rappel bientôt.

@item

@ref{af3,,loop.call_soon_threadsafe()}

@tab

Une variante compatible avec les programmes à fils d'exécution multiples de @ref{af2,,loop.call_soon()}.

@item

@ref{af4,,loop.call_later()}

@tab

Invoque un rappel `après' le temps imparti.

@item

@ref{af5,,loop.call_at()}

@tab

Invoque un rappel `à l'heure' indiquée.

@end multitable


@subsubheading Pool de fils d'exécution ou processus



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{8d6,,loop.run_in_executor()}

@tab

Exécute une fonction utilisant beaucoup de CPU ou une autre fonction bloquante dans un exécuteur @ref{21,,concurrent.futures}.

@item

@ref{72d,,loop.set_default_executor()}

@tab

Définit l'exécuteur par défaut pour @ref{8d6,,loop.run_in_executor()}.

@end multitable


@subsubheading Tâches et `Futures'



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{c67,,loop.create_future()}

@tab

Crée un objet @ref{bbb,,Future}.

@item

@ref{9ca,,loop.create_task()}

@tab

Planifie la coroutine en tant que @ref{4c2,,Task}.

@item

@ref{db3,,loop.set_task_factory()}

@tab

Définit une fabrique utilisée par @ref{9ca,,loop.create_task()} pour créer des @ref{4c2,,Tasks}.

@item

@ref{db4,,loop.get_task_factory()}

@tab

Récupère la fabrique que @ref{9ca,,loop.create_task()} utilise pour créer des @ref{4c2,,Tasks}.

@end multitable


@subsubheading DNS



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{c02,,loop.getaddrinfo()}

@tab

Version asynchrone de @ref{16e0,,socket.getaddrinfo()}.

@item

@code{await} @ref{c03,,loop.getnameinfo()}

@tab

Version asynchrone de @ref{164d,,socket.getnameinfo()}.

@end multitable


@subsubheading Réseau et communication inter-processus



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{5ee,,loop.create_connection()}

@tab

Ouvre une connexion TCP.

@item

@code{await} @ref{b01,,loop.create_server()}

@tab

Crée un serveur TCP.

@item

@code{await} @ref{3218,,loop.create_unix_connection()}

@tab

Ouvre une connexion socket Unix.

@item

@code{await} @ref{1ac,,loop.create_unix_server()}

@tab

Crée un serveur de socket Unix.

@item

@code{await} @ref{b08,,loop.connect_accepted_socket()}

@tab

Enveloppe une @ref{d8e,,socket} dans une paire @code{(transport, protocol)}.

@item

@code{await} @ref{71d,,loop.create_datagram_endpoint()}

@tab

Ouvre une connexion par datagramme (UDP).

@item

@code{await} @ref{32aa,,loop.sendfile()}

@tab

Envoie un fichier via un transport.

@item

@code{await} @ref{af7,,loop.start_tls()}

@tab

Bascule une connexion existante vers TLS.

@item

@code{await} @ref{325b,,loop.connect_read_pipe()}

@tab

Enveloppe une extrémité de lecture d'un tube dans une paire @code{(transport, protocol)}.

@item

@code{await} @ref{325c,,loop.connect_write_pipe()}

@tab

Enveloppe une extrémité d'écriture d'un tube dans une paire @code{(transport, protocol)}.

@end multitable


@subsubheading Interfaces de connexion (`sockets')



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{await} @ref{bff,,loop.sock_recv()}

@tab

Reçoit les données de @ref{d8e,,socket}.

@item

@code{await} @ref{af8,,loop.sock_recv_into()}

@tab

Reçoit les données de @ref{d8e,,socket} dans un tampon.

@item

@code{await} @ref{5f1,,loop.sock_recvfrom()}

@tab

Reçoit un datagramme de @ref{d8e,,socket}.

@item

@code{await} @ref{5f2,,loop.sock_recvfrom_into()}

@tab

Reçoit un datagramme de @ref{d8e,,socket} dans un tampon.

@item

@code{await} @ref{c00,,loop.sock_sendall()}

@tab

Envoie des données à @ref{d8e,,socket}.

@item

@code{await} @ref{5f0,,loop.sock_sendto()}

@tab

Envoie un datagramme via @ref{d8e,,socket} à l'adresse indiquée.

@item

@code{await} @ref{db7,,loop.sock_connect()}

@tab

Connecte la @ref{d8e,,socket}.

@item

@code{await} @ref{c01,,loop.sock_accept()}

@tab

Accepte une connexion @ref{d8e,,socket}.

@item

@code{await} @ref{afc,,loop.sock_sendfile()}

@tab

Envoie un fichier via @ref{d8e,,socket}.

@item

@ref{3233,,loop.add_reader()}

@tab

Commence à observer un descripteur de fichier pour la disponibilité en lecture.

@item

@ref{32ad,,loop.remove_reader()}

@tab

Arrête d'observer un descripteur de fichier pour la disponibilité en lecture.

@item

@ref{32ae,,loop.add_writer()}

@tab

Commence à observer un descripteur de fichier pour la disponibilité en écriture.

@item

@ref{32af,,loop.remove_writer()}

@tab

Arrête d'observer un descripteur de fichier pour la disponibilité en écriture.

@end multitable


@subsubheading Signaux Unix



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{32b7,,loop.add_signal_handler()}

@tab

Ajoute un gestionnaire pour le @ref{c5,,signal}.

@item

@ref{32b8,,loop.remove_signal_handler()}

@tab

Supprime un gestionnaire pour le @ref{c5,,signal}.

@end multitable


@subsubheading Sous-processus



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3258,,loop.subprocess_exec()}

@tab

Crée un sous-processus.

@item

@ref{3259,,loop.subprocess_shell()}

@tab

Crée un sous-processus à partir d'une commande shell.

@end multitable


@subsubheading Gestion des erreurs



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{32bc,,loop.call_exception_handler()}

@tab

Appelle le gestionnaire d'exceptions.

@item

@ref{32bb,,loop.set_exception_handler()}

@tab

Définit un nouveau gestionnaire d'exceptions.

@item

@ref{c68,,loop.get_exception_handler()}

@tab

Renvoie le gestionnaire d'exceptions actuel.

@item

@ref{32bd,,loop.default_exception_handler()}

@tab

Implémentation du gestionnaire d'exceptions par défaut.

@end multitable


@subsubheading Exemples



@itemize *

@item 
@ref{32c8,,Utilisation d'asyncio.new_event_loop() et de loop.run_forever()}.

@item 
@ref{32ca,,Utilisation de loop.call_later()}.

@item 
Utilisation de @code{loop.create_connection()} pour implémenter @ref{322a,,un client écho}.

@item 
Utilisation de @code{loop.create_connection()} pour @ref{3231,,connecter un socket}.

@item 
@ref{3232,,Utilisation de add_reader() pour surveiller un descripteur de fichier pour les événements de lecture}.

@item 
@ref{32cd,,Utilisation de loop.add_signal_handler()}.

@item 
@ref{3270,,Utilisation de loop.subprocess_exec()}.
@end itemize

@node Transports<2>,Protocoles<2>,Méthodes de la boucle d'évènements<2>,Index de l'API de bas niveau
@anchor{library/asyncio-llapi-index transports}@anchor{3345}
@subsubsection Transports


Tous les transports mettent en œuvre les méthodes suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{32a3,,transport.close()}

@tab

Ferme le transport.

@item

@ref{c66,,transport.is_closing()}

@tab

Renvoie @code{True} si le transport se ferme ou est fermé.

@item

@ref{a8a,,transport.get_extra_info()}

@tab

Demande d'informations sur le transport.

@item

@ref{32e8,,transport.set_protocol()}

@tab

Change le protocole.

@item

@ref{32e9,,transport.get_protocol()}

@tab

Renvoie le protocole courant.

@end multitable


Transports pouvant recevoir des données (connexions TCP et Unix, pipes, etc.). Renvoyé par des méthodes telles que @ref{5ee,,loop.create_connection()}, @ref{3218,,loop.create_unix_connection()}, @ref{325b,,loop.connect_read_pipe()}, etc :

@subsubheading Transports en lecture



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{b0a,,transport.is_reading()}

@tab

Renvoie @code{True} si le transport est en cours de réception.

@item

@ref{b0c,,transport.pause_reading()}

@tab

Suspend la réception.

@item

@ref{b0b,,transport.resume_reading()}

@tab

Reprend la réception.

@end multitable


Transports pouvant envoyer des données (connexions TCP et Unix, pipes, etc.). Renvoyé par des méthodes telles que @ref{5ee,,loop.create_connection()}, @ref{3218,,loop.create_unix_connection()}, @ref{325c,,loop.connect_write_pipe()}, etc :

@subsubheading Transports en écriture



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{32f2,,transport.write()}

@tab

Écrit des données dans le transport.

@item

@ref{150a,,transport.writelines()}

@tab

Écrit des tampons dans le transport.

@item

@ref{32ec,,transport.can_write_eof()}

@tab

Renvoie @ref{bfb,,True} si le transport prend en charge l'envoi d'EOF.

@item

@ref{32ed,,transport.write_eof()}

@tab

Ferme et envoie EOF après avoir vidé les données mises en mémoire tampon.

@item

@ref{32c5,,transport.abort()}

@tab

Ferme immédiatement le transport.

@item

@ref{32ee,,transport.get_write_buffer_size()}

@tab

Return the current size of the output buffer.

@item

@ref{db2,,transport.get_write_buffer_limits()}

@tab

Renvoie les seuils haut et bas pour le contrôle du flux d'écriture.

@item

@ref{32ef,,transport.set_write_buffer_limits()}

@tab

Définit de nouvelles bornes hautes et basses pour le contrôle du flux d'écriture.

@end multitable


Transports renvoyés par @ref{71d,,loop.create_datagram_endpoint()} :

@subsubheading Transports par datagrammes



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{1ad,,transport.sendto()}

@tab

Envoie des données au pair distant.

@item

@ref{32f4,,transport.abort()}

@tab

Ferme immédiatement le transport.

@end multitable


Abstraction de transport de bas niveau sur les sous-processus. Renvoyé par @ref{3258,,loop.subprocess_exec()} et @ref{3259,,loop.subprocess_shell()} :

@subsubheading Transports vers des sous-processus



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{32f6,,transport.get_pid()}

@tab

Renvoie l'ID de processus du sous-processus.

@item

@ref{32f7,,transport.get_pipe_transport()}

@tab

Renvoie le transport pour le tube de communication demandé (`stdin', `stdout' ou `stderr').

@item

@ref{32f8,,transport.get_returncode()}

@tab

Renvoie le code de retour du sous-processus.

@item

@ref{32f9,,transport.kill()}

@tab

Tue le sous-processus.

@item

@ref{32fb,,transport.send_signal()}

@tab

Envoie un signal au sous-processus.

@item

@ref{32fa,,transport.terminate()}

@tab

Termine le sous-processus.

@item

@ref{32fc,,transport.close()}

@tab

Tue le sous-processus et ferme tous les tubes.

@end multitable


@node Protocoles<2>,Politiques de boucle d'événements,Transports<2>,Index de l'API de bas niveau
@anchor{library/asyncio-llapi-index protocols}@anchor{3346}
@subsubsection Protocoles


Les classes de protocole peuvent implémenter les `méthodes de rappel' suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{32a1,,connection_made()}

@tab

Appelée lorsqu'une connexion est établie.

@item

@code{callback} @ref{32e4,,connection_lost()}

@tab

Appelé lorsqu'une connexion est perdue ou fermée.

@item

@code{callback} @ref{32f0,,pause_writing()}

@tab

Appelée lorsque la mémoire tampon du transport dépasse le seuil haut.

@item

@code{callback} @ref{32f1,,resume_writing()}

@tab

Appelée lorsque la mémoire tampon du transport passe sous le seuil bas.

@end multitable


@subsubheading Protocoles de flux (TCP, Unix Sockets, Pipes)



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{171b,,data_received()}

@tab

Appelée lorsque certaines données sont reçues.

@item

@code{callback} @ref{3300,,eof_received()}

@tab

Appelée lorsqu'un EOF est reçu.

@end multitable


@subsubheading Protocoles de flux tamponnés



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{3302,,get_buffer()}

@tab

Appelée pour allouer un nouveau tampon de réception.

@item

@code{callback} @ref{3303,,buffer_updated()}

@tab

Appelée lorsque le tampon a été mis à jour avec les données reçues.

@item

@code{callback} @ref{3304,,eof_received()}

@tab

Appelée lorsqu'un EOF est reçu.

@end multitable


@subsubheading Protocoles par datagrammes (non-connectés)



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{3306,,datagram_received()}

@tab

Appelée lorsqu'un datagramme est reçu.

@item

@code{callback} @ref{3307,,error_received()}

@tab

Appelée lorsqu'une opération d'envoi ou de réception précédente lève une @ref{40d,,OSError}.

@end multitable


@subsubheading Protocoles liés aux sous-processus



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{callback} @ref{1752,,pipe_data_received()}

@tab

Appelée lorsqu'un processus enfant écrit sur sa sortie d'erreur ou sa sortie standard.

@item

@code{callback} @ref{3309,,pipe_connection_lost()}

@tab

Appelée lorsqu'un tube de communication avec un sous-processus est fermée.

@item

@code{callback} @ref{1751,,process_exited()}

@tab

Called when the child process has exited. It can be called before
@ref{1752,,pipe_data_received()} and
@ref{3309,,pipe_connection_lost()} methods.

@end multitable


@node Politiques de boucle d'événements,,Protocoles<2>,Index de l'API de bas niveau
@anchor{library/asyncio-llapi-index event-loop-policies}@anchor{3347}
@subsubsection Politiques de boucle d'événements


Les politiques sont un mécanisme de bas niveau pour modifier le comportement de fonctions telles que @ref{2bf,,asyncio.get_event_loop()}. Voir aussi la section principale @ref{328d,,Politiques} pour plus de détails.

@subsubheading Accès aux politiques



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@ref{3318,,asyncio.get_event_loop_policy()}

@tab

Renvoie la politique actuelle à l'échelle du processus.

@item

@ref{3319,,asyncio.set_event_loop_policy()}

@tab

Définit une nouvelle politique à l'échelle du processus.

@item

@ref{3316,,AbstractEventLoopPolicy}

@tab

Classe mère pour les objets de politique.

@end multitable


@node Programmer avec asyncio,,Index de l'API de bas niveau,asyncio --- Asynchronous I/O
@anchor{library/asyncio-dev doc}@anchor{3348}@anchor{library/asyncio-dev asyncio-dev}@anchor{3349}@anchor{library/asyncio-dev developing-with-asyncio}@anchor{334a}
@subsubsection Programmer avec `asyncio'


La programmation asynchrone est différente de la programmation « séquentielle » classique.

Cette page liste les pièges et erreurs communs que le développeur pourrait rencontrer et décrit comment les éviter.

@menu
* Mode débogage:: 
* Programmation concurrente et multi-fils:: 
* Exécution de code bloquant:: 
* Journalisation: Journalisation<3>. 
* Détection des coroutines jamais attendues:: 
* Détection des exceptions jamais récupérées:: 

@end menu

@node Mode débogage,Programmation concurrente et multi-fils,,Programmer avec asyncio
@anchor{library/asyncio-dev asyncio-debug-mode}@anchor{1cdb}@anchor{library/asyncio-dev debug-mode}@anchor{334b}
@subsubsection Mode débogage


Par défaut, `asyncio' s'exécute en mode production. Pour faciliter le développement, `asyncio' possède un « mode débogage ».

Il existe plusieurs façons d'activer le mode débogage de `asyncio' :


@itemize *

@item 
en réglant la variable d’environnement 
@geindex PYTHONASYNCIODEBUG
@geindex variable d'environnement; PYTHONASYNCIODEBUG
@ref{1cda,,PYTHONASYNCIODEBUG} à @code{1} ;

@item 
en utilisant le mode développement de Python (@ref{1f5,,Python Development Mode}) ;

@item 
en passant @code{debug=True} à la fonction @ref{466,,asyncio.run()} ;

@item 
en appelant la méthode @ref{daf,,loop.set_debug()}.
@end itemize

En plus d'activer le mode débogage, vous pouvez également :


@itemize *

@item 
setting the log level of the @ref{334c,,asyncio logger} to
@ref{1c7f,,logging.DEBUG}, for example the following snippet of code
can be run at startup of the application:

@example
logging.basicConfig(level=logging.DEBUG)
@end example

@item 
configurer le module @ref{111,,warnings} afin d'afficher les avertissements de type @ref{241,,ResourceWarning} ; vous pouvez faire cela en utilisant l'option @ref{8b4,,-W} @code{default} sur la ligne de commande.
@end itemize

Lorsque le mode débogage est activé :


@itemize *

@item 
`asyncio' surveille les @ref{334d,,coroutines qui ne sont jamais attendues} et les journalise ; cela atténue le problème des « `await' oubliés » ;

@item 
beaucoup d'`API' `asyncio' ne prenant pas en charge les fils d'exécution multiples (comme les méthodes @ref{af2,,loop.call_soon()} et @ref{af5,,loop.call_at()}) lèvent une exception si elles sont appelées par le mauvais fil d’exécution ;

@item 
le temps d'exécution du sélecteur d'entrée-sortie est journalisé si une opération prend trop de temps à s'effectuer ;

@item 
les fonctions de rappel prenant plus de 100 ms sont journalisées ; l'attribut @ref{32bf,,loop.slow_callback_duration} peut être utilisé pour changer la limite (en secondes) après laquelle une fonction de rappel est considérée comme « lente ».
@end itemize

@node Programmation concurrente et multi-fils,Exécution de code bloquant,Mode débogage,Programmer avec asyncio
@anchor{library/asyncio-dev asyncio-multithreading}@anchor{3202}@anchor{library/asyncio-dev concurrency-and-multithreading}@anchor{334e}
@subsubsection Programmation concurrente et multi-fils


Une boucle d'évènements s'exécute dans un fil d’exécution (typiquement dans le fil principal) et traite toutes les fonctions de rappel (`callbacks') ainsi que toutes les tâches dans ce même fil. Lorsqu'une tâche est en cours d'exécution dans la boucle d'évènements, aucune autre tâche ne peut s'exécuter dans ce fil. Quand une tâche traite une expression @code{await}, elle se suspend et laisse la boucle d’évènements traiter la tâche suivante.

Pour planifier un @ref{2893,,rappel} depuis un autre fil d'exécution système, utilisez la méthode @ref{af3,,loop.call_soon_threadsafe()}. Par exemple :

@example
loop.call_soon_threadsafe(callback, *args)
@end example

La plupart des objets `asyncio' ne sont pas conçus pour être exécutés dans un contexte multi-fils (`thread-safe') mais cela n'est en général pas un problème à moins que l'objet ne fasse appel à du code se trouvant en dehors d'une tâche ou d'une fonction de rappel. Dans ce dernier cas, si le code appelle les `API' bas niveau de `asyncio', utilisez la méthode @ref{af3,,loop.call_soon_threadsafe()}. Par exemple :

@example
loop.call_soon_threadsafe(fut.cancel)
@end example

Pour planifier un objet concurrent depuis un autre fil d'exécution système, utilisez @ref{86e,,run_coroutine_threadsafe()}. Cette fonction renvoie un objet @ref{118f,,concurrent.futures.Future} pour accéder au résultat :

@example
async def coro_func():
     return await asyncio.sleep(1, 42)

# Later in another OS thread:

future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
# Wait for the result:
result = future.result()
@end example

To handle signals the event loop must be
run in the main thread.

La méthode @ref{8d6,,loop.run_in_executor()} peut être utilisée avec @ref{72c,,concurrent.futures.ThreadPoolExecutor} pour exécuter du code bloquant dans un autre fil d'exécution, afin de ne pas bloquer le fil où la boucle d'évènements se trouve.

Il n'y a actuellement aucune façon de planifier des coroutines ou des rappels directement depuis un autre processus (comme, par exemple, un processus démarré avec @ref{93,,multiprocessing}). La section @ref{d66,,Méthodes de la boucle d'évènements} liste les `API' pouvant lire les tubes (`pipes') et surveiller les descripteurs de fichiers sans bloquer la boucle d'évènements. De plus, les `API' @ref{31d5,,Subprocess} d'`asyncio' fournissent un moyen de démarrer un processus et de communiquer avec lui depuis la boucle d'évènements. Enfin, la méthode @ref{8d6,,loop.run_in_executor()} susmentionnée peut également être utilisée avec @ref{8db,,concurrent.futures.ProcessPoolExecutor} pour exécuter du code dans un processus différent.

@node Exécution de code bloquant,Journalisation<3>,Programmation concurrente et multi-fils,Programmer avec asyncio
@anchor{library/asyncio-dev asyncio-handle-blocking}@anchor{334f}@anchor{library/asyncio-dev running-blocking-code}@anchor{3350}
@subsubsection Exécution de code bloquant


Du code bloquant sur des opérations de calcul (`CPU-bound') ne devrait pas être appelé directement. Par exemple, si une fonction effectue des calculs utilisant le CPU intensivement pendant une seconde, toutes les tâches `asyncio' concurrentes et les opérations d'entrées-sorties seront bloquées pour une seconde.

Un exécuteur peut être utilisé pour traiter une tâche dans un fil d'exécution ou un processus différent, afin d'éviter de bloquer le fil d'exécution système dans lequel se trouve la boucle d’évènements. Voir @ref{8d6,,loop.run_in_executor()} pour plus de détails.

@node Journalisation<3>,Détection des coroutines jamais attendues,Exécution de code bloquant,Programmer avec asyncio
@anchor{library/asyncio-dev asyncio-logger}@anchor{334c}@anchor{library/asyncio-dev logging}@anchor{3351}
@subsubsection Journalisation


`Asyncio' utilise le module @ref{86,,logging}. Toutes les opérations de journalisation sont effectuées via l'enregistreur (`logger') @code{"asyncio"}.

The default log level is @ref{1c80,,logging.INFO}, which can be easily
adjusted:

@example
logging.getLogger("asyncio").setLevel(logging.WARNING)
@end example

La journalisation réseau peut bloquer la boucle d'événements. Il est recommandé d'utiliser un fil d'exécution séparé pour gérer les journaux ou d'utiliser des entrées-sorties non bloquantes. Par exemple, voir @ref{3352,,Utilisation de gestionnaires bloquants}.

@node Détection des coroutines jamais attendues,Détection des exceptions jamais récupérées,Journalisation<3>,Programmer avec asyncio
@anchor{library/asyncio-dev asyncio-coroutine-not-scheduled}@anchor{334d}@anchor{library/asyncio-dev detect-never-awaited-coroutines}@anchor{3353}
@subsubsection Détection des coroutines jamais attendues


Lorsqu'une fonction coroutine est appelée mais qu'elle n'est pas attendue (p. ex.  @code{coro()} au lieu de @code{await coro()}) ou si la coroutine n'est pas planifiée avec @ref{5e7,,asyncio.create_task()}, `asyncio' émet un @ref{1bb,,RuntimeWarning} :

@example
import asyncio

async def test():
    print("never scheduled")

async def main():
    test()

asyncio.run(main())
@end example

Sortie :

@example
test.py:7: RuntimeWarning: coroutine 'test' was never awaited
  test()
@end example

Affichage en mode débogage :

@example
test.py:7: RuntimeWarning: coroutine 'test' was never awaited
Coroutine created at (most recent call last)
  File "../t.py", line 9, in <module>
    asyncio.run(main(), debug=True)

  < .. >

  File "../t.py", line 7, in main
    test()
  test()
@end example

La façon habituelle de régler ce problème est d'attendre (`await') la coroutine ou bien d'appeler la fonction @ref{5e7,,asyncio.create_task()} :

@example
async def main():
    await test()
@end example

@node Détection des exceptions jamais récupérées,,Détection des coroutines jamais attendues,Programmer avec asyncio
@anchor{library/asyncio-dev detect-never-retrieved-exceptions}@anchor{3354}
@subsubsection Détection des exceptions jamais récupérées


Si la méthode @ref{3207,,Future.set_exception()} est appelée mais que l'objet `Future' n'est pas attendu, l'exception n'est pas propagée au code utilisateur. Dans ce cas, `asyncio' écrit un message dans le journal lorsque l'objet `Future' est récupéré par le ramasse-miette.

Exemple d'une exception non-gérée :

@example
import asyncio

async def bug():
    raise Exception("not consumed")

async def main():
    asyncio.create_task(bug())

asyncio.run(main())
@end example

Sortie :

@example
Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
  exception=Exception('not consumed')>

Traceback (most recent call last):
  File "test.py", line 4, in bug
    raise Exception("not consumed")
Exception: not consumed
@end example

@ref{1cdb,,Activez le mode débogage} pour récupérer la trace d'appels indiquant où la tâche a été créée :

@example
asyncio.run(main(), debug=True)
@end example

Affichage en mode débogage :

@example
Task exception was never retrieved
future: <Task finished coro=<bug() done, defined at test.py:3>
    exception=Exception('not consumed') created at asyncio/tasks.py:321>

source_traceback: Object created at (most recent call last):
  File "../t.py", line 9, in <module>
    asyncio.run(main(), debug=True)

< .. >

Traceback (most recent call last):
  File "../t.py", line 4, in bug
    raise Exception("not consumed")
Exception: not consumed
@end example

@cartouche
@quotation Note 
Le code source d'@code{asyncio} est disponible dans Lib/asyncio/@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/}.
@end quotation
@end cartouche

@node socket --- Low-level networking interface,ssl --- TLS/SSL wrapper for socket objects,asyncio --- Asynchronous I/O,Réseau et communication entre processus
@anchor{library/socket doc}@anchor{3355}@anchor{library/socket module-socket}@anchor{cb}@anchor{library/socket socket-low-level-networking-interface}@anchor{3356}
@subsection @code{socket} --- Low-level networking interface


@geindex module; socket

`Code source :' Lib/secrets.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/secrets.py}


__________________________________________________________________


This module provides access to the BSD `socket' interface. It is available on
all modern Unix systems, Windows, MacOS, and probably additional platforms.

@cartouche
@quotation Note 
Some behavior may be platform dependent, since calls are made to the operating
system socket APIs.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@geindex object;socket

The Python interface is a straightforward transliteration of the Unix system
call and library interface for sockets to Python's object-oriented style: the
@ref{d8e,,socket()} function returns a `socket object' whose methods implement
the various socket system calls.  Parameter types are somewhat higher-level than
in the C interface: as with @code{read()} and @code{write()} operations on Python
files, buffer allocation on receive operations is automatic, and buffer length
is implicit on send operations.


@subsubheading Voir aussi



@table @asis

@item Module @ref{cc,,socketserver}

Classes that simplify writing network servers.

@item Module @ref{cf,,ssl}

A TLS/SSL wrapper for socket objects.
@end table


@menu
* Socket families:: 
* Module contents:: 
* Socket Objects:: 
* Notes on socket timeouts:: 
* Exemple: Exemple<7>. 

@end menu

@node Socket families,Module contents,,socket --- Low-level networking interface
@anchor{library/socket socket-families}@anchor{3357}
@subsubsection Socket families


Depending on the system and the build options, various socket families
are supported by this module.

The address format required by a particular socket object is automatically
selected based on the address family specified when the socket object was
created.  Socket addresses are represented as follows:


@itemize -

@item 
The address of an @ref{17ad,,AF_UNIX} socket bound to a file system node
is represented as a string, using the file system encoding and the
@code{'surrogateescape'} error handler (see 
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/}).  An address in
Linux's abstract namespace is returned as a @ref{d1b,,bytes-like object} with
an initial null byte; note that sockets in this namespace can
communicate with normal file system sockets, so programs intended to
run on Linux may need to deal with both types of address.  A string or
bytes-like object can be used for either type of address when
passing it as an argument.


Modifié dans la version 3.3: Previously, @ref{17ad,,AF_UNIX} socket paths were assumed to use UTF-8
encoding.



Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end itemize
@anchor{library/socket host-port}@anchor{3358}

@itemize -

@item 
A pair @code{(host, port)} is used for the @ref{17ab,,AF_INET} address family,
where `host' is a string representing either a hostname in internet domain
notation like @code{'daring.cwi.nl'} or an IPv4 address like @code{'100.50.200.5'},
and `port' is an integer.


@itemize -

@item 
For IPv4 addresses, two special forms are accepted instead of a host
address: @code{'@w{'}} represents @code{INADDR_ANY}, which is used to bind to all
interfaces, and the string @code{'<broadcast>'} represents
@code{INADDR_BROADCAST}.  This behavior is not compatible with IPv6,
therefore, you may want to avoid these if you intend to support IPv6 with your
Python programs.
@end itemize

@item 
For @ref{17ac,,AF_INET6} address family, a four-tuple @code{(host, port, flowinfo,
scope_id)} is used, where `flowinfo' and `scope_id' represent the @code{sin6_flowinfo}
and @code{sin6_scope_id} members in @code{struct sockaddr_in6} in C.  For
@ref{cb,,socket} module methods, `flowinfo' and `scope_id' can be omitted just for
backward compatibility.  Note, however, omission of `scope_id' can cause problems
in manipulating scoped IPv6 addresses.


Modifié dans la version 3.7: For multicast addresses (with `scope_id' meaningful) `address' may not contain
@code{%scope_id} (or @code{zone id}) part. This information is superfluous and may
be safely omitted (recommended).


@item 
@code{AF_NETLINK} sockets are represented as pairs @code{(pid, groups)}.

@item 
Linux-only support for TIPC is available using the @code{AF_TIPC}
address family.  TIPC is an open, non-IP based networked protocol designed
for use in clustered computer environments.  Addresses are represented by a
tuple, and the fields depend on the address type. The general tuple form is
@code{(addr_type, v1, v2, v3 [, scope])}, where:


@itemize -

@item 
`addr_type' is one of @code{TIPC_ADDR_NAMESEQ}, @code{TIPC_ADDR_NAME},
or @code{TIPC_ADDR_ID}.

@item 
`scope' is one of @code{TIPC_ZONE_SCOPE}, @code{TIPC_CLUSTER_SCOPE}, and
@code{TIPC_NODE_SCOPE}.

@item 
If `addr_type' is @code{TIPC_ADDR_NAME}, then `v1' is the server type, `v2' is
the port identifier, and `v3' should be 0.

If `addr_type' is @code{TIPC_ADDR_NAMESEQ}, then `v1' is the server type, `v2'
is the lower port number, and `v3' is the upper port number.

If `addr_type' is @code{TIPC_ADDR_ID}, then `v1' is the node, `v2' is the
reference, and `v3' should be set to 0.
@end itemize

@item 
A tuple @code{(interface, )} is used for the @ref{3359,,AF_CAN} address family,
where `interface' is a string representing a network interface name like
@code{'can0'}. The network interface name @code{'@w{'}} can be used to receive packets
from all network interfaces of this family.


@itemize -

@item 
@ref{335a,,CAN_ISOTP} protocol require a tuple @code{(interface, rx_addr, tx_addr)}
where both additional parameters are unsigned long integer that represent a
CAN identifier (standard or extended).

@item 
@ref{91f,,CAN_J1939} protocol require a tuple @code{(interface, name, pgn, addr)}
where additional parameters are 64-bit unsigned integer representing the
ECU name, a 32-bit unsigned integer representing the Parameter Group Number
(PGN), and an 8-bit integer representing the address.
@end itemize

@item 
A string or a tuple @code{(id, unit)} is used for the @code{SYSPROTO_CONTROL}
protocol of the @code{PF_SYSTEM} family. The string is the name of a
kernel control using a dynamically assigned ID. The tuple can be used if ID
and unit number of the kernel control are known or if a registered ID is
used.


Ajouté dans la version 3.3.


@item 
@code{AF_BLUETOOTH} supports the following protocols and address
formats:


@itemize -

@item 
@code{BTPROTO_L2CAP} accepts @code{(bdaddr, psm)} where @code{bdaddr} is
the Bluetooth address as a string and @code{psm} is an integer.

@item 
@code{BTPROTO_RFCOMM} accepts @code{(bdaddr, channel)} where @code{bdaddr}
is the Bluetooth address as a string and @code{channel} is an integer.

@item 
@code{BTPROTO_HCI} accepts @code{(device_id,)} where @code{device_id} is
either an integer or a string with the Bluetooth address of the
interface. (This depends on your OS; NetBSD and DragonFlyBSD expect
a Bluetooth address while everything else expects an integer.)


Modifié dans la version 3.2: NetBSD and DragonFlyBSD support added.


@item 
@code{BTPROTO_SCO} accepts @code{bdaddr} where @code{bdaddr} is a
@ref{1bd,,bytes} object containing the Bluetooth address in a
string format. (ex. @code{b'12:23:34:45:56:67'}) This protocol is not
supported under FreeBSD.
@end itemize

@item 
@ref{cc5,,AF_ALG} is a Linux-only socket based interface to Kernel
cryptography. An algorithm socket is configured with a tuple of two to four
elements @code{(type, name [, feat [, mask]])}, where:


@itemize -

@item 
`type' is the algorithm type as string, e.g. @code{aead}, @code{hash},
@code{skcipher} or @code{rng}.

@item 
`name' is the algorithm name and operation mode as string, e.g.
@code{sha256}, @code{hmac(sha256)}, @code{cbc(aes)} or @code{drbg_nopr_ctr_aes256}.

@item 
`feat' and `mask' are unsigned 32bit integers.
@end itemize

@ref{1ce0,,Availability}: Linux >= 2.6.38.

Some algorithm types require more recent Kernels.


Ajouté dans la version 3.6.


@item 
@ref{b63,,AF_VSOCK} allows communication between virtual machines and
their hosts. The sockets are represented as a @code{(CID, port)} tuple
where the context ID or CID and port are integers.

@ref{1ce0,,Availability}: Linux >= 3.9

See @code{vsock(7)@footnote{https://manpages.debian.org/vsock(7)}}


Ajouté dans la version 3.7.


@item 
@ref{335b,,AF_PACKET} is a low-level interface directly to network devices.
The addresses are represented by the tuple
@code{(ifname, proto[, pkttype[, hatype[, addr]]])} where:


@itemize -

@item 
`ifname' - String specifying the device name.

@item 
`proto' - The Ethernet protocol number.
May be @ref{1736,,ETH_P_ALL} to capture all protocols,
one of the @ref{1737,,ETHERTYPE_* constants}
or any other Ethernet protocol number.

@item 
`pkttype' - Optional integer specifying the packet type:


@itemize -

@item 
@code{PACKET_HOST} (the default) - Packet addressed to the local host.

@item 
@code{PACKET_BROADCAST} - Physical-layer broadcast packet.

@item 
@code{PACKET_MULTICAST} - Packet sent to a physical-layer multicast address.

@item 
@code{PACKET_OTHERHOST} - Packet to some other host that has been caught by
a device driver in promiscuous mode.

@item 
@code{PACKET_OUTGOING} - Packet originating from the local host that is
looped back to a packet socket.
@end itemize

@item 
`hatype' - Optional integer specifying the ARP hardware address type.

@item 
`addr' - Optional bytes-like object specifying the hardware physical
address, whose interpretation depends on the device.
@end itemize

@ref{1ce0,,Availability}: Linux >= 2.2.

@item 
@ref{335c,,AF_QIPCRTR} is a Linux-only socket based interface for communicating
with services running on co-processors in Qualcomm platforms. The address
family is represented as a @code{(node, port)} tuple where the `node' and `port'
are non-negative integers.

@ref{1ce0,,Availability}: Linux >= 4.7.


Ajouté dans la version 3.8.


@item 
@code{IPPROTO_UDPLITE} is a variant of UDP which allows you to specify
what portion of a packet is covered with the checksum. It adds two socket
options that you can change.
@code{self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length)} will
change what portion of outgoing packets are covered by the checksum and
@code{self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length)} will
filter out packets which cover too little of their data. In both cases
@code{length} should be in @code{range(8, 2**16, 8)}.

Such a socket should be constructed with
@code{socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)} for IPv4 or
@code{socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)} for IPv6.

@ref{1ce0,,Availability}: Linux >= 2.6.20, FreeBSD >= 10.1


Ajouté dans la version 3.9.


@item 
@ref{335d,,AF_HYPERV} is a Windows-only socket based interface for communicating
with Hyper-V hosts and guests. The address family is represented as a
@code{(vm_id, service_id)} tuple where the @code{vm_id} and @code{service_id} are
UUID strings.

The @code{vm_id} is the virtual machine identifier or a set of known VMID values
if the target is not a specific virtual machine. Known VMID constants
defined on @code{socket} are:


@itemize -

@item 
@code{HV_GUID_ZERO}

@item 
@code{HV_GUID_BROADCAST}

@item 
@code{HV_GUID_WILDCARD} - Used to bind on itself and accept connections from
all partitions.

@item 
@code{HV_GUID_CHILDREN} - Used to bind on itself and accept connection from
child partitions.

@item 
@code{HV_GUID_LOOPBACK} - Used as a target to itself.

@item 
@code{HV_GUID_PARENT} - When used as a bind accepts connection from the parent
partition. When used as an address target it will connect to the parent partition.
@end itemize

The @code{service_id} is the service identifier of the registered service.


Ajouté dans la version 3.12.

@end itemize

If you use a hostname in the `host' portion of IPv4/v6 socket address, the
program may show a nondeterministic behavior, as Python uses the first address
returned from the DNS resolution.  The socket address will be resolved
differently into an actual IPv4/v6 address, depending on the results from DNS
resolution and/or the host configuration.  For deterministic behavior use a
numeric address in `host' portion.

All errors raise exceptions.  The normal exceptions for invalid argument types
and out-of-memory conditions can be raised. Errors
related to socket or address semantics raise @ref{40d,,OSError} or one of its
subclasses.

Non-blocking mode is supported through @ref{2ac5,,setblocking()}.  A
generalization of this based on timeouts is supported through
@ref{335e,,settimeout()}.

@node Module contents,Socket Objects,Socket families,socket --- Low-level networking interface
@anchor{library/socket module-contents}@anchor{335f}
@subsubsection Module contents


The module @ref{cb,,socket} exports the following elements.

@menu
* Exceptions: Exceptions<15>. 
* Constantes: Constantes<8>. 
* Fonctions: Fonctions<8>. 

@end menu

@node Exceptions<15>,Constantes<8>,,Module contents
@anchor{library/socket exceptions}@anchor{3360}
@subsubsection Exceptions


@geindex error
@anchor{library/socket socket error}@anchor{103e}
@deffn {Exception} socket.error

A deprecated alias of @ref{40d,,OSError}.


Modifié dans la version 3.3: Following 
@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/}, this class was made an alias of @ref{40d,,OSError}.

@end deffn

@geindex herror
@anchor{library/socket socket herror}@anchor{3361}
@deffn {Exception} socket.herror

A subclass of @ref{40d,,OSError}, this exception is raised for
address-related errors, i.e. for functions that use `h_errno' in the POSIX
C API, including @ref{185b,,gethostbyname_ex()} and @ref{185a,,gethostbyaddr()}.
The accompanying value is a pair @code{(h_errno, string)} representing an
error returned by a library call.  `h_errno' is a numeric value, while
`string' represents the description of `h_errno', as returned by the
@code{hstrerror()} C function.


Modifié dans la version 3.3: This class was made a subclass of @ref{40d,,OSError}.

@end deffn

@geindex gaierror
@anchor{library/socket socket gaierror}@anchor{16e1}
@deffn {Exception} socket.gaierror

A subclass of @ref{40d,,OSError}, this exception is raised for
address-related errors by @ref{16e0,,getaddrinfo()} and @ref{164d,,getnameinfo()}.
The accompanying value is a pair @code{(error, string)} representing an error
returned by a library call.  `string' represents the description of
`error', as returned by the @code{gai_strerror()} C function.  The
numeric `error' value will match one of the @code{EAI_*} constants
defined in this module.


Modifié dans la version 3.3: This class was made a subclass of @ref{40d,,OSError}.

@end deffn

@geindex timeout
@anchor{library/socket socket timeout}@anchor{81e}
@deffn {Exception} socket.timeout

A deprecated alias of @ref{81f,,TimeoutError}.

A subclass of @ref{40d,,OSError}, this exception is raised when a timeout
occurs on a socket which has had timeouts enabled via a prior call to
@ref{335e,,settimeout()} (or implicitly through
@ref{3362,,setdefaulttimeout()}).  The accompanying value is a string
whose value is currently always "timed out".


Modifié dans la version 3.3: This class was made a subclass of @ref{40d,,OSError}.



Modifié dans la version 3.10: cette classe est devenue un alias de @ref{81f,,TimeoutError}.

@end deffn

@node Constantes<8>,Fonctions<8>,Exceptions<15>,Module contents
@anchor{library/socket constants}@anchor{3363}
@subsubsection Constantes


@quotation

The AF_* and SOCK_* constants are now @code{AddressFamily} and
@code{SocketKind} @ref{ccd,,IntEnum} collections.


Ajouté dans la version 3.4.

@end quotation

@geindex AF_UNIX (dans le module socket)
@geindex AF_INET (dans le module socket)
@geindex AF_INET6 (dans le module socket)
@anchor{library/socket socket AF_UNIX}@anchor{17ad}
@deffn {Données} socket.AF_UNIX
@anchor{library/socket socket AF_INET}@anchor{17ab}
@deffnx {Données} socket.AF_INET
@anchor{library/socket socket AF_INET6}@anchor{17ac}
@deffnx {Données} socket.AF_INET6

These constants represent the address (and protocol) families, used for the
first argument to @ref{d8e,,socket()}.  If the @ref{17ad,,AF_UNIX} constant is not
defined then this protocol is unsupported.  More constants may be available
depending on the system.
@end deffn

@geindex AF_UNSPEC (dans le module socket)
@anchor{library/socket socket AF_UNSPEC}@anchor{32a8}
@deffn {Données} socket.AF_UNSPEC

@ref{32a8,,AF_UNSPEC} means that
@ref{16e0,,getaddrinfo()} should return socket addresses for any
address family (either IPv4, IPv6, or any other) that can be used.
@end deffn

@geindex SOCK_STREAM (dans le module socket)
@geindex SOCK_DGRAM (dans le module socket)
@geindex SOCK_RAW (dans le module socket)
@geindex SOCK_RDM (dans le module socket)
@geindex SOCK_SEQPACKET (dans le module socket)
@anchor{library/socket socket SOCK_STREAM}@anchor{12d1}
@deffn {Données} socket.SOCK_STREAM
@anchor{library/socket socket SOCK_DGRAM}@anchor{12d0}
@deffnx {Données} socket.SOCK_DGRAM
@anchor{library/socket socket SOCK_RAW}@anchor{3364}
@deffnx {Données} socket.SOCK_RAW
@anchor{library/socket socket SOCK_RDM}@anchor{3365}
@deffnx {Données} socket.SOCK_RDM
@anchor{library/socket socket SOCK_SEQPACKET}@anchor{3366}
@deffnx {Données} socket.SOCK_SEQPACKET

These constants represent the socket types, used for the second argument to
@ref{d8e,,socket()}.  More constants may be available depending on the system.
(Only @ref{12d1,,SOCK_STREAM} and @ref{12d0,,SOCK_DGRAM} appear to be generally
useful.)
@end deffn

@geindex SOCK_CLOEXEC (dans le module socket)
@geindex SOCK_NONBLOCK (dans le module socket)
@anchor{library/socket socket SOCK_CLOEXEC}@anchor{bf9}
@deffn {Données} socket.SOCK_CLOEXEC
@anchor{library/socket socket SOCK_NONBLOCK}@anchor{bf8}
@deffnx {Données} socket.SOCK_NONBLOCK

These two constants, if defined, can be combined with the socket types and
allow you to set some flags atomically (thus avoiding possible race
conditions and the need for separate calls).


@subsubheading Voir aussi


Secure File Descriptor Handling@footnote{https://udrepper.livejournal.com/20407.html}
for a more thorough explanation.


@ref{1ce0,,Availability}: Linux >= 2.6.27.


Ajouté dans la version 3.2.

@end deffn

@geindex SOMAXCONN (dans le module socket)
@anchor{library/socket socket-unix-constants}@anchor{32a4}
@deffn {Données} SO_*
@anchor{library/socket socket SOMAXCONN}@anchor{e48}
@deffnx {Données} socket.SOMAXCONN

@deffnx {Données} MSG_*

@deffnx {Données} SOL_*

@deffnx {Données} SCM_*

@deffnx {Données} IPPROTO_*

@deffnx {Données} IPPORT_*

@deffnx {Données} INADDR_*

@deffnx {Données} IP_*

@deffnx {Données} IPV6_*

@deffnx {Données} EAI_*

@deffnx {Données} AI_*

@deffnx {Données} NI_*

@deffnx {Données} TCP_*

Many constants of these forms, documented in the Unix documentation on sockets
and/or the IP protocol, are also defined in the socket module. They are
generally used in arguments to the @ref{cc4,,setsockopt()} and @ref{cc3,,getsockopt()}
methods of socket objects.  In most cases, only those symbols that are defined
in the Unix header files are defined; for a few symbols, default values are
provided.


Modifié dans la version 3.6: @code{SO_DOMAIN}, @code{SO_PROTOCOL}, @code{SO_PEERSEC}, @code{SO_PASSSEC},
@code{TCP_USER_TIMEOUT}, @code{TCP_CONGESTION} were added.



Modifié dans la version 3.6.5: On Windows, @code{TCP_FASTOPEN}, @code{TCP_KEEPCNT} appear if run-time Windows
supports.



Modifié dans la version 3.7: @code{TCP_NOTSENT_LOWAT} was added.

On Windows, @code{TCP_KEEPIDLE}, @code{TCP_KEEPINTVL} appear if run-time Windows
supports.



Modifié dans la version 3.10: @code{IP_RECVTOS} was added.
 Added @code{TCP_KEEPALIVE}. On MacOS this constant can be used in the same
 way that @code{TCP_KEEPIDLE} is used on Linux.



Modifié dans la version 3.11: Added @code{TCP_CONNECTION_INFO}. On MacOS this constant can be used in the
same way that @code{TCP_INFO} is used on Linux and BSD.



Modifié dans la version 3.12: Added @code{SO_RTABLE} and @code{SO_USER_COOKIE}. On OpenBSD
and FreeBSD respectively those constants can be used in the same way that
@code{SO_MARK} is used on Linux. Also added missing TCP socket options from
Linux: @code{TCP_MD5SIG}, @code{TCP_THIN_LINEAR_TIMEOUTS}, @code{TCP_THIN_DUPACK},
@code{TCP_REPAIR}, @code{TCP_REPAIR_QUEUE}, @code{TCP_QUEUE_SEQ},
@code{TCP_REPAIR_OPTIONS}, @code{TCP_TIMESTAMP}, @code{TCP_CC_INFO},
@code{TCP_SAVE_SYN}, @code{TCP_SAVED_SYN}, @code{TCP_REPAIR_WINDOW},
@code{TCP_FASTOPEN_CONNECT}, @code{TCP_ULP}, @code{TCP_MD5SIG_EXT},
@code{TCP_FASTOPEN_KEY}, @code{TCP_FASTOPEN_NO_COOKIE},
@code{TCP_ZEROCOPY_RECEIVE}, @code{TCP_INQ}, @code{TCP_TX_DELAY}.
Added @code{IP_PKTINFO}, @code{IP_UNBLOCK_SOURCE}, @code{IP_BLOCK_SOURCE},
@code{IP_ADD_SOURCE_MEMBERSHIP}, @code{IP_DROP_SOURCE_MEMBERSHIP}.



Modifié dans la version 3.13: Added @code{SO_BINDTOIFINDEX}. On Linux this constant can be used in the
same way that @code{SO_BINDTODEVICE} is used, but with the index of a
network interface instead of its name.

@end deffn

@geindex AF_CAN (dans le module socket)
@geindex PF_CAN (dans le module socket)
@anchor{library/socket socket AF_CAN}@anchor{3359}
@deffn {Données} socket.AF_CAN
@anchor{library/socket socket PF_CAN}@anchor{3367}
@deffnx {Données} socket.PF_CAN

@deffnx {Données} SOL_CAN_*

@deffnx {Données} CAN_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{1ce0,,Availability}: Linux >= 2.6.25, NetBSD >= 8.


Ajouté dans la version 3.3.



Modifié dans la version 3.11: NetBSD support was added.

@end deffn

@geindex CAN_BCM (dans le module socket)
@anchor{library/socket socket CAN_BCM}@anchor{f8d}
@deffn {Données} socket.CAN_BCM

@deffnx {Données} CAN_BCM_*

CAN_BCM, in the CAN protocol family, is the broadcast manager (BCM) protocol.
Broadcast manager constants, documented in the Linux documentation, are also
defined in the socket module.

@ref{1ce0,,Availability}: Linux >= 2.6.25.

@cartouche
@quotation Note 
The @code{CAN_BCM_CAN_FD_FRAME} flag is only available on Linux >= 4.8.
@end quotation
@end cartouche


Ajouté dans la version 3.4.

@end deffn

@geindex CAN_RAW_FD_FRAMES (dans le module socket)
@anchor{library/socket socket CAN_RAW_FD_FRAMES}@anchor{eb3}
@deffn {Données} socket.CAN_RAW_FD_FRAMES

Enables CAN FD support in a CAN_RAW socket. This is disabled by default.
This allows your application to send both CAN and CAN FD frames; however,
you must accept both CAN and CAN FD frames when reading from the socket.

This constant is documented in the Linux documentation.

@ref{1ce0,,Availability}: Linux >= 3.6.


Ajouté dans la version 3.5.

@end deffn

@geindex CAN_RAW_JOIN_FILTERS (dans le module socket)
@anchor{library/socket socket CAN_RAW_JOIN_FILTERS}@anchor{91e}
@deffn {Données} socket.CAN_RAW_JOIN_FILTERS

Joins the applied CAN filters such that only CAN frames that match all
given CAN filters are passed to user space.

This constant is documented in the Linux documentation.

@ref{1ce0,,Availability}: Linux >= 4.1.


Ajouté dans la version 3.9.

@end deffn

@geindex CAN_ISOTP (dans le module socket)
@anchor{library/socket socket CAN_ISOTP}@anchor{335a}
@deffn {Données} socket.CAN_ISOTP

CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
ISO-TP constants, documented in the Linux documentation.

@ref{1ce0,,Availability}: Linux >= 2.6.25.


Ajouté dans la version 3.7.

@end deffn

@geindex CAN_J1939 (dans le module socket)
@anchor{library/socket socket CAN_J1939}@anchor{91f}
@deffn {Données} socket.CAN_J1939

CAN_J1939, in the CAN protocol family, is the SAE J1939 protocol.
J1939 constants, documented in the Linux documentation.

@ref{1ce0,,Availability}: Linux >= 5.4.


Ajouté dans la version 3.9.

@end deffn

@geindex AF_DIVERT (dans le module socket)
@geindex PF_DIVERT (dans le module socket)
@anchor{library/socket socket AF_DIVERT}@anchor{3368}
@deffn {Données} socket.AF_DIVERT
@anchor{library/socket socket PF_DIVERT}@anchor{3369}
@deffnx {Données} socket.PF_DIVERT

These two constants, documented in the FreeBSD divert(4) manual page, are
also defined in the socket module.

@ref{1ce0,,Availability}: FreeBSD >= 14.0.


Ajouté dans la version 3.12.

@end deffn

@geindex AF_PACKET (dans le module socket)
@geindex PF_PACKET (dans le module socket)
@anchor{library/socket socket AF_PACKET}@anchor{335b}
@deffn {Données} socket.AF_PACKET
@anchor{library/socket socket PF_PACKET}@anchor{336a}
@deffnx {Données} socket.PF_PACKET

@deffnx {Données} PACKET_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{1ce0,,Availability}: Linux >= 2.2.
@end deffn

@geindex ETH_P_ALL (dans le module socket)
@anchor{library/socket socket ETH_P_ALL}@anchor{1736}
@deffn {Données} socket.ETH_P_ALL

@code{ETH_P_ALL} can be used in the @ref{d8e,,socket}
constructor as `proto' for the @ref{335b,,AF_PACKET} family in order to
capture every packet, regardless of protocol.

For more information, see the @code{packet(7)@footnote{https://manpages.debian.org/packet(7)}} manpage.

@ref{1ce0,,Availability}: Linux.


Ajouté dans la version 3.12.

@end deffn

@geindex AF_RDS (dans le module socket)
@geindex PF_RDS (dans le module socket)
@geindex SOL_RDS (dans le module socket)
@anchor{library/socket socket AF_RDS}@anchor{336b}
@deffn {Données} socket.AF_RDS
@anchor{library/socket socket PF_RDS}@anchor{336c}
@deffnx {Données} socket.PF_RDS
@anchor{library/socket socket SOL_RDS}@anchor{336d}
@deffnx {Données} socket.SOL_RDS

@deffnx {Données} RDS_*

Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.

@ref{1ce0,,Availability}: Linux >= 2.6.30.


Ajouté dans la version 3.3.

@end deffn

@geindex SIO_RCVALL (dans le module socket)
@geindex SIO_KEEPALIVE_VALS (dans le module socket)
@geindex SIO_LOOPBACK_FAST_PATH (dans le module socket)
@anchor{library/socket socket SIO_RCVALL}@anchor{336e}
@deffn {Données} socket.SIO_RCVALL
@anchor{library/socket socket SIO_KEEPALIVE_VALS}@anchor{336f}
@deffnx {Données} socket.SIO_KEEPALIVE_VALS
@anchor{library/socket socket SIO_LOOPBACK_FAST_PATH}@anchor{cc2}
@deffnx {Données} socket.SIO_LOOPBACK_FAST_PATH

@deffnx {Données} RCVALL_*

Constants for Windows' WSAIoctl(). The constants are used as arguments to the
@ref{cc1,,ioctl()} method of socket objects.


Modifié dans la version 3.6: @code{SIO_LOOPBACK_FAST_PATH} was added.

@end deffn


@deffn {Données} TIPC_*

TIPC related constants, matching the ones exported by the C socket API. See
the TIPC documentation for more information.
@end deffn

@geindex AF_ALG (dans le module socket)
@geindex SOL_ALG (dans le module socket)
@anchor{library/socket socket AF_ALG}@anchor{cc5}
@deffn {Données} socket.AF_ALG
@anchor{library/socket socket SOL_ALG}@anchor{3370}
@deffnx {Données} socket.SOL_ALG

@deffnx {Données} ALG_*

Constants for Linux Kernel cryptography.

@ref{1ce0,,Availability}: Linux >= 2.6.38.


Ajouté dans la version 3.6.

@end deffn

@geindex AF_VSOCK (dans le module socket)
@geindex IOCTL_VM_SOCKETS_GET_LOCAL_CID (dans le module socket)
@anchor{library/socket socket AF_VSOCK}@anchor{b63}
@deffn {Données} socket.AF_VSOCK
@anchor{library/socket socket IOCTL_VM_SOCKETS_GET_LOCAL_CID}@anchor{3371}
@deffnx {Données} socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

@deffnx {Données} VMADDR*

@deffnx {Données} SO_VM*

Constants for Linux host/guest communication.

@ref{1ce0,,Availability}: Linux >= 4.8.


Ajouté dans la version 3.7.

@end deffn

@geindex AF_LINK (dans le module socket)
@anchor{library/socket socket AF_LINK}@anchor{f8e}
@deffn {Données} socket.AF_LINK

@ref{1ce0,,Availability}: BSD, macOS.


Ajouté dans la version 3.4.

@end deffn

@geindex has_ipv6 (dans le module socket)
@anchor{library/socket socket has_ipv6}@anchor{3372}
@deffn {Données} socket.has_ipv6

This constant contains a boolean value which indicates if IPv6 is supported on
this platform.
@end deffn

@geindex BDADDR_ANY (dans le module socket)
@geindex BDADDR_LOCAL (dans le module socket)
@anchor{library/socket socket BDADDR_ANY}@anchor{3373}
@deffn {Données} socket.BDADDR_ANY
@anchor{library/socket socket BDADDR_LOCAL}@anchor{3374}
@deffnx {Données} socket.BDADDR_LOCAL

These are string constants containing Bluetooth addresses with special
meanings. For example, @ref{3373,,BDADDR_ANY} can be used to indicate
any address when specifying the binding socket with
@code{BTPROTO_RFCOMM}.
@end deffn

@geindex HCI_FILTER (dans le module socket)
@geindex HCI_TIME_STAMP (dans le module socket)
@geindex HCI_DATA_DIR (dans le module socket)
@anchor{library/socket socket HCI_FILTER}@anchor{3375}
@deffn {Données} socket.HCI_FILTER
@anchor{library/socket socket HCI_TIME_STAMP}@anchor{3376}
@deffnx {Données} socket.HCI_TIME_STAMP
@anchor{library/socket socket HCI_DATA_DIR}@anchor{3377}
@deffnx {Données} socket.HCI_DATA_DIR

For use with @code{BTPROTO_HCI}. @ref{3375,,HCI_FILTER} is not
available for NetBSD or DragonFlyBSD. @ref{3376,,HCI_TIME_STAMP} and
@ref{3377,,HCI_DATA_DIR} are not available for FreeBSD, NetBSD, or
DragonFlyBSD.
@end deffn

@geindex AF_QIPCRTR (dans le module socket)
@anchor{library/socket socket AF_QIPCRTR}@anchor{335c}
@deffn {Données} socket.AF_QIPCRTR

Constant for Qualcomm's IPC router protocol, used to communicate with
service providing remote processors.

@ref{1ce0,,Availability}: Linux >= 4.7.
@end deffn

@geindex SCM_CREDS2 (dans le module socket)
@geindex LOCAL_CREDS (dans le module socket)
@geindex LOCAL_CREDS_PERSISTENT (dans le module socket)
@anchor{library/socket socket SCM_CREDS2}@anchor{3378}
@deffn {Données} socket.SCM_CREDS2
@anchor{library/socket socket LOCAL_CREDS}@anchor{3379}
@deffnx {Données} socket.LOCAL_CREDS
@anchor{library/socket socket LOCAL_CREDS_PERSISTENT}@anchor{337a}
@deffnx {Données} socket.LOCAL_CREDS_PERSISTENT

LOCAL_CREDS and LOCAL_CREDS_PERSISTENT can be used
with SOCK_DGRAM, SOCK_STREAM sockets, equivalent to
Linux/DragonFlyBSD SO_PASSCRED, while LOCAL_CREDS
sends the credentials at first read, LOCAL_CREDS_PERSISTENT
sends for each read, SCM_CREDS2 must be then used for
the latter for the message type.


Ajouté dans la version 3.11.


@ref{1ce0,,Availability}: FreeBSD.
@end deffn

@geindex SO_INCOMING_CPU (dans le module socket)
@anchor{library/socket socket SO_INCOMING_CPU}@anchor{337b}
@deffn {Données} socket.SO_INCOMING_CPU

@quotation

Constant to optimize CPU locality, to be used in conjunction with
@code{SO_REUSEPORT}.
@end quotation


Ajouté dans la version 3.11.


@ref{1ce0,,Availability}: Linux >= 3.9
@end deffn

@geindex AF_HYPERV (dans le module socket)
@geindex HV_PROTOCOL_RAW (dans le module socket)
@geindex HVSOCKET_CONNECT_TIMEOUT (dans le module socket)
@geindex HVSOCKET_CONNECT_TIMEOUT_MAX (dans le module socket)
@geindex HVSOCKET_CONNECTED_SUSPEND (dans le module socket)
@geindex HVSOCKET_ADDRESS_FLAG_PASSTHRU (dans le module socket)
@geindex HV_GUID_ZERO (dans le module socket)
@geindex HV_GUID_WILDCARD (dans le module socket)
@geindex HV_GUID_BROADCAST (dans le module socket)
@geindex HV_GUID_CHILDREN (dans le module socket)
@geindex HV_GUID_LOOPBACK (dans le module socket)
@geindex HV_GUID_PARENT (dans le module socket)
@anchor{library/socket socket AF_HYPERV}@anchor{335d}
@deffn {Données} socket.AF_HYPERV
@anchor{library/socket socket HV_PROTOCOL_RAW}@anchor{337c}
@deffnx {Données} socket.HV_PROTOCOL_RAW
@anchor{library/socket socket HVSOCKET_CONNECT_TIMEOUT}@anchor{337d}
@deffnx {Données} socket.HVSOCKET_CONNECT_TIMEOUT
@anchor{library/socket socket HVSOCKET_CONNECT_TIMEOUT_MAX}@anchor{337e}
@deffnx {Données} socket.HVSOCKET_CONNECT_TIMEOUT_MAX
@anchor{library/socket socket HVSOCKET_CONNECTED_SUSPEND}@anchor{337f}
@deffnx {Données} socket.HVSOCKET_CONNECTED_SUSPEND
@anchor{library/socket socket HVSOCKET_ADDRESS_FLAG_PASSTHRU}@anchor{3380}
@deffnx {Données} socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU
@anchor{library/socket socket HV_GUID_ZERO}@anchor{3381}
@deffnx {Données} socket.HV_GUID_ZERO
@anchor{library/socket socket HV_GUID_WILDCARD}@anchor{3382}
@deffnx {Données} socket.HV_GUID_WILDCARD
@anchor{library/socket socket HV_GUID_BROADCAST}@anchor{3383}
@deffnx {Données} socket.HV_GUID_BROADCAST
@anchor{library/socket socket HV_GUID_CHILDREN}@anchor{3384}
@deffnx {Données} socket.HV_GUID_CHILDREN
@anchor{library/socket socket HV_GUID_LOOPBACK}@anchor{3385}
@deffnx {Données} socket.HV_GUID_LOOPBACK
@anchor{library/socket socket HV_GUID_PARENT}@anchor{3386}
@deffnx {Données} socket.HV_GUID_PARENT

Constants for Windows Hyper-V sockets for host/guest communications.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.12.

@end deffn

@geindex ETHERTYPE_ARP (dans le module socket)
@geindex ETHERTYPE_IP (dans le module socket)
@geindex ETHERTYPE_IPV6 (dans le module socket)
@geindex ETHERTYPE_VLAN (dans le module socket)
@anchor{library/socket socket-ethernet-types}@anchor{1737}@anchor{library/socket socket ETHERTYPE_ARP}@anchor{3387}
@deffn {Données} socket.ETHERTYPE_ARP
@anchor{library/socket socket ETHERTYPE_IP}@anchor{3388}
@deffnx {Données} socket.ETHERTYPE_IP
@anchor{library/socket socket ETHERTYPE_IPV6}@anchor{3389}
@deffnx {Données} socket.ETHERTYPE_IPV6
@anchor{library/socket socket ETHERTYPE_VLAN}@anchor{338a}
@deffnx {Données} socket.ETHERTYPE_VLAN

IEEE 802.3 protocol number@footnote{https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.txt}.
constants.

@ref{1ce0,,Availability}: Linux, FreeBSD, macOS.


Ajouté dans la version 3.12.

@end deffn

@geindex SHUT_RD (dans le module socket)
@geindex SHUT_WR (dans le module socket)
@geindex SHUT_RDWR (dans le module socket)
@anchor{library/socket socket SHUT_RD}@anchor{338b}
@deffn {Données} socket.SHUT_RD
@anchor{library/socket socket SHUT_WR}@anchor{338c}
@deffnx {Données} socket.SHUT_WR
@anchor{library/socket socket SHUT_RDWR}@anchor{338d}
@deffnx {Données} socket.SHUT_RDWR

These constants are used by the @ref{338e,,shutdown()} method of socket objects.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@node Fonctions<8>,,Constantes<8>,Module contents
@anchor{library/socket functions}@anchor{338f}
@subsubsection Fonctions


@menu
* Creating sockets:: 
* Autres fonctions: Autres fonctions<2>. 

@end menu

@node Creating sockets,Autres fonctions<2>,,Fonctions<8>
@anchor{library/socket creating-sockets}@anchor{3390}
@subsubsection Creating sockets


The following functions all create @ref{3391,,socket objects}.

@geindex socket (classe dans socket)
@anchor{library/socket socket socket}@anchor{d8e}
@deffn {Classe} socket.socket (family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

Create a new socket using the given address family, socket type and protocol
number.  The address family should be @ref{17ab,,AF_INET} (the default),
@ref{17ac,,AF_INET6}, @ref{17ad,,AF_UNIX}, @ref{3359,,AF_CAN}, @ref{335b,,AF_PACKET},
or @ref{336b,,AF_RDS}. The socket type should be @ref{12d1,,SOCK_STREAM} (the
default), @ref{12d0,,SOCK_DGRAM}, @ref{3364,,SOCK_RAW} or perhaps one of the other
@code{SOCK_} constants. The protocol number is usually zero and may be omitted
or in the case where the address family is @ref{3359,,AF_CAN} the protocol
should be one of @code{CAN_RAW}, @ref{f8d,,CAN_BCM}, @ref{335a,,CAN_ISOTP} or
@ref{91f,,CAN_J1939}.

If `fileno' is specified, the values for `family', `type', and `proto' are
auto-detected from the specified file descriptor.  Auto-detection can be
overruled by calling the function with explicit `family', `type', or `proto'
arguments.  This only affects how Python represents e.g. the return value
of @ref{32e5,,socket.getpeername()} but not the actual OS resource.  Unlike
@ref{3392,,socket.fromfd()}, `fileno' will return the same socket and not a
duplicate. This may help close a detached socket using
@ref{b61,,socket.close()}.

Il n'est @ref{ee4,,pas possible d'hériter} du connecteur nouvellement créé.

Raises an @ref{1848,,auditing event} @code{socket.__new__} with arguments @code{self}, @code{family}, @code{type}, @code{protocol}.


Modifié dans la version 3.3: The AF_CAN family was added.
The AF_RDS family was added.



Modifié dans la version 3.4: The CAN_BCM protocol was added.



Modifié dans la version 3.4: The returned socket is now non-inheritable.



Modifié dans la version 3.7: The CAN_ISOTP protocol was added.



Modifié dans la version 3.7: When @ref{bf8,,SOCK_NONBLOCK} or @ref{bf9,,SOCK_CLOEXEC}
bit flags are applied to `type' they are cleared, and
@ref{bfa,,socket.type} will not reflect them.  They are still passed
to the underlying system @code{socket()} call.  Therefore,

@example
sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)
@end example

will still create a non-blocking socket on OSes that support
@code{SOCK_NONBLOCK}, but @code{sock.type} will be set to
@code{socket.SOCK_STREAM}.



Modifié dans la version 3.9: The CAN_J1939 protocol was added.



Modifié dans la version 3.10: The IPPROTO_MPTCP protocol was added.

@end deffn

@geindex socketpair() (dans le module socket)
@anchor{library/socket socket socketpair}@anchor{be3}
@deffn {Fonction} socket.socketpair ([family[, type[, proto]]])

Build a pair of connected socket objects using the given address family, socket
type, and protocol number.  Address family, socket type, and protocol number are
as for the @ref{d8e,,socket()} function above. The default family is @ref{17ad,,AF_UNIX}
if defined on the platform; otherwise, the default is @ref{17ab,,AF_INET}.

The newly created sockets are @ref{ee4,,non-inheritable}.


Modifié dans la version 3.2: The returned socket objects now support the whole socket API, rather
than a subset.



Modifié dans la version 3.4: The returned sockets are now non-inheritable.



Modifié dans la version 3.5: Windows support added.

@end deffn

@geindex create_connection() (dans le module socket)
@anchor{library/socket socket create_connection}@anchor{65d}
@deffn {Fonction} socket.create_connection (address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)

Connect to a TCP service listening on the internet `address' (a 2-tuple
@code{(host, port)}), and return the socket object.  This is a higher-level
function than @ref{d90,,socket.connect()}: if `host' is a non-numeric hostname,
it will try to resolve it for both @ref{17ab,,AF_INET} and @ref{17ac,,AF_INET6},
and then try to connect to all possible addresses in turn until a
connection succeeds.  This makes it easy to write clients that are
compatible to both IPv4 and IPv6.

Passing the optional `timeout' parameter will set the timeout on the
socket instance before attempting to connect.  If no `timeout' is
supplied, the global default timeout setting returned by
@ref{3393,,getdefaulttimeout()} is used.

If supplied, `source_address' must be a 2-tuple @code{(host, port)} for the
socket to bind to as its source address before connecting.  If host or port
are '@w{'} or 0 respectively the OS default behavior will be used.

When a connection cannot be created, an exception is raised. By default,
it is the exception from the last address in the list. If `all_errors'
is @code{True}, it is an @ref{1b4,,ExceptionGroup} containing the errors of all
attempts.


Modifié dans la version 3.2: Le paramètre `source_address' a été ajouté.



Modifié dans la version 3.11: `all_errors' was added.

@end deffn

@geindex create_server() (dans le module socket)
@anchor{library/socket socket create_server}@anchor{a19}
@deffn {Fonction} socket.create_server (address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)

Convenience function which creates a TCP socket bound to `address' (a 2-tuple
@code{(host, port)}) and returns the socket object.

`family' should be either @ref{17ab,,AF_INET} or @ref{17ac,,AF_INET6}.
`backlog' is the queue size passed to @ref{e47,,socket.listen()}; if not specified
, a default reasonable value is chosen.
`reuse_port' dictates whether to set the @code{SO_REUSEPORT} socket option.

If `dualstack_ipv6' is true and the platform supports it the socket will
be able to accept both IPv4 and IPv6 connections, else it will raise
@ref{1ff,,ValueError}. Most POSIX platforms and Windows are supposed to support
this functionality.
When this functionality is enabled the address returned by
@ref{32e5,,socket.getpeername()} when an IPv4 connection occurs will be an IPv6
address represented as an IPv4-mapped IPv6 address.
If `dualstack_ipv6' is false it will explicitly disable this functionality
on platforms that enable it by default (e.g. Linux).
This parameter can be used in conjunction with @ref{a1a,,has_dualstack_ipv6()}:

@example
import socket

addr = ("", 8080)  # all interfaces, port 8080
if socket.has_dualstack_ipv6():
    s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
    s = socket.create_server(addr)
@end example

@cartouche
@quotation Note 
On POSIX platforms the @code{SO_REUSEADDR} socket option is set in order to
immediately reuse previous sockets which were bound on the same `address'
and remained in TIME_WAIT state.
@end quotation
@end cartouche


Ajouté dans la version 3.8.

@end deffn

@geindex has_dualstack_ipv6() (dans le module socket)
@anchor{library/socket socket has_dualstack_ipv6}@anchor{a1a}
@deffn {Fonction} socket.has_dualstack_ipv6 ()

Return @code{True} if the platform supports creating a TCP socket which can
handle both IPv4 and IPv6 connections.


Ajouté dans la version 3.8.

@end deffn

@geindex fromfd() (dans le module socket)
@anchor{library/socket socket fromfd}@anchor{3392}
@deffn {Fonction} socket.fromfd (fd, family, type, proto=0)

Duplicate the file descriptor `fd' (an integer as returned by a file object's
@ref{27cf,,fileno()} method) and build a socket object from the result.  Address
family, socket type and protocol number are as for the @ref{d8e,,socket()} function
above. The file descriptor should refer to a socket, but this is not checked ---
subsequent operations on the object may fail if the file descriptor is invalid.
This function is rarely needed, but can be used to get or set socket options on
a socket passed to a program as standard input or output (such as a server
started by the Unix inet daemon).  The socket is assumed to be in blocking mode.

Il n'est @ref{ee4,,pas possible d'hériter} du connecteur nouvellement créé.


Modifié dans la version 3.4: The returned socket is now non-inheritable.

@end deffn

@geindex fromshare() (dans le module socket)
@anchor{library/socket socket fromshare}@anchor{bf5}
@deffn {Fonction} socket.fromshare (data)

Instantiate a socket from data obtained from the @ref{bf6,,socket.share()}
method.  The socket is assumed to be in blocking mode.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.3.

@end deffn

@geindex SocketType (dans le module socket)
@anchor{library/socket socket SocketType}@anchor{3394}
@deffn {Données} socket.SocketType

This is a Python type object that represents the socket object type. It is the
same as @code{type(socket(...))}.
@end deffn

@node Autres fonctions<2>,,Creating sockets,Fonctions<8>
@anchor{library/socket other-functions}@anchor{3395}
@subsubsection Autres fonctions


The @ref{cb,,socket} module also offers various network-related services:

@geindex close() (dans le module socket)
@anchor{library/socket socket close}@anchor{b61}
@deffn {Fonction} socket.close (fd)

Close a socket file descriptor. This is like @ref{b62,,os.close()}, but for
sockets. On some platforms (most noticeable Windows) @ref{b62,,os.close()}
does not work for socket file descriptors.


Ajouté dans la version 3.7.

@end deffn

@geindex getaddrinfo() (dans le module socket)
@anchor{library/socket socket getaddrinfo}@anchor{16e0}
@deffn {Fonction} socket.getaddrinfo (host, port, family=AF_UNSPEC, type=0, proto=0, flags=0)

This function wraps the C function @code{getaddrinfo} of the underlying system.

Translate the `host'/`port' argument into a sequence of 5-tuples that contain
all the necessary arguments for creating a socket connected to that service.
`host' is a domain name, a string representation of an IPv4/v6 address
or @code{None}. `port' is a string service name such as @code{'http'}, a numeric
port number or @code{None}.  By passing @code{None} as the value of `host'
and `port', you can pass @code{NULL} to the underlying C API.

The `family', `type' and `proto' arguments can be optionally specified
in order to provide options and limit the list of addresses returned.
Pass their default values (@ref{32a8,,AF_UNSPEC}, 0, and 0, respectively)
to not limit the results. See the note below for details.

The `flags' argument can be one or several of the @code{AI_*} constants,
and will influence how results are computed and returned.
For example, @code{AI_NUMERICHOST} will disable domain name resolution
and will raise an error if `host' is a domain name.

The function returns a list of 5-tuples with the following structure:

@code{(family, type, proto, canonname, sockaddr)}

In these tuples, `family', `type', `proto' are all integers and are
meant to be passed to the @ref{d8e,,socket()} function.  `canonname' will be
a string representing the canonical name of the `host' if
@code{AI_CANONNAME} is part of the `flags' argument; else `canonname'
will be empty.  `sockaddr' is a tuple describing a socket address, whose
format depends on the returned `family' (a @code{(address, port)} 2-tuple for
@ref{17ab,,AF_INET}, a @code{(address, port, flowinfo, scope_id)} 4-tuple for
@ref{17ac,,AF_INET6}), and is meant to be passed to the @ref{d90,,socket.connect()}
method.

@cartouche
@quotation Note 
If you intend to use results from @code{getaddrinfo()} to create a socket
(rather than, for example, retrieve `canonname'),
consider limiting the results by `type' (e.g. @ref{12d1,,SOCK_STREAM} or
@ref{12d0,,SOCK_DGRAM}) and/or `proto' (e.g. @code{IPPROTO_TCP} or
@code{IPPROTO_UDP}) that your application can handle.

The behavior with default values of `family', `type', `proto'
and `flags' is system-specific.

Many systems (for example, most Linux configurations) will return a sorted
list of all matching addresses.
These addresses should generally be tried in order until a connection succeeds
(possibly tried in parallel, for example, using a Happy Eyeballs@footnote{https://en.wikipedia.org/wiki/Happy_Eyeballs} algorithm).
In these cases, limiting the `type' and/or `proto' can help eliminate
unsuccessful or unusable connection attempts.

Some systems will, however, only return a single address.
(For example, this was reported on Solaris and AIX configurations.)
On these systems, limiting the `type' and/or `proto' helps ensure that
this address is usable.
@end quotation
@end cartouche

Raises an @ref{1848,,auditing event} @code{socket.getaddrinfo} with arguments @code{host}, @code{port}, @code{family}, @code{type}, @code{protocol}.

The following example fetches address information for a hypothetical TCP
connection to @code{example.org} on port 80 (results may differ on your
system if IPv6 isn't enabled):

@example
>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(socket.AF_INET6, socket.SOCK_STREAM,
 6, '@w{'}, ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (socket.AF_INET, socket.SOCK_STREAM,
 6, '@w{'}, ('93.184.216.34', 80))]
@end example


Modifié dans la version 3.2: parameters can now be passed using keyword arguments.



Modifié dans la version 3.7: for IPv6 multicast addresses, string representing an address will not
contain @code{%scope_id} part.

@end deffn

@geindex getfqdn() (dans le module socket)
@anchor{library/socket socket getfqdn}@anchor{170a}
@deffn {Fonction} socket.getfqdn ([name])

Return a fully qualified domain name for `name'. If `name' is omitted or empty,
it is interpreted as the local host.  To find the fully qualified name, the
hostname returned by @ref{185a,,gethostbyaddr()} is checked, followed by aliases for the
host, if available.  The first name which includes a period is selected.  In
case no fully qualified domain name is available and `name' was provided,
it is returned unchanged.  If `name' was empty or equal to @code{'0.0.0.0'},
the hostname from @ref{2aae,,gethostname()} is returned.
@end deffn

@geindex gethostbyname() (dans le module socket)
@anchor{library/socket socket gethostbyname}@anchor{3396}
@deffn {Fonction} socket.gethostbyname (hostname)

Translate a host name to IPv4 address format.  The IPv4 address is returned as a
string, such as  @code{'100.50.200.5'}.  If the host name is an IPv4 address itself
it is returned unchanged.  See @ref{185b,,gethostbyname_ex()} for a more complete
interface. @ref{3396,,gethostbyname()} does not support IPv6 name resolution, and
@ref{16e0,,getaddrinfo()} should be used instead for IPv4/v6 dual stack support.

Raises an @ref{1848,,auditing event} @code{socket.gethostbyname} with argument @code{hostname}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex gethostbyname_ex() (dans le module socket)
@anchor{library/socket socket gethostbyname_ex}@anchor{185b}
@deffn {Fonction} socket.gethostbyname_ex (hostname)

Translate a host name to IPv4 address format, extended interface. Return a
3-tuple @code{(hostname, aliaslist, ipaddrlist)} where `hostname' is the host's
primary host name, `aliaslist' is a (possibly
empty) list of alternative host names for the same address, and `ipaddrlist' is
a list of IPv4 addresses for the same interface on the same host (often but not
always a single address). @ref{185b,,gethostbyname_ex()} does not support IPv6 name
resolution, and @ref{16e0,,getaddrinfo()} should be used instead for IPv4/v6 dual
stack support.

Raises an @ref{1848,,auditing event} @code{socket.gethostbyname} with argument @code{hostname}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex gethostname() (dans le module socket)
@anchor{library/socket socket gethostname}@anchor{2aae}
@deffn {Fonction} socket.gethostname ()

Return a string containing the hostname of the machine where  the Python
interpreter is currently executing.

Raises an @ref{1848,,auditing event} @code{socket.gethostname} with no arguments.

Note: @ref{2aae,,gethostname()} doesn't always return the fully qualified domain
name; use @ref{170a,,getfqdn()} for that.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex gethostbyaddr() (dans le module socket)
@anchor{library/socket socket gethostbyaddr}@anchor{185a}
@deffn {Fonction} socket.gethostbyaddr (ip_address)

Return a 3-tuple @code{(hostname, aliaslist, ipaddrlist)} where `hostname' is the
primary host name responding to the given `ip_address', `aliaslist' is a
(possibly empty) list of alternative host names for the same address, and
`ipaddrlist' is a list of IPv4/v6 addresses for the same interface on the same
host (most likely containing only a single address). To find the fully qualified
domain name, use the function @ref{170a,,getfqdn()}. @ref{185a,,gethostbyaddr()} supports
both IPv4 and IPv6.

Raises an @ref{1848,,auditing event} @code{socket.gethostbyaddr} with argument @code{ip_address}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex getnameinfo() (dans le module socket)
@anchor{library/socket socket getnameinfo}@anchor{164d}
@deffn {Fonction} socket.getnameinfo (sockaddr, flags)

Translate a socket address `sockaddr' into a 2-tuple @code{(host, port)}. Depending
on the settings of `flags', the result can contain a fully qualified domain name
or numeric address representation in `host'.  Similarly, `port' can contain a
string port name or a numeric port number.

For IPv6 addresses, @code{%scope_id} is appended to the host part if `sockaddr'
contains meaningful `scope_id'. Usually this happens for multicast addresses.

For more information about `flags' you can consult @code{getnameinfo(3)@footnote{https://manpages.debian.org/getnameinfo(3)}}.

Raises an @ref{1848,,auditing event} @code{socket.getnameinfo} with argument @code{sockaddr}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex getprotobyname() (dans le module socket)
@anchor{library/socket socket getprotobyname}@anchor{3397}
@deffn {Fonction} socket.getprotobyname (protocolname)

Translate an internet protocol name (for example, @code{'icmp'}) to a constant
suitable for passing as the (optional) third argument to the @ref{d8e,,socket()}
function.  This is usually only needed for sockets opened in "raw" mode
(@ref{3364,,SOCK_RAW}); for the normal socket modes, the correct protocol is chosen
automatically if the protocol is omitted or zero.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex getservbyname() (dans le module socket)
@anchor{library/socket socket getservbyname}@anchor{3398}
@deffn {Fonction} socket.getservbyname (servicename[, protocolname])

Translate an internet service name and protocol name to a port number for that
service.  The optional protocol name, if given, should be @code{'tcp'} or
@code{'udp'}, otherwise any protocol will match.

Raises an @ref{1848,,auditing event} @code{socket.getservbyname} with arguments @code{servicename}, @code{protocolname}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex getservbyport() (dans le module socket)
@anchor{library/socket socket getservbyport}@anchor{3399}
@deffn {Fonction} socket.getservbyport (port[, protocolname])

Translate an internet port number and protocol name to a service name for that
service.  The optional protocol name, if given, should be @code{'tcp'} or
@code{'udp'}, otherwise any protocol will match.

Raises an @ref{1848,,auditing event} @code{socket.getservbyport} with arguments @code{port}, @code{protocolname}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex ntohl() (dans le module socket)
@anchor{library/socket socket ntohl}@anchor{339a}
@deffn {Fonction} socket.ntohl (x)

Convert 32-bit positive integers from network to host byte order.  On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 4-byte swap operation.
@end deffn

@geindex ntohs() (dans le module socket)
@anchor{library/socket socket ntohs}@anchor{86c}
@deffn {Fonction} socket.ntohs (x)

Convert 16-bit positive integers from network to host byte order.  On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 2-byte swap operation.


Modifié dans la version 3.10: Raises @ref{86d,,OverflowError} if `x' does not fit in a 16-bit unsigned
integer.

@end deffn

@geindex htonl() (dans le module socket)
@anchor{library/socket socket htonl}@anchor{339b}
@deffn {Fonction} socket.htonl (x)

Convert 32-bit positive integers from host to network byte order.  On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 4-byte swap operation.
@end deffn

@geindex htons() (dans le module socket)
@anchor{library/socket socket htons}@anchor{86b}
@deffn {Fonction} socket.htons (x)

Convert 16-bit positive integers from host to network byte order.  On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 2-byte swap operation.


Modifié dans la version 3.10: Raises @ref{86d,,OverflowError} if `x' does not fit in a 16-bit unsigned
integer.

@end deffn

@geindex inet_aton() (dans le module socket)
@anchor{library/socket socket inet_aton}@anchor{94e}
@deffn {Fonction} socket.inet_aton (ip_string)

Convert an IPv4 address from dotted-quad string format (for example,
'123.45.67.89') to 32-bit packed binary format, as a bytes object four characters in
length.  This is useful when conversing with a program that uses the standard C
library and needs objects of type @code{in_addr}, which is the C type
for the 32-bit packed binary this function returns.

@ref{94e,,inet_aton()} also accepts strings with less than three dots; see the
Unix manual page @code{inet(3)@footnote{https://manpages.debian.org/inet(3)}} for details.

If the IPv4 address string passed to this function is invalid,
@ref{40d,,OSError} will be raised. Note that exactly what is valid depends on
the underlying C implementation of @code{inet_aton()}.

@ref{94e,,inet_aton()} does not support IPv6, and @ref{94f,,inet_pton()} should be used
instead for IPv4/v6 dual stack support.
@end deffn

@geindex inet_ntoa() (dans le module socket)
@anchor{library/socket socket inet_ntoa}@anchor{339c}
@deffn {Fonction} socket.inet_ntoa (packed_ip)

Convert a 32-bit packed IPv4 address (a @ref{d1b,,bytes-like object} four
bytes in length) to its standard dotted-quad string representation (for example,
'123.45.67.89').  This is useful when conversing with a program that uses the
standard C library and needs objects of type @code{in_addr}, which
is the C type for the 32-bit packed binary data this function takes as an
argument.

If the byte sequence passed to this function is not exactly 4 bytes in
length, @ref{40d,,OSError} will be raised. @ref{339c,,inet_ntoa()} does not
support IPv6, and @ref{f8f,,inet_ntop()} should be used instead for IPv4/v6 dual
stack support.


Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end deffn

@geindex inet_pton() (dans le module socket)
@anchor{library/socket socket inet_pton}@anchor{94f}
@deffn {Fonction} socket.inet_pton (address_family, ip_string)

Convert an IP address from its family-specific string format to a packed,
binary format. @ref{94f,,inet_pton()} is useful when a library or network protocol
calls for an object of type @code{in_addr} (similar to
@ref{94e,,inet_aton()}) or @code{in6_addr}.

Supported values for `address_family' are currently @ref{17ab,,AF_INET} and
@ref{17ac,,AF_INET6}. If the IP address string `ip_string' is invalid,
@ref{40d,,OSError} will be raised. Note that exactly what is valid depends on
both the value of `address_family' and the underlying implementation of
@code{inet_pton()}.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.4: Ajout de la gestion de Windows.

@end deffn

@geindex inet_ntop() (dans le module socket)
@anchor{library/socket socket inet_ntop}@anchor{f8f}
@deffn {Fonction} socket.inet_ntop (address_family, packed_ip)

Convert a packed IP address (a @ref{d1b,,bytes-like object} of some number of
bytes) to its standard, family-specific string representation (for
example, @code{'7.10.0.5'} or @code{'5aef:2b::8'}).
@ref{f8f,,inet_ntop()} is useful when a library or network protocol returns an
object of type @code{in_addr} (similar to @ref{339c,,inet_ntoa()}) or
@code{in6_addr}.

Supported values for `address_family' are currently @ref{17ab,,AF_INET} and
@ref{17ac,,AF_INET6}. If the bytes object `packed_ip' is not the correct
length for the specified address family, @ref{1ff,,ValueError} will be raised.
@ref{40d,,OSError} is raised for errors from the call to @ref{f8f,,inet_ntop()}.

@ref{1ce0,,Availability}: Unix, Windows.


Modifié dans la version 3.4: Ajout de la gestion de Windows.



Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end deffn

@c XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any
@c non-Unix platforms?  The old (obsolete?) 4.2BSD form of the
@c interface, in which struct msghdr has no msg_control or
@c msg_controllen members, is not currently supported.

@geindex CMSG_LEN() (dans le module socket)
@anchor{library/socket socket CMSG_LEN}@anchor{19c5}
@deffn {Fonction} socket.CMSG_LEN (length)

Return the total length, without trailing padding, of an ancillary
data item with associated data of the given `length'.  This value
can often be used as the buffer size for @ref{d93,,recvmsg()} to
receive a single item of ancillary data, but 
@geindex RFC; RFC 3542
RFC 3542@footnote{https://datatracker.ietf.org/doc/html/rfc3542.html} requires
portable applications to use @ref{19c4,,CMSG_SPACE()} and thus include
space for padding, even when the item will be the last in the
buffer.  Raises @ref{86d,,OverflowError} if `length' is outside the
permissible range of values.

@ref{1ce0,,Availability}: Unix, not WASI.

Most Unix platforms.


Ajouté dans la version 3.3.

@end deffn

@geindex CMSG_SPACE() (dans le module socket)
@anchor{library/socket socket CMSG_SPACE}@anchor{19c4}
@deffn {Fonction} socket.CMSG_SPACE (length)

Return the buffer size needed for @ref{d93,,recvmsg()} to
receive an ancillary data item with associated data of the given
`length', along with any trailing padding.  The buffer space needed
to receive multiple items is the sum of the @ref{19c4,,CMSG_SPACE()}
values for their associated data lengths.  Raises
@ref{86d,,OverflowError} if `length' is outside the permissible range
of values.

Note that some systems might support ancillary data without
providing this function.  Also note that setting the buffer size
using the results of this function may not precisely limit the
amount of ancillary data that can be received, since additional
data may be able to fit into the padding area.

@ref{1ce0,,Availability}: Unix, not WASI.

most Unix platforms.


Ajouté dans la version 3.3.

@end deffn

@geindex getdefaulttimeout() (dans le module socket)
@anchor{library/socket socket getdefaulttimeout}@anchor{3393}
@deffn {Fonction} socket.getdefaulttimeout ()

Return the default timeout in seconds (float) for new socket objects. A value
of @code{None} indicates that new socket objects have no timeout. When the socket
module is first imported, the default is @code{None}.
@end deffn

@geindex setdefaulttimeout() (dans le module socket)
@anchor{library/socket socket setdefaulttimeout}@anchor{3362}
@deffn {Fonction} socket.setdefaulttimeout (timeout)

Set the default timeout in seconds (float) for new socket objects.  When
the socket module is first imported, the default is @code{None}.  See
@ref{335e,,settimeout()} for possible values and their respective
meanings.
@end deffn

@geindex sethostname() (dans le module socket)
@anchor{library/socket socket sethostname}@anchor{111b}
@deffn {Fonction} socket.sethostname (name)

Set the machine's hostname to `name'.  This will raise an
@ref{40d,,OSError} if you don't have enough rights.

Raises an @ref{1848,,auditing event} @code{socket.sethostname} with argument @code{name}.

@ref{1ce0,,Availability}: Unix, not Android.


Ajouté dans la version 3.3.

@end deffn

@geindex if_nameindex() (dans le module socket)
@anchor{library/socket socket if_nameindex}@anchor{a1b}
@deffn {Fonction} socket.if_nameindex ()

Return a list of network interface information
(index int, name string) tuples.
@ref{40d,,OSError} if the system call fails.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.


Ajouté dans la version 3.3.



Modifié dans la version 3.8: Windows support was added.


@cartouche
@quotation Note 
On Windows network interfaces have different names in different contexts
(all names are examples):


@itemize *

@item 
UUID: @code{@{FB605B73-AAC2-49A6-9A2F-25416AEA0573@}}

@item 
name: @code{ethernet_32770}

@item 
friendly name: @code{vEthernet (nat)}

@item 
description: @code{Hyper-V Virtual Ethernet Adapter}
@end itemize

This function returns names of the second form from the list, @code{ethernet_32770}
in this example case.
@end quotation
@end cartouche
@end deffn

@geindex if_nametoindex() (dans le module socket)
@anchor{library/socket socket if_nametoindex}@anchor{a1c}
@deffn {Fonction} socket.if_nametoindex (if_name)

Return a network interface index number corresponding to an
interface name.
@ref{40d,,OSError} if no interface with the given name exists.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.


Ajouté dans la version 3.3.



Modifié dans la version 3.8: Windows support was added.



@subsubheading Voir aussi


"Interface name" is a name as documented in @ref{a1b,,if_nameindex()}.

@end deffn

@geindex if_indextoname() (dans le module socket)
@anchor{library/socket socket if_indextoname}@anchor{a1d}
@deffn {Fonction} socket.if_indextoname (if_index)

Return a network interface name corresponding to an
interface index number.
@ref{40d,,OSError} if no interface with the given index exists.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.


Ajouté dans la version 3.3.



Modifié dans la version 3.8: Windows support was added.



@subsubheading Voir aussi


"Interface name" is a name as documented in @ref{a1b,,if_nameindex()}.

@end deffn

@geindex send_fds() (dans le module socket)
@anchor{library/socket socket send_fds}@anchor{920}
@deffn {Fonction} socket.send_fds (sock, buffers, fds[, flags[, address]])

Send the list of file descriptors `fds' over an @ref{17ad,,AF_UNIX} socket `sock'.
The `fds' parameter is a sequence of file descriptors.
Consult @ref{460,,sendmsg()} for the documentation of these parameters.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.

Unix platforms supporting @ref{460,,sendmsg()}
and @code{SCM_RIGHTS} mechanism.


Ajouté dans la version 3.9.

@end deffn

@geindex recv_fds() (dans le module socket)
@anchor{library/socket socket recv_fds}@anchor{921}
@deffn {Fonction} socket.recv_fds (sock, bufsize, maxfds[, flags])

Receive up to `maxfds' file descriptors from an @ref{17ad,,AF_UNIX} socket `sock'.
Return @code{(msg, list(fds), flags, addr)}.
Consult @ref{d93,,recvmsg()} for the documentation of these parameters.

@ref{1ce0,,Availability}: Unix, Windows, not WASI.

Unix platforms supporting @ref{460,,sendmsg()}
and @code{SCM_RIGHTS} mechanism.


Ajouté dans la version 3.9.


@cartouche
@quotation Note 
Any truncated integers at the end of the list of file descriptors.
@end quotation
@end cartouche
@end deffn

@node Socket Objects,Notes on socket timeouts,Module contents,socket --- Low-level networking interface
@anchor{library/socket id1}@anchor{339d}@anchor{library/socket socket-objects}@anchor{3391}
@subsubsection Socket Objects


Socket objects have the following methods.  Except for
@ref{117d,,makefile()}, these correspond to Unix system calls applicable
to sockets.


Modifié dans la version 3.2: Support for the @ref{5be,,context manager} protocol was added.  Exiting the
context manager is equivalent to calling @ref{b61,,close()}.


@geindex accept() (méthode socket.socket)
@anchor{library/socket socket socket accept}@anchor{d8f}
@deffn {Méthode} socket.accept ()

Accept a connection. The socket must be bound to an address and listening for
connections. The return value is a pair @code{(conn, address)} where `conn' is a
`new' socket object usable to send and receive data on the connection, and
`address' is the address bound to the socket on the other end of the connection.

Il n'est @ref{ee4,,pas possible d'hériter} du connecteur nouvellement créé.


Modifié dans la version 3.4: The socket is now non-inheritable.



Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex bind() (méthode socket.socket)
@anchor{library/socket socket socket bind}@anchor{14f0}
@deffn {Méthode} socket.bind (address)

Bind the socket to `address'.  The socket must not already be bound. (The format
of `address' depends on the address family --- see above.)

Raises an @ref{1848,,auditing event} @code{socket.bind} with arguments @code{self}, @code{address}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex close() (méthode socket.socket)
@anchor{library/socket socket socket close}@anchor{d31}
@deffn {Méthode} socket.close ()

Mark the socket closed.  The underlying system resource (e.g. a file
descriptor) is also closed when all file objects from @ref{117d,,makefile()}
are closed.  Once that happens, all future operations on the socket
object will fail. The remote end will receive no more data (after
queued data is flushed).

Sockets are automatically closed when they are garbage-collected, but
it is recommended to @ref{b61,,close()} them explicitly, or to use a
@ref{5bc,,with} statement around them.


Modifié dans la version 3.6: @ref{40d,,OSError} is now raised if an error occurs when the underlying
@code{close()} call is made.


@cartouche
@quotation Note 
@ref{b61,,close()} releases the resource associated with a connection but
does not necessarily close the connection immediately.  If you want
to close the connection in a timely fashion, call @ref{338e,,shutdown()}
before @ref{b61,,close()}.
@end quotation
@end cartouche
@end deffn

@geindex connect() (méthode socket.socket)
@anchor{library/socket socket socket connect}@anchor{d90}
@deffn {Méthode} socket.connect (address)

Connect to a remote socket at `address'. (The format of `address' depends on the
address family --- see above.)

If the connection is interrupted by a signal, the method waits until the
connection completes, or raise a @ref{81f,,TimeoutError} on timeout, if the
signal handler doesn't raise an exception and the socket is blocking or has
a timeout. For non-blocking sockets, the method raises an
@ref{d75,,InterruptedError} exception if the connection is interrupted by a
signal (or the exception raised by the signal handler).

Raises an @ref{1848,,auditing event} @code{socket.connect} with arguments @code{self}, @code{address}.


Modifié dans la version 3.5: The method now waits until the connection completes instead of raising an
@ref{d75,,InterruptedError} exception if the connection is interrupted by a
signal, the signal handler doesn't raise an exception and the socket is
blocking or has a timeout (see the 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).


@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex connect_ex() (méthode socket.socket)
@anchor{library/socket socket socket connect_ex}@anchor{14ef}
@deffn {Méthode} socket.connect_ex (address)

Like @code{connect(address)}, but return an error indicator instead of raising an
exception for errors returned by the C-level @code{connect()} call (other
problems, such as "host not found," can still raise exceptions).  The error
indicator is @code{0} if the operation succeeded, otherwise the value of the
@code{errno} variable.  This is useful to support, for example, asynchronous
connects.

Raises an @ref{1848,,auditing event} @code{socket.connect} with arguments @code{self}, @code{address}.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex detach() (méthode socket.socket)
@anchor{library/socket socket socket detach}@anchor{11fa}
@deffn {Méthode} socket.detach ()

Put the socket object into closed state without actually closing the
underlying file descriptor.  The file descriptor is returned, and can
be reused for other purposes.


Ajouté dans la version 3.2.

@end deffn

@geindex dup() (méthode socket.socket)
@anchor{library/socket socket socket dup}@anchor{339e}
@deffn {Méthode} socket.dup ()

Duplicate the socket.

Il n'est @ref{ee4,,pas possible d'hériter} du connecteur nouvellement créé.


Modifié dans la version 3.4: The socket is now non-inheritable.


@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex fileno() (méthode socket.socket)
@anchor{library/socket socket socket fileno}@anchor{339f}
@deffn {Méthode} socket.fileno ()

Return the socket's file descriptor (a small integer), or -1 on failure. This
is useful with @ref{d8d,,select.select()}.

Under Windows the small integer returned by this method cannot be used where a
file descriptor can be used (such as @ref{1eb7,,os.fdopen()}).  Unix does not have
this limitation.
@end deffn

@geindex get_inheritable() (méthode socket.socket)
@anchor{library/socket socket socket get_inheritable}@anchor{ee9}
@deffn {Méthode} socket.get_inheritable ()

Get the @ref{ee4,,inheritable flag} of the socket's file
descriptor or socket's handle: @code{True} if the socket can be inherited in
child processes, @code{False} if it cannot.


Ajouté dans la version 3.4.

@end deffn

@geindex getpeername() (méthode socket.socket)
@anchor{library/socket socket socket getpeername}@anchor{32e5}
@deffn {Méthode} socket.getpeername ()

Return the remote address to which the socket is connected.  This is useful to
find out the port number of a remote IPv4/v6 socket, for instance. (The format
of the address returned depends on the address family --- see above.)  On some
systems this function is not supported.
@end deffn

@geindex getsockname() (méthode socket.socket)
@anchor{library/socket socket socket getsockname}@anchor{32e6}
@deffn {Méthode} socket.getsockname ()

Return the socket's own address.  This is useful to find out the port number of
an IPv4/v6 socket, for instance. (The format of the address returned depends on
the address family --- see above.)
@end deffn

@geindex getsockopt() (méthode socket.socket)
@anchor{library/socket socket socket getsockopt}@anchor{cc3}
@deffn {Méthode} socket.getsockopt (level, optname[, buflen])

Return the value of the given socket option (see the Unix man page
@code{getsockopt(2)@footnote{https://manpages.debian.org/getsockopt(2)}}).  The needed symbolic constants (@ref{32a4,,SO_* etc.})
are defined in this module.  If `buflen' is absent, an integer option is assumed
and its integer value is returned by the function.  If `buflen' is present, it
specifies the maximum length of the buffer used to receive the option in, and
this buffer is returned as a bytes object.  It is up to the caller to decode the
contents of the buffer (see the optional built-in module @ref{d4,,struct} for a way
to decode C structures encoded as byte strings).

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex getblocking() (méthode socket.socket)
@anchor{library/socket socket socket getblocking}@anchor{b60}
@deffn {Méthode} socket.getblocking ()

Return @code{True} if socket is in blocking mode, @code{False} if in
non-blocking.

This is equivalent to checking @code{socket.gettimeout() != 0}.


Ajouté dans la version 3.7.

@end deffn

@geindex gettimeout() (méthode socket.socket)
@anchor{library/socket socket socket gettimeout}@anchor{33a0}
@deffn {Méthode} socket.gettimeout ()

Return the timeout in seconds (float) associated with socket operations,
or @code{None} if no timeout is set.  This reflects the last call to
@ref{2ac5,,setblocking()} or @ref{335e,,settimeout()}.
@end deffn

@geindex ioctl() (méthode socket.socket)
@anchor{library/socket socket socket ioctl}@anchor{cc1}
@deffn {Méthode} socket.ioctl (control, option)

@*@code{platform}: 
Windows


The @ref{cc1,,ioctl()} method is a limited interface to the WSAIoctl system
interface.  Please refer to the Win32 documentation@footnote{https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx} for more
information.

On other platforms, the generic @ref{33a1,,fcntl.fcntl()} and @ref{142e,,fcntl.ioctl()}
functions may be used; they accept a socket object as their first argument.

Currently only the following control codes are supported:
@code{SIO_RCVALL}, @code{SIO_KEEPALIVE_VALS}, and @code{SIO_LOOPBACK_FAST_PATH}.


Modifié dans la version 3.6: @code{SIO_LOOPBACK_FAST_PATH} was added.

@end deffn

@geindex listen() (méthode socket.socket)
@anchor{library/socket socket socket listen}@anchor{e47}
@deffn {Méthode} socket.listen ([backlog])

Enable a server to accept connections.  If `backlog' is specified, it must
be at least 0 (if it is lower, it is set to 0); it specifies the number of
unaccepted connections that the system will allow before refusing new
connections. If not specified, a default reasonable value is chosen.

@ref{1ce0,,Availability}: not WASI.


Modifié dans la version 3.5: The `backlog' parameter is now optional.

@end deffn

@geindex makefile() (méthode socket.socket)
@anchor{library/socket socket socket makefile}@anchor{117d}
@deffn {Méthode} socket.makefile (mode='r', buffering=None, *, encoding=None, errors=None, newline=None)

@geindex I/O control;buffering

Return a @ref{11a0,,file object} associated with the socket.  The exact returned
type depends on the arguments given to @ref{117d,,makefile()}.  These arguments are
interpreted the same way as by the built-in @ref{505,,open()} function, except
the only supported `mode' values are @code{'r'} (default), @code{'w'}, @code{'b'}, or
a combination of those.

The socket must be in blocking mode; it can have a timeout, but the file
object's internal buffer may end up in an inconsistent state if a timeout
occurs.

Closing the file object returned by @ref{117d,,makefile()} won't close the
original socket unless all other file objects have been closed and
@ref{b61,,socket.close()} has been called on the socket object.

@cartouche
@quotation Note 
On Windows, the file-like object created by @ref{117d,,makefile()} cannot be
used where a file object with a file descriptor is expected, such as the
stream arguments of @ref{197,,subprocess.Popen()}.
@end quotation
@end cartouche
@end deffn

@geindex recv() (méthode socket.socket)
@anchor{library/socket socket socket recv}@anchor{d91}
@deffn {Méthode} socket.recv (bufsize[, flags])

Receive data from the socket.  The return value is a bytes object representing the
data received.  The maximum amount of data to be received at once is specified
by `bufsize'. A returned empty bytes object indicates that the client has disconnected.
See the Unix manual page @code{recv(2)@footnote{https://manpages.debian.org/recv(2)}} for the meaning of the optional argument
`flags'; it defaults to zero.

@cartouche
@quotation Note 
For best match with hardware and network realities, the value of  `bufsize'
should be a relatively small power of 2, for example, 4096.
@end quotation
@end cartouche


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex recvfrom() (méthode socket.socket)
@anchor{library/socket socket socket recvfrom}@anchor{d92}
@deffn {Méthode} socket.recvfrom (bufsize[, flags])

Receive data from the socket.  The return value is a pair @code{(bytes, address)}
where `bytes' is a bytes object representing the data received and `address' is the
address of the socket sending the data.  See the Unix manual page
@code{recv(2)@footnote{https://manpages.debian.org/recv(2)}} for the meaning of the optional argument `flags'; it defaults
to zero. (The format of `address' depends on the address family --- see above.)


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).



Modifié dans la version 3.7: For multicast IPv6 address, first item of `address' does not contain
@code{%scope_id} part anymore. In order to get full IPv6 address use
@ref{164d,,getnameinfo()}.

@end deffn

@geindex recvmsg() (méthode socket.socket)
@anchor{library/socket socket socket recvmsg}@anchor{d93}
@deffn {Méthode} socket.recvmsg (bufsize[, ancbufsize[, flags]])

Receive normal data (up to `bufsize' bytes) and ancillary data from
the socket.  The `ancbufsize' argument sets the size in bytes of
the internal buffer used to receive the ancillary data; it defaults
to 0, meaning that no ancillary data will be received.  Appropriate
buffer sizes for ancillary data can be calculated using
@ref{19c4,,CMSG_SPACE()} or @ref{19c5,,CMSG_LEN()}, and items which do not fit
into the buffer might be truncated or discarded.  The `flags'
argument defaults to 0 and has the same meaning as for
@ref{d91,,recv()}.

The return value is a 4-tuple: @code{(data, ancdata, msg_flags,
address)}.  The `data' item is a @ref{1bd,,bytes} object holding the
non-ancillary data received.  The `ancdata' item is a list of zero
or more tuples @code{(cmsg_level, cmsg_type, cmsg_data)} representing
the ancillary data (control messages) received: `cmsg_level' and
`cmsg_type' are integers specifying the protocol level and
protocol-specific type respectively, and `cmsg_data' is a
@ref{1bd,,bytes} object holding the associated data.  The `msg_flags'
item is the bitwise OR of various flags indicating conditions on
the received message; see your system documentation for details.
If the receiving socket is unconnected, `address' is the address of
the sending socket, if available; otherwise, its value is
unspecified.

On some systems, @ref{460,,sendmsg()} and @ref{d93,,recvmsg()} can be used to
pass file descriptors between processes over an @ref{17ad,,AF_UNIX}
socket.  When this facility is used (it is often restricted to
@ref{12d1,,SOCK_STREAM} sockets), @ref{d93,,recvmsg()} will return, in its
ancillary data, items of the form @code{(socket.SOL_SOCKET,
socket.SCM_RIGHTS, fds)}, where `fds' is a @ref{1bd,,bytes} object
representing the new file descriptors as a binary array of the
native C int type.  If @ref{d93,,recvmsg()} raises an
exception after the system call returns, it will first attempt to
close any file descriptors received via this mechanism.

Some systems do not indicate the truncated length of ancillary data
items which have been only partially received.  If an item appears
to extend beyond the end of the buffer, @ref{d93,,recvmsg()} will issue
a @ref{1bb,,RuntimeWarning}, and will return the part of it which is
inside the buffer provided it has not been truncated before the
start of its associated data.

On systems which support the @code{SCM_RIGHTS} mechanism, the
following function will receive up to `maxfds' file descriptors,
returning the message data and a list containing the descriptors
(while ignoring unexpected conditions such as unrelated control
messages being received).  See also @ref{460,,sendmsg()}.

@example
import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)
@end example

@ref{1ce0,,Availability}: Unix.

Most Unix platforms.


Ajouté dans la version 3.3.



Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex recvmsg_into() (méthode socket.socket)
@anchor{library/socket socket socket recvmsg_into}@anchor{111a}
@deffn {Méthode} socket.recvmsg_into (buffers[, ancbufsize[, flags]])

Receive normal data and ancillary data from the socket, behaving as
@ref{d93,,recvmsg()} would, but scatter the non-ancillary data into a
series of buffers instead of returning a new bytes object.  The
`buffers' argument must be an iterable of objects that export
writable buffers (e.g. @ref{528,,bytearray} objects); these will be
filled with successive chunks of the non-ancillary data until it
has all been written or there are no more buffers.  The operating
system may set a limit (@ref{2aec,,sysconf()} value @code{SC_IOV_MAX})
on the number of buffers that can be used.  The `ancbufsize' and
`flags' arguments have the same meaning as for @ref{d93,,recvmsg()}.

The return value is a 4-tuple: @code{(nbytes, ancdata, msg_flags,
address)}, where `nbytes' is the total number of bytes of
non-ancillary data written into the buffers, and `ancdata',
`msg_flags' and `address' are the same as for @ref{d93,,recvmsg()}.

Exemple :

@example
>>> import socket
>>> s1, s2 = socket.socketpair()
>>> b1 = bytearray(b'----')
>>> b2 = bytearray(b'0123456789')
>>> b3 = bytearray(b'--------------')
>>> s1.send(b'Mary had a little lamb')
22
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
(22, [], 0, None)
>>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
@end example

@ref{1ce0,,Availability}: Unix.

Most Unix platforms.


Ajouté dans la version 3.3.

@end deffn

@geindex recvfrom_into() (méthode socket.socket)
@anchor{library/socket socket socket recvfrom_into}@anchor{12fc}
@deffn {Méthode} socket.recvfrom_into (buffer[, nbytes[, flags]])

Receive data from the socket, writing it into `buffer' instead of creating a
new bytestring.  The return value is a pair @code{(nbytes, address)} where `nbytes' is
the number of bytes received and `address' is the address of the socket sending
the data.  See the Unix manual page @code{recv(2)@footnote{https://manpages.debian.org/recv(2)}} for the meaning of the
optional argument `flags'; it defaults to zero.  (The format of `address'
depends on the address family --- see above.)
@end deffn

@geindex recv_into() (méthode socket.socket)
@anchor{library/socket socket socket recv_into}@anchor{12fb}
@deffn {Méthode} socket.recv_into (buffer[, nbytes[, flags]])

Receive up to `nbytes' bytes from the socket, storing the data into a buffer
rather than creating a new bytestring.  If `nbytes' is not specified (or 0),
receive up to the size available in the given buffer.  Returns the number of
bytes received.  See the Unix manual page @code{recv(2)@footnote{https://manpages.debian.org/recv(2)}} for the meaning
of the optional argument `flags'; it defaults to zero.
@end deffn

@geindex send() (méthode socket.socket)
@anchor{library/socket socket socket send}@anchor{d94}
@deffn {Méthode} socket.send (bytes[, flags])

Send data to the socket.  The socket must be connected to a remote socket.  The
optional `flags' argument has the same meaning as for @ref{d91,,recv()} above.
Returns the number of bytes sent. Applications are responsible for checking that
all data has been sent; if only some of the data was transmitted, the
application needs to attempt delivery of the remaining data. For further
information on this topic, consult the @ref{33a2,,Guide pratique ; programmation avec les sockets}.


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex sendall() (méthode socket.socket)
@anchor{library/socket socket socket sendall}@anchor{d95}
@deffn {Méthode} socket.sendall (bytes[, flags])

Send data to the socket.  The socket must be connected to a remote socket.  The
optional `flags' argument has the same meaning as for @ref{d91,,recv()} above.
Unlike @ref{d94,,send()}, this method continues to send data from `bytes' until
either all data has been sent or an error occurs.  @code{None} is returned on
success.  On error, an exception is raised, and there is no way to determine how
much data, if any, was successfully sent.


Modifié dans la version 3.5: The socket timeout is no longer reset each time data is sent successfully.
The socket timeout is now the maximum total duration to send all data.



Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex sendto() (méthode socket.socket)
@anchor{library/socket socket socket sendto}@anchor{d96}
@deffn {Méthode} socket.sendto (bytes, address)

@deffnx {Méthode} socket.sendto (bytes, flags, address)

Send data to the socket.  The socket should not be connected to a remote socket,
since the destination socket is specified by `address'.  The optional `flags'
argument has the same meaning as for @ref{d91,,recv()} above.  Return the number of
bytes sent. (The format of `address' depends on the address family --- see
above.)

Raises an @ref{1848,,auditing event} @code{socket.sendto} with arguments @code{self}, @code{address}.


Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex sendmsg() (méthode socket.socket)
@anchor{library/socket socket socket sendmsg}@anchor{460}
@deffn {Méthode} socket.sendmsg (buffers[, ancdata[, flags[, address]]])

Send normal and ancillary data to the socket, gathering the
non-ancillary data from a series of buffers and concatenating it
into a single message.  The `buffers' argument specifies the
non-ancillary data as an iterable of
@ref{d1b,,bytes-like objects}
(e.g. @ref{1bd,,bytes} objects); the operating system may set a limit
(@ref{2aec,,sysconf()} value @code{SC_IOV_MAX}) on the number of buffers
that can be used.  The `ancdata' argument specifies the ancillary
data (control messages) as an iterable of zero or more tuples
@code{(cmsg_level, cmsg_type, cmsg_data)}, where `cmsg_level' and
`cmsg_type' are integers specifying the protocol level and
protocol-specific type respectively, and `cmsg_data' is a
bytes-like object holding the associated data.  Note that
some systems (in particular, systems without @ref{19c4,,CMSG_SPACE()})
might support sending only one control message per call.  The
`flags' argument defaults to 0 and has the same meaning as for
@ref{d94,,send()}.  If `address' is supplied and not @code{None}, it sets a
destination address for the message.  The return value is the
number of bytes of non-ancillary data sent.

The following function sends the list of file descriptors `fds'
over an @ref{17ad,,AF_UNIX} socket, on systems which support the
@code{SCM_RIGHTS} mechanism.  See also @ref{d93,,recvmsg()}.

@example
import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])
@end example

@ref{1ce0,,Availability}: Unix, not WASI.

Most Unix platforms.

Raises an @ref{1848,,auditing event} @code{socket.sendmsg} with arguments @code{self}, @code{address}.


Ajouté dans la version 3.3.



Modifié dans la version 3.5: Si l'appel système est interrompu et que le gestionnaire de signal ne lève aucune exception, la fonction réessaye l'appel système au lieu de lever une @ref{d75,,InterruptedError} (voir la 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} à propos du raisonnement).

@end deffn

@geindex sendmsg_afalg() (méthode socket.socket)
@anchor{library/socket socket socket sendmsg_afalg}@anchor{cc6}
@deffn {Méthode} socket.sendmsg_afalg ([msg], *, op[, iv[, assoclen[, flags]]])

Specialized version of @ref{460,,sendmsg()} for @ref{cc5,,AF_ALG} socket.
Set mode, IV, AEAD associated data length and flags for @ref{cc5,,AF_ALG} socket.

@ref{1ce0,,Availability}: Linux >= 2.6.38.


Ajouté dans la version 3.6.

@end deffn

@geindex sendfile() (méthode socket.socket)
@anchor{library/socket socket socket sendfile}@anchor{e46}
@deffn {Méthode} socket.sendfile (file, offset=0, count=None)

Send a file until EOF is reached by using high-performance
@ref{afd,,os.sendfile} and return the total number of bytes which were sent.
`file' must be a regular file object opened in binary mode. If
@ref{afd,,os.sendfile} is not available (e.g. Windows) or `file' is not a
regular file @ref{d94,,send()} will be used instead. `offset' tells from where to
start reading the file. If specified, `count' is the total number of bytes
to transmit as opposed to sending the file until EOF is reached. File
position is updated on return or also in case of error in which case
@ref{2930,,file.tell()} can be used to figure out the number of
bytes which were sent. The socket must be of @ref{12d1,,SOCK_STREAM} type.
Non-blocking sockets are not supported.


Ajouté dans la version 3.5.

@end deffn

@geindex set_inheritable() (méthode socket.socket)
@anchor{library/socket socket socket set_inheritable}@anchor{eea}
@deffn {Méthode} socket.set_inheritable (inheritable)

Set the @ref{ee4,,inheritable flag} of the socket's file
descriptor or socket's handle.


Ajouté dans la version 3.4.

@end deffn

@geindex setblocking() (méthode socket.socket)
@anchor{library/socket socket socket setblocking}@anchor{2ac5}
@deffn {Méthode} socket.setblocking (flag)

Set blocking or non-blocking mode of the socket: if `flag' is false, the
socket is set to non-blocking, else to blocking mode.

This method is a shorthand for certain @ref{335e,,settimeout()} calls:


@itemize *

@item 
@code{sock.setblocking(True)} is equivalent to @code{sock.settimeout(None)}

@item 
@code{sock.setblocking(False)} is equivalent to @code{sock.settimeout(0.0)}
@end itemize


Modifié dans la version 3.7: The method no longer applies @ref{bf8,,SOCK_NONBLOCK} flag on
@ref{bfa,,socket.type}.

@end deffn

@geindex settimeout() (méthode socket.socket)
@anchor{library/socket socket socket settimeout}@anchor{335e}
@deffn {Méthode} socket.settimeout (value)

Set a timeout on blocking socket operations.  The `value' argument can be a
nonnegative floating-point number expressing seconds, or @code{None}.
If a non-zero value is given, subsequent socket operations will raise a
@ref{81e,,timeout} exception if the timeout period `value' has elapsed before
the operation has completed.  If zero is given, the socket is put in
non-blocking mode. If @code{None} is given, the socket is put in blocking mode.

For further information, please consult the @ref{33a3,,notes on socket timeouts}.


Modifié dans la version 3.7: The method no longer toggles @ref{bf8,,SOCK_NONBLOCK} flag on
@ref{bfa,,socket.type}.

@end deffn

@geindex setsockopt() (méthode socket.socket)
@anchor{library/socket socket socket setsockopt}@anchor{cc4}
@deffn {Méthode} socket.setsockopt (level, optname, value: int)
@end deffn


@deffn {Méthode} socket.setsockopt (level, optname, value: buffer)
@end deffn


@deffn {Méthode} socket.setsockopt (level, optname, None, optlen: int)

@geindex module;struct

Set the value of the given socket option (see the Unix manual page
@code{setsockopt(2)@footnote{https://manpages.debian.org/setsockopt(2)}}).  The needed symbolic constants are defined in this
module (SO_* etc. <socket-unix-constants>).  The value can be an integer,
@code{None} or a @ref{d1b,,bytes-like object} representing a buffer. In the later
case it is up to the caller to ensure that the bytestring contains the
proper bits (see the optional built-in module @ref{d4,,struct} for a way to
encode C structures as bytestrings). When `value' is set to @code{None},
`optlen' argument is required. It's equivalent to call @code{setsockopt()} C
function with @code{optval=NULL} and @code{optlen=optlen}.


Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.



Modifié dans la version 3.6: setsockopt(level, optname, None, optlen: int) form added.


@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex shutdown() (méthode socket.socket)
@anchor{library/socket socket socket shutdown}@anchor{338e}
@deffn {Méthode} socket.shutdown (how)

Shut down one or both halves of the connection.  If `how' is @ref{338b,,SHUT_RD},
further receives are disallowed.  If `how' is @ref{338c,,SHUT_WR}, further sends
are disallowed.  If `how' is @ref{338d,,SHUT_RDWR}, further sends and receives are
disallowed.

@ref{1ce0,,Availability}: not WASI.
@end deffn

@geindex share() (méthode socket.socket)
@anchor{library/socket socket socket share}@anchor{bf6}
@deffn {Méthode} socket.share (process_id)

Duplicate a socket and prepare it for sharing with a target process.  The
target process must be provided with `process_id'.  The resulting bytes object
can then be passed to the target process using some form of interprocess
communication and the socket can be recreated there using @ref{bf5,,fromshare()}.
Once this method has been called, it is safe to close the socket since
the operating system has already duplicated it for the target process.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.3.

@end deffn

Note that there are no methods @code{read()} or @code{write()}; use
@ref{d91,,recv()} and @ref{d94,,send()} without `flags' argument instead.

Socket objects also have these (read-only) attributes that correspond to the
values given to the @ref{d8e,,socket} constructor.

@geindex family (attribut socket.socket)
@anchor{library/socket socket socket family}@anchor{33a4}
@deffn {Attribut} socket.family

The socket family.
@end deffn

@geindex type (attribut socket.socket)
@anchor{library/socket socket socket type}@anchor{bfa}
@deffn {Attribut} socket.type

The socket type.
@end deffn

@geindex proto (attribut socket.socket)
@anchor{library/socket socket socket proto}@anchor{33a5}
@deffn {Attribut} socket.proto

The socket protocol.
@end deffn

@node Notes on socket timeouts,Exemple<7>,Socket Objects,socket --- Low-level networking interface
@anchor{library/socket notes-on-socket-timeouts}@anchor{33a6}@anchor{library/socket socket-timeouts}@anchor{33a3}
@subsubsection Notes on socket timeouts


A socket object can be in one of three modes: blocking, non-blocking, or
timeout.  Sockets are by default always created in blocking mode, but this
can be changed by calling @ref{3362,,setdefaulttimeout()}.


@itemize *

@item 
In `blocking mode', operations block until complete or the system returns
an error (such as connection timed out).

@item 
In `non-blocking mode', operations fail (with an error that is unfortunately
system-dependent) if they cannot be completed immediately: functions from the
@ref{c0,,select} module can be used to know when and whether a socket is available
for reading or writing.

@item 
In `timeout mode', operations fail if they cannot be completed within the
timeout specified for the socket (they raise a @ref{81e,,timeout} exception)
or if the system returns an error.
@end itemize

@cartouche
@quotation Note 
At the operating system level, sockets in `timeout mode' are internally set
in non-blocking mode.  Also, the blocking and timeout modes are shared between
file descriptors and socket objects that refer to the same network endpoint.
This implementation detail can have visible consequences if e.g. you decide
to use the @ref{339f,,fileno()} of a socket.
@end quotation
@end cartouche

@menu
* Timeouts and the connect method:: 
* Timeouts and the accept method:: 

@end menu

@node Timeouts and the connect method,Timeouts and the accept method,,Notes on socket timeouts
@anchor{library/socket timeouts-and-the-connect-method}@anchor{33a7}
@subsubsection Timeouts and the @code{connect} method


The @ref{d90,,connect()} operation is also subject to the timeout
setting, and in general it is recommended to call @ref{335e,,settimeout()}
before calling @ref{d90,,connect()} or pass a timeout parameter to
@ref{65d,,create_connection()}.  However, the system network stack may also
return a connection timeout error of its own regardless of any Python socket
timeout setting.

@node Timeouts and the accept method,,Timeouts and the connect method,Notes on socket timeouts
@anchor{library/socket timeouts-and-the-accept-method}@anchor{33a8}
@subsubsection Timeouts and the @code{accept} method


If @ref{3393,,getdefaulttimeout()} is not @ref{660,,None}, sockets returned by
the @ref{d8f,,accept()} method inherit that timeout.  Otherwise, the
behaviour depends on settings of the listening socket:


@itemize *

@item 
if the listening socket is in `blocking mode' or in `timeout mode',
the socket returned by @ref{d8f,,accept()} is in `blocking mode';

@item 
if the listening socket is in `non-blocking mode', whether the socket
returned by @ref{d8f,,accept()} is in blocking or non-blocking mode
is operating system-dependent.  If you want to ensure cross-platform
behaviour, it is recommended you manually override this setting.
@end itemize

@node Exemple<7>,,Notes on socket timeouts,socket --- Low-level networking interface
@anchor{library/socket example}@anchor{33a9}@anchor{library/socket socket-example}@anchor{33aa}
@subsubsection Exemple


Here are four minimal example programs using the TCP/IP protocol: a server that
echoes all data that it receives back (servicing only one client), and a client
using it.  Note that a server must perform the sequence @ref{d8e,,socket()},
@ref{14f0,,bind()}, @ref{e47,,listen()}, @ref{d8f,,accept()} (possibly
repeating the @ref{d8f,,accept()} to service more than one client), while a
client only needs the sequence @ref{d8e,,socket()}, @ref{d90,,connect()}.  Also
note that the server does not @ref{d95,,sendall()}/@ref{d91,,recv()} on
the socket it is listening on but on the new socket returned by
@ref{d8f,,accept()}.

The first two examples support IPv4 only.

@example
# Echo server program
import socket

HOST = '@w{'}                 # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)
@end example

@example
# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))
@end example

The next two examples are identical to the above two, but support both IPv4 and
IPv6. The server side will listen to the first address family available (it
should listen to both instead). On most of IPv6-ready systems, IPv6 will take
precedence and the server may not accept IPv4 traffic. The client side will try
to connect to all the addresses returned as a result of the name resolution, and
sends traffic to the first one connected successfully.

@example
# Echo server program
import socket
import sys

HOST = None               # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)
@end example

@example
# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))
@end example

The next example shows how to write a very simple network sniffer with raw
sockets on Windows. The example requires administrator privileges to modify
the interface:

@example
import socket

# the public network interface
HOST = socket.gethostbyname(socket.gethostname())

# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# receive all packets
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a packet
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
@end example

The next example shows how to use the socket interface to communicate to a CAN
network using the raw socket protocol. To use CAN with the broadcast
manager protocol instead, open a socket with:

@example
socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)
@end example

After binding (@code{CAN_RAW}) or connecting (@ref{f8d,,CAN_BCM}) the socket, you
can use the @ref{d94,,socket.send()} and @ref{d91,,socket.recv()} operations (and
their counterparts) on the socket object as usual.

This last example might require special privileges:

@example
import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')
@end example

Running an example several times with too small delay between executions, could
lead to this error:

@example
OSError: [Errno 98] Address already in use
@end example

This is because the previous execution has left the socket in a @code{TIME_WAIT}
state, and can't be immediately reused.

There is a @ref{cb,,socket} flag to set, in order to prevent this,
@code{socket.SO_REUSEADDR}:

@example
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))
@end example

the @code{SO_REUSEADDR} flag tells the kernel to reuse a local socket in
@code{TIME_WAIT} state, without waiting for its natural timeout to expire.


@subsubheading Voir aussi


For an introduction to socket programming (in C), see the following papers:


@itemize -

@item 
`An Introductory 4.3BSD Interprocess Communication Tutorial', by Stuart Sechrest

@item 
`An Advanced 4.3BSD Interprocess Communication Tutorial', by Samuel J.  Leffler et
al,
@end itemize

both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
PS1:7 and PS1:8).  The platform-specific reference material for the various
socket-related system calls are also a valuable source of information on the
details of socket semantics.  For Unix, refer to the manual pages; for Windows,
see the WinSock (or Winsock 2) specification.  For IPv6-ready APIs, readers may
want to refer to 
@geindex RFC; RFC 3493
RFC 3493@footnote{https://datatracker.ietf.org/doc/html/rfc3493.html} titled Basic Socket Interface Extensions for IPv6.


@node ssl --- TLS/SSL wrapper for socket objects,select --- Waiting for I/O completion,socket --- Low-level networking interface,Réseau et communication entre processus
@anchor{library/ssl doc}@anchor{33ab}@anchor{library/ssl module-ssl}@anchor{cf}@anchor{library/ssl ssl-tls-ssl-wrapper-for-socket-objects}@anchor{33ac}
@subsection @code{ssl} --- TLS/SSL wrapper for socket objects


@geindex module; ssl

`Code source :' Lib/ssl.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/ssl.py}

@geindex OpenSSL;(use in module ssl)

@geindex TLS
@geindex SSL
@geindex Transport Layer Security
@geindex Secure Sockets Layer


__________________________________________________________________


This module provides access to Transport Layer Security (often known as "Secure
Sockets Layer") encryption and peer authentication facilities for network
sockets, both client-side and server-side.  This module uses the OpenSSL
library. It is available on all modern Unix systems, Windows, macOS, and
probably additional platforms, as long as OpenSSL is installed on that platform.

@cartouche
@quotation Note 
Some behavior may be platform dependent, since calls are made to the
operating system socket APIs.  The installed version of OpenSSL may also
cause variations in behavior. For example, TLSv1.3 comes with OpenSSL version
1.1.1.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
N’utilisez pas ce module sans lire @ref{32a2,,Security considerations}. Cela pourrait créer un faux sentiment de sécurité, car les paramètres par défaut du module `ssl' ne sont pas nécessairement appropriés pour votre application.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Cette section documente les objets et les fonctions du module @code{ssl}. Pour des informations plus générales sur TLS, SSL et les certificats, le lecteur est prié de se référer aux documents de la section « Voir Aussi » au bas de cette page.

This module provides a class, @ref{8d7,,ssl.SSLSocket}, which is derived from the
@ref{d8e,,socket.socket} type, and provides a socket-like wrapper that also
encrypts and decrypts the data going over the socket with SSL.  It supports
additional methods such as @code{getpeercert()}, which retrieves the
certificate of the other side of the connection, @code{cipher()}, which
retrieves the cipher being used for the secure connection or
@code{get_verified_chain()}, @code{get_unverified_chain()} which retrieves
certificate chain.

Pour les applications plus sophistiquées, la classe @ref{291,,ssl.SSLContext} facilite la gestion des paramètres et des certificats, qui peuvent ensuite être hérités par les connecteurs SSL créés via la méthode @ref{50e,,SSLContext.wrap_socket()}.


Modifié dans la version 3.5.3: Mise à jour pour prendre en charge la liaison avec OpenSSL 1.1.0



Modifié dans la version 3.6: OpenSSL 0.9.8, 1.0.0 et 1.0.1 sont obsolètes et ne sont plus prises en charge. Dans l'avenir, le module `ssl' nécessitera au minimum OpenSSL 1.0.2 ou 1.1.0.



Modifié dans la version 3.10: 
@geindex Python Enhancement Proposals; PEP 644
PEP 644@footnote{https://peps.python.org/pep-0644/} has been implemented. The ssl module requires OpenSSL 1.1.1
or newer.

Use of deprecated constants and functions result in deprecation warnings.


@menu
* Fonctions@comma{} constantes et exceptions: Fonctions constantes et exceptions. 
* SSL Sockets:: 
* SSL Contexts:: 
* Certificates:: 
* Exemples: Exemples<20>. 
* Notes on non-blocking sockets:: 
* Memory BIO Support: Memory BIO Support<2>. 
* SSL session:: 
* Security considerations: Security considerations<2>. 
* TLS 1.3: TLS 1 3. 

@end menu

@node Fonctions constantes et exceptions,SSL Sockets,,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl functions-constants-and-exceptions}@anchor{33ad}
@subsubsection Fonctions, constantes et exceptions


@menu
* Création de connecteurs:: 
* Création de contexte:: 
* Exceptions: Exceptions<16>. 
* Random generation:: 
* Certificate handling:: 
* Constantes: Constantes<9>. 

@end menu

@node Création de connecteurs,Création de contexte,,Fonctions constantes et exceptions
@anchor{library/ssl socket-creation}@anchor{33ae}
@subsubsection Création de connecteurs


Instances of @ref{8d7,,SSLSocket} must be created using the
@ref{50e,,SSLContext.wrap_socket()} method. The helper function
@ref{154,,create_default_context()} returns a new context with secure default
settings.

Exemple de connecteur client avec contexte par défaut et double pile IPv4/IPv6 :

@example
import socket
import ssl

hostname = 'www.python.org'
context = ssl.create_default_context()

with socket.create_connection((hostname, 443)) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())
@end example

Exemple de connecteur client avec contexte personnalisé et IPv4 :

@example
hostname = 'www.python.org'
# PROTOCOL_TLS_CLIENT requires valid cert chain and hostname
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    with context.wrap_socket(sock, server_hostname=hostname) as ssock:
        print(ssock.version())
@end example

Exemple de connecteur serveur à l'écoute sur IPv4 `localhost' :

@example
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')

with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
    sock.bind(('127.0.0.1', 8443))
    sock.listen(5)
    with context.wrap_socket(sock, server_side=True) as ssock:
        conn, addr = ssock.accept()
        ...
@end example

@node Création de contexte,Exceptions<16>,Création de connecteurs,Fonctions constantes et exceptions
@anchor{library/ssl context-creation}@anchor{33af}
@subsubsection Création de contexte


Une fonction utilitaire permettant de créer facilement des objets @ref{291,,SSLContext} pour des usages classiques.

@geindex create_default_context() (dans le module ssl)
@anchor{library/ssl ssl create_default_context}@anchor{154}
@deffn {Fonction} ssl.create_default_context (purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)

Renvoie un nouvel objet @ref{291,,SSLContext}. Le paramètre `purpose' permet de choisir parmi un ensemble de paramètres par défaut en fonction de l'usage souhaité. Les paramètres sont choisis par le module @ref{cf,,ssl} et représentent généralement un niveau de sécurité supérieur à celui utilisé lorsque vous appelez directement le constructeur @ref{291,,SSLContext}.

`cafile', `capath', `cadata' représentent des certificats d'autorité de certification facultatifs approuvés pour la vérification de certificats, comme dans @ref{ed6,,SSLContext.load_verify_locations()}. Si les trois sont à @ref{660,,None}, cette fonction peut choisir de faire confiance aux certificats d'autorité de certification par défaut du système.

The settings are: @ref{85d,,PROTOCOL_TLS_CLIENT} or
@ref{85e,,PROTOCOL_TLS_SERVER}, @ref{823,,OP_NO_SSLv2}, and @ref{824,,OP_NO_SSLv3}
with high encryption cipher suites without RC4 and
without unauthenticated cipher suites. Passing @ref{f9d,,SERVER_AUTH}
as `purpose' sets @ref{33b0,,verify_mode} to @ref{33b1,,CERT_REQUIRED}
and either loads CA certificates (when at least one of `cafile', `capath' or
`cadata' is given) or uses @ref{f9c,,SSLContext.load_default_certs()} to load
default CA certificates.

Lorsque @ref{33b2,,keylog_filename} est pris en charge et que la variable d'environnement 
@geindex SSLKEYLOGFILE
@geindex variable d'environnement; SSLKEYLOGFILE
@code{SSLKEYLOGFILE} est définie, @ref{154,,create_default_context()} active la journalisation des clés.

The default settings for this context include
@ref{155,,VERIFY_X509_PARTIAL_CHAIN} and @ref{156,,VERIFY_X509_STRICT}.
These make the underlying OpenSSL implementation behave more like
a conforming implementation of 
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}, in exchange for a small
amount of incompatibility with older X.509 certificates.

@cartouche
@quotation Note 
Le protocole, les options, l'algorithme de chiffrement et d'autres paramètres peuvent changer pour des valeurs plus restrictives à tout moment sans avertissement préalable. Les valeurs représentent un juste équilibre entre compatibilité et sécurité.

Si votre application nécessite des paramètres spécifiques, vous devez créer une classe @ref{291,,SSLContext} et appliquer les paramètres vous-même.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Si vous constatez que, lorsque certains clients ou serveurs plus anciens tentent de se connecter avec une classe @ref{291,,SSLContext} créée par cette fonction, une erreur indiquant « `Protocol or cipher suite mismatch' » (« Non concordance de protocole ou d'algorithme de chiffrement ») est détectée, il se peut qu'ils ne prennent en charge que SSL 3.0 que cette fonction exclut en utilisant @ref{824,,OP_NO_SSLv3}. SSL3.0 est notoirement considéré comme totalement déficient@footnote{https://fr.wikipedia.org/wiki/POODLE}. Si vous souhaitez toujours continuer à utiliser cette fonction tout en autorisant les connexions SSL 3.0, vous pouvez les réactiver à l'aide de :

@example
ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3
@end example
@end quotation
@end cartouche

@cartouche
@quotation Note 
This context enables @ref{156,,VERIFY_X509_STRICT} by default, which
may reject pre-
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html} or malformed certificates that the
underlying OpenSSL implementation otherwise would accept. While disabling
this is not recommended, you can do so using:

@example
ctx = ssl.create_default_context()
ctx.verify_flags &= ~ssl.VERIFY_X509_STRICT
@end example
@end quotation
@end cartouche


Ajouté dans la version 3.4.



Modifié dans la version 3.4.4: RC4 a été supprimé de la liste des algorithmes de chiffrement par défaut.



Modifié dans la version 3.6: `ChaCha20'/`Poly1305' a été ajouté à la liste des algorithmes de chiffrement par défaut.

`3DES' a été supprimé de la liste des algorithmes de chiffrement par défaut.



Modifié dans la version 3.8: La prise en charge de la journalisation des clés dans 
@geindex SSLKEYLOGFILE
@geindex variable d'environnement; SSLKEYLOGFILE
@code{SSLKEYLOGFILE} a été ajoutée.



Modifié dans la version 3.10: The context now uses @ref{85d,,PROTOCOL_TLS_CLIENT} or
@ref{85e,,PROTOCOL_TLS_SERVER} protocol instead of generic
@ref{33b3,,PROTOCOL_TLS}.



Modifié dans la version 3.13: The context now uses @ref{155,,VERIFY_X509_PARTIAL_CHAIN} and
@ref{156,,VERIFY_X509_STRICT} in its default verify flags.

@end deffn

@node Exceptions<16>,Random generation,Création de contexte,Fonctions constantes et exceptions
@anchor{library/ssl exceptions}@anchor{33b4}
@subsubsection Exceptions


@geindex SSLError
@anchor{library/ssl ssl SSLError}@anchor{1258}
@deffn {Exception} ssl.SSLError

Levée pour signaler une erreur de l'implémentation SSL sous-jacente (actuellement fournie par la bibliothèque OpenSSL). Cela signifie qu'un problème est apparu dans la couche d'authentification et de chiffrement de niveau supérieur qui s'appuie sur la connexion réseau sous-jacente. Cette erreur est un sous-type de @ref{40d,,OSError}. Le code d'erreur et le message des instances de @ref{1258,,SSLError} sont fournis par la bibliothèque OpenSSL.


Modifié dans la version 3.3: @ref{1258,,SSLError} était un sous-type de @ref{103e,,socket.error}.


@geindex library (attribut ssl.SSLError)
@anchor{library/ssl ssl SSLError library}@anchor{1127}
@deffn {Attribut} library

Une chaîne de caractères mnémonique désignant le sous-module OpenSSL dans lequel l'erreur s'est produite, telle que @code{SSL}, @code{PEM} ou @code{X509}. L'étendue des valeurs possibles dépend de la version d'OpenSSL.


Ajouté dans la version 3.3.

@end deffn

@geindex reason (attribut ssl.SSLError)
@anchor{library/ssl ssl SSLError reason}@anchor{1128}
@deffn {Attribut} reason

A string mnemonic designating the reason this error occurred, for
example @code{CERTIFICATE_VERIFY_FAILED}.  The range of possible
values depends on the OpenSSL version.


Ajouté dans la version 3.3.

@end deffn
@end deffn

@geindex SSLZeroReturnError
@anchor{library/ssl ssl SSLZeroReturnError}@anchor{33b5}
@deffn {Exception} ssl.SSLZeroReturnError

A subclass of @ref{1258,,SSLError} raised when trying to read or write and
the SSL connection has been closed cleanly.  Note that this doesn't
mean that the underlying transport (read TCP) has been closed.


Ajouté dans la version 3.3.

@end deffn

@geindex SSLWantReadError
@anchor{library/ssl ssl SSLWantReadError}@anchor{e52}
@deffn {Exception} ssl.SSLWantReadError

Sous-classe de @ref{1258,,SSLError} levée par un connecteur @ref{33b6,,SSL non bloquant} lors d'une tentative de lecture ou d'écriture de données, alors que davantage de données doivent être reçues sur la couche TCP sous-jacente avant que la demande puisse être satisfaite.


Ajouté dans la version 3.3.

@end deffn

@geindex SSLWantWriteError
@anchor{library/ssl ssl SSLWantWriteError}@anchor{e53}
@deffn {Exception} ssl.SSLWantWriteError

A subclass of @ref{1258,,SSLError} raised by a @ref{33b6,,non-blocking SSL socket} when trying to read or write data, but more data needs
to be sent on the underlying TCP transport before the request can be
fulfilled.


Ajouté dans la version 3.3.

@end deffn

@geindex SSLSyscallError
@anchor{library/ssl ssl SSLSyscallError}@anchor{33b7}
@deffn {Exception} ssl.SSLSyscallError

A subclass of @ref{1258,,SSLError} raised when a system error was encountered
while trying to fulfill an operation on a SSL socket.  Unfortunately,
there is no easy way to inspect the original errno number.


Ajouté dans la version 3.3.

@end deffn

@geindex SSLEOFError
@anchor{library/ssl ssl SSLEOFError}@anchor{16d2}
@deffn {Exception} ssl.SSLEOFError

A subclass of @ref{1258,,SSLError} raised when the SSL connection has been
terminated abruptly.  Generally, you shouldn't try to reuse the underlying
transport when this error is encountered.


Ajouté dans la version 3.3.

@end deffn

@geindex SSLCertVerificationError
@anchor{library/ssl ssl SSLCertVerificationError}@anchor{b6a}
@deffn {Exception} ssl.SSLCertVerificationError

A subclass of @ref{1258,,SSLError} raised when certificate validation has
failed.


Ajouté dans la version 3.7.


@geindex verify_code (attribut ssl.SSLCertVerificationError)
@anchor{library/ssl ssl SSLCertVerificationError verify_code}@anchor{33b8}
@deffn {Attribut} verify_code

A numeric error number that denotes the verification error.
@end deffn

@geindex verify_message (attribut ssl.SSLCertVerificationError)
@anchor{library/ssl ssl SSLCertVerificationError verify_message}@anchor{33b9}
@deffn {Attribut} verify_message

A human readable string of the verification error.
@end deffn
@end deffn

@geindex CertificateError
@anchor{library/ssl ssl CertificateError}@anchor{33ba}
@deffn {Exception} ssl.CertificateError

An alias for @ref{b6a,,SSLCertVerificationError}.


Modifié dans la version 3.7: The exception is now an alias for @ref{b6a,,SSLCertVerificationError}.

@end deffn

@node Random generation,Certificate handling,Exceptions<16>,Fonctions constantes et exceptions
@anchor{library/ssl random-generation}@anchor{33bb}
@subsubsection Random generation


@geindex RAND_bytes() (dans le module ssl)
@anchor{library/ssl ssl RAND_bytes}@anchor{50d}
@deffn {Fonction} ssl.RAND_bytes (num)

Return `num' cryptographically strong pseudo-random bytes. Raises an
@ref{1258,,SSLError} if the PRNG has not been seeded with enough data or if the
operation is not supported by the current RAND method. @ref{1854,,RAND_status()}
can be used to check the status of the PRNG and @ref{33bc,,RAND_add()} can be used
to seed the PRNG.

For almost all applications @ref{50c,,os.urandom()} is preferable.

Read the Wikipedia article, Cryptographically secure pseudorandom number generator (CSPRNG)@footnote{https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator},
to get the requirements of a cryptographically strong generator.


Ajouté dans la version 3.3.

@end deffn

@geindex RAND_status() (dans le module ssl)
@anchor{library/ssl ssl RAND_status}@anchor{1854}
@deffn {Fonction} ssl.RAND_status ()

Return @code{True} if the SSL pseudo-random number generator has been seeded
with 'enough' randomness, and @code{False} otherwise.  You can use
@code{ssl.RAND_egd()} and @ref{33bc,,ssl.RAND_add()} to increase the randomness of
the pseudo-random number generator.
@end deffn

@geindex RAND_add() (dans le module ssl)
@anchor{library/ssl ssl RAND_add}@anchor{33bc}
@deffn {Fonction} ssl.RAND_add (bytes, entropy)

Mix the given `bytes' into the SSL pseudo-random number generator.  The
parameter `entropy' (a float) is a lower bound on the entropy contained in
string (so you can always use @code{0.0}).  See 
@geindex RFC; RFC 1750
RFC 1750@footnote{https://datatracker.ietf.org/doc/html/rfc1750.html} for more
information on sources of entropy.


Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end deffn

@node Certificate handling,Constantes<9>,Random generation,Fonctions constantes et exceptions
@anchor{library/ssl certificate-handling}@anchor{33bd}
@subsubsection Certificate handling


@c import ssl

@geindex cert_time_to_seconds() (dans le module ssl)
@anchor{library/ssl ssl cert_time_to_seconds}@anchor{e54}
@deffn {Fonction} ssl.cert_time_to_seconds (cert_time)

Return the time in seconds since the Epoch, given the @code{cert_time}
string representing the "notBefore" or "notAfter" date from a
certificate in @code{"%b %d %H:%M:%S %Y %Z"} strptime format (C
locale).

Here's an example:

@example
>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
>>> timestamp  
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))  
2018-01-05 09:34:43
@end example

"notBefore" or "notAfter" dates must use GMT (
@geindex RFC; RFC 5280
RFC 5280@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}).


Modifié dans la version 3.5: Interpret the input time as a time in UTC as specified by 'GMT'
timezone in the input string. Local timezone was used
previously. Return an integer (no fractions of a second in the
input format)

@end deffn

@geindex get_server_certificate() (dans le module ssl)
@anchor{library/ssl ssl get_server_certificate}@anchor{826}
@deffn {Fonction} ssl.get_server_certificate (addr, ssl_version=PROTOCOL_TLS_CLIENT, ca_certs=None[, timeout])

Given the address @code{addr} of an SSL-protected server, as a (`hostname',
`port-number') pair, fetches the server's certificate, and returns it as a
PEM-encoded string.  If @code{ssl_version} is specified, uses that version of
the SSL protocol to attempt to connect to the server.  If `ca_certs' is
specified, it should be a file containing a list of root certificates, the
same format as used for the `cafile' parameter in
@ref{ed6,,SSLContext.load_verify_locations()}.  The call will attempt to validate the
server certificate against that set of root certificates, and will fail
if the validation attempt fails.  A timeout can be specified with the
@code{timeout} parameter.


Modifié dans la version 3.3: This function is now IPv6-compatible.



Modifié dans la version 3.5: The default `ssl_version' is changed from @ref{33be,,PROTOCOL_SSLv3} to
@ref{33b3,,PROTOCOL_TLS} for maximum compatibility with modern servers.



Modifié dans la version 3.10: The `timeout' parameter was added.

@end deffn

@geindex DER_cert_to_PEM_cert() (dans le module ssl)
@anchor{library/ssl ssl DER_cert_to_PEM_cert}@anchor{33bf}
@deffn {Fonction} ssl.DER_cert_to_PEM_cert (DER_cert_bytes)

Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
string version of the same certificate.
@end deffn

@geindex PEM_cert_to_DER_cert() (dans le module ssl)
@anchor{library/ssl ssl PEM_cert_to_DER_cert}@anchor{33c0}
@deffn {Fonction} ssl.PEM_cert_to_DER_cert (PEM_cert_string)

Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
bytes for that same certificate.
@end deffn

@geindex get_default_verify_paths() (dans le module ssl)
@anchor{library/ssl ssl get_default_verify_paths}@anchor{f94}
@deffn {Fonction} ssl.get_default_verify_paths ()

Returns a named tuple with paths to OpenSSL's default cafile and capath.
The paths are the same as used by
@ref{f95,,SSLContext.set_default_verify_paths()}. The return value is a
@ref{639,,named tuple} @code{DefaultVerifyPaths}:


@itemize *

@item 
@code{cafile} - resolved path to cafile or @code{None} if the file doesn't exist,

@item 
@code{capath} - resolved path to capath or @code{None} if the directory doesn't exist,

@item 
@code{openssl_cafile_env} - OpenSSL's environment key that points to a cafile,

@item 
@code{openssl_cafile} - hard coded path to a cafile,

@item 
@code{openssl_capath_env} - OpenSSL's environment key that points to a capath,

@item 
@code{openssl_capath} - hard coded path to a capath directory
@end itemize


Ajouté dans la version 3.4.

@end deffn

@geindex enum_certificates() (dans le module ssl)
@anchor{library/ssl ssl enum_certificates}@anchor{f9f}
@deffn {Fonction} ssl.enum_certificates (store_name)

Retrieve certificates from Windows' system cert store. `store_name' may be
one of @code{CA}, @code{ROOT} or @code{MY}. Windows may provide additional cert
stores, too.

The function returns a list of (cert_bytes, encoding_type, trust) tuples.
The encoding_type specifies the encoding of cert_bytes. It is either
@code{x509_asn} for X.509 ASN.1 data or @code{pkcs_7_asn} for
PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set
of OIDS or exactly @code{True} if the certificate is trustworthy for all
purposes.

Exemple :

@example
>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', @{'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'@}),
 (b'data...', 'x509_asn', True)]
@end example

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.4.

@end deffn

@geindex enum_crls() (dans le module ssl)
@anchor{library/ssl ssl enum_crls}@anchor{fa0}
@deffn {Fonction} ssl.enum_crls (store_name)

Retrieve CRLs from Windows' system cert store. `store_name' may be
one of @code{CA}, @code{ROOT} or @code{MY}. Windows may provide additional cert
stores, too.

The function returns a list of (cert_bytes, encoding_type, trust) tuples.
The encoding_type specifies the encoding of cert_bytes. It is either
@code{x509_asn} for X.509 ASN.1 data or @code{pkcs_7_asn} for
PKCS#7 ASN.1 data.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.4.

@end deffn

@node Constantes<9>,,Certificate handling,Fonctions constantes et exceptions
@anchor{library/ssl constants}@anchor{33c1}
@subsubsection Constantes


@quotation

All constants are now @ref{ccd,,enum.IntEnum} or @ref{2280,,enum.IntFlag} collections.


Ajouté dans la version 3.6.

@end quotation

@geindex CERT_NONE (dans le module ssl)
@anchor{library/ssl ssl CERT_NONE}@anchor{33c2}
@deffn {Données} ssl.CERT_NONE

Possible value for @ref{33b0,,SSLContext.verify_mode}.
Except for @ref{85d,,PROTOCOL_TLS_CLIENT},
it is the default mode.  With client-side sockets, just about any
cert is accepted.  Validation errors, such as untrusted or expired cert,
are ignored and do not abort the TLS/SSL handshake.

In server mode, no certificate is requested from the client, so the client
does not send any for client cert authentication.

See the discussion of @ref{32a2,,Security considerations} below.
@end deffn

@geindex CERT_OPTIONAL (dans le module ssl)
@anchor{library/ssl ssl CERT_OPTIONAL}@anchor{33c3}
@deffn {Données} ssl.CERT_OPTIONAL

Possible value for @ref{33b0,,SSLContext.verify_mode}.
In client mode, @ref{33c3,,CERT_OPTIONAL}
has the same meaning as @ref{33b1,,CERT_REQUIRED}. It is recommended to
use @ref{33b1,,CERT_REQUIRED} for client-side sockets instead.

In server mode, a client certificate request is sent to the client.  The
client may either ignore the request or send a certificate in order
perform TLS client cert authentication.  If the client chooses to send
a certificate, it is verified.  Any verification error immediately aborts
the TLS handshake.

Use of this setting requires a valid set of CA certificates to
be passed to @ref{ed6,,SSLContext.load_verify_locations()}.
@end deffn

@geindex CERT_REQUIRED (dans le module ssl)
@anchor{library/ssl ssl CERT_REQUIRED}@anchor{33b1}
@deffn {Données} ssl.CERT_REQUIRED

Possible value for @ref{33b0,,SSLContext.verify_mode}.
In this mode, certificates are
required from the other side of the socket connection; an @ref{1258,,SSLError}
will be raised if no certificate is provided, or if its validation fails.
This mode is `not' sufficient to verify a certificate in client mode as
it does not match hostnames.  @ref{33c4,,check_hostname} must be
enabled as well to verify the authenticity of a cert.
@ref{85d,,PROTOCOL_TLS_CLIENT} uses @ref{33b1,,CERT_REQUIRED} and
enables @ref{33c4,,check_hostname} by default.

With server socket, this mode provides mandatory TLS client cert
authentication.  A client certificate request is sent to the client and
the client must provide a valid and trusted certificate.

Use of this setting requires a valid set of CA certificates to
be passed to @ref{ed6,,SSLContext.load_verify_locations()}.
@end deffn

@geindex VerifyMode (classe dans ssl)
@anchor{library/ssl ssl VerifyMode}@anchor{33c5}
@deffn {Classe} ssl.VerifyMode

@ref{ccd,,enum.IntEnum} collection of CERT_* constants.


Ajouté dans la version 3.6.

@end deffn

@geindex VERIFY_DEFAULT (dans le module ssl)
@anchor{library/ssl ssl VERIFY_DEFAULT}@anchor{f99}
@deffn {Données} ssl.VERIFY_DEFAULT

Possible value for @ref{f98,,SSLContext.verify_flags}. In this mode, certificate
revocation lists (CRLs) are not checked. By default OpenSSL does neither
require nor verify CRLs.


Ajouté dans la version 3.4.

@end deffn

@geindex VERIFY_CRL_CHECK_LEAF (dans le module ssl)
@anchor{library/ssl ssl VERIFY_CRL_CHECK_LEAF}@anchor{f9a}
@deffn {Données} ssl.VERIFY_CRL_CHECK_LEAF

Possible value for @ref{f98,,SSLContext.verify_flags}. In this mode, only the
peer cert is checked but none of the intermediate CA certificates. The mode
requires a valid CRL that is signed by the peer cert's issuer (its direct
ancestor CA). If no proper CRL has been loaded with
@ref{ed6,,SSLContext.load_verify_locations}, validation will fail.


Ajouté dans la version 3.4.

@end deffn

@geindex VERIFY_CRL_CHECK_CHAIN (dans le module ssl)
@anchor{library/ssl ssl VERIFY_CRL_CHECK_CHAIN}@anchor{f9b}
@deffn {Données} ssl.VERIFY_CRL_CHECK_CHAIN

Possible value for @ref{f98,,SSLContext.verify_flags}. In this mode, CRLs of
all certificates in the peer cert chain are checked.


Ajouté dans la version 3.4.

@end deffn

@geindex VERIFY_X509_STRICT (dans le module ssl)
@anchor{library/ssl ssl VERIFY_X509_STRICT}@anchor{156}
@deffn {Données} ssl.VERIFY_X509_STRICT

Possible value for @ref{f98,,SSLContext.verify_flags} to disable workarounds
for broken X.509 certificates.


Ajouté dans la version 3.4.

@end deffn

@geindex VERIFY_ALLOW_PROXY_CERTS (dans le module ssl)
@anchor{library/ssl ssl VERIFY_ALLOW_PROXY_CERTS}@anchor{1869}
@deffn {Données} ssl.VERIFY_ALLOW_PROXY_CERTS

Possible value for @ref{f98,,SSLContext.verify_flags} to enables proxy
certificate verification.


Ajouté dans la version 3.10.

@end deffn

@geindex VERIFY_X509_TRUSTED_FIRST (dans le module ssl)
@anchor{library/ssl ssl VERIFY_X509_TRUSTED_FIRST}@anchor{33c6}
@deffn {Données} ssl.VERIFY_X509_TRUSTED_FIRST

Possible value for @ref{f98,,SSLContext.verify_flags}. It instructs OpenSSL to
prefer trusted certificates when building the trust chain to validate a
certificate. This flag is enabled by default.


Ajouté dans la version 3.4.4.

@end deffn

@geindex VERIFY_X509_PARTIAL_CHAIN (dans le module ssl)
@anchor{library/ssl ssl VERIFY_X509_PARTIAL_CHAIN}@anchor{155}
@deffn {Données} ssl.VERIFY_X509_PARTIAL_CHAIN

Possible value for @ref{f98,,SSLContext.verify_flags}. It instructs OpenSSL to
accept intermediate CAs in the trust store to be treated as trust-anchors,
in the same way as the self-signed root CA certificates. This makes it
possible to trust certificates issued by an intermediate CA without having
to trust its ancestor root CA.


Ajouté dans la version 3.10.

@end deffn

@geindex VerifyFlags (classe dans ssl)
@anchor{library/ssl ssl VerifyFlags}@anchor{33c7}
@deffn {Classe} ssl.VerifyFlags

@ref{2280,,enum.IntFlag} collection of VERIFY_* constants.


Ajouté dans la version 3.6.

@end deffn

@geindex PROTOCOL_TLS (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_TLS}@anchor{33b3}
@deffn {Données} ssl.PROTOCOL_TLS

Selects the highest protocol version that both the client and server support.
Despite the name, this option can select both "SSL" and "TLS" protocols.


Ajouté dans la version 3.6.



Obsolète depuis la version 3.10: TLS clients and servers require different default settings for secure
communication. The generic TLS protocol constant is deprecated in
favor of @ref{85d,,PROTOCOL_TLS_CLIENT} and @ref{85e,,PROTOCOL_TLS_SERVER}.

@end deffn

@geindex PROTOCOL_TLS_CLIENT (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_TLS_CLIENT}@anchor{85d}
@deffn {Données} ssl.PROTOCOL_TLS_CLIENT

Auto-negotiate the highest protocol version that both the client and
server support, and configure the context client-side connections. The
protocol enables @ref{33b1,,CERT_REQUIRED} and
@ref{33c4,,check_hostname} by default.


Ajouté dans la version 3.6.

@end deffn

@geindex PROTOCOL_TLS_SERVER (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_TLS_SERVER}@anchor{85e}
@deffn {Données} ssl.PROTOCOL_TLS_SERVER

Auto-negotiate the highest protocol version that both the client and
server support, and configure the context server-side connections.


Ajouté dans la version 3.6.

@end deffn

@geindex PROTOCOL_SSLv23 (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_SSLv23}@anchor{33c8}
@deffn {Données} ssl.PROTOCOL_SSLv23

Alias for @ref{33b3,,PROTOCOL_TLS}.


Obsolète depuis la version 3.6: Use @ref{33b3,,PROTOCOL_TLS} instead.

@end deffn

@geindex PROTOCOL_SSLv3 (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_SSLv3}@anchor{33be}
@deffn {Données} ssl.PROTOCOL_SSLv3

Selects SSL version 3 as the channel encryption protocol.

This protocol is not available if OpenSSL is compiled with the
@code{no-ssl3} option.

@cartouche
@quotation Avertissement 
SSL version 3 is insecure.  Its use is highly discouraged.
@end quotation
@end cartouche


Obsolète depuis la version 3.6: OpenSSL has deprecated all version specific protocols. Use the default
protocol @ref{85e,,PROTOCOL_TLS_SERVER} or @ref{85d,,PROTOCOL_TLS_CLIENT}
with @ref{85b,,SSLContext.minimum_version} and
@ref{85c,,SSLContext.maximum_version} instead.

@end deffn

@geindex PROTOCOL_TLSv1 (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_TLSv1}@anchor{33c9}
@deffn {Données} ssl.PROTOCOL_TLSv1

Selects TLS version 1.0 as the channel encryption protocol.


Obsolète depuis la version 3.6: OpenSSL has deprecated all version specific protocols.

@end deffn

@geindex PROTOCOL_TLSv1_1 (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_TLSv1_1}@anchor{f92}
@deffn {Données} ssl.PROTOCOL_TLSv1_1

Selects TLS version 1.1 as the channel encryption protocol.
Available only with openssl version 1.0.1+.


Ajouté dans la version 3.4.



Obsolète depuis la version 3.6: OpenSSL has deprecated all version specific protocols.

@end deffn

@geindex PROTOCOL_TLSv1_2 (dans le module ssl)
@anchor{library/ssl ssl PROTOCOL_TLSv1_2}@anchor{f93}
@deffn {Données} ssl.PROTOCOL_TLSv1_2

Selects TLS version 1.2 as the channel encryption protocol.
Available only with openssl version 1.0.1+.


Ajouté dans la version 3.4.



Obsolète depuis la version 3.6: OpenSSL has deprecated all version specific protocols.

@end deffn

@geindex OP_ALL (dans le module ssl)
@anchor{library/ssl ssl OP_ALL}@anchor{33ca}
@deffn {Données} ssl.OP_ALL

Enables workarounds for various bugs present in other SSL implementations.
This option is set by default.  It does not necessarily set the same
flags as OpenSSL's @code{SSL_OP_ALL} constant.


Ajouté dans la version 3.2.

@end deffn

@geindex OP_NO_SSLv2 (dans le module ssl)
@anchor{library/ssl ssl OP_NO_SSLv2}@anchor{823}
@deffn {Données} ssl.OP_NO_SSLv2

Prevents an SSLv2 connection.  This option is only applicable in
conjunction with @ref{33b3,,PROTOCOL_TLS}.  It prevents the peers from
choosing SSLv2 as the protocol version.


Ajouté dans la version 3.2.



Obsolète depuis la version 3.6: SSLv2 is deprecated

@end deffn

@geindex OP_NO_SSLv3 (dans le module ssl)
@anchor{library/ssl ssl OP_NO_SSLv3}@anchor{824}
@deffn {Données} ssl.OP_NO_SSLv3

Prevents an SSLv3 connection.  This option is only applicable in
conjunction with @ref{33b3,,PROTOCOL_TLS}.  It prevents the peers from
choosing SSLv3 as the protocol version.


Ajouté dans la version 3.2.



Obsolète depuis la version 3.6: SSLv3 is deprecated

@end deffn

@geindex OP_NO_TLSv1 (dans le module ssl)
@anchor{library/ssl ssl OP_NO_TLSv1}@anchor{33cb}
@deffn {Données} ssl.OP_NO_TLSv1

Prevents a TLSv1 connection.  This option is only applicable in
conjunction with @ref{33b3,,PROTOCOL_TLS}.  It prevents the peers from
choosing TLSv1 as the protocol version.


Ajouté dans la version 3.2.



Obsolète depuis la version 3.7: The option is deprecated since OpenSSL 1.1.0, use the new
@ref{85b,,SSLContext.minimum_version} and
@ref{85c,,SSLContext.maximum_version} instead.

@end deffn

@geindex OP_NO_TLSv1_1 (dans le module ssl)
@anchor{library/ssl ssl OP_NO_TLSv1_1}@anchor{33cc}
@deffn {Données} ssl.OP_NO_TLSv1_1

Prevents a TLSv1.1 connection. This option is only applicable in conjunction
with @ref{33b3,,PROTOCOL_TLS}. It prevents the peers from choosing TLSv1.1 as
the protocol version. Available only with openssl version 1.0.1+.


Ajouté dans la version 3.4.



Obsolète depuis la version 3.7: The option is deprecated since OpenSSL 1.1.0.

@end deffn

@geindex OP_NO_TLSv1_2 (dans le module ssl)
@anchor{library/ssl ssl OP_NO_TLSv1_2}@anchor{33cd}
@deffn {Données} ssl.OP_NO_TLSv1_2

Prevents a TLSv1.2 connection. This option is only applicable in conjunction
with @ref{33b3,,PROTOCOL_TLS}. It prevents the peers from choosing TLSv1.2 as
the protocol version. Available only with openssl version 1.0.1+.


Ajouté dans la version 3.4.



Obsolète depuis la version 3.7: The option is deprecated since OpenSSL 1.1.0.

@end deffn

@geindex OP_NO_TLSv1_3 (dans le module ssl)
@anchor{library/ssl ssl OP_NO_TLSv1_3}@anchor{1834}
@deffn {Données} ssl.OP_NO_TLSv1_3

Prevents a TLSv1.3 connection. This option is only applicable in conjunction
with @ref{33b3,,PROTOCOL_TLS}. It prevents the peers from choosing TLSv1.3 as
the protocol version. TLS 1.3 is available with OpenSSL 1.1.1 or later.
When Python has been compiled against an older version of OpenSSL, the
flag defaults to `0'.


Ajouté dans la version 3.6.3.



Obsolète depuis la version 3.7: The option is deprecated since OpenSSL 1.1.0. It was added to 2.7.15 and
3.6.3 for backwards compatibility with OpenSSL 1.0.2.

@end deffn

@geindex OP_NO_RENEGOTIATION (dans le module ssl)
@anchor{library/ssl ssl OP_NO_RENEGOTIATION}@anchor{33ce}
@deffn {Données} ssl.OP_NO_RENEGOTIATION

Disable all renegotiation in TLSv1.2 and earlier. Do not send
HelloRequest messages, and ignore renegotiation requests via ClientHello.

This option is only available with OpenSSL 1.1.0h and later.


Ajouté dans la version 3.7.

@end deffn

@geindex OP_CIPHER_SERVER_PREFERENCE (dans le module ssl)
@anchor{library/ssl ssl OP_CIPHER_SERVER_PREFERENCE}@anchor{1129}
@deffn {Données} ssl.OP_CIPHER_SERVER_PREFERENCE

Use the server's cipher ordering preference, rather than the client's.
This option has no effect on client sockets and SSLv2 server sockets.


Ajouté dans la version 3.3.

@end deffn

@geindex OP_SINGLE_DH_USE (dans le module ssl)
@anchor{library/ssl ssl OP_SINGLE_DH_USE}@anchor{33cf}
@deffn {Données} ssl.OP_SINGLE_DH_USE

Prevents reuse of the same DH key for distinct SSL sessions.  This
improves forward secrecy but requires more computational resources.
This option only applies to server sockets.


Ajouté dans la version 3.3.

@end deffn

@geindex OP_SINGLE_ECDH_USE (dans le module ssl)
@anchor{library/ssl ssl OP_SINGLE_ECDH_USE}@anchor{33d0}
@deffn {Données} ssl.OP_SINGLE_ECDH_USE

Prevents reuse of the same ECDH key for distinct SSL sessions.  This
improves forward secrecy but requires more computational resources.
This option only applies to server sockets.


Ajouté dans la version 3.3.

@end deffn

@geindex OP_ENABLE_MIDDLEBOX_COMPAT (dans le module ssl)
@anchor{library/ssl ssl OP_ENABLE_MIDDLEBOX_COMPAT}@anchor{33d1}
@deffn {Données} ssl.OP_ENABLE_MIDDLEBOX_COMPAT

Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake to make
a TLS 1.3 connection look more like a TLS 1.2 connection.

This option is only available with OpenSSL 1.1.1 and later.


Ajouté dans la version 3.8.

@end deffn

@geindex OP_NO_COMPRESSION (dans le module ssl)
@anchor{library/ssl ssl OP_NO_COMPRESSION}@anchor{1126}
@deffn {Données} ssl.OP_NO_COMPRESSION

Disable compression on the SSL channel.  This is useful if the application
protocol supports its own compression scheme.


Ajouté dans la version 3.3.

@end deffn

@geindex Options (classe dans ssl)
@anchor{library/ssl ssl Options}@anchor{33d2}
@deffn {Classe} ssl.Options

@ref{2280,,enum.IntFlag} collection of OP_* constants.
@end deffn

@geindex OP_NO_TICKET (dans le module ssl)
@anchor{library/ssl ssl OP_NO_TICKET}@anchor{33d3}
@deffn {Données} ssl.OP_NO_TICKET

Prevent client side from requesting a session ticket.


Ajouté dans la version 3.6.

@end deffn

@geindex OP_IGNORE_UNEXPECTED_EOF (dans le module ssl)
@anchor{library/ssl ssl OP_IGNORE_UNEXPECTED_EOF}@anchor{821}
@deffn {Données} ssl.OP_IGNORE_UNEXPECTED_EOF

Ignore unexpected shutdown of TLS connections.

This option is only available with OpenSSL 3.0.0 and later.


Ajouté dans la version 3.10.

@end deffn

@geindex OP_ENABLE_KTLS (dans le module ssl)
@anchor{library/ssl ssl OP_ENABLE_KTLS}@anchor{1725}
@deffn {Données} ssl.OP_ENABLE_KTLS

Enable the use of the kernel TLS. To benefit from the feature, OpenSSL must
have been compiled with support for it, and the negotiated cipher suites and
extensions must be supported by it (a list of supported ones may vary by
platform and kernel version).

Note that with enabled kernel TLS some cryptographic operations are
performed by the kernel directly and not via any available OpenSSL
Providers. This might be undesirable if, for example, the application
requires all cryptographic operations to be performed by the FIPS provider.

This option is only available with OpenSSL 3.0.0 and later.


Ajouté dans la version 3.12.

@end deffn

@geindex OP_LEGACY_SERVER_CONNECT (dans le module ssl)
@anchor{library/ssl ssl OP_LEGACY_SERVER_CONNECT}@anchor{170b}
@deffn {Données} ssl.OP_LEGACY_SERVER_CONNECT

Allow legacy insecure renegotiation between OpenSSL and unpatched servers
only.


Ajouté dans la version 3.12.

@end deffn

@geindex HAS_ALPN (dans le module ssl)
@anchor{library/ssl ssl HAS_ALPN}@anchor{e4f}
@deffn {Données} ssl.HAS_ALPN

Whether the OpenSSL library has built-in support for the `Application-Layer
Protocol Negotiation' TLS extension as described in 
@geindex RFC; RFC 7301
RFC 7301@footnote{https://datatracker.ietf.org/doc/html/rfc7301.html}.


Ajouté dans la version 3.5.

@end deffn

@geindex HAS_NEVER_CHECK_COMMON_NAME (dans le module ssl)
@anchor{library/ssl ssl HAS_NEVER_CHECK_COMMON_NAME}@anchor{33d4}
@deffn {Données} ssl.HAS_NEVER_CHECK_COMMON_NAME

Whether the OpenSSL library has built-in support not checking subject
common name and @ref{b6b,,SSLContext.hostname_checks_common_name} is
writeable.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_ECDH (dans le module ssl)
@anchor{library/ssl ssl HAS_ECDH}@anchor{33d5}
@deffn {Données} ssl.HAS_ECDH

Whether the OpenSSL library has built-in support for the Elliptic Curve-based
Diffie-Hellman key exchange.  This should be true unless the feature was
explicitly disabled by the distributor.


Ajouté dans la version 3.3.

@end deffn

@geindex HAS_SNI (dans le module ssl)
@anchor{library/ssl ssl HAS_SNI}@anchor{33d6}
@deffn {Données} ssl.HAS_SNI

Whether the OpenSSL library has built-in support for the `Server Name
Indication' extension (as defined in 
@geindex RFC; RFC 6066
RFC 6066@footnote{https://datatracker.ietf.org/doc/html/rfc6066.html}).


Ajouté dans la version 3.2.

@end deffn

@geindex HAS_NPN (dans le module ssl)
@anchor{library/ssl ssl HAS_NPN}@anchor{33d7}
@deffn {Données} ssl.HAS_NPN

Whether the OpenSSL library has built-in support for the `Next Protocol
Negotiation' as described in the Application Layer Protocol Negotiation@footnote{https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation}.
When true, you can use the @ref{2f6,,SSLContext.set_npn_protocols()} method to advertise
which protocols you want to support.


Ajouté dans la version 3.3.

@end deffn

@geindex HAS_SSLv2 (dans le module ssl)
@anchor{library/ssl ssl HAS_SSLv2}@anchor{33d8}
@deffn {Données} ssl.HAS_SSLv2

Whether the OpenSSL library has built-in support for the SSL 2.0 protocol.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_SSLv3 (dans le module ssl)
@anchor{library/ssl ssl HAS_SSLv3}@anchor{33d9}
@deffn {Données} ssl.HAS_SSLv3

Whether the OpenSSL library has built-in support for the SSL 3.0 protocol.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_TLSv1 (dans le module ssl)
@anchor{library/ssl ssl HAS_TLSv1}@anchor{33da}
@deffn {Données} ssl.HAS_TLSv1

Whether the OpenSSL library has built-in support for the TLS 1.0 protocol.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_TLSv1_1 (dans le module ssl)
@anchor{library/ssl ssl HAS_TLSv1_1}@anchor{b71}
@deffn {Données} ssl.HAS_TLSv1_1

Whether the OpenSSL library has built-in support for the TLS 1.1 protocol.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_TLSv1_2 (dans le module ssl)
@anchor{library/ssl ssl HAS_TLSv1_2}@anchor{33db}
@deffn {Données} ssl.HAS_TLSv1_2

Whether the OpenSSL library has built-in support for the TLS 1.2 protocol.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_TLSv1_3 (dans le module ssl)
@anchor{library/ssl ssl HAS_TLSv1_3}@anchor{33dc}
@deffn {Données} ssl.HAS_TLSv1_3

Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.


Ajouté dans la version 3.7.

@end deffn

@geindex HAS_PSK (dans le module ssl)
@anchor{library/ssl ssl HAS_PSK}@anchor{33dd}
@deffn {Données} ssl.HAS_PSK

Whether the OpenSSL library has built-in support for TLS-PSK.


Ajouté dans la version 3.13.

@end deffn

@geindex CHANNEL_BINDING_TYPES (dans le module ssl)
@anchor{library/ssl ssl CHANNEL_BINDING_TYPES}@anchor{33de}
@deffn {Données} ssl.CHANNEL_BINDING_TYPES

List of supported TLS channel binding types.  Strings in this list
can be used as arguments to @ref{1124,,SSLSocket.get_channel_binding()}.


Ajouté dans la version 3.3.

@end deffn

@geindex OPENSSL_VERSION (dans le module ssl)
@anchor{library/ssl ssl OPENSSL_VERSION}@anchor{11fc}
@deffn {Données} ssl.OPENSSL_VERSION

The version string of the OpenSSL library loaded by the interpreter:

@example
>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k  26 Jan 2017'
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex OPENSSL_VERSION_INFO (dans le module ssl)
@anchor{library/ssl ssl OPENSSL_VERSION_INFO}@anchor{11fd}
@deffn {Données} ssl.OPENSSL_VERSION_INFO

A tuple of five integers representing version information about the
OpenSSL library:

@example
>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex OPENSSL_VERSION_NUMBER (dans le module ssl)
@anchor{library/ssl ssl OPENSSL_VERSION_NUMBER}@anchor{11fe}
@deffn {Données} ssl.OPENSSL_VERSION_NUMBER

The raw version number of the OpenSSL library, as a single integer:

@example
>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex ALERT_DESCRIPTION_HANDSHAKE_FAILURE (dans le module ssl)
@geindex ALERT_DESCRIPTION_INTERNAL_ERROR (dans le module ssl)
@anchor{library/ssl ssl ALERT_DESCRIPTION_HANDSHAKE_FAILURE}@anchor{33df}
@deffn {Données} ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
@anchor{library/ssl ssl ALERT_DESCRIPTION_INTERNAL_ERROR}@anchor{33e0}
@deffnx {Données} ssl.ALERT_DESCRIPTION_INTERNAL_ERROR

@deffnx {Données} ALERT_DESCRIPTION_*

Alert Descriptions from 
@geindex RFC; RFC 5246
RFC 5246@footnote{https://datatracker.ietf.org/doc/html/rfc5246.html} and others. The IANA TLS Alert Registry@footnote{https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6}
contains this list and references to the RFCs where their meaning is defined.

Used as the return value of the callback function in
@ref{fa1,,SSLContext.set_servername_callback()}.


Ajouté dans la version 3.4.

@end deffn

@geindex AlertDescription (classe dans ssl)
@anchor{library/ssl ssl AlertDescription}@anchor{33e1}
@deffn {Classe} ssl.AlertDescription

@ref{ccd,,enum.IntEnum} collection of ALERT_DESCRIPTION_* constants.


Ajouté dans la version 3.6.

@end deffn

@geindex Purpose.SERVER_AUTH (dans le module ssl)
@anchor{library/ssl ssl Purpose SERVER_AUTH}@anchor{f9d}
@deffn {Données} Purpose.SERVER_AUTH

Option for @ref{154,,create_default_context()} and
@ref{f9c,,SSLContext.load_default_certs()}.  This value indicates that the
context may be used to authenticate web servers (therefore, it will
be used to create client-side sockets).


Ajouté dans la version 3.4.

@end deffn

@geindex Purpose.CLIENT_AUTH (dans le module ssl)
@anchor{library/ssl ssl Purpose CLIENT_AUTH}@anchor{f9e}
@deffn {Données} Purpose.CLIENT_AUTH

Option for @ref{154,,create_default_context()} and
@ref{f9c,,SSLContext.load_default_certs()}.  This value indicates that the
context may be used to authenticate web clients (therefore, it will
be used to create server-side sockets).


Ajouté dans la version 3.4.

@end deffn

@geindex SSLErrorNumber (classe dans ssl)
@anchor{library/ssl ssl SSLErrorNumber}@anchor{33e2}
@deffn {Classe} ssl.SSLErrorNumber

@ref{ccd,,enum.IntEnum} collection of SSL_ERROR_* constants.


Ajouté dans la version 3.6.

@end deffn

@geindex TLSVersion (classe dans ssl)
@anchor{library/ssl ssl TLSVersion}@anchor{33e3}
@deffn {Classe} ssl.TLSVersion

@ref{ccd,,enum.IntEnum} collection of SSL and TLS versions for
@ref{85c,,SSLContext.maximum_version} and @ref{85b,,SSLContext.minimum_version}.


Ajouté dans la version 3.7.

@end deffn

@geindex MINIMUM_SUPPORTED (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion MINIMUM_SUPPORTED}@anchor{33e4}
@deffn {Attribut} TLSVersion.MINIMUM_SUPPORTED
@end deffn

@geindex MAXIMUM_SUPPORTED (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion MAXIMUM_SUPPORTED}@anchor{33e5}
@deffn {Attribut} TLSVersion.MAXIMUM_SUPPORTED

The minimum or maximum supported SSL or TLS version. These are magic
constants. Their values don't reflect the lowest and highest available
TLS/SSL versions.
@end deffn

@geindex SSLv3 (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion SSLv3}@anchor{33e6}
@deffn {Attribut} TLSVersion.SSLv3
@end deffn

@geindex TLSv1 (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1}@anchor{33e7}
@deffn {Attribut} TLSVersion.TLSv1
@end deffn

@geindex TLSv1_1 (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1_1}@anchor{33e8}
@deffn {Attribut} TLSVersion.TLSv1_1
@end deffn

@geindex TLSv1_2 (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1_2}@anchor{33e9}
@deffn {Attribut} TLSVersion.TLSv1_2
@end deffn

@geindex TLSv1_3 (attribut ssl.TLSVersion)
@anchor{library/ssl ssl TLSVersion TLSv1_3}@anchor{33ea}
@deffn {Attribut} TLSVersion.TLSv1_3

SSL 3.0 to TLS 1.3.


Obsolète depuis la version 3.10: All @ref{33e3,,TLSVersion} members except @ref{33e9,,TLSVersion.TLSv1_2} and
@ref{33ea,,TLSVersion.TLSv1_3} are deprecated.

@end deffn

@node SSL Sockets,SSL Contexts,Fonctions constantes et exceptions,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-sockets}@anchor{33eb}
@subsubsection SSL Sockets


@geindex SSLSocket (classe dans ssl)
@anchor{library/ssl ssl SSLSocket}@anchor{8d7}
@deffn {Classe} ssl.SSLSocket (socket.socket)

SSL sockets provide the following methods of @ref{3391,,Socket Objects}:


@itemize -

@item 
@ref{d8f,,accept()}

@item 
@ref{14f0,,bind()}

@item 
@ref{d31,,close()}

@item 
@ref{d90,,connect()}

@item 
@ref{11fa,,detach()}

@item 
@ref{339f,,fileno()}

@item 
@ref{32e5,,getpeername()}, @ref{32e6,,getsockname()}

@item 
@ref{cc3,,getsockopt()}, @ref{cc4,,setsockopt()}

@item 
@ref{33a0,,gettimeout()}, @ref{335e,,settimeout()},
@ref{2ac5,,setblocking()}

@item 
@ref{e47,,listen()}

@item 
@ref{117d,,makefile()}

@item 
@ref{d91,,recv()}, @ref{12fb,,recv_into()}
(but passing a non-zero @code{flags} argument is not allowed)

@item 
@ref{d94,,send()}, @ref{d95,,sendall()} (with
the same limitation)

@item 
@ref{e46,,sendfile()} (but @ref{afd,,os.sendfile} will be used
for plain-text sockets only, else @ref{d94,,send()} will be used)

@item 
@ref{338e,,shutdown()}
@end itemize

However, since the SSL (and TLS) protocol has its own framing atop
of TCP, the SSL sockets abstraction can, in certain respects, diverge from
the specification of normal, OS-level sockets.  See especially the
@ref{33b6,,notes on non-blocking sockets}.

Instances of @ref{8d7,,SSLSocket} must be created using the
@ref{50e,,SSLContext.wrap_socket()} method.


Modifié dans la version 3.5: The @code{sendfile()} method was added.



Modifié dans la version 3.5: The @code{shutdown()} does not reset the socket timeout each time bytes
are received or sent. The socket timeout is now the maximum total duration
of the shutdown.



Obsolète depuis la version 3.6: It is deprecated to create a @ref{8d7,,SSLSocket} instance directly, use
@ref{50e,,SSLContext.wrap_socket()} to wrap a socket.



Modifié dans la version 3.7: @ref{8d7,,SSLSocket} instances must to created with
@ref{50e,,wrap_socket()}. In earlier versions, it was possible
to create instances directly. This was never documented or officially
supported.



Modifié dans la version 3.10: Python now uses @code{SSL_read_ex} and @code{SSL_write_ex} internally. The
functions support reading and writing of data larger than 2 GB. Writing
zero-length data no longer fails with a protocol violation error.

@end deffn

SSL sockets also have the following additional methods and attributes:

@geindex read() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket read}@anchor{e57}
@deffn {Méthode} SSLSocket.read (len=1024, buffer=None)

Read up to `len' bytes of data from the SSL socket and return the result as
a @code{bytes} instance. If `buffer' is specified, then read into the buffer
instead, and return the number of bytes read.

Raise @ref{e52,,SSLWantReadError} or @ref{e53,,SSLWantWriteError} if the socket is
@ref{33b6,,non-blocking} and the read would block.

As at any time a re-negotiation is possible, a call to @ref{e57,,read()} can also
cause write operations.


Modifié dans la version 3.5: The socket timeout is no longer reset each time bytes are received or sent.
The socket timeout is now the maximum total duration to read up to `len'
bytes.



Obsolète depuis la version 3.6: Use @code{recv()} instead of @ref{e57,,read()}.

@end deffn

@geindex write() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket write}@anchor{e58}
@deffn {Méthode} SSLSocket.write (buf)

Write `buf' to the SSL socket and return the number of bytes written. The
`buf' argument must be an object supporting the buffer interface.

Raise @ref{e52,,SSLWantReadError} or @ref{e53,,SSLWantWriteError} if the socket is
@ref{33b6,,non-blocking} and the write would block.

As at any time a re-negotiation is possible, a call to @ref{e58,,write()} can
also cause read operations.


Modifié dans la version 3.5: The socket timeout is no longer reset each time bytes are received or sent.
The socket timeout is now the maximum total duration to write `buf'.



Obsolète depuis la version 3.6: Use @code{send()} instead of @ref{e58,,write()}.

@end deffn

@cartouche
@quotation Note 
The @ref{e57,,read()} and @ref{e58,,write()} methods are the
low-level methods that read and write unencrypted, application-level data
and decrypt/encrypt it to encrypted, wire-level data. These methods
require an active SSL connection, i.e. the handshake was completed and
@ref{33ec,,SSLSocket.unwrap()} was not called.

Normally you should use the socket API methods like
@ref{d91,,recv()} and @ref{d94,,send()} instead of these
methods.
@end quotation
@end cartouche

@geindex do_handshake() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket do_handshake}@anchor{e56}
@deffn {Méthode} SSLSocket.do_handshake ()

Perform the SSL setup handshake.


Modifié dans la version 3.4: The handshake method also performs @code{match_hostname()} when the
@ref{33c4,,check_hostname} attribute of the socket's
@ref{33ed,,context} is true.



Modifié dans la version 3.5: The socket timeout is no longer reset each time bytes are received or sent.
The socket timeout is now the maximum total duration of the handshake.



Modifié dans la version 3.7: Hostname or IP address is matched by OpenSSL during handshake. The
function @code{match_hostname()} is no longer used. In case OpenSSL
refuses a hostname or IP address, the handshake is aborted early and
a TLS alert message is sent to the peer.

@end deffn

@geindex getpeercert() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket getpeercert}@anchor{fa2}
@deffn {Méthode} SSLSocket.getpeercert (binary_form=False)

If there is no certificate for the peer on the other end of the connection,
return @code{None}.  If the SSL handshake hasn't been done yet, raise
@ref{1ff,,ValueError}.

If the @code{binary_form} parameter is @ref{b25,,False}, and a certificate was
received from the peer, this method returns a @ref{253,,dict} instance.  If the
certificate was not validated, the dict is empty.  If the certificate was
validated, it returns a dict with several keys, amongst them @code{subject}
(the principal for which the certificate was issued) and @code{issuer}
(the principal issuing the certificate).  If a certificate contains an
instance of the `Subject Alternative Name' extension (see 
@geindex RFC; RFC 3280
RFC 3280@footnote{https://datatracker.ietf.org/doc/html/rfc3280.html}),
there will also be a @code{subjectAltName} key in the dictionary.

The @code{subject} and @code{issuer} fields are tuples containing the sequence
of relative distinguished names (RDNs) given in the certificate's data
structure for the respective fields, and each RDN is a sequence of
name-value pairs.  Here is a real-world example:

@example
@{'issuer': ((('countryName', 'IL'),),
            (('organizationName', 'StartCom Ltd.'),),
            (('organizationalUnitName',
              'Secure Digital Certificate Signing'),),
            (('commonName',
              'StartCom Class 2 Primary Intermediate Server CA'),)),
 'notAfter': 'Nov 22 08:15:19 2013 GMT',
 'notBefore': 'Nov 21 03:09:52 2011 GMT',
 'serialNumber': '95F0',
 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'California'),),
             (('localityName', 'San Francisco'),),
             (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
             (('commonName', '*.eff.org'),),
             (('emailAddress', 'hostmaster@@eff.org'),)),
 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
 'version': 3@}
@end example

If the @code{binary_form} parameter is @ref{bfb,,True}, and a certificate was
provided, this method returns the DER-encoded form of the entire certificate
as a sequence of bytes, or @ref{660,,None} if the peer did not provide a
certificate.  Whether the peer provides a certificate depends on the SSL
socket's role:


@itemize *

@item 
for a client SSL socket, the server will always provide a certificate,
regardless of whether validation was required;

@item 
for a server SSL socket, the client will only provide a certificate
when requested by the server; therefore @ref{fa2,,getpeercert()} will return
@ref{660,,None} if you used @ref{33c2,,CERT_NONE} (rather than
@ref{33c3,,CERT_OPTIONAL} or @ref{33b1,,CERT_REQUIRED}).
@end itemize

See also @ref{33c4,,SSLContext.check_hostname}.


Modifié dans la version 3.2: The returned dictionary includes additional items such as @code{issuer}
and @code{notBefore}.



Modifié dans la version 3.4: @ref{1ff,,ValueError} is raised when the handshake isn't done.
The returned dictionary includes additional X509v3 extension items
  such as @code{crlDistributionPoints}, @code{caIssuers} and @code{OCSP} URIs.



Modifié dans la version 3.9: IPv6 address strings no longer have a trailing new line.

@end deffn

@geindex get_verified_chain() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket get_verified_chain}@anchor{1564}
@deffn {Méthode} SSLSocket.get_verified_chain ()

Returns verified certificate chain provided by the other
end of the SSL channel as a list of DER-encoded bytes.
If certificate verification was disabled method acts the same as
@ref{1565,,get_unverified_chain()}.


Ajouté dans la version 3.13.

@end deffn

@geindex get_unverified_chain() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket get_unverified_chain}@anchor{1565}
@deffn {Méthode} SSLSocket.get_unverified_chain ()

Returns raw certificate chain provided by the other
end of the SSL channel as a list of DER-encoded bytes.


Ajouté dans la version 3.13.

@end deffn

@geindex cipher() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket cipher}@anchor{32e7}
@deffn {Méthode} SSLSocket.cipher ()

Returns a three-value tuple containing the name of the cipher being used, the
version of the SSL protocol that defines its use, and the number of secret
bits being used.  If no connection has been established, returns @code{None}.
@end deffn

@geindex shared_ciphers() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket shared_ciphers}@anchor{e55}
@deffn {Méthode} SSLSocket.shared_ciphers ()

Return the list of ciphers available in both the client and server.  Each
entry of the returned list is a three-value tuple containing the name of the
cipher, the version of the SSL protocol that defines its use, and the number
of secret bits the cipher uses.  @ref{e55,,shared_ciphers()} returns
@code{None} if no connection has been established or the socket is a client
socket.


Ajouté dans la version 3.5.

@end deffn

@geindex compression() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket compression}@anchor{1125}
@deffn {Méthode} SSLSocket.compression ()

Return the compression algorithm being used as a string, or @code{None}
if the connection isn't compressed.

If the higher-level protocol supports its own compression mechanism,
you can use @ref{1126,,OP_NO_COMPRESSION} to disable SSL-level compression.


Ajouté dans la version 3.3.

@end deffn

@geindex get_channel_binding() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket get_channel_binding}@anchor{1124}
@deffn {Méthode} SSLSocket.get_channel_binding (cb_type='tls-unique')

Get channel binding data for current connection, as a bytes object.  Returns
@code{None} if not connected or the handshake has not been completed.

The `cb_type' parameter allow selection of the desired channel binding
type. Valid channel binding types are listed in the
@ref{33de,,CHANNEL_BINDING_TYPES} list.  Currently only the 'tls-unique' channel
binding, defined by 
@geindex RFC; RFC 5929
RFC 5929@footnote{https://datatracker.ietf.org/doc/html/rfc5929.html}, is supported.  @ref{1ff,,ValueError} will be
raised if an unsupported channel binding type is requested.


Ajouté dans la version 3.3.

@end deffn

@geindex selected_alpn_protocol() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket selected_alpn_protocol}@anchor{e4e}
@deffn {Méthode} SSLSocket.selected_alpn_protocol ()

Return the protocol that was selected during the TLS handshake.  If
@ref{e4d,,SSLContext.set_alpn_protocols()} was not called, if the other party does
not support ALPN, if this socket does not support any of the client's
proposed protocols, or if the handshake has not happened yet, @code{None} is
returned.


Ajouté dans la version 3.5.

@end deffn

@geindex selected_npn_protocol() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket selected_npn_protocol}@anchor{85f}
@deffn {Méthode} SSLSocket.selected_npn_protocol ()

Return the higher-level protocol that was selected during the TLS/SSL
handshake. If @ref{2f6,,SSLContext.set_npn_protocols()} was not called, or
if the other party does not support NPN, or if the handshake has not yet
happened, this will return @code{None}.


Ajouté dans la version 3.3.



Obsolète depuis la version 3.10: NPN has been superseded by ALPN

@end deffn

@geindex unwrap() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket unwrap}@anchor{33ec}
@deffn {Méthode} SSLSocket.unwrap ()

Performs the SSL shutdown handshake, which removes the TLS layer from the
underlying socket, and returns the underlying socket object.  This can be
used to go from encrypted operation over a connection to unencrypted.  The
returned socket should always be used for further communication with the
other side of the connection, rather than the original socket.
@end deffn

@geindex verify_client_post_handshake() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket verify_client_post_handshake}@anchor{a20}
@deffn {Méthode} SSLSocket.verify_client_post_handshake ()

Requests post-handshake authentication (PHA) from a TLS 1.3 client. PHA
can only be initiated for a TLS 1.3 connection from a server-side socket,
after the initial TLS handshake and with PHA enabled on both sides, see
@ref{a1f,,SSLContext.post_handshake_auth}.

The method does not perform a cert exchange immediately. The server-side
sends a CertificateRequest during the next write event and expects the
client to respond with a certificate on the next read event.

If any precondition isn't met (e.g. not TLS 1.3, PHA not enabled), an
@ref{1258,,SSLError} is raised.

@cartouche
@quotation Note 
Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3
support, the method raises @ref{225,,NotImplementedError}.
@end quotation
@end cartouche


Ajouté dans la version 3.8.

@end deffn

@geindex version() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket version}@anchor{e51}
@deffn {Méthode} SSLSocket.version ()

Return the actual SSL protocol version negotiated by the connection
as a string, or @code{None} if no secure connection is established.
As of this writing, possible return values include @code{"SSLv2"},
@code{"SSLv3"}, @code{"TLSv1"}, @code{"TLSv1.1"} and @code{"TLSv1.2"}.
Recent OpenSSL versions may define more return values.


Ajouté dans la version 3.5.

@end deffn

@geindex pending() (méthode ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket pending}@anchor{33ee}
@deffn {Méthode} SSLSocket.pending ()

Returns the number of already decrypted bytes available for read, pending on
the connection.
@end deffn

@geindex context (attribut ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket context}@anchor{33ed}
@deffn {Attribut} SSLSocket.context

The @ref{291,,SSLContext} object this SSL socket is tied to.


Ajouté dans la version 3.2.

@end deffn

@geindex server_side (attribut ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket server_side}@anchor{33ef}
@deffn {Attribut} SSLSocket.server_side

A boolean which is @code{True} for server-side sockets and @code{False} for
client-side sockets.


Ajouté dans la version 3.2.

@end deffn

@geindex server_hostname (attribut ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket server_hostname}@anchor{b6d}
@deffn {Attribut} SSLSocket.server_hostname

Hostname of the server: @ref{435,,str} type, or @code{None} for server-side
socket or if the hostname was not specified in the constructor.


Ajouté dans la version 3.2.



Modifié dans la version 3.7: The attribute is now always ASCII text. When @code{server_hostname} is
an internationalized domain name (IDN), this attribute now stores the
A-label form (@code{"xn--pythn-mua.org"}), rather than the U-label form
(@code{"pythön.org"}).

@end deffn

@geindex session (attribut ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket session}@anchor{1534}
@deffn {Attribut} SSLSocket.session

The @ref{ccb,,SSLSession} for this SSL connection. The session is available
for client and server side sockets after the TLS handshake has been
performed. For client sockets the session can be set before
@ref{e56,,do_handshake()} has been called to reuse a session.


Ajouté dans la version 3.6.

@end deffn

@geindex session_reused (attribut ssl.SSLSocket)
@anchor{library/ssl ssl SSLSocket session_reused}@anchor{33f0}
@deffn {Attribut} SSLSocket.session_reused


Ajouté dans la version 3.6.

@end deffn

@node SSL Contexts,Certificates,SSL Sockets,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-contexts}@anchor{33f1}
@subsubsection SSL Contexts



Ajouté dans la version 3.2.


An SSL context holds various data longer-lived than single SSL connections,
such as SSL configuration options, certificate(s) and private key(s).
It also manages a cache of SSL sessions for server-side sockets, in order
to speed up repeated connections from the same clients.

@geindex SSLContext (classe dans ssl)
@anchor{library/ssl ssl SSLContext}@anchor{291}
@deffn {Classe} ssl.SSLContext (protocol=None)

Create a new SSL context.  You may pass `protocol' which must be one
of the @code{PROTOCOL_*} constants defined in this module.  The parameter
specifies which version of the SSL protocol to use.  Typically, the
server chooses a particular protocol version, and the client must adapt
to the server's choice.  Most of the versions are not interoperable
with the other versions.  If not specified, the default is
@ref{33b3,,PROTOCOL_TLS}; it provides the most compatibility with other
versions.

Here's a table showing which versions in a client (down the side) can connect
to which versions in a server (along the top):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxxxxx} 
@item

`client' / `server'

@tab

`SSLv2'

@tab

`SSLv3'

@tab

`TLS' @footnote{
TLS 1.3 protocol will be available with @ref{33b3,,PROTOCOL_TLS} in
OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
TLS 1.3.
}

@tab

`TLSv1'

@tab

`TLSv1.1'

@tab

`TLSv1.2'

@item

`SSLv2'

@tab

oui

@tab

non

@tab

no @footnote{
@ref{291,,SSLContext} disables SSLv2 with @ref{823,,OP_NO_SSLv2} by default.
}

@tab

non

@tab

non

@tab

non

@item

`SSLv3'

@tab

non

@tab

oui

@tab

no @footnote{
@ref{291,,SSLContext} disables SSLv3 with @ref{824,,OP_NO_SSLv3} by default.
}

@tab

non

@tab

non

@tab

non

@item

`TLS' (`SSLv23') @footnote{
TLS 1.3 protocol will be available with @ref{33b3,,PROTOCOL_TLS} in
OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
TLS 1.3.
}

@tab

no @footnote{
@ref{291,,SSLContext} disables SSLv2 with @ref{823,,OP_NO_SSLv2} by default.
}

@tab

no @footnote{
@ref{291,,SSLContext} disables SSLv3 with @ref{824,,OP_NO_SSLv3} by default.
}

@tab

oui

@tab

oui

@tab

oui

@tab

oui

@item

`TLSv1'

@tab

non

@tab

non

@tab

oui

@tab

oui

@tab

non

@tab

non

@item

`TLSv1.1'

@tab

non

@tab

non

@tab

oui

@tab

non

@tab

oui

@tab

non

@item

`TLSv1.2'

@tab

non

@tab

non

@tab

oui

@tab

non

@tab

non

@tab

oui

@end multitable


@subsubheading Notes



@subsubheading Voir aussi


@ref{154,,create_default_context()} lets the @ref{cf,,ssl} module choose
security settings for a given purpose.



Modifié dans la version 3.6: The context is created with secure default values. The options
@ref{1126,,OP_NO_COMPRESSION}, @ref{1129,,OP_CIPHER_SERVER_PREFERENCE},
@ref{33cf,,OP_SINGLE_DH_USE}, @ref{33d0,,OP_SINGLE_ECDH_USE},
@ref{823,,OP_NO_SSLv2},
and @ref{824,,OP_NO_SSLv3} (except for @ref{33be,,PROTOCOL_SSLv3}) are
set by default. The initial cipher suite list contains only @code{HIGH}
ciphers, no @code{NULL} ciphers and no @code{MD5} ciphers.



Obsolète depuis la version 3.10: @ref{291,,SSLContext} without protocol argument is deprecated. The
context class will either require @ref{85d,,PROTOCOL_TLS_CLIENT} or
@ref{85e,,PROTOCOL_TLS_SERVER} protocol in the future.



Modifié dans la version 3.10: The default cipher suites now include only secure AES and ChaCha20
ciphers with forward secrecy and security level 2. RSA and DH keys with
less than 2048 bits and ECC keys with less than 224 bits are prohibited.
@ref{33b3,,PROTOCOL_TLS}, @ref{85d,,PROTOCOL_TLS_CLIENT}, and
@ref{85e,,PROTOCOL_TLS_SERVER} use TLS 1.2 as minimum TLS version.


@cartouche
@quotation Note 
@ref{291,,SSLContext} only supports limited mutation once it has been used
by a connection. Adding new certificates to the internal trust store is
allowed, but changing ciphers, verification settings, or mTLS
certificates may result in surprising behavior.
@end quotation
@end cartouche

@cartouche
@quotation Note 
@ref{291,,SSLContext} is designed to be shared and used by multiple
connections.
Thus, it is thread-safe as long as it is not reconfigured after being
used by a connection.
@end quotation
@end cartouche
@end deffn

@ref{291,,SSLContext} objects have the following methods and attributes:

@geindex cert_store_stats() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext cert_store_stats}@anchor{f96}
@deffn {Méthode} SSLContext.cert_store_stats ()

Get statistics about quantities of loaded X.509 certificates, count of
X.509 certificates flagged as CA certificates and certificate revocation
lists as dictionary.

Example for a context with one CA cert and one other cert:

@example
>>> context.cert_store_stats()
@{'crl': 0, 'x509_ca': 1, 'x509': 2@}
@end example


Ajouté dans la version 3.4.

@end deffn

@geindex load_cert_chain() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_cert_chain}@anchor{292}
@deffn {Méthode} SSLContext.load_cert_chain (certfile, keyfile=None, password=None)

Load a private key and the corresponding certificate.  The `certfile'
string must be the path to a single file in PEM format containing the
certificate as well as any number of CA certificates needed to establish
the certificate's authenticity.  The `keyfile' string, if present, must
point to a file containing the private key.  Otherwise the private
key will be taken from `certfile' as well.  See the discussion of
@ref{33f2,,Certificates} for more information on how the certificate
is stored in the `certfile'.

The `password' argument may be a function to call to get the password for
decrypting the private key.  It will only be called if the private key is
encrypted and a password is necessary.  It will be called with no arguments,
and it should return a string, bytes, or bytearray.  If the return value is
a string it will be encoded as UTF-8 before using it to decrypt the key.
Alternatively a string, bytes, or bytearray value may be supplied directly
as the `password' argument.  It will be ignored if the private key is not
encrypted and no password is needed.

If the `password' argument is not specified and a password is required,
OpenSSL's built-in password prompting mechanism will be used to
interactively prompt the user for a password.

An @ref{1258,,SSLError} is raised if the private key doesn't
match with the certificate.


Modifié dans la version 3.3: New optional argument `password'.

@end deffn

@geindex load_default_certs() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_default_certs}@anchor{f9c}
@deffn {Méthode} SSLContext.load_default_certs (purpose=Purpose.SERVER_AUTH)

Load a set of default "certification authority" (CA) certificates from
default locations. On Windows it loads CA certs from the @code{CA} and
@code{ROOT} system stores. On all systems it calls
@ref{f95,,SSLContext.set_default_verify_paths()}. In the future the method may
load CA certificates from other locations, too.

The `purpose' flag specifies what kind of CA certificates are loaded. The
default settings @ref{f9d,,Purpose.SERVER_AUTH} loads certificates, that are
flagged and trusted for TLS web server authentication (client side
sockets). @ref{f9e,,Purpose.CLIENT_AUTH} loads CA certificates for client
certificate verification on the server side.


Ajouté dans la version 3.4.

@end deffn

@geindex load_verify_locations() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_verify_locations}@anchor{ed6}
@deffn {Méthode} SSLContext.load_verify_locations (cafile=None, capath=None, cadata=None)

Load a set of "certification authority" (CA) certificates used to validate
other peers' certificates when @ref{33b0,,verify_mode} is other than
@ref{33c2,,CERT_NONE}.  At least one of `cafile' or `capath' must be specified.

This method can also load certification revocation lists (CRLs) in PEM or
DER format. In order to make use of CRLs, @ref{f98,,SSLContext.verify_flags}
must be configured properly.

The `cafile' string, if present, is the path to a file of concatenated
CA certificates in PEM format. See the discussion of
@ref{33f2,,Certificates} for more information about how to arrange the
certificates in this file.

The `capath' string, if present, is
the path to a directory containing several CA certificates in PEM format,
following an OpenSSL specific layout@footnote{https://docs.openssl.org/master/man3/SSL_CTX_load_verify_locations/}.

The `cadata' object, if present, is either an ASCII string of one or more
PEM-encoded certificates or a @ref{d1b,,bytes-like object} of DER-encoded
certificates. Like with `capath' extra lines around PEM-encoded
certificates are ignored but at least one certificate must be present.


Modifié dans la version 3.4: New optional argument `cadata'

@end deffn

@geindex get_ca_certs() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext get_ca_certs}@anchor{f97}
@deffn {Méthode} SSLContext.get_ca_certs (binary_form=False)

Get a list of loaded "certification authority" (CA) certificates. If the
@code{binary_form} parameter is @ref{b25,,False} each list
entry is a dict like the output of @ref{fa2,,SSLSocket.getpeercert()}. Otherwise
the method returns a list of DER-encoded certificates. The returned list
does not contain certificates from `capath' unless a certificate was
requested and loaded by a SSL connection.

@cartouche
@quotation Note 
Certificates in a capath directory aren't loaded unless they have
been used at least once.
@end quotation
@end cartouche


Ajouté dans la version 3.4.

@end deffn

@geindex get_ciphers() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext get_ciphers}@anchor{ccc}
@deffn {Méthode} SSLContext.get_ciphers ()

Get a list of enabled ciphers. The list is in order of cipher priority.
See @ref{33f3,,SSLContext.set_ciphers()}.

Exemple :

@example
>>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()
[@{'aead': True,
  'alg_bits': 256,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'digest': None,
  'id': 50380848,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'@},
 @{'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'@}]
@end example


Ajouté dans la version 3.6.

@end deffn

@geindex set_default_verify_paths() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_default_verify_paths}@anchor{f95}
@deffn {Méthode} SSLContext.set_default_verify_paths ()

Load a set of default "certification authority" (CA) certificates from
a filesystem path defined when building the OpenSSL library.  Unfortunately,
there's no easy way to know whether this method succeeds: no error is
returned if no certificates are to be found.  When the OpenSSL library is
provided as part of the operating system, though, it is likely to be
configured properly.
@end deffn

@geindex set_ciphers() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_ciphers}@anchor{33f3}
@deffn {Méthode} SSLContext.set_ciphers (ciphers)

Set the available ciphers for sockets created with this context.
It should be a string in the OpenSSL cipher list format@footnote{https://docs.openssl.org/master/man1/ciphers/}.
If no cipher can be selected (because compile-time options or other
configuration forbids use of all the specified ciphers), an
@ref{1258,,SSLError} will be raised.

@cartouche
@quotation Note 
when connected, the @ref{32e7,,SSLSocket.cipher()} method of SSL sockets will
give the currently selected cipher.

TLS 1.3 cipher suites cannot be disabled with
@ref{33f3,,set_ciphers()}.
@end quotation
@end cartouche
@end deffn

@geindex set_alpn_protocols() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_alpn_protocols}@anchor{e4d}
@deffn {Méthode} SSLContext.set_alpn_protocols (protocols)

Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of ASCII strings, like @code{['http/1.1',
'spdy/2']}, ordered by preference. The selection of a protocol will happen
during the handshake, and will play out according to 
@geindex RFC; RFC 7301
RFC 7301@footnote{https://datatracker.ietf.org/doc/html/rfc7301.html}. After a
successful handshake, the @ref{e4e,,SSLSocket.selected_alpn_protocol()} method will
return the agreed-upon protocol.

This method will raise @ref{225,,NotImplementedError} if @ref{e4f,,HAS_ALPN} is
@code{False}.


Ajouté dans la version 3.5.

@end deffn

@geindex set_npn_protocols() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_npn_protocols}@anchor{2f6}
@deffn {Méthode} SSLContext.set_npn_protocols (protocols)

Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of strings, like @code{['http/1.1', 'spdy/2']},
ordered by preference. The selection of a protocol will happen during the
handshake, and will play out according to the Application Layer Protocol Negotiation@footnote{https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation}. After a
successful handshake, the @ref{85f,,SSLSocket.selected_npn_protocol()} method will
return the agreed-upon protocol.

This method will raise @ref{225,,NotImplementedError} if @ref{33d7,,HAS_NPN} is
@code{False}.


Ajouté dans la version 3.3.



Obsolète depuis la version 3.10: NPN has been superseded by ALPN

@end deffn

@geindex sni_callback (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext sni_callback}@anchor{1863}
@deffn {Attribut} SSLContext.sni_callback

Register a callback function that will be called after the TLS Client Hello
handshake message has been received by the SSL/TLS server when the TLS client
specifies a server name indication. The server name indication mechanism
is specified in 
@geindex RFC; RFC 6066
RFC 6066@footnote{https://datatracker.ietf.org/doc/html/rfc6066.html} section 3 - Server Name Indication.

Only one callback can be set per @code{SSLContext}.  If `sni_callback'
is set to @code{None} then the callback is disabled. Calling this function a
subsequent time will disable the previously registered callback.

The callback function will be called with three
arguments; the first being the @ref{8d7,,ssl.SSLSocket}, the second is a string
that represents the server name that the client is intending to communicate
(or @ref{660,,None} if the TLS Client Hello does not contain a server name)
and the third argument is the original @ref{291,,SSLContext}. The server name
argument is text. For internationalized domain name, the server
name is an IDN A-label (@code{"xn--pythn-mua.org"}).

A typical use of this callback is to change the @ref{8d7,,ssl.SSLSocket}'s
@ref{33ed,,SSLSocket.context} attribute to a new object of type
@ref{291,,SSLContext} representing a certificate chain that matches the server
name.

Due to the early negotiation phase of the TLS connection, only limited
methods and attributes are usable like
@ref{e4e,,SSLSocket.selected_alpn_protocol()} and @ref{33ed,,SSLSocket.context}.
The @ref{fa2,,SSLSocket.getpeercert()}, @ref{1564,,SSLSocket.get_verified_chain()},
@ref{1565,,SSLSocket.get_unverified_chain()} @ref{32e7,,SSLSocket.cipher()}
and @ref{1125,,SSLSocket.compression()} methods require that
the TLS connection has progressed beyond the TLS Client Hello and therefore
will not return meaningful values nor can they be called safely.

The `sni_callback' function must return @code{None} to allow the
TLS negotiation to continue.  If a TLS failure is required, a constant
@ref{33e0,,ALERT_DESCRIPTION_*} can be
returned.  Other return values will result in a TLS fatal error with
@ref{33e0,,ALERT_DESCRIPTION_INTERNAL_ERROR}.

If an exception is raised from the `sni_callback' function the TLS
connection will terminate with a fatal TLS alert message
@ref{33df,,ALERT_DESCRIPTION_HANDSHAKE_FAILURE}.

This method will raise @ref{225,,NotImplementedError} if the OpenSSL library
had OPENSSL_NO_TLSEXT defined when it was built.


Ajouté dans la version 3.7.

@end deffn

@geindex set_servername_callback (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_servername_callback}@anchor{fa1}
@deffn {Attribut} SSLContext.set_servername_callback (server_name_callback)

This is a legacy API retained for backwards compatibility. When possible,
you should use @ref{1863,,sni_callback} instead. The given `server_name_callback'
is similar to `sni_callback', except that when the server hostname is an
IDN-encoded internationalized domain name, the `server_name_callback'
receives a decoded U-label (@code{"pythön.org"}).

If there is a decoding error on the server name, the TLS connection will
terminate with an @ref{33e0,,ALERT_DESCRIPTION_INTERNAL_ERROR} fatal TLS
alert message to the client.


Ajouté dans la version 3.4.

@end deffn

@geindex load_dh_params() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext load_dh_params}@anchor{1122}
@deffn {Méthode} SSLContext.load_dh_params (dhfile)

Load the key generation parameters for Diffie-Hellman (DH) key exchange.
Using DH key exchange improves forward secrecy at the expense of
computational resources (both on the server and on the client).
The `dhfile' parameter should be the path to a file containing DH
parameters in PEM format.

This setting doesn't apply to client sockets.  You can also use the
@ref{33cf,,OP_SINGLE_DH_USE} option to further improve security.


Ajouté dans la version 3.3.

@end deffn

@geindex set_ecdh_curve() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_ecdh_curve}@anchor{1123}
@deffn {Méthode} SSLContext.set_ecdh_curve (curve_name)

Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
exchange.  ECDH is significantly faster than regular DH while arguably
as secure.  The `curve_name' parameter should be a string describing
a well-known elliptic curve, for example @code{prime256v1} for a widely
supported curve.

This setting doesn't apply to client sockets.  You can also use the
@ref{33d0,,OP_SINGLE_ECDH_USE} option to further improve security.

This method is not available if @ref{33d5,,HAS_ECDH} is @code{False}.


Ajouté dans la version 3.3.



@subsubheading Voir aussi



@table @asis

@item SSL/TLS & Perfect Forward Secrecy@footnote{https://vincent.bernat.ch/en/blog/2011-ssl-perfect-forward-secrecy}

Vincent Bernat.
@end table

@end deffn

@geindex wrap_socket() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext wrap_socket}@anchor{50e}
@deffn {Méthode} SSLContext.wrap_socket (sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)

Wrap an existing Python socket `sock' and return an instance of
@ref{33f4,,SSLContext.sslsocket_class} (default @ref{8d7,,SSLSocket}). The
returned SSL socket is tied to the context, its settings and certificates.
`sock' must be a @ref{12d1,,SOCK_STREAM} socket; other
socket types are unsupported.

The parameter @code{server_side} is a boolean which identifies whether
server-side or client-side behavior is desired from this socket.

For client-side sockets, the context construction is lazy; if the
underlying socket isn't connected yet, the context construction will be
performed after @code{connect()} is called on the socket.  For
server-side sockets, if the socket has no remote peer, it is assumed
to be a listening socket, and the server-side SSL wrapping is
automatically performed on client connections accepted via the
@code{accept()} method. The method may raise @ref{1258,,SSLError}.

On client connections, the optional parameter `server_hostname' specifies
the hostname of the service which we are connecting to.  This allows a
single server to host multiple SSL-based services with distinct certificates,
quite similarly to HTTP virtual hosts. Specifying `server_hostname' will
raise a @ref{1ff,,ValueError} if `server_side' is true.

The parameter @code{do_handshake_on_connect} specifies whether to do the SSL
handshake automatically after doing a @code{socket.connect()}, or whether the
application program will call it explicitly, by invoking the
@ref{e56,,SSLSocket.do_handshake()} method.  Calling
@ref{e56,,SSLSocket.do_handshake()} explicitly gives the program control over the
blocking behavior of the socket I/O involved in the handshake.

The parameter @code{suppress_ragged_eofs} specifies how the
@code{SSLSocket.recv()} method should signal unexpected EOF from the other end
of the connection.  If specified as @ref{bfb,,True} (the default), it returns a
normal EOF (an empty bytes object) in response to unexpected EOF errors
raised from the underlying socket; if @ref{b25,,False}, it will raise the
exceptions back to the caller.

`session', see @ref{1534,,session}.

To wrap an @ref{8d7,,SSLSocket} in another @ref{8d7,,SSLSocket}, use
@ref{b70,,SSLContext.wrap_bio()}.


Modifié dans la version 3.5: Always allow a server_hostname to be passed, even if OpenSSL does not
have SNI.



Modifié dans la version 3.6: `session' argument was added.



Modifié dans la version 3.7: The method returns an instance of @ref{33f4,,SSLContext.sslsocket_class}
instead of hard-coded @ref{8d7,,SSLSocket}.

@end deffn

@geindex sslsocket_class (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext sslsocket_class}@anchor{33f4}
@deffn {Attribut} SSLContext.sslsocket_class

The return type of @ref{50e,,SSLContext.wrap_socket()}, defaults to
@ref{8d7,,SSLSocket}. The attribute can be overridden on instance of class
in order to return a custom subclass of @ref{8d7,,SSLSocket}.


Ajouté dans la version 3.7.

@end deffn

@geindex wrap_bio() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext wrap_bio}@anchor{b70}
@deffn {Méthode} SSLContext.wrap_bio (incoming, outgoing, server_side=False, server_hostname=None, session=None)

Wrap the BIO objects `incoming' and `outgoing' and return an instance of
@ref{33f5,,SSLContext.sslobject_class} (default @ref{b6f,,SSLObject}). The SSL
routines will read input data from the incoming BIO and write data to the
outgoing BIO.

The `server_side', `server_hostname' and `session' parameters have the
same meaning as in @ref{50e,,SSLContext.wrap_socket()}.


Modifié dans la version 3.6: `session' argument was added.



Modifié dans la version 3.7: The method returns an instance of @ref{33f5,,SSLContext.sslobject_class}
instead of hard-coded @ref{b6f,,SSLObject}.

@end deffn

@geindex sslobject_class (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext sslobject_class}@anchor{33f5}
@deffn {Attribut} SSLContext.sslobject_class

The return type of @ref{b70,,SSLContext.wrap_bio()}, defaults to
@ref{b6f,,SSLObject}. The attribute can be overridden on instance of class
in order to return a custom subclass of @ref{b6f,,SSLObject}.


Ajouté dans la version 3.7.

@end deffn

@geindex session_stats() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext session_stats}@anchor{33f6}
@deffn {Méthode} SSLContext.session_stats ()

Get statistics about the SSL sessions created or managed by this context.
A dictionary is returned which maps the names of each piece of information@footnote{https://docs.openssl.org/1.1.1/man3/SSL_CTX_sess_number/} to their
numeric values.  For example, here is the total number of hits and misses
in the session cache since the context was created:

@example
>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)
@end example
@end deffn

@geindex check_hostname (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext check_hostname}@anchor{33c4}
@deffn {Attribut} SSLContext.check_hostname

Whether to match the peer cert's hostname in
@ref{e56,,SSLSocket.do_handshake()}. The context's
@ref{33b0,,verify_mode} must be set to @ref{33c3,,CERT_OPTIONAL} or
@ref{33b1,,CERT_REQUIRED}, and you must pass `server_hostname' to
@ref{50e,,wrap_socket()} in order to match the hostname.  Enabling
hostname checking automatically sets @ref{33b0,,verify_mode} from
@ref{33c2,,CERT_NONE} to @ref{33b1,,CERT_REQUIRED}.  It cannot be set back to
@ref{33c2,,CERT_NONE} as long as hostname checking is enabled. The
@ref{85d,,PROTOCOL_TLS_CLIENT} protocol enables hostname checking by default.
With other protocols, hostname checking must be enabled explicitly.

Exemple :

@example
import socket, ssl

context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))
@end example


Ajouté dans la version 3.4.



Modifié dans la version 3.7: @ref{33b0,,verify_mode} is now automatically changed
to @ref{33b1,,CERT_REQUIRED}  when hostname checking is enabled and
@ref{33b0,,verify_mode} is @ref{33c2,,CERT_NONE}. Previously
the same operation would have failed with a @ref{1ff,,ValueError}.

@end deffn

@geindex keylog_filename (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext keylog_filename}@anchor{33b2}
@deffn {Attribut} SSLContext.keylog_filename

Write TLS keys to a keylog file, whenever key material is generated or
received. The keylog file is designed for debugging purposes only. The
file format is specified by NSS and used by many traffic analyzers such
as Wireshark. The log file is opened in append-only mode. Writes are
synchronized between threads, but not between processes.


Ajouté dans la version 3.8.

@end deffn

@geindex maximum_version (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext maximum_version}@anchor{85c}
@deffn {Attribut} SSLContext.maximum_version

A @ref{33e3,,TLSVersion} enum member representing the highest supported
TLS version. The value defaults to @ref{33e5,,TLSVersion.MAXIMUM_SUPPORTED}.
The attribute is read-only for protocols other than @ref{33b3,,PROTOCOL_TLS},
@ref{85d,,PROTOCOL_TLS_CLIENT}, and @ref{85e,,PROTOCOL_TLS_SERVER}.

The attributes @ref{85c,,maximum_version},
@ref{85b,,minimum_version} and
@ref{822,,SSLContext.options} all affect the supported SSL
and TLS versions of the context. The implementation does not prevent
invalid combination. For example a context with
@ref{33cd,,OP_NO_TLSv1_2} in @ref{822,,options} and
@ref{85c,,maximum_version} set to @ref{33e9,,TLSVersion.TLSv1_2}
will not be able to establish a TLS 1.2 connection.


Ajouté dans la version 3.7.

@end deffn

@geindex minimum_version (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext minimum_version}@anchor{85b}
@deffn {Attribut} SSLContext.minimum_version

Like @ref{85c,,SSLContext.maximum_version} except it is the lowest
supported version or @ref{33e4,,TLSVersion.MINIMUM_SUPPORTED}.


Ajouté dans la version 3.7.

@end deffn

@geindex num_tickets (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext num_tickets}@anchor{33f7}
@deffn {Attribut} SSLContext.num_tickets

Control the number of TLS 1.3 session tickets of a
@ref{85e,,PROTOCOL_TLS_SERVER} context. The setting has no impact on TLS
1.0 to 1.2 connections.


Ajouté dans la version 3.8.

@end deffn

@geindex options (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext options}@anchor{822}
@deffn {Attribut} SSLContext.options

An integer representing the set of SSL options enabled on this context.
The default value is @ref{33ca,,OP_ALL}, but you can specify other options
such as @ref{823,,OP_NO_SSLv2} by ORing them together.


Modifié dans la version 3.6: @ref{822,,SSLContext.options} returns @ref{33d2,,Options} flags:

@example
>>> ssl.create_default_context().options  
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
@end example



Obsolète depuis la version 3.7: All @code{OP_NO_SSL*} and @code{OP_NO_TLS*} options have been deprecated since
Python 3.7. Use @ref{85b,,SSLContext.minimum_version} and
@ref{85c,,SSLContext.maximum_version} instead.

@end deffn

@geindex post_handshake_auth (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext post_handshake_auth}@anchor{a1f}
@deffn {Attribut} SSLContext.post_handshake_auth

Enable TLS 1.3 post-handshake client authentication. Post-handshake auth
is disabled by default and a server can only request a TLS client
certificate during the initial handshake. When enabled, a server may
request a TLS client certificate at any time after the handshake.

When enabled on client-side sockets, the client signals the server that
it supports post-handshake authentication.

When enabled on server-side sockets, @ref{33b0,,SSLContext.verify_mode} must
be set to @ref{33c3,,CERT_OPTIONAL} or @ref{33b1,,CERT_REQUIRED}, too. The
actual client cert exchange is delayed until
@ref{a20,,SSLSocket.verify_client_post_handshake()} is called and some I/O is
performed.


Ajouté dans la version 3.8.

@end deffn

@geindex protocol (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext protocol}@anchor{33f8}
@deffn {Attribut} SSLContext.protocol

The protocol version chosen when constructing the context.  This attribute
is read-only.
@end deffn

@geindex hostname_checks_common_name (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext hostname_checks_common_name}@anchor{b6b}
@deffn {Attribut} SSLContext.hostname_checks_common_name

Whether @ref{33c4,,check_hostname} falls back to verify the cert's
subject common name in the absence of a subject alternative name
extension (default: true).


Ajouté dans la version 3.7.



Modifié dans la version 3.10: The flag had no effect with OpenSSL before version 1.1.1l. Python 3.8.9,
3.9.3, and 3.10 include workarounds for previous versions.

@end deffn

@geindex security_level (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext security_level}@anchor{33f9}
@deffn {Attribut} SSLContext.security_level

An integer representing the security level@footnote{https://docs.openssl.org/master/man3/SSL_CTX_get_security_level/}
for the context. This attribute is read-only.


Ajouté dans la version 3.10.

@end deffn

@geindex verify_flags (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext verify_flags}@anchor{f98}
@deffn {Attribut} SSLContext.verify_flags

The flags for certificate verification operations. You can set flags like
@ref{f9a,,VERIFY_CRL_CHECK_LEAF} by ORing them together. By default OpenSSL
does neither require nor verify certificate revocation lists (CRLs).


Ajouté dans la version 3.4.



Modifié dans la version 3.6: @ref{f98,,SSLContext.verify_flags} returns @ref{33c7,,VerifyFlags} flags:

@example
>>> ssl.create_default_context().verify_flags  
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>
@end example

@end deffn

@geindex verify_mode (attribut ssl.SSLContext)
@anchor{library/ssl ssl SSLContext verify_mode}@anchor{33b0}
@deffn {Attribut} SSLContext.verify_mode

Whether to try to verify other peers' certificates and how to behave
if verification fails.  This attribute must be one of
@ref{33c2,,CERT_NONE}, @ref{33c3,,CERT_OPTIONAL} or @ref{33b1,,CERT_REQUIRED}.


Modifié dans la version 3.6: @ref{33b0,,SSLContext.verify_mode} returns @ref{33c5,,VerifyMode} enum:

@example
>>> ssl.create_default_context().verify_mode  
<VerifyMode.CERT_REQUIRED: 2>
@end example

@end deffn

@geindex set_psk_client_callback() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_psk_client_callback}@anchor{33fa}
@deffn {Méthode} SSLContext.set_psk_client_callback (callback)

Enables TLS-PSK (pre-shared key) authentication on a client-side connection.

In general, certificate based authentication should be preferred over this method.

The parameter @code{callback} is a callable object with the signature:
@code{def callback(hint: str | None) -> tuple[str | None, bytes]}.
The @code{hint} parameter is an optional identity hint sent by the server.
The return value is a tuple in the form (client-identity, psk).
Client-identity is an optional string which may be used by the server to
select a corresponding PSK for the client. The string must be less than or
equal to @code{256} octets when UTF-8 encoded. PSK is a
@ref{d1b,,bytes-like object} representing the pre-shared key. Return a zero
length PSK to reject the connection.

Setting @code{callback} to @ref{660,,None} removes any existing callback.

@cartouche
@quotation Note 
When using TLS 1.3:


@itemize -

@item 
the @code{hint} parameter is always @ref{660,,None}.

@item 
client-identity must be a non-empty string.
@end itemize
@end quotation
@end cartouche

Example usage:

@example
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_client_callback(lambda hint: (None, psk))

# A table using the hint from the server:
psk_table = @{ 'ServerId_1': bytes.fromhex('c0ffee'),
              'ServerId_2': bytes.fromhex('facade')
@}
def callback(hint):
    return 'ClientId_1', psk_table.get(hint, b'@w{'})
context.set_psk_client_callback(callback)
@end example

This method will raise @ref{225,,NotImplementedError} if @ref{33dd,,HAS_PSK} is
@code{False}.


Ajouté dans la version 3.13.

@end deffn

@geindex set_psk_server_callback() (méthode ssl.SSLContext)
@anchor{library/ssl ssl SSLContext set_psk_server_callback}@anchor{33fb}
@deffn {Méthode} SSLContext.set_psk_server_callback (callback, identity_hint=None)

Enables TLS-PSK (pre-shared key) authentication on a server-side connection.

In general, certificate based authentication should be preferred over this method.

The parameter @code{callback} is a callable object with the signature:
@code{def callback(identity: str | None) -> bytes}.
The @code{identity} parameter is an optional identity sent by the client which can
be used to select a corresponding PSK.
The return value is a @ref{d1b,,bytes-like object} representing the pre-shared key.
Return a zero length PSK to reject the connection.

Setting @code{callback} to @ref{660,,None} removes any existing callback.

The parameter @code{identity_hint} is an optional identity hint string sent to
the client. The string must be less than or equal to @code{256} octets when
UTF-8 encoded.

@cartouche
@quotation Note 
When using TLS 1.3 the @code{identity_hint} parameter is not sent to the client.
@end quotation
@end cartouche

Example usage:

@example
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.maximum_version = ssl.TLSVersion.TLSv1_2
context.set_ciphers('PSK')

# A simple lambda:
psk = bytes.fromhex('c0ffee')
context.set_psk_server_callback(lambda identity: psk)

# A table using the identity of the client:
psk_table = @{ 'ClientId_1': bytes.fromhex('c0ffee'),
              'ClientId_2': bytes.fromhex('facade')
@}
def callback(identity):
    return psk_table.get(identity, b'@w{'})
context.set_psk_server_callback(callback, 'ServerId_1')
@end example

This method will raise @ref{225,,NotImplementedError} if @ref{33dd,,HAS_PSK} is
@code{False}.


Ajouté dans la version 3.13.

@end deffn

@geindex certificates

@geindex X509 certificate

@node Certificates,Exemples<20>,SSL Contexts,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl certificates}@anchor{33fc}@anchor{library/ssl ssl-certificates}@anchor{33f2}
@subsubsection Certificates


Certificates in general are part of a public-key / private-key system.  In this
system, each `principal', (which may be a machine, or a person, or an
organization) is assigned a unique two-part encryption key.  One part of the key
is public, and is called the `public key'; the other part is kept secret, and is
called the `private key'.  The two parts are related, in that if you encrypt a
message with one of the parts, you can decrypt it with the other part, and
`only' with the other part.

A certificate contains information about two principals.  It contains the name
of a `subject', and the subject's public key.  It also contains a statement by a
second principal, the `issuer', that the subject is who they claim to be, and
that this is indeed the subject's public key.  The issuer's statement is signed
with the issuer's private key, which only the issuer knows.  However, anyone can
verify the issuer's statement by finding the issuer's public key, decrypting the
statement with it, and comparing it to the other information in the certificate.
The certificate also contains information about the time period over which it is
valid.  This is expressed as two fields, called "notBefore" and "notAfter".

In the Python use of certificates, a client or server can use a certificate to
prove who they are.  The other side of a network connection can also be required
to produce a certificate, and that certificate can be validated to the
satisfaction of the client or server that requires such validation.  The
connection attempt can be set to raise an exception if the validation fails.
Validation is done automatically, by the underlying OpenSSL framework; the
application need not concern itself with its mechanics.  But the application
does usually need to provide sets of certificates to allow this process to take
place.

Python uses files to contain certificates.  They should be formatted as "PEM"
(see 
@geindex RFC; RFC 1422
RFC 1422@footnote{https://datatracker.ietf.org/doc/html/rfc1422.html}), which is a base-64 encoded form wrapped with a header line
and a footer line:

@example
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----
@end example

@menu
* Certificate chains:: 
* CA certificates:: 
* Combined key and certificate:: 
* Self-signed certificates:: 

@end menu

@node Certificate chains,CA certificates,,Certificates
@anchor{library/ssl certificate-chains}@anchor{33fd}
@subsubsection Certificate chains


The Python files which contain certificates can contain a sequence of
certificates, sometimes called a `certificate chain'.  This chain should start
with the specific certificate for the principal who "is" the client or server,
and then the certificate for the issuer of that certificate, and then the
certificate for the issuer of `that' certificate, and so on up the chain till
you get to a certificate which is `self-signed', that is, a certificate which
has the same subject and issuer, sometimes called a `root certificate'.  The
certificates should just be concatenated together in the certificate file.  For
example, suppose we had a three certificate chain, from our server certificate
to the certificate of the certification authority that signed our server
certificate, to the root certificate of the agency which issued the
certification authority's certificate:

@example
-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----
@end example

@node CA certificates,Combined key and certificate,Certificate chains,Certificates
@anchor{library/ssl ca-certificates}@anchor{33fe}
@subsubsection CA certificates


If you are going to require validation of the other side of the connection's
certificate, you need to provide a "CA certs" file, filled with the certificate
chains for each issuer you are willing to trust.  Again, this file just contains
these chains concatenated together.  For validation, Python will use the first
chain it finds in the file which matches.  The platform's certificates file can
be used by calling @ref{f9c,,SSLContext.load_default_certs()}, this is done
automatically with @ref{154,,create_default_context()}.

@node Combined key and certificate,Self-signed certificates,CA certificates,Certificates
@anchor{library/ssl combined-key-and-certificate}@anchor{33ff}
@subsubsection Combined key and certificate


Often the private key is stored in the same file as the certificate; in this
case, only the @code{certfile} parameter to @ref{292,,SSLContext.load_cert_chain()}
needs to be passed.  If the private key is stored
with the certificate, it should come before the first certificate in
the certificate chain:

@example
-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----
@end example

@node Self-signed certificates,,Combined key and certificate,Certificates
@anchor{library/ssl self-signed-certificates}@anchor{3400}
@subsubsection Self-signed certificates


If you are going to create a server that provides SSL-encrypted connection
services, you will need to acquire a certificate for that service.  There are
many ways of acquiring appropriate certificates, such as buying one from a
certification authority.  Another common practice is to generate a self-signed
certificate.  The simplest way to do this is with the OpenSSL package, using
something like the following:

@example
% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@@myserver.mygroup.myorganization.com
%
@end example

The disadvantage of a self-signed certificate is that it is its own root
certificate, and no one else will have it in their cache of known (and trusted)
root certificates.

@node Exemples<20>,Notes on non-blocking sockets,Certificates,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl examples}@anchor{3401}
@subsubsection Exemples


@menu
* Testing for SSL support:: 
* Client-side operation:: 
* Server-side operation:: 

@end menu

@node Testing for SSL support,Client-side operation,,Exemples<20>
@anchor{library/ssl testing-for-ssl-support}@anchor{3402}
@subsubsection Testing for SSL support


To test for the presence of SSL support in a Python installation, user code
should use the following idiom:

@example
try:
    import ssl
except ImportError:
    pass
else:
    ...  # do something that requires SSL support
@end example

@node Client-side operation,Server-side operation,Testing for SSL support,Exemples<20>
@anchor{library/ssl client-side-operation}@anchor{3403}
@subsubsection Client-side operation


This example creates a SSL context with the recommended security settings
for client sockets, including automatic certificate verification:

@example
>>> context = ssl.create_default_context()
@end example

If you prefer to tune security settings yourself, you might create
a context from scratch (but beware that you might not get the settings
right):

@example
>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
@end example

(this snippet assumes your operating system places a bundle of all CA
certificates in @code{/etc/ssl/certs/ca-bundle.crt}; if not, you'll get an
error and have to adjust the location)

The @ref{85d,,PROTOCOL_TLS_CLIENT} protocol configures the context for cert
validation and hostname verification. @ref{33b0,,verify_mode} is
set to @ref{33b1,,CERT_REQUIRED} and @ref{33c4,,check_hostname} is set
to @code{True}. All other protocols create SSL contexts with insecure defaults.

When you use the context to connect to a server, @ref{33b1,,CERT_REQUIRED}
and @ref{33c4,,check_hostname} validate the server certificate: it
ensures that the server certificate was signed with one of the CA
certificates, checks the signature for correctness, and verifies other
properties like validity and identity of the hostname:

@example
>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
...                            server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))
@end example

You may then fetch the certificate:

@example
>>> cert = conn.getpeercert()
@end example

Visual inspection shows that the certificate does identify the desired service
(that is, the HTTPS host @code{www.python.org}):

@example
>>> pprint.pprint(cert)
@{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3@}
@end example

Now the SSL channel is established and the certificate verified, you can
proceed to talk with the server:

@example
>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'@w{'},
 b'@w{'}]
@end example

See the discussion of @ref{32a2,,Security considerations} below.

@node Server-side operation,,Client-side operation,Exemples<20>
@anchor{library/ssl server-side-operation}@anchor{3404}
@subsubsection Server-side operation


For server operation, typically you'll need to have a server certificate, and
private key, each in a file.  You'll first create a context holding the key
and the certificate, so that clients can check your authenticity.  Then
you'll open a socket, bind it to a port, call @code{listen()} on it, and start
waiting for clients to connect:

@example
import socket, ssl

context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")

bindsocket = socket.socket()
bindsocket.bind(('myaddr.example.com', 10023))
bindsocket.listen(5)
@end example

When a client connects, you'll call @code{accept()} on the socket to get the
new socket from the other end, and use the context's @ref{50e,,SSLContext.wrap_socket()}
method to create a server-side SSL socket for the connection:

@example
while True:
    newsocket, fromaddr = bindsocket.accept()
    connstream = context.wrap_socket(newsocket, server_side=True)
    try:
        deal_with_client(connstream)
    finally:
        connstream.shutdown(socket.SHUT_RDWR)
        connstream.close()
@end example

Then you'll read data from the @code{connstream} and do something with it till you
are finished with the client (or the client is finished with you):

@example
def deal_with_client(connstream):
    data = connstream.recv(1024)
    # empty data means the client is finished with us
    while data:
        if not do_something(connstream, data):
            # we'll assume do_something returns False
            # when we're finished with client
            break
        data = connstream.recv(1024)
    # finished with client
@end example

And go back to listening for new client connections (of course, a real server
would probably handle each client connection in a separate thread, or put
the sockets in @ref{33b6,,non-blocking mode} and use an event loop).

@node Notes on non-blocking sockets,Memory BIO Support<2>,Exemples<20>,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl notes-on-non-blocking-sockets}@anchor{3405}@anchor{library/ssl ssl-nonblocking}@anchor{33b6}
@subsubsection Notes on non-blocking sockets


SSL sockets behave slightly different than regular sockets in
non-blocking mode. When working with non-blocking sockets, there are
thus several things you need to be aware of:


@itemize -

@item 
Most @ref{8d7,,SSLSocket} methods will raise either
@ref{e53,,SSLWantWriteError} or @ref{e52,,SSLWantReadError} instead of
@ref{1040,,BlockingIOError} if an I/O operation would
block. @ref{e52,,SSLWantReadError} will be raised if a read operation on
the underlying socket is necessary, and @ref{e53,,SSLWantWriteError} for
a write operation on the underlying socket. Note that attempts to
`write' to an SSL socket may require `reading' from the underlying
socket first, and attempts to `read' from the SSL socket may require
a prior `write' to the underlying socket.


Modifié dans la version 3.5: In earlier Python versions, the @code{SSLSocket.send()} method
returned zero instead of raising @ref{e53,,SSLWantWriteError} or
@ref{e52,,SSLWantReadError}.


@item 
Calling @ref{d8d,,select()} tells you that the OS-level socket can be
read from (or written to), but it does not imply that there is sufficient
data at the upper SSL layer.  For example, only part of an SSL frame might
have arrived.  Therefore, you must be ready to handle @code{SSLSocket.recv()}
and @code{SSLSocket.send()} failures, and retry after another call to
@ref{d8d,,select()}.

@item 
Conversely, since the SSL layer has its own framing, a SSL socket may
still have data available for reading without @ref{d8d,,select()}
being aware of it.  Therefore, you should first call
@code{SSLSocket.recv()} to drain any potentially available data, and then
only block on a @ref{d8d,,select()} call if still necessary.

(of course, similar provisions apply when using other primitives such as
@ref{2b36,,poll()}, or those in the @ref{c1,,selectors} module)

@item 
The SSL handshake itself will be non-blocking: the
@ref{e56,,SSLSocket.do_handshake()} method has to be retried until it returns
successfully.  Here is a synopsis using @ref{d8d,,select()} to wait for
the socket's readiness:

@example
while True:
    try:
        sock.do_handshake()
        break
    except ssl.SSLWantReadError:
        select.select([sock], [], [])
    except ssl.SSLWantWriteError:
        select.select([], [sock], [])
@end example
@end itemize


@subsubheading Voir aussi


The @ref{a,,asyncio} module supports @ref{33b6,,non-blocking SSL sockets} and provides a higher level @ref{31d4,,Streams API}.
It polls for events using the @ref{c1,,selectors} module and
handles @ref{e53,,SSLWantWriteError}, @ref{e52,,SSLWantReadError} and
@ref{1040,,BlockingIOError} exceptions. It runs the SSL handshake asynchronously
as well.


@node Memory BIO Support<2>,SSL session,Notes on non-blocking sockets,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl memory-bio-support}@anchor{3406}
@subsubsection Memory BIO Support



Ajouté dans la version 3.5.


Ever since the SSL module was introduced in Python 2.6, the @ref{8d7,,SSLSocket}
class has provided two related but distinct areas of functionality:


@itemize -

@item 
SSL protocol handling

@item 
Network IO
@end itemize

The network IO API is identical to that provided by @ref{d8e,,socket.socket},
from which @ref{8d7,,SSLSocket} also inherits. This allows an SSL socket to be
used as a drop-in replacement for a regular socket, making it very easy to add
SSL support to an existing application.

Combining SSL protocol handling and network IO usually works well, but there
are some cases where it doesn't. An example is async IO frameworks that want to
use a different IO multiplexing model than the "select/poll on a file
descriptor" (readiness based) model that is assumed by @ref{d8e,,socket.socket}
and by the internal OpenSSL socket IO routines. This is mostly relevant for
platforms like Windows where this model is not efficient. For this purpose, a
reduced scope variant of @ref{8d7,,SSLSocket} called @ref{b6f,,SSLObject} is
provided.

@geindex SSLObject (classe dans ssl)
@anchor{library/ssl ssl SSLObject}@anchor{b6f}
@deffn {Classe} ssl.SSLObject

A reduced-scope variant of @ref{8d7,,SSLSocket} representing an SSL protocol
instance that does not contain any network IO methods. This class is
typically used by framework authors that want to implement asynchronous IO
for SSL through memory buffers.

This class implements an interface on top of a low-level SSL object as
implemented by OpenSSL. This object captures the state of an SSL connection
but does not provide any network IO itself. IO needs to be performed through
separate "BIO" objects which are OpenSSL's IO abstraction layer.

This class has no public constructor.  An @ref{b6f,,SSLObject} instance
must be created using the @ref{b70,,wrap_bio()} method. This
method will create the @ref{b6f,,SSLObject} instance and bind it to a
pair of BIOs. The `incoming' BIO is used to pass data from Python to the
SSL protocol instance, while the `outgoing' BIO is used to pass data the
other way around.

The following methods are available:


@itemize -

@item 
@ref{33ed,,context}

@item 
@ref{33ef,,server_side}

@item 
@ref{b6d,,server_hostname}

@item 
@ref{1534,,session}

@item 
@ref{33f0,,session_reused}

@item 
@ref{e57,,read()}

@item 
@ref{e58,,write()}

@item 
@ref{fa2,,getpeercert()}

@item 
@ref{1564,,get_verified_chain()}

@item 
@ref{1565,,get_unverified_chain()}

@item 
@ref{e4e,,selected_alpn_protocol()}

@item 
@ref{85f,,selected_npn_protocol()}

@item 
@ref{32e7,,cipher()}

@item 
@ref{e55,,shared_ciphers()}

@item 
@ref{1125,,compression()}

@item 
@ref{33ee,,pending()}

@item 
@ref{e56,,do_handshake()}

@item 
@ref{a20,,verify_client_post_handshake()}

@item 
@ref{33ec,,unwrap()}

@item 
@ref{1124,,get_channel_binding()}

@item 
@ref{e51,,version()}
@end itemize

When compared to @ref{8d7,,SSLSocket}, this object lacks the following
features:


@itemize -

@item 
Any form of network IO; @code{recv()} and @code{send()} read and write only to
the underlying @ref{e4b,,MemoryBIO} buffers.

@item 
There is no `do_handshake_on_connect' machinery. You must always manually
call @ref{e56,,do_handshake()} to start the handshake.

@item 
There is no handling of `suppress_ragged_eofs'. All end-of-file conditions
that are in violation of the protocol are reported via the
@ref{16d2,,SSLEOFError} exception.

@item 
The method @ref{33ec,,unwrap()} call does not return anything,
unlike for an SSL socket where it returns the underlying socket.

@item 
The `server_name_callback' callback passed to
@ref{fa1,,SSLContext.set_servername_callback()} will get an @ref{b6f,,SSLObject}
instance instead of a @ref{8d7,,SSLSocket} instance as its first parameter.
@end itemize

Some notes related to the use of @ref{b6f,,SSLObject}:


@itemize -

@item 
All IO on an @ref{b6f,,SSLObject} is @ref{33b6,,non-blocking}.
This means that for example @ref{e57,,read()} will raise an
@ref{e52,,SSLWantReadError} if it needs more data than the incoming BIO has
available.
@end itemize


Modifié dans la version 3.7: @ref{b6f,,SSLObject} instances must be created with
@ref{b70,,wrap_bio()}. In earlier versions, it was possible to
create instances directly. This was never documented or officially
supported.

@end deffn

An SSLObject communicates with the outside world using memory buffers. The
class @ref{e4b,,MemoryBIO} provides a memory buffer that can be used for this
purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:

@geindex MemoryBIO (classe dans ssl)
@anchor{library/ssl ssl MemoryBIO}@anchor{e4b}
@deffn {Classe} ssl.MemoryBIO

A memory buffer that can be used to pass data between Python and an SSL
protocol instance.

@geindex pending (attribut ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO pending}@anchor{3407}
@deffn {Attribut} pending

Return the number of bytes currently in the memory buffer.
@end deffn

@geindex eof (attribut ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO eof}@anchor{3408}
@deffn {Attribut} eof

A boolean indicating whether the memory BIO is current at the end-of-file
position.
@end deffn

@geindex read() (méthode ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO read}@anchor{3409}
@deffn {Méthode} read (n=-1)

Read up to `n' bytes from the memory buffer. If `n' is not specified or
negative, all bytes are returned.
@end deffn

@geindex write() (méthode ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO write}@anchor{340a}
@deffn {Méthode} write (buf)

Write the bytes from `buf' to the memory BIO. The `buf' argument must be an
object supporting the buffer protocol.

The return value is the number of bytes written, which is always equal to
the length of `buf'.
@end deffn

@geindex write_eof() (méthode ssl.MemoryBIO)
@anchor{library/ssl ssl MemoryBIO write_eof}@anchor{340b}
@deffn {Méthode} write_eof ()

Write an EOF marker to the memory BIO. After this method has been called, it
is illegal to call @ref{340a,,write()}. The attribute @ref{3408,,eof} will
become true after all data currently in the buffer has been read.
@end deffn
@end deffn

@node SSL session,Security considerations<2>,Memory BIO Support<2>,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-session}@anchor{340c}
@subsubsection SSL session



Ajouté dans la version 3.6.


@geindex SSLSession (classe dans ssl)
@anchor{library/ssl ssl SSLSession}@anchor{ccb}
@deffn {Classe} ssl.SSLSession

Session object used by @ref{1534,,session}.

@geindex id (attribut ssl.SSLSession)
@anchor{library/ssl ssl SSLSession id}@anchor{340d}
@deffn {Attribut} id
@end deffn

@geindex time (attribut ssl.SSLSession)
@anchor{library/ssl ssl SSLSession time}@anchor{340e}
@deffn {Attribut} time
@end deffn

@geindex timeout (attribut ssl.SSLSession)
@anchor{library/ssl ssl SSLSession timeout}@anchor{340f}
@deffn {Attribut} timeout
@end deffn

@geindex ticket_lifetime_hint (attribut ssl.SSLSession)
@anchor{library/ssl ssl SSLSession ticket_lifetime_hint}@anchor{3410}
@deffn {Attribut} ticket_lifetime_hint
@end deffn

@geindex has_ticket (attribut ssl.SSLSession)
@anchor{library/ssl ssl SSLSession has_ticket}@anchor{3411}
@deffn {Attribut} has_ticket
@end deffn
@end deffn

@node Security considerations<2>,TLS 1 3,SSL session,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl security-considerations}@anchor{3412}@anchor{library/ssl ssl-security}@anchor{32a2}
@subsubsection Security considerations


@menu
* Best defaults:: 
* Manual settings:: 
* Multi-processing:: 

@end menu

@node Best defaults,Manual settings,,Security considerations<2>
@anchor{library/ssl best-defaults}@anchor{3413}
@subsubsection Best defaults


For `client use', if you don't have any special requirements for your
security policy, it is highly recommended that you use the
@ref{154,,create_default_context()} function to create your SSL context.
It will load the system's trusted CA certificates, enable certificate
validation and hostname checking, and try to choose reasonably secure
protocol and cipher settings.

For example, here is how you would use the @ref{91a,,smtplib.SMTP} class to
create a trusted, secure connection to a SMTP server:

@example
>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')
@end example

If a client certificate is needed for the connection, it can be added with
@ref{292,,SSLContext.load_cert_chain()}.

By contrast, if you create the SSL context by calling the @ref{291,,SSLContext}
constructor yourself, it will not have certificate validation nor hostname
checking enabled by default.  If you do so, please read the paragraphs below
to achieve a good security level.

@node Manual settings,Multi-processing,Best defaults,Security considerations<2>
@anchor{library/ssl manual-settings}@anchor{3414}
@subsubsection Manual settings


@menu
* Verifying certificates:: 
* Protocol versions:: 
* Cipher selection:: 

@end menu

@node Verifying certificates,Protocol versions,,Manual settings
@anchor{library/ssl verifying-certificates}@anchor{3415}
@subsubsection Verifying certificates


When calling the @ref{291,,SSLContext} constructor directly,
@ref{33c2,,CERT_NONE} is the default.  Since it does not authenticate the other
peer, it can be insecure, especially in client mode where most of the time you
would like to ensure the authenticity of the server you're talking to.
Therefore, when in client mode, it is highly recommended to use
@ref{33b1,,CERT_REQUIRED}.  However, it is in itself not sufficient; you also
have to check that the server certificate, which can be obtained by calling
@ref{fa2,,SSLSocket.getpeercert()}, matches the desired service.  For many
protocols and applications, the service can be identified by the hostname.
This common check is automatically performed when
@ref{33c4,,SSLContext.check_hostname} is enabled.


Modifié dans la version 3.7: Hostname matchings is now performed by OpenSSL. Python no longer uses
@code{match_hostname()}.


In server mode, if you want to authenticate your clients using the SSL layer
(rather than using a higher-level authentication mechanism), you'll also have
to specify @ref{33b1,,CERT_REQUIRED} and similarly check the client certificate.

@node Protocol versions,Cipher selection,Verifying certificates,Manual settings
@anchor{library/ssl protocol-versions}@anchor{3416}
@subsubsection Protocol versions


SSL versions 2 and 3 are considered insecure and are therefore dangerous to
use.  If you want maximum compatibility between clients and servers, it is
recommended to use @ref{85d,,PROTOCOL_TLS_CLIENT} or
@ref{85e,,PROTOCOL_TLS_SERVER} as the protocol version. SSLv2 and SSLv3 are
disabled by default.

@example
>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.minimum_version = ssl.TLSVersion.TLSv1_3
>>> client_context.maximum_version = ssl.TLSVersion.TLSv1_3
@end example

The SSL context created above will only allow TLSv1.3 and later (if
supported by your system) connections to a server. @ref{85d,,PROTOCOL_TLS_CLIENT}
implies certificate validation and hostname checks by default. You have to
load certificates into the context.

@node Cipher selection,,Protocol versions,Manual settings
@anchor{library/ssl cipher-selection}@anchor{3417}
@subsubsection Cipher selection


If you have advanced security requirements, fine-tuning of the ciphers
enabled when negotiating a SSL session is possible through the
@ref{33f3,,SSLContext.set_ciphers()} method.  Starting from Python 3.2.3, the
ssl module disables certain weak ciphers by default, but you may want
to further restrict the cipher choice. Be sure to read OpenSSL's documentation
about the cipher list format@footnote{https://docs.openssl.org/1.1.1/man1/ciphers/#cipher-list-format}.
If you want to check which ciphers are enabled by a given cipher list, use
@ref{ccc,,SSLContext.get_ciphers()} or the @code{openssl ciphers} command on your
system.

@node Multi-processing,,Manual settings,Security considerations<2>
@anchor{library/ssl multi-processing}@anchor{3418}
@subsubsection Multi-processing


If using this module as part of a multi-processed application (using,
for example the @ref{93,,multiprocessing} or @ref{21,,concurrent.futures} modules),
be aware that OpenSSL's internal random number generator does not properly
handle forked processes.  Applications must change the PRNG state of the
parent process if they use any SSL feature with @ref{195,,os.fork()}.  Any
successful call of @ref{33bc,,RAND_add()} or @ref{50d,,RAND_bytes()} is
sufficient.

@node TLS 1 3,,Security considerations<2>,ssl --- TLS/SSL wrapper for socket objects
@anchor{library/ssl ssl-tlsv1-3}@anchor{b6e}@anchor{library/ssl tls-1-3}@anchor{3419}
@subsubsection TLS 1.3



Ajouté dans la version 3.7.


The TLS 1.3 protocol behaves slightly differently than previous version
of TLS/SSL. Some new TLS 1.3 features are not yet available.


@itemize -

@item 
TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM and
ChaCha20 cipher suites are enabled by default.  The method
@ref{33f3,,SSLContext.set_ciphers()} cannot enable or disable any TLS 1.3
ciphers yet, but @ref{ccc,,SSLContext.get_ciphers()} returns them.

@item 
Session tickets are no longer sent as part of the initial handshake and
are handled differently.  @ref{1534,,SSLSocket.session} and @ref{ccb,,SSLSession}
are not compatible with TLS 1.3.

@item 
Client-side certificates are also no longer verified during the initial
handshake.  A server can request a certificate at any time.  Clients
process certificate requests while they send or receive application data
from the server.

@item 
TLS 1.3 features like early data, deferred TLS client cert request,
signature algorithm configuration, and rekeying are not supported yet.
@end itemize


@subsubheading Voir aussi



@table @asis

@item Class @ref{d8e,,socket.socket}

Documentation of underlying @ref{cb,,socket} class

@item SSL/TLS Strong Encryption: An Introduction@footnote{https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html}

Intro from the Apache HTTP Server documentation

@geindex RFC; RFC 1422

@item RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management@footnote{https://datatracker.ietf.org/doc/html/rfc1422.html}

Steve Kent

@geindex RFC; RFC 4086

@item RFC 4086: Randomness Requirements for Security@footnote{https://datatracker.ietf.org/doc/html/rfc4086.html}

Donald E., Jeffrey I. Schiller

@geindex RFC; RFC 5280

@item RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile@footnote{https://datatracker.ietf.org/doc/html/rfc5280.html}

D. Cooper

@geindex RFC; RFC 5246

@item RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2@footnote{https://datatracker.ietf.org/doc/html/rfc5246.html}

T. Dierks et. al.

@geindex RFC; RFC 6066

@item RFC 6066: Transport Layer Security (TLS) Extensions@footnote{https://datatracker.ietf.org/doc/html/rfc6066.html}

D. Eastlake

@item IANA TLS: Transport Layer Security (TLS) Parameters@footnote{https://www.iana.org/assignments/tls-parameters/tls-parameters.xml}

IANA

@geindex RFC; RFC 7525

@item RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)@footnote{https://datatracker.ietf.org/doc/html/rfc7525.html}

IETF

@item Mozilla's Server Side TLS recommendations@footnote{https://wiki.mozilla.org/Security/Server_Side_TLS}

Mozilla
@end table


@node select --- Waiting for I/O completion,selectors --- High-level I/O multiplexing,ssl --- TLS/SSL wrapper for socket objects,Réseau et communication entre processus
@anchor{library/select doc}@anchor{341a}@anchor{library/select module-select}@anchor{c0}@anchor{library/select select-waiting-for-i-o-completion}@anchor{341b}
@subsection @code{select} --- Waiting for I/O completion


@geindex module; select


__________________________________________________________________


This module provides access to the @code{select()} and @code{poll()} functions
available in most operating systems, @code{devpoll()} available on
Solaris and derivatives, @code{epoll()} available on Linux 2.5+ and
@code{kqueue()} available on most BSD.
Note that on Windows, it only works for sockets; on other operating systems,
it also works for other file types (in particular, on Unix, it works on pipes).
It cannot be used on regular files to determine whether a file has grown since
it was last read.

@cartouche
@quotation Note 
The @ref{c1,,selectors} module allows high-level and efficient I/O
multiplexing, built upon the @ref{c0,,select} module primitives. Users are
encouraged to use the @ref{c1,,selectors} module instead, unless they want
precise control over the OS-level primitives used.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Le module définit :

@geindex error
@anchor{library/select select error}@anchor{103f}
@deffn {Exception} select.error

A deprecated alias of @ref{40d,,OSError}.


Modifié dans la version 3.3: Following 
@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/}, this class was made an alias of @ref{40d,,OSError}.

@end deffn

@geindex devpoll() (dans le module select)
@anchor{library/select select devpoll}@anchor{f80}
@deffn {Fonction} select.devpoll ()

(Only supported on Solaris and derivatives.)  Returns a @code{/dev/poll}
polling object; see section @ref{341c,,/dev/poll Polling Objects} below for the
methods supported by devpoll objects.

@code{devpoll()} objects are linked to the number of file
descriptors allowed at the time of instantiation. If your program
reduces this value, @code{devpoll()} will fail. If your program
increases this value, @code{devpoll()} may return an
incomplete list of active file descriptors.

The new file descriptor is @ref{ee4,,non-inheritable}.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: Le nouveau descripteur de fichier est maintenant non-héritable.

@end deffn

@geindex epoll() (dans le module select)
@anchor{library/select select epoll}@anchor{f7e}
@deffn {Fonction} select.epoll (sizehint=-1, flags=0)

(Only supported on Linux 2.5.44 and newer.) Return an edge polling object,
which can be used as Edge or Level Triggered interface for I/O
events.

`sizehint' informs epoll about the expected number of events to be
registered.  It must be positive, or @code{-1} to use the default. It is only
used on older systems where @code{epoll_create1()} is not available;
otherwise it has no effect (though its value is still checked).

`flags' is deprecated and completely ignored.  However, when supplied, its
value must be @code{0} or @code{select.EPOLL_CLOEXEC}, otherwise @code{OSError} is
raised.

See the @ref{341d,,Edge and Level Trigger Polling (epoll) Objects} section below for the methods supported by
epolling objects.

@code{epoll} objects support the context management protocol: when used in a
@ref{5bc,,with} statement, the new file descriptor is automatically closed
at the end of the block.

The new file descriptor is @ref{ee4,,non-inheritable}.


Modifié dans la version 3.3: Added the `flags' parameter.



Modifié dans la version 3.4: Support for the @ref{5bc,,with} statement was added.
The new file descriptor is now non-inheritable.



Obsolète depuis la version 3.4: The `flags' parameter.  @code{select.EPOLL_CLOEXEC} is used by default now.
Use @ref{ee6,,os.set_inheritable()} to make the file descriptor inheritable.

@end deffn

@geindex poll() (dans le module select)
@anchor{library/select select poll}@anchor{2b36}
@deffn {Fonction} select.poll ()

(Not supported by all operating systems.)  Returns a polling object, which
supports registering and unregistering file descriptors, and then polling them
for I/O events; see section @ref{341e,,Polling Objects} below for the methods supported
by polling objects.
@end deffn

@geindex kqueue() (dans le module select)
@anchor{library/select select kqueue}@anchor{1657}
@deffn {Fonction} select.kqueue ()

(Only supported on BSD.)  Returns a kernel queue object; see section
@ref{341f,,Kqueue Objects} below for the methods supported by kqueue objects.

The new file descriptor is @ref{ee4,,non-inheritable}.


Modifié dans la version 3.4: Le nouveau descripteur de fichier est maintenant non-héritable.

@end deffn

@geindex kevent() (dans le module select)
@anchor{library/select select kevent}@anchor{3420}
@deffn {Fonction} select.kevent (ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)

(Only supported on BSD.)  Returns a kernel event object; see section
@ref{3421,,Kevent Objects} below for the methods supported by kevent objects.
@end deffn

@geindex select() (dans le module select)
@anchor{library/select select select}@anchor{d8d}
@deffn {Fonction} select.select (rlist, wlist, xlist[, timeout])

This is a straightforward interface to the Unix @code{select()} system call.
The first three arguments are iterables of 'waitable objects': either
integers representing file descriptors or objects with a parameterless method
named @ref{27cf,,fileno()} returning such an integer:


@itemize *

@item 
`rlist': wait until ready for reading

@item 
`wlist': wait until ready for writing

@item 
`xlist': wait for an "exceptional condition" (see the manual page for what
your system considers such a condition)
@end itemize

Empty iterables are allowed, but acceptance of three empty iterables is
platform-dependent. (It is known to work on Unix but not on Windows.)  The
optional `timeout' argument specifies a time-out as a floating-point number
in seconds.  When the `timeout' argument is omitted the function blocks until
at least one file descriptor is ready.  A time-out value of zero specifies a
poll and never blocks.

The return value is a triple of lists of objects that are ready: subsets of the
first three arguments.  When the time-out is reached without a file descriptor
becoming ready, three empty lists are returned.

@geindex socket() (in module socket)
@geindex popen() (in module os)

Among the acceptable object types in the iterables are Python @ref{11a0,,file objects} (e.g. @code{sys.stdin}, or objects returned by
@ref{505,,open()} or @ref{a75,,os.popen()}), socket objects returned by
@ref{d8e,,socket.socket()}.  You may also define a `wrapper' class yourself,
as long as it has an appropriate @ref{27cf,,fileno()} method (that
really returns a file descriptor, not just a random integer).

@cartouche
@quotation Note 
@geindex WinSock

File objects on Windows are not acceptable, but sockets are.  On Windows,
the underlying @code{select()} function is provided by the WinSock
library, and does not handle file descriptors that don't originate from
WinSock.
@end quotation
@end cartouche


Modifié dans la version 3.5: The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale), instead of raising
@ref{d75,,InterruptedError}.

@end deffn

@geindex PIPE_BUF (dans le module select)
@anchor{library/select select PIPE_BUF}@anchor{11e7}
@deffn {Attribut} select.PIPE_BUF

The minimum number of bytes which can be written without blocking to a pipe
when the pipe has been reported as ready for writing by @ref{d8d,,select()},
@code{poll()} or another interface in this module.  This doesn't apply
to other kind of file-like objects such as sockets.

This value is guaranteed by POSIX to be at least 512.

@ref{1ce0,,Availability}: Unix


Ajouté dans la version 3.2.

@end deffn

@menu
* /dev/poll Polling Objects:: 
* Edge and Level Trigger Polling (epoll) Objects: Edge and Level Trigger Polling epoll Objects. 
* Polling Objects:: 
* Kqueue Objects:: 
* Kevent Objects:: 

@end menu

@node /dev/poll Polling Objects,Edge and Level Trigger Polling epoll Objects,,select --- Waiting for I/O completion
@anchor{library/select dev-poll-polling-objects}@anchor{3422}@anchor{library/select devpoll-objects}@anchor{341c}
@subsubsection @code{/dev/poll} Polling Objects


Solaris and derivatives have @code{/dev/poll}. While @code{select()} is
`O'(`highest file descriptor') and @code{poll()} is `O'(`number of file
descriptors'), @code{/dev/poll} is `O'(`active file descriptors').

@code{/dev/poll} behaviour is very close to the standard @code{poll()}
object.

@geindex close() (méthode select.devpoll)
@anchor{library/select select devpoll close}@anchor{f82}
@deffn {Méthode} devpoll.close ()

Close the file descriptor of the polling object.


Ajouté dans la version 3.4.

@end deffn

@geindex closed (attribut select.devpoll)
@anchor{library/select select devpoll closed}@anchor{f83}
@deffn {Attribut} devpoll.closed

@code{True} if the polling object is closed.


Ajouté dans la version 3.4.

@end deffn

@geindex fileno() (méthode select.devpoll)
@anchor{library/select select devpoll fileno}@anchor{f81}
@deffn {Méthode} devpoll.fileno ()

Return the file descriptor number of the polling object.


Ajouté dans la version 3.4.

@end deffn

@geindex register() (méthode select.devpoll)
@anchor{library/select select devpoll register}@anchor{3423}
@deffn {Méthode} devpoll.register (fd[, eventmask])

Register a file descriptor with the polling object.  Future calls to the
@ref{2b36,,poll()} method will then check whether the file descriptor has any
pending I/O events.  `fd' can be either an integer, or an object with a
@ref{27cf,,fileno()} method that returns an integer.  File objects
implement @code{fileno()}, so they can also be used as the argument.

`eventmask' is an optional bitmask describing the type of events you want to
check for. The constants are the same that with @code{poll()}
object. The default value is a combination of the constants @code{POLLIN},
@code{POLLPRI}, and @code{POLLOUT}.

@cartouche
@quotation Avertissement 
Registering a file descriptor that's already registered is not an
error, but the result is undefined. The appropriate action is to
unregister or modify it first. This is an important difference
compared with @code{poll()}.
@end quotation
@end cartouche
@end deffn

@geindex modify() (méthode select.devpoll)
@anchor{library/select select devpoll modify}@anchor{3424}
@deffn {Méthode} devpoll.modify (fd[, eventmask])

This method does an @ref{3425,,unregister()} followed by a
@ref{3423,,register()}. It is (a bit) more efficient that doing the same
explicitly.
@end deffn

@geindex unregister() (méthode select.devpoll)
@anchor{library/select select devpoll unregister}@anchor{3425}
@deffn {Méthode} devpoll.unregister (fd)

Remove a file descriptor being tracked by a polling object.  Just like the
@ref{3423,,register()} method, `fd' can be an integer or an object with a
@ref{27cf,,fileno()} method that returns an integer.

Attempting to remove a file descriptor that was never registered is
safely ignored.
@end deffn

@geindex poll() (méthode select.devpoll)
@anchor{library/select select devpoll poll}@anchor{d89}
@deffn {Méthode} devpoll.poll ([timeout])

Polls the set of registered file descriptors, and returns a possibly empty list
containing @code{(fd, event)} 2-tuples for the descriptors that have events or
errors to report. `fd' is the file descriptor, and `event' is a bitmask with
bits set for the reported events for that descriptor --- @code{POLLIN} for
waiting input, @code{POLLOUT} to indicate that the descriptor can be written
to, and so forth. An empty list indicates that the call timed out and no file
descriptors had any events to report. If `timeout' is given, it specifies the
length of time in milliseconds which the system will wait for events before
returning. If `timeout' is omitted, -1, or @ref{660,,None}, the call will
block until there is an event for this poll object.


Modifié dans la version 3.5: The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale), instead of raising
@ref{d75,,InterruptedError}.

@end deffn

@node Edge and Level Trigger Polling epoll Objects,Polling Objects,/dev/poll Polling Objects,select --- Waiting for I/O completion
@anchor{library/select edge-and-level-trigger-polling-epoll-objects}@anchor{3426}@anchor{library/select epoll-objects}@anchor{341d}
@subsubsection Edge and Level Trigger Polling (epoll) Objects


@quotation

@indicateurl{https://linux.die.net/man/4/epoll}

`eventmask'


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{EPOLLIN}

@tab

Available for read

@item

@code{EPOLLOUT}

@tab

Available for write

@item

@code{EPOLLPRI}

@tab

Urgent data for read

@item

@code{EPOLLERR}

@tab

Error condition happened on the assoc. fd

@item

@code{EPOLLHUP}

@tab

Hang up happened on the assoc. fd

@item

@code{EPOLLET}

@tab

Set Edge Trigger behavior, the default is
Level Trigger behavior

@item

@code{EPOLLONESHOT}

@tab

Set one-shot behavior. After one event is
pulled out, the fd is internally disabled

@item

@code{EPOLLEXCLUSIVE}

@tab

Wake only one epoll object when the
associated fd has an event. The default (if
this flag is not set) is to wake all epoll
objects polling on a fd.

@item

@code{EPOLLRDHUP}

@tab

Stream socket peer closed connection or shut
down writing half of connection.

@item

@code{EPOLLRDNORM}

@tab

Equivalent to @code{EPOLLIN}

@item

@code{EPOLLRDBAND}

@tab

Priority data band can be read.

@item

@code{EPOLLWRNORM}

@tab

Equivalent to @code{EPOLLOUT}

@item

@code{EPOLLWRBAND}

@tab

Priority data may be written.

@item

@code{EPOLLMSG}

@tab

Ignored.

@end multitable



Ajouté dans la version 3.6: @code{EPOLLEXCLUSIVE} was added.  It's only supported by Linux Kernel 4.5
or later.

@end quotation

@geindex close() (méthode select.epoll)
@anchor{library/select select epoll close}@anchor{f7f}
@deffn {Méthode} epoll.close ()

Close the control file descriptor of the epoll object.
@end deffn

@geindex closed (attribut select.epoll)
@anchor{library/select select epoll closed}@anchor{3427}
@deffn {Attribut} epoll.closed

@code{True} if the epoll object is closed.
@end deffn

@geindex fileno() (méthode select.epoll)
@anchor{library/select select epoll fileno}@anchor{3428}
@deffn {Méthode} epoll.fileno ()

Return the file descriptor number of the control fd.
@end deffn

@geindex fromfd() (méthode select.epoll)
@anchor{library/select select epoll fromfd}@anchor{3429}
@deffn {Méthode} epoll.fromfd (fd)

Create an epoll object from a given file descriptor.
@end deffn

@geindex register() (méthode select.epoll)
@anchor{library/select select epoll register}@anchor{342a}
@deffn {Méthode} epoll.register (fd[, eventmask])

Register a fd descriptor with the epoll object.
@end deffn

@geindex modify() (méthode select.epoll)
@anchor{library/select select epoll modify}@anchor{342b}
@deffn {Méthode} epoll.modify (fd, eventmask)

Modify a registered file descriptor.
@end deffn

@geindex unregister() (méthode select.epoll)
@anchor{library/select select epoll unregister}@anchor{947}
@deffn {Méthode} epoll.unregister (fd)

Remove a registered file descriptor from the epoll object.


Modifié dans la version 3.9: The method no longer ignores the @ref{948,,EBADF} error.

@end deffn

@geindex poll() (méthode select.epoll)
@anchor{library/select select epoll poll}@anchor{d8a}
@deffn {Méthode} epoll.poll (timeout=None, maxevents=-1)

Wait for events. timeout in seconds (float)


Modifié dans la version 3.5: The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale), instead of raising
@ref{d75,,InterruptedError}.

@end deffn

@node Polling Objects,Kqueue Objects,Edge and Level Trigger Polling epoll Objects,select --- Waiting for I/O completion
@anchor{library/select poll-objects}@anchor{341e}@anchor{library/select polling-objects}@anchor{342c}
@subsubsection Polling Objects


The @code{poll()} system call, supported on most Unix systems, provides better
scalability for network servers that service many, many clients at the same
time. @code{poll()} scales better because the system call only requires listing
the file descriptors of interest, while @code{select()} builds a bitmap, turns
on bits for the fds of interest, and then afterward the whole bitmap has to be
linearly scanned again. @code{select()} is `O'(`highest file descriptor'), while
@code{poll()} is `O'(`number of file descriptors').

@geindex register() (méthode select.poll)
@anchor{library/select select poll register}@anchor{342d}
@deffn {Méthode} poll.register (fd[, eventmask])

Register a file descriptor with the polling object.  Future calls to the
@ref{2b36,,poll()} method will then check whether the file descriptor has any
pending I/O events.  `fd' can be either an integer, or an object with a
@ref{27cf,,fileno()} method that returns an integer.  File objects
implement @code{fileno()}, so they can also be used as the argument.

`eventmask' is an optional bitmask describing the type of events you want to
check for, and can be a combination of the constants @code{POLLIN},
@code{POLLPRI}, and @code{POLLOUT}, described in the table below.  If not
specified, the default value used will check for all 3 types of events.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{POLLIN}

@tab

There is data to read

@item

@code{POLLPRI}

@tab

There is urgent data to read

@item

@code{POLLOUT}

@tab

Ready for output: writing will not block

@item

@code{POLLERR}

@tab

Error condition of some sort

@item

@code{POLLHUP}

@tab

Hung up

@item

@code{POLLRDHUP}

@tab

Stream socket peer closed connection, or
shut down writing half of connection

@item

@code{POLLNVAL}

@tab

Invalid request: descriptor not open

@end multitable


Registering a file descriptor that's already registered is not an error, and has
the same effect as registering the descriptor exactly once.
@end deffn

@geindex modify() (méthode select.poll)
@anchor{library/select select poll modify}@anchor{342e}
@deffn {Méthode} poll.modify (fd, eventmask)

Modifies an already registered fd. This has the same effect as
@code{register(fd, eventmask)}.  Attempting to modify a file descriptor
that was never registered causes an @ref{40d,,OSError} exception with errno
@code{ENOENT} to be raised.
@end deffn

@geindex unregister() (méthode select.poll)
@anchor{library/select select poll unregister}@anchor{342f}
@deffn {Méthode} poll.unregister (fd)

Remove a file descriptor being tracked by a polling object.  Just like the
@ref{342d,,register()} method, `fd' can be an integer or an object with a
@ref{27cf,,fileno()} method that returns an integer.

Attempting to remove a file descriptor that was never registered causes a
@ref{33a,,KeyError} exception to be raised.
@end deffn

@geindex poll() (méthode select.poll)
@anchor{library/select select poll poll}@anchor{d8c}
@deffn {Méthode} poll.poll ([timeout])

Polls the set of registered file descriptors, and returns a possibly empty list
containing @code{(fd, event)} 2-tuples for the descriptors that have events or
errors to report. `fd' is the file descriptor, and `event' is a bitmask with
bits set for the reported events for that descriptor --- @code{POLLIN} for
waiting input, @code{POLLOUT} to indicate that the descriptor can be written
to, and so forth. An empty list indicates that the call timed out and no file
descriptors had any events to report. If `timeout' is given, it specifies the
length of time in milliseconds which the system will wait for events before
returning. If `timeout' is omitted, negative, or @ref{660,,None}, the call will
block until there is an event for this poll object.


Modifié dans la version 3.5: The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale), instead of raising
@ref{d75,,InterruptedError}.

@end deffn

@node Kqueue Objects,Kevent Objects,Polling Objects,select --- Waiting for I/O completion
@anchor{library/select id1}@anchor{3430}@anchor{library/select kqueue-objects}@anchor{341f}
@subsubsection Kqueue Objects


@geindex close() (méthode select.kqueue)
@anchor{library/select select kqueue close}@anchor{3431}
@deffn {Méthode} kqueue.close ()

Close the control file descriptor of the kqueue object.
@end deffn

@geindex closed (attribut select.kqueue)
@anchor{library/select select kqueue closed}@anchor{3432}
@deffn {Attribut} kqueue.closed

@code{True} if the kqueue object is closed.
@end deffn

@geindex fileno() (méthode select.kqueue)
@anchor{library/select select kqueue fileno}@anchor{3433}
@deffn {Méthode} kqueue.fileno ()

Return the file descriptor number of the control fd.
@end deffn

@geindex fromfd() (méthode select.kqueue)
@anchor{library/select select kqueue fromfd}@anchor{3434}
@deffn {Méthode} kqueue.fromfd (fd)

Create a kqueue object from a given file descriptor.
@end deffn

@geindex control() (méthode select.kqueue)
@anchor{library/select select kqueue control}@anchor{d8b}
@deffn {Méthode} kqueue.control (changelist, max_events[, timeout]) -> eventlist

Low level interface to kevent


@itemize -

@item 
changelist must be an iterable of kevent objects or @code{None}

@item 
max_events must be 0 or a positive integer

@item 
timeout in seconds (floats possible); the default is @code{None},
to wait forever
@end itemize


Modifié dans la version 3.5: The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale), instead of raising
@ref{d75,,InterruptedError}.

@end deffn

@node Kevent Objects,,Kqueue Objects,select --- Waiting for I/O completion
@anchor{library/select id2}@anchor{3435}@anchor{library/select kevent-objects}@anchor{3421}
@subsubsection Kevent Objects


@indicateurl{https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2}

@geindex ident (attribut select.kevent)
@anchor{library/select select kevent ident}@anchor{3436}
@deffn {Attribut} kevent.ident

Value used to identify the event. The interpretation depends on the filter
but it's usually the file descriptor. In the constructor ident can either
be an int or an object with a @ref{27cf,,fileno()} method. kevent
stores the integer internally.
@end deffn

@geindex filter (attribut select.kevent)
@anchor{library/select select kevent filter}@anchor{3437}
@deffn {Attribut} kevent.filter

Name of the kernel filter.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{KQ_FILTER_READ}

@tab

Takes a descriptor and returns whenever
there is data available to read

@item

@code{KQ_FILTER_WRITE}

@tab

Takes a descriptor and returns whenever
there is data available to write

@item

@code{KQ_FILTER_AIO}

@tab

AIO requests

@item

@code{KQ_FILTER_VNODE}

@tab

Returns when one or more of the requested
events watched in `fflag' occurs

@item

@code{KQ_FILTER_PROC}

@tab

Watch for events on a process id

@item

@code{KQ_FILTER_NETDEV}

@tab

Watch for events on a network device
[not available on macOS]

@item

@code{KQ_FILTER_SIGNAL}

@tab

Returns whenever the watched signal is
delivered to the process

@item

@code{KQ_FILTER_TIMER}

@tab

Establishes an arbitrary timer

@end multitable

@end deffn

@geindex flags (attribut select.kevent)
@anchor{library/select select kevent flags}@anchor{3438}
@deffn {Attribut} kevent.flags

Filter action.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{KQ_EV_ADD}

@tab

Adds or modifies an event

@item

@code{KQ_EV_DELETE}

@tab

Removes an event from the queue

@item

@code{KQ_EV_ENABLE}

@tab

Permitscontrol() to returns the event

@item

@code{KQ_EV_DISABLE}

@tab

Disablesevent

@item

@code{KQ_EV_ONESHOT}

@tab

Removes event after first occurrence

@item

@code{KQ_EV_CLEAR}

@tab

Reset the state after an event is retrieved

@item

@code{KQ_EV_SYSFLAGS}

@tab

internal event

@item

@code{KQ_EV_FLAG1}

@tab

internal event

@item

@code{KQ_EV_EOF}

@tab

Filter specific EOF condition

@item

@code{KQ_EV_ERROR}

@tab

See return values

@end multitable

@end deffn

@geindex fflags (attribut select.kevent)
@anchor{library/select select kevent fflags}@anchor{3439}
@deffn {Attribut} kevent.fflags

Filter specific flags.

@code{KQ_FILTER_READ} and  @code{KQ_FILTER_WRITE} filter flags:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{KQ_NOTE_LOWAT}

@tab

low water mark of a socket buffer

@end multitable


@code{KQ_FILTER_VNODE} filter flags:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{KQ_NOTE_DELETE}

@tab

`unlink()' was called

@item

@code{KQ_NOTE_WRITE}

@tab

a write occurred

@item

@code{KQ_NOTE_EXTEND}

@tab

the file was extended

@item

@code{KQ_NOTE_ATTRIB}

@tab

an attribute was changed

@item

@code{KQ_NOTE_LINK}

@tab

the link count has changed

@item

@code{KQ_NOTE_RENAME}

@tab

the file was renamed

@item

@code{KQ_NOTE_REVOKE}

@tab

access to the file was revoked

@end multitable


@code{KQ_FILTER_PROC} filter flags:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{KQ_NOTE_EXIT}

@tab

the process has exited

@item

@code{KQ_NOTE_FORK}

@tab

the process has called `fork()'

@item

@code{KQ_NOTE_EXEC}

@tab

the process has executed a new process

@item

@code{KQ_NOTE_PCTRLMASK}

@tab

internal filter flag

@item

@code{KQ_NOTE_PDATAMASK}

@tab

internal filter flag

@item

@code{KQ_NOTE_TRACK}

@tab

follow a process across `fork()'

@item

@code{KQ_NOTE_CHILD}

@tab

returned on the child process for
`NOTE_TRACK'

@item

@code{KQ_NOTE_TRACKERR}

@tab

unable to attach to a child

@end multitable


@code{KQ_FILTER_NETDEV} filter flags (not available on macOS):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{KQ_NOTE_LINKUP}

@tab

link is up

@item

@code{KQ_NOTE_LINKDOWN}

@tab

link is down

@item

@code{KQ_NOTE_LINKINV}

@tab

link state is invalid

@end multitable

@end deffn

@geindex data (attribut select.kevent)
@anchor{library/select select kevent data}@anchor{343a}
@deffn {Attribut} kevent.data

Filter specific data.
@end deffn

@geindex udata (attribut select.kevent)
@anchor{library/select select kevent udata}@anchor{343b}
@deffn {Attribut} kevent.udata

User defined value.
@end deffn

@node selectors --- High-level I/O multiplexing,signal --- Set handlers for asynchronous events,select --- Waiting for I/O completion,Réseau et communication entre processus
@anchor{library/selectors doc}@anchor{343c}@anchor{library/selectors module-selectors}@anchor{c1}@anchor{library/selectors selectors-high-level-i-o-multiplexing}@anchor{343d}
@subsection @code{selectors} --- High-level I/O multiplexing


@geindex module; selectors


Ajouté dans la version 3.4.


`Source code:' Lib/selectors.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/selectors.py}


__________________________________________________________________


@menu
* Introduction: Introduction<9>. 
* Classes: Classes<4>. 
* Exemples: Exemples<21>. 

@end menu

@node Introduction<9>,Classes<4>,,selectors --- High-level I/O multiplexing
@anchor{library/selectors introduction}@anchor{343e}
@subsubsection Introduction


This module allows high-level and efficient I/O multiplexing, built upon the
@ref{c0,,select} module primitives. Users are encouraged to use this module
instead, unless they want precise control over the OS-level primitives used.

It defines a @ref{343f,,BaseSelector} abstract base class, along with several
concrete implementations (@ref{332e,,KqueueSelector}, @ref{bc3,,EpollSelector}...),
that can be used to wait for I/O readiness notification on multiple file
objects. In the following, "file object" refers to any object with a
@ref{27cf,,fileno()} method, or a raw file descriptor. See @ref{11a0,,file object}.

@ref{3440,,DefaultSelector} is an alias to the most efficient implementation
available on the current platform: this should be the default choice for most
users.

@cartouche
@quotation Note 
The type of file objects supported depends on the platform: on Windows,
sockets are supported, but not pipes, whereas on Unix, both are supported
(some other types may be supported as well, such as fifos or special file
devices).
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item @ref{c0,,select}

Low-level I/O multiplexing module.
@end table


@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@node Classes<4>,Exemples<21>,Introduction<9>,selectors --- High-level I/O multiplexing
@anchor{library/selectors classes}@anchor{3441}
@subsubsection Classes


Classes hierarchy:

@example
BaseSelector
+-- SelectSelector
+-- PollSelector
+-- EpollSelector
+-- DevpollSelector
+-- KqueueSelector
@end example

In the following, `events' is a bitwise mask indicating which I/O events should
be waited for on a given file object. It can be a combination of the modules
constants below:

@quotation


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@geindex EVENT_READ (dans le module selectors)
@anchor{library/selectors selectors EVENT_READ}@anchor{3442}
@deffn {Données} selectors.EVENT_READ
@end deffn

@tab

Available for read

@item

@geindex EVENT_WRITE (dans le module selectors)
@anchor{library/selectors selectors EVENT_WRITE}@anchor{3443}
@deffn {Données} selectors.EVENT_WRITE
@end deffn

@tab

Available for write

@end multitable

@end quotation

@geindex SelectorKey (classe dans selectors)
@anchor{library/selectors selectors SelectorKey}@anchor{3444}
@deffn {Classe} selectors.SelectorKey

A @ref{3444,,SelectorKey} is a @ref{1c5,,namedtuple} used to
associate a file object to its underlying file descriptor, selected event
mask and attached data. It is returned by several @ref{343f,,BaseSelector}
methods.

@geindex fileobj (attribut selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey fileobj}@anchor{3445}
@deffn {Attribut} fileobj

File object registered.
@end deffn

@geindex fd (attribut selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey fd}@anchor{3446}
@deffn {Attribut} fd

Underlying file descriptor.
@end deffn

@geindex events (attribut selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey events}@anchor{3447}
@deffn {Attribut} events

Events that must be waited for on this file object.
@end deffn

@geindex data (attribut selectors.SelectorKey)
@anchor{library/selectors selectors SelectorKey data}@anchor{3448}
@deffn {Attribut} data

Optional opaque data associated to this file object: for example, this
could be used to store a per-client session ID.
@end deffn
@end deffn

@geindex BaseSelector (classe dans selectors)
@anchor{library/selectors selectors BaseSelector}@anchor{343f}
@deffn {Classe} selectors.BaseSelector

A @ref{343f,,BaseSelector} is used to wait for I/O event readiness on multiple
file objects. It supports file stream registration, unregistration, and a
method to wait for I/O events on those streams, with an optional timeout.
It's an abstract base class, so cannot be instantiated. Use
@ref{3440,,DefaultSelector} instead, or one of @ref{332b,,SelectSelector},
@ref{332e,,KqueueSelector} etc. if you want to specifically use an
implementation, and your platform supports it.
@ref{343f,,BaseSelector} and its concrete implementations support the
@ref{5be,,context manager} protocol.

@geindex register() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector register}@anchor{3449}
@deffn {Méthode} abstractmethod register (fileobj, events, data=None)

Register a file object for selection, monitoring it for I/O events.

`fileobj' is the file object to monitor.  It may either be an integer
file descriptor or an object with a @code{fileno()} method.
`events' is a bitwise mask of events to monitor.
`data' is an opaque object.

This returns a new @ref{3444,,SelectorKey} instance, or raises a
@ref{1ff,,ValueError} in case of invalid event mask or file descriptor, or
@ref{33a,,KeyError} if the file object is already registered.
@end deffn

@geindex unregister() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector unregister}@anchor{344a}
@deffn {Méthode} abstractmethod unregister (fileobj)

Unregister a file object from selection, removing it from monitoring. A
file object shall be unregistered prior to being closed.

`fileobj' must be a file object previously registered.

This returns the associated @ref{3444,,SelectorKey} instance, or raises a
@ref{33a,,KeyError} if `fileobj' is not registered.  It will raise
@ref{1ff,,ValueError} if `fileobj' is invalid (e.g. it has no @code{fileno()}
method or its @code{fileno()} method has an invalid return value).
@end deffn

@geindex modify() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector modify}@anchor{bc2}
@deffn {Méthode} modify (fileobj, events, data=None)

Change a registered file object's monitored events or attached data.

This is equivalent to @code{BaseSelector.unregister(fileobj)} followed
by @code{BaseSelector.register(fileobj, events, data)}, except that it
can be implemented more efficiently.

This returns a new @ref{3444,,SelectorKey} instance, or raises a
@ref{1ff,,ValueError} in case of invalid event mask or file descriptor, or
@ref{33a,,KeyError} if the file object is not registered.
@end deffn

@geindex select() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector select}@anchor{344b}
@deffn {Méthode} abstractmethod select (timeout=None)

Wait until some registered file objects become ready, or the timeout
expires.

If @code{timeout > 0}, this specifies the maximum wait time, in seconds.
If @code{timeout <= 0}, the call won't block, and will report the currently
ready file objects.
If `timeout' is @code{None}, the call will block until a monitored file object
becomes ready.

This returns a list of @code{(key, events)} tuples, one for each ready file
object.

`key' is the @ref{3444,,SelectorKey} instance corresponding to a ready file
object.
`events' is a bitmask of events ready on this file object.

@cartouche
@quotation Note 
This method can return before any file object becomes ready or the
timeout has elapsed if the current process receives a signal: in this
case, an empty list will be returned.
@end quotation
@end cartouche


Modifié dans la version 3.5: The selector is now retried with a recomputed timeout when interrupted
by a signal if the signal handler did not raise an exception (see
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale), instead of returning an empty list
of events before the timeout.

@end deffn

@geindex close() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector close}@anchor{344c}
@deffn {Méthode} close ()

Close the selector.

This must be called to make sure that any underlying resource is freed.
The selector shall not be used once it has been closed.
@end deffn

@geindex get_key() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector get_key}@anchor{344d}
@deffn {Méthode} get_key (fileobj)

Return the key associated with a registered file object.

This returns the @ref{3444,,SelectorKey} instance associated to this file
object, or raises @ref{33a,,KeyError} if the file object is not registered.
@end deffn

@geindex get_map() (méthode selectors.BaseSelector)
@anchor{library/selectors selectors BaseSelector get_map}@anchor{344e}
@deffn {Méthode} abstractmethod get_map ()

Return a mapping of file objects to selector keys.

This returns a @ref{8b7,,Mapping} instance mapping
registered file objects to their associated @ref{3444,,SelectorKey}
instance.
@end deffn
@end deffn

@geindex DefaultSelector (classe dans selectors)
@anchor{library/selectors selectors DefaultSelector}@anchor{3440}
@deffn {Classe} selectors.DefaultSelector

The default selector class, using the most efficient implementation
available on the current platform. This should be the default choice for
most users.
@end deffn

@geindex SelectSelector (classe dans selectors)
@anchor{library/selectors selectors SelectSelector}@anchor{332b}
@deffn {Classe} selectors.SelectSelector

@ref{d8d,,select.select()}-based selector.
@end deffn

@geindex PollSelector (classe dans selectors)
@anchor{library/selectors selectors PollSelector}@anchor{bc4}
@deffn {Classe} selectors.PollSelector

@ref{2b36,,select.poll()}-based selector.
@end deffn

@geindex EpollSelector (classe dans selectors)
@anchor{library/selectors selectors EpollSelector}@anchor{bc3}
@deffn {Classe} selectors.EpollSelector

@ref{f7e,,select.epoll()}-based selector.

@geindex fileno() (méthode selectors.EpollSelector)
@anchor{library/selectors selectors EpollSelector fileno}@anchor{344f}
@deffn {Méthode} fileno ()

This returns the file descriptor used by the underlying
@ref{f7e,,select.epoll()} object.
@end deffn
@end deffn

@geindex DevpollSelector (classe dans selectors)
@anchor{library/selectors selectors DevpollSelector}@anchor{bc5}
@deffn {Classe} selectors.DevpollSelector

@ref{f80,,select.devpoll()}-based selector.

@geindex fileno() (méthode selectors.DevpollSelector)
@anchor{library/selectors selectors DevpollSelector fileno}@anchor{3450}
@deffn {Méthode} fileno ()

This returns the file descriptor used by the underlying
@ref{f80,,select.devpoll()} object.
@end deffn


Ajouté dans la version 3.5.

@end deffn

@geindex KqueueSelector (classe dans selectors)
@anchor{library/selectors selectors KqueueSelector}@anchor{332e}
@deffn {Classe} selectors.KqueueSelector

@ref{1657,,select.kqueue()}-based selector.

@geindex fileno() (méthode selectors.KqueueSelector)
@anchor{library/selectors selectors KqueueSelector fileno}@anchor{3451}
@deffn {Méthode} fileno ()

This returns the file descriptor used by the underlying
@ref{1657,,select.kqueue()} object.
@end deffn
@end deffn

@node Exemples<21>,,Classes<4>,selectors --- High-level I/O multiplexing
@anchor{library/selectors examples}@anchor{3452}
@subsubsection Exemples


Here is a simple echo server implementation:

@example
import selectors
import socket

sel = selectors.DefaultSelector()

def accept(sock, mask):
    conn, addr = sock.accept()  # Should be ready
    print('accepted', conn, 'from', addr)
    conn.setblocking(False)
    sel.register(conn, selectors.EVENT_READ, read)

def read(conn, mask):
    data = conn.recv(1000)  # Should be ready
    if data:
        print('echoing', repr(data), 'to', conn)
        conn.send(data)  # Hope it won't block
    else:
        print('closing', conn)
        sel.unregister(conn)
        conn.close()

sock = socket.socket()
sock.bind(('localhost', 1234))
sock.listen(100)
sock.setblocking(False)
sel.register(sock, selectors.EVENT_READ, accept)

while True:
    events = sel.select()
    for key, mask in events:
        callback = key.data
        callback(key.fileobj, mask)
@end example

@node signal --- Set handlers for asynchronous events,mmap --- Memory-mapped file support,selectors --- High-level I/O multiplexing,Réseau et communication entre processus
@anchor{library/signal doc}@anchor{3453}@anchor{library/signal module-signal}@anchor{c5}@anchor{library/signal signal-set-handlers-for-asynchronous-events}@anchor{3454}
@subsection @code{signal} --- Set handlers for asynchronous events


@geindex module; signal

`Source code:' Lib/signal.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/signal.py}


__________________________________________________________________


This module provides mechanisms to use signal handlers in Python.

@menu
* General rules:: 
* Module contents: Module contents<2>. 
* Examples:: 
* Note on SIGPIPE:: 
* Note on Signal Handlers and Exceptions:: 

@end menu

@node General rules,Module contents<2>,,signal --- Set handlers for asynchronous events
@anchor{library/signal general-rules}@anchor{3455}
@subsubsection General rules


The @ref{1114,,signal.signal()} function allows defining custom handlers to be
executed when a signal is received.  A small number of default handlers are
installed: @ref{3456,,SIGPIPE} is ignored (so write errors on pipes and sockets
can be reported as ordinary Python exceptions) and @ref{82e,,SIGINT} is
translated into a @ref{9bf,,KeyboardInterrupt} exception if the parent process
has not changed it.

A handler for a particular signal, once set, remains installed until it is
explicitly reset (Python emulates the BSD style interface regardless of the
underlying implementation), with the exception of the handler for
@ref{2b71,,SIGCHLD}, which follows the underlying implementation.

On WebAssembly platforms, signals are emulated and therefore behave
differently. Several functions and signals are not available on these
platforms.

@menu
* Execution of Python signal handlers:: 
* Signals and threads:: 

@end menu

@node Execution of Python signal handlers,Signals and threads,,General rules
@anchor{library/signal execution-of-python-signal-handlers}@anchor{3457}
@subsubsection Execution of Python signal handlers


A Python signal handler does not get executed inside the low-level (C) signal
handler.  Instead, the low-level signal handler sets a flag which tells the
@ref{3458,,virtual machine} to execute the corresponding Python signal handler
at a later point(for example at the next @ref{185,,bytecode} instruction).
This has consequences:


@itemize *

@item 
It makes little sense to catch synchronous errors like @ref{1cd6,,SIGFPE} or
@ref{1cd5,,SIGSEGV} that are caused by an invalid operation in C code.  Python
will return from the signal handler to the C code, which is likely to raise
the same signal again, causing Python to apparently hang.  From Python 3.3
onwards, you can use the @ref{57,,faulthandler} module to report on synchronous
errors.

@item 
A long-running calculation implemented purely in C (such as regular
expression matching on a large body of text) may run uninterrupted for an
arbitrary amount of time, regardless of any signals received.  The Python
signal handlers will be called when the calculation finishes.

@item 
If the handler raises an exception, it will be raised "out of thin air" in
the main thread. See the @ref{2212,,note below} for a
discussion.
@end itemize

@node Signals and threads,,Execution of Python signal handlers,General rules
@anchor{library/signal id1}@anchor{3459}@anchor{library/signal signals-and-threads}@anchor{345a}
@subsubsection Signals and threads


Python signal handlers are always executed in the main Python thread of the main interpreter,
even if the signal was received in another thread.  This means that signals
can't be used as a means of inter-thread communication.  You can use
the synchronization primitives from the @ref{ec,,threading} module instead.

Besides, only the main thread of the main interpreter is allowed to set a new signal handler.

@node Module contents<2>,Examples,General rules,signal --- Set handlers for asynchronous events
@anchor{library/signal module-contents}@anchor{345b}
@subsubsection Module contents



Modifié dans la version 3.5: signal (SIG*), handler (@ref{17af,,SIG_DFL}, @ref{17ae,,SIG_IGN}) and sigmask
(@ref{345c,,SIG_BLOCK}, @ref{345d,,SIG_UNBLOCK}, @ref{345e,,SIG_SETMASK})
related constants listed below were turned into
@ref{ccd,,enums} (@ref{345f,,Signals}, @ref{3460,,Handlers} and @ref{3461,,Sigmasks} respectively).
@ref{1635,,getsignal()}, @ref{1110,,pthread_sigmask()}, @ref{1112,,sigpending()} and
@ref{1113,,sigwait()} functions return human-readable
@ref{ccd,,enums} as @ref{345f,,Signals} objects.


The signal module defines three enums:

@geindex Signals (classe dans signal)
@anchor{library/signal signal Signals}@anchor{345f}
@deffn {Classe} signal.Signals

@ref{ccd,,enum.IntEnum} collection of SIG* constants and the CTRL_* constants.


Ajouté dans la version 3.5.

@end deffn

@geindex Handlers (classe dans signal)
@anchor{library/signal signal Handlers}@anchor{3460}
@deffn {Classe} signal.Handlers

@ref{ccd,,enum.IntEnum} collection the constants @ref{17af,,SIG_DFL} and @ref{17ae,,SIG_IGN}.


Ajouté dans la version 3.5.

@end deffn

@geindex Sigmasks (classe dans signal)
@anchor{library/signal signal Sigmasks}@anchor{3461}
@deffn {Classe} signal.Sigmasks

@ref{ccd,,enum.IntEnum} collection the constants @ref{345c,,SIG_BLOCK}, @ref{345d,,SIG_UNBLOCK} and @ref{345e,,SIG_SETMASK}.

@ref{1ce0,,Availability}: Unix.

See the man page @code{sigprocmask(2)@footnote{https://manpages.debian.org/sigprocmask(2)}} and
@code{pthread_sigmask(3)@footnote{https://manpages.debian.org/pthread_sigmask(3)}} for further information.


Ajouté dans la version 3.5.

@end deffn

The variables defined in the @ref{c5,,signal} module are:

@geindex SIG_DFL (dans le module signal)
@anchor{library/signal signal SIG_DFL}@anchor{17af}
@deffn {Données} signal.SIG_DFL

This is one of two standard signal handling options; it will simply perform
the default function for the signal.  For example, on most systems the
default action for @code{SIGQUIT} is to dump core and exit, while the
default action for @ref{2b71,,SIGCHLD} is to simply ignore it.
@end deffn

@geindex SIG_IGN (dans le module signal)
@anchor{library/signal signal SIG_IGN}@anchor{17ae}
@deffn {Données} signal.SIG_IGN

This is another standard signal handler, which will simply ignore the given
signal.
@end deffn

@geindex SIGABRT (dans le module signal)
@anchor{library/signal signal SIGABRT}@anchor{1cd7}
@deffn {Données} signal.SIGABRT

Abort signal from @code{abort(3)@footnote{https://manpages.debian.org/abort(3)}}.
@end deffn

@geindex SIGALRM (dans le module signal)
@anchor{library/signal signal SIGALRM}@anchor{3462}
@deffn {Données} signal.SIGALRM

Timer signal from @code{alarm(2)@footnote{https://manpages.debian.org/alarm(2)}}.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGBREAK (dans le module signal)
@anchor{library/signal signal SIGBREAK}@anchor{3463}
@deffn {Données} signal.SIGBREAK

Interrupt from keyboard (CTRL + BREAK).

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex SIGBUS (dans le module signal)
@anchor{library/signal signal SIGBUS}@anchor{1cd8}
@deffn {Données} signal.SIGBUS

Bus error (bad memory access).

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGCHLD (dans le module signal)
@anchor{library/signal signal SIGCHLD}@anchor{2b71}
@deffn {Données} signal.SIGCHLD

Child process stopped or terminated.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGCLD (dans le module signal)
@anchor{library/signal signal SIGCLD}@anchor{3464}
@deffn {Données} signal.SIGCLD

Alias to @ref{2b71,,SIGCHLD}.

@ref{1ce0,,Availability}: not macOS.
@end deffn

@geindex SIGCONT (dans le module signal)
@anchor{library/signal signal SIGCONT}@anchor{2b7f}
@deffn {Données} signal.SIGCONT

Continue the process if it is currently stopped

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGFPE (dans le module signal)
@anchor{library/signal signal SIGFPE}@anchor{1cd6}
@deffn {Données} signal.SIGFPE

Floating-point exception. For example, division by zero.


@subsubheading Voir aussi


@ref{932,,ZeroDivisionError} is raised when the second argument of a division
or modulo operation is zero.

@end deffn

@geindex SIGHUP (dans le module signal)
@anchor{library/signal signal SIGHUP}@anchor{3465}
@deffn {Données} signal.SIGHUP

Hangup detected on controlling terminal or death of controlling process.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGILL (dans le module signal)
@anchor{library/signal signal SIGILL}@anchor{1cd9}
@deffn {Données} signal.SIGILL

Illegal instruction.
@end deffn

@geindex SIGINT (dans le module signal)
@anchor{library/signal signal SIGINT}@anchor{82e}
@deffn {Données} signal.SIGINT

Interrupt from keyboard (CTRL + C).

Default action is to raise @ref{9bf,,KeyboardInterrupt}.
@end deffn

@geindex SIGKILL (dans le module signal)
@anchor{library/signal signal SIGKILL}@anchor{3466}
@deffn {Données} signal.SIGKILL

Kill signal.

It cannot be caught, blocked, or ignored.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGPIPE (dans le module signal)
@anchor{library/signal signal SIGPIPE}@anchor{3456}
@deffn {Données} signal.SIGPIPE

Broken pipe: write to pipe with no readers.

Default action is to ignore the signal.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGSEGV (dans le module signal)
@anchor{library/signal signal SIGSEGV}@anchor{1cd5}
@deffn {Données} signal.SIGSEGV

Segmentation fault: invalid memory reference.
@end deffn

@geindex SIGSTKFLT (dans le module signal)
@anchor{library/signal signal SIGSTKFLT}@anchor{17f2}
@deffn {Données} signal.SIGSTKFLT

@quotation

Stack fault on coprocessor. The Linux kernel does not raise this signal: it
can only be raised in user space.
@end quotation

@ref{1ce0,,Availability}: Linux.

On architectures where the signal is available. See
the man page @code{signal(7)@footnote{https://manpages.debian.org/signal(7)}} for further information.


Ajouté dans la version 3.11.

@end deffn

@geindex SIGTERM (dans le module signal)
@anchor{library/signal signal SIGTERM}@anchor{1396}
@deffn {Données} signal.SIGTERM

Termination signal.
@end deffn

@geindex SIGUSR1 (dans le module signal)
@anchor{library/signal signal SIGUSR1}@anchor{3467}
@deffn {Données} signal.SIGUSR1

User-defined signal 1.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGUSR2 (dans le module signal)
@anchor{library/signal signal SIGUSR2}@anchor{3468}
@deffn {Données} signal.SIGUSR2

User-defined signal 2.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex SIGWINCH (dans le module signal)
@anchor{library/signal signal SIGWINCH}@anchor{3469}
@deffn {Données} signal.SIGWINCH

Window resize signal.

@ref{1ce0,,Availability}: Unix.
@end deffn


@deffn {Données} SIG*

All the signal numbers are defined symbolically.  For example, the hangup signal
is defined as @ref{3465,,signal.SIGHUP}; the variable names are identical to the
names used in C programs, as found in @code{<signal.h>}.  The Unix man page for
'@code{signal()}' lists the existing signals (on some systems this is
@code{signal(2)@footnote{https://manpages.debian.org/signal(2)}}, on others the list is in @code{signal(7)@footnote{https://manpages.debian.org/signal(7)}}). Note that
not all systems define the same set of signal names; only those names defined by
the system are defined by this module.
@end deffn

@geindex CTRL_C_EVENT (dans le module signal)
@anchor{library/signal signal CTRL_C_EVENT}@anchor{133f}
@deffn {Données} signal.CTRL_C_EVENT

The signal corresponding to the @code{Ctrl+C} keystroke event. This signal can
only be used with @ref{133e,,os.kill()}.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.2.

@end deffn

@geindex CTRL_BREAK_EVENT (dans le module signal)
@anchor{library/signal signal CTRL_BREAK_EVENT}@anchor{1340}
@deffn {Données} signal.CTRL_BREAK_EVENT

The signal corresponding to the @code{Ctrl+Break} keystroke event. This signal can
only be used with @ref{133e,,os.kill()}.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.2.

@end deffn

@geindex NSIG (dans le module signal)
@anchor{library/signal signal NSIG}@anchor{178c}
@deffn {Données} signal.NSIG

One more than the number of the highest signal number.
Use @ref{346a,,valid_signals()} to get valid signal numbers.
@end deffn

@geindex ITIMER_REAL (dans le module signal)
@anchor{library/signal signal ITIMER_REAL}@anchor{346b}
@deffn {Données} signal.ITIMER_REAL

Decrements interval timer in real time, and delivers @ref{3462,,SIGALRM} upon
expiration.
@end deffn

@geindex ITIMER_VIRTUAL (dans le module signal)
@anchor{library/signal signal ITIMER_VIRTUAL}@anchor{346c}
@deffn {Données} signal.ITIMER_VIRTUAL

Decrements interval timer only when the process is executing, and delivers
SIGVTALRM upon expiration.
@end deffn

@geindex ITIMER_PROF (dans le module signal)
@anchor{library/signal signal ITIMER_PROF}@anchor{346d}
@deffn {Données} signal.ITIMER_PROF

Decrements interval timer both when the process executes and when the
system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL,
this timer is usually used to profile the time spent by the application
in user and kernel space. SIGPROF is delivered upon expiration.
@end deffn

@geindex SIG_BLOCK (dans le module signal)
@anchor{library/signal signal SIG_BLOCK}@anchor{345c}
@deffn {Données} signal.SIG_BLOCK

A possible value for the `how' parameter to @ref{1110,,pthread_sigmask()}
indicating that signals are to be blocked.


Ajouté dans la version 3.3.

@end deffn

@geindex SIG_UNBLOCK (dans le module signal)
@anchor{library/signal signal SIG_UNBLOCK}@anchor{345d}
@deffn {Données} signal.SIG_UNBLOCK

A possible value for the `how' parameter to @ref{1110,,pthread_sigmask()}
indicating that signals are to be unblocked.


Ajouté dans la version 3.3.

@end deffn

@geindex SIG_SETMASK (dans le module signal)
@anchor{library/signal signal SIG_SETMASK}@anchor{345e}
@deffn {Données} signal.SIG_SETMASK

A possible value for the `how' parameter to @ref{1110,,pthread_sigmask()}
indicating that the signal mask is to be replaced.


Ajouté dans la version 3.3.

@end deffn

The @ref{c5,,signal} module defines one exception:

@geindex ItimerError
@anchor{library/signal signal ItimerError}@anchor{346e}
@deffn {Exception} signal.ItimerError

Raised to signal an error from the underlying @ref{346f,,setitimer()} or
@ref{3470,,getitimer()} implementation. Expect this error if an invalid
interval timer or a negative time is passed to @ref{346f,,setitimer()}.
This error is a subtype of @ref{40d,,OSError}.


Ajouté dans la version 3.3: This error used to be a subtype of @ref{103b,,IOError}, which is now an
alias of @ref{40d,,OSError}.

@end deffn

The @ref{c5,,signal} module defines the following functions:

@geindex alarm() (dans le module signal)
@anchor{library/signal signal alarm}@anchor{3471}
@deffn {Fonction} signal.alarm (time)

If `time' is non-zero, this function requests that a @ref{3462,,SIGALRM} signal be
sent to the process in `time' seconds. Any previously scheduled alarm is
canceled (only one alarm can be scheduled at any time).  The returned value is
then the number of seconds before any previously set alarm was to have been
delivered. If `time' is zero, no alarm is scheduled, and any scheduled alarm is
canceled.  If the return value is zero, no alarm is currently scheduled.

@ref{1ce0,,Availability}: Unix.

See the man page @code{alarm(2)@footnote{https://manpages.debian.org/alarm(2)}} for further information.
@end deffn

@geindex getsignal() (dans le module signal)
@anchor{library/signal signal getsignal}@anchor{1635}
@deffn {Fonction} signal.getsignal (signalnum)

Return the current signal handler for the signal `signalnum'. The returned value
may be a callable Python object, or one of the special values
@ref{17ae,,signal.SIG_IGN}, @ref{17af,,signal.SIG_DFL} or @ref{660,,None}.  Here,
@ref{17ae,,signal.SIG_IGN} means that the signal was previously ignored,
@ref{17af,,signal.SIG_DFL} means that the default way of handling the signal was
previously in use, and @code{None} means that the previous signal handler was not
installed from Python.
@end deffn

@geindex strsignal() (dans le module signal)
@anchor{library/signal signal strsignal}@anchor{19cc}
@deffn {Fonction} signal.strsignal (signalnum)

Returns the description of signal `signalnum', such as "Interrupt"
for @ref{82e,,SIGINT}. Returns @ref{660,,None} if `signalnum' has no
description. Raises @ref{1ff,,ValueError} if `signalnum' is invalid.


Ajouté dans la version 3.8.

@end deffn

@geindex valid_signals() (dans le module signal)
@anchor{library/signal signal valid_signals}@anchor{346a}
@deffn {Fonction} signal.valid_signals ()

Return the set of valid signal numbers on this platform.  This can be
less than @code{range(1, NSIG)} if some signals are reserved by the system
for internal use.


Ajouté dans la version 3.8.

@end deffn

@geindex pause() (dans le module signal)
@anchor{library/signal signal pause}@anchor{3472}
@deffn {Fonction} signal.pause ()

Cause the process to sleep until a signal is received; the appropriate handler
will then be called.  Returns nothing.

@ref{1ce0,,Availability}: Unix.

See the man page @code{signal(2)@footnote{https://manpages.debian.org/signal(2)}} for further information.

See also @ref{1113,,sigwait()}, @ref{d98,,sigwaitinfo()}, @ref{d97,,sigtimedwait()} and
@ref{1112,,sigpending()}.
@end deffn

@geindex raise_signal() (dans le module signal)
@anchor{library/signal signal raise_signal}@anchor{1790}
@deffn {Fonction} signal.raise_signal (signum)

Sends a signal to the calling process. Returns nothing.


Ajouté dans la version 3.8.

@end deffn

@geindex pidfd_send_signal() (dans le module signal)
@anchor{library/signal signal pidfd_send_signal}@anchor{918}
@deffn {Fonction} signal.pidfd_send_signal (pidfd, sig, siginfo=None, flags=0)

Send signal `sig' to the process referred to by file descriptor `pidfd'.
Python does not currently support the `siginfo' parameter; it must be
@code{None}.  The `flags' argument is provided for future extensions; no flag
values are currently defined.

See the @code{pidfd_send_signal(2)@footnote{https://manpages.debian.org/pidfd_send_signal(2)}} man page for more information.

@ref{1ce0,,Availability}: Linux >= 5.1, Android >= @ref{b78,,build-time} API level 31


Ajouté dans la version 3.9.

@end deffn

@geindex pthread_kill() (dans le module signal)
@anchor{library/signal signal pthread_kill}@anchor{1111}
@deffn {Fonction} signal.pthread_kill (thread_id, signalnum)

Send the signal `signalnum' to the thread `thread_id', another thread in the
same process as the caller.  The target thread can be executing any code
(Python or not).  However, if the target thread is executing the Python
interpreter, the Python signal handlers will be @ref{345a,,executed by the main thread of the main interpreter}.  Therefore, the only point of sending a
signal to a particular Python thread would be to force a running system call
to fail with @ref{d75,,InterruptedError}.

Use @ref{113a,,threading.get_ident()} or the @ref{2bc7,,ident}
attribute of @ref{939,,threading.Thread} objects to get a suitable value
for `thread_id'.

If `signalnum' is 0, then no signal is sent, but error checking is still
performed; this can be used to check if the target thread is still running.

Raises an @ref{1848,,auditing event} @code{signal.pthread_kill} with arguments @code{thread_id}, @code{signalnum}.

@ref{1ce0,,Availability}: Unix.

See the man page @code{pthread_kill(3)@footnote{https://manpages.debian.org/pthread_kill(3)}} for further  information.

See also @ref{133e,,os.kill()}.


Ajouté dans la version 3.3.

@end deffn

@geindex pthread_sigmask() (dans le module signal)
@anchor{library/signal signal pthread_sigmask}@anchor{1110}
@deffn {Fonction} signal.pthread_sigmask (how, mask)

Fetch and/or change the signal mask of the calling thread.  The signal mask
is the set of signals whose delivery is currently blocked for the caller.
Return the old signal mask as a set of signals.

The behavior of the call is dependent on the value of `how', as follows.


@itemize *

@item 
@ref{345c,,SIG_BLOCK}: The set of blocked signals is the union of the current
set and the `mask' argument.

@item 
@ref{345d,,SIG_UNBLOCK}: The signals in `mask' are removed from the current
set of blocked signals.  It is permissible to attempt to unblock a
signal which is not blocked.

@item 
@ref{345e,,SIG_SETMASK}: The set of blocked signals is set to the `mask'
argument.
@end itemize

`mask' is a set of signal numbers (e.g. @{@ref{82e,,signal.SIGINT},
@ref{1396,,signal.SIGTERM}@}). Use @ref{346a,,valid_signals()} for a full
mask including all signals.

For example, @code{signal.pthread_sigmask(signal.SIG_BLOCK, [])} reads the
signal mask of the calling thread.

@ref{3466,,SIGKILL} and @code{SIGSTOP} cannot be blocked.

@ref{1ce0,,Availability}: Unix.

See the man page @code{sigprocmask(2)@footnote{https://manpages.debian.org/sigprocmask(2)}} and
@code{pthread_sigmask(3)@footnote{https://manpages.debian.org/pthread_sigmask(3)}} for further information.

See also @ref{3472,,pause()}, @ref{1112,,sigpending()} and @ref{1113,,sigwait()}.


Ajouté dans la version 3.3.

@end deffn

@geindex setitimer() (dans le module signal)
@anchor{library/signal signal setitimer}@anchor{346f}
@deffn {Fonction} signal.setitimer (which, seconds, interval=0.0)

Sets given interval timer (one of @ref{346b,,signal.ITIMER_REAL},
@ref{346c,,signal.ITIMER_VIRTUAL} or @ref{346d,,signal.ITIMER_PROF}) specified
by `which' to fire after `seconds' (float is accepted, different from
@ref{3471,,alarm()}) and after that every `interval' seconds (if `interval'
is non-zero). The interval timer specified by `which' can be cleared by
setting `seconds' to zero.

When an interval timer fires, a signal is sent to the process.
The signal sent is dependent on the timer being used;
@ref{346b,,signal.ITIMER_REAL} will deliver @ref{3462,,SIGALRM},
@ref{346c,,signal.ITIMER_VIRTUAL} sends @code{SIGVTALRM},
and @ref{346d,,signal.ITIMER_PROF} will deliver @code{SIGPROF}.

The old values are returned as a tuple: (delay, interval).

Attempting to pass an invalid interval timer will cause an
@ref{346e,,ItimerError}.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex getitimer() (dans le module signal)
@anchor{library/signal signal getitimer}@anchor{3470}
@deffn {Fonction} signal.getitimer (which)

Returns current value of a given interval timer specified by `which'.

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex set_wakeup_fd() (dans le module signal)
@anchor{library/signal signal set_wakeup_fd}@anchor{b5e}
@deffn {Fonction} signal.set_wakeup_fd (fd, *, warn_on_full_buffer=True)

Set the wakeup file descriptor to `fd'.  When a signal is received, the
signal number is written as a single byte into the fd.  This can be used by
a library to wakeup a poll or select call, allowing the signal to be fully
processed.

The old wakeup fd is returned (or -1 if file descriptor wakeup was not
enabled).  If `fd' is -1, file descriptor wakeup is disabled.
If not -1, `fd' must be non-blocking.  It is up to the library to remove
any bytes from `fd' before calling poll or select again.

When threads are enabled, this function can only be called
from @ref{345a,,the main thread of the main interpreter};
attempting to call it from other threads will cause a @ref{1ff,,ValueError}
exception to be raised.

There are two common ways to use this function. In both approaches,
you use the fd to wake up when a signal arrives, but then they
differ in how they determine `which' signal or signals have
arrived.

In the first approach, we read the data out of the fd's buffer, and
the byte values give you the signal numbers. This is simple, but in
rare cases it can run into a problem: generally the fd will have a
limited amount of buffer space, and if too many signals arrive too
quickly, then the buffer may become full, and some signals may be
lost. If you use this approach, then you should set
@code{warn_on_full_buffer=True}, which will at least cause a warning
to be printed to stderr when signals are lost.

In the second approach, we use the wakeup fd `only' for wakeups,
and ignore the actual byte values. In this case, all we care about
is whether the fd's buffer is empty or non-empty; a full buffer
doesn't indicate a problem at all. If you use this approach, then
you should set @code{warn_on_full_buffer=False}, so that your users
are not confused by spurious warning messages.


Modifié dans la version 3.5: On Windows, the function now also supports socket handles.



Modifié dans la version 3.7: Added @code{warn_on_full_buffer} parameter.

@end deffn

@geindex siginterrupt() (dans le module signal)
@anchor{library/signal signal siginterrupt}@anchor{1115}
@deffn {Fonction} signal.siginterrupt (signalnum, flag)

Change system call restart behaviour: if `flag' is @ref{b25,,False}, system
calls will be restarted when interrupted by signal `signalnum', otherwise
system calls will be interrupted.  Returns nothing.

@ref{1ce0,,Availability}: Unix.

See the man page @code{siginterrupt(3)@footnote{https://manpages.debian.org/siginterrupt(3)}} for further information.

Note that installing a signal handler with @ref{c5,,signal()} will reset the
restart behaviour to interruptible by implicitly calling
@code{siginterrupt()} with a true `flag' value for the given signal.
@end deffn

@geindex signal() (dans le module signal)
@anchor{library/signal signal signal}@anchor{1114}
@deffn {Fonction} signal.signal (signalnum, handler)

Set the handler for signal `signalnum' to the function `handler'.  `handler' can
be a callable Python object taking two arguments (see below), or one of the
special values @ref{17ae,,signal.SIG_IGN} or @ref{17af,,signal.SIG_DFL}.  The previous
signal handler will be returned (see the description of @ref{1635,,getsignal()}
above).  (See the Unix man page @code{signal(2)@footnote{https://manpages.debian.org/signal(2)}} for further information.)

When threads are enabled, this function can only be called
from @ref{345a,,the main thread of the main interpreter};
attempting to call it from other threads will cause a @ref{1ff,,ValueError}
exception to be raised.

The `handler' is called with two arguments: the signal number and the current
stack frame (@code{None} or a frame object; for a description of frame objects,
see the @ref{6ca,,description in the type hierarchy} or see the
attribute descriptions in the @ref{7d,,inspect} module).

On Windows, @ref{c5,,signal()} can only be called with @ref{1cd7,,SIGABRT},
@ref{1cd6,,SIGFPE}, @ref{1cd9,,SIGILL}, @ref{82e,,SIGINT}, @ref{1cd5,,SIGSEGV},
@ref{1396,,SIGTERM}, or @ref{3463,,SIGBREAK}.
A @ref{1ff,,ValueError} will be raised in any other case.
Note that not all systems define the same set of signal names; an
@ref{343,,AttributeError} will be raised if a signal name is not defined as
@code{SIG*} module level constant.
@end deffn

@geindex sigpending() (dans le module signal)
@anchor{library/signal signal sigpending}@anchor{1112}
@deffn {Fonction} signal.sigpending ()

Examine the set of signals that are pending for delivery to the calling
thread (i.e., the signals which have been raised while blocked).  Return the
set of the pending signals.

@ref{1ce0,,Availability}: Unix.

See the man page @code{sigpending(2)@footnote{https://manpages.debian.org/sigpending(2)}} for further information.

See also @ref{3472,,pause()}, @ref{1110,,pthread_sigmask()} and @ref{1113,,sigwait()}.


Ajouté dans la version 3.3.

@end deffn

@geindex sigwait() (dans le module signal)
@anchor{library/signal signal sigwait}@anchor{1113}
@deffn {Fonction} signal.sigwait (sigset)

Suspend execution of the calling thread until the delivery of one of the
signals specified in the signal set `sigset'.  The function accepts the signal
(removes it from the pending list of signals), and returns the signal number.

@ref{1ce0,,Availability}: Unix.

See the man page @code{sigwait(3)@footnote{https://manpages.debian.org/sigwait(3)}} for further information.

See also @ref{3472,,pause()}, @ref{1110,,pthread_sigmask()}, @ref{1112,,sigpending()},
@ref{d98,,sigwaitinfo()} and @ref{d97,,sigtimedwait()}.


Ajouté dans la version 3.3.

@end deffn

@geindex sigwaitinfo() (dans le module signal)
@anchor{library/signal signal sigwaitinfo}@anchor{d98}
@deffn {Fonction} signal.sigwaitinfo (sigset)

Suspend execution of the calling thread until the delivery of one of the
signals specified in the signal set `sigset'.  The function accepts the
signal and removes it from the pending list of signals. If one of the
signals in `sigset' is already pending for the calling thread, the function
will return immediately with information about that signal. The signal
handler is not called for the delivered signal. The function raises an
@ref{d75,,InterruptedError} if it is interrupted by a signal that is not in
`sigset'.

The return value is an object representing the data contained in the
@code{siginfo_t} structure, namely: @code{si_signo}, @code{si_code},
@code{si_errno}, @code{si_pid}, @code{si_uid}, @code{si_status},
@code{si_band}.

@ref{1ce0,,Availability}: Unix.

See the man page @code{sigwaitinfo(2)@footnote{https://manpages.debian.org/sigwaitinfo(2)}} for further information.

See also @ref{3472,,pause()}, @ref{1113,,sigwait()} and @ref{d97,,sigtimedwait()}.


Ajouté dans la version 3.3.



Modifié dans la version 3.5: The function is now retried if interrupted by a signal not in `sigset'
and the signal handler does not raise an exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for
the rationale).

@end deffn

@geindex sigtimedwait() (dans le module signal)
@anchor{library/signal signal sigtimedwait}@anchor{d97}
@deffn {Fonction} signal.sigtimedwait (sigset, timeout)

Like @ref{d98,,sigwaitinfo()}, but takes an additional `timeout' argument
specifying a timeout. If `timeout' is specified as @code{0}, a poll is
performed. Returns @ref{660,,None} if a timeout occurs.

@ref{1ce0,,Availability}: Unix.

See the man page @code{sigtimedwait(2)@footnote{https://manpages.debian.org/sigtimedwait(2)}} for further information.

See also @ref{3472,,pause()}, @ref{1113,,sigwait()} and @ref{d98,,sigwaitinfo()}.


Ajouté dans la version 3.3.



Modifié dans la version 3.5: The function is now retried with the recomputed `timeout' if interrupted
by a signal not in `sigset' and the signal handler does not raise an
exception (see 
@geindex Python Enhancement Proposals; PEP 475
PEP 475@footnote{https://peps.python.org/pep-0475/} for the rationale).

@end deffn

@node Examples,Note on SIGPIPE,Module contents<2>,signal --- Set handlers for asynchronous events
@anchor{library/signal examples}@anchor{3473}@anchor{library/signal signal-example}@anchor{3474}
@subsubsection Examples


Here is a minimal example program. It uses the @ref{3471,,alarm()} function to limit
the time spent waiting to open a file; this is useful if the file is for a
serial device that may not be turned on, which would normally cause the
@ref{d7f,,os.open()} to hang indefinitely.  The solution is to set a 5-second alarm
before opening the file; if the operation takes too long, the alarm signal will
be sent, and the handler raises an exception.

@example
import signal, os

def handler(signum, frame):
    signame = signal.Signals(signum).name
    print(f'Signal handler called with signal @{signame@} (@{signum@})')
    raise OSError("Couldn't open device!")

# Set the signal handler and a 5-second alarm
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)

# This open() may hang indefinitely
fd = os.open('/dev/ttyS0', os.O_RDWR)

signal.alarm(0)          # Disable the alarm
@end example

@node Note on SIGPIPE,Note on Signal Handlers and Exceptions,Examples,signal --- Set handlers for asynchronous events
@anchor{library/signal note-on-sigpipe}@anchor{3475}
@subsubsection Note on SIGPIPE


Piping output of your program to tools like @code{head(1)@footnote{https://manpages.debian.org/head(1)}} will
cause a @ref{3456,,SIGPIPE} signal to be sent to your process when the receiver
of its standard output closes early.  This results in an exception
like @code{BrokenPipeError: [Errno 32] Broken pipe}.  To handle this
case, wrap your entry point to catch this exception as follows:

@example
import os
import sys

def main():
    try:
        # simulate large output (your code replaces this loop)
        for x in range(10000):
            print("y")
        # flush output here to force SIGPIPE to be triggered
        # while inside this try block.
        sys.stdout.flush()
    except BrokenPipeError:
        # Python flushes standard streams on exit; redirect remaining output
        # to devnull to avoid another BrokenPipeError at shutdown
        devnull = os.open(os.devnull, os.O_WRONLY)
        os.dup2(devnull, sys.stdout.fileno())
        sys.exit(1)  # Python exits with error code 1 on EPIPE

if __name__ == '__main__':
    main()
@end example

Do not set @ref{3456,,SIGPIPE}'s disposition to @ref{17af,,SIG_DFL} in
order to avoid @ref{1045,,BrokenPipeError}.  Doing that would cause
your program to exit unexpectedly whenever any socket
connection is interrupted while your program is still writing to
it.

@node Note on Signal Handlers and Exceptions,,Note on SIGPIPE,signal --- Set handlers for asynchronous events
@anchor{library/signal handlers-and-exceptions}@anchor{2212}@anchor{library/signal note-on-signal-handlers-and-exceptions}@anchor{3476}
@subsubsection Note on Signal Handlers and Exceptions


If a signal handler raises an exception, the exception will be propagated to
the main thread and may be raised after any @ref{185,,bytecode} instruction. Most
notably, a @ref{9bf,,KeyboardInterrupt} may appear at any point during execution.
Most Python code, including the standard library, cannot be made robust against
this, and so a @ref{9bf,,KeyboardInterrupt} (or any other exception resulting from
a signal handler) may on rare occasions put the program in an unexpected state.

To illustrate this issue, consider the following code:

@example
class SpamContext:
    def __init__(self):
        self.lock = threading.Lock()

    def __enter__(self):
        # If KeyboardInterrupt occurs here, everything is fine
        self.lock.acquire()
        # If KeyboardInterrupt occurs here, __exit__ will not be called
        ...
        # KeyboardInterrupt could occur just before the function returns

    def __exit__(self, exc_type, exc_val, exc_tb):
        ...
        self.lock.release()
@end example

For many programs, especially those that merely want to exit on
@ref{9bf,,KeyboardInterrupt}, this is not a problem, but applications that are
complex or require high reliability should avoid raising exceptions from signal
handlers. They should also avoid catching @ref{9bf,,KeyboardInterrupt} as a means
of gracefully shutting down.  Instead, they should install their own
@ref{82e,,SIGINT} handler. Below is an example of an HTTP server that avoids
@ref{9bf,,KeyboardInterrupt}:

@example
import signal
import socket
from selectors import DefaultSelector, EVENT_READ
from http.server import HTTPServer, SimpleHTTPRequestHandler

interrupt_read, interrupt_write = socket.socketpair()

def handler(signum, frame):
    print('Signal handler called with signal', signum)
    interrupt_write.send(b'\0')
signal.signal(signal.SIGINT, handler)

def serve_forever(httpd):
    sel = DefaultSelector()
    sel.register(interrupt_read, EVENT_READ)
    sel.register(httpd, EVENT_READ)

    while True:
        for key, _ in sel.select():
            if key.fileobj == interrupt_read:
                interrupt_read.recv(1)
                return
            if key.fileobj == httpd:
                httpd.handle_request()

print("Serving on port 8000")
httpd = HTTPServer(('@w{'}, 8000), SimpleHTTPRequestHandler)
serve_forever(httpd)
print("Shutdown...")
@end example

@node mmap --- Memory-mapped file support,,signal --- Set handlers for asynchronous events,Réseau et communication entre processus
@anchor{library/mmap doc}@anchor{3477}@anchor{library/mmap mmap-memory-mapped-file-support}@anchor{3478}@anchor{library/mmap module-mmap}@anchor{8f}
@subsection @code{mmap} --- Memory-mapped file support


@geindex module; mmap


__________________________________________________________________


@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Memory-mapped file objects behave like both @ref{528,,bytearray} and like
@ref{11a0,,file objects}.  You can use mmap objects in most places
where @ref{528,,bytearray} are expected; for example, you can use the @ref{b8,,re}
module to search through a memory-mapped file.  You can also change a single
byte by doing @code{obj[index] = 97}, or change a subsequence by assigning to a
slice: @code{obj[i1:i2] = b'...'}.  You can also read and write data starting at
the current file position, and @code{seek()} through the file to different positions.

A memory-mapped file is created by the @ref{208,,mmap} constructor, which is
different on Unix and on Windows.  In either case you must provide a file
descriptor for a file opened for update. If you wish to map an existing Python
file object, use its @ref{27cf,,fileno()} method to obtain the correct value for the
`fileno' parameter.  Otherwise, you can open the file using the
@ref{d7f,,os.open()} function, which returns a file descriptor directly (the file
still needs to be closed when done).

@cartouche
@quotation Note 
If you want to create a memory-mapping for a writable, buffered file, you
should @ref{2b9f,,flush()} the file first.  This is necessary to ensure
that local modifications to the buffers are actually available to the
mapping.
@end quotation
@end cartouche

For both the Unix and Windows versions of the constructor, `access' may be
specified as an optional keyword parameter. `access' accepts one of four
values: @code{ACCESS_READ}, @code{ACCESS_WRITE}, or @code{ACCESS_COPY} to
specify read-only, write-through or copy-on-write memory respectively, or
@code{ACCESS_DEFAULT} to defer to `prot'.  `access' can be used on both Unix
and Windows.  If `access' is not specified, Windows mmap returns a
write-through mapping.  The initial memory values for all three access types
are taken from the specified file.  Assignment to an @code{ACCESS_READ}
memory map raises a @ref{522,,TypeError} exception.  Assignment to an
@code{ACCESS_WRITE} memory map affects both memory and the underlying file.
Assignment to an @code{ACCESS_COPY} memory map affects memory but does not
update the underlying file.


Modifié dans la version 3.7: Added @code{ACCESS_DEFAULT} constant.


To map anonymous memory, -1 should be passed as the fileno along with the length.

@geindex mmap (classe dans mmap)
@anchor{library/mmap mmap mmap}@anchor{208}
@deffn {Classe} mmap.mmap (fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)

`(Windows version)' Maps `length' bytes from the file specified by the
file handle `fileno', and creates a mmap object.  If `length' is larger
than the current size of the file, the file is extended to contain `length'
bytes.  If `length' is @code{0}, the maximum length of the map is the current
size of the file, except that if the file is empty Windows raises an
exception (you cannot create an empty mapping on Windows).

`tagname', if specified and not @code{None}, is a string giving a tag name for
the mapping.  Windows allows you to have many different mappings against
the same file.  If you specify the name of an existing tag, that tag is
opened, otherwise a new tag of this name is created.  If this parameter is
omitted or @code{None}, the mapping is created without a name.  Avoiding the
use of the `tagname' parameter will assist in keeping your code portable
between Unix and Windows.

`offset' may be specified as a non-negative integer offset. mmap references
will be relative to the offset from the beginning of the file. `offset'
defaults to 0.  `offset' must be a multiple of the @code{ALLOCATIONGRANULARITY}.

Raises an @ref{1848,,auditing event} @code{mmap.__new__} with arguments @code{fileno}, @code{length}, @code{access}, @code{offset}.
@end deffn


@deffn {Classe} mmap.mmap (fileno, length, flags=MAP_SHARED, prot=PROT_WRITE | PROT_READ, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)

`(Unix version)' Maps `length' bytes from the file specified by the file
descriptor `fileno', and returns a mmap object.  If `length' is @code{0}, the
maximum length of the map will be the current size of the file when
@ref{208,,mmap} is called.

`flags' specifies the nature of the mapping. @ref{3479,,MAP_PRIVATE} creates a
private copy-on-write mapping, so changes to the contents of the mmap
object will be private to this process, and @ref{347a,,MAP_SHARED} creates a
mapping that's shared with all other processes mapping the same areas of
the file.  The default value is @ref{347a,,MAP_SHARED}. Some systems have
additional possible flags with the full list specified in
@ref{347b,,MAP_* constants}.

`prot', if specified, gives the desired memory protection; the two most
useful values are @code{PROT_READ} and @code{PROT_WRITE}, to specify
that the pages may be read or written.  `prot' defaults to
@code{PROT_READ | PROT_WRITE}.

`access' may be specified in lieu of `flags' and `prot' as an optional
keyword parameter.  It is an error to specify both `flags', `prot' and
`access'.  See the description of `access' above for information on how to
use this parameter.

`offset' may be specified as a non-negative integer offset. mmap references
will be relative to the offset from the beginning of the file. `offset'
defaults to 0. `offset' must be a multiple of @code{ALLOCATIONGRANULARITY}
which is equal to @code{PAGESIZE} on Unix systems.

If `trackfd' is @code{False}, the file descriptor specified by `fileno' will
not be duplicated, and the resulting @code{mmap} object will not
be associated with the map's underlying file.
This means that the @ref{347c,,size()} and @ref{347d,,resize()}
methods will fail.
This mode is useful to limit the number of open file descriptors.

To ensure validity of the created memory mapping the file specified
by the descriptor `fileno' is internally automatically synchronized
with the physical backing store on macOS.


Modifié dans la version 3.13: The `trackfd' parameter was added.


This example shows a simple way of using @ref{208,,mmap}:

@example
import mmap

# write a simple example file
with open("hello.txt", "wb") as f:
    f.write(b"Hello Python!\n")

with open("hello.txt", "r+b") as f:
    # memory-map the file, size 0 means whole file
    mm = mmap.mmap(f.fileno(), 0)
    # read content via standard file methods
    print(mm.readline())  # prints b"Hello Python!\n"
    # read content via slice notation
    print(mm[:5])  # prints b"Hello"
    # update content using slice notation;
    # note that new content must have same size
    mm[6:] = b" world!\n"
    # ... and read again using standard file methods
    mm.seek(0)
    print(mm.readline())  # prints b"Hello  world!\n"
    # close the map
    mm.close()
@end example

@ref{208,,mmap} can also be used as a context manager in a @ref{5bc,,with}
statement:

@example
import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")
@end example


Ajouté dans la version 3.2: Context manager support.


The next example demonstrates how to create an anonymous map and exchange
data between the parent and child processes:

@example
import mmap
import os

mm = mmap.mmap(-1, 13)
mm.write(b"Hello world!")

pid = os.fork()

if pid == 0:  # In a child process
    mm.seek(0)
    print(mm.readline())

    mm.close()
@end example

Raises an @ref{1848,,auditing event} @code{mmap.__new__} with arguments @code{fileno}, @code{length}, @code{access}, @code{offset}.

Memory-mapped file objects support the following methods:

@geindex close() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap close}@anchor{347e}
@deffn {Méthode} close ()

Closes the mmap. Subsequent calls to other methods of the object will
result in a ValueError exception being raised. This will not close
the open file.
@end deffn

@geindex closed (attribut mmap.mmap)
@anchor{library/mmap mmap mmap closed}@anchor{347f}
@deffn {Attribut} closed

@code{True} if the file is closed.


Ajouté dans la version 3.2.

@end deffn

@geindex find() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap find}@anchor{3480}
@deffn {Méthode} find (sub[, start[, end]])

Returns the lowest index in the object where the subsequence `sub' is
found, such that `sub' is contained in the range [`start', `end'].
Optional arguments `start' and `end' are interpreted as in slice notation.
Returns @code{-1} on failure.


Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end deffn

@geindex flush() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap flush}@anchor{a86}
@deffn {Méthode} flush ([offset[, size]])

Flushes changes made to the in-memory copy of a file back to disk. Without
use of this call there is no guarantee that changes are written back before
the object is destroyed.  If `offset' and `size' are specified, only
changes to the given range of bytes will be flushed to disk; otherwise, the
whole extent of the mapping is flushed.  `offset' must be a multiple of the
@code{PAGESIZE} or @code{ALLOCATIONGRANULARITY}.

@code{None} is returned to indicate success.  An exception is raised when the
call failed.


Modifié dans la version 3.8: Previously, a nonzero value was returned on success; zero was returned
on error under Windows.  A zero value was returned on success; an
exception was raised on error under Unix.

@end deffn

@geindex madvise() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap madvise}@anchor{9f6}
@deffn {Méthode} madvise (option[, start[, length]])

Send advice `option' to the kernel about the memory region beginning at
`start' and extending `length' bytes.  `option' must be one of the
@ref{3481,,MADV_* constants} available on the system.  If
`start' and `length' are omitted, the entire mapping is spanned.  On
some systems (including Linux), `start' must be a multiple of the
@code{PAGESIZE}.

Availability: Systems with the @code{madvise()} system call.


Ajouté dans la version 3.8.

@end deffn

@geindex move() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap move}@anchor{3482}
@deffn {Méthode} move (dest, src, count)

Copy the `count' bytes starting at offset `src' to the destination index
`dest'.  If the mmap was created with @code{ACCESS_READ}, then calls to
move will raise a @ref{522,,TypeError} exception.
@end deffn

@geindex read() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap read}@anchor{10bf}
@deffn {Méthode} read ([n])

Return a @ref{1bd,,bytes} containing up to `n' bytes starting from the
current file position. If the argument is omitted, @code{None} or negative,
return all bytes from the current file position to the end of the
mapping. The file position is updated to point after the bytes that were
returned.


Modifié dans la version 3.3: Argument can be omitted or @code{None}.

@end deffn

@geindex read_byte() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap read_byte}@anchor{3483}
@deffn {Méthode} read_byte ()

Returns a byte at the current file position as an integer, and advances
the file position by 1.
@end deffn

@geindex readline() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap readline}@anchor{3484}
@deffn {Méthode} readline ()

Returns a single line, starting at the current file position and up to the
next newline. The file position is updated to point after the bytes that were
returned.
@end deffn

@geindex resize() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap resize}@anchor{347d}
@deffn {Méthode} resize (newsize)

Resizes the map and the underlying file, if any.

Resizing a map created with `access' of @code{ACCESS_READ} or
@code{ACCESS_COPY}, will raise a @ref{522,,TypeError} exception.
Resizing a map created with with `trackfd' set to @code{False},
will raise a @ref{1ff,,ValueError} exception.

`On Windows': Resizing the map will raise an @ref{40d,,OSError} if there are other
maps against the same named file. Resizing an anonymous map (ie against the
pagefile) will silently create a new map with the original data copied over
up to the length of the new size.


Modifié dans la version 3.11: Correctly fails if attempting to resize when another map is held
Allows resize against an anonymous map on Windows

@end deffn

@geindex rfind() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap rfind}@anchor{3485}
@deffn {Méthode} rfind (sub[, start[, end]])

Returns the highest index in the object where the subsequence `sub' is
found, such that `sub' is contained in the range [`start', `end'].
Optional arguments `start' and `end' are interpreted as in slice notation.
Returns @code{-1} on failure.


Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end deffn

@geindex seek() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap seek}@anchor{20a}
@deffn {Méthode} seek (pos[, whence])

Set the file's current position.  `whence' argument is optional and
defaults to @code{os.SEEK_SET} or @code{0} (absolute file positioning); other
values are @code{os.SEEK_CUR} or @code{1} (seek relative to the current
position) and @code{os.SEEK_END} or @code{2} (seek relative to the file's end).


Modifié dans la version 3.13: Return the new absolute position instead of @code{None}.

@end deffn

@geindex seekable() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap seekable}@anchor{209}
@deffn {Méthode} seekable ()

Return whether the file supports seeking, and the return value is always @code{True}.


Ajouté dans la version 3.13.

@end deffn

@geindex size() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap size}@anchor{347c}
@deffn {Méthode} size ()

Return the length of the file, which can be larger than the size of the
memory-mapped area.
@end deffn

@geindex tell() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap tell}@anchor{3486}
@deffn {Méthode} tell ()

Returns the current position of the file pointer.
@end deffn

@geindex write() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap write}@anchor{3487}
@deffn {Méthode} write (bytes)

Write the bytes in `bytes' into memory at the current position of the
file pointer and return the number of bytes written (never less than
@code{len(bytes)}, since if the write fails, a @ref{1ff,,ValueError} will be
raised).  The file position is updated to point after the bytes that
were written.  If the mmap was created with @code{ACCESS_READ}, then
writing to it will raise a @ref{522,,TypeError} exception.


Modifié dans la version 3.5: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.



Modifié dans la version 3.6: The number of bytes written is now returned.

@end deffn

@geindex write_byte() (méthode mmap.mmap)
@anchor{library/mmap mmap mmap write_byte}@anchor{3488}
@deffn {Méthode} write_byte (byte)

Write the integer `byte' into memory at the current
position of the file pointer; the file position is advanced by @code{1}. If
the mmap was created with @code{ACCESS_READ}, then writing to it will
raise a @ref{522,,TypeError} exception.
@end deffn
@end deffn

@menu
* MADV_* Constants:: 
* MAP_* Constants:: 

@end menu

@node MADV_* Constants,MAP_* Constants,,mmap --- Memory-mapped file support
@anchor{library/mmap madv-constants}@anchor{3489}@anchor{library/mmap madvise-constants}@anchor{3481}
@subsubsection MADV_* Constants


@geindex MADV_NORMAL (dans le module mmap)
@geindex MADV_RANDOM (dans le module mmap)
@geindex MADV_SEQUENTIAL (dans le module mmap)
@geindex MADV_WILLNEED (dans le module mmap)
@geindex MADV_DONTNEED (dans le module mmap)
@geindex MADV_REMOVE (dans le module mmap)
@geindex MADV_DONTFORK (dans le module mmap)
@geindex MADV_DOFORK (dans le module mmap)
@geindex MADV_HWPOISON (dans le module mmap)
@geindex MADV_MERGEABLE (dans le module mmap)
@geindex MADV_UNMERGEABLE (dans le module mmap)
@geindex MADV_SOFT_OFFLINE (dans le module mmap)
@geindex MADV_HUGEPAGE (dans le module mmap)
@geindex MADV_NOHUGEPAGE (dans le module mmap)
@geindex MADV_DONTDUMP (dans le module mmap)
@geindex MADV_DODUMP (dans le module mmap)
@geindex MADV_FREE (dans le module mmap)
@geindex MADV_NOSYNC (dans le module mmap)
@geindex MADV_AUTOSYNC (dans le module mmap)
@geindex MADV_NOCORE (dans le module mmap)
@geindex MADV_CORE (dans le module mmap)
@geindex MADV_PROTECT (dans le module mmap)
@geindex MADV_FREE_REUSABLE (dans le module mmap)
@geindex MADV_FREE_REUSE (dans le module mmap)
@anchor{library/mmap mmap MADV_NORMAL}@anchor{348a}
@deffn {Données} mmap.MADV_NORMAL
@anchor{library/mmap mmap MADV_RANDOM}@anchor{348b}
@deffnx {Données} mmap.MADV_RANDOM
@anchor{library/mmap mmap MADV_SEQUENTIAL}@anchor{348c}
@deffnx {Données} mmap.MADV_SEQUENTIAL
@anchor{library/mmap mmap MADV_WILLNEED}@anchor{348d}
@deffnx {Données} mmap.MADV_WILLNEED
@anchor{library/mmap mmap MADV_DONTNEED}@anchor{348e}
@deffnx {Données} mmap.MADV_DONTNEED
@anchor{library/mmap mmap MADV_REMOVE}@anchor{348f}
@deffnx {Données} mmap.MADV_REMOVE
@anchor{library/mmap mmap MADV_DONTFORK}@anchor{3490}
@deffnx {Données} mmap.MADV_DONTFORK
@anchor{library/mmap mmap MADV_DOFORK}@anchor{3491}
@deffnx {Données} mmap.MADV_DOFORK
@anchor{library/mmap mmap MADV_HWPOISON}@anchor{3492}
@deffnx {Données} mmap.MADV_HWPOISON
@anchor{library/mmap mmap MADV_MERGEABLE}@anchor{3493}
@deffnx {Données} mmap.MADV_MERGEABLE
@anchor{library/mmap mmap MADV_UNMERGEABLE}@anchor{3494}
@deffnx {Données} mmap.MADV_UNMERGEABLE
@anchor{library/mmap mmap MADV_SOFT_OFFLINE}@anchor{3495}
@deffnx {Données} mmap.MADV_SOFT_OFFLINE
@anchor{library/mmap mmap MADV_HUGEPAGE}@anchor{3496}
@deffnx {Données} mmap.MADV_HUGEPAGE
@anchor{library/mmap mmap MADV_NOHUGEPAGE}@anchor{3497}
@deffnx {Données} mmap.MADV_NOHUGEPAGE
@anchor{library/mmap mmap MADV_DONTDUMP}@anchor{3498}
@deffnx {Données} mmap.MADV_DONTDUMP
@anchor{library/mmap mmap MADV_DODUMP}@anchor{3499}
@deffnx {Données} mmap.MADV_DODUMP
@anchor{library/mmap mmap MADV_FREE}@anchor{349a}
@deffnx {Données} mmap.MADV_FREE
@anchor{library/mmap mmap MADV_NOSYNC}@anchor{349b}
@deffnx {Données} mmap.MADV_NOSYNC
@anchor{library/mmap mmap MADV_AUTOSYNC}@anchor{349c}
@deffnx {Données} mmap.MADV_AUTOSYNC
@anchor{library/mmap mmap MADV_NOCORE}@anchor{349d}
@deffnx {Données} mmap.MADV_NOCORE
@anchor{library/mmap mmap MADV_CORE}@anchor{349e}
@deffnx {Données} mmap.MADV_CORE
@anchor{library/mmap mmap MADV_PROTECT}@anchor{349f}
@deffnx {Données} mmap.MADV_PROTECT
@anchor{library/mmap mmap MADV_FREE_REUSABLE}@anchor{34a0}
@deffnx {Données} mmap.MADV_FREE_REUSABLE
@anchor{library/mmap mmap MADV_FREE_REUSE}@anchor{34a1}
@deffnx {Données} mmap.MADV_FREE_REUSE

These options can be passed to @ref{9f6,,mmap.madvise()}.  Not every option will
be present on every system.

Availability: Systems with the madvise() system call.


Ajouté dans la version 3.8.

@end deffn

@node MAP_* Constants,,MADV_* Constants,mmap --- Memory-mapped file support
@anchor{library/mmap id1}@anchor{34a2}@anchor{library/mmap map-constants}@anchor{347b}
@subsubsection MAP_* Constants


@geindex MAP_SHARED (dans le module mmap)
@geindex MAP_PRIVATE (dans le module mmap)
@geindex MAP_32BIT (dans le module mmap)
@geindex MAP_ALIGNED_SUPER (dans le module mmap)
@geindex MAP_ANON (dans le module mmap)
@geindex MAP_ANONYMOUS (dans le module mmap)
@geindex MAP_CONCEAL (dans le module mmap)
@geindex MAP_DENYWRITE (dans le module mmap)
@geindex MAP_EXECUTABLE (dans le module mmap)
@geindex MAP_HASSEMAPHORE (dans le module mmap)
@geindex MAP_JIT (dans le module mmap)
@geindex MAP_NOCACHE (dans le module mmap)
@geindex MAP_NOEXTEND (dans le module mmap)
@geindex MAP_NORESERVE (dans le module mmap)
@geindex MAP_POPULATE (dans le module mmap)
@geindex MAP_RESILIENT_CODESIGN (dans le module mmap)
@geindex MAP_RESILIENT_MEDIA (dans le module mmap)
@geindex MAP_STACK (dans le module mmap)
@geindex MAP_TPRO (dans le module mmap)
@geindex MAP_TRANSLATED_ALLOW_EXECUTE (dans le module mmap)
@geindex MAP_UNIX03 (dans le module mmap)
@anchor{library/mmap mmap MAP_SHARED}@anchor{347a}
@deffn {Données} mmap.MAP_SHARED
@anchor{library/mmap mmap MAP_PRIVATE}@anchor{3479}
@deffnx {Données} mmap.MAP_PRIVATE
@anchor{library/mmap mmap MAP_32BIT}@anchor{162a}
@deffnx {Données} mmap.MAP_32BIT
@anchor{library/mmap mmap MAP_ALIGNED_SUPER}@anchor{16e4}
@deffnx {Données} mmap.MAP_ALIGNED_SUPER
@anchor{library/mmap mmap MAP_ANON}@anchor{34a3}
@deffnx {Données} mmap.MAP_ANON
@anchor{library/mmap mmap MAP_ANONYMOUS}@anchor{34a4}
@deffnx {Données} mmap.MAP_ANONYMOUS
@anchor{library/mmap mmap MAP_CONCEAL}@anchor{16e5}
@deffnx {Données} mmap.MAP_CONCEAL
@anchor{library/mmap mmap MAP_DENYWRITE}@anchor{34a5}
@deffnx {Données} mmap.MAP_DENYWRITE
@anchor{library/mmap mmap MAP_EXECUTABLE}@anchor{34a6}
@deffnx {Données} mmap.MAP_EXECUTABLE
@anchor{library/mmap mmap MAP_HASSEMAPHORE}@anchor{1625}
@deffnx {Données} mmap.MAP_HASSEMAPHORE
@anchor{library/mmap mmap MAP_JIT}@anchor{1627}
@deffnx {Données} mmap.MAP_JIT
@anchor{library/mmap mmap MAP_NOCACHE}@anchor{1626}
@deffnx {Données} mmap.MAP_NOCACHE
@anchor{library/mmap mmap MAP_NOEXTEND}@anchor{1624}
@deffnx {Données} mmap.MAP_NOEXTEND
@anchor{library/mmap mmap MAP_NORESERVE}@anchor{1623}
@deffnx {Données} mmap.MAP_NORESERVE
@anchor{library/mmap mmap MAP_POPULATE}@anchor{18d5}
@deffnx {Données} mmap.MAP_POPULATE
@anchor{library/mmap mmap MAP_RESILIENT_CODESIGN}@anchor{1628}
@deffnx {Données} mmap.MAP_RESILIENT_CODESIGN
@anchor{library/mmap mmap MAP_RESILIENT_MEDIA}@anchor{1629}
@deffnx {Données} mmap.MAP_RESILIENT_MEDIA
@anchor{library/mmap mmap MAP_STACK}@anchor{34a7}
@deffnx {Données} mmap.MAP_STACK
@anchor{library/mmap mmap MAP_TPRO}@anchor{162d}
@deffnx {Données} mmap.MAP_TPRO
@anchor{library/mmap mmap MAP_TRANSLATED_ALLOW_EXECUTE}@anchor{162b}
@deffnx {Données} mmap.MAP_TRANSLATED_ALLOW_EXECUTE
@anchor{library/mmap mmap MAP_UNIX03}@anchor{162c}
@deffnx {Données} mmap.MAP_UNIX03

These are the various flags that can be passed to @ref{208,,mmap.mmap()}.  @ref{16e4,,MAP_ALIGNED_SUPER}
is only available at FreeBSD and @ref{16e5,,MAP_CONCEAL} is only available at OpenBSD.  Note
that some options might not be present on some systems.


Modifié dans la version 3.10: Added @ref{18d5,,MAP_POPULATE} constant.



Ajouté dans la version 3.11: Added @ref{34a7,,MAP_STACK} constant.



Ajouté dans la version 3.12: Added @ref{16e4,,MAP_ALIGNED_SUPER} and @ref{16e5,,MAP_CONCEAL} constants.



Ajouté dans la version 3.13: Added @ref{162a,,MAP_32BIT}, @ref{1625,,MAP_HASSEMAPHORE}, @ref{1627,,MAP_JIT},
@ref{1626,,MAP_NOCACHE}, @ref{1624,,MAP_NOEXTEND}, @ref{1623,,MAP_NORESERVE},
@ref{1628,,MAP_RESILIENT_CODESIGN}, @ref{1629,,MAP_RESILIENT_MEDIA},
@ref{162d,,MAP_TPRO}, @ref{162b,,MAP_TRANSLATED_ALLOW_EXECUTE}, and
@ref{162c,,MAP_UNIX03} constants.

@end deffn

@node Traitement des données provenant d'Internet,Outils de traitement de balises structurées,Réseau et communication entre processus,La bibliothèque standard
@anchor{library/netdata doc}@anchor{34a8}@anchor{library/netdata internet-data-handling}@anchor{34a9}@anchor{library/netdata netdata}@anchor{34aa}
@section Traitement des données provenant d'Internet


This chapter describes modules which support handling data formats commonly used
on the internet.

@menu
* email: email --- An email and MIME handling package. An email and MIME handling package
* json: json --- JSON encoder and decoder. JSON encoder and decoder
* mailbox: mailbox --- Manipulate mailboxes in various formats. Manipulate mailboxes in various formats
* mimetypes: mimetypes --- Map filenames to MIME types. Map filenames to MIME types
* base64: base64 --- Base16 Base32 Base64 Base85 Data Encodings. Base16, Base32, Base64, Base85 Data Encodings
* binascii: binascii --- Convert between binary and ASCII. Convert between binary and ASCII
* quopri: quopri --- Encode and decode MIME quoted-printable data. Encode and decode MIME quoted-printable data

@end menu

@node email --- An email and MIME handling package,json --- JSON encoder and decoder,,Traitement des données provenant d'Internet
@anchor{library/email doc}@anchor{34ab}@anchor{library/email email-an-email-and-mime-handling-package}@anchor{34ac}@anchor{library/email module-email}@anchor{3b}
@subsection @code{email} --- An email and MIME handling package


@geindex module; email

`Code source:' Lib/email/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/__init__.py}


__________________________________________________________________


The @ref{3b,,email} package is a library for managing email messages.  It is
specifically `not' designed to do any sending of email messages to SMTP
(
@geindex RFC; RFC 2821
RFC 2821@footnote{https://datatracker.ietf.org/doc/html/rfc2821.html}), NNTP, or other servers; those are functions of modules such as
@ref{c9,,smtplib}.  The @ref{3b,,email} package attempts to be as
RFC-compliant as possible, supporting 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} and 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html}, as well as
such MIME-related RFCs as 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, 
@geindex RFC; RFC 2046
RFC 2046@footnote{https://datatracker.ietf.org/doc/html/rfc2046.html}, 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}, 
@geindex RFC; RFC 2183
RFC 2183@footnote{https://datatracker.ietf.org/doc/html/rfc2183.html},
and 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}.

Ce paquet peut être divisé entre trois composants majeurs, et un quatrième composant qui contrôle le comportement des trois autres.

Le composant central du paquet est un "modèle d'objet" qui représente les messages. Une application interagit avec le paquet, dans un premier temps, à travers l'interface de modèle d'objet définie dans le sous-module @ref{44,,message}. L'application peut utiliser cette API pour poser des questions à propos d'un mail existant, pour créer un nouvel e-mail, ou ajouter ou retirer des sous-composants d'e-mail qui utilisent la même interface de modèle d'objet. Suivant la nature des messages et leurs sous-composants MIME, le modèle d'objet d'e-mail est une structure arborescente d'objets qui fournit tout à l'API de @ref{278,,EmailMessage}.

Les deux autres composants majeurs de ce paquet sont l'analyseur (@ref{4e,,parser}) et le générateur (@ref{40,,generator}). L'analyseur prend la version sérialisée d'un e-mail (un flux d'octets) et le convertit en une arborescence d'objets @ref{278,,EmailMessage}. Le générateur prend un objet @ref{278,,EmailMessage} et le retransforme en un flux d'octets sérialisé (l'analyseur et le générateur gèrent aussi des suites de caractères textuels, mais cette utilisation est déconseillée car il est très facile de finir avec des messages invalides d'une manière ou d'une autre).

Le composant de contrôle est le module @ref{4f,,policy}. Chaque @ref{278,,EmailMessage}, chaque @ref{40,,generator} et chaque @ref{4e,,parser} possède un objet associé @ref{4f,,policy} qui contrôle son comportement. Habituellement une application n'a besoin de spécifier la politique que quand un @ref{278,,EmailMessage} est créé, soit en instanciant directement un @ref{278,,EmailMessage} pour créer un nouvel e-mail, soit lors de l'analyse d'un flux entrant en utilisant un @ref{4e,,parser}. Mais la politique peut être changée quand le message est sérialisé en utilisant un @ref{40,,generator}. Cela permet, par exemple, d'analyser un message e-mail générique du disque, puis de le sérialiser en utilisant une configuration SMTP standard quand on l'envoie vers un serveur d'e-mail.

Le paquet `email' fait son maximum pour cacher les détails des différentes RFCs de référence à l'application. Conceptuellement, l'application doit être capable de traiter l'e-mail comme une arborescence structurée de texte Unicode et de pièces jointes binaires, sans avoir à se préoccuper de leur représentation sérialisée. Dans la pratique, cependant, il est souvent nécessaire d'être conscient d'au moins quelques règles relatives aux messages MIME et à leur structure, en particulier les noms et natures des "types de contenus" et comment ils identifient les documents à plusieurs parties. Pour la plupart, cette connaissance devrait seulement être nécessaire pour des applications plus complexes, et même là, il devrait être question des structures de haut niveau et non des détails sur la manière dont elles sont représentées. Comme les types de contenus MIME sont couramment utilisés dans les logiciels internet modernes (et non uniquement les e-mails), les développeurs sont généralement familiers de ce concept.

La section suivante décrit les fonctionnalités du paquet @ref{3b,,email}. Nous commençons avec le modèle d'objet @ref{44,,message}, qui est la principale interface qu'une application utilise, et continuons avec les composants @ref{4e,,parser} et @ref{40,,generator}. Ensuite, nous couvrons les contrôles @ref{4f,,policy}, qui complètent le traitement des principaux composants de la bibliothèque.

Les trois prochaines sections couvrent les exceptions que le paquet peut rencontrer et les imperfections (non-respect des RFCs) que le module @ref{4e,,parser} peut détecter. Ensuite nous couvrons les sous-composants @ref{42,,headerregistry} et @ref{3d,,contentmanager}, qui fournissent des outils pour faire des manipulations plus détaillées des en-têtes et du contenu, respectivement. Les deux composants contiennent des fonctionnalités adaptées pour traiter et produire des messages qui sortent de l'ordinaire, et elles documentent aussi leurs API pour pouvoir les étendre, ce qui ne manquera pas d'intéresser les applications avancées.

Ci-dessous se trouve un ensemble d'exemples d'utilisations des éléments fondamentaux des API couvertes dans les sections précédentes.

Ce que nous venons d'aborder constitue l'API moderne (compatible Unicode) du paquet `email'. Les sections restantes, commençant par la classe @ref{279,,Message}, couvrent l'API héritée @ref{c87,,compat32} qui traite beaucoup plus directement des détails sur la manière dont les e-mails sont représentés. L'API @ref{c87,,compat32} ne cache `pas' les détails des RFCs à l'application, mais pour les applications qui requièrent d'opérer à ce niveau, elle peut être un outil pratique. Cette documentation est aussi pertinente pour les applications qui utilisent toujours l'API @ref{c87,,compat32} pour des raisons de rétrocompatibilité.


Modifié dans la version 3.6: Documents réorganisés et réécrits pour promouvoir la nouvelle API @ref{278,,EmailMessage}/@ref{1099,,EmailPolicy}.


Contenus de la documentation du paquet @ref{3b,,email} :

@menu
* email.message; Representing an email message: email message Representing an email message. 
* email.parser; Parsing email messages: email parser Parsing email messages. 
* email.generator; Generating MIME documents: email generator Generating MIME documents. 
* email.policy; Policy Objects: email policy Policy Objects. 
* email.errors; Exception and Defect classes: email errors Exception and Defect classes. 
* email.headerregistry; Custom Header Objects: email headerregistry Custom Header Objects. 
* email.contentmanager; Managing MIME Content: email contentmanager Managing MIME Content. 
* email; Exemples: email Exemples. 
* email.message.Message ; représentation d'un message électronique à l'aide de l'API compat32: email message Message représentation d'un message électronique à l'aide de l'API compat32. 
* email.mime; Creating email and MIME objects from scratch: email mime Creating email and MIME objects from scratch. 
* email.header; Internationalized headers: email header Internationalized headers. 
* email.charset; Representing character sets: email charset Representing character sets. 
* email.encoders; Encoders: email encoders Encoders. 
* email.utils; Miscellaneous utilities: email utils Miscellaneous utilities. 
* email.iterators; Iterators: email iterators Iterators. 

@end menu

@node email message Representing an email message,email parser Parsing email messages,,email --- An email and MIME handling package
@anchor{library/email message doc}@anchor{34ad}@anchor{library/email message email-message-representing-an-email-message}@anchor{34ae}@anchor{library/email message module-email message}@anchor{44}
@subsubsection @code{email.message}: Representing an email message


@geindex module; email.message

`Code source :' Lib/email/message.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/message.py}


__________________________________________________________________



Ajouté dans la version 3.6: @footnote{
Ajouté à l'origine dans 3.4 en tant que @ref{102a,,module provisoire}. Les documents pour la classe de message héritée ont été déplacés dans @ref{34af,,email.message.Message ; représentation d'un message électronique à l'aide de l'API compat32}.
}


La classe centrale du paquet @ref{3b,,email} est la classe @ref{278,,EmailMessage}, importée du module @ref{44,,email.message}. C'est la classe mère du modèle d'objet @ref{3b,,email}. @ref{278,,EmailMessage} fournit la fonctionnalité de base pour définir et interroger les champs d'en-tête, pour accéder au corps des messages et pour créer ou modifier des messages structurés.

Un message électronique se compose d'en-têtes (`headers') et d'une `charge utile' (`payload' en anglais, également appelée `contenu' – `content' en anglais). Les en-têtes sont des noms et valeurs de champ de style 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} ou 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html}, où le nom et la valeur du champ sont séparés par deux points. Les deux-points ne font partie ni du nom du champ ni de la valeur du champ. La charge utile peut être un simple message texte, un objet binaire ou une séquence structurée de sous-messages chacun avec son propre ensemble d'en-têtes et sa propre charge utile. Ce dernier type de charge utile est indiqué par le message ayant un type MIME tel que @code{multipart/*} ou @code{message/rfc822}.

Le modèle conceptuel fourni par un objet @ref{278,,EmailMessage} est celui d'un dictionnaire ordonné d'en-têtes couplé à une `charge utile' qui représente le corps 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} du message, qui peut être une liste de sous-objets @code{EmailMessage}. En plus des méthodes de dictionnaire normales pour accéder aux noms et valeurs d'en-têtes, il existe des méthodes pour accéder à des informations spécialisées à partir des en-têtes (par exemple le type de contenu MIME), pour agir sur la charge utile, pour générer une version sérialisée du message et pour parcourir récursivement l'arborescence d'objets.

The @ref{278,,EmailMessage} dictionary-like interface is indexed by the header
names, which must be ASCII values.  The values of the dictionary are strings
with some extra methods.  Headers are stored and returned in case-preserving
form, but field names are matched case-insensitively.  The keys are ordered,
but unlike a real dict, there can be duplicates.  Additional methods are
provided for working with headers that have duplicate keys.

La `charge utile' est soit une chaîne ou un objet d'octets, dans le cas d'objets de message simples, soit une liste d'objets @ref{278,,EmailMessage} pour les documents de conteneur MIME tels que @code{multipart/*} et les objets messages @code{message/rfc822}.

@geindex EmailMessage (classe dans email.message)
@anchor{library/email message email message EmailMessage}@anchor{278}
@deffn {Classe} email.message.EmailMessage (policy=default)

Si `policy' est spécifiée, Python utilise les règles qu'elle spécifie pour mettre à jour et sérialiser la représentation du message. Si `policy' n'est pas définie, Python utilise la politique @ref{34b0,,default}, qui suit les règles des RFC de messagerie sauf pour les fins de ligne (au lieu de @code{\r\n} indiqués par la RFC, il utilise les fins de ligne standard Python @code{\n}). Pour plus d'informations, consultez la documentation @ref{4f,,policy}.

@geindex as_string() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage as_string}@anchor{34b1}
@deffn {Méthode} as_string (unixfrom=False, maxheaderlen=None, policy=None)

Return the entire message flattened as a string.  When optional
`unixfrom' is true, the envelope header is included in the returned
string.  `unixfrom' defaults to @code{False}.  For backward compatibility
with the base @ref{279,,Message} class `maxheaderlen' is
accepted, but defaults to @code{None}, which means that by default the line
length is controlled by the
@ref{34b2,,max_line_length} of the policy.  The
`policy' argument may be used to override the default policy obtained
from the message instance.  This can be used to control some of the
formatting produced by the method, since the specified `policy' will be
passed to the @ref{11ab,,Generator}.

L'aplatissement du message peut déclencher des changements dans @ref{278,,EmailMessage} si les valeurs par défaut doivent être renseignées pour terminer la transformation en chaîne (par exemple, les limites MIME peuvent être générées ou modifiées).

Notez que cette méthode est fournie à titre de commodité et n'est peut-être pas la méthode la plus utile pour sérialiser les messages dans votre application, en particulier si vous traitez plusieurs messages. Voir @ref{11ab,,email.generator.Generator} pour une API plus flexible pour la sérialisation des messages. Notez également que cette méthode est limitée à la production de messages sérialisés en « 7 bits propres » lorsque @ref{de5,,utf8} est @code{False}, qui est la valeur par défaut.


Modifié dans la version 3.6: le comportement par défaut lorsque `maxheaderlen' n'est pas spécifié est passé de la valeur par défaut à 0 à la valeur par défaut de `max_line_length' de la politique.

@end deffn

@geindex __str__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __str__}@anchor{34b3}
@deffn {Méthode} __str__ ()

Équivalent à @code{as_string(policy=self.policy.clone(utf8=True))}. Permet à @code{str(msg)} de produire une chaîne contenant le message sérialisé dans un format lisible.


Modifié dans la version 3.4: la méthode a été modifiée pour utiliser @code{utf8=True}, produisant ainsi une représentation de message semblable à 
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}, au lieu d'être un alias direct pour @ref{34b1,,as_string()}.

@end deffn

@geindex as_bytes() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage as_bytes}@anchor{34b4}
@deffn {Méthode} as_bytes (unixfrom=False, policy=None)

Renvoie le message entier aplati en tant qu'objet bytes. Lorsque l'option `unixfrom' est vraie, l'en-tête de l'enveloppe est inclus dans la chaîne renvoyée. `unixfrom' par défaut est @code{False}. L'argument `policy' peut être utilisé pour remplacer la politique par défaut obtenue à partir de l'instance de message. Cela peut être utilisé pour contrôler une partie du formatage produit par la méthode, puisque la `policy' spécifiée sera transmise à @ref{11ac,,BytesGenerator}.

L'aplatissement du message peut déclencher des changements dans @ref{278,,EmailMessage} si les valeurs par défaut doivent être renseignées pour terminer la transformation en chaîne (par exemple, les limites MIME peuvent être générées ou modifiées).

Notez que cette méthode est fournie à titre de commodité et n'est peut-être pas la méthode la plus utile pour sérialiser les messages dans votre application, en particulier si vous traitez plusieurs messages. Voir @ref{11ac,,email.generator.BytesGenerator} pour une API plus flexible pour la sérialisation des messages.
@end deffn

@geindex __bytes__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __bytes__}@anchor{34b5}
@deffn {Méthode} __bytes__ ()

Equivalent to @ref{34b4,,as_bytes()}.  Allows @code{bytes(msg)} to produce a
bytes object containing the serialized message.
@end deffn

@geindex is_multipart() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage is_multipart}@anchor{34b6}
@deffn {Méthode} is_multipart ()

Renvoie @code{True} si la charge utile du message est une liste d'objets @ref{278,,EmailMessage}, sinon renvoie @code{False}. Lorsque @ref{34b6,,is_multipart()} renvoie @code{False}, la charge utile doit être un objet chaîne (qui peut être une charge utile binaire encodée CTE). Notez que @ref{34b6,,is_multipart()} renvoyant @code{True} ne signifie pas nécessairement que @code{msg.get_content_maintype() == 'multipart'} renvoie @code{True}. Par exemple, @code{is_multipart} renvoie @code{True} lorsque le @ref{278,,EmailMessage} est de type @code{message/rfc822}.
@end deffn

@geindex set_unixfrom() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_unixfrom}@anchor{34b7}
@deffn {Méthode} set_unixfrom (unixfrom)

Définit l'en-tête de l'enveloppe du message sur `unixfrom', qui doit être une chaîne (voir @ref{34b8,,mboxMessage} pour une brève description de cet en-tête).
@end deffn

@geindex get_unixfrom() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_unixfrom}@anchor{34b9}
@deffn {Méthode} get_unixfrom ()

Renvoie l'en-tête de l'enveloppe du message. La valeur par défaut est @code{None} si l'en-tête de l'enveloppe n'a jamais été défini.
@end deffn

Les méthodes suivantes implémentent l'interface de type correspondance pour accéder aux en-têtes du message. Notez qu'il existe des différences sémantiques entre ces méthodes et une interface de correspondance normale (c'est-à-dire un dictionnaire). Par exemple, dans un dictionnaire, il n'y a pas de clés en double, mais ici, il peut y avoir des en-têtes de message en double. De plus, dans les dictionnaires, il n'y a pas d'ordre garanti pour les clés renvoyées par @ref{34ba,,keys()}, mais dans un objet @ref{278,,EmailMessage}, les en-têtes sont toujours renvoyés dans l'ordre dans lequel ils sont apparus dans le message d'origine, ou dans lequel ils ont été ajoutés au message plus tard. Tout en-tête supprimé puis rajouté est toujours ajouté à la fin de la liste des en-têtes.

Ces différences sémantiques sont intentionnelles et privilégient la commodité dans les cas d'utilisation les plus courants.

Notez que dans tous les cas, tout en-tête d'enveloppe présent dans le message n'est pas inclus dans l'interface de correspondance.

@geindex __len__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __len__}@anchor{34bb}
@deffn {Méthode} __len__ ()

Renvoie le nombre total d'en-têtes, y compris les doublons.
@end deffn

@geindex __contains__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __contains__}@anchor{34bc}
@deffn {Méthode} __contains__ (name)

Renvoie @code{True} si l'objet message a un champ nommé `name'. La correspondance est effectuée sans tenir compte de la casse et `name' n'inclut pas les deux-points de fin. Utilisé pour l'opérateur @code{in}. Par exemple :

@example
if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])
@end example
@end deffn

@geindex __getitem__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __getitem__}@anchor{34bd}
@deffn {Méthode} __getitem__ (name)

Renvoie la valeur du champ d'en-tête nommé. `name' n'inclut pas le séparateur de champ deux-points. Si l'en-tête est manquant, @code{None} est renvoyée ; @ref{33a,,KeyError} n'est jamais levée.

Notez que si le champ nommé apparaît plus d'une fois dans les en-têtes du message, il n'est pas défini la valeur de quel champ est renvoyée. Utilisez la méthode @ref{34be,,get_all()} pour obtenir les valeurs de tous les en-têtes existants nommés `name'.

En utilisant les politiques standard (non-@code{compat32}), la valeur renvoyée est une instance d'une sous-classe de @ref{34bf,,email.headerregistry.BaseHeader}.
@end deffn

@geindex __setitem__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __setitem__}@anchor{34c0}
@deffn {Méthode} __setitem__ (name, val)

Ajoute un en-tête au message avec le nom de champ `name' et la valeur `val'. Le champ est ajouté à la fin des en-têtes existants du message.

Notez que cela n'écrase `pas' ou ne supprime aucun en-tête existant portant le même nom. Si vous voulez vous assurer que le nouvel en-tête est le seul présent dans le message avec le nom de champ `name', supprimez d'abord le champ, par exemple :

@example
del msg['subject']
msg['subject'] = 'Python roolz!'
@end example

If the @ref{4f,,policy} defines certain headers to be unique (as the standard
policies do), this method may raise a @ref{1ff,,ValueError} when an attempt
is made to assign a value to such a header when one already exists.  This
behavior is intentional for consistency's sake, but do not depend on it
as we may choose to make such assignments do an automatic deletion of the
existing header in the future.
@end deffn

@geindex __delitem__() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage __delitem__}@anchor{34c1}
@deffn {Méthode} __delitem__ (name)

Supprime toutes les occurrences du champ portant le nom `name' des en-têtes du message. Aucune exception n'est levée si le champ nommé n'est pas présent dans les en-têtes.
@end deffn

@geindex keys() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage keys}@anchor{34ba}
@deffn {Méthode} keys ()

Renvoie une liste de tous les noms de champs d'en-tête du message.
@end deffn

@geindex values() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage values}@anchor{34c2}
@deffn {Méthode} values ()

Renvoie une liste de toutes les valeurs de champ du message.
@end deffn

@geindex items() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage items}@anchor{34c3}
@deffn {Méthode} items ()

Renvoie une liste de couples contenant tous les en-têtes et valeurs de champ du message.
@end deffn

@geindex get() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get}@anchor{34c4}
@deffn {Méthode} get (name, failobj=None)

Return the value of the named header field.  This is identical to
@ref{280,,__getitem__()} except that optional `failobj' is returned if the
named header is missing (`failobj' defaults to @code{None}).
@end deffn

Voici quelques méthodes supplémentaires utiles liées aux en-têtes :

@geindex get_all() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_all}@anchor{34be}
@deffn {Méthode} get_all (name, failobj=None)

Renvoie la liste de toutes les valeurs du champ nommé `name'. S'il n'y a pas d'en-têtes nommés de ce type dans le message, `failobj' est renvoyé (la valeur par défaut est @code{None}).
@end deffn

@geindex add_header() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_header}@anchor{34c5}
@deffn {Méthode} add_header (_name, _value, **_params)

Étend les en-têtes. Cette méthode est similaire à @ref{34c0,,__setitem__()} sauf que des paramètres d'en-tête supplémentaires peuvent être fournis en tant qu'arguments nommés. `_name' est le champ d'en-tête à ajouter et `_value' est la valeur `primaire' de l'en-tête.

Pour chaque élément du dictionnaire d'arguments nommés `_params', la clé est prise comme nom de paramètre, avec des traits de soulignement convertis en tirets (puisque les tirets sont illégaux dans les identifiants Python). Normalement, le paramètre est ajouté en tant que @code{key="value"} sauf si la valeur est @code{None}, auquel cas seule la clé est ajoutée.

Si la valeur contient des caractères non-ASCII, le jeu de caractères et la langue peuvent être explicitement contrôlés en spécifiant la valeur sous la forme d'un triplet au format @code{(CHARSET, LANGUAGE, VALUE)}, où @code{CHARSET} est une chaîne nommant le jeu de caractères à utiliser pour encoder la valeur, @code{LANGUAGE} peut généralement être défini sur @code{None} ou sur la chaîne vide (voir 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} pour d'autres possibilités) et @code{VALUE} est la chaîne contenant les valeurs des points de code non-ASCII. Si un triplet n'est pas passé et que la valeur contient des caractères non-ASCII, elle est automatiquement encodée au format 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} en utilisant @code{utf-8} comme @code{CHARSET} et @code{None} comme @code{LANGUAGE}.

Voici un exemple :

@example
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
@end example

Cela ajoute un en-tête qui ressemble à :

@example
Content-Disposition: attachment; filename="bud.gif"
@end example

Un exemple d'interface étendue avec des caractères non-ASCII :

@example
msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '@w{'}, 'Fußballer.ppt'))
@end example
@end deffn

@geindex replace_header() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage replace_header}@anchor{34c6}
@deffn {Méthode} replace_header (_name, _value)

Remplace un en-tête. Remplace le premier en-tête trouvé dans le message qui correspond à `_name', en conservant l'ordre des en-têtes et la casse du nom de champ de l'en-tête d'origine. Si aucun en-tête correspondant n'est trouvé, lève une @ref{33a,,KeyError}.
@end deffn

@geindex get_content_type() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_type}@anchor{34c7}
@deffn {Méthode} get_content_type ()

Renvoie le type de contenu du message, contraint en minuscules de la forme @code{maintype/subtype}. S'il n'y a pas d'en-tête @code{Content-Type} dans le message, renvoie la valeur renvoyée par @ref{34c8,,get_default_type()}. Si l'en-tête @code{Content-Type} n'est pas valide, renvoie @code{text/plain}.

(Selon la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, les messages ont toujours un type par défaut, @ref{34c7,,get_content_type()} renvoie toujours une valeur. La 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} définit le type par défaut d'un message comme étant @code{text/plain} à moins qu'il n'apparaisse dans un conteneur @code{multipart/digest}, auquel cas ce serait @code{message/rfc822}. Si l'en-tête @code{Content-Type} a une spécification de type invalide, la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} exige que le type par défaut soit @code{text/plain}.)
@end deffn

@geindex get_content_maintype() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_maintype}@anchor{34c9}
@deffn {Méthode} get_content_maintype ()

Renvoie le type de contenu principal du message. C'est la partie @code{maintype} de la chaîne renvoyée par @ref{34c7,,get_content_type()}.
@end deffn

@geindex get_content_subtype() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_subtype}@anchor{34ca}
@deffn {Méthode} get_content_subtype ()

Renvoie le type de sous-contenu du message. C'est la partie @code{subtype} de la chaîne renvoyée par @ref{34c7,,get_content_type()}.
@end deffn

@geindex get_default_type() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_default_type}@anchor{34c8}
@deffn {Méthode} get_default_type ()

Renvoie le type de contenu par défaut. La plupart des messages ont un type de contenu @code{text/plain} par défaut, à l'exception des messages qui sont des sous-parties des conteneurs @code{multipart/digest}. Ces sous-parties ont un type de contenu par défaut de @code{message/rfc822}.
@end deffn

@geindex set_default_type() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_default_type}@anchor{34cb}
@deffn {Méthode} set_default_type (ctype)

Définit le type de contenu par défaut. `ctype' doit être @code{text/plain} ou @code{message/rfc822}, bien que cela ne soit pas imposé. Le type de contenu par défaut n'est pas stocké dans l'en-tête @code{Content-Type}, il n'affecte donc que la valeur de retour des méthodes @code{get_content_type} lorsqu'aucun en-tête @code{Content-Type} n'est présent dans le message .
@end deffn

@geindex set_param() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_param}@anchor{34cc}
@deffn {Méthode} set_param (param, value, header='Content-Type', requote=True, charset=None, language='@w{'}, replace=False)

Définit un paramètre dans l'en-tête @code{Content-Type}. Si le paramètre existe déjà dans l'en-tête, remplace sa valeur par `value'. Lorsque `header' est @code{Content-Type} (la valeur par défaut) et que l'en-tête n'existe pas encore dans le message, l'ajoute, définit sa valeur sur @code{text/plain} et ajoute la nouvelle valeur du paramètre. `header' facultatif spécifie un en-tête alternatif à @code{Content-Type}.

Si la valeur contient des caractères non ASCII, le jeu de caractères et la langue peuvent être explicitement spécifiés à l'aide des paramètres facultatifs `charset' et `language'. L'option `language' spécifie la langue 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}, par défaut la chaîne vide. `charset' et `language' doivent être des chaînes. La valeur par défaut est @code{utf8} pour `charset' et @code{None} pour `language'.

Si `replace' est @code{False} (valeur par défaut), l'en-tête est déplacé à la fin de la liste des en-têtes. Si `replace' est @code{True}, l'en-tête est mis à jour sur place.

L'utilisation du paramètre `requote' avec les objets @ref{278,,EmailMessage} est obsolète.

Note that existing parameter values of headers may be accessed through
the @ref{34cd,,params} attribute of the
header value (for example, @code{msg['Content-Type'].params['charset']}).


Modifié dans la version 3.4: le paramètre nommé @code{replace} a été ajouté.

@end deffn

@geindex del_param() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage del_param}@anchor{34ce}
@deffn {Méthode} del_param (param, header='content-type', requote=True)

Supprime complètement le paramètre donné de l'en-tête @code{Content-Type}. L'en-tête est réécrit en place sans le paramètre ou sa valeur. L'option `header' spécifie une alternative à @code{Content-Type}.

L'utilisation du paramètre `requote' avec les objets @ref{278,,EmailMessage} est obsolète.
@end deffn

@geindex get_filename() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_filename}@anchor{34cf}
@deffn {Méthode} get_filename (failobj=None)

Renvoie la valeur du paramètre @code{filename} de l'en-tête @code{Content-Disposition} du message. Si l'en-tête n'a pas de paramètre @code{filename}, cette méthode revient à rechercher le paramètre @code{name} dans l'en-tête @code{Content-Type}. Si aucun n'est trouvé, ou si l'en-tête est manquant, alors `failobj' est renvoyé. La chaîne renvoyée est toujours sans guillemets selon @ref{34d0,,email.utils.unquote()}.
@end deffn

@geindex get_boundary() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_boundary}@anchor{34d1}
@deffn {Méthode} get_boundary (failobj=None)

Renvoie la valeur du paramètre @code{boundary} de l'en-tête @code{Content-Type} du message, ou `failobj' si l'en-tête est manquant ou n'a pas de paramètre @code{boundary}. La chaîne renvoyée est toujours sans guillemets selon @ref{34d0,,email.utils.unquote()}.
@end deffn

@geindex set_boundary() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_boundary}@anchor{34d2}
@deffn {Méthode} set_boundary (boundary)

Définit le paramètre @code{boundary} de l'en-tête @code{Content-Type} sur `boundary'. @ref{34d2,,set_boundary()} entoure `boundary' de guillemets si nécessaire. Une @ref{34d3,,HeaderParseError} est levée si l'objet message n'a pas d'en-tête @code{Content-Type}.

Notez que l'utilisation de cette méthode est légèrement différente de la suppression de l'ancien en-tête @code{Content-Type} et de l'ajout d'un nouveau avec la nouvelle délimitation via @ref{34c5,,add_header()}, car @ref{34d2,,set_boundary()} préserve l'ordre des en-têtes @code{Content-Type} dans la liste des en-têtes.
@end deffn

@geindex get_content_charset() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_charset}@anchor{34d4}
@deffn {Méthode} get_content_charset (failobj=None)

Renvoie le paramètre @code{charset} de l'en-tête @code{Content-Type}, contraint en minuscules. S'il n'y a pas d'en-tête @code{Content-Type}, ou si cet en-tête n'a pas de paramètre @code{charset}, `failobj' est renvoyé.
@end deffn

@geindex get_charsets() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_charsets}@anchor{34d5}
@deffn {Méthode} get_charsets (failobj=None)

Renvoie la liste des noms des jeux de caractères dans le message. Si le message est un @code{multipart}, alors la liste contient un élément pour chaque sous-partie dans la charge utile, sinon c'est une liste de longueur 1.

Chaque élément de la liste est une chaîne qui est la valeur du paramètre @code{charset} dans l'en-tête @code{Content-Type} pour la sous-partie représentée. Si la sous-partie n'a pas d'en-tête @code{Content-Type}, pas de paramètre @code{charset} ou n'est pas du type MIME principal @code{text}, alors cet élément est `failobj' dans la liste renvoyée.
@end deffn

@geindex is_attachment() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage is_attachment}@anchor{34d6}
@deffn {Méthode} is_attachment ()

Renvoie @code{True} s'il y a un en-tête @code{Content-Disposition} et que sa valeur (insensible à la casse) est @code{attachment}, @code{False} sinon.


Modifié dans la version 3.4.2: `is_attachment' est maintenant une méthode au lieu d'une propriété, par souci de cohérence avec @ref{34d7,,is_multipart()}.

@end deffn

@geindex get_content_disposition() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content_disposition}@anchor{34d8}
@deffn {Méthode} get_content_disposition ()

Renvoie la valeur en minuscules (sans paramètres) de l'en-tête @code{Content-Disposition} du message s'il en a un, ou @code{None}. Les valeurs possibles pour cette méthode sont `inline', `attachment' ou @code{None} si le message respecte la 
@geindex RFC; RFC 2183
RFC 2183@footnote{https://datatracker.ietf.org/doc/html/rfc2183.html}.


Ajouté dans la version 3.5.

@end deffn

Les méthodes suivantes concernent l'interrogation et la manipulation du contenu (charge utile) du message.

@geindex walk() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage walk}@anchor{34d9}
@deffn {Méthode} walk ()

La méthode @ref{34d9,,walk()} est un générateur polyvalent qui peut être utilisé pour itérer sur toutes les parties et sous-parties d'un arbre d'objets de message, dans l'ordre de parcours en profondeur d'abord. L'utilisation classique est d'itérer avec @ref{34d9,,walk()} dans une boucle @code{for} ; chaque itération renvoie la sous-partie suivante.

Voici un exemple qui imprime le type MIME de chaque partie d'une structure de message en plusieurs parties :

@c from email import message_from_binary_file
@c with open('../Lib/test/test_email/data/msg_16.txt', 'rb') as f:
@c     msg = message_from_binary_file(f)

@example
>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain
@end example

@code{walk} itère sur les sous-parties de toute partie où @ref{34b6,,is_multipart()} renvoie @code{True}, même si @code{msg.get_content_maintype() == 'multipart'} peut renvoyer @code{False}. Nous pouvons le voir dans notre exemple en utilisant la fonction d'aide au débogage @code{_structure} :

@example
>>> from email.iterators import _structure
>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain
@end example

Ici, les parties @code{message} ne sont pas des @code{multiparts}, mais elles contiennent des sous-parties. @code{is_multipart()} renvoie @code{True} et @code{walk} descend dans les sous-parties.
@end deffn

@geindex get_body() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_body}@anchor{34da}
@deffn {Méthode} get_body (preferencelist=('related', 'html', 'plain'))

Renvoie la partie MIME qui est la meilleure candidate pour être le corps du message.

`preferencelist' doit être une séquence de chaînes de l'ensemble @code{related}, @code{html} et @code{plain}, et indique l'ordre de préférence pour le type de contenu de la partie renvoyée.

Elle commence par rechercher des correspondances candidates avec l'objet sur lequel la méthode @code{get_body} est appelée.

Si @code{related} n'est pas inclus dans `preferencelist', elle considère la partie racine (ou sous-partie de la partie racine) de tout lien rencontré comme candidat si la (sous-)partie correspond à une préférence.

Lorsqu'elle rencontre un @code{multipart/related}, elle vérifie le paramètre @code{start} et si une partie avec un @code{Content-ID} correspondant est trouvée, elle la considère uniquement lors de la recherche de correspondances candidates. Sinon, elle ne considère que la première partie (racine par défaut) de @code{multipart/related}.

Si une partie a un en-tête @code{Content-Disposition}, elle ne considère la partie comme une correspondance candidate que si la valeur de l'en-tête est @code{inline}.

Si aucun des candidats ne correspond à aucune des préférences dans `preferencelist', elle renvoie @code{None}.

Remarques : (1) Pour la plupart des applications, les seules combinaisons `preferencelist' qui ont vraiment un sens sont @code{('plain',)}, @code{('html', 'plain')} et la valeur par défaut @code{( 'related', 'html', 'plain')}. (2) Parce que la correspondance commence avec l'objet sur lequel @code{get_body} est appelée, appeler @code{get_body} sur un @code{multipart/related} renvoie l'objet lui-même à moins que `preferencelist' n'ait une valeur autre que celle par défaut. (3) Les messages (ou parties de message) qui ne spécifient pas un @code{Content-Type} ou dont l'en-tête @code{Content-Type} est invalide sont traités comme s'ils étaient de type @code{text/plain}, ce qui peut occasionnellement amener @code{get_body} à renvoyer des résultats inattendus.
@end deffn

@geindex iter_attachments() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage iter_attachments}@anchor{34db}
@deffn {Méthode} iter_attachments ()

Renvoie un itérateur sur toutes les sous-parties immédiates du message qui ne sont pas des parties de « corps » candidates. Autrement dit, elle ignore la première occurrence de chacun des éléments suivants : @code{text/plain}, @code{text/html}, @code{multipart/related} ou @code{multipart/alternative} (sauf s'ils sont explicitement marqués comme pièces jointes via @code{Content-Disposition: attachment}), et renvoie toutes les parties restantes. Lorsqu'elle est appliquée directement à un @code{multipart/related}, renvoie un itérateur sur toutes les parties liées sauf la partie racine (c'est-à-dire la partie pointée par le paramètre @code{start}, ou la première partie s'il n'y a pas de paramètre @code{start} ou si le paramètre @code{start} ne correspond pas au @code{Content-ID} de l'une des parties). Lorsqu'elle est appliquée directement à un @code{multipart/alternative} ou à un non-@code{multipart}, elle renvoie un itérateur vide.
@end deffn

@geindex iter_parts() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage iter_parts}@anchor{34dc}
@deffn {Méthode} iter_parts ()

Renvoie un itérateur sur toutes les sous-parties immédiates du message, qui seront vides pour une non-@code{multipart} (voir aussi @ref{34d9,,walk()}).
@end deffn

@geindex get_content() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage get_content}@anchor{34dd}
@deffn {Méthode} get_content (*args, content_manager=None, **kw)

Appelle la méthode @ref{34de,,get_content()} du `content_manager', en passant `self' comme objet message et en passant tout autre argument ou mot-clé comme argument supplémentaire. Si `content_manager' n'est pas spécifié, utilise le @code{content_manager} spécifié par la @ref{4f,,policy} actuelle.
@end deffn

@geindex set_content() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage set_content}@anchor{1836}
@deffn {Méthode} set_content (*args, content_manager=None, **kw)

Appelle la méthode @ref{34df,,set_content()} du `content_manager', en passant `self' comme objet message et en passant tout autre argument ou mot-clé comme argument supplémentaire. Si `content_manager' n'est pas spécifié, utilise le @code{content_manager} spécifié par la @ref{4f,,policy} actuelle.
@end deffn

@geindex make_related() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage make_related}@anchor{34e0}
@deffn {Méthode} make_related (boundary=None)

Convertit un message non-@code{multipart} en un message @code{multipart/related}, en déplaçant tous les en-têtes @code{Content-} existants et la charge utile dans une (nouvelle) première partie du @code{multipart}. Si `boundary' est spécifié, elle l'utilise comme chaîne de délimitation dans le `multipart', sinon elle laisse la délimitation être créée automatiquement lorsque cela est nécessaire (par exemple, lorsque le message est sérialisé).
@end deffn

@geindex make_alternative() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage make_alternative}@anchor{34e1}
@deffn {Méthode} make_alternative (boundary=None)

Convertit un non-@code{multipart} ou un @code{multipart/related} en un @code{multipart/alternative}, en déplaçant tous les en-têtes @code{Content-} existants et la charge utile dans une (nouvelle) première partie du @code{multipart}. Si `boundary' est spécifiée, l'utilise comme chaîne de délimitation dans le `multipart', sinon laisse la délimitation être créée automatiquement lorsque cela est nécessaire (par exemple, lorsque le message est sérialisé).
@end deffn

@geindex make_mixed() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage make_mixed}@anchor{34e2}
@deffn {Méthode} make_mixed (boundary=None)

Convertit un non-@code{multipart}, un @code{multipart/related} ou un @code{multipart-alternative} en un @code{multipart/mixed}, en déplaçant tous les en-têtes @code{Content-} existants et charge utile dans une (nouvelle) première partie du @code{multipart}. Si `boundary' est spécifiée, l'utilise comme chaîne de délimitation dans le `multipart', sinon elle laisse la délimitation être créée automatiquement lorsque cela est nécessaire (par exemple, lorsque le message est sérialisé).
@end deffn

@geindex add_related() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_related}@anchor{34e3}
@deffn {Méthode} add_related (*args, content_manager=None, **kw)

Si le message est un @code{multipart/related}, crée un nouvel objet message, passe tous les arguments à sa méthode @ref{1836,,set_content()} et le joint avec @ref{34e4,,attach()} au @code{multipart}. Si le message n'est pas en @code{multipart}, appelle @ref{34e0,,make_related()} puis procède comme ci-dessus. Si le message est un autre type de @code{multipart}, lève une @ref{522,,TypeError}. Si `content_manager' n'est pas spécifié, utilise le @code{content_manager} spécifié par la @ref{4f,,policy} actuelle. Si la partie ajoutée n'a pas d'en-tête @code{Content-Disposition}, en ajoute un avec la valeur @code{inline}.
@end deffn

@geindex add_alternative() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_alternative}@anchor{34e5}
@deffn {Méthode} add_alternative (*args, content_manager=None, **kw)

Si le message est un @code{multipart/alternative}, crée un nouvel objet message, transmet tous les arguments à sa méthode @ref{1836,,set_content()} et le joint avec @ref{34e4,,attach()} au @code{multipart}. Si le message est non-@code{multipart} ou @code{multipart/related}, appelle @ref{34e1,,make_alternative()} puis procède comme ci-dessus. Si le message est un autre type de @code{multipart}, lève une @ref{522,,TypeError}. Si `content_manager' n'est pas spécifié, utilise le @code{content_manager} spécifié par la @ref{4f,,policy} actuelle.
@end deffn

@geindex add_attachment() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage add_attachment}@anchor{34e6}
@deffn {Méthode} add_attachment (*args, content_manager=None, **kw)

Si le message est un @code{multipart/mixed}, crée un nouvel objet message, passe tous les arguments à sa méthode @ref{1836,,set_content()} et le joint avec @ref{34e4,,attach()} au @code{multipart}. Si le message n'est pas en @code{multipart}, @code{multipart/related} ou @code{multipart/alternative}, appelle @ref{34e2,,make_mixed()} puis procède comme ci-dessus. Si `content_manager' n'est pas spécifié, utilise le @code{content_manager} spécifié par la @ref{4f,,policy} actuelle. Si la partie ajoutée n'a pas d'en-tête @code{Content-Disposition}, en ajoute un avec la valeur @code{attachment}. Cette méthode peut être utilisée à la fois pour les pièces jointes explicites (@code{Content-Disposition:attachment}) et les pièces jointes @code{inline} (@code{Content-Disposition:inline}), en passant les options appropriées au @code{content_manager}.
@end deffn

@geindex clear() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage clear}@anchor{34e7}
@deffn {Méthode} clear ()

Supprime la charge utile et tous les en-têtes.
@end deffn

@geindex clear_content() (méthode email.message.EmailMessage)
@anchor{library/email message email message EmailMessage clear_content}@anchor{34e8}
@deffn {Méthode} clear_content ()

Remove the payload and all of the @code{!Content-} headers, leaving
all other headers intact and in their original order.
@end deffn

Les objets @ref{278,,EmailMessage} ont les attributs d'instance suivants :

@geindex preamble (attribut email.message.EmailMessage)
@anchor{library/email message email message EmailMessage preamble}@anchor{34e9}
@deffn {Attribut} preamble

Le format d'un document MIME permet d'insérer du texte entre la ligne vide suivant les en-têtes et la première chaîne de délimitation en plusieurs parties. Normalement, ce texte n'est jamais visible dans un lecteur de courrier compatible MIME car il ne fait pas partie de l'attirail MIME standard. Toutefois, lors de l'affichage du texte brut du message ou lors de l'affichage du message dans un lecteur non compatible MIME, ce texte peut devenir visible.

L'attribut `preamble' contient ce texte hors cadre de tête pour les documents MIME. Lorsque @ref{117c,,Parser} découvre du texte après les en-têtes mais avant la première chaîne de délimitation, il attribue ce texte à l'attribut `preamble' du message. Lorsque @ref{11ab,,Generator} écrit la représentation en texte brut d'un message MIME, et qu'il trouve que le message a un attribut `preamble', il écrit ce texte dans la zone entre les en-têtes et la première limite. Voir @ref{4e,,email.parser} et @ref{40,,email.generator} pour plus de détails.

Notez que si l'objet message n'a pas de préambule, l'attribut `preamble' est @code{None}.
@end deffn

@geindex epilogue (attribut email.message.EmailMessage)
@anchor{library/email message email message EmailMessage epilogue}@anchor{34ea}
@deffn {Attribut} epilogue

L'attribut `epilogue' agit de la même manière que l'attribut `preamble', sauf qu'il contient du texte qui apparaît entre la dernière limite et la fin du message. Comme avec @ref{34e9,,preamble}, s'il n'y a pas de texte d'épilogue, cet attribut est @code{None}.
@end deffn

@geindex defects (attribut email.message.EmailMessage)
@anchor{library/email message email message EmailMessage defects}@anchor{34eb}
@deffn {Attribut} defects

L'attribut `defects' contient une liste de tous les problèmes rencontrés lors de l'analyse de ce message. Voir @ref{3f,,email.errors} pour une description détaillée des défauts d'analyse possibles.
@end deffn
@end deffn

@geindex MIMEPart (classe dans email.message)
@anchor{library/email message email message MIMEPart}@anchor{f25}
@deffn {Classe} email.message.MIMEPart (policy=default)

Cette classe représente une sous-partie d'un message MIME. Elle est identique à @ref{278,,EmailMessage}, sauf qu'aucun en-tête @code{MIME-Version} n'est ajouté lorsque @ref{1836,,set_content()} est appelée, car les sous-parties n'ont pas besoin de leurs propres en-têtes @code{MIME-Version}.
@end deffn

@subsubheading Notes


@node email parser Parsing email messages,email generator Generating MIME documents,email message Representing an email message,email --- An email and MIME handling package
@anchor{library/email parser doc}@anchor{34ec}@anchor{library/email parser email-parser-parsing-email-messages}@anchor{34ed}@anchor{library/email parser module-email parser}@anchor{4e}
@subsubsection @code{email.parser}: Parsing email messages


@geindex module; email.parser

`Code source :' Lib/email/parser.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/parser.py}


__________________________________________________________________


Les instances de messages peuvent être créées de deux façons : elles peuvent être créées de toutes pièces en créant un objet @code{EmailMessage}, en ajoutant des en-têtes en utilisant l'interface de dictionnaire, et en ajoutant un ou plusieurs corps de message en utilisant @code{set_content()} et les méthodes associées, ou elles peuvent être créées en analysant une représentation sérialisée de l'e-mail.

Le paquet @ref{3b,,email} fournit un analyseur standard qui comprend la plupart des structures de documents de courrier électronique, y compris les documents MIME. Vous pouvez passer à l'analyseur un objet `bytes', chaîne ou fichier, et l'analyseur vous renverra l'instance racine @ref{278,,EmailMessage} de la structure de l'objet. Pour les messages simples non MIME, la charge utile de cet objet racine sera probablement une chaîne contenant le texte du message. Pour les messages MIME, la méthode @ref{34b6,,is_multipart()} de l'objet racine renvoie @code{True}, et les sous-parties sont accessibles via les méthodes de manipulation de la charge utile, telles que @code{get_body()}, @ref{34dc,,iter_parts()} et @ref{34d9,,walk()}.

Il existe en fait deux interfaces d'analyseur disponibles, l'API @ref{117c,,Parser} et l'API incrémentale @ref{34ee,,FeedParser}. L'API @ref{117c,,Parser} est plus utile si vous avez le texte entier du message en mémoire ou si le message entier réside dans un fichier sur le système de fichiers. @ref{34ee,,FeedParser} est plus appropriée lorsque vous lisez le message à partir d'un flux qui peut bloquer en attente d'une entrée supplémentaire (comme la lecture d'un message électronique à partir d'un connecteur réseau). @ref{34ee,,FeedParser} peut consommer et analyser le message de manière incrémentielle et ne renvoie l'objet racine que lorsque vous fermez l'analyseur.

Note that the parser can be extended in limited ways, and of course you can
implement your own parser completely from scratch.  All of the logic that
connects the @ref{3b,,email} package's bundled parser and the
@ref{278,,EmailMessage} class is embodied in the @ref{1095,,Policy}
class, so a custom parser can create message object trees any way it finds
necessary by implementing custom versions of the appropriate @code{Policy}
methods.

@menu
* API FeedParser:: 
* API de Parser:: 
* Notes complémentaires:: 

@end menu

@node API FeedParser,API de Parser,,email parser Parsing email messages
@anchor{library/email parser feedparser-api}@anchor{34ef}
@subsubsection API `FeedParser'


@ref{11a8,,BytesFeedParser}, importée du module @code{email.feedparser}, fournit une API propice à l'analyse incrémentielle des messages électroniques, adaptée à la lecture du texte d'un message électronique à partir d'une source qui peut bloquer (comme un connecteur). @ref{11a8,,BytesFeedParser} peut bien sûr être utilisée pour analyser un message électronique entièrement contenu dans un @ref{d1b,,objet octets-compatible}, une chaîne ou un fichier, mais l'API @ref{11a9,,BytesParser} peut être plus pratique dans ces utilisations. La sémantique et les résultats des deux API d'analyseurs sont identiques.

L'API de @ref{11a8,,BytesFeedParser} est simple ; vous créez une instance, l'alimentez d'une suite d'octets jusqu'à ce qu'il n'y en ait plus pour l'alimenter, puis fermez l'analyseur pour récupérer l'objet message racine. @ref{11a8,,BytesFeedParser} est extrêmement précise lors de l'analyse des messages conformes aux normes, et elle fait un très bon travail d'analyse des messages non conformes, fournissant des informations sur ce qu'elle considère comme non approprié dans un message. Elle remplit l'attribut @ref{34eb,,defects} d'un objet message avec une liste de tous les problèmes trouvés dans un message. Voir le module @ref{3f,,email.errors} pour la liste des défauts qu'elle peut trouver.

Voici l’API de @ref{11a8,,BytesFeedParser} :

@geindex BytesFeedParser (classe dans email.parser)
@anchor{library/email parser email parser BytesFeedParser}@anchor{11a8}
@deffn {Classe} email.parser.BytesFeedParser (_factory=None, *, policy=policy.compat32)

Crée une instance @ref{11a8,,BytesFeedParser}. `_factory' est un appelable facultatif sans argument ; s'il n'est pas spécifié, elle utilise la @ref{c86,,message_factory} de la `policy'. Elle appelle `_factory' chaque fois qu'un nouvel objet de message est nécessaire.

Si `policy' est spécifiée, elle utilise les règles spécifiées pour mettre à jour la représentation du message. Si `policy' n'est pas définie, elle utilise la stratégie @ref{1096,,compat32}, qui maintient la rétrocompatibilité avec la version Python 3.2 du paquet de messagerie et fournit @ref{279,,Message} comme usine par défaut. Toutes les autres stratégies fournissent @ref{278,,EmailMessage} comme `_factory' par défaut. Pour plus d'informations sur ce que `policy' régit, consultez la documentation @ref{4f,,policy}.

Remarque : `Le paramètre nommé « policy » doit toujours être spécifié' ; La valeur par défaut deviendra @ref{34b0,,email.policy.default} dans une future version de Python.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: ajout du paramètre nommé `policy'.



Modifié dans la version 3.6: `_factory' utilise par défaut la politique @code{message_factory}.


@geindex feed() (méthode email.parser.BytesFeedParser)
@anchor{library/email parser email parser BytesFeedParser feed}@anchor{34f0}
@deffn {Méthode} feed (data)

Alimente l'analyseur avec plus de données. `data' doit être un @ref{d1b,,objet octets-compatible} contenant une ou plusieurs lignes. Les lignes peuvent être partielles et l'analyseur assemble correctement ces lignes partielles. Les lignes peuvent avoir l'une des trois fins de ligne courantes : retour chariot, nouvelle ligne ou retour chariot et nouvelle ligne (elles peuvent même être mélangées).
@end deffn

@geindex close() (méthode email.parser.BytesFeedParser)
@anchor{library/email parser email parser BytesFeedParser close}@anchor{34f1}
@deffn {Méthode} close ()

Termine l'analyse de toutes les données précédemment alimentées et renvoie l'objet message racine. Ce qui se passe si @ref{34f0,,feed()} est appelée après l'appel de cette méthode n'est pas défini.
@end deffn
@end deffn

@geindex FeedParser (classe dans email.parser)
@anchor{library/email parser email parser FeedParser}@anchor{34ee}
@deffn {Classe} email.parser.FeedParser (_factory=None, *, policy=policy.compat32)

Fonctionne comme @ref{11a8,,BytesFeedParser} sauf que l'entrée de la méthode @ref{34f0,,feed()} doit être une chaîne. Ceci est d'une utilité limitée, car la seule façon pour qu'un tel message soit valide est qu'il ne contienne que du texte ASCII ou, si @code{utf8} vaut @code{True}, aucun binaire en pièce jointe.


Modifié dans la version 3.3: ajout du paramètre nommé `policy'.

@end deffn

@node API de Parser,Notes complémentaires,API FeedParser,email parser Parsing email messages
@anchor{library/email parser parser-api}@anchor{34f2}
@subsubsection API de `Parser'


La classe @ref{11a9,,BytesParser}, importée du module @ref{4e,,email.parser}, fournit une API qui peut être utilisée pour analyser un message lorsque le contenu complet du message est disponible dans un @ref{d1b,,objet octets-compatible} ou un fichier. Le module @ref{4e,,email.parser} fournit également @ref{117c,,Parser} pour l'analyse des chaînes et des analyseurs d'en-tête uniquement, @ref{109d,,BytesHeaderParser} et @ref{109e,,HeaderParser}, qui peuvent être utilisés si vous ne vous intéressez qu'aux en-têtes du message. @ref{109d,,BytesHeaderParser} et @ref{109e,,HeaderParser} peuvent être beaucoup plus rapides dans ces situations, car ils n'essaient pas d'analyser le corps du message.

@geindex BytesParser (classe dans email.parser)
@anchor{library/email parser email parser BytesParser}@anchor{11a9}
@deffn {Classe} email.parser.BytesParser (_class=None, *, policy=policy.compat32)

Crée une instance @ref{11a9,,BytesParser}. Les arguments `_class' et `policy' ont la même signification et la même sémantique que les arguments `_factory' et `policy' de @ref{11a8,,BytesFeedParser}.

Remarque : `Le paramètre nommé « policy » doit toujours être spécifié' ; La valeur par défaut deviendra @ref{34b0,,email.policy.default} dans une future version de Python.


Modifié dans la version 3.3: suppression de l'argument `strict' qui était obsolète dans 2.4. Ajout du paramètre nommé `policy'.



Modifié dans la version 3.6: `_class' utilise par défaut la politique @code{message_factory}.


@geindex parse() (méthode email.parser.BytesParser)
@anchor{library/email parser email parser BytesParser parse}@anchor{34f3}
@deffn {Méthode} parse (fp, headersonly=False)

Lit toutes les données de l'objet de type fichier binaire `fp', analyse les octets résultants et renvoie l'objet message. `fp' doit prendre en charge les méthodes @ref{1307,,readline()} et @code{read()}.

Les octets contenus dans `fp' doivent être formatés comme un bloc d'en-têtes de style conforme à la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} (ou, si @code{utf8} est @code{True}, à la 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html}), éventuellement précédés d'un en-tête d'enveloppe. Le bloc d'en-têtes se termine soit par la fin des données, soit par une ligne blanche. Après le bloc d'en-têtes se trouve le corps du message (qui peut contenir des sous-parties codées MIME, y compris des sous-parties avec un @code{Content-Transfer-Encoding} de @code{8bit}).

`headersonly' est un indicateur facultatif spécifiant s'il faut arrêter l'analyse après avoir lu les en-têtes ou non. La valeur par défaut est @code{False}, ce qui signifie qu'il analyse tout le contenu du fichier.
@end deffn

@geindex parsebytes() (méthode email.parser.BytesParser)
@anchor{library/email parser email parser BytesParser parsebytes}@anchor{34f4}
@deffn {Méthode} parsebytes (bytes, headersonly=False)

Semblable à la méthode @ref{34f3,,parse()}, sauf qu'elle prend un @ref{d1b,,objet octets-compatible} au lieu d'un objet de type fichier. Appeler cette méthode sur un @ref{d1b,,objet octets-compatible} équivaut à envelopper `bytes' dans une instance @ref{e8d,,BytesIO} d'abord et à appeler @ref{34f3,,parse()}.

L'utilisation de l'option `headersonly' est identique à son utilisation dans la méthode @ref{34f3,,parse()}.
@end deffn


Ajouté dans la version 3.2.

@end deffn

@geindex BytesHeaderParser (classe dans email.parser)
@anchor{library/email parser email parser BytesHeaderParser}@anchor{109d}
@deffn {Classe} email.parser.BytesHeaderParser (_class=None, *, policy=policy.compat32)

Exactement comme @ref{11a9,,BytesParser}, sauf que `headersonly' par défaut est @code{True}.


Ajouté dans la version 3.3.

@end deffn

@geindex Parser (classe dans email.parser)
@anchor{library/email parser email parser Parser}@anchor{117c}
@deffn {Classe} email.parser.Parser (_class=None, *, policy=policy.compat32)

Cette classe est semblable à @ref{11a9,,BytesParser}, mais elle accepte une chaîne en entrée.


Modifié dans la version 3.3: suppression de l'argument `strict'. Ajout de l'argument nommé `policy'.



Modifié dans la version 3.6: `_class' utilise par défaut la politique @code{message_factory}.


@geindex parse() (méthode email.parser.Parser)
@anchor{library/email parser email parser Parser parse}@anchor{34f5}
@deffn {Méthode} parse (fp, headersonly=False)

Lit toutes les données de l'objet de type fichier en mode texte `fp', analyse le texte résultant et renvoie l'objet message racine. `fp' doit prendre en charge les méthodes @ref{1c4b,,readline()} et @ref{1c13,,read()} sur les objets de type fichier.

Outre l'exigence du mode texte, cette méthode fonctionne comme @ref{34f3,,BytesParser.parse()}.
@end deffn

@geindex parsestr() (méthode email.parser.Parser)
@anchor{library/email parser email parser Parser parsestr}@anchor{34f6}
@deffn {Méthode} parsestr (text, headersonly=False)

Similaire à la méthode @ref{34f5,,parse()}, sauf qu'elle prend un objet chaîne au lieu d'un objet de type fichier. Appeler cette méthode sur une chaîne équivaut à envelopper `text' dans une instance @ref{f12,,StringIO} d'abord et à appeler @ref{34f5,,parse()}.

L'utilisation de l'option `headersonly' est identique à son utilisation dans la méthode @ref{34f5,,parse()}.
@end deffn
@end deffn

@geindex HeaderParser (classe dans email.parser)
@anchor{library/email parser email parser HeaderParser}@anchor{109e}
@deffn {Classe} email.parser.HeaderParser (_class=None, *, policy=policy.compat32)

Exactement comme @ref{117c,,Parser}, sauf que `headersonly' par défaut est @code{True}.
@end deffn

Étant donné que la création d'une structure d'objet message à partir d'une chaîne ou d'un objet fichier est une tâche très courante, quatre fonctions sont fournies par commodité. Elles sont disponibles dans l'espace de noms de paquet de niveau supérieur @ref{3b,,email}.

@geindex message_from_bytes() (dans le module email)
@anchor{library/email parser email message_from_bytes}@anchor{11a6}
@deffn {Fonction} email.message_from_bytes (s, _class=None, *, policy=policy.compat32)

Renvoie une structure d'objet message à partir d'un @ref{d1b,,objet octets-compatible}. C'est équivalent à @code{BytesParser().parsebytes(s)}. `_class' et `policy' (facultatifs) sont interprétés comme pour le constructeur de classe @ref{11a9,,BytesParser}.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: suppression de l'argument `strict'. Ajout de l'argument nommé `policy'.

@end deffn

@geindex message_from_binary_file() (dans le module email)
@anchor{library/email parser email message_from_binary_file}@anchor{11a7}
@deffn {Fonction} email.message_from_binary_file (fp, _class=None, *, policy=policy.compat32)

Renvoie une arborescence d'objets message à partir d'un @ref{11a0,,objet fichier} binaire ouvert. C'est équivalent à @code{BytesParser().parse(fp)}. `_class' et `policy' sont interprétés comme pour le constructeur de classe @ref{11a9,,BytesParser}.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: suppression de l'argument `strict'. Ajout de l'argument nommé `policy'.

@end deffn

@geindex message_from_string() (dans le module email)
@anchor{library/email parser email message_from_string}@anchor{34f7}
@deffn {Fonction} email.message_from_string (s, _class=None, *, policy=policy.compat32)

Renvoie une structure d'objet message à partir d'une chaîne. C'est équivalent à @code{Parser().parsestr(s)}. `_class' et `policy' sont interprétés comme avec le constructeur de classe @ref{117c,,Parser}.


Modifié dans la version 3.3: suppression de l'argument `strict'. Ajout de l'argument nommé `policy'.

@end deffn

@geindex message_from_file() (dans le module email)
@anchor{library/email parser email message_from_file}@anchor{34f8}
@deffn {Fonction} email.message_from_file (fp, _class=None, *, policy=policy.compat32)

Renvoie une arborescence de structures d'objets messages à partir d'un @ref{11a0,,objet fichier} ouvert. C'est équivalent à @code{Parser().parse(fp)}. `_class' et `policy' sont interprétés comme avec le constructeur de classe @ref{117c,,Parser}.


Modifié dans la version 3.3: suppression de l'argument `strict'. Ajout de l'argument nommé `policy'.



Modifié dans la version 3.6: `_class' utilise par défaut la politique @code{message_factory}.

@end deffn

Voici un exemple d'utilisation @ref{11a6,,message_from_bytes()} dans une invite Python interactive :

@example
>>> import email
>>> msg = email.message_from_bytes(myBytes)  
@end example

@node Notes complémentaires,,API de Parser,email parser Parsing email messages
@anchor{library/email parser additional-notes}@anchor{34f9}
@subsubsection Notes complémentaires


Voici des remarques sur la sémantique d'analyse :


@itemize *

@item 
La plupart des messages de type non-@code{multipart} sont analysés comme un seul objet de message avec une charge utile de type chaîne. Ces objets renvoient @code{False} pour @ref{34b6,,is_multipart()} et @ref{34dc,,iter_parts()} donne une liste vide.

@item 
Tous les messages de type @code{multipart} sont analysés comme un objet de message conteneur avec une liste d'objets de sous-messages pour leur charge utile. Le message du conteneur externe renvoie @code{True} pour @ref{34b6,,is_multipart()} et @ref{34dc,,iter_parts()} donne une liste de sous-parties.

@item 
La plupart des messages avec un type de contenu de @code{message/*} (tels que @code{message/delivery-status} et @code{message/rfc822}) sont également analysés en tant qu'objet conteneur contenant une charge utile de type « liste de longueur 1 ». Leur méthode @ref{34b6,,is_multipart()} renvoie @code{True}. L'élément unique généré par @ref{34dc,,iter_parts()} est un objet sous-message.

@item 
Certains messages non conformes aux normes peuvent ne pas être cohérents en interne quant à @code{multipart}. De tels messages peuvent avoir un en-tête @code{Content-Type} de type @code{multipart}, mais leur méthode @ref{34b6,,is_multipart()} peut renvoyer @code{False}. Si de tels messages ont été analysés avec la @ref{34ee,,FeedParser}, ils auront une instance de la classe @code{MultipartInvariantViolationDefect} dans leur liste d'attributs `defects'. Voir @ref{3f,,email.errors} pour plus de détails.
@end itemize

@node email generator Generating MIME documents,email policy Policy Objects,email parser Parsing email messages,email --- An email and MIME handling package
@anchor{library/email generator doc}@anchor{34fa}@anchor{library/email generator email-generator-generating-mime-documents}@anchor{34fb}@anchor{library/email generator module-email generator}@anchor{40}
@subsubsection @code{email.generator}: Generating MIME documents


@geindex module; email.generator

`Code source :' Lib/email/igenerator.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/igenerator.py}


__________________________________________________________________


One of the most common tasks is to generate the flat (serialized) version of
the email message represented by a message object structure.  You will need to
do this if you want to send your message via @ref{e42,,smtplib.SMTP.sendmail()},
or print the message on the console.  Taking a
message object structure and producing a serialized representation is the job
of the generator classes.

Comme avec le module @ref{4e,,email.parser}, vous n'êtes pas limité aux fonctionnalités du générateur fourni ; vous pourriez en écrire un à partir de zéro vous-même. Cependant, le générateur fourni sait comment générer la plupart des e-mails d'une manière conforme aux normes, est conçu pour gérer correctement les e-mails MIME et non MIME, et pour que les opérations (sur des suites d'octets) d'analyse et de génération soient inverses, en supposant que la même @ref{4f,,policy} est utilisée pour les deux. Autrement dit, l'analyse du flux d'octets sérialisé via la classe @ref{11a9,,BytesParser} puis la régénération du flux d'octets sérialisé à l'aide de @ref{11ac,,BytesGenerator} devrait produire une sortie identique à l'entrée @footnote{
This statement assumes that you use the appropriate setting for
@code{unixfrom}, and that there are no @ref{4f,,email.policy} settings calling for
automatic adjustments (for example,
@ref{34fc,,refold_source} must be @code{none}, which is
`not' the default).  It is also not 100% true, since if the message
does not conform to the RFC standards occasionally information about the
exact original text is lost during parsing error recovery.  It is a goal
to fix these latter edge cases when possible.
} (d'un autre côté, l'utilisation du générateur sur un @ref{278,,EmailMessage} construit par programme peut entraîner des modifications de l'objet @ref{278,,EmailMessage} car les valeurs par défaut sont renseignées).

La classe @ref{11ab,,Generator} peut être utilisée pour aplatir un message dans une représentation sérialisée textuelle (par opposition à binaire), mais comme Unicode ne peut pas représenter directement des données binaires, le message est nécessairement transformé en quelque chose qui ne contient que des caractères ASCII, en utilisant les techniques standard de codage de transfert de contenu RFC pour le codage des messages électroniques pour le transport sur des canaux qui ne sont pas « complétement 8 bits ».

Pour s'adapter au traitement reproductible des messages signés SMIME @ref{11ab,,Generator} ne raccourcit pas les en-têtes pour les parties de message de type @code{multipart/signed} et toutes les sous-parties.

@geindex BytesGenerator (classe dans email.generator)
@anchor{library/email generator email generator BytesGenerator}@anchor{11ac}
@deffn {Classe} email.generator.BytesGenerator (outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Renvoie un objet @ref{11ac,,BytesGenerator} qui écrit tout message fourni à la méthode @ref{34fd,,flatten()}, ou tout texte encodé par `surrogateescape' fourni à la méthode @ref{34fe,,write()}, dans le @ref{250d,,objet simili-fichier} `outfp'. `outfp' doit disposer d'une méthode @code{write} qui accepte les données binaires.

Si l'option `mangle_from_' est @code{True}, place un caractère @code{>} devant toute ligne du corps commençant par la chaîne exacte @code{"From "}, c'est-à-dire une ligne commençant par @code{From} suivi par une espace. `mangle_from_' prend par défaut la valeur du paramètre @ref{de3,,mangle_from_} de la `policy' (qui est @code{True} pour la politique @ref{c87,,compat32} et @code{False} pour tous les autres). `mangle_from_' est destiné à être utilisé lorsque les messages sont stockés au format Unix `mbox' (voir @ref{8a,,mailbox} et WHY THE CONTENT-LENGTH FORMAT IS BAD@footnote{https://www.jwz.org/doc/content-length.html}).

Si `maxheaderlen' n'est pas @code{None}, raccourcit toutes les lignes d'en-tête qui sont plus longues que `maxheaderlen', ou si @code{0}, ne raccourcit aucun en-tête. Si `manheaderlen' est @code{None} (valeur par défaut), formate les en-têtes et autres lignes de message en fonction des paramètres de `policy'.

Si `policy' est spécifiée, utilise cette politique pour contrôler la génération des messages. Si `policy' est @code{None} (par défaut), utilise la politique associée à l'objet @ref{279,,Message} ou @ref{278,,EmailMessage} passée à @code{flatten} pour contrôler la génération des messages. Voir @ref{4f,,email.policy} pour plus de détails sur ce que `policy' contrôle.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: ajout du mot-clé `policy'.



Modifié dans la version 3.6: le comportement par défaut des paramètres `mangle_from_' et `maxheaderlen' est de suivre la politique.


@geindex flatten() (méthode email.generator.BytesGenerator)
@anchor{library/email generator email generator BytesGenerator flatten}@anchor{34fd}
@deffn {Méthode} flatten (msg, unixfrom=False, linesep=None)

Affiche la représentation textuelle de la structure de l'objet message dont la racine est `msg' dans le fichier de sortie spécifié lors de la création de l'instance @ref{11ac,,BytesGenerator}.

Si l'option @ref{34ff,,cte_type} de @ref{4f,,policy} est @code{8bit} (valeur par défaut), copie tous les en-têtes du message analysé d'origine qui n'ont pas été modifiés en sortie avec tous les octets dont le bit de poids fort identique à l'original, et conserve le @code{Content-Transfer-Encoding} non-ASCII de toutes les parties du corps qui en ont. Si @code{cte_type} est @code{7bit}, convertit les octets avec le bit de poids fort défini selon les besoins en utilisant un @code{Content-Transfer-Encoding} compatible ASCII. Autrement dit, transforme les parties non ASCII @code{Content-Transfer-Encoding} (@code{Content-Transfer-Encoding: 8bit}) en un @code{Content-Transfer-Encoding} compatible ASCII, et encode les octets non ASCII non valides de la RFC dans les en-têtes utilisant le jeu de caractères MIME @code{unknown-8bit}, les rendant ainsi conformes à la RFC.

@c XXX: There should be an option that just does the RFC
@c compliance transformation on headers but leaves CTE 8bit parts alone.

Si `unixfrom' est @code{True}, affiche le délimiteur d'en-tête d'enveloppe utilisé par le format de boîte aux lettres Unix (voir @ref{8a,,mailbox}) avant le premier des en-têtes 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} de l'objet message racine. Si l'objet racine n'a pas d'en-tête d'enveloppe, en crée un standard. La valeur par défaut est @code{False}. Notez que pour les sous-parties, aucun en-tête d'enveloppe n'est jamais imprimé.

Si `linesep' n'est pas @code{None}, l'utilise comme caractère de séparation entre toutes les lignes du message aplati. Si `linesep' est @code{None} (valeur par défaut), utilise la valeur spécifiée dans la `policy'.

@c XXX: flatten should take a *policy* keyword.
@end deffn

@geindex clone() (méthode email.generator.BytesGenerator)
@anchor{library/email generator email generator BytesGenerator clone}@anchor{3500}
@deffn {Méthode} clone (fp)

Renvoie un clone indépendant de cette instance @ref{11ac,,BytesGenerator} avec exactement les mêmes paramètres d'option, et `fp' comme nouveau `outfp'.
@end deffn

@geindex write() (méthode email.generator.BytesGenerator)
@anchor{library/email generator email generator BytesGenerator write}@anchor{34fe}
@deffn {Méthode} write (s)

Encode `s' en utilisant le codec @code{ASCII} et le gestionnaire d'erreurs @code{surrogateescape}, et le passe à la méthode `write' du `outfp' passé au constructeur de @ref{11ac,,BytesGenerator}.
@end deffn
@end deffn

Par commodité, @ref{278,,EmailMessage} fournit les méthodes @ref{34b4,,as_bytes()} et @code{bytes(aMessage)} (alias @code{__bytes__()}), qui simplifient la génération d'une représentation binaire sérialisée d'un objet message. Pour plus de détails, voir @ref{44,,email.message}.

Comme les chaînes ne peuvent pas représenter des données binaires, la classe @ref{11ab,,Generator} doit convertir toutes les données binaires de tout message qu'elle aplatit en un format compatible ASCII, en les convertissant en un @code{Content-Transfer_Encoding} compatible ASCII. En utilisant la terminologie des RFC des e-mails, vous pouvez considérer cela comme un @ref{11ab,,Generator} sérialisant vers un flux d'entrées-sorties qui n'est pas « complètement 8 bits ». En d'autres termes, la plupart des applications voudront utiliser @ref{11ac,,BytesGenerator} et pas @ref{11ab,,Generator}.

@geindex Generator (classe dans email.generator)
@anchor{library/email generator email generator Generator}@anchor{11ab}
@deffn {Classe} email.generator.Generator (outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Renvoie un objet @ref{11ab,,Generator} qui écrit tout message fourni à la méthode @ref{3501,,flatten()}, ou tout texte fourni à la méthode @ref{3502,,write()}, dans l'@ref{250d,,objet simili-fichier} `outfp'. `outfp' doit prendre en charge une méthode @code{write} qui accepte les données de type chaîne.

Si l'option `mangle_from_' est @code{True}, place un caractère @code{>} devant toute ligne du corps commençant par la chaîne exacte @code{"From "}, c'est-à-dire une ligne commençant par @code{From} suivi par une espace. `mangle_from_' prend par défaut la valeur du paramètre @ref{de3,,mangle_from_} de la `policy' (qui est @code{True} pour la politique @ref{c87,,compat32} et @code{False} pour tous les autres). `mangle_from_' est destiné à être utilisé lorsque les messages sont stockés au format Unix `mbox' (voir @ref{8a,,mailbox} et WHY THE CONTENT-LENGTH FORMAT IS BAD@footnote{https://www.jwz.org/doc/content-length.html}).

Si `maxheaderlen' n'est pas @code{None}, raccourcit toutes les lignes d'en-tête qui sont plus longues que `maxheaderlen', ou si @code{0}, ne raccourcit aucun en-tête. Si `manheaderlen' est @code{None} (valeur par défaut), formate les en-têtes et autres lignes de message en fonction des paramètres de `policy'.

Si `policy' est spécifiée, utilise cette politique pour contrôler la génération des messages. Si `policy' est @code{None} (par défaut), utilise la politique associée à l'objet @ref{279,,Message} ou @ref{278,,EmailMessage} passée à @code{flatten} pour contrôler la génération des messages. Voir @ref{4f,,email.policy} pour plus de détails sur ce que `policy' contrôle.


Modifié dans la version 3.3: ajout du mot-clé `policy'.



Modifié dans la version 3.6: le comportement par défaut des paramètres `mangle_from_' et `maxheaderlen' est de suivre la politique.


@geindex flatten() (méthode email.generator.Generator)
@anchor{library/email generator email generator Generator flatten}@anchor{3501}
@deffn {Méthode} flatten (msg, unixfrom=False, linesep=None)

Affiche la représentation textuelle de la structure de l'objet message dont la racine est `msg' dans le fichier de sortie spécifié lors de la création de l'instance @ref{11ab,,Generator}.

Si l'option @ref{4f,,policy} @ref{34ff,,cte_type} est @code{8bit}, génère le message comme si l'option était définie sur @code{7bit} (c'est nécessaire car les chaînes ne peuvent pas représenter des octets non ASCII). Convertit tous les octets avec le bit de poids fort défini selon les besoins à l'aide d'un @code{Content-Transfer-Encoding} compatible ASCII. Autrement dit, transforme les parties non ASCII @code{Content-Transfer-Encoding} (@code{Content-Transfer-Encoding: 8bit}) en un @code{Content-Transfer-Encoding} compatible ASCII, et encode les octets non ASCII non valides RFC dans les en-têtes utilisant le jeu de caractères MIME @code{unknown-8bit}, les rendant ainsi conformes à la RFC.

Si `unixfrom' est @code{True}, affiche le délimiteur d'en-tête d'enveloppe utilisé par le format de boîte aux lettres Unix (voir @ref{8a,,mailbox}) avant le premier des en-têtes 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} de l'objet message racine. Si l'objet racine n'a pas d'en-tête d'enveloppe, en crée un standard. La valeur par défaut est @code{False}. Notez que pour les sous-parties, aucun en-tête d'enveloppe n'est jamais imprimé.

Si `linesep' n'est pas @code{None}, l'utilise comme caractère de séparation entre toutes les lignes du message aplati. Si `linesep' est @code{None} (valeur par défaut), utilise la valeur spécifiée dans la `policy'.

@c XXX: flatten should take a *policy* keyword.


Modifié dans la version 3.2: ajout de la prise en charge du ré-encodage des corps de message @code{8bit} et de l'argument `linesep'.

@end deffn

@geindex clone() (méthode email.generator.Generator)
@anchor{library/email generator email generator Generator clone}@anchor{3503}
@deffn {Méthode} clone (fp)

Renvoie un clone indépendant de cette instance @ref{11ab,,Generator} avec exactement les mêmes options, et avec `fp' comme nouveau `outfp'.
@end deffn

@geindex write() (méthode email.generator.Generator)
@anchor{library/email generator email generator Generator write}@anchor{3502}
@deffn {Méthode} write (s)

Écrit `s' dans la méthode `write' de `outfp' passé au constructeur de @ref{11ab,,Generator}. Cela fournit une API ressemblant suffisamment au type fichier pour les instances de @ref{11ab,,Generator} utilisées dans la fonction @ref{f60,,print()}.
@end deffn
@end deffn

Par commodité, @ref{278,,EmailMessage} fournit les méthodes @ref{34b1,,as_string()} et @code{str(aMessage)} (alias @code{__str__()}), qui simplifient la génération d'une représentation sous forme de chaîne formatée d'un objet message. Pour plus de détails, voir @ref{44,,email.message}.

Le module @ref{40,,email.generator} fournit également une classe dérivée, @ref{c85,,DecodedGenerator}, qui ressemble à la classe de base @ref{11ab,,Generator}, sauf que les parties non-@code{text} ne sont pas sérialisées, mais sont plutôt représentées dans le flux de sortie par une chaîne dérivée d'un modèle rempli d'informations sur la partie concernée.

@geindex DecodedGenerator (classe dans email.generator)
@anchor{library/email generator email generator DecodedGenerator}@anchor{c85}
@deffn {Classe} email.generator.DecodedGenerator (outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Agit comme @ref{11ab,,Generator}, sauf que pour toute sous-partie du message transmise à @ref{3501,,Generator.flatten()}, si la sous-partie est de type principal @code{text}, affiche la charge utile décodée de la sous-partie, et si le type principal n'est pas @code{text}, au lieu de l'afficher, remplit la chaîne `fmt' en utilisant les informations de la partie et affiche la chaîne remplie résultante.

Pour remplir `fmt', exécute @code{fmt % part_info}, où @code{part_info} est un dictionnaire composé des clés et valeurs suivantes :


@itemize *

@item 
@code{type} – Type MIME complet de la partie non-@code{text}

@item 
@code{maintype} – Type MIME principal de la partie non-@code{text}

@item 
@code{subtype} – Sous-type MIME de la partie non-@code{text}

@item 
@code{filename} – Nom de fichier de la partie non-@code{text}

@item 
@code{description} – Description associée à la partie non-@code{text}

@item 
@code{encoding} – Encodage du contenu de la partie non-@code{text}
@end itemize

Si `fmt' est @code{None}, utilise le `fmt' par défaut suivant :

@quotation

"[Non-text (%(type)s) part of message omitted, filename %(filename)s]"
@end quotation

`_mangle_from_' et `maxheaderlen' sont optionnels et fonctionnent comme avec la classe mère @ref{11ab,,Generator}.
@end deffn

@subsubheading Notes


@node email policy Policy Objects,email errors Exception and Defect classes,email generator Generating MIME documents,email --- An email and MIME handling package
@anchor{library/email policy doc}@anchor{3504}@anchor{library/email policy email-policy-policy-objects}@anchor{3505}@anchor{library/email policy module-email policy}@anchor{4f}
@subsubsection @code{email.policy}: Policy Objects


@geindex module; email.policy


Ajouté dans la version 3.3.


`Code source :' Lib/email/policy.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/policy.py}


__________________________________________________________________


Le principal objectif du paquet @ref{3b,,email} est la gestion des messages électroniques comme décrit par les diverses RFC de messagerie et MIME. Cependant, le format général des messages électroniques (un bloc de champs d'en-tête composés chacun d'un nom suivi de deux-points suivi d'une valeur, le bloc entier suivi d'une ligne vide et d'un « corps » arbitraire), est un format qui a trouvé son utilité en dehors du domaine du courrier électronique. Certaines de ces utilisations sont assez conformes aux principales RFC de messagerie, d'autres non. Même lorsque vous travaillez avec des e-mails, il est parfois souhaitable de ne pas respecter strictement les RFC, par exemple en générant des e-mails qui interagissent avec des serveurs de messagerie qui ne respectent pas eux-mêmes les normes ou qui implémentent des extensions que vous souhaitez utiliser d'une manière qui enfreint les normes.

Les objets de définition de politique donnent au paquet de messagerie la flexibilité nécessaire pour gérer tous ces cas d'utilisation disparates.

Un objet @ref{1095,,Policy} encapsule un ensemble d'attributs et de méthodes qui contrôlent le comportement de divers composants du paquet de messagerie lors de son utilisation. Les instances @ref{1095,,Policy} peuvent être transmises à diverses classes et méthodes dans le paquet de courrier électronique pour modifier le comportement par défaut. Les valeurs réglables et leurs valeurs par défaut sont décrites ci-dessous.

Il existe une politique par défaut utilisée par toutes les classes dans le paquet de messagerie. Pour toutes les classes @ref{4e,,parser} et les fonctions pratiques associées, et pour la classe @ref{279,,Message}, il s'agit de la politique @ref{1096,,Compat32}, via son instance correspondante prédéfinie @ref{c87,,compat32}. Cette politique fournit une rétrocompatibilité complète (dans certains cas, y compris la compatibilité des bogues) avec la version pré-Python3.3 du paquet de messagerie.

Cette valeur par défaut pour le paramètre nommé `policy' de @ref{278,,EmailMessage} est la politique @ref{1099,,EmailPolicy}, via son instance prédéfinie @ref{34b0,,default}.

Lorsqu'un objet @ref{279,,Message} ou @ref{278,,EmailMessage} est créé, il acquiert une politique. Si le message est créé par un @ref{4e,,parser}, la politique transmise à l'analyseur est la politique utilisée par le message qu'il crée. Si le message est créé par le programme, la stratégie peut être spécifiée lors de sa création. Lorsqu'un message est passé à un @ref{40,,generator}, le générateur utilise la politique du message par défaut, mais vous pouvez également passer une politique spécifique au générateur qui remplace celle stockée sur l'objet message.

La valeur par défaut du paramètre nommé `policy' pour les classes @ref{4e,,email.parser} et les fonctions pratiques de l'analyseur `va changer' dans une future version de Python. Par conséquent, vous devez `toujours spécifier explicitement la stratégie que vous souhaitez utiliser' lors de l'appel de l'une des classes et fonctions décrites dans le module @ref{4e,,parser}.

La première partie de cette documentation couvre les fonctionnalités de @ref{1095,,Policy}, une @ref{1193,,classe mère abstraite} qui définit les fonctionnalités communes à tous les objets de stratégie, y compris @ref{c87,,compat32}. Cela inclut certaines méthodes automatiques (`hooks' en anglais) appelées en interne par le paquet de messagerie, qu'une stratégie personnalisée peut remplacer pour obtenir un comportement différent. La deuxième partie décrit les classes concrètes @ref{1099,,EmailPolicy} et @ref{1096,,Compat32}, qui implémentent les points d'entrée automatiques qui fournissent respectivement le comportement standard et le comportement et les fonctionnalités rétrocompatibles.

Les instances @ref{1095,,Policy} sont immuables, mais elles peuvent être clonées, en acceptant les mêmes arguments nommés que le constructeur de classe et en renvoyant une nouvelle instance @ref{1095,,Policy} qui est une copie de l'original mais avec les valeurs d'attributs spécifiées modifiées.

Par exemple, le code suivant peut être utilisé pour lire un message électronique à partir d'un fichier sur le disque et le transmettre au programme système @code{sendmail} sur un système Unix :

@c from unittest import mock
@c mocker = mock.patch('subprocess.Popen')
@c m = mocker.start()
@c proc = mock.MagicMock()
@c m.return_value = proc
@c proc.stdin.close.return_value = None
@c mymsg = open('mymsg.txt', 'w')
@c mymsg.write('To: abc@xyz.com\n\n')
@c mymsg.flush()

@example
>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
...     msg = message_from_binary_file(f, policy=policy.default)
...
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()
@end example

@c mymsg.close()
@c mocker.stop()
@c import os
@c os.remove('mymsg.txt')

Ici, nous disons à @ref{11ac,,BytesGenerator} d'utiliser les caractères de séparation de ligne corrects de la RFC lors de la création de la chaîne binaire à fournir à @code{stdin} de @code{sendmail}, où la politique par défaut utiliserait @code{\n} comme séparateur de ligne.

Certaines méthodes du paquet de messagerie acceptent un argument nommé `policy', permettant à la politique d'être remplacée pour cette méthode. Par exemple, le code suivant utilise la méthode @ref{f22,,as_bytes()} de l'objet `msg' de l'exemple précédent et écrit le message dans un fichier en utilisant les séparateurs de ligne natifs de la plate-forme sur laquelle il est en cours d'exécution :

@example
>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17
@end example

Les objets de stratégie peuvent également être combinés à l'aide de l'opérateur d'addition, produisant un objet de stratégie dont les paramètres sont une combinaison des objets additionnées (en ne prenant en compte que les paramètres données explicitement) :

@example
>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict
@end example

Cette opération n'est pas commutative ; c'est-à-dire que l'ordre dans lequel les objets sont ajoutés est important. Pour illustrer :

@example
>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100
@end example

@geindex Policy (classe dans email.policy)
@anchor{library/email policy email policy Policy}@anchor{1095}
@deffn {Classe} email.policy.Policy (**kw)

C'est la @ref{1193,,classe mère abstraite} pour toutes les classes de définition de politique. Elle fournit des implémentations par défaut pour quelques méthodes triviales, ainsi que l'implémentation de la propriété d'immutabilité, la méthode @ref{1097,,clone()} et la sémantique du constructeur.

Le constructeur d'une classe de définition de politique peut recevoir divers arguments nommés. Les arguments qui peuvent être spécifiés sont toutes les propriétés qui ne sont pas des méthodes sur cette classe, plus toutes les propriétés qui ne sont pas des méthodes supplémentaires sur la classe concrète. Une valeur spécifiée dans le constructeur remplace la valeur par défaut de l'attribut correspondant.

Cette classe définit les propriétés suivantes, et ainsi les valeurs des éléments suivants peuvent être passées dans le constructeur de n'importe quelle classe de définition de politique :

@geindex max_line_length (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy max_line_length}@anchor{34b2}
@deffn {Attribut} max_line_length

La longueur maximale de toute ligne dans la sortie sérialisée, sans compter le(s) caractère(s) de fin de ligne. La valeur par défaut est 78, selon la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}. Une valeur de @code{0} ou @ref{660,,None} indique qu'aucun retour à la ligne ne doit être fait.
@end deffn

@geindex linesep (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy linesep}@anchor{3506}
@deffn {Attribut} linesep

La chaîne à utiliser pour terminer les lignes dans la sortie sérialisée. La valeur par défaut est @code{\n} car c'est la définition interne de fin de ligne utilisée par Python, bien que @code{\r\n} soit requis par les RFC.
@end deffn

@geindex cte_type (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy cte_type}@anchor{34ff}
@deffn {Attribut} cte_type

Contrôle le type d'encodage de contenu qui peut ou doit être utilisé. Les valeurs possibles sont :


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{7bit}

@tab

toutes les données doivent être « complétement 7 bits » (ASCII uniquement). Cela signifie que si nécessaire, les données seront encodées à l'aide de l'encodage `quoted-printable' ou `base64'.

@item

@code{8bit}

@tab

les données ne sont pas contraintes d'être uniquement sur 7 bits. Les données dans les en-têtes doivent toujours être en ASCII uniquement et seront donc encodées (voir @ref{3507,,fold_binary()} et @ref{de5,,utf8} ci-dessous pour les exceptions), mais les parties du corps peuvent utiliser le @code{8bit} CTE.

@end multitable


Une valeur @code{cte_type} de @code{8bit} ne fonctionne qu'avec @code{BytesGenerator},  et pas avec @code{Generator} car les chaînes ne peuvent pas contenir de données binaires. Si un @code{Generator} fonctionne sous une politique qui spécifie @code{cte_type=8bit}, il agit comme si @code{cte_type} était @code{7bit}.
@end deffn

@geindex raise_on_defect (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy raise_on_defect}@anchor{3508}
@deffn {Attribut} raise_on_defect

Si @ref{bfb,,True}, tous les défauts rencontrés sont signalés comme des erreurs. Si @ref{b25,,False} (la valeur par défaut), les défauts sont passés à la méthode @ref{3509,,register_defect()}.
@end deffn

@geindex mangle_from_ (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy mangle_from_}@anchor{de3}
@deffn {Attribut} mangle_from_

Si @ref{bfb,,True}, les lignes commençant par `"From "' dans le corps sont échappées en mettant un @code{>} devant elles. Ce paramètre est utilisé lorsque le message est sérialisé par un générateur. Par défaut, vaut @ref{b25,,False}.


Ajouté dans la version 3.5.

@end deffn

@geindex message_factory (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy message_factory}@anchor{c86}
@deffn {Attribut} message_factory

Une fonction de fabrique pour construire un nouvel objet de message vide. Utilisé par l'analyseur lors de la construction des messages. La valeur par défaut est @code{None}, @ref{279,,Message} est alors utilisé.


Ajouté dans la version 3.6.

@end deffn

@geindex verify_generated_headers (attribut email.policy.Policy)
@anchor{library/email policy email policy Policy verify_generated_headers}@anchor{1dd}
@deffn {Attribut} verify_generated_headers

If @code{True} (the default), the generator will raise
@ref{350a,,HeaderWriteError} instead of writing a header
that is improperly folded or delimited, such that it would
be parsed as multiple headers or joined with adjacent data.
Such headers can be generated by custom header classes or bugs
in the @code{email} module.

As it's a security feature, this defaults to @code{True} even in the
@ref{1096,,Compat32} policy.
For backwards compatible, but unsafe, behavior, it must be set to
@code{False} explicitly.


Ajouté dans la version 3.13.

@end deffn

La méthode @ref{1095,,Policy} suivante est destinée à être appelée par le code à l'aide de la bibliothèque de messagerie pour créer des instances de stratégie avec des paramètres personnalisés :

@geindex clone() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy clone}@anchor{1097}
@deffn {Méthode} clone (**kw)

Renvoie une nouvelle instance de @ref{1095,,Policy} dont les attributs ont les mêmes valeurs que l'instance actuelle, sauf si ces attributs reçoivent de nouvelles valeurs par les arguments nommés.
@end deffn

Les méthodes @ref{1095,,Policy} restantes sont appelées par le code du paquet de messagerie et ne sont pas destinées à être appelées par une application utilisant le paquet de messagerie. Une stratégie personnalisée doit implémenter toutes ces méthodes.

@geindex handle_defect() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy handle_defect}@anchor{350b}
@deffn {Méthode} handle_defect (obj, defect)

Gère un `defect' trouvé sur `obj'. Lorsque le paquet de messagerie appelle cette méthode, `defect' est toujours une sous-classe de @code{Defect}.

L'implémentation par défaut vérifie le drapeau @ref{3508,,raise_on_defect}. Si c'est @code{True}, `defect' est levé comme une exception. Si c'est @code{False} (par défaut), `obj' et `defect' sont passés à @ref{3509,,register_defect()}.
@end deffn

@geindex register_defect() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy register_defect}@anchor{3509}
@deffn {Méthode} register_defect (obj, defect)

Enregistre un `defect' sur `obj'. Dans le paquet de messagerie, `defect' sera toujours une sous-classe de @code{Defect}.

L'implémentation par défaut appelle la méthode @code{append} de l'attribut @code{defects} de `obj'. Lorsque le paquet de courrier électronique appelle @ref{350b,,handle_defect}, `obj' a normalement un attribut @code{defects} qui a une méthode @code{append}. Les types d'objets personnalisés utilisés avec le paquet de messagerie (par exemple, les objets @code{Message} personnalisés) doivent également fournir un tel attribut, sinon les défauts dans les messages analysés généreront des erreurs inattendues.
@end deffn

@geindex header_max_count() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy header_max_count}@anchor{350c}
@deffn {Méthode} header_max_count (name)

Renvoie le nombre maximal autorisé d'en-têtes nommés `name'.

Appelé lorsqu'un en-tête est ajouté à un objet @ref{278,,EmailMessage} ou @ref{279,,Message}. Si la valeur renvoyée n'est pas @code{0} ou @code{None}, et qu'il y a déjà un certain nombre d'en-têtes avec le nom `name' supérieur ou égal à la valeur renvoyée, une @ref{1ff,,ValueError} est levée.

Parce que le comportement par défaut de @code{Message.__setitem__} est d'ajouter la valeur à la liste des en-têtes, il est facile de créer des en-têtes en double sans s'en rendre compte. Cette méthode permet à certains en-têtes d'être limités dans le nombre d'instances de cet en-tête qui peuvent être ajoutées à un @code{Message} par programme (la limite n'est pas respectée par l'analyseur, qui produit fidèlement autant d'en-têtes qu'il en existe dans le message analysé).

L'implémentation par défaut renvoie @code{None} pour tous les noms d'en-tête.
@end deffn

@geindex header_source_parse() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy header_source_parse}@anchor{350d}
@deffn {Méthode} header_source_parse (sourcelines)

Le paquet de courrier électronique appelle cette méthode avec une liste de chaînes, chaque chaîne se terminant par les caractères de séparation de ligne trouvés dans la source analysée. La première ligne comprend le nom de l'en-tête de champ et le séparateur. Tous les espaces blancs dans la source sont préservés. La méthode doit renvoyer le couple @code{(name, value)} qui doit être stocké dans le @code{Message} pour représenter l'en-tête analysé.

Si une implémentation souhaite conserver la compatibilité avec les politiques de paquet de messagerie existantes, `name' doit être le nom préservé de la casse (tous les caractères jusqu'au séparateur @code{:}), tandis que `value' doit être la valeur dépliée (c.-à-d. tous les caractères de séparation de ligne supprimés, mais les espaces blancs conservés intacts), dépouillés des espaces blancs de tête.

`sourcelines' peut contenir des données binaires échappées de substitution.

Il n'y a pas d'implémentation par défaut
@end deffn

@geindex header_store_parse() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy header_store_parse}@anchor{350e}
@deffn {Méthode} header_store_parse (name, value)

Le paquet de courrier électronique appelle cette méthode avec le nom et la valeur fournis par le programme d'application lorsque le programme d'application modifie un @code{Message} par programme (par opposition à un @code{Message} créé par un analyseur). La méthode doit renvoyer le couple @code{(name, value)} qui doit être stocké dans le @code{Message} pour représenter l'en-tête.

Si une implémentation souhaite conserver la compatibilité avec les politiques existantes du paquet de messagerie, le `name' et la `value' doivent être des chaînes ou des sous-classes de chaînes qui ne modifient pas le contenu des arguments transmis.

Il n'y a pas d'implémentation par défaut
@end deffn

@geindex header_fetch_parse() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy header_fetch_parse}@anchor{350f}
@deffn {Méthode} header_fetch_parse (name, value)

Le paquet de courrier électronique appelle cette méthode avec le `name' et la `value' actuellement stockés dans le @code{Message} lorsque cet en-tête est demandé par le programme d'application, et tout ce que la méthode renvoie est ce qui est renvoyé à l'application comme valeur de l'en-tête récupéré. Notez qu'il peut y avoir plus d'un en-tête avec le même nom stocké dans le @code{Message} ; la méthode reçoit le nom et la valeur spécifiques de l'en-tête destiné à être renvoyé à l'application.

`value' peut contenir des données binaires de substitution échappées. Il ne doit pas y avoir de données binaires échappées de substitution dans la valeur renvoyée par la méthode.

Il n'y a pas d'implémentation par défaut
@end deffn

@geindex fold() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy fold}@anchor{3510}
@deffn {Méthode} fold (name, value)

Le paquet de courrier électronique appelle cette méthode avec le `name' et la `value' actuellement stockés dans le @code{Message} pour un en-tête donné. La méthode doit renvoyer une chaîne qui représente correctement cet en-tête « plié » (selon les paramètres de la politique) en mettant en forme le couple `name' - `value' et en insérant les caractères @ref{3506,,linesep} aux endroits appropriés. Voir 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} pour une discussion sur les règles de mise en forme (« pliage » ou `folding' en anglais) des en-têtes de courrier électronique.

`value' peut contenir des données binaires de substitution échappées. Il ne doit pas y avoir de données binaires échappées de substitution dans la chaîne renvoyée par la méthode.
@end deffn

@geindex fold_binary() (méthode email.policy.Policy)
@anchor{library/email policy email policy Policy fold_binary}@anchor{3507}
@deffn {Méthode} fold_binary (name, value)

Identique à @ref{3510,,fold()}, sauf que la valeur renvoyée doit être un objet bytes plutôt qu'une chaîne.

`value' peut contenir des données binaires de substitution échappées. Celles-ci pourraient être reconverties en données binaires dans l'objet bytes renvoyé.
@end deffn
@end deffn

@geindex EmailPolicy (classe dans email.policy)
@anchor{library/email policy email policy EmailPolicy}@anchor{1099}
@deffn {Classe} email.policy.EmailPolicy (**kw)

Cette @ref{1095,,Policy} concrète fournit un comportement destiné à être entièrement conforme aux RFC de messagerie actuelles. Ce qui inclut (mais n'est pas limité à) la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} et les RFC MIME actuelles.

Cette politique ajoute de nouveaux algorithmes d'analyse d'en-tête et de mise en forme (« pliage »). Au lieu de simples chaînes, les en-têtes sont des sous-classes @code{str} avec des attributs qui dépendent du type du champ. L'algorithme d'analyse et de pliage implémente entièrement la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} et la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}.

La valeur par défaut de l'attribut @ref{c86,,message_factory} est @ref{278,,EmailMessage}.

Outre les attributs définissables répertoriés ci-dessus qui s'appliquent à toutes les règles, cette règle ajoute les attributs supplémentaires suivants :


Ajouté dans la version 3.6: @footnote{
Initialement ajouté dans 3.3 en tant que @ref{102a,,paquet provisoire}.
}


@geindex utf8 (attribut email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy utf8}@anchor{de5}
@deffn {Attribut} utf8

Si c'est @code{False}, suit la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, en prenant en charge les caractères non-ASCII dans les en-têtes en les encodant comme des « mots encodés ». Si c'est @code{True}, suit la 
@geindex RFC; RFC 6532
RFC 6532@footnote{https://datatracker.ietf.org/doc/html/rfc6532.html} et utilise l'encodage @code{utf-8} pour les en-têtes. Les messages formatés de cette manière peuvent être transmis aux serveurs SMTP qui gèrent l'extension @code{SMTPUTF8} (
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}).
@end deffn

@geindex refold_source (attribut email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy refold_source}@anchor{34fc}
@deffn {Attribut} refold_source

Si la valeur d'un en-tête dans l'objet @code{Message} provient d'un @ref{4e,,parser} (au lieu d'être définie par un programme), cet attribut indique si un générateur doit ou non remettre en forme cette valeur lorsqu'il retransforme le message sous forme sérialisée. Les valeurs possibles sont :


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@code{none}

@tab

toutes les valeurs sources utilisent la mise en forme (`folding' en anglais) d'origine

@item

@code{long}

@tab

les valeurs sources dont une ligne est plus longue que @code{max_line_length} sont remises en forme

@item

@code{all}

@tab

toutes les valeurs sont remises en forme.

@end multitable


La valeur par défaut est @code{long}.
@end deffn

@geindex header_factory (attribut email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_factory}@anchor{3511}
@deffn {Attribut} header_factory

Appelable qui prend deux arguments, @code{name} et @code{value}, où @code{name} est un nom de champ d'en-tête et @code{value} est une valeur de champ d'en-tête dépliée (c-à-d. sans retours à la ligne de mise en forme), et renvoie une sous-classe de chaîne qui représente cet en-tête. Un @code{header_factory} par défaut (voir @ref{42,,headerregistry}) est fourni qui prend en charge l'analyse personnalisée pour les divers types de champs d'en-tête d'adresse et de date 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, et les principaux types de champs d'en-tête MIME. La prise en charge d'une analyse personnalisée supplémentaire sera ajoutée à l'avenir.
@end deffn

@geindex content_manager (attribut email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy content_manager}@anchor{f26}
@deffn {Attribut} content_manager

Objet avec au moins deux méthodes : `get_content' et `set_content'. Lorsque la méthode @ref{34dd,,get_content()} ou @ref{1836,,set_content()} d'un objet @ref{278,,EmailMessage} est appelée, elle appelle la méthode correspondante de cet objet, en lui transmettant l'objet message comme premier argument, et tous les arguments positionnels ou nommés qui lui ont été transmis comme arguments supplémentaires. Par défaut, @code{content_manager} est défini sur @ref{3512,,raw_data_manager}.


Ajouté dans la version 3.4.

@end deffn

La classe fournit les implémentations concrètes suivantes des méthodes abstraites de @ref{1095,,Policy} :

@geindex header_max_count() (méthode email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_max_count}@anchor{3513}
@deffn {Méthode} header_max_count (name)

Renvoie la valeur de l'attribut @ref{3514,,max_count} de la classe spécialisée utilisée pour représenter l'en-tête avec le nom donné.
@end deffn

@geindex header_source_parse() (méthode email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_source_parse}@anchor{152c}
@deffn {Méthode} header_source_parse (sourcelines)

Le nom est analysé comme le reste jusqu'au @code{:} et renvoyé sans modification. La valeur est déterminée en supprimant les espaces blancs de début du reste de la première ligne, en joignant toutes les lignes suivantes et en supprimant tous les caractères de retour chariot ou de saut de ligne de fin.
@end deffn

@geindex header_store_parse() (méthode email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_store_parse}@anchor{3515}
@deffn {Méthode} header_store_parse (name, value)

Le nom est renvoyé tel quel. Si la valeur d'entrée a un attribut @code{name} et qu'elle correspond à `name' sans tenir compte de la casse, la valeur est renvoyée inchangée. Sinon, le `name' et la `value' sont passés à @code{header_factory}, et l'objet d'en-tête résultant est renvoyé comme valeur. Dans ce cas, une @code{ValueError} est levée si la valeur d'entrée contient des caractères CR ou LF.
@end deffn

@geindex header_fetch_parse() (méthode email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy header_fetch_parse}@anchor{3516}
@deffn {Méthode} header_fetch_parse (name, value)

Si la valeur a un attribut @code{name}, elle est renvoyée sans modification. Sinon, le `name' et la `value' sans les caractères CR ou LF sont passés à @code{header_factory}, et l'objet d'en-tête résultant est renvoyé. Tous les octets échappés de substitution sont transformés en glyphe Unicode de caractère inconnu.
@end deffn

@geindex fold() (méthode email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy fold}@anchor{15fe}
@deffn {Méthode} fold (name, value)

La mise en forme d'en-tête est contrôlée par le paramètre de politique @ref{34fc,,refold_source}. Une valeur est considérée comme une « valeur source » si et seulement si elle n'a pas d'attribut @code{name} (avoir un attribut @code{name} signifie qu'il s'agit d'un objet d'en-tête quelconque). Si une valeur source doit être mise en forme conformément à la politique, elle est convertie en un objet d'en-tête en passant le `name' et la `value' avec tous les caractères CR et LF supprimés à @code{header_factory}. La mise en forme multi-lignes d'un objet d'en-tête (« pliage » ou `folding' en anglais) se fait en appelant sa méthode @code{fold} avec la politique actuelle.

Les valeurs sources sont divisées en lignes en utilisant @ref{1235,,splitlines()}. Si la valeur ne doit pas être remise en forme, les lignes sont jointes en utilisant le caractère @code{linesep} de la politique et renvoyées. L'exception concerne les lignes contenant des données binaires non ASCII. Dans ce cas, la valeur est remise en forme quel que soit le paramètre @code{refold_source}, ce qui entraîne le codage CTE des données binaires à l'aide du jeu de caractères @code{unknown-8bit}.
@end deffn

@geindex fold_binary() (méthode email.policy.EmailPolicy)
@anchor{library/email policy email policy EmailPolicy fold_binary}@anchor{3517}
@deffn {Méthode} fold_binary (name, value)

Identique à @ref{15fe,,fold()} si @ref{34ff,,cte_type} vaut @code{7bit}, sauf que la valeur renvoyée est de type `bytes'.

Si @ref{34ff,,cte_type} est @code{8bit}, les données binaires non-ASCII sont reconverties en octets. Les en-têtes contenant des données binaires ne sont pas remises en forme, quel que soit le paramètre @code{refold_header}, puisqu'il n'y a aucun moyen de savoir si les données binaires sont constituées de caractères à un seul octet ou de caractères à plusieurs octets.
@end deffn
@end deffn

Les instances suivantes de @ref{1099,,EmailPolicy} fournissent des valeurs par défaut adaptées à des domaines d'application spécifiques. Notez qu'à l'avenir, le comportement de ces instances (en particulier l'instance @code{HTTP}) pourra être ajusté pour se conformer encore plus étroitement aux RFC relatives à leurs domaines.

@geindex default (dans le module email.policy)
@anchor{library/email policy email policy default}@anchor{34b0}
@deffn {Données} email.policy.default

Une instance de @code{EmailPolicy} avec toutes les valeurs par défaut inchangées. Cette politique utilise les fins de ligne standard Python @code{\n} plutôt que le @code{\r\n} conforme à la RFC.
@end deffn

@geindex SMTP (dans le module email.policy)
@anchor{library/email policy email policy SMTP}@anchor{3518}
@deffn {Données} email.policy.SMTP

Convient pour la sérialisation des messages conformément aux RFC des e-mails. Comme @code{default}, mais avec @code{linesep} défini sur @code{\r\n}, ce qui est conforme à la RFC.
@end deffn

@geindex SMTPUTF8 (dans le module email.policy)
@anchor{library/email policy email policy SMTPUTF8}@anchor{3519}
@deffn {Données} email.policy.SMTPUTF8

Identique à @code{SMTP} sauf que @ref{de5,,utf8} vaut @code{True}. Utile pour sérialiser des messages dans une banque de messages sans utiliser de mots encodés dans les en-têtes. Ne doit être utilisée pour la transmission SMTP que si les adresses de l'expéditeur ou du destinataire contiennent des caractères non ASCII (la méthode @ref{e43,,smtplib.SMTP.send_message()} gère cela automatiquement).
@end deffn

@geindex HTTP (dans le module email.policy)
@anchor{library/email policy email policy HTTP}@anchor{351a}
@deffn {Données} email.policy.HTTP

Convient pour la sérialisation des en-têtes à utiliser dans le trafic HTTP. Comme @code{SMTP} sauf que @code{max_line_length} est défini sur @code{None} (illimité).
@end deffn

@geindex strict (dans le module email.policy)
@anchor{library/email policy email policy strict}@anchor{351b}
@deffn {Données} email.policy.strict

Exemple de commodité. Identique à @code{default} sauf que @code{raise_on_defect} est défini sur @code{True}. Cela permet de rendre stricte toute politique en écrivant :

@example
somepolicy + policy.strict
@end example
@end deffn

Avec toutes ces @ref{1099,,EmailPolicies}, l'API effective du paquet de messagerie est modifiée par rapport à l'API Python 3.2 de la manière suivante :


@itemize *

@item 
Définir un en-tête sur un @ref{279,,Message} entraîne l'analyse de cet en-tête et la création d'un objet d'en-tête.

@item 
La récupération d'une valeur d'en-tête à partir d'un @ref{279,,Message} entraîne l'analyse de cet en-tête ainsi que la création et le renvoi d'un objet d'en-tête.

@item 
Tout objet d'en-tête, ou tout en-tête qui est remis en forme en raison des paramètres de politique, est mis en forme à l'aide d'un algorithme qui implémente entièrement les algorithmes de pliage de la RFC, notamment en sachant où les mots encodés sont requis et autorisés.
@end itemize

Du point de vue de l'application, cela signifie que tout en-tête obtenu via @ref{278,,EmailMessage} est un objet d'en-tête avec des attributs supplémentaires, dont la valeur de chaîne est la valeur Unicode entièrement décodée de l'en-tête. De même, un en-tête peut se voir attribuer une nouvelle valeur, ou un nouvel en-tête créé, à l'aide d'une chaîne Unicode, et la politique se chargera de convertir la chaîne Unicode dans la forme encodée RFC correcte.

Les objets d'en-tête et leurs attributs sont décrits dans @ref{42,,headerregistry}.

@geindex Compat32 (classe dans email.policy)
@anchor{library/email policy email policy Compat32}@anchor{1096}
@deffn {Classe} email.policy.Compat32 (**kw)

Cette @ref{1095,,Policy} concrète est la politique de rétrocompatibilité. Elle reproduit le comportement du paquet de courrier électronique dans Python 3.2. Le module @ref{4f,,policy} définit également une instance de cette classe, @ref{c87,,compat32}, qui est utilisée comme politique par défaut. Ainsi, le comportement par défaut du paquet de messagerie est de maintenir la compatibilité avec Python 3.2.

Les attributs suivants ont des valeurs différentes de la valeur par défaut de @ref{1095,,Policy} :

@geindex mangle_from_ (attribut email.policy.Compat32)
@anchor{library/email policy email policy Compat32 mangle_from_}@anchor{351c}
@deffn {Attribut} mangle_from_

La valeur par défaut est @code{True}.
@end deffn

La classe fournit les implémentations concrètes suivantes des méthodes abstraites de @ref{1095,,Policy} :

@geindex header_source_parse() (méthode email.policy.Compat32)
@anchor{library/email policy email policy Compat32 header_source_parse}@anchor{152d}
@deffn {Méthode} header_source_parse (sourcelines)

Le nom est analysé comme le reste jusqu'au @code{:} et renvoyé sans modification. La valeur est déterminée en supprimant les espaces blancs de début du reste de la première ligne, en joignant toutes les lignes suivantes et en supprimant tous les caractères de retour chariot ou de saut de ligne de fin.
@end deffn

@geindex header_store_parse() (méthode email.policy.Compat32)
@anchor{library/email policy email policy Compat32 header_store_parse}@anchor{351d}
@deffn {Méthode} header_store_parse (name, value)

Le nom et la valeur sont renvoyés sans modification.
@end deffn

@geindex header_fetch_parse() (méthode email.policy.Compat32)
@anchor{library/email policy email policy Compat32 header_fetch_parse}@anchor{351e}
@deffn {Méthode} header_fetch_parse (name, value)

Si la valeur contient des données binaires, elle est convertie en un objet @ref{1837,,Header} en utilisant le jeu de caractères @code{unknown-8bit}. Sinon, elle est renvoyée sans modification.
@end deffn

@geindex fold() (méthode email.policy.Compat32)
@anchor{library/email policy email policy Compat32 fold}@anchor{351f}
@deffn {Méthode} fold (name, value)

Les en-têtes sont mis en forme à l'aide de l'algorithme de pliage @ref{1837,,Header}, qui préserve les sauts de ligne existants dans la valeur et encapsule chaque ligne résultante dans la @code{max_line_length}. Les données binaires non-ASCII sont codées en CTE à l'aide du jeu de caractères @code{unknown-8bit}.
@end deffn

@geindex fold_binary() (méthode email.policy.Compat32)
@anchor{library/email policy email policy Compat32 fold_binary}@anchor{3520}
@deffn {Méthode} fold_binary (name, value)

Les en-têtes sont mis en forme à l'aide de l'algorithme de pliage @ref{1837,,Header}, qui préserve les sauts de ligne existants dans la valeur et encapsule chaque ligne résultante dans la @code{max_line_length}. Si @code{cte_type} est @code{7bit}, les données binaires non-ASCII sont encodées en CTE en utilisant le jeu de caractères @code{unknown-8bit}. Sinon, l'en-tête source d'origine est utilisé, avec ses sauts de ligne existants et toutes les données binaires (non conformes à la RFC) qu'il peut contenir.
@end deffn
@end deffn

@geindex compat32 (dans le module email.policy)
@anchor{library/email policy email policy compat32}@anchor{c87}
@deffn {Données} email.policy.compat32

Instance de @ref{1096,,Compat32}, offrant une rétrocompatibilité avec le comportement du paquet de messagerie dans Python 3.2.
@end deffn

@subsubheading Notes


@node email errors Exception and Defect classes,email headerregistry Custom Header Objects,email policy Policy Objects,email --- An email and MIME handling package
@anchor{library/email errors doc}@anchor{3521}@anchor{library/email errors email-errors-exception-and-defect-classes}@anchor{3522}@anchor{library/email errors module-email errors}@anchor{3f}
@subsubsection @code{email.errors}: Exception and Defect classes


@geindex module; email.errors

`Code source :' Lib/email/errors.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/errors.py}


__________________________________________________________________


Les classes d'exception suivantes sont définies dans le module @ref{3f,,email.errors} :

@geindex MessageError
@anchor{library/email errors email errors MessageError}@anchor{3523}
@deffn {Exception} email.errors.MessageError

Exception de base, dont héritent toutes les exceptions du paquet @ref{3b,,email}. Cette classe hérite de la classe native @ref{9c7,,Exception} et ne définit aucune méthode additionnelle.
@end deffn

@geindex MessageParseError
@anchor{library/email errors email errors MessageParseError}@anchor{3524}
@deffn {Exception} email.errors.MessageParseError

Exception de base pour les exceptions levées par la classe  @ref{117c,,Parser}. Elle hérite de @ref{3523,,MessageError}. Cette classe est aussi utilisée en interne par l'analyseur de @ref{42,,headerregistry}.
@end deffn

@geindex HeaderParseError
@anchor{library/email errors email errors HeaderParseError}@anchor{34d3}
@deffn {Exception} email.errors.HeaderParseError

Cette exception, dérivée de  @ref{3524,,MessageParseError}, est levée sous différentes conditions lors de l'analyse des en-têtes 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} du message.  Lorsque la  méthode @ref{34d2,,set_boundary()} est invoquée, elle lève cette erreur si le type du contenu est inconnu.  La classe @ref{1837,,Header} lève cette exception pour certains types d'erreurs provenant du décodage base64.  Elle la lève aussi  quand un en-tête est créé et qu'il semble contenir un en-tête imbriqué, c'est-à-dire que la ligne qui suit ressemble à un en-tête et ne commence pas par des caractères d'espacement.
@end deffn

@geindex BoundaryError
@anchor{library/email errors email errors BoundaryError}@anchor{3525}
@deffn {Exception} email.errors.BoundaryError

Obsolète, n'est plus utilisé.
@end deffn

@geindex MultipartConversionError
@anchor{library/email errors email errors MultipartConversionError}@anchor{3526}
@deffn {Exception} email.errors.MultipartConversionError

Cette exception est levée quand le contenu, que la méthode @code{add_payload()} essaie d'ajouter à l'objet @ref{279,,Message}, est déjà un scalaire et que le type principal du message  @code{Content-Type} est manquant ou différent de  @code{multipart}.  @ref{3526,,MultipartConversionError} hérite à la fois de  @ref{3523,,MessageError} et de @ref{522,,TypeError}.

Comme la méthode @code{Message.add_payload()} est obsolète, cette exception est rarement utilisée. Néanmoins, elle peut être levée si la méthode  @ref{34e4,,attach()} est invoquée sur une instance de classe dérivée de @ref{3527,,MIMENonMultipart} (p. ex. @ref{3528,,MIMEImage}).
@end deffn

@geindex HeaderWriteError
@anchor{library/email errors email errors HeaderWriteError}@anchor{350a}
@deffn {Exception} email.errors.HeaderWriteError

Raised when an error occurs when the @ref{40,,generator} outputs
headers.
@end deffn

@geindex MessageDefect
@anchor{library/email errors email errors MessageDefect}@anchor{3529}
@deffn {Exception} email.errors.MessageDefect

This is the base class for all defects found when parsing email messages.
It is derived from @ref{1ff,,ValueError}.
@end deffn

@geindex HeaderDefect
@anchor{library/email errors email errors HeaderDefect}@anchor{352a}
@deffn {Exception} email.errors.HeaderDefect

This is the base class for all defects found when parsing email headers.
It is derived from @ref{3529,,MessageDefect}.
@end deffn

Voici la liste des anomalies que peut identifier @ref{34ee,,FeedParser} pendant l'analyse des messages. Notez que les anomalies sont signalées à l'endroit où elles sont détectées : par exemple, dans le cas d'une malformation de l'en-tête d'un message imbriqué dans un message de type  @code{multipart/alternative}, l'anomalie est signalée sur le message imbriqué seulement.

Toutes les anomalies sont des sous-classes de  @ref{3529,,email.errors.MessageDefect}.


@itemize *

@item 
@code{NoBoundaryInMultipartDefect} — Un message qui prétend être composite (`multipart' en anglais), mais qui ne contient pas de séparateur  @code{boundary}.

@item 
@code{StartBoundaryNotFoundDefect} — Le message ne contient pas le séparateur de départ indiqué dans le @code{Content-Type}.

@item 
@code{CloseBoundaryNotFoundDefect} — Le séparateur de départ a été trouvé, mais pas le séparateur de fin correspondant.


Ajouté dans la version 3.3.


@item 
@code{FirstHeaderLineIsContinuationDefect} — La première ligne de l'en-tête du message est une ligne de continuation.

@item 
@code{MisplacedEnvelopeHeaderDefect} — Un en-tête `Unix From' est présent à l'intérieur d'un bloc d'en-tête.

@item 
@code{MissingHeaderBodySeparatorDefect} — Une ligne d'en-tête ne contient pas de caractères d'espacement au début et aucun « : ». L'analyse continue en supposant qu'il s'agit donc de la première ligne du corps du message.


Ajouté dans la version 3.3.


@item 
@code{MalformedHeaderDefect} -- Un en-tête est mal formé ou il manque un « : ».


Obsolète depuis la version 3.3: Cette anomalie est obsolète depuis plusieurs versions de Python.


@item 
@code{MultipartInvariantViolationDefect} — Le message indique être de type @code{multipart}, mais aucune pièce jointe n'a été trouvée.  Notez que, dans ce cas, la méthode @ref{34d7,,is_multipart()} peut renvoyer @code{False} même si le type de contenu est @code{multipart}.

@item 
@code{InvalidBase64PaddingDefect} — Remplissage incorrect d'un bloc d'octets encodés en base64.  Des caractères de remplissage ont été ajoutés pour permettre le décodage, mais le résultat du décodage peut être invalide.

@item 
@code{InvalidBase64CharactersDefect} — Des caractères n'appartenant pas à l'alphabet base64 ont été rencontrés lors du décodage d'un bloc d'octets encodés en base64.  Les caractères ont été ignorés, mais le résultat du décodage peut être invalide.

@item 
@code{InvalidBase64LengthDefect} — Le nombre de caractères (autres que de remplissage) d'un bloc d'octets encodés en base64 est invalide (1 de plus qu'un multiple de 4).  Le bloc encodé n'a pas été modifié.

@item 
@code{InvalidDateDefect} — Le champ de date est invalide. La valeur est laissée telle-quelle.
@end itemize

@node email headerregistry Custom Header Objects,email contentmanager Managing MIME Content,email errors Exception and Defect classes,email --- An email and MIME handling package
@anchor{library/email headerregistry doc}@anchor{352b}@anchor{library/email headerregistry email-headerregistry-custom-header-objects}@anchor{352c}@anchor{library/email headerregistry module-email headerregistry}@anchor{42}
@subsubsection @code{email.headerregistry}: Custom Header Objects


@geindex module; email.headerregistry

`Code source :' Lib/email/headerregistry.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/headerregistry.py}


__________________________________________________________________



Ajouté dans la version 3.6: @footnote{
Ajouté à l'origine dans 3.3 en tant que @ref{102a,,paquet provisoire}
}


Les en-têtes sont représentés par des sous-classes personnalisées de @ref{435,,str}. La classe particulière utilisée pour représenter un en-tête donné est déterminée par @ref{3511,,header_factory} de la @ref{4f,,policy} en vigueur lorsque les en-têtes sont créés. Cette section documente la @code{header_factory} particulière implémentée par le paquet de messagerie pour la gestion des messages électroniques conformes à la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, qui fournit non seulement des objets d'en-tête personnalisés pour différents types d'en-tête, mais fournit également un mécanisme d'extension permettant aux applications d'ajouter leurs propres types d'en-tête personnalisés.

Lors de l'utilisation de l'un des objets de définition de politique dérivés de @ref{1099,,EmailPolicy}, tous les en-têtes sont produits par @ref{352d,,HeaderRegistry} et ont @ref{34bf,,BaseHeader} comme dernière classe mère. Chaque classe d'en-tête a une classe mère supplémentaire qui est déterminée par le type de l'en-tête. Par exemple, de nombreux en-têtes ont la classe @ref{352e,,UnstructuredHeader} comme autre classe mère. La deuxième classe spécialisée pour un en-tête est déterminée par le nom de l'en-tête, en utilisant un tableau de recherche stocké dans @ref{352d,,HeaderRegistry}. Tout cela est géré de manière transparente pour le programme d'application typique, mais des interfaces sont fournies pour modifier le comportement par défaut pour une utilisation par des applications plus complexes.

Les sections ci-dessous documentent d'abord les classes mères d'en-tête et leurs attributs, suivies de l'API pour modifier le comportement de @ref{352d,,HeaderRegistry}, et enfin les classes de gestion utilisées pour représenter les données analysées à partir d'en-têtes structurés.

@geindex BaseHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry BaseHeader}@anchor{34bf}
@deffn {Classe} email.headerregistry.BaseHeader (name, value)

`name' et `value' sont passés à @code{BaseHeader} à partir de l'appel @ref{3511,,header_factory}. La valeur de chaîne de tout objet d'en-tête est la `value' entièrement décodée en Unicode.

Cette classe mère définit les propriétés en lecture seule suivantes :

@geindex name (attribut email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader name}@anchor{352f}
@deffn {Attribut} name

Nom de l'en-tête (la partie du champ avant le @code{:}). C'est exactement la valeur passée dans l'appel @ref{3511,,header_factory} pour `name' ; c'est-à-dire que la casse est préservée.
@end deffn

@geindex defects (attribut email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader defects}@anchor{3530}
@deffn {Attribut} defects

`n'-uplet d'instances @ref{352a,,HeaderDefect} signalant tout problème de conformité avec les RFC détecté lors de l'analyse. Le paquet d'e-mails tente d'être complet en ce qui concerne la détection des problèmes de conformité. Voir le module @ref{3f,,errors} pour une discussion sur les types de défauts qui peuvent être signalés.
@end deffn

@geindex max_count (attribut email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader max_count}@anchor{3514}
@deffn {Attribut} max_count

Nombre maximum d'en-têtes de ce type pouvant avoir le même @code{name}. Une valeur de @code{None} signifie illimité. La valeur @code{BaseHeader} pour cet attribut est @code{None} ; les classes d'en-tête spécialisées sont censées remplacer cette valeur si nécessaire.
@end deffn

@code{BaseHeader} fournit également la méthode suivante, qui est appelée par le code de la bibliothèque de messagerie et ne doit généralement pas être appelée par les programmes d'application :

@geindex fold() (méthode email.headerregistry.BaseHeader)
@anchor{library/email headerregistry email headerregistry BaseHeader fold}@anchor{3531}
@deffn {Méthode} fold (*, policy)

Renvoie une chaîne contenant les caractères @ref{3506,,linesep} nécessaires pour remettre en forme correctement l'en-tête conformément à `policy'. Un @ref{34ff,,cte_type} de @code{8bit} est traité comme s'il s'agissait de @code{7bit}, car les en-têtes ne peuvent pas contenir de données binaires arbitraires. Si @ref{de5,,utf8} est @code{False}, les données non-ASCII seront encodées selon la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}.
@end deffn

@code{BaseHeader} seule ne peut pas être utilisée pour créer un objet d'en-tête. Elle définit un protocole avec lequel chaque en-tête spécialisé coopère afin de produire l'objet d'en-tête. Plus précisément, @code{BaseHeader} nécessite que la classe spécialisée fournisse une @ref{165,,classmethod()} nommée @code{parse}. Cette méthode s'appelle comme suit :

@example
parse(string, kwds)
@end example

@code{kwds} est un dictionnaire contenant une clé pré-initialisée : @code{defects}. @code{defects} est une liste vide. La méthode d'analyse doit ajouter tous les défauts détectés à cette liste. Au retour, le dictionnaire @code{kwds} `doit' contenir des valeurs pour au moins les clés @code{decoded} et @code{defects}. @code{decoded} doit être la valeur de la chaîne pour l'en-tête (c'est-à-dire la valeur de l'en-tête entièrement décodée en Unicode). La méthode d'analyse doit supposer que `string' peut contenir des parties codées par transfert de contenu, mais doit également gérer correctement tous les caractères Unicode valides afin de pouvoir analyser les valeurs d'en-tête non codées.

@code{__new__} de @code{BaseHeader} crée ensuite l'instance d'en-tête et appelle sa méthode @code{init}. La classe spécialisée n'a besoin de fournir une méthode @code{init} que si elle souhaite définir des attributs supplémentaires au-delà de ceux fournis par @code{BaseHeader} lui-même. Une telle méthode @code{init} devrait ressembler à ceci :

@example
def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)
@end example

Autrement dit, tout ce que la classe spécialisée ajoute au dictionnaire @code{kwds} doit être supprimé et géré, et le contenu restant de @code{kw} (et @code{args}) est passé à la méthode @code{init} de  @code{BaseHeader}.
@end deffn

@geindex UnstructuredHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry UnstructuredHeader}@anchor{352e}
@deffn {Classe} email.headerregistry.UnstructuredHeader

Un en-tête « non structuré » est le type d'en-tête par défaut dans la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}. Tout en-tête qui n'a pas de syntaxe spécifiée est traité comme non structuré. L'exemple classique d'en-tête non structuré est l'en-tête @code{Subject}.

Dans la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, un en-tête non structuré est une séquence de texte arbitraire dans le jeu de caractères ASCII. 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}, cependant, possède un mécanisme compatible 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} pour encoder du texte non-ASCII en tant que caractères ASCII dans une valeur d'en-tête. Lorsqu'une `value' contenant des mots encodés est passée au constructeur, l'analyseur @code{UnstructuredHeader} convertit ces mots encodés en Unicode, en suivant les règles de la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} pour le texte non structuré. L'analyseur utilise des heuristiques pour tenter de décoder certains mots codés non conformes. Des défauts sont enregistrés dans de tels cas, ainsi que des défauts pour des problèmes tels que des caractères non valides dans les mots codés ou le texte non codé.

Ce type d'en-tête ne fournit aucun attribut supplémentaire.
@end deffn

@geindex DateHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry DateHeader}@anchor{3532}
@deffn {Classe} email.headerregistry.DateHeader

La 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} spécifie un format très spécifique pour les dates dans les en-têtes de courrier électronique. L'analyseur @code{DateHeader} reconnaît ce format de date, ainsi qu'un certain nombre de formes variantes que l'on trouve parfois « dans la nature ».

Ce type d'en-tête fournit les attributs supplémentaires suivants :

@geindex datetime (attribut email.headerregistry.DateHeader)
@anchor{library/email headerregistry email headerregistry DateHeader datetime}@anchor{3533}
@deffn {Attribut} datetime

Si la valeur d'en-tête peut être reconnue comme une date valide d'une forme ou d'une autre, cet attribut contient une instance @ref{1c7,,datetime} représentant cette date. Si le fuseau horaire de la date d'entrée est spécifié comme @code{-0000} (indiquant qu'il est en UTC mais ne contient aucune information sur le fuseau horaire source), alors @ref{3533,,datetime} est une @ref{1c7,,datetime} naïve. Si un décalage de fuseau horaire spécifique est trouvé (y compris @code{+0000}), alors @ref{3533,,datetime} contient un @code{datetime} avisé qui utilise @ref{10a1,,datetime.timezone} pour enregistrer le décalage lié au fuseau horaire.
@end deffn

La valeur @code{decoded} de l'en-tête est déterminée en formatant le @code{datetime} selon les règles de la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html} ; c'est-à-dire qu'elle est définie sur :

@example
email.utils.format_datetime(self.datetime)
@end example

Lors de la création d'un @code{DateHeader}, `value' peut être une instance de @ref{1c7,,datetime}. Cela signifie, par exemple, que le code suivant est valide et fait ce à quoi on pourrait s'attendre :

@example
msg['Date'] = datetime(2011, 7, 15, 21)
@end example

Comme il s'agit d'un @code{datetime} naïf, il est interprété comme un horodatage UTC et la valeur résultante a un fuseau horaire de @code{-0000}. Il est beaucoup plus utile d'utiliser la fonction @ref{2c2,,localtime()} du module @ref{50,,utils} :

@example
msg['Date'] = utils.localtime()
@end example

Cet exemple définit l'en-tête de date sur l'heure et la date actuelles à l'aide du décalage horaire actuel.
@end deffn

@geindex AddressHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry AddressHeader}@anchor{3534}
@deffn {Classe} email.headerregistry.AddressHeader

Les en-têtes d'adresse sont l'un des types d'en-têtes structurés les plus complexes. La classe @code{AddressHeader} fournit une interface générique à n'importe quel en-tête d'adresse.

Ce type d'en-tête fournit les attributs supplémentaires suivants :

@geindex groups (attribut email.headerregistry.AddressHeader)
@anchor{library/email headerregistry email headerregistry AddressHeader groups}@anchor{3535}
@deffn {Attribut} groups

`n'-uplet d'objets @ref{3536,,Group} encodant les adresses et les groupes trouvés dans la valeur d'en-tête. Les adresses qui ne font pas partie d'un groupe sont représentées dans cette liste comme des @code{Groups} à adresse unique dont @ref{3537,,display_name} est @code{None}.
@end deffn

@geindex addresses (attribut email.headerregistry.AddressHeader)
@anchor{library/email headerregistry email headerregistry AddressHeader addresses}@anchor{3538}
@deffn {Attribut} addresses

`n'-uplet d'objets @ref{3539,,Address} encodant toutes les adresses individuelles à partir de la valeur d'en-tête. Si la valeur d'en-tête contient des groupes, les adresses individuelles du groupe sont incluses dans la liste au point où le groupe apparaît dans la valeur (c'est-à-dire que la liste d'adresses est « aplatie » en une liste unidimensionnelle).
@end deffn

La valeur @code{decoded} de l'en-tête a tous les mots codés décodés en Unicode. Les noms de domaine encodés en @ref{51,,idna} sont également décodés en Unicode. La valeur @code{decoded} est définie en @ref{2150,,joignant} la valeur @ref{435,,str} des éléments de l'attribut @code{groups} avec @code{', '}.

Une liste d'objets @ref{3539,,Address} et @ref{3536,,Group} dans n'importe quelle combinaison peut être utilisée pour définir la valeur d'un en-tête d'adresse. Les objets @code{Group} dont le @code{display_name} est @code{None} sont interprétés comme des adresses uniques, ce qui permet de copier une liste d'adresses avec des groupes intacts en utilisant la liste obtenue à partir de l'attribut @code{groups} de l'en-tête source.
@end deffn

@geindex SingleAddressHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry SingleAddressHeader}@anchor{353a}
@deffn {Classe} email.headerregistry.SingleAddressHeader

Sous-classe de @ref{3534,,AddressHeader} qui ajoute un attribut supplémentaire :

@geindex address (attribut email.headerregistry.SingleAddressHeader)
@anchor{library/email headerregistry email headerregistry SingleAddressHeader address}@anchor{353b}
@deffn {Attribut} address

Adresse unique codée par la valeur d'en-tête. Si la valeur d'en-tête contient en fait plus d'une adresse (ce qui serait une violation de la RFC sous la valeur par défaut @ref{4f,,policy}), l'accès à cet attribut lève une @ref{1ff,,ValueError}.
@end deffn
@end deffn

La plupart des classes ci-dessus ont également une variante @code{Unique} (par exemple, @code{UniqueUnstructuredHeader}). La seule différence est que dans la variante @code{Unique}, @ref{3514,,max_count} est définie sur 1.

@geindex MIMEVersionHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader}@anchor{353c}
@deffn {Classe} email.headerregistry.MIMEVersionHeader

Il n'y a vraiment qu'une seule valeur valide pour l'en-tête @code{MIME-Version}, et c'est @code{1.0}. Au cas où, cette classe d'en-tête prend en charge d'autres numéros de version valides. Si un numéro de version a une valeur valide selon la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, alors l'objet d'en-tête a des valeurs autres que @code{None} pour les attributs suivants :

@geindex version (attribut email.headerregistry.MIMEVersionHeader)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader version}@anchor{353d}
@deffn {Attribut} version

Numéro de version sous forme de chaîne, sans espaces ni commentaires.
@end deffn

@geindex major (attribut email.headerregistry.MIMEVersionHeader)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader major}@anchor{353e}
@deffn {Attribut} major

Numéro de version majeure sous forme d'entier
@end deffn

@geindex minor (attribut email.headerregistry.MIMEVersionHeader)
@anchor{library/email headerregistry email headerregistry MIMEVersionHeader minor}@anchor{353f}
@deffn {Attribut} minor

Numéro de version mineure sous forme d'entier
@end deffn
@end deffn

@geindex ParameterizedMIMEHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry ParameterizedMIMEHeader}@anchor{3540}
@deffn {Classe} email.headerregistry.ParameterizedMIMEHeader

Les en-têtes MIME commencent tous par le préfixe @code{'Content-'}. Chaque en-tête spécifique a une certaine valeur, décrite par la classe de cet en-tête. Certains peuvent également prendre une liste de paramètres supplémentaires, qui ont un format commun. Cette classe sert de base à tous les en-têtes MIME qui prennent des paramètres.

@geindex params (attribut email.headerregistry.ParameterizedMIMEHeader)
@anchor{library/email headerregistry email headerregistry ParameterizedMIMEHeader params}@anchor{34cd}
@deffn {Attribut} params

Dictionnaire de correspondance entre les noms de paramètres et leurs valeurs.
@end deffn
@end deffn

@geindex ContentTypeHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader}@anchor{3541}
@deffn {Classe} email.headerregistry.ContentTypeHeader

Classe @ref{3540,,ParameterizedMIMEHeader} qui gère l'en-tête @code{Content-Type}.

@geindex content_type (attribut email.headerregistry.ContentTypeHeader)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader content_type}@anchor{3542}
@deffn {Attribut} content_type

Chaîne de type de contenu, sous la forme @code{maintype/subtype}.
@end deffn

@geindex maintype (attribut email.headerregistry.ContentTypeHeader)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader maintype}@anchor{3543}
@deffn {Attribut} maintype
@end deffn

@geindex subtype (attribut email.headerregistry.ContentTypeHeader)
@anchor{library/email headerregistry email headerregistry ContentTypeHeader subtype}@anchor{3544}
@deffn {Attribut} subtype
@end deffn
@end deffn

@geindex ContentDispositionHeader (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry ContentDispositionHeader}@anchor{3545}
@deffn {Classe} email.headerregistry.ContentDispositionHeader

Classe @ref{3540,,ParameterizedMIMEHeader} qui gère l'en-tête @code{Content-Disposition}.

@geindex content_disposition (attribut email.headerregistry.ContentDispositionHeader)
@anchor{library/email headerregistry email headerregistry ContentDispositionHeader content_disposition}@anchor{3546}
@deffn {Attribut} content_disposition

@code{inline} et @code{attachment} sont les seules valeurs valides couramment utilisées.
@end deffn
@end deffn

@geindex ContentTransferEncoding (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry ContentTransferEncoding}@anchor{3547}
@deffn {Classe} email.headerregistry.ContentTransferEncoding

Gère l'en-tête @code{Content-Transfer-Encoding}.

@geindex cte (attribut email.headerregistry.ContentTransferEncoding)
@anchor{library/email headerregistry email headerregistry ContentTransferEncoding cte}@anchor{3548}
@deffn {Attribut} cte

Les valeurs valides sont @code{7bit}, @code{8bit}, @code{base64} et @code{quoted-printable}. Voir la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} pour plus d'informations.
@end deffn
@end deffn

@geindex HeaderRegistry (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry}@anchor{352d}
@deffn {Classe} email.headerregistry.HeaderRegistry (base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)

This is the factory used by @ref{1099,,EmailPolicy} by default.
@code{HeaderRegistry} builds the class used to create a header instance
dynamically, using `base_class' and a specialized class retrieved from a
registry that it holds.  When a given header name does not appear in the
registry, the class specified by `default_class' is used as the specialized
class.  When `use_default_map' is @code{True} (the default), the standard
mapping of header names to classes is copied in to the registry during
initialization.  `base_class' is always the last class in the generated
class's @ref{1460,,__bases__} list.

Les correspondances par défaut sont :

@quotation

@*subject: 
UniqueUnstructuredHeader


@*date: 
UniqueDateHeader


@*resent-date: 
DateHeader


@*orig-date: 
UniqueDateHeader


@*sender: 
UniqueSingleAddressHeader


@*resent-sender: 
SingleAddressHeader


@*to: 
UniqueAddressHeader


@*resent-to: 
AddressHeader


@*cc: 
UniqueAddressHeader


@*resent-cc: 
AddressHeader


@*bcc: 
UniqueAddressHeader


@*resent-bcc: 
AddressHeader


@*from: 
UniqueAddressHeader


@*resent-from: 
AddressHeader


@*reply-to: 
UniqueAddressHeader


@*mime-version: 
MIMEVersionHeader


@*content-type: 
ContentTypeHeader


@*content-disposition: 
ContentDispositionHeader


@*content-transfer-encoding: 
ContentTransferEncodingHeader


@*message-id: 
MessageIDHeader

@end quotation

@code{HeaderRegistry} a les méthodes suivantes :

@geindex map_to_type() (méthode email.headerregistry.HeaderRegistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry map_to_type}@anchor{3549}
@deffn {Méthode} map_to_type (self, name, cls)

`name' est le nom de l'en-tête à faire correspondre. Il est converti en minuscules dans le registre. `cls' est la classe spécialisée à utiliser, avec `base_class', pour créer la classe utilisée pour instancier les en-têtes qui correspondent à `name'.
@end deffn

@geindex __getitem__() (méthode email.headerregistry.HeaderRegistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry __getitem__}@anchor{354a}
@deffn {Méthode} __getitem__ (name)

Construit et renvoie une classe pour gérer la création d'un en-tête `name'.
@end deffn

@geindex __call__() (méthode email.headerregistry.HeaderRegistry)
@anchor{library/email headerregistry email headerregistry HeaderRegistry __call__}@anchor{354b}
@deffn {Méthode} __call__ (name, value)

Récupère l'en-tête spécialisé associé à `name' du registre (en utilisant `default_class' si `name' n'apparaît pas dans le registre) et le compose avec `base_class' pour produire une classe, appelle le constructeur de la classe construite, en lui passant la même liste d'arguments, et renvoie enfin l'instance de classe ainsi créée.
@end deffn
@end deffn

Les classes suivantes sont les classes utilisées pour représenter les données analysées à partir d'en-têtes structurés et peuvent, en général, être utilisées par un programme d'application pour construire des valeurs structurées à affecter à des en-têtes spécifiques.

@geindex Address (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry Address}@anchor{3539}
@deffn {Classe} email.headerregistry.Address (display_name='@w{'}, username='@w{'}, domain='@w{'}, addr_spec=None)

Classe utilisée pour représenter une adresse e-mail. La forme générale d'une adresse est :

@example
[display_name] <username@@domain>
@end example

ou :

@example
username@@domain
@end example

où chaque partie doit se conformer à des règles de syntaxe spécifiques énoncées dans la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}.

Pour plus de commodité, `addr_spec' peut être spécifié à la place de `username' et `domain', `username' et `domain' sont alors analysés à partir de `addr_spec'. Une `addr_spec' doit être une chaîne correctement entre guillemets RFC ; si ce n'est pas le cas, @code{Address} lève une erreur. Les caractères Unicode sont autorisés et sont encodés proprement lors de la sérialisation. Cependant, selon les RFC, l’Unicode n'est `pas' autorisé dans la partie nom d'utilisateur de l'adresse.

@geindex display_name (attribut email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address display_name}@anchor{354c}
@deffn {Attribut} display_name

Partie du nom d'affichage de l'adresse, le cas échéant, avec toutes les citations supprimées. Si l'adresse n'a pas de nom d'affichage, cet attribut est une chaîne vide.
@end deffn

@geindex username (attribut email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address username}@anchor{354d}
@deffn {Attribut} username

Partie @code{username} de l'adresse, sans guillemets.
@end deffn

@geindex domain (attribut email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address domain}@anchor{354e}
@deffn {Attribut} domain

Partie @code{domain} de l'adresse.
@end deffn

@geindex addr_spec (attribut email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address addr_spec}@anchor{354f}
@deffn {Attribut} addr_spec

Partie @code{username@@domain} de l'adresse, correctement citée pour une utilisation en tant qu'adresse nue (la deuxième forme illustrée ci-dessus). Cet attribut n'est pas modifiable.
@end deffn

@geindex __str__() (méthode email.headerregistry.Address)
@anchor{library/email headerregistry email headerregistry Address __str__}@anchor{3550}
@deffn {Méthode} __str__ ()

La valeur @code{str} de l'objet est l'adresse entre guillemets selon les règles de la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, mais sans encodage de contenu pour les caractères non-ASCII.
@end deffn

Pour prendre en charge SMTP (
@geindex RFC; RFC 5321
RFC 5321@footnote{https://datatracker.ietf.org/doc/html/rfc5321.html}), @code{Address} gère un cas particulier : si @code{username} et @code{domain} sont tous deux la chaîne vide (ou @code{None}), alors la valeur de chaîne de @code{Address} est @code{<>}.
@end deffn

@geindex Group (classe dans email.headerregistry)
@anchor{library/email headerregistry email headerregistry Group}@anchor{3536}
@deffn {Classe} email.headerregistry.Group (display_name=None, addresses=None)

Classe utilisée pour représenter un groupe d'adresses. La forme générale d'un groupe d'adresses est :

@example
display_name: [address-list];
@end example

Pour faciliter le traitement des listes d'adresses composées d'un mélange de groupes et d'adresses uniques, un @code{Group} peut également être utilisé pour représenter des adresses uniques qui ne font pas partie d'un groupe en définissant `display_name' sur @code{None} et en fournissant une liste de l'adresse unique sous la forme `adresses'.

@geindex display_name (attribut email.headerregistry.Group)
@anchor{library/email headerregistry email headerregistry Group display_name}@anchor{3537}
@deffn {Attribut} display_name

@code{display_name} du groupe. Si c'est @code{None} et qu'il y a exactement une @code{Adress} dans @code{adresses}, alors le @code{Group} représente une seule adresse qui n'est pas dans un groupe.
@end deffn

@geindex addresses (attribut email.headerregistry.Group)
@anchor{library/email headerregistry email headerregistry Group addresses}@anchor{3551}
@deffn {Attribut} addresses

`n'-uplet éventuellement vide d'objets @ref{3539,,Address} représentant les adresses du groupe.
@end deffn

@geindex __str__() (méthode email.headerregistry.Group)
@anchor{library/email headerregistry email headerregistry Group __str__}@anchor{3552}
@deffn {Méthode} __str__ ()

La valeur @code{str} d'un @code{Group} est formatée selon la 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, mais sans encodage de contenu pour les caractères non-ASCII. Si @code{display_name} est @code{None} et qu'il y a une seule @code{Address} dans la liste @code{addresses}, la valeur @code{str} est la même que la @code{str} de cette seule @code{Adress}.
@end deffn
@end deffn

@subsubheading Notes


@node email contentmanager Managing MIME Content,email Exemples,email headerregistry Custom Header Objects,email --- An email and MIME handling package
@anchor{library/email contentmanager doc}@anchor{3553}@anchor{library/email contentmanager email-contentmanager-managing-mime-content}@anchor{3554}@anchor{library/email contentmanager module-email contentmanager}@anchor{3d}
@subsubsection @code{email.contentmanager}: Managing MIME Content


@geindex module; email.contentmanager

`Code source :' Lib/email/contentmanager.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/contentmanager.py}


__________________________________________________________________



Ajouté dans la version 3.6: @footnote{
Initialement ajouté dans 3.4 en tant que @ref{102a,,paquet provisoire}.
}


@geindex ContentManager (classe dans email.contentmanager)
@anchor{library/email contentmanager email contentmanager ContentManager}@anchor{3555}
@deffn {Classe} email.contentmanager.ContentManager

Classe mère pour les gestionnaires de contenu. Fournit les mécanismes de registre standard pour enregistrer les convertisseurs entre le contenu MIME et d'autres représentations, ainsi que les méthodes de répartition @code{get_content} et @code{set_content}.

@geindex get_content() (méthode email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager get_content}@anchor{34de}
@deffn {Méthode} get_content (msg, *args, **kw)

Recherche une fonction de gestion en se basant sur le @code{mimetype} de `msg' (voir le paragraphe suivant), l'appelle en lui passant tous les arguments et renvoie le résultat de l'appel. Le gestionnaire doit extraire la charge utile de `msg' et renvoyer un objet qui encode les informations relatives aux données extraites.

Pour trouver le gestionnaire, recherche les clés suivantes dans le registre, en s'arrêtant à la première trouvée :


@itemize *

@item 
une chaîne représentant le type MIME complet (@code{maintype/subtype}) ;

@item 
une chaîne représentant le @code{maintype} ;

@item 
une chaîne vide.
@end itemize

Si aucune de ces clés ne produit de gestionnaire, lève une @ref{33a,,KeyError} pour le type MIME complet.
@end deffn

@geindex set_content() (méthode email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager set_content}@anchor{34df}
@deffn {Méthode} set_content (msg, obj, *args, **kw)

Si le @code{maintype} est @code{multipart}, lève une @ref{522,,TypeError} ; sinon recherche une fonction de gestion en se basant sur le type de `obj' (voir le paragraphe suivant), appelle @ref{34e8,,clear_content()} sur le `msg' et appelle la fonction de gestion en lui passant tous les arguments. Le gestionnaire doit transformer et stocker `obj' en `msg', apportant éventuellement d'autres modifications à `msg' également, comme l'ajout de divers en-têtes MIME pour coder les informations nécessaires à l'interprétation des données stockées.

Pour trouver le gestionnaire, récupère le type de `obj' (@code{typ = type(obj)}) et recherche les clés suivantes dans le registre, en s'arrêtant à la première trouvée :


@itemize *

@item 
le type lui-même (@code{typ}) ;

@item 
le nom complet du type (@code{typ.__module__ + '.' + typ.__qualname__}) ;

@item 
the type's @ref{1eab,,qualname} (@code{typ.__qualname__})

@item 
the type's @ref{145f,,name} (@code{typ.__name__}).
@end itemize

If none of the above match, repeat all of the checks above for each of
the types in the @ref{3556,,MRO} (@ref{1eae,,typ.__mro__}).
Finally, if no other key
yields a handler, check for a handler for the key @code{None}.  If there is
no handler for @code{None}, raise a @ref{33a,,KeyError} for the fully
qualified name of the type.

Ajoute également un en-tête @code{MIME-Version} s'il n'y en a pas (voir aussi @ref{f25,,MIMEPart}).
@end deffn

@geindex add_get_handler() (méthode email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager add_get_handler}@anchor{3557}
@deffn {Méthode} add_get_handler (key, handler)

Enregistre la fonction `handler' comme gestionnaire pour `key'. Pour les valeurs possibles de `key', voir @ref{3558,,get_content()}.
@end deffn

@geindex add_set_handler() (méthode email.contentmanager.ContentManager)
@anchor{library/email contentmanager email contentmanager ContentManager add_set_handler}@anchor{3559}
@deffn {Méthode} add_set_handler (typekey, handler)

Enregistre `handler' comme fonction à appeler lorsqu'un objet d'un type correspondant à `typekey' est passé à @ref{355a,,set_content()}. Pour les valeurs possibles de `typekey', voir @ref{355a,,set_content()}.
@end deffn
@end deffn

@menu
* Instances de gestionnaires de contenus:: 

@end menu

@node Instances de gestionnaires de contenus,,,email contentmanager Managing MIME Content
@anchor{library/email contentmanager content-manager-instances}@anchor{355b}
@subsubsection Instances de gestionnaires de contenus


Actuellement, le paquet `email' ne fournit qu'un seul gestionnaire de contenu concret, @ref{3512,,raw_data_manager}, bien que d'autres puissent être ajoutés à l'avenir. @ref{3512,,raw_data_manager} est le @ref{f26,,content_manager} fourni par @ref{1099,,EmailPolicy} et ses dérivés.

@geindex raw_data_manager (dans le module email.contentmanager)
@anchor{library/email contentmanager email contentmanager raw_data_manager}@anchor{3512}
@deffn {Données} email.contentmanager.raw_data_manager

Ce gestionnaire de contenu ne fournit qu'une interface minimale au-delà de celle fournie par @ref{279,,Message} lui-même : il  prend seulement en charge le texte, les chaînes d'octets brutes et les objets @ref{279,,Message}. Néanmoins, il offre des avantages significatifs par rapport à l'API de base : @code{get_content} sur une partie de texte renvoie une chaîne Unicode sans que l'application ait besoin de la décoder manuellement, @code{set_content} fournit de nombreuses options pour contrôler les en-têtes ajoutés à une partie et l'encodage du transfert de contenu, et il permet l'utilisation des différentes méthodes @code{add_}, ce qui simplifie la création de messages en plusieurs parties.

@geindex get_content() (dans le module email.contentmanager)
@anchor{library/email contentmanager email contentmanager get_content}@anchor{3558}
@deffn {Méthode} email.contentmanager.get_content (msg, errors='replace')

Renvoie la charge utile de la partie sous la forme d'une chaîne (pour les parties @code{text}), d'un objet @ref{278,,EmailMessage} (pour les parties @code{message/rfc822}) ou d'un objet @code{bytes} (pour tous les autres types à l'exception de `multipart'). Lève une @ref{33a,,KeyError} si cette méthode est appelée sur un @code{multipart}. S'il s'agit d'une partie @code{text} et que `errors' est spécifié, ce paramètre est utilisé comme gestionnaire d'erreurs lors du décodage de la charge utile en Unicode. Le gestionnaire d'erreurs par défaut est @code{replace}.
@end deffn

@geindex set_content() (dans le module email.contentmanager)
@anchor{library/email contentmanager email contentmanager set_content}@anchor{355a}
@deffn {Méthode} email.contentmanager.set_content (msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

@deffnx {Méthode} email.contentmanager.set_content (msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)

@deffnx {Méthode} email.contentmanager.set_content (msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

Ajoute des en-têtes et une charge utile à `msg' :

Ajoute un en-tête @code{Content-Type} avec une valeur @code{maintype/subtype}.


@itemize *

@item 
Pour @code{str}, définit le @code{maintype} MIME à @code{text} et définit le sous-type à `subtype' s'il est spécifié, ou à @code{plain} s'il ne l'est pas.

@item 
Pour @code{bytes}, utilise les `maintype' et `subtype' spécifiés, ou lève une @ref{522,,TypeError} s'ils ne sont pas spécifiés.

@item 
Pour les objets @ref{278,,EmailMessage}, définit le type principal (`maintype') à @code{message} et définit le sous-type à `subtype' s'il est spécifié ou à @code{rfc822} s'il ne l'est pas. Si `subtype' est @code{partial}, lève une erreur (les objets @code{bytes} doivent être utilisés pour construire les parties @code{message/partial}).
@end itemize

Si `charset' est fourni (qui n'est valide que pour @code{str}), encode la chaîne en octets en utilisant le jeu de caractères spécifié. La valeur par défaut est @code{utf-8}. Si le `charset' spécifié est un alias connu pour un nom de jeu de caractères MIME standard, utilise plutôt le jeu de caractères standard.

Si `cte' est défini, encode la charge utile à l'aide de l'encodage de transfert de contenu spécifié et définit l'en-tête @code{Content-Transfer-Encoding} à cette valeur. Les valeurs possibles pour `cte' sont @code{quoted-printable}, @code{base64}, @code{7bit}, @code{8bit} et @code{binary}. Si l'entrée ne peut pas être encodée dans l'encodage spécifié (par exemple, en spécifiant un `cte' de @code{7bit} pour une entrée qui contient des valeurs non-ASCII), lève une @ref{1ff,,ValueError}.


@itemize *

@item 
Pour les objets @code{str}, si `cte' n'est pas défini, utilise une heuristique pour déterminer l'encodage le plus compact.

@item 
Pour @ref{278,,EmailMessage}, selon la 
@geindex RFC; RFC 2046
RFC 2046@footnote{https://datatracker.ietf.org/doc/html/rfc2046.html}, pour le `subtype' @code{rfc822}, lève une erreur pour un `cte' valant @code{quoted-printable} ou @code{base64}. Pour le `subtype' @code{external-body}, lève une erreur pour tout `cte' autre que @code{7bit}. Pour @code{message/rfc822}, la valeur par défaut de `cte' est @code{8bit}. Pour toutes les autres valeurs de `sous-type', la valeur par défaut de `cte' est @code{7bit}.
@end itemize

@cartouche
@quotation Note 
la valeur @code{binary} pour `cte' ne fonctionne pas encore correctement. L'objet @code{EmailMessage} tel que modifié par @code{set_content} est correct, mais @ref{11ac,,BytesGenerator} ne le sérialise pas correctement.
@end quotation
@end cartouche

Si `disposition' est spécifié, utilise cette valeur pour l'en-tête @code{Content-Disposition}. S'il n'est pas spécifié et que `filename' est spécifié, utilise la valeur @code{attachment} pour l'en-tête. Si ni `disposition' ni `filename' ne sont spécifiés, n'ajoute pas cet en-tête. Les seules valeurs valides pour `disposition' sont @code{attachment} et @code{inline}.

Si `filename' est spécifié, utilise cette valeur pour le paramètre @code{filename} de l'en-tête @code{Content-Disposition}.

Si `cid' est spécifié, ajoute un en-tête @code{Content-ID} avec cette valeur.

Si `params' est spécifié, itère sur sa méthode @code{items} et utilise les paires @code{(clé, valeur)} résultantes pour définir des paramètres supplémentaires dans l'en-tête @code{Content-Type}.

Si `headers' est spécifié et est une liste de chaînes de la forme @code{headername: headervalue} ou une liste d'objets @code{header} (distingués des chaînes par l'attribut @code{name}), ajoute ces en-têtes à `msg'.
@end deffn
@end deffn

@subsubheading Notes


@node email Exemples,email message Message représentation d'un message électronique à l'aide de l'API compat32,email contentmanager Managing MIME Content,email --- An email and MIME handling package
@anchor{library/email examples doc}@anchor{355c}@anchor{library/email examples email-examples}@anchor{f27}@anchor{library/email examples id1}@anchor{355d}
@subsubsection @code{email}: Exemples


Cette page contient quelques exemples de l'utilisation du package @ref{3b,,email} pour lire, écrire, et envoyer de simples messages mail, ainsi que des messages MIME plus complexes.

Premièrement, regardons comment créer et envoyer un message avec simplement du texte (le contenu textuel et les adresses peuvent tous deux contenir des caractères Unicodes) :

@example
# Import smtplib for the actual sending function
import smtplib

# Import the email modules we'll need
from email.message import EmailMessage

# Open the plain text file whose name is in textfile for reading.
with open(textfile) as fp:
    # Create a text/plain message
    msg = EmailMessage()
    msg.set_content(fp.read())

# me == the sender's email address
# you == the recipient's email address
msg['Subject'] = f'The contents of @{textfile@}'
msg['From'] = me
msg['To'] = you

# Send the message via our own SMTP server.
s = smtplib.SMTP('localhost')
s.send_message(msg)
s.quit()
@end example

Analyser des entêtes 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} peut être aisément réalisé en utilisant les classes du module @ref{4e,,parser} :

@example
# Import the email modules we'll need
#from email.parser import BytesParser
from email.parser import Parser
from email.policy import default

# If the e-mail headers are in a file, uncomment these two lines:
# with open(messagefile, 'rb') as fp:
#     headers = BytesParser(policy=default).parse(fp)

#  Or for parsing headers in a string (this is an uncommon operation), use:
headers = Parser(policy=default).parsestr(
        'From: Foo Bar <user@@example.com>\n'
        'To: <someone_else@@example.com>\n'
        'Subject: Test message\n'
        '\n'
        'Body would go here\n')

#  Now the header items can be accessed as a dictionary:
print('To: @{@}'.format(headers['to']))
print('From: @{@}'.format(headers['from']))
print('Subject: @{@}'.format(headers['subject']))

# You can also access the parts of the addresses:
print('Recipient username: @{@}'.format(headers['to'].addresses[0].username))
print('Sender name: @{@}'.format(headers['from'].addresses[0].display_name))
@end example

Voici un exemple de l'envoi d'un message MIME contenant une série de photos de famille qui sont stockés ensemble dans un dossier :

@example
# Import smtplib for the actual sending function.
import smtplib

# Here are the email package modules we'll need.
from email.message import EmailMessage

# Create the container email message.
msg = EmailMessage()
msg['Subject'] = 'Our family reunion'
# me == the sender's email address
# family = the list of all recipients' email addresses
msg['From'] = me
msg['To'] = ', '.join(family)
msg.preamble = 'You will not see this in a MIME-aware mail reader.\n'

# Open the files in binary mode.  You can also omit the subtype
# if you want MIMEImage to guess it.
for file in pngfiles:
    with open(file, 'rb') as fp:
        img_data = fp.read()
    msg.add_attachment(img_data, maintype='image',
                                 subtype='png')

# Send the email via our own SMTP server.
with smtplib.SMTP('localhost') as s:
    s.send_message(msg)
@end example

Voici un exemple d'envoi du contenu d'un dossier entier en tant que message mail : @footnote{
Merci à Matthew Dixon Cowles pour l'inspiration originale et les exemples.
}

@example
#!/usr/bin/env python3

"""Send the contents of a directory as a MIME message."""

import os
import smtplib
# For guessing MIME type based on file name extension
import mimetypes

from argparse import ArgumentParser

from email.message import EmailMessage
from email.policy import SMTP


def main():
    parser = ArgumentParser(description="""\
Send the contents of a directory as a MIME message.
Unless the -o option is given, the email is sent by forwarding to your local
SMTP server, which then does the normal delivery process.  Your local machine
must be running an SMTP server.
""")
    parser.add_argument('-d', '--directory',
                        help="""Mail the contents of the specified directory,
                        otherwise use the current directory.  Only the regular
                        files in the directory are sent, and we don't recurse to
                        subdirectories.""")
    parser.add_argument('-o', '--output',
                        metavar='FILE',
                        help="""Print the composed message to FILE instead of
                        sending the message to the SMTP server.""")
    parser.add_argument('-s', '--sender', required=True,
                        help='The value of the From: header (required)')
    parser.add_argument('-r', '--recipient', required=True,
                        action='append', metavar='RECIPIENT',
                        default=[], dest='recipients',
                        help='A To: header value (at least one required)')
    args = parser.parse_args()
    directory = args.directory
    if not directory:
        directory = '.'
    # Create the message
    msg = EmailMessage()
    msg['Subject'] = f'Contents of directory @{os.path.abspath(directory)@}'
    msg['To'] = ', '.join(args.recipients)
    msg['From'] = args.sender
    msg.preamble = 'You will not see this in a MIME-aware mail reader.\n'

    for filename in os.listdir(directory):
        path = os.path.join(directory, filename)
        if not os.path.isfile(path):
            continue
        # Guess the content type based on the file's extension.  Encoding
        # will be ignored, although we should check for simple things like
        # gzip'd or compressed files.
        ctype, encoding = mimetypes.guess_file_type(path)
        if ctype is None or encoding is not None:
            # No guess could be made, or the file is encoded (compressed), so
            # use a generic bag-of-bits type.
            ctype = 'application/octet-stream'
        maintype, subtype = ctype.split('/', 1)
        with open(path, 'rb') as fp:
            msg.add_attachment(fp.read(),
                               maintype=maintype,
                               subtype=subtype,
                               filename=filename)
    # Now send or store the message
    if args.output:
        with open(args.output, 'wb') as fp:
            fp.write(msg.as_bytes(policy=SMTP))
    else:
        with smtplib.SMTP('localhost') as s:
            s.send_message(msg)


if __name__ == '__main__':
    main()
@end example

Voici un exemple de comment décomposer un message MIME comme celui ci-dessus en tant que fichiers dans un dossier :

@example
#!/usr/bin/env python3

"""Unpack a MIME message into a directory of files."""

import os
import email
import mimetypes

from email.policy import default

from argparse import ArgumentParser


def main():
    parser = ArgumentParser(description="""\
Unpack a MIME message into a directory of files.
""")
    parser.add_argument('-d', '--directory', required=True,
                        help="""Unpack the MIME message into the named
                        directory, which will be created if it doesn't already
                        exist.""")
    parser.add_argument('msgfile')
    args = parser.parse_args()

    with open(args.msgfile, 'rb') as fp:
        msg = email.message_from_binary_file(fp, policy=default)

    try:
        os.mkdir(args.directory)
    except FileExistsError:
        pass

    counter = 1
    for part in msg.walk():
        # multipart/* are just containers
        if part.get_content_maintype() == 'multipart':
            continue
        # Applications should really sanitize the given filename so that an
        # email message can't be used to overwrite important files
        filename = part.get_filename()
        if not filename:
            ext = mimetypes.guess_extension(part.get_content_type())
            if not ext:
                # Use a generic bag-of-bits extension
                ext = '.bin'
            filename = f'part-@{counter:03d@}@{ext@}'
        counter += 1
        with open(os.path.join(args.directory, filename), 'wb') as fp:
            fp.write(part.get_payload(decode=True))


if __name__ == '__main__':
    main()
@end example

Voici un exemple de création d'un message HTML avec une version en texte comme alternative. Pour rendre les choses un peu plus intéressantes, nous incluons aussi une image dans la partie HTML, nous sauvons une copie du message sur le disque, et nous l'envoyons.

@example
#!/usr/bin/env python3

import smtplib

from email.message import EmailMessage
from email.headerregistry import Address
from email.utils import make_msgid

# Create the base text message.
msg = EmailMessage()
msg['Subject'] = "Pourquoi pas des asperges pour ce midi ?"
msg['From'] = Address("Pepé Le Pew", "pepe", "example.com")
msg['To'] = (Address("Penelope Pussycat", "penelope", "example.com"),
             Address("Fabrette Pussycat", "fabrette", "example.com"))
msg.set_content("""\
Salut!

Cette recette [1] sera sûrement un très bon repas.

[1] http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718

--Pepé
""")

# Add the html version.  This converts the message into a multipart/alternative
# container, with the original text message as the first part and the new html
# message as the second part.
asparagus_cid = make_msgid()
msg.add_alternative("""\
<html>
  <head></head>
  <body>
    <p>Salut!</p>
    <p>Cette
        <a href="http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718">
            recette
        </a> sera sûrement un très bon repas.
    </p>
    <img src="cid:@{asparagus_cid@}" />
  </body>
</html>
""".format(asparagus_cid=asparagus_cid[1:-1]), subtype='html')
# note that we needed to peel the <> off the msgid for use in the html.

# Now add the related image to the html part.
with open("roasted-asparagus.jpg", 'rb') as img:
    msg.get_payload()[1].add_related(img.read(), 'image', 'jpeg',
                                     cid=asparagus_cid)

# Make a local copy of what we are going to send.
with open('outgoing.msg', 'wb') as f:
    f.write(bytes(msg))

# Send the message via local SMTP server.
with smtplib.SMTP('localhost') as s:
    s.send_message(msg)
@end example

Si on nous avait envoyé le message de l'exemple précédent, voici la manière avec laquelle nous pourrions le traiter :

@example
import os
import sys
import tempfile
import mimetypes
import webbrowser

# Import the email modules we'll need
from email import policy
from email.parser import BytesParser


def magic_html_parser(html_text, partfiles):
    """Return safety-sanitized html linked to partfiles.

    Rewrite the href="cid:...." attributes to point to the filenames in partfiles.
    Though not trivial, this should be possible using html.parser.
    """
    raise NotImplementedError("Add the magic needed")


# In a real program you'd get the filename from the arguments.
with open('outgoing.msg', 'rb') as fp:
    msg = BytesParser(policy=policy.default).parse(fp)

# Now the header items can be accessed as a dictionary, and any non-ASCII will
# be converted to unicode:
print('To:', msg['to'])
print('From:', msg['from'])
print('Subject:', msg['subject'])

# If we want to print a preview of the message content, we can extract whatever
# the least formatted payload is and print the first three lines.  Of course,
# if the message has no plain text part printing the first three lines of html
# is probably useless, but this is just a conceptual example.
simplest = msg.get_body(preferencelist=('plain', 'html'))
print()
print('@w{'}.join(simplest.get_content().splitlines(keepends=True)[:3]))

ans = input("View full message?")
if ans.lower()[0] == 'n':
    sys.exit()

# We can extract the richest alternative in order to display it:
richest = msg.get_body()
partfiles = @{@}
if richest['content-type'].maintype == 'text':
    if richest['content-type'].subtype == 'plain':
        for line in richest.get_content().splitlines():
            print(line)
        sys.exit()
    elif richest['content-type'].subtype == 'html':
        body = richest
    else:
        print("Don't know how to display @{@}".format(richest.get_content_type()))
        sys.exit()
elif richest['content-type'].content_type == 'multipart/related':
    body = richest.get_body(preferencelist=('html'))
    for part in richest.iter_attachments():
        fn = part.get_filename()
        if fn:
            extension = os.path.splitext(part.get_filename())[1]
        else:
            extension = mimetypes.guess_extension(part.get_content_type())
        with tempfile.NamedTemporaryFile(suffix=extension, delete=False) as f:
            f.write(part.get_content())
            # again strip the <> to go from email form of cid to html form.
            partfiles[part['content-id'][1:-1]] = f.name
else:
    print("Don't know how to display @{@}".format(richest.get_content_type()))
    sys.exit()
with tempfile.NamedTemporaryFile(mode='w', delete=False) as f:
    f.write(magic_html_parser(body.get_content(), partfiles))
webbrowser.open(f.name)
os.remove(f.name)
for fn in partfiles.values():
    os.remove(fn)

# Of course, there are lots of email messages that could break this simple
# minded program, but it will handle the most common ones.
@end example

La sortie textuelle du code ci dessus est :

@example
To: Penelope Pussycat <penelope@@example.com>, Fabrette Pussycat <fabrette@@example.com>
From: Pepé Le Pew <pepe@@example.com>
Subject: Pourquoi pas des asperges pour ce midi ?

Salut!

Cette recette [1] sera sûrement un très bon repas.
@end example

@subsubheading Notes


API héritée :

@node email message Message représentation d'un message électronique à l'aide de l'API compat32,email mime Creating email and MIME objects from scratch,email Exemples,email --- An email and MIME handling package
@anchor{library/email compat32-message doc}@anchor{355e}@anchor{library/email compat32-message compat32-message}@anchor{34af}@anchor{library/email compat32-message email-message-message-representing-an-email-message-using-the-compat32-api}@anchor{355f}
@subsubsection @code{email.message.Message} : représentation d'un message électronique à l'aide de l'API @code{compat32}


La classe @ref{279,,Message} est très similaire à la classe @ref{278,,EmailMessage}, sans les méthodes ajoutées par cette classe et avec le comportement par défaut légèrement différent pour certaines autres méthodes. Nous documentons également ici certaines méthodes qui, bien que prises en charge par la classe @ref{278,,EmailMessage}, ne sont pas recommandées, sauf si vous avez affaire à du code hérité.

La philosophie et la structure des deux classes sont par ailleurs les mêmes.

Ce document décrit le comportement avec les règles par défaut (pour @ref{279,,Message}) @ref{1096,,Compat32}. Si vous envisagez d'utiliser d'autres règles, vous devriez plutôt utiliser la classe @ref{278,,EmailMessage}.

Un message électronique se compose d'`en-têtes' et d'une `charge utile'. Les en-têtes doivent être des noms et des valeurs de style 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}, où le nom et la valeur du champ sont séparés par deux-points. Les deux-points ne font partie ni du nom du champ ni de la valeur du champ. La charge utile peut être un simple message texte, ou un objet binaire, ou une séquence structurée de sous-messages chacun avec son propre ensemble d'en-têtes et sa propre charge utile. Ce dernier type de charge utile est indiqué par le message ayant un type MIME tel que @code{multipart/*} ou @code{message/rfc822}.

Le modèle conceptuel fourni par un objet @ref{279,,Message} est celui d'un dictionnaire ordonné d'en-têtes avec des méthodes supplémentaires pour accéder à la fois aux informations spécialisées des en-têtes, pour accéder à la charge utile, pour générer une version sérialisée du message et pour parcourir récursivement l'arbre d'objets. Notez que les en-têtes en double sont pris en charge mais que des méthodes spéciales doivent être utilisées pour y accéder.

Le pseudo-dictionnaire @ref{279,,Message} est indicé par les noms d'en-tête, qui doivent être des valeurs ASCII. Les valeurs du dictionnaire sont des chaînes censées contenir uniquement des caractères ASCII ; il existe une gestion spéciale pour les entrées non ASCII, mais cela ne produit pas toujours les résultats corrects. Les en-têtes sont stockés et renvoyés sous une forme respectant la casse, mais les noms de champ sont mis en correspondance sans tenir compte de la casse. Il peut également y avoir un seul en-tête d'enveloppe, également appelé en-tête `Unix-From' ou en-tête @code{From_}. La `charge utile' est soit une chaîne ou des octets, dans le cas d'objets message simples, soit une liste d'objets @ref{279,,Message}, pour les documents conteneurs MIME (par exemple @code{multipart/*} et @code{message/rfc822}).

Voici les méthodes de la classe @ref{279,,Message} :

@geindex Message (classe dans email.message)
@anchor{library/email compat32-message email message Message}@anchor{279}
@deffn {Classe} email.message.Message (policy=compat32)

Si `policy' est spécifié (il doit s'agir d'une instance d'une classe @ref{4f,,policy}), utilise les règles spécifiées pour mettre à jour et sérialiser la représentation du message. Si `policy' n'est pas défini, utilise les règles @ref{1096,,compat32}, qui maintient la rétrocompatibilité avec la version Python 3.2 du paquet de messagerie. Pour plus d'informations, consultez la documentation @ref{4f,,policy}.


Modifié dans la version 3.3: l'argument nommé `policy' a été ajouté.


@geindex as_string() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message as_string}@anchor{f21}
@deffn {Méthode} as_string (unixfrom=False, maxheaderlen=0, policy=None)

Renvoie le message entier aplati sous forme de chaîne. Lorsque l'option `unixfrom' est vraie, l'en-tête de l'enveloppe est inclus dans la chaîne renvoyée. `unixfrom' par défaut est @code{False}. Pour des raisons de compatibilité descendante, `maxheaderlen' est par défaut à @code{0}, donc si vous voulez une valeur différente, vous devez la remplacer explicitement (la valeur spécifiée pour `max_line_length' dans la politique sera ignorée par cette méthode). L'argument `policy' peut être utilisé pour remplacer les règles par défaut obtenues à partir de l'instance de message. Cela peut être utilisé pour contrôler une partie du formatage produit par la méthode, puisque la `policy' spécifiée est transmise au @code{Generator}.

L'aplatissement du message peut déclencher des changements dans @ref{279,,Message} si les valeurs par défaut doivent être renseignées pour terminer la transformation en chaîne (par exemple, les limites MIME peuvent être générées ou modifiées).

Notez que cette méthode est fournie à titre de commodité et peut ne pas toujours formater le message comme vous le souhaitez. Par exemple, par défaut, elle ne reformate pas les lignes qui commencent par @code{From} qui est requis par le format `mbox' Unix. Pour plus de flexibilité, instanciez une instance @ref{11ab,,Generator} et utilisez sa méthode @ref{3501,,flatten()} directement. Par exemple :

@example
from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
@end example

Si l'objet message contient des données binaires qui ne sont pas encodées selon les normes RFC, les données non conformes seront remplacées par des points de code Unicode « caractère inconnu » (voir aussi @ref{f22,,as_bytes()} et @ref{11ac,,BytesGenerator}).


Modifié dans la version 3.4: l'argument nommé `policy' a été ajouté.

@end deffn

@geindex __str__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __str__}@anchor{3560}
@deffn {Méthode} __str__ ()

Equivalent to @ref{f21,,as_string()}.  Allows @code{str(msg)} to produce a
string containing the formatted message.
@end deffn

@geindex as_bytes() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message as_bytes}@anchor{f22}
@deffn {Méthode} as_bytes (unixfrom=False, policy=None)

Renvoie le message entier aplati en tant qu'objet bytes. Lorsque l'option `unixfrom' est vraie, l'en-tête de l'enveloppe est inclus dans la chaîne renvoyée. `unixfrom' par défaut est @code{False}. L'argument `policy' peut être utilisé pour remplacer les règles par défaut obtenues à partir de l'instance de message. Cela peut être utilisé pour contrôler une partie du formatage produit par la méthode, puisque la `policy' spécifiée est passée au @code{BytesGenerator}.

L'aplatissement du message peut déclencher des changements dans @ref{279,,Message} si les valeurs par défaut doivent être renseignées pour terminer la transformation en chaîne (par exemple, les limites MIME peuvent être générées ou modifiées).

Notez que cette méthode est fournie à titre de commodité et peut ne pas toujours formater le message comme vous le souhaitez. Par exemple, par défaut, elle ne reformate pas les lignes qui commencent par @code{From} qui est requis par le format `mbox' Unix. Pour plus de flexibilité, instanciez une instance @ref{11ac,,BytesGenerator} et utilisez sa méthode @ref{34fd,,flatten()} directement. Par exemple :

@example
from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
@end example


Ajouté dans la version 3.4.

@end deffn

@geindex __bytes__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __bytes__}@anchor{f23}
@deffn {Méthode} __bytes__ ()

Equivalent to @ref{f22,,as_bytes()}.  Allows @code{bytes(msg)} to produce a
bytes object containing the formatted message.


Ajouté dans la version 3.4.

@end deffn

@geindex is_multipart() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message is_multipart}@anchor{34d7}
@deffn {Méthode} is_multipart ()

Renvoie @code{True} si la charge utile du message est une liste d'objets sous-@ref{279,,Message}, sinon renvoie @code{False}. Lorsque @ref{34d7,,is_multipart()} renvoie @code{False}, la charge utile doit être un objet chaîne (qui peut être une charge utile binaire encodée CTE). (Notez que @ref{34d7,,is_multipart()} renvoyant @code{True} ne signifie pas nécessairement que @code{msg.get_content_maintype() == 'multipart'} renvoie @code{True}. Par exemple, @code{is_multipart} renvoie @code{True} lorsque le @ref{279,,Message} est de type @code{message/rfc822}.)
@end deffn

@geindex set_unixfrom() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_unixfrom}@anchor{3561}
@deffn {Méthode} set_unixfrom (unixfrom)

Définit l'en-tête de l'enveloppe du message sur `unixfrom', qui doit être une chaîne.
@end deffn

@geindex get_unixfrom() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_unixfrom}@anchor{3562}
@deffn {Méthode} get_unixfrom ()

Renvoie l'en-tête de l'enveloppe du message. La valeur par défaut est @code{None} si l'en-tête de l'enveloppe n'a jamais été défini.
@end deffn

@geindex attach() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message attach}@anchor{34e4}
@deffn {Méthode} attach (payload)

Ajoute le `payload' donné à la charge utile actuelle, qui doit être @code{None} ou une liste d'objets @ref{279,,Message} avant l'appel. Après l'appel, la charge utile sera toujours une liste d'objets @ref{279,,Message}. Si vous souhaitez définir la charge utile sur un objet scalaire (par exemple, une chaîne), utilisez @ref{3563,,set_payload()} à la place.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage} sa fonctionnalité est remplacée par @ref{1836,,set_content()} et les méthodes associées @code{make} et @code{add}.
@end deffn

@geindex get_payload() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_payload}@anchor{11aa}
@deffn {Méthode} get_payload (i=None, decode=False)

Renvoie la charge utile actuelle, qui est une liste d'objets @ref{279,,Message} lorsque @ref{34d7,,is_multipart()} est @code{True}, ou une chaîne lorsque @ref{34d7,,is_multipart()} est @code{False}. Si la charge utile est une liste et que vous modifiez l'objet liste, vous modifiez la charge utile du message « sur place ».

Avec l'argument optionnel `i', @ref{11aa,,get_payload()} renvoie le `i'@w{^ème} élément de la charge utile, en partant de zéro, si @ref{34d7,,is_multipart()} vaut @code{True}. Une @ref{14eb,,IndexError} est levée si `i' est inférieur à 0 ou supérieur ou égal au nombre d'éléments dans la charge utile. Si la charge utile est une chaîne (c'est-à-dire que @ref{34d7,,is_multipart()} est @code{False}) et que `i' est donné, une @ref{522,,TypeError} est levée.

`decode' est un indicateur facultatif indiquant si la charge utile doit être décodée ou non, selon l'en-tête @code{Content-Transfer-Encoding}. Lorsqu'il vaut @code{True} et que le message n'est pas en plusieurs parties, la charge utile est décodée si la valeur de cet en-tête est @code{quoted-printable} ou @code{base64}. Si un autre encodage est utilisé, ou si l'en-tête @code{Content-Transfer-Encoding} est manquant, la charge utile est renvoyée telle quelle (non décodée). Dans tous les cas, la valeur renvoyée est une donnée binaire. Si le message est en plusieurs parties et que l'indicateur `decode' est @code{True}, alors @code{None} est renvoyé. Si la charge utile est en base64 et qu'elle n'a pas été parfaitement formée (remplissage manquant, caractères en dehors de l'alphabet base64), alors un défaut approprié est ajouté à la propriété de défaut du message (@code{InvalidBase64PaddingDefect} ou @code{InvalidBase64CharactersDefect}, respectivement).

Lorsque `decode' est @code{False} (valeur par défaut), le corps est renvoyé sous forme de chaîne sans décoder le @code{Content-Transfer-Encoding}. Cependant, pour un @code{Content-Transfer-Encoding} de 8 bits, une tentative est faite pour décoder les octets d'origine en utilisant le @code{charset} spécifié par l'en-tête @code{Content-Type}, en utilisant le gestionnaire d'erreurs @code{replace}. Si aucun @code{charset} n'est spécifié, ou si le @code{charset} donné n'est pas reconnu par le paquet de messagerie, le corps est décodé en utilisant le jeu de caractères ASCII par défaut.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage} sa fonctionnalité est remplacée par @ref{34dd,,get_content()} et @ref{34dc,,iter_parts()}.
@end deffn

@geindex set_payload() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_payload}@anchor{3563}
@deffn {Méthode} set_payload (payload, charset=None)

Définit la charge utile de l'objet message entier à `payload'. Il est de la responsabilité du client de s'assurer des invariants de la charge utile. Le `charset' facultatif définit le jeu de caractères par défaut du message ; voir @ref{3564,,set_charset()} pour plus de détails.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage} sa fonctionnalité est remplacée par @ref{1836,,set_content()}.
@end deffn

@geindex set_charset() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_charset}@anchor{3564}
@deffn {Méthode} set_charset (charset)

Définit le jeu de caractères de la charge utile à `charset', qui peut être soit une instance de @ref{de7,,Charset} (voir @ref{3c,,email.charset}), une chaîne nommant un jeu de caractères ou @code{None}. S'il s'agit d'une chaîne, elle est convertie en une instance @ref{de7,,Charset}. Si `charset' est @code{None}, le paramètre @code{charset} est supprimé de l'en-tête @code{Content-Type} (le message n'est pas modifié autrement). Tout le reste lève une @ref{522,,TypeError}.

S'il n'y a pas d'en-tête @code{MIME-Version} existant, un en-tête est ajouté. S'il n'y a pas d'en-tête @code{Content-Type}, un en-tête est ajouté avec une valeur de @code{text/plain}. Que l'en-tête @code{Content-Type} existe déjà ou non, son paramètre @code{charset} est défini sur `charset.output_charset'. Si `charset.input_charset' et `charset.output_charset' diffèrent, la charge utile est ré-encodée dans le `output_charset'. S'il n'y a pas d'en-tête @code{Content-Transfer-Encoding} existant, alors la charge utile est encodée par transfert, si nécessaire, en utilisant le @ref{de7,,Charset} spécifié et un en-tête avec cette valeur est ajouté. Si un en-tête @code{Content-Transfer-Encoding} existe déjà, la charge utile est supposée être déjà correctement encodée à l'aide de cet en-tête @code{Content-Transfer-Encoding} et n'est pas modifiée.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage} sa fonctionnalité est remplacée par le paramètre `charset' de la méthode @code{email.emailmessage.EmailMessage.set_content()}.
@end deffn

@geindex get_charset() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_charset}@anchor{3565}
@deffn {Méthode} get_charset ()

Renvoie l'instance @ref{de7,,Charset} associée à la charge utile du message.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage}, elle renvoie toujours @code{None}.
@end deffn

Les méthodes suivantes implémentent une interface de type correspondance pour accéder aux en-têtes 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} du message. Notez qu'il existe des différences sémantiques entre ces méthodes et une interface de correspondance normale (c'est-à-dire un dictionnaire). Par exemple, dans un dictionnaire, il n'y a pas de clés en double, mais ici, il peut y avoir des en-têtes de message en double. De plus, dans les dictionnaires, il n'y a pas d'ordre garanti pour les clés renvoyées par @ref{3566,,keys()}, mais dans un objet @ref{279,,Message}, les en-têtes sont toujours renvoyés dans l'ordre dans lequel ils sont apparus dans le message d'origine, ou ont été ajoutés au message plus tard. Tout en-tête supprimé puis rajouté est toujours ajouté à la fin de la liste des en-têtes.

Ces différences sémantiques sont intentionnelles et visent une commodité maximale.

Notez que dans tous les cas, tout en-tête d'enveloppe présent dans le message n'est pas inclus dans l'interface de correspondance.

Dans un modèle généré à partir d'octets, toutes les valeurs d'en-tête qui (en violation des RFC) contiennent des octets non-ASCII sont, lorsqu'elles sont récupérées via cette interface, représentées comme des objets @ref{1837,,Header} avec un `charset' à @code{unknown-8bit}.

@geindex __len__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __len__}@anchor{3567}
@deffn {Méthode} __len__ ()

Renvoie le nombre total d'en-têtes, y compris les doublons.
@end deffn

@geindex __contains__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __contains__}@anchor{170d}
@deffn {Méthode} __contains__ (name)

Renvoie @code{True} si l'objet message a un champ nommé `name'. La correspondance est insensible à la casse et `name' ne doit pas inclure les deux-points à la fin. Utilisé pour l'opérateur @code{in}, par exemple :

@example
if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])
@end example
@end deffn

@geindex __getitem__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __getitem__}@anchor{3568}
@deffn {Méthode} __getitem__ (name)

Renvoie la valeur du champ d'en-tête désigné. `name' ne doit pas inclure le séparateur de champ deux-points. Si l'en-tête est manquant, @code{None} est renvoyé ; @ref{33a,,KeyError} n'est jamais levée.

Notez que si le champ désigné apparaît plus d'une fois dans les en-têtes du message, la valeur exacte renvoyée n'est pas définie. Utilisez la méthode @ref{3569,,get_all()} pour obtenir les valeurs de tous les en-têtes existants.
@end deffn

@geindex __setitem__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __setitem__}@anchor{356a}
@deffn {Méthode} __setitem__ (name, val)

Ajoute un en-tête au message avec le nom de champ `name' et la valeur `val'. Le champ est ajouté à la fin des champs existants du message.

Notez que cela n'écrase `pas' ou ne supprime aucun en-tête existant portant le même nom. Si vous voulez vous assurer que le nouvel en-tête est le seul présent dans le message avec le nom de champ `name', supprimez d'abord le champ, par exemple :

@example
del msg['subject']
msg['subject'] = 'Python roolz!'
@end example
@end deffn

@geindex __delitem__() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message __delitem__}@anchor{356b}
@deffn {Méthode} __delitem__ (name)

Supprime toutes les occurrences du champ portant le nom `name' des en-têtes du message. Aucune exception n'est levée si le champ désigné n'est pas présent dans les en-têtes.
@end deffn

@geindex keys() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message keys}@anchor{3566}
@deffn {Méthode} keys ()

Renvoie une liste de tous les noms de champs d'en-tête du message.
@end deffn

@geindex values() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message values}@anchor{356c}
@deffn {Méthode} values ()

Renvoie une liste de toutes les valeurs de champ du message.
@end deffn

@geindex items() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message items}@anchor{356d}
@deffn {Méthode} items ()

Renvoie une liste de couples contenant tous les en-têtes et valeurs de champs associées du message.
@end deffn

@geindex get() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get}@anchor{356e}
@deffn {Méthode} get (name, failobj=None)

Return the value of the named header field.  This is identical to
@ref{280,,__getitem__()} except that optional `failobj' is returned if the
named header is missing (defaults to @code{None}).
@end deffn

Voici quelques méthodes supplémentaires utiles :

@geindex get_all() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_all}@anchor{3569}
@deffn {Méthode} get_all (name, failobj=None)

Renvoie la liste de toutes les valeurs du champ nommé `name'. S'il n'y a pas d'en-têtes de ce nom dans le message, `failobj' est renvoyé (la valeur par défaut est @code{None}).
@end deffn

@geindex add_header() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message add_header}@anchor{356f}
@deffn {Méthode} add_header (_name, _value, **_params)

Définition de paramètres d'en-têtes étendus. Cette méthode est similaire à @ref{356a,,__setitem__()} sauf que des paramètres d'en-tête supplémentaires peuvent être fournis en tant qu'arguments nommés. `_name' est le champ d'en-tête à ajouter et `_value' est la valeur `primaire' de l'en-tête.

Pour chaque élément du dictionnaire d'arguments nommés `_params', la clé est prise comme nom de paramètre, avec des traits de soulignement convertis en tirets (puisque les tirets sont illégaux dans les identifiants Python). Normalement, le paramètre est ajouté en tant que @code{key="value"} sauf si la valeur est @code{None}, auquel cas seule la clé est ajoutée. Si la valeur contient des caractères non-ASCII, elle peut être spécifiée sous la forme d'un triplet au format @code{(CHARSET, LANGUAGE, VALUE)}, où @code{CHARSET} est une chaîne nommant le jeu de caractères à utiliser pour coder la valeur, @code{LANGUAGE} peut généralement être défini sur @code{None} ou la chaîne vide (voir la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} pour d'autres possibilités), et @code{VALUE} est la valeur de chaîne contenant des points de code non-ASCII. Si un triplet n'est pas passé et que la valeur contient des caractères non-ASCII, elle est automatiquement encodée au format 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} en utilisant un @code{CHARSET} à @code{utf-8} et un @code{LANGUAGE} à @code{None}.

Voici un exemple :

@example
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
@end example

Cela ajoute un en-tête qui ressemble à :

@example
Content-Disposition: attachment; filename="bud.gif"
@end example

Un exemple avec des caractères non-ASCII :

@example
msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '@w{'}, 'Fußballer.ppt'))
@end example

qui produit :

@example
Content-Disposition: attachment; filename*="iso-8859-1'@w{'}Fu%DFballer.ppt"
@end example
@end deffn

@geindex replace_header() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message replace_header}@anchor{3570}
@deffn {Méthode} replace_header (_name, _value)

Remplace un en-tête. Remplace le premier en-tête trouvé dans le message qui correspond à `_name', en conservant l'ordre des en-têtes et la casse des noms de champs. Si aucun en-tête correspondant n'a été trouvé, une @ref{33a,,KeyError} est levée.
@end deffn

@geindex get_content_type() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_content_type}@anchor{3571}
@deffn {Méthode} get_content_type ()

Renvoie le type de contenu du message. La chaîne renvoyée est convertie en minuscules sous la forme @code{maintype/subtype}. S'il n'y avait pas d'en-tête @code{Content-Type} dans le message, le type par défaut tel qu'indiqué par @ref{3572,,get_default_type()} est renvoyé. Puisque selon la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, les messages ont toujours un type par défaut, @ref{3571,,get_content_type()} renvoie toujours une valeur.

La 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} définit le type par défaut d'un message comme étant @code{text/plain} sauf s'il apparaît dans un conteneur @code{multipart/digest}, auquel cas ce serait @code{message/rfc822}. Si l'en-tête @code{Content-Type} a une spécification de type invalide, la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} exige que le type par défaut soit @code{text/plain}.
@end deffn

@geindex get_content_maintype() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_content_maintype}@anchor{3573}
@deffn {Méthode} get_content_maintype ()

Renvoie le type de contenu principal du message. C'est la partie @code{maintype} de la chaîne renvoyée par @ref{3571,,get_content_type()}.
@end deffn

@geindex get_content_subtype() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_content_subtype}@anchor{3574}
@deffn {Méthode} get_content_subtype ()

Renvoie le type de sous-contenu du message. C'est la partie @code{subtype} de la chaîne renvoyée par @ref{3571,,get_content_type()}.
@end deffn

@geindex get_default_type() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_default_type}@anchor{3572}
@deffn {Méthode} get_default_type ()

Renvoie le type de contenu par défaut. La plupart des messages ont un type de contenu par défaut de @code{text/plain}, à l'exception des messages qui sont des sous-parties des conteneurs @code{multipart/digest}. Ces sous-parties ont un type de contenu par défaut de @code{message/rfc822}.
@end deffn

@geindex set_default_type() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_default_type}@anchor{3575}
@deffn {Méthode} set_default_type (ctype)

Définit le type de contenu par défaut. `ctype' doit être @code{text/plain} ou @code{message/rfc822}, bien que cela ne soit pas appliqué. Le type de contenu par défaut n'est pas stocké dans l'en-tête @code{Content-Type}.
@end deffn

@geindex get_params() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_params}@anchor{3576}
@deffn {Méthode} get_params (failobj=None, header='content-type', unquote=True)

Renvoie les paramètres @code{Content-Type} du message, sous forme de liste. Les éléments de la liste renvoyée sont des couples clé-valeur, ayant été séparés sur le signe @code{'='}. Le côté gauche du @code{'='} est la clé, tandis que le côté droit est la valeur. S'il n'y a pas de signe @code{'='} dans le paramètre, la valeur est la chaîne vide, sinon la valeur est telle que décrite dans @ref{3577,,get_param()} et n'est pas entre guillemets si l'option `unquote' est @code{True} (la valeur par défaut).

`failobj' (facultatif) est l'objet à renvoyer s'il n'y a pas d'en-tête @code{Content-Type}. `header' (facultatif) est l'en-tête à rechercher au lieu de @code{Content-Type}.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage}, sa fonctionnalité est remplacée par la propriété `params' des objets d'en-tête individuels renvoyés par les méthodes d'accès aux en-têtes.
@end deffn

@geindex get_param() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_param}@anchor{3577}
@deffn {Méthode} get_param (param, failobj=None, header='content-type', unquote=True)

Renvoie la valeur du paramètre `param' de l'en-tête @code{Content-Type} sous forme de chaîne. Si le message n'a pas d'en-tête @code{Content-Type} ou s'il n'y a pas un tel paramètre, alors `failobj' est renvoyé (par défaut à @code{None}).

`header' s'il est fourni, spécifie l'en-tête de message à utiliser à la place de @code{Content-Type}.

Les clés en paramètre sont toujours comparées sans tenir compte de la casse. La valeur de retour peut être soit une chaîne, soit un triplet si le paramètre a été encodé selon la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. Lorsqu'il s'agit d'un triplet, les éléments de la valeur sont de la forme @code{(CHARSET, LANGUAGE, VALUE)}. Notez que @code{CHARSET} et @code{LANGUAGE} peuvent être @code{None}, vous devriez alors considérer que @code{VALUE} est encodé dans le jeu de caractères @code{us-ascii}. Vous pouvez généralement ignorer @code{LANGUAGE}.

Si votre application ne se soucie pas de savoir si le paramètre a été encodé conformément à la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}, vous pouvez réduire la valeur du paramètre en appelant @ref{3578,,email.utils.collapse_rfc2231_value()}, en transmettant la valeur de retour de @ref{3577,,get_param()}. Cela renverra une chaîne Unicode convenablement décodée lorsque la valeur est un `n'-uplet, ou la chaîne d'origine sans guillemets si ce n'est pas le cas. Par exemple :

@example
rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)
@end example

Dans tous les cas, la valeur du paramètre (soit la chaîne renvoyée, soit l'élément @code{VALUE} dans le triplet) est toujours sans guillemets, sauf si `unquote' est défini sur @code{False}.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage}, sa fonctionnalité est remplacée par la propriété `params' des objets d'en-tête individuels renvoyés par les méthodes d'accès aux en-têtes.
@end deffn

@geindex set_param() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_param}@anchor{f24}
@deffn {Méthode} set_param (param, value, header='Content-Type', requote=True, charset=None, language='@w{'}, replace=False)

Définit un paramètre dans l'en-tête @code{Content-Type}. Si le paramètre existe déjà dans l'en-tête, sa valeur est remplacée par `value'. Si l'en-tête @code{Content-Type} n'a pas encore été défini pour ce message, il est défini à @code{text/plain} et la nouvelle valeur du paramètre est ajoutée conformément à la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}.

L'option `header' spécifie un en-tête alternatif à @code{Content-Type}, et tous les paramètres seront entre guillemets si nécessaire sauf si l'option `requote' est @code{False} (la valeur par défaut est @code{True}).

Si `charset' est spécifié, le paramètre est encodé selon la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. `language' (facultatif) spécifie la langue RFC 2231, par défaut c'est la chaîne vide. `charset' et `language' doivent être des chaînes.

Si `replace' est @code{False} (valeur par défaut), l'en-tête est déplacé à la fin de la liste des en-têtes. Si `replace' est @code{True}, l'en-tête est mis à jour « sur place ».


Modifié dans la version 3.4: l'argument nommé @code{replace} a été ajouté.

@end deffn

@geindex del_param() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message del_param}@anchor{3579}
@deffn {Méthode} del_param (param, header='content-type', requote=True)

Supprime complètement le paramètre donné de l'en-tête @code{Content-Type}. L'en-tête est réécrit « sur place » sans le paramètre ou sa valeur. Toutes les valeurs seront entre guillemets si nécessaire sauf si `requote' est @code{False} (la valeur par défaut est @code{True}). L'option `header' spécifie une alternative à @code{Content-Type}.
@end deffn

@geindex set_type() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_type}@anchor{357a}
@deffn {Méthode} set_type (type, header='Content-Type', requote=True)

Définit le type principal et le sous-type de l'en-tête @code{Content-Type}. `type' doit être une chaîne sous la forme @code{maintype/subtype}, sinon une @ref{1ff,,ValueError} est levée.

Cette méthode remplace l'en-tête @code{Content-Type}, en gardant tous les paramètres en place. Si `requote' est @code{False}, cela laisse les guillemets de l'en-tête existant tels quels, sinon les paramètres sont mis entre guillemets (par défaut).

Un en-tête alternatif peut être spécifié dans l'argument `header'. Lorsque l'en-tête @code{Content-Type} est défini, un en-tête @code{MIME-Version} est également ajouté.

Il s'agit d'une ancienne méthode. Dans la classe @code{EmailMessage} sa fonctionnalité est remplacée par les méthodes @code{make_} et @code{add_}.
@end deffn

@geindex get_filename() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_filename}@anchor{357b}
@deffn {Méthode} get_filename (failobj=None)

Renvoie la valeur du paramètre @code{filename} de l'en-tête @code{Content-Disposition} du message. Si l'en-tête n'a pas de paramètre @code{filename}, cette méthode revient à rechercher le paramètre @code{name} dans l'en-tête @code{Content-Type}. Si aucun n'est trouvé, ou si l'en-tête est manquant, alors `failobj' est renvoyé. La chaîne renvoyée est toujours sans guillemets comme indiqué par @ref{34d0,,email.utils.unquote()}.
@end deffn

@geindex get_boundary() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_boundary}@anchor{357c}
@deffn {Méthode} get_boundary (failobj=None)

Renvoie la valeur du paramètre @code{boundary} de l'en-tête @code{Content-Type} du message, ou `failobj' si l'en-tête est manquant ou n'a pas de paramètre @code{boundary}. La chaîne renvoyée est toujours sans guillemets comme indiqué par @ref{34d0,,email.utils.unquote()}.
@end deffn

@geindex set_boundary() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message set_boundary}@anchor{357d}
@deffn {Méthode} set_boundary (boundary)

Définit le paramètre @code{boundary} de l'en-tête @code{Content-Type} sur `boundary'. @ref{357d,,set_boundary()} met toujours `boundary' entre guillemets si nécessaire. Une @ref{34d3,,HeaderParseError} est levée si l'objet message n'a pas d'en-tête @code{Content-Type}.

Notez que l'utilisation de cette méthode est légèrement différente de la suppression de l'ancien en-tête @code{Content-Type} et de l'ajout d'un nouveau avec la nouvelle limite via @ref{356f,,add_header()}, car @ref{357d,,set_boundary()} préserve l'ordre des en-têtes @code{Content-Type} dans la liste des en-têtes. Cependant, elle ne conserve `pas' les lignes de continuation qui auraient pu être présentes dans l'en-tête original @code{Content-Type}.
@end deffn

@geindex get_content_charset() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_content_charset}@anchor{357e}
@deffn {Méthode} get_content_charset (failobj=None)

Renvoie le paramètre @code{charset} de l'en-tête @code{Content-Type}, mis en minuscules. S'il n'y a pas d'en-tête @code{Content-Type}, ou si cet en-tête n'a pas de paramètre @code{charset}, `failobj' est renvoyé.

Notez que cette méthode diffère de @ref{3565,,get_charset()} qui renvoie l'instance @ref{de7,,Charset} avec l'encodage par défaut du corps du message.
@end deffn

@geindex get_charsets() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_charsets}@anchor{357f}
@deffn {Méthode} get_charsets (failobj=None)

Renvoie une liste contenant les noms des jeux de caractères dans le message. Si le message est un @code{multipart}, alors la liste contient un élément pour chaque sous-partie dans la charge utile, sinon, c'est une liste de longueur 1.

Chaque élément de la liste est une chaîne qui est la valeur du paramètre @code{charset} dans l'en-tête @code{Content-Type} pour la sous-partie représentée. Cependant, si la sous-partie n'a pas d'en-tête @code{Content-Type}, pas de paramètre @code{charset}, ou n'est pas du type MIME principal @code{text}, alors cet élément dans la liste renvoyée est `failobj'.
@end deffn

@geindex get_content_disposition() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message get_content_disposition}@anchor{de4}
@deffn {Méthode} get_content_disposition ()

Renvoie la valeur en minuscules (sans paramètres) de l'en-tête @code{Content-Disposition} du message s'il en a un, ou @code{None}. Les valeurs possibles pour cette méthode sont `inline', `attachment' ou @code{None} si le message suit la 
@geindex RFC; RFC 2183
RFC 2183@footnote{https://datatracker.ietf.org/doc/html/rfc2183.html}.


Ajouté dans la version 3.5.

@end deffn

@geindex walk() (méthode email.message.Message)
@anchor{library/email compat32-message email message Message walk}@anchor{3580}
@deffn {Méthode} walk ()

La méthode @ref{3580,,walk()} est un générateur polyvalent qui peut être utilisé pour itérer sur toutes les parties et sous-parties d'une arborescence d'objets de message, dans l'ordre de parcours en profondeur d'abord. Vous utiliserez généralement @ref{3580,,walk()} comme itérateur dans une boucle @code{for} ; chaque itération renvoie la sous-partie suivante.

Voici un exemple qui imprime le type MIME de chaque partie d'une structure de message en plusieurs parties :

@c import email
@c from email import message_from_binary_file
@c from os.path import join, dirname
@c lib_dir = dirname(dirname(email.__file__))
@c file_path = join(lib_dir, 'test/test_email/data/msg_16.txt')
@c with open(file_path, 'rb') as f:
@c     msg = message_from_binary_file(f)
@c from email.iterators import _structure

@example
>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain
@end example

@code{walk} itère sur les sous-parties de toute partie où @ref{34d7,,is_multipart()} renvoie @code{True}, même si @code{msg.get_content_maintype() == 'multipart'} peut renvoyer @code{False}. Nous pouvons le voir dans notre exemple en utilisant la fonction d'aide au débogage @code{_structure} :

@example
>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain
@end example

Ici, les parties @code{message} ne sont pas des @code{multiparts}, mais elles contiennent des sous-parties. @code{is_multipart()} renvoie @code{True} et @code{walk} descend dans les sous-parties.
@end deffn

Les objets @ref{279,,Message} peuvent aussi éventuellement contenir deux attributs d'instance, qui peuvent être utilisés lors de la génération du texte brut d'un message MIME.

@geindex preamble (attribut email.message.Message)
@anchor{library/email compat32-message email message Message preamble}@anchor{3581}
@deffn {Attribut} preamble

Le format d'un document MIME permet d'insérer du texte entre la ligne vide suivant les en-têtes et la première chaîne de délimitation en plusieurs parties. Normalement, ce texte n'est jamais visible dans un lecteur de courrier compatible MIME car il ne fait pas partie du cadre MIME standard. Toutefois, lors de l'affichage du texte brut du message ou lors de l'affichage du message dans un lecteur non compatible MIME, ce texte peut devenir visible.

L'attribut `preamble' contient ce texte hors-cadre de tête pour les documents MIME. Lorsque @ref{117c,,Parser} découvre du texte après les en-têtes mais avant la première chaîne de délimitation, il attribue ce texte à l'attribut `preamble' du message. Lorsque @ref{11ab,,Generator} écrit la représentation en texte brut d'un message MIME, et qu'il trouve que le message a un attribut `preamble', il écrit ce texte dans la zone entre les en-têtes et la première frontière. Voir @ref{4e,,email.parser} et @ref{40,,email.generator} pour plus de détails.

Notez que si l'objet message n'a pas de préambule, l'attribut `preamble' est @code{None}.
@end deffn

@geindex epilogue (attribut email.message.Message)
@anchor{library/email compat32-message email message Message epilogue}@anchor{3582}
@deffn {Attribut} epilogue

L'attribut `epilogue' agit de la même manière que l'attribut `preamble', sauf qu'il contient du texte qui apparaît entre la dernière limite et la fin du message.

Vous n'avez pas besoin de définir l'épilogue sur la chaîne vide pour que @ref{11ab,,Generator} imprime une nouvelle ligne à la fin du fichier.
@end deffn

@geindex defects (attribut email.message.Message)
@anchor{library/email compat32-message email message Message defects}@anchor{3583}
@deffn {Attribut} defects

L'attribut `defects' contient une liste de tous les problèmes rencontrés lors de l'analyse de ce message. Voir @ref{3f,,email.errors} pour une description détaillée des défauts d'analyse possibles.
@end deffn
@end deffn

@node email mime Creating email and MIME objects from scratch,email header Internationalized headers,email message Message représentation d'un message électronique à l'aide de l'API compat32,email --- An email and MIME handling package
@anchor{library/email mime doc}@anchor{3584}@anchor{library/email mime email-mime-creating-email-and-mime-objects-from-scratch}@anchor{3585}@anchor{library/email mime module-email mime}@anchor{45}
@subsubsection @code{email.mime}: Creating email and MIME objects from scratch


@geindex module; email.mime

`Code source :' Lib/email/mime/@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/mime/}


__________________________________________________________________


Ce module fait partie de l'ancienne API de messagerie (@code{Compat32}). Sa fonctionnalité est partiellement remplacée par le @ref{3d,,contentmanager} dans la nouvelle API mais, dans certaines applications, ces classes peuvent toujours être utiles, même dans du code pas si ancien.

Habituellement, vous obtenez une structure d'objet message en passant un fichier ou du texte à un analyseur, qui analyse le texte et renvoie l'objet message racine. Cependant, vous pouvez également créer une structure de message complète à partir de zéro, ou même des objets individuels @ref{279,,Message} à la main. En fait, vous pouvez également prendre une structure existante et ajouter de nouveaux objets @ref{279,,Message}, les déplacer, etc. Cela crée une interface très pratique pour découper et manipuler chaque morceau de messages MIME.

Vous pouvez créer une nouvelle structure d'objet en créant des instances @ref{279,,Message}, en ajoutant manuellement les pièces jointes et tous les en-têtes appropriés. Pour les messages MIME cependant, le paquet @ref{3b,,email} fournit quelques sous-classes pratiques pour faciliter les choses.

Voici les classes :

@geindex module; email.mime.base

@geindex MIMEBase (classe dans email.mime.base)
@anchor{library/email mime module-email mime base}@anchor{48}@anchor{library/email mime email mime base MIMEBase}@anchor{3586}
@deffn {Classe} email.mime.base.MIMEBase (_maintype, _subtype, *, policy=compat32, **_params)

Module : @ref{48,,email.mime.base}

C'est la classe mère pour toutes les sous-classes spécifiques à MIME de @ref{279,,Message}. Normalement, vous ne créerez pas d'instances spécifiques de @ref{3586,,MIMEBase}, bien que cela soit possible. @ref{3586,,MIMEBase} est fourni principalement comme une classe mère pratique pour des sous-classes plus spécifiques compatibles MIME.

`_maintype' est le type majeur du @code{Content-Type} (par exemple @code{text} ou @code{image}) et `_subtype' est le type mineur du @code{Content-Type} (par exemple, @code{plain} ou @code{gif}). `_params' est un paramètre dictionnaire clé-valeur et est transmis directement à @ref{356f,,Message.add_header}.

Si `policy' est spécifiée, (par défaut la politique @ref{1096,,compat32}) elle est passée à @ref{279,,Message}.

La classe @ref{3586,,MIMEBase} ajoute toujours un en-tête @code{Content-Type} (basé sur `_maintype', `_subtype' et `_params') et un en-tête @code{MIME-Version} (toujours défini à @code{1.0}).


Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@geindex module; email.mime.nonmultipart

@geindex MIMENonMultipart (classe dans email.mime.nonmultipart)
@anchor{library/email mime module-email mime nonmultipart}@anchor{4c}@anchor{library/email mime email mime nonmultipart MIMENonMultipart}@anchor{3527}
@deffn {Classe} email.mime.nonmultipart.MIMENonMultipart

Module : @ref{4c,,email.mime.nonmultipart}

Sous-classe de @ref{3586,,MIMEBase}, c'est une classe mère intermédiaire pour les messages MIME qui ne sont pas @code{multipart}. Le but principal de cette classe est d'empêcher l'utilisation de la méthode @ref{34e4,,attach()}, qui n'a de sens que pour les messages @code{multipart}. Si @ref{34e4,,attach()} est appelée, une exception @ref{3526,,MultipartConversionError} est levée.
@end deffn

@geindex module; email.mime.multipart

@geindex MIMEMultipart (classe dans email.mime.multipart)
@anchor{library/email mime module-email mime multipart}@anchor{4b}@anchor{library/email mime email mime multipart MIMEMultipart}@anchor{3587}
@deffn {Classe} email.mime.multipart.MIMEMultipart (_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

Module : @ref{4b,,email.mime.multipart}

Sous-classe de @ref{3586,,MIMEBase}, c'est une classe mère intermédiaire pour les messages MIME qui sont @code{multipart}. `_subtype' (facultatif) est par défaut @code{mixed}, mais peut être utilisé pour spécifier le sous-type du message. Un en-tête @code{Content-Type} de @code{multipart/_subtype} sera ajouté à l'objet message. Un en-tête @code{MIME-Version} sera également ajouté.

`boundary' (facultatif) est la chaîne de délimitation en plusieurs parties. Si elle vaut @code{None} (la valeur par défaut), la délimitation est calculée au besoin (par exemple, lorsque le message est sérialisé).

`_subparts' est une séquence de sous-parties initiales pour la charge utile. Il doit être possible de convertir cette séquence en une liste. Vous pouvez toujours joindre de nouvelles sous-parties au message en utilisant la méthode @ref{34e4,,Message.attach}.

L'argument facultatif `policy' est par défaut @ref{1096,,compat32}.

Des paramètres supplémentaires pour l'en-tête @code{Content-Type} sont extraits des arguments nommés ou passés à l'argument `_params', qui est un dictionnaire de mots-clés.


Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@geindex module; email.mime.application

@geindex MIMEApplication (classe dans email.mime.application)
@anchor{library/email mime module-email mime application}@anchor{46}@anchor{library/email mime email mime application MIMEApplication}@anchor{3588}
@deffn {Classe} email.mime.application.MIMEApplication (_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Module : @ref{46,,email.mime.application}

Sous-classe de @ref{3527,,MIMENonMultipart}, la classe @ref{3588,,MIMEApplication} est utilisée pour représenter les objets de message MIME de type principal @code{application}. `_data' contient les octets pour les données d'application brutes. L'option `_subtype' spécifie le sous-type MIME et la valeur par défaut est @code{octet-stream}.

`_encoder' (facultatif) est un appelable (c'est-à-dire une fonction) qui effectue le codage réel des données pour le transport. Cet appelable prend un argument, qui est l'instance @ref{3588,,MIMEApplication}. Il doit utiliser @ref{11aa,,get_payload()} et @ref{3563,,set_payload()} pour modifier la charge utile sous forme codée. Il doit également ajouter n'importe quel @code{Content-Transfer-Encoding} ou d'autres en-têtes à l'objet message si nécessaire. L'encodage par défaut est base64. Voir le module @ref{3e,,email.encoders} pour une liste des encodeurs intégrés.

L'argument facultatif `policy' est par défaut @ref{1096,,compat32}.

Les `_params' sont transmis directement au constructeur de la classe mère.


Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@geindex module; email.mime.audio

@geindex MIMEAudio (classe dans email.mime.audio)
@anchor{library/email mime module-email mime audio}@anchor{47}@anchor{library/email mime email mime audio MIMEAudio}@anchor{3589}
@deffn {Classe} email.mime.audio.MIMEAudio (_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Module : @ref{47,,email.mime.audio}

Sous-classe de @ref{3527,,MIMENonMultipart}, la classe @ref{3589,,MIMEAudio} est utilisée pour créer des objets de message MIME de type majeur @code{audio}. `_audiodata' contient les octets pour les données audio brutes. Si ces données peuvent être décodées au format `au', `wav', `aiff' ou `aifc', alors le sous-type est automatiquement inclus dans l'en-tête @code{Content-Type}. Sinon, vous pouvez spécifier explicitement le sous-type audio via l'argument `_subtype'. Si le type mineur n'a pas pu être deviné et que `_subtype' n'a pas été donné, alors une @ref{522,,TypeError} est levée.

`_encoder' (facultatif) est un appelable (c'est-à-dire une fonction) qui effectue le codage réel des données audio pour le transport. Cet appelable prend un argument, qui est l'instance @ref{3589,,MIMEAudio}. Il doit utiliser @ref{11aa,,get_payload()} et @ref{3563,,set_payload()} pour modifier la charge utile sous forme codée. Il doit également ajouter n'importe quel @code{Content-Transfer-Encoding} ou d'autres en-têtes à l'objet message si nécessaire. L'encodage par défaut est base64. Voir le module @ref{3e,,email.encoders} pour une liste des encodeurs intégrés.

L'argument facultatif `policy' est par défaut @ref{1096,,compat32}.

Les `_params' sont transmis directement au constructeur de la classe mère.


Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@geindex module; email.mime.image

@geindex MIMEImage (classe dans email.mime.image)
@anchor{library/email mime module-email mime image}@anchor{49}@anchor{library/email mime email mime image MIMEImage}@anchor{3528}
@deffn {Classe} email.mime.image.MIMEImage (_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Module : @ref{49,,email.mime.image}

Sous-classe de @ref{3527,,MIMENonMultipart}, la classe @ref{3528,,MIMEImage} est utilisée pour créer des objets de message MIME de type principal @code{image}. `_imagedata' contient les octets pour les données d'image brutes. Si ce type de données peut être détecté (`jpeg', `png', `gif', `tiff', `rgb', `pbm', `pgm', `ppm', `rast', `xbm', `bmp', `webp' et `exr' sont essayés), alors le sous-type est automatiquement inclus dans l'en-tête @code{Content-Type}. Sinon, vous pouvez spécifier explicitement le sous-type d'image via l'argument `_subtype'. Si le type mineur n'a pas pu être deviné et que `_subtype' n'a pas été donné, alors une @ref{522,,TypeError} est levée.

`_encoder' (facultatif) est un appelable (c'est-à-dire une fonction) qui effectue le codage réel des données d'image pour le transport. Cet appelable prend un argument, qui est l'instance @ref{3528,,MIMEImage}. Il doit utiliser @ref{11aa,,get_payload()} et @ref{3563,,set_payload()} pour modifier la charge utile sous forme codée. Il doit également ajouter n'importe quel @code{Content-Transfer-Encoding} ou d'autres en-têtes à l'objet message si nécessaire. L'encodage par défaut est base64. Voir le module @ref{3e,,email.encoders} pour une liste des encodeurs intégrés.

L'argument facultatif `policy' est par défaut @ref{1096,,compat32}.

Les `_params' sont transmis directement au constructeur @ref{3586,,MIMEBase}.


Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@geindex module; email.mime.message

@geindex MIMEMessage (classe dans email.mime.message)
@anchor{library/email mime module-email mime message}@anchor{4a}@anchor{library/email mime email mime message MIMEMessage}@anchor{358a}
@deffn {Classe} email.mime.message.MIMEMessage (_msg, _subtype='rfc822', *, policy=compat32)

Module : @ref{4a,,email.mime.message}

Sous-classe de @ref{3527,,MIMENonMultipart}, la classe @ref{358a,,MIMEMessage} est utilisée pour créer des objets MIME de type principal @code{message}. `_msg' est utilisé comme charge utile et doit être une instance de la classe @ref{279,,Message} (ou une sous-classe de celle-ci), sinon une @ref{522,,TypeError} est levée.

L'option `_subtype' définit le sous-type du message ; par défaut c'est @code{rfc822}.

L'argument facultatif `policy' est par défaut @ref{1096,,compat32}.


Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@geindex module; email.mime.text

@geindex MIMEText (classe dans email.mime.text)
@anchor{library/email mime module-email mime text}@anchor{4d}@anchor{library/email mime email mime text MIMEText}@anchor{de6}
@deffn {Classe} email.mime.text.MIMEText (_text, _subtype='plain', _charset=None, *, policy=compat32)

Module : @ref{4d,,email.mime.text}

Sous-classe de @ref{3527,,MIMENonMultipart}, la classe @ref{de6,,MIMEText} est utilisée pour créer des objets MIME de type principal @code{text}. `_text' est la chaîne de la charge utile. `_subtype' est le type mineur et par défaut est @code{plain}. `_charset' est le jeu de caractères du texte et est passé en argument au constructeur @ref{3527,,MIMENonMultipart} ; sa valeur par défaut est @code{us-ascii} si la chaîne ne contient que des points de code @code{ascii}, et @code{utf-8} sinon. Le paramètre `_charset' accepte soit une chaîne soit une instance @ref{de7,,Charset}.

À moins que l'argument `_charset' ne soit explicitement défini sur @code{None}, l'objet `MIMEText' créé possède à la fois un en-tête @code{Content-Type} avec un paramètre @code{charset} et un en-tête @code{Content-Transfer-Encoding}. Cela signifie qu'un appel ultérieur à @code{set_payload} n'entraîne pas l'encodage de la charge utile, même si un jeu de caractères est passé dans la commande @code{set_payload}. Vous pouvez « réinitialiser » ce comportement en supprimant l'en-tête @code{Content-Transfer-Encoding}, après quoi un appel @code{set_payload} encodera automatiquement la nouvelle charge utile (et ajoutera un nouvel en-tête @code{Content-Transfer-Encoding}).

L'argument facultatif `policy' est par défaut @ref{1096,,compat32}.


Modifié dans la version 3.5: `_charset' accepte également les instances @ref{de7,,Charset}.



Modifié dans la version 3.6: ajout du paramètre nommé `policy'.

@end deffn

@node email header Internationalized headers,email charset Representing character sets,email mime Creating email and MIME objects from scratch,email --- An email and MIME handling package
@anchor{library/email header doc}@anchor{358b}@anchor{library/email header email-header-internationalized-headers}@anchor{358c}@anchor{library/email header module-email header}@anchor{41}
@subsubsection @code{email.header}: Internationalized headers


@geindex module; email.header

`Code source :' Lib/email/headers.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/headers.py}


__________________________________________________________________


Ce module fait partie de l'ancienne API de messagerie (@code{Compat32}). Dans l'API actuelle, l'encodage et le décodage des en-têtes sont gérés de manière transparente par l'API de type dictionnaire de la classe @ref{278,,EmailMessage}. En plus des utilisations dans de l'ancien code, ce module peut être utile dans les applications qui doivent contrôler complètement les jeux de caractères utilisés lors de l'encodage des en-têtes.

Le texte restant de cette section est la documentation originale de ce module.

La 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} est la norme de base qui décrit le format des messages électroniques. Elle dérive de l'ancienne norme 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} qui s'est généralisée à une époque où la plupart des e-mails étaient composés uniquement de caractères ASCII. La 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} est une spécification écrite en supposant que le courrier électronique ne contient que des caractères ASCII 7 bits.

Bien sûr, à mesure que le courrier électronique a été déployé dans le monde, il s'est internationalisé, de sorte que des jeux de caractères spécifiques à une langue peuvent désormais être utilisés dans les messages électroniques. La norme de base exige toujours que les messages électroniques soient transférés en utilisant uniquement des caractères ASCII 7 bits, de sorte qu'un grand nombre de RFC décrivent comment encoder les e-mails contenant des caractères non ASCII dans le format conforme à la 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}. Ces RFC incluent la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}, la 
@geindex RFC; RFC 2046
RFC 2046@footnote{https://datatracker.ietf.org/doc/html/rfc2046.html}, la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} et la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. Le paquet @ref{3b,,email} gère ces normes dans ses modules @ref{41,,email.header} et @ref{3c,,email.charset}.

Si vous souhaitez inclure des caractères non-ASCII dans les en-têtes de vos e-mails, par exemple dans les champs @code{Subject} ou @code{To}, vous devez utiliser la classe @ref{1837,,Header} et affecter le champ dans le @ref{279,,Message} à une instance de @ref{1837,,Header} au lieu d'utiliser une chaîne pour la valeur de l'en-tête. Importez la classe @ref{1837,,Header} du module @ref{41,,email.header}. Par exemple :

@example
>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'
@end example

Remarquez ici comment nous voulions que le champ @code{Subject} contienne un caractère non-ASCII : nous avons créé une instance @ref{1837,,Header} et transmis le jeu de caractères dans lequel la chaîne d'octets était encodée. Lorsque l'instance suivante @ref{279,,Message} a été aplatie, le champ @code{Subject} était correctement encodé selon la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}. Les lecteurs de courrier compatibles MIME afficheraient cet en-tête en utilisant le caractère ISO-8859-1 intégré.

Voici la description de la classe @ref{1837,,Header} :

@geindex Header (classe dans email.header)
@anchor{library/email header email header Header}@anchor{1837}
@deffn {Classe} email.header.Header (s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

Crée un en-tête compatible MIME pouvant contenir des chaînes dans différents jeux de caractères.

`s' (facultatif) est la valeur d'en-tête initiale. S'il vaut @code{None} (valeur par défaut), la valeur d'en-tête initiale n'est pas définie. Vous pouvez ensuite ajouter des choses à l'en-tête avec des appels de méthode @ref{358d,,append()}. `s' peut être une instance de @ref{1bd,,bytes} ou @ref{435,,str}, mais consultez la documentation @ref{358d,,append()} pour la sémantique.

L'option `charset' sert à deux fins : elle a la même signification que l'argument `charset' de la méthode @ref{358d,,append()}. Elle définit également le jeu de caractères par défaut pour tous les appels suivants @ref{358d,,append()} qui omettent l'argument `charset'. Si `charset' n'est pas fourni dans le constructeur (par défaut), le jeu de caractères @code{us-ascii} est utilisé à la fois comme jeu de caractères initial de `s' et comme jeu par défaut pour les appels suivants à @ref{358d,,append()}.

The maximum line length can be specified explicitly via `maxlinelen'.  For
splitting the first line to a shorter value (to account for the field header
which isn't included in `s', e.g. @code{Subject}) pass in the name of the
field in `header_name'.  The default `maxlinelen' is 78, and the default value
for `header_name' is @code{None}, meaning it is not taken into account for the
first line of a long, split header.

`continuation_ws' (facultatif) doit être conforme aux caractères de reformatage 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} ; c'est généralement soit une espace, soit un caractère de tabulation fixe. Ce caractère est ajouté aux lignes de continuation. `continuation_ws' utilise par défaut une seule espace.

`errors' (facultatif) est transmis directement à la méthode @ref{358d,,append()}.

@geindex append() (méthode email.header.Header)
@anchor{library/email header email header Header append}@anchor{358d}
@deffn {Méthode} append (s, charset=None, errors='strict')

Ajoute la chaîne `s' à l'en-tête MIME.

Le `charset' facultatif, s'il est fourni, doit être une instance de @ref{de7,,Charset} (voir @ref{3c,,email.charset}) ou le nom d'un jeu de caractères, qui est converti en une instance @ref{de7,,Charset}. Une valeur @code{None} (la valeur par défaut) signifie que le `charset' donné dans le constructeur est utilisé.

`s' peut être une instance de @ref{1bd,,bytes} ou @ref{435,,str}. S'il s'agit d'une instance de @ref{1bd,,bytes}, alors `charset' est l'encodage de cette chaîne d'octets et une @ref{1281,,UnicodeError} est levée si la chaîne ne peut pas être décodée avec ce jeu de caractères.

Si `s' est une instance de @ref{435,,str}, alors `charset' est une indication spécifiant le jeu de caractères des caractères de la chaîne.

Dans les deux cas, lors de la production d'un en-tête conforme à la 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} à l'aide des règles 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}, la chaîne est encodée à l'aide du codec de sortie du jeu de caractères. Si la chaîne ne peut pas être encodée à l'aide du codec de sortie, une erreur `UnicodeError' est levée.

L'option `errors' est transmise comme argument d'erreurs à l'appel de décodage si `s' est une chaîne d'octets.
@end deffn

@geindex encode() (méthode email.header.Header)
@anchor{library/email header email header Header encode}@anchor{358e}
@deffn {Méthode} encode (splitchars=';, \t', maxlinelen=None, linesep='\n')

Encode un en-tête de message dans un format conforme à la RFC, en reformatant éventuellement de longues lignes et en encapsulant des parties non ASCII dans des encodages base64 ou dits `quoted-printable' (c.-à-d. que, par exemple, les caractères non ASCII sont représentés par un signe égal, suivi de son numéro, exprimé en hexadécimal).

`splitchars' (facultatif) est une chaîne contenant des caractères auxquels l'algorithme de fractionnement doit donner un poids supplémentaire lors du reformatage normal de l'en-tête. Il s'agit d'une prise en charge très approximative des « ruptures syntaxiques de niveau supérieur » de la 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} : les points de séparation précédés d'un caractère de séparation sont préférés lors de la séparation des lignes, les caractères étant préférés dans l'ordre dans lequel ils apparaissent dans la chaîne. Une espace et une tabulation peuvent être incluses dans la chaîne pour indiquer si la préférence doit être donnée à l'une plutôt qu'à l'autre comme point de partage lorsque d'autres caractères fractionnés n'apparaissent pas dans la ligne fractionnée. `splitchars' n'affecte pas les lignes encodées selon la 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html}.

`maxlinelen', s'il est fourni, remplace la valeur de l'instance pour la longueur de ligne maximale.

`linesep' spécifie les caractères utilisés pour séparer les lignes de l'en-tête plié. Il prend par défaut la valeur la plus utile pour le code d'application Python (@code{\n}), mais @code{\r\n} peut être spécifié afin de produire des en-têtes avec des séparateurs de ligne conformes à la RFC.


Modifié dans la version 3.2: ajout de l'argument `linesep'.

@end deffn

La classe @ref{1837,,Header} fournit également un certain nombre de méthodes pour prendre en charge les opérateurs standard et les fonctions intégrées.

@geindex __str__() (méthode email.header.Header)
@anchor{library/email header email header Header __str__}@anchor{358f}
@deffn {Méthode} __str__ ()

Renvoie une approximation de @ref{1837,,Header} sous forme de chaîne, en utilisant une longueur de ligne illimitée. Toutes les parties sont converties en Unicode en utilisant l'encodage spécifié et réunies de manière appropriée. Tous les morceaux avec un `charset' à @code{'unknown-8bit'} sont décodés en ASCII en utilisant le gestionnaire d'erreurs @code{'replace'}.


Modifié dans la version 3.2: ajout de la gestion du jeu de caractères @code{'unknown-8bit'}.

@end deffn

@geindex __eq__() (méthode email.header.Header)
@anchor{library/email header email header Header __eq__}@anchor{3590}
@deffn {Méthode} __eq__ (other)

Cette méthode vous permet de tester l'égalité de deux instances de @ref{1837,,Header}.
@end deffn

@geindex __ne__() (méthode email.header.Header)
@anchor{library/email header email header Header __ne__}@anchor{3591}
@deffn {Méthode} __ne__ (other)

Cette méthode vous permet de tester l'inégalité de deux instances de @ref{1837,,Header}.
@end deffn
@end deffn

Le module @ref{41,,email.header} fournit également les fonctions pratiques suivantes.

@geindex decode_header() (dans le module email.header)
@anchor{library/email header email header decode_header}@anchor{109a}
@deffn {Fonction} email.header.decode_header (header)

Décode une valeur d'en-tête de message sans convertir le jeu de caractères. La valeur de l'en-tête est dans `header'.

Cette fonction renvoie une liste de paires @code{(decoded_string, charset)} contenant chacune des parties décodées de l'en-tête. `charset' est @code{None} pour les parties non encodées de l'en-tête, sinon une chaîne en minuscules contenant le nom du jeu de caractères spécifié dans la chaîne encodée.

Voici un exemple :

@example
>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
@end example
@end deffn

@geindex make_header() (dans le module email.header)
@anchor{library/email header email header make_header}@anchor{109b}
@deffn {Fonction} email.header.make_header (decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Crée une instance @ref{1837,,Header} à partir d'une séquence de paires renvoyées par @ref{109a,,decode_header()}.

@ref{109a,,decode_header()} prend une chaîne de valeur d'en-tête et renvoie une séquence de paires au format @code{(decoded_string, charset)} où `charset' est le nom du jeu de caractères.

Cette fonction prend l'une de ces séquences de paires et renvoie une instance @ref{1837,,Header}. `maxlinelen', `header_name' et `continuation_ws' (facultatifs) s'utilisent comme dans le constructeur @ref{1837,,Header}.
@end deffn

@node email charset Representing character sets,email encoders Encoders,email header Internationalized headers,email --- An email and MIME handling package
@anchor{library/email charset doc}@anchor{3592}@anchor{library/email charset email-charset-representing-character-sets}@anchor{3593}@anchor{library/email charset module-email charset}@anchor{3c}
@subsubsection @code{email.charset}: Representing character sets


@geindex module; email.charset

`Code source :' Lib/email/charset.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/charset.py}


__________________________________________________________________


Ce module fait partie de l'ancienne API de messagerie (@code{Compat32}). Dans la nouvelle API, seule la table des alias est utilisée.

Le texte restant de cette section est la documentation originale de ce module.

Ce module fournit une classe @ref{de7,,Charset} pour représenter les jeux de caractères et les conversions de jeux de caractères dans les messages électroniques, ainsi qu'un registre de jeux de caractères et plusieurs méthodes pratiques pour manipuler ce registre. Les instances de @ref{de7,,Charset} sont utilisées dans plusieurs autres modules du paquet @ref{3b,,email}.

Importez cette classe depuis le module @ref{3c,,email.charset}.

@geindex Charset (classe dans email.charset)
@anchor{library/email charset email charset Charset}@anchor{de7}
@deffn {Classe} email.charset.Charset (input_charset=DEFAULT_CHARSET)

Associe les jeux de caractères à leurs propriétés d'e-mail.

Cette classe fournit des informations sur les exigences imposées aux e-mails pour un jeu de caractères spécifique. Elle fournit également des routines pratiques pour la conversion entre les jeux de caractères, compte tenu de la disponibilité des codecs applicables. Étant donné un jeu de caractères, elle fait de son mieux pour fournir des informations sur la façon d'utiliser ce jeu de caractères dans un message électronique d'une manière conforme à la RFC.

Certains jeux de caractères doivent être encodés avec `quoted-printable' ou en `base64' lorsqu'ils sont utilisés dans les en-têtes ou les corps des e-mails. Certains jeux de caractères doivent être convertis directement et ne sont pas autorisés dans les e-mails.

Le `input_charset' facultatif est tel que décrit ci-dessous ; il est toujours contraint en minuscules. Après avoir été normalisé par alias, il est également utilisé comme recherche dans le registre des jeux de caractères pour trouver le codage d'en-tête, le codage de corps et le codec de conversion de sortie à utiliser pour le jeu de caractères. Par exemple, si `input_charset' vaut @code{iso-8859-1}, alors les en-têtes et les corps seront encodés en utilisant `quoted-printable' et aucun codec de conversion de sortie n'est nécessaire. Si `input_charset' vaut @code{euc-jp}, alors les en-têtes seront encodés en `base64', les corps ne seront pas encodés, mais le texte de sortie sera converti du jeu de caractères @code{euc-jp} vers le jeu de caractères @code{iso-2022-jp}.

Les instances de @ref{de7,,Charset} ont les attributs de données suivants :

@geindex input_charset (attribut email.charset.Charset)
@anchor{library/email charset email charset Charset input_charset}@anchor{3594}
@deffn {Attribut} input_charset

Jeu de caractères initial spécifié. Les alias communs sont convertis en leurs noms de messagerie `officiels' (par exemple, @code{latin_1} est converti en @code{iso-8859-1}). Par défaut, @code{us-ascii} 7 bits.
@end deffn

@geindex header_encoding (attribut email.charset.Charset)
@anchor{library/email charset email charset Charset header_encoding}@anchor{3595}
@deffn {Attribut} header_encoding

If the character set must be encoded before it can be used in an email
header, this attribute will be set to @code{charset.QP} (for
quoted-printable), @code{charset.BASE64} (for base64 encoding), or
@code{charset.SHORTEST} for the shortest of QP or BASE64 encoding. Otherwise,
it will be @code{None}.
@end deffn

@geindex body_encoding (attribut email.charset.Charset)
@anchor{library/email charset email charset Charset body_encoding}@anchor{3596}
@deffn {Attribut} body_encoding

Same as `header_encoding', but describes the encoding for the mail
message's body, which indeed may be different than the header encoding.
@code{charset.SHORTEST} is not allowed for `body_encoding'.
@end deffn

@geindex output_charset (attribut email.charset.Charset)
@anchor{library/email charset email charset Charset output_charset}@anchor{3597}
@deffn {Attribut} output_charset

Certains jeux de caractères doivent être convertis avant de pouvoir être utilisés dans les en-têtes ou le corps des e-mails. Si le `input_charset' est un jeu de ce type, alors cet attribut contient le nom du jeu de caractères vers lequel la sortie sera convertie. Sinon, il vaut @code{None}.
@end deffn

@geindex input_codec (attribut email.charset.Charset)
@anchor{library/email charset email charset Charset input_codec}@anchor{3598}
@deffn {Attribut} input_codec

Nom du codec Python utilisé pour convertir le `input_charset' en Unicode. Si aucun codec de conversion n'est nécessaire, cet attribut vaut @code{None}.
@end deffn

@geindex output_codec (attribut email.charset.Charset)
@anchor{library/email charset email charset Charset output_codec}@anchor{3599}
@deffn {Attribut} output_codec

Nom du codec Python utilisé pour convertir Unicode en `output_charset'. Si aucun codec de conversion n'est nécessaire, cet attribut a la même valeur que le `input_codec'.
@end deffn

Les instances de @ref{de7,,Charset} ont également les méthodes suivantes :

@geindex get_body_encoding() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset get_body_encoding}@anchor{359a}
@deffn {Méthode} get_body_encoding ()

Renvoie l'encodage de transfert de contenu utilisé pour l'encodage du corps.

Il s'agit soit de la chaîne @code{quoted-printable} ou @code{base64} selon l'encodage utilisé, soit d'une fonction, vous devez alors appeler la fonction avec un seul argument, l'objet Message étant encodé. La fonction doit ensuite définir l'en-tête @code{Content-Transfer-Encoding} à la valeur appropriée.

Renvoie la chaîne @code{quoted-printable} si `body_encoding' est @code{QP}, renvoie la chaîne @code{base64} si `body_encoding' est @code{BASE64} et renvoie la chaîne @code{7bit} sinon.
@end deffn

@geindex get_output_charset() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset get_output_charset}@anchor{359b}
@deffn {Méthode} get_output_charset ()

Renvoie le jeu de caractères de sortie.

C'est l'attribut `output_charset' si ce n'est pas @code{None}, sinon c'est `input_charset'.
@end deffn

@geindex header_encode() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset header_encode}@anchor{359c}
@deffn {Méthode} header_encode (string)

Encode la chaîne `string' pour un en-tête.

Le type d'encodage (`base64' ou `quoted-printable') est basé sur l'attribut `header_encoding'.
@end deffn

@geindex header_encode_lines() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset header_encode_lines}@anchor{359d}
@deffn {Méthode} header_encode_lines (string, maxlengths)

Encode `string' en la convertissant d'abord en octets, pour un en-tête.

C'est similaire à @ref{359c,,header_encode()} sauf que la chaîne est adaptée aux longueurs de ligne maximales indiquées par l'argument `maxlengths', qui doit être un itérateur : chaque élément renvoyé par cet itérateur fournit la prochaine longueur de ligne maximale.
@end deffn

@geindex body_encode() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset body_encode}@anchor{359e}
@deffn {Méthode} body_encode (string)

Encode la chaîne `string' pour un usage en corps de message.

Le type d'encodage (`base64' ou `quoted-printable') est basé sur l'attribut `body_encoding'.
@end deffn

La classe @ref{de7,,Charset} fournit également un certain nombre de méthodes pour prendre en charge les opérations standard et les fonctions intégrées.

@geindex __str__() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset __str__}@anchor{359f}
@deffn {Méthode} __str__ ()

Returns `input_charset' as a string coerced to lower
case. @code{__repr__()} is an alias for @code{__str__()}.
@end deffn

@geindex __eq__() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset __eq__}@anchor{35a0}
@deffn {Méthode} __eq__ (other)

Cette méthode vous permet de tester l'égalité de deux instances de @ref{de7,,Charset}.
@end deffn

@geindex __ne__() (méthode email.charset.Charset)
@anchor{library/email charset email charset Charset __ne__}@anchor{35a1}
@deffn {Méthode} __ne__ (other)

Cette méthode vous permet de tester l'inégalité de deux instances de @ref{de7,,Charset}.
@end deffn
@end deffn

Le module @ref{3c,,email.charset} fournit également les fonctions suivantes pour ajouter de nouvelles entrées à l'ensemble des jeux de caractères globaux, aux registres d'alias et de codec :

@geindex add_charset() (dans le module email.charset)
@anchor{library/email charset email charset add_charset}@anchor{35a2}
@deffn {Fonction} email.charset.add_charset (charset, header_enc=None, body_enc=None, output_charset=None)

Ajoute des propriétés relatives d'un jeu de caractères dans le registre global.

`charset' est le jeu de caractères d'entrée et doit être le nom canonique d'un jeu de caractères.

Optional `header_enc' and `body_enc' is either @code{charset.QP} for
quoted-printable, @code{charset.BASE64} for base64 encoding,
@code{charset.SHORTEST} for the shortest of quoted-printable or base64 encoding,
or @code{None} for no encoding.  @code{SHORTEST} is only valid for
`header_enc'. The default is @code{None} for no encoding.

`output_charset' (facultatif) est le jeu de caractères dans lequel doit être la sortie. Les conversions se poursuivent du jeu de caractères d'entrée, vers Unicode, vers le jeu de caractères de sortie lorsque la méthode @code{Charset.convert()} est appelée. La valeur par défaut est de sortir dans le même jeu de caractères que l'entrée.

`input_charset' et `output_charset' doivent avoir des entrées de codec Unicode dans la table de correspondances du jeu de caractères au codec du module ; utilisez @ref{35a3,,add_codec()} pour ajouter des codecs que le module ne connaît pas. Voir la documentation du module @ref{1b,,codecs} pour plus d'informations.

Le registre de jeux de caractères global est conservé dans le dictionnaire global du module @code{CHARSETS}.
@end deffn

@geindex add_alias() (dans le module email.charset)
@anchor{library/email charset email charset add_alias}@anchor{35a4}
@deffn {Fonction} email.charset.add_alias (alias, canonical)

Ajoute un alias de jeu de caractères. `alias' est le nom d'alias, par ex. @code{latin-1}. `canonical' est le nom canonique du jeu de caractères, par ex. @code{iso-8859-1}.

Le registre global des alias du jeu de caractères est conservé dans le dictionnaire global du module @code{ALIASES}.
@end deffn

@geindex add_codec() (dans le module email.charset)
@anchor{library/email charset email charset add_codec}@anchor{35a3}
@deffn {Fonction} email.charset.add_codec (charset, codecname)

Ajoute un codec qui fait correspondre les caractères du jeu de caractères donné vers et depuis Unicode.

`charset' est le nom canonique d'un jeu de caractères. `codecname' est le nom d'un codec Python (c.-à-d. une valeur valable comme second argument de la méthode @ref{8c2,,encode()} de @ref{435,,str}).
@end deffn

@node email encoders Encoders,email utils Miscellaneous utilities,email charset Representing character sets,email --- An email and MIME handling package
@anchor{library/email encoders doc}@anchor{35a5}@anchor{library/email encoders email-encoders-encoders}@anchor{35a6}@anchor{library/email encoders module-email encoders}@anchor{3e}
@subsubsection @code{email.encoders}: Encoders


@geindex module; email.encoders

`Code source :' Lib/email/encoders.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/encoders.py}


__________________________________________________________________


Ce module fait partie du code patrimonial (@code{Compat32}) de l'API mail. Dans la nouvelle API la fonctionnalité est fournie par le paramètre `cte' de la méthode @ref{1836,,set_content()}.

Ce module est obsolète en Python 3. Il n'est pas de besoin d'appeler explicitement les fonctions définies ici puisque la classe @ref{de6,,MIMEText} ajuste le type de contenu et l'entête CTE à l'aide des paramètres `_subtype' et `_charset' de son constructeur.

Le texte restant de cette section est la documentation originale de ce module.

Au moment de la création d'objets @ref{279,,Message} à la main, il est souvent nécessaire d'encoder les charges utiles pour le transport à travers des serveurs mail conformes. C'est particulièrement vrai pour les messages de type @code{image/*} et @code{text/*} contenant des données binaires.

The @ref{3b,,email} package provides some convenient encoders in its
@ref{3e,,encoders} module.  These encoders are actually used by the
@ref{3589,,MIMEAudio} and @ref{3528,,MIMEImage}
class constructors to provide default encodings.  All encoder functions take
exactly one argument, the message object to encode.  They usually extract the
payload, encode it, and reset the payload to this newly encoded value.  They
should also set the @code{Content-Transfer-Encoding} header as appropriate.

À noter que ces fonctions n'ont pas de sens dans le cadre d'un message en plusieurs parties. Elles doivent à la place être appliquées aux sous-parties individuelles, et lèvent @ref{522,,TypeError} si on leur passe un message en plusieurs parties.

Voici les fonctions d'encodages fournies :

@geindex encode_quopri() (dans le module email.encoders)
@anchor{library/email encoders email encoders encode_quopri}@anchor{35a7}
@deffn {Fonction} email.encoders.encode_quopri (msg)

Encode la charge utile au format Quoted-Printable, et assigne @code{quoted-printable} @footnote{
À noter que l'encodage avec @ref{35a7,,encode_quopri()} encode également tous les caractères tabulation et espace.
} à l'en-tête @code{Content-Transfer-Encoding}. C'est un bon encodage à utiliser quand la majorité de la charge utile contient essentiellement des données imprimables, à l'exceptions de quelques caractères.
@end deffn

@geindex encode_base64() (dans le module email.encoders)
@anchor{library/email encoders email encoders encode_base64}@anchor{35a8}
@deffn {Fonction} email.encoders.encode_base64 (msg)

Encode la charge utile au format `base64', et assigne @code{base64} à l'en-tête @code{Content-Transfer-Encoding}. C'est un bon encodage à utiliser quand la majorité de la charge utile est non imprimable puisque c'est une forme plus compacte que `quoted-printable'.
@end deffn

@geindex encode_7or8bit() (dans le module email.encoders)
@anchor{library/email encoders email encoders encode_7or8bit}@anchor{35a9}
@deffn {Fonction} email.encoders.encode_7or8bit (msg)

Ceci ne modifie pas effectivement la charge utile du message, mais va bien en revanche assigner la valeur @code{7bit} ou @code{8bit} à l'en-tête @code{Content-Transfer-Encoding} selon la nature de la charge utile.
@end deffn

@geindex encode_noop() (dans le module email.encoders)
@anchor{library/email encoders email encoders encode_noop}@anchor{35aa}
@deffn {Fonction} email.encoders.encode_noop (msg)

Ceci ne fait rien; et ne va même pas changer la valeur de l'en-tête @code{Content-Transfer-Encoding}.
@end deffn

@subsubheading Notes


@node email utils Miscellaneous utilities,email iterators Iterators,email encoders Encoders,email --- An email and MIME handling package
@anchor{library/email utils doc}@anchor{35ab}@anchor{library/email utils email-utils-miscellaneous-utilities}@anchor{35ac}@anchor{library/email utils module-email utils}@anchor{50}
@subsubsection @code{email.utils}: Miscellaneous utilities


@geindex module; email.utils

`Code source :' Lib/email/utils.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/utils.py}


__________________________________________________________________


Il y a quelques utilitaires utiles fournis dans le module @ref{50,,email.utils} :

@geindex localtime() (dans le module email.utils)
@anchor{library/email utils email utils localtime}@anchor{2c2}
@deffn {Fonction} email.utils.localtime (dt=None)

Return local time as an aware datetime object.  If called without
arguments, return current time.  Otherwise `dt' argument should be a
@ref{1c7,,datetime} instance, and it is converted to the local time
zone according to the system time zone database.  If `dt' is naive (that
is, @code{dt.tzinfo} is @code{None}), it is assumed to be in local time.  The
`isdst' parameter is ignored.


Ajouté dans la version 3.3.



Deprecated since version 3.12, will be removed in version 3.14: The `isdst' parameter.

@end deffn

@geindex make_msgid() (dans le module email.utils)
@anchor{library/email utils email utils make_msgid}@anchor{35ad}
@deffn {Fonction} email.utils.make_msgid (idstring=None, domain=None)

Renvoie une chaîne adaptée à un en-tête  @code{Message-ID} compatible 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}. `idstring', s'il est fourni, est une chaîne utilisée pour renforcer l'unicité de l'identifiant du message. Le `domain' facultatif, s'il est fourni, fournit la partie du `msgid' après le '@@'. La valeur par défaut est le nom d'hôte local. Il n'est normalement pas nécessaire de remplacer cette valeur par défaut, mais cela peut être utile dans certains cas, comme la construction d'un système distribué qui utilise un nom de domaine cohérent sur plusieurs hôtes.


Modifié dans la version 3.2: ajout du mot-clé `domaine'.

@end deffn

Les fonctions restantes font partie de l'ancienne API de messagerie (@code{Compat32}). Il n'est pas nécessaire de les utiliser directement avec la nouvelle API, car l'analyse et le formatage qu'elles fournissent sont effectués automatiquement par le mécanisme d'analyse d'en-tête de la nouvelle API.

@geindex quote() (dans le module email.utils)
@anchor{library/email utils email utils quote}@anchor{35ae}
@deffn {Fonction} email.utils.quote (str)

Renvoie une nouvelle chaîne avec les barres obliques inverses (`backslash') dans `str' remplacées par deux barres obliques inverses et les guillemets doubles remplacés par des guillemets doubles échappés par une barre oblique inverse.
@end deffn

@geindex unquote() (dans le module email.utils)
@anchor{library/email utils email utils unquote}@anchor{34d0}
@deffn {Fonction} email.utils.unquote (str)

Renvoie une nouvelle chaîne qui est une version `sans guillemets' de `str'. Si `str' se termine et commence par des guillemets doubles, ils sont supprimés. De même, si `str' est encadrée par des chevrons mathématiques, ils sont supprimés.
@end deffn

@geindex parseaddr() (dans le module email.utils)
@anchor{library/email utils email utils parseaddr}@anchor{1df}
@deffn {Fonction} email.utils.parseaddr (address, *, strict=True)

Analyse l'adresse – qui devrait être la valeur d'un champ contenant une adresse tel que @code{To} ou @code{Cc} – dans ses parties constituantes `realname' et `email address'. Renvoie un `n'-uplet de cette information, sauf si l'analyse échoue, alors un couple @code{('@w{'}, '@w{'})} est renvoyé.

If `strict' is true, use a strict parser which rejects malformed inputs.


Modifié dans la version 3.13: Add `strict' optional parameter and reject malformed inputs by default.

@end deffn

@geindex formataddr() (dans le module email.utils)
@anchor{library/email utils email utils formataddr}@anchor{1179}
@deffn {Fonction} email.utils.formataddr (pair, charset='utf-8')

L'inverse de @ref{1df,,parseaddr()}, elle prend un couple de la forme @code{(realname, email_address)} et renvoie la valeur de chaîne appropriée pour un en-tête @code{To} ou @code{Cc}. Si le premier élément de `pair' s'évalue à faux, alors le deuxième élément est renvoyé sans modification.

Le `charset' optionnel est le jeu de caractères qui est utilisé dans l'encodage 
@geindex RFC; RFC 2047
RFC 2047@footnote{https://datatracker.ietf.org/doc/html/rfc2047.html} du @code{realname} si le @code{realname} contient des caractères non-ASCII. Cela peut être une instance de @ref{435,,str} ou un @ref{de7,,Charset}. La valeur par défaut est @code{utf-8}.


Modifié dans la version 3.3: ajout de l'option `charset'.

@end deffn

@geindex getaddresses() (dans le module email.utils)
@anchor{library/email utils email utils getaddresses}@anchor{1de}
@deffn {Fonction} email.utils.getaddresses (fieldvalues, *, strict=True)

This method returns a list of 2-tuples of the form returned by @code{parseaddr()}.
`fieldvalues' is a sequence of header field values as might be returned by
@ref{3569,,Message.get_all}.

If `strict' is true, use a strict parser which rejects malformed inputs.

Here's a simple example that gets all the recipients of a message:

@example
from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
@end example


Modifié dans la version 3.13: Add `strict' optional parameter and reject malformed inputs by default.

@end deffn

@geindex parsedate() (dans le module email.utils)
@anchor{library/email utils email utils parsedate}@anchor{35af}
@deffn {Fonction} email.utils.parsedate (date)

Tente d'analyser une date selon les règles de la 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}. Cependant, certains expéditeurs ne suivent pas ce format comme spécifié, donc @ref{35af,,parsedate()} fait son possible dans de tels cas. `date' est une chaîne contenant une date 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}, telle que @code{"Mon, 20 Nov 1995 19:12:08 -0500"}. Si elle réussit à analyser la date, @ref{35af,,parsedate()} renvoie un 9-uplet qui peut être passé directement à @ref{11c5,,time.mktime()} ; sinon @code{None} est renvoyé. Notez que les indices 6, 7 et 8 du `n'-uplet résultat ne sont pas utilisables.
@end deffn

@geindex parsedate_tz() (dans le module email.utils)
@anchor{library/email utils email utils parsedate_tz}@anchor{180c}
@deffn {Fonction} email.utils.parsedate_tz (date)

Effectue la même fonction que @ref{35af,,parsedate()}, mais renvoie soit @code{None} ou un 10-uplet ; les 9 premiers éléments constituent un `n'-uplet qui peut être passé directement à @ref{11c5,,time.mktime()}, et le dixième est le décalage du fuseau horaire de la date par rapport à UTC (qui est le terme officiel pour `Greenwich Mean Time') @footnote{
Notez que le signe du décalage horaire est l'opposé du signe de la variable @code{time.timezone} pour le même fuseau horaire ; cette dernière variable suit la norme POSIX tandis que ce module suit la 
@geindex RFC; RFC 2822
@uref{https://datatracker.ietf.org/doc/html/rfc2822.html,RFC 2822}.
}. Si la chaîne d'entrée n'a pas de fuseau horaire, le dernier élément du `n'-uplet renvoyé est @code{0}, qui représente l'UTC. Notez que les indices 6, 7 et 8 du `n'-uplet résultat ne sont pas utilisables.
@end deffn

@geindex parsedate_to_datetime() (dans le module email.utils)
@anchor{library/email utils email utils parsedate_to_datetime}@anchor{10a0}
@deffn {Fonction} email.utils.parsedate_to_datetime (date)

L'inverse de @ref{109f,,format_datetime()}. Effectue la même fonction que @ref{35af,,parsedate()} mais, en cas de succès, renvoie un @ref{1c7,,datetime} ; sinon une @code{ValueError} est levée si `date' contient une valeur invalide telle qu'une heure supérieure à 23 ou un décalage de fuseau horaire non compris entre −24 et 24 heures. Si la date d'entrée a un fuseau horaire de @code{-0000}, le @code{datetime} sera un @code{datetime} naïf, et si la date est conforme aux RFC, elle représentera une heure en UTC mais sans indication du fuseau horaire source réel du message d'où provient la date. Si la date d'entrée a un autre décalage de fuseau horaire valide, le @code{datetime} sera un @code{datetime} avisé avec le @ref{10a1,,timezone} @ref{5c8,,tzinfo} adéquat.


Ajouté dans la version 3.3.

@end deffn

@geindex mktime_tz() (dans le module email.utils)
@anchor{library/email utils email utils mktime_tz}@anchor{35b0}
@deffn {Fonction} email.utils.mktime_tz (tuple)

Transforme un 10-uplet renvoyé par @ref{180c,,parsedate_tz()} en un horodatage UTC (en secondes depuis `Epoch'). Si l'élément de fuseau horaire dans le `n'-uplet est @code{None}, elle considère que l'heure est locale.
@end deffn

@geindex formatdate() (dans le module email.utils)
@anchor{library/email utils email utils formatdate}@anchor{141e}
@deffn {Fonction} email.utils.formatdate (timeval=None, localtime=False, usegmt=False)

Renvoie une chaîne de date conforme à la 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}, par exemple :

@example
Fri, 09 Nov 2001 01:08:47 -0000
@end example

Optional `timeval' if given is a floating-point time value as accepted by
@ref{119d,,time.gmtime()} and @ref{14af,,time.localtime()}, otherwise the current time is
used.

L'option `localtime' est un indicateur qui, lorsqu'il est @code{True}, interprète `timeval' et renvoie une date relative au fuseau horaire local au lieu de UTC, en tenant correctement compte de l'heure d'été. La valeur par défaut est @code{False}, ce qui signifie que l'UTC est utilisée.

L'option `usegmt' est un indicateur qui, lorsqu'il est @code{True}, affiche une chaîne de date avec le fuseau horaire sous la forme de la chaîne ASCII @code{GMT}, plutôt qu'un @code{-0000} numérique. C'est nécessaire pour certains protocoles (tels que HTTP). Cela ne s'applique que lorsque `localtime' est @code{False}. La valeur par défaut est @code{False}.
@end deffn

@geindex format_datetime() (dans le module email.utils)
@anchor{library/email utils email utils format_datetime}@anchor{109f}
@deffn {Fonction} email.utils.format_datetime (dt, usegmt=False)

Comme @code{formatdate}, mais l'entrée est une instance @ref{30,,datetime}. S'il s'agit d'un groupe date-heure naïf, il est considéré être « UTC sans information sur le fuseau horaire source », et le @code{-0000} conventionnel est utilisé pour le fuseau horaire. S'il s'agit d'un @code{datetime} avisé, alors le décalage numérique du fuseau horaire est utilisé. S'il s'agit d'un groupe date-heure avisé avec un décalage de fuseau horaire de zéro, alors `usegmt' peut être défini sur @code{True}, la chaîne @code{GMT} est alors utilisée à la place du décalage numérique du fuseau horaire. Cela fournit un moyen de générer des en-têtes de date HTTP conformes aux normes.


Ajouté dans la version 3.3.

@end deffn

@geindex decode_rfc2231() (dans le module email.utils)
@anchor{library/email utils email utils decode_rfc2231}@anchor{35b1}
@deffn {Fonction} email.utils.decode_rfc2231 (s)

Décode la chaîne `s' selon la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}.
@end deffn

@geindex encode_rfc2231() (dans le module email.utils)
@anchor{library/email utils email utils encode_rfc2231}@anchor{35b2}
@deffn {Fonction} email.utils.encode_rfc2231 (s, charset=None, language=None)

Encode la chaîne `s' selon la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. `charset' et `language', s'ils sont fournis, indiquent le jeu de caractères et le nom de la langue à utiliser. Si aucun n'est donné, `s' est renvoyé telle quelle. Si `charset' est donné mais que `language' ne l'est pas, la chaîne est encodée en utilisant la chaîne vide pour `language'.
@end deffn

@geindex collapse_rfc2231_value() (dans le module email.utils)
@anchor{library/email utils email utils collapse_rfc2231_value}@anchor{3578}
@deffn {Fonction} email.utils.collapse_rfc2231_value (value, errors='replace', fallback_charset='us-ascii')

Lorsqu'un paramètre d'en-tête est encodé au format 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}, @ref{3577,,Message.get_param} peut renvoyer un triplet contenant le jeu de caractères, la langue et la valeur. @ref{3578,,collapse_rfc2231_value()} transforme cela en une chaîne Unicode. `errors' (facultatif) est passé à l'argument `errors' de la méthode @ref{8c2,,encode()} de @ref{435,,str} ; sa valeur par défaut est @code{'replace'}. `fallback_charset' (facultatif) spécifie le jeu de caractères à utiliser si celui de l'en-tête 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html} n'est pas connu de Python ; sa valeur par défaut est @code{'us-ascii'}.

Pour plus de commodité, si la `valeur' transmise à @ref{3578,,collapse_rfc2231_value()} n'est pas un `n'-uplet, ce doit être une chaîne et elle est renvoyée sans guillemets.
@end deffn

@geindex decode_params() (dans le module email.utils)
@anchor{library/email utils email utils decode_params}@anchor{35b3}
@deffn {Fonction} email.utils.decode_params (params)

Décode la liste des paramètres selon la 
@geindex RFC; RFC 2231
RFC 2231@footnote{https://datatracker.ietf.org/doc/html/rfc2231.html}. `params' est une séquence de couples contenant des éléments de la forme @code{(content-type, string-value)}.
@end deffn

@subsubheading Notes


@node email iterators Iterators,,email utils Miscellaneous utilities,email --- An email and MIME handling package
@anchor{library/email iterators doc}@anchor{35b4}@anchor{library/email iterators email-iterators-iterators}@anchor{35b5}@anchor{library/email iterators module-email iterators}@anchor{43}
@subsubsection @code{email.iterators}: Iterators


@geindex module; email.iterators

`Code source :' Lib/email/iterators.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/email/iterators.py}


__________________________________________________________________


Itérer sur l'arborescence d'un objet message est plutôt simple avec la méthode @ref{3580,,Message.walk}. Le module @ref{43,,email.iterators} fournit des fonctionnalités d'itérations de plus haut niveau sur les arbres d'objets messages.

@geindex body_line_iterator() (dans le module email.iterators)
@anchor{library/email iterators email iterators body_line_iterator}@anchor{35b6}
@deffn {Fonction} email.iterators.body_line_iterator (msg, decode=False)

Cette fonction permet d'itérer sur tous les contenus de tous les éléments de `msg', en retournant les contenus sous forme de chaînes de caractères ligne par ligne. Il saute les entêtes des sous éléments, et tous les sous éléments dont le contenu n'est pas une chaîne de caractères Python. C'est en quelque sorte équivalent à une lecture plate d'une représentation textuelle du message à partir d'un fichier en utilisant @ref{1c4b,,readline()}, et en sautant toutes les entêtes intermédiaires.

Le paramètre optionnel `decode' est transmis à la méthode @ref{11aa,,Message.get_payload}.
@end deffn

@geindex typed_subpart_iterator() (dans le module email.iterators)
@anchor{library/email iterators email iterators typed_subpart_iterator}@anchor{35b7}
@deffn {Fonction} email.iterators.typed_subpart_iterator (msg, maintype='text', subtype=None)

Cette fonction permet d'itérer sur tous les sous éléments de `msg', en retournant seulement les sous éléments qui correspondent au type MIME spécifié par `maintype' et `subtype'.

Notez que le paramètre `subtype' est optionnel ; s'il n'est pas présent, alors le type MIME du sous élément est seulement composé du type principal. `maintype' est également optionnel ; sa valeur par défaut est @code{text}.

En conséquence, par défaut, @ref{35b7,,typed_subpart_iterator()} retourne chaque sous élément qui a un type MIME de type @code{text/*}.
@end deffn

La fonction suivante a été ajouté en tant qu'un outil de débogage. Elle `ne devrait pas' être considérée comme une interface publique supportée pour ce paquet.

@geindex _structure() (dans le module email.iterators)
@anchor{library/email iterators email iterators _structure}@anchor{35b8}
@deffn {Fonction} email.iterators._structure (msg, fp=None, level=0, include_default=False)

Affiche une représentation indentée des types de contenu de la structure de l'objet message. Par exemple :

@c import email
@c from email.iterators import _structure
@c somefile = open('../Lib/test/test_email/data/msg_02.txt')

@example
>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
    text/plain
    text/plain
    multipart/digest
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
        message/rfc822
            text/plain
    text/plain
@end example

@c somefile.close()

Le paramètre optionnel `fp' est un objet fichier-compatible dans lequel on peut écrire le flux de sortie. Il doit être approprié pour la fonction de Python @ref{f60,,print()}. `level' est utilisé en interne. `include_default', si vrai, affiche aussi le type par défaut.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{c9,,smtplib}

Client SMTP (`Simple Mail Transport Protocol')

@item Module @ref{ab,,poplib}

Client POP (`Post Office Protocol')

@item Module @ref{73,,imaplib}

Client IMAP (`Internet Message Access Protocol')

@item Module @ref{8a,,mailbox}

Outils pour créer, lire et gérer des messages regroupés sur disque en utilisant des formats standards variés.
@end table


@node json --- JSON encoder and decoder,mailbox --- Manipulate mailboxes in various formats,email --- An email and MIME handling package,Traitement des données provenant d'Internet
@anchor{library/json doc}@anchor{35b9}@anchor{library/json json-json-encoder-and-decoder}@anchor{35ba}@anchor{library/json module-json}@anchor{81}
@subsection @code{json} --- JSON encoder and decoder


@geindex module; json

`Code source :' Lib/json/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/json/__init__.py}


__________________________________________________________________


JSON (JavaScript Object Notation)@footnote{https://json.org}, specified by
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html} (which obsoletes 
@geindex RFC; RFC 4627
RFC 4627@footnote{https://datatracker.ietf.org/doc/html/rfc4627.html}) and by
ECMA-404@footnote{https://ecma-international.org/publications-and-standards/standards/ecma-404/},
is a lightweight data interchange format inspired by
JavaScript@footnote{https://en.wikipedia.org/wiki/JavaScript} object literal syntax
(although it is not a strict subset of JavaScript @footnote{
Comme noté dans @uref{https://www.rfc-editor.org/errata_search.php?rfc=7159,l'errata de la RFC 7159}, JSON autorise les caractères littéraux U+2028 (`LINE SEPARATOR') et U+2029 (`PARAGRAPH SEPARATOR') dans les chaînes de caractères, alors que Javascript (selon le standard ECMAScript édition 5.1) ne le permet pas.
} ).

@cartouche
@quotation Avertissement 
Be cautious when parsing JSON data from untrusted sources. A malicious
JSON string may cause the decoder to consume considerable CPU and memory
resources. Limiting the size of data to be parsed is recommended.
@end quotation
@end cartouche

@ref{81,,json} fournit une API familière aux utilisateurs des modules @ref{8c,,marshal} et @ref{a5,,pickle} de la bibliothèque standard.

Encodage de quelques objets de base Python :

@example
>>> import json
>>> json.dumps(['foo', @{'bar': ('baz', None, 1.0, 2)@}])
'["foo", @{"bar": ["baz", null, 1.0, 2]@}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps(@{"c": 0, "b": 0, "a": 0@}, sort_keys=True))
@{"a": 0, "b": 0, "c": 0@}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'
@end example

Encodage compact :

@example
>>> import json
>>> json.dumps([1, 2, 3, @{'4': 5, '6': 7@}], separators=(',', ':'))
'[1,2,3,@{"4":5,"6":7@}]'
@end example

Affichage plus lisible :

@example
>>> import json
>>> print(json.dumps(@{'6': 7, '4': 5@}, sort_keys=True, indent=4))
@{
    "4": 5,
    "6": 7
@}
@end example

Specializing JSON object encoding:

@example
>>> import json
>>> def custom_json(obj):
...     if isinstance(obj, complex):
...         return @{'__complex__': True, 'real': obj.real, 'imag': obj.imag@}
...     raise TypeError(f'Cannot serialize object of @{type(obj)@}')
...
>>> json.dumps(1 + 2j, default=custom_json)
'@{"__complex__": true, "real": 1.0, "imag": 2.0@}'
@end example

Décodage JSON :

@example
>>> import json
>>> json.loads('["foo", @{"bar":["baz", null, 1.0, 2]@}]')
['foo', @{'bar': ['baz', None, 1.0, 2]@}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['streaming API']
@end example

Spécialisation du décodage JSON pour un objet :

@example
>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('@{"__complex__": true, "real": 1, "imag": 2@}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')
@end example

Extension de la classe @ref{d34,,JSONEncoder} :

@example
>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         # Let the base class default method raise the TypeError
...         return super().default(obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[2.0', ', 1.0', ']']
@end example

Utilisation du module @ref{82,,json.tool} depuis l'invite de commandes pour valider un flux et l'afficher lisiblement :

@example
$ echo '@{"json":"obj"@}' | python -m json.tool
@{
    "json": "obj"
@}
$ echo '@{1.2:3.4@}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
@end example

Voir @ref{35bb,,Interface en ligne de commande} pour une documentation détaillée.

@cartouche
@quotation Note 
JSON is a subset of YAML@footnote{https://yaml.org/} 1.2.  The JSON produced by
this module's default settings (in particular, the default `separators'
value) is also a subset of YAML 1.0 and 1.1.  This module can thus also be
used as a YAML serializer.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Les encodeurs et décodeurs de ce module conservent l'ordre d'entrée et de sortie par défaut. L'ordre n'est perdu que si les conteneurs sous-jacents ne sont pas ordonnés.
@end quotation
@end cartouche

@menu
* Utilisation de base:: 
* Encodeurs et décodeurs:: 
* Exceptions: Exceptions<17>. 
* Conformité au standard et Interopérabilité:: 
* Interface en ligne de commande: Interface en ligne de commande<4>. 

@end menu

@node Utilisation de base,Encodeurs et décodeurs,,json --- JSON encoder and decoder
@anchor{library/json basic-usage}@anchor{35bc}
@subsubsection Utilisation de base


@geindex dump() (dans le module json)
@anchor{library/json json dump}@anchor{d32}
@deffn {Fonction} json.dump (obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Serialize `obj' as a JSON formatted stream to `fp' (a @code{.write()}-supporting
@ref{250d,,file-like object}) using this @ref{35bd,,Python-to-JSON conversion table}.

@cartouche
@quotation Note 
À l'inverse de @ref{a5,,pickle} et @ref{8c,,marshal}, JSON n'est pas un protocole par trames, donc essayer de sérialiser plusieurs objets par des appels répétés à @ref{d32,,dump()} en utilisant le même `fp' résulte en un fichier JSON invalide.
@end quotation
@end cartouche

@*Paramètres: 

@itemize *

@item 
@code{obj} (@ref{a7a,,object}) -- The Python object to be serialized.

@item 
@code{fp} (@ref{250d,,file-like object}) -- The file-like object `obj' will be serialized to.
The @code{json} module always produces @ref{435,,str} objects,
not @ref{1bd,,bytes} objects,
therefore @code{fp.write()} must support @ref{435,,str} input.

@item 
@code{skipkeys} (@ref{451,,bool}) -- If @code{True}, keys that are not of a basic type
(@ref{435,,str}, @ref{254,,int}, @ref{2eb,,float}, @ref{451,,bool}, @code{None})
will be skipped instead of raising a @ref{522,,TypeError}.
Default @code{False}.

@item 
@code{ensure_ascii} (@ref{451,,bool}) -- If @code{True} (the default), the output is guaranteed to
have all incoming non-ASCII characters escaped.
If @code{False}, these characters will be outputted as-is.

@item 
@code{check_circular} (@ref{451,,bool}) -- If @code{False}, the circular reference check for container types is skipped
and a circular reference will result in a @ref{d59,,RecursionError} (or worse).
Default @code{True}.

@item 
@code{allow_nan} (@ref{451,,bool}) -- If @code{False}, serialization of out-of-range @ref{2eb,,float} values
(@code{nan}, @code{inf}, @code{-inf}) will result in a @ref{1ff,,ValueError},
in strict compliance with the JSON specification.
If @code{True} (the default), their JavaScript equivalents
(@code{NaN}, @code{Infinity}, @code{-Infinity}) are used.

@item 
@code{cls} (a @ref{d34,,JSONEncoder} subclass) -- If set, a custom JSON encoder with the
@ref{35be,,default()} method overridden,
for serializing into custom datatypes.
If @code{None} (the default), @code{JSONEncoder} is used.

@item 
@code{indent} (@ref{254,,int}@code{ | }@ref{435,,str}@code{ | }@code{None}) -- If a positive integer or string, JSON array elements and
object members will be pretty-printed with that indent level.
A positive integer indents that many spaces per level;
a string (such as @code{"\t"}) is used to indent each level.
If zero, negative, or @code{""} (the empty string),
only newlines are inserted.
If @code{None} (the default), the most compact representation is used.

@item 
@code{separators} (@ref{366,,tuple}@code{ | }@code{None}) -- A two-tuple: @code{(item_separator, key_separator)}.
If @code{None} (the default), `separators' defaults to
@code{(', ', ': ')} if `indent' is @code{None},
and @code{(',', ': ')} otherwise.
For the most compact JSON,
specify @code{(',', ':')} to eliminate whitespace.

@item 
@code{default} (@ref{2870,,callable} | None) -- A function that is called for objects that can't otherwise be serialized.
It should return a JSON encodable version of the object
or raise a @ref{522,,TypeError}.
If @code{None} (the default), @code{TypeError} is raised.

@item 
@code{sort_keys} (@ref{451,,bool}) -- If @code{True}, dictionaries will be outputted sorted by key.
Default @code{False}.
@end itemize



Modifié dans la version 3.2: Autorise les chaînes en plus des nombres entiers pour `indent'.



Modifié dans la version 3.4: Utilise @code{(',', ': ')} par défaut si `indent' n'est pas @code{None}.



Modifié dans la version 3.6: tous les paramètres optionnels sont maintenant des @ref{2a2,,keyword-only}.

@end deffn

@geindex dumps() (dans le module json)
@anchor{library/json json dumps}@anchor{d33}
@deffn {Fonction} json.dumps (obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Sérialise `obj' en une @ref{435,,str} formatée en JSON, en utilisant cette @ref{35bd,,table de conversion}. Les arguments ont la même signification que ceux de @ref{d32,,dump()}.

@cartouche
@quotation Note 
Les clés dans les couples JSON clé-valeur sont toujours de type @ref{435,,str}. Quand un dictionnaire est converti en JSON, toutes les clés du dictionnaire sont transformées en chaînes de caractères. Ce qui fait que si un dictionnaire est converti en JSON et reconverti en dictionnaire, le résultat peut ne pas être égal à l'original. Ainsi, @code{loads(dumps(x)) != x} si x contient des clés qui ne sont pas des chaînes.
@end quotation
@end cartouche
@end deffn

@geindex load() (dans le module json)
@anchor{library/json json load}@anchor{ca2}
@deffn {Fonction} json.load (fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Déserialise `fp' (un @ref{1c14,,text file} ou un @ref{1c15,,binary file} supportant @code{.read()} et contenant un document JSON) vers un objet Python en utilisant cette @ref{35bf,,table de conversion}.

`object_hook' is an optional function that will be called with the result of
any object literal decoded (a @ref{253,,dict}).  The return value of
`object_hook' will be used instead of the @ref{253,,dict}.  This feature can
be used to implement custom decoders (e.g. JSON-RPC@footnote{https://www.jsonrpc.org} class hinting).

`object_pairs_hook' is an optional function that will be called with the
result of any object literal decoded with an ordered list of pairs.  The
return value of `object_pairs_hook' will be used instead of the
@ref{253,,dict}.  This feature can be used to implement custom decoders.  If
`object_hook' is also defined, the `object_pairs_hook' takes priority.


Modifié dans la version 3.1: ajout du support de `object_pairs_hook'.


`parse_float' is an optional function that will be called with the string of
every JSON float to be decoded.  By default, this is equivalent to
@code{float(num_str)}.  This can be used to use another datatype or parser for
JSON floats (e.g. @ref{29a,,decimal.Decimal}).

`parse_int' is an optional function that will be called with the string of
every JSON int to be decoded.  By default, this is equivalent to
@code{int(num_str)}.  This can be used to use another datatype or parser for
JSON integers (e.g. @ref{2eb,,float}).


Modifié dans la version 3.11: The default `parse_int' of @ref{254,,int()} now limits the maximum length of
the integer string via the interpreter's @ref{5df,,integer string conversion length limitation} to help avoid denial
of service attacks.


`parse_constant' is an optional function that will be called with one of the
following strings: @code{'-Infinity'}, @code{'Infinity'}, @code{'NaN'}.  This can be
used to raise an exception if invalid JSON numbers are encountered.


Modifié dans la version 3.1: `parse_constant' n'est plus appelée pour `null', `true' ou `false'.


Pour utiliser une sous-classe @ref{d35,,JSONDecoder} personnalisée, spécifiez-la avec l'argument nommé @code{cls} ; autrement, @ref{d35,,JSONDecoder} est utilisée.  Les arguments nommés additionnels sont passés au constructeur de cette classe.

Si les données à désérialiser ne sont pas un document JSON valide, une @ref{e0d,,JSONDecodeError} est levée.


Modifié dans la version 3.6: tous les paramètres optionnels sont maintenant des @ref{2a2,,keyword-only}.



Modifié dans la version 3.6: `fp' peut maintenant être un @code{binary file}. Son encodage doit être UTF-8, UTF-16 ou UTF-32.

@end deffn

@geindex loads() (dans le module json)
@anchor{library/json json loads}@anchor{942}
@deffn {Fonction} json.loads (s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Déserialise `s' (une instance de @ref{435,,str}, @ref{1bd,,bytes} ou @ref{528,,bytearray} contenant un document JSON) vers un objet Python en utilisant cette @ref{35bf,,table de conversion}.

Les autres arguments ont la même signification que dans @ref{ca2,,load()}.

Si les données à désérialiser ne sont pas un document JSON valide, une @ref{e0d,,JSONDecodeError} est levée.


Modifié dans la version 3.6: `s' peut maintenant être de type @ref{1bd,,bytes} ou @ref{528,,bytearray}. L'encodage d'entrée doit être UTF-8, UTF-16 ou UTF-32.



Modifié dans la version 3.9: suppression de l’argument nommé `encoding'.

@end deffn

@node Encodeurs et décodeurs,Exceptions<17>,Utilisation de base,json --- JSON encoder and decoder
@anchor{library/json encoders-and-decoders}@anchor{35c0}
@subsubsection Encodeurs et décodeurs


@geindex JSONDecoder (classe dans json)
@anchor{library/json json JSONDecoder}@anchor{d35}
@deffn {Classe} json.JSONDecoder (*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

Décodeur simple JSON.

Applique par défaut les conversions suivantes en décodant :
@anchor{library/json json-to-py-table}@anchor{35bf}

@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

JSON

@tab

Python

@item

objet

@tab

`dict'

@item

`array'

@tab

`list'

@item

`string'

@tab

`str'

@item

`number' (nombre entier)

@tab

`int'

@item

`number' (nombre réel)

@tab

`float'

@item

`true'

@tab

`True'

@item

`false'

@tab

`False'

@item

`null'

@tab

@code{None}

@end multitable


Les valeurs @code{NaN}, @code{Infinity} et @code{-Infinity} sont aussi comprises comme leurs valeurs @code{float} correspondantes, bien que ne faisant pas partie de la spécification JSON.

`object_hook' is an optional function that will be called with the result of
every JSON object decoded and its return value will be used in place of the
given @ref{253,,dict}.  This can be used to provide custom deserializations
(e.g. to support JSON-RPC@footnote{https://www.jsonrpc.org} class hinting).

`object_pairs_hook' is an optional function that will be called with the
result of every JSON object decoded with an ordered list of pairs.  The
return value of `object_pairs_hook' will be used instead of the
@ref{253,,dict}.  This feature can be used to implement custom decoders.  If
`object_hook' is also defined, the `object_pairs_hook' takes priority.


Modifié dans la version 3.1: ajout du support de `object_pairs_hook'.


`parse_float' is an optional function that will be called with the string of
every JSON float to be decoded.  By default, this is equivalent to
@code{float(num_str)}.  This can be used to use another datatype or parser for
JSON floats (e.g. @ref{29a,,decimal.Decimal}).

`parse_int' is an optional function that will be called with the string of
every JSON int to be decoded.  By default, this is equivalent to
@code{int(num_str)}.  This can be used to use another datatype or parser for
JSON integers (e.g. @ref{2eb,,float}).

`parse_constant' is an optional function that will be called with one of the
following strings: @code{'-Infinity'}, @code{'Infinity'}, @code{'NaN'}.  This can be
used to raise an exception if invalid JSON numbers are encountered.

Si `strict' vaut @code{False} (@code{True} par défaut), alors les caractères de contrôle sont autorisés à l'intérieur des chaînes.  Les caractères de contrôle dans ce contexte sont ceux dont les codes sont dans l'intervalle 0--31, incluant @code{'\t'} (tabulation), @code{'\n'}, @code{'\r'} et @code{'\0'}.

Si les données à désérialiser ne sont pas un document JSON valide, une @ref{e0d,,JSONDecodeError} est levée.


Modifié dans la version 3.6: Tous les paramètres sont maintenant des @ref{2a2,,keyword-only}.


@geindex decode() (méthode json.JSONDecoder)
@anchor{library/json json JSONDecoder decode}@anchor{35c1}
@deffn {Méthode} decode (s)

Renvoie la représentation Python de `s' (une instance @ref{435,,str} contenant un document JSON).

Une @ref{e0d,,JSONDecodeError} est levée si le document JSON donné n'est pas valide.
@end deffn

@geindex raw_decode() (méthode json.JSONDecoder)
@anchor{library/json json JSONDecoder raw_decode}@anchor{35c2}
@deffn {Méthode} raw_decode (s)

Décode en document JSON depuis `s' (une instance @ref{435,,str} débutant par un document JSON) et renvoie un `n'-uplet de 2 éléments contenant la représentation Python de l'objet et l'index dans `s' où le document se terminait.

Elle peut être utilisée pour décoder un document JSON depuis une chaîne qui peut contenir des données supplémentaires à la fin.
@end deffn
@end deffn

@geindex JSONEncoder (classe dans json)
@anchor{library/json json JSONEncoder}@anchor{d34}
@deffn {Classe} json.JSONEncoder (*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Encodeur JSON extensible pour les structures de données Python.

Prend en charge par défaut les objets et types suivants :
@anchor{library/json py-to-json-table}@anchor{35bd}

@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Python

@tab

JSON

@item

`dict'

@tab

objet

@item

`list', `tuple'

@tab

`array'

@item

`str'

@tab

`string'

@item

`int', `float', et `Enums' dérivées d'`int' ou de `float'

@tab

`number'

@item

`True'

@tab

`true'

@item

`False'

@tab

`false'

@item

@code{None}

@tab

`null'

@end multitable



Modifié dans la version 3.4: ajout de la prise en charge des classes `Enum' dérivées d'`int' ou de `float'.


To extend this to recognize other objects, subclass and implement a
@ref{35be,,default()} method with another method that returns a serializable object
for @code{o} if possible, otherwise it should call the superclass implementation
(to raise @ref{522,,TypeError}).

Si `skipkeys' vaut @code{False} (valeur par défaut), une @ref{522,,TypeError} est levée si la clé encodée n'est pas de type @ref{435,,str}, @ref{254,,int}, @ref{2eb,,float} ou @code{None}. Si `skipkeys' vaut @code{True}, ces éléments sont simplement ignorés.

Si `ensure_ascii' vaut @code{True} (valeur par défaut), les caractères non ASCII sont tous échappés à la sortie. Si `ensure_ascii' vaut @code{False}, ils sont écrits tels quels.

Si `check_circular' vaut @code{True} (valeur par défaut), une vérification a lieu sur les listes, dictionnaires et objets personnalisés, afin de détecter les références circulaires et éviter les récursions infinies (qui causeraient une @ref{d59,,RecursionError}). Autrement, la vérification n'a pas lieu.

Si `allow_nan' vaut @code{True} (valeur par défaut), alors @code{NaN}, @code{Infinity} et @code{-Infinity} sont encodés comme tels.  Ce comportement ne respecte pas la spécification JSON, mais est cohérent avec le majorité des encodeurs-décodeurs JavaScript.  Autrement, une @ref{1ff,,ValueError} est levée pour de telles valeurs.

Si `sort_keys' vaut @code{True} (@code{False} par défaut), alors les dictionnaires sont triés par clés en sortie ; cela est utile lors de tests de régression pour pouvoir comparer les sérialisations JSON au jour le jour.

Si `indent' est un nombre entier positif ou une chaîne de caractères, les éléments de tableaux et les membres d'objets JSON sont affichés élégamment avec ce niveau d'indentation. Un niveau d'indentation de 0, négatif, ou @code{""} n'insère que des retours à la ligne. @code{None} (la valeur par défaut) choisit la représentation la plus compacte. Utiliser un entier positif pour `indent' indente d'autant d'espaces par niveau. Si `indent' est une chaîne (telle que @code{"\t"}), cette chaîne est utilisée pour indenter à chaque niveau.


Modifié dans la version 3.2: Autorise les chaînes en plus des nombres entiers pour `indent'.


Si spécifié, `separators' doit être un `n'-uplet @code{(item_separator, key_separator)}.  Sa valeur par défaut est @code{(', ', ': ')} si `indent' est @code{None}, et @code{(',', ': ')} autrement.  Pour obtenir la représentation JSON la plus compacte possible, passez @code{(',', ':')} pour éliminer les espaces.


Modifié dans la version 3.4: Utilise @code{(',', ': ')} par défaut si `indent' n'est pas @code{None}.


Si spécifié, `default' doit être une fonction qui sera appelée pour les objets qui ne peuvent être sérialisés autrement. Elle doit renvoyer une représentation composée d'objets Python sérialisable en JSON ou lever une @ref{522,,TypeError}. Si non spécifié, une @ref{522,,TypeError} est levée.


Modifié dans la version 3.6: Tous les paramètres sont maintenant des @ref{2a2,,keyword-only}.


@geindex default() (méthode json.JSONEncoder)
@anchor{library/json json JSONEncoder default}@anchor{35be}
@deffn {Méthode} default (o)

Implémentez cette méthode dans une sous-classe afin qu'elle renvoie un objet sérialisable pour `o', ou appelle l'implémentation de base (qui lèvera une @ref{522,,TypeError}).

For example, to support arbitrary iterators, you could implement
@ref{35be,,default()} like this:

@example
def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Let the base class default method raise the TypeError
   return super().default(o)
@end example
@end deffn

@geindex encode() (méthode json.JSONEncoder)
@anchor{library/json json JSONEncoder encode}@anchor{35c3}
@deffn {Méthode} encode (o)

Renvoie une chaîne JSON représentant la structure de données Python `o'.  Par exemple :

@example
>>> json.JSONEncoder().encode(@{"foo": ["bar", "baz"]@})
'@{"foo": ["bar", "baz"]@}'
@end example
@end deffn

@geindex iterencode() (méthode json.JSONEncoder)
@anchor{library/json json JSONEncoder iterencode}@anchor{35c4}
@deffn {Méthode} iterencode (o)

Encode l'objet `o' donné, et produit chaque chaîne représentant l'objet selon disponibilité.  Par exemple :

@example
for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)
@end example
@end deffn
@end deffn

@node Exceptions<17>,Conformité au standard et Interopérabilité,Encodeurs et décodeurs,json --- JSON encoder and decoder
@anchor{library/json exceptions}@anchor{35c5}
@subsubsection Exceptions


@geindex JSONDecodeError
@anchor{library/json json JSONDecodeError}@anchor{e0d}
@deffn {Exception} json.JSONDecodeError (msg, doc, pos)

Sous-classe de @ref{1ff,,ValueError} avec les attributs additionnels suivants :

@geindex msg (attribut json.JSONDecodeError)
@anchor{library/json json JSONDecodeError msg}@anchor{35c6}
@deffn {Attribut} msg

Le message d'erreur non formaté.
@end deffn

@geindex doc (attribut json.JSONDecodeError)
@anchor{library/json json JSONDecodeError doc}@anchor{35c7}
@deffn {Attribut} doc

Le document JSON en cours de traitement.
@end deffn

@geindex pos (attribut json.JSONDecodeError)
@anchor{library/json json JSONDecodeError pos}@anchor{35c8}
@deffn {Attribut} pos

L'index de `doc' à partir duquel l'analyse a échoué.
@end deffn

@geindex lineno (attribut json.JSONDecodeError)
@anchor{library/json json JSONDecodeError lineno}@anchor{35c9}
@deffn {Attribut} lineno

La ligne correspondant à `pos'.
@end deffn

@geindex colno (attribut json.JSONDecodeError)
@anchor{library/json json JSONDecodeError colno}@anchor{35ca}
@deffn {Attribut} colno

La colonne correspondant à `pos'.
@end deffn


Ajouté dans la version 3.5.

@end deffn

@node Conformité au standard et Interopérabilité,Interface en ligne de commande<4>,Exceptions<17>,json --- JSON encoder and decoder
@anchor{library/json standard-compliance-and-interoperability}@anchor{35cb}
@subsubsection Conformité au standard et Interopérabilité


The JSON format is specified by 
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html} and by
ECMA-404@footnote{https://ecma-international.org/publications-and-standards/standards/ecma-404/}.
This section details this module's level of compliance with the RFC.
For simplicity, @ref{d34,,JSONEncoder} and @ref{d35,,JSONDecoder} subclasses, and
parameters other than those explicitly mentioned, are not considered.

Ce module ne se conforme pas strictement à la RFC, implémentant quelques extensions qui sont valides en JavaScript mais pas en JSON.  En particulier :


@itemize -

@item 
Les nombres infinis et `NaN' sont acceptés et retranscrits ;

@item 
Les noms répétés au sein d'un objet sont acceptés, seule la valeur du dernier couple nom-valeur est utilisée.
@end itemize

Comme la RFC permet aux analyseurs conformes d'accepter en entrée des textes non conformes, le désérialiseur de ce module avec ses paramètres par défaut est techniquement conforme à la RFC.

@menu
* Encodage des caractères:: 
* Valeurs numériques infinies et NaN:: 
* Noms répétés au sein d'un objet:: 
* Valeurs de plus haut niveau (hors objets ou tableaux): Valeurs de plus haut niveau hors objets ou tableaux. 
* Limitations de l'implémentation:: 

@end menu

@node Encodage des caractères,Valeurs numériques infinies et NaN,,Conformité au standard et Interopérabilité
@anchor{library/json character-encodings}@anchor{35cc}
@subsubsection Encodage des caractères


La RFC requiert que le JSON soit représenté en utilisant l'encodage UTF-8, UTF-16 ou UTF-32, avec UTF-8 recommandé par défaut pour une interopérabilité maximale.

Comme cela est permis par la RFC, bien que non requis, le sérialiseur du module active `ensure_ascii=True' par défaut, échappant ainsi la sortie de façon à ce que les chaînes résultants ne contiennent que des caractères ASCII.

Outre le paramètre `ensure_ascii', les conversions entre objets Python et @ref{435,,chaînes Unicode} de ce module sont strictement définies, et ne résolvent donc pas directement le problème de l'encodage des caractères.

La RFC interdit d'ajouter un octet marqueur d'ordre (`byte mark order' ou BOM) au début du texte JSON, et le sérialiseur de ce module n'ajoute pas de tel BOM. La RFC permet, mais ne requiert pas, que les désérialiseurs JSON ignorent ces BOM.  Le désérialiseur de ce module lève une @ref{1ff,,ValueError} quand un BOM est présent au début du fichier.

La RFC n'interdit pas explicitement les chaînes JSON contenant des séquences d'octets ne correspondant à aucun caractère Unicode valide (p. ex. les `surrogates' UTF-16 sans correspondance), mais précise que cela peut causer des problèmes d'interopérabilité. Par défaut, ce module accepte et retranscrit (quand présents dans la @ref{435,,str} originale) les `code points' de telles séquences.

@node Valeurs numériques infinies et NaN,Noms répétés au sein d'un objet,Encodage des caractères,Conformité au standard et Interopérabilité
@anchor{library/json infinite-and-nan-number-values}@anchor{35cd}
@subsubsection Valeurs numériques infinies et NaN


La RFC ne permet pas la représentation des nombres infinis ou des `NaN'. Néanmoins, par défaut, ce module accepte et retranscrit @code{Infinity}, @code{-Infinity} et @code{NaN} comme s'ils étaient des valeurs numériques littérales JSON valides :

@example
>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan
@end example

Dans le sérialiseur, le paramètre `allow_nan' peut être utilisé pour altérer ce comportement.  Dans le désérialiseur, le paramètre `parse_constant' peut être utilisé pour changer ce comportement.

@node Noms répétés au sein d'un objet,Valeurs de plus haut niveau hors objets ou tableaux,Valeurs numériques infinies et NaN,Conformité au standard et Interopérabilité
@anchor{library/json repeated-names-within-an-object}@anchor{35ce}
@subsubsection Noms répétés au sein d'un objet


La RFC précise que les noms au sein d'un objet JSON doivent être uniques, mais ne décrit pas comment les noms répétés doivent être gérés.  Par défaut, ce module ne lève pas d'exception ; à la place, il ignore tous les couples nom-valeur sauf le dernier pour un nom donné :

@example
>>> weird_json = '@{"x": 1, "x": 2, "x": 3@}'
>>> json.loads(weird_json)
@{'x': 3@}
@end example

Le paramètre `object_pairs_hook' peut être utilisé pour modifier ce comportement.

@node Valeurs de plus haut niveau hors objets ou tableaux,Limitations de l'implémentation,Noms répétés au sein d'un objet,Conformité au standard et Interopérabilité
@anchor{library/json top-level-non-object-non-array-values}@anchor{35cf}
@subsubsection Valeurs de plus haut niveau (hors objets ou tableaux)


L'ancienne version de JSON définie par l'obsolète 
@geindex RFC; RFC 4627
RFC 4627@footnote{https://datatracker.ietf.org/doc/html/rfc4627.html} demandait à ce que la valeur de plus haut niveau du texte JSON soit un objet ou un tableau JSON (@ref{253,,dict} ou @ref{5fc,,list} Python), et ne soit pas `null', un nombre, ou une chaîne de caractères.  La 
@geindex RFC; RFC 7159
RFC 7159@footnote{https://datatracker.ietf.org/doc/html/rfc7159.html} a supprimé cette restriction, jamais implémentée par ce module, que ce soit dans le sérialiseur ou le désérialiseur.

Cependant, pour une interopérabilité maximale, vous pourriez volontairement souhaiter adhérer à cette restriction.

@node Limitations de l'implémentation,,Valeurs de plus haut niveau hors objets ou tableaux,Conformité au standard et Interopérabilité
@anchor{library/json implementation-limitations}@anchor{35d0}
@subsubsection Limitations de l'implémentation


Certaines implémentations de désérialiseurs JSON peuvent avoir des limites sur :


@itemize *

@item 
la taille des textes JSON acceptés ;

@item 
le niveau maximum d'objets et tableaux JSON imbriqués ;

@item 
l'intervalle et la précision des nombres JSON ;

@item 
le contenu et la longueur maximale des chaînes JSON.
@end itemize

Ce module n'impose pas de telles limites si ce n'est celles inhérentes aux types de données Python ou à l'interpréteur.

Lors d'une sérialisation JSON, faites attention à ces limitations dans les applications qui utilisent votre JSON.  En particulier, il est courant pour les nombres JSON d'être désérialisés vers des nombres IEEE 754 à précision double, et donc sujets à l'intervalle et aux limitations sur la précision de cette représentation.  Cela est d'autant plus important lors de la sérialisation de grands @ref{254,,int} Python, ou d'instances de types numériques « exotiques » comme @ref{29a,,decimal.Decimal}.

@node Interface en ligne de commande<4>,,Conformité au standard et Interopérabilité,json --- JSON encoder and decoder
@anchor{library/json command-line-interface}@anchor{35d1}@anchor{library/json json-commandline}@anchor{35bb}@anchor{library/json module-json tool}@anchor{82}
@subsubsection Interface en ligne de commande


@geindex module; json.tool

`Code source :' Lib/json/tool.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/json/tool.py}


__________________________________________________________________


Le module @ref{82,,json.tool} fournit une simple interface en ligne de commande pour valider et réécrire élégamment des objets JSON.

If the optional @code{infile} and @code{outfile} arguments are not
specified, @ref{527,,sys.stdin} and @ref{ac4,,sys.stdout} will be used respectively:

@example
$ echo '@{"json": "obj"@}' | python -m json.tool
@{
    "json": "obj"
@}
$ echo '@{1.2:3.4@}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
@end example


Modifié dans la version 3.5: La sortie conserve maintenant l'ordre des données de l'entrée. Utilisez l'option @ref{35d2,,--sort-keys} pour sortir des dictionnaires triés alphabétiquement par clés.


@menu
* Options de la ligne de commande: Options de la ligne de commande<4>. 

@end menu

@node Options de la ligne de commande<4>,,,Interface en ligne de commande<4>
@anchor{library/json command-line-options}@anchor{35d3}
@subsubsection Options de la ligne de commande


@geindex option de ligne de commande json.tool; infile
@anchor{library/json cmdoption-json tool-arg-infile}@anchor{35d4}
@deffn {Option} infile

Le fichier JSON à valider ou réécrire élégamment :

@example
$ python -m json.tool mp_films.json
[
    @{
        "title": "And Now for Something Completely Different",
        "year": 1971
    @},
    @{
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    @}
]
@end example

If `infile' is not specified, read from @ref{527,,sys.stdin}.
@end deffn

@geindex option de ligne de commande json.tool; outfile
@anchor{library/json cmdoption-json tool-arg-outfile}@anchor{35d5}
@deffn {Option} outfile

Write the output of the `infile' to the given `outfile'. Otherwise, write it
to @ref{ac4,,sys.stdout}.
@end deffn

@geindex option de ligne de commande json.tool; --sort-keys
@anchor{library/json cmdoption-json tool-sort-keys}@anchor{35d2}
@deffn {Option} @w{-}@w{-}sort@w{-}keys

Trie alphabétiquement les dictionnaires par clés.


Ajouté dans la version 3.5.

@end deffn

@geindex option de ligne de commande json.tool; --no-ensure-ascii
@anchor{library/json cmdoption-json tool-no-ensure-ascii}@anchor{35d6}
@deffn {Option} @w{-}@w{-}no@w{-}ensure@w{-}ascii

Désactive l’échappement des caractères non ASCII, voir @ref{d33,,json.dumps()} pour plus d'informations.


Ajouté dans la version 3.9.

@end deffn

@geindex option de ligne de commande json.tool; --json-lines
@anchor{library/json cmdoption-json tool-json-lines}@anchor{35d7}
@deffn {Option} @w{-}@w{-}json@w{-}lines

Transforme chaque ligne d'entrée en un objet JSON individuel.


Ajouté dans la version 3.8.

@end deffn

@geindex option de ligne de commande json.tool; --indent
@geindex option de ligne de commande json.tool; --tab
@geindex option de ligne de commande json.tool; --no-indent
@geindex option de ligne de commande json.tool; --compact
@anchor{library/json cmdoption-json tool-indent}@anchor{35d8}@anchor{library/json cmdoption-json tool-tab}@anchor{35d9}@anchor{library/json cmdoption-json tool-no-indent}@anchor{35da}@anchor{library/json cmdoption-json tool-compact}@anchor{35db}
@deffn {Option} @w{-}@w{-}indent, @w{-}@w{-}tab, @w{-}@w{-}no@w{-}indent, @w{-}@w{-}compact

Options mutuellement exclusives de contrôle des espaces.


Ajouté dans la version 3.9.

@end deffn

@geindex option de ligne de commande json.tool; -h
@geindex option de ligne de commande json.tool; --help
@anchor{library/json cmdoption-json tool-h}@anchor{35dc}@anchor{library/json cmdoption-json tool-help}@anchor{35dd}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Affiche le message d'aide.
@end deffn

@subsubheading Notes


@node mailbox --- Manipulate mailboxes in various formats,mimetypes --- Map filenames to MIME types,json --- JSON encoder and decoder,Traitement des données provenant d'Internet
@anchor{library/mailbox doc}@anchor{35de}@anchor{library/mailbox mailbox-manipulate-mailboxes-in-various-formats}@anchor{35df}@anchor{library/mailbox module-mailbox}@anchor{8a}
@subsection @code{mailbox} --- Manipulate mailboxes in various formats


@geindex module; mailbox

`Code source :' Lib/mailbox.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/mailbox.py}


__________________________________________________________________


This module defines two classes, @ref{122b,,Mailbox} and @ref{122f,,Message}, for
accessing and manipulating on-disk mailboxes and the messages they contain.
@code{Mailbox} offers a dictionary-like mapping from keys to messages.
@code{Message} extends the @ref{44,,email.message} module's
@ref{279,,Message} class with format-specific state and behavior.
Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.


@subsubheading Voir aussi



@table @asis

@item Module @ref{3b,,email}

Représente et manipule des messages.
@end table


@menu
* Mailbox objects:: 
* Message objects:: 
* Exceptions: Exceptions<18>. 
* Exemples: Exemples<22>. 

@end menu

@node Mailbox objects,Message objects,,mailbox --- Manipulate mailboxes in various formats
@anchor{library/mailbox id1}@anchor{35e0}@anchor{library/mailbox mailbox-objects}@anchor{35e1}
@subsubsection @code{Mailbox} objects


@geindex Mailbox (classe dans mailbox)
@anchor{library/mailbox mailbox Mailbox}@anchor{122b}
@deffn {Classe} mailbox.Mailbox

Une boîte mail, qui peut être inspectée et modifiée.

The @code{Mailbox} class defines an interface and is not intended to be
instantiated.  Instead, format-specific subclasses should inherit from
@code{Mailbox} and your code should instantiate a particular subclass.

The @code{Mailbox} interface is dictionary-like, with small keys
corresponding to messages. Keys are issued by the @code{Mailbox} instance
with which they will be used and are only meaningful to that @code{Mailbox}
instance. A key continues to identify a message even if the corresponding
message is modified, such as by replacing it with another message.

Messages may be added to a @code{Mailbox} instance using the set-like
method @ref{122a,,add()} and removed using a @code{del} statement or the set-like
methods @ref{35e2,,remove()} and @ref{35e3,,discard()}.

@code{Mailbox} interface semantics differ from dictionary semantics in some
noteworthy ways. Each time a message is requested, a new representation
(typically a @ref{122f,,Message} instance) is generated based upon the current
state of the mailbox. Similarly, when a message is added to a
@code{Mailbox} instance, the provided message representation's contents are
copied. In neither case is a reference to the message representation kept by
the @code{Mailbox} instance.

The default @code{Mailbox} @ref{1aa,,iterator} iterates over message
representations, not keys as the default @ref{253,,dictionary}
iterator does. Moreover, modification of a
mailbox during iteration is safe and well-defined. Messages added to the
mailbox after an iterator is created will not be seen by the
iterator. Messages removed from the mailbox before the iterator yields them
will be silently skipped, though using a key from an iterator may result in a
@ref{33a,,KeyError} exception if the corresponding message is subsequently
removed.

@cartouche
@quotation Avertissement 
Be very cautious when modifying mailboxes that might be simultaneously
changed by some other process.  The safest mailbox format to use for such
tasks is @ref{412,,Maildir}; try to avoid using single-file formats such as
@ref{1608,,mbox} for
concurrent writing.  If you're modifying a mailbox, you `must' lock it by
calling the @ref{35e4,,lock()} and @ref{35e5,,unlock()} methods `before' reading any
messages in the file or making any changes by adding or deleting a
message.  Failing to lock the mailbox runs the risk of losing messages or
corrupting the entire mailbox.
@end quotation
@end cartouche

@code{Mailbox} instances have the following methods:

@geindex add() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox add}@anchor{122a}
@deffn {Méthode} add (message)

Ajoute `message' à la boîte mail et renvoie la clé qui lui a été assigné.

Le paramètre `message' peut être une instance @ref{122f,,Message}, une instance @ref{279,,email.message.Message}, une chaîne de caractères, une séquence d'octets ou un objet fichier-compatible (qui doit être ouvert en mode binaire). Si `message' est une instance de la sous-classe @ref{122f,,Message} au format correspondant (par exemple s'il s'agit d'une instance @ref{34b8,,mboxMessage} et d'une instance @ref{1608,,mbox}), les informations spécifiques à son format sont utilisées. Sinon, des valeurs par défaut raisonnables pour son format sont utilisées.


Modifié dans la version 3.2: Ajout de la gestion des messages binaires.

@end deffn

@geindex remove() (méthode mailbox.Mailbox)
@geindex __delitem__() (méthode mailbox.Mailbox)
@geindex discard() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox remove}@anchor{35e2}
@deffn {Méthode} remove (key)
@anchor{library/mailbox mailbox Mailbox __delitem__}@anchor{35e6}
@deffnx {Méthode} __delitem__ (key)
@anchor{library/mailbox mailbox Mailbox discard}@anchor{35e3}
@deffnx {Méthode} discard (key)

Supprime le message correspondant à `key' dans la boîte mail.

Si ce message n'existe pas, une exception @ref{33a,,KeyError} est levée si la méthode a été appelée en tant que @ref{35e2,,remove()} ou @ref{35e6,,__delitem__()} ; mais aucune exception n'est levée si la méthode a été appelée en tant que @ref{35e3,,discard()}. Vous préférerez sûrement le comportement de @ref{35e3,,discard()} si le format de boîte mail sous-jacent accepte la modification concurrente par les autres processus.
@end deffn

@geindex __setitem__() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox __setitem__}@anchor{35e7}
@deffn {Méthode} __setitem__ (key, message)

Remplace le message correspondant à `key' par `message'. Lève une exception @ref{33a,,KeyError} s'il n'y a pas déjà de message correspondant à `key'.

Comme pour @ref{122a,,add()}, le paramètre `message' peut être une instance @ref{122f,,Message}, une instance @ref{279,,email.message.Message}, une chaîne de caractères, une chaîne d'octets ou un objet fichier-compatible (qui doit être ouvert en mode binaire). Si `message' est une instance de la sous-classe @ref{122f,,Message} au format correspondant (par exemple s'il s'agit d'une instance @ref{34b8,,mboxMessage} et d'une instance @ref{1608,,mbox}), les informations spécifiques à son format sont utilisées. Sinon, les informations spécifiques au format du message qui correspond à `key' ne sont modifiées.
@end deffn

@geindex iterkeys() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox iterkeys}@anchor{35e8}
@deffn {Méthode} iterkeys ()

Return an @ref{1aa,,iterator} over all keys
@end deffn

@geindex keys() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox keys}@anchor{35e9}
@deffn {Méthode} keys ()

The same as @ref{35e8,,iterkeys()}, except that a @ref{5fc,,list} is returned
rather than an @ref{1aa,,iterator}
@end deffn

@geindex itervalues() (méthode mailbox.Mailbox)
@geindex __iter__() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox itervalues}@anchor{35ea}
@deffn {Méthode} itervalues ()
@anchor{library/mailbox mailbox Mailbox __iter__}@anchor{35eb}
@deffnx {Méthode} __iter__ ()

Return an @ref{1aa,,iterator} over representations of all messages.
The messages are represented
as instances of the appropriate format-specific @ref{122f,,Message} subclass
unless a custom message factory was specified when the @code{Mailbox}
instance was initialized.

@cartouche
@quotation Note 
Le comportement de @ref{35eb,,__iter__()} diffère de celui d'un dictionnaire, pour lequel l'itération se fait sur ses clés.
@end quotation
@end cartouche
@end deffn

@geindex values() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox values}@anchor{35ec}
@deffn {Méthode} values ()

The same as @ref{35ea,,itervalues()}, except that a @ref{5fc,,list} is returned
rather than an @ref{1aa,,iterator}
@end deffn

@geindex iteritems() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox iteritems}@anchor{35ed}
@deffn {Méthode} iteritems ()

Return an @ref{1aa,,iterator} over (`key', `message') pairs, where `key' is
a key and `message' is a message representation. The messages are
represented as instances of the appropriate format-specific
@ref{122f,,Message} subclass unless a custom message factory was specified
when the @code{Mailbox} instance was initialized.
@end deffn

@geindex items() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox items}@anchor{35ee}
@deffn {Méthode} items ()

The same as @ref{35ed,,iteritems()}, except that a @ref{5fc,,list} of pairs is
returned rather than an @ref{1aa,,iterator} of pairs.
@end deffn

@geindex get() (méthode mailbox.Mailbox)
@geindex __getitem__() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get}@anchor{35ef}
@deffn {Méthode} get (key, default=None)
@anchor{library/mailbox mailbox Mailbox __getitem__}@anchor{35f0}
@deffnx {Méthode} __getitem__ (key)

Return a representation of the message corresponding to `key'. If no such
message exists, `default' is returned if the method was called as
@ref{35ef,,get()} and a @ref{33a,,KeyError} exception is raised if the method was
called as @code{__getitem__()}. The message is represented as an instance
of the appropriate format-specific @ref{122f,,Message} subclass unless a
custom message factory was specified when the @code{Mailbox} instance
was initialized.
@end deffn

@geindex get_message() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_message}@anchor{35f1}
@deffn {Méthode} get_message (key)

Return a representation of the message corresponding to `key' as an
instance of the appropriate format-specific @ref{122f,,Message} subclass, or
raise a @ref{33a,,KeyError} exception if no such message exists.
@end deffn

@geindex get_bytes() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_bytes}@anchor{122d}
@deffn {Méthode} get_bytes (key)

Return a byte representation of the message corresponding to `key', or
raise a @ref{33a,,KeyError} exception if no such message exists.


Ajouté dans la version 3.2.

@end deffn

@geindex get_string() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_string}@anchor{122e}
@deffn {Méthode} get_string (key)

Return a string representation of the message corresponding to `key', or
raise a @ref{33a,,KeyError} exception if no such message exists.  The
message is processed through @ref{279,,email.message.Message} to
convert it to a 7bit clean representation.
@end deffn

@geindex get_file() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox get_file}@anchor{122c}
@deffn {Méthode} get_file (key)

Return a @ref{250d,,file-like} representation of the
message corresponding to `key',
or raise a @ref{33a,,KeyError} exception if no such message exists.  The
file-like object behaves as if open in binary mode.  This file should be
closed once it is no longer needed.


Modifié dans la version 3.2: The file object really is a @ref{1c15,,binary file}; previously it was
incorrectly returned in text mode.  Also, the @ref{250d,,file-like object}
now supports the @ref{5be,,context manager} protocol: you can use a
@ref{5bc,,with} statement to automatically close it.


@cartouche
@quotation Note 
Unlike other representations of messages,
@ref{250d,,file-like} representations are not
necessarily independent of the @code{Mailbox} instance that
created them or of the underlying mailbox.  More specific documentation
is provided by each subclass.
@end quotation
@end cartouche
@end deffn

@geindex __contains__() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox __contains__}@anchor{35f2}
@deffn {Méthode} __contains__ (key)

Return @code{True} if `key' corresponds to a message, @code{False} otherwise.
@end deffn

@geindex __len__() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox __len__}@anchor{35f3}
@deffn {Méthode} __len__ ()

Return a count of messages in the mailbox.
@end deffn

@geindex clear() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox clear}@anchor{35f4}
@deffn {Méthode} clear ()

Supprime tous les messages de la boîte de courriel.
@end deffn

@geindex pop() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox pop}@anchor{35f5}
@deffn {Méthode} pop (key, default=None)

Return a representation of the message corresponding to `key' and delete
the message. If no such message exists, return `default'. The message is
represented as an instance of the appropriate format-specific
@ref{122f,,Message} subclass unless a custom message factory was specified
when the @code{Mailbox} instance was initialized.
@end deffn

@geindex popitem() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox popitem}@anchor{35f6}
@deffn {Méthode} popitem ()

Return an arbitrary (`key', `message') pair, where `key' is a key and
`message' is a message representation, and delete the corresponding
message. If the mailbox is empty, raise a @ref{33a,,KeyError} exception. The
message is represented as an instance of the appropriate format-specific
@ref{122f,,Message} subclass unless a custom message factory was specified
when the @code{Mailbox} instance was initialized.
@end deffn

@geindex update() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox update}@anchor{35f7}
@deffn {Méthode} update (arg)

Parameter `arg' should be a `key'-to-`message' mapping or an iterable of
(`key', `message') pairs. Updates the mailbox so that, for each given
`key' and `message', the message corresponding to `key' is set to
`message' as if by using @ref{35e7,,__setitem__()}. As with @ref{35e7,,__setitem__()},
each `key' must already correspond to a message in the mailbox or else a
@ref{33a,,KeyError} exception will be raised, so in general it is incorrect
for `arg' to be a @code{Mailbox} instance.

@cartouche
@quotation Note 
Unlike with dictionaries, keyword arguments are not supported.
@end quotation
@end cartouche
@end deffn

@geindex flush() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox flush}@anchor{35f8}
@deffn {Méthode} flush ()

Write any pending changes to the filesystem. For some @ref{122b,,Mailbox}
subclasses, changes are always written immediately and @code{flush()} does
nothing, but you should still make a habit of calling this method.
@end deffn

@geindex lock() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox lock}@anchor{35e4}
@deffn {Méthode} lock ()

Acquire an exclusive advisory lock on the mailbox so that other processes
know not to modify it. An @ref{35f9,,ExternalClashError} is raised if the lock
is not available. The particular locking mechanisms used depend upon the
mailbox format.  You should `always' lock the mailbox before making any
modifications to its contents.
@end deffn

@geindex unlock() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox unlock}@anchor{35e5}
@deffn {Méthode} unlock ()

Release the lock on the mailbox, if any.
@end deffn

@geindex close() (méthode mailbox.Mailbox)
@anchor{library/mailbox mailbox Mailbox close}@anchor{35fa}
@deffn {Méthode} close ()

Flush the mailbox, unlock it if necessary, and close any open files. For
some @code{Mailbox} subclasses, this method does nothing.
@end deffn
@end deffn

@menu
* Maildir objects:: 
* mbox objects:: 
* MH objects:: 
* Babyl objects:: 
* MMDF objects:: 

@end menu

@node Maildir objects,mbox objects,,Mailbox objects
@anchor{library/mailbox mailbox-maildir}@anchor{35fb}@anchor{library/mailbox maildir-objects}@anchor{35fc}
@subsubsection @code{Maildir} objects


@geindex Maildir (classe dans mailbox)
@anchor{library/mailbox mailbox Maildir}@anchor{412}
@deffn {Classe} mailbox.Maildir (dirname, factory=None, create=True)

A subclass of @ref{122b,,Mailbox} for mailboxes in Maildir format. Parameter
`factory' is a callable object that accepts a file-like message representation
(which behaves as if opened in binary mode) and returns a custom representation.
If `factory' is @code{None}, @ref{35fd,,MaildirMessage} is used as the default message
representation. If `create' is @code{True}, the mailbox is created if it does not
exist.

If `create' is @code{True} and the `dirname' path exists, it will be treated as
an existing maildir without attempting to verify its directory layout.

It is for historical reasons that `dirname' is named as such rather than `path'.

Maildir is a directory-based mailbox format invented for the qmail mail
transfer agent and now widely supported by other programs. Messages in a
Maildir mailbox are stored in separate files within a common directory
structure. This design allows Maildir mailboxes to be accessed and modified
by multiple unrelated programs without data corruption, so file locking is
unnecessary.

Maildir mailboxes contain three subdirectories, namely: @code{tmp},
@code{new}, and @code{cur}. Messages are created momentarily in the
@code{tmp} subdirectory and then moved to the @code{new} subdirectory to
finalize delivery. A mail user agent may subsequently move the message to the
@code{cur} subdirectory and store information about the state of the message
in a special "info" section appended to its file name.

Folders of the style introduced by the Courier mail transfer agent are also
supported. Any subdirectory of the main mailbox is considered a folder if
@code{'.'} is the first character in its name. Folder names are represented by
@code{Maildir} without the leading @code{'.'}. Each folder is itself a Maildir
mailbox but should not contain other folders. Instead, a logical nesting is
indicated using @code{'.'} to delimit levels, e.g., "Archived.2005.07".

@geindex colon (attribut mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir colon}@anchor{35fe}
@deffn {Attribut} colon

The Maildir specification requires the use of a colon (@code{':'}) in certain
message file names. However, some operating systems do not permit this
character in file names, If you wish to use a Maildir-like format on such
an operating system, you should specify another character to use
instead. The exclamation point (@code{'!'}) is a popular choice. For
example:

@example
import mailbox
mailbox.Maildir.colon = '!'
@end example

The @code{colon} attribute may also be set on a per-instance basis.
@end deffn


Modifié dans la version 3.13: @ref{412,,Maildir} now ignores files with a leading dot.


@code{Maildir} instances have all of the methods of @ref{122b,,Mailbox} in
addition to the following:

@geindex list_folders() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir list_folders}@anchor{35ff}
@deffn {Méthode} list_folders ()

Return a list of the names of all folders.
@end deffn

@geindex get_folder() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_folder}@anchor{3600}
@deffn {Méthode} get_folder (folder)

Return a @code{Maildir} instance representing the folder whose name is
`folder'. A @ref{3601,,NoSuchMailboxError} exception is raised if the folder
does not exist.
@end deffn

@geindex add_folder() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir add_folder}@anchor{3602}
@deffn {Méthode} add_folder (folder)

Create a folder whose name is `folder' and return a @code{Maildir}
instance representing it.
@end deffn

@geindex remove_folder() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir remove_folder}@anchor{3603}
@deffn {Méthode} remove_folder (folder)

Delete the folder whose name is `folder'. If the folder contains any
messages, a @ref{3604,,NotEmptyError} exception will be raised and the folder
will not be deleted.
@end deffn

@geindex clean() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir clean}@anchor{3605}
@deffn {Méthode} clean ()

Delete temporary files from the mailbox that have not been accessed in the
last 36 hours. The Maildir specification says that mail-reading programs
should do this occasionally.
@end deffn

@geindex get_flags() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_flags}@anchor{165b}
@deffn {Méthode} get_flags (key)

Return as a string the flags that are set on the message
corresponding to `key'.
This is the same as @code{get_message(key).get_flags()} but much
faster, because it does not open the message file.
Use this method when iterating over the keys to determine which
messages are interesting to get.

If you do have a @ref{35fd,,MaildirMessage} object, use
its @ref{3606,,get_flags()} method instead, because
changes made by the message's @ref{3607,,set_flags()},
@ref{3608,,add_flag()} and @ref{3609,,remove_flag()}
methods are not reflected here until the mailbox's
@ref{360a,,__setitem__()} method is called.


Ajouté dans la version 3.13.

@end deffn

@geindex set_flags() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir set_flags}@anchor{165c}
@deffn {Méthode} set_flags (key, flags)

On the message corresponding to `key', set the flags specified
by `flags' and unset all others.
Calling @code{some_mailbox.set_flags(key, flags)} is similar to

@example
one_message = some_mailbox.get_message(key)
one_message.set_flags(flags)
some_mailbox[key] = one_message
@end example

but faster, because it does not open the message file.

If you do have a @ref{35fd,,MaildirMessage} object, use
its @ref{3607,,set_flags()} method instead, because
changes made with this mailbox method will not be visible to the
message object's method, @ref{3606,,get_flags()}.


Ajouté dans la version 3.13.

@end deffn

@geindex add_flag() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir add_flag}@anchor{165d}
@deffn {Méthode} add_flag (key, flag)

On the message corresponding to `key', set the flags specified
by `flag' without changing other flags. To add more than one
flag at a time, `flag' may be a string of more than one character.

Considerations for using this method versus the message object's
@ref{3608,,add_flag()} method are similar to
those for @ref{165c,,set_flags()}; see the discussion there.


Ajouté dans la version 3.13.

@end deffn

@geindex remove_flag() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir remove_flag}@anchor{165e}
@deffn {Méthode} remove_flag (key, flag)

On the message corresponding to `key', unset the flags specified
by `flag' without changing other flags. To remove more than one
flag at a time, `flag' may be a string of more than one character.

Considerations for using this method versus the message object's
@ref{3609,,remove_flag()} method are similar to
those for @ref{165c,,set_flags()}; see the discussion there.


Ajouté dans la version 3.13.

@end deffn

@geindex get_info() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_info}@anchor{1659}
@deffn {Méthode} get_info (key)

Return a string containing the info for the message
corresponding to `key'.
This is the same as @code{get_message(key).get_info()} but much
faster, because it does not open the message file.
Use this method when iterating over the keys to determine which
messages are interesting to get.

If you do have a @ref{35fd,,MaildirMessage} object, use
its @ref{360b,,get_info()} method instead, because
changes made by the message's @ref{360c,,set_info()} method
are not reflected here until the mailbox's @ref{360a,,__setitem__()} method
is called.


Ajouté dans la version 3.13.

@end deffn

@geindex set_info() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir set_info}@anchor{165a}
@deffn {Méthode} set_info (key, info)

Set the info of the message corresponding to `key' to `info'.
Calling @code{some_mailbox.set_info(key, flags)} is similar to

@example
one_message = some_mailbox.get_message(key)
one_message.set_info(info)
some_mailbox[key] = one_message
@end example

but faster, because it does not open the message file.

If you do have a @ref{35fd,,MaildirMessage} object, use
its @ref{360c,,set_info()} method instead, because
changes made with this mailbox method will not be visible to the
message object's method, @ref{360b,,get_info()}.


Ajouté dans la version 3.13.

@end deffn

Some @ref{122b,,Mailbox} methods implemented by @code{Maildir} deserve special
remarks:

@geindex add() (méthode mailbox.Maildir)
@geindex __setitem__() (méthode mailbox.Maildir)
@geindex update() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir add}@anchor{360d}
@deffn {Méthode} add (message)
@anchor{library/mailbox mailbox Maildir __setitem__}@anchor{360a}
@deffnx {Méthode} __setitem__ (key, message)
@anchor{library/mailbox mailbox Maildir update}@anchor{360e}
@deffnx {Méthode} update (arg)

@cartouche
@quotation Avertissement 
These methods generate unique file names based upon the current process
ID. When using multiple threads, undetected name clashes may occur and
cause corruption of the mailbox unless threads are coordinated to avoid
using these methods to manipulate the same mailbox simultaneously.
@end quotation
@end cartouche
@end deffn

@geindex flush() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir flush}@anchor{360f}
@deffn {Méthode} flush ()

All changes to Maildir mailboxes are immediately applied, so this method
does nothing.
@end deffn

@geindex lock() (méthode mailbox.Maildir)
@geindex unlock() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir lock}@anchor{3610}
@deffn {Méthode} lock ()
@anchor{library/mailbox mailbox Maildir unlock}@anchor{3611}
@deffnx {Méthode} unlock ()

Maildir mailboxes do not support (or require) locking, so these methods do
nothing.
@end deffn

@geindex close() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir close}@anchor{3612}
@deffn {Méthode} close ()

@code{Maildir} instances do not keep any open files and the underlying
mailboxes do not support locking, so this method does nothing.
@end deffn

@geindex get_file() (méthode mailbox.Maildir)
@anchor{library/mailbox mailbox Maildir get_file}@anchor{3613}
@deffn {Méthode} get_file (key)

Depending upon the host platform, it may not be possible to modify or
remove the underlying message while the returned file remains open.
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item maildir man page from Courier@footnote{https://www.courier-mta.org/maildir.html}

A specification of the format. Describes a common extension for
supporting folders.

@item Using maildir format@footnote{https://cr.yp.to/proto/maildir.html}

Notes on Maildir by its inventor. Includes an updated name-creation scheme and
details on "info" semantics.
@end table


@node mbox objects,MH objects,Maildir objects,Mailbox objects
@anchor{library/mailbox mailbox-mbox}@anchor{3614}@anchor{library/mailbox mbox-objects}@anchor{3615}
@subsubsection @code{mbox} objects


@geindex mbox (classe dans mailbox)
@anchor{library/mailbox mailbox mbox}@anchor{1608}
@deffn {Classe} mailbox.mbox (path, factory=None, create=True)

A subclass of @ref{122b,,Mailbox} for mailboxes in mbox format. Parameter `factory'
is a callable object that accepts a file-like message representation (which
behaves as if opened in binary mode) and returns a custom representation. If
`factory' is @code{None}, @ref{34b8,,mboxMessage} is used as the default message
representation. If `create' is @code{True}, the mailbox is created if it does not
exist.

The mbox format is the classic format for storing mail on Unix systems. All
messages in an mbox mailbox are stored in a single file with the beginning of
each message indicated by a line whose first five characters are "From ".

Several variations of the mbox format exist to address perceived shortcomings in
the original. In the interest of compatibility, @code{mbox} implements the
original format, which is sometimes referred to as `mboxo'. This means that
the @code{Content-Length} header, if present, is ignored and that any
occurrences of "From " at the beginning of a line in a message body are
transformed to ">From " when storing the message, although occurrences of ">From
" are not transformed to "From " when reading the message.

Some @ref{122b,,Mailbox} methods implemented by @code{mbox} deserve special
remarks:

@geindex get_file() (méthode mailbox.mbox)
@anchor{library/mailbox mailbox mbox get_file}@anchor{3616}
@deffn {Méthode} get_file (key)

Using the file after calling @ref{35f8,,flush()} or
@ref{35fa,,close()} on the @code{mbox} instance may yield
unpredictable results or raise an exception.
@end deffn

@geindex lock() (méthode mailbox.mbox)
@geindex unlock() (méthode mailbox.mbox)
@anchor{library/mailbox mailbox mbox lock}@anchor{3617}
@deffn {Méthode} lock ()
@anchor{library/mailbox mailbox mbox unlock}@anchor{3618}
@deffnx {Méthode} unlock ()

Three locking mechanisms are used---dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls.
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item mbox man page from tin@footnote{http://www.tin.org/bin/man.cgi?section=5&topic=mbox}

A specification of the format, with details on locking.

@item Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad@footnote{https://www.jwz.org/doc/content-length.html}

An argument for using the original mbox format rather than a variation.

@item "mbox" is a family of several mutually incompatible mailbox formats@footnote{https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml}

A history of mbox variations.
@end table


@node MH objects,Babyl objects,mbox objects,Mailbox objects
@anchor{library/mailbox mailbox-mh}@anchor{3619}@anchor{library/mailbox mh-objects}@anchor{361a}
@subsubsection @code{MH} objects


@geindex MH (classe dans mailbox)
@anchor{library/mailbox mailbox MH}@anchor{163f}
@deffn {Classe} mailbox.MH (path, factory=None, create=True)

A subclass of @ref{122b,,Mailbox} for mailboxes in MH format. Parameter `factory'
is a callable object that accepts a file-like message representation (which
behaves as if opened in binary mode) and returns a custom representation. If
`factory' is @code{None}, @ref{361b,,MHMessage} is used as the default message
representation. If `create' is @code{True}, the mailbox is created if it does not
exist.

MH is a directory-based mailbox format invented for the MH Message Handling
System, a mail user agent. Each message in an MH mailbox resides in its own
file. An MH mailbox may contain other MH mailboxes (called `folders') in
addition to messages. Folders may be nested indefinitely. MH mailboxes also
support `sequences', which are named lists used to logically group
messages without moving them to sub-folders. Sequences are defined in a file
called @code{.mh_sequences} in each folder.

The @code{MH} class manipulates MH mailboxes, but it does not attempt to
emulate all of @code{mh}'s behaviors. In particular, it does not modify
and is not affected by the @code{context} or @code{.mh_profile} files that
are used by @code{mh} to store its state and configuration.

@code{MH} instances have all of the methods of @ref{122b,,Mailbox} in addition
to the following:


Modifié dans la version 3.13: Supported folders that don't contain a @code{.mh_sequences} file.


@geindex list_folders() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH list_folders}@anchor{361c}
@deffn {Méthode} list_folders ()

Return a list of the names of all folders.
@end deffn

@geindex get_folder() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH get_folder}@anchor{361d}
@deffn {Méthode} get_folder (folder)

Return an @code{MH} instance representing the folder whose name is
`folder'. A @ref{3601,,NoSuchMailboxError} exception is raised if the folder
does not exist.
@end deffn

@geindex add_folder() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH add_folder}@anchor{361e}
@deffn {Méthode} add_folder (folder)

Create a folder whose name is `folder' and return an @code{MH} instance
representing it.
@end deffn

@geindex remove_folder() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH remove_folder}@anchor{361f}
@deffn {Méthode} remove_folder (folder)

Delete the folder whose name is `folder'. If the folder contains any
messages, a @ref{3604,,NotEmptyError} exception will be raised and the folder
will not be deleted.
@end deffn

@geindex get_sequences() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH get_sequences}@anchor{3620}
@deffn {Méthode} get_sequences ()

Return a dictionary of sequence names mapped to key lists. If there are no
sequences, the empty dictionary is returned.
@end deffn

@geindex set_sequences() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH set_sequences}@anchor{3621}
@deffn {Méthode} set_sequences (sequences)

Re-define the sequences that exist in the mailbox based upon `sequences',
a dictionary of names mapped to key lists, like returned by
@ref{3620,,get_sequences()}.
@end deffn

@geindex pack() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH pack}@anchor{3622}
@deffn {Méthode} pack ()

Rename messages in the mailbox as necessary to eliminate gaps in
numbering.  Entries in the sequences list are updated correspondingly.

@cartouche
@quotation Note 
Already-issued keys are invalidated by this operation and should not be
subsequently used.
@end quotation
@end cartouche
@end deffn

Some @ref{122b,,Mailbox} methods implemented by @code{MH} deserve special
remarks:

@geindex remove() (méthode mailbox.MH)
@geindex __delitem__() (méthode mailbox.MH)
@geindex discard() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH remove}@anchor{3623}
@deffn {Méthode} remove (key)
@anchor{library/mailbox mailbox MH __delitem__}@anchor{3624}
@deffnx {Méthode} __delitem__ (key)
@anchor{library/mailbox mailbox MH discard}@anchor{3625}
@deffnx {Méthode} discard (key)

These methods immediately delete the message. The MH convention of marking
a message for deletion by prepending a comma to its name is not used.
@end deffn

@geindex lock() (méthode mailbox.MH)
@geindex unlock() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH lock}@anchor{3626}
@deffn {Méthode} lock ()
@anchor{library/mailbox mailbox MH unlock}@anchor{3627}
@deffnx {Méthode} unlock ()

Three locking mechanisms are used---dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls. For MH mailboxes, locking
the mailbox means locking the @code{.mh_sequences} file and, only for the
duration of any operations that affect them, locking individual message
files.
@end deffn

@geindex get_file() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH get_file}@anchor{3628}
@deffn {Méthode} get_file (key)

Depending upon the host platform, it may not be possible to remove the
underlying message while the returned file remains open.
@end deffn

@geindex flush() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH flush}@anchor{3629}
@deffn {Méthode} flush ()

All changes to MH mailboxes are immediately applied, so this method does
nothing.
@end deffn

@geindex close() (méthode mailbox.MH)
@anchor{library/mailbox mailbox MH close}@anchor{362a}
@deffn {Méthode} close ()

@code{MH} instances do not keep any open files, so this method is
equivalent to @ref{3627,,unlock()}.
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item nmh - Message Handling System@footnote{https://www.nongnu.org/nmh/}

Home page of @code{nmh}, an updated version of the original @code{mh}.

@item MH & nmh: Email for Users & Programmers@footnote{https://rand-mh.sourceforge.io/book/}

A GPL-licensed book on @code{mh} and @code{nmh}, with some information
on the mailbox format.
@end table


@node Babyl objects,MMDF objects,MH objects,Mailbox objects
@anchor{library/mailbox babyl-objects}@anchor{362b}@anchor{library/mailbox mailbox-babyl}@anchor{362c}
@subsubsection @code{Babyl} objects


@geindex Babyl (classe dans mailbox)
@anchor{library/mailbox mailbox Babyl}@anchor{362d}
@deffn {Classe} mailbox.Babyl (path, factory=None, create=True)

A subclass of @ref{122b,,Mailbox} for mailboxes in Babyl format. Parameter
`factory' is a callable object that accepts a file-like message representation
(which behaves as if opened in binary mode) and returns a custom representation.
If `factory' is @code{None}, @ref{362e,,BabylMessage} is used as the default message
representation. If `create' is @code{True}, the mailbox is created if it does not
exist.

Babyl is a single-file mailbox format used by the Rmail mail user agent
included with Emacs. The beginning of a message is indicated by a line
containing the two characters Control-Underscore (@code{'\037'}) and Control-L
(@code{'\014'}). The end of a message is indicated by the start of the next
message or, in the case of the last message, a line containing a
Control-Underscore (@code{'\037'}) character.

Messages in a Babyl mailbox have two sets of headers, original headers and
so-called visible headers. Visible headers are typically a subset of the
original headers that have been reformatted or abridged to be more
attractive. Each message in a Babyl mailbox also has an accompanying list of
`labels', or short strings that record extra information about the
message, and a list of all user-defined labels found in the mailbox is kept
in the Babyl options section.

@code{Babyl} instances have all of the methods of @ref{122b,,Mailbox} in
addition to the following:

@geindex get_labels() (méthode mailbox.Babyl)
@anchor{library/mailbox mailbox Babyl get_labels}@anchor{362f}
@deffn {Méthode} get_labels ()

Return a list of the names of all user-defined labels used in the mailbox.

@cartouche
@quotation Note 
The actual messages are inspected to determine which labels exist in
the mailbox rather than consulting the list of labels in the Babyl
options section, but the Babyl section is updated whenever the mailbox
is modified.
@end quotation
@end cartouche
@end deffn

Some @ref{122b,,Mailbox} methods implemented by @code{Babyl} deserve special
remarks:

@geindex get_file() (méthode mailbox.Babyl)
@anchor{library/mailbox mailbox Babyl get_file}@anchor{3630}
@deffn {Méthode} get_file (key)

In Babyl mailboxes, the headers of a message are not stored contiguously
with the body of the message. To generate a file-like representation, the
headers and body are copied together into an @ref{e8d,,io.BytesIO} instance,
which has an API identical to that of a
file. As a result, the file-like object is truly independent of the
underlying mailbox but does not save memory compared to a string
representation.
@end deffn

@geindex lock() (méthode mailbox.Babyl)
@geindex unlock() (méthode mailbox.Babyl)
@anchor{library/mailbox mailbox Babyl lock}@anchor{3631}
@deffn {Méthode} lock ()
@anchor{library/mailbox mailbox Babyl unlock}@anchor{3632}
@deffnx {Méthode} unlock ()

Three locking mechanisms are used---dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls.
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item Format of Version 5 Babyl Files@footnote{https://quimby.gnus.org/notes/BABYL}

A specification of the Babyl format.

@item Reading Mail with Rmail@footnote{https://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html}

The Rmail manual, with some information on Babyl semantics.
@end table


@node MMDF objects,,Babyl objects,Mailbox objects
@anchor{library/mailbox mailbox-mmdf}@anchor{3633}@anchor{library/mailbox mmdf-objects}@anchor{3634}
@subsubsection @code{MMDF} objects


@geindex MMDF (classe dans mailbox)
@anchor{library/mailbox mailbox MMDF}@anchor{1609}
@deffn {Classe} mailbox.MMDF (path, factory=None, create=True)

A subclass of @ref{122b,,Mailbox} for mailboxes in MMDF format. Parameter `factory'
is a callable object that accepts a file-like message representation (which
behaves as if opened in binary mode) and returns a custom representation. If
`factory' is @code{None}, @ref{3635,,MMDFMessage} is used as the default message
representation. If `create' is @code{True}, the mailbox is created if it does not
exist.

MMDF is a single-file mailbox format invented for the Multichannel Memorandum
Distribution Facility, a mail transfer agent. Each message is in the same
form as an mbox message but is bracketed before and after by lines containing
four Control-A (@code{'\001'}) characters. As with the mbox format, the
beginning of each message is indicated by a line whose first five characters
are "From ", but additional occurrences of "From " are not transformed to
">From " when storing messages because the extra message separator lines
prevent mistaking such occurrences for the starts of subsequent messages.

Some @ref{122b,,Mailbox} methods implemented by @code{MMDF} deserve special
remarks:

@geindex get_file() (méthode mailbox.MMDF)
@anchor{library/mailbox mailbox MMDF get_file}@anchor{3636}
@deffn {Méthode} get_file (key)

Using the file after calling @ref{35f8,,flush()} or
@ref{35fa,,close()} on the @code{MMDF} instance may yield
unpredictable results or raise an exception.
@end deffn

@geindex lock() (méthode mailbox.MMDF)
@geindex unlock() (méthode mailbox.MMDF)
@anchor{library/mailbox mailbox MMDF lock}@anchor{3637}
@deffn {Méthode} lock ()
@anchor{library/mailbox mailbox MMDF unlock}@anchor{3638}
@deffnx {Méthode} unlock ()

Three locking mechanisms are used---dot locking and, if available, the
@code{flock()} and @code{lockf()} system calls.
@end deffn
@end deffn


@subsubheading Voir aussi



@table @asis

@item mmdf man page from tin@footnote{http://www.tin.org/bin/man.cgi?section=5&topic=mmdf}

A specification of MMDF format from the documentation of tin, a newsreader.

@item MMDF@footnote{https://en.wikipedia.org/wiki/MMDF}

A Wikipedia article describing the Multichannel Memorandum Distribution
Facility.
@end table


@node Message objects,Exceptions<18>,Mailbox objects,mailbox --- Manipulate mailboxes in various formats
@anchor{library/mailbox mailbox-message-objects}@anchor{3639}@anchor{library/mailbox message-objects}@anchor{363a}
@subsubsection @code{Message} objects


@geindex Message (classe dans mailbox)
@anchor{library/mailbox mailbox Message}@anchor{122f}
@deffn {Classe} mailbox.Message (message=None)

A subclass of the @ref{44,,email.message} module's
@ref{279,,Message}. Subclasses of @code{mailbox.Message} add
mailbox-format-specific state and behavior.

If `message' is omitted, the new instance is created in a default, empty state.
If `message' is an @ref{279,,email.message.Message} instance, its contents are
copied; furthermore, any format-specific information is converted insofar as
possible if `message' is a @code{Message} instance. If `message' is a string,
a byte string,
or a file, it should contain an 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html}-compliant message, which is read
and parsed.  Files should be open in binary mode, but text mode files
are accepted for backward compatibility.

The format-specific state and behaviors offered by subclasses vary, but in
general it is only the properties that are not specific to a particular
mailbox that are supported (although presumably the properties are specific
to a particular mailbox format). For example, file offsets for single-file
mailbox formats and file names for directory-based mailbox formats are not
retained, because they are only applicable to the original mailbox. But state
such as whether a message has been read by the user or marked as important is
retained, because it applies to the message itself.

There is no requirement that @code{Message} instances be used to represent
messages retrieved using @ref{122b,,Mailbox} instances. In some situations, the
time and memory required to generate @code{Message} representations might
not be acceptable. For such situations, @code{Mailbox} instances also
offer string and file-like representations, and a custom message factory may
be specified when a @code{Mailbox} instance is initialized.
@end deffn

@menu
* MaildirMessage objects:: 
* mboxMessage objects:: 
* MHMessage objects:: 
* BabylMessage objects:: 
* MMDFMessage objects:: 

@end menu

@node MaildirMessage objects,mboxMessage objects,,Message objects
@anchor{library/mailbox mailbox-maildirmessage}@anchor{363b}@anchor{library/mailbox maildirmessage-objects}@anchor{363c}
@subsubsection @code{MaildirMessage} objects


@geindex MaildirMessage (classe dans mailbox)
@anchor{library/mailbox mailbox MaildirMessage}@anchor{35fd}
@deffn {Classe} mailbox.MaildirMessage (message=None)

A message with Maildir-specific behaviors. Parameter `message' has the same
meaning as with the @ref{122f,,Message} constructor.

Typically, a mail user agent application moves all of the messages in the
@code{new} subdirectory to the @code{cur} subdirectory after the first time
the user opens and closes the mailbox, recording that the messages are old
whether or not they've actually been read. Each message in @code{cur} has an
"info" section added to its file name to store information about its state.
(Some mail readers may also add an "info" section to messages in
@code{new}.)  The "info" section may take one of two forms: it may contain
"2," followed by a list of standardized flags (e.g., "2,FR") or it may
contain "1," followed by so-called experimental information. Standard flags
for Maildir messages are as follows:


@multitable {xxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@tab

Explication

@item

D

@tab

Draft

@tab

Under composition

@item

F

@tab

Flagged

@tab

Marked as important

@item

P

@tab

Passed

@tab

Forwarded, resent, or bounced

@item

R

@tab

Replied

@tab

Replied to

@item

S

@tab

Seen

@tab

Read

@item

T

@tab

Trashed

@tab

Marked for subsequent deletion

@end multitable


@code{MaildirMessage} instances offer the following methods:

@geindex get_subdir() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_subdir}@anchor{363d}
@deffn {Méthode} get_subdir ()

Return either "new" (if the message should be stored in the @code{new}
subdirectory) or "cur" (if the message should be stored in the @code{cur}
subdirectory).

@cartouche
@quotation Note 
A message is typically moved from @code{new} to @code{cur} after its
mailbox has been accessed, whether or not the message has been
read. A message @code{msg} has been read if @code{"S" in msg.get_flags()} is
@code{True}.
@end quotation
@end cartouche
@end deffn

@geindex set_subdir() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_subdir}@anchor{363e}
@deffn {Méthode} set_subdir (subdir)

Set the subdirectory the message should be stored in. Parameter `subdir'
must be either "new" or "cur".
@end deffn

@geindex get_flags() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_flags}@anchor{3606}
@deffn {Méthode} get_flags ()

Return a string specifying the flags that are currently set. If the
message complies with the standard Maildir format, the result is the
concatenation in alphabetical order of zero or one occurrence of each of
@code{'D'}, @code{'F'}, @code{'P'}, @code{'R'}, @code{'S'}, and @code{'T'}. The empty string
is returned if no flags are set or if "info" contains experimental
semantics.
@end deffn

@geindex set_flags() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_flags}@anchor{3607}
@deffn {Méthode} set_flags (flags)

Set the flags specified by `flags' and unset all others.
@end deffn

@geindex add_flag() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage add_flag}@anchor{3608}
@deffn {Méthode} add_flag (flag)

Set the flag(s) specified by `flag' without changing other flags. To add
more than one flag at a time, `flag' may be a string of more than one
character. The current "info" is overwritten whether or not it contains
experimental information rather than flags.
@end deffn

@geindex remove_flag() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage remove_flag}@anchor{3609}
@deffn {Méthode} remove_flag (flag)

Unset the flag(s) specified by `flag' without changing other flags. To
remove more than one flag at a time, `flag' maybe a string of more than
one character.  If "info" contains experimental information rather than
flags, the current "info" is not modified.
@end deffn

@geindex get_date() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_date}@anchor{363f}
@deffn {Méthode} get_date ()

Return the delivery date of the message as a floating-point number
representing seconds since the epoch.
@end deffn

@geindex set_date() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_date}@anchor{3640}
@deffn {Méthode} set_date (date)

Set the delivery date of the message to `date', a floating-point number
representing seconds since the epoch.
@end deffn

@geindex get_info() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage get_info}@anchor{360b}
@deffn {Méthode} get_info ()

Return a string containing the "info" for a message. This is useful for
accessing and modifying "info" that is experimental (i.e., not a list of
flags).
@end deffn

@geindex set_info() (méthode mailbox.MaildirMessage)
@anchor{library/mailbox mailbox MaildirMessage set_info}@anchor{360c}
@deffn {Méthode} set_info (info)

Set "info" to `info', which should be a string.
@end deffn
@end deffn

When a @code{MaildirMessage} instance is created based upon an
@ref{34b8,,mboxMessage} or @ref{3635,,MMDFMessage} instance, the @code{Status}
and @code{X-Status} headers are omitted and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{34b8,,mboxMessage} or @ref{3635,,MMDFMessage}
state

@item

"cur" subdirectory

@tab

O flag

@item

F flag

@tab

F flag

@item

R flag

@tab

A flag

@item

S flag

@tab

R flag

@item

T flag

@tab

D flag

@end multitable


When a @code{MaildirMessage} instance is created based upon an
@ref{361b,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{361b,,MHMessage} state

@item

"cur" subdirectory

@tab

"unseen" sequence

@item

"cur" subdirectory and S flag

@tab

no "unseen" sequence

@item

F flag

@tab

"flagged" sequence

@item

R flag

@tab

"replied" sequence

@end multitable


When a @code{MaildirMessage} instance is created based upon a
@ref{362e,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{362e,,BabylMessage} state

@item

"cur" subdirectory

@tab

"unseen" label

@item

"cur" subdirectory and S flag

@tab

no "unseen" label

@item

P flag

@tab

"forwarded" or "resent" label

@item

R flag

@tab

"answered" label

@item

T flag

@tab

"deleted" label

@end multitable


@node mboxMessage objects,MHMessage objects,MaildirMessage objects,Message objects
@anchor{library/mailbox mailbox-mboxmessage}@anchor{3641}@anchor{library/mailbox mboxmessage-objects}@anchor{3642}
@subsubsection @code{mboxMessage} objects


@geindex mboxMessage (classe dans mailbox)
@anchor{library/mailbox mailbox mboxMessage}@anchor{34b8}
@deffn {Classe} mailbox.mboxMessage (message=None)

A message with mbox-specific behaviors. Parameter `message' has the same meaning
as with the @ref{122f,,Message} constructor.

Messages in an mbox mailbox are stored together in a single file. The
sender's envelope address and the time of delivery are typically stored in a
line beginning with "From " that is used to indicate the start of a message,
though there is considerable variation in the exact format of this data among
mbox implementations. Flags that indicate the state of the message, such as
whether it has been read or marked as important, are typically stored in
@code{Status} and @code{X-Status} headers.

Conventional flags for mbox messages are as follows:


@multitable {xxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@tab

Explication

@item

R

@tab

Read

@tab

Read

@item

O

@tab

Old

@tab

Previously detected by MUA

@item

D

@tab

Deleted

@tab

Marked for subsequent deletion

@item

F

@tab

Flagged

@tab

Marked as important

@item

A

@tab

Answered

@tab

Replied to

@end multitable


The "R" and "O" flags are stored in the @code{Status} header, and the
"D", "F", and "A" flags are stored in the @code{X-Status} header. The
flags and headers typically appear in the order mentioned.

@code{mboxMessage} instances offer the following methods:

@geindex get_from() (méthode mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage get_from}@anchor{3643}
@deffn {Méthode} get_from ()

Return a string representing the "From " line that marks the start of the
message in an mbox mailbox. The leading "From " and the trailing newline
are excluded.
@end deffn

@geindex set_from() (méthode mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage set_from}@anchor{3644}
@deffn {Méthode} set_from (from_, time_=None)

Set the "From " line to `from_', which should be specified without a
leading "From " or trailing newline. For convenience, `time_' may be
specified and will be formatted appropriately and appended to `from_'. If
`time_' is specified, it should be a @ref{cd8,,time.struct_time} instance, a
tuple suitable for passing to @ref{11c6,,time.strftime()}, or @code{True} (to use
@ref{119d,,time.gmtime()}).
@end deffn

@geindex get_flags() (méthode mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage get_flags}@anchor{3645}
@deffn {Méthode} get_flags ()

Return a string specifying the flags that are currently set. If the
message complies with the conventional format, the result is the
concatenation in the following order of zero or one occurrence of each of
@code{'R'}, @code{'O'}, @code{'D'}, @code{'F'}, and @code{'A'}.
@end deffn

@geindex set_flags() (méthode mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage set_flags}@anchor{3646}
@deffn {Méthode} set_flags (flags)

Set the flags specified by `flags' and unset all others. Parameter `flags'
should be the concatenation in any order of zero or more occurrences of
each of @code{'R'}, @code{'O'}, @code{'D'}, @code{'F'}, and @code{'A'}.
@end deffn

@geindex add_flag() (méthode mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage add_flag}@anchor{3647}
@deffn {Méthode} add_flag (flag)

Set the flag(s) specified by `flag' without changing other flags. To add
more than one flag at a time, `flag' may be a string of more than one
character.
@end deffn

@geindex remove_flag() (méthode mailbox.mboxMessage)
@anchor{library/mailbox mailbox mboxMessage remove_flag}@anchor{3648}
@deffn {Méthode} remove_flag (flag)

Unset the flag(s) specified by `flag' without changing other flags. To
remove more than one flag at a time, `flag' maybe a string of more than
one character.
@end deffn
@end deffn

When an @code{mboxMessage} instance is created based upon a
@ref{35fd,,MaildirMessage} instance, a "From " line is generated based upon the
@ref{35fd,,MaildirMessage} instance's delivery date, and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{35fd,,MaildirMessage} state

@item

R flag

@tab

S flag

@item

O flag

@tab

"cur" subdirectory

@item

D flag

@tab

T flag

@item

F flag

@tab

F flag

@item

A flag

@tab

R flag

@end multitable


When an @code{mboxMessage} instance is created based upon an
@ref{361b,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{361b,,MHMessage} state

@item

R flag and O flag

@tab

no "unseen" sequence

@item

O flag

@tab

"unseen" sequence

@item

F flag

@tab

"flagged" sequence

@item

A flag

@tab

"replied" sequence

@end multitable


When an @code{mboxMessage} instance is created based upon a
@ref{362e,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{362e,,BabylMessage} state

@item

R flag and O flag

@tab

no "unseen" label

@item

O flag

@tab

"unseen" label

@item

D flag

@tab

"deleted" label

@item

A flag

@tab

"answered" label

@end multitable


When a @code{mboxMessage} instance is created based upon an
@ref{3635,,MMDFMessage}
instance, the "From " line is copied and all flags directly correspond:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{3635,,MMDFMessage} state

@item

R flag

@tab

R flag

@item

O flag

@tab

O flag

@item

D flag

@tab

D flag

@item

F flag

@tab

F flag

@item

A flag

@tab

A flag

@end multitable


@node MHMessage objects,BabylMessage objects,mboxMessage objects,Message objects
@anchor{library/mailbox mailbox-mhmessage}@anchor{3649}@anchor{library/mailbox mhmessage-objects}@anchor{364a}
@subsubsection @code{MHMessage} objects


@geindex MHMessage (classe dans mailbox)
@anchor{library/mailbox mailbox MHMessage}@anchor{361b}
@deffn {Classe} mailbox.MHMessage (message=None)

A message with MH-specific behaviors. Parameter `message' has the same meaning
as with the @ref{122f,,Message} constructor.

MH messages do not support marks or flags in the traditional sense, but they
do support sequences, which are logical groupings of arbitrary messages. Some
mail reading programs (although not the standard @code{mh} and
@code{nmh}) use sequences in much the same way flags are used with other
formats, as follows:


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Séquence

@tab

Explication

@item

unseen

@tab

Not read, but previously detected by MUA

@item

replied

@tab

Replied to

@item

flagged

@tab

Marked as important

@end multitable


@code{MHMessage} instances offer the following methods:

@geindex get_sequences() (méthode mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage get_sequences}@anchor{364b}
@deffn {Méthode} get_sequences ()

Return a list of the names of sequences that include this message.
@end deffn

@geindex set_sequences() (méthode mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage set_sequences}@anchor{364c}
@deffn {Méthode} set_sequences (sequences)

Set the list of sequences that include this message.
@end deffn

@geindex add_sequence() (méthode mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage add_sequence}@anchor{364d}
@deffn {Méthode} add_sequence (sequence)

Add `sequence' to the list of sequences that include this message.
@end deffn

@geindex remove_sequence() (méthode mailbox.MHMessage)
@anchor{library/mailbox mailbox MHMessage remove_sequence}@anchor{364e}
@deffn {Méthode} remove_sequence (sequence)

Remove `sequence' from the list of sequences that include this message.
@end deffn
@end deffn

When an @code{MHMessage} instance is created based upon a
@ref{35fd,,MaildirMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{35fd,,MaildirMessage} state

@item

"unseen" sequence

@tab

no S flag

@item

"replied" sequence

@tab

R flag

@item

"flagged" sequence

@tab

F flag

@end multitable


When an @code{MHMessage} instance is created based upon an
@ref{34b8,,mboxMessage} or @ref{3635,,MMDFMessage} instance, the @code{Status}
and @code{X-Status} headers are omitted and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{34b8,,mboxMessage} or @ref{3635,,MMDFMessage}
state

@item

"unseen" sequence

@tab

no R flag

@item

"replied" sequence

@tab

A flag

@item

"flagged" sequence

@tab

F flag

@end multitable


When an @code{MHMessage} instance is created based upon a
@ref{362e,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{362e,,BabylMessage} state

@item

"unseen" sequence

@tab

"unseen" label

@item

"replied" sequence

@tab

"answered" label

@end multitable


@node BabylMessage objects,MMDFMessage objects,MHMessage objects,Message objects
@anchor{library/mailbox babylmessage-objects}@anchor{364f}@anchor{library/mailbox mailbox-babylmessage}@anchor{3650}
@subsubsection @code{BabylMessage} objects


@geindex BabylMessage (classe dans mailbox)
@anchor{library/mailbox mailbox BabylMessage}@anchor{362e}
@deffn {Classe} mailbox.BabylMessage (message=None)

A message with Babyl-specific behaviors. Parameter `message' has the same
meaning as with the @ref{122f,,Message} constructor.

Certain message labels, called `attributes', are defined by convention
to have special meanings. The attributes are as follows:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Label

@tab

Explication

@item

unseen

@tab

Not read, but previously detected by MUA

@item

deleted

@tab

Marked for subsequent deletion

@item

filed

@tab

Copied to another file or mailbox

@item

answered

@tab

Replied to

@item

forwarded

@tab

Forwarded

@item

edited

@tab

Modified by the user

@item

resent

@tab

Resent

@end multitable


By default, Rmail displays only visible headers. The @code{BabylMessage}
class, though, uses the original headers because they are more
complete. Visible headers may be accessed explicitly if desired.

@code{BabylMessage} instances offer the following methods:

@geindex get_labels() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage get_labels}@anchor{3651}
@deffn {Méthode} get_labels ()

Return a list of labels on the message.
@end deffn

@geindex set_labels() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage set_labels}@anchor{3652}
@deffn {Méthode} set_labels (labels)

Set the list of labels on the message to `labels'.
@end deffn

@geindex add_label() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage add_label}@anchor{3653}
@deffn {Méthode} add_label (label)

Add `label' to the list of labels on the message.
@end deffn

@geindex remove_label() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage remove_label}@anchor{3654}
@deffn {Méthode} remove_label (label)

Remove `label' from the list of labels on the message.
@end deffn

@geindex get_visible() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage get_visible}@anchor{3655}
@deffn {Méthode} get_visible ()

Return a @ref{122f,,Message} instance whose headers are the message's
visible headers and whose body is empty.
@end deffn

@geindex set_visible() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage set_visible}@anchor{3656}
@deffn {Méthode} set_visible (visible)

Set the message's visible headers to be the same as the headers in
`message'.  Parameter `visible' should be a @ref{122f,,Message} instance, an
@ref{279,,email.message.Message} instance, a string, or a file-like object
(which should be open in text mode).
@end deffn

@geindex update_visible() (méthode mailbox.BabylMessage)
@anchor{library/mailbox mailbox BabylMessage update_visible}@anchor{3657}
@deffn {Méthode} update_visible ()

When a @code{BabylMessage} instance's original headers are modified, the
visible headers are not automatically modified to correspond. This method
updates the visible headers as follows: each visible header with a
corresponding original header is set to the value of the original header,
each visible header without a corresponding original header is removed,
and any of @code{Date}, @code{From}, @code{Reply-To},
@code{To}, @code{CC}, and @code{Subject} that are
present in the original headers but not the visible headers are added to
the visible headers.
@end deffn
@end deffn

When a @code{BabylMessage} instance is created based upon a
@ref{35fd,,MaildirMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{35fd,,MaildirMessage} state

@item

"unseen" label

@tab

no S flag

@item

"deleted" label

@tab

T flag

@item

"answered" label

@tab

R flag

@item

"forwarded" label

@tab

P flag

@end multitable


When a @code{BabylMessage} instance is created based upon an
@ref{34b8,,mboxMessage} or @ref{3635,,MMDFMessage} instance, the @code{Status}
and @code{X-Status} headers are omitted and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{34b8,,mboxMessage} or @ref{3635,,MMDFMessage}
state

@item

"unseen" label

@tab

no R flag

@item

"deleted" label

@tab

D flag

@item

"answered" label

@tab

A flag

@end multitable


When a @code{BabylMessage} instance is created based upon an
@ref{361b,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{361b,,MHMessage} state

@item

"unseen" label

@tab

"unseen" sequence

@item

"answered" label

@tab

"replied" sequence

@end multitable


@node MMDFMessage objects,,BabylMessage objects,Message objects
@anchor{library/mailbox mailbox-mmdfmessage}@anchor{3658}@anchor{library/mailbox mmdfmessage-objects}@anchor{3659}
@subsubsection @code{MMDFMessage} objects


@geindex MMDFMessage (classe dans mailbox)
@anchor{library/mailbox mailbox MMDFMessage}@anchor{3635}
@deffn {Classe} mailbox.MMDFMessage (message=None)

Un message avec des comportements spécifiques à `MMDF'. Le paramètre `message' a le même sens que pour le constructeur de @ref{122f,,Message}.

Comme pour le message d'une boîte de courriel `mbox', les messages `MMDF' sont stockés avec l'adresse de l'expéditeur et la date d'expédition dans la ligne initiale commençant avec « From ». De même, les options indiquant l'état du message sont stockées dans les en-têtes @code{Status} et @code{X-Status}.

Les options conventionnelles des messages `MMDF' sont identiques à celles de message `mbox' et sont les suivantes :


@multitable {xxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@tab

Explication

@item

R

@tab

Read

@tab

Read

@item

O

@tab

Old

@tab

Previously detected by MUA

@item

D

@tab

Deleted

@tab

Marked for subsequent deletion

@item

F

@tab

Flagged

@tab

Marked as important

@item

A

@tab

Answered

@tab

Replied to

@end multitable


The "R" and "O" flags are stored in the @code{Status} header, and the
"D", "F", and "A" flags are stored in the @code{X-Status} header. The
flags and headers typically appear in the order mentioned.

@code{MMDFMessage} instances offer the following methods, which are
identical to those offered by @ref{34b8,,mboxMessage}:

@geindex get_from() (méthode mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage get_from}@anchor{365a}
@deffn {Méthode} get_from ()

Return a string representing the "From " line that marks the start of the
message in an mbox mailbox. The leading "From " and the trailing newline
are excluded.
@end deffn

@geindex set_from() (méthode mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage set_from}@anchor{365b}
@deffn {Méthode} set_from (from_, time_=None)

Set the "From " line to `from_', which should be specified without a
leading "From " or trailing newline. For convenience, `time_' may be
specified and will be formatted appropriately and appended to `from_'. If
`time_' is specified, it should be a @ref{cd8,,time.struct_time} instance, a
tuple suitable for passing to @ref{11c6,,time.strftime()}, or @code{True} (to use
@ref{119d,,time.gmtime()}).
@end deffn

@geindex get_flags() (méthode mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage get_flags}@anchor{365c}
@deffn {Méthode} get_flags ()

Return a string specifying the flags that are currently set. If the
message complies with the conventional format, the result is the
concatenation in the following order of zero or one occurrence of each of
@code{'R'}, @code{'O'}, @code{'D'}, @code{'F'}, and @code{'A'}.
@end deffn

@geindex set_flags() (méthode mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage set_flags}@anchor{365d}
@deffn {Méthode} set_flags (flags)

Set the flags specified by `flags' and unset all others. Parameter `flags'
should be the concatenation in any order of zero or more occurrences of
each of @code{'R'}, @code{'O'}, @code{'D'}, @code{'F'}, and @code{'A'}.
@end deffn

@geindex add_flag() (méthode mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage add_flag}@anchor{365e}
@deffn {Méthode} add_flag (flag)

Set the flag(s) specified by `flag' without changing other flags. To add
more than one flag at a time, `flag' may be a string of more than one
character.
@end deffn

@geindex remove_flag() (méthode mailbox.MMDFMessage)
@anchor{library/mailbox mailbox MMDFMessage remove_flag}@anchor{365f}
@deffn {Méthode} remove_flag (flag)

Unset the flag(s) specified by `flag' without changing other flags. To
remove more than one flag at a time, `flag' maybe a string of more than
one character.
@end deffn
@end deffn

When an @code{MMDFMessage} instance is created based upon a
@ref{35fd,,MaildirMessage} instance, a "From " line is generated based upon the
@ref{35fd,,MaildirMessage} instance's delivery date, and the following conversions
take place:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{35fd,,MaildirMessage} state

@item

R flag

@tab

S flag

@item

O flag

@tab

"cur" subdirectory

@item

D flag

@tab

T flag

@item

F flag

@tab

F flag

@item

A flag

@tab

R flag

@end multitable


When an @code{MMDFMessage} instance is created based upon an
@ref{361b,,MHMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{361b,,MHMessage} state

@item

R flag and O flag

@tab

no "unseen" sequence

@item

O flag

@tab

"unseen" sequence

@item

F flag

@tab

"flagged" sequence

@item

A flag

@tab

"replied" sequence

@end multitable


When an @code{MMDFMessage} instance is created based upon a
@ref{362e,,BabylMessage} instance, the following conversions take place:


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

@ref{362e,,BabylMessage} state

@item

R flag and O flag

@tab

no "unseen" label

@item

O flag

@tab

"unseen" label

@item

D flag

@tab

"deleted" label

@item

A flag

@tab

"answered" label

@end multitable


When an @code{MMDFMessage} instance is created based upon an
@ref{34b8,,mboxMessage} instance, the "From " line is copied and all flags directly
correspond:


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Resulting state

@tab

état de @ref{34b8,,mboxMessage}

@item

R flag

@tab

R flag

@item

O flag

@tab

O flag

@item

D flag

@tab

D flag

@item

F flag

@tab

F flag

@item

A flag

@tab

A flag

@end multitable


@node Exceptions<18>,Exemples<22>,Message objects,mailbox --- Manipulate mailboxes in various formats
@anchor{library/mailbox exceptions}@anchor{3660}
@subsubsection Exceptions


The following exception classes are defined in the @code{mailbox} module:

@geindex Error
@anchor{library/mailbox mailbox Error}@anchor{3661}
@deffn {Exception} mailbox.Error

Classe de base pour toutes les autres exceptions spécifiques à ce module.
@end deffn

@geindex NoSuchMailboxError
@anchor{library/mailbox mailbox NoSuchMailboxError}@anchor{3601}
@deffn {Exception} mailbox.NoSuchMailboxError

Levée lorsqu'une boîte de courriel est attendue mais introuvable, comme quand on instancie une sous-classe @ref{122b,,Mailbox} avec un chemin qui n'existe pas (et avec le paramètre `create' fixé à @code{False}), ou quand on ouvre un répertoire qui n'existe pas.
@end deffn

@geindex NotEmptyError
@anchor{library/mailbox mailbox NotEmptyError}@anchor{3604}
@deffn {Exception} mailbox.NotEmptyError

Levée lorsqu'une boîte de courriel n'est pas vide mais devrait l'être, comme lorsqu'on supprime un répertoire contenant des messages.
@end deffn

@geindex ExternalClashError
@anchor{library/mailbox mailbox ExternalClashError}@anchor{35f9}
@deffn {Exception} mailbox.ExternalClashError

Raised when some mailbox-related condition beyond the control of the program
causes it to be unable to proceed, such as when failing to acquire a lock that
another program already holds a lock, or when a uniquely generated file name
already exists.
@end deffn

@geindex FormatError
@anchor{library/mailbox mailbox FormatError}@anchor{3662}
@deffn {Exception} mailbox.FormatError

Levée lorsque la donnée dans le fichier ne peut être analysée, comme lorsque l'instance de @ref{163f,,MH} tente de lire un fichier @code{.mh_sequences} corrompu.
@end deffn

@node Exemples<22>,,Exceptions<18>,mailbox --- Manipulate mailboxes in various formats
@anchor{library/mailbox examples}@anchor{3663}@anchor{library/mailbox mailbox-examples}@anchor{3664}
@subsubsection Exemples


Un exemple simple d'affichage de l'objet, qui semble pertinent, de tous les messages d'une boîte de courriel :

@example
import mailbox
for message in mailbox.mbox('~/mbox'):
    subject = message['subject']       # Could possibly be None.
    if subject and 'python' in subject.lower():
        print(subject)
@end example

Cet exemple copie tout le courriel d'une boite de courriel au format  `Babyl' vers une boite de courriel au format `MH', convertissant toute l'information qu'il est possible de convertir du premier format vers le second :

@example
import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
    destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()
@end example

Cet exemple trie le courriel en provenance de plusieurs listes de diffusion vers différentes boîtes de courriel, tout en évitant une corruption à cause de modifications concurrentielles par d'autres programmes, une perte due à une interruption du programme ou un arrêt prématuré causé par des messages mal structurés :

@example
import mailbox
import email.errors

list_names = ('python-list', 'python-dev', 'python-bugs')

boxes = @{name: mailbox.mbox('~/email/%s' % name) for name in list_names@}
inbox = mailbox.Maildir('~/Maildir', factory=None)

for key in inbox.iterkeys():
    try:
        message = inbox[key]
    except email.errors.MessageParseError:
        continue                # The message is malformed. Just leave it.

    for name in list_names:
        list_id = message['list-id']
        if list_id and name in list_id:
            # Get mailbox to use
            box = boxes[name]

            # Write copy to disk before removing original.
            # If there's a crash, you might duplicate a message, but
            # that's better than losing a message completely.
            box.lock()
            box.add(message)
            box.flush()
            box.unlock()

            # Remove original message
            inbox.lock()
            inbox.discard(key)
            inbox.flush()
            inbox.unlock()
            break               # Found destination, so stop looking.

for box in boxes.itervalues():
    box.close()
@end example

@node mimetypes --- Map filenames to MIME types,base64 --- Base16 Base32 Base64 Base85 Data Encodings,mailbox --- Manipulate mailboxes in various formats,Traitement des données provenant d'Internet
@anchor{library/mimetypes doc}@anchor{3665}@anchor{library/mimetypes mimetypes-map-filenames-to-mime-types}@anchor{3666}@anchor{library/mimetypes module-mimetypes}@anchor{8e}
@subsection @code{mimetypes} --- Map filenames to MIME types


@geindex module; mimetypes

`Source code:' Lib/mimetypes.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/mimetypes.py}

@geindex MIME;content type


__________________________________________________________________


The @ref{8e,,mimetypes} module converts between a filename or URL and the MIME type
associated with the filename extension.  Conversions are provided from filename
to MIME type and from MIME type to filename extension; encodings are not
supported for the latter conversion.

The module provides one class and a number of convenience functions. The
functions are the normal interface to this module, but some applications may be
interested in the class as well.

The functions described below provide the primary interface for this module.  If
the module has not been initialized, they will call @ref{3667,,init()} if they rely on
the information @ref{3667,,init()} sets up.

@geindex guess_type() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes guess_type}@anchor{205}
@deffn {Fonction} mimetypes.guess_type (url, strict=True)

@geindex MIME;headers

Guess the type of a file based on its filename, path or URL, given by `url'.
URL can be a string or a @ref{29d,,path-like object}.

The return value is a tuple @code{(type, encoding)} where `type' is @code{None} if the
type can't be guessed (missing or unknown suffix) or a string of the form
@code{'type/subtype'}, usable for a MIME @code{content-type} header.

`encoding' is @code{None} for no encoding or the name of the program used to encode
(e.g. @code{compress} or @code{gzip}). The encoding is suitable for use
as a @code{Content-Encoding} header, `not' as a
@code{Content-Transfer-Encoding} header. The mappings are table driven.
Encoding suffixes are case sensitive; type suffixes are first tried case
sensitively, then case insensitively.

The optional `strict' argument is a flag specifying whether the list of known MIME types
is limited to only the official types registered with IANA@footnote{https://www.iana.org/assignments/media-types/media-types.xhtml}.
When `strict' is @code{True} (the default), only the IANA types are supported; when
`strict' is @code{False}, some additional non-standard but commonly used MIME types
are also recognized.


Modifié dans la version 3.8: Added support for `url' being a @ref{29d,,path-like object}.



Obsolète depuis la version 3.13: Passing a file path instead of URL is @ref{206,,soft deprecated}.
Use @ref{204,,guess_file_type()} for this.

@end deffn

@geindex guess_file_type() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes guess_file_type}@anchor{204}
@deffn {Fonction} mimetypes.guess_file_type (path, *, strict=True)

@geindex MIME;headers

Guess the type of a file based on its path, given by `path'.
Similar to the @ref{205,,guess_type()} function, but accepts a path instead of URL.
Path can be a string, a bytes object or a @ref{29d,,path-like object}.


Ajouté dans la version 3.13.

@end deffn

@geindex guess_all_extensions() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes guess_all_extensions}@anchor{1823}
@deffn {Fonction} mimetypes.guess_all_extensions (type, strict=True)

Guess the extensions for a file based on its MIME type, given by `type'. The
return value is a list of strings giving all possible filename extensions,
including the leading dot (@code{'.'}).  The extensions are not guaranteed to have
been associated with any particular data stream, but would be mapped to the MIME
type `type' by @ref{205,,guess_type()} and @ref{204,,guess_file_type()}.

The optional `strict' argument has the same meaning as with the @ref{205,,guess_type()} function.
@end deffn

@geindex guess_extension() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes guess_extension}@anchor{3668}
@deffn {Fonction} mimetypes.guess_extension (type, strict=True)

Guess the extension for a file based on its MIME type, given by `type'. The
return value is a string giving a filename extension, including the leading dot
(@code{'.'}).  The extension is not guaranteed to have been associated with any
particular data stream, but would be mapped to the MIME type `type' by
@ref{205,,guess_type()} and @ref{204,,guess_file_type()}.
If no extension can be guessed for `type', @code{None} is returned.

The optional `strict' argument has the same meaning as with the @ref{205,,guess_type()} function.
@end deffn

Some additional functions and data items are available for controlling the
behavior of the module.

@geindex init() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes init}@anchor{3667}
@deffn {Fonction} mimetypes.init (files=None)

Initialize the internal data structures.  If given, `files' must be a sequence
of file names which should be used to augment the default type map.  If omitted,
the file names to use are taken from @ref{3669,,knownfiles}; on Windows, the
current registry settings are loaded.  Each file named in `files' or
@ref{3669,,knownfiles} takes precedence over those named before it.  Calling
@ref{3667,,init()} repeatedly is allowed.

Specifying an empty list for `files' will prevent the system defaults from
being applied: only the well-known values will be present from a built-in list.

If `files' is @code{None} the internal data structure is completely rebuilt to its
initial default value. This is a stable operation and will produce the same results
when called multiple times.


Modifié dans la version 3.2: Previously, Windows registry settings were ignored.

@end deffn

@geindex read_mime_types() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes read_mime_types}@anchor{18d0}
@deffn {Fonction} mimetypes.read_mime_types (filename)

Load the type map given in the file `filename', if it exists.  The type map is
returned as a dictionary mapping filename extensions, including the leading dot
(@code{'.'}), to strings of the form @code{'type/subtype'}.  If the file `filename'
does not exist or cannot be read, @code{None} is returned.
@end deffn

@geindex add_type() (dans le module mimetypes)
@anchor{library/mimetypes mimetypes add_type}@anchor{366a}
@deffn {Fonction} mimetypes.add_type (type, ext, strict=True)

Add a mapping from the MIME type `type' to the extension `ext'. When the
extension is already known, the new type will replace the old one. When the type
is already known the extension will be added to the list of known extensions.

When `strict' is @code{True} (the default), the mapping will be added to the
official MIME types, otherwise to the non-standard ones.
@end deffn

@geindex inited (dans le module mimetypes)
@anchor{library/mimetypes mimetypes inited}@anchor{366b}
@deffn {Données} mimetypes.inited

Flag indicating whether or not the global data structures have been initialized.
This is set to @code{True} by @ref{3667,,init()}.
@end deffn

@geindex knownfiles (dans le module mimetypes)
@anchor{library/mimetypes mimetypes knownfiles}@anchor{3669}
@deffn {Données} mimetypes.knownfiles

@geindex file;mime.types

List of type map file names commonly installed.  These files are typically named
@code{mime.types} and are installed in different locations by different
packages.
@end deffn

@geindex suffix_map (dans le module mimetypes)
@anchor{library/mimetypes mimetypes suffix_map}@anchor{366c}
@deffn {Données} mimetypes.suffix_map

Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
encoded files for which the encoding and the type are indicated by the same
extension.  For example, the @code{.tgz} extension is mapped to @code{.tar.gz}
to allow the encoding and type to be recognized separately.
@end deffn

@geindex encodings_map (dans le module mimetypes)
@anchor{library/mimetypes mimetypes encodings_map}@anchor{366d}
@deffn {Données} mimetypes.encodings_map

Dictionary mapping filename extensions to encoding types.
@end deffn

@geindex types_map (dans le module mimetypes)
@anchor{library/mimetypes mimetypes types_map}@anchor{366e}
@deffn {Données} mimetypes.types_map

Dictionary mapping filename extensions to MIME types.
@end deffn

@geindex common_types (dans le module mimetypes)
@anchor{library/mimetypes mimetypes common_types}@anchor{366f}
@deffn {Données} mimetypes.common_types

Dictionary mapping filename extensions to non-standard, but commonly found MIME
types.
@end deffn

Un exemple d'utilisation du module :

@example
>>> import mimetypes
>>> mimetypes.init()
>>> mimetypes.knownfiles
['/etc/mime.types', '/etc/httpd/mime.types', ... ]
>>> mimetypes.suffix_map['.tgz']
'.tar.gz'
>>> mimetypes.encodings_map['.gz']
'gzip'
>>> mimetypes.types_map['.tgz']
'application/x-tar-gz'
@end example

@menu
* MimeTypes Objects:: 

@end menu

@node MimeTypes Objects,,,mimetypes --- Map filenames to MIME types
@anchor{library/mimetypes id1}@anchor{3670}@anchor{library/mimetypes mimetypes-objects}@anchor{3671}
@subsubsection MimeTypes Objects


The @ref{14b1,,MimeTypes} class may be useful for applications which may want more
than one MIME-type database; it provides an interface similar to the one of the
@ref{8e,,mimetypes} module.

@geindex MimeTypes (classe dans mimetypes)
@anchor{library/mimetypes mimetypes MimeTypes}@anchor{14b1}
@deffn {Classe} mimetypes.MimeTypes (filenames=(), strict=True)

This class represents a MIME-types database.  By default, it provides access to
the same database as the rest of this module. The initial database is a copy of
that provided by the module, and may be extended by loading additional
@code{mime.types}-style files into the database using the @ref{3672,,read()} or
@ref{3673,,readfp()} methods.  The mapping dictionaries may also be cleared before
loading additional data if the default data is not desired.

The optional `filenames' parameter can be used to cause additional files to be
loaded "on top" of the default database.

@geindex suffix_map (attribut mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes suffix_map}@anchor{3674}
@deffn {Attribut} suffix_map

Dictionary mapping suffixes to suffixes.  This is used to allow recognition of
encoded files for which the encoding and the type are indicated by the same
extension.  For example, the @code{.tgz} extension is mapped to @code{.tar.gz}
to allow the encoding and type to be recognized separately.  This is initially a
copy of the global @ref{366c,,suffix_map} defined in the module.
@end deffn

@geindex encodings_map (attribut mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes encodings_map}@anchor{3675}
@deffn {Attribut} encodings_map

Dictionary mapping filename extensions to encoding types.  This is initially a
copy of the global @ref{366d,,encodings_map} defined in the module.
@end deffn

@geindex types_map (attribut mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes types_map}@anchor{3676}
@deffn {Attribut} types_map

Tuple containing two dictionaries, mapping filename extensions to MIME types:
the first dictionary is for the non-standards types and the second one is for
the standard types. They are initialized by @ref{366f,,common_types} and
@ref{366e,,types_map}.
@end deffn

@geindex types_map_inv (attribut mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes types_map_inv}@anchor{3677}
@deffn {Attribut} types_map_inv

Tuple containing two dictionaries, mapping MIME types to a list of filename
extensions: the first dictionary is for the non-standards types and the
second one is for the standard types. They are initialized by
@ref{366f,,common_types} and @ref{366e,,types_map}.
@end deffn

@geindex guess_extension() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_extension}@anchor{3678}
@deffn {Méthode} guess_extension (type, strict=True)

Similar to the @ref{3668,,guess_extension()} function, using the tables stored as part
of the object.
@end deffn

@geindex guess_type() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_type}@anchor{19c6}
@deffn {Méthode} guess_type (url, strict=True)

Similar to the @ref{205,,guess_type()} function, using the tables stored as part of
the object.
@end deffn

@geindex guess_file_type() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_file_type}@anchor{3679}
@deffn {Méthode} guess_file_type (path, *, strict=True)

Similar to the @ref{204,,guess_file_type()} function, using the tables stored
as part of the object.


Ajouté dans la version 3.13.

@end deffn

@geindex guess_all_extensions() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes guess_all_extensions}@anchor{367a}
@deffn {Méthode} guess_all_extensions (type, strict=True)

Similar to the @ref{1823,,guess_all_extensions()} function, using the tables stored
as part of the object.
@end deffn

@geindex read() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes read}@anchor{3672}
@deffn {Méthode} read (filename, strict=True)

Load MIME information from a file named `filename'.  This uses @ref{3673,,readfp()} to
parse the file.

If `strict' is @code{True}, information will be added to list of standard types,
else to the list of non-standard types.
@end deffn

@geindex readfp() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes readfp}@anchor{3673}
@deffn {Méthode} readfp (fp, strict=True)

Load MIME type information from an open file `fp'.  The file must have the format of
the standard @code{mime.types} files.

If `strict' is @code{True}, information will be added to the list of standard
types, else to the list of non-standard types.
@end deffn

@geindex read_windows_registry() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes read_windows_registry}@anchor{367b}
@deffn {Méthode} read_windows_registry (strict=True)

Load MIME type information from the Windows registry.

@ref{1ce0,,Availability}: Windows.

If `strict' is @code{True}, information will be added to the list of standard
types, else to the list of non-standard types.


Ajouté dans la version 3.2.

@end deffn

@geindex add_type() (méthode mimetypes.MimeTypes)
@anchor{library/mimetypes mimetypes MimeTypes add_type}@anchor{367c}
@deffn {Méthode} add_type (type, ext, strict=True)

Add a mapping from the MIME type `type' to the extension `ext'. When the
extension is already known, the new type will replace the old one. When the type
is already known the extension will be added to the list of known extensions.

When `strict' is @code{True} (the default), the mapping will be added to the
official MIME types, otherwise to the non-standard ones.
@end deffn
@end deffn

@node base64 --- Base16 Base32 Base64 Base85 Data Encodings,binascii --- Convert between binary and ASCII,mimetypes --- Map filenames to MIME types,Traitement des données provenant d'Internet
@anchor{library/base64 doc}@anchor{367d}@anchor{library/base64 base64-base16-base32-base64-base85-data-encodings}@anchor{367e}@anchor{library/base64 module-base64}@anchor{e}
@subsection @code{base64} --- Base16, Base32, Base64, Base85 Data Encodings


@geindex module; base64

`Code source :' Lib/base64.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/base64.py}

@geindex base64;encoding
@geindex MIME;base64 encoding


__________________________________________________________________


This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data.
It provides encoding and decoding functions for the encodings specified in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}, which defines the Base16, Base32, and Base64 algorithms,
and for the de-facto standard Ascii85 and Base85 encodings.

The 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} encodings are suitable for encoding binary data so that it can be
safely sent by email, used as parts of URLs, or included as part of an HTTP
POST request.  The encoding algorithm is not the same as the
@code{uuencode} program.

There are two interfaces provided by this module.  The modern interface
supports encoding @ref{d1b,,bytes-like objects} to ASCII
@ref{1bd,,bytes}, and decoding @ref{d1b,,bytes-like objects} or
strings containing ASCII to @ref{1bd,,bytes}.  Both base-64 alphabets
defined in 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} (normal, and URL- and filesystem-safe) are supported.

L'interface historique ne permet pas le décodage des chaînes de caractères mais fournit des fonctions permettant d'encoder et décoder depuis et vers des @ref{11a0,,objets fichiers}. Elle ne gère que l'alphabet base64 standard et ajoute une nouvelle ligne tous les 76 caractères, comme spécifié par la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}. Notez que le paquet @ref{3b,,email} est probablement ce que vous cherchez si vous souhaitez une implémentation de la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html}.


Modifié dans la version 3.3: Les chaînes de caractères Unicode contenant uniquement des caractères ASCII sont désormais acceptées par les fonctions de décodage de l'interface moderne.



Modifié dans la version 3.4: Tous les @ref{d1b,,objets octet-compatibles} sont désormais acceptés par l'ensemble des fonctions d'encodage et de décodage de ce module. La gestion de Ascii85/base85 a été ajoutée.


L'interface moderne propose :

@geindex b64encode() (dans le module base64)
@anchor{library/base64 base64 b64encode}@anchor{367f}
@deffn {Fonction} base64.b64encode (s, altchars=None)

Encode un @ref{d1b,,objet octet-compatible} `s' en utilisant l'algorithme base64 et renvoie les @ref{1bd,,bytes} encodés.

Optional `altchars' must be a @ref{d1b,,bytes-like object} of length 2 which
specifies an alternative alphabet for the @code{+} and @code{/} characters.
This allows an application to e.g. generate URL or filesystem safe Base64
strings.  The default is @code{None}, for which the standard Base64 alphabet is used.

May assert or raise a @ref{1ff,,ValueError} if the length of `altchars' is not 2.  Raises a
@ref{522,,TypeError} if `altchars' is not a @ref{d1b,,bytes-like object}.
@end deffn

@geindex b64decode() (dans le module base64)
@anchor{library/base64 base64 b64decode}@anchor{1935}
@deffn {Fonction} base64.b64decode (s, altchars=None, validate=False)

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `s' encodée en base64 et renvoie les @ref{1bd,,bytes} décodés.

Optional `altchars' must be a @ref{d1b,,bytes-like object} or ASCII string
of length 2 which specifies the alternative alphabet used instead of the
@code{+} and @code{/} characters.

Une exception @ref{100f,,binascii.Error} est levée si `s' n'est pas remplie à une longueur attendue.

Si `validate' est @code{False} (par défaut), les caractères qui ne sont ni dans l'alphabet base64 normal, ni dans l'alphabet alternatif, sont ignorés avant la vérification de la longueur du remplissage. Si `validate' est @code{True}, les caractères hors de l'alphabet de l'entrée produisent une @ref{100f,,binascii.Error}.

For more information about the strict base64 check, see @ref{15b6,,binascii.a2b_base64()}

May assert or raise a @ref{1ff,,ValueError} if the length of `altchars' is not 2.
@end deffn

@geindex standard_b64encode() (dans le module base64)
@anchor{library/base64 base64 standard_b64encode}@anchor{3680}
@deffn {Fonction} base64.standard_b64encode (s)

Encode un @ref{d1b,,objet octet-compatible} `s' en utilisant l'alphabet standard base64 et renvoie les @ref{1bd,,bytes} encodés.
@end deffn

@geindex standard_b64decode() (dans le module base64)
@anchor{library/base64 base64 standard_b64decode}@anchor{3681}
@deffn {Fonction} base64.standard_b64decode (s)

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `s' utilisant l'alphabet base64 standard et renvoie les @ref{1bd,,bytes} décodés.
@end deffn

@geindex urlsafe_b64encode() (dans le module base64)
@anchor{library/base64 base64 urlsafe_b64encode}@anchor{3682}
@deffn {Fonction} base64.urlsafe_b64encode (s)

Encode un @ref{d1b,,objet byte-compatible} `s' en utilisant un alphabet sûr pour les URL et systèmes de fichiers qui substitue @code{-} et @code{_} à @code{+} et @code{/} dans l'alphabet standard base64 et renvoie les @ref{1bd,,bytes} encodés.
@end deffn

@geindex urlsafe_b64decode() (dans le module base64)
@anchor{library/base64 base64 urlsafe_b64decode}@anchor{3683}
@deffn {Fonction} base64.urlsafe_b64decode (s)

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `s' utilisant un alphabet sûr pour les URL et systèmes de fichiers qui substitue @code{-} et @code{_} à @code{+} et @code{/} dans l'alphabet standard base64 et renvoie les @ref{1bd,,bytes} décodés.
@end deffn

@geindex b32encode() (dans le module base64)
@anchor{library/base64 base64 b32encode}@anchor{3684}
@deffn {Fonction} base64.b32encode (s)

Encode un @ref{d1b,,objet byte-compatible} `s' en utilisant l'algorithme base32 et renvoie les @ref{1bd,,bytes} encodés.
@end deffn

@geindex b32decode() (dans le module base64)
@anchor{library/base64 base64 b32decode}@anchor{100e}
@deffn {Fonction} base64.b32decode (s, casefold=False, map01=None)

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `s' encodé en base32 et renvoie les @ref{1bd,,bytes} décodés.

L'option `casefold' est un drapeau spécifiant si l'utilisation d'un alphabet en minuscules est acceptable comme entrée. Pour des raisons de sécurité, cette option est à @code{False} par défaut.

@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} allows for optional mapping of the digit 0 (zero) to the letter O
(oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
or letter L (el).  The optional argument `map01' when not @code{None}, specifies
which letter the digit 1 should be mapped to (when `map01' is not @code{None}, the
digit 0 is always mapped to the letter O).  For security purposes the default is
@code{None}, so that 0 and 1 are not allowed in the input.

Une exception @ref{100f,,binascii.Error} est levée si `s' n'est pas remplie à une longueur attendue ou si elle contient des caractères hors de l'alphabet.
@end deffn

@geindex b32hexencode() (dans le module base64)
@anchor{library/base64 base64 b32hexencode}@anchor{7cd}
@deffn {Fonction} base64.b32hexencode (s)

Similar to @ref{3684,,b32encode()} but uses the Extended Hex Alphabet, as defined in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.


Ajouté dans la version 3.10.

@end deffn

@geindex b32hexdecode() (dans le module base64)
@anchor{library/base64 base64 b32hexdecode}@anchor{7ce}
@deffn {Fonction} base64.b32hexdecode (s, casefold=False)

Similar to @ref{100e,,b32decode()} but uses the Extended Hex Alphabet, as defined in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}.

This version does not allow the digit 0 (zero) to the letter O (oh) and digit
1 (one) to either the letter I (eye) or letter L (el) mappings, all these
characters are included in the Extended Hex Alphabet and are not
interchangeable.


Ajouté dans la version 3.10.

@end deffn

@geindex b16encode() (dans le module base64)
@anchor{library/base64 base64 b16encode}@anchor{3685}
@deffn {Fonction} base64.b16encode (s)

Encode un @ref{d1b,,objet byte-compatible} `s' en utilisant l'algorithme base16 et renvoie les @ref{1bd,,bytes} encodés.
@end deffn

@geindex b16decode() (dans le module base64)
@anchor{library/base64 base64 b16decode}@anchor{3686}
@deffn {Fonction} base64.b16decode (s, casefold=False)

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `s' encodé en base16 et renvoie les @ref{1bd,,bytes} décodés.

L'option `casefold' est un drapeau spécifiant si l'utilisation d'un alphabet en minuscules est acceptable comme entrée. Pour des raisons de sécurité, cette option est à @code{False} par défaut.

Une exception @ref{100f,,binascii.Error} est levée si `s' n'est pas remplie à une longueur attendue ou si elle contient des caractères hors de l'alphabet.
@end deffn

@geindex a85encode() (dans le module base64)
@anchor{library/base64 base64 a85encode}@anchor{f09}
@deffn {Fonction} base64.a85encode (b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Encode un @ref{d1b,,objet byte-compatible} `s' en utilisant l'algorithme Ascii85 et renvoie les @ref{1bd,,bytes} encodés.

L'option `foldspaces' permet d'utiliser la séquence spéciale 'y' à la place de quatre espaces consécutives (ASCII @code{0x20}) comme  pris en charge par `btoa'. Cette fonctionnalité n'est pas gérée par l'encodage « standard » Ascii85.

`wrapcol' controls whether the output should have newline (@code{b'\n'})
characters added to it. If this is non-zero, each output line will be
at most this many characters long, excluding the trailing newline.

`pad' spécifie l'ajout de caractères de remplissage (`padding' en anglais) à l'entrée jusqu'à ce que sa longueur soit un multiple de 4 avant encodage. Notez que l'implémentation @code{btoa} effectue systématiquement ce remplissage.

`adobe' contrôle si oui ou non la séquence encodée d'octets est encadrée par @code{<~} et @code{~>} comme utilisé dans l'implémentation Adobe.


Ajouté dans la version 3.4.

@end deffn

@geindex a85decode() (dans le module base64)
@anchor{library/base64 base64 a85decode}@anchor{f0a}
@deffn {Fonction} base64.a85decode (b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `s' encodé en Ascii85 et renvoie les @ref{1bd,,bytes} décodés.

L'option `foldspaces' permet d'utiliser la séquence spéciale 'y' à la place de quatre espaces consécutives (ASCII @code{0x20}) comme  pris en charge par `btoa'. Cette fonctionnalité n'est pas gérée par l'encodage « standard » Ascii85.

`adobe' indique si la séquence d'entrée utilise le format Adobe Ascii85 (c'est-à-dire utilise l'encadrement par @code{<~} et @code{~>}).

`ignorechars' doit être un @ref{d1b,,bytes-like object} ou une chaîne ASCII contenant des caractères à ignorer dans l'entrée. Il ne doit contenir que des caractères d'espacement et contient par défaut l'ensemble des caractères d'espacement de l'alphabet ASCII.


Ajouté dans la version 3.4.

@end deffn

@geindex b85encode() (dans le module base64)
@anchor{library/base64 base64 b85encode}@anchor{f0b}
@deffn {Fonction} base64.b85encode (b, pad=False)

Encode un @ref{d1b,,objet byte-compatible} `s' en utilisant l'algorithme base85 (tel qu'utilisé par exemple par le programme `git-diff' sur des données binaires) et renvoie les @ref{1bd,,bytes} encodés.

Si `pad' est vrai, des caractères de remplissage @code{b'\0'} (`padding' en anglais) sont ajoutés à l'entrée jusqu'à ce que sa longueur soit un multiple de 4 octets avant encodage.


Ajouté dans la version 3.4.

@end deffn

@geindex b85decode() (dans le module base64)
@anchor{library/base64 base64 b85decode}@anchor{f0c}
@deffn {Fonction} base64.b85decode (b)

Décode un @ref{d1b,,objet octet-compatible} ou une chaîne de caractères ASCII `b' encodé en base85 et renvoie les @ref{1bd,,bytes} décodés. Les caractères de remplissage sont implicitement retirés si nécessaire.


Ajouté dans la version 3.4.

@end deffn

@geindex z85encode() (dans le module base64)
@anchor{library/base64 base64 z85encode}@anchor{14e}
@deffn {Fonction} base64.z85encode (s)

Encode the @ref{d1b,,bytes-like object} `s' using Z85 (as used in ZeroMQ)
and return the encoded @ref{1bd,,bytes}.  See Z85 specification@footnote{https://rfc.zeromq.org/spec/32/} for more information.


Ajouté dans la version 3.13.

@end deffn

@geindex z85decode() (dans le module base64)
@anchor{library/base64 base64 z85decode}@anchor{14f}
@deffn {Fonction} base64.z85decode (s)

Decode the Z85-encoded @ref{d1b,,bytes-like object} or ASCII string `s' and
return the decoded @ref{1bd,,bytes}.  See Z85 specification@footnote{https://rfc.zeromq.org/spec/32/} for more information.


Ajouté dans la version 3.13.

@end deffn

L'interface historique :

@geindex decode() (dans le module base64)
@anchor{library/base64 base64 decode}@anchor{3687}
@deffn {Fonction} base64.decode (input, output)

Décode le contenu d'un fichier binaire `input' et écrit les données binaires résultantes dans le fichier `output'. `input' et `output' doivent être des @ref{11a0,,objets fichiers}. `input' est lu jusqu'à ce que @code{input.readline()} renvoie un objet `bytes' vide.
@end deffn

@geindex decodebytes() (dans le module base64)
@anchor{library/base64 base64 decodebytes}@anchor{941}
@deffn {Fonction} base64.decodebytes (s)

Décode un @ref{d1b,,objet octet-compatible} `s' devant contenir une ou plusieurs lignes de données encodées en base64 et renvoie les @ref{1bd,,bytes} décodés.


Ajouté dans la version 3.1.

@end deffn

@geindex encode() (dans le module base64)
@anchor{library/base64 base64 encode}@anchor{3688}
@deffn {Fonction} base64.encode (input, output)

Encode le contenu du fichier binaire `input' et écrit les données encodées en base64 résultantes dans le fichier `output. *input' et `output' doivent être des @ref{11a0,,objets fichiers}. `input' est lu jusqu'à ce que @code{input.readline()} renvoie un objet `bytes' vide. @ref{3688,,encode()} insère un caractère de saut de ligne (@code{b'\n'}) tous les 76 octets de sortie et assure que celle-ci se termine par une nouvelle ligne, comme spécifié par la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} (MIME).
@end deffn

@geindex encodebytes() (dans le module base64)
@anchor{library/base64 base64 encodebytes}@anchor{940}
@deffn {Fonction} base64.encodebytes (s)

Encode un @ref{d1b,,objet octet-compatible} `s' pouvant contenir des données binaires arbitraires et renvoie les @ref{1bd,,bytes} contenant les données encodées en base64. Un caractère de saut de ligne (@code{b'\n'}) est inséré tous les 76 octets de sortie et celle-ci se termine par une nouvelle ligne, comme spécifié par la 
@geindex RFC; RFC 2045
RFC 2045@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html} (MIME).


Ajouté dans la version 3.1.

@end deffn

Un exemple d'utilisation du module :

@example
>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'
@end example

@menu
* Considérations de sécurité: Considérations de sécurité<2>. 

@end menu

@node Considérations de sécurité<2>,,,base64 --- Base16 Base32 Base64 Base85 Data Encodings
@anchor{library/base64 base64-security}@anchor{3689}@anchor{library/base64 security-considerations}@anchor{368a}
@subsubsection Considérations de sécurité


A new security considerations section was added to 
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html} (section 12); it's
recommended to review the security section for any code deployed to production.


@subsubheading Voir aussi



@table @asis

@item Module @ref{10,,binascii}

Module secondaire contenant les conversions ASCII vers binaire et binaire vers ASCII.

@geindex RFC; RFC 1521

@item RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html} — MIME (`Multipurpose Internet Mail Extensions') `Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies'

La Section 5.2, "`Base64 Content-Transfer-Encoding'", donne la définition de l'encodage base64.
@end table


@node binascii --- Convert between binary and ASCII,quopri --- Encode and decode MIME quoted-printable data,base64 --- Base16 Base32 Base64 Base85 Data Encodings,Traitement des données provenant d'Internet
@anchor{library/binascii doc}@anchor{368b}@anchor{library/binascii binascii-convert-between-binary-and-ascii}@anchor{368c}@anchor{library/binascii module-binascii}@anchor{10}
@subsection @code{binascii} --- Convert between binary and ASCII


@geindex module; binascii

@geindex module;base64


__________________________________________________________________


The @ref{10,,binascii} module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you will not
use these functions directly but use wrapper modules like
@ref{e,,base64} instead. The @ref{10,,binascii} module contains
low-level functions written in C for greater speed that are used by the
higher-level modules.

@cartouche
@quotation Note 
La fonction @code{a2b_*} accepte des chaînes de caractères contenant seulement des caractères ASCII. D’autres fonctions acceptent seulement des objets @ref{d1b,,bytes et similaire} (tel que @ref{1bd,,bytes}, @ref{528,,bytearray} et autres objets qui supportent le protocole tampon).


Modifié dans la version 3.3: Les chaines de caractères `unicode' seulement composées de caractères ASCII sont désormais acceptées par les fonctions @code{a2b_*}.

@end quotation
@end cartouche

Le module @ref{10,,binascii} définit les fonctions suivantes :

@geindex a2b_uu() (dans le module binascii)
@anchor{library/binascii binascii a2b_uu}@anchor{368d}
@deffn {Fonction} binascii.a2b_uu (string)

Convertit une seule ligne de donnée `uuencoded' en binaire et renvoie la donnée binaire. Les lignes contiennent normalement 45 octets (binaire), sauf pour la dernière ligne. Il se peut que la ligne de donnée soit suivie d’un espace blanc.
@end deffn

@geindex b2a_uu() (dans le module binascii)
@anchor{library/binascii binascii b2a_uu}@anchor{b0f}
@deffn {Fonction} binascii.b2a_uu (data, *, backtick=False)

Convertit les données binaires en une ligne de caractères ASCII, la valeur renvoyée est la ligne convertie incluant un caractère de nouvelle ligne. La longueur de `data' doit être au maximum de 45. Si `backtick' est vraie, les zéros sont représentés par @code{'`'} plutôt que par des espaces.


Modifié dans la version 3.7: Ajout du paramètre `backtick'.

@end deffn

@geindex a2b_base64() (dans le module binascii)
@anchor{library/binascii binascii a2b_base64}@anchor{15b6}
@deffn {Fonction} binascii.a2b_base64 (string, /, *, strict_mode=False)

Convertit un bloc de donnée en `base64' en binaire et renvoie la donnée binaire. Plus d’une ligne peut être passé à la fois.

If `strict_mode' is true, only valid base64 data will be converted. Invalid base64
data will raise @ref{100f,,binascii.Error}.

Valid base64:


@itemize *

@item 
Conforms to 
@geindex RFC; RFC 3548
RFC 3548@footnote{https://datatracker.ietf.org/doc/html/rfc3548.html}.

@item 
Contains only characters from the base64 alphabet.

@item 
Contains no excess data after padding (including excess padding, newlines, etc.).

@item 
Does not start with a padding.
@end itemize


Modifié dans la version 3.11: Added the `strict_mode' parameter.

@end deffn

@geindex b2a_base64() (dans le module binascii)
@anchor{library/binascii binascii b2a_base64}@anchor{c6d}
@deffn {Fonction} binascii.b2a_base64 (data, *, newline=True)

Convertit les données binaires en une ligne de caractères ASCII en codage base 64. La valeur de renvoyée et la ligne convertie, incluant un caractère de nouvelle ligne si `newline' est vraie. La sortie de cette fonction se conforme à 
@geindex RFC; RFC 3548
RFC 3548@footnote{https://datatracker.ietf.org/doc/html/rfc3548.html}.


Modifié dans la version 3.6: Ajout du paramètre `newline'.

@end deffn

@geindex a2b_qp() (dans le module binascii)
@anchor{library/binascii binascii a2b_qp}@anchor{368e}
@deffn {Fonction} binascii.a2b_qp (data, header=False)

Convertit un bloc de données `quoted-printable' en binaire et renvoie les données binaires. Plus d’une ligne peut être passée à la fois. Si l’argument optionnel `header' est présent et vrai, les traits soulignés seront décodés en espaces.
@end deffn

@geindex b2a_qp() (dans le module binascii)
@anchor{library/binascii binascii b2a_qp}@anchor{368f}
@deffn {Fonction} binascii.b2a_qp (data, quotetabs=False, istext=True, header=False)

Convertit les données binaires en ligne(s) de caractères ASCII en codage imprimable entre guillemets. La valeur de retour est lales lignes(s) convertie(s). Si l’argument optionnel `quotetabs' est présent et vrai, toutes les tabulations et espaces seront encodés. Si l’argument optionnel `istext' est présent et faux, les nouvelles lignes ne sont pas encodées mais les espaces de fin de ligne le seront. Si l’argument optionnel `header' est présent et vrai, les espaces vont être encodés comme de traits soulignés selon 
@geindex RFC; RFC 1522
RFC 1522@footnote{https://datatracker.ietf.org/doc/html/rfc1522.html}. Si l’argument optionnel `header' est présent et faux, les caractères de nouvelle ligne seront également encodés ; sinon la conversion de saut de ligne pourrait corrompre le flux de données binaire.
@end deffn

@geindex crc_hqx() (dans le module binascii)
@anchor{library/binascii binascii crc_hqx}@anchor{71e}
@deffn {Fonction} binascii.crc_hqx (data, value)

Calcule une valeur en CRC 16-bit de `data', commençant par `value' comme CRC initial et renvoie le résultat. Ceci utilise le CRC-CCITT polynomial `x'@w{^16} + `x'@w{^12} + `x'@w{^5} + 1, souvent représenté comme `0x1021'. Ce CRC est utilisé dans le format `binhex4'.
@end deffn

@geindex crc32() (dans le module binascii)
@anchor{library/binascii binascii crc32}@anchor{161f}
@deffn {Fonction} binascii.crc32 (data[, value])

Compute CRC-32, the unsigned 32-bit checksum of `data', starting with an
initial CRC of `value'.  The default initial CRC is zero.  The algorithm
is consistent with the ZIP file checksum.  Since the algorithm is designed for
use as a checksum algorithm, it is not suitable for use as a general hash
algorithm.  Use as follows:

@example
print(binascii.crc32(b"hello world"))
# Or, in two pieces:
crc = binascii.crc32(b"hello")
crc = binascii.crc32(b" world", crc)
print('crc32 = @{:#010x@}'.format(crc))
@end example


Modifié dans la version 3.0: Renvoie une valeur non-signée.

@end deffn

@geindex b2a_hex() (dans le module binascii)
@geindex hexlify() (dans le module binascii)
@anchor{library/binascii binascii b2a_hex}@anchor{2399}
@deffn {Fonction} binascii.b2a_hex (data[, sep[, bytes_per_sep=1]])
@anchor{library/binascii binascii hexlify}@anchor{3690}
@deffnx {Fonction} binascii.hexlify (data[, sep[, bytes_per_sep=1]])

Renvoie la représentation hexadécimale du binaire `data'. Chaque octet de `data' est converti en la représentation 2 chiffres correspondante. L’objet octets renvoyé est donc deux fois plus long que la longueur de `data'.

Fonctionnalité similaire est également commodément accessible en utilisant la méthode @ref{d56,,bytes.hex()}.

Si `sep' est spécifié, il doit s'agir d'une chaîne de caractères ou d'un objet `byte'. Il sera inséré dans la sortie tous les `bytes_per_sep' octets. Par défaut, l'emplacement du séparateur est compté à partir de l'extrémité droite de la sortie. Si vous souhaitez compter à partir de la gauche, indiquez une valeur `bytes_per_sep' négative.

@example
>>> import binascii
>>> binascii.b2a_hex(b'\xb9\x01\xef')
b'b901ef'
>>> binascii.hexlify(b'\xb9\x01\xef', '-')
b'b9-01-ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
b'b9_01ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
b'b901 ef'
@end example


Modifié dans la version 3.8: ajout des paramètres `sep' et `bytes_per_sep'.

@end deffn

@geindex a2b_hex() (dans le module binascii)
@geindex unhexlify() (dans le module binascii)
@anchor{library/binascii binascii a2b_hex}@anchor{239a}
@deffn {Fonction} binascii.a2b_hex (hexstr)
@anchor{library/binascii binascii unhexlify}@anchor{19d5}
@deffnx {Fonction} binascii.unhexlify (hexstr)

Renvoie la donnée binaire représentée par la chaîne de caractères hexadécimale `hexstr'. Cette fonction est l’inverse de @ref{2399,,b2a_hex()}. `hexstr' doit contenir un nombre pair de chiffres hexadécimaux (qui peuvent être en majuscule ou minuscule), sinon une exception @ref{100f,,Error} est levée.

Une fonctionnalité similaire (n’acceptant que les arguments de chaîne de texte, mais plus libérale vis-à-vis des espaces blancs) est également accessible en utilisant la méthode de classe @ref{add,,bytes.fromhex()}.
@end deffn

@geindex Error
@anchor{library/binascii binascii Error}@anchor{100f}
@deffn {Exception} binascii.Error

Exception levée en cas d'erreurs. Ce sont typiquement des erreurs de programmation.
@end deffn

@geindex Incomplete
@anchor{library/binascii binascii Incomplete}@anchor{3691}
@deffn {Exception} binascii.Incomplete

Exception levée par des données incomplète. Il ne s’agit généralement pas d’erreurs de programmation, mais elles peuvent être traitées en lisant un peu plus de données et en réessayant.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{e,,base64}

Support de l’encodage `base64-style' conforme RFC en base 16, 32, 64 et 85.

@item Module @ref{b6,,quopri}

Support de l’encodage `quote-printable' utilisé par les messages `email' MIME.
@end table


@node quopri --- Encode and decode MIME quoted-printable data,,binascii --- Convert between binary and ASCII,Traitement des données provenant d'Internet
@anchor{library/quopri doc}@anchor{3692}@anchor{library/quopri module-quopri}@anchor{b6}@anchor{library/quopri quopri-encode-and-decode-mime-quoted-printable-data}@anchor{3693}
@subsection @code{quopri} --- Encode and decode MIME quoted-printable data


@geindex module; quopri

`Code source :' Lib/quopri.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/quopri.py}

@geindex quoted-printable;encoding
@geindex MIME;quoted-printable encoding


__________________________________________________________________


Ce module effectue des encodages et décodages de transport `quoted-printable', tel que définis dans la 
@geindex RFC; RFC 1521
RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html} : "`MIME (Multipurpose Internet Mail Extensions) Part One Mechanisms for Specifying and Describing the Format of Internet Message Bodies'". L'encodage `quoted-printable' est adapté aux données dans lesquelles peu de données ne sont pas affichables. L'encodage `base64' disponible dans le module @ref{e,,base64} est plus compact dans les cas où ces caractères sont nombreux, typiquement pour encoder des images.

@geindex decode() (dans le module quopri)
@anchor{library/quopri quopri decode}@anchor{239c}
@deffn {Fonction} quopri.decode (input, output, header=False)

Décode le contenu du fichier `input' et écrit le résultat décodé, binaire, dans le fichier `output'. `input' et `output' doivent être des @ref{11a0,,objets fichiers binaires}. Si l'argument facultatif `header' est fourni et vrai, les `underscore' seront décodés en espaces. C'est utilisé pour décoder des entêtes encodées "Q" décrits dans la RFC 
@geindex RFC; RFC 1522
RFC 1522@footnote{https://datatracker.ietf.org/doc/html/rfc1522.html} : "`MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text'".
@end deffn

@geindex encode() (dans le module quopri)
@anchor{library/quopri quopri encode}@anchor{239b}
@deffn {Fonction} quopri.encode (input, output, quotetabs, header=False)

Encode le contenu du fichier `input' et écrit le résultat dans le fichier `output'. `input' et `output' doivent être des @ref{11a0,,objets fichiers binaires}. `quotetabs'  (paramètre obligatoire) permet de choisir le style d'encodage des espaces et des tabulations, si vrai les espaces seront encodées, sinon elles seront laissées inchangées. Notez que les espaces et tabulations en fin de ligne sont toujours encodées, tel que spécifié par la 
@geindex RFC; RFC 1521
RFC 1521@footnote{https://datatracker.ietf.org/doc/html/rfc1521.html}. `header' est une option permettant d'encoder les espace en `underscores', tel que spécifié par la 
@geindex RFC; RFC 1522
RFC 1522@footnote{https://datatracker.ietf.org/doc/html/rfc1522.html}.
@end deffn

@geindex decodestring() (dans le module quopri)
@anchor{library/quopri quopri decodestring}@anchor{3694}
@deffn {Fonction} quopri.decodestring (s, header=False)

Fonctionne comme @ref{239c,,decode()}, sauf qu'elle accepte des @ref{1bd,,bytes} comme source, et renvoie les @ref{1bd,,bytes} décodés correspondants.
@end deffn

@geindex encodestring() (dans le module quopri)
@anchor{library/quopri quopri encodestring}@anchor{3695}
@deffn {Fonction} quopri.encodestring (s, quotetabs=False, header=False)

Fonctionne comme @ref{239b,,encode()}, sauf qu'elle accepte des @ref{1bd,,bytes} comme source et renvoie les @ref{1bd,,bytes} encodés correspondants. Par défaut, @code{False} est donné au paramètre `quotetabs' de la fonction @ref{239b,,encode()}.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{e,,base64}

Encode et décode des données MIME en `base64'
@end table


@node Outils de traitement de balises structurées,Gestion des protocoles internet,Traitement des données provenant d'Internet,La bibliothèque standard
@anchor{library/markup doc}@anchor{3696}@anchor{library/markup markup}@anchor{3697}@anchor{library/markup structured-markup-processing-tools}@anchor{3698}
@section Outils de traitement de balises structurées


Python intègre une variété de modules pour fonctionner avec différentes formes de données structurées et balisées, comme le SGML (`Standard Generalized Markup Language'), le HTML (`Hypert Markup Language'), et quelques interfaces pour travailler avec du XML (`eXtensible Markup Language').

@menu
* html: html --- HyperText Markup Language support. HyperText Markup Language support
* html.parser: html parser --- Simple HTML and XHTML parser. Simple HTML and XHTML parser
* html.entities: html entities --- Definitions of HTML general entities. Definitions of HTML general entities
* Modules de traitement XML:: 
* xml.etree.ElementTree: xml etree ElementTree --- The ElementTree XML API. The ElementTree XML API
* xml.dom: xml dom --- The Document Object Model API. The Document Object Model API
* xml.dom.minidom: xml dom minidom --- Minimal DOM implementation. Minimal DOM implementation
* xml.dom.pulldom: xml dom pulldom --- Support for building partial DOM trees. Support for building partial DOM trees
* xml.sax: xml sax --- Support for SAX2 parsers. Support for SAX2 parsers
* xml.sax.handler: xml sax handler --- Base classes for SAX handlers. Base classes for SAX handlers
* xml.sax.saxutils: xml sax saxutils --- SAX Utilities. SAX Utilities
* xml.sax.xmlreader: xml sax xmlreader --- Interface for XML parsers. Interface for XML parsers
* xml.parsers.expat: xml parsers expat --- Fast XML parsing using Expat. Fast XML parsing using Expat

@end menu

@node html --- HyperText Markup Language support,html parser --- Simple HTML and XHTML parser,,Outils de traitement de balises structurées
@anchor{library/html doc}@anchor{3699}@anchor{library/html html-hypertext-markup-language-support}@anchor{369a}@anchor{library/html module-html}@anchor{6a}
@subsection @code{html} --- HyperText Markup Language support


@geindex module; html

`Source code:' Lib/html/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/html/__init__.py}


__________________________________________________________________


Ce module définit des outils permettant la manipulation d'HTML.

@geindex escape() (dans le module html)
@anchor{library/html html escape}@anchor{ff7}
@deffn {Fonction} html.escape (s, quote=True)

Convertit les caractères @code{&}, @code{<} et @code{>} de la chaîne de caractères `s' en séquences HTML valides. À utiliser si le texte à afficher pourrait contenir de tels caractères dans le HTML. Si le paramètre optionnel `quote' est vrai, les caractères (@code{"}) et (@code{'}) sont également traduits; cela est utile pour les inclusions dans des valeurs d'attributs HTML délimitées par des guillemets, comme dans @code{<a href="...">}.


Ajouté dans la version 3.2.

@end deffn

@geindex unescape() (dans le module html)
@anchor{library/html html unescape}@anchor{944}
@deffn {Fonction} html.unescape (s)

Convertit toutes les références de caractères nommés et numériques (e.g. @code{&gt;}, @code{&#62;}, @code{&#x3e;}) dans la chaîne de caractères `s' par les caractères Unicode correspondants. Cette fonction utilise les règles définies par le standard HTML 5 à la fois pour les caractères valides et les caractères invalides, et la @ref{10b4,,liste des références des caractères nommés en HTML 5}.


Ajouté dans la version 3.4.

@end deffn


__________________________________________________________________


Les sous-modules dans le paquet @code{html} sont :


@itemize *

@item 
@ref{6c,,html.parser} -- Parseur HTML/XHTML avec un mode de `parsing' tolérant

@item 
@ref{6b,,html.entities} -- Définitions d'entités HTML
@end itemize

@node html parser --- Simple HTML and XHTML parser,html entities --- Definitions of HTML general entities,html --- HyperText Markup Language support,Outils de traitement de balises structurées
@anchor{library/html parser doc}@anchor{369b}@anchor{library/html parser html-parser-simple-html-and-xhtml-parser}@anchor{369c}@anchor{library/html parser module-html parser}@anchor{6c}
@subsection @code{html.parser} --- Simple HTML and XHTML parser


@geindex module; html.parser

`Code source :' Lib/html/parser.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/html/parser.py}

@geindex HTML
@geindex XHTML


__________________________________________________________________


Ce module définit une classe @ref{862,,HTMLParser} qui sert de base pour l'analyse syntaxique de fichiers texte formatés HTML (`HyperText Mark-up Language', le  « langage de balisage hypertexte ») et XHTML (`EXtensible HyperText Markup Language', le « langage extensible de balisage hypertexte »).

@geindex HTMLParser (classe dans html.parser)
@anchor{library/html parser html parser HTMLParser}@anchor{862}
@deffn {Classe} html.parser.HTMLParser (*, convert_charrefs=True)

Crée une instance d'analyseur capable de traiter tout balisage, même invalide.

Si `convert_charrefs' est @code{True} (valeur par défaut), toute référence de caractère (sauf ceux enchâssés dans des éléments @code{script}/@code{style}) est automatiquement convertie en son caractère Unicode.

Une instance de @ref{862,,HTMLParser} est alimentée par des données HTML. Elle fait appel à des méthodes offrant un traitement spécifique quand est rencontré un élément de balisage : balise ouvrante ou fermante, textes, commentaires… Pour implémenter le comportement désiré, l'utilisateur crée une sous-classe de @ref{862,,HTMLParser} en surchargeant ses méthodes.

Cet analyseur ne vérifie ni que les balises fermantes correspondent aux balises ouvrantes, ni n'invoque le gestionnaire de balises fermantes pour les éléments implicitement fermés par un élément extérieur.


Modifié dans la version 3.4: L'argument `convert_charrefs' a été ajouté.



Modifié dans la version 3.5: La valeur par défaut de l'argument `convert_charrefs' est désormais @code{True}.

@end deffn

@menu
* Exemple d'application de l'analyseur HTML:: 
* Méthodes de la classe HTMLParser:: 
* Exemples: Exemples<23>. 

@end menu

@node Exemple d'application de l'analyseur HTML,Méthodes de la classe HTMLParser,,html parser --- Simple HTML and XHTML parser
@anchor{library/html parser example-html-parser-application}@anchor{369d}
@subsubsection Exemple d'application de l'analyseur HTML


Comme exemple simple, un analyseur HTML minimal qui utilise la classe @ref{862,,HTMLParser} pour afficher les balises ouvrantes, les balises fermantes ainsi que les données quand elles apparaissent :

@example
from html.parser import HTMLParser

class MyHTMLParser(HTMLParser):
    def handle_starttag(self, tag, attrs):
        print("Encountered a start tag:", tag)

    def handle_endtag(self, tag):
        print("Encountered an end tag :", tag)

    def handle_data(self, data):
        print("Encountered some data  :", data)

parser = MyHTMLParser()
parser.feed('<html><head><title>Test</title></head>'
            '<body><h1>Parse me!</h1></body></html>')
@end example

La sortie est alors :

@example
Encountered a start tag: html
Encountered a start tag: head
Encountered a start tag: title
Encountered some data  : Test
Encountered an end tag : title
Encountered an end tag : head
Encountered a start tag: body
Encountered a start tag: h1
Encountered some data  : Parse me!
Encountered an end tag : h1
Encountered an end tag : body
Encountered an end tag : html
@end example

@node Méthodes de la classe HTMLParser,Exemples<23>,Exemple d'application de l'analyseur HTML,html parser --- Simple HTML and XHTML parser
@anchor{library/html parser htmlparser-methods}@anchor{369e}
@subsubsection Méthodes de la classe @code{HTMLParser}


Les instances de @ref{862,,HTMLParser} disposent des méthodes suivantes :

@geindex feed() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser feed}@anchor{369f}
@deffn {Méthode} HTMLParser.feed (data)

Alimente l'analyseur avec du texte. Ce texte est traité dans la mesure où il constitue des éléments complets ; les données incomplètes sont mises dans un tampon jusqu'à ce que d'autres données soient fournies ou que la méthode @ref{36a0,,close()} soit appelée. L'argument `data' doit être de classe @ref{435,,str}.
@end deffn

@geindex close() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser close}@anchor{36a0}
@deffn {Méthode} HTMLParser.close ()

Force le traitement de toutes les données du tampon comme si elles étaient suivies par un caractère `fin de fichier'. Cette méthode peut-être redéfinie par une classe dérivée pour ajouter des traitements supplémentaires à la fin de l'entrée, mais la version redéfinie devra impérativement appeler la méthode @ref{36a0,,close()} de la classe de base @ref{862,,HTMLParser}.
@end deffn

@geindex reset() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser reset}@anchor{36a1}
@deffn {Méthode} HTMLParser.reset ()

Réinitialise l'instance. Toutes les données non traitées sont perdues. Cette méthode est appelée implicitement lors de l'instanciation.
@end deffn

@geindex getpos() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser getpos}@anchor{36a2}
@deffn {Méthode} HTMLParser.getpos ()

Renvoie le numéro de ligne et le numéro du caractère dans la ligne où le curseur est positionné.
@end deffn

@geindex get_starttag_text() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser get_starttag_text}@anchor{36a3}
@deffn {Méthode} HTMLParser.get_starttag_text ()

Return the text of the most recently opened start tag.  This should not normally
be needed for structured processing, but may be useful in dealing with HTML "as
deployed" or for re-generating input with minimal changes (whitespace between
attributes can be preserved, etc.).
@end deffn

Les méthodes suivantes sont appelées lors de la rencontre de données ou d'éléments de balisage ; elles sont destinées à être surchargées par la sous-classe. L'implémentation de la classe de base ne fait rien (sauf pour ce qui est de @ref{36a4,,handle_startendtag()}) :

@geindex handle_starttag() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_starttag}@anchor{36a5}
@deffn {Méthode} HTMLParser.handle_starttag (tag, attrs)

Cette méthode est appelée pour traiter une balise ouvrante (p.  ex. @code{<div id="main">}).

L'argument `tag' contient le nom de la balise en minuscules. L'argument `attrs' contient une liste de `n-uplets' @code{(name, value)} regroupant les attributs présents entre les symboles @code{<} et @code{>} de la balise. Le paramètre `name' est converti en minuscule ; les guillemets sont supprimés du paramètre `value' et toute entité de référence ou de caractère est remplacée.

Par exemple, pour la balise @code{<A HREF="https://www.cwi.nl/">}, cette méthode est appelée par @code{handle_starttag('a', [('href', 'https://www.cwi.nl/')])}.

Toute référence d'entité présente dans @ref{6b,,html.entities} est remplacée dans la valeur des attributs.
@end deffn

@geindex handle_endtag() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_endtag}@anchor{36a6}
@deffn {Méthode} HTMLParser.handle_endtag (tag)

Cette méthode est appelée pour traiter les balises fermantes (p.  ex. @code{</div>}).

L'argument `tag' est le nom de la balise en minuscules.
@end deffn

@geindex handle_startendtag() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_startendtag}@anchor{36a4}
@deffn {Méthode} HTMLParser.handle_startendtag (tag, attrs)

Traitée de façon similaire à @ref{36a5,,handle_starttag()}, mais appelée quand l'analyseur rencontre une balise vide de type `XHTML' (p.  ex. @code{<img ... />}). Cette méthode peut-être surchargée par les sous-classes demandant cette information lexicale ; l'implémentation par défaut appelle simplement @ref{36a5,,handle_starttag()} et @ref{36a6,,handle_endtag()}.
@end deffn

@geindex handle_data() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_data}@anchor{36a7}
@deffn {Méthode} HTMLParser.handle_data (data)

Cette méthode est appelée pour traiter toute donnée arbitraire (p.  ex. les nœuds textuels ou les contenus de @code{<script>...</script>} et @code{<style>...</style>}).
@end deffn

@geindex handle_entityref() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_entityref}@anchor{36a8}
@deffn {Méthode} HTMLParser.handle_entityref (name)

Cette méthode est appelée pour traiter les références nommées de caractères de la forme @code{&name;} (p.  ex. @code{&gt;}), où `name' est une référence à une entité générique (p.  ex. @code{'gt'}). Cette méthode n'est jamais appelée si `convert_charrefs' vaut @code{True}.
@end deffn

@geindex handle_charref() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_charref}@anchor{36a9}
@deffn {Méthode} HTMLParser.handle_charref (name)

This method is called to process decimal and hexadecimal numeric character
references of the form @code{&#@var{NNN};} and @code{&#x@var{NNN};}.  For example, the decimal
equivalent for @code{&gt;} is @code{&#62;}, whereas the hexadecimal is @code{&#x3E;};
in this case the method will receive @code{'62'} or @code{'x3E'}.  This method
is never called if `convert_charrefs' is @code{True}.
@end deffn

@geindex handle_comment() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_comment}@anchor{36aa}
@deffn {Méthode} HTMLParser.handle_comment (data)

Cette méthode est appelée quand un commentaire (p.  ex. @code{<!--commentaire-->}) est rencontré.

Par exemple, le commentaire @code{<!-- commentaire -->} provoque l'appel de cette méthode avec l'argument @code{' commentaire '}.

Le contenu des commentaires conditionnels d'Internet Explorer (`condcoms') ne sont pas traités de manière particulière par l'analyseur.  Ils sont passés à cette méthode comme tous les autres commentaires. Ainsi, pour @code{<!--[if IE 9]>Contenu spécifique à IE9<![endif]-->}, cette méthode sera appelée avec @code{'[if IE 9]>Contenu spécifique à IE9<![endif]'}.
@end deffn

@geindex handle_decl() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_decl}@anchor{36ab}
@deffn {Méthode} HTMLParser.handle_decl (decl)

Cette méthode est appelée pour traiter la déclaration `doctype' de HTML (p.  ex. @code{<!DOCTYPE html>}).

Le paramètre `decl' contient la totalité de la déclaration contenue dans le balisage @code{<!...>} (p.  ex. @code{'DOCTYPE html'}).
@end deffn

@geindex handle_pi() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser handle_pi}@anchor{36ac}
@deffn {Méthode} HTMLParser.handle_pi (data)

Méthode appelée quand une instruction de traitement est rencontrée. Le paramètre `data' contient la totalité de l'instruction de traitement. Par exemple, pour l'instruction de traitement @code{<?proc color='rouge'>}, cette méthode est appelée par @code{handle_pi("proc color='rouge'")}. Elle est destinée à être surchargée dans une classe dérivée ; la classe de base ne réalise aucun traitement.

@cartouche
@quotation Note 
La classe @ref{862,,HTMLParser} utilise les règles syntaxiques de `SGML' pour traiter les instructions de traitement. Une instruction de traitement `XHTML' utilisant une terminaison en @code{'?'} se traduit par l'inclusion de ce @code{'?'} dans `data'.
@end quotation
@end cartouche
@end deffn

@geindex unknown_decl() (méthode html.parser.HTMLParser)
@anchor{library/html parser html parser HTMLParser unknown_decl}@anchor{36ad}
@deffn {Méthode} HTMLParser.unknown_decl (data)

Cette méthode est appelée quand une déclaration non reconnue est lue par l'analyseur.

Le paramètre `data' contient toute la déclaration enchâssée dans le balisage @code{<![...]>}. Il est parfois utile de le surcharger dans une classe dérivée. L'implémentation de la classe de base ne réalise aucune opération.
@end deffn

@node Exemples<23>,,Méthodes de la classe HTMLParser,html parser --- Simple HTML and XHTML parser
@anchor{library/html parser examples}@anchor{36ae}@anchor{library/html parser htmlparser-examples}@anchor{36af}
@subsubsection Exemples


La classe suivante implémente un analyseur qui est utilisé dans les exemples ci-dessous :

@example
from html.parser import HTMLParser
from html.entities import name2codepoint

class MyHTMLParser(HTMLParser):
    def handle_starttag(self, tag, attrs):
        print("Start tag:", tag)
        for attr in attrs:
            print("     attr:", attr)

    def handle_endtag(self, tag):
        print("End tag  :", tag)

    def handle_data(self, data):
        print("Data     :", data)

    def handle_comment(self, data):
        print("Comment  :", data)

    def handle_entityref(self, name):
        c = chr(name2codepoint[name])
        print("Named ent:", c)

    def handle_charref(self, name):
        if name.startswith('x'):
            c = chr(int(name[1:], 16))
        else:
            c = chr(int(name))
        print("Num ent  :", c)

    def handle_decl(self, data):
        print("Decl     :", data)

parser = MyHTMLParser()
@end example

Traitement du `doctype' :

@example
>>> parser.feed('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" '
...             '"http://www.w3.org/TR/html4/strict.dtd">')
Decl     : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"
@end example

Analyse d'un élément avec un titre et des attributs :

@example
>>> parser.feed('<img src="python-logo.png" alt="The Python logo">')
Start tag: img
     attr: ('src', 'python-logo.png')
     attr: ('alt', 'The Python logo')
>>>
>>> parser.feed('<h1>Python</h1>')
Start tag: h1
Data     : Python
End tag  : h1
@end example

Le contenu des éléments @code{script} et @code{style} est renvoyé tel quel (sans autre traitement) :

@example
>>> parser.feed('<style type="text/css">#python @{ color: green @}</style>')
Start tag: style
     attr: ('type', 'text/css')
Data     : #python @{ color: green @}
End tag  : style

>>> parser.feed('<script type="text/javascript">'
...             'alert("<strong>hello!</strong>");</script>')
Start tag: script
     attr: ('type', 'text/javascript')
Data     : alert("<strong>hello!</strong>");
End tag  : script
@end example

Traitement des commentaires :

@example
>>> parser.feed('<!-- a comment -->'
...             '<!--[if IE 9]>IE-specific content<![endif]-->')
Comment  :  a comment
Comment  : [if IE 9]>IE-specific content<![endif]
@end example

L'analyse des caractères nommés et des références numériques de caractères et leur conversion en leur caractère correct (note : ces trois références sont équivalentes à @code{'>'}) :

@example
>>> parser.feed('&gt;&#62;&#x3E;')
Named ent: >
Num ent  : >
Num ent  : >
@end example

Il est possible de fournir des portions de code incomplètes à @ref{369f,,feed()}, mais alors il est possible que @ref{36a7,,handle_data()} soit appelée plusieurs fois, à moins que `convert_charrefs' soit @code{True} :

@example
>>> for chunk in ['<sp', 'an>buff', 'ered ', 'text</s', 'pan>']:
...     parser.feed(chunk)
...
Start tag: span
Data     : buff
Data     : ered
Data     : text
End tag  : span
@end example

L'analyse de code `HTML' non valide (p. ex. des attributs sans guillemets) fonctionne également :

@example
>>> parser.feed('<p><a class=link href=#main>tag soup</p ></a>')
Start tag: p
Start tag: a
     attr: ('class', 'link')
     attr: ('href', '#main')
Data     : tag soup
End tag  : p
End tag  : a
@end example

@node html entities --- Definitions of HTML general entities,Modules de traitement XML,html parser --- Simple HTML and XHTML parser,Outils de traitement de balises structurées
@anchor{library/html entities doc}@anchor{36b0}@anchor{library/html entities html-entities-definitions-of-html-general-entities}@anchor{36b1}@anchor{library/html entities module-html entities}@anchor{6b}
@subsection @code{html.entities} --- Definitions of HTML general entities


@geindex module; html.entities

`Source code:' Lib/html/entities.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/html/entities.py}


__________________________________________________________________


Ce module définit quatre dictionnaires, @ref{10b4,,html5}, @ref{36b2,,name2codepoint}, @ref{36b3,,codepoint2name}, et @ref{36b4,,entitydefs}.

@geindex html5 (dans le module html.entities)
@anchor{library/html entities html entities html5}@anchor{10b4}
@deffn {Données} html.entities.html5

Un dictionnaire qui fait correspondre les références de caractères nommés HTML5 @footnote{
See @indicateurl{https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references}
} aux caractères Unicode équivalents, e.g. @code{html5['gt;'] == '>'}. À noter que le point-virgule en fin de chaîne est inclus dans le nom (e.g. @code{'gt;'}), toutefois certains noms sont acceptés par le standard même sans le point-virgule: dans ce cas, le nom est présent à la fois avec et sans le @code{;}. Voir aussi @ref{944,,html.unescape()}.


Ajouté dans la version 3.3.

@end deffn

@geindex entitydefs (dans le module html.entities)
@anchor{library/html entities html entities entitydefs}@anchor{36b4}
@deffn {Données} html.entities.entitydefs

Un dictionnaire qui fait correspondre les définitions d'entités XHTML 1.0 avec leur remplacement en ISO Latin-1.
@end deffn

@geindex name2codepoint (dans le module html.entities)
@anchor{library/html entities html entities name2codepoint}@anchor{36b2}
@deffn {Données} html.entities.name2codepoint

A dictionary that maps HTML4 entity names to the Unicode code points.
@end deffn

@geindex codepoint2name (dans le module html.entities)
@anchor{library/html entities html entities codepoint2name}@anchor{36b3}
@deffn {Données} html.entities.codepoint2name

A dictionary that maps Unicode code points to HTML4 entity names.
@end deffn

@subsubheading Notes


@node Modules de traitement XML,xml etree ElementTree --- The ElementTree XML API,html entities --- Definitions of HTML general entities,Outils de traitement de balises structurées
@anchor{library/xml doc}@anchor{36b5}@anchor{library/xml module-xml}@anchor{11f}@anchor{library/xml xml}@anchor{36b6}@anchor{library/xml xml-processing-modules}@anchor{36b7}
@subsection Modules de traitement XML


@geindex module; xml

`Code source:' Lib/xml/@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/}


__________________________________________________________________


Les interfaces de Python de traitement de XML sont regroupées dans le paquet @code{xml}.

@cartouche
@quotation Avertissement 
les modules XML ne sont pas protégés contre les données mal construites ou malveillantes. Si vous devez parcourir des données douteuses non authentifiées, lisez les sections @ref{36b8,,Vulnérabilités XML} et @ref{36b9,,The defusedxml Package}.
@end quotation
@end cartouche

Il est important de noter que les modules dans le paquet @ref{11f,,xml} nécessitent qu'au moins un analyseur compatible `SAX' soit disponible. L'analyseur `Expat' est inclus dans Python, ainsi le module @ref{125,,xml.parsers.expat} est toujours disponible.

La documentation des interfaces vers `DOM' et `SAX' se trouve dans @ref{120,,xml.dom} et @ref{128,,xml.sax}.

Les sous-modules de traitement XML sont :


@itemize *

@item 
@ref{124,,xml.etree.ElementTree} : l'API `ElementTree', un processeur simple et léger
@end itemize



@itemize *

@item 
@ref{120,,xml.dom} : la définition de l'API DOM

@item 
@ref{121,,xml.dom.minidom} : une implémentation minimale de DOM

@item 
@ref{122,,xml.dom.pulldom} : gestion de la construction partielle des arbres DOM
@end itemize



@itemize *

@item 
@ref{128,,xml.sax} : classes mères `SAX2' et fonctions utilitaires

@item 
@ref{125,,xml.parsers.expat} : l'interface de l'analyseur `Expat'
@end itemize

@menu
* Vulnérabilités XML:: 
* The defusedxml Package:: 

@end menu

@node Vulnérabilités XML,The defusedxml Package,,Modules de traitement XML
@anchor{library/xml id1}@anchor{36ba}@anchor{library/xml xml-vulnerabilities}@anchor{36b8}
@subsubsection Vulnérabilités XML


Les modules de traitement XML ne sont pas sécurisés contre les données construites malicieusement. Un attaquant peut abuser des fonctionnalités XML pour exécuter des attaques par déni de service, accéder à des fichiers locaux, générer des connexions réseaux à d'autres machines ou contourner des pare-feux.

Le tableau suivant donne une vue d'ensemble des attaques connues et indique si les différents modules y sont vulnérables.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 
@headitem

type

@tab

`sax'

@tab

`etree'

@tab

`minidom'

@tab

`pulldom'

@tab

`xmlrpc'

@item

`billion laughs'

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@item

`quadratic blowup'

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@tab

`Vulnérable' (1)

@item

`external entity expansion'

@tab

Sûr (5)

@tab

Sûr (2)

@tab

Sûr (3)

@tab

Sûr (5)

@tab

Sûr (4)

@item

Récupération de DTD@footnote{https://en.wikipedia.org/wiki/Document_type_definition}

@tab

Sûr (5)

@tab

Sûr

@tab

Sûr

@tab

Sûr (5)

@tab

Sûr

@item

`decompression bomb'

@tab

Sûr

@tab

Sûr

@tab

Sûr

@tab

Sûr

@tab

`Vulnérable'

@item

large tokens

@tab

`Vulnerable' (6)

@tab

`Vulnerable' (6)

@tab

`Vulnerable' (6)

@tab

`Vulnerable' (6)

@tab

`Vulnerable' (6)

@end multitable



@enumerate 

@item 
Expat 2.4.1 and newer is not vulnerable to the "billion laughs" and
"quadratic blowup" vulnerabilities. Items still listed as vulnerable due to
potential reliance on system-provided libraries. Check
@code{pyexpat.EXPAT_VERSION}.

@item 
@ref{124,,xml.etree.ElementTree} doesn't expand external entities and raises a
@ref{1256,,ParseError} when an entity occurs.

@item 
@ref{121,,xml.dom.minidom} n'étend pas les entités externes et renvoie simplement l'entité mot pour mot (non étendue).

@item 
@ref{12d,,xmlrpc.client} doesn't expand external entities and omits them.

@item 
Depuis Python 3.7.1, par défaut les entités générales externes ne sont plus traitées.

@item 
Expat 2.6.0 and newer is not vulnerable to denial of service
through quadratic runtime caused by parsing large tokens.
Items still listed as vulnerable due to
potential reliance on system-provided libraries. Check
@code{pyexpat.EXPAT_VERSION}.
@end enumerate


@table @asis

@item `billion laughs' / `exponential entity expansion'

L'attaque Billion Laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs} – aussi connue comme `exponential entity expansion' – utilise de multiples niveaux d'entités imbriquées. Chaque entité se réfère à une autre entité de multiple fois. L'entité finale contient une chaîne courte. Le résultat de l'expansion exponentielle génère plusieurs gigaoctets de texte et consomme beaucoup de mémoire et de temps processeur.

@item `quadratic blowup entity expansion'

Une attaque `quadratic blowup' est similaire à l'attaque Billion Laughs@footnote{https://en.wikipedia.org/wiki/Billion_laughs} ; il s'agit également d'un abus d'extension d'entités. Au lieu d'utiliser des entités imbriquées, cette attaque répète encore et encore une seule entité de plusieurs milliers de caractères. Cette attaque n'est pas aussi efficace que la version exponentielle mais contourne les contre-mesures de l'analyseur qui interdit les entités imbriquées de multiples fois.

@item `external entity expansion'

Les déclarations d'entités peuvent contenir plus que du texte de substitution. Elles peuvent également référencer des ressources externes ou des fichiers locaux. L'analyseur XML accède à ces fichiers et inclut les contenus dans le document XML.

@item Récupération de DTD@footnote{https://en.wikipedia.org/wiki/Document_type_definition}

Certaines bibliothèques XML comme @ref{122,,xml.dom.pulldom} de Python récupère les documents de définitions de types (`DTD') depuis des emplacements distants ou locaux. La fonctionnalité a des implications similaires au problème d'extension d'entités externes.

@item `decompression bomb'

Des bombes de décompression (ou ZIP bomb@footnote{https://en.wikipedia.org/wiki/Zip_bomb}) sont valables pour toutes les bibliothèques XML qui peuvent analyser des flux XML compressés comme des flux HTTP `gzip' ou des fichiers compressés `LZMA'. Pour L'attaquant, cela permet de réduire d'une magnitude d'ordre 3 ou plus la quantité de données transmises.

@item large tokens

Expat needs to re-parse unfinished tokens; without the protection
introduced in Expat 2.6.0, this can lead to quadratic runtime that can
be used to cause denial of service in the application parsing XML.
The issue is known as 
@geindex Common Vulnerabilities and Exposures; CVE 2023-52425
CVE 2023-52425@footnote{https://www.cve.org/CVERecord?id=CVE-2023-52425}.
@end table

The documentation for defusedxml@footnote{https://pypi.org/project/defusedxml/} on PyPI has further information about
all known attack vectors with examples and references.

@node The defusedxml Package,,Vulnérabilités XML,Modules de traitement XML
@anchor{library/xml defusedxml-package}@anchor{36b9}@anchor{library/xml the-defusedxml-package}@anchor{36bb}
@subsubsection The @code{defusedxml} Package


defusedxml@footnote{https://pypi.org/project/defusedxml/} is a pure Python package with modified subclasses of all stdlib
XML parsers that prevent any potentially malicious operation. Use of this
package is recommended for any server code that parses untrusted XML data. The
package also ships with example exploits and extended documentation on more
XML exploits such as XPath injection.

@node xml etree ElementTree --- The ElementTree XML API,xml dom --- The Document Object Model API,Modules de traitement XML,Outils de traitement de balises structurées
@anchor{library/xml etree elementtree doc}@anchor{36bc}@anchor{library/xml etree elementtree module-xml etree ElementTree}@anchor{124}@anchor{library/xml etree elementtree xml-etree-elementtree-the-elementtree-xml-api}@anchor{36bd}
@subsection @code{xml.etree.ElementTree} --- The ElementTree XML API


@geindex module; xml.etree.ElementTree

`Code Source:' Lib/xml/etree/ElementTree.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/etree/ElementTree.py}


__________________________________________________________________


Le  module @ref{124,,xml.etree.ElementTree} implémente une API simple et efficace pour analyser et créer des données XML.


Modifié dans la version 3.3: ce module utilise une implémentation rapide chaque fois que c'est possible.



Obsolète depuis la version 3.3: The @code{xml.etree.cElementTree} module is deprecated.


@cartouche
@quotation Avertissement 
le module @ref{128,,xml.sax} n'est pas sécurisé contre les données construites de façon malveillante. Si vous avez besoin d'analyser des données non sécurisées ou non authentifiées, référez-vous à @ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche

@menu
* Tutoriel: Tutoriel<3>. 
* Prise en charge de XPath:: 
* Référence: Référence<2>. 
* Prise en charge de XInclude:: 
* Référence: Référence<3>. 

@end menu

@node Tutoriel<3>,Prise en charge de XPath,,xml etree ElementTree --- The ElementTree XML API
@anchor{library/xml etree elementtree tutorial}@anchor{36be}
@subsubsection Tutoriel


Ceci est un petit tutoriel pour utiliser @ref{124,,xml.etree.ElementTree} (@code{ET}). Le but est de montrer quelques composants et les concepts basiques du module.

@menu
* Arborescence et éléments XML:: 
* Analyse XML:: 
* API à flux tiré:: 
* Atteinte d'éléments d'intérêt:: 
* Modification d'un fichier XML:: 
* Création de documents XML:: 
* Analyse d'un XML avec des espaces de noms:: 

@end menu

@node Arborescence et éléments XML,Analyse XML,,Tutoriel<3>
@anchor{library/xml etree elementtree xml-tree-and-elements}@anchor{36bf}
@subsubsection Arborescence et éléments XML


XML est un format de données fondamentalement hiérarchique et la façon la plus naturelle de le représenter est avec un arbre. @code{ET} a deux classes pour ce but : @ref{93b,,ElementTree} représente l'ensemble du document XML comme un arbre et @ref{305,,Element} représente un simple nœud dans cet arbre. Les interactions (lire et écrire vers et depuis des fichiers) sur le document sont habituellement effectuées au niveau de @ref{93b,,ElementTree}. Les interactions sur un seul élément XML et ses sous-éléments sont effectuées au niveau de @ref{305,,Element}.

@node Analyse XML,API à flux tiré,Arborescence et éléments XML,Tutoriel<3>
@anchor{library/xml etree elementtree elementtree-parsing-xml}@anchor{36c0}@anchor{library/xml etree elementtree parsing-xml}@anchor{36c1}
@subsubsection Analyse XML


We'll be using the fictive @code{country_data.xml} XML document as the sample data for this section:

@example
<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>
@end example

Nous pouvons importer ces données en lisant un fichier :

@example
import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()
@end example

Ou depuis une chaîne de caractères :

@example
root = ET.fromstring(country_data_as_string)
@end example

@ref{36c2,,fromstring()} analyse les données XML depuis une chaîne de caractères et produit un @ref{305,,Element}, qui est l'élément racine de l'arbre analysé.  D'autres fonctions d'analyse peuvent créer un @ref{93b,,ElementTree}.  Vérifiez la documentation pour en être sûr.

En tant qu'@ref{305,,Element}, @code{root} a une balise (`tag') et un dictionnaire d'attributs :

@example
>>> root.tag
'data'
>>> root.attrib
@{@}
@end example

Il contient aussi des nœuds enfants sur lesquels nous pouvons itérer :

@example
>>> for child in root:
...     print(child.tag, child.attrib)
...
country @{'name': 'Liechtenstein'@}
country @{'name': 'Singapore'@}
country @{'name': 'Panama'@}
@end example

Les enfants sont imbriqués et nous pouvons accéder aux nœuds enfants spécifiques `via' un indice :

@example
>>> root[0][1].text
'2008'
@end example

@cartouche
@quotation Note 
les éléments du XML d'entrée ne sont pas tous considérés comme des éléments de l'arborescence. Actuellement, le module ignore les commentaires XML, les instructions de traitements et la déclaration du type de document dans l'entrée. Néanmoins, les arborescences construites en utilisant l'API du module plutôt que par l'analyse du texte XML peuvent contenir des commentaires et des instructions de traitement ; ils seront inclus lors de la génération du XML de sortie. La DTD du document est accessible en passant une instance de @ref{a43,,TreeBuilder} au constructeur de @ref{a42,,XMLParser}.
@end quotation
@end cartouche

@node API à flux tiré,Atteinte d'éléments d'intérêt,Analyse XML,Tutoriel<3>
@anchor{library/xml etree elementtree elementtree-pull-parsing}@anchor{fdd}@anchor{library/xml etree elementtree pull-api-for-non-blocking-parsing}@anchor{36c3}
@subsubsection API à flux tiré


La plupart des fonctions d'analyse fournies par ce module nécessitent que le document entier soit lu en même temps avant de renvoyer un résultat. Il est possible d'utiliser un @ref{a42,,XMLParser} et d'y introduire des données de manière incrémentielle, mais il s'agit d'une API à flux poussé qui appelle des méthodes par rappel automatique, ce qui est de trop bas niveau et peu pratique pour la plupart des besoins. Parfois, ce que l'utilisateur souhaite réellement, c'est pouvoir analyser du XML de manière incrémentielle, sans bloquer les opérations, tout en bénéficiant de la commodité des objets @ref{305,,Element} entièrement construits.

L'outil le plus puissant pour ce faire est @ref{fdc,,XMLPullParser}. Il ne nécessite pas de lecture bloquante pour obtenir les données XML et est plutôt alimenté en données de manière incrémentielle avec des appels à @ref{36c4,,XMLPullParser.feed()}. Pour obtenir les éléments XML analysés, appelez @ref{36c5,,XMLPullParser.read_events()}. Voici un exemple :

@example
>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end
mytag text= sometext more text
@end example

Le cas d'utilisation évident concerne les applications qui fonctionnent de manière non bloquante dans lesquelles les données XML sont reçues à partir d'un connecteur réseau ou lues de manière incrémentielle à partir d'un périphérique de stockage. Dans de tels cas, le blocage des lectures est inacceptable.

Parce qu'il est très flexible, @ref{fdc,,XMLPullParser} peut être peu pratique à utiliser pour des cas d'utilisation plus simples. Si cela ne vous dérange pas que votre application se bloque pendant la lecture de données XML mais que vous souhaitez tout de même disposer de capacités d'analyse incrémentielle, jetez un œil à @ref{270,,iterparse()}. Cela peut être utile lorsque vous lisez un document XML volumineux et que vous ne souhaitez pas le conserver entièrement en mémoire.

Where `immediate' feedback through events is wanted, calling method
@ref{26d,,XMLPullParser.flush()} can help reduce delay;
please make sure to study the related security notes.

@node Atteinte d'éléments d'intérêt,Modification d'un fichier XML,API à flux tiré,Tutoriel<3>
@anchor{library/xml etree elementtree finding-interesting-elements}@anchor{36c6}
@subsubsection Atteinte d'éléments d'intérêt


@ref{305,,Element} a quelques méthodes très utiles qui aident à parcourir récursivement tous les sous-arbres (ses enfants, leurs enfants et ainsi de suite). Par exemple, @ref{132d,,Element.iter()} :

@example
>>> for neighbor in root.iter('neighbor'):
...     print(neighbor.attrib)
...
@{'name': 'Austria', 'direction': 'E'@}
@{'name': 'Switzerland', 'direction': 'W'@}
@{'name': 'Malaysia', 'direction': 'N'@}
@{'name': 'Costa Rica', 'direction': 'W'@}
@{'name': 'Colombia', 'direction': 'E'@}
@end example

@ref{36c7,,Element.findall()} récupère seulement les éléments avec une balise qui sont les descendants directs de l'élément courant. @ref{36c8,,Element.find()} récupère le `premier' élément avec une balise particulière et @ref{36c9,,Element.text} accède au contenu textuel de l'élément.  @ref{36ca,,Element.get()} accède aux attributs de l'élément :

@example
>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68
@end example

Une caractérisation plus sophistiquée des éléments à rechercher est possible en utilisant @ref{b9b,,XPath}.

@node Modification d'un fichier XML,Création de documents XML,Atteinte d'éléments d'intérêt,Tutoriel<3>
@anchor{library/xml etree elementtree modifying-an-xml-file}@anchor{36cb}
@subsubsection Modification d'un fichier XML


@ref{93b,,ElementTree} fournit un moyen simple de créer des documents XML et de les écrire dans des fichiers. La méthode @ref{fe0,,ElementTree.write()} sert à cet effet.

Une fois créé, un objet @ref{305,,Element} peut être manipulé en changeant directement ses champs (tels que @ref{36c9,,Element.text}), en ajoutant et en modifiant des attributs (méthode @ref{36cc,,Element.set()}), ou en ajoutant de nouveaux enfants (par exemple avec @ref{36cd,,Element.append()}).

Disons que nous voulons en ajouter un au classement de chaque pays, et ajouter un attribut `updated' (« mis à jour ») à l'élément de classement :

@example
>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')
@end example

Maintenant, notre XML ressemble à ceci :

@example
<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>
@end example

Nous pouvons supprimer des éléments en utilisant @ref{36ce,,Element.remove()}. Supposons que nous souhaitions supprimer tous les pays dont le classement est supérieur à 50 :

@example
>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')
@end example

Notez que les modifications simultanées lors de l'itération peuvent entraîner des problèmes, tout comme lors de l'itération et de la modification de listes ou de dictionnaires Python. Par conséquent, l'exemple collecte d'abord tous les éléments correspondants avec @code{root.findall()}, et après seulement parcourt la liste des correspondances.

Maintenant, notre XML ressemble à ceci :

@example
<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>
@end example

@node Création de documents XML,Analyse d'un XML avec des espaces de noms,Modification d'un fichier XML,Tutoriel<3>
@anchor{library/xml etree elementtree building-xml-documents}@anchor{36cf}
@subsubsection Création de documents XML


La fonction @ref{36d0,,SubElement()} fournit également un moyen pratique de créer de nouveaux sous-éléments pour un élément donné :

@example
>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>
@end example

@node Analyse d'un XML avec des espaces de noms,,Création de documents XML,Tutoriel<3>
@anchor{library/xml etree elementtree parsing-xml-with-namespaces}@anchor{36d1}
@subsubsection Analyse d'un XML avec des espaces de noms


Si l'entrée XML a des espaces de noms@footnote{https://fr.wikipedia.org/wiki/Espace_de_noms_XML}, les balises et les attributs avec des préfixes sous la forme `préfixe:unebalise' sont étendus à @code{@{uri@}unebalise} où le `préfixe' est remplacé par l'`URI' complet. De plus, s'il existe un espace de noms par défaut@footnote{https://www.w3.org/TR/xml-names/#defaulting}, cet URI complet est ajouté au début de toutes les balises non préfixées.

Voici un exemple XML qui intègre deux espaces de noms, l'un avec le préfixe `fictional' et l'autre servant d'espace de noms par défaut :

@example
<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>
@end example

Une façon de rechercher et d'explorer cet exemple XML consiste à ajouter manuellement l'URI à chaque balise ou attribut dans le `xpath' d'une recherche @ref{36c8,,find()} ou @ref{36c7,,findall()} :

@example
root = fromstring(xml_text)
for actor in root.findall('@{http://people.example.com@}actor'):
    name = actor.find('@{http://people.example.com@}name')
    print(name.text)
    for char in actor.findall('@{http://characters.example.com@}character'):
        print(' |-->', char.text)
@end example

Une meilleure façon de rechercher dans l'exemple XML avec espace de noms consiste à créer un dictionnaire avec vos propres préfixes et à les utiliser dans les fonctions de recherche :

@example
ns = @{'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'@}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print(name.text)
    for char in actor.findall('role:character', ns):
        print(' |-->', char.text)
@end example

Ces deux approches donnent le même résultat :

@example
John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement
@end example

@node Prise en charge de XPath,Référence<2>,Tutoriel<3>,xml etree ElementTree --- The ElementTree XML API
@anchor{library/xml etree elementtree elementtree-xpath}@anchor{b9b}@anchor{library/xml etree elementtree xpath-support}@anchor{36d2}
@subsubsection Prise en charge de `XPath'


Ce module fournit une prise en charge limitée des expressions XPath@footnote{https://www.w3.org/TR/xpath} pour localiser des éléments dans une arborescence. L'objectif est de prendre en charge un petit sous-ensemble de la syntaxe abrégée ; un moteur `XPath' complet sort du cadre du module.

@menu
* Exemple: Exemple<8>. 
* Prise en charge de la syntaxe XPath:: 

@end menu

@node Exemple<8>,Prise en charge de la syntaxe XPath,,Prise en charge de XPath
@anchor{library/xml etree elementtree example}@anchor{36d3}
@subsubsection Exemple


Voici un exemple qui démontre certaines des fonctionnalités `XPath' du module. Nous utilisons le document XML @code{countrydata} de la section @ref{36c0,,Parsing XML} :

@example
import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")
@end example

Pour du XML avec des espaces de noms, utilisez la notation qualifiée habituelle @code{@{namespace@}tag} :

@example
# All dublin-core "title" tags in the document
root.findall(".//@{http://purl.org/dc/elements/1.1/@}title")
@end example

@node Prise en charge de la syntaxe XPath,,Exemple<8>,Prise en charge de XPath
@anchor{library/xml etree elementtree supported-xpath-syntax}@anchor{36d4}
@subsubsection Prise en charge de la syntaxe `XPath'



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Syntaxe

@tab

Signification

@item

@code{tag}

@tab

Sélectionne tous les éléments enfants avec une balise donnée. Par exemple, @code{spam} sélectionne tous les éléments enfants nommés @code{spam} et @code{spam/egg} sélectionne tous les petits-enfants nommés @code{egg} dans les enfants nommés @code{spam}. @code{@{namespace@}*} sélectionne toutes les balises dans l'espace de noms donné, @code{@{*@}spam} sélectionne les balises nommées @code{spam} dans n'importe quel (ou aucun) espace de noms et @code{@{@}*} sélectionne seulement les balises qui ne sont pas dans un espace de noms.


Modifié dans la version 3.8: la prise en charge des caractères génériques étoiles a été ajoutée.


@item

@code{*}

@tab

Sélectionne tous les éléments enfants, y compris les commentaires et les instructions de traitement. Par exemple, @code{*/egg} sélectionne tous les petits-enfants nommés @code{egg}.

@item

@code{.}

@tab

Sélectionne le nœud actuel. C'est surtout utile au début du chemin, pour indiquer qu'il s'agit d'un chemin relatif.

@item

@code{//}

@tab

Sélectionne tous les sous-éléments, à tous les niveaux situés sous l'élément actuel. Par exemple, @code{.//egg} sélectionne tous les éléments @code{egg} dans l'arborescence entière.

@item

@code{..}

@tab

Sélectionne l'élément parent. Renvoie @code{None} si le chemin tente d'atteindre les ancêtres de l'élément de départ (l'élément sur lequel @code{find} a été appelé).

@item

@code{[@@attrib]}

@tab

Sélectionne tous les éléments qui ont l'attribut donné.

@item

@code{[@@attrib='value']}

@tab

Sélectionne tous les éléments pour lesquels l'attribut donné a la valeur donnée. La valeur ne peut pas contenir de guillemet simple (@code{'}).

@item

@code{[@@attrib!='value']}

@tab

Sélectionne tous les éléments pour lesquels l'attribut donné n'a pas la valeur donnée. La valeur ne peut pas contenir de guillemet simple (@code{'}).


Ajouté dans la version 3.10.


@item

@code{[tag]}

@tab

Sélectionne tous les éléments qui ont un enfant nommé @code{tag}. Seuls les enfants immédiats sont pris en charge.

@item

@code{[.='text']}

@tab

Sélectionne tous les éléments dont le contenu textuel complet, y compris les descendants, est égal au @code{text} donné.


Ajouté dans la version 3.7.


@item

@code{[.!='text']}

@tab

Sélectionne tous les éléments dont le contenu textuel complet, y compris les descendants, n'est pas égal au @code{text} donné.


Ajouté dans la version 3.10.


@item

@code{[tag='text']}

@tab

Sélectionne tous les éléments qui ont un enfant nommé @code{tag} dont le contenu textuel complet, y compris les descendants, est égal au @code{text} donné.

@item

@code{[tag!='text']}

@tab

Sélectionne tous les éléments qui ont un enfant nommé @code{tag} dont le contenu textuel complet, y compris les descendants, n'est pas égal au @code{text} donné.


Ajouté dans la version 3.10.


@item

@code{[position]}

@tab

Sélectionne tous les éléments situés à la position donnée. La position peut être soit un entier (1 est la première position), l'expression @code{last()} (pour la dernière position), ou une position relative à la dernière position (par exemple @code{last()-1}).

@end multitable


Les prédicats (expressions entre crochets) doivent être précédés d'un nom de balise, d'un astérisque ou d'un autre prédicat. Les prédicats @code{position} doivent être précédés d'un nom de balise.

@node Référence<2>,Prise en charge de XInclude,Prise en charge de XPath,xml etree ElementTree --- The ElementTree XML API
@anchor{library/xml etree elementtree reference}@anchor{36d5}
@subsubsection Référence


@menu
* Fonctions: Fonctions<9>. 

@end menu

@node Fonctions<9>,,,Référence<2>
@anchor{library/xml etree elementtree elementtree-functions}@anchor{36d6}@anchor{library/xml etree elementtree functions}@anchor{36d7}
@subsubsection Fonctions


@geindex canonicalize() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree canonicalize}@anchor{36d8}
@deffn {Fonction} xml.etree.ElementTree.canonicalize (xml_data=None, *, out=None, from_file=None, **options)

Fonction de transformation C14N 2.0@footnote{https://www.w3.org/TR/xml-c14n2/}.

Canonicalization is a way to normalise XML output in a way that allows
byte-by-byte comparisons and digital signatures.  It reduces the freedom
that XML serializers have and instead generates a more constrained XML
representation.  The main restrictions regard the placement of namespace
declarations, the ordering of attributes, and ignorable whitespace.

Cette fonction prend une chaîne de données XML (`xml_data') ou un chemin de fichier ou un objet de type fichier (`from_file') en entrée, la convertit sous la forme canonique et l'écrit à l'aide de l'objet simili-fichier `out', s'il est fourni, ou le renvoie sous forme de chaîne de texte sinon. Le fichier de sortie reçoit du texte, pas des octets. Il doit donc être ouvert en mode texte avec l'encodage @code{utf-8}.

Utilisation typique :

@example
xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)
@end example

Les `options' de configuration sont les suivantes :


@itemize -

@item 
`with_comments' : définissez cet attribut à vrai pour inclure les commentaires (par défaut : faux)

@item 

@table @asis

@item `strip_text' : définissez à vrai pour supprimer les espaces avant et après le contenu du texte

(par défaut : faux)
@end table

@item 

@table @asis

@item `rewrite_prefixes' : définissez à vrai pour remplacer les préfixes d'espace de noms par « n@{nombre@} »

(par défaut : faux)
@end table

@item 

@table @asis

@item `qname_aware_tags' : ensemble de noms de balises prenant en charge les noms qualifiés dans lesquels les préfixes

doivent être remplacés dans le contenu du texte (par défaut : vide)
@end table

@item 

@table @asis

@item `qname_aware_attrs' : ensemble de noms d'attributs prenant en charge les noms qualifiés dans lesquels les préfixes

doivent être remplacés dans le contenu du texte (par défaut : vide)
@end table

@item 
`exclude_attrs' : ensemble de noms d'attributs qui ne doivent pas être sérialisés

@item 
`exclude_tags' : ensemble de noms de balises qui ne doivent pas être sérialisés
@end itemize

Dans la liste d'options ci-dessus, un « ensemble » fait référence à toute collection ou itérable de chaînes, aucun ordre n'est attendu.


Ajouté dans la version 3.8.

@end deffn

@geindex Comment() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree Comment}@anchor{36d9}
@deffn {Fonction} xml.etree.ElementTree.Comment (text=None)

Fabrique d’éléments de commentaire. Cette fonction crée un élément spécial qui sera sérialisé sous forme de commentaire XML par le sérialiseur standard. La chaîne de commentaire peut être une chaîne d'octets ou une chaîne Unicode. `text' est une chaîne contenant la chaîne de commentaire. Renvoie une instance d'élément représentant un commentaire.

Notez que @ref{a42,,XMLParser} ignore les commentaires dans l'entrée au lieu de créer des objets de commentaire pour eux. Un @ref{93b,,ElementTree} ne contiendra que des nœuds de commentaires qui ont été insérés dans l'arborescence à l'aide de l'une des méthodes d'@ref{305,,Element}.
@end deffn

@geindex dump() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree dump}@anchor{36da}
@deffn {Fonction} xml.etree.ElementTree.dump (elem)

Écrit une arborescence d'éléments ou une structure d'éléments dans `sys.stdout'. Cette fonction doit être utilisée uniquement pour le débogage.

Le format de sortie exact dépend de l’implémentation. Dans cette version, il est écrit sous la forme d'un fichier XML ordinaire.

`elem' est un élément de l'arborescence ou un élément individuel.


Modifié dans la version 3.8: la fonction @ref{36da,,dump()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.

@end deffn

@geindex fromstring() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree fromstring}@anchor{36c2}
@deffn {Fonction} xml.etree.ElementTree.fromstring (text, parser=None)

Analyse une section XML à partir d'une constante de chaîne. Identique à @ref{36db,,XML()}. `text' est une chaîne contenant des données XML. `parser' est une instance d'analyseur facultative. S'il n'est pas fourni, l'analyseur standard @ref{a42,,XMLParser} est utilisé. Renvoie une instance d'@ref{305,,Element}.
@end deffn

@geindex fromstringlist() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree fromstringlist}@anchor{11ae}
@deffn {Fonction} xml.etree.ElementTree.fromstringlist (sequence, parser=None)

Analyse un document XML à partir d'une séquence de fragments de chaîne. `séquence' est une liste ou une autre séquence contenant des fragments de données XML. `parser' est une instance d'analyseur facultative. S'il n'est pas fourni, l'analyseur standard @ref{a42,,XMLParser} est utilisé. Renvoie une instance d'@ref{305,,Element}.


Ajouté dans la version 3.2.

@end deffn

@geindex indent() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree indent}@anchor{36dc}
@deffn {Fonction} xml.etree.ElementTree.indent (tree, space='  ', level=0)

Ajoute des espaces au sous-arbre pour indenter visuellement l'arborescence. Cela peut être utilisé pour générer une sortie XML avec une mise en forme agréable. `tree' peut être un élément ou un `ElementTree'. `espace' est la chaîne d'espaces qui est insérée pour chaque niveau d'indentation, deux caractères d'espace par défaut. Pour indenter des sous-arbres partiels à l'intérieur d'un arbre déjà indenté, transmettez le niveau d'indentation initial dans `level'.


Ajouté dans la version 3.9.

@end deffn

@geindex iselement() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree iselement}@anchor{36dd}
@deffn {Fonction} xml.etree.ElementTree.iselement (element)

Vérifie si un objet semble être un objet élément valide. `element' est une instance d'élément. Renvoie @code{True} s'il s'agit d'un objet élément.
@end deffn

@geindex iterparse() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree iterparse}@anchor{270}
@deffn {Fonction} xml.etree.ElementTree.iterparse (source, events=None, parser=None)

Parses an XML section into an element tree incrementally, and reports what's
going on to the user.  `source' is a filename or @ref{11a0,,file object}
containing XML data.  `events' is a sequence of events to report back.  The
supported events are the strings @code{"start"}, @code{"end"}, @code{"comment"},
@code{"pi"}, @code{"start-ns"} and @code{"end-ns"}
(the "ns" events are used to get detailed namespace
information).  If `events' is omitted, only @code{"end"} events are reported.
`parser' is an optional parser instance.  If not given, the standard
@ref{a42,,XMLParser} parser is used.  `parser' must be a subclass of
@ref{a42,,XMLParser} and can only use the default @ref{a43,,TreeBuilder} as a
target. Returns an @ref{1aa,,iterator} providing @code{(event, elem)} pairs;
it has a @code{root} attribute that references the root element of the
resulting XML tree once `source' is fully read.
The iterator has the @code{close()} method that closes the internal
file object if `source' is a filename.

Notez que même si @ref{270,,iterparse()} construit l'arborescence de manière incrémentielle, il bloque pendant les lectures sur `source'. En tant que tel, il ne convient pas aux applications dans lesquelles le blocage pendant les lectures ne peut pas être effectué. Pour une analyse entièrement non bloquante, voir @ref{fdc,,XMLPullParser}.

@cartouche
@quotation Note 
@ref{270,,iterparse()} garantit uniquement qu'il a vu le caractère @code{">"} d'une balise de début lorsqu'il émet un événement @code{"start"}, donc les attributs sont définis mais le contenu des attributs `text' et `tail' n'est pas défini à ce stade. La même chose s'applique aux nœuds enfants de l'élément ; ils peuvent être présents ou non.

Si vous avez besoin d'un élément entièrement rempli, recherchez plutôt les événements @code{"end"}.
@end quotation
@end cartouche


Obsolète depuis la version 3.4: l'argument `parser'.



Modifié dans la version 3.8: les évènements @code{comment} et @code{pi} ont été ajoutés.



Modifié dans la version 3.13: Added the @code{close()} method.

@end deffn

@geindex parse() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree parse}@anchor{36de}
@deffn {Fonction} xml.etree.ElementTree.parse (source, parser=None)

Analyse une section XML dans une arborescence d'éléments. `source' est un nom de fichier ou un objet fichier contenant des données XML. `parser' (facultatif) est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard @ref{a42,,XMLParser} est utilisé. Renvoie une instance d'@ref{93b,,ElementTree}.
@end deffn

@geindex ProcessingInstruction() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ProcessingInstruction}@anchor{36df}
@deffn {Fonction} xml.etree.ElementTree.ProcessingInstruction (target, text=None)

Fabrique d’éléments `Processing Instruction' (PI). Cette fonction crée un élément spécial qui sera sérialisé en tant qu'instruction de traitement XML. `target' est une chaîne contenant la cible PI. `text' est une chaîne contenant le contenu de l'instruction de traitement (ou PI), s'il est fourni. Renvoie une instance d'élément, représentant l'instruction de traitement.

Note that @ref{a42,,XMLParser} skips over processing instructions
in the input instead of creating PI objects for them. An
@ref{93b,,ElementTree} will only contain processing instruction nodes if
they have been inserted into to the tree using one of the
@ref{305,,Element} methods.
@end deffn

@geindex register_namespace() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree register_namespace}@anchor{11af}
@deffn {Fonction} xml.etree.ElementTree.register_namespace (prefix, uri)

Enregistre un préfixe d'espace de noms. Le registre est global et toute correspondance existante pour le préfixe donné ainsi que l'URI de l'espace de noms sera supprimé. `prefix' est un préfixe d'espace de noms. `uri' est un URI d'espace de noms. Les balises et les attributs de cet espace de noms seront sérialisés avec le préfixe donné, si possible.


Ajouté dans la version 3.2.

@end deffn

@geindex SubElement() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree SubElement}@anchor{36d0}
@deffn {Fonction} xml.etree.ElementTree.SubElement (parent, tag, attrib=@{@}, **extra)

Fabrique de sous-élément. Cette fonction crée une instance d'élément et l'ajoute à un élément existant.

Le nom de l'élément, les noms d'attributs et les valeurs d'attributs peuvent être des chaînes d'octets ou des chaînes Unicode. `parent' est l'élément parent. `tag' est le nom du sous-élément. `attrib' est un dictionnaire facultatif contenant les attributs de l'élément. `extra' contient des attributs supplémentaires, donnés sous forme d'arguments nommés. Renvoie une instance d'élément.
@end deffn

@geindex tostring() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree tostring}@anchor{fde}
@deffn {Fonction} xml.etree.ElementTree.tostring (element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Génère une représentation sous forme de chaîne d'un élément XML, y compris tous les sous-éléments. `element' est une instance de @ref{305,,Element}. `encoding' @footnote{
La chaîne de caractères encodée inclue dans la sortie XML doit être conforme aux standards. Par exemple, @code{"UTF-8"} est valide, mais pas @code{"UTF8"}.  Voir @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl} et @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
} est l'encodage de sortie (la valeur par défaut est US-ASCII). Utilisez @code{encoding="unicode"} pour générer une chaîne Unicode (sinon, une chaîne d'octets est générée). `method' vaut @code{"xml"}, @code{"html"} ou @code{"text"} (la valeur par défaut est @code{"xml"}). `xml_declaration', `default_namespace' et `short_empty_elements' ont la même signification que dans @ref{fe0,,ElementTree.write()}. Renvoie une chaîne codée (éventuellement) contenant les données XML.


Modifié dans la version 3.4: Added the `short_empty_elements' parameter.



Modifié dans la version 3.8: Added the `xml_declaration' and `default_namespace' parameters.



Modifié dans la version 3.8: la fonction @ref{fde,,tostring()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.

@end deffn

@geindex tostringlist() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree tostringlist}@anchor{fdf}
@deffn {Fonction} xml.etree.ElementTree.tostringlist (element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)

Génère une représentation sous forme de chaîne d'un élément XML, y compris tous les sous-éléments. `element' est une instance de @ref{305,,Element}. `encoding' @footnote{
La chaîne de caractères encodée inclue dans la sortie XML doit être conforme aux standards. Par exemple, @code{"UTF-8"} est valide, mais pas @code{"UTF8"}.  Voir @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl} et @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
} est l'encodage de sortie (la valeur par défaut est US-ASCII). Utilisez @code{encoding="unicode"} pour générer une chaîne Unicode (sinon, une chaîne d'octets est générée). `method' vaut @code{"xml"}, @code{"html"} ou @code{"text"} (la valeur par défaut est @code{"xml"}). `xml_declaration', `default_namespace' et `short_empty_elements' ont la même signification que dans @ref{fe0,,ElementTree.write()}. Renvoie une liste de chaînes codées (éventuellement) contenant les données XML. Elle ne garantit aucune séquence spécifique, seulement @code{b"".join(tostringlist(element)) == tostring(element)}.


Ajouté dans la version 3.2.



Modifié dans la version 3.4: Added the `short_empty_elements' parameter.



Modifié dans la version 3.8: Added the `xml_declaration' and `default_namespace' parameters.



Modifié dans la version 3.8: la fonction @ref{fdf,,tostringlist()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.

@end deffn

@geindex XML() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XML}@anchor{36db}
@deffn {Fonction} xml.etree.ElementTree.XML (text, parser=None)

Analyse une section XML à partir d'une constante de chaîne. Cette fonction peut être utilisée pour intégrer des « littéraux XML » dans du code Python. `text' est une chaîne contenant des données XML. `parser', facultatif, est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard @ref{a42,,XMLParser} est utilisé. Renvoie une instance d'@ref{305,,Element}.
@end deffn

@geindex XMLID() (dans le module xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XMLID}@anchor{36e0}
@deffn {Fonction} xml.etree.ElementTree.XMLID (text, parser=None)

Analyse une section XML à partir d'une constante de chaîne et renvoie également un dictionnaire qui fait correspondre les identifiants d'éléments aux éléments. `text' est une chaîne contenant des données XML. `parser', facultatif, est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard @ref{a42,,XMLParser} est utilisé. Renvoie un `n'-uplet contenant une instance d'@ref{305,,Element} et un dictionnaire.
@end deffn

@node Prise en charge de XInclude,Référence<3>,Référence<2>,xml etree ElementTree --- The ElementTree XML API
@anchor{library/xml etree elementtree elementtree-xinclude}@anchor{36e1}@anchor{library/xml etree elementtree xinclude-support}@anchor{36e2}
@subsubsection Prise en charge de `XInclude'


Ce module fournit une prise en charge limitée des directives XInclude@footnote{https://www.w3.org/TR/xinclude/}, via le module d'assistance @ref{123,,xml.etree.ElementInclude}. Ce module peut être utilisé pour insérer des sous-arbres et des chaînes de texte dans des arborescences d'éléments, en fonction des informations contenues dans l'arborescence.

@menu
* Exemple: Exemple<9>. 

@end menu

@node Exemple<9>,,,Prise en charge de XInclude
@anchor{library/xml etree elementtree id3}@anchor{36e3}
@subsubsection Exemple


Voici un exemple qui montre l'utilisation du module `XInclude'. Pour inclure un document XML dans le document actuel, utilisez l'élément @code{@{http://www.w3.org/2001/XInclude@}include}, définissez l'attribut `parse' sur @code{"xml"}  et utilisez l'attribut `href' pour spécifier le document à inclure.

@example
<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>
@end example

Par défaut, l'attribut `href' est traité comme un nom de fichier. Vous pouvez utiliser des chargeurs personnalisés pour remplacer ce comportement. Notez également que l'assistant standard ne prend pas en charge la syntaxe `XPointer'.

Pour traiter ce fichier, chargez-le comme d'habitude et passez l'élément racine au module @ref{124,,xml.etree.ElementTree} :

@example
from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)
@end example

Le module `ElementInclude' remplace l'élément @code{@{http://www.w3.org/2001/XInclude@}include} par l'élément racine du document `source.xml'. Le résultat pourrait ressembler à ceci :

@example
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>This is a paragraph.</para>
</document>
@end example

Si l'attribut `parse' est omis, sa valeur par défaut est @code{"xml"}. L'attribut `href' est obligatoire.

Pour inclure un document texte, utilisez l'élément @code{@{http://www.w3.org/2001/XInclude@}include} et définissez l'attribut `parse' sur @code{"text"} :

@example
<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>
@end example

Le résultat pourrait ressembler à ceci :

@example
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) 2003.
</document>
@end example

@node Référence<3>,,Prise en charge de XInclude,xml etree ElementTree --- The ElementTree XML API
@anchor{library/xml etree elementtree id4}@anchor{36e4}
@subsubsection Référence


@menu
* Fonctions: Fonctions<10>. 
* Objets Element:: 
* Objets ElementTree:: 
* Objets QName:: 
* Objets TreeBuilder:: 
* Objets XMLParser:: 
* Objets XMLPullParser:: 
* Exceptions: Exceptions<19>. 

@end menu

@node Fonctions<10>,Objets Element,,Référence<3>
@anchor{library/xml etree elementtree elementinclude-functions}@anchor{36e5}@anchor{library/xml etree elementtree id5}@anchor{36e6}
@subsubsection Fonctions


@geindex module; xml.etree.ElementInclude

@geindex default_loader() (dans le module xml.etree.ElementInclude)
@anchor{library/xml etree elementtree module-xml etree ElementInclude}@anchor{123}@anchor{library/xml etree elementtree xml etree ElementInclude default_loader}@anchor{36e7}
@deffn {Fonction} xml.etree.ElementInclude.default_loader (href, parse, encoding=None)

Default loader. This default loader reads an included resource from disk.
`href' is a URL.  `parse' is for parse mode either "xml" or "text".
`encoding' is an optional text encoding.  If not given, encoding is @code{utf-8}.
Returns the expanded resource.
If the parse mode is @code{"xml"}, this is an @ref{305,,Element} instance.
If the parse mode is @code{"text"}, this is a string.
If the loader fails, it can return @code{None} or raise an exception.
@end deffn

@geindex include() (dans le module xml.etree.ElementInclude)
@anchor{library/xml etree elementtree xml etree ElementInclude include}@anchor{36e8}
@deffn {Fonction} xml.etree.ElementInclude.include (elem, loader=None, base_url=None, max_depth=6)

This function expands XInclude directives in-place in tree pointed by `elem'.
`elem' is either the root @ref{305,,Element} or an
@ref{93b,,ElementTree} instance to find such element.
`loader' is an optional resource loader.  If omitted, it defaults to @ref{36e7,,default_loader()}.
If given, it should be a callable that implements the same interface as
@ref{36e7,,default_loader()}.  `base_url' is base URL of the original file, to resolve
relative include file references.  `max_depth' is the maximum number of recursive
inclusions.  Limited to reduce the risk of malicious content explosion.
Pass @code{None} to disable the limitation.


Modifié dans la version 3.9: Added the `base_url' and `max_depth' parameters.

@end deffn

@node Objets Element,Objets ElementTree,Fonctions<10>,Référence<3>
@anchor{library/xml etree elementtree element-objects}@anchor{36e9}@anchor{library/xml etree elementtree elementtree-element-objects}@anchor{36ea}
@subsubsection Objets `Element'


@geindex Element (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree Element}@anchor{305}
@deffn {Classe} xml.etree.ElementTree.Element (tag, attrib=@{@}, **extra)

Classe Element.  Cette classe définit l'interface Element et fournit une implémentation de référence de cette interface.

Le nom de l'élément, les noms d'attributs et les valeurs d'attributs peuvent être des chaînes d'octets ou des chaînes Unicode. `tag' est le nom de l'élément. `attrib' est un dictionnaire facultatif contenant les attributs des éléments. `extra' contient des attributs supplémentaires, donnés sous forme d'arguments nommés.

@geindex tag (attribut xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element tag}@anchor{132c}
@deffn {Attribut} tag

Chaîne identifiant le type de données que cet élément représente (en d'autres termes, le type d'élément).
@end deffn

@geindex text (attribut xml.etree.ElementTree.Element)
@geindex tail (attribut xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element text}@anchor{36c9}
@deffn {Attribut} text
@anchor{library/xml etree elementtree xml etree ElementTree Element tail}@anchor{36eb}
@deffnx {Attribut} tail

Ces attributs peuvent être utilisés pour contenir des données supplémentaires associées à l'élément. Leurs valeurs sont généralement des chaînes mais peuvent être n'importe quel objet spécifique à une application. Si l'élément est créé à partir d'un fichier XML, l'attribut `text' contient soit le texte entre la balise de début de l'élément et sa première balise enfant ou de fin, soit @code{None} ; l'attribut `tail' contient soit le texte entre la balise de fin de l'élément et la balise suivante, soit @code{None}. Pour les données XML

@example
<a><b>1<c>2<d/>3</c></b>4</a>
@end example

les attributs `text' et `tail' de l'élément `a' valent @code{None}, l'attribut `text' de l'élément `b' vaut @code{"1"} et `tail' vaut @code{"4"}, l'attribut `text' de l'élément `c' vaut @code{"2"} et `tail' vaut @code{None}, et l'attribut `text' de l'élément `d' vaut @code{None} et `tail' vaut @code{"3"}.

Pour récupérer le texte interne d'un élément, voir @ref{11b2,,itertext()}, par exemple @code{"".join(element.itertext())}.

Les applications peuvent stocker des objets arbitraires dans ces attributs.
@end deffn

@geindex attrib (attribut xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element attrib}@anchor{36ec}
@deffn {Attribut} attrib

Dictionnaire contenant les attributs de l'élément. Notez que même si la valeur `attrib' est toujours un véritable dictionnaire Python mutable, une implémentation d'`ElementTree' peut choisir d'utiliser une autre représentation interne et de créer le dictionnaire uniquement si quelqu'un le demande. Pour profiter de telles implémentations, utilisez les méthodes de dictionnaire ci-dessous autant que possible.
@end deffn

Les méthodes dictionnaire-compatibles suivantes traitent les attributs de l'élément.

@geindex clear() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element clear}@anchor{36ed}
@deffn {Méthode} clear ()

Réinitialise un élément. Cette fonction supprime tous les sous-éléments, efface tous les attributs et définit les attributs `text' et `tail' sur @code{None}.
@end deffn

@geindex get() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element get}@anchor{36ca}
@deffn {Méthode} get (key, default=None)

Accède à l'attribut de l'élément nommé `key'.

Renvoie la valeur de l'attribut ou `default' si l'attribut n'a pas été trouvé.
@end deffn

@geindex items() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element items}@anchor{36ee}
@deffn {Méthode} items ()

Renvoie les attributs de l'élément comme une séquence de paire (nom, valeur). Les attributs sont renvoyés dans un ordre arbitraire.
@end deffn

@geindex keys() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element keys}@anchor{36ef}
@deffn {Méthode} keys ()

Renvoie les noms d'attributs des éléments sous forme de liste. Les noms sont renvoyés dans un ordre arbitraire.
@end deffn

@geindex set() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element set}@anchor{36cc}
@deffn {Méthode} set (key, value)

Change l'attribut `key' à l'élément `value'.
@end deffn

Les méthodes suivantes traitent les éléments enfants (sous-éléments).

@geindex append() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element append}@anchor{36cd}
@deffn {Méthode} append (subelement)

Ajoute l'élément `subelement' à la fin de la liste interne des sous-éléments de cet élément. Lève une @ref{522,,TypeError} si `subelement' n'est pas un @ref{305,,Element}.
@end deffn

@geindex extend() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element extend}@anchor{11b0}
@deffn {Méthode} extend (subelements)

Appends `subelements' from an iterable of elements.
Raises @ref{522,,TypeError} if a subelement is not an @ref{305,,Element}.


Ajouté dans la version 3.2.

@end deffn

@geindex find() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element find}@anchor{36c8}
@deffn {Méthode} find (match, namespaces=None)

Recherche le premier sous-élément correspondant à `match'. `match' peut être un nom de balise ou un @ref{b9b,,path}. Renvoie une instance d'élément ou @code{None}. `namespaces' est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets. Passez @code{'@w{'}} comme préfixe pour déplacer tous les noms de balises sans préfixe dans l'expression dans l'espace de noms donné.
@end deffn

@geindex findall() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element findall}@anchor{36c7}
@deffn {Méthode} findall (match, namespaces=None)

Recherche tous les sous-éléments correspondants, par nom de balise ou @ref{b9b,,path}. Renvoie une liste contenant tous les éléments correspondants dans l'ordre du document. `namespaces' est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets. Passez @code{'@w{'}} comme préfixe pour déplacer tous les noms de balises sans préfixe dans l'expression dans l'espace de noms donné.
@end deffn

@geindex findtext() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element findtext}@anchor{36f0}
@deffn {Méthode} findtext (match, default=None, namespaces=None)

Recherche le texte du premier sous-élément correspondant à `match'. `match' peut être un nom de balise ou un @ref{b9b,,path}. Renvoie le contenu textuel du premier élément correspondant, ou `default' si aucun élément n'a été trouvé. Notez que si l'élément correspondant n'a pas de contenu textuel, une chaîne vide est renvoyée. `namespaces' est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets. Passez @code{'@w{'}} comme préfixe pour déplacer tous les noms de balises sans préfixe dans l'expression dans l'espace de noms donné.
@end deffn

@geindex insert() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element insert}@anchor{36f1}
@deffn {Méthode} insert (index, subelement)

Insère le `subelement' à la position donnée dans cet élément. Lève une @ref{522,,TypeError} si `subelement' n'est pas un @ref{305,,Element}.
@end deffn

@geindex iter() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element iter}@anchor{132d}
@deffn {Méthode} iter (tag=None)

Crée un @ref{1aa,,itérateur} sur l'arbre  avec l'élément actuel comme racine. L'itérateur parcourt cet élément et tous les éléments situés en dessous, dans l'ordre du document (profondeur en premier). Si `tag' n'est pas @code{None} ou @code{'*'}, seuls les éléments dont la balise est égale à `tag' sont renvoyés par l'itérateur. Si l'arborescence est modifiée au cours de l'itération, le résultat est indéfini.


Ajouté dans la version 3.2.

@end deffn

@geindex iterfind() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element iterfind}@anchor{11b1}
@deffn {Méthode} iterfind (match, namespaces=None)

Recherche tous les sous-éléments correspondants, par nom de balise ou @ref{b9b,,path}. Renvoie un itérable donnant tous les éléments correspondants dans l'ordre du document. `namespaces' est un tableau de correspondances facultatif de préfixes d'espaces de noms vers des noms complets.


Ajouté dans la version 3.2.

@end deffn

@geindex itertext() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element itertext}@anchor{11b2}
@deffn {Méthode} itertext ()

Crée un itérateur de texte. L'itérateur parcourt cet élément et tous les sous-éléments, dans l'ordre du document, et renvoie tout le texte interne.


Ajouté dans la version 3.2.

@end deffn

@geindex makeelement() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element makeelement}@anchor{36f2}
@deffn {Méthode} makeelement (tag, attrib)

Crée un nouvel objet élément du même type que cet élément. N'appelez pas cette méthode, utilisez plutôt la fonction de fabrique @ref{36d0,,SubElement()}.
@end deffn

@geindex remove() (méthode xml.etree.ElementTree.Element)
@anchor{library/xml etree elementtree xml etree ElementTree Element remove}@anchor{36ce}
@deffn {Méthode} remove (subelement)

Supprime le `subelement' de l'élément. Contrairement aux méthodes `find*', cette méthode compare les éléments en fonction de l'identité de l'instance, et non de la valeur ou du contenu de la balise.
@end deffn

Les objets @ref{305,,Element} prennent également en charge les méthodes de type séquence suivantes pour travailler avec des sous éléments : @ref{12aa,,__delitem__()}, @ref{280,,__getitem__()}, @ref{12a9,,__setitem__()}, @ref{1ee5,,__len__()}.

Caution: Elements with no subelements will test as @code{False}.  In a future
release of Python, all elements will test as @code{True} regardless of whether
subelements exist.  Instead, prefer explicit @code{len(elem)} or
@code{elem is not None} tests.:

@example
element = root.find('foo')

if not element:  # careful!
    print("element not found, or element has no subelements")

if element is None:
    print("element not found")
@end example


Modifié dans la version 3.12: Testing the truth value of an Element emits @ref{1a3,,DeprecationWarning}.


Avant Python 3.8, l'ordre de sérialisation des attributs XML des éléments était artificiellement rendu prévisible en classant les attributs par leur nom. Sur la base de l'ordre désormais garanti des dictionnaires, cette réorganisation arbitraire a été supprimée dans Python 3.8 pour préserver l'ordre dans lequel les attributs ont été initialement analysés ou créés par le code utilisateur.

En général, le code utilisateur doit essayer de ne pas dépendre d'un ordre spécifique des attributs, étant donné que la documentation de référence XML@footnote{https://www.w3.org/TR/xml-infoset/} exclut explicitement que l'ordre des attributs soit porteur d'information. Le code doit être prêt à gérer tout ordre en entrée. Dans les cas où une sortie XML déterministe est requise, par exemple pour la signature cryptographique ou les ensembles de données de test, la sérialisation canonique est disponible avec la fonction @ref{36d8,,canonicalize()}.

Dans les cas où la sortie canonique n'est pas applicable mais où un ordre d'attributs spécifique est quand même souhaitable en sortie, le code doit viser à créer les attributs directement dans l'ordre souhaité, afin d'éviter des inadéquations de perception pour les lecteurs du code. Dans les cas où cela est difficile à réaliser, une recette comme ci-dessous peut être appliquée avant la sérialisation pour appliquer un ordre indépendant de la création de l'élément :

@example
def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)
@end example
@end deffn

@node Objets ElementTree,Objets QName,Objets Element,Référence<3>
@anchor{library/xml etree elementtree elementtree-elementtree-objects}@anchor{36f3}@anchor{library/xml etree elementtree elementtree-objects}@anchor{36f4}
@subsubsection Objets `ElementTree'


@geindex ElementTree (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree}@anchor{93b}
@deffn {Classe} xml.etree.ElementTree.ElementTree (element=None, file=None)

Classe enveloppant `ElementTree'. Cette classe représente une hiérarchie d'éléments entière et ajoute une prise en charge supplémentaire pour la sérialisation vers et depuis le XML standard.

`element' est l'élément racine. L'arborescence est initialisée avec le contenu du fichier XML `file' s'il est fourni.

@geindex _setroot() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree _setroot}@anchor{36f5}
@deffn {Méthode} _setroot (element)

Remplace l'élément racine de cette arborescence. Cela supprime le contenu actuel de l'arborescence et le remplace par l'élément donné. À utiliser avec précaution. `element' est une instance d'élément.
@end deffn

@geindex find() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree find}@anchor{36f6}
@deffn {Méthode} find (match, namespaces=None)

Comme @ref{36c8,,Element.find()}, commence à la racine de l'arbre.
@end deffn

@geindex findall() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree findall}@anchor{36f7}
@deffn {Méthode} findall (match, namespaces=None)

Identique à @ref{36c7,,Element.findall()}, en commençant à la racine de l'arborescence.
@end deffn

@geindex findtext() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree findtext}@anchor{36f8}
@deffn {Méthode} findtext (match, default=None, namespaces=None)

Identique à @ref{36f0,,Element.findtext()}, en commençant à la racine de l'arborescence.
@end deffn

@geindex getroot() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree getroot}@anchor{36f9}
@deffn {Méthode} getroot ()

Renvoie l'élément racine de l'arbre.
@end deffn

@geindex iter() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree iter}@anchor{36fa}
@deffn {Méthode} iter (tag=None)

Crée et renvoie un itérateur d'arborescence pour l'élément racine. L'itérateur parcourt tous les éléments de cette arborescence, dans l'ordre des sections. `tag' est la balise à rechercher (la valeur par défaut est de renvoyer tous les éléments).
@end deffn

@geindex iterfind() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree iterfind}@anchor{36fb}
@deffn {Méthode} iterfind (match, namespaces=None)

Identique à @ref{11b1,,Element.iterfind()}, en commençant à la racine de l'arborescence.


Ajouté dans la version 3.2.

@end deffn

@geindex parse() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree parse}@anchor{36fc}
@deffn {Méthode} parse (source, parser=None)

Charge une section XML externe dans cette arborescence d'éléments. `source' est un nom de fichier ou un @ref{11a0,,objet fichier}. `parser', facultatif, est une instance d'analyseur. S'il n'est pas fourni, l'analyseur standard @ref{a42,,XMLParser} est utilisé. Renvoie l'élément racine de la section.
@end deffn

@geindex write() (méthode xml.etree.ElementTree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ElementTree write}@anchor{fe0}
@deffn {Méthode} write (file, encoding='us-ascii', xml_declaration=None, default_namespace=None, method='xml', *, short_empty_elements=True)

Écrit l'arborescence des éléments dans un fichier, au format XML. `file' est un nom de fichier ou un @ref{11a0,,objet fichier} ouvert en écriture. `encoding' @footnote{
La chaîne de caractères encodée inclue dans la sortie XML doit être conforme aux standards. Par exemple, @code{"UTF-8"} est valide, mais pas @code{"UTF8"}.  Voir @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl} et @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
} est l'encodage de sortie (la valeur par défaut est US-ASCII). `xml_declaration' contrôle si une déclaration XML doit être ajoutée au fichier. Utilisez @code{False} pour jamais, @code{True} pour toujours, @code{None} pour seulement si ce n'est pas de l'US-ASCII ou de l'UTF-8 ou de l'Unicode (la valeur par défaut est @code{None}). `default_namespace' définit l'espace de noms XML par défaut (pour @code{"xmlns"}). `method' vaut @code{"xml"}, @code{"html"} ou @code{"text"} (la valeur par défaut est @code{"xml"}). Le paramètre nommé (uniquement) `short_empty_elements' contrôle le formatage des éléments qui ne contiennent aucun contenu. Si c'est @code{True} (valeur par défaut), ils sont écrits sous la forme d'une seule balise auto-fermée, sinon ils sont écrits sous la forme d'une paire de balises de début-fin.

La sortie est une chaîne (@ref{435,,str}) ou du binaire (@ref{1bd,,bytes}). C'est contrôlé par l'argument `encoding'. Si `encoding' est @code{"unicode"}, la sortie est une chaîne ; sinon, c'est binaire. Notez que cela peut entrer en conflit avec le type de `fichier' s'il s'agit d'un @ref{11a0,,objet fichier} déjà ouvert ; assurez-vous de ne pas essayer d'écrire une chaîne dans un flux binaire et vice versa.


Modifié dans la version 3.4: Added the `short_empty_elements' parameter.



Modifié dans la version 3.8: la méthode @ref{fe0,,write()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.

@end deffn
@end deffn

Voici le fichier XML à manipuler :

@example
<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>Moved to <a href="http://example.org/">example.org</a>
        or <a href="http://example.com/">example.com</a>.</p>
    </body>
</html>
@end example

Exemple de modification de l'attribut `target' de chaque lien dans le premier paragraphe :

@example
>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Iterates through all found links
...     i.attrib["target"] = "blank"
...
>>> tree.write("output.xhtml")
@end example

@node Objets QName,Objets TreeBuilder,Objets ElementTree,Référence<3>
@anchor{library/xml etree elementtree elementtree-qname-objects}@anchor{36fd}@anchor{library/xml etree elementtree qname-objects}@anchor{36fe}
@subsubsection Objets `QName'


@geindex QName (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree QName}@anchor{36ff}
@deffn {Classe} xml.etree.ElementTree.QName (text_or_uri, tag=None)

Surcouche à `QName'. Cela peut être utilisé pour envelopper une valeur d'attribut `QName', afin d'obtenir une gestion appropriée de l'espace de noms en sortie. `text_or_uri' est une chaîne contenant la valeur `QName', sous la forme `@{uri@}local' ou, si l'argument `tag' est donné, la partie URI d'un `QName'. Si `tag' est donné, le premier argument est interprété comme un URI et cet argument est interprété comme un nom local. Les instances @ref{36ff,,QName} sont opaques.
@end deffn

@node Objets TreeBuilder,Objets XMLParser,Objets QName,Référence<3>
@anchor{library/xml etree elementtree elementtree-treebuilder-objects}@anchor{3700}@anchor{library/xml etree elementtree treebuilder-objects}@anchor{3701}
@subsubsection Objets `TreeBuilder'


@geindex TreeBuilder (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder}@anchor{a43}
@deffn {Classe} xml.etree.ElementTree.TreeBuilder (element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)

Générateur de structure d'éléments générique. Ce constructeur convertit une séquence d'appels de méthode `start', `data', `end', `comment' et `pi' en une structure d'éléments bien formée. Vous pouvez utiliser cette classe pour créer une structure d'éléments à l'aide d'un analyseur XML personnalisé ou d'un analyseur pour un autre type de format XML.

`element_factory', lorsqu'il est donné, doit être un appelable acceptant deux arguments positionnels : une balise et un dictionnaire d'attributs. Elle est censée renvoyer une nouvelle instance d'élément.

Les fonctions `comment_factory' et `pi_factory', lorsqu'elles sont données, doivent se comporter comme les fonctions @ref{36d9,,Comment()} et @ref{36df,,ProcessingInstruction()} pour créer des commentaires et des instructions de traitement. Lorsqu’elles ne sont pas fournies, les fabriques par défaut sont utilisées. Lorsque `insert_comments' ou `insert_pis' sont vraies, les commentaires et instructions de traitement sont insérés dans l'arborescence s'ils apparaissent dans l'élément racine (mais pas à l'extérieur de celui-ci).

@geindex close() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder close}@anchor{3702}
@deffn {Méthode} close ()

Vide les tampons du générateur et renvoie l'élément de document de niveau supérieur. Renvoie une instance d'@ref{305,,Element}.
@end deffn

@geindex data() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder data}@anchor{3703}
@deffn {Méthode} data (data)

Ajoute du texte à l'élément courant.  `data' est une chaîne de caractères.  Cela peut être une chaîne d'octets ou une chaîne Unicode.
@end deffn

@geindex end() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder end}@anchor{11b3}
@deffn {Méthode} end (tag)

Ferme l'élément courant.  `tag' est le nom de l'élément.  Renvoie l'élément fermé.
@end deffn

@geindex start() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder start}@anchor{1911}
@deffn {Méthode} start (tag, attrs)

Ouvre un nouvel élément. `tag' est le nom de l'élément. `attrs' est un dictionnaire contenant les attributs de l'élément. Renvoie l'élément ouvert.
@end deffn

@geindex comment() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder comment}@anchor{3704}
@deffn {Méthode} comment (text)

Crée un commentaire avec le `text' donné. Si @code{insert_comments} est vrai, cela l'ajoute également à l'arborescence.


Ajouté dans la version 3.8.

@end deffn

@geindex pi() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder pi}@anchor{3705}
@deffn {Méthode} pi (target, text)

Creates a process instruction with the given `target' name and `text'.
If @code{insert_pis} is true, this will also add it to the tree.


Ajouté dans la version 3.8.

@end deffn

De plus, un objet @ref{a43,,TreeBuilder} personnalisé peut fournir les méthodes suivantes :

@geindex doctype() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder doctype}@anchor{a85}
@deffn {Méthode} doctype (name, pubid, system)

Gère une déclaration `doctype'. `name' est le nom du type de document. `pubid' est l'identifiant public. `system' est l'identifiant du système. Cette méthode n'existe pas sur la classe par défaut @ref{a43,,TreeBuilder}.


Ajouté dans la version 3.2.

@end deffn

@geindex start_ns() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder start_ns}@anchor{3706}
@deffn {Méthode} start_ns (prefix, uri)

Est appelée chaque fois que l'analyseur rencontre une nouvelle déclaration d'espace de noms, avant le rappel @code{start()} pour l'élément d'ouverture qui le définit. `prefix' est @code{'@w{'}} pour l'espace de noms par défaut et le nom du préfixe d'espace de noms déclaré dans le cas contraire. `uri' est l'URI de l'espace de noms.


Ajouté dans la version 3.8.

@end deffn

@geindex end_ns() (méthode xml.etree.ElementTree.TreeBuilder)
@anchor{library/xml etree elementtree xml etree ElementTree TreeBuilder end_ns}@anchor{3707}
@deffn {Méthode} end_ns (prefix)

Est appelée après le rappel @code{end()} d'un élément qui a déclaré une correspondance de préfixe d'espace de noms, avec le nom du `prefix' qui passe hors de portée.


Ajouté dans la version 3.8.

@end deffn
@end deffn

@geindex C14NWriterTarget (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree C14NWriterTarget}@anchor{3708}
@deffn {Classe} xml.etree.ElementTree.C14NWriterTarget (write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None)

Écrivain C14N 2.0@footnote{https://www.w3.org/TR/xml-c14n2/}. Les arguments sont les mêmes que pour la fonction @ref{36d8,,canonicalize()}. Cette classe ne construit pas d'arborescence mais traduit les événements de rappel directement sous une forme sérialisée à l'aide de la fonction `write'.


Ajouté dans la version 3.8.

@end deffn

@node Objets XMLParser,Objets XMLPullParser,Objets TreeBuilder,Référence<3>
@anchor{library/xml etree elementtree elementtree-xmlparser-objects}@anchor{3709}@anchor{library/xml etree elementtree xmlparser-objects}@anchor{370a}
@subsubsection Objets `XMLParser'


@geindex XMLParser (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser}@anchor{a42}
@deffn {Classe} xml.etree.ElementTree.XMLParser (*, target=None, encoding=None)

Cette classe est l’élément de base du module. Elle utilise @ref{125,,xml.parsers.expat} pour une analyse efficace du XML et fonctionne à base d'événements. Elle peut être alimentée en données XML de manière incrémentielle avec la méthode @ref{370b,,feed()}, et les événements d'analyse sont traduits en une API à flux poussé – en appelant les méthodes de rappel de l'objet `target'. Si `target' est omis, le @ref{a43,,TreeBuilder} standard est utilisé. Si `encoding' @footnote{
La chaîne de caractères encodée inclue dans la sortie XML doit être conforme aux standards. Par exemple, @code{"UTF-8"} est valide, mais pas @code{"UTF8"}.  Voir @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl} et @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
} est donné, la valeur remplace l'encodage spécifié dans le fichier XML.


Modifié dans la version 3.8: Parameters are now @ref{2a2,,keyword-only}.
The `html' argument is no longer supported.


@geindex close() (méthode xml.etree.ElementTree.XMLParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser close}@anchor{370c}
@deffn {Méthode} close ()

Termine l'envoi des données à l'analyseur. Renvoie le résultat de l'appel de la méthode @code{close()} de la `target' passée lors de la construction ; par défaut, il s'agit de l'élément de plus haut niveau du document.
@end deffn

@geindex feed() (méthode xml.etree.ElementTree.XMLParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser feed}@anchor{370b}
@deffn {Méthode} feed (data)

Fournit des données à l’analyseur. `data' est une donnée encodée.
@end deffn

@geindex flush() (méthode xml.etree.ElementTree.XMLParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLParser flush}@anchor{26c}
@deffn {Méthode} flush ()

Triggers parsing of any previously fed unparsed data, which can be
used to ensure more immediate feedback, in particular with Expat >=2.6.0.
The implementation of @ref{26c,,flush()} temporarily disables reparse deferral
with Expat (if currently enabled) and triggers a reparse.
Disabling reparse deferral has security consequences; please see
@ref{26f,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()} for details.

Note that @ref{26c,,flush()} has been backported to some prior releases of
CPython as a security fix.  Check for availability of @ref{26c,,flush()}
using @ref{4bb,,hasattr()} if used in code running across a variety of Python
versions.


Ajouté dans la version 3.13.

@end deffn

@ref{370b,,XMLParser.feed()} appelle la méthode @code{start(tag, attrs_dict)} de `target' pour chaque balise d'ouverture, sa méthode @code{end(tag)} pour chaque balise de fermeture, et les données sont traitées par la méthode @code{data(data)}. Pour d'autres méthodes de rappel prises en charge, consultez la classe @ref{a43,,TreeBuilder}. @ref{370c,,XMLParser.close()} appelle la méthode @code{close()} de `target'. @ref{a42,,XMLParser} peut être utilisée pour autre chose que seulement construire une structure arborescente. Voici un exemple de comptage de la profondeur maximale d'un fichier XML :

@example
>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4
@end example
@end deffn

@node Objets XMLPullParser,Exceptions<19>,Objets XMLParser,Référence<3>
@anchor{library/xml etree elementtree elementtree-xmlpullparser-objects}@anchor{370d}@anchor{library/xml etree elementtree xmlpullparser-objects}@anchor{370e}
@subsubsection Objets `XMLPullParser'


@geindex XMLPullParser (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser}@anchor{fdc}
@deffn {Classe} xml.etree.ElementTree.XMLPullParser (events=None)

Analyseur à flux tiré adapté aux applications non bloquantes. Son API côté entrée est similaire à celle de @ref{a42,,XMLParser}, mais au lieu de pousser les appels vers une cible de rappel, @ref{fdc,,XMLPullParser} collecte une liste interne d'événements d'analyse et permet à l'utilisateur de la lire. `events' est une séquence d'événements à signaler. Les événements pris en charge sont les chaînes @code{"start"}, @code{"end"}, @code{"comment"}, @code{"pi"}, @code{"start-ns"} et @code{"end-ns"} (les événements @code{"ns"} sont utilisés pour obtenir des informations détaillées sur les espaces de noms). Si `events' est omis, seuls les événements @code{"end"} sont rapportés.

@geindex feed() (méthode xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser feed}@anchor{36c4}
@deffn {Méthode} feed (data)

Transmet les données d’octets à l’analyseur.
@end deffn

@geindex flush() (méthode xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser flush}@anchor{26d}
@deffn {Méthode} flush ()

Triggers parsing of any previously fed unparsed data, which can be
used to ensure more immediate feedback, in particular with Expat >=2.6.0.
The implementation of @ref{26d,,flush()} temporarily disables reparse deferral
with Expat (if currently enabled) and triggers a reparse.
Disabling reparse deferral has security consequences; please see
@ref{26f,,xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()} for details.

Note that @ref{26d,,flush()} has been backported to some prior releases of
CPython as a security fix.  Check for availability of @ref{26d,,flush()}
using @ref{4bb,,hasattr()} if used in code running across a variety of Python
versions.


Ajouté dans la version 3.13.

@end deffn

@geindex close() (méthode xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser close}@anchor{370f}
@deffn {Méthode} close ()

Signale à l'analyseur que le flux de données est terminé. Contrairement à @ref{370c,,XMLParser.close()}, cette méthode renvoie toujours @ref{660,,None}. Tous les événements non encore récupérés lorsque l'analyseur est fermé peuvent toujours être lus avec @ref{36c5,,read_events()}.
@end deffn

@geindex read_events() (méthode xml.etree.ElementTree.XMLPullParser)
@anchor{library/xml etree elementtree xml etree ElementTree XMLPullParser read_events}@anchor{36c5}
@deffn {Méthode} read_events ()

Renvoie un itérateur sur les événements qui ont été rencontrés dans les données fournies à l'analyseur. L'itérateur génère des paires @code{(event, elem)}, où `event' est une chaîne représentant le type d'événement (par exemple @code{"end"}) et `elem' est l'objet @ref{305,,Element} rencontré, ou une autre valeur de contexte comme suit.


@itemize *

@item 
@code{start}, @code{end} : l'élément actuel.

@item 
@code{comment}, @code{pi} : le commentaire ou l'instruction de traitement actuel

@item 
@code{start-ns} : couple @code{(prefix, uri)} nommant la correspondance d'espace de noms déclarée.

@item 
@code{end-ns} : @ref{660,,None} (cela peut changer dans une version future)
@end itemize

Les événements fournis lors d'un appel précédent à @ref{36c5,,read_events()} ne seront plus renvoyés. Les événements sont consommés à partir de la file d'attente interne uniquement lorsqu'ils sont récupérés de l'itérateur, donc plusieurs lecteurs itérant en parallèle sur les itérateurs obtenus à partir de @ref{36c5,,read_events()} auront des résultats imprévisibles.
@end deffn

@cartouche
@quotation Note 
@ref{fdc,,XMLPullParser} garantit uniquement qu'il a vu le caractère @code{">"} d'une balise de début lorsqu'il émet un événement @code{"start"}, donc les attributs sont définis, mais le contenu des attributs `text' et `tail' n'est pas défini à ce stade. La même chose s'applique aux nœuds enfants de l'élément ; ils peuvent être présents ou non.

Si vous avez besoin d'un élément entièrement rempli, recherchez plutôt les événements @code{"end"}.
@end quotation
@end cartouche


Ajouté dans la version 3.4.



Modifié dans la version 3.8: les évènements @code{comment} et @code{pi} ont été ajoutés.

@end deffn

@node Exceptions<19>,,Objets XMLPullParser,Référence<3>
@anchor{library/xml etree elementtree exceptions}@anchor{3710}
@subsubsection Exceptions


@geindex ParseError (classe dans xml.etree.ElementTree)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError}@anchor{1256}
@deffn {Classe} xml.etree.ElementTree.ParseError

Erreur d'analyse XML, générée par les différentes méthodes d'analyse de ce module lorsque l'analyse échoue. La représentation sous forme de chaîne d'une instance de cette exception contient un message d'erreur convivial. De plus, elle possède les attributs suivants :

@geindex code (attribut xml.etree.ElementTree.ParseError)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError code}@anchor{3711}
@deffn {Attribut} code

Code d'erreur numérique de l'analyseur `expat'. Voir la documentation de @ref{125,,xml.parsers.expat} pour la liste des codes d'erreur et leur signification.
@end deffn

@geindex position (attribut xml.etree.ElementTree.ParseError)
@anchor{library/xml etree elementtree xml etree ElementTree ParseError position}@anchor{3712}
@deffn {Attribut} position

Un `n'-uplet de numéros de `ligne' et `colonne' indiquant le lieu d'apparition de l'erreur.
@end deffn
@end deffn

@subsubheading Notes


@node xml dom --- The Document Object Model API,xml dom minidom --- Minimal DOM implementation,xml etree ElementTree --- The ElementTree XML API,Outils de traitement de balises structurées
@anchor{library/xml dom doc}@anchor{3713}@anchor{library/xml dom module-xml dom}@anchor{120}@anchor{library/xml dom xml-dom-the-document-object-model-api}@anchor{3714}
@subsection @code{xml.dom} --- The Document Object Model API


@geindex module; xml.dom

`Code source:' Lib/xml/dom/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/dom/__init__.py}


__________________________________________________________________


Le Document Object Model, ou "DOM," est une API inter-langage du World Wide Web Consortium (`W3C') pour accéder et modifier les documents XML. Une implémentation DOM présente le document XML comme un arbre ou autorise le code client à construire une telle structure depuis zéro. Il permet alors d'accéder à la structure à l'aide d'un ensemble d'objet qui fournissent des interfaces bien connues.

Le DOM est extrêmement utile pour les applications à accès aléatoire. SAX ne vous permet de visualiser qu'un seul morceau du document à la fois. Si vous regardez un élément SAX, vous n'avez pas accès à un autre.  Si vous regardez un nœud de texte, vous n'avez pas accès à un élément parent. Lorsque vous écrivez une application SAX, vous devez suivre la position de votre programme dans le document quelque part dans votre propre code. SAX ne le fait pas pour vous. De plus, si vous devez examiner un nœud plus lus loin dans le document XML, vous n'avez pas de chance.

Il est tout simplement impossible d'implémenter certains algorithmes avec un modèle évènementiel, sans un accès à un arbre. Bien sûr, vous pourriez construire vous même un arbre à partir des événements SAX mais DOM vous permet d'éviter d'écrire ce code. Le DOM est représentation standard en arbre pour des données XML.

Le DOM (Document Object Model) est défini par le `W3C' en étapes ou `"levels"' (niveaux) selon leur terminologie. Le couplage de l'API de Python est essentiellement basée sur la recommandation DOM Level 2.

@c What if your needs are somewhere between SAX and the DOM?  Perhaps
@c you cannot afford to load the entire tree in memory but you find the
@c SAX model somewhat cumbersome and low-level.  There is also a module
@c called xml.dom.pulldom that allows you to build trees of only the
@c parts of a document that you need structured access to.  It also has
@c features that allow you to find your way around the DOM.
@c See http://www.prescod.net/python/pulldom

Typiquement, les applications DOM commencent par analyser du XML dans du DOM. Comment cela doit être exposé n'est absolument pas décrit par DOM Level 1 et Level 2 ne fournit que des améliorations limités. Il existe une classe @code{DOMImplementation} qui fournit un accès à des méthodes de création de @code{Document} mais il n'y a pas de moyen d'accéder à un lecteur/analyseur/constructeur de `document' de façon indépendante de l'implémentation. Il n'est pas également très bien définis comment accéder à ces méthodes sans un objet @code{Document}. En Python, chaque implémentation fournira une fonction @ref{3715,,getDOMImplementation()} . DOM Level 3 ajoute une spécification `Load/Store' (charge/stocke) qui définie une interface pour le lecteur mais qui n'est pas disponible dans la bibliothèque standard de Python.

Une fois que vous avez un objet document DOM, vous pouvez accéder aux parties de votre document XML à travers ses méthodes et propriétés. Ces propriétés sont définis dans les spécifications DOM ; cette portion du manuel de références décrit l'interprétation des ces spécifications en Python.

Les spécifications fournies par le `W3C' définissent les API DOM pour Java, ECMAScript, et OMG IDL. Les correspondances de Python définies ici sont basées pour une grande part sur la version IDL de la spécification mais une conformité stricte n'est pas requise (bien que ces implémentations soient libre d'implémenter le support strict des correspondances de IDL). Voir la section @ref{3716,,Conformité} pour une discussion détaillée des pré-requis des correspondances.


@subsubheading Voir aussi



@table @asis

@item Document Object Model (DOM) Level 2 Specification@footnote{https://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/}

La recommandation `W3C' sur laquelle l'API DOM de Python est basée.

@item Spécification Level 1 Document Object Model (DOM)@footnote{https://www.w3.org/TR/REC-DOM-Level-1/}

La recommandation du `W3C' pour le DOM supporté par @ref{121,,xml.dom.minidom}.

@item Python Language Mapping Specification@footnote{https://www.omg.org/spec/PYTH/1.2/PDF}

Ceci spécifies les correspondances depuis OMG IDL vers Python.
@end table


@menu
* Contenu du module: Contenu du module<4>. 
* Objets dans le DOM:: 
* Conformité:: 

@end menu

@node Contenu du module<4>,Objets dans le DOM,,xml dom --- The Document Object Model API
@anchor{library/xml dom module-contents}@anchor{3717}
@subsubsection Contenu du module


Le @ref{120,,xml.dom} contient les fonctions suivantes :

@geindex registerDOMImplementation() (dans le module xml.dom)
@anchor{library/xml dom xml dom registerDOMImplementation}@anchor{3718}
@deffn {Fonction} xml.dom.registerDOMImplementation (name, factory)

Enregistre la fonction `factory' avec le nom `name'. La fonction `factory' doit renvoyer un objet qui implémente l'interface de @code{DOMImplementation}. La fonction `factory' peut renvoyer le même objet à chaque fois ou un nouveau à chaque appel en accord avec les spécificités de l'implémentation  (Par exemple si l'implémentation supporte certaines personnalisations).
@end deffn

@geindex getDOMImplementation() (dans le module xml.dom)
@anchor{library/xml dom xml dom getDOMImplementation}@anchor{3715}
@deffn {Fonction} xml.dom.getDOMImplementation (name=None, features=())

Renvoie une implémentation DOM appropriée. Le `name' est soit connu, soit le nom du module d'une implémentation DOM, soit @code{None}. Si ce n'est pas @code{None}, le module correspondant est importé et retourne un objet @code{DOMImplementation} si l'importation réussit. Si Aucun `name' n'est donné et que la variable d'environnement 
@geindex PYTHON_DOM
@geindex variable d'environnement; PYTHON_DOM
@code{PYTHON_DOM} est positionnée, cette variable est utilisée pour trouver l'implémentation.

Si `name' n'est pas donné, la fonction examine les implémentations disponibles pour en trouver une avec l'ensemble des fonctionnalités requises. Si aucune implémentation n'est trouvée, une @ref{40f,,ImportError} est levée. La liste de fonctionnalité doit être une séquence de paires @code{(feature, version)} qui est passée à la méthode @code{hasFeature()} disponible dans les objets @code{DOMImplementation}.
@end deffn

Quelques constantes pratiques sont également fournies :

@geindex EMPTY_NAMESPACE (dans le module xml.dom)
@anchor{library/xml dom xml dom EMPTY_NAMESPACE}@anchor{3719}
@deffn {Données} xml.dom.EMPTY_NAMESPACE

La valeur utilisée pour indiquer qu'aucun espace de noms n'est associé à un nœud dans le DOM. Typiquement, ceci est trouvé comme @code{namespaceURI} dans un nœud ou utilisé comme le paramètre `namespaceURI' dans une méthode spécifique aux espaces de noms.
@end deffn

@geindex XML_NAMESPACE (dans le module xml.dom)
@anchor{library/xml dom xml dom XML_NAMESPACE}@anchor{371a}
@deffn {Données} xml.dom.XML_NAMESPACE

L'URI de l'espace de noms associé avec le préfixe réservé @code{xml} comme défini par Namespaces in XML@footnote{https://www.w3.org/TR/REC-xml-names/} (section 4).
@end deffn

@geindex XMLNS_NAMESPACE (dans le module xml.dom)
@anchor{library/xml dom xml dom XMLNS_NAMESPACE}@anchor{371b}
@deffn {Données} xml.dom.XMLNS_NAMESPACE

L'URI de l'espace de noms pour la déclaration des espaces de noms, tel que défini par Document Object Model (DOM) Level 2 Core Specification@footnote{https://www.w3.org/TR/DOM-Level-2-Core/core.html} (section 1.1.8).
@end deffn

@geindex XHTML_NAMESPACE (dans le module xml.dom)
@anchor{library/xml dom xml dom XHTML_NAMESPACE}@anchor{371c}
@deffn {Données} xml.dom.XHTML_NAMESPACE

L'URI de l'espace de noms XHTML tel que défini par XHTML 1.0: The Extensible HyperText Markup Language@footnote{https://www.w3.org/TR/xhtml1/} (section 3.1.1).
@end deffn

Par ailleurs, @ref{120,,xml.dom} contient une classe de base @code{Node} et les exceptions de DOM. La classe @code{Node} fournie par ce module n'implémente aucune des méthodes ou des attributs définis par les spécifications DOM ; les implémentations concrètes des DOM doivent fournir les informations suivantes. La classe @code{Node} fournie part ce modules fournit les constantes utilisées pour l'attribut @code{nodeType} pour des objets concrets @code{Node} ; ils sont situés dans les classes plutôt qu'au niveau du module en accord avec les spécifications DOM.

@c Should the Node documentation go here?

@node Objets dans le DOM,Conformité,Contenu du module<4>,xml dom --- The Document Object Model API
@anchor{library/xml dom dom-objects}@anchor{371d}@anchor{library/xml dom objects-in-the-dom}@anchor{371e}
@subsubsection Objets dans le DOM


La documentation finale pour le DOM est la spécification DOM du `W3C'.

Notez que les attributs DOM peuvent également être manipulés comme des nœuds au lieu de simples chaînes. Il est relativement rare que vous ayez besoin de faire cela, cependant, cet usage n'est pas encore documenté.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Interface

@tab

Section

@tab

Objectif

@item

@code{DOMImplementation}

@tab

@ref{371f,,Objets DOMImplementation}

@tab

Interface de l'implémentation sous-jacente.

@item

@code{Node}

@tab

@ref{3720,,Objets nœuds}

@tab

Interface de base pour la majorité des objets dans un document.

@item

@code{NodeList}

@tab

@ref{3721,,Objet NodeList}

@tab

Interface pour une séquence de nœuds.

@item

@code{DocumentType}

@tab

@ref{3722,,Objets DocumnentType}

@tab

Informations sur les déclarations nécessaires au traitement d'un document.

@item

@code{Document}

@tab

@ref{3723,,Objets Document}

@tab

Objet représentant un document entier.

@item

@code{Element}

@tab

@ref{3724,,Objets Elements}

@tab

Nœuds éléments dans la hiérarchie d'un document.

@item

@code{Attr}

@tab

@ref{3725,,Objets Attr}

@tab

Valeur des nœuds attributs sur dans des nœuds éléments.

@item

@code{Comment}

@tab

@ref{3726,,Objets Comment}

@tab

Représentation des commentaires dans le fichier source du document.

@item

@code{Text}

@tab

@ref{3727,,Objets Text et CDATASection}

@tab

Nœud contenant un contenu texte du document.

@item

@code{ProcessingInstruction}

@tab

@ref{3728,,Objets ProcessingInstruction}

@tab

Représentation des `Processing Instructions'.

@end multitable


Une Section additionnelle décrit les exceptions définis pour travailler avec le DOM en Python.

@menu
* Objets DOMImplementation:: 
* Objets nœuds:: 
* Objet NodeList:: 
* Objets DocumnentType:: 
* Objets Document:: 
* Objets Elements:: 
* Objets Attr:: 
* Objets NameNodeMap:: 
* Objets Comment:: 
* Objets Text et CDATASection:: 
* Objets ProcessingInstruction:: 
* Exceptions: Exceptions<20>. 

@end menu

@node Objets DOMImplementation,Objets nœuds,,Objets dans le DOM
@anchor{library/xml dom dom-implementation-objects}@anchor{371f}@anchor{library/xml dom domimplementation-objects}@anchor{3729}
@subsubsection Objets DOMImplementation


L'interface @code{DOMImplementation} fournit un moyen pour les applications de déterminer la disponibilité de fonctionnalités particulières dans le DOM qu'elles utilisent. `DOM Level 2' ajoute la capacité de créer des nouveaux objets @code{Document} et @code{DocumentType} utilisant également @code{DOMImplementation}.

@geindex hasFeature() (méthode xml.dom.DOMImplementation)
@anchor{library/xml dom xml dom DOMImplementation hasFeature}@anchor{372a}
@deffn {Méthode} DOMImplementation.hasFeature (feature, version)

Renvoie @code{True} si la fonctionnalité identifiée par le couple de chaînes `feature' et `version' est implémentée.
@end deffn

@geindex createDocument() (méthode xml.dom.DOMImplementation)
@anchor{library/xml dom xml dom DOMImplementation createDocument}@anchor{372b}
@deffn {Méthode} DOMImplementation.createDocument (namespaceUri, qualifiedName, doctype)

Renvoie un nouvel objet @code{Document} (la racine du DOM), avec un objet fils @code{Element} ayant les `namespaceUri' et `qualifiedName' passés en paramètre. Le `doctype' doit être un objet @code{DocumentType} créé par @ref{372c,,createDocumentType()} ou @code{None}. Dans l'API DOM de Python, les deux premiers arguments peuvent également être à @code{None} de manière à indiquer qu'aucun enfant @code{Element} ne soit crée.
@end deffn

@geindex createDocumentType() (méthode xml.dom.DOMImplementation)
@anchor{library/xml dom xml dom DOMImplementation createDocumentType}@anchor{372c}
@deffn {Méthode} DOMImplementation.createDocumentType (qualifiedName, publicId, systemId)

Renvoie un nouvel objet @code{DocumentType} qui encapsule les chaînes `qualifiedName', `publicId', et `systemId' passées en paramètre représentant les informations contenues dans dans la déclaration du document XML.
@end deffn

@node Objets nœuds,Objet NodeList,Objets DOMImplementation,Objets dans le DOM
@anchor{library/xml dom dom-node-objects}@anchor{3720}@anchor{library/xml dom node-objects}@anchor{372d}
@subsubsection Objets nœuds


Tous les composants d'un document XML sont des sous-classes de @code{Node}.

@geindex nodeType (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node nodeType}@anchor{372e}
@deffn {Attribut} Node.nodeType

Un entier représentant le type de nœud. Pour l'objet @code{Node},  les constantes symboliques pour les types sont @code{ELEMENT_NODE}, @code{ATTRIBUTE_NODE}, @code{TEXT_NODE}, @code{CDATA_SECTION_NODE}, @code{ENTITY_NODE}, @code{PROCESSING_INSTRUCTION_NODE}, @code{COMMENT_NODE}, @code{DOCUMENT_NODE}, @code{DOCUMENT_TYPE_NODE}, @code{NOTATION_NODE}. Ceci est un attribut en lecture seule.
@end deffn

@geindex parentNode (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node parentNode}@anchor{372f}
@deffn {Attribut} Node.parentNode

Le parent du nœud courant ou @code{None} dans le cas du nœud document. La valeur est toujours un objet @code{Node} ou @code{None}. Pour les nœuds @code{Element}, ce sera le parent de l'élément sauf si l'élément est la racine, dans ce cas ce sera l'objet @code{Document}. Pour les nœuds @code{Attr}, cela sera toujours @code{None}. Ceci est un attribut en lecture seule.
@end deffn

@geindex attributes (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node attributes}@anchor{3730}
@deffn {Attribut} Node.attributes

Un objet @code{NamedNodeMap} d'objet attributs. Seulement les éléments ayant des valeurs seront listés, les autres renverront @code{None} pour cet attribut. Cet attribut est en lecture seule.
@end deffn

@geindex previousSibling (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node previousSibling}@anchor{3731}
@deffn {Attribut} Node.previousSibling

Le nœud avec le même parent qui précède immédiatement le nœud courant. Par exemple, l'élément avec la balise fermente qui est juste avant la balise ouvrante de l'élément `self'. Naturellement, les documents XML sont fait de plus que juste des éléments ; donc le `previous sibling' peut être du texte, un commentaire ou autre chose. Si le nœud courant est le premier fils du parent, cet attribut vaudra @code{None}. Cet attribut est en lecture seule.
@end deffn

@geindex nextSibling (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node nextSibling}@anchor{3732}
@deffn {Attribut} Node.nextSibling

Le nœud qui suit immédiatement le nœud courant dans le même parent. Voir également @ref{3731,,previousSibling}. Si ce nœud est le dernier de son parent, alors l'attribut sera @code{None}. Cet attribut est en lecture seule.
@end deffn

@geindex childNodes (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node childNodes}@anchor{3733}
@deffn {Attribut} Node.childNodes

Une liste de nœuds contenu dans le nœud courant. Cet attribut est en lecture seule.
@end deffn

@geindex firstChild (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node firstChild}@anchor{3734}
@deffn {Attribut} Node.firstChild

S'il y a des fils, premier fils du nœud courant, sinon @code{None}. Cet attribut est en lecture seule.
@end deffn

@geindex lastChild (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node lastChild}@anchor{3735}
@deffn {Attribut} Node.lastChild

S'il y a des fils, le dernier nœud fils du nœud courant. Sinon @code{None}. Cet attribut est en lecture seule.
@end deffn

@geindex localName (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node localName}@anchor{3736}
@deffn {Attribut} Node.localName

S'il y a un `:', contient la partie suivante de @code{tagName} ce `:' sinon la valeur complète de @code{tagName}. Cette valeur est une chaîne.
@end deffn

@geindex prefix (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node prefix}@anchor{3737}
@deffn {Attribut} Node.prefix

La partie de @code{tagName} précédent le `:' s'il y en a un. sinon une chaîne vide. La valeur est une chaîne ou @code{None}.
@end deffn

@geindex namespaceURI (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node namespaceURI}@anchor{3738}
@deffn {Attribut} Node.namespaceURI

L'espace de noms associé (`namespace' en anglais) au nom de l'élément. Cette valeur est une chaîne ou @code{None}. Cet attribut est en lecture seule.
@end deffn

@geindex nodeName (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node nodeName}@anchor{3739}
@deffn {Attribut} Node.nodeName

L'attribut a un sens différent pour chaque type de nœud ; se reporter à la spécification DOM pour les détails. Vous obtiendrez toujours l'information que vous obtiendrez à l'aide d'une autre propriété comme  @code{tagName} pour les éléments ou @code{name} pour les attributs. Pour tous les types de nœuds, la valeur sera soit une chaîne soit @code{None}. Cet attribut est en lecture seule.
@end deffn

@geindex nodeValue (attribut xml.dom.Node)
@anchor{library/xml dom xml dom Node nodeValue}@anchor{373a}
@deffn {Attribut} Node.nodeValue

L'attribut a un sens différent pour chaque type de nœud ; se reporter à la spécification DOM pour les détails. La situation est similaire à @ref{3739,,nodeName}. La valeur est une chaîne ou @code{None}.
@end deffn

@geindex hasAttributes() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node hasAttributes}@anchor{373b}
@deffn {Méthode} Node.hasAttributes ()

Renvoie @code{True} si le nœud a des attributs.
@end deffn

@geindex hasChildNodes() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node hasChildNodes}@anchor{373c}
@deffn {Méthode} Node.hasChildNodes ()

Renvoie @code{True} si le nœud a des nœuds fils.
@end deffn

@geindex isSameNode() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node isSameNode}@anchor{373d}
@deffn {Méthode} Node.isSameNode (other)

Renvoie @code{True} si `other' fait référence au même nœud que le nœud courant. Ceci est particulièrement pratique pour une implémentation de DOM qui utilise un ou des mandataires dans son architecture (car plus d'un objet peut se référer au même nœud).

@cartouche
@quotation Note 
Ceci est basé sur l'API proposé par * DOM Level 3* qui est toujours à l'étape "`working draft'" mais cette interface particulière ne parait pas controversée. Les changement du `W3C' n'affecteront pas nécessairement cette méthode dans l'interface DOM de Python. (bien que toute nouvelle API `W3C' à cet effet soit également supportée).
@end quotation
@end cartouche
@end deffn

@geindex appendChild() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node appendChild}@anchor{373e}
@deffn {Méthode} Node.appendChild (newChild)

Ajoute un nouveau nœud fils à ce nœud à la fin de la liste des fils renvoyant `newChild'. Si ce nœud est déjà dans l'arbre, il sera d'abord retiré.
@end deffn

@geindex insertBefore() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node insertBefore}@anchor{373f}
@deffn {Méthode} Node.insertBefore (newChild, refChild)

Insère un nouveau nœud fils avant un fils existant. Il est impératif que `refChild' soit un fils du nœud, sinon @ref{1ff,,ValueError} sera levée. `newChild' est renvoyé. Si `refChild' est @code{None}, `newChild' est inséré à la fin de la liste des fils.
@end deffn

@geindex removeChild() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node removeChild}@anchor{3740}
@deffn {Méthode} Node.removeChild (oldChild)

Retire un nœud fils. `oldChild' doit être un fils de ce nœud ; sinon @ref{1ff,,ValueError} sera levée. En cas de succès, `oldChild' est renvoyé. Si `oldChild' n'est plus utilisé, sa méthode @code{unlink()} doit être appelée.
@end deffn

@geindex replaceChild() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node replaceChild}@anchor{3741}
@deffn {Méthode} Node.replaceChild (newChild, oldChild)

Remplace un nœud existant avec un nouveau. `oldChild' doit être un fils de ce nœud ; sinon @ref{1ff,,ValueError} sera levée.
@end deffn

@geindex normalize() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node normalize}@anchor{3742}
@deffn {Méthode} Node.normalize ()

Jointe les nœuds texte adjacents de manière à ce que tous les segments de texte soient stockés dans une seule instance de @code{Text}.  Ceci simplifie le traitement du texte d'un arbre DOM pour de nombreuses applications.
@end deffn

@geindex cloneNode() (méthode xml.dom.Node)
@anchor{library/xml dom xml dom Node cloneNode}@anchor{3743}
@deffn {Méthode} Node.cloneNode (deep)

Clone ce nœud. Positionner `deep' signifie que tous les nœuds fils seront également clonés. La méthode renvoi le clone.
@end deffn

@node Objet NodeList,Objets DocumnentType,Objets nœuds,Objets dans le DOM
@anchor{library/xml dom dom-nodelist-objects}@anchor{3721}@anchor{library/xml dom nodelist-objects}@anchor{3744}
@subsubsection Objet NodeList


@code{NodeList} représente une séquence de nœuds. Ces objets sont utilisés de deux manières dans la recommandation Dom Core : un objet @code{Element} fournit en fournis liste des nœud fils et les méthodes @code{getElementsByTagName()} et @code{getElementsByTagNameNS()} de  @code{Node} renvoient des objet avec cette interface pour représenter les résultats des requêtes.

La recommandation DOM Level 2 définit un attribut et une méthode pour ces objets :

@geindex item() (méthode xml.dom.NodeList)
@anchor{library/xml dom xml dom NodeList item}@anchor{3745}
@deffn {Méthode} NodeList.item (i)

Renvoie le `i'@w{^e} élément de la séquence s'il existe ou @code{None}. L'index `i' ne peut pas être inférieur à 0 ou supérieur ou égale à la longueur de la séquence.
@end deffn

@geindex length (attribut xml.dom.NodeList)
@anchor{library/xml dom xml dom NodeList length}@anchor{3746}
@deffn {Attribut} NodeList.length

Le nombre d'éléments dans la séquence.
@end deffn

En plus, l'interface DOM de Python requiert quelques ajouts supplémentaires pour permettre que les objet @code{NodeList} puissent être utilisés comme des séquences Python. Toutes les implémentations de @code{NodeList} doivent inclure le support de @ref{1ee5,,__len__()} et de @ref{280,,__getitem__()} ; ceci permet l'itération sur @code{NodeList} avec l'instruction @ref{2e6,,for} et un support de la fonction native  @ref{619,,len()}.

Si une implémentation de DOM support les modifications du document, l'implémentation de @code{NodeList} doit également supporter les méthodes @ref{12a9,,__setitem__()} et @ref{12aa,,__delitem__()} .

@node Objets DocumnentType,Objets Document,Objet NodeList,Objets dans le DOM
@anchor{library/xml dom documenttype-objects}@anchor{3747}@anchor{library/xml dom dom-documenttype-objects}@anchor{3722}
@subsubsection Objets DocumnentType


Les objets de type @code{DocumentType} fournissent des informations sur les notations et les entités déclarées par un document (incluant les données externes si l'analyseur les utilise et peut les fournir). Le @code{DocumentType} d'un @code{Document} est accessible via l'attribut @code{doctype}. Si le document ne déclare pas de @code{DOCTYPE}, l'attribut @code{doctype} vaudra @code{None} plutôt qu'une instance de cette interface.

@code{DocumentType}  est une spécialisation de @code{Node} et ajoute les attributs suivants :

@geindex publicId (attribut xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType publicId}@anchor{3748}
@deffn {Attribut} DocumentType.publicId

L'identifiant publique pour un sous ensemble de la définition type de document (`DTD'). Cela sera une chaîne ou @code{None}.
@end deffn

@geindex systemId (attribut xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType systemId}@anchor{3749}
@deffn {Attribut} DocumentType.systemId

L'identifiant système pour un sous ensemble du document de définition type (`DTD'). Cela sera une URI sous la forme d'une chaîne ou @code{None}.
@end deffn

@geindex internalSubset (attribut xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType internalSubset}@anchor{374a}
@deffn {Attribut} DocumentType.internalSubset

Un chaîne donnant le sous ensemble complet du document. Ceci n'inclut pas les chevrons qui englobe le sous ensemble. Si le document n'a pas de sous ensemble, cela devrait être @code{None}.
@end deffn

@geindex name (attribut xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType name}@anchor{374b}
@deffn {Attribut} DocumentType.name

Le nom de l'élément racine donné dans la déclaration  @code{DOCTYPE} si présente.
@end deffn

@geindex entities (attribut xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType entities}@anchor{374c}
@deffn {Attribut} DocumentType.entities

Ceci est un @code{NamedNodeMap} donnant les définitions des entités externes. Pour les entités définies plusieurs fois seule la première définition est fournie (les suivantes sont ignorées comme requis par la recommandation XML). Ceci peut retourner @code{None} si l'information n'est pas fournie à l'analyseur ou si aucune entités n'est définis.
@end deffn

@geindex notations (attribut xml.dom.DocumentType)
@anchor{library/xml dom xml dom DocumentType notations}@anchor{374d}
@deffn {Attribut} DocumentType.notations

Ceci est un @code{NamedNodeMap} donnant la définition des notations. Pour les notations définies plus d'une fois, seule la première est fournie (les suivante sont ignorées comme requis par la recommandation XML). Ceci peut retourner @code{None} si l'information n'est pas fournie à l'analyseur ou si aucune entités n'est définis.
@end deffn

@node Objets Document,Objets Elements,Objets DocumnentType,Objets dans le DOM
@anchor{library/xml dom document-objects}@anchor{374e}@anchor{library/xml dom dom-document-objects}@anchor{3723}
@subsubsection Objets Document


Un @code{Document} représente un document XML en son entier, incluant les éléments qui le constitue, les attributs, les `processing instructions', commentaires, etc. Rappelez vous qu'il hérite des propriété de @code{Node}.

@geindex documentElement (attribut xml.dom.Document)
@anchor{library/xml dom xml dom Document documentElement}@anchor{374f}
@deffn {Attribut} Document.documentElement

Le seul et unique élément racine du document.
@end deffn

@geindex createElement() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createElement}@anchor{3750}
@deffn {Méthode} Document.createElement (tagName)

Créé et renvoi un nouveau nœud élément. Ce n'est pas inséré dans le document quand il est créé. Vous avez besoin de l'insérer explicitement avec l'une des autres méthodes comme @code{insertBefore()} ou @code{appendChild()}.
@end deffn

@geindex createElementNS() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createElementNS}@anchor{3751}
@deffn {Méthode} Document.createElementNS (namespaceURI, tagName)

Créé et renvoi un nouvel élément avec un `namespace'.  Le `tagName' peut avoir un préfixe. L'élément ne sera pas insérer dans le document quand il est créé. Vous avez besoin de l'insérer explicitement avec l'une des autres méthodes comme @code{insertBefore()} ou @code{appendChild()}.
@end deffn

@geindex createTextNode() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createTextNode}@anchor{3752}
@deffn {Méthode} Document.createTextNode (data)

Créé et renvoi un nœud texte contenant les `data' passées en paramètre. Comme pour les autres méthodes de création, la méthode n'insère pas le nœud dans l'arbre.
@end deffn

@geindex createComment() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createComment}@anchor{3753}
@deffn {Méthode} Document.createComment (data)

Créé et renvoi un nœud commentaire contenant les `data' passé en commentaire. Comme pour les autres méthodes de création, la méthode n'insère pas le nœud dans l'arbre.
@end deffn

@geindex createProcessingInstruction() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createProcessingInstruction}@anchor{3754}
@deffn {Méthode} Document.createProcessingInstruction (target, data)

Créé et retourne un nœud `processing instruction' contenant les `target' et `data'  passés en paramètres. Comme pour les autres méthodes de création, la méthode n'insère pas le nœud dans l'arbre.
@end deffn

@geindex createAttribute() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createAttribute}@anchor{3755}
@deffn {Méthode} Document.createAttribute (name)

Créé et renvoi un nœud attribut. Cette méthode n'associe le nœud attribut aucun nœud en particulier. Vous devez utiliser la méthode @code{setAttributeNode()} sur un objet @code{Element} approprié pour utiliser une instance d'attribut nouvellement créé.
@end deffn

@geindex createAttributeNS() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document createAttributeNS}@anchor{3756}
@deffn {Méthode} Document.createAttributeNS (namespaceURI, qualifiedName)

Créé et renvoi un nœud attribut avec un `namespace'. Le `tagName' peut avoir un préfixe. Cette méthode n'associe le nœud attribut à aucun nœud en particulier. Vous devez utiliser la méthode @code{setAttributeNode()} sur un objet @code{Element} approprié pour utiliser une instance d'attribut nouvellement créé.
@end deffn

@geindex getElementsByTagName() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document getElementsByTagName}@anchor{3757}
@deffn {Méthode} Document.getElementsByTagName (tagName)

Cherche tout les descendants (fils directs, fils de fils, etc.) avec un nom de balise particulier.
@end deffn

@geindex getElementsByTagNameNS() (méthode xml.dom.Document)
@anchor{library/xml dom xml dom Document getElementsByTagNameNS}@anchor{3758}
@deffn {Méthode} Document.getElementsByTagNameNS (namespaceURI, localName)

Cherche tous les descendants (fils directs, fils de fils, etc.) avec un `namespace URI' particulier et un `localName'. Le `localName' fait parti du `namespace' après le préfixe.
@end deffn

@node Objets Elements,Objets Attr,Objets Document,Objets dans le DOM
@anchor{library/xml dom dom-element-objects}@anchor{3724}@anchor{library/xml dom element-objects}@anchor{3759}
@subsubsection Objets Elements


@code{Element} est une une sous classe de @code{Node} et donc hérite de tout les éléments de cette classe.

@geindex tagName (attribut xml.dom.Element)
@anchor{library/xml dom xml dom Element tagName}@anchor{375a}
@deffn {Attribut} Element.tagName

Le nom de l'élément type. Dans un document utilisant des `namespace', il pourrait y avoir des `:' dedans. La valeur est une chaîne.
@end deffn

@geindex getElementsByTagName() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element getElementsByTagName}@anchor{375b}
@deffn {Méthode} Element.getElementsByTagName (tagName)

Identique à la méthode équivalente de la classe @code{Document}.
@end deffn

@geindex getElementsByTagNameNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element getElementsByTagNameNS}@anchor{375c}
@deffn {Méthode} Element.getElementsByTagNameNS (namespaceURI, localName)

Identique à la méthode équivalente de la classe @code{Document}.
@end deffn

@geindex hasAttribute() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element hasAttribute}@anchor{375d}
@deffn {Méthode} Element.hasAttribute (name)

Renvoie @code{True} si l'élément a un attribut nommé `name'.
@end deffn

@geindex hasAttributeNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element hasAttributeNS}@anchor{375e}
@deffn {Méthode} Element.hasAttributeNS (namespaceURI, localName)

Renvoie @code{True} si l'élément a un attribut nommé `localName' dans l'espace de noms `namespaceURI'.
@end deffn

@geindex getAttribute() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttribute}@anchor{375f}
@deffn {Méthode} Element.getAttribute (name)

Retourne la valeur de l'attribut nommé par `name' comme une chaîne. Si un tel attribue n'existe pas, une chaîne vide est retournée comme si l'attribut n'avait aucune valeur.
@end deffn

@geindex getAttributeNode() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttributeNode}@anchor{3760}
@deffn {Méthode} Element.getAttributeNode (attrname)

Retourne le nœud @code{Attr} pour l'attribut nommé par `attrname'.
@end deffn

@geindex getAttributeNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttributeNS}@anchor{3761}
@deffn {Méthode} Element.getAttributeNS (namespaceURI, localName)

Renvoi la valeur de l'attribut nommé par `namespaceURI' et `localName' comme une chaîne. Si un tel attribue n'existe pas, une chaîne vide est retournée comme si l'attribut n'avait aucune valeur.
@end deffn

@geindex getAttributeNodeNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element getAttributeNodeNS}@anchor{3762}
@deffn {Méthode} Element.getAttributeNodeNS (namespaceURI, localName)

Renvoi la valeur de l'attribue comme un nœud étant donné `namespaceURI' et `localName'.
@end deffn

@geindex removeAttribute() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element removeAttribute}@anchor{3763}
@deffn {Méthode} Element.removeAttribute (name)

Retire un attribut nommé `name'. S'il n'y a aucun attribut correspondant une @ref{3764,,NotFoundErr} est levée.
@end deffn

@geindex removeAttributeNode() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element removeAttributeNode}@anchor{3765}
@deffn {Méthode} Element.removeAttributeNode (oldAttr)

Supprime et renvoi `oldAttr' de la liste des attributs si présent. Si `oldAttr' n'est pas présent, @ref{3764,,NotFoundErr} est levée.
@end deffn

@geindex removeAttributeNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element removeAttributeNS}@anchor{3766}
@deffn {Méthode} Element.removeAttributeNS (namespaceURI, localName)

Retire un attribut selon son nom. Notez qu'il utilise un `localName' et nom un `qname'. Aucune exception n'est levée s'il n'y a pas d'attribut correspondant.
@end deffn

@geindex setAttribute() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttribute}@anchor{3767}
@deffn {Méthode} Element.setAttribute (name, value)

Assigne la valeur à un attribut pour la chaîne.
@end deffn

@geindex setAttributeNode() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttributeNode}@anchor{3768}
@deffn {Méthode} Element.setAttributeNode (newAttr)

Ajoute un nouveau nœud attribut à l'élément, remplaçant un attribut existant si nécessaire si @code{name} corresponds à un attribut. Si l'attribut en remplace un précédent, l'ancien attribut sera retourné. Si `newAttr' est déjà utilisé, @ref{3769,,InuseAttributeErr} sera levée.
@end deffn

@geindex setAttributeNodeNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttributeNodeNS}@anchor{376a}
@deffn {Méthode} Element.setAttributeNodeNS (newAttr)

Ajoute un nouveau nœud attribut, remplaçant un attribut existant si @code{namespaceURI} et @code{localName} corresponds à un attribut. S'il y a remplacement, l'ancien nœud sera renvoyé. Si `newAttr' est déjà utilisé, @ref{3769,,InuseAttributeErr} sera levée.
@end deffn

@geindex setAttributeNS() (méthode xml.dom.Element)
@anchor{library/xml dom xml dom Element setAttributeNS}@anchor{376b}
@deffn {Méthode} Element.setAttributeNS (namespaceURI, qname, value)

Assigne la valeur d'un attribut depuis une chaîne étant donnée un `namespaceURI' et un `qname'. Notez que `qname' est le nom de l'attribut en entier. Ceci est différent d'au dessus.
@end deffn

@node Objets Attr,Objets NameNodeMap,Objets Elements,Objets dans le DOM
@anchor{library/xml dom attr-objects}@anchor{376c}@anchor{library/xml dom dom-attr-objects}@anchor{3725}
@subsubsection Objets Attr


@code{Attr} hérite @code{Node} et donc hérite de tout ces attributs.

@geindex name (attribut xml.dom.Attr)
@anchor{library/xml dom xml dom Attr name}@anchor{376d}
@deffn {Attribut} Attr.name

Le nom de l'attribut. Dans un document utilisant des `namespaces', il pourra inclure un `:'.
@end deffn

@geindex localName (attribut xml.dom.Attr)
@anchor{library/xml dom xml dom Attr localName}@anchor{376e}
@deffn {Attribut} Attr.localName

La partie du nom suivant le `:' s'il y en a un ou le nom entier sinon. Ceci est un attribut en lecture seule.
@end deffn

@geindex prefix (attribut xml.dom.Attr)
@anchor{library/xml dom xml dom Attr prefix}@anchor{376f}
@deffn {Attribut} Attr.prefix

La partie du nom précédent le `:' s'il y en a un ou une chaîne vide.
@end deffn

@geindex value (attribut xml.dom.Attr)
@anchor{library/xml dom xml dom Attr value}@anchor{3770}
@deffn {Attribut} Attr.value

La valeur texte de l'attribut. C'est un synonyme de l'attribut @code{nodeValue}.
@end deffn

@node Objets NameNodeMap,Objets Comment,Objets Attr,Objets dans le DOM
@anchor{library/xml dom dom-attributelist-objects}@anchor{3771}@anchor{library/xml dom namednodemap-objects}@anchor{3772}
@subsubsection Objets NameNodeMap


@code{NamedNodeMap} `n'hérite pas' de @code{Node}.

@geindex length (attribut xml.dom.NamedNodeMap)
@anchor{library/xml dom xml dom NamedNodeMap length}@anchor{3773}
@deffn {Attribut} NamedNodeMap.length

La longueur de la liste d'attributs.
@end deffn

@geindex item() (méthode xml.dom.NamedNodeMap)
@anchor{library/xml dom xml dom NamedNodeMap item}@anchor{3774}
@deffn {Méthode} NamedNodeMap.item (index)

Renvoi un attribut à un index particulier. L'ordre des attribut est arbitraire mais sera constant durant toute la vie du DOM. Chacun des item sera un nœud attribut. Obtenez sa  valeur avec @code{value} de l'attribut.
@end deffn

There are also experimental methods that give this class more mapping behavior.
You can use them or you can use the standardized @code{getAttribute*()} family
of methods on the @code{Element} objects.

@node Objets Comment,Objets Text et CDATASection,Objets NameNodeMap,Objets dans le DOM
@anchor{library/xml dom comment-objects}@anchor{3775}@anchor{library/xml dom dom-comment-objects}@anchor{3726}
@subsubsection Objets Comment


@code{Comment} représente un commentaire dans le document XML. C'est une sous classe @code{Node} mais n'a aucune nœuds fils.

@geindex data (attribut xml.dom.Comment)
@anchor{library/xml dom xml dom Comment data}@anchor{3776}
@deffn {Attribut} Comment.data

Le contenu du commentaire comme une chaîne. L'attribut contient tous les caractères entre @code{<!-}@code{-} et  @code{-}@code{->} mais ne les inclues pas.
@end deffn

@node Objets Text et CDATASection,Objets ProcessingInstruction,Objets Comment,Objets dans le DOM
@anchor{library/xml dom dom-text-objects}@anchor{3727}@anchor{library/xml dom text-and-cdatasection-objects}@anchor{3777}
@subsubsection Objets Text et CDATASection


L'interface @code{Text} représente le texte dans un document XML. Si l'analyseur et l'implémentation DOM supporte les extensions XML du DOM, les portion de texte encapsulées dans des section marquées CDATA seront stockées dans des objets @code{CDATASection}. Ces deux interfaces sont identiques mais fournissent des valeurs différentes pour l'attribut @code{nodeType}.

Ces interfaces étendent l'interface @code{Node}. Elles ne peuvent pas avoir de nœuds fils.

@geindex data (attribut xml.dom.Text)
@anchor{library/xml dom xml dom Text data}@anchor{3778}
@deffn {Attribut} Text.data

Le contenu du nœud texte comme une chaîne.
@end deffn

@cartouche
@quotation Note 
L'utilisation d'un nœud @code{CDATASection} n'indique pas que le nœud représente une section complète marquée CDATA, seulement que le contenu du nœud est le contenu d'une section CDATA. Une seule section CDATA peut représenter plus d'un nœud dans l'arbre du document. Il n'y a aucun moyen de déterminer si deux nœuds @code{CDATASection} adjacents représentent différentes sections CDATA.
@end quotation
@end cartouche

@node Objets ProcessingInstruction,Exceptions<20>,Objets Text et CDATASection,Objets dans le DOM
@anchor{library/xml dom dom-pi-objects}@anchor{3728}@anchor{library/xml dom processinginstruction-objects}@anchor{3779}
@subsubsection Objets ProcessingInstruction


Représente une `processing instruction' dans un document XML. Hérite de l'interface @code{Node} et ne peut avoir aucun nœud fils.

@geindex target (attribut xml.dom.ProcessingInstruction)
@anchor{library/xml dom xml dom ProcessingInstruction target}@anchor{377a}
@deffn {Attribut} ProcessingInstruction.target

Le contenu de la `processing instruction' jusqu'au premier caractère blanc. Cet attribut est en lecture seule.
@end deffn

@geindex data (attribut xml.dom.ProcessingInstruction)
@anchor{library/xml dom xml dom ProcessingInstruction data}@anchor{377b}
@deffn {Attribut} ProcessingInstruction.data

Le contenu de la `processing instruction' après le premier caractère blanc.
@end deffn

@node Exceptions<20>,,Objets ProcessingInstruction,Objets dans le DOM
@anchor{library/xml dom dom-exceptions}@anchor{377c}@anchor{library/xml dom exceptions}@anchor{377d}
@subsubsection Exceptions


La recommandation `DOM Level 2' définie une seule exception @ref{377e,,DOMException} et un nombre de constantes qui permettent aux applications à déterminer quelle type d'erreur s'est produit. Les instances de @ref{377e,,DOMException} ont un attribut @ref{1a,,code} qui fourni une valeur approprié pour une exception spécifique.

L'interface DOM de Python fournit des constant mais également étends un ensemble d'exception pour qu'il existe une exception spécifique pour chaque code d'exception défini par le DOM. L'implémentation doit lever l'exception spécifique appropriée. Chacune ayant la valeur appropriée pour l'attribut @ref{1a,,code}.

@geindex DOMException
@anchor{library/xml dom xml dom DOMException}@anchor{377e}
@deffn {Exception} xml.dom.DOMException

Exception de base utilisée pour toutes les exceptions spécifiques du DOM. Cette classe ne peut pas être instanciée directement.
@end deffn

@geindex DomstringSizeErr
@anchor{library/xml dom xml dom DomstringSizeErr}@anchor{377f}
@deffn {Exception} xml.dom.DomstringSizeErr

Levée quand un intervalle spécifique de texte ne rentre pas dans une chaîne. Cette exception n'est pas réputée être utilisée par les implémentations DOM de Python  mais elle peur être levée par des implémentations de DOM qui ne sont pas écrite en Python.
@end deffn

@geindex HierarchyRequestErr
@anchor{library/xml dom xml dom HierarchyRequestErr}@anchor{3780}
@deffn {Exception} xml.dom.HierarchyRequestErr

Levée quand l'insertion d'un nœud est tentée dans un type de nœud incompatible.
@end deffn

@geindex IndexSizeErr
@anchor{library/xml dom xml dom IndexSizeErr}@anchor{3781}
@deffn {Exception} xml.dom.IndexSizeErr

Levée quand un index ou la taille d'un paramètre d'une méthode est négatif ou excède les valeurs autorisées.
@end deffn

@geindex InuseAttributeErr
@anchor{library/xml dom xml dom InuseAttributeErr}@anchor{3769}
@deffn {Exception} xml.dom.InuseAttributeErr

Levée quand l'insertion d'un nœud @code{Attr} est tenté alors que ce nœud est déjà présent ailleurs dans le document.
@end deffn

@geindex InvalidAccessErr
@anchor{library/xml dom xml dom InvalidAccessErr}@anchor{3782}
@deffn {Exception} xml.dom.InvalidAccessErr

Levée si un paramètre ou une opération n'est pas supporté par l'objet sous-jacent.
@end deffn

@geindex InvalidCharacterErr
@anchor{library/xml dom xml dom InvalidCharacterErr}@anchor{3783}
@deffn {Exception} xml.dom.InvalidCharacterErr

Cette exception est levée quand un paramètre chaîne contient un caractère qui n'est pas autorisé dans le contexte utilisé par la recommandation XML 1.0. Par exemple, lors la tentative de création d'un nœud @code{Element} avec un espace dans le nom de l'élément.
@end deffn

@geindex InvalidModificationErr
@anchor{library/xml dom xml dom InvalidModificationErr}@anchor{3784}
@deffn {Exception} xml.dom.InvalidModificationErr

Levée lors de la tentative de modifier le type de nœud.
@end deffn

@geindex InvalidStateErr
@anchor{library/xml dom xml dom InvalidStateErr}@anchor{3785}
@deffn {Exception} xml.dom.InvalidStateErr

Levée quand une tentative est faite d'utiliser un objet non défini ou qui ne sont plus utilisables.
@end deffn

@geindex NamespaceErr
@anchor{library/xml dom xml dom NamespaceErr}@anchor{3786}
@deffn {Exception} xml.dom.NamespaceErr

Si une tentative est faite de changer un objet d'une manière qui n'est pas autorisée selon la recommandation Namespaces in XML@footnote{https://www.w3.org/TR/REC-xml-names/} , cette exception est levée.
@end deffn

@geindex NotFoundErr
@anchor{library/xml dom xml dom NotFoundErr}@anchor{3764}
@deffn {Exception} xml.dom.NotFoundErr

Exception quand un nœud n'existe pas dans le contexte référencé. Par exemple, @code{NamedNodeMap.removeNamedItem()} lèvera cette exception si le nœud passé n'appartient pas à la séquence.
@end deffn

@geindex NotSupportedErr
@anchor{library/xml dom xml dom NotSupportedErr}@anchor{3787}
@deffn {Exception} xml.dom.NotSupportedErr

Levée si l'implémentation ne supporte pas le type d'objet requis ou l'opération.
@end deffn

@geindex NoDataAllowedErr
@anchor{library/xml dom xml dom NoDataAllowedErr}@anchor{3788}
@deffn {Exception} xml.dom.NoDataAllowedErr

Levée si la donnée spécifiée pour un nœud n'est pas supportée.

@c XXX  a better explanation is needed!
@end deffn

@geindex NoModificationAllowedErr
@anchor{library/xml dom xml dom NoModificationAllowedErr}@anchor{3789}
@deffn {Exception} xml.dom.NoModificationAllowedErr

Levée lors de la tentative de modification sur objet où les modifications ne sont pas autorisées (tels que les nœuds en lecture seule).
@end deffn

@geindex SyntaxErr
@anchor{library/xml dom xml dom SyntaxErr}@anchor{378a}
@deffn {Exception} xml.dom.SyntaxErr

Levée quand une chaîne invalide ou illégale est spécifiée.

@c XXX  how is this different from InvalidCharacterErr?
@end deffn

@geindex WrongDocumentErr
@anchor{library/xml dom xml dom WrongDocumentErr}@anchor{378b}
@deffn {Exception} xml.dom.WrongDocumentErr

Levée quand un nœud est inséré dans un document différent de celui auquel il appartient et que l'implémentation ne supporte pas la migration d'un document à un autre.
@end deffn

Les codes d'exceptions définis par la recommandation DOM avec leurs correspondances décrites si dessous selon ce tableau :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Exception

@item

@code{DOMSTRING_SIZE_ERR}

@tab

@ref{377f,,DomstringSizeErr}

@item

@code{HIERARCHY_REQUEST_ERR}

@tab

@ref{3780,,HierarchyRequestErr}

@item

@code{INDEX_SIZE_ERR}

@tab

@ref{3781,,IndexSizeErr}

@item

@code{INUSE_ATTRIBUTE_ERR}

@tab

@ref{3769,,InuseAttributeErr}

@item

@code{INVALID_ACCESS_ERR}

@tab

@ref{3782,,InvalidAccessErr}

@item

@code{INVALID_CHARACTER_ERR}

@tab

@ref{3783,,InvalidCharacterErr}

@item

@code{INVALID_MODIFICATION_ERR}

@tab

@ref{3784,,InvalidModificationErr}

@item

@code{INVALID_STATE_ERR}

@tab

@ref{3785,,InvalidStateErr}

@item

@code{NAMESPACE_ERR}

@tab

@ref{3786,,NamespaceErr}

@item

@code{NOT_FOUND_ERR}

@tab

@ref{3764,,NotFoundErr}

@item

@code{NOT_SUPPORTED_ERR}

@tab

@ref{3787,,NotSupportedErr}

@item

@code{NO_DATA_ALLOWED_ERR}

@tab

@ref{3788,,NoDataAllowedErr}

@item

@code{NO_MODIFICATION_ALLOWED_ERR}

@tab

@ref{3789,,NoModificationAllowedErr}

@item

@code{SYNTAX_ERR}

@tab

@ref{378a,,SyntaxErr}

@item

@code{WRONG_DOCUMENT_ERR}

@tab

@ref{378b,,WrongDocumentErr}

@end multitable


@node Conformité,,Objets dans le DOM,xml dom --- The Document Object Model API
@anchor{library/xml dom conformance}@anchor{378c}@anchor{library/xml dom dom-conformance}@anchor{3716}
@subsubsection Conformité


Cette section décrit la conformité des pré requis et des relations entre l'API DOM de Python, les recommandations `W3C' DOM et les correspondances OMG IDL pour Python.

@menu
* Correspondance des types:: 
* Méthodes d'accès:: 

@end menu

@node Correspondance des types,Méthodes d'accès,,Conformité
@anchor{library/xml dom dom-type-mapping}@anchor{378d}@anchor{library/xml dom type-mapping}@anchor{378e}
@subsubsection Correspondance des types


Les types IDL utilisés dans la spécification DOM correspondent aux types Python selon le tableau suivant.


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type IDL

@tab

Type Python

@item

@code{boolean}

@tab

@code{bool} ou @code{int}

@item

@code{int}

@tab

@code{int}

@item

@code{long int}

@tab

@code{int}

@item

@code{unsigned int}

@tab

@code{int}

@item

@code{DOMString}

@tab

@code{str} or @code{bytes}

@item

@code{null}

@tab

@code{None}

@end multitable


@node Méthodes d'accès,,Correspondance des types,Conformité
@anchor{library/xml dom accessor-methods}@anchor{378f}@anchor{library/xml dom dom-accessor-methods}@anchor{3790}
@subsubsection Méthodes d'accès


Les correspondance de OMG IDL vers Python définissent des fonction d'accès pour les déclarations @code{attribut} d'IDL à la manière dont Java le fait. Correspondance des déclarations IDL

@example
readonly attribute string someValue;
         attribute string anotherValue;
@end example

donne trois fonctions d'accès : une méthode `get' pour @code{someValue} (@code{_get_someValue()}) et des méthodes `get' et `set' pour @code{anotherValue} (@code{_get_anotherValue()} et @code{_set_anotherValue()}). Le `mapping', en particulier, ne requiert pas que les attributs IDL soient accessible comme des attributs Python normaux : @code{object.someValue} n'est `pas' requis de fonctionner et peut lever une @ref{343,,AttributeError}.

Cependant, l'API DOM de Python `impose' que les accès par attributs classiques fonctionnent. Par conséquent, les substituts générés par le compilateur IDL de Python ne fonctionneront probablement pas, et des objets façade pourraient être nécessaires côté client si les objets DOM sont manipulés via CORBA. Bien qu'utiliser un client DOM CORBA nécessite une bonne réflexion, les développeurs habitués et expérimentés à l'utilisation de CORBA ne considèrent pas que c'est un problème. Les attributs déclarés @code{readonly} pourraient ne pas voir leur accès en écriture restreint dans toutes les implémentations du DOM.

Dans l'API DOM de Python, les fonctions d'accès ne sont pas requises. Si elles sont fournies, elles doivent prendre la forme définie par le `mapping' de Python IDL, mais ces méthodes sont considérées inutiles car les attributs sont directement accessible depuis Python. Les fonctions d'accès "Set" ne devraient jamais être fournies pour les attributs @code{readonly} (en lecture seule).

Les définitions IDL n'embarquent pas entièrement les pré-requis de l'API de DOM API telle que la notion de objets ou que la valeur de retour de @code{getElementsByTagName()} est dynamique. L'API DOM de Python ne requiert pas des implémentations d'avoir de tel pré-requis.

@node xml dom minidom --- Minimal DOM implementation,xml dom pulldom --- Support for building partial DOM trees,xml dom --- The Document Object Model API,Outils de traitement de balises structurées
@anchor{library/xml dom minidom doc}@anchor{3791}@anchor{library/xml dom minidom module-xml dom minidom}@anchor{121}@anchor{library/xml dom minidom xml-dom-minidom-minimal-dom-implementation}@anchor{3792}
@subsection @code{xml.dom.minidom} --- Minimal DOM implementation


@geindex module; xml.dom.minidom

`Code source:' Lib/xml/dom/minidom.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/dom/minidom.py}


__________________________________________________________________


@ref{121,,xml.dom.minidom} est une implémentation minimale de l'interface `Document Object Model', avec une API similaire à celle d'autres langages. Elle est censée être plus simple que le DOM complet et également nettement plus petite. Les utilisateurs qui ne maîtrisent pas déjà le DOM devraient plutôt envisager d'utiliser le module @ref{124,,xml.etree.ElementTree} pour leur traitement XML.

@cartouche
@quotation Avertissement 
le module @ref{121,,xml.dom.minidom} n'est pas sécurisé contre les données construites de façon malveillante. Si vous avez besoin d'analyser des données non sécurisées ou non authentifiées, référez-vous à @ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche

Les applications DOM commencent généralement par analyser du XML dans un DOM. Avec @ref{121,,xml.dom.minidom}, cela se fait via les fonctions d'analyse :

@example
from xml.dom.minidom import parse, parseString

dom1 = parse('c:\\temp\\mydata.xml')  # parse an XML file by name

datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource)  # parse an open file

dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
@end example

La fonction @ref{3793,,parse()} peut prendre soit un nom de fichier, soit un objet fichier ouvert.

@geindex parse() (dans le module xml.dom.minidom)
@anchor{library/xml dom minidom xml dom minidom parse}@anchor{3793}
@deffn {Fonction} xml.dom.minidom.parse (filename_or_file, parser=None, bufsize=None)

Renvoie un @code{Document} à partir de l'entrée donnée. `filename_or_file' peut être soit un nom de fichier, soit un objet simili-fichier. `parser', s'il est donné, doit être un objet analyseur `SAX2'. Cette fonction modifie le pointeur vers le document de l'analyseur et active la prise en charge des espaces de noms ; les autres configurations de l'analyseur (comme la définition d'un résolveur d'entité) doivent avoir été effectuées à l'avance.
@end deffn

Si votre XML se trouve dans une chaîne, vous pouvez utiliser la fonction @ref{3794,,parseString()} à la place :

@geindex parseString() (dans le module xml.dom.minidom)
@anchor{library/xml dom minidom xml dom minidom parseString}@anchor{3794}
@deffn {Fonction} xml.dom.minidom.parseString (string, parser=None)

Renvoie un @code{Document} qui représente `string'. Cette méthode crée un objet @ref{f12,,io.StringIO} pour la chaîne et le transmet à @ref{3793,,parse()}.
@end deffn

Les deux fonctions renvoient un objet @code{Document} représentant le contenu du document.

Ce que font les fonctions @ref{3793,,parse()} et @ref{3794,,parseString()}, c'est connecter un analyseur XML avec un « constructeur DOM » qui peut accepter les événements d'analyse de n'importe quel analyseur `SAX' et les convertir en une arborescence DOM. Les noms des fonctions sont peut-être trompeurs, mais sont faciles à comprendre lors de l'apprentissage des interfaces. L'analyse du document sera terminée avant le retour de ces fonctions ; c'est simplement que ces fonctions ne fournissent pas elles-mêmes d'implémentation d'analyseur.

Vous pouvez également créer un @code{Document} en appelant une méthode sur un objet « DOM Implementation ». Vous pouvez obtenir cet objet soit en appelant la fonction @code{getDOMImplementation()} du paquet @ref{120,,xml.dom} ou du module @ref{121,,xml.dom.minidom}. Une fois que vous avez un @code{Document}, vous pouvez y ajouter des nœuds enfants pour remplir le DOM :

@example
from xml.dom.minidom import getDOMImplementation

impl = getDOMImplementation()

newdoc = impl.createDocument(None, "some_tag", None)
top_element = newdoc.documentElement
text = newdoc.createTextNode('Some textual content.')
top_element.appendChild(text)
@end example

Une fois que vous disposez d'un objet document DOM, vous pouvez accéder aux parties de votre document XML via ses propriétés et méthodes. Ces propriétés sont définies dans la spécification DOM. La propriété principale de l'objet document est la propriété @code{documentElement}. Il vous donne l'élément principal du document XML : celui qui contient tous les autres. Voici un exemple de programme :

@example
dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"
@end example

Lorsque vous avez terminé avec une arborescence DOM, vous pouvez éventuellement appeler la méthode @code{unlink()} pour favoriser un nettoyage précoce des objets désormais inutiles. @code{unlink()} est une extension spécifique @ref{121,,xml.dom.minidom} de l'API DOM qui rend le nœud et ses descendants essentiellement inutiles. Sinon, le ramasse-miettes de Python finira par s'occuper des objets dans l'arborescence.


@subsubheading Voir aussi



@table @asis

@item Spécification Level 1 Document Object Model (DOM)@footnote{https://www.w3.org/TR/REC-DOM-Level-1/}

La recommandation du `W3C' pour le DOM pris en charge par @ref{121,,xml.dom.minidom}.
@end table


@menu
* Objets DOM:: 
* Exemple DOM:: 
* minidom et le standard DOM:: 

@end menu

@node Objets DOM,Exemple DOM,,xml dom minidom --- Minimal DOM implementation
@anchor{library/xml dom minidom dom-objects}@anchor{3795}@anchor{library/xml dom minidom minidom-objects}@anchor{3796}
@subsubsection Objets DOM


La définition de l'API DOM pour Python est donnée dans le cadre de la documentation du module @ref{120,,xml.dom}. Cette section répertorie les différences entre l'API et @ref{121,,xml.dom.minidom}.

@geindex unlink() (méthode xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node unlink}@anchor{3797}
@deffn {Méthode} Node.unlink ()

Casse les références internes dans le DOM afin qu'elles soient récupérées sur les versions de Python sans ramasse-miettes cyclique. Même lorsque le ramasse-miettes cyclique est disponible, son utilisation peut libérer de grandes quantités de mémoire disponibles plus tôt, donc l'appeler sur les objets DOM dès qu'ils ne sont plus nécessaires est une bonne pratique. Il est suffisant de l'appeler sur l'objet @code{Document}, mais peut être appelée sur les nœuds enfants pour éliminer les enfants de ce nœud.

Vous pouvez éviter d'appeler cette méthode explicitement en utilisant l'instruction @ref{5bc,,with}. Le code suivant dissocie automatiquement `dom' lorsque le bloc @code{with} est quitté :

@example
with xml.dom.minidom.parse(datasource) as dom:
    ... # Work with dom.
@end example
@end deffn

@geindex writexml() (méthode xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node writexml}@anchor{3798}
@deffn {Méthode} Node.writexml (writer, indent='@w{'}, addindent='@w{'}, newl='@w{'}, encoding=None, standalone=None)

Écrit du XML dans l'objet `writer'. Cet objet reçoit du texte mais pas des octets en entrée, il doit avoir une méthode @code{write()} qui correspond à celle de l'interface objet fichier. Le paramètre `indent' est l'indentation du nœud actuel. Le paramètre `addindent' est l'indentation incrémentielle à utiliser pour les sous-nœuds du nœud actuel. Le paramètre `newl' spécifie la chaîne à utiliser pour terminer les nouvelles lignes.

Pour le nœud @code{Document}, un argument nommé supplémentaire `encoding' peut être utilisé pour spécifier le champ d'encodage de l'en-tête XML.

De même, l'indication explicite de l'argument `standalone' entraîne l'ajout des déclarations de document autonome au prologue du document XML. Si la valeur est définie sur @code{True}, @code{standalone="yes"} est ajoutée, sinon elle est définie sur @code{"no"}. Par défaut la déclaration n'est pas écrite dans le document.


Modifié dans la version 3.8: la méthode @ref{3798,,writexml()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.



Modifié dans la version 3.9: le paramètre `standalone' a été ajouté.

@end deffn

@geindex toxml() (méthode xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node toxml}@anchor{147d}
@deffn {Méthode} Node.toxml (encoding=None, standalone=None)

Renvoie une chaîne ou une chaîne d'octets contenant le XML représenté par le nœud DOM.

Avec un argument explicite `encoding' @footnote{
Le nom de codage inclus dans la sortie XML doit être conforme aux normes appropriées. Par exemple, @code{"UTF-8"} est valide, mais @code{"UTF8"} ne l'est pas dans la déclaration d'un document XML, même si Python l'accepte comme nom de codage. Voir @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl} et @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
}, le résultat est une chaîne d'octets dans l'encodage spécifié. Sans argument `encoding', le résultat est une chaîne Unicode et la déclaration XML dans la chaîne résultante ne spécifie pas d'encodage. Encoder cette chaîne dans un codage autre que UTF-8 est probablement incorrect, puisque UTF-8 est l'encodage par défaut de XML.

L'argument `standalone' se comporte exactement comme dans @ref{3798,,writexml()}.


Modifié dans la version 3.8: la méthode @ref{147d,,toxml()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.



Modifié dans la version 3.9: le paramètre `standalone' a été ajouté.

@end deffn

@geindex toprettyxml() (méthode xml.dom.minidom.Node)
@anchor{library/xml dom minidom xml dom minidom Node toprettyxml}@anchor{147e}
@deffn {Méthode} Node.toprettyxml (indent='\t', newl='\n', encoding=None, standalone=None)

Renvoie une version du document agréablement mise en forme. `indent' spécifie la chaîne d'indentation et est par défaut une tabulation ; `newl' spécifie la chaîne émise à la fin de chaque ligne et la valeur par défaut est @code{\n}.

L'argument `encoding' se comporte comme l'argument correspondant de @ref{147d,,toxml()}.

L'argument `standalone' se comporte exactement comme dans @ref{3798,,writexml()}.


Modifié dans la version 3.8: la méthode @ref{147e,,toprettyxml()} préserve désormais l'ordre des attributs spécifié par l'utilisateur.



Modifié dans la version 3.9: le paramètre `standalone' a été ajouté.

@end deffn

@node Exemple DOM,minidom et le standard DOM,Objets DOM,xml dom minidom --- Minimal DOM implementation
@anchor{library/xml dom minidom dom-example}@anchor{3799}@anchor{library/xml dom minidom id2}@anchor{379a}
@subsubsection Exemple DOM


Cet exemple de programme est un exemple assez réaliste de programme simple. Dans ce cas particulier, nous ne profitons pas beaucoup de la flexibilité du DOM.

@example
import xml.dom.minidom

document = """\
<slideshow>
<title>Demo slideshow</title>
<slide><title>Slide title</title>
<point>This is a demo</point>
<point>Of a program for processing slides</point>
</slide>

<slide><title>Another demo slide</title>
<point>It is important</point>
<point>To have more than</point>
<point>one slide</point>
</slide>
</slideshow>
"""

dom = xml.dom.minidom.parseString(document)

def getText(nodelist):
    rc = []
    for node in nodelist:
        if node.nodeType == node.TEXT_NODE:
            rc.append(node.data)
    return '@w{'}.join(rc)

def handleSlideshow(slideshow):
    print("<html>")
    handleSlideshowTitle(slideshow.getElementsByTagName("title")[0])
    slides = slideshow.getElementsByTagName("slide")
    handleToc(slides)
    handleSlides(slides)
    print("</html>")

def handleSlides(slides):
    for slide in slides:
        handleSlide(slide)

def handleSlide(slide):
    handleSlideTitle(slide.getElementsByTagName("title")[0])
    handlePoints(slide.getElementsByTagName("point"))

def handleSlideshowTitle(title):
    print(f"<title>@{getText(title.childNodes)@}</title>")

def handleSlideTitle(title):
    print(f"<h2>@{getText(title.childNodes)@}</h2>")

def handlePoints(points):
    print("<ul>")
    for point in points:
        handlePoint(point)
    print("</ul>")

def handlePoint(point):
    print(f"<li>@{getText(point.childNodes)@}</li>")

def handleToc(slides):
    for slide in slides:
        title = slide.getElementsByTagName("title")[0]
        print(f"<p>@{getText(title.childNodes)@}</p>")

handleSlideshow(dom)
@end example

@node minidom et le standard DOM,,Exemple DOM,xml dom minidom --- Minimal DOM implementation
@anchor{library/xml dom minidom minidom-and-dom}@anchor{379b}@anchor{library/xml dom minidom minidom-and-the-dom-standard}@anchor{379c}
@subsubsection `minidom' et le standard DOM


Le module @ref{121,,xml.dom.minidom} est essentiellement une interface vers DOM compatible DOM 1.0 avec certaines fonctionnalités DOM 2 (principalement des fonctionnalités d'espace de noms).

L'utilisation de l'interface DOM en Python est simple. Les règles de correspondances suivantes s'appliquent :


@itemize *

@item 
Les interfaces sont accessibles via des objets d'instance. Les applications ne doivent pas instancier les classes elles-mêmes ; elles doivent utiliser les fonctions de création disponibles sur l'objet @code{Document}. Les interfaces dérivées prennent en charge toutes les opérations (et attributs) des interfaces de base, ainsi que toutes les nouvelles opérations.

@item 
Les opérations sont utilisées comme méthodes. Puisque le DOM utilise uniquement les paramètres @ref{2e8,,in}, les arguments sont passés dans l'ordre normal (de gauche à droite). Il n'y a pas d'argument facultatif. Les opérations @code{void} renvoient @code{None}.

@item 
Les attributs `IDL' (`Interface Description Language') correspondent aux attributs d'instance. Pour des raisons de compatibilité avec la correspondance OMG (`Object Management Group') du langage `IDL' pour Python, un attribut @code{foo} est également accessible via les méthodes d'accès @code{_get_foo()} et @code{_set_foo()}. Les attributs @code{readonly} ne doivent pas être modifiés ; ce n'est pas vérifié au moment de l'exécution.

@item 
Les types @code{short int}, @code{unsigned int}, @code{unsigned long long} et @code{boolean} correspondent tous à des objets entiers Python.

@item 
Le type @code{DOMString} correspond aux chaînes Python. @ref{121,,xml.dom.minidom} prend en charge soit les octets, soit les chaînes, et produit normalement des chaînes. Les valeurs de type @code{DOMString} peuvent également être @code{None} là où la valeur `IDL' @code{null} est autorisée par la spécification DOM du W3C.

@item 
Les déclarations @code{const} correspondent aux variables dans leur portée respective (par exemple @code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE}) ; elles ne doivent pas être modifiées.

@item 
@code{DOMException} n'est actuellement pas pris en charge dans @ref{121,,xml.dom.minidom}. En lieu et place, @ref{121,,xml.dom.minidom} utilise des exceptions Python standard telles que @ref{522,,TypeError} et @ref{343,,AttributeError}.

@item 
Les objets @code{NodeList} sont implémentés à l'aide du type de liste natif de Python. Ces objets fournissent l'interface définie dans la spécification DOM, mais avec les versions antérieures de Python, ils ne prennent pas en charge l'API officielle. C'est cependant bien plus « Pythonique » que l’interface définie dans les recommandations du W3C.
@end itemize

Les interfaces suivantes n'ont aucune implémentation dans @ref{121,,xml.dom.minidom} :


@itemize *

@item 
@code{DOMTimeStamp}

@item 
@code{EntityReference}
@end itemize

La plupart d'entre elles reflètent des informations contenues dans le document XML qui ne sont pas d'utilité générale pour la plupart des utilisateurs du DOM.

@subsubheading Notes


@node xml dom pulldom --- Support for building partial DOM trees,xml sax --- Support for SAX2 parsers,xml dom minidom --- Minimal DOM implementation,Outils de traitement de balises structurées
@anchor{library/xml dom pulldom doc}@anchor{379d}@anchor{library/xml dom pulldom module-xml dom pulldom}@anchor{122}@anchor{library/xml dom pulldom xml-dom-pulldom-support-for-building-partial-dom-trees}@anchor{379e}
@subsection @code{xml.dom.pulldom} --- Support for building partial DOM trees


@geindex module; xml.dom.pulldom

`Code source :' Lib/xml/dom/pulldom.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/dom/pulldom.py}


__________________________________________________________________


Le module @ref{122,,xml.dom.pulldom} fournit un « analyseur à flux tiré » auquel on peut également demander de produire des fragments du document accessibles via le DOM si nécessaire. Le concept de base consiste à extraire des « événements » d'un flux XML entrant et à les traiter. Contrairement à `SAX' qui utilise également un modèle de traitement basé sur les événements avec des rappels, l'utilisateur d'un analyseur à flux tiré est responsable de l'extraction explicite des événements du flux, en parcourant ces événements en boucle jusqu'à ce que le traitement soit terminé ou qu'une condition d'erreur se produise.

@cartouche
@quotation Avertissement 
le module @ref{122,,xml.dom.pulldom} n'est pas sécurisé contre les données construites de façon malveillante. Si vous avez besoin d'analyser des données non sécurisées ou non authentifiées, référez-vous à @ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche


Modifié dans la version 3.7.1: l'analyseur `SAX' ne traite plus les entités externes générales par défaut pour augmenter la sécurité par défaut. Pour activer le traitement des entités externes, transmettez une instance d'analyseur personnalisée à :

@example
from xml.dom.pulldom import parse
from xml.sax import make_parser
from xml.sax.handler import feature_external_ges

parser = make_parser()
parser.setFeature(feature_external_ges, True)
parse(filename, parser=parser)
@end example


Exemple :

@example
from xml.dom import pulldom

doc = pulldom.parse('sales_items.xml')
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'item':
        if int(node.getAttribute('price')) > 50:
            doc.expandNode(node)
            print(node.toxml())
@end example

@code{event} est une constante parmi les éléments suivants :


@itemize *

@item 
@code{START_ELEMENT}

@item 
@code{END_ELEMENT}

@item 
@code{COMMENT}

@item 
@code{START_DOCUMENT}

@item 
@code{END_DOCUMENT}

@item 
@code{CHARACTERS}

@item 
@code{PROCESSING_INSTRUCTION}

@item 
@code{IGNORABLE_WHITESPACE}
@end itemize

@code{node} est un objet de type @code{xml.dom.minidom.Document}, @code{xml.dom.minidom.Element} ou @code{xml.dom.minidom.Text}.

Puisque le document est traité comme un flux « plat » d’événements, « l’arborescence » du document est implicitement parcourue et les éléments souhaités sont trouvés quelle que soit leur profondeur dans l’arborescence. En d'autres termes, il n'est pas nécessaire de prendre en compte les problèmes hiérarchiques tels que la recherche récursive des nœuds du document, même dans le cas où le contexte des éléments est important, et où il faudrait soit maintenir un état lié au contexte (c'est-à-dire se souvenir où l'on se trouve dans le document à un moment donné), soit utiliser la méthode @ref{379f,,DOMEventStream.expandNode()} et passer au traitement lié du DOM.

@geindex PullDom (classe dans xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom PullDom}@anchor{37a0}
@deffn {Classe} xml.dom.pulldom.PullDom (documentFactory=None)

Sous-classe de @ref{37a1,,xml.sax.handler.ContentHandler}.
@end deffn

@geindex SAX2DOM (classe dans xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom SAX2DOM}@anchor{37a2}
@deffn {Classe} xml.dom.pulldom.SAX2DOM (documentFactory=None)

Sous-classe de @ref{37a1,,xml.sax.handler.ContentHandler}.
@end deffn

@geindex parse() (dans le module xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom parse}@anchor{37a3}
@deffn {Fonction} xml.dom.pulldom.parse (stream_or_string, parser=None, bufsize=None)

Renvoie un @ref{71f,,DOMEventStream} à partir de l'entrée donnée. `stream_or_string' peut être soit un nom de fichier, soit un objet simili-fichier. `parser', s'il est donné, doit être un objet @ref{37a4,,XMLReader}. Cette fonction modifie le gestionnaire de documents de l'analyseur et active la prise en charge des espaces de noms ; les autres configurations de l'analyseur (comme la définition d'un résolveur d'entité) doivent avoir été effectuées à l'avance.
@end deffn

Si vous avez du XML dans une chaîne, vous pouvez utiliser la fonction @ref{37a5,,parseString()} à la place :

@geindex parseString() (dans le module xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom parseString}@anchor{37a5}
@deffn {Fonction} xml.dom.pulldom.parseString (string, parser=None)

Renvoie un @ref{71f,,DOMEventStream} qui représente `string' (Unicode).
@end deffn

@geindex default_bufsize (dans le module xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom default_bufsize}@anchor{37a6}
@deffn {Données} xml.dom.pulldom.default_bufsize

Valeur par défaut du paramètre `bufsize' de @ref{37a3,,parse()}.

La valeur de cette variable peut être modifiée avant d'appeler @ref{37a3,,parse()} et la nouvelle valeur prendra effet.
@end deffn

@menu
* Objets DOMEventStream:: 

@end menu

@node Objets DOMEventStream,,,xml dom pulldom --- Support for building partial DOM trees
@anchor{library/xml dom pulldom domeventstream-objects}@anchor{37a7}@anchor{library/xml dom pulldom id1}@anchor{37a8}
@subsubsection Objets `DOMEventStream'


@geindex DOMEventStream (classe dans xml.dom.pulldom)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream}@anchor{71f}
@deffn {Classe} xml.dom.pulldom.DOMEventStream (stream, parser, bufsize)


Modifié dans la version 3.11: Support for @ref{280,,__getitem__()} method has been removed.


@geindex getEvent() (méthode xml.dom.pulldom.DOMEventStream)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream getEvent}@anchor{37a9}
@deffn {Méthode} getEvent ()

Renvoie un `n'-uplet contenant `event' et le `node' actuel sous la forme d'un @code{xml.dom.minidom.Document} si l'événement est égal à @code{START_DOCUMENT}, un @code{xml.dom.minidom.Element} si l'événement est égal à @code{START_ELEMENT} ou @code{END_ELEMENT}, ou un @code{xml.dom.minidom.Text} si l'événement est égal à @code{CHARACTERS}. Le nœud actuel ne contient pas d'informations sur ses enfants, sauf si @ref{379f,,expandNode()} est appelé.
@end deffn

@geindex expandNode() (méthode xml.dom.pulldom.DOMEventStream)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream expandNode}@anchor{379f}
@deffn {Méthode} expandNode (node)

Développe tous les enfants de `node' dans `node'. Par exemple :

@example
from xml.dom import pulldom

xml = '<html><title>Foo</title> <p>Some text <div>and more</div></p> </html>'
doc = pulldom.parseString(xml)
for event, node in doc:
    if event == pulldom.START_ELEMENT and node.tagName == 'p':
        # Following statement only prints '<p/>'
        print(node.toxml())
        doc.expandNode(node)
        # Following statement prints node with all its children '<p>Some text <div>and more</div></p>'
        print(node.toxml())
@end example
@end deffn

@geindex reset() (méthode xml.dom.pulldom.DOMEventStream)
@anchor{library/xml dom pulldom xml dom pulldom DOMEventStream reset}@anchor{37aa}
@deffn {Méthode} reset ()
@end deffn
@end deffn

@node xml sax --- Support for SAX2 parsers,xml sax handler --- Base classes for SAX handlers,xml dom pulldom --- Support for building partial DOM trees,Outils de traitement de balises structurées
@anchor{library/xml sax doc}@anchor{37ab}@anchor{library/xml sax module-xml sax}@anchor{128}@anchor{library/xml sax xml-sax-support-for-sax2-parsers}@anchor{37ac}
@subsection @code{xml.sax} --- Support for SAX2 parsers


@geindex module; xml.sax

`Code source :' Lib/xml/sax/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/sax/__init__.py}


__________________________________________________________________


Le paquet @ref{128,,xml.sax} fournit des modules qui implémentent l'interface `Simple API for XML (SAX)' pour Python. Le paquet en lui-même fournit les exceptions `SAX' et les fonctions les plus utiles qui sont le plus utilisées par les utilisateurs de l'API `SAX'.

@cartouche
@quotation Avertissement 
le module @ref{128,,xml.sax} n'est pas sécurisé contre les données construites de façon malveillante. Si vous avez besoin d'analyser des données non sécurisées ou non authentifiées, lisez @ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche


Modifié dans la version 3.7.1: l'analyseur `SAX' ne traite plus les entités externes générales par défaut pour augmenter la sécurité. Auparavant, l'analyseur créait des connexions réseau pour extraire des fichiers distants ou des fichiers locaux chargés à partir du système de fichiers pour les `DTD' et les entités. La fonctionnalité peut être activée à nouveau avec la méthode @ref{37ad,,setFeature()} sur l'objet analyseur et l'argument @ref{37ae,,feature_external_ges}.


Les fonctions les plus utiles sont :

@geindex make_parser() (dans le module xml.sax)
@anchor{library/xml sax xml sax make_parser}@anchor{19c9}
@deffn {Fonction} xml.sax.make_parser (parser_list=[])

Crée et renvoie un objet @ref{37a4,,XMLReader} `SAX'. Le premier analyseur trouvé est utilisé. Si `parser_list' est fourni, il doit être un itérable de chaînes de caractères qui nomme des modules qui ont une fonction nommée @code{create_parser()}. Les modules listés dans `parser_list' sont utilisés avant les modules dans la liste par défaut des analyseurs.


Modifié dans la version 3.8: l'argument `parser_list' peut être n'importe quel itérable, pas seulement une liste.

@end deffn

@geindex parse() (dans le module xml.sax)
@anchor{library/xml sax xml sax parse}@anchor{1992}
@deffn {Fonction} xml.sax.parse (filename_or_stream, handler, error_handler=handler.ErrorHandler())

Crée un analyseur `SAX' et l'utilise pour analyser un document. Le document transmis comme `filename_or_stream', peut être un nom de fichier ou un objet fichier. Le paramètre `handler' doit être une instance @ref{37a1,,ContentHandler} `SAX'. Si un `error_handler' est donné, il doit être un @ref{37af,,ErrorHandler} `SAX' ; s'il est omis, une @ref{37b0,,SAXParseException} est levée sur toutes les erreurs. Il n'y a pas de valeur de retour, tout le travail doit être fait par le `handler' transmis.
@end deffn

@geindex parseString() (dans le module xml.sax)
@anchor{library/xml sax xml sax parseString}@anchor{e85}
@deffn {Fonction} xml.sax.parseString (string, handler, error_handler=handler.ErrorHandler())

Similaire à @ref{1992,,parse()}, mais analyse à partir d'un espace mémoire `string' reçu en tant que paramètre. `string' doit être une instance @ref{435,,str} ou un objet @ref{d1b,,octet-compatible}.


Modifié dans la version 3.5: ajout de la gestion des instances @ref{435,,str}.

@end deffn

Une application `SAX' typique utilise trois types d'objets : les `readers', les `handlers' et les sources d'entrée. `Reader' dans ce contexte est un autre terme pour « analyseur », c'est-à-dire un morceau de code qui lit les octets ou les caractères de la source d'entrée et qui produit une séquence d'événements. Les événements sont ensuite distribués aux objets du `handler', c'est-à-dire que le lecteur appelle une méthode sur le `handler'. L'application doit donc obtenir un objet `reader', créer ou ouvrir les sources d'entrée, créer les `handlers' et connecter ces objets tous ensemble. La dernière étape de la préparation, le `reader' est appelé à analyser l'entrée. Pendant l'analyse, les méthodes sur les objets du `handler' sont appelées en fonction d'événements structurels et syntaxiques à partir des données d'entrée.

Pour ces objets, seules les interfaces sont pertinentes ; elles ne sont pas normalement instanciées par l'application elle-même. Puisque Python n'a pas de notion explicite d'interface, elles sont formellement introduites en tant que classes, mais les applications peuvent utiliser des implémentations qui n'héritent pas des classes fournies. Les interfaces @ref{e84,,InputSource}, @ref{37b1,,Locator}, @code{Attributes}, @code{AttributesNS} et @ref{37a4,,XMLReader} sont définies dans le module @ref{12b,,xml.sax.xmlreader}. Les interfaces du `handler' sont définies dans @ref{129,,xml.sax.handler}. Pour plus de commodité, @ref{e84,,xml.sax.xmlreader.InputSource} (qui est souvent instanciée directement) et les classes du `handler' sont également disponibles à partir de @ref{128,,xml.sax}. Ces interfaces sont décrites ci-dessous.

En plus de ces classes, @ref{128,,xml.sax} fournit les classes d'exceptions suivantes.

@geindex SAXException
@anchor{library/xml sax xml sax SAXException}@anchor{37b2}
@deffn {Exception} xml.sax.SAXException (msg, exception=None)

Encapsule une erreur ou un avertissement XML. Cette classe peut contenir une erreur de base ou une information d'avertissement soit de l'analyseur XML ou de l'application : elle peut être sous-classée pour fournir des fonctionnalités supplémentaires ou pour ajouter une localisation. Noter que même si les `handlers' définis dans l'interface  @ref{37af,,ErrorHandler} reçoivent des instances de cette exception, ce n'est pas nécessaire de lever l'exception --- il est également utile en tant que conteneur pour l'information.

Quand elle est instanciée, `msg' doit être une description intelligible de l'erreur. Le paramètre optionnel `exception', s'il est donné, doit être @code{None} ou une exception qui a été interceptée par le code d'analyse et qui est transmise comme information.

Ceci est la classe de base pour les autres classes d'exception `SAX'.
@end deffn

@geindex SAXParseException
@anchor{library/xml sax xml sax SAXParseException}@anchor{37b0}
@deffn {Exception} xml.sax.SAXParseException (msg, exception, locator)

Sous-classe de @ref{37b2,,SAXException} élevée sur les erreurs d'analyse. Les instances de cette classe sont passées aux méthodes de l'interface @ref{37af,,ErrorHandler} `SAX' pour fournir des informations sur l'erreur d'analyse. Cette classe prend aussi en charge l'interface `SAX' @ref{37b1,,Locator} comme l'interface @ref{37b2,,SAXException}.
@end deffn

@geindex SAXNotRecognizedException
@anchor{library/xml sax xml sax SAXNotRecognizedException}@anchor{37b3}
@deffn {Exception} xml.sax.SAXNotRecognizedException (msg, exception=None)

Sous-classe de @ref{37b2,,SAXException} levée quand un @code{ XMLReader} `SAX' est confronté à une caractéristique ou à une propriété non reconnue. Les applications et les extensions `SAX' peuvent utiliser cette classe à des fins similaires.
@end deffn

@geindex SAXNotSupportedException
@anchor{library/xml sax xml sax SAXNotSupportedException}@anchor{37b4}
@deffn {Exception} xml.sax.SAXNotSupportedException (msg, exception=None)

Sous-classe de @ref{37b2,,SAXException} levée quand un @ref{37a4,,XMLReader} `SAX' est demandé pour activer une fonctionnalité qui n'est pas prise en charge, ou pour définir une propriété à une valeur que l'implémentation ne prend pas en charge. Les applications et les extensions `SAX' peuvent utiliser cette classe à des fins similaires.
@end deffn


@subsubheading Voir aussi



@table @asis

@item SAX : l'API simple pour XML@footnote{http://www.saxproject.org/}

Ce site est le point focal pour la définition de l'API `SAX'. Il offre une implémentation Java et une documentation en ligne. Des liens pour l'implémentation et des informations historiques sont également disponibles.

@item Module @ref{129,,xml.sax.handler}

Définitions des interfaces pour les objets fournis par l'application.

@item Module @ref{12a,,xml.sax.saxutils}

Fonctions pratiques pour une utilisation dans les applications `SAX'.

@item Module @ref{12b,,xml.sax.xmlreader}

Définitions des interfaces pour les objets fournis par l'analyseur.
@end table


@menu
* Les objets SAXException:: 

@end menu

@node Les objets SAXException,,,xml sax --- Support for SAX2 parsers
@anchor{library/xml sax sax-exception-objects}@anchor{37b5}@anchor{library/xml sax saxexception-objects}@anchor{37b6}
@subsubsection Les objets `SAXException'


La classe d'exception @ref{37b2,,SAXException} gère les méthodes suivantes :

@geindex getMessage() (méthode xml.sax.SAXException)
@anchor{library/xml sax xml sax SAXException getMessage}@anchor{37b7}
@deffn {Méthode} SAXException.getMessage ()

Renvoie un message intelligible décrivant la condition d'erreur.
@end deffn

@geindex getException() (méthode xml.sax.SAXException)
@anchor{library/xml sax xml sax SAXException getException}@anchor{37b8}
@deffn {Méthode} SAXException.getException ()

Renvoie un objet d'exception encapsulé ou @code{None}.
@end deffn

@node xml sax handler --- Base classes for SAX handlers,xml sax saxutils --- SAX Utilities,xml sax --- Support for SAX2 parsers,Outils de traitement de balises structurées
@anchor{library/xml sax handler doc}@anchor{37b9}@anchor{library/xml sax handler module-xml sax handler}@anchor{129}@anchor{library/xml sax handler xml-sax-handler-base-classes-for-sax-handlers}@anchor{37ba}
@subsection @code{xml.sax.handler} --- Base classes for SAX handlers


@geindex module; xml.sax.handler

`Code source :' Lib/xml/sax/handler.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/sax/handler.py}


__________________________________________________________________


L'API `SAX' définit cinq types de gestionnaires : les gestionnaires de contenu, les gestionnaires de `DTD', les gestionnaires d'erreurs, les résolveurs d'entités et les gestionnaires lexicaux. Les applications n'ont normalement besoin d'implémenter que les interfaces dont les événements les intéressent ; elles peuvent implémenter les interfaces dans un seul objet ou dans plusieurs objets. Les implémentations de gestionnaires doivent hériter des classes mères fournies dans le module @ref{129,,xml.sax.handler}, afin que toutes les méthodes aient des implémentations par défaut.

@geindex ContentHandler (classe dans xml.sax.handler)
@anchor{library/xml sax handler xml sax handler ContentHandler}@anchor{37a1}
@deffn {Classe} xml.sax.handler.ContentHandler

Il s'agit de l'interface de rappel principale de `SAX' et de la plus importante pour les applications. L'ordre des événements dans cette interface reflète l'ordre des informations dans le document.
@end deffn

@geindex DTDHandler (classe dans xml.sax.handler)
@anchor{library/xml sax handler xml sax handler DTDHandler}@anchor{37bb}
@deffn {Classe} xml.sax.handler.DTDHandler

Gestionnaires d'évènements `DTD'

Cette interface concerne uniquement les événements `DTD' requis pour une analyse basique (entités et attributs non analysés).
@end deffn

@geindex EntityResolver (classe dans xml.sax.handler)
@anchor{library/xml sax handler xml sax handler EntityResolver}@anchor{37bc}
@deffn {Classe} xml.sax.handler.EntityResolver

Interface de base pour résoudre les entités. Si vous créez un objet implémentant cette interface, puis enregistrez l'objet auprès de votre analyseur, l'analyseur appellera la méthode de votre objet pour résoudre toutes les entités externes.
@end deffn

@geindex ErrorHandler (classe dans xml.sax.handler)
@anchor{library/xml sax handler xml sax handler ErrorHandler}@anchor{37af}
@deffn {Classe} xml.sax.handler.ErrorHandler

Interface utilisée par l'analyseur pour présenter des messages d'erreur et d'avertissement à l'application. Les méthodes de cet objet permettent de choisir si les erreurs doivent être immédiatement converties en exceptions ou si elles doivent être traitées d'une autre manière.
@end deffn

@geindex LexicalHandler (classe dans xml.sax.handler)
@anchor{library/xml sax handler xml sax handler LexicalHandler}@anchor{846}
@deffn {Classe} xml.sax.handler.LexicalHandler

Interface utilisée par l'analyseur pour représenter des événements rares qui n'intéressent que peu d'applications.
@end deffn

En plus de ces classes, @ref{129,,xml.sax.handler} fournit des constantes symboliques pour les noms de fonctionnalités et de propriétés.

@geindex feature_namespaces (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_namespaces}@anchor{37bd}
@deffn {Données} xml.sax.handler.feature_namespaces


@display
valeur : @code{"http://xml.org/sax/features/namespaces"}@w{ }
vrai : effectue le traitement de l'espace de noms.@w{ }
faux : n'effectue pas le traitement des espaces de noms (implique `namespace-prefixes' ; valeur par défaut).@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex feature_namespace_prefixes (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_namespace_prefixes}@anchor{37be}
@deffn {Données} xml.sax.handler.feature_namespace_prefixes


@display
valeur : @code{"http://xml.org/sax/features/namespace-prefixes"}@w{ }
vrai : renvoie les noms et attributs avec les préfixes originaux utilisés dans les déclarations d'espaces de noms.@w{ }
faux : ne renvoie pas les attributs utilisés pour les déclarations d'espaces de noms et, éventuellement, ne signale pas les noms avec les préfixes originaux (par défaut).@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex feature_string_interning (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_string_interning}@anchor{37bf}
@deffn {Données} xml.sax.handler.feature_string_interning


@display
valeur : @code{"http://xml.org/sax/features/string-interning"}@w{ }
vrai : tous les noms d'éléments, préfixes, noms d'attributs, URI d'espace de noms et noms locaux sont rendus internes à l'aide de la fonction native correspondante.@w{ }
faux : les noms ne sont pas nécessairement rendus internes, bien qu'ils puissent l'être (par défaut).@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex feature_validation (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_validation}@anchor{37c0}
@deffn {Données} xml.sax.handler.feature_validation


@display
valeur : @code{"http://xml.org/sax/features/validation"}@w{ }
vrai : signale toutes les erreurs de validation (implique `external-general-entities' et `external-parameter-entities').@w{ }
faux : ne signale pas les erreurs de validation.@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex feature_external_ges (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_external_ges}@anchor{37ae}
@deffn {Données} xml.sax.handler.feature_external_ges


@display
valeur : @code{"http://xml.org/sax/features/external-general-entities"}@w{ }
vrai : Inclut toutes les entités générales (texte) externes.@w{ }
faux : n'inclut pas les entités générales externes.@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex feature_external_pes (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler feature_external_pes}@anchor{37c1}
@deffn {Données} xml.sax.handler.feature_external_pes


@display
valeur : @code{"http://xml.org/sax/features/external-parameter-entities"}@w{ }
vrai : Inclut toutes les entités de paramètres externes, y compris les sous-ensembles `DTD' externes.@w{ }
faux : n'inclue aucune entité de paramètre externe, même les sous-ensembles `DTD' externes.@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex all_features (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler all_features}@anchor{37c2}
@deffn {Données} xml.sax.handler.all_features

Liste de toutes les fonctionnalités.
@end deffn

@geindex property_lexical_handler (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_lexical_handler}@anchor{37c3}
@deffn {Données} xml.sax.handler.property_lexical_handler


@display
valeur : @code{"http://xml.org/sax/properties/lexical-handler"}@w{ }
type de données : @code{xml.sax.handler.LexicalHandler} (non pris en charge dans Python 2)@w{ }
description : gestionnaire d'extension facultatif pour les événements lexicaux tels que les commentaires.@w{ }
accès : lecture-écriture@w{ }
@end display


@end deffn

@geindex property_declaration_handler (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_declaration_handler}@anchor{37c4}
@deffn {Données} xml.sax.handler.property_declaration_handler


@display
valeur : @code{"http://xml.org/sax/properties/declaration-handler"}@w{ }
type de données : xml.sax.sax2lib.DeclHandler (non pris en charge dans Python 2)@w{ }
description : gestionnaire d'extension facultatif pour les événements liés à la `DTD' autres que les notations et les entités non analysées.@w{ }
accès : lecture-écriture@w{ }
@end display


@end deffn

@geindex property_dom_node (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_dom_node}@anchor{37c5}
@deffn {Données} xml.sax.handler.property_dom_node


@display
valeur : @code{"http://xml.org/sax/properties/dom-node"}@w{ }
type de données : org.w3c.dom.Node (non pris en charge dans Python 2)@w{ }
description : lors de l'analyse, le nœud DOM actuel visité s'il s'agit d'un itérateur DOM ; hors de l'analyse, le nœud racine du DOM pour l'itération.@w{ }
accès : (lors de l'analyse) en lecture seule ; (hors de l'analyse) lecture-écriture@w{ }
@end display


@end deffn

@geindex property_xml_string (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler property_xml_string}@anchor{37c6}
@deffn {Données} xml.sax.handler.property_xml_string


@display
valeur : @code{"http://xml.org/sax/properties/xml-string"}@w{ }
type de données : octets@w{ }
description : chaîne littérale de caractères qui était la source de l'événement en cours.@w{ }
accès : lecture seule@w{ }
@end display


@end deffn

@geindex all_properties (dans le module xml.sax.handler)
@anchor{library/xml sax handler xml sax handler all_properties}@anchor{37c7}
@deffn {Données} xml.sax.handler.all_properties

Liste de tous les noms de propriétés connus.
@end deffn

@menu
* Objets ContentHandler:: 
* Objets DTDHandler:: 
* Objets EntityResolver:: 
* Objets ErrorHandler:: 
* Objets LexicalHandler:: 

@end menu

@node Objets ContentHandler,Objets DTDHandler,,xml sax handler --- Base classes for SAX handlers
@anchor{library/xml sax handler content-handler-objects}@anchor{37c8}@anchor{library/xml sax handler contenthandler-objects}@anchor{37c9}
@subsubsection Objets `ContentHandler'


Les utilisateurs doivent sous-classer @ref{37a1,,ContentHandler} dans leur application. Les méthodes suivantes sont appelées par l'analyseur pour notifier les événements appropriés dans le document d'entrée :

@geindex setDocumentLocator() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler setDocumentLocator}@anchor{37ca}
@deffn {Méthode} ContentHandler.setDocumentLocator (locator)

Appelé par l'analyseur pour donner à l'application un localisateur permettant de localiser l'origine des événements du document.

Les analyseurs `SAX' sont fortement encouragés (bien que ce ne soit pas absolument obligatoire) à fournir un localisateur : s'ils le font, ils doivent fournir le localisateur à l'application en appelant cette méthode avant d'invoquer l'une des autres méthodes de l'interface `DocumentHandler'.

Le localisateur permet à l'application de déterminer la position finale de tout événement lié au document, même si l'analyseur ne signale pas d'erreur. En règle générale, l'application utilise ces informations pour signaler ses propres erreurs (telles que le contenu d'un champ texte qui ne correspond pas aux règles métier d'une application). Les informations renvoyées par le localisateur ne sont probablement pas suffisantes pour être utilisées avec un moteur de recherche.

Notez que le localisateur renvoie des informations correctes pendant la durée de l'invocation des événements dans cette interface. L'application ne doit pas tenter de l'utiliser à un autre moment.
@end deffn

@geindex startDocument() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startDocument}@anchor{37cb}
@deffn {Méthode} ContentHandler.startDocument ()

Reçoit la notification correspondant au début du document.

L'analyseur `SAX' invoque cette méthode une seule fois, avant toute autre méthode dans cette interface ou dans `DTDHandler' (sauf pour @ref{37ca,,setDocumentLocator()}).
@end deffn

@geindex endDocument() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endDocument}@anchor{37cc}
@deffn {Méthode} ContentHandler.endDocument ()

Reçoit la notification correspondant à la fin du document.

L'analyseur `SAX' n'invoque cette méthode qu'une seule fois et c'est la dernière méthode invoquée lors de l'analyse. L'analyseur ne doit pas invoquer cette méthode tant qu'il n'a pas abandonné l'analyse (en raison d'une erreur irrécupérable) ou atteint la fin de l'entrée.
@end deffn

@geindex startPrefixMapping() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startPrefixMapping}@anchor{37cd}
@deffn {Méthode} ContentHandler.startPrefixMapping (prefix, uri)

Commence la portée d’une correspondance d’espace de noms préfixe-URI.

Les informations de cet événement ne sont pas nécessaires au traitement normal des espaces de noms : le lecteur XML `SAX' remplace automatiquement les préfixes des noms d'éléments et d'attributs lorsque la fonctionnalité @code{feature_namespaces} est activée (la valeur par défaut).

Il existe cependant des cas où les applications doivent utiliser des préfixes dans des champs textes ou dans les valeurs d'attribut, où ils ne peuvent pas être développés automatiquement en toute sécurité ; les événements @ref{37cd,,startPrefixMapping()} et @ref{37ce,,endPrefixMapping()} fournissent les informations à l'application pour développer elle-même les préfixes dans ces contextes, si nécessaire.

@c XXX This is not really the default, is it? MvL

Notez qu'il n'est pas garanti que les événements @ref{37cd,,startPrefixMapping()} et @ref{37ce,,endPrefixMapping()} soient correctement imbriqués les uns par rapport aux autres : tout événement @ref{37cd,,startPrefixMapping()} se produit avant l'événement @ref{14f9,,startElement()} correspondant, et tout événement @ref{37ce,,endPrefixMapping()} se produit après l'événement @ref{14fa,,endElement()} correspondant, mais leur ordre n'est pas garanti.
@end deffn

@geindex endPrefixMapping() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endPrefixMapping}@anchor{37ce}
@deffn {Méthode} ContentHandler.endPrefixMapping (prefix)

Termine la portée d’une correspondance préfixe-URI.

Voir @ref{37cd,,startPrefixMapping()} pour plus de détails. Cet événement se produit toujours après l'événement @ref{14fa,,endElement()} correspondant, mais l'ordre des événements @ref{37ce,,endPrefixMapping()} n'est pas garanti entre eux.
@end deffn

@geindex startElement() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startElement}@anchor{14f9}
@deffn {Méthode} ContentHandler.startElement (name, attrs)

Signale le début d’un élément en mode sans espaces de noms.

Le paramètre `name' contient le nom brut XML 1.0 du type d'élément sous forme de chaîne et le paramètre `attrs' contient un objet de l'interface @code{Attributes} (voir @ref{37cf,,The Attributes Interface}) contenant les attributs de l'élément. L'objet passé comme `attrs' peut être réutilisé par l'analyseur ; conserver une référence à celui-ci n’est pas un moyen fiable de conserver une copie des attributs. Pour conserver une copie des attributs, utilisez la méthode @ref{25,,copy()} de l'objet `attrs'.
@end deffn

@geindex endElement() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endElement}@anchor{14fa}
@deffn {Méthode} ContentHandler.endElement (name)

Signale la fin d'un élément en mode sans espaces de noms.

Le paramètre `name' contient le nom du type d'élément, tout comme pour l'événement @ref{14f9,,startElement()}.
@end deffn

@geindex startElementNS() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler startElementNS}@anchor{37d0}
@deffn {Méthode} ContentHandler.startElementNS (name, qname, attrs)

Signale le début d’un élément en mode avec espaces de noms.

Le paramètre `name' contient le nom du type d'élément sous forme de `n'-uplet @code{(uri, localname)}, le paramètre `qname' contient le nom XML 1.0 brut utilisé dans le document source et le paramètre `attrs' contient une instance de l'interface @code{AttributesNS} (voir @ref{37d1,,The AttributesNS Interface}) contenant les attributs de l'élément. Si aucun espace de noms n'est associé à l'élément, le composant `uri' de `name' est @code{None}. L'objet passé comme `attrs' peut être réutilisé par l'analyseur ; conserver une référence à celui-ci n’est pas un moyen fiable de conserver une copie des attributs. Pour conserver une copie des attributs, utilisez la méthode @ref{25,,copy()} de l'objet `attrs'.

Les analyseurs peuvent définir le paramètre `qname' à @code{None}, à moins que la fonctionnalité @code{feature_namespace_prefixes} ne soit activée.
@end deffn

@geindex endElementNS() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler endElementNS}@anchor{37d2}
@deffn {Méthode} ContentHandler.endElementNS (name, qname)

Signale la fin d'un élément en mode avec espaces de noms.

Le paramètre `name' contient le nom du type d'élément, tout comme avec la méthode @ref{37d0,,startElementNS()}, de même que le paramètre `qname'.
@end deffn

@geindex characters() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler characters}@anchor{14fb}
@deffn {Méthode} ContentHandler.characters (content)

Reçoit une notification correspondant à des données de type caractère.

L'analyseur appelle cette méthode pour signaler chaque morceau de données de caractères. Les analyseurs `SAX' peuvent renvoyer toutes les données de caractères contiguës en un seul morceau ou ils peuvent les diviser en plusieurs morceaux ; cependant, tous les caractères d'un événement doivent provenir de la même entité externe afin que le localisateur fournisse des informations utiles.

`content' peut être une instance de chaîne ou d'octets ; le module lecteur @code{expat} produit toujours des chaînes.

@cartouche
@quotation Note 
l'interface `SAX 1' précédente fournie par Python XML utilisait une interface plus proche de Java pour cette méthode. Étant donné que la plupart des analyseurs utilisés à partir de Python ne tiraient pas parti de l’ancienne interface, la signature la plus simple a été choisie pour la remplacer. Pour convertir l'ancien code vers la nouvelle interface, utilisez `content' au lieu de découper le contenu avec les anciens paramètres `offset' et `length'.
@end quotation
@end cartouche
@end deffn

@geindex ignorableWhitespace() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler ignorableWhitespace}@anchor{37d3}
@deffn {Méthode} ContentHandler.ignorableWhitespace (whitespace)

Reçoit une notification en cas d'espaces pouvant être ignorées dans le contenu de l'élément.

Les analyseurs validateurs doivent utiliser cette méthode pour signaler chaque morceau d'espaces pouvant être ignorées (voir la recommandation W3C XML 1.0, section 2.10) : les analyseurs non validateurs peuvent également utiliser cette méthode s'ils sont capables d'analyser et d'utiliser des modèles de contenu.

Les analyseurs `SAX' peuvent renvoyer tous les espaces contigües en un seul morceau ou ils peuvent le diviser en plusieurs morceaux ; cependant, tous les caractères d'un événement doivent provenir de la même entité externe, afin que le localisateur fournisse des informations utiles.
@end deffn

@geindex processingInstruction() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler processingInstruction}@anchor{37d4}
@deffn {Méthode} ContentHandler.processingInstruction (target, data)

Reçoit une notification correspondant à une instruction de traitement.

L'analyseur invoque cette méthode une fois pour chaque instruction de traitement trouvée : notez que les instructions de traitement peuvent survenir avant ou après l'élément principal du document.

Un analyseur `SAX' ne doit jamais rapporter une déclaration XML (XML 1.0, section 2.8) ou une déclaration texte (XML 1.0, section 4.3.1) en utilisant cette méthode.
@end deffn

@geindex skippedEntity() (méthode xml.sax.handler.ContentHandler)
@anchor{library/xml sax handler xml sax handler ContentHandler skippedEntity}@anchor{37d5}
@deffn {Méthode} ContentHandler.skippedEntity (name)

Reçoit une notification correspondant à une entité ignorée.

L'analyseur invoque cette méthode une fois pour chaque entité ignorée. Les processeurs non validateurs peuvent ignorer les entités s'ils n'ont pas vu les déclarations (parce que, par exemple, l'entité a été déclarée dans un sous-ensemble `DTD' externe). Tous les processeurs peuvent ignorer les entités externes, en fonction des valeurs des propriétés @code{feature_external_ges} et @code{feature_external_pes}.
@end deffn

@node Objets DTDHandler,Objets EntityResolver,Objets ContentHandler,xml sax handler --- Base classes for SAX handlers
@anchor{library/xml sax handler dtd-handler-objects}@anchor{37d6}@anchor{library/xml sax handler dtdhandler-objects}@anchor{37d7}
@subsubsection Objets `DTDHandler'


Les instances @ref{37bb,,DTDHandler} fournissent les méthodes suivantes :

@geindex notationDecl() (méthode xml.sax.handler.DTDHandler)
@anchor{library/xml sax handler xml sax handler DTDHandler notationDecl}@anchor{37d8}
@deffn {Méthode} DTDHandler.notationDecl (name, publicId, systemId)

Gère un événement de déclaration de notation.
@end deffn

@geindex unparsedEntityDecl() (méthode xml.sax.handler.DTDHandler)
@anchor{library/xml sax handler xml sax handler DTDHandler unparsedEntityDecl}@anchor{37d9}
@deffn {Méthode} DTDHandler.unparsedEntityDecl (name, publicId, systemId, ndata)

Gère un événement de déclaration d'entité non analysé.
@end deffn

@node Objets EntityResolver,Objets ErrorHandler,Objets DTDHandler,xml sax handler --- Base classes for SAX handlers
@anchor{library/xml sax handler entity-resolver-objects}@anchor{37da}@anchor{library/xml sax handler entityresolver-objects}@anchor{37db}
@subsubsection Objets `EntityResolver'


@geindex resolveEntity() (méthode xml.sax.handler.EntityResolver)
@anchor{library/xml sax handler xml sax handler EntityResolver resolveEntity}@anchor{37dc}
@deffn {Méthode} EntityResolver.resolveEntity (publicId, systemId)

Résout l'identifiant système d'une entité et renvoie soit l'identifiant système à partir duquel lire sous forme de chaîne, soit un `InputSource' à partir duquel lire. L'implémentation par défaut renvoie `systemId'.
@end deffn

@node Objets ErrorHandler,Objets LexicalHandler,Objets EntityResolver,xml sax handler --- Base classes for SAX handlers
@anchor{library/xml sax handler errorhandler-objects}@anchor{37dd}@anchor{library/xml sax handler sax-error-handler}@anchor{37de}
@subsubsection Objets `ErrorHandler'


Objects with this interface are used to receive error and warning information
from the @ref{37a4,,XMLReader}.  If you create an object that
implements this interface, then register the object with your
@ref{37a4,,XMLReader}, the parser
will call the methods in your object to report all warnings and errors. There
are three levels of errors available: warnings, (possibly) recoverable errors,
and unrecoverable errors.  All methods take a @ref{37b0,,SAXParseException} as the
only parameter.  Errors and warnings may be converted to an exception by raising
the passed-in exception object.

@geindex error() (méthode xml.sax.handler.ErrorHandler)
@anchor{library/xml sax handler xml sax handler ErrorHandler error}@anchor{37df}
@deffn {Méthode} ErrorHandler.error (exception)

Appelée lorsque l'analyseur rencontre une erreur récupérable. Si cette méthode ne génère pas d'exception, l'analyse peut continuer, mais l'application ne doit pas attendre d'autres informations concernant le document. Autoriser l'analyseur à continuer peut permettre de découvrir des erreurs supplémentaires dans le document d'entrée.
@end deffn

@geindex fatalError() (méthode xml.sax.handler.ErrorHandler)
@anchor{library/xml sax handler xml sax handler ErrorHandler fatalError}@anchor{37e0}
@deffn {Méthode} ErrorHandler.fatalError (exception)

Appelée lorsque l'analyseur rencontre une erreur irrécupérable ; l'analyse devrait se terminer au retour de cette méthode.
@end deffn

@geindex warning() (méthode xml.sax.handler.ErrorHandler)
@anchor{library/xml sax handler xml sax handler ErrorHandler warning}@anchor{37e1}
@deffn {Méthode} ErrorHandler.warning (exception)

Appelée lorsque l'analyseur présente des informations d'avertissement mineures à l'application. L'analyse devrait se poursuivre lorsque cette méthode termine et les informations du document continueront d'être transmises à l'application. La levée d’une exception dans cette méthode entraîne la fin de l’analyse.
@end deffn

@node Objets LexicalHandler,,Objets ErrorHandler,xml sax handler --- Base classes for SAX handlers
@anchor{library/xml sax handler lexical-handler-objects}@anchor{37e2}@anchor{library/xml sax handler lexicalhandler-objects}@anchor{37e3}
@subsubsection Objets `LexicalHandler'


Gestionnaire `SAX2' facultatif pour les événements lexicaux.

Ce gestionnaire est utilisé pour obtenir des informations lexicales relatives à un document XML. Les informations lexicales incluent des informations décrivant le codage du document utilisé et les commentaires XML intégrés dans le document, ainsi que les limites des sections pour la `DTD' et pour toutes les sections `CDATA'. Les gestionnaires lexicaux sont utilisés de la même manière que les gestionnaires de contenu.

Définissez le `LexicalHandler' d'un `XMLReader' en utilisant la méthode `setProperty' avec l'identifiant de propriété @code{'http://xml.org/sax/properties/lexical-handler'}.

@geindex comment() (méthode xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler comment}@anchor{37e4}
@deffn {Méthode} LexicalHandler.comment (content)

Signale un commentaire n'importe où dans le document (y compris la `DTD' et en dehors de l'élément de document).
@end deffn

@geindex startDTD() (méthode xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler startDTD}@anchor{37e5}
@deffn {Méthode} LexicalHandler.startDTD (name, public_id, system_id)

Signale le début des déclarations `DTD' si le document a une `DTD' associée.
@end deffn

@geindex endDTD() (méthode xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler endDTD}@anchor{37e6}
@deffn {Méthode} LexicalHandler.endDTD ()

Signale la fin de la déclaration de la `DTD'.
@end deffn

@geindex startCDATA() (méthode xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler startCDATA}@anchor{37e7}
@deffn {Méthode} LexicalHandler.startCDATA ()

Signale le début d’une section marquée `CDATA'.

Le contenu de la section marquée `CDATA' est signalé via le gestionnaire de données de type caractère.
@end deffn

@geindex endCDATA() (méthode xml.sax.handler.LexicalHandler)
@anchor{library/xml sax handler xml sax handler LexicalHandler endCDATA}@anchor{37e8}
@deffn {Méthode} LexicalHandler.endCDATA ()

Signale la fin d’une section marquée `CDATA'.
@end deffn

@node xml sax saxutils --- SAX Utilities,xml sax xmlreader --- Interface for XML parsers,xml sax handler --- Base classes for SAX handlers,Outils de traitement de balises structurées
@anchor{library/xml sax utils doc}@anchor{37e9}@anchor{library/xml sax utils module-xml sax saxutils}@anchor{12a}@anchor{library/xml sax utils xml-sax-saxutils-sax-utilities}@anchor{37ea}
@subsection @code{xml.sax.saxutils} --- SAX Utilities


@geindex module; xml.sax.saxutils

`Code source :' Lib/xml/sax/saxutils.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/sax/saxutils.py}


__________________________________________________________________


Le module  @ref{12a,,xml.sax.saxutils} contient des classes et fonctions qui sont fréquemment utiles en créant des applications SAX, soit en utilisation directe, soit en classes de base.

@geindex escape() (dans le module xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils escape}@anchor{37eb}
@deffn {Fonction} xml.sax.saxutils.escape (data, entities=@{@})

Échappe @code{'&'}, @code{'<'}, et @code{'>'} dans une chaine de caractères de données.

Vous pouvez échapper d'autres chaines de caractères de données en passant un dictionnaire au paramètre optionnel `entities'. Les clés et valeurs doivent toutes être des chaines de caractères ; chaque clé sera remplacée par sa valeur correspondante. Les caractères @code{'&'}, @code{'<'} et @code{'>'} sont toujours échappés même si `entities' est donné en paramètre.

@cartouche
@quotation Note 
This function should only be used to escape characters that
can't be used directly in XML. Do not use this function as a general
string translation function.
@end quotation
@end cartouche
@end deffn

@geindex unescape() (dans le module xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils unescape}@anchor{37ec}
@deffn {Fonction} xml.sax.saxutils.unescape (data, entities=@{@})

`Parse' @code{'&amp;'}, @code{'&lt;'}, et @code{'&gt;'} dans une chaine de caractères de données.

Vous pouvez dé-échapper d'autres chaines de caractères de données en passant un dictionnaire au paramètre optionnel `entities'. Les clés et valeurs doivent toutes être des chaines de caractères ; chaque clé sera remplacée par sa valeur correspondante. Les caractères @code{'&'}, @code{'<'} et @code{'>'} sont toujours dé-échappés même si `entities' est donné en paramètre.
@end deffn

@geindex quoteattr() (dans le module xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils quoteattr}@anchor{37ed}
@deffn {Fonction} xml.sax.saxutils.quoteattr (data, entities=@{@})

Similaire à @ref{37eb,,escape()}, mais prépare aussi `data' pour être utilisé comme une valeur d'attribut. La valeur renvoyée est une version entre guillemets de `data' avec tous les remplacements supplémentaires nécessaires. @ref{37ed,,quoteattr()} va sélectionner un caractère guillemet basé sur le contenu de `data', en essayant d’éviter d'encoder tous les caractères guillemets dans la chaine de caractères. Si les caractères guillemet simple et guillemets sont déjà dans `data', les caractères guillemets simples seront encodés et `data' sera entouré de guillemets. La chaine de caractères résultante pourra être utilisée en tant que valeur d'attribut :

@example
>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
<element attr="ab ' cd &quot; ef">
@end example

Cette fonction est utile quand vous générez des valeurs d'attributs pour du HTML ou n'importe quel SGML en utilisant la syntaxe concrète de référence.
@end deffn

@geindex XMLGenerator (classe dans xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils XMLGenerator}@anchor{37ee}
@deffn {Classe} xml.sax.saxutils.XMLGenerator (out=None, encoding='iso-8859-1', short_empty_elements=False)

Cette classe implémente l'interface @ref{37a1,,ContentHandler} en écrivant les événements SAX dans un document XML. En d'autres termes, utiliser un @ref{37ee,,XMLGenerator} en tant que gestionnaire de contenu reproduira le document original qui était analysé. `out' devrait être un objet de type fichier qui est par défaut `sys.stdout'. `encoding' est l'encodage du flux de sortie qui est par défaut @code{'iso-8859-1'}. `short_empty_elements' contrôle le formatage des éléments qui ne contiennent rien :  si @code{False} (par défaut), ils sont émis comme une paire de balises (début, fin). Si la valeur est @code{True}, ils sont émis comme une balise seule auto-fermante.


Modifié dans la version 3.2: Added the `short_empty_elements' parameter.

@end deffn

@geindex XMLFilterBase (classe dans xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils XMLFilterBase}@anchor{37ef}
@deffn {Classe} xml.sax.saxutils.XMLFilterBase (base)

Cette classe est faite pour être entre @ref{37a4,,XMLReader} et le gestionnaire des événements de l'application client. Par défaut, elle ne fait rien mais passe les requêtes au lecteur et les événements au gestionnaire sans les modifier, mais des sous-classes peuvent surcharger des méthodes spécifiques pour modifier le flux d’événements ou la configuration des requêtes à leur passage.
@end deffn

@geindex prepare_input_source() (dans le module xml.sax.saxutils)
@anchor{library/xml sax utils xml sax saxutils prepare_input_source}@anchor{37f0}
@deffn {Fonction} xml.sax.saxutils.prepare_input_source (source, base='@w{'})

This function takes an input source and an optional base URL and returns a
fully resolved @ref{e84,,InputSource} object ready for
reading.  The input source can be given as a string, a file-like object, or
an @ref{e84,,InputSource} object; parsers will use this
function to implement the polymorphic `source' argument to their
@ref{37f1,,parse()} method.
@end deffn

@node xml sax xmlreader --- Interface for XML parsers,xml parsers expat --- Fast XML parsing using Expat,xml sax saxutils --- SAX Utilities,Outils de traitement de balises structurées
@anchor{library/xml sax reader doc}@anchor{37f2}@anchor{library/xml sax reader module-xml sax xmlreader}@anchor{12b}@anchor{library/xml sax reader xml-sax-xmlreader-interface-for-xml-parsers}@anchor{37f3}
@subsection @code{xml.sax.xmlreader} --- Interface for XML parsers


@geindex module; xml.sax.xmlreader

`Source code:' Lib/xml/sax/xmlreader.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xml/sax/xmlreader.py}


__________________________________________________________________


SAX parsers implement the @ref{37a4,,XMLReader} interface. They are implemented in
a Python module, which must provide a function @code{create_parser()}. This
function is invoked by  @ref{19c9,,xml.sax.make_parser()} with no arguments to create
a new  parser object.

@geindex XMLReader (classe dans xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader}@anchor{37a4}
@deffn {Classe} xml.sax.xmlreader.XMLReader

Base class which can be inherited by SAX parsers.
@end deffn

@geindex IncrementalParser (classe dans xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser}@anchor{37f4}
@deffn {Classe} xml.sax.xmlreader.IncrementalParser

In some cases, it is desirable not to parse an input source at once, but to feed
chunks of the document as they get available. Note that the reader will normally
not read the entire file, but read it in chunks as well; still @code{parse()}
won't return until the entire document is processed. So these interfaces should
be used if the blocking behaviour of @code{parse()} is not desirable.

When the parser is instantiated it is ready to begin accepting data from the
feed method immediately. After parsing has been finished with a call to close
the reset method must be called to make the parser ready to accept new data,
either from feed or using the parse method.

Note that these methods must `not' be called during parsing, that is, after
parse has been called and before it returns.

By default, the class also implements the parse method of the XMLReader
interface using the feed, close and reset methods of the IncrementalParser
interface as a convenience to SAX 2.0 driver writers.
@end deffn

@geindex Locator (classe dans xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader Locator}@anchor{37b1}
@deffn {Classe} xml.sax.xmlreader.Locator

Interface for associating a SAX event with a document location. A locator object
will return valid results only during calls to DocumentHandler methods; at any
other time, the results are unpredictable. If information is not available,
methods may return @code{None}.
@end deffn

@geindex InputSource (classe dans xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader InputSource}@anchor{e84}
@deffn {Classe} xml.sax.xmlreader.InputSource (system_id=None)

Encapsulation of the information needed by the @ref{37a4,,XMLReader} to read
entities.

This class may include information about the public identifier, system
identifier, byte stream (possibly with character encoding information) and/or
the character stream of an entity.

Applications will create objects of this class for use in the
@ref{37f1,,XMLReader.parse()} method and for returning from
EntityResolver.resolveEntity.

An @ref{e84,,InputSource} belongs to the application, the @ref{37a4,,XMLReader} is
not allowed to modify @ref{e84,,InputSource} objects passed to it from the
application, although it may make copies and modify those.
@end deffn

@geindex AttributesImpl (classe dans xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader AttributesImpl}@anchor{37f5}
@deffn {Classe} xml.sax.xmlreader.AttributesImpl (attrs)

This is an implementation of the @code{Attributes} interface (see section
@ref{37cf,,The Attributes Interface}).  This is a dictionary-like object which
represents the element attributes in a @code{startElement()} call. In addition
to the most useful dictionary operations, it supports a number of other
methods as described by the interface. Objects of this class should be
instantiated by readers; `attrs' must be a dictionary-like object containing
a mapping from attribute names to attribute values.
@end deffn

@geindex AttributesNSImpl (classe dans xml.sax.xmlreader)
@anchor{library/xml sax reader xml sax xmlreader AttributesNSImpl}@anchor{37f6}
@deffn {Classe} xml.sax.xmlreader.AttributesNSImpl (attrs, qnames)

Namespace-aware variant of @ref{37f5,,AttributesImpl}, which will be passed to
@code{startElementNS()}. It is derived from @ref{37f5,,AttributesImpl}, but
understands attribute names as two-tuples of `namespaceURI' and
`localname'. In addition, it provides a number of methods expecting qualified
names as they appear in the original document.  This class implements the
@code{AttributesNS} interface (see section @ref{37d1,,The AttributesNS Interface}).
@end deffn

@menu
* XMLReader Objects:: 
* IncrementalParser Objects:: 
* Locator Objects:: 
* InputSource Objects:: 
* The Attributes Interface:: 
* The AttributesNS Interface:: 

@end menu

@node XMLReader Objects,IncrementalParser Objects,,xml sax xmlreader --- Interface for XML parsers
@anchor{library/xml sax reader id1}@anchor{37f7}@anchor{library/xml sax reader xmlreader-objects}@anchor{37f8}
@subsubsection XMLReader Objects


The @ref{37a4,,XMLReader} interface supports the following methods:

@geindex parse() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader parse}@anchor{37f1}
@deffn {Méthode} XMLReader.parse (source)

Process an input source, producing SAX events. The `source' object can be a
system identifier (a string identifying the input source -- typically a file
name or a URL), a @ref{226,,pathlib.Path} or @ref{29d,,path-like}
object, or an @ref{e84,,InputSource} object. When
@ref{37f1,,parse()} returns, the input is completely processed, and the parser object
can be discarded or reset.


Modifié dans la version 3.5: Added support of character streams.



Modifié dans la version 3.8: Added support of path-like objects.

@end deffn

@geindex getContentHandler() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getContentHandler}@anchor{37f9}
@deffn {Méthode} XMLReader.getContentHandler ()

Return the current @ref{37a1,,ContentHandler}.
@end deffn

@geindex setContentHandler() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setContentHandler}@anchor{37fa}
@deffn {Méthode} XMLReader.setContentHandler (handler)

Set the current @ref{37a1,,ContentHandler}.  If no
@ref{37a1,,ContentHandler} is set, content events will be
discarded.
@end deffn

@geindex getDTDHandler() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getDTDHandler}@anchor{37fb}
@deffn {Méthode} XMLReader.getDTDHandler ()

Return the current @ref{37bb,,DTDHandler}.
@end deffn

@geindex setDTDHandler() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setDTDHandler}@anchor{37fc}
@deffn {Méthode} XMLReader.setDTDHandler (handler)

Set the current @ref{37bb,,DTDHandler}.  If no
@ref{37bb,,DTDHandler} is set, DTD
events will be discarded.
@end deffn

@geindex getEntityResolver() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getEntityResolver}@anchor{37fd}
@deffn {Méthode} XMLReader.getEntityResolver ()

Return the current @ref{37bc,,EntityResolver}.
@end deffn

@geindex setEntityResolver() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setEntityResolver}@anchor{37fe}
@deffn {Méthode} XMLReader.setEntityResolver (handler)

Set the current @ref{37bc,,EntityResolver}.  If no
@ref{37bc,,EntityResolver} is set,
attempts to resolve an external entity will result in opening the system
identifier for the entity, and fail if it is not available.
@end deffn

@geindex getErrorHandler() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getErrorHandler}@anchor{37ff}
@deffn {Méthode} XMLReader.getErrorHandler ()

Return the current @ref{37af,,ErrorHandler}.
@end deffn

@geindex setErrorHandler() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setErrorHandler}@anchor{3800}
@deffn {Méthode} XMLReader.setErrorHandler (handler)

Set the current error handler.  If no @ref{37af,,ErrorHandler}
is set, errors will be raised as exceptions, and warnings will be printed.
@end deffn

@geindex setLocale() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setLocale}@anchor{3801}
@deffn {Méthode} XMLReader.setLocale (locale)

Allow an application to set the locale for errors and warnings.

SAX parsers are not required to provide localization for errors and warnings; if
they cannot support the requested locale, however, they must raise a SAX
exception.  Applications may request a locale change in the middle of a parse.
@end deffn

@geindex getFeature() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getFeature}@anchor{3802}
@deffn {Méthode} XMLReader.getFeature (featurename)

Return the current setting for feature `featurename'.  If the feature is not
recognized, @code{SAXNotRecognizedException} is raised. The well-known
featurenames are listed in the module @ref{129,,xml.sax.handler}.
@end deffn

@geindex setFeature() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setFeature}@anchor{37ad}
@deffn {Méthode} XMLReader.setFeature (featurename, value)

Set the `featurename' to `value'. If the feature is not recognized,
@code{SAXNotRecognizedException} is raised. If the feature or its setting is not
supported by the parser, `SAXNotSupportedException' is raised.
@end deffn

@geindex getProperty() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader getProperty}@anchor{3803}
@deffn {Méthode} XMLReader.getProperty (propertyname)

Return the current setting for property `propertyname'. If the property is not
recognized, a @code{SAXNotRecognizedException} is raised. The well-known
propertynames are listed in the module @ref{129,,xml.sax.handler}.
@end deffn

@geindex setProperty() (méthode xml.sax.xmlreader.XMLReader)
@anchor{library/xml sax reader xml sax xmlreader XMLReader setProperty}@anchor{3804}
@deffn {Méthode} XMLReader.setProperty (propertyname, value)

Set the `propertyname' to `value'. If the property is not recognized,
@code{SAXNotRecognizedException} is raised. If the property or its setting is
not supported by the parser, `SAXNotSupportedException' is raised.
@end deffn

@node IncrementalParser Objects,Locator Objects,XMLReader Objects,xml sax xmlreader --- Interface for XML parsers
@anchor{library/xml sax reader incremental-parser-objects}@anchor{3805}@anchor{library/xml sax reader incrementalparser-objects}@anchor{3806}
@subsubsection IncrementalParser Objects


Instances of @ref{37f4,,IncrementalParser} offer the following additional methods:

@geindex feed() (méthode xml.sax.xmlreader.IncrementalParser)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser feed}@anchor{3807}
@deffn {Méthode} IncrementalParser.feed (data)

Process a chunk of `data'.
@end deffn

@geindex close() (méthode xml.sax.xmlreader.IncrementalParser)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser close}@anchor{3808}
@deffn {Méthode} IncrementalParser.close ()

Assume the end of the document. That will check well-formedness conditions that
can be checked only at the end, invoke handlers, and may clean up resources
allocated during parsing.
@end deffn

@geindex reset() (méthode xml.sax.xmlreader.IncrementalParser)
@anchor{library/xml sax reader xml sax xmlreader IncrementalParser reset}@anchor{3809}
@deffn {Méthode} IncrementalParser.reset ()

This method is called after close has been called to reset the parser so that it
is ready to parse new documents. The results of calling parse or feed after
close without calling reset are undefined.
@end deffn

@node Locator Objects,InputSource Objects,IncrementalParser Objects,xml sax xmlreader --- Interface for XML parsers
@anchor{library/xml sax reader id2}@anchor{380a}@anchor{library/xml sax reader locator-objects}@anchor{380b}
@subsubsection Locator Objects


Instances of @ref{37b1,,Locator} provide these methods:

@geindex getColumnNumber() (méthode xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getColumnNumber}@anchor{380c}
@deffn {Méthode} Locator.getColumnNumber ()

Return the column number where the current event begins.
@end deffn

@geindex getLineNumber() (méthode xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getLineNumber}@anchor{380d}
@deffn {Méthode} Locator.getLineNumber ()

Return the line number where the current event begins.
@end deffn

@geindex getPublicId() (méthode xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getPublicId}@anchor{380e}
@deffn {Méthode} Locator.getPublicId ()

Return the public identifier for the current event.
@end deffn

@geindex getSystemId() (méthode xml.sax.xmlreader.Locator)
@anchor{library/xml sax reader xml sax xmlreader Locator getSystemId}@anchor{380f}
@deffn {Méthode} Locator.getSystemId ()

Return the system identifier for the current event.
@end deffn

@node InputSource Objects,The Attributes Interface,Locator Objects,xml sax xmlreader --- Interface for XML parsers
@anchor{library/xml sax reader input-source-objects}@anchor{3810}@anchor{library/xml sax reader inputsource-objects}@anchor{3811}
@subsubsection InputSource Objects


@geindex setPublicId() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setPublicId}@anchor{3812}
@deffn {Méthode} InputSource.setPublicId (id)

Sets the public identifier of this @ref{e84,,InputSource}.
@end deffn

@geindex getPublicId() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getPublicId}@anchor{3813}
@deffn {Méthode} InputSource.getPublicId ()

Returns the public identifier of this @ref{e84,,InputSource}.
@end deffn

@geindex setSystemId() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setSystemId}@anchor{3814}
@deffn {Méthode} InputSource.setSystemId (id)

Sets the system identifier of this @ref{e84,,InputSource}.
@end deffn

@geindex getSystemId() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getSystemId}@anchor{3815}
@deffn {Méthode} InputSource.getSystemId ()

Returns the system identifier of this @ref{e84,,InputSource}.
@end deffn

@geindex setEncoding() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setEncoding}@anchor{3816}
@deffn {Méthode} InputSource.setEncoding (encoding)

Sets the character encoding of this @ref{e84,,InputSource}.

The encoding must be a string acceptable for an XML encoding declaration (see
section 4.3.3 of the XML recommendation).

The encoding attribute of the @ref{e84,,InputSource} is ignored if the
@ref{e84,,InputSource} also contains a character stream.
@end deffn

@geindex getEncoding() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getEncoding}@anchor{3817}
@deffn {Méthode} InputSource.getEncoding ()

Get the character encoding of this InputSource.
@end deffn

@geindex setByteStream() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setByteStream}@anchor{3818}
@deffn {Méthode} InputSource.setByteStream (bytefile)

Set the byte stream (a @ref{1c15,,binary file}) for this input source.

The SAX parser will ignore this if there is also a character stream specified,
but it will use a byte stream in preference to opening a URI connection itself.

If the application knows the character encoding of the byte stream, it should
set it with the setEncoding method.
@end deffn

@geindex getByteStream() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getByteStream}@anchor{3819}
@deffn {Méthode} InputSource.getByteStream ()

Get the byte stream for this input source.

The getEncoding method will return the character encoding for this byte stream,
or @code{None} if unknown.
@end deffn

@geindex setCharacterStream() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource setCharacterStream}@anchor{381a}
@deffn {Méthode} InputSource.setCharacterStream (charfile)

Set the character stream (a @ref{1c14,,text file}) for this input source.

If there is a character stream specified, the SAX parser will ignore any byte
stream and will not attempt to open a URI connection to the system identifier.
@end deffn

@geindex getCharacterStream() (méthode xml.sax.xmlreader.InputSource)
@anchor{library/xml sax reader xml sax xmlreader InputSource getCharacterStream}@anchor{381b}
@deffn {Méthode} InputSource.getCharacterStream ()

Get the character stream for this input source.
@end deffn

@node The Attributes Interface,The AttributesNS Interface,InputSource Objects,xml sax xmlreader --- Interface for XML parsers
@anchor{library/xml sax reader attributes-objects}@anchor{37cf}@anchor{library/xml sax reader the-attributes-interface}@anchor{381c}
@subsubsection The @code{Attributes} Interface


@code{Attributes} objects implement a portion of the @ref{1199,,mapping protocol}, including the methods @code{copy()},
@code{get()}, @ref{1ee0,,__contains__()},
@code{items()}, @code{keys()},
and @code{values()}.  The following methods
are also provided:

@geindex getLength() (méthode xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getLength}@anchor{381d}
@deffn {Méthode} Attributes.getLength ()

Return the number of attributes.
@end deffn

@geindex getNames() (méthode xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getNames}@anchor{381e}
@deffn {Méthode} Attributes.getNames ()

Return the names of the attributes.
@end deffn

@geindex getType() (méthode xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getType}@anchor{381f}
@deffn {Méthode} Attributes.getType (name)

Returns the type of the attribute `name', which is normally @code{'CDATA'}.
@end deffn

@geindex getValue() (méthode xml.sax.xmlreader.Attributes)
@anchor{library/xml sax reader xml sax xmlreader Attributes getValue}@anchor{3820}
@deffn {Méthode} Attributes.getValue (name)

Return the value of attribute `name'.
@end deffn

@c getValueByQName, getNameByQName, getQNameByName, getQNames available

@c here already, but documented only for derived class.

@node The AttributesNS Interface,,The Attributes Interface,xml sax xmlreader --- Interface for XML parsers
@anchor{library/xml sax reader attributes-ns-objects}@anchor{37d1}@anchor{library/xml sax reader the-attributesns-interface}@anchor{3821}
@subsubsection The @code{AttributesNS} Interface


This interface is a subtype of the @code{Attributes} interface (see section
@ref{37cf,,The Attributes Interface}).  All methods supported by that interface are also
available on @code{AttributesNS} objects.

The following methods are also available:

@geindex getValueByQName() (méthode xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getValueByQName}@anchor{3822}
@deffn {Méthode} AttributesNS.getValueByQName (name)

Return the value for a qualified name.
@end deffn

@geindex getNameByQName() (méthode xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getNameByQName}@anchor{3823}
@deffn {Méthode} AttributesNS.getNameByQName (name)

Return the @code{(namespace, localname)} pair for a qualified `name'.
@end deffn

@geindex getQNameByName() (méthode xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getQNameByName}@anchor{3824}
@deffn {Méthode} AttributesNS.getQNameByName (name)

Return the qualified name for a @code{(namespace, localname)} pair.
@end deffn

@geindex getQNames() (méthode xml.sax.xmlreader.AttributesNS)
@anchor{library/xml sax reader xml sax xmlreader AttributesNS getQNames}@anchor{3825}
@deffn {Méthode} AttributesNS.getQNames ()

Return the qualified names of all attributes.
@end deffn

@node xml parsers expat --- Fast XML parsing using Expat,,xml sax xmlreader --- Interface for XML parsers,Outils de traitement de balises structurées
@anchor{library/pyexpat doc}@anchor{3826}@anchor{library/pyexpat module-xml parsers expat}@anchor{125}@anchor{library/pyexpat xml-parsers-expat-fast-xml-parsing-using-expat}@anchor{3827}
@subsection @code{xml.parsers.expat} --- Fast XML parsing using Expat


@geindex module; xml.parsers.expat


__________________________________________________________________


@c Markup notes:
@c 
@c Many of the attributes of the XMLParser objects are callbacks.  Since
@c signature information must be presented, these are described using the method
@c directive.  Since they are attributes which are set by client code, in-text
@c references to these attributes should be marked using the :member: role.

@cartouche
@quotation Avertissement 
The @code{pyexpat} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data see
@ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche

@geindex Expat

The @ref{125,,xml.parsers.expat} module is a Python interface to the Expat
non-validating XML parser. The module provides a single extension type,
@code{xmlparser}, that represents the current state of an XML parser.  After
an @code{xmlparser} object has been created, various attributes of the object
can be set to handler functions.  When an XML document is then fed to the
parser, the handler functions are called for the character data and markup in
the XML document.

@geindex module;pyexpat

This module uses the @code{pyexpat} module to provide access to the Expat
parser.  Direct use of the @code{pyexpat} module is deprecated.

This module provides one exception and one type object:

@geindex ExpatError
@anchor{library/pyexpat xml parsers expat ExpatError}@anchor{1257}
@deffn {Exception} xml.parsers.expat.ExpatError

The exception raised when Expat reports an error.  See section
@ref{3828,,ExpatError Exceptions} for more information on interpreting Expat errors.
@end deffn

@geindex error
@anchor{library/pyexpat xml parsers expat error}@anchor{3829}
@deffn {Exception} xml.parsers.expat.error

Alias for @ref{1257,,ExpatError}.
@end deffn

@geindex XMLParserType (dans le module xml.parsers.expat)
@anchor{library/pyexpat xml parsers expat XMLParserType}@anchor{382a}
@deffn {Données} xml.parsers.expat.XMLParserType

The type of the return values from the @ref{382b,,ParserCreate()} function.
@end deffn

The @ref{125,,xml.parsers.expat} module contains two functions:

@geindex ErrorString() (dans le module xml.parsers.expat)
@anchor{library/pyexpat xml parsers expat ErrorString}@anchor{382c}
@deffn {Fonction} xml.parsers.expat.ErrorString (errno)

Returns an explanatory string for a given error number `errno'.
@end deffn

@geindex ParserCreate() (dans le module xml.parsers.expat)
@anchor{library/pyexpat xml parsers expat ParserCreate}@anchor{382b}
@deffn {Fonction} xml.parsers.expat.ParserCreate (encoding=None, namespace_separator=None)

Creates and returns a new @code{xmlparser} object.   `encoding', if specified,
must be a string naming the encoding  used by the XML data.  Expat doesn't
support as many encodings as Python does, and its repertoire of encodings can't
be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII.  If
`encoding' @footnote{
The encoding string included in XML output should conform to the
appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
not. See @indicateurl{https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl}
and @indicateurl{https://www.iana.org/assignments/character-sets/character-sets.xhtml}.
} is given it will override the implicit or explicit encoding of the
document.

Expat can optionally do XML namespace processing for you, enabled by providing a
value for `namespace_separator'.  The value must be a one-character string; a
@ref{1ff,,ValueError} will be raised if the string has an illegal length (@code{None}
is considered the same as omission).  When namespace processing is enabled,
element type names and attribute names that belong to a namespace will be
expanded.  The element name passed to the element handlers
@code{StartElementHandler} and @code{EndElementHandler} will be the
concatenation of the namespace URI, the namespace separator character, and the
local part of the name.  If the namespace separator is a zero byte (@code{chr(0)})
then the namespace URI and the local part will be concatenated without any
separator.

For example, if `namespace_separator' is set to a space character (@code{' '}) and
the following document is parsed:

@example
<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>
@end example

@code{StartElementHandler} will receive the following strings for each
element:

@example
http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2
@end example

Due to limitations in the @code{Expat} library used by @code{pyexpat},
the @code{xmlparser} instance returned can only be used to parse a single
XML document.  Call @code{ParserCreate} for each document to provide unique
parser instances.
@end deffn


@subsubheading Voir aussi



@table @asis

@item The Expat XML Parser@footnote{http://www.libexpat.org/}

Home page of the Expat project.
@end table


@menu
* Objets XMLParser: Objets XMLParser<2>. 
* ExpatError Exceptions:: 
* Exemple: Exemple<10>. 
* Content Model Descriptions:: 
* Expat error constants:: 

@end menu

@node Objets XMLParser<2>,ExpatError Exceptions,,xml parsers expat --- Fast XML parsing using Expat
@anchor{library/pyexpat id2}@anchor{382d}@anchor{library/pyexpat xmlparser-objects}@anchor{382e}
@subsubsection Objets `XMLParser'


@code{xmlparser} objects have the following methods:

@geindex Parse() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser Parse}@anchor{382f}
@deffn {Méthode} xmlparser.Parse (data[, isfinal])

Parses the contents of the string `data', calling the appropriate handler
functions to process the parsed data.  `isfinal' must be true on the final call
to this method; it allows the parsing of a single file in fragments,
not the submission of multiple files.
`data' can be the empty string at any time.
@end deffn

@geindex ParseFile() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ParseFile}@anchor{3830}
@deffn {Méthode} xmlparser.ParseFile (file)

Parse XML data reading from the object `file'.  `file' only needs to provide
the @code{read(nbytes)} method, returning the empty string when there's no more
data.
@end deffn

@geindex SetBase() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetBase}@anchor{3831}
@deffn {Méthode} xmlparser.SetBase (base)

Sets the base to be used for resolving relative URIs in system identifiers in
declarations.  Resolving relative identifiers is left to the application: this
value will be passed through as the `base' argument to the
@ref{3832,,ExternalEntityRefHandler()}, @ref{3833,,NotationDeclHandler()}, and
@ref{3834,,UnparsedEntityDeclHandler()} functions.
@end deffn

@geindex GetBase() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser GetBase}@anchor{3835}
@deffn {Méthode} xmlparser.GetBase ()

Returns a string containing the base set by a previous call to @ref{3831,,SetBase()},
or @code{None} if  @ref{3831,,SetBase()} hasn't been called.
@end deffn

@geindex GetInputContext() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser GetInputContext}@anchor{3836}
@deffn {Méthode} xmlparser.GetInputContext ()

Returns the input data that generated the current event as a string. The data is
in the encoding of the entity which contains the text. When called while an
event handler is not active, the return value is @code{None}.
@end deffn

@geindex ExternalEntityParserCreate() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ExternalEntityParserCreate}@anchor{3837}
@deffn {Méthode} xmlparser.ExternalEntityParserCreate (context[, encoding])

Create a "child" parser which can be used to parse an external parsed entity
referred to by content parsed by the parent parser.  The `context' parameter
should be the string passed to the @ref{3832,,ExternalEntityRefHandler()} handler
function, described below. The child parser is created with the
@ref{3838,,ordered_attributes} and @ref{3839,,specified_attributes} set to the values of
this parser.
@end deffn

@geindex SetParamEntityParsing() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetParamEntityParsing}@anchor{383a}
@deffn {Méthode} xmlparser.SetParamEntityParsing (flag)

Control parsing of parameter entities (including the external DTD subset).
Possible `flag' values are @code{XML_PARAM_ENTITY_PARSING_NEVER},
@code{XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE} and
@code{XML_PARAM_ENTITY_PARSING_ALWAYS}.  Return true if setting the flag
was successful.
@end deffn

@geindex UseForeignDTD() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser UseForeignDTD}@anchor{383b}
@deffn {Méthode} xmlparser.UseForeignDTD ([flag])

Calling this with a true value for `flag' (the default) will cause Expat to call
the @ref{3832,,ExternalEntityRefHandler} with @ref{660,,None} for all arguments to
allow an alternate DTD to be loaded.  If the document does not contain a
document type declaration, the @ref{3832,,ExternalEntityRefHandler} will still be
called, but the @ref{383c,,StartDoctypeDeclHandler} and
@ref{383d,,EndDoctypeDeclHandler} will not be called.

Passing a false value for `flag' will cancel a previous call that passed a true
value, but otherwise has no effect.

This method can only be called before the @ref{382f,,Parse()} or @ref{3830,,ParseFile()}
methods are called; calling it after either of those have been called causes
@ref{1257,,ExpatError} to be raised with the @ref{1a,,code} attribute set to
@code{errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING]}.
@end deffn

@geindex SetReparseDeferralEnabled() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser SetReparseDeferralEnabled}@anchor{26f}
@deffn {Méthode} xmlparser.SetReparseDeferralEnabled (enabled)

@cartouche
@quotation Avertissement 
Calling @code{SetReparseDeferralEnabled(False)} has security implications,
as detailed below; please make sure to understand these consequences
prior to using the @code{SetReparseDeferralEnabled} method.
@end quotation
@end cartouche

Expat 2.6.0 introduced a security mechanism called "reparse deferral"
where instead of causing denial of service through quadratic runtime
from reparsing large tokens, reparsing of unfinished tokens is now delayed
by default until a sufficient amount of input is reached.
Due to this delay, registered handlers may — depending of the sizing of
input chunks pushed to Expat — no longer be called right after pushing new
input to the parser.  Where immediate feedback and taking over responsibility
of protecting against denial of service from large tokens are both wanted,
calling @code{SetReparseDeferralEnabled(False)} disables reparse deferral
for the current Expat parser instance, temporarily or altogether.
Calling @code{SetReparseDeferralEnabled(True)} allows re-enabling reparse
deferral.

Note that @ref{26f,,SetReparseDeferralEnabled()} has been backported to some
prior releases of CPython as a security fix.  Check for availability of
@ref{26f,,SetReparseDeferralEnabled()} using @ref{4bb,,hasattr()} if used in code
running across a variety of Python versions.


Ajouté dans la version 3.13.

@end deffn

@geindex GetReparseDeferralEnabled() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser GetReparseDeferralEnabled}@anchor{26e}
@deffn {Méthode} xmlparser.GetReparseDeferralEnabled ()

Returns whether reparse deferral is currently enabled for the given
Expat parser instance.


Ajouté dans la version 3.13.

@end deffn

@code{xmlparser} objects have the following attributes:

@geindex buffer_size (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_size}@anchor{383e}
@deffn {Attribut} xmlparser.buffer_size

The size of the buffer used when @ref{1476,,buffer_text} is true.
A new buffer size can be set by assigning a new integer value
to this attribute.
When the size is changed, the buffer will be flushed.
@end deffn

@geindex buffer_text (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_text}@anchor{1476}
@deffn {Attribut} xmlparser.buffer_text

Setting this to true causes the @code{xmlparser} object to buffer textual
content returned by Expat to avoid multiple calls to the
@ref{383f,,CharacterDataHandler()} callback whenever possible.  This can improve
performance substantially since Expat normally breaks character data into chunks
at every line ending.  This attribute is false by default, and may be changed at
any time. Note that when it is false, data that does not contain newlines
may be chunked too.
@end deffn

@geindex buffer_used (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser buffer_used}@anchor{3840}
@deffn {Attribut} xmlparser.buffer_used

If @ref{1476,,buffer_text} is enabled, the number of bytes stored in the buffer.
These bytes represent UTF-8 encoded text.  This attribute has no meaningful
interpretation when @ref{1476,,buffer_text} is false.
@end deffn

@geindex ordered_attributes (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ordered_attributes}@anchor{3838}
@deffn {Attribut} xmlparser.ordered_attributes

Setting this attribute to a non-zero integer causes the attributes to be
reported as a list rather than a dictionary.  The attributes are presented in
the order found in the document text.  For each attribute, two list entries are
presented: the attribute name and the attribute value.  (Older versions of this
module also used this format.)  By default, this attribute is false; it may be
changed at any time.
@end deffn

@geindex specified_attributes (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser specified_attributes}@anchor{3839}
@deffn {Attribut} xmlparser.specified_attributes

If set to a non-zero integer, the parser will report only those attributes which
were specified in the document instance and not those which were derived from
attribute declarations.  Applications which set this need to be especially
careful to use what additional information is available from the declarations as
needed to comply with the standards for the behavior of XML processors.  By
default, this attribute is false; it may be changed at any time.
@end deffn

The following attributes contain values relating to the most recent error
encountered by an @code{xmlparser} object, and will only have correct values
once a call to @code{Parse()} or @code{ParseFile()} has raised an
@ref{1257,,xml.parsers.expat.ExpatError} exception.

@geindex ErrorByteIndex (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorByteIndex}@anchor{3841}
@deffn {Attribut} xmlparser.ErrorByteIndex

Byte index at which an error occurred.
@end deffn

@geindex ErrorCode (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorCode}@anchor{3842}
@deffn {Attribut} xmlparser.ErrorCode

Numeric code specifying the problem.  This value can be passed to the
@ref{382c,,ErrorString()} function, or compared to one of the constants defined in the
@code{errors} object.
@end deffn

@geindex ErrorColumnNumber (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorColumnNumber}@anchor{3843}
@deffn {Attribut} xmlparser.ErrorColumnNumber

Column number at which an error occurred.
@end deffn

@geindex ErrorLineNumber (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ErrorLineNumber}@anchor{3844}
@deffn {Attribut} xmlparser.ErrorLineNumber

Line number at which an error occurred.
@end deffn

The following attributes contain values relating to the current parse location
in an @code{xmlparser} object.  During a callback reporting a parse event they
indicate the location of the first of the sequence of characters that generated
the event.  When called outside of a callback, the position indicated will be
just past the last parse event (regardless of whether there was an associated
callback).

@geindex CurrentByteIndex (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentByteIndex}@anchor{3845}
@deffn {Attribut} xmlparser.CurrentByteIndex

Current byte index in the parser input.
@end deffn

@geindex CurrentColumnNumber (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentColumnNumber}@anchor{3846}
@deffn {Attribut} xmlparser.CurrentColumnNumber

Current column number in the parser input.
@end deffn

@geindex CurrentLineNumber (attribut xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CurrentLineNumber}@anchor{3847}
@deffn {Attribut} xmlparser.CurrentLineNumber

Current line number in the parser input.
@end deffn

Here is the list of handlers that can be set.  To set a handler on an
@code{xmlparser} object `o', use @code{o.handlername = func}.  `handlername' must
be taken from the following list, and `func' must be a callable object accepting
the correct number of arguments.  The arguments are all strings, unless
otherwise stated.

@geindex XmlDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser XmlDeclHandler}@anchor{3848}
@deffn {Méthode} xmlparser.XmlDeclHandler (version, encoding, standalone)

Called when the XML declaration is parsed.  The XML declaration is the
(optional) declaration of the applicable version of the XML recommendation, the
encoding of the document text, and an optional "standalone" declaration.
`version' and `encoding' will be strings, and `standalone' will be @code{1} if the
document is declared standalone, @code{0} if it is declared not to be standalone,
or @code{-1} if the standalone clause was omitted. This is only available with
Expat version 1.95.0 or newer.
@end deffn

@geindex StartDoctypeDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartDoctypeDeclHandler}@anchor{383c}
@deffn {Méthode} xmlparser.StartDoctypeDeclHandler (doctypeName, systemId, publicId, has_internal_subset)

Called when Expat begins parsing the document type declaration (@code{<!DOCTYPE
...}).  The `doctypeName' is provided exactly as presented.  The `systemId' and
`publicId' parameters give the system and public identifiers if specified, or
@code{None} if omitted.  `has_internal_subset' will be true if the document
contains and internal document declaration subset. This requires Expat version
1.2 or newer.
@end deffn

@geindex EndDoctypeDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndDoctypeDeclHandler}@anchor{383d}
@deffn {Méthode} xmlparser.EndDoctypeDeclHandler ()

Called when Expat is done parsing the document type declaration. This requires
Expat version 1.2 or newer.
@end deffn

@geindex ElementDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ElementDeclHandler}@anchor{3849}
@deffn {Méthode} xmlparser.ElementDeclHandler (name, model)

Called once for each element type declaration.  `name' is the name of the
element type, and `model' is a representation of the content model.
@end deffn

@geindex AttlistDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser AttlistDeclHandler}@anchor{384a}
@deffn {Méthode} xmlparser.AttlistDeclHandler (elname, attname, type, default, required)

Called for each declared attribute for an element type.  If an attribute list
declaration declares three attributes, this handler is called three times, once
for each attribute.  `elname' is the name of the element to which the
declaration applies and `attname' is the name of the attribute declared.  The
attribute type is a string passed as `type'; the possible values are
@code{'CDATA'}, @code{'ID'}, @code{'IDREF'}, ... `default' gives the default value for
the attribute used when the attribute is not specified by the document instance,
or @code{None} if there is no default value (@code{#IMPLIED} values).  If the
attribute is required to be given in the document instance, `required' will be
true. This requires Expat version 1.95.0 or newer.
@end deffn

@geindex StartElementHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartElementHandler}@anchor{384b}
@deffn {Méthode} xmlparser.StartElementHandler (name, attributes)

Called for the start of every element.  `name' is a string containing the
element name, and `attributes' is the element attributes. If
@ref{3838,,ordered_attributes} is true, this is a list (see
@ref{3838,,ordered_attributes} for a full description). Otherwise it's a
dictionary mapping names to values.
@end deffn

@geindex EndElementHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndElementHandler}@anchor{384c}
@deffn {Méthode} xmlparser.EndElementHandler (name)

Called for the end of every element.
@end deffn

@geindex ProcessingInstructionHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ProcessingInstructionHandler}@anchor{384d}
@deffn {Méthode} xmlparser.ProcessingInstructionHandler (target, data)

Called for every processing instruction.
@end deffn

@geindex CharacterDataHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CharacterDataHandler}@anchor{383f}
@deffn {Méthode} xmlparser.CharacterDataHandler (data)

Called for character data.  This will be called for normal character data, CDATA
marked content, and ignorable whitespace.  Applications which must distinguish
these cases can use the @ref{384e,,StartCdataSectionHandler},
@ref{384f,,EndCdataSectionHandler}, and @ref{3849,,ElementDeclHandler} callbacks to
collect the required information. Note that the character data may be
chunked even if it is short and so you may receive more than one call to
@ref{383f,,CharacterDataHandler()}. Set the @ref{1476,,buffer_text} instance attribute
to @code{True} to avoid that.
@end deffn

@geindex UnparsedEntityDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser UnparsedEntityDeclHandler}@anchor{3834}
@deffn {Méthode} xmlparser.UnparsedEntityDeclHandler (entityName, base, systemId, publicId, notationName)

Called for unparsed (NDATA) entity declarations.  This is only present for
version 1.2 of the Expat library; for more recent versions, use
@ref{3850,,EntityDeclHandler} instead.  (The underlying function in the Expat
library has been declared obsolete.)
@end deffn

@geindex EntityDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EntityDeclHandler}@anchor{3850}
@deffn {Méthode} xmlparser.EntityDeclHandler (entityName, is_parameter_entity, value, base, systemId, publicId, notationName)

Called for all entity declarations.  For parameter and internal entities,
`value' will be a string giving the declared contents of the entity; this will
be @code{None} for external entities.  The `notationName' parameter will be
@code{None} for parsed entities, and the name of the notation for unparsed
entities. `is_parameter_entity' will be true if the entity is a parameter entity
or false for general entities (most applications only need to be concerned with
general entities). This is only available starting with version 1.95.0 of the
Expat library.
@end deffn

@geindex NotationDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser NotationDeclHandler}@anchor{3833}
@deffn {Méthode} xmlparser.NotationDeclHandler (notationName, base, systemId, publicId)

Called for notation declarations.  `notationName', `base', and `systemId', and
`publicId' are strings if given.  If the public identifier is omitted,
`publicId' will be @code{None}.
@end deffn

@geindex StartNamespaceDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartNamespaceDeclHandler}@anchor{3851}
@deffn {Méthode} xmlparser.StartNamespaceDeclHandler (prefix, uri)

Called when an element contains a namespace declaration.  Namespace declarations
are processed before the @ref{384b,,StartElementHandler} is called for the element
on which declarations are placed.
@end deffn

@geindex EndNamespaceDeclHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndNamespaceDeclHandler}@anchor{3852}
@deffn {Méthode} xmlparser.EndNamespaceDeclHandler (prefix)

Called when the closing tag is reached for an element  that contained a
namespace declaration.  This is called once for each namespace declaration on
the element in the reverse of the order for which the
@ref{3851,,StartNamespaceDeclHandler} was called to indicate the start of each
namespace declaration's scope.  Calls to this handler are made after the
corresponding @ref{384c,,EndElementHandler} for the end of the element.
@end deffn

@geindex CommentHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser CommentHandler}@anchor{3853}
@deffn {Méthode} xmlparser.CommentHandler (data)

Called for comments.  `data' is the text of the comment, excluding the leading
@code{'<!-}@code{-'} and trailing @code{'-}@code{->'}.
@end deffn

@geindex StartCdataSectionHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser StartCdataSectionHandler}@anchor{384e}
@deffn {Méthode} xmlparser.StartCdataSectionHandler ()

Called at the start of a CDATA section.  This and @ref{384f,,EndCdataSectionHandler}
are needed to be able to identify the syntactical start and end for CDATA
sections.
@end deffn

@geindex EndCdataSectionHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser EndCdataSectionHandler}@anchor{384f}
@deffn {Méthode} xmlparser.EndCdataSectionHandler ()

Called at the end of a CDATA section.
@end deffn

@geindex DefaultHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser DefaultHandler}@anchor{3854}
@deffn {Méthode} xmlparser.DefaultHandler (data)

Called for any characters in the XML document for which no applicable handler
has been specified.  This means characters that are part of a construct which
could be reported, but for which no handler has been supplied.
@end deffn

@geindex DefaultHandlerExpand() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser DefaultHandlerExpand}@anchor{3855}
@deffn {Méthode} xmlparser.DefaultHandlerExpand (data)

This is the same as the @ref{3854,,DefaultHandler()},  but doesn't inhibit expansion
of internal entities. The entity reference will not be passed to the default
handler.
@end deffn

@geindex NotStandaloneHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser NotStandaloneHandler}@anchor{3856}
@deffn {Méthode} xmlparser.NotStandaloneHandler ()

Called if the XML document hasn't been declared as being a standalone document.
This happens when there is an external subset or a reference to a parameter
entity, but the XML declaration does not set standalone to @code{yes} in an XML
declaration.  If this handler returns @code{0}, then the parser will raise an
@code{XML_ERROR_NOT_STANDALONE} error.  If this handler is not set, no
exception is raised by the parser for this condition.
@end deffn

@geindex ExternalEntityRefHandler() (méthode xml.parsers.expat.xmlparser)
@anchor{library/pyexpat xml parsers expat xmlparser ExternalEntityRefHandler}@anchor{3832}
@deffn {Méthode} xmlparser.ExternalEntityRefHandler (context, base, systemId, publicId)

Called for references to external entities.  `base' is the current base, as set
by a previous call to @ref{3831,,SetBase()}.  The public and system identifiers,
`systemId' and `publicId', are strings if given; if the public identifier is not
given, `publicId' will be @code{None}.  The `context' value is opaque and should
only be used as described below.

For external entities to be parsed, this handler must be implemented. It is
responsible for creating the sub-parser using
@code{ExternalEntityParserCreate(context)}, initializing it with the appropriate
callbacks, and parsing the entity.  This handler should return an integer; if it
returns @code{0}, the parser will raise an
@code{XML_ERROR_EXTERNAL_ENTITY_HANDLING} error, otherwise parsing will
continue.

If this handler is not provided, external entities are reported by the
@ref{3854,,DefaultHandler} callback, if provided.
@end deffn

@node ExpatError Exceptions,Exemple<10>,Objets XMLParser<2>,xml parsers expat --- Fast XML parsing using Expat
@anchor{library/pyexpat expaterror-exceptions}@anchor{3857}@anchor{library/pyexpat expaterror-objects}@anchor{3828}
@subsubsection ExpatError Exceptions


@ref{1257,,ExpatError} exceptions have a number of interesting attributes:

@geindex code (attribut xml.parsers.expat.ExpatError)
@anchor{library/pyexpat xml parsers expat ExpatError code}@anchor{3858}
@deffn {Attribut} ExpatError.code

Expat's internal error number for the specific error.  The
@ref{3859,,errors.messages} dictionary maps
these error numbers to Expat's error messages.  For example:

@example
from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])
@end example

The @ref{126,,errors} module also provides error message
constants and a dictionary @ref{385a,,codes} mapping
these messages back to the error codes, see below.
@end deffn

@geindex lineno (attribut xml.parsers.expat.ExpatError)
@anchor{library/pyexpat xml parsers expat ExpatError lineno}@anchor{385b}
@deffn {Attribut} ExpatError.lineno

Line number on which the error was detected.  The first line is numbered @code{1}.
@end deffn

@geindex offset (attribut xml.parsers.expat.ExpatError)
@anchor{library/pyexpat xml parsers expat ExpatError offset}@anchor{385c}
@deffn {Attribut} ExpatError.offset

Character offset into the line where the error occurred.  The first column is
numbered @code{0}.
@end deffn

@node Exemple<10>,Content Model Descriptions,ExpatError Exceptions,xml parsers expat --- Fast XML parsing using Expat
@anchor{library/pyexpat example}@anchor{385d}@anchor{library/pyexpat expat-example}@anchor{385e}
@subsubsection Exemple


The following program defines three handlers that just print out their
arguments.

@example
import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)
@end example

The output from this program is:

@example
Start element: parent @{'id': 'top'@}
Start element: child1 @{'name': 'paul'@}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 @{'name': 'fred'@}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent
@end example

@node Content Model Descriptions,Expat error constants,Exemple<10>,xml parsers expat --- Fast XML parsing using Expat
@anchor{library/pyexpat content-model-descriptions}@anchor{385f}@anchor{library/pyexpat expat-content-models}@anchor{3860}@anchor{library/pyexpat module-xml parsers expat model}@anchor{127}
@subsubsection Content Model Descriptions


@geindex module; xml.parsers.expat.model

Content models are described using nested tuples.  Each tuple contains four
values: the type, the quantifier, the name, and a tuple of children.  Children
are simply additional content model descriptions.

The values of the first two fields are constants defined in the
@ref{127,,xml.parsers.expat.model} module.  These constants can be collected in two
groups: the model type group and the quantifier group.

The constants in the model type group are:


@deffn {Données} xml.parsers.expat.model.XML_CTYPE_ANY

The element named by the model name was declared to have a content model of
@code{ANY}.
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CTYPE_CHOICE

The named element allows a choice from a number of options; this is used for
content models such as @code{(A | B | C)}.
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CTYPE_EMPTY

Elements which are declared to be @code{EMPTY} have this model type.
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CTYPE_MIXED
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CTYPE_NAME
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CTYPE_SEQ

Models which represent a series of models which follow one after the other are
indicated with this model type.  This is used for models such as @code{(A, B, C)}.
@end deffn

The constants in the quantifier group are:


@deffn {Données} xml.parsers.expat.model.XML_CQUANT_NONE

No modifier is given, so it can appear exactly once, as for @code{A}.
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CQUANT_OPT

The model is optional: it can appear once or not at all, as for @code{A?}.
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CQUANT_PLUS

The model must occur one or more times (like @code{A+}).
@end deffn


@deffn {Données} xml.parsers.expat.model.XML_CQUANT_REP

The model must occur zero or more times, as for @code{A*}.
@end deffn

@node Expat error constants,,Content Model Descriptions,xml parsers expat --- Fast XML parsing using Expat
@anchor{library/pyexpat expat-error-constants}@anchor{3861}@anchor{library/pyexpat expat-errors}@anchor{3862}@anchor{library/pyexpat module-xml parsers expat errors}@anchor{126}
@subsubsection Expat error constants


@geindex module; xml.parsers.expat.errors

The following constants are provided in the @ref{126,,xml.parsers.expat.errors}
module.  These constants are useful in interpreting some of the attributes of
the @code{ExpatError} exception objects raised when an error has occurred.
Since for backwards compatibility reasons, the constants' value is the error
`message' and not the numeric error `code', you do this by comparing its
@ref{1a,,code} attribute with
@code{errors.codes[errors.XML_ERROR_@var{CONSTANT_NAME}]}.

The @code{errors} module has the following attributes:

@geindex codes (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors codes}@anchor{385a}
@deffn {Données} xml.parsers.expat.errors.codes

A dictionary mapping string descriptions to their error codes.


Ajouté dans la version 3.2.

@end deffn

@geindex messages (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors messages}@anchor{3859}
@deffn {Données} xml.parsers.expat.errors.messages

A dictionary mapping numeric error codes to their string descriptions.


Ajouté dans la version 3.2.

@end deffn

@geindex XML_ERROR_ASYNC_ENTITY (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ASYNC_ENTITY}@anchor{3863}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY
@end deffn

@geindex XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF}@anchor{3864}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

An entity reference in an attribute value referred to an external entity instead
of an internal entity.
@end deffn

@geindex XML_ERROR_BAD_CHAR_REF (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_BAD_CHAR_REF}@anchor{3865}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF

A character reference referred to a character which is illegal in XML (for
example, character @code{0}, or '@code{&#0;}').
@end deffn

@geindex XML_ERROR_BINARY_ENTITY_REF (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_BINARY_ENTITY_REF}@anchor{3866}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF

An entity reference referred to an entity which was declared with a notation, so
cannot be parsed.
@end deffn

@geindex XML_ERROR_DUPLICATE_ATTRIBUTE (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_DUPLICATE_ATTRIBUTE}@anchor{3867}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE

An attribute was used more than once in a start tag.
@end deffn

@geindex XML_ERROR_INCORRECT_ENCODING (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INCORRECT_ENCODING}@anchor{3868}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING
@end deffn

@geindex XML_ERROR_INVALID_TOKEN (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INVALID_TOKEN}@anchor{3869}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN

Raised when an input byte could not properly be assigned to a character; for
example, a NUL byte (value @code{0}) in a UTF-8 input stream.
@end deffn

@geindex XML_ERROR_JUNK_AFTER_DOC_ELEMENT (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_JUNK_AFTER_DOC_ELEMENT}@anchor{386a}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT

Something other than whitespace occurred after the document element.
@end deffn

@geindex XML_ERROR_MISPLACED_XML_PI (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_MISPLACED_XML_PI}@anchor{386b}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI

An XML declaration was found somewhere other than the start of the input data.
@end deffn

@geindex XML_ERROR_NO_ELEMENTS (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_ELEMENTS}@anchor{386c}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS

The document contains no elements (XML requires all documents to contain exactly
one top-level element)..
@end deffn

@geindex XML_ERROR_NO_MEMORY (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_MEMORY}@anchor{386d}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_NO_MEMORY

Expat was not able to allocate memory internally.
@end deffn

@geindex XML_ERROR_PARAM_ENTITY_REF (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PARAM_ENTITY_REF}@anchor{386e}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF

A parameter entity reference was found where it was not allowed.
@end deffn

@geindex XML_ERROR_PARTIAL_CHAR (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PARTIAL_CHAR}@anchor{386f}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR

An incomplete character was found in the input.
@end deffn

@geindex XML_ERROR_RECURSIVE_ENTITY_REF (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RECURSIVE_ENTITY_REF}@anchor{3870}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF

An entity reference contained another reference to the same entity; possibly via
a different name, and possibly indirectly.
@end deffn

@geindex XML_ERROR_SYNTAX (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SYNTAX}@anchor{3871}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_SYNTAX

Some unspecified syntax error was encountered.
@end deffn

@geindex XML_ERROR_TAG_MISMATCH (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_TAG_MISMATCH}@anchor{3872}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH

An end tag did not match the innermost open start tag.
@end deffn

@geindex XML_ERROR_UNCLOSED_TOKEN (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNCLOSED_TOKEN}@anchor{3873}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN

Some token (such as a start tag) was not closed before the end of the stream or
the next token was encountered.
@end deffn

@geindex XML_ERROR_UNDEFINED_ENTITY (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNDEFINED_ENTITY}@anchor{3874}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY

A reference was made to an entity which was not defined.
@end deffn

@geindex XML_ERROR_UNKNOWN_ENCODING (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNKNOWN_ENCODING}@anchor{3875}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING

The document encoding is not supported by Expat.
@end deffn

@geindex XML_ERROR_UNCLOSED_CDATA_SECTION (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNCLOSED_CDATA_SECTION}@anchor{3876}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION

A CDATA marked section was not closed.
@end deffn

@geindex XML_ERROR_EXTERNAL_ENTITY_HANDLING (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_EXTERNAL_ENTITY_HANDLING}@anchor{3877}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING
@end deffn

@geindex XML_ERROR_NOT_STANDALONE (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_STANDALONE}@anchor{3878}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE

The parser determined that the document was not "standalone" though it declared
itself to be in the XML declaration, and the @code{NotStandaloneHandler} was
set and returned @code{0}.
@end deffn

@geindex XML_ERROR_UNEXPECTED_STATE (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNEXPECTED_STATE}@anchor{3879}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE
@end deffn

@geindex XML_ERROR_ENTITY_DECLARED_IN_PE (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ENTITY_DECLARED_IN_PE}@anchor{387a}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE
@end deffn

@geindex XML_ERROR_FEATURE_REQUIRES_XML_DTD (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_FEATURE_REQUIRES_XML_DTD}@anchor{387b}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD

An operation was requested that requires DTD support to be compiled in, but
Expat was configured without DTD support.  This should never be reported by a
standard build of the @ref{125,,xml.parsers.expat} module.
@end deffn

@geindex XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}@anchor{387c}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

A behavioral change was requested after parsing started that can only be changed
before parsing has started.  This is (currently) only raised by
@code{UseForeignDTD()}.
@end deffn

@geindex XML_ERROR_UNBOUND_PREFIX (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNBOUND_PREFIX}@anchor{387d}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX

An undeclared prefix was found when namespace processing was enabled.
@end deffn

@geindex XML_ERROR_UNDECLARING_PREFIX (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_UNDECLARING_PREFIX}@anchor{387e}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX

The document attempted to remove the namespace declaration associated with a
prefix.
@end deffn

@geindex XML_ERROR_INCOMPLETE_PE (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INCOMPLETE_PE}@anchor{387f}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE

A parameter entity contained incomplete markup.
@end deffn

@geindex XML_ERROR_XML_DECL (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_XML_DECL}@anchor{3880}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_XML_DECL

The document contained no document element at all.
@end deffn

@geindex XML_ERROR_TEXT_DECL (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_TEXT_DECL}@anchor{3881}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_TEXT_DECL

There was an error parsing a text declaration in an external entity.
@end deffn

@geindex XML_ERROR_PUBLICID (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_PUBLICID}@anchor{3882}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_PUBLICID

Characters were found in the public id that are not allowed.
@end deffn

@geindex XML_ERROR_SUSPENDED (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SUSPENDED}@anchor{3883}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_SUSPENDED

The requested operation was made on a suspended parser, but isn't allowed.  This
includes attempts to provide additional input or to stop the parser.
@end deffn

@geindex XML_ERROR_NOT_SUSPENDED (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NOT_SUSPENDED}@anchor{3884}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED

An attempt to resume the parser was made when the parser had not been suspended.
@end deffn

@geindex XML_ERROR_ABORTED (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_ABORTED}@anchor{3885}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_ABORTED

This should not be reported to Python applications.
@end deffn

@geindex XML_ERROR_FINISHED (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_FINISHED}@anchor{3886}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_FINISHED

The requested operation was made on a parser which was finished parsing input,
but isn't allowed.  This includes attempts to provide additional input or to
stop the parser.
@end deffn

@geindex XML_ERROR_SUSPEND_PE (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_SUSPEND_PE}@anchor{3887}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE
@end deffn

@geindex XML_ERROR_RESERVED_PREFIX_XML (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_PREFIX_XML}@anchor{3888}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML

An attempt was made to
undeclare reserved namespace prefix @code{xml}
or to bind it to another namespace URI.
@end deffn

@geindex XML_ERROR_RESERVED_PREFIX_XMLNS (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_PREFIX_XMLNS}@anchor{3889}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS

An attempt was made to declare or undeclare reserved namespace prefix @code{xmlns}.
@end deffn

@geindex XML_ERROR_RESERVED_NAMESPACE_URI (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_RESERVED_NAMESPACE_URI}@anchor{388a}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI

An attempt was made to bind the URI of one the reserved namespace
prefixes @code{xml} and @code{xmlns} to another namespace prefix.
@end deffn

@geindex XML_ERROR_INVALID_ARGUMENT (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_INVALID_ARGUMENT}@anchor{388b}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT

This should not be reported to Python applications.
@end deffn

@geindex XML_ERROR_NO_BUFFER (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_NO_BUFFER}@anchor{388c}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_NO_BUFFER

This should not be reported to Python applications.
@end deffn

@geindex XML_ERROR_AMPLIFICATION_LIMIT_BREACH (dans le module xml.parsers.expat.errors)
@anchor{library/pyexpat xml parsers expat errors XML_ERROR_AMPLIFICATION_LIMIT_BREACH}@anchor{388d}
@deffn {Données} xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH

The limit on input amplification factor (from DTD and entities)
has been breached.
@end deffn

@subsubheading Notes


@node Gestion des protocoles internet,Services multimédia,Outils de traitement de balises structurées,La bibliothèque standard
@anchor{library/internet doc}@anchor{388e}@anchor{library/internet internet}@anchor{388f}@anchor{library/internet internet-protocols-and-support}@anchor{3890}
@section Gestion des protocoles internet


@geindex WWW
@geindex Internet
@geindex World Wide Web

@geindex module;socket

Les modules documentés dans ce chapitre implémentent des protocoles relatifs à Internet et à ses technologies relatives.  Ils sont tous implémentés en Python. La majorité de ces modules nécessitent la présence du module @ref{cb,,socket} lui même dépendant du système, mais fourni sur la plupart des plateformes populaires. Voici une vue d'ensemble :

@menu
* webbrowser: webbrowser --- Convenient web-browser controller. Convenient web-browser controller
* wsgiref: wsgiref --- WSGI Utilities and Reference Implementation. WSGI Utilities and Reference Implementation
* urllib: urllib --- URL handling modules. URL handling modules
* urllib.request: urllib request --- Extensible library for opening URLs. Extensible library for opening URLs
* urllib.response: urllib response --- Response classes used by urllib. Response classes used by urllib
* urllib.parse: urllib parse --- Parse URLs into components. Parse URLs into components
* urllib.error: urllib error --- Exception classes raised by urllib request. Exception classes raised by urllib.request
* urllib.robotparser: urllib robotparser --- Parser for robots txt. Parser for robots.txt
* http: http --- HTTP modules. HTTP modules
* http.client: http client --- HTTP protocol client. HTTP protocol client
* ftplib: ftplib --- FTP protocol client. FTP protocol client
* poplib: poplib --- POP3 protocol client. POP3 protocol client
* imaplib: imaplib --- IMAP4 protocol client. IMAP4 protocol client
* smtplib: smtplib --- SMTP protocol client. SMTP protocol client
* uuid: uuid --- UUID objects according to RFC 4122. UUID objects according to RFC 4122
* socketserver: socketserver --- A framework for network servers. A framework for network servers
* http.server: http server --- HTTP servers. HTTP servers
* http.cookies: http cookies --- HTTP state management. HTTP state management
* http.cookiejar: http cookiejar --- Cookie handling for HTTP clients. Cookie handling for HTTP clients
* xmlrpc: xmlrpc --- XMLRPC server and client modules. XMLRPC server and client modules
* xmlrpc.client: xmlrpc client --- XML-RPC client access. XML-RPC client access
* xmlrpc.server: xmlrpc server --- Basic XML-RPC servers. Basic XML-RPC servers
* ipaddress: ipaddress --- IPv4/IPv6 manipulation library. IPv4/IPv6 manipulation library

@end menu

@node webbrowser --- Convenient web-browser controller,wsgiref --- WSGI Utilities and Reference Implementation,,Gestion des protocoles internet
@anchor{library/webbrowser doc}@anchor{3891}@anchor{library/webbrowser module-webbrowser}@anchor{114}@anchor{library/webbrowser webbrowser-convenient-web-browser-controller}@anchor{3892}
@subsection @code{webbrowser} --- Convenient web-browser controller


@geindex module; webbrowser

`Source code:' Lib/webbrowser.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/webbrowser.py}


__________________________________________________________________


The @ref{114,,webbrowser} module provides a high-level interface to allow displaying
web-based documents to users. Under most circumstances, simply calling the
@ref{3893,,open()} function from this module will do the right thing.

Under Unix, graphical browsers are preferred under X11, but text-mode browsers
will be used if graphical browsers are not available or an X11 display isn't
available.  If text-mode browsers are used, the calling process will block until
the user exits the browser.

If the environment variable 
@geindex BROWSER
@geindex variable d'environnement; BROWSER
@code{BROWSER} exists, it is interpreted as the
@ref{1cd0,,os.pathsep}-separated list of browsers to try ahead of the platform
defaults.  When the value of a list part contains the string @code{%s}, then it is
interpreted as a literal browser command line to be used with the argument URL
substituted for @code{%s}; if the part does not contain @code{%s}, it is simply
interpreted as the name of the browser to launch. @footnote{
Executables named here without a full path will be searched in the
directories given in the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} environment variable.
}

For non-Unix platforms, or when a remote browser is available on Unix, the
controlling process will not wait for the user to finish with the browser, but
allow the remote browser to maintain its own windows on the display.  If remote
browsers are not available on Unix, the controlling process will launch a new
browser and wait.

On iOS, the 
@geindex BROWSER
@geindex variable d'environnement; BROWSER
@code{BROWSER} environment variable, as well as any arguments
controlling autoraise, browser preference, and new tab/window creation will be
ignored. Web pages will `always' be opened in the user's preferred browser, in
a new tab, with the browser being brought to the foreground. The use of the
@ref{114,,webbrowser} module on iOS requires the @ref{2a,,ctypes} module. If
@ref{2a,,ctypes} isn't available, calls to @ref{3893,,open()} will fail.

The script @code{webbrowser} can be used as a command-line interface for the
module. It accepts a URL as the argument. It accepts the following optional
parameters:


@itemize *

@item 
@code{-n}/@code{--new-window} opens the URL in a new browser window, if possible.

@item 
@code{-t}/@code{--new-tab} opens the URL in a new browser page ("tab").
@end itemize

The options are, naturally, mutually exclusive.  Usage example:

@example
python -m webbrowser -t "https://www.python.org"
@end example

@ref{1ce0,,Availability}: not WASI, not Android.

L'exception suivante est définie :

@geindex Error
@anchor{library/webbrowser webbrowser Error}@anchor{3894}
@deffn {Exception} webbrowser.Error

Exception raised when a browser control error occurs.
@end deffn

Les fonctions suivantes sont définies :

@geindex open() (dans le module webbrowser)
@anchor{library/webbrowser webbrowser open}@anchor{3893}
@deffn {Fonction} webbrowser.open (url, new=0, autoraise=True)

Display `url' using the default browser. If `new' is 0, the `url' is opened
in the same browser window if possible.  If `new' is 1, a new browser window
is opened if possible.  If `new' is 2, a new browser page ("tab") is opened
if possible.  If `autoraise' is @code{True}, the window is raised if possible
(note that under many window managers this will occur regardless of the
setting of this variable).

Returns @code{True} if a browser was successfully launched, @code{False} otherwise.

Note that on some platforms, trying to open a filename using this function,
may work and start the operating system's associated program.  However, this
is neither supported nor portable.

Raises an @ref{1848,,auditing event} @code{webbrowser.open} with argument @code{url}.
@end deffn

@geindex open_new() (dans le module webbrowser)
@anchor{library/webbrowser webbrowser open_new}@anchor{3895}
@deffn {Fonction} webbrowser.open_new (url)

Open `url' in a new window of the default browser, if possible, otherwise, open
`url' in the only browser window.

Returns @code{True} if a browser was successfully launched, @code{False} otherwise.
@end deffn

@geindex open_new_tab() (dans le module webbrowser)
@anchor{library/webbrowser webbrowser open_new_tab}@anchor{3896}
@deffn {Fonction} webbrowser.open_new_tab (url)

Open `url' in a new page ("tab") of the default browser, if possible, otherwise
equivalent to @ref{3895,,open_new()}.

Returns @code{True} if a browser was successfully launched, @code{False} otherwise.
@end deffn

@geindex get() (dans le module webbrowser)
@anchor{library/webbrowser webbrowser get}@anchor{3897}
@deffn {Fonction} webbrowser.get (using=None)

Return a controller object for the browser type `using'.  If `using' is
@code{None}, return a controller for a default browser appropriate to the
caller's environment.
@end deffn

@geindex register() (dans le module webbrowser)
@anchor{library/webbrowser webbrowser register}@anchor{3898}
@deffn {Fonction} webbrowser.register (name, constructor, instance=None, *, preferred=False)

Register the browser type `name'.  Once a browser type is registered, the
@ref{3897,,get()} function can return a controller for that browser type.  If
`instance' is not provided, or is @code{None}, `constructor' will be called without
parameters to create an instance when needed.  If `instance' is provided,
`constructor' will never be called, and may be @code{None}.

Setting `preferred' to @code{True} makes this browser a preferred result for
a @ref{3897,,get()} call with no argument.  Otherwise, this entry point is only
useful if you plan to either set the 
@geindex BROWSER
@geindex variable d'environnement; BROWSER
@code{BROWSER} variable or call
@ref{3897,,get()} with a nonempty argument matching the name of a handler you
declare.


Modifié dans la version 3.7: `preferred' keyword-only parameter was added.

@end deffn

A number of browser types are predefined.  This table gives the type names that
may be passed to the @ref{3897,,get()} function and the corresponding instantiations
for the controller classes, all defined in this module.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} 
@headitem

Type Name

@tab

Class Name

@tab

Notes

@item

@code{'mozilla'}

@tab

@code{Mozilla('mozilla')}

@tab

@item

@code{'firefox'}

@tab

@code{Mozilla('mozilla')}

@tab

@item

@code{'epiphany'}

@tab

@code{Epiphany('epiphany')}

@tab

@item

@code{'kfmclient'}

@tab

@code{Konqueror()}

@tab

(1)

@item

@code{'konqueror'}

@tab

@code{Konqueror()}

@tab

(1)

@item

@code{'kfm'}

@tab

@code{Konqueror()}

@tab

(1)

@item

@code{'opera'}

@tab

@code{Opera()}

@tab

@item

@code{'links'}

@tab

@code{GenericBrowser('links')}

@tab

@item

@code{'elinks'}

@tab

@code{Elinks('elinks')}

@tab

@item

@code{'lynx'}

@tab

@code{GenericBrowser('lynx')}

@tab

@item

@code{'w3m'}

@tab

@code{GenericBrowser('w3m')}

@tab

@item

@code{'windows-default'}

@tab

@code{WindowsDefault}

@tab

(2)

@item

@code{'macosx'}

@tab

@code{MacOSXOSAScript('default')}

@tab

(3)

@item

@code{'safari'}

@tab

@code{MacOSXOSAScript('safari')}

@tab

(3)

@item

@code{'google-chrome'}

@tab

@code{Chrome('google-chrome')}

@tab

@item

@code{'chrome'}

@tab

@code{Chrome('chrome')}

@tab

@item

@code{'chromium'}

@tab

@code{Chromium('chromium')}

@tab

@item

@code{'chromium-browser'}

@tab

@code{Chromium('chromium-browser')}

@tab

@item

@code{'iosbrowser'}

@tab

@code{IOSBrowser}

@tab

(4)

@end multitable


Notes :


@enumerate 

@item 
"Konqueror" is the file manager for the KDE desktop environment for Unix, and
only makes sense to use if KDE is running.  Some way of reliably detecting KDE
would be nice; the @code{KDEDIR} variable is not sufficient.  Note also that
the name "kfm" is used even when using the @code{konqueror} command with KDE
2 --- the implementation selects the best strategy for running Konqueror.

@item 
Only on Windows platforms.

@item 
Only on macOS.

@item 
Only on iOS.
@end enumerate


Ajouté dans la version 3.2: A new @code{MacOSXOSAScript} class has been added
and is used on Mac instead of the previous @code{MacOSX} class.
This adds support for opening browsers not currently set as the OS default.



Ajouté dans la version 3.3: Support for Chrome/Chromium has been added.



Modifié dans la version 3.12: Support for several obsolete browsers has been removed.
Removed browsers include Grail, Mosaic, Netscape, Galeon,
Skipstone, Iceape, and Firefox versions 35 and below.



Modifié dans la version 3.13: Support for iOS has been added.


Here are some simple examples:

@example
url = 'https://docs.python.org/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)
@end example

@menu
* Browser Controller Objects:: 

@end menu

@node Browser Controller Objects,,,webbrowser --- Convenient web-browser controller
@anchor{library/webbrowser browser-controller-objects}@anchor{3899}@anchor{library/webbrowser browser-controllers}@anchor{389a}
@subsubsection Browser Controller Objects


Browser controllers provide these methods which parallel three of the
module-level convenience functions:

@geindex name (attribut webbrowser.controller)
@anchor{library/webbrowser webbrowser controller name}@anchor{294}
@deffn {Attribut} controller.name

System-dependent name for the browser.
@end deffn

@geindex open() (méthode webbrowser.controller)
@anchor{library/webbrowser webbrowser controller open}@anchor{389b}
@deffn {Méthode} controller.open (url, new=0, autoraise=True)

Display `url' using the browser handled by this controller. If `new' is 1, a new
browser window is opened if possible. If `new' is 2, a new browser page ("tab")
is opened if possible.
@end deffn

@geindex open_new() (méthode webbrowser.controller)
@anchor{library/webbrowser webbrowser controller open_new}@anchor{389c}
@deffn {Méthode} controller.open_new (url)

Open `url' in a new window of the browser handled by this controller, if
possible, otherwise, open `url' in the only browser window.  Alias
@ref{3895,,open_new()}.
@end deffn

@geindex open_new_tab() (méthode webbrowser.controller)
@anchor{library/webbrowser webbrowser controller open_new_tab}@anchor{389d}
@deffn {Méthode} controller.open_new_tab (url)

Open `url' in a new page ("tab") of the browser handled by this controller, if
possible, otherwise equivalent to @ref{3895,,open_new()}.
@end deffn

@subsubheading Notes


@node wsgiref --- WSGI Utilities and Reference Implementation,urllib --- URL handling modules,webbrowser --- Convenient web-browser controller,Gestion des protocoles internet
@anchor{library/wsgiref doc}@anchor{389e}@anchor{library/wsgiref module-wsgiref}@anchor{117}@anchor{library/wsgiref wsgiref-wsgi-utilities-and-reference-implementation}@anchor{389f}
@subsection @code{wsgiref} --- WSGI Utilities and Reference Implementation


@geindex module; wsgiref

`Source code:' Lib/wsgiref@footnote{https://github.com/python/cpython/tree/3.13/Lib/wsgiref}


__________________________________________________________________


WSGI (`Web Server Gateway Interface') est une interface standard entre le serveur web et une application web écrite en Python. Avoir une interface standardisée permet de faciliter l'usage de ces applications avec un certain nombre de serveurs web différents.

Seules les personnes programmant des serveurs web et des cadriciels ont besoin de connaître les détails d'implémentation et les cas particuliers de l'architecture de WSGI. En tant qu'utilisateur WSGI vous avez uniquement besoin d'installer WSGI ou d'utiliser un cadriciel existant.

@ref{117,,wsgiref} is a reference implementation of the WSGI specification that can
be used to add WSGI support to a web server or framework.  It provides utilities
for manipulating WSGI environment variables and response headers, base classes
for implementing WSGI servers, a demo HTTP server that serves WSGI applications,
types for static type checking,
and a validation tool that checks WSGI servers and applications for conformance
to the WSGI specification (
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}).

Voir wsgi.readthedocs.io@footnote{https://wsgi.readthedocs.io/} pour plus d'informations à propos de WSGI ainsi que des liens vers des tutoriels et d'autres ressources.

@c XXX If you're just trying to write a web application...

@menu
* wsgiref.util — outils pour les environnements WSGI: wsgiref util — outils pour les environnements WSGI. 
* wsgiref.headers: wsgiref headers -- WSGI response header tools. WSGI response header tools
* wsgiref.simple_server: wsgiref simple_server -- a simple WSGI HTTP server. a simple WSGI HTTP server
* wsgiref.validate: wsgiref validate --- WSGI conformance checker. WSGI conformance checker
* wsgiref.handlers: wsgiref handlers -- server/gateway base classes. server/gateway base classes
* wsgiref.types: wsgiref types -- WSGI types for static type checking. WSGI types for static type checking
* Exemples: Exemples<24>. 

@end menu

@node wsgiref util — outils pour les environnements WSGI,wsgiref headers -- WSGI response header tools,,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref util}@anchor{11c}@anchor{library/wsgiref wsgiref-util-wsgi-environment-utilities}@anchor{38a0}
@subsubsection @code{wsgiref.util} — outils pour les environnements WSGI


@geindex module; wsgiref.util

This module provides a variety of utility functions for working with WSGI
environments.  A WSGI environment is a dictionary containing HTTP request
variables as described in 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.  All of the functions taking an `environ'
parameter expect a WSGI-compliant dictionary to be supplied; please see
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} for a detailed specification and
@ref{38a1,,WSGIEnvironment} for a type alias that can be used
in type annotations.

@geindex guess_scheme() (dans le module wsgiref.util)
@anchor{library/wsgiref wsgiref util guess_scheme}@anchor{38a2}
@deffn {Fonction} wsgiref.util.guess_scheme (environ)

Tente de déterminer s'il faut assigner "http" ou "https" à @code{wsgi.url_sheme}, en vérifiant si une variable d'environnement @code{HTTPS} est dans le dictionnaire `environ'. La valeur renvoyée est une chaîne de caractères.

This function is useful when creating a gateway that wraps CGI or a CGI-like
protocol such as FastCGI.  Typically, servers providing such protocols will
include a @code{HTTPS} variable with a value of "1", "yes", or "on" when a request
is received via SSL.  So, this function returns "https" if such a value is
found, and "http" otherwise.
@end deffn

@geindex request_uri() (dans le module wsgiref.util)
@anchor{library/wsgiref wsgiref util request_uri}@anchor{38a3}
@deffn {Fonction} wsgiref.util.request_uri (environ, include_query=True)

Return the full request URI, optionally including the query string, using the
algorithm found in the "URL Reconstruction" section of 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.  If
`include_query' is false, the query string is not included in the resulting URI.
@end deffn

@geindex application_uri() (dans le module wsgiref.util)
@anchor{library/wsgiref wsgiref util application_uri}@anchor{38a4}
@deffn {Fonction} wsgiref.util.application_uri (environ)

Similar to @ref{38a3,,request_uri()}, except that the @code{PATH_INFO} and
@code{QUERY_STRING} variables are ignored.  The result is the base URI of the
application object addressed by the request.
@end deffn

@geindex shift_path_info() (dans le module wsgiref.util)
@anchor{library/wsgiref wsgiref util shift_path_info}@anchor{38a5}
@deffn {Fonction} wsgiref.util.shift_path_info (environ)

Shift a single name from @code{PATH_INFO} to @code{SCRIPT_NAME} and return the name.
The `environ' dictionary is `modified' in-place; use a copy if you need to keep
the original @code{PATH_INFO} or @code{SCRIPT_NAME} intact.

If there are no remaining path segments in @code{PATH_INFO}, @code{None} is returned.

Typically, this routine is used to process each portion of a request URI path,
for example to treat the path as a series of dictionary keys. This routine
modifies the passed-in environment to make it suitable for invoking another WSGI
application that is located at the target URI. For example, if there is a WSGI
application at @code{/foo}, and the request URI path is @code{/foo/bar/baz}, and the
WSGI application at @code{/foo} calls @ref{38a5,,shift_path_info()}, it will receive the
string "bar", and the environment will be updated to be suitable for passing to
a WSGI application at @code{/foo/bar}.  That is, @code{SCRIPT_NAME} will change from
@code{/foo} to @code{/foo/bar}, and @code{PATH_INFO} will change from @code{/bar/baz} to
@code{/baz}.

When @code{PATH_INFO} is just a "/", this routine returns an empty string and
appends a trailing slash to @code{SCRIPT_NAME}, even though empty path segments are
normally ignored, and @code{SCRIPT_NAME} doesn't normally end in a slash.  This is
intentional behavior, to ensure that an application can tell the difference
between URIs ending in @code{/x} from ones ending in @code{/x/} when using this
routine to do object traversal.
@end deffn

@geindex setup_testing_defaults() (dans le module wsgiref.util)
@anchor{library/wsgiref wsgiref util setup_testing_defaults}@anchor{38a6}
@deffn {Fonction} wsgiref.util.setup_testing_defaults (environ)

Met à jour `environ' avec des valeurs par défaut pour des cas de tests.

Cette fonction ajoute des paramètres requis pour WSGI, en particulier @code{HTTP_HOST}, @code{SERVER_NAME}, @code{SERVER_PORT}, @code{REQUEST_METHOD}, @code{SCRIPT_NAME}, @code{PATH_INFO} et toutes les autres variables WSGI définies dans la 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}. Elle ne fournit que des valeurs par défaut sans toucher aux valeurs déjà définies de ces variables.

Cette fonction a pour but de faciliter les tests unitaires des serveurs et des applications WSGI dans des environnements factices. Elle ne devrait pas être utilisée dans une application ou un serveur WSGI, étant donné que les données sont factices !

Exemple d'utilisation :

@example
from wsgiref.util import setup_testing_defaults
from wsgiref.simple_server import make_server

# A relatively simple WSGI application. It's going to print out the
# environment dictionary after being updated by setup_testing_defaults
def simple_app(environ, start_response):
    setup_testing_defaults(environ)

    status = '200 OK'
    headers = [('Content-type', 'text/plain; charset=utf-8')]

    start_response(status, headers)

    ret = [("%s: %s\n" % (key, value)).encode("utf-8")
           for key, value in environ.items()]
    return ret

with make_server('@w{'}, 8000, simple_app) as httpd:
    print("Serving on port 8000...")
    httpd.serve_forever()
@end example
@end deffn

In addition to the environment functions above, the @ref{11c,,wsgiref.util} module
also provides these miscellaneous utilities:

@geindex is_hop_by_hop() (dans le module wsgiref.util)
@anchor{library/wsgiref wsgiref util is_hop_by_hop}@anchor{164e}
@deffn {Fonction} wsgiref.util.is_hop_by_hop (header_name)

Return @code{True} if 'header_name' is an HTTP/1.1 "Hop-by-Hop" header, as defined by
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}.
@end deffn

@geindex FileWrapper (classe dans wsgiref.util)
@anchor{library/wsgiref wsgiref util FileWrapper}@anchor{720}
@deffn {Classe} wsgiref.util.FileWrapper (filelike, blksize=8192)

A concrete implementation of the @ref{38a7,,wsgiref.types.FileWrapper}
protocol used to convert a file-like object to an @ref{1aa,,iterator}.
The resulting objects
are @ref{1205,,iterable}s. As the object is iterated over, the
optional `blksize' parameter will be repeatedly passed to the `filelike'
object's @code{read()} method to obtain bytestrings to yield.  When @code{read()}
returns an empty bytestring, iteration is ended and is not resumable.

If `filelike' has a @code{close()} method, the returned object will also have a
@code{close()} method, and it will invoke the `filelike' object's @code{close()}
method when called.

Exemple d'utilisation :

@example
from io import StringIO
from wsgiref.util import FileWrapper

# We're using a StringIO-buffer for as the file-like object
filelike = StringIO("This is an example file-like object"*10)
wrapper = FileWrapper(filelike, blksize=5)

for chunk in wrapper:
    print(chunk)
@end example


Modifié dans la version 3.11: Support for @ref{280,,__getitem__()} method has been removed.

@end deffn

@node wsgiref headers -- WSGI response header tools,wsgiref simple_server -- a simple WSGI HTTP server,wsgiref util — outils pour les environnements WSGI,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref headers}@anchor{119}@anchor{library/wsgiref wsgiref-headers-wsgi-response-header-tools}@anchor{38a8}
@subsubsection @code{wsgiref.headers} -- WSGI response header tools


@geindex module; wsgiref.headers

This module provides a single class, @ref{e81,,Headers}, for convenient
manipulation of WSGI response headers using a mapping-like interface.

@geindex Headers (classe dans wsgiref.headers)
@anchor{library/wsgiref wsgiref headers Headers}@anchor{e81}
@deffn {Classe} wsgiref.headers.Headers ([headers])

Create a mapping-like object wrapping `headers', which must be a list of header
name/value tuples as described in 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}. The default value of `headers' is
an empty list.

@ref{e81,,Headers} objects support typical mapping operations including
@ref{280,,__getitem__()}, @ref{21cb,,get()}, @ref{12a9,,__setitem__()},
@ref{1062,,setdefault()},
@ref{12aa,,__delitem__()} and @ref{1ee0,,__contains__()}.  For each of
these methods, the key is the header name (treated case-insensitively), and the
value is the first value associated with that header name.  Setting a header
deletes any existing values for that header, then adds a new value at the end of
the wrapped header list.  Headers' existing order is generally maintained, with
new headers added to the end of the wrapped list.

Unlike a dictionary, @ref{e81,,Headers} objects do not raise an error when you try
to get or delete a key that isn't in the wrapped header list. Getting a
nonexistent header just returns @code{None}, and deleting a nonexistent header does
nothing.

@ref{e81,,Headers} objects also support @code{keys()}, @code{values()}, and
@code{items()} methods.  The lists returned by @code{keys()} and @code{items()} can
include the same key more than once if there is a multi-valued header.  The
@code{len()} of a @ref{e81,,Headers} object is the same as the length of its
@code{items()}, which is the same as the length of the wrapped header list.  In
fact, the @code{items()} method just returns a copy of the wrapped header list.

Calling @code{bytes()} on a @ref{e81,,Headers} object returns a formatted bytestring
suitable for transmission as HTTP response headers.  Each header is placed on a
line with its value, separated by a colon and a space. Each line is terminated
by a carriage return and line feed, and the bytestring is terminated with a
blank line.

In addition to their mapping interface and formatting features, @ref{e81,,Headers}
objects also have the following methods for querying and adding multi-valued
headers, and for adding headers with MIME parameters:

@geindex get_all() (méthode wsgiref.headers.Headers)
@anchor{library/wsgiref wsgiref headers Headers get_all}@anchor{38a9}
@deffn {Méthode} get_all (name)

Renvoie une liste de toutes les valeurs pour l'en-tête `name'.

The returned list will be sorted in the order they appeared in the original
header list or were added to this instance, and may contain duplicates.  Any
fields deleted and re-inserted are always appended to the header list.  If no
fields exist with the given name, returns an empty list.
@end deffn

@geindex add_header() (méthode wsgiref.headers.Headers)
@anchor{library/wsgiref wsgiref headers Headers add_header}@anchor{38aa}
@deffn {Méthode} add_header (name, value, **_params)

Add a (possibly multi-valued) header, with optional MIME parameters specified
via keyword arguments.

`name' is the header field to add.  Keyword arguments can be used to set MIME
parameters for the header field.  Each parameter must be a string or @code{None}.
Underscores in parameter names are converted to dashes, since dashes are illegal
in Python identifiers, but many MIME parameter names include dashes.  If the
parameter value is a string, it is added to the header value parameters in the
form @code{name="value"}. If it is @code{None}, only the parameter name is added.
(This is used for MIME parameters without a value.)  Example usage:

@example
h.add_header('content-disposition', 'attachment', filename='bud.gif')
@end example

Le code ci-dessus ajoute un en-tête qui ressemble à ceci :

@example
Content-Disposition: attachment; filename="bud.gif"
@end example
@end deffn


Modifié dans la version 3.5: Le paramètre `headers' est optionnel.

@end deffn

@node wsgiref simple_server -- a simple WSGI HTTP server,wsgiref validate --- WSGI conformance checker,wsgiref headers -- WSGI response header tools,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref simple_server}@anchor{11a}@anchor{library/wsgiref wsgiref-simple-server-a-simple-wsgi-http-server}@anchor{38ab}
@subsubsection @code{wsgiref.simple_server} -- a simple WSGI HTTP server


@geindex module; wsgiref.simple_server

This module implements a simple HTTP server (based on @ref{71,,http.server})
that serves WSGI applications.  Each server instance serves a single WSGI
application on a given host and port.  If you want to serve multiple
applications on a single host and port, you should create a WSGI application
that parses @code{PATH_INFO} to select which application to invoke for each
request.  (E.g., using the @code{shift_path_info()} function from
@ref{11c,,wsgiref.util}.)

@geindex make_server() (dans le module wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server make_server}@anchor{38ac}
@deffn {Fonction} wsgiref.simple_server.make_server (host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)

Create a new WSGI server listening on `host' and `port', accepting connections
for `app'.  The return value is an instance of the supplied `server_class', and
will process requests using the specified `handler_class'.  `app' must be a WSGI
application object, as defined by 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.

Exemple d'utilisation :

@example
from wsgiref.simple_server import make_server, demo_app

with make_server('@w{'}, 8000, demo_app) as httpd:
    print("Serving HTTP on port 8000...")

    # Respond to requests until process is killed
    httpd.serve_forever()

    # Alternative: serve one request, then exit
    httpd.handle_request()
@end example
@end deffn

@geindex demo_app() (dans le module wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server demo_app}@anchor{38ad}
@deffn {Fonction} wsgiref.simple_server.demo_app (environ, start_response)

This function is a small but complete WSGI application that returns a text page
containing the message "Hello world!" and a list of the key/value pairs provided
in the `environ' parameter.  It's useful for verifying that a WSGI server (such
as @ref{11a,,wsgiref.simple_server}) is able to run a simple WSGI application
correctly.
@end deffn

@geindex WSGIServer (classe dans wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server WSGIServer}@anchor{38ae}
@deffn {Classe} wsgiref.simple_server.WSGIServer (server_address, RequestHandlerClass)

Create a @ref{38ae,,WSGIServer} instance.  `server_address' should be a
@code{(host,port)} tuple, and `RequestHandlerClass' should be the subclass of
@ref{10ad,,http.server.BaseHTTPRequestHandler} that will be used to process
requests.

You do not normally need to call this constructor, as the @ref{38ac,,make_server()}
function can handle all the details for you.

@ref{38ae,,WSGIServer} is a subclass of @ref{38af,,http.server.HTTPServer}, so all
of its methods (such as @code{serve_forever()} and @code{handle_request()}) are
available. @ref{38ae,,WSGIServer} also provides these WSGI-specific methods:

@geindex set_app() (méthode wsgiref.simple_server.WSGIServer)
@anchor{library/wsgiref wsgiref simple_server WSGIServer set_app}@anchor{38b0}
@deffn {Méthode} set_app (application)

Sets the callable `application' as the WSGI application that will receive
requests.
@end deffn

@geindex get_app() (méthode wsgiref.simple_server.WSGIServer)
@anchor{library/wsgiref wsgiref simple_server WSGIServer get_app}@anchor{38b1}
@deffn {Méthode} get_app ()

Returns the currently set application callable.
@end deffn

Normally, however, you do not need to use these additional methods, as
@ref{38b0,,set_app()} is normally called by @ref{38ac,,make_server()}, and the
@ref{38b1,,get_app()} exists mainly for the benefit of request handler instances.
@end deffn

@geindex WSGIRequestHandler (classe dans wsgiref.simple_server)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler}@anchor{38b2}
@deffn {Classe} wsgiref.simple_server.WSGIRequestHandler (request, client_address, server)

Create an HTTP handler for the given `request' (i.e. a socket), `client_address'
(a @code{(host,port)} tuple), and `server' (@ref{38ae,,WSGIServer} instance).

You do not need to create instances of this class directly; they are
automatically created as needed by @ref{38ae,,WSGIServer} objects.  You can,
however, subclass this class and supply it as a `handler_class' to the
@ref{38ac,,make_server()} function.  Some possibly relevant methods for overriding in
subclasses:

@geindex get_environ() (méthode wsgiref.simple_server.WSGIRequestHandler)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler get_environ}@anchor{38b3}
@deffn {Méthode} get_environ ()

Return a @ref{38a1,,WSGIEnvironment} dictionary for a
request.  The default
implementation copies the contents of the @ref{38ae,,WSGIServer} object's
@code{base_environ} dictionary attribute and then adds various headers derived
from the HTTP request.  Each call to this method should return a new dictionary
containing all of the relevant CGI environment variables as specified in
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.
@end deffn

@geindex get_stderr() (méthode wsgiref.simple_server.WSGIRequestHandler)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler get_stderr}@anchor{38b4}
@deffn {Méthode} get_stderr ()

Return the object that should be used as the @code{wsgi.errors} stream. The default
implementation just returns @code{sys.stderr}.
@end deffn

@geindex handle() (méthode wsgiref.simple_server.WSGIRequestHandler)
@anchor{library/wsgiref wsgiref simple_server WSGIRequestHandler handle}@anchor{38b5}
@deffn {Méthode} handle ()

Process the HTTP request.  The default implementation creates a handler instance
using a @ref{118,,wsgiref.handlers} class to implement the actual WSGI application
interface.
@end deffn
@end deffn

@node wsgiref validate --- WSGI conformance checker,wsgiref handlers -- server/gateway base classes,wsgiref simple_server -- a simple WSGI HTTP server,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref validate}@anchor{11d}@anchor{library/wsgiref wsgiref-validate-wsgi-conformance-checker}@anchor{38b6}
@subsubsection @code{wsgiref.validate} --- WSGI conformance checker


@geindex module; wsgiref.validate

When creating new WSGI application objects, frameworks, servers, or middleware,
it can be useful to validate the new code's conformance using
@ref{11d,,wsgiref.validate}.  This module provides a function that creates WSGI
application objects that validate communications between a WSGI server or
gateway and a WSGI application object, to check both sides for protocol
conformance.

Note that this utility does not guarantee complete 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} compliance; an
absence of errors from this module does not necessarily mean that errors do not
exist.  However, if this module does produce an error, then it is virtually
certain that either the server or application is not 100% compliant.

This module is based on the @code{paste.lint} module from Ian Bicking's "Python
Paste" library.

@geindex validator() (dans le module wsgiref.validate)
@anchor{library/wsgiref wsgiref validate validator}@anchor{38b7}
@deffn {Fonction} wsgiref.validate.validator (application)

Wrap `application' and return a new WSGI application object.  The returned
application will forward all requests to the original `application', and will
check that both the `application' and the server invoking it are conforming to
the WSGI specification and to 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}.

Any detected nonconformance results in an @ref{694,,AssertionError} being raised;
note, however, that how these errors are handled is server-dependent.  For
example, @ref{11a,,wsgiref.simple_server} and other servers based on
@ref{118,,wsgiref.handlers} (that don't override the error handling methods to do
something else) will simply output a message that an error has occurred, and
dump the traceback to @code{sys.stderr} or some other error stream.

This wrapper may also generate output using the @ref{111,,warnings} module to
indicate behaviors that are questionable but which may not actually be
prohibited by 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.  Unless they are suppressed using Python command-line
options or the @ref{111,,warnings} API, any such warnings will be written to
@code{sys.stderr} (`not' @code{wsgi.errors}, unless they happen to be the same
object).

Exemple d'utilisation :

@example
from wsgiref.validate import validator
from wsgiref.simple_server import make_server

# Our callable object which is intentionally not compliant to the
# standard, so the validator is going to break
def simple_app(environ, start_response):
    status = '200 OK'  # HTTP Status
    headers = [('Content-type', 'text/plain')]  # HTTP Headers
    start_response(status, headers)

    # This is going to break because we need to return a list, and
    # the validator is going to inform us
    return b"Hello World"

# This is the application wrapped in a validator
validator_app = validator(simple_app)

with make_server('@w{'}, 8000, validator_app) as httpd:
    print("Listening on port 8000....")
    httpd.serve_forever()
@end example
@end deffn

@node wsgiref handlers -- server/gateway base classes,wsgiref types -- WSGI types for static type checking,wsgiref validate --- WSGI conformance checker,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref handlers}@anchor{118}@anchor{library/wsgiref wsgiref-handlers-server-gateway-base-classes}@anchor{38b8}
@subsubsection @code{wsgiref.handlers} -- server/gateway base classes


@geindex module; wsgiref.handlers

This module provides base handler classes for implementing WSGI servers and
gateways.  These base classes handle most of the work of communicating with a
WSGI application, as long as they are given a CGI-like environment, along with
input, output, and error streams.

@geindex CGIHandler (classe dans wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers CGIHandler}@anchor{38b9}
@deffn {Classe} wsgiref.handlers.CGIHandler

CGI-based invocation via @code{sys.stdin}, @code{sys.stdout}, @code{sys.stderr} and
@code{os.environ}.  This is useful when you have a WSGI application and want to run
it as a CGI script.  Simply invoke @code{CGIHandler().run(app)}, where @code{app} is
the WSGI application object you wish to invoke.

This class is a subclass of @ref{38ba,,BaseCGIHandler} that sets @code{wsgi.run_once}
to true, @code{wsgi.multithread} to false, and @code{wsgi.multiprocess} to true, and
always uses @ref{d8,,sys} and @ref{a0,,os} to obtain the necessary CGI streams and
environment.
@end deffn

@geindex IISCGIHandler (classe dans wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers IISCGIHandler}@anchor{38bb}
@deffn {Classe} wsgiref.handlers.IISCGIHandler

A specialized alternative to @ref{38b9,,CGIHandler}, for use when deploying on
Microsoft's IIS web server, without having set the config allowPathInfo
option (IIS>=7) or metabase allowPathInfoForScriptMappings (IIS<7).

By default, IIS gives a @code{PATH_INFO} that duplicates the @code{SCRIPT_NAME} at
the front, causing problems for WSGI applications that wish to implement
routing. This handler strips any such duplicated path.

IIS can be configured to pass the correct @code{PATH_INFO}, but this causes
another bug where @code{PATH_TRANSLATED} is wrong. Luckily this variable is
rarely used and is not guaranteed by WSGI. On IIS<7, though, the
setting can only be made on a vhost level, affecting all other script
mappings, many of which break when exposed to the @code{PATH_TRANSLATED} bug.
For this reason IIS<7 is almost never deployed with the fix (Even IIS7
rarely uses it because there is still no UI for it.).

There is no way for CGI code to tell whether the option was set, so a
separate handler class is provided.  It is used in the same way as
@ref{38b9,,CGIHandler}, i.e., by calling @code{IISCGIHandler().run(app)}, where
@code{app} is the WSGI application object you wish to invoke.


Ajouté dans la version 3.2.

@end deffn

@geindex BaseCGIHandler (classe dans wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers BaseCGIHandler}@anchor{38ba}
@deffn {Classe} wsgiref.handlers.BaseCGIHandler (stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

Similar to @ref{38b9,,CGIHandler}, but instead of using the @ref{d8,,sys} and
@ref{a0,,os} modules, the CGI environment and I/O streams are specified explicitly.
The `multithread' and `multiprocess' values are used to set the
@code{wsgi.multithread} and @code{wsgi.multiprocess} flags for any applications run by
the handler instance.

This class is a subclass of @ref{38bc,,SimpleHandler} intended for use with
software other than HTTP "origin servers".  If you are writing a gateway
protocol implementation (such as CGI, FastCGI, SCGI, etc.) that uses a
@code{Status:} header to send an HTTP status, you probably want to subclass this
instead of @ref{38bc,,SimpleHandler}.
@end deffn

@geindex SimpleHandler (classe dans wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers SimpleHandler}@anchor{38bc}
@deffn {Classe} wsgiref.handlers.SimpleHandler (stdin, stdout, stderr, environ, multithread=True, multiprocess=False)

Similar to @ref{38ba,,BaseCGIHandler}, but designed for use with HTTP origin
servers.  If you are writing an HTTP server implementation, you will probably
want to subclass this instead of @ref{38ba,,BaseCGIHandler}.

This class is a subclass of @ref{197e,,BaseHandler}.  It overrides the
@code{__init__()}, @ref{38bd,,get_stdin()},
@ref{38be,,get_stderr()}, @ref{38bf,,add_cgi_vars()},
@ref{38c0,,_write()}, and @ref{38c1,,_flush()} methods to
support explicitly setting the
environment and streams via the constructor.  The supplied environment and
streams are stored in the @code{stdin}, @code{stdout}, @code{stderr}, and
@code{environ} attributes.

The @ref{cc9,,write()} method of `stdout' should write
each chunk in full, like @ref{67f,,io.BufferedIOBase}.
@end deffn

@geindex BaseHandler (classe dans wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers BaseHandler}@anchor{197e}
@deffn {Classe} wsgiref.handlers.BaseHandler

This is an abstract base class for running WSGI applications.  Each instance
will handle a single HTTP request, although in principle you could create a
subclass that was reusable for multiple requests.

@ref{197e,,BaseHandler} instances have only one method intended for external use:

@geindex run() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler run}@anchor{38c2}
@deffn {Méthode} run (app)

Run the specified WSGI application, `app'.
@end deffn

All of the other @ref{197e,,BaseHandler} methods are invoked by this method in the
process of running the application, and thus exist primarily to allow
customizing the process.

The following methods MUST be overridden in a subclass:

@geindex _write() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler _write}@anchor{38c0}
@deffn {Méthode} _write (data)

Buffer the bytes `data' for transmission to the client.  It's okay if this
method actually transmits the data; @ref{197e,,BaseHandler} just separates write
and flush operations for greater efficiency when the underlying system actually
has such a distinction.
@end deffn

@geindex _flush() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler _flush}@anchor{38c1}
@deffn {Méthode} _flush ()

Force buffered data to be transmitted to the client.  It's okay if this method
is a no-op (i.e., if @ref{38c0,,_write()} actually sends the data).
@end deffn

@geindex get_stdin() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_stdin}@anchor{38bd}
@deffn {Méthode} get_stdin ()

Return an object compatible with @ref{38c3,,InputStream}
suitable for use as the @code{wsgi.input} of the
request currently being processed.
@end deffn

@geindex get_stderr() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_stderr}@anchor{38be}
@deffn {Méthode} get_stderr ()

Return an object compatible with @ref{38c4,,ErrorStream}
suitable for use as the @code{wsgi.errors} of the
request currently being processed.
@end deffn

@geindex add_cgi_vars() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler add_cgi_vars}@anchor{38bf}
@deffn {Méthode} add_cgi_vars ()

Insert CGI variables for the current request into the @code{environ} attribute.
@end deffn

Here are some other methods and attributes you may wish to override. This list
is only a summary, however, and does not include every method that can be
overridden.  You should consult the docstrings and source code for additional
information before attempting to create a customized @ref{197e,,BaseHandler}
subclass.

Attributes and methods for customizing the WSGI environment:

@geindex wsgi_multithread (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_multithread}@anchor{38c5}
@deffn {Attribut} wsgi_multithread

The value to be used for the @code{wsgi.multithread} environment variable.  It
defaults to true in @ref{197e,,BaseHandler}, but may have a different default (or
be set by the constructor) in the other subclasses.
@end deffn

@geindex wsgi_multiprocess (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_multiprocess}@anchor{38c6}
@deffn {Attribut} wsgi_multiprocess

The value to be used for the @code{wsgi.multiprocess} environment variable.  It
defaults to true in @ref{197e,,BaseHandler}, but may have a different default (or
be set by the constructor) in the other subclasses.
@end deffn

@geindex wsgi_run_once (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_run_once}@anchor{38c7}
@deffn {Attribut} wsgi_run_once

The value to be used for the @code{wsgi.run_once} environment variable.  It
defaults to false in @ref{197e,,BaseHandler}, but @ref{38b9,,CGIHandler} sets it to
true by default.
@end deffn

@geindex os_environ (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler os_environ}@anchor{38c8}
@deffn {Attribut} os_environ

The default environment variables to be included in every request's WSGI
environment.  By default, this is a copy of @code{os.environ} at the time that
@ref{118,,wsgiref.handlers} was imported, but subclasses can either create their own
at the class or instance level.  Note that the dictionary should be considered
read-only, since the default value is shared between multiple classes and
instances.
@end deffn

@geindex server_software (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler server_software}@anchor{38c9}
@deffn {Attribut} server_software

If the @ref{38ca,,origin_server} attribute is set, this attribute's value is used to
set the default @code{SERVER_SOFTWARE} WSGI environment variable, and also to set a
default @code{Server:} header in HTTP responses.  It is ignored for handlers (such
as @ref{38ba,,BaseCGIHandler} and @ref{38b9,,CGIHandler}) that are not HTTP origin
servers.


Modifié dans la version 3.3: The term "Python" is replaced with implementation specific term like
"CPython", "Jython" etc.

@end deffn

@geindex get_scheme() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler get_scheme}@anchor{38cb}
@deffn {Méthode} get_scheme ()

Return the URL scheme being used for the current request.  The default
implementation uses the @code{guess_scheme()} function from @ref{11c,,wsgiref.util}
to guess whether the scheme should be "http" or "https", based on the current
request's @code{environ} variables.
@end deffn

@geindex setup_environ() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler setup_environ}@anchor{38cc}
@deffn {Méthode} setup_environ ()

Set the @code{environ} attribute to a fully populated WSGI environment.  The
default implementation uses all of the above methods and attributes, plus the
@ref{38bd,,get_stdin()}, @ref{38be,,get_stderr()}, and @ref{38bf,,add_cgi_vars()} methods and the
@ref{38cd,,wsgi_file_wrapper} attribute.  It also inserts a @code{SERVER_SOFTWARE} key
if not present, as long as the @ref{38ca,,origin_server} attribute is a true value
and the @ref{38c9,,server_software} attribute is set.
@end deffn

Methods and attributes for customizing exception handling:

@geindex log_exception() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler log_exception}@anchor{38ce}
@deffn {Méthode} log_exception (exc_info)

Log the `exc_info' tuple in the server log.  `exc_info' is a @code{(type, value,
traceback)} tuple.  The default implementation simply writes the traceback to
the request's @code{wsgi.errors} stream and flushes it.  Subclasses can override
this method to change the format or retarget the output, mail the traceback to
an administrator, or whatever other action may be deemed suitable.
@end deffn

@geindex traceback_limit (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler traceback_limit}@anchor{38cf}
@deffn {Attribut} traceback_limit

The maximum number of frames to include in tracebacks output by the default
@ref{38ce,,log_exception()} method.  If @code{None}, all frames are included.
@end deffn

@geindex error_output() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_output}@anchor{38d0}
@deffn {Méthode} error_output (environ, start_response)

This method is a WSGI application to generate an error page for the user.  It is
only invoked if an error occurs before headers are sent to the client.

This method can access the current error using @code{sys.exception()},
and should pass that information to `start_response' when calling it (as
described in the "Error Handling" section of 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}).

The default implementation just uses the @ref{38d1,,error_status},
@ref{38d2,,error_headers}, and @ref{38d3,,error_body} attributes to generate an output
page.  Subclasses can override this to produce more dynamic error output.

Note, however, that it's not recommended from a security perspective to spit out
diagnostics to any old user; ideally, you should have to do something special to
enable diagnostic output, which is why the default implementation doesn't
include any.
@end deffn

@geindex error_status (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_status}@anchor{38d1}
@deffn {Attribut} error_status

The HTTP status used for error responses.  This should be a status string as
defined in 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}; it defaults to a 500 code and message.
@end deffn

@geindex error_headers (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_headers}@anchor{38d2}
@deffn {Attribut} error_headers

The HTTP headers used for error responses.  This should be a list of WSGI
response headers (@code{(name, value)} tuples), as described in 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.  The
default list just sets the content type to @code{text/plain}.
@end deffn

@geindex error_body (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler error_body}@anchor{38d3}
@deffn {Attribut} error_body

The error response body.  This should be an HTTP response body bytestring. It
defaults to the plain text, "A server error occurred.  Please contact the
administrator."
@end deffn

Methods and attributes for 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}'s "Optional Platform-Specific File
Handling" feature:

@geindex wsgi_file_wrapper (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler wsgi_file_wrapper}@anchor{38cd}
@deffn {Attribut} wsgi_file_wrapper

A @code{wsgi.file_wrapper} factory, compatible with
@ref{38a7,,wsgiref.types.FileWrapper}, or @code{None}.  The default value
of this attribute is the @ref{720,,wsgiref.util.FileWrapper} class.
@end deffn

@geindex sendfile() (méthode wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler sendfile}@anchor{38d4}
@deffn {Méthode} sendfile ()

Override to implement platform-specific file transmission.  This method is
called only if the application's return value is an instance of the class
specified by the @ref{38cd,,wsgi_file_wrapper} attribute.  It should return a true
value if it was able to successfully transmit the file, so that the default
transmission code will not be executed. The default implementation of this
method just returns a false value.
@end deffn

Miscellaneous methods and attributes:

@geindex origin_server (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler origin_server}@anchor{38ca}
@deffn {Attribut} origin_server

This attribute should be set to a true value if the handler's @ref{38c0,,_write()} and
@ref{38c1,,_flush()} are being used to communicate directly to the client, rather than
via a CGI-like gateway protocol that wants the HTTP status in a special
@code{Status:} header.

This attribute's default value is true in @ref{197e,,BaseHandler}, but false in
@ref{38ba,,BaseCGIHandler} and @ref{38b9,,CGIHandler}.
@end deffn

@geindex http_version (attribut wsgiref.handlers.BaseHandler)
@anchor{library/wsgiref wsgiref handlers BaseHandler http_version}@anchor{38d5}
@deffn {Attribut} http_version

If @ref{38ca,,origin_server} is true, this string attribute is used to set the HTTP
version of the response set to the client.  It defaults to @code{"1.0"}.
@end deffn
@end deffn

@geindex read_environ() (dans le module wsgiref.handlers)
@anchor{library/wsgiref wsgiref handlers read_environ}@anchor{1196}
@deffn {Fonction} wsgiref.handlers.read_environ ()

Transcode CGI variables from @code{os.environ} to 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/} "bytes in unicode"
strings, returning a new dictionary.  This function is used by
@ref{38b9,,CGIHandler} and @ref{38bb,,IISCGIHandler} in place of directly using
@code{os.environ}, which is not necessarily WSGI-compliant on all platforms
and web servers using Python 3 -- specifically, ones where the OS's
actual environment is Unicode (i.e. Windows), or ones where the environment
is bytes, but the system encoding used by Python to decode it is anything
other than ISO-8859-1 (e.g. Unix systems using UTF-8).

If you are implementing a CGI-based handler of your own, you probably want
to use this routine instead of just copying values out of @code{os.environ}
directly.


Ajouté dans la version 3.2.

@end deffn

@node wsgiref types -- WSGI types for static type checking,Exemples<24>,wsgiref handlers -- server/gateway base classes,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref module-wsgiref types}@anchor{11b}@anchor{library/wsgiref wsgiref-types-wsgi-types-for-static-type-checking}@anchor{38d6}
@subsubsection @code{wsgiref.types} -- WSGI types for static type checking


@geindex module; wsgiref.types

This module provides various types for static type checking as described
in 
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}.


Ajouté dans la version 3.11.


@geindex StartResponse (classe dans wsgiref.types)
@anchor{library/wsgiref wsgiref types StartResponse}@anchor{38d7}
@deffn {Classe} wsgiref.types.StartResponse

A @ref{261,,typing.Protocol} describing 
@geindex Python Enhancement Proposals; PEP 3333#the-start-response-callable
start_response()@footnote{https://peps.python.org/pep-3333/#the-start-response-callable}
callables (
@geindex Python Enhancement Proposals; PEP 3333
PEP 3333@footnote{https://peps.python.org/pep-3333/}).
@end deffn

@geindex WSGIEnvironment (dans le module wsgiref.types)
@anchor{library/wsgiref wsgiref types WSGIEnvironment}@anchor{38a1}
@deffn {Données} wsgiref.types.WSGIEnvironment

A type alias describing a WSGI environment dictionary.
@end deffn

@geindex WSGIApplication (dans le module wsgiref.types)
@anchor{library/wsgiref wsgiref types WSGIApplication}@anchor{38d8}
@deffn {Données} wsgiref.types.WSGIApplication

A type alias describing a WSGI application callable.
@end deffn

@geindex InputStream (classe dans wsgiref.types)
@anchor{library/wsgiref wsgiref types InputStream}@anchor{38c3}
@deffn {Classe} wsgiref.types.InputStream

A @ref{261,,typing.Protocol} describing a 
@geindex Python Enhancement Proposals; PEP 3333#input-and-error-streams
WSGI Input Stream@footnote{https://peps.python.org/pep-3333/#input-and-error-streams}.
@end deffn

@geindex ErrorStream (classe dans wsgiref.types)
@anchor{library/wsgiref wsgiref types ErrorStream}@anchor{38c4}
@deffn {Classe} wsgiref.types.ErrorStream

A @ref{261,,typing.Protocol} describing a 
@geindex Python Enhancement Proposals; PEP 3333#input-and-error-streams
WSGI Error Stream@footnote{https://peps.python.org/pep-3333/#input-and-error-streams}.
@end deffn

@geindex FileWrapper (classe dans wsgiref.types)
@anchor{library/wsgiref wsgiref types FileWrapper}@anchor{38a7}
@deffn {Classe} wsgiref.types.FileWrapper

A @ref{261,,typing.Protocol} describing a 
@geindex Python Enhancement Proposals; PEP 3333#optional-platform-specific-file-handling
file wrapper@footnote{https://peps.python.org/pep-3333/#optional-platform-specific-file-handling}.
See @ref{720,,wsgiref.util.FileWrapper} for a concrete implementation of this
protocol.
@end deffn

@node Exemples<24>,,wsgiref types -- WSGI types for static type checking,wsgiref --- WSGI Utilities and Reference Implementation
@anchor{library/wsgiref examples}@anchor{38d9}
@subsubsection Exemples


This is a working "Hello World" WSGI application:

@example
"""
Every WSGI application must have an application object - a callable
object that accepts two arguments. For that purpose, we're going to
use a function (note that you're not limited to a function, you can
use a class for example). The first argument passed to the function
is a dictionary containing CGI-style environment variables and the
second variable is the callable object.
"""
from wsgiref.simple_server import make_server


def hello_world_app(environ, start_response):
    status = "200 OK"  # HTTP Status
    headers = [("Content-type", "text/plain; charset=utf-8")]  # HTTP Headers
    start_response(status, headers)

    # The returned object is going to be printed
    return [b"Hello World"]

with make_server("", 8000, hello_world_app) as httpd:
    print("Serving on port 8000...")

    # Serve until process is killed
    httpd.serve_forever()
@end example

Example of a WSGI application serving the current directory, accept optional
directory and port number (default: 8000) on the command line:

@example
"""
Small wsgiref based web server. Takes a path to serve from and an
optional port number (defaults to 8000), then tries to serve files.
MIME types are guessed from the file names, 404 errors are raised
if the file is not found.
"""
import mimetypes
import os
import sys
from wsgiref import simple_server, util


def app(environ, respond):
    # Get the file name and MIME type
    fn = os.path.join(path, environ["PATH_INFO"][1:])
    if "." not in fn.split(os.path.sep)[-1]:
        fn = os.path.join(fn, "index.html")
    mime_type = mimetypes.guess_file_type(fn)[0]

    # Return 200 OK if file exists, otherwise 404 Not Found
    if os.path.exists(fn):
        respond("200 OK", [("Content-Type", mime_type)])
        return util.FileWrapper(open(fn, "rb"))
    else:
        respond("404 Not Found", [("Content-Type", "text/plain")])
        return [b"not found"]


if __name__ == "__main__":
    # Get the path and port from command-line arguments
    path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8000

    # Make and start the server until control-c
    httpd = simple_server.make_server("", port, app)
    print(f"Serving @{path@} on port @{port@}, control-C to stop")
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        print("Shutting down.")
        httpd.server_close()
@end example

@node urllib --- URL handling modules,urllib request --- Extensible library for opening URLs,wsgiref --- WSGI Utilities and Reference Implementation,Gestion des protocoles internet
@anchor{library/urllib doc}@anchor{38da}@anchor{library/urllib module-urllib}@anchor{107}@anchor{library/urllib urllib-url-handling-modules}@anchor{38db}
@subsection @code{urllib} --- URL handling modules


@geindex module; urllib

`Code source :' Lib/urllib/@footnote{https://github.com/python/cpython/tree/3.13/Lib/urllib/}


__________________________________________________________________


@code{urllib} est un paquet qui collecte plusieurs modules travaillant avec les URLs :


@itemize *

@item 
@ref{10a,,urllib.request} pour ouvrir et lire des URLs ;

@item 
@ref{108,,urllib.error} contenant les exceptions levées par @ref{10a,,urllib.request} ;

@item 
@ref{109,,urllib.parse} pour analyser les URLs ;

@item 
@ref{10c,,urllib.robotparser} pour analyser les fichiers @code{robots.txt}.
@end itemize

@node urllib request --- Extensible library for opening URLs,urllib response --- Response classes used by urllib,urllib --- URL handling modules,Gestion des protocoles internet
@anchor{library/urllib request doc}@anchor{38dc}@anchor{library/urllib request module-urllib request}@anchor{10a}@anchor{library/urllib request urllib-request-extensible-library-for-opening-urls}@anchor{38dd}
@subsection @code{urllib.request} --- Extensible library for opening URLs


@geindex module; urllib.request

`Source code:' Lib/urllib/request.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/urllib/request.py}


__________________________________________________________________


The @ref{10a,,urllib.request} module defines functions and classes which help in
opening URLs (mostly HTTP) in a complex world --- basic and digest
authentication, redirections, cookies and more.


@subsubheading Voir aussi


The Requests package@footnote{https://requests.readthedocs.io/en/master/}
is recommended for a higher-level HTTP client interface.


@cartouche
@quotation Avertissement 
On macOS it is unsafe to use this module in programs using
@ref{195,,os.fork()} because the @ref{38de,,getproxies()} implementation for
macOS uses a higher-level system API. Set the environment variable
@code{no_proxy} to @code{*} to avoid this problem
(e.g. @code{os.environ["no_proxy"] = "*"}).
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

The @ref{10a,,urllib.request} module defines the following functions:

@geindex urlopen() (dans le module urllib.request)
@anchor{library/urllib request urllib request urlopen}@anchor{290}
@deffn {Fonction} urllib.request.urlopen (url, data=None[, timeout], *, context=None)

Open `url', which can be either a string containing a valid, properly
encoded URL, or a @ref{fc3,,Request} object.

`data' must be an object specifying additional data to be sent to the
server, or @code{None} if no such data is needed.  See @ref{fc3,,Request}
for details.

urllib.request module uses HTTP/1.1 and includes @code{Connection:close} header
in its HTTP requests.

The optional `timeout' parameter specifies a timeout in seconds for
blocking operations like the connection attempt (if not specified,
the global default timeout setting will be used).  This actually
only works for HTTP, HTTPS and FTP connections.

If `context' is specified, it must be a @ref{291,,ssl.SSLContext} instance
describing the various SSL options. See @ref{b2f,,HTTPSConnection}
for more details.

This function always returns an object which can work as a
@ref{5be,,context manager} and has the properties `url', `headers', and `status'.
See @ref{38df,,urllib.response.addinfourl} for more detail on these properties.

For HTTP and HTTPS URLs, this function returns a
@ref{10b0,,http.client.HTTPResponse} object slightly modified. In addition
to the three new methods above, the msg attribute contains the
same information as the @ref{38e0,,reason}
attribute --- the reason phrase returned by server --- instead of
the response headers as it is specified in the documentation for
@ref{10b0,,HTTPResponse}.

For FTP, file, and data URLs and requests explicitly handled by legacy
@ref{303,,URLopener} and @ref{304,,FancyURLopener} classes, this function
returns a @ref{38df,,urllib.response.addinfourl} object.

Raises @ref{38e1,,URLError} on protocol errors.

Note that @code{None} may be returned if no handler handles the request (though
the default installed global @ref{38e2,,OpenerDirector} uses
@ref{38e3,,UnknownHandler} to ensure this never happens).

In addition, if proxy settings are detected (for example, when a @code{*_proxy}
environment variable like @code{http_proxy} is set),
@ref{195e,,ProxyHandler} is default installed and makes sure the requests are
handled through the proxy.

The legacy @code{urllib.urlopen} function from Python 2.6 and earlier has been
discontinued; @ref{290,,urllib.request.urlopen()} corresponds to the old
@code{urllib2.urlopen}.  Proxy handling, which was done by passing a dictionary
parameter to @code{urllib.urlopen}, can be obtained by using
@ref{195e,,ProxyHandler} objects.


The default opener raises an @ref{1848,,auditing event}
@code{urllib.Request} with arguments @code{fullurl}, @code{data}, @code{headers},
@code{method} taken from the request object.



Modifié dans la version 3.2: `cafile' and `capath' were added.

HTTPS virtual hosts are now supported if possible (that is, if
@ref{33d6,,ssl.HAS_SNI} is true).

`data' can be an iterable object.



Modifié dans la version 3.3: `cadefault' was added.



Modifié dans la version 3.4.3: `context' was added.



Modifié dans la version 3.10: HTTPS connection now send an ALPN extension with protocol indicator
@code{http/1.1} when no `context' is given. Custom `context' should set
ALPN protocols with @ref{e4d,,set_alpn_protocols()}.



Modifié dans la version 3.13: Remove `cafile', `capath' and `cadefault' parameters: use the `context'
parameter instead.

@end deffn

@geindex install_opener() (dans le module urllib.request)
@anchor{library/urllib request urllib request install_opener}@anchor{38e4}
@deffn {Fonction} urllib.request.install_opener (opener)

Install an @ref{38e2,,OpenerDirector} instance as the default global opener.
Installing an opener is only necessary if you want urlopen to use that
opener; otherwise, simply call @ref{fc7,,OpenerDirector.open()} instead of
@ref{290,,urlopen()}.  The code does not check for a real
@ref{38e2,,OpenerDirector}, and any class with the appropriate interface will
work.
@end deffn

@geindex build_opener() (dans le module urllib.request)
@anchor{library/urllib request urllib request build_opener}@anchor{38e5}
@deffn {Fonction} urllib.request.build_opener ([handler, ...])

Return an @ref{38e2,,OpenerDirector} instance, which chains the handlers in the
order given. `handler's can be either instances of @ref{38e6,,BaseHandler}, or
subclasses of @ref{38e6,,BaseHandler} (in which case it must be possible to call
the constructor without any parameters).  Instances of the following classes
will be in front of the `handler's, unless the `handler's contain them,
instances of them or subclasses of them: @ref{195e,,ProxyHandler} (if proxy
settings are detected), @ref{38e3,,UnknownHandler}, @ref{38e7,,HTTPHandler},
@ref{38e8,,HTTPDefaultErrorHandler}, @ref{38e9,,HTTPRedirectHandler},
@ref{38ea,,FTPHandler}, @ref{38eb,,FileHandler}, @ref{38ec,,HTTPErrorProcessor}.

If the Python installation has SSL support (i.e., if the @ref{cf,,ssl} module
can be imported), @ref{1201,,HTTPSHandler} will also be added.

A @ref{38e6,,BaseHandler} subclass may also change its @code{handler_order}
attribute to modify its position in the handlers list.
@end deffn

@geindex pathname2url() (dans le module urllib.request)
@anchor{library/urllib request urllib request pathname2url}@anchor{151b}
@deffn {Fonction} urllib.request.pathname2url (path)

Convert the given local path to a @code{file:} URL. This function uses
@ref{b91,,quote()} function to encode the path. For historical
reasons, the return value omits the @code{file:} scheme prefix. This example
shows the function being used on Windows:

@example
>>> from urllib.request import pathname2url
>>> path = 'C:\\Program Files'
>>> 'file:' + pathname2url(path)
'file:///C:/Program%20Files'
@end example
@end deffn

@geindex url2pathname() (dans le module urllib.request)
@anchor{library/urllib request urllib request url2pathname}@anchor{151c}
@deffn {Fonction} urllib.request.url2pathname (url)

Convert the given @code{file:} URL to a local path. This function uses
@ref{1714,,unquote()} to decode the URL. For historical reasons,
the given value `must' omit the @code{file:} scheme prefix. This example shows
the function being used on Windows:

@example
>>> from urllib.request import url2pathname
>>> url = 'file:///C:/Program%20Files'
>>> url2pathname(url.removeprefix('file:'))
'C:\\Program Files'
@end example
@end deffn

@geindex getproxies() (dans le module urllib.request)
@anchor{library/urllib request urllib request getproxies}@anchor{38de}
@deffn {Fonction} urllib.request.getproxies ()

This helper function returns a dictionary of scheme to proxy server URL
mappings. It scans the environment for variables named @code{<scheme>_proxy},
in a case insensitive approach, for all operating systems first, and when it
cannot find it, looks for proxy information from System
Configuration for macOS and Windows Systems Registry for Windows.
If both lowercase and uppercase environment variables exist (and disagree),
lowercase is preferred.

@cartouche
@quotation Note 
If the environment variable @code{REQUEST_METHOD} is set, which usually
indicates your script is running in a CGI environment, the environment
variable @code{HTTP_PROXY} (uppercase @code{_PROXY}) will be ignored. This is
because that variable can be injected by a client using the "Proxy:" HTTP
header. If you need to use an HTTP proxy in a CGI environment, either use
@code{ProxyHandler} explicitly, or make sure the variable name is in
lowercase (or at least the @code{_proxy} suffix).
@end quotation
@end cartouche
@end deffn

The following classes are provided:

@geindex Request (classe dans urllib.request)
@anchor{library/urllib request urllib request Request}@anchor{fc3}
@deffn {Classe} urllib.request.Request (url, data=None, headers=@{@}, origin_req_host=None, unverifiable=False, method=None)

This class is an abstraction of a URL request.

`url' should be a string containing a valid, properly encoded URL.

`data' must be an object specifying additional data to send to the
server, or @code{None} if no such data is needed.  Currently HTTP
requests are the only ones that use `data'.  The supported object
types include bytes, file-like objects, and iterables of bytes-like objects.
If no @code{Content-Length} nor @code{Transfer-Encoding} header field
has been provided, @ref{38e7,,HTTPHandler} will set these headers according
to the type of `data'.  @code{Content-Length} will be used to send
bytes objects, while @code{Transfer-Encoding: chunked} as specified in
@geindex RFC; RFC 7230
RFC 7230@footnote{https://datatracker.ietf.org/doc/html/rfc7230.html}, Section 3.3.1 will be used to send files and other iterables.

For an HTTP POST request method, `data' should be a buffer in the
standard @code{application/x-www-form-urlencoded} format.  The
@ref{e7e,,urllib.parse.urlencode()} function takes a mapping or sequence
of 2-tuples and returns an ASCII string in this format. It should
be encoded to bytes before being used as the `data' parameter.

`headers' should be a dictionary, and will be treated as if
@ref{38ed,,add_header()} was called with each key and value as arguments.
This is often used to "spoof" the @code{User-Agent} header value, which is
used by a browser to identify itself -- some HTTP servers only
allow requests coming from common browsers as opposed to scripts.
For example, Mozilla Firefox may identify itself as @code{"Mozilla/5.0
(X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"}, while
@ref{107,,urllib}'s default user agent string is
@code{"Python-urllib/2.6"} (on Python 2.6).
All header keys are sent in camel case.

An appropriate @code{Content-Type} header should be included if the `data'
argument is present.  If this header has not been provided and `data'
is not @code{None}, @code{Content-Type: application/x-www-form-urlencoded} will
be added as a default.

The next two arguments are only of interest for correct handling
of third-party HTTP cookies:

`origin_req_host' should be the request-host of the origin
transaction, as defined by 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html}.  It defaults to
@code{http.cookiejar.request_host(self)}.  This is the host name or IP
address of the original request that was initiated by the user.
For example, if the request is for an image in an HTML document,
this should be the request-host of the request for the page
containing the image.

`unverifiable' should indicate whether the request is unverifiable,
as defined by 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html}.  It defaults to @code{False}.  An unverifiable
request is one whose URL the user did not have the option to
approve.  For example, if the request is for an image in an HTML
document, and the user had no option to approve the automatic
fetching of the image, this should be true.

`method' should be a string that indicates the HTTP request method that
will be used (e.g. @code{'HEAD'}).  If provided, its value is stored in the
@ref{fc4,,method} attribute and is used by @ref{1149,,get_method()}.
The default is @code{'GET'} if `data' is @code{None} or @code{'POST'} otherwise.
Subclasses may indicate a different default method by setting the
@ref{fc4,,method} attribute in the class itself.

@cartouche
@quotation Note 
The request will not work as expected if the data object is unable
to deliver its content more than once (e.g. a file or an iterable
that can produce the content only once) and the request is retried
for HTTP redirects or authentication.  The `data' is sent to the
HTTP server right away after the headers.  There is no support for
a 100-continue expectation in the library.
@end quotation
@end cartouche


Modifié dans la version 3.3: @ref{fc4,,Request.method} argument is added to the Request class.



Modifié dans la version 3.4: Default @ref{fc4,,Request.method} may be indicated at the class level.



Modifié dans la version 3.6: Do not raise an error if the @code{Content-Length} has not been
provided and `data' is neither @code{None} nor a bytes object.
Fall back to use chunked transfer encoding instead.

@end deffn

@geindex OpenerDirector (classe dans urllib.request)
@anchor{library/urllib request urllib request OpenerDirector}@anchor{38e2}
@deffn {Classe} urllib.request.OpenerDirector

The @ref{38e2,,OpenerDirector} class opens URLs via @ref{38e6,,BaseHandler}s chained
together. It manages the chaining of handlers, and recovery from errors.
@end deffn

@geindex BaseHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request BaseHandler}@anchor{38e6}
@deffn {Classe} urllib.request.BaseHandler

This is the base class for all registered handlers --- and handles only the
simple mechanics of registration.
@end deffn

@geindex HTTPDefaultErrorHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPDefaultErrorHandler}@anchor{38e8}
@deffn {Classe} urllib.request.HTTPDefaultErrorHandler

A class which defines a default handler for HTTP error responses; all responses
are turned into @ref{fc9,,HTTPError} exceptions.
@end deffn

@geindex HTTPRedirectHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPRedirectHandler}@anchor{38e9}
@deffn {Classe} urllib.request.HTTPRedirectHandler

A class to handle redirections.
@end deffn

@geindex HTTPCookieProcessor (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPCookieProcessor}@anchor{38ee}
@deffn {Classe} urllib.request.HTTPCookieProcessor (cookiejar=None)

A class to handle HTTP Cookies.
@end deffn

@geindex ProxyHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request ProxyHandler}@anchor{195e}
@deffn {Classe} urllib.request.ProxyHandler (proxies=None)

Cause requests to go through a proxy. If `proxies' is given, it must be a
dictionary mapping protocol names to URLs of proxies. The default is to read
the list of proxies from the environment variables
@code{<protocol>_proxy}.  If no proxy environment variables are set, then
in a Windows environment proxy settings are obtained from the registry's
Internet Settings section, and in a macOS environment proxy information
is retrieved from the System Configuration Framework.

To disable autodetected proxy pass an empty dictionary.

The 
@geindex no_proxy
@geindex variable d'environnement; no_proxy
@code{no_proxy} environment variable can be used to specify hosts
which shouldn't be reached via proxy; if set, it should be a comma-separated
list of hostname suffixes, optionally with @code{:port} appended, for example
@code{cern.ch,ncsa.uiuc.edu,some.host:8080}.

@cartouche
@quotation Note 
@code{HTTP_PROXY} will be ignored if a variable @code{REQUEST_METHOD} is set;
see the documentation on @ref{38de,,getproxies()}.
@end quotation
@end cartouche
@end deffn

@geindex HTTPPasswordMgr (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPPasswordMgr}@anchor{38ef}
@deffn {Classe} urllib.request.HTTPPasswordMgr

Keep a database of  @code{(realm, uri) -> (user, password)} mappings.
@end deffn

@geindex HTTPPasswordMgrWithDefaultRealm (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithDefaultRealm}@anchor{38f0}
@deffn {Classe} urllib.request.HTTPPasswordMgrWithDefaultRealm

Keep a database of  @code{(realm, uri) -> (user, password)} mappings. A realm of
@code{None} is considered a catch-all realm, which is searched if no other realm
fits.
@end deffn

@geindex HTTPPasswordMgrWithPriorAuth (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth}@anchor{e7d}
@deffn {Classe} urllib.request.HTTPPasswordMgrWithPriorAuth

A variant of @ref{38f0,,HTTPPasswordMgrWithDefaultRealm} that also has a
database of @code{uri -> is_authenticated} mappings.  Can be used by a
BasicAuth handler to determine when to send authentication credentials
immediately instead of waiting for a @code{401} response first.


Ajouté dans la version 3.5.

@end deffn

@geindex AbstractBasicAuthHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request AbstractBasicAuthHandler}@anchor{1849}
@deffn {Classe} urllib.request.AbstractBasicAuthHandler (password_mgr=None)

This is a mixin class that helps with HTTP authentication, both to the remote
host and to a proxy. `password_mgr', if given, should be something that is
compatible with @ref{38ef,,HTTPPasswordMgr}; refer to section
@ref{38f1,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.  If `passwd_mgr' also provides @code{is_authenticated} and
@code{update_authenticated} methods (see
@ref{38f2,,HTTPPasswordMgrWithPriorAuth Objects}), then the handler will use the
@code{is_authenticated} result for a given URI to determine whether or not to
send authentication credentials with the request.  If @code{is_authenticated}
returns @code{True} for the URI, credentials are sent.  If @code{is_authenticated}
is @code{False}, credentials are not sent, and then if a @code{401} response is
received the request is re-sent with the authentication credentials.  If
authentication succeeds, @code{update_authenticated} is called to set
@code{is_authenticated} @code{True} for the URI, so that subsequent requests to
the URI or any of its super-URIs will automatically include the
authentication credentials.


Ajouté dans la version 3.5: Added @code{is_authenticated} support.

@end deffn

@geindex HTTPBasicAuthHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPBasicAuthHandler}@anchor{38f3}
@deffn {Classe} urllib.request.HTTPBasicAuthHandler (password_mgr=None)

Handle authentication with the remote host. `password_mgr', if given, should
be something that is compatible with @ref{38ef,,HTTPPasswordMgr}; refer to
section @ref{38f1,,HTTPPasswordMgr Objects} for information on the interface that must
be supported. HTTPBasicAuthHandler will raise a @ref{1ff,,ValueError} when
presented with a wrong Authentication scheme.
@end deffn

@geindex ProxyBasicAuthHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request ProxyBasicAuthHandler}@anchor{38f4}
@deffn {Classe} urllib.request.ProxyBasicAuthHandler (password_mgr=None)

Handle authentication with the proxy. `password_mgr', if given, should be
something that is compatible with @ref{38ef,,HTTPPasswordMgr}; refer to section
@ref{38f1,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.
@end deffn

@geindex AbstractDigestAuthHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request AbstractDigestAuthHandler}@anchor{1910}
@deffn {Classe} urllib.request.AbstractDigestAuthHandler (password_mgr=None)

This is a mixin class that helps with HTTP authentication, both to the remote
host and to a proxy. `password_mgr', if given, should be something that is
compatible with @ref{38ef,,HTTPPasswordMgr}; refer to section
@ref{38f1,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.
@end deffn

@geindex HTTPDigestAuthHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPDigestAuthHandler}@anchor{38f5}
@deffn {Classe} urllib.request.HTTPDigestAuthHandler (password_mgr=None)

Handle authentication with the remote host. `password_mgr', if given, should
be something that is compatible with @ref{38ef,,HTTPPasswordMgr}; refer to
section @ref{38f1,,HTTPPasswordMgr Objects} for information on the interface that must
be supported. When both Digest Authentication Handler and Basic
Authentication Handler are both added, Digest Authentication is always tried
first. If the Digest Authentication returns a 40x response again, it is sent
to Basic Authentication handler to Handle.  This Handler method will raise a
@ref{1ff,,ValueError} when presented with an authentication scheme other than
Digest or Basic.


Modifié dans la version 3.3: Raise @ref{1ff,,ValueError} on unsupported Authentication Scheme.

@end deffn

@geindex ProxyDigestAuthHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request ProxyDigestAuthHandler}@anchor{38f6}
@deffn {Classe} urllib.request.ProxyDigestAuthHandler (password_mgr=None)

Handle authentication with the proxy. `password_mgr', if given, should be
something that is compatible with @ref{38ef,,HTTPPasswordMgr}; refer to section
@ref{38f1,,HTTPPasswordMgr Objects} for information on the interface that must be
supported.
@end deffn

@geindex HTTPHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPHandler}@anchor{38e7}
@deffn {Classe} urllib.request.HTTPHandler

A class to handle opening of HTTP URLs.
@end deffn

@geindex HTTPSHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPSHandler}@anchor{1201}
@deffn {Classe} urllib.request.HTTPSHandler (debuglevel=0, context=None, check_hostname=None)

A class to handle opening of HTTPS URLs.  `context' and `check_hostname'
have the same meaning as in @ref{b2f,,http.client.HTTPSConnection}.


Modifié dans la version 3.2: `context' and `check_hostname' were added.

@end deffn

@geindex FileHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request FileHandler}@anchor{38eb}
@deffn {Classe} urllib.request.FileHandler

Open local files.
@end deffn

@geindex DataHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request DataHandler}@anchor{fc2}
@deffn {Classe} urllib.request.DataHandler

Open data URLs.


Ajouté dans la version 3.4.

@end deffn

@geindex FTPHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request FTPHandler}@anchor{38ea}
@deffn {Classe} urllib.request.FTPHandler

Open FTP URLs.
@end deffn

@geindex CacheFTPHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request CacheFTPHandler}@anchor{16b3}
@deffn {Classe} urllib.request.CacheFTPHandler

Open FTP URLs, keeping a cache of open FTP connections to minimize delays.
@end deffn

@geindex UnknownHandler (classe dans urllib.request)
@anchor{library/urllib request urllib request UnknownHandler}@anchor{38e3}
@deffn {Classe} urllib.request.UnknownHandler

A catch-all class to handle unknown URLs.
@end deffn

@geindex HTTPErrorProcessor (classe dans urllib.request)
@anchor{library/urllib request urllib request HTTPErrorProcessor}@anchor{38ec}
@deffn {Classe} urllib.request.HTTPErrorProcessor

Process HTTP error responses.
@end deffn

@menu
* Request Objects:: 
* OpenerDirector Objects:: 
* BaseHandler Objects:: 
* HTTPRedirectHandler Objects:: 
* HTTPCookieProcessor Objects:: 
* ProxyHandler Objects:: 
* HTTPPasswordMgr Objects:: 
* HTTPPasswordMgrWithPriorAuth Objects:: 
* AbstractBasicAuthHandler Objects:: 
* HTTPBasicAuthHandler Objects:: 
* ProxyBasicAuthHandler Objects:: 
* AbstractDigestAuthHandler Objects:: 
* HTTPDigestAuthHandler Objects:: 
* ProxyDigestAuthHandler Objects:: 
* HTTPHandler Objects:: 
* HTTPSHandler Objects:: 
* FileHandler Objects:: 
* DataHandler Objects:: 
* FTPHandler Objects:: 
* CacheFTPHandler Objects:: 
* UnknownHandler Objects:: 
* HTTPErrorProcessor Objects:: 
* Exemples: Exemples<25>. 
* Legacy interface:: 
* urllib.request Restrictions: urllib request Restrictions. 

@end menu

@node Request Objects,OpenerDirector Objects,,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request id1}@anchor{38f7}@anchor{library/urllib request request-objects}@anchor{38f8}
@subsubsection Request Objects


The following methods describe @ref{fc3,,Request}'s public interface,
and so all may be overridden in subclasses.  It also defines several
public attributes that can be used by clients to inspect the parsed
request.

@geindex full_url (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request full_url}@anchor{fc5}
@deffn {Attribut} Request.full_url

The original URL passed to the constructor.


Modifié dans la version 3.4.


Request.full_url is a property with setter, getter and a deleter. Getting
@ref{fc5,,full_url} returns the original request URL with the
fragment, if it was present.
@end deffn

@geindex type (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request type}@anchor{38f9}
@deffn {Attribut} Request.type

The URI scheme.
@end deffn

@geindex host (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request host}@anchor{38fa}
@deffn {Attribut} Request.host

The URI authority, typically a host, but may also contain a port
separated by a colon.
@end deffn

@geindex origin_req_host (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request origin_req_host}@anchor{38fb}
@deffn {Attribut} Request.origin_req_host

The original host for the request, without port.
@end deffn

@geindex selector (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request selector}@anchor{38fc}
@deffn {Attribut} Request.selector

The URI path.  If the @ref{fc3,,Request} uses a proxy, then selector
will be the full URL that is passed to the proxy.
@end deffn

@geindex data (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request data}@anchor{fc6}
@deffn {Attribut} Request.data

The entity body for the request, or @code{None} if not specified.


Modifié dans la version 3.4: Changing value of @ref{fc6,,Request.data} now deletes "Content-Length"
header if it was previously set or calculated.

@end deffn

@geindex unverifiable (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request unverifiable}@anchor{38fd}
@deffn {Attribut} Request.unverifiable

boolean, indicates whether the request is unverifiable as defined
by 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html}.
@end deffn

@geindex method (attribut urllib.request.Request)
@anchor{library/urllib request urllib request Request method}@anchor{fc4}
@deffn {Attribut} Request.method

The HTTP request method to use.  By default its value is @ref{660,,None},
which means that @ref{1149,,get_method()} will do its normal computation
of the method to be used.  Its value can be set (thus overriding the default
computation in @ref{1149,,get_method()}) either by providing a default
value by setting it at the class level in a @ref{fc3,,Request} subclass, or by
passing a value in to the @ref{fc3,,Request} constructor via the `method'
argument.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: A default value can now be set in subclasses; previously it could only
be set via the constructor argument.

@end deffn

@geindex get_method() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request get_method}@anchor{1149}
@deffn {Méthode} Request.get_method ()

Return a string indicating the HTTP request method.  If
@ref{fc4,,Request.method} is not @code{None}, return its value, otherwise return
@code{'GET'} if @ref{fc6,,Request.data} is @code{None}, or @code{'POST'} if it's not.
This is only meaningful for HTTP requests.


Modifié dans la version 3.3: get_method now looks at the value of @ref{fc4,,Request.method}.

@end deffn

@geindex add_header() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request add_header}@anchor{38ed}
@deffn {Méthode} Request.add_header (key, val)

Add another header to the request.  Headers are currently ignored by all
handlers except HTTP handlers, where they are added to the list of headers sent
to the server.  Note that there cannot be more than one header with the same
name, and later calls will overwrite previous calls in case the `key' collides.
Currently, this is no loss of HTTP functionality, since all headers which have
meaning when used more than once have a (header-specific) way of gaining the
same functionality using only one header.  Note that headers added using
this method are also added to redirected requests.
@end deffn

@geindex add_unredirected_header() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request add_unredirected_header}@anchor{38fe}
@deffn {Méthode} Request.add_unredirected_header (key, header)

Add a header that will not be added to a redirected request.
@end deffn

@geindex has_header() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request has_header}@anchor{38ff}
@deffn {Méthode} Request.has_header (header)

Return whether the instance has the named header (checks both regular and
unredirected).
@end deffn

@geindex remove_header() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request remove_header}@anchor{fc8}
@deffn {Méthode} Request.remove_header (header)

Remove named header from the request instance (both from regular and
unredirected headers).


Ajouté dans la version 3.4.

@end deffn

@geindex get_full_url() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request get_full_url}@anchor{3900}
@deffn {Méthode} Request.get_full_url ()

Return the URL given in the constructor.


Modifié dans la version 3.4.


Returns @ref{fc5,,Request.full_url}
@end deffn

@geindex set_proxy() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request set_proxy}@anchor{3901}
@deffn {Méthode} Request.set_proxy (host, type)

Prepare the request by connecting to a proxy server. The `host' and `type' will
replace those of the instance, and the instance's selector will be the original
URL given in the constructor.
@end deffn

@geindex get_header() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request get_header}@anchor{3902}
@deffn {Méthode} Request.get_header (header_name, default=None)

Return the value of the given header. If the header is not present, return
the default value.
@end deffn

@geindex header_items() (méthode urllib.request.Request)
@anchor{library/urllib request urllib request Request header_items}@anchor{3903}
@deffn {Méthode} Request.header_items ()

Return a list of tuples (header_name, header_value) of the Request headers.
@end deffn


Modifié dans la version 3.4: The request methods add_data, has_data, get_data, get_type, get_host,
get_selector, get_origin_req_host and is_unverifiable that were deprecated
since 3.3 have been removed.


@node OpenerDirector Objects,BaseHandler Objects,Request Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request opener-director-objects}@anchor{3904}@anchor{library/urllib request openerdirector-objects}@anchor{3905}
@subsubsection OpenerDirector Objects


@ref{38e2,,OpenerDirector} instances have the following methods:

@geindex add_handler() (méthode urllib.request.OpenerDirector)
@anchor{library/urllib request urllib request OpenerDirector add_handler}@anchor{3906}
@deffn {Méthode} OpenerDirector.add_handler (handler)

`handler' should be an instance of @ref{38e6,,BaseHandler}.  The following methods
are searched, and added to the possible chains (note that HTTP errors are a
special case).  Note that, in the following, `protocol' should be replaced
with the actual protocol to handle, for example @code{http_response()} would
be the HTTP protocol response handler.  Also `type' should be replaced with
the actual HTTP code, for example @code{http_error_404()} would handle HTTP
404 errors.


@itemize *

@item 
@code{<protocol>_open()} --- signal that the handler knows how to open `protocol'
URLs.

See @ref{3907,,BaseHandler.<protocol>_open()} for more information.

@item 
@code{http_error_<type>()} --- signal that the handler knows how to handle HTTP
errors with HTTP error code `type'.

See @ref{3908,,BaseHandler.http_error_<nnn>()} for more information.

@item 
@code{<protocol>_error()} --- signal that the handler knows how to handle errors
from (non-@code{http}) `protocol'.

@item 
@code{<protocol>_request()} --- signal that the handler knows how to pre-process
`protocol' requests.

See @ref{3909,,BaseHandler.<protocol>_request()} for more information.

@item 
@code{<protocol>_response()} --- signal that the handler knows how to
post-process `protocol' responses.

See @ref{390a,,BaseHandler.<protocol>_response()} for more information.
@end itemize
@end deffn

@geindex open() (méthode urllib.request.OpenerDirector)
@anchor{library/urllib request urllib request OpenerDirector open}@anchor{fc7}
@deffn {Méthode} OpenerDirector.open (url, data=None[, timeout])

Open the given `url' (which can be a request object or a string), optionally
passing the given `data'. Arguments, return values and exceptions raised are
the same as those of @ref{290,,urlopen()} (which simply calls the @ref{505,,open()}
method on the currently installed global @ref{38e2,,OpenerDirector}).  The
optional `timeout' parameter specifies a timeout in seconds for blocking
operations like the connection attempt (if not specified, the global default
timeout setting will be used). The timeout feature actually works only for
HTTP, HTTPS and FTP connections.
@end deffn

@geindex error() (méthode urllib.request.OpenerDirector)
@anchor{library/urllib request urllib request OpenerDirector error}@anchor{390b}
@deffn {Méthode} OpenerDirector.error (proto, *args)

Handle an error of the given protocol.  This will call the registered error
handlers for the given protocol with the given arguments (which are protocol
specific).  The HTTP protocol is a special case which uses the HTTP response
code to determine the specific error handler; refer to the @code{http_error_<type>()}
methods of the handler classes.

Return values and exceptions raised are the same as those of @ref{290,,urlopen()}.
@end deffn

OpenerDirector objects open URLs in three stages:

The order in which these methods are called within each stage is determined by
sorting the handler instances.


@enumerate 

@item 
Every handler with a method named like @code{<protocol>_request()} has that
method called to pre-process the request.

@item 
Handlers with a method named like @code{<protocol>_open()} are called to handle
the request. This stage ends when a handler either returns a non-@ref{660,,None}
value (ie. a response), or raises an exception (usually
@ref{38e1,,URLError}).  Exceptions are allowed to propagate.

In fact, the above algorithm is first tried for methods named
@ref{390c,,default_open()}.  If all such methods return @ref{660,,None}, the algorithm
is repeated for methods named like @code{<protocol>_open()}.  If all such methods
return @ref{660,,None}, the algorithm is repeated for methods named
@ref{390d,,unknown_open()}.

Note that the implementation of these methods may involve calls of the parent
@ref{38e2,,OpenerDirector} instance's @ref{fc7,,open()} and
@ref{390b,,error()} methods.

@item 
Every handler with a method named like @code{<protocol>_response()} has that
method called to post-process the response.
@end enumerate

@node BaseHandler Objects,HTTPRedirectHandler Objects,OpenerDirector Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request base-handler-objects}@anchor{390e}@anchor{library/urllib request basehandler-objects}@anchor{390f}
@subsubsection BaseHandler Objects


@ref{38e6,,BaseHandler} objects provide a couple of methods that are directly
useful, and others that are meant to be used by derived classes.  These are
intended for direct use:

@geindex add_parent() (méthode urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler add_parent}@anchor{3910}
@deffn {Méthode} BaseHandler.add_parent (director)

Add a director as parent.
@end deffn

@geindex close() (méthode urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler close}@anchor{3911}
@deffn {Méthode} BaseHandler.close ()

Remove any parents.
@end deffn

The following attribute and methods should only be used by classes derived from
@ref{38e6,,BaseHandler}.

@cartouche
@quotation Note 
The convention has been adopted that subclasses defining
@code{<protocol>_request()} or @code{<protocol>_response()} methods are named
@code{*Processor}; all others are named @code{*Handler}.
@end quotation
@end cartouche

@geindex parent (attribut urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler parent}@anchor{3912}
@deffn {Attribut} BaseHandler.parent

A valid @ref{38e2,,OpenerDirector}, which can be used to open using a different
protocol, or handle errors.
@end deffn

@geindex default_open() (méthode urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler default_open}@anchor{390c}
@deffn {Méthode} BaseHandler.default_open (req)

This method is `not' defined in @ref{38e6,,BaseHandler}, but subclasses should
define it if they want to catch all URLs.

This method, if implemented, will be called by the parent
@ref{38e2,,OpenerDirector}.  It should return a file-like object as described in
the return value of the @ref{fc7,,open()} method of @ref{38e2,,OpenerDirector}, or @code{None}.
It should raise @ref{38e1,,URLError}, unless a truly exceptional
thing happens (for example, @ref{164b,,MemoryError} should not be mapped to
@ref{38e1,,URLError}).

This method will be called before any protocol-specific open method.
@end deffn

@anchor{library/urllib request protocol-open}@anchor{3907}
@deffn {Méthode} BaseHandler.<protocol>_open(req)

This method is `not' defined in @ref{38e6,,BaseHandler}, but subclasses should
define it if they want to handle URLs with the given protocol.

This method, if defined, will be called by the parent @ref{38e2,,OpenerDirector}.
Return values should be the same as for  @ref{390c,,default_open()}.
@end deffn

@geindex unknown_open() (méthode urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler unknown_open}@anchor{390d}
@deffn {Méthode} BaseHandler.unknown_open (req)

This method is `not' defined in @ref{38e6,,BaseHandler}, but subclasses should
define it if they want to catch all URLs with no specific registered handler to
open it.

This method, if implemented, will be called by the @ref{3912,,parent}
@ref{38e2,,OpenerDirector}.  Return values should be the same as for
@ref{390c,,default_open()}.
@end deffn

@geindex http_error_default() (méthode urllib.request.BaseHandler)
@anchor{library/urllib request urllib request BaseHandler http_error_default}@anchor{3913}
@deffn {Méthode} BaseHandler.http_error_default (req, fp, code, msg, hdrs)

This method is `not' defined in @ref{38e6,,BaseHandler}, but subclasses should
override it if they intend to provide a catch-all for otherwise unhandled HTTP
errors.  It will be called automatically by the  @ref{38e2,,OpenerDirector} getting
the error, and should not normally be called in other circumstances.

`req' will be a @ref{fc3,,Request} object, `fp' will be a file-like object with
the HTTP error body, `code' will be the three-digit code of the error, `msg'
will be the user-visible explanation of the code and `hdrs' will be a mapping
object with the headers of the error.

Return values and exceptions raised should be the same as those of
@ref{290,,urlopen()}.
@end deffn

@anchor{library/urllib request http-error-nnn}@anchor{3908}
@deffn {Méthode} BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

`nnn' should be a three-digit HTTP error code.  This method is also not defined
in @ref{38e6,,BaseHandler}, but will be called, if it exists, on an instance of a
subclass, when an HTTP error with code `nnn' occurs.

Subclasses should override this method to handle specific HTTP errors.

Arguments, return values and exceptions raised should be the same as for
@ref{3913,,http_error_default()}.
@end deffn

@anchor{library/urllib request protocol-request}@anchor{3909}
@deffn {Méthode} BaseHandler.<protocol>_request(req)

This method is `not' defined in @ref{38e6,,BaseHandler}, but subclasses should
define it if they want to pre-process requests of the given protocol.

This method, if defined, will be called by the parent @ref{38e2,,OpenerDirector}.
`req' will be a @ref{fc3,,Request} object. The return value should be a
@ref{fc3,,Request} object.
@end deffn

@anchor{library/urllib request protocol-response}@anchor{390a}
@deffn {Méthode} BaseHandler.<protocol>_response(req, response)

This method is `not' defined in @ref{38e6,,BaseHandler}, but subclasses should
define it if they want to post-process responses of the given protocol.

This method, if defined, will be called by the parent @ref{38e2,,OpenerDirector}.
`req' will be a @ref{fc3,,Request} object. `response' will be an object
implementing the same interface as the return value of @ref{290,,urlopen()}.  The
return value should implement the same interface as the return value of
@ref{290,,urlopen()}.
@end deffn

@node HTTPRedirectHandler Objects,HTTPCookieProcessor Objects,BaseHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-redirect-handler}@anchor{3914}@anchor{library/urllib request httpredirecthandler-objects}@anchor{3915}
@subsubsection HTTPRedirectHandler Objects


@cartouche
@quotation Note 
Some HTTP redirections require action from this module's client code.  If this
is the case, @ref{fc9,,HTTPError} is raised.  See 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html} for
details of the precise meanings of the various redirection codes.

An @ref{fc9,,HTTPError} exception raised as a security consideration if the
HTTPRedirectHandler is presented with a redirected URL which is not an HTTP,
HTTPS or FTP URL.
@end quotation
@end cartouche

@geindex redirect_request() (méthode urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler redirect_request}@anchor{3916}
@deffn {Méthode} HTTPRedirectHandler.redirect_request (req, fp, code, msg, hdrs, newurl)

Return a @ref{fc3,,Request} or @code{None} in response to a redirect. This is called
by the default implementations of the @code{http_error_30*()} methods when a
redirection is received from the server.  If a redirection should take place,
return a new @ref{fc3,,Request} to allow @code{http_error_30*()} to perform the
redirect to `newurl'.  Otherwise, raise @ref{fc9,,HTTPError} if
no other handler should try to handle this URL, or return @code{None} if you
can't but another handler might.

@cartouche
@quotation Note 
The default implementation of this method does not strictly follow 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html},
which says that 301 and 302 responses to @code{POST} requests must not be
automatically redirected without confirmation by the user.  In reality, browsers
do allow automatic redirection of these responses, changing the POST to a
@code{GET}, and the default implementation reproduces this behavior.
@end quotation
@end cartouche
@end deffn

@geindex http_error_301() (méthode urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_301}@anchor{3917}
@deffn {Méthode} HTTPRedirectHandler.http_error_301 (req, fp, code, msg, hdrs)

Redirect to the @code{Location:} or @code{URI:} URL.  This method is called by the
parent @ref{38e2,,OpenerDirector} when getting an HTTP 'moved permanently' response.
@end deffn

@geindex http_error_302() (méthode urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_302}@anchor{3918}
@deffn {Méthode} HTTPRedirectHandler.http_error_302 (req, fp, code, msg, hdrs)

The same as @ref{3917,,http_error_301()}, but called for the 'found' response.
@end deffn

@geindex http_error_303() (méthode urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_303}@anchor{3919}
@deffn {Méthode} HTTPRedirectHandler.http_error_303 (req, fp, code, msg, hdrs)

The same as @ref{3917,,http_error_301()}, but called for the 'see other' response.
@end deffn

@geindex http_error_307() (méthode urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_307}@anchor{391a}
@deffn {Méthode} HTTPRedirectHandler.http_error_307 (req, fp, code, msg, hdrs)

The same as @ref{3917,,http_error_301()}, but called for the 'temporary redirect'
response. It does not allow changing the request method from @code{POST}
to @code{GET}.
@end deffn

@geindex http_error_308() (méthode urllib.request.HTTPRedirectHandler)
@anchor{library/urllib request urllib request HTTPRedirectHandler http_error_308}@anchor{391b}
@deffn {Méthode} HTTPRedirectHandler.http_error_308 (req, fp, code, msg, hdrs)

The same as @ref{3917,,http_error_301()}, but called for the 'permanent redirect'
response. It does not allow changing the request method from @code{POST}
to @code{GET}.


Ajouté dans la version 3.11.

@end deffn

@node HTTPCookieProcessor Objects,ProxyHandler Objects,HTTPRedirectHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-cookie-processor}@anchor{391c}@anchor{library/urllib request httpcookieprocessor-objects}@anchor{391d}
@subsubsection HTTPCookieProcessor Objects


@ref{38ee,,HTTPCookieProcessor} instances have one attribute:

@geindex cookiejar (attribut urllib.request.HTTPCookieProcessor)
@anchor{library/urllib request urllib request HTTPCookieProcessor cookiejar}@anchor{391e}
@deffn {Attribut} HTTPCookieProcessor.cookiejar

The @ref{391f,,http.cookiejar.CookieJar} in which cookies are stored.
@end deffn

@node ProxyHandler Objects,HTTPPasswordMgr Objects,HTTPCookieProcessor Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request proxy-handler}@anchor{3920}@anchor{library/urllib request proxyhandler-objects}@anchor{3921}
@subsubsection ProxyHandler Objects



@deffn {Méthode} ProxyHandler.<protocol>_open(request)

The @ref{195e,,ProxyHandler} will have a method @code{<protocol>_open()} for every
`protocol' which has a proxy in the `proxies' dictionary given in the
constructor.  The method will modify requests to go through the proxy, by
calling @code{request.set_proxy()}, and call the next handler in the chain to
actually execute the protocol.
@end deffn

@node HTTPPasswordMgr Objects,HTTPPasswordMgrWithPriorAuth Objects,ProxyHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-password-mgr}@anchor{38f1}@anchor{library/urllib request httppasswordmgr-objects}@anchor{3922}
@subsubsection HTTPPasswordMgr Objects


These methods are available on @ref{38ef,,HTTPPasswordMgr} and
@ref{38f0,,HTTPPasswordMgrWithDefaultRealm} objects.

@geindex add_password() (méthode urllib.request.HTTPPasswordMgr)
@anchor{library/urllib request urllib request HTTPPasswordMgr add_password}@anchor{3923}
@deffn {Méthode} HTTPPasswordMgr.add_password (realm, uri, user, passwd)

`uri' can be either a single URI, or a sequence of URIs. `realm', `user' and
`passwd' must be strings. This causes @code{(user, passwd)} to be used as
authentication tokens when authentication for `realm' and a super-URI of any of
the given URIs is given.
@end deffn

@geindex find_user_password() (méthode urllib.request.HTTPPasswordMgr)
@anchor{library/urllib request urllib request HTTPPasswordMgr find_user_password}@anchor{17cd}
@deffn {Méthode} HTTPPasswordMgr.find_user_password (realm, authuri)

Get user/password for given realm and URI, if any.  This method will return
@code{(None, None)} if there is no matching user/password.

For @ref{38f0,,HTTPPasswordMgrWithDefaultRealm} objects, the realm @code{None} will be
searched if the given `realm' has no matching user/password.
@end deffn

@node HTTPPasswordMgrWithPriorAuth Objects,AbstractBasicAuthHandler Objects,HTTPPasswordMgr Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-password-mgr-with-prior-auth}@anchor{38f2}@anchor{library/urllib request httppasswordmgrwithpriorauth-objects}@anchor{3924}
@subsubsection HTTPPasswordMgrWithPriorAuth Objects


This password manager extends @ref{38f0,,HTTPPasswordMgrWithDefaultRealm} to support
tracking URIs for which authentication credentials should always be sent.

@geindex add_password() (méthode urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth add_password}@anchor{3925}
@deffn {Méthode} HTTPPasswordMgrWithPriorAuth.add_password (realm, uri, user, passwd, is_authenticated=False)

`realm', `uri', `user', `passwd' are as for
@ref{3923,,HTTPPasswordMgr.add_password()}.  `is_authenticated' sets the initial
value of the @code{is_authenticated} flag for the given URI or list of URIs.
If `is_authenticated' is specified as @code{True}, `realm' is ignored.
@end deffn

@geindex find_user_password() (méthode urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth find_user_password}@anchor{3926}
@deffn {Méthode} HTTPPasswordMgrWithPriorAuth.find_user_password (realm, authuri)

Same as for @ref{38f0,,HTTPPasswordMgrWithDefaultRealm} objects
@end deffn

@geindex update_authenticated() (méthode urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth update_authenticated}@anchor{3927}
@deffn {Méthode} HTTPPasswordMgrWithPriorAuth.update_authenticated (self, uri, is_authenticated=False)

Update the @code{is_authenticated} flag for the given `uri' or list
of URIs.
@end deffn

@geindex is_authenticated() (méthode urllib.request.HTTPPasswordMgrWithPriorAuth)
@anchor{library/urllib request urllib request HTTPPasswordMgrWithPriorAuth is_authenticated}@anchor{17ce}
@deffn {Méthode} HTTPPasswordMgrWithPriorAuth.is_authenticated (self, authuri)

Returns the current state of the @code{is_authenticated} flag for
the given URI.
@end deffn

@node AbstractBasicAuthHandler Objects,HTTPBasicAuthHandler Objects,HTTPPasswordMgrWithPriorAuth Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request abstract-basic-auth-handler}@anchor{3928}@anchor{library/urllib request abstractbasicauthhandler-objects}@anchor{3929}
@subsubsection AbstractBasicAuthHandler Objects


@geindex http_error_auth_reqed() (méthode urllib.request.AbstractBasicAuthHandler)
@anchor{library/urllib request urllib request AbstractBasicAuthHandler http_error_auth_reqed}@anchor{392a}
@deffn {Méthode} AbstractBasicAuthHandler.http_error_auth_reqed (authreq, host, req, headers)

Handle an authentication request by getting a user/password pair, and re-trying
the request.  `authreq' should be the name of the header where the information
about the realm is included in the request, `host' specifies the URL and path to
authenticate for, `req' should be the (failed) @ref{fc3,,Request} object, and
`headers' should be the error headers.

`host' is either an authority (e.g. @code{"python.org"}) or a URL containing an
authority component (e.g. @code{"http://python.org/"}). In either case, the
authority must not contain a userinfo component (so, @code{"python.org"} and
@code{"python.org:80"} are fine, @code{"joe:password@@python.org"} is not).
@end deffn

@node HTTPBasicAuthHandler Objects,ProxyBasicAuthHandler Objects,AbstractBasicAuthHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-basic-auth-handler}@anchor{392b}@anchor{library/urllib request httpbasicauthhandler-objects}@anchor{392c}
@subsubsection HTTPBasicAuthHandler Objects


@geindex http_error_401() (méthode urllib.request.HTTPBasicAuthHandler)
@anchor{library/urllib request urllib request HTTPBasicAuthHandler http_error_401}@anchor{392d}
@deffn {Méthode} HTTPBasicAuthHandler.http_error_401 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node ProxyBasicAuthHandler Objects,AbstractDigestAuthHandler Objects,HTTPBasicAuthHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request proxy-basic-auth-handler}@anchor{392e}@anchor{library/urllib request proxybasicauthhandler-objects}@anchor{392f}
@subsubsection ProxyBasicAuthHandler Objects


@geindex http_error_407() (méthode urllib.request.ProxyBasicAuthHandler)
@anchor{library/urllib request urllib request ProxyBasicAuthHandler http_error_407}@anchor{3930}
@deffn {Méthode} ProxyBasicAuthHandler.http_error_407 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node AbstractDigestAuthHandler Objects,HTTPDigestAuthHandler Objects,ProxyBasicAuthHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request abstract-digest-auth-handler}@anchor{3931}@anchor{library/urllib request abstractdigestauthhandler-objects}@anchor{3932}
@subsubsection AbstractDigestAuthHandler Objects


@geindex http_error_auth_reqed() (méthode urllib.request.AbstractDigestAuthHandler)
@anchor{library/urllib request urllib request AbstractDigestAuthHandler http_error_auth_reqed}@anchor{3933}
@deffn {Méthode} AbstractDigestAuthHandler.http_error_auth_reqed (authreq, host, req, headers)

`authreq' should be the name of the header where the information about the realm
is included in the request, `host' should be the host to authenticate to, `req'
should be the (failed) @ref{fc3,,Request} object, and `headers' should be the
error headers.
@end deffn

@node HTTPDigestAuthHandler Objects,ProxyDigestAuthHandler Objects,AbstractDigestAuthHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-digest-auth-handler}@anchor{3934}@anchor{library/urllib request httpdigestauthhandler-objects}@anchor{3935}
@subsubsection HTTPDigestAuthHandler Objects


@geindex http_error_401() (méthode urllib.request.HTTPDigestAuthHandler)
@anchor{library/urllib request urllib request HTTPDigestAuthHandler http_error_401}@anchor{3936}
@deffn {Méthode} HTTPDigestAuthHandler.http_error_401 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node ProxyDigestAuthHandler Objects,HTTPHandler Objects,HTTPDigestAuthHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request proxy-digest-auth-handler}@anchor{3937}@anchor{library/urllib request proxydigestauthhandler-objects}@anchor{3938}
@subsubsection ProxyDigestAuthHandler Objects


@geindex http_error_407() (méthode urllib.request.ProxyDigestAuthHandler)
@anchor{library/urllib request urllib request ProxyDigestAuthHandler http_error_407}@anchor{3939}
@deffn {Méthode} ProxyDigestAuthHandler.http_error_407 (req, fp, code, msg, hdrs)

Retry the request with authentication information, if available.
@end deffn

@node HTTPHandler Objects,HTTPSHandler Objects,ProxyDigestAuthHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-handler-objects}@anchor{393a}@anchor{library/urllib request httphandler-objects}@anchor{393b}
@subsubsection HTTPHandler Objects


@geindex http_open() (méthode urllib.request.HTTPHandler)
@anchor{library/urllib request urllib request HTTPHandler http_open}@anchor{393c}
@deffn {Méthode} HTTPHandler.http_open (req)

Send an HTTP request, which can be either GET or POST, depending on
@code{req.has_data()}.
@end deffn

@node HTTPSHandler Objects,FileHandler Objects,HTTPHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request https-handler-objects}@anchor{393d}@anchor{library/urllib request httpshandler-objects}@anchor{393e}
@subsubsection HTTPSHandler Objects


@geindex https_open() (méthode urllib.request.HTTPSHandler)
@anchor{library/urllib request urllib request HTTPSHandler https_open}@anchor{393f}
@deffn {Méthode} HTTPSHandler.https_open (req)

Send an HTTPS request, which can be either GET or POST, depending on
@code{req.has_data()}.
@end deffn

@node FileHandler Objects,DataHandler Objects,HTTPSHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request file-handler-objects}@anchor{3940}@anchor{library/urllib request filehandler-objects}@anchor{3941}
@subsubsection FileHandler Objects


@geindex file_open() (méthode urllib.request.FileHandler)
@anchor{library/urllib request urllib request FileHandler file_open}@anchor{3942}
@deffn {Méthode} FileHandler.file_open (req)

Open the file locally, if there is no host name, or the host name is
@code{'localhost'}.


Modifié dans la version 3.2: This method is applicable only for local hostnames.  When a remote
hostname is given, a @ref{38e1,,URLError} is raised.

@end deffn

@node DataHandler Objects,FTPHandler Objects,FileHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request data-handler-objects}@anchor{3943}@anchor{library/urllib request datahandler-objects}@anchor{3944}
@subsubsection DataHandler Objects


@geindex data_open() (méthode urllib.request.DataHandler)
@anchor{library/urllib request urllib request DataHandler data_open}@anchor{3945}
@deffn {Méthode} DataHandler.data_open (req)

Read a data URL. This kind of URL contains the content encoded in the URL
itself. The data URL syntax is specified in 
@geindex RFC; RFC 2397
RFC 2397@footnote{https://datatracker.ietf.org/doc/html/rfc2397.html}. This implementation
ignores white spaces in base64 encoded data URLs so the URL may be wrapped
in whatever source file it comes from. But even though some browsers don't
mind about a missing padding at the end of a base64 encoded data URL, this
implementation will raise a @ref{1ff,,ValueError} in that case.
@end deffn

@node FTPHandler Objects,CacheFTPHandler Objects,DataHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request ftp-handler-objects}@anchor{3946}@anchor{library/urllib request ftphandler-objects}@anchor{3947}
@subsubsection FTPHandler Objects


@geindex ftp_open() (méthode urllib.request.FTPHandler)
@anchor{library/urllib request urllib request FTPHandler ftp_open}@anchor{3948}
@deffn {Méthode} FTPHandler.ftp_open (req)

Open the FTP file indicated by `req'. The login is always done with empty
username and password.
@end deffn

@node CacheFTPHandler Objects,UnknownHandler Objects,FTPHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request cacheftp-handler-objects}@anchor{3949}@anchor{library/urllib request cacheftphandler-objects}@anchor{394a}
@subsubsection CacheFTPHandler Objects


@ref{16b3,,CacheFTPHandler} objects are @ref{38ea,,FTPHandler} objects with the
following additional methods:

@geindex setTimeout() (méthode urllib.request.CacheFTPHandler)
@anchor{library/urllib request urllib request CacheFTPHandler setTimeout}@anchor{394b}
@deffn {Méthode} CacheFTPHandler.setTimeout (t)

Set timeout of connections to `t' seconds.
@end deffn

@geindex setMaxConns() (méthode urllib.request.CacheFTPHandler)
@anchor{library/urllib request urllib request CacheFTPHandler setMaxConns}@anchor{394c}
@deffn {Méthode} CacheFTPHandler.setMaxConns (m)

Set maximum number of cached connections to `m'.
@end deffn

@node UnknownHandler Objects,HTTPErrorProcessor Objects,CacheFTPHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request unknown-handler-objects}@anchor{394d}@anchor{library/urllib request unknownhandler-objects}@anchor{394e}
@subsubsection UnknownHandler Objects


@geindex unknown_open() (méthode urllib.request.UnknownHandler)
@anchor{library/urllib request urllib request UnknownHandler unknown_open}@anchor{394f}
@deffn {Méthode} UnknownHandler.unknown_open ()

Raise a @ref{38e1,,URLError} exception.
@end deffn

@node HTTPErrorProcessor Objects,Exemples<25>,UnknownHandler Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request http-error-processor-objects}@anchor{3950}@anchor{library/urllib request httperrorprocessor-objects}@anchor{3951}
@subsubsection HTTPErrorProcessor Objects


@geindex http_response() (méthode urllib.request.HTTPErrorProcessor)
@anchor{library/urllib request urllib request HTTPErrorProcessor http_response}@anchor{3952}
@deffn {Méthode} HTTPErrorProcessor.http_response (request, response)

Process HTTP error responses.

For 200 error codes, the response object is returned immediately.

For non-200 error codes, this simply passes the job on to the
@code{http_error_<type>()} handler methods, via @ref{390b,,OpenerDirector.error()}.
Eventually, @ref{38e8,,HTTPDefaultErrorHandler} will raise an
@ref{fc9,,HTTPError} if no other handler handles the error.
@end deffn

@geindex https_response() (méthode urllib.request.HTTPErrorProcessor)
@anchor{library/urllib request urllib request HTTPErrorProcessor https_response}@anchor{3953}
@deffn {Méthode} HTTPErrorProcessor.https_response (request, response)

Process HTTPS error responses.

The behavior is same as @ref{3952,,http_response()}.
@end deffn

@node Exemples<25>,Legacy interface,HTTPErrorProcessor Objects,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request examples}@anchor{3954}@anchor{library/urllib request urllib-request-examples}@anchor{3955}
@subsubsection Exemples


In addition to the examples below, more examples are given in
@ref{3956,,Guide pratique ; récupérer des ressources web en utilisant le module urllib}.

This example gets the python.org main page and displays the first 300 bytes of
it.

@example
>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '
@end example

Note that urlopen returns a bytes object.  This is because there is no way
for urlopen to automatically determine the encoding of the byte stream
it receives from the HTTP server. In general, a program will decode
the returned bytes object to string once it determines or guesses
the appropriate encoding.

The following W3C document, @indicateurl{https://www.w3.org/International/O-charset}, lists
the various ways in which an (X)HTML or an XML document could have specified its
encoding information.

As the python.org website uses `utf-8' encoding as specified in its meta tag, we
will use the same for decoding the bytes object.

@example
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm
@end example

It is also possible to achieve the same result without using the
@ref{5be,,context manager} approach.

@example
>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm
@end example

In the following example, we are sending a data-stream to the stdin of a CGI
and reading the data it returns to us. Note that this example will only work
when the Python installation supports SSL.

@example
>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"
@end example

The code for the sample CGI used in the above example is:

@example
#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)
@end example

Here is an example of doing a @code{PUT} request using @ref{fc3,,Request}:

@example
import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)
@end example

Use of Basic HTTP Authentication:

@example
import urllib.request
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')
@end example

@ref{38e5,,build_opener()} provides many handlers by default, including a
@ref{195e,,ProxyHandler}.  By default, @ref{195e,,ProxyHandler} uses the environment
variables named @code{<scheme>_proxy}, where @code{<scheme>} is the URL scheme
involved.  For example, the @code{http_proxy} environment variable is read to
obtain the HTTP proxy's URL.

This example replaces the default @ref{195e,,ProxyHandler} with one that uses
programmatically supplied proxy URLs, and adds proxy authorization support with
@ref{38f4,,ProxyBasicAuthHandler}.

@example
proxy_handler = urllib.request.ProxyHandler(@{'http': 'http://www.example.com:3128/'@})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')
@end example

Adding HTTP headers:

Use the `headers' argument to the @ref{fc3,,Request} constructor, or:

@example
import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)
@end example

@ref{38e2,,OpenerDirector} automatically adds a @code{User-Agent} header to
every @ref{fc3,,Request}.  To change this:

@example
import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')
@end example

Also, remember that a few standard headers (@code{Content-Length},
@code{Content-Type} and @code{Host})
are added when the @ref{fc3,,Request} is passed to @ref{290,,urlopen()} (or
@ref{fc7,,OpenerDirector.open()}).
@anchor{library/urllib request urllib-examples}@anchor{3957}
Here is an example session that uses the @code{GET} method to retrieve a URL
containing parameters:

@example
>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode(@{'spam': 1, 'eggs': 2, 'bacon': 0@})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...
@end example

The following example uses the @code{POST} method instead. Note that params output
from urlencode is encoded to bytes before it is sent to urlopen as data:

@example
>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode(@{'spam': 1, 'eggs': 2, 'bacon': 0@})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...
@end example

The following example uses an explicitly specified HTTP proxy, overriding
environment settings:

@example
>>> import urllib.request
>>> proxies = @{'http': 'http://proxy.example.com:8080/'@}
>>> opener = urllib.request.FancyURLopener(proxies)
>>> with opener.open("http://www.python.org") as f:
...     f.read().decode('utf-8')
...
@end example

The following example uses no proxies at all, overriding environment settings:

@example
>>> import urllib.request
>>> opener = urllib.request.FancyURLopener(@{@})
>>> with opener.open("http://www.python.org/") as f:
...     f.read().decode('utf-8')
...
@end example

@node Legacy interface,urllib request Restrictions,Exemples<25>,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request legacy-interface}@anchor{3958}
@subsubsection Legacy interface


The following functions and classes are ported from the Python 2 module
@code{urllib} (as opposed to @code{urllib2}).  They might become deprecated at
some point in the future.

@geindex urlretrieve() (dans le module urllib.request)
@anchor{library/urllib request urllib request urlretrieve}@anchor{3959}
@deffn {Fonction} urllib.request.urlretrieve (url, filename=None, reporthook=None, data=None)

Copy a network object denoted by a URL to a local file. If the URL
points to a local file, the object will not be copied unless filename is supplied.
Return a tuple @code{(filename, headers)} where `filename' is the
local file name under which the object can be found, and `headers' is whatever
the @code{info()} method of the object returned by @ref{290,,urlopen()} returned (for
a remote object). Exceptions are the same as for @ref{290,,urlopen()}.

The second argument, if present, specifies the file location to copy to (if
absent, the location will be a tempfile with a generated name). The third
argument, if present, is a callable that will be called once on
establishment of the network connection and once after each block read
thereafter.  The callable will be passed three arguments; a count of blocks
transferred so far, a block size in bytes, and the total size of the file.  The
third argument may be @code{-1} on older FTP servers which do not return a file
size in response to a retrieval request.

The following example illustrates the most common usage scenario:

@example
>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()
@end example

If the `url' uses the @code{http:} scheme identifier, the optional `data'
argument may be given to specify a @code{POST} request (normally the request
type is @code{GET}).  The `data' argument must be a bytes object in standard
@code{application/x-www-form-urlencoded} format; see the
@ref{e7e,,urllib.parse.urlencode()} function.

@ref{3959,,urlretrieve()} will raise @ref{395a,,ContentTooShortError} when it detects that
the amount of data available  was less than the expected amount (which is the
size reported by a  `Content-Length' header). This can occur, for example, when
the  download is interrupted.

The `Content-Length' is treated as a lower bound: if there's more data  to read,
urlretrieve reads more data, but if less data is available,  it raises the
exception.

You can still retrieve the downloaded data in this case, it is stored in the
@code{content} attribute of the exception instance.

If no `Content-Length' header was supplied, urlretrieve can not check the size
of the data it has downloaded, and just returns it.  In this case you just have
to assume that the download was successful.
@end deffn

@geindex urlcleanup() (dans le module urllib.request)
@anchor{library/urllib request urllib request urlcleanup}@anchor{1965}
@deffn {Fonction} urllib.request.urlcleanup ()

Cleans up temporary files that may have been left behind by previous
calls to @ref{3959,,urlretrieve()}.
@end deffn

@geindex URLopener (classe dans urllib.request)
@anchor{library/urllib request urllib request URLopener}@anchor{303}
@deffn {Classe} urllib.request.URLopener (proxies=None, **x509)


Obsolète depuis la version 3.3.


Base class for opening and reading URLs.  Unless you need to support opening
objects using schemes other than @code{http:}, @code{ftp:}, or @code{file:},
you probably want to use @ref{304,,FancyURLopener}.

By default, the @ref{303,,URLopener} class sends a @code{User-Agent} header
of @code{urllib/VVV}, where `VVV' is the @ref{107,,urllib} version number.
Applications can define their own @code{User-Agent} header by subclassing
@ref{303,,URLopener} or @ref{304,,FancyURLopener} and setting the class attribute
@ref{395b,,version} to an appropriate string value in the subclass definition.

The optional `proxies' parameter should be a dictionary mapping scheme names to
proxy URLs, where an empty dictionary turns proxies off completely.  Its default
value is @code{None}, in which case environmental proxy settings will be used if
present, as discussed in the definition of @ref{290,,urlopen()}, above.

Additional keyword parameters, collected in `x509', may be used for
authentication of the client when using the @code{https:} scheme.  The keywords
`key_file' and `cert_file' are supported to provide an  SSL key and certificate;
both are needed to support client authentication.

@ref{303,,URLopener} objects will raise an @ref{40d,,OSError} exception if the server
returns an error code.

@geindex open() (méthode urllib.request.URLopener)
@anchor{library/urllib request urllib request URLopener open}@anchor{395c}
@deffn {Méthode} open (fullurl, data=None)

Open `fullurl' using the appropriate protocol.  This method sets up cache and
proxy information, then calls the appropriate open method with its input
arguments.  If the scheme is not recognized, @ref{395d,,open_unknown()} is called.
The `data' argument has the same meaning as the `data' argument of
@ref{290,,urlopen()}.

This method always quotes `fullurl' using @ref{b91,,quote()}.
@end deffn

@geindex open_unknown() (méthode urllib.request.URLopener)
@anchor{library/urllib request urllib request URLopener open_unknown}@anchor{395d}
@deffn {Méthode} open_unknown (fullurl, data=None)

Overridable interface to open unknown URL types.
@end deffn

@geindex retrieve() (méthode urllib.request.URLopener)
@anchor{library/urllib request urllib request URLopener retrieve}@anchor{197c}
@deffn {Méthode} retrieve (url, filename=None, reporthook=None, data=None)

Retrieves the contents of `url' and places it in `filename'.  The return value
is a tuple consisting of a local filename and either an
@ref{279,,email.message.Message} object containing the response headers (for remote
URLs) or @code{None} (for local URLs).  The caller must then open and read the
contents of `filename'.  If `filename' is not given and the URL refers to a
local file, the input filename is returned.  If the URL is non-local and
`filename' is not given, the filename is the output of @ref{181b,,tempfile.mktemp()}
with a suffix that matches the suffix of the last path component of the input
URL.  If `reporthook' is given, it must be a function accepting three numeric
parameters: A chunk number, the maximum size chunks are read in and the total size of the download
(-1 if unknown).  It will be called once at the start and after each chunk of data is read from the
network.  `reporthook' is ignored for local URLs.

If the `url' uses the @code{http:} scheme identifier, the optional `data'
argument may be given to specify a @code{POST} request (normally the request type
is @code{GET}).  The `data' argument must in standard
@code{application/x-www-form-urlencoded} format; see the
@ref{e7e,,urllib.parse.urlencode()} function.
@end deffn

@geindex version (attribut urllib.request.URLopener)
@anchor{library/urllib request urllib request URLopener version}@anchor{395b}
@deffn {Attribut} version

Variable that specifies the user agent of the opener object.  To get
@ref{107,,urllib} to tell servers that it is a particular user agent, set this in a
subclass as a class variable or in the constructor before calling the base
constructor.
@end deffn
@end deffn

@geindex FancyURLopener (classe dans urllib.request)
@anchor{library/urllib request urllib request FancyURLopener}@anchor{304}
@deffn {Classe} urllib.request.FancyURLopener (...)


Obsolète depuis la version 3.3.


@ref{304,,FancyURLopener} subclasses @ref{303,,URLopener} providing default handling
for the following HTTP response codes: 301, 302, 303, 307 and 401.  For the 30x
response codes listed above, the @code{Location} header is used to fetch
the actual URL.  For 401 response codes (authentication required), basic HTTP
authentication is performed.  For the 30x response codes, recursion is bounded
by the value of the `maxtries' attribute, which defaults to 10.

For all other response codes, the method @ref{3913,,http_error_default()} is called
which you can override in subclasses to handle the error appropriately.

@cartouche
@quotation Note 
According to the letter of 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}, 301 and 302 responses to POST requests
must not be automatically redirected without confirmation by the user.  In
reality, browsers do allow automatic redirection of these responses, changing
the POST to a GET, and @ref{107,,urllib} reproduces this behaviour.
@end quotation
@end cartouche

The parameters to the constructor are the same as those for @ref{303,,URLopener}.

@cartouche
@quotation Note 
When performing basic authentication, a @ref{304,,FancyURLopener} instance calls
its @ref{395e,,prompt_user_passwd()} method.  The default implementation asks the
users for the required information on the controlling terminal.  A subclass may
override this method to support more appropriate behavior if needed.
@end quotation
@end cartouche

The @ref{304,,FancyURLopener} class offers one additional method that should be
overloaded to provide the appropriate behavior:

@geindex prompt_user_passwd() (méthode urllib.request.FancyURLopener)
@anchor{library/urllib request urllib request FancyURLopener prompt_user_passwd}@anchor{395e}
@deffn {Méthode} prompt_user_passwd (host, realm)

Return information needed to authenticate the user at the given host in the
specified security realm.  The return value should be a tuple, @code{(user,
password)}, which can be used for basic authentication.

The implementation prompts for this information on the terminal; an application
should override this method to use an appropriate interaction model in the local
environment.
@end deffn
@end deffn

@node urllib request Restrictions,,Legacy interface,urllib request --- Extensible library for opening URLs
@anchor{library/urllib request urllib-request-restrictions}@anchor{395f}
@subsubsection @code{urllib.request} Restrictions


@geindex HTTP;protocol
@geindex FTP;protocol


@itemize *

@item 
Currently, only the following protocols are supported: HTTP (versions 0.9 and
1.0), FTP, local files, and data URLs.


Modifié dans la version 3.4: Added support for data URLs.


@item 
The caching feature of @ref{3959,,urlretrieve()} has been disabled until someone
finds the time to hack proper processing of Expiration time headers.

@item 
There should be a function to query whether a particular URL is in the cache.

@item 
For backward compatibility, if a URL appears to point to a local file but the
file can't be opened, the URL is re-interpreted using the FTP protocol.  This
can sometimes cause confusing error messages.

@item 
The @ref{290,,urlopen()} and @ref{3959,,urlretrieve()} functions can cause arbitrarily
long delays while waiting for a network connection to be set up.  This means
that it is difficult to build an interactive web client using these functions
without using threads.

@geindex HTML
@geindex HTTP;protocol

@item 
The data returned by @ref{290,,urlopen()} or @ref{3959,,urlretrieve()} is the raw data
returned by the server.  This may be binary data (such as an image), plain text
or (for example) HTML.  The HTTP protocol provides type information in the reply
header, which can be inspected by looking at the @code{Content-Type}
header.  If the returned data is HTML, you can use the module
@ref{6c,,html.parser} to parse it.

@geindex FTP

@item 
The code handling the FTP protocol cannot differentiate between a file and a
directory.  This can lead to unexpected behavior when attempting to read a URL
that points to a file that is not accessible.  If the URL ends in a @code{/}, it is
assumed to refer to a directory and will be handled accordingly.  But if an
attempt to read a file leads to a 550 error (meaning the URL cannot be found or
is not accessible, often for permission reasons), then the path is treated as a
directory in order to handle the case when a directory is specified by a URL but
the trailing @code{/} has been left off.  This can cause misleading results when
you try to fetch a file whose read permissions make it inaccessible; the FTP
code will try to read it, fail with a 550 error, and then perform a directory
listing for the unreadable file. If fine-grained control is needed, consider
using the @ref{5d,,ftplib} module, subclassing @ref{304,,FancyURLopener}, or changing
`_urlopener' to meet your needs.
@end itemize

@node urllib response --- Response classes used by urllib,urllib parse --- Parse URLs into components,urllib request --- Extensible library for opening URLs,Gestion des protocoles internet
@anchor{library/urllib request module-urllib response}@anchor{10b}@anchor{library/urllib request urllib-response-response-classes-used-by-urllib}@anchor{3960}
@subsection @code{urllib.response} --- Response classes used by urllib


@geindex module; urllib.response

The @ref{10b,,urllib.response} module defines functions and classes which define a
minimal file-like interface, including @code{read()} and @code{readline()}.
Functions defined by this module are used internally by the @ref{10a,,urllib.request} module.
The typical response object is a @ref{38df,,urllib.response.addinfourl} instance:

@geindex addinfourl (classe dans urllib.response)
@anchor{library/urllib request urllib response addinfourl}@anchor{38df}
@deffn {Classe} urllib.response.addinfourl

@geindex url (attribut urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl url}@anchor{3961}
@deffn {Attribut} url

L'URL de la ressource récupérée, utilisée habituellement pour déterminer si une redirection a été suivie.
@end deffn

@geindex headers (attribut urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl headers}@anchor{3962}
@deffn {Attribut} headers

Returns the headers of the response in the form of an @ref{278,,EmailMessage} instance.
@end deffn

@geindex status (attribut urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl status}@anchor{3963}
@deffn {Attribut} status


Ajouté dans la version 3.9.


Code d'état renvoyé par le serveur.
@end deffn

@geindex geturl() (méthode urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl geturl}@anchor{3964}
@deffn {Méthode} geturl ()


Obsolète depuis la version 3.9: Deprecated in favor of @ref{3961,,url}.

@end deffn

@geindex info() (méthode urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl info}@anchor{3965}
@deffn {Méthode} info ()


Obsolète depuis la version 3.9: Deprecated in favor of @ref{3962,,headers}.

@end deffn

@geindex code (attribut urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl code}@anchor{3966}
@deffn {Attribut} code


Obsolète depuis la version 3.9: Deprecated in favor of @ref{3963,,status}.

@end deffn

@geindex getcode() (méthode urllib.response.addinfourl)
@anchor{library/urllib request urllib response addinfourl getcode}@anchor{3967}
@deffn {Méthode} getcode ()


Obsolète depuis la version 3.9: Deprecated in favor of @ref{3963,,status}.

@end deffn
@end deffn

@node urllib parse --- Parse URLs into components,urllib error --- Exception classes raised by urllib request,urllib response --- Response classes used by urllib,Gestion des protocoles internet
@anchor{library/urllib parse doc}@anchor{3968}@anchor{library/urllib parse module-urllib parse}@anchor{109}@anchor{library/urllib parse urllib-parse-parse-urls-into-components}@anchor{3969}
@subsection @code{urllib.parse} --- Parse URLs into components


@geindex module; urllib.parse

`Code source :' Lib/urllib/parse.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/urllib/parse.py}

@geindex WWW
@geindex World Wide Web
@geindex URL
@geindex URL;parsing
@geindex relative;URL


__________________________________________________________________


This module defines a standard interface to break Uniform Resource Locator (URL)
strings up in components (addressing scheme, network location, path etc.), to
combine the components back into a URL string, and to convert a "relative URL"
to an absolute URL given a "base URL."

The module has been designed to match the internet RFC on Relative Uniform
Resource Locators. It supports the following URL schemes: @code{file}, @code{ftp},
@code{gopher}, @code{hdl}, @code{http}, @code{https}, @code{imap}, @code{itms-services}, @code{mailto}, @code{mms},
@code{news}, @code{nntp}, @code{prospero}, @code{rsync}, @code{rtsp}, @code{rtsps}, @code{rtspu},
@code{sftp}, @code{shttp}, @code{sip}, @code{sips}, @code{snews}, @code{svn}, @code{svn+ssh},
@code{telnet}, @code{wais}, @code{ws}, @code{wss}.

`Particularité de l'implémentation CPython :' The inclusion of the @code{itms-services} URL scheme can prevent an app from
passing Apple's App Store review process for the macOS and iOS App Stores.
Handling for the @code{itms-services} scheme is always removed on iOS; on
macOS, it `may' be removed if CPython has been built with the
@ref{157b,,--with-app-store-compliance} option.

The @ref{109,,urllib.parse} module defines functions that fall into two broad
categories: URL parsing and URL quoting. These are covered in detail in
the following sections.

This module's functions use the deprecated term @code{netloc} (or @code{net_loc}),
which was introduced in 
@geindex RFC; RFC 1808
RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html}. However, this term has been obsoleted by
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}, which introduced the term @code{authority} as its replacement.
The use of @code{netloc} is continued for backward compatibility.

@menu
* URL Parsing:: 
* URL parsing security:: 
* Parsing ASCII Encoded Bytes:: 
* Structured Parse Results:: 
* URL Quoting:: 

@end menu

@node URL Parsing,URL parsing security,,urllib parse --- Parse URLs into components
@anchor{library/urllib parse url-parsing}@anchor{396a}
@subsubsection URL Parsing


The URL parsing functions focus on splitting a URL string into its components,
or on combining URL components into a URL string.

@geindex urlparse() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urlparse}@anchor{302}
@deffn {Fonction} urllib.parse.urlparse (urlstring, scheme='@w{'}, allow_fragments=True)

Parse a URL into six components, returning a 6-item @ref{639,,named tuple}.  This
corresponds to the general structure of a URL:
@code{scheme://netloc/path;parameters?query#fragment}.
Each tuple item is a string, possibly empty. The components are not broken up
into smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
result, except for a leading slash in the `path' component, which is retained if
present.  For example:

@example
>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='@w{'},
            query='query', fragment='fragment')
>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='@w{'},
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'
@end example

Following the syntax specifications in 
@geindex RFC; RFC 1808
RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html}, urlparse recognizes
a netloc only if it is properly introduced by '//'.  Otherwise the
input is presumed to be a relative URL and thus to start with
a path component.

@example
>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='@w{'}, netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='@w{'}, netloc='@w{'}, path='www.cwi.nl/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
>>> urlparse('help/Python.html')
ParseResult(scheme='@w{'}, netloc='@w{'}, path='help/Python.html', params='@w{'},
            query='@w{'}, fragment='@w{'})
@end example

The `scheme' argument gives the default addressing scheme, to be
used only if the URL does not specify one.  It should be the same type
(text or bytes) as `urlstring', except that the default value @code{'@w{'}} is
always allowed, and is automatically converted to @code{b'@w{'}} if appropriate.

If the `allow_fragments' argument is false, fragment identifiers are not
recognized.  Instead, they are parsed as part of the path, parameters
or query component, and @code{fragment} is set to the empty string in
the return value.

The return value is a @ref{639,,named tuple}, which means that its items can
be accessed by index or as named attributes, which are:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Index

@tab

Valeur

@tab

Value if not present

@item

@code{scheme}

@tab

0

@tab

URL scheme specifier

@tab

`scheme' parameter

@item

@code{netloc}

@tab

1

@tab

Network location part

@tab

empty string

@item

@code{path}

@tab

2

@tab

Hierarchical path

@tab

empty string

@item

@code{params}

@tab

3

@tab

Parameters for last
path element

@tab

empty string

@item

@code{query}

@tab

4

@tab

Query component

@tab

empty string

@item

@code{fragment}

@tab

5

@tab

Fragment identifier

@tab

empty string

@item

@code{username}

@tab

@tab

User name

@tab

@ref{660,,None}

@item

@code{password}

@tab

@tab

Password

@tab

@ref{660,,None}

@item

@code{hostname}

@tab

@tab

Host name (lower case)

@tab

@ref{660,,None}

@item

@code{port}

@tab

@tab

Port number as integer,
if present

@tab

@ref{660,,None}

@end multitable


Reading the @code{port} attribute will raise a @ref{1ff,,ValueError} if
an invalid port is specified in the URL.  See section
@ref{396b,,Structured Parse Results} for more information on the result object.

Unmatched square brackets in the @code{netloc} attribute will raise a
@ref{1ff,,ValueError}.

Characters in the @code{netloc} attribute that decompose under NFKC
normalization (as used by the IDNA encoding) into any of @code{/}, @code{?},
@code{#}, @code{@@}, or @code{:} will raise a @ref{1ff,,ValueError}. If the URL is
decomposed before parsing, no error will be raised.

As is the case with all named tuples, the subclass has a few additional methods
and attributes that are particularly useful. One such method is @code{_replace()}.
The @code{_replace()} method will return a new ParseResult object replacing specified
fields with new values.

@example
>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='@w{'}, netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='@w{'}, query='@w{'}, fragment='@w{'})
@end example

@cartouche
@quotation Avertissement 
@ref{302,,urlparse()} does not perform validation.  See @ref{396c,,URL parsing security} for details.
@end quotation
@end cartouche


Modifié dans la version 3.2: Added IPv6 URL parsing capabilities.



Modifié dans la version 3.3: The fragment is now parsed for all URL schemes (unless `allow_fragments' is
false), in accordance with 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}.  Previously, an allowlist of
schemes that support fragments existed.



Modifié dans la version 3.6: Out-of-range port numbers now raise @ref{1ff,,ValueError}, instead of
returning @ref{660,,None}.



Modifié dans la version 3.8: Characters that affect netloc parsing under NFKC normalization will
now raise @ref{1ff,,ValueError}.

@end deffn

@geindex parse_qs() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse parse_qs}@anchor{277}
@deffn {Fonction} urllib.parse.parse_qs (qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Parse a query string given as a string argument (data of type
@code{application/x-www-form-urlencoded}).  Data are returned as a
dictionary.  The dictionary keys are the unique query variable names and the
values are lists of values for each name.

The optional argument `keep_blank_values' is a flag indicating whether blank
values in percent-encoded queries should be treated as blank strings. A true value
indicates that blanks should be retained as  blank strings.  The default false
value indicates that blank values are to be ignored and treated as if they were
not included.

The optional argument `strict_parsing' is a flag indicating what to do with
parsing errors.  If false (the default), errors are silently ignored.  If true,
errors raise a @ref{1ff,,ValueError} exception.

The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{8c3,,bytes.decode()} method.

The optional argument `max_num_fields' is the maximum number of fields to
read. If set, then throws a @ref{1ff,,ValueError} if there are more than
`max_num_fields' fields read.

The optional argument `separator' is the symbol to use for separating the
query arguments. It defaults to @code{&}.

Use the @ref{e7e,,urllib.parse.urlencode()} function (with the @code{doseq}
parameter set to @code{True}) to convert such dictionaries into query
strings.


Modifié dans la version 3.2: Add `encoding' and `errors' parameters.



Modifié dans la version 3.8: Added `max_num_fields' parameter.



Modifié dans la version 3.10: Added `separator' parameter with the default value of @code{&}. Python
versions earlier than Python 3.10 allowed using both @code{;} and @code{&} as
query parameter separator. This has been changed to allow only a single
separator key, with @code{&} as the default separator.

@end deffn

@geindex parse_qsl() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse parse_qsl}@anchor{276}
@deffn {Fonction} urllib.parse.parse_qsl (qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Parse a query string given as a string argument (data of type
@code{application/x-www-form-urlencoded}).  Data are returned as a list of
name, value pairs.

The optional argument `keep_blank_values' is a flag indicating whether blank
values in percent-encoded queries should be treated as blank strings. A true value
indicates that blanks should be retained as  blank strings.  The default false
value indicates that blank values are to be ignored and treated as if they were
not included.

The optional argument `strict_parsing' is a flag indicating what to do with
parsing errors.  If false (the default), errors are silently ignored.  If true,
errors raise a @ref{1ff,,ValueError} exception.

The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{8c3,,bytes.decode()} method.

The optional argument `max_num_fields' is the maximum number of fields to
read. If set, then throws a @ref{1ff,,ValueError} if there are more than
`max_num_fields' fields read.

The optional argument `separator' is the symbol to use for separating the
query arguments. It defaults to @code{&}.

Use the @ref{e7e,,urllib.parse.urlencode()} function to convert such lists of pairs into
query strings.


Modifié dans la version 3.2: Add `encoding' and `errors' parameters.



Modifié dans la version 3.8: Added `max_num_fields' parameter.



Modifié dans la version 3.10: Added `separator' parameter with the default value of @code{&}. Python
versions earlier than Python 3.10 allowed using both @code{;} and @code{&} as
query parameter separator. This has been changed to allow only a single
separator key, with @code{&} as the default separator.

@end deffn

@geindex urlunparse() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urlunparse}@anchor{155f}
@deffn {Fonction} urllib.parse.urlunparse (parts)

Construct a URL from a tuple as returned by @code{urlparse()}. The `parts'
argument can be any six-item iterable. This may result in a slightly
different, but equivalent URL, if the URL that was parsed originally had
unnecessary delimiters (for example, a @code{?} with an empty query; the RFC
states that these are equivalent).
@end deffn

@geindex urlsplit() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urlsplit}@anchor{d2d}
@deffn {Fonction} urllib.parse.urlsplit (urlstring, scheme='@w{'}, allow_fragments=True)

This is similar to @ref{302,,urlparse()}, but does not split the params from the URL.
This should generally be used instead of @ref{302,,urlparse()} if the more recent URL
syntax allowing parameters to be applied to each segment of the `path' portion
of the URL (see 
@geindex RFC; RFC 2396
RFC 2396@footnote{https://datatracker.ietf.org/doc/html/rfc2396.html}) is wanted.  A separate function is needed to
separate the path segments and parameters.  This function returns a 5-item
@ref{639,,named tuple}:

@example
(addressing scheme, network location, path, query, fragment identifier).
@end example

The return value is a @ref{639,,named tuple}, its items can be accessed by index
or as named attributes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Index

@tab

Valeur

@tab

Value if not present

@item

@code{scheme}

@tab

0

@tab

URL scheme specifier

@tab

`scheme' parameter

@item

@code{netloc}

@tab

1

@tab

Network location part

@tab

empty string

@item

@code{path}

@tab

2

@tab

Hierarchical path

@tab

empty string

@item

@code{query}

@tab

3

@tab

Query component

@tab

empty string

@item

@code{fragment}

@tab

4

@tab

Fragment identifier

@tab

empty string

@item

@code{username}

@tab

@tab

User name

@tab

@ref{660,,None}

@item

@code{password}

@tab

@tab

Password

@tab

@ref{660,,None}

@item

@code{hostname}

@tab

@tab

Host name (lower case)

@tab

@ref{660,,None}

@item

@code{port}

@tab

@tab

Port number as integer,
if present

@tab

@ref{660,,None}

@end multitable


Reading the @code{port} attribute will raise a @ref{1ff,,ValueError} if
an invalid port is specified in the URL.  See section
@ref{396b,,Structured Parse Results} for more information on the result object.

Unmatched square brackets in the @code{netloc} attribute will raise a
@ref{1ff,,ValueError}.

Characters in the @code{netloc} attribute that decompose under NFKC
normalization (as used by the IDNA encoding) into any of @code{/}, @code{?},
@code{#}, @code{@@}, or @code{:} will raise a @ref{1ff,,ValueError}. If the URL is
decomposed before parsing, no error will be raised.

Following some of the WHATWG spec@footnote{https://url.spec.whatwg.org/#concept-basic-url-parser} that updates RFC 3986, leading C0
control and space characters are stripped from the URL. @code{\n},
@code{\r} and tab @code{\t} characters are removed from the URL at any position.

@cartouche
@quotation Avertissement 
@ref{d2d,,urlsplit()} does not perform validation.  See @ref{396c,,URL parsing security} for details.
@end quotation
@end cartouche


Modifié dans la version 3.6: Out-of-range port numbers now raise @ref{1ff,,ValueError}, instead of
returning @ref{660,,None}.



Modifié dans la version 3.8: Characters that affect netloc parsing under NFKC normalization will
now raise @ref{1ff,,ValueError}.



Modifié dans la version 3.10: ASCII newline and tab characters are stripped from the URL.



Modifié dans la version 3.12: Leading WHATWG C0 control and space characters are stripped from the URL.

@end deffn

@geindex urlunsplit() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urlunsplit}@anchor{155e}
@deffn {Fonction} urllib.parse.urlunsplit (parts)

Combine the elements of a tuple as returned by @ref{d2d,,urlsplit()} into a
complete URL as a string. The `parts' argument can be any five-item
iterable. This may result in a slightly different, but equivalent URL, if the
URL that was parsed originally had unnecessary delimiters (for example, a ?
with an empty query; the RFC states that these are equivalent).
@end deffn

@geindex urljoin() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urljoin}@anchor{e7f}
@deffn {Fonction} urllib.parse.urljoin (base, url, allow_fragments=True)

Construct a full ("absolute") URL by combining a "base URL" (`base') with
another URL (`url').  Informally, this uses components of the base URL, in
particular the addressing scheme, the network location and (part of) the
path, to provide missing components in the relative URL.  For example:

@example
>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'
@end example

The `allow_fragments' argument has the same meaning and default as for
@ref{302,,urlparse()}.

@cartouche
@quotation Note 
If `url' is an absolute URL (that is, it starts with @code{//} or @code{scheme://}),
the `url''s hostname and/or scheme will be present in the result.  For example:

@example
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'
@end example

If you do not want that behavior, preprocess the `url' with @ref{d2d,,urlsplit()} and
@ref{155e,,urlunsplit()}, removing possible `scheme' and `netloc' parts.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Because an absolute URL may be passed as the @code{url} parameter, it is
generally `not secure' to use @code{urljoin} with an attacker-controlled
@code{url}. For example in,
@code{urljoin("https://website.com/users/", username)}, if @code{username} can
contain an absolute URL, the result of @code{urljoin} will be the absolute
URL.
@end quotation
@end cartouche


Modifié dans la version 3.5: Behavior updated to match the semantics defined in 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}.

@end deffn

@geindex urldefrag() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urldefrag}@anchor{1226}
@deffn {Fonction} urllib.parse.urldefrag (url)

If `url' contains a fragment identifier, return a modified version of `url'
with no fragment identifier, and the fragment identifier as a separate
string.  If there is no fragment identifier in `url', return `url' unmodified
and an empty string.

The return value is a @ref{639,,named tuple}, its items can be accessed by index
or as named attributes:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Index

@tab

Valeur

@tab

Value if not present

@item

@code{url}

@tab

0

@tab

URL with no fragment

@tab

empty string

@item

@code{fragment}

@tab

1

@tab

Fragment identifier

@tab

empty string

@end multitable


See section @ref{396b,,Structured Parse Results} for more information on the result
object.


Modifié dans la version 3.2: Result is a structured object rather than a simple 2-tuple.

@end deffn

@geindex unwrap() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse unwrap}@anchor{396d}
@deffn {Fonction} urllib.parse.unwrap (url)

Extract the url from a wrapped URL (that is, a string formatted as
@code{<URL:scheme://host/path>}, @code{<scheme://host/path>}, @code{URL:scheme://host/path}
or @code{scheme://host/path}). If `url' is not a wrapped URL, it is returned
without changes.
@end deffn

@node URL parsing security,Parsing ASCII Encoded Bytes,URL Parsing,urllib parse --- Parse URLs into components
@anchor{library/urllib parse id1}@anchor{396e}@anchor{library/urllib parse url-parsing-security}@anchor{396c}
@subsubsection URL parsing security


The @ref{d2d,,urlsplit()} and @ref{302,,urlparse()} APIs do not perform `validation' of
inputs.  They may not raise errors on inputs that other applications consider
invalid.  They may also succeed on some inputs that might not be considered
URLs elsewhere.  Their purpose is for practical functionality rather than
purity.

Instead of raising an exception on unusual input, they may instead return some
component parts as empty strings. Or components may contain more than perhaps
they should.

We recommend that users of these APIs where the values may be used anywhere
with security implications code defensively. Do some verification within your
code before trusting a returned component part.  Does that @code{scheme} make
sense?  Is that a sensible @code{path}?  Is there anything strange about that
@code{hostname}?  etc.

What constitutes a URL is not universally well defined.  Different applications
have different needs and desired constraints.  For instance the living WHATWG spec@footnote{https://url.spec.whatwg.org/#concept-basic-url-parser} describes what user facing web clients such as a web browser require.
While 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html} is more general.  These functions incorporate some aspects of
both, but cannot be claimed compliant with either.  The APIs and existing user
code with expectations on specific behaviors predate both standards leading us
to be very cautious about making API behavior changes.

@node Parsing ASCII Encoded Bytes,Structured Parse Results,URL parsing security,urllib parse --- Parse URLs into components
@anchor{library/urllib parse id2}@anchor{396f}@anchor{library/urllib parse parsing-ascii-encoded-bytes}@anchor{1228}
@subsubsection Parsing ASCII Encoded Bytes


The URL parsing functions were originally designed to operate on character
strings only. In practice, it is useful to be able to manipulate properly
quoted and encoded URLs as sequences of ASCII bytes. Accordingly, the
URL parsing functions in this module all operate on @ref{1bd,,bytes} and
@ref{528,,bytearray} objects in addition to @ref{435,,str} objects.

If @ref{435,,str} data is passed in, the result will also contain only
@ref{435,,str} data. If @ref{1bd,,bytes} or @ref{528,,bytearray} data is
passed in, the result will contain only @ref{1bd,,bytes} data.

Attempting to mix @ref{435,,str} data with @ref{1bd,,bytes} or
@ref{528,,bytearray} in a single function call will result in a
@ref{522,,TypeError} being raised, while attempting to pass in non-ASCII
byte values will trigger @ref{a01,,UnicodeDecodeError}.

To support easier conversion of result objects between @ref{435,,str} and
@ref{1bd,,bytes}, all return values from URL parsing functions provide
either an @code{encode()} method (when the result contains @ref{435,,str}
data) or a @code{decode()} method (when the result contains @ref{1bd,,bytes}
data). The signatures of these methods match those of the corresponding
@ref{435,,str} and @ref{1bd,,bytes} methods (except that the default encoding
is @code{'ascii'} rather than @code{'utf-8'}). Each produces a value of a
corresponding type that contains either @ref{1bd,,bytes} data (for
@code{encode()} methods) or @ref{435,,str} data (for
@code{decode()} methods).

Applications that need to operate on potentially improperly quoted URLs
that may contain non-ASCII data will need to do their own decoding from
bytes to characters before invoking the URL parsing methods.

The behaviour described in this section applies only to the URL parsing
functions. The URL quoting functions use their own rules when producing
or consuming byte sequences as detailed in the documentation of the
individual URL quoting functions.


Modifié dans la version 3.2: URL parsing functions now accept ASCII encoded byte sequences


@node Structured Parse Results,URL Quoting,Parsing ASCII Encoded Bytes,urllib parse --- Parse URLs into components
@anchor{library/urllib parse structured-parse-results}@anchor{3970}@anchor{library/urllib parse urlparse-result-object}@anchor{396b}
@subsubsection Structured Parse Results


The result objects from the @ref{302,,urlparse()}, @ref{d2d,,urlsplit()}  and
@ref{1226,,urldefrag()} functions are subclasses of the @ref{366,,tuple} type.
These subclasses add the attributes listed in the documentation for
those functions, the encoding and decoding support described in the
previous section, as well as an additional method:

@geindex geturl() (méthode urllib.parse.urllib.parse.SplitResult)
@anchor{library/urllib parse urllib parse urllib parse SplitResult geturl}@anchor{3971}
@deffn {Méthode} urllib.parse.SplitResult.geturl ()

Return the re-combined version of the original URL as a string. This may
differ from the original URL in that the scheme may be normalized to lower
case and empty components may be dropped. Specifically, empty parameters,
queries, and fragment identifiers will be removed.

For @ref{1226,,urldefrag()} results, only empty fragment identifiers will be removed.
For @ref{d2d,,urlsplit()} and @ref{302,,urlparse()} results, all noted changes will be
made to the URL returned by this method.

The result of this method remains unchanged if passed back through the original
parsing function:

@example
>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'
@end example
@end deffn

The following classes provide the implementations of the structured parse
results when operating on @ref{435,,str} objects:

@geindex DefragResult (classe dans urllib.parse)
@anchor{library/urllib parse urllib parse DefragResult}@anchor{3972}
@deffn {Classe} urllib.parse.DefragResult (url, fragment)

Concrete class for @ref{1226,,urldefrag()} results containing @ref{435,,str}
data. The @code{encode()} method returns a @ref{3973,,DefragResultBytes}
instance.


Ajouté dans la version 3.2.

@end deffn

@geindex ParseResult (classe dans urllib.parse)
@anchor{library/urllib parse urllib parse ParseResult}@anchor{3974}
@deffn {Classe} urllib.parse.ParseResult (scheme, netloc, path, params, query, fragment)

Concrete class for @ref{302,,urlparse()} results containing @ref{435,,str}
data. The @code{encode()} method returns a @ref{3975,,ParseResultBytes}
instance.
@end deffn

@geindex SplitResult (classe dans urllib.parse)
@anchor{library/urllib parse urllib parse SplitResult}@anchor{3976}
@deffn {Classe} urllib.parse.SplitResult (scheme, netloc, path, query, fragment)

Concrete class for @ref{d2d,,urlsplit()} results containing @ref{435,,str}
data. The @code{encode()} method returns a @ref{3977,,SplitResultBytes}
instance.
@end deffn

The following classes provide the implementations of the parse results when
operating on @ref{1bd,,bytes} or @ref{528,,bytearray} objects:

@geindex DefragResultBytes (classe dans urllib.parse)
@anchor{library/urllib parse urllib parse DefragResultBytes}@anchor{3973}
@deffn {Classe} urllib.parse.DefragResultBytes (url, fragment)

Concrete class for @ref{1226,,urldefrag()} results containing @ref{1bd,,bytes}
data. The @code{decode()} method returns a @ref{3972,,DefragResult}
instance.


Ajouté dans la version 3.2.

@end deffn

@geindex ParseResultBytes (classe dans urllib.parse)
@anchor{library/urllib parse urllib parse ParseResultBytes}@anchor{3975}
@deffn {Classe} urllib.parse.ParseResultBytes (scheme, netloc, path, params, query, fragment)

Concrete class for @ref{302,,urlparse()} results containing @ref{1bd,,bytes}
data. The @code{decode()} method returns a @ref{3974,,ParseResult}
instance.


Ajouté dans la version 3.2.

@end deffn

@geindex SplitResultBytes (classe dans urllib.parse)
@anchor{library/urllib parse urllib parse SplitResultBytes}@anchor{3977}
@deffn {Classe} urllib.parse.SplitResultBytes (scheme, netloc, path, query, fragment)

Concrete class for @ref{d2d,,urlsplit()} results containing @ref{1bd,,bytes}
data. The @code{decode()} method returns a @ref{3976,,SplitResult}
instance.


Ajouté dans la version 3.2.

@end deffn

@node URL Quoting,,Structured Parse Results,urllib parse --- Parse URLs into components
@anchor{library/urllib parse url-quoting}@anchor{3978}
@subsubsection URL Quoting


The URL quoting functions focus on taking program data and making it safe
for use as URL components by quoting special characters and appropriately
encoding non-ASCII text. They also support reversing these operations to
recreate the original data from the contents of a URL component if that
task isn't already covered by the URL parsing functions above.

@geindex quote() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse quote}@anchor{b91}
@deffn {Fonction} urllib.parse.quote (string, safe='/', encoding=None, errors=None)

Replace special characters in `string' using the @code{%@var{xx}} escape. Letters,
digits, and the characters @code{'_.-~'} are never quoted. By default, this
function is intended for quoting the path section of a URL. The optional
`safe' parameter specifies additional ASCII characters that should not be
quoted --- its default value is @code{'/'}.

`string' may be either a @ref{435,,str} or a @ref{1bd,,bytes} object.


Modifié dans la version 3.7: Moved from 
@geindex RFC; RFC 2396
RFC 2396@footnote{https://datatracker.ietf.org/doc/html/rfc2396.html} to 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html} for quoting URL strings. "~" is now
included in the set of unreserved characters.


The optional `encoding' and `errors' parameters specify how to deal with
non-ASCII characters, as accepted by the @ref{8c2,,str.encode()} method.
`encoding' defaults to @code{'utf-8'}.
`errors' defaults to @code{'strict'}, meaning unsupported characters raise a
@ref{662,,UnicodeEncodeError}.
`encoding' and `errors' must not be supplied if `string' is a
@ref{1bd,,bytes}, or a @ref{522,,TypeError} is raised.

Note that @code{quote(string, safe, encoding, errors)} is equivalent to
@code{quote_from_bytes(string.encode(encoding, errors), safe)}.

Example: @code{quote('/El Niño/')} yields @code{'/El%20Ni%C3%B1o/'}.
@end deffn

@geindex quote_plus() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse quote_plus}@anchor{1227}
@deffn {Fonction} urllib.parse.quote_plus (string, safe='@w{'}, encoding=None, errors=None)

Like @ref{b91,,quote()}, but also replace spaces with plus signs, as required for
quoting HTML form values when building up a query string to go into a URL.
Plus signs in the original string are escaped unless they are included in
`safe'.  It also does not have `safe' default to @code{'/'}.

Example: @code{quote_plus('/El Niño/')} yields @code{'%2FEl+Ni%C3%B1o%2F'}.
@end deffn

@geindex quote_from_bytes() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse quote_from_bytes}@anchor{1753}
@deffn {Fonction} urllib.parse.quote_from_bytes (bytes, safe='/')

Like @ref{b91,,quote()}, but accepts a @ref{1bd,,bytes} object rather than a
@ref{435,,str}, and does not perform string-to-bytes encoding.

Example: @code{quote_from_bytes(b'a&\xef')} yields
@code{'a%26%EF'}.
@end deffn

@geindex unquote() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse unquote}@anchor{1714}
@deffn {Fonction} urllib.parse.unquote (string, encoding='utf-8', errors='replace')

Replace @code{%@var{xx}} escapes with their single-character equivalent.
The optional `encoding' and `errors' parameters specify how to decode
percent-encoded sequences into Unicode characters, as accepted by the
@ref{8c3,,bytes.decode()} method.

`string' may be either a @ref{435,,str} or a @ref{1bd,,bytes} object.

`encoding' defaults to @code{'utf-8'}.
`errors' defaults to @code{'replace'}, meaning invalid sequences are replaced
by a placeholder character.

Example: @code{unquote('/El%20Ni%C3%B1o/')} yields @code{'/El Niño/'}.


Modifié dans la version 3.9: `string' parameter supports bytes and str objects (previously only str).

@end deffn

@geindex unquote_plus() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse unquote_plus}@anchor{3979}
@deffn {Fonction} urllib.parse.unquote_plus (string, encoding='utf-8', errors='replace')

Like @ref{1714,,unquote()}, but also replace plus signs with spaces, as required
for unquoting HTML form values.

`string' must be a @ref{435,,str}.

Example: @code{unquote_plus('/El+Ni%C3%B1o/')} yields @code{'/El Niño/'}.
@end deffn

@geindex unquote_to_bytes() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse unquote_to_bytes}@anchor{1715}
@deffn {Fonction} urllib.parse.unquote_to_bytes (string)

Replace @code{%@var{xx}} escapes with their single-octet equivalent, and return a
@ref{1bd,,bytes} object.

`string' may be either a @ref{435,,str} or a @ref{1bd,,bytes} object.

If it is a @ref{435,,str}, unescaped non-ASCII characters in `string'
are encoded into UTF-8 bytes.

Example: @code{unquote_to_bytes('a%26%EF')} yields @code{b'a&\xef'}.
@end deffn

@geindex urlencode() (dans le module urllib.parse)
@anchor{library/urllib parse urllib parse urlencode}@anchor{e7e}
@deffn {Fonction} urllib.parse.urlencode (query, doseq=False, safe='@w{'}, encoding=None, errors=None, quote_via=quote_plus)

Convert a mapping object or a sequence of two-element tuples, which may
contain @ref{435,,str} or @ref{1bd,,bytes} objects, to a percent-encoded ASCII
text string.  If the resultant string is to be used as a `data' for POST
operation with the @ref{290,,urlopen()} function, then
it should be encoded to bytes, otherwise it would result in a
@ref{522,,TypeError}.

The resulting string is a series of @code{key=value} pairs separated by @code{'&'}
characters, where both `key' and `value' are quoted using the `quote_via'
function.  By default, @ref{1227,,quote_plus()} is used to quote the values, which
means spaces are quoted as a @code{'+'} character and '/' characters are
encoded as @code{%2F}, which follows the standard for GET requests
(@code{application/x-www-form-urlencoded}).  An alternate function that can be
passed as `quote_via' is @ref{b91,,quote()}, which will encode spaces as @code{%20}
and not encode '/' characters.  For maximum control of what is quoted, use
@code{quote} and specify a value for `safe'.

When a sequence of two-element tuples is used as the `query'
argument, the first element of each tuple is a key and the second is a
value. The value element in itself can be a sequence and in that case, if
the optional parameter `doseq' evaluates to @code{True}, individual
@code{key=value} pairs separated by @code{'&'} are generated for each element of
the value sequence for the key.  The order of parameters in the encoded
string will match the order of parameter tuples in the sequence.

The `safe', `encoding', and `errors' parameters are passed down to
`quote_via' (the `encoding' and `errors' parameters are only passed
when a query element is a @ref{435,,str}).

To reverse this encoding process, @ref{277,,parse_qs()} and @ref{276,,parse_qsl()} are
provided in this module to parse query strings into Python data structures.

Refer to @ref{3957,,urllib examples} to find out how the
@ref{e7e,,urllib.parse.urlencode()} method can be used for generating the query
string of a URL or data for a POST request.


Modifié dans la version 3.2: `query' supports bytes and string objects.



Modifié dans la version 3.5: Added the `quote_via' parameter.

@end deffn


@subsubheading Voir aussi



@table @asis

@item WHATWG@footnote{https://url.spec.whatwg.org/} -  URL Living standard

Working Group for the URL Standard that defines URLs, domains, IP addresses, the
application/x-www-form-urlencoded format, and their API.

@geindex RFC; RFC 3986

@item RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html} - Uniform Resource Identifiers

This is the current standard (STD66). Any changes to urllib.parse module
should conform to this. Certain deviations could be observed, which are
mostly for backward compatibility purposes and for certain de-facto
parsing requirements as commonly observed in major browsers.

@geindex RFC; RFC 2732

@item RFC 2732@footnote{https://datatracker.ietf.org/doc/html/rfc2732.html} - Format for Literal IPv6 Addresses in URL's.

This specifies the parsing requirements of IPv6 URLs.

@geindex RFC; RFC 2396

@item RFC 2396@footnote{https://datatracker.ietf.org/doc/html/rfc2396.html} - Uniform Resource Identifiers (URI): Generic Syntax

Document describing the generic syntactic requirements for both Uniform Resource
Names (URNs) and Uniform Resource Locators (URLs).

@geindex RFC; RFC 2368

@item RFC 2368@footnote{https://datatracker.ietf.org/doc/html/rfc2368.html} - The mailto URL scheme.

Parsing requirements for mailto URL schemes.

@geindex RFC; RFC 1808

@item RFC 1808@footnote{https://datatracker.ietf.org/doc/html/rfc1808.html} - Relative Uniform Resource Locators

This Request For Comments includes the rules for joining an absolute and a
relative URL, including a fair number of "Abnormal Examples" which govern the
treatment of border cases.

@geindex RFC; RFC 1738

@item RFC 1738@footnote{https://datatracker.ietf.org/doc/html/rfc1738.html} - Uniform Resource Locators (URL)

This specifies the formal syntax and semantics of absolute URLs.
@end table


@node urllib error --- Exception classes raised by urllib request,urllib robotparser --- Parser for robots txt,urllib parse --- Parse URLs into components,Gestion des protocoles internet
@anchor{library/urllib error doc}@anchor{397a}@anchor{library/urllib error module-urllib error}@anchor{108}@anchor{library/urllib error urllib-error-exception-classes-raised-by-urllib-request}@anchor{397b}
@subsection @code{urllib.error} --- Exception classes raised by urllib.request


@geindex module; urllib.error

`Code source :' Lib/urllib/error.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/urllib/error.py}


__________________________________________________________________


Le module @ref{108,,urllib.error} définit les classes des exceptions levées par @ref{10a,,urllib.request}.  La classe de base de ces exceptions est @ref{38e1,,URLError}.

Les exceptions suivantes sont levées par @ref{108,,urllib.error} aux cas appropriés :

@geindex URLError
@anchor{library/urllib error urllib error URLError}@anchor{38e1}
@deffn {Exception} urllib.error.URLError

Les gestionnaires lèvent cette exception (ou des exceptions dérivées) quand ils rencontrent un problème.  Elle est une sous-classe de @ref{40d,,OSError}.

@geindex reason (attribut urllib.error.URLError)
@anchor{library/urllib error urllib error URLError reason}@anchor{397c}
@deffn {Attribut} reason

La raison de cette erreur.  Il peut s'agir d'un message textuel ou d'une autre instance d'exception.
@end deffn


Modifié dans la version 3.3: @ref{38e1,,URLError} used to be a subtype of @ref{103b,,IOError}, which is now an
alias of @ref{40d,,OSError}.

@end deffn

@geindex HTTPError
@anchor{library/urllib error urllib error HTTPError}@anchor{fc9}
@deffn {Exception} urllib.error.HTTPError (url, code, msg, hdrs, fp)

Bien qu'étant une exception (une sous-classe de @ref{38e1,,URLError}), une @ref{fc9,,HTTPError} peut aussi fonctionner comme une valeur de retour normale et fichier-compatible (la même chose que renvoyé par @ref{290,,urlopen()}).  Cela est utile pour gérer les erreurs HTTP exotiques, comme les requêtes d'authentification.

@geindex url (attribut urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError url}@anchor{397d}
@deffn {Attribut} url

Contains the request URL.
An alias for `filename' attribute.
@end deffn

@geindex code (attribut urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError code}@anchor{397e}
@deffn {Attribut} code

Un statut HTTP comme défini dans la 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}.  Cette valeur numérique correspond à une valeur trouvée dans le dictionnaire des codes comme dans @ref{397f,,http.server.BaseHTTPRequestHandler.responses}.
@end deffn

@geindex reason (attribut urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError reason}@anchor{3980}
@deffn {Attribut} reason

This is usually a string explaining the reason for this error.
An alias for `msg' attribute.
@end deffn

@geindex headers (attribut urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError headers}@anchor{fca}
@deffn {Attribut} headers

The HTTP response headers for the HTTP request that caused the
@ref{fc9,,HTTPError}.
An alias for `hdrs' attribute.


Ajouté dans la version 3.4.

@end deffn

@geindex fp (attribut urllib.error.HTTPError)
@anchor{library/urllib error urllib error HTTPError fp}@anchor{3981}
@deffn {Attribut} fp

A file-like object where the HTTP error body can be read from.
@end deffn
@end deffn

@geindex ContentTooShortError
@anchor{library/urllib error urllib error ContentTooShortError}@anchor{395a}
@deffn {Exception} urllib.error.ContentTooShortError (msg, content)

This exception is raised when the @ref{3959,,urlretrieve()}
function detects that
the amount of the downloaded data is less than the expected amount (given by
the `Content-Length' header).

@geindex content (attribut urllib.error.ContentTooShortError)
@anchor{library/urllib error urllib error ContentTooShortError content}@anchor{3982}
@deffn {Attribut} content

The downloaded (and supposedly truncated) data.
@end deffn
@end deffn

@node urllib robotparser --- Parser for robots txt,http --- HTTP modules,urllib error --- Exception classes raised by urllib request,Gestion des protocoles internet
@anchor{library/urllib robotparser doc}@anchor{3983}@anchor{library/urllib robotparser module-urllib robotparser}@anchor{10c}@anchor{library/urllib robotparser urllib-robotparser-parser-for-robots-txt}@anchor{3984}
@subsection @code{urllib.robotparser} ---  Parser for robots.txt


@geindex module; urllib.robotparser

`Code source :' Lib/urllib/robotparser.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/urllib/robotparser.py}

@geindex WWW
@geindex World Wide Web
@geindex URL
@geindex robots.txt


__________________________________________________________________


This module provides a single class, @ref{ceb,,RobotFileParser}, which answers
questions about whether or not a particular user agent can fetch a URL on the
web site that published the @code{robots.txt} file.  For more details on the
structure of @code{robots.txt} files, see @indicateurl{http://www.robotstxt.org/orig.html}.

@geindex RobotFileParser (classe dans urllib.robotparser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser}@anchor{ceb}
@deffn {Classe} urllib.robotparser.RobotFileParser (url='@w{'})

Cette classe fournit des méthodes pour lire, analyser et répondre aux questions à propos du fichier @code{robots.txt} disponible à l'adresse `url'.

@geindex set_url() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser set_url}@anchor{3985}
@deffn {Méthode} set_url (url)

Modifie l'URL référençant le fichier @code{robots.txt}.
@end deffn

@geindex read() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser read}@anchor{3986}
@deffn {Méthode} read ()

Lit le fichier @code{robots.txt} depuis son URL et envoie le contenu à l'analyseur.
@end deffn

@geindex parse() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser parse}@anchor{1a30}
@deffn {Méthode} parse (lines)

Analyse les lignes données en argument.
@end deffn

@geindex can_fetch() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser can_fetch}@anchor{3987}
@deffn {Méthode} can_fetch (useragent, url)

Renvoie @code{True} si `useragent' est autorisé à accéder à `url' selon les règles contenues dans le fichier @code{robots.txt} analysé.
@end deffn

@geindex mtime() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser mtime}@anchor{3988}
@deffn {Méthode} mtime ()

Renvoie le temps auquel le fichier @code{robots.txt} a été téléchargé pour la dernière fois.  Cela est utile pour des `web spiders' de longue durée qui doivent vérifier périodiquement si le fichier est mis à jour.
@end deffn

@geindex modified() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser modified}@anchor{3989}
@deffn {Méthode} modified ()

Indique que le fichier @code{robots.txt} a été téléchargé pour la dernière fois au temps courant.
@end deffn

@geindex crawl_delay() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser crawl_delay}@anchor{398a}
@deffn {Méthode} crawl_delay (useragent)

Renvoie la valeur du paramètre @code{Crawl-delay} du @code{robots.txt} pour le `useragent' en question.  S'il n'y a pas de tel paramètre ou qu'il ne s'applique pas au `useragent' spécifié ou si l'entrée du @code{robots.txt} pour ce paramètre a une syntaxe invalide, renvoie @code{None}.


Ajouté dans la version 3.6.

@end deffn

@geindex request_rate() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser request_rate}@anchor{398b}
@deffn {Méthode} request_rate (useragent)

Renvoie le contenu du paramètre @code{Request-rate} du @code{robots.txt} sous la forme d'un @ref{639,,named tuple} @code{RequestRate(requests, seconds)}.  S'il n'y a pas de tel paramètre ou qu'il ne s'applique pas au `useragent' spécifié ou si l'entrée du @code{robots.txt} pour ce paramètre a une syntaxe invalide, @code{None} est renvoyé.


Ajouté dans la version 3.6.

@end deffn

@geindex site_maps() (méthode urllib.robotparser.RobotFileParser)
@anchor{library/urllib robotparser urllib robotparser RobotFileParser site_maps}@anchor{19cf}
@deffn {Méthode} site_maps ()

Renvoie le contenu du paramètre de @code{Sitemap} depuis @code{robots.txt} dans la forme d'une @ref{5fc,,list()}. S'il n'y a pas de tel paramètre ou qu'il ne s'applique pas au `useragent' spécifié ou si l'entrée du @code{robots.txt} pour ce paramètre a une syntaxe invalide, renvoie @code{None}.


Ajouté dans la version 3.8.

@end deffn
@end deffn

L'exemple suivant présente une utilisation basique de la classe @ref{ceb,,RobotFileParser} :

@example
>>> import urllib.robotparser
>>> rp = urllib.robotparser.RobotFileParser()
>>> rp.set_url("http://www.musi-cal.com/robots.txt")
>>> rp.read()
>>> rrate = rp.request_rate("*")
>>> rrate.requests
3
>>> rrate.seconds
20
>>> rp.crawl_delay("*")
6
>>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
False
>>> rp.can_fetch("*", "http://www.musi-cal.com/")
True
@end example

@node http --- HTTP modules,http client --- HTTP protocol client,urllib robotparser --- Parser for robots txt,Gestion des protocoles internet
@anchor{library/http doc}@anchor{398c}@anchor{library/http http-http-modules}@anchor{398d}@anchor{library/http module-http}@anchor{6d}
@subsection @code{http} --- HTTP modules


@geindex module; http

`Code source :' Lib/http/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/http/__init__.py}

@geindex HTTP;protocol
@geindex HTTP;http (standard module)


__________________________________________________________________


@ref{6d,,http} est un paquet qui rassemble plusieurs modules servant à travailler avec le protocole HTTP (`HyperText Transfer Procotol') :


@itemize *

@item 
Le module @ref{6e,,http.client} est un client HTTP bas niveau. Pour accéder à des ressources web, utiliser le module haut niveau @ref{10a,,urllib.request}

@item 
Le module @ref{71,,http.server} contient des classes serveur HTTP basiques basées sur @ref{cc,,socketserver}

@item 
Le module @ref{70,,http.cookies} contient des utilitaires liés à la gestion d'état HTTP via les cookies

@item 
Le module @ref{6f,,http.cookiejar} fournit un mécanisme de persistance des cookies
@end itemize

The @ref{6d,,http} module also defines the following enums that help you work with http related code:

@geindex HTTPStatus (classe dans http)
@anchor{library/http http HTTPStatus}@anchor{8ed}
@deffn {Classe} http.HTTPStatus


Ajouté dans la version 3.5.


Sous-classe de @ref{ccd,,enum.IntEnum} qui définit un ensemble de codes d'état HTTP, messages explicatifs et descriptions complètes écrites en anglais.

Utilisation :

@example
>>> from http import HTTPStatus
>>> HTTPStatus.OK
HTTPStatus.OK
>>> HTTPStatus.OK == 200
True
>>> HTTPStatus.OK.value
200
>>> HTTPStatus.OK.phrase
'OK'
>>> HTTPStatus.OK.description
'Request fulfilled, document follows'
>>> list(HTTPStatus)
[HTTPStatus.CONTINUE, HTTPStatus.SWITCHING_PROTOCOLS, ...]
@end example
@end deffn

@menu
* Codes d'état HTTP:: 
* HTTP status category:: 
* HTTP methods:: 

@end menu

@node Codes d'état HTTP,HTTP status category,,http --- HTTP modules
@anchor{library/http http-status-codes}@anchor{398e}@anchor{library/http id1}@anchor{398f}
@subsubsection Codes d'état HTTP


Supported,
IANA-registered status codes@footnote{https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml}
available in @ref{8ed,,http.HTTPStatus} are:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Code

@tab

Message

@tab

Détails

@item

@code{100}

@tab

@code{CONTINUE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.2.1

@item

@code{101}

@tab

@code{SWITCHING_PROTOCOLS}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.2.2

@item

@code{102}

@tab

@code{PROCESSING}

@tab

`WebDAV' 
@geindex RFC; RFC 2518
RFC 2518@footnote{https://datatracker.ietf.org/doc/html/rfc2518.html}, Section 10.1

@item

@code{103}

@tab

@code{EARLY_HINTS}

@tab

An HTTP Status Code for Indicating Hints 
@geindex RFC; RFC 8297
RFC 8297@footnote{https://datatracker.ietf.org/doc/html/rfc8297.html}

@item

@code{200}

@tab

@code{OK}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.1

@item

@code{201}

@tab

@code{CREATED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.2

@item

@code{202}

@tab

@code{ACCEPTED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.3

@item

@code{203}

@tab

@code{NON_AUTHORITATIVE_INFORMATION}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.4

@item

@code{204}

@tab

@code{NO_CONTENT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.5

@item

@code{205}

@tab

@code{RESET_CONTENT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.6

@item

@code{206}

@tab

@code{PARTIAL_CONTENT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.3.7

@item

@code{207}

@tab

@code{MULTI_STATUS}

@tab

`WebDAV' 
@geindex RFC; RFC 4918
RFC 4918@footnote{https://datatracker.ietf.org/doc/html/rfc4918.html}, Section 11.1

@item

@code{208}

@tab

@code{ALREADY_REPORTED}

@tab

`WebDAV' Binding Extensions 
@geindex RFC; RFC 5842
RFC 5842@footnote{https://datatracker.ietf.org/doc/html/rfc5842.html}, Section 7.1 (Expérimental)

@item

@code{226}

@tab

@code{IM_USED}

@tab

Delta Encoding in HTTP 
@geindex RFC; RFC 3229
RFC 3229@footnote{https://datatracker.ietf.org/doc/html/rfc3229.html}, Section 10.4.1

@item

@code{300}

@tab

@code{MULTIPLE_CHOICES}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.1

@item

@code{301}

@tab

@code{MOVED_PERMANENTLY}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.2

@item

@code{302}

@tab

@code{FOUND}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.3

@item

@code{303}

@tab

@code{SEE_OTHER}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.4

@item

@code{304}

@tab

@code{NOT_MODIFIED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.5

@item

@code{305}

@tab

@code{USE_PROXY}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.6

@item

@code{307}

@tab

@code{TEMPORARY_REDIRECT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.8

@item

@code{308}

@tab

@code{PERMANENT_REDIRECT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.4.9

@item

@code{400}

@tab

@code{BAD_REQUEST}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.1

@item

@code{401}

@tab

@code{UNAUTHORIZED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.2

@item

@code{402}

@tab

@code{PAYMENT_REQUIRED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.3

@item

@code{403}

@tab

@code{FORBIDDEN}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.4

@item

@code{404}

@tab

@code{NOT_FOUND}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.5

@item

@code{405}

@tab

@code{METHOD_NOT_ALLOWED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.6

@item

@code{406}

@tab

@code{NOT_ACCEPTABLE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.7

@item

@code{407}

@tab

@code{PROXY_AUTHENTICATION_REQUIRED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.8

@item

@code{408}

@tab

@code{REQUEST_TIMEOUT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.9

@item

@code{409}

@tab

@code{CONFLICT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.10

@item

@code{410}

@tab

@code{GONE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.11

@item

@code{411}

@tab

@code{LENGTH_REQUIRED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.12

@item

@code{412}

@tab

@code{PRECONDITION_FAILED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.13

@item

@code{413}

@tab

@code{CONTENT_TOO_LARGE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.14

@item

@code{414}

@tab

@code{URI_TOO_LONG}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.15

@item

@code{415}

@tab

@code{UNSUPPORTED_MEDIA_TYPE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.16

@item

@code{416}

@tab

@code{RANGE_NOT_SATISFIABLE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.17

@item

@code{417}

@tab

@code{EXPECTATION_FAILED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.18

@item

@code{418}

@tab

@code{IM_A_TEAPOT}

@tab

HTCPCP/1.0 
@geindex RFC; RFC 2324
RFC 2324@footnote{https://datatracker.ietf.org/doc/html/rfc2324.html}, Section 2.3.2

@item

@code{421}

@tab

@code{MISDIRECTED_REQUEST}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.20

@item

@code{422}

@tab

@code{UNPROCESSABLE_CONTENT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.21

@item

@code{423}

@tab

@code{LOCKED}

@tab

`WebDAV' 
@geindex RFC; RFC 4918
RFC 4918@footnote{https://datatracker.ietf.org/doc/html/rfc4918.html}, Section 11.3

@item

@code{424}

@tab

@code{FAILED_DEPENDENCY}

@tab

`WebDAV' 
@geindex RFC; RFC 4918
RFC 4918@footnote{https://datatracker.ietf.org/doc/html/rfc4918.html}, Section 11.4

@item

@code{425}

@tab

@code{TOO_EARLY}

@tab

Using Early Data in HTTP 
@geindex RFC; RFC 8470
RFC 8470@footnote{https://datatracker.ietf.org/doc/html/rfc8470.html}

@item

@code{426}

@tab

@code{UPGRADE_REQUIRED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.5.22

@item

@code{428}

@tab

@code{PRECONDITION_REQUIRED}

@tab

Additional HTTP Status Codes 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}

@item

@code{429}

@tab

@code{TOO_MANY_REQUESTS}

@tab

Additional HTTP Status Codes 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}

@item

@code{431}

@tab

@code{REQUEST_HEADER_FIELDS_TOO_LARGE}

@tab

Additional HTTP Status Codes 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}

@item

@code{451}

@tab

@code{UNAVAILABLE_FOR_LEGAL_REASONS}

@tab

An HTTP Status Code to Report Legal Obstacles 
@geindex RFC; RFC 7725
RFC 7725@footnote{https://datatracker.ietf.org/doc/html/rfc7725.html}

@item

@code{500}

@tab

@code{INTERNAL_SERVER_ERROR}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.6.1

@item

@code{501}

@tab

@code{NOT_IMPLEMENTED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.6.2

@item

@code{502}

@tab

@code{BAD_GATEWAY}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.6.3

@item

@code{503}

@tab

@code{SERVICE_UNAVAILABLE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.6.4

@item

@code{504}

@tab

@code{GATEWAY_TIMEOUT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.6.5

@item

@code{505}

@tab

@code{HTTP_VERSION_NOT_SUPPORTED}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15.6.6

@item

@code{506}

@tab

@code{VARIANT_ALSO_NEGOTIATES}

@tab

Transparent Content Negotiation in HTTP 
@geindex RFC; RFC 2295
RFC 2295@footnote{https://datatracker.ietf.org/doc/html/rfc2295.html}, Section 8.1 (Expérimental)

@item

@code{507}

@tab

@code{INSUFFICIENT_STORAGE}

@tab

`WebDAV' 
@geindex RFC; RFC 4918
RFC 4918@footnote{https://datatracker.ietf.org/doc/html/rfc4918.html}, Section 11.5

@item

@code{508}

@tab

@code{LOOP_DETECTED}

@tab

`WebDAV Binding Extensions' 
@geindex RFC; RFC 5842
RFC 5842@footnote{https://datatracker.ietf.org/doc/html/rfc5842.html}, Section 7.2 (Expérimental)

@item

@code{510}

@tab

@code{NOT_EXTENDED}

@tab

An HTTP Extension Framework 
@geindex RFC; RFC 2774
RFC 2774@footnote{https://datatracker.ietf.org/doc/html/rfc2774.html}, Section 7 (Expérimental)

@item

@code{511}

@tab

@code{NETWORK_AUTHENTICATION_REQUIRED}

@tab

Codes d'état HTTP supplémentaires 
@geindex RFC; RFC 6585
RFC 6585@footnote{https://datatracker.ietf.org/doc/html/rfc6585.html}, Section 6

@end multitable


Dans le but de préserver la compatibilité descendante, les valeurs d'énumération sont aussi présentes dans le module @ref{6e,,http.client} sous forme de constantes. Les noms de valeurs de l'énumération sont accessibles de deux manières : par exemple, le code HTTP 200 est accessible sous les noms @code{http.HTTPStatus.OK} et @code{http.client.OK}.


Modifié dans la version 3.7: Ajouté le code d'état @code{421 MISDIRECTED_REQUEST}.



Ajouté dans la version 3.8: Added @code{451 UNAVAILABLE_FOR_LEGAL_REASONS} status code.



Ajouté dans la version 3.9: Added @code{103 EARLY_HINTS}, @code{418 IM_A_TEAPOT} and @code{425 TOO_EARLY} status codes.



Modifié dans la version 3.13: Implemented RFC9110 naming for status constants. Old constant names are preserved for
backwards compatibility.


@node HTTP status category,HTTP methods,Codes d'état HTTP,http --- HTTP modules
@anchor{library/http http-status-category}@anchor{3990}
@subsubsection HTTP status category



Ajouté dans la version 3.12.


The enum values have several properties to indicate the HTTP status category:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Property

@tab

Indicates that

@tab

Détails

@item

@code{is_informational}

@tab

@code{100 <= status <= 199}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15

@item

@code{is_success}

@tab

@code{200 <= status <= 299}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15

@item

@code{is_redirection}

@tab

@code{300 <= status <= 399}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15

@item

@code{is_client_error}

@tab

@code{400 <= status <= 499}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15

@item

@code{is_server_error}

@tab

@code{500 <= status <= 599}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 15

@end multitable


@quotation

Utilisation :

@example
>>> from http import HTTPStatus
>>> HTTPStatus.OK.is_success
True
>>> HTTPStatus.OK.is_client_error
False
@end example
@end quotation

@geindex HTTPMethod (classe dans http)
@anchor{library/http http HTTPMethod}@anchor{3991}
@deffn {Classe} http.HTTPMethod


Ajouté dans la version 3.11.


A subclass of @ref{605,,enum.StrEnum} that defines a set of HTTP methods and descriptions written in English.

Utilisation :

@example
>>> from http import HTTPMethod
>>>
>>> HTTPMethod.GET
<HTTPMethod.GET>
>>> HTTPMethod.GET == 'GET'
True
>>> HTTPMethod.GET.value
'GET'
>>> HTTPMethod.GET.description
'Retrieve the target.'
>>> list(HTTPMethod)
[<HTTPMethod.CONNECT>,
 <HTTPMethod.DELETE>,
 <HTTPMethod.GET>,
 <HTTPMethod.HEAD>,
 <HTTPMethod.OPTIONS>,
 <HTTPMethod.PATCH>,
 <HTTPMethod.POST>,
 <HTTPMethod.PUT>,
 <HTTPMethod.TRACE>]
@end example
@end deffn

@node HTTP methods,,HTTP status category,http --- HTTP modules
@anchor{library/http http-methods}@anchor{3992}@anchor{library/http id2}@anchor{3993}
@subsubsection HTTP methods


Supported,
IANA-registered methods@footnote{https://www.iana.org/assignments/http-methods/http-methods.xhtml}
available in @ref{3991,,http.HTTPMethod} are:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Méthode

@tab

Message

@tab

Détails

@item

@code{GET}

@tab

@code{GET}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.1

@item

@code{HEAD}

@tab

@code{HEAD}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.2

@item

@code{POST}

@tab

@code{POST}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.3

@item

@code{PUT}

@tab

@code{PUT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.4

@item

@code{DELETE}

@tab

@code{DELETE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.5

@item

@code{CONNECT}

@tab

@code{CONNECT}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.6

@item

@code{OPTIONS}

@tab

@code{OPTIONS}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.7

@item

@code{TRACE}

@tab

@code{TRACE}

@tab

HTTP Semantics 
@geindex RFC; RFC 9110
RFC 9110@footnote{https://datatracker.ietf.org/doc/html/rfc9110.html}, Section 9.3.8

@item

@code{PATCH}

@tab

@code{PATCH}

@tab

HTTP/1.1 
@geindex RFC; RFC 5789
RFC 5789@footnote{https://datatracker.ietf.org/doc/html/rfc5789.html}

@end multitable


@node http client --- HTTP protocol client,ftplib --- FTP protocol client,http --- HTTP modules,Gestion des protocoles internet
@anchor{library/http client doc}@anchor{3994}@anchor{library/http client http-client-http-protocol-client}@anchor{3995}@anchor{library/http client module-http client}@anchor{6e}
@subsection @code{http.client} --- HTTP protocol client


@geindex module; http.client

`Code source :' Lib/http/client.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/http/client.py}

@geindex HTTP;protocol
@geindex HTTP;http.client (standard module)

@geindex module;urllib.request


__________________________________________________________________


This module defines classes that implement the client side of the HTTP and
HTTPS protocols.  It is normally not used directly --- the module
@ref{10a,,urllib.request} uses it to handle URLs that use HTTP and HTTPS.


@subsubheading Voir aussi


The Requests package@footnote{https://requests.readthedocs.io/en/latest/}
is recommended for a higher-level HTTP client interface.


@cartouche
@quotation Note 
L'implémentation d'HTTPS n'est disponible que si Python a été compilé avec la prise en charge de SSL (au moyen du module @ref{cf,,ssl}).
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Le module fournit les classes suivantes :

@geindex HTTPConnection (classe dans http.client)
@anchor{library/http client http client HTTPConnection}@anchor{b2e}
@deffn {Classe} http.client.HTTPConnection (host, port=None[, timeout], source_address=None, blocksize=8192)

An @ref{b2e,,HTTPConnection} instance represents one transaction with an HTTP
server.  It should be instantiated by passing it a host and optional port
number.  If no port number is passed, the port is extracted from the host
string if it has the form @code{host:port}, else the default HTTP port (80) is
used.  If the optional `timeout' parameter is given, blocking
operations (like connection attempts) will timeout after that many seconds
(if it is not given, the global default timeout setting is used).
The optional `source_address' parameter may be a tuple of a (host, port)
to use as the source address the HTTP connection is made from.
The optional `blocksize' parameter sets the buffer size in bytes for
sending a file-like message body.

Par exemple, tous les appels suivants créent des instances qui se connectent à un serveur sur le même hôte et le même port :

@example
>>> h1 = http.client.HTTPConnection('www.python.org')
>>> h2 = http.client.HTTPConnection('www.python.org:80')
>>> h3 = http.client.HTTPConnection('www.python.org', 80)
>>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)
@end example


Modifié dans la version 3.2: Le paramètre `source_address' a été ajouté.



Modifié dans la version 3.4: The  `strict' parameter was removed. HTTP 0.9-style "Simple Responses" are
no longer supported.



Modifié dans la version 3.7: Le paramètre `blocksize' a été ajouté.

@end deffn

@geindex HTTPSConnection (classe dans http.client)
@anchor{library/http client http client HTTPSConnection}@anchor{b2f}
@deffn {Classe} http.client.HTTPSConnection (host, port=None, *[, timeout], source_address=None, context=None, blocksize=8192)

Cette sous-classe de @ref{b2e,,HTTPConnection} utilise SSL pour communiquer avec des serveurs sécurisés. Le port par défaut est @code{443}. Si le paramètre `context' est fourni, ce doit être une instance de @ref{291,,ssl.SSLContext} décrivant les diverses options SSL.

Il est conseillé de lire @ref{32a2,,Security considerations} pour plus d'informations sur les bonnes pratiques.


Modifié dans la version 3.2: Les paramètres `source_address', `context' et `check_hostname' ont été ajoutés.



Modifié dans la version 3.2: This class now supports HTTPS virtual hosts if possible (that is,
if @ref{33d6,,ssl.HAS_SNI} is true).



Modifié dans la version 3.4: Le paramètre `strict' a été supprimé. Les « réponses simples » de HTTP 0.9 ne sont plus prises en charge.



Modifié dans la version 3.4.3: This class now performs all the necessary certificate and hostname checks
by default. To revert to the previous, unverified, behavior
@code{ssl._create_unverified_context()} can be passed to the `context'
parameter.



Modifié dans la version 3.8: Cette classe sélectionne désormais TLS 1.3 pour @ref{a1f,,ssl.SSLContext.post_handshake_auth} dans le `context' par défaut ou quand `cert_file' est fourni avec une valeur de `context' personnalisée.



Modifié dans la version 3.10: This class now sends an ALPN extension with protocol indicator
@code{http/1.1} when no `context' is given. Custom `context' should set
ALPN protocols with @ref{e4d,,set_alpn_protocols()}.



Modifié dans la version 3.12: The deprecated `key_file', `cert_file' and `check_hostname' parameters
have been removed.

@end deffn

@geindex HTTPResponse (classe dans http.client)
@anchor{library/http client http client HTTPResponse}@anchor{10b0}
@deffn {Classe} http.client.HTTPResponse (sock, debuglevel=0, method=None, url=None)

Classe dont les instances sont renvoyées dès qu'une connexion est établie.  Cette classe n'est jamais instanciée directement par l'utilisateur.


Modifié dans la version 3.4: Le paramètre `strict' a été supprimé. Les « réponses simples » de HTTP 0.9 ne sont plus prises en charge.

@end deffn

Ce module fournit les fonctions suivantes :

@geindex parse_headers() (dans le module http.client)
@anchor{library/http client http client parse_headers}@anchor{19d7}
@deffn {Fonction} http.client.parse_headers (fp)

Parse the headers from a file pointer `fp' representing a HTTP
request/response. The file has to be a @ref{67f,,BufferedIOBase} reader
(i.e. not text) and must provide a valid 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} style header.

Cette fonction renvoie une instance de @ref{3996,,http.client.HTTPMessage} qui contient les champs d'en-tête, mais pas la charge utile (de même que @ref{3997,,HTTPResponse.msg} et @ref{3998,,http.server.BaseHTTPRequestHandler.headers}). Après le retour, le pointeur de fichier `fp' est prêt à lire le corps HTTP.

@cartouche
@quotation Note 
La méthode @ref{19d7,,parse_headers()} n'analyse pas la ligne initiale d'un message HTTP ; elle n'analyse que les lignes @code{Name: value}. Le fichier doit être prêt à lire ces lignes de champs, aussi la première ligne doit déjà avoir été consommée avant l'appel de la fonction.
@end quotation
@end cartouche
@end deffn

Les exceptions suivantes sont levées selon les cas :

@geindex HTTPException
@anchor{library/http client http client HTTPException}@anchor{3999}
@deffn {Exception} http.client.HTTPException

La classe de base des autres exceptions de ce module.  C'est une sous-classe de  @ref{9c7,,Exception}.
@end deffn

@geindex NotConnected
@anchor{library/http client http client NotConnected}@anchor{399a}
@deffn {Exception} http.client.NotConnected

Sous-classe de @ref{3999,,HTTPException}.
@end deffn

@geindex InvalidURL
@anchor{library/http client http client InvalidURL}@anchor{399b}
@deffn {Exception} http.client.InvalidURL

Sous-classe de @ref{3999,,HTTPException}, levée si le port donné n'est pas numérique ou est vide.
@end deffn

@geindex UnknownProtocol
@anchor{library/http client http client UnknownProtocol}@anchor{399c}
@deffn {Exception} http.client.UnknownProtocol

Sous-classe de @ref{3999,,HTTPException}.
@end deffn

@geindex UnknownTransferEncoding
@anchor{library/http client http client UnknownTransferEncoding}@anchor{399d}
@deffn {Exception} http.client.UnknownTransferEncoding

Sous-classe de @ref{3999,,HTTPException}.
@end deffn

@geindex UnimplementedFileMode
@anchor{library/http client http client UnimplementedFileMode}@anchor{399e}
@deffn {Exception} http.client.UnimplementedFileMode

Sous-classe de @ref{3999,,HTTPException}.
@end deffn

@geindex IncompleteRead
@anchor{library/http client http client IncompleteRead}@anchor{399f}
@deffn {Exception} http.client.IncompleteRead

Sous-classe de @ref{3999,,HTTPException}.
@end deffn

@geindex ImproperConnectionState
@anchor{library/http client http client ImproperConnectionState}@anchor{39a0}
@deffn {Exception} http.client.ImproperConnectionState

Sous-classe de @ref{3999,,HTTPException}.
@end deffn

@geindex CannotSendRequest
@anchor{library/http client http client CannotSendRequest}@anchor{39a1}
@deffn {Exception} http.client.CannotSendRequest

Sous-classe de @ref{39a0,,ImproperConnectionState}.
@end deffn

@geindex CannotSendHeader
@anchor{library/http client http client CannotSendHeader}@anchor{39a2}
@deffn {Exception} http.client.CannotSendHeader

Sous-classe de @ref{39a0,,ImproperConnectionState}.
@end deffn

@geindex ResponseNotReady
@anchor{library/http client http client ResponseNotReady}@anchor{39a3}
@deffn {Exception} http.client.ResponseNotReady

Sous-classe de @ref{39a0,,ImproperConnectionState}.
@end deffn

@geindex BadStatusLine
@anchor{library/http client http client BadStatusLine}@anchor{39a4}
@deffn {Exception} http.client.BadStatusLine

Sous-classe de @ref{3999,,HTTPException}.  Levée si un serveur répond avec un code d'état HTTP qui n'est pas compris.
@end deffn

@geindex LineTooLong
@anchor{library/http client http client LineTooLong}@anchor{39a5}
@deffn {Exception} http.client.LineTooLong

Sous-classe de @ref{3999,,HTTPException}.  Levée si une ligne du protocole HTTP est excessivement longue dans ce qui provient du serveur.
@end deffn

@geindex RemoteDisconnected
@anchor{library/http client http client RemoteDisconnected}@anchor{df6}
@deffn {Exception} http.client.RemoteDisconnected

Sous-classe de @ref{1048,,ConnectionResetError} et @ref{39a4,,BadStatusLine}.  Levée par la méthode @ref{df5,,HTTPConnection.getresponse()} quand la tentative de lire la réponse n'aboutit à aucune donnée provenant de la connexion, indiquant ainsi que la partie distante a fermé celle-ci.


Ajouté dans la version 3.5: Antérieurement, @ref{39a4,,BadStatusLine}@code{('@w{'})} était levée.

@end deffn

Les constantes définies dans ce module sont :

@geindex HTTP_PORT (dans le module http.client)
@anchor{library/http client http client HTTP_PORT}@anchor{39a6}
@deffn {Données} http.client.HTTP_PORT

Le port par défaut du protocole HTTP (toujours @code{80}).
@end deffn

@geindex HTTPS_PORT (dans le module http.client)
@anchor{library/http client http client HTTPS_PORT}@anchor{39a7}
@deffn {Données} http.client.HTTPS_PORT

Le port par défaut du protocole HTTPS (toujours @code{443}).
@end deffn

@geindex responses (dans le module http.client)
@anchor{library/http client http client responses}@anchor{39a8}
@deffn {Données} http.client.responses

Ce dictionnaire associe les codes d'états HTTP 1.1 à leurs noms tels que définis par le W3C.

Par exemple : @code{http.client.responses[http.client.NOT_FOUND]} est @code{'Not Found'}.
@end deffn

Voir @ref{398e,,Codes d'état HTTP} pour une liste des codes d'état HTTP qui sont disponibles comme constantes dans ce module.

@menu
* Les objets HTTPConnection:: 
* Les objets HTTPResponse:: 
* Exemples: Exemples<26>. 
* Les objets HTTPMessage:: 

@end menu

@node Les objets HTTPConnection,Les objets HTTPResponse,,http client --- HTTP protocol client
@anchor{library/http client httpconnection-objects}@anchor{39a9}@anchor{library/http client id1}@anchor{39aa}
@subsubsection Les objets HTTPConnection


Les instances de la classe @ref{b2e,,HTTPConnection} possèdent les méthodes suivantes :

@geindex request() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection request}@anchor{c97}
@deffn {Méthode} HTTPConnection.request (method, url, body=None, headers=@{@}, *, encode_chunked=False)

This will send a request to the server using the HTTP request
method `method' and the request URI `url'. The provided `url' must be
an absolute path to conform with 
@geindex RFC; RFC 2616 Section 5.1.2
RFC 2616 §5.1.2@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html#section-5.1.2}
(unless connecting to an HTTP proxy server or using the @code{OPTIONS} or
@code{CONNECT} methods).

Si `body' est passé en paramètre, les données transmises sont envoyées à la suite des en-têtes. Ce paramètre peut-être une @ref{435,,str}, un @ref{d1b,,objet octet-comptatible}, un @ref{11a0,,objet fichier} préalablement ouvert, ou un itérable de classe @ref{1bd,,bytes}. Si `body' est une chaîne, elle est encodée en ISO-8859-1, valeur par défaut pour HTTP. Si c'est un objet octet-compatible, les octets sont envoyés tels quels. Si c'est un @ref{11a0,,objet fichier}, le contenu du fichier est envoyé ; cet objet fichier doit implémenter au moins la méthode  @code{read()}. Si l'objet fichier est une instance de @ref{680,,io.TextIOBase}, les données renvoyées par la méthode @code{read()} sont encodées en ISO-8859-1, sinon les données renvoyées par @code{read()} sont envoyées telles quelles. Si `body' est un itérable, les éléments de cet itérable sont envoyés jusqu'à ce que l'itérable soit vide.

The `headers' argument should be a mapping of extra HTTP headers to send
with the request. A 
@geindex RFC; RFC 2616 Section 14.23
Host header@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html#section-14.23}
must be provided to conform with 
@geindex RFC; RFC 2616 Section 5.1.2
RFC 2616 §5.1.2@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html#section-5.1.2}
(unless connecting to an HTTP proxy server or using the @code{OPTIONS} or
@code{CONNECT} methods).

Si `headers' ne contient ni @code{Content-Length:} ni @code{Transfer-Encoding:}, mais qu'un corps de requête est fourni, un de ces en-têtes est ajouté automatiquement. Si `body' est @code{None}, l'en-tête @code{Content-Length:} est paramétré à @code{0} pour les méthodes qui attendent un corps (@code{PUT}, @code{POST}, et @code{PATCH}). Si `body' est une chaîne ou un objet de type octets qui n'est pas un (@ref{11a0,,objet fichier}), l'en-tête @code{Content-Length} est paramétré à sa longueur. Un `body' de tout autre type (fichiers ou itérables en général) est encodé par morceaux et l'en-tête @code{Transfer-Encoding} est automatiquement paramétré à la place de @code{Content-Length}.

L'argument `encode_chunked' n'est pertinent que si l'en-tête @code{Transfer-Encoding:} est présent. Si `encode_chunked' est @code{False}, l'objet  HTTPConnection suppose que l'encodage est géré par le code d'appel. S'il vaut @code{True}, le corps est encodé par morceaux.

For example, to perform a @code{GET} request to @code{https://docs.python.org/3/}:

@example
>>> import http.client
>>> host = "docs.python.org"
>>> conn = http.client.HTTPSConnection(host)
>>> conn.request("GET", "/3/", headers=@{"Host": host@})
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200 OK
@end example

@cartouche
@quotation Note 
L'encodage pour les transferts par morceaux a été ajouté à la version 1.1 du protocole HTTP. À moins que le serveur HTTP sache gérer HTTP 1.1, l'appelant doit soit spécifier l'en-tête @code{Content-Length:}, soit passer la représentation du corps de message dans un objet de classe @ref{435,,str} ou un objet octet-compatible qui ne soit pas un fichier.
@end quotation
@end cartouche


Modifié dans la version 3.2: `body' peut désormais être un itérable.



Modifié dans la version 3.6: Si parmi les en-têtes ne figure ni @code{Content-Length:}, ni @code{Transfer-Encoding:}, les objets fichiers et itérables `body' sont désormais encodés par morceaux. L'argument `encode_chunked' a été ajouté. Aucune tentative n'est faite pour essayer de déterminer la valeur de l'en-tête @code{Content-Length} pour un objet fichier.

@end deffn

@geindex getresponse() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection getresponse}@anchor{df5}
@deffn {Méthode} HTTPConnection.getresponse ()

Doit être appelé après qu'une requête a été envoyée pour récupérer la réponse du serveur. Renvoie une instance de @ref{10b0,,HTTPResponse}.

@cartouche
@quotation Note 
Notez que la totalité de la réponse doit être lue avant de pouvoir envoyer une nouvelle requête au serveur.
@end quotation
@end cartouche


Modifié dans la version 3.5: Si une exception @ref{df7,,ConnectionError} ou une de ses sous-classes est levée, l'objet de classe @ref{b2e,,HTTPConnection} sera prêt à se reconnecter quand une nouvelle requête sera envoyée.

@end deffn

@geindex set_debuglevel() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection set_debuglevel}@anchor{39ab}
@deffn {Méthode} HTTPConnection.set_debuglevel (level)

Règle le niveau de débogage. Le niveau de débogage par défaut est @code{0} (aucune sortie de débogage n'est affichée). Toute valeur plus grande que @code{0} provoque l'affichage sur @code{sys.stdout} de toutes les sorties de débogage actuellement définies. Le paramètre @code{debuglevel} est passé à tout nouvel objet de classe @ref{10b0,,HTTPResponse} qui est créé.


Ajouté dans la version 3.1.

@end deffn

@geindex set_tunnel() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection set_tunnel}@anchor{1206}
@deffn {Méthode} HTTPConnection.set_tunnel (host, port=None, headers=None)

Paramètre l'hôte et le port pour le tunnel de connexion HTTP. Il permet de réaliser la connexion au travers d'un serveur mandataire.

The `host' and `port' arguments specify the endpoint of the tunneled connection
(i.e. the address included in the CONNECT request, `not' the address of the
proxy server).

The `headers' argument should be a mapping of extra HTTP headers to send with
the CONNECT request.

As HTTP/1.1 is used for HTTP CONNECT tunnelling request, as per the RFC@footnote{https://datatracker.ietf.org/doc/html/rfc7231#section-4.3.6}, a HTTP @code{Host:}
header must be provided, matching the authority-form of the request target
provided as the destination for the CONNECT request. If a HTTP @code{Host:}
header is not provided via the headers argument, one is generated and
transmitted automatically.

Par exemple, pour un tunnel traversant un serveur mandataire HTTPS accessible localement sur le port 8080, nous devons passer l'adresse du serveur mandataire au constructeur de la classe @ref{b2f,,HTTPSConnection}, en plus de l'éventuelle adresse de l'hôte que nous voulons atteindre, qui elle doit être passée à la méthode @ref{1206,,set_tunnel()} :

@example
>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")
@end example


Ajouté dans la version 3.2.



Modifié dans la version 3.12: HTTP CONNECT tunnelling requests use protocol HTTP/1.1, upgraded from
protocol HTTP/1.0. @code{Host:} HTTP headers are mandatory for HTTP/1.1, so
one will be automatically generated and transmitted if not provided in
the headers argument.

@end deffn

@geindex get_proxy_response_headers() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection get_proxy_response_headers}@anchor{168c}
@deffn {Méthode} HTTPConnection.get_proxy_response_headers ()

Returns a dictionary with the headers of the response received from
the proxy server to the CONNECT request.

If the CONNECT request was not sent, the method returns @code{None}.


Ajouté dans la version 3.12.

@end deffn

@geindex connect() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection connect}@anchor{39ac}
@deffn {Méthode} HTTPConnection.connect ()

Se connecte au serveur spécifié quand l'objet est créé. Par défaut, est appelée automatiquement lorsqu'une requête est faite alors que le client ne s'est pas connecté au préalable.

Lève un @ref{1848,,évènement d'audit} @code{http.client.connect} contenant les arguments @code{self}, @code{host}, @code{port}.
@end deffn

@geindex close() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection close}@anchor{39ad}
@deffn {Méthode} HTTPConnection.close ()

Ferme la connexion au serveur.
@end deffn

@geindex blocksize (attribut http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection blocksize}@anchor{39ae}
@deffn {Attribut} HTTPConnection.blocksize

Taille en octets du tampon utilisé pour transmettre un corps de message de type fichier.


Ajouté dans la version 3.7.

@end deffn

As an alternative to using the @ref{c97,,request()} method described above, you can
also send your request step by step, by using the four functions below.

@geindex putrequest() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection putrequest}@anchor{39af}
@deffn {Méthode} HTTPConnection.putrequest (method, url, skip_host=False, skip_accept_encoding=False)

Ce doit être le premier appel une fois que la connexion au serveur a été réalisée. Est envoyée au serveur une ligne consistant en la chaîne `method', la chaîne d'`url', et la version du protocole HTTP (@code{HTTP/1.1}). Pour désactiver l'envoi automatique des en-têtes @code{Host:} ou @code{Accept-Encoding:} (par exemple pour accepter des encodages supplémentaires de contenus), il est nécessaire de passer les paramètres `skip_host' ou `skip_accept_encoding' avec des valeurs différentes de @code{False}.
@end deffn

@geindex putheader() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection putheader}@anchor{39b0}
@deffn {Méthode} HTTPConnection.putheader (header, argument[, ...])

Envoie un en-tête de style 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} au serveur. Elle envoie au serveur une ligne regroupant un en-tête, une espace, un @code{:}, une espace et le premier argument. Si plusieurs arguments sont donnés, des lignes de continuation sont envoyées, chacune d'elle étant constituée d'une espace suivie d'un argument.
@end deffn

@geindex endheaders() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection endheaders}@anchor{c98}
@deffn {Méthode} HTTPConnection.endheaders (message_body=None, *, encode_chunked=False)

Envoie une ligne blanche au serveur, signalant la fin des en-têtes. L'argument optionnel `message_body' peut-être utilisé pour passer le corps du message associé à la requête.

Si `encode_chunked' est @code{True}, le résultat de chaque itération sur `message_body' est un morceau encodé selon la 
@geindex RFC; RFC 7230
RFC 7230@footnote{https://datatracker.ietf.org/doc/html/rfc7230.html}, section 3.3.1. La façon dont les données sont encodées dépend du type de `message_body'. Si `message_body' implémente l'@ref{38e,,interface tampon} l'encodage donne un unique morceau. Si `message_body' est un itérable de classe @ref{21d6,,collections.abc.Iterable}, chaque itération sur `message_body' donne un morceau. Si `message_body' est un @ref{11a0,,fichier objet}, chaque appel à @code{.read()} renvoie un morceau. La méthode signale automatiquement la fin des données encodées par morceaux immédiatement après `message_body'.

@cartouche
@quotation Note 
Selon la spécification de l'encodage des morceaux, les morceaux vides renvoyés par un itérateur associé au corps du message sont ignorés par l'encodeur de morceaux. Ce comportement est choisi pour éviter que la lecture de la requête par le serveur cible ne se termine prématurément pour cause d'encodage mal formé.
@end quotation
@end cartouche


Modifié dans la version 3.6: Added chunked encoding support and the `encode_chunked' parameter.

@end deffn

@geindex send() (méthode http.client.HTTPConnection)
@anchor{library/http client http client HTTPConnection send}@anchor{39b1}
@deffn {Méthode} HTTPConnection.send (data)

Envoie les données au serveur. Elle ne peut être utilisée directement qu'une fois la méthode @ref{c98,,endheaders()} a été appelée et avant que la méthode @ref{df5,,getresponse()} ait été appelée.

Lève un @ref{1848,,évènement d'audit} @code{http.client.send} avec comme arguments @code{self}, @code{data}.
@end deffn

@node Les objets HTTPResponse,Exemples<26>,Les objets HTTPConnection,http client --- HTTP protocol client
@anchor{library/http client httpresponse-objects}@anchor{39b2}@anchor{library/http client id2}@anchor{39b3}
@subsubsection Les objets HTTPResponse


Une instance de @ref{10b0,,HTTPResponse} encapsule la réponse HTTP du serveur. Elle fournit un accès aux en-têtes et au corps de la réponse. La réponse est un objet itérable pouvant être utilisé avec l'instruction @code{with}.


Modifié dans la version 3.5: L'interface de la classe @ref{67f,,io.BufferedIOBase} est désormais implémentée et toutes ses opérations de lecture sont gérées.


@geindex read() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse read}@anchor{16d6}
@deffn {Méthode} HTTPResponse.read ([amt])

Lit et renvoie soit tout le corps de la réponse soit une partie de celui-ci se limitant aux `amt' octets suivants.
@end deffn

@geindex readinto() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse readinto}@anchor{10b1}
@deffn {Méthode} HTTPResponse.readinto (b)

Lit les prochains @code{len(b)} octets du corps de la réponse et les place dans le tampon `b'. Renvoie le nombre d'octets lus.


Ajouté dans la version 3.3.

@end deffn

@geindex getheader() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse getheader}@anchor{39b4}
@deffn {Méthode} HTTPResponse.getheader (name, default=None)

Return the value of the header `name', or `default' if there is no header
matching `name'.  If there is more than one  header with the name `name',
return all of the values joined by ', '.  If `default' is any iterable other
than a single string, its elements are similarly returned joined by commas.
@end deffn

@geindex getheaders() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse getheaders}@anchor{39b5}
@deffn {Méthode} HTTPResponse.getheaders ()

Renvoie une liste d'`n'-uplets @code{(en-tête, valeur)}.
@end deffn

@geindex fileno() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse fileno}@anchor{39b6}
@deffn {Méthode} HTTPResponse.fileno ()

Renvoie le @code{fileno} du connecteur réseau sous-jacent.
@end deffn

@geindex msg (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse msg}@anchor{3997}
@deffn {Attribut} HTTPResponse.msg

Une instance de @ref{3996,,http.client.HTTPMessage} contenant les en-têtes de la réponse. La classe @ref{3996,,http.client.HTTPMessage} est une sous-classe de la classe @ref{279,,email.message.Message}.
@end deffn

@geindex version (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse version}@anchor{39b7}
@deffn {Attribut} HTTPResponse.version

La version du protocole HTTP utilisée par le serveur : 10 pour HTTP/1.0, 11 pour HTTP/1.1.
@end deffn

@geindex url (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse url}@anchor{39b8}
@deffn {Attribut} HTTPResponse.url

L'URL de la ressource récupérée, utilisée habituellement pour déterminer si une redirection a été suivie.
@end deffn

@geindex headers (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse headers}@anchor{39b9}
@deffn {Attribut} HTTPResponse.headers

Les en-têtes de la réponse sous la forme d'une instance de @ref{278,,email.message.EmailMessage}.
@end deffn

@geindex status (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse status}@anchor{39ba}
@deffn {Attribut} HTTPResponse.status

Code d'état renvoyé par le serveur.
@end deffn

@geindex reason (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse reason}@anchor{38e0}
@deffn {Attribut} HTTPResponse.reason

Phrase renvoyée par le serveur et indiquant la cause.
@end deffn

@geindex debuglevel (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse debuglevel}@anchor{39bb}
@deffn {Attribut} HTTPResponse.debuglevel

Un point d'entrée pour débogage. Si @ref{39bb,,debuglevel} est plus grand que zéro, les messages sont envoyés à @code{sys.stdout} pendant la lecture et l'analyse de la réponse.
@end deffn

@geindex closed (attribut http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse closed}@anchor{39bc}
@deffn {Attribut} HTTPResponse.closed

Vaut @code{True} si le flux est terminé.
@end deffn

@geindex geturl() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse geturl}@anchor{39bd}
@deffn {Méthode} HTTPResponse.geturl ()


Obsolète depuis la version 3.9: Rendu obsolète par @ref{39b8,,url}.

@end deffn

@geindex info() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse info}@anchor{39be}
@deffn {Méthode} HTTPResponse.info ()


Obsolète depuis la version 3.9: Rendu obsolète par @ref{39b9,,headers}.

@end deffn

@geindex getcode() (méthode http.client.HTTPResponse)
@anchor{library/http client http client HTTPResponse getcode}@anchor{39bf}
@deffn {Méthode} HTTPResponse.getcode ()


Obsolète depuis la version 3.9: Rendu obsolète par @ref{39ba,,status}.

@end deffn

@node Exemples<26>,Les objets HTTPMessage,Les objets HTTPResponse,http client --- HTTP protocol client
@anchor{library/http client examples}@anchor{39c0}
@subsubsection Exemples


Voici un exemple de session utilisant la méthode @code{GET} :

@example
>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while chunk := r1.read(200):
...     print(repr(chunk))
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()
@end example

Voici un exemple de session utilisant la méthode  @code{HEAD}.  Notez que la méthode @code{HEAD} ne renvoie jamais de données.

@example
>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b'@w{'}
True
@end example

Here is an example session that uses the @code{POST} method:

@example
>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode(@{'@@number': 12524, '@@type': 'issue', '@@action': 'show'@})
>>> headers = @{"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"@}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="https://bugs.python.org/issue12524">https://bugs.python.org/issue12524</a>'
>>> conn.close()
@end example

Client side HTTP @code{PUT} requests are very similar to @code{POST} requests. The
difference lies only on the server side where HTTP servers will allow resources to
be created via @code{PUT} requests. It should be noted that custom HTTP methods
are also handled in @ref{fc3,,urllib.request.Request} by setting the appropriate
method attribute. Here is an example session that uses the @code{PUT} method:

@example
>>> # This creates an HTTP request
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK
@end example

@node Les objets HTTPMessage,,Exemples<26>,http client --- HTTP protocol client
@anchor{library/http client httpmessage-objects}@anchor{39c1}@anchor{library/http client id3}@anchor{39c2}
@subsubsection Les objets HTTPMessage


@geindex HTTPMessage (classe dans http.client)
@anchor{library/http client http client HTTPMessage}@anchor{3996}
@deffn {Classe} http.client.HTTPMessage (email.message.Message)
@end deffn

Une instance de classe @ref{3996,,http.client.HTTPMessage} contient les en-têtes d'une réponse HTTP. Elle est implémentée en utilisant la classe @ref{279,,email.message.Message}.

@c XXX Define the methods that clients can depend upon between versions.

@node ftplib --- FTP protocol client,poplib --- POP3 protocol client,http client --- HTTP protocol client,Gestion des protocoles internet
@anchor{library/ftplib doc}@anchor{39c3}@anchor{library/ftplib ftplib-ftp-protocol-client}@anchor{39c4}@anchor{library/ftplib module-ftplib}@anchor{5d}
@subsection @code{ftplib} --- FTP protocol client


@geindex module; ftplib

`Code source :' Lib/ftplib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/ftplib.py}

@geindex FTP;protocol
@geindex FTP;ftplib (standard module)


__________________________________________________________________


Ce module définit la classe @ref{8e7,,FTP} et quelques éléments associés. La classe @ref{8e7,,FTP} implémente le côté client du protocole FTP. Vous pouvez l'utiliser pour écrire des programmes Python qui effectuent diverses tâches automatisées telles que la synchronisation d'autres serveurs FTP. Il est aussi utilisé par le module @ref{10a,,urllib.request}  pour gérer les URL qui utilisent FTP. Pour plus d'informations sur FTP (File Transfer Protocol), voir la 
@geindex RFC; RFC 959
RFC 959@footnote{https://datatracker.ietf.org/doc/html/rfc959.html}.

L'encodage par défaut est UTF-8, voir la 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Voici un exemple de session utilisant le module @ref{5d,,ftplib} :

@example
>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'
@end example

@menu
* Référence: Référence<4>. 

@end menu

@node Référence<4>,,,ftplib --- FTP protocol client
@anchor{library/ftplib ftplib-reference}@anchor{39c5}@anchor{library/ftplib reference}@anchor{39c6}
@subsubsection Référence


@menu
* FTP objects:: 
* FTP_TLS objects:: 
* Module variables:: 

@end menu

@node FTP objects,FTP_TLS objects,,Référence<4>
@anchor{library/ftplib ftp-objects}@anchor{39c7}@anchor{library/ftplib id1}@anchor{39c8}
@subsubsection FTP objects


@c Use substitutions for some param docs so we don't need to repeat them
@c in multiple places.

@c Ideally, we'd like to use the :rfc: directive, but Sphinx will not allow it.

@geindex FTP (classe dans ftplib)
@anchor{library/ftplib ftplib FTP}@anchor{8e7}
@deffn {Classe} ftplib.FTP (host='@w{'}, user='@w{'}, passwd='@w{'}, acct='@w{'}, timeout=None, source_address=None, *, encoding='utf-8')

Return a new instance of the @ref{8e7,,FTP} class.

@*Paramètres: 

@itemize *

@item 
@code{host} (@ref{435,,str}) -- The hostname to connect to.
If given, @code{connect(host)} is implicitly called by the constructor.

@item 
@code{user} (@ref{435,,str}) -- The username to log in with (default: @code{'anonymous'}).
If given, @code{login(host, passwd, acct)} is implicitly called
by the constructor.

@item 
@code{passwd} (@ref{435,,str}) -- The password to use when logging in.
If not given, and if `passwd' is the empty string or @code{"-"},
a password will be automatically generated.

@item 
@code{acct} (@ref{435,,str}) -- Account information to be used for the @code{ACCT} FTP command.
Few systems implement this.
See RFC-959@footnote{https://datatracker.ietf.org/doc/html/rfc959.html}
for more details.

@item 
@code{timeout} (@ref{2eb,,float}@code{ | }@code{None}) -- A timeout in seconds for blocking operations like @ref{39c9,,connect()}
(default: the global default timeout setting).

@item 
@code{source_address} (@ref{366,,tuple}@code{ | }@code{None}) -- A 2-tuple @code{(host, port)} for the socket to bind to as its
source address before connecting.

@item 
@code{encoding} (@ref{435,,str}) -- The encoding for directories and filenames (default: @code{'utf-8'}).
@end itemize


La classe @ref{8e7,,FTP} peut s'utiliser avec l'instruction @ref{5bc,,with}, p. ex. :

@example
>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
... 
'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
>>>
@end example


Modifié dans la version 3.2: La prise en charge de l'instruction @ref{5bc,,with} a été ajoutée.



Modifié dans la version 3.3: `source_address' parameter was added.



Modifié dans la version 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{1ff,,ValueError} to prevent the creation of a non-blocking socket.
The `encoding' parameter was added, and the default was changed from
Latin-1 to UTF-8 to follow 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}.


Several @code{FTP} methods are available in two flavors:
one for handling text files and another for binary files.
The methods are named for the command which is used followed by
@code{lines} for the text version or @code{binary} for the binary version.

Les instances de la classe @ref{8e7,,FTP} possèdent les méthodes suivantes :

@geindex set_debuglevel() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP set_debuglevel}@anchor{39ca}
@deffn {Méthode} set_debuglevel (level)

Set the instance's debugging level as an @ref{254,,int}.
This controls the amount of debugging output printed.
The debug levels are:


@itemize *

@item 
@code{0} (default): No debug output.

@item 
@code{1}: Produce a moderate amount of debug output,
generally a single line per request.

@item 
@code{2} or higher: Produce the maximum amount of debugging output,
logging each line sent and received on the control connection.
@end itemize
@end deffn

@geindex connect() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP connect}@anchor{39c9}
@deffn {Méthode} connect (host='@w{'}, port=0, timeout=None, source_address=None)

Connect to the given host and port.
This function should be called only once for each instance;
it should not be called if a `host' argument was given
when the @ref{8e7,,FTP} instance was created.
All other @code{FTP} methods can only be called
after a connection has successfully been made.

@*Paramètres: 

@itemize *

@item 
@code{host} (@ref{435,,str}) -- The host to connect to.

@item 
@code{port} (@ref{254,,int}) -- The TCP port to connect to (default: @code{21},
as specified by the FTP protocol specification).
It is rarely needed to specify a different port number.

@item 
@code{timeout} (@ref{2eb,,float}@code{ | }@code{None}) -- A timeout in seconds for the connection attempt
(default: the global default timeout setting).

@item 
@code{source_address} (@ref{366,,tuple}@code{ | }@code{None}) -- A 2-tuple @code{(host, port)} for the socket to bind to as its
source address before connecting.
@end itemize


Raises an @ref{1848,,auditing event} @code{ftplib.connect} with arguments @code{self}, @code{host}, @code{port}.


Modifié dans la version 3.3: `source_address' parameter was added.

@end deffn

@geindex getwelcome() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP getwelcome}@anchor{39cb}
@deffn {Méthode} getwelcome ()

Return the welcome message sent by the server in reply to the initial
connection.  (This message sometimes contains disclaimers or help information
that may be relevant to the user.)
@end deffn

@geindex login() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP login}@anchor{39cc}
@deffn {Méthode} login (user='anonymous', passwd='@w{'}, acct='@w{'})

Log on to the connected FTP server.
This function should be called only once for each instance,
after a connection has been established;
it should not be called if the `host' and `user' arguments were given
when the @ref{8e7,,FTP} instance was created.
Most FTP commands are only allowed after the client has logged in.

@*Paramètres: 

@itemize *

@item 
@code{user} (@ref{435,,str}) -- The username to log in with (default: @code{'anonymous'}).

@item 
@code{passwd} (@ref{435,,str}) -- The password to use when logging in.
If not given, and if `passwd' is the empty string or @code{"-"},
a password will be automatically generated.

@item 
@code{acct} (@ref{435,,str}) -- Account information to be used for the @code{ACCT} FTP command.
Few systems implement this.
See RFC-959@footnote{https://datatracker.ietf.org/doc/html/rfc959.html}
for more details.
@end itemize

@end deffn

@geindex abort() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP abort}@anchor{39cd}
@deffn {Méthode} abort ()

Abort a file transfer that is in progress.  Using this does not always work, but
it's worth a try.
@end deffn

@geindex sendcmd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP sendcmd}@anchor{39ce}
@deffn {Méthode} sendcmd (cmd)

Send a simple command string to the server and return the response string.

Raises an @ref{1848,,auditing event} @code{ftplib.sendcmd} with arguments @code{self}, @code{cmd}.
@end deffn

@geindex voidcmd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP voidcmd}@anchor{39cf}
@deffn {Méthode} voidcmd (cmd)

Send a simple command string to the server and handle the response.  Return
the response string if the response code corresponds to success (codes in
the range 200--299).  Raise @ref{39d0,,error_reply} otherwise.

Raises an @ref{1848,,auditing event} @code{ftplib.sendcmd} with arguments @code{self}, @code{cmd}.
@end deffn

@geindex retrbinary() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP retrbinary}@anchor{39d1}
@deffn {Méthode} retrbinary (cmd, callback, blocksize=8192, rest=None)

Retrieve a file in binary transfer mode.

@*Paramètres: 

@itemize *

@item 
@code{cmd} (@ref{435,,str}) -- An appropriate @code{RETR} command: @code{"RETR @var{filename}"}.

@item 
@code{callback} (@ref{2870,,callable}) -- A single parameter callable that is called
for each block of data received,
with its single argument being the data as @ref{1bd,,bytes}.

@item 
@code{blocksize} (@ref{254,,int}) -- The maximum chunk size to read on the low-level
@ref{d8e,,socket} object created to do the actual transfer.
This also corresponds to the largest size of data
that will be passed to `callback'.
Defaults to @code{8192}.

@item 
@code{rest} (@ref{254,,int}) -- A @code{REST} command to be sent to the server.
See the documentation for the `rest' parameter of the @ref{39d2,,transfercmd()} method.
@end itemize

@end deffn

@geindex retrlines() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP retrlines}@anchor{39d3}
@deffn {Méthode} retrlines (cmd, callback=None)

Retrieve a file or directory listing in the encoding specified by the
`encoding' parameter at initialization.
`cmd' should be an appropriate @code{RETR} command (see @ref{39d1,,retrbinary()}) or
a command such as @code{LIST} or @code{NLST} (usually just the string @code{'LIST'}).
@code{LIST} retrieves a list of files and information about those files.
@code{NLST} retrieves a list of file names.
The `callback' function is called for each line with a string argument
containing the line with the trailing CRLF stripped.  The default `callback'
prints the line to @ref{ac4,,sys.stdout}.
@end deffn

@geindex set_pasv() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP set_pasv}@anchor{39d4}
@deffn {Méthode} set_pasv (val)

Enable "passive" mode if `val' is true, otherwise disable passive mode.
Passive mode is on by default.
@end deffn

@geindex storbinary() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP storbinary}@anchor{12e8}
@deffn {Méthode} storbinary (cmd, fp, blocksize=8192, callback=None, rest=None)

Store a file in binary transfer mode.

@*Paramètres: 

@itemize *

@item 
@code{cmd} (@ref{435,,str}) -- An appropriate @code{STOR} command: @code{"STOR @var{filename}"}.

@item 
@code{fp} (@ref{11a0,,file object}) -- A file object (opened in binary mode) which is read until EOF,
using its @ref{e09,,read()} method in blocks of size `blocksize'
to provide the data to be stored.

@item 
@code{blocksize} (@ref{254,,int}) -- The read block size.
Defaults to @code{8192}.

@item 
@code{callback} (@ref{2870,,callable}) -- A single parameter callable that is called
for each block of data sent,
with its single argument being the data as @ref{1bd,,bytes}.

@item 
@code{rest} (@ref{254,,int}) -- A @code{REST} command to be sent to the server.
See the documentation for the `rest' parameter of the @ref{39d2,,transfercmd()} method.
@end itemize



Modifié dans la version 3.2: The `rest' parameter was added.

@end deffn

@geindex storlines() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP storlines}@anchor{39d5}
@deffn {Méthode} storlines (cmd, fp, callback=None)

Store a file in line mode.  `cmd' should be an appropriate
@code{STOR} command (see @ref{12e8,,storbinary()}).  Lines are read until EOF from the
@ref{11a0,,file object} `fp' (opened in binary mode) using its @ref{1307,,readline()}
method to provide the data to be stored.  `callback' is an optional single
parameter callable that is called on each line after it is sent.
@end deffn

@geindex transfercmd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP transfercmd}@anchor{39d2}
@deffn {Méthode} transfercmd (cmd, rest=None)

Initiate a transfer over the data connection.  If the transfer is active, send an
@code{EPRT} or  @code{PORT} command and the transfer command specified by `cmd', and
accept the connection.  If the server is passive, send an @code{EPSV} or @code{PASV}
command, connect to it, and start the transfer command.  Either way, return the
socket for the connection.

If optional `rest' is given, a @code{REST} command is sent to the server, passing
`rest' as an argument.  `rest' is usually a byte offset into the requested file,
telling the server to restart sending the file's bytes at the requested offset,
skipping over the initial bytes.  Note however that the @ref{39d2,,transfercmd()}
method converts `rest' to a string with the `encoding' parameter specified
at initialization, but no check is performed on the string's contents.  If the
server does not recognize the @code{REST} command, an @ref{39d0,,error_reply} exception
will be raised.  If this happens, simply call @ref{39d2,,transfercmd()} without a
`rest' argument.
@end deffn

@geindex ntransfercmd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP ntransfercmd}@anchor{39d6}
@deffn {Méthode} ntransfercmd (cmd, rest=None)

Like @ref{39d2,,transfercmd()}, but returns a tuple of the data connection and the
expected size of the data.  If the expected size could not be computed, @code{None}
will be returned as the expected size.  `cmd' and `rest' means the same thing as
in @ref{39d2,,transfercmd()}.
@end deffn

@geindex mlsd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP mlsd}@anchor{10a4}
@deffn {Méthode} mlsd (path='@w{'}, facts=[])

List a directory in a standardized format by using @code{MLSD} command
(
@geindex RFC; RFC 3659
RFC 3659@footnote{https://datatracker.ietf.org/doc/html/rfc3659.html}).  If `path' is omitted the current directory is assumed.
`facts' is a list of strings representing the type of information desired
(e.g. @code{["type", "size", "perm"]}).  Return a generator object yielding a
tuple of two elements for every file found in path.  First element is the
file name, the second one is a dictionary containing facts about the file
name.  Content of this dictionary might be limited by the `facts' argument
but server is not guaranteed to return all requested facts.


Ajouté dans la version 3.3.

@end deffn

@geindex nlst() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP nlst}@anchor{10a5}
@deffn {Méthode} nlst (argument[, ...])

Renvoie une liste de noms de fichiers comme celle que renvoie la commande @code{NLST}. Le paramètre optionnel `argument' est une liste de dossiers (la valeur par défaut est le répertoire courant du serveur). Plusieurs paramètres peuvent être utilisés pour passer des paramètres non standards à la commande @code{NLST}.

@cartouche
@quotation Note 
La commande @ref{10a4,,mlsd()} offre une meilleure API si votre serveur sait la gérer.
@end quotation
@end cartouche
@end deffn

@geindex dir() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP dir}@anchor{10a6}
@deffn {Méthode} dir (argument[, ...])

Produce a directory listing as returned by the @code{LIST} command, printing it to
standard output.  The optional `argument' is a directory to list (default is the
current server directory).  Multiple arguments can be used to pass non-standard
options to the @code{LIST} command.  If the last argument is a function, it is used
as a `callback' function as for @ref{39d3,,retrlines()}; the default prints to
@ref{ac4,,sys.stdout}.  This method returns @code{None}.

@cartouche
@quotation Note 
La commande @ref{10a4,,mlsd()} offre une meilleure API si votre serveur sait la gérer.
@end quotation
@end cartouche
@end deffn

@geindex rename() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP rename}@anchor{39d7}
@deffn {Méthode} rename (fromname, toname)

Renomme le fichier portant le nom `fromname' en `toname' sur le serveur.
@end deffn

@geindex delete() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP delete}@anchor{39d8}
@deffn {Méthode} delete (filename)

Remove the file named `filename' from the server.  If successful, returns the
text of the response, otherwise raises @ref{39d9,,error_perm} on permission errors or
@ref{39d0,,error_reply} on other errors.
@end deffn

@geindex cwd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP cwd}@anchor{39da}
@deffn {Méthode} cwd (pathname)

Set the current directory on the server.
@end deffn

@geindex mkd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP mkd}@anchor{39db}
@deffn {Méthode} mkd (pathname)

Crée un nouveau dossier sur le serveur.
@end deffn

@geindex pwd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP pwd}@anchor{39dc}
@deffn {Méthode} pwd ()

Renvoie le chemin d'accès au répertoire courant sur le serveur.
@end deffn

@geindex rmd() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP rmd}@anchor{39dd}
@deffn {Méthode} rmd (dirname)

Supprime le dossier portant le nom `dirname' sur le serveur.
@end deffn

@geindex size() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP size}@anchor{39de}
@deffn {Méthode} size (filename)

Request the size of the file named `filename' on the server.  On success, the
size of the file is returned as an integer, otherwise @code{None} is returned.
Note that the @code{SIZE} command is not  standardized, but is supported by many
common server implementations.
@end deffn

@geindex quit() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP quit}@anchor{39df}
@deffn {Méthode} quit ()

Send a @code{QUIT} command to the server and close the connection. This is the
"polite" way to close a connection, but it may raise an exception if the server
responds with an error to the @code{QUIT} command.  This implies a call to the
@ref{39e0,,close()} method which renders the @ref{8e7,,FTP} instance useless for
subsequent calls (see below).
@end deffn

@geindex close() (méthode ftplib.FTP)
@anchor{library/ftplib ftplib FTP close}@anchor{39e0}
@deffn {Méthode} close ()

Close the connection unilaterally.  This should not be applied to an already
closed connection such as after a successful call to @ref{39df,,quit()}.
After this call the @ref{8e7,,FTP} instance should not be used any more (after
a call to @ref{39e0,,close()} or @ref{39df,,quit()} you cannot reopen the
connection by issuing another @ref{39cc,,login()} method).
@end deffn
@end deffn

@node FTP_TLS objects,Module variables,FTP objects,Référence<4>
@anchor{library/ftplib ftp-tls-objects}@anchor{39e1}
@subsubsection FTP_TLS objects


@geindex FTP_TLS (classe dans ftplib)
@anchor{library/ftplib ftplib FTP_TLS}@anchor{8e8}
@deffn {Classe} ftplib.FTP_TLS (host='@w{'}, user='@w{'}, passwd='@w{'}, acct='@w{'}, *, context=None, timeout=None, source_address=None, encoding='utf-8')

An @ref{8e7,,FTP} subclass which adds TLS support to FTP as described in
@geindex RFC; RFC 4217
RFC 4217@footnote{https://datatracker.ietf.org/doc/html/rfc4217.html}.
Connect to port 21 implicitly securing the FTP control connection
before authenticating.

@cartouche
@quotation Note 
The user must explicitly secure the data connection
by calling the @ref{39e2,,prot_p()} method.
@end quotation
@end cartouche

@*Paramètres: 

@itemize *

@item 
@code{host} (@ref{435,,str}) -- The hostname to connect to.
If given, @code{connect(host)} is implicitly called by the constructor.

@item 
@code{user} (@ref{435,,str}) -- The username to log in with (default: @code{'anonymous'}).
If given, @code{login(host, passwd, acct)} is implicitly called
by the constructor.

@item 
@code{passwd} (@ref{435,,str}) -- The password to use when logging in.
If not given, and if `passwd' is the empty string or @code{"-"},
a password will be automatically generated.

@item 
@code{acct} (@ref{435,,str}) -- Account information to be used for the @code{ACCT} FTP command.
Few systems implement this.
See RFC-959@footnote{https://datatracker.ietf.org/doc/html/rfc959.html}
for more details.

@item 
@code{context} (@ref{291,,ssl.SSLContext}) -- An SSL context object which allows bundling SSL configuration options,
certificates and private keys into a single, potentially long-lived,
structure.
Please read @ref{32a2,,Security considerations} for best practices.

@item 
@code{timeout} (@ref{2eb,,float}@code{ | }@code{None}) -- A timeout in seconds for blocking operations like @ref{39c9,,connect()}
(default: the global default timeout setting).

@item 
@code{source_address} (@ref{366,,tuple}@code{ | }@code{None}) -- A 2-tuple @code{(host, port)} for the socket to bind to as its
source address before connecting.

@item 
@code{encoding} (@ref{435,,str}) -- The encoding for directories and filenames (default: @code{'utf-8'}).
@end itemize



Ajouté dans la version 3.2.



Modifié dans la version 3.3: Added the `source_address' parameter.



Modifié dans la version 3.4: The class now supports hostname check with
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).



Modifié dans la version 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{1ff,,ValueError} to prevent the creation of a non-blocking socket.
The `encoding' parameter was added, and the default was changed from
Latin-1 to UTF-8 to follow 
@geindex RFC; RFC 2640
RFC 2640@footnote{https://datatracker.ietf.org/doc/html/rfc2640.html}.



Modifié dans la version 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.


Voici un exemple de session utilisant la classe @ref{8e8,,FTP_TLS} :

@example
>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']
@end example

@code{FTP_TLS} class inherits from @ref{8e7,,FTP},
defining these additional methods and attributes:

@geindex ssl_version (attribut ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS ssl_version}@anchor{39e3}
@deffn {Attribut} ssl_version

The SSL version to use (defaults to @ref{33c8,,ssl.PROTOCOL_SSLv23}).
@end deffn

@geindex auth() (méthode ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS auth}@anchor{39e4}
@deffn {Méthode} auth ()

Set up a secure control connection by using TLS or SSL, depending on what
is specified in the @ref{39e3,,ssl_version} attribute.


Modifié dans la version 3.4: The method now supports hostname check with
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).

@end deffn

@geindex ccc() (méthode ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS ccc}@anchor{10a3}
@deffn {Méthode} ccc ()

Revert control channel back to plaintext.  This can be useful to take
advantage of firewalls that know how to handle NAT with non-secure FTP
without opening fixed ports.


Ajouté dans la version 3.3.

@end deffn

@geindex prot_p() (méthode ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS prot_p}@anchor{39e2}
@deffn {Méthode} prot_p ()

Établit une connexion de données sécurisée.
@end deffn

@geindex prot_c() (méthode ftplib.FTP_TLS)
@anchor{library/ftplib ftplib FTP_TLS prot_c}@anchor{39e5}
@deffn {Méthode} prot_c ()

Établit une connexion de données non sécurisées.
@end deffn
@end deffn

@node Module variables,,FTP_TLS objects,Référence<4>
@anchor{library/ftplib module-variables}@anchor{39e6}
@subsubsection Module variables


@geindex error_reply
@anchor{library/ftplib ftplib error_reply}@anchor{39d0}
@deffn {Exception} ftplib.error_reply

Exception levée lorsqu'une réponse inattendue est reçue du serveur.
@end deffn

@geindex error_temp
@anchor{library/ftplib ftplib error_temp}@anchor{39e7}
@deffn {Exception} ftplib.error_temp

Exception levée lorsqu'un code d'erreur signifiant une erreur temporaire (code de réponse dans l'intervalle 400-499) est reçu.
@end deffn

@geindex error_perm
@anchor{library/ftplib ftplib error_perm}@anchor{39d9}
@deffn {Exception} ftplib.error_perm

Exception levée lorsqu'un code d'erreur signifiant une erreur permanente (code de réponse dans l'intervalle 500-599) est reçu.
@end deffn

@geindex error_proto
@anchor{library/ftplib ftplib error_proto}@anchor{39e8}
@deffn {Exception} ftplib.error_proto

Exception levée lorsqu'une réponse reçue du serveur ne correspond pas aux à la spécification de File Transfer Protocol, c.-à-d. qu'elle doit commencer par un chiffre dans l'intervalle 1-5.
@end deffn

@geindex all_errors (dans le module ftplib)
@anchor{library/ftplib ftplib all_errors}@anchor{39e9}
@deffn {Données} ftplib.all_errors

The set of all exceptions (as a tuple) that methods of @ref{8e7,,FTP}
instances may raise as a result of problems with the FTP connection (as
opposed to programming errors made by the caller).  This set includes the
four exceptions listed above as well as @ref{40d,,OSError} and @ref{12b7,,EOFError}.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{9a,,netrc}

Parser for the @code{.netrc} file format.  The file @code{.netrc} is
typically used by FTP clients to load user authentication information
before prompting the user.
@end table


@node poplib --- POP3 protocol client,imaplib --- IMAP4 protocol client,ftplib --- FTP protocol client,Gestion des protocoles internet
@anchor{library/poplib doc}@anchor{39ea}@anchor{library/poplib module-poplib}@anchor{ab}@anchor{library/poplib poplib-pop3-protocol-client}@anchor{39eb}
@subsection @code{poplib} --- POP3 protocol client


@geindex module; poplib

@c revised by ESR, January 2000

`Code source :' Lib/poplib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/poplib.py}

@geindex POP3;protocol


__________________________________________________________________


This module defines a class, @ref{911,,POP3}, which encapsulates a connection to a
POP3 server and implements the protocol as defined in 
@geindex RFC; RFC 1939
RFC 1939@footnote{https://datatracker.ietf.org/doc/html/rfc1939.html}. The
@ref{911,,POP3} class supports both the minimal and optional command sets from
@geindex RFC; RFC 1939
RFC 1939@footnote{https://datatracker.ietf.org/doc/html/rfc1939.html}. The @ref{911,,POP3} class also supports the @code{STLS} command introduced
in 
@geindex RFC; RFC 2595
RFC 2595@footnote{https://datatracker.ietf.org/doc/html/rfc2595.html} to enable encrypted communication on an already established connection.

Additionally, this module provides a class @ref{912,,POP3_SSL}, which provides
support for connecting to POP3 servers that use SSL as an underlying protocol
layer.

Note that POP3, though widely supported, is obsolescent.  The implementation
quality of POP3 servers varies widely, and too many are quite poor. If your
mailserver supports IMAP, you would be better off using the
@ref{8f0,,imaplib.IMAP4} class, as IMAP servers tend to be better implemented.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

The @ref{ab,,poplib} module provides two classes:

@geindex POP3 (classe dans poplib)
@anchor{library/poplib poplib POP3}@anchor{911}
@deffn {Classe} poplib.POP3 (host, port=POP3_PORT[, timeout])

This class implements the actual POP3 protocol.  The connection is created when
the instance is initialized. If `port' is omitted, the standard POP3 port (110)
is used. The optional `timeout' parameter specifies a timeout in seconds for the
connection attempt (if not specified, the global default timeout setting will
be used).

Raises an @ref{1848,,auditing event} @code{poplib.connect} with arguments @code{self}, @code{host}, @code{port}.


All commands will raise an @ref{1848,,auditing event}
@code{poplib.putline} with arguments @code{self} and @code{line},
where @code{line} is the bytes about to be sent to the remote host.



Modifié dans la version 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{1ff,,ValueError} to prevent the creation of a non-blocking socket.

@end deffn

@geindex POP3_SSL (classe dans poplib)
@anchor{library/poplib poplib POP3_SSL}@anchor{912}
@deffn {Classe} poplib.POP3_SSL (host, port=POP3_SSL_PORT, *, timeout=None, context=None)

This is a subclass of @ref{911,,POP3} that connects to the server over an SSL
encrypted socket.  If `port' is not specified, 995, the standard POP3-over-SSL
port is used.  `timeout' works as in the @ref{911,,POP3} constructor.
`context' is an optional @ref{291,,ssl.SSLContext} object which allows
bundling SSL configuration options, certificates and private keys into a
single (potentially long-lived) structure.  Please read @ref{32a2,,Security considerations}
for best practices.

Raises an @ref{1848,,auditing event} @code{poplib.connect} with arguments @code{self}, @code{host}, @code{port}.


All commands will raise an @ref{1848,,auditing event}
@code{poplib.putline} with arguments @code{self} and @code{line},
where @code{line} is the bytes about to be sent to the remote host.



Modifié dans la version 3.2: `context' parameter added.



Modifié dans la version 3.4: The class now supports hostname check with
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).



Modifié dans la version 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{1ff,,ValueError} to prevent the creation of a non-blocking socket.



Modifié dans la version 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.

@end deffn

One exception is defined as an attribute of the @ref{ab,,poplib} module:

@geindex error_proto
@anchor{library/poplib poplib error_proto}@anchor{117b}
@deffn {Exception} poplib.error_proto

Exception raised on any errors from this module (errors from @ref{cb,,socket}
module are not caught). The reason for the exception is passed to the
constructor as a string.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{73,,imaplib}

The standard Python IMAP module.

@item Frequently Asked Questions About Fetchmail@footnote{http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html}

The FAQ for the @code{fetchmail} POP/IMAP client collects information on
POP3 server variations and RFC noncompliance that may be useful if you need to
write an application based on the POP protocol.
@end table


@menu
* POP3 Objects:: 
* POP3 Example:: 

@end menu

@node POP3 Objects,POP3 Example,,poplib --- POP3 protocol client
@anchor{library/poplib id1}@anchor{39ec}@anchor{library/poplib pop3-objects}@anchor{39ed}
@subsubsection POP3 Objects


All POP3 commands are represented by methods of the same name, in lowercase;
most return the response text sent by the server.

A @ref{911,,POP3} instance has the following methods:

@geindex set_debuglevel() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 set_debuglevel}@anchor{39ee}
@deffn {Méthode} POP3.set_debuglevel (level)

Set the instance's debugging level.  This controls the amount of debugging
output printed.  The default, @code{0}, produces no debugging output.  A value of
@code{1} produces a moderate amount of debugging output, generally a single line
per request.  A value of @code{2} or higher produces the maximum amount of
debugging output, logging each line sent and received on the control connection.
@end deffn

@geindex getwelcome() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 getwelcome}@anchor{39ef}
@deffn {Méthode} POP3.getwelcome ()

Returns the greeting string sent by the POP3 server.
@end deffn

@geindex capa() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 capa}@anchor{f67}
@deffn {Méthode} POP3.capa ()

Query the server's capabilities as specified in 
@geindex RFC; RFC 2449
RFC 2449@footnote{https://datatracker.ietf.org/doc/html/rfc2449.html}.
Returns a dictionary in the form @code{@{'name': ['param'...]@}}.


Ajouté dans la version 3.4.

@end deffn

@geindex user() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 user}@anchor{39f0}
@deffn {Méthode} POP3.user (username)

Send user command, response should indicate that a password is required.
@end deffn

@geindex pass_() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 pass_}@anchor{39f1}
@deffn {Méthode} POP3.pass_ (password)

Send password, response includes message count and mailbox size. Note: the
mailbox on the server is locked until @ref{117a,,quit()} is called.
@end deffn

@geindex apop() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 apop}@anchor{39f2}
@deffn {Méthode} POP3.apop (user, secret)

Use the more secure APOP authentication to log into the POP3 server.
@end deffn

@geindex rpop() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 rpop}@anchor{39f3}
@deffn {Méthode} POP3.rpop (user)

Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
@end deffn

@geindex stat() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 stat}@anchor{39f4}
@deffn {Méthode} POP3.stat ()

Get mailbox status.  The result is a tuple of 2 integers: @code{(message count,
mailbox size)}.
@end deffn

@geindex list() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 list}@anchor{39f5}
@deffn {Méthode} POP3.list ([which])

Request message list, result is in the form @code{(response, ['mesg_num octets',
...], octets)}. If `which' is set, it is the message to list.
@end deffn

@geindex retr() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 retr}@anchor{39f6}
@deffn {Méthode} POP3.retr (which)

Retrieve whole message number `which', and set its seen flag. Result is in form
@code{(response, ['line', ...], octets)}.
@end deffn

@geindex dele() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 dele}@anchor{39f7}
@deffn {Méthode} POP3.dele (which)

Flag message number `which' for deletion.  On most servers deletions are not
actually performed until QUIT (the major exception is Eudora QPOP, which
deliberately violates the RFCs by doing pending deletes on any disconnect).
@end deffn

@geindex rset() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 rset}@anchor{39f8}
@deffn {Méthode} POP3.rset ()

Remove any deletion marks for the mailbox.
@end deffn

@geindex noop() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 noop}@anchor{39f9}
@deffn {Méthode} POP3.noop ()

Do nothing.  Might be used as a keep-alive.
@end deffn

@geindex quit() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 quit}@anchor{117a}
@deffn {Méthode} POP3.quit ()

Signoff:  commit changes, unlock mailbox, drop connection.
@end deffn

@geindex top() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 top}@anchor{39fa}
@deffn {Méthode} POP3.top (which, howmuch)

Retrieves the message header plus `howmuch' lines of the message after the
header of message number `which'. Result is in form @code{(response, ['line', ...],
octets)}.

The POP3 TOP command this method uses, unlike the RETR command, doesn't set the
message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is
frequently broken in off-brand servers. Test this method by hand against the
POP3 servers you will use before trusting it.
@end deffn

@geindex uidl() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 uidl}@anchor{39fb}
@deffn {Méthode} POP3.uidl (which=None)

Return message digest (unique id) list. If `which' is specified, result contains
the unique id for that message in the form @code{'response mesgnum uid}, otherwise
result is list @code{(response, ['mesgnum uid', ...], octets)}.
@end deffn

@geindex utf8() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 utf8}@anchor{e37}
@deffn {Méthode} POP3.utf8 ()

Try to switch to UTF-8 mode. Returns the server response if successful,
raises @ref{117b,,error_proto} if not. Specified in 
@geindex RFC; RFC 6856
RFC 6856@footnote{https://datatracker.ietf.org/doc/html/rfc6856.html}.


Ajouté dans la version 3.5.

@end deffn

@geindex stls() (méthode poplib.POP3)
@anchor{library/poplib poplib POP3 stls}@anchor{f68}
@deffn {Méthode} POP3.stls (context=None)

Start a TLS session on the active connection as specified in 
@geindex RFC; RFC 2595
RFC 2595@footnote{https://datatracker.ietf.org/doc/html/rfc2595.html}.
This is only allowed before user authentication

`context' parameter is a @ref{291,,ssl.SSLContext} object which allows
bundling SSL configuration options, certificates and private keys into
a single (potentially long-lived) structure.  Please read @ref{32a2,,Security considerations}
for best practices.

This method supports hostname checking via
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).


Ajouté dans la version 3.4.

@end deffn

Instances of @ref{912,,POP3_SSL} have no additional methods. The interface of this
subclass is identical to its parent.

@node POP3 Example,,POP3 Objects,poplib --- POP3 protocol client
@anchor{library/poplib id2}@anchor{39fc}@anchor{library/poplib pop3-example}@anchor{39fd}
@subsubsection POP3 Example


Here is a minimal example (without error checking) that opens a mailbox and
retrieves and prints all messages:

@example
import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print(j)
@end example

At the end of the module, there is a test section that contains a more extensive
example of usage.

@node imaplib --- IMAP4 protocol client,smtplib --- SMTP protocol client,poplib --- POP3 protocol client,Gestion des protocoles internet
@anchor{library/imaplib doc}@anchor{39fe}@anchor{library/imaplib imaplib-imap4-protocol-client}@anchor{39ff}@anchor{library/imaplib module-imaplib}@anchor{73}
@subsection @code{imaplib} --- IMAP4 protocol client


@geindex module; imaplib

@c revised by ESR, January 2000

@c changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002

@c changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
@c November 2002

`Code source :' Lib/imaplib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/imaplib.py}

@geindex IMAP4;protocol
@geindex IMAP4_SSL;protocol
@geindex IMAP4_stream;protocol


__________________________________________________________________


This module defines three classes, @ref{8f0,,IMAP4}, @ref{8f1,,IMAP4_SSL} and
@ref{8f3,,IMAP4_stream}, which encapsulate a connection to an IMAP4 server and
implement a large subset of the IMAP4rev1 client protocol as defined in
@geindex RFC; RFC 2060
RFC 2060@footnote{https://datatracker.ietf.org/doc/html/rfc2060.html}. It is backward compatible with IMAP4 (
@geindex RFC; RFC 1730
RFC 1730@footnote{https://datatracker.ietf.org/doc/html/rfc1730.html}) servers, but
note that the @code{STATUS} command is not supported in IMAP4.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Three classes are provided by the @ref{73,,imaplib} module, @ref{8f0,,IMAP4} is the
base class:

@geindex IMAP4 (classe dans imaplib)
@anchor{library/imaplib imaplib IMAP4}@anchor{8f0}
@deffn {Classe} imaplib.IMAP4 (host='@w{'}, port=IMAP4_PORT, timeout=None)

This class implements the actual IMAP4 protocol.  The connection is created and
protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
initialized. If `host' is not specified, @code{'@w{'}} (the local host) is used. If
`port' is omitted, the standard IMAP4 port (143) is used. The optional `timeout'
parameter specifies a timeout in seconds for the connection attempt.
If timeout is not given or is @code{None}, the global default socket timeout is used.

The @ref{8f0,,IMAP4} class supports the @ref{5bc,,with} statement.  When used
like this, the IMAP4 @code{LOGOUT} command is issued automatically when the
@code{with} statement exits.  E.g.:

@example
>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
@end example


Modifié dans la version 3.5: La prise en charge de l'instruction @ref{5bc,,with} a été ajoutée.



Modifié dans la version 3.9: The optional `timeout' parameter was added.

@end deffn

Three exceptions are defined as attributes of the @ref{8f0,,IMAP4} class:

@geindex IMAP4.error
@anchor{library/imaplib imaplib IMAP4 error}@anchor{3a00}
@deffn {Exception} IMAP4.error

Exception raised on any errors.  The reason for the exception is passed to the
constructor as a string.
@end deffn

@geindex IMAP4.abort
@anchor{library/imaplib imaplib IMAP4 abort}@anchor{3a01}
@deffn {Exception} IMAP4.abort

IMAP4 server errors cause this exception to be raised.  This is a sub-class of
@ref{3a00,,IMAP4.error}.  Note that closing the instance and instantiating a new one
will usually allow recovery from this exception.
@end deffn

@geindex IMAP4.readonly
@anchor{library/imaplib imaplib IMAP4 readonly}@anchor{3a02}
@deffn {Exception} IMAP4.readonly

This exception is raised when a writable mailbox has its status changed by the
server.  This is a sub-class of @ref{3a00,,IMAP4.error}.  Some other client now has
write permission, and the mailbox will need to be re-opened to re-obtain write
permission.
@end deffn

There's also a subclass for secure connections:

@geindex IMAP4_SSL (classe dans imaplib)
@anchor{library/imaplib imaplib IMAP4_SSL}@anchor{8f1}
@deffn {Classe} imaplib.IMAP4_SSL (host='@w{'}, port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)

This is a subclass derived from @ref{8f0,,IMAP4} that connects over an SSL
encrypted socket (to use this class you need a socket module that was compiled
with SSL support).  If `host' is not specified, @code{'@w{'}} (the local host) is used.
If `port' is omitted, the standard IMAP4-over-SSL port (993) is used.
`ssl_context' is a @ref{291,,ssl.SSLContext} object which allows bundling
SSL configuration options, certificates and private keys into a single
(potentially long-lived) structure.  Please read @ref{32a2,,Security considerations} for
best practices.

The optional `timeout' parameter specifies a timeout in seconds for the
connection attempt. If timeout is not given or is @code{None}, the global default
socket timeout is used.


Modifié dans la version 3.3: `ssl_context' parameter was added.



Modifié dans la version 3.4: The class now supports hostname check with
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).



Modifié dans la version 3.9: The optional `timeout' parameter was added.



Modifié dans la version 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.

@end deffn

The second subclass allows for connections created by a child process:

@geindex IMAP4_stream (classe dans imaplib)
@anchor{library/imaplib imaplib IMAP4_stream}@anchor{8f3}
@deffn {Classe} imaplib.IMAP4_stream (command)

This is a subclass derived from @ref{8f0,,IMAP4} that connects to the
@code{stdin/stdout} file descriptors created by passing `command' to
@code{subprocess.Popen()}.
@end deffn

The following utility functions are defined:

@geindex Internaldate2tuple() (dans le module imaplib)
@anchor{library/imaplib imaplib Internaldate2tuple}@anchor{3a03}
@deffn {Fonction} imaplib.Internaldate2tuple (datestr)

Parse an IMAP4 @code{INTERNALDATE} string and return corresponding local
time.  The return value is a @ref{cd8,,time.struct_time} tuple or
@code{None} if the string has wrong format.
@end deffn

@geindex Int2AP() (dans le module imaplib)
@anchor{library/imaplib imaplib Int2AP}@anchor{3a04}
@deffn {Fonction} imaplib.Int2AP (num)

Converts an integer into a bytes representation using characters from the set
[@code{A} .. @code{P}].
@end deffn

@geindex ParseFlags() (dans le module imaplib)
@anchor{library/imaplib imaplib ParseFlags}@anchor{3a05}
@deffn {Fonction} imaplib.ParseFlags (flagstr)

Converts an IMAP4 @code{FLAGS} response to a tuple of individual flags.
@end deffn

@geindex Time2Internaldate() (dans le module imaplib)
@anchor{library/imaplib imaplib Time2Internaldate}@anchor{3a06}
@deffn {Fonction} imaplib.Time2Internaldate (date_time)

Convert `date_time' to an IMAP4 @code{INTERNALDATE} representation.
The return value is a string in the form: @code{"DD-Mmm-YYYY HH:MM:SS
+HHMM"} (including double-quotes).  The `date_time' argument can
be a number (int or float) representing seconds since epoch (as
returned by @ref{251,,time.time()}), a 9-tuple representing local time
an instance of @ref{cd8,,time.struct_time} (as returned by
@ref{14af,,time.localtime()}), an aware instance of
@ref{1c7,,datetime.datetime}, or a double-quoted string.  In the last
case, it is assumed to already be in the correct format.
@end deffn

Note that IMAP4 message numbers change as the mailbox changes; in particular,
after an @code{EXPUNGE} command performs deletions the remaining messages are
renumbered. So it is highly advisable to use UIDs instead, with the UID command.

At the end of the module, there is a test section that contains a more extensive
example of usage.


@subsubheading Voir aussi


Documents describing the protocol, sources for servers
implementing it, by the University of Washington's IMAP Information Center
can all be found at (`Source Code') @indicateurl{https://github.com/uw-imap/imap} (`Not Maintained').


@menu
* IMAP4 Objects:: 
* IMAP4 Example:: 

@end menu

@node IMAP4 Objects,IMAP4 Example,,imaplib --- IMAP4 protocol client
@anchor{library/imaplib id1}@anchor{3a07}@anchor{library/imaplib imap4-objects}@anchor{3a08}
@subsubsection IMAP4 Objects


All IMAP4rev1 commands are represented by methods of the same name, either
uppercase or lowercase.

All arguments to commands are converted to strings, except for @code{AUTHENTICATE},
and the last argument to @code{APPEND} which is passed as an IMAP4 literal.  If
necessary (the string contains IMAP4 protocol-sensitive characters and isn't
enclosed with either parentheses or double quotes) each string is quoted.
However, the `password' argument to the @code{LOGIN} command is always quoted. If
you want to avoid having an argument string quoted (eg: the `flags' argument to
@code{STORE}) then enclose the string in parentheses (eg: @code{r'(\Deleted)'}).

Each command returns a tuple: @code{(type, [data, ...])} where `type' is usually
@code{'OK'} or @code{'NO'}, and `data' is either the text from the command response,
or mandated results from the command. Each `data' is either a @code{bytes}, or a
tuple. If a tuple, then the first part is the header of the response, and the
second part contains the data (ie: 'literal' value).

The `message_set' options to commands below is a string specifying one or more
messages to be acted upon.  It may be a simple message number (@code{'1'}), a range
of message numbers (@code{'2:4'}), or a group of non-contiguous ranges separated by
commas (@code{'1:3,6:9'}).  A range can contain an asterisk to indicate an infinite
upper bound (@code{'3:*'}).

An @ref{8f0,,IMAP4} instance has the following methods:

@geindex append() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 append}@anchor{3a09}
@deffn {Méthode} IMAP4.append (mailbox, flags, date_time, message)

Append `message' to named mailbox.
@end deffn

@geindex authenticate() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 authenticate}@anchor{3a0a}
@deffn {Méthode} IMAP4.authenticate (mechanism, authobject)

Authenticate command --- requires response processing.

`mechanism' specifies which authentication mechanism is to be used - it should
appear in the instance variable @code{capabilities} in the form @code{AUTH=mechanism}.

`authobject' must be a callable object:

@example
data = authobject(response)
@end example

It will be called to process server continuation responses; the `response'
argument it is passed will be @code{bytes}.  It should return @code{bytes} `data'
that will be base64 encoded and sent to the server.  It should return
@code{None} if the client abort response @code{*} should be sent instead.


Modifié dans la version 3.5: string usernames and passwords are now encoded to @code{utf-8} instead of
being limited to ASCII.

@end deffn

@geindex check() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 check}@anchor{3a0b}
@deffn {Méthode} IMAP4.check ()

Checkpoint mailbox on server.
@end deffn

@geindex close() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 close}@anchor{8f5}
@deffn {Méthode} IMAP4.close ()

Close currently selected mailbox. Deleted messages are removed from writable
mailbox. This is the recommended command before @code{LOGOUT}.
@end deffn

@geindex copy() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 copy}@anchor{3a0c}
@deffn {Méthode} IMAP4.copy (message_set, new_mailbox)

Copy `message_set' messages onto end of `new_mailbox'.
@end deffn

@geindex create() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 create}@anchor{3a0d}
@deffn {Méthode} IMAP4.create (mailbox)

Create new mailbox named `mailbox'.
@end deffn

@geindex delete() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 delete}@anchor{3a0e}
@deffn {Méthode} IMAP4.delete (mailbox)

Delete old mailbox named `mailbox'.
@end deffn

@geindex deleteacl() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 deleteacl}@anchor{3a0f}
@deffn {Méthode} IMAP4.deleteacl (mailbox, who)

Delete the ACLs (remove any rights) set for who on mailbox.
@end deffn

@geindex enable() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 enable}@anchor{dfa}
@deffn {Méthode} IMAP4.enable (capability)

Enable `capability' (see 
@geindex RFC; RFC 5161
RFC 5161@footnote{https://datatracker.ietf.org/doc/html/rfc5161.html}).  Most capabilities do not need to be
enabled.  Currently only the @code{UTF8=ACCEPT} capability is supported
(see 
@geindex RFC; RFC 6855
RFC 6855@footnote{https://datatracker.ietf.org/doc/html/rfc6855.html}).


Ajouté dans la version 3.5: The @ref{dfa,,enable()} method itself, and 
@geindex RFC; RFC 6855
RFC 6855@footnote{https://datatracker.ietf.org/doc/html/rfc6855.html} support.

@end deffn

@geindex expunge() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 expunge}@anchor{3a10}
@deffn {Méthode} IMAP4.expunge ()

Permanently remove deleted items from selected mailbox. Generates an @code{EXPUNGE}
response for each deleted message. Returned data contains a list of @code{EXPUNGE}
message numbers in order received.
@end deffn

@geindex fetch() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 fetch}@anchor{3a11}
@deffn {Méthode} IMAP4.fetch (message_set, message_parts)

Fetch (parts of) messages.  `message_parts' should be a string of message part
names enclosed within parentheses, eg: @code{"(UID BODY[TEXT])"}.  Returned data
are tuples of message part envelope and data.
@end deffn

@geindex getacl() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getacl}@anchor{3a12}
@deffn {Méthode} IMAP4.getacl (mailbox)

Get the @code{ACL}s for `mailbox'. The method is non-standard, but is supported
by the @code{Cyrus} server.
@end deffn

@geindex getannotation() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getannotation}@anchor{3a13}
@deffn {Méthode} IMAP4.getannotation (mailbox, entry, attribute)

Retrieve the specified @code{ANNOTATION}s for `mailbox'. The method is
non-standard, but is supported by the @code{Cyrus} server.
@end deffn

@geindex getquota() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getquota}@anchor{3a14}
@deffn {Méthode} IMAP4.getquota (root)

Get the @code{quota} `root''s resource usage and limits. This method is part of the
IMAP4 QUOTA extension defined in rfc2087.
@end deffn

@geindex getquotaroot() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 getquotaroot}@anchor{3a15}
@deffn {Méthode} IMAP4.getquotaroot (mailbox)

Get the list of @code{quota} @code{roots} for the named `mailbox'. This method is part
of the IMAP4 QUOTA extension defined in rfc2087.
@end deffn

@geindex list() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 list}@anchor{3a16}
@deffn {Méthode} IMAP4.list ([directory[, pattern]])

List mailbox names in `directory' matching `pattern'.  `directory' defaults to
the top-level mail folder, and `pattern' defaults to match anything.  Returned
data contains a list of @code{LIST} responses.
@end deffn

@geindex login() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 login}@anchor{3a17}
@deffn {Méthode} IMAP4.login (user, password)

Identify the client using a plaintext password. The `password' will be quoted.
@end deffn

@geindex login_cram_md5() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 login_cram_md5}@anchor{3a18}
@deffn {Méthode} IMAP4.login_cram_md5 (user, password)

Force use of @code{CRAM-MD5} authentication when identifying the client to protect
the password.  Will only work if the server @code{CAPABILITY} response includes the
phrase @code{AUTH=CRAM-MD5}.
@end deffn

@geindex logout() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 logout}@anchor{3a19}
@deffn {Méthode} IMAP4.logout ()

Shutdown connection to server. Returns server @code{BYE} response.


Modifié dans la version 3.8: The method no longer ignores silently arbitrary exceptions.

@end deffn

@geindex lsub() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 lsub}@anchor{3a1a}
@deffn {Méthode} IMAP4.lsub (directory='""', pattern='*')

List subscribed mailbox names in directory matching pattern. `directory'
defaults to the top level directory and `pattern' defaults to match any mailbox.
Returned data are tuples of message part envelope and data.
@end deffn

@geindex myrights() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 myrights}@anchor{3a1b}
@deffn {Méthode} IMAP4.myrights (mailbox)

Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
@end deffn

@geindex namespace() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 namespace}@anchor{3a1c}
@deffn {Méthode} IMAP4.namespace ()

Returns IMAP namespaces as defined in 
@geindex RFC; RFC 2342
RFC 2342@footnote{https://datatracker.ietf.org/doc/html/rfc2342.html}.
@end deffn

@geindex noop() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 noop}@anchor{3a1d}
@deffn {Méthode} IMAP4.noop ()

Send @code{NOOP} to server.
@end deffn

@geindex open() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 open}@anchor{8f2}
@deffn {Méthode} IMAP4.open (host, port, timeout=None)

Opens socket to `port' at `host'. The optional `timeout' parameter
specifies a timeout in seconds for the connection attempt.
If timeout is not given or is @code{None}, the global default socket timeout
is used. Also note that if the `timeout' parameter is set to be zero,
it will raise a @ref{1ff,,ValueError} to reject creating a non-blocking socket.
This method is implicitly called by the @ref{8f0,,IMAP4} constructor.
The connection objects established by this method will be used in
the @ref{3a1e,,IMAP4.read()}, @ref{3a1f,,IMAP4.readline()}, @ref{3a20,,IMAP4.send()},
and @ref{3a21,,IMAP4.shutdown()} methods. You may override this method.

Raises an @ref{1848,,auditing event} @code{imaplib.open} with arguments @code{self}, @code{host}, @code{port}.


Modifié dans la version 3.9: The `timeout' parameter was added.

@end deffn

@geindex partial() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 partial}@anchor{3a22}
@deffn {Méthode} IMAP4.partial (message_num, message_part, start, length)

Fetch truncated part of a message. Returned data is a tuple of message part
envelope and data.
@end deffn

@geindex proxyauth() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 proxyauth}@anchor{3a23}
@deffn {Méthode} IMAP4.proxyauth (user)

Assume authentication as `user'. Allows an authorised administrator to proxy
into any user's mailbox.
@end deffn

@geindex read() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 read}@anchor{3a1e}
@deffn {Méthode} IMAP4.read (size)

Reads `size' bytes from the remote server. You may override this method.
@end deffn

@geindex readline() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 readline}@anchor{3a1f}
@deffn {Méthode} IMAP4.readline ()

Reads one line from the remote server. You may override this method.
@end deffn

@geindex recent() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 recent}@anchor{3a24}
@deffn {Méthode} IMAP4.recent ()

Prompt server for an update. Returned data is @code{None} if no new messages, else
value of @code{RECENT} response.
@end deffn

@geindex rename() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 rename}@anchor{3a25}
@deffn {Méthode} IMAP4.rename (oldmailbox, newmailbox)

Rename mailbox named `oldmailbox' to `newmailbox'.
@end deffn

@geindex response() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 response}@anchor{3a26}
@deffn {Méthode} IMAP4.response (code)

Return data for response `code' if received, or @code{None}. Returns the given
code, instead of the usual type.
@end deffn

@geindex search() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 search}@anchor{3a27}
@deffn {Méthode} IMAP4.search (charset, criterion[, ...])

Search mailbox for matching messages.  `charset' may be @code{None}, in which case
no @code{CHARSET} will be specified in the request to the server.  The IMAP
protocol requires that at least one criterion be specified; an exception will be
raised when the server returns an error.  `charset' must be @code{None} if
the @code{UTF8=ACCEPT} capability was enabled using the @ref{dfa,,enable()}
command.

Exemple :

@example
# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')
@end example
@end deffn

@geindex select() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 select}@anchor{3a28}
@deffn {Méthode} IMAP4.select (mailbox='INBOX', readonly=False)

Select a mailbox. Returned data is the count of messages in `mailbox'
(@code{EXISTS} response).  The default `mailbox' is @code{'INBOX'}.  If the `readonly'
flag is set, modifications to the mailbox are not allowed.
@end deffn

@geindex send() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 send}@anchor{3a20}
@deffn {Méthode} IMAP4.send (data)

Sends @code{data} to the remote server. You may override this method.

Raises an @ref{1848,,auditing event} @code{imaplib.send} with arguments @code{self}, @code{data}.
@end deffn

@geindex setacl() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 setacl}@anchor{3a29}
@deffn {Méthode} IMAP4.setacl (mailbox, who, what)

Set an @code{ACL} for `mailbox'. The method is non-standard, but is supported by
the @code{Cyrus} server.
@end deffn

@geindex setannotation() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 setannotation}@anchor{3a2a}
@deffn {Méthode} IMAP4.setannotation (mailbox, entry, attribute[, ...])

Set @code{ANNOTATION}s for `mailbox'. The method is non-standard, but is
supported by the @code{Cyrus} server.
@end deffn

@geindex setquota() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 setquota}@anchor{3a2b}
@deffn {Méthode} IMAP4.setquota (root, limits)

Set the @code{quota} `root''s resource `limits'. This method is part of the IMAP4
QUOTA extension defined in rfc2087.
@end deffn

@geindex shutdown() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 shutdown}@anchor{3a21}
@deffn {Méthode} IMAP4.shutdown ()

Close connection established in @code{open}.  This method is implicitly
called by @ref{3a19,,IMAP4.logout()}.  You may override this method.
@end deffn

@geindex socket() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 socket}@anchor{3a2c}
@deffn {Méthode} IMAP4.socket ()

Returns socket instance used to connect to server.
@end deffn

@geindex sort() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 sort}@anchor{3a2d}
@deffn {Méthode} IMAP4.sort (sort_criteria, charset, search_criterion[, ...])

The @code{sort} command is a variant of @code{search} with sorting semantics for the
results.  Returned data contains a space separated list of matching message
numbers.

Sort has two arguments before the `search_criterion' argument(s); a
parenthesized list of `sort_criteria', and the searching `charset'.  Note that
unlike @code{search}, the searching `charset' argument is mandatory.  There is also
a @code{uid sort} command which corresponds to @code{sort} the way that @code{uid search}
corresponds to @code{search}.  The @code{sort} command first searches the mailbox for
messages that match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria.  It then returns the
numbers of matching messages.

This is an @code{IMAP4rev1} extension command.
@end deffn

@geindex starttls() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 starttls}@anchor{1203}
@deffn {Méthode} IMAP4.starttls (ssl_context=None)

Send a @code{STARTTLS} command.  The `ssl_context' argument is optional
and should be a @ref{291,,ssl.SSLContext} object.  This will enable
encryption on the IMAP connection.  Please read @ref{32a2,,Security considerations} for
best practices.


Ajouté dans la version 3.2.



Modifié dans la version 3.4: The method now supports hostname check with
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).

@end deffn

@geindex status() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 status}@anchor{3a2e}
@deffn {Méthode} IMAP4.status (mailbox, names)

Request named status conditions for `mailbox'.
@end deffn

@geindex store() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 store}@anchor{3a2f}
@deffn {Méthode} IMAP4.store (message_set, command, flag_list)

Alters flag dispositions for messages in mailbox.  `command' is specified by
section 6.4.6 of 
@geindex RFC; RFC 2060
RFC 2060@footnote{https://datatracker.ietf.org/doc/html/rfc2060.html} as being one of "FLAGS", "+FLAGS", or "-FLAGS",
optionally with a suffix of ".SILENT".

For example, to set the delete flag on all messages:

@example
typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()
@end example

@cartouche
@quotation Note 
Creating flags containing ']' (for example: "[test]") violates
@geindex RFC; RFC 3501
RFC 3501@footnote{https://datatracker.ietf.org/doc/html/rfc3501.html} (the IMAP protocol).  However, imaplib has historically
allowed creation of such tags, and popular IMAP servers, such as Gmail,
accept and produce such flags.  There are non-Python programs which also
create such tags.  Although it is an RFC violation and IMAP clients and
servers are supposed to be strict, imaplib still continues to allow
such tags to be created for backward compatibility reasons, and as of
Python 3.6, handles them if they are sent from the server, since this
improves real-world compatibility.
@end quotation
@end cartouche
@end deffn

@geindex subscribe() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 subscribe}@anchor{3a30}
@deffn {Méthode} IMAP4.subscribe (mailbox)

Subscribe to new mailbox.
@end deffn

@geindex thread() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 thread}@anchor{3a31}
@deffn {Méthode} IMAP4.thread (threading_algorithm, charset, search_criterion[, ...])

The @code{thread} command is a variant of @code{search} with threading semantics for
the results.  Returned data contains a space separated list of thread members.

Thread members consist of zero or more messages numbers, delimited by spaces,
indicating successive parent and child.

Thread has two arguments before the `search_criterion' argument(s); a
`threading_algorithm', and the searching `charset'.  Note that unlike
@code{search}, the searching `charset' argument is mandatory.  There is also a
@code{uid thread} command which corresponds to @code{thread} the way that @code{uid
search} corresponds to @code{search}.  The @code{thread} command first searches the
mailbox for messages that match the given searching criteria using the `charset'
argument for the interpretation of strings in the searching criteria. It then
returns the matching messages threaded according to the specified threading
algorithm.

This is an @code{IMAP4rev1} extension command.
@end deffn

@geindex uid() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 uid}@anchor{3a32}
@deffn {Méthode} IMAP4.uid (command, arg[, ...])

Execute command args with messages identified by UID, rather than message
number.  Returns response appropriate to command.  At least one argument must be
supplied; if none are provided, the server will return an error and an exception
will be raised.
@end deffn

@geindex unsubscribe() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 unsubscribe}@anchor{3a33}
@deffn {Méthode} IMAP4.unsubscribe (mailbox)

Unsubscribe from old mailbox.
@end deffn

@geindex unselect() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 unselect}@anchor{8f4}
@deffn {Méthode} IMAP4.unselect ()

@ref{8f4,,imaplib.IMAP4.unselect()} frees server's resources associated with the
selected mailbox and returns the server to the authenticated
state. This command performs the same actions as @ref{8f5,,imaplib.IMAP4.close()}, except
that no messages are permanently removed from the currently
selected mailbox.


Ajouté dans la version 3.9.

@end deffn

@geindex xatom() (méthode imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 xatom}@anchor{3a34}
@deffn {Méthode} IMAP4.xatom (name[, ...])

Allow simple extension commands notified by server in @code{CAPABILITY} response.
@end deffn

The following attributes are defined on instances of @ref{8f0,,IMAP4}:

@geindex PROTOCOL_VERSION (attribut imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 PROTOCOL_VERSION}@anchor{3a35}
@deffn {Attribut} IMAP4.PROTOCOL_VERSION

The most recent supported protocol in the @code{CAPABILITY} response from the
server.
@end deffn

@geindex debug (attribut imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 debug}@anchor{3a36}
@deffn {Attribut} IMAP4.debug

Integer value to control debugging output.  The initialize value is taken from
the module variable @code{Debug}.  Values greater than three trace each command.
@end deffn

@geindex utf8_enabled (attribut imaplib.IMAP4)
@anchor{library/imaplib imaplib IMAP4 utf8_enabled}@anchor{dfb}
@deffn {Attribut} IMAP4.utf8_enabled

Boolean value that is normally @code{False}, but is set to @code{True} if an
@ref{dfa,,enable()} command is successfully issued for the @code{UTF8=ACCEPT}
capability.


Ajouté dans la version 3.5.

@end deffn

@node IMAP4 Example,,IMAP4 Objects,imaplib --- IMAP4 protocol client
@anchor{library/imaplib id2}@anchor{3a37}@anchor{library/imaplib imap4-example}@anchor{3a38}
@subsubsection IMAP4 Example


Here is a minimal example (without error checking) that opens a mailbox and
retrieves and prints all messages:

@example
import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()
@end example

@node smtplib --- SMTP protocol client,uuid --- UUID objects according to RFC 4122,imaplib --- IMAP4 protocol client,Gestion des protocoles internet
@anchor{library/smtplib doc}@anchor{3a39}@anchor{library/smtplib module-smtplib}@anchor{c9}@anchor{library/smtplib smtplib-smtp-protocol-client}@anchor{3a3a}
@subsection @code{smtplib} --- SMTP protocol client


@geindex module; smtplib

`Code source :' Lib/smtplib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/smtplib.py}

@geindex SMTP;protocol
@geindex Simple Mail Transfer Protocol


__________________________________________________________________


The @ref{c9,,smtplib} module defines an SMTP client session object that can be used
to send mail to any internet machine with an SMTP or ESMTP listener daemon.  For
details of SMTP and ESMTP operation, consult 
@geindex RFC; RFC 821
RFC 821@footnote{https://datatracker.ietf.org/doc/html/rfc821.html} (Simple Mail Transfer
Protocol) and 
@geindex RFC; RFC 1869
RFC 1869@footnote{https://datatracker.ietf.org/doc/html/rfc1869.html} (SMTP Service Extensions).

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@geindex SMTP (classe dans smtplib)
@anchor{library/smtplib smtplib SMTP}@anchor{91a}
@deffn {Classe} smtplib.SMTP (host='@w{'}, port=0, local_hostname=None[, timeout], source_address=None)

An @ref{91a,,SMTP} instance encapsulates an SMTP connection.  It has methods
that support a full repertoire of SMTP and ESMTP operations. If the optional
`host' and `port' parameters are given, the SMTP @ref{1958,,connect()} method is
called with those parameters during initialization.  If specified,
`local_hostname' is used as the FQDN of the local host in the HELO/EHLO
command.  Otherwise, the local hostname is found using
@ref{170a,,socket.getfqdn()}.  If the @ref{1958,,connect()} call returns anything other
than a success code, an @ref{3a3b,,SMTPConnectError} is raised. The optional
`timeout' parameter specifies a timeout in seconds for blocking operations
like the connection attempt (if not specified, the global default timeout
setting will be used).  If the timeout expires, @ref{81f,,TimeoutError} is
raised.  The optional `source_address' parameter allows binding
to some specific source address in a machine with multiple network
interfaces, and/or to some specific source TCP port. It takes a 2-tuple
@code{(host, port)}, for the socket to bind to as its source address before
connecting. If omitted (or if `host' or `port' are @code{'@w{'}} and/or @code{0}
respectively) the OS default behavior will be used.

For normal use, you should only require the initialization/connect,
@ref{e42,,sendmail()}, and @ref{3a3c,,SMTP.quit()} methods.
An example is included below.

The @ref{91a,,SMTP} class supports the @ref{5bc,,with} statement.  When used
like this, the SMTP @code{QUIT} command is issued automatically when the
@code{with} statement exits.  E.g.:

@example
>>> from smtplib import SMTP
>>> with SMTP("domain.org") as smtp:
...     smtp.noop()
...
(250, b'Ok')
>>>
@end example


All commands will raise an @ref{1848,,auditing event}
@code{smtplib.SMTP.send} with arguments @code{self} and @code{data},
where @code{data} is the bytes about to be sent to the remote host.



Modifié dans la version 3.3: La prise en charge de l'instruction @ref{5bc,,with} a été ajoutée.



Modifié dans la version 3.3: `source_address' argument was added.



Ajouté dans la version 3.5: The SMTPUTF8 extension (
@geindex RFC; RFC 6531
RFC 6531@footnote{https://datatracker.ietf.org/doc/html/rfc6531.html}) is now supported.



Modifié dans la version 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{1ff,,ValueError} to prevent the creation of a non-blocking socket.

@end deffn

@geindex SMTP_SSL (classe dans smtplib)
@anchor{library/smtplib smtplib SMTP_SSL}@anchor{91b}
@deffn {Classe} smtplib.SMTP_SSL (host='@w{'}, port=0, local_hostname=None, *[, timeout], context=None, source_address=None)

An @ref{91b,,SMTP_SSL} instance behaves exactly the same as instances of
@ref{91a,,SMTP}. @ref{91b,,SMTP_SSL} should be used for situations where SSL is
required from the beginning of the connection and using @code{starttls()} is
not appropriate. If `host' is not specified, the local host is used. If
`port' is zero, the standard SMTP-over-SSL port (465) is used.  The optional
arguments `local_hostname', `timeout' and `source_address' have the same
meaning as they do in the @ref{91a,,SMTP} class.  `context', also optional,
can contain a @ref{291,,SSLContext} and allows configuring various
aspects of the secure connection.  Please read @ref{32a2,,Security considerations} for
best practices.


Modifié dans la version 3.3: `context' was added.



Modifié dans la version 3.3: The `source_address' argument was added.



Modifié dans la version 3.4: The class now supports hostname check with
@ref{33c4,,ssl.SSLContext.check_hostname} and `Server Name Indication' (see
@ref{33d6,,ssl.HAS_SNI}).



Modifié dans la version 3.9: If the `timeout' parameter is set to be zero, it will raise a
@ref{1ff,,ValueError} to prevent the creation of a non-blocking socket



Modifié dans la version 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.

@end deffn

@geindex LMTP (classe dans smtplib)
@anchor{library/smtplib smtplib LMTP}@anchor{91c}
@deffn {Classe} smtplib.LMTP (host='@w{'}, port=LMTP_PORT, local_hostname=None, source_address=None[, timeout])

The LMTP protocol, which is very similar to ESMTP, is heavily based on the
standard SMTP client. It's common to use Unix sockets for LMTP, so our
@code{connect()} method must support that as well as a regular host:port
server. The optional arguments `local_hostname' and `source_address' have the
same meaning as they do in the @ref{91a,,SMTP} class. To specify a Unix
socket, you must use an absolute path for `host', starting with a '/'.

Authentication is supported, using the regular SMTP mechanism. When using a
Unix socket, LMTP generally don't support or require any authentication, but
your mileage might vary.


Modifié dans la version 3.9: The optional `timeout' parameter was added.

@end deffn

A nice selection of exceptions is defined as well:

@geindex SMTPException
@anchor{library/smtplib smtplib SMTPException}@anchor{f8b}
@deffn {Exception} smtplib.SMTPException

Subclass of @ref{40d,,OSError} that is the base exception class for all
the other exceptions provided by this module.


Modifié dans la version 3.4: SMTPException became subclass of @ref{40d,,OSError}

@end deffn

@geindex SMTPServerDisconnected
@anchor{library/smtplib smtplib SMTPServerDisconnected}@anchor{3a3d}
@deffn {Exception} smtplib.SMTPServerDisconnected

This exception is raised when the server unexpectedly disconnects, or when an
attempt is made to use the @ref{91a,,SMTP} instance before connecting it to a
server.
@end deffn

@geindex SMTPResponseException
@anchor{library/smtplib smtplib SMTPResponseException}@anchor{3a3e}
@deffn {Exception} smtplib.SMTPResponseException

Base class for all exceptions that include an SMTP error code. These exceptions
are generated in some instances when the SMTP server returns an error code.  The
error code is stored in the @code{smtp_code} attribute of the error, and the
@code{smtp_error} attribute is set to the error message.
@end deffn

@geindex SMTPSenderRefused
@anchor{library/smtplib smtplib SMTPSenderRefused}@anchor{3a3f}
@deffn {Exception} smtplib.SMTPSenderRefused

Sender address refused.  In addition to the attributes set by on all
@ref{3a3e,,SMTPResponseException} exceptions, this sets 'sender' to the string that
the SMTP server refused.
@end deffn

@geindex SMTPRecipientsRefused
@anchor{library/smtplib smtplib SMTPRecipientsRefused}@anchor{3a40}
@deffn {Exception} smtplib.SMTPRecipientsRefused

All recipient addresses refused.  The errors for each recipient are accessible
through the attribute @code{recipients}, which is a dictionary of exactly the
same sort as @ref{e42,,SMTP.sendmail()} returns.
@end deffn

@geindex SMTPDataError
@anchor{library/smtplib smtplib SMTPDataError}@anchor{3a41}
@deffn {Exception} smtplib.SMTPDataError

The SMTP server refused to accept the message data.
@end deffn

@geindex SMTPConnectError
@anchor{library/smtplib smtplib SMTPConnectError}@anchor{3a3b}
@deffn {Exception} smtplib.SMTPConnectError

Error occurred during establishment of a connection  with the server.
@end deffn

@geindex SMTPHeloError
@anchor{library/smtplib smtplib SMTPHeloError}@anchor{3a42}
@deffn {Exception} smtplib.SMTPHeloError

The server refused our @code{HELO} message.
@end deffn

@geindex SMTPNotSupportedError
@anchor{library/smtplib smtplib SMTPNotSupportedError}@anchor{1957}
@deffn {Exception} smtplib.SMTPNotSupportedError

The command or option attempted is not supported by the server.


Ajouté dans la version 3.5.

@end deffn

@geindex SMTPAuthenticationError
@anchor{library/smtplib smtplib SMTPAuthenticationError}@anchor{3a43}
@deffn {Exception} smtplib.SMTPAuthenticationError

SMTP authentication went wrong.  Most probably the server didn't accept the
username/password combination provided.
@end deffn


@subsubheading Voir aussi



@table @asis

@geindex RFC; RFC 821

@item RFC 821@footnote{https://datatracker.ietf.org/doc/html/rfc821.html} - Simple Mail Transfer Protocol

Protocol definition for SMTP.  This document covers the model, operating
procedure, and protocol details for SMTP.

@geindex RFC; RFC 1869

@item RFC 1869@footnote{https://datatracker.ietf.org/doc/html/rfc1869.html} - SMTP Service Extensions

Definition of the ESMTP extensions for SMTP.  This describes a framework for
extending SMTP with new commands, supporting dynamic discovery of the commands
provided by the server, and defines a few additional commands.
@end table


@menu
* SMTP Objects:: 
* SMTP Example:: 

@end menu

@node SMTP Objects,SMTP Example,,smtplib --- SMTP protocol client
@anchor{library/smtplib id1}@anchor{3a44}@anchor{library/smtplib smtp-objects}@anchor{3a45}
@subsubsection SMTP Objects


An @ref{91a,,SMTP} instance has the following methods:

@geindex set_debuglevel() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP set_debuglevel}@anchor{e41}
@deffn {Méthode} SMTP.set_debuglevel (level)

Set the debug output level.  A value of 1 or @code{True} for `level' results in
debug messages for connection and for all messages sent to and received from
the server.  A value of 2 for `level' results in these messages being
timestamped.


Modifié dans la version 3.5: Added debuglevel 2.

@end deffn

@geindex docmd() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP docmd}@anchor{3a46}
@deffn {Méthode} SMTP.docmd (cmd, args='@w{'})

Send a command `cmd' to the server.  The optional argument `args' is simply
concatenated to the command, separated by a space.

This returns a 2-tuple composed of a numeric response code and the actual
response line (multiline responses are joined into one long line.)

In normal operation it should not be necessary to call this method explicitly.
It is used to implement other methods and may be useful for testing private
extensions.

If the connection to the server is lost while waiting for the reply,
@ref{3a3d,,SMTPServerDisconnected} will be raised.
@end deffn

@geindex connect() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP connect}@anchor{1958}
@deffn {Méthode} SMTP.connect (host='localhost', port=0)

Connect to a host on a given port.  The defaults are to connect to the local
host at the standard SMTP port (25). If the hostname ends with a colon (@code{':'})
followed by a number, that suffix will be stripped off and the number
interpreted as the port number to use. This method is automatically invoked by
the constructor if a host is specified during instantiation.  Returns a
2-tuple of the response code and message sent by the server in its
connection response.

Raises an @ref{1848,,auditing event} @code{smtplib.connect} with arguments @code{self}, @code{host}, @code{port}.
@end deffn

@geindex helo() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP helo}@anchor{3a47}
@deffn {Méthode} SMTP.helo (name='@w{'})

Identify yourself to the SMTP server using @code{HELO}.  The hostname argument
defaults to the fully qualified domain name of the local host.
The message returned by the server is stored as the @code{helo_resp} attribute
of the object.

In normal operation it should not be necessary to call this method explicitly.
It will be implicitly called by the @ref{e42,,sendmail()} when necessary.
@end deffn

@geindex ehlo() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP ehlo}@anchor{3a48}
@deffn {Méthode} SMTP.ehlo (name='@w{'})

Identify yourself to an ESMTP server using @code{EHLO}.  The hostname argument
defaults to the fully qualified domain name of the local host.  Examine the
response for ESMTP option and store them for use by @ref{3a49,,has_extn()}.
Also sets several informational attributes: the message returned by
the server is stored as the @code{ehlo_resp} attribute, @code{does_esmtp}
is set to @code{True} or @code{False} depending on whether the server supports
ESMTP, and @code{esmtp_features} will be a dictionary containing the names
of the SMTP service extensions this server supports, and their parameters
(if any).

Unless you wish to use @ref{3a49,,has_extn()} before sending mail, it should not be
necessary to call this method explicitly.  It will be implicitly called by
@ref{e42,,sendmail()} when necessary.
@end deffn

@geindex ehlo_or_helo_if_needed() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP ehlo_or_helo_if_needed}@anchor{3a4a}
@deffn {Méthode} SMTP.ehlo_or_helo_if_needed ()

This method calls @ref{3a48,,ehlo()} and/or @ref{3a47,,helo()} if there has been no
previous @code{EHLO} or @code{HELO} command this session.  It tries ESMTP @code{EHLO}
first.


@table @asis

@item @ref{3a42,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.
@end table
@end deffn

@geindex has_extn() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP has_extn}@anchor{3a49}
@deffn {Méthode} SMTP.has_extn (name)

Return @ref{bfb,,True} if `name' is in the set of SMTP service extensions returned
by the server, @ref{b25,,False} otherwise. Case is ignored.
@end deffn

@geindex verify() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP verify}@anchor{3a4b}
@deffn {Méthode} SMTP.verify (address)

Check the validity of an address on this server using SMTP @code{VRFY}. Returns a
tuple consisting of code 250 and a full 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} address (including human
name) if the user address is valid. Otherwise returns an SMTP error code of 400
or greater and an error string.

@cartouche
@quotation Note 
Many sites disable SMTP @code{VRFY} in order to foil spammers.
@end quotation
@end cartouche
@end deffn

@geindex login() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP login}@anchor{3a4c}
@deffn {Méthode} SMTP.login (user, password, *, initial_response_ok=True)

Log in on an SMTP server that requires authentication. The arguments are the
username and the password to authenticate with. If there has been no previous
@code{EHLO} or @code{HELO} command this session, this method tries ESMTP @code{EHLO}
first. This method will return normally if the authentication was successful, or
may raise the following exceptions:


@table @asis

@item @ref{3a42,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.

@item @ref{3a43,,SMTPAuthenticationError}

The server didn't accept the username/password combination.

@item @ref{1957,,SMTPNotSupportedError}

The @code{AUTH} command is not supported by the server.

@item @ref{f8b,,SMTPException}

No suitable authentication method was found.
@end table

Each of the authentication methods supported by @ref{c9,,smtplib} are tried in
turn if they are advertised as supported by the server.  See @ref{e40,,auth()}
for a list of supported authentication methods.  `initial_response_ok' is
passed through to @ref{e40,,auth()}.

Optional keyword argument `initial_response_ok' specifies whether, for
authentication methods that support it, an "initial response" as specified
in 
@geindex RFC; RFC 4954
RFC 4954@footnote{https://datatracker.ietf.org/doc/html/rfc4954.html} can be sent along with the @code{AUTH} command, rather than
requiring a challenge/response.


Modifié dans la version 3.5: @ref{1957,,SMTPNotSupportedError} may be raised, and the
`initial_response_ok' parameter was added.

@end deffn

@geindex auth() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP auth}@anchor{e40}
@deffn {Méthode} SMTP.auth (mechanism, authobject, *, initial_response_ok=True)

Issue an @code{SMTP} @code{AUTH} command for the specified authentication
`mechanism', and handle the challenge response via `authobject'.

`mechanism' specifies which authentication mechanism is to
be used as argument to the @code{AUTH} command; the valid values are
those listed in the @code{auth} element of @code{esmtp_features}.

`authobject' must be a callable object taking an optional single argument:

@example
data = authobject(challenge=None)
@end example

If optional keyword argument `initial_response_ok' is true,
@code{authobject()} will be called first with no argument.  It can return the
@geindex RFC; RFC 4954
RFC 4954@footnote{https://datatracker.ietf.org/doc/html/rfc4954.html} "initial response" ASCII @code{str} which will be encoded and sent with
the @code{AUTH} command as below.  If the @code{authobject()} does not support an
initial response (e.g. because it requires a challenge), it should return
@code{None} when called with @code{challenge=None}.  If `initial_response_ok' is
false, then @code{authobject()} will not be called first with @code{None}.

If the initial response check returns @code{None}, or if `initial_response_ok' is
false, @code{authobject()} will be called to process the server's challenge
response; the `challenge' argument it is passed will be a @code{bytes}.  It
should return ASCII @code{str} `data' that will be base64 encoded and sent to the
server.

The @code{SMTP} class provides @code{authobjects} for the @code{CRAM-MD5}, @code{PLAIN},
and @code{LOGIN} mechanisms; they are named @code{SMTP.auth_cram_md5},
@code{SMTP.auth_plain}, and @code{SMTP.auth_login} respectively.  They all require
that the @code{user} and @code{password} properties of the @code{SMTP} instance are
set to appropriate values.

User code does not normally need to call @code{auth} directly, but can instead
call the @ref{3a4c,,login()} method, which will try each of the above mechanisms
in turn, in the order listed.  @code{auth} is exposed to facilitate the
implementation of authentication methods not (or not yet) supported
directly by @ref{c9,,smtplib}.


Ajouté dans la version 3.5.

@end deffn

@geindex starttls() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP starttls}@anchor{1118}
@deffn {Méthode} SMTP.starttls (*, context=None)

Put the SMTP connection in TLS (Transport Layer Security) mode.  All SMTP
commands that follow will be encrypted.  You should then call @ref{3a48,,ehlo()}
again.

If `keyfile' and `certfile' are provided, they are used to create an
@ref{291,,ssl.SSLContext}.

Optional `context' parameter is an @ref{291,,ssl.SSLContext} object; This is
an alternative to using a keyfile and a certfile and if specified both
`keyfile' and `certfile' should be @code{None}.

If there has been no previous @code{EHLO} or @code{HELO} command this session,
this method tries ESMTP @code{EHLO} first.


Modifié dans la version 3.12: The deprecated `keyfile' and `certfile' parameters have been removed.



@table @asis

@item @ref{3a42,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.

@item @ref{1957,,SMTPNotSupportedError}

The server does not support the STARTTLS extension.

@item @ref{193,,RuntimeError}

SSL/TLS support is not available to your Python interpreter.
@end table


Modifié dans la version 3.3: `context' was added.



Modifié dans la version 3.4: The method now supports hostname check with
@code{SSLContext.check_hostname} and `Server Name Indicator' (see
@ref{33d6,,HAS_SNI}).



Modifié dans la version 3.5: The error raised for lack of STARTTLS support is now the
@ref{1957,,SMTPNotSupportedError} subclass instead of the base
@ref{f8b,,SMTPException}.

@end deffn

@geindex sendmail() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP sendmail}@anchor{e42}
@deffn {Méthode} SMTP.sendmail (from_addr, to_addrs, msg, mail_options=(), rcpt_options=())

Send mail.  The required arguments are an 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} from-address string, a list
of 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} to-address strings (a bare string will be treated as a list with 1
address), and a message string.  The caller may pass a list of ESMTP options
(such as @code{8bitmime}) to be used in @code{MAIL FROM} commands as `mail_options'.
ESMTP options (such as @code{DSN} commands) that should be used with all @code{RCPT}
commands can be passed as `rcpt_options'.  (If you need to use different ESMTP
options to different recipients you have to use the low-level methods such as
@code{mail()}, @code{rcpt()} and @code{data()} to send the message.)

@cartouche
@quotation Note 
The `from_addr' and `to_addrs' parameters are used to construct the message
envelope used by the transport agents.  @code{sendmail} does not modify the
message headers in any way.
@end quotation
@end cartouche

`msg' may be a string containing characters in the ASCII range, or a byte
string.  A string is encoded to bytes using the ascii codec, and lone @code{\r}
and @code{\n} characters are converted to @code{\r\n} characters.  A byte string is
not modified.

If there has been no previous @code{EHLO} or @code{HELO} command this session, this
method tries ESMTP @code{EHLO} first. If the server does ESMTP, message size and
each of the specified options will be passed to it (if the option is in the
feature set the server advertises).  If @code{EHLO} fails, @code{HELO} will be tried
and ESMTP options suppressed.

This method will return normally if the mail is accepted for at least one
recipient. Otherwise it will raise an exception.  That is, if this method does
not raise an exception, then someone should get your mail. If this method does
not raise an exception, it returns a dictionary, with one entry for each
recipient that was refused.  Each entry contains a tuple of the SMTP error code
and the accompanying error message sent by the server.

If @code{SMTPUTF8} is included in `mail_options', and the server supports it,
`from_addr' and `to_addrs' may contain non-ASCII characters.

This method may raise the following exceptions:


@table @asis

@item @ref{3a40,,SMTPRecipientsRefused}

All recipients were refused.  Nobody got the mail.  The @code{recipients}
attribute of the exception object is a dictionary with information about the
refused recipients (like the one returned when at least one recipient was
accepted).

@item @ref{3a42,,SMTPHeloError}

The server didn't reply properly to the @code{HELO} greeting.

@item @ref{3a3f,,SMTPSenderRefused}

The server didn't accept the `from_addr'.

@item @ref{3a41,,SMTPDataError}

The server replied with an unexpected error code (other than a refusal of a
recipient).

@item @ref{1957,,SMTPNotSupportedError}

@code{SMTPUTF8} was given in the `mail_options' but is not supported by the
server.
@end table

Unless otherwise noted, the connection will be open even after an exception is
raised.


Modifié dans la version 3.2: `msg' may be a byte string.



Modifié dans la version 3.5: @code{SMTPUTF8} support added, and @ref{1957,,SMTPNotSupportedError} may be
raised if @code{SMTPUTF8} is specified but the server does not support it.

@end deffn

@geindex send_message() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP send_message}@anchor{e43}
@deffn {Méthode} SMTP.send_message (msg, from_addr=None, to_addrs=None, mail_options=(), rcpt_options=())

This is a convenience method for calling @ref{e42,,sendmail()} with the message
represented by an @ref{279,,email.message.Message} object.  The arguments have
the same meaning as for @ref{e42,,sendmail()}, except that `msg' is a @code{Message}
object.

If `from_addr' is @code{None} or `to_addrs' is @code{None}, @code{send_message} fills
those arguments with addresses extracted from the headers of `msg' as
specified in 
@geindex RFC; RFC 5322
RFC 5322@footnote{https://datatracker.ietf.org/doc/html/rfc5322.html}: `from_addr' is set to the @code{Sender}
field if it is present, and otherwise to the @code{From} field.
`to_addrs' combines the values (if any) of the @code{To},
@code{Cc}, and @code{Bcc} fields from `msg'.  If exactly one
set of @code{Resent-*} headers appear in the message, the regular
headers are ignored and the @code{Resent-*} headers are used instead.
If the message contains more than one set of @code{Resent-*} headers,
a @ref{1ff,,ValueError} is raised, since there is no way to unambiguously detect
the most recent set of @code{Resent-} headers.

@code{send_message} serializes `msg' using
@ref{11ac,,BytesGenerator} with @code{\r\n} as the `linesep', and
calls @ref{e42,,sendmail()} to transmit the resulting message.  Regardless of the
values of `from_addr' and `to_addrs', @code{send_message} does not transmit any
@code{Bcc} or @code{Resent-Bcc} headers that may appear
in `msg'.  If any of the addresses in `from_addr' and `to_addrs' contain
non-ASCII characters and the server does not advertise @code{SMTPUTF8} support,
an @code{SMTPNotSupported} error is raised.  Otherwise the @code{Message} is
serialized with a clone of its @ref{4f,,policy} with the
@ref{de5,,utf8} attribute set to @code{True}, and
@code{SMTPUTF8} and @code{BODY=8BITMIME} are added to `mail_options'.


Ajouté dans la version 3.2.



Ajouté dans la version 3.5: Support for internationalized addresses (@code{SMTPUTF8}).

@end deffn

@geindex quit() (méthode smtplib.SMTP)
@anchor{library/smtplib smtplib SMTP quit}@anchor{3a3c}
@deffn {Méthode} SMTP.quit ()

Terminate the SMTP session and close the connection.  Return the result of
the SMTP @code{QUIT} command.
@end deffn

Low-level methods corresponding to the standard SMTP/ESMTP commands @code{HELP},
@code{RSET}, @code{NOOP}, @code{MAIL}, @code{RCPT}, and @code{DATA} are also supported.
Normally these do not need to be called directly, so they are not documented
here.  For details, consult the module code.

@node SMTP Example,,SMTP Objects,smtplib --- SMTP protocol client
@anchor{library/smtplib id2}@anchor{3a4d}@anchor{library/smtplib smtp-example}@anchor{3a4e}
@subsubsection SMTP Example


This example prompts the user for addresses needed in the message envelope ('To'
and 'From' addresses), and the message to be delivered.  Note that the headers
to be included with the message must be included in the message as entered; this
example doesn't do any processing of the 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html} headers.  In particular, the
'To' and 'From' addresses must be included in the message headers explicitly:

@example
import smtplib

def prompt(title):
    return input(title).strip()

from_addr = prompt("From: ")
to_addrs  = prompt("To: ").split()
print("Enter message, end with ^D (Unix) or ^Z (Windows):")

# Add the From: and To: headers at the start!
lines = [f"From: @{from_addr@}", f"To: @{', '.join(to_addrs)@}", ""]
while True:
    try:
        line = input()
    except EOFError:
        break
    else:
        lines.append(line)

msg = "\r\n".join(lines)
print("Message length is", len(msg))

server = smtplib.SMTP("localhost")
server.set_debuglevel(1)
server.sendmail(from_addr, to_addrs, msg)
server.quit()
@end example

@cartouche
@quotation Note 
In general, you will want to use the @ref{3b,,email} package's features to
construct an email message, which you can then send
via @ref{e43,,send_message()}; see @ref{f27,,email; Exemples}.
@end quotation
@end cartouche

@node uuid --- UUID objects according to RFC 4122,socketserver --- A framework for network servers,smtplib --- SMTP protocol client,Gestion des protocoles internet
@anchor{library/uuid doc}@anchor{3a4f}@anchor{library/uuid module-uuid}@anchor{10f}@anchor{library/uuid uuid-uuid-objects-according-to-rfc-4122}@anchor{3a50}
@subsection @code{uuid} --- UUID objects according to 
@geindex RFC; RFC 4122
`RFC 4122'


@geindex module; uuid

`Code source :' Lib/uuid.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/uuid.py}


__________________________________________________________________


Ce module exporte des objets @ref{a4f,,UUID} immuables (de la classe @ref{a4f,,UUID}) et les fonctions @ref{b96,,uuid1()}, @ref{16d3,,uuid3()}, @ref{3a51,,uuid4()}, @ref{16d4,,uuid5()} permettant de générer des UUID de version 1, 3, 4 et 5 tels que définis dans la 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}.

Utilisez @ref{b96,,uuid1()} ou @ref{3a51,,uuid4()} si votre but est de produire un identifiant unique. Notez que @ref{b96,,uuid1()} peut dévoiler des informations personnelles car l'UUID produit contient l'adresse réseau de l'ordinateur. En revanche, @ref{3a51,,uuid4()} génère un UUID aléatoire.

Depending on support from the underlying platform, @ref{b96,,uuid1()} may or may
not return a "safe" UUID.  A safe UUID is one which is generated using
synchronization methods that ensure no two processes can obtain the same
UUID.  All instances of @ref{a4f,,UUID} have an @ref{b94,,is_safe} attribute
which relays any information about the UUID's safety, using this enumeration:

@geindex SafeUUID (classe dans uuid)
@anchor{library/uuid uuid SafeUUID}@anchor{3a52}
@deffn {Classe} uuid.SafeUUID


Ajouté dans la version 3.7.


@geindex safe (attribut uuid.SafeUUID)
@anchor{library/uuid uuid SafeUUID safe}@anchor{3a53}
@deffn {Attribut} safe

L'UUID a été généré par la plateforme en utilisant une méthode sûre dans un contexte de parallélisme par processus.
@end deffn

@geindex unsafe (attribut uuid.SafeUUID)
@anchor{library/uuid uuid SafeUUID unsafe}@anchor{3a54}
@deffn {Attribut} unsafe

L'UUID n'a pas été généré par une méthode sûre dans un contexte de parallélisme par processus.
@end deffn

@geindex unknown (attribut uuid.SafeUUID)
@anchor{library/uuid uuid SafeUUID unknown}@anchor{3a55}
@deffn {Attribut} unknown

La plateforme ne précise pas si l'UUID a été généré de façon sûre ou non.
@end deffn
@end deffn

@geindex UUID (classe dans uuid)
@anchor{library/uuid uuid UUID}@anchor{a4f}
@deffn {Classe} uuid.UUID (hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

Produit un UUID à partir soit d'une chaîne de 32 chiffres hexadécimaux, soit une chaîne de 16 octets gros-boutiste (argument `bytes'), soit une chaîne de 16 octets petit-boutiste (argument `bytes_le'), soit un sextuplet d'entiers (32-bit `time_low', 16-bit `time_mid', 16-bit `time_hi_version', 8-bit `clock_seq_hi_variant', 8-bit `clock_seq_low', 48-bit `node') (argument `fields'), soit un unique entier sur 128 bits (argument `int'). Lorsque la fonction reçoit une chaîne de chiffres hexadécimaux, les accolades, les tirets et le préfixe URN sont facultatifs. Par exemple, toutes les expressions ci-dessous génèrent le même UUID :

@example
UUID('@{12345678-1234-5678-1234-567812345678@}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(bytes=b'\x12\x34\x56\x78'*4)
UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' +
              b'\x12\x34\x56\x78\x12\x34\x56\x78')
UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
UUID(int=0x12345678123456781234567812345678)
@end example

Un seul des arguments `hex', `bytes', `bytes_le', `fields' ou `int' doit être spécifié. L'argument `version' est optionnel : s'il est spécifié, l'UUID généré aura pour numéro de version et de variante la valeur indiquée dans la 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}, remplaçant les bits idoines de `hex', `bytes', `bytes_le', `fields' ou `int'.

La comparaison de deux objets UUID se fait en comparant leurs attributs @ref{3a56,,UUID.int}. La comparaison avec un objet autre qu'un UUID lève une exception @ref{522,,TypeError}.

@code{str(uuid)} renvoie une chaîne de caractères de la forme @code{12345678-1234-5678-1234-567812345678} représentant l'UUID par une chaîne de 32 chiffres hexadécimaux.
@end deffn

Les instances de @ref{a4f,,UUID} possèdent les attributs suivants en lecture seule :

@geindex bytes (attribut uuid.UUID)
@anchor{library/uuid uuid UUID bytes}@anchor{3a57}
@deffn {Attribut} UUID.bytes

L'UUID représenté comme une chaîne de 16 octets (contenant les six champs entiers dans l'ordre gros-boutiste).
@end deffn

@geindex bytes_le (attribut uuid.UUID)
@anchor{library/uuid uuid UUID bytes_le}@anchor{3a58}
@deffn {Attribut} UUID.bytes_le

L'UUID représenté comme une chaîne de 16 octets (avec `time_low', `time_mid' et `time_hi_version' dans l'ordre petit-boutiste).
@end deffn

@geindex fields (attribut uuid.UUID)
@anchor{library/uuid uuid UUID fields}@anchor{3a59}
@deffn {Attribut} UUID.fields

Un sextuplet contenant les champs entiers de l'UUID, également accessibles en tant que six attributs individuels et deux attributs dérivés :
@end deffn


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

Champ

@tab

Signification

@item

@geindex time_low (attribut uuid.UUID)
@anchor{library/uuid uuid UUID time_low}@anchor{3a5a}
@deffn {Attribut} UUID.time_low
@end deffn

@tab

The first 32 bits of the UUID.

@item

@geindex time_mid (attribut uuid.UUID)
@anchor{library/uuid uuid UUID time_mid}@anchor{3a5b}
@deffn {Attribut} UUID.time_mid
@end deffn

@tab

The next 16 bits of the UUID.

@item

@geindex time_hi_version (attribut uuid.UUID)
@anchor{library/uuid uuid UUID time_hi_version}@anchor{3a5c}
@deffn {Attribut} UUID.time_hi_version
@end deffn

@tab

The next 16 bits of the UUID.

@item

@geindex clock_seq_hi_variant (attribut uuid.UUID)
@anchor{library/uuid uuid UUID clock_seq_hi_variant}@anchor{3a5d}
@deffn {Attribut} UUID.clock_seq_hi_variant
@end deffn

@tab

The next 8 bits of the UUID.

@item

@geindex clock_seq_low (attribut uuid.UUID)
@anchor{library/uuid uuid UUID clock_seq_low}@anchor{3a5e}
@deffn {Attribut} UUID.clock_seq_low
@end deffn

@tab

The next 8 bits of the UUID.

@item

@geindex node (attribut uuid.UUID)
@anchor{library/uuid uuid UUID node}@anchor{3a5f}
@deffn {Attribut} UUID.node
@end deffn

@tab

The last 48 bits of the UUID.

@item

@geindex time (attribut uuid.UUID)
@anchor{library/uuid uuid UUID time}@anchor{3a60}
@deffn {Attribut} UUID.time
@end deffn

@tab

The 60-bit timestamp.

@item

@geindex clock_seq (attribut uuid.UUID)
@anchor{library/uuid uuid UUID clock_seq}@anchor{3a61}
@deffn {Attribut} UUID.clock_seq
@end deffn

@tab

The 14-bit sequence number.

@end multitable


@geindex hex (attribut uuid.UUID)
@anchor{library/uuid uuid UUID hex}@anchor{3a62}
@deffn {Attribut} UUID.hex

The UUID as a 32-character lowercase hexadecimal string.
@end deffn

@geindex int (attribut uuid.UUID)
@anchor{library/uuid uuid UUID int}@anchor{3a56}
@deffn {Attribut} UUID.int

Représentation de l'UUId sous forme d'un entier de 128 bits.
@end deffn

@geindex urn (attribut uuid.UUID)
@anchor{library/uuid uuid UUID urn}@anchor{3a63}
@deffn {Attribut} UUID.urn

Représentation de l'UUID sous forme d'URN tel que spécifié dans la 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}.
@end deffn

@geindex variant (attribut uuid.UUID)
@anchor{library/uuid uuid UUID variant}@anchor{3a64}
@deffn {Attribut} UUID.variant

Variante de l'UUID. Celle-ci détermine l'agencement interne de l'UUID. Les valeurs possibles sont les constantes suivantes : @ref{3a65,,RESERVED_NCS}, @ref{3a66,,RFC_4122}, @ref{3a67,,RESERVED_MICROSOFT} ou @ref{3a68,,RESERVED_FUTURE}.
@end deffn

@geindex version (attribut uuid.UUID)
@anchor{library/uuid uuid UUID version}@anchor{3a69}
@deffn {Attribut} UUID.version

Numéro de version de l'UUID (de 1 à 5). Cette valeur n'a de sens que dans le cas de la variante @ref{3a66,,RFC_4122}.
@end deffn

@geindex is_safe (attribut uuid.UUID)
@anchor{library/uuid uuid UUID is_safe}@anchor{b94}
@deffn {Attribut} UUID.is_safe

Valeur de l'énumération @ref{3a52,,SafeUUID} indiquant si la plateforme a généré l'UUID d'une façon sûre dans un contexte de parallélisme par processus.


Ajouté dans la version 3.7.

@end deffn

Le module @ref{10e,,uu} définit les fonctions suivantes :

@geindex getnode() (dans le module uuid)
@anchor{library/uuid uuid getnode}@anchor{b95}
@deffn {Fonction} uuid.getnode ()

Renvoie l'adresse réseau matérielle sous forme d'un entier positif sur 48 bits. Cette fonction peut faire appel à un programme externe relativement lent lors de sa première exécution. Si toutes les tentatives d'obtenir l'adresse matérielle échouent, un nombre aléatoire sur 48 bit avec le bit de `multicast' (bit de poids faible du premier octet) à 1 est généré, comme recommandé par la 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}. Ici, « adresse matérielle » correspond à l'adresse MAC d'une interface réseau. Sur une machine avec plusieurs interfaces réseau, les adresses MAC  de type UUA (`universally administered address', pour lesquelles le second bit de poids faible est à zéro) sont prioritaires par rapport aux autres adresses MAC. Aucune autre garantie n'est donnée sur l'ordre dans lequel les interfaces sont choisies.


Modifié dans la version 3.7: Les adresses MAC de type UUA sont préférées par rapport aux adresses locales car ces dernières ne sont pas nécessairement uniques.

@end deffn

@geindex getnode

@geindex uuid1() (dans le module uuid)
@anchor{library/uuid uuid uuid1}@anchor{b96}
@deffn {Fonction} uuid.uuid1 (node=None, clock_seq=None)

Génère un UUID à partir d'un identifiant hôte, d'un numéro de séquence et de l'heure actuelle. Si `node' n'est pas spécifié, la fonction @ref{b95,,getnode()} est appelée pour obtenir l'adresse matérielle. `clock_seq' est utilisé comme numéro de séquence s'il est spécifié, sinon un numéro aléatoire sur 14 bits est utilisé à la place.
@end deffn

@geindex uuid1

@geindex uuid3() (dans le module uuid)
@anchor{library/uuid uuid uuid3}@anchor{16d3}
@deffn {Fonction} uuid.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 @ref{1bd,,bytes} object or a string
that will be encoded using UTF-8).
@end deffn

@geindex uuid3

@geindex uuid4() (dans le module uuid)
@anchor{library/uuid uuid uuid4}@anchor{3a51}
@deffn {Fonction} uuid.uuid4 ()

Génère un UUID aléatoire.
@end deffn

@geindex uuid4

@geindex uuid5() (dans le module uuid)
@anchor{library/uuid uuid uuid5}@anchor{16d4}
@deffn {Fonction} uuid.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 @ref{1bd,,bytes} object or a string
that will be encoded using UTF-8).
@end deffn

@geindex uuid5

Le module @ref{10f,,uuid} définit les identifiants d'espaces de noms suivants (pour @ref{16d3,,uuid3()} et @ref{16d4,,uuid5()}).

@geindex NAMESPACE_DNS (dans le module uuid)
@anchor{library/uuid uuid NAMESPACE_DNS}@anchor{3a6a}
@deffn {Données} uuid.NAMESPACE_DNS

When this namespace is specified, the `name' string is a fully qualified domain
name.
@end deffn

@geindex NAMESPACE_URL (dans le module uuid)
@anchor{library/uuid uuid NAMESPACE_URL}@anchor{3a6b}
@deffn {Données} uuid.NAMESPACE_URL

Lorsque cet espace de nom est spécifié, la chaîne `name' doit être une URL.
@end deffn

@geindex NAMESPACE_OID (dans le module uuid)
@anchor{library/uuid uuid NAMESPACE_OID}@anchor{3a6c}
@deffn {Données} uuid.NAMESPACE_OID

Lorsque cet espace de nom est spécifié, la chaîne `name' doit être un OID ISO.
@end deffn

@geindex NAMESPACE_X500 (dans le module uuid)
@anchor{library/uuid uuid NAMESPACE_X500}@anchor{3a6d}
@deffn {Données} uuid.NAMESPACE_X500

Lorsque cet espace de nom est spécifié, la chaîne `name' doit être un DN X.500 au format texte ou DER.
@end deffn

The @ref{10f,,uuid} module defines the following constants for the possible values
of the @ref{3a64,,variant} attribute:

@geindex RESERVED_NCS (dans le module uuid)
@anchor{library/uuid uuid RESERVED_NCS}@anchor{3a65}
@deffn {Données} uuid.RESERVED_NCS

Réservé pour la compatibilité NCS.
@end deffn

@geindex RFC_4122 (dans le module uuid)
@anchor{library/uuid uuid RFC_4122}@anchor{3a66}
@deffn {Données} uuid.RFC_4122

Utilise l'agencement des UUID de la 
@geindex RFC; RFC 4122
RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html}.
@end deffn

@geindex RESERVED_MICROSOFT (dans le module uuid)
@anchor{library/uuid uuid RESERVED_MICROSOFT}@anchor{3a67}
@deffn {Données} uuid.RESERVED_MICROSOFT

Réservé pour la compatibilité Microsoft.
@end deffn

@geindex RESERVED_FUTURE (dans le module uuid)
@anchor{library/uuid uuid RESERVED_FUTURE}@anchor{3a68}
@deffn {Données} uuid.RESERVED_FUTURE

Réservé pour un usage futur.
@end deffn


@subsubheading Voir aussi



@table @asis

@geindex RFC; RFC 4122

@item RFC 4122@footnote{https://datatracker.ietf.org/doc/html/rfc4122.html} – `A Universally Unique IDentifier (UUID) URN Namespace'

Cette spécification (en anglais) définit un espace de noms `Uniform Resource Name' pour les UUID, leur format interne et les méthodes permettant de les générer.
@end table


@menu
* Utilisation en ligne de commande.: Utilisation en ligne de commande<2>. 
* Exemple: Exemple<11>. 
* Command-Line Example:: 

@end menu

@node Utilisation en ligne de commande<2>,Exemple<11>,,uuid --- UUID objects according to RFC 4122
@anchor{library/uuid command-line-usage}@anchor{3a6e}@anchor{library/uuid uuid-cli}@anchor{42d}
@subsubsection Utilisation en ligne de commande.



Ajouté dans la version 3.12.


The @ref{10f,,uuid} module can be executed as a script from the command line.

@example
python -m uuid [-h] [-u @{uuid1,uuid3,uuid4,uuid5@}] [-n NAMESPACE] [-N NAME]
@end example

Les options suivantes sont acceptées :

@geindex option de ligne de commande uuid; -h
@geindex option de ligne de commande uuid; --help
@anchor{library/uuid cmdoption-uuid-h}@anchor{3a6f}@anchor{library/uuid cmdoption-uuid-help}@anchor{3a70}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Affiche un message d'aide et quitte.
@end deffn

@geindex option de ligne de commande uuid; -u
@geindex option de ligne de commande uuid; --uuid
@anchor{library/uuid cmdoption-uuid-u}@anchor{3a71}
@deffn {Option} @w{-}u <uuid>
@anchor{library/uuid cmdoption-uuid-uuid}@anchor{3a72}
@deffnx {Option} @w{-}@w{-}uuid <uuid>

Specify the function name to use to generate the uuid. By default @ref{3a51,,uuid4()}
is used.
@end deffn

@geindex option de ligne de commande uuid; -n
@geindex option de ligne de commande uuid; --namespace
@anchor{library/uuid cmdoption-uuid-n}@anchor{3a73}
@deffn {Option} @w{-}n <namespace>
@anchor{library/uuid cmdoption-uuid-namespace}@anchor{3a74}
@deffnx {Option} @w{-}@w{-}namespace <namespace>

The namespace is a @code{UUID}, or @code{@@ns} where @code{ns} is a well-known predefined UUID
addressed by namespace name. Such as @code{@@dns}, @code{@@url}, @code{@@oid}, and @code{@@x500}.
Only required for @ref{16d3,,uuid3()} / @ref{16d4,,uuid5()} functions.
@end deffn

@geindex option de ligne de commande uuid; -N
@geindex option de ligne de commande uuid; --name
@anchor{library/uuid cmdoption-uuid-N}@anchor{3a75}
@deffn {Option} @w{-}N <name>
@anchor{library/uuid cmdoption-uuid-name}@anchor{3a76}
@deffnx {Option} @w{-}@w{-}name <name>

The name used as part of generating the uuid. Only required for
@ref{16d3,,uuid3()} / @ref{16d4,,uuid5()} functions.
@end deffn

@node Exemple<11>,Command-Line Example,Utilisation en ligne de commande<2>,uuid --- UUID objects according to RFC 4122
@anchor{library/uuid example}@anchor{3a77}@anchor{library/uuid uuid-example}@anchor{3a78}
@subsubsection Exemple


Voici quelques exemples classiques d'utilisation du module @ref{10f,,uuid} :

@example
>>> import uuid

>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('@{00010203-0405-0607-0809-0a0b0c0d0e0f@}')

>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # get the raw 16 bytes of the UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
@end example

@node Command-Line Example,,Exemple<11>,uuid --- UUID objects according to RFC 4122
@anchor{library/uuid command-line-example}@anchor{3a79}@anchor{library/uuid uuid-cli-example}@anchor{3a7a}
@subsubsection Command-Line Example


Here are some examples of typical usage of the @ref{10f,,uuid} command line interface:

@example
# generate a random uuid - by default uuid4() is used
$ python -m uuid

# generate a uuid using uuid1()
$ python -m uuid -u uuid1

# generate a uuid using uuid5
$ python -m uuid -u uuid5 -n @@url -N example.com
@end example

@node socketserver --- A framework for network servers,http server --- HTTP servers,uuid --- UUID objects according to RFC 4122,Gestion des protocoles internet
@anchor{library/socketserver doc}@anchor{3a7b}@anchor{library/socketserver module-socketserver}@anchor{cc}@anchor{library/socketserver socketserver-a-framework-for-network-servers}@anchor{3a7c}
@subsection @code{socketserver} --- A framework for network servers


@geindex module; socketserver

`Code source :' Lib/socketserver.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/socketserver.py}


__________________________________________________________________


Le module @ref{cc,,socketserver} permet de simplifier le développement de serveurs réseaux.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Il existe quatre classes concrètes fondamentales :

@geindex TCPServer (classe dans socketserver)
@anchor{library/socketserver socketserver TCPServer}@anchor{12fd}
@deffn {Classe} socketserver.TCPServer (server_address, RequestHandlerClass, bind_and_activate=True)

Cette classe permet de créer des flux continus de données entre un client et un serveur en utilisant le protocole internet TCP. Si `bind_and_activate' est vrai, le constructeur tente automatiquement d'invoquer  @ref{3a7d,,server_bind()} et @ref{3a7e,,server_activate()}. Les autres paramètres sont passés à la classe de base @ref{111d,,BaseServer}.
@end deffn

@geindex UDPServer (classe dans socketserver)
@anchor{library/socketserver socketserver UDPServer}@anchor{3a7f}
@deffn {Classe} socketserver.UDPServer (server_address, RequestHandlerClass, bind_and_activate=True)

Cette classe utilise des datagrammes, qui sont des paquets d'information pouvant arriver dans le désordre, voire être perdus, durant le transport. Les paramètres sont identiques à @ref{12fd,,TCPServer}.
@end deffn

@geindex UnixStreamServer (classe dans socketserver)
@geindex UnixDatagramServer (classe dans socketserver)
@anchor{library/socketserver socketserver UnixStreamServer}@anchor{3a80}
@deffn {Classe} socketserver.UnixStreamServer (server_address, RequestHandlerClass, bind_and_activate=True)
@anchor{library/socketserver socketserver UnixDatagramServer}@anchor{3a81}
@deffnx {Classe} socketserver.UnixDatagramServer (server_address, RequestHandlerClass, bind_and_activate=True)

Ces classes, moins fréquemment utilisées, sont similaires aux classes pour TCP et UDP mais utilisent des connecteurs UNIX ; ces connecteurs ne sont disponibles que sur les plateformes UNIX. Les paramètres sont identiques à @ref{12fd,,TCPServer}.
@end deffn

Ces quatre classes traitent les requêtes de façon `synchrone' : chaque requête doit être terminée avant de pouvoir traiter la suivante. Cette méthode n'est pas adaptée si les requêtes prennent beaucoup de temps à être traitées. Cela peut arriver si les requêtes demandent beaucoup de calcul, ou si elles renvoient beaucoup de données que le client peine à traiter. Dans ce cas, la solution est de créer un processus ou un fil d’exécution séparé pour chaque requête ; les classes de mélange @ref{b65,,ForkingMixIn} et @ref{b66,,ThreadingMixIn} peuvent être utilisées pour réaliser ce comportement asynchrone.

La création d'un serveur requiert plusieurs étapes. Premièrement, vous devez créer une classe pour gérer les requêtes en héritant de @ref{3a82,,BaseRequestHandler} et surcharger sa méthode @ref{3a83,,handle()}, laquelle traitera les requêtes entrantes. Deuxièmement, vous devez instancier l'une des classes serveurs et lui passer l’adresse du serveur ainsi que la classe gérant les requêtes. Il est recommandé de faire ceci dans une instruction @ref{5bc,,with}. Ensuite, appelez la méthode @ref{1300,,handle_request()} ou @ref{111f,,serve_forever()} de l'objet serveur afin de traiter une ou plusieurs requêtes. Enfin, appelez la méthode @ref{3a84,,server_close()} pour fermer le connecteur (à moins que vous n'ayez utilisé une instruction @code{with}).

Lorsque vous héritez de @ref{b66,,ThreadingMixIn} pour déléguer les connexions à différent fils d’exécution, vous devez déclarer explicitement comment les fils d’exécution doivent se comporter en cas d'arrêt abrupt. La classe @ref{b66,,ThreadingMixIn} définit un attribut `daemon_threads', indiquant si le serveur doit attendre la fin des fils d’exécution ou non. Vous pouvez utiliser cet attribut si vous souhaitez que les fils d’exécution soient autonomes. La valeur par défaut est @ref{b25,,False}, indiquant que Python ne doit pas quitter avant que tous les fils d'exécution créés par @ref{b66,,ThreadingMixIn} ne soient terminés.

Toutes les classes de serveurs exposent les mêmes méthodes et attributs, peu importe le protocole réseau utilisé.

@menu
* Notes sur la création de serveurs:: 
* Objets serveur:: 
* Objets gestionnaire de requêtes:: 
* Exemples: Exemples<27>. 

@end menu

@node Notes sur la création de serveurs,Objets serveur,,socketserver --- A framework for network servers
@anchor{library/socketserver server-creation-notes}@anchor{3a85}
@subsubsection Notes sur la création de serveurs


Il y a cinq classes dans la hiérarchie. Quatre d'entre elles représentent des serveurs synchrones de quatre types différents :

@example
+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+
@end example

Note that @ref{3a81,,UnixDatagramServer} derives from @ref{3a7f,,UDPServer}, not from
@ref{3a80,,UnixStreamServer} --- the only difference between an IP and a Unix
server is the address family.

@geindex ForkingMixIn (classe dans socketserver)
@geindex ThreadingMixIn (classe dans socketserver)
@anchor{library/socketserver socketserver ForkingMixIn}@anchor{b65}
@deffn {Classe} socketserver.ForkingMixIn
@anchor{library/socketserver socketserver ThreadingMixIn}@anchor{b66}
@deffnx {Classe} socketserver.ThreadingMixIn

Des versions utilisant des fils d’exécution ou des processus peuvent être créées pour chaque type de serveur, en utilisant ces classes de mélange. Par exemple, @ref{3a86,,ThreadingUDPServer} est créé comme suit :

@example
class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass
@end example

La classe de mélange est en premier car elle surcharge une méthode définie dans @ref{3a7f,,UDPServer}. Configurer les différents attributs changera également le comportement du serveur.

La classe @ref{b65,,ForkingMixIn} et les classes créant des processus mentionnées ci-dessous sont uniquement disponibles sur les plateformes POSIX prenant en charge @ref{195,,fork()}.

@geindex block_on_close (attribut socketserver.ThreadingMixIn)
@anchor{library/socketserver socketserver ThreadingMixIn block_on_close}@anchor{beb}
@deffn {Attribut} block_on_close

@ref{3a84,,ForkingMixIn.server_close}
waits until all child processes complete, except if
@ref{beb,,block_on_close} attribute is @code{False}.

@ref{3a84,,ThreadingMixIn.server_close}
waits until all non-daemon threads complete, except if
@ref{beb,,block_on_close} attribute is @code{False}.
@end deffn

@geindex daemon_threads (attribut socketserver.ThreadingMixIn)
@anchor{library/socketserver socketserver ThreadingMixIn daemon_threads}@anchor{3a87}
@deffn {Attribut} daemon_threads

For @ref{b66,,ThreadingMixIn} use daemonic threads by setting
@ref{3a87,,ThreadingMixIn.daemon_threads}
to @code{True} to not wait until threads complete.
@end deffn


Modifié dans la version 3.7: @ref{3a84,,ForkingMixIn.server_close} and
@ref{3a84,,ThreadingMixIn.server_close} now waits until all
child processes and non-daemonic threads complete.
Add a new @ref{beb,,ForkingMixIn.block_on_close} class
attribute to opt-in for the pre-3.7 behaviour.

@end deffn

@geindex ForkingTCPServer (classe dans socketserver)
@geindex ForkingUDPServer (classe dans socketserver)
@geindex ThreadingTCPServer (classe dans socketserver)
@geindex ThreadingUDPServer (classe dans socketserver)
@geindex ForkingUnixStreamServer (classe dans socketserver)
@geindex ForkingUnixDatagramServer (classe dans socketserver)
@geindex ThreadingUnixStreamServer (classe dans socketserver)
@geindex ThreadingUnixDatagramServer (classe dans socketserver)
@anchor{library/socketserver socketserver ForkingTCPServer}@anchor{3a88}
@deffn {Classe} socketserver.ForkingTCPServer
@anchor{library/socketserver socketserver ForkingUDPServer}@anchor{3a89}
@deffnx {Classe} socketserver.ForkingUDPServer
@anchor{library/socketserver socketserver ThreadingTCPServer}@anchor{3a8a}
@deffnx {Classe} socketserver.ThreadingTCPServer
@anchor{library/socketserver socketserver ThreadingUDPServer}@anchor{3a86}
@deffnx {Classe} socketserver.ThreadingUDPServer
@anchor{library/socketserver socketserver ForkingUnixStreamServer}@anchor{3a8b}
@deffnx {Classe} socketserver.ForkingUnixStreamServer
@anchor{library/socketserver socketserver ForkingUnixDatagramServer}@anchor{3a8c}
@deffnx {Classe} socketserver.ForkingUnixDatagramServer
@anchor{library/socketserver socketserver ThreadingUnixStreamServer}@anchor{3a8d}
@deffnx {Classe} socketserver.ThreadingUnixStreamServer
@anchor{library/socketserver socketserver ThreadingUnixDatagramServer}@anchor{3a8e}
@deffnx {Classe} socketserver.ThreadingUnixDatagramServer

Ces classes sont prédéfinies en utilisant les classes de mélange.
@end deffn


Ajouté dans la version 3.12: The @code{ForkingUnixStreamServer} and @code{ForkingUnixDatagramServer} classes
were added.


Pour implémenter un service, vous devez créer une classe héritant de @ref{3a82,,BaseRequestHandler} et redéfinir sa méthode @ref{3a83,,handle()}. Ensuite, vous pourrez créer différentes versions de votre service en combinant les classes serveurs avec votre classe de gestion des requêtes. Cette classe de gestion des requêtes doit être différente pour les services utilisant des datagrammes ou des flux de données. Cette contrainte peut être dissimulée en utilisant les classes de gestion dérivées @ref{cc8,,StreamRequestHandler} ou @ref{3a8f,,DatagramRequestHandler}.

Bien entendu, vous devrez toujours utiliser votre tête ! Par exemple, utiliser un serveur utilisant des processus clonés (`forking') n'aurait aucun sens si le serveur garde en mémoire des états pouvant être modifiés par les requêtes reçues. En effet, un processus enfant traitant une requête n'aurait alors aucun moyen de propager le nouvel état à son parent. Dans ce cas, vous devez utiliser un serveur utilisant des fils d'exécution, mais cela demande probablement d'utiliser des verrous pour protéger l’intégrité des données partagées.

D'un autre côté, si vous développez un serveur HTTP qui a toutes ses données stockées hors de la mémoire (sur un système de fichiers par exemple), une classe synchrone rendrait le service sourd à toute nouvelle requête aussi longtemps qu'une précédente soit en cours de traitement. Cette situation pourrait perdurer pendant un long moment si le client prend du temps à recevoir toutes les données demandées. Dans ce cas, un serveur utilisant des processus ou des fils d'exécutions est approprié.

Dans certains cas, il peut être judicieux de commencer à traiter une requête de façon synchrone mais de pouvoir déléguer le reste du traitement à un processus enfant si besoin. Ce comportement peut être implémenté en utilisant un serveur synchrone et en laissant à la méthode @ref{3a83,,handle()}, de la classe gérant les requêtes, le soin de créer le processus enfant explicitement.

Another approach to handling multiple simultaneous requests in an environment
that supports neither threads nor @ref{195,,fork()} (or where these are too
expensive or inappropriate for the service) is to maintain an explicit table of
partially finished requests and to use @ref{c1,,selectors} to decide which
request to work on next (or whether to handle a new incoming request).  This is
particularly important for stream services where each client can potentially be
connected for a long time (if threads or subprocesses cannot be used).

@c XXX should data and methods be intermingled, or separate?
@c how should the distinction between class and instance variables be drawn?

@node Objets serveur,Objets gestionnaire de requêtes,Notes sur la création de serveurs,socketserver --- A framework for network servers
@anchor{library/socketserver server-objects}@anchor{3a90}
@subsubsection Objets serveur


@geindex BaseServer (classe dans socketserver)
@anchor{library/socketserver socketserver BaseServer}@anchor{111d}
@deffn {Classe} socketserver.BaseServer (server_address, RequestHandlerClass)

Il s'agit de la classe parente de tous les objets serveur du module. Elle déclare l'interface, définie ci-dessous, mais laisse aux classes filles le soin d'implémenter la plupart des méthodes. Les deux paramètres sont stockés respectivement dans les attributs @ref{3a91,,server_address} et @ref{3a92,,RequestHandlerClass}.

@geindex fileno() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer fileno}@anchor{3a93}
@deffn {Méthode} fileno ()

Renvoie un entier représentant le descripteur de fichier pour le connecteur que le serveur écoute. Cette fonction est, la plupart du temps, passée à @ref{c1,,selectors} afin de pouvoir surveiller plusieurs serveurs dans le même processus.
@end deffn

@geindex handle_request() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer handle_request}@anchor{1300}
@deffn {Méthode} handle_request ()

Traite une seule requête. Cette fonction appelle, dans l'ordre, les méthodes @ref{3a94,,get_request()}, @ref{3a95,,verify_request()} et @ref{3a96,,process_request()}. Si la méthode @ref{3a83,,handle()} de la classe de gestion des requêtes lève une exception, alors la méthode @ref{d2f,,handle_error()} du serveur est appelée. Si aucune requête n'est reçue avant « @ref{12fe,,timeout} » secondes, @ref{12ff,,handle_timeout()} est appelée et @ref{1300,,handle_request()} rend la main.
@end deffn

@geindex serve_forever() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer serve_forever}@anchor{111f}
@deffn {Méthode} serve_forever (poll_interval=0.5)

Gère les requêtes indéfiniment jusqu'à ce que @ref{19c3,,shutdown()} soit appelée. Vérifie si une demande d’arrêt (`shutdown') a été émise toutes les `poll_interval' secondes. Ignore l'attribut @ref{12fe,,timeout}. Appelle également @ref{111e,,service_actions()}, qui peut être utilisée par une classe enfant ou une classe de mélange afin d'implémenter une action spécifique pour un service donné. Par exemple, la classe @ref{b65,,ForkingMixIn} utilise @ref{111e,,service_actions()} pour supprimer les processus enfants zombies.


Modifié dans la version 3.3: La méthode @code{serve_forever} appelle dorénavant @code{service_actions}.

@end deffn

@geindex service_actions() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer service_actions}@anchor{111e}
@deffn {Méthode} service_actions ()

Cette méthode est appelée dans la boucle de @ref{111f,,serve_forever()}. Cette méthode peut être surchargée par une classe fille ou une classe de mélange afin d'effectuer une action spécifique à un service donné, comme une action de nettoyage.


Ajouté dans la version 3.3.

@end deffn

@geindex shutdown() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer shutdown}@anchor{19c3}
@deffn {Méthode} shutdown ()

Demande l'arrêt de la boucle de @ref{111f,,serve_forever()} et attend jusqu'à ce que ce soit fait. @ref{19c3,,shutdown()} doit être appelée dans un fil d’exécution différent de @ref{111f,,serve_forever()} sous peine d'interblocage.
@end deffn

@geindex server_close() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_close}@anchor{3a84}
@deffn {Méthode} server_close ()

Nettoie le serveur. Peut être surchargée.
@end deffn

@geindex address_family (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer address_family}@anchor{3a97}
@deffn {Attribut} address_family

La famille de protocoles auquel le connecteur appartient. Les exemples les plus communs sont @ref{17ab,,socket.AF_INET} et @ref{17ad,,socket.AF_UNIX}.
@end deffn

@geindex RequestHandlerClass (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer RequestHandlerClass}@anchor{3a92}
@deffn {Attribut} RequestHandlerClass

La classe de gestion des requêtes, fournie par l'utilisateur. Une instance de cette classe est créée pour chaque requête.
@end deffn

@geindex server_address (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_address}@anchor{3a91}
@deffn {Attribut} server_address

Renvoie l’adresse sur laquelle le serveur écoute. Le format de l’adresse dépend de la famille de protocoles utilisée ; pour plus de détails, voir la documentation du module @ref{cb,,socket}. Pour les protocoles Internet, cette valeur est une paire formée d'une chaine de caractère pour l’adresse et d'un entier pour le port. Exemple : @code{('127.0.0.1', 80)}.
@end deffn

@geindex socket (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer socket}@anchor{3a98}
@deffn {Attribut} socket

L'objet connecteur utilisé par le serveur pour écouter les nouvelles requêtes.
@end deffn

Les classes serveurs prennent en charge les variables de classe suivantes :

@c XXX should class variables be covered before instance variables, or vice versa?

@geindex allow_reuse_address (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer allow_reuse_address}@anchor{3a99}
@deffn {Attribut} allow_reuse_address

Indique si le serveur autorise la réutilisation d'une adresse. La valeur par défaut est @ref{b25,,False} mais cela peut être changé dans les classes enfants.
@end deffn

@geindex request_queue_size (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer request_queue_size}@anchor{3a9a}
@deffn {Attribut} request_queue_size

La taille de la file des requêtes. Lorsque traiter une requête prend du temps, toute nouvelle requête arrivant pendant que le serveur est occupé est placé dans une file jusqu'à atteindre « @ref{3a9a,,request_queue_size} » requêtes. Si la queue est pleine, les nouvelles requêtes clientes se voient renvoyer une erreur `Connection denied'. La valeur par défaut est habituellement 5 mais peut être changée par les classes filles.
@end deffn

@geindex socket_type (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer socket_type}@anchor{3a9b}
@deffn {Attribut} socket_type

Le type de connecteur utilisé par le serveur ; @ref{12d1,,socket.SOCK_STREAM} et @ref{12d0,,socket.SOCK_DGRAM} sont deux valeurs usuelles.
@end deffn

@geindex timeout (attribut socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer timeout}@anchor{12fe}
@deffn {Attribut} timeout

Délai d'attente en secondes, ou @ref{660,,None} si aucune limite n'est demandée. Si @ref{1300,,handle_request()} ne reçoit aucune requête entrante pendant le délai d'attente, la méthode @ref{12ff,,handle_timeout()} est appelée.
@end deffn

Il existe plusieurs méthodes serveur pouvant être surchargées par des classes dérivant de classes de base comme @ref{12fd,,TCPServer} ; ces méthodes ne sont pas utiles aux utilisateurs externes de l'objet serveur.

@c XXX should the default implementations of these be documented, or should
@c it be assumed that the user will look at socketserver.py?

@geindex finish_request() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer finish_request}@anchor{3a9c}
@deffn {Méthode} finish_request (request, client_address)

Méthode en charge de traiter la requête en instanciant @ref{3a92,,RequestHandlerClass} et en appelant sa méthode @ref{3a83,,handle()}.
@end deffn

@geindex get_request() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer get_request}@anchor{3a94}
@deffn {Méthode} get_request ()

Accepte obligatoirement une requête depuis le connecteur et renvoie une paire contenant le `nouvel' objet connecteur utilisé pour communiquer avec le client et l'adresse du client.
@end deffn

@geindex handle_error() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer handle_error}@anchor{d2f}
@deffn {Méthode} handle_error (request, client_address)

Cette fonction est appelée si la méthode @ref{3a83,,handle()} de l'objet @ref{3a92,,RequestHandlerClass} lève une exception. Par défaut, la méthode imprime la trace d'appels sur la sortie d'erreur standard et continue de traiter les requêtes suivantes.


Modifié dans la version 3.6: N'est maintenant appelée que sur les exceptions dérivant de la classe @ref{9c7,,Exception}.

@end deffn

@geindex handle_timeout() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer handle_timeout}@anchor{12ff}
@deffn {Méthode} handle_timeout ()

Cette fonction est appelée lorsque l'attribut @ref{12fe,,timeout} est réglé à autre chose que @ref{660,,None} et que le délai d'attente expire sans qu'aucune requête ne soit reçue. Par défaut, cette fonction récupère le statut de tous les processus enfants ayant terminé pour les serveurs utilisant des processus ou ne fait rien pour le cas des serveurs utilisant des fils d’exécution.
@end deffn

@geindex process_request() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer process_request}@anchor{3a96}
@deffn {Méthode} process_request (request, client_address)

Appelle @ref{3a9c,,finish_request()} pour instancier @ref{3a92,,RequestHandlerClass}. Si désiré, cette fonction peut créer des processus fils ou des fils d’exécution pour traiter les requêtes ; les classes de mélange @ref{b65,,ForkingMixIn} et @ref{b66,,ThreadingMixIn} implémentent cela.
@end deffn

@c Is there any point in documenting the following two functions?
@c What would the purpose of overriding them be: initializing server
@c instance variables, adding new network families?

@geindex server_activate() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_activate}@anchor{3a7e}
@deffn {Méthode} server_activate ()

Appelée par le constructeur du serveur afin de l'activer. Le comportement par défaut pour un serveur TCP est de seulement invoquer @ref{e47,,listen()} sur le connecteur du serveur. Peut être surchargée.
@end deffn

@geindex server_bind() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer server_bind}@anchor{3a7d}
@deffn {Méthode} server_bind ()

Appelée par le constructeur du serveur afin d'assigner (`bind') l'adresse requise au connecteur du serveur. Peut être surchargée.
@end deffn

@geindex verify_request() (méthode socketserver.BaseServer)
@anchor{library/socketserver socketserver BaseServer verify_request}@anchor{3a95}
@deffn {Méthode} verify_request (request, client_address)

Doit renvoyer un booléen. Si la valeur est @ref{bfb,,True}, la requête sera traitée. Si la valeur est @ref{b25,,False}, la requête sera refusée. Cette fonction peut être surchargée afin d'implémenter une stratégie de contrôle d'accès au serveur. L'implémentation par défaut renvoie toujours @ref{bfb,,True}.
@end deffn


Modifié dans la version 3.6: La gestion du protocole @ref{5be,,context manager} a été ajoutée. Sortir du gestionnaire de contexte revient à appeler @ref{3a84,,server_close()}.

@end deffn

@node Objets gestionnaire de requêtes,Exemples<27>,Objets serveur,socketserver --- A framework for network servers
@anchor{library/socketserver request-handler-objects}@anchor{3a9d}
@subsubsection Objets gestionnaire de requêtes


@geindex BaseRequestHandler (classe dans socketserver)
@anchor{library/socketserver socketserver BaseRequestHandler}@anchor{3a82}
@deffn {Classe} socketserver.BaseRequestHandler

Classe de base de tous les objets gestionnaire de requêtes. Elle déclare l'interface, définie ci-dessous, pour tous les gestionnaires. Une implémentation concrète doit définir une nouvelle méthode @ref{3a83,,handle()} et peut surcharger n'importe quelle autre méthode. Cette classe concrète est instanciée pour chaque requête.

@geindex setup() (méthode socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler setup}@anchor{3a9e}
@deffn {Méthode} setup ()

Appelée avant la méthode @ref{3a83,,handle()} afin d'effectuer toutes les opérations d'initialisation requises. L'implémentation par défaut ne fait rien.
@end deffn

@geindex handle() (méthode socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler handle}@anchor{3a83}
@deffn {Méthode} handle ()

This function must do all the work required to service a request.  The
default implementation does nothing.  Several instance attributes are
available to it; the request is available as @ref{3a9f,,request}; the client
address as @ref{3aa0,,client_address}; and the server instance as
@ref{3aa1,,server}, in case it needs access to per-server information.

The type of @ref{3a9f,,request} is different for datagram or stream
services.  For stream services, @ref{3a9f,,request} is a socket object; for
datagram services, @ref{3a9f,,request} is a pair of string and socket.
@end deffn

@geindex finish() (méthode socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler finish}@anchor{3aa2}
@deffn {Méthode} finish ()

Appelée après la méthode @ref{3a83,,handle()} pour effectuer les opérations de nettoyage requises. L'implémentation par défaut ne fait rien. Si @ref{3a9e,,setup()} lève une exception, cette méthode n'est pas appelée.
@end deffn

@geindex request (attribut socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler request}@anchor{3a9f}
@deffn {Attribut} request

The `new' @ref{d8e,,socket.socket} object
to be used to communicate with the client.
@end deffn

@geindex client_address (attribut socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler client_address}@anchor{3aa0}
@deffn {Attribut} client_address

Client address returned by @ref{3a94,,BaseServer.get_request()}.
@end deffn

@geindex server (attribut socketserver.BaseRequestHandler)
@anchor{library/socketserver socketserver BaseRequestHandler server}@anchor{3aa1}
@deffn {Attribut} server

@ref{111d,,BaseServer} object used for handling the request.
@end deffn
@end deffn

@geindex StreamRequestHandler (classe dans socketserver)
@geindex DatagramRequestHandler (classe dans socketserver)
@anchor{library/socketserver socketserver StreamRequestHandler}@anchor{cc8}
@deffn {Classe} socketserver.StreamRequestHandler
@anchor{library/socketserver socketserver DatagramRequestHandler}@anchor{3a8f}
@deffnx {Classe} socketserver.DatagramRequestHandler

These @ref{3a82,,BaseRequestHandler} subclasses override the
@ref{3a9e,,setup()} and @ref{3aa2,,finish()}
methods, and provide @ref{3aa3,,rfile} and @ref{3aa4,,wfile} attributes.

@geindex rfile (attribut socketserver.DatagramRequestHandler)
@anchor{library/socketserver socketserver DatagramRequestHandler rfile}@anchor{3aa3}
@deffn {Attribut} rfile

A file object from which receives the request is read.
Support the @ref{67f,,io.BufferedIOBase} readable interface.
@end deffn

@geindex wfile (attribut socketserver.DatagramRequestHandler)
@anchor{library/socketserver socketserver DatagramRequestHandler wfile}@anchor{3aa4}
@deffn {Attribut} wfile

A file object to which the reply is written.
Support the @ref{67f,,io.BufferedIOBase} writable interface
@end deffn


Modifié dans la version 3.6: @ref{3aa4,,wfile} also supports the
@ref{67f,,io.BufferedIOBase} writable interface.

@end deffn

@node Exemples<27>,,Objets gestionnaire de requêtes,socketserver --- A framework for network servers
@anchor{library/socketserver examples}@anchor{3aa5}
@subsubsection Exemples


@menu
* Exemple pour socketserver.TCPServer: Exemple pour socketserver TCPServer. 
* Exemple pour socketserver.UDPServer: Exemple pour socketserver UDPServer. 
* Classes de mélange asynchrone:: 

@end menu

@node Exemple pour socketserver TCPServer,Exemple pour socketserver UDPServer,,Exemples<27>
@anchor{library/socketserver socketserver-tcpserver-example}@anchor{3aa6}
@subsubsection Exemple pour @code{socketserver.TCPServer}


Implémentation côté serveur :

@example
import socketserver

class MyTCPHandler(socketserver.BaseRequestHandler):
    """
    The request handler class for our server.

    It is instantiated once per connection to the server, and must
    override the handle() method to implement communication to the
    client.
    """

    def handle(self):
        # self.request is the TCP socket connected to the client
        self.data = self.request.recv(1024).strip()
        print("Received from @{@}:".format(self.client_address[0]))
        print(self.data)
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999

    # Create the server, binding to localhost on port 9999
    with socketserver.TCPServer((HOST, PORT), MyTCPHandler) as server:
        # Activate the server; this will keep running until you
        # interrupt the program with Ctrl-C
        server.serve_forever()
@end example

Une implémentation alternative du gestionnaire de requêtes utilisant les flux de données (avec des objets fichier-compatibles simplifiant la communication en fournissant l'interface fichier standard) :

@example
class MyTCPHandler(socketserver.StreamRequestHandler):

    def handle(self):
        # self.rfile is a file-like object created by the handler;
        # we can now use e.g. readline() instead of raw recv() calls
        self.data = self.rfile.readline().strip()
        print("@{@} wrote:".format(self.client_address[0]))
        print(self.data)
        # Likewise, self.wfile is a file-like object used to write back
        # to the client
        self.wfile.write(self.data.upper())
@end example

The difference is that the @code{readline()} call in the second handler will call
@code{recv()} multiple times until it encounters a newline character, while the
single @code{recv()} call in the first handler will just return what has been
received so far from the client's @code{sendall()} call (typically all of it, but
this is not guaranteed by the TCP protocol).

Implémentation côté client :

@example
import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# Create a socket (SOCK_STREAM means a TCP socket)
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
    # Connect to server and send data
    sock.connect((HOST, PORT))
    sock.sendall(bytes(data + "\n", "utf-8"))

    # Receive data from the server and shut down
    received = str(sock.recv(1024), "utf-8")

print("Sent:     @{@}".format(data))
print("Received: @{@}".format(received))
@end example

La sortie de cet exemple devrait ressembler à ça :

Serveur :

@example
$ python TCPServer.py
127.0.0.1 wrote:
b'hello world with TCP'
127.0.0.1 wrote:
b'python is nice'
@end example

Client :

@example
$ python TCPClient.py hello world with TCP
Sent:     hello world with TCP
Received: HELLO WORLD WITH TCP
$ python TCPClient.py python is nice
Sent:     python is nice
Received: PYTHON IS NICE
@end example

@node Exemple pour socketserver UDPServer,Classes de mélange asynchrone,Exemple pour socketserver TCPServer,Exemples<27>
@anchor{library/socketserver socketserver-udpserver-example}@anchor{3aa7}
@subsubsection Exemple pour @code{socketserver.UDPServer}


Implémentation côté serveur :

@example
import socketserver

class MyUDPHandler(socketserver.BaseRequestHandler):
    """
    This class works similar to the TCP handler class, except that
    self.request consists of a pair of data and client socket, and since
    there is no connection the client address must be given explicitly
    when sending data back via sendto().
    """

    def handle(self):
        data = self.request[0].strip()
        socket = self.request[1]
        print("@{@} wrote:".format(self.client_address[0]))
        print(data)
        socket.sendto(data.upper(), self.client_address)

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999
    with socketserver.UDPServer((HOST, PORT), MyUDPHandler) as server:
        server.serve_forever()
@end example

Implémentation côté client :

@example
import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# SOCK_DGRAM is the socket type to use for UDP sockets
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# As you can see, there is no connect() call; UDP has no connections.
# Instead, data is directly sent to the recipient via sendto().
sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))
received = str(sock.recv(1024), "utf-8")

print("Sent:     @{@}".format(data))
print("Received: @{@}".format(received))
@end example

La sortie de cet exemple devrait ressembler exactement à la sortie de l'exemple pour le serveur TCP.

@node Classes de mélange asynchrone,,Exemple pour socketserver UDPServer,Exemples<27>
@anchor{library/socketserver asynchronous-mixins}@anchor{3aa8}
@subsubsection Classes de mélange asynchrone


Pour développer des gestionnaires asynchrones, utilisez les classes @ref{b66,,ThreadingMixIn} et @ref{b65,,ForkingMixIn}.

Exemple pour @ref{b66,,ThreadingMixIn} :

@example
import socket
import threading
import socketserver

class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):

    def handle(self):
        data = str(self.request.recv(1024), 'ascii')
        cur_thread = threading.current_thread()
        response = bytes("@{@}: @{@}".format(cur_thread.name, data), 'ascii')
        self.request.sendall(response)

class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
    pass

def client(ip, port, message):
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.connect((ip, port))
        sock.sendall(bytes(message, 'ascii'))
        response = str(sock.recv(1024), 'ascii')
        print("Received: @{@}".format(response))

if __name__ == "__main__":
    # Port 0 means to select an arbitrary unused port
    HOST, PORT = "localhost", 0

    server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
    with server:
        ip, port = server.server_address

        # Start a thread with the server -- that thread will then start one
        # more thread for each request
        server_thread = threading.Thread(target=server.serve_forever)
        # Exit the server thread when the main thread terminates
        server_thread.daemon = True
        server_thread.start()
        print("Server loop running in thread:", server_thread.name)

        client(ip, port, "Hello World 1")
        client(ip, port, "Hello World 2")
        client(ip, port, "Hello World 3")

        server.shutdown()
@end example

La sortie de cet exemple devrait ressembler à ça :

@example
$ python ThreadedTCPServer.py
Server loop running in thread: Thread-1
Received: Thread-2: Hello World 1
Received: Thread-3: Hello World 2
Received: Thread-4: Hello World 3
@end example

La classe @ref{b65,,ForkingMixIn} est utilisable de la même façon à la différence près que le serveur crée un nouveau processus fils pour chaque requête. Disponible uniquement sur les plateformes POSIX prenant en charge @ref{195,,fork()}.

@node http server --- HTTP servers,http cookies --- HTTP state management,socketserver --- A framework for network servers,Gestion des protocoles internet
@anchor{library/http server doc}@anchor{3aa9}@anchor{library/http server http-server-http-servers}@anchor{3aaa}@anchor{library/http server module-http server}@anchor{71}
@subsection @code{http.server} --- HTTP servers


@geindex module; http.server

`Code source :' Lib/http/server.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/http/server.py}

@geindex WWW;server
@geindex HTTP;protocol
@geindex URL
@geindex httpd


__________________________________________________________________


Ce module définit des classes implémentant des serveurs HTTP.

@cartouche
@quotation Avertissement 
@ref{71,,http.server} is not recommended for production. It only implements
@ref{3aab,,basic security checks}.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

Une des classes, @ref{38af,,HTTPServer}, est une sous-classe de @ref{12fd,,socketserver.TCPServer}. Elle crée une interface de connexion (`socket' en anglais) avant de rester à l'écoute des messages reçus sur celle-ci, les répartissant à un gestionnaire d'évènements (`handler' en anglais). Le code pour créer et exécuter le serveur ressemble à ceci :

@example
def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
    server_address = ('@w{'}, 8000)
    httpd = server_class(server_address, handler_class)
    httpd.serve_forever()
@end example

@geindex HTTPServer (classe dans http.server)
@anchor{library/http server http server HTTPServer}@anchor{38af}
@deffn {Classe} http.server.HTTPServer (server_address, RequestHandlerClass)

Cette classe hérite de la classe @ref{12fd,,TCPServer}. Ses instances contiennent l'adresse du serveur dans les variables d'instance @code{server_name} et @code{server_port}.Le serveur est accessible par le gestionnaire d'évènements, habituellement par le biais de sa variable d'instance @code{server}.
@end deffn

@geindex ThreadingHTTPServer (classe dans http.server)
@anchor{library/http server http server ThreadingHTTPServer}@anchor{b32}
@deffn {Classe} http.server.ThreadingHTTPServer (server_address, RequestHandlerClass)

Cette classe est identique à `HTTPServer' mais utilise des fils d'exécution afin de gérer les requêtes, et ce, par le biais de @ref{b66,,ThreadingMixIn}. Ceci est utile afin de gérer les pré-ouvertures des interfaces de connexion des navigateurs web, sur lesquelles @ref{38af,,HTTPServer} attendrait de façon perpétuelle.


Ajouté dans la version 3.7.

@end deffn

On doit passer un `RequestHandlerClass' lors de l'instanciation de @ref{38af,,HTTPServer} et de @ref{b32,,ThreadingHTTPServer}. Ce module fournit trois variantes différentes :

@geindex BaseHTTPRequestHandler (classe dans http.server)
@anchor{library/http server http server BaseHTTPRequestHandler}@anchor{10ad}
@deffn {Classe} http.server.BaseHTTPRequestHandler (request, client_address, server)

Cette classe est utilisée afin de gérer les requêtes HTTP arrivant au serveur. Elle ne peut pas répondre par elle-même à des requêtes HTTP ; cette méthode doit être surchargée dans les classes dérivées, par exemple `GET' ou `POST'. La classe @ref{10ad,,BaseHTTPRequestHandler} fournit plusieurs classes et variables d'instance, ainsi que des méthodes à utiliser par les sous-classes.

The handler will parse the request and the headers, then call a method
specific to the request type. The method name is constructed from the
request. For example, for the request method @code{SPAM}, the @code{do_SPAM()}
method will be called with no arguments. All of the relevant information is
stored in instance variables of the handler.  Subclasses should not need to
override or extend the @code{__init__()} method.

@ref{10ad,,BaseHTTPRequestHandler} a les variables d'instances suivantes :

@geindex client_address (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler client_address}@anchor{3aac}
@deffn {Attribut} client_address

Contient un `n'-uplet de la forme @code{(host, port)}, faisant référence à l'adresse du client.
@end deffn

@geindex server (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler server}@anchor{3aad}
@deffn {Attribut} server

Contient l'instance du serveur.
@end deffn

@geindex close_connection (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler close_connection}@anchor{3aae}
@deffn {Attribut} close_connection

Booléen qui doit être défini avant que @ref{3aaf,,handle_one_request()} ne termine son exécution, indiquant si on peut recevoir une autre requête ou si la connexion doit être fermée.
@end deffn

@geindex requestline (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler requestline}@anchor{3ab0}
@deffn {Attribut} requestline

Contient la chaîne de caractères représentant la ligne de requête HTTP. La dénotation de fin de ligne `CRLF' est enlevée. Cet attribut doit être défini par @ref{3aaf,,handle_one_request()}. Dans le cas où aucune ligne de requête valide n'a été traitée, il doit prendre la valeur de la chaîne de caractères vide.
@end deffn

@geindex command (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler command}@anchor{3ab1}
@deffn {Attribut} command

Contient la commande (le type de requête). Par exemple, @code{'GET'}.
@end deffn

@geindex path (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler path}@anchor{3ab2}
@deffn {Attribut} path

Contient le chemin de la requête. Si la composante de requête de l'URL est présente, alors @code{path} contient la requête. Selon la terminologie de 
@geindex RFC; RFC 3986
RFC 3986@footnote{https://datatracker.ietf.org/doc/html/rfc3986.html}, @code{path} inclut ici @code{hier-part} et la @code{query}.
@end deffn

@geindex request_version (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler request_version}@anchor{3ab3}
@deffn {Attribut} request_version

Contient la version de la requête, en chaîne de caractères. Par exemple, @code{'HTTP/1.0'}.
@end deffn

@geindex headers (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler headers}@anchor{3998}
@deffn {Attribut} headers

Holds an instance of the class specified by the @ref{3ab4,,MessageClass} class
variable. This instance parses and manages the headers in the HTTP
request. The @ref{19d7,,parse_headers()} function from
@ref{6e,,http.client} is used to parse the headers and it requires that the
HTTP request provide a valid 
@geindex RFC; RFC 2822
RFC 2822@footnote{https://datatracker.ietf.org/doc/html/rfc2822.html} style header.
@end deffn

@geindex rfile (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler rfile}@anchor{3ab5}
@deffn {Attribut} rfile

An @ref{67f,,io.BufferedIOBase} input stream, ready to read from
the start of the optional input data.
@end deffn

@geindex wfile (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler wfile}@anchor{3ab6}
@deffn {Attribut} wfile

Contains the output stream for writing a response back to the
client. Proper adherence to the HTTP protocol must be used when writing to
this stream in order to achieve successful interoperation with HTTP
clients.


Modifié dans la version 3.6: This is an @ref{67f,,io.BufferedIOBase} stream.

@end deffn

@ref{10ad,,BaseHTTPRequestHandler} has the following attributes:

@geindex server_version (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler server_version}@anchor{3ab7}
@deffn {Attribut} server_version

Précise la version du logiciel du serveur. Vous pouvez la modifier. Le format utilisé est constitué de plusieurs chaînes de caractères séparées par des caractères d'espacement, où chaque chaîne prend la forme `nom[/version]'. Par exemple, @code{'BaseHTTP/0.2'}.
@end deffn

@geindex sys_version (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler sys_version}@anchor{3ab8}
@deffn {Attribut} sys_version

Contient la version système de Python, dans une forme pouvant être utilisée par la méthode @ref{3ab9,,version_string} ainsi que par la variable de classe @ref{3ab7,,server_version}. Par exemple, @code{'Python/1.4'}.
@end deffn

@geindex error_message_format (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler error_message_format}@anchor{3aba}
@deffn {Attribut} error_message_format

Définit une chaîne de caractères avec champs de formatage devant être utilisée par la méthode @ref{f3b,,send_error()} afin de construire une réponse d'erreur pour le client. Par défaut, la chaîne contient des variables provenant de l'attribut @ref{397f,,responses} se basant sur le code de statut passé à @ref{f3b,,send_error()}.
@end deffn

@geindex error_content_type (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler error_content_type}@anchor{3abb}
@deffn {Attribut} error_content_type

Définit l'en-tête HTTP Content-Type des réponses d'erreur envoyées au client. La valeur par défaut est @code{'text/html'}.
@end deffn

@geindex protocol_version (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler protocol_version}@anchor{3abc}
@deffn {Attribut} protocol_version

Specifies the HTTP version to which the server is conformant. It is sent
in responses to let the client know the server's communication
capabilities for future requests. If set to
@code{'HTTP/1.1'}, the server will permit HTTP persistent connections;
however, your server `must' then include an accurate @code{Content-Length}
header (using @ref{3abd,,send_header()}) in all of its responses to clients.
For backwards compatibility, the setting defaults to @code{'HTTP/1.0'}.
@end deffn

@geindex MessageClass (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler MessageClass}@anchor{3ab4}
@deffn {Attribut} MessageClass

Définit une classe similaire à @ref{279,,email.message.Message} permettant l'analyse des en-têtes HTTP. Habituellement, cette valeur n'est pas modifiée, et prend par défaut la valeur de @ref{3996,,http.client.HTTPMessage}.
@end deffn

@geindex responses (attribut http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler responses}@anchor{397f}
@deffn {Attribut} responses

Cet attribut contient une table de correspondance entre des codes d'erreurs dénotés par des entiers et des `n'-uplets contenant un message court et un message long. Par exemple, @code{@{code: (shortmessage, longmessage)@}}. Habituellement, le message `shortmessage' correspond à la clé `message' d'une réponse d'erreur, alors que le message `longmessage' correspond à la clé `explain' de celle-ci. Il est utilisé par les méthodes @ref{3abe,,send_response_only()} et @ref{f3b,,send_error()}.
@end deffn

Une instance de la classe @ref{10ad,,BaseHTTPRequestHandler} contient les méthodes suivantes :

@geindex handle() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler handle}@anchor{3abf}
@deffn {Méthode} handle ()

Calls @ref{3aaf,,handle_one_request()} once (or, if persistent connections are
enabled, multiple times) to handle incoming HTTP requests. You should
never need to override it; instead, implement appropriate @code{do_*()}
methods.
@end deffn

@geindex handle_one_request() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler handle_one_request}@anchor{3aaf}
@deffn {Méthode} handle_one_request ()

This method will parse and dispatch the request to the appropriate
@code{do_*()} method.  You should never need to override it.
@end deffn

@geindex handle_expect_100() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler handle_expect_100}@anchor{3ac0}
@deffn {Méthode} handle_expect_100 ()

When an HTTP/1.1 conformant server receives an @code{Expect: 100-continue}
request header it responds back with a @code{100 Continue} followed by @code{200
OK} headers.
This method can be overridden to raise an error if the server does not
want the client to continue.  For e.g. server can choose to send @code{417
Expectation Failed} as a response header and @code{return False}.


Ajouté dans la version 3.2.

@end deffn

@geindex send_error() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_error}@anchor{f3b}
@deffn {Méthode} send_error (code, message=None, explain=None)

Sends and logs a complete error reply to the client. The numeric `code'
specifies the HTTP error code, with `message' as an optional, short, human
readable description of the error.  The `explain' argument can be used to
provide more detailed information about the error; it will be formatted
using the @ref{3aba,,error_message_format} attribute and emitted, after
a complete set of headers, as the response body.  The @ref{397f,,responses}
attribute holds the default values for `message' and `explain' that
will be used if no value is provided; for unknown codes the default value
for both is the string @code{???}. The body will be empty if the method is
HEAD or the response code is one of the following: @code{1@var{xx}},
@code{204 No Content}, @code{205 Reset Content}, @code{304 Not Modified}.


Modifié dans la version 3.4: The error response includes a Content-Length header.
Added the `explain' argument.

@end deffn

@geindex send_response() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_response}@anchor{3ac1}
@deffn {Méthode} send_response (code, message=None)

Adds a response header to the headers buffer and logs the accepted
request. The HTTP response line is written to the internal buffer,
followed by `Server' and `Date' headers. The values for these two headers
are picked up from the @ref{3ab9,,version_string()} and
@ref{3ac2,,date_time_string()} methods, respectively. If the server does not
intend to send any other headers using the @ref{3abd,,send_header()} method,
then @ref{3ac1,,send_response()} should be followed by an @ref{10ae,,end_headers()}
call.


Modifié dans la version 3.3: Headers are stored to an internal buffer and @ref{10ae,,end_headers()}
needs to be called explicitly.

@end deffn

@geindex send_header() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_header}@anchor{3abd}
@deffn {Méthode} send_header (keyword, value)

Adds the HTTP header to an internal buffer which will be written to the
output stream when either @ref{10ae,,end_headers()} or @ref{10af,,flush_headers()} is
invoked. `keyword' should specify the header keyword, with `value'
specifying its value. Note that, after the send_header calls are done,
@ref{10ae,,end_headers()} MUST BE called in order to complete the operation.


Modifié dans la version 3.2: Headers are stored in an internal buffer.

@end deffn

@geindex send_response_only() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler send_response_only}@anchor{3abe}
@deffn {Méthode} send_response_only (code, message=None)

Sends the response header only, used for the purposes when @code{100
Continue} response is sent by the server to the client. The headers not
buffered and sent directly the output stream.If the `message' is not
specified, the HTTP message corresponding the response `code'  is sent.


Ajouté dans la version 3.2.

@end deffn

@geindex end_headers() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler end_headers}@anchor{10ae}
@deffn {Méthode} end_headers ()

Adds a blank line
(indicating the end of the HTTP headers in the response)
to the headers buffer and calls @ref{10af,,flush_headers()}.


Modifié dans la version 3.2: The buffered headers are written to the output stream.

@end deffn

@geindex flush_headers() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler flush_headers}@anchor{10af}
@deffn {Méthode} flush_headers ()

Finally send the headers to the output stream and flush the internal
headers buffer.


Ajouté dans la version 3.3.

@end deffn

@geindex log_request() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_request}@anchor{3ac3}
@deffn {Méthode} log_request (code='-', size='-')

Logs an accepted (successful) request. `code' should specify the numeric
HTTP code associated with the response. If a size of the response is
available, then it should be passed as the `size' parameter.
@end deffn

@geindex log_error() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_error}@anchor{3ac4}
@deffn {Méthode} log_error (...)

Logs an error when a request cannot be fulfilled. By default, it passes
the message to @ref{3ac5,,log_message()}, so it takes the same arguments
(`format' and additional values).
@end deffn

@geindex log_message() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_message}@anchor{3ac5}
@deffn {Méthode} log_message (format, ...)

Logs an arbitrary message to @code{sys.stderr}. This is typically overridden
to create custom error logging mechanisms. The `format' argument is a
standard printf-style format string, where the additional arguments to
@ref{3ac5,,log_message()} are applied as inputs to the formatting. The client
ip address and current date and time are prefixed to every message logged.
@end deffn

@geindex version_string() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler version_string}@anchor{3ab9}
@deffn {Méthode} version_string ()

Returns the server software's version string. This is a combination of the
@ref{3ab7,,server_version} and @ref{3ab8,,sys_version} attributes.
@end deffn

@geindex date_time_string() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler date_time_string}@anchor{3ac2}
@deffn {Méthode} date_time_string (timestamp=None)

Returns the date and time given by `timestamp' (which must be @code{None} or in
the format returned by @ref{251,,time.time()}), formatted for a message
header. If `timestamp' is omitted, it uses the current date and time.

The result looks like @code{'Sun, 06 Nov 1994 08:49:37 GMT'}.
@end deffn

@geindex log_date_time_string() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler log_date_time_string}@anchor{3ac6}
@deffn {Méthode} log_date_time_string ()

Returns the current date and time, formatted for logging.
@end deffn

@geindex address_string() (méthode http.server.BaseHTTPRequestHandler)
@anchor{library/http server http server BaseHTTPRequestHandler address_string}@anchor{3ac7}
@deffn {Méthode} address_string ()

Returns the client address.


Modifié dans la version 3.3: Previously, a name lookup was performed. To avoid name resolution
delays, it now always returns the IP address.

@end deffn
@end deffn

@geindex SimpleHTTPRequestHandler (classe dans http.server)
@anchor{library/http server http server SimpleHTTPRequestHandler}@anchor{b31}
@deffn {Classe} http.server.SimpleHTTPRequestHandler (request, client_address, server, directory=None)

This class serves files from the directory `directory' and below,
or the current directory if `directory' is not provided, directly
mapping the directory structure to HTTP requests.


Modifié dans la version 3.7: Added the `directory' parameter.



Modifié dans la version 3.9: The `directory' parameter accepts a @ref{29d,,path-like object}.


A lot of the work, such as parsing the request, is done by the base class
@ref{10ad,,BaseHTTPRequestHandler}.  This class implements the @ref{3ac8,,do_GET()}
and @ref{3ac9,,do_HEAD()} functions.

The following are defined as class-level attributes of
@ref{b31,,SimpleHTTPRequestHandler}:

@geindex server_version (attribut http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler server_version}@anchor{3aca}
@deffn {Attribut} server_version

This will be @code{"SimpleHTTP/" + __version__}, where @code{__version__} is
defined at the module level.
@end deffn

@geindex extensions_map (attribut http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler extensions_map}@anchor{3acb}
@deffn {Attribut} extensions_map

A dictionary mapping suffixes into MIME types, contains custom overrides
for the default system mappings. The mapping is used case-insensitively,
and so should contain only lower-cased keys.


Modifié dans la version 3.9: This dictionary is no longer filled with the default system mappings,
but only contains overrides.

@end deffn

The @ref{b31,,SimpleHTTPRequestHandler} class defines the following methods:

@geindex do_HEAD() (méthode http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler do_HEAD}@anchor{3ac9}
@deffn {Méthode} do_HEAD ()

This method serves the @code{'HEAD'} request type: it sends the headers it
would send for the equivalent @code{GET} request. See the @ref{3ac8,,do_GET()}
method for a more complete explanation of the possible headers.
@end deffn

@geindex do_GET() (méthode http.server.SimpleHTTPRequestHandler)
@anchor{library/http server http server SimpleHTTPRequestHandler do_GET}@anchor{3ac8}
@deffn {Méthode} do_GET ()

The request is mapped to a local file by interpreting the request as a
path relative to the current working directory.

If the request was mapped to a directory, the directory is checked for a
file named @code{index.html} or @code{index.htm} (in that order). If found, the
file's contents are returned; otherwise a directory listing is generated
by calling the @code{list_directory()} method. This method uses
@ref{10da,,os.listdir()} to scan the directory, and returns a @code{404} error
response if the @ref{10da,,listdir()} fails.

If the request was mapped to a file, it is opened. Any @ref{40d,,OSError}
exception in opening the requested file is mapped to a @code{404},
@code{'File not found'} error. If there was an @code{'If-Modified-Since'}
header in the request, and the file was not modified after this time,
a @code{304}, @code{'Not Modified'} response is sent. Otherwise, the content
type is guessed by calling the @code{guess_type()} method, which in turn
uses the `extensions_map' variable, and the file contents are returned.

A @code{'Content-type:'} header with the guessed content type is output,
followed by a @code{'Content-Length:'} header with the file's size and a
@code{'Last-Modified:'} header with the file's modification time.

Then follows a blank line signifying the end of the headers, and then the
contents of the file are output. If the file's MIME type starts with
@code{text/} the file is opened in text mode; otherwise binary mode is used.

For example usage, see the implementation of the @code{test} function
in Lib/http/server.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/http/server.py}.


Modifié dans la version 3.7: Support of the @code{'If-Modified-Since'} header.

@end deffn
@end deffn

The @ref{b31,,SimpleHTTPRequestHandler} class can be used in the following
manner in order to create a very basic webserver serving files relative to
the current directory:

@example
import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("serving at port", PORT)
    httpd.serve_forever()
@end example

@ref{b31,,SimpleHTTPRequestHandler} can also be subclassed to enhance behavior,
such as using different index file names by overriding the class attribute
@code{index_pages}.
@anchor{library/http server http-server-cli}@anchor{f3c}
@ref{71,,http.server} can also be invoked directly using the @ref{5cb,,-m}
switch of the interpreter.  Similar to
the previous example, this serves files relative to the current directory:

@example
python -m http.server
@end example

The server listens to port 8000 by default. The default can be overridden
by passing the desired port number as an argument:

@example
python -m http.server 9000
@end example

By default, the server binds itself to all interfaces.  The option @code{-b/--bind}
specifies a specific address to which it should bind. Both IPv4 and IPv6
addresses are supported. For example, the following command causes the server
to bind to localhost only:

@example
python -m http.server --bind 127.0.0.1
@end example


Modifié dans la version 3.4: Added the @code{--bind} option.



Modifié dans la version 3.8: Support IPv6 in the @code{--bind} option.


By default, the server uses the current directory. The option @code{-d/--directory}
specifies a directory to which it should serve the files. For example,
the following command uses a specific directory:

@example
python -m http.server --directory /tmp/
@end example


Modifié dans la version 3.7: Added the @code{--directory} option.


By default, the server is conformant to HTTP/1.0. The option @code{-p/--protocol}
specifies the HTTP version to which the server is conformant. For example, the
following command runs an HTTP/1.1 conformant server:

@example
python -m http.server --protocol HTTP/1.1
@end example


Modifié dans la version 3.11: Added the @code{--protocol} option.


@geindex CGIHTTPRequestHandler (classe dans http.server)
@anchor{library/http server http server CGIHTTPRequestHandler}@anchor{29e}
@deffn {Classe} http.server.CGIHTTPRequestHandler (request, client_address, server)

This class is used to serve either files or output of CGI scripts from the
current directory and below. Note that mapping HTTP hierarchic structure to
local directory structure is exactly as in @ref{b31,,SimpleHTTPRequestHandler}.

@cartouche
@quotation Note 
CGI scripts run by the @ref{29e,,CGIHTTPRequestHandler} class cannot execute
redirects (HTTP code 302), because code 200 (script output follows) is
sent prior to execution of the CGI script.  This pre-empts the status
code.
@end quotation
@end cartouche

The class will however, run the CGI script, instead of serving it as a file,
if it guesses it to be a CGI script.  Only directory-based CGI are used ---
the other common server configuration is to treat special extensions as
denoting CGI scripts.

The @code{do_GET()} and @code{do_HEAD()} functions are modified to run CGI scripts
and serve the output, instead of serving files, if the request leads to
somewhere below the @code{cgi_directories} path.

The @ref{29e,,CGIHTTPRequestHandler} defines the following data member:

@geindex cgi_directories (attribut http.server.CGIHTTPRequestHandler)
@anchor{library/http server http server CGIHTTPRequestHandler cgi_directories}@anchor{3acc}
@deffn {Attribut} cgi_directories

This defaults to @code{['/cgi-bin', '/htbin']} and describes directories to
treat as containing CGI scripts.
@end deffn

The @ref{29e,,CGIHTTPRequestHandler} defines the following method:

@geindex do_POST() (méthode http.server.CGIHTTPRequestHandler)
@anchor{library/http server http server CGIHTTPRequestHandler do_POST}@anchor{3acd}
@deffn {Méthode} do_POST ()

This method serves the @code{'POST'} request type, only allowed for CGI
scripts.  Error 501, "Can only POST to CGI scripts", is output when trying
to POST to a non-CGI url.
@end deffn

Note that CGI scripts will be run with UID of user nobody, for security
reasons.  Problems with the CGI script will be translated to error 403.


Deprecated since version 3.13, will be removed in version 3.15: @ref{29e,,CGIHTTPRequestHandler} is being removed in 3.15.  CGI has not
been considered a good way to do things for well over a decade. This code
has been unmaintained for a while now and sees very little practical use.
Retaining it could lead to further @ref{3aab,,security considerations}.

@end deffn

@ref{29e,,CGIHTTPRequestHandler} can be enabled in the command line by passing
the @code{--cgi} option:

@example
python -m http.server --cgi
@end example


Deprecated since version 3.13, will be removed in version 3.15: @ref{71,,http.server} command line @code{--cgi} support is being removed
because @ref{29e,,CGIHTTPRequestHandler} is being removed.


@cartouche
@quotation Avertissement 
@ref{29e,,CGIHTTPRequestHandler} and the @code{--cgi} command line option
are not intended for use by untrusted clients and may be vulnerable
to exploitation. Always use within a secure environment.
@end quotation
@end cartouche

@menu
* Considérations de sécurité: Considérations de sécurité<3>. 

@end menu

@node Considérations de sécurité<3>,,,http server --- HTTP servers
@anchor{library/http server http-server-security}@anchor{3aab}@anchor{library/http server security-considerations}@anchor{3ace}
@subsubsection Considérations de sécurité


@geindex http.server;security

@ref{b31,,SimpleHTTPRequestHandler} will follow symbolic links when handling
requests, this makes it possible for files outside of the specified directory
to be served.

Earlier versions of Python did not scrub control characters from the
log messages emitted to stderr from @code{python -m http.server} or the
default @ref{10ad,,BaseHTTPRequestHandler} @code{.log_message}
implementation. This could allow remote clients connecting to your
server to send nefarious control codes to your terminal.


Modifié dans la version 3.12: Control characters are scrubbed in stderr logs.


@node http cookies --- HTTP state management,http cookiejar --- Cookie handling for HTTP clients,http server --- HTTP servers,Gestion des protocoles internet
@anchor{library/http cookies doc}@anchor{3acf}@anchor{library/http cookies http-cookies-http-state-management}@anchor{3ad0}@anchor{library/http cookies module-http cookies}@anchor{70}
@subsection @code{http.cookies} --- HTTP state management


@geindex module; http.cookies

`Code source :' Lib/http/cookies.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/http/cookies.py}


__________________________________________________________________


Le module @ref{70,,http.cookies} définit des classes abstrayant le concept de témoin web (cookie), un mécanisme de gestion d'état pour HTTP. Il fournit une abstraction gérant des données textuelles et tout type de données sérialisable comme valeur de témoin.

The module formerly strictly applied the parsing rules described in the
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} and 
@geindex RFC; RFC 2068
RFC 2068@footnote{https://datatracker.ietf.org/doc/html/rfc2068.html} specifications.  It has since been discovered that
MSIE 3.0x didn't follow the character rules outlined in those specs; many
current-day browsers and servers have also relaxed parsing rules when it comes
to cookie handling.  As a result, this module now uses parsing rules that are a
bit less strict than they once were.

The character set, @ref{12a1,,string.ascii_letters}, @ref{2248,,string.digits} and
@code{!#$%&'*+-.^_`|~:} denote the set of valid characters allowed by this module
in a cookie name (as @ref{bef,,key}).


Modifié dans la version 3.3: Allowed ':' as a valid cookie name character.


@cartouche
@quotation Note 
Quand un témoin invalide est rencontré, l'exception @ref{3ad1,,CookieError} est levée. Si les données du témoin proviennent d'un navigateur il faut impérativement gérer les données invalides en attrapant @ref{3ad1,,CookieError}.
@end quotation
@end cartouche

@geindex CookieError
@anchor{library/http cookies http cookies CookieError}@anchor{3ad1}
@deffn {Exception} http.cookies.CookieError

Exception levée pour cause d'incompatibilité avec la 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html}. Exemples : attributs incorrects, en-tête @code{Set-Cookie} incorrect, etc.
@end deffn

@geindex BaseCookie (classe dans http.cookies)
@anchor{library/http cookies http cookies BaseCookie}@anchor{3ad2}
@deffn {Classe} http.cookies.BaseCookie ([input])

Cette classe définit un dictionnaire dont les clés sont des chaines de caractères et dont les valeurs sont des instances de @ref{bf2,,Morsel}. Notez qu'à l'assignation d'une valeur à une clé, la valeur est transformée en @ref{bf2,,Morsel} contenant la clé et la valeur.

Si l'argument `input' est donné, il est passé à la méthode @ref{3ad3,,load()}.
@end deffn

@geindex SimpleCookie (classe dans http.cookies)
@anchor{library/http cookies http cookies SimpleCookie}@anchor{19d1}
@deffn {Classe} http.cookies.SimpleCookie ([input])

This class derives from @ref{3ad2,,BaseCookie} and overrides @ref{3ad4,,value_decode()}
and @ref{3ad5,,value_encode()}. @code{SimpleCookie} supports
strings as cookie values. When setting the value, @code{SimpleCookie}
calls the builtin @ref{435,,str()} to convert
the value to a string. Values received from HTTP are kept as strings.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{6f,,http.cookiejar}

Gestion de témoins HTTP pour `clients' web.  Les modules @ref{6f,,http.cookiejar} et @ref{70,,http.cookies} ne dépendent pas l'un de l'autre.

@geindex RFC; RFC 2109

@item RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} - HTTP State Management Mechanism

Spécification de gestion d'états implantée par ce module.
@end table


@menu
* Objets Cookie:: 
* Objets Morsel:: 
* Exemple: Exemple<12>. 

@end menu

@node Objets Cookie,Objets Morsel,,http cookies --- HTTP state management
@anchor{library/http cookies cookie-objects}@anchor{3ad6}@anchor{library/http cookies id1}@anchor{3ad7}
@subsubsection Objets `Cookie'


@geindex value_decode() (méthode http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie value_decode}@anchor{3ad4}
@deffn {Méthode} BaseCookie.value_decode (val)

Renvoie une paire @code{(real_value, coded_value)} depuis une représentation de chaine. @code{real_value} peut être de n’importe quel type. Cette méthode ne décode rien dans @ref{3ad2,,BaseCookie} – elle existe pour être surchargée.
@end deffn

@geindex value_encode() (méthode http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie value_encode}@anchor{3ad5}
@deffn {Méthode} BaseCookie.value_encode (val)

Renvoie une paire @code{(real_value, coded_value)}. `val' peut être de n’importe quel type, mais @code{coded_value} est toujours converti en chaine de caractères. Cette méthode n’encode pas dans @ref{3ad2,,BaseCookie} – elle existe pour être surchargée.

Généralement, les méthodes @ref{3ad5,,value_encode()} et @ref{3ad4,,value_decode()} doivent être inverses l'une de l'autre, c'est-à-dire qu'en envoyant la sortie de l'un dans l'entrée de l'autre la valeur finale doit être égale à la valeur initiale.
@end deffn

@geindex output() (méthode http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie output}@anchor{3ad8}
@deffn {Méthode} BaseCookie.output (attrs=None, header='Set-Cookie:', sep='\r\n')

Return a string representation suitable to be sent as HTTP headers. `attrs' and
`header' are sent to each @ref{bf2,,Morsel}'s @ref{3ad9,,output()} method. `sep' is used
to join the headers together, and is by default the combination @code{'\r\n'}
(CRLF).
@end deffn

@geindex js_output() (méthode http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie js_output}@anchor{3ada}
@deffn {Méthode} BaseCookie.js_output (attrs=None)

Renvoie un extrait de code JavaScript qui, lorsque exécuté par un navigateur qui supporte le JavaScript, va fonctionner de la même manière que si les en-têtes HTTP avaient été envoyés.

`attrs' a la même signification que dans la méthode @ref{3ad8,,output()}.
@end deffn

@geindex load() (méthode http.cookies.BaseCookie)
@anchor{library/http cookies http cookies BaseCookie load}@anchor{3ad3}
@deffn {Méthode} BaseCookie.load (rawdata)

Si `rawdata' est une chaine de caractères, l'analyser comme étant un @code{HTTP_COOKIE} et ajouter les valeurs trouvées en tant que @ref{bf2,,Morsel}s. S'il s'agit d'un dictionnaire, cela est équivalent à :

@example
for k, v in rawdata.items():
    cookie[k] = v
@end example
@end deffn

@node Objets Morsel,Exemple<12>,Objets Cookie,http cookies --- HTTP state management
@anchor{library/http cookies id2}@anchor{3adb}@anchor{library/http cookies morsel-objects}@anchor{3adc}
@subsubsection Objets `Morsel'


@geindex Morsel (classe dans http.cookies)
@anchor{library/http cookies http cookies Morsel}@anchor{bf2}
@deffn {Classe} http.cookies.Morsel

Abstraction de paire clé / valeur, accompagnée d'attributs provenant de la spécification 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html}.

Morsels are dictionary-like objects, whose set of keys is constant --- the valid
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} attributes, which are:

@quotation

@geindex expires (attribut http.cookies.Morsel)
@geindex path (attribut http.cookies.Morsel)
@geindex comment (attribut http.cookies.Morsel)
@geindex domain (attribut http.cookies.Morsel)
@geindex secure (attribut http.cookies.Morsel)
@geindex version (attribut http.cookies.Morsel)
@geindex httponly (attribut http.cookies.Morsel)
@geindex samesite (attribut http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel expires}@anchor{3add}
@deffn {Attribut} expires
@anchor{library/http cookies http cookies Morsel path}@anchor{3ade}
@deffnx {Attribut} path
@anchor{library/http cookies http cookies Morsel comment}@anchor{3adf}
@deffnx {Attribut} comment
@anchor{library/http cookies http cookies Morsel domain}@anchor{3ae0}
@deffnx {Attribut} domain

@deffnx {Attribut} max@w{-}age
@anchor{library/http cookies http cookies Morsel secure}@anchor{3ae1}
@deffnx {Attribut} secure
@anchor{library/http cookies http cookies Morsel version}@anchor{3ae2}
@deffnx {Attribut} version
@anchor{library/http cookies http cookies Morsel httponly}@anchor{1387}
@deffnx {Attribut} httponly
@anchor{library/http cookies http cookies Morsel samesite}@anchor{3ae3}
@deffnx {Attribut} samesite
@end deffn
@end quotation

L'attribut @ref{1387,,httponly} spécifie que le témoin transféré dans les requêtes HTTP n'est pas accessible par le biais de JavaScript. Il s'agit d'une contre-mesure à certaines attaques de scripts inter-sites (`XSS').

L'attribut @ref{3ae3,,samesite} spécifie que le navigateur n'est pas autorisé à envoyer le témoin de connexion avec les requêtes inter-sites. Cela vise à contrer les attaques `CSRF'. Les valeurs valides pour cet attribut sont « Strict » et « Lax ».

Les clés ne sont pas sensibles à la casse, leur valeur par défaut est @code{'@w{'}}.


Modifié dans la version 3.5: @code{__eq__()} now takes @ref{bef,,key} and @ref{bf0,,value}
into account.



Modifié dans la version 3.7: les attributs @ref{bef,,key}, @ref{bf0,,value} et @ref{bf1,,coded_value} sont en lecture seule. Utilisez @ref{bf3,,set()} pour les assigner.



Modifié dans la version 3.8: ajout de la prise en charge de l'attribut @ref{3ae3,,samesite}.

@end deffn

@geindex value (attribut http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel value}@anchor{bf0}
@deffn {Attribut} Morsel.value

La valeur du témoin.
@end deffn

@geindex coded_value (attribut http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel coded_value}@anchor{bf1}
@deffn {Attribut} Morsel.coded_value

La valeur codée du témoin. C'est celle qui doit être transférée.
@end deffn

@geindex key (attribut http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel key}@anchor{bef}
@deffn {Attribut} Morsel.key

Le nom du témoin.
@end deffn

@geindex set() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel set}@anchor{bf3}
@deffn {Méthode} Morsel.set (key, value, coded_value)

Assigne les attributs `key', `value' et `coded_value'.
@end deffn

@geindex isReservedKey() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel isReservedKey}@anchor{3ae4}
@deffn {Méthode} Morsel.isReservedKey (K)

Renvoie si `K' est membre des clés d'un @ref{bf2,,Morsel}.
@end deffn

@geindex output() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel output}@anchor{3ad9}
@deffn {Méthode} Morsel.output (attrs=None, header='Set-Cookie:')

Renvoie une représentation textuelle du `Morsel' compatible avec les en-têtes HTTP. Par défaut, tous les attributs sont inclus, à moins que `attrs' ne soit renseigné. Dans ce cas la valeur doit être une liste d'attributs à utiliser. Par défaut, `header' a la valeur @code{"Set-Cookie:"}.
@end deffn

@geindex js_output() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel js_output}@anchor{3ae5}
@deffn {Méthode} Morsel.js_output (attrs=None)

Renvoie un extrait de code JavaScript qui, lorsque exécuté par un navigateur qui supporte le JavaScript, va fonctionner de la même manière que si les en-têtes HTTP avaient été envoyés.

`attrs' a la même signification que dans la méthode @ref{3ad9,,output()}.
@end deffn

@geindex OutputString() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel OutputString}@anchor{3ae6}
@deffn {Méthode} Morsel.OutputString (attrs=None)

Renvoie une chaine de caractères représentant le `Morsel', nettoyé de son contexte HTTP ou JavaScript.

`attrs' a la même signification que dans la méthode @ref{3ad9,,output()}.
@end deffn

@geindex update() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel update}@anchor{eb2}
@deffn {Méthode} Morsel.update (values)

Met à jour les valeurs du dictionnaire du `Morsel' avec les valeurs provenant du dictionnaire `values'.  Lève une erreur si une des clés n'est pas un attribut 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} valide.


Modifié dans la version 3.5: une erreur est levée pour les clés invalides.

@end deffn

@geindex copy() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel copy}@anchor{eb1}
@deffn {Méthode} Morsel.copy (value)

Renvoie une copie superficielle de l'objet `Morsel'.


Modifié dans la version 3.5: renvoie un objet `Morsel' au lieu d'un @code{dict}.

@end deffn

@geindex setdefault() (méthode http.cookies.Morsel)
@anchor{library/http cookies http cookies Morsel setdefault}@anchor{3ae7}
@deffn {Méthode} Morsel.setdefault (key, value=None)

Lève une erreur si la clé n'est pas un attribut 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} valide, sinon fonctionne de la même manière que @ref{1062,,dict.setdefault()}.
@end deffn

@node Exemple<12>,,Objets Morsel,http cookies --- HTTP state management
@anchor{library/http cookies cookie-example}@anchor{3ae8}@anchor{library/http cookies example}@anchor{3ae9}
@subsubsection Exemple


L'exemple suivant montre comment utiliser le module @ref{70,,http.cookies}.

@example
>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = cookies.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print(C.output(header="Cookie:"))
Cookie: rocky=road; Path=/cookie
>>> print(C.output(attrs=[], header="Cookie:"))
Cookie: rocky=road
>>> C = cookies.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print(C)
Set-Cookie: number=7
Set-Cookie: string=seven
@end example

@node http cookiejar --- Cookie handling for HTTP clients,xmlrpc --- XMLRPC server and client modules,http cookies --- HTTP state management,Gestion des protocoles internet
@anchor{library/http cookiejar doc}@anchor{3aea}@anchor{library/http cookiejar http-cookiejar-cookie-handling-for-http-clients}@anchor{3aeb}@anchor{library/http cookiejar module-http cookiejar}@anchor{6f}
@subsection @code{http.cookiejar} --- Cookie handling for HTTP clients


@geindex module; http.cookiejar

`Source code:' Lib/http/cookiejar.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/http/cookiejar.py}


__________________________________________________________________


The @ref{6f,,http.cookiejar} module defines classes for automatic handling of HTTP
cookies.  It is useful for accessing web sites that require small pieces of data
-- `cookies' -- to be set on the client machine by an HTTP response from a
web server, and then returned to the server in later HTTP requests.

Both the regular Netscape cookie protocol and the protocol defined by
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} are handled.  RFC 2965 handling is switched off by default.
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies are parsed as Netscape cookies and subsequently treated
either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
Note that the great majority of cookies on the internet are Netscape cookies.
@ref{6f,,http.cookiejar} attempts to follow the de-facto Netscape cookie protocol (which
differs substantially from that set out in the original Netscape specification),
including taking note of the @code{max-age} and @code{port} cookie-attributes
introduced with RFC 2965.

@cartouche
@quotation Note 
The various named parameters found in @code{Set-Cookie} and
@code{Set-Cookie2} headers (eg. @code{domain} and @code{expires}) are
conventionally referred to as `attributes'.  To distinguish them from
Python attributes, the documentation for this module uses the term
`cookie-attribute' instead.
@end quotation
@end cartouche

The module defines the following exception:

@geindex LoadError
@anchor{library/http cookiejar http cookiejar LoadError}@anchor{3aec}
@deffn {Exception} http.cookiejar.LoadError

Instances of @ref{3aed,,FileCookieJar} raise this exception on failure to load
cookies from a file.  @ref{3aec,,LoadError} is a subclass of @ref{40d,,OSError}.


Modifié dans la version 3.3: @ref{3aec,,LoadError} used to be a subtype of @ref{103b,,IOError}, which is now an
alias of @ref{40d,,OSError}.

@end deffn

The following classes are provided:

@geindex CookieJar (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar CookieJar}@anchor{391f}
@deffn {Classe} http.cookiejar.CookieJar (policy=None)

`policy' is an object implementing the @ref{3aee,,CookiePolicy} interface.

The @ref{391f,,CookieJar} class stores HTTP cookies.  It extracts cookies from HTTP
requests, and returns them in HTTP responses. @ref{391f,,CookieJar} instances
automatically expire contained cookies when necessary.  Subclasses are also
responsible for storing and retrieving cookies from a file or database.
@end deffn

@geindex FileCookieJar (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar FileCookieJar}@anchor{3aed}
@deffn {Classe} http.cookiejar.FileCookieJar (filename=None, delayload=None, policy=None)

`policy' is an object implementing the @ref{3aee,,CookiePolicy} interface.  For the
other arguments, see the documentation for the corresponding attributes.

A @ref{391f,,CookieJar} which can load cookies from, and perhaps save cookies to, a
file on disk.  Cookies are `NOT' loaded from the named file until either the
@ref{3aef,,load()} or @ref{3af0,,revert()} method is called.  Subclasses of this class are
documented in section @ref{3af1,,FileCookieJar subclasses and co-operation with web browsers}.

This should not be initialized directly – use its subclasses below instead.


Modifié dans la version 3.8: The filename parameter supports a @ref{29d,,path-like object}.

@end deffn

@geindex CookiePolicy (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar CookiePolicy}@anchor{3aee}
@deffn {Classe} http.cookiejar.CookiePolicy

This class is responsible for deciding whether each cookie should be accepted
from / returned to the server.
@end deffn

@geindex DefaultCookiePolicy (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy}@anchor{199f}
@deffn {Classe} http.cookiejar.DefaultCookiePolicy (blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=('https', 'wss'))

Constructor arguments should be passed as keyword arguments only.
`blocked_domains' is a sequence of domain names that we never accept cookies
from, nor return cookies to. `allowed_domains' if not @ref{660,,None}, this is a
sequence of the only domains for which we accept and return cookies.
`secure_protocols' is a sequence of protocols for which secure cookies can be
added to. By default `https' and `wss' (secure websocket) are considered
secure protocols. For all other arguments, see the documentation for
@ref{3aee,,CookiePolicy} and @ref{199f,,DefaultCookiePolicy} objects.

@ref{199f,,DefaultCookiePolicy} implements the standard accept / reject rules for
Netscape and 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies.  By default, 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies (ie. cookies
received in a @code{Set-Cookie} header with a version cookie-attribute of
1) are treated according to the RFC 2965 rules.  However, if RFC 2965 handling
is turned off or @ref{3af2,,rfc2109_as_netscape} is @code{True}, RFC 2109 cookies are
'downgraded' by the @ref{391f,,CookieJar} instance to Netscape cookies, by
setting the @code{version} attribute of the @ref{3af3,,Cookie} instance to 0.
@ref{199f,,DefaultCookiePolicy} also provides some parameters to allow some
fine-tuning of policy.
@end deffn

@geindex Cookie (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar Cookie}@anchor{3af3}
@deffn {Classe} http.cookiejar.Cookie

This class represents Netscape, 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} and 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies.  It is not
expected that users of @ref{6f,,http.cookiejar} construct their own @ref{3af3,,Cookie}
instances.  Instead, if necessary, call @code{make_cookies()} on a
@ref{391f,,CookieJar} instance.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{10a,,urllib.request}

URL opening with automatic cookie handling.

@item Module @ref{70,,http.cookies}

HTTP cookie classes, principally useful for server-side code.  The
@ref{6f,,http.cookiejar} and @ref{70,,http.cookies} modules do not depend on each
other.

@item @indicateurl{https://curl.se/rfc/cookie_spec.html}

The specification of the original Netscape cookie protocol.  Though this is
still the dominant protocol, the 'Netscape cookie protocol' implemented by all
the major browsers (and @ref{6f,,http.cookiejar}) only bears a passing resemblance to
the one sketched out in @code{cookie_spec.html}.

@geindex RFC; RFC 2109

@item RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} - HTTP State Management Mechanism

Obsoleted by 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html}. Uses @code{Set-Cookie} with version=1.

@geindex RFC; RFC 2965

@item RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} - HTTP State Management Mechanism

The Netscape protocol with the bugs fixed.  Uses @code{Set-Cookie2} in
place of @code{Set-Cookie}.  Not widely used.

@item @indicateurl{https://kristol.org/cookie/errata.html}

Unfinished errata to 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html}.
@end table

@geindex RFC; RFC 2964
RFC 2964@footnote{https://datatracker.ietf.org/doc/html/rfc2964.html} - Use of HTTP State Management


@menu
* CookieJar and FileCookieJar Objects:: 
* FileCookieJar subclasses and co-operation with web browsers:: 
* CookiePolicy Objects:: 
* DefaultCookiePolicy Objects:: 
* Objets Cookie: Objets Cookie<2>. 
* Exemples: Exemples<28>. 

@end menu

@node CookieJar and FileCookieJar Objects,FileCookieJar subclasses and co-operation with web browsers,,http cookiejar --- Cookie handling for HTTP clients
@anchor{library/http cookiejar cookie-jar-objects}@anchor{3af4}@anchor{library/http cookiejar cookiejar-and-filecookiejar-objects}@anchor{3af5}
@subsubsection CookieJar and FileCookieJar Objects


@ref{391f,,CookieJar} objects support the @ref{1aa,,iterator} protocol for iterating over
contained @ref{3af3,,Cookie} objects.

@ref{391f,,CookieJar} has the following methods:

@geindex add_cookie_header() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar add_cookie_header}@anchor{3af6}
@deffn {Méthode} CookieJar.add_cookie_header (request)

Add correct @code{Cookie} header to `request'.

If policy allows (ie. the @code{rfc2965} and @code{hide_cookie2} attributes of
the @ref{391f,,CookieJar}'s @ref{3aee,,CookiePolicy} instance are true and false
respectively), the @code{Cookie2} header is also added when appropriate.

The `request' object (usually a @ref{fc3,,urllib.request.Request} instance)
must support the methods @code{get_full_url()}, @code{has_header()},
@code{get_header()}, @code{header_items()}, @code{add_unredirected_header()}
and the attributes @code{host}, @code{type}, @code{unverifiable}
and @code{origin_req_host} as documented by @ref{10a,,urllib.request}.


Modifié dans la version 3.3: `request' object needs @code{origin_req_host} attribute. Dependency on a
deprecated method @code{get_origin_req_host()} has been removed.

@end deffn

@geindex extract_cookies() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar extract_cookies}@anchor{3af7}
@deffn {Méthode} CookieJar.extract_cookies (response, request)

Extract cookies from HTTP `response' and store them in the @ref{391f,,CookieJar},
where allowed by policy.

The @ref{391f,,CookieJar} will look for allowable @code{Set-Cookie} and
@code{Set-Cookie2} headers in the `response' argument, and store cookies
as appropriate (subject to the @ref{3af8,,CookiePolicy.set_ok()} method's approval).

The `response' object (usually the result of a call to
@ref{290,,urllib.request.urlopen()}, or similar) should support an @code{info()}
method, which returns an @ref{279,,email.message.Message} instance.

The `request' object (usually a @ref{fc3,,urllib.request.Request} instance)
must support the method @code{get_full_url()} and the attributes
@code{host}, @code{unverifiable} and @code{origin_req_host},
as documented by @ref{10a,,urllib.request}.  The request is used to set
default values for cookie-attributes as well as for checking that the
cookie is allowed to be set.


Modifié dans la version 3.3: `request' object needs @code{origin_req_host} attribute. Dependency on a
deprecated method @code{get_origin_req_host()} has been removed.

@end deffn

@geindex set_policy() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar set_policy}@anchor{3af9}
@deffn {Méthode} CookieJar.set_policy (policy)

Set the @ref{3aee,,CookiePolicy} instance to be used.
@end deffn

@geindex make_cookies() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar make_cookies}@anchor{3afa}
@deffn {Méthode} CookieJar.make_cookies (response, request)

Return sequence of @ref{3af3,,Cookie} objects extracted from `response' object.

See the documentation for @ref{3af7,,extract_cookies()} for the interfaces required of
the `response' and `request' arguments.
@end deffn

@geindex set_cookie_if_ok() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar set_cookie_if_ok}@anchor{3afb}
@deffn {Méthode} CookieJar.set_cookie_if_ok (cookie, request)

Set a @ref{3af3,,Cookie} if policy says it's OK to do so.
@end deffn

@geindex set_cookie() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar set_cookie}@anchor{3afc}
@deffn {Méthode} CookieJar.set_cookie (cookie)

Set a @ref{3af3,,Cookie}, without checking with policy to see whether or not it
should be set.
@end deffn

@geindex clear() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar clear}@anchor{3afd}
@deffn {Méthode} CookieJar.clear ([domain[, path[, name]]])

Clear some cookies.

If invoked without arguments, clear all cookies.  If given a single argument,
only cookies belonging to that `domain' will be removed. If given two arguments,
cookies belonging to the specified `domain' and URL `path' are removed.  If
given three arguments, then the cookie with the specified `domain', `path' and
`name' is removed.

Raises @ref{33a,,KeyError} if no matching cookie exists.
@end deffn

@geindex clear_session_cookies() (méthode http.cookiejar.CookieJar)
@anchor{library/http cookiejar http cookiejar CookieJar clear_session_cookies}@anchor{3afe}
@deffn {Méthode} CookieJar.clear_session_cookies ()

Discard all session cookies.

Discards all contained cookies that have a true @code{discard} attribute
(usually because they had either no @code{max-age} or @code{expires} cookie-attribute,
or an explicit @code{discard} cookie-attribute).  For interactive browsers, the end
of a session usually corresponds to closing the browser window.

Note that the @code{save()} method won't save session cookies anyway, unless you
ask otherwise by passing a true `ignore_discard' argument.
@end deffn

@ref{3aed,,FileCookieJar} implements the following additional methods:

@geindex save() (méthode http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar save}@anchor{3aff}
@deffn {Méthode} FileCookieJar.save (filename=None, ignore_discard=False, ignore_expires=False)

Save cookies to a file.

This base class raises @ref{225,,NotImplementedError}.  Subclasses may leave this
method unimplemented.

`filename' is the name of file in which to save cookies.  If `filename' is not
specified, @code{self.filename} is used (whose default is the value passed to
the constructor, if any); if @code{self.filename} is @ref{660,,None},
@ref{1ff,,ValueError} is raised.

`ignore_discard': save even cookies set to be discarded. `ignore_expires': save
even cookies that have expired

The file is overwritten if it already exists, thus wiping all the cookies it
contains.  Saved cookies can be restored later using the @ref{3aef,,load()} or
@ref{3af0,,revert()} methods.
@end deffn

@geindex load() (méthode http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar load}@anchor{3aef}
@deffn {Méthode} FileCookieJar.load (filename=None, ignore_discard=False, ignore_expires=False)

Load cookies from a file.

Old cookies are kept unless overwritten by newly loaded ones.

Arguments are as for @ref{3aff,,save()}.

The named file must be in the format understood by the class, or
@ref{3aec,,LoadError} will be raised.  Also, @ref{40d,,OSError} may be raised, for
example if the file does not exist.


Modifié dans la version 3.3: @ref{103b,,IOError} était normalement levée, elle est maintenant un alias de @ref{40d,,OSError}.

@end deffn

@geindex revert() (méthode http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar revert}@anchor{3af0}
@deffn {Méthode} FileCookieJar.revert (filename=None, ignore_discard=False, ignore_expires=False)

Clear all cookies and reload cookies from a saved file.

@ref{3af0,,revert()} can raise the same exceptions as @ref{3aef,,load()}. If there is a
failure, the object's state will not be altered.
@end deffn

@ref{3aed,,FileCookieJar} instances have the following public attributes:

@geindex filename (attribut http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar filename}@anchor{3b00}
@deffn {Attribut} FileCookieJar.filename

Filename of default file in which to keep cookies.  This attribute may be
assigned to.
@end deffn

@geindex delayload (attribut http.cookiejar.FileCookieJar)
@anchor{library/http cookiejar http cookiejar FileCookieJar delayload}@anchor{3b01}
@deffn {Attribut} FileCookieJar.delayload

If true, load cookies lazily from disk.  This attribute should not be assigned
to.  This is only a hint, since this only affects performance, not behaviour
(unless the cookies on disk are changing). A @ref{391f,,CookieJar} object may
ignore it.  None of the @ref{3aed,,FileCookieJar} classes included in the standard
library lazily loads cookies.
@end deffn

@node FileCookieJar subclasses and co-operation with web browsers,CookiePolicy Objects,CookieJar and FileCookieJar Objects,http cookiejar --- Cookie handling for HTTP clients
@anchor{library/http cookiejar file-cookie-jar-classes}@anchor{3af1}@anchor{library/http cookiejar filecookiejar-subclasses-and-co-operation-with-web-browsers}@anchor{3b02}
@subsubsection FileCookieJar subclasses and co-operation with web browsers


The following @ref{391f,,CookieJar} subclasses are provided for reading and
writing.

@geindex MozillaCookieJar (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar MozillaCookieJar}@anchor{3b03}
@deffn {Classe} http.cookiejar.MozillaCookieJar (filename=None, delayload=None, policy=None)

A @ref{3aed,,FileCookieJar} that can load from and save cookies to disk in the
Mozilla @code{cookies.txt} file format (which is also used by curl and the Lynx
and Netscape browsers).

@cartouche
@quotation Note 
This loses information about 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies, and also about newer or
non-standard cookie-attributes such as @code{port}.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Back up your cookies before saving if you have cookies whose loss / corruption
would be inconvenient (there are some subtleties which may lead to slight
changes in the file over a load / save round-trip).
@end quotation
@end cartouche

Also note that cookies saved while Mozilla is running will get clobbered by
Mozilla.
@end deffn

@geindex LWPCookieJar (classe dans http.cookiejar)
@anchor{library/http cookiejar http cookiejar LWPCookieJar}@anchor{3b04}
@deffn {Classe} http.cookiejar.LWPCookieJar (filename=None, delayload=None, policy=None)

A @ref{3aed,,FileCookieJar} that can load from and save cookies to disk in format
compatible with the libwww-perl library's @code{Set-Cookie3} file format.  This is
convenient if you want to store cookies in a human-readable file.


Modifié dans la version 3.8: The filename parameter supports a @ref{29d,,path-like object}.

@end deffn

@node CookiePolicy Objects,DefaultCookiePolicy Objects,FileCookieJar subclasses and co-operation with web browsers,http cookiejar --- Cookie handling for HTTP clients
@anchor{library/http cookiejar cookie-policy-objects}@anchor{3b05}@anchor{library/http cookiejar cookiepolicy-objects}@anchor{3b06}
@subsubsection CookiePolicy Objects


Objects implementing the @ref{3aee,,CookiePolicy} interface have the following
methods:

@geindex set_ok() (méthode http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy set_ok}@anchor{3af8}
@deffn {Méthode} CookiePolicy.set_ok (cookie, request)

Return boolean value indicating whether cookie should be accepted from server.

`cookie' is a @ref{3af3,,Cookie} instance.  `request' is an object
implementing the interface defined by the documentation for
@ref{3af7,,CookieJar.extract_cookies()}.
@end deffn

@geindex return_ok() (méthode http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy return_ok}@anchor{3b07}
@deffn {Méthode} CookiePolicy.return_ok (cookie, request)

Return boolean value indicating whether cookie should be returned to server.

`cookie' is a @ref{3af3,,Cookie} instance.  `request' is an object
implementing the interface defined by the documentation for
@ref{3af6,,CookieJar.add_cookie_header()}.
@end deffn

@geindex domain_return_ok() (méthode http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy domain_return_ok}@anchor{3b08}
@deffn {Méthode} CookiePolicy.domain_return_ok (domain, request)

Return @code{False} if cookies should not be returned, given cookie domain.

This method is an optimization.  It removes the need for checking every cookie
with a particular domain (which might involve reading many files).  Returning
true from @ref{3b08,,domain_return_ok()} and @ref{3b09,,path_return_ok()} leaves all the
work to @ref{3b07,,return_ok()}.

If @ref{3b08,,domain_return_ok()} returns true for the cookie domain,
@ref{3b09,,path_return_ok()} is called for the cookie path.  Otherwise,
@ref{3b09,,path_return_ok()} and @ref{3b07,,return_ok()} are never called for that cookie
domain.  If @ref{3b09,,path_return_ok()} returns true, @ref{3b07,,return_ok()} is called
with the @ref{3af3,,Cookie} object itself for a full check.  Otherwise,
@ref{3b07,,return_ok()} is never called for that cookie path.

Note that @ref{3b08,,domain_return_ok()} is called for every `cookie' domain, not just
for the `request' domain.  For example, the function might be called with both
@code{".example.com"} and @code{"www.example.com"} if the request domain is
@code{"www.example.com"}.  The same goes for @ref{3b09,,path_return_ok()}.

The `request' argument is as documented for @ref{3b07,,return_ok()}.
@end deffn

@geindex path_return_ok() (méthode http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy path_return_ok}@anchor{3b09}
@deffn {Méthode} CookiePolicy.path_return_ok (path, request)

Return @code{False} if cookies should not be returned, given cookie path.

See the documentation for @ref{3b08,,domain_return_ok()}.
@end deffn

In addition to implementing the methods above, implementations of the
@ref{3aee,,CookiePolicy} interface must also supply the following attributes,
indicating which protocols should be used, and how.  All of these attributes may
be assigned to.

@geindex netscape (attribut http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy netscape}@anchor{3b0a}
@deffn {Attribut} CookiePolicy.netscape

Implement Netscape protocol.
@end deffn

@geindex rfc2965 (attribut http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy rfc2965}@anchor{3b0b}
@deffn {Attribut} CookiePolicy.rfc2965

Implement 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} protocol.
@end deffn

@geindex hide_cookie2 (attribut http.cookiejar.CookiePolicy)
@anchor{library/http cookiejar http cookiejar CookiePolicy hide_cookie2}@anchor{3b0c}
@deffn {Attribut} CookiePolicy.hide_cookie2

Don't add @code{Cookie2} header to requests (the presence of this header
indicates to the server that we understand 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies).
@end deffn

The most useful way to define a @ref{3aee,,CookiePolicy} class is by subclassing
from @ref{199f,,DefaultCookiePolicy} and overriding some or all of the methods
above.  @ref{3aee,,CookiePolicy} itself may be used as a 'null policy' to allow
setting and receiving any and all cookies (this is unlikely to be useful).

@node DefaultCookiePolicy Objects,Objets Cookie<2>,CookiePolicy Objects,http cookiejar --- Cookie handling for HTTP clients
@anchor{library/http cookiejar default-cookie-policy-objects}@anchor{3b0d}@anchor{library/http cookiejar defaultcookiepolicy-objects}@anchor{3b0e}
@subsubsection DefaultCookiePolicy Objects


Implements the standard rules for accepting and returning cookies.

Both 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} and Netscape cookies are covered.  RFC 2965 handling is switched
off by default.

The easiest way to provide your own policy is to override this class and call
its methods in your overridden implementations before adding your own additional
checks:

@example
import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True
@end example

In addition to the features required to implement the @ref{3aee,,CookiePolicy}
interface, this class allows you to block and allow domains from setting and
receiving cookies.  There are also some strictness switches that allow you to
tighten up the rather loose Netscape protocol rules a little bit (at the cost of
blocking some benign cookies).

A domain blocklist and allowlist is provided (both off by default). Only domains
not in the blocklist and present in the allowlist (if the allowlist is active)
participate in cookie setting and returning.  Use the `blocked_domains'
constructor argument, and @code{blocked_domains()} and
@code{set_blocked_domains()} methods (and the corresponding argument and methods
for `allowed_domains').  If you set an allowlist, you can turn it off again by
setting it to @ref{660,,None}.

Domains in block or allow lists that do not start with a dot must equal the
cookie domain to be matched.  For example, @code{"example.com"} matches a blocklist
entry of @code{"example.com"}, but @code{"www.example.com"} does not.  Domains that do
start with a dot are matched by more specific domains too. For example, both
@code{"www.example.com"} and @code{"www.coyote.example.com"} match @code{".example.com"}
(but @code{"example.com"} itself does not).  IP addresses are an exception, and
must match exactly.  For example, if blocked_domains contains @code{"192.168.1.2"}
and @code{".168.1.2"}, 192.168.1.2 is blocked, but 193.168.1.2 is not.

@ref{199f,,DefaultCookiePolicy} implements the following additional methods:

@geindex blocked_domains() (méthode http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy blocked_domains}@anchor{3b0f}
@deffn {Méthode} DefaultCookiePolicy.blocked_domains ()

Return the sequence of blocked domains (as a tuple).
@end deffn

@geindex set_blocked_domains() (méthode http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy set_blocked_domains}@anchor{3b10}
@deffn {Méthode} DefaultCookiePolicy.set_blocked_domains (blocked_domains)

Set the sequence of blocked domains.
@end deffn

@geindex is_blocked() (méthode http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy is_blocked}@anchor{3b11}
@deffn {Méthode} DefaultCookiePolicy.is_blocked (domain)

Return @code{True} if `domain' is on the blocklist for setting or receiving
cookies.
@end deffn

@geindex allowed_domains() (méthode http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy allowed_domains}@anchor{3b12}
@deffn {Méthode} DefaultCookiePolicy.allowed_domains ()

Return @ref{660,,None}, or the sequence of allowed domains (as a tuple).
@end deffn

@geindex set_allowed_domains() (méthode http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy set_allowed_domains}@anchor{3b13}
@deffn {Méthode} DefaultCookiePolicy.set_allowed_domains (allowed_domains)

Set the sequence of allowed domains, or @ref{660,,None}.
@end deffn

@geindex is_not_allowed() (méthode http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy is_not_allowed}@anchor{3b14}
@deffn {Méthode} DefaultCookiePolicy.is_not_allowed (domain)

Return @code{True} if `domain' is not on the allowlist for setting or receiving
cookies.
@end deffn

@ref{199f,,DefaultCookiePolicy} instances have the following attributes, which are
all initialised from the constructor arguments of the same name, and which may
all be assigned to.

@geindex rfc2109_as_netscape (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy rfc2109_as_netscape}@anchor{3af2}
@deffn {Attribut} DefaultCookiePolicy.rfc2109_as_netscape

If true, request that the @ref{391f,,CookieJar} instance downgrade 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies
(ie. cookies received in a @code{Set-Cookie} header with a version
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
the @ref{3af3,,Cookie} instance to 0.  The default value is @ref{660,,None}, in which
case RFC 2109 cookies are downgraded if and only if 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} handling is turned
off.  Therefore, RFC 2109 cookies are downgraded by default.
@end deffn

General strictness switches:

@geindex strict_domain (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_domain}@anchor{3b15}
@deffn {Attribut} DefaultCookiePolicy.strict_domain

Don't allow sites to set two-component domains with country-code top-level
domains like @code{.co.uk}, @code{.gov.uk}, @code{.co.nz}.etc.  This is far from perfect
and isn't guaranteed to work!
@end deffn

@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} protocol strictness switches:

@geindex strict_rfc2965_unverifiable (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_rfc2965_unverifiable}@anchor{3b16}
@deffn {Attribut} DefaultCookiePolicy.strict_rfc2965_unverifiable

Follow 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} rules on unverifiable transactions (usually, an unverifiable
transaction is one resulting from a redirect or a request for an image hosted on
another site).  If this is false, cookies are `never' blocked on the basis of
verifiability
@end deffn

Netscape protocol strictness switches:

@geindex strict_ns_unverifiable (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_unverifiable}@anchor{3b17}
@deffn {Attribut} DefaultCookiePolicy.strict_ns_unverifiable

Apply 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} rules on unverifiable transactions even to Netscape cookies.
@end deffn

@geindex strict_ns_domain (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_domain}@anchor{3b18}
@deffn {Attribut} DefaultCookiePolicy.strict_ns_domain

Flags indicating how strict to be with domain-matching rules for Netscape
cookies.  See below for acceptable values.
@end deffn

@geindex strict_ns_set_initial_dollar (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_set_initial_dollar}@anchor{3b19}
@deffn {Attribut} DefaultCookiePolicy.strict_ns_set_initial_dollar

Ignore cookies in Set-Cookie: headers that have names starting with @code{'$'}.
@end deffn

@geindex strict_ns_set_path (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy strict_ns_set_path}@anchor{3b1a}
@deffn {Attribut} DefaultCookiePolicy.strict_ns_set_path

Don't allow setting cookies whose path doesn't path-match request URI.
@end deffn

@code{strict_ns_domain} is a collection of flags.  Its value is constructed by
or-ing together (for example, @code{DomainStrictNoDots|DomainStrictNonDomain} means
both flags are set).

@geindex DomainStrictNoDots (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrictNoDots}@anchor{3b1b}
@deffn {Attribut} DefaultCookiePolicy.DomainStrictNoDots

When setting cookies, the 'host prefix' must not contain a dot (eg.
@code{www.foo.bar.com} can't set a cookie for @code{.bar.com}, because @code{www.foo}
contains a dot).
@end deffn

@geindex DomainStrictNonDomain (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrictNonDomain}@anchor{3b1c}
@deffn {Attribut} DefaultCookiePolicy.DomainStrictNonDomain

Cookies that did not explicitly specify a @code{domain} cookie-attribute can only
be returned to a domain equal to the domain that set the cookie (eg.
@code{spam.example.com} won't be returned cookies from @code{example.com} that had no
@code{domain} cookie-attribute).
@end deffn

@geindex DomainRFC2965Match (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainRFC2965Match}@anchor{3b1d}
@deffn {Attribut} DefaultCookiePolicy.DomainRFC2965Match

When setting cookies, require a full 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} domain-match.
@end deffn

The following attributes are provided for convenience, and are the most useful
combinations of the above flags:

@geindex DomainLiberal (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainLiberal}@anchor{3b1e}
@deffn {Attribut} DefaultCookiePolicy.DomainLiberal

Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
off).
@end deffn

@geindex DomainStrict (attribut http.cookiejar.DefaultCookiePolicy)
@anchor{library/http cookiejar http cookiejar DefaultCookiePolicy DomainStrict}@anchor{3b1f}
@deffn {Attribut} DefaultCookiePolicy.DomainStrict

Equivalent to @code{DomainStrictNoDots|DomainStrictNonDomain}.
@end deffn

@node Objets Cookie<2>,Exemples<28>,DefaultCookiePolicy Objects,http cookiejar --- Cookie handling for HTTP clients
@anchor{library/http cookiejar cookie-objects}@anchor{3b20}
@subsubsection Objets `Cookie'


@ref{3af3,,Cookie} instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards.  The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the @code{max-age} and @code{expires}
cookie-attributes contain equivalent information, and because 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies
may be 'downgraded' by @ref{6f,,http.cookiejar} from version 1 to version 0 (Netscape)
cookies.

Assignment to these attributes should not be necessary other than in rare
circumstances in a @ref{3aee,,CookiePolicy} method.  The class does not enforce
internal consistency, so you should know what you're doing if you do that.

@geindex version (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie version}@anchor{3b21}
@deffn {Attribut} Cookie.version

Integer or @ref{660,,None}.  Netscape cookies have @ref{3b21,,version} 0. 
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} and
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookies have a @code{version} cookie-attribute of 1.  However, note that
@ref{6f,,http.cookiejar} may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
case @ref{3b21,,version} is 0.
@end deffn

@geindex name (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie name}@anchor{3b22}
@deffn {Attribut} Cookie.name

Cookie name (a string).
@end deffn

@geindex value (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie value}@anchor{3b23}
@deffn {Attribut} Cookie.value

Cookie value (a string), or @ref{660,,None}.
@end deffn

@geindex port (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie port}@anchor{3b24}
@deffn {Attribut} Cookie.port

String representing a port or a set of ports (eg. '80', or '80,8080'), or
@ref{660,,None}.
@end deffn

@geindex domain (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie domain}@anchor{3b25}
@deffn {Attribut} Cookie.domain

Cookie domain (a string).
@end deffn

@geindex path (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie path}@anchor{3b26}
@deffn {Attribut} Cookie.path

Cookie path (a string, eg. @code{'/acme/rocket_launchers'}).
@end deffn

@geindex secure (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie secure}@anchor{3b27}
@deffn {Attribut} Cookie.secure

@code{True} if cookie should only be returned over a secure connection.
@end deffn

@geindex expires (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie expires}@anchor{3b28}
@deffn {Attribut} Cookie.expires

Integer expiry date in seconds since epoch, or @ref{660,,None}.  See also the
@ref{3b29,,is_expired()} method.
@end deffn

@geindex discard (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie discard}@anchor{3b2a}
@deffn {Attribut} Cookie.discard

@code{True} if this is a session cookie.
@end deffn

@geindex comment (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie comment}@anchor{3b2b}
@deffn {Attribut} Cookie.comment

String comment from the server explaining the function of this cookie, or
@ref{660,,None}.
@end deffn

@geindex comment_url (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie comment_url}@anchor{3b2c}
@deffn {Attribut} Cookie.comment_url

URL linking to a comment from the server explaining the function of this cookie,
or @ref{660,,None}.
@end deffn

@geindex rfc2109 (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie rfc2109}@anchor{3b2d}
@deffn {Attribut} Cookie.rfc2109

@code{True} if this cookie was received as an 
@geindex RFC; RFC 2109
RFC 2109@footnote{https://datatracker.ietf.org/doc/html/rfc2109.html} cookie (ie. the cookie
arrived in a @code{Set-Cookie} header, and the value of the Version
cookie-attribute in that header was 1).  This attribute is provided because
@ref{6f,,http.cookiejar} may 'downgrade' RFC 2109 cookies to Netscape cookies, in
which case @ref{3b21,,version} is 0.
@end deffn

@geindex port_specified (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie port_specified}@anchor{3b2e}
@deffn {Attribut} Cookie.port_specified

@code{True} if a port or set of ports was explicitly specified by the server (in the
@code{Set-Cookie} / @code{Set-Cookie2} header).
@end deffn

@geindex domain_specified (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie domain_specified}@anchor{3b2f}
@deffn {Attribut} Cookie.domain_specified

@code{True} if a domain was explicitly specified by the server.
@end deffn

@geindex domain_initial_dot (attribut http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie domain_initial_dot}@anchor{3b30}
@deffn {Attribut} Cookie.domain_initial_dot

@code{True} if the domain explicitly specified by the server began with a dot
(@code{'.'}).
@end deffn

Cookies may have additional non-standard cookie-attributes.  These may be
accessed using the following methods:

@geindex has_nonstandard_attr() (méthode http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie has_nonstandard_attr}@anchor{3b31}
@deffn {Méthode} Cookie.has_nonstandard_attr (name)

Return @code{True} if cookie has the named cookie-attribute.
@end deffn

@geindex get_nonstandard_attr() (méthode http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie get_nonstandard_attr}@anchor{3b32}
@deffn {Méthode} Cookie.get_nonstandard_attr (name, default=None)

If cookie has the named cookie-attribute, return its value. Otherwise, return
`default'.
@end deffn

@geindex set_nonstandard_attr() (méthode http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie set_nonstandard_attr}@anchor{3b33}
@deffn {Méthode} Cookie.set_nonstandard_attr (name, value)

Set the value of the named cookie-attribute.
@end deffn

The @ref{3af3,,Cookie} class also defines the following method:

@geindex is_expired() (méthode http.cookiejar.Cookie)
@anchor{library/http cookiejar http cookiejar Cookie is_expired}@anchor{3b29}
@deffn {Méthode} Cookie.is_expired (now=None)

@code{True} if cookie has passed the time at which the server requested it should
expire.  If `now' is given (in seconds since the epoch), return whether the
cookie has expired at the specified time.
@end deffn

@node Exemples<28>,,Objets Cookie<2>,http cookiejar --- Cookie handling for HTTP clients
@anchor{library/http cookiejar examples}@anchor{3b34}
@subsubsection Exemples


The first example shows the most common usage of @ref{6f,,http.cookiejar}:

@example
import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
@end example

This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
cookies (assumes Unix/Netscape convention for location of the cookies file):

@example
import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
@end example

The next example illustrates the use of @ref{199f,,DefaultCookiePolicy}. Turn on
@geindex RFC; RFC 2965
RFC 2965@footnote{https://datatracker.ietf.org/doc/html/rfc2965.html} cookies, be more strict about domains when setting and returning
Netscape cookies, and block some domains from setting cookies or having them
returned:

@example
import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
@end example

@node xmlrpc --- XMLRPC server and client modules,xmlrpc client --- XML-RPC client access,http cookiejar --- Cookie handling for HTTP clients,Gestion des protocoles internet
@anchor{library/xmlrpc doc}@anchor{3b35}@anchor{library/xmlrpc module-xmlrpc}@anchor{12c}@anchor{library/xmlrpc xmlrpc-xmlrpc-server-and-client-modules}@anchor{3b36}
@subsection @code{xmlrpc} --- XMLRPC server and client modules


@geindex module; xmlrpc

XML-RPC est une méthode pour appeler des procédures distantes utilisant XML via HTTP. XML-RPC permet à un client d'appeler des fonctions avec leurs arguments sur un serveur distant (désigné par une URI), et recevoir en retour des données structurées.

@code{xmlrpc} est un paquet rassemblant un client et un serveur XML-RPC. Ces modules sont :


@itemize *

@item 
@ref{12d,,xmlrpc.client}

@item 
@ref{12e,,xmlrpc.server}
@end itemize

@node xmlrpc client --- XML-RPC client access,xmlrpc server --- Basic XML-RPC servers,xmlrpc --- XMLRPC server and client modules,Gestion des protocoles internet
@anchor{library/xmlrpc client doc}@anchor{3b37}@anchor{library/xmlrpc client module-xmlrpc client}@anchor{12d}@anchor{library/xmlrpc client xmlrpc-client-xml-rpc-client-access}@anchor{3b38}
@subsection @code{xmlrpc.client} --- XML-RPC client access


@geindex module; xmlrpc.client

`Source code:' Lib/xmlrpc/client.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xmlrpc/client.py}

@c XXX Not everything is documented yet.  It might be good to describe
@c Marshaller, Unmarshaller, getparser and Transport.


__________________________________________________________________


XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a
transport.  With it, a client can call methods with parameters on a remote
server (the server is named by a URI) and get back structured data.  This module
supports writing XML-RPC client code; it handles all the details of translating
between conformable Python objects and XML on the wire.

@cartouche
@quotation Avertissement 
The @ref{12d,,xmlrpc.client} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data see
@ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche


Modifié dans la version 3.5: For HTTPS URIs, @ref{12d,,xmlrpc.client} now performs all the necessary
certificate and hostname checks by default.


@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@geindex ServerProxy (classe dans xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client ServerProxy}@anchor{a45}
@deffn {Classe} xmlrpc.client.ServerProxy (uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, headers=(), context=None)

A @ref{a45,,ServerProxy} instance is an object that manages communication with a
remote XML-RPC server.  The required first argument is a URI (Uniform Resource
Indicator), and will normally be the URL of the server.  The optional second
argument is a transport factory instance; by default it is an internal
@code{SafeTransport} instance for https: URLs and an internal HTTP
@code{Transport} instance otherwise.  The optional third argument is an
encoding, by default UTF-8. The optional fourth argument is a debugging flag.

The following parameters govern the use of the returned proxy instance.
If `allow_none' is true,  the Python constant @code{None} will be translated into
XML; the default behaviour is for @code{None} to raise a @ref{522,,TypeError}. This is
a commonly used extension to the XML-RPC specification, but isn't supported by
all clients and servers; see http://ontosys.com/xml-rpc/extensions.php@footnote{https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php}
for a description.
The `use_builtin_types' flag can be used to cause date/time values
to be presented as @ref{1c7,,datetime.datetime} objects and binary data to be
presented as @ref{1bd,,bytes} objects; this flag is false by default.
@ref{1c7,,datetime.datetime}, @ref{1bd,,bytes} and @ref{528,,bytearray} objects
may be passed to calls.
The `headers' parameter is an optional sequence of HTTP headers to send with
each request, expressed as a sequence of 2-tuples representing the header
name and value. (e.g. @code{[('Header-Name', 'value')]}).
The obsolete `use_datetime' flag is similar to `use_builtin_types' but it
applies only to date/time values.


Modifié dans la version 3.3: The `use_builtin_types' flag was added.



Modifié dans la version 3.8: The `headers' parameter was added.


Both the HTTP and HTTPS transports support the URL syntax extension for HTTP
Basic Authentication: @code{http://user:pass@@host:port/path}.  The  @code{user:pass}
portion will be base64-encoded as an HTTP 'Authorization' header, and sent to
the remote server as part of the connection process when invoking an XML-RPC
method.  You only need to use this if the remote server requires a Basic
Authentication user and password. If an HTTPS URL is provided, `context' may
be @ref{291,,ssl.SSLContext} and configures the SSL settings of the underlying
HTTPS connection.

The returned instance is a proxy object with methods that can be used to invoke
corresponding RPC calls on the remote server.  If the remote server supports the
introspection API, the proxy can also be used to query the remote server for the
methods it supports (service discovery) and fetch other server-associated
metadata.

Types that are conformable (e.g. that can be marshalled through XML),
include the following (and except where noted, they are unmarshalled
as the same Python type):


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

XML-RPC type

@tab

Type Python

@item

@code{boolean}

@tab

@ref{451,,bool}

@item

@code{int}, @code{i1},
@code{i2},  @code{i4},
@code{i8} or
@code{biginteger}

@tab

@ref{254,,int} in range from -2147483648 to 2147483647.
Values get the @code{<int>} tag.

@item

@code{double} or
@code{float}

@tab

@ref{2eb,,float}.  Values get the @code{<double>} tag.

@item

@code{string}

@tab

@ref{435,,str}

@item

@code{array}

@tab

@ref{5fc,,list} or @ref{366,,tuple} containing
conformable elements.  Arrays are returned as
@ref{5fc,,lists}.

@item

@code{struct}

@tab

@ref{253,,dict}.  Keys must be strings, values may be
any conformable type.  Objects of user-defined
classes can be passed in; only their
@ref{546,,__dict__} attribute is transmitted.

@item

@code{dateTime.iso8601}

@tab

@ref{139a,,DateTime} or @ref{1c7,,datetime.datetime}.
Returned type depends on values of
`use_builtin_types' and `use_datetime' flags.

@item

@code{base64}

@tab

@ref{3b39,,Binary}, @ref{1bd,,bytes} or
@ref{528,,bytearray}.  Returned type depends on the
value of the `use_builtin_types' flag.

@item

@code{nil}

@tab

The @code{None} constant.  Passing is allowed only if
`allow_none' is true.

@item

@code{bigdecimal}

@tab

@ref{29a,,decimal.Decimal}.  Returned type only.

@end multitable


This is the full set of data types supported by XML-RPC.  Method calls may also
raise a special @ref{3b3a,,Fault} instance, used to signal XML-RPC server errors, or
@ref{3b3b,,ProtocolError} used to signal an error in the HTTP/HTTPS transport layer.
Both @ref{3b3a,,Fault} and @ref{3b3b,,ProtocolError} derive from a base class called
@code{Error}.  Note that the xmlrpc client module currently does not marshal
instances of subclasses of built-in types.

When passing strings, characters special to XML such as @code{<}, @code{>}, and @code{&}
will be automatically escaped.  However, it's the caller's responsibility to
ensure that the string is free of characters that aren't allowed in XML, such as
the control characters with ASCII values between 0 and 31 (except, of course,
tab, newline and carriage return); failing to do this will result in an XML-RPC
request that isn't well-formed XML.  If you have to pass arbitrary bytes
via XML-RPC, use @ref{1bd,,bytes} or @ref{528,,bytearray} classes or the
@ref{3b39,,Binary} wrapper class described below.

@code{Server} is retained as an alias for @ref{a45,,ServerProxy} for backwards
compatibility.  New code should use @ref{a45,,ServerProxy}.


Modifié dans la version 3.5: Added the `context' argument.



Modifié dans la version 3.6: Added support of type tags with prefixes (e.g. @code{ex:nil}).
Added support of unmarshalling additional types used by Apache XML-RPC
implementation for numerics: @code{i1}, @code{i2}, @code{i8}, @code{biginteger},
@code{float} and @code{bigdecimal}.
See @indicateurl{https://ws.apache.org/xmlrpc/types.html} for a description.

@end deffn


@subsubheading Voir aussi



@table @asis

@item XML-RPC HOWTO@footnote{https://tldp.org/HOWTO/XML-RPC-HOWTO/index.html}

A good description of XML-RPC operation and client software in several languages.
Contains pretty much everything an XML-RPC client developer needs to know.

@item XML-RPC Introspection@footnote{https://xmlrpc-c.sourceforge.io/introspection.html}

Describes the XML-RPC protocol extension for introspection.

@item XML-RPC Specification@footnote{http://xmlrpc.scripting.com/spec.html}

The official specification.
@end table


@menu
* ServerProxy Objects:: 
* Objets DateTime:: 
* Binary Objects:: 
* Fault Objects:: 
* ProtocolError Objects:: 
* MultiCall Objects:: 
* Convenience Functions:: 
* Example of Client Usage:: 
* Example of Client and Server Usage:: 

@end menu

@node ServerProxy Objects,Objets DateTime,,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client id1}@anchor{3b3c}@anchor{library/xmlrpc client serverproxy-objects}@anchor{3b3d}
@subsubsection ServerProxy Objects


A @ref{a45,,ServerProxy} instance has a method corresponding to each remote
procedure call accepted by the XML-RPC server.  Calling the method performs an
RPC, dispatched by both name and argument signature (e.g. the same method name
can be overloaded with multiple argument signatures).  The RPC finishes by
returning a value, which may be either returned data in a conformant type or a
@ref{3b3a,,Fault} or @ref{3b3b,,ProtocolError} object indicating an error.

Servers that support the XML introspection API support some common methods
grouped under the reserved @code{system} attribute:

@geindex listMethods() (méthode xmlrpc.client.ServerProxy.system)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system listMethods}@anchor{3b3e}
@deffn {Méthode} ServerProxy.system.listMethods ()

This method returns a list of strings, one for each (non-system) method
supported by the XML-RPC server.
@end deffn

@geindex methodSignature() (méthode xmlrpc.client.ServerProxy.system)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system methodSignature}@anchor{3b3f}
@deffn {Méthode} ServerProxy.system.methodSignature (name)

This method takes one parameter, the name of a method implemented by the XML-RPC
server. It returns an array of possible signatures for this method. A signature
is an array of types. The first of these types is the return type of the method,
the rest are parameters.

Because multiple signatures (ie. overloading) is permitted, this method returns
a list of signatures rather than a singleton.

Signatures themselves are restricted to the top level parameters expected by a
method. For instance if a method expects one array of structs as a parameter,
and it returns a string, its signature is simply "string, array". If it expects
three integers and returns a string, its signature is "string, int, int, int".

If no signature is defined for the method, a non-array value is returned. In
Python this means that the type of the returned  value will be something other
than list.
@end deffn

@geindex methodHelp() (méthode xmlrpc.client.ServerProxy.system)
@anchor{library/xmlrpc client xmlrpc client ServerProxy system methodHelp}@anchor{3b40}
@deffn {Méthode} ServerProxy.system.methodHelp (name)

This method takes one parameter, the name of a method implemented by the XML-RPC
server.  It returns a documentation string describing the use of that method. If
no such string is available, an empty string is returned. The documentation
string may contain HTML markup.
@end deffn


Modifié dans la version 3.5: Instances of @ref{a45,,ServerProxy} support the @ref{5be,,context manager} protocol
for closing the underlying transport.


A working example follows. The server code:

@example
from xmlrpc.server import SimpleXMLRPCServer

def is_even(n):
    return n % 2 == 0

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(is_even, "is_even")
server.serve_forever()
@end example

The client code for the preceding server:

@example
import xmlrpc.client

with xmlrpc.client.ServerProxy("http://localhost:8000/") as proxy:
    print("3 is even: %s" % str(proxy.is_even(3)))
    print("100 is even: %s" % str(proxy.is_even(100)))
@end example

@node Objets DateTime,Binary Objects,ServerProxy Objects,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client datetime-objects}@anchor{3b41}@anchor{library/xmlrpc client id2}@anchor{3b42}
@subsubsection Objets DateTime


@geindex DateTime (classe dans xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client DateTime}@anchor{139a}
@deffn {Classe} xmlrpc.client.DateTime

This class may be initialized with seconds since the epoch, a time
tuple, an ISO 8601 time/date string, or a @ref{1c7,,datetime.datetime}
instance.  It has the following methods, supported mainly for internal
use by the marshalling/unmarshalling code:

@geindex decode() (méthode xmlrpc.client.DateTime)
@anchor{library/xmlrpc client xmlrpc client DateTime decode}@anchor{3b43}
@deffn {Méthode} decode (string)

Accept a string as the instance's new time value.
@end deffn

@geindex encode() (méthode xmlrpc.client.DateTime)
@anchor{library/xmlrpc client xmlrpc client DateTime encode}@anchor{3b44}
@deffn {Méthode} encode (out)

Write the XML-RPC encoding of this @ref{139a,,DateTime} item to the `out' stream
object.
@end deffn

It also supports certain of Python's built-in operators through
@ref{127d,,rich comparison} and @ref{607,,__repr__()}
methods.
@end deffn

A working example follows. The server code:

@example
import datetime
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def today():
    today = datetime.datetime.today()
    return xmlrpc.client.DateTime(today)

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(today, "today")
server.serve_forever()
@end example

The client code for the preceding server:

@example
import xmlrpc.client
import datetime

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")

today = proxy.today()
# convert the ISO8601 string to a datetime object
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print("Today: %s" % converted.strftime("%d.%m.%Y, %H:%M"))
@end example

@node Binary Objects,Fault Objects,Objets DateTime,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client binary-objects}@anchor{3b45}@anchor{library/xmlrpc client id3}@anchor{3b46}
@subsubsection Binary Objects


@geindex Binary (classe dans xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client Binary}@anchor{3b39}
@deffn {Classe} xmlrpc.client.Binary

This class may be initialized from bytes data (which may include NULs). The
primary access to the content of a @ref{3b39,,Binary} object is provided by an
attribute:

@geindex data (attribut xmlrpc.client.Binary)
@anchor{library/xmlrpc client xmlrpc client Binary data}@anchor{3b47}
@deffn {Attribut} data

The binary data encapsulated by the @ref{3b39,,Binary} instance.  The data is
provided as a @ref{1bd,,bytes} object.
@end deffn

@ref{3b39,,Binary} objects have the following methods, supported mainly for
internal use by the marshalling/unmarshalling code:

@geindex decode() (méthode xmlrpc.client.Binary)
@anchor{library/xmlrpc client xmlrpc client Binary decode}@anchor{3b48}
@deffn {Méthode} decode (bytes)

Accept a base64 @ref{1bd,,bytes} object and decode it as the instance's new data.
@end deffn

@geindex encode() (méthode xmlrpc.client.Binary)
@anchor{library/xmlrpc client xmlrpc client Binary encode}@anchor{3b49}
@deffn {Méthode} encode (out)

Write the XML-RPC base 64 encoding of this binary item to the `out' stream object.

The encoded data will have newlines every 76 characters as per
@geindex RFC; RFC 2045 Section 6.8
RFC 2045 section 6.8@footnote{https://datatracker.ietf.org/doc/html/rfc2045.html#section-6.8},
which was the de facto standard base64 specification when the
XML-RPC spec was written.
@end deffn

It also supports certain of Python's built-in operators through
@ref{ae8,,__eq__()} and @ref{14ce,,__ne__()} methods.
@end deffn

Example usage of the binary objects.  We're going to transfer an image over
XMLRPC:

@example
from xmlrpc.server import SimpleXMLRPCServer
import xmlrpc.client

def python_logo():
    with open("python_logo.jpg", "rb") as handle:
        return xmlrpc.client.Binary(handle.read())

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(python_logo, 'python_logo')

server.serve_forever()
@end example

The client gets the image and saves it to a file:

@example
import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
with open("fetched_python_logo.jpg", "wb") as handle:
    handle.write(proxy.python_logo().data)
@end example

@node Fault Objects,ProtocolError Objects,Binary Objects,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client fault-objects}@anchor{3b4a}@anchor{library/xmlrpc client id4}@anchor{3b4b}
@subsubsection Fault Objects


@geindex Fault (classe dans xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client Fault}@anchor{3b3a}
@deffn {Classe} xmlrpc.client.Fault

A @ref{3b3a,,Fault} object encapsulates the content of an XML-RPC fault tag. Fault
objects have the following attributes:

@geindex faultCode (attribut xmlrpc.client.Fault)
@anchor{library/xmlrpc client xmlrpc client Fault faultCode}@anchor{3b4c}
@deffn {Attribut} faultCode

An int indicating the fault type.
@end deffn

@geindex faultString (attribut xmlrpc.client.Fault)
@anchor{library/xmlrpc client xmlrpc client Fault faultString}@anchor{3b4d}
@deffn {Attribut} faultString

A string containing a diagnostic message associated with the fault.
@end deffn
@end deffn

In the following example we're going to intentionally cause a @ref{3b3a,,Fault} by
returning a complex type object.  The server code:

@example
from xmlrpc.server import SimpleXMLRPCServer

# A marshalling error is going to occur because we're returning a
# complex number
def add(x, y):
    return x+y+0j

server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_function(add, 'add')

server.serve_forever()
@end example

The client code for the preceding server:

@example
import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
try:
    proxy.add(2, 5)
except xmlrpc.client.Fault as err:
    print("A fault occurred")
    print("Fault code: %d" % err.faultCode)
    print("Fault string: %s" % err.faultString)
@end example

@node ProtocolError Objects,MultiCall Objects,Fault Objects,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client protocol-error-objects}@anchor{3b4e}@anchor{library/xmlrpc client protocolerror-objects}@anchor{3b4f}
@subsubsection ProtocolError Objects


@geindex ProtocolError (classe dans xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client ProtocolError}@anchor{3b3b}
@deffn {Classe} xmlrpc.client.ProtocolError

A @ref{3b3b,,ProtocolError} object describes a protocol error in the underlying
transport layer (such as a 404 'not found' error if the server named by the URI
does not exist).  It has the following attributes:

@geindex url (attribut xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError url}@anchor{3b50}
@deffn {Attribut} url

The URI or URL that triggered the error.
@end deffn

@geindex errcode (attribut xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError errcode}@anchor{3b51}
@deffn {Attribut} errcode

The error code.
@end deffn

@geindex errmsg (attribut xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError errmsg}@anchor{3b52}
@deffn {Attribut} errmsg

The error message or diagnostic string.
@end deffn

@geindex headers (attribut xmlrpc.client.ProtocolError)
@anchor{library/xmlrpc client xmlrpc client ProtocolError headers}@anchor{3b53}
@deffn {Attribut} headers

A dict containing the headers of the HTTP/HTTPS request that triggered the
error.
@end deffn
@end deffn

In the following example we're going to intentionally cause a @ref{3b3b,,ProtocolError}
by providing an invalid URI:

@example
import xmlrpc.client

# create a ServerProxy with a URI that doesn't respond to XMLRPC requests
proxy = xmlrpc.client.ServerProxy("http://google.com/")

try:
    proxy.some_method()
except xmlrpc.client.ProtocolError as err:
    print("A protocol error occurred")
    print("URL: %s" % err.url)
    print("HTTP/HTTPS headers: %s" % err.headers)
    print("Error code: %d" % err.errcode)
    print("Error message: %s" % err.errmsg)
@end example

@node MultiCall Objects,Convenience Functions,ProtocolError Objects,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client multicall-objects}@anchor{3b54}
@subsubsection MultiCall Objects


The @ref{3b55,,MultiCall} object provides a way to encapsulate multiple calls to a
remote server into a single request @footnote{
This approach has been first presented in @uref{https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic,a discussion on xmlrpc.com}.
}.

@geindex MultiCall (classe dans xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client MultiCall}@anchor{3b55}
@deffn {Classe} xmlrpc.client.MultiCall (server)

Create an object used to boxcar method calls. `server' is the eventual target of
the call. Calls can be made to the result object, but they will immediately
return @code{None}, and only store the call name and parameters in the
@ref{3b55,,MultiCall} object. Calling the object itself causes all stored calls to
be transmitted as a single @code{system.multicall} request. The result of this call
is a @ref{104a,,generator}; iterating over this generator yields the individual
results.
@end deffn

A usage example of this class follows.  The server code:

@example
from xmlrpc.server import SimpleXMLRPCServer

def add(x, y):
    return x + y

def subtract(x, y):
    return x - y

def multiply(x, y):
    return x * y

def divide(x, y):
    return x // y

# A simple server with simple arithmetic functions
server = SimpleXMLRPCServer(("localhost", 8000))
print("Listening on port 8000...")
server.register_multicall_functions()
server.register_function(add, 'add')
server.register_function(subtract, 'subtract')
server.register_function(multiply, 'multiply')
server.register_function(divide, 'divide')
server.serve_forever()
@end example

The client code for the preceding server:

@example
import xmlrpc.client

proxy = xmlrpc.client.ServerProxy("http://localhost:8000/")
multicall = xmlrpc.client.MultiCall(proxy)
multicall.add(7, 3)
multicall.subtract(7, 3)
multicall.multiply(7, 3)
multicall.divide(7, 3)
result = multicall()

print("7+3=%d, 7-3=%d, 7*3=%d, 7//3=%d" % tuple(result))
@end example

@node Convenience Functions,Example of Client Usage,MultiCall Objects,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client convenience-functions}@anchor{3b56}
@subsubsection Convenience Functions


@geindex dumps() (dans le module xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client dumps}@anchor{3b57}
@deffn {Fonction} xmlrpc.client.dumps (params, methodname=None, methodresponse=None, encoding=None, allow_none=False)

Convert `params' into an XML-RPC request. or into a response if `methodresponse'
is true. `params' can be either a tuple of arguments or an instance of the
@ref{3b3a,,Fault} exception class.  If `methodresponse' is true, only a single value
can be returned, meaning that `params' must be of length 1. `encoding', if
supplied, is the encoding to use in the generated XML; the default is UTF-8.
Python's @ref{660,,None} value cannot be used in standard XML-RPC; to allow using
it via an extension,  provide a true value for `allow_none'.
@end deffn

@geindex loads() (dans le module xmlrpc.client)
@anchor{library/xmlrpc client xmlrpc client loads}@anchor{13eb}
@deffn {Fonction} xmlrpc.client.loads (data, use_datetime=False, use_builtin_types=False)

Convert an XML-RPC request or response into Python objects, a @code{(params,
methodname)}.  `params' is a tuple of argument; `methodname' is a string, or
@code{None} if no method name is present in the packet. If the XML-RPC packet
represents a fault condition, this function will raise a @ref{3b3a,,Fault} exception.
The `use_builtin_types' flag can be used to cause date/time values to be
presented as @ref{1c7,,datetime.datetime} objects and binary data to be
presented as @ref{1bd,,bytes} objects; this flag is false by default.

The obsolete `use_datetime' flag is similar to `use_builtin_types' but it
applies only to date/time values.


Modifié dans la version 3.3: The `use_builtin_types' flag was added.

@end deffn

@node Example of Client Usage,Example of Client and Server Usage,Convenience Functions,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client example-of-client-usage}@anchor{3b58}@anchor{library/xmlrpc client xmlrpc-client-example}@anchor{3b59}
@subsubsection Example of Client Usage


@example
# simple test program (from the XML-RPC specification)
from xmlrpc.client import ServerProxy, Error

# server = ServerProxy("http://localhost:8000") # local server
with ServerProxy("http://betty.userland.com") as proxy:

    print(proxy)

    try:
        print(proxy.examples.getStateName(41))
    except Error as v:
        print("ERROR", v)
@end example

To access an XML-RPC server through a HTTP proxy, you need to define a custom
transport.  The following example shows how:

@example
import http.client
import xmlrpc.client

class ProxiedTransport(xmlrpc.client.Transport):

    def set_proxy(self, host, port=None, headers=None):
        self.proxy = host, port
        self.proxy_headers = headers

    def make_connection(self, host):
        connection = http.client.HTTPConnection(*self.proxy)
        connection.set_tunnel(host, headers=self.proxy_headers)
        self._connection = host, connection
        return connection

transport = ProxiedTransport()
transport.set_proxy('proxy-server', 8080)
server = xmlrpc.client.ServerProxy('http://betty.userland.com', transport=transport)
print(server.examples.getStateName(41))
@end example

@node Example of Client and Server Usage,,Example of Client Usage,xmlrpc client --- XML-RPC client access
@anchor{library/xmlrpc client example-of-client-and-server-usage}@anchor{3b5a}
@subsubsection Example of Client and Server Usage


See @ref{3b5b,,SimpleXMLRPCServer Example}.

@subsubheading Notes


@c the link now points to webarchive since the one at

@c http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin

@c doesn't reply)

@node xmlrpc server --- Basic XML-RPC servers,ipaddress --- IPv4/IPv6 manipulation library,xmlrpc client --- XML-RPC client access,Gestion des protocoles internet
@anchor{library/xmlrpc server doc}@anchor{3b5c}@anchor{library/xmlrpc server module-xmlrpc server}@anchor{12e}@anchor{library/xmlrpc server xmlrpc-server-basic-xml-rpc-servers}@anchor{3b5d}
@subsection @code{xmlrpc.server} --- Basic XML-RPC servers


@geindex module; xmlrpc.server

`Source code:' Lib/xmlrpc/server.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/xmlrpc/server.py}


__________________________________________________________________


The @ref{12e,,xmlrpc.server} module provides a basic server framework for XML-RPC
servers written in Python.  Servers can either be free standing, using
@ref{3b5e,,SimpleXMLRPCServer}, or embedded in a CGI environment, using
@ref{3b5f,,CGIXMLRPCRequestHandler}.

@cartouche
@quotation Avertissement 
The @ref{12e,,xmlrpc.server} module is not secure against maliciously
constructed data.  If you need to parse untrusted or unauthenticated data see
@ref{36b8,,Vulnérabilités XML}.
@end quotation
@end cartouche

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@geindex SimpleXMLRPCServer (classe dans xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer}@anchor{3b5e}
@deffn {Classe} xmlrpc.server.SimpleXMLRPCServer (addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)

Create a new server instance.  This class provides methods for registration of
functions that can be called by the XML-RPC protocol.  The `requestHandler'
parameter should be a factory for request handler instances; it defaults to
@ref{1305,,SimpleXMLRPCRequestHandler}.  The `addr' and `requestHandler' parameters
are passed to the @ref{12fd,,socketserver.TCPServer} constructor.  If `logRequests'
is true (the default), requests will be logged; setting this parameter to false
will turn off logging.   The `allow_none' and `encoding' parameters are passed
on to @ref{12d,,xmlrpc.client} and control the XML-RPC responses that will be returned
from the server. The `bind_and_activate' parameter controls whether
@code{server_bind()} and @code{server_activate()} are called immediately by the
constructor; it defaults to true. Setting it to false allows code to manipulate
the `allow_reuse_address' class variable before the address is bound.
The `use_builtin_types' parameter is passed to the
@ref{13eb,,loads()} function and controls which types are processed
when date/times values or binary data are received; it defaults to false.


Modifié dans la version 3.3: The `use_builtin_types' flag was added.

@end deffn

@geindex CGIXMLRPCRequestHandler (classe dans xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler}@anchor{3b5f}
@deffn {Classe} xmlrpc.server.CGIXMLRPCRequestHandler (allow_none=False, encoding=None, use_builtin_types=False)

Create a new instance to handle XML-RPC requests in a CGI environment.  The
`allow_none' and `encoding' parameters are passed on to @ref{12d,,xmlrpc.client}
and control the XML-RPC responses that will be returned from the server.
The `use_builtin_types' parameter is passed to the
@ref{13eb,,loads()} function and controls which types are processed
when date/times values or binary data are received; it defaults to false.


Modifié dans la version 3.3: The `use_builtin_types' flag was added.

@end deffn

@geindex SimpleXMLRPCRequestHandler (classe dans xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCRequestHandler}@anchor{1305}
@deffn {Classe} xmlrpc.server.SimpleXMLRPCRequestHandler

Create a new request handler instance.  This request handler supports @code{POST}
requests and modifies logging so that the `logRequests' parameter to the
@ref{3b5e,,SimpleXMLRPCServer} constructor parameter is honored.
@end deffn

@menu
* SimpleXMLRPCServer Objects:: 
* CGIXMLRPCRequestHandler:: 
* Documenting XMLRPC server:: 
* DocXMLRPCServer Objects:: 
* DocCGIXMLRPCRequestHandler:: 

@end menu

@node SimpleXMLRPCServer Objects,CGIXMLRPCRequestHandler,,xmlrpc server --- Basic XML-RPC servers
@anchor{library/xmlrpc server simple-xmlrpc-servers}@anchor{3b60}@anchor{library/xmlrpc server simplexmlrpcserver-objects}@anchor{3b61}
@subsubsection SimpleXMLRPCServer Objects


The @ref{3b5e,,SimpleXMLRPCServer} class is based on
@ref{12fd,,socketserver.TCPServer} and provides a means of creating simple, stand
alone XML-RPC servers.

@geindex register_function() (méthode xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_function}@anchor{3b62}
@deffn {Méthode} SimpleXMLRPCServer.register_function (function=None, name=None)

Register a function that can respond to XML-RPC requests.  If `name' is given,
it will be the method name associated with `function', otherwise
@ref{12b2,,function.__name__} will be used.  `name' is a string, and may contain
characters not legal in Python identifiers, including the period character.

This method can also be used as a decorator.  When used as a decorator,
`name' can only be given as a keyword argument to register `function' under
`name'.  If no `name' is given, @ref{12b2,,function.__name__} will be used.


Modifié dans la version 3.7: @ref{3b62,,register_function()} can be used as a decorator.

@end deffn

@geindex register_instance() (méthode xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_instance}@anchor{3b63}
@deffn {Méthode} SimpleXMLRPCServer.register_instance (instance, allow_dotted_names=False)

Register an object which is used to expose method names which have not been
registered using @ref{3b62,,register_function()}.  If `instance' contains a
@code{_dispatch()} method, it is called with the requested method name and the
parameters from the request.  Its API is @code{def _dispatch(self, method, params)}
(note that `params' does not represent a variable argument list).  If it calls
an underlying function to perform its task, that function is called as
@code{func(*params)}, expanding the parameter list. The return value from
@code{_dispatch()} is returned to the client as the result.  If `instance' does
not have a @code{_dispatch()} method, it is searched for an attribute matching
the name of the requested method.

If the optional `allow_dotted_names' argument is true and the instance does not
have a @code{_dispatch()} method, then if the requested method name contains
periods, each component of the method name is searched for individually, with
the effect that a simple hierarchical search is performed.  The value found from
this search is then called with the parameters from the request, and the return
value is passed back to the client.

@cartouche
@quotation Avertissement 
Enabling the `allow_dotted_names' option allows intruders to access your
module's global variables and may allow intruders to execute arbitrary code on
your machine.  Only use this option on a secure, closed network.
@end quotation
@end cartouche
@end deffn

@geindex register_introspection_functions() (méthode xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_introspection_functions}@anchor{3b64}
@deffn {Méthode} SimpleXMLRPCServer.register_introspection_functions ()

Registers the XML-RPC introspection functions @code{system.listMethods},
@code{system.methodHelp} and @code{system.methodSignature}.
@end deffn

@geindex register_multicall_functions() (méthode xmlrpc.server.SimpleXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCServer register_multicall_functions}@anchor{3b65}
@deffn {Méthode} SimpleXMLRPCServer.register_multicall_functions ()

Registers the XML-RPC multicall function system.multicall.
@end deffn

@geindex rpc_paths (attribut xmlrpc.server.SimpleXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server SimpleXMLRPCRequestHandler rpc_paths}@anchor{3b66}
@deffn {Attribut} SimpleXMLRPCRequestHandler.rpc_paths

An attribute value that must be a tuple listing valid path portions of the URL
for receiving XML-RPC requests.  Requests posted to other paths will result in a
404 "no such page" HTTP error.  If this tuple is empty, all paths will be
considered valid. The default value is @code{('/', '/RPC2')}.
@end deffn

@menu
* SimpleXMLRPCServer Example:: 

@end menu

@node SimpleXMLRPCServer Example,,,SimpleXMLRPCServer Objects
@anchor{library/xmlrpc server id1}@anchor{3b67}@anchor{library/xmlrpc server simplexmlrpcserver-example}@anchor{3b5b}
@subsubsection SimpleXMLRPCServer Example


Server code:

@example
from xmlrpc.server import SimpleXMLRPCServer
from xmlrpc.server import SimpleXMLRPCRequestHandler

# Restrict to a particular path.
class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

# Create server
with SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) as server:
    server.register_introspection_functions()

    # Register pow() function; this will use the value of
    # pow.__name__ as the name, which is just 'pow'.
    server.register_function(pow)

    # Register a function under a different name
    def adder_function(x, y):
        return x + y
    server.register_function(adder_function, 'add')

    # Register an instance; all the methods of the instance are
    # published as XML-RPC methods (in this case, just 'mul').
    class MyFuncs:
        def mul(self, x, y):
            return x * y

    server.register_instance(MyFuncs())

    # Run the server's main loop
    server.serve_forever()
@end example

The following client code will call the methods made available by the preceding
server:

@example
import xmlrpc.client

s = xmlrpc.client.ServerProxy('http://localhost:8000')
print(s.pow(2,3))  # Returns 2**3 = 8
print(s.add(2,3))  # Returns 5
print(s.mul(5,2))  # Returns 5*2 = 10

# Print list of available methods
print(s.system.listMethods())
@end example

@code{register_function()} can also be used as a decorator. The previous server
example can register functions in a decorator way:

@example
from xmlrpc.server import SimpleXMLRPCServer
from xmlrpc.server import SimpleXMLRPCRequestHandler

class RequestHandler(SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

with SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) as server:
    server.register_introspection_functions()

    # Register pow() function; this will use the value of
    # pow.__name__ as the name, which is just 'pow'.
    server.register_function(pow)

    # Register a function under a different name, using
    # register_function as a decorator. *name* can only be given
    # as a keyword argument.
    @@server.register_function(name='add')
    def adder_function(x, y):
        return x + y

    # Register a function under function.__name__.
    @@server.register_function
    def mul(x, y):
        return x * y

    server.serve_forever()
@end example

The following example included in the @code{Lib/xmlrpc/server.py} module shows
a server allowing dotted names and registering a multicall function.

@cartouche
@quotation Avertissement 
Enabling the `allow_dotted_names' option allows intruders to access your
module's global variables and may allow intruders to execute arbitrary code on
your machine.  Only use this example only within a secure, closed network.
@end quotation
@end cartouche

@example
import datetime

class ExampleService:
    def getData(self):
        return '42'

    class currentTime:
        @@staticmethod
        def getCurrentTime():
            return datetime.datetime.now()

with SimpleXMLRPCServer(("localhost", 8000)) as server:
    server.register_function(pow)
    server.register_function(lambda x,y: x+y, 'add')
    server.register_instance(ExampleService(), allow_dotted_names=True)
    server.register_multicall_functions()
    print('Serving XML-RPC on localhost port 8000')
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        print("\nKeyboard interrupt received, exiting.")
        sys.exit(0)
@end example

This ExampleService demo can be invoked from the command line:

@example
python -m xmlrpc.server
@end example

The client that interacts with the above server is included in
@code{Lib/xmlrpc/client.py}:

@example
server = ServerProxy("http://localhost:8000")

try:
    print(server.currentTime.getCurrentTime())
except Error as v:
    print("ERROR", v)

multi = MultiCall(server)
multi.getData()
multi.pow(2,9)
multi.add(1,2)
try:
    for response in multi():
        print(response)
except Error as v:
    print("ERROR", v)
@end example

This client which interacts with the demo XMLRPC server can be invoked as:

@example
python -m xmlrpc.client
@end example

@node CGIXMLRPCRequestHandler,Documenting XMLRPC server,SimpleXMLRPCServer Objects,xmlrpc server --- Basic XML-RPC servers
@anchor{library/xmlrpc server cgixmlrpcrequesthandler}@anchor{3b68}
@subsubsection CGIXMLRPCRequestHandler


The @ref{3b5f,,CGIXMLRPCRequestHandler} class can be used to handle XML-RPC
requests sent to Python CGI scripts.

@geindex register_function() (méthode xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_function}@anchor{3b69}
@deffn {Méthode} CGIXMLRPCRequestHandler.register_function (function=None, name=None)

Register a function that can respond to XML-RPC requests.  If `name' is given,
it will be the method name associated with `function', otherwise
@ref{12b2,,function.__name__} will be used.  `name' is a string, and may contain
characters not legal in Python identifiers, including the period character.

This method can also be used as a decorator.  When used as a decorator,
`name' can only be given as a keyword argument to register `function' under
`name'.  If no `name' is given, @ref{12b2,,function.__name__} will be used.


Modifié dans la version 3.7: @ref{3b69,,register_function()} can be used as a decorator.

@end deffn

@geindex register_instance() (méthode xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_instance}@anchor{3b6a}
@deffn {Méthode} CGIXMLRPCRequestHandler.register_instance (instance)

Register an object which is used to expose method names  which have not been
registered using @ref{3b69,,register_function()}. If  instance contains a
@code{_dispatch()} method, it is called with the  requested method name and the
parameters from the  request; the return value is returned to the client as the
result. If instance does not have a @code{_dispatch()} method, it is searched
for an attribute matching the name of the requested method; if  the requested
method name contains periods, each  component of the method name is searched for
individually,  with the effect that a simple hierarchical search is performed.
The value found from this search is then called with the  parameters from the
request, and the return value is passed  back to the client.
@end deffn

@geindex register_introspection_functions() (méthode xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_introspection_functions}@anchor{3b6b}
@deffn {Méthode} CGIXMLRPCRequestHandler.register_introspection_functions ()

Register the XML-RPC introspection functions  @code{system.listMethods},
@code{system.methodHelp} and  @code{system.methodSignature}.
@end deffn

@geindex register_multicall_functions() (méthode xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler register_multicall_functions}@anchor{3b6c}
@deffn {Méthode} CGIXMLRPCRequestHandler.register_multicall_functions ()

Register the XML-RPC multicall function @code{system.multicall}.
@end deffn

@geindex handle_request() (méthode xmlrpc.server.CGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server CGIXMLRPCRequestHandler handle_request}@anchor{3b6d}
@deffn {Méthode} CGIXMLRPCRequestHandler.handle_request (request_text=None)

Handle an XML-RPC request. If `request_text' is given, it should be the POST
data provided by the HTTP server,  otherwise the contents of stdin will be used.
@end deffn

Exemple :

@example
class MyFuncs:
    def mul(self, x, y):
        return x * y


handler = CGIXMLRPCRequestHandler()
handler.register_function(pow)
handler.register_function(lambda x,y: x+y, 'add')
handler.register_introspection_functions()
handler.register_instance(MyFuncs())
handler.handle_request()
@end example

@node Documenting XMLRPC server,DocXMLRPCServer Objects,CGIXMLRPCRequestHandler,xmlrpc server --- Basic XML-RPC servers
@anchor{library/xmlrpc server documenting-xmlrpc-server}@anchor{3b6e}
@subsubsection Documenting XMLRPC server


These classes extend the above classes to serve HTML documentation in response
to HTTP GET requests.  Servers can either be free standing, using
@ref{194c,,DocXMLRPCServer}, or embedded in a CGI environment, using
@ref{3b6f,,DocCGIXMLRPCRequestHandler}.

@geindex DocXMLRPCServer (classe dans xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer}@anchor{194c}
@deffn {Classe} xmlrpc.server.DocXMLRPCServer (addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)

Create a new server instance. All parameters have the same meaning as for
@ref{3b5e,,SimpleXMLRPCServer}; `requestHandler' defaults to
@ref{3b70,,DocXMLRPCRequestHandler}.


Modifié dans la version 3.3: The `use_builtin_types' flag was added.

@end deffn

@geindex DocCGIXMLRPCRequestHandler (classe dans xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler}@anchor{3b6f}
@deffn {Classe} xmlrpc.server.DocCGIXMLRPCRequestHandler

Create a new instance to handle XML-RPC requests in a CGI environment.
@end deffn

@geindex DocXMLRPCRequestHandler (classe dans xmlrpc.server)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCRequestHandler}@anchor{3b70}
@deffn {Classe} xmlrpc.server.DocXMLRPCRequestHandler

Create a new request handler instance. This request handler supports XML-RPC
POST requests, documentation GET requests, and modifies logging so that the
`logRequests' parameter to the @ref{194c,,DocXMLRPCServer} constructor parameter is
honored.
@end deffn

@node DocXMLRPCServer Objects,DocCGIXMLRPCRequestHandler,Documenting XMLRPC server,xmlrpc server --- Basic XML-RPC servers
@anchor{library/xmlrpc server doc-xmlrpc-servers}@anchor{3b71}@anchor{library/xmlrpc server docxmlrpcserver-objects}@anchor{3b72}
@subsubsection DocXMLRPCServer Objects


The @ref{194c,,DocXMLRPCServer} class is derived from @ref{3b5e,,SimpleXMLRPCServer}
and provides a means of creating self-documenting, stand alone XML-RPC
servers. HTTP POST requests are handled as XML-RPC method calls. HTTP GET
requests are handled by generating pydoc-style HTML documentation. This allows a
server to provide its own web-based documentation.

@geindex set_server_title() (méthode xmlrpc.server.DocXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer set_server_title}@anchor{3b73}
@deffn {Méthode} DocXMLRPCServer.set_server_title (server_title)

Set the title used in the generated HTML documentation. This title will be used
inside the HTML "title" element.
@end deffn

@geindex set_server_name() (méthode xmlrpc.server.DocXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer set_server_name}@anchor{3b74}
@deffn {Méthode} DocXMLRPCServer.set_server_name (server_name)

Set the name used in the generated HTML documentation. This name will appear at
the top of the generated documentation inside a "h1" element.
@end deffn

@geindex set_server_documentation() (méthode xmlrpc.server.DocXMLRPCServer)
@anchor{library/xmlrpc server xmlrpc server DocXMLRPCServer set_server_documentation}@anchor{3b75}
@deffn {Méthode} DocXMLRPCServer.set_server_documentation (server_documentation)

Set the description used in the generated HTML documentation. This description
will appear as a paragraph, below the server name, in the documentation.
@end deffn

@node DocCGIXMLRPCRequestHandler,,DocXMLRPCServer Objects,xmlrpc server --- Basic XML-RPC servers
@anchor{library/xmlrpc server doccgixmlrpcrequesthandler}@anchor{3b76}
@subsubsection DocCGIXMLRPCRequestHandler


The @ref{3b6f,,DocCGIXMLRPCRequestHandler} class is derived from
@ref{3b5f,,CGIXMLRPCRequestHandler} and provides a means of creating
self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled as XML-RPC
method calls. HTTP GET requests are handled by generating pydoc-style HTML
documentation. This allows a server to provide its own web-based documentation.

@geindex set_server_title() (méthode xmlrpc.server.DocCGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler set_server_title}@anchor{3b77}
@deffn {Méthode} DocCGIXMLRPCRequestHandler.set_server_title (server_title)

Set the title used in the generated HTML documentation. This title will be used
inside the HTML "title" element.
@end deffn

@geindex set_server_name() (méthode xmlrpc.server.DocCGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler set_server_name}@anchor{3b78}
@deffn {Méthode} DocCGIXMLRPCRequestHandler.set_server_name (server_name)

Set the name used in the generated HTML documentation. This name will appear at
the top of the generated documentation inside a "h1" element.
@end deffn

@geindex set_server_documentation() (méthode xmlrpc.server.DocCGIXMLRPCRequestHandler)
@anchor{library/xmlrpc server xmlrpc server DocCGIXMLRPCRequestHandler set_server_documentation}@anchor{3b79}
@deffn {Méthode} DocCGIXMLRPCRequestHandler.set_server_documentation (server_documentation)

Set the description used in the generated HTML documentation. This description
will appear as a paragraph, below the server name, in the documentation.
@end deffn

@node ipaddress --- IPv4/IPv6 manipulation library,,xmlrpc server --- Basic XML-RPC servers,Gestion des protocoles internet
@anchor{library/ipaddress doc}@anchor{3b7a}@anchor{library/ipaddress ipaddress-ipv4-ipv6-manipulation-library}@anchor{3b7b}@anchor{library/ipaddress module-ipaddress}@anchor{7f}
@subsection @code{ipaddress} --- IPv4/IPv6 manipulation library


@geindex module; ipaddress

`Code source :' Lib/ipaddress.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/ipaddress.py}


__________________________________________________________________


@ref{7f,,ipaddress} propose des fonctionnalités pour créer, manipuler et opérer sur des réseaux et adresses IPv4 et IPv6.

Les fonctions et les classes dans ce module facilitent la gestion de différentes tâches reliée aux adresses IP, incluant vérifier si deux hôtes sont sur le même sous-réseau, itérer sur tous les hôtes d'un sous-réseau particulier, vérifier si une chaîne représente bien une adresse IP ou une définition de réseau valide, et ainsi de suite.

Ceci est la référence complète de l'API du module, pour un aperçu et introduction, voir @ref{3b7c,,Introduction au module ipaddress}.


Ajouté dans la version 3.3.


@c import ipaddress
@c from ipaddress import (
@c     ip_network, IPv4Address, IPv4Interface, IPv4Network,
@c )

@menu
* Fonctions fabriques pratiques:: 
* Adresses IP:: 
* Définitions de réseaux IP:: 
* Objets interface:: 
* Autres fonctions au niveau de module:: 
* Exceptions personnalisées:: 

@end menu

@node Fonctions fabriques pratiques,Adresses IP,,ipaddress --- IPv4/IPv6 manipulation library
@anchor{library/ipaddress convenience-factory-functions}@anchor{3b7d}
@subsubsection Fonctions fabriques pratiques


Le module @ref{7f,,ipaddress} propose des fonctions fabriques pour facilement créer des adresses IP, réseaux et interfaces :

@geindex ip_address() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress ip_address}@anchor{3b7e}
@deffn {Fonction} ipaddress.ip_address (address)

Return an @ref{1f9,,IPv4Address} or @ref{1fa,,IPv6Address} object depending on
the IP address passed as argument.  Either IPv4 or IPv6 addresses may be
supplied; integers less than @code{2**32} will be considered to be IPv4 by default.
A @ref{1ff,,ValueError} is raised if `address' does not represent a valid IPv4
or IPv6 address.

@example
>>> ipaddress.ip_address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.ip_address('2001:db8::')
IPv6Address('2001:db8::')
@end example
@end deffn

@geindex ip_network() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress ip_network}@anchor{3b7f}
@deffn {Fonction} ipaddress.ip_network (address, strict=True)

Return an @ref{1fb,,IPv4Network} or @ref{1fc,,IPv6Network} object depending on
the IP address passed as argument.  `address' is a string or integer
representing the IP network.  Either IPv4 or IPv6 networks may be supplied;
integers less than @code{2**32} will be considered to be IPv4 by default.  `strict'
is passed to @ref{1fb,,IPv4Network} or @ref{1fc,,IPv6Network} constructor.  A
@ref{1ff,,ValueError} is raised if `address' does not represent a valid IPv4 or
IPv6 address, or if the network has host bits set.

@example
>>> ipaddress.ip_network('192.168.0.0/28')
IPv4Network('192.168.0.0/28')
@end example
@end deffn

@geindex ip_interface() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress ip_interface}@anchor{3b80}
@deffn {Fonction} ipaddress.ip_interface (address)

Return an @ref{179c,,IPv4Interface} or @ref{179d,,IPv6Interface} object depending
on the IP address passed as argument.  `address' is a string or integer
representing the IP address.  Either IPv4 or IPv6 addresses may be supplied;
integers less than @code{2**32} will be considered to be IPv4 by default.  A
@ref{1ff,,ValueError} is raised if `address' does not represent a valid IPv4 or
IPv6 address.
@end deffn

Un inconvénient de ces fonctions pratiques est que le besoin de gérer à la fois IPv4 et IPv6 signifie que les messages d'erreur contiennent peu d'information sur l'erreur précise puisqu'elles ne peuvent pas deviner quel format entre IPv4 et IPv6 est voulu. Un compte-rendu d'erreur plus détaillé peut être obtenu en appelant directement le constructeur de classe pour la version voulue.

@node Adresses IP,Définitions de réseaux IP,Fonctions fabriques pratiques,ipaddress --- IPv4/IPv6 manipulation library
@anchor{library/ipaddress ip-addresses}@anchor{3b81}
@subsubsection Adresses IP


@menu
* Objets adresse:: 
* Conversion vers les chaînes et les entiers:: 
* Opérateurs: Opérateurs<3>. 

@end menu

@node Objets adresse,Conversion vers les chaînes et les entiers,,Adresses IP
@anchor{library/ipaddress address-objects}@anchor{3b82}
@subsubsection Objets adresse


Les objets @ref{1f9,,IPv4Address} et @ref{1fa,,IPv6Address} ont beaucoup d'attributs en commun. Certains attributs qui n'ont du sens que pour des adresses IPv6 sont aussi implémentés par les objets @ref{1f9,,IPv4Address} pour faciliter l'écriture de code qui gère les 2 versions IP correctement. Les objets d'adresse sont @ref{5fb,,hachables} pour qu'ils puissent être utilisés comme des clés dans des dictionnaires.

@geindex IPv4Address (classe dans ipaddress)
@anchor{library/ipaddress ipaddress IPv4Address}@anchor{1f9}
@deffn {Classe} ipaddress.IPv4Address (address)

Construit une adresse IPv4. Une exception @ref{3b83,,AddressValueError} est levée si `address' n'est pas une adresse IPv4 valide.

Une adresse IPv4 valide est composée de :


@enumerate 

@item 
Une chaîne en notation décimale par points, composée de quatre entiers décimaux dans la plage inclusive 0—255, séparés par des points (p. ex. @code{192.168.0.1}). Chaque entier représente un octet dans l'adresse. Les zéros en tête ne sont pas tolérés pour éviter toute confusion avec la notation octale.

@item 
Un entier qui tient dans 32 bits.

@item 
Un entier tassé dans un objet @ref{1bd,,bytes} de taille 4 (gros-boutiste).
@end enumerate

@example
>>> ipaddress.IPv4Address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(3232235521)
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
IPv4Address('192.168.0.1')
@end example


Modifié dans la version 3.8: Les zéros en tête sont tolérés, même dans les cas ambigus qui ont l'apparence de notation octal.



Modifié dans la version 3.9.5: Les zéros en tête ne sont plus tolérés et seront traités comme une erreur. Les chaînes d'adresses IPv4 sont maintenant analysées aussi strictement que dans dans la fonction glibc @ref{94f,,inet_pton()}.


@geindex version (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address version}@anchor{3b84}
@deffn {Attribut} version

Numéro de version approprié : @code{4} pour IPv4, @code{6} pour IPv6.
@end deffn

@geindex max_prefixlen (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address max_prefixlen}@anchor{3b85}
@deffn {Attribut} max_prefixlen

Nombre total de bits dans la représentation d'adresse de cette version : @code{32} pour IPv4, @code{128} pour IPv6.

Le préfixe définit le nombre de bits en tête dans une adresse qui sont comparés pour déterminer si une adresse fait partie d'un réseau.
@end deffn

@geindex compressed (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address compressed}@anchor{3b86}
@deffn {Attribut} compressed
@end deffn

@geindex exploded (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address exploded}@anchor{3b87}
@deffn {Attribut} exploded

Une chaîne en notation décimale par points. Les zéros en tête ne sont jamais inclus dans la représentation.

Comme IPv4 ne définit pas une notation abrégée pour les adresses avec des octets définis à zéro, ces deux attributs sont toujours identiques à @code{str(addr)} pour les adresses IPv4. Exposer ces attributs rend plus simple l'écriture de code d'affichage qui peut gérer à la fois les adresses IPv4 et IPv6.
@end deffn

@geindex packed (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address packed}@anchor{3b88}
@deffn {Attribut} packed

La représentation binaire de cette adresse — un objet @ref{1bd,,bytes} avec une taille appropriée (gros-boutiste). La taille est de 4 octets pour IPv4 et 16 octets pour IPv6.
@end deffn

@geindex reverse_pointer (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address reverse_pointer}@anchor{3b89}
@deffn {Attribut} reverse_pointer

Nom de l'enregistrement DNS PTR inverse pour l'adresse IP, p. ex :

@example
>>> ipaddress.ip_address("127.0.0.1").reverse_pointer
'1.0.0.127.in-addr.arpa'
>>> ipaddress.ip_address("2001:db8::1").reverse_pointer
'1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa'
@end example

C'est le nom utilisé pour effectuer une recherche inverse PTR et non le nom de l'hôte résolu lui-même.


Ajouté dans la version 3.5.

@end deffn

@geindex is_multicast (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_multicast}@anchor{3b8a}
@deffn {Attribut} is_multicast

@code{True} si l'adresse est réservée pour utilisation `multicast'. Voir 
@geindex RFC; RFC 3171
RFC 3171@footnote{https://datatracker.ietf.org/doc/html/rfc3171.html} (pour IPv4) or 
@geindex RFC; RFC 2373
RFC 2373@footnote{https://datatracker.ietf.org/doc/html/rfc2373.html} (pour IPv6).
@end deffn

@geindex is_private (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_private}@anchor{15d2}
@deffn {Attribut} is_private

@code{True} if the address is defined as not globally reachable by
iana-ipv4-special-registry@footnote{https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml} (for IPv4) or iana-ipv6-special-registry@footnote{https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml}
(for IPv6) with the following exceptions:


@itemize *

@item 
@code{is_private} is @code{False} for the shared address space (@code{100.64.0.0/10})

@item 
For IPv4-mapped IPv6-addresses the @code{is_private} value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see @ref{3b8b,,IPv6Address.ipv4_mapped}):

@example
address.is_private == address.ipv4_mapped.is_private
@end example
@end itemize

@code{is_private} has value opposite to @ref{f4a,,is_global}, except for the shared address space
(@code{100.64.0.0/10} range) where they are both @code{False}.


Modifié dans la version 3.13: Fixed some false positives and false negatives.


@itemize *

@item 
@code{192.0.0.0/24} is considered private with the exception of @code{192.0.0.9/32} and
@code{192.0.0.10/32} (previously: only the @code{192.0.0.0/29} sub-range was considered private).

@item 
@code{64:ff9b:1::/48} is considered private.

@item 
@code{2002::/16} is considered private.

@item 
There are exceptions within @code{2001::/23} (otherwise considered private): @code{2001:1::1/128},
@code{2001:1::2/128}, @code{2001:3::/32}, @code{2001:4:112::/48}, @code{2001:20::/28}, @code{2001:30::/28}.
The exceptions are not considered private.
@end itemize

@end deffn

@geindex is_global (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_global}@anchor{f4a}
@deffn {Attribut} is_global

@code{True} if the address is defined as globally reachable by
iana-ipv4-special-registry@footnote{https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml} (for IPv4) or iana-ipv6-special-registry@footnote{https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml}
(for IPv6) with the following exception:

For IPv4-mapped IPv6-addresses the @code{is_private} value is determined by the
semantics of the underlying IPv4 addresses and the following condition holds
(see @ref{3b8b,,IPv6Address.ipv4_mapped}):

@example
address.is_global == address.ipv4_mapped.is_global
@end example

@code{is_global} has value opposite to @ref{15d2,,is_private}, except for the shared address space
(@code{100.64.0.0/10} range) where they are both @code{False}.


Ajouté dans la version 3.4.



Modifié dans la version 3.13: Fixed some false positives and false negatives, see @ref{15d2,,is_private} for details.

@end deffn

@geindex is_unspecified (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_unspecified}@anchor{3b8c}
@deffn {Attribut} is_unspecified

@code{True} si l'adresse est non-spécifiée. Voir 
@geindex RFC; RFC 5735
RFC 5735@footnote{https://datatracker.ietf.org/doc/html/rfc5735.html} (pour IPv4) or 
@geindex RFC; RFC 2373
RFC 2373@footnote{https://datatracker.ietf.org/doc/html/rfc2373.html} (pour IPv6).
@end deffn

@geindex is_reserved (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_reserved}@anchor{3b8d}
@deffn {Attribut} is_reserved

@code{True} si l'adresse est réservée par l'IETF.
@end deffn

@geindex is_loopback (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_loopback}@anchor{3b8e}
@deffn {Attribut} is_loopback

@code{True} si c'est une adresse de rebouclage (`loopback' en anglais). Voir 
@geindex RFC; RFC 3330
RFC 3330@footnote{https://datatracker.ietf.org/doc/html/rfc3330.html} (pour IPv4) or 
@geindex RFC; RFC 2373
RFC 2373@footnote{https://datatracker.ietf.org/doc/html/rfc2373.html} (pour IPv6).
@end deffn

@geindex is_link_local (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address is_link_local}@anchor{3b8f}
@deffn {Attribut} is_link_local

@code{True} si l'adresse est réservée pour les liaisons locales auto-configurées. Voir 
@geindex RFC; RFC 3927
RFC 3927@footnote{https://datatracker.ietf.org/doc/html/rfc3927.html}.
@end deffn

@geindex ipv6_mapped (attribut ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address ipv6_mapped}@anchor{1f8}
@deffn {Attribut} ipv6_mapped

@ref{1f9,,IPv4Address} object representing the IPv4-mapped IPv6 address. See 
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html}.


Ajouté dans la version 3.13.

@end deffn
@end deffn

@geindex __format__() (méthode ipaddress.IPv4Address)
@anchor{library/ipaddress ipaddress IPv4Address __format__}@anchor{3b90}
@deffn {Méthode} IPv4Address.__format__ (fmt)

Renvoie l'adresse IP sous forme d'une chaîne, contrôlée par une chaîne de formatage explicite. `fmt' peut être : @code{'s'}, l'option par défaut, équivalent à @ref{435,,str()}, @code{'b'} pour une chaîne binaire préfixée par des zéros, @code{'X'} ou @code{'x'} pour une représentation hexadécimale majuscule ou minuscule, ou @code{'n'}, équivalant à @code{'b'} pour les adresses IPv4 et @code{'x'} pour IPv6. Pour les représentations binaires et hexadécimales, le spécificateur de forme @code{'#'} et l'option de regroupement @code{'_'} sont disponibles. @code{__format__} est utilisé par @code{format}, @code{str.format} et les f-strings.

@example
>>> format(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> '@{:#b@}'.format(ipaddress.IPv4Address('192.168.0.1'))
'0b11000000101010000000000000000001'
>>> f'@{ipaddress.IPv6Address("2001:db8::1000"):s@}'
'2001:db8::1000'
>>> format(ipaddress.IPv6Address('2001:db8::1000'), '_X')
'2001_0DB8_0000_0000_0000_0000_0000_1000'
>>> '@{:#_n@}'.format(ipaddress.IPv6Address('2001:db8::1000'))
'0x2001_0db8_0000_0000_0000_0000_0000_1000'
@end example


Ajouté dans la version 3.9.

@end deffn

@geindex IPv6Address (classe dans ipaddress)
@anchor{library/ipaddress ipaddress IPv6Address}@anchor{1fa}
@deffn {Classe} ipaddress.IPv6Address (address)

Construit une adresse IPv6. Une @ref{3b83,,AddressValueError} est levée si `address' n'est pas une adresse IPv6 valide.

Une adresse IPv6 valide est constituée de :


@enumerate 

@item 
Une chaîne constituée de huit groupes de quatre chiffres hexadécimaux, chaque groupe représentant 16 bits. Les groupes sont séparés par des deux-points. Ceci décrit une notation `éclatée' (longue). La chaîne peut-être aussi `abrégée' (notation courte) par différents moyens. Voir 
@geindex RFC; RFC 4291
RFC 4291@footnote{https://datatracker.ietf.org/doc/html/rfc4291.html} pour plus de détails. Par exemple, @code{"0000:0000:0000:0000:0000:0abc:0007:0def"} peut s'écrire @code{"::abc:7:def"}.

Optionnellement, la chaîne peut avoir un indice de zone de portée, exprimé avec un suffixe @code{%scope_id}. Si présent, l'indice de portée ne doit pas être vide et ne doit pas contenir @code{%}. Voir 
@geindex RFC; RFC 4007
RFC 4007@footnote{https://datatracker.ietf.org/doc/html/rfc4007.html} pour plus de détails. Par exemple, @code{fe80::1234%1} pourrait identifier @code{fe80::1234} sur la première interface du nœud.

@item 
Un entier qui tient dans 128 bits.

@item 
Un entier tassé dans un objet @ref{1bd,,bytes} de taille 16, gros-boutiste.
@end enumerate

@example
>>> ipaddress.IPv6Address('2001:db8::1000')
IPv6Address('2001:db8::1000')
>>> ipaddress.IPv6Address('ff02::5678%1')
IPv6Address('ff02::5678%1')
@end example

@geindex compressed (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address compressed}@anchor{3b91}
@deffn {Attribut} compressed
@end deffn

Version courte de la représentation d'adresse, avec les groupes de zéros en tête omis et la séquence la plus longue de groupes constitués entièrement de zéros réduit à un seul groupe vide.

C'est aussi la valeur renvoyée par @code{str(addr)} pour les adresses IPv6.

@geindex exploded (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address exploded}@anchor{3b92}
@deffn {Attribut} exploded
@end deffn

Version longue de la représentation d'adresse, avec tous les zéros en tête et groupes composés entièrement de zéros inclus.

Pour les attributs et méthodes suivants, voir la documentation de la classe @ref{1f9,,IPv4Address} :

@geindex packed (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address packed}@anchor{3b93}
@deffn {Attribut} packed
@end deffn

@geindex reverse_pointer (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address reverse_pointer}@anchor{155d}
@deffn {Attribut} reverse_pointer
@end deffn

@geindex version (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address version}@anchor{3b94}
@deffn {Attribut} version
@end deffn

@geindex max_prefixlen (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address max_prefixlen}@anchor{3b95}
@deffn {Attribut} max_prefixlen
@end deffn

@geindex is_multicast (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_multicast}@anchor{3b96}
@deffn {Attribut} is_multicast
@end deffn

@geindex is_private (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_private}@anchor{15d3}
@deffn {Attribut} is_private
@end deffn

@geindex is_global (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_global}@anchor{15d4}
@deffn {Attribut} is_global


Ajouté dans la version 3.4.

@end deffn

@geindex is_unspecified (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_unspecified}@anchor{3b97}
@deffn {Attribut} is_unspecified
@end deffn

@geindex is_reserved (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_reserved}@anchor{3b98}
@deffn {Attribut} is_reserved
@end deffn

@geindex is_loopback (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_loopback}@anchor{15bd}
@deffn {Attribut} is_loopback
@end deffn

@geindex is_link_local (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_link_local}@anchor{3b99}
@deffn {Attribut} is_link_local
@end deffn

@geindex is_site_local (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address is_site_local}@anchor{3b9a}
@deffn {Attribut} is_site_local

@code{True} si l'adresse est réservée pour usage sur réseau local. Notez que l'espace d'adressage sur réseau local a été rendu obsolète par 
@geindex RFC; RFC 3879
RFC 3879@footnote{https://datatracker.ietf.org/doc/html/rfc3879.html}. Utilisez @ref{15d2,,is_private} pour tester si l'adresse est dans l'espace d'adresses locales et uniques défini par 
@geindex RFC; RFC 4193
RFC 4193@footnote{https://datatracker.ietf.org/doc/html/rfc4193.html}.
@end deffn

@geindex ipv4_mapped (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address ipv4_mapped}@anchor{3b8b}
@deffn {Attribut} ipv4_mapped

Pour les adresses qui semblent être des adresses mappées IPv4 (commençant par @code{::FFFF/96}), cette propriété rapporte l'adresse IPv4 imbriquée. Pour toute autre adresse, cette propriété sera @code{None}.
@end deffn

@geindex scope_id (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address scope_id}@anchor{8fb}
@deffn {Attribut} scope_id

Pour les adresses avec une portée spécifiée comme définies par 
@geindex RFC; RFC 4007
RFC 4007@footnote{https://datatracker.ietf.org/doc/html/rfc4007.html}, cette propriété identifie la zone précise de la portée d'adresse à laquelle cette adresse appartient, en tant que chaîne. Quand la zone de portée n'est pas spécifiée, cette propriété est @code{None}.
@end deffn

@geindex sixtofour (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address sixtofour}@anchor{3b9b}
@deffn {Attribut} sixtofour

Pour les adresses qui semblent être des adresses `6to4' (commençant par @code{2002::/16}) tel que défini par 
@geindex RFC; RFC 3056
RFC 3056@footnote{https://datatracker.ietf.org/doc/html/rfc3056.html}, cette propriété rapporte l'adresse IPv4 imbriquée. Pour toute autre adresse, cette propriété sera @code{None}.
@end deffn

@geindex teredo (attribut ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address teredo}@anchor{3b9c}
@deffn {Attribut} teredo

Pour les adresses qui semblent être des adresses `Teredo' (commençant par @code{2001::/32}) tel que défini par 
@geindex RFC; RFC 4380
RFC 4380@footnote{https://datatracker.ietf.org/doc/html/rfc4380.html}, cette propriété rapporte la paire @code{(server, client)} imbriquée. Pour toute autre adresse, cette propriété sera @code{None}.
@end deffn
@end deffn

@geindex __format__() (méthode ipaddress.IPv6Address)
@anchor{library/ipaddress ipaddress IPv6Address __format__}@anchor{3b9d}
@deffn {Méthode} IPv6Address.__format__ (fmt)

Référez-vous à la documentation de la méthode correspondante dans @ref{1f9,,IPv4Address}.


Ajouté dans la version 3.9.

@end deffn

@node Conversion vers les chaînes et les entiers,Opérateurs<3>,Objets adresse,Adresses IP
@anchor{library/ipaddress conversion-to-strings-and-integers}@anchor{3b9e}
@subsubsection Conversion vers les chaînes et les entiers


Afin d'interagir avec les API de réseau tels que le module socket, les adresses doivent être converties en chaînes et en entiers. Ceci est géré en utilisant les fonctions natives @ref{435,,str()} et @ref{254,,int()} :

@example
>>> str(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> int(ipaddress.IPv4Address('192.168.0.1'))
3232235521
>>> str(ipaddress.IPv6Address('::1'))
'::1'
>>> int(ipaddress.IPv6Address('::1'))
1
@end example

Note that IPv6 scoped addresses are converted to integers without scope zone ID.

@node Opérateurs<3>,,Conversion vers les chaînes et les entiers,Adresses IP
@anchor{library/ipaddress operators}@anchor{3b9f}
@subsubsection Opérateurs


Address objects support some operators.  Unless stated otherwise, operators can
only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
IPv6).

@menu
* Opérateurs de comparaison:: 
* Opérateurs arithmétiques:: 

@end menu

@node Opérateurs de comparaison,Opérateurs arithmétiques,,Opérateurs<3>
@anchor{library/ipaddress comparison-operators}@anchor{3ba0}
@subsubsection Opérateurs de comparaison


Address objects can be compared with the usual set of comparison operators.
Same IPv6 addresses with different scope zone IDs are not equal.
Some examples:

@example
>>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
True
>>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
False
>>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
True
>>> IPv6Address('fe80::1234') == IPv6Address('fe80::1234%1')
False
>>> IPv6Address('fe80::1234%1') != IPv6Address('fe80::1234%2')
True
@end example

@node Opérateurs arithmétiques,,Opérateurs de comparaison,Opérateurs<3>
@anchor{library/ipaddress arithmetic-operators}@anchor{3ba1}
@subsubsection Opérateurs arithmétiques


Les entiers peuvent être additionnés ou soustraits des objets d'adresse. Quelques exemples :

@example
>>> IPv4Address('127.0.0.2') + 3
IPv4Address('127.0.0.5')
>>> IPv4Address('127.0.0.2') - 3
IPv4Address('126.255.255.255')
>>> IPv4Address('255.255.255.255') + 1
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address
@end example

@node Définitions de réseaux IP,Objets interface,Adresses IP,ipaddress --- IPv4/IPv6 manipulation library
@anchor{library/ipaddress ip-network-definitions}@anchor{3ba2}
@subsubsection Définitions de réseaux IP


The @ref{1fb,,IPv4Network} and @ref{1fc,,IPv6Network} objects provide a mechanism
for defining and inspecting IP network definitions.  A network definition
consists of a `mask' and a `network address', and as such defines a range of
IP addresses that equal the network address when masked (binary AND) with the
mask.  For example, a network definition with the mask @code{255.255.255.0} and
the network address @code{192.168.1.0} consists of IP addresses in the inclusive
range @code{192.168.1.0} to @code{192.168.1.255}.

@menu
* Préfixe@comma{} masque réseau et masque de l'hôte: Préfixe masque réseau et masque de l'hôte. 
* Objets réseau:: 
* Opérateurs: Opérateurs<4>. 

@end menu

@node Préfixe masque réseau et masque de l'hôte,Objets réseau,,Définitions de réseaux IP
@anchor{library/ipaddress prefix-net-mask-and-host-mask}@anchor{3ba3}
@subsubsection Préfixe, masque réseau et masque de l'hôte


There are several equivalent ways to specify IP network masks.  A `prefix'
@code{/<nbits>} is a notation that denotes how many high-order bits are set in
the network mask.  A `net mask' is an IP address with some number of
high-order bits set.  Thus the prefix @code{/24} is equivalent to the net mask
@code{255.255.255.0} in IPv4, or @code{ffff:ff00::} in IPv6.  In addition, a
`host mask' is the logical inverse of a `net mask', and is sometimes used
(for example in Cisco access control lists) to denote a network mask.  The
host mask equivalent to @code{/24} in IPv4 is @code{0.0.0.255}.

@node Objets réseau,Opérateurs<4>,Préfixe masque réseau et masque de l'hôte,Définitions de réseaux IP
@anchor{library/ipaddress network-objects}@anchor{3ba4}
@subsubsection Objets réseau


All attributes implemented by address objects are implemented by network
objects as well.  In addition, network objects implement additional attributes.
All of these are common between @ref{1fb,,IPv4Network} and @ref{1fc,,IPv6Network},
so to avoid duplication they are only documented for @ref{1fb,,IPv4Network}.
Network objects are @ref{5fb,,hashable}, so they can be used as keys in
dictionaries.

@geindex IPv4Network (classe dans ipaddress)
@anchor{library/ipaddress ipaddress IPv4Network}@anchor{1fb}
@deffn {Classe} ipaddress.IPv4Network (address, strict=True)

Construit une définition de réseau IPv4. `address' peut valoir :


@enumerate 

@item 
A string consisting of an IP address and an optional mask, separated by
a slash (@code{/}).  The IP address is the network address, and the mask
can be either a single number, which means it's a `prefix', or a string
representation of an IPv4 address.  If it's the latter, the mask is
interpreted as a `net mask' if it starts with a non-zero field, or as a
`host mask' if it starts with a zero field, with the single exception of
an all-zero mask which is treated as a `net mask'.  If no mask is provided,
it's considered to be @code{/32}.

For example, the following `address' specifications are equivalent:
@code{192.168.1.0/24}, @code{192.168.1.0/255.255.255.0} and
@code{192.168.1.0/0.0.0.255}.

@item 
An integer that fits into 32 bits.  This is equivalent to a
single-address network, with the network address being `address' and
the mask being @code{/32}.

@item 
An integer packed into a @ref{1bd,,bytes} object of length 4, big-endian.
The interpretation is similar to an integer `address'.

@item 
A two-tuple of an address description and a netmask, where the address
description is either a string, a 32-bits integer, a 4-bytes packed
integer, or an existing IPv4Address object; and the netmask is either
an integer representing the prefix length (e.g. @code{24}) or a string
representing the prefix mask (e.g. @code{255.255.255.0}).
@end enumerate

An @ref{3b83,,AddressValueError} is raised if `address' is not a valid IPv4
address.  A @ref{3ba5,,NetmaskValueError} is raised if the mask is not valid for
an IPv4 address.

If `strict' is @code{True} and host bits are set in the supplied address,
then @ref{1ff,,ValueError} is raised.  Otherwise, the host bits are masked out
to determine the appropriate network address.

Unless stated otherwise, all network methods accepting other network/address
objects will raise @ref{522,,TypeError} if the argument's IP version is
incompatible to @code{self}.


Modifié dans la version 3.5: Ajout de la forme paire pour le paramètre `address' du constructeur.


@geindex version (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network version}@anchor{3ba6}
@deffn {Attribut} version
@end deffn

@geindex max_prefixlen (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network max_prefixlen}@anchor{3ba7}
@deffn {Attribut} max_prefixlen

Référez-vous à la documentation de l'attribut correspondant dans @ref{1f9,,IPv4Address}.
@end deffn

@geindex is_multicast (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_multicast}@anchor{3ba8}
@deffn {Attribut} is_multicast
@end deffn

@geindex is_private (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_private}@anchor{3ba9}
@deffn {Attribut} is_private
@end deffn

@geindex is_unspecified (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_unspecified}@anchor{3baa}
@deffn {Attribut} is_unspecified
@end deffn

@geindex is_reserved (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_reserved}@anchor{3bab}
@deffn {Attribut} is_reserved
@end deffn

@geindex is_loopback (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_loopback}@anchor{3bac}
@deffn {Attribut} is_loopback
@end deffn

@geindex is_link_local (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network is_link_local}@anchor{3bad}
@deffn {Attribut} is_link_local

These attributes are true for the network as a whole if they are true
for both the network address and the broadcast address.
@end deffn

@geindex network_address (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network network_address}@anchor{3bae}
@deffn {Attribut} network_address

The network address for the network. The network address and the
prefix length together uniquely define a network.
@end deffn

@geindex broadcast_address (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network broadcast_address}@anchor{3baf}
@deffn {Attribut} broadcast_address

The broadcast address for the network. Packets sent to the broadcast
address should be received by every host on the network.
@end deffn

@geindex hostmask (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network hostmask}@anchor{3bb0}
@deffn {Attribut} hostmask

Le masque de l'hôte, en tant qu'objet @ref{1f9,,IPv4Address}.
@end deffn

@geindex netmask (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network netmask}@anchor{3bb1}
@deffn {Attribut} netmask

Le masque réseau, en tant qu'objet @ref{1f9,,IPv4Address}.
@end deffn

@geindex with_prefixlen (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network with_prefixlen}@anchor{3bb2}
@deffn {Attribut} with_prefixlen
@end deffn

@geindex compressed (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network compressed}@anchor{3bb3}
@deffn {Attribut} compressed
@end deffn

@geindex exploded (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network exploded}@anchor{3bb4}
@deffn {Attribut} exploded

Adresse IP du réseau sous forme d'une chaîne, avec le masque en notation CIDR.

@code{with_prefixlen} and @code{compressed} are always the same as
@code{str(network)}.
@code{exploded} uses the exploded form the network address.
@end deffn

@geindex with_netmask (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network with_netmask}@anchor{3bb5}
@deffn {Attribut} with_netmask

A string representation of the network, with the mask in net mask
notation.
@end deffn

@geindex with_hostmask (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network with_hostmask}@anchor{3bb6}
@deffn {Attribut} with_hostmask

A string representation of the network, with the mask in host mask
notation.
@end deffn

@geindex num_addresses (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network num_addresses}@anchor{3bb7}
@deffn {Attribut} num_addresses

Le nombre total d'adresses dans le réseau.
@end deffn

@geindex prefixlen (attribut ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network prefixlen}@anchor{3bb8}
@deffn {Attribut} prefixlen

Length of the network prefix, in bits.
@end deffn

@geindex hosts() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network hosts}@anchor{3bb9}
@deffn {Méthode} hosts ()

Returns an iterator over the usable hosts in the network.  The usable
hosts are all the IP addresses that belong to the network, except the
network address itself and the network broadcast address.  For networks
with a mask length of 31, the network address and network broadcast
address are also included in the result. Networks with a mask of 32
will return a list containing the single host address.

@example
>>> list(ip_network('192.0.2.0/29').hosts())  
[IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),
 IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),
 IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')]
>>> list(ip_network('192.0.2.0/31').hosts())
[IPv4Address('192.0.2.0'), IPv4Address('192.0.2.1')]
>>> list(ip_network('192.0.2.1/32').hosts())
[IPv4Address('192.0.2.1')]
@end example
@end deffn

@geindex overlaps() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network overlaps}@anchor{3bba}
@deffn {Méthode} overlaps (other)

@code{True} si ce réseau est partiellement ou complètement contenu dans `other' ou `other' est complètement contenu dans ce réseau.
@end deffn

@geindex address_exclude() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network address_exclude}@anchor{3bbb}
@deffn {Méthode} address_exclude (network)

Computes the network definitions resulting from removing the given
`network' from this one.  Returns an iterator of network objects.
Raises @ref{1ff,,ValueError} if `network' is not completely contained in
this network.

@example
>>> n1 = ip_network('192.0.2.0/28')
>>> n2 = ip_network('192.0.2.1/32')
>>> list(n1.address_exclude(n2))  
[IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),
 IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')]
@end example
@end deffn

@geindex subnets() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network subnets}@anchor{e89}
@deffn {Méthode} subnets (prefixlen_diff=1, new_prefix=None)

The subnets that join to make the current network definition, depending
on the argument values.  `prefixlen_diff' is the amount our prefix
length should be increased by.  `new_prefix' is the desired new
prefix of the subnets; it must be larger than our prefix.  One and
only one of `prefixlen_diff' and `new_prefix' must be set.  Returns an
iterator of network objects.

@example
>>> list(ip_network('192.0.2.0/24').subnets())
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
>>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))  
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))  
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise ValueError('new prefix must be longer')
ValueError: new prefix must be longer
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
@end example
@end deffn

@geindex supernet() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network supernet}@anchor{e8a}
@deffn {Méthode} supernet (prefixlen_diff=1, new_prefix=None)

The supernet containing this network definition, depending on the
argument values.  `prefixlen_diff' is the amount our prefix length
should be decreased by.  `new_prefix' is the desired new prefix of
the supernet; it must be smaller than our prefix.  One and only one
of `prefixlen_diff' and `new_prefix' must be set.  Returns a single
network object.

@example
>>> ip_network('192.0.2.0/24').supernet()
IPv4Network('192.0.2.0/23')
>>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)
IPv4Network('192.0.0.0/22')
>>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
IPv4Network('192.0.0.0/20')
@end example
@end deffn

@geindex subnet_of() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network subnet_of}@anchor{3bbc}
@deffn {Méthode} subnet_of (other)

Renvoie @code{True} si ce réseau est un sous-réseau de `other'.

@example
>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True
@end example


Ajouté dans la version 3.7.

@end deffn

@geindex supernet_of() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network supernet_of}@anchor{3bbd}
@deffn {Méthode} supernet_of (other)

Renvoie @code{True} si `other' est un sous-réseau de ce réseau.

@example
>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True
@end example


Ajouté dans la version 3.7.

@end deffn

@geindex compare_networks() (méthode ipaddress.IPv4Network)
@anchor{library/ipaddress ipaddress IPv4Network compare_networks}@anchor{3bbe}
@deffn {Méthode} compare_networks (other)

Compare this network to `other'.  In this comparison only the network
addresses are considered; host bits aren't.  Returns either @code{-1},
@code{0} or @code{1}.

@example
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))
-1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))
1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))
0
@end example


Obsolète depuis la version 3.7: Utilise le même algorithme de relation d'ordre et de comparaison que @code{<}, @code{==}, et @code{>}.

@end deffn
@end deffn

@geindex IPv6Network (classe dans ipaddress)
@anchor{library/ipaddress ipaddress IPv6Network}@anchor{1fc}
@deffn {Classe} ipaddress.IPv6Network (address, strict=True)

Construit une définition de réseau IPv6. `address' peut valoir :


@enumerate 

@item 
A string consisting of an IP address and an optional prefix length,
separated by a slash (@code{/}).  The IP address is the network address,
and the prefix length must be a single number, the `prefix'.  If no
prefix length is provided, it's considered to be @code{/128}.

Note that currently expanded netmasks are not supported.  That means
@code{2001:db00::0/24} is a valid argument while @code{2001:db00::0/ffff:ff00::}
is not.

@item 
An integer that fits into 128 bits.  This is equivalent to a
single-address network, with the network address being `address' and
the mask being @code{/128}.

@item 
An integer packed into a @ref{1bd,,bytes} object of length 16, big-endian.
The interpretation is similar to an integer `address'.

@item 
A two-tuple of an address description and a netmask, where the address
description is either a string, a 128-bits integer, a 16-bytes packed
integer, or an existing IPv6Address object; and the netmask is an
integer representing the prefix length.
@end enumerate

An @ref{3b83,,AddressValueError} is raised if `address' is not a valid IPv6
address.  A @ref{3ba5,,NetmaskValueError} is raised if the mask is not valid for
an IPv6 address.

If `strict' is @code{True} and host bits are set in the supplied address,
then @ref{1ff,,ValueError} is raised.  Otherwise, the host bits are masked out
to determine the appropriate network address.


Modifié dans la version 3.5: Ajout de la forme paire pour le paramètre `address' du constructeur.


@geindex version (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network version}@anchor{3bbf}
@deffn {Attribut} version
@end deffn

@geindex max_prefixlen (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network max_prefixlen}@anchor{3bc0}
@deffn {Attribut} max_prefixlen
@end deffn

@geindex is_multicast (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_multicast}@anchor{3bc1}
@deffn {Attribut} is_multicast
@end deffn

@geindex is_private (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_private}@anchor{3bc2}
@deffn {Attribut} is_private
@end deffn

@geindex is_unspecified (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_unspecified}@anchor{3bc3}
@deffn {Attribut} is_unspecified
@end deffn

@geindex is_reserved (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_reserved}@anchor{3bc4}
@deffn {Attribut} is_reserved
@end deffn

@geindex is_loopback (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_loopback}@anchor{3bc5}
@deffn {Attribut} is_loopback
@end deffn

@geindex is_link_local (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_link_local}@anchor{3bc6}
@deffn {Attribut} is_link_local
@end deffn

@geindex network_address (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network network_address}@anchor{3bc7}
@deffn {Attribut} network_address
@end deffn

@geindex broadcast_address (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network broadcast_address}@anchor{3bc8}
@deffn {Attribut} broadcast_address
@end deffn

@geindex hostmask (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network hostmask}@anchor{3bc9}
@deffn {Attribut} hostmask
@end deffn

@geindex netmask (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network netmask}@anchor{3bca}
@deffn {Attribut} netmask
@end deffn

@geindex with_prefixlen (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network with_prefixlen}@anchor{3bcb}
@deffn {Attribut} with_prefixlen
@end deffn

@geindex compressed (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network compressed}@anchor{3bcc}
@deffn {Attribut} compressed
@end deffn

@geindex exploded (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network exploded}@anchor{3bcd}
@deffn {Attribut} exploded
@end deffn

@geindex with_netmask (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network with_netmask}@anchor{3bce}
@deffn {Attribut} with_netmask
@end deffn

@geindex with_hostmask (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network with_hostmask}@anchor{3bcf}
@deffn {Attribut} with_hostmask
@end deffn

@geindex num_addresses (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network num_addresses}@anchor{3bd0}
@deffn {Attribut} num_addresses
@end deffn

@geindex prefixlen (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network prefixlen}@anchor{3bd1}
@deffn {Attribut} prefixlen
@end deffn

@geindex hosts() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network hosts}@anchor{3bd2}
@deffn {Méthode} hosts ()

Returns an iterator over the usable hosts in the network.  The usable
hosts are all the IP addresses that belong to the network, except the
Subnet-Router anycast address.  For networks with a mask length of 127,
the Subnet-Router anycast address is also included in the result.
Networks with a mask of 128 will return a list containing the
single host address.
@end deffn

@geindex overlaps() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network overlaps}@anchor{3bd3}
@deffn {Méthode} overlaps (other)
@end deffn

@geindex address_exclude() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network address_exclude}@anchor{3bd4}
@deffn {Méthode} address_exclude (network)
@end deffn

@geindex subnets() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network subnets}@anchor{3bd5}
@deffn {Méthode} subnets (prefixlen_diff=1, new_prefix=None)
@end deffn

@geindex supernet() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network supernet}@anchor{3bd6}
@deffn {Méthode} supernet (prefixlen_diff=1, new_prefix=None)
@end deffn

@geindex subnet_of() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network subnet_of}@anchor{3bd7}
@deffn {Méthode} subnet_of (other)
@end deffn

@geindex supernet_of() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network supernet_of}@anchor{3bd8}
@deffn {Méthode} supernet_of (other)
@end deffn

@geindex compare_networks() (méthode ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network compare_networks}@anchor{3bd9}
@deffn {Méthode} compare_networks (other)

Référez-vous à la documentation de l'attribut correspondant dans @ref{1fb,,IPv4Network}.
@end deffn

@geindex is_site_local (attribut ipaddress.IPv6Network)
@anchor{library/ipaddress ipaddress IPv6Network is_site_local}@anchor{3bda}
@deffn {Attribut} is_site_local

These attribute is true for the network as a whole if it is true
for both the network address and the broadcast address.
@end deffn
@end deffn

@node Opérateurs<4>,,Objets réseau,Définitions de réseaux IP
@anchor{library/ipaddress id1}@anchor{3bdb}
@subsubsection Opérateurs


Network objects support some operators.  Unless stated otherwise, operators can
only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
IPv6).

@menu
* Opérateurs logiques:: 
* Itération:: 
* Réseaux en tant que conteneurs d'adresses:: 

@end menu

@node Opérateurs logiques,Itération,,Opérateurs<4>
@anchor{library/ipaddress logical-operators}@anchor{3bdc}
@subsubsection Opérateurs logiques


Network objects can be compared with the usual set of logical operators.
Network objects are ordered first by network address, then by net mask.

@node Itération,Réseaux en tant que conteneurs d'adresses,Opérateurs logiques,Opérateurs<4>
@anchor{library/ipaddress iteration}@anchor{3bdd}
@subsubsection Itération


Network objects can be iterated to list all the addresses belonging to the
network.  For iteration, `all' hosts are returned, including unusable hosts
(for usable hosts, use the @ref{3bb9,,hosts()} method).  An
example:

@example
>>> for addr in IPv4Network('192.0.2.0/28'):
...     addr
...
IPv4Address('192.0.2.0')
IPv4Address('192.0.2.1')
IPv4Address('192.0.2.2')
IPv4Address('192.0.2.3')
IPv4Address('192.0.2.4')
IPv4Address('192.0.2.5')
IPv4Address('192.0.2.6')
IPv4Address('192.0.2.7')
IPv4Address('192.0.2.8')
IPv4Address('192.0.2.9')
IPv4Address('192.0.2.10')
IPv4Address('192.0.2.11')
IPv4Address('192.0.2.12')
IPv4Address('192.0.2.13')
IPv4Address('192.0.2.14')
IPv4Address('192.0.2.15')
@end example

@node Réseaux en tant que conteneurs d'adresses,,Itération,Opérateurs<4>
@anchor{library/ipaddress networks-as-containers-of-addresses}@anchor{3bde}
@subsubsection Réseaux en tant que conteneurs d'adresses


Les objets réseau peuvent agir en tant que conteneurs d'adresses. Quelques exemples :

@example
>>> IPv4Network('192.0.2.0/28')[0]
IPv4Address('192.0.2.0')
>>> IPv4Network('192.0.2.0/28')[15]
IPv4Address('192.0.2.15')
>>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
True
>>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
False
@end example

@node Objets interface,Autres fonctions au niveau de module,Définitions de réseaux IP,ipaddress --- IPv4/IPv6 manipulation library
@anchor{library/ipaddress interface-objects}@anchor{3bdf}
@subsubsection Objets interface


Les objets interface sont @ref{5fb,,hachables}, ce qui signifie qu'ils peuvent être utilisés comme clés de dictionnaire.

@geindex IPv4Interface (classe dans ipaddress)
@anchor{library/ipaddress ipaddress IPv4Interface}@anchor{179c}
@deffn {Classe} ipaddress.IPv4Interface (address)

Construct an IPv4 interface.  The meaning of `address' is as in the
constructor of @ref{1fb,,IPv4Network}, except that arbitrary host addresses
are always accepted.

@ref{179c,,IPv4Interface} is a subclass of @ref{1f9,,IPv4Address}, so it inherits
all the attributes from that class.  In addition, the following attributes
are available:

@geindex ip (attribut ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface ip}@anchor{3be0}
@deffn {Attribut} ip

L'adresse (@ref{1f9,,IPv4Address}) sans information de réseau.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.ip
IPv4Address('192.0.2.5')
@end example
@end deffn

@geindex network (attribut ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface network}@anchor{3be1}
@deffn {Attribut} network

Le réseau (@ref{1fb,,IPv4Network}) auquel cette interface appartient.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.network
IPv4Network('192.0.2.0/24')
@end example
@end deffn

@geindex with_prefixlen (attribut ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface with_prefixlen}@anchor{3be2}
@deffn {Attribut} with_prefixlen

A string representation of the interface with the mask in prefix notation.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_prefixlen
'192.0.2.5/24'
@end example
@end deffn

@geindex with_netmask (attribut ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface with_netmask}@anchor{3be3}
@deffn {Attribut} with_netmask

A string representation of the interface with the network as a net mask.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_netmask
'192.0.2.5/255.255.255.0'
@end example
@end deffn

@geindex with_hostmask (attribut ipaddress.IPv4Interface)
@anchor{library/ipaddress ipaddress IPv4Interface with_hostmask}@anchor{3be4}
@deffn {Attribut} with_hostmask

A string representation of the interface with the network as a host mask.

@example
>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_hostmask
'192.0.2.5/0.0.0.255'
@end example
@end deffn
@end deffn

@geindex IPv6Interface (classe dans ipaddress)
@anchor{library/ipaddress ipaddress IPv6Interface}@anchor{179d}
@deffn {Classe} ipaddress.IPv6Interface (address)

Construct an IPv6 interface.  The meaning of `address' is as in the
constructor of @ref{1fc,,IPv6Network}, except that arbitrary host addresses
are always accepted.

@ref{179d,,IPv6Interface} is a subclass of @ref{1fa,,IPv6Address}, so it inherits
all the attributes from that class.  In addition, the following attributes
are available:

@geindex ip (attribut ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface ip}@anchor{3be5}
@deffn {Attribut} ip
@end deffn

@geindex network (attribut ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface network}@anchor{3be6}
@deffn {Attribut} network
@end deffn

@geindex with_prefixlen (attribut ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface with_prefixlen}@anchor{3be7}
@deffn {Attribut} with_prefixlen
@end deffn

@geindex with_netmask (attribut ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface with_netmask}@anchor{3be8}
@deffn {Attribut} with_netmask
@end deffn

@geindex with_hostmask (attribut ipaddress.IPv6Interface)
@anchor{library/ipaddress ipaddress IPv6Interface with_hostmask}@anchor{3be9}
@deffn {Attribut} with_hostmask

Référez-vous à la documentation de l'attribut correspondant dans @ref{179c,,IPv4Interface}.
@end deffn
@end deffn

@menu
* Opérateurs: Opérateurs<5>. 

@end menu

@node Opérateurs<5>,,,Objets interface
@anchor{library/ipaddress id2}@anchor{3bea}
@subsubsection Opérateurs


Interface objects support some operators.  Unless stated otherwise, operators
can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
IPv6).

@menu
* Opérateurs logiques: Opérateurs logiques<2>. 

@end menu

@node Opérateurs logiques<2>,,,Opérateurs<5>
@anchor{library/ipaddress id3}@anchor{3beb}
@subsubsection Opérateurs logiques


Interface objects can be compared with the usual set of logical operators.

For equality comparison (@code{==} and @code{!=}), both the IP address and network
must be the same for the objects to be equal.  An interface will not compare
equal to any address or network object.

For ordering (@code{<}, @code{>}, etc) the rules are different.  Interface and
address objects with the same IP version can be compared, and the address
objects will always sort before the interface objects.  Two interface objects
are first compared by their networks and, if those are the same, then by their
IP addresses.

@node Autres fonctions au niveau de module,Exceptions personnalisées,Objets interface,ipaddress --- IPv4/IPv6 manipulation library
@anchor{library/ipaddress other-module-level-functions}@anchor{3bec}
@subsubsection Autres fonctions au niveau de module


Le module fournit aussi les fonctions suivantes :

@geindex v4_int_to_packed() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress v4_int_to_packed}@anchor{3bed}
@deffn {Fonction} ipaddress.v4_int_to_packed (address)

Represent an address as 4 packed bytes in network (big-endian) order.
`address' is an integer representation of an IPv4 IP address.  A
@ref{1ff,,ValueError} is raised if the integer is negative or too large to be an
IPv4 IP address.

@example
>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.v4_int_to_packed(3221225985)
b'\xc0\x00\x02\x01'
@end example
@end deffn

@geindex v6_int_to_packed() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress v6_int_to_packed}@anchor{3bee}
@deffn {Fonction} ipaddress.v6_int_to_packed (address)

Represent an address as 16 packed bytes in network (big-endian) order.
`address' is an integer representation of an IPv6 IP address.  A
@ref{1ff,,ValueError} is raised if the integer is negative or too large to be an
IPv6 IP address.
@end deffn

@geindex summarize_address_range() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress summarize_address_range}@anchor{e8b}
@deffn {Fonction} ipaddress.summarize_address_range (first, last)

Return an iterator of the summarized network range given the first and last
IP addresses.  `first' is the first @ref{1f9,,IPv4Address} or
@ref{1fa,,IPv6Address} in the range and `last' is the last @ref{1f9,,IPv4Address}
or @ref{1fa,,IPv6Address} in the range.  A @ref{522,,TypeError} is raised if
`first' or `last' are not IP addresses or are not of the same version.  A
@ref{1ff,,ValueError} is raised if `last' is not greater than `first' or if
`first' address version is not 4 or 6.

@example
>>> [ipaddr for ipaddr in ipaddress.summarize_address_range(
...    ipaddress.IPv4Address('192.0.2.0'),
...    ipaddress.IPv4Address('192.0.2.130'))]
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]
@end example
@end deffn

@geindex collapse_addresses() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress collapse_addresses}@anchor{e8c}
@deffn {Fonction} ipaddress.collapse_addresses (addresses)

Return an iterator of the collapsed @ref{1fb,,IPv4Network} or
@ref{1fc,,IPv6Network} objects.  `addresses' is an @ref{1205,,iterable} of
@ref{1fb,,IPv4Network} or @ref{1fc,,IPv6Network} objects.  A @ref{522,,TypeError} is
raised if `addresses' contains mixed version objects.

@example
>>> [ipaddr for ipaddr in
... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
... ipaddress.IPv4Network('192.0.2.128/25')])]
[IPv4Network('192.0.2.0/24')]
@end example
@end deffn

@geindex get_mixed_type_key() (dans le module ipaddress)
@anchor{library/ipaddress ipaddress get_mixed_type_key}@anchor{3bef}
@deffn {Fonction} ipaddress.get_mixed_type_key (obj)

Return a key suitable for sorting between networks and addresses.  Address
and Network objects are not sortable by default; they're fundamentally
different, so the expression:

@example
IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
@end example

doesn't make sense.  There are some times however, where you may wish to
have @ref{7f,,ipaddress} sort these anyway.  If you need to do this, you can use
this function as the `key' argument to @ref{bbc,,sorted()}.

`obj' est un objet réseau ou adresse.
@end deffn

@node Exceptions personnalisées,,Autres fonctions au niveau de module,ipaddress --- IPv4/IPv6 manipulation library
@anchor{library/ipaddress custom-exceptions}@anchor{3bf0}
@subsubsection Exceptions personnalisées


To support more specific error reporting from class constructors, the
module defines the following exceptions:

@geindex AddressValueError
@anchor{library/ipaddress ipaddress AddressValueError}@anchor{3b83}
@deffn {Exception} ipaddress.AddressValueError (ValueError)

Toute erreur de valeur liée à l'adresse.
@end deffn

@geindex NetmaskValueError
@anchor{library/ipaddress ipaddress NetmaskValueError}@anchor{3ba5}
@deffn {Exception} ipaddress.NetmaskValueError (ValueError)

Toute erreur de valeur liée au masque réseau.
@end deffn

@node Services multimédia,Internationalisation,Gestion des protocoles internet,La bibliothèque standard
@anchor{library/mm doc}@anchor{3bf1}@anchor{library/mm mmedia}@anchor{3bf2}@anchor{library/mm multimedia-services}@anchor{3bf3}
@section Services multimédia


Les modules documentés dans ce chapitre implémentent divers algorithmes ou interfaces principalement utiles pour les applications multimédia. Ils peuvent ne pas être disponibles sur votre installation. En voici un aperçu :

@menu
* wave: wave --- Read and write WAV files. Read and write WAV files
* colorsys: colorsys --- Conversions between color systems. Conversions between color systems

@end menu

@node wave --- Read and write WAV files,colorsys --- Conversions between color systems,,Services multimédia
@anchor{library/wave doc}@anchor{3bf4}@anchor{library/wave module-wave}@anchor{112}@anchor{library/wave wave-read-and-write-wav-files}@anchor{3bf5}
@subsection @code{wave} --- Read and write WAV files


@geindex module; wave

@c Documentations stolen from comments in file.

`Code source :' Lib/wave.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/wave.py}


__________________________________________________________________


The @ref{112,,wave} module provides a convenient interface to the Waveform Audio
"WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
supported.


Modifié dans la version 3.12: Support for @code{WAVE_FORMAT_EXTENSIBLE} headers was added, provided that the
extended format is @code{KSDATAFORMAT_SUBTYPE_PCM}.


Le module @ref{112,,wave} définit la fonction et l'exception suivante :

@geindex open() (dans le module wave)
@anchor{library/wave wave open}@anchor{938}
@deffn {Fonction} wave.open (file, mode=None)

Si `file' est une chaîne de caractères, ouvre le fichier sous ce nom, sinon, il est traité comme un objet de type fichier. `mode' peut être :


@table @asis

@item @code{'rb'}

Mode lecture seule.

@item @code{'wb'}

Mode écriture seule.
@end table

Notez que ce module ne permet pas de manipuler des fichiers WAV en lecture/écriture.

Un `mode' @code{'rb'} renvoie un objet @ref{2b3,,Wave_read}, alors qu'un `mode' @code{'wb'} renvoie un objet @ref{2b4,,Wave_write}. Si `mode' est omis et qu'un objet de type fichier est donné au paramètre `file', @code{file.mode} est utilisé comme valeur par défaut pour `mode'.

If you pass in a file-like object, the wave object will not close it when its
@code{close()} method is called; it is the caller's responsibility to close
the file object.

The @ref{938,,open()} function may be used in a @ref{5bc,,with} statement.  When
the @code{with} block completes, the @ref{3bf6,,Wave_read.close()} or
@ref{3bf7,,Wave_write.close()} method is called.


Modifié dans la version 3.4: Ajout de la gestion des fichiers non navigables.

@end deffn

@geindex Error
@anchor{library/wave wave Error}@anchor{3bf8}
@deffn {Exception} wave.Error

Une erreur est levée lorsque quelque chose est impossible car elle enfreint la spécification WAV ou rencontre un problème d'implémentation.
@end deffn

@menu
* Objets Wave_read:: 
* Objets Wave_write:: 

@end menu

@node Objets Wave_read,Objets Wave_write,,wave --- Read and write WAV files
@anchor{library/wave id1}@anchor{3bf9}@anchor{library/wave wave-read-objects}@anchor{3bfa}
@subsubsection Objets Wave_read


@geindex Wave_read (classe dans wave)
@anchor{library/wave wave Wave_read}@anchor{2b3}
@deffn {Classe} wave.Wave_read

Read a WAV file.

Les objets Wave_read, tels qu'ils sont renvoyés par @ref{938,,open()}, ont les méthodes suivantes :

@geindex close() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read close}@anchor{3bf6}
@deffn {Méthode} close ()

Ferme le flux s'il a été ouvert par @ref{112,,wave} et rend l'instance inutilisable. Ceci est appelé automatiquement lorsque l'objet est détruit .
@end deffn

@geindex getnchannels() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getnchannels}@anchor{3bfb}
@deffn {Méthode} getnchannels ()

Renvoie le nombre de canaux audio (@code{1} pour mono, @code{2} pour stéréo).
@end deffn

@geindex getsampwidth() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getsampwidth}@anchor{3bfc}
@deffn {Méthode} getsampwidth ()

Renvoie la largeur de l'échantillon en octets.
@end deffn

@geindex getframerate() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getframerate}@anchor{3bfd}
@deffn {Méthode} getframerate ()

Renvoie la fréquence d'échantillonnage.
@end deffn

@geindex getnframes() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getnframes}@anchor{3bfe}
@deffn {Méthode} getnframes ()

Renvoie le nombre de trames audio.
@end deffn

@geindex getcomptype() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getcomptype}@anchor{3bff}
@deffn {Méthode} getcomptype ()

Renvoie le type de compression (@code{'NONE'} est le seul type géré).
@end deffn

@geindex getcompname() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getcompname}@anchor{3c00}
@deffn {Méthode} getcompname ()

Version compréhensible de @ref{3bff,,getcomptype()}. Généralement, @code{'not compressed'} équivaut à @code{'NONE'}.
@end deffn

@geindex getparams() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getparams}@anchor{3c01}
@deffn {Méthode} getparams ()

Returns a @ref{1c5,,namedtuple()} @code{(nchannels, sampwidth,
framerate, nframes, comptype, compname)}, equivalent to output of the
@code{get*()} methods.
@end deffn

@geindex readframes() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read readframes}@anchor{3c02}
@deffn {Méthode} readframes (n)

Lit et renvoie au plus `n' trames audio, sous forme d'objet @ref{1bd,,bytes}.
@end deffn

@geindex rewind() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read rewind}@anchor{3c03}
@deffn {Méthode} rewind ()

Remet le pointeur de fichier au début du flux audio.
@end deffn

The following two methods are defined for compatibility with the old @code{aifc}
module, and don't do anything interesting.

@geindex getmarkers() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getmarkers}@anchor{2b2}
@deffn {Méthode} getmarkers ()

Renvoie @code{None}.


Deprecated since version 3.13, will be removed in version 3.15: The method only existed for compatibility with the @code{aifc} module
which has been removed in Python 3.13.

@end deffn

@geindex getmark() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read getmark}@anchor{2b1}
@deffn {Méthode} getmark (id)

Lève une erreur.


Deprecated since version 3.13, will be removed in version 3.15: The method only existed for compatibility with the @code{aifc} module
which has been removed in Python 3.13.

@end deffn

Les deux fonctions suivantes utilisent le vocabulaire "position". Ces positions sont compatible entre elles, la "position" de l'un est compatible avec la "position" de l'autre. Cette position est dépendante de l'implémentation.

@geindex setpos() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read setpos}@anchor{3c04}
@deffn {Méthode} setpos (pos)

Place le pointeur du fichier sur la position spécifiée.
@end deffn

@geindex tell() (méthode wave.Wave_read)
@anchor{library/wave wave Wave_read tell}@anchor{3c05}
@deffn {Méthode} tell ()

Renvoie la position actuelle du pointeur du fichier.
@end deffn
@end deffn

@node Objets Wave_write,,Objets Wave_read,wave --- Read and write WAV files
@anchor{library/wave id2}@anchor{3c06}@anchor{library/wave wave-write-objects}@anchor{fd4}
@subsubsection Objets Wave_write


@geindex Wave_write (classe dans wave)
@anchor{library/wave wave Wave_write}@anchor{2b4}
@deffn {Classe} wave.Wave_write

Write a WAV file.

Wave_write objects, as returned by @ref{938,,open()}.

For seekable output streams, the @code{wave} header will automatically be updated
to reflect the number of frames actually written.  For unseekable streams, the
`nframes' value must be accurate when the first frame data is written.  An
accurate `nframes' value can be achieved either by calling
@ref{3c07,,setnframes()} or @ref{3c08,,setparams()} with the number
of frames that will be written before @ref{3bf7,,close()} is called and
then using @ref{fd5,,writeframesraw()} to write the frame data, or by
calling @ref{fd6,,writeframes()} with all of the frame data to be
written.  In the latter case @ref{fd6,,writeframes()} will calculate
the number of frames in the data and set `nframes' accordingly before writing
the frame data.


Modifié dans la version 3.4: Ajout de la gestion des fichiers non navigables.


Wave_write objects have the following methods:

@geindex close() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write close}@anchor{3bf7}
@deffn {Méthode} close ()

Assurez-vous que `nframes' soit correct et fermez le fichier s'il a été ouvert par @ref{112,,wave}. Cette méthode est appelée à la destruction de l'objet. Il lève une erreur si le flux de sortie n'est pas navigable et si `nframes' ne correspond pas au nombre de trames réellement écrites.
@end deffn

@geindex setnchannels() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write setnchannels}@anchor{3c09}
@deffn {Méthode} setnchannels (n)

Définit le nombre de canaux.
@end deffn

@geindex setsampwidth() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write setsampwidth}@anchor{3c0a}
@deffn {Méthode} setsampwidth (n)

Définit la largeur de l'échantillon à `n' octets.
@end deffn

@geindex setframerate() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write setframerate}@anchor{3c0b}
@deffn {Méthode} setframerate (n)

Définit la fréquence des trames à `n'.


Modifié dans la version 3.2: Un paramètre non-entier passé à cette méthode est arrondi à l'entier le plus proche.

@end deffn

@geindex setnframes() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write setnframes}@anchor{3c07}
@deffn {Méthode} setnframes (n)

Définit le nombre de trames à `n'. Cela sera modifié ultérieurement si le nombre de trames réellement écrites est différent (la tentative de mise à jour générera une erreur si le flux de sortie n'est pas indexable).
@end deffn

@geindex setcomptype() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write setcomptype}@anchor{3c0c}
@deffn {Méthode} setcomptype (type, name)

Définit le type de compression et la description. Pour le moment, seul le type de compression @code{NONE} est géré, c'est-à-dire aucune compression.
@end deffn

@geindex setparams() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write setparams}@anchor{3c08}
@deffn {Méthode} setparams (tuple)

The `tuple' should be @code{(nchannels, sampwidth, framerate, nframes, comptype,
compname)}, with values valid for the @code{set*()} methods.  Sets all
parameters.
@end deffn

@geindex tell() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write tell}@anchor{3c0d}
@deffn {Méthode} tell ()

Renvoie la position actuelle dans le fichier, avec les mêmes réserves que pour les méthodes @ref{3c05,,Wave_read.tell()} et @ref{3c04,,Wave_read.setpos()}.
@end deffn

@geindex writeframesraw() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write writeframesraw}@anchor{fd5}
@deffn {Méthode} writeframesraw (data)

Écrit les trames audio sans corriger `nframes'.


Modifié dans la version 3.4: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.

@end deffn

@geindex writeframes() (méthode wave.Wave_write)
@anchor{library/wave wave Wave_write writeframes}@anchor{fd6}
@deffn {Méthode} writeframes (data)

Écrit des trames audio et s'assure que `nframes' est correct. Une erreur est levée si le flux de sortie est non-navigable et si le nombre total de trames écrites après que `data' soit écrit ne correspond pas à la valeur précédemment définie pour `nframes'.


Modifié dans la version 3.4: N'importe quel @ref{d1b,,bytes-like object} est maintenant accepté.


Notez qu'il est impossible de définir des paramètres après avoir appelé @ref{fd6,,writeframes()} ou @ref{fd5,,writeframesraw()}, et toute tentative en ce sens lève une @ref{3bf8,,wave.Error}.
@end deffn
@end deffn

@node colorsys --- Conversions between color systems,,wave --- Read and write WAV files,Services multimédia
@anchor{library/colorsys doc}@anchor{3c0e}@anchor{library/colorsys colorsys-conversions-between-color-systems}@anchor{3c0f}@anchor{library/colorsys module-colorsys}@anchor{1f}
@subsection @code{colorsys} --- Conversions between color systems


@geindex module; colorsys

`Code source :' Lib/colorsys.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/colorsys.py}


__________________________________________________________________


The @ref{1f,,colorsys} module defines bidirectional conversions of color values
between colors expressed in the RGB (Red Green Blue) color space used in
computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
Saturation) and HSV (Hue Saturation Value).  Coordinates in all of these color
spaces are floating-point values.  In the YIQ space, the Y coordinate is between
0 and 1, but the I and Q coordinates can be positive or negative.  In all other
spaces, the coordinates are all between 0 and 1.


@subsubheading Voir aussi


Consultez @indicateurl{https://poynton.ca/ColorFAQ.html} et @indicateurl{https://www.cambridgeincolour.com/tutorials/color-spaces.htm} pour plus d'informations concernant les espaces colorimétriques.


Le module @ref{1f,,colorsys} définit les fonctions suivantes :

@geindex rgb_to_yiq() (dans le module colorsys)
@anchor{library/colorsys colorsys rgb_to_yiq}@anchor{3c10}
@deffn {Fonction} colorsys.rgb_to_yiq (r, g, b)

Convertit la couleur des coordonnées RGB (RVB) vers les coordonnées YIQ.
@end deffn

@geindex yiq_to_rgb() (dans le module colorsys)
@anchor{library/colorsys colorsys yiq_to_rgb}@anchor{3c11}
@deffn {Fonction} colorsys.yiq_to_rgb (y, i, q)

Convertit la couleur des coordonnées YIQ vers les coordonnées RGB (RVB).
@end deffn

@geindex rgb_to_hls() (dans le module colorsys)
@anchor{library/colorsys colorsys rgb_to_hls}@anchor{168b}
@deffn {Fonction} colorsys.rgb_to_hls (r, g, b)

Convertit la couleur des coordonnées RGB (RVB) vers les coordonnées HLS (TSV).
@end deffn

@geindex hls_to_rgb() (dans le module colorsys)
@anchor{library/colorsys colorsys hls_to_rgb}@anchor{3c12}
@deffn {Fonction} colorsys.hls_to_rgb (h, l, s)

Convertit la couleur des coordonnées HLS (TSV) vers les coordonnées RGB (RVB).
@end deffn

@geindex rgb_to_hsv() (dans le module colorsys)
@anchor{library/colorsys colorsys rgb_to_hsv}@anchor{3c13}
@deffn {Fonction} colorsys.rgb_to_hsv (r, g, b)

Convertit la couleur des coordonnées RGB (RVB) vers les coordonnées HSV (TSV).
@end deffn

@geindex hsv_to_rgb() (dans le module colorsys)
@anchor{library/colorsys colorsys hsv_to_rgb}@anchor{3c14}
@deffn {Fonction} colorsys.hsv_to_rgb (h, s, v)

Convertit la couleur des coordonnées HSV (TSV) vers les coordonnées RGB (RVB).
@end deffn

Exemple :

@example
>>> import colorsys
>>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)
(0.5, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)
(0.2, 0.4, 0.4)
@end example

@node Internationalisation,Cadriciels d'applications,Services multimédia,La bibliothèque standard
@anchor{library/i18n doc}@anchor{3c15}@anchor{library/i18n i18n}@anchor{3c16}@anchor{library/i18n internationalization}@anchor{3c17}
@section Internationalisation


Les modules décrits dans ce chapitre vous aident à rédiger des programmes indépendants des langues et des cultures en fournissant des mécanismes pour sélectionner une langue à utiliser dans les messages, ou en adaptant la sortie aux conventions culturelles.

La liste des modules documentés dans ce chapitre est :

@menu
* gettext: gettext --- Multilingual internationalization services. Multilingual internationalization services
* locale: locale --- Internationalization services. Internationalization services

@end menu

@node gettext --- Multilingual internationalization services,locale --- Internationalization services,,Internationalisation
@anchor{library/gettext doc}@anchor{3c18}@anchor{library/gettext gettext-multilingual-internationalization-services}@anchor{3c19}@anchor{library/gettext module-gettext}@anchor{62}
@subsection @code{gettext} --- Multilingual internationalization services


@geindex module; gettext

`Code source :' Lib/gettext.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/gettext.py}


__________________________________________________________________


Le module @ref{62,,gettext} fournit un service d'internationalisation (`I18N') et de localisation linguistique (`L10N') pour vos modules et applications Python. Il est compatible avec l'API du catalogue de messages GNU @code{gettext} et à un plus haut niveau, avec l'API basée sur les classes qui serait peut-être plus adaptée aux fichiers Python. L'interface décrite ci-dessous vous permet d'écrire les textes de vos modules et applications dans une langue naturelle, puis de fournir un catalogue de traductions pour les lancer ensuite dans d'autres langues naturelles.

Quelques astuces sur la localisation de vos modules et applications Python sont également données.

@menu
* API GNU gettext:: 
* API basée sur les classes:: 
* Internationaliser vos programmes et modules:: 
* Remerciements: Remerciements<9>. 

@end menu

@node API GNU gettext,API basée sur les classes,,gettext --- Multilingual internationalization services
@anchor{library/gettext gnu-gettext-api}@anchor{3c1a}
@subsubsection API GNU @code{gettext}


Le module @ref{62,,gettext} définit l'API suivante, qui est très proche de l'API de GNU @code{gettext}.  Si vous utilisez cette API, cela affectera la traduction de toute votre application.  C'est souvent le comportement attendu si votre application est monolingue, avec le choix de la langue qui dépend des paramètres linguistiques de l'utilisateur.  Si vous localisez un module Python ou si votre application a besoin de changer de langue à la volée, il est plus judicieux d'utiliser l'API basée sur des classes.

@geindex bindtextdomain() (dans le module gettext)
@anchor{library/gettext gettext bindtextdomain}@anchor{3c1b}
@deffn {Fonction} gettext.bindtextdomain (domain, localedir=None)

Lie `domain' au répertoire `localedir' des localisations. Plus spécifiquement, @ref{62,,gettext} va chercher les fichiers binaires @code{.mo} pour un domaine donné, en utilisant le chemin suivant (sous Unix) : @code{`localedir'/`language'/LC_MESSAGES/`domain'.mo}, où `language' est recherché dans l'une des variables d'environnement suivantes : 
@geindex LANGUAGE
@geindex variable d'environnement; LANGUAGE
@code{LANGUAGE}, 
@geindex LC_ALL
@geindex variable d'environnement; LC_ALL
@code{LC_ALL}, 
@geindex LC_MESSAGES
@geindex variable d'environnement; LC_MESSAGES
@code{LC_MESSAGES} et 
@geindex LANG
@geindex variable d'environnement; LANG
@code{LANG}.

Si `localedir' n'est pas renseigné ou vaut @code{None}, alors le lien actuel de `domain' est renvoyé. @footnote{
The default locale directory is system dependent; for example, on Red Hat Linux
it is @code{/usr/share/locale}, but on Solaris it is @code{/usr/lib/locale}.
The @code{gettext} module does not try to support these system dependent
defaults; instead its default is @code{`sys.base_prefix'/share/locale} (see
@ref{3e6,,sys.base_prefix}). For this reason, it is always best to call
@ref{3c1b,,bindtextdomain()} with an explicit absolute path at the start of your
application.
}
@end deffn

@geindex textdomain() (dans le module gettext)
@anchor{library/gettext gettext textdomain}@anchor{3c1c}
@deffn {Fonction} gettext.textdomain (domain=None)

Change ou interroge le domaine global actuel.  Si `domain' vaut @code{None}, alors le domaine global actuel est renvoyé.  Sinon, le domaine global est positionné à `domain', puis renvoyé.
@end deffn

@geindex _ (underscore);gettext

@geindex gettext() (dans le module gettext)
@anchor{library/gettext gettext gettext}@anchor{141d}
@deffn {Fonction} gettext.gettext (message)

Return the localized translation of `message', based on the current global
domain, language, and locale directory.  This function is usually aliased as
@code{_()} in the local namespace (see examples below).
@end deffn

@geindex dgettext() (dans le module gettext)
@anchor{library/gettext gettext dgettext}@anchor{3c1d}
@deffn {Fonction} gettext.dgettext (domain, message)

Comme @ref{141d,,gettext()}, mais cherche le message dans le domaine spécifié.
@end deffn

@geindex ngettext() (dans le module gettext)
@anchor{library/gettext gettext ngettext}@anchor{3c1e}
@deffn {Fonction} gettext.ngettext (singular, plural, n)

Comme @ref{141d,,gettext()}, mais prend en compte les formes au pluriel.  Si une traduction a été trouvée, utilise la formule pour trouver le pluriel à `n' et renvoie le message généré (quelques langues ont plus de deux formes au pluriel).  Si aucune traduction n'a été trouvée, renvoie `singular' si `n' vaut 1, `plural' sinon.

La formule pour trouver le pluriel est récupérée dans l'entête du catalogue.  C'est une expression en C ou en Python qui a une variable libre `n' et qui évalue l'index du pluriel dans le catalogue.  Voir la documentation de GNU gettext@footnote{https://www.gnu.org/software/gettext/manual/gettext.html} pour la syntaxe précise à utiliser dans les fichiers @code{.po} et pour les formules dans différents langues.
@end deffn

@geindex dngettext() (dans le module gettext)
@anchor{library/gettext gettext dngettext}@anchor{3c1f}
@deffn {Fonction} gettext.dngettext (domain, singular, plural, n)

Comme @ref{3c1e,,ngettext()}, mais cherche le message dans le domaine spécifié.
@end deffn

@geindex pgettext() (dans le module gettext)
@anchor{library/gettext gettext pgettext}@anchor{9e3}
@deffn {Fonction} gettext.pgettext (context, message)
@end deffn

@geindex dpgettext() (dans le module gettext)
@anchor{library/gettext gettext dpgettext}@anchor{3c20}
@deffn {Fonction} gettext.dpgettext (domain, context, message)
@end deffn

@geindex npgettext() (dans le module gettext)
@anchor{library/gettext gettext npgettext}@anchor{3c21}
@deffn {Fonction} gettext.npgettext (context, singular, plural, n)
@end deffn

@geindex dnpgettext() (dans le module gettext)
@anchor{library/gettext gettext dnpgettext}@anchor{3c22}
@deffn {Fonction} gettext.dnpgettext (domain, context, singular, plural, n)

Semblable aux fonctions correspondantes sans le @code{p} dans le préfixe (c'est-à-dire @ref{62,,gettext()}, @ref{3c1d,,dgettext()}, @ref{3c1e,,ngettext()} et @ref{3c1f,,dngettext()}), mais la traduction est limitée au `context' du message donné.


Ajouté dans la version 3.8.

@end deffn

Note that GNU @code{gettext} also defines a @code{dcgettext()} method, but
this was deemed not useful and so it is currently unimplemented.

Voici un exemple classique d'utilisation de cette API :

@example
import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print(_('This is a translatable string.'))
@end example

@node API basée sur les classes,Internationaliser vos programmes et modules,API GNU gettext,gettext --- Multilingual internationalization services
@anchor{library/gettext class-based-api}@anchor{3c23}
@subsubsection API basée sur les classes


The class-based API of the @ref{62,,gettext} module gives you more flexibility and
greater convenience than the GNU @code{gettext} API.  It is the recommended
way of localizing your Python applications and modules.  @code{gettext} defines
a @ref{3c24,,GNUTranslations} class which implements the parsing of GNU @code{.mo} format
files, and has methods for returning strings. Instances of this class can also
install themselves in the built-in namespace as the function @code{_()}.

@geindex find() (dans le module gettext)
@anchor{library/gettext gettext find}@anchor{3c25}
@deffn {Fonction} gettext.find (domain, localedir=None, languages=None, all=False)

Cette fonction implémente l'algorithme standard de recherche de fichier @code{mo}. Il prend en entrée un `domain', tout comme la fonction @ref{3c1c,,textdomain()}. Le paramètre optionnel `localedir' est le même que celui de @ref{3c1b,,bindtextdomain()}. Le paramètre optionnel `langages' est une liste de chaînes de caractères correspondants au code d'une langue.

Si `localedir' n'est pas renseigné, alors le répertoire de la locale par défaut du système est utilisé. @footnote{
Voir la note de @ref{3c1b,,bindtextdomain()} ci-dessus.
}  Si `languages' n'est pas renseigné, alors les variables d'environnement suivantes sont utilisées : 
@geindex LANGUAGE
@geindex variable d'environnement; LANGUAGE
@code{LANGUAGE}, 
@geindex LC_ALL
@geindex variable d'environnement; LC_ALL
@code{LC_ALL}, 
@geindex LC_MESSAGES
@geindex variable d'environnement; LC_MESSAGES
@code{LC_MESSAGES} et 
@geindex LANG
@geindex variable d'environnement; LANG
@code{LANG}.  La première à renvoyer une valeur non vide est alors utilisée pour `languages'.  Ces variables d'environnement doivent contenir une liste de langues, séparées par des deux-points, qui sera utilisée pour générer la liste des codes de langues attendue.

Recherche avec @ref{3c25,,find()}, découvre et normalise les langues, puis itère sur la liste obtenue afin de trouver un fichier de traduction existant et correspondant :

@code{`localedir'/`language'/LC_MESSAGES/`domain'.mo}

Le premier nom de fichier trouvé est renvoyé par @ref{3c25,,find()}.  Si aucun fichier n'a été trouvé, alors @code{None} est renvoyé.  Si `all' est vrai, est renvoyée la liste de tous les noms de fichiers, dans l'ordre dans lequel ils apparaissent dans `languages' ou dans les variables d'environnement.
@end deffn

@geindex translation() (dans le module gettext)
@anchor{library/gettext gettext translation}@anchor{a67}
@deffn {Fonction} gettext.translation (domain, localedir=None, languages=None, class_=None, fallback=False)

Return a @code{*Translations} instance based on the `domain', `localedir',
and `languages', which are first passed to @ref{3c25,,find()} to get a list of the
associated @code{.mo} file paths.  Instances with identical @code{.mo} file
names are cached.  The actual class instantiated is `class_' if
provided, otherwise @ref{3c24,,GNUTranslations}.  The class's constructor must
take a single @ref{11a0,,file object} argument.

Si plusieurs fichiers ont été trouvés, les derniers sont utilisés comme substitut des premiers.  Pour rendre possible cette substitution, @ref{51d,,copy.copy()} est utilisé pour copier chaque objet traduit depuis le cache ; les vraies données de l'instance étant toujours recopiées dans le cache.

Si aucun fichier @code{.mo} n'a été trouvé, soit `fallback' vaut `False' (valeur par défaut) et une exception @ref{40d,,OSError} est levée, soit `fallback' vaut `True' et une instance @ref{3c26,,NullTranslations} est renvoyée.


Modifié dans la version 3.3: @ref{103b,,IOError} used to be raised, it is now an alias of @ref{40d,,OSError}.



Modifié dans la version 3.11: `codeset' parameter is removed.

@end deffn

@geindex install() (dans le module gettext)
@anchor{library/gettext gettext install}@anchor{a68}
@deffn {Fonction} gettext.install (domain, localedir=None, *, names=None)

This installs the function @code{_()} in Python's builtins namespace, based on
`domain' and `localedir' which are passed to the function @ref{a67,,translation()}.

Concernant le paramètre `names', se référer à la description de la méthode @ref{3c27,,install()}.

As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the @code{_()}
function, like this:

@example
print(_('This string will be translated.'))
@end example

For convenience, you want the @code{_()} function to be installed in Python's
builtins namespace, so it is easily accessible in all modules of your
application.


Modifié dans la version 3.11: `names' est désormais un paramètre à mot-clé uniquement.

@end deffn

@menu
* La classe NullTranslations:: 
* La classe GNUTranslations:: 
* Support du catalogue de message de Solaris:: 
* Le constructeur Catalog:: 

@end menu

@node La classe NullTranslations,La classe GNUTranslations,,API basée sur les classes
@anchor{library/gettext the-nulltranslations-class}@anchor{3c28}
@subsubsection La classe @code{NullTranslations}


Les classes de traduction implémentent le fait de passer d'une chaîne de caractères du fichier original à traduire à la traduction de celle-ci.  La classe de base utilisée est @ref{3c26,,NullTranslations}.  C'est l'interface de base à utiliser lorsque vous souhaitez écrire vos propres classes spécifiques à la traduction.  Voici les méthodes de @code{NullTranslations} :

@geindex NullTranslations (classe dans gettext)
@anchor{library/gettext gettext NullTranslations}@anchor{3c26}
@deffn {Classe} gettext.NullTranslations (fp=None)

Prend un paramètre optionnel un @ref{11a0,,file object} `fp', qui est ignoré par la classe de base.  Initialise les variables d'instance "protégées" `_info' et `_chardet', définies par des classes dérivées, tout comme `_fallback' qui est définie au travers de @ref{3c29,,add_fallback()}.  Puis appelle @code{self._parse(fp)} si `fp' ne vaut pas @code{None}.

@geindex _parse() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations _parse}@anchor{3c2a}
@deffn {Méthode} _parse (fp)

Cette méthode, non exécutée dans la classe de base, prend en paramètre un objet fichier `fp' et lit les données de ce dernier.  Si vous avez un catalogue de messages dont le format n'est pas pris en charge, vous devriez surcharger cette méthode pour analyser votre format.
@end deffn

@geindex add_fallback() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations add_fallback}@anchor{3c29}
@deffn {Méthode} add_fallback (fallback)

Ajoute `fallback' comme objet de substitution pour l'objet de traduction courant.  Un objet de traduction devrait interroger cet objet de substitution s'il ne peut fournir une traduction pour un message donné.
@end deffn

@geindex gettext() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations gettext}@anchor{3c2b}
@deffn {Méthode} gettext (message)

Si un objet de substitution a été défini, transmet @code{gettext()} à celui-ci.  Sinon, renvoie `message'.  Surchargé dans les classes dérivées.
@end deffn

@geindex ngettext() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations ngettext}@anchor{3c2c}
@deffn {Méthode} ngettext (singular, plural, n)

Si un objet de substitution a été défini, transmet @code{ngettext()} à celui-ci.  Sinon, renvoie `singular' si `n' vaut 1, `plural' sinon.  Surchargé dans les classes dérivées.
@end deffn

@geindex pgettext() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations pgettext}@anchor{3c2d}
@deffn {Méthode} pgettext (context, message)

Si un objet de substitution a été défini, transmet @ref{9e3,,pgettext()} à celui-ci. Sinon, renvoie le message traduit. Surchargé dans les classes dérivées.


Ajouté dans la version 3.8.

@end deffn

@geindex npgettext() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations npgettext}@anchor{3c2e}
@deffn {Méthode} npgettext (context, singular, plural, n)

Si un objet de substitution a été défini, transmet @ref{3c21,,npgettext()} à celui-ci. Sinon, renvoie le message traduit. Surchargé dans les classes dérivées.


Ajouté dans la version 3.8.

@end deffn

@geindex info() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations info}@anchor{3c2f}
@deffn {Méthode} info ()

Return a dictionary containing
the metadata found in the message catalog file.
@end deffn

@geindex charset() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations charset}@anchor{3c30}
@deffn {Méthode} charset ()

Renvoie l'encodage du fichier du catalogue de messages.
@end deffn

@geindex install() (méthode gettext.NullTranslations)
@anchor{library/gettext gettext NullTranslations install}@anchor{3c27}
@deffn {Méthode} install (names=None)

Cette méthode positionne @ref{3c2b,,gettext()} dans l'espace de nommage natif, en le liant à @code{_}.

If the `names' parameter is given, it must be a sequence containing the
names of functions you want to install in the builtins namespace in
addition to @code{_()}.  Supported names are @code{'gettext'}, @code{'ngettext'},
@code{'pgettext'}, and @code{'npgettext'}.

Note that this is only one way, albeit the most convenient way, to make
the @code{_()} function available to your application.  Because it affects
the entire application globally, and specifically the built-in namespace,
localized modules should never install @code{_()}. Instead, they should use
this code to make @code{_()} available to their module:

@example
import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext
@end example

This puts @code{_()} only in the module's global namespace and so only
affects calls within this module.


Modifié dans la version 3.8: Ajout de @code{'pgettext'} et @code{'npgettext'}.

@end deffn
@end deffn

@node La classe GNUTranslations,Support du catalogue de message de Solaris,La classe NullTranslations,API basée sur les classes
@anchor{library/gettext the-gnutranslations-class}@anchor{3c31}
@subsubsection La classe @code{GNUTranslations}


The @code{gettext} module provides one additional class derived from
@ref{3c26,,NullTranslations}: @ref{3c24,,GNUTranslations}.  This class overrides
@code{_parse()} to enable reading GNU @code{gettext} format @code{.mo} files
in both big-endian and little-endian format.

@ref{3c24,,GNUTranslations} parses optional metadata out of the translation
catalog. It is convention with GNU @code{gettext} to include metadata as
the translation for the empty string. This metadata is in 
@geindex RFC; RFC 822
RFC 822@footnote{https://datatracker.ietf.org/doc/html/rfc822.html}-style
@code{key: value} pairs, and should contain the @code{Project-Id-Version} key.  If the
key @code{Content-Type} is found, then the @code{charset} property is used to
initialize the "protected" @code{_charset} instance variable, defaulting to
@code{None} if not found.  If the charset encoding is specified, then all message
ids and message strings read from the catalog are converted to Unicode using
this encoding, else ASCII is assumed.

Since message ids are read as Unicode strings too, all @code{*gettext()} methods
will assume message ids as Unicode strings, not byte strings.

The entire set of key/value pairs are placed into a dictionary and set as the
"protected" @code{_info} instance variable.

Si le nombre magique du fichier @code{.mo} est invalide, le numéro de la version majeure inattendu, ou si d'autres problèmes apparaissent durant la lecture du fichier, instancier une classe @ref{3c24,,GNUTranslations} peut lever une exception @ref{40d,,OSError}.

@geindex GNUTranslations (classe dans gettext)
@anchor{library/gettext gettext GNUTranslations}@anchor{3c24}
@deffn {Classe} gettext.GNUTranslations

Les méthodes suivantes, provenant de l'implémentation de la classe de base, ont été surchargée :

@geindex gettext() (méthode gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations gettext}@anchor{3c32}
@deffn {Méthode} gettext (message)

Recherche l'identifiant de `message' dans le catalogue et renvoie le message de la chaîne de caractères correspondante comme une chaîne Unicode.  Si aucun identifiant n'a été trouvé pour `message' et qu'un substitut a été défini, la recherche est transmise à la méthode @ref{3c2b,,gettext()} du substitut.  Sinon, l'identifiant de `message' est renvoyé.
@end deffn

@geindex ngettext() (méthode gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations ngettext}@anchor{3c33}
@deffn {Méthode} ngettext (singular, plural, n)

Effectue une recherche sur les formes plurielles de l'identifiant d'un message.  `singular' est utilisé pour la recherche de l'identifiant dans le catalogue, alors que `n' permet de savoir quelle forme plurielle utiliser.  La chaîne de caractère du message renvoyée est une chaîne Unicode.

Si l'identifiant du message n'est pas trouvé dans le catalogue et qu'un substitut a été spécifié, la requête est transmise à la méthode @ref{3c2c,,ngettext()} du substitut.  Sinon, est renvoyé `singular' lorsque `n' vaut 1, `plural' dans tous les autres cas.

Voici un exemple :

@example
n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ngettext(
    'There is %(num)d file in this directory',
    'There are %(num)d files in this directory',
    n) % @{'num': n@}
@end example
@end deffn

@geindex pgettext() (méthode gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations pgettext}@anchor{3c34}
@deffn {Méthode} pgettext (context, message)

Recherche le `contexte' et l'identifiant de `message' dans le catalogue et renvoie le message de la chaîne de caractères correspondante comme une chaîne Unicode. Si aucun identifiant n'a été trouvé pour l'identifiant du `message' et du `context' et qu'un substitut a été défini, la recherche est transmise à la méthode @ref{9e3,,pgettext()} du substitut. Sinon, l'identifiant de `message' est renvoyé.


Ajouté dans la version 3.8.

@end deffn

@geindex npgettext() (méthode gettext.GNUTranslations)
@anchor{library/gettext gettext GNUTranslations npgettext}@anchor{3c35}
@deffn {Méthode} npgettext (context, singular, plural, n)

Effectue une recherche sur les formes plurielles de l'identifiant d'un message. `singular' est utilisé pour la recherche de l'identifiant dans le catalogue, alors que `n' permet de savoir quelle forme plurielle utiliser.

Si l'identifiant du message pour le `context' n'est pas trouvé dans le catalogue et qu'un substitut a été spécifié, la requête est transmise à la méthode @ref{3c21,,npgettext()} du substitut. Sinon, est renvoyé `singular' lorsque `n' vaut 1, `plural' dans tous les autres cas.


Ajouté dans la version 3.8.

@end deffn
@end deffn

@node Support du catalogue de message de Solaris,Le constructeur Catalog,La classe GNUTranslations,API basée sur les classes
@anchor{library/gettext solaris-message-catalog-support}@anchor{3c36}
@subsubsection Support du catalogue de message de Solaris


Le système d'exploitation Solaris possède son propre format de fichier binaire @code{.mo}, mais pour l'heure, puisqu'on ne peut trouver de documentation sur ce format, il n'est pas géré.

@node Le constructeur Catalog,,Support du catalogue de message de Solaris,API basée sur les classes
@anchor{library/gettext the-catalog-constructor}@anchor{3c37}
@subsubsection Le constructeur `Catalog'


@geindex GNOME

GNOME utilise une version du module @ref{62,,gettext} de James Henstridge, mais qui a une API légèrement différente.  D'après la documentation, elle s'utilise ainsi :

@example
import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print(_('hello world'))
@end example

For compatibility with this older module, the function @code{Catalog()} is an
alias for the @ref{a67,,translation()} function described above.

Une différence entre ce module et celui de Henstridge : les objets de son catalogue étaient accessibles depuis un schéma de l'API, mais cela semblait ne pas être utilisé et donc n'est pas pris en charge.

@node Internationaliser vos programmes et modules,Remerciements<9>,API basée sur les classes,gettext --- Multilingual internationalization services
@anchor{library/gettext i18n-howto}@anchor{2e31}@anchor{library/gettext internationalizing-your-programs-and-modules}@anchor{3c38}
@subsubsection Internationaliser vos programmes et modules


L'internationalisation (`I18N') consiste à permettre à un programme de recevoir des traductions dans plusieurs langues.  La localisation (`L10N') consiste à adapter un programme à la langue et aux habitudes culturelles locales, une fois celui-ci internationalisé.  Afin de fournir du texte multilingue à votre programme Python, les étapes suivantes sont nécessaires :


@enumerate 

@item 
préparer votre programme ou module en marquant spécifiquement les chaînes à traduire

@item 
lancer une suite d'outils sur les fichiers contenant des chaînes à traduire pour générer des catalogues de messages brut

@item 
créer les traductions spécifiques à une langue des catalogues de messages

@item 
utiliser le module @ref{62,,gettext} pour que les chaînes de caractères soient bien traduites
@end enumerate

In order to prepare your code for I18N, you need to look at all the strings in
your files.  Any string that needs to be translated should be marked by wrapping
it in @code{_('...')} --- that is, a call to the function @ref{62,,_}.  For example:

@example
filename = 'mylog.txt'
message = _('writing a log message')
with open(filename, 'w') as fp:
    fp.write(message)
@end example

Dans cet exemple, la chaîne @code{'writing a log message'} est maquée comme traduite, contrairement aux chaînes @code{'mylog.txt'} et @code{'w'}.

There are a few tools to extract the strings meant for translation.
The original GNU @code{gettext} only supported C or C++ source
code but its extended version @code{xgettext} scans code written
in a number of languages, including Python, to find strings marked as
translatable.  Babel@footnote{https://babel.pocoo.org/} is a Python
internationalization library that includes a @code{pybabel} script to
extract and compile message catalogs.  François Pinard's program
called @code{xpot} does a similar job and is available as part of
his po-utils package@footnote{https://github.com/pinard/po-utils}.

(Python inclut également des versions en Python de ces programmes, @code{pygettext.py} et @code{msgfmt.py}, que certaines distributions Python installeront pour vous.  @code{pygettext.py} est similaire à @code{xgettext}, mais ne comprend que le code source écrit en Python et ne peut prendre en charge d'autres langages de programmation tels que le C ou C++.  @code{pygettext.py} possède une interface en ligne de commande similaire à celle de @code{xgettext} --- pour plus de détails sur son utilisation, exécuter @code{pygettext.py --help}.  @code{msgfmt.py} est compatible avec GNU @code{msgfmt}.  Avec ces deux programmes, vous ne devriez pas avoir besoin du paquet GNU @code{gettext} pour internationaliser vos applications en Python.)

@code{xgettext}, @code{pygettext} et d'autres outils similaires génèrent des fichiers @code{.po} représentant les catalogues de messages.  Il s'agit de fichiers structurés et lisibles par un être humain, qui contiennent toutes les chaînes du code source marquées comme traduisible, ainsi que leur traduction à utiliser.

Les copies de ces fichiers @code{.po} sont ensuite remises à des êtres humains qui traduisent le contenu pour chaque langue naturelle prise en charge.  Pour chacune des langues, ces derniers renvoient la version complétée sous la forme d'un fichier @code{<code-langue>.po} qui a été compilé dans un fichier binaire @code{.mo} représentant le catalogue lisible par une machine à l'aide du programme @code{msgfmt}.  Les fichiers @code{.mo} sont utilisés par le module @ref{62,,gettext} pour la traduction lors de l'exécution.

La façon dont vous utilisez le module @ref{62,,gettext} dans votre code dépend de si vous internationalisez un seul module ou l'ensemble de votre application.  Les deux sections suivantes traitent chacune des cas.

@menu
* Localiser votre module:: 
* Localiser votre application:: 
* Changer de langue à la volée:: 
* Traductions différées:: 

@end menu

@node Localiser votre module,Localiser votre application,,Internationaliser vos programmes et modules
@anchor{library/gettext localizing-your-module}@anchor{3c39}
@subsubsection Localiser votre module


Si vous localisez votre module, veillez à ne pas faire de changements globaux, e.g. dans l'espace de nommage natif. Vous ne devriez pas utiliser l’API GNU @code{gettext} mais plutôt celle basée sur les classes.

Disons que votre module s'appelle "spam" et que les fichiers @code{.mo} de traduction dans les différentes langues naturelles soient dans @code{/usr/share/locale} au format GNU @code{gettext}.  Voici ce que vous pouvez alors mettre en haut de votre module :

@example
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext
@end example

@node Localiser votre application,Changer de langue à la volée,Localiser votre module,Internationaliser vos programmes et modules
@anchor{library/gettext localizing-your-application}@anchor{3c3a}
@subsubsection Localiser votre application


If you are localizing your application, you can install the @code{_()} function
globally into the built-in namespace, usually in the main driver file of your
application.  This will let all your application-specific files just use
@code{_('...')} without having to explicitly install it in each file.

Dans ce cas, vous n'aurez à ajouter que le bout de code suivant au fichier principal de votre application :

@example
import gettext
gettext.install('myapplication')
@end example

Si vous avez besoin de définir le dossier des localisations, vous pouvez le mettre en argument de la fonction @ref{a68,,install()} :

@example
import gettext
gettext.install('myapplication', '/usr/share/locale')
@end example

@node Changer de langue à la volée,Traductions différées,Localiser votre application,Internationaliser vos programmes et modules
@anchor{library/gettext changing-languages-on-the-fly}@anchor{3c3b}
@subsubsection Changer de langue à la volée


Si votre programme a besoin de prendre en charge plusieurs langues en même temps, vous pouvez créer plusieurs instances de traduction, puis basculer entre elles de façon explicite, comme ceci :

@example
import gettext

lang1 = gettext.translation('myapplication', languages=['en'])
lang2 = gettext.translation('myapplication', languages=['fr'])
lang3 = gettext.translation('myapplication', languages=['de'])

# start by using language1
lang1.install()

# ... time goes by, user selects language 2
lang2.install()

# ... more time goes by, user selects language 3
lang3.install()
@end example

@node Traductions différées,,Changer de langue à la volée,Internationaliser vos programmes et modules
@anchor{library/gettext deferred-translations}@anchor{3c3c}
@subsubsection Traductions différées


Dans la plupart des cas, en programmation, les chaînes de caractères sont traduites à l'endroit où on les écrit.  Cependant, il peut arriver que vous ayez besoin de traduire une chaîne de caractères un peu plus loin.  Un exemple classique est :

@example
animals = ['mollusk',
           'albatross',
           'rat',
           'penguin',
           'python', ]
# ...
for a in animals:
    print(a)
@end example

Ici, vous voulez marquer les chaînes de caractères de la liste @code{animals} comme étant traduisibles, mais ne les traduire qu'au moment de les afficher.

Voici un moyen de gérer ce cas :

@example
def _(message): return message

animals = [_('mollusk'),
           _('albatross'),
           _('rat'),
           _('penguin'),
           _('python'), ]

del _

# ...
for a in animals:
    print(_(a))
@end example

This works because the dummy definition of @code{_()} simply returns the string
unchanged.  And this dummy definition will temporarily override any definition
of @code{_()} in the built-in namespace (until the @ref{1734,,del} command). Take
care, though if you have a previous definition of @code{_()} in the local
namespace.

Note that the second use of @code{_()} will not identify "a" as being
translatable to the @code{gettext} program, because the parameter
is not a string literal.

Voici une autre solution :

@example
def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print(_(a))
@end example

In this case, you are marking translatable strings with the function
@code{N_()}, which won't conflict with any definition of @code{_()}.
However, you will need to teach your message extraction program to
look for translatable strings marked with @code{N_()}. @code{xgettext},
@code{pygettext}, @code{pybabel extract}, and @code{xpot} all
support this through the use of the @code{-k} command-line switch.
The choice of @code{N_()} here is totally arbitrary; it could have just
as easily been @code{MarkThisStringForTranslation()}.

@node Remerciements<9>,,Internationaliser vos programmes et modules,gettext --- Multilingual internationalization services
@anchor{library/gettext acknowledgements}@anchor{3c3d}
@subsubsection Remerciements


Les personnes suivantes ont contribué au code, ont fait des retours, ont participé aux suggestions de conception et aux implémentations précédentes, et ont partagé leur expérience précieuse pour la création de ce module :


@itemize *

@item 
Peter Funk

@item 
James Henstridge

@item 
Juan David Ibáñez Palomar

@item 
Marc-André Lemburg

@item 
Martin von Löwis

@item 
François Pinard

@item 
Barry Warsaw

@item 
Gustavo Niemeyer
@end itemize

@subsubheading Notes


@node locale --- Internationalization services,,gettext --- Multilingual internationalization services,Internationalisation
@anchor{library/locale doc}@anchor{3c3e}@anchor{library/locale locale-internationalization-services}@anchor{3c3f}@anchor{library/locale module-locale}@anchor{85}
@subsection @code{locale} --- Internationalization services


@geindex module; locale

`Source code:' Lib/locale.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/locale.py}


__________________________________________________________________


Le module @ref{85,,locale} donne accès à la base de données et aux fonctionnalités des paramètres linguistiques définis par POSIX. Le mécanisme des paramètres linguistiques de POSIX permet aux développeurs de faire face à certaines problématiques culturelles dans une application, sans avoir à connaître toutes les spécificités de chaque pays où le logiciel est exécuté.

@geindex module;_locale

The @ref{85,,locale} module is implemented on top of the @code{_locale} module,
which in turn uses an ANSI C locale implementation if available.

Le module @ref{85,,locale} définit l'exception et les fonctions suivantes :

@geindex Error
@anchor{library/locale locale Error}@anchor{3c40}
@deffn {Exception} locale.Error

Exception levée lorsque le paramètre régional passé en paramètre de @ref{2da,,setlocale()} n'est pas reconnu.
@end deffn

@geindex setlocale() (dans le module locale)
@anchor{library/locale locale setlocale}@anchor{2da}
@deffn {Fonction} locale.setlocale (category, locale=None)

Si `locale' ne vaut pas @code{None}, @ref{2da,,setlocale()} modifie le paramètre régional pour la catégorie `category'. Les catégories disponibles sont listées dans la description des données ci-dessous. `locale' peut être une chaîne de caractères ou un itérable de deux chaînes de caractères (code de la langue et encodage). Si c'est un itérable, il est converti en un nom de paramètre régional à l'aide du moteur de normalisation fait pour. Si c'est une chaîne vide, les paramètres par défaut de l'utilisateur sont utilisés. Si la modification du paramètre régional échoue, l'exception @ref{3c40,,Error} est levée. Si elle fonctionne, le nouveau paramètre est renvoyé.

Si `locale' est omis ou vaut @code{None}, le paramètre actuel de `category' est renvoyé.

@ref{2da,,setlocale()} n'est pas `thread-safe' sur la plupart des systèmes. Les applications commencent généralement par un appel de

@example
import locale
locale.setlocale(locale.LC_ALL, '@w{'})
@end example

Cela définit les paramètres régionaux dans toutes les catégories sur ceux par défaut de l'utilisateur (habituellement spécifiés dans la variable d'environnement 
@geindex LANG
@geindex variable d'environnement; LANG
@code{LANG}).  Si les paramètres régionaux ne sont pas modifiés par la suite, l'utilisation de fils d'exécution ne devrait pas poser de problèmes.
@end deffn

@geindex localeconv() (dans le module locale)
@anchor{library/locale locale localeconv}@anchor{bec}
@deffn {Fonction} locale.localeconv ()

Renvoie la base de données des conventions locales sous forme de dictionnaire. Ce dictionnaire a les chaînes de caractères suivantes comme clés :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Catégorie

@tab

Clé

@tab

Signification

@item

@ref{3c41,,LC_NUMERIC}

@tab

@code{'decimal_point'}

@tab

Caractère du séparateur décimal (entre la partie entière et la partie décimale).

@item

@tab

@code{'grouping'}

@tab

Séquence de nombres spécifiant les positions relatives attendues pour @code{'thousands_sep'} (séparateur de milliers).  Si la séquence se termine par @ref{3c42,,CHAR_MAX}, aucun autre regroupement n'est effectué. Si la séquence se termine par un @code{0},  la dernière taille du groupe est utilisée à plusieurs reprises.

@item

@tab

@code{'thousands_sep'}

@tab

Caractère utilisé entre les groupes (séparateur de milliers).

@item

@ref{3c43,,LC_MONETARY}

@tab

@code{'int_curr_symbol'}

@tab

Symbole monétaire international.

@item

@tab

@code{'currency_symbol'}

@tab

Symbole monétaire local.

@item

@tab

@code{'p_cs_precedes/n_cs_precedes'}

@tab

Si le symbole monétaire précède ou non la valeur (pour les valeurs positives et négatives, respectivement).

@item

@tab

@code{'p_sep_by_space/n_sep_by_space'}

@tab

Si le symbole monétaire est séparé de la valeur  par une espace ou non (pour les valeurs positives et négatives, respectivement).

@item

@tab

@code{'mon_decimal_point'}

@tab

Séparateur décimal (entre la partie entière et la partie décimale) utilisé pour les valeurs monétaires.

@item

@tab

@code{'frac_digits'}

@tab

Nombre de décimales utilisées dans le format local des valeurs monétaires.

@item

@tab

@code{'int_frac_digits'}

@tab

Nombre de décimales utilisées dans le format international des valeurs monétaires.

@item

@tab

@code{'mon_thousands_sep'}

@tab

Séparateur de groupe utilisé pour les valeurs monétaires.

@item

@tab

@code{'mon_grouping'}

@tab

Équivalent de @code{'grouping'}, utilisé pour les valeurs monétaires.

@item

@tab

@code{'positive_sign'}

@tab

Symbole utilisé pour indiquer qu'une valeur monétaire est positive.

@item

@tab

@code{'negative_sign'}

@tab

Symbole utilisé pour indiquer qu'une valeur monétaire est négative.

@item

@tab

@code{'p_sign_posn/n_sign_posn'}

@tab

Position du signe (pour les valeurs positives et négatives, respectivement), voir ci-dessous.

@end multitable


Toutes les valeurs numériques peuvent être définies à @ref{3c42,,CHAR_MAX} pour indiquer qu'il n'y a pas de valeur spécifiée pour ces paramètres régionaux.

Les valeurs possibles pour @code{'p_sign_posn'} et @code{'n_sign_posn'} sont données ci-dessous.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Explication

@item

@code{0}

@tab

Le symbole monétaire et la valeur sont entourés de parenthèses.

@item

@code{1}

@tab

Le signe doit précéder la valeur et le symbole monétaire.

@item

@code{2}

@tab

Le signe doit suivre la valeur et le symbole monétaire.

@item

@code{3}

@tab

Le signe doit précéder immédiatement la valeur.

@item

@code{4}

@tab

Le signe doit suivre immédiatement la valeur.

@item

@code{CHAR_MAX}

@tab

Rien n'est spécifié dans ces paramètres régionaux.

@end multitable


The function temporarily sets the @code{LC_CTYPE} locale to the @code{LC_NUMERIC}
locale or the @code{LC_MONETARY} locale if locales are different and numeric or
monetary strings are non-ASCII. This temporary change affects other threads.


Modifié dans la version 3.7: The function now temporarily sets the @code{LC_CTYPE} locale to the
@code{LC_NUMERIC} locale in some cases.

@end deffn

@geindex nl_langinfo() (dans le module locale)
@anchor{library/locale locale nl_langinfo}@anchor{3c44}
@deffn {Fonction} locale.nl_langinfo (option)

Renvoie quelques informations spécifiques aux paramètres régionaux sous forme de chaîne.  Cette fonction n'est pas disponible sur tous les systèmes et l'ensemble des options possibles peut également varier d'une plateforme à l'autre.  Les valeurs possibles pour les arguments sont des nombres, pour lesquels des constantes symboliques sont disponibles dans le module `locale'.

La fonction @ref{3c44,,nl_langinfo()} accepte l'une des clés suivantes.  La plupart des descriptions sont extraites des descriptions correspondantes dans la bibliothèque GNU C.

@geindex CODESET (dans le module locale)
@anchor{library/locale locale CODESET}@anchor{3c45}
@deffn {Données} locale.CODESET

Récupère une chaîne avec le nom de l'encodage des caractères utilisé par le paramètre régional sélectionné.
@end deffn

@geindex D_T_FMT (dans le module locale)
@anchor{library/locale locale D_T_FMT}@anchor{3c46}
@deffn {Données} locale.D_T_FMT

Récupère une chaîne qui peut être utilisée comme une chaîne de format par @ref{11c6,,time.strftime()} afin de représenter la date et l'heure pour un paramètre régional spécifique.
@end deffn

@geindex D_FMT (dans le module locale)
@anchor{library/locale locale D_FMT}@anchor{3c47}
@deffn {Données} locale.D_FMT

Récupère une chaîne qui peut être utilisée comme une chaîne de format par @ref{11c6,,time.strftime()} afin de représenter une date pour un paramètre régional spécifique.
@end deffn

@geindex T_FMT (dans le module locale)
@anchor{library/locale locale T_FMT}@anchor{3c48}
@deffn {Données} locale.T_FMT

Récupère une chaîne qui peut être utilisée comme une chaîne de format par @ref{11c6,,time.strftime()} afin de représenter une heure pour un paramètre régional spécifique.
@end deffn

@geindex T_FMT_AMPM (dans le module locale)
@anchor{library/locale locale T_FMT_AMPM}@anchor{3c49}
@deffn {Données} locale.T_FMT_AMPM

Récupère une chaîne de format pour @ref{11c6,,time.strftime()} afin de représenter l'heure au format am / pm.
@end deffn

@geindex DAY_1 (dans le module locale)
@geindex DAY_2 (dans le module locale)
@geindex DAY_3 (dans le module locale)
@geindex DAY_4 (dans le module locale)
@geindex DAY_5 (dans le module locale)
@geindex DAY_6 (dans le module locale)
@geindex DAY_7 (dans le module locale)
@anchor{library/locale locale DAY_1}@anchor{3c4a}
@deffn {Données} locale.DAY_1
@anchor{library/locale locale DAY_2}@anchor{3c4b}
@deffnx {Données} locale.DAY_2
@anchor{library/locale locale DAY_3}@anchor{3c4c}
@deffnx {Données} locale.DAY_3
@anchor{library/locale locale DAY_4}@anchor{3c4d}
@deffnx {Données} locale.DAY_4
@anchor{library/locale locale DAY_5}@anchor{3c4e}
@deffnx {Données} locale.DAY_5
@anchor{library/locale locale DAY_6}@anchor{3c4f}
@deffnx {Données} locale.DAY_6
@anchor{library/locale locale DAY_7}@anchor{3c50}
@deffnx {Données} locale.DAY_7

Récupère le nom du n-ième jour de la semaine.

@cartouche
@quotation Note 
Cela suit la convention américaine qui définit @ref{3c4a,,DAY_1} comme étant dimanche, et non la convention internationale (ISO 8601) où lundi est le premier jour de la semaine.
@end quotation
@end cartouche
@end deffn

@geindex ABDAY_1 (dans le module locale)
@geindex ABDAY_2 (dans le module locale)
@geindex ABDAY_3 (dans le module locale)
@geindex ABDAY_4 (dans le module locale)
@geindex ABDAY_5 (dans le module locale)
@geindex ABDAY_6 (dans le module locale)
@geindex ABDAY_7 (dans le module locale)
@anchor{library/locale locale ABDAY_1}@anchor{3c51}
@deffn {Données} locale.ABDAY_1
@anchor{library/locale locale ABDAY_2}@anchor{3c52}
@deffnx {Données} locale.ABDAY_2
@anchor{library/locale locale ABDAY_3}@anchor{3c53}
@deffnx {Données} locale.ABDAY_3
@anchor{library/locale locale ABDAY_4}@anchor{3c54}
@deffnx {Données} locale.ABDAY_4
@anchor{library/locale locale ABDAY_5}@anchor{3c55}
@deffnx {Données} locale.ABDAY_5
@anchor{library/locale locale ABDAY_6}@anchor{3c56}
@deffnx {Données} locale.ABDAY_6
@anchor{library/locale locale ABDAY_7}@anchor{3c57}
@deffnx {Données} locale.ABDAY_7

Récupère l'abréviation du n-ième jour de la semaine.
@end deffn

@geindex MON_1 (dans le module locale)
@geindex MON_2 (dans le module locale)
@geindex MON_3 (dans le module locale)
@geindex MON_4 (dans le module locale)
@geindex MON_5 (dans le module locale)
@geindex MON_6 (dans le module locale)
@geindex MON_7 (dans le module locale)
@geindex MON_8 (dans le module locale)
@geindex MON_9 (dans le module locale)
@geindex MON_10 (dans le module locale)
@geindex MON_11 (dans le module locale)
@geindex MON_12 (dans le module locale)
@anchor{library/locale locale MON_1}@anchor{3c58}
@deffn {Données} locale.MON_1
@anchor{library/locale locale MON_2}@anchor{3c59}
@deffnx {Données} locale.MON_2
@anchor{library/locale locale MON_3}@anchor{3c5a}
@deffnx {Données} locale.MON_3
@anchor{library/locale locale MON_4}@anchor{3c5b}
@deffnx {Données} locale.MON_4
@anchor{library/locale locale MON_5}@anchor{3c5c}
@deffnx {Données} locale.MON_5
@anchor{library/locale locale MON_6}@anchor{3c5d}
@deffnx {Données} locale.MON_6
@anchor{library/locale locale MON_7}@anchor{3c5e}
@deffnx {Données} locale.MON_7
@anchor{library/locale locale MON_8}@anchor{3c5f}
@deffnx {Données} locale.MON_8
@anchor{library/locale locale MON_9}@anchor{3c60}
@deffnx {Données} locale.MON_9
@anchor{library/locale locale MON_10}@anchor{3c61}
@deffnx {Données} locale.MON_10
@anchor{library/locale locale MON_11}@anchor{3c62}
@deffnx {Données} locale.MON_11
@anchor{library/locale locale MON_12}@anchor{3c63}
@deffnx {Données} locale.MON_12

Récupère le nom du n-ième mois.
@end deffn

@geindex ABMON_1 (dans le module locale)
@geindex ABMON_2 (dans le module locale)
@geindex ABMON_3 (dans le module locale)
@geindex ABMON_4 (dans le module locale)
@geindex ABMON_5 (dans le module locale)
@geindex ABMON_6 (dans le module locale)
@geindex ABMON_7 (dans le module locale)
@geindex ABMON_8 (dans le module locale)
@geindex ABMON_9 (dans le module locale)
@geindex ABMON_10 (dans le module locale)
@geindex ABMON_11 (dans le module locale)
@geindex ABMON_12 (dans le module locale)
@anchor{library/locale locale ABMON_1}@anchor{3c64}
@deffn {Données} locale.ABMON_1
@anchor{library/locale locale ABMON_2}@anchor{3c65}
@deffnx {Données} locale.ABMON_2
@anchor{library/locale locale ABMON_3}@anchor{3c66}
@deffnx {Données} locale.ABMON_3
@anchor{library/locale locale ABMON_4}@anchor{3c67}
@deffnx {Données} locale.ABMON_4
@anchor{library/locale locale ABMON_5}@anchor{3c68}
@deffnx {Données} locale.ABMON_5
@anchor{library/locale locale ABMON_6}@anchor{3c69}
@deffnx {Données} locale.ABMON_6
@anchor{library/locale locale ABMON_7}@anchor{3c6a}
@deffnx {Données} locale.ABMON_7
@anchor{library/locale locale ABMON_8}@anchor{3c6b}
@deffnx {Données} locale.ABMON_8
@anchor{library/locale locale ABMON_9}@anchor{3c6c}
@deffnx {Données} locale.ABMON_9
@anchor{library/locale locale ABMON_10}@anchor{3c6d}
@deffnx {Données} locale.ABMON_10
@anchor{library/locale locale ABMON_11}@anchor{3c6e}
@deffnx {Données} locale.ABMON_11
@anchor{library/locale locale ABMON_12}@anchor{3c6f}
@deffnx {Données} locale.ABMON_12

Récupère l'abréviation du n-ième mois.
@end deffn

@geindex RADIXCHAR (dans le module locale)
@anchor{library/locale locale RADIXCHAR}@anchor{3c70}
@deffn {Données} locale.RADIXCHAR

Récupère le caractère de séparation `radix' (point décimal, virgule décimale, etc.).
@end deffn

@geindex THOUSEP (dans le module locale)
@anchor{library/locale locale THOUSEP}@anchor{3c71}
@deffn {Données} locale.THOUSEP

Récupère le caractère de séparation des milliers (groupes de 3 chiffres).
@end deffn

@geindex YESEXPR (dans le module locale)
@anchor{library/locale locale YESEXPR}@anchor{3c72}
@deffn {Données} locale.YESEXPR

Récupère une expression régulière qui peut être utilisée par la fonction `regex' pour reconnaître une réponse positive à une question fermée (oui / non).
@end deffn

@geindex NOEXPR (dans le module locale)
@anchor{library/locale locale NOEXPR}@anchor{3c73}
@deffn {Données} locale.NOEXPR

Get a regular expression that can be used with the @code{regex(3)} function to
recognize a negative response to a yes/no question.

@cartouche
@quotation Note 
The regular expressions for @ref{3c72,,YESEXPR} and
@ref{3c73,,NOEXPR} use syntax suitable for the
@code{regex} function from the C library, which might
differ from the syntax used in @ref{b8,,re}.
@end quotation
@end cartouche
@end deffn

@geindex CRNCYSTR (dans le module locale)
@anchor{library/locale locale CRNCYSTR}@anchor{3c74}
@deffn {Données} locale.CRNCYSTR

Récupère le symbole monétaire, précédé de « - » si le symbole doit apparaître avant la valeur, « + » s'il doit apparaître après la valeur, ou « . » s'il doit remplacer le caractère de séparation `radix'.
@end deffn

@geindex ERA (dans le module locale)
@anchor{library/locale locale ERA}@anchor{3c75}
@deffn {Données} locale.ERA

Get a string which describes how years are counted and displayed for
each era in a locale.

La plupart des paramètres régionaux ne définissent pas cette valeur.  Un exemple de région qui définit bien cette valeur est le japonais.  Au Japon, la représentation traditionnelle des dates comprend le nom de l'ère correspondant au règne de l'empereur de l'époque.

Normally it should not be necessary to use this value directly. Specifying
the @code{E} modifier in their format strings causes the @ref{11c6,,time.strftime()}
function to use this information.
The format of the returned string is specified in `The Open Group Base
Specifications Issue 8', paragraph 7.3.5.2 LC_TIME C-Language Access@footnote{https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap07.html#tag_07_03_05_02}.
@end deffn

@geindex ERA_D_T_FMT (dans le module locale)
@anchor{library/locale locale ERA_D_T_FMT}@anchor{3c76}
@deffn {Données} locale.ERA_D_T_FMT

Récupère la chaîne de format pour @ref{11c6,,time.strftime()} afin de représenter la date et l'heure pour un paramètre régional spécifique basée sur une ère.
@end deffn

@geindex ERA_D_FMT (dans le module locale)
@anchor{library/locale locale ERA_D_FMT}@anchor{3c77}
@deffn {Données} locale.ERA_D_FMT

Récupère la chaîne de format pour @ref{11c6,,time.strftime()} afin de représenter une date pour un paramètre régional spécifique basée sur une ère.
@end deffn

@geindex ERA_T_FMT (dans le module locale)
@anchor{library/locale locale ERA_T_FMT}@anchor{3c78}
@deffn {Données} locale.ERA_T_FMT

Récupère la chaîne de format pour @ref{11c6,,time.strftime()} afin de représenter une heure pour un paramètre régional spécifique basée sur une ère.
@end deffn

@geindex ALT_DIGITS (dans le module locale)
@anchor{library/locale locale ALT_DIGITS}@anchor{3c79}
@deffn {Données} locale.ALT_DIGITS

Get a string consisting of up to 100 semicolon-separated symbols used
to represent the values 0 to 99 in a locale-specific way.
In most locales this is an empty string.
@end deffn
@end deffn

@geindex getdefaultlocale() (dans le module locale)
@anchor{library/locale locale getdefaultlocale}@anchor{2d8}
@deffn {Fonction} locale.getdefaultlocale ([envvars])

Tente de déterminer les paramètres régionaux par défaut, puis les renvoie sous la forme d'un n-uplet @code{(code de la langue, encodage)}.

D'après POSIX, un programme qui n'a pas appelé @code{setlocale(LC_ALL, '@w{'})} fonctionne en utilisant le paramètre régional portable @code{'C'}.  Appeler @code{setlocale(LC_ALL, '@w{'})} lui permet d'utiliser les paramètres régionaux par défaut définis par la variable 
@geindex LANG
@geindex variable d'environnement; LANG
@code{LANG}.  Comme nous ne voulons pas interférer avec les paramètres régionaux actuels, nous émulons donc le comportement décrit ci-dessus.

Afin de maintenir la compatibilité avec d'autres plateformes, non seulement la variable 
@geindex LANG
@geindex variable d'environnement; LANG
@code{LANG} est testée, mais c'est aussi le cas pour toute une liste de variables passés en paramètre via `envvars'.  La première variable à être définie sera utilisée.  `envvars' utilise par défaut le chemin de recherche utilisé dans GNU `gettext' ; il doit toujours contenir le nom de variable @code{'LANG'}.  Le chemin de recherche de GNU `gettext' contient @code{'LC_ALL'}, @code{'LC_CTYPE'}, @code{'LANG'} et @code{'LANGUAGE'}, dans cet ordre.

À l'exception du code @code{'C'}, le code d'une langue correspond à la 
@geindex RFC; RFC 1766
RFC 1766@footnote{https://datatracker.ietf.org/doc/html/rfc1766.html}. Le `code de la langue' et l'`encodage' peuvent valoir @code{None} si leur valeur ne peut être déterminée.


Deprecated since version 3.11, will be removed in version 3.15.

@end deffn

@geindex getlocale() (dans le module locale)
@anchor{library/locale locale getlocale}@anchor{2d9}
@deffn {Fonction} locale.getlocale (category=LC_CTYPE)

Returns the current setting for the given locale category as sequence containing
`language code', `encoding'. `category' may be one of the @code{LC_*} values
except @ref{3c7a,,LC_ALL}.  It defaults to @ref{3c7b,,LC_CTYPE}.

À l'exception du code @code{'C'}, le code d'une langue correspond à la 
@geindex RFC; RFC 1766
RFC 1766@footnote{https://datatracker.ietf.org/doc/html/rfc1766.html}. Le `code de la langue' et l'`encodage' peuvent valoir @code{None} si leur valeur ne peut être déterminée.
@end deffn

@geindex getpreferredencoding() (dans le module locale)
@anchor{library/locale locale getpreferredencoding}@anchor{524}
@deffn {Fonction} locale.getpreferredencoding (do_setlocale=True)

Return the @ref{23f,,locale encoding} used for text data, according to user
preferences.  User preferences are expressed differently on different
systems, and might not be available programmatically on some systems, so
this function only returns a guess.

Sur certains systèmes, il est nécessaire d'invoquer @ref{2da,,setlocale()} pour obtenir les préférences de l'utilisateur, cette fonction n'est donc pas utilisable sans protection dans les programmes à fils d'exécutions multiples. Si l'appel de @code{setlocale} n'est pas nécessaire ou souhaité, `do_setlocale' doit être réglé à @code{False}.

On Android or if the @ref{641,,Python UTF-8 Mode} is enabled, always
return @code{'utf-8'}, the @ref{23f,,locale encoding} and the `do_setlocale'
argument are ignored.

The @ref{3c7c,,Python preinitialization} configures the LC_CTYPE
locale. See also the @ref{525,,filesystem encoding and error handler}.


Modifié dans la version 3.7: The function now always returns @code{"utf-8"} on Android or if the
@ref{641,,Python UTF-8 Mode} is enabled.

@end deffn

@geindex getencoding() (dans le module locale)
@anchor{library/locale locale getencoding}@anchor{2db}
@deffn {Fonction} locale.getencoding ()

Get the current @ref{23f,,locale encoding}:


@itemize *

@item 
On Android and VxWorks, return @code{"utf-8"}.

@item 
On Unix, return the encoding of the current @ref{3c7b,,LC_CTYPE} locale.
Return @code{"utf-8"} if @code{nl_langinfo(CODESET)} returns an empty string:
for example, if the current LC_CTYPE locale is not supported.

@item 
On Windows, return the ANSI code page.
@end itemize

The @ref{3c7c,,Python preinitialization} configures the LC_CTYPE
locale. See also the @ref{525,,filesystem encoding and error handler}.

This function is similar to
@ref{524,,getpreferredencoding(False)} except this
function ignores the @ref{641,,Python UTF-8 Mode}.


Ajouté dans la version 3.11.

@end deffn

@geindex normalize() (dans le module locale)
@anchor{library/locale locale normalize}@anchor{3c7d}
@deffn {Fonction} locale.normalize (localename)

Renvoie un code normalisé pour le nom du paramètre régional fourni.  Ce code renvoyé est structuré de façon à être utilisé avec @ref{2da,,setlocale()}.  Si la normalisation échoue, le nom d'origine est renvoyé inchangé.

Si l'encodage donné n'est pas connu, la fonction utilise l'encodage par défaut pour le code du paramètre régional, tout comme @ref{2da,,setlocale()}.
@end deffn

@geindex strcoll() (dans le module locale)
@anchor{library/locale locale strcoll}@anchor{3c7e}
@deffn {Fonction} locale.strcoll (string1, string2)

Compare deux chaînes en se basant sur le paramètre @ref{3c7f,,LC_COLLATE} actuel. Comme toute autre fonction de comparaison, renvoie une valeur négative, positive, ou @code{0}, selon si `string1' est lexicographiquement inférieure, supérieure, ou égale à `string2'.
@end deffn

@geindex strxfrm() (dans le module locale)
@anchor{library/locale locale strxfrm}@anchor{3c80}
@deffn {Fonction} locale.strxfrm (string)

Transforme une chaîne de caractères en une chaîne qui peut être utilisée dans les comparaisons sensibles aux paramètres régionaux.  Par exemple, @code{strxfrm(s1) < strxfrm(s2)} est équivalent à @code{strcoll(s1, s2) < 0}.  Cette fonction peut être utilisée lorsque la même chaîne est comparée de façon répétitive, par exemple lors de l'assemblage d'une séquence de chaînes.
@end deffn

@geindex format_string() (dans le module locale)
@anchor{library/locale locale format_string}@anchor{508}
@deffn {Fonction} locale.format_string (format, val, grouping=False, monetary=False)

Formats a number `val' according to the current @ref{3c41,,LC_NUMERIC} setting.
The format follows the conventions of the @code{%} operator.  For floating-point
values, the decimal point is modified if appropriate.  If `grouping' is @code{True},
also takes the grouping into account.

Si `monetary' est vrai, la conversion utilise un séparateur des milliers monétaire et des chaînes de regroupement.

Traite les marqueurs de structure en @code{format % val}, mais en prenant en compte les paramètres régionaux actuels.


Modifié dans la version 3.7: The `monetary' keyword parameter was added.

@end deffn

@geindex currency() (dans le module locale)
@anchor{library/locale locale currency}@anchor{3c81}
@deffn {Fonction} locale.currency (val, symbol=True, grouping=False, international=False)

Structure un nombre `val' en fonction du paramètre @ref{3c43,,LC_MONETARY} actuel.

The returned string includes the currency symbol if `symbol' is true, which is
the default. If `grouping' is @code{True} (which is not the default), grouping is done
with the value. If `international' is @code{True} (which is not the default), the
international currency symbol is used.

@cartouche
@quotation Note 
This function will not work with the 'C' locale, so you have to set a
locale via @ref{2da,,setlocale()} first.
@end quotation
@end cartouche
@end deffn

@geindex str() (dans le module locale)
@anchor{library/locale locale str}@anchor{3c82}
@deffn {Fonction} locale.str (float)

Formats a floating-point number using the same format as the built-in function
@code{str(float)}, but takes the decimal point into account.
@end deffn

@geindex delocalize() (dans le module locale)
@anchor{library/locale locale delocalize}@anchor{e12}
@deffn {Fonction} locale.delocalize (string)

Convertit une chaîne de caractères en une chaîne de nombres normalisés, en suivant les réglages @ref{3c41,,LC_NUMERIC}.


Ajouté dans la version 3.5.

@end deffn

@geindex localize() (dans le module locale)
@anchor{library/locale locale localize}@anchor{3c83}
@deffn {Fonction} locale.localize (string, grouping=False, monetary=False)

Converts a normalized number string into a formatted string following the
@ref{3c41,,LC_NUMERIC} settings.


Ajouté dans la version 3.10.

@end deffn

@geindex atof() (dans le module locale)
@anchor{library/locale locale atof}@anchor{3c84}
@deffn {Fonction} locale.atof (string, func=float)

Converts a string to a number, following the @ref{3c41,,LC_NUMERIC} settings,
by calling `func' on the result of calling @ref{e12,,delocalize()} on `string'.
@end deffn

@geindex atoi() (dans le module locale)
@anchor{library/locale locale atoi}@anchor{3c85}
@deffn {Fonction} locale.atoi (string)

Convertit une chaîne de caractères en un entier, en suivant les réglages @ref{3c41,,LC_NUMERIC}.
@end deffn

@geindex LC_CTYPE (dans le module locale)
@anchor{library/locale locale LC_CTYPE}@anchor{3c7b}
@deffn {Données} locale.LC_CTYPE

Locale category for the character type functions.  Most importantly, this
category defines the text encoding, i.e. how bytes are interpreted as
Unicode codepoints.  See 
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/} and 
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/} for how this variable
might be automatically coerced to @code{C.UTF-8} to avoid issues created by
invalid settings in containers or incompatible settings passed over remote
SSH connections.

Python doesn't internally use locale-dependent character transformation functions
from @code{ctype.h}. Instead, an internal @code{pyctype.h} provides locale-independent
equivalents like @code{Py_TOLOWER}.
@end deffn

@geindex LC_COLLATE (dans le module locale)
@anchor{library/locale locale LC_COLLATE}@anchor{3c7f}
@deffn {Données} locale.LC_COLLATE

Catégorie de paramètre régional pour les tris de chaînes de caractères.  Les fonctions @ref{3c7e,,strcoll()} et @ref{3c80,,strxfrm()} du module @ref{85,,locale} sont concernées.
@end deffn

@geindex LC_TIME (dans le module locale)
@anchor{library/locale locale LC_TIME}@anchor{3c86}
@deffn {Données} locale.LC_TIME

Catégorie de paramètre régional pour la mise en forme de la date et de l'heure.  La fonction @ref{11c6,,time.strftime()} suit ces conventions.
@end deffn

@geindex LC_MONETARY (dans le module locale)
@anchor{library/locale locale LC_MONETARY}@anchor{3c43}
@deffn {Données} locale.LC_MONETARY

Catégorie de paramètre régional pour la mise en forme des valeurs monétaires.  Les options disponibles sont accessibles à partir de la fonction @ref{bec,,localeconv()}.
@end deffn

@geindex LC_MESSAGES (dans le module locale)
@anchor{library/locale locale LC_MESSAGES}@anchor{3c87}
@deffn {Données} locale.LC_MESSAGES

Catégorie de paramètre régional pour l'affichage de messages. Actuellement, Python ne gère pas les messages spécifiques aux applications qui sont sensibles aux paramètres régionaux.  Les messages affichés par le système d'exploitation, comme ceux renvoyés par @ref{2aac,,os.strerror()} peuvent être affectés par cette catégorie.

This value may not be available on operating systems not conforming to the
POSIX standard, most notably Windows.
@end deffn

@geindex LC_NUMERIC (dans le module locale)
@anchor{library/locale locale LC_NUMERIC}@anchor{3c41}
@deffn {Données} locale.LC_NUMERIC

Locale category for formatting numbers.  The functions @ref{508,,format_string()},
@ref{3c85,,atoi()}, @ref{3c84,,atof()} and @ref{3c82,,str()} of the @ref{85,,locale} module are
affected by that category.  All other numeric formatting operations are not
affected.
@end deffn

@geindex LC_ALL (dans le module locale)
@anchor{library/locale locale LC_ALL}@anchor{3c7a}
@deffn {Données} locale.LC_ALL

Combinaison de tous les paramètres régionaux.  Si cette option est utilisée lors du changement de paramètres régionaux, la définition de ces paramètres pour toutes les catégories est tentée. Si cela échoue pour n'importe quelle catégorie, aucune d'entre elles n'est modifiée.  Lorsque les paramètres régionaux sont récupérés à l'aide de cette option, une chaîne de caractères indiquant le réglage pour toutes les catégories est renvoyée. Cette chaîne peut alors être utilisée plus tard pour restaurer les paramètres d'origine.
@end deffn

@geindex CHAR_MAX (dans le module locale)
@anchor{library/locale locale CHAR_MAX}@anchor{3c42}
@deffn {Données} locale.CHAR_MAX

Ceci est une constante symbolique utilisée pour différentes valeurs renvoyées par @ref{bec,,localeconv()}.
@end deffn

Exemple :

@example
>>> import locale
>>> loc = locale.getlocale()  # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '@w{'})   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale
@end example

@menu
* Contexte@comma{} détails@comma{} conseils@comma{} astuces et mises en garde: Contexte détails conseils astuces et mises en garde. 
* Pour les auteurs d'extensions et les programmes qui intègrent Python:: 
* Accéder aux catalogues de messages:: 

@end menu

@node Contexte détails conseils astuces et mises en garde,Pour les auteurs d'extensions et les programmes qui intègrent Python,,locale --- Internationalization services
@anchor{library/locale background-details-hints-tips-and-caveats}@anchor{3c88}
@subsubsection Contexte, détails, conseils, astuces et mises en garde


The C standard defines the locale as a program-wide property that may be
relatively expensive to change.  On top of that, some implementations are broken
in such a way that frequent locale changes may cause core dumps.  This makes the
locale somewhat painful to use correctly.

Initialement, lorsqu'un programme est démarré, les paramètres régionaux @code{C} sont utilisés, peu importe les réglages de l'utilisateur.  Il y a toutefois une exception : la catégorie @ref{3c7b,,LC_CTYPE} est modifiée au démarrage pour définir l'encodage des paramètres régionaux actuels comme celui défini par l'utilisateur. Le programme doit explicitement dire qu'il veut utiliser les réglages de l'utilisateur pour les autres catégories, en appelant @code{setlocale(LC_ALL, '@w{'})}.

C'est généralement une mauvaise idée d'appeler @ref{2da,,setlocale()} dans une routine de bibliothèque car cela a pour effet secondaire d'affecter le programme entier.  Sauvegarder et restaurer les paramètres est presque aussi mauvais : c'est coûteux et cela affecte d'autres fils d'exécutions qui s'exécutent avant que les paramètres n'aient été restaurés.

Si, lors du développement d'un module à usage général, vous avez besoin d'une version indépendante des paramètres régionaux pour une opération y étant sensible (comme c'est le cas pour certains formats utilisés avec @ref{11c6,,time.strftime()}), vous devez trouver un moyen de le faire sans utiliser la routine de la bibliothèque standard.  Le mieux est encore de se convaincre que l'usage des paramètres régionaux est une bonne chose.  Ce n'est qu'en dernier recours que vous devez documenter que votre module n'est pas compatible avec les réglages du paramètre régional @code{C}.

The only way to perform numeric operations according to the locale is to use the
special functions defined by this module: @ref{3c84,,atof()}, @ref{3c85,,atoi()},
@ref{508,,format_string()}, @ref{3c82,,str()}.

Il n'y a aucun moyen d'effectuer des conversions de casse et des classifications de caractères en fonction des paramètres régionaux.  Pour les chaînes de caractères (Unicode), celles-ci se font uniquement en fonction de la valeur du caractère, tandis que pour les chaînes d'octets, les conversions et les classifications se font en fonction de la valeur ASCII de l'octet, et les octets dont le bit de poids fort est à 1 (c'est-à-dire les octets non ASCII) ne sont jamais convertis ou considérés comme faisant partie d'une classe de caractères comme une lettre ou une espace.

@node Pour les auteurs d'extensions et les programmes qui intègrent Python,Accéder aux catalogues de messages,Contexte détails conseils astuces et mises en garde,locale --- Internationalization services
@anchor{library/locale embedding-locale}@anchor{3c89}@anchor{library/locale for-extension-writers-and-programs-that-embed-python}@anchor{3c8a}
@subsubsection Pour les auteurs d'extensions et les programmes qui intègrent Python


Les modules d'extensions ne devraient jamais appeler @ref{2da,,setlocale()}, sauf pour connaître le paramètre régional actuel.  Mais comme la valeur renvoyée ne peut être utilisée que pour le restaurer, ce n'est pas très utile (sauf peut-être pour savoir si le paramètre régional est défini à @code{C} ou non).

When Python code uses the @ref{85,,locale} module to change the locale, this also
affects the embedding application.  If the embedding application doesn't want
this to happen, it should remove the @code{_locale} extension module (which does
all the work) from the table of built-in modules in the @code{config.c} file,
and make sure that the @code{_locale} module is not accessible as a shared
library.

@node Accéder aux catalogues de messages,,Pour les auteurs d'extensions et les programmes qui intègrent Python,locale --- Internationalization services
@anchor{library/locale access-to-message-catalogs}@anchor{3c8b}@anchor{library/locale locale-gettext}@anchor{3c8c}
@subsubsection Accéder aux catalogues de messages


@geindex gettext() (dans le module locale)
@anchor{library/locale locale gettext}@anchor{3c8d}
@deffn {Fonction} locale.gettext (msg)
@end deffn

@geindex dgettext() (dans le module locale)
@anchor{library/locale locale dgettext}@anchor{3c8e}
@deffn {Fonction} locale.dgettext (domain, msg)
@end deffn

@geindex dcgettext() (dans le module locale)
@anchor{library/locale locale dcgettext}@anchor{3c8f}
@deffn {Fonction} locale.dcgettext (domain, msg, category)
@end deffn

@geindex textdomain() (dans le module locale)
@anchor{library/locale locale textdomain}@anchor{3c90}
@deffn {Fonction} locale.textdomain (domain)
@end deffn

@geindex bindtextdomain() (dans le module locale)
@anchor{library/locale locale bindtextdomain}@anchor{3c91}
@deffn {Fonction} locale.bindtextdomain (domain, dir)
@end deffn

@geindex bind_textdomain_codeset() (dans le module locale)
@anchor{library/locale locale bind_textdomain_codeset}@anchor{3c92}
@deffn {Fonction} locale.bind_textdomain_codeset (domain, codeset)
@end deffn

The locale module exposes the C library's gettext interface on systems that
provide this interface.  It consists of the functions @ref{62,,gettext()},
@ref{3c8e,,dgettext()}, @ref{3c8f,,dcgettext()}, @ref{3c90,,textdomain()}, @ref{3c91,,bindtextdomain()},
and @ref{3c92,,bind_textdomain_codeset()}.  These are similar to the same functions in
the @ref{62,,gettext} module, but use the C library's binary format for message
catalogs, and the C library's search algorithms for locating message catalogs.

Python applications should normally find no need to invoke these functions, and
should use @ref{62,,gettext} instead.  A known exception to this rule are
applications that link with additional C libraries which internally invoke
C functions @code{gettext} or @code{dcgettext}.  For these applications, it may be
necessary to bind the text domain, so that the libraries can properly locate
their message catalogs.

@node Cadriciels d'applications,Interfaces Utilisateur Graphiques avec Tk,Internationalisation,La bibliothèque standard
@anchor{library/frameworks doc}@anchor{3c93}@anchor{library/frameworks frameworks}@anchor{3c94}@anchor{library/frameworks program-frameworks}@anchor{3c95}
@section Cadriciels d'applications


Les modules décrits dans ce chapitre sont des cadriciels (`frameworks', en anglais) qui encadreront la structure de vos programmes. Actuellement tous les modules décrits ici sont destinés à écrire des interfaces en ligne de commande.

La liste complète des modules décrits dans ce chapitre est :

@menu
* turtle — Tortue graphique:: 
* cmd: cmd --- Support for line-oriented command interpreters. Support for line-oriented command interpreters
* shlex: shlex --- Simple lexical analysis. Simple lexical analysis

@end menu

@node turtle — Tortue graphique,cmd --- Support for line-oriented command interpreters,,Cadriciels d'applications
@anchor{library/turtle doc}@anchor{3c96}@anchor{library/turtle module-turtle}@anchor{100}@anchor{library/turtle turtle-turtle-graphics}@anchor{3c97}
@subsection @code{turtle} — Tortue graphique


@geindex module; turtle

`Code Source :' Lib/turtle.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/turtle.py}

@c from turtle import *
@c turtle = Turtle()


__________________________________________________________________


@menu
* Introduction: Introduction<10>. 
* Get started:: 
* Tutoriel: Tutoriel<4>. 
* How to...: How to. 
* Turtle graphics reference:: 
* Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes:: 
* Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes:: 
* Classes publiques:: 
* Explication:: 
* Aide et configuration:: 
* turtledemo — Scripts de démonstration:: 
* Modifications depuis Python 2.6: Modifications depuis Python 2 6. 
* Modifications depuis Python 3.0: Modifications depuis Python 3 0. 

@end menu

@node Introduction<10>,Get started,,turtle — Tortue graphique
@anchor{library/turtle introduction}@anchor{3c98}
@subsubsection Introduction


Turtle graphics is an implementation of the popular geometric drawing tools introduced in Logo@footnote{https://en.wikipedia.org/wiki/Turtle_(robot)}, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon
in 1967.

@node Get started,Tutoriel<4>,Introduction<10>,turtle — Tortue graphique
@anchor{library/turtle get-started}@anchor{3c99}
@subsubsection Get started


Imaginez un robot sous forme de tortue partant au centre (0, 0) d'un plan cartésien x-y. Après un @code{import turtle}, exécutez la commande @code{turtle.forward(15)} et la tortue se déplace (sur l'écran) de 15 pixels en face d'elle, en dessinant une ligne.

@subsubheading Turtle star



La tortue permet de dessiner des formes complexes en utilisant un programme qui répète des actions élémentaires.

@image{python-figures/turtle-star,,,,png}

In Python, turtle graphics provides a representation of a physical "turtle"
(a little robot with a pen) that draws on a sheet of paper on the floor.

It's an effective and well-proven way for learners to encounter
programming concepts and interaction with software, as it provides instant,
visible feedback. It also provides convenient access to graphical output
in general.

Turtle drawing was originally created as an educational tool, to be used by
teachers in the classroom. For the programmer who needs to produce some
graphical output it can be a way to do that without the overhead of
introducing more complex or external libraries into their work.

@node Tutoriel<4>,How to,Get started,turtle — Tortue graphique
@anchor{library/turtle turtle-tutorial}@anchor{3c9a}@anchor{library/turtle tutorial}@anchor{3c9b}
@subsubsection Tutoriel


New users should start here. In this tutorial we'll explore some of the
basics of turtle drawing.

@menu
* Starting a turtle environment:: 
* Basic drawing:: 
* Making algorithmic patterns:: 

@end menu

@node Starting a turtle environment,Basic drawing,,Tutoriel<4>
@anchor{library/turtle starting-a-turtle-environment}@anchor{3c9c}
@subsubsection Starting a turtle environment


In a Python shell, import all the objects of the @code{turtle} module:

@example
from turtle import *
@end example

If you run into a @code{No module named '_tkinter'} error, you'll have to
install the @ref{ef,,Tk interface package} on your system.

@node Basic drawing,Making algorithmic patterns,Starting a turtle environment,Tutoriel<4>
@anchor{library/turtle basic-drawing}@anchor{3c9d}
@subsubsection Basic drawing


Send the turtle forward 100 steps:

@example
forward(100)
@end example

You should see (most likely, in a new window on your display) a line
drawn by the turtle, heading East. Change the direction of the turtle,
so that it turns 120 degrees left (anti-clockwise):

@example
left(120)
@end example

Let's continue by drawing a triangle:

@example
forward(100)
left(120)
forward(100)
@end example

Notice how the turtle, represented by an arrow, points in different
directions as you steer it.

Experiment with those commands, and also with @code{backward()} and
@code{right()}.

@menu
* Réglage des stylos:: 
* The turtle's position:: 

@end menu

@node Réglage des stylos,The turtle's position,,Basic drawing
@anchor{library/turtle pen-control}@anchor{3c9e}
@subsubsection Réglage des stylos


Try changing the color - for example, @code{color('blue')} - and
width of the line - for example, @code{width(3)} - and then drawing again.

You can also move the turtle around without drawing, by lifting up the pen:
@code{up()} before moving. To start drawing again, use @code{down()}.

@node The turtle's position,,Réglage des stylos,Basic drawing
@anchor{library/turtle the-turtle-s-position}@anchor{3c9f}
@subsubsection The turtle's position


Send your turtle back to its starting-point (useful if it has disappeared
off-screen):

@example
home()
@end example

The home position is at the center of the turtle's screen. If you ever need to
know them, get the turtle's x-y coordinates with:

@example
pos()
@end example

Home is at @code{(0, 0)}.

And after a while, it will probably help to clear the window so we can start
anew:

@example
clearscreen()
@end example

@node Making algorithmic patterns,,Basic drawing,Tutoriel<4>
@anchor{library/turtle making-algorithmic-patterns}@anchor{3ca0}
@subsubsection Making algorithmic patterns


Using loops, it's possible to build up geometric patterns:

@example
for steps in range(100):
    for c in ('blue', 'red', 'green'):
        color(c)
        forward(steps)
        right(30)
@end example

- which of course, are limited only by the imagination!

Let's draw the star shape at the top of this page. We want red lines,
filled in with yellow:

@example
color('red')
fillcolor('yellow')
@end example

Just as @code{up()} and @code{down()} determine whether lines will be drawn,
filling can be turned on and off:

@example
begin_fill()
@end example

Next we'll create a loop:

@example
while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break
@end example

@code{abs(pos()) < 1} is a good way to know when the turtle is back at its
home position.

Finally, complete the filling:

@example
end_fill()
@end example

(Note that filling only actually takes place when you give the
@code{end_fill()} command.)

@node How to,Turtle graphics reference,Tutoriel<4>,turtle — Tortue graphique
@anchor{library/turtle how-to}@anchor{3ca1}@anchor{library/turtle turtle-how-to}@anchor{3ca2}
@subsubsection How to...


This section covers some typical turtle use-cases and approaches.

@menu
* Get started as quickly as possible:: 
* Use the turtle module namespace:: 
* Use turtle graphics in a script:: 
* Use object-oriented turtle graphics:: 

@end menu

@node Get started as quickly as possible,Use the turtle module namespace,,How to
@anchor{library/turtle get-started-as-quickly-as-possible}@anchor{3ca3}
@subsubsection Get started as quickly as possible


One of the joys of turtle graphics is the immediate, visual feedback that's
available from simple commands - it's an excellent way to introduce children
to programming ideas, with a minimum of overhead (not just children, of
course).

The turtle module makes this possible by exposing all its basic functionality
as functions, available with @code{from turtle import *}. The @ref{3c9a,,turtle graphics tutorial} covers this approach.

It's worth noting that many of the turtle commands also have even more terse
equivalents, such as @code{fd()} for @ref{3ca4,,forward()}. These are especially
useful when working with learners for whom typing is not a skill.
@anchor{library/turtle note}@anchor{3ca5}
@quotation

You'll need to have the @ref{ef,,Tk interface package} installed on
your system for turtle graphics to work. Be warned that this is not
always straightforward, so check this in advance if you're planning to
use turtle graphics with a learner.
@end quotation

@node Use the turtle module namespace,Use turtle graphics in a script,Get started as quickly as possible,How to
@anchor{library/turtle use-the-turtle-module-namespace}@anchor{3ca6}
@subsubsection Use the @code{turtle} module namespace


Using @code{from turtle import *} is convenient - but be warned that it imports a
rather large collection of objects, and if you're doing anything but turtle
graphics you run the risk of a name conflict (this becomes even more an issue
if you're using turtle graphics in a script where other modules might be
imported).

The solution is to use @code{import turtle} - @code{fd()} becomes
@code{turtle.fd()}, @code{width()} becomes @code{turtle.width()} and so on. (If typing
"turtle" over and over again becomes tedious, use for example @code{import turtle
as t} instead.)

@node Use turtle graphics in a script,Use object-oriented turtle graphics,Use the turtle module namespace,How to
@anchor{library/turtle use-turtle-graphics-in-a-script}@anchor{3ca7}
@subsubsection Use turtle graphics in a script


It's recommended to use the @code{turtle} module namespace as described
immediately above, for example:

@example
import turtle as t
from random import random

for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)
@end example

Another step is also required though - as soon as the script ends, Python
will also close the turtle's window. Add:

@example
t.mainloop()
@end example

to the end of the script. The script will now wait to be dismissed and
will not exit until it is terminated, for example by closing the turtle
graphics window.

@node Use object-oriented turtle graphics,,Use turtle graphics in a script,How to
@anchor{library/turtle use-object-oriented-turtle-graphics}@anchor{3ca8}
@subsubsection Use object-oriented turtle graphics



@subsubheading Voir aussi


@ref{3ca9,,Explanation of the object-oriented interface}


Other than for very basic introductory purposes, or for trying things out
as quickly as possible, it's more usual and much more powerful to use the
object-oriented approach to turtle graphics. For example, this allows
multiple turtles on screen at once.

In this approach, the various turtle commands are methods of objects (mostly of
@code{Turtle} objects). You `can' use the object-oriented approach in the shell,
but it would be more typical in a Python script.

The example above then becomes:

@example
from turtle import Turtle
from random import random

t = Turtle()
for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

t.screen.mainloop()
@end example

Note the last line. @code{t.screen} is an instance of the @ref{3caa,,Screen}
that a Turtle instance exists on; it's created automatically along with
the turtle.

The turtle's screen can be customised, for example:

@example
t.screen.title('Object-oriented turtle demo')
t.screen.bgcolor("orange")
@end example

@node Turtle graphics reference,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes,How to,turtle — Tortue graphique
@anchor{library/turtle turtle-graphics-reference}@anchor{3cab}
@subsubsection Turtle graphics reference


@cartouche
@quotation Note 
La liste des paramètres des fonctions est donnée dans cette documentation. Les méthodes ont, évidemment, le paramètre `self' comme premier argument, mais ce dernier n'est pas indiqué ici.
@end quotation
@end cartouche

@menu
* Les méthodes du module Turtle:: 
* Méthodes de TurtleScreen/Screen:: 

@end menu

@node Les méthodes du module Turtle,Méthodes de TurtleScreen/Screen,,Turtle graphics reference
@anchor{library/turtle turtle-methods}@anchor{3cac}
@subsubsection Les méthodes du module `Turtle'



@table @asis

@item Les mouvements dans le module `Turtle'


@table @asis

@item Bouger et dessiner


@display
@ref{3ca4,,forward()} | @ref{3cad,,fd()}@w{ }
@ref{3cae,,backward()} | @ref{3caf,,bk()} | @ref{3cb0,,back()}@w{ }
@ref{3cb1,,right()} | @ref{3cb2,,rt()}@w{ }
@ref{3cb3,,left()} | @ref{3cb4,,lt()}@w{ }
@ref{3cb5,,goto()} | @ref{3cb6,,setpos()} | @ref{3cb7,,setposition()}@w{ }
@ref{16b1,,teleport()}@w{ }
@ref{3cb8,,setx()}@w{ }
@ref{3cb9,,sety()}@w{ }
@ref{3cba,,setheading()} | @ref{3cbb,,seth()}@w{ }
@ref{3cbc,,home()}@w{ }
@ref{3cbd,,circle()}@w{ }
@ref{3cbe,,dot()}@w{ }
@ref{3cbf,,stamp()}@w{ }
@ref{3cc0,,clearstamp()}@w{ }
@ref{3cc1,,clearstamps()}@w{ }
@ref{3cc2,,undo()}@w{ }
@ref{3cc3,,speed()}@w{ }
@end display



@item Connaître l'état de la tortue


@display
@ref{3cc4,,position()} | @ref{3cc5,,pos()}@w{ }
@ref{3cc6,,towards()}@w{ }
@ref{3cc7,,xcor()}@w{ }
@ref{3cc8,,ycor()}@w{ }
@ref{3cc9,,heading()}@w{ }
@ref{3cca,,distance()}@w{ }
@end display



@item Paramétrage et mesure


@display
@ref{3ccb,,degrees()}@w{ }
@ref{3ccc,,radians()}@w{ }
@end display


@end table

@item Réglage des stylos


@table @asis

@item État des stylos


@display
@ref{3ccd,,pendown()} | @ref{3cce,,pd()} | @ref{3ccf,,down()}@w{ }
@ref{3cd0,,penup()} | @ref{3cd1,,pu()} | @ref{3cd2,,up()}@w{ }
@ref{3cd3,,pensize()} | @ref{3cd4,,width()}@w{ }
@ref{3cd5,,pen()}@w{ }
@ref{3cd6,,isdown()}@w{ }
@end display



@item Réglage des couleurs


@display
@ref{3cd7,,color()}@w{ }
@ref{3cd8,,pencolor()}@w{ }
@ref{3cd9,,fillcolor()}@w{ }
@end display



@item Remplissage


@display
@ref{3cda,,filling()}@w{ }
@ref{3cdb,,begin_fill()}@w{ }
@ref{3cdc,,end_fill()}@w{ }
@end display



@item Plus des réglages pour le dessin


@display
@ref{3cdd,,reset()}@w{ }
@ref{3cde,,clear()}@w{ }
@ref{3cdf,,write()}@w{ }
@end display


@end table

@item État de la tortue


@table @asis

@item Visibilité


@display
@ref{3ce0,,showturtle()} | @ref{3ce1,,st()}@w{ }
@ref{3ce2,,hideturtle()} | @ref{3ce3,,ht()}@w{ }
@ref{3ce4,,isvisible()}@w{ }
@end display



@item Apparence


@display
@ref{3ce5,,shape()}@w{ }
@ref{3ce6,,resizemode()}@w{ }
@ref{3ce7,,shapesize()} | @ref{3ce8,,turtlesize()}@w{ }
@ref{3ce9,,shearfactor()}@w{ }
@ref{70f,,tiltangle()}@w{ }
@ref{3cea,,tilt()}@w{ }
@ref{3ceb,,shapetransform()}@w{ }
@ref{3cec,,get_shapepoly()}@w{ }
@end display


@end table

@item Utilisation des événements


@display
@ref{3ced,,onclick()}@w{ }
@ref{3cee,,onrelease()}@w{ }
@ref{3cef,,ondrag()}@w{ }
@end display



@item Méthodes spéciales de la tortue


@display
@ref{3cf0,,begin_poly()}@w{ }
@ref{3cf1,,end_poly()}@w{ }
@ref{3cf2,,get_poly()}@w{ }
@ref{3cf3,,clone()}@w{ }
@ref{3cf4,,getturtle()} | @ref{3cf5,,getpen()}@w{ }
@ref{3cf6,,getscreen()}@w{ }
@ref{3cf7,,setundobuffer()}@w{ }
@ref{3cf8,,undobufferentries()}@w{ }
@end display


@end table

@node Méthodes de TurtleScreen/Screen,,Les méthodes du module Turtle,Turtle graphics reference
@anchor{library/turtle methods-of-turtlescreen-screen}@anchor{3cf9}
@subsubsection Méthodes de `TurtleScreen'/`Screen'



@table @asis

@item Réglage de la fenêtre


@display
@ref{3cfa,,bgcolor()}@w{ }
@ref{3cfb,,bgpic()}@w{ }
@ref{3cfc,,clearscreen()}@w{ }
@ref{3cfd,,resetscreen()}@w{ }
@ref{3cfe,,screensize()}@w{ }
@ref{3cff,,setworldcoordinates()}@w{ }
@end display



@item Réglage de l'animation


@display
@ref{3d00,,delay()}@w{ }
@ref{3d01,,tracer()}@w{ }
@ref{3d02,,update()}@w{ }
@end display



@item Utilisation des événements concernant l'écran


@display
@ref{3d03,,listen()}@w{ }
@ref{3d04,,onkey()} | @ref{3d05,,onkeyrelease()}@w{ }
@ref{3d06,,onkeypress()}@w{ }
@ref{3ced,,onclick()} | @ref{3d07,,onscreenclick()}@w{ }
@ref{3d08,,ontimer()}@w{ }
@ref{3d09,,mainloop()} | @ref{3d0a,,done()}@w{ }
@end display



@item Paramétrages et méthodes spéciales


@display
@ref{3d0b,,mode()}@w{ }
@ref{3d0c,,colormode()}@w{ }
@ref{3d0d,,getcanvas()}@w{ }
@ref{3d0e,,getshapes()}@w{ }
@ref{3d0f,,register_shape()} | @ref{3d10,,addshape()}@w{ }
@ref{3d11,,turtles()}@w{ }
@ref{3d12,,window_height()}@w{ }
@ref{3d13,,window_width()}@w{ }
@end display



@item Méthodes de saisie


@display
@ref{1850,,textinput()}@w{ }
@ref{1851,,numinput()}@w{ }
@end display



@item Méthodes spécifiques de `Screen'


@display
@ref{3d14,,bye()}@w{ }
@ref{3d15,,exitonclick()}@w{ }
@ref{3d16,,setup()}@w{ }
@ref{3d17,,title()}@w{ }
@end display


@end table

@node Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes,Turtle graphics reference,turtle — Tortue graphique
@anchor{library/turtle methods-of-rawturtle-turtle-and-corresponding-functions}@anchor{3d18}
@subsubsection Méthodes de `RawTurtle'/`Turtle' et leurs fonctions correspondantes


La plupart des exemples de cette section se réfèrent à une instance de `Turtle' appelée @code{turtle}.

@menu
* Les mouvements dans le module Turtle:: 
* Connaître l'état de la tortue:: 
* Paramètres de mesure:: 
* Réglage des stylos: Réglage des stylos<2>. 
* État de la tortue:: 
* Utilisation des événements:: 
* Méthodes spéciales de la tortue:: 
* Formes composées:: 

@end menu

@node Les mouvements dans le module Turtle,Connaître l'état de la tortue,,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle turtle-motion}@anchor{3d19}
@subsubsection Les mouvements dans le module `Turtle'


@geindex forward() (dans le module turtle)
@geindex fd() (dans le module turtle)
@anchor{library/turtle turtle forward}@anchor{3ca4}
@deffn {Fonction} turtle.forward (distance)
@anchor{library/turtle turtle fd}@anchor{3cad}
@deffnx {Fonction} turtle.fd (distance)

@*Paramètres: 
@code{distance} -- un nombre (entier ou flottant)


Avance la tortue de la `distance' spécifiée, dans la direction où elle se dirige.

@example
>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)
@end example
@end deffn

@geindex back() (dans le module turtle)
@geindex bk() (dans le module turtle)
@geindex backward() (dans le module turtle)
@anchor{library/turtle turtle back}@anchor{3cb0}
@deffn {Fonction} turtle.back (distance)
@anchor{library/turtle turtle bk}@anchor{3caf}
@deffnx {Fonction} turtle.bk (distance)
@anchor{library/turtle turtle backward}@anchor{3cae}
@deffnx {Fonction} turtle.backward (distance)

@*Paramètres: 
@code{distance} -- un nombre


Déplace la tortue de `distance' vers l'arrière (dans le sens opposé à celui vers lequel elle pointe). Ne change pas le cap de la tortue.

@c >>> turtle.goto(0, 0)

@example
>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)
@end example
@end deffn

@geindex right() (dans le module turtle)
@geindex rt() (dans le module turtle)
@anchor{library/turtle turtle right}@anchor{3cb1}
@deffn {Fonction} turtle.right (angle)
@anchor{library/turtle turtle rt}@anchor{3cb2}
@deffnx {Fonction} turtle.rt (angle)

@*Paramètres: 
@code{angle} -- un nombre (entier ou flottant)


Tourne la tortue à droite de `angle' unités (les unités sont par défaut des degrés, mais peuvent être définies via les fonctions @ref{3ccb,,degrees()} et @ref{3ccc,,radians()}). L'orientation de l'angle dépend du mode de la tortue, voir @ref{3d0b,,mode()}.

@c >>> turtle.setheading(22)

@example
>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0
@end example
@end deffn

@geindex left() (dans le module turtle)
@geindex lt() (dans le module turtle)
@anchor{library/turtle turtle left}@anchor{3cb3}
@deffn {Fonction} turtle.left (angle)
@anchor{library/turtle turtle lt}@anchor{3cb4}
@deffnx {Fonction} turtle.lt (angle)

@*Paramètres: 
@code{angle} -- un nombre (entier ou flottant)


Tourne la tortue à gauche d'une valeur de `angle' unités (les unités sont par défaut des degrés, mais peuvent être définies via les fonctions @ref{3ccb,,degrees()} et @ref{3ccc,,radians()}). L'orientation de l'angle dépend du mode de la tortue, voir @ref{3d0b,,mode()}.

@c >>> turtle.setheading(22)

@example
>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0
@end example
@end deffn

@geindex goto() (dans le module turtle)
@geindex setpos() (dans le module turtle)
@geindex setposition() (dans le module turtle)
@anchor{library/turtle turtle goto}@anchor{3cb5}
@deffn {Fonction} turtle.goto (x, y=None)
@anchor{library/turtle turtle setpos}@anchor{3cb6}
@deffnx {Fonction} turtle.setpos (x, y=None)
@anchor{library/turtle turtle setposition}@anchor{3cb7}
@deffnx {Fonction} turtle.setposition (x, y=None)

@*Paramètres: 

@itemize *

@item 
@code{x} -- un nombre ou une paire / un vecteur de nombres

@item 
@code{y} -- un nombre ou @code{None}
@end itemize


Si `y' est @code{None}, `x' doit être une paire de coordonnées, ou bien une instance de @ref{3d1a,,Vec2D} (par exemple, tel que renvoyé par @ref{3cc5,,pos()}).

Déplace la tortue vers une position absolue. Si le stylo est en bas, trace une ligne. Ne change pas l'orientation de la tortue.

@c >>> turtle.goto(0, 0)

@example
>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)
@end example
@end deffn

@geindex teleport() (dans le module turtle)
@anchor{library/turtle turtle teleport}@anchor{16b1}
@deffn {Fonction} turtle.teleport (x, y=None, *, fill_gap=False)

@*Paramètres: 

@itemize *

@item 
@code{x} -- un nombre ou @code{None}

@item 
@code{y} -- un nombre ou @code{None}

@item 
@code{fill_gap} -- a boolean
@end itemize


Move turtle to an absolute position. Unlike goto(x, y), a line will not
be drawn. The turtle's orientation does not change. If currently
filling, the polygon(s) teleported from will be filled after leaving,
and filling will begin again after teleporting. This can be disabled
with fill_gap=True, which makes the imaginary line traveled during
teleporting act as a fill barrier like in goto(x, y).

@c >>> turtle.goto(0, 0)

@example
>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.teleport(60)
>>> turtle.pos()
(60.00,0.00)
>>> turtle.teleport(y=10)
>>> turtle.pos()
(60.00,10.00)
>>> turtle.teleport(20, 30)
>>> turtle.pos()
(20.00,30.00)
@end example


Ajouté dans la version 3.12.

@end deffn

@geindex setx() (dans le module turtle)
@anchor{library/turtle turtle setx}@anchor{3cb8}
@deffn {Fonction} turtle.setx (x)

@*Paramètres: 
@code{x} -- un nombre (entier ou flottant)


Définit la première coordonnée de la tortue à `x', en laissant la deuxième coordonnée inchangée.

@c >>> turtle.goto(0, 240)

@example
>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)
@end example
@end deffn

@geindex sety() (dans le module turtle)
@anchor{library/turtle turtle sety}@anchor{3cb9}
@deffn {Fonction} turtle.sety (y)

@*Paramètres: 
@code{y} -- un nombre (entier ou flottant)


Définit la deuxième coordonnée de la tortue à `y', en laissant la première coordonnée inchangée.

@c >>> turtle.goto(0, 40)

@example
>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)
@end example
@end deffn

@geindex setheading() (dans le module turtle)
@geindex seth() (dans le module turtle)
@anchor{library/turtle turtle setheading}@anchor{3cba}
@deffn {Fonction} turtle.setheading (to_angle)
@anchor{library/turtle turtle seth}@anchor{3cbb}
@deffnx {Fonction} turtle.seth (to_angle)

@*Paramètres: 
@code{to_angle} -- un nombre (entier ou flottant)


Règle l'orientation de la tortue à la valeur @code{to_angle}. Voici quelques orientations courantes en degrés :


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
@headitem

mode standard

@tab

mode logo

@item

0 – Est

@tab

0 – Nord

@item

90 – Nord

@tab

90 – Est

@item

180 – Ouest

@tab

180 – Sud

@item

270 – Sud

@tab

270 – Ouest

@end multitable


@example
>>> turtle.setheading(90)
>>> turtle.heading()
90.0
@end example
@end deffn

@geindex home() (dans le module turtle)
@anchor{library/turtle turtle home}@anchor{3cbc}
@deffn {Fonction} turtle.home ()

Déplace la tortue à l'origine — coordonnées (0,0) — et l'oriente à son cap initial (qui dépend du mode, voir @ref{3d0b,,mode()}).

@c >>> turtle.setheading(90)
@c >>> turtle.goto(0, -10)

@example
>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
@end example
@end deffn

@geindex circle() (dans le module turtle)
@anchor{library/turtle turtle circle}@anchor{3cbd}
@deffn {Fonction} turtle.circle (radius, extent=None, steps=None)

@*Paramètres: 

@itemize *

@item 
@code{radius} -- un nombre

@item 
@code{extent} -- un nombre (ou @code{None})

@item 
@code{steps} -- un entier (ou @code{None})
@end itemize


Dessine un cercle de rayon `radius'. Le centre se trouve à une distance de `radius' à gauche de la tortue ; l'angle `extent' détermine quelle partie du cercle est dessinée. Si `extent' n'est pas fourni, dessine le cercle en entier. Si `extent' ne correspond pas à un cercle entier, la position actuelle du stylo est donnée par l'un des points d'extrémité de l'arc de cercle. Si la valeur de `radius' est positive, dessine l'arc de cercle dans le sens inverse des aiguilles d'une montre, sinon le dessine dans le sens des aiguilles d'une montre. Enfin, la direction de la tortue peut être modifiée en réglant la valeur de `extent'.

Comme le cercle est approximé par un polygone régulier inscrit, `steps' détermine le nombre de pas à utiliser. Si cette valeur n'est pas donnée, elle sera calculée automatiquement. Elle peut être utilisée pour dessiner des polygones réguliers.

@example
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0
@end example
@end deffn

@geindex dot() (dans le module turtle)
@anchor{library/turtle turtle dot}@anchor{3cbe}
@deffn {Fonction} turtle.dot (size=None, *color)

@*Paramètres: 

@itemize *

@item 
@code{size} -- un entier supérieur ou égal à 1 (si fourni)

@item 
@code{color} -- une chaîne qui désigne une couleur ou un triplet de couleur numérique
@end itemize


Dessine un point circulaire de diamètre `size', de la couleur `color'. Si le paramètre `size' n'est pas indiqué, utilise la valeur maximum de la taille du stylo plus 4 et de la taille du stylo multiplié par 2.

@example
>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0
@end example
@end deffn

@geindex stamp() (dans le module turtle)
@anchor{library/turtle turtle stamp}@anchor{3cbf}
@deffn {Fonction} turtle.stamp ()

Tamponne une copie de la forme de la tortue sur le canevas à la position actuelle de la tortue. Renvoie un `stamp_id' pour ce tampon, qui peut être utilisé pour le supprimer en appelant @code{clearstamp(stamp_id)}.

@example
>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)
@end example
@end deffn

@geindex clearstamp() (dans le module turtle)
@anchor{library/turtle turtle clearstamp}@anchor{3cc0}
@deffn {Fonction} turtle.clearstamp (stampid)

@*Paramètres: 
@code{stampid} -- un entier, doit être la valeur renvoyée par l'appel précédent de @ref{3cbf,,stamp()}


Supprime le tampon dont le `stampid' est donné.

@example
>>> turtle.position()
(150.00,-0.00)
>>> turtle.color("blue")
>>> astamp = turtle.stamp()
>>> turtle.fd(50)
>>> turtle.position()
(200.00,-0.00)
>>> turtle.clearstamp(astamp)
>>> turtle.position()
(200.00,-0.00)
@end example
@end deffn

@geindex clearstamps() (dans le module turtle)
@anchor{library/turtle turtle clearstamps}@anchor{3cc1}
@deffn {Fonction} turtle.clearstamps (n=None)

@*Paramètres: 
@code{n} -- un entier (ou @code{None})


Supprime tous, les `n' premiers ou les `n' derniers tampons de la tortue. Si `n' est @code{None}, supprime tous les tampons, si `n' > 0, supprime les `n' premiers tampons et si n < 0, supprime les `n' derniers tampons.

@example
>>> for i in range(8):
...     unused_stamp_id = turtle.stamp()
...     turtle.fd(30)
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()
@end example
@end deffn

@geindex undo() (dans le module turtle)
@anchor{library/turtle turtle undo}@anchor{3cc2}
@deffn {Fonction} turtle.undo ()

Annule la ou les dernières (si répété) actions de la tortue. Le nombre d'annulations disponible est déterminé par la taille de la mémoire tampon d'annulations.

@example
>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()
@end example
@end deffn

@geindex speed() (dans le module turtle)
@anchor{library/turtle turtle speed}@anchor{3cc3}
@deffn {Fonction} turtle.speed (speed=None)

@*Paramètres: 
@code{speed} -- un nombre entier compris dans l’intervalle entre 0 et 10 inclus, ou une chaîne de vitesse (voir ci-dessous)


Règle la vitesse de la tortue à une valeur entière comprise entre 0 et 10 inclus. Si aucun argument n'est donné, renvoie la vitesse actuelle.

Si l'entrée est un nombre supérieur à 10 ou inférieur à 0,5, la vitesse est fixée à 0. Les chaînes de vitesse sont mises en correspondance avec les valeurs de vitesse comme suit :


@itemize *

@item 
@code{"fastest"} :  0

@item 
@code{"fast"} :  10

@item 
@code{"normal"} :  6

@item 
@code{"slow"} :  3

@item 
@code{"slowest"} :  1
@end itemize

Les vitesses de 1 à 10 permettent une animation de plus en plus rapide du trait du dessin et de la rotation des tortues.

Attention : `speed' = 0 signifie qu'il n'y a `aucune' animation. `forward'/`back' font sauter la tortue et, de même, `left'/`right' font tourner la tortue instantanément.

@example
>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9
@end example
@end deffn

@node Connaître l'état de la tortue,Paramètres de mesure,Les mouvements dans le module Turtle,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle tell-turtle-s-state}@anchor{3d1b}
@subsubsection Connaître l'état de la tortue


@geindex position() (dans le module turtle)
@geindex pos() (dans le module turtle)
@anchor{library/turtle turtle position}@anchor{3cc4}
@deffn {Fonction} turtle.position ()
@anchor{library/turtle turtle pos}@anchor{3cc5}
@deffnx {Fonction} turtle.pos ()

Renvoie la position actuelle de la tortue (x,y) (en tant qu'un vecteur @code{Vec2d}).

@example
>>> turtle.pos()
(440.00,-0.00)
@end example
@end deffn

@geindex towards() (dans le module turtle)
@anchor{library/turtle turtle towards}@anchor{3cc6}
@deffn {Fonction} turtle.towards (x, y=None)

@*Paramètres: 

@itemize *

@item 
@code{x} -- un nombre, ou une paire / un vecteur de nombres, ou une instance de tortue

@item 
@code{y} -- un nombre si `x' est un nombre, sinon @code{None}
@end itemize


Renvoie l'angle entre l'orientation d'origine et la ligne formée de la position de la tortue à la position spécifiée par (x,y), le vecteur ou l'autre tortue. L'orientation d'origine dépend du mode — "standard"/"world" ou "logo".

@example
>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0
@end example
@end deffn

@geindex xcor() (dans le module turtle)
@anchor{library/turtle turtle xcor}@anchor{3cc7}
@deffn {Fonction} turtle.xcor ()

Renvoie la coordonnée x de la tortue.

@example
>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876
@end example
@end deffn

@geindex ycor() (dans le module turtle)
@anchor{library/turtle turtle ycor}@anchor{3cc8}
@deffn {Fonction} turtle.ycor ()

Renvoie la coordonnée y de la tortue.

@example
>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254
@end example
@end deffn

@geindex heading() (dans le module turtle)
@anchor{library/turtle turtle heading}@anchor{3cc9}
@deffn {Fonction} turtle.heading ()

Renvoie le cap de la tortue (la valeur dépend du mode de la tortue, voir @ref{3d0b,,mode()}).

@example
>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0
@end example
@end deffn

@geindex distance() (dans le module turtle)
@anchor{library/turtle turtle distance}@anchor{3cca}
@deffn {Fonction} turtle.distance (x, y=None)

@*Paramètres: 

@itemize *

@item 
@code{x} -- un nombre, ou une paire / un vecteur de nombres, ou une instance de tortue

@item 
@code{y} -- un nombre si `x' est un nombre, sinon @code{None}
@end itemize


Renvoie la distance entre la tortue et (x,y), le vecteur donné ou l'autre tortue donnée. La valeur est exprimée en unités de pas de tortue.

@example
>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0
@end example
@end deffn

@node Paramètres de mesure,Réglage des stylos<2>,Connaître l'état de la tortue,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle settings-for-measurement}@anchor{3d1c}
@subsubsection Paramètres de mesure


@geindex degrees() (dans le module turtle)
@anchor{library/turtle turtle degrees}@anchor{3ccb}
@deffn {Fonction} turtle.degrees (fullcircle=360.0)

@*Paramètres: 
@code{fullcircle} -- un nombre


Définit les unités de mesure des angles, c.-à-d. fixe le nombre de « degrés » pour un cercle complet. La valeur par défaut est de 360 degrés.

@example
>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0

Change angle measurement unit to grad (also known as gon,
grade, or gradian and equals 1/100-th of the right angle.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0
@end example
@end deffn

@geindex radians() (dans le module turtle)
@anchor{library/turtle turtle radians}@anchor{3ccc}
@deffn {Fonction} turtle.radians ()

Règle l'unité de mesure des angles sur radians. Équivalent à @code{degrees(2*math.pi)}.

@example
>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966
@end example

@c >>> turtle.degrees(360)
@end deffn

@node Réglage des stylos<2>,État de la tortue,Paramètres de mesure,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle id1}@anchor{3d1d}
@subsubsection Réglage des stylos


@menu
* État des stylos:: 
* Réglage des couleurs:: 
* Remplissage:: 
* Plus des réglages pour le dessin:: 

@end menu

@node État des stylos,Réglage des couleurs,,Réglage des stylos<2>
@anchor{library/turtle drawing-state}@anchor{3d1e}
@subsubsection État des stylos


@geindex pendown() (dans le module turtle)
@geindex pd() (dans le module turtle)
@geindex down() (dans le module turtle)
@anchor{library/turtle turtle pendown}@anchor{3ccd}
@deffn {Fonction} turtle.pendown ()
@anchor{library/turtle turtle pd}@anchor{3cce}
@deffnx {Fonction} turtle.pd ()
@anchor{library/turtle turtle down}@anchor{3ccf}
@deffnx {Fonction} turtle.down ()

Baisse la pointe du stylo — dessine quand il se déplace.
@end deffn

@geindex penup() (dans le module turtle)
@geindex pu() (dans le module turtle)
@geindex up() (dans le module turtle)
@anchor{library/turtle turtle penup}@anchor{3cd0}
@deffn {Fonction} turtle.penup ()
@anchor{library/turtle turtle pu}@anchor{3cd1}
@deffnx {Fonction} turtle.pu ()
@anchor{library/turtle turtle up}@anchor{3cd2}
@deffnx {Fonction} turtle.up ()

Lève la pointe du stylo  — pas de dessin quand il se déplace.
@end deffn

@geindex pensize() (dans le module turtle)
@geindex width() (dans le module turtle)
@anchor{library/turtle turtle pensize}@anchor{3cd3}
@deffn {Fonction} turtle.pensize (width=None)
@anchor{library/turtle turtle width}@anchor{3cd4}
@deffnx {Fonction} turtle.width (width=None)

@*Paramètres: 
@code{width} -- un nombre positif


Règle l'épaisseur de la ligne à `width' ou la renvoie. Si `resizemode' est défini à "auto" et que `turtleshape' (la forme de la tortue) est un polygone, le polygone est dessiné avec cette épaisseur. Si aucun argument n'est passé, la taille actuelle du stylo (`pensize') est renvoyée.

@example
>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn
@end example
@end deffn

@geindex pen() (dans le module turtle)
@anchor{library/turtle turtle pen}@anchor{3cd5}
@deffn {Fonction} turtle.pen (pen=None, **pendict)

@*Paramètres: 

@itemize *

@item 
@code{pen} -- un dictionnaire avec certaines ou toutes les clés énumérées ci-dessous

@item 
@code{pendict} -- un ou plusieurs arguments par mots-clés avec les clés suivantes comme mots-clés
@end itemize


Renvoie ou définit les attributs du stylo dans un @code{"pen-dictionary"} avec les paires clés / valeurs suivantes :


@itemize *

@item 
@code{"shown"} : @code{True} / @code{False}

@item 
@code{"pendown"} : @code{True} / @code{False}

@item 
@code{"pencolor"} : chaîne de caractères ou triplet désignant la couleur du stylo

@item 
@code{"fillcolor"} : chaîne de caractères ou triplet pour la couleur de remplissage

@item 
@code{"pensize"} : nombre positif

@item 
@code{"speed"} : nombre compris dans intervalle 0 et 10

@item 
@code{"resizemode"} : @code{"auto"}, @code{"user"} ou @code{"noresize"}

@item 
@code{"stretchfactor"} : (nombre positif, nombre positif)

@item 
@code{"outline"} : nombre positif

@item 
@code{"tilt"} : nombre
@end itemize

Ce dictionnaire peut être utilisé comme argument pour un appel ultérieur à @ref{3cd5,,pen()} pour restaurer l'ancien état du stylo. En outre, un ou plus de ces attributs peuvent est passés en tant qu'arguments nommés. Cela peut être utilisé pour définir plusieurs attributs du stylo en une instruction.

@example
>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', '@w{'}), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]
@end example
@end deffn

@geindex isdown() (dans le module turtle)
@anchor{library/turtle turtle isdown}@anchor{3cd6}
@deffn {Fonction} turtle.isdown ()

Renvoie @code{True} si la pointe du stylo est en bas et @code{False} si elle est en haut.

@example
>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True
@end example
@end deffn

@node Réglage des couleurs,Remplissage,État des stylos,Réglage des stylos<2>
@anchor{library/turtle color-control}@anchor{3d1f}
@subsubsection Réglage des couleurs


@geindex pencolor() (dans le module turtle)
@anchor{library/turtle turtle pencolor}@anchor{3cd8}
@deffn {Fonction} turtle.pencolor (*args)

Renvoie ou règle la couleur du stylo.

Quatre formats d'entrée sont autorisés :


@table @asis

@item @code{pencolor()}

Renvoie la couleur du stylo actuelle en tant que chaine de spécification de couleurs ou en tant qu'un `n'-uplet (voir l'exemple). Peut être utilisée comme entrée à un autre appel de `color'/`pencolor'/`fillcolor'.

@item @code{pencolor(colorstring)}

Définit la couleur du stylo à @code{colorstring}, qui est une chaîne de spécification de couleur `Tk', telle que @code{"red"}, @code{"yellow"}, ou @code{"#33cc8c"}.

@item @code{pencolor((r, g, b))}

Définit la couleur du stylo à la couleur RGB représentée par le `n'-uplet de `r', `g' et `b'. Chacun des `r', `g' et `b' doit être dans l'intervalle @code{0..colormode}, où `colormode' est vaut 1.0 ou 255 (voir @ref{3d0c,,colormode()}).

@item @code{pencolor(r, g, b)}

Définit la couleur du stylo à la couleur RGB représentée par `r', `g' et `b'. Chacun des `r', `g' et `b' doit être dans l'intervalle @code{0..colormode}.
@end table

Si la forme de la tortue est un polygone, le contour de ce polygone est dessiné avec la nouvelle couleur du stylo.

@example
>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51.0, 204.0, 140.0)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
@end example
@end deffn

@geindex fillcolor() (dans le module turtle)
@anchor{library/turtle turtle fillcolor}@anchor{3cd9}
@deffn {Fonction} turtle.fillcolor (*args)

Renvoie ou règle la couleur de remplissage.

Quatre formats d'entrée sont autorisés :


@table @asis

@item @code{fillcolor()}

Renvoie la couleur de remplissage actuelle (`fillcolor') en tant que chaine de spécification, possiblement en format `n'-uplet (voir l'exemple). Peut être utilisée en entrée pour un autre appel de `color'/`pencolor'/`fillcolor'.

@item @code{fillcolor(colorstring)}

Définit la couleur de remplissage (`fillcolor') à `colorstring', qui est une chaine de spécification de couleur `Tk' comme par exemple @code{"red"}, @code{"yellow"} ou @code{"#33cc8c"}.

@item @code{fillcolor((r, g, b))}

Définit la couleur du remplissage (`fillcolor') à la couleur RGB représentée par le `n'-uplet  `r', `g', `b'. Chacun des `r', `g' et `b' doit être dans l'intervalle @code{0..colormode} où `colormode' vaut 1.0 ou 255 (voir @ref{3d0c,,colormode()}).

@item @code{fillcolor(r, g, b)}

Définit la couleur du remplissage(`fillcolor') à la couleur RGB représentée par `r', `g' et `b'. Chacun des `r', `g' et `b' doit être dans l'intervalle @code{0..colormode}.
@end table

Si la forme de la tortue est un polygone, l'intérieur de ce polygone sera dessiné avec la nouvelle couleur de remplissage.

@example
>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor((50, 193, 143))  # Integers, not floats
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)
@end example
@end deffn

@geindex color() (dans le module turtle)
@anchor{library/turtle turtle color}@anchor{3cd7}
@deffn {Fonction} turtle.color (*args)

Renvoie ou règle la couleur du stylo et la couleur de remplissage.

Plusieurs formats d'entrée sont autorisés. Ils peuvent avoir de zéro jusqu'à trois arguments, employés comme suit :


@table @asis

@item @code{color()}

Renvoie la couleur du stylo actuelle et la couleur de remplissage actuelle sous forme de paire, soit de chaines de spécification de couleur, soit de `n'-uplets comme renvoyés par @ref{3cd8,,pencolor()} et @ref{3cd9,,fillcolor()}.

@item @code{color(colorstring)}, @code{color((r,g,b))}, @code{color(r,g,b)}

Les formats d'entrée sont comme dans @ref{3cd8,,pencolor()}. Définit à la fois la couleur de remplissage et la couleur du stylo à la valeur passée.

@item @code{color(colorstring1, colorstring2)}, @code{color((r1,g1,b1), (r2,g2,b2))}

Équivalent à @code{pencolor(colorstring1)} et @code{fillcolor(colorstring2)} et de manière analogue si un autre format d'entrée est utilisé.
@end table

Si la forme de la tortue est un polygone, le contour et l'intérieur de ce polygone sont dessinés avec les nouvelles couleurs.

@example
>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))
@end example
@end deffn

Voir aussi : la méthode @ref{3d0c,,colormode()} de `Screen'.

@node Remplissage,Plus des réglages pour le dessin,Réglage des couleurs,Réglage des stylos<2>
@anchor{library/turtle filling}@anchor{3d20}
@subsubsection Remplissage


@c >>> turtle.home()

@geindex filling() (dans le module turtle)
@anchor{library/turtle turtle filling}@anchor{3cda}
@deffn {Fonction} turtle.filling ()

Renvoie l'état de remplissage (@code{True} signifie en train de faire un remplissage, @code{False} sinon).

@example
>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)
@end example
@end deffn

@geindex begin_fill() (dans le module turtle)
@anchor{library/turtle turtle begin_fill}@anchor{3cdb}
@deffn {Fonction} turtle.begin_fill ()

À appeler juste avant de dessiner une forme à remplir.
@end deffn

@geindex end_fill() (dans le module turtle)
@anchor{library/turtle turtle end_fill}@anchor{3cdc}
@deffn {Fonction} turtle.end_fill ()

Remplit la forme dessinée après le dernier appel à @ref{3cdb,,begin_fill()}.

Le remplissage correct des formes complexes (polygones qui se recoupent, plusieurs formes) dépend des primitives graphiques du système d’exploitation, du type et du nombre des chevauchements. Par exemple, l'étoile (`Turtle star' en anglais) ci-dessus peut être entièrement jaune ou comporter quelques régions blanches.

@example
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
@end example
@end deffn

@node Plus des réglages pour le dessin,,Remplissage,Réglage des stylos<2>
@anchor{library/turtle more-drawing-control}@anchor{3d21}
@subsubsection Plus des réglages pour le dessin


@geindex reset() (dans le module turtle)
@anchor{library/turtle turtle reset}@anchor{3cdd}
@deffn {Fonction} turtle.reset ()

Supprime les dessins de la tortue de l'écran, recentre la tortue et assigne les variables aux valeurs par défaut.

@example
>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
@end example
@end deffn

@geindex clear() (dans le module turtle)
@anchor{library/turtle turtle clear}@anchor{3cde}
@deffn {Fonction} turtle.clear ()

Supprime les dessins de la tortue de l'écran. Ne déplace pas la tortue. L'état et la position de la tortue ainsi que les dessins des autres tortues ne sont pas affectés.
@end deffn

@geindex write() (dans le module turtle)
@anchor{library/turtle turtle write}@anchor{3cdf}
@deffn {Fonction} turtle.write (arg, move=False, align='left', font=('Arial', 8, 'normal'))

@*Paramètres: 

@itemize *

@item 
@code{arg} -- objet à écrire sur le `TurtleScreen'

@item 
@code{move} -- @code{True} / @code{False}

@item 
@code{align} -- l'une des chaînes de caractères suivantes : @code{"left"}, @code{"center"} ou @code{"right"}

@item 
@code{font} -- triplet (nom de police, taille de police, type de police)
@end itemize


Écrit du texte - La représentation de la chaîne `arg' - à la position actuelle de la tortue conformément à `align' ("`left'", "`center'" ou "`right'") et en police donnée. Si `move' est @code{True}, le stylo est déplacé vers le coin inférieur droit du texte. Par défaut, `move' est @code{False}.

@example
>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)
@end example
@end deffn

@node État de la tortue,Utilisation des événements,Réglage des stylos<2>,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle turtle-state}@anchor{3d22}
@subsubsection État de la tortue


@menu
* Visibilité:: 
* Apparence:: 

@end menu

@node Visibilité,Apparence,,État de la tortue
@anchor{library/turtle visibility}@anchor{3d23}
@subsubsection Visibilité


@geindex hideturtle() (dans le module turtle)
@geindex ht() (dans le module turtle)
@anchor{library/turtle turtle hideturtle}@anchor{3ce2}
@deffn {Fonction} turtle.hideturtle ()
@anchor{library/turtle turtle ht}@anchor{3ce3}
@deffnx {Fonction} turtle.ht ()

Rend la tortue invisible. C'est recommandé lorsque vous êtes en train de faire un dessin complexe, vous observerez alors une accélération notable.

@example
>>> turtle.hideturtle()
@end example
@end deffn

@geindex showturtle() (dans le module turtle)
@geindex st() (dans le module turtle)
@anchor{library/turtle turtle showturtle}@anchor{3ce0}
@deffn {Fonction} turtle.showturtle ()
@anchor{library/turtle turtle st}@anchor{3ce1}
@deffnx {Fonction} turtle.st ()

Rend la tortue visible.

@example
>>> turtle.showturtle()
@end example
@end deffn

@geindex isvisible() (dans le module turtle)
@anchor{library/turtle turtle isvisible}@anchor{3ce4}
@deffn {Fonction} turtle.isvisible ()

Renvoie @code{True} si la tortue est visible, et @code{False} si elle est cachée.

@example
>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True
@end example
@end deffn

@node Apparence,,Visibilité,État de la tortue
@anchor{library/turtle appearance}@anchor{3d24}
@subsubsection Apparence


@geindex shape() (dans le module turtle)
@anchor{library/turtle turtle shape}@anchor{3ce5}
@deffn {Fonction} turtle.shape (name=None)

@*Paramètres: 
@code{name} -- une chaîne de caractères qui correspond à un nom de forme valide


La tortue prend la forme `name' donnée, ou, si `name' n'est pas donné, renvoie le nom de la forme actuelle. Le nom `name' donné doit exister dans le dictionnaire de formes de `TurtleScreen'. Initialement, il y a les polygones suivants : "`arrow'", "`turtle'", "`circle'", "`square'", "`triangle'", "`classic'". Pour en apprendre plus sur comment gérer les formes, voir la méthode de `Screen' @ref{3d0f,,register_shape()}.

@example
>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'
@end example
@end deffn

@geindex resizemode() (dans le module turtle)
@anchor{library/turtle turtle resizemode}@anchor{3ce6}
@deffn {Fonction} turtle.resizemode (rmode=None)

@*Paramètres: 
@code{rmode} -- l'une des chaînes suivantes : @code{"auto"}, @code{"user"}, @code{"noresize"}


Définit `resizemode' à l'une des valeurs suivantes : "`auto'", "`user'", "`noresize'". Si "`rmode'" n'est pas donné, renvoie le `resizemode' actuel. Les différents `resizemode' ont les effets suivants :


@itemize -

@item 
`"auto"' : adapte l'apparence de la tortue en fonction de la largeur du stylo (`value of pensize' en anglais).

@item 
`"user"' : adapte l'apparence de la tortue en fonction des valeurs du paramètre d'étirement et de la largeur des contours, déterminés par @ref{3ce7,,shapesize()}.

@item 
`"noresize"' : il n'y a pas de modification de l'apparence de la tortue.
@end itemize

@code{resizemode("user")} est appelé par @ref{3ce7,,shapesize()} quand utilisé sans arguments.

@example
>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'
@end example
@end deffn

@geindex shapesize() (dans le module turtle)
@geindex turtlesize() (dans le module turtle)
@anchor{library/turtle turtle shapesize}@anchor{3ce7}
@deffn {Fonction} turtle.shapesize (stretch_wid=None, stretch_len=None, outline=None)
@anchor{library/turtle turtle turtlesize}@anchor{3ce8}
@deffnx {Fonction} turtle.turtlesize (stretch_wid=None, stretch_len=None, outline=None)

@*Paramètres: 

@itemize *

@item 
@code{stretch_wid} -- nombre positif

@item 
@code{stretch_len} -- nombre positif

@item 
@code{outline} -- nombre positif
@end itemize


Return or set the pen's attributes x/y-stretchfactors and/or outline.  Set
resizemode to "user".  If and only if resizemode is set to "user", the turtle
will be displayed stretched according to its stretchfactors: `stretch_wid' is
stretchfactor perpendicular to its orientation, `stretch_len' is
stretchfactor in direction of its orientation, `outline' determines the width
of the shape's outline.

@example
>>> turtle.shapesize()
(1.0, 1.0, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)
@end example
@end deffn

@geindex shearfactor() (dans le module turtle)
@anchor{library/turtle turtle shearfactor}@anchor{3ce9}
@deffn {Fonction} turtle.shearfactor (shear=None)

@*Paramètres: 
@code{shear} -- un nombre (facultatif)


Définit ou renvoie le paramétrage de cisaillement actuel. Déforme la tortue en fonction du paramètre `shear' donné, qui est la tangente de l'angle de cisaillement. Ne change pas le sens de déplacement de la tortue. Si le paramètre `shear' n'est pas indiqué, renvoie la valeur actuelle du cisaillement, c.-à-d. la valeur de la tangente de l'angle de cisaillement, celui par rapport auquel les lignes parallèles à la direction de la tortue sont cisaillées.

@example
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5
@end example
@end deffn

@geindex tilt() (dans le module turtle)
@anchor{library/turtle turtle tilt}@anchor{3cea}
@deffn {Fonction} turtle.tilt (angle)

@*Paramètres: 
@code{angle} -- un nombre


Tourne la forme de la tortue de `angle' depuis son angle d'inclinaison actuel, mais `ne change pas' le cap de la tortue (direction du mouvement).

@example
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)
@end example
@end deffn

@geindex tiltangle() (dans le module turtle)
@anchor{library/turtle turtle tiltangle}@anchor{70f}
@deffn {Fonction} turtle.tiltangle (angle=None)

@*Paramètres: 
@code{angle} -- un nombre (facultatif)


Définit ou renvoie l'angle d'inclinaison actuel. Si l'angle est donné, la forme de la tortue est tournée pour pointer dans direction spécifiée par l'angle, indépendamment de son angle d'inclinaison actuel. `Ne change pas' le cap de la tortue (direction du mouvement). Si l'angle n'est pas donné, renvoie l'angle d'inclinaison actuel (L'angle entre l'orientation de la forme de la tortue et le cap de la tortue (sa direction de mouvement)).

@example
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0
@end example
@end deffn

@geindex shapetransform() (dans le module turtle)
@anchor{library/turtle turtle shapetransform}@anchor{3ceb}
@deffn {Fonction} turtle.shapetransform (t11=None, t12=None, t21=None, t22=None)

@*Paramètres: 

@itemize *

@item 
@code{t11} -- un nombre (facultatif)

@item 
@code{t12} -- un nombre (facultatif)

@item 
@code{t21} -- un nombre (facultatif)

@item 
@code{t12} -- un nombre (facultatif)
@end itemize


Définit ou renvoie la matrice de transformation actuelle de la forme de la tortue.

Si aucun élément de la matrice n'est fourni, renvoie la matrice de transformation sous la forme d'un `n'-uplet à 4 éléments. Autrement, définit les éléments donnés et transforme la forme de la tortue conformément à la matrice dont la première ligne est t11, t12 et la deuxième ligne t21, t22. Le déterminant t11 * t22 - t12 * t21 ne doit pas être nul, sinon une erreur est levée. Cela modifie le facteur d'étirement, le facteur de cisaillement et l'angle d'inclinaison en fonction de la matrice donnée.

@example
>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)
@end example
@end deffn

@geindex get_shapepoly() (dans le module turtle)
@anchor{library/turtle turtle get_shapepoly}@anchor{3cec}
@deffn {Fonction} turtle.get_shapepoly ()

Renvoie la forme actuelle du polygone en `n'-uplet de paires de coordonnées. Vous pouvez l'utiliser afin de définir une nouvelle forme ou en tant que composant pour une forme plus complexe.

@example
>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))
@end example
@end deffn

@node Utilisation des événements,Méthodes spéciales de la tortue,État de la tortue,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle using-events}@anchor{3d25}
@subsubsection Utilisation des événements



@deffn {Fonction} turtle.onclick (fun, btn=1, add=None)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction à deux arguments qui sera appelée avec les coordonnées du point cliqué sur le canevas

@item 
@code{btn} -- numéro du bouton de la souris, par défaut 1 (bouton de gauche)

@item 
@code{add} -- @code{True} ou @code{False} — si @code{True}, un nouveau lien est ajouté, sinon il remplace un ancien lien
@end itemize


Crée un lien vers `fun' pour les événements de clics de la souris sur cette tortue. Si `fun' est @code{None}, les liens existants sont supprimés. Exemple pour la tortue anonyme, c'est-à-dire la manière procédurale :

@example
>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # Now clicking into the turtle will turn it.
>>> onclick(None)  # event-binding will be removed
@end example
@end deffn

@geindex onrelease() (dans le module turtle)
@anchor{library/turtle turtle onrelease}@anchor{3cee}
@deffn {Fonction} turtle.onrelease (fun, btn=1, add=None)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction à deux arguments qui sera appelée avec les coordonnées du point cliqué sur le canevas

@item 
@code{btn} -- numéro du bouton de la souris, par défaut 1 (bouton de gauche)

@item 
@code{add} -- @code{True} ou @code{False} — si @code{True}, un nouveau lien est ajouté, sinon il remplace un ancien lien
@end itemize


Crée un lien vers `fun' pour les événements de relâchement d'un clic de la souris sur cette tortue. Si `fun' est @code{None}, les liens existants sont supprimés.

@example
>>> class MyTurtle(Turtle):
...     def glow(self,x,y):
...         self.fillcolor("red")
...     def unglow(self,x,y):
...         self.fillcolor("")
...
>>> turtle = MyTurtle()
>>> turtle.onclick(turtle.glow)     # clicking on turtle turns fillcolor red,
>>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.
@end example
@end deffn

@geindex ondrag() (dans le module turtle)
@anchor{library/turtle turtle ondrag}@anchor{3cef}
@deffn {Fonction} turtle.ondrag (fun, btn=1, add=None)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction à deux arguments qui sera appelée avec les coordonnées du point cliqué sur le canevas

@item 
@code{btn} -- numéro du bouton de la souris, par défaut 1 (bouton de gauche)

@item 
@code{add} -- @code{True} ou @code{False} — si @code{True}, un nouveau lien est ajouté, sinon il remplace un ancien lien
@end itemize


Crée un lien vers `fun' pour les événements de mouvement de la souris sur cette tortue. Si `fun' est @code{None}, les liens existants sont supprimés.

Remarque : toutes les séquences d'événements de mouvement de la souris sur une tortue sont précédées par un événement de clic de la souris sur cette tortue.

@example
>>> turtle.ondrag(turtle.goto)
@end example

Par la suite, un cliquer-glisser sur la tortue la fait se déplacer au travers de l'écran, produisant ainsi des dessins « à la main » (si le stylo est posé).
@end deffn

@node Méthodes spéciales de la tortue,Formes composées,Utilisation des événements,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle special-turtle-methods}@anchor{3d26}
@subsubsection Méthodes spéciales de la tortue


@geindex begin_poly() (dans le module turtle)
@anchor{library/turtle turtle begin_poly}@anchor{3cf0}
@deffn {Fonction} turtle.begin_poly ()

Démarre l'enregistrement des sommets d'un polygone. La position actuelle de la tortue est le premier sommet du polygone.
@end deffn

@geindex end_poly() (dans le module turtle)
@anchor{library/turtle turtle end_poly}@anchor{3cf1}
@deffn {Fonction} turtle.end_poly ()

Arrête l'enregistrement des sommets d'un polygone. La position actuelle de la tortue sera le dernier sommet du polygone. Il sera connecté au premier sommet.
@end deffn

@geindex get_poly() (dans le module turtle)
@anchor{library/turtle turtle get_poly}@anchor{3cf2}
@deffn {Fonction} turtle.get_poly ()

Renvoie le dernier polygone sauvegardé.

@example
>>> turtle.home()
>>> turtle.begin_poly()
>>> turtle.fd(100)
>>> turtle.left(20)
>>> turtle.fd(30)
>>> turtle.left(60)
>>> turtle.fd(50)
>>> turtle.end_poly()
>>> p = turtle.get_poly()
>>> register_shape("myFavouriteShape", p)
@end example
@end deffn

@geindex clone() (dans le module turtle)
@anchor{library/turtle turtle clone}@anchor{3cf3}
@deffn {Fonction} turtle.clone ()

Crée et renvoie un clone de la tortue avec les mêmes position, cap et propriétés.

@example
>>> mick = Turtle()
>>> joe = mick.clone()
@end example
@end deffn

@geindex getturtle() (dans le module turtle)
@geindex getpen() (dans le module turtle)
@anchor{library/turtle turtle getturtle}@anchor{3cf4}
@deffn {Fonction} turtle.getturtle ()
@anchor{library/turtle turtle getpen}@anchor{3cf5}
@deffnx {Fonction} turtle.getpen ()

Renvoie l'objet `Turtle' lui-même. Sa seule utilisation : comme fonction pour renvoyer la "tortue anonyme" :

@example
>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>
@end example
@end deffn

@geindex getscreen() (dans le module turtle)
@anchor{library/turtle turtle getscreen}@anchor{3cf6}
@deffn {Fonction} turtle.getscreen ()

Renvoie l'objet @ref{3d27,,TurtleScreen} sur lequel la tortue dessine. Les méthodes de TurtleScreen peuvent être appelées pour cet objet.

@example
>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")
@end example
@end deffn

@geindex setundobuffer() (dans le module turtle)
@anchor{library/turtle turtle setundobuffer}@anchor{3cf7}
@deffn {Fonction} turtle.setundobuffer (size)

@*Paramètres: 
@code{size} -- un entier ou @code{None}


Définit ou désactive la mémoire d'annulation. Si `size' est un entier, une mémoire d'annulation de la taille donnée est installée. `size' donne le nombre maximum d'actions de la tortue qui peuvent être annulées par la fonction/méthode @ref{3cc2,,undo()}. Si `size' est @code{None}, la mémoire d'annulation est désactivée.

@example
>>> turtle.setundobuffer(42)
@end example
@end deffn

@geindex undobufferentries() (dans le module turtle)
@anchor{library/turtle turtle undobufferentries}@anchor{3cf8}
@deffn {Fonction} turtle.undobufferentries ()

Renvoie le nombre d'entrées dans la mémoire d'annulation.

@example
>>> while undobufferentries():
...     undo()
@end example
@end deffn

@node Formes composées,,Méthodes spéciales de la tortue,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes
@anchor{library/turtle compound-shapes}@anchor{3d28}@anchor{library/turtle compoundshapes}@anchor{3d29}
@subsubsection Formes composées


Pour utiliser des formes de tortues combinées, qui sont composées de polygones de différentes couleurs, vous devez utiliser la classe utilitaire @ref{3d2a,,Shape} explicitement comme décrit ci-dessous :


@enumerate 

@item 
Créez un objet Shape vide de type "compound".

@item 
Add as many components to this object as desired, using the
@ref{3d2b,,addcomponent()} method.

Par exemple :

@example
>>> s = Shape("compound")
>>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s.addcomponent(poly1, "red", "blue")
>>> poly2 = ((0,0),(10,-5),(-10,-5))
>>> s.addcomponent(poly2, "blue", "red")
@end example

@item 
Maintenant ajoutez la `Shape' à la liste des formes de `Screen' et utilisez la :

@example
>>> register_shape("myshape", s)
>>> shape("myshape")
@end example
@end enumerate

@cartouche
@quotation Note 
La classe @ref{3d2a,,Shape} est utilisée en interne par la méthode @ref{3d0f,,register_shape()} de différentes façons. Le développeur n'interagit avec la classe Shape `que' lorsqu'il utilise des formes composées comme montré ci-dessus !
@end quotation
@end cartouche

@node Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes,Classes publiques,Méthodes de RawTurtle/Turtle et leurs fonctions correspondantes,turtle — Tortue graphique
@anchor{library/turtle methods-of-turtlescreen-screen-and-corresponding-functions}@anchor{3d2c}
@subsubsection Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes


La plupart des exemples dans cette section font référence à une instance de TurtleScreen appelée @code{screen}.

@c >>> screen = Screen()

@menu
* Réglage de la fenêtre:: 
* Réglage de l'animation:: 
* Utilisation des événements concernant l'écran:: 
* Méthodes de saisie:: 
* Paramétrages et méthodes spéciales:: 
* Méthodes spécifiques à Screen@comma{} non héritées de TurtleScreen: Méthodes spécifiques à Screen non héritées de TurtleScreen. 

@end menu

@node Réglage de la fenêtre,Réglage de l'animation,,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes
@anchor{library/turtle window-control}@anchor{3d2d}
@subsubsection Réglage de la fenêtre


@geindex bgcolor() (dans le module turtle)
@anchor{library/turtle turtle bgcolor}@anchor{3cfa}
@deffn {Fonction} turtle.bgcolor (*args)

@*Paramètres: 
@code{args} -- chaîne spécifiant une couleur ou trois nombres dans l'intervalle `0..colormode' ou `n'-uplet de ces trois nombres


Définit ou renvoie la couleur de fond de l'écran de la tortue (`TurtleScreen' en anglais).

@example
>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)
@end example
@end deffn

@geindex bgpic() (dans le module turtle)
@anchor{library/turtle turtle bgpic}@anchor{3cfb}
@deffn {Fonction} turtle.bgpic (picname=None)

@*Paramètres: 
@code{picname} -- une chaîne de caractères, le nom d'un fichier `gif', ou @code{"nopic"}, ou @code{None}


Définit l'image de fond ou renvoie l'image de fond actuelle. Si `picname' est un nom de fichier, cette image et mis en image de fond. Si `picname' est @code{"nopic"}, l'image de fond sera supprimée si présente. SI `picname' est @code{None}, le nom du fichier de l'image de fond actuelle est renvoyé.

@example
>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"
@end example
@end deffn


@deffn {Fonction} turtle.clear ()

@cartouche
@quotation Note 
Cette méthode TurtleScreen est disponible en tant que fonction globale seulement sous le nom @code{clearscreen}. La fonction globale @code{clear} est une fonction différente dérivée de la méthode Turtle @code{clear}.
@end quotation
@end cartouche
@end deffn

@geindex clearscreen() (dans le module turtle)
@anchor{library/turtle turtle clearscreen}@anchor{3cfc}
@deffn {Fonction} turtle.clearscreen ()

Supprime tous les dessins et toutes les tortues du TurtleScreen. Réinitialise le TurtleScreen maintenant vide à son état initial : fond blanc, pas d'image de fond, pas d'événement liés, et traçage activé.
@end deffn


@deffn {Fonction} turtle.reset ()

@cartouche
@quotation Note 
Cette méthode TurtleScreen est disponible en tant que fonction globale seulement sous le nom @code{resetscreen}. La fonction globale @code{reset} est une fonction différente dérivée de la méthode Turtle @code{reset}.
@end quotation
@end cartouche
@end deffn

@geindex resetscreen() (dans le module turtle)
@anchor{library/turtle turtle resetscreen}@anchor{3cfd}
@deffn {Fonction} turtle.resetscreen ()

Remet toutes les tortues à l'écran dans leur état initial.
@end deffn

@geindex screensize() (dans le module turtle)
@anchor{library/turtle turtle screensize}@anchor{3cfe}
@deffn {Fonction} turtle.screensize (canvwidth=None, canvheight=None, bg=None)

@*Paramètres: 

@itemize *

@item 
@code{canvwidth} -- nombre entier positif, nouvelle largeur du canevas (zone sur laquelle se déplace la tortue), en pixels

@item 
@code{canvheight} -- nombre entier positif, nouvelle hauteur du canevas, en pixels

@item 
@code{bg} -- chaîne de caractères indiquant la couleur ou triplet de couleurs, nouvelle couleur de fond
@end itemize


Si aucun arguments ne sont passés, renvoie l'actuel `(canvaswidth, canvasheight)'. Sinon, redimensionne le canevas sur lequel les tortues dessinent. Ne modifiez pas la fenêtre de dessin. Pour observer les parties cachées du canevas, utilisez les barres de défilement. Avec cette méthode, on peut rendre visible les parties d'un dessin qui étaient en dehors du canevas précédemment.

@example
>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)
@end example

par exemple, chercher une tortue échappée de manière erronée
@end deffn

@geindex setworldcoordinates() (dans le module turtle)
@anchor{library/turtle turtle setworldcoordinates}@anchor{3cff}
@deffn {Fonction} turtle.setworldcoordinates (llx, lly, urx, ury)

@*Paramètres: 

@itemize *

@item 
@code{llx} -- un nombre, coordonnée x du coin inférieur gauche du canevas

@item 
@code{lly} -- un nombre, la coordonnée y du coin inférieur gauche du canevas

@item 
@code{urx} -- un nombre, la coordonnée x du coin supérieur droit du canevas

@item 
@code{ury} -- un nombre, la coordonnée y du coin supérieur droit du canevas
@end itemize


Configure un système de coordonnées défini par l'utilisateur et bascule vers le mode "world" si nécessaire. Cela effectuera un @code{screen.reset()}. Si le mode "world" est déjà actif, tous les dessins sont re-déssinés par rapport aux nouveaux coordonnées.

`ATTENTION' : dans les systèmes de coordonnées définis par l'utilisateur, les angles peuvent apparaître déformés.

@example
>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
...     left(10)
...
>>> for _ in range(8):
...     left(45); fd(2)   # a regular octagon
@end example

@c >>> screen.reset()
@c >>> for t in turtles():
@c ...      t.reset()
@end deffn

@node Réglage de l'animation,Utilisation des événements concernant l'écran,Réglage de la fenêtre,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes
@anchor{library/turtle animation-control}@anchor{3d2e}
@subsubsection Réglage de l'animation


@geindex delay() (dans le module turtle)
@anchor{library/turtle turtle delay}@anchor{3d00}
@deffn {Fonction} turtle.delay (delay=None)

@*Paramètres: 
@code{delay} -- entier positif


Définit ou renvoie le délai (`delay') de dessin en millisecondes. (Cet approximativement le temps passé entre deux mises à jour du canevas.) Plus le délai est long, plus l'animation sera lente.

Argument facultatif :

@example
>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
@end example
@end deffn

@geindex tracer() (dans le module turtle)
@anchor{library/turtle turtle tracer}@anchor{3d01}
@deffn {Fonction} turtle.tracer (n=None, delay=None)

@*Paramètres: 

@itemize *

@item 
@code{n} -- entier non-négatif

@item 
@code{delay} -- entier non-négatif
@end itemize


Active/désactive les animations des tortues et définit le délai pour mettre à jour les dessins.Si `n' est passé, seulement les n-ièmes mises à jours régulières de l'écran seront vraiment effectuées. (Peut être utilisé pour accélérer le dessin de graphiques complexes.) Lorsqu'appelé sans arguments, renvoie la valeur actuelle de `n'. Le deuxième argument définit la valeur du délai (voir @ref{3d00,,delay()}).

@example
>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2
@end example
@end deffn

@geindex update() (dans le module turtle)
@anchor{library/turtle turtle update}@anchor{3d02}
@deffn {Fonction} turtle.update ()

Effectue une mise à jour de `TurtleScreen'. À utiliser lorsque le traceur est désactivé.
@end deffn

Voir aussi la méthode @ref{3cc3,,speed()} de `RawTurtle'/`Turtle'.

@node Utilisation des événements concernant l'écran,Méthodes de saisie,Réglage de l'animation,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes
@anchor{library/turtle using-screen-events}@anchor{3d2f}
@subsubsection Utilisation des événements concernant l'écran


@geindex listen() (dans le module turtle)
@anchor{library/turtle turtle listen}@anchor{3d03}
@deffn {Fonction} turtle.listen (xdummy=None, ydummy=None)

Donne le focus à `TurtleScreen' (afin de collecter les événements clés). Des arguments factices sont fournis afin de pouvoir passer @ref{3d03,,listen()} à la méthode `onclick'.
@end deffn

@geindex onkey() (dans le module turtle)
@geindex onkeyrelease() (dans le module turtle)
@anchor{library/turtle turtle onkey}@anchor{3d04}
@deffn {Fonction} turtle.onkey (fun, key)
@anchor{library/turtle turtle onkeyrelease}@anchor{3d05}
@deffnx {Fonction} turtle.onkeyrelease (fun, key)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction sans arguments ou @code{None}

@item 
@code{key} -- une chaîne : clé (par exemple "`a'") ou clé symbole (Par exemple "`space'")
@end itemize


Lie `fun' à l'événement d'un relâchement d'une touche. Si `fun' est @code{None}, les événements liés sont supprimés. Remarque : Pour pouvoir enregistrer les événements lié au touches, TurtleScreen doit avoir le `focus' (fenêtre en premier plan). (Voir la méthode @ref{3d03,,listen()}.)

@example
>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
@end example
@end deffn

@geindex onkeypress() (dans le module turtle)
@anchor{library/turtle turtle onkeypress}@anchor{3d06}
@deffn {Fonction} turtle.onkeypress (fun, key=None)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction sans arguments ou @code{None}

@item 
@code{key} -- une chaîne : clé (par exemple "`a'") ou clé symbole (Par exemple "`space'")
@end itemize


Lie `fun' à l'événement d'un pressement de touche si `key' (touche) est donné, ou n'importe quelle touche si aucune touche n'est passée. Remarque : Pour pouvoir enregistrer des événements liés au touches, TurtleScreen doit être en premier plan. (voir la méthode @ref{3d03,,listen()}.)

@example
>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
@end example
@end deffn

@geindex onclick() (dans le module turtle)
@geindex onscreenclick() (dans le module turtle)
@anchor{library/turtle turtle onclick}@anchor{3ced}
@deffn {Fonction} turtle.onclick (fun, btn=1, add=None)
@anchor{library/turtle turtle onscreenclick}@anchor{3d07}
@deffnx {Fonction} turtle.onscreenclick (fun, btn=1, add=None)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction à deux arguments qui sera appelée avec les coordonnées du point cliqué sur le canevas

@item 
@code{btn} -- numéro du bouton de la souris, par défaut 1 (bouton de gauche)

@item 
@code{add} -- @code{True} ou @code{False} — si @code{True}, un nouveau lien est ajouté, sinon il remplace un ancien lien
@end itemize


Crée un lien vers `fun' pour les événements de clique de la souris sur cet écran. Si `fun' est @code{None}, les liens existants sont supprimés.

Exemple pour une instance de TurtleScreen nommée @code{screen} et une instance Turtle nommée @code{turtle} :

@example
>>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will
>>>                             # make the turtle move to the clicked point.
>>> screen.onclick(None)        # remove event binding again
@end example

@cartouche
@quotation Note 
Cette méthode de TurtleScreen est disponible en tant que fonction globale seulement sous le nom de @code{onscreenclick}. La fonction globale @code{onclick} est une autre fonction dérivée de la méthode Turtle @code{onclick}.
@end quotation
@end cartouche
@end deffn

@geindex ontimer() (dans le module turtle)
@anchor{library/turtle turtle ontimer}@anchor{3d08}
@deffn {Fonction} turtle.ontimer (fun, t=0)

@*Paramètres: 

@itemize *

@item 
@code{fun} -- une fonction sans arguments

@item 
@code{t} -- un nombre supérieur ou égal à 0
@end itemize


Installe un minuteur qui appelle `fun' après `t' millisecondes.

@example
>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### makes the turtle march around
>>> running = False
@end example
@end deffn

@geindex mainloop() (dans le module turtle)
@geindex done() (dans le module turtle)
@anchor{library/turtle turtle mainloop}@anchor{3d09}
@deffn {Fonction} turtle.mainloop ()
@anchor{library/turtle turtle done}@anchor{3d0a}
@deffnx {Fonction} turtle.done ()

Démarre la boucle d'événements - appelle la boucle principale de Tkinter. Doit être la dernière opération dan un programme graphique `turtle'. `Ne dois pas' être utilisé si un script est lancé depuis IDLE avec le mode @code{-n} (pas de sous processus) - pour une utilisation interactive des graphiques `turtle'

@example
>>> screen.mainloop()
@end example
@end deffn

@node Méthodes de saisie,Paramétrages et méthodes spéciales,Utilisation des événements concernant l'écran,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes
@anchor{library/turtle input-methods}@anchor{3d30}
@subsubsection Méthodes de saisie


@geindex textinput() (dans le module turtle)
@anchor{library/turtle turtle textinput}@anchor{1850}
@deffn {Fonction} turtle.textinput (title, prompt)

@*Paramètres: 

@itemize *

@item 
@code{title} -- chaîne de caractères

@item 
@code{prompt} -- chaîne de caractères
@end itemize


Fait apparaitre une fenêtre pour entrer une chaine de caractères. Le paramètre `title' est le titre de la fenêtre, `prompt' est le texte expliquant quelle information écrire. Renvoie l'entrée utilisateur sous forme de chaîne. Si le dialogue est annulé, renvoie @code{None}.

@example
>>> screen.textinput("NIM", "Name of first player:")
@end example
@end deffn

@geindex numinput() (dans le module turtle)
@anchor{library/turtle turtle numinput}@anchor{1851}
@deffn {Fonction} turtle.numinput (title, prompt, default=None, minval=None, maxval=None)

@*Paramètres: 

@itemize *

@item 
@code{title} -- chaîne de caractères

@item 
@code{prompt} -- chaîne de caractères

@item 
@code{default} -- un nombre (facultatif)

@item 
@code{minval} -- un nombre (facultatif)

@item 
@code{maxval} -- un nombre (facultatif)
@end itemize


Pop up a dialog window for input of a number. title is the title of the
dialog window, prompt is a text mostly describing what numerical information
to input. default: default value, minval: minimum value for input,
maxval: maximum value for input.
The number input must be in the range minval .. maxval if these are
given. If not, a hint is issued and the dialog remains open for
correction.
Return the number input. If the dialog is canceled,  return @code{None}.

@example
>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)
@end example
@end deffn

@node Paramétrages et méthodes spéciales,Méthodes spécifiques à Screen non héritées de TurtleScreen,Méthodes de saisie,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes
@anchor{library/turtle settings-and-special-methods}@anchor{3d31}
@subsubsection Paramétrages et méthodes spéciales


@geindex mode() (dans le module turtle)
@anchor{library/turtle turtle mode}@anchor{3d0b}
@deffn {Fonction} turtle.mode (mode=None)

@*Paramètres: 
@code{mode} -- l'une des chaînes de caractères : @code{"standard"}, @code{"logo"} ou @code{"world"}


Règle le mode de la tortue ("`standard'", "`logo'" ou "`world'") et la réinitialise. Si le mode n'est pas donné, le mode actuel est renvoyé.

Le mode "`standard'" est compatible avec l'ancien @ref{100,,turtle}. Le mode "`logo'" est compatible avec la plupart des graphiques `turtle' Logo. Le mode "`world'" utilise des "coordonnées monde" (`world coordinates') définis par l'utilisateur. `Attention' : Dans ce mode, les angles apparaissent déformés si le ratio unitaire de @code{x/y} n'est pas 1.


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 
@headitem

Mode

@tab

Orientation initiale de la tortue

@tab

angles positifs

@item

"standard"

@tab

vers la droite (vers l'Est)

@tab

dans le sens inverse des aiguilles d'une montre

@item

"logo"

@tab

vers le haut (vers le Nord)

@tab

dans le sens des aiguilles d'une montre

@end multitable


@example
>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'
@end example
@end deffn

@geindex colormode() (dans le module turtle)
@anchor{library/turtle turtle colormode}@anchor{3d0c}
@deffn {Fonction} turtle.colormode (cmode=None)

@*Paramètres: 
@code{cmode} -- l'une des valeurs suivantes : 1.0 ou 255


Renvoie le mode de couleur (`colormode') ou le définit à 1.0 ou 255. Les valeurs `r', `g' et `b' doivent aussi être dans la gamme @code{0}..`cmode'.

@example
>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
     ...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)
@end example
@end deffn

@geindex getcanvas() (dans le module turtle)
@anchor{library/turtle turtle getcanvas}@anchor{3d0d}
@deffn {Fonction} turtle.getcanvas ()

Renvoie le canevas de ce TurtleScreen. Utile pour les initiés qui savent quoi faire avec un canevas Tkinter.

@example
>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>
@end example
@end deffn

@geindex getshapes() (dans le module turtle)
@anchor{library/turtle turtle getshapes}@anchor{3d0e}
@deffn {Fonction} turtle.getshapes ()

Renvoie une liste de noms de toutes les formes actuellement disponibles pour les tortues.

@example
>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']
@end example
@end deffn

@geindex register_shape() (dans le module turtle)
@geindex addshape() (dans le module turtle)
@anchor{library/turtle turtle register_shape}@anchor{3d0f}
@deffn {Fonction} turtle.register_shape (name, shape=None)
@anchor{library/turtle turtle addshape}@anchor{3d10}
@deffnx {Fonction} turtle.addshape (name, shape=None)

Il existe trois façons différentes d’appeler cette fonction :


@enumerate 

@item 
`name' est le nom d'un fichier `gif' et `shape' est @code{None} : Installe la forme d'image correspondante.

@example
>>> screen.register_shape("turtle.gif")
@end example

@cartouche
@quotation Note 
Les formes d'images `ne tournent pas' lorsque la tortue tourne, donc elles n'indiquent pas le cap de la tortue !
@end quotation
@end cartouche

@item 
`name' est une chaîne de caractères arbitraire et `shape' est un `n'-uplet de paires de coordonnées : Installe le polygone correspondant.

@example
>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
@end example

@item 
`name' is an arbitrary string and `shape' is a (compound) @ref{3d2a,,Shape}
object: Install the corresponding compound shape.
@end enumerate

Ajoute une forme de tortue a la liste des formes du TurtleScreen. Seulement les formes enregistrées de cette façon peuvent être utilisée avec la commande @code{shape(shapename)}.
@end deffn

@geindex turtles() (dans le module turtle)
@anchor{library/turtle turtle turtles}@anchor{3d11}
@deffn {Fonction} turtle.turtles ()

Renvoie la liste des tortues présentes sur l'écran.

@example
>>> for turtle in screen.turtles():
...     turtle.color("red")
@end example
@end deffn

@geindex window_height() (dans le module turtle)
@anchor{library/turtle turtle window_height}@anchor{3d12}
@deffn {Fonction} turtle.window_height ()

Renvoie la hauteur de la fenêtre de la tortue.

@example
>>> screen.window_height()
480
@end example
@end deffn

@geindex window_width() (dans le module turtle)
@anchor{library/turtle turtle window_width}@anchor{3d13}
@deffn {Fonction} turtle.window_width ()

Renvoie la largeur de la fenêtre de la tortue.

@example
>>> screen.window_width()
640
@end example
@end deffn

@node Méthodes spécifiques à Screen non héritées de TurtleScreen,,Paramétrages et méthodes spéciales,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes
@anchor{library/turtle methods-specific-to-screen-not-inherited-from-turtlescreen}@anchor{3d32}@anchor{library/turtle screenspecific}@anchor{3d33}
@subsubsection Méthodes spécifiques à Screen, non héritées de TurtleScreen


@geindex bye() (dans le module turtle)
@anchor{library/turtle turtle bye}@anchor{3d14}
@deffn {Fonction} turtle.bye ()

Éteins la fenêtre `turtlegraphics'.
@end deffn

@geindex exitonclick() (dans le module turtle)
@anchor{library/turtle turtle exitonclick}@anchor{3d15}
@deffn {Fonction} turtle.exitonclick ()

Lie la méthode @code{bye()} à un clique de souris sur l'écran (`Screen').

Si la valeur de "`using_IDLE'" dans le dictionnaire de configuration est @code{False} (valeur par défaut), démarre aussi la boucle principale. Remarque : Si IDLE est lancé avec l'option @code{-n} (Pas de sous processus), Cette valeur devrait être définie à @code{True} dans @code{turtle.cfg}. Dans ce cas, la boucle principale d'IDLE est active aussi pour le script du client.
@end deffn

@geindex setup() (dans le module turtle)
@anchor{library/turtle turtle setup}@anchor{3d16}
@deffn {Fonction} turtle.setup (width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])

Définit la taille et la position de la fenêtre principale. Les valeurs par défaut des arguments sont stockées dans le dictionnaire de configuration et peuvent être modifiées via un fichier @code{turtle.cfg}.

@*Paramètres: 

@itemize *

@item 
@code{width} -- s'il s'agit d'un nombre entier, une taille en pixels, s'il s'agit d'un nombre flottant, une fraction de l'écran ; la valeur par défaut est de 50 % de l'écran

@item 
@code{height} -- s'il s'agit d'un nombre entier, la hauteur en pixels, s'il s'agit d'un nombre flottant, une fraction de l'écran ; la valeur par défaut est 75 % de l'écran

@item 
@code{startx} -- s'il s'agit d'un nombre positif, position de départ en pixels à partir du bord gauche de l'écran, s'il s'agit d'un nombre négatif, position de départ en pixels à partir du bord droit, si c'est @code{None}, centre la fenêtre horizontalement

@item 
@code{starty} -- si positif, la position de départ en pixels depuis le haut de l'écran. Si négatif, depuis de bas de l'écran. Si @code{None}, Le centre de la fenêtre verticalement
@end itemize


@example
>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # sets window to 75% of screen by 50% of screen and centers
@end example
@end deffn

@geindex title() (dans le module turtle)
@anchor{library/turtle turtle title}@anchor{3d17}
@deffn {Fonction} turtle.title (titlestring)

@*Paramètres: 
@code{titlestring} -- chaîne de caractères affichée dans la barre de titre de la fenêtre graphique de la tortue


Définit le titre de la fenêtre de la tortue comme `titlestring'.

@example
>>> screen.title("Welcome to the turtle zoo!")
@end example
@end deffn

@node Classes publiques,Explication,Méthodes de TurtleScreen/Screen et leurs fonctions correspondantes,turtle — Tortue graphique
@anchor{library/turtle public-classes}@anchor{3d34}
@subsubsection Classes publiques


@geindex RawTurtle (classe dans turtle)
@geindex RawPen (classe dans turtle)
@anchor{library/turtle turtle RawTurtle}@anchor{3d35}
@deffn {Classe} turtle.RawTurtle (canvas)
@anchor{library/turtle turtle RawPen}@anchor{3d36}
@deffnx {Classe} turtle.RawPen (canvas)

@*Paramètres: 
@code{canvas} -- a @code{tkinter.Canvas}, a @ref{3d37,,ScrolledCanvas} or a
@ref{3d27,,TurtleScreen}


Crée une tortue. Cette tortue à toutes les méthodes décrites ci-dessus comme "Méthode de Turtle/RawTurtle".
@end deffn

@geindex Turtle (classe dans turtle)
@anchor{library/turtle turtle Turtle}@anchor{3d38}
@deffn {Classe} turtle.Turtle

Sous-classe de RawTurtle, à la même interface mais dessine sur un objet @code{screen} par défaut créé automatiquement lorsque nécessaire pour la première fois.
@end deffn

@geindex TurtleScreen (classe dans turtle)
@anchor{library/turtle turtle TurtleScreen}@anchor{3d27}
@deffn {Classe} turtle.TurtleScreen (cv)

@*Paramètres: 
@code{cv} -- a @code{tkinter.Canvas}


Provides screen oriented methods like @ref{3cfa,,bgcolor()} etc. that are described
above.
@end deffn

@geindex Screen (classe dans turtle)
@anchor{library/turtle turtle Screen}@anchor{3caa}
@deffn {Classe} turtle.Screen

Sous-classess de TurtleScreen, avec @ref{3d33,,quatre nouvelles méthodes}.
@end deffn

@geindex ScrolledCanvas (classe dans turtle)
@anchor{library/turtle turtle ScrolledCanvas}@anchor{3d37}
@deffn {Classe} turtle.ScrolledCanvas (master)

@*Paramètres: 
@code{master} -- certain modules Tkinter pour contenir le ScrolledCanvas, c'est à dire, un canevas Tkinter avec des barres de défilement ajoutées


Utilisé par la classe Screen, qui fournit donc automatiquement un ScrolledCanvas comme terrain de jeu pour les tortues.
@end deffn

@geindex Shape (classe dans turtle)
@anchor{library/turtle turtle Shape}@anchor{3d2a}
@deffn {Classe} turtle.Shape (type_, data)

@*Paramètres: 
@code{type_} -- l'une des chaînes suivantes : @code{"polygon"}, @code{"image"} ou @code{"compound"}


Formes de modélisation de la structure des données. La paire @code{(type_, data)} doit suivre cette spécification :


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

`type_'

@tab

`données'

@item

"polygon"

@tab

un polygone `n'-uplet, c'est-à-dire un `n'-uplet constitué de paires (chaque paire définissant des coordonnées)

@item

"image"

@tab

une image (utilisée uniquement en interne sous ce format !)

@item

"compound"

@tab

@code{None} (une forme composée doit être construite en utilisant la méthode @ref{3d2b,,addcomponent()})

@end multitable


@geindex addcomponent() (méthode turtle.Shape)
@anchor{library/turtle turtle Shape addcomponent}@anchor{3d2b}
@deffn {Méthode} addcomponent (poly, fill, outline=None)

@*Paramètres: 

@itemize *

@item 
@code{poly} -- un polygone, c.-à-d. un `n'-uplet de paires de nombres

@item 
@code{fill} -- une couleur de remplissage pour `poly'

@item 
@code{outline} -- une couleur pour le contour du polygone (si elle est donnée)
@end itemize


Exemple :

@example
>>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... add more components and then use register_shape()
@end example

Voir @ref{3d29,,Formes composées}.
@end deffn
@end deffn

@geindex Vec2D (classe dans turtle)
@anchor{library/turtle turtle Vec2D}@anchor{3d1a}
@deffn {Classe} turtle.Vec2D (x, y)

Une classe de vecteur bidimensionnel, utilisée en tant que classe auxiliaire pour implémenter les graphiques `turtle'. Peut être utile pour les programmes graphiques faits avec `turtle'. Dérivé des `n'-uplets, donc un vecteur est un `n'-uplet !

Permet (pour les vecteurs `a', `b' et le nombre `k') :


@itemize *

@item 
@code{a + b} addition de vecteurs

@item 
@code{a - b} soustraction de deux vecteurs

@item 
@code{a * b} produit scalaire

@item 
@code{k * a} et @code{a * k} multiplication avec un scalaire

@item 
@code{abs(a)} valeur absolue de a

@item 
@code{a.rotate(angle)} rotation
@end itemize
@end deffn

@node Explication,Aide et configuration,Classes publiques,turtle — Tortue graphique
@anchor{library/turtle explanation}@anchor{3d39}@anchor{library/turtle turtle-explanation}@anchor{3ca9}
@subsubsection Explication


A turtle object draws on a screen object, and there a number of key classes in
the turtle object-oriented interface that can be used to create them and relate
them to each other.

A @ref{3d38,,Turtle} instance will automatically create a @ref{3caa,,Screen}
instance if one is not already present.

@code{Turtle} is a subclass of @ref{3d35,,RawTurtle}, which `doesn't' automatically
create a drawing surface - a `canvas' will need to be provided or created for
it. The `canvas' can be a @code{tkinter.Canvas}, @ref{3d37,,ScrolledCanvas}
or @ref{3d27,,TurtleScreen}.

@ref{3d27,,TurtleScreen} is the basic drawing surface for a
turtle. @ref{3caa,,Screen} is a subclass of @code{TurtleScreen}, and
includes @ref{3d33,,some additional methods} for managing its
appearance (including size and title) and behaviour. @code{TurtleScreen}'s
constructor needs a @code{tkinter.Canvas} or a
@ref{3d37,,ScrolledCanvas} as an argument.

The functional interface for turtle graphics uses the various methods of
@code{Turtle} and @code{TurtleScreen}/@code{Screen}. Behind the scenes, a screen
object is automatically created whenever a function derived from a @code{Screen}
method is called. Similarly, a turtle object is automatically created
whenever any of the functions derived from a Turtle method is called.

To use multiple turtles on a screen, the object-oriented interface must be
used.

@node Aide et configuration,turtledemo — Scripts de démonstration,Explication,turtle — Tortue graphique
@anchor{library/turtle help-and-configuration}@anchor{3d3a}
@subsubsection Aide et configuration


@menu
* Utilisation de l'aide:: 
* Traduction de chaînes de documents en différentes langues:: 
* Comment configurer Screen et Turtle:: 

@end menu

@node Utilisation de l'aide,Traduction de chaînes de documents en différentes langues,,Aide et configuration
@anchor{library/turtle how-to-use-help}@anchor{3d3b}
@subsubsection Utilisation de l'aide


Les méthodes publiques des classes `Screen' et `Turtle' sont largement documentées dans les `docstrings'. Elles peuvent donc être utilisées comme aide en ligne via les fonctions d'aide de Python :


@itemize -

@item 
Lors de l'utilisation d'IDLE, des info-bulles apparaissent avec la signature et les premières lignes de `docstring' de la fonction/méthode appelée.

@item 
L'appel de @ref{8c4,,help()} sur les méthodes ou fonctions affichera les `docstrings' :

@example
>>> help(Screen.bgcolor)
Help on method bgcolor in module turtle:

bgcolor(self, *args) unbound turtle.Screen method
    Set or return backgroundcolor of the TurtleScreen.

    Arguments (if given): a color string or three numbers
    in the range 0..colormode or a 3-tuple of such numbers.


    >>> screen.bgcolor("orange")
    >>> screen.bgcolor()
    "orange"
    >>> screen.bgcolor(0.5,0,0.5)
    >>> screen.bgcolor()
    "#800080"

>>> help(Turtle.penup)
Help on method penup in module turtle:

penup(self) unbound turtle.Turtle method
    Pull the pen up -- no drawing when moving.

    Aliases: penup | pu | up

    No argument

    >>> turtle.penup()
@end example

@item 
Les `docstrings' des fonctions qui sont dérivées des méthodes ont une forme modifiée :

@example
>>> help(bgcolor)
Help on function bgcolor in module turtle:

bgcolor(*args)
    Set or return backgroundcolor of the TurtleScreen.

    Arguments (if given): a color string or three numbers
    in the range 0..colormode or a 3-tuple of such numbers.

    Example::

      >>> bgcolor("orange")
      >>> bgcolor()
      "orange"
      >>> bgcolor(0.5,0,0.5)
      >>> bgcolor()
      "#800080"

>>> help(penup)
Help on function penup in module turtle:

penup()
    Pull the pen up -- no drawing when moving.

    Aliases: penup | pu | up

    No argument

    Example:
    >>> penup()
@end example
@end itemize

Ces chaînes de documents modifiées sont créées automatiquement avec les définitions de fonctions qui sont dérivées des méthodes au moment de l'importation.

@node Traduction de chaînes de documents en différentes langues,Comment configurer Screen et Turtle,Utilisation de l'aide,Aide et configuration
@anchor{library/turtle translation-of-docstrings-into-different-languages}@anchor{3d3c}
@subsubsection Traduction de chaînes de documents en différentes langues


Il est utile de créer un dictionnaire dont les clés sont les noms des méthodes et les valeurs sont les `docstrings' de méthodes publiques des classes Screen et Turtle.

@geindex write_docstringdict() (dans le module turtle)
@anchor{library/turtle turtle write_docstringdict}@anchor{3d3d}
@deffn {Fonction} turtle.write_docstringdict (filename='turtle_docstringdict')

@*Paramètres: 
@code{filename} -- une chaîne de caractères, utilisée en tant que nom de fichier


Crée et écrit un dictionnaire de `docstrings' dans un script Python avec le nom donné. Cette fonction doit être appelée explicitement (elle n'est pas utilisée par les classes graphiques de `turtle'). Ce dictionnaire de `doctrings' sera écrit dans le script Python @code{`filename'.py}. Il sert de modèle pour la traduction des `docstrings' dans différentes langues.
@end deffn

Si vous (ou vos étudiants) veulent utiliser @ref{100,,turtle} avec de l'aide en ligne dans votre langue natale, vous devez traduire les `docstrings' et sauvegarder les fichiers résultants en, par exemple, @code{turtle_docstringdict_german.py}.

Si vous avez une entrée appropriée dans votre fichier @code{turtle.cfg}, ce dictionnaire est lu au moment de l'importation et remplace la `docstrings' originale en anglais par cette entrée.

Au moment de l'écriture de cette documentation, il n'existe seulement que des `docstrings' en Allemand et Italien. (Merci de faire vos demandes à @email{glingl@@aon.at}.)

@node Comment configurer Screen et Turtle,,Traduction de chaînes de documents en différentes langues,Aide et configuration
@anchor{library/turtle how-to-configure-screen-and-turtles}@anchor{3d3e}
@subsubsection Comment configurer `Screen' et `Turtle'


La configuration par défaut imite l'apparence et le comportement de l'ancien module `turtle' pour pouvoir maintenir la meilleure compatibilité avec celui-ci.

Si vous voulez utiliser une configuration différente qui reflète mieux les fonctionnalités de ce module ou qui correspond mieux à vos besoins, par exemple pour un cours, vous pouvez préparer un ficher de configuration @code{turtle.cfg} qui sera lu au moment de l'importation et qui modifiera la configuration en utilisant les paramètres du fichier.

The built in configuration would correspond to the following @code{turtle.cfg}:

@example
width = 0.5
height = 0.75
leftright = None
topbottom = None
canvwidth = 400
canvheight = 300
mode = standard
colormode = 1.0
delay = 10
undobuffersize = 1000
shape = classic
pencolor = black
fillcolor = black
resizemode = noresize
visible = True
language = english
exampleturtle = turtle
examplescreen = screen
title = Python Turtle Graphics
using_IDLE = False
@end example

Brève explication des entrées sélectionnées :


@itemize -

@item 
The first four lines correspond to the arguments of the @ref{3d16,,Screen.setup}
method.

@item 
Line 5 and 6 correspond to the arguments of the method
@ref{3cfe,,Screen.screensize}.

@item 
`shape' peut être n'importe quelle forme native, par exemple `arrow', `turtle' etc. Pour plus d'informations, essayez @code{help(shape)}.

@item 
If you want to use no fill color (i.e. make the turtle transparent), you have
to write @code{fillcolor = ""} (but all nonempty strings must not have quotes in
the cfg file).

@item 
Si vous voulez refléter l'état de la tortue, vous devez utiliser @code{resizemode = auto}.

@item 
If you set e.g. @code{language = italian} the docstringdict
@code{turtle_docstringdict_italian.py} will be loaded at import time (if
present on the import path, e.g. in the same directory as @ref{100,,turtle}).

@item 
Les entrées `exampleturtle' et `examplescreen' définissent les noms de ces objets tels qu'ils apparaissent dans les `docstrings'. La transformation des méthodes-`docstrings' vers fonction-`docstrings' supprimera ces noms des `docstrings'.

@item 
`using_IDLE': Set this to @code{True} if you regularly work with IDLE and its @code{-n}
switch ("no subprocess").  This will prevent @ref{3d15,,exitonclick()} to enter the
mainloop.
@end itemize

Il peut y avoir un @code{turtle.cfg} dans le dossier où se situe @ref{100,,turtle} et un autre dans le dossier de travail courant. Ce dernier prendra le dessus.

Le dossier @code{Lib/turtledemo} contient un fichier @code{turtle.cfg}. Vous pouvez le prendre comme exemple et voir ses effets lorsque vous lancez les démos (il est préférable de ne pas le faire depuis la visionneuse de démos).

@node turtledemo — Scripts de démonstration,Modifications depuis Python 2 6,Aide et configuration,turtle — Tortue graphique
@anchor{library/turtle module-turtledemo}@anchor{101}@anchor{library/turtle turtledemo-demo-scripts}@anchor{3d3f}
@subsubsection @code{turtledemo} — Scripts de démonstration


@geindex module; turtledemo

Le paquet @ref{101,,turtledemo} inclut un ensemble de scripts de démonstration. Ces scripts peuvent être lancés et observés en utilisant la visionneuse de démos comme suit :

@example
python -m turtledemo
@end example

Alternativement, vous pouvez lancer les scripts de démo individuellement. Par exemple

@example
python -m turtledemo.bytedesign
@end example

Le paquet @ref{101,,turtledemo} contient :


@itemize -

@item 
Une visionneuse @code{__main__.py} qui peut être utilisée pour lire le code source de ces scripts et pour les faire tourner en même temps.

@item 
Plusieurs script présentent les différentes fonctionnalités du module @ref{100,,turtle}. Les exemples peuvent être consultés via le menu `Examples'. Ils peuvent aussi être lancés de manière autonome.

@item 
Un fichier exemple @code{turtle.cfg} montrant comment rédiger de tels fichiers.
@end itemize

Les scripts de démonstration sont :


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Nom

@tab

Description

@tab

Caractéristiques

@item

`bytedesign'

@tab

motif complexe de la tortue graphique classique

@tab

@ref{3d01,,tracer()}, temps mort, @ref{3d02,,update()}

@item

chaos

@tab

graphiques dynamiques de Verhulst, cela démontre que les calculs de l'ordinateur peuvent générer des résultats qui vont parfois à l'encontre du bon sens

@tab

`world coordinates'

@item

`clock'

@tab

horloge analogique indiquant l'heure de votre ordinateur

@tab

tortues sous forme des aiguilles d'horloge, sur minuterie

@item

`colormixer' (mélangeur de couleurs)

@tab

des expériences en rouge, vert, bleu

@tab

@ref{3cef,,ondrag()}

@item

`forest' (forêt)

@tab

3 arbres tracés par un parcours en largeur

@tab

`randomization' (répartition aléatoire)

@item

`fractalcurves'

@tab

Courbes de Hilbert et de Koch

@tab

récursivité

@item

`lindenmayer'

@tab

ethnomathématiques (kolams indiens)

@tab

`L-Système'

@item

`minimal_hanoi'

@tab

Tours de Hanoï

@tab

Des tortues rectangulaires à la place des disques (`shape', `shapesize')

@item

`nim'

@tab

jouez au classique jeu de `nim' avec trois piles de bâtons contre l'ordinateur.

@tab

tortues en tant que bâtons de `nim', géré par des événements (clavier et souris)

@item

`paint' (peinture)

@tab

programme de dessin extra minimaliste

@tab

@ref{3ced,,onclick()}

@item

`peace' (paix)

@tab

basique

@tab

tortue : apparence et animation

@item

`penrose'

@tab

tuiles apériodiques avec cerfs-volants et fléchettes

@tab

@ref{3cbf,,stamp()}

@item

`planet_and_moon' (planète et lune)

@tab

simulation d'un système gravitationnel

@tab

formes composées, @ref{3d1a,,Vec2D}

@item

rosette

@tab

un motif issu de l'article de `wikipedia' sur la tortue graphique

@tab

@ref{3cf3,,clone()},
@ref{3cc2,,undo()}

@item

`round_dance'

@tab

tortues dansantes tournant par paires en sens inverse

@tab

formes composées, clones de la forme (`shapesize'), rotation, `get_shapepoly', `update'

@item

`sorting_animate'

@tab

démonstration visuelle des différentes méthodes de classement

@tab

alignement simple, répartition aléatoire

@item

`tree' (arbre)

@tab

un arbre (tracé) par un parcours en largeur (à l’aide de générateurs)

@tab

@ref{3cf3,,clone()}

@item

`two_canvases' (deux toiles)

@tab

design simple

@tab

tortues sur deux canevas

@item

`yinyang'

@tab

un autre exemple élémentaire

@tab

@ref{3cbd,,circle()}

@end multitable


Amusez-vous !

@node Modifications depuis Python 2 6,Modifications depuis Python 3 0,turtledemo — Scripts de démonstration,turtle — Tortue graphique
@anchor{library/turtle changes-since-python-2-6}@anchor{3d40}
@subsubsection Modifications depuis Python 2.6



@itemize -

@item 
The methods @ref{3d01,,Turtle.tracer}, @ref{3d13,,Turtle.window_width} and
@ref{3d12,,Turtle.window_height} have been eliminated.
Methods with these names and functionality are now available only
as methods of @ref{3caa,,Screen}. The functions derived from these remain
available. (In fact already in Python 2.6 these methods were merely
duplications of the corresponding
@ref{3d27,,TurtleScreen}/@ref{3caa,,Screen} methods.)

@item 
The method @code{Turtle.fill()} has been eliminated.
The behaviour of @ref{3cdb,,begin_fill()} and @ref{3cdc,,end_fill()}
have changed slightly: now every filling process must be completed with an
@code{end_fill()} call.

@item 
A method @ref{3cda,,Turtle.filling} has been added. It returns a boolean
value: @code{True} if a filling process is under way, @code{False} otherwise.
This behaviour corresponds to a @code{fill()} call without arguments in
Python 2.6.
@end itemize

@node Modifications depuis Python 3 0,,Modifications depuis Python 2 6,turtle — Tortue graphique
@anchor{library/turtle changes-since-python-3-0}@anchor{3d41}
@subsubsection Modifications depuis Python 3.0



@itemize -

@item 
The @ref{3d38,,Turtle} methods @ref{3ce9,,shearfactor()}, @ref{3ceb,,shapetransform()} and
@ref{3cec,,get_shapepoly()} have been added. Thus the full range of
regular linear transforms is now available for transforming turtle shapes.
@ref{70f,,tiltangle()} has been enhanced in functionality: it now can
be used to get or set the tilt angle.

@item 
The @ref{3caa,,Screen} method @ref{3d06,,onkeypress()} has been added as a complement to
@ref{3d04,,onkey()}. As the latter binds actions to the key release event,
an alias: @ref{3d05,,onkeyrelease()} was also added for it.

@item 
The method @ref{3d09,,Screen.mainloop} has been added,
so there is no longer a need to use the standalone @ref{3d09,,mainloop()} function
when working with @ref{3caa,,Screen} and @ref{3d38,,Turtle} objects.

@item 
Two input methods have been added: @ref{1850,,Screen.textinput} and
@ref{1851,,Screen.numinput}. These pop up input dialogs and return
strings and numbers respectively.

@item 
Deux exemples de scripts @code{tdemo_nim.py} et @code{tdemo_round_dance.py} ont été ajoutés au répertoire @code{Lib/turtledemo}.
@end itemize

@c >>> for turtle in turtles():
@c ...      turtle.reset()
@c >>> turtle.penup()
@c >>> turtle.goto(-200,25)
@c >>> turtle.pendown()
@c >>> turtle.write("No one expects the Spanish Inquisition!",
@c ...      font=("Arial", 20, "normal"))
@c >>> turtle.penup()
@c >>> turtle.goto(-100,-50)
@c >>> turtle.pendown()
@c >>> turtle.write("Our two chief Turtles are...",
@c ...      font=("Arial", 16, "normal"))
@c >>> turtle.penup()
@c >>> turtle.goto(-450,-75)
@c >>> turtle.write(str(turtles()))

@node cmd --- Support for line-oriented command interpreters,shlex --- Simple lexical analysis,turtle — Tortue graphique,Cadriciels d'applications
@anchor{library/cmd doc}@anchor{3d42}@anchor{library/cmd cmd-support-for-line-oriented-command-interpreters}@anchor{3d43}@anchor{library/cmd module-cmd}@anchor{19}
@subsection @code{cmd} --- Support for line-oriented command interpreters


@geindex module; cmd

`Code source:' Lib/cmd.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/cmd.py}


__________________________________________________________________


La @ref{164f,,Cmd} fournit une base simple permettant d'écrire des interpréteurs en ligne de commande. Ceux-ci sont souvent utiles pour piloter des tests, pour des outils administratifs, et pour des prototypes destinés à être intégrés à une interface plus sophistiquée.

@geindex Cmd (classe dans cmd)
@anchor{library/cmd cmd Cmd}@anchor{164f}
@deffn {Classe} cmd.Cmd (completekey='tab', stdin=None, stdout=None)

Une instance de @ref{164f,,Cmd} ou d'une classe en héritant est un `framework' orienté ligne de commande. Il n'y a pas de bonne raison d'instancier @ref{164f,,Cmd} directement. Elle est plutôt utile en tant que classe mère d'une classe-interprète que vous définirez afin d'hériter des méthodes de @ref{164f,,Cmd} et d'encapsuler les opérations.

L'argument facultatif `completekey' est le nom @ref{b9,,readline} d'une touche de complétion. Si `completekey' ne vaut pas @ref{660,,None} et que @ref{b9,,readline} est disponible, la complétion de commandes est faite automatiquement.

The default, @code{'tab'}, is treated specially, so that it refers to the
@code{Tab} key on every @ref{1638,,readline.backend}.
Specifically, if @ref{1638,,readline.backend} is @code{editline},
@code{Cmd} will use @code{'^I'} instead of @code{'tab'}.
Note that other values are not treated this way, and might only work
with a specific backend.

Les arguments facultatifs `stdin' et `stdout' spécifient les objets-fichiers de lecture et d'écriture que l'instance de Cmd ou d'une classe fille utilisera comme entrée et sortie. Si ces arguments ne sont pas spécifiés, ils prendront comme valeur par défaut @ref{527,,sys.stdin} et @ref{ac4,,sys.stdout}.

Si vous souhaitez qu'un `stdin' donné soit utilisé, assurez-vous que l'attribut @ref{3d44,,use_rawinput} de l'instance vaille @code{False}, faute de quoi `stdin' sera ignoré.


Modifié dans la version 3.13: @code{completekey='tab'} is replaced by @code{'^I'} for @code{editline}.

@end deffn

@menu
* Objets Cmd:: 
* Exemple: Exemple<13>. 

@end menu

@node Objets Cmd,Exemple<13>,,cmd --- Support for line-oriented command interpreters
@anchor{library/cmd cmd-objects}@anchor{3d45}@anchor{library/cmd id1}@anchor{3d46}
@subsubsection Objets Cmd


Une instance de @ref{164f,,Cmd} possède les méthodes suivantes :

@geindex cmdloop() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd cmdloop}@anchor{3d47}
@deffn {Méthode} Cmd.cmdloop (intro=None)

Affiche une invite de commande de manière répétée, accepte une entrée, soustrait un préfixe initial de l'entrée reçue et envoie aux méthodes d'opération la partie restante de l'entrée reçue.

L'argument facultatif est une bannière ou chaîne de caractères d'introduction à afficher avant la première invite de commande (il redéfinit l'attribut de classe @ref{3d48,,intro}).

Si le module @ref{b9,,readline} est chargé, l'entrée héritera automatiquement d'une édition d'historique similaire à @code{bash} (Par exemple, @code{Control-P} reviendra à la dernière commande, @code{Control-N} avancera à la suivante, @code{Control-F} déplace le curseur vers la droite, @code{Control-B} déplace le curseur vers la gauche, etc...).

Une caractère de fin de fichier est transmis via la chaîne de caractères @code{'EOF'}.

@geindex ? (question mark);in a command interpreter
@geindex ! (exclamation);in a command interpreter

An interpreter instance will recognize a command name @code{foo} if and only if it
has a method @code{do_foo()}.  As a special case, a line beginning with the
character @code{'?'} is dispatched to the method @ref{163d,,do_help()}.  As another
special case, a line beginning with the character @code{'!'} is dispatched to the
method @code{do_shell()} (if such a method is defined).

This method will return when the @ref{3d49,,postcmd()} method returns a true value.
The `stop' argument to @ref{3d49,,postcmd()} is the return value from the command's
corresponding @code{do_*()} method.

If completion is enabled, completing commands will be done automatically, and
completing of commands args is done by calling @code{complete_foo()} with
arguments `text', `line', `begidx', and `endidx'.  `text' is the string prefix
we are attempting to match: all returned matches must begin with it. `line' is
the current input line with leading whitespace removed, `begidx' and `endidx'
are the beginning and ending indexes of the prefix text, which could be used to
provide different completion depending upon which position the argument is in.
@end deffn

@geindex do_help() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd do_help}@anchor{163d}
@deffn {Méthode} Cmd.do_help (arg)

All subclasses of @ref{164f,,Cmd} inherit a predefined @code{do_help()}.  This
method, called with an argument @code{'bar'}, invokes the corresponding method
@code{help_bar()}, and if that is not present, prints the docstring of
@code{do_bar()}, if available.  With no argument, @code{do_help()} lists all
available help topics (that is, all commands with corresponding
@code{help_*()} methods or commands that have docstrings), and also lists any
undocumented commands.
@end deffn

@geindex onecmd() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd onecmd}@anchor{3d4a}
@deffn {Méthode} Cmd.onecmd (str)

Interpret the argument as though it had been typed in response to the prompt.
This may be overridden, but should not normally need to be; see the
@ref{3d4b,,precmd()} and @ref{3d49,,postcmd()} methods for useful execution hooks.  The
return value is a flag indicating whether interpretation of commands by the
interpreter should stop.  If there is a @code{do_*()} method for the command
`str', the return value of that method is returned, otherwise the return value
from the @ref{3d4c,,default()} method is returned.
@end deffn

@geindex emptyline() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd emptyline}@anchor{3d4d}
@deffn {Méthode} Cmd.emptyline ()

Méthode appelée quand une ligne vide est entrée en réponse à l'invite de commande. Si cette méthode n'est pas surchargée, elle répète la dernière commande non-vide entrée.
@end deffn

@geindex default() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd default}@anchor{3d4c}
@deffn {Méthode} Cmd.default (line)

Méthode appelée lorsque le préfixe de commande d'une ligne entrée n'est pas reconnu. Si cette méthode n'est pas surchargée, elle affiche un message d'erreur et s'arrête.
@end deffn

@geindex completedefault() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd completedefault}@anchor{3d4e}
@deffn {Méthode} Cmd.completedefault (text, line, begidx, endidx)

Method called to complete an input line when no command-specific
@code{complete_*()} method is available.  By default, it returns an empty list.
@end deffn

@geindex columnize() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd columnize}@anchor{17f4}
@deffn {Méthode} Cmd.columnize (list, displaywidth=80)

Méthode appelée pour afficher une liste de chaînes de caractères sous la forme d'un ensemble compact de colonnes. Chaque colonne est de largeur minimale. Les colonnes sont séparées par deux espaces pour faciliter la lecture.
@end deffn

@geindex precmd() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd precmd}@anchor{3d4b}
@deffn {Méthode} Cmd.precmd (line)

Méthode de rappel exécutée juste avant que la ligne de commande `line' ne soit interprétée, mais après que l'invite de commande ait été généré et affiché. Cette méthode existe afin d'être surchargée par des classes filles de @ref{164f,,Cmd}. La valeur de retour est utilisée comme la commande qui sera exécutée par la méthode @ref{3d4a,,onecmd()}. L'implémentation de @ref{3d4b,,precmd()} peut réécrire la commande ou simplement renvoyer `line' sans modification.
@end deffn

@geindex postcmd() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd postcmd}@anchor{3d49}
@deffn {Méthode} Cmd.postcmd (stop, line)

Méthode de rappel exécutée juste après qu'une commande ait été exécutée. Cette méthode existe afin d'être surchargée par des classes filles de @ref{164f,,Cmd}. `line' est la ligne de commande ayant été exécutée et `stop' est un `flag' indiquant si l'exécution sera terminée après un appel à @ref{3d49,,postcmd()}. `stop' sera la valeur de retour de @ref{3d4a,,onecmd()}. La valeur de retour de cette méthode sera utilisée comme nouvelle valeur pour le `flag' interne correspondant à `stop'. Renvoyer `False' permettra à l'interprétation de continuer.
@end deffn

@geindex preloop() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd preloop}@anchor{3d4f}
@deffn {Méthode} Cmd.preloop ()

Méthode de rappel exécutée une fois lorsque @ref{3d47,,cmdloop()} est appelée. Cette méthode existe afin d'être surchargée par des classes filles de @ref{164f,,Cmd}.
@end deffn

@geindex postloop() (méthode cmd.Cmd)
@anchor{library/cmd cmd Cmd postloop}@anchor{3d50}
@deffn {Méthode} Cmd.postloop ()

Méthode de rappel exécutée une fois lorsque @ref{3d47,,cmdloop()} va s'arrêter. Cette méthode existe afin d'être surchargée par des classes filles de @ref{164f,,Cmd}.
@end deffn

Les instances de classes filles de @ref{164f,,Cmd} possèdent des variables d'instance publiques :

@geindex prompt (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd prompt}@anchor{3d51}
@deffn {Attribut} Cmd.prompt

L'invite de commande affiché pour solliciter une entrée.
@end deffn

@geindex identchars (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd identchars}@anchor{3d52}
@deffn {Attribut} Cmd.identchars

La chaîne de caractères acceptée en tant que préfixe de commande.
@end deffn

@geindex lastcmd (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd lastcmd}@anchor{3d53}
@deffn {Attribut} Cmd.lastcmd

Le dernier préfixe de commande non-vide vu.
@end deffn

@geindex cmdqueue (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd cmdqueue}@anchor{3d54}
@deffn {Attribut} Cmd.cmdqueue

Une liste de lignes entrées en file. La liste `cmdqueue' est vérifiée dans @ref{3d47,,cmdloop()} lorsqu'une nouvelle entrée est nécessitée; si elle n'est pas vide, ses éléments seront traités dans l'ordre, comme si ils avaient entrés dans l'invite de commande.
@end deffn

@geindex intro (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd intro}@anchor{3d48}
@deffn {Attribut} Cmd.intro

Une chaîne de caractères à afficher en introduction ou bannière. Peut être surchargée en passant un argument à la méthode @ref{3d47,,cmdloop()}.
@end deffn

@geindex doc_header (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd doc_header}@anchor{3d55}
@deffn {Attribut} Cmd.doc_header

L'en-tête à afficher si la sortie de l'aide possède une section pour les commandes documentées.
@end deffn

@geindex misc_header (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd misc_header}@anchor{3d56}
@deffn {Attribut} Cmd.misc_header

The header to issue if the help output has a section for miscellaneous  help
topics (that is, there are @code{help_*()} methods without corresponding
@code{do_*()} methods).
@end deffn

@geindex undoc_header (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd undoc_header}@anchor{3d57}
@deffn {Attribut} Cmd.undoc_header

The header to issue if the help output has a section for undocumented  commands
(that is, there are @code{do_*()} methods without corresponding @code{help_*()}
methods).
@end deffn

@geindex ruler (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd ruler}@anchor{3d58}
@deffn {Attribut} Cmd.ruler

Le caractère utilisé pour afficher des lignes de séparation sous les en-têtes de messages d'aide. Si il est vide, aucune ligne de séparation n'est affichée. Par défaut, ce caractère vaut @code{'='}.
@end deffn

@geindex use_rawinput (attribut cmd.Cmd)
@anchor{library/cmd cmd Cmd use_rawinput}@anchor{3d44}
@deffn {Attribut} Cmd.use_rawinput

A flag, defaulting to true.  If true, @ref{3d47,,cmdloop()} uses @ref{12b6,,input()} to
display a prompt and read the next command; if false, @ref{ac4,,sys.stdout.write()}
and @ref{527,,sys.stdin.readline()} are used. (This means that by importing
@ref{b9,,readline}, on systems that support it, the interpreter will automatically
support @code{Emacs}-like line editing  and command-history keystrokes.)
@end deffn

@node Exemple<13>,,Objets Cmd,cmd --- Support for line-oriented command interpreters
@anchor{library/cmd cmd-example}@anchor{3d59}@anchor{library/cmd id2}@anchor{3d5a}
@subsubsection Exemple


Le module @ref{19,,cmd} est utile pour produire des invites de commande permettant à l'utilisateur de travailler avec un programme de manière interactive.

Cette section présente un exemple simple de comment produire une invite de commande autour de quelques commandes du module @ref{100,,turtle}.

Basic turtle commands such as @ref{3ca4,,forward()} are added to a
@ref{164f,,Cmd} subclass with method named @code{do_forward()}.  The argument is
converted to a number and dispatched to the turtle module.  The docstring is
used in the help utility provided by the shell.

The example also includes a basic record and playback facility implemented with
the @ref{3d4b,,precmd()} method which is responsible for converting the input to
lowercase and writing the commands to a file.  The @code{do_playback()} method
reads the file and adds the recorded commands to the @ref{3d54,,cmdqueue} for
immediate playback:

@example
import cmd, sys
from turtle import *

class TurtleShell(cmd.Cmd):
    intro = 'Welcome to the turtle shell.   Type help or ? to list commands.\n'
    prompt = '(turtle) '
    file = None

    # ----- basic turtle commands -----
    def do_forward(self, arg):
        'Move the turtle forward by the specified distance:  FORWARD 10'
        forward(*parse(arg))
    def do_right(self, arg):
        'Turn turtle right by given number of degrees:  RIGHT 20'
        right(*parse(arg))
    def do_left(self, arg):
        'Turn turtle left by given number of degrees:  LEFT 90'
        left(*parse(arg))
    def do_goto(self, arg):
        'Move turtle to an absolute position with changing orientation.  GOTO 100 200'
        goto(*parse(arg))
    def do_home(self, arg):
        'Return turtle to the home position:  HOME'
        home()
    def do_circle(self, arg):
        'Draw circle with given radius an options extent and steps:  CIRCLE 50'
        circle(*parse(arg))
    def do_position(self, arg):
        'Print the current turtle position:  POSITION'
        print('Current position is %d %d\n' % position())
    def do_heading(self, arg):
        'Print the current turtle heading in degrees:  HEADING'
        print('Current heading is %d\n' % (heading(),))
    def do_color(self, arg):
        'Set the color:  COLOR BLUE'
        color(arg.lower())
    def do_undo(self, arg):
        'Undo (repeatedly) the last turtle action(s):  UNDO'
    def do_reset(self, arg):
        'Clear the screen and return turtle to center:  RESET'
        reset()
    def do_bye(self, arg):
        'Stop recording, close the turtle window, and exit:  BYE'
        print('Thank you for using Turtle')
        self.close()
        bye()
        return True

    # ----- record and playback -----
    def do_record(self, arg):
        'Save future commands to filename:  RECORD rose.cmd'
        self.file = open(arg, 'w')
    def do_playback(self, arg):
        'Playback commands from a file:  PLAYBACK rose.cmd'
        self.close()
        with open(arg) as f:
            self.cmdqueue.extend(f.read().splitlines())
    def precmd(self, line):
        line = line.lower()
        if self.file and 'playback' not in line:
            print(line, file=self.file)
        return line
    def close(self):
        if self.file:
            self.file.close()
            self.file = None

def parse(arg):
    'Convert a series of zero or more numbers to an argument tuple'
    return tuple(map(int, arg.split()))

if __name__ == '__main__':
    TurtleShell().cmdloop()
@end example

Voici une session d'exemple avec l'invite de commande `turtle'. Elle montre les fonctions d'aide, utilise les lignes vides pour répéter des commandes et montre l'utilitaire de `playback' :

@example
Welcome to the turtle shell.   Type help or ? to list commands.

(turtle) ?

Documented commands (type help <topic>):
========================================
bye     color    goto     home  playback  record  right
circle  forward  heading  left  position  reset   undo

(turtle) help forward
Move the turtle forward by the specified distance:  FORWARD 10
(turtle) record spiral.cmd
(turtle) position
Current position is 0 0

(turtle) heading
Current heading is 0

(turtle) reset
(turtle) circle 20
(turtle) right 30
(turtle) circle 40
(turtle) right 30
(turtle) circle 60
(turtle) right 30
(turtle) circle 80
(turtle) right 30
(turtle) circle 100
(turtle) right 30
(turtle) circle 120
(turtle) right 30
(turtle) circle 120
(turtle) heading
Current heading is 180

(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 100
(turtle)
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 500
(turtle) right 90
(turtle) forward 400
(turtle) right 90
(turtle) forward 300
(turtle) playback spiral.cmd
Current position is 0 0

Current heading is 0

Current heading is 180

(turtle) bye
Thank you for using Turtle
@end example

@node shlex --- Simple lexical analysis,,cmd --- Support for line-oriented command interpreters,Cadriciels d'applications
@anchor{library/shlex doc}@anchor{3d5b}@anchor{library/shlex module-shlex}@anchor{c3}@anchor{library/shlex shlex-simple-lexical-analysis}@anchor{3d5c}
@subsection @code{shlex} --- Simple lexical analysis


@geindex module; shlex

`Code source :' Lib/shlex.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/shlex.py}


__________________________________________________________________


The @ref{cbb,,shlex} class makes it easy to write lexical analyzers for
simple syntaxes resembling that of the Unix shell.  This will often be useful
for writing minilanguages, (for example, in run control files for Python
applications) or for parsing quoted strings.

The @ref{c3,,shlex} module defines the following functions:

@geindex split() (dans le module shlex)
@anchor{library/shlex shlex split}@anchor{526}
@deffn {Fonction} shlex.split (s, comments=False, posix=True)

Split the string `s' using shell-like syntax. If `comments' is @ref{b25,,False}
(the default), the parsing of comments in the given string will be disabled
(setting the @ref{3d5d,,commenters} attribute of the
@ref{cbb,,shlex} instance to the empty string).  This function operates
in POSIX mode by default, but uses non-POSIX mode if the `posix' argument is
false.


Modifié dans la version 3.12: Passing @code{None} for `s' argument now raises an exception, rather than
reading @ref{527,,sys.stdin}.

@end deffn

@geindex join() (dans le module shlex)
@anchor{library/shlex shlex join}@anchor{a15}
@deffn {Fonction} shlex.join (split_command)

Concatenate the tokens of the list `split_command' and return a string.
This function is the inverse of @ref{526,,split()}.

@example
>>> from shlex import join
>>> print(join(['echo', '-n', 'Multiple words']))
echo -n 'Multiple words'
@end example

The returned value is shell-escaped to protect against injection
vulnerabilities (see @ref{27a,,quote()}).


Ajouté dans la version 3.8.

@end deffn

@geindex quote() (dans le module shlex)
@anchor{library/shlex shlex quote}@anchor{27a}
@deffn {Fonction} shlex.quote (s)

Return a shell-escaped version of the string `s'.  The returned value is a
string that can safely be used as one token in a shell command line, for
cases where you cannot use a list.
@anchor{library/shlex shlex-quote-warning}@anchor{3173}
@cartouche
@quotation Avertissement 
The @code{shlex} module is `only designed for Unix shells'.

The @ref{27a,,quote()} function is not guaranteed to be correct on non-POSIX
compliant shells or shells from other operating systems such as Windows.
Executing commands quoted by this module on such shells can open up the
possibility of a command injection vulnerability.

Consider using functions that pass command arguments with lists such as
@ref{b74,,subprocess.run()} with @code{shell=False}.
@end quotation
@end cartouche

This idiom would be unsafe:

@example
>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l @{@}'.format(filename)
>>> print(command)  # executed by a shell: boom!
ls -l somefile; rm -rf ~
@end example

@ref{27a,,quote()} lets you plug the security hole:

@example
>>> from shlex import quote
>>> command = 'ls -l @{@}'.format(quote(filename))
>>> print(command)
ls -l 'somefile; rm -rf ~'
>>> remote_command = 'ssh home @{@}'.format(quote(command))
>>> print(remote_command)
ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"'@w{'}
@end example

The quoting is compatible with UNIX shells and with @ref{526,,split()}:

@example
>>> from shlex import split
>>> remote_command = split(remote_command)
>>> remote_command
['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
>>> command = split(remote_command[-1])
>>> command
['ls', '-l', 'somefile; rm -rf ~']
@end example


Ajouté dans la version 3.3.

@end deffn

The @ref{c3,,shlex} module defines the following class:

@geindex shlex (classe dans shlex)
@anchor{library/shlex shlex shlex}@anchor{cbb}
@deffn {Classe} shlex.shlex (instream=None, infile=None, posix=False, punctuation_chars=False)

A @ref{cbb,,shlex} instance or subclass instance is a lexical analyzer
object.  The initialization argument, if present, specifies where to read
characters from.  It must be a file-/stream-like object with
@ref{1c13,,read()} and @ref{1c4b,,readline()} methods, or
a string.  If no argument is given, input will be taken from @code{sys.stdin}.
The second optional argument is a filename string, which sets the initial
value of the @ref{3d5e,,infile} attribute.  If the `instream'
argument is omitted or equal to @code{sys.stdin}, this second argument
defaults to "stdin".  The `posix' argument defines the operational mode:
when `posix' is not true (default), the @ref{cbb,,shlex} instance will
operate in compatibility mode.  When operating in POSIX mode,
@ref{cbb,,shlex} will try to be as close as possible to the POSIX shell
parsing rules.  The `punctuation_chars' argument provides a way to make the
behaviour even closer to how real shells parse.  This can take a number of
values: the default value, @code{False}, preserves the behaviour seen under
Python 3.5 and earlier.  If set to @code{True}, then parsing of the characters
@code{();<>|&} is changed: any run of these characters (considered punctuation
characters) is returned as a single token.  If set to a non-empty string of
characters, those characters will be used as the punctuation characters.  Any
characters in the @ref{3d5f,,wordchars} attribute that appear in
`punctuation_chars' will be removed from @ref{3d5f,,wordchars}.  See
@ref{cbc,,Improved Compatibility with Shells} for more information. `punctuation_chars'
can be set only upon @ref{cbb,,shlex} instance creation and can't be
modified later.


Modifié dans la version 3.6: The `punctuation_chars' parameter was added.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{22,,configparser}

Parser for configuration files similar to the Windows @code{.ini} files.
@end table


@menu
* shlex Objects:: 
* Parsing Rules:: 
* Improved Compatibility with Shells:: 

@end menu

@node shlex Objects,Parsing Rules,,shlex --- Simple lexical analysis
@anchor{library/shlex id1}@anchor{3d60}@anchor{library/shlex shlex-objects}@anchor{3d61}
@subsubsection shlex Objects


A @ref{cbb,,shlex} instance has the following methods:

@geindex get_token() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex get_token}@anchor{3d62}
@deffn {Méthode} shlex.get_token ()

Return a token.  If tokens have been stacked using @ref{3d63,,push_token()}, pop a
token off the stack.  Otherwise, read one from the input stream.  If reading
encounters an immediate end-of-file, @ref{3d64,,eof} is returned (the empty
string (@code{'@w{'}}) in non-POSIX mode, and @code{None} in POSIX mode).
@end deffn

@geindex push_token() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex push_token}@anchor{3d63}
@deffn {Méthode} shlex.push_token (str)

Push the argument onto the token stack.
@end deffn

@geindex read_token() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex read_token}@anchor{3d65}
@deffn {Méthode} shlex.read_token ()

Read a raw token.  Ignore the pushback stack, and do not interpret source
requests.  (This is not ordinarily a useful entry point, and is documented here
only for the sake of completeness.)
@end deffn

@geindex sourcehook() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex sourcehook}@anchor{3d66}
@deffn {Méthode} shlex.sourcehook (filename)

When @ref{cbb,,shlex} detects a source request (see @ref{3d67,,source}
below) this method is given the following token as argument, and expected
to return a tuple consisting of a filename and an open file-like object.

Normally, this method first strips any quotes off the argument.  If the result
is an absolute pathname, or there was no previous source request in effect, or
the previous source was a stream (such as @code{sys.stdin}), the result is left
alone.  Otherwise, if the result is a relative pathname, the directory part of
the name of the file immediately before it on the source inclusion stack is
prepended (this behavior is like the way the C preprocessor handles @code{#include
"file.h"}).

The result of the manipulations is treated as a filename, and returned as the
first component of the tuple, with @ref{505,,open()} called on it to yield the second
component. (Note: this is the reverse of the order of arguments in instance
initialization!)

This hook is exposed so that you can use it to implement directory search paths,
addition of file extensions, and other namespace hacks. There is no
corresponding 'close' hook, but a shlex instance will call the
@ref{1f3,,close()} method of the sourced input stream when it returns
EOF.

For more explicit control of source stacking, use the @ref{3d68,,push_source()} and
@ref{3d69,,pop_source()} methods.
@end deffn

@geindex push_source() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex push_source}@anchor{3d68}
@deffn {Méthode} shlex.push_source (newstream, newfile=None)

Push an input source stream onto the input stack.  If the filename argument is
specified it will later be available for use in error messages.  This is the
same method used internally by the @ref{3d66,,sourcehook()} method.
@end deffn

@geindex pop_source() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex pop_source}@anchor{3d69}
@deffn {Méthode} shlex.pop_source ()

Pop the last-pushed input source from the input stack. This is the same method
used internally when the lexer reaches EOF on a stacked input stream.
@end deffn

@geindex error_leader() (méthode shlex.shlex)
@anchor{library/shlex shlex shlex error_leader}@anchor{3d6a}
@deffn {Méthode} shlex.error_leader (infile=None, lineno=None)

This method generates an error message leader in the format of a Unix C compiler
error label; the format is @code{'"%s", line %d: '}, where the @code{%s} is replaced
with the name of the current source file and the @code{%d} with the current input
line number (the optional arguments can be used to override these).

This convenience is provided to encourage @ref{c3,,shlex} users to generate error
messages in the standard, parseable format understood by Emacs and other Unix
tools.
@end deffn

Instances of @ref{cbb,,shlex} subclasses have some public instance
variables which either control lexical analysis or can be used for debugging:

@geindex commenters (attribut shlex.shlex)
@anchor{library/shlex shlex shlex commenters}@anchor{3d5d}
@deffn {Attribut} shlex.commenters

The string of characters that are recognized as comment beginners. All
characters from the comment beginner to end of line are ignored. Includes just
@code{'#'} by default.
@end deffn

@geindex wordchars (attribut shlex.shlex)
@anchor{library/shlex shlex shlex wordchars}@anchor{3d5f}
@deffn {Attribut} shlex.wordchars

The string of characters that will accumulate into multi-character tokens.  By
default, includes all ASCII alphanumerics and underscore.  In POSIX mode, the
accented characters in the Latin-1 set are also included.  If
@ref{195f,,punctuation_chars} is not empty, the characters @code{~-./*?=}, which can
appear in filename specifications and command line parameters, will also be
included in this attribute, and any characters which appear in
@code{punctuation_chars} will be removed from @code{wordchars} if they are present
there. If @ref{3d6b,,whitespace_split} is set to @code{True}, this will have no
effect.
@end deffn

@geindex whitespace (attribut shlex.shlex)
@anchor{library/shlex shlex shlex whitespace}@anchor{3d6c}
@deffn {Attribut} shlex.whitespace

Characters that will be considered whitespace and skipped.  Whitespace bounds
tokens.  By default, includes space, tab, linefeed and carriage-return.
@end deffn

@geindex escape (attribut shlex.shlex)
@anchor{library/shlex shlex shlex escape}@anchor{3d6d}
@deffn {Attribut} shlex.escape

Characters that will be considered as escape. This will be only used in POSIX
mode, and includes just @code{'\'} by default.
@end deffn

@geindex quotes (attribut shlex.shlex)
@anchor{library/shlex shlex shlex quotes}@anchor{3d6e}
@deffn {Attribut} shlex.quotes

Characters that will be considered string quotes.  The token accumulates until
the same quote is encountered again (thus, different quote types protect each
other as in the shell.)  By default, includes ASCII single and double quotes.
@end deffn

@geindex escapedquotes (attribut shlex.shlex)
@anchor{library/shlex shlex shlex escapedquotes}@anchor{3d6f}
@deffn {Attribut} shlex.escapedquotes

Characters in @ref{3d6e,,quotes} that will interpret escape characters defined in
@ref{3d6d,,escape}.  This is only used in POSIX mode, and includes just @code{'"'} by
default.
@end deffn

@geindex whitespace_split (attribut shlex.shlex)
@anchor{library/shlex shlex shlex whitespace_split}@anchor{3d6b}
@deffn {Attribut} shlex.whitespace_split

If @code{True}, tokens will only be split in whitespaces.  This is useful, for
example, for parsing command lines with @ref{cbb,,shlex}, getting
tokens in a similar way to shell arguments.  When used in combination with
@ref{195f,,punctuation_chars}, tokens will be split on whitespace in addition to
those characters.


Modifié dans la version 3.8: The @ref{195f,,punctuation_chars} attribute was made compatible with the
@ref{3d6b,,whitespace_split} attribute.

@end deffn

@geindex infile (attribut shlex.shlex)
@anchor{library/shlex shlex shlex infile}@anchor{3d5e}
@deffn {Attribut} shlex.infile

The name of the current input file, as initially set at class instantiation time
or stacked by later source requests.  It may be useful to examine this when
constructing error messages.
@end deffn

@geindex instream (attribut shlex.shlex)
@anchor{library/shlex shlex shlex instream}@anchor{3d70}
@deffn {Attribut} shlex.instream

The input stream from which this @ref{cbb,,shlex} instance is reading
characters.
@end deffn

@geindex source (attribut shlex.shlex)
@anchor{library/shlex shlex shlex source}@anchor{3d67}
@deffn {Attribut} shlex.source

This attribute is @code{None} by default.  If you assign a string to it, that
string will be recognized as a lexical-level inclusion request similar to the
@code{source} keyword in various shells.  That is, the immediately following token
will be opened as a filename and input will be taken from that stream until
EOF, at which point the @ref{1f3,,close()} method of that stream will be
called and the input source will again become the original input stream.  Source
requests may be stacked any number of levels deep.
@end deffn

@geindex debug (attribut shlex.shlex)
@anchor{library/shlex shlex shlex debug}@anchor{3d71}
@deffn {Attribut} shlex.debug

If this attribute is numeric and @code{1} or more, a @ref{cbb,,shlex}
instance will print verbose progress output on its behavior.  If you need
to use this, you can read the module source code to learn the details.
@end deffn

@geindex lineno (attribut shlex.shlex)
@anchor{library/shlex shlex shlex lineno}@anchor{3d72}
@deffn {Attribut} shlex.lineno

Source line number (count of newlines seen so far plus one).
@end deffn

@geindex token (attribut shlex.shlex)
@anchor{library/shlex shlex shlex token}@anchor{3d73}
@deffn {Attribut} shlex.token

The token buffer.  It may be useful to examine this when catching exceptions.
@end deffn

@geindex eof (attribut shlex.shlex)
@anchor{library/shlex shlex shlex eof}@anchor{3d64}
@deffn {Attribut} shlex.eof

Token used to determine end of file. This will be set to the empty string
(@code{'@w{'}}), in non-POSIX mode, and to @code{None} in POSIX mode.
@end deffn

@geindex punctuation_chars (attribut shlex.shlex)
@anchor{library/shlex shlex shlex punctuation_chars}@anchor{195f}
@deffn {Attribut} shlex.punctuation_chars

A read-only property. Characters that will be considered punctuation. Runs of
punctuation characters will be returned as a single token. However, note that no
semantic validity checking will be performed: for example, '>>>' could be
returned as a token, even though it may not be recognised as such by shells.


Ajouté dans la version 3.6.

@end deffn

@node Parsing Rules,Improved Compatibility with Shells,shlex Objects,shlex --- Simple lexical analysis
@anchor{library/shlex parsing-rules}@anchor{3d74}@anchor{library/shlex shlex-parsing-rules}@anchor{3d75}
@subsubsection Parsing Rules


When operating in non-POSIX mode, @ref{cbb,,shlex} will try to obey to the
following rules.


@itemize *

@item 
Quote characters are not recognized within words (@code{Do"Not"Separate} is
parsed as the single word @code{Do"Not"Separate});

@item 
Escape characters are not recognized;

@item 
Enclosing characters in quotes preserve the literal value of all characters
within the quotes;

@item 
Closing quotes separate words (@code{"Do"Separate} is parsed as @code{"Do"} and
@code{Separate});

@item 
If @ref{3d6b,,whitespace_split} is @code{False}, any character not
declared to be a word character, whitespace, or a quote will be returned as
a single-character token. If it is @code{True}, @ref{cbb,,shlex} will only
split words in whitespaces;

@item 
EOF is signaled with an empty string (@code{'@w{'}});

@item 
It's not possible to parse empty strings, even if quoted.
@end itemize

When operating in POSIX mode, @ref{cbb,,shlex} will try to obey to the
following parsing rules.


@itemize *

@item 
Quotes are stripped out, and do not separate words (@code{"Do"Not"Separate"} is
parsed as the single word @code{DoNotSeparate});

@item 
Non-quoted escape characters (e.g. @code{'\'}) preserve the literal value of the
next character that follows;

@item 
Enclosing characters in quotes which are not part of
@ref{3d6f,,escapedquotes} (e.g. @code{"'"}) preserve the literal value
of all characters within the quotes;

@item 
Enclosing characters in quotes which are part of
@ref{3d6f,,escapedquotes} (e.g. @code{'"'}) preserves the literal value
of all characters within the quotes, with the exception of the characters
mentioned in @ref{3d6d,,escape}.  The escape characters retain its
special meaning only when followed by the quote in use, or the escape
character itself. Otherwise the escape character will be considered a
normal character.

@item 
EOF is signaled with a @ref{660,,None} value;

@item 
Quoted empty strings (@code{'@w{'}}) are allowed.
@end itemize

@node Improved Compatibility with Shells,,Parsing Rules,shlex --- Simple lexical analysis
@anchor{library/shlex improved-compatibility-with-shells}@anchor{3d76}@anchor{library/shlex improved-shell-compatibility}@anchor{cbc}
@subsubsection Improved Compatibility with Shells



Ajouté dans la version 3.6.


The @ref{c3,,shlex} class provides compatibility with the parsing performed by
common Unix shells like @code{bash}, @code{dash}, and @code{sh}.  To take advantage of
this compatibility, specify the @code{punctuation_chars} argument in the
constructor.  This defaults to @code{False}, which preserves pre-3.6 behaviour.
However, if it is set to @code{True}, then parsing of the characters @code{();<>|&}
is changed: any run of these characters is returned as a single token.  While
this is short of a full parser for shells (which would be out of scope for the
standard library, given the multiplicity of shells out there), it does allow
you to perform processing of command lines more easily than you could
otherwise.  To illustrate, you can see the difference in the following snippet:

@example
>>> import shlex
>>> text = "a && b; c && d || e; f >'abc'; (def \"ghi\")"
>>> s = shlex.shlex(text, posix=True)
>>> s.whitespace_split = True
>>> list(s)
['a', '&&', 'b;', 'c', '&&', 'd', '||', 'e;', 'f', '>abc;', '(def', 'ghi)']
>>> s = shlex.shlex(text, posix=True, punctuation_chars=True)
>>> s.whitespace_split = True
>>> list(s)
['a', '&&', 'b', ';', 'c', '&&', 'd', '||', 'e', ';', 'f', '>', 'abc', ';',
'(', 'def', 'ghi', ')']
@end example

Of course, tokens will be returned which are not valid for shells, and you'll
need to implement your own error checks on the returned tokens.

Instead of passing @code{True} as the value for the punctuation_chars parameter,
you can pass a string with specific characters, which will be used to determine
which characters constitute punctuation. For example:

@example
>>> import shlex
>>> s = shlex.shlex("a && b || c", punctuation_chars="|")
>>> list(s)
['a', '&', '&', 'b', '||', 'c']
@end example

@cartouche
@quotation Note 
When @code{punctuation_chars} is specified, the @ref{3d5f,,wordchars}
attribute is augmented with the characters @code{~-./*?=}.  That is because these
characters can appear in file names (including wildcards) and command-line
arguments (e.g. @code{--color=auto}). Hence:

@example
>>> import shlex
>>> s = shlex.shlex('~/a && b-c --color=auto || d *.py?',
...                 punctuation_chars=True)
>>> list(s)
['~/a', '&&', 'b-c', '--color=auto', '||', 'd', '*.py?']
@end example

However, to match the shell as closely as possible, it is recommended to
always use @code{posix} and @ref{3d6b,,whitespace_split} when using
@ref{195f,,punctuation_chars}, which will negate
@ref{3d5f,,wordchars} entirely.
@end quotation
@end cartouche

For best effect, @code{punctuation_chars} should be set in conjunction with
@code{posix=True}. (Note that @code{posix=False} is the default for
@ref{cbb,,shlex}.)

@node Interfaces Utilisateur Graphiques avec Tk,Outils de développement,Cadriciels d'applications,La bibliothèque standard
@anchor{library/tk doc}@anchor{3d77}@anchor{library/tk graphical-user-interfaces-with-tk}@anchor{3d78}@anchor{library/tk tkinter}@anchor{3d79}
@section Interfaces Utilisateur Graphiques avec Tk


@geindex GUI
@geindex Graphical User Interface
@geindex Tkinter
@geindex Tk

Tk/Tcl has long been an integral part of Python.  It provides a robust and
platform independent windowing toolkit, that is available to Python programmers
using the @ref{ef,,tkinter} package, and its extension, the @ref{f8,,tkinter.ttk} module.

The @ref{ef,,tkinter} package is a thin object-oriented layer on top of Tcl/Tk. To
use @ref{ef,,tkinter}, you don't need to write Tcl code, but you will need to
consult the Tk documentation, and occasionally the Tcl documentation.
@ref{ef,,tkinter} is a set of wrappers that implement the Tk widgets as Python
classes.

@ref{ef,,tkinter}'s chief virtues are that it is fast, and that it usually comes
bundled with Python. Although its standard documentation is weak, good
material is available, which includes: references, tutorials, a book and
others. @ref{ef,,tkinter} is also famous for having an outdated look and feel,
which has been vastly improved in Tk 8.5. Nevertheless, there are many other
GUI libraries that you could be interested in. The Python wiki lists several
alternative GUI frameworks and tools@footnote{https://wiki.python.org/moin/GuiProgramming}.

@menu
* tkinter: tkinter --- Python interface to Tcl/Tk. Python interface to Tcl/Tk
* tkinter.colorchooser: tkinter colorchooser --- Color choosing dialog. Color choosing dialog
* tkinter.font: tkinter font --- Tkinter font wrapper. Tkinter font wrapper
* Boîtes de dialogue Tkinter:: 
* tkinter.messagebox: tkinter messagebox --- Tkinter message prompts. Tkinter message prompts
* tkinter.scrolledtext: tkinter scrolledtext --- Scrolled Text Widget. Scrolled Text Widget
* tkinter.dnd: tkinter dnd --- Drag and drop support. Drag and drop support
* tkinter.ttk: tkinter ttk --- Tk themed widgets. Tk themed widgets
* IDLE: IDLE<64>. 

@end menu

@node tkinter --- Python interface to Tcl/Tk,tkinter colorchooser --- Color choosing dialog,,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter doc}@anchor{3d7a}@anchor{library/tkinter module-tkinter}@anchor{ef}@anchor{library/tkinter tkinter-python-interface-to-tcl-tk}@anchor{3d7b}
@subsection @code{tkinter} --- Python interface to Tcl/Tk


@geindex module; tkinter

`Code source :' Lib/tkinter/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/__init__.py}


__________________________________________________________________


Le paquet @ref{ef,,tkinter} (« interface Tk ») est l'interface Python standard de la boîte à outils d'interface utilisateur graphique (GUI) `Tcl/Tk'. `Tk' et @ref{ef,,tkinter} sont disponibles sur la plupart des plates-formes Unix, y compris macOS, ainsi que sur les systèmes Windows.

Exécuter @code{python -m tkinter} depuis la ligne de commande ouvre une fenêtre de démonstration d'une interface `Tk' simple, vous indiquant que @ref{ef,,tkinter} est correctement installé sur votre système et indiquant également quelle version de `Tcl/Tk' est installée ; vous pouvez donc lire la documentation `Tcl/Tk' spécifique à cette version.

`Tkinter' prend en charge une gamme de versions `Tcl/Tk', construites avec ou sans prise en charge des fils d'exécution multiples. La version binaire officielle de Python utilise `Tcl/Tk' 8.6 gérant les fils d'exécution multiples. Voir le code source du module @ref{3,,_tkinter} pour plus d'informations sur les versions prises en charge.

`Tkinter' n'est pas une simple enveloppe, mais ajoute une bonne partie de sa propre logique pour rendre l'expérience plus `pythonique'. Cette documentation se concentre sur ces ajouts et modifications, et se réfère à la documentation officielle de `Tcl/Tk' pour les détails qui restent inchangés.

@cartouche
@quotation Note 
`Tcl/Tk' 8.5 (2007) a introduit un ensemble moderne de composants d'interface utilisateur thématiques ainsi qu'une nouvelle API pour les utiliser. Les anciennes et les nouvelles API sont toujours disponibles. La plupart des documents que vous trouverez en ligne utilisent toujours l'ancienne API et peuvent être terriblement obsolètes.
@end quotation
@end cartouche


@subsubheading Voir aussi



@itemize *

@item 

@table @asis

@item TkDocs@footnote{https://www.tkdocs.com/}

Tutoriel complet sur la création d'interfaces utilisateur avec `Tkinter'. Explique les concepts clés et illustre les approches recommandées à l'aide de l'API moderne.
@end table

@item 

@table @asis

@item Référence *Tkinter* 8.5 : une interface graphique pour Python@footnote{https://www.tkdocs.com/shipman/}

Documentation de référence pour `Tkinter' 8.5 détaillant les classes, méthodes et options disponibles (ressource en anglais).
@end table
@end itemize

Ressources `Tcl'/Tk :


@itemize *

@item 

@table @asis

@item Commandes *Tk*@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm}

Référence complète de chacune des commandes `Tcl/Tk' sous-jacentes utilisées par `Tkinter' (ressource en anglais).
@end table

@item 

@table @asis

@item Page d'accueil de Tcl/Tk@footnote{https://www.tcl.tk}

Documentation supplémentaire et liens vers le développement principal de `Tcl/Tk'.
@end table
@end itemize

Livres :


@itemize *

@item 

@table @asis

@item Modern Tkinter for Busy Python Developers@footnote{https://tkdocs.com/book.html}

par Mark Roseman. (ISBN 978-1999149567)
@end table

@item 

@table @asis

@item Python GUI programming with Tkinter@footnote{https://www.packtpub.com/en-us/product/python-gui-programming-with-tkinter-9781788835886}

By Alan D. Moore. (ISBN 978-1788835886)
@end table

@item 

@table @asis

@item Programming Python@footnote{https://learning-python.com/about-pp4e.html}

livre de Mark Lutz, qui couvre excellemment bien `Tkinter' (ISBN 978-0596158101).
@end table

@item 

@table @asis

@item Tcl and the Tk Toolkit (2nd edition)@footnote{https://www.amazon.com/exec/obidos/ASIN/032133633X}

par John Ousterhout, inventeur de `Tcl/Tk', et Ken Jones ; ne couvre pas `Tkinter'. (ISBN 978-0321336330)
@end table
@end itemize


@menu
* Architecture:: 
* Modules Tkinter:: 
* Guide de survie Tkinter:: 
* Fils d'exécution multiples:: 
* Guide pratique:: 
* Gestionnaires de fichiers:: 

@end menu

@node Architecture,Modules Tkinter,,tkinter --- Python interface to Tcl/Tk
@anchor{library/tkinter architecture}@anchor{3d7c}
@subsubsection Architecture


`Tcl/Tk' n'est pas une bibliothèque unique mais se compose plutôt de quelques modules distincts, chacun avec des fonctionnalités distinctes et sa propre documentation officielle. Les versions binaires de Python sont également livrées avec un module complémentaire.


@table @asis

@item Tcl

`Tcl' est un langage de programmation interprété dynamique, tout comme Python. Bien qu'il puisse être utilisé seul comme langage de programmation à usage général, il est le plus souvent intégré dans les applications C en tant que moteur de script ou interface avec la boîte à outils `Tk'. La bibliothèque `Tcl' a une interface C pour créer et gérer une ou plusieurs instances d'un interpréteur `Tcl', exécuter des commandes et des scripts `Tcl' dans ces instances et ajouter des commandes personnalisées implémentées en `Tcl' ou C. Chaque interpréteur a une file d'attente d'événements et il y a facilités pour lui envoyer des événements et les traiter. Contrairement à Python, le modèle d'exécution de `Tcl' est conçu autour du multitâches coopératif, et `Tkinter' comble cette différence (voir @ref{3d7d,,Modèle de thread} pour plus de détails).

@item Tk

`Tk' est un paquet *Tcl*@footnote{https://wiki.tcl-lang.org/37432} implémenté en C qui ajoute des commandes personnalisées pour créer et manipuler des widgets d'interface graphique. Chaque objet @ref{15bf,,Tk} embarque sa propre instance d'interpréteur `Tcl' avec `Tk' chargé dedans. Les widgets de `Tk' sont très personnalisables, mais au prix d'une apparence datée. `Tk' utilise la file d'attente d'événements de `Tcl' pour générer et traiter les événements de l'interface graphique.

@item Ttk

`Themed Tk' (`Ttk') est une nouvelle famille de widgets `Tk' qui offrent une bien meilleure apparence sur différentes plates-formes que la plupart des widgets `Tk' classiques. `Ttk' est distribué dans le cadre de `Tk', à partir de la version 8.5 de `Tk'. Les liaisons Python sont fournies dans un module séparé, @ref{f8,,tkinter.ttk}.
@end table

En interne, `Tk' et Ttk utilisent les fonctionnalités du système d'exploitation sous-jacent, c'est-à-dire Xlib sur Unix/X11, Cocoa sur macOS, GDI sur Windows.

Lorsque votre application Python utilise une classe dans `Tkinter', par exemple pour créer un widget, le module @ref{ef,,tkinter} assemble d'abord une chaîne de commande `Tcl/Tk'. Il passe cette chaîne de commande `Tcl' à un module binaire interne @ref{3,,_tkinter}, qui appelle ensuite l'interpréteur `Tcl' pour l'évaluer. L'interpréteur `Tcl' appelle alors les paquets `Tk' et/ou Ttk, qui à leur tour font des appels à Xlib, Cocoa ou GDI.

@node Modules Tkinter,Guide de survie Tkinter,Architecture,tkinter --- Python interface to Tcl/Tk
@anchor{library/tkinter tkinter-modules}@anchor{3d7e}
@subsubsection Modules `Tkinter'


La prise en charge de `Tkinter' est répartie sur plusieurs modules. La plupart des applications auront besoin du module principal @ref{ef,,tkinter}, ainsi que du module @ref{f8,,tkinter.ttk}, qui fournit l'ensemble de widgets thématiques modernes et l'API :

@example
from tkinter import *
from tkinter import ttk
@end example

@geindex Tk (classe dans tkinter)
@anchor{library/tkinter tkinter Tk}@anchor{15bf}
@deffn {Classe} tkinter.Tk (screenName=None, baseName=None, className='Tk', useTk=True, sync=False, use=None)

Construit un widget `Tk' de niveau supérieur, qui est généralement la fenêtre principale d'une application, et initialise un interpréteur `Tcl' pour ce widget. Chaque instance a son propre interpréteur `Tcl' associé.

La classe @ref{15bf,,Tk} est généralement instanciée en utilisant toutes les valeurs par défaut. Cependant, les arguments nommés suivants sont actuellement reconnus :


@table @asis

@item `screenName'

Lorsqu'il est donné (sous forme de chaîne), définit la variable d'environnement 
@geindex DISPLAY
@geindex variable d'environnement; DISPLAY
@code{DISPLAY}. (X11 uniquement)

@item `baseName'

Nom du fichier de profil. Par défaut, `baseName' est dérivé du nom du programme (@code{sys.argv[0]}).

@item `className'

Nom de la classe de widget. Utilisé comme fichier de profil et aussi comme nom avec lequel `Tcl' est invoqué (`argv0' dans `interp').

@item `useTk'

S'il vaut @code{True}, initialise le sous-système `Tk'. La fonction @code{tkinter.*Tcl*()} définit ceci sur @code{False}.

@item `sync'

Si @code{True}, exécute toutes les commandes du serveur X de manière synchrone, afin que les erreurs soient signalées immédiatement. Peut être utilisé pour le débogage. (X11 uniquement)

@item `use'

Spécifie l'`id' de la fenêtre dans laquelle intégrer l'application, au lieu de la créer en tant que fenêtre de niveau supérieur indépendante. `id' doit être spécifié de la même manière que la valeur de l'option -use pour les widgets de niveau supérieur (c'est-à-dire qu'il a une forme semblable à celle renvoyée par @code{winfo_id()}).

Notez que sur certaines plates-formes, cela ne fonctionne correctement que si `id' fait référence à un cadre `Tk' ou à un niveau supérieur dont l'option -container est activée.
@end table

@ref{15bf,,Tk} reads and interprets profile files, named
@code{.`className'.tcl} and @code{.`baseName'.tcl}, into the Tcl
interpreter and calls @ref{17d,,exec()} on the contents of
@code{.`className'.py} and @code{.`baseName'.py}.  The path for the
profile files is the 
@geindex HOME
@geindex variable d'environnement; HOME
@code{HOME} environment variable or, if that
isn't defined, then @ref{275d,,os.curdir}.

@geindex tk (attribut tkinter.Tk)
@anchor{library/tkinter tkinter Tk tk}@anchor{3d7f}
@deffn {Attribut} tk

L'objet d'application `Tk' créé en instanciant @ref{15bf,,Tk}. Cela donne accès à l'interpréteur `Tcl'. Chaque widget auquel est attachée la même instance de @ref{15bf,,Tk} a la même valeur pour son attribut @ref{3d7f,,tk}.
@end deffn

@geindex master (attribut tkinter.Tk)
@anchor{library/tkinter tkinter Tk master}@anchor{3d80}
@deffn {Attribut} master

L'objet widget qui contient ce widget. Pour @ref{15bf,,Tk}, le `master' est @ref{660,,None} car c'est la fenêtre principale. Les termes `master' et `parent' sont similaires et parfois utilisés de manière interchangeable comme noms d'arguments ; cependant, appeler @code{winfo_parent()} renvoie une chaîne du nom du widget alors que @ref{3d80,,master} renvoie l'objet. `parent'/`enfant' reflète la relation arborescente tandis que `maître'/`esclave' reflète la structure du conteneur.
@end deffn

@geindex children (attribut tkinter.Tk)
@anchor{library/tkinter tkinter Tk children}@anchor{3d81}
@deffn {Attribut} children

Les descendants immédiats de ce widget en tant que @ref{253,,dict} avec les noms des widgets enfants comme clés et les objets d'instance enfants comme valeurs.
@end deffn
@end deffn

@geindex Tcl() (dans le module tkinter)
@anchor{library/tkinter tkinter Tcl}@anchor{3d82}
@deffn {Fonction} tkinter.Tcl (screenName=None, baseName=None, className='Tk', useTk=False)

La fonction @ref{3d82,,Tcl()} est une fonction fabrique qui crée un objet similaire à celui créé par la classe @ref{15bf,,Tk}, sauf qu'elle n'initialise pas le sous-système `Tk'.  Ceci est le plus souvent utile lorsque vous pilotez l'interpréteur `Tcl' dans un environnement où vous ne voulez pas créer des fenêtres de haut niveau supplémentaires, ou alors si c'est impossible (comme les systèmes Unix/Linux sans un serveur X).  Un objet créé par @ref{3d82,,Tcl()} peut avoir une fenêtre de haut niveau créée (et le sous-système `Tk' initialisé) en appelant sa méthode @code{loadtk()}.
@end deffn

Parmi les modules qui savent gérer `Tk', nous pouvons citer :


@table @asis

@item @ref{ef,,tkinter}

Module `Tkinter' principal

@item @ref{f0,,tkinter.colorchooser}

Boîte de dialogue permettant à l'utilisateur de choisir une couleur.

@item @ref{f1,,tkinter.commondialog}

Classe de base pour les boîtes de dialogue définies dans les autres modules listés ici.

@item @ref{f3,,tkinter.filedialog}

Boîtes de dialogue standard permettant à l'utilisateur de spécifier un fichier à ouvrir ou à enregistrer.

@item @ref{f4,,tkinter.font}

Utilitaires pour gérer les polices de caractères.

@item @ref{f5,,tkinter.messagebox}

Accès aux boîtes de dialogue `Tk' standard.

@item @ref{f6,,tkinter.scrolledtext}

Outil d'affichage de texte avec une barre de défilement verticale intégrée.

@item @ref{f7,,tkinter.simpledialog}

Boîtes de dialogue simples et fonctions utilitaires.

@item @ref{f8,,tkinter.ttk}

Ensemble de widgets thématiques introduit dans `Tk' 8.5, offrant des alternatives modernes à de nombreux widgets classiques du module principal @ref{ef,,tkinter}.
@end table

Modules supplémentaires :

@geindex module; _tkinter
@anchor{library/tkinter module-_tkinter}@anchor{3}

@table @asis

@item @ref{3,,_tkinter}

Module binaire qui contient l'interface de bas niveau vers `Tcl/Tk'. Il est automatiquement importé par le module principal @ref{ef,,tkinter} et ne doit jamais être utilisé directement par les programmeurs d'applications. Il s'agit généralement d'une bibliothèque partagée (ou `DLL'), mais peut dans certains cas être lié statiquement à l'interpréteur Python.

@item @ref{72,,idlelib}

Environnement de développement et d'apprentissage intégré de Python (`IDLE' pour `Integrated Development and Learning Environment'). Basé sur @ref{ef,,tkinter}.

@item @code{tkinter.constants}

Constantes symboliques pouvant être utilisées à la place des chaînes lors de la transmission de divers paramètres aux appels `Tkinter'. Importé automatiquement par le module principal @ref{ef,,tkinter}.

@item @ref{f2,,tkinter.dnd}

Gestion du glisser-déposer pour @ref{ef,,tkinter}. Il s'agit d'une méthode expérimentale qui ne sera plus maintenue lorsqu'elle sera remplacée par `Tk DND'.

@item @ref{100,,turtle}

Tortue graphique dans une fenêtre `Tk'.
@end table

@node Guide de survie Tkinter,Fils d'exécution multiples,Modules Tkinter,tkinter --- Python interface to Tcl/Tk
@anchor{library/tkinter tkinter-life-preserver}@anchor{3d83}
@subsubsection Guide de survie `Tkinter'


Cette section n'est pas conçue pour être un tutoriel exhaustif sur `Tk' ou `Tkinter'. Pour cela, reportez-vous à l'une des ressources externes mentionnées précédemment. Cette section fournit plutôt un guide très rapide sur ce à quoi ressemble une application `Tkinter', identifie les concepts fondamentaux de `Tk' et explique comment l'enveloppe `Tkinter' est structurée.

Le reste de cette section vous aidera à identifier les classes, méthodes et options dont vous aurez besoin dans votre application `Tkinter', et où trouver une documentation plus détaillée à leur sujet, y compris dans le manuel de référence officiel `Tcl/Tk'.

@menu
* Un simple programme Hello World:: 
* Concepts importants de Tk:: 
* Comprendre comment Tkinter enveloppe Tcl/Tk:: 
* Comment puis-je… ? Quelle option… ?:: 
* Navigation dans le manuel de référence Tcl/Tk:: 

@end menu

@node Un simple programme Hello World,Concepts importants de Tk,,Guide de survie Tkinter
@anchor{library/tkinter a-hello-world-program}@anchor{3d84}
@subsubsection Un simple programme `Hello World'


Nous commençons par disséquer une application `Hello World' dans `Tkinter'. Ce n'est pas le plus petit que nous puissions écrire, mais il en contient suffisamment pour illustrer certains concepts clés que vous devez connaître.

@example
from tkinter import *
from tkinter import ttk
root = Tk()
frm = ttk.Frame(root, padding=10)
frm.grid()
ttk.Label(frm, text="Hello World!").grid(column=0, row=0)
ttk.Button(frm, text="Quit", command=root.destroy).grid(column=1, row=0)
root.mainloop()
@end example

Après les importations, la ligne suivante crée une instance de la classe @code{Tk}, qui initialise `Tk' et crée son interpréteur `Tcl' associé. Elle crée également une fenêtre de niveau supérieur, connue sous le nom de fenêtre racine, qui sert de fenêtre principale de l'application.

La ligne suivante crée un widget de cadre, qui dans ce cas contiendra une étiquette et un bouton que nous créerons ensuite. Le cadre est ajusté à l'intérieur de la fenêtre racine.

La ligne suivante crée un widget d'étiquette contenant une chaîne de texte statique. La méthode @code{grid()} est utilisée pour spécifier la disposition relative (position) de l'étiquette dans son widget cadre contenant, similaire au fonctionnement des tableaux en HTML.

Un widget de bouton est alors créé et placé à droite de l'étiquette. Lorsqu'il est pressé, il appelle la méthode @code{destroy()} de la fenêtre racine.

Enfin, la méthode @code{mainloop()} affiche tout sur l'écran et répond aux entrées de l'utilisateur jusqu'à ce que le programme se termine.

@node Concepts importants de Tk,Comprendre comment Tkinter enveloppe Tcl/Tk,Un simple programme Hello World,Guide de survie Tkinter
@anchor{library/tkinter important-tk-concepts}@anchor{3d85}
@subsubsection Concepts importants de `Tk'


Même ce programme simple illustre les concepts clés suivants de `Tk' :


@table @asis

@item widgets

Une interface utilisateur `Tkinter' est composée de `widgets' individuels. Chaque widget est représenté comme un objet Python, instancié à partir de classes comme @code{ttk.Frame}, @code{ttk.Label} et @code{ttk.Button}.

@item hiérarchie des widgets

Les widgets sont organisés dans une `hiérarchie'. L'étiquette et le bouton étaient contenus dans un cadre, qui à son tour était contenu dans la fenêtre racine. Lors de la création de chaque widget `enfant', son widget `parent' est passé comme premier argument au constructeur du widget.

@item options de configuration

Les widgets ont des `options de configuration', qui modifient leur apparence et leur comportement, comme le texte à afficher dans une étiquette ou un bouton. Différentes classes de widgets auront différents ensembles d'options.

@item gestion de la géométrie

Les widgets ne sont pas automatiquement ajoutés à l'interface utilisateur lorsqu'ils sont créés. Un `gestionnaire de géométrie' comme @code{grid} contrôle où ils sont placés dans l'interface utilisateur.

@item boucle d'événements

`Tkinter' réagit aux entrées de l'utilisateur, aux modifications de votre programme et même rafraîchit l'affichage uniquement lors de l'exécution active d'une `boucle d'événements'. Si votre programme n'exécute pas la boucle d'événements, votre interface utilisateur n'est pas mise à jour.
@end table

@node Comprendre comment Tkinter enveloppe Tcl/Tk,Comment puis-je… ? Quelle option… ?,Concepts importants de Tk,Guide de survie Tkinter
@anchor{library/tkinter understanding-how-tkinter-wraps-tcl-tk}@anchor{3d86}
@subsubsection Comprendre comment `Tkinter' enveloppe `Tcl/Tk'


When your application uses Tkinter's classes and methods, internally Tkinter
is assembling strings representing Tcl/Tk commands, and executing those
commands in the Tcl interpreter attached to your application's @code{Tk}
instance.

Qu'il s'agisse d'essayer de naviguer dans la documentation de référence, d'essayer de trouver la bonne méthode ou option, d'adapter du code existant ou de déboguer votre application `Tkinter', il arrive qu'il soit utile de comprendre à quoi ressemblent ces commandes `Tcl/Tk' sous-jacentes.

Pour illustrer cette idée, voici l'équivalent `Tcl/Tk' de la partie principale du script `Tkinter' ci-dessus.

@example
ttk::frame .frm -padding 10
grid .frm
grid [ttk::label .frm.lbl -text "Hello World!"] -column 0 -row 0
grid [ttk::button .frm.btn -text "Quit" -command "destroy ."] -column 1 -row 0
@end example

La syntaxe de `Tcl' est similaire à celle de nombreux langages `shell', où le premier mot est la commande à exécuter, suivi des arguments de cette commande, séparés par des espaces. Sans entrer dans trop de détails, notez ce qui suit :


@itemize *

@item 
Les commandes utilisées pour créer des widgets (comme @code{ttk::frame}) correspondent aux classes de widgets dans `Tkinter'.

@item 
Les options du widget `Tcl' (comme @code{-text}) correspondent aux arguments de mots-clés dans `Tkinter'.

@item 
Les widgets sont référencés par un `chemin' en `Tcl' (comme @code{.frm.btn}), alors que `Tkinter' n'utilise pas de noms mais des références d'objets.

@item 
La place d'un widget dans la hiérarchie des widgets est encodée dans son nom de chemin (hiérarchique), qui utilise un @code{.} (point) comme séparateur de chemin. Le chemin d'accès à la fenêtre racine est simplement @code{.} (point). Dans `Tkinter', la hiérarchie n'est pas définie par le nom de chemin mais en spécifiant le widget parent lors de la création de chaque widget enfant.

@item 
Les opérations qui sont implémentées comme des `commandes' séparées dans `Tcl' (comme @code{grid} ou @code{destroy}) sont représentées comme des `méthodes' sur les objets widget de `Tkinter'. Comme vous le verrez bientôt, à d'autres moments, `Tcl' utilise ce qui semble être des appels de méthode sur des objets widget, qui reflètent plus fidèlement ce qui serait utilisé dans `Tkinter'.
@end itemize

@node Comment puis-je… ? Quelle option… ?,Navigation dans le manuel de référence Tcl/Tk,Comprendre comment Tkinter enveloppe Tcl/Tk,Guide de survie Tkinter
@anchor{library/tkinter how-do-i-what-option-does}@anchor{3d87}
@subsubsection Comment puis-je… ? Quelle option… ?


Si vous ne savez pas comment faire quelque chose dans `Tkinter' et que vous ne le trouvez pas immédiatement dans le didacticiel ou la documentation de référence que vous utilisez, il existe quelques stratégies qui peuvent être utiles.

Tout d'abord, rappelez-vous que les détails du fonctionnement des widgets individuels peuvent varier selon les différentes versions de `Tkinter' et de `Tcl/Tk'. Si vous recherchez de la documentation, assurez-vous qu'elle correspond aux versions Python et `Tcl/Tk' installées sur votre système.

Lorsque vous recherchez comment utiliser une API, il est utile de connaître le nom exact de la classe, de l'option ou de la méthode que vous utilisez. L'introspection, soit dans un shell Python interactif, soit avec @ref{f60,,print()}, peut vous aider à identifier ce dont vous avez besoin.

Pour savoir quelles options de configuration sont disponibles sur n'importe quel widget, appelez sa méthode @code{configure()}, qui renvoie un dictionnaire contenant une variété d'informations sur l'objet, y compris ses valeurs par défaut et actuelles. Utilisez @code{keys()} pour obtenir uniquement les noms de chaque option.

@example
btn = ttk.Button(frm, ...)
print(btn.configure().keys())
@end example

Comme la plupart des widgets ont de nombreuses options de configuration en commun, il peut être utile de savoir lesquelles sont spécifiques à une classe de widget particulière. Comparer la liste des options à celle d'un widget plus simple, comme un cadre, est une façon de faire.

@example
print(set(btn.configure().keys()) - set(frm.configure().keys()))
@end example

De même, vous pouvez trouver les méthodes disponibles pour un objet widget en utilisant la fonction standard @ref{61d,,dir()}. Si vous l'essayez, vous verrez qu'il existe plus de 200 méthodes de widget courantes donc, encore une fois, identifier celles spécifiques à une classe de widget est utile.

@example
print(dir(btn))
print(set(dir(btn)) - set(dir(frm)))
@end example

@node Navigation dans le manuel de référence Tcl/Tk,,Comment puis-je… ? Quelle option… ?,Guide de survie Tkinter
@anchor{library/tkinter navigating-the-tcl-tk-reference-manual}@anchor{3d88}
@subsubsection Navigation dans le manuel de référence `Tcl/Tk'


Comme indiqué, le manuel de référence officiel des commandes Tk@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm} (pages de manuel) est souvent la description la plus précise sur ce que font des opérations spécifiques sur les widgets. Même lorsque vous connaissez le nom de l'option ou de la méthode dont vous avez besoin, il se peut que vous ayez encore quelques endroits à chercher.

Alors que toutes les opérations dans `Tkinter' sont implémentées en tant qu'appels de méthode sur des objets widget, vous avez vu que de nombreuses opérations `Tcl/Tk' apparaissent sous forme de commandes qui prennent un chemin d'accès de widget comme premier paramètre, suivi de paramètres facultatifs, par exemple :

@example
destroy .
grid .frm.btn -column 0 -row 0
@end example

D'autres, cependant, ressemblent plus à des méthodes appelées sur un objet widget (en fait, lorsque vous créez un widget en `Tcl/Tk', il crée une commande `Tcl' avec le nom du chemin du widget, le premier paramètre de cette commande étant le nom d'une méthode à appeler).

@example
.frm.btn invoke
.frm.lbl configure -text "Goodbye"
@end example

Dans la documentation de référence officielle `Tcl/Tk', vous trouvez la plupart des opérations qui ressemblent à des appels de méthode dans la page de manuel d'un widget spécifique (par exemple, vous trouvez la méthode @code{invoke()} dans la page de manuel sur le ttk::button@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_button.htm}), tandis que les fonctions qui prennent un widget comme paramètre ont souvent leur propre page de manuel (par exemple, grid@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/grid.htm}).

Vous trouvez de nombreuses options et méthodes courantes dans les pages de manuel des options@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/options.htm} ou ttk::widget@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/ttk_widget.htm}, tandis que d'autres se trouvent dans la page de manuel d'une classe de widget spécifique.

Vous constaterez également que de nombreuses méthodes `Tkinter' ont des noms composés, par exemple @code{winfo_x()}, @code{winfo_height()}, @code{winfo_viewable()}. Vous trouverez de la documentation pour tout cela dans la page de manuel winfo@footnote{https://www.tcl.tk/man/tcl8.6/TkCmd/winfo.htm}.

@cartouche
@quotation Note 
de manière quelque peu déroutante, il existe également des méthodes sur tous les widgets `Tkinter' qui ne fonctionnent pas réellement sur le widget, mais fonctionnent à une portée globale, indépendamment de tout widget. Les méthodes d'accès au presse-papiers ou à la sonnerie du système en font partie (il se trouve qu'elles sont implémentées en tant que méthodes dans la classe de base @code{Widget} dont héritent tous les widgets `Tkinter').
@end quotation
@end cartouche

@node Fils d'exécution multiples,Guide pratique,Guide de survie Tkinter,tkinter --- Python interface to Tcl/Tk
@anchor{library/tkinter threading-model}@anchor{3d7d}
@subsubsection Fils d'exécution multiples


Python et `Tcl/Tk' gèrent les fils d'exécution multiples (`threads') de manière très différente, et @ref{ef,,tkinter} essaie de combler cette différence. Si vous utilisez des fils d'exécution multiples, vous devrez sûrement en être conscient.

Un interpréteur Python peut être associé à de nombreux fils d'exécution. En `Tcl', plusieurs fils d'exécution peuvent être créés, mais chaque fil d'exécution est associé à une instance d'interpréteur `Tcl' distincte. Les fils d'exécution multiples peuvent également créer plusieurs instances d'interpréteur, bien que chaque instance d'interpréteur ne puisse être utilisée que par le seul fil d'exécution qui l'a créée.

Chaque objet @code{Tk} créé par @ref{ef,,tkinter} contient un interpréteur `Tcl'. Il garde également une trace du fil d'exécution qui a créé cet interpréteur. Les appels à @ref{ef,,tkinter} peuvent être effectués à partir de n'importe quel fil d'exécution Python. En interne, si un appel provient d'un fil d'exécution autre que celui qui a créé l'objet @code{Tk}, un événement est posté dans la file d'attente d'événements de l'interpréteur et, lorsqu'il est exécuté, le résultat est renvoyé au fil d'exécution Python appelant.

Les applications `Tcl/Tk' sont normalement pilotées par les événements, ce qui signifie qu'après l'initialisation, l'interpréteur exécute une boucle d'événements (c'est-à-dire @code{Tk.mainloop()}) et répond aux événements. Comme il s'agit d'un seul fil d'exécution, les gestionnaires d'événements doivent répondre rapidement, sinon ils empêchent le traitement d'autres événements. Pour éviter cela, les calculs de longue durée ne doivent pas s'exécuter dans un gestionnaire d'événements, mais sont soit divisés en plus petits morceaux à l'aide de temporisateurs, soit exécutés dans un autre fil d'exécution. Ceci est différent de nombreux kits d'outils d'interface graphique où l'interface graphique s'exécute dans un fil d'exécution complètement séparé de tout le code d'application, y compris les gestionnaires d'événements.

Si l'interpréteur `Tcl' n'exécute pas la boucle d'événements et ne traite pas les événements, tout appel @ref{ef,,tkinter} effectué à partir de fils d'exécution autres que celui exécutant l'interpréteur `Tcl' échoue.

Plusieurs cas particuliers existent :


@itemize *

@item 
Les bibliothèques `Tcl/Tk' peuvent être construites de manière à ne pas gérer les fils d'exécution multiples. Dans ce cas, @ref{ef,,tkinter} appelle la bibliothèque à partir du fil d'exécution Python d'origine, même s'il est différent du fil d'exécution qui a créé l'interpréteur `Tcl'. Un verrou global garantit qu'un seul appel se produit à la fois.

@item 
Alors que @ref{ef,,tkinter} vous permet de créer plus d'une instance d'un objet @code{Tk} (avec son propre interpréteur), tous les interpréteurs qui font partie du même fil d'exécution partagent une file d'attente d'événements commune, qui devient très vite moche. En pratique, ne créez pas plus d'une instance de @code{Tk} à la fois. Sinon, il est préférable de les créer dans des fils d'exécution séparés et de vous assurer que vous exécutez une instance `Tcl/Tk' compatible avec les fils d'exécution multiples.

@item 
Le blocage des gestionnaires d'événements n'est pas le seul moyen d'empêcher l'interpréteur `Tcl' de bien gérer la boucle d'événements. Il est même possible d'exécuter plusieurs boucles d'événements imbriquées ou d'abandonner complètement la boucle d'événements. Si vous faites quelque chose de délicat en ce qui concerne les événements ou les fils d'exécution, soyez conscient de ces possibilités.

@item 
Il existe quelques fonctions select @ref{ef,,tkinter} qui ne fonctionnent actuellement que lorsqu'elles sont appelées depuis le fil d'exécution qui a créé l'interpréteur `Tcl'.
@end itemize

@node Guide pratique,Gestionnaires de fichiers,Fils d'exécution multiples,tkinter --- Python interface to Tcl/Tk
@anchor{library/tkinter handy-reference}@anchor{3d89}
@subsubsection Guide pratique


@menu
* Définition des options:: 
* L'empaqueteur:: 
* Options de l'empaqueteur:: 
* Association des variables de l'objet graphique:: 
* Le gestionnaire de fenêtres:: 
* Types de données des options Tk:: 
* Liaisons et événements:: 
* Le paramètre index:: 
* Images:: 

@end menu

@node Définition des options,L'empaqueteur,,Guide pratique
@anchor{library/tkinter setting-options}@anchor{3d8a}@anchor{library/tkinter tkinter-setting-options}@anchor{3d8b}
@subsubsection Définition des options


Les options contrôlent des paramètres tels que la couleur et la largeur de la bordure d'un objet graphique. Les options peuvent être réglées de trois façons :


@table @asis

@item Lors de la création de l'objet, à l'aide d'arguments par mots-clés

@example
fred = Button(self, fg="red", bg="blue")
@end example

@item Après la création de l'objet, en manipulant le nom de l'option comme une entrée de dictionnaire

@example
fred["fg"] = "red"
fred["bg"] = "blue"
@end example

@item Utilisez la méthode @code{config()} pour mettre à jour plusieurs attributs après la création de l'objet

@example
fred.config(fg="red", bg="blue")
@end example
@end table

Pour l'explication complète d'une option donnée et de son comportement, voir les pages de manuel `Tk' de l'objet graphique en question.

Notez que les pages de manuel listent « OPTIONS STANDARD » et « OPTIONS SPÉCIFIQUES D'OBJETS GRAPHIQUES » pour chaque objet graphique.  La première est une liste d'options communes à de nombreux objets graphiques, la seconde est une liste d'options propres à cet objet graphique particulier.  Les options standard sont documentées sur la page de manuel @code{options(3)@footnote{https://manpages.debian.org/options(3)}}.

Aucune distinction n'est faite dans ce document entre les options standard et les options spécifiques à un objet graphique.  Certaines options ne s'appliquent pas à certains types d'objets graphiques. La réaction d'un objet graphique donné à une option particulière dépend de la classe de l'objet graphique ; les boutons possèdent une option @code{command}, pas les étiquettes.

Les options gérées par un objet graphique donné sont listées dans la page de manuel de cet objet graphique, ou peuvent être interrogées à l'exécution en appelant la méthode @code{config()} sans argument, ou en appelant la méthode @code{keys()} sur cet objet graphique.  La valeur de retour de ces appels est un dictionnaire dont la clé est le nom de l'option sous forme de chaîne (par exemple, @code{'relief'}) et dont les valeurs sont des `5-uplets'.

Certaines options, comme @code{bg}, sont des synonymes d'options communes qui ont des noms longs (@code{bg} est une abréviation pour @code{background} « arrière-plan »). Passer le nom abrégé d'une option à la méthode @code{config()} renvoie un couple, pas un quintuplet. Le couple renvoyé contient le nom abrégé et le nom `réel' de l'option, par exemple  @code{('bg','background')}.


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Signification

@tab

Exemple

@item

0

@tab

nom des options

@tab

@code{'relief'}

@item

1

@tab

nom de l'option pour la recherche dans la base de données

@tab

@code{'relief'}

@item

2

@tab

classe de l'option pour la recherche dans la base de données

@tab

@code{'Relief'}

@item

3

@tab

valeur par défaut

@tab

@code{'raised'}

@item

4

@tab

valeur actuelle

@tab

@code{'groove'}

@end multitable


Exemple :

@example
>>> print(fred.config())
@{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')@}
@end example

Bien sûr, le dictionnaire affiché contient toutes les options disponibles et leurs valeurs.  Ceci n'est donné qu'à titre d'exemple.

@node L'empaqueteur,Options de l'empaqueteur,Définition des options,Guide pratique
@anchor{library/tkinter the-packer}@anchor{3d8c}
@subsubsection L'empaqueteur


@geindex packing (widgets)

L'empaqueteur est l'un des mécanismes de `Tk' pour la gestion de la disposition des éléments sur l'écran.   Les gestionnaires de géométrie sont utilisés pour spécifier le positionnement relatif du positionnement des objets graphiques dans leur conteneur — leur `constructeur' mutuel.  Contrairement au plus encombrant `placeur' (qui est utilisé moins souvent, et nous n'en parlons pas ici), l'empaqueteur prend les spécifications qualitatives de relation — `above', `to the left of', `filling', etc — et calcule tout pour déterminer les coordonnées exactes du placement pour vous.

La taille d'un objet graphique `constructeur' est déterminée par la taille des « objets graphiques hérités » à l'intérieur.  L'empaqueteur est utilisé pour contrôler l'endroit où les objets graphiques hérités apparaissent à l'intérieur du constructeur dans lequel ils sont empaquetés.  Vous pouvez regrouper des objets graphiques dans des cadres, et des cadres dans d'autres cadres, afin d'obtenir le type de mise en page souhaité. De plus, l'arrangement est ajusté dynamiquement pour s'adapter aux changements incrémentiels de la configuration, une fois qu'elle est empaquetées.

Notez que les objets graphiques n'apparaissent pas tant que leur disposition n'a pas été spécifiée avec un gestionnaire de géométrie.  C'est une erreur de débutant courante de ne pas tenir compte de la spécification de la géométrie, puis d'être surpris lorsque l'objet graphique est créé mais que rien n'apparaît.  Un objet graphique n'apparaît qu'après que, par exemple, la méthode @code{pack()} de l'empaqueteur lui ait été appliquée.

La méthode @code{pack()} peut être appelée avec des paires mot-clé-option/valeur qui contrôlent où l'objet graphique doit apparaître dans son conteneur et comment il doit se comporter lorsque la fenêtre principale de l'application est redimensionnée.  En voici quelques exemples :

@example
fred.pack()                     # defaults to side = "top"
fred.pack(side="left")
fred.pack(expand=1)
@end example

@node Options de l'empaqueteur,Association des variables de l'objet graphique,L'empaqueteur,Guide pratique
@anchor{library/tkinter packer-options}@anchor{3d8d}
@subsubsection Options de l'empaqueteur


Pour de plus amples informations sur l'empaqueteur et les options qu'il peut prendre, voir les pages de manuel et la page 183 du livre de John Ousterhout.


@table @asis

@item `anchor'

Type d'ancrage.  Indique l'endroit où l'empaqueteur doit placer chaque enfant dans son espace.

@item `expand'

Booléen, @code{0} ou @code{1}.

@item `fill'

Valeurs acceptées : @code{'x'}, @code{'y'}, @code{'both'}, @code{'none'}.

@item `ipadx' et `ipady'

Une distance — désignant l'écart interne de chaque côté de l'objet graphique hérité.

@item `padx' et `pady'

Une distance — désignant l'écart externe de chaque côté de l'objet graphique hérité.

@item `side'

Valeurs acceptées : @code{'left'}, @code{'right'}, @code{'top'}, @code{'bottom'}.
@end table

@node Association des variables de l'objet graphique,Le gestionnaire de fenêtres,Options de l'empaqueteur,Guide pratique
@anchor{library/tkinter coupling-widget-variables}@anchor{3d8e}
@subsubsection Association des variables de l'objet graphique


L'assignation d'une valeur à certains objets graphiques (comme les objets graphique de saisie de texte) peut être liée directement aux variables de votre application à l'aide d'options spéciales.  Ces options sont @code{variable}, @code{textvariable}, @code{onvalue}, @code{offvalue} et @code{value}.  Ce lien fonctionne dans les deux sens : si la variable change pour une raison ou pour une autre, l'objet graphique auquel elle est connectée est mis à jour pour refléter la nouvelle valeur.

Malheureusement, dans l'implémentation actuelle de @ref{ef,,tkinter} il n'est pas possible de passer une variable Python arbitraire à un objet graphique via une option @code{variable} ou @code{textvariable}.  Les seuls types de variables pour lesquels cela fonctionne sont les variables qui sont sous-classées à partir d'une classe appelée @code{Variable}, définie dans @ref{ef,,tkinter}.

Il existe de nombreuses sous-classes utiles de @code{Variable} déjà définies : @code{StringVar}, @code{IntVar}, @code{DoubleVar} et @code{BooleanVar}. Pour lire la valeur courante d'une telle variable, appelez la méthode @code{get()} dessus et, pour changer sa valeur, appelez la méthode @code{set()}.  Si vous suivez ce protocole, l'objet graphique suivra toujours la valeur de la variable, sans autre intervention de votre part.

Par exemple :

@example
import tkinter as tk

class App(tk.Frame):
    def __init__(self, master):
        super().__init__(master)
        self.pack()

        self.entrythingy = tk.Entry()
        self.entrythingy.pack()

        # Create the application variable.
        self.contents = tk.StringVar()
        # Set it to some value.
        self.contents.set("this is a variable")
        # Tell the entry widget to watch this variable.
        self.entrythingy["textvariable"] = self.contents

        # Define a callback for when the user hits return.
        # It prints the current value of the variable.
        self.entrythingy.bind('<Key-Return>',
                             self.print_contents)

    def print_contents(self, event):
        print("Hi. The current entry content is:",
              self.contents.get())

root = tk.Tk()
myapp = App(root)
myapp.mainloop()
@end example

@node Le gestionnaire de fenêtres,Types de données des options Tk,Association des variables de l'objet graphique,Guide pratique
@anchor{library/tkinter the-window-manager}@anchor{3d8f}
@subsubsection Le gestionnaire de fenêtres


@geindex window manager (widgets)

Dans `Tk', il y a une commande pratique, @code{wm}, pour interagir avec le gestionnaire de fenêtres.  Les options de la commande @code{wm} vous permettent de contrôler les titres, le placement, les icônes en mode `bitmap' et encore d'autres choses du même genre.  Dans @ref{ef,,tkinter}, ces commandes ont été implémentées en tant que méthodes sur la classe @code{Wm}.  Les objets graphiques de haut niveau sont sous-classés à partir de la classe @code{Wm}, ils peuvent donc appeler directement les méthodes de @code{Wm}.

Pour accéder à la fenêtre du plus haut niveau qui contient un objet graphique donné, vous pouvez souvent simplement vous référer au parent de cet objet graphique.  Bien sûr, si l'objet graphique a été empaqueté à l'intérieur d'un cadre, le parent ne représentera pas la fenêtre de plus haut niveau.  Pour accéder à la fenêtre du plus haut niveau qui contient un objet graphique arbitraire, vous pouvez appeler la méthode @code{_root()}. Cette méthode commence par un soulignement pour indiquer que cette fonction fait partie de l'implémentation, et non d'une interface avec la fonctionnalité `Tk'.

Voici quelques exemples d'utilisation courante :

@example
import tkinter as tk

class App(tk.Frame):
    def __init__(self, master=None):
        super().__init__(master)
        self.pack()

# create the application
myapp = App()

#
# here are method calls to the window manager class
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)

# start the program
myapp.mainloop()
@end example

@node Types de données des options Tk,Liaisons et événements,Le gestionnaire de fenêtres,Guide pratique
@anchor{library/tkinter tk-option-data-types}@anchor{3d90}
@subsubsection Types de données des options `Tk'


@geindex Types de données des options *Tk*


@table @asis

@item `anchor'

Les valeurs acceptées sont des points cardinaux : @code{"n"}, @code{"ne"}, @code{"e"}, @code{"se"}, @code{"s"}, @code{"sw"}, @code{"w"}, @code{"nw"} et @code{"center"}.

@item `bitmap'

Il y a huit bitmaps intégrés nommés : @code{"error"}, @code{"gray25"}, @code{"gray50"}, @code{"hourglass"}, @code{"info"}, @code{"questhead"}, @code{"question"}, @code{"warning"}.  Pour spécifier un nom de fichier bitmap X, indiquez le chemin complet du fichier, précédé de @code{@@}, comme dans @code{"@@/usr/contrib/bitmap/gumby.bit"}.

@item `boolean'

Vous pouvez lui donner les entiers 0 ou 1 ou les chaînes de caractères @code{"yes"} ou @code{"no"}.

@item `callback'

N'importe quelle fonction Python qui ne prend pas d'argument.  Par exemple :

@example
def print_it():
    print("hi there")
fred["command"] = print_it
@end example

@item `color'

Les couleurs peuvent être données sous forme de noms de couleurs `Xorg' dans le fichier `rgb.txt', ou sous forme de chaînes représentant les valeurs RVB en 4 bits : @code{"#RGB"}, 8 bits : @code{"#RRVVBB"}, 12 bits : @code{"#RRRVVVBBB"}, ou 16 bits : @code{"#RRRRVVVVBBBB"}, où R,V,B représente ici tout chiffre hexadécimal valide. Voir page 160 du livre d'Ousterhout pour plus de détails.

@item `cursor'

Les noms de curseurs `Xorg' standard que l'on trouve dans @code{cursorfont.h} peuvent être utilisés, sans le préfixe @code{XC_}. Par exemple pour obtenir un curseur en forme de main (@code{XC_hand2}), utilisez la chaîne @code{"hand2"}. Vous pouvez également spécifier votre propre bitmap et fichier masque. Voir page 179 du livre d'Ousterhout.

@item `distance'

Les distances à l'écran peuvent être spécifiées en pixels ou en distances absolues. Les pixels sont donnés sous forme de nombres et les distances absolues sous forme de chaînes de caractères, le dernier caractère indiquant les unités : @code{c} pour les centimètres, @code{i} pour les pouces (`inches' en anglais), @code{m} pour les millimètres, @code{p} pour les points d'impression. Par exemple, 3,5 pouces est noté @code{"3.5i"}.

@item `font'

`Tk' utilise un format de nom de police sous forme de liste, tel que @code{@{courier 10 bold@}}. Les tailles de polices avec des nombres positifs sont mesurées en points ; les tailles avec des nombres négatifs sont mesurées en pixels.

@item `geometry'

Il s'agit d'une chaîne de caractères de la forme @code{largeurxhauteur}, où la largeur et la hauteur sont mesurées en pixels pour la plupart des objets graphiques (en caractères pour les objets graphiques affichant du texte). Par exemple : @code{fred["geometry"] = "200x100"}.

@item `justify'

Les valeurs acceptées sont les chaînes de caractères : @code{"left"}, @code{"center"}, @code{"right"} et @code{"fill"}.

@item `region'

c'est une chaîne de caractères avec quatre éléments séparés par des espaces, chacun d'eux étant une distance valide (voir ci-dessus).  Par exemple : @code{"2 3 4 5"}, @code{" 3i 2i 4.5i 2i"} et @code{"3c 2c 4c 10.43c"} sont toutes des régions valides.

@item `relief'

Détermine le style de bordure d'un objet graphique. Les valeurs valides sont : @code{"raised"}, @code{"sunken"}, @code{"flat"}, @code{"groove"} et @code{"ridge"}.

@item `scrollcommand'

C'est presque toujours la méthode @code{set()} d'un objet graphique de défilement, mais peut être n'importe quelle méthode d'objet graphique qui prend un seul argument.

@item `wrap'

Doit être @code{"none"}, @code{"char"} ou @code{"word"}.
@end table

@node Liaisons et événements,Le paramètre index,Types de données des options Tk,Guide pratique
@anchor{library/tkinter bindings-and-events}@anchor{3d91}@anchor{library/tkinter id2}@anchor{3d92}
@subsubsection Liaisons et événements


@geindex bind (widgets)
@geindex events (widgets)

La méthode @code{bind} de la commande d'objet graphique vous permet de surveiller certains événements et d'avoir un déclencheur de fonction de rappel lorsque ce type d'événement se produit.  La forme de la méthode de liaison est la suivante :

@example
def bind(self, sequence, func, add='@w{'}):
@end example

où :


@table @asis

@item `sequence'

est une chaîne de caractères qui indique le type d'événement cible.  (Voir la page du manuel de @code{bind(3tk)@footnote{https://manpages.debian.org/bind(3tk)}} et la page 201 du livre de John Ousterhout @cite{Tcl and the Tk Toolkit (2nd edition)} pour plus de détails).

@item `func'

est une fonction Python, prenant un argument, à invoquer lorsque l'événement se produit. Une instance d’évènement sera passée en argument. (Les fonctions déployées de cette façon sont communément appelées `callbacks' ou « fonctions de rappel » en français).

@item `add'

est facultative, soit @code{'@w{'}} ou @code{'+'}.  L'envoi d'une chaîne de caractères vide indique que cette liaison doit remplacer toute autre liaison à laquelle cet événement est associé.  L'envoi de @code{"+"} signifie que cette fonction doit être ajoutée à la liste des fonctions liées à ce type d'événement.
@end table

Par exemple :

@example
def turn_red(self, event):
    event.widget["activeforeground"] = "red"

self.button.bind("<Enter>", self.turn_red)
@end example

Remarquez comment on accède au champ `objet graphique' de l'événement dans la fonction de rappel @code{turn_red()}.  Ce champ contient l'objet graphique qui a capturé l'événement `Xorg'. Le tableau suivant répertorie les autres champs d'événements auxquels vous pouvez accéder, et comment ils sont nommés dans `Tk', ce qui peut être utile lorsque vous vous référez aux pages de manuel `Tk'.


@multitable {xxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Tk

@tab

Champ `évènement' de `Tkinter'

@tab

Tk

@tab

Champ `évènement' de `Tkinter'

@item

%f

@tab

focus

@tab

%A

@tab

char

@item

%h

@tab

hauteur

@tab

%E

@tab

send_event

@item

%k

@tab

keycode

@tab

%K

@tab

keysym

@item

%s

@tab

state

@tab

%N

@tab

keysym_num

@item

%t

@tab

time

@tab

%T

@tab

type

@item

%w

@tab

width

@tab

%W

@tab

widget

@item

%x

@tab

x

@tab

%X

@tab

x_root

@item

%y

@tab

y

@tab

%Y

@tab

y_root

@end multitable


@node Le paramètre index,Images,Liaisons et événements,Guide pratique
@anchor{library/tkinter the-index-parameter}@anchor{3d93}
@subsubsection Le paramètre index


Un certain nombre d'objets graphiques nécessitent le passage de paramètres « indicés ».  Ils sont utilisés pour pointer vers un endroit spécifique dans un objet graphique de type `Texte', ou vers des caractères particuliers dans un objet graphique de type `Entrée', ou vers des éléments de menu particuliers dans un objet graphique de type `Menu'.


@table @asis

@item Index des objets graphique de type `Entrée' (@code{index}, @code{view index}, etc.)

Les objets graphiques de type `Entrée' ont des options qui se réfèrent à la position des caractères dans le texte affiché.  Vous pouvez utiliser ces fonctions @ref{ef,,tkinter} pour accéder à ces points spéciaux dans les widgets textes :

@item Index des objets graphiques texte

La notation de l'index des objets graphiques de type `Texte' est très riche et mieux décrite dans les pages du manuel `Tk'.

@item Index menu (@code{menu.invoke()}, @code{menu.entryconfig()}, etc.)

Certaines options et méthodes pour manipuler les menus nécessitent des éléments de spécifiques. Chaque fois qu'un index de menu est nécessaire pour une option ou un paramètre, vous pouvez utiliser :


@itemize *

@item 
un entier qui fait référence à la position numérique de l'entrée dans l'objet graphique, comptée à partir du haut, en commençant par 0 ;

@item 
la chaîne de caractères @code{"active"}, qui fait référence à la position du menu qui se trouve actuellement sous le curseur ;

@item 
la chaîne de caractères @code{"last"} qui fait référence au dernier élément du menu ;

@item 
un entier précédé de @code{@@}, comme dans @code{@@6}, où l'entier est interprété comme une coordonnée y de pixels dans le système de coordonnées du menu ;

@item 
la chaîne de caractères @code{"none"}, qui n'indique aucune entrée du menu, le plus souvent utilisée avec @code{menu.activate()} pour désactiver toutes les entrées, et enfin,

@item 
une chaîne de texte dont le motif correspond à l'étiquette de l'entrée de menu, telle qu'elle est balayée du haut vers le bas du menu.  Notez que ce type d'index est considéré après tous les autres, ce qui signifie que les correspondances pour les éléments de menu étiquetés @code{last}, @code{active} ou @code{none} peuvent être interprétés comme les littéraux ci-dessus, plutôt.
@end itemize
@end table

@node Images,,Le paramètre index,Guide pratique
@anchor{library/tkinter images}@anchor{3d94}
@subsubsection Images


Des images de différents formats peuvent être créées à travers la sous-classe correspondante de @code{tkinter.Image} :


@itemize *

@item 
@code{BitmapImage} pour les images au format `XBM'.

@item 
@code{PhotoImage} pour les images aux formats `PGM', `PPM', `GIF' et `PNG'. Ce dernier est géré à partir de `Tk' 8.6.
@end itemize

L'un ou l'autre type d'image est créé par l'option @code{file} ou @code{data} (d'autres options sont également disponibles).


Modifié dans la version 3.13: Added the @code{PhotoImage} method @code{copy_replace()} to copy a region
from one image to other image, possibly with pixel zooming and/or
subsampling.
Add `from_coords' parameter to @code{PhotoImage} methods @code{copy()},
@code{zoom()} and @code{subsample()}.
Add `zoom' and `subsample' parameters to @code{PhotoImage} method
@code{copy()}.


L'objet image peut alors être utilisé partout où un objet graphique sait gérer une option @code{image} (par ex. étiquettes, boutons, menus). Dans ces cas, `Tk' ne conserve pas de référence à l'image. Lorsque la dernière référence Python à l'objet image est supprimée, les données de l'image sont également supprimées, et `Tk' affiche une boite vide à l'endroit où l'image était utilisée.


@subsubheading Voir aussi


Le paquet Pillow@footnote{https://python-pillow.org/} ajoute la prise en charge de formats tels que `BMP', `JPEG', `TIFF' et `WebP', entre autres.


@node Gestionnaires de fichiers,,Guide pratique,tkinter --- Python interface to Tcl/Tk
@anchor{library/tkinter file-handlers}@anchor{3d95}@anchor{library/tkinter tkinter-file-handlers}@anchor{3d96}
@subsubsection Gestionnaires de fichiers


`Tk' vous permet d'enregistrer et de `désenregistrer' une fonction de rappel qui est appelée depuis la boucle principale de `Tk' lorsque des entrées-sorties sont possibles sur un descripteur de fichier. Un seul gestionnaire peut être enregistré par descripteur de fichier. Exemple de code :

@example
import tkinter
widget = tkinter.Tk()
mask = tkinter.READABLE | tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)
@end example

Cette fonction n'est pas disponible sous Windows.

Dans la mesure où vous ne savez pas combien d'octets sont disponibles en lecture, il ne faut pas utiliser les méthodes @ref{67f,,BufferedIOBase} ou @ref{680,,TextIOBase} @ref{1306,,read()} ou @ref{1307,,readline()}, car elles requièrent d'indiquer le nombre de `bytes' à lire. Pour les connecteurs, les méthodes @code{recv()} ou @ref{d92,,recvfrom()} fonctionnent bien ; pour les autres fichiers, utilisez des lectures brutes ou @code{os.read(file.fileno(), maxbytecount)}.

@geindex createfilehandler() (méthode _tkinter.Widget.tk)
@anchor{library/tkinter tkinter Widget tk createfilehandler}@anchor{3d97}
@deffn {Méthode} Widget.tk.createfilehandler (file, mask, func)

Enregistre la fonction de rappel du gestionnaire de fichiers `func'. L'argument @code{file} peut être soit un objet avec une méthode @ref{27cf,,fileno()} (comme un objet fichier ou connecteur), soit un descripteur de fichier de type entier. L'argument @code{mask} est une combinaison `OU' de l'une des trois constantes ci-dessous. La fonction de rappel s'utilise comme suit :

@example
callback(file, mask)
@end example
@end deffn

@geindex deletefilehandler() (méthode _tkinter.Widget.tk)
@anchor{library/tkinter tkinter Widget tk deletefilehandler}@anchor{3d98}
@deffn {Méthode} Widget.tk.deletefilehandler (file)

Désenregistre un gestionnaire de fichiers.
@end deffn

@geindex READABLE (dans le module _tkinter)
@geindex WRITABLE (dans le module _tkinter)
@geindex EXCEPTION (dans le module _tkinter)
@anchor{library/tkinter tkinter READABLE}@anchor{3d99}
@deffn {Données} _tkinter.READABLE
@anchor{library/tkinter tkinter WRITABLE}@anchor{3d9a}
@deffnx {Données} _tkinter.WRITABLE
@anchor{library/tkinter tkinter EXCEPTION}@anchor{3d9b}
@deffnx {Données} _tkinter.EXCEPTION

Constantes utilisées dans les arguments @code{mask}.
@end deffn

@node tkinter colorchooser --- Color choosing dialog,tkinter font --- Tkinter font wrapper,tkinter --- Python interface to Tcl/Tk,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter colorchooser doc}@anchor{3d9c}@anchor{library/tkinter colorchooser module-tkinter colorchooser}@anchor{f0}@anchor{library/tkinter colorchooser tkinter-colorchooser-color-choosing-dialog}@anchor{3d9d}
@subsection @code{tkinter.colorchooser} --- Color choosing dialog


@geindex module; tkinter.colorchooser

`Code source :' Lib/tkinter/colorchooser.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/colorchooser.py}


__________________________________________________________________


Le module @ref{f0,,tkinter.colorchooser} fournit la classe @ref{3d9e,,Chooser} en tant qu'interface avec la boîte de dialogue native du sélecteur de couleurs. @code{Chooser} implémente une fenêtre de dialogue de choix de couleur modale. La classe @code{Chooser} hérite de la classe @ref{3d9f,,Dialog}.

@geindex Chooser (classe dans tkinter.colorchooser)
@anchor{library/tkinter colorchooser tkinter colorchooser Chooser}@anchor{3d9e}
@deffn {Classe} tkinter.colorchooser.Chooser (master=None, **options)
@end deffn

@geindex askcolor() (dans le module tkinter.colorchooser)
@anchor{library/tkinter colorchooser tkinter colorchooser askcolor}@anchor{3da0}
@deffn {Fonction} tkinter.colorchooser.askcolor (color=None, **options)

Crée une boîte de dialogue de choix de couleur. Un appel à cette méthode affiche la fenêtre, attend que l'utilisateur fasse une sélection et renvoie la couleur sélectionnée (ou @code{None}) à l'appelant.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{f1,,tkinter.commondialog}

Module de dialogue standard `Tkinter'
@end table


@node tkinter font --- Tkinter font wrapper,Boîtes de dialogue Tkinter,tkinter colorchooser --- Color choosing dialog,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter font doc}@anchor{3da1}@anchor{library/tkinter font module-tkinter font}@anchor{f4}@anchor{library/tkinter font tkinter-font-tkinter-font-wrapper}@anchor{3da2}
@subsection @code{tkinter.font} --- Tkinter font wrapper


@geindex module; tkinter.font

`Code source :' Lib/tkinter/font.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/font.py}


__________________________________________________________________


Le module @ref{f4,,tkinter.font} fournit la classe @ref{1898,,Font} pour créer et utiliser des polices nommées.

Les différentes épaisseurs et inclinaisons des polices sont :

@geindex NORMAL (dans le module tkinter.font)
@geindex BOLD (dans le module tkinter.font)
@geindex ITALIC (dans le module tkinter.font)
@geindex ROMAN (dans le module tkinter.font)
@anchor{library/tkinter font tkinter font NORMAL}@anchor{3da3}
@deffn {Données} tkinter.font.NORMAL
@anchor{library/tkinter font tkinter font BOLD}@anchor{3da4}
@deffnx {Données} tkinter.font.BOLD
@anchor{library/tkinter font tkinter font ITALIC}@anchor{3da5}
@deffnx {Données} tkinter.font.ITALIC
@anchor{library/tkinter font tkinter font ROMAN}@anchor{3da6}
@deffnx {Données} tkinter.font.ROMAN
@end deffn

@geindex Font (classe dans tkinter.font)
@anchor{library/tkinter font tkinter font Font}@anchor{1898}
@deffn {Classe} tkinter.font.Font (root=None, font=None, name=None, exists=False, **options)

La classe @ref{1898,,Font} représente une police nommée. Les instances `Font' reçoivent des noms uniques et peuvent être spécifiées par leur configuration de famille, de taille et de style. Les polices nommées sont la méthode de `Tk' pour créer et identifier les polices comme un seul objet, plutôt que de spécifier une police par ses attributs à chaque occurrence.

@quotation

arguments :

@quotation


@display
`font' – `n'-uplet spécificateur de police (famille, taille, options)@w{ }
`name' – nom de police unique@w{ }
`exists' – s'il est vrai, `self' pointe vers la police nommée existante@w{ }
@end display


@end quotation

options nommées supplémentaires (ignorées si `font' est spécifié) :

@quotation


@display
`family' – famille de polices, c'est-à-dire `Courier', `Times'@w{ }
`size' – taille de la police@w{ }
@display
Si `size' est positif, il est interprété comme une taille en points.@w{ }
Si `size' est un nombre négatif sa valeur absolue est traitée@w{ }
comme taille en pixels.@w{ }
@end display
`weight' – accentuation de la police (`NORMAL', `BOLD' pour gras)@w{ }
`slant' – `ROMAN' pour romain, `ITALIC' pour italique@w{ }
`underline' – soulignement de la police (0 – aucun, 1 – souligné)@w{ }
`overstrike' – police barrée (0 – aucune, 1 – barré)@w{ }
@end display


@end quotation
@end quotation

@geindex actual() (méthode tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font actual}@anchor{3da7}
@deffn {Méthode} actual (option=None, displayof=None)

Renvoie les attributs de la police.
@end deffn

@geindex cget() (méthode tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font cget}@anchor{3da8}
@deffn {Méthode} cget (option)

Récupère un attribut de la police.
@end deffn

@geindex config() (méthode tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font config}@anchor{3da9}
@deffn {Méthode} config (**options)

Modifie les attributs de la police.
@end deffn

@geindex copy() (méthode tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font copy}@anchor{3daa}
@deffn {Méthode} copy ()

Renvoie une nouvelle instance de la police actuelle.
@end deffn

@geindex measure() (méthode tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font measure}@anchor{3dab}
@deffn {Méthode} measure (text, displayof=None)

Renvoie la quantité d'espace que le texte occuperait sur l'affichage spécifié s'il était formaté dans la police actuelle. Si `displayof' n'est pas spécifié, `tk' suppose que c'est la fenêtre principale de l'application.
@end deffn

@geindex metrics() (méthode tkinter.font.Font)
@anchor{library/tkinter font tkinter font Font metrics}@anchor{3dac}
@deffn {Méthode} metrics (*options, **kw)

Renvoie des données spécifiques à la police. Les options incluent :


@table @asis

@item `ascent' – distance entre la ligne de base et le point le plus haut qu'un

caractère de la police peut occuper

@item `descent' – distance entre la ligne de base et le point le plus bas qu'un

caractère de la police peut occuper

@item `linespace' – séparation verticale minimale nécessaire entre deux

caractères de la police qui assure l'absence de chevauchement vertical entre les lignes.
@end table

`fixed' – 1 si la police est à largeur fixe sinon 0
@end deffn
@end deffn

@geindex families() (dans le module tkinter.font)
@anchor{library/tkinter font tkinter font families}@anchor{3dad}
@deffn {Fonction} tkinter.font.families (root=None, displayof=None)

Renvoie les différentes familles de polices.
@end deffn

@geindex names() (dans le module tkinter.font)
@anchor{library/tkinter font tkinter font names}@anchor{3dae}
@deffn {Fonction} tkinter.font.names (root=None)

Renvoie les noms des polices définies.
@end deffn

@geindex nametofont() (dans le module tkinter.font)
@anchor{library/tkinter font tkinter font nametofont}@anchor{189a}
@deffn {Fonction} tkinter.font.nametofont (name, root=None)

Renvoie une représentation @ref{1898,,Font} d'une police `tk' nommée.


Modifié dans la version 3.10: le paramètre `root' a été ajouté.

@end deffn

@node Boîtes de dialogue Tkinter,tkinter messagebox --- Tkinter message prompts,tkinter font --- Tkinter font wrapper,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/dialog doc}@anchor{3daf}@anchor{library/dialog tkinter-dialogs}@anchor{3db0}
@subsection Boîtes de dialogue `Tkinter'


@menu
* tkinter.simpledialog – Boîtes de dialogue de saisie standard de Tkinter: tkinter simpledialog – Boîtes de dialogue de saisie standard de Tkinter. 
* tkinter.filedialog – Boîtes de dialogue de sélection de fichiers: tkinter filedialog – Boîtes de dialogue de sélection de fichiers. 
* tkinter.commondialog – Modèles de fenêtre de dialogue: tkinter commondialog – Modèles de fenêtre de dialogue. 

@end menu

@node tkinter simpledialog – Boîtes de dialogue de saisie standard de Tkinter,tkinter filedialog – Boîtes de dialogue de sélection de fichiers,,Boîtes de dialogue Tkinter
@anchor{library/dialog module-tkinter simpledialog}@anchor{f7}@anchor{library/dialog tkinter-simpledialog-standard-tkinter-input-dialogs}@anchor{3db1}
@subsubsection @code{tkinter.simpledialog} – Boîtes de dialogue de saisie standard de `Tkinter'


@geindex module; tkinter.simpledialog

`Code source :' Lib/tkinter/simpledialog.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/simpledialog.py}


__________________________________________________________________


Le module @ref{f7,,tkinter.simpledialog} contient des classes pratiques et des fonctions pour créer des boîtes de dialogue modales simples afin d'obtenir une valeur de l'utilisateur.

@geindex askfloat() (dans le module tkinter.simpledialog)
@geindex askinteger() (dans le module tkinter.simpledialog)
@geindex askstring() (dans le module tkinter.simpledialog)
@anchor{library/dialog tkinter simpledialog askfloat}@anchor{3db2}
@deffn {Fonction} tkinter.simpledialog.askfloat (title, prompt, **kw)
@anchor{library/dialog tkinter simpledialog askinteger}@anchor{189b}
@deffnx {Fonction} tkinter.simpledialog.askinteger (title, prompt, **kw)
@anchor{library/dialog tkinter simpledialog askstring}@anchor{3db3}
@deffnx {Fonction} tkinter.simpledialog.askstring (title, prompt, **kw)

Les trois fonctions ci-dessus fournissent des boîtes de dialogue qui invitent l'utilisateur à saisir une valeur du type souhaité.
@end deffn

@geindex Dialog (classe dans tkinter.simpledialog)
@anchor{library/dialog tkinter simpledialog Dialog}@anchor{3db4}
@deffn {Classe} tkinter.simpledialog.Dialog (parent, title=None)

Classe mère pour les boîtes de dialogue personnalisées.

@geindex body() (méthode tkinter.simpledialog.Dialog)
@anchor{library/dialog tkinter simpledialog Dialog body}@anchor{3db5}
@deffn {Méthode} body (master)

À remplacer pour construire l'interface de la boîte de dialogue et renvoyer le widget qui doit avoir le focus initial.
@end deffn

@geindex buttonbox() (méthode tkinter.simpledialog.Dialog)
@anchor{library/dialog tkinter simpledialog Dialog buttonbox}@anchor{3db6}
@deffn {Méthode} buttonbox ()

Le comportement par défaut ajoute les boutons OK et Annuler. À remplacer avoir une disposition de boutons personnalisée.
@end deffn
@end deffn

@node tkinter filedialog – Boîtes de dialogue de sélection de fichiers,tkinter commondialog – Modèles de fenêtre de dialogue,tkinter simpledialog – Boîtes de dialogue de saisie standard de Tkinter,Boîtes de dialogue Tkinter
@anchor{library/dialog module-tkinter filedialog}@anchor{f3}@anchor{library/dialog tkinter-filedialog-file-selection-dialogs}@anchor{3db7}
@subsubsection @code{tkinter.filedialog} – Boîtes de dialogue de sélection de fichiers


@geindex module; tkinter.filedialog

`Code source :' Lib/tkinter/filedialog.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/filedialog.py}


__________________________________________________________________


Le module @ref{f3,,tkinter.filedialog} fournit des classes et des fonctions de fabrique pour créer des fenêtres de sélection de fichiers ou répertoires.

@menu
* Boîtes de dialogue de chargement et sauvegarde natives:: 

@end menu

@node Boîtes de dialogue de chargement et sauvegarde natives,,,tkinter filedialog – Boîtes de dialogue de sélection de fichiers
@anchor{library/dialog native-load-save-dialogs}@anchor{3db8}
@subsubsection Boîtes de dialogue de chargement et sauvegarde natives


Les classes et fonctions suivantes fournissent des fenêtres de dialogue de fichiers qui combinent une apparence native avec des options de configuration pour personnaliser le comportement. Les arguments nommés  suivants s'appliquent aux classes et fonctions répertoriées ci-dessous :

@quotation


@display
`parent' – la fenêtre sur laquelle placer la boîte de dialogue@w{ }
@end display




@display
`title' – le titre de la fenêtre@w{ }
@end display




@display
`initialdir' – le répertoire dans lequel la boîte de dialogue démarre@w{ }
@end display




@display
`initialfile' – le fichier sélectionné à l'ouverture de la boîte de dialogue@w{ }
@end display




@display
`filetypes' – une séquence de `n'-uplets (étiquette, motif), le caractère générique @code{'*'} est autorisé@w{ }
@end display




@display
`defaultextension' – extension par défaut à ajouter au fichier (boîtes de dialogue de sauvegarde)@w{ }
@end display




@display
`multiple' – lorsque vrai, la sélection de plusieurs éléments est autorisée@w{ }
@end display


@end quotation

`Fonctions statiques de fabrique'

Les fonctions ci-dessous, lorsqu'elles sont appelées, créent une boîte de dialogue d'apparence modale native, attendent la sélection de l'utilisateur, puis renvoient la ou les valeurs sélectionnées ou @code{None} à l'appelant.

@geindex askopenfile() (dans le module tkinter.filedialog)
@geindex askopenfiles() (dans le module tkinter.filedialog)
@anchor{library/dialog tkinter filedialog askopenfile}@anchor{3db9}
@deffn {Fonction} tkinter.filedialog.askopenfile (mode='r', **options)
@anchor{library/dialog tkinter filedialog askopenfiles}@anchor{3dba}
@deffnx {Fonction} tkinter.filedialog.askopenfiles (mode='r', **options)

Les deux fonctions ci-dessus créent une boîte de dialogue @ref{3dbb,,Open} et renvoient le(s) objet(s) fichier ouvert(s) en mode lecture seule.
@end deffn

@geindex asksaveasfile() (dans le module tkinter.filedialog)
@anchor{library/dialog tkinter filedialog asksaveasfile}@anchor{3dbc}
@deffn {Fonction} tkinter.filedialog.asksaveasfile (mode='w', **options)

Crée une boîte de dialogue @ref{3dbd,,SaveAs} et renvoie un objet fichier ouvert en mode écriture seule.
@end deffn

@geindex askopenfilename() (dans le module tkinter.filedialog)
@geindex askopenfilenames() (dans le module tkinter.filedialog)
@anchor{library/dialog tkinter filedialog askopenfilename}@anchor{3dbe}
@deffn {Fonction} tkinter.filedialog.askopenfilename (**options)
@anchor{library/dialog tkinter filedialog askopenfilenames}@anchor{3dbf}
@deffnx {Fonction} tkinter.filedialog.askopenfilenames (**options)

Les deux fonctions ci-dessus créent une boîte de dialogue @ref{3dbb,,Open} et renvoient le(s) nom(s) de fichier sélectionné(s) qui correspondent au(x) fichier(s) existant(s).
@end deffn

@geindex asksaveasfilename() (dans le module tkinter.filedialog)
@anchor{library/dialog tkinter filedialog asksaveasfilename}@anchor{3dc0}
@deffn {Fonction} tkinter.filedialog.asksaveasfilename (**options)

Crée une boîte de dialogue @ref{3dbd,,SaveAs} et renvoie le nom de fichier sélectionné.
@end deffn

@geindex askdirectory() (dans le module tkinter.filedialog)
@anchor{library/dialog tkinter filedialog askdirectory}@anchor{3dc1}
@deffn {Fonction} tkinter.filedialog.askdirectory (**options)


@display
Demande à l'utilisateur de sélectionner un répertoire.@w{ }
Option nommée supplémentaire :@w{ }
@display
`mustexist' – détermine si la sélection doit être un répertoire existant.@w{ }
@end display
@end display


@end deffn

@geindex Open (classe dans tkinter.filedialog)
@geindex SaveAs (classe dans tkinter.filedialog)
@anchor{library/dialog tkinter filedialog Open}@anchor{3dbb}
@deffn {Classe} tkinter.filedialog.Open (master=None, **options)
@anchor{library/dialog tkinter filedialog SaveAs}@anchor{3dbd}
@deffnx {Classe} tkinter.filedialog.SaveAs (master=None, **options)

Les deux classes ci-dessus fournissent des fenêtres de dialogue natives pour enregistrer et charger des fichiers.
@end deffn

`Classes de commodité'

Les classes ci-dessous sont utilisées pour créer des fenêtres avec fichiers et répertoires à partir de zéro. Celles-ci n'imitent pas l'apparence native de la plateforme.

@geindex Directory (classe dans tkinter.filedialog)
@anchor{library/dialog tkinter filedialog Directory}@anchor{3dc2}
@deffn {Classe} tkinter.filedialog.Directory (master=None, **options)

Crée une boîte de dialogue invitant l'utilisateur à sélectionner un répertoire.
@end deffn

@cartouche
@quotation Note 
la classe `FileDialog' doit être sous-classée pour un comportement et une gestion des événements personnalisés.
@end quotation
@end cartouche

@geindex FileDialog (classe dans tkinter.filedialog)
@anchor{library/dialog tkinter filedialog FileDialog}@anchor{3dc3}
@deffn {Classe} tkinter.filedialog.FileDialog (master, title=None)

Crée une boîte de dialogue basique de sélection de fichiers.

@geindex cancel_command() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog cancel_command}@anchor{3dc4}
@deffn {Méthode} cancel_command (event=None)

Déclenche la fermeture de la fenêtre de dialogue.
@end deffn

@geindex dirs_double_event() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog dirs_double_event}@anchor{3dc5}
@deffn {Méthode} dirs_double_event (event)

Gestionnaire d'événements pour l'événement de double-clic sur le répertoire.
@end deffn

@geindex dirs_select_event() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog dirs_select_event}@anchor{3dc6}
@deffn {Méthode} dirs_select_event (event)

Gestionnaire d'événements pour l'événement de clic sur le répertoire.
@end deffn

@geindex files_double_event() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog files_double_event}@anchor{3dc7}
@deffn {Méthode} files_double_event (event)

Gestionnaire d'événements pour l'événement de double-clic sur le fichier.
@end deffn

@geindex files_select_event() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog files_select_event}@anchor{3dc8}
@deffn {Méthode} files_select_event (event)

Gestionnaire d'événements pour un événement en un seul clic sur le fichier.
@end deffn

@geindex filter_command() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog filter_command}@anchor{3dc9}
@deffn {Méthode} filter_command (event=None)

Filtre les fichiers par répertoire.
@end deffn

@geindex get_filter() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog get_filter}@anchor{3dca}
@deffn {Méthode} get_filter ()

Récupère le filtre de fichiers actuellement utilisé.
@end deffn

@geindex get_selection() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog get_selection}@anchor{3dcb}
@deffn {Méthode} get_selection ()

Récupère l'élément actuellement sélectionné.
@end deffn

@geindex go() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog go}@anchor{3dcc}
@deffn {Méthode} go (dir_or_file=os.curdir, pattern='*', default='@w{'}, key=None)

Affiche la boîte de dialogue et lance la boucle d'événements.
@end deffn

@geindex ok_event() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog ok_event}@anchor{3dcd}
@deffn {Méthode} ok_event (event)

Quitte la boîte de dialogue en renvoyant la sélection actuelle.
@end deffn

@geindex quit() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog quit}@anchor{3dce}
@deffn {Méthode} quit (how=None)

Sort de la boîte de dialogue en renvoyant le nom du fichier, le cas échéant.
@end deffn

@geindex set_filter() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog set_filter}@anchor{3dcf}
@deffn {Méthode} set_filter (dir, pat)

Définit le filtre de fichiers.
@end deffn

@geindex set_selection() (méthode tkinter.filedialog.FileDialog)
@anchor{library/dialog tkinter filedialog FileDialog set_selection}@anchor{3dd0}
@deffn {Méthode} set_selection (file)

Met à jour la sélection de fichiers actuelle vers `file'.
@end deffn
@end deffn

@geindex LoadFileDialog (classe dans tkinter.filedialog)
@anchor{library/dialog tkinter filedialog LoadFileDialog}@anchor{3dd1}
@deffn {Classe} tkinter.filedialog.LoadFileDialog (master, title=None)

Sous-classe de `FileDialog' qui crée une fenêtre de dialogue pour sélectionner un fichier existant.

@geindex ok_command() (méthode tkinter.filedialog.LoadFileDialog)
@anchor{library/dialog tkinter filedialog LoadFileDialog ok_command}@anchor{3dd2}
@deffn {Méthode} ok_command ()

Teste qu'un fichier est fourni et que la sélection indique un fichier déjà existant.
@end deffn
@end deffn

@geindex SaveFileDialog (classe dans tkinter.filedialog)
@anchor{library/dialog tkinter filedialog SaveFileDialog}@anchor{3dd3}
@deffn {Classe} tkinter.filedialog.SaveFileDialog (master, title=None)

Sous-classe de `FileDialog' qui crée une fenêtre de dialogue pour sélectionner un fichier de destination.

@geindex ok_command() (méthode tkinter.filedialog.SaveFileDialog)
@anchor{library/dialog tkinter filedialog SaveFileDialog ok_command}@anchor{3dd4}
@deffn {Méthode} ok_command ()

Teste si la sélection pointe vers un fichier valide qui n'est pas un répertoire. Une confirmation est requise si un fichier déjà existant est sélectionné.
@end deffn
@end deffn

@node tkinter commondialog – Modèles de fenêtre de dialogue,,tkinter filedialog – Boîtes de dialogue de sélection de fichiers,Boîtes de dialogue Tkinter
@anchor{library/dialog module-tkinter commondialog}@anchor{f1}@anchor{library/dialog tkinter-commondialog-dialog-window-templates}@anchor{3dd5}
@subsubsection @code{tkinter.commondialog} – Modèles de fenêtre de dialogue


@geindex module; tkinter.commondialog

`Code source :' Lib/tkinter/commondialog.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/commondialog.py}


__________________________________________________________________


Le module @ref{f1,,tkinter.commondialog} fournit la classe @ref{3d9f,,Dialog} qui est la classe mère pour les dialogues définis dans d'autres modules.

@geindex Dialog (classe dans tkinter.commondialog)
@anchor{library/dialog tkinter commondialog Dialog}@anchor{3d9f}
@deffn {Classe} tkinter.commondialog.Dialog (master=None, **options)

@geindex show() (méthode tkinter.commondialog.Dialog)
@anchor{library/dialog tkinter commondialog Dialog show}@anchor{3dd6}
@deffn {Méthode} show (color=None, **options)

Affiche la fenêtre de dialogue.
@end deffn
@end deffn


@subsubheading Voir aussi


Modules @ref{f5,,tkinter.messagebox}, @ref{1c0d,,Lecture et écriture de fichiers}


@node tkinter messagebox --- Tkinter message prompts,tkinter scrolledtext --- Scrolled Text Widget,Boîtes de dialogue Tkinter,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter messagebox doc}@anchor{3dd7}@anchor{library/tkinter messagebox module-tkinter messagebox}@anchor{f5}@anchor{library/tkinter messagebox tkinter-messagebox-tkinter-message-prompts}@anchor{3dd8}
@subsection @code{tkinter.messagebox} --- Tkinter message prompts


@geindex module; tkinter.messagebox

`Code source :' Lib/tkinter/messagebox.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/messagebox.py}


__________________________________________________________________


The @ref{f5,,tkinter.messagebox} module provides a template base class as well as
a variety of convenience methods for commonly used configurations. The message
boxes are modal and will return a subset of (@code{True}, @code{False}, @code{None},
@ref{3dd9,,OK}, @ref{3dda,,CANCEL}, @ref{3ddb,,YES}, @ref{3ddc,,NO}) based on
the user's selection. Common message box styles and layouts include but are not
limited to:


@float Figure

@image{python-figures/tk_msg,,,,png}

@end float


@geindex Message (classe dans tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox Message}@anchor{3ddd}
@deffn {Classe} tkinter.messagebox.Message (master=None, **options)

Create a message window with an application-specified message, an icon
and a set of buttons.
Each of the buttons in the message window is identified by a unique symbolic name (see the `type' options).

The following options are supported:

@quotation


@table @asis

@item `command'

Specifies the function to invoke when the user closes the dialog.
The name of the button clicked by the user to close the dialog is
passed as argument.
This is only available on macOS.

@item `default'

Gives the @ref{3dde,,symbolic name} of the default button
for this message window (@ref{3dd9,,OK}, @ref{3dda,,CANCEL}, and so on).
If this option is not specified, the first button in the dialog will
be made the default.

@item `detail'

Specifies an auxiliary message to the main message given by the
`message' option.
The message detail will be presented beneath the main message and,
where supported by the OS, in a less emphasized font than the main
message.

@item `icon'

Specifies an @ref{3ddf,,icon} to display.
If this option is not specified, then the @ref{3de0,,INFO} icon will be
displayed.

@item `message'

Specifies the message to display in this message box.
The default value is an empty string.

@item `parent'

Makes the specified window the logical parent of the message box.
The message box is displayed on top of its parent window.

@item `title'

Specifies a string to display as the title of the message box.
This option is ignored on macOS, where platform guidelines forbid
the use of a title on this kind of dialog.

@item `type'

Arranges for a @ref{3de1,,predefined set of buttons}
to be displayed.
@end table
@end quotation

@geindex show() (méthode tkinter.messagebox.Message)
@anchor{library/tkinter messagebox tkinter messagebox Message show}@anchor{3de2}
@deffn {Méthode} show (**options)

Display a message window and wait for the user to select one of the buttons. Then return the symbolic name of the selected button.
Keyword arguments can override options specified in the constructor.
@end deffn
@end deffn

`Boîte de message d'information'

@geindex showinfo() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox showinfo}@anchor{3de3}
@deffn {Fonction} tkinter.messagebox.showinfo (title=None, message=None, **options)

Creates and displays an information message box with the specified title
and message.
@end deffn

`Boîtes de message d'avertissement'

@geindex showwarning() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox showwarning}@anchor{3de4}
@deffn {Fonction} tkinter.messagebox.showwarning (title=None, message=None, **options)

Creates and displays a warning message box with the specified title
and message.
@end deffn

@geindex showerror() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox showerror}@anchor{3de5}
@deffn {Fonction} tkinter.messagebox.showerror (title=None, message=None, **options)

Creates and displays an error message box with the specified title
and message.
@end deffn

`Boîtes de message posant une question'

@geindex askquestion() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askquestion}@anchor{3de6}
@deffn {Fonction} tkinter.messagebox.askquestion (title=None, message=None, *, type=YESNO, **options)

Ask a question. By default shows buttons @ref{3ddb,,YES} and @ref{3ddc,,NO}.
Returns the symbolic name of the selected button.
@end deffn

@geindex askokcancel() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askokcancel}@anchor{3de7}
@deffn {Fonction} tkinter.messagebox.askokcancel (title=None, message=None, **options)

Ask if operation should proceed. Shows buttons @ref{3dd9,,OK} and @ref{3dda,,CANCEL}.
Returns @code{True} if the answer is ok and @code{False} otherwise.
@end deffn

@geindex askretrycancel() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askretrycancel}@anchor{3de8}
@deffn {Fonction} tkinter.messagebox.askretrycancel (title=None, message=None, **options)

Ask if operation should be retried. Shows buttons @ref{3de9,,RETRY} and @ref{3dda,,CANCEL}.
Return @code{True} if the answer is yes and @code{False} otherwise.
@end deffn

@geindex askyesno() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askyesno}@anchor{3dea}
@deffn {Fonction} tkinter.messagebox.askyesno (title=None, message=None, **options)

Ask a question. Shows buttons @ref{3ddb,,YES} and @ref{3ddc,,NO}.
Returns @code{True} if the answer is yes and @code{False} otherwise.
@end deffn

@geindex askyesnocancel() (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox askyesnocancel}@anchor{3deb}
@deffn {Fonction} tkinter.messagebox.askyesnocancel (title=None, message=None, **options)

Ask a question. Shows buttons @ref{3ddb,,YES}, @ref{3ddc,,NO} and @ref{3dda,,CANCEL}.
Return @code{True} if the answer is yes, @code{None} if cancelled, and @code{False}
otherwise.
@end deffn
@anchor{library/tkinter messagebox messagebox-buttons}@anchor{3dde}
Symbolic names of buttons:

@geindex ABORT (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox ABORT}@anchor{3dec}
@deffn {Données} tkinter.messagebox.ABORT = 'abort'
@end deffn

@geindex RETRY (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox RETRY}@anchor{3de9}
@deffn {Données} tkinter.messagebox.RETRY = 'retry'
@end deffn

@geindex IGNORE (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox IGNORE}@anchor{3ded}
@deffn {Données} tkinter.messagebox.IGNORE = 'ignore'
@end deffn

@geindex OK (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox OK}@anchor{3dd9}
@deffn {Données} tkinter.messagebox.OK = 'ok'
@end deffn

@geindex CANCEL (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox CANCEL}@anchor{3dda}
@deffn {Données} tkinter.messagebox.CANCEL = 'cancel'
@end deffn

@geindex YES (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox YES}@anchor{3ddb}
@deffn {Données} tkinter.messagebox.YES = 'yes'
@end deffn

@geindex NO (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox NO}@anchor{3ddc}
@deffn {Données} tkinter.messagebox.NO = 'no'
@end deffn
@anchor{library/tkinter messagebox messagebox-types}@anchor{3de1}
Predefined sets of buttons:

@geindex ABORTRETRYIGNORE (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox ABORTRETRYIGNORE}@anchor{3dee}
@deffn {Données} tkinter.messagebox.ABORTRETRYIGNORE = 'abortretryignore'

Displays three buttons whose symbolic names are @ref{3dec,,ABORT},
@ref{3de9,,RETRY} and @ref{3ded,,IGNORE}.
@end deffn


@deffn {Données} tkinter.messagebox.OK = 'ok'

Displays one button whose symbolic name is @ref{3dd9,,OK}.
@end deffn

@geindex OKCANCEL (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox OKCANCEL}@anchor{3def}
@deffn {Données} tkinter.messagebox.OKCANCEL = 'okcancel'

Displays two buttons whose symbolic names are @ref{3dd9,,OK} and
@ref{3dda,,CANCEL}.
@end deffn

@geindex RETRYCANCEL (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox RETRYCANCEL}@anchor{3df0}
@deffn {Données} tkinter.messagebox.RETRYCANCEL = 'retrycancel'

Displays two buttons whose symbolic names are @ref{3de9,,RETRY} and
@ref{3dda,,CANCEL}.
@end deffn

@geindex YESNO (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox YESNO}@anchor{3df1}
@deffn {Données} tkinter.messagebox.YESNO = 'yesno'

Displays two buttons whose symbolic names are @ref{3ddb,,YES} and
@ref{3ddc,,NO}.
@end deffn

@geindex YESNOCANCEL (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox YESNOCANCEL}@anchor{3df2}
@deffn {Données} tkinter.messagebox.YESNOCANCEL = 'yesnocancel'

Displays three buttons whose symbolic names are @ref{3ddb,,YES},
@ref{3ddc,,NO} and @ref{3dda,,CANCEL}.
@end deffn
@anchor{library/tkinter messagebox messagebox-icons}@anchor{3ddf}
Icon images:

@geindex ERROR (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox ERROR}@anchor{3df3}
@deffn {Données} tkinter.messagebox.ERROR = 'error'
@end deffn

@geindex INFO (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox INFO}@anchor{3de0}
@deffn {Données} tkinter.messagebox.INFO = 'info'
@end deffn

@geindex QUESTION (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox QUESTION}@anchor{3df4}
@deffn {Données} tkinter.messagebox.QUESTION = 'question'
@end deffn

@geindex WARNING (dans le module tkinter.messagebox)
@anchor{library/tkinter messagebox tkinter messagebox WARNING}@anchor{3df5}
@deffn {Données} tkinter.messagebox.WARNING = 'warning'
@end deffn

@node tkinter scrolledtext --- Scrolled Text Widget,tkinter dnd --- Drag and drop support,tkinter messagebox --- Tkinter message prompts,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter scrolledtext doc}@anchor{3df6}@anchor{library/tkinter scrolledtext module-tkinter scrolledtext}@anchor{f6}@anchor{library/tkinter scrolledtext tkinter-scrolledtext-scrolled-text-widget}@anchor{3df7}
@subsection @code{tkinter.scrolledtext} --- Scrolled Text Widget


@geindex module; tkinter.scrolledtext

`Code source :' Lib/tkinter/scrolledtext.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/scrolledtext.py}


__________________________________________________________________


Le module @ref{f6,,tkinter.scrolledtext} fournit une classe, de même nom, implémentant un simple gadget texte avec une barre de défilement verticale, configuré "pour faire ce qu'on attend de lui". Utiliser @ref{3df8,,ScrolledText} est beaucoup plus simple que configurer un gadget texte et une barre de défilement.

Le gadget texte et la barre de défilement sont regroupés dans une @code{Frame}, et les méthodes gestionnaires de géométrie @code{Grid} et @code{Pack} sont récupérées de l'objet @code{Frame}. L'objet @ref{3df8,,ScrolledText} a donc tous les attributs classiques pour la gestion de la géométrie.

Si un contrôle plus fin est nécessaire, les attributs suivants sont disponibles :

@geindex ScrolledText (classe dans tkinter.scrolledtext)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText}@anchor{3df8}
@deffn {Classe} tkinter.scrolledtext.ScrolledText (master=None, **kw)

@geindex frame (attribut tkinter.scrolledtext.ScrolledText)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText frame}@anchor{3df9}
@deffn {Attribut} frame

Le cadre (objet `Frame') qui englobe le gadget texte et le gadget de la barre de défilement.
@end deffn

@geindex vbar (attribut tkinter.scrolledtext.ScrolledText)
@anchor{library/tkinter scrolledtext tkinter scrolledtext ScrolledText vbar}@anchor{3dfa}
@deffn {Attribut} vbar

Le gadget de la barre de défilement.
@end deffn
@end deffn

@node tkinter dnd --- Drag and drop support,tkinter ttk --- Tk themed widgets,tkinter scrolledtext --- Scrolled Text Widget,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter dnd doc}@anchor{3dfb}@anchor{library/tkinter dnd module-tkinter dnd}@anchor{f2}@anchor{library/tkinter dnd tkinter-dnd-drag-and-drop-support}@anchor{3dfc}
@subsection @code{tkinter.dnd} --- Drag and drop support


@geindex module; tkinter.dnd

`Code source :' Lib/tkinter/dnd.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/dnd.py}


__________________________________________________________________


@cartouche
@quotation Note 
Ceci est expérimental et devrait être obsolète lorsqu'il sera remplacé par le `Tk DND'.
@end quotation
@end cartouche

Le module @ref{f2,,tkinter.dnd} offre une prise en charge du glisser-déposer d'objets au sein d'une même application, dans la même fenêtre ou entre les fenêtres. Pour activer le glissement d'un objet, vous devez créer une liaison d'événements pour celui-ci qui démarre le processus de glisser-déposer. En règle générale, vous liez un événement `ButtonPress' à une fonction de rappel que vous écrivez (voir @ref{3d91,,Liaisons et événements}). La fonction doit appeler @ref{3dfd,,dnd_start()}, où `source' est l'objet à faire glisser et `event' est l'événement qui a invoqué l'appel (l'argument de votre fonction de rappel).

La sélection d'un objet cible se produit comme suit :


@enumerate 

@item 
Recherche descendante de la zone sous la souris pour le widget cible
@end enumerate

@quotation


@itemize *

@item 
Le widget cible doit avoir un attribut appelable `dnd_accept'

@item 
If `dnd_accept' is not present or returns @code{None}, search moves to parent widget

@item 
If no target widget is found, then the target object is @code{None}
@end itemize
@end quotation


@enumerate 2

@item 
Appel à @code{<old_target>.dnd_leave(source, event)}

@item 
Appel à @code{<new_target>.dnd_enter(source, event)}

@item 
Appel à @code{<target>.dnd_commit(source, event)} pour notifier le déposer.

@item 
Appel à @code{<source>.dnd_end(target, event)} pour signaler la fin du glisser-déposer
@end enumerate

@geindex DndHandler (classe dans tkinter.dnd)
@anchor{library/tkinter dnd tkinter dnd DndHandler}@anchor{3dfe}
@deffn {Classe} tkinter.dnd.DndHandler (source, event)

La classe `DndHandler' gère les événements de glisser-déposer qui suivent les événements `Motion' et `ButtonRelease' à la racine du widget d'événement.

@geindex cancel() (méthode tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler cancel}@anchor{3dff}
@deffn {Méthode} cancel (event=None)

Annule le processus de glisser-déposer.
@end deffn

@geindex finish() (méthode tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler finish}@anchor{3e00}
@deffn {Méthode} finish (event, commit=0)

Exécute les fonctions de fin de glisser-déposer.
@end deffn

@geindex on_motion() (méthode tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler on_motion}@anchor{3e01}
@deffn {Méthode} on_motion (event)

Inspecte la zone sous la souris pour les objets cibles pendant que le glissement est effectué.
@end deffn

@geindex on_release() (méthode tkinter.dnd.DndHandler)
@anchor{library/tkinter dnd tkinter dnd DndHandler on_release}@anchor{3e02}
@deffn {Méthode} on_release (event)

Signale la fin de la traînée lorsque le modèle de relâchement est déclenché.
@end deffn
@end deffn

@geindex dnd_start() (dans le module tkinter.dnd)
@anchor{library/tkinter dnd tkinter dnd dnd_start}@anchor{3dfd}
@deffn {Fonction} tkinter.dnd.dnd_start (source, event)

Fonction de fabrique pour le processus de glisser-déposer.
@end deffn


@subsubheading Voir aussi


@ref{3d91,,Liaisons et événements}


@node tkinter ttk --- Tk themed widgets,IDLE<64>,tkinter dnd --- Drag and drop support,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/tkinter ttk doc}@anchor{3e03}@anchor{library/tkinter ttk module-tkinter ttk}@anchor{f8}@anchor{library/tkinter ttk tkinter-ttk-tk-themed-widgets}@anchor{3e04}
@subsection @code{tkinter.ttk} --- Tk themed widgets


@geindex module; tkinter.ttk

`Code source :' Lib/tkinter/ttk.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tkinter/ttk.py}

@geindex ttk


__________________________________________________________________


Le module @ref{f8,,tkinter.ttk} donne accès à l'ensemble de widgets sur le thème `Tk', introduit dans `Tk' 8.5. Il offre des avantages supplémentaires, notamment le rendu des polices avec anticrénelage sous `X11' et la transparence des fenêtres (nécessitant un gestionnaire de fenêtres de composition sur `X11').

L'idée de base de @ref{f8,,tkinter.ttk} est de séparer, dans la mesure du possible, le code implémentant le comportement d'un widget du code implémentant son apparence.


@subsubheading Voir aussi



@table @asis

@item Tk Widget Styling Support@footnote{https://core.tcl.tk/tips/doc/trunk/tip/48.md}

Document présentant la prise en charge des thèmes pour `Tk'
@end table


@menu
* Utilisation de Ttk:: 
* Widgets Ttk:: 
* Widget:: 
* Combobox:: 
* Spinbox:: 
* Carnet de notes (notebook): Carnet de notes notebook. 
* Barre de progression:: 
* Séparateur:: 
* Poignée de redimensionnement:: 
* Arborescence:: 
* Style Ttk:: 

@end menu

@node Utilisation de Ttk,Widgets Ttk,,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk using-ttk}@anchor{3e05}
@subsubsection Utilisation de `Ttk'


Pour commencer à utiliser `Ttk', importez son module :

@example
from tkinter import ttk
@end example

Pour remplacer les widgets `Tk' de base, l'importation doit suivre l'importation `Tk' :

@example
from tkinter import *
from tkinter.ttk import *
@end example

Ce code implique que plusieurs widgets @ref{f8,,tkinter.ttk} (@code{Button}, @code{Checkbutton}, @code{Entry}, @code{Frame}, @code{Label}, @code{LabelFrame}, @code{Menubutton}, @code{PanedWindow}, @code{Radiobutton}, @code{Scale} et @code{Scrollbar}) remplacent automatiquement les widgets `Tk'.

L'avantage immédiat est d'utiliser les nouveaux widgets qui donnent une meilleure apparence sur toutes les plateformes ; cependant, les widgets de remplacement ne sont pas complètement compatibles. La principale différence est que les options de widget telles que @code{"fg"}, @code{"bg"} et d'autres liées au style des widgets ne sont plus présentes dans les widgets `Ttk'. Utilisez plutôt la classe @code{ttk.Style} pour des effets de style améliorés.


@subsubheading Voir aussi



@table @asis

@item Converting existing applications to use Tile widgets@footnote{https://tktable.sourceforge.net/tile/doc/converting.txt}

Monographie (utilisant la terminologie `Tcl') sur les différences généralement rencontrées lors de la modification d'applications pour utiliser les nouveaux widgets.
@end table


@node Widgets Ttk,Widget,Utilisation de Ttk,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk ttk-widgets}@anchor{3e06}
@subsubsection Widgets `Ttk'


`Ttk' est livré avec 18 widgets, dont douze existaient déjà dans `tkinter' : @code{Button}, @code{Checkbutton}, @code{Entry}, @code{Frame}, @code{Label}, @code{LabelFrame}, @code{Menubutton}, @code{PanedWindow}, @code{Radiobutton}, @code{Scale}, @code{Scrollbar} et @ref{b82,,Spinbox}. Les six autres sont nouveaux : @ref{3e07,,Combobox}, @ref{3e08,,Notebook}, @ref{3e09,,Progressbar}, @code{Separator}, @code{Sizegrip} et @ref{a82,,Treeview}. Et tous sont des sous-classes de @ref{3e0a,,Widget}.

L'utilisation des widgets `Ttk' donne à l'application une apparence et une convivialité améliorées. Comme indiqué ci-dessus, il existe des différences dans la façon dont le style est codé.

Code `Tk' :

@example
l1 = tkinter.Label(text="Test", fg="black", bg="white")
l2 = tkinter.Label(text="Test", fg="black", bg="white")
@end example

Code `Ttk' :

@example
style = ttk.Style()
style.configure("BW.TLabel", foreground="black", background="white")

l1 = ttk.Label(text="Test", style="BW.TLabel")
l2 = ttk.Label(text="Test", style="BW.TLabel")
@end example

Pour plus d'informations sur @ref{3e0b,,TtkStyling}, consultez la documentation de la classe @ref{256,,Style}.

@node Widget,Combobox,Widgets Ttk,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk widget}@anchor{3e0c}
@subsubsection Widget


@code{ttk.Widget} définit les options et méthodes standard prises en charge par les widgets à thème `Tk' et n'est pas censé être directement instancié.

@menu
* Options standards:: 
* Options de widget avec barre de défilement:: 
* Options d'étiquette (label): Options d'étiquette label. 
* Options de compatibilité:: 
* États des widgets:: 
* ttk.Widget: ttk Widget. 

@end menu

@node Options standards,Options de widget avec barre de défilement,,Widget
@anchor{library/tkinter ttk standard-options}@anchor{3e0d}
@subsubsection Options standards


All the @code{ttk} Widgets accept the following options:


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`class'

@tab

Spécifie la classe de fenêtre. La classe est utilisée lors de l'interrogation de la base de données d'options pour les autres options de la fenêtre, pour déterminer les balises de liaison par défaut pour la fenêtre et pour sélectionner la disposition et le style par défaut du widget. Cette option est en lecture seule et ne peut être spécifiée qu'à la création de la fenêtre.

@item

`cursor'

@tab

Spécifie le curseur de la souris à utiliser pour le widget. S'il est défini sur la chaîne vide (valeur par défaut), le curseur est hérité du widget parent.

@item

`takefocus'

@tab

Détermine si la fenêtre accepte le focus pendant le parcours du clavier. 0, 1 ou une chaîne vide est renvoyée. Si 0 est renvoyé, cela signifie que la fenêtre doit être entièrement ignorée lors du parcours au clavier. Si 1, cela signifie que la fenêtre doit recevoir le focus d'entrée tant qu'elle est visible. Et une chaîne vide signifie que les scripts de parcours prennent la décision de donner ou non le focus à la fenêtre.

@item

`style'

@tab

Peut être utilisé pour spécifier un style de widget personnalisé.

@end multitable


@node Options de widget avec barre de défilement,Options d'étiquette label,Options standards,Widget
@anchor{library/tkinter ttk scrollable-widget-options}@anchor{3e0e}
@subsubsection Options de widget avec barre de défilement


Les options suivantes sont prises en charge par les widgets contrôlés par une barre de défilement.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`xscrollcommand'

@tab

Utilisé pour communiquer avec les barres de défilement horizontal.

Lorsque la vue dans la fenêtre du widget change, le widget génère une commande `Tcl' basée sur `scrollcommand'.

Habituellement, cette option consiste en la méthode @code{Scrollbar.set()} d'une barre de défilement. Cela entraîne la mise à jour de la barre de défilement chaque fois que la vue dans la fenêtre change.

@item

`yscrollcommand'

@tab

Utilisé pour communiquer avec les barres de défilement vertical. Pour plus d'informations, voir ci-dessus.

@end multitable


@node Options d'étiquette label,Options de compatibilité,Options de widget avec barre de défilement,Widget
@anchor{library/tkinter ttk label-options}@anchor{3e0f}
@subsubsection Options d'étiquette (`label')


Les options suivantes sont prises en charge par les étiquettes (`labels'), les boutons et autres widgets de type bouton.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`text'

@tab

Spécifie une chaîne de texte à afficher dans le widget.

@item

`textvariable'

@tab

Spécifie un nom dont la valeur est utilisée à la place de la ressource d'option de texte.

@item

`underline'

@tab

S'il est défini, spécifie l'indice (commençant à 0) d'un caractère à souligner dans la chaîne de texte. Le caractère de soulignement est utilisé pour l'activation mnémonique.

@item

`image'

@tab

Spécifie une image à afficher. C'est une liste de un ou plusieurs éléments. Le premier élément est le nom de l'image par défaut. Le reste de la liste est une séquence de paires `statespec'-`valeur' telles que définies par @ref{18ab,,Style.map()}, spécifiant différentes images à utiliser lorsque le widget est dans un état particulier ou une combinaison d'états. Toutes les images de la liste doivent avoir la même taille.

@item

`compound'

@tab

Spécifie comment afficher l'image par rapport au texte, dans le cas où les options de texte et d'images sont présentes. Les valeurs valides sont :


@itemize *

@item 
`text' : afficher uniquement le texte

@item 
`image' : afficher uniquement l'image

@item 
`top', `bottom', `left', `right' : afficher l'image au-dessus, en dessous, à gauche ou à droite du texte, respectivement.

@item 
`none' : la valeur par défaut. Afficher l'image si présente, sinon le texte.
@end itemize

@item

`width'

@tab

Si supérieur à zéro, spécifie la quantité d'espace, en largeurs de caractères, à allouer à l'étiquette de texte, si inférieur à zéro, spécifie une largeur minimale. Si zéro ou non spécifié, la largeur naturelle de l'étiquette de texte est utilisée.

@end multitable


@node Options de compatibilité,États des widgets,Options d'étiquette label,Widget
@anchor{library/tkinter ttk compatibility-options}@anchor{3e10}
@subsubsection Options de compatibilité



@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`state'

@tab

Peut être défini sur @code{"normal"} ou @code{"disabled"} pour contrôler le bit d'état d'activation. Il s'agit d'une option en écriture seule : sa définition modifie l'état du widget, mais la méthode @ref{3e11,,Widget.state()} n'affecte pas cette option.

@end multitable


@node États des widgets,ttk Widget,Options de compatibilité,Widget
@anchor{library/tkinter ttk widget-states}@anchor{3e12}
@subsubsection États des widgets


L'état du widget est une combinaison d'indicateurs d'état indépendants.


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`active'

@tab

Le curseur de la souris est sur le widget et appuyer sur un bouton de la souris provoquera une action

@item

`disabled'

@tab

Le widget est désactivé sous le contrôle du programme

@item

`focus'

@tab

Le widget a le focus du clavier

@item

`pressed'

@tab

Le widget est en train d'être pressé

@item

`selected'

@tab

@code{"On"}, @code{"true"} ou @code{"current"} pour des choses comme les boutons de contrôle et les boutons radio

@item

`background'

@tab

Windows et Mac ont une notion de fenêtre « active » ou de premier plan. L'état `background' est défini pour les widgets dans une fenêtre en arrière-plan et effacé pour ceux de la fenêtre au premier plan

@item

`readonly'

@tab

Le widget ne doit pas permettre la modification par l'utilisateur

@item

`alternate'

@tab

Un format d'affichage alternatif spécifique au widget

@item

`invalid'

@tab

La valeur du widget est invalide

@end multitable


Une spécification d'état est une séquence de noms d'état, éventuellement précédée d'un point d'exclamation indiquant que le bit est désactivé.

@node ttk Widget,,États des widgets,Widget
@anchor{library/tkinter ttk ttk-widget}@anchor{3e13}
@subsubsection ttk.Widget


Outre les méthodes décrites ci-dessous, la @code{ttk.Widget} prend en charge les méthodes @code{tkinter.Widget.cget()} et @code{tkinter.Widget.configure()}.

@geindex Widget (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Widget}@anchor{3e0a}
@deffn {Classe} tkinter.ttk.Widget

@geindex identify() (méthode tkinter.ttk.Widget)
@anchor{library/tkinter ttk tkinter ttk Widget identify}@anchor{3e14}
@deffn {Méthode} identify (x, y)

Renvoie le nom de l'élément à la position `x' `y', ou la chaîne vide si le point ne se trouve dans aucun élément.

`x' et `y' sont des coordonnées en pixels relatives au widget.
@end deffn

@geindex instate() (méthode tkinter.ttk.Widget)
@anchor{library/tkinter ttk tkinter ttk Widget instate}@anchor{3e15}
@deffn {Méthode} instate (statespec, callback=None, *args, **kw)

Teste l'état du widget. Si un rappel n'est pas spécifié, renvoie @code{True} si l'état du widget correspond à `statespec' et @code{False} sinon. Si le rappel est spécifié, il est appelé avec des arguments si l'état du widget correspond à `statespec'.
@end deffn

@geindex state() (méthode tkinter.ttk.Widget)
@anchor{library/tkinter ttk tkinter ttk Widget state}@anchor{3e11}
@deffn {Méthode} state (statespec=None)

Modifie ou demande l'état du widget. Si `statespec' est spécifié, définit l'état du widget en fonction de celui-ci et renvoie un nouveau `statespec' indiquant quels drapeaux ont été modifiés. Si `statespec' n'est pas spécifié, renvoie les indicateurs d'état actuellement activés.
@end deffn

`statespec' est généralement une liste ou un `n'-uplet.
@end deffn

@node Combobox,Spinbox,Widget,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk combobox}@anchor{3e16}
@subsubsection Combobox


Le widget @code{ttk.Combobox} combine un champ de texte avec une liste déroulante de valeurs. Ce widget est une sous-classe de @code{Entry}.

En plus des méthodes héritées de @ref{3e0a,,Widget} : @code{Widget.cget()}, @code{Widget.configure()}, @ref{3e14,,Widget.identify()}, @ref{3e15,,Widget.instate()} et @ref{3e11,,Widget.state()}, et les suivants hérités de @code{Entry} : @code{Entry.bbox()}, @code{Entry.delete()}, @code{Entry.icursor()}, @code{Entry.index()}, @code{Entry.insert()}, @code{Entry.selection()}, @code{Entry.xview()}, il a quelques autres méthodes, décrites dans @code{ttk.Combobox}.

@menu
* Options:: 
* Événements virtuels:: 
* ttk.Combobox: ttk Combobox. 

@end menu

@node Options,Événements virtuels,,Combobox
@anchor{library/tkinter ttk options}@anchor{3e17}
@subsubsection Options


Ce widget accepte les options spécifiques suivantes :


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`exportationsselection'

@tab

Valeur booléenne. Si elle est définie, la sélection du widget est liée à la sélection du gestionnaire de fenêtres (qui peut être renvoyée en appelant `Misc.selection_get', par exemple).

@item

`justify'

@tab

Spécifie comment le texte est aligné dans le widget. Les valeurs possibles sont @code{"left"}, @code{"center"} ou @code{"right"}.

@item

`height'

@tab

Spécifie la hauteur de la liste déroulante, en lignes.

@item

`postcommand'

@tab

Script (éventuellement enregistré avec `Misc.register') qui est appelé immédiatement avant d'afficher les valeurs. Il peut spécifier les valeurs à afficher.

@item

`state'

@tab

Les valeurs sont @code{"normal"}, @code{"readonly"} ou @code{"disabled"}. Dans l'état `readonly', la valeur ne peut pas être modifiée directement et l'utilisateur ne peut que sélectionner les valeurs dans la liste déroulante. Dans l'état `normal', le champ texte est directement éditable. Dans l'état `disabled', aucune interaction n'est possible.

@item

`textvariable'

@tab

Spécifie un nom dont la valeur est liée à la valeur du widget. Chaque fois que la valeur associée à ce nom change, la valeur du widget est mise à jour, et vice versa. Voir @code{tkinter.StringVar}.

@item

`values'

@tab

Spécifie la liste de valeurs à afficher dans la liste déroulante.

@item

`width'

@tab

Spécifie une valeur entière indiquant la largeur souhaitée de la fenêtre d'entrée, en caractères de taille moyenne de la police du widget.

@end multitable


@node Événements virtuels,ttk Combobox,Options,Combobox
@anchor{library/tkinter ttk virtual-events}@anchor{3e18}
@subsubsection Événements virtuels


Les widgets `combobox' génèrent un événement virtuel `<<ComboboxSelected>>' lorsque l'utilisateur sélectionne un élément dans la liste de valeurs.

@node ttk Combobox,,Événements virtuels,Combobox
@anchor{library/tkinter ttk ttk-combobox}@anchor{3e19}
@subsubsection ttk.Combobox


@geindex Combobox (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Combobox}@anchor{3e07}
@deffn {Classe} tkinter.ttk.Combobox

@geindex current() (méthode tkinter.ttk.Combobox)
@anchor{library/tkinter ttk tkinter ttk Combobox current}@anchor{3e1a}
@deffn {Méthode} current (newindex=None)

Si `newindex' est spécifié, définit la valeur de la `combobox' à la position de l'élément `newindex'. Sinon, renvoie l'indice de la valeur courante ou −1 si la valeur courante n'est pas dans la liste des valeurs.
@end deffn

@geindex get() (méthode tkinter.ttk.Combobox)
@anchor{library/tkinter ttk tkinter ttk Combobox get}@anchor{3e1b}
@deffn {Méthode} get ()

Renvoie la valeur actuelle de la `combobox'.
@end deffn

@geindex set() (méthode tkinter.ttk.Combobox)
@anchor{library/tkinter ttk tkinter ttk Combobox set}@anchor{3e1c}
@deffn {Méthode} set (value)

Définit la valeur de la `combobox' sur `value'.
@end deffn
@end deffn

@node Spinbox,Carnet de notes notebook,Combobox,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk spinbox}@anchor{3e1d}
@subsubsection Spinbox


Le widget @code{ttk.Spinbox} est un @code{ttk.Entry} amélioré avec des flèches d'incrémentation et de décrémentation. Il peut être utilisé pour des nombres ou des listes de valeurs de chaîne. Ce widget est une sous-classe de @code{Entry}.

En plus des méthodes héritées de @ref{3e0a,,Widget} : @code{Widget.cget()}, @code{Widget.configure()}, @ref{3e14,,Widget.identify()}, @ref{3e15,,Widget.instate()} et @ref{3e11,,Widget.state()}, et les suivantes héritées de @code{Entry} : @code{Entry.bbox()}, @code{Entry.delete()}, @code{Entry.icursor()}, @code{Entry.index()}, @code{Entry.insert()}, @code{Entry.xview()}, il a quelques autres méthodes, décrites dans @code{ttk.Spinbox}.

@menu
* Options: Options<2>. 
* Événements virtuels: Événements virtuels<2>. 
* ttk.Spinbox: ttk Spinbox. 

@end menu

@node Options<2>,Événements virtuels<2>,,Spinbox
@anchor{library/tkinter ttk id1}@anchor{3e1e}
@subsubsection Options


Ce widget accepte les options spécifiques suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`from'

@tab

Valeur flottante. Si elle est définie, il s'agit de la valeur minimale à laquelle le bouton de décrémentation décrémentera. Doit être orthographié comme @code{from_} lorsqu'il est utilisé comme argument, car @code{from} est un mot-clé Python.

@item

`to'

@tab

Valeur flottante. Si elle est définie, il s'agit de la valeur maximale du bouton d'incrémentation.

@item

`increment'

@tab

Valeur flottante. Spécifie la quantité dont les boutons d'incrémentation/décrémentation modifient la valeur. La valeur par défaut est 1.0.

@item

`values'

@tab

Séquence de valeurs de chaîne ou flottantes. S'ils sont spécifiés, les boutons d'incrémentation/décrémentation font défiler les éléments dans cette séquence plutôt que d'incrémenter ou de décrémenter les nombres.

@item

`wrap'

@tab

Valeur booléenne. Si @code{True}, les boutons d'incrémentation et de décrémentation passent de la valeur @code{to} à la valeur @code{from} ou de la valeur @code{from} à la valeur @code{to}, respectivement.

@item

`format'

@tab

Valeur sous forme de chaîne. Cela spécifie le format des nombres définis par les boutons d'incrémentation/décrémentation. Il doit être sous la forme @code{"%W.Pf"}, où W est la largeur de la valeur, P est la précision et @code{'%'} et @code{'f'} sont littéraux.

@item

`command'

@tab

appelable Python. Est appelé sans argument chaque fois que l'un des boutons d'incrémentation ou de décrémentation est enfoncé.

@end multitable


@node Événements virtuels<2>,ttk Spinbox,Options<2>,Spinbox
@anchor{library/tkinter ttk id2}@anchor{3e1f}
@subsubsection Événements virtuels


Le widget `spinbox' génère un événement virtuel `<<Increment>>' lorsque l'utilisateur appuie sur <Up>, et un événement virtuel `<<Decrement>>' lorsque l'utilisateur appuie sur <Down>.

@node ttk Spinbox,,Événements virtuels<2>,Spinbox
@anchor{library/tkinter ttk ttk-spinbox}@anchor{3e20}
@subsubsection ttk.Spinbox


@geindex Spinbox (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Spinbox}@anchor{b82}
@deffn {Classe} tkinter.ttk.Spinbox

@geindex get() (méthode tkinter.ttk.Spinbox)
@anchor{library/tkinter ttk tkinter ttk Spinbox get}@anchor{3e21}
@deffn {Méthode} get ()

Renvoie la valeur actuelle du `spinbox'.
@end deffn

@geindex set() (méthode tkinter.ttk.Spinbox)
@anchor{library/tkinter ttk tkinter ttk Spinbox set}@anchor{3e22}
@deffn {Méthode} set (value)

Définit la valeur du `spinbox' sur `value'.
@end deffn
@end deffn

@node Carnet de notes notebook,Barre de progression,Spinbox,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk notebook}@anchor{3e23}
@subsubsection Carnet de notes (`notebook')


Le widget `Ttk Notebook' gère une collection de fenêtres et n'en affiche qu'une seule à la fois. Chaque fenêtre enfant est associée à un onglet, que l'utilisateur peut sélectionner pour changer la fenêtre actuellement affichée.

@menu
* Options: Options<3>. 
* Options d'onglet:: 
* Identifiants d'onglet:: 
* Événements virtuels: Événements virtuels<3>. 
* ttk.Notebook: ttk Notebook. 

@end menu

@node Options<3>,Options d'onglet,,Carnet de notes notebook
@anchor{library/tkinter ttk id3}@anchor{3e24}
@subsubsection Options


Ce widget accepte les options spécifiques suivantes :


@multitable {xxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`height'

@tab

S'il est présent et supérieur à zéro, spécifie la hauteur souhaitée de la zone du volet (sans compter l'ajustement interne ni les onglets). Sinon, la hauteur maximale de tous les volets est utilisée.

@item

`padding'

@tab

Spécifie la quantité d'espace supplémentaire à ajouter autour de l'extérieur du bloc-notes. L'ajustement est défini par une liste jusqu'à quatre spécifications de longueur à gauche en haut à droite en bas. Si moins de quatre éléments sont spécifiés, `bottom' vaut par défaut `top', `right' vaut par défaut `left' et `top' vaut par défaut `left'.

@item

`width'

@tab

S'il est présent et supérieur à zéro, spécifiez la largeur souhaitée de la zone du volet (hors ajustement interne). Sinon, la largeur maximale de tous les volets est utilisée.

@end multitable


@node Options d'onglet,Identifiants d'onglet,Options<3>,Carnet de notes notebook
@anchor{library/tkinter ttk tab-options}@anchor{3e25}
@subsubsection Options d'onglet


Il existe également des options spécifiques pour les onglets :


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`state'

@tab

Soit @code{"normal"}, @code{"disabled"} ou @code{"hidden"}. Si `disabled', l'onglet n'est pas sélectionnable. S'il est `hidden', l'onglet n'est pas affiché.

@item

`sticky'

@tab

Spécifie comment la fenêtre enfant est positionnée dans la zone du volet. La valeur est une chaîne contenant zéro ou plusieurs des caractères "n", "s", "e" ou "w". Chaque lettre fait référence à un côté (nord, sud, est ou ouest) auquel la fenêtre enfant colle, selon le gestionnaire de géométrie @code{grid()}.

@item

`padding'

@tab

Spécifie la quantité d'espace supplémentaire à ajouter entre le bloc-notes et ce volet. La syntaxe est la même que pour l'option d'ajustement utilisée par ce widget.

@item

`text'

@tab

Spécifie un texte à afficher dans l'onglet.

@item

`image'

@tab

Spécifie une image à afficher dans l'onglet. Voir l'option `image' décrite dans @ref{3e0a,,Widget}.

@item

`compound'

@tab

Spécifie comment afficher l'image par rapport au texte, dans le cas où les deux options texte et image sont présentes. Voir @ref{3e0f,,Label Options} pour les valeurs autorisées.

@item

`underline'

@tab

Spécifie l'indice (en commençant à 0) d'un caractère à souligner dans la chaîne de texte. Le caractère souligné est utilisé pour l'activation mnémonique si @ref{3e26,,Notebook.enable_traversal()} est appelé.

@end multitable


@node Identifiants d'onglet,Événements virtuels<3>,Options d'onglet,Carnet de notes notebook
@anchor{library/tkinter ttk tab-identifiers}@anchor{3e27}
@subsubsection Identifiants d'onglet


Le `tab_id' présent dans plusieurs méthodes de @code{ttk.Notebook} peut prendre l'une des formes suivantes :


@itemize *

@item 
Un entier compris entre zéro et le nombre d'onglets

@item 
Le nom d'une fenêtre fille

@item 
Une spécification de position de la forme "@@x,y", qui identifie l'onglet

@item 
La chaîne littérale @code{"current"}, qui identifie l'onglet actuellement sélectionné

@item 
La chaîne littérale @code{"end"}, qui renvoie le nombre d'onglets (valable uniquement pour @ref{3e28,,Notebook.index()})
@end itemize

@node Événements virtuels<3>,ttk Notebook,Identifiants d'onglet,Carnet de notes notebook
@anchor{library/tkinter ttk id4}@anchor{3e29}
@subsubsection Événements virtuels


Ce widget génère un événement virtuel `<<NotebookTabChanged>>' après la sélection d'un nouvel onglet.

@node ttk Notebook,,Événements virtuels<3>,Carnet de notes notebook
@anchor{library/tkinter ttk ttk-notebook}@anchor{3e2a}
@subsubsection ttk.Notebook


@geindex Notebook (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Notebook}@anchor{3e08}
@deffn {Classe} tkinter.ttk.Notebook

@geindex add() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook add}@anchor{3e2b}
@deffn {Méthode} add (child, **kw)

Ajoute un nouvel onglet au bloc-notes.

Si la fenêtre est actuellement gérée par le `notebook' mais masquée, elle est restaurée à sa position précédente.

Voir @ref{3e25,,Options d'onglet} pour la liste des options disponibles.
@end deffn

@geindex forget() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook forget}@anchor{3e2c}
@deffn {Méthode} forget (tab_id)

Supprime l'onglet spécifié par `tab_id', et ne gère plus la fenêtre associée.
@end deffn

@geindex hide() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook hide}@anchor{3e2d}
@deffn {Méthode} hide (tab_id)

Masque l'onglet spécifié par `tab_id'.

L'onglet ne s'affiche pas, mais la fenêtre associée reste gérée par le `notebook' et sa configuration mémorisée. Les onglets cachés peuvent être restaurés avec la commande @ref{3e2b,,add()}.
@end deffn

@geindex identify() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook identify}@anchor{3e2e}
@deffn {Méthode} identify (x, y)

Renvoie le nom de l'élément `tab' à la position `x', `y', ou la chaîne vide s'il n'y en a pas.
@end deffn

@geindex index() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook index}@anchor{3e28}
@deffn {Méthode} index (tab_id)

Renvoie l'indice de l'onglet spécifié par `tab_id', ou le nombre total d'onglets si `tab_id' est la chaîne @code{"end"}.
@end deffn

@geindex insert() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook insert}@anchor{3e2f}
@deffn {Méthode} insert (pos, child, **kw)

Insère un volet à la position spécifiée.

`pos' est soit la chaîne @code{"end"}, un indice entier ou le nom d'un enfant géré. Si `child' est déjà géré par le `notebook', le déplace vers la position spécifiée.

Voir @ref{3e25,,Options d'onglet} pour la liste des options disponibles.
@end deffn

@geindex select() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook select}@anchor{3e30}
@deffn {Méthode} select (tab_id=None)

Sélectionne le `tab_id' spécifié.

La fenêtre enfant associée est affichée, et la fenêtre précédemment sélectionnée (si différente) est masquée. Si `tab_id' est omis, renvoie le nom du widget du volet actuellement sélectionné.
@end deffn

@geindex tab() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook tab}@anchor{3e31}
@deffn {Méthode} tab (tab_id, option=None, **kw)

Interroge ou modifie les options du `tab_id' spécifique.

Si `kw' n'est pas donné, renvoie un dictionnaire des valeurs des options de l'onglet. Si `option' est spécifié, renvoie la valeur de cette `option'. Sinon, définit les options sur les valeurs correspondantes.
@end deffn

@geindex tabs() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook tabs}@anchor{3e32}
@deffn {Méthode} tabs ()

Renvoie une liste des fenêtres gérées par le `notebook'.
@end deffn

@geindex enable_traversal() (méthode tkinter.ttk.Notebook)
@anchor{library/tkinter ttk tkinter ttk Notebook enable_traversal}@anchor{3e26}
@deffn {Méthode} enable_traversal ()

Active la traversée du clavier pour une fenêtre de niveau supérieur contenant ce bloc-notes.

Cela étend les liaisons pour la fenêtre de niveau supérieur contenant le bloc-notes comme suit :


@itemize *

@item 
@code{Control-Tab} : sélectionne l'onglet suivant celui actuellement sélectionné.

@item 
@code{Shift-Control-Tab} : sélectionne l'onglet précédant celui actuellement sélectionné.

@item 
@code{Alt-K} : où `K' est le caractère mnémonique (souligné) de n'importe quel onglet, sélectionne cet onglet.
@end itemize

Plusieurs blocs-notes dans un seul niveau supérieur peuvent être activés pour la traversée, y compris les blocs-notes imbriqués. Cependant, la traversée du bloc-notes ne fonctionne correctement que si tous les volets ont le bloc-notes dans lequel ils se trouvent en tant que maître.
@end deffn
@end deffn

@node Barre de progression,Séparateur,Carnet de notes notebook,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk progressbar}@anchor{3e33}
@subsubsection Barre de progression


Le widget @code{ttk.Progressbar} affiche l'état d'une opération de longue durée. Il peut fonctionner en deux modes : 1) le mode déterminé qui indique la quantité achevée par rapport à la quantité totale de travail à effectuer et 2) le mode indéterminé qui fournit un affichage animé pour informer l'utilisateur que le travail progresse.

@menu
* Options: Options<4>. 
* ttk.Progressbar: ttk Progressbar. 

@end menu

@node Options<4>,ttk Progressbar,,Barre de progression
@anchor{library/tkinter ttk id5}@anchor{3e34}
@subsubsection Options


Ce widget accepte les options spécifiques suivantes :


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`orient'

@tab

@code{"horizontal"} ou @code{"vertical"}. Spécifie l'orientation de la barre de progression.

@item

`length'

@tab

Spécifie la longueur de l'axe long de la barre de progression (largeur si horizontale, hauteur si verticale).

@item

`mode'

@tab

@code{"determinate"} ou @code{"indeterminate"}.

@item

`maximum'

@tab

Nombre spécifiant la valeur maximale. La valeur par défaut est 100.

@item

`value'

@tab

La valeur actuelle de la barre de progression. En mode `determinate', cela représente la quantité de travail accompli. En mode `indeterminate', il est interprété comme modulo `maximum' ; c'est-à-dire que la barre de progression effectue un « cycle » lorsque sa valeur augmente de `maximum'.

@item

`variable'

@tab

Nom lié à la valeur de l'option. Si spécifié, la valeur de la barre de progression est automatiquement fixée à la valeur de ce nom à chaque modification de ce dernier.

@item

`phase'

@tab

Option en lecture seule. Le widget incrémente périodiquement la valeur de cette option chaque fois que sa valeur est supérieure à 0 et, en mode `déterminate', inférieure au maximum. Cette option peut être utilisée par le thème actuel pour fournir des effets d'animation supplémentaires.

@end multitable


@node ttk Progressbar,,Options<4>,Barre de progression
@anchor{library/tkinter ttk ttk-progressbar}@anchor{3e35}
@subsubsection ttk.Progressbar


@geindex Progressbar (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Progressbar}@anchor{3e09}
@deffn {Classe} tkinter.ttk.Progressbar

@geindex start() (méthode tkinter.ttk.Progressbar)
@anchor{library/tkinter ttk tkinter ttk Progressbar start}@anchor{3e36}
@deffn {Méthode} start (interval=None)

Commence le mode d'auto-incrémentation : planifie un événement de minuterie récurrent qui appelle @ref{3e37,,Progressbar.step()} toutes les `interval' millisecondes. S'il est omis, `interval' est par défaut de 50 millisecondes.
@end deffn

@geindex step() (méthode tkinter.ttk.Progressbar)
@anchor{library/tkinter ttk tkinter ttk Progressbar step}@anchor{3e37}
@deffn {Méthode} step (amount=None)

Incrémente la valeur de la barre de progression de `amount'.

`amount' est par défaut égal à @code{1.0} s'il est omis.
@end deffn

@geindex stop() (méthode tkinter.ttk.Progressbar)
@anchor{library/tkinter ttk tkinter ttk Progressbar stop}@anchor{3e38}
@deffn {Méthode} stop ()

Arrête le mode d'auto-incrémentation : annule tout événement de minuterie récurrent initié par @ref{3e36,,Progressbar.start()} pour cette barre de progression.
@end deffn
@end deffn

@node Séparateur,Poignée de redimensionnement,Barre de progression,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk separator}@anchor{3e39}
@subsubsection Séparateur


Le widget @code{ttk.Separator} affiche une barre de séparation horizontale ou verticale.

Il n'a pas d'autres méthodes que celles héritées de @code{ttk.Widget}.

@menu
* Options: Options<5>. 

@end menu

@node Options<5>,,,Séparateur
@anchor{library/tkinter ttk id6}@anchor{3e3a}
@subsubsection Options


Ce widget accepte l'option spécifique suivante :


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`orient'

@tab

@code{"horizontal"} ou @code{"vertical"}. Spécifie l'orientation du séparateur.

@end multitable


@node Poignée de redimensionnement,Arborescence,Séparateur,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk sizegrip}@anchor{3e3b}
@subsubsection Poignée de redimensionnement


Le widget @code{ttk.Sizegrip} (également connu sous le nom de `grow box') permet à l'utilisateur de redimensionner la fenêtre de niveau supérieur en appuyant et en faisant glisser la poignée.

Ce widget n'a ni options spécifiques ni méthodes spécifiques, à part celles héritées de @code{ttk.Widget}.

@menu
* Notes spécifiques à une plateforme:: 
* Bogues:: 

@end menu

@node Notes spécifiques à une plateforme,Bogues,,Poignée de redimensionnement
@anchor{library/tkinter ttk platform-specific-notes}@anchor{3e3c}
@subsubsection Notes spécifiques à une plateforme



@itemize *

@item 
Sur macOS, les fenêtres de niveau supérieur incluent automatiquement une poignée de redimensionnement intégrée par défaut. L'ajout d'un @code{Sizegrip} est sans danger, car la poignée intégrée masquera simplement le widget.
@end itemize

@node Bogues,,Notes spécifiques à une plateforme,Poignée de redimensionnement
@anchor{library/tkinter ttk bugs}@anchor{3e3d}
@subsubsection Bogues



@itemize *

@item 
Si la position du contenant de niveau supérieur a été spécifiée par rapport à la droite ou au bas de l'écran (par exemple…), le widget @code{Sizegrip} ne redimensionne pas la fenêtre.

@item 
Ce widget ne prend en charge que le redimensionnement @code{"southeast"}.
@end itemize

@node Arborescence,Style Ttk,Poignée de redimensionnement,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk treeview}@anchor{3e3e}
@subsubsection Arborescence


Le widget @code{ttk.Treeview} affiche une collection hiérarchique d'éléments. Chaque élément possède une étiquette textuelle, une image facultative et une liste facultative de valeurs de données. Les valeurs des données sont affichées dans des colonnes successives après l'étiquette de l'arbre.

L'ordre dans lequel les valeurs de données sont affichées peut être contrôlé en définissant l'option de widget @code{displaycolumns}. Le widget d'arborescence peut également afficher les en-têtes de colonne. Les colonnes sont accessibles par des numéros ou des noms symboliques indiqués dans l'option `columns' du widget. Voir @ref{3e3f,,Identifiants de colonnes}.

Chaque élément est identifié par un nom unique. Le widget génère des identifiants d'éléments s'ils ne sont pas fournis par l'appelant. Il existe un élément racine distinct, nommé @code{@{@}}. L'élément racine lui-même n'est pas affiché ; ses enfants apparaissent au niveau supérieur de la hiérarchie.

Chaque élément possède également une liste de balises, qui peuvent être utilisées pour associer des liaisons d'événements à des éléments individuels et contrôler l'apparence de l'élément.

Le widget `Treeview' prend en charge le défilement horizontal et vertical, selon les options décrites dans @ref{3e0e,,Scrollable Widget Options} et les méthodes @ref{3e40,,Treeview.xview()} et @ref{3e41,,Treeview.yview()}.

@menu
* Options: Options<6>. 
* Options d'éléments:: 
* Options de balise:: 
* Identifiants de colonnes:: 
* Événements virtuels: Événements virtuels<4>. 
* ttk.Treeview: ttk Treeview. 

@end menu

@node Options<6>,Options d'éléments,,Arborescence
@anchor{library/tkinter ttk id7}@anchor{3e42}
@subsubsection Options


Ce widget accepte les options spécifiques suivantes :


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`columns'

@tab

Une liste d'identificateurs de colonne, spécifiant le nombre de colonnes et leurs noms.

@item

`displaycolumns'

@tab

Une liste d'identificateurs de colonne (indices symboliques ou entiers) spécifiant quelles colonnes de données sont affichées et l'ordre dans lequel elles apparaissent, ou la chaîne @code{"#all"}.

@item

`height'

@tab

Spécifie le nombre de lignes qui doivent être visibles. Remarque : la largeur demandée est déterminée à partir de la somme des largeurs de colonne.

@item

`padding'

@tab

Spécifie le remplissage interne du widget. L'ajustement est décrit par une liste jusqu'à quatre spécifications de longueur.

@item

`selectmode'

@tab

Contrôle la façon dont les liaisons de classe intégrées gèrent la sélection. Les valeurs possibles sont @code{"extended"}, @code{"browse"} ou @code{"none"}. S'il est défini sur `extended' (valeur par défaut), plusieurs éléments peuvent être sélectionnés. Si c'est `browse' un seul élément ne peut être sélectionné à la fois. Si c'est `none', la sélection ne peut pas être modifiée.

Notez que le code d'application et les liaisons de balises peuvent définir la sélection comme ils le souhaitent, quelle que soit la valeur de cette option.

@item

`show'

@tab

Une liste contenant zéro ou plusieurs des valeurs suivantes, spécifiant les éléments de l'arborescence à afficher.


@itemize *

@item 
`tree' : affiche les étiquettes de l'arbre dans la colonne 0.

@item 
`headings' : affiche la ligne d'en-tête.
@end itemize

La valeur par défaut est @code{"tree headings"}, c'est-à-dire afficher tous les éléments.

`Remarque' : la colonne 0 fait toujours référence à la colonne de l'arborescence, même si @code{show="tree"} n'est pas spécifié.

@end multitable


@node Options d'éléments,Options de balise,Options<6>,Arborescence
@anchor{library/tkinter ttk item-options}@anchor{3e43}
@subsubsection Options d'éléments


Les options d'éléments suivantes peuvent être spécifiées pour les éléments dans les commandes `insert' et les widgets de type élément.


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`text'

@tab

Libellé textuel à afficher pour l'élément.

@item

`image'

@tab

Image `Tk', affichée à gauche de l'étiquette.

@item

`values'

@tab

Liste des valeurs associées à l'élément.

Chaque élément doit avoir le même nombre de valeurs que les colonnes d'options du widget. S'il y a moins de valeurs que de colonnes, les valeurs restantes sont supposées vides. S'il y a plus de valeurs que de colonnes, les valeurs supplémentaires sont ignorées.

@item

`open'

@tab

Valeur @code{True} ou @code{False} indiquant si les enfants de l'élément doivent être affichés ou masqués.

@item

`tags'

@tab

Liste de balises associées à cet élément.

@end multitable


@node Options de balise,Identifiants de colonnes,Options d'éléments,Arborescence
@anchor{library/tkinter ttk tag-options}@anchor{3e44}
@subsubsection Options de balise


Les options suivantes peuvent être spécifiées sur les balises :


@multitable {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Description

@item

`foreground'

@tab

Spécifie la couleur de premier plan du texte.

@item

`background'

@tab

Spécifie la couleur d'arrière-plan de la cellule ou de l'élément.

@item

`font'

@tab

Spécifie la police à utiliser lors du dessin du texte.

@item

`image'

@tab

Spécifie l'image de l'élément, au cas où l'option d'image de l'élément est vide.

@end multitable


@node Identifiants de colonnes,Événements virtuels<4>,Options de balise,Arborescence
@anchor{library/tkinter ttk column-identifiers}@anchor{3e3f}
@subsubsection Identifiants de colonnes


Les identifiants de colonnes prennent l'une des formes suivantes :


@itemize *

@item 
Un nom symbolique de l'option de liste de colonnes.

@item 
Un entier n, spécifiant la n@w{^ième} colonne de données.

@item 
Une chaîne de la forme #n, où n est un entier, spécifiant la n@w{^ième} colonne d'affichage.
@end itemize

Notes :


@itemize *

@item 
Les valeurs d'option de l'élément peuvent être affichées dans un ordre différent de celui dans lequel elles sont stockées.

@item 
La colonne #0 fait toujours référence à la colonne de l'arborescence, même si @code{show="tree"} n'est pas spécifié.
@end itemize

Un numéro de colonne de données est un indice dans la liste des valeurs d'option d'un élément ; un numéro de colonne d'affichage est le numéro de colonne dans l'arborescence où les valeurs sont affichées. Les étiquettes d'arbre sont affichées dans la colonne #0. Si l'option `displaycolumns' n'est pas définie, la colonne de données n s'affiche dans la colonne #n+1. Encore une fois, `la colonne #0 fait toujours référence à la colonne de l'arborescence'.

@node Événements virtuels<4>,ttk Treeview,Identifiants de colonnes,Arborescence
@anchor{library/tkinter ttk id8}@anchor{3e45}
@subsubsection Événements virtuels


Le widget `Treeview' génère les événements virtuels suivants.


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Événement

@tab

Description

@item

<<TreeviewSelect>>

@tab

Généré chaque fois que la sélection change.

@item

<<TreeviewOpen>>

@tab

Généré juste avant de définir l'élément de focus sur @code{open=True}.

@item

<<TreeviewClose>>

@tab

Généré juste après avoir défini l'élément de focus sur @code{open=False}.

@end multitable


Les méthodes @ref{3e46,,Treeview.focus()} et @ref{a81,,Treeview.selection()} peuvent être utilisées pour déterminer le ou les éléments concernés.

@node ttk Treeview,,Événements virtuels<4>,Arborescence
@anchor{library/tkinter ttk ttk-treeview}@anchor{3e47}
@subsubsection ttk.Treeview


@geindex Treeview (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Treeview}@anchor{a82}
@deffn {Classe} tkinter.ttk.Treeview

@geindex bbox() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview bbox}@anchor{3e48}
@deffn {Méthode} bbox (item, column=None)

Renvoie la boîte englobante (relative à la fenêtre du widget `treeview') de l'`item' spécifié sous la forme (x, y, largeur, hauteur).

Si `column' est spécifié, renvoie la boîte englobante de cette cellule. Si `item' n'est pas visible (c'est-à-dire s'il est un descendant d'un élément fermé ou se trouve hors écran en raison du défilement), renvoie une chaîne vide.
@end deffn

@geindex get_children() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview get_children}@anchor{3e49}
@deffn {Méthode} get_children (item=None)

Renvoie la liste des enfants appartenant à `item'.

Si `item' n'est pas spécifié, renvoie les enfants racine.
@end deffn

@geindex set_children() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview set_children}@anchor{3e4a}
@deffn {Méthode} set_children (item, *newchildren)

Remplace l'enfant de `item' par `newchildren'.

Les enfants présents dans `item' qui ne sont pas présents dans `newchildren' sont détachés de l'arbre. Aucun élément de `newchildren' ne peut être un ancêtre de `item'. Notez que ne pas spécifier `newchildren' entraîne le détachement des enfants de `item'.
@end deffn

@geindex column() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview column}@anchor{3e4b}
@deffn {Méthode} column (column, option=None, **kw)

Interroge ou modifie les options pour la `column' spécifiée.

Si `kw' n'est pas donné, renvoie un dictionnaire des valeurs d'option de colonne. Si `option' est spécifié, la valeur de cette `option' est renvoyée. Sinon, définit les options sur les valeurs correspondantes.

Les options/valeurs valides sont :


@table @asis

@item `id'

Renvoie le nom de la colonne. Il s'agit d'une option en lecture seule.

@item `anchor': One of the standard Tk anchor values.

Spécifie comment le texte de cette colonne doit être aligné par rapport à la cellule.

@item `minwidth': width

La largeur minimale de la colonne en pixels. Le widget `Treeview' ne rend pas la colonne plus petite que celle spécifiée par cette option lorsque le widget est redimensionné ou que l'utilisateur fait glisser une colonne.

@item `stretch': @code{True}/@code{False}

Spécifie si la largeur de la colonne doit être ajustée lorsque le widget est redimensionné.

@item `width': width

La largeur de la colonne en pixels.
@end table

Pour configurer la colonne d'arborescence, appelez-la avec @code{column = "#0"}
@end deffn

@geindex delete() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview delete}@anchor{3e4c}
@deffn {Méthode} delete (*items)

Supprime tous les `items' spécifiés et tous leurs descendants.

L'élément racine ne peut pas être supprimé.
@end deffn

@geindex detach() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview detach}@anchor{3e4d}
@deffn {Méthode} detach (*items)

Dissocie tous les `items' spécifiés de l'arborescence.

Les éléments et tous leurs descendants sont toujours présents et peuvent être réinsérés à un autre point de l'arborescence, mais ne seront pas affichés.

L'élément racine ne peut pas être détaché.
@end deffn

@geindex exists() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview exists}@anchor{3e4e}
@deffn {Méthode} exists (item)

Renvoie @code{True} si l'`item' spécifié est présent dans l'arborescence.
@end deffn

@geindex focus() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview focus}@anchor{3e46}
@deffn {Méthode} focus (item=None)

Si `item' est spécifié, définit l'élément de focus sur `item'. Sinon, renvoie l'élément de focus actuel, ou @code{'@w{'}} s'il n'y en a pas.
@end deffn

@geindex heading() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview heading}@anchor{3e4f}
@deffn {Méthode} heading (column, option=None, **kw)

Interroge ou modifie les options d'en-tête pour la `column' spécifiée.

Si `kw' n'est pas donné, renvoie un dictionnaire des valeurs d'option d'en-tête. Si `option' est spécifié, la valeur de cette `option' est renvoyée. Sinon, définit les options sur les valeurs correspondantes.

Les options/valeurs valides sont :


@table @asis

@item `text': text

Texte à afficher dans l'en-tête de colonne.

@item `image': imageName

Spécifie une image à afficher à droite de l'en-tête de colonne.

@item `anchor': anchor

Spécifie comment le texte du titre doit être aligné. Une des valeurs d'ancrage `Tk' standard.

@item `command': callback

Un rappel à invoquer lorsque l'étiquette d'en-tête est pressée.
@end table

Pour configurer l'en-tête de colonne de l'arborescence, appelez-la avec @code{column = "#0"}.
@end deffn

@geindex identify() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify}@anchor{3e50}
@deffn {Méthode} identify (component, x, y)

Renvoie une description du `component' spécifié sous le point donné par `x' et `y', ou la chaîne vide si aucun `component' de ce type n'est présent à cette position.
@end deffn

@geindex identify_row() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_row}@anchor{3e51}
@deffn {Méthode} identify_row (y)

Renvoie l'ID d'élément de l'élément à la position `y'.
@end deffn

@geindex identify_column() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_column}@anchor{3e52}
@deffn {Méthode} identify_column (x)

Renvoie l'identificateur de colonne de données de la cellule à la position `x'.

La colonne arborescence possède l'ID #0.
@end deffn

@geindex identify_region() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_region}@anchor{3e53}
@deffn {Méthode} identify_region (x, y)

Renvoie l'un des éléments suivants :


@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

`region'

@tab

signification

@item

`heading'

@tab

Zone d'en-tête de l'arbre.

@item

`separator'

@tab

Espace entre deux en-têtes de colonnes.

@item

`tree' (arbre)

@tab

Une zone de l'arbre.

@item

`cell'

@tab

Une cellule de données.

@end multitable


Disponibilité : `Tk' 8.6.
@end deffn

@geindex identify_element() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview identify_element}@anchor{3e54}
@deffn {Méthode} identify_element (x, y)

Renvoie l'élément à la position `x', `y'.

Disponibilité : `Tk' 8.6.
@end deffn

@geindex index() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview index}@anchor{3e55}
@deffn {Méthode} index (item)

Renvoie l'indice (entier) de `item' dans la liste des enfants de son parent.
@end deffn

@geindex insert() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview insert}@anchor{3e56}
@deffn {Méthode} insert (parent, index, iid=None, **kw)

Crée un nouvel élément et renvoie l'identifiant de l'élément nouvellement créé.

`parent' est l'ID d'élément de l'élément parent ou la chaîne vide pour créer un nouvel élément de niveau supérieur. `index' est un entier, ou la valeur @code{"end"}, spécifiant où dans la liste des enfants du parent insérer le nouvel élément. Si `index' est inférieur ou égal à zéro, le nouveau nœud est inséré au début ; si `index' est supérieur ou égal au nombre actuel d'enfants, il est inséré à la fin. Si `iid' est spécifié, il est utilisé comme identifiant d'élément ; `iid' ne doit pas déjà exister dans l'arborescence. Sinon, un nouvel identifiant unique est généré.

See @ref{3e43,,Item Options} for the list of available options.
@end deffn

@geindex item() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview item}@anchor{3e57}
@deffn {Méthode} item (item, option=None, **kw)

Interroge ou modifie les options pour l'`item' spécifié.

Si aucune option n'est donnée, un dictionnaire avec des options/valeurs pour l'élément est renvoyé. Si `option' est spécifié, la valeur de cette option est renvoyée. Sinon, définit les options sur les valeurs correspondantes données par `kw'.
@end deffn

@geindex move() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview move}@anchor{3e58}
@deffn {Méthode} move (item, parent, index)

Déplace `item' vers la position `index' dans la liste des enfants de `parent'.

Il est interdit de déplacer un élément sous l'un de ses descendants. Si `index' est inférieur ou égal à zéro, `item' est déplacé au début ; s'il est supérieur ou égal au nombre d'enfants, il est déplacé à la fin. Si `item' a été détaché, il est rattaché.
@end deffn

@geindex next() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview next}@anchor{3e59}
@deffn {Méthode} next (item)

Renvoie l'identifiant du frère suivant de `item', ou @code{'@w{'}} si `item' est le dernier enfant de son parent.
@end deffn

@geindex parent() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview parent}@anchor{3e5a}
@deffn {Méthode} parent (item)

Renvoie l'identifiant du parent de `item', ou @code{'@w{'}} si `item' est au niveau supérieur de la hiérarchie.
@end deffn

@geindex prev() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview prev}@anchor{3e5b}
@deffn {Méthode} prev (item)

Renvoie l'identifiant du frère précédent de `item', ou @code{'@w{'}} si `item' est le premier enfant de son parent.
@end deffn

@geindex reattach() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview reattach}@anchor{3e5c}
@deffn {Méthode} reattach (item, parent, index)

Alias pour @ref{3e58,,Treeview.move()}.
@end deffn

@geindex see() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview see}@anchor{3e5d}
@deffn {Méthode} see (item)

Fait en sorte que `item' soit visible.

Définit l'option d'ouverture de tous les ancêtres de `item' sur @code{True}, et fait défiler le widget si nécessaire afin que `item' soit dans la partie visible de l'arborescence.
@end deffn

@geindex selection() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection}@anchor{a81}
@deffn {Méthode} selection ()

Renvoie un `n'-uplet d'éléments sélectionnés.


Modifié dans la version 3.8: @code{selection()} ne prend plus d'arguments. Pour modifier l'état de sélection, utilisez les méthodes de sélection suivantes.

@end deffn

@geindex selection_set() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_set}@anchor{a83}
@deffn {Méthode} selection_set (*items)

`items' devient la nouvelle sélection.


Modifié dans la version 3.6: `items' peut être passé en tant qu'arguments séparés, pas seulement en tant que `n'-uplet.

@end deffn

@geindex selection_add() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_add}@anchor{3e5e}
@deffn {Méthode} selection_add (*items)

Ajoute des `items' à la sélection.


Modifié dans la version 3.6: `items' peut être passé en tant qu'arguments séparés, pas seulement en tant que `n'-uplet.

@end deffn

@geindex selection_remove() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_remove}@anchor{3e5f}
@deffn {Méthode} selection_remove (*items)

Supprime les `items' de la sélection.


Modifié dans la version 3.6: `items' peut être passé en tant qu'arguments séparés, pas seulement en tant que `n'-uplet.

@end deffn

@geindex selection_toggle() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview selection_toggle}@anchor{3e60}
@deffn {Méthode} selection_toggle (*items)

Bascule l'état de sélection de chaque élément de `items'.


Modifié dans la version 3.6: `items' peut être passé en tant qu'arguments séparés, pas seulement en tant que `n'-uplet.

@end deffn

@geindex set() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview set}@anchor{3e61}
@deffn {Méthode} set (item, column=None, value=None)

Avec un argument, renvoie un dictionnaire de paires colonne/valeur pour l'`item' spécifié. Avec deux arguments, renvoie la valeur actuelle de la `column' spécifiée. Avec trois arguments, définit la valeur de la `column' donnée dans l'`item' donné à la `value' spécifiée.
@end deffn

@geindex tag_bind() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview tag_bind}@anchor{3e62}
@deffn {Méthode} tag_bind (tagname, sequence=None, callback=None)

Lie le rappel `callback' à l'événement donné `sequence' pour la balise `tagname'. Lorsqu'un événement est envoyé à un élément, les rappels pour chacune des options de balises de l'élément sont appelés.
@end deffn

@geindex tag_configure() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview tag_configure}@anchor{3e63}
@deffn {Méthode} tag_configure (tagname, option=None, **kw)

Interroge ou modifie les options pour le `tagname' spécifié.

Si `kw' n'est pas donné, renvoie un dictionnaire des paramètres d'option pour `tagname'. Si `option' est spécifié, renvoie la valeur de cette `option' pour le `tagname' spécifié. Sinon, définit les options sur les valeurs correspondantes pour le `tagname' donné.
@end deffn

@geindex tag_has() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview tag_has}@anchor{3e64}
@deffn {Méthode} tag_has (tagname, item=None)

Si `item' est spécifié, renvoie 1 ou 0 selon que `item' spécifié a le `tagname' donné. Sinon, renvoie une liste de tous les éléments qui ont la balise spécifiée.

Disponibilité : `Tk' 8.6
@end deffn

@geindex xview() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview xview}@anchor{3e40}
@deffn {Méthode} xview (*args)

Interroge ou modifie la position horizontale de l'arborescence.
@end deffn

@geindex yview() (méthode tkinter.ttk.Treeview)
@anchor{library/tkinter ttk tkinter ttk Treeview yview}@anchor{3e41}
@deffn {Méthode} yview (*args)

Interroge ou modifie la position verticale de l'arborescence.
@end deffn
@end deffn

@node Style Ttk,,Arborescence,tkinter ttk --- Tk themed widgets
@anchor{library/tkinter ttk ttk-styling}@anchor{3e65}@anchor{library/tkinter ttk ttkstyling}@anchor{3e0b}
@subsubsection Style Ttk


Chaque widget dans @code{ttk} se voit attribuer un style, qui spécifie l'ensemble d'éléments composant le widget et la façon dont ils sont disposés, ainsi que les paramètres dynamiques et par défaut pour les options d'élément. Par défaut, le nom du style est le même que le nom de la classe du widget, mais il peut être remplacé par l'option de style du widget. Si vous ne connaissez pas le nom de classe d'un widget, utilisez la méthode @code{Misc.winfo_class()} (`somewidget.winfo_class()').


@subsubheading Voir aussi



@table @asis

@item Tcl'2004 conference presentation@footnote{https://tktable.sourceforge.net/tile/tile-tcl2004.pdf}

Ce document explique le fonctionnement du moteur de thème
@end table


@geindex Style (classe dans tkinter.ttk)
@anchor{library/tkinter ttk tkinter ttk Style}@anchor{256}
@deffn {Classe} tkinter.ttk.Style

Cette classe est utilisée pour manipuler la base de données de style.

@geindex configure() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style configure}@anchor{3e66}
@deffn {Méthode} configure (style, query_opt=None, **kw)

Interroge ou définit la valeur par défaut des options spécifiées dans `style'.

Chaque clé dans `kw' est une option et chaque valeur est une chaîne identifiant la valeur de cette option.

Par exemple, pour changer chaque bouton par défaut en un bouton plat avec un ajustement et une couleur d'arrière-plan différente :

@example
from tkinter import ttk
import tkinter

root = tkinter.Tk()

ttk.Style().configure("TButton", padding=6, relief="flat",
   background="#ccc")

btn = ttk.Button(text="Sample")
btn.pack()

root.mainloop()
@end example
@end deffn

@geindex map() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style map}@anchor{18ab}
@deffn {Méthode} map (style, query_opt=None, **kw)

Interroge ou définit les valeurs dynamiques des options spécifiées dans `style'.

Chaque clé dans `kw' est une option et chaque valeur doit être une liste ou un `n'-uplet (généralement) contenant des spécifications d'état regroupées dans des `n'-uplets, des listes ou une autre préférence. Un `statespec' est un composé d'un ou plusieurs états, puis d'une valeur.

Un exemple peut le rendre plus compréhensible :

@example
import tkinter
from tkinter import ttk

root = tkinter.Tk()

style = ttk.Style()
style.map("C.TButton",
    foreground=[('pressed', 'red'), ('active', 'blue')],
    background=[('pressed', '!disabled', 'black'), ('active', 'white')]
    )

colored_btn = ttk.Button(text="Test", style="C.TButton").pack()

root.mainloop()
@end example

Notez que l'ordre des séquences (états, valeur) pour une option est important, si l'ordre est changé en @code{[('active', 'blue'), ('pressed', 'red')]} dans l'option de premier plan, par exemple, le résultat est un premier plan bleu lorsque le widget est dans les états actif ou pressé.
@end deffn

@geindex lookup() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style lookup}@anchor{3e67}
@deffn {Méthode} lookup (style, option, state=None, default=None)

Renvoie la valeur spécifiée pour `option' dans `style'.

Si `state' est spécifié, on s'attend à ce qu'il s'agisse d'une séquence d'un ou plusieurs états. Si l'argument `default' est défini, il est utilisé comme valeur de secours au cas où aucune spécification d'option n'est trouvée.

Pour vérifier quelle police un bouton utilise par défaut :

@example
from tkinter import ttk

print(ttk.Style().lookup("TButton", "font"))
@end example
@end deffn

@geindex layout() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style layout}@anchor{3e68}
@deffn {Méthode} layout (style, layoutspec=None)

Définit la disposition du widget pour un `style' donné. Si `layoutspec' est omis, renvoie la spécification de mise en page pour le style donné.

`layoutspec', si spécifié, doit être une liste ou un autre type de séquence (à l'exception des chaînes), où chaque élément doit être un `n'-uplet et le premier élément est le nom de la mise en page et le deuxième élément doit avoir le format décrit dans @ref{3e69,,Layouts}.

Pour comprendre le format, consultez l'exemple suivant (il n'est pas destiné à faire quoi que ce soit d'utile) :

@example
from tkinter import ttk
import tkinter

root = tkinter.Tk()

style = ttk.Style()
style.layout("TMenubutton", [
   ("Menubutton.background", None),
   ("Menubutton.button", @{"children":
       [("Menubutton.focus", @{"children":
           [("Menubutton.padding", @{"children":
               [("Menubutton.label", @{"side": "left", "expand": 1@})]
           @})]
       @})]
   @}),
])

mbtn = ttk.Menubutton(text='Text')
mbtn.pack()
root.mainloop()
@end example
@end deffn

@geindex element_create() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style element_create}@anchor{255}
@deffn {Méthode} element_create (elementname, etype, *args, **kw)

Create a new element in the current theme, of the given `etype' which is
expected to be either "image", "from" or "vsapi".
The latter is only available in Tk 8.6 on Windows.

Si `image' est utilisé, `args' doit contenir le nom de l'image par défaut suivi de paires `statespec' / `value' (il s'agit de l'`imagespec'), et `kw' peut avoir les options suivantes :


@table @asis

@item `border'=remplissage

`padding' est une liste de quatre entiers maximum, spécifiant respectivement les bordures gauche, supérieure, droite et inférieure.

@item `height'=hauteur

Spécifie une hauteur minimale pour l'élément. Si elle est inférieure à zéro, la hauteur de l'image de base est utilisée par défaut.

@item `padding'= ajustement

Spécifie l'ajustement intérieur de l'élément. La valeur par défaut est la valeur de `border' si elle n'est pas spécifiée.

@item `sticky'= `spec'

Spécifie comment l'image est placée dans la partie de l'espace attribué finale. `spec' contient zéro ou plusieurs caractères "n", "s", "w" ou "e".

@item `width'=largeur

Spécifie une largeur minimale pour l'élément. Si inférieur à zéro, la largeur de l'image de base est utilisée par défaut.
@end table

Exemple :

@example
img1 = tkinter.PhotoImage(master=root, file='button.png')
img1 = tkinter.PhotoImage(master=root, file='button-pressed.png')
img1 = tkinter.PhotoImage(master=root, file='button-active.png')
style = ttk.Style(root)
style.element_create('Button.button', 'image',
                     img1, ('pressed', img2), ('active', img3),
                     border=(2, 4), sticky='we')
@end example

Si `from' est utilisé comme valeur de `etype', @ref{255,,element_create()} clone un élément existant. `args' doit contenir un nom de thème, à partir duquel l'élément est cloné, et éventuellement un élément à cloner. Si cet élément qu'il faut cloner n'est pas spécifié, un élément vide est utilisé. `kw' est ignoré.

Exemple :

@example
style = ttk.Style(root)
style.element_create('plain.background', 'from', 'default')
@end example

If "vsapi" is used as the value of `etype', @ref{255,,element_create()}
will create a new element in the current theme whose visual appearance
is drawn using the Microsoft Visual Styles API which is responsible
for the themed styles on Windows XP and Vista.
`args' is expected to contain the Visual Styles class and part as
given in the Microsoft documentation followed by an optional sequence
of tuples of ttk states and the corresponding Visual Styles API state
value.
`kw' may have the following options:


@table @asis

@item `padding'= ajustement

Specify the element's interior padding.
`padding' is a list of up to four integers specifying the left,
top, right and bottom padding quantities respectively.
If fewer than four elements are specified, bottom defaults to top,
right defaults to left, and top defaults to left.
In other words, a list of three numbers specify the left, vertical,
and right padding; a list of two numbers specify the horizontal
and the vertical padding; a single number specifies the same
padding all the way around the widget.
This option may not be mixed with any other options.

@item margins=padding

Specifies the elements exterior padding.
`padding' is a list of up to four integers specifying the left, top,
right and bottom padding quantities respectively.
This option may not be mixed with any other options.

@item `width'=largeur

Specifies the width for the element.
If this option is set then the Visual Styles API will not be queried
for the recommended size or the part.
If this option is set then `height' should also be set.
The `width' and `height' options cannot be mixed with the `padding'
or `margins' options.

@item `height'=hauteur

Specifies the height of the element.
See the comments for `width'.
@end table

Exemple :

@example
style = ttk.Style(root)
style.element_create('pin', 'vsapi', 'EXPLORERBAR', 3, [
                     ('pressed', '!selected', 3),
                     ('active', '!selected', 2),
                     ('pressed', 'selected', 6),
                     ('active', 'selected', 5),
                     ('selected', 4),
                     ('@w{'}, 1)])
style.layout('Explorer.Pin',
             [('Explorer.Pin.pin', @{'sticky': 'news'@})])
pin = ttk.Checkbutton(style='Explorer.Pin')
pin.pack(expand=True, fill='both')
@end example


Modifié dans la version 3.13: Added support of the "vsapi" element factory.

@end deffn

@geindex element_names() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style element_names}@anchor{3e6a}
@deffn {Méthode} element_names ()

Renvoie la liste des éléments définis dans le thème courant.
@end deffn

@geindex element_options() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style element_options}@anchor{3e6b}
@deffn {Méthode} element_options (elementname)

Renvoie la liste des options de `elementname'.
@end deffn

@geindex theme_create() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_create}@anchor{3e6c}
@deffn {Méthode} theme_create (themename, parent=None, settings=None)

Crée un nouveau thème.

C'est une erreur si `themename' existe déjà. Si `parent' est spécifié, le nouveau thème hérite des styles, des éléments et des mises en page du thème parent. Si `settings' est présent, il doit avoir la même syntaxe que celle utilisée pour @ref{3e6d,,theme_settings()}.
@end deffn

@geindex theme_settings() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_settings}@anchor{3e6d}
@deffn {Méthode} theme_settings (themename, settings)

Définit temporairement le thème actuel sur `themename', applique les `settings' spécifiés, puis restaure le thème précédent.

Chaque clé dans `settings' est un style et chaque valeur peut contenir les clés @code{'configure'}, @code{'map'}, @code{'layout'} et @code{'element create'} et elles doivent avoir le même format que celui spécifié par les méthodes @ref{3e66,,Style.configure()}, @ref{18ab,,Style.map()}, @ref{3e68,,Style.layout()} et @ref{255,,Style.element_create()} respectivement.

À titre d'exemple, changeons un peu la `Combobox' pour le thème par défaut :

@example
from tkinter import ttk
import tkinter

root = tkinter.Tk()

style = ttk.Style()
style.theme_settings("default", @{
   "TCombobox": @{
       "configure": @{"padding": 5@},
       "map": @{
           "background": [("active", "green2"),
                          ("!disabled", "green4")],
           "fieldbackground": [("!disabled", "green3")],
           "foreground": [("focus", "OliveDrab1"),
                          ("!disabled", "OliveDrab2")]
       @}
   @}
@})

combo = ttk.Combobox().pack()

root.mainloop()
@end example
@end deffn

@geindex theme_names() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_names}@anchor{3e6e}
@deffn {Méthode} theme_names ()

Renvoie une liste de tous les thèmes connus.
@end deffn

@geindex theme_use() (méthode tkinter.ttk.Style)
@anchor{library/tkinter ttk tkinter ttk Style theme_use}@anchor{3e6f}
@deffn {Méthode} theme_use (themename=None)

Si `themename' n'est pas donné, renvoie le thème utilisé. Sinon, définit le thème actuel sur `themename', actualise tous les widgets et lève un événement <<ThemeChanged>>.
@end deffn
@end deffn

@menu
* Dispositions de mise en page:: 

@end menu

@node Dispositions de mise en page,,,Style Ttk
@anchor{library/tkinter ttk layouts}@anchor{3e69}
@subsubsection Dispositions de mise en page


A layout can be just @code{None}, if it takes no options, or a dict of
options specifying how to arrange the element. The layout mechanism
uses a simplified version of the pack geometry manager: given an
initial cavity, each element is allocated a parcel.

Les options/valeurs valides sont :


@table @asis

@item `side': whichside

Spécifie de quel côté de l'espace vide placer l'élément ; `top' (en haut), `right' (à droite), `bottom' (en bas) ou `left' (à gauche). S'il est omis, l'élément occupe toute l'espace.

@item `sticky': nswe

Spécifie où l'élément est placé à l'intérieur de sa partie d'espace alloué.

@item `unit': 0 or 1

Si défini sur 1, l'élément et tous ses descendants sont traités comme un seul élément aux fins de @ref{3e14,,Widget.identify()} et consœurs. Il est utilisé pour des choses comme la barre de défilement ou les agrandissements.

@item `children': [sublayout... ]

Spécifie une liste d'éléments à placer à l'intérieur de l'élément. Chaque élément est un `n'-uplet (ou un autre type de séquence) où le premier élément est le nom de la mise en page et l'autre est un @ref{3e69,,Layout}.
@end table
@anchor{library/tkinter ttk layout}@anchor{3e70}
@node IDLE<64>,,tkinter ttk --- Tk themed widgets,Interfaces Utilisateur Graphiques avec Tk
@anchor{library/idle doc}@anchor{3e71}@anchor{library/idle id1}@anchor{3e72}@anchor{library/idle idle}@anchor{ffe}
@subsection `IDLE'


`Code source' : Lib/idlelib/@footnote{https://github.com/python/cpython/tree/3.13/Lib/idlelib/}

@geindex *IDLE*
@geindex Python Editor
@geindex Integrated Development Environment


__________________________________________________________________


`IDLE' est l'environnement de développement et d'apprentissage intégré de Python (`Integrated Development and Learning Environment').

`IDLE' a les fonctionnalités suivantes :


@itemize *

@item 
multiplateformes : fonctionne de la même manière sous Windows, `Unix' et `macOS'

@item 
Console Python (interpréteur interactif) avec coloration du code entré, des sorties et des messages d'erreur

@item 
éditeur de texte multi-fenêtres avec annulations multiples, coloration Python, indentation automatique, aide pour les appels de fonction, `autocomplétion', parmi d'autres fonctionnalités

@item 
recherche dans n'importe quelle fenêtre, remplacement dans une fenêtre d'édition et recherche dans des fichiers multiples (`grep')

@item 
débogueur avec points d'arrêt persistants, pas-à-pas et visualisation des espaces de nommage locaux et globaux

@item 
configuration, navigateur et d'autres fenêtres de dialogue
@end itemize

@menu
* Menus:: 
* Editing and Navigation:: 
* Startup and Code Execution:: 
* Help and Preferences:: 
* idlelib:: 

@end menu

@node Menus,Editing and Navigation,,IDLE<64>
@anchor{library/idle menus}@anchor{3e73}
@subsubsection Menus


`IDLE' a deux principaux types de fenêtre, la fenêtre de console et la fenêtre d'édition. Il est possible d'avoir de multiples fenêtres d'édition ouvertes simultanément. Sous Windows et Linux, chacune a son propre menu. Chaque menu documenté ci-dessous indique à quel type de fenêtre il est associé.

Les fenêtre d'affichage, comme celles qui sont utilisées pour `Edit => Find in Files', sont un sous-type de fenêtre d'édition. Elles possèdent actuellement le même menu principal mais un titre par défaut et un menu contextuel différents.

Sous `macOS', il y a un menu d'application. Il change dynamiquement en fonction de la fenêtre active. Il a un menu `IDLE' et certaines entrées décrites ci-dessous sont déplacées conformément aux directives d'Apple.

@menu
* Menu File (Console et Éditeur): Menu File Console et Éditeur. 
* Menu Edit (console et éditeur): Menu Edit console et éditeur. 
* Menu Format (fenêtre d'édition uniquement): Menu Format fenêtre d'édition uniquement. 
* Menu Run (fenêtre d'édition uniquement): Menu Run fenêtre d'édition uniquement. 
* Menu Shell (fenêtre de console uniquement): Menu Shell fenêtre de console uniquement. 
* Menu Debug (fenêtre de console uniquement): Menu Debug fenêtre de console uniquement. 
* Menu Options (console et éditeur): Menu Options console et éditeur. 
* Menu Windows (console et éditeur): Menu Windows console et éditeur. 
* Menu Help (console et éditeur): Menu Help console et éditeur. 
* Context menus:: 

@end menu

@node Menu File Console et Éditeur,Menu Edit console et éditeur,,Menus
@anchor{library/idle file-menu-shell-and-editor}@anchor{3e74}
@subsubsection Menu `File' (Console et Éditeur)



@table @asis

@item `New File'

Crée une nouvelle fenêtre d'édition.

@item `Open...'

Ouvre un fichier existant avec une fenêtre de dialogue pour l'ouverture.

@item `Open Module...'

Ouvre un module existant (cherche dans `sys.path').

@item `Recent Files'

Ouvre une liste des fichiers récents. Cliquez sur l'un d'eux pour l'ouvrir.
@end table

@geindex Module browser
@geindex Path browser


@table @asis

@item Module Browser

Montre les fonctions, classes et méthodes dans une arborescence pour le fichier en cours d'édition. Dans la console, ouvre d'abord un module.

@item `Path Browser'

Affiche les dossiers de `sys.path', les modules, fonctions, classes et méthodes dans une arborescence.

@item `Save'

Enregistre la fenêtre active sous le fichier associé, s'il existe. Les fenêtres qui ont été modifiées depuis leur ouverture ou leur dernier enregistrement ont un * avant et après le titre de la fenêtre. S'il n'y a aucun fichier associé, exécute `Save As' à la place.

@item `Save As...'

Save the current window with a Save As dialog.  The file saved becomes the
new associated file for the window. (If your file namager is set to hide
extensions, the current extension will be omitted in the file name box.
If the new filename has no '.', '.py' and '.txt' will be added for Python
and text files, except that on macOS Aqua,'.py' is added for all files.)

@item `Save Copy As...'

Save the current window to different file without changing the associated
file.  (See Save As note above about filename extensions.)

@item `Print Window'

Imprime la fenêtre active avec l'imprimante par défaut.

@item Close Window

Close the current window (if an unsaved editor, ask to save; if an unsaved
Shell, ask to quit execution).  Calling @code{exit()} or @code{close()} in the Shell
window also closes Shell.  If this is the only window, also exit IDLE.

@item Exit IDLE

Close all windows and quit IDLE (ask to save unsaved edit windows).
@end table

@node Menu Edit console et éditeur,Menu Format fenêtre d'édition uniquement,Menu File Console et Éditeur,Menus
@anchor{library/idle edit-menu-shell-and-editor}@anchor{3e75}
@subsubsection Menu `Edit' (console et éditeur)



@table @asis

@item `Undo'

Annule le dernier changement dans la fenêtre active. Un maximum de 1000 changements peut être annulé.

@item `Redo'

Ré-applique le dernier changement annulé dans la fenêtre active.

@item `Select All'

Sélectionne la totalité du contenu de la fenêtre active.

@item `Cut'

Copie la sélection dans le presse-papier global ; puis supprime la sélection.

@item `Copy'

Copie la sélection dans le presse-papier global.

@item `Paste'

Insère le contenu du presse-papier global dans la fenêtre active.
@end table

Les fonctions du presse-papier sont aussi disponibles dans les menus contextuels.


@table @asis

@item `Find...'

Ouvre une fenêtre de recherche avec de nombreuses options

@item `Find Again'

Répète la dernière recherche, s'il y en a une.

@item `Find Selection'

Cherche la chaîne sélectionnée, s'il y en a une.

@item `Find in Files...'

Ouvre une fenêtre de recherche de fichiers. Présente les résultats dans une nouvelle fenêtre d'affichage.

@item `Replace...'

Ouvre une fenêtre de recherche et remplacement.

@item `Go to Line'

Move the cursor to the beginning of the line requested and make that
line visible.  A request past the end of the file goes to the end.
Clear any selection and update the line and column status.

@item `Show Completions'

Open a scrollable list allowing selection of existing names. See
@ref{3e76,,Completions} in the Editing and navigation section below.

@item `Expand Word'

Complète un préfixe que vous avez saisi pour correspondre à un mot complet de la même fenêtre ; recommencez pour obtenir un autre complément.

@item Show Call Tip

Après une parenthèse ouverte pour une fonction, ouvre une petite fenêtre avec des indications sur les paramètres de la fonction. Reportez-vous à @ref{3e77,,Aides aux appels} dans la section Édition et navigation ci-dessous.

@item Show Surrounding Parens

Surligne les parenthèses encadrantes.
@end table

@node Menu Format fenêtre d'édition uniquement,Menu Run fenêtre d'édition uniquement,Menu Edit console et éditeur,Menus
@anchor{library/idle format-menu}@anchor{3e78}@anchor{library/idle format-menu-editor-window-only}@anchor{3e79}
@subsubsection Menu `Format' (fenêtre d'édition uniquement)



@table @asis

@item `Format Paragraph'

Reformate le paragraphe actif, délimité par des lignes vides, en un bloc de commentaires, ou la chaîne de caractères multi-lignes ou ligne sélectionnée en chaîne de caractères. Toutes les lignes du paragraphe seront formatées à moins de N colonnes, avec N valant 72 par défaut.

@item `Indent Region'

Décale les lignes sélectionnées vers la droite d'un niveau d'indentation (4 espaces par défaut).

@item `Dedent Region'

Décale les lignes sélectionnées vers la gauche d'un niveau d'indentation (4 espaces par défaut).

@item `Comment Out Region'

Insère ## devant les lignes sélectionnées.

@item `Uncomment Region'

Enlève les # ou ## au début des lignes sélectionnées.

@item `Tabify Region'

Transforme les blocs d'espaces `au début des lignes'  en tabulations. (Note : Nous recommandons d'utiliser des blocs de 4 espaces pour indenter du code Python.)

@item `Untabify Region'

Transforme `toutes' les tabulations en le bon nombre d'espaces.

@item `Toggle Tabs'

Ouvre une boîte de dialogue permettant de passer des espaces aux tabulations (et inversement) pour l'indentation.

@item `New Indent Width'

Ouvre une boîte de dialogue pour changer la taille de l'indentation. La valeur par défaut acceptée par la communauté Python est de 4 espaces.

@item Strip Trailing Chitespace

Enlève les espaces après le dernier caractère non blanc d'une ligne en appliquant `str.rstrip' à chaque ligne, y compris les lignes avec des chaînes de caractères multi-lignes. À l'exception des fenêtres de terminal, supprime les lignes supplémentaires à la fin du fichier.
@end table

@geindex Run script

@node Menu Run fenêtre d'édition uniquement,Menu Shell fenêtre de console uniquement,Menu Format fenêtre d'édition uniquement,Menus
@anchor{library/idle run-menu-editor-window-only}@anchor{3e7a}
@subsubsection Menu `Run' (fenêtre d'édition uniquement)

@anchor{library/idle run-module}@anchor{3e7b}

@table @asis

@item `Run Module'

Applique @ref{3e7c,,Check Module} (ci-dessus). S'il n'y a pas d'erreur, redémarre la console pour nettoyer l'environnement, puis exécute le module. Les sorties sont affichées dans la fenêtre de console. Notez qu'une sortie requiert l'utilisation de @code{print} ou @code{write}. Quand l'exécution est terminée, la console reste active et affiche une invite de commande. À ce moment, vous pouvez explorer interactivement le résultat de l'exécution. Ceci est similaire à l'exécution d'un fichier avec @code{python -i fichier} sur un terminal.
@end table
@anchor{library/idle run-custom}@anchor{3e7d}

@table @asis

@item Run... Customized

Similaire à @ref{3e7b,,Run Module}, mais lance le module  avec des paramètres personnalisés. Les `Command Line Arguments' se rajoutent à @ref{1243,,sys.argv} comme s'ils étaient passés par la ligne de commande. Le module peut être lancé dans le terminal sans avoir à le redémarrer.
@end table
@anchor{library/idle check-module}@anchor{3e7c}

@table @asis

@item `Check Module'

Vérifie la syntaxe du module actuellement ouvert dans la fenêtre d'édition. Si le module n'a pas été enregistré, `IDLE' va soit demander à enregistrer à l'utilisateur, soit enregistrer automatiquement, selon l'option sélectionnée dans l'onglet `General' de la fenêtre de configuration d'`IDLE'. S'il y a une erreur de syntaxe, l'emplacement approximatif est indiqué dans la fenêtre d'édition.
@end table
@anchor{library/idle python-shell}@anchor{3e7e}

@table @asis

@item Console Python

Ouvre ou active la fenêtre de console Python.
@end table

@node Menu Shell fenêtre de console uniquement,Menu Debug fenêtre de console uniquement,Menu Run fenêtre d'édition uniquement,Menus
@anchor{library/idle shell-menu-shell-window-only}@anchor{3e7f}
@subsubsection Menu Shell (fenêtre de console uniquement)



@table @asis

@item `View Last Restart'

Fait défiler la fenêtre de console jusqu'au dernier redémarrage de la console.

@item `Restart Shell'

Restart the shell to clean the environment and reset display and exception handling.

@item `Previous History'

Parcours les commandes précédentes dans l'historique qui correspondent à l'entrée actuelle.

@item `Next History'

Parcours les commandes suivantes dans l'historique qui correspondent à l'entrée actuelle.

@item `Interrupt Execution'

Arrête un programme en cours d'exécution.
@end table

@node Menu Debug fenêtre de console uniquement,Menu Options console et éditeur,Menu Shell fenêtre de console uniquement,Menus
@anchor{library/idle debug-menu-shell-window-only}@anchor{3e80}
@subsubsection Menu `Debug' (fenêtre de console uniquement)



@table @asis

@item `Go to File/Line'

Cherche, sur la ligne active et la ligne en-dessous, un nom de fichier et un numéro de ligne. Le cas échéant, ouvre le fichier s'il n'est pas encore ouvert et montre la ligne. Utilisez ceci pour visualiser les lignes de code source référencées dans un `traceback' d'exception et les lignes trouvées par `Find in Files'. Également disponible dans le menu contextuel des fenêtres de console et d'affichage.
@end table

@geindex debugger
@geindex stack viewer


@table @asis

@item `Debugger' ([dés]activer)

Quand cette fonctionnalité est activée, le code saisi dans la console ou exécuté depuis un Éditeur s'exécutera avec le débogueur. Dans l'Éditeur, des points d'arrêt peuvent être placés avec le menu contextuel. Cette fonctionnalité est encore incomplète et plus ou moins expérimentale.

@item `Stack Viewer'

Montre l'état de la pile au moment de la dernière erreur dans une arborescence, avec accès aux variables locales et globales.

@item `Auto-open Stack Viewer'

Active ou désactive l'ouverture automatique de l'afficheur de pile après une erreur non gérée.
@end table

@node Menu Options console et éditeur,Menu Windows console et éditeur,Menu Debug fenêtre de console uniquement,Menus
@anchor{library/idle options-menu-shell-and-editor}@anchor{3e81}
@subsubsection Menu `Options' (console et éditeur)



@table @asis

@item `Configure IDLE'

Ouvre une fenêtre de configuration et change les préférences pour les éléments suivants : police, indentation, raccourcis clavier, thème de coloration du texte, taille et nature de la fenêtre au lancement, sources d'aide additionnelles et extensions. Sous `macOS', ouvrez la fenêtre de configuration en sélectionnant `Preferences' dans le menu de l'application. Pour plus de détails, référez-vous à @ref{3e82,,Modifier les préférences} dans Aide et paramètres.
@end table

La plupart des paramètres de configuration s'appliquent à toutes les fenêtres, ouvertes ou non. Les éléments d'option ci-dessous s'appliquent uniquement à la fenêtre active.


@table @asis

@item `Show/Hide Code Context' (fenêtres d'édition uniquement)

Fais passer la fenêtre de taille normale à maximale. La taille de départ par défaut est de 40 lignes par 80 caractères, sauf changement dans l'onglet `General' de la fenêtre de configuration d'`IDLE'. Consultez @ref{3e83,,Code Context} dans la section « Édition et navigation » ci-dessous.

@item `Show/Hide Line Numbers' (fenêtre de l'éditeur uniquement)

Ajoute une colonne à gauche de la fenêtre d'édition qui indique le numéro de chaque ligne de texte. Cette colonne est désactivée par défaut, ce qui peut être modifié dans les préférences (voir @ref{3e82,,Modifier les préférences}).

@item `Zoom/Restore Height'

Bascule la fenêtre entre la taille normale et la hauteur maximale. La taille initiale par défaut est de 40 lignes par 80 caractères, sauf si elle est modifiée dans l'onglet « `General' » de la boîte de dialogue « Configure IDLE ». La hauteur maximale d'un écran est déterminée en maximisant momentanément une fenêtre lors du premier zoom sur l'écran. La modification des paramètres d'écran peut invalider la hauteur enregistrée. Cette bascule n'a aucun effet lorsqu'une fenêtre est agrandie.
@end table

@node Menu Windows console et éditeur,Menu Help console et éditeur,Menu Options console et éditeur,Menus
@anchor{library/idle window-menu-shell-and-editor}@anchor{3e84}
@subsubsection Menu `Windows' (console et éditeur)


Liste les noms de toutes les fenêtres ouvertes ; sélectionnez-en une pour l'amener au premier plan (en l'ouvrant si nécessaire).

@node Menu Help console et éditeur,Context menus,Menu Windows console et éditeur,Menus
@anchor{library/idle help-menu-shell-and-editor}@anchor{3e85}
@subsubsection Menu `Help' (console et éditeur)



@table @asis

@item About `IDLE'

Affiche la version, les copyrights, la licence, les crédits, entre autres.

@item `IDLE Help'

Affiche ce document `IDLE', qui détaille les options des menus, les bases de l'édition et de la navigation ainsi que d'autres astuces.

@item `Python Docs'

Accède à la documentation Python locale, si installée, ou ouvre docs.python.org dans un navigateur pour afficher la documentation Python la plus récente.

@item `Turtle Demo'

Exécute le module `turtledemo' avec des exemples de code Python et de dessins `turtle'.
@end table

Des sources d'aide supplémentaires peuvent être ajoutées ici avec la fenêtre de configuration d'`IDLE' dans l'onglet `General'. Référez-vous à la sous-section @ref{3e86,,Sources d'aide} ci-dessous pour plus de détails sur les choix du menu d'aide.

@geindex *Cut*
@geindex *Copy*
@geindex *Paste*
@geindex *Set Breakpoint*
@geindex *Clear Breakpoint*
@geindex breakpoints

@node Context menus,,Menu Help console et éditeur,Menus
@anchor{library/idle context-menus}@anchor{3e87}
@subsubsection Context menus


Vous pouvez ouvrir un menu contextuel par un clic droit dans une fenêtre (Contrôle-clic sous `macOS'). Les menus contextuels ont les fonctions de presse-papier standard, également disponibles dans le menu `Edit'.


@table @asis

@item `Cut'

Copie la sélection dans le presse-papier global ; puis supprime la sélection.

@item `Copy'

Copie la sélection dans le presse-papier global.

@item `Paste'

Insère le contenu du presse-papier global dans la fenêtre active.
@end table

Les fenêtres d'édition ont aussi des fonctions de points d'arrêt. Les lignes sur lesquelles est défini un point d'arrêt sont marquées de manière spéciale. Les points d'arrêt n'ont d'effet que lorsque l'exécution se déroule sous débogueur. Les points d'arrêt pour un fichier sont enregistrés dans le dossier @code{.idlerc} de l'utilisateur.


@table @asis

@item `Set Breakpoint'

Place un point d'arrêt sur la ligne active.

@item `Clear Breakpoint'

Enlève le point d'arrêt sur cette ligne.
@end table

Les fenêtres de console et d'affichage disposent en plus des éléments suivants.


@table @asis

@item `Go to file/line'

Même effet que dans le menu `Debug'.
@end table

Les fenêtres de console ont également une fonction de réduction des sorties détaillée dans la sous-section `fenêtre de console de Python' ci-dessous.


@table @asis

@item `Squeeze'

Si le curseur est sur une ligne d'affichage, compacte toute la sortie entre le code au-dessus et l'invite en-dessous en un bouton `"Squeezed text"'.
@end table

@node Editing and Navigation,Startup and Code Execution,Menus,IDLE<64>
@anchor{library/idle editing-and-navigation}@anchor{3e88}@anchor{library/idle id2}@anchor{3e89}
@subsubsection Editing and Navigation


@menu
* Fenêtre d'édition:: 
* Raccourcis clavier:: 
* Indentation automatique:: 
* Recherche et substitution:: 
* Complétions:: 
* Info-bulles:: 
* Contexte du code:: 
* Shell window:: 
* Coloration du texte:: 

@end menu

@node Fenêtre d'édition,Raccourcis clavier,,Editing and Navigation
@anchor{library/idle editor-windows}@anchor{3e8a}
@subsubsection Fenêtre d'édition


`IDLE' peut ouvrir une fenêtre d'édition quand il démarre, selon les paramètres et la manière dont vous démarrez `IDLE'. Ensuite, utilisez le menu `File'. Il ne peut y avoir qu'une fenêtre d'édition pour un fichier donné.

La barre de titre contient le nom du fichier, le chemin absolu et la version de Python et d'`IDLE' s'exécutant dans la fenêtre. La barre de statut contient le numéro de ligne ("`Ln"') et le numéro de la colonne ("`Col"'). Les numéros de ligne commencent à 1 ; les numéros de colonne commencent à 0.

`IDLE' suppose que les fichiers avec une extension en `.py*' reconnue contiennent du code Python, mais pas les autres fichiers. Exécutez du code Python avec le menu `Run'.

@node Raccourcis clavier,Indentation automatique,Fenêtre d'édition,Editing and Navigation
@anchor{library/idle key-bindings}@anchor{3e8b}
@subsubsection Raccourcis clavier


The IDLE insertion cursor is a thin vertical bar between character
positions.  When characters are entered, the insertion cursor and
everything to its right moves right one character and
the new character is entered in the new space.

Several non-character keys move the cursor and possibly
delete characters.  Deletion does not puts text on the clipboard,
but IDLE has an undo list.  Wherever this doc discusses keys,
'C' refers to the @code{Control} key on Windows and
Unix and the @code{Command} key on macOS.  (And all such discussions
assume that the keys have not been re-bound to something else.)


@itemize *

@item 
Arrow keys move the cursor one character or line.

@item 
@code{C-LeftArrow} and @code{C-RightArrow} moves left or right one word.

@item 
@code{Home} and @code{End} go to the beginning or end of the line.

@item 
@code{Page Up} and @code{Page Down} go up or down one screen.

@item 
@code{C-Home} and @code{C-End} go to beginning or end of the file.

@item 
@code{Backspace} and @code{Del} (or @code{C-d}) delete the previous
or next character.

@item 
@code{C-Backspace} and @code{C-Del} delete one word left or right.

@item 
@code{C-k} deletes ('kills') everything to the right.
@end itemize

Les raccourcis clavier standards (comme @code{C-c} pour copier et @code{C-v} pour coller) peuvent fonctionner. Les raccourcis clavier sont sélectionnés dans la fenêtre de configuration d'`IDLE'.

@node Indentation automatique,Recherche et substitution,Raccourcis clavier,Editing and Navigation
@anchor{library/idle automatic-indentation}@anchor{3e8c}
@subsubsection Indentation automatique


Après une structure d'ouverture de bloc, la prochaine ligne est indentée de 4 espaces (dans la console Python d'une tabulation). Après certains mots-clefs (`break', `return' etc) la ligne suivante est `dédentée'. Dans une indentation au début de la ligne, @code{Retour arrière} supprime jusqu'à 4 espaces s'il y en a. @code{Tab} insère des espaces (dans la console, une tabulation), en nombre dépendant de la configuration. Les tabulations sont actuellement restreintes à quatre espaces à cause de limitations de `Tcl/Tk'.

Cf. les commandes `indent/dedent region' dans le @ref{3e78,,menu *Format*}.

@node Recherche et substitution,Complétions,Indentation automatique,Editing and Navigation
@anchor{library/idle search-and-replace}@anchor{3e8d}
@subsubsection Recherche et substitution


Any selection becomes a search target.  However, only selections within
a line work because searches are only performed within lines with the
terminal newline removed.  If @code{[x] Regular expression} is checked, the
target is interpreted according to the Python re module.

@node Complétions,Info-bulles,Recherche et substitution,Editing and Navigation
@anchor{library/idle completions}@anchor{3e76}@anchor{library/idle id3}@anchor{3e8e}
@subsubsection Complétions


Completions are supplied, when requested and available, for module
names, attributes of classes or functions, or filenames.  Each request
method displays a completion box with existing names.  (See tab
completions below for an exception.) For any box, change the name
being completed and the item highlighted in the box by
typing and deleting characters; by hitting @code{Up}, @code{Down},
@code{PageUp}, @code{PageDown}, @code{Home}, and @code{End} keys;
and by a single click within the box.  Close the box with @code{Escape},
@code{Enter}, and double @code{Tab} keys or clicks outside the box.
A double click within the box selects and closes.

One way to open a box is to type a key character and wait for a
predefined interval.  This defaults to 2 seconds; customize it
in the settings dialog.  (To prevent auto popups, set the delay to a
large number of milliseconds, such as 100000000.) For imported module
names or class or function attributes, type '.'.
For filenames in the root directory, type @ref{655,,os.sep} or
@ref{656,,os.altsep} immediately after an opening quote.  (On Windows,
one can specify a drive first.)  Move into subdirectories by typing a
directory name and a separator.

Instead of waiting, or after a box is closed, open a completion box
immediately with Show Completions on the Edit menu.  The default hot
key is @code{C-space}.  If one types a prefix for the desired name
before opening the box, the first match or near miss is made visible.
The result is the same as if one enters a prefix
after the box is displayed.  Show Completions after a quote completes
filenames in the current directory instead of a root directory.

Hitting @code{Tab} after a prefix usually has the same effect as Show
Completions.  (With no prefix, it indents.)  However, if there is only
one match to the prefix, that match is immediately added to the editor
text without opening a box.

Invoking 'Show Completions', or hitting @code{Tab} after a prefix,
outside of a string and without a preceding '.' opens a box with
keywords, builtin names, and available module-level names.

When editing code in an editor (as oppose to Shell), increase the
available module-level names by running your code
and not restarting the Shell thereafter.  This is especially useful
after adding imports at the top of a file.  This also increases
possible attribute completions.

Completion boxes initially exclude names beginning with '_' or, for
modules, not included in '__all__'.  The hidden names can be accessed
by typing '_' after '.', either before or after the box is opened.

@node Info-bulles,Contexte du code,Complétions,Editing and Navigation
@anchor{library/idle calltips}@anchor{3e77}@anchor{library/idle id4}@anchor{3e8f}
@subsubsection Info-bulles


A calltip is shown automatically when one types @code{(} after the name
of an `accessible' function.  A function name expression may include
dots and subscripts.  A calltip remains until it is clicked, the cursor
is moved out of the argument area, or @code{)} is typed.  Whenever the
cursor is in the argument part of a definition, select Edit and "Show
Call Tip" on the menu or enter its shortcut to display a calltip.

The calltip consists of the function's signature and docstring up to
the latter's first blank line or the fifth non-blank line.  (Some builtin
functions lack an accessible signature.)  A '/' or '*' in the signature
indicates that the preceding or following arguments are passed by
position or name (keyword) only.  Details are subject to change.

In Shell, the accessible functions depends on what modules have been
imported into the user process, including those imported by Idle itself,
and which definitions have been run, all since the last restart.

For example, restart the Shell and enter @code{itertools.count(}.  A calltip
appears because Idle imports itertools into the user process for its own
use.  (This could change.)  Enter @code{turtle.write(} and nothing appears.
Idle does not itself import turtle.  The menu entry and shortcut also do
nothing.  Enter @code{import turtle}.  Thereafter, @code{turtle.write(}
will display a calltip.

In an editor, import statements have no effect until one runs the file.
One might want to run a file after writing import statements, after
adding function definitions, or after opening an existing file.

@node Contexte du code,Shell window,Info-bulles,Editing and Navigation
@anchor{library/idle code-context}@anchor{3e83}@anchor{library/idle id5}@anchor{3e90}
@subsubsection Contexte du code


Dans une fenêtre d'édition contenant du code Python, le contexte du code peut être activé pour afficher ou cacher une zone en haut de la fenêtre. Quand elle est affichée, cette zone gèle les lignes ouvrant le bloc de code, comme celles qui commencent par les mots-clés @code{class}, @code{def} ou @code{if}, qui auraient autrement été cachées plus haut dans le fichier. La taille de cette zone varie automatiquement selon ce qui est nécessaire pour afficher tous les niveaux de contexte, jusqu'à un nombre maximal de lignes défini dans la fenêtre de configuration d'`IDLE' (valeur qui vaut 15 par défaut). S'il n'y a pas de lignes de contexte et que cette fonctionnalité est activée, une unique ligne vide est affichée. Un clic sur une ligne dans la zone de contexte  déplace cette ligne en haut de l'éditeur.

Les couleurs de texte et du fond pour la zone de contexte peuvent être configurées dans l'onglet `Highlights' de la fenêtre de configuration d'`IDLE'.

@node Shell window,Coloration du texte,Contexte du code,Editing and Navigation
@anchor{library/idle shell-window}@anchor{3e91}
@subsubsection Shell window


In IDLE's Shell, enter, edit, and recall complete statements. (Most
consoles and terminals only work with a single physical line at a time).

Submit a single-line statement for execution by hitting @code{Return}
with the cursor anywhere on the line.  If a line is extended with
Backslash (@code{\}), the cursor must be on the last physical line.
Submit a multi-line compound statement by entering a blank line after
the statement.

When one pastes code into Shell, it is not compiled and possibly executed
until one hits @code{Return}, as specified above.
One may edit pasted code first.
If one pastes more than one statement into Shell, the result will be a
@ref{18b,,SyntaxError} when multiple statements are compiled as if they were one.

Lines containing @code{RESTART} mean that the user execution process has been
re-started.  This occurs when the user execution process has crashed,
when one requests a restart on the Shell menu, or when one runs code
in an editor window.

The editing features described in previous subsections work when entering
code interactively.  IDLE's Shell window also responds to the following:


@itemize *

@item 
@code{C-c} attempts to interrupt statement execution (but may fail).

@item 
@code{C-d} closes Shell if typed at a @code{>>>} prompt.

@item 
@code{Alt-p} and @code{Alt-n} (@code{C-p} and @code{C-n} on macOS)
retrieve to the current prompt the previous or next previously
entered statement that matches anything already typed.

@item 
@code{Return} while the cursor is on any previous statement
appends the latter to anything already typed at the prompt.
@end itemize

@node Coloration du texte,,Shell window,Editing and Navigation
@anchor{library/idle text-colors}@anchor{3e92}
@subsubsection Coloration du texte


`IDLE' affiche par défaut le texte en noir sur blanc mais colore le texte qui possède une signification spéciale. Pour la console, ceci concerne les sorties de la console et de l'utilisateur ainsi que les erreurs de l'utilisateur. Pour le code Python, dans l'invite de commande de la console ou sur un éditeur, ce sont les mots-clefs, noms de fonctions et de classes incluses par défaut, les noms suivant @code{class} et @code{def}, les chaînes de caractères et les commentaires. Pour n'importe quelle fenêtre de texte, ce sont le curseur (si présent), le texte trouvé (s'il y en a) et le texte sélectionné.

IDLE also highlights the @ref{7f6,,soft keywords} @ref{7f7,,match},
@ref{7f7,,case}, and @ref{7f8,,_} in
pattern-matching statements. However, this highlighting is not perfect and
will be incorrect in some rare cases, including some @code{_}-s in @code{case}
patterns.

La coloration du texte est faite en arrière-plan, donc du texte non coloré est parfois visible. Pour changer les couleurs, utilisez l'onglet `Highlighting' de la fenêtre de configuration d'`IDLE'. Le marquage des points d'arrêt du débogueur dans l'éditeur et du texte dans les dialogues n'est pas configurable.

@node Startup and Code Execution,Help and Preferences,Editing and Navigation,IDLE<64>
@anchor{library/idle startup-and-code-execution}@anchor{3e93}
@subsubsection Startup and Code Execution


Quand il est démarré avec l'option @code{-s}, `IDLE' exécutera le fichier référencé par la variable d'environnement 
@geindex IDLE*STARTUP
@geindex variable d'environnement; IDLE*STARTUP
@code{IDLE*STARTUP} ou 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP}. `IDLE' cherche d'abord @code{IDLESTARTUP} ; si @code{IDLESTARTUP} est présent, le fichier référencé est exécuté. Si @code{IDLESTARTUP} n'est pas présent, alors `IDLE' cherche @code{PYTHONSTARTUP}. Les fichiers référencés par ces variables d'environnement sont de bons endroits pour stocker des fonctions qui sont utilisées fréquemment depuis la console d'`IDLE' ou pour exécuter des commandes d'importation des modules communs.

De plus, @code{Tk} charge lui aussi un fichier de démarrage s'il est présent. Notez que le fichier de `Tk' est chargé sans condition. Ce fichier additionnel est @code{.Idle.py} et est recherché dans le dossier personnel de l'utilisateur. Les commandes dans ce fichier sont exécutées dans l'espace de nommage de `Tk', donc ce fichier n'est pas utile pour importer des fonctions à utiliser depuis la console Python d'`IDLE'.

@menu
* Utilisation de la ligne de commande:: 
* Échec au démarrage:: 
* Exécuter le code de l'utilisateur:: 
* Sortie de l'utilisateur sur la console:: 
* Développer des applications tkinter:: 
* Exécution sans sous-processus:: 

@end menu

@node Utilisation de la ligne de commande,Échec au démarrage,,Startup and Code Execution
@anchor{library/idle command-line-usage}@anchor{3e94}
@subsubsection Utilisation de la ligne de commande


@example
idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...

-c command  run command in the shell window
-d          enable debugger and open shell window
-e          open editor window
-h          print help message with legal combinations and exit
-i          open shell window
-r file     run file in shell window
-s          run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
-t title    set title of shell window
-           run stdin in shell (- must be last option before args)
@end example

S'il y a des arguments :


@itemize *

@item 
Si @code{-}, @code{-c} ou @code{-r} sont utilisés, tous les arguments sont placés dans @code{sys.argv[1:...]} et @code{sys.argv[0]} est assigné à @code{'@w{'}}, @code{'-c'}, ou @code{'-r'}.  Aucune fenêtre d'édition n'est ouverte, même si c'est le comportement par défaut fixé dans la fenêtre d'options.

@item 
Sinon, les arguments sont des fichiers ouverts pour édition et @code{sys.argv} reflète les arguments passés à `IDLE' lui-même.
@end itemize

@node Échec au démarrage,Exécuter le code de l'utilisateur,Utilisation de la ligne de commande,Startup and Code Execution
@anchor{library/idle startup-failure}@anchor{3e95}
@subsubsection Échec au démarrage


IDLE uses a socket to communicate between the IDLE GUI process and the user
code execution process.  A connection must be established whenever the Shell
starts or restarts.  (The latter is indicated by a divider line that says
'RESTART'). If the user process fails to connect to the GUI process, it
usually displays a @code{Tk} error box with a 'cannot connect' message
that directs the user here.  It then exits.

One specific connection failure on Unix systems results from
misconfigured masquerading rules somewhere in a system's network setup.
When IDLE is started from a terminal, one will see a message starting
with @code{** Invalid host:}.
The valid value is @code{127.0.0.1 (idlelib.rpc.LOCALHOST)}.
One can diagnose with @code{tcpconnect -irv 127.0.0.1 6543} in one
terminal window and @code{tcplisten <same args>} in another.

Une cause d'échec courant est un fichier écrit par l'utilisateur avec le même nom qu'un module de la bibliothèque standard, comme `random.py' et `tkinter.py'. Quand un fichier de ce genre est enregistré dans le même répertoire qu'un fichier à exécuter, `IDLE' ne peut pas importer le fichier standard. La solution actuelle consiste à renommer le fichier de l'utilisateur.

Même si c'est plus rare qu'avant, un antivirus ou un pare-feu peuvent interrompre la connexion. Si le programme ne peut pas être paramétré pour autoriser la connexion, alors il doit être éteint pour qu'`IDLE' puisse fonctionner. Cette connexion interne est sûre car aucune donnée n'est visible depuis un port extérieur. Un problème similaire est une mauvaise configuration du réseau qui bloque les connexions.

Des problèmes d'installation de Python stoppent parfois `IDLE' : il peut y avoir un conflit de versions ou bien l'installation peut nécessiter des privilèges administrateurs. Si on corrige le conflit , ou qu'on ne peut ou ne veut pas accorder de privilège, il peut être plus facile de désinstaller complètement Python et de recommencer.

A zombie pythonw.exe process could be a problem.  On Windows, use Task
Manager to check for one and stop it if there is.  Sometimes a restart
initiated by a program crash or Keyboard Interrupt (control-C) may fail
to connect.  Dismissing the error box or using Restart Shell on the Shell
menu may fix a temporary problem.

When IDLE first starts, it attempts to read user configuration files in
@code{~/.idlerc/} (~ is one's home directory).  If there is a problem, an error
message should be displayed.  Leaving aside random disk glitches, this can
be prevented by never editing the files by hand.  Instead, use the
configuration dialog, under Options.  Once there is an error in a user
configuration file, the best solution may be to delete it and start over
with the settings dialog.

If IDLE quits with no message, and it was not started from a console, try
starting it from a console or terminal (@code{python -m idlelib}) and see if
this results in an error message.

On Unix-based systems with tcl/tk older than @code{8.6.11} (see
@code{About IDLE}) certain characters of certain fonts can cause
a tk failure with a message to the terminal.  This can happen either
if one starts IDLE to edit a file with such a character or later
when entering such a character.  If one cannot upgrade tcl/tk,
then re-configure IDLE to use a font that works better.

@node Exécuter le code de l'utilisateur,Sortie de l'utilisateur sur la console,Échec au démarrage,Startup and Code Execution
@anchor{library/idle running-user-code}@anchor{3e96}
@subsubsection Exécuter le code de l'utilisateur


With rare exceptions, the result of executing Python code with IDLE is
intended to be the same as executing the same code by the default method,
directly with Python in a text-mode system console or terminal window.
However, the different interface and operation occasionally affect
visible results.  For instance, @code{sys.modules} starts with more entries,
and @code{threading.active_count()} returns 2 instead of 1.

Par défaut, `IDLE' exécute le code de l'utilisateur dans un processus système séparé plutôt que dans le processus d'interface utilisateur qui exécute la console et l'éditeur. Dans le processus d'exécution, il remplace @code{sys.stdin}, @code{sys.stdout} et @code{sys.stderr} par des objets qui récupèrent les entrées et envoient les sorties à la fenêtre de console. Les valeurs originales stockées dans @code{sys.__stdin__}, @code{sys.__stdout__} et @code{sys.__stderr__} ne sont pas touchées, mais peuvent être @code{None}.

Sending print output from one process to a text widget in another is
slower than printing to a system terminal in the same process.
This has the most effect when printing multiple arguments, as the string
for each argument, each separator, the newline are sent separately.
For development, this is usually not a problem, but if one wants to
print faster in IDLE, format and join together everything one wants
displayed together and then print a single string.  Both format strings
and @ref{2134,,str.join()} can help combine fields and lines.

IDLE's standard stream replacements are not inherited by subprocesses
created in the execution process, whether directly by user code or by
modules such as multiprocessing.  If such subprocess use @code{input} from
sys.stdin or @code{print} or @code{write} to sys.stdout or sys.stderr,
IDLE should be started in a command line window.  (On Windows,
use @code{python} or @code{py} rather than @code{pythonw} or @code{pyw}.)
The secondary subprocess
will then be attached to that window for input and output.

Si @code{sys} est réinitialisé par le code de l'utilisateur, comme avec @code{importlib.reload(sys)}, les changements d'`IDLE' seront perdus et l'entrée du clavier et la sortie à l'écran ne fonctionneront pas correctement.

Quand la console est au premier plan, elle contrôle le clavier et l'écran. Ceci est normalement transparent, mais les fonctions qui accèdent directement au clavier et à l'écran ne fonctionneront pas. Ceci inclut des fonctions spécifiques du système qui déterminent si une touche a été pressée et, le cas échéant, laquelle.

Le code IDLE tournant dans le processus d'exécution ajoute des appels de fonctions à la pile d'appels qui ne seraient pas là autrement. IDLE encapsule @code{sys.getrecursionlimit}  et @code{sys.setrecursionlimit}  pour réduire l'effet des piles de fonctions supplémentaires.

Lorsque l'utilisateur lève @code{SystemExit} directement ou en appelant @code{sys.exit}, IDLE revient au terminal IDLE au lieu de quitter.

@node Sortie de l'utilisateur sur la console,Développer des applications tkinter,Exécuter le code de l'utilisateur,Startup and Code Execution
@anchor{library/idle user-output-in-shell}@anchor{3e97}
@subsubsection Sortie de l'utilisateur sur la console


Quand un programme affiche du texte, le résultat est déterminé par le support d'affichage correspondant. Quand `IDLE' exécute du code de l'utilisateur, @code{sys.stdout} et @code{sys.stderr} sont connectées à la zone d'affichage de la console d'`IDLE'. Certaines de ces fonctionnalités sont héritées des widgets `Tk' sous-jacents. D'autres sont des additions programmées. Quand cela importe, la console est conçue pour le développement plutôt que l'exécution en production.

Par exemple, la console ne supprime jamais de sortie. Un programme qui écrit à l'infini dans la console finira par remplir la mémoire, ce qui entraînera un erreur mémoire. Par ailleurs, certains systèmes de fenêtres textuelles ne conservent que les n dernières lignes de sortie. Une console Windows, par exemple, conserve une quantité de lignes configurable entre 1 et 9999, avec une valeur par défaut de 300.

Un widget `Text' de `Tk' et donc la console d'`IDLE', affiche des caractères (points de code) dans le sous-ensemble `BMP' (`Basic Multilingual Plane') d'Unicode. Quels caractères sont affichés avec le bon glyphe et lesquels sont affichés avec un caractère de remplacement dépend du système d'exploitation et des polices installées. Les caractères de tabulation font que le texte suivant commencera après le prochain taquet de tabulation (ils sont placés tous les 8 `"caractères"'). Les caractères saut de ligne font apparaître le texte suivant sur une nouvelle ligne. Les autres caractères de contrôle sont ignorés ou affichés sous forme d'espace, de boîte, ou d'autre chose, selon le système d'exploitation et la police (déplacer le curseur de texte sur un affichage de ce genre peut provoquer un comportement surprenant du point de vue de l'espacement).

@example
>>> s = 'a\tb\a<\x02><\r>\bc\nd'  # Enter 22 chars.
>>> len(s)
14
>>> s  # Display repr(s)
'a\tb\x07<\x02><\r>\x08c\nd'
>>> print(s, end='@w{'})  # Display s as is.
# Result varies by OS and font.  Try it.
@end example

La fonction @code{repr} est utilisée pour l'affichage interactif de la valeur des expressions. Elle renvoie une version modifiée de la chaîne en entrée dans laquelle les codes de contrôle, certains points de code `BMP' et tous les points de code non `BMP' sont remplacés par des caractères d'échappement. Comme montré ci-dessus, ceci permet d'identifier les caractères dans une chaîne, quelle que soit la façon dont elle est affichée.

Les sorties standard et d'erreur sont généralement séparées (sur des lignes séparées) de l'entrée de code et entre elles. Elles ont chacune une coloration différente.

Pour les `traceback' de `SyntaxError', le `"^"' habituel marquant l'endroit où l'erreur a été détectée est remplacé par la coloration et le surlignage du texte avec une erreur. Quand du code exécuté depuis un fichier cause d'autres exceptions, un clic droit sur la ligne du `traceback' permet d'accéder à la ligne correspondante dans un éditeur `IDLE'. Le fichier est ouvert si nécessaire.

La console a une fonctionnalité spéciale pour réduire les lignes de sorties à une étiquette `"Squeezed text"'. Ceci est fait automatiquement pour un sortie de plus de N lignes (N = 50 par défaut). N peut être changé dans la section `PyShell' de la page `General' de la fenêtre de configuration. Les sorties avec moins de lignes peuvent être réduites par un clic droit sur la sortie. Ceci peut être utile sur des lignes si longues qu'elles ralentissent la navigation.

Les sorties réduites sont étendues sur place en double-cliquant sur l'étiquette Elles peuvent aussi être envoyées au presse-papier ou sur un fenêtre séparée par un clic-droit sur l'étiquette.

@node Développer des applications tkinter,Exécution sans sous-processus,Sortie de l'utilisateur sur la console,Startup and Code Execution
@anchor{library/idle developing-tkinter-applications}@anchor{3e98}
@subsubsection Développer des applications `tkinter'


`IDLE' est intentionnellement différent de Python standard dans le but de faciliter le développement des programmes `tkinter'. Saisissez @code{import *tkinter* as tk; root = tk.Tk()} avec Python standard, rien n'apparaît. Saisissez la même chose dans `IDLE' et une fenêtre `tk' apparaît. En Python standard, il faut également saisir @code{root.update()} pour voir la fenêtre. `IDLE' fait un équivalent mais en arrière-plan, environ 20 fois par seconde, soit environ toutes les 50 millisecondes. Ensuite, saisissez @code{b = tk.Button(root, text='button'); b.pack()}. De la même manière, aucun changement n'est visible en Python standard jusqu'à la saisie de @code{root.update()}.

La plupart des programmes `tkinter' exécutent @code{root.mainloop()}, qui d'habitude ne renvoie pas jusqu'à ce que l'application `tk' soit détruite. Si le programme est exécuté avec @code{python -i} ou depuis un éditeur `IDLE', une invite de commande @code{>>>} n'apparaît pas tant que @code{mainloop()} ne termine pas, c'est-à-dire quand il ne reste plus rien avec lequel interagir.

Avec un programme `tkinter' exécuté depuis un éditeur `IDLE', vous pouvez immédiatement commenter l'appel à `mainloop'. On a alors accès à une invite de commande et on peut interagir en direct avec l'application. Il faut juste se rappeler de réactiver l'appel à `mainloop' lors de l'exécution en Python standard.

@node Exécution sans sous-processus,,Développer des applications tkinter,Startup and Code Execution
@anchor{library/idle running-without-a-subprocess}@anchor{3e99}
@subsubsection Exécution sans sous-processus


By default, IDLE executes user code in a separate subprocess via a socket,
which uses the internal loopback interface.  This connection is not
externally visible and no data is sent to or received from the internet.
If firewall software complains anyway, you can ignore it.

Si la tentative de connexion par le `socket' échoue, `IDLE' vous le notifie. Ce genre d'échec est parfois temporaire, mais s'il persiste, le problème peut soit venir d'un pare-feu qui bloque la connexion ou d'une mauvaise configuration dans un système particulier. Jusqu'à ce que le problème soit résolu, vous pouvez exécuter `IDLE' avec l'option `-n' de la ligne de commande.

Si `IDLE' est démarré avec l'option `-n' de la ligne de commande, il s'exécute dans un seul processus et ne crée pas de sous-processus pour exécuter le serveur RPC d'exécution de Python. Ceci peut être utile si Python ne peut pas créer de sous-processus ou de connecteur `RPC' sur votre plateforme. Cependant, dans ce mode, le code de l'utilisateur n'est pas isolé de `IDLE' lui-même. De plus, l'environnement n'est pas réinitialisé quand `Run/Run Module' (@code{F5}) est sélectionné. Si votre code a été modifié, vous devez `reload'() les modules affectés et ré-importer tous les éléments spécifiques (e.g. `from foo import baz') pour que les changements prennent effet. Pour toutes ces raisons, il est préférable d'exécuter `IDLE' avec le sous-processus par défaut si c'est possible.


Obsolète depuis la version 3.4.


@node Help and Preferences,idlelib,Startup and Code Execution,IDLE<64>
@anchor{library/idle help-and-preferences}@anchor{3e9a}
@subsubsection Help and Preferences


@menu
* Sources d'aide:: 
* Modifier les préférences:: 
* IDLE sous macOS:: 
* Extensions:: 

@end menu

@node Sources d'aide,Modifier les préférences,,Help and Preferences
@anchor{library/idle help-sources}@anchor{3e86}@anchor{library/idle id6}@anchor{3e9b}
@subsubsection Sources d'aide


L'entrée du menu d'aide `"IDLE Help"' affiche une version `html' formatée du chapitre sur `IDLE' de la `Library Reference'. Le résultat, dans une fenêtre de texte `tkinter' en lecture-seule, est proche de ce qu'on voit dans un navigateur. Naviguez dans le texte avec la molette de la souris, la barre de défilement ou avec les touches directionnelles du clavier enfoncées. Ou cliquez sur le bouton TOC (`Table of Contents' : sommaire) et sélectionnez un titre de section dans l'espace ouvert.

L'entrée du menu d'aide `"Python Docs"' ouvre les sources d'aide détaillées, incluant des tutoriels, disponibles sur @indicateurl{https://docs.python.org/x.y}, avec `"x.y"' la version de Python en cours d'exécution. Si votre système a une copie locale de la documentation (cela peut être une option d'installation), c'est elle qui est ouverte.

Les URL sélectionnées peuvent être ajoutées ou enlevées du menu d'aide à n'importe quel moment en utilisant l'onglet « `General' » de la fenêtre « Configure IDLE ».

@node Modifier les préférences,IDLE sous macOS,Sources d'aide,Help and Preferences
@anchor{library/idle preferences}@anchor{3e82}@anchor{library/idle setting-preferences}@anchor{3e9c}
@subsubsection Modifier les préférences


Les préférences de polices, surlignage, touches et les préférences générales peuvent être changées via « Configure IDLE » dans le menu « Options ». Les paramètres modifiés par l'utilisateur sont enregistrés dans un dossier @code{.idlerc} dans le dossier personnel de l'utilisateur. Les problèmes causés par des fichiers de configuration utilisateur corrompus sont résolus en modifiant ou en supprimant un ou plusieurs fichiers dans `.idlerc'.

Dans l'onglet `Fonts', regardez les échantillons de texte pour voir l'effet de la police et de la taille sur de multiples caractères de multiples langues. Éditez les échantillons pour ajouter d'autres caractères qui vous intéressent. Utilisez les échantillons pour sélectionner les polices à largeur constante. Si certains caractères posent des difficultés dans la console ou l'éditeur, ajoutez-les en haut des échantillons et essayez de changer d'abord la taille, puis la fonte.

Dans les onglets `Highlights' et `Keys', sélectionnez un ensemble de couleurs et de raccourcis pré-inclus ou personnalisé. Pour utiliser un ensemble de couleurs et de raccourcis récent avec une version d'`IDLE' plus ancienne, enregistrez-le en tant que nouveau thème ou ensemble de raccourcis personnalisé ; il sera alors accessible aux `IDLE' plus anciens.

@node IDLE sous macOS,Extensions,Modifier les préférences,Help and Preferences
@anchor{library/idle idle-on-macos}@anchor{3e9d}
@subsubsection `IDLE' sous `macOS'


Dans `System Preferences: Dock', on peut mettre `"Prefer tabs when opening documents"' à la valeur `"Always"'. Ce paramètre n'est pas compatible avec le cadriciel `tk/tkinter' utilisé par `IDLE' et il casse quelques fonctionnalités d'`IDLE'.

@node Extensions,,IDLE sous macOS,Help and Preferences
@anchor{library/idle extensions}@anchor{3e9e}
@subsubsection Extensions


`IDLE' inclut un outil d'extensions. Les préférences pour les extensions peuvent être changées avec l'onglet Extensions de la fenêtre de préférences. Lisez le début de `config-extensions.def' dans le dossier `idlelib' pour plus d'informations. La seule extension actuellement utilisée par défaut est `zzdummy', un exemple également utilisé pour les tests.

@node idlelib,,Help and Preferences,IDLE<64>
@anchor{library/idle idlelib}@anchor{3e9f}@anchor{library/idle module-idlelib}@anchor{72}
@subsubsection idlelib


@geindex module; idlelib

`Source code:' Lib/idlelib@footnote{https://github.com/python/cpython/tree/3.13/Lib/idlelib}


__________________________________________________________________


The Lib/idlelib package implements the IDLE application.  See the rest
of this page for how to use IDLE.

The files in idlelib are described in idlelib/README.txt.  Access it
either in idlelib or click Help => About IDLE on the IDLE menu.  This
file also maps IDLE menu items to the code that implements the item.
Except for files listed under 'Startup', the idlelib code is 'private' in
sense that feature changes can be backported (see 
@geindex Python Enhancement Proposals; PEP 434
PEP 434@footnote{https://peps.python.org/pep-0434/}).

@c Other sections I have in mind are
@c Tkinter internals
@c Freezing Tkinter applications

@node Outils de développement,Débogueur et instrumentation,Interfaces Utilisateur Graphiques avec Tk,La bibliothèque standard
@anchor{library/development doc}@anchor{3ea0}@anchor{library/development development}@anchor{3ea1}@anchor{library/development development-tools}@anchor{3ea2}
@section Outils de développement


The modules described in this chapter help you write software.  For example, the
@ref{b4,,pydoc} module takes a module and generates documentation based on the
module's contents.  The @ref{3a,,doctest} and @ref{105,,unittest} modules contains
frameworks for writing unit tests that automatically exercise code and verify
that the expected output is produced.

La liste des modules documentés dans ce chapitre est :

@menu
* typing — Prise en charge des annotations de type:: 
* pydoc: pydoc --- Documentation generator and online help system. Documentation generator and online help system
* Python Development Mode:: 
* doctest — Exemples de tests interactifs en Python:: 
* unittest: unittest --- Unit testing framework. Unit testing framework
* unittest.mock: unittest mock --- mock object library. mock object library
* unittest.mock: unittest mock --- getting started. getting started
* test: test --- Regression tests package for Python. Regression tests package for Python
* test.support: test support --- Utilities for the Python test suite. Utilities for the Python test suite
* test.support.socket_helper: test support socket_helper --- Utilities for socket tests. Utilities for socket tests
* test.support.script_helper: test support script_helper --- Utilities for the Python execution tests. Utilities for the Python execution tests
* test.support.bytecode_helper: test support bytecode_helper --- Support tools for testing correct bytecode generation. Support tools for testing correct bytecode
                                generation
* test.support.threading_helper: test support threading_helper --- Utilities for threading tests. Utilities for threading tests
* test.support.os_helper: test support os_helper --- Utilities for os tests. Utilities for os tests
* test.support.import_helper: test support import_helper --- Utilities for import tests. Utilities for import tests
* test.support.warnings_helper: test support warnings_helper --- Utilities for warnings tests. Utilities for warnings tests

@end menu

@node typing — Prise en charge des annotations de type,pydoc --- Documentation generator and online help system,,Outils de développement
@anchor{library/typing doc}@anchor{3ea3}@anchor{library/typing typing-support-for-type-hints}@anchor{3ea4}
@subsection @code{typing} — Prise en charge des annotations de type


@c import typing
@c from dataclasses import dataclass
@c from typing import *

@geindex module; typing
@anchor{library/typing module-typing}@anchor{103}

Ajouté dans la version 3.5.


`Code source :' Lib/typing.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/typing.py}

@cartouche
@quotation Note 
The Python runtime does not enforce function and variable type annotations.
They can be used by third party tools such as @ref{26a,,type checkers},
IDEs, linters, etc.
@end quotation
@end cartouche


__________________________________________________________________


This module provides runtime support for type hints.

Consider the function below:

@example
def surface_area_of_cube(edge_length: float) -> str:
    return f"The surface area of the cube is @{6 * edge_length ** 2@}."
@end example

The function @code{surface_area_of_cube} takes an argument expected to
be an instance of @ref{2eb,,float}, as indicated by the @ref{1f04,,type hint}
@code{edge_length: float}. The function is expected to return an instance
of @ref{435,,str}, as indicated by the @code{-> str} hint.

While type hints can be simple classes like @ref{2eb,,float} or @ref{435,,str},
they can also be more complex. The @ref{103,,typing} module provides a vocabulary of
more advanced type hints.

New features are frequently added to the @code{typing} module.
The typing_extensions@footnote{https://pypi.org/project/typing_extensions/} package
provides backports of these new features to older versions of Python.


@subsubheading Voir aussi



@table @asis

@item "Typing cheat sheet"@footnote{https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html}

A quick overview of type hints (hosted at the mypy docs)

@item "Type System Reference" section of the mypy docs@footnote{https://mypy.readthedocs.io/en/stable/index.html}

The Python typing system is standardised via PEPs, so this reference
should broadly apply to most Python type checkers. (Some parts may still
be specific to mypy.)

@item "Static Typing with Python"@footnote{https://typing.readthedocs.io/en/latest/}

Type-checker-agnostic documentation written by the community detailing
type system features, useful typing related tools and typing best
practices.
@end table


@menu
* Specification for the Python Type System:: 
* Alias de type:: 
* NewType:: 
* Annotating callable objects:: 
* Génériques:: 
* Annotating tuples:: 
* The type of class objects:: 
* Annotating generators and coroutines:: 
* Types génériques définis par l'utilisateur:: 
* Le type Any:: 
* Sous-typage nominal et sous-typage structurel:: 
* Classe de données:: 
* Étapes d'Obsolescence des Fonctionnalités Majeures:: 

@end menu

@node Specification for the Python Type System,Alias de type,,typing — Prise en charge des annotations de type
@anchor{library/typing relevant-peps}@anchor{3ea5}@anchor{library/typing specification-for-the-python-type-system}@anchor{3ea6}
@subsubsection Specification for the Python Type System


The canonical, up-to-date specification of the Python type system can be
found at "Specification for the Python type system"@footnote{https://typing.readthedocs.io/en/latest/spec/index.html}.

@node Alias de type,NewType,Specification for the Python Type System,typing — Prise en charge des annotations de type
@anchor{library/typing id2}@anchor{3ea7}@anchor{library/typing type-aliases}@anchor{43d}
@subsubsection Alias de type


A type alias is defined using the @ref{421,,type} statement, which creates
an instance of @ref{43e,,TypeAliasType}. In this example,
@code{Vector} and @code{list[float]} will be treated equivalently by static type
checkers:

@example
type Vector = list[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# passes type checking; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])
@end example

Les alias de type sont utiles pour simplifier les signatures complexes. Par exemple :

@example
from collections.abc import Sequence

type ConnectionOptions = dict[str, str]
type Address = tuple[str, int]
type Server = tuple[Address, ConnectionOptions]

def broadcast_message(message: str, servers: Sequence[Server]) -> None:
    ...

# The static type checker will treat the previous type signature as
# being exactly equivalent to this one.
def broadcast_message(
    message: str,
    servers: Sequence[tuple[tuple[str, int], dict[str, str]]]
) -> None:
    ...
@end example

The @ref{421,,type} statement is new in Python 3.12. For backwards
compatibility, type aliases can also be created through simple assignment:

@example
Vector = list[float]
@end example

Or marked with @ref{7b3,,TypeAlias} to make it explicit that this is a type alias,
not a normal variable assignment:

@example
from typing import TypeAlias

Vector: TypeAlias = list[float]
@end example

@node NewType,Annotating callable objects,Alias de type,typing — Prise en charge des annotations de type
@anchor{library/typing distinct}@anchor{3ea8}@anchor{library/typing newtype}@anchor{3ea9}
@subsubsection `NewType'


Utilisez la classe @ref{ce3,,NewType} pour créer des types distincts :

@example
from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)
@end example

Le vérificateur de types statiques traite le nouveau type comme s'il s'agissait d'une sous-classe du type original. C'est utile pour aider à détecter les erreurs logiques :

@example
def get_user_name(user_id: UserId) -> str:
    ...

# passes type checking
user_a = get_user_name(UserId(42351))

# fails type checking; an int is not a UserId
user_b = get_user_name(-1)
@end example

Vous pouvez toujours effectuer toutes les opérations applicables à un entier (type @code{int}) sur une variable de type @code{UserId}, mais le résultat sera toujours de type @code{int}. Ceci vous permet de passer un @code{UserId} partout où un @code{int} est attendu, mais vous empêche de créer accidentellement un @code{UserId} d'une manière invalide :

@example
# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)
@end example

Notez que ces contrôles ne sont exécutés que par le vérificateur de types statique. À l'exécution, l'instruction @code{Derived = NewType('Derived', Base)} fait de @code{Derived} une fonction qui renvoie immédiatement le paramètre que vous lui passez. Cela signifie que l'expression @code{Derived(some_value)} ne crée pas une nouvelle classe et n'introduit pas de surcharge au-delà de celle d'un appel de fonction normal.

Plus précisément, l'expression @code{some_value is Derived(some_value)} est toujours vraie au moment de l'exécution.

La création d'un sous-type de @code{Derived} est invalide :

@example
from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not pass type checking
class AdminUserId(UserId): pass
@end example

Il est néanmoins possible de créer un @ref{ce3,,NewType} basé sur un @code{NewType} « dérivé » :

@example
from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)
@end example

et la vérification de type pour @code{ProUserId} fonctionne comme prévu.

Voir la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} pour plus de détails.

@cartouche
@quotation Note 
Recall that the use of a type alias declares two types to be `equivalent' to
one another. Doing @code{type Alias = Original} will make the static type checker
treat @code{Alias} as being `exactly equivalent' to @code{Original} in all cases.
This is useful when you want to simplify complex type signatures.

En revanche, @code{NewType} déclare qu'un type est un `sous-type' d'un autre. Écrire @code{Derived = NewType('Derived', Original)} fait que le vérificateur de type statique traite @code{Derived} comme une `sous-classe' de @code{Original}, ce qui signifie qu'une valeur de type @code{Original} ne peut être utilisée dans les endroits où une valeur de type @code{Derived} est prévue. C'est utile lorsque vous voulez éviter les erreurs logiques avec un coût d'exécution minimal.
@end quotation
@end cartouche


Ajouté dans la version 3.5.2.



Modifié dans la version 3.10: @code{NewType} is now a class rather than a function.  As a result, there is
some additional runtime cost when calling @code{NewType} over a regular
function.



Modifié dans la version 3.11: The performance of calling @code{NewType} has been restored to its level in
Python 3.9.


@node Annotating callable objects,Génériques,NewType,typing — Prise en charge des annotations de type
@anchor{library/typing annotating-callable-objects}@anchor{3eaa}@anchor{library/typing annotating-callables}@anchor{24af}
@subsubsection Annotating callable objects


Functions -- or other @ref{2870,,callable} objects -- can be annotated using
@ref{7d4,,collections.abc.Callable} or deprecated @ref{7af,,typing.Callable}.
@code{Callable[[int], str]} signifies a function that takes a single parameter
of type @ref{254,,int} and returns a @ref{435,,str}.

For example:

@example
from collections.abc import Callable, Awaitable

def feeder(get_next_item: Callable[[], str]) -> None:
    ...  # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    ...  # Body

async def on_update(value: str) -> None:
    ...  # Body

callback: Callable[[str], Awaitable[None]] = on_update
@end example

The subscription syntax must always be used with exactly two values: the
argument list and the return type.  The argument list must be a list of types,
a @ref{15d,,ParamSpec}, @ref{7ae,,Concatenate}, or an ellipsis. The return type must
be a single type.

If a literal ellipsis @code{...} is given as the argument list, it indicates that
a callable with any arbitrary parameter list would be acceptable:

@example
def concat(x: str, y: str) -> str:
    return x + y

x: Callable[..., str]
x = str     # OK
x = concat  # Also OK
@end example

@code{Callable} cannot express complex signatures such as functions that take a
variadic number of arguments, @ref{3eab,,overloaded functions}, or
functions that have keyword-only parameters. However, these signatures can be
expressed by defining a @ref{261,,Protocol} class with a
@ref{543,,__call__()} method:

@example
from collections.abc import Iterable
from typing import Protocol

class Combiner(Protocol):
    def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...

def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> bytes:
    for item in data:
        ...

def good_cb(*vals: bytes, maxlen: int | None = None) -> list[bytes]:
    ...
def bad_cb(*vals: bytes, maxitems: int | None) -> list[bytes]:
    ...

batch_proc([], good_cb)  # OK
batch_proc([], bad_cb)   # Error! Argument 2 has incompatible type because of
                         # different name and kind in the callback
@end example

Les appelables qui prennent en argument d'autres appelables peuvent indiquer que leurs types de paramètres dépendent les uns des autres en utilisant @ref{15d,,ParamSpec}. De plus, si un appelable ajoute ou supprime des arguments d'autres appelables, l'opérateur @ref{7ae,,Concatenate} peut être utilisé.  Ils prennent la forme @code{Callable[ParamSpecVariable, ReturnType]} et @code{Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]} respectivement.


Modifié dans la version 3.10: @code{Callable} prend désormais en charge @ref{15d,,ParamSpec} et @ref{7ae,,Concatenate}. Voir 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} pour plus de détails.



@subsubheading Voir aussi


La documentation pour @ref{15d,,ParamSpec} et @ref{7ae,,Concatenate} fournit des exemples d'utilisation dans @code{Callable}.


@node Génériques,Annotating tuples,Annotating callable objects,typing — Prise en charge des annotations de type
@anchor{library/typing generics}@anchor{1f02}@anchor{library/typing id3}@anchor{3eac}
@subsubsection Génériques


Since type information about objects kept in containers cannot be statically
inferred in a generic way, many container classes in the standard library support
subscription to denote the expected types of container elements.

@example
from collections.abc import Mapping, Sequence

class Employee: ...

# Sequence[Employee] indicates that all elements in the sequence
# must be instances of "Employee".
# Mapping[str, str] indicates that all keys and all values in the mapping
# must be strings.
def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...
@end example

Generic functions and classes can be parameterized by using
@ref{2b0,,type parameter syntax}:

@example
from collections.abc import Sequence

def first[T](l: Sequence[T]) -> T:  # Function is generic over the TypeVar "T"
    return l[0]
@end example

Or by using the @ref{15c,,TypeVar} factory directly:

@example
from collections.abc import Sequence
from typing import TypeVar

U = TypeVar('U')                  # Declare type variable "U"

def second(l: Sequence[U]) -> U:  # Function is generic over the TypeVar "U"
    return l[1]
@end example


Modifié dans la version 3.12: Syntactic support for generics is new in Python 3.12.


@node Annotating tuples,The type of class objects,Génériques,typing — Prise en charge des annotations de type
@anchor{library/typing annotating-tuples}@anchor{3ead}@anchor{library/typing id4}@anchor{3eae}
@subsubsection Annotating tuples


For most containers in Python, the typing system assumes that all elements in
the container will be of the same type. For example:

@example
from collections.abc import Mapping

# Type checker will infer that all elements in `@w{`}x`@w{`} are meant to be ints
x: list[int] = []

# Type checker error: `@w{`}list`@w{`} only accepts a single type argument:
y: list[int, str] = [1, 'foo']

# Type checker will infer that all keys in `@w{`}z`@w{`} are meant to be strings,
# and that all values in `@w{`}z`@w{`} are meant to be either strings or ints
z: Mapping[str, str | int] = @{@}
@end example

@ref{5fc,,list} only accepts one type argument, so a type checker would emit an
error on the @code{y} assignment above. Similarly,
@ref{8b7,,Mapping} only accepts two type arguments: the first
indicates the type of the keys, and the second indicates the type of the
values.

Unlike most other Python containers, however, it is common in idiomatic Python
code for tuples to have elements which are not all of the same type. For this
reason, tuples are special-cased in Python's typing system. @ref{366,,tuple}
accepts `any number' of type arguments:

@example
# OK: `@w{`}x`@w{`} is assigned to a tuple of length 1 where the sole element is an int
x: tuple[int] = (5,)

# OK: `@w{`}y`@w{`} is assigned to a tuple of length 2;
# element 1 is an int, element 2 is a str
y: tuple[int, str] = (5, "foo")

# Error: the type annotation indicates a tuple of length 1,
# but `@w{`}z`@w{`} has been assigned to a tuple of length 3
z: tuple[int] = (1, 2, 3)
@end example

To denote a tuple which could be of `any' length, and in which all elements are
of the same type @code{T}, use @code{tuple[T, ...]}. To denote an empty tuple, use
@code{tuple[()]}. Using plain @code{tuple} as an annotation is equivalent to using
@code{tuple[Any, ...]}:

@example
x: tuple[int, ...] = (1, 2)
# These reassignments are OK: `@w{`}tuple[int, ...]`@w{`} indicates x can be of any length
x = (1, 2, 3)
x = ()
# This reassignment is an error: all elements in `@w{`}x`@w{`} must be ints
x = ("foo", "bar")

# `@w{`}y`@w{`} can only ever be assigned to an empty tuple
y: tuple[()] = ()

z: tuple = ("foo", "bar")
# These reassignments are OK: plain `@w{`}tuple`@w{`} is equivalent to `@w{`}tuple[Any, ...]`@w{`}
z = (1, 2, 3)
z = ()
@end example

@node The type of class objects,Annotating generators and coroutines,Annotating tuples,typing — Prise en charge des annotations de type
@anchor{library/typing the-type-of-class-objects}@anchor{3eaf}@anchor{library/typing type-of-class-objects}@anchor{3eb0}
@subsubsection The type of class objects


A variable annotated with @code{C} may accept a value of type @code{C}. In
contrast, a variable annotated with @code{type[C]} (or deprecated
@ref{3eb1,,typing.Type[C]}) may accept values that are classes
themselves -- specifically, it will accept the `class object' of @code{C}. For
example:

@example
a = 3         # Has type `@w{`}int`@w{`}
b = int       # Has type `@w{`}type[int]`@w{`}
c = type(a)   # Also has type `@w{`}type[int]`@w{`}
@end example

Note that @code{type[C]} is covariant:

@example
class User: ...
class ProUser(User): ...
class TeamUser(User): ...

def make_new_user(user_class: type[User]) -> User:
    # ...
    return user_class()

make_new_user(User)      # OK
make_new_user(ProUser)   # Also OK: `@w{`}type[ProUser]`@w{`} is a subtype of `@w{`}type[User]`@w{`}
make_new_user(TeamUser)  # Still fine
make_new_user(User())    # Error: expected `@w{`}type[User]`@w{`} but got `@w{`}User`@w{`}
make_new_user(int)       # Error: `@w{`}type[int]`@w{`} is not a subtype of `@w{`}type[User]`@w{`}
@end example

The only legal parameters for @ref{d36,,type} are classes, @ref{697,,Any},
@ref{1f02,,type variables}, and unions of any of these types.
For example:

@example
def new_non_team_user(user_class: type[BasicUser | ProUser]): ...

new_non_team_user(BasicUser)  # OK
new_non_team_user(ProUser)    # OK
new_non_team_user(TeamUser)   # Error: `@w{`}type[TeamUser]`@w{`} is not a subtype
                              # of `@w{`}type[BasicUser | ProUser]`@w{`}
new_non_team_user(User)       # Also an error
@end example

@code{type[Any]} is equivalent to @ref{d36,,type}, which is the root of Python's
@ref{1ef6,,metaclass hierarchy}.

@node Annotating generators and coroutines,Types génériques définis par l'utilisateur,The type of class objects,typing — Prise en charge des annotations de type
@anchor{library/typing annotating-generators-and-coroutines}@anchor{24b0}@anchor{library/typing id5}@anchor{3eb2}
@subsubsection Annotating generators and coroutines


A generator can be annotated using the generic type
@ref{dc8,,Generator[YieldType@comma{} SendType@comma{} ReturnType]}.
For example:

@example
def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'
@end example

Note that unlike many other generic classes in the standard library,
the @code{SendType} of @ref{dc8,,Generator} behaves
contravariantly, not covariantly or invariantly.

The @code{SendType} and @code{ReturnType} parameters default to @code{None}:

@example
def infinite_stream(start: int) -> Generator[int]:
    while True:
        yield start
        start += 1
@end example

It is also possible to set these types explicitly:

@example
def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1
@end example

Simple generators that only ever yield values can also be annotated
as having a return type of either
@ref{21d6,,Iterable[YieldType]}
or @ref{21d7,,Iterator[YieldType]}:

@example
def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1
@end example

Async generators are handled in a similar fashion, but don't
expect a @code{ReturnType} type argument
(@ref{c78,,AsyncGenerator[YieldType@comma{} SendType]}).
The @code{SendType} argument defaults to @code{None}, so the following definitions
are equivalent:

@example
async def infinite_stream(start: int) -> AsyncGenerator[int]:
    while True:
        yield start
        start = await increment(start)

async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)
@end example

As in the synchronous case,
@ref{dcc,,AsyncIterable[YieldType]}
and @ref{dcb,,AsyncIterator[YieldType]} are
available as well:

@example
async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)
@end example

Coroutines can be annotated using
@ref{dca,,Coroutine[YieldType@comma{} SendType@comma{} ReturnType]}.
Generic arguments correspond to those of @ref{dc8,,Generator},
for example:

@example
from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # Some coroutine defined elsewhere
x = c.send('hi')                   # Inferred type of 'x' is list[str]
async def bar() -> None:
    y = await c                    # Inferred type of 'y' is int
@end example

@node Types génériques définis par l'utilisateur,Le type Any,Annotating generators and coroutines,typing — Prise en charge des annotations de type
@anchor{library/typing user-defined-generic-types}@anchor{3eb3}@anchor{library/typing user-defined-generics}@anchor{4b8}
@subsubsection Types génériques définis par l'utilisateur


Une classe définie par l'utilisateur peut être définie comme une classe générique.

@example
from logging import Logger

class LoggedVar[T]:
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new

    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value

    def log(self, message: str) -> None:
        self.logger.info('%s: %s', self.name, message)
@end example

This syntax indicates that the class @code{LoggedVar} is parameterised around a
single @ref{3eb4,,type variable} @code{T} . This also makes @code{T} valid as
a type within the class body.

Generic classes implicitly inherit from @ref{15a1,,Generic}. For compatibility
with Python 3.11 and lower, it is also possible to inherit explicitly from
@ref{15a1,,Generic} to indicate a generic class:

@example
from typing import TypeVar, Generic

T = TypeVar('T')

class LoggedVar(Generic[T]):
    ...
@end example

Generic classes have @ref{725,,__class_getitem__()} methods, meaning they
can be parameterised at runtime (e.g. @code{LoggedVar[int]} below):

@example
from collections.abc import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)
@end example

A generic type can have any number of type variables. All varieties of
@ref{15c,,TypeVar} are permissible as parameters for a generic type:

@example
from typing import TypeVar, Generic, Sequence

class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
    ...

OldT = TypeVar('OldT', contravariant=True)
OldB = TypeVar('OldB', bound=Sequence[bytes], covariant=True)
OldS = TypeVar('OldS', int, str)

class OldWeirdTrio(Generic[OldT, OldB, OldS]):
    ...
@end example

Chaque argument de variable de type @ref{15a1,,Generic} doit être distinct. Ceci n'est donc pas valable :

@example
from typing import TypeVar, Generic
...

class Pair[M, M]:  # SyntaxError
    ...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...
@end example

Generic classes can also inherit from other classes:

@example
from collections.abc import Sized

class LinkedList[T](Sized):
    ...
@end example

When inheriting from generic classes, some type parameters could be fixed:

@example
from collections.abc import Mapping

class MyDict[T](Mapping[str, T]):
    ...
@end example

Dans ce cas, @code{MyDict} a un seul paramètre, @code{T}.

Using a generic class without specifying type parameters assumes
@ref{697,,Any} for each position. In the following example, @code{MyIterable} is
not generic but implicitly inherits from @code{Iterable[Any]}:

@example
from collections.abc import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]
    ...
@end example

User-defined generic type aliases are also supported. Examples:

@example
from collections.abc import Iterable

type Response[S] = Iterable[S] | int

# Return type here is same as Iterable[str] | int
def response(query: str) -> Response[str]:
    ...

type Vec[T] = Iterable[tuple[T, T]]

def inproduct[T: (int, float, complex)](v: Vec[T]) -> T: # Same as Iterable[tuple[T, T]]
    return sum(x*y for x, y in v)
@end example

For backward compatibility, generic type aliases can also be created
through a simple assignment:

@example
from collections.abc import Iterable
from typing import TypeVar

S = TypeVar("S")
Response = Iterable[S] | int
@end example


Modifié dans la version 3.7: @ref{15a1,,Generic} n'a plus de métaclasse personnalisée.



Modifié dans la version 3.12: Syntactic support for generics and type aliases is new in version 3.12.
Previously, generic classes had to explicitly inherit from @ref{15a1,,Generic}
or contain a type variable in one of their bases.


User-defined generics for parameter expressions are also supported via parameter
specification variables in the form @code{[**P]}.  The behavior is consistent
with type variables' described above as parameter specification variables are
treated by the typing module as a specialized type variable.  The one exception
to this is that a list of types can be used to substitute a @ref{15d,,ParamSpec}:

@example
>>> class Z[T, **P]: ...  # T is a TypeVar; P is a ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]
@end example

Classes generic over a @ref{15d,,ParamSpec} can also be created using explicit
inheritance from @ref{15a1,,Generic}. In this case, @code{**} is not used:

@example
from typing import ParamSpec, Generic

P = ParamSpec('P')

class Z(Generic[P]):
    ...
@end example

Another difference between @ref{15c,,TypeVar} and @ref{15d,,ParamSpec} is that a
generic with only one parameter specification variable will accept
parameter lists in the forms @code{X[[Type1, Type2, ...]]} and also
@code{X[Type1, Type2, ...]} for aesthetic reasons.  Internally, the latter is converted
to the former, so the following are equivalent:

@example
>>> class X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]
@end example

Note that generics with @ref{15d,,ParamSpec} may not have correct
@code{__parameters__} after substitution in some cases because they
are intended primarily for static type checking.


Modifié dans la version 3.10: @ref{15a1,,Generic} can now be parameterized over parameter expressions.
See @ref{15d,,ParamSpec} and 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} for more details.


A user-defined generic class can have ABCs as base classes without a metaclass
conflict. Generic metaclasses are not supported. The outcome of parameterizing
generics is cached, and most types in the typing module are @ref{5fb,,hashable} and
comparable for equality.

@node Le type Any,Sous-typage nominal et sous-typage structurel,Types génériques définis par l'utilisateur,typing — Prise en charge des annotations de type
@anchor{library/typing the-any-type}@anchor{3eb5}
@subsubsection Le type @code{Any}


Un type particulier est @ref{697,,Any}. Un vérificateur de types statiques traite chaque type comme étant compatible avec @ref{697,,Any} et @ref{697,,Any} comme étant compatible avec chaque type.

This means that it is possible to perform any operation or method call on a
value of type @ref{697,,Any} and assign it to any variable:

@example
from typing import Any

a: Any = None
a = []          # OK
a = 2           # OK

s: str = '@w{'}
s = a           # OK

def foo(item: Any) -> int:
    # Passes type checking; 'item' could be any type,
    # and that type might have a 'bar' method
    item.bar()
    ...
@end example

Notice that no type checking is performed when assigning a value of type
@ref{697,,Any} to a more precise type. For example, the static type checker did
not report an error when assigning @code{a} to @code{s} even though @code{s} was
declared to be of type @ref{435,,str} and receives an @ref{254,,int} value at
runtime!

De plus, toutes les fonctions sans type de retour ni type de paramètre sont considérées comme utilisant @ref{697,,Any} implicitement par défaut :

@example
def legacy_parser(text):
    ...
    return data

# A static type checker will treat the above
# as having the same signature as:
def legacy_parser(text: Any) -> Any:
    ...
    return data
@end example

Ce comportement permet à @ref{697,,Any} d'être utilisé comme succédané lorsque vous avez besoin de mélanger du code typé dynamiquement et statiquement.

Comparons le comportement de @ref{697,,Any} avec celui de @ref{a7a,,object}. De la même manière que pour @ref{697,,Any}, chaque type est un sous-type de @ref{a7a,,object}. Cependant, contrairement à @ref{697,,Any}, l'inverse n'est pas vrai : @ref{a7a,,object} n'est `pas' un sous-type de chaque autre type.

Cela signifie que lorsque le type d'une valeur est @ref{a7a,,object}, un vérificateur de types rejette presque toutes les opérations sur celle-ci, et l'affecter à une variable (ou l'utiliser comme une valeur de retour) d'un type plus spécialisé est une erreur de typage. Par exemple :

@example
def hash_a(item: object) -> int:
    # Fails type checking; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Passes type checking
    item.magic()
    ...

# Passes type checking, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")

# Passes type checking, since Any is compatible with all types
hash_b(42)
hash_b("foo")
@end example

Utilisez @ref{a7a,,object} pour indiquer qu'une valeur peut être de n'importe quel type de manière sûre. Utiliser @ref{697,,Any} pour indiquer qu'une valeur est typée dynamiquement.

@node Sous-typage nominal et sous-typage structurel,Classe de données,Le type Any,typing — Prise en charge des annotations de type
@anchor{library/typing nominal-vs-structural-subtyping}@anchor{3eb6}
@subsubsection Sous-typage nominal et sous-typage structurel


Initially 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} defined the Python static type system as using
`nominal subtyping'. This means that a class @code{A} is allowed where
a class @code{B} is expected if and only if @code{A} is a subclass of @code{B}.

This requirement previously also applied to abstract base classes, such as
@ref{21d6,,Iterable}. The problem with this approach is that a class had
to be explicitly marked to support them, which is unpythonic and unlike
what one would normally do in idiomatic dynamically typed Python code.
For example, this conforms to 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}:

@example
from collections.abc import Sized, Iterable, Iterator

class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...
@end example

La 
@geindex Python Enhancement Proposals; PEP 544
PEP 544@footnote{https://peps.python.org/pep-0544/} permet de résoudre ce problème en permettant aux utilisateurs d'écrire le code ci-dessus sans classes mères explicites dans la définition de classe, permettant à @code{Bucket} d'être implicitement considéré comme un sous-type de @code{Sized} et @code{Iterable[int]} par des vérificateurs de type statique. C'est ce qu'on appelle le `sous-typage structurel' (ou typage canard) :

@example
from collections.abc import Iterator, Iterable

class Bucket:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check
@end example

De plus, en sous-classant une classe spéciale @ref{261,,Protocol}, un utilisateur peut définir de nouveaux protocoles personnalisés pour profiter pleinement du sous-typage structurel (voir exemples ci-dessous).

@node Classe de données,Étapes d'Obsolescence des Fonctionnalités Majeures,Sous-typage nominal et sous-typage structurel,typing — Prise en charge des annotations de type
@anchor{library/typing module-contents}@anchor{3eb7}
@subsubsection Classe de données


The @code{typing} module defines the following classes, functions and decorators.

@menu
* Special typing primitives:: 
* Protocoles: Protocoles<3>. 
* ABCs for working with IO:: 
* Functions and decorators:: 
* Utilitaires d'introspection:: 
* Constante:: 
* Deprecated aliases:: 

@end menu

@node Special typing primitives,Protocoles<3>,,Classe de données
@anchor{library/typing special-typing-primitives}@anchor{3eb8}
@subsubsection Special typing primitives


@menu
* Special types:: 
* Special forms:: 
* Building generic types and type aliases:: 
* Other special directives:: 

@end menu

@node Special types,Special forms,,Special typing primitives
@anchor{library/typing special-types}@anchor{3eb9}
@subsubsection Special types


These can be used as types in annotations. They do not support subscription
using @code{[]}.

@geindex Any (dans le module typing)
@anchor{library/typing typing Any}@anchor{697}
@deffn {Données} typing.Any

Type spécial indiquant un type non contraint.


@itemize *

@item 
Chaque type est compatible avec @ref{697,,Any}.

@item 
@ref{697,,Any} est compatible avec tous les types.
@end itemize


Modifié dans la version 3.11: @ref{697,,Any} can now be used as a base class. This can be useful for
avoiding type checker errors with classes that can duck type anywhere or
are highly dynamic.

@end deffn

@geindex AnyStr (dans le module typing)
@anchor{library/typing typing AnyStr}@anchor{2af}
@deffn {Données} typing.AnyStr

A @ref{3eba,,constrained type variable}.

Definition:

@example
AnyStr = TypeVar('AnyStr', str, bytes)
@end example

@code{AnyStr} is meant to be used for functions that may accept @ref{435,,str} or
@ref{1bd,,bytes} arguments but cannot allow the two to mix.

Par exemple :

@example
def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat("foo", "bar")    # OK, output has type 'str'
concat(b"foo", b"bar")  # OK, output has type 'bytes'
concat("foo", b"bar")   # Error, cannot mix str and bytes
@end example

Note that, despite its name, @code{AnyStr} has nothing to do with the
@ref{697,,Any} type, nor does it mean "any string". In particular, @code{AnyStr}
and @code{str | bytes} are different from each other and have different use
cases:

@example
# Invalid use of AnyStr:
# The type variable is used only once in the function signature,
# so cannot be "solved" by the type checker
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# The better way of annotating this function:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"
@end example


Deprecated since version 3.13, will be removed in version 3.18: Deprecated in favor of the new @ref{2b0,,type parameter syntax}.
Use @code{class A[T: (str, bytes)]: ...} instead of importing @code{AnyStr}. See
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} for more details.

In Python 3.16, @code{AnyStr} will be removed from @code{typing.__all__}, and
deprecation warnings will be emitted at runtime when it is accessed or
imported from @code{typing}. @code{AnyStr} will be removed from @code{typing}
in Python 3.18.

@end deffn

@geindex LiteralString (dans le module typing)
@anchor{library/typing typing LiteralString}@anchor{5b4}
@deffn {Données} typing.LiteralString

Special type that includes only literal strings.

Any string
literal is compatible with @code{LiteralString}, as is another
@code{LiteralString}. However, an object typed as just @code{str} is not.
A string created by composing @code{LiteralString}-typed objects
is also acceptable as a @code{LiteralString}.

Example:

@example
def run_query(sql: LiteralString) -> None:
    ...

def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # OK
    run_query(literal_string)  # OK
    run_query("SELECT * FROM " + literal_string)  # OK
    run_query(arbitrary_string)  # type checker error
    run_query(  # type checker error
        f"SELECT * FROM students WHERE name = @{arbitrary_string@}"
    )
@end example

@code{LiteralString} is useful for sensitive APIs where arbitrary user-generated
strings could generate problems. For example, the two cases above
that generate type checker errors could be vulnerable to an SQL
injection attack.

See 
@geindex Python Enhancement Proposals; PEP 675
PEP 675@footnote{https://peps.python.org/pep-0675/} for more details.


Ajouté dans la version 3.11.

@end deffn

@geindex Never (dans le module typing)
@geindex NoReturn (dans le module typing)
@anchor{library/typing typing Never}@anchor{693}
@deffn {Données} typing.Never
@anchor{library/typing typing NoReturn}@anchor{3ebb}
@deffnx {Données} typing.NoReturn

@code{Never} and @code{NoReturn} represent the
bottom type@footnote{https://en.wikipedia.org/wiki/Bottom_type},
a type that has no members.

They can be used to indicate that a function never returns,
such as @ref{1327,,sys.exit()}:

@example
from typing import Never  # or NoReturn

def stop() -> Never:
    raise RuntimeError('no way')
@end example

Or to define a function that should never be
called, as there are no valid arguments, such as
@ref{692,,assert_never()}:

@example
from typing import Never  # or NoReturn

def never_call_me(arg: Never) -> None:
    pass

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # type checker error
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK, arg is of type Never (or NoReturn)
@end example

@code{Never} and @code{NoReturn} have the same meaning in the type system
and static type checkers treat both equivalently.


Ajouté dans la version 3.6.2: Added @ref{3ebb,,NoReturn}.



Ajouté dans la version 3.11: Added @ref{693,,Never}.

@end deffn

@geindex Self (dans le module typing)
@anchor{library/typing typing Self}@anchor{5b1}
@deffn {Données} typing.Self

Special type to represent the current enclosed class.

Par exemple :

@example
from typing import Self, reveal_type

class Foo:
    def return_self(self) -> Self:
        ...
        return self

class SubclassOfFoo(Foo): pass

reveal_type(Foo().return_self())  # Revealed type is "Foo"
reveal_type(SubclassOfFoo().return_self())  # Revealed type is "SubclassOfFoo"
@end example

This annotation is semantically equivalent to the following,
albeit in a more succinct fashion:

@example
from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self
@end example

In general, if something returns @code{self}, as in the above examples, you
should use @code{Self} as the return annotation. If @code{Foo.return_self} was
annotated as returning @code{"Foo"}, then the type checker would infer the
object returned from @code{SubclassOfFoo.return_self} as being of type @code{Foo}
rather than @code{SubclassOfFoo}.

Other common use cases include:


@itemize -

@item 
@ref{165,,classmethod}s that are used as alternative constructors and return instances
of the @code{cls} parameter.

@item 
Annotating an @ref{5b2,,__enter__()} method which returns self.
@end itemize

You should not use @code{Self} as the return annotation if the method is not
guaranteed to return an instance of a subclass when the class is
subclassed:

@example
class Eggs:
    # Self would be an incorrect return annotation here,
    # as the object returned is always an instance of Eggs,
    # even in subclasses
    def returns_eggs(self) -> "Eggs":
        return Eggs()
@end example

See 
@geindex Python Enhancement Proposals; PEP 673
PEP 673@footnote{https://peps.python.org/pep-0673/} for more details.


Ajouté dans la version 3.11.

@end deffn

@geindex TypeAlias (dans le module typing)
@anchor{library/typing typing TypeAlias}@anchor{7b3}
@deffn {Données} typing.TypeAlias

Special annotation for explicitly declaring a @ref{43d,,type alias}.

Par exemple :

@example
from typing import TypeAlias

Factors: TypeAlias = list[int]
@end example

@code{TypeAlias} is particularly useful on older Python versions for annotating
aliases that make use of forward references, as it can be hard for type
checkers to distinguish these from normal variable assignments:

@example
from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box" does not exist yet,
# so we have to use quotes for the forward reference on Python <3.12.
# Using `@w{`}TypeAlias`@w{`} tells the type checker that this is a type alias declaration,
# not a variable assignment to a string.
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
    @@classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...
@end example

See 
@geindex Python Enhancement Proposals; PEP 613
PEP 613@footnote{https://peps.python.org/pep-0613/} for more details.


Ajouté dans la version 3.10.



Obsolète depuis la version 3.12: @ref{7b3,,TypeAlias} is deprecated in favor of the @ref{421,,type} statement,
which creates instances of @ref{43e,,TypeAliasType}
and which natively supports forward references.
Note that while @ref{7b3,,TypeAlias} and @ref{43e,,TypeAliasType} serve
similar purposes and have similar names, they are distinct and the
latter is not the type of the former.
Removal of @ref{7b3,,TypeAlias} is not currently planned, but users
are encouraged to migrate to @ref{421,,type} statements.

@end deffn

@node Special forms,Building generic types and type aliases,Special types,Special typing primitives
@anchor{library/typing special-forms}@anchor{3ebc}
@subsubsection Special forms


These can be used as types in annotations. They all support subscription using
@code{[]}, but each has a unique syntax.

@geindex Union (dans le module typing)
@anchor{library/typing typing Union}@anchor{626}
@deffn {Données} typing.Union

Union type; @code{Union[X, Y]} is equivalent to @code{X | Y} and means either X or Y.

To define a union, use e.g. @code{Union[int, str]} or the shorthand @code{int | str}. Using that shorthand is recommended. Details:


@itemize *

@item 
Les arguments doivent être des types et il doit y en avoir au moins un.

@item 
Les unions d'unions sont aplanies, par exemple :

@example
Union[Union[int, str], float] == Union[int, str, float]
@end example

@item 
Les unions d'un seul argument disparaissent, par exemple :

@example
Union[int] == int  # The constructor actually returns int
@end example

@item 
Les arguments redondants sont ignorés, par exemple :

@example
Union[int, str, int] == Union[int, str] == int | str
@end example

@item 
Lors de la comparaison d'unions, l'ordre des arguments est ignoré, par exemple :

@example
Union[int, str] == Union[str, int]
@end example

@item 
You cannot subclass or instantiate a @code{Union}.

@item 
Vous ne pouvez pas écrire @code{Union[X][Y]}.
@end itemize


Modifié dans la version 3.7: Ne supprime pas les sous-classes explicites des unions à l'exécution.



Modifié dans la version 3.10: Unions can now be written as @code{X | Y}. See
@ref{7ac,,union type expressions}.

@end deffn

@geindex Optional (dans le module typing)
@anchor{library/typing typing Optional}@anchor{69e}
@deffn {Données} typing.Optional

@code{Optional[X]} is equivalent to @code{X | None} (or @code{Union[X, None]}).

Notez que ce n'est pas le même concept qu'un argument optionnel, qui est un argument qui possède une valeur par défaut. Un argument optionnel (qui a une valeur par défaut) ne nécessite pas, à ce titre, le qualificatif @code{Optional} sur son annotation de type. Par exemple :

@example
def foo(arg: int = 0) -> None:
    ...
@end example

Par contre, si une valeur explicite de @code{None} est permise, l'utilisation de @code{Optional} est appropriée, que l'argument soit facultatif ou non. Par exemple :

@example
def foo(arg: Optional[int] = None) -> None:
    ...
@end example


Modifié dans la version 3.10: Optional can now be written as @code{X | None}. See
@ref{7ac,,union type expressions}.

@end deffn

@geindex Concatenate (dans le module typing)
@anchor{library/typing typing Concatenate}@anchor{7ae}
@deffn {Données} typing.Concatenate

Special form for annotating higher-order functions.

@code{Concatenate} can be used in conjunction with @ref{24af,,Callable} and
@ref{15d,,ParamSpec} to annotate a higher-order callable which adds, removes,
or transforms parameters of another
callable.  Usage is in the form
@code{Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]}. @code{Concatenate}
is currently only valid when used as the first argument to a @ref{24af,,Callable}.
The last parameter to @code{Concatenate} must be a @ref{15d,,ParamSpec} or
ellipsis (@code{...}).

For example, to annotate a decorator @code{with_lock} which provides a
@ref{1600,,threading.Lock} to the decorated function,  @code{Concatenate} can be
used to indicate that @code{with_lock} expects a callable which takes in a
@code{Lock} as the first argument, and returns a callable with a different type
signature.  In this case, the @ref{15d,,ParamSpec} indicates that the returned
callable's parameter types are dependent on the parameter types of the
callable being passed in:

@example
from collections.abc import Callable
from threading import Lock
from typing import Concatenate

# Use this lock to ensure that only one thread is executing a function
# at any time.
my_lock = Lock()

def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '@w{'}'A type-safe decorator which provides a lock.'@w{'}'
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # Provide the lock as the first argument.
        return f(my_lock, *args, **kwargs)
    return inner

@@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '@w{'}'Add a list of numbers together in a thread-safe manner.'@w{'}'
    with lock:
        return sum(numbers)

# We don't need to pass in the lock ourselves thanks to the decorator.
sum_threadsafe([1.1, 2.2, 3.3])
@end example


Ajouté dans la version 3.10.



@subsubheading Voir aussi



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} -- Parameter Specification Variables (the PEP which introduced
@code{ParamSpec} and @code{Concatenate})

@item 
@ref{15d,,ParamSpec}

@item 
@ref{24af,,Annotating callable objects}
@end itemize

@end deffn

@geindex Literal (dans le module typing)
@anchor{library/typing typing Literal}@anchor{83f}
@deffn {Données} typing.Literal

Special typing form to define "literal types".

@code{Literal} can be used to indicate to type checkers that the
annotated object has a value equivalent to one of the
provided literals.

Par exemple :

@example
def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

type Mode = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: Mode) -> str:
    ...

open_helper('/some/path', 'r')      # Passes type check
open_helper('/other/path', 'typo')  # Error in type checker
@end example

@code{Literal[...]} ne peut être sous-classé. Lors de l'exécution, une valeur arbitraire est autorisée comme argument de type pour @code{Literal[...]}, mais les vérificateurs de type peuvent imposer des restrictions. Voir la 
@geindex Python Enhancement Proposals; PEP 586
PEP 586@footnote{https://peps.python.org/pep-0586/} pour plus de détails sur les types littéraux.


Ajouté dans la version 3.8.



Modifié dans la version 3.9.1: @code{Literal} now de-duplicates parameters.  Equality comparisons of
@code{Literal} objects are no longer order dependent. @code{Literal} objects
will now raise a @ref{522,,TypeError} exception during equality comparisons
if one of their parameters are not @ref{5fb,,hashable}.

@end deffn

@geindex ClassVar (dans le module typing)
@anchor{library/typing typing ClassVar}@anchor{263}
@deffn {Données} typing.ClassVar

Construction de type particulière pour indiquer les variables de classe.

Telle qu'introduite dans la 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}, une annotation de variable enveloppée dans ClassVar indique qu'un attribut donné est destiné à être utilisé comme une variable de classe et ne doit pas être défini sur des instances de cette classe. Utilisation :

@example
class Starship:
    stats: ClassVar[dict[str, int]] = @{@} # class variable
    damage: int = 10                     # instance variable
@end example

@ref{263,,ClassVar} n'accepte que les types et ne peut plus être dérivé.

@ref{263,,ClassVar} n'est pas une classe en soi, et ne devrait pas être utilisée avec @ref{42b,,isinstance()} ou @ref{7ab,,issubclass()}. @ref{263,,ClassVar} ne modifie pas le comportement d'exécution Python, mais il peut être utilisé par des vérificateurs tiers. Par exemple, un vérificateur de types peut marquer le code suivant comme une erreur :

@example
enterprise_d = Starship(3000)
enterprise_d.stats = @{@} # Error, setting class variable on instance
Starship.stats = @{@}     # This is OK
@end example


Ajouté dans la version 3.5.3.



Modifié dans la version 3.13: @ref{263,,ClassVar} can now be nested in @ref{264,,Final} and vice versa.

@end deffn

@geindex Final (dans le module typing)
@anchor{library/typing typing Final}@anchor{264}
@deffn {Données} typing.Final

Special typing construct to indicate final names to type checkers.

Final names cannot be reassigned in any scope. Final names declared in class
scopes cannot be overridden in subclasses.

Par exemple :

@example
MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Error reported by type checker

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Error reported by type checker
@end example

Ces propriétés ne sont pas vérifiées à l'exécution. Voir la 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/} pour plus de détails.


Ajouté dans la version 3.8.



Modifié dans la version 3.13: @ref{264,,Final} can now be nested in @ref{263,,ClassVar} and vice versa.

@end deffn

@geindex Required (dans le module typing)
@anchor{library/typing typing Required}@anchor{5ae}
@deffn {Données} typing.Required

Special typing construct to mark a @ref{161,,TypedDict} key as required.

This is mainly useful for @code{total=False} TypedDicts. See @ref{161,,TypedDict}
and 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/} for more details.


Ajouté dans la version 3.11.

@end deffn

@geindex NotRequired (dans le module typing)
@anchor{library/typing typing NotRequired}@anchor{5af}
@deffn {Données} typing.NotRequired

Special typing construct to mark a @ref{161,,TypedDict} key as potentially
missing.

See @ref{161,,TypedDict} and 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/} for more details.


Ajouté dans la version 3.11.

@end deffn

@geindex ReadOnly (dans le module typing)
@anchor{library/typing typing ReadOnly}@anchor{160}
@deffn {Données} typing.ReadOnly

A special typing construct to mark an item of a @ref{161,,TypedDict} as read-only.

Par exemple :

@example
class Movie(TypedDict):
   title: ReadOnly[str]
   year: int

def mutate_movie(m: Movie) -> None:
   m["year"] = 1999  # allowed
   m["title"] = "The Matrix"  # typechecker error
@end example

There is no runtime checking for this property.

See @ref{161,,TypedDict} and 
@geindex Python Enhancement Proposals; PEP 705
PEP 705@footnote{https://peps.python.org/pep-0705/} for more details.


Ajouté dans la version 3.13.

@end deffn

@geindex Annotated (dans le module typing)
@anchor{library/typing typing Annotated}@anchor{92a}
@deffn {Données} typing.Annotated

Special typing form to add context-specific metadata to an annotation.

Add metadata @code{x} to a given type @code{T} by using the annotation
@code{Annotated[T, x]}. Metadata added using @code{Annotated} can be used by
static analysis tools or at runtime. At runtime, the metadata is stored
in a @code{__metadata__} attribute.

If a library or tool encounters an annotation @code{Annotated[T, x]} and has
no special logic for the metadata, it should ignore the metadata and simply
treat the annotation as @code{T}. As such, @code{Annotated} can be useful for code
that wants to use annotations for purposes outside Python's static typing
system.

Using @code{Annotated[T, x]} as an annotation still allows for static
typechecking of @code{T}, as type checkers will simply ignore the metadata @code{x}.
In this way, @code{Annotated} differs from the
@ref{69f,,@@no_type_check} decorator, which can also be used for
adding annotations outside the scope of the typing system, but
completely disables typechecking for a function or class.

The responsibility of how to interpret the metadata
lies with the tool or library encountering an
@code{Annotated} annotation. A tool or library encountering an @code{Annotated} type
can scan through the metadata elements to determine if they are of interest
(e.g., using @ref{42b,,isinstance()}).


@deffn {Describe} Annotated[<type>, <metadata>]
@end deffn

Here is an example of how you might use @code{Annotated} to add metadata to
type annotations if you were doing range analysis:

@example
@@dataclass
class ValueRange:
    lo: int
    hi: int

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]
@end example

Details of the syntax:


@itemize *

@item 
The first argument to @code{Annotated} must be a valid type

@item 
Multiple metadata elements can be supplied (@code{Annotated} supports variadic
arguments):

@example
@@dataclass
class ctype:
    kind: str

Annotated[int, ValueRange(3, 10), ctype("char")]
@end example

It is up to the tool consuming the annotations to decide whether the
client is allowed to add multiple metadata elements to one annotation and how to
merge those annotations.

@item 
@code{Annotated} must be subscripted with at least two arguments (
@code{Annotated[int]} is not valid)

@item 
The order of the metadata elements is preserved and matters for equality
checks:

@example
assert Annotated[int, ValueRange(3, 10), ctype("char")] != Annotated[
    int, ctype("char"), ValueRange(3, 10)
]
@end example

@item 
Nested @code{Annotated} types are flattened. The order of the metadata elements
starts with the innermost annotation:

@example
assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]
@end example

@item 
Duplicated metadata elements are not removed:

@example
assert Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]
@end example

@item 
@code{Annotated} can be used with nested and generic aliases:

@example
@@dataclass
class MaxLen:
    value: int

type Vec[T] = Annotated[list[tuple[T, T]], MaxLen(10)]

# When used in a type annotation, a type checker will treat "V" the same as
# `@w{`}Annotated[list[tuple[int, int]], MaxLen(10)]`@w{`}:
type V = Vec[int]
@end example

@item 
@code{Annotated} cannot be used with an unpacked @ref{15e,,TypeVarTuple}:

@example
type Variadic[*Ts] = Annotated[*Ts, Ann1]  # NOT valid
@end example

This would be equivalent to:

@example
Annotated[T1, T2, T3, ..., Ann1]
@end example

where @code{T1}, @code{T2}, etc. are @ref{15c,,TypeVars}. This would be
invalid: only one type should be passed to Annotated.

@item 
By default, @ref{69c,,get_type_hints()} strips the metadata from annotations.
Pass @code{include_extras=True} to have the metadata preserved:

@example
>>> from typing import Annotated, get_type_hints
>>> def func(x: Annotated[int, "metadata"]) -> None: pass
...
>>> get_type_hints(func)
@{'x': <class 'int'>, 'return': <class 'NoneType'>@}
>>> get_type_hints(func, include_extras=True)
@{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>@}
@end example

@item 
At runtime, the metadata associated with an @code{Annotated} type can be
retrieved via the @code{__metadata__} attribute:

@example
>>> from typing import Annotated
>>> X = Annotated[int, "very", "important", "metadata"]
>>> X
typing.Annotated[int, 'very', 'important', 'metadata']
>>> X.__metadata__
('very', 'important', 'metadata')
@end example

@item 
At runtime, if you want to retrieve the original
type wrapped by @code{Annotated}, use the @code{__origin__} attribute:

@example
>>> from typing import Annotated, get_origin
>>> Password = Annotated[str, "secret"]
>>> Password.__origin__
<class 'str'>
@end example

Note that using @ref{a35,,get_origin()} will return @code{Annotated} itself:

@example
>>> get_origin(Password)
typing.Annotated
@end example
@end itemize


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 593

@item PEP 593@footnote{https://peps.python.org/pep-0593/} - Flexible function and variable annotations

The PEP introducing @code{Annotated} to the standard library.
@end table



Ajouté dans la version 3.9.

@end deffn

@geindex TypeIs (dans le module typing)
@anchor{library/typing typing TypeIs}@anchor{162}
@deffn {Données} typing.TypeIs

Special typing construct for marking user-defined type predicate functions.

@code{TypeIs} can be used to annotate the return type of a user-defined
type predicate function.  @code{TypeIs} only accepts a single type argument.
At runtime, functions marked this way should return a boolean and take at
least one positional argument.

@code{TypeIs} aims to benefit `type narrowing' -- a technique used by static
type checkers to determine a more precise type of an expression within a
program's code flow.  Usually type narrowing is done by analyzing
conditional code flow and applying the narrowing to a block of code.  The
conditional expression here is sometimes referred to as a "type predicate":

@example
def is_str(val: str | float):
    # "isinstance" type predicate
    if isinstance(val, str):
        # Type of `@w{`}val`@w{`} is narrowed to `@w{`}str`@w{`}
        ...
    else:
        # Else, type of `@w{`}val`@w{`} is narrowed to `@w{`}float`@w{`}.
        ...
@end example

Sometimes it would be convenient to use a user-defined boolean function
as a type predicate.  Such a function should use @code{TypeIs[...]} or
@ref{163,,TypeGuard} as its return type to alert static type checkers to
this intention.  @code{TypeIs} usually has more intuitive behavior than
@code{TypeGuard}, but it cannot be used when the input and output types
are incompatible (e.g., @code{list[object]} to @code{list[int]}) or when the
function does not return @code{True} for all instances of the narrowed type.

Using  @code{-> TypeIs[NarrowedType]} tells the static type checker that for a given
function:


@enumerate 

@item 
The return value is a boolean.

@item 
If the return value is @code{True}, the type of its argument
is the intersection of the argument's original type and @code{NarrowedType}.

@item 
If the return value is @code{False}, the type of its argument
is narrowed to exclude @code{NarrowedType}.
@end enumerate

Par exemple :

@example
from typing import assert_type, final, TypeIs

class Parent: pass
class Child(Parent): pass
@@final
class Unrelated: pass

def is_parent(val: object) -> TypeIs[Parent]:
    return isinstance(val, Parent)

def run(arg: Child | Unrelated):
    if is_parent(arg):
        # Type of `@w{`}arg`@w{`} is narrowed to the intersection
        # of `@w{`}Parent`@w{`} and `@w{`}Child`@w{`}, which is equivalent to
        # `@w{`}Child`@w{`}.
        assert_type(arg, Child)
    else:
        # Type of `@w{`}arg`@w{`} is narrowed to exclude `@w{`}Parent`@w{`},
        # so only `@w{`}Unrelated`@w{`} is left.
        assert_type(arg, Unrelated)
@end example

The type inside @code{TypeIs} must be consistent with the type of the
function's argument; if it is not, static type checkers will raise
an error.  An incorrectly written @code{TypeIs} function can lead to
unsound behavior in the type system; it is the user's responsibility
to write such functions in a type-safe manner.

If a @code{TypeIs} function is a class or instance method, then the type in
@code{TypeIs} maps to the type of the second parameter (after @code{cls} or
@code{self}).

In short, the form @code{def foo(arg: TypeA) -> TypeIs[TypeB]: ...},
means that if @code{foo(arg)} returns @code{True}, then @code{arg} is an instance
of @code{TypeB}, and if it returns @code{False}, it is not an instance of @code{TypeB}.

@code{TypeIs} also works with type variables.  For more information, see
@geindex Python Enhancement Proposals; PEP 742
PEP 742@footnote{https://peps.python.org/pep-0742/} (Narrowing types with @code{TypeIs}).


Ajouté dans la version 3.13.

@end deffn

@geindex TypeGuard (dans le module typing)
@anchor{library/typing typing TypeGuard}@anchor{163}
@deffn {Données} typing.TypeGuard

Special typing construct for marking user-defined type predicate functions.

Type predicate functions are user-defined functions that return whether their
argument is an instance of a particular type.
@code{TypeGuard} works similarly to @ref{162,,TypeIs}, but has subtly different
effects on type checking behavior (see below).

Using  @code{-> TypeGuard} tells the static type checker that for a given
function:


@enumerate 

@item 
The return value is a boolean.

@item 
If the return value is @code{True}, the type of its argument
is the type inside @code{TypeGuard}.
@end enumerate

@code{TypeGuard} also works with type variables.  See 
@geindex Python Enhancement Proposals; PEP 647
PEP 647@footnote{https://peps.python.org/pep-0647/} for more details.

Par exemple :

@example
def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '@w{'}'Determines whether all objects in the list are strings'@w{'}'
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # Type of `@w{`}val`@w{`} is narrowed to `@w{`}list[str]`@w{`}.
        print(" ".join(val))
    else:
        # Type of `@w{`}val`@w{`} remains as `@w{`}list[object]`@w{`}.
        print("Not a list of strings!")
@end example

@code{TypeIs} and @code{TypeGuard} differ in the following ways:


@itemize *

@item 
@code{TypeIs} requires the narrowed type to be a subtype of the input type, while
@code{TypeGuard} does not.  The main reason is to allow for things like
narrowing @code{list[object]} to @code{list[str]} even though the latter
is not a subtype of the former, since @code{list} is invariant.

@item 
When a @code{TypeGuard} function returns @code{True}, type checkers narrow the type of the
variable to exactly the @code{TypeGuard} type. When a @code{TypeIs} function returns @code{True},
type checkers can infer a more precise type combining the previously known type of the
variable with the @code{TypeIs} type. (Technically, this is known as an intersection type.)

@item 
When a @code{TypeGuard} function returns @code{False}, type checkers cannot narrow the type of
the variable at all. When a @code{TypeIs} function returns @code{False}, type checkers can narrow
the type of the variable to exclude the @code{TypeIs} type.
@end itemize


Ajouté dans la version 3.10.

@end deffn

@geindex Unpack (dans le module typing)
@anchor{library/typing typing Unpack}@anchor{15b8}
@deffn {Données} typing.Unpack

Typing operator to conceptually mark an object as having been unpacked.

For example, using the unpack operator @code{*} on a
@ref{3ebd,,type variable tuple} is equivalent to using @code{Unpack}
to mark the type variable tuple as having been unpacked:

@example
Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# Effectively does:
tup: tuple[Unpack[Ts]]
@end example

In fact, @code{Unpack} can be used interchangeably with @code{*} in the context
of @ref{15e,,typing.TypeVarTuple} and
@ref{366,,builtins.tuple} types. You might see @code{Unpack} being used
explicitly in older versions of Python, where @code{*} couldn't be used in
certain places:

@example
# In older versions of Python, TypeVarTuple and Unpack
# are located in the `typing_extensions` backports package.
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Syntax error on Python <= 3.10!
tup: tuple[Unpack[Ts]]  # Semantically equivalent, and backwards-compatible
@end example

@code{Unpack} can also be used along with @ref{161,,typing.TypedDict} for typing
@code{**kwargs} in a function signature:

@example
from typing import TypedDict, Unpack

class Movie(TypedDict):
    name: str
    year: int

# This function expects two keyword arguments - `name` of type `str`
# and `year` of type `int`.
def foo(**kwargs: Unpack[Movie]): ...
@end example

See 
@geindex Python Enhancement Proposals; PEP 692
PEP 692@footnote{https://peps.python.org/pep-0692/} for more details on using @code{Unpack} for @code{**kwargs} typing.


Ajouté dans la version 3.11.

@end deffn

@node Building generic types and type aliases,Other special directives,Special forms,Special typing primitives
@anchor{library/typing building-generic-types-and-type-aliases}@anchor{3ebe}
@subsubsection Building generic types and type aliases


The following classes should not be used directly as annotations.
Their intended purpose is to be building blocks
for creating generic types and type aliases.

These objects can be created through special syntax
(@ref{2b0,,type parameter lists} and the @ref{421,,type} statement).
For compatibility with Python 3.11 and earlier, they can also be created
without the dedicated syntax, as documented below.

@geindex Generic (classe dans typing)
@anchor{library/typing typing Generic}@anchor{15a1}
@deffn {Classe} typing.Generic

Classe de base abstraite pour les types génériques.

A generic type is typically declared by adding a list of type parameters
after the class name:

@example
class Mapping[KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.
@end example

Such a class implicitly inherits from @code{Generic}.
The runtime semantics of this syntax are discussed in the
@ref{43b,,Language Reference}.

Cette classe peut alors être utilisée comme suit :

@example
def lookup_name[X, Y](mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default
@end example

Here the brackets after the function name indicate a
@ref{43c,,generic function}.

For backwards compatibility, generic classes can also be
declared by explicitly inheriting from
@code{Generic}. In this case, the type parameters must be declared
separately:

@example
KT = TypeVar('KT')
VT = TypeVar('VT')

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.
@end example
@end deffn

@geindex TypeVar (classe dans typing)
@anchor{library/typing typevar}@anchor{3eb4}@anchor{library/typing typing TypeVar}@anchor{15c}
@deffn {Classe} typing.TypeVar (name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)

Variables de type.

The preferred way to construct a type variable is via the dedicated syntax
for @ref{43c,,generic functions},
@ref{43b,,generic classes}, and
@ref{43f,,generic type aliases}:

@example
class Sequence[T]:  # T is a TypeVar
    ...
@end example

This syntax can also be used to create bounded and constrained type
variables:

@example
class StrSequence[S: str]:  # S is a TypeVar with a `str` upper bound;
    ...                     # we can say that S is "bounded by `str`"


class StrOrBytesSequence[A: (str, bytes)]:  # A is a TypeVar constrained to str or bytes
    ...
@end example

However, if desired, reusable type variables can also be constructed manually, like so:

@example
T = TypeVar('T')  # Can be anything
S = TypeVar('S', bound=str)  # Can be any subtype of str
A = TypeVar('A', str, bytes)  # Must be exactly str or bytes
@end example

Type variables exist primarily for the benefit of static type
checkers.  They serve as the parameters for generic types as well
as for generic function and type alias definitions.
See @ref{15a1,,Generic} for more
information on generic types.  Generic functions work as follows:

@example
def repeat[T](x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n


def print_capitalized[S: str](x: S) -> S:
    """Print x capitalized, and return x."""
    print(x.capitalize())
    return x


def concatenate[A: (str, bytes)](x: A, y: A) -> A:
    """Add two strings or bytes objects together."""
    return x + y
@end example

Note that type variables can be `bounded', `constrained', or neither, but
cannot be both bounded `and' constrained.

The variance of type variables is inferred by type checkers when they are created
through the @ref{2b0,,type parameter syntax} or when
@code{infer_variance=True} is passed.
Manually created type variables may be explicitly marked covariant or contravariant by passing
@code{covariant=True} or @code{contravariant=True}.
By default, manually created type variables are invariant.
See 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} and 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/} for more details.

Bounded type variables and constrained type variables have different
semantics in several important ways. Using a `bounded' type variable means
that the @code{TypeVar} will be solved using the most specific type possible:

@example
x = print_capitalized('a string')
reveal_type(x)  # revealed type is str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # revealed type is StringSubclass

z = print_capitalized(45)  # error: int is not a subtype of str
@end example

The upper bound of a type variable can be a concrete type, abstract type
(ABC or Protocol), or even a union of types:

@example
# Can be anything with an __abs__ method
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))

U = TypeVar('U', bound=str|bytes)  # Can be any subtype of the union str|bytes
V = TypeVar('V', bound=SupportsAbs)  # Can be anything with an __abs__ method
@end example
@anchor{library/typing typing-constrained-typevar}@anchor{3eba}
Using a `constrained' type variable, however, means that the @code{TypeVar}
can only ever be solved as being exactly one of the constraints given:

@example
a = concatenate('one', 'two')
reveal_type(a)  # revealed type is str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # revealed type is str, despite StringSubclass being passed in

c = concatenate('one', b'two')  # error: type variable 'A' can be either str or bytes in a function call, but not both
@end example

At runtime, @code{isinstance(x, T)} will raise @ref{522,,TypeError}.

@geindex __name__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __name__}@anchor{3ebf}
@deffn {Attribut} __name__

The name of the type variable.
@end deffn

@geindex __covariant__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __covariant__}@anchor{3ec0}
@deffn {Attribut} __covariant__

Whether the type var has been explicitly marked as covariant.
@end deffn

@geindex __contravariant__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __contravariant__}@anchor{3ec1}
@deffn {Attribut} __contravariant__

Whether the type var has been explicitly marked as contravariant.
@end deffn

@geindex __infer_variance__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __infer_variance__}@anchor{3ec2}
@deffn {Attribut} __infer_variance__

Whether the type variable's variance should be inferred by type checkers.


Ajouté dans la version 3.12.

@end deffn

@geindex __bound__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __bound__}@anchor{3ec3}
@deffn {Attribut} __bound__

The upper bound of the type variable, if any.


Modifié dans la version 3.12: For type variables created through @ref{2b0,,type parameter syntax},
the bound is evaluated only when the attribute is accessed, not when
the type variable is created (see @ref{440,,Lazy evaluation}).

@end deffn

@geindex __constraints__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __constraints__}@anchor{3ec4}
@deffn {Attribut} __constraints__

A tuple containing the constraints of the type variable, if any.


Modifié dans la version 3.12: For type variables created through @ref{2b0,,type parameter syntax},
the constraints are evaluated only when the attribute is accessed, not when
the type variable is created (see @ref{440,,Lazy evaluation}).

@end deffn

@geindex __default__ (attribut typing.TypeVar)
@anchor{library/typing typing TypeVar __default__}@anchor{3ec5}
@deffn {Attribut} __default__

The default value of the type variable, or @ref{25f,,typing.NoDefault} if it
has no default.


Ajouté dans la version 3.13.

@end deffn

@geindex has_default() (méthode typing.TypeVar)
@anchor{library/typing typing TypeVar has_default}@anchor{3ec6}
@deffn {Méthode} has_default ()

Return whether or not the type variable has a default value. This is equivalent
to checking whether @ref{3ec5,,__default__} is not the @ref{25f,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{440,,lazily evaluated} default value.


Ajouté dans la version 3.13.

@end deffn


Modifié dans la version 3.12: Type variables can now be declared using the
@ref{2b0,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.
The @code{infer_variance} parameter was added.



Modifié dans la version 3.13: Support for default values was added.

@end deffn

@geindex TypeVarTuple (classe dans typing)
@anchor{library/typing typevartuple}@anchor{3ebd}@anchor{library/typing typing TypeVarTuple}@anchor{15e}
@deffn {Classe} typing.TypeVarTuple (name, *, default=typing.NoDefault)

Type variable tuple. A specialized form of @ref{3eb4,,type variable}
that enables `variadic' generics.

Type variable tuples can be declared in @ref{2b0,,type parameter lists}
using a single asterisk (@code{*}) before the name:

@example
def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])
@end example

Or by explicitly invoking the @code{TypeVarTuple} constructor:

@example
T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])
@end example

A normal type variable enables parameterization with a single type. A type
variable tuple, in contrast, allows parameterization with an
`arbitrary' number of types by acting like an `arbitrary' number of type
variables wrapped in a tuple. For example:

@example
# T is bound to int, Ts is bound to ()
# Return value is (1,), which has type tuple[int]
move_first_element_to_last(tup=(1,))

# T is bound to int, Ts is bound to (str,)
# Return value is ('spam', 1), which has type tuple[str, int]
move_first_element_to_last(tup=(1, 'spam'))

# T is bound to int, Ts is bound to (str, float)
# Return value is ('spam', 3.0, 1), which has type tuple[str, float, int]
move_first_element_to_last(tup=(1, 'spam', 3.0))

# This fails to type check (and fails at runtime)
# because tuple[()] is not compatible with tuple[T, *Ts]
# (at least one element is required)
move_first_element_to_last(tup=())
@end example

Note the use of the unpacking operator @code{*} in @code{tuple[T, *Ts]}.
Conceptually, you can think of @code{Ts} as a tuple of type variables
@code{(T1, T2, ...)}. @code{tuple[T, *Ts]} would then become
@code{tuple[T, *(T1, T2, ...)]}, which is equivalent to
@code{tuple[T, T1, T2, ...]}. (Note that in older versions of Python, you might
see this written using @ref{15b8,,Unpack} instead, as
@code{Unpack[Ts]}.)

Type variable tuples must `always' be unpacked. This helps distinguish type
variable tuples from normal type variables:

@example
x: Ts          # Not valid
x: tuple[Ts]   # Not valid
x: tuple[*Ts]  # The correct way to do it
@end example

Type variable tuples can be used in the same contexts as normal type
variables. For example, in class definitions, arguments, and return types:

@example
class Array[*Shape]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...
@end example

Type variable tuples can be happily combined with normal type variables:

@example
class Array[DType, *Shape]:  # This is fine
    pass

class Array2[*Shape, DType]:  # This would also be fine
    pass

class Height: ...
class Width: ...

float_array_1d: Array[float, Height] = Array()     # Totally fine
int_array_2d: Array[int, Height, Width] = Array()  # Yup, fine too
@end example

However, note that at most one type variable tuple may appear in a single
list of type arguments or type parameters:

@example
x: tuple[*Ts, *Ts]            # Not valid
class Array[*Shape, *Shape]:  # Not valid
    pass
@end example

Finally, an unpacked type variable tuple can be used as the type annotation
of @code{*args}:

@example
def call_soon[*Ts](
    callback: Callable[[*Ts], None],
    *args: *Ts
) -> None:
    ...
    callback(*args)
@end example

In contrast to non-unpacked annotations of @code{*args} - e.g. @code{*args: int},
which would specify that `all' arguments are @code{int} - @code{*args: *Ts}
enables reference to the types of the `individual' arguments in @code{*args}.
Here, this allows us to ensure the types of the @code{*args} passed
to @code{call_soon} match the types of the (positional) arguments of
@code{callback}.

See 
@geindex Python Enhancement Proposals; PEP 646
PEP 646@footnote{https://peps.python.org/pep-0646/} for more details on type variable tuples.

@geindex __name__ (attribut typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __name__}@anchor{3ec7}
@deffn {Attribut} __name__

The name of the type variable tuple.
@end deffn

@geindex __default__ (attribut typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple __default__}@anchor{3ec8}
@deffn {Attribut} __default__

The default value of the type variable tuple, or @ref{25f,,typing.NoDefault} if it
has no default.


Ajouté dans la version 3.13.

@end deffn

@geindex has_default() (méthode typing.TypeVarTuple)
@anchor{library/typing typing TypeVarTuple has_default}@anchor{3ec9}
@deffn {Méthode} has_default ()

Return whether or not the type variable tuple has a default value. This is equivalent
to checking whether @ref{3ec8,,__default__} is not the @ref{25f,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{440,,lazily evaluated} default value.


Ajouté dans la version 3.13.

@end deffn


Ajouté dans la version 3.11.



Modifié dans la version 3.12: Type variable tuples can now be declared using the
@ref{2b0,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



Modifié dans la version 3.13: Support for default values was added.

@end deffn

@geindex ParamSpec (classe dans typing)
@anchor{library/typing typing ParamSpec}@anchor{15d}
@deffn {Classe} typing.ParamSpec (name, *, bound=None, covariant=False, contravariant=False, default=typing.NoDefault)

Parameter specification variable.  A specialized version of
@ref{3eb4,,type variables}.

In @ref{2b0,,type parameter lists}, parameter specifications
can be declared with two asterisks (@code{**}):

@example
type IntFunc[**P] = Callable[P, int]
@end example

For compatibility with Python 3.11 and earlier, @code{ParamSpec} objects
can also be created as follows:

@example
P = ParamSpec('P')
@end example

Parameter specification variables exist primarily for the benefit of static
type checkers.  They are used to forward the parameter types of one
callable to another callable -- a pattern commonly found in higher order
functions and decorators.  They are only valid when used in @code{Concatenate},
or as the first argument to @code{Callable}, or as parameters for user-defined
Generics.  See @ref{15a1,,Generic} for more information on generic types.

For example, to add basic logging to a function, one can create a decorator
@code{add_logging} to log function calls.  The parameter specification variable
tells the type checker that the callable passed into the decorator and the
new callable returned by it have inter-dependent type parameters:

@example
from collections.abc import Callable
import logging

def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '@w{'}'A type-safe decorator to add logging to a function.'@w{'}'
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'@{f.__name__@} was called')
        return f(*args, **kwargs)
    return inner

@@add_logging
def add_two(x: float, y: float) -> float:
    '@w{'}'Add two numbers together.'@w{'}'
    return x + y
@end example

Without @code{ParamSpec}, the simplest way to annotate this previously was to
use a @ref{15c,,TypeVar} with upper bound @code{Callable[..., Any]}.  However this
causes two problems:


@enumerate 

@item 
The type checker can't type check the @code{inner} function because
@code{*args} and @code{**kwargs} have to be typed @ref{697,,Any}.

@item 
@ref{3eca,,cast()} may be required in the body of the @code{add_logging}
decorator when returning the @code{inner} function, or the static type
checker must be told to ignore the @code{return inner}.
@end enumerate

@geindex args (attribut typing.ParamSpec)
@anchor{library/typing typing ParamSpec args}@anchor{3ecb}
@deffn {Attribut} args
@end deffn

@geindex kwargs (attribut typing.ParamSpec)
@anchor{library/typing typing ParamSpec kwargs}@anchor{3ecc}
@deffn {Attribut} kwargs

Since @code{ParamSpec} captures both positional and keyword parameters,
@code{P.args} and @code{P.kwargs} can be used to split a @code{ParamSpec} into its
components.  @code{P.args} represents the tuple of positional parameters in a
given call and should only be used to annotate @code{*args}.  @code{P.kwargs}
represents the mapping of keyword parameters to their values in a given call,
and should be only be used to annotate @code{**kwargs}.  Both
attributes require the annotated parameter to be in scope. At runtime,
@code{P.args} and @code{P.kwargs} are instances respectively of
@ref{7b0,,ParamSpecArgs} and @ref{7b1,,ParamSpecKwargs}.
@end deffn

@geindex __name__ (attribut typing.ParamSpec)
@anchor{library/typing typing ParamSpec __name__}@anchor{3ecd}
@deffn {Attribut} __name__

The name of the parameter specification.
@end deffn

@geindex __default__ (attribut typing.ParamSpec)
@anchor{library/typing typing ParamSpec __default__}@anchor{3ece}
@deffn {Attribut} __default__

The default value of the parameter specification, or @ref{25f,,typing.NoDefault} if it
has no default.


Ajouté dans la version 3.13.

@end deffn

@geindex has_default() (méthode typing.ParamSpec)
@anchor{library/typing typing ParamSpec has_default}@anchor{3ecf}
@deffn {Méthode} has_default ()

Return whether or not the parameter specification has a default value. This is equivalent
to checking whether @ref{3ece,,__default__} is not the @ref{25f,,typing.NoDefault}
singleton, except that it does not force evaluation of the
@ref{440,,lazily evaluated} default value.


Ajouté dans la version 3.13.

@end deffn

Parameter specification variables created with @code{covariant=True} or
@code{contravariant=True} can be used to declare covariant or contravariant
generic types.  The @code{bound} argument is also accepted, similar to
@ref{15c,,TypeVar}.  However the actual semantics of these keywords are yet to
be decided.


Ajouté dans la version 3.10.



Modifié dans la version 3.12: Parameter specifications can now be declared using the
@ref{2b0,,type parameter} syntax introduced by 
@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}.



Modifié dans la version 3.13: Support for default values was added.


@cartouche
@quotation Note 
Only parameter specification variables defined in global scope can
be pickled.
@end quotation
@end cartouche


@subsubheading Voir aussi



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} -- Parameter Specification Variables (the PEP which introduced
@code{ParamSpec} and @code{Concatenate})

@item 
@ref{7ae,,Concatenate}

@item 
@ref{24af,,Annotating callable objects}
@end itemize

@end deffn

@geindex ParamSpecArgs (dans le module typing)
@geindex ParamSpecKwargs (dans le module typing)
@anchor{library/typing typing ParamSpecArgs}@anchor{7b0}
@deffn {Données} typing.ParamSpecArgs
@anchor{library/typing typing ParamSpecKwargs}@anchor{7b1}
@deffnx {Données} typing.ParamSpecKwargs

Arguments and keyword arguments attributes of a @ref{15d,,ParamSpec}. The
@code{P.args} attribute of a @code{ParamSpec} is an instance of @code{ParamSpecArgs},
and @code{P.kwargs} is an instance of @code{ParamSpecKwargs}. They are intended
for runtime introspection and have no special meaning to static type checkers.

Calling @ref{a35,,get_origin()} on either of these objects will return the
original @code{ParamSpec}:

@example
>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex TypeAliasType (classe dans typing)
@anchor{library/typing typing TypeAliasType}@anchor{43e}
@deffn {Classe} typing.TypeAliasType (name, value, *, type_params=())

The type of type aliases created through the @ref{421,,type} statement.

Example:

@example
>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>
@end example


Ajouté dans la version 3.12.


@geindex __name__ (attribut typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __name__}@anchor{3ed0}
@deffn {Attribut} __name__

The name of the type alias:

@example
>>> type Alias = int
>>> Alias.__name__
'Alias'
@end example
@end deffn

@geindex __module__ (attribut typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __module__}@anchor{3ed1}
@deffn {Attribut} __module__

The module in which the type alias was defined:

@example
>>> type Alias = int
>>> Alias.__module__
'__main__'
@end example
@end deffn

@geindex __type_params__ (attribut typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __type_params__}@anchor{3ed2}
@deffn {Attribut} __type_params__

The type parameters of the type alias, or an empty tuple if the alias is
not generic:

@example
>>> type ListOrSet[T] = list[T] | set[T]
>>> ListOrSet.__type_params__
(T,)
>>> type NotGeneric = int
>>> NotGeneric.__type_params__
()
@end example
@end deffn

@geindex __value__ (attribut typing.TypeAliasType)
@anchor{library/typing typing TypeAliasType __value__}@anchor{3ed3}
@deffn {Attribut} __value__

The type alias's value. This is @ref{440,,lazily evaluated},
so names used in the definition of the alias are not resolved until the
@code{__value__} attribute is accessed:

@example
>>> type Mutually = Recursive
>>> type Recursive = Mutually
>>> Mutually
Mutually
>>> Recursive
Recursive
>>> Mutually.__value__
Recursive
>>> Recursive.__value__
Mutually
@end example
@end deffn
@end deffn

@node Other special directives,,Building generic types and type aliases,Special typing primitives
@anchor{library/typing other-special-directives}@anchor{3ed4}
@subsubsection Other special directives


These functions and classes should not be used directly as annotations.
Their intended purpose is to be building blocks for creating and declaring
types.

@geindex NamedTuple (classe dans typing)
@anchor{library/typing typing NamedTuple}@anchor{2ad}
@deffn {Classe} typing.NamedTuple

Version typée de @ref{1c5,,collections.namedtuple()}.

Utilisation :

@example
class Employee(NamedTuple):
    name: str
    id: int
@end example

Ce qui est équivalent à :

@example
Employee = collections.namedtuple('Employee', ['name', 'id'])
@end example

Pour assigner une valeur par défaut à un champ, vous pouvez lui donner dans le corps de classe :

@example
class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3
@end example

Les champs avec une valeur par défaut doivent venir après tous les champs sans valeur par défaut.

The resulting class has an extra attribute @code{__annotations__} giving a
dict that maps the field names to the field types.  (The field names are in
the @code{_fields} attribute and the default values are in the
@code{_field_defaults} attribute, both of which are part of the @ref{1c5,,namedtuple()}
API.)

Les sous-classes de @code{NamedTuple} peuvent aussi avoir des `docstrings' et des méthodes :

@example
class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee @{self.name@}, id=@{self.id@}>'
@end example

@code{NamedTuple} subclasses can be generic:

@example
class Group[T](NamedTuple):
    key: T
    group: list[T]
@end example

Utilisation rétrocompatible :

@example
# For creating a generic NamedTuple on Python 3.11
T = TypeVar("T")

class Group(NamedTuple, Generic[T]):
    key: T
    group: list[T]

# A functional syntax is also supported
Employee = NamedTuple('Employee', [('name', str), ('id', int)])
@end example


Modifié dans la version 3.6: Ajout de la gestion de la syntaxe d'annotation variable de la 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}.



Modifié dans la version 3.6.1: Ajout de la prise en charge des valeurs par défaut, des méthodes et des chaînes de caractères `docstrings'.



Modifié dans la version 3.8: Les attributs @code{_field_types} et @code{__annotations__} sont maintenant des dictionnaires standards au lieu d'instances de @code{OrderedDict}.



Modifié dans la version 3.9: rend l'attribut @code{_field_types} obsolète en faveur de l'attribut plus standard @code{__annotations__} qui a la même information.



Modifié dans la version 3.11: Added support for generic namedtuples.



Deprecated since version 3.13, will be removed in version 3.15: The undocumented keyword argument syntax for creating NamedTuple classes
(@code{NT = NamedTuple("NT", x=int)}) is deprecated, and will be disallowed
in 3.15. Use the class-based syntax or the functional syntax instead.



Deprecated since version 3.13, will be removed in version 3.15: When using the functional syntax to create a NamedTuple class, failing to
pass a value to the 'fields' parameter (@code{NT = NamedTuple("NT")}) is
deprecated. Passing @code{None} to the 'fields' parameter
(@code{NT = NamedTuple("NT", None)}) is also deprecated. Both will be
disallowed in Python 3.15. To create a NamedTuple class with 0 fields,
use @code{class NT(NamedTuple): pass} or @code{NT = NamedTuple("NT", [])}.

@end deffn

@geindex NewType (classe dans typing)
@anchor{library/typing typing NewType}@anchor{ce3}
@deffn {Classe} typing.NewType (name, tp)

Helper class to create low-overhead @ref{3ea8,,distinct types}.

A @code{NewType} is considered a distinct type by a typechecker. At runtime,
however, calling a @code{NewType} returns its argument unchanged.

Utilisation :

@example
UserId = NewType('UserId', int)  # Declare the NewType "UserId"
first_user = UserId(1)  # "UserId" returns the argument unchanged at runtime
@end example

@geindex __module__ (attribut typing.NewType)
@anchor{library/typing typing NewType __module__}@anchor{3ed5}
@deffn {Attribut} __module__

The module in which the new type is defined.
@end deffn

@geindex __name__ (attribut typing.NewType)
@anchor{library/typing typing NewType __name__}@anchor{3ed6}
@deffn {Attribut} __name__

The name of the new type.
@end deffn

@geindex __supertype__ (attribut typing.NewType)
@anchor{library/typing typing NewType __supertype__}@anchor{3ed7}
@deffn {Attribut} __supertype__

The type that the new type is based on.
@end deffn


Ajouté dans la version 3.5.2.



Modifié dans la version 3.10: @code{NewType} is now a class rather than a function.

@end deffn

@geindex Protocol (classe dans typing)
@anchor{library/typing typing Protocol}@anchor{261}
@deffn {Classe} typing.Protocol (Generic)

Base class for protocol classes.

Protocol classes are defined like this:

@example
class Proto(Protocol):
    def meth(self) -> int:
        ...
@end example

Ces classes sont principalement utilisées avec les vérificateurs statiques de type qui reconnaissent les sous-types structurels (typage canard statique), par exemple :

@example
class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check
@end example

See 
@geindex Python Enhancement Proposals; PEP 544
PEP 544@footnote{https://peps.python.org/pep-0544/} for more details. Protocol classes decorated with
@ref{42c,,runtime_checkable()} (described later) act as simple-minded runtime
protocols that check only the presence of given attributes, ignoring their
type signatures.

Les classes de protocole peuvent être génériques, par exemple :

@example
class GenProto[T](Protocol):
    def meth(self) -> T:
        ...
@end example

In code that needs to be compatible with Python 3.11 or older, generic
Protocols can be written as follows:

@example
T = TypeVar("T")

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex runtime_checkable() (dans le module typing)
@anchor{library/typing typing runtime_checkable}@anchor{42c}
@deffn {Fonction} @@typing.runtime_checkable

Marquez une classe de protocole comme protocole d'exécution.

Such a protocol can be used with @ref{42b,,isinstance()} and @ref{7ab,,issubclass()}.
This raises @ref{522,,TypeError} when applied to a non-protocol class.  This
allows a simple-minded structural check, very similar to "one trick ponies"
in @ref{1e,,collections.abc} such as @ref{21d6,,Iterable}.  For example:

@example
@@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

@@runtime_checkable
class Named(Protocol):
    name: str

import threading
assert isinstance(threading.Thread(name='Bob'), Named)
@end example

@cartouche
@quotation Note 
@code{runtime_checkable()} will check only the presence of the required
methods or attributes, not their type signatures or types.
For example, @ref{b6f,,ssl.SSLObject}
is a class, therefore it passes an @ref{7ab,,issubclass()}
check against @ref{24af,,Callable}. However, the
@code{ssl.SSLObject.__init__} method exists only to raise a
@ref{522,,TypeError} with a more informative message, therefore making
it impossible to call (instantiate) @ref{b6f,,ssl.SSLObject}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
An @ref{42b,,isinstance()} check against a runtime-checkable protocol can be
surprisingly slow compared to an @code{isinstance()} check against
a non-protocol class. Consider using alternative idioms such as
@ref{4bb,,hasattr()} calls for structural checks in performance-sensitive
code.
@end quotation
@end cartouche


Ajouté dans la version 3.8.



Modifié dans la version 3.12: The internal implementation of @ref{42b,,isinstance()} checks against
runtime-checkable protocols now uses @ref{47e,,inspect.getattr_static()}
to look up attributes (previously, @ref{4bb,,hasattr()} was used).
As a result, 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.



Modifié dans la version 3.12: 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 @ref{42b,,isinstance()} checks comparing objects to the
protocol. See @ref{4ba,,"What's new in Python 3.12"}
for more details.

@end deffn

@geindex TypedDict (classe dans typing)
@anchor{library/typing typing TypedDict}@anchor{161}
@deffn {Classe} typing.TypedDict (dict)

Special construct to add type hints to a dictionary.
At runtime it is a plain @ref{253,,dict}.

@code{TypedDict} declares a dictionary type that expects all of its
instances to have a certain set of keys, where each key is
associated with a value of a consistent type. This expectation
is not checked at runtime but is only enforced by type checkers.
Usage:

@example
class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = @{'x': 1, 'y': 2, 'label': 'good'@}  # OK
b: Point2D = @{'z': 3, 'label': 'bad'@}           # Fails type check

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
@end example

An alternative way to create a @code{TypedDict} is by using
function-call syntax. The second argument must be a literal @ref{253,,dict}:

@example
Point2D = TypedDict('Point2D', @{'x': int, 'y': int, 'label': str@})
@end example

This functional syntax allows defining keys which are not valid
@ref{1e1a,,identifiers}, for example because they are
keywords or contain hyphens:

@example
# raises SyntaxError
class Point2D(TypedDict):
    in: int  # 'in' is a keyword
    x-y: int  # name with hyphens

# OK, functional syntax
Point2D = TypedDict('Point2D', @{'in': int, 'x-y': int@})
@end example

By default, all keys must be present in a @code{TypedDict}. It is possible to
mark individual keys as non-required using @ref{5af,,NotRequired}:

@example
class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# Alternative syntax
Point2D = TypedDict('Point2D', @{'x': int, 'y': int, 'label': NotRequired[str]@})
@end example

This means that a @code{Point2D} @code{TypedDict} can have the @code{label}
key omitted.

It is also possible to mark all keys as non-required by default
by specifying a totality of @code{False}:

@example
class Point2D(TypedDict, total=False):
    x: int
    y: int

# Alternative syntax
Point2D = TypedDict('Point2D', @{'x': int, 'y': int@}, total=False)
@end example

This means that a @code{Point2D} @code{TypedDict} can have any of the keys
omitted. A type checker is only expected to support a literal @code{False} or
@code{True} as the value of the @code{total} argument. @code{True} is the default,
and makes all items defined in the class body required.

Individual keys of a @code{total=False} @code{TypedDict} can be marked as
required using @ref{5ae,,Required}:

@example
class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# Alternative syntax
Point2D = TypedDict('Point2D', @{
    'x': Required[int],
    'y': Required[int],
    'label': str
@}, total=False)
@end example

It is possible for a @code{TypedDict} type to inherit from one or more other @code{TypedDict} types
using the class-based syntax.
Usage:

@example
class Point3D(Point2D):
    z: int
@end example

@code{Point3D} has three items: @code{x}, @code{y} and @code{z}. It is equivalent to this
definition:

@example
class Point3D(TypedDict):
    x: int
    y: int
    z: int
@end example

A @code{TypedDict} cannot inherit from a non-@code{TypedDict} class,
except for @ref{15a1,,Generic}. For example:

@example
class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # A non-TypedDict class

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # raises TypeError
@end example

A @code{TypedDict} can be generic:

@example
class Group[T](TypedDict):
    key: T
    group: list[T]
@end example

To create a generic @code{TypedDict} that is compatible with Python 3.11
or lower, inherit from @ref{15a1,,Generic} explicitly:

@example
T = TypeVar("T")

class Group(TypedDict, Generic[T]):
    key: T
    group: list[T]
@end example

A @code{TypedDict} can be introspected via annotations dicts
(see @ref{7c3,,Bonnes pratiques concernant les annotations} for more information on annotations best practices),
@ref{3ed8,,__total__}, @ref{3ed9,,__required_keys__}, and @ref{3eda,,__optional_keys__}.

@geindex __total__ (attribut typing.TypedDict)
@anchor{library/typing typing TypedDict __total__}@anchor{3ed8}
@deffn {Attribut} __total__

@code{Point2D.__total__} gives the value of the @code{total} argument.
Example:

@example
>>> from typing import TypedDict
>>> class Point2D(TypedDict): pass
>>> Point2D.__total__
True
>>> class Point2D(TypedDict, total=False): pass
>>> Point2D.__total__
False
>>> class Point3D(Point2D): pass
>>> Point3D.__total__
True
@end example

This attribute reflects `only' the value of the @code{total} argument
to the current @code{TypedDict} class, not whether the class is semantically
total. For example, a @code{TypedDict} with @code{__total__} set to @code{True} may
have keys marked with @ref{5af,,NotRequired}, or it may inherit from another
@code{TypedDict} with @code{total=False}. Therefore, it is generally better to use
@ref{3ed9,,__required_keys__} and @ref{3eda,,__optional_keys__} for introspection.
@end deffn

@geindex __required_keys__ (attribut typing.TypedDict)
@anchor{library/typing typing TypedDict __required_keys__}@anchor{3ed9}
@deffn {Attribut} __required_keys__


Ajouté dans la version 3.9.

@end deffn

@geindex __optional_keys__ (attribut typing.TypedDict)
@anchor{library/typing typing TypedDict __optional_keys__}@anchor{3eda}
@deffn {Attribut} __optional_keys__

@code{Point2D.__required_keys__} and @code{Point2D.__optional_keys__} return
@ref{5c4,,frozenset} objects containing required and non-required keys, respectively.

Keys marked with @ref{5ae,,Required} will always appear in @code{__required_keys__}
and keys marked with @ref{5af,,NotRequired} will always appear in @code{__optional_keys__}.

For backwards compatibility with Python 3.10 and below,
it is also possible to use inheritance to declare both required and
non-required keys in the same @code{TypedDict} . This is done by declaring a
@code{TypedDict} with one value for the @code{total} argument and then
inheriting from it in another @code{TypedDict} with a different value for
@code{total}:

@example
>>> class Point2D(TypedDict, total=False):
...     x: int
...     y: int
...
>>> class Point3D(Point2D):
...     z: int
...
>>> Point3D.__required_keys__ == frozenset(@{'z'@})
True
>>> Point3D.__optional_keys__ == frozenset(@{'x', 'y'@})
True
@end example


Ajouté dans la version 3.9.


@cartouche
@quotation Note 
If @code{from __future__ import annotations} is used or if annotations
are given as strings, annotations are not evaluated when the
@code{TypedDict} is defined. Therefore, the runtime introspection that
@code{__required_keys__} and @code{__optional_keys__} rely on may not work
properly, and the values of the attributes may be incorrect.
@end quotation
@end cartouche
@end deffn

Support for @ref{160,,ReadOnly} is reflected in the following attributes:

@geindex __readonly_keys__ (attribut typing.TypedDict)
@anchor{library/typing typing TypedDict __readonly_keys__}@anchor{3edb}
@deffn {Attribut} __readonly_keys__

A @ref{5c4,,frozenset} containing the names of all read-only keys. Keys
are read-only if they carry the @ref{160,,ReadOnly} qualifier.


Ajouté dans la version 3.13.

@end deffn

@geindex __mutable_keys__ (attribut typing.TypedDict)
@anchor{library/typing typing TypedDict __mutable_keys__}@anchor{3edc}
@deffn {Attribut} __mutable_keys__

A @ref{5c4,,frozenset} containing the names of all mutable keys. Keys
are mutable if they do not carry the @ref{160,,ReadOnly} qualifier.


Ajouté dans la version 3.13.

@end deffn

See 
@geindex Python Enhancement Proposals; PEP 589
PEP 589@footnote{https://peps.python.org/pep-0589/} for more examples and detailed rules of using @code{TypedDict}.


Ajouté dans la version 3.8.



Modifié dans la version 3.11: Added support for marking individual keys as @ref{5ae,,Required} or @ref{5af,,NotRequired}.
See 
@geindex Python Enhancement Proposals; PEP 655
PEP 655@footnote{https://peps.python.org/pep-0655/}.



Modifié dans la version 3.11: Added support for generic @code{TypedDict}s.



Modifié dans la version 3.13: Removed support for the keyword-argument method of creating @code{TypedDict}s.



Modifié dans la version 3.13: Support for the @ref{160,,ReadOnly} qualifier was added.



Deprecated since version 3.13, will be removed in version 3.15: When using the functional syntax to create a TypedDict class, failing to
pass a value to the 'fields' parameter (@code{TD = TypedDict("TD")}) is
deprecated. Passing @code{None} to the 'fields' parameter
(@code{TD = TypedDict("TD", None)}) is also deprecated. Both will be
disallowed in Python 3.15. To create a TypedDict class with 0 fields,
use @code{class TD(TypedDict): pass} or @code{TD = TypedDict("TD", @{@})}.

@end deffn

@node Protocoles<3>,ABCs for working with IO,Special typing primitives,Classe de données
@anchor{library/typing protocols}@anchor{3edd}
@subsubsection Protocoles


The following protocols are provided by the typing module. All are decorated
with @ref{42c,,@@runtime_checkable}.

@geindex SupportsAbs (classe dans typing)
@anchor{library/typing typing SupportsAbs}@anchor{3ede}
@deffn {Classe} typing.SupportsAbs

Une ABC avec une méthode abstraite @code{__abs__} qui est covariante dans son type de retour.
@end deffn

@geindex SupportsBytes (classe dans typing)
@anchor{library/typing typing SupportsBytes}@anchor{5d4}
@deffn {Classe} typing.SupportsBytes

Une ABC avec une méthode abstraite @code{__bytes__}.
@end deffn

@geindex SupportsComplex (classe dans typing)
@anchor{library/typing typing SupportsComplex}@anchor{5d3}
@deffn {Classe} typing.SupportsComplex

Une ABC avec une méthode abstraite @code{__complex__}.
@end deffn

@geindex SupportsFloat (classe dans typing)
@anchor{library/typing typing SupportsFloat}@anchor{3edf}
@deffn {Classe} typing.SupportsFloat

Une ABC avec une méthode abstraite @code{__float__}.
@end deffn

@geindex SupportsIndex (classe dans typing)
@anchor{library/typing typing SupportsIndex}@anchor{a34}
@deffn {Classe} typing.SupportsIndex

Une ABC avec une méthode abstraite @code{__index__}.


Ajouté dans la version 3.8.

@end deffn

@geindex SupportsInt (classe dans typing)
@anchor{library/typing typing SupportsInt}@anchor{a33}
@deffn {Classe} typing.SupportsInt

Une ABC avec une méthode abstraite @code{__int__}.
@end deffn

@geindex SupportsRound (classe dans typing)
@anchor{library/typing typing SupportsRound}@anchor{3ee0}
@deffn {Classe} typing.SupportsRound

Une ABC avec une méthode abstraite @code{__round__} qui est covariante dans son type de retour.
@end deffn

@node ABCs for working with IO,Functions and decorators,Protocoles<3>,Classe de données
@anchor{library/typing abcs-for-working-with-io}@anchor{3ee1}
@subsubsection ABCs for working with IO


@geindex IO (classe dans typing)
@geindex TextIO (classe dans typing)
@geindex BinaryIO (classe dans typing)
@anchor{library/typing typing IO}@anchor{715}
@deffn {Classe} typing.IO
@anchor{library/typing typing TextIO}@anchor{3ee2}
@deffnx {Classe} typing.TextIO
@anchor{library/typing typing BinaryIO}@anchor{3ee3}
@deffnx {Classe} typing.BinaryIO

Generic type @code{IO[AnyStr]} and its subclasses @code{TextIO(IO[str])}
and @code{BinaryIO(IO[bytes])}
represent the types of I/O streams such as returned by
@ref{505,,open()}.
@end deffn

@node Functions and decorators,Utilitaires d'introspection,ABCs for working with IO,Classe de données
@anchor{library/typing functions-and-decorators}@anchor{3ee4}
@subsubsection Functions and decorators


@geindex cast() (dans le module typing)
@anchor{library/typing typing cast}@anchor{3eca}
@deffn {Fonction} typing.cast (typ, val)

Convertit une valeur en un type.

Ceci renvoie la valeur inchangée. Pour le vérificateur de types, cela signifie que la valeur de retour a le type désigné mais, à l'exécution, intentionnellement, rien n'est vérifié (afin que cela soit aussi rapide que possible).
@end deffn

@geindex assert_type() (dans le module typing)
@anchor{library/typing typing assert_type}@anchor{696}
@deffn {Fonction} typing.assert_type (val, typ, /)

Vérifie que `val' est bien du type `typ'.

At runtime this does nothing: it returns the first argument unchanged with no
checks or side effects, no matter the actual type of the argument.

When a static type checker encounters a call to @code{assert_type()}, it
emits an error if the value is not of the specified type:

@example
def greet(name: str) -> None:
    assert_type(name, str)  # OK, inferred type of `name` is `str`
    assert_type(name, int)  # type checker error
@end example

Cette fonction permet de s'assurer de la compréhension du vérificateur de type d'un script par rapport aux intentions du développeur :

@example
def complex_function(arg: object):
    # Do some complex type-narrowing logic,
    # after which we hope the inferred type will be `int`
    ...
    # Test whether the type checker correctly understands our function
    assert_type(arg, int)
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex assert_never() (dans le module typing)
@anchor{library/typing typing assert_never}@anchor{692}
@deffn {Fonction} typing.assert_never (arg, /)

Demande une confirmation de la part du vérificateur statique de type qu'une ligne de code est inaccessible.

Example:

@example
def int_or_str(arg: int | str) -> None:
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _ as unreachable:
            assert_never(unreachable)
@end example

Here, the annotations allow the type checker to infer that the
last case can never execute, because @code{arg} is either
an @ref{254,,int} or a @ref{435,,str}, and both options are covered by
earlier cases.

If a type checker finds that a call to @code{assert_never()} is
reachable, it will emit an error. For example, if the type annotation
for @code{arg} was instead @code{int | str | float}, the type checker would
emit an error pointing out that @code{unreachable} is of type @ref{2eb,,float}.
For a call to @code{assert_never} to pass type checking, the inferred type of
the argument passed in must be the bottom type, @ref{693,,Never}, and nothing
else.

Une erreur est levé si la fonction est appelé lors de l'exécution.


@subsubheading Voir aussi


Unreachable Code and Exhaustiveness Checking@footnote{https://typing.readthedocs.io/en/latest/guides/unreachable.html} has more
information about exhaustiveness checking with static typing.



Ajouté dans la version 3.11.

@end deffn

@geindex reveal_type() (dans le module typing)
@anchor{library/typing typing reveal_type}@anchor{695}
@deffn {Fonction} typing.reveal_type (obj, /)

Ask a static type checker to reveal the inferred type of an expression.

When a static type checker encounters a call to this function,
it emits a diagnostic with the inferred type of the argument. For example:

@example
x: int = 1
reveal_type(x)  # Revealed type is "builtins.int"
@end example

Cela est utile afin de comprendre comment le vérificateur de types va traiter un bout de code précis.

At runtime, this function prints the runtime type of its argument to
@ref{926,,sys.stderr} and returns the argument unchanged (allowing the call to
be used within an expression):

@example
x = reveal_type(1)  # prints "Runtime type is int"
print(x)  # prints "1"
@end example

Note that the runtime type may be different from (more or less specific
than) the type statically inferred by a type checker.

Most type checkers support @code{reveal_type()} anywhere, even if the
name is not imported from @code{typing}. Importing the name from
@code{typing}, however, allows your code to run without runtime errors and
communicates intent more clearly.


Ajouté dans la version 3.11.

@end deffn

@geindex dataclass_transform() (dans le module typing)
@anchor{library/typing typing dataclass_transform}@anchor{4bd}
@deffn {Fonction} @@typing.dataclass_transform (*, eq_default=True, order_default=False, kw_only_default=False, frozen_default=False, field_specifiers=(), **kwargs)

Decorator to mark an object as providing
@ref{1c6,,dataclass}-like behavior.

@code{dataclass_transform} may be used to
decorate a class, metaclass, or a function that is itself a decorator.
The presence of @code{@@dataclass_transform()} tells a static type checker that the
decorated object performs runtime "magic" that
transforms a class in a similar way to
@ref{1c6,,@@dataclasses.dataclass}.

Example usage with a decorator function:

@example
@@dataclass_transform()
def create_model[T](cls: type[T]) -> type[T]:
    ...
    return cls

@@create_model
class CustomerModel:
    id: int
    name: str
@end example

Avec une classe de base :

@example
@@dataclass_transform()
class ModelBase: ...

class CustomerModel(ModelBase):
    id: int
    name: str
@end example

Avec une métaclasse :

@example
@@dataclass_transform()
class ModelMeta(type): ...

class ModelBase(metaclass=ModelMeta): ...

class CustomerModel(ModelBase):
    id: int
    name: str
@end example

Les classes @code{CustomerModel} définis ci-dessus sont traitées par les vérificateurs de type de la même que les classes créées avec @ref{1c6,,@@dataclasses.dataclass}. Par exemple, les vérificateurs de type déduisent que ces classes possèdent une méthode @code{__init__} acceptant @code{id} et @code{name} comme arguments.

Les arguments booléens suivants sont acceptés,les vérificateurs de type supposent qu'ils ont le même effet qu'ils auraient eu sur le décorateur @ref{1c6,,@@dataclasses.dataclass} : @code{init}, @code{eq}, @code{order}, @code{unsafe_hash}, @code{frozen}, @code{match_args}, @code{kw_only}, et @code{slots}. Il est possible d'évaluer statiquement les valeurs de ces arguments (@code{True} or @code{False}).

Les arguments du décorateur @code{dataclass_transform} permettent de personnaliser le comportement par défaut de la classe, métaclasse ou fonction décorée :

@*Paramètres: 

@itemize *

@item 
@code{eq_default} (@ref{451,,bool}) -- Indicates whether the @code{eq} parameter is assumed to be
@code{True} or @code{False} if it is omitted by the caller.
Defaults to @code{True}.

@item 
@code{order_default} (@ref{451,,bool}) -- Indicates whether the @code{order} parameter is
assumed to be @code{True} or @code{False} if it is omitted by the caller.
Defaults to @code{False}.

@item 
@code{kw_only_default} (@ref{451,,bool}) -- Indicates whether the @code{kw_only} parameter is
assumed to be @code{True} or @code{False} if it is omitted by the caller.
Defaults to @code{False}.

@item 
@code{frozen_default} (@ref{451,,bool}) -- 
Indicates whether the @code{frozen} parameter is
assumed to be @code{True} or @code{False} if it is omitted by the caller.
Defaults to @code{False}.


Ajouté dans la version 3.12.



@item 
@code{field_specifiers} (@ref{366,,tuple}@code{[}@ref{7d4,,Callable}@code{[}@code{...}@code{, }@code{Any}@code{]}@code{, }@code{...}@code{]}) -- Specifies a static list of supported classes
or functions that describe fields, similar to @ref{19ae,,dataclasses.field()}.
Defaults to @code{()}.

@item 
@code{**kwargs} (@code{Any}) -- D'autres arguments sont acceptés afin d'autoriser de futurs possibles extensions.
@end itemize


Type checkers recognize the following optional parameters on field
specifiers:
`Recognised parameters for field specifiers'



@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Parameter name

@tab

Description

@item

@code{init}

@tab

Indicates whether the field should be included in the
synthesized @code{__init__} method. If unspecified, @code{init} defaults to
@code{True}.

@item

@code{default}

@tab

Provides the default value for the field.

@item

@code{default_factory}

@tab

Provides a runtime callback that returns the
default value for the field. If neither @code{default} nor
@code{default_factory} are specified, the field is assumed to have no
default value and must be provided a value when the class is
instantiated.

@item

@code{factory}

@tab

An alias for the @code{default_factory} parameter on field specifiers.

@item

@code{kw_only}

@tab

Indicates whether the field should be marked as
keyword-only. If @code{True}, the field will be keyword-only. If
@code{False}, it will not be keyword-only. If unspecified, the value of
the @code{kw_only} parameter on the object decorated with
@code{dataclass_transform} will be used, or if that is unspecified, the
value of @code{kw_only_default} on @code{dataclass_transform} will be used.

@item

@code{alias}

@tab

Provides an alternative name for the field. This alternative
name is used in the synthesized @code{__init__} method.

@end multitable


Lors de l'exécution, les arguments de ce décorateur sont enregistrés au sein de l'attribut @code{__dataclass_transform__} de l'objet décoré. Il n'y pas d'autre effet à l'exécution.

See 
@geindex Python Enhancement Proposals; PEP 681
PEP 681@footnote{https://peps.python.org/pep-0681/} for more details.


Ajouté dans la version 3.11.

@end deffn

@geindex overload() (dans le module typing)
@anchor{library/typing overload}@anchor{3eab}@anchor{library/typing typing overload}@anchor{3ee5}
@deffn {Fonction} @@typing.overload

Decorator for creating overloaded functions and methods.

The @code{@@overload} decorator allows describing functions and methods
that support multiple different combinations of argument types. A series
of @code{@@overload}-decorated definitions must be followed by exactly one
non-@code{@@overload}-decorated definition (for the same function/method).

@code{@@overload}-decorated definitions are for the benefit of the
type checker only, since they will be overwritten by the
non-@code{@@overload}-decorated definition. The non-@code{@@overload}-decorated
definition, meanwhile, will be used at
runtime but should be ignored by a type checker.  At runtime, calling
an @code{@@overload}-decorated function directly will raise
@ref{225,,NotImplementedError}.

An example of overload that gives a more
precise type than can be expressed using a union or a type variable:

@example
@@overload
def process(response: None) -> None:
    ...
@@overload
def process(response: int) -> tuple[int, str]:
    ...
@@overload
def process(response: bytes) -> str:
    ...
def process(response):
    ...  # actual implementation goes here
@end example

See 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} for more details and comparison with other typing semantics.


Modifié dans la version 3.11: Les fonctions surchargées peuvent maintenant être inspectées durant l'exécution via @ref{699,,get_overloads()}.

@end deffn

@geindex get_overloads() (dans le module typing)
@anchor{library/typing typing get_overloads}@anchor{699}
@deffn {Fonction} typing.get_overloads (func)

Return a sequence of @ref{3ee5,,@@overload}-decorated definitions for
`func'.

`func' is the function object for the implementation of the
overloaded function. For example, given the definition of @code{process} in
the documentation for @ref{3ee5,,@@overload},
@code{get_overloads(process)} will return a sequence of three function objects
for the three defined overloads. If called on a function with no overloads,
@code{get_overloads()} returns an empty sequence.

@code{get_overloads()} peut être utilisé afin d'inspecter une fonction surchargée durant l'exécution.


Ajouté dans la version 3.11.

@end deffn

@geindex clear_overloads() (dans le module typing)
@anchor{library/typing typing clear_overloads}@anchor{69a}
@deffn {Fonction} typing.clear_overloads ()

Clear all registered overloads in the internal registry.

This can be used to reclaim the memory used by the registry.


Ajouté dans la version 3.11.

@end deffn

@geindex final() (dans le module typing)
@anchor{library/typing typing final}@anchor{698}
@deffn {Fonction} @@typing.final

Decorator to indicate final methods and final classes.

Decorating a method with @code{@@final} indicates to a type checker that the
method cannot be overridden in a subclass. Decorating a class with @code{@@final}
indicates that it cannot be subclassed.

Par exemple :

@example
class Base:
    @@final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Error reported by type checker
        ...

@@final
class Leaf:
    ...
class Other(Leaf):  # Error reported by type checker
    ...
@end example

Ces propriétés ne sont pas vérifiées à l'exécution. Voir la 
@geindex Python Enhancement Proposals; PEP 591
PEP 591@footnote{https://peps.python.org/pep-0591/} pour plus de détails.


Ajouté dans la version 3.8.



Modifié dans la version 3.11: The decorator will now attempt to set a @code{__final__} attribute to @code{True}
on the decorated object. Thus, a check like
@code{if getattr(obj, "__final__", False)} can be used at runtime
to determine whether an object @code{obj} has been marked as final.
If the decorated object does not support setting attributes,
the decorator returns the object unchanged without raising an exception.

@end deffn

@geindex no_type_check() (dans le module typing)
@anchor{library/typing typing no_type_check}@anchor{69f}
@deffn {Fonction} @@typing.no_type_check

Décorateur pour indiquer que les annotations ne sont pas des indications de type.

This works as a class or function @ref{71b,,decorator}.  With a class, it
applies recursively to all methods and classes defined in that class
(but not to methods defined in its superclasses or subclasses). Type
checkers will ignore all annotations in a function or class with this
decorator.

@code{@@no_type_check} mutates the decorated object in place.
@end deffn

@geindex no_type_check_decorator() (dans le module typing)
@anchor{library/typing typing no_type_check_decorator}@anchor{2ae}
@deffn {Fonction} @@typing.no_type_check_decorator

Décorateur pour donner à un autre décorateur l'effet @ref{69f,,no_type_check()}.

Ceci enveloppe le décorateur avec quelque chose qui enveloppe la fonction décorée dans @ref{69f,,no_type_check()}.


Deprecated since version 3.13, will be removed in version 3.15: No type checker ever added support for @code{@@no_type_check_decorator}. It
is therefore deprecated, and will be removed in Python 3.15.

@end deffn

@geindex override() (dans le module typing)
@anchor{library/typing typing override}@anchor{434}
@deffn {Fonction} @@typing.override

Decorator to indicate that a method in a subclass is intended to override a
method or attribute in a superclass.

Type checkers should emit an error if a method decorated with @code{@@override}
does not, in fact, override anything.
This helps prevent bugs that may occur when a base class is changed without
an equivalent change to a child class.

For example:

@example
class Base:
    def log_status(self) -> None:
        ...

class Sub(Base):
    @@override
    def log_status(self) -> None:  # Okay: overrides Base.log_status
        ...

    @@override
    def done(self) -> None:  # Error reported by type checker
        ...
@end example

There is no runtime checking of this property.

The decorator will attempt to set an @code{__override__} attribute to @code{True} on
the decorated object. Thus, a check like
@code{if getattr(obj, "__override__", False)} can be used at runtime to determine
whether an object @code{obj} has been marked as an override.  If the decorated object
does not support setting attributes, the decorator returns the object unchanged
without raising an exception.

See 
@geindex Python Enhancement Proposals; PEP 698
PEP 698@footnote{https://peps.python.org/pep-0698/} for more details.


Ajouté dans la version 3.12.

@end deffn

@geindex type_check_only() (dans le module typing)
@anchor{library/typing typing type_check_only}@anchor{3ee6}
@deffn {Fonction} @@typing.type_check_only

Decorator to mark a class or function as unavailable at runtime.

Ce décorateur n'est pas disponible à l'exécution. Il est principalement destiné à marquer les classes qui sont définies dans des fichiers séparés d'annotations de type (`type stub file', en anglais) si une implémentation renvoie une instance d'une classe privée :

@example
@@type_check_only
class Response:  # private or not available at runtime
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...
@end example

Notez qu'il n'est pas recommandé de renvoyer les instances des classes privées. Il est généralement préférable de rendre ces classes publiques.
@end deffn

@node Utilitaires d'introspection,Constante,Functions and decorators,Classe de données
@anchor{library/typing introspection-helpers}@anchor{3ee7}
@subsubsection Utilitaires d'introspection


@geindex get_type_hints() (dans le module typing)
@anchor{library/typing typing get_type_hints}@anchor{69c}
@deffn {Fonction} typing.get_type_hints (obj, globalns=None, localns=None, include_extras=False)

Renvoie un dictionnaire contenant des annotations de type pour une fonction, une méthode, un module ou un objet de classe.

This is often the same as @code{obj.__annotations__}, but this function makes
the following changes to the annotations dictionary:


@itemize *

@item 
Forward references encoded as string literals or @ref{17d1,,ForwardRef}
objects are handled by evaluating them in `globalns', `localns', and
(where applicable) `obj''s @ref{2b0,,type parameter} namespace.
If `globalns' or `localns' is not given, appropriate namespace
dictionaries are inferred from `obj'.

@item 
@code{None} is replaced with @ref{83c,,types.NoneType}.

@item 
If @ref{69f,,@@no_type_check} has been applied to `obj', an
empty dictionary is returned.

@item 
If `obj' is a class @code{C}, the function returns a dictionary that merges
annotations from @code{C}'s base classes with those on @code{C} directly. This
is done by traversing @ref{1eae,,C.__mro__} and iteratively
combining
@code{__annotations__} dictionaries. Annotations on classes appearing
earlier in the @ref{2109,,method resolution order} always take precedence over
annotations on classes appearing later in the method resolution order.

@item 
The function recursively replaces all occurrences of @code{Annotated[T, ...]}
with @code{T}, unless `include_extras' is set to @code{True} (see
@ref{92a,,Annotated} for more information).
@end itemize

See also @ref{7fd,,inspect.get_annotations()}, a lower-level function that
returns annotations more directly.

@cartouche
@quotation Note 
If any forward references in the annotations of `obj' are not resolvable
or are not valid Python code, this function will raise an exception
such as @ref{428,,NameError}. For example, this can happen with imported
@ref{43d,,type aliases} that include forward references,
or with names imported under @ref{ce2,,if TYPE_CHECKING}.
@end quotation
@end cartouche


Modifié dans la version 3.9: Added @code{include_extras} parameter as part of 
@geindex Python Enhancement Proposals; PEP 593
PEP 593@footnote{https://peps.python.org/pep-0593/}.
See the documentation on @ref{92a,,Annotated} for more information.



Modifié dans la version 3.11: Avant, @code{Optional[t]} était ajouté pour les annotations de fonctions et de méthodes dans le cas où une valeur par défaut était égal à @code{None}. Maintenant, les annotations sont renvoyées inchangées.

@end deffn

@geindex get_origin() (dans le module typing)
@anchor{library/typing typing get_origin}@anchor{a35}
@deffn {Fonction} typing.get_origin (tp)

Get the unsubscripted version of a type: for a typing object of the form
@code{X[Y, Z, ...]} return @code{X}.

If @code{X} is a typing-module alias for a builtin or
@ref{1d,,collections} class, it will be normalized to the original class.
If @code{X} is an instance of @ref{7b0,,ParamSpecArgs} or @ref{7b1,,ParamSpecKwargs},
return the underlying @ref{15d,,ParamSpec}.
Return @code{None} for unsupported objects.

Examples:

@example
assert get_origin(str) is None
assert get_origin(Dict[str, int]) is dict
assert get_origin(Union[int, str]) is Union
assert get_origin(Annotated[str, "metadata"]) is Annotated
P = ParamSpec('P')
assert get_origin(P.args) is P
assert get_origin(P.kwargs) is P
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex get_args() (dans le module typing)
@anchor{library/typing typing get_args}@anchor{86a}
@deffn {Fonction} typing.get_args (tp)

Get type arguments with all substitutions performed: for a typing object
of the form @code{X[Y, Z, ...]} return @code{(Y, Z, ...)}.

If @code{X} is a union or @ref{83f,,Literal} contained in another
generic type, the order of @code{(Y, Z, ...)} may be different from the order
of the original arguments @code{[Y, Z, ...]} due to type caching.
Return @code{()} for unsupported objects.

Examples:

@example
assert get_args(int) == ()
assert get_args(Dict[int, str]) == (int, str)
assert get_args(Union[int, str]) == (int, str)
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex get_protocol_members() (dans le module typing)
@anchor{library/typing typing get_protocol_members}@anchor{260}
@deffn {Fonction} typing.get_protocol_members (tp)

Return the set of members defined in a @ref{261,,Protocol}.

@example
>>> from typing import Protocol, get_protocol_members
>>> class P(Protocol):
...     def a(self) -> str: ...
...     b: int
>>> get_protocol_members(P) == frozenset(@{'a', 'b'@})
True
@end example

Raise @ref{522,,TypeError} for arguments that are not Protocols.


Ajouté dans la version 3.13.

@end deffn

@geindex is_protocol() (dans le module typing)
@anchor{library/typing typing is_protocol}@anchor{262}
@deffn {Fonction} typing.is_protocol (tp)

Determine if a type is a @ref{261,,Protocol}.

Par exemple :

@example
class P(Protocol):
    def a(self) -> str: ...
    b: int

is_protocol(P)    # => True
is_protocol(int)  # => False
@end example


Ajouté dans la version 3.13.

@end deffn

@geindex is_typeddict() (dans le module typing)
@anchor{library/typing typing is_typeddict}@anchor{840}
@deffn {Fonction} typing.is_typeddict (tp)

Vérifier si un type est un @ref{161,,TypedDict}.

For example:

@example
class Film(TypedDict):
    title: str
    year: int

assert is_typeddict(Film)
assert not is_typeddict(list | str)

# TypedDict is a factory for creating typed dicts,
# not a typed dict itself
assert not is_typeddict(TypedDict)
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex ForwardRef (classe dans typing)
@anchor{library/typing typing ForwardRef}@anchor{17d1}
@deffn {Classe} typing.ForwardRef

Class used for internal typing representation of string forward references.

For example, @code{List["SomeClass"]} is implicitly transformed into
@code{List[ForwardRef("SomeClass")]}.  @code{ForwardRef} should not be instantiated by
a user, but may be used by introspection tools.

@cartouche
@quotation Note 
Les types 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} tels que @code{list["SomeClass"]} ne seront pas implicitement transformés en @code{list[ForwardRef("SomeClass")]} et ne seront donc pas automatiquement résolus en @code{list[SomeClass]}.
@end quotation
@end cartouche


Ajouté dans la version 3.7.4.

@end deffn

@geindex NoDefault (dans le module typing)
@anchor{library/typing typing NoDefault}@anchor{25f}
@deffn {Données} typing.NoDefault

A sentinel object used to indicate that a type parameter has no default
value. For example:

@example
>>> T = TypeVar("T")
>>> T.__default__ is typing.NoDefault
True
>>> S = TypeVar("S", default=None)
>>> S.__default__ is None
True
@end example


Ajouté dans la version 3.13.

@end deffn

@node Constante,Deprecated aliases,Utilitaires d'introspection,Classe de données
@anchor{library/typing constant}@anchor{3ee8}
@subsubsection Constante


@geindex TYPE_CHECKING (dans le module typing)
@anchor{library/typing typing TYPE_CHECKING}@anchor{ce2}
@deffn {Données} typing.TYPE_CHECKING

A special constant that is assumed to be @code{True} by 3rd party static
type checkers. It is @code{False} at runtime.

Utilisation :

@example
if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()
@end example

The first type annotation must be enclosed in quotes, making it a
"forward reference", to hide the @code{expensive_mod} reference from the
interpreter runtime.  Type annotations for local variables are not
evaluated, so the second annotation does not need to be enclosed in quotes.

@cartouche
@quotation Note 
Si @code{from __future__ import annotations} est utilisé, les annotations ne sont pas évaluées au moment de la définition de fonction. Elles sont alors stockées comme des chaînes de caractères dans @code{__annotations__}, ce qui rend inutile l'utilisation de guillemets autour de l'annotation (Voir 
@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/}).
@end quotation
@end cartouche


Ajouté dans la version 3.5.2.

@end deffn
@anchor{library/typing generic-concrete-collections}@anchor{3ee9}
@node Deprecated aliases,,Constante,Classe de données
@anchor{library/typing deprecated-aliases}@anchor{3eea}@anchor{library/typing id6}@anchor{3eeb}
@subsubsection Deprecated aliases


This module defines several deprecated aliases to pre-existing
standard library classes. These were originally included in the typing
module in order to support parameterizing these generic classes using @code{[]}.
However, the aliases became redundant in Python 3.9 when the
corresponding pre-existing classes were enhanced to support @code{[]} (see
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}).

The redundant types are deprecated as of Python 3.9. However, while the aliases
may be removed at some point, removal of these aliases is not currently
planned. As such, no deprecation warnings are currently issued by the
interpreter for these aliases.

If at some point it is decided to remove these deprecated aliases, a
deprecation warning will be issued by the interpreter for at least two releases
prior to removal. The aliases are guaranteed to remain in the typing module
without deprecation warnings until at least Python 3.14.

Type checkers are encouraged to flag uses of the deprecated types if the
program they are checking targets a minimum Python version of 3.9 or newer.

@menu
* Aliases to built-in types:: 
* Aliases to types in collections:: 
* Aliases to other concrete types:: 
* Aliases to container ABCs in collections.abc: Aliases to container ABCs in collections abc. 
* Aliases to asynchronous ABCs in collections.abc: Aliases to asynchronous ABCs in collections abc. 
* Aliases to other ABCs in collections.abc: Aliases to other ABCs in collections abc. 
* Aliases to contextlib ABCs:: 

@end menu

@node Aliases to built-in types,Aliases to types in collections,,Deprecated aliases
@anchor{library/typing aliases-to-built-in-types}@anchor{3eec}@anchor{library/typing corresponding-to-built-in-types}@anchor{3eed}
@subsubsection Aliases to built-in types


@geindex Dict (classe dans typing)
@anchor{library/typing typing Dict}@anchor{3eee}
@deffn {Classe} typing.Dict (dict, MutableMapping[KT, VT])

Deprecated alias to @ref{253,,dict}.

Note that to annotate arguments, it is preferred
to use an abstract collection type such as @ref{8b7,,Mapping}
rather than to use @ref{253,,dict} or @code{typing.Dict}.


Obsolète depuis la version 3.9: @ref{253,,builtins.dict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex List (classe dans typing)
@anchor{library/typing typing List}@anchor{3eef}
@deffn {Classe} typing.List (list, MutableSequence[T])

Deprecated alias to @ref{5fc,,list}.

Note that to annotate arguments, it is preferred
to use an abstract collection type such as
@ref{11a1,,Sequence} or @ref{21d6,,Iterable}
rather than to use @ref{5fc,,list} or @code{typing.List}.


Obsolète depuis la version 3.9: @ref{5fc,,builtins.list} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Set (classe dans typing)
@anchor{library/typing typing Set}@anchor{3ef0}
@deffn {Classe} typing.Set (set, MutableSet[T])

Deprecated alias to @ref{5c3,,builtins.set}.

Note that to annotate arguments, it is preferred
to use an abstract collection type such as @ref{21ce,,collections.abc.Set}
rather than to use @ref{5c3,,set} or @ref{3ef0,,typing.Set}.


Obsolète depuis la version 3.9: @ref{5c3,,builtins.set} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex FrozenSet (classe dans typing)
@anchor{library/typing typing FrozenSet}@anchor{3ef1}
@deffn {Classe} typing.FrozenSet (frozenset, AbstractSet[T_co])

Deprecated alias to @ref{5c4,,builtins.frozenset}.


Obsolète depuis la version 3.9: @ref{5c4,,builtins.frozenset}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Tuple (dans le module typing)
@anchor{library/typing typing Tuple}@anchor{3ef2}
@deffn {Données} typing.Tuple

Deprecated alias for @ref{366,,tuple}.

@ref{366,,tuple} and @code{Tuple} are special-cased in the type system; see
@ref{3ead,,Annotating tuples} for more details.


Obsolète depuis la version 3.9: @ref{366,,builtins.tuple} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Type (classe dans typing)
@anchor{library/typing typing Type}@anchor{3eb1}
@deffn {Classe} typing.Type (Generic[CT_co])

Deprecated alias to @ref{d36,,type}.

See @ref{3eb0,,The type of class objects} for details on using @ref{d36,,type} or
@code{typing.Type} in type annotations.


Ajouté dans la version 3.5.2.



Obsolète depuis la version 3.9: @ref{d36,,builtins.type} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@node Aliases to types in collections,Aliases to other concrete types,Aliases to built-in types,Deprecated aliases
@anchor{library/typing aliases-to-types-in-collections}@anchor{3ef3}@anchor{library/typing corresponding-to-types-in-collections}@anchor{3ef4}
@subsubsection Aliases to types in @code{collections}


@geindex DefaultDict (classe dans typing)
@anchor{library/typing typing DefaultDict}@anchor{3ef5}
@deffn {Classe} typing.DefaultDict (collections.defaultdict, MutableMapping[KT, VT])

Deprecated alias to @ref{119a,,collections.defaultdict}.


Ajouté dans la version 3.5.2.



Obsolète depuis la version 3.9: @ref{119a,,collections.defaultdict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex OrderedDict (classe dans typing)
@anchor{library/typing typing OrderedDict}@anchor{3ef6}
@deffn {Classe} typing.OrderedDict (collections.OrderedDict, MutableMapping[KT, VT])

Deprecated alias to @ref{5c5,,collections.OrderedDict}.


Ajouté dans la version 3.7.2.



Obsolète depuis la version 3.9: @ref{5c5,,collections.OrderedDict} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex ChainMap (classe dans typing)
@anchor{library/typing typing ChainMap}@anchor{3ef7}
@deffn {Classe} typing.ChainMap (collections.ChainMap, MutableMapping[KT, VT])

Deprecated alias to @ref{c0a,,collections.ChainMap}.


Ajouté dans la version 3.6.1.



Obsolète depuis la version 3.9: @ref{c0a,,collections.ChainMap} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Counter (classe dans typing)
@anchor{library/typing typing Counter}@anchor{3ef8}
@deffn {Classe} typing.Counter (collections.Counter, Dict[T, int])

Deprecated alias to @ref{107b,,collections.Counter}.


Ajouté dans la version 3.6.1.



Obsolète depuis la version 3.9: @ref{107b,,collections.Counter} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Deque (classe dans typing)
@anchor{library/typing typing Deque}@anchor{3ef9}
@deffn {Classe} typing.Deque (deque, MutableSequence[T])

Deprecated alias to @ref{5c6,,collections.deque}.


Ajouté dans la version 3.6.1.



Obsolète depuis la version 3.9: @ref{5c6,,collections.deque} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@node Aliases to other concrete types,Aliases to container ABCs in collections abc,Aliases to types in collections,Deprecated aliases
@anchor{library/typing aliases-to-other-concrete-types}@anchor{3efa}@anchor{library/typing other-concrete-types}@anchor{3efb}
@subsubsection Aliases to other concrete types


@geindex Pattern (classe dans typing)
@geindex Match (classe dans typing)
@anchor{library/typing typing Pattern}@anchor{716}
@deffn {Classe} typing.Pattern
@anchor{library/typing typing Match}@anchor{3efc}
@deffnx {Classe} typing.Match

Deprecated aliases corresponding to the return types from
@ref{bc1,,re.compile()} and @ref{120b,,re.match()}.

These types (and the corresponding functions) are generic over
@ref{2af,,AnyStr}. @code{Pattern} can be specialised as @code{Pattern[str]} or
@code{Pattern[bytes]}; @code{Match} can be specialised as @code{Match[str]} or
@code{Match[bytes]}.


Obsolète depuis la version 3.9: Classes @code{Pattern} and @code{Match} from @ref{b8,,re} now support @code{[]}.
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Text (classe dans typing)
@anchor{library/typing typing Text}@anchor{300}
@deffn {Classe} typing.Text

Deprecated alias for @ref{435,,str}.

@code{Text} is provided to supply a forward
compatible path for Python 2 code: in Python 2, @code{Text} is an alias for
@code{unicode}.

Utilisez @code{Text} pour indiquer qu'une valeur doit contenir une chaîne Unicode d'une manière compatible avec Python 2 et Python 3 :

@example
def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'
@end example


Ajouté dans la version 3.5.2.



Obsolète depuis la version 3.11: Python 2 is no longer supported, and most type checkers also no longer
support type checking Python 2 code. Removal of the alias is not
currently planned, but users are encouraged to use
@ref{435,,str} instead of @code{Text}.

@end deffn
@anchor{library/typing abstract-base-classes}@anchor{3efd}
@node Aliases to container ABCs in collections abc,Aliases to asynchronous ABCs in collections abc,Aliases to other concrete types,Deprecated aliases
@anchor{library/typing aliases-to-container-abcs-in-collections-abc}@anchor{3efe}@anchor{library/typing corresponding-to-collections-in-collections-abc}@anchor{3eff}
@subsubsection Aliases to container ABCs in @code{collections.abc}


@geindex AbstractSet (classe dans typing)
@anchor{library/typing typing AbstractSet}@anchor{3f00}
@deffn {Classe} typing.AbstractSet (Collection[T_co])

Deprecated alias to @ref{21ce,,collections.abc.Set}.


Obsolète depuis la version 3.9: @ref{21ce,,collections.abc.Set} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex ByteString (classe dans typing)
@anchor{library/typing typing ByteString}@anchor{2d2}
@deffn {Classe} typing.ByteString (Sequence[int])

This type represents the types @ref{1bd,,bytes}, @ref{528,,bytearray},
and @ref{452,,memoryview} of byte sequences.


Deprecated since version 3.9, will be removed in version 3.14: Prefer @ref{2c1,,collections.abc.Buffer}, or a union like @code{bytes | bytearray | memoryview}.

@end deffn

@geindex Collection (classe dans typing)
@anchor{library/typing typing Collection}@anchor{ce1}
@deffn {Classe} typing.Collection (Sized, Iterable[T_co], Container[T_co])

Deprecated alias to @ref{c76,,collections.abc.Collection}.


Ajouté dans la version 3.6.



Obsolète depuis la version 3.9: @ref{c76,,collections.abc.Collection} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Container (classe dans typing)
@anchor{library/typing typing Container}@anchor{3f01}
@deffn {Classe} typing.Container (Generic[T_co])

Deprecated alias to @ref{21d8,,collections.abc.Container}.


Obsolète depuis la version 3.9: @ref{21d8,,collections.abc.Container} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex ItemsView (classe dans typing)
@anchor{library/typing typing ItemsView}@anchor{3f02}
@deffn {Classe} typing.ItemsView (MappingView, AbstractSet[tuple[KT_co, VT_co]])

Deprecated alias to @ref{21dc,,collections.abc.ItemsView}.


Obsolète depuis la version 3.9: @ref{21dc,,collections.abc.ItemsView} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex KeysView (classe dans typing)
@anchor{library/typing typing KeysView}@anchor{3f03}
@deffn {Classe} typing.KeysView (MappingView, AbstractSet[KT_co])

Deprecated alias to @ref{21db,,collections.abc.KeysView}.


Obsolète depuis la version 3.9: @ref{21db,,collections.abc.KeysView} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Mapping (classe dans typing)
@anchor{library/typing typing Mapping}@anchor{3f04}
@deffn {Classe} typing.Mapping (Collection[KT], Generic[KT, VT_co])

Deprecated alias to @ref{8b7,,collections.abc.Mapping}.


Obsolète depuis la version 3.9: @ref{8b7,,collections.abc.Mapping} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex MappingView (classe dans typing)
@anchor{library/typing typing MappingView}@anchor{3f05}
@deffn {Classe} typing.MappingView (Sized)

Deprecated alias to @ref{21da,,collections.abc.MappingView}.


Obsolète depuis la version 3.9: @ref{21da,,collections.abc.MappingView} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex MutableMapping (classe dans typing)
@anchor{library/typing typing MutableMapping}@anchor{3f06}
@deffn {Classe} typing.MutableMapping (Mapping[KT, VT])

Deprecated alias to @ref{1090,,collections.abc.MutableMapping}.


Obsolète depuis la version 3.9: @ref{1090,,collections.abc.MutableMapping}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex MutableSequence (classe dans typing)
@anchor{library/typing typing MutableSequence}@anchor{3f07}
@deffn {Classe} typing.MutableSequence (Sequence[T])

Deprecated alias to @ref{19f,,collections.abc.MutableSequence}.


Obsolète depuis la version 3.9: @ref{19f,,collections.abc.MutableSequence}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex MutableSet (classe dans typing)
@anchor{library/typing typing MutableSet}@anchor{3f08}
@deffn {Classe} typing.MutableSet (AbstractSet[T])

Deprecated alias to @ref{21d9,,collections.abc.MutableSet}.


Obsolète depuis la version 3.9: @ref{21d9,,collections.abc.MutableSet} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Sequence (classe dans typing)
@anchor{library/typing typing Sequence}@anchor{3f09}
@deffn {Classe} typing.Sequence (Reversible[T_co], Collection[T_co])

Deprecated alias to @ref{11a1,,collections.abc.Sequence}.


Obsolète depuis la version 3.9: @ref{11a1,,collections.abc.Sequence} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex ValuesView (classe dans typing)
@anchor{library/typing typing ValuesView}@anchor{3f0a}
@deffn {Classe} typing.ValuesView (MappingView, Collection[_VT_co])

Deprecated alias to @ref{21dd,,collections.abc.ValuesView}.


Obsolète depuis la version 3.9: @ref{21dd,,collections.abc.ValuesView} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@node Aliases to asynchronous ABCs in collections abc,Aliases to other ABCs in collections abc,Aliases to container ABCs in collections abc,Deprecated aliases
@anchor{library/typing aliases-to-asynchronous-abcs-in-collections-abc}@anchor{3f0b}@anchor{library/typing asynchronous-programming}@anchor{3f0c}
@subsubsection Aliases to asynchronous ABCs in @code{collections.abc}


@geindex Coroutine (classe dans typing)
@anchor{library/typing typing Coroutine}@anchor{18d7}
@deffn {Classe} typing.Coroutine (Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])

Deprecated alias to @ref{dca,,collections.abc.Coroutine}.

See @ref{24b0,,Annotating generators and coroutines}
for details on using @ref{dca,,collections.abc.Coroutine}
and @code{typing.Coroutine} in type annotations.


Ajouté dans la version 3.5.3.



Obsolète depuis la version 3.9: @ref{dca,,collections.abc.Coroutine} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex AsyncGenerator (classe dans typing)
@anchor{library/typing typing AsyncGenerator}@anchor{15b5}
@deffn {Classe} typing.AsyncGenerator (AsyncIterator[YieldType], Generic[YieldType, SendType])

Deprecated alias to @ref{c78,,collections.abc.AsyncGenerator}.

See @ref{24b0,,Annotating generators and coroutines}
for details on using @ref{c78,,collections.abc.AsyncGenerator}
and @code{typing.AsyncGenerator} in type annotations.


Ajouté dans la version 3.6.1.



Obsolète depuis la version 3.9: @ref{c78,,collections.abc.AsyncGenerator}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.



Modifié dans la version 3.13: The @code{SendType} parameter now has a default.

@end deffn

@geindex AsyncIterable (classe dans typing)
@anchor{library/typing typing AsyncIterable}@anchor{3f0d}
@deffn {Classe} typing.AsyncIterable (Generic[T_co])

Deprecated alias to @ref{dcc,,collections.abc.AsyncIterable}.


Ajouté dans la version 3.5.2.



Obsolète depuis la version 3.9: @ref{dcc,,collections.abc.AsyncIterable} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex AsyncIterator (classe dans typing)
@anchor{library/typing typing AsyncIterator}@anchor{3f0e}
@deffn {Classe} typing.AsyncIterator (AsyncIterable[T_co])

Deprecated alias to @ref{dcb,,collections.abc.AsyncIterator}.


Ajouté dans la version 3.5.2.



Obsolète depuis la version 3.9: @ref{dcb,,collections.abc.AsyncIterator} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Awaitable (classe dans typing)
@anchor{library/typing typing Awaitable}@anchor{3f0f}
@deffn {Classe} typing.Awaitable (Generic[T_co])

Deprecated alias to @ref{dc9,,collections.abc.Awaitable}.


Ajouté dans la version 3.5.2.



Obsolète depuis la version 3.9: @ref{dc9,,collections.abc.Awaitable} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@node Aliases to other ABCs in collections abc,Aliases to contextlib ABCs,Aliases to asynchronous ABCs in collections abc,Deprecated aliases
@anchor{library/typing aliases-to-other-abcs-in-collections-abc}@anchor{3f10}@anchor{library/typing corresponding-to-other-types-in-collections-abc}@anchor{3f11}
@subsubsection Aliases to other ABCs in @code{collections.abc}


@geindex Iterable (classe dans typing)
@anchor{library/typing typing Iterable}@anchor{3f12}
@deffn {Classe} typing.Iterable (Generic[T_co])

Deprecated alias to @ref{21d6,,collections.abc.Iterable}.


Obsolète depuis la version 3.9: @ref{21d6,,collections.abc.Iterable} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Iterator (classe dans typing)
@anchor{library/typing typing Iterator}@anchor{3f13}
@deffn {Classe} typing.Iterator (Iterable[T_co])

Deprecated alias to @ref{21d7,,collections.abc.Iterator}.


Obsolète depuis la version 3.9: @ref{21d7,,collections.abc.Iterator} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Callable (dans le module typing)
@anchor{library/typing typing Callable}@anchor{7af}
@deffn {Données} typing.Callable

Deprecated alias to @ref{7d4,,collections.abc.Callable}.

See @ref{24af,,Annotating callable objects} for details on how to use
@ref{7d4,,collections.abc.Callable} and @code{typing.Callable} in type annotations.


Obsolète depuis la version 3.9: @ref{7d4,,collections.abc.Callable} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.



Modifié dans la version 3.10: @code{Callable} prend désormais en charge @ref{15d,,ParamSpec} et @ref{7ae,,Concatenate}. Voir 
@geindex Python Enhancement Proposals; PEP 612
PEP 612@footnote{https://peps.python.org/pep-0612/} pour plus de détails.

@end deffn

@geindex Generator (classe dans typing)
@anchor{library/typing typing Generator}@anchor{15b4}
@deffn {Classe} typing.Generator (Iterator[YieldType], Generic[YieldType, SendType, ReturnType])

Deprecated alias to @ref{dc8,,collections.abc.Generator}.

See @ref{24b0,,Annotating generators and coroutines}
for details on using @ref{dc8,,collections.abc.Generator}
and @code{typing.Generator} in type annotations.


Obsolète depuis la version 3.9: @ref{dc8,,collections.abc.Generator} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.



Modifié dans la version 3.13: Default values for the send and return types were added.

@end deffn

@geindex Hashable (classe dans typing)
@anchor{library/typing typing Hashable}@anchor{4dd}
@deffn {Classe} typing.Hashable

Deprecated alias to @ref{4df,,collections.abc.Hashable}.


Obsolète depuis la version 3.12: Use @ref{4df,,collections.abc.Hashable} directly instead.

@end deffn

@geindex Reversible (classe dans typing)
@anchor{library/typing typing Reversible}@anchor{3f14}
@deffn {Classe} typing.Reversible (Iterable[T_co])

Deprecated alias to @ref{c77,,collections.abc.Reversible}.


Obsolète depuis la version 3.9: @ref{c77,,collections.abc.Reversible} now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.

@end deffn

@geindex Sized (classe dans typing)
@anchor{library/typing typing Sized}@anchor{4de}
@deffn {Classe} typing.Sized

Deprecated alias to @ref{4e0,,collections.abc.Sized}.


Obsolète depuis la version 3.12: Use @ref{4e0,,collections.abc.Sized} directly instead.

@end deffn

@node Aliases to contextlib ABCs,,Aliases to other ABCs in collections abc,Deprecated aliases
@anchor{library/typing aliases-to-contextlib-abcs}@anchor{3f15}@anchor{library/typing context-manager-types}@anchor{3f16}
@subsubsection Aliases to @code{contextlib} ABCs


@geindex ContextManager (classe dans typing)
@anchor{library/typing typing ContextManager}@anchor{c7c}
@deffn {Classe} typing.ContextManager (Generic[T_co, ExitT_co])

Deprecated alias to @ref{c7b,,contextlib.AbstractContextManager}.

The first type parameter, @code{T_co}, represents the type returned by
the @ref{5b2,,__enter__()} method. The optional second type parameter, @code{ExitT_co},
which defaults to @code{bool | None}, represents the type returned by the
@ref{12de,,__exit__()} method.


Ajouté dans la version 3.5.4.



Obsolète depuis la version 3.9: @ref{c7b,,contextlib.AbstractContextManager}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.



Modifié dans la version 3.13: Added the optional second type parameter, @code{ExitT_co}.

@end deffn

@geindex AsyncContextManager (classe dans typing)
@anchor{library/typing typing AsyncContextManager}@anchor{15b2}
@deffn {Classe} typing.AsyncContextManager (Generic[T_co, AExitT_co])

Deprecated alias to @ref{b19,,contextlib.AbstractAsyncContextManager}.

The first type parameter, @code{T_co}, represents the type returned by
the @ref{1f53,,__aenter__()} method. The optional second type parameter, @code{AExitT_co},
which defaults to @code{bool | None}, represents the type returned by the
@ref{15b3,,__aexit__()} method.


Ajouté dans la version 3.6.2.



Obsolète depuis la version 3.9: @ref{b19,,contextlib.AbstractAsyncContextManager}
now supports subscripting (@code{[]}).
See 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/} and @ref{69d,,Type Alias générique}.



Modifié dans la version 3.13: Added the optional second type parameter, @code{AExitT_co}.

@end deffn

@node Étapes d'Obsolescence des Fonctionnalités Majeures,,Classe de données,typing — Prise en charge des annotations de type
@anchor{library/typing deprecation-timeline-of-major-features}@anchor{3f17}
@subsubsection Étapes d'Obsolescence des Fonctionnalités Majeures


Certaines fonctionnalités dans @code{typing} sont obsolètes et peuvent être supprimées dans une future version de Python. Le tableau suivant résume les principales dépréciations. Celui-ci peut changer et toutes les dépréciations ne sont pas listées.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Fonctionnalité

@tab

Obsolète en

@tab

Suppression prévue

@tab

PEP/issue

@item

Versions de typage des collections standards

@tab

3.9

@tab

Undecided (see @ref{3eea,,Deprecated aliases} for more information)

@tab

@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}

@item

@ref{2d2,,typing.ByteString}

@tab

3.9

@tab

3.14

@tab

gh-91896@footnote{https://github.com/python/cpython/issues/91896}

@item

@ref{300,,typing.Text}

@tab

3.11

@tab

Non défini

@tab

gh-92332@footnote{https://github.com/python/cpython/issues/92332}

@item

@ref{4dd,,typing.Hashable} and @ref{4de,,typing.Sized}

@tab

3.12

@tab

Non défini

@tab

gh-94309@footnote{https://github.com/python/cpython/issues/94309}

@item

@ref{7b3,,typing.TypeAlias}

@tab

3.12

@tab

Non défini

@tab

@geindex Python Enhancement Proposals; PEP 695
PEP 695@footnote{https://peps.python.org/pep-0695/}

@item

@ref{2ae,,@@typing.no_type_check_decorator}

@tab

3.13

@tab

3.15

@tab

gh-106309@footnote{https://github.com/python/cpython/issues/106309}

@item

@ref{2af,,typing.AnyStr}

@tab

3.13

@tab

3.18

@tab

gh-105578@footnote{https://github.com/python/cpython/issues/105578}

@end multitable


@node pydoc --- Documentation generator and online help system,Python Development Mode,typing — Prise en charge des annotations de type,Outils de développement
@anchor{library/pydoc doc}@anchor{3f18}@anchor{library/pydoc module-pydoc}@anchor{b4}@anchor{library/pydoc pydoc-documentation-generator-and-online-help-system}@anchor{3f19}
@subsection @code{pydoc} --- Documentation generator and online help system


@geindex module; pydoc

`Code source :' Lib/pydoc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pydoc.py}

@geindex documentation;generation
@geindex documentation;online
@geindex help;online


__________________________________________________________________


The @code{pydoc} module automatically generates documentation from Python
modules.  The documentation can be presented as pages of text on the console,
served to a web browser, or saved to HTML files.

For modules, classes, functions and methods, the displayed documentation is
derived from the docstring (i.e. the @ref{915,,__doc__} attribute) of the object,
and recursively of its documentable members.  If there is no docstring,
@code{pydoc} tries to obtain a description from the block of comment lines just
above the definition of the class, function or method in the source file, or at
the top of the module (see @ref{154e,,inspect.getcomments()}).

The built-in function @ref{8c4,,help()} invokes the online help system in the
interactive interpreter, which uses @code{pydoc} to generate its documentation
as text on the console.  The same text documentation can also be viewed from
outside the Python interpreter by running @code{pydoc} as a script at the
operating system's command prompt. For example, running

@example
python -m pydoc sys
@end example

dans un terminal, cela affiche la documentation du module @ref{d8,,sys} dans un style similaire à la commande Unix @code{man}. On peut passer comme argument à @code{pydoc} le nom d’une fonction, d’un module, d’un paquet, ou une référence pointant vers une classe, une méthode, ou une fonction dans un module ou dans un paquet. Si l’argument passé à @code{pydoc} est un chemin (c.-à-d. qu’il contient des séparateurs de chemin tels que la barre oblique @code{/} dans Unix), et fait référence à un fichier source Python existant, alors la documentation est générée pour ce fichier.

@cartouche
@quotation Note 
In order to find objects and their documentation, @code{pydoc} imports the
module(s) to be documented.  Therefore, any code on module level will be
executed on that occasion.  Use an @code{if __name__ == '__main__':} guard to
only execute code when a file is invoked as a script and not just imported.
@end quotation
@end cartouche

When printing output to the console, @code{pydoc} attempts to paginate the
output for easier reading.  If either the 
@geindex MANPAGER
@geindex variable d'environnement; MANPAGER
@code{MANPAGER} or the
@geindex PAGER
@geindex variable d'environnement; PAGER
@code{PAGER} environment variable is set, @code{pydoc} will use its
value as a pagination program. When both are set, 
@geindex MANPAGER
@geindex variable d'environnement; MANPAGER
@code{MANPAGER} is used.

Ajouter une option @code{-w} avant l’argument entraine l’enregistrement de la documentation HTML générée dans un fichier du répertoire courant au lieu de l’afficher dans la console.

Ajouter une option @code{-w} avant l’argument cherche les lignes de résumé de tous les modules disponibles pour le mot clé donné comme argument, ceci à la manière de la commande Unix @code{man}. Les lignes de résumé d’un module sont les premières lignes de sa `docstring'.

You can also use @code{pydoc} to start an HTTP server on the local machine
that will serve documentation to visiting web browsers.  @code{python -m pydoc -p 1234}
will start a HTTP server on port 1234, allowing you to browse the
documentation at @code{http://localhost:1234/} in your preferred web browser.
Specifying @code{0} as the port number will select an arbitrary unused port.

@code{python -m pydoc -n <hostname>} will start the server listening at the given
hostname.  By default the hostname is 'localhost' but if you want the server to
be reached from other machines, you may want to change the host name that the
server responds to.  During development this is especially useful if you want
to run pydoc from within a container.

@code{python -m pydoc -b} will start the server and additionally open a web
browser to a module index page.  Each served page has a navigation bar at the
top where you can `Get' help on an individual item, `Search' all modules with a
keyword in their synopsis line, and go to the `Module index', `Topics' and
`Keywords' pages.

Quand @code{pydoc} génère de la documentation, il utilise l’environnement et le chemin courant pour localiser les modules. Ainsi, en invoquant les documents @code{pydoc spam} en précisant la version du module, vous obtenez le même résultat qu’en lançant l’interpréteur Python et en tapant la commande @code{import spam}.

Module docs for core modules are assumed to reside in
@code{https://docs.python.org/X.Y/library/} where @code{X} and @code{Y} are the
major and minor version numbers of the Python interpreter.  This can
be overridden by setting the @code{PYTHONDOCS} environment variable
to a different URL or to a local directory containing the Library
Reference Manual pages.


Modifié dans la version 3.2: Ajout de l’option @code{-b}.



Modifié dans la version 3.3: Suppression de l’option @code{-g}.



Modifié dans la version 3.4: @code{pydoc} now uses @ref{722,,inspect.signature()} rather than
@ref{723,,inspect.getfullargspec()} to extract signature information from
callables.



Modifié dans la version 3.7: Ajout de l’option @code{-n}.


@node Python Development Mode,doctest — Exemples de tests interactifs en Python,pydoc --- Documentation generator and online help system,Outils de développement
@anchor{library/devmode doc}@anchor{3f1a}@anchor{library/devmode devmode}@anchor{1f5}@anchor{library/devmode python-development-mode}@anchor{3f1b}
@subsection Python Development Mode



Ajouté dans la version 3.7.


The Python Development Mode introduces additional runtime checks that are too
expensive to be enabled by default. It should not be more verbose than the
default if the code is correct; new warnings are only emitted when an issue is
detected.

It can be enabled using the @ref{175,,-X dev} command line option or by
setting the 
@geindex PYTHONDEVMODE
@geindex variable d'environnement; PYTHONDEVMODE
@ref{adb,,PYTHONDEVMODE} environment variable to @code{1}.

See also @ref{1f6,,Python debug build}.

@menu
* Effects of the Python Development Mode:: 
* ResourceWarning Example:: 
* Bad file descriptor error example:: 

@end menu

@node Effects of the Python Development Mode,ResourceWarning Example,,Python Development Mode
@anchor{library/devmode effects-of-the-python-development-mode}@anchor{3f1c}
@subsubsection Effects of the Python Development Mode


Enabling the Python Development Mode is similar to the following command, but
with additional effects described below:

@example
PYTHONMALLOC=debug PYTHONASYNCIODEBUG=1 python -W default -X faulthandler
@end example

Effects of the Python Development Mode:


@itemize *

@item 
Add @code{default} @ref{1cc5,,warning filter}. The
following warnings are shown:


@itemize *

@item 
@ref{1a3,,DeprecationWarning}

@item 
@ref{4e4,,ImportWarning}

@item 
@ref{8b5,,PendingDeprecationWarning}

@item 
@ref{241,,ResourceWarning}
@end itemize

Normally, the above warnings are filtered by the default @ref{1cc5,,warning filters}.

It behaves as if the @ref{8b4,,-W default} command line option is used.

Use the @ref{8b4,,-W error} command line option or set the
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS} environment variable to @code{error} to treat warnings
as errors.

@item 
Install debug hooks on memory allocators to check for:


@itemize *

@item 
Buffer underflow

@item 
Buffer overflow

@item 
Memory allocator API violation

@item 
Unsafe usage of the GIL
@end itemize

See the @ref{c58,,PyMem_SetupDebugHooks()} C function.

It behaves as if the 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable is set to
@code{debug}.

To enable the Python Development Mode without installing debug hooks on
memory allocators, set the 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable to
@code{default}.

@item 
Call @ref{c8c,,faulthandler.enable()} at Python startup to install handlers for
the @ref{1cd5,,SIGSEGV}, @ref{1cd6,,SIGFPE},
@ref{1cd7,,SIGABRT}, @ref{1cd8,,SIGBUS} and
@ref{1cd9,,SIGILL} signals to dump the Python traceback on a crash.

It behaves as if the @ref{175,,-X faulthandler} command line option is
used or if the 
@geindex PYTHONFAULTHANDLER
@geindex variable d'environnement; PYTHONFAULTHANDLER
@ref{1069,,PYTHONFAULTHANDLER} environment variable is set to
@code{1}.

@item 
Enable @ref{1cdb,,asyncio debug mode}. For example,
@ref{a,,asyncio} checks for coroutines that were not awaited and logs them.

It behaves as if the 
@geindex PYTHONASYNCIODEBUG
@geindex variable d'environnement; PYTHONASYNCIODEBUG
@ref{1cda,,PYTHONASYNCIODEBUG} environment variable is set
to @code{1}.

@item 
Check the `encoding' and `errors' arguments for string encoding and decoding
operations. Examples: @ref{505,,open()}, @ref{8c2,,str.encode()} and
@ref{8c3,,bytes.decode()}.

By default, for best performance, the `errors' argument is only checked at
the first encoding/decoding error and the `encoding' argument is sometimes
ignored for empty strings.

@item 
The @ref{1f2,,io.IOBase} destructor logs @code{close()} exceptions.

@item 
Set the @ref{1a2f,,dev_mode} attribute of @ref{677,,sys.flags} to
@code{True}.
@end itemize

The Python Development Mode does not enable the @ref{fe,,tracemalloc} module by
default, because the overhead cost (to performance and memory) would be too
large. Enabling the @ref{fe,,tracemalloc} module provides additional information
on the origin of some errors. For example, @ref{241,,ResourceWarning} logs the
traceback where the resource was allocated, and a buffer overflow error logs
the traceback where the memory block was allocated.

The Python Development Mode does not prevent the @ref{da2,,-O} command line
option from removing @ref{955,,assert} statements nor from setting
@ref{7c4,,__debug__} to @code{False}.

The Python Development Mode can only be enabled at the Python startup. Its
value can be read from @ref{677,,sys.flags.dev_mode}.


Modifié dans la version 3.8: The @ref{1f2,,io.IOBase} destructor now logs @code{close()} exceptions.



Modifié dans la version 3.9: The `encoding' and `errors' arguments are now checked for string encoding
and decoding operations.


@node ResourceWarning Example,Bad file descriptor error example,Effects of the Python Development Mode,Python Development Mode
@anchor{library/devmode resourcewarning-example}@anchor{3f1d}
@subsubsection ResourceWarning Example


Example of a script counting the number of lines of the text file specified in
the command line:

@example
import sys

def main():
    fp = open(sys.argv[1])
    nlines = len(fp.readlines())
    print(nlines)
    # The file is closed implicitly

if __name__ == "__main__":
    main()
@end example

The script does not close the file explicitly. By default, Python does not emit
any warning. Example using README.txt, which has 269 lines:

@example
$ python script.py README.txt
269
@end example

Enabling the Python Development Mode displays a @ref{241,,ResourceWarning} warning:

@example
$ python -X dev script.py README.txt
269
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README.rst' mode='r' encoding='UTF-8'>
  main()
ResourceWarning: Enable tracemalloc to get the object allocation traceback
@end example

In addition, enabling @ref{fe,,tracemalloc} shows the line where the file was
opened:

@example
$ python -X dev -X tracemalloc=5 script.py README.rst
269
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='README.rst' mode='r' encoding='UTF-8'>
  main()
Object allocated at (most recent call last):
  File "script.py", lineno 10
    main()
  File "script.py", lineno 4
    fp = open(sys.argv[1])
@end example

The fix is to close explicitly the file. Example using a context manager:

@example
def main():
    # Close the file explicitly when exiting the with block
    with open(sys.argv[1]) as fp:
        nlines = len(fp.readlines())
    print(nlines)
@end example

Not closing a resource explicitly can leave a resource open for way longer than
expected; it can cause severe issues upon exiting Python. It is bad in
CPython, but it is even worse in PyPy. Closing resources explicitly makes an
application more deterministic and more reliable.

@node Bad file descriptor error example,,ResourceWarning Example,Python Development Mode
@anchor{library/devmode bad-file-descriptor-error-example}@anchor{3f1e}
@subsubsection Bad file descriptor error example


Script displaying the first line of itself:

@example
import os

def main():
    fp = open(__file__)
    firstline = fp.readline()
    print(firstline.rstrip())
    os.close(fp.fileno())
    # The file is closed implicitly

main()
@end example

By default, Python does not emit any warning:

@example
$ python script.py
import os
@end example

The Python Development Mode shows a @ref{241,,ResourceWarning} and logs a "Bad file
descriptor" error when finalizing the file object:

@example
$ python -X dev script.py
import os
script.py:10: ResourceWarning: unclosed file <_io.TextIOWrapper name='script.py' mode='r' encoding='UTF-8'>
  main()
ResourceWarning: Enable tracemalloc to get the object allocation traceback
Exception ignored in: <_io.TextIOWrapper name='script.py' mode='r' encoding='UTF-8'>
Traceback (most recent call last):
  File "script.py", line 10, in <module>
    main()
OSError: [Errno 9] Bad file descriptor
@end example

@code{os.close(fp.fileno())} closes the file descriptor. When the file object
finalizer tries to close the file descriptor again, it fails with the @code{Bad
file descriptor} error. A file descriptor must be closed only once. In the
worst case scenario, closing it twice can lead to a crash (see bpo-18748@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=18748}
for an example).

The fix is to remove the @code{os.close(fp.fileno())} line, or open the file with
@code{closefd=False}.

@node doctest — Exemples de tests interactifs en Python,unittest --- Unit testing framework,Python Development Mode,Outils de développement
@anchor{library/doctest doc}@anchor{3f1f}@anchor{library/doctest doctest-test-interactive-python-examples}@anchor{3f20}@anchor{library/doctest module-doctest}@anchor{3a}
@subsection @code{doctest} — Exemples de tests interactifs en Python


@geindex module; doctest

`Code source :' Lib/doctest.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/doctest.py}


__________________________________________________________________


Le module @ref{3a,,doctest} cherche des extraits de texte ressemblant à des sessions Python interactives avant de les exécuter, de façon à vérifier que le fonctionnement correspond exactement à la description. Voici quelques cas d'utilisation de `doctest' :


@itemize *

@item 
Vérifier que les `docstrings' d'un module sont à jour en vérifiant que tous les exemples interactifs fonctionnent toujours tels que décrits.

@item 
Réaliser un test de régression en vérifiant que les exemples interactifs provenant d'un fichier de test ou d'un objet de test fonctionnent comme prévu.

@item 
Rédiger de la documentation sous forme de tutoriel pour un paquet, avec une abondance d'exemples ayant des entrées et des sorties. On pourrait voir ça comme des tests « dans le texte » ou de la « documentation exécutable », selon le point de vue.
@end itemize

Voici un petit exemple d'un module qui soit tout de même complet :

@example
"""
This is the "example" module.

The example module supplies one function, factorial().  For example,

>>> factorial(5)
120
"""

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(30)
    265252859812191058636308480000000
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0

    Factorials of floats are OK, but the float must be an exact integer:
    >>> factorial(30.1)
    Traceback (most recent call last):
        ...
    ValueError: n must be exact integer
    >>> factorial(30.0)
    265252859812191058636308480000000

    It must also not be ridiculously large:
    >>> factorial(1e100)
    Traceback (most recent call last):
        ...
    OverflowError: n too large
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result


if __name__ == "__main__":
    import doctest
    doctest.testmod()
@end example

L'exécution du fichier @code{example.py} directement à partir de la ligne de commande démontre la magie de @ref{3a,,doctest} :

@example
$ python example.py
$
@end example

Il n'y a pas de sortie ! C'est normal, cela signifie que tous les exemples fonctionnent. Passez @code{-v} au script pour que @ref{3a,,doctest} affiche un journal détaillé de ce qui a été essayé, avant d'afficher un résumé à la fin :

@example
$ python example.py -v
Trying:
    factorial(5)
Expecting:
    120
ok
Trying:
    [factorial(n) for n in range(6)]
Expecting:
    [1, 1, 2, 6, 24, 120]
ok
@end example

Et ainsi de suite, jusqu'à ce qu'on atteigne :

@example
Trying:
    factorial(1e100)
Expecting:
    Traceback (most recent call last):
        ...
    OverflowError: n too large
ok
2 items passed all tests:
   1 test in __main__
   6 tests in __main__.factorial
7 tests in 2 items.
7 passed.
Test passed.
$
@end example

That's all you need to know to start making productive use of @ref{3a,,doctest}!
Jump in.  The following sections provide full details.  Note that there are many
examples of doctests in the standard Python test suite and libraries.
Especially useful examples can be found in the standard test file
@code{Lib/test/test_doctest/test_doctest.py}.

@menu
* Utilisation simple ; vérifier des exemples dans des docstrings: Utilisation simple vérifier des exemples dans des docstrings. 
* Utilisation simple ; vérifier des exemples dans un fichier texte: Utilisation simple vérifier des exemples dans un fichier texte. 
* Comment ça marche:: 
* API de base:: 
* API de tests unitaires:: 
* API avancé:: 
* Débogage:: 
* Éditorial:: 

@end menu

@node Utilisation simple vérifier des exemples dans des docstrings,Utilisation simple vérifier des exemples dans un fichier texte,,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest doctest-simple-testmod}@anchor{3f21}@anchor{library/doctest simple-usage-checking-examples-in-docstrings}@anchor{3f22}
@subsubsection Utilisation simple : vérifier des exemples dans des `docstrings'


Le plus simple pour commencer à utiliser `doctest' (mais pas nécessairement la façon avec laquelle vous continuerez) est de terminer chaque module @code{M} avec :

@example
if __name__ == "__main__":
    import doctest
    doctest.testmod()
@end example

@code{doctest} examine alors les `docstrings' dans le module @code{M}.

Exécuter le module comme un script a comme conséquence d'exécuter et de vérifier les exemples dans les `docstrings' :

@example
python M.py
@end example

Ceci n'affiche rien à moins qu'un exemple échoue ; le cas échéant, les exemples défaillants et les causes du ou des échecs sont affichés sur `stdout', et la ligne finale de la sortie est @code{***Test Failed*** *N failures*.}, où `N' est le nombre d'exemples défaillants.

À la place, exécutez-la avec l'option de ligne de commande @code{-v} :

@example
python M.py -v
@end example

alors, un rapport détaillé de tous les exemples faisant partie de l'essai est affiché sur la sortie standard, accompagné à la fin de leurs résumés.

Vous pouvez activer le mode verbeux en passant @code{verbose=True} à @ref{1421,,testmod()}, ou vous le désactiver en lui passant @code{verbose=False}. Dans ces deux cas, @code{sys.argv} n'est pas inspecté par @ref{1421,,testmod()} (ainsi, lui passer @code{-v} ou pas n'a aucun effet).

Il y a un raccourci pour exécuter @ref{1421,,testmod()} à partir de la ligne de commande. Vous demandez à l'interpréteur Python d'exécuter le module `doctest' directement à partir de la bibliothèque standard afin de passer le ou les noms des modules à partir de la ligne de commande ainsi :

@example
python -m doctest -v example.py
@end example

Ceci importera @code{example.py} comme un module autonome et exécutera @ref{1421,,testmod()} sur celui-ci. Notez que ceci peut ne pas fonctionner si le fichier fait partie d'un paquet et importe d'autres sous-modules de ce paquet.

Pour plus d'informations sur @ref{1421,,testmod()}, consultez la section @ref{3f23,,API de base}.

@node Utilisation simple vérifier des exemples dans un fichier texte,Comment ça marche,Utilisation simple vérifier des exemples dans des docstrings,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest doctest-simple-testfile}@anchor{3f24}@anchor{library/doctest simple-usage-checking-examples-in-a-text-file}@anchor{3f25}
@subsubsection Utilisation simple : vérifier des exemples dans un fichier texte


Une autre application simple de `doctest' est de tester des exemples interactifs dans un fichier texte. Ceci est fait avec la fonction @ref{3f26,,testfile()} :

@example
import doctest
doctest.testfile("example.txt")
@end example

Ce court script exécute et vérifie chacun des exemples Python interactifs contenus dans le fichier @code{example.txt}. Le contenu du fichier est traité comme une seule `docstring' géante ; le fichier n'a pas besoin de contenir un programme Python ! Par exemple, prenons un fichier @code{example.txt} contenant :

@example
The `@w{`}example`@w{`} module
======================

Using `@w{`}factorial`@w{`}
-------------------

This is an example text file in reStructuredText format.  First import
`@w{`}factorial`@w{`} from the `@w{`}example`@w{`} module:

    >>> from example import factorial

Now use it:

    >>> factorial(6)
    120
@end example

Exécuter @code{doctest.testfile("example.txt")} recherche les erreurs dans cette documentation :

@example
File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720
@end example

Comme pour @ref{1421,,testmod()}, @ref{3f26,,testfile()} n'affichera rien sauf si un exemple échoue. Si un exemple échoue, alors le ou les exemples défaillants et leurs causes sont affichés sur `stdout', dans le même format que @ref{1421,,testmod()}.

Par défaut, @ref{3f26,,testfile()} cherche les fichiers dans le répertoire où se situe le module qui l'appelle. Consultez la section @ref{3f23,,API de base} pour une description des options de ligne de commande à utiliser afin de chercher dans d'autres répertoires.

Comme pour @ref{1421,,testmod()}, la verbosité de @ref{3f26,,testfile()} peut être ajustée avec l'option de ligne de commande @code{-v} ou avec le mot clé `verbose'.

Il y a un raccourci pour exécuter @ref{3f26,,testfile()} à partir de la ligne de commande.  Demandez à l'interpréteur Python d'exécuter le module `doctest' directement à partir de la bibliothèque standard et de passer le ou les noms des modules à partir de la ligne de commande ainsi :

@example
python -m doctest -v example.txt
@end example

Puisque le nom du fichier ne se termine pas par @code{.py}, @ref{3a,,doctest} en déduit qu'il s'exécute à l'aide de @ref{3f26,,testfile()}, et non pas @ref{1421,,testmod()}.

Pour plus d'information sur @ref{3f26,,testfile()}, consultez la section @ref{3f23,,API de base}.

@node Comment ça marche,API de base,Utilisation simple vérifier des exemples dans un fichier texte,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest doctest-how-it-works}@anchor{3f27}@anchor{library/doctest how-it-works}@anchor{3f28}
@subsubsection Comment ça marche


Cette section examine en détail le fonctionnement de `doctest' : quelles `docstrings' sont considérées, comment sont trouvés les exemples interactifs, quel est le contexte d'exécution sélectionné, comment les exceptions sont gérées, et de quelles façons les options de ligne de commande peuvent être utilisées pour définir le comportement. Ceci est l'information dont vous avez besoin pour écrire des exemples `doctest' ; pour de l'information sur l'exécution de `doctest' sur ces exemples, consultez les sections suivantes.

@menu
* Quelles docstrings sont considérées ?:: 
* Comment les exemples docstring sont-ils identifiés ?:: 
* Quel est le contexte d'exécution ?:: 
* Qu'en est-il des exceptions ?:: 
* Options de ligne de commande:: 
* Instructions:: 
* Avertissements: Avertissements<2>. 

@end menu

@node Quelles docstrings sont considérées ?,Comment les exemples docstring sont-ils identifiés ?,,Comment ça marche
@anchor{library/doctest doctest-which-docstrings}@anchor{3f29}@anchor{library/doctest which-docstrings-are-examined}@anchor{3f2a}
@subsubsection Quelles `docstrings' sont considérées ?


Les `docstrings' du module, de toutes les fonctions, classes, et méthodes sont cherchées. Les objets qui sont importés dans le module ne sont pas cherchés.

In addition, there are cases when you want tests to be part of a module but not part
of the help text, which requires that the tests not be included in the docstring.
Doctest looks for a module-level variable called @code{__test__} and uses it to locate other
tests. If @code{M.__test__} exists, it must be a dict, and each
entry maps a (string) name to a function object, class object, or string.
Function and class object docstrings found from @code{M.__test__} are searched, and
strings are treated as if they were docstrings.  In output, a key @code{K} in
@code{M.__test__} appears with name @code{M.__test__.K}.

For example, place this block of code at the top of @code{example.py}:

@example
__test__ = @{
    'numbers': """
>>> factorial(6)
720

>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
"""
@}
@end example

The value of @code{example.__test__["numbers"]} will be treated as a
docstring and all the tests inside it will be run. It is
important to note that the value can be mapped to a function,
class object, or module; if so, @code{doctest}
searches them recursively for docstrings, which are then scanned for tests.

Toute classe trouvée est ainsi cherchée récursivement, afin de tester les `docstrings' contenues dans leurs méthodes et leurs classes imbriquées.

@node Comment les exemples docstring sont-ils identifiés ?,Quel est le contexte d'exécution ?,Quelles docstrings sont considérées ?,Comment ça marche
@anchor{library/doctest doctest-finding-examples}@anchor{3f2b}@anchor{library/doctest how-are-docstring-examples-recognized}@anchor{3f2c}
@subsubsection Comment les exemples `docstring' sont-ils identifiés ?


Dans la plupart des cas, un copier-coller d'une séance interactive de console fonctionne bien, mais `doctest' n'essaye pas de faire une simulation exacte d'un `shell' Python spécifique.

@example
>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print("yes")
... else:
...     print("no")
...     print("NO")
...     print("NO!!!")
...
no
NO
NO!!!
>>>
@end example

@geindex >>>;interpreter prompt
@geindex ...;interpreter prompt

Toute sortie souhaitée doit immédiatement suivre le dernier @code{'>>> '} ou le dernier @code{'... '} contenant le code, et la sortie souhaitée, s'il y en a une, s'étend jusqu'au prochain @code{'>>> '} ou à la prochaine ligne vide.

En détail :


@itemize *

@item 
La sortie souhaitée ne peut pas contenir une ligne vide, puisque contenir une telle ligne signale la fin de la sortie souhaitée. Si la sortie souhaitée doit contenir une ligne vide, ajoutez @code{<BLANKLINE>} dans votre exemple `doctest' à chaque endroit où une ligne vide est souhaitée.

@item 
Tous les caractères de tabulation insécables (`hard tab characters') sont convertis en espaces, en utilisant des taquets de tabulation de 8 espaces. Les tabulations se trouvant dans la sortie générée par le code test ne sont pas modifiées. Comme tout caractère de tabulation insécable `est' converti, ceci veut dire que si le code de sortie inclut des caractères de tabulation insécables, alors la seule façon que le `doctest' peut réussir est si l'option @ref{3f2d,,NORMALIZE_WHITESPACE} ou si @ref{3f2e,,directive} a cours. De façon alternative, le test peut être ré-écrit afin de capturer la sortie et de la comparer à un ensemble de valeurs attendues, et ce, en tant qu'étape du test. Cette gestion des tabulations à la source a été obtenue suite à un processus d'essais et d'erreurs ; il a été démontré que c'était là la façon de les gérer qui soit la moins susceptible de générer des erreurs. Il est possible d'utiliser un algorithme différent pour la gestion des tabulations en rédigeant une classe sur mesure @ref{3f2f,,DocTestParser}.

@item 
La sortie vers `stdout' est capturée, mais pas la sortie vers `stderr' (les traces d'appel sont capturées par d'autres moyens).

@item 
Si vous souhaitez conserver les barres obliques inversées telles quelles lorsque vous terminez une ligne avec une barre oblique inversée dans une séance interactive, ou quand vous utilisez une telle barre pour toute autre raison, vous devez utiliser une `docstring' brute :

@example
>>> def f(x):
...     r'@w{'}'Backslashes in a raw docstring: m\n'@w{'}'
...
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n
@end example

Sinon, la barre oblique inversée est interprétée comme faisant partie de la chaîne de caractères. Par exemple, le @code{\n} ci-dessus est interprété comme un caractère de saut de ligne. De façon alternative, vous pouvez doubler chaque barre oblique inversée dans la version `doctest' (et n'utilisez pas dans ce cas de `docstring' brute) :

@example
>>> def f(x):
...     '@w{'}'Backslashes in a raw docstring: m\\n'@w{'}'
...
>>> print(f.__doc__)
Backslashes in a raw docstring: m\n
@end example

@item 
La colonne de départ n'a pas d'importance :

@example
>>> assert "Easy!"
      >>> import math
          >>> math.floor(1.9)
          1
@end example

et autant d'espaces sont retirés de la sortie attendue qu'il y avait d'espaces avant la ligne commençant par @code{'>>> '}.
@end itemize

@node Quel est le contexte d'exécution ?,Qu'en est-il des exceptions ?,Comment les exemples docstring sont-ils identifiés ?,Comment ça marche
@anchor{library/doctest doctest-execution-context}@anchor{3f30}@anchor{library/doctest what-s-the-execution-context}@anchor{3f31}
@subsubsection Quel est le contexte d'exécution ?


Par défaut, chaque fois que @ref{3a,,doctest} trouve une `docstring' à tester, il utilise une `copie superficielle' des variables globales de @code{M}, de telle façon que l'exécution de tests ne change pas les variables globales réelles du module et que l'exécution d'un unique test dans @code{M} ne puisse laisser traîner des miettes pouvant accidentellement causer la réussite d'un autre test. Ceci signifie que les exemples peuvent utiliser librement n'importe quel nom défini au niveau supérieur dans @code{M} ainsi que les noms définis précédemment dans la `docstring' en cours d'exécution. Les exemples ne peuvent voir les noms définis dans d'autres `docstrings'.

Vous pouvez forcer l'utilisation de votre propre `dict' comme contexte d'exécution en passant @code{globs=your_dict} à @ref{1421,,testmod()} ou encore, à @ref{3f26,,testfile()}.

@node Qu'en est-il des exceptions ?,Options de ligne de commande,Quel est le contexte d'exécution ?,Comment ça marche
@anchor{library/doctest doctest-exceptions}@anchor{3f32}@anchor{library/doctest what-about-exceptions}@anchor{3f33}
@subsubsection Qu'en est-il des exceptions ?


Pas de problèmes, tant que la trace d'appels est la seule sortie produite par l'exemple : il suffit d'ajouter la trace. @footnote{
Les exemples contenant à la fois la sortie attendue et une exception ne sont pas supportés. Tenter de deviner où finit l'un et où commence l'autre peut mener à plusieurs erreurs, en plus d'être un test qui soit source de confusion.
} Comme les traces d'appels contiennent des détails qui sont sujets à changement rapide (par exemple, le chemin exact vers un fichier et les numéros de ligne), ceci est un cas où `doctest' fait un effort pour être flexible dans ce qu'il accepte.

Exemple simple :

@example
>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list
@end example

Ce `doctest' réussit si @ref{1ff,,ValueError} est levée, avec le détail @code{list.remote(x): x not in list} tel que montré.

La sortie attendue pour une exception doit commencer par un en-tête de trace d'appels, qui peut être l'une des deux lignes suivantes, avec la même indentation que la première ligne de l'exemple :

@example
Traceback (most recent call last):
Traceback (innermost last):
@end example

L'en-tête de la trace d'appels est suivi par une pile optionnelle de trace d'appels, dont le contenu est ignoré par `doctest'. La trace d'appels est habituellement omise, ou est copiée verbatim à partir d'une séance interactive.

La pile de trace d'appels est suivie par la partie la plus intéressante : la ou les lignes contenant le type et le détail de l'exception. Ceci est habituellement la dernière ligne de la trace d'appels ; dans le cas où l'exception a un détail sur plusieurs lignes, il est possible de prolonger sur plusieurs lignes :

@example
>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: multi
    line
detail
@end example

Les trois dernières lignes (en commençant par @ref{1ff,,ValueError}) sont comparées avec le type et le détail de l'exception ; tout le reste est ignoré.

La pratique optimale est d'omettre la pile de trace d'appels, à moins que celle-ci ait une valeur significative de documentation de l'exemple. Ainsi, le dernier exemple est probablement meilleur tel qui suit :

@example
>>> raise ValueError('multi\n    line\ndetail')
Traceback (most recent call last):
    ...
ValueError: multi
    line
detail
@end example

Prenez note que les traces d'appels sont traitées de façon vraiment particulière. Précisément, dans l'exemple ré-écrit, l'utilisation de @code{...} est indépendante de l'option `doctest' @ref{1422,,ELLIPSIS}. Les points de suspension dans cet exemple peuvent être omis, ou peuvent aussi être trois (ou trois cents) virgules ou chiffres, ou une retranscription indentée d'une parodie de Monty Python.

Quelques détails que vous devriez lire une fois, mais que vous pouvez oublier :


@itemize *

@item 
`Doctest' ne peut pas deviner si votre sortie attendue provient d'une trace d'appels issue d'une exception ou d'un affichage ordinaire. Ainsi, si nous avons un exemple s'attendant à obtenir @code{ValueError: 42 is prime}, celui-ci réussira peu importe si @ref{1ff,,ValueError} est réellement levée ou si l'exemple affiche simplement ce texte de trace d'appels. Dans la pratique, une sortie ordinaire commence rarement par une ligne d'en-tête de trace d'appels ; ainsi, ceci ne pose pas de vrai problème.

@item 
Chaque ligne de la trace d'appel (s'il y en a) doit soit être indentée d'un niveau supplémentaire au niveau de la première ligne de l'exemple `ou' doit commencer par un caractère qui ne soit pas alphanumérique. La première ligne suivant l'en-tête de la trace d'appels qui soit indentée similairement et qui commence par un caractère alphanumérique est comprise comme étant le début du détail de l'exception. Bien sûr, ceci fait la chose adéquate pour les traces d'appels véritables.

@item 
Lorsque l'option de `doctest' @ref{12e7,,IGNORE_EXCEPTION_DETAIL} est définie, tout ce qui suit le point-virgule se trouvant le plus à gauche ainsi que toute information liée au module dans le nom de l'exception sont ignorés.

@item 
Le shell interactif omet la ligne d'en-tête de la trace d'appels pour certaines erreurs @ref{18b,,SyntaxError}. Ceci étant dit, `doctest' utilise la ligne d'en-tête de la trace d'appels afin de faire une distinction entre les exceptions et les autres types d'erreurs. Ainsi, dans les rares cas où vous avez besoin de tester une erreur @ref{18b,,SyntaxError} qui omet l'en-tête de la trace d'appels, il vous est nécessaire d'ajouter manuellement la ligne d'en-tête de la trace d'appels à l'exemple de test.
@end itemize

@geindex ^ (caret);marker


@itemize *

@item 
Pour certaines erreurs, Python affiche la position de l'erreur en utilisant le marqueur @code{^} et des tildes :

@example
>>> 1 + None
  File "<stdin>", line 1
    1 + None
    ~~^~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
@end example

Comme les lignes dénotant la position de l'erreur précèdent le type et le détail de l'exception, elles ne sont pas vérifiées par `doctest'. Par exemple, le test suivant réussira, même si le marqueur @code{^} n'est pas à la bonne place :

@example
>>> 1 + None
  File "<stdin>", line 1
    1 + None
    ^~~~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'NoneType'
@end example
@end itemize
@anchor{library/doctest option-flags-and-directives}@anchor{3f34}
@node Options de ligne de commande,Instructions,Qu'en est-il des exceptions ?,Comment ça marche
@anchor{library/doctest doctest-options}@anchor{f1e}@anchor{library/doctest option-flags}@anchor{3f35}
@subsubsection Options de ligne de commande


Un ensemble d'options de ligne de commande contrôle différents aspects du comportement de `doctest'. Pour les options, des noms symboliques sont fournis comme des constantes de module, qui peuvent être composés par un OU bit à bit (@ref{1ff1,,bitwise ORed}) et passés à diverses fonctions. Les noms peuvent aussi être utilisés dans des @ref{3f2e,,instructions doctest}, et peuvent être passés à l'interface de ligne de commande de `doctest' à l'aide de l'option @code{-o}.


Ajouté dans la version 3.4: L'option de ligne de commande @code{-o}.


Le premier groupe d'options définit les sémantiques de test, de façon à contrôler comment `doctest' décide si la sortie obtenue correspond à la sortie attendue de l'exemple :

@geindex DONT_ACCEPT_TRUE_FOR_1 (dans le module doctest)
@anchor{library/doctest doctest DONT_ACCEPT_TRUE_FOR_1}@anchor{3f36}
@deffn {Données} doctest.DONT_ACCEPT_TRUE_FOR_1

Par défaut, si un bloc de sortie attendu contient uniquement un @code{1}, un vrai bloc de sortie contenant uniquement un @code{1} ou un @code{True} sera considéré comme étant une correspondance ; de façon similaire, nous avons une correspondance pour @code{0} et @code{False}. Lorsque l'option @ref{3f36,,DONT_ACCEPT_TRUE_FOR_1} est précisée, aucune de ces substitutions n'est acceptée. Le comportement par défaut s'ajuste au fait que Python a changé le type de renvoi de plusieurs fonctions, passant de nombres entiers à des booléens ; les `doctests' s'attendant à une sortie de « petit entier » (`little integer') fonctionnent encore dans ces cas. Cette option disparaîtra probablement, mais pas avant plusieurs années.
@end deffn

@geindex <BLANKLINE>

@geindex DONT_ACCEPT_BLANKLINE (dans le module doctest)
@anchor{library/doctest doctest DONT_ACCEPT_BLANKLINE}@anchor{3f37}
@deffn {Données} doctest.DONT_ACCEPT_BLANKLINE

Par défaut, si un bloc de sortie attendue contient une ligne contenant uniquement la chaîne de caractères @code{<BLANKLINE>}, alors cette ligne sera en correspondance avec une ligne vide dans la sortie réelle. Puisqu'une véritable ligne vide permet de délimiter la sortie attendue, ceci est la seule façon de communiquer qu'une ligne vide est souhaitée. Lorsque l'option @ref{3f37,,DONT_ACCEPT_BLANKLINE} est précisée, cette substitution n'est pas permise.
@end deffn

@geindex NORMALIZE_WHITESPACE (dans le module doctest)
@anchor{library/doctest doctest NORMALIZE_WHITESPACE}@anchor{3f2d}
@deffn {Données} doctest.NORMALIZE_WHITESPACE

Lorsque précisé, toutes les séquences de caractères d'espacement et de caractères de saut de ligne sont traitées comme équivalentes. Toute séquence de caractères d'espacement à l'intérieur de la sortie attendue correspondra alors à toute séquence de caractères d'espacement à l'intérieur de la sortie réelle. Par défaut, les caractères d'espacement doivent correspondre de façon exacte. L'option @ref{3f2d,,NORMALIZE_WHITESPACE} est particulièrement utile lorsqu'une ligne de sortie attendue est très longue, et que l'on souhaite la répartir sur plusieurs lignes dans le fichier source.
@end deffn

@geindex ...;in doctests

@geindex ELLIPSIS (dans le module doctest)
@anchor{library/doctest doctest ELLIPSIS}@anchor{1422}
@deffn {Données} doctest.ELLIPSIS

Lorsque précisé, un marqueur de points de suspension (@code{...}) dans la sortie attendue peut correspondre à n'importe quelle partie de chaîne de caractères dans la sortie réelle. Ceci inclut les parties qui traversent les frontières de lignes, ainsi que les parties vides de chaînes de caractères ; ainsi, il est préférable d'en faire une utilisation simple. Les usages complexes mènent aux mêmes surprises du type "oups, il y avait trop de correspondances !" que l'utilisation de @code{.*} dans les expressions régulières.
@end deffn

@geindex IGNORE_EXCEPTION_DETAIL (dans le module doctest)
@anchor{library/doctest doctest IGNORE_EXCEPTION_DETAIL}@anchor{12e7}
@deffn {Données} doctest.IGNORE_EXCEPTION_DETAIL

When specified, doctests expecting exceptions pass so long as an exception
of the expected type is raised, even if the details
(message and fully qualified exception name) don't match.

For example, an example expecting @code{ValueError: 42} will pass if the actual
exception raised is @code{ValueError: 3*14}, but will fail if, say, a
@ref{522,,TypeError} is raised instead.
It will also ignore any fully qualified name included before the
exception class, which can vary between implementations and versions
of Python and the code/libraries in use.
Hence, all three of these variations will work with the flag specified:

@example
>>> raise Exception('message')
Traceback (most recent call last):
Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
builtins.Exception: message

>>> raise Exception('message')
Traceback (most recent call last):
__main__.Exception: message
@end example

Note that @ref{1422,,ELLIPSIS} can also be used to ignore the
details of the exception message, but such a test may still fail based
on whether the module name is present or matches exactly.


Modifié dans la version 3.2: Maintenant, @ref{12e7,,IGNORE_EXCEPTION_DETAIL} permet aussi d'ignorer toute information liée au module contenant l'exception qui est en train d'être testée.

@end deffn

@geindex SKIP (dans le module doctest)
@anchor{library/doctest doctest SKIP}@anchor{3f38}
@deffn {Données} doctest.SKIP

Lorsque précisé, cesse complètement l'exécution de tous les exemples. Ceci peut être utile dans des contextes où les exemples `doctest' sont à la fois de la documentation et des cas de tests, et qu'un exemple doit être inclus pour des raisons de documentation, mais ne devrait pas être vérifié. Par exemple, la sortie de l'exemple doit être aléatoire ; ou encore, lorsque l'exemple peut dépendre de ressources inatteignables pour l'exécuteur de test.

L'option `SKIP' peut aussi être utilisée temporairement afin de commenter des exemples et d'en empêcher l'exécution.
@end deffn

@geindex COMPARISON_FLAGS (dans le module doctest)
@anchor{library/doctest doctest COMPARISON_FLAGS}@anchor{3f39}
@deffn {Données} doctest.COMPARISON_FLAGS

Un masque binaire effectuant une composition avec OU de toutes les options de comparaisons ci-dessus.
@end deffn

Le deuxième groupe d'options détermine comment les échecs de tests sont signalés :

@geindex REPORT_UDIFF (dans le module doctest)
@anchor{library/doctest doctest REPORT_UDIFF}@anchor{1423}
@deffn {Données} doctest.REPORT_UDIFF

Lorsque précisé, les défaillances qui font intervenir des sorties attendues et réelles multi-lignes sont affichées dans une `diff' unifiée.
@end deffn

@geindex REPORT_CDIFF (dans le module doctest)
@anchor{library/doctest doctest REPORT_CDIFF}@anchor{1424}
@deffn {Données} doctest.REPORT_CDIFF

Lorsque précisé, les défaillances qui font intervenir des sorties attendues et réelles multi-lignes sont affichées dans une `diff' de contexte.
@end deffn

@geindex REPORT_NDIFF (dans le module doctest)
@anchor{library/doctest doctest REPORT_NDIFF}@anchor{1425}
@deffn {Données} doctest.REPORT_NDIFF

Lorsque précisé, les différences sont obtenues grâce à @code{difflib.Differ}, en utilisant le même algorithme que le populaire utilitaire @code{ndiff.py}. Ceci est la seule méthode qui puisse faire la différence à l'intérieur des lignes ainsi que parmi les lignes prises conjointement. Par exemple, si une ligne de sortie attendue contient le chiffre @code{1} alors que la sortie réelle contient la lettre @code{l}, une ligne est insérée avec un marqueur caret démarquant les positions de colonnes où il n'y a pas de correspondance.
@end deffn

@geindex REPORT_ONLY_FIRST_FAILURE (dans le module doctest)
@anchor{library/doctest doctest REPORT_ONLY_FIRST_FAILURE}@anchor{3f3a}
@deffn {Données} doctest.REPORT_ONLY_FIRST_FAILURE

Lorsque précisé, le premier exemple défaillant de chaque `doctest' est affiché, mais la sortie est supprimée pour tous les autres exemples. Ceci empêche `doctest' de rapporter les exemples adéquats qui échouent du fait d'échecs précédents ; ceci peut aussi cacher des exemples inadéquats qui échouent de façon indépendante au premier échec. Lorsque @ref{3f3a,,REPORT_ONLY_FIRST_FAILURE} est précisé, les exemples restants sont toujours exécutés, et sont toujours comptabilisés dans le nombre total des lignes échouant ; seulement la sortie est omise.
@end deffn

@geindex FAIL_FAST (dans le module doctest)
@anchor{library/doctest doctest FAIL_FAST}@anchor{f1f}
@deffn {Données} doctest.FAIL_FAST

Lorsque précisé, mettre fin à l'exécution après le premier exemple défaillant et ne pas essayer d'exécuter les exemples restants. Ainsi, le nombre d'échecs rapporté sera au plus un (1). Cette option peut être utile durant le débogage, étant donné que les exemples suivant le premier échec ne produiront aucune sortie de débogage.

La ligne de commande de `doctest' accepte l'option @code{-f} comme un raccourci de @code{-o FAIL_FAST}.


Ajouté dans la version 3.4.

@end deffn

@geindex REPORTING_FLAGS (dans le module doctest)
@anchor{library/doctest doctest REPORTING_FLAGS}@anchor{3f3b}
@deffn {Données} doctest.REPORTING_FLAGS

Un masque binaire effectuant une composition avec le OU de toutes les options de signalement ci-dessus.
@end deffn

Il y a aussi une façon d'enregistrer des nouveaux noms d'option, quoique ceci n'est pas utile sauf dans le cas où vous devez faire une extension pour le code interne de @ref{3a,,doctest} par le biais d'une sous-classe :

@geindex register_optionflag() (dans le module doctest)
@anchor{library/doctest doctest register_optionflag}@anchor{3f3c}
@deffn {Fonction} doctest.register_optionflag (name)

Crée une nouvelle option avec un nom donné, et renvoie la valeur en nombre entier de la nouvelle option. La fonction @ref{3f3c,,register_optionflag()} peut être utilisée lors de la création de sous-classes à partir de @ref{3f3d,,OutputChecker} ou @ref{3f3e,,DocTestRunner} pour créer de nouvelles options qui sont supportées par vos sous-classes. La fonction @ref{3f3c,,register_optionflag()} devrait toujours être appelée par l'expression suivante :

@example
MY_FLAG = register_optionflag('MY_FLAG')
@end example
@end deffn

@geindex # (hash);in doctests
@geindex + (plus);in doctests
@geindex - (minus);in doctests

@node Instructions,Avertissements<2>,Options de ligne de commande,Comment ça marche
@anchor{library/doctest directives}@anchor{3f3f}@anchor{library/doctest doctest-directives}@anchor{3f2e}
@subsubsection Instructions


Les instructions `doctest' peuvent être utilisées afin de modifier les @ref{f1e,,options} pour un exemple individuel. Les instructions `doctest' sont des commentaires Python spéciaux suivant le code source d'un exemple :

@example
@anchor{library/doctest grammar-token-doctest-directive}@anchor{3f40}directive             ::= "#" "doctest:" directive_options
@anchor{library/doctest grammar-token-doctest-directive_options}@anchor{3f41}directive_options     ::= directive_option ("," directive_option)*
@anchor{library/doctest grammar-token-doctest-directive_option}@anchor{3f42}directive_option      ::= on_or_off directive_option_name
@anchor{library/doctest grammar-token-doctest-on_or_off}@anchor{3f43}on_or_off             ::= "+" | "-"
@anchor{library/doctest grammar-token-doctest-directive_option_name}@anchor{3f44}directive_option_name ::= "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...
@end example

Les caractères d'espacement ne sont pas permis entre les @code{+} ou les @code{-} et le nom de l'option d'instruction. Le nom de l'option d'instruction peut être n'importe lequel des noms d'options expliqués ci-dessus.

Les instructions d'un exemple `doctest' modifient le comportement de `doctest' et ce, seulement pour cet exemple. Utilisez @code{+} pour activer le comportement nommé, ou @code{-} pour le désactiver.

For example, this test passes:

@example
>>> print(list(range(20)))  # doctest: +NORMALIZE_WHITESPACE
[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,
10,  11, 12, 13, 14, 15, 16, 17, 18, 19]
@end example

Without the directive it would fail, both because the actual output doesn't have
two blanks before the single-digit list elements, and because the actual output
is on a single line.  This test also passes, and also requires a directive to do
so:

@example
>>> print(list(range(20)))  # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
@end example

Multiple directives can be used on a single physical line, separated by
commas:

@example
>>> print(list(range(20)))  # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]
@end example

If multiple directive comments are used for a single example, then they are
combined:

@example
>>> print(list(range(20)))  # doctest: +ELLIPSIS
...                         # doctest: +NORMALIZE_WHITESPACE
[0,    1, ...,   18,    19]
@end example

As the previous example shows, you can add @code{...} lines to your example
containing only directives.  This can be useful when an example is too long for
a directive to comfortably fit on the same line:

@example
>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39]
@end example

Prendre note que puisque toutes les options sont désactivées par défaut, et comme les instructions s'appliquent uniquement aux exemples dans lesquelles elles apparaissent, activer les options (par le biais de @code{+} dans une instruction) est habituellement le seul choix ayant du sens. Toutefois, les options peuvent aussi être passées aux fonctions qui exécutent les `doctests', définissant de nouvelles valeurs par défaut. Dans de tels cas, désactiver une option par l'utilisation de @code{-} dans une instruction peut être utile.

@node Avertissements<2>,,Instructions,Comment ça marche
@anchor{library/doctest doctest-warnings}@anchor{3f45}@anchor{library/doctest warnings}@anchor{3f46}
@subsubsection Avertissements


Le module @ref{3a,,doctest} est rigoureux pour ce qui est d'inclure des correspondances exactes dans la sortie attendue. Si un seul caractère ne correspond pas, le test échoue. Ceci vous surprendra probablement quelques fois, alors que vous apprenez exactement ce que Python garantit et ne garantit pas pour qui est des sorties. Par exemple, lorsqu'on affiche un ensemble (set), Python ne garantit pas que les éléments sont affichés dans un ordre particulier ; ainsi un test tel que

@example
>>> foo()
@{"spam", "eggs"@}
@end example

est vulnérable ! Une alternative est de faire

@example
>>> foo() == @{"spam", "eggs"@}
True
@end example

à la place. Une autre façon de faire est

@example
>>> d = sorted(foo())
>>> d
['eggs', 'spam']
@end example

Il y en a d'autres, mais vous saisissez l'idée.

Another bad idea is to print things that embed an object address, like

@example
>>> id(1.0)  # certain to fail some of the time  
7948648
>>> class C: pass
>>> C()  # the default repr() for instances embeds an address   
<C object at 0x00AC18F0>
@end example

The @ref{1422,,ELLIPSIS} directive gives a nice approach for the last example:

@example
>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>
@end example

Les nombres à virgule flottante sont aussi sujets à de petites variations à la sortie, tout dépendamment de la plateforme utilisée, étant donné que Python s'en remet à la bibliothèque de la plateforme C pour la mise-en-forme des `floats', et les bibliothèques C varient grandement pour ce qui de leur qualité sur ce point.

@example
>>> 1./7  # risky
0.14285714285714285
>>> print(1./7) # safer
0.142857142857
>>> print(round(1./7, 6)) # much safer
0.142857
@end example

Numbers of the form @code{I/2.**J} are safe across all platforms, and I often
contrive doctest examples to produce numbers of that form:

@example
>>> 3./4  # utterly safe
0.75
@end example

Les fractions simples sont aussi plus faciles à comprendre, et cela fait une meilleure documentation.

@node API de base,API de tests unitaires,Comment ça marche,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest basic-api}@anchor{3f47}@anchor{library/doctest doctest-basic-api}@anchor{3f23}
@subsubsection API de base


Les fonctions @ref{1421,,testmod()} et @ref{3f26,,testfile()} fournissent une interface simple pour `doctest' qui est suffisante pour les cas d'usage les plus élémentaires. Pour une introduction moins formelle à ces deux fonctions, voir les sections @ref{3f21,,Utilisation simple ; vérifier des exemples dans des docstrings} et @ref{3f24,,Utilisation simple ; vérifier des exemples dans un fichier texte}.

@geindex testfile() (dans le module doctest)
@anchor{library/doctest doctest testfile}@anchor{3f26}
@deffn {Fonction} doctest.testfile (filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None)

Tous les arguments sauf `filename' sont optionnels, et doivent être précisés sous forme lettrée.

Teste les exemples dans le fichier nommé `filename'. Renvoie @code{(failure_count, test_count)}.

L'argument optionnel `module_relative' précise comment le nom de fichier doit être interprété :


@itemize *

@item 
Si `module_relative' prend la valeur @code{True} (la valeur par défaut), alors `filename' précise un chemin relatif au module qui soit indépendant du système d'exploitation (`OS'). Par défaut, ce chemin est relatif au répertoire du module appelant ; mais si l'argument `package' est précisé, alors il est relatif à ce paquet. Pour garantir l'indépendance quant au système d'exploitation, `filename' doit utiliser des caractères @code{/} pour séparer chaque segment de chemin, et ne peut pas être un chemin absolu (c'est-à-dire qu'il ne peut pas commencer par @code{/}).

@item 
Si `module_relative' prend la valeur @code{False}, alors `filename' précise un chemin en fonction du système d'exploitation. Le chemin peut être absolu ou relatif ; les chemins relatifs sont résolus en rapport au répertoire actif.
@end itemize

L'option `name' désigne le nom du test ; par défaut, ou si @code{None} est passé en argument, @code{os.path.basename(filename)} est utilisé.

L'option `package' est un paquet Python ou le nom d'un paquet Python dont le répertoire doit être utilisé comme le répertoire principal pour un nom de fichier lié à un module. Si aucun paquet n'est spécifié, le répertoire du module appelé à l'exécution est utilisé comme le répertoire principal pour les noms de fichiers liés au module. C'est une erreur que de spécifier `package' si `module_relative' a @code{False} comme valeur.

L'option `globs' spécifie un `dict' à utiliser comme `globals' lorsque des exemples sont exécutés. Une copie superficielle de ce `dict' est créée pour le `doctest' ; ainsi, ces exemples commencent avec un état vide. Par défaut, ou si @code{None} est passé en argument, un nouveau `dict' vide est utilisé.

L'option `extraglobs' spécifie un `dict' intégré dans les variables globales utilisées pour exécuter l'exemple. Ceci fonctionne comme @ref{1419,,dict.update()} : si `globs' et `extraglobs' ont une clé commune, la valeur associée à `extraglobs' apparaît dans le `dict' combiné. Par défaut, ou si @code{None} est passé en argument, aucune variable globale supplémentaire est utilisée. Ceci est une fonctionnalité avancée qui permet la configuration des `doctests'. Par exemple, un `doctest' peut être rédigé pour une classe de base, en utilisant un nom générique pour la classe, puis réutilisé afin de tester un nombre indéfini de sous-classes en passant un `dict' `extraglobs' reliant le nom générique à la sous-classe qui doit être testée.

L'option `verbose' affiche une grande quantité d'information si elle est vraie, et affiche uniquement les défaillances si elle est fausse ; par défaut, ou si @code{None}, celle-ci est vraie si et seulement si @code{-v} est présent dans @code{sys.argv}.

L'option `report' affiche un résumé à la fin lorsque vraie ; sinon, rien n'est affiché à la fin. En mode `verbose', le résumé est détaillé, sinon le résumé est très bref (en fait, vide si tous les tests ont réussi).

L'option `optionflags' (dont la valeur par défaut est de zéro) calcule la valeur @ref{1ff1,,bitwise OR} des options de ligne de commande. Voir la section @ref{f1e,,Options de ligne de commande}.

L'option `raise_on_error' est fausse par défaut. Si elle est vraie, une exception est levée à la première défaillance ou à la première exception qui ne soit prévue dans l'exemple. Ceci permet aux défaillances d'être analysées lors d'un post-mortem. Le comportement par défaut est de poursuivre l'exécution des exemples.

L'option `parser' définit une classe ou une sous-classe @ref{3f2f,,DocTestParser} qui doit être utilisée pour extraire les tests des fichiers. Par défaut, on utilise un analyseur normal (c'est-à-dire, @code{DocTestParser()}).

L'option `encoding' définit un encodage à utiliser pour convertir le fichier en format `unicode'.
@end deffn

@geindex testmod() (dans le module doctest)
@anchor{library/doctest doctest testmod}@anchor{1421}
@deffn {Fonction} doctest.testmod (m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False)

Toutes les options sont facultatives, et toutes sauf `m' doivent être définies en format lettré.

Ceci teste les exemples en `docstrings' dans les fonctions et les classes accessibles depuis le module `m' (ou depuis le module @ref{1,,__main__} si `m' n'a pas été défini ou est @code{None}), en commençant par @code{m.__doc__}.

Also test examples reachable from dict @code{m.__test__}, if it exists.
@code{m.__test__} maps names (strings) to functions, classes and
strings; function and class docstrings are searched for examples; strings are
searched directly, as if they were docstrings.

Seulement les `docstrings' attribuées à des objets appartenant au module `m' sont fouillées.

Renvoie @code{(failure_count, test_count)}.

L'option `name' donne le nom du module ; par défaut, ou si @code{None}, @code{m.__name__} est utilisé.

Optional argument `exclude_empty' defaults to false.  If true, objects for which
no doctests are found are excluded from consideration. The default is a backward
compatibility hack, so that code still using
@ref{3f48,,doctest.master.summarize} in
conjunction with @ref{1421,,testmod()} continues to get output for objects with no
tests. The `exclude_empty' argument to the newer @ref{15bb,,DocTestFinder}
constructor defaults to true.

Les options `extraglobs', `verbose', `report', `optionflags', `raise_on_error', et `globs' sont les mêmes que pour la fonction @ref{3f26,,testfile()} ci-dessus, sauf pour `globs', qui est @code{m.__dict__} par défaut.
@end deffn

@geindex run_docstring_examples() (dans le module doctest)
@anchor{library/doctest doctest run_docstring_examples}@anchor{3f49}
@deffn {Fonction} doctest.run_docstring_examples (f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0)

Les exemples de test associés à l'objet `f' ; par exemple, `f' peut être une chaîne de caractères, un module, une fonction, ou un objet de classe.

Une copie superficielle de l'argument-dictionnaire `globs' est utilisée pour le contexte d'exécution.

L'option `name' est utilisée pour les messages d'échec, et prend @code{"NoName"} comme valeur par défaut.

Si l'option `verbose' est vraie, les sorties sont générées même s'il n'y a aucun échec. Par défaut, la sortie est générée seulement si un exemple échoue.

L'option `compileflags' donne l'ensemble des options qui doit être utilisée par le compilateur Python lorsqu'il exécute les exemples. Par défaut, ou si @code{None}, les options sont inférées à partir de l'ensemble des fonctionnalités futures trouvées dans `globs'.

L'option `optionflags' fonctionne similairement à la fonction @ref{3f26,,testfile()} ci-dessus.
@end deffn

@node API de tests unitaires,API avancé,API de base,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest doctest-unittest-api}@anchor{3f4a}@anchor{library/doctest unittest-api}@anchor{3f4b}
@subsubsection API de tests unitaires


As your collection of doctest'ed modules grows, you'll want a way to run all
their doctests systematically.  @ref{3a,,doctest} provides two functions that can
be used to create @ref{105,,unittest} test suites from modules and text files
containing doctests.  To integrate with @ref{105,,unittest} test discovery, include
a @ref{3f4c,,load_tests} function in your test module:

@example
import unittest
import doctest
import my_module_with_doctests

def load_tests(loader, tests, ignore):
    tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
    return tests
@end example

Il y a deux fonctions principales pour créer des instances de la classe @ref{de1,,unittest.TestSuite} à partir de fichiers textes et de modules ayant des `doctests' :

@geindex DocFileSuite() (dans le module doctest)
@anchor{library/doctest doctest DocFileSuite}@anchor{3f4d}
@deffn {Fonction} doctest.DocFileSuite (*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None)

Convertit des tests `doctest' à partir d'un ou plusieurs fichiers vers une classe @ref{de1,,unittest.TestSuite}.

The returned @ref{de1,,unittest.TestSuite} is to be run by the unittest framework
and runs the interactive examples in each file.  If an example in any file
fails, then the synthesized unit test fails, and a @ref{3f4e,,failureException}
exception is raised showing the name of the file containing the test and a
(sometimes approximate) line number.  If all the examples in a file are
skipped, then the synthesized unit test is also marked as skipped.

Passe un ou plusieurs chemins (sous forme de chaînes de caractères) à des fichiers textes afin d'être vérifiés.

Les options peuvent être fournies comme des options lettrées :

L'option `module_relative' précise comment les noms de fichiers dans `paths' doivent être interprétés :


@itemize *

@item 
Si `module_relative' a @code{True} comme valeur (valeur par défaut), alors chaque nom de fichier dans `paths' précise un chemin relatif au module qui soit indépendant du système d'exploitation. Par défaut, ce chemin est relatif au répertoire du module appelant ; mais si l'option `package' est précisée, alors il est relatif à ce paquet. Afin de garantir l'indépendance face au système d'exploitation, chaque nom de fichier doit utiliser des caractères @code{/} afin de séparer les segments de chemin, et ne peut pas être un chemin absolu (c'est-à-dire, il ne peut pas commencer par @code{/}).

@item 
Si `module_relative' prend la valeur @code{False}, alors `filename' précise un chemin en fonction du système d'exploitation. Le chemin peut être absolu ou relatif ; les chemins relatifs sont résolus en rapport au répertoire actif.
@end itemize

L'option `package' est un paquet Python ou le nom d'un paquet Python dont le répertoire dont être utilisé comme le répertoire principal pour un nom de fichier dans `paths' qui soit lié à un module. Si aucun paquet n'est spécifié, le répertoire du module appelé à l'exécution est utilisé comme le répertoire principal pour les noms de fichiers liés au module. C'est une erreur que de spécifier `package' si `module_relative' a @code{False} comme valeur.

L'option `setUp' précise une fonction de mise-en-place pour la suite de tests. Ceci est appelé avant l'exécution des tests dans chaque fichier. La fonction `setUp' est passée à un objet @ref{163b,,DocTest}. La fonction `setUp' peut accéder aux valeurs globales du test par le biais de l'attribut `globs' du test passé.

L'option `tearDown' précise une fonction de démolition pour la suite de tests. Celle-ci est appelée après avoir exécuté les tests dans chaque fichier. La fonction `tearDown' est passée à un objet @ref{163b,,DocTest}. La fonction `setUp' peut accéder aux valeurs globales du test par l'attribut `globs' du test passé.

L'option `globs' est un dictionnaire contenant les variables globales initiales pour les tests. Une nouvelle copie de ce dictionnaire est créée pour chaque test. Par défaut, `globs' est un nouveau dictionnaire vide.

Les options `optionflags' précisent les options par défaut de `doctest' pour les tests, créées en composant par un OU les différentes options individuelles. Voir la section @ref{f1e,,Options de ligne de commande}. Voir la fonction @ref{3f4f,,set_unittest_reportflags()} ci-dessous pour une meilleure façon de préciser des options de rapport.

L'option `parser' définit une classe ou une sous-classe @ref{3f2f,,DocTestParser} qui doit être utilisée pour extraire les tests des fichiers. Par défaut, on utilise un analyseur normal (c'est-à-dire, @code{DocTestParser()}).

L'option `encoding' définit un encodage à utiliser pour convertir le fichier en format `unicode'.

La valeur globale @code{__file__} est ajoutée aux valeurs globales fournies par les `doctests', ceux-ci étant téléchargés d'un fichier texte utilisant la fonction @ref{3f4d,,DocFileSuite()}.
@end deffn

@geindex DocTestSuite() (dans le module doctest)
@anchor{library/doctest doctest DocTestSuite}@anchor{de0}
@deffn {Fonction} doctest.DocTestSuite (module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, optionflags=0, checker=None)

Convertit les tests `doctest' pour un module donné à une classe @ref{de1,,unittest.TestSuite}.

The returned @ref{de1,,unittest.TestSuite} is to be run by the unittest framework
and runs each doctest in the module.  If any of the doctests fail, then the
synthesized unit test fails, and a @ref{3f4e,,failureException} exception is raised
showing the name of the file containing the test and a (sometimes approximate)
line number.  If all the examples in a docstring are skipped, then the
synthesized unit test is also marked as skipped.

L'option `module' fournit le module qui sera testé. Il peut prendre la forme d'un objet-module ou celle du nom d'un module (possiblement `dotted'). Si non-précisée, le module appelant cette fonction est utilisé.

L'option `globs' est un dictionnaire contenant les variables globales initiales pour les tests. Une nouvelle copie de ce dictionnaire est créée pour chaque test. Par défaut, `globs' est un nouveau dictionnaire vide.

L'option `extraglobs' précise un ensemble supplémentaire de variables globales, à fusionner avec `globs'. Par défaut, aucune variable globale supplémentaire est utilisée.

L'option `test_finder' est l'instance de @ref{15bb,,DocTestFinder} (ou un remplacement `drop-in') qui est utilisée pour extraire les `doctests' à partir du module.

Les options `setUp', `tearDown' et `optionflags' sont les mêmes que pour la fonction @ref{3f4d,,DocFileSuite()} ci-dessus.

Cette fonction utilise la même technique de recherche que @ref{1421,,testmod()}.


Modifié dans la version 3.5: La fonction @ref{de0,,DocTestSuite()} renvoie une instance vide de la classe @ref{de1,,unittest.TestSuite} si `module' ne contient aucune `docstring', et ce, au lieu de lever l'exception @ref{1ff,,ValueError}.

@end deffn

@geindex failureException
@anchor{library/doctest doctest failureException}@anchor{3f4e}
@deffn {Exception} doctest.failureException

When doctests which have been converted to unit tests by @ref{3f4d,,DocFileSuite()}
or @ref{de0,,DocTestSuite()} fail, this exception is raised showing the name of
the file containing the test and a (sometimes approximate) line number.
@end deffn

Under the covers, @ref{de0,,DocTestSuite()} creates a @ref{de1,,unittest.TestSuite} out
of @code{doctest.DocTestCase} instances, and @code{DocTestCase} is a
subclass of @ref{437,,unittest.TestCase}. @code{DocTestCase} isn't documented
here (it's an internal detail), but studying its code can answer questions about
the exact details of @ref{105,,unittest} integration.

Similarly, @ref{3f4d,,DocFileSuite()} creates a @ref{de1,,unittest.TestSuite} out of
@code{doctest.DocFileCase} instances, and @code{DocFileCase} is a subclass
of @code{DocTestCase}.

So both ways of creating a @ref{de1,,unittest.TestSuite} run instances of
@code{DocTestCase}.  This is important for a subtle reason: when you run
@ref{3a,,doctest} functions yourself, you can control the @ref{3a,,doctest} options in
use directly, by passing option flags to @ref{3a,,doctest} functions.  However, if
you're writing a @ref{105,,unittest} framework, @ref{105,,unittest} ultimately controls
when and how tests get run.  The framework author typically wants to control
@ref{3a,,doctest} reporting options (perhaps, e.g., specified by command line
options), but there's no way to pass options through @ref{105,,unittest} to
@ref{3a,,doctest} test runners.

Pour cette raison, @ref{3a,,doctest} implémente le concept d'options de rapport de @ref{3a,,doctest} qui soit spécifique à @ref{105,,unittest}, par le biais de cette fonction :

@geindex set_unittest_reportflags() (dans le module doctest)
@anchor{library/doctest doctest set_unittest_reportflags}@anchor{3f4f}
@deffn {Fonction} doctest.set_unittest_reportflags (flags)

Voir les options de ligne de commandes de @ref{3a,,doctest} pour l'utilisation.

L'argument `flags' prend la @ref{1ff1,,composition OU bit à bit} des arguments. Voir la section @ref{f1e,,Options de ligne de commande}. Ce sont uniquement les "options de rapport" qui peuvent être utilisées.

This is a module-global setting, and affects all future doctests run by module
@ref{105,,unittest}:  the @code{runTest()} method of @code{DocTestCase} looks at
the option flags specified for the test case when the @code{DocTestCase}
instance was constructed.  If no reporting flags were specified (which is the
typical and expected case), @code{doctest}'s @ref{105,,unittest} reporting flags are
@ref{1ff1,,bitwise ORed} into the option flags, and the option flags
so augmented are passed to the @ref{3f3e,,DocTestRunner} instance created to
run the doctest.  If any reporting flags were specified when the
@code{DocTestCase} instance was constructed, @code{doctest}'s
@ref{105,,unittest} reporting flags are ignored.

La valeur prise par les options de rapport de @ref{105,,unittest} et ce, avant que la fonction n'ait été appelée, est renvoyée par la fonction.
@end deffn

@node API avancé,Débogage,API de tests unitaires,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest advanced-api}@anchor{3f50}@anchor{library/doctest doctest-advanced-api}@anchor{3f51}
@subsubsection API avancé


The basic API is a simple wrapper that's intended to make doctest easy to use.
It is fairly flexible, and should meet most users' needs; however, if you
require more fine-grained control over testing, or wish to extend doctest's
capabilities, then you should use the advanced API.

The advanced API revolves around two container classes, which are used to store
the interactive examples extracted from doctest cases:


@itemize *

@item 
@ref{3f52,,Example} : Un unique @ref{2704,,statement} Python, pris conjointement avec sa sortie attendue.

@item 
@ref{163b,,DocTest} : Une collection de @ref{3f52,,Example}, habituellement extraits d'une seule `docstring' ou fichier texte.
@end itemize

Additional processing classes are defined to find, parse, and run, and check
doctest examples:


@itemize *

@item 
@ref{15bb,,DocTestFinder}: Finds all docstrings in a given module, and uses a
@ref{3f2f,,DocTestParser} to create a @ref{163b,,DocTest} from every docstring that
contains interactive examples.

@item 
@ref{3f2f,,DocTestParser}: Creates a @ref{163b,,DocTest} object from a string (such
as an object's docstring).

@item 
@ref{3f3e,,DocTestRunner}: Executes the examples in a @ref{163b,,DocTest}, and uses
an @ref{3f3d,,OutputChecker} to verify their output.

@item 
@ref{3f3d,,OutputChecker}: Compares the actual output from a doctest example with
the expected output, and decides whether they match.
@end itemize

The relationships among these processing classes are summarized in the following
diagram:

@example
                            list of:
+------+                   +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+    |        ^     +---------+     |       ^    (printed)
            |        |     | Example |     |       |
            v        |     |   ...   |     v       |
           DocTestParser   | Example |   OutputChecker
                           +---------+
@end example

@menu
* Objets doctest:: 
* Exemples d'objets:: 
* Objets DocTestFinder:: 
* Objets DocTestParser:: 
* Objets TestResults:: 
* Objets DocTestRunner:: 
* Objets OutputChecker:: 

@end menu

@node Objets doctest,Exemples d'objets,,API avancé
@anchor{library/doctest doctest-doctest}@anchor{3f53}@anchor{library/doctest doctest-objects}@anchor{3f54}
@subsubsection Objets `doctest'


@geindex DocTest (classe dans doctest)
@anchor{library/doctest doctest DocTest}@anchor{163b}
@deffn {Classe} doctest.DocTest (examples, globs, name, filename, lineno, docstring)

A collection of doctest examples that should be run in a single namespace.  The
constructor arguments are used to initialize the attributes of the same names.

@ref{163b,,DocTest} définit les attributs suivants. Ils sont initialisés par le constructeur, et ne doivent pas être modifiés directement.

@geindex examples (attribut doctest.DocTest)
@anchor{library/doctest doctest DocTest examples}@anchor{3f55}
@deffn {Attribut} examples

A list of @ref{3f52,,Example} objects encoding the individual interactive Python
examples that should be run by this test.
@end deffn

@geindex globs (attribut doctest.DocTest)
@anchor{library/doctest doctest DocTest globs}@anchor{3f56}
@deffn {Attribut} globs

The namespace (aka globals) that the examples should be run in. This is a
dictionary mapping names to values.  Any changes to the namespace made by the
examples (such as binding new variables) will be reflected in @ref{3f56,,globs}
after the test is run.
@end deffn

@geindex name (attribut doctest.DocTest)
@anchor{library/doctest doctest DocTest name}@anchor{3f57}
@deffn {Attribut} name

A string name identifying the @ref{163b,,DocTest}.  Typically, this is the name
of the object or file that the test was extracted from.
@end deffn

@geindex filename (attribut doctest.DocTest)
@anchor{library/doctest doctest DocTest filename}@anchor{3f58}
@deffn {Attribut} filename

The name of the file that this @ref{163b,,DocTest} was extracted from; or
@code{None} if the filename is unknown, or if the @ref{163b,,DocTest} was not
extracted from a file.
@end deffn

@geindex lineno (attribut doctest.DocTest)
@anchor{library/doctest doctest DocTest lineno}@anchor{176d}
@deffn {Attribut} lineno

The line number within @ref{3f58,,filename} where this @ref{163b,,DocTest} begins, or
@code{None} if the line number is unavailable.  This line number is zero-based
with respect to the beginning of the file.
@end deffn

@geindex docstring (attribut doctest.DocTest)
@anchor{library/doctest doctest DocTest docstring}@anchor{3f59}
@deffn {Attribut} docstring

The string that the test was extracted from, or @code{None} if the string is
unavailable, or if the test was not extracted from a string.
@end deffn
@end deffn

@node Exemples d'objets,Objets DocTestFinder,Objets doctest,API avancé
@anchor{library/doctest doctest-example}@anchor{3f5a}@anchor{library/doctest example-objects}@anchor{3f5b}
@subsubsection Exemples d'objets


@geindex Example (classe dans doctest)
@anchor{library/doctest doctest Example}@anchor{3f52}
@deffn {Classe} doctest.Example (source, want, exc_msg=None, lineno=0, indent=0, options=None)

A single interactive example, consisting of a Python statement and its expected
output.  The constructor arguments are used to initialize the attributes of
the same names.

@ref{3f52,,Example} defines the following attributes.  They are initialized by
the constructor, and should not be modified directly.

@geindex source (attribut doctest.Example)
@anchor{library/doctest doctest Example source}@anchor{3f5c}
@deffn {Attribut} source

A string containing the example's source code.  This source code consists of a
single Python statement, and always ends with a newline; the constructor adds
a newline when necessary.
@end deffn

@geindex want (attribut doctest.Example)
@anchor{library/doctest doctest Example want}@anchor{3f5d}
@deffn {Attribut} want

The expected output from running the example's source code (either from
stdout, or a traceback in case of exception).  @ref{3f5d,,want} ends with a
newline unless no output is expected, in which case it's an empty string.  The
constructor adds a newline when necessary.
@end deffn

@geindex exc_msg (attribut doctest.Example)
@anchor{library/doctest doctest Example exc_msg}@anchor{3f5e}
@deffn {Attribut} exc_msg

The exception message generated by the example, if the example is expected to
generate an exception; or @code{None} if it is not expected to generate an
exception.  This exception message is compared against the return value of
@ref{838,,traceback.format_exception_only()}.  @ref{3f5e,,exc_msg} ends with a newline
unless it's @code{None}.  The constructor adds a newline if needed.
@end deffn

@geindex lineno (attribut doctest.Example)
@anchor{library/doctest doctest Example lineno}@anchor{3f5f}
@deffn {Attribut} lineno

The line number within the string containing this example where the example
begins.  This line number is zero-based with respect to the beginning of the
containing string.
@end deffn

@geindex indent (attribut doctest.Example)
@anchor{library/doctest doctest Example indent}@anchor{3f60}
@deffn {Attribut} indent

The example's indentation in the containing string, i.e., the number of space
characters that precede the example's first prompt.
@end deffn

@geindex options (attribut doctest.Example)
@anchor{library/doctest doctest Example options}@anchor{3f61}
@deffn {Attribut} options

A dictionary mapping from option flags to @code{True} or @code{False}, which is used
to override default options for this example.  Any option flags not contained
in this dictionary are left at their default value (as specified by the
@ref{3f3e,,DocTestRunner}'s @ref{f1e,,optionflags}).
By default, no options are set.
@end deffn
@end deffn

@node Objets DocTestFinder,Objets DocTestParser,Exemples d'objets,API avancé
@anchor{library/doctest doctest-doctestfinder}@anchor{3f62}@anchor{library/doctest doctestfinder-objects}@anchor{3f63}
@subsubsection Objets `DocTestFinder'


@geindex DocTestFinder (classe dans doctest)
@anchor{library/doctest doctest DocTestFinder}@anchor{15bb}
@deffn {Classe} doctest.DocTestFinder (verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)

A processing class used to extract the @ref{163b,,DocTest}s that are relevant to
a given object, from its docstring and the docstrings of its contained objects.
@ref{163b,,DocTest}s can be extracted from modules, classes, functions,
methods, staticmethods, classmethods, and properties.

The optional argument `verbose' can be used to display the objects searched by
the finder.  It defaults to @code{False} (no output).

The optional argument `parser' specifies the @ref{3f2f,,DocTestParser} object (or a
drop-in replacement) that is used to extract doctests from docstrings.

If the optional argument `recurse' is false, then @ref{1688,,DocTestFinder.find()}
will only examine the given object, and not any contained objects.

If the optional argument `exclude_empty' is false, then
@ref{1688,,DocTestFinder.find()} will include tests for objects with empty docstrings.

La classe @ref{15bb,,DocTestFinder} définit la méthode suivante :

@geindex find() (méthode doctest.DocTestFinder)
@anchor{library/doctest doctest DocTestFinder find}@anchor{1688}
@deffn {Méthode} find (obj[, name][, module][, globs][, extraglobs])

Return a list of the @ref{163b,,DocTest}s that are defined by `obj''s
docstring, or by any of its contained objects' docstrings.

The optional argument `name' specifies the object's name; this name will be
used to construct names for the returned @ref{163b,,DocTest}s.  If `name' is
not specified, then @code{obj.__name__} is used.

The optional parameter `module' is the module that contains the given object.
If the module is not specified or is @code{None}, then the test finder will attempt
to automatically determine the correct module.  The object's module is used:


@itemize *

@item 
As a default namespace, if `globs' is not specified.

@item 
To prevent the DocTestFinder from extracting DocTests from objects that are
imported from other modules.  (Contained objects with modules other than
`module' are ignored.)

@item 
Afin de trouver le nom du fichier contenant l'objet.

@item 
To help find the line number of the object within its file.
@end itemize

If `module' is @code{False}, no attempt to find the module will be made.  This is
obscure, of use mostly in testing doctest itself: if `module' is @code{False}, or
is @code{None} but cannot be found automatically, then all objects are considered
to belong to the (non-existent) module, so all contained objects will
(recursively) be searched for doctests.

The globals for each @ref{163b,,DocTest} is formed by combining `globs' and
`extraglobs' (bindings in `extraglobs' override bindings in `globs').  A new
shallow copy of the globals dictionary is created for each @ref{163b,,DocTest}.
If `globs' is not specified, then it defaults to the module's `__dict__', if
specified, or @code{@{@}} otherwise.  If `extraglobs' is not specified, then it
defaults to @code{@{@}}.
@end deffn
@end deffn

@node Objets DocTestParser,Objets TestResults,Objets DocTestFinder,API avancé
@anchor{library/doctest doctest-doctestparser}@anchor{3f64}@anchor{library/doctest doctestparser-objects}@anchor{3f65}
@subsubsection Objets `DocTestParser'


@geindex DocTestParser (classe dans doctest)
@anchor{library/doctest doctest DocTestParser}@anchor{3f2f}
@deffn {Classe} doctest.DocTestParser

A processing class used to extract interactive examples from a string, and use
them to create a @ref{163b,,DocTest} object.

La classe @ref{15bb,,DocTestFinder} définit les méthodes suivantes :

@geindex get_doctest() (méthode doctest.DocTestParser)
@anchor{library/doctest doctest DocTestParser get_doctest}@anchor{3f66}
@deffn {Méthode} get_doctest (string, globs, name, filename, lineno)

Extrait tous les exemples de `doctests' à partir de la chaîne de caractère donnée, et les réunit dans un objet @ref{163b,,DocTest}.

Notez que `globs', `name', `filname' et `lineno' sont des attributs pour le nouvel objet @ref{163b,,DocTest}. Voir la documentation pour @ref{163b,,DocTest} pour plus d'information.
@end deffn

@geindex get_examples() (méthode doctest.DocTestParser)
@anchor{library/doctest doctest DocTestParser get_examples}@anchor{3f67}
@deffn {Méthode} get_examples (string, name='<string>')

Extract all doctest examples from the given string, and return them as a list
of @ref{3f52,,Example} objects.  Line numbers are 0-based.  The optional argument
`name' is a name identifying this string, and is only used for error messages.
@end deffn

@geindex parse() (méthode doctest.DocTestParser)
@anchor{library/doctest doctest DocTestParser parse}@anchor{3f68}
@deffn {Méthode} parse (string, name='<string>')

Divide the given string into examples and intervening text, and return them as
a list of alternating @ref{3f52,,Example}s and strings. Line numbers for the
@ref{3f52,,Example}s are 0-based.  The optional argument `name' is a name
identifying this string, and is only used for error messages.
@end deffn
@end deffn

@node Objets TestResults,Objets DocTestRunner,Objets DocTestParser,API avancé
@anchor{library/doctest testresults-objects}@anchor{3f69}
@subsubsection Objets `TestResults'


@geindex TestResults (classe dans doctest)
@anchor{library/doctest doctest TestResults}@anchor{3f6a}
@deffn {Classe} doctest.TestResults (failed, attempted)

@geindex failed (attribut doctest.TestResults)
@anchor{library/doctest doctest TestResults failed}@anchor{3f6b}
@deffn {Attribut} failed

Nombre de tests échoués.
@end deffn

@geindex attempted (attribut doctest.TestResults)
@anchor{library/doctest doctest TestResults attempted}@anchor{3f6c}
@deffn {Attribut} attempted

Nombre de tests tentés.
@end deffn

@geindex skipped (attribut doctest.TestResults)
@anchor{library/doctest doctest TestResults skipped}@anchor{1db}
@deffn {Attribut} skipped

Nombre de tests sautés.


Ajouté dans la version 3.13.

@end deffn
@end deffn

@node Objets DocTestRunner,Objets OutputChecker,Objets TestResults,API avancé
@anchor{library/doctest doctest-doctestrunner}@anchor{3f6d}@anchor{library/doctest doctestrunner-objects}@anchor{3f6e}
@subsubsection Objets `DocTestRunner'


@geindex DocTestRunner (classe dans doctest)
@anchor{library/doctest doctest DocTestRunner}@anchor{3f3e}
@deffn {Classe} doctest.DocTestRunner (checker=None, verbose=None, optionflags=0)

A processing class used to execute and verify the interactive examples in a
@ref{163b,,DocTest}.

The comparison between expected outputs and actual outputs is done by an
@ref{3f3d,,OutputChecker}.  This comparison may be customized with a number of
option flags; see section @ref{f1e,,Options de ligne de commande} for more information.  If the
option flags are insufficient, then the comparison may also be customized by
passing a subclass of @ref{3f3d,,OutputChecker} to the constructor.

The test runner's display output can be controlled in two ways. First, an output
function can be passed to @ref{1d9,,run()}; this function will be called
with strings that should be displayed.  It defaults to @code{sys.stdout.write}.  If
capturing the output is not sufficient, then the display output can be also
customized by subclassing DocTestRunner, and overriding the methods
@ref{3f6f,,report_start()}, @ref{3f70,,report_success()},
@ref{3f71,,report_unexpected_exception()}, and @ref{3f72,,report_failure()}.

The optional keyword argument `checker' specifies the @ref{3f3d,,OutputChecker}
object (or drop-in replacement) that should be used to compare the expected
outputs to the actual outputs of doctest examples.

The optional keyword argument `verbose' controls the @ref{3f3e,,DocTestRunner}'s
verbosity.  If `verbose' is @code{True}, then information is printed about each
example, as it is run.  If `verbose' is @code{False}, then only failures are
printed.  If `verbose' is unspecified, or @code{None}, then verbose output is used
iff the command-line switch @code{-v} is used.

The optional keyword argument `optionflags' can be used to control how the test
runner compares expected output to actual output, and how it displays failures.
For more information, see section @ref{f1e,,Options de ligne de commande}.

The test runner accumulates statistics. The aggregated number of attempted,
failed and skipped examples is also available via the @ref{3f73,,tries},
@ref{3f74,,failures} and @ref{1da,,skips} attributes. The @ref{1d9,,run()} and
@ref{3f48,,summarize()} methods return a @ref{3f6a,,TestResults} instance.

La classe @ref{3f3e,,DocTestRunner} définit les méthodes suivantes :

@geindex report_start() (méthode doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_start}@anchor{3f6f}
@deffn {Méthode} report_start (out, test, example)

Report that the test runner is about to process the given example. This method
is provided to allow subclasses of @ref{3f3e,,DocTestRunner} to customize their
output; it should not be called directly.

`example' is the example about to be processed.  `test' is the test
`containing example'.  `out' is the output function that was passed to
@ref{1d9,,DocTestRunner.run()}.
@end deffn

@geindex report_success() (méthode doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_success}@anchor{3f70}
@deffn {Méthode} report_success (out, test, example, got)

Report that the given example ran successfully.  This method is provided to
allow subclasses of @ref{3f3e,,DocTestRunner} to customize their output; it
should not be called directly.

`example' is the example about to be processed.  `got' is the actual output
from the example.  `test' is the test containing `example'.  `out' is the
output function that was passed to @ref{1d9,,DocTestRunner.run()}.
@end deffn

@geindex report_failure() (méthode doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_failure}@anchor{3f72}
@deffn {Méthode} report_failure (out, test, example, got)

Report that the given example failed.  This method is provided to allow
subclasses of @ref{3f3e,,DocTestRunner} to customize their output; it should not
be called directly.

`example' is the example about to be processed.  `got' is the actual output
from the example.  `test' is the test containing `example'.  `out' is the
output function that was passed to @ref{1d9,,DocTestRunner.run()}.
@end deffn

@geindex report_unexpected_exception() (méthode doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner report_unexpected_exception}@anchor{3f71}
@deffn {Méthode} report_unexpected_exception (out, test, example, exc_info)

Report that the given example raised an unexpected exception. This method is
provided to allow subclasses of @ref{3f3e,,DocTestRunner} to customize their
output; it should not be called directly.

`example' is the example about to be processed. `exc_info' is a tuple
containing information about the unexpected exception (as returned by
@ref{675,,sys.exc_info()}). `test' is the test containing `example'.  `out' is the
output function that was passed to @ref{1d9,,DocTestRunner.run()}.
@end deffn

@geindex run() (méthode doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner run}@anchor{1d9}
@deffn {Méthode} run (test, compileflags=None, out=None, clear_globs=True)

Run the examples in `test' (a @ref{163b,,DocTest} object), and display the
results using the writer function `out'. Return a @ref{3f6a,,TestResults}
instance.

The examples are run in the namespace @code{test.globs}.  If `clear_globs' is
true (the default), then this namespace will be cleared after the test runs,
to help with garbage collection. If you would like to examine the namespace
after the test completes, then use `clear_globs=False'.

`compileflags' gives the set of flags that should be used by the Python
compiler when running the examples.  If not specified, then it will default to
the set of future-import flags that apply to `globs'.

The output of each example is checked using the @ref{3f3e,,DocTestRunner}'s
output checker, and the results are formatted by the
@code{DocTestRunner.report_*()} methods.
@end deffn

@geindex summarize() (méthode doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner summarize}@anchor{3f48}
@deffn {Méthode} summarize (verbose=None)

Print a summary of all the test cases that have been run by this DocTestRunner,
and return a @ref{3f6a,,TestResults} instance.

The optional `verbose' argument controls how detailed the summary is.  If the
verbosity is not specified, then the @ref{3f3e,,DocTestRunner}'s verbosity is
used.
@end deffn

@ref{3f2f,,DocTestParser} définit les attributs suivants :

@geindex tries (attribut doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner tries}@anchor{3f73}
@deffn {Attribut} tries

Number of attempted examples.
@end deffn

@geindex failures (attribut doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner failures}@anchor{3f74}
@deffn {Attribut} failures

Number of failed examples.
@end deffn

@geindex skips (attribut doctest.DocTestRunner)
@anchor{library/doctest doctest DocTestRunner skips}@anchor{1da}
@deffn {Attribut} skips

Number of skipped examples.


Ajouté dans la version 3.13.

@end deffn
@end deffn

@node Objets OutputChecker,,Objets DocTestRunner,API avancé
@anchor{library/doctest doctest-outputchecker}@anchor{3f75}@anchor{library/doctest outputchecker-objects}@anchor{3f76}
@subsubsection Objets `OutputChecker'


@geindex OutputChecker (classe dans doctest)
@anchor{library/doctest doctest OutputChecker}@anchor{3f3d}
@deffn {Classe} doctest.OutputChecker

A class used to check the whether the actual output from a doctest example
matches the expected output.  @ref{3f3d,,OutputChecker} defines two methods:
@ref{3f77,,check_output()}, which compares a given pair of outputs, and returns @code{True}
if they match; and @ref{3f78,,output_difference()}, which returns a string describing
the differences between two outputs.

La classe @ref{3f3d,,OutputChecker} définit les méthodes suivantes :

@geindex check_output() (méthode doctest.OutputChecker)
@anchor{library/doctest doctest OutputChecker check_output}@anchor{3f77}
@deffn {Méthode} check_output (want, got, optionflags)

Return @code{True} iff the actual output from an example (`got') matches the
expected output (`want').  These strings are always considered to match if
they are identical; but depending on what option flags the test runner is
using, several non-exact match types are also possible.  See section
@ref{f1e,,Options de ligne de commande} for more information about option flags.
@end deffn

@geindex output_difference() (méthode doctest.OutputChecker)
@anchor{library/doctest doctest OutputChecker output_difference}@anchor{3f78}
@deffn {Méthode} output_difference (example, got, optionflags)

Return a string describing the differences between the expected output for a
given example (`example') and the actual output (`got').  `optionflags' is the
set of option flags used to compare `want' and `got'.
@end deffn
@end deffn

@node Débogage,Éditorial,API avancé,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest debugging}@anchor{3f79}@anchor{library/doctest doctest-debugging}@anchor{3f7a}
@subsubsection Débogage


`Doctest' fournit plusieurs mécanismes pour déboguer des exemples `doctest' :


@itemize *

@item 
Plusieurs fonctions convertissent les `doctests' en programmes Python exécutables, qui peuvent être exécutés grâce au débogueur Python, @ref{a4,,pdb}.

@item 
The @ref{3f7b,,DebugRunner} class is a subclass of @ref{3f3e,,DocTestRunner} that
raises an exception for the first failing example, containing information about
that example. This information can be used to perform post-mortem debugging on
the example.

@item 
The @ref{105,,unittest} cases generated by @ref{de0,,DocTestSuite()} support the
@ref{3f7c,,debug()} method defined by @ref{437,,unittest.TestCase}.

@item 
You can add a call to @ref{232,,pdb.set_trace()} in a doctest example, and you'll
drop into the Python debugger when that line is executed.  Then you can inspect
current values of variables, and so on.  For example, suppose @code{a.py}
contains just this module docstring:

@example
"""
>>> def f(x):
...     g(x*2)
>>> def g(x):
...     print(x+3)
...     import pdb; pdb.set_trace()
>>> f(3)
9
"""
@end example

Alors une séance interactive de Python peut ressembler à ceci :

@example
>>> import a, doctest
>>> doctest.testmod(a)
--Return--
> <doctest a[1]>(3)g()->None
-> import pdb; pdb.set_trace()
(Pdb) list
  1     def g(x):
  2         print(x+3)
  3  ->     import pdb; pdb.set_trace()
[EOF]
(Pdb) p x
6
(Pdb) step
--Return--
> <doctest a[0]>(2)f()->None
-> g(x*2)
(Pdb) list
  1     def f(x):
  2  ->     g(x*2)
[EOF]
(Pdb) p x
3
(Pdb) step
--Return--
> <doctest a[2]>(1)?()->None
-> f(3)
(Pdb) cont
(0, 3)
>>>
@end example
@end itemize

Functions that convert doctests to Python code, and possibly run the synthesized
code under the debugger:

@geindex script_from_examples() (dans le module doctest)
@anchor{library/doctest doctest script_from_examples}@anchor{3f7d}
@deffn {Fonction} doctest.script_from_examples (s)

Convertit du texte contenant des exemples en un script.

Argument `s' is a string containing doctest examples.  The string is converted
to a Python script, where doctest examples in `s' are converted to regular code,
and everything else is converted to Python comments.  The generated script is
returned as a string. For example,

@example
import doctest
print(doctest.script_from_examples(r"""
    Set x and y to 1 and 2.
    >>> x, y = 1, 2

    Print their sum:
    >>> print(x+y)
    3
"""))
@end example

affiche:

@example
# Set x and y to 1 and 2.
x, y = 1, 2
#
# Print their sum:
print(x+y)
# Expected:
## 3
@end example

Cette fonction est utilisée à l'interne par d'autres fonctions (voir ci-bas), mais peut aussi être utile lorsque l'on souhaite transformer une séance interactive de Python en script Python.
@end deffn

@geindex testsource() (dans le module doctest)
@anchor{library/doctest doctest testsource}@anchor{3f7e}
@deffn {Fonction} doctest.testsource (module, name)

Convertit en script l'objet `doctest'.

Argument `module' is a module object, or dotted name of a module, containing the
object whose doctests are of interest.  Argument `name' is the name (within the
module) of the object with the doctests of interest.  The result is a string,
containing the object's docstring converted to a Python script, as described for
@ref{3f7d,,script_from_examples()} above.  For example, if module @code{a.py}
contains a top-level function @code{f()}, then

@example
import a, doctest
print(doctest.testsource(a, "a.f"))
@end example

prints a script version of function @code{f()}'s docstring, with doctests
converted to code, and the rest placed in comments.
@end deffn

@geindex debug() (dans le module doctest)
@anchor{library/doctest doctest debug}@anchor{3f7c}
@deffn {Fonction} doctest.debug (module, name, pm=False)

Débogue les `doctests' pour un objet.

The `module' and `name' arguments are the same as for function
@ref{3f7e,,testsource()} above.  The synthesized Python script for the named object's
docstring is written to a temporary file, and then that file is run under the
control of the Python debugger, @ref{a4,,pdb}.

Une copie superficielle de @code{module.__dict__} est utilisée à la fois pour les contextes d'exécution locaux et globaux.

Optional argument `pm' controls whether post-mortem debugging is used.  If `pm'
has a true value, the script file is run directly, and the debugger gets
involved only if the script terminates via raising an unhandled exception.  If
it does, then post-mortem debugging is invoked, via @ref{1391,,pdb.post_mortem()},
passing the traceback object from the unhandled exception.  If `pm' is not
specified, or is false, the script is run under the debugger from the start, via
passing an appropriate @ref{17d,,exec()} call to @ref{3f7f,,pdb.run()}.
@end deffn

@geindex debug_src() (dans le module doctest)
@anchor{library/doctest doctest debug_src}@anchor{3f80}
@deffn {Fonction} doctest.debug_src (src, pm=False, globs=None)

Débogue les `doctests' dans une chaîne de caractères.

Ceci est similaire à la fonction @ref{3f7c,,debug()} décrite ci-haut, mis-à-part qu'une chaîne de caractères contenant des exemples `doctest' est définie directement, par l'option `src'.

L'option `pm' a la même définition que dans la fonction @ref{3f7c,,debug()} ci-haut.

L'option `globs' définit un dictionnaire à utiliser comme contexte d'exécution global et local. Si elle n'est pas définie, ou si @code{None}, un dictionnaire vide est utilisé. Si définie, une copie superficielle du dictionnaire est utilisée.
@end deffn

The @ref{3f7b,,DebugRunner} class, and the special exceptions it may raise, are of
most interest to testing framework authors, and will only be sketched here.  See
the source code, and especially @ref{3f7b,,DebugRunner}'s docstring (which is a
doctest!) for more details:

@geindex DebugRunner (classe dans doctest)
@anchor{library/doctest doctest DebugRunner}@anchor{3f7b}
@deffn {Classe} doctest.DebugRunner (checker=None, verbose=None, optionflags=0)

A subclass of @ref{3f3e,,DocTestRunner} that raises an exception as soon as a
failure is encountered.  If an unexpected exception occurs, an
@ref{3f81,,UnexpectedException} exception is raised, containing the test, the
example, and the original exception.  If the output doesn't match, then a
@ref{3f82,,DocTestFailure} exception is raised, containing the test, the example, and
the actual output.

Pour de l'information sur les paramètres et méthodes du constructeur, voir la documentation pour la classe @code{DocTestrunner} dans la section @ref{3f51,,API avancé}.
@end deffn

Il y a deux exceptions qui peuvent être levées par des instances @ref{3f7b,,DebugRunner} :

@geindex DocTestFailure
@anchor{library/doctest doctest DocTestFailure}@anchor{3f82}
@deffn {Exception} doctest.DocTestFailure (test, example, got)

Une exception levée par @ref{3f3e,,DocTestRunner} pour signaler que la sortie obtenue suite à un exemple `doctest' ne correspond pas à la sortie attendue. Les arguments du constructeur sont utilisés pour initialiser les attributs des mêmes noms.
@end deffn

@ref{3f82,,DocTestFailure} définit les attributs suivants :

@geindex test (attribut doctest.DocTestFailure)
@anchor{library/doctest doctest DocTestFailure test}@anchor{3f83}
@deffn {Attribut} DocTestFailure.test

L'objet issu de la classe @ref{163b,,DocTest} qui était en cours d'exécution lorsque l'exemple a échoué.
@end deffn

@geindex example (attribut doctest.DocTestFailure)
@anchor{library/doctest doctest DocTestFailure example}@anchor{3f84}
@deffn {Attribut} DocTestFailure.example

L'exemple @ref{3f52,,Example} qui a échoué.
@end deffn

@geindex got (attribut doctest.DocTestFailure)
@anchor{library/doctest doctest DocTestFailure got}@anchor{3f85}
@deffn {Attribut} DocTestFailure.got

La sortie obtenue par l'exécution de l'exemple.
@end deffn

@geindex UnexpectedException
@anchor{library/doctest doctest UnexpectedException}@anchor{3f81}
@deffn {Exception} doctest.UnexpectedException (test, example, exc_info)

Une exception levée par @ref{3f3e,,DocTestRunner} afin de signaler qu'un exemple `doctest' a levé une exception inattendue. Les arguments du constructeur sont utilisés pour initialiser les attributs des mêmes noms.
@end deffn

@ref{3f81,,UnexpectedException} définit les attributs suivants :

@geindex test (attribut doctest.UnexpectedException)
@anchor{library/doctest doctest UnexpectedException test}@anchor{3f86}
@deffn {Attribut} UnexpectedException.test

L'objet issu de la classe @ref{163b,,DocTest} qui était en cours d'exécution lorsque l'exemple a échoué.
@end deffn

@geindex example (attribut doctest.UnexpectedException)
@anchor{library/doctest doctest UnexpectedException example}@anchor{3f87}
@deffn {Attribut} UnexpectedException.example

L'exemple @ref{3f52,,Example} qui a échoué.
@end deffn

@geindex exc_info (attribut doctest.UnexpectedException)
@anchor{library/doctest doctest UnexpectedException exc_info}@anchor{3f88}
@deffn {Attribut} UnexpectedException.exc_info

Un n-uplet contenant l'information au sujet de l'exception inattendue, telle que retourné par @ref{675,,sys.exc_info()}.
@end deffn

@node Éditorial,,Débogage,doctest — Exemples de tests interactifs en Python
@anchor{library/doctest doctest-soapbox}@anchor{3f89}@anchor{library/doctest soapbox}@anchor{3f8a}
@subsubsection Éditorial


Comme mentionné dans l'introduction, @ref{3a,,doctest} a présentement trois usages principaux :


@enumerate 

@item 
Vérifier les exemples dans les `docstrings'.

@item 
Test de régression.

@item 
De la documentation exécutable / des tests littéraires.
@end enumerate

These uses have different requirements, and it is important to distinguish them.
In particular, filling your docstrings with obscure test cases makes for bad
documentation.

When writing a docstring, choose docstring examples with care. There's an art to
this that needs to be learned---it may not be natural at first.  Examples should
add genuine value to the documentation.  A good example can often be worth many
words. If done with care, the examples will be invaluable for your users, and
will pay back the time it takes to collect them many times over as the years go
by and things change.  I'm still amazed at how often one of my @ref{3a,,doctest}
examples stops working after a "harmless" change.

Doctest also makes an excellent tool for regression testing, especially if you
don't skimp on explanatory text.  By interleaving prose and examples, it becomes
much easier to keep track of what's actually being tested, and why.  When a test
fails, good prose can make it much easier to figure out what the problem is, and
how it should be fixed.  It's true that you could write extensive comments in
code-based testing, but few programmers do. Many have found that using doctest
approaches instead leads to much clearer tests.  Perhaps this is simply because
doctest makes writing prose a little easier than writing code, while writing
comments in code is a little harder.  I think it goes deeper than just that:
the natural attitude when writing a doctest-based test is that you want to
explain the fine points of your software, and illustrate them with examples.
This in turn naturally leads to test files that start with the simplest
features, and logically progress to complications and edge cases.  A coherent
narrative is the result, instead of a collection of isolated functions that test
isolated bits of functionality seemingly at random.  It's a different attitude,
and produces different results, blurring the distinction between testing and
explaining.

Regression testing is best confined to dedicated objects or files.  There are
several options for organizing tests:


@itemize *

@item 
Write text files containing test cases as interactive examples, and test the
files using @ref{3f26,,testfile()} or @ref{3f4d,,DocFileSuite()}.  This is recommended,
although is easiest to do for new projects, designed from the start to use
doctest.

@item 
Define functions named @code{_regrtest_topic} that consist of single docstrings,
containing test cases for the named topics.  These functions can be included in
the same file as the module, or separated out into a separate test file.

@item 
Define a @code{__test__} dictionary mapping from regression test topics to
docstrings containing test cases.
@end itemize

Lorsque vous placez vos tests dans un module, le module lui-même peut être l'exécuteur de tests. Lorsqu'un test échoue, vous pouvez signifier à votre exécuteur de tests de rouler une seconde fois uniquement les tests qui échouent et ce, tant que vous travaillez sur le problème. Voici un exemple minimal d'un test exécuteur de tests :

@example
if __name__ == '__main__':
    import doctest
    flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
    if len(sys.argv) > 1:
        name = sys.argv[1]
        if name in globals():
            obj = globals()[name]
        else:
            obj = __test__[name]
        doctest.run_docstring_examples(obj, globals(), name=name,
                                       optionflags=flags)
    else:
        fail, total = doctest.testmod(optionflags=flags)
        print(f"@{fail@} failures out of @{total@} tests")
@end example

@subsubheading Notes


@node unittest --- Unit testing framework,unittest mock --- mock object library,doctest — Exemples de tests interactifs en Python,Outils de développement
@anchor{library/unittest doc}@anchor{3f8b}@anchor{library/unittest module-unittest}@anchor{105}@anchor{library/unittest unittest-unit-testing-framework}@anchor{3f8c}
@subsection @code{unittest} --- Unit testing framework


@geindex module; unittest

`Code source :' Lib/unittest/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/unittest/__init__.py}


__________________________________________________________________


(Si vous êtes déjà familier des concepts de base concernant les tests, vous pouvez souhaiter passer à @ref{3f8d,,la liste des méthodes}.)

Le cadre applicatif de tests unitaires @ref{105,,unittest} était au départ inspiré par `JUnit' et ressemble aux principaux `frameworks' de tests unitaires des autres langages. Il gère l'automatisation des tests,  le partage de code pour la mise en place et la finalisation des tests, l'agrégation de tests en collections, et l'indépendance des tests par rapport au `framework' utilisé.

Pour y parvenir, @ref{105,,unittest} gère quelques concepts importants avec une approche orientée objet :


@table @asis

@item aménagement de test (`fixture')

Un `aménagement de test' (`fixture' en anglais) désigne la préparation nécessaire au déroulement d'un ou plusieurs tests, et toutes les actions de nettoyage associées. Cela peut concerner, par exemple, la création de bases de données temporaires ou mandataires, de répertoires, ou le démarrage d'un processus serveur.

@item scénario de test

Un `scénario de test' est l'élément de base des tests. Il attend une réponse spécifique pour un ensemble particulier d'entrées. @ref{105,,unittest} fournit une classe de base, @ref{437,,TestCase}, qui peut être utilisée pour créer de nouveaux scénarios de test.

@item suite de tests

Une `suite de tests' est une collection de scénarios de test, de suites de tests ou les deux. Cela sert à regrouper les tests qui devraient être exécutés ensemble.

@item lanceur de tests

Un `lanceur de tests' est un composant qui orchestre l'exécution des tests et fournit le résultat pour l'utilisateur. Le lanceur peut utiliser une interface graphique, une interface textuelle, ou renvoie une valeur spéciale pour indiquer les résultats de l'exécution des tests.
@end table


@subsubheading Voir aussi



@table @asis

@item Module @ref{3a,,doctest}

Un autre module de test adoptant une approche très différente.

@item Simple Smalltalk Testing: With Patterns@footnote{https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm}

Le papier originel de Kent Beck sur les `frameworks' de test utilisant le modèle sur lequel s'appuie @ref{105,,unittest}.

@item pytest@footnote{https://docs.pytest.org/}

Des cadres applicatifs tiers de tests unitaires avec une syntaxe allégée pour l'écriture des tests. Par exemple, @code{assert func(10) == 42}.

@item The Python Testing Tools Taxonomy@footnote{https://wiki.python.org/moin/PythonTestingToolsTaxonomy}

Une liste étendue des outils de test pour Python comprenant des `frameworks' de tests fonctionnels et des bibliothèques d'objets simulés (`mocks').

@item Testing in Python Mailing List@footnote{http://lists.idyll.org/listinfo/testing-in-python}

Un groupe de discussion dédié aux tests, et outils de test, en Python.
@end table

The script @code{Tools/unittestgui/unittestgui.py} in the Python source distribution is
a GUI tool for test discovery and execution.  This is intended largely for ease of use
for those new to unit testing.  For production environments it is
recommended that tests be driven by a continuous integration system such as
Buildbot@footnote{https://buildbot.net/}, Jenkins@footnote{https://www.jenkins.io/},
GitHub Actions@footnote{https://github.com/features/actions}, or
AppVeyor@footnote{https://www.appveyor.com/}.


@menu
* Exemple basique:: 
* Interface en ligne de commande: Interface en ligne de commande<5>. 
* Découverte des tests:: 
* Organiser le code de test:: 
* Réutilisation d'ancien code de test:: 
* Ignorer des tests et des erreurs prévisibles:: 
* Distinguer les itérations de test à l'aide de sous-tests:: 
* Classes et fonctions:: 
* Classes et modules d'aménagements des tests:: 
* Traitement des signaux:: 

@end menu

@node Exemple basique,Interface en ligne de commande<5>,,unittest --- Unit testing framework
@anchor{library/unittest basic-example}@anchor{3f8e}@anchor{library/unittest unittest-minimal-example}@anchor{3f8f}
@subsubsection Exemple basique


Le module @ref{105,,unittest} fournit un riche ensemble d'outils pour construire et lancer des tests. Cette section montre qu'une petite partie des outils suffit pour satisfaire les besoins de la plupart des utilisateurs.

Voici un court script pour tester trois méthodes de `string' :

@example
import unittest

class TestStringMethods(unittest.TestCase):

    def test_upper(self):
        self.assertEqual('foo'.upper(), 'FOO')

    def test_isupper(self):
        self.assertTrue('FOO'.isupper())
        self.assertFalse('Foo'.isupper())

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', 'world'])
        # check that s.split fails when the separator is not a string
        with self.assertRaises(TypeError):
            s.split(2)

if __name__ == '__main__':
    unittest.main()
@end example

Un scénario de test est créé comme classe-fille de @ref{437,,unittest.TestCase}. Les trois tests individuels sont définis par des méthodes dont les noms commencent par les lettres @code{test}. Cette convention de nommage signale au lanceur de tests quelles méthodes sont des tests.

Le cœur de chaque test est un appel à @ref{512,,assertEqual()} pour vérifier un résultat attendu ; @ref{510,,assertTrue()} ou @ref{511,,assertFalse()} pour vérifier une condition ; ou @ref{516,,assertRaises()} pour vérifier qu'une exception particulière est levée. Ces méthodes sont utilisées à la place du mot-clé @ref{955,,assert}  pour que le lanceur de tests puisse récupérer les résultats de tous les tests et produire un rapport.

Les méthodes @ref{1317,,setUp()} et @ref{1318,,tearDown()} vous autorisent à définir des instructions qui seront exécutées avant et après chaque méthode test. Elles sont davantage détaillées dans la section @ref{3f90,,Organiser le code de test}.

Le bloc final montre une manière simple de lancer les tests. @ref{fce,,unittest.main()} fournit une interface en ligne de commande pour le script de test. Lorsqu'il est lancé en ligne de commande, le script ci-dessus produit une sortie qui ressemble à ceci :

@example
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK
@end example

Passer l'option @code{-v} à votre script de test informera @ref{fce,,unittest.main()} qu'il doit fournir un niveau plus important de détails, et produit la sortie suivante :

@example
test_isupper (__main__.TestStringMethods.test_isupper) ... ok
test_split (__main__.TestStringMethods.test_split) ... ok
test_upper (__main__.TestStringMethods.test_upper) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK
@end example

Les exemples ci-dessus montrent les fonctionnalités d'@ref{105,,unittest} les plus communément utilisées et qui sont suffisantes pour couvrir les besoins courants en matière de test. Le reste de la documentation explore l'ensemble complet des fonctionnalités depuis les premiers principes.


Modifié dans la version 3.11: The behavior of returning a value from a test method (other than the default
@code{None} value), is now deprecated.


@node Interface en ligne de commande<5>,Découverte des tests,Exemple basique,unittest --- Unit testing framework
@anchor{library/unittest command-line-interface}@anchor{3f91}@anchor{library/unittest unittest-command-line-interface}@anchor{3f92}
@subsubsection Interface en ligne de commande


Le module `unittest' est utilisable depuis la ligne de commande pour exécuter des tests à partir de modules, de classes ou même de méthodes de test individuelles :

@example
python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method
@end example

La commande accepte en argument une liste de n'importe quelle combinaison de noms de modules et de noms de classes ou de méthodes entièrement qualifiés.

Les modules de test peuvent également être spécifiés par un chemin de fichier :

@example
python -m unittest tests/test_something.py
@end example

Cette fonctionnalité permet d'utiliser la complétion de l'interpréteur de commandes système (`le shell') pour spécifier le module de test. Le chemin est converti en nom de module en supprimant le @code{.py} et en convertissant les séparateurs de chemin en '.'. Si vous voulez exécuter un fichier test qui n'est pas importable en tant que module, exécutez directement le fichier.

Pour obtenir plus de détails lors de l'exécution utilisez l'option @code{-v} (plus de verbosité) :

@example
python -m unittest -v test_module
@end example

Quand la commande est exécutée sans arguments @ref{3f93,,Découverte des tests} est lancée :

@example
python -m unittest
@end example

Pour afficher la liste de toutes les options de la commande utilisez l'option @code{-h} :

@example
python -m unittest -h
@end example


Modifié dans la version 3.2: Dans les versions antérieures, il était seulement possible d'exécuter des méthodes de test individuelles et non des modules ou des classes.


@menu
* Options de la ligne de commande: Options de la ligne de commande<5>. 

@end menu

@node Options de la ligne de commande<5>,,,Interface en ligne de commande<5>
@anchor{library/unittest command-line-options}@anchor{3f94}
@subsubsection Options de la ligne de commande


Le programme @code{unittest} gère ces options de la ligne de commande :

@geindex option de ligne de commande unittest; -b
@geindex option de ligne de commande unittest; --buffer
@anchor{library/unittest cmdoption-unittest-b}@anchor{1310}@anchor{library/unittest cmdoption-unittest-buffer}@anchor{3f95}
@deffn {Option} @w{-}b, @w{-}@w{-}buffer

Les flux de sortie et d'erreur standards sont mis en mémoire tampon pendant l'exécution des tests. L'affichage produit par un test réussi n'est pas pris en compte. Les sorties d'affichages d'un test en échec ou en erreur sont conservés et  ajoutés aux messages d'erreur.
@end deffn

@geindex option de ligne de commande unittest; -c
@geindex option de ligne de commande unittest; --catch
@anchor{library/unittest cmdoption-unittest-c}@anchor{1311}@anchor{library/unittest cmdoption-unittest-catch}@anchor{3f96}
@deffn {Option} @w{-}c, @w{-}@w{-}catch

Utiliser @code{Control-C} pendant l'exécution des tests attend que le test en cours se termine, puis affiche tous les résultats obtenus jusqu'ici. Une seconde utilisation de @code{Control-C} provoque l'exception normale @ref{9bf,,KeyboardInterrupt}.

Voir @ref{3f97,,Signal Handling} pour les fonctions qui utilisent cette fonctionnalité.
@end deffn

@geindex option de ligne de commande unittest; -f
@geindex option de ligne de commande unittest; --failfast
@anchor{library/unittest cmdoption-unittest-f}@anchor{1313}@anchor{library/unittest cmdoption-unittest-failfast}@anchor{3f98}
@deffn {Option} @w{-}f, @w{-}@w{-}failfast

Arrête l'exécution des tests lors du premier cas d'erreur ou d'échec.
@end deffn

@geindex option de ligne de commande unittest; -k
@anchor{library/unittest cmdoption-unittest-k}@anchor{3f99}
@deffn {Option} @w{-}k

Only run test methods and classes that match the pattern or substring.
This option may be used multiple times, in which case all test cases that
match any of the given patterns are included.

Les motifs qui contiennent un caractère de remplacement (@code{*}) sont comparés au nom du test en utilisant @ref{182e,,fnmatch.fnmatchcase()} ; sinon, une recherche simple de sous chaîne respectant la casse est faite.

Les motifs sont comparés au nom de la méthode de test complètement qualifiée tel qu'importé par le chargeur de test.

Par exemple, @code{-k machin} retient les tests @code{machin_tests.UnTest.test_untruc}, @code{truc_tests.UnTest.test_machin}, mais pas @code{truc_tests.MachinTest.test_untruc}.
@end deffn

@geindex option de ligne de commande unittest; --locals
@anchor{library/unittest cmdoption-unittest-locals}@anchor{3f9a}
@deffn {Option} @w{-}@w{-}locals

Affiche les variables locales dans les traces d'appels.
@end deffn

@geindex option de ligne de commande unittest; --durations
@anchor{library/unittest cmdoption-unittest-durations}@anchor{3f9b}
@deffn {Option} @w{-}@w{-}durations N

Show the N slowest test cases (N=0 for all).
@end deffn


Ajouté dans la version 3.2: Les options de ligne de commande @code{-b}, @code{-c} et @code{-f} ont été ajoutées.



Ajouté dans la version 3.5: Ajout de l'option de ligne de commande @code{--locals}.



Ajouté dans la version 3.7: Ajout de l'option de ligne de commande @code{-k}.



Ajouté dans la version 3.12: The command-line option @code{--durations}.


La ligne de commande peut également être utilisée pour découvrir les tests, pour exécuter tous les tests dans un projet ou juste un sous-ensemble.

@node Découverte des tests,Organiser le code de test,Interface en ligne de commande<5>,unittest --- Unit testing framework
@anchor{library/unittest test-discovery}@anchor{3f9c}@anchor{library/unittest unittest-test-discovery}@anchor{3f93}
@subsubsection Découverte des tests



Ajouté dans la version 3.2.


Unittest supports simple test discovery. In order to be compatible with test
discovery, all of the test files must be @ref{1be4,,modules} or
@ref{1bf5,,packages} importable from the top-level directory of
the project (this means that their filenames must be valid @ref{1e1a,,identifiers}).

La découverte de tests est implémentée dans @ref{fd0,,TestLoader.discover()}, mais peut également être utilisée depuis la ligne de commande. Par exemple :

@example
cd project_directory
python -m unittest discover
@end example

@cartouche
@quotation Note 
Comme raccourci, @code{python -m unittest} est l'équivalent de @code{python -m unittest discover}. Pour passer des arguments au système de découverte des tests, la sous-commande @code{discover} doit être utilisée explicitement.
@end quotation
@end cartouche

La sous-commande @code{discover} a les options suivantes :

@geindex option de ligne de commande unittest-discover; -v
@geindex option de ligne de commande unittest-discover; --verbose
@anchor{library/unittest cmdoption-unittest-discover-v}@anchor{3f9d}@anchor{library/unittest cmdoption-unittest-discover-verbose}@anchor{3f9e}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

Affichage plus détaillé
@end deffn

@geindex option de ligne de commande unittest-discover; -s
@geindex option de ligne de commande unittest-discover; --start-directory
@anchor{library/unittest cmdoption-unittest-discover-s}@anchor{3f9f}@anchor{library/unittest cmdoption-unittest-discover-start-directory}@anchor{3fa0}
@deffn {Option} @w{-}s, @w{-}@w{-}start@w{-}directory directory

Répertoire racine pour démarrer la découverte (@code{.} par défaut).
@end deffn

@geindex option de ligne de commande unittest-discover; -p
@geindex option de ligne de commande unittest-discover; --pattern
@anchor{library/unittest cmdoption-unittest-discover-p}@anchor{3fa1}@anchor{library/unittest cmdoption-unittest-discover-pattern}@anchor{3fa2}
@deffn {Option} @w{-}p, @w{-}@w{-}pattern pattern

Motif de détection des fichiers de test (@code{test*.py} par défaut)
@end deffn

@geindex option de ligne de commande unittest-discover; -t
@geindex option de ligne de commande unittest-discover; --top-level-directory
@anchor{library/unittest cmdoption-unittest-discover-t}@anchor{3fa3}@anchor{library/unittest cmdoption-unittest-discover-top-level-directory}@anchor{3fa4}
@deffn {Option} @w{-}t, @w{-}@w{-}top@w{-}level@w{-}directory directory

Dossier du premier niveau du projet (Par défaut le dossier de départ)
@end deffn

Les options @ref{3f9f,,-s}, @ref{3fa1,,-p} et @ref{3fa3,,-t} peuvent être passées en arguments positionnels dans cet ordre. Les deux lignes de commande suivantes sont équivalentes :

@example
python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"
@end example

Il est aussi possible de passer un nom de paquet plutôt qu'un chemin, par exemple @code{monprojet.souspaquet.test}, comme répertoire racine. Le nom du paquet fourni est alors importé et son emplacement sur le système de fichiers est utilisé comme répertoire racine.

@cartouche
@quotation Prudence 
Le mécanisme de découverte charge les tests en les important. Une fois que le système a trouvé tous les fichiers de tests du répertoire de démarrage spécifié, il transforme les chemins en noms de paquets à importer. Par exemple @code{truc/bidule/machin.py} est importé sous @code{truc.bidule.machin}.

Si un paquet est installé globalement et que le mécanisme de découverte de tests est effectué sur une copie différente du paquet, l'importation `peut' se produire à partir du mauvais endroit. Si cela arrive, le système émet un avertissement et se termine.

Si vous donnez le répertoire racine sous la forme d'un nom de paquet plutôt que d'un chemin d'accès à un répertoire, alors Python suppose que l'emplacement à partir duquel il importe est l'emplacement que vous voulez, vous ne verrez donc pas l'avertissement.
@end quotation
@end cartouche

Les modules de test et les paquets peuvent adapter le chargement et la découverte des tests en utilisant le protocole @ref{3fa5,,load_tests protocol}.


Modifié dans la version 3.4: Test discovery supports @ref{1bf6,,namespace packages}
for the start directory. Note that you need to specify the top level
directory too (e.g.
@code{python -m unittest discover -s root/namespace -t root}).



Modifié dans la version 3.11: @ref{105,,unittest} dropped the @ref{1bf6,,namespace packages}
support in Python 3.11. It has been broken since Python 3.7. Start directory and
subdirectories containing tests must be regular package that have
@code{__init__.py} file.

Directories containing start directory still can be a namespace package.
In this case, you need to specify start directory as dotted package name,
and target directory explicitly. For example:

@example
# proj/  <-- current directory
#   namespace/
#     mypkg/
#       __init__.py
#       test_mypkg.py

python -m unittest discover -s namespace.mypkg -t .
@end example


@node Organiser le code de test,Réutilisation d'ancien code de test,Découverte des tests,unittest --- Unit testing framework
@anchor{library/unittest organizing-test-code}@anchor{3fa6}@anchor{library/unittest organizing-tests}@anchor{3f90}
@subsubsection Organiser le code de test


Les éléments de base des tests unitaires sont les `scénarios de tests'  (`test cases' en anglais) --- Des scénarios uniques qui sont mis en place et exécutés pour vérifier qu'ils sont corrects.  Dans @ref{105,,unittest}, les scénarios de test sont représentés par des instances de @ref{437,,unittest.TestCase}. Pour créer vos propres scénarios de test, vous devez écrire des sous-classes de @ref{437,,TestCase} ou utiliser @ref{1692,,FunctionTestCase}.

Le code de test d'une instance de @ref{437,,TestCase} doit être entièrement autonome, de sorte qu'il puisse être exécuté soit de manière isolée, soit en combinaison arbitraire avec un nombre quelconque d'autres scénarios de test.

La sous-classe @ref{437,,TestCase} la plus simple va tout simplement implémenter une méthode de test (c'est-à-dire une méthode dont le nom commence par @code{test}) afin d'exécuter un code de test spécifique :

@example
import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def test_default_widget_size(self):
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50))
@end example

Note that in order to test something, we use one of the @ref{3f8d,,assert* methods}
provided by the @ref{437,,TestCase} base class.  If the test fails, an
exception will be raised with an explanatory message, and @ref{105,,unittest}
will identify the test case as a `failure'.  Any other exceptions will be
treated as `errors'.

Les tests peuvent être nombreux et leur mise en place peut être répétitive.  Heureusement, on peut factoriser le code de mise en place en implémentant une méthode appelée @ref{1317,,setUp()}, que le système de test appelle automatiquement pour chaque test exécuté :

@example
import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def test_default_widget_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_widget_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')
@end example

@cartouche
@quotation Note 
L'ordre dans lequel les différents tests sont exécutés est déterminé en classant les noms des méthodes de test en fonction de la relation d'ordre des chaines de caractères .
@end quotation
@end cartouche

Si la méthode @ref{1317,,setUp()} lève une exception pendant l'exécution du test, le système considère que le test a subi une erreur, et la méthode test n'est pas exécutée.

De même, on peut fournir une méthode @ref{1318,,tearDown()} qui nettoie après l'exécution de la méthode de test :

@example
import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()
@end example

Si @ref{1317,,setUp()} a réussi, @ref{1318,,tearDown()} est exécutée, que la méthode de test ait réussi ou non.

Un tel environnement de travail pour le code de test s'appelle un `aménagement de test' (`fixture' en anglais).  Une nouvelle instance de `TestCase' est créée sous la forme d'un dispositif de test unique utilisé pour exécuter chaque méthode de test individuelle.  Ainsi @ref{1317,,setUp()}, @ref{1318,,tearDown()} et @code{__init__()} ne sont appelées qu'une fois par test.

Il est recommandé d'utiliser `TestCase' pour regrouper les tests en fonction des fonctionnalités qu'ils testent. @ref{105,,unittest} fournit un mécanisme pour cela : la `suite de tests', représentée par @ref{de1,,TestSuite} du module @ref{105,,unittest}. Dans la plupart des cas, appeler @ref{fce,,unittest.main()} fait correctement les choses et trouve tous les scénarios de test du module pour vous et les exécute.

Cependant, si vous voulez personnaliser la construction de votre suite de tests, vous pouvez le faire vous-même :

@example
def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_widget_size'))
    suite.addTest(WidgetTestCase('test_widget_resize'))
    return suite

if __name__ == '__main__':
    runner = unittest.TextTestRunner()
    runner.run(suite())
@end example

Vous pouvez placer les définitions des scénarios de test et des suites de test dans le même module que le code à tester (tel que @code{composant.py}), mais il y a plusieurs avantages à placer le code de test dans un module séparé, tel que @code{test_composant.py} :


@itemize *

@item 
Le module de test peut être exécuté indépendamment depuis la ligne de commande.

@item 
Le code de test est plus facilement séparable du code livré.

@item 
La tentation est moins grande de changer le code de test pour l'adapter au code qu'il teste sans avoir une bonne raison.

@item 
Le code de test doit être modifié beaucoup moins souvent que le code qu'il teste.

@item 
Le code testé peut être réusiné plus facilement.

@item 
Les tests pour les modules écrits en C doivent de toute façon être dans des modules séparés, alors pourquoi ne pas être cohérent ?

@item 
Si la stratégie de test change, il n'est pas nécessaire de changer le code source.
@end itemize

@node Réutilisation d'ancien code de test,Ignorer des tests et des erreurs prévisibles,Organiser le code de test,unittest --- Unit testing framework
@anchor{library/unittest legacy-unit-tests}@anchor{3fa7}@anchor{library/unittest re-using-old-test-code}@anchor{3fa8}
@subsubsection Réutilisation d'ancien code de test


Certains utilisateurs constatent qu'ils ont du code de test existant qu'ils souhaitent exécuter à partir de @ref{105,,unittest}, sans convertir chaque ancienne fonction de test en une sous-classe de @ref{437,,TestCase}.

Pour cette raison, @ref{105,,unittest} fournit une classe @ref{1692,,FunctionTestCase}. Cette sous-classe de @ref{437,,TestCase} peut être utilisée pour encapsuler une fonction de test existante. Des fonctions de mise en place (`setUp') et de démantèlement (`tearDown') peuvent également être fournies.

Étant donnée la fonction de test suivante :

@example
def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...
@end example

on peut créer une instance de scénario de test équivalente, avec des méthodes optionnelles de mise en place et de démantèlement :

@example
testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)
@end example

@cartouche
@quotation Note 
Même si  la classe @ref{1692,,FunctionTestCase} peut être utilisée pour convertir rapidement une base de test existante vers un système basé sur @ref{105,,unittest}, cette approche n'est pas recommandée.  Prendre le temps de bien configurer les sous-classes de @ref{437,,TestCase} simplifiera considérablement les futurs réusinages des tests.
@end quotation
@end cartouche

Dans certains cas, les tests déjà existants ont pu être écrits avec le module @ref{3a,,doctest}.  Dans ce cas, @ref{3a,,doctest} fournit une classe @code{DocTestSuite} qui peut construire automatiquement des instances de la classe @ref{de1,,unittest.TestSuite} depuis des tests basés sur le module @ref{3a,,doctest}.

@node Ignorer des tests et des erreurs prévisibles,Distinguer les itérations de test à l'aide de sous-tests,Réutilisation d'ancien code de test,unittest --- Unit testing framework
@anchor{library/unittest skipping-tests-and-expected-failures}@anchor{3fa9}@anchor{library/unittest unittest-skipping}@anchor{3faa}
@subsubsection Ignorer des tests et des erreurs prévisibles



Ajouté dans la version 3.1.


`Unittest' permet d'ignorer des méthodes de test individuelles et même des classes entières de tests. De plus, il prend en charge le marquage d'un test comme étant une "erreur prévue". Un test qui est cassé et qui échoue, mais qui ne doit pas être considéré comme un échec dans la classe @ref{1147,,TestResult}.

Ignorer un test consiste à soit utiliser le @ref{71b,,décorateur} @ref{1967,,skip()} ou une de ses variantes conditionnelles, soit appeler @ref{3fab,,TestCase.skipTest()} à l'intérieur d'une méthode @ref{1317,,setUp()} ou de test, soit lever @ref{fcf,,SkipTest} directement.

Un exemple de tests à ignorer :

@example
class MyTestCase(unittest.TestCase):

    @@unittest.skip("demonstrating skipping")
    def test_nothing(self):
        self.fail("shouldn't happen")

    @@unittest.skipIf(mylib.__version__ < (1, 3),
                     "not supported in this library version")
    def test_format(self):
        # Tests that work for only a certain version of the library.
        pass

    @@unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_windows_support(self):
        # windows specific testing code
        pass

    def test_maybe_skipped(self):
        if not external_resource_available():
            self.skipTest("external resource not available")
        # test code that depends on the external resource
        pass
@end example

Ceci est le résultat de l'exécution de l'exemple ci-dessus en mode verbeux :

@example
test_format (__main__.MyTestCase.test_format) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase.test_nothing) ... skipped 'demonstrating skipping'
test_maybe_skipped (__main__.MyTestCase.test_maybe_skipped) ... skipped 'external resource not available'
test_windows_support (__main__.MyTestCase.test_windows_support) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 4 tests in 0.005s

OK (skipped=4)
@end example

Les classes peuvent être ignorées tout comme les méthodes :

@example
@@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass
@end example

La méthode @ref{1317,,TestCase.setUp()} permet également d'ignorer le test.  Ceci est utile lorsqu'une ressource qui doit être configurée n'est pas disponible.

Les erreurs prévisibles utilisent le décorateur @ref{3fac,,expectedFailure()}

@example
class ExpectedFailureTestCase(unittest.TestCase):
    @@unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")
@end example

Il est facile de faire ses propres décorateurs en créant un décorateur qui appelle @ref{1967,,skip()} sur le test que vous voulez ignorer. Par exemple, ce décorateur ignore le test à moins que l'objet passé ne possède un certain attribut :

@example
def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("@{!r@} doesn't have @{!r@}".format(obj, attr))
@end example

Les décorateurs et exceptions suivants implémentent le système d'omission des tests et les erreurs prévisibles :

@geindex skip() (dans le module unittest)
@anchor{library/unittest unittest skip}@anchor{1967}
@deffn {Fonction} @@unittest.skip (reason)

Ignore sans condition le test décoré.  `La raison' doit décrire la raison pour laquelle le test est omis.
@end deffn

@geindex skipIf() (dans le module unittest)
@anchor{library/unittest unittest skipIf}@anchor{3fad}
@deffn {Fonction} @@unittest.skipIf (condition, reason)

Ignore le test décoré si la `condition' est vraie.
@end deffn

@geindex skipUnless() (dans le module unittest)
@anchor{library/unittest unittest skipUnless}@anchor{3fae}
@deffn {Fonction} @@unittest.skipUnless (condition, reason)

Ignore le test décoré sauf si la `condition' est vraie.
@end deffn

@geindex expectedFailure() (dans le module unittest)
@anchor{library/unittest unittest expectedFailure}@anchor{3fac}
@deffn {Fonction} @@unittest.expectedFailure

Mark the test as an expected failure or error.  If the test fails or errors
in the test function itself (rather than in one of the `test fixture'
methods) then it will be considered a success.  If the test passes, it will
be considered a failure.
@end deffn

@geindex SkipTest
@anchor{library/unittest unittest SkipTest}@anchor{fcf}
@deffn {Exception} unittest.SkipTest (reason)

Cette exception est levée pour ignorer un test.

Habituellement, on utilise @ref{3fab,,TestCase.skipTest()} ou l'un des décorateurs d'omission au lieu de le lever une exception directement.
@end deffn

Les tests ignorés ne lancent ni @ref{1317,,setUp()} ni @ref{1318,,tearDown()}. Les classes ignorées ne lancent ni @ref{a3d,,setUpClass()} ni @ref{1315,,tearDownClass()}. Les modules sautés n'ont pas @code{setUpModule()} ou @code{tearDownModule()} d'exécutés.

@node Distinguer les itérations de test à l'aide de sous-tests,Classes et fonctions,Ignorer des tests et des erreurs prévisibles,unittest --- Unit testing framework
@anchor{library/unittest distinguishing-test-iterations-using-subtests}@anchor{3faf}@anchor{library/unittest subtests}@anchor{fcd}
@subsubsection Distinguer les itérations de test à l'aide de sous-tests



Ajouté dans la version 3.4.


Lorsque certains de vos tests ne diffèrent que par de très petites différences, par exemple certains paramètres, `unittest' vous permet de les distinguer en utilisant le gestionnaire de contexte @ref{fcc,,subTest()} dans le corps d'une méthode de test.

Par exemple, le test suivant :

@example
class NumbersTest(unittest.TestCase):

    def test_even(self):
        """
        Test that numbers between 0 and 5 are all even.
        """
        for i in range(0, 6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)
@end example

produit le résultat suivant :

@example
======================================================================
FAIL: test_even (__main__.NumbersTest.test_even) (i=1)
Test that numbers between 0 and 5 are all even.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 11, in test_even
    self.assertEqual(i % 2, 0)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest.test_even) (i=3)
Test that numbers between 0 and 5 are all even.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 11, in test_even
    self.assertEqual(i % 2, 0)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest.test_even) (i=5)
Test that numbers between 0 and 5 are all even.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 11, in test_even
    self.assertEqual(i % 2, 0)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: 1 != 0
@end example

Sans l'utilisation d'un sous-test, l'exécution se termine après le premier échec, et l'erreur est moins facile à diagnostiquer car la valeur de @code{i} ne s'affiche pas :

@example
======================================================================
FAIL: test_even (__main__.NumbersTest.test_even)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0
@end example

@node Classes et fonctions,Classes et modules d'aménagements des tests,Distinguer les itérations de test à l'aide de sous-tests,unittest --- Unit testing framework
@anchor{library/unittest classes-and-functions}@anchor{3fb0}@anchor{library/unittest unittest-contents}@anchor{3fb1}
@subsubsection Classes et fonctions


Cette section décrit en détail l'API de @ref{105,,unittest}.

@menu
* Scénarios de tests:: 
* Regroupement des tests:: 
* Chargement et exécution des tests:: 

@end menu

@node Scénarios de tests,Regroupement des tests,,Classes et fonctions
@anchor{library/unittest test-cases}@anchor{3fb2}@anchor{library/unittest testcase-objects}@anchor{3fb3}
@subsubsection Scénarios de tests


@geindex TestCase (classe dans unittest)
@anchor{library/unittest unittest TestCase}@anchor{437}
@deffn {Classe} unittest.TestCase (methodName='runTest')

Les instances de la classe @ref{437,,TestCase} représentent des tests logiques unitaires dans l'univers @ref{105,,unittest}. Cette classe est conçue pour être utilisée comme classe de base. Les scénarios de tests sont à implémenter en héritant de cette classe. La classe implémente l'interface nécessaire au lanceur de tests pour lui permettre de les exécuter ainsi que les méthodes que le code de test peut utiliser pour vérifier et signaler les différents types d'erreurs.

Chaque instance de la classe @ref{437,,TestCase} n'exécute qu'une seule méthode de base : la méthode nommée `methodName' . Dans la plupart des utilisations de la classe @ref{437,,TestCase}, vous n'avez pas à changer le nom de la méthode, ni à réimplémenter la méthode @code{runTest()}.


Modifié dans la version 3.2: La classe @ref{437,,TestCase} peut désormais être utilisée sans passer de paramètre `methodName'. Cela facilite l'usage de @ref{437,,TestCase} dans l'interpréteur interactif.


Les instances de la classe @ref{437,,TestCase} fournissent trois groupes de méthodes : un groupe utilisé pour exécuter le test, un autre utilisé par l'implémentation du test pour vérifier les conditions et signaler les échecs, et quelques méthodes de recherche permettant de recueillir des informations sur le test lui-même.

Les méthodes du premier groupe (exécution du test) sont :

@geindex setUp() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase setUp}@anchor{1317}
@deffn {Méthode} setUp ()

Méthode appelée pour réaliser la mise en place du test. Elle est exécutée immédiatement avant l'appel de la méthode de test ; à l'exception de @ref{694,,AssertionError} ou @ref{fcf,,SkipTest}, toute exception levée par cette méthode est considérée comme une erreur et non pas comme un échec du test. L'implémentation par défaut ne fait rien.
@end deffn

@geindex tearDown() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase tearDown}@anchor{1318}
@deffn {Méthode} tearDown ()

Méthode appelée immédiatement après l'appel de la méthode de test et l'enregistrement du résultat.  Elle est appelée même si la méthode de test a levé une exception. De fait, l'implémentation d'un sous-classes doit être fait avec précaution  si vous vérifiez l'état interne de la classe. Toute exception, autre que @ref{694,,AssertionError} ou @ref{fcf,,SkipTest}, levée par cette méthode est considérée comme une erreur supplémentaire plutôt que comme un échec du test (augmentant ainsi le nombre total des erreurs signalées). Cette méthode est appelée uniquement si l'exécution de @ref{1317,,setUp()} est réussie quel que soit le résultat de la méthode de test. L'implémentation par défaut ne fait rien.
@end deffn

@geindex setUpClass() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase setUpClass}@anchor{a3d}
@deffn {Méthode} setUpClass ()

Méthode de classe appelée avant l'exécution des tests dans la classe en question. @code{setUpClass} est appelée avec la classe comme seul argument et doit être décorée comme une  @ref{165,,classmethod()} :

@example
@@classmethod
def setUpClass(cls):
    ...
@end example

Voir @ref{3fb4,,Class and Module Fixtures} pour plus de détails.


Ajouté dans la version 3.2.

@end deffn

@geindex tearDownClass() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase tearDownClass}@anchor{1315}
@deffn {Méthode} tearDownClass ()

Méthode de classe appelée après l'exécution des tests de la classe en question. @code{tearDownClass} est appelée avec la classe comme seul argument et doit être décorée comme une @ref{165,,classmethod()} :

@example
@@classmethod
def tearDownClass(cls):
    ...
@end example

Voir @ref{3fb4,,Class and Module Fixtures} pour plus de détails.


Ajouté dans la version 3.2.

@end deffn

@geindex run() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase run}@anchor{1146}
@deffn {Méthode} run (result=None)

Exécute le test, en collectant le résultat dans l'objet @ref{1147,,TestResult} passé comme `result'.  Si `result' est omis ou vaut @code{None}, un objet temporaire de résultat est créé (en appelant la méthode @ref{3fb5,,defaultTestResult()}) et utilisé. L'objet résultat est renvoyé à l'appelant de @ref{1146,,run()}.

Le même effet peut être obtenu en appelant simplement l'instance @ref{437,,TestCase}.


Modifié dans la version 3.3: Les versions précédentes de @code{run} ne renvoyaient pas le résultat. Pas plus que l'appel d'une instance.

@end deffn

@geindex skipTest() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase skipTest}@anchor{3fab}
@deffn {Méthode} skipTest (reason)

Appeler cette fonction pendant l'exécution d'une méthode de test ou de @ref{1317,,setUp()} permet d'ignorer le test en cours.  Voir @ref{3faa,,Ignorer des tests et des erreurs prévisibles} pour plus d'informations.


Ajouté dans la version 3.1.

@end deffn

@geindex subTest() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase subTest}@anchor{fcc}
@deffn {Méthode} subTest (msg=None, **params)

Renvoie un gestionnaire de contexte qui exécute le bloc de code du contexte comme un sous-test. `msg' et `params' sont des valeurs optionnelles et arbitraires qui sont affichées chaque fois qu'un sous-test échoue, permettant de les identifier clairement.

Un scénario de test peut contenir un nombre quelconque de déclarations de sous-test, et elles peuvent être imbriquées librement.

Voir @ref{fcd,,Distinguer les itérations de test à l'aide de sous-tests} pour plus d'informations.


Ajouté dans la version 3.4.

@end deffn

@geindex debug() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase debug}@anchor{1822}
@deffn {Méthode} debug ()

Lance le test sans collecter le résultat.  Ceci permet aux exceptions levées par le test d'être propagées à l'appelant, et donc peut être utilisé pour exécuter des tests sous un débogueur.
@end deffn
@anchor{library/unittest assert-methods}@anchor{3f8d}
La classe @ref{437,,TestCase} fournit plusieurs méthodes d'assertion pour vérifier et signaler les échecs.  Le tableau suivant énumère les méthodes les plus couramment utilisées (voir les tableaux ci-dessous pour plus de méthodes d'assertion) :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Méthode

@tab

Vérifie que

@tab

Disponible en

@item

@ref{512,,assertEqual(a@comma{} b)}

@tab

@code{a == b}

@tab

@item

@ref{513,,assertNotEqual(a@comma{} b)}

@tab

@code{a != b}

@tab

@item

@ref{510,,assertTrue(x)}

@tab

@code{bool(x) is True}

@tab

@item

@ref{511,,assertFalse(x)}

@tab

@code{bool(x) is False}

@tab

@item

@ref{1319,,assertIs(a@comma{} b)}

@tab

@code{a is b}

@tab

3.1

@item

@ref{131a,,assertIsNot(a@comma{} b)}

@tab

@code{a is not b}

@tab

3.1

@item

@ref{1268,,assertIsNone(x)}

@tab

@code{x is None}

@tab

3.1

@item

@ref{1269,,assertIsNotNone(x)}

@tab

@code{x is not None}

@tab

3.1

@item

@ref{1322,,assertIn(a@comma{} b)}

@tab

@code{a in b}

@tab

3.1

@item

@ref{1323,,assertNotIn(a@comma{} b)}

@tab

@code{a not in b}

@tab

3.1

@item

@ref{131b,,assertIsInstance(a@comma{} b)}

@tab

@code{isinstance(a, b)}

@tab

3.2

@item

@ref{131c,,assertNotIsInstance(a@comma{} b)}

@tab

@code{not isinstance(a, b)}

@tab

3.2

@end multitable


Toutes les méthodes `assert' prennent en charge un argument `msg' qui, s'il est spécifié, est utilisé comme message d'erreur en cas d'échec (voir aussi @ref{1314,,longMessage}). Notez que l'argument nommé `msg' peut être passé à @ref{516,,assertRaises()}, @ref{518,,assertRaisesRegex()}, @ref{1144,,assertWarns()}, @ref{1145,,assertWarnsRegex()}, seulement quand elles sont utilisées comme gestionnaire de contexte.

@geindex assertEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertEqual}@anchor{512}
@deffn {Méthode} assertEqual (first, second, msg=None)

Vérifie que `first' et `second' sont égaux.  Si les valeurs ne sont pas égales, le test échouera.

En outre, si `first' et `second' ont exactement le même type et sont de type `list', `tuple', `dict', `set', `frozenset' ou `str' ou tout autre type de sous classe enregistrée dans @ref{1326,,addTypeEqualityFunc()}. La fonction égalité spécifique au type sera appelée pour générer une erreur plus utile (voir aussi @ref{3fb6,,liste des méthodes spécifiques de type}).


Modifié dans la version 3.1: Ajout de l'appel automatique de la fonction d'égalité spécifique au type.



Modifié dans la version 3.2: Ajout de @ref{1321,,assertMultiLineEqual()} comme fonction d'égalité de type par défaut pour comparer les chaînes.

@end deffn

@geindex assertNotEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNotEqual}@anchor{513}
@deffn {Méthode} assertNotEqual (first, second, msg=None)

Vérifie que `first' et `second' ne sont pas égaux.  Si les valeurs sont égales, le test échouera.
@end deffn

@geindex assertTrue() (méthode unittest.TestCase)
@geindex assertFalse() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertTrue}@anchor{510}
@deffn {Méthode} assertTrue (expr, msg=None)
@anchor{library/unittest unittest TestCase assertFalse}@anchor{511}
@deffnx {Méthode} assertFalse (expr, msg=None)

Vérifie que `expr' est vraie (ou fausse).

Notez que cela revient à utiliser @code{bool(expr) is True} et non à @code{expr is True} (utilisez @code{assertIs(expr, True)} pour cette dernière). Cette méthode doit également être évitée lorsque des méthodes plus spécifiques sont disponibles (par exemple @code{assertEqual(a, b)} au lieu de @code{assertTrue(a == b)}), car elles fournissent un meilleur message d'erreur en cas d' échec.
@end deffn

@geindex assertIs() (méthode unittest.TestCase)
@geindex assertIsNot() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIs}@anchor{1319}
@deffn {Méthode} assertIs (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertIsNot}@anchor{131a}
@deffnx {Méthode} assertIsNot (first, second, msg=None)

Vérifie que `first' et `second' sont (ou ne sont pas) le même objet.


Ajouté dans la version 3.1.

@end deffn

@geindex assertIsNone() (méthode unittest.TestCase)
@geindex assertIsNotNone() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIsNone}@anchor{1268}
@deffn {Méthode} assertIsNone (expr, msg=None)
@anchor{library/unittest unittest TestCase assertIsNotNone}@anchor{1269}
@deffnx {Méthode} assertIsNotNone (expr, msg=None)

Vérifie que `expr' est (ou n'est pas) la valeur @code{None}.


Ajouté dans la version 3.1.

@end deffn

@geindex assertIn() (méthode unittest.TestCase)
@geindex assertNotIn() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIn}@anchor{1322}
@deffn {Méthode} assertIn (member, container, msg=None)
@anchor{library/unittest unittest TestCase assertNotIn}@anchor{1323}
@deffnx {Méthode} assertNotIn (member, container, msg=None)

Vérifie que `member' est (ou n'est pas) dans `container'.


Ajouté dans la version 3.1.

@end deffn

@geindex assertIsInstance() (méthode unittest.TestCase)
@geindex assertNotIsInstance() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertIsInstance}@anchor{131b}
@deffn {Méthode} assertIsInstance (obj, cls, msg=None)
@anchor{library/unittest unittest TestCase assertNotIsInstance}@anchor{131c}
@deffnx {Méthode} assertNotIsInstance (obj, cls, msg=None)

Vérifie que `obj' est (ou n'est pas) une instance de `cls' (Ce qui peut être une classe ou un `n'-uplet de classes, comme utilisée par @ref{42b,,isinstance()}). Pour vérifier le type exact, utilisez @ref{1319,,assertIs(type(obj)@comma{} cls)}.


Ajouté dans la version 3.2.

@end deffn

Il est également possible de vérifier la production des exceptions, des avertissements et des messages de journaux à l'aide des méthodes suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Méthode

@tab

Vérifie que

@tab

Disponible en

@item

@ref{516,,assertRaises(exc@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} lève bien l'exception `exc'

@tab

@item

@ref{518,,assertRaisesRegex(exc@comma{} r@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} lève bien l'exception `exc' et que le message correspond au motif de l'expression régulière `r'

@tab

3.1

@item

@ref{1144,,assertWarns(warn@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} lève bien l'avertissement `warn'

@tab

3.2

@item

@ref{1145,,assertWarnsRegex(warn@comma{} r@comma{} fun@comma{} *args@comma{} **kwds)}

@tab

@code{fun(*args, **kwds)} lève bien l'avertissement `warn' et que le message correspond au motif de l'expression régulière `r'

@tab

3.2

@item

@ref{843,,assertLogs(logger@comma{} level)}

@tab

Le bloc @code{with} écrit dans le `logger'  avec un niveau minimum égal à `level'

@tab

3.4

@item

@ref{842,,assertNoLogs(logger@comma{} level)}

@tab


@table @asis

@item The @code{with} block does not log on

`logger' with minimum `level'
@end table

@tab

3.10

@end multitable


@geindex assertRaises() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertRaises}@anchor{516}
@deffn {Méthode} assertRaises (exception, callable, *args, **kwds)

@deffnx {Méthode} assertRaises (exception, *, msg=None)

Vérifie qu'une exception est levée lorsque `callable' est appelé avec n'importe quel argument positionnel ou nommé qui est également passé à @ref{516,,assertRaises()}.  Le test réussit si `exception' est levée, est en erreur si une autre exception est levée, ou en échec si aucune exception n'est levée. Pour capturer une exception d'un groupe d'exceptions, un `n'-uplet contenant les classes d'exceptions peut être passé à `exception'.

Si seuls les arguments `exception' et éventuellement `msg' sont donnés, renvoie un gestionnaire de contexte pour que le code sous test puisse être écrit en ligne plutôt que comme une fonction :

@example
with self.assertRaises(SomeException):
    do_something()
@end example

Lorsqu'il est utilisé comme gestionnaire de contexte, @ref{516,,assertRaises()} accepte l'argument nommé supplémentaire `msg'.

Le gestionnaire de contexte enregistre l'exception interceptée dans son attribut @code{exception}. Ceci est particulièrement utile si l'intention est d'effectuer des contrôles supplémentaires sur l'exception levée :

@example
with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)
@end example


Modifié dans la version 3.1: Ajout de la possibilité d'utiliser @ref{516,,assertRaises()} comme gestionnaire de contexte.



Modifié dans la version 3.2: Ajout de l'attribut @code{exception}.



Modifié dans la version 3.3: Ajout de l'argument nommé `msg' lorsqu'il est utilisé comme gestionnaire de contexte.

@end deffn

@geindex assertRaisesRegex() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertRaisesRegex}@anchor{518}
@deffn {Méthode} assertRaisesRegex (exception, regex, callable, *args, **kwds)

@deffnx {Méthode} assertRaisesRegex (exception, regex, *, msg=None)

Comme @ref{516,,assertRaises()} mais vérifie aussi que `regex' correspond à la représentation de la chaîne de caractères de l'exception levée.  `regex' peut être un objet d'expression rationnelle ou une chaîne contenant une expression rationnelle appropriée pour être utilisée par @ref{120a,,re.search()}.  Exemples :

@example
self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')
@end example

ou :

@example
with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')
@end example


Ajouté dans la version 3.1: Sous le nom @code{assertRaisesRegexp}.



Modifié dans la version 3.2: Renommé en @ref{518,,assertRaisesRegex()}.



Modifié dans la version 3.3: Ajout de l'argument nommé `msg' lorsqu'il est utilisé comme gestionnaire de contexte.

@end deffn

@geindex assertWarns() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertWarns}@anchor{1144}
@deffn {Méthode} assertWarns (warning, callable, *args, **kwds)

@deffnx {Méthode} assertWarns (warning, *, msg=None)

Test qu'un avertissement est déclenché lorsque `callable' est appelé avec n'importe quel argument positionnel ou nommé qui est également passé à @ref{1144,,assertWarns()}. Le test passe si `warning' est déclenché et échoue s'il ne l'est pas. Toute exception est une erreur. Pour capturer un avertissement dans un ensemble d'avertissements, un `n'-uplet contenant les classes d'avertissement peut être passé à `warnings'.

Si seuls les arguments * warning* et éventuellement `msg' sont donnés, renvoie un gestionnaire de contexte pour que le code testé puisse être écrit en ligne plutôt que comme une fonction :

@example
with self.assertWarns(SomeWarning):
    do_something()
@end example

Lorsqu'il est utilisé comme gestionnaire de contexte, @ref{1144,,assertWarns()} accepte l'argument nommé supplémentaire `msg'.

Le gestionnaire de contexte stocke l'avertissement capturé dans son attribut @code{warning}, et la ligne source qui a déclenché les avertissements dans les attributs @code{filename} et @code{lineno}. Cette fonction peut être utile si l'intention est d'effectuer des contrôles supplémentaires sur l'avertissement capturé :

@example
with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)
@end example

Cette méthode fonctionne indépendamment des filtres d'avertissement en place lorsqu'elle est appelée.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: Ajout de l'argument nommé `msg' lorsqu'il est utilisé comme gestionnaire de contexte.

@end deffn

@geindex assertWarnsRegex() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertWarnsRegex}@anchor{1145}
@deffn {Méthode} assertWarnsRegex (warning, regex, callable, *args, **kwds)

@deffnx {Méthode} assertWarnsRegex (warning, regex, *, msg=None)

Comme @ref{1144,,assertWarns()} mais vérifie aussi qu'une `regex' corresponde au message de l'avertissement. `regex' peut être un objet d'expression régulière ou une chaîne contenant une expression régulière appropriée pour être utilisée par @ref{120a,,re.search()}. Exemple :

@example
self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')
@end example

ou :

@example
with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')
@end example


Ajouté dans la version 3.2.



Modifié dans la version 3.3: Ajout de l'argument nommé `msg' lorsqu'il est utilisé comme gestionnaire de contexte.

@end deffn

@geindex assertLogs() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertLogs}@anchor{843}
@deffn {Méthode} assertLogs (logger=None, level=None)

Un gestionnaire de contexte pour tester qu'au moins un message est enregistré sur le `logger' ou un de ses enfants, avec au moins le `niveau' donné.

Si donné, `logger' doit être une classe @code{logging.logger} objet ou une classe @ref{435,,str} donnant le nom d'un journal. La valeur par défaut est le journal racine `root', qui capture tous les messages qui n'ont pas été arrêtés par un `logger' ne propageant pas les messages.

If given, `level' should be either a numeric logging level or
its string equivalent (for example either @code{"ERROR"} or
@ref{1c82,,logging.ERROR}).  The default is @ref{1c80,,logging.INFO}.

Le test passe si au moins un message émis à l'intérieur du bloc @code{with} correspond aux conditions `logger' et `level', sinon il échoue.

L'objet retourné par le gestionnaire de contexte est une aide à l'enregistrement qui garde la trace des messages de journal correspondants. Il a deux attributs :

@geindex records (attribut unittest.TestCase)
@anchor{library/unittest unittest TestCase records}@anchor{3fb7}
@deffn {Attribut} records

Une liste d'objets @ref{fd1,,logging.LogRecord} de messages de log correspondants.
@end deffn

@geindex output (attribut unittest.TestCase)
@anchor{library/unittest unittest TestCase output}@anchor{3fb8}
@deffn {Attribut} output

Une liste d'objets @ref{435,,str} avec la sortie formatée des messages correspondants.
@end deffn

Exemple :

@example
with self.assertLogs('foo', level='INFO') as cm:
    logging.getLogger('foo').info('first message')
    logging.getLogger('foo.bar').error('second message')
self.assertEqual(cm.output, ['INFO:foo:first message',
                             'ERROR:foo.bar:second message'])
@end example


Ajouté dans la version 3.4.

@end deffn

@geindex assertNoLogs() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertNoLogs}@anchor{842}
@deffn {Méthode} assertNoLogs (logger=None, level=None)

A context manager to test that no messages are logged on
the `logger' or one of its children, with at least the given
`level'.

If given, `logger' should be a @ref{b3d,,logging.Logger} object or a
@ref{435,,str} giving the name of a logger.  The default is the root
logger, which will catch all messages.

If given, `level' should be either a numeric logging level or
its string equivalent (for example either @code{"ERROR"} or
@ref{1c82,,logging.ERROR}).  The default is @ref{1c80,,logging.INFO}.

Unlike @ref{843,,assertLogs()}, nothing will be returned by the context
manager.


Ajouté dans la version 3.10.

@end deffn

Il existe également d'autres méthodes utilisées pour effectuer des contrôles plus spécifiques, telles que :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Méthode

@tab

Vérifie que

@tab

Disponible en

@item

@ref{514,,assertAlmostEqual(a@comma{} b)}

@tab

@code{round(a-b, 7) == 0}

@tab

@item

@ref{515,,assertNotAlmostEqual(a@comma{} b)}

@tab

@code{round(a-b, 7) != 0}

@tab

@item

@ref{131d,,assertGreater(a@comma{} b)}

@tab

@code{a > b}

@tab

3.1

@item

@ref{131e,,assertGreaterEqual(a@comma{} b)}

@tab

@code{a >= b}

@tab

3.1

@item

@ref{131f,,assertLess(a@comma{} b)}

@tab

@code{a < b}

@tab

3.1

@item

@ref{1320,,assertLessEqual(a@comma{} b)}

@tab

@code{a <= b}

@tab

3.1

@item

@ref{517,,assertRegex(s@comma{} r)}

@tab

@code{r.search(s)}

@tab

3.1

@item

@ref{519,,assertNotRegex(s@comma{} r)}

@tab

@code{not r.search(s)}

@tab

3.2

@item

@ref{1208,,assertCountEqual(a@comma{} b)}

@tab

`a' et `b' ont les mêmes éléments dans le même nombre, quel que soit leur ordre.

@tab

3.2

@end multitable


@geindex assertAlmostEqual() (méthode unittest.TestCase)
@geindex assertNotAlmostEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertAlmostEqual}@anchor{514}
@deffn {Méthode} assertAlmostEqual (first, second, places=7, msg=None, delta=None)
@anchor{library/unittest unittest TestCase assertNotAlmostEqual}@anchor{515}
@deffnx {Méthode} assertNotAlmostEqual (first, second, places=7, msg=None, delta=None)

Vérifie que `first' et `second' sont approximativement (ou pas approximativement) égaux en calculant la différence, en arrondissant au nombre donné de décimales `places' (par défaut 7), et en comparant à zéro. Notez que ces méthodes arrondissent les valeurs au nombre donné de `décimales' (par exemple comme la fonction @ref{12b8,,round()}) et non aux `chiffres significatifs'.

Si `delta' est fourni au lieu de `places', la différence entre `first' et `second' doit être inférieure ou égale (ou supérieure) à `delta'.

Fournir à la fois `delta' et `places' lève une @ref{522,,TypeError}.


Modifié dans la version 3.2: @ref{514,,assertAlmostEqual()} considère automatiquement des objets presque égaux qui se comparent égaux. @code{assertNotNotAlmostEqual()} échoue automatiquement si les objets qui se comparent sont égaux.  Ajout de l'argument nommé `delta'.

@end deffn

@geindex assertGreater() (méthode unittest.TestCase)
@geindex assertGreaterEqual() (méthode unittest.TestCase)
@geindex assertLess() (méthode unittest.TestCase)
@geindex assertLessEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertGreater}@anchor{131d}
@deffn {Méthode} assertGreater (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertGreaterEqual}@anchor{131e}
@deffnx {Méthode} assertGreaterEqual (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertLess}@anchor{131f}
@deffnx {Méthode} assertLess (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertLessEqual}@anchor{1320}
@deffnx {Méthode} assertLessEqual (first, second, msg=None)

Vérifie que `first' est respectivement >, >=, >=, < ou <= à `second' selon le nom de la méthode.  Sinon, le test échouera :

@example
>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex assertRegex() (méthode unittest.TestCase)
@geindex assertNotRegex() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertRegex}@anchor{517}
@deffn {Méthode} assertRegex (text, regex, msg=None)
@anchor{library/unittest unittest TestCase assertNotRegex}@anchor{519}
@deffnx {Méthode} assertNotRegex (text, regex, msg=None)

Vérifie qu'une  recherche par motif `regex' correspond (ou ne correspond pas) à `text'.  En cas d'échec, le message d'erreur inclura le motif et le `texte' (ou le motif et la partie du `texte' qui correspond de manière inattendue).  `regex' peut être un objet d'expression régulière ou une chaîne contenant une expression régulière appropriée pour être utilisée par @ref{120a,,re.search()}.


Ajouté dans la version 3.1: Ajouté sous le nom @code{assertRegexpMatches}.



Modifié dans la version 3.2: La méthode @code{assertRegexpMatches()} a été renommé en @ref{517,,assertRegex()}.



Ajouté dans la version 3.2: @ref{519,,assertNotRegex()}.

@end deffn

@geindex assertCountEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertCountEqual}@anchor{1208}
@deffn {Méthode} assertCountEqual (first, second, msg=None)

Vérifie que la séquence `first' contient les mêmes éléments que `second', quel que soit leur ordre. Si ce n'est pas le cas, un message d'erreur indiquant les différences entre les séquences est généré.

Les éléments en double ne sont `pas' ignorés lors de la comparaison entre `first' et `second'. Il vérifie si chaque élément a le même nombre dans les deux séquences. Équivalent à : @code{assertEqual(Counter(list(first))), Counter(list(second)))} mais fonctionne aussi avec des séquences d'objets non `hachables'.


Ajouté dans la version 3.2.

@end deffn
@anchor{library/unittest type-specific-methods}@anchor{3fb6}
La méthode @ref{512,,assertEqual()} envoie le contrôle d'égalité pour les objets du même type à différentes méthodes spécifiques au type. Ces méthodes sont déjà implémentées pour la plupart des types intégrés, mais il est également possible d'enregistrer de nouvelles méthodes en utilisant @ref{1326,,addTypeEqualityFunc()} :

@geindex addTypeEqualityFunc() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase addTypeEqualityFunc}@anchor{1326}
@deffn {Méthode} addTypeEqualityFunc (typeobj, function)

Enregistre une méthode spécifique appelée par @ref{512,,assertEqual()} pour vérifier si deux objets exactement du même `typeobj' (et non leurs sous-classes) sont égaux. `function' doit prendre deux arguments positionnels et un troisième argument nommé `msg=None' tout comme @ref{512,,assertEqual()} le fait. Il doit lever @ref{3fb9,,self.failureException(msg)} lorsqu'une inégalité entre les deux premiers paramètres est détectée en fournissant éventuellement des informations utiles et expliquant l'inégalité en détail dans le message d'erreur.


Ajouté dans la version 3.1.

@end deffn

La liste des méthodes spécifiques utilisées automatiquement par @ref{512,,assertEqual()} est résumée dans le tableau suivant.  Notez qu'il n'est généralement pas nécessaire d'invoquer ces méthodes directement.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} 
@headitem

Méthode

@tab

Utilisé pour comparer

@tab

Disponible en

@item

@ref{1321,,assertMultiLineEqual(a@comma{} b)}

@tab

chaînes

@tab

3.1

@item

@ref{1267,,assertSequenceEqual(a@comma{} b)}

@tab

séquences

@tab

3.1

@item

@ref{1265,,assertListEqual(a@comma{} b)}

@tab

listes

@tab

3.1

@item

@ref{1266,,assertTupleEqual(a@comma{} b)}

@tab

`n'-uplets

@tab

3.1

@item

@ref{1263,,assertSetEqual(a@comma{} b)}

@tab

`sets' ou `frozensets'

@tab

3.1

@item

@ref{1264,,assertDictEqual(a@comma{} b)}

@tab

dictionnaires

@tab

3.1

@end multitable


@geindex assertMultiLineEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertMultiLineEqual}@anchor{1321}
@deffn {Méthode} assertMultiLineEqual (first, second, msg=None)

Vérifie que la chaîne sur plusieurs lignes `first' est égale à la chaîne `second'. Si les deux chaînes de caractères ne sont pas égales, un `diff' mettant en évidence les différences est inclus dans le message d'erreur. Cette méthode est utilisée par défaut pour comparer les chaînes avec @ref{512,,assertEqual()}.


Ajouté dans la version 3.1.

@end deffn

@geindex assertSequenceEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertSequenceEqual}@anchor{1267}
@deffn {Méthode} assertSequenceEqual (first, second, msg=None, seq_type=None)

Vérifie que deux séquences sont égales. Si un `seq_type' est fourni, `first' et `second' doivent tous deux être des instances de `seq_type' ou un échec est levé. Si les séquences sont différentes, un message d'erreur indiquant la différence entre les deux est généré.

Cette méthode n'est pas appelée directement par @ref{512,,assertEqual()}, mais sert à implémenter @ref{1265,,assertListEqual()} et @ref{1266,,assertTupleEqual()}.


Ajouté dans la version 3.1.

@end deffn

@geindex assertListEqual() (méthode unittest.TestCase)
@geindex assertTupleEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertListEqual}@anchor{1265}
@deffn {Méthode} assertListEqual (first, second, msg=None)
@anchor{library/unittest unittest TestCase assertTupleEqual}@anchor{1266}
@deffnx {Méthode} assertTupleEqual (first, second, msg=None)

Vérifie que deux listes ou deux `n'-uplets sont égaux.  Si ce n'est pas le cas, un message d'erreur qui ne montre que les différences entre les deux est généré.  Une erreur est également signalée si l'un ou l'autre des paramètres n'est pas du bon type. Ces méthodes sont utilisées par défaut pour comparer des listes ou des `n'-uplets avec @ref{512,,assertEqual()}.


Ajouté dans la version 3.1.

@end deffn

@geindex assertSetEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertSetEqual}@anchor{1263}
@deffn {Méthode} assertSetEqual (first, second, msg=None)

Vérifie que deux ensembles sont égaux. Si ce n'est pas le cas, un message d'erreur s'affiche et indique les différences entre les `sets'. Cette méthode est utilisée par défaut lors de la comparaison de `sets' ou de `frozensets' avec @ref{512,,assertEqual()}.

Échoue si l'un des objets `first' ou `second' n'a pas de méthode @code{set.difference()}.


Ajouté dans la version 3.1.

@end deffn

@geindex assertDictEqual() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase assertDictEqual}@anchor{1264}
@deffn {Méthode} assertDictEqual (first, second, msg=None)

Vérifie que deux dictionnaires sont égaux. Si ce n'est pas le cas, un message d'erreur qui montre les différences dans les dictionnaires est généré. Cette méthode est utilisée par défaut pour comparer les dictionnaires dans les appels à @ref{512,,assertEqual()}.


Ajouté dans la version 3.1.

@end deffn
@anchor{library/unittest other-methods-and-attrs}@anchor{3fba}
Enfin, la classe @ref{437,,TestCase} fournit les méthodes et attributs suivants :

@geindex fail() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase fail}@anchor{3fbb}
@deffn {Méthode} fail (msg=None)

Indique un échec du test sans condition, avec `msg' ou @code{None} pour le message d'erreur.
@end deffn

@geindex failureException (attribut unittest.TestCase)
@anchor{library/unittest unittest TestCase failureException}@anchor{3fb9}
@deffn {Attribut} failureException

Cet attribut de classe donne l'exception levée par la méthode de test.  Si un `framework' de tests doit utiliser une exception spécialisée, probablement pour enrichir l'exception d'informations additionnels., il doit hériter de cette classe d'exception pour `bien fonctionner'  avec le `framework'. La valeur initiale de cet attribut est @ref{694,,AssertionError}.
@end deffn

@geindex longMessage (attribut unittest.TestCase)
@anchor{library/unittest unittest TestCase longMessage}@anchor{1314}
@deffn {Attribut} longMessage

Cet attribut de classe détermine ce qui se passe lorsqu'un message d'échec personnalisé est passé en argument au paramètre `msg' à un appel `assertXYYY' qui échoue. @code{True} est la valeur par défaut. Dans ce cas, le message personnalisé est ajouté à la fin du message d'erreur standard. Lorsqu'il est réglé sur @code{False}, le message personnalisé remplace le message standard.

Le paramétrage de la classe peut être écrasé dans les méthodes de test individuelles en assignant un attribut d'instance, `self.longMessage', à @code{True} ou @code{False} avant d'appeler les méthodes d'assertion.

Le réglage de la classe est réinitialisé avant chaque appel de test.


Ajouté dans la version 3.1.

@end deffn

@geindex maxDiff (attribut unittest.TestCase)
@anchor{library/unittest unittest TestCase maxDiff}@anchor{1209}
@deffn {Attribut} maxDiff

Cet attribut contrôle la longueur maximale des `diffs' en sortie des méthodes qui génèrent des `diffs' en cas d'échec. La valeur par défaut est 80*8 caractères. Les méthodes d'assertions affectées par cet attribut sont @ref{1267,,assertSequenceEqual()} (y compris toutes les méthodes de comparaison de séquences qui lui sont déléguées), @ref{1264,,assertDictEqual()} et @ref{1321,,assertMultiLineEqual()}.

Régler @code{maxDiff} sur @code{None} signifie qu'il n'y a pas de longueur maximale pour les `diffs'.


Ajouté dans la version 3.2.

@end deffn

Les `frameworks' de test peuvent utiliser les méthodes suivantes pour recueillir des informations sur le test :

@geindex countTestCases() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase countTestCases}@anchor{3fbc}
@deffn {Méthode} countTestCases ()

Renvoie le nombre de tests représentés par cet objet test. Pour les instances de @ref{437,,TestCase}, c'est toujours @code{1}.
@end deffn

@geindex defaultTestResult() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase defaultTestResult}@anchor{3fb5}
@deffn {Méthode} defaultTestResult ()

Retourne une instance de la classe de résultat de test qui doit être utilisée pour cette classe de cas de test (si aucune autre instance de résultat n'est fournie à la méthode @ref{1146,,run()}).

Pour les instances de @ref{437,,TestCase}, c'est toujours une instance de @ref{1147,,TestResult} ; les sous-classes de @ref{437,,TestCase} peuvent la remplacer au besoin.
@end deffn

@geindex id() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase id}@anchor{3fbd}
@deffn {Méthode} id ()

Retourne une chaîne identifiant le cas de test spécifique. Il s'agit généralement du nom complet de la méthode de test, y compris le nom du module et de la classe.
@end deffn

@geindex shortDescription() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase shortDescription}@anchor{3fbe}
@deffn {Méthode} shortDescription ()

Renvoie une description du test, ou @code{None} si aucune description n'a été fournie. L'implémentation par défaut de cette méthode renvoie la première ligne de la `docstring' de la méthode de test, si disponible, ou @code{None}.


Modifié dans la version 3.1: En 3.1, ceci a été modifié pour ajouter le nom du test à la description courte, même en présence d'une `docstring'. Cela a causé des problèmes de compatibilité avec les extensions `unittest' et l'ajout du nom du test a été déplacé dans la classe @ref{51a,,TextTestResult} dans Python 3.2.

@end deffn

@geindex addCleanup() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase addCleanup}@anchor{a6f}
@deffn {Méthode} addCleanup (function, /, *args, **kwargs)

Ajout d'une fonction à appeler après @ref{1318,,tearDown()} pour nettoyer les ressources utilisées pendant le test. Les fonctions seront appelées dans l'ordre inverse de l'ordre dans lequel elles ont été ajoutées (@abbr{LIFO}).  Elles sont appelées avec tous les arguments positionnels et arguments nommés passés à @ref{a6f,,addCleanup()} quand elles sont ajoutées.

Si @ref{1317,,setUp()} échoue, cela signifie que @ref{1318,,tearDown()} n'est pas appelé, alors que les fonctions de nettoyage ajoutées seront toujours appelées.


Ajouté dans la version 3.1.

@end deffn

@geindex enterContext() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase enterContext}@anchor{6a4}
@deffn {Méthode} enterContext (cm)

Enter the supplied @ref{5be,,context manager}.  If successful, also
add its @ref{12de,,__exit__()} method as a cleanup function by
@ref{a6f,,addCleanup()} and return the result of the
@ref{5b2,,__enter__()} method.


Ajouté dans la version 3.11.

@end deffn

@geindex doCleanups() (méthode unittest.TestCase)
@anchor{library/unittest unittest TestCase doCleanups}@anchor{1316}
@deffn {Méthode} doCleanups ()

Cette méthode est appelée sans conditions après @ref{1318,,tearDown()}, ou après @ref{1317,,setUp()} si @ref{1317,,setUp()} lève une exception.

Cette méthode est chargée d'appeler toutes les fonctions de nettoyage ajoutées par @ref{a6f,,addCleanup()}. Si vous avez besoin de fonctions de nettoyage à appeler `avant' l'appel à @ref{1318,,tearDown()} alors vous pouvez appeler @ref{1316,,doCleanups()} vous-même.

@ref{1316,,doCleanups()} extrait les méthodes de la pile des fonctions de nettoyage une à la fois, de sorte qu'elles peuvent être appelées à tout moment.


Ajouté dans la version 3.1.

@end deffn

@geindex addClassCleanup() (méthode de la classe unittest.TestCase)
@anchor{library/unittest unittest TestCase addClassCleanup}@anchor{a3c}
@deffn {Méthode} classmethod addClassCleanup (function, /, *args, **kwargs)

Ajout d'une fonction à appeler après @ref{1315,,tearDownClass()} pour nettoyer les ressources utilisées par la classe test. Les fonctions sont appelées dans l'ordre inverse de l'ordre dans lequel elles ont été ajoutées (@abbr{LIFO}). Elles sont appelées avec tous les arguments positionnels et nommés passés à @ref{a3c,,addClassCleanup()} quand elles sont ajoutées.

Si @ref{a3d,,setUpClass()} échoue, impliquant que @ref{1315,,tearDownClass()} n'est pas appelé, alors les fonctions de nettoyage ajoutées sont quand même appelées.


Ajouté dans la version 3.8.

@end deffn

@geindex enterClassContext() (méthode de la classe unittest.TestCase)
@anchor{library/unittest unittest TestCase enterClassContext}@anchor{6a5}
@deffn {Méthode} classmethod enterClassContext (cm)

Enter the supplied @ref{5be,,context manager}.  If successful, also
add its @ref{12de,,__exit__()} method as a cleanup function by
@ref{a3c,,addClassCleanup()} and return the result of the
@ref{5b2,,__enter__()} method.


Ajouté dans la version 3.11.

@end deffn

@geindex doClassCleanups() (méthode de la classe unittest.TestCase)
@anchor{library/unittest unittest TestCase doClassCleanups}@anchor{3fbf}
@deffn {Méthode} classmethod doClassCleanups ()

Cette méthode est appelée sans conditions après @ref{1315,,tearDownClass()}, ou après @ref{a3d,,setUpClass()} si @ref{a3d,,setUpClass()} lève une exception.

Cette méthode est chargée d'appeler toutes les fonctions de nettoyage ajoutées par @ref{a3c,,addClassCleanup()}. Si vous avez besoin de fonctions de nettoyage à appeler `avant' l'appel à @ref{1315,,tearDownClass()} alors vous pouvez appeler @ref{3fbf,,doClassCleanups()} vous-même.

@ref{3fbf,,doClassCleanups()} extrait les méthodes de la pile des fonctions de nettoyage une à la fois, de sorte qu'elles peuvent être appelées à tout moment.


Ajouté dans la version 3.8.

@end deffn
@end deffn

@geindex IsolatedAsyncioTestCase (classe dans unittest)
@anchor{library/unittest unittest IsolatedAsyncioTestCase}@anchor{301}
@deffn {Classe} unittest.IsolatedAsyncioTestCase (methodName='runTest')

Cette classe fournit une API similaire à @ref{437,,TestCase} et accepte aussi les coroutines en tant que fonctions de test.


Ajouté dans la version 3.8.


@geindex loop_factory (attribut unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase loop_factory}@anchor{3fc0}
@deffn {Attribut} loop_factory

The `loop_factory' passed to @ref{5eb,,asyncio.Runner}. Override
in subclasses with @ref{167f,,asyncio.EventLoop} to avoid using the
asyncio policy system.


Ajouté dans la version 3.13.

@end deffn

@geindex asyncSetUp() (méthode unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase asyncSetUp}@anchor{3fc1}
@deffn {Méthode} coroutine asyncSetUp ()

Méthode appelée pour réaliser la mise en place du test. Celle-ci est exécutée après @code{setUp()}. Elle est exécutée immédiatement avant l'appel de la méthode de test ; à l'exception de @ref{694,,AssertionError} ou @ref{fcf,,SkipTest}, toute exception levée par cette méthode est considérée comme une erreur et non pas comme un échec du test. L'implémentation par défaut ne fait rien.
@end deffn

@geindex asyncTearDown() (méthode unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase asyncTearDown}@anchor{3fc2}
@deffn {Méthode} coroutine asyncTearDown ()

Méthode appelée immédiatement après l'appel de la méthode de test et l'enregistrement du résultat. Elle est appelée avant @code{tearDown()}. Elle est appelée même si la méthode de test a levé une exception. De fait, l'implémentation d'une sous-classe doit être faite avec précaution si vous vérifiez l'état interne de la classe. Toute exception, autre que @ref{694,,AssertionError} ou @ref{fcf,,SkipTest}, levée par cette méthode est considérée comme une erreur supplémentaire plutôt que comme un échec du test (augmentant ainsi le nombre total des erreurs signalées). Cette méthode est appelée uniquement si l'exécution de @ref{3fc1,,asyncSetUp()} est réussie quel que soit le résultat de la méthode de test. L'implémentation par défaut ne fait rien.
@end deffn

@geindex addAsyncCleanup() (méthode unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase addAsyncCleanup}@anchor{3fc3}
@deffn {Méthode} addAsyncCleanup (function, /, *args, **kwargs)

Cette méthode accepte une coroutine qui peut être utilisée comme fonction de nettoyage.
@end deffn

@geindex enterAsyncContext() (méthode unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase enterAsyncContext}@anchor{6a6}
@deffn {Méthode} coroutine enterAsyncContext (cm)

Enter the supplied @ref{5c1,,asynchronous context manager}.  If successful,
also add its @ref{15b3,,__aexit__()} method as a cleanup function by
@ref{3fc3,,addAsyncCleanup()} and return the result of the
@ref{1f53,,__aenter__()} method.


Ajouté dans la version 3.11.

@end deffn

@geindex run() (méthode unittest.IsolatedAsyncioTestCase)
@anchor{library/unittest unittest IsolatedAsyncioTestCase run}@anchor{3fc4}
@deffn {Méthode} run (result=None)

Configure une nouvelle boucle d'évènements pour exécuter le test, en collectant le résultat dans l'objet @ref{1147,,TestResult} passé comme `result'. Si `result' est omis ou vaut @code{None}, un objet temporaire de résultat est créé (en appelant la méthode @code{defaultTestResult()}) et utilisé. L'objet résultat est renvoyé à l'appelant de @ref{3fc4,,run()}. À la fin du test, toutes les taches de la boucle d’événements sont annulées.
@end deffn

Exemple illustrant l'ordre :

@example
from unittest import IsolatedAsyncioTestCase

events = []


class Test(IsolatedAsyncioTestCase):


    def setUp(self):
        events.append("setUp")

    async def asyncSetUp(self):
        self._async_connection = await AsyncConnection()
        events.append("asyncSetUp")

    async def test_response(self):
        events.append("test_response")
        response = await self._async_connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)
        self.addAsyncCleanup(self.on_cleanup)

    def tearDown(self):
        events.append("tearDown")

    async def asyncTearDown(self):
        await self._async_connection.close()
        events.append("asyncTearDown")

    async def on_cleanup(self):
        events.append("cleanup")

if __name__ == "__main__":
    unittest.main()
@end example

Après avoir lancé les tests, @code{events} contiendrait @code{["setUp", "asyncSetUp", "test_response", "asyncTearDown", "tearDown", "cleanup"]}.
@end deffn

@geindex FunctionTestCase (classe dans unittest)
@anchor{library/unittest unittest FunctionTestCase}@anchor{1692}
@deffn {Classe} unittest.FunctionTestCase (testFunc, setUp=None, tearDown=None, description=None)

Cette classe implémente la partie de l'interface @ref{437,,TestCase} qui permet au lanceur de test de piloter le scénario de test, mais ne fournit pas les méthodes que le code test peut utiliser pour vérifier et signaler les erreurs. Ceci est utilisé pour créer des scénario de test utilisant du code de test existant afin de faciliter l'intégration dans un `framework' de test basé sur @ref{105,,unittest}.
@end deffn

@node Regroupement des tests,Chargement et exécution des tests,Scénarios de tests,Classes et fonctions
@anchor{library/unittest grouping-tests}@anchor{3fc5}@anchor{library/unittest testsuite-objects}@anchor{3fc6}
@subsubsection Regroupement des tests


@geindex TestSuite (classe dans unittest)
@anchor{library/unittest unittest TestSuite}@anchor{de1}
@deffn {Classe} unittest.TestSuite (tests=())

Cette classe représente une agrégation de cas de test individuels et de suites de tests. La classe présente l'interface requise par le lanceur de test pour être exécutée comme tout autre cas de test. L'exécution d'une instance de @ref{de1,,TestSuite} est identique à l'itération sur la suite, en exécutant chaque test indépendamment.

Si `tests' est fourni, il doit s'agir d'un itérable de cas de test individuels ou d'autres suites de test qui seront utilisés pour construire la suite initial. Des méthodes supplémentaires sont fournies pour ajouter ultérieurement des cas de test et des suites à la collection.

Les objets @ref{de1,,TestSuite} se comportent comme les objets @ref{437,,TestCase}, sauf qu'ils n'implémentent pas réellement un test. Au lieu de cela, ils sont utilisés pour regrouper les tests en groupes de tests qui doivent être exécutés ensemble. Des méthodes supplémentaires sont disponibles pour ajouter des tests aux instances de @ref{de1,,TestSuite} :

@geindex addTest() (méthode unittest.TestSuite)
@anchor{library/unittest unittest TestSuite addTest}@anchor{3fc7}
@deffn {Méthode} addTest (test)

Ajouter un objet @ref{437,,TestCase} ou @ref{de1,,TestSuite} à la suite de tests.
@end deffn

@geindex addTests() (méthode unittest.TestSuite)
@anchor{library/unittest unittest TestSuite addTests}@anchor{3fc8}
@deffn {Méthode} addTests (tests)

Ajouter tous les tests d'un itérable d'instances de @ref{437,,TestCase} et de @ref{de1,,TestSuite} à cette suite de tests.

C'est l'équivalent d'une itération sur `tests', appelant @ref{3fc7,,addTest()} pour chaque élément.
@end deffn

@ref{de1,,TestSuite} partage les méthodes suivantes avec @ref{437,,TestCase} :

@geindex run() (méthode unittest.TestSuite)
@anchor{library/unittest unittest TestSuite run}@anchor{3fc9}
@deffn {Méthode} run (result)

Exécute les tests associés à cette suite, en collectant le résultat dans l'objet de résultat de test passé par `result'.  Remarquer que contrairement à @ref{1146,,TestCase.run()}, @ref{3fc9,,TestSuite.run()} nécessite que l'objet résultat soit passé.
@end deffn

@geindex debug() (méthode unittest.TestSuite)
@anchor{library/unittest unittest TestSuite debug}@anchor{3fca}
@deffn {Méthode} debug ()

Exécute les tests associés à cette suite sans collecter le résultat. Ceci permet aux exceptions levées par le test d'être propagées à l'appelant et peut être utilisé pour exécuter des tests sous un débogueur.
@end deffn

@geindex countTestCases() (méthode unittest.TestSuite)
@anchor{library/unittest unittest TestSuite countTestCases}@anchor{3fcb}
@deffn {Méthode} countTestCases ()

Renvoie le nombre de tests représentés par cet objet de test, y compris tous les tests individuels et les sous-suites.
@end deffn

@geindex __iter__() (méthode unittest.TestSuite)
@anchor{library/unittest unittest TestSuite __iter__}@anchor{1012}
@deffn {Méthode} __iter__ ()

Tests grouped by a @ref{de1,,TestSuite} are always accessed by iteration.
Subclasses can lazily provide tests by overriding @code{__iter__()}. Note
that this method may be called several times on a single suite (for
example when counting tests or comparing for equality) so the tests
returned by repeated iterations before @ref{3fc9,,TestSuite.run()} must be the
same for each call iteration. After @ref{3fc9,,TestSuite.run()}, callers should
not rely on the tests returned by this method unless the caller uses a
subclass that overrides @code{TestSuite._removeTestAtIndex()} to preserve
test references.


Modifié dans la version 3.2: In earlier versions the @ref{de1,,TestSuite} accessed tests directly rather
than through iteration, so overriding @code{__iter__()} wasn't sufficient
for providing tests.



Modifié dans la version 3.4: Dans les versions précédentes, la classe @ref{de1,,TestSuite} contenait des références à chaque @ref{437,,TestCase} après l'appel à @ref{3fc9,,TestSuite.run()}. Les sous-classes peuvent restaurer ce comportement en surchargeant @code{TestSuite._removeTestAtIndex()}.

@end deffn

Dans l'utilisation typique de l'objet @ref{de1,,TestSuite}, la méthode @ref{3fc9,,run()} est invoquée par une classe @code{TestRunner} plutôt que par le système de test de l'utilisateur.
@end deffn

@node Chargement et exécution des tests,,Regroupement des tests,Classes et fonctions
@anchor{library/unittest loading-and-running-tests}@anchor{3fcc}
@subsubsection Chargement et exécution des tests


@geindex TestLoader (classe dans unittest)
@anchor{library/unittest unittest TestLoader}@anchor{28b}
@deffn {Classe} unittest.TestLoader

La classe @ref{28b,,TestLoader} est utilisée pour créer des suites de tests à partir de classes et de modules. Normalement, il n'est pas nécessaire de créer une instance de cette classe ; le module @ref{105,,unittest} fournit une instance qui peut être partagée comme @ref{3fcd,,unittest.defaultTestLoader}. L'utilisation d'une sous-classe ou d'une instance permet cependant de personnaliser certaines propriétés configurables.

Les objets de la classe @ref{28b,,TestLoader} ont les attributs suivants :

@geindex errors (attribut unittest.TestLoader)
@anchor{library/unittest unittest TestLoader errors}@anchor{e77}
@deffn {Attribut} errors

A list of the non-fatal errors encountered while loading tests. Not reset
by the loader at any point. Fatal errors are signalled by the relevant
method raising an exception to the caller. Non-fatal errors are also
indicated by a synthetic test that will raise the original error when
run.


Ajouté dans la version 3.5.

@end deffn

Les objets de la classe @ref{28b,,TestLoader} ont les attributs suivants :

@geindex loadTestsFromTestCase() (méthode unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromTestCase}@anchor{28d}
@deffn {Méthode} loadTestsFromTestCase (testCaseClass)

Renvoie une suite de tous les cas de test contenus dans la classe @code{TestCaseClass}dérivée de @code{testCase}.

Une instance de cas de test est créée pour chaque méthode nommée par @ref{28e,,getTestCaseNames()}. Par défaut, ce sont les noms des méthodes commençant par "test". Si @code{getTestTestCaseNames()} ne renvoie aucune méthode, mais que la méthode @code{runTest()} est implémentée, un seul cas de test est créé pour cette méthode à la place.
@end deffn

@geindex loadTestsFromModule() (méthode unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromModule}@anchor{28c}
@deffn {Méthode} loadTestsFromModule (module, *, pattern=None)

Renvoie une suite de tous les cas de test contenus dans le module donné. Cette méthode recherche `module' pour les classes dérivées de @ref{437,,TestCase} et crée une instance de la classe pour chaque méthode de test définie pour cette classe.

@cartouche
@quotation Note 
Bien que l'utilisation d'une hiérarchie de classes @ref{437,,TestCase} (les classes dérivées de `TestCase') peut être un moyen pratique de partager des `fixtures' et des fonctions utilitaires, définir une méthode de test pour des classes de base non destinées à être directement instanciée ne marche pas bien avec cette méthode. Cela peut toutefois s'avérer utile lorsque les `fixtures' sont différentes et définies dans des sous-classes.
@end quotation
@end cartouche

Si un module fournit une fonction @code{load_tests}, il est appelé pour charger les tests. Cela permet aux modules de personnaliser le chargement des tests. C'est le protocole @ref{3fa5,,load_tests protocol}.  L'argument `pattern' est passé comme troisième argument à @code{load_tests}.


Modifié dans la version 3.2: Ajout de la prise en charge de @code{load_tests}.



Modifié dans la version 3.5: Support for a keyword-only argument `pattern' has been added.



Modifié dans la version 3.12: The undocumented and unofficial `use_load_tests' parameter has been
removed.

@end deffn

@geindex loadTestsFromName() (méthode unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromName}@anchor{1324}
@deffn {Méthode} loadTestsFromName (name, module=None)

Renvoie une suite de tous les cas de test en fonction d'un spécificateur de chaîne de caractères.

Le spécificateur `name' est un "nom pointillé" qui peut être résolu soit par un module, une classe de cas de test, une méthode de test dans une classe de cas de test, une instance de @ref{de1,,TestSuite}, ou un objet appelable qui retourne une instance de classe @ref{437,,TestCase} ou de classe @ref{de1,,TestSuite}. Ces contrôles sont appliqués dans l'ordre indiqué ici, c'est-à-dire qu'une méthode sur une classe de cas de test possible sera choisie comme "méthode de test dans une classe de cas de test", plutôt que comme "un objet appelable".

Par exemple, si vous avez un module @code{SampleTests} contenant une classe @ref{437,,TestCase} (classe dérivée de la classe @code{SampleTestCase}) avec trois méthodes de test (@code{test_one()}, @code{test_two()} et @code{test_three()}), l'élément spécificateur @code{SampleTests.sampleTestCase} renvoie une suite qui va exécuter les trois méthodes de tests. L'utilisation du spécificateur @code{SampleTests.SampleTestCase.test_two} permettrait de retourner une suite de tests qui ne lancerait que la méthode test @code{test_two()}. Le spécificateur peut se référer à des modules et packages qui n'ont pas été importés. Ils seront importés par un effet de bord.

La méthode résout facultativement `name' relatif au `module' donné.


Modifié dans la version 3.5: Si une @ref{40f,,ImportError} ou @ref{343,,AttributeError} se produit pendant la traversée de `name', un test synthétique qui enrichie l'erreur produite lors de l'exécution est renvoyé. Ces erreurs sont incluses dans les erreurs accumulées par `self.errors'.

@end deffn

@geindex loadTestsFromNames() (méthode unittest.TestLoader)
@anchor{library/unittest unittest TestLoader loadTestsFromNames}@anchor{3fce}
@deffn {Méthode} loadTestsFromNames (names, module=None)

Similaire à @ref{1324,,loadTestsFromName()}, mais prend une séquence de noms plutôt qu'un seul nom.  La valeur renvoyée est une suite de tests qui gère tous les tests définis pour chaque nom.
@end deffn

@geindex getTestCaseNames() (méthode unittest.TestLoader)
@anchor{library/unittest unittest TestLoader getTestCaseNames}@anchor{28e}
@deffn {Méthode} getTestCaseNames (testCaseClass)

Renvoie une séquence triée de noms de méthodes trouvés dans `testCaseClass' ; ceci doit être une sous-classe de @ref{437,,TestCase}.
@end deffn

@geindex discover() (méthode unittest.TestLoader)
@anchor{library/unittest unittest TestLoader discover}@anchor{fd0}
@deffn {Méthode} discover (start_dir, pattern='test*.py', top_level_dir=None)

Trouve tous les modules de test en parcourant les sous-répertoires du répertoire de démarrage spécifié, et renvoie un objet `TestSuite' qui les contient. Seuls les fichiers de test qui correspondent à `pattern' sont chargés. Seuls les noms de modules qui sont importables (c'est-à-dire qui sont des identifiants Python valides) sont chargés.

All test modules must be importable from the top level of the project. If
the start directory is not the top level directory then `top_level_dir'
must be specified separately.

Si l'importation d'un module échoue, par exemple en raison d'une erreur de syntaxe, celle-ci est alors enregistrée comme une erreur unique et la découverte se poursuit.  Si l'échec de l'importation est dû au fait que @ref{fcf,,SkipTest} est levé, il est enregistré comme un saut plutôt que comme un message d'erreur.

Si un paquet (un répertoire contenant un fichier nommé @code{__init__.py}) est trouvé, le paquet est alors vérifié pour une fonction @code{load_tests}. Si elle existe, elle s'appellera @code{package.load_tests(loader, tests, pattern)}. Le mécanisme de découverte de test prend soin de s'assurer qu'un paquet n'est vérifié qu'une seule fois au cours d'une invocation, même si la fonction `load_tests' appelle elle-même @code{loader.discover}.

Si @code{load_tests} existe alors la découverte ne poursuit pas la récursion dans le paquet, @code{load_tests} a la responsabilité de charger tous les tests dans le paquet.

The pattern is deliberately not stored as a loader attribute so that
packages can continue discovery themselves.

`top_level_dir' is stored internally, and used as a default to any
nested calls to @code{discover()}. That is, if a package's @code{load_tests}
calls @code{loader.discover()}, it does not need to pass this argument.

`start_dir' peut être un nom de module ainsi qu'un répertoire.


Ajouté dans la version 3.2.



Modifié dans la version 3.4: Les modules levant une exception @ref{fcf,,SkipTest} au moment de leur importation ne sont pas considérés comme des erreurs, et sont marqués à sauter.



Modifié dans la version 3.4: `start_dir' peut être un @ref{1bf6,,paquet-espace de nommage}.



Modifié dans la version 3.4: Les chemins sont classés avant d'être importés afin que l'ordre d'exécution soit toujours le même, même si le système de fichiers sous-jacent ne classe pas les fichiers par leur nom.



Modifié dans la version 3.5: Les paquets trouvés sont maintenant vérifiés pour @code{load_tests} indépendamment du fait que leur chemin d'accès corresponde ou non à `pattern', car il est impossible pour un nom de paquet de correspondre au motif par défaut.



Modifié dans la version 3.11: `start_dir' can not be a @ref{1bf6,,namespace packages}.
It has been broken since Python 3.7 and Python 3.11 officially remove it.



Modifié dans la version 3.13: `top_level_dir' is only stored for the duration of `discover' call.

@end deffn

Les attributs suivants d'une classe @ref{28b,,TestLoader} peuvent être configurés soit par héritage, soit par affectation sur une instance :

@geindex testMethodPrefix (attribut unittest.TestLoader)
@anchor{library/unittest unittest TestLoader testMethodPrefix}@anchor{3fcf}
@deffn {Attribut} testMethodPrefix

Chaîne donnant le préfixe des noms de méthodes qui seront interprétés comme méthodes de test. La valeur par défaut est @code{'test'}.

This affects @ref{28e,,getTestCaseNames()} and all the @code{loadTestsFrom*}
methods.
@end deffn

@geindex sortTestMethodsUsing (attribut unittest.TestLoader)
@anchor{library/unittest unittest TestLoader sortTestMethodsUsing}@anchor{3fd0}
@deffn {Attribut} sortTestMethodsUsing

Function to be used to compare method names when sorting them in
@ref{28e,,getTestCaseNames()} and all the @code{loadTestsFrom*} methods.
@end deffn

@geindex suiteClass (attribut unittest.TestLoader)
@anchor{library/unittest unittest TestLoader suiteClass}@anchor{1325}
@deffn {Attribut} suiteClass

Objet appelable qui construit une suite de tests à partir d'une liste de tests. Aucune méthode sur l'objet résultant n'est nécessaire.  La valeur par défaut est la classe @ref{de1,,TestSuite}.

This affects all the @code{loadTestsFrom*} methods.
@end deffn

@geindex testNamePatterns (attribut unittest.TestLoader)
@anchor{library/unittest unittest TestLoader testNamePatterns}@anchor{3fd1}
@deffn {Attribut} testNamePatterns

List of Unix shell-style wildcard test name patterns that test methods
have to match to be included in test suites (see @code{-k} option).

If this attribute is not @code{None} (the default), all test methods to be
included in test suites must match one of the patterns in this list.
Note that matches are always performed using @ref{182e,,fnmatch.fnmatchcase()},
so unlike patterns passed to the @code{-k} option, simple substring patterns
will have to be converted using @code{*} wildcards.

This affects all the @code{loadTestsFrom*} methods.


Ajouté dans la version 3.7.

@end deffn
@end deffn

@geindex TestResult (classe dans unittest)
@anchor{library/unittest unittest TestResult}@anchor{1147}
@deffn {Classe} unittest.TestResult

Cette classe est utilisée pour compiler des informations sur les tests qui ont réussi et ceux qui ont échoué.

Un objet @ref{1147,,TestResult} stocke les résultats d'un ensemble de tests. Les classes @ref{437,,TestCase} et @ref{de1,,TestSuite} s'assurent que les résultats sont correctement enregistrés. Les auteurs du test n'ont pas à se soucier de l'enregistrement des résultats des tests.

Les cadriciels de test construits sur @ref{105,,unittest} peuvent nécessiter l'accès à l'objet @ref{1147,,TestResult} généré en exécutant un ensemble de tests à des fins de génération de comptes-rendu. Une instance de @ref{1147,,TestResult} est alors renvoyée par la méthode @code{TestRunner.run()} à cette fin.

Les instance de @ref{1147,,TestResult} ont les attributs suivants qui sont intéressant pour l'inspection des résultats de l'exécution d'un ensemble de tests :

@geindex errors (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult errors}@anchor{3fd2}
@deffn {Attribut} errors

Une liste contenant des paires d'instances de @ref{437,,TestCase} et de chaînes de caractères contenant des traces de pile d'appels formatées. Chaque paire représente un test qui a levé une exception inattendue.
@end deffn

@geindex failures (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult failures}@anchor{3fd3}
@deffn {Attribut} failures

A list containing 2-tuples of @ref{437,,TestCase} instances and strings
holding formatted tracebacks. Each tuple represents a test where a failure
was explicitly signalled using the @ref{3f8d,,assert* methods}.
@end deffn

@geindex skipped (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult skipped}@anchor{3fd4}
@deffn {Attribut} skipped

Une liste contenant des paires d'instances de @ref{437,,TestCase} et de chaînes de caractères contenant la raison de l'omission du test.


Ajouté dans la version 3.1.

@end deffn

@geindex expectedFailures (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult expectedFailures}@anchor{3fd5}
@deffn {Attribut} expectedFailures

Une liste contenant des paires d'instances @ref{437,,TestCase} et de chaînes de caractères contenant des traces de pile d'appels formatées. Chaque paire représente un échec attendu ou une erreur du scénario de test.
@end deffn

@geindex unexpectedSuccesses (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult unexpectedSuccesses}@anchor{3fd6}
@deffn {Attribut} unexpectedSuccesses

Une liste contenant les instances @ref{437,,TestCase} qui ont été marquées comme des échecs attendus, mais qui ont réussi.
@end deffn

@geindex collectedDurations (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult collectedDurations}@anchor{1698}
@deffn {Attribut} collectedDurations

A list containing 2-tuples of test case names and floats
representing the elapsed time of each test which was run.


Ajouté dans la version 3.12.

@end deffn

@geindex shouldStop (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult shouldStop}@anchor{3fd7}
@deffn {Attribut} shouldStop

A positionner sur @code{True} quand l'exécution des tests doit être arrêter par @ref{3fd8,,stop()}.
@end deffn

@geindex testsRun (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult testsRun}@anchor{3fd9}
@deffn {Attribut} testsRun

Le nombre total de tests effectués jusqu'à présent.
@end deffn

@geindex buffer (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult buffer}@anchor{3fda}
@deffn {Attribut} buffer

S'il est défini sur `true', @code{sys.stdout} et @code{sys.stderr} sont mis dans un tampon entre les appels de @ref{3fdb,,startTest()} et @ref{3fdc,,stopTest()}. La sortie collectée est répercutée sur les sorties @code{sys.stdout} et @code{sys.stderr} réels uniquement en cas d'échec ou d'erreur du test. Toute sortie est également attachée au message d'erreur.


Ajouté dans la version 3.2.

@end deffn

@geindex failfast (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult failfast}@anchor{3fdd}
@deffn {Attribut} failfast

Si la valeur est `true' @ref{3fd8,,stop()} est appelée lors de la première défaillance ou erreur, ce qui interrompt le test en cours d'exécution.


Ajouté dans la version 3.2.

@end deffn

@geindex tb_locals (attribut unittest.TestResult)
@anchor{library/unittest unittest TestResult tb_locals}@anchor{3fde}
@deffn {Attribut} tb_locals

Si la valeur est `true', les variables locales sont affichées dans les traces d'appels.


Ajouté dans la version 3.5.

@end deffn

@geindex wasSuccessful() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult wasSuccessful}@anchor{3fdf}
@deffn {Méthode} wasSuccessful ()

Renvoie @code{True} si tous les tests effectués jusqu'à présent ont réussi, sinon renvoie @code{False}.


Modifié dans la version 3.4: Renvoie @code{False} s'il y a eu des @ref{3fd6,,unexpectedSuccesses} dans les tests annotés avec le décorateur @ref{3fac,,expectedFailure()}.

@end deffn

@geindex stop() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult stop}@anchor{3fd8}
@deffn {Méthode} stop ()

Cette méthode peut être appelée pour signaler que l'ensemble des tests en cours d'exécution doit être annulé en définissant l'attribut @ref{3fd7,,shouldStop} sur @code{True}. Les instances de @code{TestRunner} doivent respecter ce signal et se terminer sans exécuter de tests supplémentaires.

Par exemple, cette fonctionnalité est utilisée par la classe @ref{16d0,,TextTestRunner} pour arrêter le cadriciel de test lorsque l'utilisateur lance une interruption clavier. Les outils interactifs qui fournissent des implémentations de @code{TestRunner} peuvent l'utiliser de la même manière.
@end deffn

Les méthodes suivantes de la classe @ref{1147,,TestResult} sont utilisées pour maintenir les structures de données internes, et peuvent être étendues dans des sous-classes pour gérer des exigences supplémentaires en termes de compte-rendu.  Cette fonction est particulièrement utile pour créer des outils qui prennent en charge la génération de rapports interactifs pendant l'exécution des tests.

@geindex startTest() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult startTest}@anchor{3fdb}
@deffn {Méthode} startTest (test)

Appelé lorsque le scénario de test `test' est sur le point d'être exécuté.
@end deffn

@geindex stopTest() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult stopTest}@anchor{3fdc}
@deffn {Méthode} stopTest (test)

Appelé après l'exécution du cas de test `test', quel qu'en soit le résultat.
@end deffn

@geindex startTestRun() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult startTestRun}@anchor{1328}
@deffn {Méthode} startTestRun ()

Appelé une fois avant l'exécution des tests.


Ajouté dans la version 3.1.

@end deffn

@geindex stopTestRun() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult stopTestRun}@anchor{1329}
@deffn {Méthode} stopTestRun ()

Appelé une fois après l'exécution des tests.


Ajouté dans la version 3.1.

@end deffn

@geindex addError() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addError}@anchor{1825}
@deffn {Méthode} addError (test, err)

Appelé lorsque le cas de test `test' soulève une exception inattendue. `err' est un `n'-uplet de la même forme que celle renvoyée par @ref{675,,sys.exc_info()} : @code{(type, valeur, traceback)}.

L'implémentation par défaut ajoute un `n'-uplet @code{(test, formatted_err)} à l'attribut @ref{3fd2,,errors} de l'instance, où `formatted_err' est une trace formatée à partir de `err'.
@end deffn

@geindex addFailure() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addFailure}@anchor{1824}
@deffn {Méthode} addFailure (test, err)

Appelé lorsque le cas de test `test' soulève une exception inattendue. `err' est un triplet de la même forme que celui renvoyé par @ref{675,,sys.exc_info()} : @code{(type, valeur, traceback)}.

L'implémentation par défaut ajoute un `n'-uplet @code{(test, formatted_err)} à l'attribut @code{errors} de l'instance, où `formatted_err' est une trace formatée à partir de `err'.
@end deffn

@geindex addSuccess() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addSuccess}@anchor{3fe0}
@deffn {Méthode} addSuccess (test)

Appelé lorsque le scénario de test `test' réussit.

L'implémentation par défaut ne fait rien.
@end deffn

@geindex addSkip() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addSkip}@anchor{1826}
@deffn {Méthode} addSkip (test, reason)

Appelé lorsque le scénario de test `test' est ignoré. `raison' est la raison pour laquelle le test donné à été ignoré.

L'implémentation par défaut ajoute un `n'-uplet @code{(test, raison)} à l'attribut @ref{3fd4,,skipped} de l'instance.
@end deffn

@geindex addExpectedFailure() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addExpectedFailure}@anchor{3fe1}
@deffn {Méthode} addExpectedFailure (test, err)

Appelé lorsque le scénario de test `test' échoue (assertion ou exception), mais qui a été marqué avec le décorateur @ref{3fac,,expectedFailure()}.

L'implémentation par défaut ajoute un `n'-uplet @code{(test, formatted_err)} à l'attribut @code{errors} de l'instance, où `formatted_err' est une trace formatée à partir de `err'.
@end deffn

@geindex addUnexpectedSuccess() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addUnexpectedSuccess}@anchor{3fe2}
@deffn {Méthode} addUnexpectedSuccess (test)

Appelé lorsque le scénario de test `test' réussit, mais que ce scénario a été marqué avec le décorateur @ref{3fac,,expectedFailure()}.

L'implémentation par défaut ajoute le test à l'attribut @ref{3fd6,,unexpectedSuccesses} de l'instance.
@end deffn

@geindex addSubTest() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addSubTest}@anchor{1827}
@deffn {Méthode} addSubTest (test, subtest, outcome)

Appelé à la fin d'un sous-test. `test' est le cas de test correspondant à la méthode de test. `subtest' est une instance dérivée de @ref{437,,TestCase} décrivant le sous-test.

Si `outcome' est @ref{660,,None}, le sous-test a réussi. Sinon, il a échoué avec une exception où `outcome' est un triplet du formulaire renvoyé par @ref{675,,sys.exc_info()} : @code{(type, valeur, traceback)}.

L'implémentation par défaut ne fait rien lorsque le résultat est un succès, et enregistre les échecs de sous-test comme des échecs normaux.


Ajouté dans la version 3.4.

@end deffn

@geindex addDuration() (méthode unittest.TestResult)
@anchor{library/unittest unittest TestResult addDuration}@anchor{16d1}
@deffn {Méthode} addDuration (test, elapsed)

Called when the test case finishes.  `elapsed' is the time represented in
seconds, and it includes the execution of cleanup functions.


Ajouté dans la version 3.12.

@end deffn
@end deffn

@geindex TextTestResult (classe dans unittest)
@anchor{library/unittest unittest TextTestResult}@anchor{51a}
@deffn {Classe} unittest.TextTestResult (stream, descriptions, verbosity, *, durations=None)

A concrete implementation of @ref{1147,,TestResult} used by the
@ref{16d0,,TextTestRunner}. Subclasses should accept @code{**kwargs} to ensure
compatibility as the interface changes.


Ajouté dans la version 3.2.



Modifié dans la version 3.12: Added the `durations' keyword parameter.

@end deffn

@geindex defaultTestLoader (dans le module unittest)
@anchor{library/unittest unittest defaultTestLoader}@anchor{3fcd}
@deffn {Données} unittest.defaultTestLoader

Instance de la classe @ref{28b,,TestLoader} destinée à être partagée. Si aucune personnalisation de la classe @ref{28b,,TestLoader} n'est nécessaire, cette instance peut être utilisée au lieu de créer plusieurs fois de nouvelles instances.
@end deffn

@geindex TextTestRunner (classe dans unittest)
@anchor{library/unittest unittest TextTestRunner}@anchor{16d0}
@deffn {Classe} unittest.TextTestRunner (stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False, durations=None)

Une implémentation de base d'un lanceur de test qui fournit les résultats dans un flux. Si `stream' est @code{None}, par défaut, @ref{926,,sys.stderr} est utilisé comme flux de sortie. Cette classe a quelques paramètres configurables, mais est essentiellement très simple. Les applications graphiques qui exécutent des suites de tests doivent fournir des implémentations alternatives. De telles implémentations doivent accepter @code{**kwargs} car l'interface pour construire les lanceurs change lorsque des fonctionnalités sont ajoutées à `unittest'.

By default this runner shows @ref{1a3,,DeprecationWarning},
@ref{8b5,,PendingDeprecationWarning}, @ref{241,,ResourceWarning} and
@ref{4e4,,ImportWarning} even if they are @ref{3fe3,,ignored by default}.  This behavior can
be overridden using Python's @code{-Wd} or @code{-Wa} options
(see @ref{1cc4,,Warning control}) and leaving
`warnings' to @code{None}.


Modifié dans la version 3.2: Added the `warnings' parameter.



Modifié dans la version 3.2: Le flux par défaut est défini sur @ref{926,,sys.stderr} au moment de l'instanciation plutôt qu'à l'importation.



Modifié dans la version 3.5: Added the `tb_locals' parameter.



Modifié dans la version 3.12: Added the `durations' parameter.


@geindex _makeResult() (méthode unittest.TextTestRunner)
@anchor{library/unittest unittest TextTestRunner _makeResult}@anchor{3fe4}
@deffn {Méthode} _makeResult ()

Cette méthode renvoie l'instance de @code{TestResult} utilisée par @ref{3fe5,,run()}. Il n'est pas destiné à être appelé directement, mais peut être surchargée dans des sous-classes pour fournir un @code{TestResult} personnalisé.

@code{_makeResult()} instancie la classe ou l'appelable passé dans le constructeur @code{TextTestRunner} comme argument @code{resultclass}. Il vaut par défaut @ref{51a,,TextTestResult} si aucune @code{resultclass} n'est fournie. La classe de résultat est instanciée avec les arguments suivants :

@example
stream, descriptions, verbosity
@end example
@end deffn

@geindex run() (méthode unittest.TextTestRunner)
@anchor{library/unittest unittest TextTestRunner run}@anchor{3fe5}
@deffn {Méthode} run (test)

Cette méthode est l'interface publique principale du @code{TextTestRunner}. Cette méthode prend une instance @ref{de1,,TestSuite} ou @ref{437,,TestCase}. Un @ref{1147,,TestResult} est créé en appelant @ref{3fe4,,_makeResult()} et le ou les tests sont exécutés et les résultats affichés sur la sortie standard.
@end deffn
@end deffn

@geindex main() (dans le module unittest)
@anchor{library/unittest unittest main}@anchor{fce}
@deffn {Fonction} unittest.main (module='__main__', defaultTest=None, argv=None, testRunner=None, testLoader=unittest.defaultTestLoader, exit=True, verbosity=1, failfast=None, catchbreak=None, buffer=None, warnings=None)

Un programme en ligne de commande qui charge un ensemble de tests à partir du `module' et les exécute. L'utilisation principale est de rendre les modules de test facilement exécutables. L'utilisation la plus simple pour cette fonction est d'inclure la ligne suivante à la fin d'un script de test :

@example
if __name__ == '__main__':
    unittest.main()
@end example

Vous pouvez exécuter des tests avec des informations plus détaillées en utilisant l'option de verbosité :

@example
if __name__ == '__main__':
    unittest.main(verbosity=2)
@end example

L'argument `defaultTest' est soit le nom d'un seul test, soit un itérable de noms de test à exécuter si aucun nom de test n'est spécifié via `argv'. Si aucun nom de test n'est fourni via `argv', tous les tests trouvés dans `module' sont exécutés.

L'argument `argv' peut être une liste d'options passées au programme, le premier élément étant le nom du programme. S'il n'est pas spécifié ou vaut @code{None}, les valeurs de @ref{1243,,sys.argv} sont utilisées.

The `testRunner' argument can either be a test runner class or an already
created instance of it. By default @code{main} calls @ref{1327,,sys.exit()} with
an exit code indicating success (0) or failure (1) of the tests run.
An exit code of 5 indicates that no tests were run or skipped.

L'argument `testLoader' doit être une instance de @ref{28b,,TestLoader}, et par défaut de @ref{3fcd,,defaultTestLoader}.

Les @code{main} sont utilisés à partir de l'interpréteur interactif en passant dans l'argument @code{exit=False}. Ceci affiche le résultat sur la sortie standard sans appeler @ref{1327,,sys.exit()} :

@example
>>> from unittest import main
>>> main(module='test_module', exit=False)
@end example

Les paramètres `failfast', `catchbreak' et `buffer' ont le même effet que la même option en ligne de commande @ref{3f94,,command-line options}.

L'argument `warnings' spécifie l'argument @ref{8b6,,filtre d'avertissement} qui doit être utilisé lors de l'exécution des tests. Si elle n'est pas spécifiée, elle reste réglée sur @code{None} si une option @code{-W'} est passée à @code{python} (voir @ref{1cc4,,Utilisation des avertissements}), sinon elle sera réglée sur @code{'default'}.

Calling @code{main} returns an object with the @code{result} attribute that contains
the result of the tests run as a @ref{1147,,unittest.TestResult}.


Modifié dans la version 3.1: Ajout du paramètre `exit'.



Modifié dans la version 3.2: Ajout des paramètres `verbosity', `failfast', `catchbreak', `buffer' et `warnings'.



Modifié dans la version 3.4: Le paramètre `defaultTest' a été modifié pour accepter également un itérable de noms de test.

@end deffn

@menu
* Protocole de chargement des tests (load_tests Protocol): Protocole de chargement des tests load_tests Protocol. 

@end menu

@node Protocole de chargement des tests load_tests Protocol,,,Chargement et exécution des tests
@anchor{library/unittest id1}@anchor{3fa5}@anchor{library/unittest load-tests-protocol}@anchor{3f4c}
@subsubsection Protocole de chargement des tests (`load_tests Protocol')



Ajouté dans la version 3.2.


Les modules ou paquets peuvent personnaliser la façon dont les tests sont chargés à partir de ceux-ci pendant l'exécution des tests ou pendant la découverte de tests en implémentant une fonction appelée @code{load_tests}.

Si un module de test définit @code{load_tests} il est appelé par @ref{28c,,TestLoader.loadTestsFromModule()} avec les arguments suivants :

@example
load_tests(loader, standard_tests, pattern)
@end example

où `pattern' est passé directement depuis @code{loadTestsFromModule}. La valeur par défaut est @code{None}.

Elle doit renvoyer une classe @ref{de1,,TestSuite}.

`loader' est l'instance de @ref{28b,,TestLoader} qui effectue le chargement. `standard_tests' sont les tests qui sont chargés par défaut depuis le module. Il est courant que les modules de test veuillent seulement ajouter ou supprimer des tests de l'ensemble standard de tests. Le troisième argument est utilisé lors du chargement de paquets dans le cadre de la découverte de tests.

Une fonction typique de @code{load_tests} qui charge les tests d'un ensemble spécifique de classes @ref{437,,TestCase} peut ressembler à :

@example
test_cases = (TestCase1, TestCase2, TestCase3)

def load_tests(loader, tests, pattern):
    suite = TestSuite()
    for test_class in test_cases:
        tests = loader.loadTestsFromTestCase(test_class)
        suite.addTests(tests)
    return suite
@end example

Si la découverte est lancée dans un répertoire contenant un paquet, soit à partir de la ligne de commande, soit en appelant @ref{fd0,,TestLoader.discover()}, alors le système recherche dans le fichier du paquet @code{__init__.py} la fonction @code{load_tests}. Si cette fonction n'existe pas, la découverte se poursuit dans le paquet comme si c'était juste un autre répertoire. Sinon, la découverte des tests du paquet est effectuée par @code{load_tests} qui est appelé avec les arguments suivants :

@example
load_tests(loader, standard_tests, pattern)
@end example

Doit renvoyer une classe @ref{de1,,TestSuite} représentant tous les tests du paquet. (@code{standard_tests} ne contient que les tests collectés dans le fichier @code{__init__.py}).

Comme le motif est passé à @code{load_tests}, le paquet est libre de continuer (et potentiellement de modifier) la découverte des tests. Une fonction « ne rien faire » @code{load_tests} pour un paquet de test ressemblerait à :

@example
def load_tests(loader, standard_tests, pattern):
    # top level directory cached on loader instance
    this_dir = os.path.dirname(__file__)
    package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
    standard_tests.addTests(package_tests)
    return standard_tests
@end example


Modifié dans la version 3.5: La découverte de test ne vérifie plus que les noms de paquets correspondent à `pattern' en raison de l'impossibilité de trouver des noms de paquets correspondant au motif par défaut.


@node Classes et modules d'aménagements des tests,Traitement des signaux,Classes et fonctions,unittest --- Unit testing framework
@anchor{library/unittest class-and-module-fixtures}@anchor{3fb4}
@subsubsection Classes et modules d'aménagements des tests


Les classes et modules d'aménagements des tests sont implémentés dans @ref{de1,,TestSuite}. Lorsque la suite de tests rencontre un test d'une nouvelle classe, alors @code{tearDownClass()} de la classe précédente (s'il y en a une) est appelé, suivi de @code{setUpClass()} de la nouvelle classe.

De même, si un test provient d'un module différent du test précédent, alors @code{tearDownModule} du module précédent est exécuté, suivi par @code{setUpModule} du nouveau module.

Après que tous les tests ont été exécutés, les @code{tearDownClass} et @code{tearDownModule} finaux sont exécutés.

Notez que les aménagements de tests partagés ne fonctionnent pas bien avec de « potentielles » fonctions comme la parallélisation de test et qu'ils brisent l'isolation des tests. Ils doivent être utilisés avec parcimonie.

L'ordre par défaut des tests créés par les chargeurs de tests unitaires est de regrouper tous les tests des mêmes modules et classes. Cela à pour conséquence que @code{setUpClass} / @code{setUpModule} (etc) sont appelé exactement une fois par classe et module. Si vous rendez l'ordre aléatoire, de sorte que les tests de différents modules et classes soient adjacents les uns aux autres, alors ces fonctions d'aménagements partagées peuvent être appelées plusieurs fois dans un même test.

Les aménagements de tests partagés ne sont pas conçus pour fonctionner avec des suites dont la commande n'est pas standard. Une @code{BaseTestSuite} existe toujours pour les cadriciels qui ne veulent pas gérer les aménagements de tests partagés.

S'il y a des exceptions levées pendant l'une des fonctions d'aménagement de tests partagés, le test est signalé comme étant en erreur. Parce qu'il n'y a pas d'instance de test correspondante, un objet @code{_ErrorHolder} (qui a la même interface qu'une classe @ref{437,,TestCase}) est créé pour représenter l'erreur. Si vous n'utilisez que le lanceur de test unitaire standard, ce détail n'a pas d'importance, mais si vous êtes un auteur de cadriciel de test, il peut être pertinent.

@menu
* Classes de mise en place (setUpClass) et de démantèlement des tests (tearDownClass): Classes de mise en place setUpClass et de démantèlement des tests tearDownClass. 
* Module de mise en place (setUpModule) et de démantèlement des tests (tearDownModule): Module de mise en place setUpModule et de démantèlement des tests tearDownModule. 

@end menu

@node Classes de mise en place setUpClass et de démantèlement des tests tearDownClass,Module de mise en place setUpModule et de démantèlement des tests tearDownModule,,Classes et modules d'aménagements des tests
@anchor{library/unittest setupclass-and-teardownclass}@anchor{3fe6}
@subsubsection Classes de mise en place (`setUpClass') et de démantèlement des tests (`tearDownClass')


Elles doivent être implémentées en tant que méthodes de classe :

@example
import unittest

class Test(unittest.TestCase):
    @@classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @@classmethod
    def tearDownClass(cls):
        cls._connection.destroy()
@end example

Si vous voulez que les classes de base @code{setUpClass} et @code{tearDownClass} soient appelées, vous devez les appeler vous-même. Les implémentations dans @ref{437,,TestCase} sont vides.

Si une exception est levée pendant l'exécution de @code{setUpClass} alors les tests dans la classe ne sont pas exécutés et la classe @code{tearDownClass} n'est pas exécutée. Les classes ignorées n'auront pas d'exécution de @code{setUpClass} ou @code{tearDownClass}. Si l'exception est une exception @ref{fcf,,SkipTest} alors la classe est signalée comme ayant été ignorée au lieu d'être en échec.

@node Module de mise en place setUpModule et de démantèlement des tests tearDownModule,,Classes de mise en place setUpClass et de démantèlement des tests tearDownClass,Classes et modules d'aménagements des tests
@anchor{library/unittest setupmodule-and-teardownmodule}@anchor{3fe7}
@subsubsection Module de mise en place (`setUpModule') et de démantèlement des tests (`tearDownModule')


Elles doivent être implémentées en tant que fonctions :

@example
def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()
@end example

Si une exception est levée pendant l'exécution de la fonction @code{setUpModule} alors aucun des tests du module ne sera exécuté et la fonction @code{tearDownModule} ne sera pas exécutée. Si l'exception est une exception @ref{fcf,,SkipTest} alors le module est signalé comme ayant été ignoré au lieu d'être en échec.

Pour ajouter du code de nettoyage qui doit être exécuté même en cas d'exception, utilisez @code{addModuleCleanup} :

@geindex addModuleCleanup() (dans le module unittest)
@anchor{library/unittest unittest addModuleCleanup}@anchor{a3b}
@deffn {Fonction} unittest.addModuleCleanup (function, /, *args, **kwargs)

Ajout d'une fonction à appeler après @code{tearDownModule()} pour nettoyer les ressources utilisées pendant le test. Les fonctions seront appelées dans l'ordre inverse de l'ordre dans lequel elles ont été ajoutées (@abbr{LIFO}). Elles sont appelées avec tous les arguments et arguments nommés passés à @ref{a3b,,addModuleCleanup()} quand elles sont ajoutées.

Si @code{setUpModule()} échoue, impliquant que @code{tearDownModule()} n'est pas appelée, alors les fonctions de nettoyage ajoutées sont quand même toujours appelées.


Ajouté dans la version 3.8.

@end deffn

@geindex enterModuleContext() (dans le module unittest)
@anchor{library/unittest unittest enterModuleContext}@anchor{6a7}
@deffn {Méthode} classmethod unittest.enterModuleContext (cm)

Enter the supplied @ref{5be,,context manager}.  If successful, also
add its @ref{12de,,__exit__()} method as a cleanup function by
@ref{a3b,,addModuleCleanup()} and return the result of the
@ref{5b2,,__enter__()} method.


Ajouté dans la version 3.11.

@end deffn

@geindex doModuleCleanups() (dans le module unittest)
@anchor{library/unittest unittest doModuleCleanups}@anchor{17ca}
@deffn {Fonction} unittest.doModuleCleanups ()

Cette méthode est appelée sans conditions après @code{tearDownModule()}, ou après @code{setUpModule()} si @code{setUpModule()} lève une exception.

It is responsible for calling all the cleanup functions added by
@ref{a3b,,addModuleCleanup()}. If you need cleanup functions to be called
`prior' to @code{tearDownModule()} then you can call
@ref{17ca,,doModuleCleanups()} yourself.

@ref{17ca,,doModuleCleanups()} extrait les méthodes de la pile des fonctions de nettoyage une à la fois, de sorte qu'elles peuvent être appelées à tout moment.


Ajouté dans la version 3.8.

@end deffn

@node Traitement des signaux,,Classes et modules d'aménagements des tests,unittest --- Unit testing framework
@anchor{library/unittest signal-handling}@anchor{3f97}
@subsubsection Traitement des signaux



Ajouté dans la version 3.2.


The @ref{1311,,-c/--catch} command-line option to unittest,
along with the @code{catchbreak} parameter to @ref{fce,,unittest.main()}, provide
more friendly handling of control-C during a test run. With catch break
behavior enabled control-C will allow the currently running test to complete,
and the test run will then end and report all the results so far. A second
control-c will raise a @ref{9bf,,KeyboardInterrupt} in the usual way.

Le gestionnaire du signal `contrôle-C' tente de rester compatible avec le code ou les tests qui installent leur propre gestionnaire @ref{82e,,signal.SIGINT}. Si le gestionnaire @code{unittest} est appelé mais `n'est pas' le gestionnaire installé @ref{82e,,signal.SIGINT}, c'est-à-dire qu'il a été remplacé par le système sous test et délégué, alors il appelle le gestionnaire par défaut. C'est normalement le comportement attendu par un code qui remplace un gestionnaire installé et lui délègue. Pour les tests individuels qui ont besoin que le signal `contrôle-C' "`unittest'" soit désactivée, le décorateur @ref{1312,,removeHandler()} peut être utilisé.

Il existe quelques fonctions de support pour les auteurs de cadriciel afin d'activer la fonctionnalité  de gestion des `contrôle-C' dans les cadriciels de test.

@geindex installHandler() (dans le module unittest)
@anchor{library/unittest unittest installHandler}@anchor{3fe8}
@deffn {Fonction} unittest.installHandler ()

Installe le gestionnaire `contrôle-c'. Quand un @ref{82e,,signal.SIGINT} est reçu (généralement en réponse à l'utilisateur appuyant sur `contrôle-c') tous les résultats enregistrés vont appeler la méthode @ref{3fd8,,stop()}.
@end deffn

@geindex registerResult() (dans le module unittest)
@anchor{library/unittest unittest registerResult}@anchor{3fe9}
@deffn {Fonction} unittest.registerResult (result)

Enregistre un objet @ref{1147,,TestResult} pour la gestion du `contrôle-C'. L'enregistrement d'un résultat stocke une référence faible sur celui-ci, de sorte qu'il n'empêche pas que le résultat soit collecté par le ramasse-miette.

L'enregistrement d'un objet @ref{1147,,TestResult} n'a pas d'effets de bord si la gestion du `contrôle-c' n'est pas activée, donc les cadriciels de test peuvent enregistrer sans condition tous les résultats qu'ils créent indépendamment du fait que la gestion soit activée ou non.
@end deffn

@geindex removeResult() (dans le module unittest)
@anchor{library/unittest unittest removeResult}@anchor{3fea}
@deffn {Fonction} unittest.removeResult (result)

Supprime un résultat enregistré. Une fois qu'un résultat a été supprimé, @ref{3fd8,,stop()} n'est plus appelé sur cet objet résultat en réponse à un `contrôle-c'.
@end deffn

@geindex removeHandler() (dans le module unittest)
@anchor{library/unittest unittest removeHandler}@anchor{1312}
@deffn {Fonction} unittest.removeHandler (function=None)

Lorsqu'elle est appelée sans arguments, cette fonction supprime le gestionnaire `contrôle-c' s'il a été installé. Cette fonction peut également être utilisée comme décorateur de test pour supprimer temporairement le gestionnaire pendant l'exécution du test :

@example
@@unittest.removeHandler
def test_signal_handling(self):
    ...
@end example
@end deffn

@node unittest mock --- mock object library,unittest mock --- getting started,unittest --- Unit testing framework,Outils de développement
@anchor{library/unittest mock doc}@anchor{3feb}@anchor{library/unittest mock module-unittest mock}@anchor{106}@anchor{library/unittest mock unittest-mock-mock-object-library}@anchor{3fec}
@subsection @code{unittest.mock} --- mock object library


@geindex module; unittest.mock


Ajouté dans la version 3.3.


`Code source :' Lib/unittest/mock.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/unittest/mock.py}


__________________________________________________________________


@ref{106,,unittest.mock} est une bibliothèque pour tester en Python. Elle permet de remplacer des parties du système sous tests par des objets simulacres et faire des assertions sur la façon dont ces objets ont été utilisés.

@ref{106,,unittest.mock} fournit une classe @ref{a3a,,Mock} pour ne pas avoir besoin de créer manuellement des objets factices dans la suite de tests. Après avoir effectué une action, on peut faire des assertions sur les méthodes / attributs utilisés et les arguments avec lesquels ils ont été appelés. On peut également spécifier des valeurs renvoyées et définir les attributs nécessaires aux tests.

De plus, `mock' fournit un décorateur @ref{e7b,,patch()} qui est capable de `patcher' les modules et les classes dans la portée d'un test, ainsi que @ref{b8e,,sentinel} pour créer des objets uniques. Voir le guide rapide @ref{3fed,,quick guide} pour quelques exemples d'utilisation de @ref{a3a,,Mock}, @ref{e7a,,MagicMock} et @ref{e7b,,patch()}.

Mock is designed for use with @ref{105,,unittest} and
is based on the 'action -> assertion' pattern instead of 'record -> replay'
used by many mocking frameworks.

There is a backport of @ref{106,,unittest.mock} for earlier versions of Python,
available as mock@footnote{https://pypi.org/project/mock/} on PyPI.

@menu
* Guide rapide:: 
* La classe Mock:: 
* The patchers:: 
* MagicMock and magic method support:: 
* Helpers:: 
* Order of precedence of side_effect@comma{} return_value and wraps: Order of precedence of side_effect return_value and wraps. 

@end menu

@node Guide rapide,La classe Mock,,unittest mock --- mock object library
@anchor{library/unittest mock quick-guide}@anchor{3fed}
@subsubsection Guide rapide


@c class ProductionClass:
@c     def method(self, a, b, c):
@c         pass
@c 
@c class SomeClass:
@c     @staticmethod
@c     def static_method(args):
@c         return args
@c 
@c     @classmethod
@c     def class_method(cls, args):
@c         return args

Les classes @ref{a3a,,Mock} et @ref{e7a,,MagicMock} créent tous les attributs et méthodes au fur et à mesure des accès et stockent les détails de la façon dont ils ont été utilisés. On peut les configurer, pour spécifier des valeurs de renvoi ou limiter les attributs utilisables, puis faire des assertions sur la façon dont ils ont été utilisés :

@example
>>> from unittest.mock import MagicMock
>>> thing = ProductionClass()
>>> thing.method = MagicMock(return_value=3)
>>> thing.method(3, 4, 5, key='value')
3
>>> thing.method.assert_called_with(3, 4, 5, key='value')
@end example

@ref{3fee,,side_effect} allows you to perform side effects, including raising an
exception when a mock is called:

@example
>>> from unittest.mock import Mock
>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
 ...
KeyError: 'foo'
@end example

@example
>>> values = @{'a': 1, 'b': 2, 'c': 3@}
>>> def side_effect(arg):
...     return values[arg]
...
>>> mock.side_effect = side_effect
>>> mock('a'), mock('b'), mock('c')
(1, 2, 3)
>>> mock.side_effect = [5, 4, 3, 2, 1]
>>> mock(), mock(), mock()
(5, 4, 3)
@end example

Il existe beaucoup d'autres façons de configurer et de contrôler le comportement de `Mock'. Par exemple, l'argument `spec' configure le `mock' pour qu'il utilise les spécifications d'un autre objet. Tenter d'accéder à des attributs ou méthodes sur le `mock' qui n'existent pas sur l'objet `spec' lève une @ref{343,,AttributeError}.

The @ref{e7b,,patch()} decorator / context manager makes it easy to mock classes or
objects in a module under test. The object you specify will be replaced with a
mock (or other object) during the test and restored when the test ends:

@example
>>> from unittest.mock import patch
>>> @@patch('module.ClassName2')
... @@patch('module.ClassName1')
... def test(MockClass1, MockClass2):
...     module.ClassName1()
...     module.ClassName2()
...     assert MockClass1 is module.ClassName1
...     assert MockClass2 is module.ClassName2
...     assert MockClass1.called
...     assert MockClass2.called
...
>>> test()
@end example

@cartouche
@quotation Note 
Lorsque l'on imbrique des décorateurs de patchs, les `mocks' sont transmis à la fonction décorée dans le même ordre qu'ils ont été déclarés (l'ordre normal `Python' des décorateurs est appliqué). Cela signifie du bas vers le haut, donc dans l'exemple ci-dessus, l'objet simulacre pour @code{module.ClassName1} est passé en premier.

Avec @ref{e7b,,patch()}, il est important de `patcher' les objets dans l'espace de nommage où ils sont recherchés. C'est ce qui se fait normalement, mais pour un guide rapide, lisez @ref{3fef,,où patcher}.
@end quotation
@end cartouche

Comme tout décorateur, @ref{e7b,,patch()} peut être utilisé comme gestionnaire de contexte avec une instruction `with' :

@example
>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
...     thing = ProductionClass()
...     thing.method(1, 2, 3)
...
>>> mock_method.assert_called_once_with(1, 2, 3)
@end example

Il existe également @ref{1981,,patch.dict()} pour définir des valeurs d'un dictionnaire au sein d'une portée et restaurer ce dictionnaire à son état d'origine lorsque le test se termine :

@example
>>> foo = @{'key': 'value'@}
>>> original = foo.copy()
>>> with patch.dict(foo, @{'newkey': 'newvalue'@}, clear=True):
...     assert foo == @{'newkey': 'newvalue'@}
...
>>> assert foo == original
@end example

`Mock' gère le remplacement des @ref{3ff0,,méthodes magiques} de Python. La façon la plus simple d'utiliser les méthodes magiques est la classe @ref{e7a,,MagicMock}. Elle permet de faire des choses comme :

@example
>>> mock = MagicMock()
>>> mock.__str__.return_value = 'foobarbaz'
>>> str(mock)
'foobarbaz'
>>> mock.__str__.assert_called_with()
@end example

`Mock' permet d'assigner des fonctions (ou d'autres instances `Mock') à des méthodes magiques et elles seront appelées correctement. La classe @ref{e7a,,MagicMock} est juste une variante de `Mock' qui a toutes les méthodes magiques pré-créées (enfin, toutes les méthodes utiles).

L'exemple suivant est un exemple de création de méthodes magiques avec la classe `Mock' ordinaire :

@example
>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'
@end example

Pour être sûr que les objets simulacres dans vos tests ont la même API que les objets qu'ils remplacent, utilisez @ref{3ff1,,l'auto-spécification}. L'auto-spécification peut se faire via l'argument `autospec' de patch ou par la fonction @ref{1590,,create_autospec()}. L'auto-spécification crée des objets simulacres qui ont les mêmes attributs et méthodes que les objets qu'ils remplacent, et toutes les fonctions et méthodes (y compris les constructeurs) ont les mêmes signatures d'appel que l'objet réel.

Ceci garantit que vos objets simulacres échouent de la même manière que votre code de production s'ils ne sont pas utilisés correctement :

@example
>>> from unittest.mock import create_autospec
>>> def function(a, b, c):
...     pass
...
>>> mock_function = create_autospec(function, return_value='fishy')
>>> mock_function(1, 2, 3)
'fishy'
>>> mock_function.assert_called_once_with(1, 2, 3)
>>> mock_function('wrong arguments')
Traceback (most recent call last):
 ...
TypeError: missing a required argument: 'b'
@end example

La fonction @ref{1590,,create_autospec()} peut aussi être utilisée sur les classes, où elle copie la signature de la méthode @code{__init__}, et sur les objets appelables où elle copie la signature de la méthode @code{__call__}.

@node La classe Mock,The patchers,Guide rapide,unittest mock --- mock object library
@anchor{library/unittest mock the-mock-class}@anchor{3ff2}
@subsubsection La classe `Mock'


@c import asyncio
@c import inspect
@c import unittest
@c import threading
@c from unittest.mock import sentinel, DEFAULT, ANY
@c from unittest.mock import patch, call, Mock, MagicMock, PropertyMock, AsyncMock
@c from unittest.mock import ThreadingMock
@c from unittest.mock import mock_open

La classe @ref{a3a,,Mock} est un objet simulacre flexible destiné à remplacer l'utilisation d'objets bouchons et factices dans votre code. Les Mocks sont appelables et créent des attributs comme de nouveaux `Mocks' lorsque l'on y accède @footnote{
The only exceptions are magic methods and attributes (those that have
leading and trailing double underscores). Mock doesn't create these but
instead raises an @ref{343,,AttributeError}. This is because the interpreter
will often implicitly request these methods, and gets `very' confused to
get a new Mock object when it expects a magic method. If you need magic
method support see @ref{3ff0,,magic methods}.
}. L'accès au même attribut renvoie toujours le même `mock'. Les simulacres enregistrent la façon dont ils sont utilisés, ce qui permet de faire des assertions sur ce que le code leur a fait.

La classe @ref{e7a,,MagicMock} est une sous-classe de @ref{a3a,,Mock} avec toutes les méthodes magiques pré-créées et prête à l'emploi. Il existe également des variantes non appelables, utiles lorsque l'on simule des objets qui ne sont pas appelables : @ref{3ff3,,NonCallableMock} et @ref{3ff4,,NonCallableMagicMock}

Le décorateur @ref{e7b,,patch()} facilite le remplacement temporaire de classes d'un module avec un objet @ref{a3a,,Mock}. Par défaut @ref{e7b,,patch()} crée un @ref{e7a,,MagicMock}. On peut spécifier une classe alternative de @ref{a3a,,Mock} en utilisant le paramètre `new_callable' de @ref{e7b,,patch()}.

@geindex Mock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock Mock}@anchor{a3a}
@deffn {Classe} unittest.mock.Mock (spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

Crée un nouvel objet @ref{a3a,,Mock}. @ref{a3a,,Mock} prend plusieurs arguments optionnels qui spécifient le comportement de l'objet `Mock' :


@itemize *

@item 
`spec' : une liste de chaînes de caractères ou un objet existant (une classe ou une instance) qui sert de spécification pour l'objet simulacre. Si on passe un objet, alors une liste de chaînes de caractères est formée en appelant la fonction `dir' sur l'objet (à l'exclusion des attributs et méthodes magiques non pris en charge). L'accès à un attribut qui n'est pas dans cette liste entraîne la levée d'une exception @ref{343,,AttributeError}.

If `spec' is an object (rather than a list of strings) then
@ref{1461,,__class__} returns the class of the spec object. This
allows mocks to pass @ref{42b,,isinstance()} tests.

@item 
`spec_set' : variante plus stricte de `spec'. S'il est utilisé, essayer d'utiliser la fonction `set' ou tenter d’accéder à un attribut sur le `mock' qui n'est pas sur l'objet passé comme `spec_set' lève une exception @ref{343,,AttributeError}.

@item 
`side_effect' : fonction à appeler à chaque fois que le `Mock' est appelé. Voir l'attribut @ref{3fee,,side_effect}. Utile pour lever des exceptions ou modifier dynamiquement les valeurs de retour. La fonction est appelée avec les mêmes arguments que la fonction simulée et, à moins qu'elle ne renvoie @ref{3ff5,,DEFAULT}, la valeur de retour de cette fonction devient la valeur de retour de la fonction simulée.

`side_effect' peut être soit une classe, soit une instance d'exception. Dans ce cas, l'exception est levée lors de l'appel de l'objet simulacre.

Si `side_effect' est un itérable alors chaque appel au `mock' renvoie la valeur suivante de l’itérable.

Utilisez @code{None} pour remettre à zéro un `side_effect'.

@item 
`return_value' : valeur renvoyée lors de l'appel de l'objet simulacre. Par défaut, il s'agit d'un nouveau `Mock' (créé lors du premier accès). Voir l'attribut @ref{3ff6,,return_value}.

@item 
`unsafe': By default, accessing any attribute whose name starts with
`assert', `assret', `asert', `aseert' or `assrt' will raise an
@ref{343,,AttributeError}. Passing @code{unsafe=True} will allow access to
these attributes.


Ajouté dans la version 3.5.


@item 
`wraps' : élément que le simulacre doit simuler. Si `wraps' n'est pas @code{None} alors appeler `Mock' passe l'appel à l'objet simulé (renvoyant le résultat réel). L'accès à un attribut sur le `mock' renvoie un objet `Mock' qui simule l'attribut correspondant de l'objet simulé (donc essayer d'accéder à un attribut qui n'existe pas lève une exception @ref{343,,AttributeError}).

Si l'objet simulacre a un ensemble explicite de `return_value' alors les appels ne sont pas passés à l'objet simulé et c'est `return_value' qui est renvoyée à la place.

@item 
`name' : Si le `mock' a un nom, il est alors utilisé par la fonction `repr' du `mock'. C'est utile pour le débogage. Le nom est propagé aux enfants de l'objet `mock'.
@end itemize

Les `mocks' peuvent aussi être appelés avec des arguments par mots-clés arbitraires. Ceux-ci sont utilisés pour définir les attributs sur le `mock' après sa création. Voir la méthode @ref{3ff7,,configure_mock()} pour plus de détails.

@geindex assert_called() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called}@anchor{ce6}
@deffn {Méthode} assert_called ()

Asserter que le `mock' a été appelé au moins une fois.

@example
>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called()
@end example


Ajouté dans la version 3.6.

@end deffn

@geindex assert_called_once() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called_once}@anchor{ce7}
@deffn {Méthode} assert_called_once ()

Asserter que le `mock' a été appelé exactement une fois.

@example
>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_once()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_once()
Traceback (most recent call last):
...
AssertionError: Expected 'method' to have been called once. Called 2 times.
Calls: [call(), call()].
@end example


Ajouté dans la version 3.6.

@end deffn

@geindex assert_called_with() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called_with}@anchor{19af}
@deffn {Méthode} assert_called_with (*args, **kwargs)

This method is a convenient way of asserting that the last call has been
made in a particular way:

@example
>>> mock = Mock()
>>> mock.method(1, 2, 3, test='wow')
<Mock name='mock.method()' id='...'>
>>> mock.method.assert_called_with(1, 2, 3, test='wow')
@end example
@end deffn

@geindex assert_called_once_with() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_called_once_with}@anchor{3ff8}
@deffn {Méthode} assert_called_once_with (*args, **kwargs)

Assert that the mock was called exactly once and that call was with the
specified arguments.

@example
>>> mock = Mock(return_value=None)
>>> mock('foo', bar='baz')
>>> mock.assert_called_once_with('foo', bar='baz')
>>> mock('other', bar='values')
>>> mock.assert_called_once_with('other', bar='values')
Traceback (most recent call last):
  ...
AssertionError: Expected 'mock' to be called once. Called 2 times.
Calls: [call('foo', bar='baz'), call('other', bar='values')].
@end example
@end deffn

@geindex assert_any_call() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_any_call}@anchor{3ff9}
@deffn {Méthode} assert_any_call (*args, **kwargs)

Asserter que le simulacre a été appelé avec les arguments spécifiés.

Asserter que le simulacre a `bien' été appelé avec les arguments au cours de la vie du simulacre. Contrairement à @ref{19af,,assert_called_with()} et @ref{3ff8,,assert_called_once_with()} qui passent seulement si l'appel demandé correspond bien au dernier appel, et dans le cas de @ref{3ff8,,assert_called_once_with()} l'appel au simulacre doit être unique.

@example
>>> mock = Mock(return_value=None)
>>> mock(1, 2, arg='thing')
>>> mock('some', 'thing', 'else')
>>> mock.assert_any_call(1, 2, arg='thing')
@end example
@end deffn

@geindex assert_has_calls() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_has_calls}@anchor{1631}
@deffn {Méthode} assert_has_calls (calls, any_order=False)

Asserter que le simulacre a été appelé avec les appels spécifiés. L'attribut @ref{3ffa,,mock_calls} est comparé à la liste des appels.

If `any_order' is false then the calls must be
sequential. There can be extra calls before or after the
specified calls.

Si `any_order' est vrai alors les appels peuvent être dans n'importe quel ordre, mais ils doivent tous apparaître dans @ref{3ffa,,mock_calls}.

@example
>>> mock = Mock(return_value=None)
>>> mock(1)
>>> mock(2)
>>> mock(3)
>>> mock(4)
>>> calls = [call(2), call(3)]
>>> mock.assert_has_calls(calls)
>>> calls = [call(4), call(2), call(3)]
>>> mock.assert_has_calls(calls, any_order=True)
@end example
@end deffn

@geindex assert_not_called() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock assert_not_called}@anchor{e79}
@deffn {Méthode} assert_not_called ()

Asserter que le simulacre n'a jamais été appelé.

@example
>>> m = Mock()
>>> m.hello.assert_not_called()
>>> obj = m.hello()
>>> m.hello.assert_not_called()
Traceback (most recent call last):
  ...
AssertionError: Expected 'hello' to not have been called. Called 1 times.
Calls: [call()].
@end example


Ajouté dans la version 3.5.

@end deffn

@geindex reset_mock() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock reset_mock}@anchor{ce8}
@deffn {Méthode} reset_mock (*, return_value=False, side_effect=False)

La méthode `reset_mock' réinitialise tous les attributs d'appel sur un simulacre :

@example
>>> mock = Mock(return_value=None)
>>> mock('hello')
>>> mock.called
True
>>> mock.reset_mock()
>>> mock.called
False
@end example


Modifié dans la version 3.6: Added two keyword-only arguments to the reset_mock function.


This can be useful where you want to make a series of assertions that
reuse the same object. Note that @ref{ce8,,reset_mock()} `doesn't' clear the
@ref{3ff6,,return_value}, @ref{3fee,,side_effect} or any child attributes you have
set using normal assignment by default. In case you want to reset
@ref{3ff6,,return_value} or @ref{3fee,,side_effect}, then pass the corresponding
parameter as @code{True}. Child mocks and the return value mock
(if any) are reset as well.

@cartouche
@quotation Note 
`return_value', and `side_effect' are keyword-only
arguments.
@end quotation
@end cartouche
@end deffn

@geindex mock_add_spec() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock mock_add_spec}@anchor{3ffb}
@deffn {Méthode} mock_add_spec (spec, spec_set=False)

Ajoute une spécification à un simulacre. `spec' peut être un objet ou une liste de chaînes de caractères. Seuls les attributs de la spécification `spec' peuvent être récupérés en tant qu'attributs du simulacre.

Si `spec_set' est vrai, seuls les attributs de la spécification peuvent être définis.
@end deffn

@geindex attach_mock() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock attach_mock}@anchor{1597}
@deffn {Méthode} attach_mock (mock, attribute)

Attache un simulacre comme attribut de l'instance courante, en remplaçant son nom et son parent. Les appels au simulacre attaché sont enregistrés dans les attributs @ref{3ffc,,method_calls} et @ref{3ffa,,mock_calls} de l'instance courante.
@end deffn

@geindex configure_mock() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock configure_mock}@anchor{3ff7}
@deffn {Méthode} configure_mock (**kwargs)

Définir les attributs sur le simulacre à l'aide d'arguments nommés.

Les attributs, les valeurs de retour et les effets de bords peuvent être définis sur des simulacres enfants en utilisant la notation par points standard et en dépaquetant un dictionnaire dans l'appel de méthode :

@example
>>> mock = Mock()
>>> attrs = @{'method.return_value': 3, 'other.side_effect': KeyError@}
>>> mock.configure_mock(**attrs)
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError
@end example

La même chose peut être réalisée en utilisant le constructeur des simulacres :

@example
>>> attrs = @{'method.return_value': 3, 'other.side_effect': KeyError@}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError
@end example

@ref{3ff7,,configure_mock()} existe pour faciliter la configuration après la création du simulacre.
@end deffn

@geindex __dir__() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock __dir__}@anchor{3ffd}
@deffn {Méthode} __dir__ ()

Les objets @ref{a3a,,Mock} limitent les résultats de @code{dir(un_mock)} à des résultats utiles. Pour les simulacres avec une spécification `spec', cela inclut tous les attributs autorisés du simulacre.

Voir @ref{3ffe,,FILTER_DIR} pour savoir ce que fait ce filtrage, et comment le désactiver.
@end deffn

@geindex _get_child_mock() (méthode unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock _get_child_mock}@anchor{3fff}
@deffn {Méthode} _get_child_mock (**kw)

Crée les simulacres enfants pour les attributs et la valeur de retour. Par défaut, les objets simulacre enfants sont du même type que le parent. Les sous-classes de `Mock' peuvent surcharger cette méthode pour personnaliser la façon dont les simulacres enfants sont créés.

Pour les simulacres non appelables, la variante appelable est utilisée (plutôt qu'une sous-classe personnalisée).
@end deffn

@geindex called (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock called}@anchor{4000}
@deffn {Attribut} called

Un booléen représentant si le simulacre a bien été appelé ou non :

@example
>>> mock = Mock(return_value=None)
>>> mock.called
False
>>> mock()
>>> mock.called
True
@end example
@end deffn

@geindex call_count (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock call_count}@anchor{4001}
@deffn {Attribut} call_count

Un entier indiquant combien de fois le simulacre a été appelé :

@example
>>> mock = Mock(return_value=None)
>>> mock.call_count
0
>>> mock()
>>> mock()
>>> mock.call_count
2
@end example
@end deffn

@geindex return_value (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock return_value}@anchor{3ff6}
@deffn {Attribut} return_value

Définir cette option pour configurer la valeur renvoyé par appel du simulacre :

@example
>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'
@end example

La valeur de revoie par défaut est un simulacre configurable normalement :

@example
>>> mock = Mock()
>>> mock.return_value.attribute = sentinel.Attribute
>>> mock.return_value()
<Mock name='mock()()' id='...'>
>>> mock.return_value.assert_called_with()
@end example

L'attribut @ref{3ff6,,return_value} peut également être défini dans le constructeur :

@example
>>> mock = Mock(return_value=3)
>>> mock.return_value
3
>>> mock()
3
@end example
@end deffn

@geindex side_effect (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock side_effect}@anchor{3fee}
@deffn {Attribut} side_effect

C'est soit une fonction à appeler lors de l'appel du simulacre, soit une exception (classe ou instance) à lever.

Si vous passez une fonction, elle est appelée avec les mêmes arguments que la fonction simulée et à moins que la fonction ne renvoie le singleton @ref{3ff5,,DEFAULT} l'appel le la fonction simulée renvoie ce que la fonction renvoie. Si la fonction renvoie @ref{3ff5,,DEFAULT} alors le simulacre renvoie sa valeur normale (celle de @ref{3ff6,,return_value}).

Si vous passez un itérable, il est utilisé pour récupérer un itérateur qui doit renvoyer une valeur à chaque appel. Cette valeur peut être soit une instance d'exception à lever, soit une valeur à renvoyer à l'appel au simulacre (le traitement @ref{3ff5,,DEFAULT} est identique au renvoie de la fonction simulée).

Un exemple d'un simulacre qui lève une exception (pour tester la gestion des exceptions d'une API) :

@example
>>> mock = Mock()
>>> mock.side_effect = Exception('Boom!')
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!
@end example

Utiliser @ref{3fee,,side_effect} pour renvoyer une séquence de valeurs :

@example
>>> mock = Mock()
>>> mock.side_effect = [3, 2, 1]
>>> mock(), mock(), mock()
(3, 2, 1)
@end example

Utilisation d'un objet appelable :

@example
>>> mock = Mock(return_value=3)
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> mock.side_effect = side_effect
>>> mock()
3
@end example

Un attribut @ref{3fee,,side_effect} peut être défini dans le constructeur. Voici un exemple qui ajoute un à la valeur du simulacre appelé et qui le renvoie :

@example
>>> side_effect = lambda value: value + 1
>>> mock = Mock(side_effect=side_effect)
>>> mock(3)
4
>>> mock(-8)
-7
@end example

Positionner @ref{3fee,,side_effect} sur @code{None} l'efface :

@example
>>> m = Mock(side_effect=KeyError, return_value=3)
>>> m()
Traceback (most recent call last):
 ...
KeyError
>>> m.side_effect = None
>>> m()
3
@end example
@end deffn

@geindex call_args (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock call_args}@anchor{190e}
@deffn {Attribut} call_args

This is either @code{None} (if the mock hasn't been called), or the
arguments that the mock was last called with. This will be in the
form of a tuple: the first member, which can also be accessed through
the @code{args} property, is any ordered arguments the mock was
called with (or an empty tuple) and the second member, which can
also be accessed through the @code{kwargs} property, is any keyword
arguments (or an empty dictionary).

@example
>>> mock = Mock(return_value=None)
>>> print(mock.call_args)
None
>>> mock()
>>> mock.call_args
call()
>>> mock.call_args == ()
True
>>> mock(3, 4)
>>> mock.call_args
call(3, 4)
>>> mock.call_args == ((3, 4),)
True
>>> mock.call_args.args
(3, 4)
>>> mock.call_args.kwargs
@{@}
>>> mock(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args
call(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args.args
(3, 4, 5)
>>> mock.call_args.kwargs
@{'key': 'fish', 'next': 'w00t!'@}
@end example

L'attribut @ref{190e,,call_args}, ainsi que les éléments des listes @ref{4002,,call_args_list}, @ref{3ffc,,method_calls} et @ref{3ffa,,mock_calls} sont des objets @ref{195c,,call}. Ce sont des `n'-uplets, que l'on peut dépaqueter afin de faire des affirmations plus complexes sur chacun des arguments. Voir @ref{4003,,appels comme *n*-uplets}.


Modifié dans la version 3.8: Added @code{args} and @code{kwargs} properties.

@end deffn

@geindex call_args_list (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock call_args_list}@anchor{4002}
@deffn {Attribut} call_args_list

This is a list of all the calls made to the mock object in sequence
(so the length of the list is the number of times it has been
called). Before any calls have been made it is an empty list. The
@ref{195c,,call} object can be used for conveniently constructing lists of
calls to compare with @ref{4002,,call_args_list}.

@example
>>> mock = Mock(return_value=None)
>>> mock()
>>> mock(3, 4)
>>> mock(key='fish', next='w00t!')
>>> mock.call_args_list
[call(), call(3, 4), call(key='fish', next='w00t!')]
>>> expected = [(), ((3, 4),), (@{'key': 'fish', 'next': 'w00t!'@},)]
>>> mock.call_args_list == expected
True
@end example

Members of @ref{4002,,call_args_list} are @ref{195c,,call} objects. These can be
unpacked as tuples to get at the individual arguments. See
@ref{4003,,calls as tuples}.
@end deffn

@geindex method_calls (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock method_calls}@anchor{3ffc}
@deffn {Attribut} method_calls

As well as tracking calls to themselves, mocks also track calls to
methods and attributes, and `their' methods and attributes:

@example
>>> mock = Mock()
>>> mock.method()
<Mock name='mock.method()' id='...'>
>>> mock.property.method.attribute()
<Mock name='mock.property.method.attribute()' id='...'>
>>> mock.method_calls
[call.method(), call.property.method.attribute()]
@end example

Members of @ref{3ffc,,method_calls} are @ref{195c,,call} objects. These can be
unpacked as tuples to get at the individual arguments. See
@ref{4003,,calls as tuples}.
@end deffn

@geindex mock_calls (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock mock_calls}@anchor{3ffa}
@deffn {Attribut} mock_calls

@ref{3ffa,,mock_calls} records `all' calls to the mock object, its methods,
magic methods `and' return value mocks.

@example
>>> mock = MagicMock()
>>> result = mock(1, 2, 3)
>>> mock.first(a=3)
<MagicMock name='mock.first()' id='...'>
>>> mock.second()
<MagicMock name='mock.second()' id='...'>
>>> int(mock)
1
>>> result(1)
<MagicMock name='mock()()' id='...'>
>>> expected = [call(1, 2, 3), call.first(a=3), call.second(),
... call.__int__(), call()(1)]
>>> mock.mock_calls == expected
True
@end example

Members of @ref{3ffa,,mock_calls} are @ref{195c,,call} objects. These can be
unpacked as tuples to get at the individual arguments. See
@ref{4003,,calls as tuples}.

@cartouche
@quotation Note 
The way @ref{3ffa,,mock_calls} are recorded means that where nested
calls are made, the parameters of ancestor calls are not recorded
and so will always compare equal:

@example
>>> mock = MagicMock()
>>> mock.top(a=3).bottom()
<MagicMock name='mock.top().bottom()' id='...'>
>>> mock.mock_calls
[call.top(a=3), call.top().bottom()]
>>> mock.mock_calls[-1] == call.top(a=-1).bottom()
True
@end example
@end quotation
@end cartouche
@end deffn

@geindex __class__ (attribut unittest.mock.Mock)
@anchor{library/unittest mock unittest mock Mock __class__}@anchor{4004}
@deffn {Attribut} __class__

Normally the @code{__class__} attribute of an object will return its type.
For a mock object with a @code{spec}, @code{__class__} returns the spec class
instead. This allows mock objects to pass @ref{42b,,isinstance()} tests for the
object they are replacing / masquerading as:

@example
>>> mock = Mock(spec=3)
>>> isinstance(mock, int)
True
@end example

@code{__class__} is assignable to, this allows a mock to pass an
@ref{42b,,isinstance()} check without forcing you to use a spec:

@example
>>> mock = Mock()
>>> mock.__class__ = dict
>>> isinstance(mock, dict)
True
@end example
@end deffn
@end deffn

@geindex NonCallableMock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock NonCallableMock}@anchor{3ff3}
@deffn {Classe} unittest.mock.NonCallableMock (spec=None, wraps=None, name=None, spec_set=None, **kwargs)

A non-callable version of @ref{a3a,,Mock}. The constructor parameters have the same
meaning of @ref{a3a,,Mock}, with the exception of `return_value' and `side_effect'
which have no meaning on a non-callable mock.
@end deffn

Mock objects that use a class or an instance as a @code{spec} or
@code{spec_set} are able to pass @ref{42b,,isinstance()} tests:

@example
>>> mock = Mock(spec=SomeClass)
>>> isinstance(mock, SomeClass)
True
>>> mock = Mock(spec_set=SomeClass())
>>> isinstance(mock, SomeClass)
True
@end example

The @ref{a3a,,Mock} classes have support for mocking magic methods. See @ref{3ff0,,magic methods} for the full details.

The mock classes and the @ref{e7b,,patch()} decorators all take arbitrary keyword
arguments for configuration. For the @ref{e7b,,patch()} decorators the keywords are
passed to the constructor of the mock being created. The keyword arguments
are for configuring attributes of the mock:

@example
>>> m = MagicMock(attribute=3, other='fish')
>>> m.attribute
3
>>> m.other
'fish'
@end example

The return value and side effect of child mocks can be set in the same way,
using dotted notation. As you can't use dotted names directly in a call you
have to create a dictionary and unpack it using @code{**}:

@example
>>> attrs = @{'method.return_value': 3, 'other.side_effect': KeyError@}
>>> mock = Mock(some_attribute='eggs', **attrs)
>>> mock.some_attribute
'eggs'
>>> mock.method()
3
>>> mock.other()
Traceback (most recent call last):
  ...
KeyError
@end example

A callable mock which was created with a `spec' (or a `spec_set') will
introspect the specification object's signature when matching calls to
the mock.  Therefore, it can match the actual call's arguments regardless
of whether they were passed positionally or by name:

@example
>>> def f(a, b, c): pass
...
>>> mock = Mock(spec=f)
>>> mock(1, 2, c=3)
<Mock name='mock()' id='140161580456576'>
>>> mock.assert_called_with(1, 2, 3)
>>> mock.assert_called_with(a=1, b=2, c=3)
@end example

This applies to @ref{19af,,assert_called_with()},
@ref{3ff8,,assert_called_once_with()}, @ref{1631,,assert_has_calls()} and
@ref{3ff9,,assert_any_call()}.  When @ref{3ff1,,Autospeccing}, it will also
apply to method calls on the mock object.


Modifié dans la version 3.4: Added signature introspection on specced and autospecced mock objects.


@geindex PropertyMock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock PropertyMock}@anchor{4005}
@deffn {Classe} unittest.mock.PropertyMock (*args, **kwargs)

A mock intended to be used as a @ref{192,,property}, or other
@ref{1ef3,,descriptor}, on a class. @ref{4005,,PropertyMock} provides
@ref{149d,,__get__()} and @ref{1eec,,__set__()} methods
so you can specify a return value when it is fetched.

Fetching a @ref{4005,,PropertyMock} instance from an object calls the mock, with
no args. Setting it calls the mock with the value being set.

@example
>>> class Foo:
...     @@property
...     def foo(self):
...         return 'something'
...     @@foo.setter
...     def foo(self, value):
...         pass
...
>>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo:
...     mock_foo.return_value = 'mockity-mock'
...     this_foo = Foo()
...     print(this_foo.foo)
...     this_foo.foo = 6
...
mockity-mock
>>> mock_foo.mock_calls
[call(), call(6)]
@end example
@end deffn

Because of the way mock attributes are stored you can't directly attach a
@ref{4005,,PropertyMock} to a mock object. Instead you can attach it to the mock type
object:

@example
>>> m = MagicMock()
>>> p = PropertyMock(return_value=3)
>>> type(m).foo = p
>>> m.foo
3
>>> p.assert_called_once_with()
@end example

@cartouche
@quotation Prudence 
If an @ref{343,,AttributeError} is raised by @ref{4005,,PropertyMock},
it will be interpreted as a missing descriptor and
@ref{4bc,,__getattr__()} will be called on the parent mock:

@example
>>> m = MagicMock()
>>> no_attribute = PropertyMock(side_effect=AttributeError)
>>> type(m).my_property = no_attribute
>>> m.my_property
<MagicMock name='mock.my_property' id='140165240345424'>
@end example

See @ref{4bc,,__getattr__()} for details.
@end quotation
@end cartouche

@geindex AsyncMock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock AsyncMock}@anchor{a39}
@deffn {Classe} unittest.mock.AsyncMock (spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)

An asynchronous version of @ref{e7a,,MagicMock}. The @ref{a39,,AsyncMock} object will
behave so the object is recognized as an async function, and the result of a
call is an awaitable.

@example
>>> mock = AsyncMock()
>>> asyncio.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())  
True
@end example

The result of @code{mock()} is an async function which will have the outcome
of @code{side_effect} or @code{return_value} after it has been awaited:


@itemize -

@item 
if @code{side_effect} is a function, the async function will return the
result of that function,

@item 
if @code{side_effect} is an exception, the async function will raise the
exception,

@item 
if @code{side_effect} is an iterable, the async function will return the
next value of the iterable, however, if the sequence of result is
exhausted, @code{StopAsyncIteration} is raised immediately,

@item 
if @code{side_effect} is not defined, the async function will return the
value defined by @code{return_value}, hence, by default, the async function
returns a new @ref{a39,,AsyncMock} object.
@end itemize

Setting the `spec' of a @ref{a3a,,Mock} or @ref{e7a,,MagicMock} to an async function
will result in a coroutine object being returned after calling.

@example
>>> async def async_func(): pass
...
>>> mock = MagicMock(async_func)
>>> mock
<MagicMock spec='function' id='...'>
>>> mock()  
<coroutine object AsyncMockMixin._mock_call at ...>
@end example

Setting the `spec' of a @ref{a3a,,Mock}, @ref{e7a,,MagicMock}, or @ref{a39,,AsyncMock}
to a class with asynchronous and synchronous functions will automatically
detect the synchronous functions and set them as @ref{e7a,,MagicMock} (if the
parent mock is @ref{a39,,AsyncMock} or @ref{e7a,,MagicMock}) or @ref{a3a,,Mock} (if
the parent mock is @ref{a3a,,Mock}). All asynchronous functions will be
@ref{a39,,AsyncMock}.

@example
>>> class ExampleClass:
...     def sync_foo():
...         pass
...     async def async_foo():
...         pass
...
>>> a_mock = AsyncMock(ExampleClass)
>>> a_mock.sync_foo
<MagicMock name='mock.sync_foo' id='...'>
>>> a_mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>
>>> mock = Mock(ExampleClass)
>>> mock.sync_foo
<Mock name='mock.sync_foo' id='...'>
>>> mock.async_foo
<AsyncMock name='mock.async_foo' id='...'>
@end example


Ajouté dans la version 3.8.


@geindex assert_awaited() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited}@anchor{4006}
@deffn {Méthode} assert_awaited ()

Assert that the mock was awaited at least once. Note that this is separate
from the object having been called, the @code{await} keyword must be used:

@example
>>> mock = AsyncMock()
>>> async def main(coroutine_mock):
...     await coroutine_mock
...
>>> coroutine_mock = mock()
>>> mock.called
True
>>> mock.assert_awaited()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited.
>>> asyncio.run(main(coroutine_mock))
>>> mock.assert_awaited()
@end example
@end deffn

@geindex assert_awaited_once() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited_once}@anchor{4007}
@deffn {Méthode} assert_awaited_once ()

Assert that the mock was awaited exactly once.

@example
>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.assert_awaited_once()
>>> asyncio.run(main())
>>> mock.assert_awaited_once()
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.
@end example
@end deffn

@geindex assert_awaited_with() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited_with}@anchor{4008}
@deffn {Méthode} assert_awaited_with (*args, **kwargs)

Assert that the last await was with the specified arguments.

@example
>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_with('foo', bar='bar')
>>> mock.assert_awaited_with('other')
Traceback (most recent call last):
...
AssertionError: expected await not found.
Expected: mock('other')
Actual: mock('foo', bar='bar')
@end example
@end deffn

@geindex assert_awaited_once_with() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_awaited_once_with}@anchor{4009}
@deffn {Méthode} assert_awaited_once_with (*args, **kwargs)

Assert that the mock was awaited exactly once and with the specified
arguments.

@example
>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_once_with('foo', bar='bar')
>>> asyncio.run(main('foo', bar='bar'))
>>> mock.assert_awaited_once_with('foo', bar='bar')
Traceback (most recent call last):
...
AssertionError: Expected mock to have been awaited once. Awaited 2 times.
@end example
@end deffn

@geindex assert_any_await() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_any_await}@anchor{400a}
@deffn {Méthode} assert_any_await (*args, **kwargs)

Assert the mock has ever been awaited with the specified arguments.

@example
>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> asyncio.run(main('foo', bar='bar'))
>>> asyncio.run(main('hello'))
>>> mock.assert_any_await('foo', bar='bar')
>>> mock.assert_any_await('other')
Traceback (most recent call last):
...
AssertionError: mock('other') await not found
@end example
@end deffn

@geindex assert_has_awaits() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_has_awaits}@anchor{400b}
@deffn {Méthode} assert_has_awaits (calls, any_order=False)

Assert the mock has been awaited with the specified calls.
The @ref{190d,,await_args_list} list is checked for the awaits.

If `any_order' is false then the awaits must be
sequential. There can be extra calls before or after the
specified awaits.

If `any_order' is true then the awaits can be in any order, but
they must all appear in @ref{190d,,await_args_list}.

@example
>>> mock = AsyncMock()
>>> async def main(*args, **kwargs):
...     await mock(*args, **kwargs)
...
>>> calls = [call("foo"), call("bar")]
>>> mock.assert_has_awaits(calls)
Traceback (most recent call last):
...
AssertionError: Awaits not found.
Expected: [call('foo'), call('bar')]
Actual: []
>>> asyncio.run(main('foo'))
>>> asyncio.run(main('bar'))
>>> mock.assert_has_awaits(calls)
@end example
@end deffn

@geindex assert_not_awaited() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock assert_not_awaited}@anchor{400c}
@deffn {Méthode} assert_not_awaited ()

Assert that the mock was never awaited.

@example
>>> mock = AsyncMock()
>>> mock.assert_not_awaited()
@end example
@end deffn

@geindex reset_mock() (méthode unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock reset_mock}@anchor{400d}
@deffn {Méthode} reset_mock (*args, **kwargs)

See @ref{ce8,,Mock.reset_mock()}. Also sets @ref{400e,,await_count} to 0,
@ref{400f,,await_args} to None, and clears the @ref{190d,,await_args_list}.
@end deffn

@geindex await_count (attribut unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock await_count}@anchor{400e}
@deffn {Attribut} await_count

An integer keeping track of how many times the mock object has been awaited.

@example
>>> mock = AsyncMock()
>>> async def main():
...     await mock()
...
>>> asyncio.run(main())
>>> mock.await_count
1
>>> asyncio.run(main())
>>> mock.await_count
2
@end example
@end deffn

@geindex await_args (attribut unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock await_args}@anchor{400f}
@deffn {Attribut} await_args

This is either @code{None} (if the mock hasn’t been awaited), or the arguments that
the mock was last awaited with. Functions the same as @ref{190e,,Mock.call_args}.

@example
>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args
>>> asyncio.run(main('foo'))
>>> mock.await_args
call('foo')
>>> asyncio.run(main('bar'))
>>> mock.await_args
call('bar')
@end example
@end deffn

@geindex await_args_list (attribut unittest.mock.AsyncMock)
@anchor{library/unittest mock unittest mock AsyncMock await_args_list}@anchor{190d}
@deffn {Attribut} await_args_list

This is a list of all the awaits made to the mock object in sequence (so the
length of the list is the number of times it has been awaited). Before any
awaits have been made it is an empty list.

@example
>>> mock = AsyncMock()
>>> async def main(*args):
...     await mock(*args)
...
>>> mock.await_args_list
[]
>>> asyncio.run(main('foo'))
>>> mock.await_args_list
[call('foo')]
>>> asyncio.run(main('bar'))
>>> mock.await_args_list
[call('foo'), call('bar')]
@end example
@end deffn
@end deffn

@geindex ThreadingMock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock ThreadingMock}@anchor{4010}
@deffn {Classe} unittest.mock.ThreadingMock (spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, *, timeout=UNSET, **kwargs)

A version of @ref{e7a,,MagicMock} for multithreading tests. The
@ref{4010,,ThreadingMock} object provides extra methods to wait for a call to
be invoked, rather than assert on it immediately.

The default timeout is specified by the @code{timeout} argument, or if unset by the
@ref{4011,,ThreadingMock.DEFAULT_TIMEOUT} attribute, which defaults to blocking (@code{None}).

You can configure the global default timeout by setting @ref{4011,,ThreadingMock.DEFAULT_TIMEOUT}.

@geindex wait_until_called() (méthode unittest.mock.ThreadingMock)
@anchor{library/unittest mock unittest mock ThreadingMock wait_until_called}@anchor{4012}
@deffn {Méthode} wait_until_called (*, timeout=UNSET)

Waits until the mock is called.

If a timeout was passed at the creation of the mock or if a timeout
argument is passed to this function, the function raises an
@ref{694,,AssertionError} if the call is not performed in time.

@example
>>> mock = ThreadingMock()
>>> thread = threading.Thread(target=mock)
>>> thread.start()
>>> mock.wait_until_called(timeout=1)
>>> thread.join()
@end example
@end deffn

@geindex wait_until_any_call_with() (méthode unittest.mock.ThreadingMock)
@anchor{library/unittest mock unittest mock ThreadingMock wait_until_any_call_with}@anchor{4013}
@deffn {Méthode} wait_until_any_call_with (*args, **kwargs)

Waits until the mock is called with the specified arguments.

If a timeout was passed at the creation of the mock
the function raises an @ref{694,,AssertionError} if the call is not performed in time.

@example
>>> mock = ThreadingMock()
>>> thread = threading.Thread(target=mock, args=("arg1", "arg2",), kwargs=@{"arg": "thing"@})
>>> thread.start()
>>> mock.wait_until_any_call_with("arg1", "arg2", arg="thing")
>>> thread.join()
@end example
@end deffn

@geindex DEFAULT_TIMEOUT (attribut unittest.mock.ThreadingMock)
@anchor{library/unittest mock unittest mock ThreadingMock DEFAULT_TIMEOUT}@anchor{4011}
@deffn {Attribut} DEFAULT_TIMEOUT

Global default timeout in seconds to create instances of @ref{4010,,ThreadingMock}.
@end deffn


Ajouté dans la version 3.13.

@end deffn

@menu
* Calling:: 
* Deleting Attributes:: 
* Mock names and the name attribute:: 
* Attaching Mocks as Attributes:: 

@end menu

@node Calling,Deleting Attributes,,La classe Mock
@anchor{library/unittest mock calling}@anchor{4014}
@subsubsection Calling


Mock objects are callable. The call will return the value set as the
@ref{3ff6,,return_value} attribute. The default return value is a new Mock
object; it is created the first time the return value is accessed (either
explicitly or by calling the Mock) - but it is stored and the same one
returned each time.

Calls made to the object will be recorded in the attributes
like @ref{190e,,call_args} and @ref{4002,,call_args_list}.

If @ref{3fee,,side_effect} is set then it will be called after the call has
been recorded, so if @code{side_effect} raises an exception the call is still
recorded.

The simplest way to make a mock raise an exception when called is to make
@ref{3fee,,side_effect} an exception class or instance:

@example
>>> m = MagicMock(side_effect=IndexError)
>>> m(1, 2, 3)
Traceback (most recent call last):
  ...
IndexError
>>> m.mock_calls
[call(1, 2, 3)]
>>> m.side_effect = KeyError('Bang!')
>>> m('two', 'three', 'four')
Traceback (most recent call last):
  ...
KeyError: 'Bang!'
>>> m.mock_calls
[call(1, 2, 3), call('two', 'three', 'four')]
@end example

If @ref{3fee,,side_effect} is a function then whatever that function returns is what
calls to the mock return. The @code{side_effect} function is called with the
same arguments as the mock. This allows you to vary the return value of the
call dynamically, based on the input:

@example
>>> def side_effect(value):
...     return value + 1
...
>>> m = MagicMock(side_effect=side_effect)
>>> m(1)
2
>>> m(2)
3
>>> m.mock_calls
[call(1), call(2)]
@end example

If you want the mock to still return the default return value (a new mock), or
any set return value, then there are two ways of doing this. Either return
@ref{3ff6,,return_value} from inside @ref{3fee,,side_effect}, or return @ref{3ff5,,DEFAULT}:

@example
>>> m = MagicMock()
>>> def side_effect(*args, **kwargs):
...     return m.return_value
...
>>> m.side_effect = side_effect
>>> m.return_value = 3
>>> m()
3
>>> def side_effect(*args, **kwargs):
...     return DEFAULT
...
>>> m.side_effect = side_effect
>>> m()
3
@end example

To remove a @ref{3fee,,side_effect}, and return to the default behaviour, set the
@code{side_effect} to @code{None}:

@example
>>> m = MagicMock(return_value=6)
>>> def side_effect(*args, **kwargs):
...     return 3
...
>>> m.side_effect = side_effect
>>> m()
3
>>> m.side_effect = None
>>> m()
6
@end example

The @ref{3fee,,side_effect} can also be any iterable object. Repeated calls to the mock
will return values from the iterable (until the iterable is exhausted and
a @ref{be8,,StopIteration} is raised):

@example
>>> m = MagicMock(side_effect=[1, 2, 3])
>>> m()
1
>>> m()
2
>>> m()
3
>>> m()
Traceback (most recent call last):
  ...
StopIteration
@end example

If any members of the iterable are exceptions they will be raised instead of
returned:

@example
>>> iterable = (33, ValueError, 66)
>>> m = MagicMock(side_effect=iterable)
>>> m()
33
>>> m()
Traceback (most recent call last):
 ...
ValueError
>>> m()
66
@end example

@node Deleting Attributes,Mock names and the name attribute,Calling,La classe Mock
@anchor{library/unittest mock deleting-attributes}@anchor{4015}@anchor{library/unittest mock id2}@anchor{4016}
@subsubsection Deleting Attributes


Mock objects create attributes on demand. This allows them to pretend to be
objects of any type.

You may want a mock object to return @code{False} to a @ref{4bb,,hasattr()} call, or raise an
@ref{343,,AttributeError} when an attribute is fetched. You can do this by providing
an object as a @code{spec} for a mock, but that isn't always convenient.

You "block" attributes by deleting them. Once deleted, accessing an attribute
will raise an @ref{343,,AttributeError}.

@example
>>> mock = MagicMock()
>>> hasattr(mock, 'm')
True
>>> del mock.m
>>> hasattr(mock, 'm')
False
>>> del mock.f
>>> mock.f
Traceback (most recent call last):
    ...
AttributeError: f
@end example

@node Mock names and the name attribute,Attaching Mocks as Attributes,Deleting Attributes,La classe Mock
@anchor{library/unittest mock mock-names-and-the-name-attribute}@anchor{4017}
@subsubsection Mock names and the name attribute


Since "name" is an argument to the @ref{a3a,,Mock} constructor, if you want your
mock object to have a "name" attribute you can't just pass it in at creation
time. There are two alternatives. One option is to use
@ref{3ff7,,configure_mock()}:

@example
>>> mock = MagicMock()
>>> mock.configure_mock(name='my_name')
>>> mock.name
'my_name'
@end example

A simpler option is to simply set the "name" attribute after mock creation:

@example
>>> mock = MagicMock()
>>> mock.name = "foo"
@end example

@node Attaching Mocks as Attributes,,Mock names and the name attribute,La classe Mock
@anchor{library/unittest mock attaching-mocks-as-attributes}@anchor{4018}
@subsubsection Attaching Mocks as Attributes


When you attach a mock as an attribute of another mock (or as the return
value) it becomes a "child" of that mock. Calls to the child are recorded in
the @ref{3ffc,,method_calls} and @ref{3ffa,,mock_calls} attributes of the
parent. This is useful for configuring child mocks and then attaching them to
the parent, or for attaching mocks to a parent that records all calls to the
children and allows you to make assertions about the order of calls between
mocks:

@example
>>> parent = MagicMock()
>>> child1 = MagicMock(return_value=None)
>>> child2 = MagicMock(return_value=None)
>>> parent.child1 = child1
>>> parent.child2 = child2
>>> child1(1)
>>> child2(2)
>>> parent.mock_calls
[call.child1(1), call.child2(2)]
@end example

The exception to this is if the mock has a name. This allows you to prevent
the "parenting" if for some reason you don't want it to happen.

@example
>>> mock = MagicMock()
>>> not_a_child = MagicMock(name='not-a-child')
>>> mock.attribute = not_a_child
>>> mock.attribute()
<MagicMock name='not-a-child()' id='...'>
>>> mock.mock_calls
[]
@end example

Mocks created for you by @ref{e7b,,patch()} are automatically given names. To
attach mocks that have names to a parent you use the @ref{1597,,attach_mock()}
method:

@example
>>> thing1 = object()
>>> thing2 = object()
>>> parent = MagicMock()
>>> with patch('__main__.thing1', return_value=None) as child1:
...     with patch('__main__.thing2', return_value=None) as child2:
...         parent.attach_mock(child1, 'child1')
...         parent.attach_mock(child2, 'child2')
...         child1('one')
...         child2('two')
...
>>> parent.mock_calls
[call.child1('one'), call.child2('two')]
@end example

@node The patchers,MagicMock and magic method support,La classe Mock,unittest mock --- mock object library
@anchor{library/unittest mock the-patchers}@anchor{4019}
@subsubsection The patchers


The patch decorators are used for patching objects only within the scope of
the function they decorate. They automatically handle the unpatching for you,
even if exceptions are raised. All of these functions can also be used in with
statements or as class decorators.

@menu
* patch:: 
* patch.object: patch object. 
* patch.dict: patch dict. 
* patch.multiple: patch multiple. 
* patch methods; start and stop: patch methods start and stop. 
* patch builtins:: 
* TEST_PREFIX:: 
* Nesting Patch Decorators:: 
* Where to patch:: 
* Patching Descriptors and Proxy Objects:: 

@end menu

@node patch,patch object,,The patchers
@anchor{library/unittest mock patch}@anchor{401a}
@subsubsection patch


@cartouche
@quotation Note 
The key is to do the patching in the right namespace. See the section @ref{401b,,where to patch}.
@end quotation
@end cartouche

@geindex patch() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock patch}@anchor{e7b}
@deffn {Fonction} unittest.mock.patch (target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

@ref{e7b,,patch()} acts as a function decorator, class decorator or a context
manager. Inside the body of the function or with statement, the `target'
is patched with a `new' object. When the function/with statement exits
the patch is undone.

If `new' is omitted, then the target is replaced with an
@ref{a39,,AsyncMock} if the patched object is an async function or
a @ref{e7a,,MagicMock} otherwise.
If @ref{e7b,,patch()} is used as a decorator and `new' is
omitted, the created mock is passed in as an extra argument to the
decorated function. If @ref{e7b,,patch()} is used as a context manager the created
mock is returned by the context manager.

`target' should be a string in the form @code{'package.module.ClassName'}. The
`target' is imported and the specified object replaced with the `new'
object, so the `target' must be importable from the environment you are
calling @ref{e7b,,patch()} from. The target is imported when the decorated function
is executed, not at decoration time.

The `spec' and `spec_set' keyword arguments are passed to the @ref{e7a,,MagicMock}
if patch is creating one for you.

In addition you can pass @code{spec=True} or @code{spec_set=True}, which causes
patch to pass in the object being mocked as the spec/spec_set object.

`new_callable' allows you to specify a different class, or callable object,
that will be called to create the `new' object. By default @ref{a39,,AsyncMock}
is used for async functions and @ref{e7a,,MagicMock} for the rest.

A more powerful form of `spec' is `autospec'. If you set @code{autospec=True}
then the mock will be created with a spec from the object being replaced.
All attributes of the mock will also have the spec of the corresponding
attribute of the object being replaced. Methods and functions being mocked
will have their arguments checked and will raise a @ref{522,,TypeError} if they are
called with the wrong signature. For mocks
replacing a class, their return value (the 'instance') will have the same
spec as the class. See the @ref{1590,,create_autospec()} function and
@ref{3ff1,,Autospeccing}.

Instead of @code{autospec=True} you can pass @code{autospec=some_object} to use an
arbitrary object as the spec instead of the one being replaced.

By default @ref{e7b,,patch()} will fail to replace attributes that don't exist.
If you pass in @code{create=True}, and the attribute doesn't exist, patch will
create the attribute for you when the patched function is called, and delete
it again after the patched function has exited. This is useful for writing
tests against attributes that your production code creates at runtime. It is
off by default because it can be dangerous. With it switched on you can
write passing tests against APIs that don't actually exist!

@cartouche
@quotation Note 

Modifié dans la version 3.5: If you are patching builtins in a module then you don't
need to pass @code{create=True}, it will be added by default.

@end quotation
@end cartouche

Patch can be used as a @ref{437,,TestCase} class decorator. It works by
decorating each test method in the class. This reduces the boilerplate
code when your test methods share a common patchings set. @ref{e7b,,patch()} finds
tests by looking for method names that start with @code{patch.TEST_PREFIX}.
By default this is @code{'test'}, which matches the way @ref{105,,unittest} finds tests.
You can specify an alternative prefix by setting @code{patch.TEST_PREFIX}.

Patch can be used as a context manager, with the with statement. Here the
patching applies to the indented block after the with statement. If you
use "as" then the patched object will be bound to the name after the
"as"; very useful if @ref{e7b,,patch()} is creating a mock object for you.

@ref{e7b,,patch()} takes arbitrary keyword arguments. These will be passed to
@ref{a39,,AsyncMock} if the patched object is asynchronous, to
@ref{e7a,,MagicMock} otherwise or to `new_callable' if specified.

@code{patch.dict(...)}, @code{patch.multiple(...)} and @code{patch.object(...)} are
available for alternate use-cases.
@end deffn

@ref{e7b,,patch()} as function decorator, creating the mock for you and passing it into
the decorated function:

@example
>>> @@patch('__main__.SomeClass')
... def function(normal_argument, mock_class):
...     print(mock_class is SomeClass)
...
>>> function(None)
True
@end example

Patching a class replaces the class with a @ref{e7a,,MagicMock} `instance'. If the
class is instantiated in the code under test then it will be the
@ref{3ff6,,return_value} of the mock that will be used.

If the class is instantiated multiple times you could use
@ref{3fee,,side_effect} to return a new mock each time. Alternatively you
can set the `return_value' to be anything you want.

To configure return values on methods of `instances' on the patched class
you must do this on the @ref{3ff6,,return_value}. For example:

@example
>>> class Class:
...     def method(self):
...         pass
...
>>> with patch('__main__.Class') as MockClass:
...     instance = MockClass.return_value
...     instance.method.return_value = 'foo'
...     assert Class() is instance
...     assert Class().method() == 'foo'
...
@end example

If you use `spec' or `spec_set' and @ref{e7b,,patch()} is replacing a `class', then the
return value of the created mock will have the same spec.

@example
>>> Original = Class
>>> patcher = patch('__main__.Class', spec=True)
>>> MockClass = patcher.start()
>>> instance = MockClass()
>>> assert isinstance(instance, Original)
>>> patcher.stop()
@end example

The `new_callable' argument is useful where you want to use an alternative
class to the default @ref{e7a,,MagicMock} for the created mock. For example, if
you wanted a @ref{3ff3,,NonCallableMock} to be used:

@example
>>> thing = object()
>>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing:
...     assert thing is mock_thing
...     thing()
...
Traceback (most recent call last):
  ...
TypeError: 'NonCallableMock' object is not callable
@end example

Another use case might be to replace an object with an @ref{f12,,io.StringIO} instance:

@example
>>> from io import StringIO
>>> def foo():
...     print('Something')
...
>>> @@patch('sys.stdout', new_callable=StringIO)
... def test(mock_stdout):
...     foo()
...     assert mock_stdout.getvalue() == 'Something\n'
...
>>> test()
@end example

When @ref{e7b,,patch()} is creating a mock for you, it is common that the first thing
you need to do is to configure the mock. Some of that configuration can be done
in the call to patch. Any arbitrary keywords you pass into the call will be
used to set attributes on the created mock:

@example
>>> patcher = patch('__main__.thing', first='one', second='two')
>>> mock_thing = patcher.start()
>>> mock_thing.first
'one'
>>> mock_thing.second
'two'
@end example

As well as attributes on the created mock attributes, like the
@ref{3ff6,,return_value} and @ref{3fee,,side_effect}, of child mocks can
also be configured. These aren't syntactically valid to pass in directly as
keyword arguments, but a dictionary with these as keys can still be expanded
into a @ref{e7b,,patch()} call using @code{**}:

@example
>>> config = @{'method.return_value': 3, 'other.side_effect': KeyError@}
>>> patcher = patch('__main__.thing', **config)
>>> mock_thing = patcher.start()
>>> mock_thing.method()
3
>>> mock_thing.other()
Traceback (most recent call last):
  ...
KeyError
@end example

By default, attempting to patch a function in a module (or a method or an
attribute in a class) that does not exist will fail with @ref{343,,AttributeError}:

@example
>>> @@patch('sys.non_existing_attribute', 42)
... def test():
...     assert sys.non_existing_attribute == 42
...
>>> test()
Traceback (most recent call last):
  ...
AttributeError: <module 'sys' (built-in)> does not have the attribute 'non_existing_attribute'
@end example

but adding @code{create=True} in the call to @ref{e7b,,patch()} will make the previous example
work as expected:

@example
>>> @@patch('sys.non_existing_attribute', 42, create=True)
... def test(mock_stdout):
...     assert sys.non_existing_attribute == 42
...
>>> test()
@end example


Modifié dans la version 3.8: @ref{e7b,,patch()} now returns an @ref{a39,,AsyncMock} if the target is an async function.


@node patch object,patch dict,patch,The patchers
@anchor{library/unittest mock patch-object}@anchor{401c}
@subsubsection patch.object


@geindex patch.object() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock patch object}@anchor{151e}
@deffn {Fonction} patch.object (target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

patch the named member (`attribute') on an object (`target') with a mock
object.

@ref{151e,,patch.object()} can be used as a decorator, class decorator or a context
manager. Arguments `new', `spec', `create', `spec_set', `autospec' and
`new_callable' have the same meaning as for @ref{e7b,,patch()}. Like @ref{e7b,,patch()},
@ref{151e,,patch.object()} takes arbitrary keyword arguments for configuring the mock
object it creates.

When used as a class decorator @ref{151e,,patch.object()} honours @code{patch.TEST_PREFIX}
for choosing which methods to wrap.
@end deffn

You can either call @ref{151e,,patch.object()} with three arguments or two arguments. The
three argument form takes the object to be patched, the attribute name and the
object to replace the attribute with.

When calling with the two argument form you omit the replacement object, and a
mock is created for you and passed in as an extra argument to the decorated
function:

@example
>>> @@patch.object(SomeClass, 'class_method')
... def test(mock_method):
...     SomeClass.class_method(3)
...     mock_method.assert_called_with(3)
...
>>> test()
@end example

`spec', `create' and the other arguments to @ref{151e,,patch.object()} have the same
meaning as they do for @ref{e7b,,patch()}.

@node patch dict,patch multiple,patch object,The patchers
@anchor{library/unittest mock patch-dict}@anchor{401d}
@subsubsection patch.dict


@geindex patch.dict() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock patch dict}@anchor{1981}
@deffn {Fonction} patch.dict (in_dict, values=(), clear=False, **kwargs)

Patch a dictionary, or dictionary like object, and restore the dictionary
to its original state after the test.

`in_dict' can be a dictionary or a mapping like container. If it is a
mapping then it must at least support getting, setting and deleting items
plus iterating over keys.

`in_dict' can also be a string specifying the name of the dictionary, which
will then be fetched by importing it.

`values' can be a dictionary of values to set in the dictionary. `values'
can also be an iterable of @code{(key, value)} pairs.

If `clear' is true then the dictionary will be cleared before the new
values are set.

@ref{1981,,patch.dict()} can also be called with arbitrary keyword arguments to set
values in the dictionary.


Modifié dans la version 3.8: @ref{1981,,patch.dict()} now returns the patched dictionary when used as a context
manager.

@end deffn

@ref{1981,,patch.dict()} can be used as a context manager, decorator or class
decorator:

@example
>>> foo = @{@}
>>> @@patch.dict(foo, @{'newkey': 'newvalue'@})
... def test():
...     assert foo == @{'newkey': 'newvalue'@}
...
>>> test()
>>> assert foo == @{@}
@end example

When used as a class decorator @ref{1981,,patch.dict()} honours
@code{patch.TEST_PREFIX} (default to @code{'test'}) for choosing which methods to wrap:

@example
>>> import os
>>> import unittest
>>> from unittest.mock import patch
>>> @@patch.dict('os.environ', @{'newkey': 'newvalue'@})
... class TestSample(unittest.TestCase):
...     def test_sample(self):
...         self.assertEqual(os.environ['newkey'], 'newvalue')
@end example

If you want to use a different prefix for your test, you can inform the
patchers of the different prefix by setting @code{patch.TEST_PREFIX}. For
more details about how to change the value of see @ref{401e,,TEST_PREFIX}.

@ref{1981,,patch.dict()} can be used to add members to a dictionary, or simply let a test
change a dictionary, and ensure the dictionary is restored when the test
ends.

@example
>>> foo = @{@}
>>> with patch.dict(foo, @{'newkey': 'newvalue'@}) as patched_foo:
...     assert foo == @{'newkey': 'newvalue'@}
...     assert patched_foo == @{'newkey': 'newvalue'@}
...     # You can add, update or delete keys of foo (or patched_foo, it's the same dict)
...     patched_foo['spam'] = 'eggs'
...
>>> assert foo == @{@}
>>> assert patched_foo == @{@}
@end example

@example
>>> import os
>>> with patch.dict('os.environ', @{'newkey': 'newvalue'@}):
...     print(os.environ['newkey'])
...
newvalue
>>> assert 'newkey' not in os.environ
@end example

Keywords can be used in the @ref{1981,,patch.dict()} call to set values in the dictionary:

@example
>>> mymodule = MagicMock()
>>> mymodule.function.return_value = 'fish'
>>> with patch.dict('sys.modules', mymodule=mymodule):
...     import mymodule
...     mymodule.function('some', 'args')
...
'fish'
@end example

@ref{1981,,patch.dict()} can be used with dictionary like objects that aren't actually
dictionaries. At the very minimum they must support item getting, setting,
deleting and either iteration or membership test. This corresponds to the
magic methods @ref{280,,__getitem__()}, @ref{12a9,,__setitem__()},
@ref{12aa,,__delitem__()} and either @ref{1c4e,,__iter__()} or
@ref{1ee0,,__contains__()}.

@example
>>> class Container:
...     def __init__(self):
...         self.values = @{@}
...     def __getitem__(self, name):
...         return self.values[name]
...     def __setitem__(self, name, value):
...         self.values[name] = value
...     def __delitem__(self, name):
...         del self.values[name]
...     def __iter__(self):
...         return iter(self.values)
...
>>> thing = Container()
>>> thing['one'] = 1
>>> with patch.dict(thing, one=2, two=3):
...     assert thing['one'] == 2
...     assert thing['two'] == 3
...
>>> assert thing['one'] == 1
>>> assert list(thing) == ['one']
@end example

@node patch multiple,patch methods start and stop,patch dict,The patchers
@anchor{library/unittest mock patch-multiple}@anchor{401f}
@subsubsection patch.multiple


@geindex patch.multiple() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock patch multiple}@anchor{4020}
@deffn {Fonction} patch.multiple (target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs)

Perform multiple patches in a single call. It takes the object to be
patched (either as an object or a string to fetch the object by importing)
and keyword arguments for the patches:

@example
with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
    ...
@end example

Use @ref{3ff5,,DEFAULT} as the value if you want @ref{4020,,patch.multiple()} to create
mocks for you. In this case the created mocks are passed into a decorated
function by keyword, and a dictionary is returned when @ref{4020,,patch.multiple()} is
used as a context manager.

@ref{4020,,patch.multiple()} can be used as a decorator, class decorator or a context
manager. The arguments `spec', `spec_set', `create', `autospec' and
`new_callable' have the same meaning as for @ref{e7b,,patch()}. These arguments will
be applied to `all' patches done by @ref{4020,,patch.multiple()}.

When used as a class decorator @ref{4020,,patch.multiple()} honours @code{patch.TEST_PREFIX}
for choosing which methods to wrap.
@end deffn

If you want @ref{4020,,patch.multiple()} to create mocks for you, then you can use
@ref{3ff5,,DEFAULT} as the value. If you use @ref{4020,,patch.multiple()} as a decorator
then the created mocks are passed into the decorated function by keyword.

@example
>>> thing = object()
>>> other = object()

>>> @@patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(thing, other):
...     assert isinstance(thing, MagicMock)
...     assert isinstance(other, MagicMock)
...
>>> test_function()
@end example

@ref{4020,,patch.multiple()} can be nested with other @code{patch} decorators, but put arguments
passed by keyword `after' any of the standard arguments created by @ref{e7b,,patch()}:

@example
>>> @@patch('sys.exit')
... @@patch.multiple('__main__', thing=DEFAULT, other=DEFAULT)
... def test_function(mock_exit, other, thing):
...     assert 'other' in repr(other)
...     assert 'thing' in repr(thing)
...     assert 'exit' in repr(mock_exit)
...
>>> test_function()
@end example

If @ref{4020,,patch.multiple()} is used as a context manager, the value returned by the
context manager is a dictionary where created mocks are keyed by name:

@example
>>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values:
...     assert 'other' in repr(values['other'])
...     assert 'thing' in repr(values['thing'])
...     assert values['thing'] is thing
...     assert values['other'] is other
...
@end example

@node patch methods start and stop,patch builtins,patch multiple,The patchers
@anchor{library/unittest mock patch-methods-start-and-stop}@anchor{4021}@anchor{library/unittest mock start-and-stop}@anchor{4022}
@subsubsection patch methods: start and stop


All the patchers have @code{start()} and @code{stop()} methods. These make it simpler to do
patching in @code{setUp} methods or where you want to do multiple patches without
nesting decorators or with statements.

To use them call @ref{e7b,,patch()}, @ref{151e,,patch.object()} or @ref{1981,,patch.dict()} as
normal and keep a reference to the returned @code{patcher} object. You can then
call @code{start()} to put the patch in place and @code{stop()} to undo it.

If you are using @ref{e7b,,patch()} to create a mock for you then it will be returned by
the call to @code{patcher.start}.

@example
>>> patcher = patch('package.module.ClassName')
>>> from package import module
>>> original = module.ClassName
>>> new_mock = patcher.start()
>>> assert module.ClassName is not original
>>> assert module.ClassName is new_mock
>>> patcher.stop()
>>> assert module.ClassName is original
>>> assert module.ClassName is not new_mock
@end example

A typical use case for this might be for doing multiple patches in the @code{setUp}
method of a @ref{437,,TestCase}:

@example
>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher1 = patch('package.module.Class1')
...         self.patcher2 = patch('package.module.Class2')
...         self.MockClass1 = self.patcher1.start()
...         self.MockClass2 = self.patcher2.start()
...
...     def tearDown(self):
...         self.patcher1.stop()
...         self.patcher2.stop()
...
...     def test_something(self):
...         assert package.module.Class1 is self.MockClass1
...         assert package.module.Class2 is self.MockClass2
...
>>> MyTest('test_something').run()
@end example

@cartouche
@quotation Prudence 
If you use this technique you must ensure that the patching is "undone" by
calling @code{stop}. This can be fiddlier than you might think, because if an
exception is raised in the @code{setUp} then @code{tearDown} is not called.
@ref{a6f,,unittest.TestCase.addCleanup()} makes this easier:

@example
>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('package.module.Class')
...         self.MockClass = patcher.start()
...         self.addCleanup(patcher.stop)
...
...     def test_something(self):
...         assert package.module.Class is self.MockClass
...
@end example

As an added bonus you no longer need to keep a reference to the @code{patcher}
object.
@end quotation
@end cartouche

It is also possible to stop all patches which have been started by using
@ref{4023,,patch.stopall()}.

@geindex patch.stopall() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock patch stopall}@anchor{4023}
@deffn {Fonction} patch.stopall ()

Stop all active patches. Only stops patches started with @code{start}.
@end deffn

@node patch builtins,TEST_PREFIX,patch methods start and stop,The patchers
@anchor{library/unittest mock id4}@anchor{4024}@anchor{library/unittest mock patch-builtins}@anchor{4025}
@subsubsection patch builtins


You can patch any builtins within a module. The following example patches
builtin @ref{1e75,,ord()}:

@example
>>> @@patch('__main__.ord')
... def test(mock_ord):
...     mock_ord.return_value = 101
...     print(ord('c'))
...
>>> test()
101
@end example

@node TEST_PREFIX,Nesting Patch Decorators,patch builtins,The patchers
@anchor{library/unittest mock id5}@anchor{4026}@anchor{library/unittest mock test-prefix}@anchor{401e}
@subsubsection TEST_PREFIX


All of the patchers can be used as class decorators. When used in this way
they wrap every test method on the class. The patchers recognise methods that
start with @code{'test'} as being test methods. This is the same way that the
@ref{28b,,unittest.TestLoader} finds test methods by default.

It is possible that you want to use a different prefix for your tests. You can
inform the patchers of the different prefix by setting @code{patch.TEST_PREFIX}:

@example
>>> patch.TEST_PREFIX = 'foo'
>>> value = 3
>>>
>>> @@patch('__main__.value', 'not three')
... class Thing:
...     def foo_one(self):
...         print(value)
...     def foo_two(self):
...         print(value)
...
>>>
>>> Thing().foo_one()
not three
>>> Thing().foo_two()
not three
>>> value
3
@end example

@node Nesting Patch Decorators,Where to patch,TEST_PREFIX,The patchers
@anchor{library/unittest mock nesting-patch-decorators}@anchor{4027}
@subsubsection Nesting Patch Decorators


If you want to perform multiple patches then you can simply stack up the
decorators.

You can stack up multiple patch decorators using this pattern:

@example
>>> @@patch.object(SomeClass, 'class_method')
... @@patch.object(SomeClass, 'static_method')
... def test(mock1, mock2):
...     assert SomeClass.static_method is mock1
...     assert SomeClass.class_method is mock2
...     SomeClass.static_method('foo')
...     SomeClass.class_method('bar')
...     return mock1, mock2
...
>>> mock1, mock2 = test()
>>> mock1.assert_called_once_with('foo')
>>> mock2.assert_called_once_with('bar')
@end example

Note that the decorators are applied from the bottom upwards. This is the
standard way that Python applies decorators. The order of the created mocks
passed into your test function matches this order.

@node Where to patch,Patching Descriptors and Proxy Objects,Nesting Patch Decorators,The patchers
@anchor{library/unittest mock id6}@anchor{401b}@anchor{library/unittest mock where-to-patch}@anchor{3fef}
@subsubsection Where to patch


@ref{e7b,,patch()} works by (temporarily) changing the object that a `name' points to with
another one. There can be many names pointing to any individual object, so
for patching to work you must ensure that you patch the name used by the system
under test.

The basic principle is that you patch where an object is `looked up', which
is not necessarily the same place as where it is defined. A couple of
examples will help to clarify this.

Imagine we have a project that we want to test with the following structure:

@example
a.py
    -> Defines SomeClass

b.py
    -> from a import SomeClass
    -> some_function instantiates SomeClass
@end example

Now we want to test @code{some_function} but we want to mock out @code{SomeClass} using
@ref{e7b,,patch()}. The problem is that when we import module b, which we will have to
do then it imports @code{SomeClass} from module a. If we use @ref{e7b,,patch()} to mock out
@code{a.SomeClass} then it will have no effect on our test; module b already has a
reference to the `real' @code{SomeClass} and it looks like our patching had no
effect.

The key is to patch out @code{SomeClass} where it is used (or where it is looked up).
In this case @code{some_function} will actually look up @code{SomeClass} in module b,
where we have imported it. The patching should look like:

@example
@@patch('b.SomeClass')
@end example

However, consider the alternative scenario where instead of @code{from a import
SomeClass} module b does @code{import a} and @code{some_function} uses @code{a.SomeClass}. Both
of these import forms are common. In this case the class we want to patch is
being looked up in the module and so we have to patch @code{a.SomeClass} instead:

@example
@@patch('a.SomeClass')
@end example

@node Patching Descriptors and Proxy Objects,,Where to patch,The patchers
@anchor{library/unittest mock patching-descriptors-and-proxy-objects}@anchor{4028}
@subsubsection Patching Descriptors and Proxy Objects


Both @ref{401a,,patch} and @ref{401c,,patch.object} correctly patch and restore descriptors: class
methods, static methods and properties. You should patch these on the `class'
rather than an instance. They also work with `some' objects
that proxy attribute access, like the django settings object@footnote{https://web.archive.org/web/20200603181648/http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198}.

@node MagicMock and magic method support,Helpers,The patchers,unittest mock --- mock object library
@anchor{library/unittest mock magicmock-and-magic-method-support}@anchor{4029}
@subsubsection MagicMock and magic method support


@menu
* Mocking Magic Methods:: 
* Magic Mock:: 

@end menu

@node Mocking Magic Methods,Magic Mock,,MagicMock and magic method support
@anchor{library/unittest mock magic-methods}@anchor{3ff0}@anchor{library/unittest mock mocking-magic-methods}@anchor{402a}
@subsubsection Mocking Magic Methods


@ref{a3a,,Mock} supports mocking the Python protocol methods, also known as
@ref{402b,,"magic methods"}. This allows mock objects to replace
containers or other objects that implement Python protocols.

Because magic methods are looked up differently from normal methods @footnote{
Magic methods `should' be looked up on the class rather than the
instance. Different versions of Python are inconsistent about applying this
rule. The supported protocol methods should work with all supported versions
of Python.
}, this
support has been specially implemented. This means that only specific magic
methods are supported. The supported list includes `almost' all of them. If
there are any missing that you need please let us know.

You mock magic methods by setting the method you are interested in to a function
or a mock instance. If you are using a function then it `must' take @code{self} as
the first argument @footnote{
The function is basically hooked up to the class, but each @code{Mock}
instance is kept isolated from the others.
}.

@example
>>> def __str__(self):
...     return 'fooble'
...
>>> mock = Mock()
>>> mock.__str__ = __str__
>>> str(mock)
'fooble'
@end example

@example
>>> mock = Mock()
>>> mock.__str__ = Mock()
>>> mock.__str__.return_value = 'fooble'
>>> str(mock)
'fooble'
@end example

@example
>>> mock = Mock()
>>> mock.__iter__ = Mock(return_value=iter([]))
>>> list(mock)
[]
@end example

One use case for this is for mocking objects used as context managers in a
@ref{5bc,,with} statement:

@example
>>> mock = Mock()
>>> mock.__enter__ = Mock(return_value='foo')
>>> mock.__exit__ = Mock(return_value=False)
>>> with mock as m:
...     assert m == 'foo'
...
>>> mock.__enter__.assert_called_with()
>>> mock.__exit__.assert_called_with(None, None, None)
@end example

Calls to magic methods do not appear in @ref{3ffc,,method_calls}, but they
are recorded in @ref{3ffa,,mock_calls}.

@cartouche
@quotation Note 
If you use the `spec' keyword argument to create a mock then attempting to
set a magic method that isn't in the spec will raise an @ref{343,,AttributeError}.
@end quotation
@end cartouche

The full list of supported magic methods is:


@itemize *

@item 
@code{__hash__}, @code{__sizeof__}, @code{__repr__} and @code{__str__}

@item 
@code{__dir__}, @code{__format__} et @code{__subclasses__}

@item 
@code{__round__}, @code{__floor__}, @code{__trunc__} and @code{__ceil__}

@item 
Comparisons: @code{__lt__}, @code{__gt__}, @code{__le__}, @code{__ge__},
@code{__eq__} and @code{__ne__}

@item 
Container methods: @code{__getitem__}, @code{__setitem__}, @code{__delitem__},
@code{__contains__}, @code{__len__}, @code{__iter__}, @code{__reversed__}
and @code{__missing__}

@item 
Context manager: @code{__enter__}, @code{__exit__}, @code{__aenter__} and @code{__aexit__}

@item 
Unary numeric methods: @code{__neg__}, @code{__pos__} and @code{__invert__}

@item 
The numeric methods (including right hand and in-place variants):
@code{__add__}, @code{__sub__}, @code{__mul__}, @code{__matmul__}, @code{__truediv__},
@code{__floordiv__}, @code{__mod__}, @code{__divmod__}, @code{__lshift__},
@code{__rshift__}, @code{__and__}, @code{__xor__}, @code{__or__}, and @code{__pow__}

@item 
Numeric conversion methods: @code{__complex__}, @code{__int__}, @code{__float__}
and @code{__index__}

@item 
Descriptor methods: @code{__get__}, @code{__set__} and @code{__delete__}

@item 
Pickling: @code{__reduce__}, @code{__reduce_ex__}, @code{__getinitargs__},
@code{__getnewargs__}, @code{__getstate__} and @code{__setstate__}

@item 
File system path representation: @code{__fspath__}

@item 
Asynchronous iteration methods: @code{__aiter__} and @code{__anext__}
@end itemize


Modifié dans la version 3.8: Added support for @ref{c40,,os.PathLike.__fspath__()}.



Modifié dans la version 3.8: Added support for @code{__aenter__}, @code{__aexit__}, @code{__aiter__} and @code{__anext__}.


The following methods exist but are `not' supported as they are either in use
by mock, can't be set dynamically, or can cause problems:


@itemize *

@item 
@code{__getattr__}, @code{__setattr__}, @code{__init__} and @code{__new__}

@item 
@code{__prepare__}, @code{__instancecheck__}, @code{__subclasscheck__}, @code{__del__}
@end itemize

@node Magic Mock,,Mocking Magic Methods,MagicMock and magic method support
@anchor{library/unittest mock magic-mock}@anchor{402c}
@subsubsection Magic Mock


There are two @code{MagicMock} variants: @ref{e7a,,MagicMock} and @ref{3ff4,,NonCallableMagicMock}.

@geindex MagicMock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock MagicMock}@anchor{e7a}
@deffn {Classe} unittest.mock.MagicMock (*args, **kw)

@code{MagicMock} is a subclass of @ref{a3a,,Mock} with default implementations
of most of the @ref{402b,,magic methods}. You can use
@code{MagicMock} without having to configure the magic methods yourself.

The constructor parameters have the same meaning as for @ref{a3a,,Mock}.

If you use the `spec' or `spec_set' arguments then `only' magic methods
that exist in the spec will be created.
@end deffn

@geindex NonCallableMagicMock (classe dans unittest.mock)
@anchor{library/unittest mock unittest mock NonCallableMagicMock}@anchor{3ff4}
@deffn {Classe} unittest.mock.NonCallableMagicMock (*args, **kw)

A non-callable version of @ref{e7a,,MagicMock}.

The constructor parameters have the same meaning as for
@ref{e7a,,MagicMock}, with the exception of `return_value' and
`side_effect' which have no meaning on a non-callable mock.
@end deffn

The magic methods are setup with @ref{e7a,,MagicMock} objects, so you can configure them
and use them in the usual way:

@example
>>> mock = MagicMock()
>>> mock[3] = 'fish'
>>> mock.__setitem__.assert_called_with(3, 'fish')
>>> mock.__getitem__.return_value = 'result'
>>> mock[2]
'result'
@end example

By default many of the protocol methods are required to return objects of a
specific type. These methods are preconfigured with a default return value, so
that they can be used without you having to do anything if you aren't interested
in the return value. You can still `set' the return value manually if you want
to change the default.

Methods and their defaults:


@itemize *

@item 
@code{__lt__}: @ref{7bc,,NotImplemented}

@item 
@code{__gt__}: @code{NotImplemented}

@item 
@code{__le__}: @code{NotImplemented}

@item 
@code{__ge__}: @code{NotImplemented}

@item 
@code{__int__}: @code{1}

@item 
@code{__contains__}: @code{False}

@item 
@code{__int__}: @code{0}

@item 
@code{__iter__}: @code{iter([])}

@item 
@code{__exit__}: @code{False}

@item 
@code{__exit__}: @code{False}

@item 
@code{__complex__}: @code{1j}

@item 
@code{__float__}: @code{1.0}

@item 
@code{__bool__}: @code{True}

@item 
@code{__index__}: @code{1}

@item 
@code{__hash__}: default hash for the mock

@item 
@code{__str__}: default str for the mock

@item 
@code{__sizeof__}: default sizeof for the mock
@end itemize

Par exemple :

@example
>>> mock = MagicMock()
>>> int(mock)
1
>>> len(mock)
0
>>> list(mock)
[]
>>> object() in mock
False
@end example

The two equality methods, @code{__eq__()} and @code{__ne__()}, are special.
They do the default equality comparison on identity, using the
@ref{3fee,,side_effect} attribute, unless you change their return value to
return something else:

@example
>>> MagicMock() == 3
False
>>> MagicMock() != 3
True
>>> mock = MagicMock()
>>> mock.__eq__.return_value = True
>>> mock == 3
True
@end example

The return value of @code{MagicMock.__iter__()} can be any iterable object and isn't
required to be an iterator:

@example
>>> mock = MagicMock()
>>> mock.__iter__.return_value = ['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
['a', 'b', 'c']
@end example

If the return value `is' an iterator, then iterating over it once will consume
it and subsequent iterations will result in an empty list:

@example
>>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
>>> list(mock)
['a', 'b', 'c']
>>> list(mock)
[]
@end example

@code{MagicMock} has all of the supported magic methods configured except for some
of the obscure and obsolete ones. You can still set these up if you want.

Magic methods that are supported but not setup by default in @code{MagicMock} are:


@itemize *

@item 
@code{__subclasses__}

@item 
@code{__dir__}

@item 
@code{__format__}

@item 
@code{__get__}, @code{__set__} et @code{__delete__}

@item 
@code{__reversed__} et @code{__missing__}

@item 
@code{__reduce__}, @code{__reduce_ex__}, @code{__getinitargs__}, @code{__getnewargs__},
@code{__getstate__} and @code{__setstate__}

@item 
@code{__getformat__}
@end itemize

@node Helpers,Order of precedence of side_effect return_value and wraps,MagicMock and magic method support,unittest mock --- mock object library
@anchor{library/unittest mock helpers}@anchor{402d}
@subsubsection Helpers


@menu
* sentinel:: 
* DEFAULT:: 
* appel:: 
* create_autospec:: 
* ANY:: 
* FILTER_DIR:: 
* mock_open:: 
* Autospeccing:: 
* Sealing mocks:: 

@end menu

@node sentinel,DEFAULT,,Helpers
@anchor{library/unittest mock sentinel}@anchor{402e}
@subsubsection sentinel


@geindex sentinel (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock sentinel}@anchor{b8e}
@deffn {Données} unittest.mock.sentinel

The @code{sentinel} object provides a convenient way of providing unique
objects for your tests.

Attributes are created on demand when you access them by name. Accessing
the same attribute will always return the same object. The objects
returned have a sensible repr so that test failure messages are readable.


Modifié dans la version 3.7: The @code{sentinel} attributes now preserve their identity when they are
@ref{25,,copied} or @ref{a5,,pickled}.

@end deffn

Sometimes when testing you need to test that a specific object is passed as an
argument to another method, or returned. It can be common to create named
sentinel objects to test this. @ref{b8e,,sentinel} provides a convenient way of
creating and testing the identity of objects like this.

In this example we monkey patch @code{method} to return @code{sentinel.some_object}:

@example
>>> real = ProductionClass()
>>> real.method = Mock(name="method")
>>> real.method.return_value = sentinel.some_object
>>> result = real.method()
>>> assert result is sentinel.some_object
>>> result
sentinel.some_object
@end example

@node DEFAULT,appel,sentinel,Helpers
@anchor{library/unittest mock default}@anchor{402f}
@subsubsection DEFAULT


@geindex DEFAULT (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock DEFAULT}@anchor{3ff5}
@deffn {Données} unittest.mock.DEFAULT

The @ref{3ff5,,DEFAULT} object is a pre-created sentinel (actually
@code{sentinel.DEFAULT}). It can be used by @ref{3fee,,side_effect}
functions to indicate that the normal return value should be used.
@end deffn

@node appel,create_autospec,DEFAULT,Helpers
@anchor{library/unittest mock call}@anchor{4030}
@subsubsection appel


@geindex call() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock call}@anchor{195c}
@deffn {Fonction} unittest.mock.call (*args, **kwargs)

@ref{195c,,call()} is a helper object for making simpler assertions, for comparing with
@ref{190e,,call_args}, @ref{4002,,call_args_list},
@ref{3ffa,,mock_calls} and @ref{3ffc,,method_calls}. @ref{195c,,call()} can also be
used with @ref{1631,,assert_has_calls()}.

@example
>>> m = MagicMock(return_value=None)
>>> m(1, 2, a='foo', b='bar')
>>> m()
>>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
True
@end example
@end deffn

@geindex call_list() (méthode unittest.mock.call)
@anchor{library/unittest mock unittest mock call call_list}@anchor{4031}
@deffn {Méthode} call.call_list ()

For a call object that represents multiple calls, @ref{4031,,call_list()}
returns a list of all the intermediate calls as well as the
final call.
@end deffn

@code{call_list} is particularly useful for making assertions on "chained calls". A
chained call is multiple calls on a single line of code. This results in
multiple entries in @ref{3ffa,,mock_calls} on a mock. Manually constructing
the sequence of calls can be tedious.

@ref{4031,,call_list()} can construct the sequence of calls from the same
chained call:

@example
>>> m = MagicMock()
>>> m(1).method(arg='foo').other('bar')(2.0)
<MagicMock name='mock().method().other()()' id='...'>
>>> kall = call(1).method(arg='foo').other('bar')(2.0)
>>> kall.call_list()
[call(1),
 call().method(arg='foo'),
 call().method().other('bar'),
 call().method().other()(2.0)]
>>> m.mock_calls == kall.call_list()
True
@end example
@anchor{library/unittest mock calls-as-tuples}@anchor{4003}
A @code{call} object is either a tuple of (positional args, keyword args) or
(name, positional args, keyword args) depending on how it was constructed. When
you construct them yourself this isn't particularly interesting, but the @code{call}
objects that are in the @ref{190e,,Mock.call_args}, @ref{4002,,Mock.call_args_list} and
@ref{3ffa,,Mock.mock_calls} attributes can be introspected to get at the individual
arguments they contain.

The @code{call} objects in @ref{190e,,Mock.call_args} and @ref{4002,,Mock.call_args_list}
are two-tuples of (positional args, keyword args) whereas the @code{call} objects
in @ref{3ffa,,Mock.mock_calls}, along with ones you construct yourself, are
three-tuples of (name, positional args, keyword args).

You can use their "tupleness" to pull out the individual arguments for more
complex introspection and assertions. The positional arguments are a tuple
(an empty tuple if there are no positional arguments) and the keyword
arguments are a dictionary:

@example
>>> m = MagicMock(return_value=None)
>>> m(1, 2, 3, arg='one', arg2='two')
>>> kall = m.call_args
>>> kall.args
(1, 2, 3)
>>> kall.kwargs
@{'arg': 'one', 'arg2': 'two'@}
>>> kall.args is kall[0]
True
>>> kall.kwargs is kall[1]
True
@end example

@example
>>> m = MagicMock()
>>> m.foo(4, 5, 6, arg='two', arg2='three')
<MagicMock name='mock.foo()' id='...'>
>>> kall = m.mock_calls[0]
>>> name, args, kwargs = kall
>>> name
'foo'
>>> args
(4, 5, 6)
>>> kwargs
@{'arg': 'two', 'arg2': 'three'@}
>>> name is m.mock_calls[0][0]
True
@end example

@node create_autospec,ANY,appel,Helpers
@anchor{library/unittest mock create-autospec}@anchor{4032}
@subsubsection create_autospec


@geindex create_autospec() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock create_autospec}@anchor{1590}
@deffn {Fonction} unittest.mock.create_autospec (spec, spec_set=False, instance=False, **kwargs)

Create a mock object using another object as a spec. Attributes on the
mock will use the corresponding attribute on the `spec' object as their
spec.

Functions or methods being mocked will have their arguments checked to
ensure that they are called with the correct signature.

If `spec_set' is @code{True} then attempting to set attributes that don't exist
on the spec object will raise an @ref{343,,AttributeError}.

If a class is used as a spec then the return value of the mock (the
instance of the class) will have the same spec. You can use a class as the
spec for an instance object by passing @code{instance=True}. The returned mock
will only be callable if instances of the mock are callable.

@ref{1590,,create_autospec()} also takes arbitrary keyword arguments that are passed to
the constructor of the created mock.
@end deffn

See @ref{3ff1,,Autospeccing} for examples of how to use auto-speccing with
@ref{1590,,create_autospec()} and the `autospec' argument to @ref{e7b,,patch()}.


Modifié dans la version 3.8: @ref{1590,,create_autospec()} now returns an @ref{a39,,AsyncMock} if the target is
an async function.


@node ANY,FILTER_DIR,create_autospec,Helpers
@anchor{library/unittest mock any}@anchor{4033}
@subsubsection ANY


@geindex ANY (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock ANY}@anchor{195a}
@deffn {Données} unittest.mock.ANY
@end deffn

Sometimes you may need to make assertions about `some' of the arguments in a
call to mock, but either not care about some of the arguments or want to pull
them individually out of @ref{190e,,call_args} and make more complex
assertions on them.

To ignore certain arguments you can pass in objects that compare equal to
`everything'. Calls to @ref{19af,,assert_called_with()} and
@ref{3ff8,,assert_called_once_with()} will then succeed no matter what was
passed in.

@example
>>> mock = Mock(return_value=None)
>>> mock('foo', bar=object())
>>> mock.assert_called_once_with('foo', bar=ANY)
@end example

@ref{195a,,ANY} can also be used in comparisons with call lists like
@ref{3ffa,,mock_calls}:

@example
>>> m = MagicMock(return_value=None)
>>> m(1)
>>> m(1, 2)
>>> m(object())
>>> m.mock_calls == [call(1), call(1, 2), ANY]
True
@end example

@ref{195a,,ANY} is not limited to comparisons with call objects and so
can also be used in test assertions:

@example
class TestStringMethods(unittest.TestCase):

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', ANY])
@end example

@node FILTER_DIR,mock_open,ANY,Helpers
@anchor{library/unittest mock filter-dir}@anchor{4034}
@subsubsection FILTER_DIR


@geindex FILTER_DIR (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock FILTER_DIR}@anchor{3ffe}
@deffn {Données} unittest.mock.FILTER_DIR
@end deffn

@ref{3ffe,,FILTER_DIR} is a module level variable that controls the way mock objects
respond to @ref{61d,,dir()}. The default is @code{True},
which uses the filtering described below, to only show useful members. If you
dislike this filtering, or need to switch it off for diagnostic purposes, then
set @code{mock.FILTER_DIR = False}.

With filtering on, @code{dir(some_mock)} shows only useful attributes and will
include any dynamically created attributes that wouldn't normally be shown.
If the mock was created with a `spec' (or `autospec' of course) then all the
attributes from the original are shown, even if they haven't been accessed
yet:

@example
>>> dir(Mock())
['assert_any_call',
 'assert_called',
 'assert_called_once',
 'assert_called_once_with',
 'assert_called_with',
 'assert_has_calls',
 'assert_not_called',
 'attach_mock',
 ...
>>> from urllib import request
>>> dir(Mock(spec=request))
['AbstractBasicAuthHandler',
 'AbstractDigestAuthHandler',
 'AbstractHTTPHandler',
 'BaseHandler',
 ...
@end example

Many of the not-very-useful (private to @ref{a3a,,Mock} rather than the thing being
mocked) underscore and double underscore prefixed attributes have been
filtered from the result of calling @ref{61d,,dir()} on a @ref{a3a,,Mock}. If you dislike this
behaviour you can switch it off by setting the module level switch
@ref{3ffe,,FILTER_DIR}:

@example
>>> from unittest import mock
>>> mock.FILTER_DIR = False
>>> dir(mock.Mock())
['_NonCallableMock__get_return_value',
 '_NonCallableMock__get_side_effect',
 '_NonCallableMock__return_value_doc',
 '_NonCallableMock__set_return_value',
 '_NonCallableMock__set_side_effect',
 '__call__',
 '__class__',
 ...
@end example

Alternatively you can just use @code{vars(my_mock)} (instance members) and
@code{dir(type(my_mock))} (type members) to bypass the filtering irrespective of
@ref{3ffe,,FILTER_DIR}.

@node mock_open,Autospeccing,FILTER_DIR,Helpers
@anchor{library/unittest mock mock-open}@anchor{4035}
@subsubsection mock_open


@geindex mock_open() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock mock_open}@anchor{1693}
@deffn {Fonction} unittest.mock.mock_open (mock=None, read_data=None)

A helper function to create a mock to replace the use of @ref{505,,open()}. It works
for @ref{505,,open()} called directly or used as a context manager.

The `mock' argument is the mock object to configure. If @code{None} (the
default) then a @ref{e7a,,MagicMock} will be created for you, with the API limited
to methods or attributes available on standard file handles.

`read_data' is a string for the @ref{e09,,read()},
@ref{1307,,readline()}, and @ref{22ba,,readlines()} methods
of the file handle to return.  Calls to those methods will take data from
`read_data' until it is depleted.  The mock of these methods is pretty
simplistic: every time the `mock' is called, the `read_data' is rewound to
the start.  If you need more control over the data that you are feeding to
the tested code you will need to customize this mock for yourself.  When that
is insufficient, one of the in-memory filesystem packages on PyPI@footnote{https://pypi.org} can offer a realistic filesystem for testing.


Modifié dans la version 3.4: Added @ref{1307,,readline()} and @ref{22ba,,readlines()} support.
The mock of @ref{e09,,read()} changed to consume `read_data' rather
than returning it on each call.



Modifié dans la version 3.5: `read_data' is now reset on each call to the `mock'.



Modifié dans la version 3.8: Added @ref{1c4e,,__iter__()} to implementation so that iteration
(such as in for loops) correctly consumes `read_data'.

@end deffn

Using @ref{505,,open()} as a context manager is a great way to ensure your file handles
are closed properly and is becoming common:

@example
with open('/some/path', 'w') as f:
    f.write('something')
@end example

The issue is that even if you mock out the call to @ref{505,,open()} it is the
`returned object' that is used as a context manager (and has @ref{5b2,,__enter__()} and
@ref{12de,,__exit__()} called).

Mocking context managers with a @ref{e7a,,MagicMock} is common enough and fiddly
enough that a helper function is useful.

@example
>>> m = mock_open()
>>> with patch('__main__.open', m):
...     with open('foo', 'w') as h:
...         h.write('some stuff')
...
>>> m.mock_calls
[call('foo', 'w'),
 call().__enter__(),
 call().write('some stuff'),
 call().__exit__(None, None, None)]
>>> m.assert_called_once_with('foo', 'w')
>>> handle = m()
>>> handle.write.assert_called_once_with('some stuff')
@end example

And for reading files:

@example
>>> with patch('__main__.open', mock_open(read_data='bibble')) as m:
...     with open('foo') as h:
...         result = h.read()
...
>>> m.assert_called_once_with('foo')
>>> assert result == 'bibble'
@end example

@node Autospeccing,Sealing mocks,mock_open,Helpers
@anchor{library/unittest mock auto-speccing}@anchor{3ff1}@anchor{library/unittest mock autospeccing}@anchor{4036}
@subsubsection Autospeccing


Autospeccing is based on the existing @code{spec} feature of mock. It limits the
api of mocks to the api of an original object (the spec), but it is recursive
(implemented lazily) so that attributes of mocks only have the same api as
the attributes of the spec. In addition mocked functions / methods have the
same call signature as the original so they raise a @ref{522,,TypeError} if they are
called incorrectly.

Before I explain how auto-speccing works, here's why it is needed.

@ref{a3a,,Mock} is a very powerful and flexible object, but it suffers from a flaw which
is general to mocking. If you refactor some of your code, rename members and so on, any
tests for code that is still using the `old api' but uses mocks instead of the real
objects will still pass. This means your tests can all pass even though your code is
broken.


Modifié dans la version 3.5: Before 3.5, tests with a typo in the word assert would silently pass when they should
raise an error. You can still achieve this behavior by passing @code{unsafe=True} to Mock.


Note that this is another reason why you need integration tests as well as
unit tests. Testing everything in isolation is all fine and dandy, but if you
don't test how your units are "wired together" there is still lots of room
for bugs that tests might have caught.

@ref{106,,unittest.mock} already provides a feature to help with this, called speccing. If you
use a class or instance as the @code{spec} for a mock then you can only access
attributes on the mock that exist on the real class:

@example
>>> from urllib import request
>>> mock = Mock(spec=request.Request)
>>> mock.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'
@end example

The spec only applies to the mock itself, so we still have the same issue
with any methods on the mock:

@example
>>> mock.has_data()
<mock.Mock object at 0x...>
>>> mock.has_data.assret_called_with()  # Intentional typo!
@end example

Auto-speccing solves this problem. You can either pass @code{autospec=True} to
@ref{e7b,,patch()} / @ref{151e,,patch.object()} or use the @ref{1590,,create_autospec()} function to create a
mock with a spec. If you use the @code{autospec=True} argument to @ref{e7b,,patch()} then the
object that is being replaced will be used as the spec object. Because the
speccing is done "lazily" (the spec is created as attributes on the mock are
accessed) you can use it with very complex or deeply nested objects (like
modules that import modules that import modules) without a big performance
hit.

Here's an example of it in use:

@example
>>> from urllib import request
>>> patcher = patch('__main__.request', autospec=True)
>>> mock_request = patcher.start()
>>> request is mock_request
True
>>> mock_request.Request
<MagicMock name='request.Request' spec='Request' id='...'>
@end example

You can see that @code{request.Request} has a spec. @code{request.Request} takes two
arguments in the constructor (one of which is `self'). Here's what happens if
we try to call it incorrectly:

@example
>>> req = request.Request()
Traceback (most recent call last):
 ...
TypeError: <lambda>() takes at least 2 arguments (1 given)
@end example

The spec also applies to instantiated classes (i.e. the return value of
specced mocks):

@example
>>> req = request.Request('foo')
>>> req
<NonCallableMagicMock name='request.Request()' spec='Request' id='...'>
@end example

@code{Request} objects are not callable, so the return value of instantiating our
mocked out @code{request.Request} is a non-callable mock. With the spec in place
any typos in our asserts will raise the correct error:

@example
>>> req.add_header('spam', 'eggs')
<MagicMock name='request.Request().add_header()' id='...'>
>>> req.add_header.assret_called_with  # Intentional typo!
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'assret_called_with'
>>> req.add_header.assert_called_with('spam', 'eggs')
@end example

In many cases you will just be able to add @code{autospec=True} to your existing
@ref{e7b,,patch()} calls and then be protected against bugs due to typos and api
changes.

As well as using `autospec' through @ref{e7b,,patch()} there is a
@ref{1590,,create_autospec()} for creating autospecced mocks directly:

@example
>>> from urllib import request
>>> mock_request = create_autospec(request)
>>> mock_request.Request('foo', 'bar')
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>
@end example

This isn't without caveats and limitations however, which is why it is not
the default behaviour. In order to know what attributes are available on the
spec object, autospec has to introspect (access attributes) the spec. As you
traverse attributes on the mock a corresponding traversal of the original
object is happening under the hood. If any of your specced objects have
properties or descriptors that can trigger code execution then you may not be
able to use autospec. On the other hand it is much better to design your
objects so that introspection is safe @footnote{
This only applies to classes or already instantiated objects. Calling
a mocked class to create a mock instance `does not' create a real instance.
It is only attribute lookups - along with calls to @ref{61d,,dir()} - that are done.
}.

A more serious problem is that it is common for instance attributes to be
created in the @ref{69b,,__init__()} method and not to exist on the class at all.
`autospec' can't know about any dynamically created attributes and restricts
the api to visible attributes.

@example
>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a
...
Traceback (most recent call last):
  ...
AttributeError: Mock object has no attribute 'a'
@end example

There are a few different ways of resolving this problem. The easiest, but
not necessarily the least annoying, way is to simply set the required
attributes on the mock after creation. Just because `autospec' doesn't allow
you to fetch attributes that don't exist on the spec it doesn't prevent you
setting them:

@example
>>> with patch('__main__.Something', autospec=True):
...   thing = Something()
...   thing.a = 33
...
@end example

There is a more aggressive version of both `spec' and `autospec' that `does'
prevent you setting non-existent attributes. This is useful if you want to
ensure your code only `sets' valid attributes too, but obviously it prevents
this particular scenario:

@example
>>> with patch('__main__.Something', autospec=True, spec_set=True):
...   thing = Something()
...   thing.a = 33
...
Traceback (most recent call last):
 ...
AttributeError: Mock object has no attribute 'a'
@end example

Probably the best way of solving the problem is to add class attributes as
default values for instance members initialised in @ref{69b,,__init__()}.
Note that if
you are only setting default attributes in @code{__init__()} then providing them via
class attributes (shared between instances of course) is faster too. e.g.

@example
class Something:
    a = 33
@end example

This brings up another issue. It is relatively common to provide a default
value of @code{None} for members that will later be an object of a different type.
@code{None} would be useless as a spec because it wouldn't let you access `any'
attributes or methods on it. As @code{None} is `never' going to be useful as a
spec, and probably indicates a member that will normally of some other type,
autospec doesn't use a spec for members that are set to @code{None}. These will
just be ordinary mocks (well - MagicMocks):

@example
>>> class Something:
...     member = None
...
>>> mock = create_autospec(Something)
>>> mock.member.foo.bar.baz()
<MagicMock name='mock.member.foo.bar.baz()' id='...'>
@end example

If modifying your production classes to add defaults isn't to your liking
then there are more options. One of these is simply to use an instance as the
spec rather than the class. The other is to create a subclass of the
production class and add the defaults to the subclass without affecting the
production class. Both of these require you to use an alternative object as
the spec. Thankfully @ref{e7b,,patch()} supports this - you can simply pass the
alternative object as the `autospec' argument:

@example
>>> class Something:
...   def __init__(self):
...     self.a = 33
...
>>> class SomethingForTest(Something):
...   a = 33
...
>>> p = patch('__main__.Something', autospec=SomethingForTest)
>>> mock = p.start()
>>> mock.a
<NonCallableMagicMock name='Something.a' spec='int' id='...'>
@end example

@node Sealing mocks,,Autospeccing,Helpers
@anchor{library/unittest mock sealing-mocks}@anchor{4037}
@subsubsection Sealing mocks


@c from unittest.mock import seal

@geindex seal() (dans le module unittest.mock)
@anchor{library/unittest mock unittest mock seal}@anchor{b8f}
@deffn {Fonction} unittest.mock.seal (mock)

Seal will disable the automatic creation of mocks when accessing an attribute of
the mock being sealed or any of its attributes that are already mocks recursively.

If a mock instance with a name or a spec is assigned to an attribute
it won't be considered in the sealing chain. This allows one to prevent seal from
fixing part of the mock object.

@example
>>> mock = Mock()
>>> mock.submock.attribute1 = 2
>>> mock.not_submock = mock.Mock(name="sample_name")
>>> seal(mock)
>>> mock.new_attribute  # This will raise AttributeError.
>>> mock.submock.attribute2  # This will raise AttributeError.
>>> mock.not_submock.attribute2  # This won't raise.
@end example


Ajouté dans la version 3.7.

@end deffn

@node Order of precedence of side_effect return_value and wraps,,Helpers,unittest mock --- mock object library
@anchor{library/unittest mock order-of-precedence-of-side-effect-return-value-and-wraps}@anchor{4038}
@subsubsection Order of precedence of @code{side_effect}, @code{return_value} and `wraps'


The order of their precedence is:


@enumerate 

@item 
@ref{3fee,,side_effect}

@item 
@ref{3ff6,,return_value}

@item 
`wraps'
@end enumerate

If all three are set, mock will return the value from @ref{3fee,,side_effect},
ignoring @ref{3ff6,,return_value} and the wrapped object altogether. If any
two are set, the one with the higher precedence will return the value.
Regardless of the order of which was set first, the order of precedence
remains unchanged.

@example
>>> from unittest.mock import Mock
>>> class Order:
...     @@staticmethod
...     def get_value():
...         return "third"
...
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.get_value.side_effect = ["first"]
>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'first'
@end example

As @code{None} is the default value of @ref{3fee,,side_effect}, if you reassign
its value back to @code{None}, the order of precedence will be checked between
@ref{3ff6,,return_value} and the wrapped object, ignoring
@ref{3fee,,side_effect}.

@example
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
@end example

If the value being returned by @ref{3fee,,side_effect} is @ref{3ff5,,DEFAULT},
it is ignored and the order of precedence moves to the successor to obtain the
value to return.

@example
>>> from unittest.mock import DEFAULT
>>> order_mock.get_value.side_effect = [DEFAULT]
>>> order_mock.get_value()
'second'
@end example

When @ref{a3a,,Mock} wraps an object, the default value of
@ref{3ff6,,return_value} will be @ref{3ff5,,DEFAULT}.

@example
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.return_value
sentinel.DEFAULT
>>> order_mock.get_value.return_value
sentinel.DEFAULT
@end example

The order of precedence will ignore this value and it will move to the last
successor which is the wrapped object.

As the real call is being made to the wrapped object, creating an instance of
this mock will return the real instance of the class. The positional arguments,
if any, required by the wrapped object must be passed.

@example
>>> order_mock_instance = order_mock()
>>> isinstance(order_mock_instance, Order)
True
>>> order_mock_instance.get_value()
'third'
@end example

@example
>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'
@end example

@example
>>> order_mock.get_value.return_value = "second"
>>> order_mock.get_value()
'second'
@end example

But if you assign @code{None} to it, this will not be ignored as it is an
explicit assignment. So, the order of precedence will not move to the wrapped
object.

@example
>>> order_mock.get_value.return_value = None
>>> order_mock.get_value() is None
True
@end example

Even if you set all three at once when initializing the mock, the order of
precedence remains the same:

@example
>>> order_mock = Mock(spec=Order, wraps=Order,
...                   **@{"get_value.side_effect": ["first"],
...                      "get_value.return_value": "second"@}
...                   )
...
>>> order_mock.get_value()
'first'
>>> order_mock.get_value.side_effect = None
>>> order_mock.get_value()
'second'
>>> order_mock.get_value.return_value = DEFAULT
>>> order_mock.get_value()
'third'
@end example

If @ref{3fee,,side_effect} is exhausted, the order of precedence will not
cause a value to be obtained from the successors. Instead, @code{StopIteration}
exception is raised.

@example
>>> order_mock = Mock(spec=Order, wraps=Order)
>>> order_mock.get_value.side_effect = ["first side effect value",
...                                     "another side effect value"]
>>> order_mock.get_value.return_value = "second"
@end example

@example
>>> order_mock.get_value()
'first side effect value'
>>> order_mock.get_value()
'another side effect value'
@end example

@example
>>> order_mock.get_value()
Traceback (most recent call last):
 ...
StopIteration
@end example

@node unittest mock --- getting started,test --- Regression tests package for Python,unittest mock --- mock object library,Outils de développement
@anchor{library/unittest mock-examples doc}@anchor{4039}@anchor{library/unittest mock-examples unittest-mock-getting-started}@anchor{403a}
@subsection @code{unittest.mock} --- getting started



Ajouté dans la version 3.3.

@anchor{library/unittest mock-examples getting-started}@anchor{403b}
@c import asyncio
@c import unittest
@c from unittest.mock import Mock, MagicMock, AsyncMock, patch, call, sentinel
@c 
@c class SomeClass:
@c     attribute = 'this is a doctest'
@c 
@c     @staticmethod
@c     def static_method():
@c         pass

@menu
* Utilisation de Mock ou l'art de singer:: 
* Patch Decorators:: 
* Further Examples:: 

@end menu

@node Utilisation de Mock ou l'art de singer,Patch Decorators,,unittest mock --- getting started
@anchor{library/unittest mock-examples using-mock}@anchor{403c}
@subsubsection Utilisation de Mock ou l'art de singer


@menu
* Simulation des méthodes:: 
* S'assurer de la bonne utilisation d'un objet:: 
* Simulation des classes:: 
* Naming your mocks:: 
* Tracking all Calls:: 
* Setting Return Values and Attributes:: 
* Raising exceptions with mocks:: 
* Side effect functions and iterables:: 
* Mocking asynchronous iterators:: 
* Mocking asynchronous context manager:: 
* Creating a Mock from an Existing Object:: 
* Using side_effect to return per file content:: 

@end menu

@node Simulation des méthodes,S'assurer de la bonne utilisation d'un objet,,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples mock-patching-methods}@anchor{403d}
@subsubsection Simulation des méthodes


Usages courant de @ref{a3a,,Mock} :


@itemize *

@item 
Substitution des méthodes

@item 
Enregistrement des appels faits sur les objets
@end itemize

On peut remplacer une méthode sur un objet pour contrôler qu'elle est bien appelée avec le nombre correct d'arguments :

@example
>>> real = SomeClass()
>>> real.method = MagicMock(name='method')
>>> real.method(3, 4, 5, key='value')
<MagicMock name='method()' id='...'>
@end example

Une fois notre objet simulacre appelé (via @code{real.method} dans notre exemple), il fournit des méthodes et attributs permettant de valider comment il a été appelé.

@cartouche
@quotation Note 
Dans la majeure partie des exemples donnés ici, les classes @ref{a3a,,Mock} et @ref{e7a,,MagicMock} sont interchangeables. Étant donné que @code{MagicMock} est la classe la plus puissante des deux, cela fait sens de l'utiliser par défaut.
@end quotation
@end cartouche

Une fois l'objet Mock appelé, son attribut @ref{4000,,called} est défini à @code{True}. Qui plus est, nous pouvons utiliser les méthodes @ref{19af,,assert_called_with()} ou @ref{3ff8,,assert_called_once_with()} pour contrôler qu'il a été appelé avec les bons arguments.

Cet exemple teste que l'appel de la méthode @code{ProductionClass().method} implique bien celui de la méthode @code{something} :

@example
>>> class ProductionClass:
...     def method(self):
...         self.something(1, 2, 3)
...     def something(self, a, b, c):
...         pass
...
>>> real = ProductionClass()
>>> real.something = MagicMock()
>>> real.method()
>>> real.something.assert_called_once_with(1, 2, 3)
@end example

@node S'assurer de la bonne utilisation d'un objet,Simulation des classes,Simulation des méthodes,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples mock-for-method-calls-on-an-object}@anchor{403e}
@subsubsection S'assurer de la bonne utilisation d'un objet


Dans l'exemple précédent, nous avons directement remplacé une méthode par un objet (afin de valider que l'appel était correct). Une autre façon de faire est de passer un objet Mock en argument d'une méthode (ou de tout autre partie du code à tester) et ensuite de contrôler que notre objet a été utilisé de la façon attendue.

Ci-dessous, @code{ProductionClass} dispose d'une méthode @code{closer}. Si on l'appelle avec un objet, alors elle appelle la méthode @code{close} dessus.

@example
>>> class ProductionClass:
...     def closer(self, something):
...         something.close()
...
@end example

Ainsi, pour tester cette classe, nous devons lui passer un objet ayant une méthode @code{close}, puis vérifier qu'elle a bien été appelée.

@example
>>> real = ProductionClass()
>>> mock = Mock()
>>> real.closer(mock)
>>> mock.close.assert_called_with()
@end example

En fait, nous n'avons pas à nous soucier de fournir la méthode @code{close} dans notre objet « simulé ». Le simple fait d'accéder à la méthode @code{close} l'a crée. Si par contre la méthode @code{close} n'a pas été appelée alors, bien que le test la créée en y accédant, @ref{19af,,assert_called_with()} lèvera une exception.

@node Simulation des classes,Naming your mocks,S'assurer de la bonne utilisation d'un objet,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples mocking-classes}@anchor{403f}
@subsubsection Simulation des classes


Un cas d'utilisation courant consiste à émuler les classes instanciées par le code que nous testons. Quand on `patch' une classe, alors cette classe est remplacée par un objet `mock'. Les instances de la classe étant créées en `appelant la classe', on accède à « l'instance `mock' » via la valeur de retour de la classe émulée.

In the example below we have a function @code{some_function} that instantiates @code{Foo}
and calls a method on it. The call to @ref{e7b,,patch()} replaces the class @code{Foo} with a
mock. The @code{Foo} instance is the result of calling the mock, so it is configured
by modifying the mock @ref{3ff6,,return_value}.

@example
>>> def some_function():
...     instance = module.Foo()
...     return instance.method()
...
>>> with patch('module.Foo') as mock:
...     instance = mock.return_value
...     instance.method.return_value = 'the result'
...     result = some_function()
...     assert result == 'the result'
@end example

@node Naming your mocks,Tracking all Calls,Simulation des classes,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples naming-your-mocks}@anchor{4040}
@subsubsection Naming your mocks


It can be useful to give your mocks a name. The name is shown in the repr of
the mock and can be helpful when the mock appears in test failure messages. The
name is also propagated to attributes or methods of the mock:

@example
>>> mock = MagicMock(name='foo')
>>> mock
<MagicMock name='foo' id='...'>
>>> mock.method
<MagicMock name='foo.method' id='...'>
@end example

@node Tracking all Calls,Setting Return Values and Attributes,Naming your mocks,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples tracking-all-calls}@anchor{4041}
@subsubsection Tracking all Calls


Often you want to track more than a single call to a method. The
@ref{3ffa,,mock_calls} attribute records all calls
to child attributes of the mock - and also to their children.

@example
>>> mock = MagicMock()
>>> mock.method()
<MagicMock name='mock.method()' id='...'>
>>> mock.attribute.method(10, x=53)
<MagicMock name='mock.attribute.method()' id='...'>
>>> mock.mock_calls
[call.method(), call.attribute.method(10, x=53)]
@end example

If you make an assertion about @code{mock_calls} and any unexpected methods
have been called, then the assertion will fail. This is useful because as well
as asserting that the calls you expected have been made, you are also checking
that they were made in the right order and with no additional calls:

You use the @ref{195c,,call} object to construct lists for comparing with
@code{mock_calls}:

@example
>>> expected = [call.method(), call.attribute.method(10, x=53)]
>>> mock.mock_calls == expected
True
@end example

However, parameters to calls that return mocks are not recorded, which means it is not
possible to track nested calls where the parameters used to create ancestors are important:

@example
>>> m = Mock()
>>> m.factory(important=True).deliver()
<Mock name='mock.factory().deliver()' id='...'>
>>> m.mock_calls[-1] == call.factory(important=False).deliver()
True
@end example

@node Setting Return Values and Attributes,Raising exceptions with mocks,Tracking all Calls,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples setting-return-values-and-attributes}@anchor{4042}
@subsubsection Setting Return Values and Attributes


Setting the return values on a mock object is trivially easy:

@example
>>> mock = Mock()
>>> mock.return_value = 3
>>> mock()
3
@end example

Of course you can do the same for methods on the mock:

@example
>>> mock = Mock()
>>> mock.method.return_value = 3
>>> mock.method()
3
@end example

The return value can also be set in the constructor:

@example
>>> mock = Mock(return_value=3)
>>> mock()
3
@end example

If you need an attribute setting on your mock, just do it:

@example
>>> mock = Mock()
>>> mock.x = 3
>>> mock.x
3
@end example

Sometimes you want to mock up a more complex situation, like for example
@code{mock.connection.cursor().execute("SELECT 1")}. If we wanted this call to
return a list, then we have to configure the result of the nested call.

We can use @ref{195c,,call} to construct the set of calls in a "chained call" like
this for easy assertion afterwards:

@example
>>> mock = Mock()
>>> cursor = mock.connection.cursor.return_value
>>> cursor.execute.return_value = ['foo']
>>> mock.connection.cursor().execute("SELECT 1")
['foo']
>>> expected = call.connection.cursor().execute("SELECT 1").call_list()
>>> mock.mock_calls
[call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]
>>> mock.mock_calls == expected
True
@end example

It is the call to @code{.call_list()} that turns our call object into a list of
calls representing the chained calls.

@node Raising exceptions with mocks,Side effect functions and iterables,Setting Return Values and Attributes,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples raising-exceptions-with-mocks}@anchor{4043}
@subsubsection Raising exceptions with mocks


A useful attribute is @ref{3fee,,side_effect}. If you set this to an
exception class or instance then the exception will be raised when the mock
is called.

@example
>>> mock = Mock(side_effect=Exception('Boom!'))
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!
@end example

@node Side effect functions and iterables,Mocking asynchronous iterators,Raising exceptions with mocks,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples side-effect-functions-and-iterables}@anchor{4044}
@subsubsection Side effect functions and iterables


@code{side_effect} can also be set to a function or an iterable. The use case for
@code{side_effect} as an iterable is where your mock is going to be called several
times, and you want each call to return a different value. When you set
@code{side_effect} to an iterable every call to the mock returns the next value
from the iterable:

@example
>>> mock = MagicMock(side_effect=[4, 5, 6])
>>> mock()
4
>>> mock()
5
>>> mock()
6
@end example

For more advanced use cases, like dynamically varying the return values
depending on what the mock is called with, @code{side_effect} can be a function.
The function will be called with the same arguments as the mock. Whatever the
function returns is what the call returns:

@example
>>> vals = @{(1, 2): 1, (2, 3): 2@}
>>> def side_effect(*args):
...     return vals[args]
...
>>> mock = MagicMock(side_effect=side_effect)
>>> mock(1, 2)
1
>>> mock(2, 3)
2
@end example

@node Mocking asynchronous iterators,Mocking asynchronous context manager,Side effect functions and iterables,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples mocking-asynchronous-iterators}@anchor{4045}
@subsubsection Mocking asynchronous iterators


Since Python 3.8, @code{AsyncMock} and @code{MagicMock} have support to mock
@ref{d67,,Itérateurs asynchrones} through @code{__aiter__}. The @ref{3ff6,,return_value}
attribute of @code{__aiter__} can be used to set the return values to be used for
iteration.

@example
>>> mock = MagicMock()  # AsyncMock also works here
>>> mock.__aiter__.return_value = [1, 2, 3]
>>> async def main():
...     return [i async for i in mock]
...
>>> asyncio.run(main())
[1, 2, 3]
@end example

@node Mocking asynchronous context manager,Creating a Mock from an Existing Object,Mocking asynchronous iterators,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples mocking-asynchronous-context-manager}@anchor{4046}
@subsubsection Mocking asynchronous context manager


Since Python 3.8, @code{AsyncMock} and @code{MagicMock} have support to mock
@ref{5e6,,Gestionnaires de contexte asynchrones} through @code{__aenter__} and @code{__aexit__}.
By default, @code{__aenter__} and @code{__aexit__} are @code{AsyncMock} instances that
return an async function.

@example
>>> class AsyncContextManager:
...     async def __aenter__(self):
...         return self
...     async def __aexit__(self, exc_type, exc, tb):
...         pass
...
>>> mock_instance = MagicMock(AsyncContextManager())  # AsyncMock also works here
>>> async def main():
...     async with mock_instance as result:
...         pass
...
>>> asyncio.run(main())
>>> mock_instance.__aenter__.assert_awaited_once()
>>> mock_instance.__aexit__.assert_awaited_once()
@end example

@node Creating a Mock from an Existing Object,Using side_effect to return per file content,Mocking asynchronous context manager,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples creating-a-mock-from-an-existing-object}@anchor{4047}
@subsubsection Creating a Mock from an Existing Object


One problem with over use of mocking is that it couples your tests to the
implementation of your mocks rather than your real code. Suppose you have a
class that implements @code{some_method}. In a test for another class, you
provide a mock of this object that `also' provides @code{some_method}. If later
you refactor the first class, so that it no longer has @code{some_method} - then
your tests will continue to pass even though your code is now broken!

@ref{a3a,,Mock} allows you to provide an object as a specification for the mock,
using the `spec' keyword argument. Accessing methods / attributes on the
mock that don't exist on your specification object will immediately raise an
attribute error. If you change the implementation of your specification, then
tests that use that class will start failing immediately without you having to
instantiate the class in those tests.

@example
>>> mock = Mock(spec=SomeClass)
>>> mock.old_method()
Traceback (most recent call last):
   ...
AttributeError: Mock object has no attribute 'old_method'. Did you mean: 'class_method'?
@end example

Using a specification also enables a smarter matching of calls made to the
mock, regardless of whether some parameters were passed as positional or
named arguments:

@example
>>> def f(a, b, c): pass
...
>>> mock = Mock(spec=f)
>>> mock(1, 2, 3)
<Mock name='mock()' id='140161580456576'>
>>> mock.assert_called_with(a=1, b=2, c=3)
@end example

If you want this smarter matching to also work with method calls on the mock,
you can use @ref{3ff1,,auto-speccing}.

If you want a stronger form of specification that prevents the setting
of arbitrary attributes as well as the getting of them then you can use
`spec_set' instead of `spec'.

@node Using side_effect to return per file content,,Creating a Mock from an Existing Object,Utilisation de Mock ou l'art de singer
@anchor{library/unittest mock-examples using-side-effect-to-return-per-file-content}@anchor{4048}
@subsubsection Using side_effect to return per file content


@ref{1693,,mock_open()} is used to patch @ref{505,,open()} method. @ref{3fee,,side_effect}
can be used to return a new Mock object per call. This can be used to return different
contents per file stored in a dictionary:

@example
DEFAULT = "default"
data_dict = @{"file1": "data1",
             "file2": "data2"@}

def open_side_effect(name):
    return mock_open(read_data=data_dict.get(name, DEFAULT))()

with patch("builtins.open", side_effect=open_side_effect):
    with open("file1") as file1:
        assert file1.read() == "data1"

    with open("file2") as file2:
        assert file2.read() == "data2"

    with open("file3") as file2:
        assert file2.read() == "default"
@end example

@node Patch Decorators,Further Examples,Utilisation de Mock ou l'art de singer,unittest mock --- getting started
@anchor{library/unittest mock-examples patch-decorators}@anchor{4049}
@subsubsection Patch Decorators


@cartouche
@quotation Note 
Avec @ref{e7b,,patch()}, il est important de `patcher' les objets dans l'espace de nommage où ils sont recherchés. C'est ce qui se fait normalement, mais pour un guide rapide, lisez @ref{3fef,,où patcher}.
@end quotation
@end cartouche

A common need in tests is to patch a class attribute or a module attribute,
for example patching a builtin or patching a class in a module to test that it
is instantiated. Modules and classes are effectively global, so patching on
them has to be undone after the test or the patch will persist into other
tests and cause hard to diagnose problems.

mock provides three convenient decorators for this: @ref{e7b,,patch()}, @ref{151e,,patch.object()} and
@ref{1981,,patch.dict()}. @code{patch} takes a single string, of the form
@code{package.module.Class.attribute} to specify the attribute you are patching. It
also optionally takes a value that you want the attribute (or class or
whatever) to be replaced with. 'patch.object' takes an object and the name of
the attribute you would like patched, plus optionally the value to patch it
with.

@code{patch.object} :

@example
>>> original = SomeClass.attribute
>>> @@patch.object(SomeClass, 'attribute', sentinel.attribute)
... def test():
...     assert SomeClass.attribute == sentinel.attribute
...
>>> test()
>>> assert SomeClass.attribute == original

>>> @@patch('package.module.attribute', sentinel.attribute)
... def test():
...     from package.module import attribute
...     assert attribute is sentinel.attribute
...
>>> test()
@end example

If you are patching a module (including @ref{12,,builtins}) then use @ref{e7b,,patch()}
instead of @ref{151e,,patch.object()}:

@example
>>> mock = MagicMock(return_value=sentinel.file_handle)
>>> with patch('builtins.open', mock):
...     handle = open('filename', 'r')
...
>>> mock.assert_called_with('filename', 'r')
>>> assert handle == sentinel.file_handle, "incorrect file handle returned"
@end example

The module name can be 'dotted', in the form @code{package.module} if needed:

@example
>>> @@patch('package.module.ClassName.attribute', sentinel.attribute)
... def test():
...     from package.module import ClassName
...     assert ClassName.attribute == sentinel.attribute
...
>>> test()
@end example

A nice pattern is to actually decorate test methods themselves:

@example
>>> class MyTest(unittest.TestCase):
...     @@patch.object(SomeClass, 'attribute', sentinel.attribute)
...     def test_something(self):
...         self.assertEqual(SomeClass.attribute, sentinel.attribute)
...
>>> original = SomeClass.attribute
>>> MyTest('test_something').test_something()
>>> assert SomeClass.attribute == original
@end example

If you want to patch with a Mock, you can use @ref{e7b,,patch()} with only one argument
(or @ref{151e,,patch.object()} with two arguments). The mock will be created for you and
passed into the test function / method:

@example
>>> class MyTest(unittest.TestCase):
...     @@patch.object(SomeClass, 'static_method')
...     def test_something(self, mock_method):
...         SomeClass.static_method()
...         mock_method.assert_called_with()
...
>>> MyTest('test_something').test_something()
@end example

You can stack up multiple patch decorators using this pattern:

@example
>>> class MyTest(unittest.TestCase):
...     @@patch('package.module.ClassName1')
...     @@patch('package.module.ClassName2')
...     def test_something(self, MockClass2, MockClass1):
...         self.assertIs(package.module.ClassName1, MockClass1)
...         self.assertIs(package.module.ClassName2, MockClass2)
...
>>> MyTest('test_something').test_something()
@end example

When you nest patch decorators the mocks are passed in to the decorated
function in the same order they applied (the normal `Python' order that
decorators are applied). This means from the bottom up, so in the example
above the mock for @code{test_module.ClassName2} is passed in first.

Il existe également @ref{1981,,patch.dict()} pour définir des valeurs d'un dictionnaire au sein d'une portée et restaurer ce dictionnaire à son état d'origine lorsque le test se termine :

@example
>>> foo = @{'key': 'value'@}
>>> original = foo.copy()
>>> with patch.dict(foo, @{'newkey': 'newvalue'@}, clear=True):
...     assert foo == @{'newkey': 'newvalue'@}
...
>>> assert foo == original
@end example

@code{patch}, @code{patch.object} and @code{patch.dict} can all be used as context managers.

Where you use @ref{e7b,,patch()} to create a mock for you, you can get a reference to the
mock using the "as" form of the with statement:

@example
>>> class ProductionClass:
...     def method(self):
...         pass
...
>>> with patch.object(ProductionClass, 'method') as mock_method:
...     mock_method.return_value = None
...     real = ProductionClass()
...     real.method(1, 2, 3)
...
>>> mock_method.assert_called_with(1, 2, 3)
@end example

As an alternative @code{patch}, @code{patch.object} and @code{patch.dict} can be used as
class decorators. When used in this way it is the same as applying the
decorator individually to every method whose name starts with "test".

@node Further Examples,,Patch Decorators,unittest mock --- getting started
@anchor{library/unittest mock-examples further-examples}@anchor{404a}@anchor{library/unittest mock-examples id1}@anchor{404b}
@subsubsection Further Examples


Here are some more examples for some slightly more advanced scenarios.

@menu
* Mocking chained calls:: 
* Partial mocking:: 
* Mocking a Generator Method:: 
* Applying the same patch to every test method:: 
* Mocking Unbound Methods:: 
* Checking multiple calls with mock:: 
* Coping with mutable arguments:: 
* Nesting Patches:: 
* Mocking a dictionary with MagicMock:: 
* Mock subclasses and their attributes:: 
* Mocking imports with patch.dict: Mocking imports with patch dict. 
* Tracking order of calls and less verbose call assertions:: 
* More complex argument matching:: 

@end menu

@node Mocking chained calls,Partial mocking,,Further Examples
@anchor{library/unittest mock-examples mocking-chained-calls}@anchor{404c}
@subsubsection Mocking chained calls


Mocking chained calls is actually straightforward with mock once you
understand the @ref{3ff6,,return_value} attribute. When a mock is called for
the first time, or you fetch its @code{return_value} before it has been called, a
new @ref{a3a,,Mock} is created.

This means that you can see how the object returned from a call to a mocked
object has been used by interrogating the @code{return_value} mock:

@example
>>> mock = Mock()
>>> mock().foo(a=2, b=3)
<Mock name='mock().foo()' id='...'>
>>> mock.return_value.foo.assert_called_with(a=2, b=3)
@end example

From here it is a simple step to configure and then make assertions about
chained calls. Of course another alternative is writing your code in a more
testable way in the first place...

So, suppose we have some code that looks a little bit like this:

@example
>>> class Something:
...     def __init__(self):
...         self.backend = BackendProvider()
...     def method(self):
...         response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
...         # more code
@end example

Assuming that @code{BackendProvider} is already well tested, how do we test
@code{method()}? Specifically, we want to test that the code section @code{# more
code} uses the response object in the correct way.

As this chain of calls is made from an instance attribute we can monkey patch
the @code{backend} attribute on a @code{Something} instance. In this particular case
we are only interested in the return value from the final call to
@code{start_call} so we don't have much configuration to do. Let's assume the
object it returns is 'file-like', so we'll ensure that our response object
uses the builtin @ref{505,,open()} as its @code{spec}.

To do this we create a mock instance as our mock backend and create a mock
response object for it. To set the response as the return value for that final
@code{start_call} we could do this:

@example
mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response
@end example

We can do that in a slightly nicer way using the @ref{3ff7,,configure_mock()}
method to directly set the return value for us:

@example
>>> something = Something()
>>> mock_response = Mock(spec=open)
>>> mock_backend = Mock()
>>> config = @{'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response@}
>>> mock_backend.configure_mock(**config)
@end example

With these we monkey patch the "mock backend" in place and can make the real
call:

@example
>>> something.backend = mock_backend
>>> something.method()
@end example

Using @ref{3ffa,,mock_calls} we can check the chained call with a single
assert. A chained call is several calls in one line of code, so there will be
several entries in @code{mock_calls}. We can use @ref{4031,,call.call_list()} to create
this list of calls for us:

@example
>>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
>>> call_list = chained.call_list()
>>> assert mock_backend.mock_calls == call_list
@end example

@node Partial mocking,Mocking a Generator Method,Mocking chained calls,Further Examples
@anchor{library/unittest mock-examples partial-mocking}@anchor{404d}
@subsubsection Partial mocking


In some tests I wanted to mock out a call to @ref{1480,,datetime.date.today()}
to return a known date, but I didn't want to prevent the code under test from
creating new date objects. Unfortunately @ref{1c8,,datetime.date} is written in C, and
so I couldn't just monkey-patch out the static @ref{1480,,datetime.date.today()} method.

I found a simple way of doing this that involved effectively wrapping the date
class with a mock, but passing through calls to the constructor to the real
class (and returning real instances).

The @ref{e7b,,patch decorator} is used here to
mock out the @code{date} class in the module under test. The @ref{3fee,,side_effect}
attribute on the mock date class is then set to a lambda function that returns
a real date. When the mock date class is called a real date will be
constructed and returned by @code{side_effect}.

@example
>>> from datetime import date
>>> with patch('mymodule.date') as mock_date:
...     mock_date.today.return_value = date(2010, 10, 8)
...     mock_date.side_effect = lambda *args, **kw: date(*args, **kw)
...
...     assert mymodule.date.today() == date(2010, 10, 8)
...     assert mymodule.date(2009, 6, 8) == date(2009, 6, 8)
@end example

Note that we don't patch @ref{1c8,,datetime.date} globally, we patch @code{date} in the
module that `uses' it. See @ref{3fef,,where to patch}.

When @code{date.today()} is called a known date is returned, but calls to the
@code{date(...)} constructor still return normal dates. Without this you can find
yourself having to calculate an expected result using exactly the same
algorithm as the code under test, which is a classic testing anti-pattern.

Calls to the date constructor are recorded in the @code{mock_date} attributes
(@code{call_count} and friends) which may also be useful for your tests.

An alternative way of dealing with mocking dates, or other builtin classes,
is discussed in this blog entry@footnote{https://williambert.online/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/}.

@node Mocking a Generator Method,Applying the same patch to every test method,Partial mocking,Further Examples
@anchor{library/unittest mock-examples mocking-a-generator-method}@anchor{404e}
@subsubsection Mocking a Generator Method


A Python generator is a function or method that uses the @ref{9bb,,yield} statement
to return a series of values when iterated over @footnote{
There are also generator expressions and more @uref{http://www.dabeaz.com/coroutines/index.html,advanced uses} of generators, but we aren't
concerned about them here. A very good introduction to generators and how
powerful they are is: @uref{http://www.dabeaz.com/generators/,Generator Tricks for Systems Programmers}.
}.

A generator method / function is called to return the generator object. It is
the generator object that is then iterated over. The protocol method for
iteration is @ref{1c4e,,__iter__()}, so we can
mock this using a @ref{e7a,,MagicMock}.

Here's an example class with an "iter" method implemented as a generator:

@example
>>> class Foo:
...     def iter(self):
...         for i in [1, 2, 3]:
...             yield i
...
>>> foo = Foo()
>>> list(foo.iter())
[1, 2, 3]
@end example

How would we mock this class, and in particular its "iter" method?

To configure the values returned from the iteration (implicit in the call to
@ref{5fc,,list}), we need to configure the object returned by the call to @code{foo.iter()}.

@example
>>> mock_foo = MagicMock()
>>> mock_foo.iter.return_value = iter([1, 2, 3])
>>> list(mock_foo.iter())
[1, 2, 3]
@end example

@node Applying the same patch to every test method,Mocking Unbound Methods,Mocking a Generator Method,Further Examples
@anchor{library/unittest mock-examples applying-the-same-patch-to-every-test-method}@anchor{404f}
@subsubsection Applying the same patch to every test method


If you want several patches in place for multiple test methods the obvious way
is to apply the patch decorators to every method. This can feel like unnecessary
repetition. Instead, you can use @ref{e7b,,patch()} (in all its
various forms) as a class decorator. This applies the patches to all test
methods on the class. A test method is identified by methods whose names start
with @code{test}:

@example
>>> @@patch('mymodule.SomeClass')
... class MyTest(unittest.TestCase):
...
...     def test_one(self, MockSomeClass):
...         self.assertIs(mymodule.SomeClass, MockSomeClass)
...
...     def test_two(self, MockSomeClass):
...         self.assertIs(mymodule.SomeClass, MockSomeClass)
...
...     def not_a_test(self):
...         return 'something'
...
>>> MyTest('test_one').test_one()
>>> MyTest('test_two').test_two()
>>> MyTest('test_two').not_a_test()
'something'
@end example

An alternative way of managing patches is to use the @ref{4022,,patch methods; start and stop}.
These allow you to move the patching into your @code{setUp} and @code{tearDown} methods.

@example
>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         self.patcher = patch('mymodule.foo')
...         self.mock_foo = self.patcher.start()
...
...     def test_foo(self):
...         self.assertIs(mymodule.foo, self.mock_foo)
...
...     def tearDown(self):
...         self.patcher.stop()
...
>>> MyTest('test_foo').run()
@end example

If you use this technique you must ensure that the patching is "undone" by
calling @code{stop}. This can be fiddlier than you might think, because if an
exception is raised in the setUp then tearDown is not called.
@ref{a6f,,unittest.TestCase.addCleanup()} makes this easier:

@example
>>> class MyTest(unittest.TestCase):
...     def setUp(self):
...         patcher = patch('mymodule.foo')
...         self.addCleanup(patcher.stop)
...         self.mock_foo = patcher.start()
...
...     def test_foo(self):
...         self.assertIs(mymodule.foo, self.mock_foo)
...
>>> MyTest('test_foo').run()
@end example

@node Mocking Unbound Methods,Checking multiple calls with mock,Applying the same patch to every test method,Further Examples
@anchor{library/unittest mock-examples mocking-unbound-methods}@anchor{4050}
@subsubsection Mocking Unbound Methods


Whilst writing tests today I needed to patch an `unbound method' (patching the
method on the class rather than on the instance). I needed self to be passed
in as the first argument because I want to make asserts about which objects
were calling this particular method. The issue is that you can't patch with a
mock for this, because if you replace an unbound method with a mock it doesn't
become a bound method when fetched from the instance, and so it doesn't get
self passed in. The workaround is to patch the unbound method with a real
function instead. The @ref{e7b,,patch()} decorator makes it so simple to
patch out methods with a mock that having to create a real function becomes a
nuisance.

If you pass @code{autospec=True} to patch then it does the patching with a
`real' function object. This function object has the same signature as the one
it is replacing, but delegates to a mock under the hood. You still get your
mock auto-created in exactly the same way as before. What it means though, is
that if you use it to patch out an unbound method on a class the mocked
function will be turned into a bound method if it is fetched from an instance.
It will have @code{self} passed in as the first argument, which is exactly what I
wanted:

@example
>>> class Foo:
...   def foo(self):
...     pass
...
>>> with patch.object(Foo, 'foo', autospec=True) as mock_foo:
...   mock_foo.return_value = 'foo'
...   foo = Foo()
...   foo.foo()
...
'foo'
>>> mock_foo.assert_called_once_with(foo)
@end example

If we don't use @code{autospec=True} then the unbound method is patched out
with a Mock instance instead, and isn't called with @code{self}.

@node Checking multiple calls with mock,Coping with mutable arguments,Mocking Unbound Methods,Further Examples
@anchor{library/unittest mock-examples checking-multiple-calls-with-mock}@anchor{4051}
@subsubsection Checking multiple calls with mock


mock has a nice API for making assertions about how your mock objects are used.

@example
>>> mock = Mock()
>>> mock.foo_bar.return_value = None
>>> mock.foo_bar('baz', spam='eggs')
>>> mock.foo_bar.assert_called_with('baz', spam='eggs')
@end example

If your mock is only being called once you can use the
@ref{3ff8,,assert_called_once_with()} method that also asserts that the
@ref{4001,,call_count} is one.

@example
>>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
>>> mock.foo_bar()
>>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
Traceback (most recent call last):
    ...
AssertionError: Expected 'foo_bar' to be called once. Called 2 times.
Calls: [call('baz', spam='eggs'), call()].
@end example

Both @code{assert_called_with} and @code{assert_called_once_with} make assertions about
the `most recent' call. If your mock is going to be called several times, and
you want to make assertions about `all' those calls you can use
@ref{4002,,call_args_list}:

@example
>>> mock = Mock(return_value=None)
>>> mock(1, 2, 3)
>>> mock(4, 5, 6)
>>> mock()
>>> mock.call_args_list
[call(1, 2, 3), call(4, 5, 6), call()]
@end example

The @ref{195c,,call} helper makes it easy to make assertions about these calls. You
can build up a list of expected calls and compare it to @code{call_args_list}. This
looks remarkably similar to the repr of the @code{call_args_list}:

@example
>>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
>>> mock.call_args_list == expected
True
@end example

@node Coping with mutable arguments,Nesting Patches,Checking multiple calls with mock,Further Examples
@anchor{library/unittest mock-examples coping-with-mutable-arguments}@anchor{4052}
@subsubsection Coping with mutable arguments


Another situation is rare, but can bite you, is when your mock is called with
mutable arguments. @code{call_args} and @code{call_args_list} store `references' to the
arguments. If the arguments are mutated by the code under test then you can no
longer make assertions about what the values were when the mock was called.

Here's some example code that shows the problem. Imagine the following functions
defined in 'mymodule':

@example
def frob(val):
    pass

def grob(val):
    "First frob and then clear val"
    frob(val)
    val.clear()
@end example

When we try to test that @code{grob} calls @code{frob} with the correct argument look
what happens:

@example
>>> with patch('mymodule.frob') as mock_frob:
...     val = @{6@}
...     mymodule.grob(val)
...
>>> val
set()
>>> mock_frob.assert_called_with(@{6@})
Traceback (most recent call last):
    ...
AssertionError: Expected: ((@{6@},), @{@})
Called with: ((set(),), @{@})
@end example

One possibility would be for mock to copy the arguments you pass in. This
could then cause problems if you do assertions that rely on object identity
for equality.

Here's one solution that uses the @ref{3fee,,side_effect}
functionality. If you provide a @code{side_effect} function for a mock then
@code{side_effect} will be called with the same args as the mock. This gives us an
opportunity to copy the arguments and store them for later assertions. In this
example I'm using `another' mock to store the arguments so that I can use the
mock methods for doing the assertion. Again a helper function sets this up for
me.

@example
>>> from copy import deepcopy
>>> from unittest.mock import Mock, patch, DEFAULT
>>> def copy_call_args(mock):
...     new_mock = Mock()
...     def side_effect(*args, **kwargs):
...         args = deepcopy(args)
...         kwargs = deepcopy(kwargs)
...         new_mock(*args, **kwargs)
...         return DEFAULT
...     mock.side_effect = side_effect
...     return new_mock
...
>>> with patch('mymodule.frob') as mock_frob:
...     new_mock = copy_call_args(mock_frob)
...     val = @{6@}
...     mymodule.grob(val)
...
>>> new_mock.assert_called_with(@{6@})
>>> new_mock.call_args
call(@{6@})
@end example

@code{copy_call_args} is called with the mock that will be called. It returns a new
mock that we do the assertion on. The @code{side_effect} function makes a copy of
the args and calls our @code{new_mock} with the copy.

@cartouche
@quotation Note 
If your mock is only going to be used once there is an easier way of
checking arguments at the point they are called. You can simply do the
checking inside a @code{side_effect} function.

@example
>>> def side_effect(arg):
...     assert arg == @{6@}
...
>>> mock = Mock(side_effect=side_effect)
>>> mock(@{6@})
>>> mock(set())
Traceback (most recent call last):
    ...
AssertionError
@end example
@end quotation
@end cartouche

An alternative approach is to create a subclass of @ref{a3a,,Mock} or
@ref{e7a,,MagicMock} that copies (using @ref{b5c,,copy.deepcopy()}) the arguments.
Here's an example implementation:

@example
>>> from copy import deepcopy
>>> class CopyingMock(MagicMock):
...     def __call__(self, /, *args, **kwargs):
...         args = deepcopy(args)
...         kwargs = deepcopy(kwargs)
...         return super().__call__(*args, **kwargs)
...
>>> c = CopyingMock(return_value=None)
>>> arg = set()
>>> c(arg)
>>> arg.add(1)
>>> c.assert_called_with(set())
>>> c.assert_called_with(arg)
Traceback (most recent call last):
    ...
AssertionError: expected call not found.
Expected: mock(@{1@})
Actual: mock(set())
>>> c.foo
<CopyingMock name='mock.foo' id='...'>
@end example

When you subclass @code{Mock} or @code{MagicMock} all dynamically created attributes,
and the @code{return_value} will use your subclass automatically. That means all
children of a @code{CopyingMock} will also have the type @code{CopyingMock}.

@node Nesting Patches,Mocking a dictionary with MagicMock,Coping with mutable arguments,Further Examples
@anchor{library/unittest mock-examples nesting-patches}@anchor{4053}
@subsubsection Nesting Patches


Using patch as a context manager is nice, but if you do multiple patches you
can end up with nested with statements indenting further and further to the
right:

@example
>>> class MyTest(unittest.TestCase):
...
...     def test_foo(self):
...         with patch('mymodule.Foo') as mock_foo:
...             with patch('mymodule.Bar') as mock_bar:
...                 with patch('mymodule.Spam') as mock_spam:
...                     assert mymodule.Foo is mock_foo
...                     assert mymodule.Bar is mock_bar
...                     assert mymodule.Spam is mock_spam
...
>>> original = mymodule.Foo
>>> MyTest('test_foo').test_foo()
>>> assert mymodule.Foo is original
@end example

With unittest @code{cleanup} functions and the @ref{4022,,patch methods; start and stop} we can
achieve the same effect without the nested indentation. A simple helper
method, @code{create_patch}, puts the patch in place and returns the created mock
for us:

@example
>>> class MyTest(unittest.TestCase):
...
...     def create_patch(self, name):
...         patcher = patch(name)
...         thing = patcher.start()
...         self.addCleanup(patcher.stop)
...         return thing
...
...     def test_foo(self):
...         mock_foo = self.create_patch('mymodule.Foo')
...         mock_bar = self.create_patch('mymodule.Bar')
...         mock_spam = self.create_patch('mymodule.Spam')
...
...         assert mymodule.Foo is mock_foo
...         assert mymodule.Bar is mock_bar
...         assert mymodule.Spam is mock_spam
...
>>> original = mymodule.Foo
>>> MyTest('test_foo').run()
>>> assert mymodule.Foo is original
@end example

@node Mocking a dictionary with MagicMock,Mock subclasses and their attributes,Nesting Patches,Further Examples
@anchor{library/unittest mock-examples mocking-a-dictionary-with-magicmock}@anchor{4054}
@subsubsection Mocking a dictionary with MagicMock


You may want to mock a dictionary, or other container object, recording all
access to it whilst having it still behave like a dictionary.

We can do this with @ref{e7a,,MagicMock}, which will behave like a dictionary,
and using @ref{3fee,,side_effect} to delegate dictionary access to a real
underlying dictionary that is under our control.

When the @ref{280,,__getitem__()} and @ref{12a9,,__setitem__()} methods
of our @code{MagicMock} are called
(normal dictionary access) then @code{side_effect} is called with the key (and in
the case of @code{__setitem__} the value too). We can also control what is returned.

After the @code{MagicMock} has been used we can use attributes like
@ref{4002,,call_args_list} to assert about how the dictionary was used:

@example
>>> my_dict = @{'a': 1, 'b': 2, 'c': 3@}
>>> def getitem(name):
...      return my_dict[name]
...
>>> def setitem(name, val):
...     my_dict[name] = val
...
>>> mock = MagicMock()
>>> mock.__getitem__.side_effect = getitem
>>> mock.__setitem__.side_effect = setitem
@end example

@cartouche
@quotation Note 
An alternative to using @code{MagicMock} is to use @code{Mock} and `only' provide
the magic methods you specifically want:

@example
>>> mock = Mock()
>>> mock.__getitem__ = Mock(side_effect=getitem)
>>> mock.__setitem__ = Mock(side_effect=setitem)
@end example

A `third' option is to use @code{MagicMock} but passing in @code{dict} as the `spec'
(or `spec_set') argument so that the @code{MagicMock} created only has
dictionary magic methods available:

@example
>>> mock = MagicMock(spec_set=dict)
>>> mock.__getitem__.side_effect = getitem
>>> mock.__setitem__.side_effect = setitem
@end example
@end quotation
@end cartouche

With these side effect functions in place, the @code{mock} will behave like a normal
dictionary but recording the access. It even raises a @ref{33a,,KeyError} if you try
to access a key that doesn't exist.

@example
>>> mock['a']
1
>>> mock['c']
3
>>> mock['d']
Traceback (most recent call last):
    ...
KeyError: 'd'
>>> mock['b'] = 'fish'
>>> mock['d'] = 'eggs'
>>> mock['b']
'fish'
>>> mock['d']
'eggs'
@end example

After it has been used you can make assertions about the access using the normal
mock methods and attributes:

@example
>>> mock.__getitem__.call_args_list
[call('a'), call('c'), call('d'), call('b'), call('d')]
>>> mock.__setitem__.call_args_list
[call('b', 'fish'), call('d', 'eggs')]
>>> my_dict
@{'a': 1, 'b': 'fish', 'c': 3, 'd': 'eggs'@}
@end example

@node Mock subclasses and their attributes,Mocking imports with patch dict,Mocking a dictionary with MagicMock,Further Examples
@anchor{library/unittest mock-examples mock-subclasses-and-their-attributes}@anchor{4055}
@subsubsection Mock subclasses and their attributes


There are various reasons why you might want to subclass @ref{a3a,,Mock}. One
reason might be to add helper methods. Here's a silly example:

@example
>>> class MyMock(MagicMock):
...     def has_been_called(self):
...         return self.called
...
>>> mymock = MyMock(return_value=None)
>>> mymock
<MyMock id='...'>
>>> mymock.has_been_called()
False
>>> mymock()
>>> mymock.has_been_called()
True
@end example

The standard behaviour for @code{Mock} instances is that attributes and the return
value mocks are of the same type as the mock they are accessed on. This ensures
that @code{Mock} attributes are @code{Mocks} and @code{MagicMock} attributes are @code{MagicMocks}
@footnote{
An exception to this rule are the non-callable mocks. Attributes use the
callable variant because otherwise non-callable mocks couldn't have callable
methods.
}. So if you're subclassing to add helper methods then they'll also be
available on the attributes and return value mock of instances of your
subclass.

@example
>>> mymock.foo
<MyMock name='mock.foo' id='...'>
>>> mymock.foo.has_been_called()
False
>>> mymock.foo()
<MyMock name='mock.foo()' id='...'>
>>> mymock.foo.has_been_called()
True
@end example

Sometimes this is inconvenient. For example, one user@footnote{https://code.google.com/archive/p/mock/issues/105} is subclassing mock to
created a Twisted adaptor@footnote{https://twisted.org/documents/11.0.0/api/twisted.python.components.html}.
Having this applied to attributes too actually causes errors.

@code{Mock} (in all its flavours) uses a method called @code{_get_child_mock} to create
these "sub-mocks" for attributes and return values. You can prevent your
subclass being used for attributes by overriding this method. The signature is
that it takes arbitrary keyword arguments (@code{**kwargs}) which are then passed
onto the mock constructor:

@example
>>> class Subclass(MagicMock):
...     def _get_child_mock(self, /, **kwargs):
...         return MagicMock(**kwargs)
...
>>> mymock = Subclass()
>>> mymock.foo
<MagicMock name='mock.foo' id='...'>
>>> assert isinstance(mymock, Subclass)
>>> assert not isinstance(mymock.foo, Subclass)
>>> assert not isinstance(mymock(), Subclass)
@end example

@node Mocking imports with patch dict,Tracking order of calls and less verbose call assertions,Mock subclasses and their attributes,Further Examples
@anchor{library/unittest mock-examples mocking-imports-with-patch-dict}@anchor{4056}
@subsubsection Mocking imports with patch.dict


One situation where mocking can be hard is where you have a local import inside
a function. These are harder to mock because they aren't using an object from
the module namespace that we can patch out.

Generally local imports are to be avoided. They are sometimes done to prevent
circular dependencies, for which there is `usually' a much better way to solve
the problem (refactor the code) or to prevent "up front costs" by delaying the
import. This can also be solved in better ways than an unconditional local
import (store the module as a class or module attribute and only do the import
on first use).

That aside there is a way to use @code{mock} to affect the results of an import.
Importing fetches an `object' from the @ref{18f9,,sys.modules} dictionary. Note that it
fetches an `object', which need not be a module. Importing a module for the
first time results in a module object being put in @code{sys.modules}, so usually
when you import something you get a module back. This need not be the case
however.

This means you can use @ref{1981,,patch.dict()} to `temporarily' put a mock in place
in @ref{18f9,,sys.modules}. Any imports whilst this patch is active will fetch the mock.
When the patch is complete (the decorated function exits, the with statement
body is complete or @code{patcher.stop()} is called) then whatever was there
previously will be restored safely.

Here's an example that mocks out the 'fooble' module.

@example
>>> import sys
>>> mock = Mock()
>>> with patch.dict('sys.modules', @{'fooble': mock@}):
...    import fooble
...    fooble.blob()
...
<Mock name='mock.blob()' id='...'>
>>> assert 'fooble' not in sys.modules
>>> mock.blob.assert_called_once_with()
@end example

As you can see the @code{import fooble} succeeds, but on exit there is no 'fooble'
left in @ref{18f9,,sys.modules}.

This also works for the @code{from module import name} form:

@example
>>> mock = Mock()
>>> with patch.dict('sys.modules', @{'fooble': mock@}):
...    from fooble import blob
...    blob.blip()
...
<Mock name='mock.blob.blip()' id='...'>
>>> mock.blob.blip.assert_called_once_with()
@end example

With slightly more work you can also mock package imports:

@example
>>> mock = Mock()
>>> modules = @{'package': mock, 'package.module': mock.module@}
>>> with patch.dict('sys.modules', modules):
...    from package.module import fooble
...    fooble()
...
<Mock name='mock.module.fooble()' id='...'>
>>> mock.module.fooble.assert_called_once_with()
@end example

@node Tracking order of calls and less verbose call assertions,More complex argument matching,Mocking imports with patch dict,Further Examples
@anchor{library/unittest mock-examples tracking-order-of-calls-and-less-verbose-call-assertions}@anchor{4057}
@subsubsection Tracking order of calls and less verbose call assertions


The @ref{a3a,,Mock} class allows you to track the `order' of method calls on
your mock objects through the @ref{3ffc,,method_calls} attribute. This
doesn't allow you to track the order of calls between separate mock objects,
however we can use @ref{3ffa,,mock_calls} to achieve the same effect.

Because mocks track calls to child mocks in @code{mock_calls}, and accessing an
arbitrary attribute of a mock creates a child mock, we can create our separate
mocks from a parent one. Calls to those child mock will then all be recorded,
in order, in the @code{mock_calls} of the parent:

@example
>>> manager = Mock()
>>> mock_foo = manager.foo
>>> mock_bar = manager.bar
@end example

@example
>>> mock_foo.something()
<Mock name='mock.foo.something()' id='...'>
>>> mock_bar.other.thing()
<Mock name='mock.bar.other.thing()' id='...'>
@end example

@example
>>> manager.mock_calls
[call.foo.something(), call.bar.other.thing()]
@end example

We can then assert about the calls, including the order, by comparing with
the @code{mock_calls} attribute on the manager mock:

@example
>>> expected_calls = [call.foo.something(), call.bar.other.thing()]
>>> manager.mock_calls == expected_calls
True
@end example

If @code{patch} is creating, and putting in place, your mocks then you can attach
them to a manager mock using the @ref{1597,,attach_mock()} method. After
attaching calls will be recorded in @code{mock_calls} of the manager.

@example
>>> manager = MagicMock()
>>> with patch('mymodule.Class1') as MockClass1:
...     with patch('mymodule.Class2') as MockClass2:
...         manager.attach_mock(MockClass1, 'MockClass1')
...         manager.attach_mock(MockClass2, 'MockClass2')
...         MockClass1().foo()
...         MockClass2().bar()
<MagicMock name='mock.MockClass1().foo()' id='...'>
<MagicMock name='mock.MockClass2().bar()' id='...'>
>>> manager.mock_calls
[call.MockClass1(),
call.MockClass1().foo(),
call.MockClass2(),
call.MockClass2().bar()]
@end example

If many calls have been made, but you're only interested in a particular
sequence of them then an alternative is to use the
@ref{1631,,assert_has_calls()} method. This takes a list of calls (constructed
with the @ref{195c,,call} object). If that sequence of calls are in
@ref{3ffa,,mock_calls} then the assert succeeds.

@example
>>> m = MagicMock()
>>> m().foo().bar().baz()
<MagicMock name='mock().foo().bar().baz()' id='...'>
>>> m.one().two().three()
<MagicMock name='mock.one().two().three()' id='...'>
>>> calls = call.one().two().three().call_list()
>>> m.assert_has_calls(calls)
@end example

Even though the chained call @code{m.one().two().three()} aren't the only calls that
have been made to the mock, the assert still succeeds.

Sometimes a mock may have several calls made to it, and you are only interested
in asserting about `some' of those calls. You may not even care about the
order. In this case you can pass @code{any_order=True} to @code{assert_has_calls}:

@example
>>> m = MagicMock()
>>> m(1), m.two(2, 3), m.seven(7), m.fifty('50')
(...)
>>> calls = [call.fifty('50'), call(1), call.seven(7)]
>>> m.assert_has_calls(calls, any_order=True)
@end example

@node More complex argument matching,,Tracking order of calls and less verbose call assertions,Further Examples
@anchor{library/unittest mock-examples more-complex-argument-matching}@anchor{4058}
@subsubsection More complex argument matching


Using the same basic concept as @ref{195a,,ANY} we can implement matchers to do more
complex assertions on objects used as arguments to mocks.

Suppose we expect some object to be passed to a mock that by default
compares equal based on object identity (which is the Python default for user
defined classes). To use @ref{19af,,assert_called_with()} we would need to pass
in the exact same object. If we are only interested in some of the attributes
of this object then we can create a matcher that will check these attributes
for us.

You can see in this example how a 'standard' call to @code{assert_called_with} isn't
sufficient:

@example
>>> class Foo:
...     def __init__(self, a, b):
...         self.a, self.b = a, b
...
>>> mock = Mock(return_value=None)
>>> mock(Foo(1, 2))
>>> mock.assert_called_with(Foo(1, 2))
Traceback (most recent call last):
    ...
AssertionError: expected call not found.
Expected: mock(<__main__.Foo object at 0x...>)
Actual: mock(<__main__.Foo object at 0x...>)
@end example

A comparison function for our @code{Foo} class might look something like this:

@example
>>> def compare(self, other):
...     if not type(self) == type(other):
...         return False
...     if self.a != other.a:
...         return False
...     if self.b != other.b:
...         return False
...     return True
...
@end example

And a matcher object that can use comparison functions like this for its
equality operation would look something like this:

@example
>>> class Matcher:
...     def __init__(self, compare, some_obj):
...         self.compare = compare
...         self.some_obj = some_obj
...     def __eq__(self, other):
...         return self.compare(self.some_obj, other)
...
@end example

Putting all this together:

@example
>>> match_foo = Matcher(compare, Foo(1, 2))
>>> mock.assert_called_with(match_foo)
@end example

The @code{Matcher} is instantiated with our compare function and the @code{Foo} object
we want to compare against. In @code{assert_called_with} the @code{Matcher} equality
method will be called, which compares the object the mock was called with
against the one we created our matcher with. If they match then
@code{assert_called_with} passes, and if they don't an @ref{694,,AssertionError} is raised:

@example
>>> match_wrong = Matcher(compare, Foo(3, 4))
>>> mock.assert_called_with(match_wrong)
Traceback (most recent call last):
    ...
AssertionError: Expected: ((<Matcher object at 0x...>,), @{@})
Called with: ((<Foo object at 0x...>,), @{@})
@end example

With a bit of tweaking you could have the comparison function raise the
@ref{694,,AssertionError} directly and provide a more useful failure message.

As of version 1.5, the Python testing library PyHamcrest@footnote{https://pyhamcrest.readthedocs.io/} provides similar functionality,
that may be useful here, in the form of its equality matcher
(hamcrest.library.integration.match_equality@footnote{https://pyhamcrest.readthedocs.io/en/release-1.8/integration/#module-hamcrest.library.integration.match_equality}).

@node test --- Regression tests package for Python,test support --- Utilities for the Python test suite,unittest mock --- getting started,Outils de développement
@anchor{library/test doc}@anchor{4059}@anchor{library/test module-test}@anchor{e1}@anchor{library/test test-regression-tests-package-for-python}@anchor{405a}
@subsection @code{test} --- Regression tests package for Python


@geindex module; test

@cartouche
@quotation Note 
The @ref{e1,,test} package is meant for internal use by Python only. It is
documented for the benefit of the core developers of Python. Any use of
this package outside of Python's standard library is discouraged as code
mentioned here can change or be removed without notice between releases of
Python.
@end quotation
@end cartouche


__________________________________________________________________


The @ref{e1,,test} package contains all regression tests for Python as well as the
modules @ref{e3,,test.support} and @ref{e2,,test.regrtest}.
@ref{e3,,test.support} is used to enhance your tests while
@ref{e2,,test.regrtest} drives the testing suite.

Each module in the @ref{e1,,test} package whose name starts with @code{test_} is a
testing suite for a specific module or feature. All new tests should be written
using the @ref{105,,unittest} or @ref{3a,,doctest} module.  Some older tests are
written using a "traditional" testing style that compares output printed to
@code{sys.stdout}; this style of test is considered deprecated.


@subsubheading Voir aussi



@table @asis

@item Module @ref{105,,unittest}

Writing PyUnit regression tests.

@item Module @ref{3a,,doctest}

Tests embedded in documentation strings.
@end table


@menu
* Writing Unit Tests for the test package:: 
* Running tests using the command-line interface:: 

@end menu

@node Writing Unit Tests for the test package,Running tests using the command-line interface,,test --- Regression tests package for Python
@anchor{library/test writing-tests}@anchor{405b}@anchor{library/test writing-unit-tests-for-the-test-package}@anchor{405c}
@subsubsection Writing Unit Tests for the @code{test} package


It is preferred that tests that use the @ref{105,,unittest} module follow a few
guidelines. One is to name the test module by starting it with @code{test_} and end
it with the name of the module being tested. The test methods in the test module
should start with @code{test_} and end with a description of what the method is
testing. This is needed so that the methods are recognized by the test driver as
test methods. Also, no documentation string for the method should be included. A
comment (such as @code{# Tests function returns only True or False}) should be used
to provide documentation for test methods. This is done because documentation
strings get printed out if they exist and thus what test is being run is not
stated.

A basic boilerplate is often used:

@example
import unittest
from test import support

class MyTestCase1(unittest.TestCase):

    # Only use setUp() and tearDown() if necessary

    def setUp(self):
        ... code to execute in preparation for tests ...

    def tearDown(self):
        ... code to execute to clean up after tests ...

    def test_feature_one(self):
        # Test feature one.
        ... testing code ...

    def test_feature_two(self):
        # Test feature two.
        ... testing code ...

    ... more test methods ...

class MyTestCase2(unittest.TestCase):
    ... same structure as MyTestCase1 ...

... more test classes ...

if __name__ == '__main__':
    unittest.main()
@end example

This code pattern allows the testing suite to be run by @ref{e2,,test.regrtest},
on its own as a script that supports the @ref{105,,unittest} CLI, or via the
@code{python -m unittest} CLI.

The goal for regression testing is to try to break code. This leads to a few
guidelines to be followed:


@itemize *

@item 
The testing suite should exercise all classes, functions, and constants. This
includes not just the external API that is to be presented to the outside
world but also "private" code.

@item 
Whitebox testing (examining the code being tested when the tests are being
written) is preferred. Blackbox testing (testing only the published user
interface) is not complete enough to make sure all boundary and edge cases
are tested.

@item 
Make sure all possible values are tested including invalid ones. This makes
sure that not only all valid values are acceptable but also that improper
values are handled correctly.

@item 
Exhaust as many code paths as possible. Test where branching occurs and thus
tailor input to make sure as many different paths through the code are taken.

@item 
Add an explicit test for any bugs discovered for the tested code. This will
make sure that the error does not crop up again if the code is changed in the
future.

@item 
Make sure to clean up after your tests (such as close and remove all temporary
files).

@item 
If a test is dependent on a specific condition of the operating system then
verify the condition already exists before attempting the test.

@item 
Import as few modules as possible and do it as soon as possible. This
minimizes external dependencies of tests and also minimizes possible anomalous
behavior from side-effects of importing a module.

@item 
Try to maximize code reuse. On occasion, tests will vary by something as small
as what type of input is used. Minimize code duplication by subclassing a
basic test class with a class that specifies the input:

@example
class TestFuncAcceptsSequencesMixin:

    func = mySuperWhammyFunction

    def test_func(self):
        self.func(self.arg)

class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = [1, 2, 3]

class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = 'abc'

class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = (1, 2, 3)
@end example

When using this pattern, remember that all classes that inherit from
@ref{437,,unittest.TestCase} are run as tests.  The @code{TestFuncAcceptsSequencesMixin} class in the example above
does not have any data and so can't be run by itself, thus it does not
inherit from @ref{437,,unittest.TestCase}.
@end itemize


@subsubheading Voir aussi



@table @asis

@item Test Driven Development

A book by Kent Beck on writing tests before code.
@end table


@node Running tests using the command-line interface,,Writing Unit Tests for the test package,test --- Regression tests package for Python
@anchor{library/test module-test regrtest}@anchor{e2}@anchor{library/test regrtest}@anchor{ff2}@anchor{library/test running-tests-using-the-command-line-interface}@anchor{405d}
@subsubsection Running tests using the command-line interface


@geindex module; test.regrtest

The @ref{e1,,test} package can be run as a script to drive Python's regression
test suite, thanks to the @ref{5cb,,-m} option: @code{python -m test}. Under
the hood, it uses @ref{e2,,test.regrtest}; the call @code{python -m
test.regrtest} used in previous Python versions still works.  Running the
script by itself automatically starts running all regression tests in the
@ref{e1,,test} package. It does this by finding all modules in the package whose
name starts with @code{test_}, importing them, and executing the function
@code{test_main()} if present or loading the tests via
unittest.TestLoader.loadTestsFromModule if @code{test_main} does not exist.  The
names of tests to execute may also be passed to the script. Specifying a single
regression test (@code{python -m test test_spam}) will minimize output and
only print whether the test passed or failed.

Running @ref{e1,,test} directly allows what resources are available for
tests to use to be set. You do this by using the @code{-u} command-line
option. Specifying @code{all} as the value for the @code{-u} option enables all
possible resources: @code{python -m test -uall}.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
@code{all}. The command @code{python -m test -uall,-audio,-largefile}
will run @ref{e1,,test} with all resources except the @code{audio} and
@code{largefile} resources. For a list of all resources and more command-line
options, run @code{python -m test -h}.

Some other ways to execute the regression tests depend on what platform the
tests are being executed on. On Unix, you can run @code{make test} at the
top-level directory where Python was built. On Windows,
executing @code{rt.bat} from your @code{PCbuild} directory will run all
regression tests.

@node test support --- Utilities for the Python test suite,test support socket_helper --- Utilities for socket tests,test --- Regression tests package for Python,Outils de développement
@anchor{library/test module-test support}@anchor{e3}@anchor{library/test test-support-utilities-for-the-python-test-suite}@anchor{405e}
@subsection @code{test.support} --- Utilities for the Python test suite


@geindex module; test.support

The @ref{e3,,test.support} module provides support for Python's regression
test suite.

@cartouche
@quotation Note 
@ref{e3,,test.support} is not a public module.  It is documented here to help
Python developers write tests.  The API of this module is subject to change
without backwards compatibility concerns between releases.
@end quotation
@end cartouche

This module defines the following exceptions:

@geindex TestFailed
@anchor{library/test test support TestFailed}@anchor{405f}
@deffn {Exception} test.support.TestFailed

Exception to be raised when a test fails. This is deprecated in favor of
@ref{105,,unittest}-based tests and @ref{437,,unittest.TestCase}'s assertion
methods.
@end deffn

@geindex ResourceDenied
@anchor{library/test test support ResourceDenied}@anchor{4060}
@deffn {Exception} test.support.ResourceDenied

Subclass of @ref{fcf,,unittest.SkipTest}. Raised when a resource (such as a
network connection) is not available. Raised by the @ref{4061,,requires()}
function.
@end deffn

The @ref{e3,,test.support} module defines the following constants:

@geindex verbose (dans le module test.support)
@anchor{library/test test support verbose}@anchor{4062}
@deffn {Données} test.support.verbose

@code{True} when verbose output is enabled. Should be checked when more
detailed information is desired about a running test. `verbose' is set by
@ref{e2,,test.regrtest}.
@end deffn

@geindex is_jython (dans le module test.support)
@anchor{library/test test support is_jython}@anchor{4063}
@deffn {Données} test.support.is_jython

@code{True} if the running interpreter is Jython.
@end deffn

@geindex is_android (dans le module test.support)
@anchor{library/test test support is_android}@anchor{4064}
@deffn {Données} test.support.is_android

@code{True} if the system is Android.
@end deffn

@geindex unix_shell (dans le module test.support)
@anchor{library/test test support unix_shell}@anchor{4065}
@deffn {Données} test.support.unix_shell

Path for shell if not on Windows; otherwise @code{None}.
@end deffn

@geindex LOOPBACK_TIMEOUT (dans le module test.support)
@anchor{library/test test support LOOPBACK_TIMEOUT}@anchor{1942}
@deffn {Données} test.support.LOOPBACK_TIMEOUT

Timeout in seconds for tests using a network server listening on the network
local loopback interface like @code{127.0.0.1}.

The timeout is long enough to prevent test failure: it takes into account
that the client and the server can run in different threads or even
different processes.

The timeout should be long enough for @ref{d90,,connect()},
@ref{d91,,recv()} and @ref{d94,,send()} methods of
@ref{d8e,,socket.socket}.

Its default value is 5 seconds.

See also @ref{1943,,INTERNET_TIMEOUT}.
@end deffn

@geindex INTERNET_TIMEOUT (dans le module test.support)
@anchor{library/test test support INTERNET_TIMEOUT}@anchor{1943}
@deffn {Données} test.support.INTERNET_TIMEOUT

Timeout in seconds for network requests going to the internet.

The timeout is short enough to prevent a test to wait for too long if the
internet request is blocked for whatever reason.

Usually, a timeout using @ref{1943,,INTERNET_TIMEOUT} should not mark a test as
failed, but skip the test instead: see
@ref{4066,,transient_internet()}.

Its default value is 1 minute.

See also @ref{1942,,LOOPBACK_TIMEOUT}.
@end deffn

@geindex SHORT_TIMEOUT (dans le module test.support)
@anchor{library/test test support SHORT_TIMEOUT}@anchor{183c}
@deffn {Données} test.support.SHORT_TIMEOUT

Timeout in seconds to mark a test as failed if the test takes "too long".

The timeout value depends on the regrtest @code{--timeout} command line option.

If a test using @ref{183c,,SHORT_TIMEOUT} starts to fail randomly on slow
buildbots, use @ref{1944,,LONG_TIMEOUT} instead.

Its default value is 30 seconds.
@end deffn

@geindex LONG_TIMEOUT (dans le module test.support)
@anchor{library/test test support LONG_TIMEOUT}@anchor{1944}
@deffn {Données} test.support.LONG_TIMEOUT

Timeout in seconds to detect when a test hangs.

It is long enough to reduce the risk of test failure on the slowest Python
buildbots. It should not be used to mark a test as failed if the test takes
"too long".  The timeout value depends on the regrtest @code{--timeout} command
line option.

Its default value is 5 minutes.

See also @ref{1942,,LOOPBACK_TIMEOUT}, @ref{1943,,INTERNET_TIMEOUT} and
@ref{183c,,SHORT_TIMEOUT}.
@end deffn

@geindex PGO (dans le module test.support)
@anchor{library/test test support PGO}@anchor{4067}
@deffn {Données} test.support.PGO

Set when tests can be skipped when they are not useful for PGO.
@end deffn

@geindex PIPE_MAX_SIZE (dans le module test.support)
@anchor{library/test test support PIPE_MAX_SIZE}@anchor{4068}
@deffn {Données} test.support.PIPE_MAX_SIZE

A constant that is likely larger than the underlying OS pipe buffer size,
to make writes blocking.
@end deffn

@geindex Py_DEBUG (dans le module test.support)
@anchor{library/test test support Py_DEBUG}@anchor{4069}
@deffn {Données} test.support.Py_DEBUG

@code{True} if Python was built with the @ref{406a,,Py_DEBUG} macro
defined, that is, if
Python was @ref{1f6,,built in debug mode}.


Ajouté dans la version 3.12.

@end deffn

@geindex SOCK_MAX_SIZE (dans le module test.support)
@anchor{library/test test support SOCK_MAX_SIZE}@anchor{406b}
@deffn {Données} test.support.SOCK_MAX_SIZE

A constant that is likely larger than the underlying OS socket buffer size,
to make writes blocking.
@end deffn

@geindex TEST_SUPPORT_DIR (dans le module test.support)
@anchor{library/test test support TEST_SUPPORT_DIR}@anchor{406c}
@deffn {Données} test.support.TEST_SUPPORT_DIR

Set to the top level directory that contains @ref{e3,,test.support}.
@end deffn

@geindex TEST_HOME_DIR (dans le module test.support)
@anchor{library/test test support TEST_HOME_DIR}@anchor{406d}
@deffn {Données} test.support.TEST_HOME_DIR

Set to the top level directory for the test package.
@end deffn

@geindex TEST_DATA_DIR (dans le module test.support)
@anchor{library/test test support TEST_DATA_DIR}@anchor{406e}
@deffn {Données} test.support.TEST_DATA_DIR

Set to the @code{data} directory within the test package.
@end deffn

@geindex MAX_Py_ssize_t (dans le module test.support)
@anchor{library/test test support MAX_Py_ssize_t}@anchor{406f}
@deffn {Données} test.support.MAX_Py_ssize_t

Set to @ref{11a2,,sys.maxsize} for big memory tests.
@end deffn

@geindex max_memuse (dans le module test.support)
@anchor{library/test test support max_memuse}@anchor{4070}
@deffn {Données} test.support.max_memuse

Set by @ref{4071,,set_memlimit()} as the memory limit for big memory tests.
Limited by @ref{406f,,MAX_Py_ssize_t}.
@end deffn

@geindex real_max_memuse (dans le module test.support)
@anchor{library/test test support real_max_memuse}@anchor{4072}
@deffn {Données} test.support.real_max_memuse

Set by @ref{4071,,set_memlimit()} as the memory limit for big memory tests.  Not
limited by @ref{406f,,MAX_Py_ssize_t}.
@end deffn

@geindex MISSING_C_DOCSTRINGS (dans le module test.support)
@anchor{library/test test support MISSING_C_DOCSTRINGS}@anchor{4073}
@deffn {Données} test.support.MISSING_C_DOCSTRINGS

Set to @code{True} if Python is built without docstrings (the
@code{WITH_DOC_STRINGS} macro is not defined).
See the @ref{1d3b,,configure --without-doc-strings} option.

See also the @ref{4074,,HAVE_DOCSTRINGS} variable.
@end deffn

@geindex HAVE_DOCSTRINGS (dans le module test.support)
@anchor{library/test test support HAVE_DOCSTRINGS}@anchor{4074}
@deffn {Données} test.support.HAVE_DOCSTRINGS

Set to @code{True} if function docstrings are available.
See the @ref{da2,,python -OO} option, which strips docstrings of functions implemented in Python.

See also the @ref{4073,,MISSING_C_DOCSTRINGS} variable.
@end deffn

@geindex TEST_HTTP_URL (dans le module test.support)
@anchor{library/test test support TEST_HTTP_URL}@anchor{4075}
@deffn {Données} test.support.TEST_HTTP_URL

Define the URL of a dedicated HTTP server for the network tests.
@end deffn

@geindex ALWAYS_EQ (dans le module test.support)
@anchor{library/test test support ALWAYS_EQ}@anchor{4076}
@deffn {Données} test.support.ALWAYS_EQ

Object that is equal to anything.  Used to test mixed type comparison.
@end deffn

@geindex NEVER_EQ (dans le module test.support)
@anchor{library/test test support NEVER_EQ}@anchor{4077}
@deffn {Données} test.support.NEVER_EQ

Object that is not equal to anything (even to @ref{4076,,ALWAYS_EQ}).
Used to test mixed type comparison.
@end deffn

@geindex LARGEST (dans le module test.support)
@anchor{library/test test support LARGEST}@anchor{4078}
@deffn {Données} test.support.LARGEST

Object that is greater than anything (except itself).
Used to test mixed type comparison.
@end deffn

@geindex SMALLEST (dans le module test.support)
@anchor{library/test test support SMALLEST}@anchor{4079}
@deffn {Données} test.support.SMALLEST

Object that is less than anything (except itself).
Used to test mixed type comparison.
@end deffn

The @ref{e3,,test.support} module defines the following functions:

@geindex busy_retry() (dans le module test.support)
@anchor{library/test test support busy_retry}@anchor{407a}
@deffn {Fonction} test.support.busy_retry (timeout, err_msg=None, /, *, error=True)

Run the loop body until @code{break} stops the loop.

After `timeout' seconds, raise an @ref{694,,AssertionError} if `error' is true,
or just stop the loop if `error' is false.

Example:

@example
for _ in support.busy_retry(support.SHORT_TIMEOUT):
    if check():
        break
@end example

Example of error=False usage:

@example
for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')
@end example
@end deffn

@geindex sleeping_retry() (dans le module test.support)
@anchor{library/test test support sleeping_retry}@anchor{407b}
@deffn {Fonction} test.support.sleeping_retry (timeout, err_msg=None, /, *, init_delay=0.010, max_delay=1.0, error=True)

Wait strategy that applies exponential backoff.

Run the loop body until @code{break} stops the loop. Sleep at each loop
iteration, but not at the first iteration. The sleep delay is doubled at
each iteration (up to `max_delay' seconds).

See @ref{407a,,busy_retry()} documentation for the parameters usage.

Example raising an exception after SHORT_TIMEOUT seconds:

@example
for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
    if check():
        break
@end example

Example of error=False usage:

@example
for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
    if check():
        break
else:
    raise RuntimeError('my custom error')
@end example
@end deffn

@geindex is_resource_enabled() (dans le module test.support)
@anchor{library/test test support is_resource_enabled}@anchor{407c}
@deffn {Fonction} test.support.is_resource_enabled (resource)

Return @code{True} if `resource' is enabled and available. The list of
available resources is only set when @ref{e2,,test.regrtest} is executing the
tests.
@end deffn

@geindex python_is_optimized() (dans le module test.support)
@anchor{library/test test support python_is_optimized}@anchor{407d}
@deffn {Fonction} test.support.python_is_optimized ()

Return @code{True} if Python was not built with @code{-O0} or @code{-Og}.
@end deffn

@geindex with_pymalloc() (dans le module test.support)
@anchor{library/test test support with_pymalloc}@anchor{407e}
@deffn {Fonction} test.support.with_pymalloc ()

Return @code{_testcapi.WITH_PYMALLOC}.
@end deffn

@geindex requires() (dans le module test.support)
@anchor{library/test test support requires}@anchor{4061}
@deffn {Fonction} test.support.requires (resource, msg=None)

Raise @ref{4060,,ResourceDenied} if `resource' is not available. `msg' is the
argument to @ref{4060,,ResourceDenied} if it is raised. Always returns
@code{True} if called by a function whose @code{__name__} is @code{'__main__'}.
Used when tests are executed by @ref{e2,,test.regrtest}.
@end deffn

@geindex sortdict() (dans le module test.support)
@anchor{library/test test support sortdict}@anchor{407f}
@deffn {Fonction} test.support.sortdict (dict)

Return a repr of `dict' with keys sorted.
@end deffn

@geindex findfile() (dans le module test.support)
@anchor{library/test test support findfile}@anchor{4080}
@deffn {Fonction} test.support.findfile (filename, subdir=None)

Return the path to the file named `filename'. If no match is found
`filename' is returned. This does not equal a failure since it could be the
path to the file.

Setting `subdir' indicates a relative path to use to find the file
rather than looking directly in the path directories.
@end deffn

@geindex get_pagesize() (dans le module test.support)
@anchor{library/test test support get_pagesize}@anchor{4081}
@deffn {Fonction} test.support.get_pagesize ()

Get size of a page in bytes.


Ajouté dans la version 3.12.

@end deffn

@geindex setswitchinterval() (dans le module test.support)
@anchor{library/test test support setswitchinterval}@anchor{4082}
@deffn {Fonction} test.support.setswitchinterval (interval)

Set the @ref{937,,sys.setswitchinterval()} to the given `interval'.  Defines
a minimum interval for Android systems to prevent the system from hanging.
@end deffn

@geindex check_impl_detail() (dans le module test.support)
@anchor{library/test test support check_impl_detail}@anchor{4083}
@deffn {Fonction} test.support.check_impl_detail (**guards)

Use this check to guard CPython's implementation-specific tests or to
run them only on the implementations guarded by the arguments.  This
function returns @code{True} or @code{False} depending on the host platform.
Example usage:

@example
check_impl_detail()               # Only on CPython (default).
check_impl_detail(jython=True)    # Only on Jython.
check_impl_detail(cpython=False)  # Everywhere except CPython.
@end example
@end deffn

@geindex set_memlimit() (dans le module test.support)
@anchor{library/test test support set_memlimit}@anchor{4071}
@deffn {Fonction} test.support.set_memlimit (limit)

Set the values for @ref{4070,,max_memuse} and @ref{4072,,real_max_memuse} for big
memory tests.
@end deffn

@geindex record_original_stdout() (dans le module test.support)
@anchor{library/test test support record_original_stdout}@anchor{4084}
@deffn {Fonction} test.support.record_original_stdout (stdout)

Store the value from `stdout'.  It is meant to hold the stdout at the
time the regrtest began.
@end deffn

@geindex get_original_stdout() (dans le module test.support)
@anchor{library/test test support get_original_stdout}@anchor{4085}
@deffn {Fonction} test.support.get_original_stdout ()

Return the original stdout set by @ref{4084,,record_original_stdout()} or
@code{sys.stdout} if it's not set.
@end deffn

@geindex args_from_interpreter_flags() (dans le module test.support)
@anchor{library/test test support args_from_interpreter_flags}@anchor{4086}
@deffn {Fonction} test.support.args_from_interpreter_flags ()

Return a list of command line arguments reproducing the current settings
in @code{sys.flags} and @code{sys.warnoptions}.
@end deffn

@geindex optim_args_from_interpreter_flags() (dans le module test.support)
@anchor{library/test test support optim_args_from_interpreter_flags}@anchor{4087}
@deffn {Fonction} test.support.optim_args_from_interpreter_flags ()

Return a list of command line arguments reproducing the current
optimization settings in @code{sys.flags}.
@end deffn

@geindex captured_stdin() (dans le module test.support)
@geindex captured_stdout() (dans le module test.support)
@geindex captured_stderr() (dans le module test.support)
@anchor{library/test test support captured_stdin}@anchor{4088}
@deffn {Fonction} test.support.captured_stdin ()
@anchor{library/test test support captured_stdout}@anchor{4089}
@deffnx {Fonction} test.support.captured_stdout ()
@anchor{library/test test support captured_stderr}@anchor{1984}
@deffnx {Fonction} test.support.captured_stderr ()

A context managers that temporarily replaces the named stream with
@ref{f12,,io.StringIO} object.

Example use with output streams:

@example
with captured_stdout() as stdout, captured_stderr() as stderr:
    print("hello")
    print("error", file=sys.stderr)
assert stdout.getvalue() == "hello\n"
assert stderr.getvalue() == "error\n"
@end example

Example use with input stream:

@example
with captured_stdin() as stdin:
    stdin.write('hello\n')
    stdin.seek(0)
    # call test code that consumes from sys.stdin
    captured = input()
self.assertEqual(captured, "hello")
@end example
@end deffn

@geindex disable_faulthandler() (dans le module test.support)
@anchor{library/test test support disable_faulthandler}@anchor{408a}
@deffn {Fonction} test.support.disable_faulthandler ()

A context manager that temporary disables @ref{57,,faulthandler}.
@end deffn

@geindex gc_collect() (dans le module test.support)
@anchor{library/test test support gc_collect}@anchor{408b}
@deffn {Fonction} test.support.gc_collect ()

Force as many objects as possible to be collected.  This is needed because
timely deallocation is not guaranteed by the garbage collector.  This means
that @code{__del__} methods may be called later than expected and weakrefs
may remain alive for longer than expected.
@end deffn

@geindex disable_gc() (dans le module test.support)
@anchor{library/test test support disable_gc}@anchor{408c}
@deffn {Fonction} test.support.disable_gc ()

A context manager that disables the garbage collector on entry. On
exit, the garbage collector is restored to its prior state.
@end deffn

@geindex swap_attr() (dans le module test.support)
@anchor{library/test test support swap_attr}@anchor{408d}
@deffn {Fonction} test.support.swap_attr (obj, attr, new_val)

Context manager to swap out an attribute with a new object.

Utilisation :

@example
with swap_attr(obj, "attr", 5):
    ...
@end example

This will set @code{obj.attr} to 5 for the duration of the @code{with} block,
restoring the old value at the end of the block.  If @code{attr} doesn't
exist on @code{obj}, it will be created and then deleted at the end of the
block.

The old value (or @code{None} if it doesn't exist) will be assigned to the
target of the "as" clause, if there is one.
@end deffn

@geindex swap_item() (dans le module test.support)
@anchor{library/test test support swap_item}@anchor{408e}
@deffn {Fonction} test.support.swap_item (obj, attr, new_val)

Context manager to swap out an item with a new object.

Utilisation :

@example
with swap_item(obj, "item", 5):
    ...
@end example

This will set @code{obj["item"]} to 5 for the duration of the @code{with} block,
restoring the old value at the end of the block. If @code{item} doesn't
exist on @code{obj}, it will be created and then deleted at the end of the
block.

The old value (or @code{None} if it doesn't exist) will be assigned to the
target of the "as" clause, if there is one.
@end deffn

@geindex flush_std_streams() (dans le module test.support)
@anchor{library/test test support flush_std_streams}@anchor{408f}
@deffn {Fonction} test.support.flush_std_streams ()

Call the @code{flush()} method on @ref{ac4,,sys.stdout} and then on
@ref{926,,sys.stderr}. It can be used to make sure that the logs order is
consistent before writing into stderr.


Ajouté dans la version 3.11.

@end deffn

@geindex print_warning() (dans le module test.support)
@anchor{library/test test support print_warning}@anchor{4090}
@deffn {Fonction} test.support.print_warning (msg)

Print a warning into @ref{4091,,sys.__stderr__}. Format the message as:
@code{f"Warning -- @{msg@}"}. If `msg' is made of multiple lines, add
@code{"Warning -- "} prefix to each line.


Ajouté dans la version 3.9.

@end deffn

@geindex wait_process() (dans le module test.support)
@anchor{library/test test support wait_process}@anchor{1902}
@deffn {Fonction} test.support.wait_process (pid, *, exitcode, timeout=None)

Wait until process `pid' completes and check that the process exit code is
`exitcode'.

Raise an @ref{694,,AssertionError} if the process exit code is not equal to
`exitcode'.

If the process runs longer than `timeout' seconds (@ref{183c,,SHORT_TIMEOUT} by
default), kill the process and raise an @ref{694,,AssertionError}. The timeout
feature is not available on Windows.


Ajouté dans la version 3.9.

@end deffn

@geindex calcobjsize() (dans le module test.support)
@anchor{library/test test support calcobjsize}@anchor{4092}
@deffn {Fonction} test.support.calcobjsize (fmt)

Return the size of the @ref{32f,,PyObject} whose structure members are
defined by `fmt'. The returned value includes the size of the Python object header and alignment.
@end deffn

@geindex calcvobjsize() (dans le module test.support)
@anchor{library/test test support calcvobjsize}@anchor{4093}
@deffn {Fonction} test.support.calcvobjsize (fmt)

Return the size of the @ref{4094,,PyVarObject} whose structure members are
defined by `fmt'. The returned value includes the size of the Python object header and alignment.
@end deffn

@geindex checksizeof() (dans le module test.support)
@anchor{library/test test support checksizeof}@anchor{4095}
@deffn {Fonction} test.support.checksizeof (test, o, size)

For testcase `test', assert that the @code{sys.getsizeof} for `o' plus the GC
header size equals `size'.
@end deffn

@geindex anticipate_failure() (dans le module test.support)
@anchor{library/test test support anticipate_failure}@anchor{4096}
@deffn {Fonction} @@test.support.anticipate_failure (condition)

A decorator to conditionally mark tests with
@ref{3fac,,unittest.expectedFailure()}. Any use of this decorator should
have an associated comment identifying the relevant tracker issue.
@end deffn

@geindex system_must_validate_cert() (dans le module test.support)
@anchor{library/test test support system_must_validate_cert}@anchor{4097}
@deffn {Fonction} test.support.system_must_validate_cert (f)

A decorator that skips the decorated test on TLS certification validation failures.
@end deffn

@geindex run_with_locale() (dans le module test.support)
@anchor{library/test test support run_with_locale}@anchor{4098}
@deffn {Fonction} @@test.support.run_with_locale (catstr, *locales)

A decorator for running a function in a different locale, correctly
resetting it after it has finished.  `catstr' is the locale category as
a string (for example @code{"LC_ALL"}).  The `locales' passed will be tried
sequentially, and the first valid locale will be used.
@end deffn

@geindex run_with_tz() (dans le module test.support)
@anchor{library/test test support run_with_tz}@anchor{4099}
@deffn {Fonction} @@test.support.run_with_tz (tz)

A decorator for running a function in a specific timezone, correctly
resetting it after it has finished.
@end deffn

@geindex requires_freebsd_version() (dans le module test.support)
@anchor{library/test test support requires_freebsd_version}@anchor{409a}
@deffn {Fonction} @@test.support.requires_freebsd_version (*min_version)

Decorator for the minimum version when running test on FreeBSD.  If the
FreeBSD version is less than the minimum, the test is skipped.
@end deffn

@geindex requires_linux_version() (dans le module test.support)
@anchor{library/test test support requires_linux_version}@anchor{409b}
@deffn {Fonction} @@test.support.requires_linux_version (*min_version)

Decorator for the minimum version when running test on Linux.  If the
Linux version is less than the minimum, the test is skipped.
@end deffn

@geindex requires_mac_version() (dans le module test.support)
@anchor{library/test test support requires_mac_version}@anchor{409c}
@deffn {Fonction} @@test.support.requires_mac_version (*min_version)

Decorator for the minimum version when running test on macOS.  If the
macOS version is less than the minimum, the test is skipped.
@end deffn

@geindex requires_gil_enabled() (dans le module test.support)
@anchor{library/test test support requires_gil_enabled}@anchor{409d}
@deffn {Fonction} @@test.support.requires_gil_enabled

Decorator for skipping tests on the free-threaded build.  If the
@ref{158,,GIL} is disabled, the test is skipped.
@end deffn

@geindex requires_IEEE_754() (dans le module test.support)
@anchor{library/test test support requires_IEEE_754}@anchor{409e}
@deffn {Fonction} @@test.support.requires_IEEE_754

Decorator for skipping tests on non-IEEE 754 platforms.
@end deffn

@geindex requires_zlib() (dans le module test.support)
@anchor{library/test test support requires_zlib}@anchor{409f}
@deffn {Fonction} @@test.support.requires_zlib

Decorator for skipping tests if @ref{132,,zlib} doesn't exist.
@end deffn

@geindex requires_gzip() (dans le module test.support)
@anchor{library/test test support requires_gzip}@anchor{40a0}
@deffn {Fonction} @@test.support.requires_gzip

Decorator for skipping tests if @ref{66,,gzip} doesn't exist.
@end deffn

@geindex requires_bz2() (dans le module test.support)
@anchor{library/test test support requires_bz2}@anchor{40a1}
@deffn {Fonction} @@test.support.requires_bz2

Decorator for skipping tests if @ref{13,,bz2} doesn't exist.
@end deffn

@geindex requires_lzma() (dans le module test.support)
@anchor{library/test test support requires_lzma}@anchor{40a2}
@deffn {Fonction} @@test.support.requires_lzma

Decorator for skipping tests if @ref{89,,lzma} doesn't exist.
@end deffn

@geindex requires_resource() (dans le module test.support)
@anchor{library/test test support requires_resource}@anchor{40a3}
@deffn {Fonction} @@test.support.requires_resource (resource)

Decorator for skipping tests if `resource' is not available.
@end deffn

@geindex requires_docstrings() (dans le module test.support)
@anchor{library/test test support requires_docstrings}@anchor{40a4}
@deffn {Fonction} @@test.support.requires_docstrings

Decorator for only running the test if @ref{4074,,HAVE_DOCSTRINGS}.
@end deffn

@geindex requires_limited_api() (dans le module test.support)
@anchor{library/test test support requires_limited_api}@anchor{40a5}
@deffn {Fonction} @@test.support.requires_limited_api

Decorator for only running the test if @ref{38c,,Limited C API}
is available.
@end deffn

@geindex cpython_only() (dans le module test.support)
@anchor{library/test test support cpython_only}@anchor{40a6}
@deffn {Fonction} @@test.support.cpython_only

Decorator for tests only applicable to CPython.
@end deffn

@geindex impl_detail() (dans le module test.support)
@anchor{library/test test support impl_detail}@anchor{40a7}
@deffn {Fonction} @@test.support.impl_detail (msg=None, **guards)

Decorator for invoking @ref{4083,,check_impl_detail()} on `guards'.  If that
returns @code{False}, then uses `msg' as the reason for skipping the test.
@end deffn

@geindex no_tracing() (dans le module test.support)
@anchor{library/test test support no_tracing}@anchor{40a8}
@deffn {Fonction} @@test.support.no_tracing

Decorator to temporarily turn off tracing for the duration of the test.
@end deffn

@geindex refcount_test() (dans le module test.support)
@anchor{library/test test support refcount_test}@anchor{40a9}
@deffn {Fonction} @@test.support.refcount_test

Decorator for tests which involve reference counting.  The decorator does
not run the test if it is not run by CPython.  Any trace function is unset
for the duration of the test to prevent unexpected refcounts caused by
the trace function.
@end deffn

@geindex bigmemtest() (dans le module test.support)
@anchor{library/test test support bigmemtest}@anchor{40aa}
@deffn {Fonction} @@test.support.bigmemtest (size, memuse, dry_run=True)

Decorator for bigmem tests.

`size' is a requested size for the test (in arbitrary, test-interpreted
units.)  `memuse' is the number of bytes per unit for the test, or a good
estimate of it.  For example, a test that needs two byte buffers, of 4 GiB
each, could be decorated with @code{@@bigmemtest(size=_4G, memuse=2)}.

The `size' argument is normally passed to the decorated test method as an
extra argument.  If `dry_run' is @code{True}, the value passed to the test
method may be less than the requested value.  If `dry_run' is @code{False}, it
means the test doesn't support dummy runs when @code{-M} is not specified.
@end deffn

@geindex bigaddrspacetest() (dans le module test.support)
@anchor{library/test test support bigaddrspacetest}@anchor{40ab}
@deffn {Fonction} @@test.support.bigaddrspacetest

Decorator for tests that fill the address space.
@end deffn

@geindex check_syntax_error() (dans le module test.support)
@anchor{library/test test support check_syntax_error}@anchor{40ac}
@deffn {Fonction} test.support.check_syntax_error (testcase, statement, errtext='@w{'}, *, lineno=None, offset=None)

Test for syntax errors in `statement' by attempting to compile `statement'.
`testcase' is the @ref{105,,unittest} instance for the test.  `errtext' is the
regular expression which should match the string representation of the
raised @ref{18b,,SyntaxError}.  If `lineno' is not @code{None}, compares to
the line of the exception.  If `offset' is not @code{None}, compares to
the offset of the exception.
@end deffn

@geindex open_urlresource() (dans le module test.support)
@anchor{library/test test support open_urlresource}@anchor{40ad}
@deffn {Fonction} test.support.open_urlresource (url, *args, **kw)

Open `url'.  If open fails, raises @ref{405f,,TestFailed}.
@end deffn

@geindex reap_children() (dans le module test.support)
@anchor{library/test test support reap_children}@anchor{40ae}
@deffn {Fonction} test.support.reap_children ()

Use this at the end of @code{test_main} whenever sub-processes are started.
This will help ensure that no extra children (zombies) stick around to
hog resources and create problems when looking for refleaks.
@end deffn

@geindex get_attribute() (dans le module test.support)
@anchor{library/test test support get_attribute}@anchor{40af}
@deffn {Fonction} test.support.get_attribute (obj, name)

Get an attribute, raising @ref{fcf,,unittest.SkipTest} if @ref{343,,AttributeError}
is raised.
@end deffn

@geindex catch_unraisable_exception() (dans le module test.support)
@anchor{library/test test support catch_unraisable_exception}@anchor{1966}
@deffn {Fonction} test.support.catch_unraisable_exception ()

Context manager catching unraisable exception using
@ref{1f4,,sys.unraisablehook()}.

Storing the exception value (@code{cm.unraisable.exc_value}) creates a
reference cycle. The reference cycle is broken explicitly when the context
manager exits.

Storing the object (@code{cm.unraisable.object}) can resurrect it if it is set
to an object which is being finalized. Exiting the context manager clears
the stored object.

Utilisation :

@example
with support.catch_unraisable_exception() as cm:
    # code creating an "unraisable exception"
    ...

    # check the unraisable exception: use cm.unraisable
    ...

# cm.unraisable attribute no longer exists at this point
# (to break a reference cycle)
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex load_package_tests() (dans le module test.support)
@anchor{library/test test support load_package_tests}@anchor{40b0}
@deffn {Fonction} test.support.load_package_tests (pkg_dir, loader, standard_tests, pattern)

Generic implementation of the @ref{105,,unittest} @code{load_tests} protocol for
use in test packages.  `pkg_dir' is the root directory of the package;
`loader', `standard_tests', and `pattern' are the arguments expected by
@code{load_tests}.  In simple cases, the test package's @code{__init__.py}
can be the following:

@example
import os
from test.support import load_package_tests

def load_tests(*args):
    return load_package_tests(os.path.dirname(__file__), *args)
@end example
@end deffn

@geindex detect_api_mismatch() (dans le module test.support)
@anchor{library/test test support detect_api_mismatch}@anchor{40b1}
@deffn {Fonction} test.support.detect_api_mismatch (ref_api, other_api, *, ignore=())

Returns the set of attributes, functions or methods of `ref_api' not
found on `other_api', except for a defined list of items to be
ignored in this check specified in `ignore'.

By default this skips private attributes beginning with '_' but
includes all magic methods, i.e. those starting and ending in '__'.


Ajouté dans la version 3.5.

@end deffn

@geindex patch() (dans le module test.support)
@anchor{library/test test support patch}@anchor{40b2}
@deffn {Fonction} test.support.patch (test_instance, object_to_patch, attr_name, new_value)

Override `object_to_patch.attr_name' with `new_value'.  Also add
cleanup procedure to `test_instance' to restore `object_to_patch' for
`attr_name'.  The `attr_name' should be a valid attribute for
`object_to_patch'.
@end deffn

@geindex run_in_subinterp() (dans le module test.support)
@anchor{library/test test support run_in_subinterp}@anchor{40b3}
@deffn {Fonction} test.support.run_in_subinterp (code)

Run `code' in subinterpreter.  Raise @ref{fcf,,unittest.SkipTest} if
@ref{fe,,tracemalloc} is enabled.
@end deffn

@geindex check_free_after_iterating() (dans le module test.support)
@anchor{library/test test support check_free_after_iterating}@anchor{40b4}
@deffn {Fonction} test.support.check_free_after_iterating (test, iter, cls, args=())

Assert instances of `cls' are deallocated after iterating.
@end deffn

@geindex missing_compiler_executable() (dans le module test.support)
@anchor{library/test test support missing_compiler_executable}@anchor{40b5}
@deffn {Fonction} test.support.missing_compiler_executable (cmd_names=[])

Check for the existence of the compiler executables whose names are listed
in `cmd_names' or all the compiler executables when `cmd_names' is empty
and return the first missing executable or @code{None} when none is found
missing.
@end deffn

@geindex check__all__() (dans le module test.support)
@anchor{library/test test support check__all__}@anchor{18d9}
@deffn {Fonction} test.support.check__all__ (test_case, module, name_of_module=None, extra=(), not_exported=())

Assert that the @code{__all__} variable of `module' contains all public names.

The module's public names (its API) are detected automatically
based on whether they match the public name convention and were defined in
`module'.

The `name_of_module' argument can specify (as a string or tuple thereof) what
module(s) an API could be defined in order to be detected as a public
API. One case for this is when `module' imports part of its public API from
other modules, possibly a C backend (like @code{csv} and its @code{_csv}).

The `extra' argument can be a set of names that wouldn't otherwise be automatically
detected as "public", like objects without a proper @ref{21ff,,__module__}
attribute. If provided, it will be added to the automatically detected ones.

The `not_exported' argument can be a set of names that must not be treated
as part of the public API even though their names indicate otherwise.

Example use:

@example
import bar
import foo
import unittest
from test import support

class MiscTestCase(unittest.TestCase):
    def test__all__(self):
        support.check__all__(self, foo)

class OtherTestCase(unittest.TestCase):
    def test__all__(self):
        extra = @{'BAR_CONST', 'FOO_CONST'@}
        not_exported = @{'baz'@}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, not_exported=not_exported)
@end example


Ajouté dans la version 3.6.

@end deffn

@geindex skip_if_broken_multiprocessing_synchronize() (dans le module test.support)
@anchor{library/test test support skip_if_broken_multiprocessing_synchronize}@anchor{18da}
@deffn {Fonction} test.support.skip_if_broken_multiprocessing_synchronize ()

Skip tests if the @code{multiprocessing.synchronize} module is missing, if
there is no available semaphore implementation, or if creating a lock raises
an @ref{40d,,OSError}.


Ajouté dans la version 3.10.

@end deffn

@geindex check_disallow_instantiation() (dans le module test.support)
@anchor{library/test test support check_disallow_instantiation}@anchor{40b6}
@deffn {Fonction} test.support.check_disallow_instantiation (test_case, tp, *args, **kwds)

Assert that type `tp' cannot be instantiated using `args' and `kwds'.


Ajouté dans la version 3.10.

@end deffn

@geindex adjust_int_max_str_digits() (dans le module test.support)
@anchor{library/test test support adjust_int_max_str_digits}@anchor{40b7}
@deffn {Fonction} test.support.adjust_int_max_str_digits (max_digits)

This function returns a context manager that will change the global
@ref{174c,,sys.set_int_max_str_digits()} setting for the duration of the
context to allow execution of test code that needs a different limit
on the number of digits when converting between an integer and string.


Ajouté dans la version 3.11.

@end deffn

The @ref{e3,,test.support} module defines the following classes:

@geindex SuppressCrashReport (classe dans test.support)
@anchor{library/test test support SuppressCrashReport}@anchor{40b8}
@deffn {Classe} test.support.SuppressCrashReport

A context manager used to try to prevent crash dialog popups on tests that
are expected to crash a subprocess.

On Windows, it disables Windows Error Reporting dialogs using
SetErrorMode@footnote{https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx}.

On UNIX, @ref{40b9,,resource.setrlimit()} is used to set
@ref{40ba,,resource.RLIMIT_CORE}'s soft limit to 0 to prevent coredump file
creation.

On both platforms, the old value is restored by @ref{12de,,__exit__()}.
@end deffn

@geindex SaveSignals (classe dans test.support)
@anchor{library/test test support SaveSignals}@anchor{40bb}
@deffn {Classe} test.support.SaveSignals

Class to save and restore signal handlers registered by the Python signal
handler.

@geindex save() (méthode test.support.SaveSignals)
@anchor{library/test test support SaveSignals save}@anchor{40bc}
@deffn {Méthode} save (self)

Save the signal handlers to a dictionary mapping signal numbers to the
current signal handler.
@end deffn

@geindex restore() (méthode test.support.SaveSignals)
@anchor{library/test test support SaveSignals restore}@anchor{40bd}
@deffn {Méthode} restore (self)

Set the signal numbers from the @ref{40bc,,save()} dictionary to the saved
handler.
@end deffn
@end deffn

@geindex Matcher (classe dans test.support)
@anchor{library/test test support Matcher}@anchor{40be}
@deffn {Classe} test.support.Matcher

@geindex matches() (méthode test.support.Matcher)
@anchor{library/test test support Matcher matches}@anchor{40bf}
@deffn {Méthode} matches (self, d, **kwargs)

Try to match a single dict with the supplied arguments.
@end deffn

@geindex match_value() (méthode test.support.Matcher)
@anchor{library/test test support Matcher match_value}@anchor{40c0}
@deffn {Méthode} match_value (self, k, dv, v)

Try to match a single stored value (`dv') with a supplied value (`v').
@end deffn
@end deffn

@node test support socket_helper --- Utilities for socket tests,test support script_helper --- Utilities for the Python execution tests,test support --- Utilities for the Python test suite,Outils de développement
@anchor{library/test module-test support socket_helper}@anchor{e8}@anchor{library/test test-support-socket-helper-utilities-for-socket-tests}@anchor{40c1}
@subsection @code{test.support.socket_helper} --- Utilities for socket tests


@geindex module; test.support.socket_helper

The @ref{e8,,test.support.socket_helper} module provides support for socket tests.


Ajouté dans la version 3.9.


@geindex IPV6_ENABLED (dans le module test.support.socket_helper)
@anchor{library/test test support socket_helper IPV6_ENABLED}@anchor{40c2}
@deffn {Données} test.support.socket_helper.IPV6_ENABLED

Set to @code{True} if IPv6 is enabled on this host, @code{False} otherwise.
@end deffn

@geindex find_unused_port() (dans le module test.support.socket_helper)
@anchor{library/test test support socket_helper find_unused_port}@anchor{40c3}
@deffn {Fonction} test.support.socket_helper.find_unused_port (family=socket.AF_INET, socktype=socket.SOCK_STREAM)

Returns an unused port that should be suitable for binding.  This is
achieved by creating a temporary socket with the same family and type as
the @code{sock} parameter (default is @ref{17ab,,AF_INET},
@ref{12d1,,SOCK_STREAM}),
and binding it to the specified host address (defaults to @code{0.0.0.0})
with the port set to 0, eliciting an unused ephemeral port from the OS.
The temporary socket is then closed and deleted, and the ephemeral port is
returned.

Either this method or @ref{40c4,,bind_port()} should be used for any tests
where a server socket needs to be bound to a particular port for the
duration of the test.
Which one to use depends on whether the calling code is creating a Python
socket, or if an unused port needs to be provided in a constructor
or passed to an external program (i.e. the @code{-accept} argument to
openssl's s_server mode).  Always prefer @ref{40c4,,bind_port()} over
@ref{40c3,,find_unused_port()} where possible.  Using a hard coded port is
discouraged since it can make multiple instances of the test impossible to
run simultaneously, which is a problem for buildbots.
@end deffn

@geindex bind_port() (dans le module test.support.socket_helper)
@anchor{library/test test support socket_helper bind_port}@anchor{40c4}
@deffn {Fonction} test.support.socket_helper.bind_port (sock, host=HOST)

Bind the socket to a free port and return the port number.  Relies on
ephemeral ports in order to ensure we are using an unbound port.  This is
important as many tests may be running simultaneously, especially in a
buildbot environment.  This method raises an exception if the
@code{sock.family} is @ref{17ab,,AF_INET} and @code{sock.type} is
@ref{12d1,,SOCK_STREAM}, and the socket has
@code{SO_REUSEADDR} or @code{SO_REUSEPORT} set on it.
Tests should never set these socket options for TCP/IP sockets.
The only case for setting these options is testing multicasting via
multiple UDP sockets.

Additionally, if the @code{SO_EXCLUSIVEADDRUSE} socket option is
available (i.e. on Windows), it will be set on the socket.  This will
prevent anyone else from binding to our host/port for the duration of the
test.
@end deffn

@geindex bind_unix_socket() (dans le module test.support.socket_helper)
@anchor{library/test test support socket_helper bind_unix_socket}@anchor{40c5}
@deffn {Fonction} test.support.socket_helper.bind_unix_socket (sock, addr)

Bind a Unix socket, raising @ref{fcf,,unittest.SkipTest} if
@ref{d30,,PermissionError} is raised.
@end deffn

@geindex skip_unless_bind_unix_socket() (dans le module test.support.socket_helper)
@anchor{library/test test support socket_helper skip_unless_bind_unix_socket}@anchor{40c6}
@deffn {Fonction} @@test.support.socket_helper.skip_unless_bind_unix_socket

A decorator for running tests that require a functional @code{bind()} for Unix
sockets.
@end deffn

@geindex transient_internet() (dans le module test.support.socket_helper)
@anchor{library/test test support socket_helper transient_internet}@anchor{4066}
@deffn {Fonction} test.support.socket_helper.transient_internet (resource_name, *, timeout=30.0, errnos=())

A context manager that raises @ref{4060,,ResourceDenied} when
various issues with the internet connection manifest themselves as
exceptions.
@end deffn

@node test support script_helper --- Utilities for the Python execution tests,test support bytecode_helper --- Support tools for testing correct bytecode generation,test support socket_helper --- Utilities for socket tests,Outils de développement
@anchor{library/test module-test support script_helper}@anchor{e7}@anchor{library/test test-support-script-helper-utilities-for-the-python-execution-tests}@anchor{40c7}
@subsection @code{test.support.script_helper} --- Utilities for the Python execution tests


@geindex module; test.support.script_helper

The @ref{e7,,test.support.script_helper} module provides support for Python's
script execution tests.

@geindex interpreter_requires_environment() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper interpreter_requires_environment}@anchor{40c8}
@deffn {Fonction} test.support.script_helper.interpreter_requires_environment ()

Return @code{True} if @code{sys.executable interpreter} requires environment
variables in order to be able to run at all.

This is designed to be used with @code{@@unittest.skipIf()} to annotate tests
that need to use an @code{assert_python*()} function to launch an isolated
mode (@code{-I}) or no environment mode (@code{-E}) sub-interpreter process.

A normal build & test does not run into this situation but it can happen
when trying to run the standard library test suite from an interpreter that
doesn't have an obvious home with Python's current home finding logic.

Setting 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} is one way to get most of the testsuite to run
in that situation.  
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} or 
@geindex PYTHONUSERSITE
@geindex variable d'environnement; PYTHONUSERSITE
@code{PYTHONUSERSITE} are
other common environment variables that might impact whether or not the
interpreter can start.
@end deffn

@geindex run_python_until_end() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper run_python_until_end}@anchor{40c9}
@deffn {Fonction} test.support.script_helper.run_python_until_end (*args, **env_vars)

Set up the environment based on `env_vars' for running the interpreter
in a subprocess.  The values can include @code{__isolated}, @code{__cleanenv},
@code{__cwd}, and @code{TERM}.


Modifié dans la version 3.9: The function no longer strips whitespaces from `stderr'.

@end deffn

@geindex assert_python_ok() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper assert_python_ok}@anchor{40ca}
@deffn {Fonction} test.support.script_helper.assert_python_ok (*args, **env_vars)

Assert that running the interpreter with `args' and optional environment
variables `env_vars' succeeds (@code{rc == 0}) and return a @code{(return code,
stdout, stderr)} tuple.

If the `__cleanenv' keyword-only parameter is set, `env_vars' is used as a fresh
environment.

Python is started in isolated mode (command line option @code{-I}),
except if the `__isolated' keyword-only parameter is set to @code{False}.


Modifié dans la version 3.9: The function no longer strips whitespaces from `stderr'.

@end deffn

@geindex assert_python_failure() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper assert_python_failure}@anchor{40cb}
@deffn {Fonction} test.support.script_helper.assert_python_failure (*args, **env_vars)

Assert that running the interpreter with `args' and optional environment
variables `env_vars' fails (@code{rc != 0}) and return a @code{(return code,
stdout, stderr)} tuple.

See @ref{40ca,,assert_python_ok()} for more options.


Modifié dans la version 3.9: The function no longer strips whitespaces from `stderr'.

@end deffn

@geindex spawn_python() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper spawn_python}@anchor{40cc}
@deffn {Fonction} test.support.script_helper.spawn_python (*args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **kw)

Run a Python subprocess with the given arguments.

`kw' is extra keyword args to pass to @ref{197,,subprocess.Popen()}. Returns a
@ref{197,,subprocess.Popen} object.
@end deffn

@geindex kill_python() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper kill_python}@anchor{40cd}
@deffn {Fonction} test.support.script_helper.kill_python (p)

Run the given @ref{197,,subprocess.Popen} process until completion and return
stdout.
@end deffn

@geindex make_script() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper make_script}@anchor{40ce}
@deffn {Fonction} test.support.script_helper.make_script (script_dir, script_basename, source, omit_suffix=False)

Create script containing `source' in path `script_dir' and `script_basename'.
If `omit_suffix' is @code{False}, append @code{.py} to the name.  Return the full
script path.
@end deffn

@geindex make_zip_script() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper make_zip_script}@anchor{40cf}
@deffn {Fonction} test.support.script_helper.make_zip_script (zip_dir, zip_basename, script_name, name_in_zip=None)

Create zip file at `zip_dir' and `zip_basename' with extension @code{zip} which
contains the files in `script_name'. `name_in_zip' is the archive name.
Return a tuple containing @code{(full path, full path of archive name)}.
@end deffn

@geindex make_pkg() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper make_pkg}@anchor{40d0}
@deffn {Fonction} test.support.script_helper.make_pkg (pkg_dir, init_source='@w{'})

Create a directory named `pkg_dir' containing an @code{__init__} file with
`init_source' as its contents.
@end deffn

@geindex make_zip_pkg() (dans le module test.support.script_helper)
@anchor{library/test test support script_helper make_zip_pkg}@anchor{40d1}
@deffn {Fonction} test.support.script_helper.make_zip_pkg (zip_dir, zip_basename, pkg_name, script_basename, source, depth=1, compiled=False)

Create a zip package directory with a path of `zip_dir' and `zip_basename'
containing an empty @code{__init__} file and a file `script_basename'
containing the `source'.  If `compiled' is @code{True}, both source files will
be compiled and added to the zip package.  Return a tuple of the full zip
path and the archive name for the zip file.
@end deffn

@node test support bytecode_helper --- Support tools for testing correct bytecode generation,test support threading_helper --- Utilities for threading tests,test support script_helper --- Utilities for the Python execution tests,Outils de développement
@anchor{library/test module-test support bytecode_helper}@anchor{e4}@anchor{library/test test-support-bytecode-helper-support-tools-for-testing-correct-bytecode-generation}@anchor{40d2}
@subsection @code{test.support.bytecode_helper} --- Support tools for testing correct bytecode generation


@geindex module; test.support.bytecode_helper

The @ref{e4,,test.support.bytecode_helper} module provides support for testing
and inspecting bytecode generation.


Ajouté dans la version 3.9.


The module defines the following class:

@geindex BytecodeTestCase (classe dans test.support.bytecode_helper)
@anchor{library/test test support bytecode_helper BytecodeTestCase}@anchor{40d3}
@deffn {Classe} test.support.bytecode_helper.BytecodeTestCase (unittest.TestCase)

This class has custom assertion methods for inspecting bytecode.
@end deffn

@geindex get_disassembly_as_string() (méthode test.support.bytecode_helper.BytecodeTestCase)
@anchor{library/test test support bytecode_helper BytecodeTestCase get_disassembly_as_string}@anchor{40d4}
@deffn {Méthode} BytecodeTestCase.get_disassembly_as_string (co)

Return the disassembly of `co' as string.
@end deffn

@geindex assertInBytecode() (méthode test.support.bytecode_helper.BytecodeTestCase)
@anchor{library/test test support bytecode_helper BytecodeTestCase assertInBytecode}@anchor{40d5}
@deffn {Méthode} BytecodeTestCase.assertInBytecode (x, opname, argval=_UNSPECIFIED)

Return instr if `opname' is found, otherwise throws @ref{694,,AssertionError}.
@end deffn

@geindex assertNotInBytecode() (méthode test.support.bytecode_helper.BytecodeTestCase)
@anchor{library/test test support bytecode_helper BytecodeTestCase assertNotInBytecode}@anchor{40d6}
@deffn {Méthode} BytecodeTestCase.assertNotInBytecode (x, opname, argval=_UNSPECIFIED)

Throws @ref{694,,AssertionError} if `opname' is found.
@end deffn

@node test support threading_helper --- Utilities for threading tests,test support os_helper --- Utilities for os tests,test support bytecode_helper --- Support tools for testing correct bytecode generation,Outils de développement
@anchor{library/test module-test support threading_helper}@anchor{e9}@anchor{library/test test-support-threading-helper-utilities-for-threading-tests}@anchor{40d7}
@subsection @code{test.support.threading_helper} --- Utilities for threading tests


@geindex module; test.support.threading_helper

The @ref{e9,,test.support.threading_helper} module provides support for threading tests.


Ajouté dans la version 3.10.


@geindex join_thread() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper join_thread}@anchor{40d8}
@deffn {Fonction} test.support.threading_helper.join_thread (thread, timeout=None)

Join a `thread' within `timeout'.  Raise an @ref{694,,AssertionError} if thread
is still alive after `timeout' seconds.
@end deffn

@geindex reap_threads() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper reap_threads}@anchor{40d9}
@deffn {Fonction} @@test.support.threading_helper.reap_threads

Decorator to ensure the threads are cleaned up even if the test fails.
@end deffn

@geindex start_threads() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper start_threads}@anchor{40da}
@deffn {Fonction} test.support.threading_helper.start_threads (threads, unlock=None)

Context manager to start `threads', which is a sequence of threads.
`unlock' is a function called after the threads are started, even if an
exception was raised; an example would be @ref{307b,,threading.Event.set()}.
@code{start_threads} will attempt to join the started threads upon exit.
@end deffn

@geindex threading_cleanup() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper threading_cleanup}@anchor{40db}
@deffn {Fonction} test.support.threading_helper.threading_cleanup (*original_values)

Cleanup up threads not specified in `original_values'.  Designed to emit
a warning if a test leaves running threads in the background.
@end deffn

@geindex threading_setup() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper threading_setup}@anchor{40dc}
@deffn {Fonction} test.support.threading_helper.threading_setup ()

Return current thread count and copy of dangling threads.
@end deffn

@geindex wait_threads_exit() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper wait_threads_exit}@anchor{40dd}
@deffn {Fonction} test.support.threading_helper.wait_threads_exit (timeout=None)

Context manager to wait until all threads created in the @code{with} statement
exit.
@end deffn

@geindex catch_threading_exception() (dans le module test.support.threading_helper)
@anchor{library/test test support threading_helper catch_threading_exception}@anchor{40de}
@deffn {Fonction} test.support.threading_helper.catch_threading_exception ()

Context manager catching @ref{939,,threading.Thread} exception using
@ref{835,,threading.excepthook()}.

Attributes set when an exception is caught:


@itemize *

@item 
@code{exc_type}

@item 
@code{exc_value}

@item 
@code{exc_traceback}

@item 
@code{thread}
@end itemize

See @ref{835,,threading.excepthook()} documentation.

These attributes are deleted at the context manager exit.

Utilisation :

@example
with threading_helper.catch_threading_exception() as cm:
    # code spawning a thread which raises an exception
    ...

    # check the thread exception, use cm attributes:
    # exc_type, exc_value, exc_traceback, thread
    ...

# exc_type, exc_value, exc_traceback, thread attributes of cm no longer
# exists at this point
# (to avoid reference cycles)
@end example


Ajouté dans la version 3.8.

@end deffn

@node test support os_helper --- Utilities for os tests,test support import_helper --- Utilities for import tests,test support threading_helper --- Utilities for threading tests,Outils de développement
@anchor{library/test module-test support os_helper}@anchor{e6}@anchor{library/test test-support-os-helper-utilities-for-os-tests}@anchor{40df}
@subsection @code{test.support.os_helper} --- Utilities for os tests


@geindex module; test.support.os_helper

The @ref{e6,,test.support.os_helper} module provides support for os tests.


Ajouté dans la version 3.10.


@geindex FS_NONASCII (dans le module test.support.os_helper)
@anchor{library/test test support os_helper FS_NONASCII}@anchor{40e0}
@deffn {Données} test.support.os_helper.FS_NONASCII

A non-ASCII character encodable by @ref{c43,,os.fsencode()}.
@end deffn

@geindex SAVEDCWD (dans le module test.support.os_helper)
@anchor{library/test test support os_helper SAVEDCWD}@anchor{40e1}
@deffn {Données} test.support.os_helper.SAVEDCWD

Set to @ref{1521,,os.getcwd()}.
@end deffn

@geindex TESTFN (dans le module test.support.os_helper)
@anchor{library/test test support os_helper TESTFN}@anchor{40e2}
@deffn {Données} test.support.os_helper.TESTFN

Set to a name that is safe to use as the name of a temporary file.  Any
temporary file that is created should be closed and unlinked (removed).
@end deffn

@geindex TESTFN_NONASCII (dans le module test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_NONASCII}@anchor{40e3}
@deffn {Données} test.support.os_helper.TESTFN_NONASCII

Set to a filename containing the @ref{40e0,,FS_NONASCII} character, if it exists.
This guarantees that if the filename exists, it can be encoded and decoded
with the default filesystem encoding. This allows tests that require a
non-ASCII filename to be easily skipped on platforms where they can't work.
@end deffn

@geindex TESTFN_UNENCODABLE (dans le module test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_UNENCODABLE}@anchor{40e4}
@deffn {Données} test.support.os_helper.TESTFN_UNENCODABLE

Set to a filename (str type) that should not be able to be encoded by file
system encoding in strict mode.  It may be @code{None} if it's not possible to
generate such a filename.
@end deffn

@geindex TESTFN_UNDECODABLE (dans le module test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_UNDECODABLE}@anchor{40e5}
@deffn {Données} test.support.os_helper.TESTFN_UNDECODABLE

Set to a filename (bytes type) that should not be able to be decoded by
file system encoding in strict mode.  It may be @code{None} if it's not
possible to generate such a filename.
@end deffn

@geindex TESTFN_UNICODE (dans le module test.support.os_helper)
@anchor{library/test test support os_helper TESTFN_UNICODE}@anchor{40e6}
@deffn {Données} test.support.os_helper.TESTFN_UNICODE

Set to a non-ASCII name for a temporary file.
@end deffn

@geindex EnvironmentVarGuard (classe dans test.support.os_helper)
@anchor{library/test test support os_helper EnvironmentVarGuard}@anchor{1399}
@deffn {Classe} test.support.os_helper.EnvironmentVarGuard

Class used to temporarily set or unset environment variables.  Instances can
be used as a context manager and have a complete dictionary interface for
querying/modifying the underlying @code{os.environ}. After exit from the
context manager all changes to environment variables done through this
instance will be rolled back.


Modifié dans la version 3.1: Added dictionary interface.

@end deffn

@geindex FakePath (classe dans test.support.os_helper)
@anchor{library/test test support os_helper FakePath}@anchor{40e7}
@deffn {Classe} test.support.os_helper.FakePath (path)

Simple @ref{29d,,path-like object}.  It implements the
@ref{c40,,__fspath__()}
method which just returns the `path' argument.  If `path' is an exception,
it will be raised in @code{__fspath__()}.
@end deffn

@geindex set() (méthode test.support.os_helper.EnvironmentVarGuard)
@anchor{library/test test support os_helper EnvironmentVarGuard set}@anchor{40e8}
@deffn {Méthode} EnvironmentVarGuard.set (envvar, value)

Temporarily set the environment variable @code{envvar} to the value of
@code{value}.
@end deffn

@geindex unset() (méthode test.support.os_helper.EnvironmentVarGuard)
@anchor{library/test test support os_helper EnvironmentVarGuard unset}@anchor{40e9}
@deffn {Méthode} EnvironmentVarGuard.unset (envvar)

Temporarily unset the environment variable @code{envvar}.
@end deffn

@geindex can_symlink() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper can_symlink}@anchor{40ea}
@deffn {Fonction} test.support.os_helper.can_symlink ()

Return @code{True} if the OS supports symbolic links, @code{False}
otherwise.
@end deffn

@geindex can_xattr() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper can_xattr}@anchor{40eb}
@deffn {Fonction} test.support.os_helper.can_xattr ()

Return @code{True} if the OS supports xattr, @code{False}
otherwise.
@end deffn

@geindex change_cwd() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper change_cwd}@anchor{40ec}
@deffn {Fonction} test.support.os_helper.change_cwd (path, quiet=False)

A context manager that temporarily changes the current working
directory to `path' and yields the directory.

If `quiet' is @code{False}, the context manager raises an exception
on error.  Otherwise, it issues only a warning and keeps the current
working directory the same.
@end deffn

@geindex create_empty_file() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper create_empty_file}@anchor{40ed}
@deffn {Fonction} test.support.os_helper.create_empty_file (filename)

Create an empty file with `filename'.  If it already exists, truncate it.
@end deffn

@geindex fd_count() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper fd_count}@anchor{40ee}
@deffn {Fonction} test.support.os_helper.fd_count ()

Count the number of open file descriptors.
@end deffn

@geindex fs_is_case_insensitive() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper fs_is_case_insensitive}@anchor{40ef}
@deffn {Fonction} test.support.os_helper.fs_is_case_insensitive (directory)

Return @code{True} if the file system for `directory' is case-insensitive.
@end deffn

@geindex make_bad_fd() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper make_bad_fd}@anchor{40f0}
@deffn {Fonction} test.support.os_helper.make_bad_fd ()

Create an invalid file descriptor by opening and closing a temporary file,
and returning its descriptor.
@end deffn

@geindex rmdir() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper rmdir}@anchor{40f1}
@deffn {Fonction} test.support.os_helper.rmdir (filename)

Call @ref{10d4,,os.rmdir()} on `filename'.  On Windows platforms, this is
wrapped with a wait loop that checks for the existence of the file,
which is needed due to antivirus programs that can hold files open and prevent
deletion.
@end deffn

@geindex rmtree() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper rmtree}@anchor{40f2}
@deffn {Fonction} test.support.os_helper.rmtree (path)

Call @ref{2f5,,shutil.rmtree()} on `path' or call @ref{48b,,os.lstat()} and
@ref{10d4,,os.rmdir()} to remove a path and its contents.  As with @ref{40f1,,rmdir()},
on Windows platforms
this is wrapped with a wait loop that checks for the existence of the files.
@end deffn

@geindex skip_unless_symlink() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper skip_unless_symlink}@anchor{40f3}
@deffn {Fonction} @@test.support.os_helper.skip_unless_symlink

A decorator for running tests that require support for symbolic links.
@end deffn

@geindex skip_unless_xattr() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper skip_unless_xattr}@anchor{40f4}
@deffn {Fonction} @@test.support.os_helper.skip_unless_xattr

A decorator for running tests that require support for xattr.
@end deffn

@geindex temp_cwd() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper temp_cwd}@anchor{40f5}
@deffn {Fonction} test.support.os_helper.temp_cwd (name='tempcwd', quiet=False)

A context manager that temporarily creates a new directory and
changes the current working directory (CWD).

The context manager creates a temporary directory in the current
directory with name `name' before temporarily changing the current
working directory.  If `name' is @code{None}, the temporary directory is
created using @ref{21c,,tempfile.mkdtemp()}.

If `quiet' is @code{False} and it is not possible to create or change
the CWD, an error is raised.  Otherwise, only a warning is raised
and the original CWD is used.
@end deffn

@geindex temp_dir() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper temp_dir}@anchor{40f6}
@deffn {Fonction} test.support.os_helper.temp_dir (path=None, quiet=False)

A context manager that creates a temporary directory at `path' and
yields the directory.

If `path' is @code{None}, the temporary directory is created using
@ref{21c,,tempfile.mkdtemp()}.  If `quiet' is @code{False}, the context manager
raises an exception on error.  Otherwise, if `path' is specified and
cannot be created, only a warning is issued.
@end deffn

@geindex temp_umask() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper temp_umask}@anchor{40f7}
@deffn {Fonction} test.support.os_helper.temp_umask (umask)

A context manager that temporarily sets the process umask.
@end deffn

@geindex unlink() (dans le module test.support.os_helper)
@anchor{library/test test support os_helper unlink}@anchor{40f8}
@deffn {Fonction} test.support.os_helper.unlink (filename)

Call @ref{10d6,,os.unlink()} on `filename'.  As with @ref{40f1,,rmdir()},
on Windows platforms, this is
wrapped with a wait loop that checks for the existence of the file.
@end deffn

@node test support import_helper --- Utilities for import tests,test support warnings_helper --- Utilities for warnings tests,test support os_helper --- Utilities for os tests,Outils de développement
@anchor{library/test module-test support import_helper}@anchor{e5}@anchor{library/test test-support-import-helper-utilities-for-import-tests}@anchor{40f9}
@subsection @code{test.support.import_helper} --- Utilities for import tests


@geindex module; test.support.import_helper

The @ref{e5,,test.support.import_helper} module provides support for import tests.


Ajouté dans la version 3.10.


@geindex forget() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper forget}@anchor{40fa}
@deffn {Fonction} test.support.import_helper.forget (module_name)

Remove the module named `module_name' from @code{sys.modules} and delete any
byte-compiled files of the module.
@end deffn

@geindex import_fresh_module() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper import_fresh_module}@anchor{183b}
@deffn {Fonction} test.support.import_helper.import_fresh_module (name, fresh=(), blocked=(), deprecated=False)

This function imports and returns a fresh copy of the named Python module
by removing the named module from @code{sys.modules} before doing the import.
Note that unlike @code{reload()}, the original module is not affected by
this operation.

`fresh' is an iterable of additional module names that are also removed
from the @code{sys.modules} cache before doing the import.

`blocked' is an iterable of module names that are replaced with @code{None}
in the module cache during the import to ensure that attempts to import
them raise @ref{40f,,ImportError}.

The named module and any modules named in the `fresh' and `blocked'
parameters are saved before starting the import and then reinserted into
@code{sys.modules} when the fresh import is complete.

Module and package deprecation messages are suppressed during this import
if `deprecated' is @code{True}.

This function will raise @ref{40f,,ImportError} if the named module cannot be
imported.

Example use:

@example
# Get copies of the warnings module for testing without affecting the
# version being used by the rest of the test suite. One copy uses the
# C implementation, the other is forced to use the pure Python fallback
# implementation
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex import_module() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper import_module}@anchor{40fb}
@deffn {Fonction} test.support.import_helper.import_module (name, deprecated=False, *, required_on=())

This function imports and returns the named module. Unlike a normal
import, this function raises @ref{fcf,,unittest.SkipTest} if the module
cannot be imported.

Module and package deprecation messages are suppressed during this import
if `deprecated' is @code{True}.  If a module is required on a platform but
optional for others, set `required_on' to an iterable of platform prefixes
which will be compared against @ref{a7b,,sys.platform}.


Ajouté dans la version 3.1.

@end deffn

@geindex modules_setup() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper modules_setup}@anchor{40fc}
@deffn {Fonction} test.support.import_helper.modules_setup ()

Return a copy of @ref{18f9,,sys.modules}.
@end deffn

@geindex modules_cleanup() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper modules_cleanup}@anchor{40fd}
@deffn {Fonction} test.support.import_helper.modules_cleanup (oldmodules)

Remove modules except for `oldmodules' and @code{encodings} in order to
preserve internal cache.
@end deffn

@geindex unload() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper unload}@anchor{40fe}
@deffn {Fonction} test.support.import_helper.unload (name)

Delete `name' from @code{sys.modules}.
@end deffn

@geindex make_legacy_pyc() (dans le module test.support.import_helper)
@anchor{library/test test support import_helper make_legacy_pyc}@anchor{40ff}
@deffn {Fonction} test.support.import_helper.make_legacy_pyc (source)

Move a 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}/
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} pyc file to its legacy pyc location and return the file
system path to the legacy pyc file.  The `source' value is the file system
path to the source file.  It does not need to exist, however the PEP
3147/488 pyc file must exist.
@end deffn

@geindex CleanImport (classe dans test.support.import_helper)
@anchor{library/test test support import_helper CleanImport}@anchor{4100}
@deffn {Classe} test.support.import_helper.CleanImport (*module_names)

A context manager to force import to return a new module reference.  This
is useful for testing module-level behaviors, such as the emission of a
@ref{1a3,,DeprecationWarning} on import.  Example usage:

@example
with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.
@end example
@end deffn

@geindex DirsOnSysPath (classe dans test.support.import_helper)
@anchor{library/test test support import_helper DirsOnSysPath}@anchor{4101}
@deffn {Classe} test.support.import_helper.DirsOnSysPath (*paths)

A context manager to temporarily add directories to @ref{3ab,,sys.path}.

This makes a copy of @ref{3ab,,sys.path}, appends any directories given
as positional arguments, then reverts @ref{3ab,,sys.path} to the copied
settings when the context ends.

Note that `all' @ref{3ab,,sys.path} modifications in the body of the
context manager, including replacement of the object,
will be reverted at the end of the block.
@end deffn

@node test support warnings_helper --- Utilities for warnings tests,,test support import_helper --- Utilities for import tests,Outils de développement
@anchor{library/test module-test support warnings_helper}@anchor{ea}@anchor{library/test test-support-warnings-helper-utilities-for-warnings-tests}@anchor{4102}
@subsection @code{test.support.warnings_helper} --- Utilities for warnings tests


@geindex module; test.support.warnings_helper

The @ref{ea,,test.support.warnings_helper} module provides support for warnings tests.


Ajouté dans la version 3.10.


@geindex ignore_warnings() (dans le module test.support.warnings_helper)
@anchor{library/test test support warnings_helper ignore_warnings}@anchor{4103}
@deffn {Fonction} test.support.warnings_helper.ignore_warnings (*, category)

Suppress warnings that are instances of `category',
which must be @ref{2239,,Warning} or a subclass.
Roughly equivalent to @ref{570,,warnings.catch_warnings()}
with @ref{6ac,,warnings.simplefilter('ignore'@comma{} category=category)}.
For example:

@example
@@warning_helper.ignore_warnings(category=DeprecationWarning)
def test_suppress_warning():
    # do something
@end example


Ajouté dans la version 3.8.

@end deffn

@geindex check_no_resource_warning() (dans le module test.support.warnings_helper)
@anchor{library/test test support warnings_helper check_no_resource_warning}@anchor{4104}
@deffn {Fonction} test.support.warnings_helper.check_no_resource_warning (testcase)

Context manager to check that no @ref{241,,ResourceWarning} was raised.  You
must remove the object which may emit @ref{241,,ResourceWarning} before the
end of the context manager.
@end deffn

@geindex check_syntax_warning() (dans le module test.support.warnings_helper)
@anchor{library/test test support warnings_helper check_syntax_warning}@anchor{4105}
@deffn {Fonction} test.support.warnings_helper.check_syntax_warning (testcase, statement, errtext='@w{'}, *, lineno=1, offset=None)

Test for syntax warning in `statement' by attempting to compile `statement'.
Test also that the @ref{44f,,SyntaxWarning} is emitted only once, and that it
will be converted to a @ref{18b,,SyntaxError} when turned into error.
`testcase' is the @ref{105,,unittest} instance for the test.  `errtext' is the
regular expression which should match the string representation of the
emitted @ref{44f,,SyntaxWarning} and raised @ref{18b,,SyntaxError}.  If `lineno'
is not @code{None}, compares to the line of the warning and exception.
If `offset' is not @code{None}, compares to the offset of the exception.


Ajouté dans la version 3.8.

@end deffn

@geindex check_warnings() (dans le module test.support.warnings_helper)
@anchor{library/test test support warnings_helper check_warnings}@anchor{4106}
@deffn {Fonction} test.support.warnings_helper.check_warnings (*filters, quiet=True)

A convenience wrapper for @ref{570,,warnings.catch_warnings()} that makes it
easier to test that a warning was correctly raised.  It is approximately
equivalent to calling @code{warnings.catch_warnings(record=True)} with
@ref{6ac,,warnings.simplefilter()} set to @code{always} and with the option to
automatically validate the results that are recorded.

@code{check_warnings} accepts 2-tuples of the form @code{("message regexp",
WarningCategory)} as positional arguments. If one or more `filters' are
provided, or if the optional keyword argument `quiet' is @code{False},
it checks to make sure the warnings are as expected:  each specified filter
must match at least one of the warnings raised by the enclosed code or the
test fails, and if any warnings are raised that do not match any of the
specified filters the test fails.  To disable the first of these checks,
set `quiet' to @code{True}.

If no arguments are specified, it defaults to:

@example
check_warnings(("", Warning), quiet=True)
@end example

In this case all warnings are caught and no errors are raised.

On entry to the context manager, a @code{WarningRecorder} instance is
returned. The underlying warnings list from
@ref{570,,catch_warnings()} is available via the recorder object's
@ref{111,,warnings} attribute.  As a convenience, the attributes of the object
representing the most recent warning can also be accessed directly through
the recorder object (see example below).  If no warning has been raised,
then any of the attributes that would otherwise be expected on an object
representing a warning will return @code{None}.

The recorder object also has a @code{reset()} method, which clears the
warnings list.

The context manager is designed to be used like this:

@example
with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))
@end example

In this case if either warning was not raised, or some other warning was
raised, @ref{4106,,check_warnings()} would raise an error.

When a test needs to look more deeply into the warnings, rather than
just checking whether or not they occurred, code like this can be used:

@example
with check_warnings(quiet=True) as w:
    warnings.warn("foo")
    assert str(w.args[0]) == "foo"
    warnings.warn("bar")
    assert str(w.args[0]) == "bar"
    assert str(w.warnings[0].args[0]) == "foo"
    assert str(w.warnings[1].args[0]) == "bar"
    w.reset()
    assert len(w.warnings) == 0
@end example

Here all warnings will be caught, and the test code tests the captured
warnings directly.


Modifié dans la version 3.2: New optional arguments `filters' and `quiet'.

@end deffn

@geindex WarningsRecorder (classe dans test.support.warnings_helper)
@anchor{library/test test support warnings_helper WarningsRecorder}@anchor{4107}
@deffn {Classe} test.support.warnings_helper.WarningsRecorder

Class used to record warnings for unit tests. See documentation of
@ref{4106,,check_warnings()} above for more details.
@end deffn

@node Débogueur et instrumentation,Paquets et distribution de paquets logiciels,Outils de développement,La bibliothèque standard
@anchor{library/debug doc}@anchor{4108}@anchor{library/debug debugging-and-profiling}@anchor{4109}
@section Débogueur et instrumentation


Ces bibliothèques sont là pour vous aider lors du développement en Python : Le débogueur vous permet d'avancer pas à pas dans le code, d'analyser la pile d'appel, de placer des points d'arrêts, … Les outils d'instrumentation exécutent du code et vous donnent un rapport détaillé du temps d'exécution, vous permettant d'identifier les goulots d'étranglement dans vos programmes. Les événements d'audit fournissent une visibilité sur les comportements d'exécution qui nécessiteraient autrement un débogage ou une correction intrusifs.

@geindex audit events
@anchor{library/audit_events audit-events}@anchor{17fe}
@menu
* Table des évènements d'audit:: 
* bdb: bdb --- Debugger framework. Debugger framework
* faulthandler: faulthandler --- Dump the Python traceback. Dump the Python traceback
* pdb — Le débogueur Python:: 
* The Python Profilers:: 
* timeit: timeit --- Measure execution time of small code snippets. Measure execution time of small code snippets
* trace: trace --- Trace or track Python statement execution. Trace or track Python statement execution
* tracemalloc: tracemalloc --- Trace memory allocations. Trace memory allocations

@end menu

@node Table des évènements d'audit,bdb --- Debugger framework,,Débogueur et instrumentation
@anchor{library/audit_events doc}@anchor{410a}@anchor{library/audit_events audit-events-table}@anchor{410b}
@subsection Table des évènements d'audit


This table contains all events raised by @ref{153f,,sys.audit()} or
@ref{365,,PySys_Audit()} calls throughout the CPython runtime and the
standard library.  These calls were added in 3.8 or later (see 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/}).

Voir @ref{410c,,sys.addaudithook()} et @ref{410d,,PySys_AddAuditHook()} pour plus d'informations sur la gestion de ces évènements.

`Particularité de l'implémentation CPython :' Cette table est générée à partir de la documentation de CPython et peut ne pas représenter des évènements levés par d'autres implémentations. Consultez la documentation propre à votre implémentation pour connaître les évènements réellement levés.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Audit event

@tab

Arguments

@tab

References

@item

_thread.start_new_thread

@tab

@code{function}, @code{args}, @code{kwargs}

@tab

@ref{410e,,[1]}

@item

array.__new__

@tab

@code{typecode}, @code{initializer}

@tab

@ref{19e,,[1]}

@item

builtins.breakpoint

@tab

@code{breakpointhook}

@tab

@ref{231,,[1]}

@item

builtins.id

@tab

@code{id}

@tab

@ref{13d9,,[1]}

@item

builtins.input

@tab

@code{prompt}

@tab

@ref{12b6,,[1]}

@item

builtins.input/result

@tab

@code{result}

@tab

@ref{12b6,,[1]}

@item

code.__new__

@tab

@code{code}, @code{filename}, @code{name}, @code{argcount}, @code{posonlyargcount}, @code{kwonlyargcount}, @code{nlocals}, @code{stacksize}, @code{flags}

@tab

@ref{2dd,,[1]}

@item

compile

@tab

@code{source}, @code{filename}

@tab

@ref{190,,[1]}

@item

cpython.PyInterpreterState_Clear

@tab



@tab

@ref{410f,,[1]}

@item

cpython.PyInterpreterState_New

@tab



@tab

@ref{4110,,[1]}

@item

cpython._PySys_ClearAuditHooks

@tab



@tab

@ref{d03,,[1]}

@item

cpython.run_command

@tab

@code{command}

@tab

@ref{5ca,,[1]}

@item

cpython.run_file

@tab

@code{filename}

@tab

@ref{4111,,[1]}

@item

cpython.run_interactivehook

@tab

@code{hook}

@tab

@ref{fb2,,[1]}

@item

cpython.run_module

@tab

@code{module-name}

@tab

@ref{5cb,,[1]}

@item

cpython.run_startup

@tab

@code{filename}

@tab

@ref{fb3,,[1]}

@item

cpython.run_stdin

@tab



@tab

@ref{4112,,[1]}@ref{4113,,[2]}@ref{4114,,[3]}

@item

ctypes.addressof

@tab

@code{obj}

@tab

@ref{2d9e,,[1]}

@item

ctypes.call_function

@tab

@code{func_pointer}, @code{arguments}

@tab

@ref{2d96,,[1]}

@item

ctypes.cdata

@tab

@code{address}

@tab

@ref{2db0,,[1]}

@item

ctypes.cdata/buffer

@tab

@code{pointer}, @code{size}, @code{offset}

@tab

@ref{2dae,,[1]}@ref{2daf,,[2]}

@item

ctypes.create_string_buffer

@tab

@code{init}, @code{size}

@tab

@ref{2d53,,[1]}

@item

ctypes.create_unicode_buffer

@tab

@code{init}, @code{size}

@tab

@ref{195d,,[1]}

@item

ctypes.dlopen

@tab

@code{name}

@tab

@ref{2d94,,[1]}

@item

ctypes.dlsym

@tab

@code{library}, @code{name}

@tab

@ref{2d94,,[1]}

@item

ctypes.dlsym/handle

@tab

@code{handle}, @code{name}

@tab

@ref{2d94,,[1]}

@item

ctypes.get_errno

@tab



@tab

@ref{2d8e,,[1]}

@item

ctypes.get_last_error

@tab



@tab

@ref{2d90,,[1]}

@item

ctypes.set_errno

@tab

@code{errno}

@tab

@ref{2d8f,,[1]}

@item

ctypes.set_exception

@tab

@code{code}

@tab

@ref{2d96,,[1]}

@item

ctypes.set_last_error

@tab

@code{error}

@tab

@ref{2d91,,[1]}

@item

ctypes.string_at

@tab

@code{ptr}, @code{size}

@tab

@ref{2da7,,[1]}

@item

ctypes.wstring_at

@tab

@code{ptr}, @code{size}

@tab

@ref{2da9,,[1]}

@item

ensurepip.bootstrap

@tab

@code{root}

@tab

@ref{4115,,[1]}

@item

exec

@tab

@code{code_object}

@tab

@ref{17e,,[1]}@ref{17d,,[2]}

@item

fcntl.fcntl

@tab

@code{fd}, @code{cmd}, @code{arg}

@tab

@ref{33a1,,[1]}

@item

fcntl.flock

@tab

@code{fd}, @code{operation}

@tab

@ref{4116,,[1]}

@item

fcntl.ioctl

@tab

@code{fd}, @code{request}, @code{arg}

@tab

@ref{142e,,[1]}

@item

fcntl.lockf

@tab

@code{fd}, @code{cmd}, @code{len}, @code{start}, @code{whence}

@tab

@ref{13a3,,[1]}

@item

ftplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{39c9,,[1]}

@item

ftplib.sendcmd

@tab

@code{self}, @code{cmd}

@tab

@ref{39ce,,[1]}@ref{39cf,,[2]}

@item

function.__new__

@tab

@code{code}

@tab

@ref{86f,,[1]}

@item

gc.get_objects

@tab

@code{generation}

@tab

@ref{7ed,,[1]}

@item

gc.get_referents

@tab

@code{objs}

@tab

@ref{7ef,,[1]}

@item

gc.get_referrers

@tab

@code{objs}

@tab

@ref{7ee,,[1]}

@item

glob.glob

@tab

@code{pathname}, @code{recursive}

@tab

@ref{29c,,[1]}@ref{7f1,,[2]}

@item

glob.glob/2

@tab

@code{pathname}, @code{recursive}, @code{root_dir}, @code{dir_fd}

@tab

@ref{29c,,[1]}@ref{7f1,,[2]}

@item

http.client.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{39ac,,[1]}

@item

http.client.send

@tab

@code{self}, @code{data}

@tab

@ref{39b1,,[1]}

@item

imaplib.open

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{8f2,,[1]}

@item

imaplib.send

@tab

@code{self}, @code{data}

@tab

@ref{3a20,,[1]}

@item

import

@tab

@code{module}, @code{filename}, @code{sys.path}, @code{sys.meta_path}, @code{sys.path_hooks}

@tab

@ref{5cc,,[1]}

@item

marshal.dumps

@tab

@code{value}, @code{version}

@tab

@ref{283a,,[1]}

@item

marshal.load

@tab



@tab

@ref{19a1,,[1]}

@item

marshal.loads

@tab

@code{bytes}

@tab

@ref{19a1,,[1]}

@item

mmap.__new__

@tab

@code{fileno}, @code{length}, @code{access}, @code{offset}

@tab

@ref{208,,[1]}

@item

msvcrt.get_osfhandle

@tab

@code{fd}

@tab

@ref{4117,,[1]}

@item

msvcrt.locking

@tab

@code{fd}, @code{mode}, @code{nbytes}

@tab

@ref{4118,,[1]}

@item

msvcrt.open_osfhandle

@tab

@code{handle}, @code{flags}

@tab

@ref{4119,,[1]}

@item

object.__delattr__

@tab

@code{obj}, @code{name}

@tab

@ref{1eb3,,[1]}

@item

object.__getattr__

@tab

@code{obj}, @code{name}

@tab

@ref{bc0,,[1]}

@item

object.__setattr__

@tab

@code{obj}, @code{name}, @code{value}

@tab

@ref{1eb2,,[1]}

@item

open

@tab

@code{path}, @code{mode}, @code{flags}

@tab

@ref{505,,[1]}@ref{506,,[2]}@ref{d7f,,[3]}

@item

os.add_dll_directory

@tab

@code{path}

@tab

@ref{9d8,,[1]}

@item

os.chdir

@tab

@code{path}

@tab

@ref{5f8,,[1]}@ref{d76,,[2]}

@item

os.chflags

@tab

@code{path}, @code{flags}

@tab

@ref{10ce,,[1]}@ref{2b04,,[2]}

@item

os.chmod

@tab

@code{path}, @code{mode}, @code{dir_fd}

@tab

@ref{218,,[1]}@ref{219,,[2]}@ref{217,,[3]}

@item

os.chown

@tab

@code{path}, @code{uid}, @code{gid}, @code{dir_fd}

@tab

@ref{10cf,,[1]}@ref{d77,,[2]}@ref{2b05,,[3]}

@item

os.exec

@tab

@code{path}, @code{args}, @code{env}

@tab

@ref{2b41,,[1]}

@item

os.fork

@tab



@tab

@ref{195,,[1]}

@item

os.forkpty

@tab



@tab

@ref{196,,[1]}

@item

os.fwalk

@tab

@code{top}, @code{topdown}, @code{onerror}, @code{follow_symlinks}, @code{dir_fd}

@tab

@ref{b49,,[1]}

@item

os.getxattr

@tab

@code{path}, @code{attribute}

@tab

@ref{10e4,,[1]}

@item

os.kill

@tab

@code{pid}, @code{sig}

@tab

@ref{133e,,[1]}

@item

os.killpg

@tab

@code{pgid}, @code{sig}

@tab

@ref{1964,,[1]}

@item

os.link

@tab

@code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}

@tab

@ref{10d0,,[1]}

@item

os.listdir

@tab

@code{path}

@tab

@ref{10da,,[1]}

@item

os.listdrives

@tab



@tab

@ref{487,,[1]}

@item

os.listmounts

@tab

@code{volume}

@tab

@ref{489,,[1]}

@item

os.listvolumes

@tab



@tab

@ref{488,,[1]}

@item

os.listxattr

@tab

@code{path}

@tab

@ref{10e5,,[1]}

@item

os.lockf

@tab

@code{fd}, @code{cmd}, @code{len}

@tab

@ref{10f3,,[1]}

@item

os.mkdir

@tab

@code{path}, @code{mode}, @code{dir_fd}

@tab

@ref{21b,,[1]}@ref{21a,,[2]}

@item

os.posix_spawn

@tab

@code{path}, @code{argv}, @code{env}

@tab

@ref{21d,,[1]}@ref{19bd,,[2]}

@item

os.putenv

@tab

@code{key}, @code{value}

@tab

@ref{909,,[1]}

@item

os.remove

@tab

@code{path}, @code{dir_fd}

@tab

@ref{10d1,,[1]}@ref{2b09,,[2]}@ref{10d6,,[3]}

@item

os.removexattr

@tab

@code{path}, @code{attribute}

@tab

@ref{10e6,,[1]}

@item

os.rename

@tab

@code{src}, @code{dst}, @code{src_dir_fd}, @code{dst_dir_fd}

@tab

@ref{10d2,,[1]}@ref{2b0a,,[2]}@ref{10d3,,[3]}

@item

os.rmdir

@tab

@code{path}, @code{dir_fd}

@tab

@ref{10d4,,[1]}

@item

os.scandir

@tab

@code{path}

@tab

@ref{a4d,,[1]}

@item

os.setxattr

@tab

@code{path}, @code{attribute}, @code{value}, @code{flags}

@tab

@ref{10e7,,[1]}

@item

os.spawn

@tab

@code{mode}, @code{path}, @code{args}, @code{env}

@tab

@ref{16bc,,[1]}

@item

os.startfile

@tab

@code{path}, @code{operation}

@tab

@ref{1859,,[1]}

@item

os.startfile/2

@tab

@code{path}, @code{operation}, @code{arguments}, @code{cwd}, @code{show_cmd}

@tab

@ref{1859,,[1]}

@item

os.symlink

@tab

@code{src}, @code{dst}, @code{dir_fd}

@tab

@ref{10d5,,[1]}

@item

os.system

@tab

@code{command}

@tab

@ref{1411,,[1]}

@item

os.truncate

@tab

@code{fd}, @code{length}

@tab

@ref{d7c,,[1]}@ref{e29,,[2]}

@item

os.unsetenv

@tab

@code{key}

@tab

@ref{908,,[1]}

@item

os.utime

@tab

@code{path}, @code{times}, @code{ns}, @code{dir_fd}

@tab

@ref{10d7,,[1]}

@item

os.walk

@tab

@code{top}, @code{topdown}, @code{onerror}, @code{followlinks}

@tab

@ref{493,,[1]}

@item

pathlib.Path.glob

@tab

@code{self}, @code{pattern}

@tab

@ref{22a,,[1]}

@item

pathlib.Path.rglob

@tab

@code{self}, @code{pattern}

@tab

@ref{22b,,[1]}

@item

pdb.Pdb

@tab



@tab

@ref{90f,,[1]}

@item

pickle.find_class

@tab

@code{module}, @code{name}

@tab

@ref{2818,,[1]}

@item

poplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{911,,[1]}@ref{912,,[2]}

@item

poplib.putline

@tab

@code{self}, @code{line}

@tab

@ref{911,,[1]}@ref{912,,[2]}

@item

pty.spawn

@tab

@code{argv}

@tab

@ref{f6d,,[1]}

@item

resource.prlimit

@tab

@code{pid}, @code{resource}, @code{limits}

@tab

@ref{f74,,[1]}

@item

resource.setrlimit

@tab

@code{resource}, @code{limits}

@tab

@ref{40b9,,[1]}

@item

setopencodehook

@tab



@tab

@ref{16b4,,[1]}

@item

shutil.chown

@tab

@code{path}, @code{user}, @code{group}

@tab

@ref{23d,,[1]}

@item

shutil.copyfile

@tab

@code{src}, @code{dst}

@tab

@ref{a48,,[1]}@ref{a49,,[2]}@ref{a47,,[3]}

@item

shutil.copymode

@tab

@code{src}, @code{dst}

@tab

@ref{a48,,[1]}@ref{1634,,[2]}

@item

shutil.copystat

@tab

@code{src}, @code{dst}

@tab

@ref{a49,,[1]}@ref{110e,,[2]}

@item

shutil.copytree

@tab

@code{src}, @code{dst}

@tab

@ref{a17,,[1]}

@item

shutil.make_archive

@tab

@code{base_name}, @code{format}, @code{root_dir}, @code{base_dir}

@tab

@ref{49c,,[1]}

@item

shutil.move

@tab

@code{src}, @code{dst}

@tab

@ref{a4a,,[1]}

@item

shutil.rmtree

@tab

@code{path}, @code{dir_fd}

@tab

@ref{2f5,,[1]}

@item

shutil.unpack_archive

@tab

@code{filename}, @code{extract_dir}, @code{format}

@tab

@ref{455,,[1]}

@item

signal.pthread_kill

@tab

@code{thread_id}, @code{signalnum}

@tab

@ref{1111,,[1]}

@item

smtplib.connect

@tab

@code{self}, @code{host}, @code{port}

@tab

@ref{1958,,[1]}

@item

smtplib.send

@tab

@code{self}, @code{data}

@tab

@ref{91a,,[1]}

@item

socket.__new__

@tab

@code{self}, @code{family}, @code{type}, @code{protocol}

@tab

@ref{d8e,,[1]}

@item

socket.bind

@tab

@code{self}, @code{address}

@tab

@ref{14f0,,[1]}

@item

socket.connect

@tab

@code{self}, @code{address}

@tab

@ref{d90,,[1]}@ref{14ef,,[2]}

@item

socket.getaddrinfo

@tab

@code{host}, @code{port}, @code{family}, @code{type}, @code{protocol}

@tab

@ref{16e0,,[1]}

@item

socket.gethostbyaddr

@tab

@code{ip_address}

@tab

@ref{185a,,[1]}

@item

socket.gethostbyname

@tab

@code{hostname}

@tab

@ref{3396,,[1]}@ref{185b,,[2]}

@item

socket.gethostname

@tab



@tab

@ref{2aae,,[1]}

@item

socket.getnameinfo

@tab

@code{sockaddr}

@tab

@ref{164d,,[1]}

@item

socket.getservbyname

@tab

@code{servicename}, @code{protocolname}

@tab

@ref{3398,,[1]}

@item

socket.getservbyport

@tab

@code{port}, @code{protocolname}

@tab

@ref{3399,,[1]}

@item

socket.sendmsg

@tab

@code{self}, @code{address}

@tab

@ref{460,,[1]}

@item

socket.sendto

@tab

@code{self}, @code{address}

@tab

@ref{d96,,[1]}

@item

socket.sethostname

@tab

@code{name}

@tab

@ref{111b,,[1]}

@item

sqlite3.connect

@tab

@code{database}

@tab

@ref{2a5,,[1]}

@item

sqlite3.connect/handle

@tab

@code{connection_handle}

@tab

@ref{2a5,,[1]}

@item

sqlite3.enable_load_extension

@tab

@code{connection}, @code{enabled}

@tab

@ref{828,,[1]}

@item

sqlite3.load_extension

@tab

@code{connection}, @code{path}

@tab

@ref{4a1,,[1]}

@item

subprocess.Popen

@tab

@code{executable}, @code{args}, @code{cwd}, @code{env}

@tab

@ref{197,,[1]}

@item

sys._current_exceptions

@tab



@tab

@ref{4ab,,[1]}

@item

sys._current_frames

@tab



@tab

@ref{13e9,,[1]}

@item

sys._getframe

@tab

@code{frame}

@tab

@ref{6cb,,[1]}

@item

sys._getframemodulename

@tab

@code{depth}

@tab

@ref{16fd,,[1]}

@item

sys.addaudithook

@tab



@tab

@ref{410d,,[1]}@ref{410c,,[2]}

@item

sys.excepthook

@tab

@code{hook}, @code{type}, @code{value}, @code{traceback}

@tab

@ref{7f5,,[1]}

@item

sys.set_asyncgen_hooks_finalizer

@tab



@tab

@ref{15af,,[1]}

@item

sys.set_asyncgen_hooks_firstiter

@tab



@tab

@ref{15af,,[1]}

@item

sys.setprofile

@tab



@tab

@ref{14b5,,[1]}

@item

sys.settrace

@tab



@tab

@ref{14b6,,[1]}

@item

sys.unraisablehook

@tab

@code{hook}, @code{unraisable}

@tab

@ref{1f4,,[1]}

@item

syslog.closelog

@tab



@tab

@ref{52a,,[1]}

@item

syslog.openlog

@tab

@code{ident}, @code{logoption}, @code{facility}

@tab

@ref{529,,[1]}

@item

syslog.setlogmask

@tab

@code{maskpri}

@tab

@ref{411a,,[1]}

@item

syslog.syslog

@tab

@code{priority}, @code{message}

@tab

@ref{52b,,[1]}

@item

tempfile.mkdtemp

@tab

@code{fullpath}

@tab

@ref{1212,,[1]}@ref{21c,,[2]}

@item

tempfile.mkstemp

@tab

@code{fullpath}

@tab

@ref{4af,,[1]}@ref{27cc,,[2]}@ref{27cd,,[3]}

@item

time.sleep

@tab

@code{secs}

@tab

@ref{411b,,[1]}

@item

urllib.Request

@tab

@code{fullurl}, @code{data}, @code{headers}, @code{method}

@tab

@ref{290,,[1]}

@item

webbrowser.open

@tab

@code{url}

@tab

@ref{3893,,[1]}

@item

winreg.ConnectRegistry

@tab

@code{computer_name}, @code{key}

@tab

@ref{411c,,[1]}

@item

winreg.CreateKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{411d,,[1]}@ref{1339,,[2]}

@item

winreg.DeleteKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{411e,,[1]}@ref{133a,,[2]}

@item

winreg.DeleteValue

@tab

@code{key}, @code{value}

@tab

@ref{411f,,[1]}

@item

winreg.DisableReflectionKey

@tab

@code{key}

@tab

@ref{133b,,[1]}

@item

winreg.EnableReflectionKey

@tab

@code{key}

@tab

@ref{133c,,[1]}

@item

winreg.EnumKey

@tab

@code{key}, @code{index}

@tab

@ref{4120,,[1]}

@item

winreg.EnumValue

@tab

@code{key}, @code{index}

@tab

@ref{4121,,[1]}

@item

winreg.ExpandEnvironmentStrings

@tab

@code{str}

@tab

@ref{13af,,[1]}

@item

winreg.LoadKey

@tab

@code{key}, @code{sub_key}, @code{file_name}

@tab

@ref{4122,,[1]}

@item

winreg.OpenKey

@tab

@code{key}, @code{sub_key}, @code{access}

@tab

@ref{4123,,[1]}

@item

winreg.OpenKey/result

@tab

@code{key}

@tab

@ref{411d,,[1]}@ref{1339,,[2]}@ref{4123,,[3]}

@item

winreg.PyHKEY.Detach

@tab

@code{key}

@tab

@ref{4124,,[1]}

@item

winreg.QueryInfoKey

@tab

@code{key}

@tab

@ref{4125,,[1]}

@item

winreg.QueryReflectionKey

@tab

@code{key}

@tab

@ref{133d,,[1]}

@item

winreg.QueryValue

@tab

@code{key}, @code{sub_key}, @code{value_name}

@tab

@ref{4126,,[1]}@ref{4127,,[2]}

@item

winreg.SaveKey

@tab

@code{key}, @code{file_name}

@tab

@ref{4128,,[1]}

@item

winreg.SetValue

@tab

@code{key}, @code{sub_key}, @code{type}, @code{value}

@tab

@ref{4129,,[1]}@ref{171c,,[2]}

@end multitable


Les évènements suivants sont levés en interne et ne correspondent à aucune API publique de CPython :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Audit event

@tab

Arguments

@item

_winapi.CreateFile

@tab

@code{file_name}, @code{desired_access},
@code{share_mode}, @code{creation_disposition},
@code{flags_and_attributes}

@item

_winapi.CreateJunction

@tab

@code{src_path}, @code{dst_path}

@item

_winapi.CreateNamedPipe

@tab

@code{name}, @code{open_mode}, @code{pipe_mode}

@item

_winapi.CreatePipe

@tab

@item

_winapi.CreateProcess

@tab

@code{application_name}, @code{command_line},
@code{current_directory}

@item

_winapi.OpenProcess

@tab

@code{process_id}, @code{desired_access}

@item

_winapi.TerminateProcess

@tab

@code{handle}, @code{exit_code}

@item

ctypes.PyObj_FromPtr

@tab

@code{obj}

@end multitable


@node bdb --- Debugger framework,faulthandler --- Dump the Python traceback,Table des évènements d'audit,Débogueur et instrumentation
@anchor{library/bdb doc}@anchor{412a}@anchor{library/bdb bdb-debugger-framework}@anchor{412b}@anchor{library/bdb module-bdb}@anchor{f}
@subsection @code{bdb} --- Debugger framework


@geindex module; bdb

`Code source :' Lib/bdb.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/bdb.py}


__________________________________________________________________


The @ref{f,,bdb} module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.

L'exception suivante est définie :

@geindex BdbQuit
@anchor{library/bdb bdb BdbQuit}@anchor{412c}
@deffn {Exception} bdb.BdbQuit

Exception raised by the @ref{12e0,,Bdb} class for quitting the debugger.
@end deffn

Le module @ref{f,,bdb} définis deux classes :

@geindex Breakpoint (classe dans bdb)
@anchor{library/bdb bdb Breakpoint}@anchor{412d}
@deffn {Classe} bdb.Breakpoint (self, file, line, temporary=False, cond=None, funcname=None)

This class implements temporary breakpoints, ignore counts, disabling and
(re-)enabling, and conditionals.

Breakpoints are indexed by number through a list called @ref{412e,,bpbynumber}
and by @code{(file, line)} pairs through @ref{412f,,bplist}.  The former points to
a single instance of class @ref{412d,,Breakpoint}.  The latter points to a list
of such instances since there may be more than one breakpoint per line.

When creating a breakpoint, its associated @ref{4130,,file name} should
be in canonical form.  If a @ref{4131,,funcname} is defined, a breakpoint
@ref{4132,,hit} will be counted when the first line of that function is
executed.  A @ref{4133,,conditional} breakpoint always counts a
@ref{4132,,hit}.

@ref{412d,,Breakpoint} instances have the following methods:

@geindex deleteMe() (méthode bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint deleteMe}@anchor{4134}
@deffn {Méthode} deleteMe ()

Delete the breakpoint from the list associated to a file/line.  If it is
the last breakpoint in that position, it also deletes the entry for the
file/line.
@end deffn

@geindex enable() (méthode bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint enable}@anchor{4135}
@deffn {Méthode} enable ()

Active le point d'arrêt.
@end deffn

@geindex disable() (méthode bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint disable}@anchor{4136}
@deffn {Méthode} disable ()

Désactive le point d'arrêt.
@end deffn

@geindex bpformat() (méthode bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bpformat}@anchor{4137}
@deffn {Méthode} bpformat ()

Return a string with all the information about the breakpoint, nicely
formatted:


@itemize *

@item 
Breakpoint number.

@item 
Temporary status (del or keep).

@item 
File/line position.

@item 
Break condition.

@item 
Number of times to ignore.

@item 
Number of times hit.
@end itemize


Ajouté dans la version 3.2.

@end deffn

@geindex bpprint() (méthode bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bpprint}@anchor{4138}
@deffn {Méthode} bpprint (out=None)

Print the output of @ref{4137,,bpformat()} to the file `out', or if it is
@code{None}, to standard output.
@end deffn

@ref{412d,,Breakpoint} instances have the following attributes:

@geindex file (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint file}@anchor{4130}
@deffn {Attribut} file

File name of the @ref{412d,,Breakpoint}.
@end deffn

@geindex line (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint line}@anchor{4139}
@deffn {Attribut} line

Line number of the @ref{412d,,Breakpoint} within @ref{4130,,file}.
@end deffn

@geindex temporary (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint temporary}@anchor{413a}
@deffn {Attribut} temporary

@code{True} if a @ref{412d,,Breakpoint} at (file, line) is temporary.
@end deffn

@geindex cond (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint cond}@anchor{4133}
@deffn {Attribut} cond

Condition for evaluating a @ref{412d,,Breakpoint} at (file, line).
@end deffn

@geindex funcname (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint funcname}@anchor{4131}
@deffn {Attribut} funcname

Function name that defines whether a @ref{412d,,Breakpoint} is hit upon
entering the function.
@end deffn

@geindex enabled (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint enabled}@anchor{413b}
@deffn {Attribut} enabled

@code{True} if @ref{412d,,Breakpoint} is enabled.
@end deffn

@geindex bpbynumber (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bpbynumber}@anchor{412e}
@deffn {Attribut} bpbynumber

Numeric index for a single instance of a @ref{412d,,Breakpoint}.
@end deffn

@geindex bplist (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint bplist}@anchor{412f}
@deffn {Attribut} bplist

Dictionary of @ref{412d,,Breakpoint} instances indexed by
(@ref{4130,,file}, @ref{4139,,line}) tuples.
@end deffn

@geindex ignore (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint ignore}@anchor{413c}
@deffn {Attribut} ignore

Number of times to ignore a @ref{412d,,Breakpoint}.
@end deffn

@geindex hits (attribut bdb.Breakpoint)
@anchor{library/bdb bdb Breakpoint hits}@anchor{4132}
@deffn {Attribut} hits

Count of the number of times a @ref{412d,,Breakpoint} has been hit.
@end deffn
@end deffn

@geindex Bdb (classe dans bdb)
@anchor{library/bdb bdb Bdb}@anchor{12e0}
@deffn {Classe} bdb.Bdb (skip=None)

The @ref{12e0,,Bdb} class acts as a generic Python debugger base class.

This class takes care of the details of the trace facility; a derived class
should implement user interaction.  The standard debugger class
(@ref{90f,,pdb.Pdb}) is an example.

The `skip' argument, if given, must be an iterable of glob-style
module name patterns.  The debugger will not step into frames that
originate in a module that matches one of these patterns. Whether a
frame is considered to originate in a certain module is determined
by the @code{__name__} in the frame globals.


Modifié dans la version 3.1: Added the `skip' parameter.


The following methods of @ref{12e0,,Bdb} normally don't need to be overridden.

@geindex canonic() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb canonic}@anchor{413d}
@deffn {Méthode} canonic (filename)

Return canonical form of `filename'.

For real file names, the canonical form is an operating-system-dependent,
@ref{275c,,case-normalized} @ref{12f9,,absolute path}. A `filename' with angle brackets, such as @code{"<stdin>"}
generated in interactive mode, is returned unchanged.
@end deffn

@geindex reset() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb reset}@anchor{413e}
@deffn {Méthode} reset ()

Set the @code{botframe}, @code{stopframe}, @code{returnframe} and
@ref{413f,,quitting} attributes with values ready to start debugging.
@end deffn

@geindex trace_dispatch() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb trace_dispatch}@anchor{4140}
@deffn {Méthode} trace_dispatch (frame, event, arg)

This function is installed as the trace function of debugged frames.  Its
return value is the new trace function (in most cases, that is, itself).

The default implementation decides how to dispatch a frame, depending on
the type of event (passed as a string) that is about to be executed.
`event' can be one of the following:


@itemize *

@item 
@code{"line"}: A new line of code is going to be executed.

@item 
@code{"call"}: A function is about to be called, or another code block
entered.

@item 
@code{"return"}: A function or other code block is about to return.

@item 
@code{"exception"} : Une exception est survenue.

@item 
@code{"c_call"} : Une fonction C est sur le point d'être appelée.

@item 
@code{"c_return"} : Une fonction C s'est terminée.

@item 
@code{"c_exception"}: A C function has raised an exception.
@end itemize

For the Python events, specialized functions (see below) are called.  For
the C events, no action is taken.

Le paramètre `arg' dépend de l'événement précédent.

See the documentation for @ref{14b6,,sys.settrace()} for more information on the
trace function.  For more information on code and frame objects, refer to
@ref{1e6a,,Hiérarchie des types standards}.
@end deffn

@geindex dispatch_line() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_line}@anchor{4141}
@deffn {Méthode} dispatch_line (frame)

If the debugger should stop on the current line, invoke the
@ref{4142,,user_line()} method (which should be overridden in subclasses).
Raise a @ref{412c,,BdbQuit} exception if the @ref{413f,,quitting} flag is set
(which can be set from @ref{4142,,user_line()}).  Return a reference to the
@ref{4140,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_call() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_call}@anchor{4143}
@deffn {Méthode} dispatch_call (frame, arg)

If the debugger should stop on this function call, invoke the
@ref{4144,,user_call()} method (which should be overridden in subclasses).
Raise a @ref{412c,,BdbQuit} exception if the @ref{413f,,quitting} flag is set
(which can be set from @ref{4144,,user_call()}).  Return a reference to the
@ref{4140,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_return() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_return}@anchor{4145}
@deffn {Méthode} dispatch_return (frame, arg)

If the debugger should stop on this function return, invoke the
@ref{4146,,user_return()} method (which should be overridden in subclasses).
Raise a @ref{412c,,BdbQuit} exception if the @ref{413f,,quitting} flag is set
(which can be set from @ref{4146,,user_return()}).  Return a reference to the
@ref{4140,,trace_dispatch()} method for further tracing in that scope.
@end deffn

@geindex dispatch_exception() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb dispatch_exception}@anchor{4147}
@deffn {Méthode} dispatch_exception (frame, arg)

If the debugger should stop at this exception, invokes the
@ref{4148,,user_exception()} method (which should be overridden in subclasses).
Raise a @ref{412c,,BdbQuit} exception if the @ref{413f,,quitting} flag is set
(which can be set from @ref{4148,,user_exception()}).  Return a reference to the
@ref{4140,,trace_dispatch()} method for further tracing in that scope.
@end deffn

Normally derived classes don't override the following methods, but they may
if they want to redefine the definition of stopping and breakpoints.

@geindex is_skipped_line() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb is_skipped_line}@anchor{4149}
@deffn {Méthode} is_skipped_line (module_name)

Return @code{True} if `module_name' matches any skip pattern.
@end deffn

@geindex stop_here() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb stop_here}@anchor{414a}
@deffn {Méthode} stop_here (frame)

Return @code{True} if `frame' is below the starting frame in the stack.
@end deffn

@geindex break_here() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb break_here}@anchor{414b}
@deffn {Méthode} break_here (frame)

Return @code{True} if there is an effective breakpoint for this line.

Check whether a line or function breakpoint exists and is in effect.  Delete temporary
breakpoints based on information from @ref{414c,,effective()}.
@end deffn

@geindex break_anywhere() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb break_anywhere}@anchor{414d}
@deffn {Méthode} break_anywhere (frame)

Return @code{True} if any breakpoint exists for `frame''s filename.
@end deffn

Derived classes should override these methods to gain control over debugger
operation.

@geindex user_call() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb user_call}@anchor{4144}
@deffn {Méthode} user_call (frame, argument_list)

Called from @ref{4143,,dispatch_call()} if a break might stop inside the
called function.

`argument_list' is not used anymore and will always be @code{None}.
The argument is kept for backwards compatibility.
@end deffn

@geindex user_line() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb user_line}@anchor{4142}
@deffn {Méthode} user_line (frame)

Called from @ref{4141,,dispatch_line()} when either @ref{414a,,stop_here()} or
@ref{414b,,break_here()} returns @code{True}.
@end deffn

@geindex user_return() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb user_return}@anchor{4146}
@deffn {Méthode} user_return (frame, return_value)

Called from @ref{4145,,dispatch_return()} when @ref{414a,,stop_here()} returns @code{True}.
@end deffn

@geindex user_exception() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb user_exception}@anchor{4148}
@deffn {Méthode} user_exception (frame, exc_info)

Called from @ref{4147,,dispatch_exception()} when @ref{414a,,stop_here()}
returns @code{True}.
@end deffn

@geindex do_clear() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb do_clear}@anchor{414e}
@deffn {Méthode} do_clear (arg)

Handle how a breakpoint must be removed when it is a temporary one.

This method must be implemented by derived classes.
@end deffn

Derived classes and clients can call the following methods to affect the
stepping state.

@geindex set_step() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_step}@anchor{414f}
@deffn {Méthode} set_step ()

Arrête après une ligne de code.
@end deffn

@geindex set_next() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_next}@anchor{4150}
@deffn {Méthode} set_next (frame)

Stop on the next line in or below the given frame.
@end deffn

@geindex set_return() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_return}@anchor{4151}
@deffn {Méthode} set_return (frame)

Stop when returning from the given frame.
@end deffn

@geindex set_until() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_until}@anchor{4152}
@deffn {Méthode} set_until (frame, lineno=None)

Stop when the line with the `lineno' greater than the current one is
reached or when returning from current frame.
@end deffn

@geindex set_trace() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_trace}@anchor{4153}
@deffn {Méthode} set_trace ([frame])

Start debugging from `frame'.  If `frame' is not specified, debugging
starts from caller's frame.


Modifié dans la version 3.13: @ref{4154,,set_trace()} will enter the debugger immediately, rather than
on the next line of code to be executed.

@end deffn

@geindex set_continue() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_continue}@anchor{4155}
@deffn {Méthode} set_continue ()

Stop only at breakpoints or when finished.  If there are no breakpoints,
set the system trace function to @code{None}.
@end deffn

@geindex set_quit() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_quit}@anchor{413f}
@deffn {Méthode} set_quit ()

@geindex quitting (bdb.Bdb attribute)

Set the @code{quitting} attribute to @code{True}.  This raises @ref{412c,,BdbQuit} in
the next call to one of the @code{dispatch_*()} methods.
@end deffn

Derived classes and clients can call the following methods to manipulate
breakpoints.  These methods return a string containing an error message if
something went wrong, or @code{None} if all is well.

@geindex set_break() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb set_break}@anchor{4156}
@deffn {Méthode} set_break (filename, lineno, temporary=False, cond=None, funcname=None)

Set a new breakpoint.  If the `lineno' line doesn't exist for the
`filename' passed as argument, return an error message.  The `filename'
should be in canonical form, as described in the @ref{413d,,canonic()} method.
@end deffn

@geindex clear_break() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_break}@anchor{4157}
@deffn {Méthode} clear_break (filename, lineno)

Delete the breakpoints in `filename' and `lineno'.  If none were set,
return an error message.
@end deffn

@geindex clear_bpbynumber() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_bpbynumber}@anchor{4158}
@deffn {Méthode} clear_bpbynumber (arg)

Delete the breakpoint which has the index `arg' in the
@ref{412e,,Breakpoint.bpbynumber}.  If `arg' is not numeric or out of range,
return an error message.
@end deffn

@geindex clear_all_file_breaks() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_all_file_breaks}@anchor{4159}
@deffn {Méthode} clear_all_file_breaks (filename)

Delete all breakpoints in `filename'.  If none were set, return an error
message.
@end deffn

@geindex clear_all_breaks() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb clear_all_breaks}@anchor{415a}
@deffn {Méthode} clear_all_breaks ()

Delete all existing breakpoints.  If none were set, return an error
message.
@end deffn

@geindex get_bpbynumber() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb get_bpbynumber}@anchor{415b}
@deffn {Méthode} get_bpbynumber (arg)

Return a breakpoint specified by the given number.  If `arg' is a string,
it will be converted to a number.  If `arg' is a non-numeric string, if
the given breakpoint never existed or has been deleted, a
@ref{1ff,,ValueError} is raised.


Ajouté dans la version 3.2.

@end deffn

@geindex get_break() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb get_break}@anchor{415c}
@deffn {Méthode} get_break (filename, lineno)

Return @code{True} if there is a breakpoint for `lineno' in `filename'.
@end deffn

@geindex get_breaks() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb get_breaks}@anchor{415d}
@deffn {Méthode} get_breaks (filename, lineno)

Return all breakpoints for `lineno' in `filename', or an empty list if
none are set.
@end deffn

@geindex get_file_breaks() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb get_file_breaks}@anchor{415e}
@deffn {Méthode} get_file_breaks (filename)

Return all breakpoints in `filename', or an empty list if none are set.
@end deffn

@geindex get_all_breaks() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb get_all_breaks}@anchor{415f}
@deffn {Méthode} get_all_breaks ()

Donne tous les points d'arrêt définis.
@end deffn

Derived classes and clients can call the following methods to get a data
structure representing a stack trace.

@geindex get_stack() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb get_stack}@anchor{4160}
@deffn {Méthode} get_stack (f, t)

Return a list of (frame, lineno) tuples in a stack trace, and a size.

The most recently called frame is last in the list. The size is the number
of frames below the frame where the debugger was invoked.
@end deffn

@geindex format_stack_entry() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb format_stack_entry}@anchor{4161}
@deffn {Méthode} format_stack_entry (frame_lineno, lprefix=': ')

Return a string with information about a stack entry, which is a
@code{(frame, lineno)} tuple.  The return string contains:


@itemize *

@item 
The canonical filename which contains the frame.

@item 
The function name or @code{"<lambda>"}.

@item 
Les arguments donnés.

@item 
Le résultat.

@item 
La ligne de code (si elle existe).
@end itemize
@end deffn

The following two methods can be called by clients to use a debugger to debug
a @ref{2704,,statement}, given as a string.

@geindex run() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb run}@anchor{4162}
@deffn {Méthode} run (cmd, globals=None, locals=None)

Debug a statement executed via the @ref{17d,,exec()} function.  `globals'
defaults to @code{__main__.__dict__}, `locals' defaults to `globals'.
@end deffn

@geindex runeval() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb runeval}@anchor{4163}
@deffn {Méthode} runeval (expr, globals=None, locals=None)

Debug an expression executed via the @ref{17e,,eval()} function.  `globals' and
`locals' have the same meaning as in @ref{4162,,run()}.
@end deffn

@geindex runctx() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb runctx}@anchor{4164}
@deffn {Méthode} runctx (cmd, globals, locals)

For backwards compatibility.  Calls the @ref{4162,,run()} method.
@end deffn

@geindex runcall() (méthode bdb.Bdb)
@anchor{library/bdb bdb Bdb runcall}@anchor{a6c}
@deffn {Méthode} runcall (func, /, *args, **kwds)

Debug a single function call, and return its result.
@end deffn
@end deffn

Finally, the module defines the following functions:

@geindex checkfuncname() (dans le module bdb)
@anchor{library/bdb bdb checkfuncname}@anchor{4165}
@deffn {Fonction} bdb.checkfuncname (b, frame)

Return @code{True} if we should break here, depending on the way the
@ref{412d,,Breakpoint} `b' was set.

If it was set via line number, it checks if
@ref{4139,,b.line} is the same as the one in `frame'.
If the breakpoint was set via
@ref{4131,,function name}, we have to check we are in
the right `frame' (the right function) and if we are on its first executable
line.
@end deffn

@geindex effective() (dans le module bdb)
@anchor{library/bdb bdb effective}@anchor{414c}
@deffn {Fonction} bdb.effective (file, line, frame)

Return @code{(active breakpoint, delete temporary flag)} or @code{(None, None)} as the
breakpoint to act upon.

The `active breakpoint' is the first entry in
@ref{412f,,bplist} for the
(@ref{4130,,file}, @ref{4139,,line})
(which must exist) that is @ref{413b,,enabled}, for
which @ref{4165,,checkfuncname()} is true, and that has neither a false
@ref{4133,,condition} nor positive
@ref{413c,,ignore} count.  The `flag', meaning that a
temporary breakpoint should be deleted, is @code{False} only when the
@ref{4133,,cond} cannot be evaluated (in which case,
@ref{413c,,ignore} count is ignored).

If no such entry exists, then @code{(None, None)} is returned.
@end deffn

@geindex set_trace() (dans le module bdb)
@anchor{library/bdb bdb set_trace}@anchor{4154}
@deffn {Fonction} bdb.set_trace ()

Start debugging with a @ref{12e0,,Bdb} instance from caller's frame.
@end deffn

@node faulthandler --- Dump the Python traceback,pdb — Le débogueur Python,bdb --- Debugger framework,Débogueur et instrumentation
@anchor{library/faulthandler doc}@anchor{4166}@anchor{library/faulthandler faulthandler-dump-the-python-traceback}@anchor{4167}@anchor{library/faulthandler module-faulthandler}@anchor{57}
@subsection @code{faulthandler} --- Dump the Python traceback


@geindex module; faulthandler


Ajouté dans la version 3.3.



__________________________________________________________________


This module contains functions to dump Python tracebacks explicitly, on a fault,
after a timeout, or on a user signal. Call @ref{c8c,,faulthandler.enable()} to
install fault handlers for the @ref{1cd5,,SIGSEGV},
@ref{1cd6,,SIGFPE}, @ref{1cd7,,SIGABRT}, @ref{1cd8,,SIGBUS}, and
@ref{1cd9,,SIGILL} signals. You can also
enable them at startup by setting the 
@geindex PYTHONFAULTHANDLER
@geindex variable d'environnement; PYTHONFAULTHANDLER
@ref{1069,,PYTHONFAULTHANDLER} environment
variable or by using the @ref{175,,-X} @code{faulthandler} command line option.

The fault handler is compatible with system fault handlers like Apport or the
Windows fault handler. The module uses an alternative stack for signal handlers
if the @code{sigaltstack()} function is available. This allows it to dump the
traceback even on a stack overflow.

The fault handler is called on catastrophic cases and therefore can only use
signal-safe functions (e.g. it cannot allocate memory on the heap). Because of
this limitation traceback dumping is minimal compared to normal Python
tracebacks:


@itemize *

@item 
Only ASCII is supported. The @code{backslashreplace} error handler is used on
encoding.

@item 
Each string is limited to 500 characters.

@item 
Only the filename, the function name and the line number are
displayed. (no source code)

@item 
It is limited to 100 frames and 100 threads.

@item 
The order is reversed: the most recent call is shown first.
@end itemize

By default, the Python traceback is written to @ref{926,,sys.stderr}. To see
tracebacks, applications must be run in the terminal. A log file can
alternatively be passed to @ref{c8c,,faulthandler.enable()}.

The module is implemented in C, so tracebacks can be dumped on a crash or when
Python is deadlocked.

The @ref{1f5,,Python Development Mode} calls @ref{c8c,,faulthandler.enable()}
at Python startup.


@subsubheading Voir aussi



@table @asis

@item Module @ref{a4,,pdb}

Interactive source code debugger for Python programs.

@item Module @ref{fd,,traceback}

Standard interface to extract, format and print stack traces of Python programs.
@end table


@menu
* Dumping the traceback:: 
* Fault handler state:: 
* Dumping the tracebacks after a timeout:: 
* Dumping the traceback on a user signal:: 
* Issue with file descriptors:: 
* Exemple: Exemple<14>. 

@end menu

@node Dumping the traceback,Fault handler state,,faulthandler --- Dump the Python traceback
@anchor{library/faulthandler dumping-the-traceback}@anchor{4168}
@subsubsection Dumping the traceback


@geindex dump_traceback() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler dump_traceback}@anchor{deb}
@deffn {Fonction} faulthandler.dump_traceback (file=sys.stderr, all_threads=True)

Dump the tracebacks of all threads into `file'. If `all_threads' is
@code{False}, dump only the current thread.


@subsubheading Voir aussi


@ref{e70,,traceback.print_tb()}, which can be used to print a traceback object.



Modifié dans la version 3.5: Added support for passing file descriptor to this function.

@end deffn

@node Fault handler state,Dumping the tracebacks after a timeout,Dumping the traceback,faulthandler --- Dump the Python traceback
@anchor{library/faulthandler fault-handler-state}@anchor{4169}
@subsubsection Fault handler state


@geindex enable() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler enable}@anchor{c8c}
@deffn {Fonction} faulthandler.enable (file=sys.stderr, all_threads=True)

Enable the fault handler: install handlers for the @ref{1cd5,,SIGSEGV},
@ref{1cd6,,SIGFPE}, @ref{1cd7,,SIGABRT}, @ref{1cd8,,SIGBUS}
and @ref{1cd9,,SIGILL}
signals to dump the Python traceback. If `all_threads' is @code{True},
produce tracebacks for every running thread. Otherwise, dump only the current
thread.

The `file' must be kept open until the fault handler is disabled: see
@ref{416a,,issue with file descriptors}.


Modifié dans la version 3.5: Added support for passing file descriptor to this function.



Modifié dans la version 3.6: On Windows, a handler for Windows exception is also installed.



Modifié dans la version 3.10: The dump now mentions if a garbage collector collection is running
if `all_threads' is true.

@end deffn

@geindex disable() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler disable}@anchor{416b}
@deffn {Fonction} faulthandler.disable ()

Disable the fault handler: uninstall the signal handlers installed by
@ref{c8c,,enable()}.
@end deffn

@geindex is_enabled() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler is_enabled}@anchor{416c}
@deffn {Fonction} faulthandler.is_enabled ()

Check if the fault handler is enabled.
@end deffn

@node Dumping the tracebacks after a timeout,Dumping the traceback on a user signal,Fault handler state,faulthandler --- Dump the Python traceback
@anchor{library/faulthandler dumping-the-tracebacks-after-a-timeout}@anchor{416d}
@subsubsection Dumping the tracebacks after a timeout


@geindex dump_traceback_later() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler dump_traceback_later}@anchor{dec}
@deffn {Fonction} faulthandler.dump_traceback_later (timeout, repeat=False, file=sys.stderr, exit=False)

Dump the tracebacks of all threads, after a timeout of `timeout' seconds, or
every `timeout' seconds if `repeat' is @code{True}.  If `exit' is @code{True}, call
@code{_exit()} with status=1 after dumping the tracebacks.  (Note
@code{_exit()} exits the process immediately, which means it doesn't do any
cleanup like flushing file buffers.) If the function is called twice, the new
call replaces previous parameters and resets the timeout. The timer has a
sub-second resolution.

The `file' must be kept open until the traceback is dumped or
@ref{416e,,cancel_dump_traceback_later()} is called: see @ref{416a,,issue with file descriptors}.

This function is implemented using a watchdog thread.


Modifié dans la version 3.5: Added support for passing file descriptor to this function.



Modifié dans la version 3.7: This function is now always available.

@end deffn

@geindex cancel_dump_traceback_later() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler cancel_dump_traceback_later}@anchor{416e}
@deffn {Fonction} faulthandler.cancel_dump_traceback_later ()

Cancel the last call to @ref{dec,,dump_traceback_later()}.
@end deffn

@node Dumping the traceback on a user signal,Issue with file descriptors,Dumping the tracebacks after a timeout,faulthandler --- Dump the Python traceback
@anchor{library/faulthandler dumping-the-traceback-on-a-user-signal}@anchor{416f}
@subsubsection Dumping the traceback on a user signal


@geindex register() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler register}@anchor{dea}
@deffn {Fonction} faulthandler.register (signum, file=sys.stderr, all_threads=True, chain=False)

Register a user signal: install a handler for the `signum' signal to dump
the traceback of all threads, or of the current thread if `all_threads' is
@code{False}, into `file'. Call the previous handler if chain is @code{True}.

The `file' must be kept open until the signal is unregistered by
@ref{4170,,unregister()}: see @ref{416a,,issue with file descriptors}.

Not available on Windows.


Modifié dans la version 3.5: Added support for passing file descriptor to this function.

@end deffn

@geindex unregister() (dans le module faulthandler)
@anchor{library/faulthandler faulthandler unregister}@anchor{4170}
@deffn {Fonction} faulthandler.unregister (signum)

Unregister a user signal: uninstall the handler of the `signum' signal
installed by @ref{dea,,register()}. Return @code{True} if the signal was registered,
@code{False} otherwise.

Not available on Windows.
@end deffn

@node Issue with file descriptors,Exemple<14>,Dumping the traceback on a user signal,faulthandler --- Dump the Python traceback
@anchor{library/faulthandler faulthandler-fd}@anchor{416a}@anchor{library/faulthandler issue-with-file-descriptors}@anchor{4171}
@subsubsection Issue with file descriptors


@ref{c8c,,enable()}, @ref{dec,,dump_traceback_later()} and @ref{dea,,register()} keep the
file descriptor of their `file' argument. If the file is closed and its file
descriptor is reused by a new file, or if @ref{b51,,os.dup2()} is used to replace
the file descriptor, the traceback will be written into a different file. Call
these functions again each time that the file is replaced.

@node Exemple<14>,,Issue with file descriptors,faulthandler --- Dump the Python traceback
@anchor{library/faulthandler example}@anchor{4172}
@subsubsection Exemple


Example of a segmentation fault on Linux with and without enabling the fault
handler:

@example
$ python -c "import ctypes; ctypes.string_at(0)"
Segmentation fault

$ python -q -X faulthandler
>>> import ctypes
>>> ctypes.string_at(0)
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 "<stdin>", line 1 in <module>
Segmentation fault
@end example

@node pdb — Le débogueur Python,The Python Profilers,faulthandler --- Dump the Python traceback,Débogueur et instrumentation
@anchor{library/pdb doc}@anchor{4173}@anchor{library/pdb debugger}@anchor{4174}@anchor{library/pdb module-pdb}@anchor{a4}@anchor{library/pdb pdb-the-python-debugger}@anchor{4175}
@subsection @code{pdb} — Le débogueur Python


@geindex module; pdb

`Code source :' Lib/pdb.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pdb.py}

@geindex debugging


__________________________________________________________________


Le module @ref{a4,,pdb} définit un débogueur de code source interactif pour les programmes Python. Il supporte le paramétrage (conditionnel) de points d'arrêt et l'exécution du code source ligne par ligne, l'inspection des `frames' de la pile, la liste du code source, et l'évaluation arbitraire de code Python dans le contexte de n'importe quelle `frame' de la pile. Il supporte aussi le débogage post-mortem et peut être contrôlé depuis un programme.

@geindex Pdb (class in pdb)
@geindex module;bdb
@geindex module;cmd

Le débogueur est extensible -- Il est en réalité défini comme la classe @ref{90f,,Pdb}. C'est actuellement non-documenté mais facilement compréhensible en lisant le code source. L'interface d'extension utilise les modules @ref{f,,bdb} et @ref{19,,cmd}.


@subsubheading Voir aussi



@table @asis

@item Module @ref{57,,faulthandler}

Used to dump Python tracebacks explicitly, on a fault, after a timeout,
or on a user signal.

@item Module @ref{fd,,traceback}

Standard interface to extract, format and print stack traces of Python programs.
@end table


The typical usage to break into the debugger is to insert:

@example
import pdb; pdb.set_trace()
@end example

Or:

@example
breakpoint()
@end example

at the location you want to break into the debugger, and then run the program.
You can then step through the code following this statement, and continue
running without the debugger using the @ref{4176,,continue} command.


Modifié dans la version 3.7: The built-in @ref{231,,breakpoint()}, when called with defaults, can be used
instead of @code{import pdb; pdb.set_trace()}.


@example
def double(x):
   breakpoint()
   return x * 2
val = 3
print(f"@{val@} * 2 is @{double(val)@}")
@end example

The debugger's prompt is @code{(Pdb)}, which is the indicator that you are in debug mode:

@example
> ...(2)double()
-> breakpoint()
(Pdb) p x
3
(Pdb) continue
3 * 2 is 6
@end example


Modifié dans la version 3.3: La complétion via le module @ref{b9,,readline} est disponible pour les commandes et les arguments de commande, par exemple les noms `global' et `local' sont proposés comme arguments de la commande @code{p}.


You can also invoke @ref{a4,,pdb} from the command line to debug other scripts.  For
example:

@example
python -m pdb myscript.py
@end example

When invoked as a module, pdb will automatically enter post-mortem debugging if
the program being debugged exits abnormally.  After post-mortem debugging (or
after normal exit of the program), pdb will restart the program.  Automatic
restarting preserves pdb's state (such as breakpoints) and in most cases is more
useful than quitting the debugger upon program's exit.


Modifié dans la version 3.2: Added the @code{-c} option to execute commands as if given
in a @code{.pdbrc} file; see @ref{4177,,Commande du débogueur}.



Modifié dans la version 3.7: Added the @code{-m} option to execute modules similar to the way
@code{python -m} does. As with a script, the debugger will pause execution just
before the first line of the module.


Typical usage to execute a statement under control of the debugger is:

@example
>>> import pdb
>>> def f(x):
...     print(1 / x)
>>> pdb.run("f(2)")
> <string>(1)<module>()
(Pdb) continue
0.5
>>>
@end example

L'usage typique pour inspecter un programme planté :

@example
>>> import pdb
>>> def f(x):
...     print(1 / x)
...
>>> f(0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
ZeroDivisionError: division by zero
>>> pdb.pm()
> <stdin>(2)f()
(Pdb) p x
0
(Pdb)
@end example


Modifié dans la version 3.13: The implementation of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/} means that name assignments made via @code{pdb}
will immediately affect the active scope, even when running inside an
@ref{17c,,optimized scope}.


Le module définit les fonctions suivantes; chacune entre dans le débogueur d'une manière légèrement différente :

@geindex run() (dans le module pdb)
@anchor{library/pdb pdb run}@anchor{3f7f}
@deffn {Fonction} pdb.run (statement, globals=None, locals=None)

Exécute la `déclaration' (donnée sous forme de chaîne de caractères ou d'objet code) sous le contrôle du débogueur. L'invite de débogage apparaît avant l'exécution de tout code; vous pouvez définir des points d'arrêt et taper @ref{4176,,continue}, ou vous pouvez passer à travers l'instruction en utilisant @ref{4178,,step} ou @ref{4179,,next} (toutes ces commandes sont expliquées ci-dessous). Les arguments `globals' et `locals' optionnels spécifient l'environnement dans lequel le code est exécuté; par défaut le dictionnaire du module @ref{1,,__main__} est utilisé. (Voir l'explication des fonctions natives @ref{17d,,exec()} ou @ref{17e,,eval()}.)
@end deffn

@geindex runeval() (dans le module pdb)
@anchor{library/pdb pdb runeval}@anchor{417a}
@deffn {Fonction} pdb.runeval (expression, globals=None, locals=None)

Evaluate the `expression' (given as a string or a code object) under debugger
control.  When @ref{417a,,runeval()} returns, it returns the value of the
`expression'.  Otherwise this function is similar to @ref{3f7f,,run()}.
@end deffn

@geindex runcall() (dans le module pdb)
@anchor{library/pdb pdb runcall}@anchor{417b}
@deffn {Fonction} pdb.runcall (function, *args, **kwds)

Appelle la `function' (une fonction ou une méthode, pas une chaine de caractères) avec les arguments donnés. Quand @ref{417b,,runcall()} revient, il retourne ce que l'appel de fonctionne a renvoyé. L'invite de débogage apparaît dès que la fonction est entrée.
@end deffn

@geindex set_trace() (dans le module pdb)
@anchor{library/pdb pdb set_trace}@anchor{232}
@deffn {Fonction} pdb.set_trace (*, header=None)

Invoque le débogueur dans la cadre d'exécution appelant. C'est utile pour coder en dur un point d'arrêt dans un programme, même si le code n'est pas autrement débogué (par exemple, quand une assertion échoue). S'il est donné, `header' est affiché sur la console juste avant que le débogage commence.


Modifié dans la version 3.7: L’argument `keyword-only' `header'.



Modifié dans la version 3.13: @ref{232,,set_trace()} will enter the debugger immediately, rather than
on the next line of code to be executed.

@end deffn

@geindex post_mortem() (dans le module pdb)
@anchor{library/pdb pdb post_mortem}@anchor{1391}
@deffn {Fonction} pdb.post_mortem (traceback=None)

Entre le débogage post-mortem de l'objet `traceback' donné. Si aucun `traceback' n'est donné, il utilise celui de l'exception en cours de traitement (une exception doit être gérée si la valeur par défaut doit être utilisée).
@end deffn

@geindex pm() (dans le module pdb)
@anchor{library/pdb pdb pm}@anchor{234}
@deffn {Fonction} pdb.pm ()

Enter post-mortem debugging of the exception found in
@ref{4a7,,sys.last_exc}.
@end deffn

Les fonctions @code{run*} et @ref{232,,set_trace()} sont des alias pour instancier la classe @ref{90f,,Pdb} et appeler la méthode du même nom. Si vous souhaitez accéder à d'autres fonctionnalités, vous devez le faire vous-même :

@geindex Pdb (classe dans pdb)
@anchor{library/pdb pdb Pdb}@anchor{90f}
@deffn {Classe} pdb.Pdb (completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True)

Le classe du débogueur est la classe @ref{90f,,Pdb}.

Les arguments `completekey', `stdin' et `stdout' sont transmis à la classe sous-jacente @ref{164f,,cmd.Cmd}; voir la description ici.

L'argument `skip', s'il est donné, doit être un itérable des noms de modules de style `glob'. Le débogueur n'entrera pas dans les `frames' qui proviennent d'un module qui correspond à l'un de ces motifs. @footnote{
La question de savoir si une `frame' est considérée comme provenant d'un certain module est déterminée par le @code{__name__} dans les globales de la `frame'.
}

By default, Pdb sets a handler for the SIGINT signal (which is sent when the
user presses @code{Ctrl-C} on the console) when you give a @ref{4176,,continue} command.
This allows you to break into the debugger again by pressing @code{Ctrl-C}.  If you
want Pdb not to touch the SIGINT handler, set `nosigint' to true.

L'argument `readrc' vaut `True' par défaut et contrôle si Pdb chargera les fichiers `.pdbrc' depuis le système de fichiers.

Exemple d'appel pour activer le traçage avec `skip' :

@example
import pdb; pdb.Pdb(skip=['django.*']).set_trace()
@end example

Lève un @ref{1848,,évènement d'audit} @code{pdb.Pdb} sans argument.


Modifié dans la version 3.1: Added the `skip' parameter.



Modifié dans la version 3.2: Added the `nosigint' parameter.
Previously, a SIGINT handler was never set by Pdb.



Modifié dans la version 3.6: L'argument `readrc'.


@geindex run() (méthode pdb.Pdb)
@geindex runeval() (méthode pdb.Pdb)
@geindex runcall() (méthode pdb.Pdb)
@geindex set_trace() (méthode pdb.Pdb)
@anchor{library/pdb pdb Pdb run}@anchor{417c}
@deffn {Méthode} run (statement, globals=None, locals=None)
@anchor{library/pdb pdb Pdb runeval}@anchor{417d}
@deffnx {Méthode} runeval (expression, globals=None, locals=None)
@anchor{library/pdb pdb Pdb runcall}@anchor{417e}
@deffnx {Méthode} runcall (function, *args, **kwds)
@anchor{library/pdb pdb Pdb set_trace}@anchor{417f}
@deffnx {Méthode} set_trace ()

Voir la documentation pour les fonctions expliquées ci-dessus.
@end deffn
@end deffn

@menu
* Commande du débogueur:: 

@end menu

@node Commande du débogueur,,,pdb — Le débogueur Python
@anchor{library/pdb debugger-commands}@anchor{4177}@anchor{library/pdb id2}@anchor{4180}
@subsubsection Commande du débogueur


Les commandes reconnues par le débogueur sont listées. La plupart des commandes peuvent être abrégées à une ou deux lettres comme indiquées; par exemple. @code{h(elp)} signifie que soit @code{h} ou @code{help} peut être utilisée pour entrer la commande `help' (mais pas @code{he} or @code{hel}, ni @code{H} ou @code{HELP}). Les arguments des commandes doivent être séparées par des espaces (espaces ou tabulations). Les arguments optionnels sont entourés dans des crochets (@code{[]}) dans la syntaxe de la commande; les crochets ne doivent pas être insérés. Les alternatives dans la syntaxe de la commande sont séparés par une barre verticale (@code{|}).

Entrer une ligne vide répète la dernière commande entrée. Exception: si la dernière commande était la commande @ref{4181,,list}, les 11 prochaines lignes sont affichées.

Les commandes que le débogueur ne reconnaît pas sont supposées être des instructions Python et sont exécutées dans le contexte du programme en cours de débogage. Les instructions Python peuvent également être préfixées avec un point d'exclamation (@code{!}). C'est une façon puissante d'inspecter le programme en cours de débogage; il est même possible de changer une variable ou d'appeler une fonction. Lorsqu'une exception se produit dans une telle instruction, le nom de l'exception est affiché mais l'état du débogueur n'est pas modifié.


Modifié dans la version 3.13: Expressions/Statements whose prefix is a pdb command are now correctly
identified and executed.


Le débogueur supporte @ref{4182,,aliases}. Les alias peuvent avoir des paramètres qui permettent un certain niveau d'adaptabilité au contexte étudié.

Multiple commands may be entered on a single line, separated by @code{;;}.  (A
single @code{;} is not used as it is the separator for multiple commands in a line
that is passed to the Python parser.)  No intelligence is applied to separating
the commands; the input is split at the first @code{;;} pair, even if it is in the
middle of a quoted string. A workaround for strings with double semicolons
is to use implicit string concatenation @code{';'@w{'};'} or @code{";"";"}.

To set a temporary global variable, use a `convenience variable'. A `convenience
variable' is a variable whose name starts with @code{$}.  For example, @code{$foo = 1}
sets a global variable @code{$foo} which you can use in the debugger session.  The
`convenience variables' are cleared when the program resumes execution so it's
less likely to interfere with your program compared to using normal variables
like @code{foo = 1}.

There are three preset `convenience variables':


@itemize *

@item 
@code{$_frame}: the current frame you are debugging

@item 
@code{$_retval}: the return value if the frame is returning

@item 
@code{$_exception}: the exception if the frame is raising an exception
@end itemize


Ajouté dans la version 3.12: Added the `convenience variable' feature.


@geindex .pdbrc;file
@geindex debugger;configuration;file

If a file @code{.pdbrc} exists in the user's home directory or in the current
directory, it is read with @code{'utf-8'} encoding and executed as if it had been
typed at the debugger prompt, with the exception that empty lines and lines
starting with @code{#} are ignored.  This is particularly useful for aliases.  If both
files exist, the one in the home directory is read first and aliases defined there
can be overridden by the local file.


Modifié dans la version 3.2: Le fichier @code{.pdbrc} peut maintenant contenir des commandes qui continue le débogage, comme @ref{4176,,continue} ou @ref{4179,,next}. Précédemment, ces commandes n'avaient aucun effet.



Modifié dans la version 3.11: @code{.pdbrc} is now read with @code{'utf-8'} encoding. Previously, it was read
with the system locale encoding.


@geindex help (pdb command)
@anchor{library/pdb pdbcommand-help}@anchor{4183}
@deffn {Pdbcommand} h(elp) [command]

Sans argument, affiche la liste des commandes disponibles. Avec une `commande' comme argument, affiche l'aide de cette commande. @code{help pdb} affiche la documentation complète (la `docstring' du module @ref{a4,,pdb}). Puisque l'argument `command' doit être un identificateur, @code{help exec} doit être entré pour obtenir de l'aide sur la commande @code{!}.
@end deffn

@geindex where (pdb command)
@anchor{library/pdb pdbcommand-where}@anchor{4184}
@deffn {Pdbcommand} w(here)

Print a stack trace, with the most recent frame at the bottom.  An arrow (@code{>})
indicates the current frame, which determines the context of most commands.
@end deffn

@geindex down (pdb command)
@anchor{library/pdb pdbcommand-down}@anchor{4185}
@deffn {Pdbcommand} d(own) [count]

Déplace le niveau de la `frame' courante `count' (par défaut un) vers le bas dans la trace de pile (vers une `frame' plus récente).
@end deffn

@geindex up (pdb command)
@anchor{library/pdb pdbcommand-up}@anchor{4186}
@deffn {Pdbcommand} u(p) [count]

Déplace le niveau de la `frame' courante `count' (par défaut un) vers le haut dans la trace de pile (vers une `frame' plus ancienne).
@end deffn

@geindex break (pdb command)
@anchor{library/pdb pdbcommand-break}@anchor{4187}
@deffn {Pdbcommand} b(reak) [([filename:]lineno | function) [, condition]]

With a `lineno' argument, set a break at line `lineno' in the current file.
The line number may be prefixed with a `filename' and a colon,
to specify a breakpoint in another file (possibly one that hasn't been loaded
yet).  The file is searched on @ref{3ab,,sys.path}.  Accepatable forms of `filename'
are @code{/abspath/to/file.py}, @code{relpath/file.py}, @code{module} and
@code{package.module}.

With a `function' argument, set a break at the first executable statement within
that function. `function' can be any expression that evaluates to a function
in the current namespace.

Si un second argument est présent, c'est une expression qui doit évaluer à `True' avant que le point d'arrêt ne soit honoré.

Sans argument, liste tous les arrêts, incluant pour chaque point d'arrêt, le nombre de fois qu'un point d'arrêt a été atteint, le nombre de ignore, et la condition associée le cas échéant.

Each breakpoint is assigned a number to which all the other
breakpoint commands refer.
@end deffn

@geindex tbreak (pdb command)
@anchor{library/pdb pdbcommand-tbreak}@anchor{4188}
@deffn {Pdbcommand} tbreak [([filename:]lineno | function) [, condition]]

Point d'arrêt temporaire, qui est enlevé automatiquement au premier passage. Les arguments sont les mêmes que pour @ref{4187,,break}.
@end deffn

@geindex clear (pdb command)
@anchor{library/pdb pdbcommand-clear}@anchor{4189}
@deffn {Pdbcommand} cl(ear) [filename:lineno | bpnumber ...]

Avec un argument `filename:lineno', efface tous les points d'arrêt sur cette ligne. Avec une liste de numéros de points d'arrêt séparés par un espace, efface ces points d'arrêt. Sans argument, efface tous les points d'arrêt (mais demande d'abord confirmation).
@end deffn

@geindex disable (pdb command)
@anchor{library/pdb pdbcommand-disable}@anchor{418a}
@deffn {Pdbcommand} disable bpnumber [bpnumber ...]

Désactive les points d'arrêt indiqués sous la forme d'une liste de numéros de points d'arrêt séparés par un espace. Désactiver un point d'arrêt signifie qu'il ne peut pas interrompre l'exécution du programme, mais à la différence d'effacer un point d'arrêt, il reste dans la liste des points d'arrêt et peut être (ré)activé.
@end deffn

@geindex enable (pdb command)
@anchor{library/pdb pdbcommand-enable}@anchor{418b}
@deffn {Pdbcommand} enable bpnumber [bpnumber ...]

Active les points d'arrêt spécifiés.
@end deffn

@geindex ignore (pdb command)
@anchor{library/pdb pdbcommand-ignore}@anchor{418c}
@deffn {Pdbcommand} ignore bpnumber [count]

Set the ignore count for the given breakpoint number.  If `count' is omitted,
the ignore count is set to 0.  A breakpoint becomes active when the ignore
count is zero.  When non-zero, the `count' is decremented each time the
breakpoint is reached and the breakpoint is not disabled and any associated
condition evaluates to true.
@end deffn

@geindex condition (pdb command)
@anchor{library/pdb pdbcommand-condition}@anchor{418d}
@deffn {Pdbcommand} condition bpnumber [condition]

Définit une nouvelle `condition' pour le point d'arrêt, une expression qui doit évaluer à `True' avant que le point d'arrêt ne soit honoré. Si `condition' est absente, toute condition existante est supprimée, c'est-à-dire que le point d'arrêt est rendu inconditionnel.
@end deffn

@geindex commands (pdb command)
@anchor{library/pdb pdbcommand-commands}@anchor{418e}
@deffn {Pdbcommand} commands [bpnumber]

Spécifie une liste de commandes pour le numéro du point d'arrêt `bpnumber'. Les commandes elles-mêmes apparaissent sur les lignes suivantes. Tapez une ligne contenant juste @code{end} pour terminer les commandes. Un exemple :

@example
(Pdb) commands 1
(com) p some_variable
(com) end
(Pdb)
@end example

Pour supprimer toutes les commandes depuis un point d'arrêt, écrivez @code{commands} suivi immédiatement de @code{end} ; ceci supprime les commandes.

Sans argument `bpnumber', @code{commands} se réfère au dernier point d'arrêt défini.

Vous pouvez utiliser les commandes de point d'arrêt pour redémarrer votre programme.  Utilisez simplement la commande @ref{4176,,continue}, ou @ref{4178,,step}, ou toute autre commande qui reprend l'exécution.

Entrer toute commande reprenant l'exécution (actuellement @ref{4176,,continue}, @ref{4178,,step}, @ref{4179,,next}, @ref{418f,,return}, @ref{4190,,jump}, @ref{4191,,quit} et leurs abréviations) termine la liste des commandes (comme si cette commande était immédiatement suivie de la fin). C'est parce que chaque fois que vous reprenez l'exécution (même avec un simple `next' ou `step'), vous pouvez rencontrer un autre point d'arrêt -- qui pourrait avoir sa propre liste de commandes, conduisant à des ambiguïtés sur la liste à exécuter.

If you use the @code{silent} command in the command list, the usual message about
stopping at a breakpoint is not printed.  This may be desirable for breakpoints
that are to print a specific message and then continue.  If none of the other
commands print anything, you see no sign that the breakpoint was reached.
@end deffn

@geindex step (pdb command)
@anchor{library/pdb pdbcommand-step}@anchor{4178}
@deffn {Pdbcommand} s(tep)

Exécute la ligne en cours, s'arrête à la première occasion possible (soit dans une fonction qui est appelée, soit sur la ligne suivante de la fonction courante).
@end deffn

@geindex next (pdb command)
@anchor{library/pdb pdbcommand-next}@anchor{4179}
@deffn {Pdbcommand} n(ext)

Continue l'exécution jusqu'à ce que la ligne suivante de la fonction en cours soit atteinte ou qu'elle revienne. (La différence entre @ref{4179,,next} et @ref{4178,,step} est que @ref{4178,,step} s'arrête dans une fonction appelée, tandis que @ref{4179,,next} exécute les fonctions appelées à (presque) pleine vitesse, ne s'arrêtant qu'à la ligne suivante dans la fonction courante.)
@end deffn

@geindex until (pdb command)
@anchor{library/pdb pdbcommand-until}@anchor{4192}
@deffn {Pdbcommand} unt(il) [lineno]

Sans argument, continue l'exécution jusqu'à ce que la ligne avec un nombre supérieur au nombre actuel soit atteinte.

With `lineno', continue execution until a line with a number greater or
equal to `lineno' is reached.  In both cases, also stop when the current frame
returns.


Modifié dans la version 3.2: Permet de donner un numéro de ligne explicite.

@end deffn

@geindex return (pdb command)
@anchor{library/pdb pdbcommand-return}@anchor{418f}
@deffn {Pdbcommand} r(eturn)

Continue l'exécution jusqu'au retour de la fonction courante.
@end deffn

@geindex continue (pdb command)
@anchor{library/pdb pdbcommand-continue}@anchor{4176}
@deffn {Pdbcommand} c(ont(inue))

Continue l'exécution, seulement s'arrête quand un point d'arrêt est rencontré.
@end deffn

@geindex jump (pdb command)
@anchor{library/pdb pdbcommand-jump}@anchor{4190}
@deffn {Pdbcommand} j(ump) lineno

Définit la prochaine ligne qui sera exécutée. Uniquement disponible dans la `frame' inférieur. Cela vous permet de revenir en arrière et d'exécuter à nouveau le code, ou de passer en avant pour sauter le code que vous ne voulez pas exécuter.

Il est à noter que tous les sauts ne sont pas autorisés -- par exemple, il n'est pas possible de sauter au milieu d'une boucle @ref{2e6,,for} ou en dehors d'une clause @ref{9b8,,finally}.
@end deffn

@geindex list (pdb command)
@anchor{library/pdb pdbcommand-list}@anchor{4181}
@deffn {Pdbcommand} l(ist) [first[, last]]

Liste le code source du fichier courant. Sans arguments, liste 11 lignes autour de la ligne courante ou continue le listing précédant. Avec l'argument @code{.}, liste 11 lignes autour de la ligne courante. Avec un argument, liste les 11 lignes autour de cette ligne. Avec deux arguments, liste la plage donnée; si le second argument est inférieur au premier, il est interprété comme un compte.

La ligne en cours dans l'image courante est indiquée par @code{->}. Si une exception est en cours de débogage, la ligne où l'exception a été initialement levée ou propagée est indiquée par @code{>>}, si elle diffère de la ligne courante.


Modifié dans la version 3.2: Added the @code{>>} marker.

@end deffn

@geindex ll (pdb command)
@anchor{library/pdb pdbcommand-ll}@anchor{4193}
@deffn {Pdbcommand} ll | longlist

Liste le code source de la fonction ou du bloc courant. Les lignes intéressantes sont marquées comme pour @ref{4181,,list}.


Ajouté dans la version 3.2.

@end deffn

@geindex args (pdb command)
@anchor{library/pdb pdbcommand-args}@anchor{4194}
@deffn {Pdbcommand} a(rgs)

Print the arguments of the current function and their current values.
@end deffn

@geindex p (pdb command)
@anchor{library/pdb pdbcommand-p}@anchor{f61}
@deffn {Pdbcommand} p expression

Evaluate `expression' in the current context and print its value.

@cartouche
@quotation Note 
@code{print()} peut aussi être utilisée, mais n'est pas une commande du débogueur --- il exécute la fonction Python @ref{f60,,print()}.
@end quotation
@end cartouche
@end deffn

@geindex pp (pdb command)
@anchor{library/pdb pdbcommand-pp}@anchor{4195}
@deffn {Pdbcommand} pp expression

Like the @ref{f61,,p} command, except the value of `expression' is
pretty-printed using the @ref{ad,,pprint} module.
@end deffn

@geindex whatis (pdb command)
@anchor{library/pdb pdbcommand-whatis}@anchor{4196}
@deffn {Pdbcommand} whatis expression

Print the type of `expression'.
@end deffn

@geindex source (pdb command)
@anchor{library/pdb pdbcommand-source}@anchor{4197}
@deffn {Pdbcommand} source expression

Try to get source code of `expression' and display it.


Ajouté dans la version 3.2.

@end deffn

@geindex display (pdb command)
@anchor{library/pdb pdbcommand-display}@anchor{4198}
@deffn {Pdbcommand} display [expression]

Display the value of `expression' if it changed, each time execution stops
in the current frame.

Without `expression', list all display expressions for the current frame.

@cartouche
@quotation Note 
Display evaluates `expression' and compares to the result of the previous
evaluation of `expression', so when the result is mutable, display may not
be able to pick up the changes.
@end quotation
@end cartouche

Exemple :

@example
lst = []
breakpoint()
pass
lst.append(1)
print(lst)
@end example

Display won't realize @code{lst} has been changed because the result of evaluation
is modified in place by @code{lst.append(1)} before being compared:

@example
> example.py(3)<module>()
-> pass
(Pdb) display lst
display lst: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
(Pdb)
@end example

You can do some tricks with copy mechanism to make it work:

@example
> example.py(3)<module>()
-> pass
(Pdb) display lst[:]
display lst[:]: []
(Pdb) n
> example.py(4)<module>()
-> lst.append(1)
(Pdb) n
> example.py(5)<module>()
-> print(lst)
display lst[:]: [1]  [old: []]
(Pdb)
@end example


Ajouté dans la version 3.2.

@end deffn

@geindex undisplay (pdb command)
@anchor{library/pdb pdbcommand-undisplay}@anchor{4199}
@deffn {Pdbcommand} undisplay [expression]

Do not display `expression' anymore in the current frame.  Without
`expression', clear all display expressions for the current frame.


Ajouté dans la version 3.2.

@end deffn

@geindex interact (pdb command)
@anchor{library/pdb pdbcommand-interact}@anchor{419a}
@deffn {Pdbcommand} interact

Start an interactive interpreter (using the @ref{1a,,code} module) in a new
global namespace initialised from the local and global namespaces for the
current scope. Use @code{exit()} or @code{quit()} to exit the interpreter and
return to the debugger.

@cartouche
@quotation Note 
As @code{interact} creates a new dedicated namespace for code execution,
assignments to variables will not affect the original namespaces.
However, modifications to any referenced mutable objects will be reflected
in the original namespaces as usual.
@end quotation
@end cartouche


Ajouté dans la version 3.2.



Modifié dans la version 3.13: @code{exit()} and @code{quit()} can be used to exit the @ref{419a,,interact}
command.



Modifié dans la version 3.13: @ref{419a,,interact} directs its output to the debugger's
output channel rather than @ref{926,,sys.stderr}.

@end deffn

@geindex alias (pdb command)
@anchor{library/pdb debugger-aliases}@anchor{4182}@anchor{library/pdb pdbcommand-alias}@anchor{419b}
@deffn {Pdbcommand} alias [name [command]]

Create an alias called `name' that executes `command'.  The `command' must
`not' be enclosed in quotes.  Replaceable parameters can be indicated by
@code{%1}, @code{%2}, ... and @code{%9}, while @code{%*} is replaced by all the parameters.
If `command' is omitted, the current alias for `name' is shown. If no
arguments are given, all aliases are listed.

Les alias peuvent être imbriqués et peuvent contenir tout ce qui peut être légalement tapé à l'invite `pdb'. Notez que les commandes `pdb' internes `peuvent' être remplacées par des alias. Une telle commande est alors masquée jusqu'à ce que l'alias soit supprimé. L'`aliasing' est appliqué récursivement au premier mot de la ligne de commande; tous les autres mots de la ligne sont laissés seuls.

Comme un exemple, voici deux alias utiles (spécialement quand il est placé dans le fichier @code{.pdbrc}) :

@example
# Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print(f"%1.@{k@} = @{%1.__dict__[k]@}")
# Print instance variables in self
alias ps pi self
@end example
@end deffn

@geindex unalias (pdb command)
@anchor{library/pdb pdbcommand-unalias}@anchor{419c}
@deffn {Pdbcommand} unalias name

Delete the specified alias `name'.
@end deffn

@geindex ! (pdb command)
@anchor{library/pdb pdbcommand-0}@anchor{419d}
@deffn {Pdbcommand} ! statement

Execute the (one-line) `statement' in the context of the current stack frame.
The exclamation point can be omitted unless the first word of the statement
resembles a debugger command, e.g.:

@example
(Pdb) ! n=42
(Pdb)
@end example

To set a global variable, you can prefix the assignment command with a
@ref{188,,global} statement on the same line, e.g.:

@example
(Pdb) global list_options; list_options = ['-l']
(Pdb)
@end example
@end deffn

@geindex run (pdb command)
@geindex restart (pdb command)
@anchor{library/pdb pdbcommand-run}@anchor{419e}
@deffn {Pdbcommand} run [args ...]
@anchor{library/pdb pdbcommand-restart}@anchor{419f}
@deffnx {Pdbcommand} restart [args ...]

Restart the debugged Python program.  If `args' is supplied, it is split
with @ref{c3,,shlex} and the result is used as the new @ref{1243,,sys.argv}.
History, breakpoints, actions and debugger options are preserved.
@ref{419f,,restart} is an alias for @ref{419e,,run}.
@end deffn

@geindex quit (pdb command)
@anchor{library/pdb pdbcommand-quit}@anchor{4191}
@deffn {Pdbcommand} q(uit)

Quitte le débogueur. Le programme exécuté est arrêté.
@end deffn

@geindex debug (pdb command)
@anchor{library/pdb pdbcommand-debug}@anchor{41a0}
@deffn {Pdbcommand} debug code

Enter a recursive debugger that steps through `code'
(which is an arbitrary expression or statement to be
executed in the current environment).
@end deffn

@geindex retval (pdb command)
@anchor{library/pdb pdbcommand-retval}@anchor{41a1}
@deffn {Pdbcommand} retval

Print the return value for the last return of the current function.
@end deffn

@geindex exceptions (pdb command)
@anchor{library/pdb pdbcommand-exceptions}@anchor{235}
@deffn {Pdbcommand} exceptions [excnumber]

List or jump between chained exceptions.

When using @code{pdb.pm()}  or @code{Pdb.post_mortem(...)} with a chained exception
instead of a traceback, it allows the user to move between the
chained exceptions using @code{exceptions} command to list exceptions, and
@code{exception <number>} to switch to that exception.

Exemple :

@example
def out():
    try:
        middle()
    except Exception as e:
        raise ValueError("reraise middle() error") from e

def middle():
    try:
        return inner(0)
    except Exception as e:
        raise ValueError("Middle fail")

def inner(x):
    1 / x

 out()
@end example

calling @code{pdb.pm()} will allow to move between exceptions:

@example
> example.py(5)out()
-> raise ValueError("reraise middle() error") from e

(Pdb) exceptions
  0 ZeroDivisionError('division by zero')
  1 ValueError('Middle fail')
> 2 ValueError('reraise middle() error')

(Pdb) exceptions 0
> example.py(16)inner()
-> 1 / x

(Pdb) up
> example.py(10)middle()
-> return inner(0)
@end example


Ajouté dans la version 3.13.

@end deffn

@subsubheading Notes


@node The Python Profilers,timeit --- Measure execution time of small code snippets,pdb — Le débogueur Python,Débogueur et instrumentation
@anchor{library/profile doc}@anchor{41a2}@anchor{library/profile profile}@anchor{41a3}@anchor{library/profile the-python-profilers}@anchor{41a4}
@subsection The Python Profilers


`Source code:' Lib/profile.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/profile.py} and Lib/pstats.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pstats.py}


__________________________________________________________________


@menu
* Introduction to the profilers:: 
* Instant User's Manual:: 
* profile and cProfile Module Reference:: 
* The Stats Class:: 
* What Is Deterministic Profiling?:: 
* Limitations:: 
* Calibration:: 
* Using a custom timer:: 

@end menu

@node Introduction to the profilers,Instant User's Manual,,The Python Profilers
@anchor{library/profile introduction-to-the-profilers}@anchor{41a5}@anchor{library/profile profiler-introduction}@anchor{41a6}
@subsubsection Introduction to the profilers


@geindex deterministic profiling
@geindex profiling@comma{} deterministic

@ref{27,,cProfile} and @ref{ae,,profile} provide `deterministic profiling' of
Python programs. A `profile' is a set of statistics that describes how
often and for how long various parts of the program executed. These statistics
can be formatted into reports via the @ref{af,,pstats} module.

The Python standard library provides two different implementations of the same
profiling interface:


@enumerate 

@item 
@ref{27,,cProfile} is recommended for most users; it's a C extension with
reasonable overhead that makes it suitable for profiling long-running
programs.  Based on @code{lsprof}, contributed by Brett Rosen and Ted
Czotter.

@item 
@ref{ae,,profile}, a pure Python module whose interface is imitated by
@ref{27,,cProfile}, but which adds significant overhead to profiled programs.
If you're trying to extend the profiler in some way, the task might be easier
with this module.  Originally designed and written by Jim Roskind.
@end enumerate

@cartouche
@quotation Note 
The profiler modules are designed to provide an execution profile for a given
program, not for benchmarking purposes (for that, there is @ref{ee,,timeit} for
reasonably accurate results).  This particularly applies to benchmarking
Python code against C code: the profilers introduce overhead for Python code,
but not for C-level functions, and so the C code would seem faster than any
Python one.
@end quotation
@end cartouche

@node Instant User's Manual,profile and cProfile Module Reference,Introduction to the profilers,The Python Profilers
@anchor{library/profile instant-user-s-manual}@anchor{41a7}@anchor{library/profile profile-instant}@anchor{41a8}
@subsubsection Instant User's Manual


This section is provided for users that "don't want to read the manual." It
provides a very brief overview, and allows a user to rapidly perform profiling
on an existing application.

To profile a function that takes a single argument, you can do:

@example
import cProfile
import re
cProfile.run('re.compile("foo|bar")')
@end example

(Use @ref{ae,,profile} instead of @ref{27,,cProfile} if the latter is not available on
your system.)

The above action would run @ref{bc1,,re.compile()} and print profile results like
the following:

@example
      214 function calls (207 primitive calls) in 0.002 seconds

Ordered by: cumulative time

ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     1    0.000    0.000    0.002    0.002 @{built-in method builtins.exec@}
     1    0.000    0.000    0.001    0.001 <string>:1(<module>)
     1    0.000    0.000    0.001    0.001 __init__.py:250(compile)
     1    0.000    0.000    0.001    0.001 __init__.py:289(_compile)
     1    0.000    0.000    0.000    0.000 _compiler.py:759(compile)
     1    0.000    0.000    0.000    0.000 _parser.py:937(parse)
     1    0.000    0.000    0.000    0.000 _compiler.py:598(_code)
     1    0.000    0.000    0.000    0.000 _parser.py:435(_parse_sub)
@end example

The first line indicates that 214 calls were monitored.  Of those calls, 207
were `primitive', meaning that the call was not induced via recursion. The
next line: @code{Ordered by: cumulative time} indicates the output is sorted
by the @code{cumtime} values. The column headings include:


@table @asis

@item ncalls

for the number of calls.

@item tottime

for the total time spent in the given function (and excluding time made in
calls to sub-functions)

@item percall

is the quotient of @code{tottime} divided by @code{ncalls}

@item cumtime

is the cumulative time spent in this and all subfunctions (from invocation
till exit). This figure is accurate `even' for recursive functions.

@item percall

is the quotient of @code{cumtime} divided by primitive calls

@item filename:lineno(function)

provides the respective data of each function
@end table

When there are two numbers in the first column (for example @code{3/1}), it means
that the function recursed.  The second value is the number of primitive calls
and the former is the total number of calls.  Note that when the function does
not recurse, these two values are the same, and only the single figure is
printed.

Instead of printing the output at the end of the profile run, you can save the
results to a file by specifying a filename to the @code{run()} function:

@example
import cProfile
import re
cProfile.run('re.compile("foo|bar")', 'restats')
@end example

The @ref{41a9,,pstats.Stats} class reads profile results from a file and formats
them in various ways.
@anchor{library/profile profile-cli}@anchor{41aa}
The files @ref{27,,cProfile} and @ref{ae,,profile} can also be invoked as a script to
profile another script.  For example:

@example
python -m cProfile [-o output_file] [-s sort_order] (-m module | myscript.py)
@end example

@code{-o} writes the profile results to a file instead of to stdout

@code{-s} specifies one of the @ref{41ab,,sort_stats()} sort values to sort
the output by. This only applies when @code{-o} is not supplied.

@code{-m} specifies that a module is being profiled instead of a script.


Ajouté dans la version 3.7: Added the @code{-m} option to @ref{27,,cProfile}.



Ajouté dans la version 3.8: Added the @code{-m} option to @ref{ae,,profile}.


The @ref{af,,pstats} module's @ref{41a9,,Stats} class has a variety of methods
for manipulating and printing the data saved into a profile results file:

@example
import pstats
from pstats import SortKey
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()
@end example

The @ref{41ac,,strip_dirs()} method removed the extraneous path from all
the module names. The @ref{41ab,,sort_stats()} method sorted all the
entries according to the standard module/line/name string that is printed. The
@ref{41ad,,print_stats()} method printed out all the statistics.  You
might try the following sort calls:

@example
p.sort_stats(SortKey.NAME)
p.print_stats()
@end example

The first call will actually sort the list by function name, and the second call
will print out the statistics.  The following are some interesting calls to
experiment with:

@example
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)
@end example

This sorts the profile by cumulative time in a function, and then only prints
the ten most significant lines.  If you want to understand what algorithms are
taking time, the above line is what you would use.

If you were looking to see what functions were looping a lot, and taking a lot
of time, you would do:

@example
p.sort_stats(SortKey.TIME).print_stats(10)
@end example

to sort according to time spent within each function, and then print the
statistics for the top ten functions.

You might also try:

@example
p.sort_stats(SortKey.FILENAME).print_stats('__init__')
@end example

This will sort all the statistics by file name, and then print out statistics
for only the class init methods (since they are spelled with @code{__init__} in
them).  As one final example, you could try:

@example
p.sort_stats(SortKey.TIME, SortKey.CUMULATIVE).print_stats(.5, 'init')
@end example

This line sorts statistics with a primary key of time, and a secondary key of
cumulative time, and then prints out some of the statistics. To be specific, the
list is first culled down to 50% (re: @code{.5}) of its original size, then only
lines containing @code{init} are maintained, and that sub-sub-list is printed.

If you wondered what functions called the above functions, you could now (@code{p}
is still sorted according to the last criteria) do:

@example
p.print_callers(.5, 'init')
@end example

and you would get a list of callers for each of the listed functions.

If you want more functionality, you're going to have to read the manual, or
guess what the following functions do:

@example
p.print_callees()
p.add('restats')
@end example

Invoked as a script, the @ref{af,,pstats} module is a statistics browser for
reading and examining profile dumps.  It has a simple line-oriented interface
(implemented using @ref{19,,cmd}) and interactive help.

@node profile and cProfile Module Reference,The Stats Class,Instant User's Manual,The Python Profilers
@anchor{library/profile module-cProfile}@anchor{27}@anchor{library/profile profile-and-cprofile-module-reference}@anchor{41ae}
@subsubsection @code{profile} and @code{cProfile} Module Reference


@geindex module; cProfile

@geindex module; profile
@anchor{library/profile module-profile}@anchor{ae}
Both the @ref{ae,,profile} and @ref{27,,cProfile} modules provide the following
functions:

@geindex run() (dans le module profile)
@anchor{library/profile profile run}@anchor{41af}
@deffn {Fonction} profile.run (command, filename=None, sort=-1)

This function takes a single argument that can be passed to the @ref{17d,,exec()}
function, and an optional file name.  In all cases this routine executes:

@example
exec(command, __main__.__dict__, __main__.__dict__)
@end example

and gathers profiling statistics from the execution. If no file name is
present, then this function automatically creates a @ref{41a9,,Stats}
instance and prints a simple profiling report. If the sort value is specified,
it is passed to this @ref{41a9,,Stats} instance to control how the
results are sorted.
@end deffn

@geindex runctx() (dans le module profile)
@anchor{library/profile profile runctx}@anchor{41b0}
@deffn {Fonction} profile.runctx (command, globals, locals, filename=None, sort=-1)

This function is similar to @ref{41af,,run()}, with added arguments to supply the
globals and locals mappings for the `command' string. This routine
executes:

@example
exec(command, globals, locals)
@end example

and gathers profiling statistics as in the @ref{41af,,run()} function above.
@end deffn

@geindex Profile (classe dans profile)
@anchor{library/profile profile Profile}@anchor{9d1}
@deffn {Classe} profile.Profile (timer=None, timeunit=0.0, subcalls=True, builtins=True)

This class is normally only used if more precise control over profiling is
needed than what the @code{cProfile.run()} function provides.

A custom timer can be supplied for measuring how long code takes to run via
the `timer' argument. This must be a function that returns a single number
representing the current time. If the number is an integer, the `timeunit'
specifies a multiplier that specifies the duration of each unit of time. For
example, if the timer returns times measured in thousands of seconds, the
time unit would be @code{.001}.

Directly using the @ref{9d1,,Profile} class allows formatting profile results
without writing the profile data to a file:

@example
import cProfile, pstats, io
from pstats import SortKey
pr = cProfile.Profile()
pr.enable()
# ... do something ...
pr.disable()
s = io.StringIO()
sortby = SortKey.CUMULATIVE
ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
ps.print_stats()
print(s.getvalue())
@end example

The @ref{9d1,,Profile} class can also be used as a context manager (supported
only in @ref{27,,cProfile} module. see @ref{1f42,,Le type gestionnaire de contexte}):

@example
import cProfile

with cProfile.Profile() as pr:
    # ... do something ...

    pr.print_stats()
@end example


Modifié dans la version 3.8: Ajout de la gestion des gestionnaires de contexte.


@geindex enable() (méthode profile.Profile)
@anchor{library/profile profile Profile enable}@anchor{41b1}
@deffn {Méthode} enable ()

Start collecting profiling data. Only in @ref{27,,cProfile}.
@end deffn

@geindex disable() (méthode profile.Profile)
@anchor{library/profile profile Profile disable}@anchor{41b2}
@deffn {Méthode} disable ()

Stop collecting profiling data. Only in @ref{27,,cProfile}.
@end deffn

@geindex create_stats() (méthode profile.Profile)
@anchor{library/profile profile Profile create_stats}@anchor{41b3}
@deffn {Méthode} create_stats ()

Stop collecting profiling data and record the results internally
as the current profile.
@end deffn

@geindex print_stats() (méthode profile.Profile)
@anchor{library/profile profile Profile print_stats}@anchor{41b4}
@deffn {Méthode} print_stats (sort=-1)

Create a @ref{41a9,,Stats} object based on the current
profile and print the results to stdout.

The `sort' parameter specifies the sorting order of the displayed
statistics. It accepts a single key or a tuple of keys to enable
multi-level sorting, as in @ref{41ab,,Stats.sort_stats}.


Ajouté dans la version 3.13: @ref{41b4,,print_stats()} now accepts a tuple of keys.

@end deffn

@geindex dump_stats() (méthode profile.Profile)
@anchor{library/profile profile Profile dump_stats}@anchor{41b5}
@deffn {Méthode} dump_stats (filename)

Write the results of the current profile to `filename'.
@end deffn

@geindex run() (méthode profile.Profile)
@anchor{library/profile profile Profile run}@anchor{41b6}
@deffn {Méthode} run (cmd)

Profile the cmd via @ref{17d,,exec()}.
@end deffn

@geindex runctx() (méthode profile.Profile)
@anchor{library/profile profile Profile runctx}@anchor{41b7}
@deffn {Méthode} runctx (cmd, globals, locals)

Profile the cmd via @ref{17d,,exec()} with the specified global and
local environment.
@end deffn

@geindex runcall() (méthode profile.Profile)
@anchor{library/profile profile Profile runcall}@anchor{a6b}
@deffn {Méthode} runcall (func, /, *args, **kwargs)

Profile @code{func(*args, **kwargs)}
@end deffn
@end deffn

Note that profiling will only work if the called command/function actually
returns.  If the interpreter is terminated (e.g. via a @ref{1327,,sys.exit()} call
during the called command/function execution) no profiling results will be
printed.

@node The Stats Class,What Is Deterministic Profiling?,profile and cProfile Module Reference,The Python Profilers
@anchor{library/profile profile-stats}@anchor{41b8}@anchor{library/profile the-stats-class}@anchor{41b9}
@subsubsection The @code{Stats} Class


Analysis of the profiler data is done using the @ref{41a9,,Stats} class.

@geindex module; pstats

@geindex Stats (classe dans pstats)
@anchor{library/profile module-pstats}@anchor{af}@anchor{library/profile pstats Stats}@anchor{41a9}
@deffn {Classe} pstats.Stats (*filenames or profile, stream=sys.stdout)

This class constructor creates an instance of a "statistics object" from a
`filename' (or list of filenames) or from a @code{Profile} instance. Output
will be printed to the stream specified by `stream'.

The file selected by the above constructor must have been created by the
corresponding version of @ref{ae,,profile} or @ref{27,,cProfile}.  To be specific,
there is `no' file compatibility guaranteed with future versions of this
profiler, and there is no compatibility with files produced by other
profilers, or the same profiler run on a different operating system.  If
several files are provided, all the statistics for identical functions will
be coalesced, so that an overall view of several processes can be considered
in a single report.  If additional files need to be combined with data in an
existing @ref{41a9,,Stats} object, the @ref{41ba,,add()} method
can be used.

Instead of reading the profile data from a file, a @code{cProfile.Profile}
or @ref{9d1,,profile.Profile} object can be used as the profile data source.

@ref{41a9,,Stats} objects have the following methods:

@geindex strip_dirs() (méthode pstats.Stats)
@anchor{library/profile pstats Stats strip_dirs}@anchor{41ac}
@deffn {Méthode} strip_dirs ()

This method for the @ref{41a9,,Stats} class removes all leading path
information from file names.  It is very useful in reducing the size of
the printout to fit within (close to) 80 columns.  This method modifies
the object, and the stripped information is lost.  After performing a
strip operation, the object is considered to have its entries in a
"random" order, as it was just after object initialization and loading.
If @ref{41ac,,strip_dirs()} causes two function names to be
indistinguishable (they are on the same line of the same filename, and
have the same function name), then the statistics for these two entries
are accumulated into a single entry.
@end deffn

@geindex add() (méthode pstats.Stats)
@anchor{library/profile pstats Stats add}@anchor{41ba}
@deffn {Méthode} add (*filenames)

This method of the @ref{41a9,,Stats} class accumulates additional profiling
information into the current profiling object.  Its arguments should refer
to filenames created by the corresponding version of @ref{41af,,profile.run()}
or @code{cProfile.run()}. Statistics for identically named (re: file, line,
name) functions are automatically accumulated into single function
statistics.
@end deffn

@geindex dump_stats() (méthode pstats.Stats)
@anchor{library/profile pstats Stats dump_stats}@anchor{41bb}
@deffn {Méthode} dump_stats (filename)

Save the data loaded into the @ref{41a9,,Stats} object to a file named
`filename'.  The file is created if it does not exist, and is overwritten
if it already exists.  This is equivalent to the method of the same name
on the @ref{9d1,,profile.Profile} and @code{cProfile.Profile} classes.
@end deffn

@geindex sort_stats() (méthode pstats.Stats)
@anchor{library/profile pstats Stats sort_stats}@anchor{41ab}
@deffn {Méthode} sort_stats (*keys)

This method modifies the @ref{41a9,,Stats} object by sorting it according to
the supplied criteria.  The argument can be either a string or a SortKey
enum identifying the basis of a sort (example: @code{'time'}, @code{'name'},
@code{SortKey.TIME} or @code{SortKey.NAME}). The SortKey enums argument have
advantage over the string argument in that it is more robust and less
error prone.

When more than one key is provided, then additional keys are used as
secondary criteria when there is equality in all keys selected before
them.  For example, @code{sort_stats(SortKey.NAME, SortKey.FILE)} will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.

For the string argument, abbreviations can be used for any key names, as
long as the abbreviation is unambiguous.

The following are the valid string and SortKey:


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valid String Arg

@tab

Valid enum Arg

@tab

Signification

@item

@code{'calls'}

@tab

SortKey.CALLS

@tab

call count

@item

@code{'cumulative'}

@tab

SortKey.CUMULATIVE

@tab

cumulative time

@item

@code{'cumtime'}

@tab

N/A

@tab

cumulative time

@item

@code{'file'}

@tab

N/A

@tab

file name

@item

@code{'filename'}

@tab

SortKey.FILENAME

@tab

file name

@item

@code{'module'}

@tab

N/A

@tab

file name

@item

@code{'ncalls'}

@tab

N/A

@tab

call count

@item

@code{'pcalls'}

@tab

SortKey.PCALLS

@tab

primitive call count

@item

@code{'line'}

@tab

SortKey.LINE

@tab

line number

@item

@code{'name'}

@tab

SortKey.NAME

@tab

function name

@item

@code{'nfl'}

@tab

SortKey.NFL

@tab

name/file/line

@item

@code{'stdname'}

@tab

SortKey.STDNAME

@tab

standard name

@item

@code{'time'}

@tab

SortKey.TIME

@tab

internal time

@item

@code{'tottime'}

@tab

N/A

@tab

internal time

@end multitable


Note that all sorts on statistics are in descending order (placing most
time consuming items first), where as name, file, and line number searches
are in ascending order (alphabetical). The subtle distinction between
@code{SortKey.NFL} and @code{SortKey.STDNAME} is that the standard name is a
sort of the name as printed, which means that the embedded line numbers
get compared in an odd way.  For example, lines 3, 20, and 40 would (if
the file names were the same) appear in the string order 20, 3 and 40.
In contrast, @code{SortKey.NFL} does a numeric compare of the line numbers.
In fact, @code{sort_stats(SortKey.NFL)} is the same as
@code{sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)}.

For backward-compatibility reasons, the numeric arguments @code{-1}, @code{0},
@code{1}, and @code{2} are permitted.  They are interpreted as @code{'stdname'},
@code{'calls'}, @code{'time'}, and @code{'cumulative'} respectively.  If this old
style format (numeric) is used, only one sort key (the numeric key) will
be used, and additional arguments will be silently ignored.

@c For compatibility with the old profiler.


Ajouté dans la version 3.7: Added the SortKey enum.

@end deffn

@geindex reverse_order() (méthode pstats.Stats)
@anchor{library/profile pstats Stats reverse_order}@anchor{41bc}
@deffn {Méthode} reverse_order ()

This method for the @ref{41a9,,Stats} class reverses the ordering of the
basic list within the object.  Note that by default ascending vs
descending order is properly selected based on the sort key of choice.

@c This method is provided primarily for compatibility with the old
@c profiler.
@end deffn

@geindex print_stats() (méthode pstats.Stats)
@anchor{library/profile pstats Stats print_stats}@anchor{41ad}
@deffn {Méthode} print_stats (*restrictions)

This method for the @ref{41a9,,Stats} class prints out a report as described
in the @ref{41af,,profile.run()} definition.

The order of the printing is based on the last
@ref{41ab,,sort_stats()} operation done on the object (subject to
caveats in @ref{41ba,,add()} and
@ref{41ac,,strip_dirs()}).

The arguments provided (if any) can be used to limit the list down to the
significant entries.  Initially, the list is taken to be the complete set
of profiled functions.  Each restriction is either an integer (to select a
count of lines), or a decimal fraction between 0.0 and 1.0 inclusive (to
select a percentage of lines), or a string that will interpreted as a
regular expression (to pattern match the standard name that is printed).
If several restrictions are provided, then they are applied sequentially.
For example:

@example
print_stats(.1, 'foo:')
@end example

would first limit the printing to first 10% of list, and then only print
functions that were part of filename @code{.*foo:}.  In contrast, the
command:

@example
print_stats('foo:', .1)
@end example

would limit the list to all functions having file names @code{.*foo:},
and then proceed to only print the first 10% of them.
@end deffn

@geindex print_callers() (méthode pstats.Stats)
@anchor{library/profile pstats Stats print_callers}@anchor{41bd}
@deffn {Méthode} print_callers (*restrictions)

This method for the @ref{41a9,,Stats} class prints a list of all functions
that called each function in the profiled database.  The ordering is
identical to that provided by @ref{41ad,,print_stats()}, and the
definition of the restricting argument is also identical.  Each caller is
reported on its own line.  The format differs slightly depending on the
profiler that produced the stats:


@itemize *

@item 
With @ref{ae,,profile}, a number is shown in parentheses after each caller
to show how many times this specific call was made.  For convenience, a
second non-parenthesized number repeats the cumulative time spent in the
function at the right.

@item 
With @ref{27,,cProfile}, each caller is preceded by three numbers: the
number of times this specific call was made, and the total and
cumulative times spent in the current function while it was invoked by
this specific caller.
@end itemize
@end deffn

@geindex print_callees() (méthode pstats.Stats)
@anchor{library/profile pstats Stats print_callees}@anchor{41be}
@deffn {Méthode} print_callees (*restrictions)

This method for the @ref{41a9,,Stats} class prints a list of all function
that were called by the indicated function.  Aside from this reversal of
direction of calls (re: called vs was called by), the arguments and
ordering are identical to the @ref{41bd,,print_callers()} method.
@end deffn

@geindex get_stats_profile() (méthode pstats.Stats)
@anchor{library/profile pstats Stats get_stats_profile}@anchor{41bf}
@deffn {Méthode} get_stats_profile ()

This method returns an instance of StatsProfile, which contains a mapping
of function names to instances of FunctionProfile. Each FunctionProfile
instance holds information related to the function's profile such as how
long the function took to run, how many times it was called, etc...


Ajouté dans la version 3.9: Added the following dataclasses: StatsProfile, FunctionProfile.
Added the following function: get_stats_profile.

@end deffn
@end deffn

@node What Is Deterministic Profiling?,Limitations,The Stats Class,The Python Profilers
@anchor{library/profile deterministic-profiling}@anchor{41c0}@anchor{library/profile what-is-deterministic-profiling}@anchor{41c1}
@subsubsection What Is Deterministic Profiling?


`Deterministic profiling' is meant to reflect the fact that all `function
call', `function return', and `exception' events are monitored, and precise
timings are made for the intervals between these events (during which time the
user's code is executing).  In contrast, `statistical profiling' (which is
not done by this module) randomly samples the effective instruction pointer, and
deduces where time is being spent.  The latter technique traditionally involves
less overhead (as the code does not need to be instrumented), but provides only
relative indications of where time is being spent.

In Python, since there is an interpreter active during execution, the presence
of instrumented code is not required in order to do deterministic profiling.
Python automatically provides a `hook' (optional callback) for each event.
In addition, the interpreted nature of Python tends to add so much overhead to
execution, that deterministic profiling tends to only add small processing
overhead in typical applications.  The result is that deterministic profiling is
not that expensive, yet provides extensive run time statistics about the
execution of a Python program.

Call count statistics can be used to identify bugs in code (surprising counts),
and to identify possible inline-expansion points (high call counts).  Internal
time statistics can be used to identify "hot loops" that should be carefully
optimized.  Cumulative time statistics should be used to identify high level
errors in the selection of algorithms.  Note that the unusual handling of
cumulative times in this profiler allows statistics for recursive
implementations of algorithms to be directly compared to iterative
implementations.

@node Limitations,Calibration,What Is Deterministic Profiling?,The Python Profilers
@anchor{library/profile limitations}@anchor{41c2}@anchor{library/profile profile-limitations}@anchor{41c3}
@subsubsection Limitations


One limitation has to do with accuracy of timing information. There is a
fundamental problem with deterministic profilers involving accuracy.  The most
obvious restriction is that the underlying "clock" is only ticking at a rate
(typically) of about .001 seconds.  Hence no measurements will be more accurate
than the underlying clock.  If enough measurements are taken, then the "error"
will tend to average out. Unfortunately, removing this first error induces a
second source of error.

The second problem is that it "takes a while" from when an event is dispatched
until the profiler's call to get the time actually `gets' the state of the
clock.  Similarly, there is a certain lag when exiting the profiler event
handler from the time that the clock's value was obtained (and then squirreled
away), until the user's code is once again executing.  As a result, functions
that are called many times, or call many functions, will typically accumulate
this error. The error that accumulates in this fashion is typically less than
the accuracy of the clock (less than one clock tick), but it `can' accumulate
and become very significant.

The problem is more important with @ref{ae,,profile} than with the lower-overhead
@ref{27,,cProfile}.  For this reason, @ref{ae,,profile} provides a means of
calibrating itself for a given platform so that this error can be
probabilistically (on the average) removed. After the profiler is calibrated, it
will be more accurate (in a least square sense), but it will sometimes produce
negative numbers (when call counts are exceptionally low, and the gods of
probability work against you :-). )  Do `not' be alarmed by negative numbers in
the profile.  They should `only' appear if you have calibrated your profiler,
and the results are actually better than without calibration.

@node Calibration,Using a custom timer,Limitations,The Python Profilers
@anchor{library/profile calibration}@anchor{41c4}@anchor{library/profile profile-calibration}@anchor{41c5}
@subsubsection Calibration


The profiler of the @ref{ae,,profile} module subtracts a constant from each event
handling time to compensate for the overhead of calling the time function, and
socking away the results.  By default, the constant is 0. The following
procedure can be used to obtain a better constant for a given platform (see
@ref{41c3,,Limitations}).

@example
import profile
pr = profile.Profile()
for i in range(5):
    print(pr.calibrate(10000))
@end example

The method executes the number of Python calls given by the argument, directly
and again under the profiler, measuring the time for both. It then computes the
hidden overhead per profiler event, and returns that as a float.  For example,
on a 1.8Ghz Intel Core i5 running macOS, and using Python's time.process_time() as
the timer, the magical number is about 4.04e-6.

The object of this exercise is to get a fairly consistent result. If your
computer is `very' fast, or your timer function has poor resolution, you might
have to pass 100000, or even 1000000, to get consistent results.

When you have a consistent answer, there are three ways you can use it:

@example
import profile

# 1. Apply computed bias to all Profile instances created hereafter.
profile.Profile.bias = your_computed_bias

# 2. Apply computed bias to a specific Profile instance.
pr = profile.Profile()
pr.bias = your_computed_bias

# 3. Specify computed bias in instance constructor.
pr = profile.Profile(bias=your_computed_bias)
@end example

If you have a choice, you are better off choosing a smaller constant, and then
your results will "less often" show up as negative in profile statistics.

@node Using a custom timer,,Calibration,The Python Profilers
@anchor{library/profile profile-timers}@anchor{41c6}@anchor{library/profile using-a-custom-timer}@anchor{41c7}
@subsubsection Using a custom timer


If you want to change how current time is determined (for example, to force use
of wall-clock time or elapsed process time), pass the timing function you want
to the @code{Profile} class constructor:

@example
pr = profile.Profile(your_time_func)
@end example

The resulting profiler will then call @code{your_time_func}. Depending on whether
you are using @ref{9d1,,profile.Profile} or @code{cProfile.Profile},
@code{your_time_func}'s return value will be interpreted differently:


@table @asis

@item @ref{9d1,,profile.Profile}

@code{your_time_func} should return a single number, or a list of numbers whose
sum is the current time (like what @ref{10f5,,os.times()} returns).  If the
function returns a single time number, or the list of returned numbers has
length 2, then you will get an especially fast version of the dispatch
routine.

Be warned that you should calibrate the profiler class for the timer function
that you choose (see @ref{41c5,,Calibration}).  For most machines, a timer
that returns a lone integer value will provide the best results in terms of
low overhead during profiling.  (@ref{10f5,,os.times()} is `pretty' bad, as it
returns a tuple of floating-point values).  If you want to substitute a
better timer in the cleanest fashion, derive a class and hardwire a
replacement dispatch method that best handles your timer call, along with the
appropriate calibration constant.

@item @code{cProfile.Profile}

@code{your_time_func} should return a single number.  If it returns integers,
you can also invoke the class constructor with a second argument specifying
the real duration of one unit of time.  For example, if
@code{your_integer_time_func} returns times measured in thousands of seconds,
you would construct the @code{Profile} instance as follows:

@example
pr = cProfile.Profile(your_integer_time_func, 0.001)
@end example

As the @code{cProfile.Profile} class cannot be calibrated, custom timer
functions should be used with care and should be as fast as possible.  For
the best results with a custom timer, it might be necessary to hard-code it
in the C source of the internal @code{_lsprof} module.
@end table

Python 3.3 adds several new functions in @ref{ed,,time} that can be used to make
precise measurements of process or wall-clock time. For example, see
@ref{a76,,time.perf_counter()}.

@node timeit --- Measure execution time of small code snippets,trace --- Trace or track Python statement execution,The Python Profilers,Débogueur et instrumentation
@anchor{library/timeit doc}@anchor{41c8}@anchor{library/timeit module-timeit}@anchor{ee}@anchor{library/timeit timeit-measure-execution-time-of-small-code-snippets}@anchor{41c9}
@subsection @code{timeit} --- Measure execution time of small code snippets


@geindex module; timeit

`Code source :' Lib/timeit.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/timeit.py}

@geindex Benchmarking
@geindex Performance


__________________________________________________________________


Ce module fournit une façon simple de mesurer le temps d'exécution de fragments de code Python. Il expose une @ref{41ca,,Interface en ligne de commande} ainsi qu'une @ref{41cb,,interface Python}. Ce module permet d'éviter un certain nombre de problèmes classiques liés à la mesure des temps d'exécution. Voir par exemple à ce sujet l'introduction par Tim Peters du chapitre « Algorithmes » dans la seconde édition du livre `Python Cookbook', aux éditions O'Reilly.

@menu
* Exemples simples: Exemples simples<2>. 
* Interface Python:: 
* Interface en ligne de commande: Interface en ligne de commande<6>. 
* Exemples: Exemples<29>. 

@end menu

@node Exemples simples<2>,Interface Python,,timeit --- Measure execution time of small code snippets
@anchor{library/timeit basic-examples}@anchor{41cc}
@subsubsection Exemples simples


L'exemple suivant illustre l'utilisation de l'@ref{41ca,,Interface en ligne de commande} afin de comparer trois expressions différentes :

@example
$ python -m timeit "'-'.join(str(n) for n in range(100))"
10000 loops, best of 5: 30.2 usec per loop
$ python -m timeit "'-'.join([str(n) for n in range(100)])"
10000 loops, best of 5: 27.5 usec per loop
$ python -m timeit "'-'.join(map(str, range(100)))"
10000 loops, best of 5: 23.2 usec per loop
@end example

L'@ref{41cb,,Interface Python} peut être utilisée aux mêmes fins avec :

@example
>>> import timeit
>>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)
0.3018611848820001
>>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000)
0.2727368790656328
>>> timeit.timeit('"-".join(map(str, range(100)))', number=10000)
0.23702679807320237
@end example

Un objet appelable peut également être passé en argument à l'@ref{41cb,,Interface Python} :

@example
>>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
0.19665591977536678
@end example

Notez cependant que @ref{e69,,timeit()} détermine automatiquement le nombre de répétitions seulement lorsque l'interface en ligne de commande est utilisée. Vous pouvez trouver des exemples d'usages avancés dans la section @ref{41cd,,Exemples}.

@node Interface Python,Interface en ligne de commande<6>,Exemples simples<2>,timeit --- Measure execution time of small code snippets
@anchor{library/timeit id1}@anchor{41ce}@anchor{library/timeit python-interface}@anchor{41cb}
@subsubsection Interface Python


Ce module définit une classe publique ainsi que trois fonctions destinées à simplifier son usage :

@geindex timeit() (dans le module timeit)
@anchor{library/timeit timeit timeit}@anchor{e69}
@deffn {Fonction} timeit.timeit (stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

Crée une instance d'objet @ref{147c,,Timer} à partir de l'instruction donnée, du code `setup' et de la fonction `timer', puis exécute sa méthode @ref{cdb,,timeit()} à `number' reprises. L'argument optionnel `globals' spécifie un espace de nommage dans lequel exécuter le code.


Modifié dans la version 3.5: Le paramètre optionnel `globals' a été ajouté.

@end deffn

@geindex repeat() (dans le module timeit)
@anchor{library/timeit timeit repeat}@anchor{41cf}
@deffn {Fonction} timeit.repeat (stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

Crée une instance d'objet @ref{147c,,Timer} à partir de l'instruction donnée, du code `setup' et de la fonction `timer', puis exécute sa méthode @ref{41d0,,repeat()} à `number' reprises, `repeat' fois. L'argument optionnel `globals' spécifie un espace de nommage dans lequel exécuter le code.


Modifié dans la version 3.5: Le paramètre optionnel `globals' a été ajouté.



Modifié dans la version 3.7: La valeur par défaut de `repeat' est passée de 3 à 5.

@end deffn

@geindex default_timer() (dans le module timeit)
@anchor{library/timeit timeit default_timer}@anchor{41d1}
@deffn {Fonction} timeit.default_timer ()

The default timer, which is always time.perf_counter(), returns float seconds.
An alternative, time.perf_counter_ns, returns integer nanoseconds.


Modifié dans la version 3.3: @ref{a76,,time.perf_counter()} est désormais le minuteur par défaut.

@end deffn

@geindex Timer (classe dans timeit)
@anchor{library/timeit timeit Timer}@anchor{147c}
@deffn {Classe} timeit.Timer (stmt='pass', setup='pass', timer=<timer function>, globals=None)

Classe permettant de mesurer le temps d'exécution de fragments de code.

Ce constructeur prend en argument une instruction dont le temps d'exécution doit être mesuré, une instruction additionnelle de mise en place et une fonction de chronométrage. Les deux instructions valent @code{'pass'} par défaut; la fonction de chronométrage dépend de la plateforme d'exécution (se référer au `doc string' du module). `stmt' et `setup' peuvent contenir plusieurs instructions séparées par des @code{;} ou des sauts de lignes tant qu'ils ne comportent pas de littéraux sur plusieurs lignes. L'instruction est exécutée dans l'espace de nommage de `timeit' par défaut ; ce comportement peut être modifié en passant un espace de nommage au paramètre `globals'.

Pour mesurer le temps d'exécution de la première instruction, utilisez la méthode @ref{cdb,,timeit()}. Les méthodes @ref{41d0,,repeat()} et @ref{cda,,autorange()} sont des méthodes d'agrément permettant d'appeler @ref{cdb,,timeit()} à plusieurs reprises.

Le temps d'exécution de `setup' n'est pas pris en compte dans le temps global d'exécution.

Les paramètres `stmt' et `setup' peuvent également recevoir des objets appelables sans argument. Ceci transforme alors les appels à ces objets en fonction de chronométrage qui seront exécutées par @ref{cdb,,timeit()}. Notez que le surcoût lié à la mesure du temps d'exécution dans ce cas est légèrement supérieur en raisons des appels de fonction supplémentaires.


Modifié dans la version 3.5: Le paramètre optionnel `globals' a été ajouté.


@geindex timeit() (méthode timeit.Timer)
@anchor{library/timeit timeit Timer timeit}@anchor{cdb}
@deffn {Méthode} timeit (number=1000000)

Time `number' executions of the main statement.  This executes the setup
statement once, and then returns the time it takes to execute the main
statement a number of times.  The default timer returns seconds as a float.
The argument is the number of times through the loop, defaulting to one
million.  The main statement, the setup statement and the timer function
to be used are passed to the constructor.

@cartouche
@quotation Note 
Par défaut, @ref{cdb,,timeit()} désactive temporairement le @ref{18a7,,ramasse-miettes} pendant le chronométrage. Cette approche a l'avantage de permettre de comparer des mesures indépendantes. L'inconvénient de cette méthode est que le ramasse-miettes peut avoir un impact significatif sur les performances de la fonction étudiée. Dans ce cas, le ramasse-miettes peut être réactivé en première instruction de la chaîne `setup'. Par exemple :

@example
timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
@end example
@end quotation
@end cartouche
@end deffn

@geindex autorange() (méthode timeit.Timer)
@anchor{library/timeit timeit Timer autorange}@anchor{cda}
@deffn {Méthode} autorange (callback=None)

Détermine automatiquement combien de fois appeler @ref{cdb,,timeit()}.

This is a convenience function that calls @ref{cdb,,timeit()} repeatedly
so that the total time >= 0.2 second, returning the eventual
(number of loops, time taken for that number of loops). It calls
@ref{cdb,,timeit()} with increasing numbers from the sequence 1, 2, 5,
10, 20, 50, ... until the time taken is at least 0.2 seconds.

Si `callback' est spécifié et n'est pas @code{None}, elle est appelée après chaque itération avec deux arguments (numéro de l'itération et temps écoulé) : @code{callback(number, time_taken)}.


Ajouté dans la version 3.6.

@end deffn

@geindex repeat() (méthode timeit.Timer)
@anchor{library/timeit timeit Timer repeat}@anchor{41d0}
@deffn {Méthode} repeat (repeat=5, number=1000000)

Appelle @ref{cdb,,timeit()} plusieurs fois.

Cette fonction d'agrément appelle @ref{cdb,,timeit()} à plusieurs reprises et renvoie une liste de résultats. Le premier argument spécifie le nombre d'appels à @ref{cdb,,timeit()}. Le second argument spécifie l'argument `number' de @ref{cdb,,timeit()}.

@cartouche
@quotation Note 
Il est tentant de vouloir calculer la moyenne et l'écart-type des résultats et notifier ces valeurs. Ce n'est cependant pas très utile. En pratique, la valeur la plus basse donne une estimation basse de la vitesse maximale à laquelle votre machine peut exécuter le fragment de code spécifié ; les valeurs hautes de la liste sont typiquement provoquées non pas par une variabilité de la vitesse d'exécution de Python, mais par d'autres processus interférant avec la précision du chronométrage. Le @ref{ef3,,min()} du résultat est probablement la seule valeur à laquelle vous devriez vous intéresser. Pour aller plus loin, vous devriez regarder l'intégralité des résultats et utiliser le bon sens plutôt que les statistiques.
@end quotation
@end cartouche


Modifié dans la version 3.7: La valeur par défaut de `repeat' est passée de 3 à 5.

@end deffn

@geindex print_exc() (méthode timeit.Timer)
@anchor{library/timeit timeit Timer print_exc}@anchor{41d2}
@deffn {Méthode} print_exc (file=None)

Outil permettant d'afficher la trace du code chronométré.

Usage typique :

@example
t = Timer(...)       # outside the try/except
try:
    t.timeit(...)    # or t.repeat(...)
except Exception:
    t.print_exc()
@end example

L'avantage par rapport à la trace standard est que les lignes sources du code compilé sont affichées. Le paramètre optionnel `file' définit l'endroit où la trace est envoyée, par défaut @ref{926,,sys.stderr}.
@end deffn
@end deffn

@node Interface en ligne de commande<6>,Exemples<29>,Interface Python,timeit --- Measure execution time of small code snippets
@anchor{library/timeit command-line-interface}@anchor{41d3}@anchor{library/timeit timeit-command-line-interface}@anchor{41ca}
@subsubsection Interface en ligne de commande


Lorsque le module est appelé comme un programme en ligne de commande, la syntaxe suivante est utilisée :

@example
python -m timeit [-n N] [-r N] [-u U] [-s S] [-p] [-v] [-h] [statement ...]
@end example

Les options suivantes sont gérées :

@geindex option de ligne de commande timeit; -n
@geindex option de ligne de commande timeit; --number
@anchor{library/timeit cmdoption-timeit-n}@anchor{41d4}@anchor{library/timeit cmdoption-timeit-number}@anchor{41d5}
@deffn {Option} @w{-}n N, @w{-}@w{-}number=N

nombre d'exécutions de l'instruction `statement'
@end deffn

@geindex option de ligne de commande timeit; -r
@geindex option de ligne de commande timeit; --repeat
@anchor{library/timeit cmdoption-timeit-r}@anchor{41d6}@anchor{library/timeit cmdoption-timeit-repeat}@anchor{41d7}
@deffn {Option} @w{-}r N, @w{-}@w{-}repeat=N

nombre de répétitions du chronomètre (5 par défaut)
@end deffn

@geindex option de ligne de commande timeit; -s
@geindex option de ligne de commande timeit; --setup
@anchor{library/timeit cmdoption-timeit-s}@anchor{41d8}@anchor{library/timeit cmdoption-timeit-setup}@anchor{41d9}
@deffn {Option} @w{-}s S, @w{-}@w{-}setup=S

instruction exécutée une seule fois à l'initialisation (@code{pass} par défaut)
@end deffn

@geindex option de ligne de commande timeit; -p
@geindex option de ligne de commande timeit; --process
@anchor{library/timeit cmdoption-timeit-p}@anchor{41da}@anchor{library/timeit cmdoption-timeit-process}@anchor{41db}
@deffn {Option} @w{-}p, @w{-}@w{-}process

mesure le temps au niveau du processus et non au niveau du système, en utilisant @ref{a77,,time.process_time()} plutôt que @ref{a76,,time.perf_counter()} qui est utilisée par défaut


Ajouté dans la version 3.3.

@end deffn

@geindex option de ligne de commande timeit; -u
@geindex option de ligne de commande timeit; --unit
@anchor{library/timeit cmdoption-timeit-u}@anchor{41dc}@anchor{library/timeit cmdoption-timeit-unit}@anchor{41dd}
@deffn {Option} @w{-}u, @w{-}@w{-}unit=U

specify a time unit for timer output; can select @code{nsec}, @code{usec}, @code{msec}, or @code{sec}


Ajouté dans la version 3.5.

@end deffn

@geindex option de ligne de commande timeit; -v
@geindex option de ligne de commande timeit; --verbose
@anchor{library/timeit cmdoption-timeit-v}@anchor{41de}@anchor{library/timeit cmdoption-timeit-verbose}@anchor{41df}
@deffn {Option} @w{-}v, @w{-}@w{-}verbose

affiche les temps d'exécutions bruts, répéter pour plus de précision
@end deffn

@geindex option de ligne de commande timeit; -h
@geindex option de ligne de commande timeit; --help
@anchor{library/timeit cmdoption-timeit-h}@anchor{41e0}@anchor{library/timeit cmdoption-timeit-help}@anchor{41e1}
@deffn {Option} @w{-}h, @w{-}@w{-}help

affiche un court message d'aide puis quitte
@end deffn

Une instruction sur plusieurs lignes peut être donnée en entrée en spécifiant chaque ligne comme un argument séparé. Indenter une ligne est possible en encadrant l'argument de guillemets et en le préfixant par des espaces. Plusieurs @ref{41d8,,-s} sont gérées de la même façon.

Si @ref{41d4,,-n} n'est pas donnée, un nombre de boucles approprié est calculé en essayant des nombres croissants de la séquence 1, 2, 5, 10, 20, 50, ... jusqu'à ce que le temps total d'exécution dépasse 0,2 secondes.

Les mesures de @ref{41d1,,default_timer()} peuvent être altérées par d'autres programmes s'exécutant sur la même machine. La meilleure approche lorsqu'un chronométrage exact est nécessaire est de répéter celui-ci à plusieurs reprises et considérer le meilleur temps. L'option @ref{41d6,,-r} est adaptée à ce fonctionnement, les cinq répétitions par défaut suffisent probablement dans la plupart des cas. Vous pouvez utiliser @ref{a77,,time.process_time()} pour mesurer le temps processeur.

@cartouche
@quotation Note 
Il existe un surcoût minimal associé à l'exécution de l'instruction @code{pass}. Le code présenté ici ne tente pas de le masquer, mais vous devez être conscient de son existence. Ce surcoût minimal peut être mesuré en invoquant le programme sans argument ; il peut différer en fonction des versions de Python.
@end quotation
@end cartouche

@node Exemples<29>,,Interface en ligne de commande<6>,timeit --- Measure execution time of small code snippets
@anchor{library/timeit examples}@anchor{41e2}@anchor{library/timeit timeit-examples}@anchor{41cd}
@subsubsection Exemples


Il est possible de fournir une instruction de mise en place exécutée une seule fois au début du chronométrage :

@example
$ python -m timeit -s "text = 'sample string'; char = 'g'" "char in text"
5000000 loops, best of 5: 0.0877 usec per loop
$ python -m timeit -s "text = 'sample string'; char = 'g'" "text.find(char)"
1000000 loops, best of 5: 0.342 usec per loop
@end example

In the output, there are three fields. The loop count, which tells you how many
times the statement body was run per timing loop repetition. The repetition
count ('best of 5') which tells you how many times the timing loop was
repeated, and finally the time the statement body took on average within the
best repetition of the timing loop. That is, the time the fastest repetition
took divided by the loop count.

@example
>>> import timeit
>>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"')
0.41440500499993504
>>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"')
1.7246671520006203
@end example

La même chose peut être réalisée en utilisant la classe @ref{147c,,Timer} et ses méthodes :

@example
>>> import timeit
>>> t = timeit.Timer('char in text', setup='text = "sample string"; char = "g"')
>>> t.timeit()
0.3955516149999312
>>> t.repeat()
[0.40183617287970225, 0.37027556854118704, 0.38344867356679524, 0.3712595970846668, 0.37866875250654886]
@end example

Les exemples qui suivent montrent comment chronométrer des expressions sur plusieurs lignes. Nous comparons ici le coût d'utilisation de @ref{4bb,,hasattr()} par rapport à @ref{6d3,,try}/@ref{189,,except} pour tester la présence ou l'absence d'attributs d'un objet :

@example
$ python -m timeit "try:" "  str.__bool__" "except AttributeError:" "  pass"
20000 loops, best of 5: 15.7 usec per loop
$ python -m timeit "if hasattr(str, '__bool__'): pass"
50000 loops, best of 5: 4.26 usec per loop

$ python -m timeit "try:" "  int.__bool__" "except AttributeError:" "  pass"
200000 loops, best of 5: 1.43 usec per loop
$ python -m timeit "if hasattr(int, '__bool__'): pass"
100000 loops, best of 5: 2.23 usec per loop
@end example

@example
>>> import timeit
>>> # attribute is missing
>>> s = """\
... try:
...     str.__bool__
... except AttributeError:
...     pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.9138244460009446
>>> s = "if hasattr(str, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.5829014980008651
>>>
>>> # attribute is present
>>> s = """\
... try:
...     int.__bool__
... except AttributeError:
...     pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.04215312199994514
>>> s = "if hasattr(int, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.08588060699912603
@end example

Afin de permettre à @ref{ee,,timeit} d'accéder aux fonctions que vous avez définies, vous pouvez passer au paramètre `setup' une instruction d'importation :

@example
def test():
    """Stupid test function"""
    L = [i for i in range(100)]

if __name__ == '__main__':
    import timeit
    print(timeit.timeit("test()", setup="from __main__ import test"))
@end example

Une autre possibilité est de passer @ref{17f5,,globals()} au paramètre `globals', ceci qui exécutera le code dans l'espace de nommage global courant. Cela peut être plus pratique que de spécifier manuellement des importations :

@example
def f(x):
    return x**2
def g(x):
    return x**4
def h(x):
    return x**8

import timeit
print(timeit.timeit('[func(42) for func in (f,g,h)]', globals=globals()))
@end example

@node trace --- Trace or track Python statement execution,tracemalloc --- Trace memory allocations,timeit --- Measure execution time of small code snippets,Débogueur et instrumentation
@anchor{library/trace doc}@anchor{41e3}@anchor{library/trace module-trace}@anchor{fc}@anchor{library/trace trace-trace-or-track-python-statement-execution}@anchor{41e4}
@subsection @code{trace} --- Trace or track Python statement execution


@geindex module; trace

`Code source :' Lib/abc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/abc.py}


__________________________________________________________________


The @ref{fc,,trace} module allows you to trace program execution, generate
annotated statement coverage listings, print caller/callee relationships and
list functions executed during a program run.  It can be used in another program
or from the command line.


@subsubheading Voir aussi



@table @asis

@item Coverage.py@footnote{https://coverage.readthedocs.io/}

A popular third-party coverage tool that provides HTML
output along with advanced features such as branch coverage.
@end table


@menu
* Utilisation en ligne de commande.: Utilisation en ligne de commande<3>. 
* Programmatic Interface:: 

@end menu

@node Utilisation en ligne de commande<3>,Programmatic Interface,,trace --- Trace or track Python statement execution
@anchor{library/trace command-line-usage}@anchor{41e5}@anchor{library/trace trace-cli}@anchor{41e6}
@subsubsection Utilisation en ligne de commande.


The @ref{fc,,trace} module can be invoked from the command line.  It can be as
simple as

@example
python -m trace --count -C . somefile.py ...
@end example

The above will execute @code{somefile.py} and generate annotated listings of
all Python modules imported during the execution into the current directory.

@geindex option de ligne de commande trace; --help
@anchor{library/trace cmdoption-trace-help}@anchor{41e7}
@deffn {Option} @w{-}@w{-}help

Display usage and exit.
@end deffn

@geindex option de ligne de commande trace; --version
@anchor{library/trace cmdoption-trace-version}@anchor{41e8}
@deffn {Option} @w{-}@w{-}version

Display the version of the module and exit.
@end deffn


Ajouté dans la version 3.8: Added @code{--module} option that allows to run an executable module.


@menu
* Main options:: 
* Modifiers:: 
* Filters:: 

@end menu

@node Main options,Modifiers,,Utilisation en ligne de commande<3>
@anchor{library/trace main-options}@anchor{41e9}
@subsubsection Main options


At least one of the following options must be specified when invoking
@ref{fc,,trace}.  The @ref{41ea,,--listfuncs} option is mutually exclusive with
the @ref{41eb,,--trace} and @ref{41ec,,--count} options. When
@ref{41ea,,--listfuncs} is provided, neither @ref{41ec,,--count} nor
@ref{41eb,,--trace} are accepted, and vice versa.

@geindex option de ligne de commande trace; -c
@geindex option de ligne de commande trace; --count
@anchor{library/trace cmdoption-trace-c}@anchor{41ec}@anchor{library/trace cmdoption-trace-count}@anchor{41ed}
@deffn {Option} @w{-}c, @w{-}@w{-}count

Produce a set of annotated listing files upon program completion that shows
how many times each statement was executed.  See also
@ref{41ee,,--coverdir}, @ref{41ef,,--file} and
@ref{41f0,,--no-report} below.
@end deffn

@geindex option de ligne de commande trace; -t
@geindex option de ligne de commande trace; --trace
@anchor{library/trace cmdoption-trace-t}@anchor{41eb}@anchor{library/trace cmdoption-trace-trace}@anchor{41f1}
@deffn {Option} @w{-}t, @w{-}@w{-}trace

Display lines as they are executed.
@end deffn

@geindex option de ligne de commande trace; -l
@geindex option de ligne de commande trace; --listfuncs
@anchor{library/trace cmdoption-trace-l}@anchor{41ea}@anchor{library/trace cmdoption-trace-listfuncs}@anchor{41f2}
@deffn {Option} @w{-}l, @w{-}@w{-}listfuncs

Display the functions executed by running the program.
@end deffn

@geindex option de ligne de commande trace; -r
@geindex option de ligne de commande trace; --report
@anchor{library/trace cmdoption-trace-r}@anchor{41f3}@anchor{library/trace cmdoption-trace-report}@anchor{41f4}
@deffn {Option} @w{-}r, @w{-}@w{-}report

Produce an annotated list from an earlier program run that used the
@ref{41ec,,--count} and @ref{41ef,,--file} option.  This does not
execute any code.
@end deffn

@geindex option de ligne de commande trace; -T
@geindex option de ligne de commande trace; --trackcalls
@anchor{library/trace cmdoption-trace-T}@anchor{41f5}@anchor{library/trace cmdoption-trace-trackcalls}@anchor{41f6}
@deffn {Option} @w{-}T, @w{-}@w{-}trackcalls

Display the calling relationships exposed by running the program.
@end deffn

@node Modifiers,Filters,Main options,Utilisation en ligne de commande<3>
@anchor{library/trace modifiers}@anchor{41f7}
@subsubsection Modifiers


@geindex option de ligne de commande trace; -f
@geindex option de ligne de commande trace; --file
@anchor{library/trace cmdoption-trace-f}@anchor{41ef}@anchor{library/trace cmdoption-trace-file}@anchor{41f8}
@deffn {Option} @w{-}f, @w{-}@w{-}file=<file>

Name of a file to accumulate counts over several tracing runs.  Should be
used with the @ref{41ec,,--count} option.
@end deffn

@geindex option de ligne de commande trace; -C
@geindex option de ligne de commande trace; --coverdir
@anchor{library/trace cmdoption-trace-C}@anchor{41ee}@anchor{library/trace cmdoption-trace-coverdir}@anchor{41f9}
@deffn {Option} @w{-}C, @w{-}@w{-}coverdir=<dir>

Directory where the report files go.  The coverage report for
@code{package.module} is written to file @code{`dir'/`package'/`module'.cover}.
@end deffn

@geindex option de ligne de commande trace; -m
@geindex option de ligne de commande trace; --missing
@anchor{library/trace cmdoption-trace-m}@anchor{41fa}@anchor{library/trace cmdoption-trace-missing}@anchor{41fb}
@deffn {Option} @w{-}m, @w{-}@w{-}missing

When generating annotated listings, mark lines which were not executed with
@code{>>>>>>}.
@end deffn

@geindex option de ligne de commande trace; -s
@geindex option de ligne de commande trace; --summary
@anchor{library/trace cmdoption-trace-s}@anchor{41fc}@anchor{library/trace cmdoption-trace-summary}@anchor{41fd}
@deffn {Option} @w{-}s, @w{-}@w{-}summary

When using @ref{41ec,,--count} or @ref{41f3,,--report}, write a brief
summary to stdout for each file processed.
@end deffn

@geindex option de ligne de commande trace; -R
@geindex option de ligne de commande trace; --no-report
@anchor{library/trace cmdoption-trace-R}@anchor{41f0}@anchor{library/trace cmdoption-trace-no-report}@anchor{41fe}
@deffn {Option} @w{-}R, @w{-}@w{-}no@w{-}report

Do not generate annotated listings.  This is useful if you intend to make
several runs with @ref{41ec,,--count}, and then produce a single set of
annotated listings at the end.
@end deffn

@geindex option de ligne de commande trace; -g
@geindex option de ligne de commande trace; --timing
@anchor{library/trace cmdoption-trace-g}@anchor{41ff}@anchor{library/trace cmdoption-trace-timing}@anchor{4200}
@deffn {Option} @w{-}g, @w{-}@w{-}timing

Prefix each line with the time since the program started.  Only used while
tracing.
@end deffn

@node Filters,,Modifiers,Utilisation en ligne de commande<3>
@anchor{library/trace filters}@anchor{4201}
@subsubsection Filters


These options may be repeated multiple times.

@geindex option de ligne de commande trace; --ignore-module
@anchor{library/trace cmdoption-trace-ignore-module}@anchor{4202}
@deffn {Option} @w{-}@w{-}ignore@w{-}module=<mod>

Ignore each of the given module names and its submodules (if it is a
package).  The argument can be a list of names separated by a comma.
@end deffn

@geindex option de ligne de commande trace; --ignore-dir
@anchor{library/trace cmdoption-trace-ignore-dir}@anchor{4203}
@deffn {Option} @w{-}@w{-}ignore@w{-}dir=<dir>

Ignore all modules and packages in the named directory and subdirectories.
The argument can be a list of directories separated by @ref{1cd0,,os.pathsep}.
@end deffn

@node Programmatic Interface,,Utilisation en ligne de commande<3>,trace --- Trace or track Python statement execution
@anchor{library/trace programmatic-interface}@anchor{4204}@anchor{library/trace trace-api}@anchor{4205}
@subsubsection Programmatic Interface


@geindex Trace (classe dans trace)
@anchor{library/trace trace Trace}@anchor{4206}
@deffn {Classe} trace.Trace (count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

Create an object to trace execution of a single statement or expression.  All
parameters are optional.  `count' enables counting of line numbers.  `trace'
enables line execution tracing.  `countfuncs' enables listing of the
functions called during the run.  `countcallers' enables call relationship
tracking.  `ignoremods' is a list of modules or packages to ignore.
`ignoredirs' is a list of directories whose modules or packages should be
ignored.  `infile' is the name of the file from which to read stored count
information.  `outfile' is the name of the file in which to write updated
count information.  `timing' enables a timestamp relative to when tracing was
started to be displayed.

@geindex run() (méthode trace.Trace)
@anchor{library/trace trace Trace run}@anchor{4207}
@deffn {Méthode} run (cmd)

Execute the command and gather statistics from the execution with
the current tracing parameters.  `cmd' must be a string or code object,
suitable for passing into @ref{17d,,exec()}.
@end deffn

@geindex runctx() (méthode trace.Trace)
@anchor{library/trace trace Trace runctx}@anchor{4208}
@deffn {Méthode} runctx (cmd, globals=None, locals=None)

Execute the command and gather statistics from the execution with the
current tracing parameters, in the defined global and local
environments.  If not defined, `globals' and `locals' default to empty
dictionaries.
@end deffn

@geindex runfunc() (méthode trace.Trace)
@anchor{library/trace trace Trace runfunc}@anchor{a6d}
@deffn {Méthode} runfunc (func, /, *args, **kwds)

Call `func' with the given arguments under control of the @ref{4206,,Trace}
object with the current tracing parameters.
@end deffn

@geindex results() (méthode trace.Trace)
@anchor{library/trace trace Trace results}@anchor{4209}
@deffn {Méthode} results ()

Return a @ref{420a,,CoverageResults} object that contains the cumulative
results of all previous calls to @code{run}, @code{runctx} and @code{runfunc}
for the given @ref{4206,,Trace} instance.  Does not reset the accumulated
trace results.
@end deffn
@end deffn

@geindex CoverageResults (classe dans trace)
@anchor{library/trace trace CoverageResults}@anchor{420a}
@deffn {Classe} trace.CoverageResults

A container for coverage results, created by @ref{4209,,Trace.results()}.  Should
not be created directly by the user.

@geindex update() (méthode trace.CoverageResults)
@anchor{library/trace trace CoverageResults update}@anchor{420b}
@deffn {Méthode} update (other)

Merge in data from another @ref{420a,,CoverageResults} object.
@end deffn

@geindex write_results() (méthode trace.CoverageResults)
@anchor{library/trace trace CoverageResults write_results}@anchor{420c}
@deffn {Méthode} write_results (show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

Write coverage results.  Set `show_missing' to show lines that had no
hits.  Set `summary' to include in the output the coverage summary per
module.  `coverdir' specifies the directory into which the coverage
result files will be output.  If @code{None}, the results for each source
file are placed in its directory.

If `ignore_missing_files' is @code{True}, coverage counts for files that no
longer exist are silently ignored. Otherwise, a missing file will
raise a @ref{eae,,FileNotFoundError}.


Modifié dans la version 3.13: Added `ignore_missing_files' parameter.

@end deffn
@end deffn

A simple example demonstrating the use of the programmatic interface:

@example
import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")
@end example

@node tracemalloc --- Trace memory allocations,,trace --- Trace or track Python statement execution,Débogueur et instrumentation
@anchor{library/tracemalloc doc}@anchor{420d}@anchor{library/tracemalloc module-tracemalloc}@anchor{fe}@anchor{library/tracemalloc tracemalloc-trace-memory-allocations}@anchor{420e}
@subsection @code{tracemalloc} --- Trace memory allocations


@geindex module; tracemalloc


Ajouté dans la version 3.4.


`Source code:' Lib/tracemalloc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tracemalloc.py}


__________________________________________________________________


The tracemalloc module is a debug tool to trace memory blocks allocated by
Python. It provides the following information:


@itemize *

@item 
Traceback where an object was allocated

@item 
Statistics on allocated memory blocks per filename and per line number:
total size, number and average size of allocated memory blocks

@item 
Compute the differences between two snapshots to detect memory leaks
@end itemize

To trace most memory blocks allocated by Python, the module should be started
as early as possible by setting the 
@geindex PYTHONTRACEMALLOC
@geindex variable d'environnement; PYTHONTRACEMALLOC
@ref{1cc8,,PYTHONTRACEMALLOC} environment
variable to @code{1}, or by using @ref{175,,-X} @code{tracemalloc} command line
option. The @ref{1cc7,,tracemalloc.start()} function can be called at runtime to
start tracing Python memory allocations.

By default, a trace of an allocated memory block only stores the most recent
frame (1 frame). To store 25 frames at startup: set the
@geindex PYTHONTRACEMALLOC
@geindex variable d'environnement; PYTHONTRACEMALLOC
@ref{1cc8,,PYTHONTRACEMALLOC} environment variable to @code{25}, or use the
@ref{175,,-X} @code{tracemalloc=25} command line option.

@menu
* Exemples: Exemples<30>. 
* API:: 

@end menu

@node Exemples<30>,API,,tracemalloc --- Trace memory allocations
@anchor{library/tracemalloc examples}@anchor{420f}
@subsubsection Exemples


@menu
* Display the top 10:: 
* Compute differences:: 
* Get the traceback of a memory block:: 
* Pretty top:: 

@end menu

@node Display the top 10,Compute differences,,Exemples<30>
@anchor{library/tracemalloc display-the-top-10}@anchor{4210}
@subsubsection Display the top 10


Display the 10 files allocating the most memory:

@example
import tracemalloc

tracemalloc.start()

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')

print("[ Top 10 ]")
for stat in top_stats[:10]:
    print(stat)
@end example

Example of output of the Python test suite:

@example
[ Top 10 ]
<frozen importlib._bootstrap>:716: size=4855 KiB, count=39328, average=126 B
<frozen importlib._bootstrap>:284: size=521 KiB, count=3199, average=167 B
/usr/lib/python3.4/collections/__init__.py:368: size=244 KiB, count=2315, average=108 B
/usr/lib/python3.4/unittest/case.py:381: size=185 KiB, count=779, average=243 B
/usr/lib/python3.4/unittest/case.py:402: size=154 KiB, count=378, average=416 B
/usr/lib/python3.4/abc.py:133: size=88.7 KiB, count=347, average=262 B
<frozen importlib._bootstrap>:1446: size=70.4 KiB, count=911, average=79 B
<frozen importlib._bootstrap>:1454: size=52.0 KiB, count=25, average=2131 B
<string>:5: size=49.7 KiB, count=148, average=344 B
/usr/lib/python3.4/sysconfig.py:411: size=48.0 KiB, count=1, average=48.0 KiB
@end example

We can see that Python loaded @code{4855 KiB} data (bytecode and constants) from
modules and that the @ref{1d,,collections} module allocated @code{244 KiB} to build
@ref{1c5,,namedtuple} types.

See @ref{4211,,Snapshot.statistics()} for more options.

@node Compute differences,Get the traceback of a memory block,Display the top 10,Exemples<30>
@anchor{library/tracemalloc compute-differences}@anchor{4212}
@subsubsection Compute differences


Take two snapshots and display the differences:

@example
import tracemalloc
tracemalloc.start()
# ... start your application ...

snapshot1 = tracemalloc.take_snapshot()
# ... call the function leaking memory ...
snapshot2 = tracemalloc.take_snapshot()

top_stats = snapshot2.compare_to(snapshot1, 'lineno')

print("[ Top 10 differences ]")
for stat in top_stats[:10]:
    print(stat)
@end example

Example of output before/after running some tests of the Python test suite:

@example
[ Top 10 differences ]
<frozen importlib._bootstrap>:716: size=8173 KiB (+4428 KiB), count=71332 (+39369), average=117 B
/usr/lib/python3.4/linecache.py:127: size=940 KiB (+940 KiB), count=8106 (+8106), average=119 B
/usr/lib/python3.4/unittest/case.py:571: size=298 KiB (+298 KiB), count=589 (+589), average=519 B
<frozen importlib._bootstrap>:284: size=1005 KiB (+166 KiB), count=7423 (+1526), average=139 B
/usr/lib/python3.4/mimetypes.py:217: size=112 KiB (+112 KiB), count=1334 (+1334), average=86 B
/usr/lib/python3.4/http/server.py:848: size=96.0 KiB (+96.0 KiB), count=1 (+1), average=96.0 KiB
/usr/lib/python3.4/inspect.py:1465: size=83.5 KiB (+83.5 KiB), count=109 (+109), average=784 B
/usr/lib/python3.4/unittest/mock.py:491: size=77.7 KiB (+77.7 KiB), count=143 (+143), average=557 B
/usr/lib/python3.4/urllib/parse.py:476: size=71.8 KiB (+71.8 KiB), count=969 (+969), average=76 B
/usr/lib/python3.4/contextlib.py:38: size=67.2 KiB (+67.2 KiB), count=126 (+126), average=546 B
@end example

We can see that Python has loaded @code{8173 KiB} of module data (bytecode and
constants), and that this is @code{4428 KiB} more than had been loaded before the
tests, when the previous snapshot was taken. Similarly, the @ref{84,,linecache}
module has cached @code{940 KiB} of Python source code to format tracebacks, all
of it since the previous snapshot.

If the system has little free memory, snapshots can be written on disk using
the @ref{4213,,Snapshot.dump()} method to analyze the snapshot offline. Then use the
@ref{4214,,Snapshot.load()} method reload the snapshot.

@node Get the traceback of a memory block,Pretty top,Compute differences,Exemples<30>
@anchor{library/tracemalloc get-the-traceback-of-a-memory-block}@anchor{4215}
@subsubsection Get the traceback of a memory block


Code to display the traceback of the biggest memory block:

@example
import tracemalloc

# Store 25 frames
tracemalloc.start(25)

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('traceback')

# pick the biggest memory block
stat = top_stats[0]
print("%s memory blocks: %.1f KiB" % (stat.count, stat.size / 1024))
for line in stat.traceback.format():
    print(line)
@end example

Example of output of the Python test suite (traceback limited to 25 frames):

@example
903 memory blocks: 870.1 KiB
  File "<frozen importlib._bootstrap>", line 716
  File "<frozen importlib._bootstrap>", line 1036
  File "<frozen importlib._bootstrap>", line 934
  File "<frozen importlib._bootstrap>", line 1068
  File "<frozen importlib._bootstrap>", line 619
  File "<frozen importlib._bootstrap>", line 1581
  File "<frozen importlib._bootstrap>", line 1614
  File "/usr/lib/python3.4/doctest.py", line 101
    import pdb
  File "<frozen importlib._bootstrap>", line 284
  File "<frozen importlib._bootstrap>", line 938
  File "<frozen importlib._bootstrap>", line 1068
  File "<frozen importlib._bootstrap>", line 619
  File "<frozen importlib._bootstrap>", line 1581
  File "<frozen importlib._bootstrap>", line 1614
  File "/usr/lib/python3.4/test/support/__init__.py", line 1728
    import doctest
  File "/usr/lib/python3.4/test/test_pickletools.py", line 21
    support.run_doctest(pickletools)
  File "/usr/lib/python3.4/test/regrtest.py", line 1276
    test_runner()
  File "/usr/lib/python3.4/test/regrtest.py", line 976
    display_failure=not verbose)
  File "/usr/lib/python3.4/test/regrtest.py", line 761
    match_tests=ns.match_tests)
  File "/usr/lib/python3.4/test/regrtest.py", line 1563
    main()
  File "/usr/lib/python3.4/test/__main__.py", line 3
    regrtest.main_in_temp_cwd()
  File "/usr/lib/python3.4/runpy.py", line 73
    exec(code, run_globals)
  File "/usr/lib/python3.4/runpy.py", line 160
    "__main__", fname, loader, pkg_name)
@end example

We can see that the most memory was allocated in the @ref{76,,importlib} module to
load data (bytecode and constants) from modules: @code{870.1 KiB}. The traceback is
where the @ref{76,,importlib} loaded data most recently: on the @code{import pdb}
line of the @ref{3a,,doctest} module. The traceback may change if a new module is
loaded.

@node Pretty top,,Get the traceback of a memory block,Exemples<30>
@anchor{library/tracemalloc pretty-top}@anchor{4216}
@subsubsection Pretty top


Code to display the 10 lines allocating the most memory with a pretty output,
ignoring @code{<frozen importlib._bootstrap>} and @code{<unknown>} files:

@example
import linecache
import os
import tracemalloc

def display_top(snapshot, key_type='lineno', limit=10):
    snapshot = snapshot.filter_traces((
        tracemalloc.Filter(False, "<frozen importlib._bootstrap>"),
        tracemalloc.Filter(False, "<unknown>"),
    ))
    top_stats = snapshot.statistics(key_type)

    print("Top %s lines" % limit)
    for index, stat in enumerate(top_stats[:limit], 1):
        frame = stat.traceback[0]
        print("#%s: %s:%s: %.1f KiB"
              % (index, frame.filename, frame.lineno, stat.size / 1024))
        line = linecache.getline(frame.filename, frame.lineno).strip()
        if line:
            print('    %s' % line)

    other = top_stats[limit:]
    if other:
        size = sum(stat.size for stat in other)
        print("%s other: %.1f KiB" % (len(other), size / 1024))
    total = sum(stat.size for stat in top_stats)
    print("Total allocated size: %.1f KiB" % (total / 1024))

tracemalloc.start()

# ... run your application ...

snapshot = tracemalloc.take_snapshot()
display_top(snapshot)
@end example

Example of output of the Python test suite:

@example
Top 10 lines
#1: Lib/base64.py:414: 419.8 KiB
    _b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
#2: Lib/base64.py:306: 419.8 KiB
    _a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
#3: collections/__init__.py:368: 293.6 KiB
    exec(class_definition, namespace)
#4: Lib/abc.py:133: 115.2 KiB
    cls = super().__new__(mcls, name, bases, namespace)
#5: unittest/case.py:574: 103.1 KiB
    testMethod()
#6: Lib/linecache.py:127: 95.4 KiB
    lines = fp.readlines()
#7: urllib/parse.py:476: 71.8 KiB
    for a in _hexdig for b in _hexdig@}
#8: <string>:5: 62.0 KiB
#9: Lib/_weakrefset.py:37: 60.0 KiB
    self.data = set()
#10: Lib/base64.py:142: 59.8 KiB
    _b32tab2 = [a + b for a in _b32tab for b in _b32tab]
6220 other: 3602.8 KiB
Total allocated size: 5303.1 KiB
@end example

See @ref{4211,,Snapshot.statistics()} for more options.

@menu
* Record the current and peak size of all traced memory blocks:: 

@end menu

@node Record the current and peak size of all traced memory blocks,,,Pretty top
@anchor{library/tracemalloc record-the-current-and-peak-size-of-all-traced-memory-blocks}@anchor{4217}
@subsubsection Record the current and peak size of all traced memory blocks


The following code computes two sums like @code{0 + 1 + 2 + ...} inefficiently, by
creating a list of those numbers. This list consumes a lot of memory
temporarily. We can use @ref{4218,,get_traced_memory()} and @ref{928,,reset_peak()} to
observe the small memory usage after the sum is computed as well as the peak
memory usage during the computations:

@example
import tracemalloc

tracemalloc.start()

# Example code: compute a sum with a large temporary list
large_sum = sum(list(range(100000)))

first_size, first_peak = tracemalloc.get_traced_memory()

tracemalloc.reset_peak()

# Example code: compute a sum with a small temporary list
small_sum = sum(list(range(1000)))

second_size, second_peak = tracemalloc.get_traced_memory()

print(f"@{first_size=@}, @{first_peak=@}")
print(f"@{second_size=@}, @{second_peak=@}")
@end example

Sortie :

@example
first_size=664, first_peak=3592984
second_size=804, second_peak=29704
@end example

Using @ref{928,,reset_peak()} ensured we could accurately record the peak during the
computation of @code{small_sum}, even though it is much smaller than the overall
peak size of memory blocks since the @ref{1cc7,,start()} call. Without the call to
@ref{928,,reset_peak()}, @code{second_peak} would still be the peak from the
computation @code{large_sum} (that is, equal to @code{first_peak}). In this case,
both peaks are much higher than the final memory usage, and which suggests we
could optimise (by removing the unnecessary call to @ref{5fc,,list}, and writing
@code{sum(range(...))}).

@node API,,Exemples<30>,tracemalloc --- Trace memory allocations
@anchor{library/tracemalloc api}@anchor{4219}
@subsubsection API


@menu
* Fonctions: Fonctions<11>. 
* DomainFilter:: 
* Filter:: 
* Frame:: 
* Snapshot:: 
* Statistic:: 
* StatisticDiff:: 
* Trace:: 
* Traceback:: 

@end menu

@node Fonctions<11>,DomainFilter,,API
@anchor{library/tracemalloc functions}@anchor{421a}
@subsubsection Fonctions


@geindex clear_traces() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc clear_traces}@anchor{421b}
@deffn {Fonction} tracemalloc.clear_traces ()

Clear traces of memory blocks allocated by Python.

See also @ref{421c,,stop()}.
@end deffn

@geindex get_object_traceback() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc get_object_traceback}@anchor{1ae6}
@deffn {Fonction} tracemalloc.get_object_traceback (obj)

Get the traceback where the Python object `obj' was allocated.
Return a @ref{b84,,Traceback} instance, or @code{None} if the @ref{fe,,tracemalloc}
module is not tracing memory allocations or did not trace the allocation of
the object.

See also @ref{7ee,,gc.get_referrers()} and @ref{16f8,,sys.getsizeof()} functions.
@end deffn

@geindex get_traceback_limit() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc get_traceback_limit}@anchor{421d}
@deffn {Fonction} tracemalloc.get_traceback_limit ()

Get the maximum number of frames stored in the traceback of a trace.

The @ref{fe,,tracemalloc} module must be tracing memory allocations to
get the limit, otherwise an exception is raised.

The limit is set by the @ref{1cc7,,start()} function.
@end deffn

@geindex get_traced_memory() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc get_traced_memory}@anchor{4218}
@deffn {Fonction} tracemalloc.get_traced_memory ()

Get the current size and peak size of memory blocks traced by the
@ref{fe,,tracemalloc} module as a tuple: @code{(current: int, peak: int)}.
@end deffn

@geindex reset_peak() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc reset_peak}@anchor{928}
@deffn {Fonction} tracemalloc.reset_peak ()

Set the peak size of memory blocks traced by the @ref{fe,,tracemalloc} module
to the current size.

Do nothing if the @ref{fe,,tracemalloc} module is not tracing memory
allocations.

This function only modifies the recorded peak size, and does not modify or
clear any traces, unlike @ref{421b,,clear_traces()}. Snapshots taken with
@ref{421e,,take_snapshot()} before a call to @ref{928,,reset_peak()} can be
meaningfully compared to snapshots taken after the call.

See also @ref{4218,,get_traced_memory()}.


Ajouté dans la version 3.9.

@end deffn

@geindex get_tracemalloc_memory() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc get_tracemalloc_memory}@anchor{421f}
@deffn {Fonction} tracemalloc.get_tracemalloc_memory ()

Get the memory usage in bytes of the @ref{fe,,tracemalloc} module used to store
traces of memory blocks.
Return an @ref{254,,int}.
@end deffn

@geindex is_tracing() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc is_tracing}@anchor{4220}
@deffn {Fonction} tracemalloc.is_tracing ()

@code{True} if the @ref{fe,,tracemalloc} module is tracing Python memory
allocations, @code{False} otherwise.

See also @ref{1cc7,,start()} and @ref{421c,,stop()} functions.
@end deffn

@geindex start() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc start}@anchor{1cc7}
@deffn {Fonction} tracemalloc.start (nframe: int = 1)

Start tracing Python memory allocations: install hooks on Python memory
allocators. Collected tracebacks of traces will be limited to `nframe'
frames. By default, a trace of a memory block only stores the most recent
frame: the limit is @code{1}. `nframe' must be greater or equal to @code{1}.

You can still read the original number of total frames that composed the
traceback by looking at the @ref{4221,,Traceback.total_nframe} attribute.

Storing more than @code{1} frame is only useful to compute statistics grouped
by @code{'traceback'} or to compute cumulative statistics: see the
@ref{4222,,Snapshot.compare_to()} and @ref{4211,,Snapshot.statistics()} methods.

Storing more frames increases the memory and CPU overhead of the
@ref{fe,,tracemalloc} module. Use the @ref{421f,,get_tracemalloc_memory()} function
to measure how much memory is used by the @ref{fe,,tracemalloc} module.

The 
@geindex PYTHONTRACEMALLOC
@geindex variable d'environnement; PYTHONTRACEMALLOC
@ref{1cc8,,PYTHONTRACEMALLOC} environment variable
(@code{PYTHONTRACEMALLOC=NFRAME}) and the @ref{175,,-X} @code{tracemalloc=NFRAME}
command line option can be used to start tracing at startup.

See also @ref{421c,,stop()}, @ref{4220,,is_tracing()} and @ref{421d,,get_traceback_limit()}
functions.
@end deffn

@geindex stop() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc stop}@anchor{421c}
@deffn {Fonction} tracemalloc.stop ()

Stop tracing Python memory allocations: uninstall hooks on Python memory
allocators. Also clears all previously collected traces of memory blocks
allocated by Python.

Call @ref{421e,,take_snapshot()} function to take a snapshot of traces before
clearing them.

See also @ref{1cc7,,start()}, @ref{4220,,is_tracing()} and @ref{421b,,clear_traces()}
functions.
@end deffn

@geindex take_snapshot() (dans le module tracemalloc)
@anchor{library/tracemalloc tracemalloc take_snapshot}@anchor{421e}
@deffn {Fonction} tracemalloc.take_snapshot ()

Take a snapshot of traces of memory blocks allocated by Python. Return a new
@ref{4223,,Snapshot} instance.

The snapshot does not include memory blocks allocated before the
@ref{fe,,tracemalloc} module started to trace memory allocations.

Tracebacks of traces are limited to @ref{421d,,get_traceback_limit()} frames. Use
the `nframe' parameter of the @ref{1cc7,,start()} function to store more frames.

The @ref{fe,,tracemalloc} module must be tracing memory allocations to take a
snapshot, see the @ref{1cc7,,start()} function.

See also the @ref{1ae6,,get_object_traceback()} function.
@end deffn

@node DomainFilter,Filter,Fonctions<11>,API
@anchor{library/tracemalloc domainfilter}@anchor{4224}
@subsubsection DomainFilter


@geindex DomainFilter (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc DomainFilter}@anchor{cdf}
@deffn {Classe} tracemalloc.DomainFilter (inclusive: bool, domain: int)

Filter traces of memory blocks by their address space (domain).


Ajouté dans la version 3.6.


@geindex inclusive (attribut tracemalloc.DomainFilter)
@anchor{library/tracemalloc tracemalloc DomainFilter inclusive}@anchor{4225}
@deffn {Attribut} inclusive

If `inclusive' is @code{True} (include), match memory blocks allocated
in the address space @ref{4226,,domain}.

If `inclusive' is @code{False} (exclude), match memory blocks not allocated
in the address space @ref{4226,,domain}.
@end deffn

@geindex domain (attribut tracemalloc.DomainFilter)
@anchor{library/tracemalloc tracemalloc DomainFilter domain}@anchor{4226}
@deffn {Attribut} domain

Address space of a memory block (@code{int}). Read-only property.
@end deffn
@end deffn

@node Filter,Frame,DomainFilter,API
@anchor{library/tracemalloc filter}@anchor{4227}
@subsubsection Filter


@geindex Filter (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc Filter}@anchor{4228}
@deffn {Classe} tracemalloc.Filter (inclusive: bool, filename_pattern: str, lineno: int = None, all_frames: bool = False, domain: int = None)

Filter on traces of memory blocks.

See the @ref{182d,,fnmatch.fnmatch()} function for the syntax of
`filename_pattern'. The @code{'.pyc'} file extension is
replaced with @code{'.py'}.

Exemples :


@itemize *

@item 
@code{Filter(True, subprocess.__file__)} only includes traces of the
@ref{d5,,subprocess} module

@item 
@code{Filter(False, tracemalloc.__file__)} excludes traces of the
@ref{fe,,tracemalloc} module

@item 
@code{Filter(False, "<unknown>")} excludes empty tracebacks
@end itemize


Modifié dans la version 3.5: The @code{'.pyo'} file extension is no longer replaced with @code{'.py'}.



Modifié dans la version 3.6: Added the @ref{4229,,domain} attribute.


@geindex domain (attribut tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter domain}@anchor{4229}
@deffn {Attribut} domain

Address space of a memory block (@code{int} or @code{None}).

tracemalloc uses the domain @code{0} to trace memory allocations made by
Python. C extensions can use other domains to trace other resources.
@end deffn

@geindex inclusive (attribut tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter inclusive}@anchor{422a}
@deffn {Attribut} inclusive

If `inclusive' is @code{True} (include), only match memory blocks allocated
in a file with a name matching @ref{422b,,filename_pattern} at line number
@ref{422c,,lineno}.

If `inclusive' is @code{False} (exclude), ignore memory blocks allocated in
a file with a name matching @ref{422b,,filename_pattern} at line number
@ref{422c,,lineno}.
@end deffn

@geindex lineno (attribut tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter lineno}@anchor{422c}
@deffn {Attribut} lineno

Line number (@code{int}) of the filter. If `lineno' is @code{None}, the filter
matches any line number.
@end deffn

@geindex filename_pattern (attribut tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter filename_pattern}@anchor{422b}
@deffn {Attribut} filename_pattern

Filename pattern of the filter (@code{str}). Read-only property.
@end deffn

@geindex all_frames (attribut tracemalloc.Filter)
@anchor{library/tracemalloc tracemalloc Filter all_frames}@anchor{422d}
@deffn {Attribut} all_frames

If `all_frames' is @code{True}, all frames of the traceback are checked. If
`all_frames' is @code{False}, only the most recent frame is checked.

This attribute has no effect if the traceback limit is @code{1}.  See the
@ref{421d,,get_traceback_limit()} function and @ref{422e,,Snapshot.traceback_limit}
attribute.
@end deffn
@end deffn

@node Frame,Snapshot,Filter,API
@anchor{library/tracemalloc frame}@anchor{422f}
@subsubsection Frame


@geindex Frame (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc Frame}@anchor{4230}
@deffn {Classe} tracemalloc.Frame

Frame of a traceback.

The @ref{b84,,Traceback} class is a sequence of @ref{4230,,Frame} instances.

@geindex filename (attribut tracemalloc.Frame)
@anchor{library/tracemalloc tracemalloc Frame filename}@anchor{4231}
@deffn {Attribut} filename

Filename (@code{str}).
@end deffn

@geindex lineno (attribut tracemalloc.Frame)
@anchor{library/tracemalloc tracemalloc Frame lineno}@anchor{4232}
@deffn {Attribut} lineno

Line number (@code{int}).
@end deffn
@end deffn

@node Snapshot,Statistic,Frame,API
@anchor{library/tracemalloc snapshot}@anchor{4233}
@subsubsection Snapshot


@geindex Snapshot (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc Snapshot}@anchor{4223}
@deffn {Classe} tracemalloc.Snapshot

Snapshot of traces of memory blocks allocated by Python.

The @ref{421e,,take_snapshot()} function creates a snapshot instance.

@geindex compare_to() (méthode tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot compare_to}@anchor{4222}
@deffn {Méthode} compare_to (old_snapshot: Snapshot, key_type: str, cumulative: bool = False)

Compute the differences with an old snapshot. Get statistics as a sorted
list of @ref{4234,,StatisticDiff} instances grouped by `key_type'.

See the @ref{4211,,Snapshot.statistics()} method for `key_type' and `cumulative'
parameters.

The result is sorted from the biggest to the smallest by: absolute value
of @ref{4235,,StatisticDiff.size_diff}, @ref{4236,,StatisticDiff.size}, absolute
value of @ref{4237,,StatisticDiff.count_diff}, @ref{4238,,Statistic.count} and
then by @ref{4239,,StatisticDiff.traceback}.
@end deffn

@geindex dump() (méthode tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot dump}@anchor{4213}
@deffn {Méthode} dump (filename)

Write the snapshot into a file.

Use @ref{4214,,load()} to reload the snapshot.
@end deffn

@geindex filter_traces() (méthode tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot filter_traces}@anchor{423a}
@deffn {Méthode} filter_traces (filters)

Create a new @ref{4223,,Snapshot} instance with a filtered @ref{423b,,traces}
sequence, `filters' is a list of @ref{cdf,,DomainFilter} and
@ref{4228,,Filter} instances.  If `filters' is an empty list, return a new
@ref{4223,,Snapshot} instance with a copy of the traces.

All inclusive filters are applied at once, a trace is ignored if no
inclusive filters match it. A trace is ignored if at least one exclusive
filter matches it.


Modifié dans la version 3.6: @ref{cdf,,DomainFilter} instances are now also accepted in `filters'.

@end deffn

@geindex load() (méthode de la classe tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot load}@anchor{4214}
@deffn {Méthode} classmethod load (filename)

Load a snapshot from a file.

See also @ref{4213,,dump()}.
@end deffn

@geindex statistics() (méthode tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot statistics}@anchor{4211}
@deffn {Méthode} statistics (key_type: str, cumulative: bool = False)

Get statistics as a sorted list of @ref{423c,,Statistic} instances grouped
by `key_type':


@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

key_type

@tab

description

@item

@code{'filename'}

@tab

filename

@item

@code{'lineno'}

@tab

filename and line number

@item

@code{'traceback'}

@tab

traceback

@end multitable


If `cumulative' is @code{True}, cumulate size and count of memory blocks of
all frames of the traceback of a trace, not only the most recent frame.
The cumulative mode can only be used with `key_type' equals to
@code{'filename'} and @code{'lineno'}.

The result is sorted from the biggest to the smallest by:
@ref{423d,,Statistic.size}, @ref{4238,,Statistic.count} and then by
@ref{423e,,Statistic.traceback}.
@end deffn

@geindex traceback_limit (attribut tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot traceback_limit}@anchor{422e}
@deffn {Attribut} traceback_limit

Maximum number of frames stored in the traceback of @ref{423b,,traces}:
result of the @ref{421d,,get_traceback_limit()} when the snapshot was taken.
@end deffn

@geindex traces (attribut tracemalloc.Snapshot)
@anchor{library/tracemalloc tracemalloc Snapshot traces}@anchor{423b}
@deffn {Attribut} traces

Traces of all memory blocks allocated by Python: sequence of
@ref{423f,,Trace} instances.

The sequence has an undefined order. Use the @ref{4211,,Snapshot.statistics()}
method to get a sorted list of statistics.
@end deffn
@end deffn

@node Statistic,StatisticDiff,Snapshot,API
@anchor{library/tracemalloc statistic}@anchor{4240}
@subsubsection Statistic


@geindex Statistic (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc Statistic}@anchor{423c}
@deffn {Classe} tracemalloc.Statistic

Statistic on memory allocations.

@ref{4211,,Snapshot.statistics()} returns a list of @ref{423c,,Statistic} instances.

See also the @ref{4234,,StatisticDiff} class.

@geindex count (attribut tracemalloc.Statistic)
@anchor{library/tracemalloc tracemalloc Statistic count}@anchor{4238}
@deffn {Attribut} count

Number of memory blocks (@code{int}).
@end deffn

@geindex size (attribut tracemalloc.Statistic)
@anchor{library/tracemalloc tracemalloc Statistic size}@anchor{423d}
@deffn {Attribut} size

Total size of memory blocks in bytes (@code{int}).
@end deffn

@geindex traceback (attribut tracemalloc.Statistic)
@anchor{library/tracemalloc tracemalloc Statistic traceback}@anchor{423e}
@deffn {Attribut} traceback

Traceback where the memory block was allocated, @ref{b84,,Traceback}
instance.
@end deffn
@end deffn

@node StatisticDiff,Trace,Statistic,API
@anchor{library/tracemalloc statisticdiff}@anchor{4241}
@subsubsection StatisticDiff


@geindex StatisticDiff (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc StatisticDiff}@anchor{4234}
@deffn {Classe} tracemalloc.StatisticDiff

Statistic difference on memory allocations between an old and a new
@ref{4223,,Snapshot} instance.

@ref{4222,,Snapshot.compare_to()} returns a list of @ref{4234,,StatisticDiff}
instances. See also the @ref{423c,,Statistic} class.

@geindex count (attribut tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff count}@anchor{4242}
@deffn {Attribut} count

Number of memory blocks in the new snapshot (@code{int}): @code{0} if
the memory blocks have been released in the new snapshot.
@end deffn

@geindex count_diff (attribut tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff count_diff}@anchor{4237}
@deffn {Attribut} count_diff

Difference of number of memory blocks between the old and the new
snapshots (@code{int}): @code{0} if the memory blocks have been allocated in
the new snapshot.
@end deffn

@geindex size (attribut tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff size}@anchor{4236}
@deffn {Attribut} size

Total size of memory blocks in bytes in the new snapshot (@code{int}):
@code{0} if the memory blocks have been released in the new snapshot.
@end deffn

@geindex size_diff (attribut tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff size_diff}@anchor{4235}
@deffn {Attribut} size_diff

Difference of total size of memory blocks in bytes between the old and
the new snapshots (@code{int}): @code{0} if the memory blocks have been
allocated in the new snapshot.
@end deffn

@geindex traceback (attribut tracemalloc.StatisticDiff)
@anchor{library/tracemalloc tracemalloc StatisticDiff traceback}@anchor{4239}
@deffn {Attribut} traceback

Traceback where the memory blocks were allocated, @ref{b84,,Traceback}
instance.
@end deffn
@end deffn

@node Trace,Traceback,StatisticDiff,API
@anchor{library/tracemalloc trace}@anchor{4243}
@subsubsection Trace


@geindex Trace (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc Trace}@anchor{423f}
@deffn {Classe} tracemalloc.Trace

Trace of a memory block.

The @ref{423b,,Snapshot.traces} attribute is a sequence of @ref{423f,,Trace}
instances.


Modifié dans la version 3.6: Added the @ref{4244,,domain} attribute.


@geindex domain (attribut tracemalloc.Trace)
@anchor{library/tracemalloc tracemalloc Trace domain}@anchor{4244}
@deffn {Attribut} domain

Address space of a memory block (@code{int}). Read-only property.

tracemalloc uses the domain @code{0} to trace memory allocations made by
Python. C extensions can use other domains to trace other resources.
@end deffn

@geindex size (attribut tracemalloc.Trace)
@anchor{library/tracemalloc tracemalloc Trace size}@anchor{4245}
@deffn {Attribut} size

Size of the memory block in bytes (@code{int}).
@end deffn

@geindex traceback (attribut tracemalloc.Trace)
@anchor{library/tracemalloc tracemalloc Trace traceback}@anchor{4246}
@deffn {Attribut} traceback

Traceback where the memory block was allocated, @ref{b84,,Traceback}
instance.
@end deffn
@end deffn

@node Traceback,,Trace,API
@anchor{library/tracemalloc traceback}@anchor{4247}
@subsubsection Traceback


@geindex Traceback (classe dans tracemalloc)
@anchor{library/tracemalloc tracemalloc Traceback}@anchor{b84}
@deffn {Classe} tracemalloc.Traceback

Sequence of @ref{4230,,Frame} instances sorted from the oldest frame to the
most recent frame.

A traceback contains at least @code{1} frame. If the @code{tracemalloc} module
failed to get a frame, the filename @code{"<unknown>"} at line number @code{0} is
used.

When a snapshot is taken, tracebacks of traces are limited to
@ref{421d,,get_traceback_limit()} frames. See the @ref{421e,,take_snapshot()} function.
The original number of frames of the traceback is stored in the
@ref{4221,,Traceback.total_nframe} attribute. That allows to know if a traceback
has been truncated by the traceback limit.

The @ref{4246,,Trace.traceback} attribute is an instance of @ref{b84,,Traceback}
instance.


Modifié dans la version 3.7: Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.


@geindex total_nframe (attribut tracemalloc.Traceback)
@anchor{library/tracemalloc tracemalloc Traceback total_nframe}@anchor{4221}
@deffn {Attribut} total_nframe

Total number of frames that composed the traceback before truncation.
This attribute can be set to @code{None} if the information is not
available.
@end deffn


Modifié dans la version 3.9: The @ref{4221,,Traceback.total_nframe} attribute was added.


@geindex format() (méthode tracemalloc.Traceback)
@anchor{library/tracemalloc tracemalloc Traceback format}@anchor{b85}
@deffn {Méthode} format (limit=None, most_recent_first=False)

Format the traceback as a list of lines. Use the @ref{84,,linecache} module to
retrieve lines from the source code. If `limit' is set, format the `limit'
most recent frames if `limit' is positive. Otherwise, format the
@code{abs(limit)} oldest frames. If `most_recent_first' is @code{True}, the order
of the formatted frames is reversed, returning the most recent frame first
instead of last.

Similar to the @ref{4248,,traceback.format_tb()} function, except that
@ref{b85,,format()} does not include newlines.

Exemple :

@example
print("Traceback (most recent call first):")
for line in traceback:
    print(line)
@end example

Sortie :

@example
Traceback (most recent call first):
  File "test.py", line 9
    obj = Object()
  File "test.py", line 12
    tb = tracemalloc.get_object_traceback(f())
@end example
@end deffn
@end deffn

@node Paquets et distribution de paquets logiciels,Environnement d'exécution Python,Débogueur et instrumentation,La bibliothèque standard
@anchor{library/distribution doc}@anchor{4249}@anchor{library/distribution software-packaging-and-distribution}@anchor{424a}
@section Paquets et distribution de paquets logiciels


Ces bibliothèques vous aident lors de la publication et l'installation de logiciels Python. Bien que ces modules sont conçus pour fonctionner avec le Python Package Index@footnote{https://pypi.org}, ils peuvent aussi être utilisés avec un serveur local, ou sans serveur.

@menu
* ensurepip: ensurepip --- Bootstrapping the pip installer. Bootstrapping the pip installer
* venv: venv --- Creation of virtual environments. Creation of virtual environments
* zipapp: zipapp --- Manage executable Python zip archives. Manage executable Python zip archives

@end menu

@node ensurepip --- Bootstrapping the pip installer,venv --- Creation of virtual environments,,Paquets et distribution de paquets logiciels
@anchor{library/ensurepip doc}@anchor{424b}@anchor{library/ensurepip ensurepip-bootstrapping-the-pip-installer}@anchor{424c}@anchor{library/ensurepip module-ensurepip}@anchor{54}
@subsection @code{ensurepip} --- Bootstrapping the @code{pip} installer


@geindex module; ensurepip


Ajouté dans la version 3.4.


`Source code:' Lib/ensurepip@footnote{https://github.com/python/cpython/tree/3.13/Lib/ensurepip}


__________________________________________________________________


Le module @ref{54,,ensurepip} met en place l'installateur @code{pip} dans un environnement Python, classique ou virtuel. Ce principe d'amorçage a été choisi car @code{pip} est un projet séparé de Python avec son propre cycle de versions. Il permet en particulier d'embarquer la version la plus récente de @code{pip} dans les mises à jour de maintenance de l'interpréteur CPython comme dans les nouvelles versions principales.

Dans la plupart des cas, il n'est pas nécessaire de recourir à ce module. @code{pip} est le plus souvent déjà installé pour vous. Cependant, @code{ensurepip} peut s'avérer utile si l'installation de @code{pip} a été sautée au moment de l'installation de Python (ou en créant un environnement virtuel), ou bien si @code{pip} a été désinstallé par l'utilisateur.

@cartouche
@quotation Note 
Ce module n'accède `pas' au réseau. Tout ce qu'il faut pour amorcer @code{pip} est compris dans le paquet.
@end quotation
@end cartouche


@subsubheading Voir aussi



@table @asis

@item @ref{ee0,,Installation de modules Python}

Guide de l'utilisateur final pour installer des paquets Python

@geindex Python Enhancement Proposals; PEP 453

@item PEP 453@footnote{https://peps.python.org/pep-0453/} : Amorçage explicite de pip dans les installations de Python

Les motivations pour l'ajout de ce module et sa spécification d'origine
@end table


@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@menu
* Interface en ligne de commande: Interface en ligne de commande<7>. 
* API du module:: 

@end menu

@node Interface en ligne de commande<7>,API du module,,ensurepip --- Bootstrapping the pip installer
@anchor{library/ensurepip command-line-interface}@anchor{424d}
@subsubsection Interface en ligne de commande


On fait appel à l'interface en ligne de commande à l'aide de l'option @code{-m} de l'interpréteur.

L'invocation la plus simple est :

@example
python -m ensurepip
@end example

Cette commande installe @code{pip} s'il n'est pas déjà présent. Sinon, elle ne fait rien. Pour s'assurer que la version de @code{pip} est au moins aussi récente que celle embarquée dans @code{ensurepip}, passer l'option @code{--upgrade} :

@example
python -m ensurepip --upgrade
@end example

@code{pip} est installé par défaut dans l'environnement virtuel courant, s'il y en a un, ou bien dans le dossier @code{site-packages} du système. L'emplacement d'installation se règle à travers deux options :


@itemize *

@item 
@code{--root @var{dir}}: Installs @code{pip} relative to the given root directory
rather than the root of the currently active virtual environment (if any)
or the default root for the current Python installation.

@item 
@code{--user} : installe @code{pip} dans le dossier @code{site-packages} propre à l'utilisateur au lieu du dossier global de l'installation de Python. Cette option n'est pas valide dans un environnement virtuel.
@end itemize

Par défaut, les commandes @code{pipX} et @code{pipX.Y} sont créées (où X.Y est la version de Python avec laquelle @code{ensurepip} est utilisé). Cela se contrôle par deux options supplémentaires :


@itemize *

@item 
@code{--altinstall} : dans ce mode d'« installation parallèle », seule la commande @code{pipX.Y} est ajoutée, et pas la commande @code{pipX}.

@item 
@code{--default-pip} : ce mode d'« installation de la version par défaut » crée la commande @code{pip} en plus de @code{pipX} et @code{pipX.Y}.
@end itemize

Combiner ces deux options conduit à une exception.

@node API du module,,Interface en ligne de commande<7>,ensurepip --- Bootstrapping the pip installer
@anchor{library/ensurepip module-api}@anchor{424e}
@subsubsection API du module


Le module @ref{54,,ensurepip} définit deux fonctions pour utilisation dans les programmes :

@geindex version() (dans le module ensurepip)
@anchor{library/ensurepip ensurepip version}@anchor{424f}
@deffn {Fonction} ensurepip.version ()

Renvoie, sous forme de chaîne, la version de @code{pip} qui serait installée par @code{ensurepip}.
@end deffn

@geindex bootstrap() (dans le module ensurepip)
@anchor{library/ensurepip ensurepip bootstrap}@anchor{4115}
@deffn {Fonction} ensurepip.bootstrap (root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

Amorce @code{pip} dans l'environnement courant ou un environnement spécifique.

Passer `root' permet de changer la racine du chemin d'installation. Si `root' vaut @code{None} (la valeur par défaut), l'installation se fait dans la racine par défaut pour l'environnement courant.

`upgrade' indique s'il faut ou non effectuer la mise à jour d'une éventuelle version plus ancienne de @code{pip} déjà installée vers la version embarquée dans @code{ensurepip}.

Si `user' vaut vrai, @code{pip} est mis dans des chemins qui le rendent disponible pour cet utilisateur uniquement, et non pour tous les utilisateurs de l'installation de Python.

Par défaut, les commandes créées sont @code{pipX} et @code{pipX.Y} (où X.Y est la version de Python).

Si `altinstall' vaut vrai, @code{pipX} n'est pas créée.

Si `default_pip' vaut vrai, la commande @code{pip} est créée en plus des deux autres.

Le fait de combiner `altinstall' et `default_pip' lève l'exception @ref{1ff,,ValueError}.

`verbosity' règle le niveau de verbosité des messages émis sur @ref{ac4,,sys.stdout} pendant l'amorçage.

Cette fonction lève un @ref{1848,,événement d'audit} @code{ensurepip.bootstrap} avec l'argument @code{root}.

@cartouche
@quotation Note 
Le processus d'amorçage a des effets de bord sur @code{sys.path} et @code{os.environ}. Pour les éviter, on peut appeler l'interface en ligne de commande dans un sous-processus.
@end quotation
@end cartouche

@cartouche
@quotation Note 
L'amorçage peut installer des modules supplémentaires qui sont requis pour @code{pip}. Les autres programmes ne doivent pas prendre pour acquise la présence de ces modules, car @code{pip} pourrait dans une version future se passer de ces dépendances.
@end quotation
@end cartouche
@end deffn

@node venv --- Creation of virtual environments,zipapp --- Manage executable Python zip archives,ensurepip --- Bootstrapping the pip installer,Paquets et distribution de paquets logiciels
@anchor{library/venv doc}@anchor{4250}@anchor{library/venv module-venv}@anchor{110}@anchor{library/venv venv-creation-of-virtual-environments}@anchor{4251}
@subsection @code{venv} --- Creation of virtual environments


@geindex module; venv


Ajouté dans la version 3.3.


`Code source :' Lib/venv/@footnote{https://github.com/python/cpython/tree/3.13/Lib/venv/}

@geindex Environments;virtual


__________________________________________________________________

@anchor{library/venv venv-def}@anchor{4252}@anchor{library/venv venv-intro}@anchor{4253}
The @code{venv} module supports creating lightweight "virtual environments",
each with their own independent set of Python packages installed in
their @ref{c6,,site} directories.
A virtual environment is created on top of an existing
Python installation, known as the virtual environment's "base" Python, and may
optionally be isolated from the packages in the base environment,
so only those explicitly installed in the virtual environment are available.

When used from within a virtual environment, common installation tools such as
pip@footnote{https://pypi.org/project/pip/} will install Python packages into a virtual environment
without needing to be told to do so explicitly.

A virtual environment is (amongst other things):


@itemize *

@item 
Used to contain a specific Python interpreter and software libraries and
binaries which are needed to support a project (library or application). These
are by default isolated from software in other virtual environments and Python
interpreters and libraries installed in the operating system.

@item 
Contained in a directory, conventionally named @code{.venv} or @code{venv} in
the project directory, or under a container directory for lots of virtual
environments, such as @code{~/.virtualenvs}.

@item 
Not checked into source control systems such as Git.

@item 
Considered as disposable -- it should be simple to delete and recreate it from
scratch. You don't place any project code in the environment.

@item 
Not considered as movable or copyable -- you just recreate the same
environment in the target location.
@end itemize

See 
@geindex Python Enhancement Proposals; PEP 405
PEP 405@footnote{https://peps.python.org/pep-0405/} for more background on Python virtual environments.


@subsubheading Voir aussi


Python Packaging User Guide: Creating and using virtual environments@footnote{https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments}


@c include for modules that don't work on WASM or mobile platforms

@ref{1ce0,,Availability}: not Android, not iOS, not WASI.

This module is not supported on @ref{1ddf,,mobile platforms}
or @ref{176f,,WebAssembly platforms}.

@menu
* Création d'environnements virtuels: Création d'environnements virtuels<2>. 
* How venvs work:: 
* API: API<2>. 
* Un exemple d'extension de EnvBuilder:: 

@end menu

@node Création d'environnements virtuels<2>,How venvs work,,venv --- Creation of virtual environments
@anchor{library/venv creating-virtual-environments}@anchor{4254}
@subsubsection Création d'environnements virtuels


@ref{4252,,Virtual environments} are created by executing the @code{venv}
module:

@example
python -m venv /path/to/new/virtual/environment
@end example

This creates the target directory (including parent directories as needed)
and places a @code{pyvenv.cfg} file in it with a @code{home} key
pointing to the Python installation from which the command was run.
It also creates a @code{bin} (or @code{Scripts} on Windows) subdirectory
containing a copy or symlink of the Python executable
(as appropriate for the platform or arguments used at environment creation time).
It also creates a @code{lib/pythonX.Y/site-packages} subdirectory
(on Windows, this is @code{Libsite-packages}).
If an existing directory is specified, it will be re-used.


Modifié dans la version 3.5: L'utilisation de @code{venv} est maintenant recommandée pour créer vos environnements virtuels.



Deprecated since version 3.6, removed in version 3.8: @code{pyvenv} was the recommended tool for creating virtual environments
for Python 3.3 and 3.4, and replaced in 3.5 by executing @code{venv} directly.


On Windows, invoke the @code{venv} command as follows:

@example
PS> python -m venv C:\path\to\new\virtual\environment
@end example

La commande, si lancée avec @code{-h}, montrera les options disponibles :

@example
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            [--without-scm-ignore-files]
            ENV_DIR [ENV_DIR ...]

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.
@end example


Modifié dans la version 3.4: Installs pip by default, added the @code{--without-pip}  and @code{--copies}
options.



Modifié dans la version 3.4: Dans les versions précédentes, si le dossier de destination existait déjà, une erreur était levée, sauf si l'option @code{--clear} ou @code{--upgrade} était incluse.



Modifié dans la version 3.9: Add @code{--upgrade-deps} option to upgrade pip + setuptools to the latest on PyPI.



Modifié dans la version 3.12: @code{setuptools} is no longer a core venv dependency.



Modifié dans la version 3.13: Added the @code{--without-scm-ignore-files} option.



Modifié dans la version 3.13: @code{venv} now creates a @code{.gitignore} file for Git by default.


@cartouche
@quotation Note 
Bien que les liens symboliques soient pris en charge sous Windows, ils ne sont pas recommandés. Il est particulièrement à noter que le double-clic sur @code{python.exe} dans l'Explorateur de fichiers suivra le lien symbolique et ignorera l'environnement virtuel.
@end quotation
@end cartouche

@cartouche
@quotation Note 
On Microsoft Windows, it may be required to enable the @code{Activate.ps1}
script by setting the execution policy for the user. You can do this by
issuing the following PowerShell command:

@example
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
@end example

See About Execution Policies@footnote{https://go.microsoft.com/fwlink/?LinkID=135170}
for more information.
@end quotation
@end cartouche

The created @code{pyvenv.cfg} file also includes the
@code{include-system-site-packages} key, set to @code{true} if @code{venv} is
run with the @code{--system-site-packages} option, @code{false} otherwise.

Sauf si l'option @code{--without-pip} est incluse, @ref{54,,ensurepip} sera invoqué pour amorcer @code{pip} dans l'environnement virtuel.

Plusieurs chemins peuvent être donnés à @code{venv}, et dans ce cas un environnement virtuel sera créé, en fonction des options incluses, à chaque chemin donné.

@node How venvs work,API<2>,Création d'environnements virtuels<2>,venv --- Creation of virtual environments
@anchor{library/venv how-venvs-work}@anchor{4255}@anchor{library/venv venv-explanation}@anchor{436}
@subsubsection How venvs work


When a Python interpreter is running from a virtual environment,
@ref{3ad,,sys.prefix} and @ref{3a9,,sys.exec_prefix}
point to the directories of the virtual environment,
whereas @ref{3e6,,sys.base_prefix} and @ref{3e5,,sys.base_exec_prefix}
point to those of the base Python used to create the environment.
It is sufficient to check
@code{sys.prefix != sys.base_prefix} to determine if the current interpreter is
running from a virtual environment.

A virtual environment may be "activated" using a script in its binary directory
(@code{bin} on POSIX; @code{Scripts} on Windows).
This will prepend that directory to your 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}, so that running
@code{python} will invoke the environment's Python interpreter
and you can run installed scripts without having to use their full path.
The invocation of the activation script is platform-specific
(@code{@var{<venv>}} must be replaced by the path to the directory
containing the virtual environment):


@multitable {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Plateforme

@tab

Invite de commande

@tab

Commande pour activer l'environnement virtuel

@item

POSIX

@tab

bash/zsh

@tab

@code{$ source @var{<venv>}/bin/activate}

@item

fish

@tab

@code{$ source @var{<venv>}/bin/activate.fish}

@item

csh/tcsh

@tab

@code{$ source @var{<venv>}/bin/activate.csh}

@item

pwsh

@tab

@code{$ @var{<venv>}/bin/Activate.ps1}

@item

Windows

@tab

cmd.exe

@tab

@code{C:\> @var{<venv>}\Scripts\activate.bat}

@item

PowerShell

@tab

@code{PS C:\> @var{<venv>}\Scripts\Activate.ps1}

@end multitable



Ajouté dans la version 3.4: @code{fish} and @code{csh} activation scripts.



Ajouté dans la version 3.8: Scripts d'activation PowerShell installés sous POSIX pour le support de PowerShell Core.


You don't specifically `need' to activate a virtual environment,
as you can just specify the full path to that environment's
Python interpreter when invoking Python.
Furthermore, all scripts installed in the environment
should be runnable without activating it.

In order to achieve this, scripts installed into virtual environments have
a "shebang" line which points to the environment's Python interpreter,
@code{#!/@var{<path-to-venv>}/bin/python}.
This means that the script will run with that interpreter regardless of the
value of 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}. On Windows, "shebang" line processing is supported if
you have the @ref{5a8,,Lanceur Python pour Windows} installed. Thus, double-clicking an installed
script in a Windows Explorer window should run it with the correct interpreter
without the environment needing to be activated or on the 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}.

When a virtual environment has been activated, the @code{VIRTUAL_ENV}
environment variable is set to the path of the environment.
Since explicitly activating a virtual environment is not required to use it,
@code{VIRTUAL_ENV} cannot be relied upon to determine
whether a virtual environment is being used.

@cartouche
@quotation Avertissement 
Because scripts installed in environments should not expect the
environment to be activated, their shebang lines contain the absolute paths
to their environment's interpreters. Because of this, environments are
inherently non-portable, in the general case. You should always have a
simple means of recreating an environment (for example, if you have a
requirements file @code{requirements.txt}, you can invoke @code{pip install -r
requirements.txt} using the environment's @code{pip} to install all of the
packages needed by the environment). If for any reason you need to move the
environment to a new location, you should recreate it at the desired
location and delete the one at the old location. If you move an environment
because you moved a parent directory of it, you should recreate the
environment in its new location. Otherwise, software installed into the
environment may not work as expected.
@end quotation
@end cartouche

You can deactivate a virtual environment by typing @code{deactivate} in your shell.
The exact mechanism is platform-specific and is an internal implementation
detail (typically, a script or shell function will be used).

@node API<2>,Un exemple d'extension de EnvBuilder,How venvs work,venv --- Creation of virtual environments
@anchor{library/venv api}@anchor{4256}@anchor{library/venv venv-api}@anchor{edd}
@subsubsection API


La méthode haut niveau décrite au dessus utilise une API simple qui permet à des créateurs d'environnements virtuels externes de personnaliser la création d'environnements virtuels basés sur leurs besoins, la classe @ref{267,,EnvBuilder}.

@geindex EnvBuilder (classe dans venv)
@anchor{library/venv venv EnvBuilder}@anchor{267}
@deffn {Classe} venv.EnvBuilder (system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())

La classe @ref{267,,EnvBuilder} accepte les arguments suivants lors de l'instanciation :


@itemize *

@item 
`system_site_packages' -- a boolean value indicating that the system Python
site-packages should be available to the environment (defaults to @code{False}).

@item 
`clear' -- a boolean value which, if true, will delete the contents of
any existing target directory, before creating the environment.

@item 
`symlinks' -- a boolean value indicating whether to attempt to symlink the
Python binary rather than copying.

@item 
`upgrade' -- a boolean value which, if true, will upgrade an existing
environment with the running Python - for use when that Python has been
upgraded in-place (defaults to @code{False}).

@item 
`with_pip' -- a boolean value which, if true, ensures pip is
installed in the virtual environment. This uses @ref{54,,ensurepip} with
the @code{--default-pip} option.

@item 
`prompt' -- a string to be used after virtual environment is activated
(defaults to @code{None} which means directory name of the environment would
be used). If the special string @code{"."} is provided, the basename of the
current directory is used as the prompt.

@item 
`upgrade_deps' -- Update the base venv modules to the latest on PyPI

@item 
`scm_ignore_files' -- Create ignore files based for the specified source
control managers (SCM) in the iterable. Support is defined by having a
method named @code{create_@{scm@}_ignore_file}. The only value supported by
default is @code{"git"} via @ref{4257,,create_git_ignore_file()}.
@end itemize


Modifié dans la version 3.4: Ajout du paramètre @code{with_pip}



Modifié dans la version 3.6: Ajout du paramètre @code{prompt}



Modifié dans la version 3.9: Added the @code{upgrade_deps} parameter



Modifié dans la version 3.13: Added the @code{scm_ignore_files} parameter


@ref{267,,EnvBuilder} may be used as a base class.

@geindex create() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder create}@anchor{4258}
@deffn {Méthode} create (env_dir)

Crée un environnement virtuel en spécifiant le chemin cible (absolu ou relatif par rapport au dossier courant) qui contiendra l'environnement virtuel. La méthode @code{create} crée l'environnement dans le dossier spécifié ou lève une exception appropriée.

La méthode @code{create} de la classe @ref{267,,EnvBuilder} illustre les points d'entrées disponibles pour la personnalisation de sous-classes :

@example
def create(self, env_dir):
    """
    Create a virtualized Python environment in a directory.
    env_dir is the target directory to create an environment in.
    """
    env_dir = os.path.abspath(env_dir)
    context = self.ensure_directories(env_dir)
    self.create_configuration(context)
    self.setup_python(context)
    self.setup_scripts(context)
    self.post_setup(context)
@end example

Chacune des méthodes @ref{4259,,ensure_directories()}, @ref{425a,,create_configuration()}, @ref{425b,,setup_python()}, @ref{425c,,setup_scripts()} et @ref{425d,,post_setup()} peuvent être écrasés.
@end deffn

@geindex ensure_directories() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder ensure_directories}@anchor{4259}
@deffn {Méthode} ensure_directories (env_dir)

Creates the environment directory and all necessary subdirectories that
don't already exist, and returns a context object.  This context object
is just a holder for attributes (such as paths) for use by the other
methods.  If the @ref{267,,EnvBuilder} is created with the arg
@code{clear=True}, contents of the environment directory will be cleared
and then all necessary subdirectories will be recreated.

The returned context object is a @ref{1cc,,types.SimpleNamespace} with the
following attributes:


@itemize *

@item 
@code{env_dir} - The location of the virtual environment. Used for
@code{__VENV_DIR__} in activation scripts (see @ref{425e,,install_scripts()}).

@item 
@code{env_name} - The name of the virtual environment. Used for
@code{__VENV_NAME__} in activation scripts (see @ref{425e,,install_scripts()}).

@item 
@code{prompt} - The prompt to be used by the activation scripts. Used for
@code{__VENV_PROMPT__} in activation scripts (see @ref{425e,,install_scripts()}).

@item 
@code{executable} - The underlying Python executable used by the virtual
environment. This takes into account the case where a virtual environment
is created from another virtual environment.

@item 
@code{inc_path} - The include path for the virtual environment.

@item 
@code{lib_path} - The purelib path for the virtual environment.

@item 
@code{bin_path} - The script path for the virtual environment.

@item 
@code{bin_name} - The name of the script path relative to the virtual
environment location. Used for @code{__VENV_BIN_NAME__} in activation
scripts (see @ref{425e,,install_scripts()}).

@item 
@code{env_exe} - The name of the Python interpreter in the virtual
environment. Used for @code{__VENV_PYTHON__} in activation scripts
(see @ref{425e,,install_scripts()}).

@item 
@code{env_exec_cmd} - The name of the Python interpreter, taking into
account filesystem redirections. This can be used to run Python in
the virtual environment.
@end itemize


Modifié dans la version 3.11: The `venv'
@ref{67a,,sysconfig installation scheme}
is used to construct the paths of the created directories.



Modifié dans la version 3.12: The attribute @code{lib_path} was added to the context, and the context
object was documented.

@end deffn

@geindex create_configuration() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder create_configuration}@anchor{425a}
@deffn {Méthode} create_configuration (context)

Crée le fichier de configuration @code{pyvenv.cfg} dans l'environnement.
@end deffn

@geindex setup_python() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder setup_python}@anchor{425b}
@deffn {Méthode} setup_python (context)

Crée une copie ou un lien symbolique vers l'exécutable Python dans l'environnement. Sur les systèmes POSIX, si un exécutable spécifique @code{python3.x} a été utilisé, des liens symboliques vers @code{python} et @code{python3} seront créés pointant vers cet exécutable, sauf si des fichiers avec ces noms existent déjà.
@end deffn

@geindex setup_scripts() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder setup_scripts}@anchor{425c}
@deffn {Méthode} setup_scripts (context)

Installe les scripts d'activation appropriés à la plateforme dans l'environnement virtuel.
@end deffn

@geindex upgrade_dependencies() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder upgrade_dependencies}@anchor{425f}
@deffn {Méthode} upgrade_dependencies (context)

Upgrades the core venv dependency packages (currently pip@footnote{https://pypi.org/project/pip/})
in the environment. This is done by shelling out to the
@code{pip} executable in the environment.


Ajouté dans la version 3.9.



Modifié dans la version 3.12: setuptools@footnote{https://pypi.org/project/setuptools/} is no longer a core venv dependency.

@end deffn

@geindex post_setup() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder post_setup}@anchor{425d}
@deffn {Méthode} post_setup (context)

Une méthode qui n'est la que pour se faire surcharger dans des implémentation externes pour pré installer des paquets dans l'environnement virtuel ou pour exécuter des étapes post-création.
@end deffn

@geindex install_scripts() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder install_scripts}@anchor{425e}
@deffn {Méthode} install_scripts (context, path)

This method can be
called from @ref{425c,,setup_scripts()} or @ref{425d,,post_setup()} in subclasses to
assist in installing custom scripts into the virtual environment.

`path' is the path to a directory that should contain subdirectories
@code{common}, @code{posix}, @code{nt}; each containing scripts destined for the
@code{bin} directory in the environment.  The contents of @code{common} and the
directory corresponding to @ref{2a8a,,os.name} are copied after some text
replacement of placeholders:


@itemize *

@item 
@code{__VENV_DIR__} est remplacé avec le chemin absolu du dossier de l'environnement.

@item 
@code{__VENV_NAME__} est remplacé avec le nom de l'environnement (le dernier segment du chemin vers le dossier de l'environnement).

@item 
@code{__VENV_PROMPT__} est remplacé par le prompt (nom de l'environnement entouré de parenthèses et avec un espace le suivant).

@item 
@code{__VENV_BIN_NAME__} est remplacé par le nom du dossier `bin' (soit @code{bin} soit @code{Scripts}).

@item 
@code{__VENV_PYTHON__} est remplacé avec le chemin absolu de l’exécutable de l'environnement.
@end itemize

Les dossiers peuvent exister (pour quand un environnement existant est mis à jour).
@end deffn

@geindex create_git_ignore_file() (méthode venv.EnvBuilder)
@anchor{library/venv venv EnvBuilder create_git_ignore_file}@anchor{4257}
@deffn {Méthode} create_git_ignore_file (context)

Creates a @code{.gitignore} file within the virtual environment that causes
the entire directory to be ignored by the Git source control manager.


Ajouté dans la version 3.13.

@end deffn


Modifié dans la version 3.7.2: Windows utilise maintenant des scripts de redirection pour @code{python[w].exe} au lieu de copier les fichiers binaires. En 3.7.2 seulement @ref{425b,,setup_python()} ne fait rien sauf s'il s'exécute à partir d'un `build' dans l'arborescence source.



Modifié dans la version 3.7.3: Windows copie les scripts de redirection dans le cadre de @ref{425b,,setup_python()} au lieu de @ref{425c,,setup_scripts()}. Ce n'était pas le cas en 3.7.2. Lorsque vous utilisez des liens symboliques, les exécutables originaux seront liés.

@end deffn

Il y a aussi une fonction pratique au niveau du module :

@geindex create() (dans le module venv)
@anchor{library/venv venv create}@anchor{268}
@deffn {Fonction} venv.create (env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())

Crée une @ref{267,,EnvBuilder} avec les arguments donnés, et appelle sa méthode @ref{4258,,create()} avec l'argument `env_dir'.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: Added the `with_pip' parameter



Modifié dans la version 3.6: Added the `prompt' parameter



Modifié dans la version 3.9: Added the `upgrade_deps' parameter



Modifié dans la version 3.13: Added the `scm_ignore_files' parameter

@end deffn

@node Un exemple d'extension de EnvBuilder,,API<2>,venv --- Creation of virtual environments
@anchor{library/venv an-example-of-extending-envbuilder}@anchor{4260}
@subsubsection Un exemple d'extension de @code{EnvBuilder}


Le script qui suis montre comment étendre @ref{267,,EnvBuilder} en implémentant une sous-classe qui installe `setuptools' et `pip' dans un environnement créé :

@example
import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlparse
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    This builder installs setuptools and pip so that you can pip or
    easy_install other packages into the created virtual environment.

    :param nodist: If true, setuptools and pip are not installed into the
                   created virtual environment.
    :param nopip: If true, pip is not installed into the created
                  virtual environment.
    :param progress: If setuptools or pip are installed, the progress of the
                     installation can be monitored by passing a progress
                     callable. If specified, it is called with two
                     arguments: a string indicating some progress, and a
                     context indicating where the string is coming from.
                     The context argument can have one of three values:
                     'main', indicating that it is called from virtualize()
                     itself, and 'stdout' and 'stderr', which are obtained
                     by reading lines from the output streams of a subprocess
                     which is used to install the app.

                     If a callable is not specified, default progress
                     information is output to sys.stderr.
    """

    def __init__(self, *args, **kwargs):
        self.nodist = kwargs.pop('nodist', False)
        self.nopip = kwargs.pop('nopip', False)
        self.progress = kwargs.pop('progress', None)
        self.verbose = kwargs.pop('verbose', False)
        super().__init__(*args, **kwargs)

    def post_setup(self, context):
        """
        Set up any packages which need to be pre-installed into the
        virtual environment being created.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Can't install pip without setuptools
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Read lines from a subprocess' output stream and either pass to a progress
        callable (if specified) or write progress information to sys.stderr.
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _, _ = urlparse(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # Download script into the virtual environment's binaries folder
        urlretrieve(url, distpath)
        progress = self.progress
        if self.verbose:
            term = '\n'
        else:
            term = '@w{'}
        if progress is not None:
            progress('Installing %s ...%s' % (name, term), 'main')
        else:
            sys.stderr.write('Installing %s ...%s' % (name, term))
            sys.stderr.flush()
        # Install in the virtual environment
        args = [context.env_exe, fn]
        p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
        t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
        t1.start()
        t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
        t2.start()
        p.wait()
        t1.join()
        t2.join()
        if progress is not None:
            progress('done.', 'main')
        else:
            sys.stderr.write('done.\n')
        # Clean up - no longer needed
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Install setuptools in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = "https://bootstrap.pypa.io/ez_setup.py"
        self.install_script(context, 'setuptools', url)
        # clear up the setuptools archive which gets downloaded
        pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
        files = filter(pred, os.listdir(context.bin_path))
        for f in files:
            f = os.path.join(context.bin_path, f)
            os.unlink(f)

    def install_pip(self, context):
        """
        Install pip in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bootstrap.pypa.io/get-pip.py'
        self.install_script(context, 'pip', url)


def main(args=None):
    import argparse

    parser = argparse.ArgumentParser(prog=__name__,
                                     description='Creates virtual Python '
                                                 'environments in one or '
                                                 'more target '
                                                 'directories.')
    parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                        help='A directory in which to create the '
                             'virtual environment.')
    parser.add_argument('--no-setuptools', default=False,
                        action='store_true', dest='nodist',
                        help="Don't install setuptools or pip in the "
                             "virtual environment.")
    parser.add_argument('--no-pip', default=False,
                        action='store_true', dest='nopip',
                        help="Don't install pip in the virtual "
                             "environment.")
    parser.add_argument('--system-site-packages', default=False,
                        action='store_true', dest='system_site',
                        help='Give the virtual environment access to the '
                             'system site-packages dir.')
    if os.name == 'nt':
        use_symlinks = False
    else:
        use_symlinks = True
    parser.add_argument('--symlinks', default=use_symlinks,
                        action='store_true', dest='symlinks',
                        help='Try to use symlinks rather than copies, '
                             'when symlinks are not the default for '
                             'the platform.')
    parser.add_argument('--clear', default=False, action='store_true',
                        dest='clear', help='Delete the contents of the '
                                           'virtual environment '
                                           'directory if it already '
                                           'exists, before virtual '
                                           'environment creation.')
    parser.add_argument('--upgrade', default=False, action='store_true',
                        dest='upgrade', help='Upgrade the virtual '
                                             'environment directory to '
                                             'use this version of '
                                             'Python, assuming Python '
                                             'has been upgraded '
                                             'in-place.')
    parser.add_argument('--verbose', default=False, action='store_true',
                        dest='verbose', help='Display the output '
                                             'from the scripts which '
                                             'install setuptools and pip.')
    options = parser.parse_args(args)
    if options.upgrade and options.clear:
        raise ValueError('you cannot supply --upgrade and --clear together.')
    builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
                                   clear=options.clear,
                                   symlinks=options.symlinks,
                                   upgrade=options.upgrade,
                                   nodist=options.nodist,
                                   nopip=options.nopip,
                                   verbose=options.verbose)
    for d in options.dirs:
        builder.create(d)

if __name__ == '__main__':
    rc = 1
    try:
        main()
        rc = 0
    except Exception as e:
        print('Error: %s' % e, file=sys.stderr)
    sys.exit(rc)
@end example

Ce script est aussi disponible au téléchargement en ligne@footnote{https://gist.github.com/vsajip/4673395}.

@node zipapp --- Manage executable Python zip archives,,venv --- Creation of virtual environments,Paquets et distribution de paquets logiciels
@anchor{library/zipapp doc}@anchor{4261}@anchor{library/zipapp module-zipapp}@anchor{12f}@anchor{library/zipapp zipapp-manage-executable-python-zip-archives}@anchor{4262}
@subsection @code{zipapp} --- Manage executable Python zip archives


@geindex module; zipapp


Ajouté dans la version 3.5.


`Code source :' Lib/zipapp.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/zipapp.py}

@geindex Executable Zip Files


__________________________________________________________________


Ce module fournit des outils pour gérer la création de fichiers zip contenant du code Python, qui peuvent être @ref{1cb5,,exécutés directement par l'interpréteur Python}.  Le module fournit à la fois une interface de ligne de commande @ref{4263,,Interface en ligne de commande} et une interface @ref{4264,,API Python}.

@menu
* Exemple de base:: 
* Interface en ligne de commande: Interface en ligne de commande<8>. 
* API Python:: 
* Exemples: Exemples<31>. 
* Spécification de l'interprète:: 
* Création d'applications autonomes avec zipapp:: 
* Le format d'archive d'application Zip Python:: 

@end menu

@node Exemple de base,Interface en ligne de commande<8>,,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp basic-example}@anchor{4265}
@subsubsection Exemple de base


L'exemple suivant montre comment l'interface de ligne de commande @ref{4263,,Interface en ligne de commande} peut être utilisée pour créer une archive exécutable depuis un répertoire contenant du code Python.  Lors de l'exécution, l'archive exécutera la fonction @code{main} du module @code{myapp} dans l'archive.

@example
$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>
@end example

@node Interface en ligne de commande<8>,API Python,Exemple de base,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp command-line-interface}@anchor{4266}@anchor{library/zipapp zipapp-command-line-interface}@anchor{4263}
@subsubsection Interface en ligne de commande


Lorsqu'il est appelé en tant que programme à partir de la ligne de commande, la syntaxe suivante est utilisée :

@example
$ python -m zipapp source [options]
@end example

Si `source' est un répertoire, une archive est créée à partir du contenu de `source'.  Si `source' est un fichier, ce doit être une archive et il est copié dans l'archive cible (ou le contenu de sa ligne `shebang' est affiché si l'option @code{--info} est indiquée).

Les options suivantes sont disponibles :

@geindex option de ligne de commande zipapp; -o
@geindex option de ligne de commande zipapp; --output
@anchor{library/zipapp cmdoption-zipapp-o}@anchor{4267}@anchor{library/zipapp cmdoption-zipapp-output}@anchor{4268}
@deffn {Option} @w{-}o <output>, @w{-}@w{-}output=<output>

Écrit la sortie dans un fichier nommé `output'.  Si cette option n'est pas spécifiée, le nom du fichier de sortie sera le même que celui de l'entrée `source', avec l'extension @code{.pyz}.  Si un nom de fichier explicite est donné, il est utilisé tel quel (une extension @code{.pyz} doit donc être incluse si nécessaire).

Un nom de fichier de sortie doit être spécifié si la `source' est une archive (et, dans ce cas, la `sortie' ne doit pas être la même que la `source').
@end deffn

@geindex option de ligne de commande zipapp; -p
@geindex option de ligne de commande zipapp; --python
@anchor{library/zipapp cmdoption-zipapp-p}@anchor{4269}@anchor{library/zipapp cmdoption-zipapp-python}@anchor{426a}
@deffn {Option} @w{-}p <interpreter>, @w{-}@w{-}python=<interpreter>

Ajoute une ligne @code{#!} à l'archive en spécifiant `interpreter' comme commande à exécuter.  Aussi, sur un système POSIX, cela rend l'archive exécutable.  Le comportement par défaut est de ne pas écrire la ligne @code{#!} et de ne pas rendre le fichier exécutable.
@end deffn

@geindex option de ligne de commande zipapp; -m
@geindex option de ligne de commande zipapp; --main
@anchor{library/zipapp cmdoption-zipapp-m}@anchor{426b}@anchor{library/zipapp cmdoption-zipapp-main}@anchor{426c}
@deffn {Option} @w{-}m <mainfn>, @w{-}@w{-}main=<mainfn>

Écrit un fichier @code{__main__.py} dans l'archive qui exécute `mainfn'.  L'argument `mainfn' est de la forme « `pkg.mod:fn' », où « `pkg.mod' » est un paquet/module dans l'archive, et « `fn' » est un appelable dans le module donné. Le fichier @code{__main__.py} réalise cet appel.

@ref{426b,,--main} ne peut pas être spécifié lors de la copie d'une archive.
@end deffn

@geindex option de ligne de commande zipapp; -c
@geindex option de ligne de commande zipapp; --compress
@anchor{library/zipapp cmdoption-zipapp-c}@anchor{426d}@anchor{library/zipapp cmdoption-zipapp-compress}@anchor{426e}
@deffn {Option} @w{-}c, @w{-}@w{-}compress

Compresse les fichiers avec la méthode `deflate', réduisant ainsi la taille du fichier de sortie. Par défaut, les fichiers sont stockés non compressés dans l'archive.

@ref{426d,,--compress} n'a aucun effet lors de la copie d'une archive.


Ajouté dans la version 3.7.

@end deffn

@geindex option de ligne de commande zipapp; --info
@anchor{library/zipapp cmdoption-zipapp-info}@anchor{426f}
@deffn {Option} @w{-}@w{-}info

Affiche l'interpréteur intégré dans l'archive, à des fins de diagnostic.  Dans ce cas, toutes les autres options sont ignorées et SOURCE doit être une archive et non un répertoire.
@end deffn

@geindex option de ligne de commande zipapp; -h
@geindex option de ligne de commande zipapp; --help
@anchor{library/zipapp cmdoption-zipapp-h}@anchor{4270}@anchor{library/zipapp cmdoption-zipapp-help}@anchor{4271}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Affiche un court message d'aide et quitte.
@end deffn

@node API Python,Exemples<31>,Interface en ligne de commande<8>,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp python-api}@anchor{4272}@anchor{library/zipapp zipapp-python-api}@anchor{4264}
@subsubsection API Python


Ce module définit deux fonctions utilitaires :

@geindex create_archive() (dans le module zipapp)
@anchor{library/zipapp zipapp create_archive}@anchor{b9e}
@deffn {Fonction} zipapp.create_archive (source, target=None, interpreter=None, main=None, filter=None, compressed=False)

Crée une archive d'application à partir de `source'.  La source peut être de natures suivantes :


@itemize *

@item 
Le nom d'un répertoire, ou un @ref{29d,,path-like object} se référant à un répertoire ; dans ce cas, une nouvelle archive d'application sera créée à partir du contenu de ce répertoire.

@item 
Le nom d'un fichier d'archive d'application existant, ou un @ref{29d,,path-like object} se référant à un tel fichier ; dans ce cas, le fichier est copié sur la cible (en le modifiant pour refléter la valeur donnée à l'argument `interpreter').  Le nom du fichier doit inclure l'extension @code{.pyz}, si nécessaire.

@item 
Un objet fichier ouvert pour la lecture en mode binaire.  Le contenu du fichier doit être une archive d'application et Python suppose que l'objet fichier est positionné au début de l'archive.
@end itemize

L'argument `target' détermine où l'archive résultante sera écrite :


@itemize *

@item 
S'il s'agit d'un nom de fichier, ou d'un @ref{29d,,path-like object}, l'archive sera écrite dans ce fichier.

@item 
S'il s'agit d'un objet fichier ouvert, l'archive sera écrite dans cet objet fichier, qui doit être ouvert pour l'écriture en mode octets.

@item 
Si la cible est omise (ou @code{None}), la source doit être un répertoire et la cible sera un fichier portant le même nom que la source, avec une extension @code{.pyz} ajoutée.
@end itemize

L'argument `interpreter' spécifie le nom de l'interpréteur Python avec lequel l'archive sera exécutée.  Il est écrit dans une ligne `shebang' au début de l'archive.  Sur un système POSIX, cela est interprété par le système d'exploitation et, sur Windows, il sera géré par le lanceur Python.  L'omission de l'`interpreter' n'entraîne pas l'écriture d'une ligne `shebang'.  Si un interpréteur est spécifié et que la cible est un nom de fichier, le bit exécutable du fichier cible sera mis à 1.

L'argument `main' spécifie le nom d'un appelable, utilisé comme programme principal pour l'archive.  Il ne peut être spécifié que si la source est un répertoire et si la source ne contient pas déjà un fichier @code{__main__.py}.  L'argument `main' doit prendre la forme @code{pkg.module:callable} et l'archive sera exécutée en important @code{pkg.module} et en exécutant l'appelable donné sans argument.  Omettre `main' est une erreur si la source est un répertoire et ne contient pas un fichier @code{__main__.py} car, dans ce cas, l'archive résultante ne serait pas exécutable.

L'argument optionnel `filter' spécifie une fonction de rappel à laquelle on passe un objet `Path' représentant le chemin du fichier à ajouter (par rapport au répertoire source).  Elle doit renvoyer @code{True} si le fichier doit effectivement être ajouté.

L'argument optionnel `compressed' détermine si les fichiers doivent être compressés.  S'il vaut @code{True}, les fichiers de l'archive sont compressés avec l'algorithme `deflate' ; sinon, les fichiers sont stockés non compressés. Cet argument n'a aucun effet lors de la copie d'une archive existante.

Si un objet fichier est spécifié pour `source' ou `target', il est de la responsabilité de l'appelant de le fermer après avoir appelé @code{create_archive}.

Lors de la copie d'une archive existante, les objets fichier fournis n'ont besoin que des méthodes @code{read} et @code{readline} ou @code{write}.  Lors de la création d'une archive à partir d'un répertoire, si la cible est un objet fichier, elle sera passée à la classe @code{zipfile.ZipFile} et devra fournir les méthodes nécessaires à cette classe.


Modifié dans la version 3.7: Added the `filter' and `compressed' parameters.

@end deffn

@geindex get_interpreter() (dans le module zipapp)
@anchor{library/zipapp zipapp get_interpreter}@anchor{4273}
@deffn {Fonction} zipapp.get_interpreter (archive)

Renvoie l'interpréteur spécifié dans la ligne @code{#!} au début de l'archive.  S'il n'y a pas de ligne @code{#!}, renvoie @ref{660,,None}. L'argument `archive' peut être un nom de fichier ou un objet de type fichier ouvert à la lecture en mode binaire. Python suppose qu'il est au début de l'archive.
@end deffn

@node Exemples<31>,Spécification de l'interprète,API Python,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp examples}@anchor{4274}@anchor{library/zipapp zipapp-examples}@anchor{4275}
@subsubsection Exemples


Regroupe le contenu d'un répertoire dans une archive, puis l'exécute.

@example
$ python -m zipapp myapp
$ python myapp.pyz
<output from myapp>
@end example

La même chose peut être faite en utilisant la fonction @ref{b9e,,create_archive()} :

@example
>>> import zipapp
>>> zipapp.create_archive('myapp', 'myapp.pyz')
@end example

Pour rendre l'application directement exécutable sur un système POSIX, spécifiez un interpréteur à utiliser.

@example
$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>
@end example

Pour remplacer la ligne `shebang' sur une archive existante, créez une archive modifiée en utilisant la fonction @ref{b9e,,create_archive()} :

@example
>>> import zipapp
>>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')
@end example

To update the file in place, do the replacement in memory using a @ref{e8d,,BytesIO}
object, and then overwrite the source afterwards.  Note that there is a risk
when overwriting a file in place that an error will result in the loss of
the original file.  This code does not protect against such errors, but
production code should do so.  Also, this method will only work if the archive
fits in memory:

@example
>>> import zipapp
>>> import io
>>> temp = io.BytesIO()
>>> zipapp.create_archive('myapp.pyz', temp, '/usr/bin/python2')
>>> with open('myapp.pyz', 'wb') as f:
>>>     f.write(temp.getvalue())
@end example

@node Spécification de l'interprète,Création d'applications autonomes avec zipapp,Exemples<31>,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp specifying-the-interpreter}@anchor{4276}@anchor{library/zipapp zipapp-specifying-the-interpreter}@anchor{4277}
@subsubsection Spécification de l'interprète


Notez que si vous spécifiez un interpréteur et que vous distribuez ensuite votre archive d'application, vous devez vous assurer que l'interpréteur utilisé est portable.  Le lanceur Python pour Windows gère la plupart des formes courantes de la ligne POSIX @code{#!}, mais il y a d'autres problèmes à considérer :


@itemize *

@item 
Si vous utilisez @code{/usr/bin/env python} (ou d'autres formes de la commande `python', comme @code{/usr/bin/python}), vous devez considérer que vos utilisateurs peuvent avoir Python 2 ou Python 3 par défaut, et écrire votre code pour fonctionner dans les deux versions.

@item 
Si vous utilisez une version explicite, par exemple @code{/usr/bin/env python3} votre application ne fonctionnera pas pour les utilisateurs qui n'ont pas cette version.  (C'est peut-être ce que vous voulez si vous n'avez pas rendu votre code compatible Python 2).

@item 
Il n'y a aucun moyen de dire « python X.Y ou supérieur » donc faites attention si vous utilisez une version exacte comme @code{/usr/bin/env python3.4} car vous devrez changer votre ligne `shebang' pour les utilisateurs de Python 3.5, par exemple.
@end itemize

Normalement, vous devriez utiliser un @code{/usr/bin/env python2} ou @code{/usr/bin/env python3}, selon que votre code soit écrit pour Python 2 ou 3.

@node Création d'applications autonomes avec zipapp,Le format d'archive d'application Zip Python,Spécification de l'interprète,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp creating-standalone-applications-with-zipapp}@anchor{4278}
@subsubsection Création d'applications autonomes avec `zipapp'


En utilisant le module @ref{12f,,zipapp}, il est possible de créer  des programmes Python qui peuvent être distribués à des utilisateurs finaux dont le seul pré-requis est d'avoir la bonne version de Python installée sur leur ordinateur. Pour y arriver, la clé est de regrouper toutes les dépendances de l'application dans l'archive avec le code source de l'application.

Les étapes pour créer une archive autonome sont les suivantes :


@enumerate 

@item 
Créez votre application dans un répertoire comme d'habitude, de manière à avoir un répertoire @code{myapp} contenant un fichier @code{__main__.py} et tout le code de l'application correspondante.

@item 
Installez toutes les dépendances de votre application dans le répertoire @code{myapp} en utilisant `pip' :

@example
$ python -m pip install -r requirements.txt --target myapp
@end example

(ceci suppose que vous ayez vos dépendances de projet dans un fichier @code{requirements.txt} — sinon vous pouvez simplement lister les dépendances manuellement sur la ligne de commande `pip').

@item 
Regroupez le tout à l'aide de :

@example
$ python -m zipapp -p "interpreter" myapp
@end example
@end enumerate

Cela produira un exécutable autonome qui peut être exécuté sur n'importe quelle machine avec l'interpréteur approprié disponible. Voir @ref{4277,,Spécification de l'interprète} pour plus de détails. Il peut être envoyé aux utilisateurs sous la forme d'un seul fichier.

Sous Unix, le fichier @code{myapp.pyz} est exécutable tel quel.  Vous pouvez renommer le fichier pour supprimer l'extension @code{.pyz} si vous préférez un nom de commande « simple ».  Sous Windows, le fichier @code{myapp.pyz[w]} est exécutable en vertu du fait que l'interpréteur Python est associé aux extensions de fichier @code{.pyz} et @code{.pyzw} une fois installé.

@menu
* Mises en garde:: 

@end menu

@node Mises en garde,,,Création d'applications autonomes avec zipapp
@anchor{library/zipapp caveats}@anchor{4279}
@subsubsection Mises en garde


Si votre application dépend d'un paquet qui inclut une extension C, ce paquet ne peut pas être exécuté à partir d'un fichier zip (c'est une limitation du système d'exploitation, car le code exécutable doit être présent dans le système de fichiers pour que le lanceur de l'OS puisse le charger). Dans ce cas, vous pouvez exclure cette dépendance du fichier zip et, soit demander à vos utilisateurs de l'installer, soit la fournir avec votre fichier zip et ajouter du code à votre fichier @code{__main__.py} pour inclure le répertoire contenant le module décompressé dans @code{sys.path}. Dans ce cas, vous devrez vous assurer d'envoyer les binaires appropriés pour votre ou vos architecture(s) cible(s) (et éventuellement choisir la bonne version à ajouter à @code{sys.path} au moment de l'exécution, basée sur la machine de l'utilisateur).

@node Le format d'archive d'application Zip Python,,Création d'applications autonomes avec zipapp,zipapp --- Manage executable Python zip archives
@anchor{library/zipapp the-python-zip-application-archive-format}@anchor{427a}
@subsubsection Le format d'archive d'application Zip Python


Python est capable d'exécuter des fichiers zip qui contiennent un fichier @code{__main__.py} depuis la version 2.6.  Pour être exécutée par Python, une archive d'application doit simplement être un fichier zip standard contenant un fichier @code{__main__.py} qui sera exécuté comme point d'entrée de l'application.  Comme d'habitude pour tout script Python, le parent du script (dans ce cas le fichier zip) sera placé sur @ref{3ab,,sys.path} et ainsi d'autres modules pourront être importés depuis le fichier zip.

Le format de fichier zip permet d'ajouter des données arbitraires à un fichier zip.  Le format de l'application zip utilise cette possibilité pour préfixer une ligne `shebang' POSIX standard dans le fichier (@code{#!/path/to/interpreter}).

Formellement, le format d'application zip de Python est donc :


@enumerate 

@item 
An optional shebang line, containing the characters @code{b'#!'} followed by an
interpreter name, and then a newline (@code{b'\n'}) character.  The interpreter
name can be anything acceptable to the OS "shebang" processing, or the Python
launcher on Windows.  The interpreter should be encoded in UTF-8 on Windows,
and in @ref{c47,,sys.getfilesystemencoding()} on POSIX.

@item 
Des données `zipfile' standards, telles que générées par le module @ref{130,,zipfile}.  Le contenu du fichier zip `doit' inclure un fichier appelé @code{__main__.py} (qui doit se trouver à la racine du fichier zip — c'est-à-dire qu'il ne peut se trouver dans un sous-répertoire).  Les données du fichier zip peuvent être compressées ou non.
@end enumerate

Si une archive d'application a une ligne `shebang', elle peut avoir le bit exécutable activé sur les systèmes POSIX, pour lui permettre d'être exécutée directement.

Vous pouvez créer des archives d'applications sans utiliser les outils de ce module — le module existe pour faciliter les choses, mais les archives, créées par n'importe quel moyen tout en respectant le format ci-dessus, sont valides pour Python.

@node Environnement d'exécution Python,Interpréteurs Python personnalisés,Paquets et distribution de paquets logiciels,La bibliothèque standard
@anchor{library/python doc}@anchor{427b}@anchor{library/python python}@anchor{427c}@anchor{library/python python-runtime-services}@anchor{427d}
@section Environnement d'exécution Python


Les modules décrits dans ce chapitre fournissent une large collection de services relatifs à l'interpréteur Python et son interaction avec son environnement. En voici un survol :

@menu
* sys: sys --- System-specific parameters and functions. System-specific parameters and functions
* sys.monitoring: sys monitoring --- Execution event monitoring. Execution event monitoring
* sysconfig: sysconfig --- Provide access to Python's configuration information. Provide access to Python's configuration information
* builtins: builtins --- Built-in objects. Built-in objects
* __main__: __main__ --- Top-level code environment. Top-level code environment
* warnings: warnings --- Warning control. Warning control
* dataclasses: dataclasses --- Data Classes. Data Classes
* contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with:: 
* abc: abc --- Abstract Base Classes. Abstract Base Classes
* atexit: atexit --- Exit handlers. Exit handlers
* traceback: traceback --- Print or retrieve a stack traceback. Print or retrieve a stack traceback
* __future__: __future__ --- Future statement definitions. Future statement definitions
* gc: gc --- Garbage Collector interface. Garbage Collector interface
* inspect: inspect --- Inspect live objects. Inspect live objects
* site: site --- Site-specific configuration hook. Site-specific configuration hook

@end menu

@node sys --- System-specific parameters and functions,sys monitoring --- Execution event monitoring,,Environnement d'exécution Python
@anchor{library/sys doc}@anchor{427e}@anchor{library/sys module-sys}@anchor{d8}@anchor{library/sys sys-system-specific-parameters-and-functions}@anchor{427f}
@subsection @code{sys} --- System-specific parameters and functions


@geindex module; sys


__________________________________________________________________


Ce module fournit un accès à certaines variables utilisées et maintenues par l'interpréteur, et à des fonctions interagissant fortement avec ce dernier. Ce module est toujours disponible.

@geindex abiflags (dans le module sys)
@anchor{library/sys sys abiflags}@anchor{a52}
@deffn {Données} sys.abiflags

Contient, sur les systèmes POSIX où Python a été compilé avec le script @code{configure}, les `ABI flags' tels que définis par la 
@geindex Python Enhancement Proposals; PEP 3149
PEP 3149@footnote{https://peps.python.org/pep-3149/}.


Ajouté dans la version 3.2.



Modifié dans la version 3.8: Les options par défaut sont devenues des chaines de caractères vides (l'option @code{m} pour `pymalloc' a été enlevée).


@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex addaudithook() (dans le module sys)
@anchor{library/sys sys addaudithook}@anchor{410c}
@deffn {Fonction} sys.addaudithook (hook)

Append the callable `hook' to the list of active auditing hooks for the
current (sub)interpreter.

Quand un événement d'audit est déclenché par la fonction @ref{153f,,sys.audit()}, chaque point d'entrée est appelé dans l'ordre dans lequel il a été ajouté avec le nom de l'événement et le `n'-uplet des arguments. Les points d'entrées qui sont ajoutés par @ref{410d,,PySys_AddAuditHook()} sont appelés les premiers, suivi par les fonctions de rappel ajoutées dans l'interpréteur en cours d'exécution. Les points d'entrées peuvent `logger' l'événement, lever une exception pour stopper l'opération ou terminer le processus entièrement.

Note that audit hooks are primarily for collecting information about internal
or otherwise unobservable actions, whether by Python or libraries written in
Python. They are not suitable for implementing a "sandbox". In particular,
malicious code can trivially disable or bypass hooks added using this
function. At a minimum, any security-sensitive hooks must be added using the
C API @ref{410d,,PySys_AddAuditHook()} before initialising the runtime, and any
modules allowing arbitrary memory modification (such as @ref{2a,,ctypes}) should
be completely removed or closely monitored.

L'appel de @ref{410c,,sys.addaudithook()} lèvera d'elle même un événement d'audit appelé @code{sys.addaudithook} sans arguments. Si n'importe quel `hook' lève une exception dérivée de @ref{193,,RuntimeError}, le nouveau point d'entrée ne sera pas ajouté et l'exception supprimée. Par conséquent, les appels ne peuvent pas supposer que leurs points d'entrées ont été ajoutés à moins de contrôler tous les points d'entrées existants.

Voir la @ref{17fe,,table d'évenements d'audit} pour tous les événements levés par CPython et 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/} pour la discussion originale de ce design.


Ajouté dans la version 3.8.



Modifié dans la version 3.8.1: Les exceptions dérivées de @ref{9c7,,Exception} mais pas @ref{193,,RuntimeError} ne sont plus supprimées.


`Particularité de l'implémentation CPython :' Quand le traçage est activé (voir @ref{14b6,,settrace()}), les `hooks' Python ne sont tracés que si la fonction a un membre @code{__cantrace__} dont la valeur est vraie. Autrement, les fonctions de traçage ignorent le `hook'.
@end deffn

@geindex argv (dans le module sys)
@anchor{library/sys sys argv}@anchor{1243}
@deffn {Données} sys.argv

La liste des arguments de la ligne de commande passés à un script Python. @code{argv[0]} est le nom du script (chemin complet, ou non, en fonction du système d'exploitation). Si la commande a été exécutée avec l'option @ref{5ca,,-c} de l'interpréteur, @code{argv[0]} vaut la chaîne @code{'-c'}. Si aucun nom de script n'a été donné à l'interpréteur Python, @code{argv[0]} sera une chaîne vide.

Pour boucler sur l'entrée standard, ou la liste des fichiers donnés sur la ligne de commande, utilisez le module @ref{5a,,fileinput}.

See also @ref{82a,,sys.orig_argv}.

@cartouche
@quotation Note 
Sous Unix, les arguments de ligne de commande sont passés par des octets depuis le système d'exploitation. Python les décode en utilisant l’encodage du système de fichiers et le gestionnaire d’erreur `surrogateescape'. Quand vous avez besoin des octets originaux, vous pouvez les récupérer avec @code{[os.fsencode(arg) for arg in sys.argv]}.
@end quotation
@end cartouche
@end deffn

@geindex audit() (dans le module sys)
@anchor{library/sys auditing}@anchor{1848}@anchor{library/sys sys audit}@anchor{153f}
@deffn {Fonction} sys.audit (event, *args)

@geindex auditing

Déclenche un événement d'audit pour tous les points d'entrées d'audit actifs. `event' est une chaîne de caractères identifiant l'événement, et `args' peut contenir des arguments optionnels avec plus d'informations sur l'événement en question. Le nombre et types d'arguments pour un événement donné sont considérés comme une API publique et stable, et ne devraient pas être modifiés entre les versions.

Par exemple, un événement d'audit est nommé @code{os.chdir}. Cet événement à un argument appelé `path' qui contiendras le nouveau répertoire de travail.

@ref{153f,,sys.audit()} appellera les point d'entrées (`hooks' en anglais) d'audits existants, en passant le nom de l'événement et ses arguments, et lèvera à nouveau la première exception de n'importe quel point d'entrée. En général, si une exception est levée, elle ne devrais pas être gérée et le processus devrait être terminé aussi rapidement que possible. Cela permet que les implémentations des points d'entrées décident comment répondre à des événements particuliers : Ils peuvent simplement `logger' l'événement ou arrêter l'opération en levant une exception.

Les points d'entrées sont ajoutés en utilisant les fonctions @ref{410c,,sys.addaudithook()} ou @ref{410d,,PySys_AddAuditHook()}.

L'équivalent natif de cette fonction est @ref{365,,PySys_Audit()}. L'utilisation de la fonction native est encouragée lorsque c'est possible.

Voir le @ref{17fe,,tableau d'événements d'audit} pour tous les événements levés par CPython.


Ajouté dans la version 3.8.

@end deffn

@geindex base_exec_prefix (dans le module sys)
@anchor{library/sys sys base_exec_prefix}@anchor{3e5}
@deffn {Données} sys.base_exec_prefix

Défini au démarrage de Python, avant que @code{site.py} ne soit évalué, à la même valeur que @ref{3a9,,exec_prefix}. Hors d'un @ref{4252,,environnement virtuel}, les valeurs restent les mêmes ; si @code{site.py} détecte qu'un environnement virtuel est utilisé, les valeurs de @ref{3ad,,prefix} et @ref{3a9,,exec_prefix} sont modifiées pour pointer vers l'environnement virtuel, alors que @ref{3e6,,base_prefix} et @ref{3e5,,base_exec_prefix} pointent toujours à la racine de l'installation de Python (celui utilisé pour créer l'environnement virtuel).


Ajouté dans la version 3.3.

@end deffn

@geindex base_prefix (dans le module sys)
@anchor{library/sys sys base_prefix}@anchor{3e6}
@deffn {Données} sys.base_prefix

Défini au démarrage de Python, avant que @code{site.py} ne soit évalué, à la même valeur que @ref{3ad,,prefix}. Hors d'un @ref{4252,,environnement virtuel}, les valeurs restent les mêmes ; si @code{site.py} détecte qu'un environnement virtuel est utilisé, les valeurs de @ref{3ad,,prefix} et @ref{3a9,,exec_prefix} sont modifiées pour pointer vers l'environnement virtuel, alors que @ref{3e6,,base_prefix} et @ref{3e5,,base_exec_prefix} pointent toujours à la racine de l'installation de Python (celui utilisé pour créer l'environnement virtuel).


Ajouté dans la version 3.3.

@end deffn

@geindex byteorder (dans le module sys)
@anchor{library/sys sys byteorder}@anchor{2124}
@deffn {Données} sys.byteorder

Un indicateur de l'ordre natif des octets.  Vaudra @code{'big'} sur les plateformes gros-boutistes (octet le plus significatif en premier), et @code{'little'} sur les plateformes petit-boutiste (octet le moins significatif en premier).
@end deffn

@geindex builtin_module_names (dans le module sys)
@anchor{library/sys sys builtin_module_names}@anchor{1bed}
@deffn {Données} sys.builtin_module_names

A tuple of strings containing the names of all modules that are compiled into this
Python interpreter.  (This information is not available in any other way ---
@code{modules.keys()} only lists the imported modules.)

See also the @ref{82b,,sys.stdlib_module_names} list.
@end deffn

@geindex call_tracing() (dans le module sys)
@anchor{library/sys sys call_tracing}@anchor{17c0}
@deffn {Fonction} sys.call_tracing (func, args)

Call @code{func(*args)}, while tracing is enabled.  The tracing state is saved,
and restored afterwards.  This is intended to be called from a debugger from
a checkpoint, to recursively debug or profile some other code.

Tracing is suspended while calling a tracing function set by
@ref{14b6,,settrace()} or @ref{14b5,,setprofile()} to avoid infinite recursion.
@code{call_tracing()} enables explicit recursion of the tracing function.
@end deffn

@geindex copyright (dans le module sys)
@anchor{library/sys sys copyright}@anchor{4280}
@deffn {Données} sys.copyright

Une chaîne contenant le copyright relatif à l'interpréteur Python.
@end deffn

@geindex _clear_type_cache() (dans le module sys)
@anchor{library/sys sys _clear_type_cache}@anchor{15fa}
@deffn {Fonction} sys._clear_type_cache ()

Vide le cache interne de types. Le cache de types est utilisé pour accélérer les recherches d'attributs et de méthodes. N'utilisez cette fonction `que' pour libérer des références inutiles durant le débogage de fuite de référence.

Cette fonction ne devrait être utilisée que pour un usage interne et spécialisé.


Obsolète depuis la version 3.13: Use the more general @ref{15f9,,_clear_internal_caches()} function instead.

@end deffn

@geindex _clear_internal_caches() (dans le module sys)
@anchor{library/sys sys _clear_internal_caches}@anchor{15f9}
@deffn {Fonction} sys._clear_internal_caches ()

Clear all internal performance-related caches. Use this function `only' to
release unnecessary references and memory blocks when hunting for leaks.


Ajouté dans la version 3.13.

@end deffn

@geindex _current_frames() (dans le module sys)
@anchor{library/sys sys _current_frames}@anchor{13e9}
@deffn {Fonction} sys._current_frames ()

Renvoie un dictionnaire faisant correspondre chaque identifiant de fil d'exécution à la `stack frame' actuellement active pour ces fils d'exécution au moment où la fonction est appelée. Notez que les fonctions du module @ref{fd,,traceback} peuvent construire une `call stack' à partir d'une telle `frame'.

N'ayant pas besoin de la coopération des fils d'exécution bloqués, cette fonction est très utile pour déboguer un `deadlock'. Aussi, les `call stack' de ces fils d'exécution ne changeront pas tant qu'ils seront bloqués. La `frame' renvoyée pour un fil d'exécution non bloqué peut ne plus être liée à l'activité courante du fil d'exécution au moment où le code appelant examine la `frame'.

Cette fonction ne devrait être utilisée que pour un usage interne et spécialisé.

Lève un @ref{1848,,événement d'audit} @code{sys._current_frames} sans arguments.
@end deffn

@geindex _current_exceptions() (dans le module sys)
@anchor{library/sys sys _current_exceptions}@anchor{4ab}
@deffn {Fonction} sys._current_exceptions ()

Return a dictionary mapping each thread's identifier to the topmost exception
currently active in that thread at the time the function is called.
If a thread is not currently handling an exception, it is not included in
the result dictionary.

This is most useful for statistical profiling.

Cette fonction ne devrait être utilisée que pour un usage interne et spécialisé.

Raises an @ref{1848,,auditing event} @code{sys._current_exceptions} with no arguments.


Modifié dans la version 3.12: Each value in the dictionary is now a single exception instance, rather
than a 3-tuple as returned from @code{sys.exc_info()}.

@end deffn

@geindex breakpointhook() (dans le module sys)
@anchor{library/sys sys breakpointhook}@anchor{ac8}
@deffn {Fonction} sys.breakpointhook ()

Cette fonction auto-déclenchée (`hook function' en anglais) est appelée par la fonction native @ref{231,,breakpoint()}. Par défaut, elle vous place dans le débogueur @ref{a4,,pdb}, mais elle peut être dirigée vers n'importe quelle autre fonction pour que vous puissiez choisir le débogueur utilisé.

La signature de cette fonction dépend de ce qu'elle appelle. Par exemple, l'appel par défaut (e.g. @code{pdb.set_trace()}) n'attend pas d'argument, mais vous pourriez la lier à une fonction qui attend des arguments supplémentaires (positionnels et/ou mots-clés). La fonction native @code{breakpoint()} passe ses @code{*args} et @code{**kws} directement au travers. Tout ce que renvoie @code{breakpointhooks()} est renvoyé par @code{breakpoint()}.

L'implémentation par défaut consulte d'abord la variable d'environnement 
@geindex PYTHONBREAKPOINT
@geindex variable d'environnement; PYTHONBREAKPOINT
@ref{ac9,,PYTHONBREAKPOINT}. Si elle vaut @code{"0"} alors cette fonction s'achève immédiatement (elle ne fait donc rien). Si la variable d'environnement n'est pas définie, ou s'il s'agit d'une chaîne vide, @code{pdb.set_trace()} est appelée. Sinon cette variable doit nommer une fonction à appeler, en utilisant la syntaxe d'importation de Python, par exemple @code{package.subpackage.module.function}. Dans ce cas, @code{package.subpackage.module} sera importé et le module devra contenir une fonction appelable @code{function()}. Celle-ci est lancée en lui passant @code{*args} et @code{*kws} et, quoique renvoie @code{function()}, @code{sys.breakpointhook()} retourne à la fonction native @ref{231,,breakpoint()}.

Notez que si un problème apparaît au moment de l'importation de la fonction nommée dans 
@geindex PYTHONBREAKPOINT
@geindex variable d'environnement; PYTHONBREAKPOINT
@ref{ac9,,PYTHONBREAKPOINT}, une alerte @ref{1bb,,RuntimeWarning} est indiquée et le point d'arrêt est ignoré.

Notez également que si @code{sys.breakpointhook()} est surchargé de manière programmatique, 
@geindex PYTHONBREAKPOINT
@geindex variable d'environnement; PYTHONBREAKPOINT
@ref{ac9,,PYTHONBREAKPOINT} `n'est pas' consulté.


Ajouté dans la version 3.7.

@end deffn

@geindex _debugmallocstats() (dans le module sys)
@anchor{library/sys sys _debugmallocstats}@anchor{4281}
@deffn {Fonction} sys._debugmallocstats ()

Affiche des informations bas-niveau sur la sortie d'erreur à propos de l'état de l'allocateur de mémoire de CPython.

If Python is @ref{1f6,,built in debug mode} (@ref{418,,configure --with-pydebug option}), it also performs some expensive
internal consistency checks.


Ajouté dans la version 3.3.


`Particularité de l'implémentation CPython :' Cette fonction est spécifique à CPython.  Le format de sa sortie n'est pas définit ici et pourrait changer.
@end deffn

@geindex dllhandle (dans le module sys)
@anchor{library/sys sys dllhandle}@anchor{4282}
@deffn {Données} sys.dllhandle

Nombre entier spécifiant le descripteur de la DLL Python.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex displayhook() (dans le module sys)
@anchor{library/sys sys displayhook}@anchor{14d6}
@deffn {Fonction} sys.displayhook (value)

Si `value' n'est pas @code{None}, cette fonction écrit @code{repr(value)} sur @code{sys.stdout}, et sauvegarde `value' dans @code{builtins._}. Si @code{repr(value)} ne peut pas être encodé avec @code{sys.stdout.encoding} en utilisant le gestionnaire d'erreur @code{sys.stdout.errors} (qui est probablement @code{'strict'}), elle sera encodée avec @code{sys.stdout.encoding} en utilisant le gestionnaire d'erreur @code{'backslashreplace'}.

@code{sys.displayhook} est appelé avec le résultat de l'évaluation d'une @ref{1f08,,expression} entrée dans une session Python interactive. L'affichage de ces valeurs peut être personnalisé en assignant une autre fonction d'un argument à @code{sys.displayhook}.

Pseudo-code :

@example
def displayhook(value):
    if value is None:
        return
    # Set '_' to None to avoid recursion
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value
@end example


Modifié dans la version 3.2: Utiliser le gestionnaire d'erreur @code{'backslashreplace'} en cas d'@ref{662,,UnicodeEncodeError}.

@end deffn

@geindex dont_write_bytecode (dans le module sys)
@anchor{library/sys sys dont_write_bytecode}@anchor{4283}
@deffn {Données} sys.dont_write_bytecode

Si vrai, Python n'essaiera pas d'écrire de fichiers @code{.pyc} à l'importation de modules source. Cette valeur est initialement définie à @code{True} ou @code{False} en fonction de l'option de la ligne de commande @ref{1384,,-B} et de la variable d'environnement 
@geindex PYTHONDONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONDONTWRITEBYTECODE
@code{PYTHONDONDONTWRITEBYTECODE}, mais vous pouvez aussi la modifier vous-même pour contrôler la génération des fichiers de `bytecode'.
@end deffn

@geindex _emscripten_info (dans le module sys)
@anchor{library/sys sys _emscripten_info}@anchor{178f}
@deffn {Données} sys._emscripten_info

A @ref{639,,named tuple} holding information about the environment on the
`wasm32-emscripten' platform. The named tuple is provisional and may change
in the future.

@geindex emscripten_version (attribut sys._emscripten_info)
@anchor{library/sys sys _emscripten_info emscripten_version}@anchor{4284}
@deffn {Attribut} _emscripten_info.emscripten_version

Emscripten version as tuple of ints (major, minor, micro), e.g. @code{(3, 1, 8)}.
@end deffn

@geindex runtime (attribut sys._emscripten_info)
@anchor{library/sys sys _emscripten_info runtime}@anchor{4285}
@deffn {Attribut} _emscripten_info.runtime

Runtime string, e.g. browser user agent, @code{'Node.js v14.18.2'}, or @code{'UNKNOWN'}.
@end deffn

@geindex pthreads (attribut sys._emscripten_info)
@anchor{library/sys sys _emscripten_info pthreads}@anchor{4286}
@deffn {Attribut} _emscripten_info.pthreads

@code{True} if Python is compiled with Emscripten pthreads support.
@end deffn

@geindex shared_memory (attribut sys._emscripten_info)
@anchor{library/sys sys _emscripten_info shared_memory}@anchor{4287}
@deffn {Attribut} _emscripten_info.shared_memory

@code{True} if Python is compiled with shared memory support.
@end deffn

@ref{1ce0,,Availability}: Emscripten.


Ajouté dans la version 3.11.

@end deffn

@geindex pycache_prefix (dans le module sys)
@anchor{library/sys sys pycache_prefix}@anchor{992}
@deffn {Données} sys.pycache_prefix

If this is set (not @code{None}), Python will write bytecode-cache @code{.pyc}
files to (and read them from) a parallel directory tree rooted at this
directory, rather than from @code{__pycache__} directories in the source code
tree. Any @code{__pycache__} directories in the source code tree will be ignored
and new @code{.pyc} files written within the pycache prefix. Thus if you use
@ref{20,,compileall} as a pre-build step, you must ensure you run it with the
same pycache prefix (if any) that you will use at runtime.

Un chemin relatif est interprété relativement au répertoire courant.

Cette valeur est initialement définie basée sur la valeur de l'option de ligne de commande @ref{175,,-X} @code{pycache_prefix=PATH} ou la variable d'environnement 
@geindex PYTHONPYCACHEPREFIX
@geindex variable d'environnement; PYTHONPYCACHEPREFIX
@ref{991,,PYTHONPYCACHEPREFIX} (La ligne de commande est prioritaire). Si aucune des deux options n'est définie, alors la valeur est @code{None}.


Ajouté dans la version 3.8.

@end deffn

@geindex excepthook() (dans le module sys)
@anchor{library/sys sys excepthook}@anchor{7f5}
@deffn {Fonction} sys.excepthook (type, value, traceback)

Cette fonction affiche la `traceback' et l'exception donnée sur @code{sys.stderr}.

When an exception other than @ref{d2e,,SystemExit} is raised and uncaught, the interpreter calls
@code{sys.excepthook} with three arguments, the exception class, exception
instance, and a traceback object.  In an interactive session this happens just
before control is returned to the prompt; in a Python program this happens just
before the program exits.  The handling of such top-level exceptions can be
customized by assigning another three-argument function to @code{sys.excepthook}.

Lève un événement d'audit @code{sys.excepthook} avec les arguments @code{hook}, @code{type}, @code{value}, @code{traceback} lorsqu'une exception non interceptée se produit. Si aucun point d'entrée n'a été défini, @code{hook} peut être @code{None}. Si n'importe quel point d'entrée lève une exception dérivée de @ref{193,,RuntimeError}, l'appel au point d'entrée sera supprimé. Autrement, l'exception du point d'entrée d'audit sera reporté comme `non levable' (`unraisable' en anglais) et @code{sys.excepthook} sera appelé.


@subsubheading Voir aussi


La fonction @ref{1f4,,sys.unraisablehook()} gère les exceptions `non-levables' et la fonction @ref{835,,threading.excepthook()} gère les exceptions levées par @ref{a2b,,threading.Thread.run()}.

@end deffn

@geindex __breakpointhook__ (dans le module sys)
@geindex __displayhook__ (dans le module sys)
@geindex __excepthook__ (dans le module sys)
@geindex __unraisablehook__ (dans le module sys)
@anchor{library/sys sys __breakpointhook__}@anchor{4288}
@deffn {Données} sys.__breakpointhook__
@anchor{library/sys sys __displayhook__}@anchor{4289}
@deffnx {Données} sys.__displayhook__
@anchor{library/sys sys __excepthook__}@anchor{428a}
@deffnx {Données} sys.__excepthook__
@anchor{library/sys sys __unraisablehook__}@anchor{428b}
@deffnx {Données} sys.__unraisablehook__

Ces objets contiennent les valeurs originales de @code{breakpointhook}, @code{displayhook}, @code{excepthook} et @code{unraisablehook} au début du programme.Ils sont sauvegardés de façon à ce que @code{breakpointhook}, @code{displayhook}, @code{excepthook} et @code{unraisablehook} puissent être restaurés au cas où ils seraient remplacés par des objets cassés ou alternatifs.


Ajouté dans la version 3.7: @code{__breakpointhook__}



Ajouté dans la version 3.8: @code{__unraisablehook__}

@end deffn

@geindex exception() (dans le module sys)
@anchor{library/sys sys exception}@anchor{676}
@deffn {Fonction} sys.exception ()

This function, when called while an exception handler is executing (such as
an @code{except} or @code{except*} clause), returns the exception instance that
was caught by this handler. When exception handlers are nested within one
another, only the exception handled by the innermost handler is accessible.

If no exception handler is executing, this function returns @code{None}.


Ajouté dans la version 3.11.

@end deffn

@geindex exc_info() (dans le module sys)
@anchor{library/sys sys exc_info}@anchor{675}
@deffn {Fonction} sys.exc_info ()

This function returns the old-style representation of the handled
exception. If an exception @code{e} is currently handled (so
@ref{676,,exception()} would return @code{e}), @ref{675,,exc_info()} returns the
tuple @code{(type(e), e, e.__traceback__)}.
That is, a tuple containing the type of the exception (a subclass of
@ref{5a5,,BaseException}), the exception itself, and a @ref{ae2,,traceback object} which typically encapsulates the call
stack at the point where the exception last occurred.

@geindex object;traceback

If no exception is being handled anywhere on the stack, this function
return a tuple containing three @code{None} values.


Modifié dans la version 3.11: The @code{type} and @code{traceback} fields are now derived from the @code{value}
(the exception instance), so when an exception is modified while it is
being handled, the changes are reflected in the results of subsequent
calls to @ref{675,,exc_info()}.

@end deffn

@geindex exec_prefix (dans le module sys)
@anchor{library/sys sys exec_prefix}@anchor{3a9}
@deffn {Données} sys.exec_prefix

Une chaîne donnant le préfixe de dossier spécifique au site où les fichiers dépendant de la plateforme sont installés. Par défaut, c'est @code{'/usr/local'}. C'est configurable à la compilation avec l'option @code{--exec-prefix} du script @code{configure}. Tous les fichiers de configurations (tel que @code{pyconfig,h}) sont installés dans le dossier @code{`exec_prefix'/lib/python`X.Y'/config}, et les modules sous forme de bibliothèques partagées sont installés dans @code{`exec_prefix'/lib/python`X.Y'/lib-dynload}, où `X.Y' est le numéro de version de  Python, par exemple @code{3.2}.

@cartouche
@quotation Note 
Si un @ref{4252,,environment virtuel} est actif, cette valeur sera modifiée par @code{site.py} pour pointer vers l'environnement virtuel. La valeur d'origine sera toujours disponible via @ref{3e5,,base_exec_prefix}.
@end quotation
@end cartouche
@end deffn

@geindex executable (dans le module sys)
@anchor{library/sys sys executable}@anchor{3af}
@deffn {Données} sys.executable

Une chaîne donnant le chemin absolu vers l'interpréteur Python, un fichier binaire exécutable, sur les système sur lesquels ça à du sens. Si Python n'est pas capable de récupérer le chemin réel de son exécutable, @ref{3af,,sys.executable} sera une chaîne vide ou @code{None}.
@end deffn

@geindex exit() (dans le module sys)
@anchor{library/sys sys exit}@anchor{1327}
@deffn {Fonction} sys.exit ([arg])

Raise a @ref{d2e,,SystemExit} exception, signaling an intention to exit the interpreter.

L'argument optionnel `arg' peut être un nombre entier donnant l'état de sortie (zéro par défaut), ou un autre type d'objet.  Pour les `shells' (et autres), si c'est un entier, zéro signifie "terminé avec succès", et toutes les autres valeurs signifient "terminé anormalement". La plupart des systèmes imposent qu'il se situe dans la plage 0--127, et leur comportement n'est pas défini pour les autres cas. Certains systèmes peu communs ont pour convention d'assigner un sens particulier à des valeur spécifiques. Les programmes Unix utilisent généralement 2 pour les erreurs de syntaxe dans les arguments de la ligne de commande, et 1 pour toutes les autres erreurs. Si un autre type est passé, @code{None} est équivalent à zéro, et tout autre objet est écrit sur @ref{926,,stderr} et donne un code de sortie 1. Typiquement, @code{sys.exit("some error message")} est un moyen rapide de quitter un programme en cas d'erreur.

Since @ref{2112,,exit()} ultimately "only" raises an exception, it will only exit
the process when called from the main thread, and the exception is not
intercepted. Cleanup actions specified by finally clauses of @ref{6d3,,try} statements
are honored, and it is possible to intercept the exit attempt at an outer level.


Modifié dans la version 3.6: Si une erreur survient lors du nettoyage après que l'interpréteur Python ait intercepté un @ref{d2e,,SystemExit} (typiquement une erreur en vidant les tampons des sorties standard), le code de sortie est changé à 120.

@end deffn

@geindex flags (dans le module sys)
@anchor{library/sys sys flags}@anchor{677}
@deffn {Données} sys.flags

La @ref{639,,named tuple} `flags' expose l'état des options de ligne de commande. Ces attributs sont en lecture seule.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@item

@geindex debug (attribut sys.flags)
@anchor{library/sys sys flags debug}@anchor{428c}
@deffn {Attribut} flags.debug
@end deffn

@tab

@ref{1cbd,,-d}

@item

@geindex inspect (attribut sys.flags)
@anchor{library/sys sys flags inspect}@anchor{428d}
@deffn {Attribut} flags.inspect
@end deffn

@tab

@ref{1491,,-i}

@item

@geindex interactive (attribut sys.flags)
@anchor{library/sys sys flags interactive}@anchor{428e}
@deffn {Attribut} flags.interactive
@end deffn

@tab

@ref{1491,,-i}

@item

@geindex isolated (attribut sys.flags)
@anchor{library/sys sys flags isolated}@anchor{428f}
@deffn {Attribut} flags.isolated
@end deffn

@tab

@ref{94b,,-I}

@item

@geindex optimize (attribut sys.flags)
@anchor{library/sys sys flags optimize}@anchor{4290}
@deffn {Attribut} flags.optimize
@end deffn

@tab

@ref{da2,,-O} or @ref{da3,,-OO}

@item

@geindex dont_write_bytecode (attribut sys.flags)
@anchor{library/sys sys flags dont_write_bytecode}@anchor{4291}
@deffn {Attribut} flags.dont_write_bytecode
@end deffn

@tab

@ref{1384,,-B}

@item

@geindex no_user_site (attribut sys.flags)
@anchor{library/sys sys flags no_user_site}@anchor{4292}
@deffn {Attribut} flags.no_user_site
@end deffn

@tab

@ref{1362,,-s}

@item

@geindex no_site (attribut sys.flags)
@anchor{library/sys sys flags no_site}@anchor{4293}
@deffn {Attribut} flags.no_site
@end deffn

@tab

@ref{1186,,-S}

@item

@geindex ignore_environment (attribut sys.flags)
@anchor{library/sys sys flags ignore_environment}@anchor{4294}
@deffn {Attribut} flags.ignore_environment
@end deffn

@tab

@ref{94a,,-E}

@item

@geindex verbose (attribut sys.flags)
@anchor{library/sys sys flags verbose}@anchor{4295}
@deffn {Attribut} flags.verbose
@end deffn

@tab

@ref{13db,,-v}

@item

@geindex bytes_warning (attribut sys.flags)
@anchor{library/sys sys flags bytes_warning}@anchor{4296}
@deffn {Attribut} flags.bytes_warning
@end deffn

@tab

@ref{5cd,,-b}

@item

@geindex quiet (attribut sys.flags)
@anchor{library/sys sys flags quiet}@anchor{4297}
@deffn {Attribut} flags.quiet
@end deffn

@tab

@ref{1cc0,,-q}

@item

@geindex hash_randomization (attribut sys.flags)
@anchor{library/sys sys flags hash_randomization}@anchor{4298}
@deffn {Attribut} flags.hash_randomization
@end deffn

@tab

@ref{1a25,,-R}

@item

@geindex dev_mode (attribut sys.flags)
@anchor{library/sys sys flags dev_mode}@anchor{1a2f}
@deffn {Attribut} flags.dev_mode
@end deffn

@tab

@ref{175,,-X dev} (@ref{1f5,,Python en mode développement})

@item

@geindex utf8_mode (attribut sys.flags)
@anchor{library/sys sys flags utf8_mode}@anchor{4299}
@deffn {Attribut} flags.utf8_mode
@end deffn

@tab

@ref{175,,-X utf8}

@item

@geindex safe_path (attribut sys.flags)
@anchor{library/sys sys flags safe_path}@anchor{233}
@deffn {Attribut} flags.safe_path
@end deffn

@tab

@ref{58e,,-P}

@item

@geindex int_max_str_digits (attribut sys.flags)
@anchor{library/sys sys flags int_max_str_digits}@anchor{2203}
@deffn {Attribut} flags.int_max_str_digits
@end deffn

@tab

@ref{175,,-X int_max_str_digits}
(@ref{5df,,integer string conversion length limitation})

@item

@geindex warn_default_encoding (attribut sys.flags)
@anchor{library/sys sys flags warn_default_encoding}@anchor{429a}
@deffn {Attribut} flags.warn_default_encoding
@end deffn

@tab

@ref{175,,-X warn_default_encoding}

@end multitable



Modifié dans la version 3.2: Ajout de l'attribut @code{quiet} pour la nouvelle option @ref{1cc0,,-q}.



Ajouté dans la version 3.2.3: L'attribut @code{hash_randomization}.



Modifié dans la version 3.3: Suppression de l'attribut obsolète @code{division_warning}.



Modifié dans la version 3.4: Ajout de l'attribut @code{isolated} pour l'option @ref{94b,,-I} @code{isolated}.



Modifié dans la version 3.7: Ajout de l'attribut @code{dev_mode} pour le nouveau @ref{1f5,,Mode Développeur Python} et l'attribut @code{utf8_mode} pour la nouvelle option @ref{175,,-X} @code{utf8}.



Modifié dans la version 3.10: Added @code{warn_default_encoding} attribute for @ref{175,,-X} @code{warn_default_encoding} flag.



Modifié dans la version 3.11: Added the @code{safe_path} attribute for @ref{58e,,-P} option.



Modifié dans la version 3.11: Added the @code{int_max_str_digits} attribute.

@end deffn

@geindex float_info (dans le module sys)
@anchor{library/sys sys float_info}@anchor{1979}
@deffn {Données} sys.float_info

Un @ref{639,,named tuple} contenant des informations à propos du type `float'. Il contient des informations de bas niveau à propos de la précision et de la représentation interne.  Les valeurs correspondent aux différentes constantes à propos des nombres à virgule flottantes définies dans le fichier d'entête @code{float.h} pour le langage de programmation C. Voir la section  5.2.4.2.2 de `1999 ISO/IEC C standard' @ref{429b,,[C99]}, `Characteristics of floating types', pour plus de détails.
Attributes of the @code{float_info} named tuple



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

attribut

@tab

macro `float.h'

@tab

explication

@item

@geindex epsilon (attribut sys.float_info)
@anchor{library/sys sys float_info epsilon}@anchor{429c}
@deffn {Attribut} float_info.epsilon
@end deffn

@tab

@code{DBL_EPSILON}

@tab

difference between 1.0 and the least value greater than 1.0 that is
representable as a float.

Voir aussi : @ref{8ff,,math.ulp()}.

@item

@geindex dig (attribut sys.float_info)
@anchor{library/sys sys float_info dig}@anchor{429d}
@deffn {Attribut} float_info.dig
@end deffn

@tab

@code{DBL_DIG}

@tab

The maximum number of decimal digits that can be faithfully
represented in a float; see below.

@item

@geindex mant_dig (attribut sys.float_info)
@anchor{library/sys sys float_info mant_dig}@anchor{429e}
@deffn {Attribut} float_info.mant_dig
@end deffn

@tab

@code{DBL_MANT_DIG}

@tab

Float precision: the number of base-@code{radix} digits in the
significand of a float.

@item

@geindex max (attribut sys.float_info)
@anchor{library/sys sys float_info max}@anchor{429f}
@deffn {Attribut} float_info.max
@end deffn

@tab

@code{DBL_MAX}

@tab

The maximum representable positive finite float.

@item

@geindex max_exp (attribut sys.float_info)
@anchor{library/sys sys float_info max_exp}@anchor{42a0}
@deffn {Attribut} float_info.max_exp
@end deffn

@tab

@code{DBL_MAX_EXP}

@tab

The maximum integer `e' such that @code{radix**(e-1)} is a representable
finite float.

@item

@geindex max_10_exp (attribut sys.float_info)
@anchor{library/sys sys float_info max_10_exp}@anchor{42a1}
@deffn {Attribut} float_info.max_10_exp
@end deffn

@tab

@code{DBL_MAX_10_EXP}

@tab

The maximum integer `e' such that @code{10**e} is in the range of
representable finite floats.

@item

@geindex min (attribut sys.float_info)
@anchor{library/sys sys float_info min}@anchor{42a2}
@deffn {Attribut} float_info.min
@end deffn

@tab

@code{DBL_MIN}

@tab

The minimum representable positive `normalized' float.

Utilisez @ref{8ff,,math.ulp(0.0)} pour obtenir le plus petit nombre a virgule positif `dénormalisé' représentable.

@item

@geindex min_exp (attribut sys.float_info)
@anchor{library/sys sys float_info min_exp}@anchor{42a3}
@deffn {Attribut} float_info.min_exp
@end deffn

@tab

@code{DBL_MIN_EXP}

@tab

The minimum integer `e' such that @code{radix**(e-1)} is a normalized
float.

@item

@geindex min_10_exp (attribut sys.float_info)
@anchor{library/sys sys float_info min_10_exp}@anchor{42a4}
@deffn {Attribut} float_info.min_10_exp
@end deffn

@tab

@code{DBL_MIN_10_EXP}

@tab

The minimum integer `e' such that @code{10**e} is a normalized float.

@item

@geindex radix (attribut sys.float_info)
@anchor{library/sys sys float_info radix}@anchor{42a5}
@deffn {Attribut} float_info.radix
@end deffn

@tab

@code{FLT_RADIX}

@tab

The radix of exponent representation.

@item

@geindex rounds (attribut sys.float_info)
@anchor{library/sys sys float_info rounds}@anchor{42a6}
@deffn {Attribut} float_info.rounds
@end deffn

@tab

@code{FLT_ROUNDS}

@tab

An integer representing the rounding mode for floating-point arithmetic.
This reflects the value of the system @code{FLT_ROUNDS} macro
at interpreter startup time:


@itemize *

@item 
@code{-1}: indeterminable

@item 
@code{0}: toward zero

@item 
@code{1}: to nearest

@item 
@code{2}: toward positive infinity

@item 
@code{3}: toward negative infinity
@end itemize

All other values for @code{FLT_ROUNDS} characterize
implementation-defined rounding behavior.

@end multitable


The attribute @ref{429d,,sys.float_info.dig} needs further explanation.  If
@code{s} is any string representing a decimal number with at most
@code{sys.float_info.dig} significant digits, then converting @code{s} to a
float and back again will recover a string representing the same decimal
value:

@example
>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # decimal string with 15 significant digits
>>> format(float(s), '.15g')  # convert to float and back -> same value
'3.14159265358979'
@end example

Cependant, pour les chaînes avec plus de @ref{429d,,sys.float_info.dig} chiffres significatifs, ce n'est pas toujours vrai :

@example
>>> s = '9876543211234567'    # 16 significant digits is too many!
>>> format(float(s), '.16g')  # conversion changes value
'9876543211234568'
@end example
@end deffn

@geindex float_repr_style (dans le module sys)
@anchor{library/sys sys float_repr_style}@anchor{12d8}
@deffn {Données} sys.float_repr_style

Une chaîne indiquant comment la fonction @ref{7e7,,repr()} se comporte avec les nombres à virgule flottante. Si la chaîne a la valeur @code{'short'}, alors pour un `float' finit @code{x}, @code{repr(x)} essaye de donner une courte chaîne tel que @code{float(repr(x)) == x}.  C'est le comportement typique à partir de Python 3.1.  Autrement, @code{float_repr_style} a la valeur @code{'legacy'} et
@code{repr(x)} se comporte comme les versions antérieures à 3.1.


Ajouté dans la version 3.1.

@end deffn

@geindex getallocatedblocks() (dans le module sys)
@anchor{library/sys sys getallocatedblocks}@anchor{fb0}
@deffn {Fonction} sys.getallocatedblocks ()

Return the number of memory blocks currently allocated by the interpreter,
regardless of their size.  This function is mainly useful for tracking
and debugging memory leaks.  Because of the interpreter's internal
caches, the result can vary from call to call; you may have to call
@ref{15f9,,_clear_internal_caches()} and @ref{a28,,gc.collect()} to get more
predictable results.

If a Python build or implementation cannot reasonably compute this
information, @ref{fb0,,getallocatedblocks()} is allowed to return 0 instead.


Ajouté dans la version 3.4.

@end deffn

@geindex getunicodeinternedsize() (dans le module sys)
@anchor{library/sys sys getunicodeinternedsize}@anchor{42a7}
@deffn {Fonction} sys.getunicodeinternedsize ()

Return the number of unicode objects that have been interned.


Ajouté dans la version 3.12.

@end deffn

@geindex getandroidapilevel() (dans le module sys)
@anchor{library/sys sys getandroidapilevel}@anchor{b78}
@deffn {Fonction} sys.getandroidapilevel ()

Return the build-time API level of Android as an integer. This represents the
minimum version of Android this build of Python can run on. For runtime
version information, see @ref{15d5,,platform.android_ver()}.

@ref{1ce0,,Availability}: Android.


Ajouté dans la version 3.7.

@end deffn

@geindex getdefaultencoding() (dans le module sys)
@anchor{library/sys sys getdefaultencoding}@anchor{42a8}
@deffn {Fonction} sys.getdefaultencoding ()

Renvoie le nom du codage par défaut actuellement utilisé par l'implémentation `Unicode' pour coder les chaînes.
@end deffn

@geindex getdlopenflags() (dans le module sys)
@anchor{library/sys sys getdlopenflags}@anchor{14c6}
@deffn {Fonction} sys.getdlopenflags ()

Return the current value of the flags that are used for
@code{dlopen()} calls.  Symbolic names for the flag values can be
found in the @ref{a0,,os} module (@code{RTLD_@var{xxx}} constants, e.g.
@ref{10f8,,os.RTLD_LAZY}).

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex getfilesystemencoding() (dans le module sys)
@anchor{library/sys sys getfilesystemencoding}@anchor{c47}
@deffn {Fonction} sys.getfilesystemencoding ()

Get the @ref{525,,filesystem encoding}:
the encoding used with the @ref{525,,filesystem error handler} to convert between Unicode filenames and bytes
filenames. The filesystem error handler is returned from
@ref{cd4,,getfilesystemencodeerrors()}.

For best compatibility, str should be used for filenames in all cases,
although representing filenames as bytes is also supported. Functions
accepting or returning filenames should support either str or bytes and
internally convert to the system's preferred representation.

Les fonctions @ref{c43,,os.fsencode()} et @ref{c42,,os.fsdecode()} devraient être utilisées pour s'assurer qu'un encodage et un gestionnaire d'erreurs correct sont utilisés.

L'@ref{525,,encodage du système de fichiers et gestionnaire d'erreurs associé} sont configurés au démarrage de Python par la fonction @ref{77a,,PyConfig_Read()} : regardez @ref{3df,,filesystem_encoding} et @ref{3e0,,filesystem_errors} dans les membres de @ref{39d,,PyConfig}.


Modifié dans la version 3.2: @ref{c47,,getfilesystemencoding()} ne peut plus renvoyer @code{None}.



Modifié dans la version 3.6: Sur Windows, on est plus assurés d'obtenir @code{'mbcs'}. Voir la 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} et @ref{2ab,,_enablelegacywindowsfsencoding()} pour plus d'informations.



Modifié dans la version 3.7: Return @code{'utf-8'} if the @ref{641,,Python UTF-8 Mode} is
enabled.

@end deffn

@geindex getfilesystemencodeerrors() (dans le module sys)
@anchor{library/sys sys getfilesystemencodeerrors}@anchor{cd4}
@deffn {Fonction} sys.getfilesystemencodeerrors ()

Get the @ref{525,,filesystem error handler}: the error handler used with the @ref{525,,filesystem encoding} to convert between Unicode
filenames and bytes filenames. The filesystem encoding is returned from
@ref{c47,,getfilesystemencoding()}.

Les fonctions @ref{c43,,os.fsencode()} et @ref{c42,,os.fsdecode()} devraient être utilisées pour s'assurer qu'un encodage et un gestionnaire d'erreurs correct sont utilisés.

L'@ref{525,,encodage du système de fichiers et gestionnaire d'erreurs associé} sont configurés au démarrage de Python par la fonction @ref{77a,,PyConfig_Read()} : regardez @ref{3df,,filesystem_encoding} et @ref{3e0,,filesystem_errors} dans les membres de @ref{39d,,PyConfig}.


Ajouté dans la version 3.6.

@end deffn

@geindex get_int_max_str_digits() (dans le module sys)
@anchor{library/sys sys get_int_max_str_digits}@anchor{2205}
@deffn {Fonction} sys.get_int_max_str_digits ()

Returns the current value for the @ref{5df,,integer string conversion length limitation}. See also @ref{174c,,set_int_max_str_digits()}.


Ajouté dans la version 3.11.

@end deffn

@geindex getrefcount() (dans le module sys)
@anchor{library/sys sys getrefcount}@anchor{42a9}
@deffn {Fonction} sys.getrefcount (object)

Donne le nombre de référence de l'objet `object'. Le nombre renvoyé est généralement d'une référence de plus qu'attendu, puisqu'il compte la référence (temporaire) de l'argument à @ref{42a9,,getrefcount()}.

Note that the returned value may not actually reflect how many
references to the object are actually held.  For example, some
objects are @ref{42aa,,immortal} and have a very high refcount that does not
reflect the actual number of references.  Consequently, do not rely
on the returned value to be accurate, other than a value of 0 or 1.


Modifié dans la version 3.12: Immortal objects have very large refcounts that do not match
the actual number of references to the object.

@end deffn

@geindex getrecursionlimit() (dans le module sys)
@anchor{library/sys sys getrecursionlimit}@anchor{4ad}
@deffn {Fonction} sys.getrecursionlimit ()

Donne la limite actuelle de la limite de récursion, la profondeur maximum de la pile de l'interpréteur.  Cette limite empêche Python de planter lors d'une récursion infinie à cause d'un débordement de la pile. Elle peut être modifiée par @ref{4ac,,setrecursionlimit()}.
@end deffn

@geindex getsizeof() (dans le module sys)
@anchor{library/sys sys getsizeof}@anchor{16f8}
@deffn {Fonction} sys.getsizeof (object[, default])

Donne la taille d'un objet en octets. L'objet peut être de n'importe quel type. Le résultat sera correct pour tous les objets natifs, mais le résultat peut ne pas être toujours vrai pour les extensions, la valeur étant dépendante de l'implémentation.

Seule la mémoire directement attribuée à l'objet est prise en compte, pas la mémoire consommée par les objets vers lesquels il a des références.

S'il est fourni, `default' sera renvoyé si l'objet ne fournit aucun moyen de récupérer sa taille.  Sinon, une exception @ref{522,,TypeError} sera levée.

@ref{16f8,,getsizeof()} appelle la méthode @code{__sizeof__} de l'objet, et s'il est géré par lui, ajoute le surcoût du ramasse-miettes.

See recursive sizeof recipe@footnote{https://code.activestate.com/recipes/577504-compute-memory-footprint-of-an-object-and-its-cont/}
for an example of using @ref{16f8,,getsizeof()} recursively to find the size of
containers and all their contents.
@end deffn

@geindex getswitchinterval() (dans le module sys)
@anchor{library/sys sys getswitchinterval}@anchor{936}
@deffn {Fonction} sys.getswitchinterval ()

Renvoie la valeur du `thread switch interval' de l'interpréteur, voir @ref{937,,setswitchinterval()}.


Ajouté dans la version 3.2.

@end deffn

@geindex _getframe() (dans le module sys)
@anchor{library/sys sys _getframe}@anchor{6cb}
@deffn {Fonction} sys._getframe ([depth])

Renvoie une `frame' de la pile d'appels. Si le nombre entier optionnel `depth' est donné, la `frame' donnée sera de `depth' appels depuis le haut de la pile. Si c'est plus profond que la hauteur de la pile, une exception @ref{1ff,,ValueError} est levée. La profondeur par défaut est zéro, donnant ainsi la `frame' du dessus de la pile.

Raises an @ref{1848,,auditing event} @code{sys._getframe} with argument @code{frame}.

`Particularité de l'implémentation CPython :' Cette fonction ne devrait être utilisée que pour une utilisation interne et spécifique. Il n'est pas garanti qu'elle existe dans toutes les implémentations de Python.
@end deffn

@geindex _getframemodulename() (dans le module sys)
@anchor{library/sys sys _getframemodulename}@anchor{16fd}
@deffn {Fonction} sys._getframemodulename ([depth])

Return the name of a module from the call stack.  If optional integer `depth'
is given, return the module that many calls below the top of the stack.  If
that is deeper than the call stack, or if the module is unidentifiable,
@code{None} is returned.  The default for `depth' is zero, returning the
module at the top of the call stack.

Raises an @ref{1848,,auditing event} @code{sys._getframemodulename} with argument @code{depth}.

`Particularité de l'implémentation CPython :' Cette fonction ne devrait être utilisée que pour une utilisation interne et spécifique. Il n'est pas garanti qu'elle existe dans toutes les implémentations de Python.
@end deffn

@geindex getobjects() (dans le module sys)
@anchor{library/sys sys getobjects}@anchor{41b}
@deffn {Fonction} sys.getobjects (limit[, type])

This function only exists if CPython was built using the
specialized configure option @ref{38b,,--with-trace-refs}.
It is intended only for debugging garbage-collection issues.

Return a list of up to `limit' dynamically allocated Python objects.
If `type' is given, only objects of that exact type (not subtypes)
are included.

Objects from the list are not safe to use.
Specifically, the result will include objects from all interpreters that
share their object allocator state (that is, ones created with
@ref{42ab,,PyInterpreterConfig.use_main_obmalloc} set to 1
or using @ref{1744,,Py_NewInterpreter()}, and the
@ref{573,,main interpreter}).
Mixing objects from different interpreters may lead to crashes
or other unexpected behavior.

`Particularité de l'implémentation CPython :' This function should be used for specialized purposes only.
It is not guaranteed to exist in all implementations of Python.


Modifié dans la version 3.13.1: The result may include objects from other interpreters.

@end deffn

@geindex getprofile() (dans le module sys)
@anchor{library/sys sys getprofile}@anchor{1397}
@deffn {Fonction} sys.getprofile ()

@geindex profile function
@geindex profiler

Renvoie la fonction de profilage tel que défini par @ref{14b5,,setprofile()}.
@end deffn

@geindex gettrace() (dans le module sys)
@anchor{library/sys sys gettrace}@anchor{1398}
@deffn {Fonction} sys.gettrace ()

@geindex trace function
@geindex debugger

Renvoie la fonction de traçage tel que définie par @ref{14b6,,settrace()}.

`Particularité de l'implémentation CPython :' La fonction @ref{1398,,gettrace()} ne sert que pour implémenter des débogueurs, des `profilers', outils d'analyse de couverture, etc…. Son comportement dépend de l'implémentation et non du langage, elle n'est donc pas forcément disponible dans toutes les implémentations de Python.
@end deffn

@geindex getwindowsversion() (dans le module sys)
@anchor{library/sys sys getwindowsversion}@anchor{cd5}
@deffn {Fonction} sys.getwindowsversion ()

Renvoie un `n'-uplet nommé décrivant la version de Windows en cours d'exécution.
Les attributs nommés sont `major', `minor', `build', `platform',
`service_pack', `service_pack_minor', `service_pack_major',
`suite_mask', `product_type' et `platform_version'. `service_pack'
contient une string, `platform_version' un triplet, et tous les autres sont des nombres entiers. Ces attributs sont également accessibles par leur nom, donc @code{sys.getwindowsversion()[0]} est équivalent à @code{sys.getwindowsversion().major}. Pour des raisons de compatibilité avec les versions antérieures, seuls les 5 premiers éléments sont accessibles par leur indice.

`platform' will be @code{2} (VER_PLATFORM_WIN32_NT).

`product_type' peut être une des valeurs suivantes :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Signification

@item

@code{1} (VER_NT_WORKSTATION)

@tab

Le système une station de travail.

@item

@code{2} (VER_NT_DOMAIN_CONTROLLER)

@tab

Le système est un contrôleur de domaine.

@item

@code{3} (VER_NT_SERVER)

@tab

Le système est un serveur, mais pas un contrôleur de domaine.

@end multitable


This function wraps the Win32 @code{GetVersionEx()} function; see the
Microsoft documentation on @code{OSVERSIONINFOEX()} for more information
about these fields.

`platform_version' returns the major version, minor version and
build number of the current operating system, rather than the version that
is being emulated for the process. It is intended for use in logging rather
than for feature detection.

@cartouche
@quotation Note 
`platform_version' derives the version from kernel32.dll which can be of a different
version than the OS version. Please use @ref{a9,,platform} module for achieving accurate
OS version.
@end quotation
@end cartouche

@ref{1ce0,,Availability}: Windows.


Modifié dans la version 3.2: Changé en un `n'-uplet nommé, et ajout de `service_pack_minor', `service_pack_major', `suite_mask', et `product_type'.



Modifié dans la version 3.6: Ajout de `platform_version'

@end deffn

@geindex get_asyncgen_hooks() (dans le module sys)
@anchor{library/sys sys get_asyncgen_hooks}@anchor{17c1}
@deffn {Fonction} sys.get_asyncgen_hooks ()

Renvoie un objet `asyncgen_hooks', qui est semblable à un @ref{1c5,,namedtuple} de la forme @code{(firstiter, finalizer)}, où `firstiter' et `finalizer' sont soit @code{None} ou des fonctions qui prennent un @ref{42ac,,asynchronous generator iterator} comme argument, et sont utilisées pour planifier la finalisation d'un générateur asynchrone par un `event loop'.


Ajouté dans la version 3.6: Voir la 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} pour plus d'informations.


@cartouche
@quotation Note 
Cette fonction à été ajoutée à titre provisoire (voir la 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} pour plus d'informations.)
@end quotation
@end cartouche
@end deffn

@geindex get_coroutine_origin_tracking_depth() (dans le module sys)
@anchor{library/sys sys get_coroutine_origin_tracking_depth}@anchor{b79}
@deffn {Fonction} sys.get_coroutine_origin_tracking_depth ()

Récupère le nombre de cadres d'exécution conservés par les coroutines pour le suivi de leur création, telle que défini par @ref{b7a,,set_coroutine_origin_tracking_depth()}.


Ajouté dans la version 3.7.


@cartouche
@quotation Note 
Cette fonction à été ajoutée à titre provisoire (Voir la 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} pour plus d'informations.)  Utilisez la uniquement à des fins de débogage.
@end quotation
@end cartouche
@end deffn

@geindex hash_info (dans le module sys)
@anchor{library/sys sys hash_info}@anchor{fe8}
@deffn {Données} sys.hash_info

Un @ref{639,,named tuple} donnant les paramètres de l'implémentation de la fonction de hachage de nombres.  Pour plus d'informations sur le hachage des types numériques, consultez @ref{2129,,Hachage des types numériques}.

@geindex width (attribut sys.hash_info)
@anchor{library/sys sys hash_info width}@anchor{42ad}
@deffn {Attribut} hash_info.width

The width in bits used for hash values
@end deffn

@geindex modulus (attribut sys.hash_info)
@anchor{library/sys sys hash_info modulus}@anchor{212a}
@deffn {Attribut} hash_info.modulus

The prime modulus P used for numeric hash scheme
@end deffn

@geindex inf (attribut sys.hash_info)
@anchor{library/sys sys hash_info inf}@anchor{42ae}
@deffn {Attribut} hash_info.inf

The hash value returned for a positive infinity
@end deffn

@geindex nan (attribut sys.hash_info)
@anchor{library/sys sys hash_info nan}@anchor{42af}
@deffn {Attribut} hash_info.nan

(This attribute is no longer used)
@end deffn

@geindex imag (attribut sys.hash_info)
@anchor{library/sys sys hash_info imag}@anchor{42b0}
@deffn {Attribut} hash_info.imag

The multiplier used for the imaginary part of a complex number
@end deffn

@geindex algorithm (attribut sys.hash_info)
@anchor{library/sys sys hash_info algorithm}@anchor{42b1}
@deffn {Attribut} hash_info.algorithm

The name of the algorithm for hashing of str, bytes, and memoryview
@end deffn

@geindex hash_bits (attribut sys.hash_info)
@anchor{library/sys sys hash_info hash_bits}@anchor{42b2}
@deffn {Attribut} hash_info.hash_bits

The internal output size of the hash algorithm
@end deffn

@geindex seed_bits (attribut sys.hash_info)
@anchor{library/sys sys hash_info seed_bits}@anchor{42b3}
@deffn {Attribut} hash_info.seed_bits

The size of the seed key of the hash algorithm
@end deffn


Ajouté dans la version 3.2.



Modifié dans la version 3.4: Ajout de `algorithm', `hash_bits' et `seed_bits'

@end deffn

@geindex hexversion (dans le module sys)
@anchor{library/sys sys hexversion}@anchor{42b4}
@deffn {Données} sys.hexversion

Le numéro de version codé sous forme d'un seul nombre entier.  Ce numéro augmente avec chaque version, y compris pour les versions hors production.  Par exemple, pour vérifier que l'interpréteur Python est au moins la version 1.5, utilisez :

@example
if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...
@end example

Cet attribut s'appelle @code{hexversion} dans le sens où il ne semble avoir du sens que s'il est regardé après avoir été passé à la fonction native @ref{12ad,,hex()}.  Le @ref{639,,named tuple}  @ref{68b,,sys.version_info} représente la même information d'une manière plus humaine.

Consultez @ref{42b5,,Version des API et ABI} pour plus d'informations sur @code{hexversion}.
@end deffn

@geindex implementation (dans le module sys)
@anchor{library/sys sys implementation}@anchor{500}
@deffn {Données} sys.implementation

Un objet contenant des informations sur l'implémentation de la version actuelle de l'interpréteur Python.  Les attributs suivants existent obligatoirement sur toutes les implémentations Python.

`name' est l'identifiant de l'implémentation, e.g. @code{'cpython'}.  Cette chaîne est définie par l'implémentation de Python, mais sera toujours en minuscule.

`version' est un `n'-uplet nommé, du même format que @ref{68b,,sys.version_info}.  Il représente la version de l'`implementation' de Python.  C'est une information différente de la version du `langage' auquel l'interpréteur actuel se conforme (donnée par @code{sys.version_info}). Par exemple, pour PyPy 1.8 @code{sys.implementation.version} peut valoir @code{sys.version_info(1, 8, 0, 'final', 0)}, alors que @code{sys.version_info} peut valoir @code{sys.version_info(2, 7, 2, 'final', 0)}.  Pour CPython ces deux valeurs sont identiques puisque c'est l'implémentation de référence.

`hexversion' est la version de l'implémentation sous forme hexadécimale, comme @ref{42b4,,sys.hexversion}.

`cache_tag' est la balise utilisée par le mécanisme d'importation dans les noms de fichiers des modules mis en cache.  Par convention, il devrait se composer du nom et de la version de l'implémentation, comme @code{'cpython-33'}.  Cependant, une implémentation Python peut utiliser une autre valeur si nécessaire.  @code{cache_tag} à @code{None} signifie que la mise en cache des modules doit être désactivée.

@ref{500,,sys.implementation} peut contenir d'autres attributs spécifiques à l'implémentation de Python. Ces attributs spécifiques doivent commencer par un `underscore', et ne sont pas documentés ici.  Indépendamment de son contenu, @ref{500,,sys.implementation} ne change jamais durant l'exécution de l'interpréteur, ni entre les versions d'une même implémentation.  (Il peut cependant changer entre les versions du langage Python.)  Voir la 
@geindex Python Enhancement Proposals; PEP 421
PEP 421@footnote{https://peps.python.org/pep-0421/} pour plus d'informations.


Ajouté dans la version 3.3.


@cartouche
@quotation Note 
L'addition de nouveaux attributs requis doivent passer par le processus de `PEP' classique. Voir 
@geindex Python Enhancement Proposals; PEP 421
PEP 421@footnote{https://peps.python.org/pep-0421/} pour plus d'informations.
@end quotation
@end cartouche
@end deffn

@geindex int_info (dans le module sys)
@anchor{library/sys sys int_info}@anchor{1271}
@deffn {Données} sys.int_info

Un @ref{639,,named tuple} qui contient des informations sur la représentation interne des entiers de Python.  Les attributs sont en lecture seule.

@geindex bits_per_digit (attribut sys.int_info)
@anchor{library/sys sys int_info bits_per_digit}@anchor{42b6}
@deffn {Attribut} int_info.bits_per_digit

The number of bits held in each digit.
Python integers are stored internally in base @code{2**int_info.bits_per_digit}.
@end deffn

@geindex sizeof_digit (attribut sys.int_info)
@anchor{library/sys sys int_info sizeof_digit}@anchor{42b7}
@deffn {Attribut} int_info.sizeof_digit

The size in bytes of the C type used to represent a digit.
@end deffn

@geindex default_max_str_digits (attribut sys.int_info)
@anchor{library/sys sys int_info default_max_str_digits}@anchor{2204}
@deffn {Attribut} int_info.default_max_str_digits

The default value for @ref{2205,,sys.get_int_max_str_digits()}
when it is not otherwise explicitly configured.
@end deffn

@geindex str_digits_check_threshold (attribut sys.int_info)
@anchor{library/sys sys int_info str_digits_check_threshold}@anchor{42b8}
@deffn {Attribut} int_info.str_digits_check_threshold

The minimum non-zero value for @ref{174c,,sys.set_int_max_str_digits()},
@geindex PYTHONINTMAXSTRDIGITS
@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@ref{174b,,PYTHONINTMAXSTRDIGITS}, or @ref{175,,-X int_max_str_digits}.
@end deffn


Ajouté dans la version 3.1.



Modifié dans la version 3.11: Added @ref{2204,,default_max_str_digits} and
@ref{42b8,,str_digits_check_threshold}.

@end deffn

@geindex __interactivehook__ (dans le module sys)
@anchor{library/sys sys __interactivehook__}@anchor{fb2}
@deffn {Données} sys.__interactivehook__

Lorsque cet attribut existe, sa valeur est automatiquement appelée (sans argument) par l'interpréteur lors de son démarrage en @ref{fb1,,mode interactif}.  L'appel se fait après que le fichier 
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} soit lu, afin que vous puissiez y configurer votre fonction.  @ref{fb4,,Configuré} par le module @ref{c6,,site}.

Lève un @ref{1848,,évènement d'audit} @code{cpython.run_interactivehook} avec l'objet de point d'entrée comme argument lorsqu'il est appelé au démarrage.


Ajouté dans la version 3.4.

@end deffn

@geindex intern() (dans le module sys)
@anchor{library/sys sys intern}@anchor{12b9}
@deffn {Fonction} sys.intern (string)

Ajoute `string' dans le tableau des chaînes "internées" et renvoie la chaîne internée -- qui peut être `string' elle-même ou une copie. Interner une chaîne de caractères permet de gagner un peu de performance lors de l'accès aux dictionnaires -- si les clés du dictionnaire et la clé recherchée sont internées, les comparaisons de clés (après le hachage) pourront se faire en comparant les pointeurs plutôt que caractère par caractère. Normalement, les noms utilisés dans les programmes Python sont automatiquement internés, et les dictionnaires utilisés pour stocker les attributs de modules, de classes, ou d'instances ont aussi leurs clés internées.

Interned strings are not @ref{42aa,,immortal}; you must keep a reference to the
return value of @ref{12b9,,intern()} around to benefit from it.
@end deffn

@geindex _is_gil_enabled() (dans le module sys)
@anchor{library/sys sys _is_gil_enabled}@anchor{42b9}
@deffn {Fonction} sys._is_gil_enabled ()

Return @ref{bfb,,True} if the @ref{158,,GIL} is enabled and @ref{b25,,False} if
it is disabled.


Ajouté dans la version 3.13.

@end deffn

@geindex is_finalizing() (dans le module sys)
@anchor{library/sys sys is_finalizing}@anchor{a7d}
@deffn {Fonction} sys.is_finalizing ()

Return @ref{bfb,,True} if the main Python interpreter is
@ref{14d,,shutting down}. Return @ref{b25,,False} otherwise.

See also the @ref{14c,,PythonFinalizationError} exception.


Ajouté dans la version 3.5.

@end deffn

@geindex last_exc (dans le module sys)
@anchor{library/sys sys last_exc}@anchor{4a7}
@deffn {Données} sys.last_exc

This variable is not always defined; it is set to the exception instance
when an exception is not handled and the interpreter prints an error message
and a stack traceback.  Its intended use is to allow an interactive user to
import a debugger module and engage in post-mortem debugging without having
to re-execute the command that caused the error.  (Typical use is
@code{import pdb; pdb.pm()} to enter the post-mortem debugger; see @ref{a4,,pdb}
module for more information.)


Ajouté dans la version 3.12.

@end deffn

@geindex _is_interned() (dans le module sys)
@anchor{library/sys sys _is_interned}@anchor{24d}
@deffn {Fonction} sys._is_interned (string)

Return @ref{bfb,,True} if the given string is "interned", @ref{b25,,False}
otherwise.


Ajouté dans la version 3.13.


`Particularité de l'implémentation CPython :' It is not guaranteed to exist in all implementations of Python.
@end deffn

@geindex last_type (dans le module sys)
@geindex last_value (dans le module sys)
@geindex last_traceback (dans le module sys)
@anchor{library/sys sys last_type}@anchor{4a8}
@deffn {Données} sys.last_type
@anchor{library/sys sys last_value}@anchor{4a9}
@deffnx {Données} sys.last_value
@anchor{library/sys sys last_traceback}@anchor{4aa}
@deffnx {Données} sys.last_traceback

These three variables are deprecated; use @ref{4a7,,sys.last_exc} instead.
They hold the legacy representation of @code{sys.last_exc}, as returned
from @ref{675,,exc_info()} above.
@end deffn

@geindex maxsize (dans le module sys)
@anchor{library/sys sys maxsize}@anchor{11a2}
@deffn {Données} sys.maxsize

Un entier donnant à la valeur maximale qu'une variable de type @ref{a4e,,Py_ssize_t} peut prendre.  C'est typiquement @code{2**31 - 1} sur une plateforme 32 bits et @code{2**63 - 1} sur une plateforme 64 bits.
@end deffn

@geindex maxunicode (dans le module sys)
@anchor{library/sys sys maxunicode}@anchor{1035}
@deffn {Données} sys.maxunicode

Un entier donnant la valeur du plus grand point de code Unicode, c'est-à-dire @code{1114111} (@code{0x10FFFF} en hexadécimal).


Modifié dans la version 3.3: Avant la 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/}, @code{sys.maxunicode} valait soit @code{0xFFFF} soit @code{0x10FFFF}, en fonction l'option de configuration qui spécifiait si les caractères Unicode étaient stockés en UCS-2 ou UCS-4.

@end deffn

@geindex meta_path (dans le module sys)
@anchor{library/sys sys meta_path}@anchor{d19}
@deffn {Données} sys.meta_path

A list of @ref{1059,,meta path finder} objects that have their
@ref{853,,find_spec()} methods called to see if one
of the objects can find the module to be imported. By default, it holds entries
that implement Python's default import semantics. The
@ref{853,,find_spec()} method is called with at
least the absolute name of the module being imported. If the module to be
imported is contained in a package, then the parent package's
@ref{1bfc,,__path__}
attribute is passed in as a second argument. The method returns a
@ref{1e9b,,module spec}, or @code{None} if the module cannot be found.


@subsubheading Voir aussi



@table @asis

@item @ref{859,,importlib.abc.MetaPathFinder}

La classe de base abstraite définissant l'interface des objets `finder' de @ref{d19,,meta_path}.

@item @ref{1ded,,importlib.machinery.ModuleSpec}

La classe concrète dont @ref{853,,find_spec()} devrait renvoyer des instances.
@end table



Modifié dans la version 3.4: @ref{1e9b,,Module specs} were introduced in Python 3.4, by
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}.



Modifié dans la version 3.12: Removed the fallback that looked for a @code{find_module()} method
if a @ref{d19,,meta_path} entry didn't have a
@ref{853,,find_spec()} method.

@end deffn

@geindex modules (dans le module sys)
@anchor{library/sys sys modules}@anchor{18f9}
@deffn {Données} sys.modules

This is a dictionary that maps module names to modules which have already been
loaded.  This can be manipulated to force reloading of modules and other tricks.
However, replacing the dictionary will not necessarily work as expected and
deleting essential items from the dictionary may cause Python to fail.  If
you want to iterate over this global dictionary always use
@code{sys.modules.copy()} or @code{tuple(sys.modules)} to avoid exceptions as its
size may change during iteration as a side effect of code or activity in
other threads.
@end deffn

@geindex orig_argv (dans le module sys)
@anchor{library/sys sys orig_argv}@anchor{82a}
@deffn {Données} sys.orig_argv

The list of the original command line arguments passed to the Python
executable.

The elements of @ref{82a,,sys.orig_argv} are the arguments to the Python interpreter,
while the elements of @ref{1243,,sys.argv} are the arguments to the user's program.
Arguments consumed by the interpreter itself will be present in @ref{82a,,sys.orig_argv}
and missing from @ref{1243,,sys.argv}.


Ajouté dans la version 3.10.

@end deffn

@geindex path (dans le module sys)
@anchor{library/sys sys path}@anchor{3ab}
@deffn {Données} sys.path

@geindex module;search;path

Une liste de chaînes de caractères spécifiant les chemins de recherche des modules, initialisée à partir de la variable d'environnement 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} et d'une valeur par défaut dépendante de l'installation.

By default, as initialized upon program startup, a potentially unsafe path
is prepended to @ref{3ab,,sys.path} (`before' the entries inserted as a result
of 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH}):


@itemize *

@item 
@code{python -m module} command line: prepend the current working
directory.

@item 
@code{python script.py} command line: prepend the script's directory.
If it's a symbolic link, resolve symbolic links.

@item 
@code{python -c code} and @code{python} (REPL) command lines: prepend an empty
string, which means the current working directory.
@end itemize

To not prepend this potentially unsafe path, use the @ref{58e,,-P} command
line option or the 
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} environment variable.

A program is free to modify this list for its own purposes.  Only strings
should be added to @ref{3ab,,sys.path}; all other data types are
ignored during import.


@subsubheading Voir aussi



@itemize *

@item 
Le module @ref{c6,,site} décrit comment utiliser les fichiers `.pth' pour étendre @ref{3ab,,sys.path}.
@end itemize

@end deffn

@geindex path_hooks (dans le module sys)
@anchor{library/sys sys path_hooks}@anchor{100d}
@deffn {Données} sys.path_hooks

Une liste d'appelables d'un argument, `path', pour essayer de créer un @ref{1ea3,,finder} pour ce chemin. Si un `finder' peut être créé, il doit être renvoyé par l'appelable, sinon une @ref{40f,,ImportError} doit être levée.

Précisé à l'origine dans la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}.
@end deffn

@geindex path_importer_cache (dans le module sys)
@anchor{library/sys sys path_importer_cache}@anchor{5ce}
@deffn {Données} sys.path_importer_cache

Un dictionnaire faisant office de cache pour les objets @ref{1ea3,,finder}. Les clés sont les chemins qui ont été passés à @ref{100d,,sys.path_hooks} et les valeurs sont les `finders' trouvés. Si un chemin est valide selon le système de fichiers mais qu'aucun `finder' n'est trouvé dans @ref{100d,,sys.path_hooks}, @code{None} est stocké.

Précisé à l'origine dans la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}.
@end deffn

@geindex platform (dans le module sys)
@anchor{library/sys sys platform}@anchor{a7b}
@deffn {Données} sys.platform

A string containing a platform identifier. Known values are:


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Système

@tab

Valeur pour @code{plateforme}

@item

AIX

@tab

@code{'aix'}

@item

Android

@tab

@code{'android'}

@item

Emscripten

@tab

@code{'emscripten'}

@item

iOS

@tab

@code{'ios'}

@item

Linux

@tab

@code{'linux'}

@item

macOS

@tab

@code{'darwin'}

@item

Windows

@tab

@code{'win32'}

@item

Windows/Cygwin

@tab

@code{'cygwin'}

@item

WASI

@tab

@code{'wasi'}

@end multitable


On Unix systems not listed in the table, the value is the lowercased OS name
as returned by @code{uname -s}, with the first part of the version as returned by
@code{uname -r} appended, e.g. @code{'sunos5'} or @code{'freebsd8'}, `at the time
when Python was built'.  Unless you want to test for a specific system
version, it is therefore recommended to use the following idiom:

@example
if sys.platform.startswith('freebsd'):
    # FreeBSD-specific code here...
@end example


Modifié dans la version 3.3: On Linux, @ref{a7b,,sys.platform} doesn't contain the major version anymore.
It is always @code{'linux'}, instead of @code{'linux2'} or @code{'linux3'}.



Modifié dans la version 3.8: On AIX, @ref{a7b,,sys.platform} doesn't contain the major version anymore.
It is always @code{'aix'}, instead of @code{'aix5'} or @code{'aix7'}.



Modifié dans la version 3.13: On Android, @ref{a7b,,sys.platform} now returns @code{'android'} rather than
@code{'linux'}.



@subsubheading Voir aussi


@ref{2a8a,,os.name} has a coarser granularity.  @ref{10f6,,os.uname()} gives
system-dependent version information.

Le module @ref{a9,,platform} fournit des vérifications détaillées pour l'identité du système.

@end deffn

@geindex platlibdir (dans le module sys)
@anchor{library/sys sys platlibdir}@anchor{925}
@deffn {Données} sys.platlibdir

Nom du dossier de la bibliothèque spécifique à la plateforme. Il est utilisé pour construire le chemin de vers la bibliothèque standard et les chemins vers les modules d'extensions installés.

C'est égal à @code{"lib"} sur la plupart des plateformes. Sur Fedora et SuSE, c'est égal à @code{"lib64"} sur les plateformes 64-bits qui renvoient les chemins @code{sys.path} suivants (où @code{X.Y} et la version @code{majeure.mineur} de Python) :


@itemize *

@item 
@code{/usr/lib64/pythonX.Y/} : Bibliothèque standard (comme @code{os.py} du module @ref{a0,,os})

@item 
@code{/usr/lib64/pythonX.Y/lib-dynload/} : Modules d'extension C de la bibliothèque standard (comme le module @ref{56,,errno}, le nom du fichier exact est spécifique à la plateforme)

@item 
@code{/usr/lib/pythonX.Y/site-packages/} (toujours utiliser @code{lib}, et non @ref{925,,sys.platlibdir}) : modules tiers

@item 
@code{/usr/lib64/pythonX.Y/site-packages/} : Modules d'extension C de paquets tiers
@end itemize


Ajouté dans la version 3.9.

@end deffn

@geindex prefix (dans le module sys)
@anchor{library/sys sys prefix}@anchor{3ad}
@deffn {Données} sys.prefix

A string giving the site-specific directory prefix where the platform
independent Python files are installed; on Unix, the default is
@code{/usr/local}. This can be set at build time with the @ref{1cec,,--prefix}
argument to the @code{configure} script.  See
@ref{67a,,Installation paths} for derived paths.

@cartouche
@quotation Note 
Si a @ref{4252,,environnement virtuel} est activé, cette valeur sera changée par @code{site py} pour pointer vers l'environnement virtuel. La valeur donnée au moment de la compilation de Python sera toujours disponible, dans @ref{3e6,,base_prefix}.
@end quotation
@end cartouche
@end deffn

@geindex ps1 (dans le module sys)
@geindex ps2 (dans le module sys)
@anchor{library/sys sys ps1}@anchor{1cd1}
@deffn {Données} sys.ps1
@anchor{library/sys sys ps2}@anchor{1cd2}
@deffnx {Données} sys.ps2

@geindex interpreter prompts
@geindex prompts@comma{} interpreter
@geindex >>>;interpreter prompt
@geindex ...;interpreter prompt

Chaînes spécifiant l'invite primaire et secondaire de l'interpréteur.  Celles-ci ne sont définies que si l'interpréteur est en mode interactif.  Dans ce cas, leurs valeurs initiales sont @code{'>>>'} et @code{'...'}.  Si un objet qui n'est pas une chaîne est assigné à l'une ou l'autre variable, sa méthode @ref{435,,str()} sera appelée à chaque fois que l'interpréteur se prépare à lire une nouvelle commande interactive, c'est donc utilisable pour implémenter une invite dynamique.
@end deffn

@geindex setdlopenflags() (dans le module sys)
@anchor{library/sys sys setdlopenflags}@anchor{10ff}
@deffn {Fonction} sys.setdlopenflags (n)

Set the flags used by the interpreter for @code{dlopen()} calls, such as when
the interpreter loads extension modules.  Among other things, this will enable a
lazy resolving of symbols when importing a module, if called as
@code{sys.setdlopenflags(0)}.  To share symbols across extension modules, call as
@code{sys.setdlopenflags(os.RTLD_GLOBAL)}.  Symbolic names for the flag values
can be found in the @ref{a0,,os} module (@code{RTLD_@var{xxx}} constants, e.g.
@ref{10f8,,os.RTLD_LAZY}).

@ref{1ce0,,Availability}: Unix.
@end deffn

@geindex set_int_max_str_digits() (dans le module sys)
@anchor{library/sys sys set_int_max_str_digits}@anchor{174c}
@deffn {Fonction} sys.set_int_max_str_digits (maxdigits)

Set the @ref{5df,,integer string conversion length limitation} used by this interpreter. See also
@ref{2205,,get_int_max_str_digits()}.


Ajouté dans la version 3.11.

@end deffn

@geindex setprofile() (dans le module sys)
@anchor{library/sys sys setprofile}@anchor{14b5}
@deffn {Fonction} sys.setprofile (profilefunc)

@geindex profile function
@geindex profiler

Définit la fonction de profilage du système, qui vous permet d'implémenter un profileur de code source Python en Python.  Voir le chapitre @ref{41a3,,The Python Profilers} pour plus d'informations sur le profileur Python. La fonction de profilage du système est appelée de la même façon que la fonction trace du système (voir @ref{14b6,,settrace()}), mais elle est appelée pour des évènements différents, par exemple elle n'est pas appelée à chaque ligne de code exécutée (seulement sur appel et retours, mais l'événement pour les retours est appelé même en cas d'exception). Cette fonction est locale au fil d'exécution, et il n'existe aucun moyen, du point de vue du profileur, de prendre conscience des changements de contextes entre fils d'exécution, ça n'a donc aucun sens d'utiliser cette fonction dans un contexte `multithread'. Sa valeur de retour n'est pas utilisée, elle peut simplement renvoyer @code{None}.

@cartouche
@quotation Note 
The same tracing mechanism is used for @code{setprofile()} as @ref{14b6,,settrace()}.
To trace calls with @code{setprofile()} inside a tracing function
(e.g. in a debugger breakpoint), see @ref{17c0,,call_tracing()}.
@end quotation
@end cartouche

Les fonctions de traçage doivent avoir trois arguments : `frame', `event', et `arg'. `frame' est la `stack frame' actuelle. `event' est une chaîne de caractères pouvant valoir : @code{'call'}, @code{'return'}, @code{'c_call'}, @code{'c_return'} ou @code{'c_exception'}. `arg' dépend du type de l'évènement.

Les événements ont la signification suivante :


@table @asis

@item @code{'call'}

Une fonction est appelée (ou Python entre dans un autre bloc de code). La fonction de traçage est appelée, `arg' est @code{None}.

@item @code{'return'}

La fonction (ou un autre type de bloc) est sur le point de se terminer. La fonction de traçage est appelée, `arg' est la valeur qui sera renvoyée, ou @code{None} si l'événement est causé par la levée d'une exception.

@item @code{'c_call'}

Une fonction C est sur le point d'être appelée.  C'est soit une fonction d'extension ou une fonction native.  `arg' représente la fonction C.

@item @code{'c_return'}

Une fonction C a renvoyé une valeur. `arg' représente la fonction C.

@item @code{'c_exception'}

Une fonction C a levé une exception.  `arg' représente la fonction C.
@end table

Lève un @ref{1848,,évènement d'audit} @code{sys.setprofile} sans arguments.
@end deffn

@geindex setrecursionlimit() (dans le module sys)
@anchor{library/sys sys setrecursionlimit}@anchor{4ac}
@deffn {Fonction} sys.setrecursionlimit (limit)

Définit la profondeur maximale de la pile de l'interpréteur Python à `limit'.  Cette limite empêche une récursion infinie de provoquer un débordement de la pile C et ainsi un crash de Python.

La limite haute dépend de la plate-forme.  Un utilisateur pourrait avoir besoin de remonter la limite, lorsque son programme nécessite une récursion profonde, si sa plate-forme le permet.  Cela doit être fait avec précaution, car une limite trop élevée peut conduire à un crash.

Si la nouvelle limite est plus basse que la profondeur actuelle, une @ref{d59,,RecursionError} est levée.


Modifié dans la version 3.5.1: Une @ref{d59,,RecursionError} est maintenant levée si la nouvelle limite est plus basse que la profondeur de récursion actuelle.

@end deffn

@geindex setswitchinterval() (dans le module sys)
@anchor{library/sys sys setswitchinterval}@anchor{937}
@deffn {Fonction} sys.setswitchinterval (interval)

Configure l'intervalle de bascule des fils d'exécution de l'interpréteur (en secondes). Ce nombre à virgule flottante détermine la durée idéale allouée aux fils d'exécution en cour d'exécution (durée appelée `timeslices'). Notez que la durée observée peut être plus grande, typiquement si des fonctions ou méthodes prenant beaucoup de temps sont utilisées.  Aussi, le choix du fil d'exécution prenant la main à la fin de l'intervalle revient au système d'exploitation. L'interpréteur n'a pas son propre ordonnanceur.


Ajouté dans la version 3.2.

@end deffn

@geindex settrace() (dans le module sys)
@anchor{library/sys sys settrace}@anchor{14b6}
@deffn {Fonction} sys.settrace (tracefunc)

@geindex trace function
@geindex debugger

Définit la fonction de traçage du système, qui vous permet d'implémenter un débogueur de code source Python en Python. Cette fonction est locale au fil d'exécution courant. Pour qu'un débogueur puisse gérer plusieurs fils d'exécution, il doit enregistrer sa fonction en appelant @ref{14b6,,settrace()} pour chaque fil d'exécution qu'il souhaite surveiller ou utilisez @ref{832,,threading.settrace()}.

Les fonctions de traçage doivent avoir trois arguments : `frame', `event', et `arg'. `frame' est la `stack frame' actuelle. `event' est une chaîne de caractères pouvant valoir : @code{'call'}, @code{'line'}, @code{'return'}, @code{'exception'} ou @code{'opcode'}. `arg' dépend du type de l'évènement.

La fonction de traçage est appelée (avec `event' à @code{'call'}) à chaque fois que l'interpréteur entre dans un nouveau `scope'. Elle doit renvoyer une référence à une fonction de traçage locale à utiliser pour ce `scope', ou @code{None} si le `Scope' ne doit pas être tracé.

The local trace function should return a reference to itself, or to another
function which would then be used as the local trace function for the scope.

Si une erreur se produit dans la fonction de trace, elle sera désactivée, tout comme si @code{settrace(None)} avait été appelée.

@cartouche
@quotation Note 
Tracing is disabled while calling the trace function (e.g. a function set by
@code{settrace()}). For recursive tracing see @ref{17c0,,call_tracing()}.
@end quotation
@end cartouche

Les événements ont la signification suivante :


@table @asis

@item @code{'call'}

Une fonction est appelée (un un bloc de code). La fonction de traçage globale est appelée, `arg' est @code{None}, la valeur renvoyée donne la fonction de traçage locale.

@item @code{'line'}

The interpreter is about to execute a new line of code or re-execute the
condition of a loop.  The local trace function is called; `arg' is
@code{None}; the return value specifies the new local trace function.  See
@code{Objects/lnotab_notes.txt} for a detailed explanation of how this
works.
Per-line events may be disabled for a frame by setting
@ref{bc9,,f_trace_lines} to @ref{b25,,False} on that
@ref{6ca,,frame}.

@item @code{'return'}

La fonction (ou un autre type de bloc) est sur le point de se terminer. La fonction de traçage locale est appelée, `arg' est la valeur qui sera renvoyée, ou @code{None} si l'événement est causé par la levée d'une exception. La valeur renvoyée par la fonction de traçage est ignorée.

@item @code{'exception'}

Une exception est survenue. La fonction de traçage locale est appelée, `arg' est le triplet @code{(exception, valeur, traceback)}, la valeur renvoyée spécifie la nouvelle fonction de traçage locale.

@item @code{'opcode'}

The interpreter is about to execute a new opcode (see @ref{38,,dis} for
opcode details).  The local trace function is called; `arg' is
@code{None}; the return value specifies the new local trace function.
Per-opcode events are not emitted by default: they must be explicitly
requested by setting @ref{bca,,f_trace_opcodes} to @ref{bfb,,True} on the
@ref{6ca,,frame}.
@end table

Remarquez que, comme une exception se propage au travers de toute chaîne d'appelants, un événement @code{'exception'} est généré à chaque niveau.

Pour une utilisation plus fine, il est possible de définir une fonction de traçage en assignant @code{frame.f_trace = tracefunc} explicitement, plutôt que de s'appuyer sur le fait qu'elle soit définie indirectement par la valeur de retour d'une fonction trace déjà installée. Cela est aussi demandé pour l'activation de la fonction de traçage dans le cadre, ce que @ref{14b6,,settrace()} ne fait pas. Notez que pour que cela fonctionne, une fonction globale de traçage doit avoir été installée avec @ref{14b6,,settrace()} afin d'activer le mécanisme de traçage au moment de l'exécution, mais il n'est pas nécessaire que ce soit la même fonction de traçage (Par exemple, cela pourrait être une fonction de traçage avec peu de surcharge qui retourne simplement @code{None} pour se désactiver immédiatement à chaque cadre).

Pour plus d'informations sur les objets code et objets représentant une `frame' de la pile, consultez @ref{1e6a,,Hiérarchie des types standards}.

Lève un @ref{1848,,évènement d'audit} @code{sys.settrace} sans arguments.

`Particularité de l'implémentation CPython :' La fonction @ref{14b6,,settrace()} est destinée uniquement à l'implémentation de débogueurs, de profileurs, d'outils d'analyse de couverture et d'autres outils similaires. Son comportement fait partie de l'implémentation, plutôt que de la définition du langage, et peut donc ne pas être disponible dans toutes les implémentations de Python.


Modifié dans la version 3.7: @code{'opcode'} event type added; @ref{bc9,,f_trace_lines} and
@ref{bca,,f_trace_opcodes} attributes added to frames

@end deffn

@geindex set_asyncgen_hooks() (dans le module sys)
@anchor{library/sys sys set_asyncgen_hooks}@anchor{15af}
@deffn {Fonction} sys.set_asyncgen_hooks ([firstiter] [, finalizer])

Accepte deux arguments optionnels nommés, qui sont appelables qui acceptent un @ref{42ac,,asynchronous generator iterator} comme argument. L'appelable `firsttiter' sera appelé lorsqu'un générateur asynchrone sera itéré pour la première fois, et l'appelable `finalizer' sera appelé lorsqu'un générateur asynchrone est sur le point d'être détruit.

Lève un @ref{1848,,évènement d'audit} @code{sys.set_asyncgen_hooks_firstiter} sans arguments.

Lève un @ref{1848,,événement d'audit} @code{sys.set_asyncgen_hooks_finalizer} sans arguments.

Deux événements d'audit sont levés car l'API sous-jacente consiste de deux appels, dont chacun doit lever son propre événement.


Ajouté dans la version 3.6: Voir la 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} pour plus de détails. Pour un exemple de `finalizer', voir l'implémentation de @code{asyncio.Loop.shutdown_asyncgens} dans Lib/asyncio/base_events.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/asyncio/base_events.py}


@cartouche
@quotation Note 
Cette fonction à été ajoutée à titre provisoire (voir la 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} pour plus d'informations.)
@end quotation
@end cartouche
@end deffn

@geindex set_coroutine_origin_tracking_depth() (dans le module sys)
@anchor{library/sys sys set_coroutine_origin_tracking_depth}@anchor{b7a}
@deffn {Fonction} sys.set_coroutine_origin_tracking_depth (depth)

Allows enabling or disabling coroutine origin tracking. When
enabled, the @code{cr_origin} attribute on coroutine objects will
contain a tuple of (filename, line number, function name) tuples
describing the traceback where the coroutine object was created,
with the most recent call first. When disabled, @code{cr_origin} will
be @code{None}.

Pour l'activer, passez une valeur `depth' supérieure à zéro ; cela définit le nombre de cadres d'exécution dont les informations sont capturées. Pour le désactiver, mettez `depth' à zéro.

Ce paramètre est spécifique au fil d'exécution courant.


Ajouté dans la version 3.7.


@cartouche
@quotation Note 
Cette fonction à été ajoutée à titre provisoire (Voir la 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} pour plus d'informations.)  Utilisez la uniquement à des fins de débogage.
@end quotation
@end cartouche
@end deffn

@geindex activate_stack_trampoline() (dans le module sys)
@anchor{library/sys sys activate_stack_trampoline}@anchor{459}
@deffn {Fonction} sys.activate_stack_trampoline (backend, /)

Activate the stack profiler trampoline `backend'.
The only supported backend is @code{"perf"}.

@ref{1ce0,,Availability}: Linux.


Ajouté dans la version 3.12.



@subsubheading Voir aussi



@itemize *

@item 
@ref{18d,,Python support for the Linux perf profiler}

@item 
@indicateurl{https://perf.wiki.kernel.org}
@end itemize

@end deffn

@geindex deactivate_stack_trampoline() (dans le module sys)
@anchor{library/sys sys deactivate_stack_trampoline}@anchor{45a}
@deffn {Fonction} sys.deactivate_stack_trampoline ()

Deactivate the current stack profiler trampoline backend.

If no stack profiler is activated, this function has no effect.

@ref{1ce0,,Availability}: Linux.


Ajouté dans la version 3.12.

@end deffn

@geindex is_stack_trampoline_active() (dans le module sys)
@anchor{library/sys sys is_stack_trampoline_active}@anchor{45b}
@deffn {Fonction} sys.is_stack_trampoline_active ()

Return @code{True} if a stack profiler trampoline is active.

@ref{1ce0,,Availability}: Linux.


Ajouté dans la version 3.12.

@end deffn

@geindex _enablelegacywindowsfsencoding() (dans le module sys)
@anchor{library/sys sys _enablelegacywindowsfsencoding}@anchor{2ab}
@deffn {Fonction} sys._enablelegacywindowsfsencoding ()

Changes the @ref{525,,filesystem encoding and error handler} to 'mbcs' and
'replace' respectively, for consistency with versions of Python prior to
3.6.

Équivaut à définir la variable d'environnement 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} avant de lancer Python.

See also @ref{c47,,sys.getfilesystemencoding()} and
@ref{cd4,,sys.getfilesystemencodeerrors()}.

@ref{1ce0,,Availability}: Windows.

@cartouche
@quotation Note 
Changing the filesystem encoding after Python startup is risky because
the old fsencoding or paths encoded by the old fsencoding may be cached
somewhere. Use 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} instead.
@end quotation
@end cartouche


Ajouté dans la version 3.6: Voir la 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} pour plus d'informations.



Deprecated since version 3.13, will be removed in version 3.16: Use 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} instead.

@end deffn

@geindex stdin (dans le module sys)
@geindex stdout (dans le module sys)
@geindex stderr (dans le module sys)
@anchor{library/sys sys stdin}@anchor{527}
@deffn {Données} sys.stdin
@anchor{library/sys sys stdout}@anchor{ac4}
@deffnx {Données} sys.stdout
@anchor{library/sys sys stderr}@anchor{926}
@deffnx {Données} sys.stderr

@ref{11a0,,objets fichiers} utilisés par l'interpréteur pour l'entrée standard, la sortie standard et la sortie d'erreurs :


@itemize *

@item 
@code{stdin} est utilisé pour toutes les entrées interactives (y compris les appels à @ref{12b6,,input()})

@item 
@code{stdout} est utilisé pour la sortie de @ref{f60,,print()}, des @ref{1f08,,expression} et pour les invites de @ref{12b6,,input()} ;

@item 
Les invites de l'interpréteur et ses messages d'erreur sont écrits sur @code{stderr}.
@end itemize

Ces flux sont de classiques @ref{1c14,,fichiers texte} comme ceux renvoyés par la fonction @ref{505,,open()}. Leurs paramètres sont choisis comme suit :


@itemize *

@item 
The encoding and error handling are is initialized from
@ref{39a,,PyConfig.stdio_encoding} and @ref{42ba,,PyConfig.stdio_errors}.

On Windows, UTF-8 is used for the console device.  Non-character
devices such as disk files and pipes use the system locale
encoding (i.e. the ANSI codepage).  Non-console character
devices such as NUL (i.e. where @code{isatty()} returns @code{True}) use the
value of the console input and output codepages at startup,
respectively for stdin and stdout/stderr. This defaults to the
system @ref{23f,,locale encoding} if the process is not initially attached
to a console.

Le comportement spécial de la console peut être redéfini en assignant la variable d'environnement `PYTHONLEGACYWINDOWSSTDIO' avant de démarrer Python. Dans ce cas, les pages de code de la console sont utilisées comme pour tout autre périphérique de caractères.

Sous toutes les plateformes, vous pouvez redéfinir le codage de caractères en assignant la variable d'environnement 
@geindex PYTHONIOENCODING
@geindex variable d'environnement; PYTHONIOENCODING
@ref{ff3,,PYTHONIOENCODING} avant de démarrer Python ou en utilisant la nouvelle option de ligne de commande @ref{175,,-X} @code{utf8} et la variable d'environnement 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8}. Toutefois, pour la console Windows, cela s'applique uniquement lorsque 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex variable d'environnement; PYTHONLEGACYWINDOWSSTDIO
@ref{c49,,PYTHONLEGACYWINDOWSSTDIO} est également défini.

@item 
When interactive, the @code{stdout} stream is line-buffered. Otherwise,
it is block-buffered like regular text files.  The @code{stderr} stream
is line-buffered in both cases.  You can make both streams unbuffered
by passing the @ref{1932,,-u} command-line option or setting the
@geindex PYTHONUNBUFFERED
@geindex variable d'environnement; PYTHONUNBUFFERED
@ref{1933,,PYTHONUNBUFFERED} environment variable.
@end itemize


Modifié dans la version 3.9: Le @code{stderr} non interactif est maintenant mis en mémoire-tampon ligne par ligne plutôt qu'entièrement.


@cartouche
@quotation Note 
Pour écrire ou lire des données binaires depuis ou vers les flux standards, utilisez l'objet sous-jacent @ref{1280,,buffer}. Par exemple, pour écrire des octets sur @ref{ac4,,stdout}, utilisez @code{sys.stdout.buffer.write(b'abc')}.

However, if you are writing a library (and do not control in which
context its code will be executed), be aware that the standard streams
may be replaced with file-like objects like @ref{f12,,io.StringIO} which
do not support the @code{buffer} attribute.
@end quotation
@end cartouche
@end deffn

@geindex __stdin__ (dans le module sys)
@geindex __stdout__ (dans le module sys)
@geindex __stderr__ (dans le module sys)
@anchor{library/sys sys __stdin__}@anchor{42bb}
@deffn {Données} sys.__stdin__
@anchor{library/sys sys __stdout__}@anchor{27fb}
@deffnx {Données} sys.__stdout__
@anchor{library/sys sys __stderr__}@anchor{4091}
@deffnx {Données} sys.__stderr__

Ces objets contiennent les valeurs d'origine de @code{stdin}, @code{stderr} et @code{stdout} tel que présentes au début du programme. Ils sont utilisés pendant la finalisation, et peuvent être utiles pour écrire dans le vrai flux standard, peu importe si l'objet @code{sys.std*} a été redirigé.

Ils peuvent également être utilisés pour restaurer les entrées / sorties d'origine, au cas où ils auraient été écrasés par des objets cassé, cependant la bonne façon de faire serait de sauvegarder explicitement les flux avant de les remplacer et ainsi pouvoir les restaurer.

@cartouche
@quotation Note 
Dans certaines cas, @code{stdin}, @code{stdout} et @code{stderr} ainsi que les valeurs initiales @code{__stdin__}, @code{__stdout__} et @code{__stderr__} peuvent être @code{None}. C'est typiquement le cas pour les applications graphiques sur Windows qui ne sont pas connectées à une console, ou les applications Python démarrées avec @code{pythonw}.
@end quotation
@end cartouche
@end deffn

@geindex stdlib_module_names (dans le module sys)
@anchor{library/sys sys stdlib_module_names}@anchor{82b}
@deffn {Données} sys.stdlib_module_names

A frozenset of strings containing the names of standard library modules.

It is the same on all platforms. Modules which are not available on
some platforms and modules disabled at Python build are also listed.
All module kinds are listed: pure Python, built-in, frozen and extension
modules. Test modules are excluded.

For packages, only the main package is listed: sub-packages and sub-modules
are not listed. For example, the @code{email} package is listed, but the
@code{email.mime} sub-package and the @code{email.message} sub-module are not
listed.

See also the @ref{1bed,,sys.builtin_module_names} list.


Ajouté dans la version 3.10.

@end deffn

@geindex thread_info (dans le module sys)
@anchor{library/sys sys thread_info}@anchor{1130}
@deffn {Données} sys.thread_info

Un @ref{639,,named tuple} contenant des informations sur l'implémentation des fils d'exécution.

@geindex name (attribut sys.thread_info)
@anchor{library/sys sys thread_info name}@anchor{42bc}
@deffn {Attribut} thread_info.name

The name of the thread implementation:


@itemize *

@item 
@code{"nt"}: Windows threads

@item 
@code{"pthread"}: POSIX threads

@item 
@code{"pthread-stubs"}: stub POSIX threads
(on WebAssembly platforms without threading support)

@item 
@code{"solaris"}: Solaris threads
@end itemize
@end deffn

@geindex lock (attribut sys.thread_info)
@anchor{library/sys sys thread_info lock}@anchor{42bd}
@deffn {Attribut} thread_info.lock

The name of the lock implementation:


@itemize *

@item 
@code{"semaphore"}: a lock uses a semaphore

@item 
@code{"mutex+cond"}: a lock uses a mutex and a condition variable

@item 
@code{None} si cette information n'est pas connue
@end itemize
@end deffn

@geindex version (attribut sys.thread_info)
@anchor{library/sys sys thread_info version}@anchor{42be}
@deffn {Attribut} thread_info.version

The name and version of the thread library.
It is a string, or @code{None} if this information is unknown.
@end deffn


Ajouté dans la version 3.3.

@end deffn

@geindex tracebacklimit (dans le module sys)
@anchor{library/sys sys tracebacklimit}@anchor{1562}
@deffn {Données} sys.tracebacklimit

Lorsque cette variable contient un nombre entier, elle détermine la profondeur maximum de la pile d'appels affichée lorsqu'une exception non gérée se produit. La valeur par défaut est @code{1000}, lorsque cette valeur est égale ou inférieure à @code{0}, la pile d'appels n'est pas affichée, seul seuls le type et la valeur de l'exception sont le sont.
@end deffn

@geindex unraisablehook() (dans le module sys)
@anchor{library/sys sys unraisablehook}@anchor{1f4}
@deffn {Fonction} sys.unraisablehook (unraisable, /)

Gère une exception `non levable' (`unraisable' en anglais)

Appelé lorsqu'une exception s'est produite mais qu'il n'y a aucun moyen pour Python de la gérer. Par exemple, lorsqu'un destructeur lève une exception ou durant le passage du ramasse-miettes (@ref{a28,,gc.collect()}).

Les arguments `unraisable' ont la signification suivante :


@itemize *

@item 
@code{exc_type}: Exception type.

@item 
@code{exc_value}: Exception value, can be @code{None}.

@item 
@code{exc_traceback}: Exception traceback, can be @code{None}.

@item 
@code{err_msg}: Error message, can be @code{None}.

@item 
@code{object}: Object causing the exception, can be @code{None}.
@end itemize

The default hook formats @code{err_msg} and @code{object} as:
@code{f'@{err_msg@}: @{object!r@}'}; use "Exception ignored in" error message
if @code{err_msg} is @code{None}.

@ref{1f4,,sys.unraisablehook()} peut être remplacé pour contrôler comment les exceptions `non levables' (`unraisable' en anglais) sont gérées.


@subsubheading Voir aussi


@ref{7f5,,excepthook()} which handles uncaught exceptions.


@cartouche
@quotation Avertissement 
Storing @code{exc_value} using a custom hook can create a reference cycle.
It should be cleared explicitly to break the reference cycle when the
exception is no longer needed.

Storing @code{object} using a custom hook can resurrect it if it is set to an
object which is being finalized. Avoid storing @code{object} after the custom
hook completes to avoid resurrecting objects.
@end quotation
@end cartouche


Raise an auditing event @code{sys.unraisablehook} with arguments
`hook', `unraisable' when an exception that cannot be handled occurs.
The `unraisable' object is the same as what will be passed to the hook.
If no hook has been set, `hook' may be @code{None}.



Ajouté dans la version 3.8.

@end deffn

@geindex version (dans le module sys)
@anchor{library/sys sys version}@anchor{177}
@deffn {Données} sys.version

Une chaîne contenant le numéro de version de l'interpréteur Python, ainsi que d'autres informations comme le numéro de compilation et le compilateur utilisé. Cette chaîne est affichée lorsque l'interpréteur est démarré en mode interactif. N'essayez pas d'en extraire des informations de version, utilisez plutôt @ref{68b,,version_info} et les fonctions fournies par le module @ref{a9,,platform}.
@end deffn

@geindex api_version (dans le module sys)
@anchor{library/sys sys api_version}@anchor{42bf}
@deffn {Données} sys.api_version

La version de l'API C pour cet interpréteur.  Les développeurs peuvent trouver cette information utile en déboguant des conflits de versions entre Python et des modules d'extension.
@end deffn

@geindex version_info (dans le module sys)
@anchor{library/sys sys version_info}@anchor{68b}
@deffn {Données} sys.version_info

Un quintuplet contenant les composants du numéro de version : `major', `minor', `micro', `releaselevel' et `serial'.  Toutes les valeurs sauf `releaselevel' sont des nombres entiers. `releaselevel' peut valoir @code{'alpha'}, @code{'beta'}, @code{'candidate'}, ou @code{'final'}. La valeur de @code{version_info} pour Python 2.0 est @code{(2, 0, 0, 'final', 0)}. Ces attributs sont aussi accessibles par leur nom, ainsi @code{sys.version_info[0]} est équivalent à @code{sys.version_info.major}, et ainsi de suite.


Modifié dans la version 3.1: Ajout des attributs nommés.

@end deffn

@geindex warnoptions (dans le module sys)
@anchor{library/sys sys warnoptions}@anchor{3a7}
@deffn {Données} sys.warnoptions

C'est une spécificité de l'implémentation de la gestion des avertissements. Ne modifiez pas cette valeur.  Reportez-vous au module @ref{111,,warnings} pour plus d'informations sur le gestionnaire d'avertissements.
@end deffn

@geindex winver (dans le module sys)
@anchor{library/sys sys winver}@anchor{42c0}
@deffn {Données} sys.winver

The version number used to form registry keys on Windows platforms. This is
stored as string resource 1000 in the Python DLL.  The value is normally the
major and minor versions of the running Python interpreter.  It is provided in the @ref{d8,,sys}
module for informational purposes; modifying this value has no effect on the
registry keys used by Python.

@ref{1ce0,,Availability}: Windows.
@end deffn


@deffn {Données} sys.monitoring

Namespace containing functions and constants for register callbacks
and controlling monitoring events.
See  @ref{d9,,sys.monitoring} for details.
@end deffn

@geindex _xoptions (dans le module sys)
@anchor{library/sys sys _xoptions}@anchor{1ccb}
@deffn {Données} sys._xoptions

Un dictionnaire des différentes options spécifiques à l'implémentation passés en ligne de commande via l'option @ref{175,,-X}.  Aux noms des options correspondent soit leur valeur, si elle est donnée explicitement, soit à @ref{bfb,,True}. Exemple :

@example
$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
@{'a': 'b', 'c': True@}
@end example

`Particularité de l'implémentation CPython :' C'est un moyen spécifique à CPython pour accéder aux options passées via l'option @ref{175,,-X}.  D'autres implémentations pourraient les exposer par d'autres moyens, ou pas du tout.


Ajouté dans la version 3.2.

@end deffn

@subsubheading Citations


@anchor{library/sys c99}@anchor{429b}@w{(C99)} 
ISO/IEC 9899:1999.  "Programming languages -- C."  A public draft of this standard is available at @indicateurl{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf}.

@node sys monitoring --- Execution event monitoring,sysconfig --- Provide access to Python's configuration information,sys --- System-specific parameters and functions,Environnement d'exécution Python
@anchor{library/sys monitoring doc}@anchor{42c1}@anchor{library/sys monitoring module-sys monitoring}@anchor{d9}@anchor{library/sys monitoring sys-monitoring-execution-event-monitoring}@anchor{42c2}
@subsection @code{sys.monitoring} --- Execution event monitoring


@geindex module; sys.monitoring


Ajouté dans la version 3.12.



__________________________________________________________________


@cartouche
@quotation Note 
@ref{d9,,sys.monitoring} is a namespace within the @ref{d8,,sys} module,
not an independent module, so there is no need to
@code{import sys.monitoring}, simply @code{import sys} and then use
@code{sys.monitoring}.
@end quotation
@end cartouche

This namespace provides access to the functions and constants necessary to
activate and control event monitoring.

As programs execute, events occur that might be of interest to tools that
monitor execution. The @ref{d9,,sys.monitoring} namespace provides means to
receive callbacks when events of interest occur.

The monitoring API consists of three components:


@itemize *

@item 
@ref{42c3,,Tool identifiers}

@item 
@ref{42c4,,Events}

@item 
@ref{42c5,,Callbacks}
@end itemize

@menu
* Tool identifiers:: 
* Events:: 
* Turning events on and off:: 
* Registering callback functions:: 

@end menu

@node Tool identifiers,Events,,sys monitoring --- Execution event monitoring
@anchor{library/sys monitoring tool-identifiers}@anchor{42c3}
@subsubsection Tool identifiers


A tool identifier is an integer and the associated name.
Tool identifiers are used to discourage tools from interfering with each
other and to allow multiple tools to operate at the same time.
Currently tools are completely independent and cannot be used to
monitor each other. This restriction may be lifted in the future.

Before registering or activating events, a tool should choose an identifier.
Identifiers are integers in the range 0 to 5 inclusive.

@menu
* Registering and using tools:: 

@end menu

@node Registering and using tools,,,Tool identifiers
@anchor{library/sys monitoring registering-and-using-tools}@anchor{42c6}
@subsubsection Registering and using tools


@geindex use_tool_id() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring use_tool_id}@anchor{42c7}
@deffn {Fonction} sys.monitoring.use_tool_id (tool_id: int, name: str, /) -> None

Must be called before `tool_id' can be used.
`tool_id' must be in the range 0 to 5 inclusive.
Raises a @ref{1ff,,ValueError} if `tool_id' is in use.
@end deffn

@geindex free_tool_id() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring free_tool_id}@anchor{42c8}
@deffn {Fonction} sys.monitoring.free_tool_id (tool_id: int, /) -> None

Should be called once a tool no longer requires `tool_id'.
@end deffn

@cartouche
@quotation Note 
@ref{42c8,,free_tool_id()} will not disable global or local events associated
with `tool_id', nor will it unregister any callback functions. This
function is only intended to be used to notify the VM that the
particular `tool_id' is no longer in use.
@end quotation
@end cartouche

@geindex get_tool() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring get_tool}@anchor{42c9}
@deffn {Fonction} sys.monitoring.get_tool (tool_id: int, /) -> str | None

Returns the name of the tool if `tool_id' is in use,
otherwise it returns @code{None}.
`tool_id' must be in the range 0 to 5 inclusive.
@end deffn

All IDs are treated the same by the VM with regard to events, but the
following IDs are pre-defined to make co-operation of tools easier:

@example
sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5
@end example

@node Events,Turning events on and off,Tool identifiers,sys monitoring --- Execution event monitoring
@anchor{library/sys monitoring events}@anchor{42c4}
@subsubsection Events


The following events are supported:

@geindex BRANCH (monitoring event)
@anchor{library/sys monitoring monitoring-event-BRANCH}@anchor{42ca}
@deffn {monitoring-event} sys.monitoring.events.BRANCH

A conditional branch is taken (or not).
@end deffn

@geindex CALL (monitoring event)
@anchor{library/sys monitoring monitoring-event-CALL}@anchor{15cf}
@deffn {monitoring-event} sys.monitoring.events.CALL

A call in Python code (event occurs before the call).
@end deffn

@geindex C_RAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-C_RAISE}@anchor{42cb}
@deffn {monitoring-event} sys.monitoring.events.C_RAISE

An exception raised from any callable, except for Python functions (event occurs after the exit).
@end deffn

@geindex C_RETURN (monitoring event)
@anchor{library/sys monitoring monitoring-event-C_RETURN}@anchor{42cc}
@deffn {monitoring-event} sys.monitoring.events.C_RETURN

Return from any callable, except for Python functions (event occurs after the return).
@end deffn

@geindex EXCEPTION_HANDLED (monitoring event)
@anchor{library/sys monitoring monitoring-event-EXCEPTION_HANDLED}@anchor{42cd}
@deffn {monitoring-event} sys.monitoring.events.EXCEPTION_HANDLED

An exception is handled.
@end deffn

@geindex INSTRUCTION (monitoring event)
@anchor{library/sys monitoring monitoring-event-INSTRUCTION}@anchor{42ce}
@deffn {monitoring-event} sys.monitoring.events.INSTRUCTION

A VM instruction is about to be executed.
@end deffn

@geindex JUMP (monitoring event)
@anchor{library/sys monitoring monitoring-event-JUMP}@anchor{42cf}
@deffn {monitoring-event} sys.monitoring.events.JUMP

An unconditional jump in the control flow graph is made.
@end deffn

@geindex LINE (monitoring event)
@anchor{library/sys monitoring monitoring-event-LINE}@anchor{42d0}
@deffn {monitoring-event} sys.monitoring.events.LINE

An instruction is about to be executed that has a different line number from the preceding instruction.
@end deffn

@geindex PY_RESUME (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_RESUME}@anchor{42d1}
@deffn {monitoring-event} sys.monitoring.events.PY_RESUME

Resumption of a Python function (for generator and coroutine functions), except for @code{throw()} calls.
@end deffn

@geindex PY_RETURN (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_RETURN}@anchor{42d2}
@deffn {monitoring-event} sys.monitoring.events.PY_RETURN

Return from a Python function (occurs immediately before the return, the callee's frame will be on the stack).
@end deffn

@geindex PY_START (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_START}@anchor{42d3}
@deffn {monitoring-event} sys.monitoring.events.PY_START

Start of a Python function (occurs immediately after the call, the callee's frame will be on the stack)
@end deffn

@geindex PY_THROW (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_THROW}@anchor{42d4}
@deffn {monitoring-event} sys.monitoring.events.PY_THROW

A Python function is resumed by a @code{throw()} call.
@end deffn

@geindex PY_UNWIND (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_UNWIND}@anchor{42d5}
@deffn {monitoring-event} sys.monitoring.events.PY_UNWIND

Exit from a Python function during exception unwinding.
@end deffn

@geindex PY_YIELD (monitoring event)
@anchor{library/sys monitoring monitoring-event-PY_YIELD}@anchor{42d6}
@deffn {monitoring-event} sys.monitoring.events.PY_YIELD

Yield from a Python function (occurs immediately before the yield, the callee's frame will be on the stack).
@end deffn

@geindex RAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-RAISE}@anchor{1577}
@deffn {monitoring-event} sys.monitoring.events.RAISE

An exception is raised, except those that cause a @ref{42d7,,STOP_ITERATION} event.
@end deffn

@geindex RERAISE (monitoring event)
@anchor{library/sys monitoring monitoring-event-RERAISE}@anchor{42d8}
@deffn {monitoring-event} sys.monitoring.events.RERAISE

An exception is re-raised, for example at the end of a @ref{9b8,,finally} block.
@end deffn

@geindex STOP_ITERATION (monitoring event)
@anchor{library/sys monitoring monitoring-event-STOP_ITERATION}@anchor{42d7}
@deffn {monitoring-event} sys.monitoring.events.STOP_ITERATION

An artificial @ref{be8,,StopIteration} is raised; see @ref{42d9,,the STOP_ITERATION event}.
@end deffn

More events may be added in the future.

These events are attributes of the @code{sys.monitoring.events} namespace.
Each event is represented as a power-of-2 integer constant.
To define a set of events, simply bitwise or the individual events together.
For example, to specify both @ref{42d2,,PY_RETURN} and @ref{42d3,,PY_START}
events, use the expression @code{PY_RETURN | PY_START}.

@geindex NO_EVENTS (monitoring event)
@anchor{library/sys monitoring monitoring-event-NO_EVENTS}@anchor{42da}
@deffn {monitoring-event} sys.monitoring.events.NO_EVENTS

An alias for @code{0} so users can do explicit comparisons like:

@example
if get_events(DEBUGGER_ID) == NO_EVENTS:
    ...
@end example
@end deffn

Events are divided into three groups:

@menu
* Local events:: 
* Ancillary events:: 
* Other events:: 
* The STOP_ITERATION event:: 

@end menu

@node Local events,Ancillary events,,Events
@anchor{library/sys monitoring local-events}@anchor{42db}
@subsubsection Local events


Local events are associated with normal execution of the program and happen
at clearly defined locations. All local events can be disabled.
The local events are:


@itemize *

@item 
@ref{42d3,,PY_START}

@item 
@ref{42d1,,PY_RESUME}

@item 
@ref{42d2,,PY_RETURN}

@item 
@ref{42d6,,PY_YIELD}

@item 
@ref{15cf,,CALL}

@item 
@ref{42d0,,LINE}

@item 
@ref{42ce,,INSTRUCTION}

@item 
@ref{42cf,,JUMP}

@item 
@ref{42ca,,BRANCH}

@item 
@ref{42d7,,STOP_ITERATION}
@end itemize

@node Ancillary events,Other events,Local events,Events
@anchor{library/sys monitoring ancillary-events}@anchor{42dc}
@subsubsection Ancillary events


Ancillary events can be monitored like other events, but are controlled
by another event:


@itemize *

@item 
@ref{42cb,,C_RAISE}

@item 
@ref{42cc,,C_RETURN}
@end itemize

The @ref{42cc,,C_RETURN} and @ref{42cb,,C_RAISE} events
are controlled by the @ref{15cf,,CALL} event.
@ref{42cc,,C_RETURN} and @ref{42cb,,C_RAISE} events will only be seen if the
corresponding @ref{15cf,,CALL} event is being monitored.

@node Other events,The STOP_ITERATION event,Ancillary events,Events
@anchor{library/sys monitoring other-events}@anchor{42dd}
@subsubsection Other events


Other events are not necessarily tied to a specific location in the
program and cannot be individually disabled.

The other events that can be monitored are:


@itemize *

@item 
@ref{42d4,,PY_THROW}

@item 
@ref{42d5,,PY_UNWIND}

@item 
@ref{1577,,RAISE}

@item 
@ref{42cd,,EXCEPTION_HANDLED}
@end itemize

@node The STOP_ITERATION event,,Other events,Events
@anchor{library/sys monitoring the-stop-iteration-event}@anchor{42d9}
@subsubsection The STOP_ITERATION event


@geindex Python Enhancement Proposals; PEP 380#use-of-stopiteration-to-return-values
PEP 380@footnote{https://peps.python.org/pep-0380/#use-of-stopiteration-to-return-values}
specifies that a @ref{be8,,StopIteration} exception is raised when returning a value
from a generator or coroutine. However, this is a very inefficient way to
return a value, so some Python implementations, notably CPython 3.12+, do not
raise an exception unless it would be visible to other code.

To allow tools to monitor for real exceptions without slowing down generators
and coroutines, the @ref{42d7,,STOP_ITERATION} event is provided.
@ref{42d7,,STOP_ITERATION} can be locally disabled, unlike @ref{1577,,RAISE}.

@node Turning events on and off,Registering callback functions,Events,sys monitoring --- Execution event monitoring
@anchor{library/sys monitoring turning-events-on-and-off}@anchor{42de}
@subsubsection Turning events on and off


In order to monitor an event, it must be turned on and a corresponding callback
must be registered.
Events can be turned on or off by setting the events either globally or
for a particular code object.

@menu
* Setting events globally:: 
* Per code object events:: 
* Disabling events:: 

@end menu

@node Setting events globally,Per code object events,,Turning events on and off
@anchor{library/sys monitoring setting-events-globally}@anchor{42df}
@subsubsection Setting events globally


Events can be controlled globally by modifying the set of events being monitored.

@geindex get_events() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring get_events}@anchor{42e0}
@deffn {Fonction} sys.monitoring.get_events (tool_id: int, /) -> int

Returns the @code{int} representing all the active events.
@end deffn

@geindex set_events() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring set_events}@anchor{42e1}
@deffn {Fonction} sys.monitoring.set_events (tool_id: int, event_set: int, /) -> None

Activates all events which are set in `event_set'.
Raises a @ref{1ff,,ValueError} if `tool_id' is not in use.
@end deffn

No events are active by default.

@node Per code object events,Disabling events,Setting events globally,Turning events on and off
@anchor{library/sys monitoring per-code-object-events}@anchor{42e2}
@subsubsection Per code object events


Events can also be controlled on a per code object basis. The functions
defined below which accept a @ref{2dd,,types.CodeType} should be prepared
to accept a look-alike object from functions which are not defined
in Python (see @ref{15b,,Monitoring C API}).

@geindex get_local_events() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring get_local_events}@anchor{42e3}
@deffn {Fonction} sys.monitoring.get_local_events (tool_id: int, code: CodeType, /) -> int

Returns all the local events for `code'
@end deffn

@geindex set_local_events() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring set_local_events}@anchor{42e4}
@deffn {Fonction} sys.monitoring.set_local_events (tool_id: int, code: CodeType, event_set: int, /) -> None

Activates all the local events for `code' which are set in `event_set'.
Raises a @ref{1ff,,ValueError} if `tool_id' is not in use.
@end deffn

Local events add to global events, but do not mask them.
In other words, all global events will trigger for a code object,
regardless of the local events.

@node Disabling events,,Per code object events,Turning events on and off
@anchor{library/sys monitoring disabling-events}@anchor{42e5}
@subsubsection Disabling events


@geindex DISABLE (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring DISABLE}@anchor{42e6}
@deffn {Données} sys.monitoring.DISABLE

A special value that can be returned from a callback function to disable
events for the current code location.
@end deffn

Local events can be disabled for a specific code location by returning
@ref{42e6,,sys.monitoring.DISABLE} from a callback function. This does not change
which events are set, or any other code locations for the same event.

Disabling events for specific locations is very important for high
performance monitoring. For example, a program can be run under a
debugger with no overhead if the debugger disables all monitoring
except for a few breakpoints.

@geindex restart_events() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring restart_events}@anchor{42e7}
@deffn {Fonction} sys.monitoring.restart_events () -> None

Enable all the events that were disabled by @ref{42e6,,sys.monitoring.DISABLE}
for all tools.
@end deffn

@node Registering callback functions,,Turning events on and off,sys monitoring --- Execution event monitoring
@anchor{library/sys monitoring callbacks}@anchor{42c5}@anchor{library/sys monitoring registering-callback-functions}@anchor{42e8}
@subsubsection Registering callback functions


To register a callable for events call

@geindex register_callback() (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring register_callback}@anchor{42e9}
@deffn {Fonction} sys.monitoring.register_callback (tool_id: int, event: int, func: Callable | None, /) -> Callable | None

Registers the callable `func' for the `event' with the given `tool_id'

If another callback was registered for the given `tool_id' and `event',
it is unregistered and returned.
Otherwise @ref{42e9,,register_callback()} returns @code{None}.
@end deffn

Functions can be unregistered by calling
@code{sys.monitoring.register_callback(tool_id, event, None)}.

Callback functions can be registered and unregistered at any time.

Registering or unregistering a callback function will generate a @ref{153f,,sys.audit()} event.

@menu
* Callback function arguments:: 

@end menu

@node Callback function arguments,,,Registering callback functions
@anchor{library/sys monitoring callback-function-arguments}@anchor{42ea}
@subsubsection Callback function arguments


@geindex MISSING (dans le module sys.monitoring)
@anchor{library/sys monitoring sys monitoring MISSING}@anchor{42eb}
@deffn {Données} sys.monitoring.MISSING

A special value that is passed to a callback function to indicate
that there are no arguments to the call.
@end deffn

When an active event occurs, the registered callback function is called.
Different events will provide the callback function with different arguments, as follows:


@itemize *

@item 
@ref{42d3,,PY_START} and @ref{42d1,,PY_RESUME}:

@example
func(code: CodeType, instruction_offset: int) -> DISABLE | Any
@end example

@item 
@ref{42d2,,PY_RETURN} and @ref{42d6,,PY_YIELD}:

@example
func(code: CodeType, instruction_offset: int, retval: object) -> DISABLE | Any
@end example

@item 
@ref{15cf,,CALL}, @ref{42cb,,C_RAISE} and @ref{42cc,,C_RETURN}:

@example
func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any
@end example

If there are no arguments, `arg0' is set to @ref{42eb,,sys.monitoring.MISSING}.

@item 
@ref{1577,,RAISE}, @ref{42d8,,RERAISE}, @ref{42cd,,EXCEPTION_HANDLED},
@ref{42d5,,PY_UNWIND}, @ref{42d4,,PY_THROW} and @ref{42d7,,STOP_ITERATION}:

@example
func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any
@end example

@item 
@ref{42d0,,LINE}:

@example
func(code: CodeType, line_number: int) -> DISABLE | Any
@end example

@item 
@ref{42ca,,BRANCH} and @ref{42cf,,JUMP}:

@example
func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any
@end example

Note that the `destination_offset' is where the code will next execute.
For an untaken branch this will be the offset of the instruction following
the branch.

@item 
@ref{42ce,,INSTRUCTION}:

@example
func(code: CodeType, instruction_offset: int) -> DISABLE | Any
@end example
@end itemize

@node sysconfig --- Provide access to Python's configuration information,builtins --- Built-in objects,sys monitoring --- Execution event monitoring,Environnement d'exécution Python
@anchor{library/sysconfig doc}@anchor{42ec}@anchor{library/sysconfig module-sysconfig}@anchor{da}@anchor{library/sysconfig sysconfig-provide-access-to-python-s-configuration-information}@anchor{42ed}
@subsection @code{sysconfig} --- Provide access to Python's configuration information


@geindex module; sysconfig


Ajouté dans la version 3.2.


`Source code:' Lib/sysconfig@footnote{https://github.com/python/cpython/tree/3.13/Lib/sysconfig}

@geindex configuration information


__________________________________________________________________


The @ref{da,,sysconfig} module provides access to Python's configuration
information like the list of installation paths and the configuration variables
relevant for the current platform.

@menu
* Configuration variables:: 
* Installation paths:: 
* User scheme:: 
* Home scheme:: 
* Prefix scheme:: 
* Installation path functions:: 
* Autres fonctions: Autres fonctions<3>. 
* Using sysconfig as a script:: 

@end menu

@node Configuration variables,Installation paths,,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig configuration-variables}@anchor{42ee}
@subsubsection Configuration variables


A Python distribution contains a @code{Makefile} and a @code{pyconfig.h}
header file that are necessary to build both the Python binary itself and
third-party C extensions compiled using @code{setuptools}.

@ref{da,,sysconfig} puts all variables found in these files in a dictionary that
can be accessed using @ref{1015,,get_config_vars()} or @ref{1014,,get_config_var()}.

Notice that on Windows, it's a much smaller set.

@geindex get_config_vars() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_config_vars}@anchor{1015}
@deffn {Fonction} sysconfig.get_config_vars (*args)

With no arguments, return a dictionary of all configuration variables
relevant for the current platform.

With arguments, return a list of values that result from looking up each
argument in the configuration variable dictionary.

For each argument, if the value is not found, return @code{None}.
@end deffn

@geindex get_config_var() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_config_var}@anchor{1014}
@deffn {Fonction} sysconfig.get_config_var (name)

Return the value of a single variable `name'. Equivalent to
@code{get_config_vars().get(name)}.

If `name' is not found, return @code{None}.
@end deffn

Example of usage:

@example
>>> import sysconfig
>>> sysconfig.get_config_var('Py_ENABLE_SHARED')
0
>>> sysconfig.get_config_var('LIBDIR')
'/usr/local/lib'
>>> sysconfig.get_config_vars('AR', 'CXX')
['ar', 'g++']
@end example

@node Installation paths,User scheme,Configuration variables,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig id1}@anchor{42ef}@anchor{library/sysconfig installation-paths}@anchor{67a}
@subsubsection Installation paths


Python uses an installation scheme that differs depending on the platform and on
the installation options.  These schemes are stored in @ref{da,,sysconfig} under
unique identifiers based on the value returned by @ref{2a8a,,os.name}.
The schemes are used by package installers to determine where to copy files to.

Python currently supports nine schemes:


@itemize -

@item 
`posix_prefix': scheme for POSIX platforms like Linux or macOS.  This is
the default scheme used when Python or a component is installed.

@item 
`posix_home': scheme for POSIX platforms, when the `home' option is used.
This scheme defines paths located under a specific home prefix.

@item 
`posix_user': scheme for POSIX platforms, when the `user' option is used.
This scheme defines paths located under the user's home directory
(@ref{12fa,,site.USER_BASE}).

@item 
`posix_venv': scheme for @ref{110,,Python virtual environments} on POSIX
platforms; by default it is the same as `posix_prefix'.

@item 
`nt': scheme for Windows.
This is the default scheme used when Python or a component is installed.

@item 
`nt_user': scheme for Windows, when the `user' option is used.

@item 
`nt_venv': scheme for @ref{110,,Python virtual environments} on Windows;
by default it is the same as `nt'.

@item 
`venv': a scheme with values from either `posix_venv' or `nt_venv' depending
on the platform Python runs on.

@item 
`osx_framework_user': scheme for macOS, when the `user' option is used.
@end itemize

Each scheme is itself composed of a series of paths and each path has a unique
identifier.  Python currently uses eight paths:


@itemize -

@item 
`stdlib': directory containing the standard Python library files that are not
platform-specific.

@item 
`platstdlib': directory containing the standard Python library files that are
platform-specific.

@item 
`platlib': directory for site-specific, platform-specific files.

@item 
`purelib': directory for site-specific, non-platform-specific files ('pure' Python).

@item 
`include': directory for non-platform-specific header files for
the Python C-API.

@item 
`platinclude': directory for platform-specific header files for
the Python C-API.

@item 
`scripts': directory for script files.

@item 
`data': directory for data files.
@end itemize

@node User scheme,Home scheme,Installation paths,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig sysconfig-user-scheme}@anchor{1cd3}@anchor{library/sysconfig user-scheme}@anchor{42f0}
@subsubsection User scheme


This scheme is designed to be the most convenient solution for users that don't
have write permission to the global site-packages directory or don't want to
install into it.

Files will be installed into subdirectories of @ref{12fa,,site.USER_BASE} (written
as @code{`userbase'} hereafter).  This scheme installs pure Python modules and
extension modules in the same location (also known as @ref{1cc1,,site.USER_SITE}).

@menu
* posix_user:: 
* nt_user:: 
* osx_framework_user:: 

@end menu

@node posix_user,nt_user,,User scheme
@anchor{library/sysconfig posix-user}@anchor{42f1}
@subsubsection @code{posix_user}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Dossier d'installation

@item

`stdlib'

@tab

@code{`userbase'/lib/python`X.Y'}

@item

`platstdlib'

@tab

@code{`userbase'/lib/python`X.Y'}

@item

`platlib'

@tab

@code{`userbase'/lib/python`X.Y'/site-packages}

@item

`purelib'

@tab

@code{`userbase'/lib/python`X.Y'/site-packages}

@item

`include'

@tab

@code{`userbase'/include/python`X.Y'}

@item

`scripts'

@tab

@code{`userbase'/bin}

@item

`données'

@tab

@code{`userbase'}

@end multitable


@node nt_user,osx_framework_user,posix_user,User scheme
@anchor{library/sysconfig nt-user}@anchor{42f2}
@subsubsection @code{nt_user}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Dossier d'installation

@item

`stdlib'

@tab

@code{`userbase'\Python`XY'}

@item

`platstdlib'

@tab

@code{`userbase'\Python`XY'}

@item

`platlib'

@tab

@code{`userbase'\Python`XY'\site-packages}

@item

`purelib'

@tab

@code{`userbase'\Python`XY'\site-packages}

@item

`include'

@tab

@code{`userbase'\Python`XY'\Include}

@item

`scripts'

@tab

@code{`userbase'\Python`XY'\Scripts}

@item

`données'

@tab

@code{`userbase'}

@end multitable


@node osx_framework_user,,nt_user,User scheme
@anchor{library/sysconfig osx-framework-user}@anchor{42f3}
@subsubsection @code{osx_framework_user}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Dossier d'installation

@item

`stdlib'

@tab

@code{`userbase'/lib/python}

@item

`platstdlib'

@tab

@code{`userbase'/lib/python}

@item

`platlib'

@tab

@code{`userbase'/lib/python/site-packages}

@item

`purelib'

@tab

@code{`userbase'/lib/python/site-packages}

@item

`include'

@tab

@code{`userbase'/include/python`X.Y'}

@item

`scripts'

@tab

@code{`userbase'/bin}

@item

`données'

@tab

@code{`userbase'}

@end multitable


@node Home scheme,Prefix scheme,User scheme,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig home-scheme}@anchor{42f4}@anchor{library/sysconfig sysconfig-home-scheme}@anchor{42f5}
@subsubsection Home scheme


L’idée derrière le « schéma home » est que vous compilez et maintenez un espace personnel de modules Python. Le nom de ce schéma vient de l’idée du dossier « home » sur Unix, vu qu’il n’est pas rare pour un utilisateur UNIX d'agencer son dossier `home' avec la même disposition que @code{/usr/} ou @code{/usr/local/}. Ce schéma peut être utilisé par n’importe qui, quel que soit le système d’exploitation.

@menu
* posix_home:: 

@end menu

@node posix_home,,,Home scheme
@anchor{library/sysconfig posix-home}@anchor{42f6}
@subsubsection @code{posix_home}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Dossier d'installation

@item

`stdlib'

@tab

@code{`home'/lib/python}

@item

`platstdlib'

@tab

@code{`home'/lib/python}

@item

`platlib'

@tab

@code{`home'/lib/python}

@item

`purelib'

@tab

@code{`home'/lib/python}

@item

`include'

@tab

@code{`home'/include/python}

@item

`platinclude'

@tab

@code{`home'/include/python}

@item

`scripts'

@tab

@code{`home'/bin}

@item

`données'

@tab

@code{`home'}

@end multitable


@node Prefix scheme,Installation path functions,Home scheme,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig prefix-scheme}@anchor{42f7}@anchor{library/sysconfig sysconfig-prefix-scheme}@anchor{42f8}
@subsubsection Prefix scheme


Le schéma de préfixe est utile quand vous voulez une installation de Python pour faire la compilation/l’installation (c.-à-d. exécuter le script `setup'), mais utiliser les modules tiers d’une installation Python différente (ou quelque chose qui ressemble à une installation Python différente). Si cela vous semble inhabituel, ça l’est — c’est pourquoi les schémas `user' et `home' viennent avant. Cependant, il y a au moins deux cas connus où le schéma `prefix' est utile.

First, consider that many Linux distributions put Python in @code{/usr}, rather
than the more traditional @code{/usr/local}.  This is entirely appropriate,
since in those cases Python is part of "the system" rather than a local add-on.
However, if you are installing Python modules from source, you probably want
them to go in @code{/usr/local/lib/python2.`X'} rather than
@code{/usr/lib/python2.`X'}.

Another possibility is a network filesystem where the name used to write to a
remote directory is different from the name used to read it: for example, the
Python interpreter accessed as @code{/usr/local/bin/python} might search for
modules in @code{/usr/local/lib/python2.`X'}, but those modules would have to
be installed to, say, @code{/mnt/`@@server'/export/lib/python2.`X'}.

@menu
* posix_prefix:: 
* nt:: 

@end menu

@node posix_prefix,nt,,Prefix scheme
@anchor{library/sysconfig posix-prefix}@anchor{42f9}
@subsubsection @code{posix_prefix}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Dossier d'installation

@item

`stdlib'

@tab

@code{`prefix'/lib/python`X.Y'}

@item

`platstdlib'

@tab

@code{`prefix'/lib/python`X.Y'}

@item

`platlib'

@tab

@code{`prefix'/lib/python`X.Y'/site-packages}

@item

`purelib'

@tab

@code{`prefix'/lib/python`X.Y'/site-packages}

@item

`include'

@tab

@code{`prefix'/include/python`X.Y'}

@item

`platinclude'

@tab

@code{`prefix'/include/python`X.Y'}

@item

`scripts'

@tab

@code{`prefix'/bin}

@item

`données'

@tab

@code{`prefix'}

@end multitable


@node nt,,posix_prefix,Prefix scheme
@anchor{library/sysconfig nt}@anchor{42fa}
@subsubsection @code{nt}



@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Path

@tab

Dossier d'installation

@item

`stdlib'

@tab

@code{`prefix'\Lib}

@item

`platstdlib'

@tab

@code{`prefix'\Lib}

@item

`platlib'

@tab

@code{`prefix'\Lib\site-packages}

@item

`purelib'

@tab

@code{`prefix'\Lib\site-packages}

@item

`include'

@tab

@code{`prefix'\Include}

@item

`platinclude'

@tab

@code{`prefix'\Include}

@item

`scripts'

@tab

@code{`prefix'\Scripts}

@item

`données'

@tab

@code{`prefix'}

@end multitable


@node Installation path functions,Autres fonctions<3>,Prefix scheme,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig installation-path-functions}@anchor{42fb}
@subsubsection Installation path functions


@ref{da,,sysconfig} provides some functions to determine these installation paths.

@geindex get_scheme_names() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_scheme_names}@anchor{42fc}
@deffn {Fonction} sysconfig.get_scheme_names ()

Return a tuple containing all schemes currently supported in
@ref{da,,sysconfig}.
@end deffn

@geindex get_default_scheme() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_default_scheme}@anchor{17b1}
@deffn {Fonction} sysconfig.get_default_scheme ()

Return the default scheme name for the current platform.


Ajouté dans la version 3.10: This function was previously named @code{_get_default_scheme()} and
considered an implementation detail.



Modifié dans la version 3.11: When Python runs from a virtual environment,
the `venv' scheme is returned.

@end deffn

@geindex get_preferred_scheme() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_preferred_scheme}@anchor{67b}
@deffn {Fonction} sysconfig.get_preferred_scheme (key)

Return a preferred scheme name for an installation layout specified by `key'.

`key' must be either @code{"prefix"}, @code{"home"}, or @code{"user"}.

The return value is a scheme name listed in @ref{42fc,,get_scheme_names()}. It
can be passed to @ref{da,,sysconfig} functions that take a `scheme' argument,
such as @ref{1222,,get_paths()}.


Ajouté dans la version 3.10.



Modifié dans la version 3.11: When Python runs from a virtual environment and @code{key="prefix"},
the `venv' scheme is returned.

@end deffn

@geindex _get_preferred_schemes() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig _get_preferred_schemes}@anchor{42fd}
@deffn {Fonction} sysconfig._get_preferred_schemes ()

Return a dict containing preferred scheme names on the current platform.
Python implementers and redistributors may add their preferred schemes to
the @code{_INSTALL_SCHEMES} module-level global value, and modify this function
to return those scheme names, to e.g. provide different schemes for system
and language package managers to use, so packages installed by either do not
mix with those by the other.

End users should not use this function, but @ref{17b1,,get_default_scheme()} and
@ref{67b,,get_preferred_scheme()} instead.


Ajouté dans la version 3.10.

@end deffn

@geindex get_path_names() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_path_names}@anchor{42fe}
@deffn {Fonction} sysconfig.get_path_names ()

Return a tuple containing all path names currently supported in
@ref{da,,sysconfig}.
@end deffn

@geindex get_path() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_path}@anchor{130c}
@deffn {Fonction} sysconfig.get_path (name[, scheme[, vars[, expand]]])

Return an installation path corresponding to the path `name', from the
install scheme named `scheme'.

`name' has to be a value from the list returned by @ref{42fe,,get_path_names()}.

@ref{da,,sysconfig} stores installation paths corresponding to each path name,
for each platform, with variables to be expanded.  For instance the `stdlib'
path for the `nt' scheme is: @code{@{base@}/Lib}.

@ref{130c,,get_path()} will use the variables returned by @ref{1015,,get_config_vars()}
to expand the path.  All variables have default values for each platform so
one may call this function and get the default value.

If `scheme' is provided, it must be a value from the list returned by
@ref{42fc,,get_scheme_names()}.  Otherwise, the default scheme for the current
platform is used.

If `vars' is provided, it must be a dictionary of variables that will update
the dictionary returned by @ref{1015,,get_config_vars()}.

If `expand' is set to @code{False}, the path will not be expanded using the
variables.

If `name' is not found, raise a @ref{33a,,KeyError}.
@end deffn

@geindex get_paths() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_paths}@anchor{1222}
@deffn {Fonction} sysconfig.get_paths ([scheme[, vars[, expand]]])

Return a dictionary containing all installation paths corresponding to an
installation scheme. See @ref{130c,,get_path()} for more information.

If `scheme' is not provided, will use the default scheme for the current
platform.

If `vars' is provided, it must be a dictionary of variables that will
update the dictionary used to expand the paths.

If `expand' is set to false, the paths will not be expanded.

If `scheme' is not an existing scheme, @ref{1222,,get_paths()} will raise a
@ref{33a,,KeyError}.
@end deffn

@node Autres fonctions<3>,Using sysconfig as a script,Installation path functions,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig other-functions}@anchor{42ff}
@subsubsection Autres fonctions


@geindex get_python_version() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_python_version}@anchor{1221}
@deffn {Fonction} sysconfig.get_python_version ()

Return the @code{MAJOR.MINOR} Python version number as a string.  Similar to
@code{'%d.%d' % sys.version_info[:2]}.
@end deffn

@geindex get_platform() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_platform}@anchor{1220}
@deffn {Fonction} sysconfig.get_platform ()

Return a string that identifies the current platform.

This is used mainly to distinguish platform-specific build directories and
platform-specific built distributions.  Typically includes the OS name and
version and the architecture (as supplied by @ref{10f6,,os.uname()}), although the
exact information included depends on the OS; e.g., on Linux, the kernel
version isn't particularly important.

Exemples de valeurs renvoyées :


@itemize -

@item 
linux-i586

@item 
linux-alpha (?)

@item 
solaris-2.6-sun4u
@end itemize

Windows will return one of:


@itemize -

@item 
win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and EM64T)

@item 
win32 (all others - specifically, sys.platform is returned)
@end itemize

macOS can return:


@itemize -

@item 
macosx-10.6-ppc

@item 
macosx-10.4-ppc64

@item 
macosx-10.3-i386

@item 
macosx-10.4-fat
@end itemize

For other non-POSIX platforms, currently just returns @ref{a7b,,sys.platform}.
@end deffn

@geindex is_python_build() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig is_python_build}@anchor{2f7}
@deffn {Fonction} sysconfig.is_python_build ()

Return @code{True} if the running Python interpreter was built from source and
is being run from its built location, and not from a location resulting from
e.g. running @code{make install} or installing via a binary installer.
@end deffn

@geindex parse_config_h() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig parse_config_h}@anchor{4300}
@deffn {Fonction} sysconfig.parse_config_h (fp[, vars])

Parse a @code{config.h}-style file.

`fp' is a file-like object pointing to the @code{config.h}-like file.

A dictionary containing name/value pairs is returned.  If an optional
dictionary is passed in as the second argument, it is used instead of a new
dictionary, and updated with the values read in the file.
@end deffn

@geindex get_config_h_filename() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_config_h_filename}@anchor{4301}
@deffn {Fonction} sysconfig.get_config_h_filename ()

Return the path of @code{pyconfig.h}.
@end deffn

@geindex get_makefile_filename() (dans le module sysconfig)
@anchor{library/sysconfig sysconfig get_makefile_filename}@anchor{4302}
@deffn {Fonction} sysconfig.get_makefile_filename ()

Return the path of @code{Makefile}.
@end deffn

@node Using sysconfig as a script,,Autres fonctions<3>,sysconfig --- Provide access to Python's configuration information
@anchor{library/sysconfig sysconfig-cli}@anchor{4303}@anchor{library/sysconfig using-sysconfig-as-a-script}@anchor{4304}
@subsubsection Using @code{sysconfig} as a script


You can use @ref{da,,sysconfig} as a script with Python's `-m' option:

@example
$ python -m sysconfig
Platform: "macosx-10.4-i386"
Python version: "3.2"
Current installation scheme: "posix_prefix"

Paths:
        data = "/usr/local"
        include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
        platinclude = "."
        platlib = "/usr/local/lib/python3.2/site-packages"
        platstdlib = "/usr/local/lib/python3.2"
        purelib = "/usr/local/lib/python3.2/site-packages"
        scripts = "/usr/local/bin"
        stdlib = "/usr/local/lib/python3.2"

Variables:
        AC_APPLE_UNIVERSAL_BUILD = "0"
        AIX_GENUINE_CPLUSPLUS = "0"
        AR = "ar"
        ARFLAGS = "rc"
        ...
@end example

This call will print in the standard output the information returned by
@ref{1220,,get_platform()}, @ref{1221,,get_python_version()}, @ref{130c,,get_path()} and
@ref{1015,,get_config_vars()}.

@node builtins --- Built-in objects,__main__ --- Top-level code environment,sysconfig --- Provide access to Python's configuration information,Environnement d'exécution Python
@anchor{library/builtins doc}@anchor{4305}@anchor{library/builtins builtins-built-in-objects}@anchor{4306}@anchor{library/builtins module-builtins}@anchor{12}
@subsection @code{builtins} --- Built-in objects


@geindex module; builtins


__________________________________________________________________


This module provides direct access to all 'built-in' identifiers of Python; for
example, @code{builtins.open} is the full name for the built-in function @ref{505,,open()}.

Ce module n'est normalement pas accédé explicitement par la plupart des applications, mais peut être utile dans des modules qui exposent des objets de même nom qu'une valeur native, mais pour qui le natif de même nom est aussi nécessaire. Par exemple, dans un module qui voudrait implémenter une fonction @ref{505,,open()} autour de la fonction native @ref{505,,open()}, ce module peut être utilisé directement :

@example
import builtins

def open(path):
    f = builtins.open(path, 'r')
    return UpperCaser(f)

class UpperCaser:
    '@w{'}'Wrapper around a file that converts output to uppercase.'@w{'}'

    def __init__(self, f):
        self._f = f

    def read(self, count=-1):
        return self._f.read(count).upper()

    # ...
@end example

Spécificité de l'implémentation: La plupart des modules ont @code{__builtins__} dans leurs globales.  La valeur de @code{__builtins__} est classiquement soit ce module, soit la valeur de l'attribut @ref{546,,__dict__} du module. Puisque c'est une spécificité de CPython, ce n'est peut-être pas utilisé par toutes les autres implémentations.


@subsubheading Voir aussi



@itemize *

@item 
@ref{210d,,Constantes natives}

@item 
@ref{1811,,Exceptions natives}

@item 
@ref{123b,,Fonctions natives}

@item 
@ref{2117,,Types natifs}
@end itemize


@node __main__ --- Top-level code environment,warnings --- Warning control,builtins --- Built-in objects,Environnement d'exécution Python
@anchor{library/__main__ doc}@anchor{4307}@anchor{library/__main__ main-top-level-code-environment}@anchor{4308}@anchor{library/__main__ module-__main__}@anchor{1}
@subsection @code{__main__} --- Top-level code environment


@geindex module; __main__


__________________________________________________________________


En Python, le nom @code{__main__} a une fonction particulière. Il intervient dans deux cas :


@enumerate 

@item 
c'est le nom de l'environnement d'exécution principal, ce qui donne lieu au test courant @code{__name__ == '__main__'} ;

@item 
c'est aussi le nom du fichier @code{__main__.py} dans les paquets Python.
@end enumerate

Les deux sont liés aux modules Python, à la manière de s'en servir en tant qu'utilisateur et à la manière dont ils interagissent entre eux. Cette page contient des détails sur les modules Python. Si vous ne les avez jamais utilisés, commencez par la section qui leur est consacrée dans le tutoriel : @ref{1be4,,Modules}.

@menu
* __name__ == '__main__':: 
* Le fichier __main__.py dans les paquets Python: Le fichier __main__ py dans les paquets Python. 
* import __main__:: 

@end menu

@node __name__ == '__main__',Le fichier __main__ py dans les paquets Python,,__main__ --- Top-level code environment
@anchor{library/__main__ name-equals-main}@anchor{4309}@anchor{library/__main__ name-main}@anchor{430a}
@subsubsection @code{__name__ == '__main__'}


Lorsqu'un module ou un paquet Python est importé, son attribut @code{__name__} est défini à son nom, qui est la plupart du temps le nom du fichier qui le contient sans l'extension @code{.py} :

@example
>>> import configparser
>>> configparser.__name__
'configparser'
@end example

Si le fichier fait partie d'un paquet, @code{__name__} donne tout le chemin d'accès :

@example
>>> from concurrent.futures import process
>>> process.__name__
'concurrent.futures.process'
@end example

En revanche, si le module est exécuté dans l'environnement d'exécution principal, la variable @code{__name__} vaut @code{'__main__'}.

@menu
* Qu'est-ce que l'« environnement d'exécution principal » ?:: 
* Utilisation idiomatique:: 
* Considérations liées à l'empaquetage:: 

@end menu

@node Qu'est-ce que l'« environnement d'exécution principal » ?,Utilisation idiomatique,,__name__ == '__main__'
@anchor{library/__main__ what-is-the-top-level-code-environment}@anchor{430b}
@subsubsection Qu'est-ce que l'« environnement d'exécution principal » ?


L'environnement principal a pour nom @code{__main__}. Il s'agit du premier module Python dont l'exécution a été demandée par l'utilisateur final. On le qualifie de principal car c'est lui qui importe tous les autres modules nécessités par le programme. On l'appelle parfois le point d'entrée de l'application.

L'environnement principal peut prendre diverses formes :


@itemize *

@item 
l'environnement d'une invite de commande interactive :

@example
>>> __name__
'__main__'
@end example

@item 
le module passé directement en tant que fichier à la commande de l'interpréteur Python :

@example
$ python helloworld.py
Hello, world!
@end example

@item 
le module ou paquet passé à l'interpréteur avec l'option @ref{5cb,,-m} :

@example
$ python -m tarfile
usage: tarfile.py [-h] [-v] (...)
@end example

@item 
le code lu par l'interpréteur depuis l'entrée standard :

@example
$ echo "import this" | python
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...
@end example

@item 
le code passé à l'interpréteur avec l'option @ref{5ca,,-c} :

@example
$ python -c "import this"
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
...
@end example
@end itemize

Dans chacun de ces cas, l'attribut @code{__name__} du module principal est mis à @code{'__main__'}.

Un module peut donc savoir s'il est exécuté dans l'environnement principal en vérifiant son @code{__name__}, ce qui permet typiquement d'exécuter du code lorsque le module est initialisé d'une manière autre que l'importation :

@example
if __name__ == '__main__':
    # Execute when the module is not initialized from an import statement.
    ...
@end example


@subsubheading Voir aussi


Pour plus de détails sur la manière dont @code{__name__} est défini dans les divers cas, voir la section @ref{1be4,,Modules} dans le tutoriel.


@node Utilisation idiomatique,Considérations liées à l'empaquetage,Qu'est-ce que l'« environnement d'exécution principal » ?,__name__ == '__main__'
@anchor{library/__main__ idiomatic-usage}@anchor{430c}
@subsubsection Utilisation idiomatique


Il arrive qu'un module contienne du code qui ne doit s'exécuter que lorsque le module est utilisé comme script. On peut penser à l'analyse des arguments passés en ligne de commande, ou bien à la lecture de l'entrée standard. Il ne faudrait pas que ces opérations soient effectuées lorsque le module est importé depuis un autre module, comme pour les tests.

C'est dans ces situations que sert la construction @code{if __name__ == '__main__'}. Le code mis à l'intérieur du bloc n'est exécuté que si le module est dans l'environnement principal.

Putting as few statements as possible in the block below @code{if __name__ ==
'__main__'} can improve code clarity and correctness. Most often, a function
named @code{main} encapsulates the program's primary behavior:

@example
# echo.py

import shlex
import sys

def echo(phrase: str) -> None:
   """A dummy wrapper around print."""
   # for demonstration purposes, you can imagine that there is some
   # valuable and reusable logic inside this function
   print(phrase)

def main() -> int:
    """Echo the input arguments to standard output"""
    phrase = shlex.join(sys.argv)
    echo(phrase)
    return 0

if __name__ == '__main__':
    sys.exit(main())  # next section explains the use of sys.exit
@end example

Si, dans le module ci-dessus, le code de @code{main} était placé directement dans le @code{if __name__ == '__main__'}, la variable @code{phrase} serait globale, et d'autres fonctions pourraient s'en servir par erreur à la place d'une variable locale. Encapsuler le code dans la fonction @code{main} évite cet ennui.

De plus, la fonction @code{echo} est elle-même séparée du reste, et on peut l'importer dans un autre module. Le fait d'importer @code{echo.py} définit les fonctions @code{main} et @code{echo}, mais n'en appelle aucune, puisque @code{__name__ != '__main__'}.

@node Considérations liées à l'empaquetage,,Utilisation idiomatique,__name__ == '__main__'
@anchor{library/__main__ packaging-considerations}@anchor{430d}
@subsubsection Considérations liées à l'empaquetage


Les fonctions @code{main} servent souvent à créer des outils qui s'exécutent en ligne de commande. Les scripts sont ajoutés au système à l'aide de points d'entrée, qui demandent à pip@footnote{https://pip.pypa.io/} de créer un exécutable. Il le fait en insérant un appel à la fonction à l'intérieur d'un modèle prédéfini où la valeur qu'elle renvoie est passée directement à @ref{1327,,sys.exit()} :

@example
sys.exit(main())
@end example

Puisque l'appel de @code{main} est encapsulé dans @ref{1327,,sys.exit()}, @code{main} doit renvoyer une valeur qui convienne comme argument à @ref{1327,,sys.exit()}, par exemple un code de retour sous forme d'entier. La valeur @code{None} est également acceptée, et c'est d'ailleurs celle que renvoie la fonction si elle se termine sans rencontrer d'instruction @code{return}.

By proactively following this convention ourselves, our module will have the
same behavior when run directly (i.e. @code{python echo.py}) as it will have if
we later package it as a console script entry-point in a pip-installable
package.

En particulier, mieux vaut éviter de renvoyer une chaîne de caractères depuis la fonction @code{main}. En effet, si @ref{1327,,sys.exit()} reçoit une chaîne, elle l'interprète comme un message d'erreur, qu'elle affiche sur @ref{926,,sys.stderr} avant de terminer le programme avec le code de retour 1 (erreur). L'exemple de @code{echo.py} ci-dessus montre la pratique recommandée.


@subsubheading Voir aussi


Le guide de l'empaquetage en Python@footnote{https://packaging.python.org/} (en anglais) contient plusieurs tutoriels et documents de référence autour de la distribution et de l'installation de paquets Python avec des outils modernes.


@node Le fichier __main__ py dans les paquets Python,import __main__,__name__ == '__main__',__main__ --- Top-level code environment
@anchor{library/__main__ main-py-in-python-packages}@anchor{430e}
@subsubsection Le fichier @code{__main__.py} dans les paquets Python


Si vous n'êtes pas familier des paquets Python, lisez @ref{1bf5,,Les paquets} dans le tutoriel. Un fichier @code{__main__.py} permet à un paquet de définir une interface en ligne de commande. Prenons pour exemple un paquet nommé `bandclass' :

@example
bandclass
  ├── __init__.py
  ├── __main__.py
  └── student.py
@end example

Le fichier @code{__main__.py} qu'il contient s'exécute lorsque le paquet est appelé depuis la ligne de commande avec l'option @ref{5cb,,-m} de l'interpréteur, comme ceci :

@example
$ python -m bandclass
@end example

Cette commande lance l'exécution de @code{__main__.py}. Il vous appartient, en tant que concepteur du paquet, de déterminer ce qu'elle doit faire. Dans notre exemple, elle pourrait rechercher un étudiant dans une base de données :

@example
# bandclass/__main__.py

import sys
from .student import search_students

student_name = sys.argv[1] if len(sys.argv) >= 2 else '@w{'}
print(f'Found student: @{search_students(student_name)@}')
@end example

Remarquez l'importation @code{from .student import search_students}. Le point avant @code{student} sert à rendre le chemin @code{student} relatif à la position du module qui l'importe. Pour plus d'informations, voir @ref{1bfa,,Références internes dans un paquet} dans la section @ref{1be4,,Modules} du tutoriel.

@menu
* Utilisation idiomatique: Utilisation idiomatique<2>. 

@end menu

@node Utilisation idiomatique<2>,,,Le fichier __main__ py dans les paquets Python
@anchor{library/__main__ id1}@anchor{430f}
@subsubsection Utilisation idiomatique


The content of @code{__main__.py} typically isn't fenced with an
@code{if __name__ == '__main__'} block.  Instead, those files are kept
short and import functions to execute from other modules.  Those other modules can then be
easily unit-tested and are properly reusable.

Cependant, un @code{if __name__ == '__main__'}, s'il est présent dans le @code{__main__.py}, fonctionne correctement. En effet, si @code{__main__.py} est importé depuis autre module, son attribut @code{__name__} contient, avant @code{__main__}, le nom du paquet dont il fait partie :

@example
>>> import asyncio.__main__
>>> asyncio.__main__.__name__
'asyncio.__main__'
@end example

This won't work for @code{__main__.py} files in the root directory of a
@code{.zip} file though.  Hence, for consistency, a minimal @code{__main__.py}
without a @code{__name__} check is preferred.


@subsubheading Voir aussi


See @ref{110,,venv} for an example of a package with a minimal @code{__main__.py}
in the standard library. It doesn't contain a @code{if __name__ == '__main__'}
block. You can invoke it with @code{python -m venv [directory]}.

La documentation du module @ref{bd,,runpy} fournit une description complète de l'option @ref{5cb,,-m} de l'interpréteur.

Le module @ref{12f,,zipapp} exécute des applications emballées dans une archive ZIP. Dans ce cas, l'interpréteur recherche un fichier @code{__main__.py} à la racine de l'archive.


@node import __main__,,Le fichier __main__ py dans les paquets Python,__main__ --- Top-level code environment
@anchor{library/__main__ import-main}@anchor{4310}
@subsubsection @code{import __main__}


Quel que soit le module principal d'un programme, les autres modules peuvent accéder à l'@ref{1be5,,espace de nommage} dans lequel il s'exécute en important le module spécial @code{__main__}. Celui-ci ne correspond pas forcément à un fichier @code{__main__.py}. Il s'agit simplement du module qui a reçu le nom @code{'__main__'}.

Voici un exemple d'utilisation du module @code{__main__} :

@example
# namely.py

import __main__

def did_user_define_their_name():
    return 'my_name' in dir(__main__)

def print_user_name():
    if not did_user_define_their_name():
        raise ValueError('Define the variable `my_name`!')

    if '__file__' in dir(__main__):
        print(__main__.my_name, "found in file", __main__.__file__)
    else:
        print(__main__.my_name)
@end example

Ce code s'utilise comme ceci :

@example
# start.py

import sys

from namely import print_user_name

# my_name = "Dinsdale"

def main():
    try:
        print_user_name()
    except ValueError as ve:
        return str(ve)

if __name__ == "__main__":
    sys.exit(main())
@end example

Le programme ci-dessus donne la sortie :

@example
$ python start.py
Define the variable `my_name`!
@end example

Son code de retour est 1, ce qui signifie une erreur. En supprimant la marque de commentaire en début de ligne @code{my_name = "Dinsdale"}, le programme est corrigé, et renvoie au système le code 0 car il n'y a plus d'erreur :

@example
$ python start.py
Dinsdale found in file /path/to/start.py
@end example

On pourrait s'attendre à un problème au moment de l'importation de @code{__main__} : cela ne provoque-t-il pas l'exécution anticipée du code de script sous @code{if __name__ == '__main__'} dans le module principal @code{start} ?

Python inserts an empty @code{__main__} module in @ref{18f9,,sys.modules} at
interpreter startup, and populates it by running top-level code. In our example
this is the @code{start} module which runs line by line and imports @code{namely}.
In turn, @code{namely} imports @code{__main__} (which is really @code{start}). That's an
import cycle! Fortunately, since the partially populated @code{__main__}
module is present in @ref{18f9,,sys.modules}, Python passes that to @code{namely}.
See @ref{1f8c,,Special considerations for __main__} in the
import system's reference for details on how this works.

L'interpréteur interactif est un autre environnement d'exécution principal possible. Toute variable qui y est définie appartient à l'espace de nommage @code{__main__} :

@example
>>> import namely
>>> namely.did_user_define_their_name()
False
>>> namely.print_user_name()
Traceback (most recent call last):
...
ValueError: Define the variable `my_name`!
>>> my_name = 'Jabberwocky'
>>> namely.did_user_define_their_name()
True
>>> namely.print_user_name()
Jabberwocky
@end example

Dans ce cas, il n'y a pas de variable @code{__file__}, puisque cela n'a pas de sens dans le mode interactif.

Le module @code{__main__} est notamment employé dans les implémentations de @ref{a4,,pdb} et @ref{bc,,rlcompleter}.

@node warnings --- Warning control,dataclasses --- Data Classes,__main__ --- Top-level code environment,Environnement d'exécution Python
@anchor{library/warnings doc}@anchor{4311}@anchor{library/warnings module-warnings}@anchor{111}@anchor{library/warnings warnings-warning-control}@anchor{4312}
@subsection @code{warnings} --- Warning control


@geindex module; warnings

`Code source:' Lib/warnings.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/warnings.py}

@geindex warnings


__________________________________________________________________


Les messages d'avertissement sont généralement émis dans les situations où il est utile d'alerter l'utilisateur d'un problème dans un programme, mais qu'il n'est pas justifié de lever une exception et de le terminer. Par exemple, on peut vouloir émettre un avertissement lorsqu'un programme utilise un module obsolète.

Les développeurs Python émettent des avertissements en appelant la fonction @ref{14d0,,warn()} définie dans ce module. (Les développeurs C utilisent @ref{1401,,PyErr_WarnEx()} ; voir @ref{4313,,Gestion des exceptions} pour plus d'informations).

Les messages d'avertissement sont normalement écrits sur @ref{926,,sys.stderr}, mais leurs effets peuvent être modifiés, il est possible d'ignorer tous les avertissements ou au contraire les transformer en exceptions. L'effet des avertissements peut varier selon la  @ref{4314,,catégorie d'avertissement}, de son texte et d'où il est émis. Les répétitions du même avertissement depuis une même source sont généralement ignorées.

La gestion des avertissements se fait en deux étapes : premièrement, chaque fois qu'un avertissement est émis, le module détermine si un message doit être émis ou non ; ensuite, si un message doit être émis, il est formaté et affiché en utilisant une fonction qui peut être définie  par l'utilisateur.

Un  @ref{8b6,,filtre} (une séquence de règles) est utilisé pour décider si un message d'avertissement doit être émis ou non. Des règles peuvent être ajoutées au filtre en appelant @ref{145d,,filterwarnings()} et remises à leur état par défaut en appelant @ref{4315,,resetwarnings()}.

L'affichage des messages d'avertissement se fait en appelant la fonction @ref{4316,,showwarning()}, qui peut être redéfinie ; l'implémentation par défaut formate le message en appelant @ref{19a3,,formatwarning()}, qui peut également être réutilisée par une implémentation personnalisée.


@subsubheading Voir aussi


@ref{2c34,,logging.captureWarnings()} vous permet de gérer tous les avertissements avec l'infrastructure de journalisation standard.


@menu
* Catégories d'avertissement:: 
* Le filtre des avertissements:: 
* Suppression temporaire des avertissements:: 
* Tester les avertissements:: 
* Mise à jour du code pour les nouvelles versions des dépendances:: 
* Fonctions disponibles:: 
* Gestionnaires de contexte disponibles:: 

@end menu

@node Catégories d'avertissement,Le filtre des avertissements,,warnings --- Warning control
@anchor{library/warnings id1}@anchor{4317}@anchor{library/warnings warning-categories}@anchor{4314}
@subsubsection Catégories d'avertissement


Il existe un certain nombre d'exceptions natives qui représentent des catégories d'avertissement. Cette catégorisation est utile pour filtrer les groupes d'avertissements.

Bien qu'il s'agisse techniquement d'exceptions, les @ref{2237,,exceptions natives} sont documentées ici, parce qu'elles appartiennent conceptuellement au mécanisme des avertissements.

Le code utilisateur peut définir des catégories d'avertissement supplémentaires en héritant l'une des catégories d'avertissement standard. Une catégorie d'avertissement doit toujours hériter de la classe @ref{2239,,Warning}.

Les classes de catégories d'avertissement suivantes sont actuellement définies :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Classe

@tab

Description

@item

@ref{2239,,Warning}

@tab

Il s'agit de la classe de base de toutes les classes de catégories d'avertissement. C'est une sous-classe de @ref{9c7,,Exception}.

@item

@ref{223a,,UserWarning}

@tab

Catégorie par défaut pour @ref{14d0,,warn()}.

@item

@ref{1a3,,DeprecationWarning}

@tab

Catégorie de base pour les avertissements sur les fonctionnalités obsolètes lorsque ces avertissements sont destinés à d'autres développeurs Python (ignorées par défaut, sauf si elles proviennent de @code{__main__}).

@item

@ref{44f,,SyntaxWarning}

@tab

Catégorie de base pour les avertissements concernant les syntaxes douteuses.

@item

@ref{1bb,,RuntimeWarning}

@tab

Catégorie de base pour les avertissements concernant les fonctionnalités douteuses à l'exécution.

@item

@ref{40b,,FutureWarning}

@tab

Catégorie de base pour les avertissements concernant les fonctionnalités obsolètes lorsque ces avertissements sont destinés aux utilisateurs finaux des programmes écrits en Python.

@item

@ref{8b5,,PendingDeprecationWarning}

@tab

Catégorie de base pour les avertissements concernant les fonctionnalités qui seront obsolètes dans le futur (ignorée par défaut).

@item

@ref{4e4,,ImportWarning}

@tab

Catégorie de base pour les avertissements déclenchés lors de l'importation d'un module (ignoré par défaut).

@item

@ref{13da,,UnicodeWarning}

@tab

Catégorie de base pour les avertissements relatifs à Unicode.

@item

@ref{c11,,BytesWarning}

@tab

Catégorie de base pour les avertissements relatifs à @ref{1bd,,bytes} et @ref{528,,bytearray}.

@item

@ref{241,,ResourceWarning}

@tab

Catégorie de base pour les avertissements relatifs à l'utilisation des ressources (ignorés par défaut).

@end multitable



Modifié dans la version 3.7: Avant, la différence entre @ref{1a3,,DeprecationWarning} et @ref{40b,,FutureWarning} était que l'un était dédié aux fonctionnalités retirées, et l'autre aux fonctionnalités modifiées. La différence aujourd'hui est plutôt leur audience et la façon dont ils sont traités par les filtres d'avertissement par défaut.


@node Le filtre des avertissements,Suppression temporaire des avertissements,Catégories d'avertissement,warnings --- Warning control
@anchor{library/warnings the-warnings-filter}@anchor{4318}@anchor{library/warnings warning-filter}@anchor{8b6}
@subsubsection Le filtre des avertissements


Le filtre des avertissements contrôle si les avertissements sont ignorés, affichés ou transformés en erreurs (ce qui lève une exception).

Conceptuellement, le filtre d'avertissements maintient une liste ordonnée d'entrées ; chaque avertissement est comparé à chaque entrée de la liste jusqu'à ce qu'une correspondance soit trouvée ; l'entrée détermine l'action à effectuer.  Chaque entrée est un quintuplet de la forme (`action', `message', `catégorie', `module', `lineno'), où :


@itemize *

@item 
`action' est l'une des chaînes de caractères suivantes :


@multitable {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Valeur

@tab

Action

@item

@code{"default"}

@tab

affiche la première occurrence des avertissements correspondants pour chaque emplacement (module + numéro de ligne) où l'avertissement est émis

@item

@code{"error"}

@tab

transforme les avertissements correspondants en exceptions

@item

@code{"ignore"}

@tab

ignore les avertissements correspondants

@item

@code{"always"}

@tab

affiche toujours les avertissements correspondants

@item

@code{"module"}

@tab

affiche la première occurrence des avertissements correspondants pour chaque module où l'avertissement est émis (quel que soit le numéro de ligne)

@item

@code{"once"}

@tab

n'affiche que la première occurrence des avertissements correspondants, quel que soit l'endroit où ils se trouvent

@end multitable


@item 
`message' is a string containing a regular expression that the start of
the warning message must match, case-insensitively.  In @ref{8b4,,-W} and
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS}, `message' is a literal string that the start of the
warning message must contain (case-insensitively), ignoring any whitespace at
the start or end of `message'.

@item 
`category' est une classe (une sous-classe de @ref{2239,,Warning}) dont la catégorie d'avertissement doit être une sous-classe afin de correspondre.

@item 
`module' is a string containing a regular expression that the start of the
fully qualified module name must match, case-sensitively.  In @ref{8b4,,-W} and
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS}, `module' is a literal string that the
fully qualified module name must be equal to (case-sensitively), ignoring any
whitespace at the start or end of `module'.

@item 
`lineno' est le numéro de ligne d'où l'avertissement doit provenir, ou @code{0} pour correspondre à tous les numéros de ligne.
@end itemize

Puisque que la classe @ref{2239,,Warning} hérite de la classe @ref{9c7,,Exception}, pour transformer un avertissement en erreur, il suffit de lever @code{category(message)}.

Si un avertissement est signalé et ne correspond à aucun filtre enregistré, l'action @code{default} est appliquée (d'où son nom).

@menu
* Repeated Warning Suppression Criteria:: 
* Rédaction de filtres d'avertissement:: 
* Filtre d'avertissement par défaut:: 
* Outrepasser le filtre par défaut:: 

@end menu

@node Repeated Warning Suppression Criteria,Rédaction de filtres d'avertissement,,Le filtre des avertissements
@anchor{library/warnings id2}@anchor{4319}@anchor{library/warnings repeated-warning-suppression-criteria}@anchor{431a}
@subsubsection Repeated Warning Suppression Criteria


The filters that suppress repeated warnings apply the following criteria to determine if a warning is considered a repeat:


@itemize -

@item 
@code{"default"}: A warning is considered a repeat only if the (`message', `category', `module', `lineno') are all the same.

@item 
@code{"module"}: A warning is considered a repeat if the (`message', `category', `module') are the same, ignoring the line number.

@item 
@code{"once"}: A warning is considered a repeat if the (`message', `category') are the same, ignoring the module and line number.
@end itemize

@node Rédaction de filtres d'avertissement,Filtre d'avertissement par défaut,Repeated Warning Suppression Criteria,Le filtre des avertissements
@anchor{library/warnings describing-warning-filters}@anchor{1cc5}@anchor{library/warnings id3}@anchor{431b}
@subsubsection Rédaction de filtres d'avertissement


Le filtre des avertissements est initialisé par les options @ref{8b4,,-W} passées à la ligne de commande de l'interpréteur Python et la variable d'environnement 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS}. L'interpréteur enregistre les arguments de toutes les entrées fournies sans interprétation dans @ref{3a7,,sys.warnoptions} ; le module @ref{111,,warnings} les analyse lors de la première importation (les options invalides sont ignorées, et un message d'erreur est envoyé à @ref{926,,sys.stderr}).

Les filtres d'avertissement individuels sont décrits sous la forme d'une séquence de champs séparés par des deux-points :

@example
action:message:category:module:line
@end example

La signification de chacun de ces champs est décrite dans @ref{8b6,,Le filtre des avertissements}. Plusieurs filtres peuvent être écrits en une seule ligne (comme pour 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS}), ils sont dans ce cas séparés par des virgules, et les filtres listés plus en dernier ont priorité sur ceux qui les précèdent (car ils sont appliqués de gauche à droite, et les filtres les plus récemment appliqués ont priorité sur les précédents).

Les filtres d'avertissement couramment utilisés s'appliquent à tous les avertissements, aux avertissements d'une catégorie particulière ou aux avertissements émis par certains modules ou paquets. Quelques exemples :

@example
default                      # Show all warnings (even those ignored by default)
ignore                       # Ignore all warnings
error                        # Convert all warnings to errors
error::ResourceWarning       # Treat ResourceWarning messages as errors
default::DeprecationWarning  # Show DeprecationWarning messages
ignore,default:::mymodule    # Only report warnings triggered by "mymodule"
error:::mymodule             # Convert warnings to errors in "mymodule"
@end example

@node Filtre d'avertissement par défaut,Outrepasser le filtre par défaut,Rédaction de filtres d'avertissement,Le filtre des avertissements
@anchor{library/warnings default-warning-filter}@anchor{431c}@anchor{library/warnings id4}@anchor{431d}
@subsubsection Filtre d'avertissement par défaut


Par défaut, Python installe plusieurs filtres d'avertissement, qui peuvent être outrepassés par l'option @ref{8b4,,-W} en ligne de commande, la variable d'environnement 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS} et les appels à @ref{145d,,filterwarnings()}.

Dans les versions standard publiées de Python, le filtre d'avertissement par défaut a les entrées suivantes (par ordre de priorité) :

@example
default::DeprecationWarning:__main__
ignore::DeprecationWarning
ignore::PendingDeprecationWarning
ignore::ImportWarning
ignore::ResourceWarning
@end example

Dans les @ref{1f6,,versions de débogage}, la liste des filtres d'avertissement par défaut est vide.


Modifié dans la version 3.2: @ref{1a3,,DeprecationWarning} est maintenant ignoré par défaut en plus de @ref{8b5,,PendingDeprecationWarning}.



Modifié dans la version 3.7: @ref{1a3,,DeprecationWarning} est à nouveau affiché par défaut lorsqu'il provient directement de @code{__main__}.



Modifié dans la version 3.7: @ref{c11,,BytesWarning} n'apparaît plus dans la liste de filtres par défaut et est configuré via @ref{3a7,,sys.warnoptions} lorsque l'option @ref{5cd,,-b} est donnée deux fois.


@node Outrepasser le filtre par défaut,,Filtre d'avertissement par défaut,Le filtre des avertissements
@anchor{library/warnings overriding-the-default-filter}@anchor{431e}@anchor{library/warnings warning-disable}@anchor{431f}
@subsubsection Outrepasser le filtre par défaut


Les développeurs d'applications écrites en Python peuvent souhaiter cacher `tous' les avertissements Python à leurs utilisateurs, et ne les afficher que lorsqu'ils exécutent des tests ou travaillent sur l'application. L'attribut @ref{3a7,,sys.warnoptions} utilisé pour passer les configurations de filtre à l'interpréteur peut être utilisé comme marqueur pour indiquer si les avertissements doivent être ou non désactivés :

@example
import sys

if not sys.warnoptions:
    import warnings
    warnings.simplefilter("ignore")
@end example

Les développeurs d'exécuteurs de test pour le code Python sont invités à s'assurer que `tous' les avertissements sont affichés par défaut pour le code en cours de test, en utilisant par exemple :

@example
import sys

if not sys.warnoptions:
    import os, warnings
    warnings.simplefilter("default") # Change the filter in this process
    os.environ["PYTHONWARNINGS"] = "default" # Also affect subprocesses
@end example

Enfin, les développeurs d'interpréteurs de commandes interactifs qui exécutent du code utilisateur dans un espace de nommage autre que @code{__main__} sont invités à s'assurer que les messages @ref{1a3,,DeprecationWarning} sont rendus visibles par défaut, en utilisant le code suivant (où @code{user_ns} est le module utilisé pour exécuter le code entré interactivement) :

@example
import warnings
warnings.filterwarnings("default", category=DeprecationWarning,
                                   module=user_ns.get("__name__"))
@end example

@node Suppression temporaire des avertissements,Tester les avertissements,Le filtre des avertissements,warnings --- Warning control
@anchor{library/warnings temporarily-suppressing-warnings}@anchor{4320}@anchor{library/warnings warning-suppress}@anchor{4321}
@subsubsection Suppression temporaire des avertissements


Si vous utilisez un code dont vous savez qu'il va déclencher un avertissement, comme une fonction obsolète, mais que vous ne voulez pas voir l'avertissement (même si les avertissements ont été explicitement configurés via la ligne de commande), alors il est possible de supprimer l'avertissement en utilisant le gestionnaire de contexte @ref{570,,catch_warnings} :

@example
import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()
@end example

Dans le gestionnaire de contexte, tous les avertissements sont simplement ignorés. Ceci vous permet d'utiliser du code déclaré obsolète sans voir l'avertissement tout en ne supprimant pas l'avertissement pour un autre code qui pourrait ne pas être conscient de son utilisation de code déprécié.  Remarque : ceci ne peut être garanti que dans une application utilisant un seul fil d'exécution. Si deux ou plusieurs `threads' utilisent le gestionnaire de contexte @ref{570,,catch_warnings} en même temps, le comportement est indéfini.

@node Tester les avertissements,Mise à jour du code pour les nouvelles versions des dépendances,Suppression temporaire des avertissements,warnings --- Warning control
@anchor{library/warnings testing-warnings}@anchor{4322}@anchor{library/warnings warning-testing}@anchor{4323}
@subsubsection Tester les avertissements


Pour tester les avertissements générés par le code, utilisez le gestionnaire de contexte @ref{570,,catch_warnings}. Avec lui, vous pouvez temporairement modifier le filtre d'avertissements pour faciliter votre test. Par exemple, procédez comme suit pour capturer tous les avertissements levés à vérifier :

@example
import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings(record=True) as w:
    # Cause all warnings to always be triggered.
    warnings.simplefilter("always")
    # Trigger a warning.
    fxn()
    # Verify some things
    assert len(w) == 1
    assert issubclass(w[-1].category, DeprecationWarning)
    assert "deprecated" in str(w[-1].message)
@end example

Vous pouvez aussi faire en sorte que tous les avertissements soient des exceptions en utilisant @code{error} au lieu de @code{always}. Il faut savoir que si un avertissement a déjà été émis à cause d'une règle @code{once} ou @code{default}, quel que soit le filtre activé, l'avertissement ne sera pas revu à moins que le registre des avertissements lié à l'avertissement ait été vidé.

A sa sortie, le gestionnaire de contexte restaure le filtre des avertissements dans l'état où il était au démarrage du contexte. Cela empêche les tests de changer le filtre d'avertissements de manière inattendue entre les tests et d'aboutir à des résultats de test indéterminés. La fonction @ref{4316,,showwarning()} du module est également restaurée à sa valeur originale.  Remarque : ceci ne peut être garanti que dans une application `mono-threadées'. Si deux ou plusieurs fils d'exécution utilisent le gestionnaire de contexte @ref{570,,catch_warnings} en même temps, le comportement est indéfini.

Lorsque vous testez plusieurs opérations qui provoquent le même type d'avertissement, il est important de les tester d'une manière qui confirme que chaque opération provoque un nouvel avertissement (par exemple, définissez les avertissements comme exceptions et vérifiez que les opérations provoquent des exceptions, vérifiez que la longueur de la liste des avertissements continue à augmenter après chaque opération, ou bien supprimez les entrées précédentes de la liste des avertissements avant chaque nouvelle opération).

@node Mise à jour du code pour les nouvelles versions des dépendances,Fonctions disponibles,Tester les avertissements,warnings --- Warning control
@anchor{library/warnings updating-code-for-new-versions-of-dependencies}@anchor{4324}@anchor{library/warnings warning-ignored}@anchor{3fe3}
@subsubsection Mise à jour du code pour les nouvelles versions des dépendances


Les catégories d'avertissement qui intéressent principalement les développeurs Python (plutôt que les utilisateurs finaux d'applications écrites en Python) sont ignorées par défaut.

Notamment, cette liste "ignorés par défaut" inclut @ref{1a3,,DeprecationWarning} (pour chaque module sauf @code{__main__}), ce qui signifie que les développeurs doivent s'assurer de tester leur code avec des avertissements généralement ignorés rendus visibles afin de recevoir des notifications rapides des changements d'API (que ce soit dans la bibliothèque standard ou les paquets tiers).

Dans le cas idéal, le code dispose d'une suite de tests appropriée, et le testeur se charge d'activer implicitement tous les avertissements lors de l'exécution des tests (le testeur fourni par le module @ref{105,,unittest} le fait).

Dans des cas moins idéaux, l'utilisation de d'interfaces obsolète peut être testé en passant @ref{8b4,,-Wd} à l'interpréteur Python (c'est une abréviation pour @code{-W default}) ou en définissant @code{PYTHONWARNINGS=default} dans l'environnement. Ceci permet la gestion par défaut de tous les avertissements, y compris ceux qui sont ignorés par défaut. Pour changer l'action prise pour les avertissements rencontrés, vous pouvez changer quel argument est passé à @ref{8b4,,-W} (par exemple @code{-W error}). Voir l'option @ref{8b4,,-W} pour plus de détails sur ce qui est possible.

@node Fonctions disponibles,Gestionnaires de contexte disponibles,Mise à jour du code pour les nouvelles versions des dépendances,warnings --- Warning control
@anchor{library/warnings available-functions}@anchor{4325}@anchor{library/warnings warning-functions}@anchor{4326}
@subsubsection Fonctions disponibles


@geindex warn() (dans le module warnings)
@anchor{library/warnings warnings warn}@anchor{14d0}
@deffn {Fonction} warnings.warn (message, category=None, stacklevel=1, source=None, *, skip_file_prefixes=())

Émet, ignore, ou transforme en exception un avertissement. L'argument `category', s'il est donné, doit être une classe de @ref{4314,,warning category class} ; et vaut par défaut @ref{223a,,UserWarning}.  Aussi `message' peut être une instance de @ref{2239,,Warning}, auquel cas `category' sera ignoré et @code{message.__class__} sera utilisé. Dans ce cas, le texte du message sera @code{str(message)}. Cette fonction lève une exception si cet avertissement particulier émis est transformé en erreur par le @ref{8b6,,filtre des avertissements}.  L'argument `stacklevel' peut être utilisé par les fonctions `wrapper' écrites en Python, comme ceci :

@example
def deprecated_api(message):
    warnings.warn(message, DeprecationWarning, stacklevel=2)
@end example

This makes the warning refer to @code{deprecated_api}'s caller, rather than to
the source of @code{deprecated_api} itself (since the latter would defeat the
purpose of the warning message).

The `skip_file_prefixes' keyword argument can be used to indicate which
stack frames are ignored when counting stack levels. This can be useful when
you want the warning to always appear at call sites outside of a package
when a constant `stacklevel' does not fit all call paths or is otherwise
challenging to maintain. If supplied, it must be a tuple of strings. When
prefixes are supplied, stacklevel is implicitly overridden to be @code{max(2,
stacklevel)}. To cause a warning to be attributed to the caller from
outside of the current package you might write:

@example
# example/lower.py
_warn_skips = (os.path.dirname(__file__),)

def one_way(r_luxury_yacht=None, t_wobbler_mangrove=None):
    if r_luxury_yacht:
        warnings.warn("Please migrate to t_wobbler_mangrove=.",
                      skip_file_prefixes=_warn_skips)

# example/higher.py
from . import lower

def another_way(**kw):
    lower.one_way(**kw)
@end example

This makes the warning refer to both the @code{example.lower.one_way()} and
@code{package.higher.another_way()} call sites only from calling code living
outside of @code{example} package.

`source', s'il est fourni, est l'objet détruit qui a émis un @ref{241,,ResourceWarning}.


Modifié dans la version 3.6: Ajout du paramètre `source'.



Modifié dans la version 3.12: Added `skip_file_prefixes'.

@end deffn

@geindex warn_explicit() (dans le module warnings)
@anchor{library/warnings warnings warn_explicit}@anchor{cee}
@deffn {Fonction} warnings.warn_explicit (message, category, filename, lineno, module=None, registry=None, module_globals=None, source=None)

Il s'agit d'une interface de bas niveau pour la fonctionnalité de @ref{14d0,,warn()}, en passant explicitement le message, la catégorie, le nom de fichier et le numéro de ligne, et éventuellement le nom du module et le registre (qui devrait être le dictionnaire @code{__warningregistry__} du module).  Le nom de module par défaut est le nom de fichier sans @code{.py} ; si aucun registre n'est passé, l'avertissement n'est jamais supprimé. `message' doit être une chaîne de caractères et `category' une sous-classe de @ref{2239,,Warning} ou `message' peut être une instance de @ref{2239,,Warning}, auquel cas `category' sera ignoré.

`module_globals', s'il est fourni, doit être l'espace de nommage global utilisé par le code pour lequel l'avertissement est émis.  (Cet argument est utilisé pour afficher les sources des modules trouvés dans les fichiers zip ou d'autres sources d'importation hors du système de fichiers).

`source', s'il est fourni, est l'objet détruit qui a émis un @ref{241,,ResourceWarning}.


Modifié dans la version 3.6: Ajout du paramètre `source'.

@end deffn

@geindex showwarning() (dans le module warnings)
@anchor{library/warnings warnings showwarning}@anchor{4316}
@deffn {Fonction} warnings.showwarning (message, category, filename, lineno, file=None, line=None)

Écrit un avertissement dans un fichier.  L'implémentation par défaut appelle @code{formatwarning(message, category, filename, lineno, line)} et écrit la chaîne résultante dans `file', qui par défaut est @ref{926,,sys.stderr}.  Vous pouvez remplacer cette fonction par n'importe quel appelable en l'affectant à @code{warnings.showwarning}. `line' est une ligne de code source à inclure dans le message d'avertissement ; si `line' n'est pas fourni, @ref{4316,,showwarning()} essaiera de lire la ligne spécifiée par `filename' et `lineno'.
@end deffn

@geindex formatwarning() (dans le module warnings)
@anchor{library/warnings warnings formatwarning}@anchor{19a3}
@deffn {Fonction} warnings.formatwarning (message, category, filename, lineno, line=None)

Formate un avertissement de la manière standard.  Ceci renvoie une chaîne pouvant contenir des retours à la ligne se termine par un retour à la ligne.  `line' est une ligne de code source à inclure dans le message d'avertissement ; si `line' n'est pas fourni, @ref{19a3,,formatwarning()} essaiera de lire la ligne spécifiée par `filename' et `lineno'.
@end deffn

@geindex filterwarnings() (dans le module warnings)
@anchor{library/warnings warnings filterwarnings}@anchor{145d}
@deffn {Fonction} warnings.filterwarnings (action, message='@w{'}, category=Warning, module='@w{'}, lineno=0, append=False)

Insère une entrée dans la liste de @ref{8b6,,warning filter specifications}.  L'entrée est insérée à l'avant par défaut ; si `append' est vrai, elle est insérée à la fin.  Il vérifie le type des arguments, compile les expressions régulières `message' et `module', et les insère sous forme de `n'-uplet dans la liste des filtres d'avertissements.  Les entrées plus proches du début de la liste ont priorité sur les entrées plus loin dans la liste.  Les arguments omis ont par défaut une valeur qui correspond à tout.
@end deffn

@geindex simplefilter() (dans le module warnings)
@anchor{library/warnings warnings simplefilter}@anchor{6ac}
@deffn {Fonction} warnings.simplefilter (action, category=Warning, lineno=0, append=False)

Insère une entrée simple dans la liste de @ref{8b6,,spécifications du filtre d'avertissements}.  La signification des paramètres de fonction est la même que pour @ref{145d,,filterwarnings()}, mais les expressions régulières ne sont pas nécessaires car le filtre inséré correspond toujours à n'importe quel message dans n'importe quel module tant que la catégorie et le numéro de ligne correspondent.
@end deffn

@geindex resetwarnings() (dans le module warnings)
@anchor{library/warnings warnings resetwarnings}@anchor{4315}
@deffn {Fonction} warnings.resetwarnings ()

Réinitialise le filtre des avertissements.  Ceci supprime l'effet de tous les appels précédents à @ref{145d,,filterwarnings()}, y compris celui de l'option @ref{8b4,,-W} des options de ligne de commande et des appels à @ref{6ac,,simplefilter()}.
@end deffn

@geindex deprecated() (dans le module warnings)
@anchor{library/warnings warnings deprecated}@anchor{15f}
@deffn {Fonction} @@warnings.deprecated (msg, *, category=DeprecationWarning, stacklevel=1)

Decorator to indicate that a class, function or overload is deprecated.

When this decorator is applied to an object,
deprecation warnings may be emitted at runtime when the object is used.
@ref{26a,,static type checkers}
will also generate a diagnostic on usage of the deprecated object.

Utilisation :

@example
from warnings import deprecated
from typing import overload

@@deprecated("Use B instead")
class A:
    pass

@@deprecated("Use g instead")
def f():
    pass

@@overload
@@deprecated("int support is deprecated")
def g(x: int) -> int: ...
@@overload
def g(x: str) -> int: ...
@end example

The warning specified by `category' will be emitted at runtime
on use of deprecated objects. For functions, that happens on calls;
for classes, on instantiation and on creation of subclasses.
If the `category' is @code{None}, no warning is emitted at runtime.
The `stacklevel' determines where the
warning is emitted. If it is @code{1} (the default), the warning
is emitted at the direct caller of the deprecated object; if it
is higher, it is emitted further up the stack.
Static type checker behavior is not affected by the `category'
and `stacklevel' arguments.

The deprecation message passed to the decorator is saved in the
@code{__deprecated__} attribute on the decorated object.
If applied to an overload, the decorator
must be after the @ref{3ee5,,@@overload} decorator
for the attribute to exist on the overload as returned by
@ref{699,,typing.get_overloads()}.


Ajouté dans la version 3.13: See 
@geindex Python Enhancement Proposals; PEP 702
PEP 702@footnote{https://peps.python.org/pep-0702/}.

@end deffn

@node Gestionnaires de contexte disponibles,,Fonctions disponibles,warnings --- Warning control
@anchor{library/warnings available-context-managers}@anchor{4327}
@subsubsection Gestionnaires de contexte disponibles


@geindex catch_warnings (classe dans warnings)
@anchor{library/warnings warnings catch_warnings}@anchor{570}
@deffn {Classe} warnings.catch_warnings (*, record=False, module=None, action=None, category=Warning, lineno=0, append=False)

Un gestionnaire de contexte qui copie et, à la sortie, restaure le filtre des avertissements et la fonction @ref{4316,,showwarning()}. Si l'argument `record' est @ref{b25,,False} (par défaut), le gestionnaire de contexte retourne @ref{660,,None} en entrant. Si `record' est @ref{bfb,,True}, une liste est renvoyée qui est progressivement remplie d'objets comme vus par une fonction custom @code{showwarning' (qui supprime également la sortie vers `@w{`}sys.stdout`()}). Chaque objet de la liste a des attributs avec les mêmes noms que les arguments de @ref{4316,,showwarning()}.

L'argument `module' prend un module qui sera utilisé à la place du module renvoyé lors de l'importation @ref{111,,warnings} dont le filtre sera protégé. Cet argument existe principalement pour tester le module @ref{111,,warnings} lui-même.

If the `action' argument is not @code{None}, the remaining arguments are
passed to @ref{6ac,,simplefilter()} as if it were called immediately on
entering the context.

See @ref{8b6,,Le filtre des avertissements} for the meaning of the `category' and `lineno'
parameters.

@cartouche
@quotation Note 
Le gestionnaire @ref{570,,catch_warnings} fonctionne en remplaçant puis en restaurant plus tard la fonction @ref{4316,,showwarning()} du module et la liste interne des spécifications du filtre. Cela signifie que le gestionnaire de contexte modifie l'état global et n'est donc pas prévisible avec plusieurs fils d'exécution.
@end quotation
@end cartouche


Modifié dans la version 3.11: Added the `action', `category', `lineno', and `append' parameters.

@end deffn

@node dataclasses --- Data Classes,contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with,warnings --- Warning control,Environnement d'exécution Python
@anchor{library/dataclasses doc}@anchor{4328}@anchor{library/dataclasses dataclasses-data-classes}@anchor{4329}@anchor{library/dataclasses module-dataclasses}@anchor{2f}
@subsection @code{dataclasses} --- Data Classes


@geindex module; dataclasses

`Code source :' Lib/dataclasses.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dataclasses.py}


__________________________________________________________________


This module provides a decorator and functions for automatically
adding generated @ref{1839,,special methods} such as @ref{69b,,__init__()} and
@ref{607,,__repr__()} to user-defined classes.  It was originally described
in 
@geindex Python Enhancement Proposals; PEP 557
PEP 557@footnote{https://peps.python.org/pep-0557/}.

Les variables membres à utiliser dans ces méthodes générées sont définies en utilisant les annotations de type 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}.  Par exemple :

@example
from dataclasses import dataclass

@@dataclass
class InventoryItem:
    """Class for keeping track of an item in inventory."""
    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand
@end example

will add, among other things, a @code{__init__()} that looks like:

@example
def __init__(self, name: str, unit_price: float, quantity_on_hand: int = 0):
    self.name = name
    self.unit_price = unit_price
    self.quantity_on_hand = quantity_on_hand
@end example

Note that this method is automatically added to the class: it is not
directly specified in the @code{InventoryItem} definition shown above.


Ajouté dans la version 3.7.


@menu
* Classe de données: Classe de données<2>. 
* Post-initialisation:: 
* Variables de classe:: 
* Variables d'initialisation:: 
* Instances figées:: 
* Héritage: Héritage<2>. 
* Re-ordering of keyword-only parameters in __init__(): Re-ordering of keyword-only parameters in __init__. 
* Fabriques de valeurs par défaut:: 
* Valeurs par défaut mutables:: 
* Descriptor-typed fields:: 

@end menu

@node Classe de données<2>,Post-initialisation,,dataclasses --- Data Classes
@anchor{library/dataclasses module-contents}@anchor{432a}
@subsubsection Classe de données


@geindex dataclass() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses dataclass}@anchor{1c6}
@deffn {Fonction} @@dataclasses.dataclass (*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)

This function is a @ref{71b,,decorator} that is used to add generated
@ref{1839,,special methods} to classes, as described below.

The @code{@@dataclass} decorator examines the class to find
@code{field}s.  A @code{field} is defined as a class variable that has a
@ref{d43,,type annotation}.  With two
exceptions described below, nothing in @code{@@dataclass}
examines the type specified in the variable annotation.

L’ordre des paramètres des méthodes générées est celui d’apparition des champs dans la définition de la classe.

The @code{@@dataclass} decorator will add various "dunder" methods to
the class, described below.  If any of the added methods already
exist in the class, the behavior depends on the parameter, as documented
below. The decorator returns the same class that it is called on; no new
class is created.

If @code{@@dataclass} is used just as a simple decorator with no parameters,
it acts as if it has the default values documented in this
signature.  That is, these three uses of @code{@@dataclass} are
equivalent:

@example
@@dataclass
class C:
    ...

@@dataclass()
class C:
    ...

@@dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False,
           match_args=True, kw_only=False, slots=False, weakref_slot=False)
class C:
    ...
@end example

The parameters to @code{@@dataclass} are:


@itemize -

@item 
`init': If true (the default), a @ref{69b,,__init__()} method will be
generated.

If the class already defines @code{__init__()}, this parameter is
ignored.

@item 
`repr': If true (the default), a @ref{607,,__repr__()} method will be
generated.  The generated repr string will have the class name and
the name and repr of each field, in the order they are defined in
the class.  Fields that are marked as being excluded from the repr
are not included.  For example:
@code{InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)}.

If the class already defines @code{__repr__()}, this parameter is
ignored.

@item 
`eq': If true (the default), an @ref{ae8,,__eq__()} method will be
generated.  This method compares the class as if it were a tuple
of its fields, in order.  Both instances in the comparison must
be of the identical type.

If the class already defines @code{__eq__()}, this parameter is
ignored.

@item 
`order': If true (the default is @code{False}), @ref{127d,,__lt__()},
@ref{12e9,,__le__()}, @ref{12ea,,__gt__()}, and @ref{12eb,,__ge__()} methods will be
generated.  These compare the class as if it were a tuple of its
fields, in order.  Both instances in the comparison must be of the
identical type.  If `order' is true and `eq' is false, a
@ref{1ff,,ValueError} is raised.

If the class already defines any of @code{__lt__()},
@code{__le__()}, @code{__gt__()}, or @code{__ge__()}, then
@ref{522,,TypeError} is raised.

@item 
`unsafe_hash': If @code{False} (the default), a @ref{ae9,,__hash__()} method
is generated according to how `eq' and `frozen' are set.

@code{__hash__()} is used by built-in @ref{5d5,,hash()}, and when objects are
added to hashed collections such as dictionaries and sets.  Having a
@code{__hash__()} implies that instances of the class are immutable.
Mutability is a complicated property that depends on the programmer's
intent, the existence and behavior of @code{__eq__()}, and the values of
the `eq' and `frozen' flags in the @code{@@dataclass} decorator.

By default, @code{@@dataclass} will not implicitly add a @ref{ae9,,__hash__()}
method unless it is safe to do so.  Neither will it add or change an
existing explicitly defined @code{__hash__()} method.  Setting the class
attribute @code{__hash__ = None} has a specific meaning to Python, as
described in the @code{__hash__()} documentation.

If @code{__hash__()} is not explicitly defined, or if it is set to @code{None},
then @code{@@dataclass} `may' add an implicit @code{__hash__()} method.
Although not recommended, you can force @code{@@dataclass} to create a
@code{__hash__()} method with @code{unsafe_hash=True}. This might be the case
if your class is logically immutable but can still be mutated.
This is a specialized use case and should be considered carefully.

Here are the rules governing implicit creation of a @code{__hash__()}
method.  Note that you cannot both have an explicit @code{__hash__()}
method in your dataclass and set @code{unsafe_hash=True}; this will result
in a @ref{522,,TypeError}.

If `eq' and `frozen' are both true, by default @code{@@dataclass} will
generate a @code{__hash__()} method for you.  If `eq' is true and
`frozen' is false, @code{__hash__()} will be set to @code{None}, marking it
unhashable (which it is, since it is mutable).  If `eq' is false,
@code{__hash__()} will be left untouched meaning the @code{__hash__()}
method of the superclass will be used (if the superclass is
@ref{a7a,,object}, this means it will fall back to id-based hashing).

@item 
`frozen': If true (the default is @code{False}), assigning to fields will
generate an exception.  This emulates read-only frozen instances.  If
@ref{1eb2,,__setattr__()} or @ref{1eb3,,__delattr__()} is defined in the class, then
@ref{522,,TypeError} is raised.  See the discussion below.

@item 
`match_args': If true (the default is @code{True}), the
@ref{184d,,__match_args__} tuple will be created from the list of
parameters to the generated @ref{69b,,__init__()} method (even if
@code{__init__()} is not generated, see above).  If false, or if
@code{__match_args__} is already defined in the class, then
@code{__match_args__} will not be generated.
@end itemize

@quotation


Ajouté dans la version 3.10.

@end quotation


@itemize -

@item 
`kw_only': If true (the default value is @code{False}), then all
fields will be marked as keyword-only.  If a field is marked as
keyword-only, then the only effect is that the @ref{69b,,__init__()}
parameter generated from a keyword-only field must be specified
with a keyword when @code{__init__()} is called.  There is no
effect on any other aspect of dataclasses.  See the
@ref{1e82,,parameter} glossary entry for details.  Also see the
@ref{432b,,KW_ONLY} section.
@end itemize

@quotation


Ajouté dans la version 3.10.

@end quotation


@itemize -

@item 
`slots': If true (the default is @code{False}), @ref{14a0,,__slots__} attribute
will be generated and new class will be returned instead of the original one.
If @code{__slots__} is already defined in the class, then @ref{522,,TypeError}
is raised.
@end itemize

@quotation

@cartouche
@quotation Avertissement 
Calling no-arg @ref{4c5,,super()} in dataclasses using @code{slots=True}
will result in the following exception being raised:
@code{TypeError: super(type, obj): obj must be an instance or subtype of type}.
The two-arg @ref{4c5,,super()} is a valid workaround.
See gh-90562@footnote{https://github.com/python/cpython/issues/90562} for full details.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Passing parameters to a base class @ref{61c,,__init_subclass__()}
when using @code{slots=True} will result in a @ref{522,,TypeError}.
Either use @code{__init_subclass__} with no parameters
or use default values as a workaround.
See gh-91126@footnote{https://github.com/python/cpython/issues/91126} for full details.
@end quotation
@end cartouche


Ajouté dans la version 3.10.



Modifié dans la version 3.11: If a field name is already included in the @code{__slots__}
of a base class, it will not be included in the generated @code{__slots__}
to prevent @ref{1ef1,,overriding them}.
Therefore, do not use @code{__slots__} to retrieve the field names of a
dataclass. Use @ref{16cd,,fields()} instead.
To be able to determine inherited slots,
base class @code{__slots__} may be any iterable, but `not' an iterator.

@end quotation


@itemize -

@item 
`weakref_slot': If true (the default is @code{False}), add a slot
named "__weakref__", which is required to make an instance
@ref{fd9,,weakref-able}.
It is an error to specify @code{weakref_slot=True}
without also specifying @code{slots=True}.
@end itemize

@quotation


Ajouté dans la version 3.11.

@end quotation

Les champs peuvent éventuellement préciser une valeur par défaut, en utilisant la syntaxe Python normale :

@example
@@dataclass
class C:
    a: int       # 'a' has no default value
    b: int = 0   # assign a default value for 'b'
@end example

In this example, both @code{a} and @code{b} will be included in the added
@ref{69b,,__init__()} method, which will be defined as:

@example
def __init__(self, a: int, b: int = 0):
@end example

Une @ref{522,,TypeError} est levée si un champ sans valeur par défaut est défini après un champ avec une valeur par défaut.  C’est le cas que ce soit dans une seule classe ou si c’est le résultat d’un héritage de classes.
@end deffn

@geindex field() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses field}@anchor{19ae}
@deffn {Fonction} dataclasses.field (*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)

For common and simple use cases, no other functionality is
required.  There are, however, some dataclass features that
require additional per-field information.  To satisfy this need for
additional information, you can replace the default field value
with a call to the provided @code{field()} function.  For example:

@example
@@dataclass
class C:
    mylist: list[int] = field(default_factory=list)

c = C()
c.mylist += [1, 2, 3]
@end example

Comme le montre la signature, la constante @ref{432c,,MISSING} est une valeur sentinelle pour déterminer si des paramètres ont été fournis par l'utilisateur. @code{None} ne conviendrait pas puisque c'est une valeur avec un sens qui peut être différent pour certains paramètres. La sentinelle @ref{432c,,MISSING} est interne au module et ne doit pas être utilisée dans vos programmes.

The parameters to @code{field()} are:


@itemize -

@item 
`default': If provided, this will be the default value for this
field.  This is needed because the @code{field()} call itself
replaces the normal position of the default value.

@item 
`default_factory': If provided, it must be a zero-argument
callable that will be called when a default value is needed for
this field.  Among other purposes, this can be used to specify
fields with mutable default values, as discussed below.  It is an
error to specify both `default' and `default_factory'.

@item 
`init': If true (the default), this field is included as a
parameter to the generated @ref{69b,,__init__()} method.

@item 
`repr': If true (the default), this field is included in the
string returned by the generated @ref{607,,__repr__()} method.

@item 
`hash': This can be a bool or @code{None}.  If true, this field is
included in the generated @ref{ae9,,__hash__()} method.  If @code{None} (the
default), use the value of `compare': this would normally be
the expected behavior.  A field should be considered in the hash
if it's used for comparisons.  Setting this value to anything
other than @code{None} is discouraged.

Cependant, une raison légitime de mettre `hash' à @code{False} alors que `compare' est à @code{True} est la concourance de trois facteurs : le champ est coûteux à hacher ; il est nécessaire pour les comparaisons d'égalité ; et il y a déjà d'autres champs qui participent au hachage des instances. À ce moment, on peut alors se passer du champ dans le hachage tout en le faisant participer aux comparaisons.

@item 
`compare': If true (the default), this field is included in the
generated equality and comparison methods (@ref{ae8,,__eq__()},
@ref{12ea,,__gt__()}, et al.).

@item 
`metadata': This can be a mapping or @code{None}. @code{None} is treated as
an empty dict.  This value is wrapped in
@ref{457,,MappingProxyType()} to make it read-only, and exposed
on the @ref{21de,,Field} object. It is not used at all by Data
Classes, and is provided as a third-party extension mechanism.
Multiple third-parties can each have their own key, to use as a
namespace in the metadata.

@item 
`kw_only': If true, this field will be marked as keyword-only.
This is used when the generated @ref{69b,,__init__()} method's
parameters are computed.
@end itemize

@quotation


Ajouté dans la version 3.10.

@end quotation

If the default value of a field is specified by a call to
@code{field()}, then the class attribute for this field will be
replaced by the specified `default' value.  If `default' is not
provided, then the class attribute will be deleted.  The intent is
that after the @ref{1c6,,@@dataclass} decorator runs, the class
attributes will all contain the default values for the fields, just
as if the default value itself were specified.  For example,
after:

@example
@@dataclass
class C:
    x: int
    y: int = field(repr=False)
    z: int = field(repr=False, default=10)
    t: int = 20
@end example

The class attribute @code{C.z} will be @code{10}, the class attribute
@code{C.t} will be @code{20}, and the class attributes @code{C.x} and
@code{C.y} will not be set.
@end deffn

@geindex Field (classe dans dataclasses)
@anchor{library/dataclasses dataclasses Field}@anchor{21de}
@deffn {Classe} dataclasses.Field

@code{Field} objects describe each defined field. These objects
are created internally, and are returned by the @ref{16cd,,fields()}
module-level method (see below).  Users should never instantiate a
@code{Field} object directly.  Its documented attributes are:


@itemize -

@item 
@code{name}: The name of the field.

@item 
@code{type}: The type of the field.

@item 
@code{default}, @code{default_factory}, @code{init}, @code{repr}, @code{hash},
@code{compare}, @code{metadata}, and @code{kw_only} have the identical
meaning and values as they do in the @ref{19ae,,field()} function.
@end itemize

D'autres attributs peuvent exister, mais ils sont privés et ne sont pas censés être inspectés. Le code ne doit jamais reposer sur eux.
@end deffn

@geindex fields() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses fields}@anchor{16cd}
@deffn {Fonction} dataclasses.fields (class_or_instance)

Renvoie un `n'-uplet d'objets @ref{21de,,Field} correspondant aux champs de l'argument, à l'exclusion des pseudo-champs @code{ClassVar} ou @code{InitVar}. L'argument peut être soit une classe de données, soit une instance d'une telle classe ; si ce n'est pas le cas, une exception @ref{522,,TypeError} est levée.
@end deffn

@geindex asdict() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses asdict}@anchor{16af}
@deffn {Fonction} dataclasses.asdict (obj, *, dict_factory=dict)

Converts the dataclass `obj' to a dict (by using the
factory function `dict_factory').  Each dataclass is converted
to a dict of its fields, as @code{name: value} pairs.  dataclasses, dicts,
lists, and tuples are recursed into.  Other objects are copied with
@ref{b5c,,copy.deepcopy()}.

Example of using @code{asdict()} on nested dataclasses:

@example
@@dataclass
class Point:
     x: int
     y: int

@@dataclass
class C:
     mylist: list[Point]

p = Point(10, 20)
assert asdict(p) == @{'x': 10, 'y': 20@}

c = C([Point(0, 0), Point(10, 4)])
assert asdict(c) == @{'mylist': [@{'x': 0, 'y': 0@}, @{'x': 10, 'y': 4@}]@}
@end example

Pour créer une copie superficielle, la solution de contournement suivante peut être utilisée :

@example
@{field.name: getattr(obj, field.name) for field in fields(obj)@}
@end example

@code{asdict()} raises @ref{522,,TypeError} if `obj' is not a dataclass
instance.
@end deffn

@geindex astuple() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses astuple}@anchor{16b8}
@deffn {Fonction} dataclasses.astuple (obj, *, tuple_factory=tuple)

Converts the dataclass `obj' to a tuple (by using the
factory function `tuple_factory').  Each dataclass is converted
to a tuple of its field values.  dataclasses, dicts, lists, and
tuples are recursed into. Other objects are copied with
@ref{b5c,,copy.deepcopy()}.

Pour continuer l'exemple précédent :

@example
assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)
@end example

Pour créer une copie superficielle, la solution de contournement suivante peut être utilisée :

@example
tuple(getattr(obj, field.name) for field in dataclasses.fields(obj))
@end example

@code{astuple()} raises @ref{522,,TypeError} if `obj' is not a dataclass
instance.
@end deffn

@geindex make_dataclass() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses make_dataclass}@anchor{16cf}
@deffn {Fonction} dataclasses.make_dataclass (cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False, module=None)

Creates a new dataclass with name `cls_name', fields as defined
in `fields', base classes as given in `bases', and initialized
with a namespace as given in `namespace'.  `fields' is an
iterable whose elements are each either @code{name}, @code{(name, type)},
or @code{(name, type, Field)}.  If just @code{name} is supplied,
@ref{697,,typing.Any} is used for @code{type}.  The values of `init',
`repr', `eq', `order', `unsafe_hash', `frozen',
`match_args', `kw_only', `slots', and `weakref_slot' have
the same meaning as they do in @ref{1c6,,@@dataclass}.

If `module' is defined, the @code{__module__} attribute
of the dataclass is set to that value.
By default, it is set to the module name of the caller.

This function is not strictly required, because any Python
mechanism for creating a new class with @code{__annotations__} can
then apply the @ref{1c6,,@@dataclass} function to convert that class to
a dataclass.  This function is provided as a convenience.  For
example:

@example
C = make_dataclass('C',
                   [('x', int),
                     'y',
                    ('z', int, field(default=5))],
                   namespace=@{'add_one': lambda self: self.x + 1@})
@end example

est équivalent à :

@example
@@dataclass
class C:
    x: int
    y: 'typing.Any'
    z: int = 5

    def add_one(self):
        return self.x + 1
@end example
@end deffn

@geindex replace() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses replace}@anchor{1682}
@deffn {Fonction} dataclasses.replace (obj, /, **changes)

Creates a new object of the same type as `obj', replacing
fields with values from `changes'.  If `obj' is not a Data
Class, raises @ref{522,,TypeError}.  If keys in `changes' are not
field names of the given dataclass, raises @ref{522,,TypeError}.

The newly returned object is created by calling the @ref{69b,,__init__()}
method of the dataclass.  This ensures that
@ref{432d,,__post_init__()}, if present, is also called.

Init-only variables without default values, if any exist, must be
specified on the call to @code{replace()} so that they can be passed to
@code{__init__()} and @ref{432d,,__post_init__()}.

It is an error for `changes' to contain any fields that are
defined as having @code{init=False}.  A @ref{1ff,,ValueError} will be raised
in this case.

Be forewarned about how @code{init=False} fields work during a call to
@code{replace()}.  They are not copied from the source object, but
rather are initialized in @ref{432d,,__post_init__()}, if they're
initialized at all.  It is expected that @code{init=False} fields will
be rarely and judiciously used.  If they are used, it might be wise
to have alternate class constructors, or perhaps a custom
@code{replace()} (or similarly named) method which handles instance
copying.

Dataclass instances are also supported by generic function @ref{150,,copy.replace()}.
@end deffn

@geindex is_dataclass() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses is_dataclass}@anchor{1800}
@deffn {Fonction} dataclasses.is_dataclass (obj)

Return @code{True} if its parameter is a dataclass (including subclasses of a
dataclass) or an instance of one, otherwise return @code{False}.

Pour vérifier qu'un objet `obj' est une instance d'une classe de données, et non pas lui-même une classe de données, ajoutez le test @code{not isinstance(obj, type)} :

@example
def is_dataclass_instance(obj):
    return is_dataclass(obj) and not isinstance(obj, type)
@end example
@end deffn

@geindex MISSING (dans le module dataclasses)
@anchor{library/dataclasses dataclasses MISSING}@anchor{432c}
@deffn {Données} dataclasses.MISSING

Une valeur sentinelle pour dénoter l'absence de `default' ou `default_factory'.
@end deffn

@geindex KW_ONLY (dans le module dataclasses)
@anchor{library/dataclasses dataclasses KW_ONLY}@anchor{432b}
@deffn {Données} dataclasses.KW_ONLY

A sentinel value used as a type annotation.  Any fields after a
pseudo-field with the type of @code{KW_ONLY} are marked as
keyword-only fields.  Note that a pseudo-field of type
@code{KW_ONLY} is otherwise completely ignored.  This includes the
name of such a field.  By convention, a name of @code{_} is used for a
@code{KW_ONLY} field.  Keyword-only fields signify
@ref{69b,,__init__()} parameters that must be specified as keywords when
the class is instantiated.

Dans cet exemple @code{y} et @code{z} sont marqués comme exclusivement nommés :

@example
@@dataclass
class Point:
    x: float
    _: KW_ONLY
    y: float
    z: float

p = Point(0, y=1.5, z=2.0)
@end example

In a single dataclass, it is an error to specify more than one
field whose type is @code{KW_ONLY}.


Ajouté dans la version 3.10.

@end deffn

@geindex FrozenInstanceError
@anchor{library/dataclasses dataclasses FrozenInstanceError}@anchor{432e}
@deffn {Exception} dataclasses.FrozenInstanceError

Raised when an implicitly defined @ref{1eb2,,__setattr__()} or
@ref{1eb3,,__delattr__()} is called on a dataclass which was defined with
@code{frozen=True}. It is a subclass of @ref{343,,AttributeError}.
@end deffn

@node Post-initialisation,Variables de classe,Classe de données<2>,dataclasses --- Data Classes
@anchor{library/dataclasses id1}@anchor{432f}@anchor{library/dataclasses post-init-processing}@anchor{4330}
@subsubsection Post-initialisation


@geindex __post_init__() (dans le module dataclasses)
@anchor{library/dataclasses dataclasses __post_init__}@anchor{432d}
@deffn {Fonction} dataclasses.__post_init__ ()

When defined on the class, it will be called by the generated
@ref{69b,,__init__()}, normally as @code{self.__post_init__()}.
However, if any @code{InitVar} fields are defined, they will also be
passed to @code{__post_init__()} in the order they were defined in the
class.  If no @code{__init__()} method is generated, then
@code{__post_init__()} will not automatically be called.

Cette méthode permet, entre autres, d'initialiser des champs qui dépendent d'autres champs. Par exemple :

@example
@@dataclass
class C:
    a: float
    b: float
    c: float = field(init=False)

    def __post_init__(self):
        self.c = self.a + self.b
@end example
@end deffn

The @ref{69b,,__init__()} method generated by @ref{1c6,,@@dataclass} does not call base
class @code{__init__()} methods. If the base class has an @code{__init__()} method
that has to be called, it is common to call this method in a
@ref{432d,,__post_init__()} method:

@example
class Rectangle:
    def __init__(self, height, width):
        self.height = height
        self.width = width

@@dataclass
class Square(Rectangle):
    side: float

    def __post_init__(self):
        super().__init__(self.side, self.side)
@end example

Note, however, that in general the dataclass-generated @code{__init__()} methods
don't need to be called, since the derived dataclass will take care of
initializing all fields of any base class that is a dataclass itself.

See the section below on init-only variables for ways to pass
parameters to @code{__post_init__()}.  Also see the warning about how
@ref{1682,,replace()} handles @code{init=False} fields.

@node Variables de classe,Variables d'initialisation,Post-initialisation,dataclasses --- Data Classes
@anchor{library/dataclasses class-variables}@anchor{4331}@anchor{library/dataclasses dataclasses-class-variables}@anchor{4332}
@subsubsection Variables de classe


One of the few places where @ref{1c6,,@@dataclass} actually inspects the type
of a field is to determine if a field is a class variable as defined
in 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}.  It does this by checking if the type of the field is
@ref{263,,typing.ClassVar}.  If a field is a @code{ClassVar}, it is excluded
from consideration as a field and is ignored by the dataclass
mechanisms.  Such @code{ClassVar} pseudo-fields are not returned by the
module-level @ref{16cd,,fields()} function.

@node Variables d'initialisation,Instances figées,Variables de classe,dataclasses --- Data Classes
@anchor{library/dataclasses dataclasses-init-only-variables}@anchor{4333}@anchor{library/dataclasses init-only-variables}@anchor{4334}
@subsubsection Variables d'initialisation


Another place where @ref{1c6,,@@dataclass} inspects a type annotation is to
determine if a field is an init-only variable.  It does this by seeing
if the type of a field is of type @code{dataclasses.InitVar}.  If a field
is an @code{InitVar}, it is considered a pseudo-field called an init-only
field.  As it is not a true field, it is not returned by the
module-level @ref{16cd,,fields()} function.  Init-only fields are added as
parameters to the generated @ref{69b,,__init__()} method, and are passed to
the optional @ref{432d,,__post_init__()} method.  They are not otherwise used
by dataclasses.

On peut par exemple imaginer un champ initialisé à partir d'une base de données s'il n'a pas reçu de valeur explicite :

@example
@@dataclass
class C:
    i: int
    j: int | None = None
    database: InitVar[DatabaseType | None] = None

    def __post_init__(self, database):
        if self.j is None and database is not None:
            self.j = database.lookup('j')

c = C(10, database=my_database)
@end example

In this case, @ref{16cd,,fields()} will return @ref{21de,,Field} objects for @code{i} and
@code{j}, but not for @code{database}.

@node Instances figées,Héritage<2>,Variables d'initialisation,dataclasses --- Data Classes
@anchor{library/dataclasses dataclasses-frozen}@anchor{4335}@anchor{library/dataclasses frozen-instances}@anchor{4336}
@subsubsection Instances figées


It is not possible to create truly immutable Python objects.  However,
by passing @code{frozen=True} to the @ref{1c6,,@@dataclass} decorator you can
emulate immutability.  In that case, dataclasses will add
@ref{1eb2,,__setattr__()} and @ref{1eb3,,__delattr__()} methods to the class.  These
methods will raise a @ref{432e,,FrozenInstanceError} when invoked.

There is a tiny performance penalty when using @code{frozen=True}:
@ref{69b,,__init__()} cannot use simple assignment to initialize fields, and
must use @code{object.__setattr__()}.

@c Make sure to not remove "object" from "object.__setattr__" in the above markup!

@node Héritage<2>,Re-ordering of keyword-only parameters in __init__,Instances figées,dataclasses --- Data Classes
@anchor{library/dataclasses dataclasses-inheritance}@anchor{4337}@anchor{library/dataclasses inheritance}@anchor{4338}
@subsubsection Héritage


When the dataclass is being created by the @ref{1c6,,@@dataclass} decorator,
it looks through all of the class's base classes in reverse MRO (that
is, starting at @ref{a7a,,object}) and, for each dataclass that it finds,
adds the fields from that base class to an ordered mapping of fields.
After all of the base class fields are added, it adds its own fields
to the ordered mapping.  All of the generated methods will use this
combined, calculated ordered mapping of fields.  Because the fields
are in insertion order, derived classes override base classes.  An
example:

@example
@@dataclass
class Base:
    x: Any = 15.0
    y: int = 0

@@dataclass
class C(Base):
    z: int = 10
    x: int = 15
@end example

The final list of fields is, in order, @code{x}, @code{y}, @code{z}.  The final
type of @code{x} is @ref{254,,int}, as specified in class @code{C}.

The generated @ref{69b,,__init__()} method for @code{C} will look like:

@example
def __init__(self, x: int = 15, y: int = 0, z: int = 10):
@end example

@node Re-ordering of keyword-only parameters in __init__,Fabriques de valeurs par défaut,Héritage<2>,dataclasses --- Data Classes
@anchor{library/dataclasses re-ordering-of-keyword-only-parameters-in-init}@anchor{4339}
@subsubsection Re-ordering of keyword-only parameters in @code{__init__()}


After the parameters needed for @ref{69b,,__init__()} are computed, any
keyword-only parameters are moved to come after all regular
(non-keyword-only) parameters.  This is a requirement of how
keyword-only parameters are implemented in Python: they must come
after non-keyword-only parameters.

In this example, @code{Base.y}, @code{Base.w}, and @code{D.t} are keyword-only
fields, and @code{Base.x} and @code{D.z} are regular fields:

@example
@@dataclass
class Base:
    x: Any = 15.0
    _: KW_ONLY
    y: int = 0
    w: int = 1

@@dataclass
class D(Base):
    z: int = 10
    t: int = field(kw_only=True, default=0)
@end example

The generated @code{__init__()} method for @code{D} will look like:

@example
def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, w: int = 1, t: int = 0):
@end example

Les paramètres ont été réarrangés par rapport à leur ordre d'apparition dans la liste des champs : les paramètres provenant des attributs normaux sont suivis par les paramètres qui proviennent des attributs exclusivement nommés.

The relative ordering of keyword-only parameters is maintained in the
re-ordered @code{__init__()} parameter list.

@node Fabriques de valeurs par défaut,Valeurs par défaut mutables,Re-ordering of keyword-only parameters in __init__,dataclasses --- Data Classes
@anchor{library/dataclasses default-factory-functions}@anchor{433a}
@subsubsection Fabriques de valeurs par défaut


If a @ref{19ae,,field()} specifies a `default_factory', it is called with
zero arguments when a default value for the field is needed.  For
example, to create a new instance of a list, use:

@example
mylist: list = field(default_factory=list)
@end example

If a field is excluded from @ref{69b,,__init__()} (using @code{init=False})
and the field also specifies `default_factory', then the default
factory function will always be called from the generated
@code{__init__()} function.  This happens because there is no other
way to give the field an initial value.

@node Valeurs par défaut mutables,Descriptor-typed fields,Fabriques de valeurs par défaut,dataclasses --- Data Classes
@anchor{library/dataclasses mutable-default-values}@anchor{433b}
@subsubsection Valeurs par défaut mutables


En Python, les valeurs par défaut des attributs sont stockées dans des attributs de la classe. Observez cet exemple, sans classe de données :

@example
class C:
    x = []
    def add(self, element):
        self.x.append(element)

o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x
@end example

Note that the two instances of class @code{C} share the same class
variable @code{x}, as expected.

Avec les classes de données, si ce code était valide :

@example
@@dataclass
class D:
    x: list = []      # This code raises ValueError
    def add(self, element):
        self.x.append(element)
@end example

il générerait un code équivalent à :

@example
class D:
    x = []
    def __init__(self, x=x):
        self.x = x
    def add(self, element):
        self.x.append(element)

assert D().x is D().x
@end example

This has the same issue as the original example using class @code{C}.
That is, two instances of class @code{D} that do not specify a value
for @code{x} when creating a class instance will share the same copy
of @code{x}.  Because dataclasses just use normal Python class
creation they also share this behavior.  There is no general way
for Data Classes to detect this condition.  Instead, the
@ref{1c6,,@@dataclass} decorator will raise a @ref{1ff,,ValueError} if it
detects an unhashable default parameter.  The assumption is that if
a value is unhashable, it is mutable.  This is a partial solution,
but it does protect against many common errors.

Pour qu'un champ d'un type mutable soit par défaut initialisé à un nouvel objet pour chaque instance, utilisez une fonction de fabrique :

@example
@@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x
@end example


Modifié dans la version 3.11: Instead of looking for and disallowing objects of type @ref{5fc,,list},
@ref{253,,dict}, or @ref{5c3,,set}, unhashable objects are now not allowed as
default values.  Unhashability is used to approximate
mutability.


@node Descriptor-typed fields,,Valeurs par défaut mutables,dataclasses --- Data Classes
@anchor{library/dataclasses descriptor-typed-fields}@anchor{433c}
@subsubsection Descriptor-typed fields


Fields that are assigned @ref{c3d,,descriptor objects} as their
default value have the following special behaviors:


@itemize *

@item 
The value for the field passed to the dataclass's @ref{69b,,__init__()} method is
passed to the descriptor's @ref{1eec,,__set__()} method rather than overwriting the
descriptor object.

@item 
Similarly, when getting or setting the field, the descriptor's
@ref{149d,,__get__()} or @code{__set__()} method is called rather than returning or
overwriting the descriptor object.

@item 
To determine whether a field contains a default value, @ref{1c6,,@@dataclass}
will call the descriptor's @code{__get__()} method using its class access
form: @code{descriptor.__get__(obj=None, type=cls)}.  If the
descriptor returns a value in this case, it will be used as the
field's default. On the other hand, if the descriptor raises
@ref{343,,AttributeError} in this situation, no default value will be
provided for the field.
@end itemize

@example
class IntConversionDescriptor:
    def __init__(self, *, default):
        self._default = default

    def __set_name__(self, owner, name):
        self._name = "_" + name

    def __get__(self, obj, type):
        if obj is None:
            return self._default

        return getattr(obj, self._name, self._default)

    def __set__(self, obj, value):
        setattr(obj, self._name, int(value))

@@dataclass
class InventoryItem:
    quantity_on_hand: IntConversionDescriptor = IntConversionDescriptor(default=100)

i = InventoryItem()
print(i.quantity_on_hand)   # 100
i.quantity_on_hand = 2.5    # calls __set__ with 2.5
print(i.quantity_on_hand)   # 2
@end example

Note that if a field is annotated with a descriptor type, but is not assigned
a descriptor object as its default value, the field will act like a normal
field.

@node contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with,abc --- Abstract Base Classes,dataclasses --- Data Classes,Environnement d'exécution Python
@anchor{library/contextlib doc}@anchor{433d}@anchor{library/contextlib contextlib-utilities-for-with-statement-contexts}@anchor{433e}@anchor{library/contextlib module-contextlib}@anchor{23}
@subsection @code{contextlib} — Utilitaires pour les contextes s'appuyant sur l'instruction @code{with}


@geindex module; contextlib

`Code source :' Lib/contextlib.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/contextlib.py}


__________________________________________________________________


Ce module fournit des utilitaires pour les tâches impliquant le mot-clé @ref{5bc,,with}. Pour plus d'informations voir aussi @ref{1f42,,Le type gestionnaire de contexte} et @ref{1f40,,Gestionnaire de contexte With}.

@menu
* Utilitaires:: 
* Exemples et Recettes:: 
* Gestionnaires de contexte à usage unique@comma{} réutilisables et réentrants: Gestionnaires de contexte à usage unique réutilisables et réentrants. 

@end menu

@node Utilitaires,Exemples et Recettes,,contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with
@anchor{library/contextlib utilities}@anchor{433f}
@subsubsection Utilitaires


Fonctions et classes fournies :

@geindex AbstractContextManager (classe dans contextlib)
@anchor{library/contextlib contextlib AbstractContextManager}@anchor{c7b}
@deffn {Classe} contextlib.AbstractContextManager

@ref{1193,,Classe mère abstraite} pour les classes qui implémentent les méthodes @ref{5b2,,object.__enter__()} et @ref{12de,,object.__exit__()}. Une implémentation par défaut de @ref{5b2,,object.__enter__()} est fournie, qui renvoie @code{self}, et @ref{12de,,object.__exit__()} est une méthode abstraite qui renvoie @code{None} par défaut. Voir aussi la définition de @ref{1f42,,Le type gestionnaire de contexte}.


Ajouté dans la version 3.6.

@end deffn

@geindex AbstractAsyncContextManager (classe dans contextlib)
@anchor{library/contextlib contextlib AbstractAsyncContextManager}@anchor{b19}
@deffn {Classe} contextlib.AbstractAsyncContextManager

@ref{1193,,Classe mère abstraite} pour les classes qui implémentent les méthodes @ref{1f53,,object.__aenter__()} et @ref{15b3,,object.__aexit__()}. Une implémentation par défaut de @ref{1f53,,object.__aenter__()} est fournie, qui renvoie @code{self}, et @ref{15b3,,object.__aexit__()} est une méthode abstraite qui renvoie @code{None} par défaut. Voir aussi la définition de @ref{5e6,,Gestionnaires de contexte asynchrones}.


Ajouté dans la version 3.7.

@end deffn

@geindex contextmanager() (dans le module contextlib)
@anchor{library/contextlib contextlib contextmanager}@anchor{11df}
@deffn {Fonction} @@contextlib.contextmanager

This function is a @ref{71b,,decorator} that can be used to define a factory
function for @ref{5bc,,with} statement context managers, without needing to
create a class or separate @ref{5b2,,__enter__()} and @ref{12de,,__exit__()} methods.

Alors que de nombreux objets s'utilisent nativement dans des blocs `with', on trouve parfois des ressources qui nécessitent d'être gérées mais ne sont pas des gestionnaires de contextes, et qui n'implémentent pas de méthode @code{close()} pour pouvoir être utilisées avec @code{contextlib.closing}

L'exemple abstrait suivant présente comment assurer une gestion correcte des ressources :

@example
from contextlib import contextmanager

@@contextmanager
def managed_resource(*args, **kwds):
    # Code to acquire resource, e.g.:
    resource = acquire_resource(*args, **kwds)
    try:
        yield resource
    finally:
        # Code to release resource, e.g.:
        release_resource(resource)
@end example

The function can then be used like this:

@example
>>> with managed_resource(timeout=3600) as resource:
...     # Resource is released at the end of this block,
...     # even if code in the block raises an exception
@end example

La fonction à décorer doit renvoyer un @ref{104a,,générateur}-itérateur quand elle est appelée. Ce générateur ne doit produire qu'une seule valeur, qui est récupérée dans le bloc @ref{5bc,,with} à l'aide de la clause @code{as} si précisée.

Au moment où le générateur produit une valeur, le bloc imbriqué sous l'instruction @ref{5bc,,with} est exécuté. Le générateur est ensuite repris après la sortie du bloc. Si une exception non gérée survient dans le bloc, elle est relayée dans le générateur au niveau de l'instruction `yield'. Ainsi, vous pouvez utiliser les instructions @ref{6d3,,try}…@ref{189,,except}…@ref{9b8,,finally} pour attraper l'erreur (s'il y a), ou vous assurer qu'un nettoyage a bien lieu. Si une exception est attrapée dans l'unique but d'être journalisée ou d'effectuer une action particulière (autre que supprimer entièrement l'exception), le générateur se doit de la relayer. Autrement le générateur gestionnaire de contexte doit indiquer à l'instruction @code{with} que l'exception a été gérée, et l'exécution reprend sur l'instruction qui suit directement le bloc @code{with}.

Le décorateur @ref{11df,,contextmanager()} utilise la classe @ref{11de,,ContextDecorator} afin que les gestionnaires de contexte qu'il crée puissent être utilisés aussi bien en tant que décorateurs qu'avec des instructions @ref{5bc,,with}. Quand vous l'utilisez comme décorateur, une nouvelle instance du générateur est créée à chaque appel de la fonction (cela permet aux gestionnaires de contexte à usage unique créés par @ref{11df,,contextmanager()} de remplir la condition de pouvoir être invoqués plusieurs fois afin d'être utilisés comme décorateurs).


Modifié dans la version 3.2: Utilisation de la classe @ref{11de,,ContextDecorator}.

@end deffn

@geindex asynccontextmanager() (dans le module contextlib)
@anchor{library/contextlib contextlib asynccontextmanager}@anchor{b18}
@deffn {Fonction} @@contextlib.asynccontextmanager

Similaire à @ref{11df,,contextmanager()}, mais crée un @ref{5e6,,gestionnaire de contexte asynchrone}.

This function is a @ref{71b,,decorator} that can be used to define a factory
function for @ref{5bf,,async with} statement asynchronous context managers,
without needing to create a class or separate @ref{1f53,,__aenter__()} and
@ref{15b3,,__aexit__()} methods. It must be applied to an @ref{1fba,,asynchronous generator} function.

Un exemple simple :

@example
from contextlib import asynccontextmanager

@@asynccontextmanager
async def get_connection():
    conn = await acquire_db_connection()
    try:
        yield conn
    finally:
        await release_db_connection(conn)

async def get_all_users():
    async with get_connection() as conn:
        return conn.query('SELECT ...')
@end example


Ajouté dans la version 3.7.


Les gestionnaires de contexte définis avec @ref{b18,,asynccontextmanager()} peuvent s'utiliser comme décorateurs ou dans les instructions @ref{5bf,,async with} :

@example
import time
from contextlib import asynccontextmanager

@@asynccontextmanager
async def timeit():
    now = time.monotonic()
    try:
        yield
    finally:
        print(f'it took @{time.monotonic() - now@}s to run')

@@timeit()
async def main():
    # ... async code ...
@end example

When used as a decorator, a new generator instance is implicitly created on
each function call. This allows the otherwise "one-shot" context managers
created by @ref{b18,,asynccontextmanager()} to meet the requirement that context
managers support multiple invocations in order to be used as decorators.


Modifié dans la version 3.10: Async context managers created with @ref{b18,,asynccontextmanager()} can
be used as decorators.

@end deffn

@geindex closing() (dans le module contextlib)
@anchor{library/contextlib contextlib closing}@anchor{28c6}
@deffn {Fonction} contextlib.closing (thing)

Renvoie un gestionnaire de contexte qui ferme `thing' à la fin du bloc. C'est essentiellement équivalent à :

@example
from contextlib import contextmanager

@@contextmanager
def closing(thing):
    try:
        yield thing
    finally:
        thing.close()
@end example

Et cela vous permet d'écrire du code tel que :

@example
from contextlib import closing
from urllib.request import urlopen

with closing(urlopen('https://www.python.org')) as page:
    for line in page:
        print(line)
@end example

sans besoin de fermer explicitement @code{page}. Même si une erreur survient, @code{page.close()} est appelée à la fermeture du bloc @ref{5bc,,with}.

@cartouche
@quotation Note 
Most types managing resources support the @ref{5be,,context manager} protocol,
which closes `thing' on leaving the @ref{5bc,,with} statement.
As such, @code{closing()} is most useful for third party types that don't
support context managers.
This example is purely for illustration purposes,
as @ref{290,,urlopen()} would normally be used in a context manager.
@end quotation
@end cartouche
@end deffn

@geindex aclosing() (dans le module contextlib)
@anchor{library/contextlib contextlib aclosing}@anchor{7d7}
@deffn {Fonction} contextlib.aclosing (thing)

Return an async context manager that calls the @code{aclose()} method of `thing'
upon completion of the block.  This is basically equivalent to:

@example
from contextlib import asynccontextmanager

@@asynccontextmanager
async def aclosing(thing):
    try:
        yield thing
    finally:
        await thing.aclose()
@end example

Significantly, @code{aclosing()} supports deterministic cleanup of async
generators when they happen to exit early by @ref{a97,,break} or an
exception.  For example:

@example
from contextlib import aclosing

async with aclosing(my_generator()) as values:
    async for value in values:
        if value == 42:
            break
@end example

This pattern ensures that the generator's async exit code is executed in
the same context as its iterations (so that exceptions and context
variables work as expected, and the exit code isn't run after the
lifetime of some task it depends on).


Ajouté dans la version 3.10.

@end deffn

@geindex nullcontext() (dans le module contextlib)
@anchor{library/contextlib simplifying-support-for-single-optional-context-managers}@anchor{4340}@anchor{library/contextlib contextlib nullcontext}@anchor{7d8}
@deffn {Fonction} contextlib.nullcontext (enter_result=None)

Renvoie un gestionnaire de contexte dont la méthode @code{__enter__} renvoie `enter_result', mais ne fait rien d'autre. L'idée est de l'utiliser comme remplaçant pour un gestionnaire de contexte optionnel, par exemple :

@example
def myfunction(arg, ignore_exceptions=False):
    if ignore_exceptions:
        # Use suppress to ignore all exceptions.
        cm = contextlib.suppress(Exception)
    else:
        # Do not ignore any exceptions, cm has no effect.
        cm = contextlib.nullcontext()
    with cm:
        # Do something
@end example

Un exemple utilisant `enter_result' :

@example
def process_file(file_or_path):
    if isinstance(file_or_path, str):
        # If string, open file
        cm = open(file_or_path)
    else:
        # Caller is responsible for closing file
        cm = nullcontext(file_or_path)

    with cm as file:
        # Perform processing on the file
@end example

It can also be used as a stand-in for
@ref{5e6,,asynchronous context managers}:

@example
async def send_http(session=None):
    if not session:
        # If no http session, create it with aiohttp
        cm = aiohttp.ClientSession()
    else:
        # Caller is responsible for closing the session
        cm = nullcontext(session)

    async with cm as session:
        # Send http requests with session
@end example


Ajouté dans la version 3.7.



Modifié dans la version 3.10: @ref{5c1,,asynchronous context manager} support was added.

@end deffn

@geindex suppress() (dans le module contextlib)
@anchor{library/contextlib contextlib suppress}@anchor{f11}
@deffn {Fonction} contextlib.suppress (*exceptions)

Return a context manager that suppresses any of the specified exceptions
if they occur in the body of a @code{with} statement and then
resumes execution with the first statement following the end of the
@code{with} statement.

Comme pour tous les mécanismes qui suppriment complètement les exceptions, ce gestionnaire de contexte doit seulement être utilisé pour couvrir des cas très spécifiques d'erreurs où il est certain que continuer silencieusement l'exécution du programme est la bonne chose à faire.

Par exemple :

@example
from contextlib import suppress

with suppress(FileNotFoundError):
    os.remove('somefile.tmp')

with suppress(FileNotFoundError):
    os.remove('someotherfile.tmp')
@end example

Ce code est équivalent à :

@example
try:
    os.remove('somefile.tmp')
except FileNotFoundError:
    pass

try:
    os.remove('someotherfile.tmp')
except FileNotFoundError:
    pass
@end example

Ce gestionnaire de contexte est @ref{4341,,réentrant}.

If the code within the @code{with} block raises a
@ref{25c,,BaseExceptionGroup}, suppressed exceptions are removed from the
group.  Any exceptions of the group which are not suppressed are re-raised in
a new group which is created using the original group's @ref{1649,,derive()}
method.


Ajouté dans la version 3.4.



Modifié dans la version 3.12: @code{suppress} now supports suppressing exceptions raised as
part of a @ref{25c,,BaseExceptionGroup}.

@end deffn

@geindex redirect_stdout() (dans le module contextlib)
@anchor{library/contextlib contextlib redirect_stdout}@anchor{dd5}
@deffn {Fonction} contextlib.redirect_stdout (new_target)

Gestionnaire de contexte servant à rediriger temporairement @ref{ac4,,sys.stdout} vers un autre fichier ou objet fichier-compatible.

Cet outil ajoute une certaine flexibilité aux fonctions ou classes existantes dont la sortie est envoyée vers la sortie standard.

For example, the output of @ref{8c4,,help()} normally is sent to `sys.stdout'.
You can capture that output in a string by redirecting the output to an
@ref{f12,,io.StringIO} object. The replacement stream is returned from the
@code{__enter__} method and so is available as the target of the
@ref{5bc,,with} statement:

@example
with redirect_stdout(io.StringIO()) as f:
    help(pow)
s = f.getvalue()
@end example

Pour envoyer la sortie de @ref{8c4,,help()} vers un fichier sur le disque, redirigez-la sur un fichier normal :

@example
with open('help.txt', 'w') as f:
    with redirect_stdout(f):
        help(pow)
@end example

Pour envoyer la sortie de @ref{8c4,,help()} sur `sys.stderr' :

@example
with redirect_stdout(sys.stderr):
    help(pow)
@end example

Notez que l'effet de bord global sur @ref{ac4,,sys.stdout} signifie que ce gestionnaire de contexte n'est pas adapté à une utilisation dans le code d'une bibliothèque ni dans la plupart des applications à plusieurs fils d'exécution. Aussi, cela n'a pas d'effet sur la sortie des sous-processus. Cependant, cela reste une approche utile pour beaucoup de scripts utilitaires.

Ce gestionnaire de contexte est @ref{4341,,réentrant}.


Ajouté dans la version 3.4.

@end deffn

@geindex redirect_stderr() (dans le module contextlib)
@anchor{library/contextlib contextlib redirect_stderr}@anchor{dd4}
@deffn {Fonction} contextlib.redirect_stderr (new_target)

Similaire à @ref{dd5,,redirect_stdout()} mais redirige @ref{926,,sys.stderr} vers un autre fichier ou objet fichier-compatible.

Ce gestionnaire de contexte est @ref{4341,,réentrant}.


Ajouté dans la version 3.5.

@end deffn

@geindex chdir() (dans le module contextlib)
@anchor{library/contextlib contextlib chdir}@anchor{5f7}
@deffn {Fonction} contextlib.chdir (path)

Non parallel-safe context manager to change the current working directory.
As this changes a global state, the working directory, it is not suitable
for use in most threaded or async contexts. It is also not suitable for most
non-linear code execution, like generators, where the program execution is
temporarily relinquished -- unless explicitly desired, you should not yield
when this context manager is active.

This is a simple wrapper around @ref{5f8,,chdir()}, it changes the current
working directory upon entering and restores the old one on exit.

Ce gestionnaire de contexte est @ref{4341,,réentrant}.


Ajouté dans la version 3.11.

@end deffn

@geindex ContextDecorator (classe dans contextlib)
@anchor{library/contextlib contextlib ContextDecorator}@anchor{11de}
@deffn {Classe} contextlib.ContextDecorator

Une classe mère qui permet à un gestionnaire de contexte d'être aussi utilisé comme décorateur.

Les gestionnaires de contexte héritant de @code{ContextDecorator} doivent implémenter @code{__enter__} et @code{__exit__} comme habituellement. @code{__exit__} conserve sa gestion optionnelle des exceptions même lors de l'utilisation en décorateur.

@code{ContextDecorator} est utilisé par @ref{11df,,contextmanager()}, donc vous bénéficiez automatiquement de cette fonctionnalité.

Exemple de @code{ContextDecorator} :

@example
from contextlib import ContextDecorator

class mycontext(ContextDecorator):
    def __enter__(self):
        print('Starting')
        return self

    def __exit__(self, *exc):
        print('Finishing')
        return False
@end example

The class can then be used like this:

@example
>>> @@mycontext()
... def function():
...     print('The bit in the middle')
...
>>> function()
Starting
The bit in the middle
Finishing

>>> with mycontext():
...     print('The bit in the middle')
...
Starting
The bit in the middle
Finishing
@end example

Ce changement est simplement un sucre syntaxique pour les constructions de la forme suivante :

@example
def f():
    with cm():
        # Do stuff
@end example

@code{ContextDecorator} vous permet d'écrire à la place :

@example
@@cm()
def f():
    # Do stuff
@end example

Cela éclaircit le fait que @code{cm} s'applique à la fonction entière, et pas seulement à un morceau en particulier (et gagner un niveau d'indentation est toujours appréciable).

Les gestionnaires de contexte existants qui ont déjà une classe mère peuvent être étendus en utilisant @code{ContextDecorator} comme une `mixin' :

@example
from contextlib import ContextDecorator

class mycontext(ContextBaseClass, ContextDecorator):
    def __enter__(self):
        return self

    def __exit__(self, *exc):
        return False
@end example

@cartouche
@quotation Note 
Comme la fonction décorée doit être capable d'être appelée plusieurs fois, le gestionnaire de contexte sous-jacent doit permettre d'être utilisé dans de multiples instructions @ref{5bc,,with}. Si ce n'est pas le cas, alors la construction d'origine avec de multiples instructions @code{with} au sein de la fonction doit être utilisée.
@end quotation
@end cartouche


Ajouté dans la version 3.2.

@end deffn

@geindex AsyncContextDecorator (classe dans contextlib)
@anchor{library/contextlib contextlib AsyncContextDecorator}@anchor{7d9}
@deffn {Classe} contextlib.AsyncContextDecorator

Similar to @ref{11de,,ContextDecorator} but only for asynchronous functions.

Example of @code{AsyncContextDecorator}:

@example
from asyncio import run
from contextlib import AsyncContextDecorator

class mycontext(AsyncContextDecorator):
    async def __aenter__(self):
        print('Starting')
        return self

    async def __aexit__(self, *exc):
        print('Finishing')
        return False
@end example

The class can then be used like this:

@example
>>> @@mycontext()
... async def function():
...     print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing

>>> async def function():
...    async with mycontext():
...         print('The bit in the middle')
...
>>> run(function())
Starting
The bit in the middle
Finishing
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex ExitStack (classe dans contextlib)
@anchor{library/contextlib contextlib ExitStack}@anchor{b17}
@deffn {Classe} contextlib.ExitStack

Gestionnaire de contexte conçu pour simplifier le fait de combiner programmatiquement d'autres gestionnaires de contexte et fonctions de nettoyage, spécifiquement ceux qui sont optionnels ou pilotés par des données d'entrée.

Par exemple, un ensemble de fichiers peut facilement être géré dans une unique instruction `with' comme suit :

@example
with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # All opened files will automatically be closed at the end of
    # the with statement, even if attempts to open files later
    # in the list raise an exception
@end example

The @ref{5b2,,__enter__()} method returns the @ref{b17,,ExitStack} instance, and
performs no additional operations.

Chaque instance maintient une pile de fonctions de rappels (`callbacks') enregistrées qui sont appelées en ordre inverse quand l'instance est fermée (explicitement ou implicitement à la fin d'un bloc @ref{5bc,,with}). Notez que ces fonctions ne sont `pas' invoquées implicitement quand l'instance de la pile de contextes est collectée par le ramasse-miettes.

Ce modèle de pile est utilisé afin que les gestionnaires de contexte qui acquièrent leurs ressources dans leur méthode @code{__init__} (tels que les objets-fichiers) puissent être gérés correctement.

Comme les fonctions de rappel enregistrées sont invoquées dans l'ordre inverse d'enregistrement, cela revient au même que si de multiples blocs @ref{5bc,,with} imbriqués avaient été utilisés avec l'ensemble de fonctions enregistrées. Cela s'étend aussi à la gestion d'exceptions — si une fonction de rappel intérieure supprime ou remplace une exception, alors les fonctions extérieures reçoivent des arguments basés sur ce nouvel état.

C'est une `API' relativement bas-niveau qui s'occupe de dérouler correctement la pile des appels de sortie. Elle fournit une base adaptée pour des gestionnaires de contexte de plus haut niveau qui manipulent la pile de sortie de manière spécifique à l'application.


Ajouté dans la version 3.3.


@geindex enter_context() (méthode contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack enter_context}@anchor{5bd}
@deffn {Méthode} enter_context (cm)

Enters a new context manager and adds its @ref{12de,,__exit__()} method to
the callback stack. The return value is the result of the context
manager's own @ref{5b2,,__enter__()} method.

Ces gestionnaires de contexte peuvent supprimer des exceptions comme ils le feraient normalement s'ils étaient utilisés directement derrière une instruction @ref{5bc,,with}.


Modifié dans la version 3.11: Raises @ref{522,,TypeError} instead of @ref{343,,AttributeError} if `cm'
is not a context manager.

@end deffn

@geindex push() (méthode contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack push}@anchor{4342}
@deffn {Méthode} push (exit)

Adds a context manager's @ref{12de,,__exit__()} method to the callback stack.

As @code{__enter__} is `not' invoked, this method can be used to cover
part of an @ref{5b2,,__enter__()} implementation with a context manager's own
@ref{12de,,__exit__()} method.

If passed an object that is not a context manager, this method assumes
it is a callback with the same signature as a context manager's
@ref{12de,,__exit__()} method and adds it directly to the callback stack.

By returning true values, these callbacks can suppress exceptions the
same way context manager @ref{12de,,__exit__()} methods can.

L'objet passé en paramètre est renvoyé par la fonction, ce qui permet à la méthode d'être utilisée comme décorateur de fonction.
@end deffn

@geindex callback() (méthode contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack callback}@anchor{a71}
@deffn {Méthode} callback (callback, /, *args, **kwds)

Accepte une fonction arbitraire et ses arguments et les ajoute à la pile des fonctions de rappel.

À la différence des autres méthodes, les fonctions de rappel ajoutées de cette manière ne peuvent pas supprimer les exceptions (puisqu'elles ne reçoivent jamais les détails de l'exception).

La fonction passée en paramètre est renvoyée par la méthode, ce qui permet à la méthode d'être utilisée comme décorateur de fonction.
@end deffn

@geindex pop_all() (méthode contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack pop_all}@anchor{4343}
@deffn {Méthode} pop_all ()

Transfère la pile d'appels à une nouvelle instance de @ref{b17,,ExitStack} et la renvoie. Aucune fonction de rappel n'est invoquée par cette opération — à la place, elles sont dorénavant invoquées quand la nouvelle pile sera close (soit explicitement soit implicitement à la fin d'un bloc @ref{5bc,,with}).

Par exemple, un groupe de fichiers peut être ouvert comme une opération « tout ou rien » comme suit :

@example
with ExitStack() as stack:
    files = [stack.enter_context(open(fname)) for fname in filenames]
    # Hold onto the close method, but don't call it yet.
    close_files = stack.pop_all().close
    # If opening any file fails, all previously opened files will be
    # closed automatically. If all files are opened successfully,
    # they will remain open even after the with statement ends.
    # close_files() can then be invoked explicitly to close them all.
@end example
@end deffn

@geindex close() (méthode contextlib.ExitStack)
@anchor{library/contextlib contextlib ExitStack close}@anchor{4344}
@deffn {Méthode} close ()

Déroule immédiatement la pile d'appels, invoquant les fonctions de rappel dans l'ordre inverse d'enregistrement. Pour chaque gestionnaire de contexte et fonction de sortie enregistré, les arguments passés indiqueront qu'aucune exception n'est survenue.
@end deffn
@end deffn

@geindex AsyncExitStack (classe dans contextlib)
@anchor{library/contextlib contextlib AsyncExitStack}@anchor{b1a}
@deffn {Classe} contextlib.AsyncExitStack

Un @ref{5e6,,gestionnaire de contexte asynchrone}, similaire à @ref{b17,,ExitStack}, apte à combiner à la fois des gestionnaires de contexte synchrones et asynchrones, ainsi que la gestion de coroutines pour la logique de nettoyage.

The @ref{4344,,close()} method is not implemented; @ref{4345,,aclose()} must be used
instead.

@geindex enter_async_context() (méthode contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack enter_async_context}@anchor{5c0}
@deffn {Méthode} coroutine enter_async_context (cm)

Similar to @ref{5bd,,ExitStack.enter_context()} but expects an asynchronous context
manager.


Modifié dans la version 3.11: Raises @ref{522,,TypeError} instead of @ref{343,,AttributeError} if `cm'
is not an asynchronous context manager.

@end deffn

@geindex push_async_exit() (méthode contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack push_async_exit}@anchor{4346}
@deffn {Méthode} push_async_exit (exit)

Similar to @ref{4342,,ExitStack.push()} but expects either an asynchronous context manager
or a coroutine function.
@end deffn

@geindex push_async_callback() (méthode contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack push_async_callback}@anchor{a72}
@deffn {Méthode} push_async_callback (callback, /, *args, **kwds)

Similar to @ref{a71,,ExitStack.callback()} but expects a coroutine function.
@end deffn

@geindex aclose() (méthode contextlib.AsyncExitStack)
@anchor{library/contextlib contextlib AsyncExitStack aclose}@anchor{4345}
@deffn {Méthode} coroutine aclose ()

Similar to @ref{4344,,ExitStack.close()} but properly handles awaitables.
@end deffn

En continuité de l'exemple de @ref{b18,,asynccontextmanager()} :

@example
async with AsyncExitStack() as stack:
    connections = [await stack.enter_async_context(get_connection())
        for i in range(5)]
    # All opened connections will automatically be released at the end of
    # the async with statement, even if attempts to open a connection
    # later in the list raise an exception.
@end example


Ajouté dans la version 3.7.

@end deffn

@node Exemples et Recettes,Gestionnaires de contexte à usage unique réutilisables et réentrants,Utilitaires,contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with
@anchor{library/contextlib examples-and-recipes}@anchor{4347}
@subsubsection Exemples et Recettes


Cette section décrit quelques exemples et recettes pour décrire une utilisation réelle des outils fournis par @ref{23,,contextlib}.

@menu
* Gérer un nombre variable de gestionnaires de contexte:: 
* Attraper des exceptions depuis les méthodes __enter__:: 
* Nettoyer dans une méthode __enter__:: 
* Remplacer un try-finally avec une option variable:: 
* Utiliser un gestionnaire de contexte en tant que décorateur de fonction:: 

@end menu

@node Gérer un nombre variable de gestionnaires de contexte,Attraper des exceptions depuis les méthodes __enter__,,Exemples et Recettes
@anchor{library/contextlib supporting-a-variable-number-of-context-managers}@anchor{4348}
@subsubsection Gérer un nombre variable de gestionnaires de contexte


Le cas d'utilisation primaire de @ref{b17,,ExitStack} est celui décrit dans la documentation de la classe : gérer un nombre variable de gestionnaires de contexte et d'autres opérations de nettoyage en une unique instruction @ref{5bc,,with}. La variabilité peut venir du nombre de gestionnaires de contexte voulus découlant d'une entrée de l'utilisateur (comme ouvrir une collection spécifique de fichiers de l'utilisateur), ou de certains gestionnaires de contexte qui peuvent être optionnels :

@example
with ExitStack() as stack:
    for resource in resources:
        stack.enter_context(resource)
    if need_special_resource():
        special = acquire_special_resource()
        stack.callback(release_special_resource, special)
    # Perform operations that use the acquired resources
@end example

Comme montré, @ref{b17,,ExitStack} rend aussi assez facile d'utiliser les instructions @ref{5bc,,with} pour gérer des ressources arbitraires qui ne gèrent pas nativement le protocole des gestionnaires de contexte.

@node Attraper des exceptions depuis les méthodes __enter__,Nettoyer dans une méthode __enter__,Gérer un nombre variable de gestionnaires de contexte,Exemples et Recettes
@anchor{library/contextlib catching-exceptions-from-enter-methods}@anchor{4349}
@subsubsection Attraper des exceptions depuis les méthodes @code{__enter__}


Il est occasionnellement souhaitable d'attraper les exceptions depuis l'implémentation d'une méthode @code{__enter__}, `sans' attraper par inadvertance les exceptions du corps de l'instruction @ref{5bc,,with} ou de la méthode @code{__exit__} des gestionnaires de contexte. En utilisant @ref{b17,,ExitStack}, les étapes du protocole des gestionnaires de contexte peuvent être légèrement séparées pour permettre le code suivant :

@example
stack = ExitStack()
try:
    x = stack.enter_context(cm)
except Exception:
    # handle __enter__ exception
else:
    with stack:
        # Handle normal case
@end example

Avoir à faire cela est en fait surtout utile pour indiquer que l'`API' sous-jacente devrait fournir une interface directe de gestion des ressources à utiliser avec les instructions @ref{6d3,,try}/@ref{189,,except}/@ref{9b8,,finally}, mais que toutes les `API' ne sont pas bien conçues dans cet objectif. Quand un gestionnaire de contexte est la seule `API' de gestion des ressources fournie, alors @ref{b17,,ExitStack} peut rendre plus facile la gestion de plusieurs situations qui ne peuvent pas être traitées directement dans une instruction @ref{5bc,,with}.

@node Nettoyer dans une méthode __enter__,Remplacer un try-finally avec une option variable,Attraper des exceptions depuis les méthodes __enter__,Exemples et Recettes
@anchor{library/contextlib cleaning-up-in-an-enter-implementation}@anchor{434a}
@subsubsection Nettoyer dans une méthode @code{__enter__}


As noted in the documentation of @ref{4342,,ExitStack.push()}, this
method can be useful in cleaning up an already allocated resource if later
steps in the @ref{5b2,,__enter__()} implementation fail.

Voici un exemple de gestionnaire de contexte qui reçoit des fonctions d'acquisition de ressources et de libération, avec une méthode de validation optionnelle, et qui les adapte au protocole des gestionnaires de contexte :

@example
from contextlib import contextmanager, AbstractContextManager, ExitStack

class ResourceManager(AbstractContextManager):

    def __init__(self, acquire_resource, release_resource, check_resource_ok=None):
        self.acquire_resource = acquire_resource
        self.release_resource = release_resource
        if check_resource_ok is None:
            def check_resource_ok(resource):
                return True
        self.check_resource_ok = check_resource_ok

    @@contextmanager
    def _cleanup_on_error(self):
        with ExitStack() as stack:
            stack.push(self)
            yield
            # The validation check passed and didn't raise an exception
            # Accordingly, we want to keep the resource, and pass it
            # back to our caller
            stack.pop_all()

    def __enter__(self):
        resource = self.acquire_resource()
        with self._cleanup_on_error():
            if not self.check_resource_ok(resource):
                msg = "Failed validation for @{!r@}"
                raise RuntimeError(msg.format(resource))
        return resource

    def __exit__(self, *exc_details):
        # We don't need to duplicate any of our resource release logic
        self.release_resource()
@end example

@node Remplacer un try-finally avec une option variable,Utiliser un gestionnaire de contexte en tant que décorateur de fonction,Nettoyer dans une méthode __enter__,Exemples et Recettes
@anchor{library/contextlib replacing-any-use-of-try-finally-and-flag-variables}@anchor{434b}
@subsubsection Remplacer un @code{try-finally} avec une option variable


Un modèle que vous rencontrerez parfois est un bloc @code{try-finally} avec une option pour indiquer si le corps de la clause @code{finally} doit être exécuté ou non. Dans sa forme la plus simple (qui ne peut pas déjà être gérée avec juste une clause @code{except}), cela ressemble à :

@example
cleanup_needed = True
try:
    result = perform_operation()
    if result:
        cleanup_needed = False
finally:
    if cleanup_needed:
        cleanup_resources()
@end example

Comme avec n'importe quel code basé sur une instruction @code{try}, cela peut poser problème pour le développement et la revue, parce que beaucoup de codes d'installation et de nettoyage peuvent finir par être séparés par des sections de code arbitrairement longues.

@ref{b17,,ExitStack} rend possible de plutôt enregistrer une fonction de rappel pour être exécutée à la fin d'une instruction @code{with}, et décider ensuite de passer l'exécution de cet appel :

@example
from contextlib import ExitStack

with ExitStack() as stack:
    stack.callback(cleanup_resources)
    result = perform_operation()
    if result:
        stack.pop_all()
@end example

This allows the intended cleanup behaviour to be made explicit up front,
rather than requiring a separate flag variable.

Si une application particulière utilise beaucoup ce modèle, cela peut-être simplifié encore plus au moyen d'une petite classe d'aide :

@example
from contextlib import ExitStack

class Callback(ExitStack):
    def __init__(self, callback, /, *args, **kwds):
        super().__init__()
        self.callback(callback, *args, **kwds)

    def cancel(self):
        self.pop_all()

with Callback(cleanup_resources) as cb:
    result = perform_operation()
    if result:
        cb.cancel()
@end example

Si le nettoyage de la ressource n'est pas déjà soigneusement embarqué dans une fonction autonome, il est possible d'utiliser le décorateur @ref{a71,,ExitStack.callback()} pour déclarer la fonction de nettoyage de ressource en avance :

@example
from contextlib import ExitStack

with ExitStack() as stack:
    @@stack.callback
    def cleanup_resources():
        ...
    result = perform_operation()
    if result:
        stack.pop_all()
@end example

Dû au fonctionnement du protocole des décorateurs, une fonction déclarée ainsi ne peut prendre aucun paramètre. À la place, les ressources à libérer doivent être récupérées depuis l'extérieur comme des variables de fermeture (`closure').

@node Utiliser un gestionnaire de contexte en tant que décorateur de fonction,,Remplacer un try-finally avec une option variable,Exemples et Recettes
@anchor{library/contextlib using-a-context-manager-as-a-function-decorator}@anchor{434c}
@subsubsection Utiliser un gestionnaire de contexte en tant que décorateur de fonction


@ref{11de,,ContextDecorator} rend possible l'utilisation d'un gestionnaire de contexte à la fois ordinairement avec une instruction @code{with} ou comme un décorateur de fonction.

Par exemple, il est parfois utile d'emballer les fonctions ou blocs d'instructions avec un journaliseur qui pourrait suivre le temps d'exécution entre l'entrée et la sortie. Plutôt qu'écrire à la fois un décorateur et un gestionnaire de contexte pour la même tâche, hériter de @ref{11de,,ContextDecorator} fournit les deux fonctionnalités en une seule définition :

@example
from contextlib import ContextDecorator
import logging

logging.basicConfig(level=logging.INFO)

class track_entry_and_exit(ContextDecorator):
    def __init__(self, name):
        self.name = name

    def __enter__(self):
        logging.info('Entering: %s', self.name)

    def __exit__(self, exc_type, exc, exc_tb):
        logging.info('Exiting: %s', self.name)
@end example

Les instances de cette classe peuvent être utilisées comme gestionnaires de contexte :

@example
with track_entry_and_exit('widget loader'):
    print('Some time consuming activity goes here')
    load_widget()
@end example

Et comme décorateurs de fonctions :

@example
@@track_entry_and_exit('widget loader')
def activity():
    print('Some time consuming activity goes here')
    load_widget()
@end example

Note that there is one additional limitation when using context managers
as function decorators: there's no way to access the return value of
@ref{5b2,,__enter__()}. If that value is needed, then it is still necessary to use
an explicit @code{with} statement.


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 343

@item PEP 343@footnote{https://peps.python.org/pep-0343/} - The "with" statement

La spécification, les motivations et des exemples de l'instruction @ref{5bc,,with} en Python.
@end table


@node Gestionnaires de contexte à usage unique réutilisables et réentrants,,Exemples et Recettes,contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with
@anchor{library/contextlib single-use-reusable-and-reentrant-cms}@anchor{f13}@anchor{library/contextlib single-use-reusable-and-reentrant-context-managers}@anchor{434d}
@subsubsection Gestionnaires de contexte à usage unique, réutilisables et réentrants


La plupart des gestionnaires de contexte sont écrits d'une manière qui ne leur permet que d'être utilisés une fois avec une instruction @ref{5bc,,with}. Ces gestionnaires de contexte à usage unique doivent être recréés chaque fois qu'ils sont utilisés — tenter de les utiliser une seconde fois lève une exception ou ne fonctionne pas correctement.

Cette limitation commune signifie qu'il est généralement conseillé de créer les gestionnaires de contexte directement dans l'en-tête du bloc @ref{5bc,,with} où ils sont utilisés (comme montré dans tous les exemples d'utilisation au-dessus).

Les fichiers sont un exemple de gestionnaires de contexte étant effectivement à usage unique, puisque la première instruction @ref{5bc,,with} ferme le fichier, empêchant d'autres opérations d'entrée/sortie d'être exécutées sur ce fichier.

Les gestionnaires de contexte créés avec @ref{11df,,contextmanager()} sont aussi à usage unique, et se plaindront du fait que le générateur sous-jacent ne produise plus de valeur si vous essayez de les utiliser une seconde fois :

@example
>>> from contextlib import contextmanager
>>> @@contextmanager
... def singleuse():
...     print("Before")
...     yield
...     print("After")
...
>>> cm = singleuse()
>>> with cm:
...     pass
...
Before
After
>>> with cm:
...     pass
...
Traceback (most recent call last):
    ...
RuntimeError: generator didn't yield
@end example

@menu
* Gestionnaires de contexte réentrants:: 
* Gestionnaires de contexte réutilisables:: 

@end menu

@node Gestionnaires de contexte réentrants,Gestionnaires de contexte réutilisables,,Gestionnaires de contexte à usage unique réutilisables et réentrants
@anchor{library/contextlib reentrant-cms}@anchor{4341}@anchor{library/contextlib reentrant-context-managers}@anchor{434e}
@subsubsection Gestionnaires de contexte réentrants


Certains gestionnaires de contexte plus sophistiqués peuvent être « réentrants ». Ces gestionnaires de contexte ne peuvent pas seulement être utilisés avec plusieurs instructions @ref{5bc,,with}, mais aussi `à l'intérieur' d'une instruction @code{with} qui utilise déjà ce même gestionnaire de contexte.

@ref{2dc,,threading.RLock} is an example of a reentrant context manager, as are
@ref{f11,,suppress()}, @ref{dd5,,redirect_stdout()}, and @ref{5f7,,chdir()}. Here's a very
simple example of reentrant use:

@example
>>> from contextlib import redirect_stdout
>>> from io import StringIO
>>> stream = StringIO()
>>> write_to_stream = redirect_stdout(stream)
>>> with write_to_stream:
...     print("This is written to the stream rather than stdout")
...     with write_to_stream:
...         print("This is also written to the stream")
...
>>> print("This is written directly to stdout")
This is written directly to stdout
>>> print(stream.getvalue())
This is written to the stream rather than stdout
This is also written to the stream
@end example

Les exemples plus réels de réentrance sont susceptibles d'invoquer plusieurs fonctions s'entre-appelant, et donc être bien plus compliqués que cet exemple.

Notez aussi qu'être réentrant ne signifie `pas' être `thread safe'. @ref{dd5,,redirect_stdout()}, par exemple, n'est définitivement pas `thread safe', puisqu'il effectue des changements globaux sur l'état du système en branchant @ref{ac4,,sys.stdout} sur différents flux.

@node Gestionnaires de contexte réutilisables,,Gestionnaires de contexte réentrants,Gestionnaires de contexte à usage unique réutilisables et réentrants
@anchor{library/contextlib reusable-cms}@anchor{434f}@anchor{library/contextlib reusable-context-managers}@anchor{4350}
@subsubsection Gestionnaires de contexte réutilisables


D'autres gestionnaires de contexte que ceux à usage unique et les réentrants sont les gestionnaires de contexte « réutilisables » (ou, pour être plus explicite, « réutilisables mais pas réentrants », puisque les gestionnaires de contexte réentrants sont aussi réutilisables). Ces gestionnaires de contexte sont conçus afin d'être utilisés plusieurs fois, mais échoueront (ou ne fonctionnent pas correctement) si l'instance de gestionnaire de contexte référencée a déjà été utilisée dans une instruction `with' englobante.

@ref{1600,,threading.Lock} est un exemple de gestionnaire de contexte réutilisable mais pas réentrant (pour un verrou réentrant, il faut à la place utiliser @ref{2dc,,threading.RLock}).

Un autre exemple de gestionnaire de contexte réutilisable mais pas réentrant est @ref{b17,,ExitStack}, puisqu'il invoque `toutes' les fonctions de rappel actuellement enregistrées en quittant l'instruction `with', sans regarder où ces fonctions ont été ajoutées :

@example
>>> from contextlib import ExitStack
>>> stack = ExitStack()
>>> with stack:
...     stack.callback(print, "Callback: from first context")
...     print("Leaving first context")
...
Leaving first context
Callback: from first context
>>> with stack:
...     stack.callback(print, "Callback: from second context")
...     print("Leaving second context")
...
Leaving second context
Callback: from second context
>>> with stack:
...     stack.callback(print, "Callback: from outer context")
...     with stack:
...         stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Callback: from outer context
Leaving outer context
@end example

Comme le montre la sortie de l'exemple, réutiliser une simple pile entre plusieurs instructions `with' fonctionne correctement, mais essayer de les imbriquer fait que la pile est vidée à la fin du `with' le plus imbriqué, ce qui n'est probablement pas le comportement voulu.

Pour éviter ce problème, utilisez des instances différentes de @ref{b17,,ExitStack} plutôt qu'une seule instance :

@example
>>> from contextlib import ExitStack
>>> with ExitStack() as outer_stack:
...     outer_stack.callback(print, "Callback: from outer context")
...     with ExitStack() as inner_stack:
...         inner_stack.callback(print, "Callback: from inner context")
...         print("Leaving inner context")
...     print("Leaving outer context")
...
Leaving inner context
Callback: from inner context
Leaving outer context
Callback: from outer context
@end example

@node abc --- Abstract Base Classes,atexit --- Exit handlers,contextlib — Utilitaires pour les contextes s'appuyant sur l'instruction with,Environnement d'exécution Python
@anchor{library/abc doc}@anchor{4351}@anchor{library/abc abc-abstract-base-classes}@anchor{4352}@anchor{library/abc module-abc}@anchor{4}
@subsection @code{abc} --- Abstract Base Classes


@geindex module; abc

@c much of the content adapted from docstrings

`Code source:' Lib/abc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/abc.py}


__________________________________________________________________


Le module fournit l'infrastructure pour définir les @ref{1193,,classes mères abstraites} (`Abstract Base Class' ou `ABC' en anglais) en Python, tel qu'indiqué dans la 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/}; voir la PEP pour la raison de son ajout à Python. (Voir également la 
@geindex Python Enhancement Proposals; PEP 3141
PEP 3141@footnote{https://peps.python.org/pep-3141/} et le module @ref{9d,,numbers} pour ce qui concerne la hiérarchie de types pour les nombres basés sur les classes mères abstraites). Par la suite nous utiliserons l'abréviation ABC (`Abstract Base Class') pour désigner une classe mère abstraite.

The @ref{1d,,collections} module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the
@ref{1e,,collections.abc} submodule has some ABCs that can be used to test whether
a class or instance provides a particular interface, for example, if it is
@ref{5fb,,hashable} or if it is a @ref{1199,,mapping}.

Ce module fournit la métaclasse @ref{f03,,ABCMeta} pour définir les ABC ainsi que la classe d'aide @ref{f02,,ABC}, cette dernière permettant de définir des ABC en utilisant l'héritage :

@geindex ABC (classe dans abc)
@anchor{library/abc abc ABC}@anchor{f02}
@deffn {Classe} abc.ABC

A helper class that has @ref{f03,,ABCMeta} as its metaclass.  With this class,
an abstract base class can be created by simply deriving from @code{ABC}
avoiding sometimes confusing metaclass usage, for example:

@example
from abc import ABC

class MyABC(ABC):
    pass
@end example

Note that the type of @code{ABC} is still @ref{f03,,ABCMeta}, therefore
inheriting from @code{ABC} requires the usual precautions regarding
metaclass usage, as multiple inheritance may lead to metaclass conflicts.
One may also define an abstract base class by passing the metaclass
keyword and using @code{ABCMeta} directly, for example:

@example
from abc import ABCMeta

class MyABC(metaclass=ABCMeta):
    pass
@end example


Ajouté dans la version 3.4.

@end deffn

@geindex ABCMeta (classe dans abc)
@anchor{library/abc abc ABCMeta}@anchor{f03}
@deffn {Classe} abc.ABCMeta

Métaclasse pour définir des classes mères abstraites (ABC).

Utilisez cette métaclasse pour créer une ABC. Il est possible d'hériter d'une ABC directement, cette classe mère abstraite fonctionne alors comme une classe `mixin'. Vous pouvez également enregistrer une classe concrète sans lien (même une classe native) et des ABC comme "sous-classes virtuelles" -- celles-ci et leur descendantes seront considérées comme des sous-classes de la classe mère abstraite par la fonction native @ref{7ab,,issubclass()}, mais les ABC enregistrées n'apparaitront pas dans leur ordre de résolution des méthodes (`MRO' pour `Method Resolution Order' en anglais). Les implémentations de méthodes définies par l'ABC ne seront pas appelable (pas même via @ref{4c5,,super()}). @footnote{
Les développeurs C++ noteront que le concept Python de classe mère virtuelle ( `virtual base class' ) n'est pas le même que celui de C++.
}

Classes created with a metaclass of @code{ABCMeta} have the following method:

@geindex register() (méthode abc.ABCMeta)
@anchor{library/abc abc ABCMeta register}@anchor{1072}
@deffn {Méthode} register (subclass)

Enregistrer `subclass' en tant que sous-classe virtuelle de cette ABC. Par exemple :

@example
from abc import ABC

class MyABC(ABC):
    pass

MyABC.register(tuple)

assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)
@end example


Modifié dans la version 3.3: Renvoie la sous-classe enregistrée pour permettre l'utilisation en tant que décorateur de classe.



Modifié dans la version 3.4: To detect calls to @code{register()}, you can use the
@ref{f01,,get_cache_token()} function.

@end deffn

Vous pouvez également redéfinir cette méthode dans une ABC :

@geindex __subclasshook__() (méthode abc.ABCMeta)
@anchor{library/abc abc ABCMeta __subclasshook__}@anchor{24ad}
@deffn {Méthode} __subclasshook__ (subclass)

(Doit être définie en tant que méthode de classe.)

Check whether `subclass' is considered a subclass of this ABC.  This means
that you can customize the behavior of @ref{7ab,,issubclass()} further without the
need to call @ref{1072,,register()} on every class you want to consider a
subclass of the ABC.  (This class method is called from the
@ref{1f00,,__subclasscheck__()} method of the ABC.)

This method should return @code{True}, @code{False} or @ref{7bc,,NotImplemented}.  If
it returns @code{True}, the `subclass' is considered a subclass of this ABC.
If it returns @code{False}, the `subclass' is not considered a subclass of
this ABC, even if it would normally be one.  If it returns
@code{NotImplemented}, the subclass check is continued with the usual
mechanism.

@c XXX explain the "usual mechanism"
@end deffn

Pour une illustration de ces concepts, voir cet exemple de définition de ABC :

@example
class Foo:
    def __getitem__(self, index):
        ...
    def __len__(self):
        ...
    def get_iterator(self):
        return iter(self)

class MyIterable(ABC):

    @@abstractmethod
    def __iter__(self):
        while False:
            yield None

    def get_iterator(self):
        return self.__iter__()

    @@classmethod
    def __subclasshook__(cls, C):
        if cls is MyIterable:
            if any("__iter__" in B.__dict__ for B in C.__mro__):
                return True
        return NotImplemented

MyIterable.register(Foo)
@end example

The ABC @code{MyIterable} defines the standard iterable method,
@ref{1c51,,__iter__()}, as an abstract method.  The implementation given
here can still be called from subclasses.  The @code{get_iterator()} method
is also part of the @code{MyIterable} abstract base class, but it does not have
to be overridden in non-abstract derived classes.

The @ref{24ad,,__subclasshook__()} class method defined here says that any class
that has an @ref{1c51,,__iter__()} method in its
@ref{546,,__dict__} (or in that of one of its base classes, accessed
via the @ref{1eae,,__mro__} list) is considered a @code{MyIterable} too.

Finally, the last line makes @code{Foo} a virtual subclass of @code{MyIterable},
even though it does not define an @ref{1c51,,__iter__()} method (it uses
the old-style iterable protocol, defined in terms of @ref{1ee5,,__len__()} and
@ref{280,,__getitem__()}).  Note that this will not make @code{get_iterator}
available as a method of @code{Foo}, so it is provided separately.
@end deffn

The @code{abc} module also provides the following decorator:

@geindex abstractmethod() (dans le module abc)
@anchor{library/abc abc abstractmethod}@anchor{106f}
@deffn {Fonction} @@abc.abstractmethod

Un décorateur marquant les méthodes comme abstraites.

Using this decorator requires that the class's metaclass is @ref{f03,,ABCMeta}
or is derived from it.  A class that has a metaclass derived from
@code{ABCMeta} cannot be instantiated unless all of its abstract methods
and properties are overridden.  The abstract methods can be called using any
of the normal 'super' call mechanisms.  @code{abstractmethod()} may be used
to declare abstract methods for properties and descriptors.

Dynamically adding abstract methods to a class, or attempting to modify the
abstraction status of a method or class once it is created, are only
supported using the @ref{4353,,update_abstractmethods()} function.  The
@code{abstractmethod()} only affects subclasses derived using regular
inheritance; "virtual subclasses" registered with the ABC's
@ref{1072,,register()} method are not affected.

When @code{abstractmethod()} is applied in combination with other method
descriptors, it should be applied as the innermost decorator, as shown in
the following usage examples:

@example
class C(ABC):
    @@abstractmethod
    def my_abstract_method(self, arg1):
        ...
    @@classmethod
    @@abstractmethod
    def my_abstract_classmethod(cls, arg2):
        ...
    @@staticmethod
    @@abstractmethod
    def my_abstract_staticmethod(arg3):
        ...

    @@property
    @@abstractmethod
    def my_abstract_property(self):
        ...
    @@my_abstract_property.setter
    @@abstractmethod
    def my_abstract_property(self, val):
        ...

    @@abstractmethod
    def _get_x(self):
        ...
    @@abstractmethod
    def _set_x(self, val):
        ...
    x = property(_get_x, _set_x)
@end example

In order to correctly interoperate with the abstract base class machinery,
the descriptor must identify itself as abstract using
@code{__isabstractmethod__}. In general, this attribute should be @code{True}
if any of the methods used to compose the descriptor are abstract. For
example, Python's built-in @ref{192,,property} does the equivalent of:

@example
class Descriptor:
    ...
    @@property
    def __isabstractmethod__(self):
        return any(getattr(f, '__isabstractmethod__', False) for
                   f in (self._fget, self._fset, self._fdel))
@end example

@cartouche
@quotation Note 
Contrairement aux méthodes abstraites Java, ces méthodes abstraites peuvent être implémentées. Cette implémentation peut être appelée via le mécanisme @ref{4c5,,super()} depuis la classe qui la redéfinit. C'est typiquement utile pour y appeler `super' et ainsi coopérer correctement dans un environnement utilisant de l'héritage multiple.
@end quotation
@end cartouche
@end deffn

The @code{abc} module also supports the following legacy decorators:

@geindex abstractclassmethod() (dans le module abc)
@anchor{library/abc abc abstractclassmethod}@anchor{1070}
@deffn {Fonction} @@abc.abstractclassmethod


Ajouté dans la version 3.2.



Obsolète depuis la version 3.3: Il est désormais possible d'utiliser @ref{165,,classmethod} avec @ref{106f,,abstractmethod()}, cela rend ce décorateur redondant.


Sous-classe du décorateur natif @ref{165,,classmethod()} qui indique une méthode de classe ( @code{classmethod} ) abstraite. En dehors de cela, est similaire à @ref{106f,,abstractmethod()}.

Ce cas spécial est obsolète car le décorateur @ref{165,,classmethod()} est désormais correctement identifié comme abstrait quand il est appliqué à une méthode abstraite :

@example
class C(ABC):
    @@classmethod
    @@abstractmethod
    def my_abstract_classmethod(cls, arg):
        ...
@end example
@end deffn

@geindex abstractstaticmethod() (dans le module abc)
@anchor{library/abc abc abstractstaticmethod}@anchor{1071}
@deffn {Fonction} @@abc.abstractstaticmethod


Ajouté dans la version 3.2.



Obsolète depuis la version 3.3: Il est désormais possible d'utiliser @ref{40c,,staticmethod} avec @ref{106f,,abstractmethod()}, cela rend ce décorateur redondant.


Sous-classe du décorateur natif @ref{165,,classmethod()} qui indique une méthode statique ( @code{staticmethod} ) abstraite. En dehors de cela, est similaire à @ref{106f,,abstractmethod()}.

Ce cas spécial est obsolète car le décorateur @ref{40c,,staticmethod()} est désormais correctement identifié comme abstrait quand appliqué à une méthode abstraite :

@example
class C(ABC):
    @@staticmethod
    @@abstractmethod
    def my_abstract_staticmethod(arg):
        ...
@end example
@end deffn

@geindex abstractproperty() (dans le module abc)
@anchor{library/abc abc abstractproperty}@anchor{106e}
@deffn {Fonction} @@abc.abstractproperty


Obsolète depuis la version 3.3: Il est désormais possible d'utiliser @ref{192,,property}, @ref{15e3,,property.getter()}, @ref{15e4,,property.setter()} et @ref{15e5,,property.deleter()} avec @ref{106f,,abstractmethod()}, ce qui rend ce décorateur redondant.


Sous-classe de @ref{192,,property()}, qui indique une propriété abstraite.

Ce cas spécial est obsolète car le décorateur @ref{192,,property()} est désormais correctement identifié comme abstrait quand appliqué à une méthode abstraite :

@example
class C(ABC):
    @@property
    @@abstractmethod
    def my_abstract_property(self):
        ...
@end example

L'exemple ci-dessus définit une propriété en lecture seule. Vous pouvez également définir une propriété en lecture-écriture abstraite en indiquant une ou plusieurs des méthodes sous-jacentes comme abstraite :

@example
class C(ABC):
    @@property
    def x(self):
        ...

    @@x.setter
    @@abstractmethod
    def x(self, val):
        ...
@end example

Si seuls certains composants sont abstraits, seuls ces composants abstraits nécessitent d'être mis à jour pour créer une propriété concrète dans une sous-classe :

@example
class D(C):
    @@C.x.setter
    def x(self, val):
        ...
@end example
@end deffn

The @code{abc} module also provides the following functions:

@geindex get_cache_token() (dans le module abc)
@anchor{library/abc abc get_cache_token}@anchor{f01}
@deffn {Fonction} abc.get_cache_token ()

Renvoie le jeton de cache ( `cache token') de l'ABC.

Le jeton est un objet opaque (qui implémente le test d'égalité) qui identifie la version actuelle du cache de l'ABC pour les sous-classes virtuelles. Le jeton change avec chaque appel à @ref{1072,,ABCMeta.register()} sur n'importe quelle ABC.


Ajouté dans la version 3.4.

@end deffn

@geindex update_abstractmethods() (dans le module abc)
@anchor{library/abc abc update_abstractmethods}@anchor{4353}
@deffn {Fonction} abc.update_abstractmethods (cls)

Recalcule l'état d'abstraction de la classe. Il est nécessaire d'appeler cette fonction si les méthodes abstraites d'une classe sont ajoutées ou modifiées après la création de la classe. C'est notamment le cas dans les décorateurs de classe.

Pour permettre une utilisation en tant que décorateur, cette fonction renvoie `cls'.

Ne fait rien si `cls' n'est pas une instance de @ref{f03,,ABCMeta}.

@cartouche
@quotation Note 
Cette fonction suppose que les classes mères de `cls' ont vu leur état recalculé, et ne fait rien pour recalculer celui des classes filles.
@end quotation
@end cartouche


Ajouté dans la version 3.10.

@end deffn

@subsubheading Notes


@node atexit --- Exit handlers,traceback --- Print or retrieve a stack traceback,abc --- Abstract Base Classes,Environnement d'exécution Python
@anchor{library/atexit doc}@anchor{4354}@anchor{library/atexit atexit-exit-handlers}@anchor{4355}@anchor{library/atexit module-atexit}@anchor{c}
@subsection @code{atexit} --- Exit handlers


@geindex module; atexit


__________________________________________________________________


Le module @ref{c,,atexit} définit des fonctions pour inscrire et désinscrire des fonctions de nettoyage. Les fonctions ainsi inscrites sont automatiquement exécutées au moment de l'arrêt normal de l'interpréteur. @ref{c,,atexit} exécute ces fonctions dans l'ordre inverse dans lequel elles ont été inscrites ; si vous inscrivez @code{A}, @code{B}, et @code{C}, au moment de l'arrêt de l'interpréteur elles seront exécutées dans l'ordre @code{C}, @code{B}, @code{A}.

`Note:' Les fonctions inscrites via ce module ne sont pas appelées quand le programme est tué par un signal non géré par Python, quand une erreur fatale interne de Python est détectée, ou quand  @ref{221f,,os._exit()} est appelé.

`Note:' The effect of registering or unregistering functions from within
a cleanup function is undefined.


Modifié dans la version 3.7: Quand elles sont utilisées avec des sous-interpréteurs de l'API C, les fonctions inscrites sont locales à l'interpréteur dans lequel elles ont été inscrites.


@geindex register() (dans le module atexit)
@anchor{library/atexit atexit register}@anchor{869}
@deffn {Fonction} atexit.register (func, *args, **kwargs)

Inscrit `func' comme une fonction à exécuter au moment de l'arrêt de l'interpréteur. Tout argument optionnel qui doit être passé à `func' doit être passé comme argument à @ref{869,,register()}. Il est possible d'inscrire les mêmes fonctions et arguments plus d'une fois.

Lors d'un arrêt normal du programme (par exemple, si @ref{1327,,sys.exit()} est appelée ou l’exécution du module principal se termine), toutes les fonctions inscrites sont appelées, dans l'ordre de la dernière arrivée, première servie. La supposition est que les modules les plus bas niveau vont normalement être importés avant les modules haut niveau et ainsi être nettoyés en dernier.

Si une exception est levée durant l'exécution du gestionnaire de fin de programme, une trace d'appels est affichée (à moins que @ref{d2e,,SystemExit} ait été levée) et les informations de l'exception sont sauvegardées. Une fois que tous les gestionnaires de fin de programme ont eu une chance de s'exécuter, la dernière exception à avoir été levée l'est de nouveau.

Cette fonction renvoie `func', ce qui rend possible de l'utiliser en tant que décorateur.

@cartouche
@quotation Avertissement 
Starting new threads or calling @ref{195,,os.fork()} from a registered
function can lead to race condition between the main Python
runtime thread freeing thread states while internal @ref{ec,,threading}
routines or the new process try to use that state. This can lead to
crashes rather than clean shutdown.
@end quotation
@end cartouche


Modifié dans la version 3.12: Attempts to start a new thread or @ref{195,,os.fork()} a new process
in a registered function now leads to @ref{193,,RuntimeError}.

@end deffn

@geindex unregister() (dans le module atexit)
@anchor{library/atexit atexit unregister}@anchor{4356}
@deffn {Fonction} atexit.unregister (func)

Retire `func' de la liste des fonctions à exécuter au moment de l'arrêt de l'interpréteur. @ref{4356,,unregister()} ne fait rien et reste silencieux si `func' n'a pas été préalablement inscrite. Si `func' a été inscrite plus d'une fois, toutes les occurrences de cette fonction sont retirées de la pile d'appels de @ref{c,,atexit}. La comparaison d'égalité (@code{==}) est utilisée dans l'implémentation interne de la désinscription. Les références des fonctions n'ont donc pas besoin d'avoir la même identité.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{b9,,readline}

Un exemple utile de l'usage de @ref{c,,atexit} pour lire et écrire des fichiers d'historique @ref{b9,,readline}.
@end table


@menu
* Exemple avec atexit:: 

@end menu

@node Exemple avec atexit,,,atexit --- Exit handlers
@anchor{library/atexit atexit-example}@anchor{4357}@anchor{library/atexit id1}@anchor{4358}
@subsubsection Exemple avec @code{atexit}


Le simple exemple suivant démontre comment un module peut initialiser un compteur depuis un fichier quand il est importé, et sauver le valeur mise à jour du compteur automatiquement quand le programme se termine, sans avoir besoin que l'application fasse un appel explicite dans ce module au moment de l'arrêt de l'interpréteur.

@example
try:
    with open('counterfile') as infile:
        _count = int(infile.read())
except FileNotFoundError:
    _count = 0

def incrcounter(n):
    global _count
    _count = _count + n

def savecounter():
    with open('counterfile', 'w') as outfile:
        outfile.write('%d' % _count)

import atexit

atexit.register(savecounter)
@end example

Les arguments positionnels et nommés peuvent aussi être passés à @ref{869,,register()} afin d'être repassés à la fonction inscrite lors de son appel :

@example
def goodbye(name, adjective):
    print('Goodbye %s, it was %s to meet you.' % (name, adjective))

import atexit

atexit.register(goodbye, 'Donny', 'nice')
# or:
atexit.register(goodbye, adjective='nice', name='Donny')
@end example

Utilisation en tant que @ref{71b,,décorateur} :

@example
import atexit

@@atexit.register
def goodbye():
    print('You are now leaving the Python sector.')
@end example

Ceci fonctionne uniquement avec des fonctions qui peuvent être appelées sans argument.

@node traceback --- Print or retrieve a stack traceback,__future__ --- Future statement definitions,atexit --- Exit handlers,Environnement d'exécution Python
@anchor{library/traceback doc}@anchor{4359}@anchor{library/traceback module-traceback}@anchor{fd}@anchor{library/traceback traceback-print-or-retrieve-a-stack-traceback}@anchor{435a}
@subsection @code{traceback} --- Print or retrieve a stack traceback


@geindex module; traceback

`Source code:' Lib/traceback.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/traceback.py}


__________________________________________________________________


This module provides a standard interface to extract, format and print
stack traces of Python programs. It is more flexible than the
interpreter's default traceback display, and therefore makes it
possible to configure certain aspects of the output. Finally,
it contains a utility for capturing enough information about an
exception to print it later, without the need to save a reference
to the actual exception. Since exceptions can be the roots of large
objects graph, this utility can significantly improve
memory management.

@geindex object;traceback

The module uses @ref{ae2,,traceback objects} --- these are
objects of type @ref{ae0,,types.TracebackType},
which are assigned to the @ref{12a4,,__traceback__} field of
@ref{5a5,,BaseException} instances.


@subsubheading Voir aussi



@table @asis

@item Module @ref{57,,faulthandler}

Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.

@item Module @ref{a4,,pdb}

Interactive source code debugger for Python programs.
@end table


The module's API can be divided into two parts:


@itemize *

@item 
Module-level functions offering basic functionality, which are useful for interactive
inspection of exceptions and tracebacks.

@item 
@ref{259,,TracebackException} class and its helper classes
@ref{e6e,,StackSummary} and @ref{e6f,,FrameSummary}. These offer both more
flexibility in the output generated and the ability to store the information
necessary for later formatting without holding references to actual exception
and traceback objects.
@end itemize

@menu
* Fonctions de niveau module: Fonctions de niveau module<2>. 
* TracebackException Objects:: 
* StackSummary Objects:: 
* FrameSummary Objects:: 
* Examples of Using the Module-Level Functions:: 
* Examples of Using TracebackException:: 

@end menu

@node Fonctions de niveau module<2>,TracebackException Objects,,traceback --- Print or retrieve a stack traceback
@anchor{library/traceback module-level-functions}@anchor{435b}
@subsubsection Fonctions de niveau module


@geindex print_tb() (dans le module traceback)
@anchor{library/traceback traceback print_tb}@anchor{e70}
@deffn {Fonction} traceback.print_tb (tb, limit=None, file=None)

Print up to `limit' stack trace entries from
@ref{ae2,,traceback object} `tb' (starting
from the caller's frame) if `limit' is positive.  Otherwise, print the last
@code{abs(limit)} entries.  If `limit' is omitted or @code{None}, all entries are
printed.  If `file' is omitted or @code{None}, the output goes to
@ref{926,,sys.stderr}; otherwise it should be an open
@ref{11a0,,file} or @ref{250d,,file-like object} to
receive the output.

@cartouche
@quotation Note 
The meaning of the `limit' parameter is different than the meaning
of @ref{1562,,sys.tracebacklimit}. A negative `limit' value corresponds to
a positive value of @code{sys.tracebacklimit}, whereas the behaviour of
a positive `limit' value cannot be achieved with
@code{sys.tracebacklimit}.
@end quotation
@end cartouche


Modifié dans la version 3.5: Added negative `limit' support.

@end deffn

@geindex print_exception() (dans le module traceback)
@anchor{library/traceback traceback print_exception}@anchor{839}
@deffn {Fonction} traceback.print_exception (exc, /[, value, tb], limit=None, file=None, chain=True)

Print exception information and stack trace entries from
@ref{ae2,,traceback object}
`tb' to `file'. This differs from @ref{e70,,print_tb()} in the following
ways:


@itemize *

@item 
if `tb' is not @code{None}, it prints a header @code{Traceback (most recent
call last):}

@item 
it prints the exception type and `value' after the stack trace
@end itemize

@geindex ^ (caret);marker


@itemize *

@item 
if `type(value)' is @ref{18b,,SyntaxError} and `value' has the appropriate
format, it prints the line where the syntax error occurred with a caret
indicating the approximate position of the error.
@end itemize

Since Python 3.10, instead of passing `value' and `tb', an exception object
can be passed as the first argument. If `value' and `tb' are provided, the
first argument is ignored in order to provide backwards compatibility.

The optional `limit' argument has the same meaning as for @ref{e70,,print_tb()}.
If `chain' is true (the default), then chained exceptions (the
@ref{12a6,,__cause__} or @ref{12a5,,__context__}
attributes of the exception) will be
printed as well, like the interpreter itself does when printing an unhandled
exception.


Modifié dans la version 3.5: The `etype' argument is ignored and inferred from the type of `value'.



Modifié dans la version 3.10: The `etype' parameter has been renamed to `exc' and is now
positional-only.

@end deffn

@geindex print_exc() (dans le module traceback)
@anchor{library/traceback traceback print_exc}@anchor{180d}
@deffn {Fonction} traceback.print_exc (limit=None, file=None, chain=True)

This is a shorthand for @code{print_exception(sys.exception(), limit, file,
chain)}.
@end deffn

@geindex print_last() (dans le module traceback)
@anchor{library/traceback traceback print_last}@anchor{435c}
@deffn {Fonction} traceback.print_last (limit=None, file=None, chain=True)

This is a shorthand for @code{print_exception(sys.last_exc, limit, file,
chain)}.  In general it will work only after an exception has reached
an interactive prompt (see @ref{4a7,,sys.last_exc}).
@end deffn

@geindex print_stack() (dans le module traceback)
@anchor{library/traceback traceback print_stack}@anchor{e71}
@deffn {Fonction} traceback.print_stack (f=None, limit=None, file=None)

Print up to `limit' stack trace entries (starting from the invocation
point) if `limit' is positive.  Otherwise, print the last @code{abs(limit)}
entries.  If `limit' is omitted or @code{None}, all entries are printed.
The optional `f' argument can be used to specify an alternate
@ref{6ca,,stack frame}
to start.  The optional `file' argument has the same meaning as for
@ref{e70,,print_tb()}.


Modifié dans la version 3.5: Added negative `limit' support.

@end deffn

@geindex extract_tb() (dans le module traceback)
@anchor{library/traceback traceback extract_tb}@anchor{435d}
@deffn {Fonction} traceback.extract_tb (tb, limit=None)

Return a @ref{e6e,,StackSummary} object representing a list of "pre-processed"
stack trace entries extracted from the
@ref{ae2,,traceback object} `tb'.  It is useful
for alternate formatting of stack traces.  The optional `limit' argument has
the same meaning as for @ref{e70,,print_tb()}.  A "pre-processed" stack trace
entry is a @ref{e6f,,FrameSummary} object containing attributes
@ref{435e,,filename}, @ref{435f,,lineno},
@ref{4360,,name}, and @ref{4361,,line} representing the
information that is usually printed for a stack trace.
@end deffn

@geindex extract_stack() (dans le module traceback)
@anchor{library/traceback traceback extract_stack}@anchor{4362}
@deffn {Fonction} traceback.extract_stack (f=None, limit=None)

Extract the raw traceback from the current
@ref{6ca,,stack frame}.  The return value has
the same format as for @ref{435d,,extract_tb()}.  The optional `f' and `limit'
arguments have the same meaning as for @ref{e71,,print_stack()}.
@end deffn

@geindex print_list() (dans le module traceback)
@anchor{library/traceback traceback print_list}@anchor{4363}
@deffn {Fonction} traceback.print_list (extracted_list, file=None)

Print the list of tuples as returned by @ref{435d,,extract_tb()} or
@ref{4362,,extract_stack()} as a formatted stack trace to the given file.
If `file' is @code{None}, the output is written to @ref{926,,sys.stderr}.
@end deffn

@geindex format_list() (dans le module traceback)
@anchor{library/traceback traceback format_list}@anchor{4364}
@deffn {Fonction} traceback.format_list (extracted_list)

Given a list of tuples or @ref{e6f,,FrameSummary} objects as returned by
@ref{435d,,extract_tb()} or @ref{4362,,extract_stack()}, return a list of strings ready
for printing.  Each string in the resulting list corresponds to the item with
the same index in the argument list.  Each string ends in a newline; the
strings may contain internal newlines as well, for those items whose source
text line is not @code{None}.
@end deffn

@geindex format_exception_only() (dans le module traceback)
@anchor{library/traceback traceback format_exception_only}@anchor{838}
@deffn {Fonction} traceback.format_exception_only (exc, /[, value], *, show_group=False)

Format the exception part of a traceback using an exception value such as
given by @ref{4a9,,sys.last_value}.  The return value is a list of strings, each
ending in a newline.  The list contains the exception's message, which is
normally a single string; however, for @ref{18b,,SyntaxError} exceptions, it
contains several lines that (when printed) display detailed information
about where the syntax error occurred. Following the message, the list
contains the exception's @ref{220c,,notes}.

Since Python 3.10, instead of passing `value', an exception object
can be passed as the first argument.  If `value' is provided, the first
argument is ignored in order to provide backwards compatibility.

When `show_group' is @code{True}, and the exception is an instance of
@ref{25c,,BaseExceptionGroup}, the nested exceptions are included as
well, recursively, with indentation relative to their nesting depth.


Modifié dans la version 3.10: The `etype' parameter has been renamed to `exc' and is now
positional-only.



Modifié dans la version 3.11: The returned list now includes any
@ref{220c,,notes} attached to the exception.



Modifié dans la version 3.13: `show_group' parameter was added.

@end deffn

@geindex format_exception() (dans le module traceback)
@anchor{library/traceback traceback format_exception}@anchor{837}
@deffn {Fonction} traceback.format_exception (exc, /[, value, tb], limit=None, chain=True)

Format a stack trace and the exception information.  The arguments  have the
same meaning as the corresponding arguments to @ref{839,,print_exception()}.  The
return value is a list of strings, each ending in a newline and some
containing internal newlines.  When these lines are concatenated and printed,
exactly the same text is printed as does @ref{839,,print_exception()}.


Modifié dans la version 3.5: The `etype' argument is ignored and inferred from the type of `value'.



Modifié dans la version 3.10: This function's behavior and signature were modified to match
@ref{839,,print_exception()}.

@end deffn

@geindex format_exc() (dans le module traceback)
@anchor{library/traceback traceback format_exc}@anchor{4365}
@deffn {Fonction} traceback.format_exc (limit=None, chain=True)

This is like @code{print_exc(limit)} but returns a string instead of printing to
a file.
@end deffn

@geindex format_tb() (dans le module traceback)
@anchor{library/traceback traceback format_tb}@anchor{4248}
@deffn {Fonction} traceback.format_tb (tb, limit=None)

A shorthand for @code{format_list(extract_tb(tb, limit))}.
@end deffn

@geindex format_stack() (dans le module traceback)
@anchor{library/traceback traceback format_stack}@anchor{4366}
@deffn {Fonction} traceback.format_stack (f=None, limit=None)

A shorthand for @code{format_list(extract_stack(f, limit))}.
@end deffn

@geindex clear_frames() (dans le module traceback)
@anchor{library/traceback traceback clear_frames}@anchor{fbf}
@deffn {Fonction} traceback.clear_frames (tb)

Clears the local variables of all the stack frames in a
@ref{ae2,,traceback} `tb'
by calling the @ref{27d,,clear()} method of each
@ref{6ca,,frame object}.


Ajouté dans la version 3.4.

@end deffn

@geindex walk_stack() (dans le module traceback)
@anchor{library/traceback traceback walk_stack}@anchor{e6c}
@deffn {Fonction} traceback.walk_stack (f)

Walk a stack following @ref{776,,f.f_back} from the given frame,
yielding the frame
and line number for each frame. If `f' is @code{None}, the current stack is
used. This helper is used with @ref{4367,,StackSummary.extract()}.


Ajouté dans la version 3.5.

@end deffn

@geindex walk_tb() (dans le module traceback)
@anchor{library/traceback traceback walk_tb}@anchor{e6d}
@deffn {Fonction} traceback.walk_tb (tb)

Walk a traceback following @ref{ae1,,tb_next} yielding the frame and
line number
for each frame. This helper is used with @ref{4367,,StackSummary.extract()}.


Ajouté dans la version 3.5.

@end deffn

@node TracebackException Objects,StackSummary Objects,Fonctions de niveau module<2>,traceback --- Print or retrieve a stack traceback
@anchor{library/traceback tracebackexception-objects}@anchor{4368}
@subsubsection @code{TracebackException} Objects



Ajouté dans la version 3.5.


@code{TracebackException} objects are created from actual exceptions to
capture data for later printing.  They offer a more lightweight method of
storing this information by avoiding holding references to
@ref{ae2,,traceback} and @ref{6ca,,frame} objects.
In addition, they expose more options to configure the output compared to
the module-level functions described above.

@geindex TracebackException (classe dans traceback)
@anchor{library/traceback traceback TracebackException}@anchor{259}
@deffn {Classe} traceback.TracebackException (exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

Capture an exception for later rendering. The meaning of `limit',
`lookup_lines' and `capture_locals' are as for the @ref{e6e,,StackSummary}
class.

If `compact' is true, only data that is required by
@code{TracebackException}'s @ref{60a,,format()} method
is saved in the class attributes. In particular, the
@ref{4369,,__context__} field is calculated only if @ref{436a,,__cause__} is
@code{None} and @ref{436b,,__suppress_context__} is false.

Note that when locals are captured, they are also shown in the traceback.

`max_group_width' and `max_group_depth' control the formatting of exception
groups (see @ref{25c,,BaseExceptionGroup}). The depth refers to the nesting
level of the group, and the width refers to the size of a single exception
group's exceptions array. The formatted output is truncated when either
limit is exceeded.


Modifié dans la version 3.10: Ajout du paramètre `compact'.



Modifié dans la version 3.11: Added the `max_group_width' and `max_group_depth' parameters.


@geindex __cause__ (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __cause__}@anchor{436a}
@deffn {Attribut} __cause__

A @code{TracebackException} of the original
@ref{12a6,,__cause__}.
@end deffn

@geindex __context__ (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __context__}@anchor{4369}
@deffn {Attribut} __context__

A @code{TracebackException} of the original
@ref{12a5,,__context__}.
@end deffn

@geindex exceptions (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException exceptions}@anchor{436c}
@deffn {Attribut} exceptions

If @code{self} represents an @ref{1b4,,ExceptionGroup}, this field holds a list of
@code{TracebackException} instances representing the nested exceptions.
Otherwise it is @code{None}.


Ajouté dans la version 3.11.

@end deffn

@geindex __suppress_context__ (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __suppress_context__}@anchor{436b}
@deffn {Attribut} __suppress_context__

The @ref{2037,,__suppress_context__} value from the original
exception.
@end deffn

@geindex __notes__ (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException __notes__}@anchor{436d}
@deffn {Attribut} __notes__

The @ref{220c,,__notes__} value from the original exception,
or @code{None}
if the exception does not have any notes. If it is not @code{None}
is it formatted in the traceback after the exception string.


Ajouté dans la version 3.11.

@end deffn

@geindex stack (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException stack}@anchor{436e}
@deffn {Attribut} stack

A @ref{e6e,,StackSummary} representing the traceback.
@end deffn

@geindex exc_type (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException exc_type}@anchor{25a}
@deffn {Attribut} exc_type

The class of the original traceback.


Obsolète depuis la version 3.13.

@end deffn

@geindex exc_type_str (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException exc_type_str}@anchor{258}
@deffn {Attribut} exc_type_str

String display of the class of the original exception.


Ajouté dans la version 3.13.

@end deffn

@geindex filename (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException filename}@anchor{436f}
@deffn {Attribut} filename

For syntax errors - the file name where the error occurred.
@end deffn

@geindex lineno (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException lineno}@anchor{4370}
@deffn {Attribut} lineno

For syntax errors - the line number where the error occurred.
@end deffn

@geindex end_lineno (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException end_lineno}@anchor{4371}
@deffn {Attribut} end_lineno

For syntax errors - the end line number where the error occurred.
Can be @code{None} if not present.


Ajouté dans la version 3.10.

@end deffn

@geindex text (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException text}@anchor{4372}
@deffn {Attribut} text

For syntax errors - the text where the error occurred.
@end deffn

@geindex offset (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException offset}@anchor{4373}
@deffn {Attribut} offset

For syntax errors - the offset into the text where the error occurred.
@end deffn

@geindex end_offset (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException end_offset}@anchor{4374}
@deffn {Attribut} end_offset

For syntax errors - the end offset into the text where the error occurred.
Can be @code{None} if not present.


Ajouté dans la version 3.10.

@end deffn

@geindex msg (attribut traceback.TracebackException)
@anchor{library/traceback traceback TracebackException msg}@anchor{4375}
@deffn {Attribut} msg

For syntax errors - the compiler error message.
@end deffn

@geindex from_exception() (méthode de la classe traceback.TracebackException)
@anchor{library/traceback traceback TracebackException from_exception}@anchor{4376}
@deffn {Méthode} classmethod from_exception (exc, *, limit=None, lookup_lines=True, capture_locals=False)

Capture an exception for later rendering. `limit', `lookup_lines' and
`capture_locals' are as for the @ref{e6e,,StackSummary} class.

Note that when locals are captured, they are also shown in the traceback.
@end deffn

@geindex print() (méthode traceback.TracebackException)
@anchor{library/traceback traceback TracebackException print}@anchor{68f}
@deffn {Méthode} print (*, file=None, chain=True)

Print to `file' (default @code{sys.stderr}) the exception information returned by
@ref{60a,,format()}.


Ajouté dans la version 3.11.

@end deffn

@geindex format() (méthode traceback.TracebackException)
@anchor{library/traceback traceback TracebackException format}@anchor{4377}
@deffn {Méthode} format (*, chain=True)

Format the exception.

If `chain' is not @code{True}, @ref{436a,,__cause__} and @ref{4369,,__context__}
will not be formatted.

The return value is a generator of strings, each ending in a newline and
some containing internal newlines. @ref{839,,print_exception()}
is a wrapper around this method which just prints the lines to a file.
@end deffn

@geindex format_exception_only() (méthode traceback.TracebackException)
@anchor{library/traceback traceback TracebackException format_exception_only}@anchor{25b}
@deffn {Méthode} format_exception_only (*, show_group=False)

Format the exception part of the traceback.

The return value is a generator of strings, each ending in a newline.

When `show_group' is @code{False}, the generator emits the exception's
message followed by its notes (if it has any). The exception message
is normally a single string; however, for @ref{18b,,SyntaxError} exceptions,
it consists of several lines that (when printed) display detailed
information about where the syntax error occurred.

When `show_group' is @code{True}, and the exception is an instance of
@ref{25c,,BaseExceptionGroup}, the nested exceptions are included as
well, recursively, with indentation relative to their nesting depth.


Modifié dans la version 3.11: The exception's @ref{220c,,notes} are now
included in the output.



Modifié dans la version 3.13: Added the `show_group' parameter.

@end deffn
@end deffn

@node StackSummary Objects,FrameSummary Objects,TracebackException Objects,traceback --- Print or retrieve a stack traceback
@anchor{library/traceback stacksummary-objects}@anchor{4378}
@subsubsection @code{StackSummary} Objects



Ajouté dans la version 3.5.


@code{StackSummary} objects represent a call stack ready for formatting.

@geindex StackSummary (classe dans traceback)
@anchor{library/traceback traceback StackSummary}@anchor{e6e}
@deffn {Classe} traceback.StackSummary

@geindex extract() (méthode de la classe traceback.StackSummary)
@anchor{library/traceback traceback StackSummary extract}@anchor{4367}
@deffn {Méthode} classmethod extract (frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

Construct a @code{StackSummary} object from a frame generator (such as
is returned by @ref{e6c,,walk_stack()} or
@ref{e6d,,walk_tb()}).

If `limit' is supplied, only this many frames are taken from `frame_gen'.
If `lookup_lines' is @code{False}, the returned @ref{e6f,,FrameSummary}
objects will not have read their lines in yet, making the cost of
creating the @code{StackSummary} cheaper (which may be valuable if it
may not actually get formatted). If `capture_locals' is @code{True} the
local variables in each @code{FrameSummary} are captured as object
representations.


Modifié dans la version 3.12: Exceptions raised from @ref{7e7,,repr()} on a local variable (when
`capture_locals' is @code{True}) are no longer propagated to the caller.

@end deffn

@geindex from_list() (méthode de la classe traceback.StackSummary)
@anchor{library/traceback traceback StackSummary from_list}@anchor{4379}
@deffn {Méthode} classmethod from_list (a_list)

Construct a @code{StackSummary} object from a supplied list of
@ref{e6f,,FrameSummary} objects or old-style list of tuples.  Each tuple
should be a 4-tuple with `filename', `lineno', `name', `line' as the
elements.
@end deffn

@geindex format() (méthode traceback.StackSummary)
@anchor{library/traceback traceback StackSummary format}@anchor{437a}
@deffn {Méthode} format ()

Returns a list of strings ready for printing.  Each string in the
resulting list corresponds to a single @ref{6ca,,frame} from
the stack.
Each string ends in a newline; the strings may contain internal
newlines as well, for those items with source text lines.

For long sequences of the same frame and line, the first few
repetitions are shown, followed by a summary line stating the exact
number of further repetitions.


Modifié dans la version 3.6: Long sequences of repeated frames are now abbreviated.

@end deffn

@geindex format_frame_summary() (méthode traceback.StackSummary)
@anchor{library/traceback traceback StackSummary format_frame_summary}@anchor{68e}
@deffn {Méthode} format_frame_summary (frame_summary)

Returns a string for printing one of the @ref{6ca,,frames}
involved in the stack.
This method is called for each @ref{e6f,,FrameSummary} object to be
printed by @ref{437a,,StackSummary.format()}. If it returns @code{None}, the
frame is omitted from the output.


Ajouté dans la version 3.11.

@end deffn
@end deffn

@node FrameSummary Objects,Examples of Using the Module-Level Functions,StackSummary Objects,traceback --- Print or retrieve a stack traceback
@anchor{library/traceback framesummary-objects}@anchor{437b}
@subsubsection @code{FrameSummary} Objects



Ajouté dans la version 3.5.


A @code{FrameSummary} object represents a single @ref{6ca,,frame}
in a @ref{ae2,,traceback}.

@geindex FrameSummary (classe dans traceback)
@anchor{library/traceback traceback FrameSummary}@anchor{e6f}
@deffn {Classe} traceback.FrameSummary (filename, lineno, name, lookup_line=True, locals=None, line=None)

Represents a single @ref{6ca,,frame} in the
@ref{ae2,,traceback} or stack that is being formatted
or printed. It may optionally have a stringified version of the frame's
locals included in it. If `lookup_line' is @code{False}, the source code is not
looked up until the @code{FrameSummary} has the @ref{4361,,line}
attribute accessed (which also happens when casting it to a @ref{366,,tuple}).
@ref{4361,,line} may be directly provided, and will prevent line
lookups happening at all. `locals' is an optional local variable
mapping, and if supplied the variable representations are stored in the
summary for later display.

@code{FrameSummary} instances have the following attributes:

@geindex filename (attribut traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary filename}@anchor{435e}
@deffn {Attribut} filename

The filename of the source code for this frame. Equivalent to accessing
@ref{1344,,f.f_code.co_filename} on a
@ref{6ca,,frame object} `f'.
@end deffn

@geindex lineno (attribut traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary lineno}@anchor{435f}
@deffn {Attribut} lineno

The line number of the source code for this frame.
@end deffn

@geindex name (attribut traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary name}@anchor{4360}
@deffn {Attribut} name

Equivalent to accessing @ref{1ebb,,f.f_code.co_name} on
a @ref{6ca,,frame object} `f'.
@end deffn

@geindex line (attribut traceback.FrameSummary)
@anchor{library/traceback traceback FrameSummary line}@anchor{4361}
@deffn {Attribut} line

A string representing the source code for this frame, with leading and
trailing whitespace stripped.
If the source is not available, it is @code{None}.
@end deffn
@end deffn

@node Examples of Using the Module-Level Functions,Examples of Using TracebackException,FrameSummary Objects,traceback --- Print or retrieve a stack traceback
@anchor{library/traceback examples-of-using-the-module-level-functions}@anchor{437c}@anchor{library/traceback traceback-example}@anchor{437d}
@subsubsection Examples of Using the Module-Level Functions


This simple example implements a basic read-eval-print loop, similar to (but
less useful than) the standard Python interactive interpreter loop.  For a more
complete implementation of the interpreter loop, refer to the @ref{1a,,code}
module.

@example
import sys, traceback

def run_user_code(envdir):
    source = input(">>> ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = @{@}
while True:
    run_user_code(envdir)
@end example

The following example demonstrates the different ways to print and format the
exception and traceback:

@example
import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError as exc:
    print("*** print_tb:")
    traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
    print("*** print_exception:")
    traceback.print_exception(exc, limit=2, file=sys.stdout)
    print("*** print_exc:")
    traceback.print_exc(limit=2, file=sys.stdout)
    print("*** format_exc, first and last line:")
    formatted_lines = traceback.format_exc().splitlines()
    print(formatted_lines[0])
    print(formatted_lines[-1])
    print("*** format_exception:")
    print(repr(traceback.format_exception(exc)))
    print("*** extract_tb:")
    print(repr(traceback.extract_tb(exc.__traceback__)))
    print("*** format_tb:")
    print(repr(traceback.format_tb(exc.__traceback__)))
    print("*** tb_lineno:", exc.__traceback__.tb_lineno)
@end example

The output for the example would look similar to this:

@example
*** print_tb:
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
*** print_exception:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 '  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[<FrameSummary file <doctest...>, line 10 in <module>>,
 <FrameSummary file <doctest...>, line 4 in lumberjack>,
 <FrameSummary file <doctest...>, line 7 in bright_side_of_life>]
*** format_tb:
['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']
*** tb_lineno: 10
@end example

The following example shows the different ways to print and format the stack:

@example
>>> import traceback
>>> def another_function():
...     lumberstack()
...
>>> def lumberstack():
...     traceback.print_stack()
...     print(repr(traceback.extract_stack()))
...     print(repr(traceback.format_stack()))
...
>>> another_function()
  File "<doctest>", line 10, in <module>
    another_function()
  File "<doctest>", line 3, in another_function
    lumberstack()
  File "<doctest>", line 6, in lumberstack
    traceback.print_stack()
[('<doctest>', 10, '<module>', 'another_function()'),
 ('<doctest>', 3, 'another_function', 'lumberstack()'),
 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
['  File "<doctest>", line 10, in <module>\n    another_function()\n',
 '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
 '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']
@end example

This last example demonstrates the final few formatting functions:

@example
>>> import traceback
>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
 '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
>>> an_error = IndexError('tuple index out of range')
>>> traceback.format_exception_only(an_error)
['IndexError: tuple index out of range\n']
@end example

@node Examples of Using TracebackException,,Examples of Using the Module-Level Functions,traceback --- Print or retrieve a stack traceback
@anchor{library/traceback examples-of-using-tracebackexception}@anchor{437e}
@subsubsection Examples of Using @code{TracebackException}


With the helper class, we have more options:

@example
>>> import sys
>>> from traceback import TracebackException
>>>
>>> def lumberjack():
...     bright_side_of_life()
...
>>> def bright_side_of_life():
...     t = "bright", "side", "of", "life"
...     return t[5]
...
>>> try:
...     lumberjack()
... except IndexError as e:
...     exc = e
...
>>> try:
...     try:
...         lumberjack()
...     except:
...         1/0
... except Exception as e:
...     chained_exc = e
...
>>> # limit works as with the module-level functions
>>> TracebackException.from_exception(exc, limit=-2).print()
Traceback (most recent call last):
  File "<python-input-1>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

>>> # capture_locals adds local variables in frames
>>> TracebackException.from_exception(exc, limit=-2, capture_locals=True).print()
Traceback (most recent call last):
  File "<python-input-1>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[5]
           ~^^^
    t = ("bright", "side", "of", "life")
IndexError: tuple index out of range

>>> # The *chain* kwarg to print() controls whether chained
>>> # exceptions are displayed
>>> TracebackException.from_exception(chained_exc).print()
Traceback (most recent call last):
  File "<python-input-19>", line 4, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<python-input-8>", line 7, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-8>", line 11, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<python-input-19>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero

>>> TracebackException.from_exception(chained_exc).print(chain=False)
Traceback (most recent call last):
  File "<python-input-19>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero
@end example

@node __future__ --- Future statement definitions,gc --- Garbage Collector interface,traceback --- Print or retrieve a stack traceback,Environnement d'exécution Python
@anchor{library/__future__ doc}@anchor{437f}@anchor{library/__future__ future-future-statement-definitions}@anchor{4380}@anchor{library/__future__ module-__future__}@anchor{0}
@subsection @code{__future__} --- Future statement definitions


@geindex module; __future__

`Source code:' Lib/_future_.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/_future_.py}


__________________________________________________________________


Imports of the form @code{from __future__ import feature} are called
@ref{187,,future statements}. These are special-cased by the Python compiler
to allow the use of new Python features in modules containing the future statement
before the release in which the feature becomes standard.

While these future statements are given additional special meaning by the
Python compiler, they are still executed like any other import statement and
the @ref{0,,__future__} exists and is handled by the import system the same way
any other Python module would be. This design serves three purposes:


@itemize *

@item 
éviter de dérouter les outils existants qui analysent les instructions d'importation et s'attendent à trouver les modules qu'ils importent ;

@item 
Pour documenter le phasage de changements entraînant des incompatibilités : introduction, utilisation obligatoire. Il s’agit d’une forme de documentation exécutable, qui peut être inspectée par un programme en important @ref{0,,__future__} et en examinant son contenu.

@item 
To ensure that @ref{187,,future statements} run under releases prior to
Python 2.1 at least yield runtime exceptions (the import of @ref{0,,__future__}
will fail, because there was no module of that name prior to 2.1).
@end itemize

@menu
* Contenu du module: Contenu du module<5>. 

@end menu

@node Contenu du module<5>,,,__future__ --- Future statement definitions
@anchor{library/__future__ module-contents}@anchor{4381}
@subsubsection Contenu du module


Aucune fonctionnalité ne sera jamais supprimée de @ref{0,,__future__}. Depuis son introduction dans Python 2.1, les fonctionnalités suivantes ont trouvé leur places dans le langage utilisant ce mécanisme :


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

fonctionnalité

@tab

optionnel dans

@tab

obligatoire dans

@tab

effet

@item

nested_scopes

@tab

2.1.0b1

@tab

2.2

@tab

@geindex Python Enhancement Proposals; PEP 227
PEP 227@footnote{https://peps.python.org/pep-0227/} : `Portées imbriquées'

@item

générateurs

@tab

2.2.0a1

@tab

2.3

@tab

@geindex Python Enhancement Proposals; PEP 255
PEP 255@footnote{https://peps.python.org/pep-0255/} : `Générateurs simples'

@item

division

@tab

2.2.0a2

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/} : `Changement de l'opérateur de division'

@item

absolute_import

@tab

2.5.0a1

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/} : `Importations : multilignes et absolues/relatives' (ressource en anglais)

@item

with_statement

@tab

2.5.0a1

@tab

2.6

@tab

@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/} : `L'instruction "with"'

@item

print_function

@tab

2.6.0a2

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 3105
PEP 3105@footnote{https://peps.python.org/pep-3105/} : `Transformation de print en fonction'

@item

unicode_literals

@tab

2.6.0a2

@tab

3.0

@tab

@geindex Python Enhancement Proposals; PEP 3112
PEP 3112@footnote{https://peps.python.org/pep-3112/} : `Chaînes d'octets littéraux en Python 3000'

@item

generator_stop

@tab

3.5.0b1

@tab

3.7

@tab

@geindex Python Enhancement Proposals; PEP 479
PEP 479@footnote{https://peps.python.org/pep-0479/} : `Gestion de *StopIteration' à l’intérieur des générateurs*

@item

annotations

@tab

3.7.0b1

@tab

TBD @footnote{
@code{from __future__ import annotations} was previously scheduled to
become mandatory in Python 3.10, but the Python Steering Council
twice decided to delay the change
(@uref{https://mail.python.org/archives/list/python-dev@@python.org/message/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/,announcement for Python 3.10};
@uref{https://mail.python.org/archives/list/python-dev@@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/,announcement for Python 3.11}).
No final decision has been made yet. See also 
@geindex Python Enhancement Proposals; PEP 563
@uref{https://peps.python.org/pep-0563/,PEP 563} and 
@geindex Python Enhancement Proposals; PEP 649
@uref{https://peps.python.org/pep-0649/,PEP 649}.
}

@tab

@geindex Python Enhancement Proposals; PEP 563
PEP 563@footnote{https://peps.python.org/pep-0563/} : `Évaluation différée des annotations'

@end multitable


@c XXX Adding a new entry?  Remember to update simple_stmts.rst, too.

@geindex _Feature (classe dans __future__)
@anchor{library/__future__ future-classes}@anchor{4382}@anchor{library/__future__ future__ _Feature}@anchor{4383}
@deffn {Classe} __future__._Feature

Chaque instruction dans @code{__future__.py} est de la forme :

@example
FeatureName = _Feature(OptionalRelease, MandatoryRelease,
                       CompilerFlag)
@end example

où, normalement, `OptionalRelease' est inférieur à `MandatoryRelease', et les deux sont des quintuplets de la même forme que @ref{68b,,sys.version_info} :

@example
(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
 PY_MINOR_VERSION, # the 1; an int
 PY_MICRO_VERSION, # the 0; an int
 PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
 PY_RELEASE_SERIAL # the 3; an int
)
@end example
@end deffn

@geindex getOptionalRelease() (méthode __future__._Feature)
@anchor{library/__future__ future__ _Feature getOptionalRelease}@anchor{4384}
@deffn {Méthode} _Feature.getOptionalRelease ()

`OptionalRelease' enregistre la première version dans laquelle la fonctionnalité a été acceptée.
@end deffn

@geindex getMandatoryRelease() (méthode __future__._Feature)
@anchor{library/__future__ future__ _Feature getMandatoryRelease}@anchor{4385}
@deffn {Méthode} _Feature.getMandatoryRelease ()

Dans le cas d'un `MandatoryRelease' qui n'a pas encore eu lieu, `MandatoryRelease' prédit la `release' dans laquelle la fonctionnalité deviendra un élément du langage.

Sinon `MandatoryRelease' enregistre lorsque la fonctionnalité est devenue une partie du langage ; dans cette version ou les suivantes, les modules n'ont plus besoin d'une déclaration `future' pour utiliser la fonctionnalité en question, mais ils peuvent continuer à utiliser ces importations.

`MandatoryRelease' may also be @code{None}, meaning that a planned feature got
dropped or that it is not yet decided.
@end deffn

@geindex compiler_flag (attribut __future__._Feature)
@anchor{library/__future__ future__ _Feature compiler_flag}@anchor{20ec}
@deffn {Attribut} _Feature.compiler_flag

`CompilerFlag' is the (bitfield) flag that should be passed in the fourth
argument to the built-in function @ref{190,,compile()} to enable the feature in
dynamically compiled code.  This flag is stored in the @ref{20ec,,_Feature.compiler_flag}
attribute on @ref{4383,,_Feature} instances.
@end deffn


@subsubheading Voir aussi



@table @asis

@item @ref{187,,L'instruction future}

Comment le compilateur gère les importations « futures ».

@geindex Python Enhancement Proposals; PEP 236

@item PEP 236@footnote{https://peps.python.org/pep-0236/} — retour vers le @code{__future__}

La proposition originale pour le mécanisme de @code{__future__}.
@end table


@node gc --- Garbage Collector interface,inspect --- Inspect live objects,__future__ --- Future statement definitions,Environnement d'exécution Python
@anchor{library/gc doc}@anchor{4386}@anchor{library/gc gc-garbage-collector-interface}@anchor{4387}@anchor{library/gc module-gc}@anchor{5f}
@subsection @code{gc} --- Garbage Collector interface


@geindex module; gc


__________________________________________________________________


Ce module constitue une interface au ramasse-miettes facultatif. Il permet de désactiver le ramasse-miettes ou de régler la fréquence des passages. Il fournit des options de débogage, et donne aussi accès aux objets qui ne peuvent pas être détruits bien qu'ils aient été détectés comme non référencés. Le ramasse-miettes vient en complément du système de comptage de références, et peut donc être désactivé pour du code qui ne crée aucun cycle de références. On le désactive avec @code{gc.disable()}. Pour remonter à la source d'une fuite de mémoire, utilisez @code{gc.set_debug(gc.DEBUG_LEAK)}. Notez que @code{gc.DEBUG_LEAK} inclut @code{gc.DEBUG_SAVEALL}. Cette dernière option fait que les objets inatteignables, au lieu d'être détruits, sont placés dans la liste @code{gc.garbage} pour pouvoir y être examinés.

Le module @ref{5f,,gc} contient les fonctions suivantes :

@geindex enable() (dans le module gc)
@anchor{library/gc gc enable}@anchor{4388}
@deffn {Fonction} gc.enable ()

Active le ramasse-miettes.
@end deffn

@geindex disable() (dans le module gc)
@anchor{library/gc gc disable}@anchor{4389}
@deffn {Fonction} gc.disable ()

Désactive le ramasse-miettes.
@end deffn

@geindex isenabled() (dans le module gc)
@anchor{library/gc gc isenabled}@anchor{438a}
@deffn {Fonction} gc.isenabled ()

Renvoie @code{True} ou @code{False} selon que le ramasse-miettes est activé ou non.
@end deffn

@geindex collect() (dans le module gc)
@anchor{library/gc gc collect}@anchor{a28}
@deffn {Fonction} gc.collect (generation=2)

With no arguments, run a full collection.  The optional argument `generation'
may be an integer specifying which generation to collect (from 0 to 2).  A
@ref{1ff,,ValueError} is raised if the generation number is invalid. The sum of
collected objects and uncollectable objects is returned.

The free lists maintained for a number of built-in types are cleared
whenever a full collection or collection of the highest generation (2)
is run.  Not all items in some free lists may be freed due to the
particular implementation, in particular @ref{2eb,,float}.

The effect of calling @code{gc.collect()} while the interpreter is already
performing a collection is undefined.
@end deffn

@geindex set_debug() (dans le module gc)
@anchor{library/gc gc set_debug}@anchor{438b}
@deffn {Fonction} gc.set_debug (flags)

Change les options de débogage du ramasse-miettes, qui activent l'écriture d'informations sur @code{sys.stderr}. Une liste d'options se trouve plus bas. Les options peuvent se combiner par les opérateurs bit à bit.
@end deffn

@geindex get_debug() (dans le module gc)
@anchor{library/gc gc get_debug}@anchor{438c}
@deffn {Fonction} gc.get_debug ()

Renvoie les options de débogage actives.
@end deffn

@geindex get_objects() (dans le module gc)
@anchor{library/gc gc get_objects}@anchor{7ed}
@deffn {Fonction} gc.get_objects (generation=None)

Returns a list of all objects tracked by the collector, excluding the list
returned. If `generation' is not @code{None}, return only the objects tracked by
the collector that are in that generation.


Modifié dans la version 3.8: ajout du paramètre `generation'.


Lève un @ref{1848,,événement d'audit} @code{gc.get_objects} avec l'argument @code{generation}.
@end deffn

@geindex get_stats() (dans le module gc)
@anchor{library/gc gc get_stats}@anchor{f2f}
@deffn {Fonction} gc.get_stats ()

Renvoie une liste de trois dictionnaires, un par génération. Ils contiennent des statistiques sur l'action du ramasse-miettes depuis le lancement de l'interpréteur. Les clés actuellement présentes sont les suivantes (d'autres pourraient être ajoutées dans des versions ultérieures) :


@itemize *

@item 
@code{collections}, le nombre de fois où cette génération a été examinée par le ramasse-miettes ;

@item 
@code{collected}, le nombre total d'objets qui ont été détruits alors qu'ils étaient dans cette génération ;

@item 
@code{uncollectable}, le nombre total d'objets qui ont été identifiés comme indestructibles (et donc ajoutés à la liste @ref{119e,,garbage}) au sein de cette génération.
@end itemize


Ajouté dans la version 3.4.

@end deffn

@geindex set_threshold() (dans le module gc)
@anchor{library/gc gc set_threshold}@anchor{438d}
@deffn {Fonction} gc.set_threshold (threshold0[, threshold1[, threshold2]])

Règle les seuils de déclenchement du ramasse-miettes, qui déterminent sa fréquence de passage. Si `threshold0' est mis à zéro, le ramasse-miettes ne passe jamais.

Les objets sont répartis en trois générations en fonction du nombre de passages du ramasse-miettes qui les ont laissés intacts. Les objets fraîchement créés sont placés dans la génération la plus jeune, numéro 0. À chaque fois qu'un objet persiste à la suite d'un passage du ramasse-miettes, il monte d'une génération, ceci jusqu'à la génération 2, la plus âgée. Le ramasse-miettes se déclenche en fonction du nombre d'allocations et de destructions depuis le passage précédent : lorsque les allocations moins les destructions font plus que `threshold0', un passage est initié. Lors des premiers passages, seule la génération 0 est inspectée. La génération 1 est examinée périodiquement, lorsque le nombre de passages sur la génération 0 depuis le dernier passage ayant aussi examiné la génération 1 vient à excéder `threshold1'. Les règles pour la génération 2 sont plus complexes. Pour avoir des détails, voir Collecting the oldest generation@footnote{https://devguide.python.org/garbage_collector/#collecting-the-oldest-generation} (dans le guide du développeur, en anglais).
@end deffn

@geindex get_count() (dans le module gc)
@anchor{library/gc gc get_count}@anchor{438e}
@deffn {Fonction} gc.get_count ()

Renvoie un triplet des nombres totaux de passages effectués par génération.
@end deffn

@geindex get_threshold() (dans le module gc)
@anchor{library/gc gc get_threshold}@anchor{438f}
@deffn {Fonction} gc.get_threshold ()

Renvoie les seuils de passage sous la forme du triplet @code{(threshold0, threshold1, threshold2)}.
@end deffn

@geindex get_referrers() (dans le module gc)
@anchor{library/gc gc get_referrers}@anchor{7ee}
@deffn {Fonction} gc.get_referrers (*objs)

Renvoie la liste des objets qui contiennent directement une référence à l'un quelconque des arguments. Il est à noter que cette fonction prend uniquement en compte les objets suivis par le ramasse-miettes, ce qui exclut les instances de certains types d'extension qui contiennent bien des références sans pour autant prendre en charge le ramassage des miettes.

La liste renvoyée peut contenir des objets déjà isolés, mais maintenus en mémoire à cause d'un cycle. Pour les exclure, appelez @ref{a28,,collect()} juste avant @ref{7ee,,get_referrers()}.

@cartouche
@quotation Avertissement 
La manipulation des objets renvoyés par @ref{7ee,,get_referrers()} est hasardeuse car ils risquent d'être encore en cours d'initialisation, donc dans un état temporairement instable. Mieux vaut réserver @ref{7ee,,get_referrers()} au débogage.
@end quotation
@end cartouche

Lève un @ref{1848,,événement d'audit} @code{gc.get_referrers} avec l'argument @code{objs}.
@end deffn

@geindex get_referents() (dans le module gc)
@anchor{library/gc gc get_referents}@anchor{7ef}
@deffn {Fonction} gc.get_referents (*objs)

Renvoie une liste des objets pointés par les références que contiennent les arguments. Ils sont déterminés en appelant, si présente, la méthode C @ref{768,,tp_traverse} de chaque argument, qui visite les objets auxquels cet argument fait référence. Il est à noter que @ref{768,,tp_traverse} n'est définie que par les objets qui gèrent le ramassage des miettes, et n'a l'obligation de visiter que les objets qui peuvent potentiellement faire partie d'un cycle. Ainsi, la liste renvoyée par cette fonction ne contient par forcément tous les objets qu'il est possible d'atteindre à partir des arguments. Par exemple, si l'un des arguments contient un entier, ce dernier objet peut être présent ou non dans la liste.

Lève un @ref{1848,,événement d'audit} @code{gc.get_referents} avec l'argument @code{objs}.
@end deffn

@geindex is_tracked() (dans le module gc)
@anchor{library/gc gc is_tracked}@anchor{12ec}
@deffn {Fonction} gc.is_tracked (obj)

Renvoie @code{True} ou @code{False} selon que l'argument est suivi ou non par le ramasse-miettes. En règle générale, les objets atomiques ne sont pas suivis, tandis que les objets non-atomiques, tels que les conteneurs et instances de classes définies par l'utilisateur, le sont. Cependant, certains types présentent des optimisations qui permettent de se passer avantageusement du ramasse-miettes dans les cas simples, comme les dictionnaires dont toutes les clés et valeurs sont atomiques :

@example
>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked(@{@})
False
>>> gc.is_tracked(@{"a": 1@})
False
>>> gc.is_tracked(@{"a": []@})
True
@end example


Ajouté dans la version 3.1.

@end deffn

@geindex is_finalized() (dans le module gc)
@anchor{library/gc gc is_finalized}@anchor{8ea}
@deffn {Fonction} gc.is_finalized (obj)

Renvoie @code{True} ou @code{False} selon que l'argument a été finalisé par le ramasse-miettes.

@example
>>> x = None
>>> class Lazarus:
...     def __del__(self):
...         global x
...         x = self
...
>>> lazarus = Lazarus()
>>> gc.is_finalized(lazarus)
False
>>> del lazarus
>>> gc.is_finalized(x)
True
@end example


Ajouté dans la version 3.9.

@end deffn

@geindex freeze() (dans le module gc)
@anchor{library/gc gc freeze}@anchor{b28}
@deffn {Fonction} gc.freeze ()

Freeze all the objects tracked by the garbage collector; move them to a
permanent generation and ignore them in all the future collections.

If a process will @code{fork()} without @code{exec()}, avoiding unnecessary
copy-on-write in child processes will maximize memory sharing and reduce
overall memory usage. This requires both avoiding creation of freed "holes"
in memory pages in the parent process and ensuring that GC collections in
child processes won't touch the @code{gc_refs} counter of long-lived objects
originating in the parent process. To accomplish both, call @code{gc.disable()}
early in the parent process, @code{gc.freeze()} right before @code{fork()}, and
@code{gc.enable()} early in child processes.


Ajouté dans la version 3.7.

@end deffn

@geindex unfreeze() (dans le module gc)
@anchor{library/gc gc unfreeze}@anchor{b29}
@deffn {Fonction} gc.unfreeze ()

Unfreeze the objects in the permanent generation, put them back into the
oldest generation.


Ajouté dans la version 3.7.

@end deffn

@geindex get_freeze_count() (dans le module gc)
@anchor{library/gc gc get_freeze_count}@anchor{b2a}
@deffn {Fonction} gc.get_freeze_count ()

Return the number of objects in the permanent generation.


Ajouté dans la version 3.7.

@end deffn

Les variables suivantes sont publiques, mais elles ne sont pas censées être modifiées (vous pouvez les muter, mais pas les redéfinir) :

@geindex garbage (dans le module gc)
@anchor{library/gc gc garbage}@anchor{119e}
@deffn {Données} gc.garbage

Liste des objets indestructibles, que le ramasse-miettes n'a pas pu éliminer bien qu'ils soient inatteignables. Depuis Python 3.4, cette liste demeure la plupart du temps vide. Elle peut se remplir si le programme fait appel à des types d'extension définis en C avec un champ @code{tp_del} différent de @code{NULL}.

Si @ref{4390,,DEBUG_SAVEALL} est actif, tous les objets inatteignables sont ajoutés à cette liste au lieu d'être détruits.


Modifié dans la version 3.2: Si cette liste n'est pas vide lors de l'@ref{14d,,arrêt de l'interpréteur}, un @ref{241,,ResourceWarning} est émis (les avertissements de ce type sont silencieux par défaut). De plus, si @ref{119f,,DEBUG_UNCOLLECTABLE} est actif, tous les objets indestructibles sont affichés.



Modifié dans la version 3.4: Following 
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/}, objects with a @ref{1ee3,,__del__()} method don't end
up in @ref{119e,,gc.garbage} anymore.

@end deffn

@geindex callbacks (dans le module gc)
@anchor{library/gc gc callbacks}@anchor{10a9}
@deffn {Données} gc.callbacks

Liste de fonctions de rappel lancées par le ramasse-miettes avant et après un passage. Elles prennent deux arguments, `phase' et `info'.

`phase' peut prendre deux valeurs :

@quotation

@code{"start"} lorsque le passage du ramasse-miettes est imminent.

@code{"stop"} lorsque le passage du ramasse-miettes vient de se terminer.
@end quotation

`info' est un dictionnaire qui donne plus d'informations à la fonction de rappel. Les clés suivantes sont actuellement présentes :

@quotation

@code{"generation"}, la génération la plus âgée intégrée à ce passage ;

@code{"collected"} : si `phase' vaut @code{"stop"}, le nombre d'objets détruits avec succès ;

@code{"uncollectable"} : si `phase' vaut @code{"stop"}, le nombre d'objets indestructibles ajoutés à @ref{119e,,garbage}.
@end quotation

Toute application peut ajouter ses propres fonctions de rappel à cette liste. Voici les principales applications :

@quotation

Faire des statistiques sur le passage du ramasse-miettes, par exemple la fréquence à laquelle chaque génération est examinée, ou bien le temps d'un passage ;

Identifier les types définis par une application dont les instances s'ajoutent à @ref{119e,,garbage} car elles sont indestructibles.
@end quotation


Ajouté dans la version 3.3.

@end deffn

Les constantes suivantes définissent les options de débogage que l'on peut passer à @ref{438b,,set_debug()} :

@geindex DEBUG_STATS (dans le module gc)
@anchor{library/gc gc DEBUG_STATS}@anchor{4391}
@deffn {Données} gc.DEBUG_STATS

Affiche des statistiques durant les passages du ramasse-miettes. Utile pour pouvoir régler la fréquence des passages.
@end deffn

@geindex DEBUG_COLLECTABLE (dans le module gc)
@anchor{library/gc gc DEBUG_COLLECTABLE}@anchor{4392}
@deffn {Données} gc.DEBUG_COLLECTABLE

Affiche des informations sur les objets détruits.
@end deffn

@geindex DEBUG_UNCOLLECTABLE (dans le module gc)
@anchor{library/gc gc DEBUG_UNCOLLECTABLE}@anchor{119f}
@deffn {Données} gc.DEBUG_UNCOLLECTABLE

Affiche des informations sur les objets indestructibles (ceux qui sont ajoutés à la liste @code{garbage}, qui sont inatteignables mais dont la mémoire ne peut pas être libérée).


Modifié dans la version 3.2: Affiche également le contenu de @ref{119e,,garbage} à l'@ref{14d,,arrêt de l'interpréteur}, pour peu que cette liste ne soit pas vide.

@end deffn

@geindex DEBUG_SAVEALL (dans le module gc)
@anchor{library/gc gc DEBUG_SAVEALL}@anchor{4390}
@deffn {Données} gc.DEBUG_SAVEALL

Lorsque cette option est active, les objets inatteignables sont ajoutés à la liste `garbage' au lieu d'être supprimés. Ceci est utile pour déboguer une fuite de mémoire.
@end deffn

@geindex DEBUG_LEAK (dans le module gc)
@anchor{library/gc gc DEBUG_LEAK}@anchor{4393}
@deffn {Données} gc.DEBUG_LEAK

Combinaison des options utiles au débogage d'une fuite de mémoire. Il s'agit d'un raccourci pour @code{DEBUG_COLLECTABLE|DEBUG_UNCOLLECTABLE|DEBUG_SAVEALL}.
@end deffn

@node inspect --- Inspect live objects,site --- Site-specific configuration hook,gc --- Garbage Collector interface,Environnement d'exécution Python
@anchor{library/inspect doc}@anchor{4394}@anchor{library/inspect inspect-inspect-live-objects}@anchor{4395}
@subsection @code{inspect} --- Inspect live objects


@c import inspect
@c from inspect import *

@geindex module; inspect
@anchor{library/inspect module-inspect}@anchor{7d}
`Code source :' Lib/inspect.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/inspect.py}


__________________________________________________________________


Le module @ref{7d,,inspect} implémente plusieurs fonctions permettant d'obtenir de l'information à propos d'objets tels que les modules, classes, méthodes, fonctions, traces de piles, cadres d'exécution et objets code. Par exemple, il permet d'inspecter le contenu d'une classe, de retrouver le code source d'une méthode, d'extraire et de mettre en forme une liste d'arguments pour une fonction, ou obtenir toute l'information nécessaire pour afficher une pile d'appels détaillée.

Ce module donne accès à 4 types de services : vérification de typage, obtention de code source, inspection de classes et de fonctions et examen de la pile d'exécution.

@menu
* Types et membres:: 
* Récupération du code source:: 
* Introspection des appelables avec l'objet Signature:: 
* Classes et fonctions: Classes et fonctions<2>. 
* La pile d'interpréteur:: 
* Recherche dynamique d'attributs:: 
* Current State of Generators@comma{} Coroutines@comma{} and Asynchronous Generators: Current State of Generators Coroutines and Asynchronous Generators. 
* Bit d'option des objets code:: 
* Buffer flags:: 
* Interface en ligne de commande: Interface en ligne de commande<9>. 

@end menu

@node Types et membres,Récupération du code source,,inspect --- Inspect live objects
@anchor{library/inspect inspect-types}@anchor{1938}@anchor{library/inspect types-and-members}@anchor{4396}
@subsubsection Types et membres


The @ref{17e2,,getmembers()} function retrieves the members of an object such as a
class or module. The functions whose names begin with "is" are mainly
provided as convenient choices for the second argument to @ref{17e2,,getmembers()}.
They also help you determine when you can expect to find the following special
attributes (see @ref{1e99,,Import-related attributes on module objects} for module attributes):

@c this function name is too big to fit in the ascii-art table below


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Type

@tab

Attribut

@tab

Description

@item

classe

@tab

__doc__

@tab

texte de documentation

@item

@tab

__name__

@tab

nom de la classe lors de sa définition

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

__module__

@tab

nom du module contenant la classe lors de sa définition

@item

@tab

__type_params__

@tab

A tuple containing the
@ref{2b0,,type parameters} of
a generic class

@item

méthode

@tab

__doc__

@tab

texte de documentation

@item

@tab

__name__

@tab

nom de la méthode lors de sa définition

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

__func__

@tab

objet fonction contenant l'implémentation de la méthode

@item

@tab

__self__

@tab

instance à laquelle cette méthode est liée, ou @code{None}

@item

@tab

__module__

@tab

nom du module contenant la méthode lors de sa définition

@item

fonction

@tab

__doc__

@tab

texte de documentation

@item

@tab

__name__

@tab

nom de la fonction lors de sa définition

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

__code__

@tab

objet code contenant le @ref{185,,code intermédiaire} d'une fonction compilée

@item

@tab

__defaults__

@tab

`n'-uplet de valeurs par défaut pour arguments positionnels ou nommés

@item

@tab

__kwdefaults__

@tab

tableau de correspondance de valeurs par défaut pour les paramètres nommés

@item

@tab

__globals__

@tab

espace de nommage global lors de la définition de la fonction

@item

@tab

__builtins__

@tab

builtins namespace

@item

@tab

__annotations__

@tab

tableau de correspondance des paramètres à leur annotation ; @code{"return"} est un mot-clé réservé pour les annotations de type renvoyé.

@item

@tab

__type_params__

@tab

A tuple containing the
@ref{2b0,,type parameters} of
a generic function

@item

@tab

__module__

@tab

nom du module contenant la fonction lors de sa définition

@item

traceback

@tab

tb_frame

@tab

objet cadre à ce niveau

@item

@tab

tb_lasti

@tab

index de la dernière instruction lancée dans le code intermédiaire (@code{bytecode})

@item

@tab

tb_lineno

@tab

numéro de ligne courant dans le code source Python

@item

@tab

tb_next

@tab

trace de pile interne suivante (appel par le cadre courant)

@item

cadre

@tab

f_back

@tab

trace d'exécution externe suivante (le contexte appelant du cadre courant)

@item

@tab

f_builtins

@tab

espace de nommage natif du cadre courant

@item

@tab

f_code

@tab

objet code exécuté dans le cadre courant

@item

@tab

f_globals

@tab

espace de nommage global tel que vu par cadre courant

@item

@tab

f_lasti

@tab

index de la dernière instruction lancée dans le code intermédiaire (@code{bytecode})

@item

@tab

f_lineno

@tab

numéro de ligne courant dans le code source Python

@item

@tab

f_locals

@tab

espace de nommage local du cadre courant

@item

@tab

f_trace

@tab

fonction de traçage du cadre courant, ou @code{None}

@item

code

@tab

co_argcount

@tab

nombre d'arguments (excluant les arguments `keyword-only', * ou **)

@item

@tab

co_code

@tab

texte du code intermédiaire compilé

@item

@tab

co_cellvars

@tab

`n'-uplet du nom des cellules variables (référencées par leur contexte)

@item

@tab

co_consts

@tab

`n'-uplet des constantes utilisées dans le code intermédiaire (@code{bytecode})

@item

@tab

co_filename

@tab

nom du fichier dans lequel cet objet code a été créé

@item

@tab

co_firstlineno

@tab

numéro de la première ligne dans le code source Python

@item

@tab

co_flags

@tab

`bitmap' des options @code{CO_*}, voir plus @ref{1ecb,,ici}

@item

@tab

co_lnotab

@tab

tableau de correspondance encodée des numéros de ligne aux numéros d'indices du code intermédiaire (@code{bytecode})

@item

@tab

co_freevars

@tab

`n'-uplet des noms de variables libres (référencées par la fermeture (`closure' en anglais) d'une fonction)

@item

@tab

co_posonlyargcount

@tab

nombre d'arguments positionnels

@item

@tab

co_kwonlyargcount

@tab

nombre d'arguments `keywords-only' (excluant les arguments **)

@item

@tab

co_name

@tab

nom de l'objet code lors de sa définition

@item

@tab

co_qualname

@tab

fully qualified name with
which this code object
was defined

@item

@tab

co_names

@tab

tuple of names other
than arguments and
function locals

@item

@tab

co_nlocals

@tab

nombre de variables locales

@item

@tab

co_stacksize

@tab

espace requis pour la pile de la machine virtuelle

@item

@tab

co_varnames

@tab

`n'-uplet des noms des arguments et variables locales

@item

generator

@tab

__name__

@tab

nom

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

gi_frame

@tab

cadre

@item

@tab

gi_running

@tab

est-ce que le générateur est en cours d'exécution ?

@item

@tab

gi_code

@tab

code

@item

@tab

gi_yieldfrom

@tab

objet pointé par l'itérateur @code{yield from}, ou @code{None}

@item

@code{async generator}

@tab

__name__

@tab

nom

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

@code{cr_await}

@tab

objet sur lequel on attend (`await') présentement, ou @code{None}

@item

@tab

@code{gi_frame}

@tab

cadre

@item

@tab

@code{ag_running}

@tab

est-ce que le générateur est en cours d'exécution ?

@item

@tab

@code{ag_code}

@tab

code

@item

coroutine

@tab

__name__

@tab

nom

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

@code{cr_await}

@tab

objet sur lequel on attend (`await') présentement, ou @code{None}

@item

@tab

@code{cr_frame}

@tab

cadre

@item

@tab

@code{cr_running}

@tab

est-ce que la coroutine est en cours d'exécution ?

@item

@tab

@code{cr_code}

@tab

code

@item

@tab

@code{cr_origin}

@tab

lieu de création de la coroutine, ou @code{None}. Voir @ref{b7a,,sys.set_coroutine_origin_tracking_depth()}

@item

builtin

@tab

__doc__

@tab

texte de documentation

@item

@tab

__name__

@tab

nom originel de cette fonction ou méthode

@item

@tab

__qualname__

@tab

nom qualifié

@item

@tab

__self__

@tab

instance à laquelle est liée une méthode, ou @code{None}

@end multitable



Modifié dans la version 3.5: ajout des attributs @code{__qualname} et @code{gi_yieldfrom} aux générateurs.

L'attribut @code{__name__} du générateur est maintenant déterminé par le nom de la fonction, plutôt que le nom du code, et peut maintenant être modifié.



Modifié dans la version 3.7: Ajout de l'attribut @code{cr_origin} aux coroutines.



Modifié dans la version 3.10: Add @code{__builtins__} attribute to functions.


@geindex getmembers() (dans le module inspect)
@anchor{library/inspect inspect getmembers}@anchor{17e2}
@deffn {Fonction} inspect.getmembers (object[, predicate])

Renvoie tous les membres d'un objet sous la forme d'une liste de paires @code{(nom, valeur)}, ordonnée par nom. Si l'argument `predicate' (qui sera appelé avec la @code{valeur} de chaque membre) est fourni, seuls les membres pour lequel le prédicat est vrai seront inclus.

@cartouche
@quotation Note 
@ref{17e2,,getmembers()} will only return class attributes defined in the
metaclass when the argument is a class and those attributes have been
listed in the metaclass' custom @ref{1ee9,,__dir__()}.
@end quotation
@end cartouche
@end deffn

@geindex getmembers_static() (dans le module inspect)
@anchor{library/inspect inspect getmembers_static}@anchor{634}
@deffn {Fonction} inspect.getmembers_static (object[, predicate])

Return all the members of an object in a list of @code{(name, value)}
pairs sorted by name without triggering dynamic lookup via the descriptor
protocol, __getattr__ or __getattribute__. Optionally, only return members
that satisfy a given predicate.

@cartouche
@quotation Note 
@ref{634,,getmembers_static()} may not be able to retrieve all members
that getmembers can fetch (like dynamically created attributes)
and may find members that getmembers can't (like descriptors
that raise AttributeError). It can also return descriptor objects
instead of instance members in some cases.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex getmodulename() (dans le module inspect)
@anchor{library/inspect inspect getmodulename}@anchor{d27}
@deffn {Fonction} inspect.getmodulename (path)

Renvoie le nom du module indiqué par le fichier `path', excluant le nom des paquets englobants. L'extension du fichier est vérifiée parmi toutes les entrées renvoyées par @ref{4397,,importlib.machinery.all_suffixes()}. S'il y a une correspondance, le chemin final est renvoyé, sans l'extension. Autrement, @code{None} est renvoyé.

Notez que cette fonction renvoie un nom significatif `seulement' pour les modules Python - les chemins qui réfèrent à des paquets Python donnent toujours @code{None}.


Modifié dans la version 3.3: La fonction est basée directement sur @ref{76,,importlib}.

@end deffn

@geindex ismodule() (dans le module inspect)
@anchor{library/inspect inspect ismodule}@anchor{4398}
@deffn {Fonction} inspect.ismodule (object)

Renvoie @code{True} si l'objet est un module.
@end deffn

@geindex isclass() (dans le module inspect)
@anchor{library/inspect inspect isclass}@anchor{4399}
@deffn {Fonction} inspect.isclass (object)

Renvoie @code{True} si l'objet est une classe, qu'il s'agisse d'un objet natif ou qu'elle soit écrite en Python.
@end deffn

@geindex ismethod() (dans le module inspect)
@anchor{library/inspect inspect ismethod}@anchor{439a}
@deffn {Fonction} inspect.ismethod (object)

Renvoie @code{True} si l'objet est une méthode liée écrite en Python.
@end deffn

@geindex isfunction() (dans le module inspect)
@anchor{library/inspect inspect isfunction}@anchor{439b}
@deffn {Fonction} inspect.isfunction (object)

Renvoie @code{True} si l'objet est une fonction Python, ce qui inclut les fonctions créées par une expression @ref{26bc,,lambda}.
@end deffn

@geindex isgeneratorfunction() (dans le module inspect)
@anchor{library/inspect inspect isgeneratorfunction}@anchor{175f}
@deffn {Fonction} inspect.isgeneratorfunction (object)

Renvoie @code{True} si l'objet est un générateur.


Modifié dans la version 3.8: les fonctions englobées dans @ref{40a,,functools.partial()} renvoient maintenant @code{True} si la fonction englobée est un générateur Python.



Modifié dans la version 3.13: Functions wrapped in @ref{a69,,functools.partialmethod()} now return @code{True}
if the wrapped function is a Python generator function.

@end deffn

@geindex isgenerator() (dans le module inspect)
@anchor{library/inspect inspect isgenerator}@anchor{439c}
@deffn {Fonction} inspect.isgenerator (object)

Renvoie @code{True} si l'objet est un générateur.
@end deffn

@geindex iscoroutinefunction() (dans le module inspect)
@anchor{library/inspect inspect iscoroutinefunction}@anchor{2e2}
@deffn {Fonction} inspect.iscoroutinefunction (object)

Return @code{True} if the object is a @ref{d64,,coroutine function} (a function
defined with an @ref{5bb,,async def} syntax), a @ref{40a,,functools.partial()}
wrapping a @ref{d64,,coroutine function}, or a sync function marked with
@ref{47a,,markcoroutinefunction()}.


Ajouté dans la version 3.5.



Modifié dans la version 3.8: les fonctions englobées par @ref{40a,,functools.partial()} renvoient maintenant @code{True} si la fonction englobée est une @ref{d64,,coroutine}.



Modifié dans la version 3.12: Sync functions marked with @ref{47a,,markcoroutinefunction()} now return
@code{True}.



Modifié dans la version 3.13: Functions wrapped in @ref{a69,,functools.partialmethod()} now return @code{True}
if the wrapped function is a @ref{d64,,coroutine function}.

@end deffn

@geindex markcoroutinefunction() (dans le module inspect)
@anchor{library/inspect inspect markcoroutinefunction}@anchor{47a}
@deffn {Fonction} inspect.markcoroutinefunction (func)

Decorator to mark a callable as a @ref{d64,,coroutine function} if it would not
otherwise be detected by @ref{2e2,,iscoroutinefunction()}.

This may be of use for sync functions that return a @ref{47b,,coroutine}, if
the function is passed to an API that requires @ref{2e2,,iscoroutinefunction()}.

When possible, using an @ref{5bb,,async def} function is preferred. Also
acceptable is calling the function and testing the return with
@ref{e03,,iscoroutine()}.


Ajouté dans la version 3.12.

@end deffn

@geindex iscoroutine() (dans le module inspect)
@anchor{library/inspect inspect iscoroutine}@anchor{e03}
@deffn {Fonction} inspect.iscoroutine (object)

Renvoie @code{True} si l'objet est une @ref{47b,,coroutine} créée par une fonction @ref{5bb,,async def}.


Ajouté dans la version 3.5.

@end deffn

@geindex isawaitable() (dans le module inspect)
@anchor{library/inspect inspect isawaitable}@anchor{e04}
@deffn {Fonction} inspect.isawaitable (object)

Renvoie @code{True} si l'objet peut être utilisé par une expression @ref{1b7,,await}.

Can also be used to distinguish generator-based coroutines from regular
generators:

@example
import types

def gen():
    yield
@@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())
@end example


Ajouté dans la version 3.5.

@end deffn

@geindex isasyncgenfunction() (dans le module inspect)
@anchor{library/inspect inspect isasyncgenfunction}@anchor{1760}
@deffn {Fonction} inspect.isasyncgenfunction (object)

Return @code{True} if the object is an @ref{1fba,,asynchronous generator} function,
for example:

@example
>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True
@end example


Ajouté dans la version 3.6.



Modifié dans la version 3.8: Functions wrapped in @ref{40a,,functools.partial()} now return @code{True} if the
wrapped function is an @ref{1fba,,asynchronous generator} function.



Modifié dans la version 3.13: Functions wrapped in @ref{a69,,functools.partialmethod()} now return @code{True}
if the wrapped function is a @ref{d64,,coroutine function}.

@end deffn

@geindex isasyncgen() (dans le module inspect)
@anchor{library/inspect inspect isasyncgen}@anchor{439d}
@deffn {Fonction} inspect.isasyncgen (object)

Renvoie @code{True} si l'objet est un @ref{42ac,,itérateur de générateur asynchrone} créé par une fonction @ref{1fba,,génératrice asynchrone}.


Ajouté dans la version 3.6.

@end deffn

@geindex istraceback() (dans le module inspect)
@anchor{library/inspect inspect istraceback}@anchor{439e}
@deffn {Fonction} inspect.istraceback (object)

Renvoie @code{True} si l'objet est une trace d'exécution.
@end deffn

@geindex isframe() (dans le module inspect)
@anchor{library/inspect inspect isframe}@anchor{439f}
@deffn {Fonction} inspect.isframe (object)

Renvoie @code{True} si l'objet est un cadre.
@end deffn

@geindex iscode() (dans le module inspect)
@anchor{library/inspect inspect iscode}@anchor{43a0}
@deffn {Fonction} inspect.iscode (object)

Renvoie @code{True} si l'objet est un code.
@end deffn

@geindex isbuiltin() (dans le module inspect)
@anchor{library/inspect inspect isbuiltin}@anchor{43a1}
@deffn {Fonction} inspect.isbuiltin (object)

Renvoie @code{True} si l'objet est une fonction native ou une méthode liée native.
@end deffn

@geindex ismethodwrapper() (dans le module inspect)
@anchor{library/inspect inspect ismethodwrapper}@anchor{635}
@deffn {Fonction} inspect.ismethodwrapper (object)

Return @code{True} if the type of object is a @ref{636,,MethodWrapperType}.

These are instances of @ref{636,,MethodWrapperType}, such as @ref{608,,__str__()},
@ref{ae8,,__eq__()} and @ref{607,,__repr__()}.


Ajouté dans la version 3.11.

@end deffn

@geindex isroutine() (dans le module inspect)
@anchor{library/inspect inspect isroutine}@anchor{1573}
@deffn {Fonction} inspect.isroutine (object)

Renvoie @code{True} si l'objet est une fonction, qu'elle soit définie par l'utilisateur, native, ou une méthode.
@end deffn

@geindex isabstract() (dans le module inspect)
@anchor{library/inspect inspect isabstract}@anchor{43a2}
@deffn {Fonction} inspect.isabstract (object)

Renvoie @code{True} si l'objet est une classe de base abstraite.
@end deffn

@geindex ismethoddescriptor() (dans le module inspect)
@anchor{library/inspect inspect ismethoddescriptor}@anchor{1572}
@deffn {Fonction} inspect.ismethoddescriptor (object)

Renvoie @code{True} si l'objet est un descripteur de méthode sauf si @ref{439a,,ismethod()}, @ref{4399,,isclass()}, @ref{439b,,isfunction()} ou @ref{43a1,,isbuiltin()} sont vrais (@code{True}).

This, for example, is true of @code{int.__add__}.  An object passing this test
has a @ref{149d,,__get__()} method, but not a @ref{1eec,,__set__()}
method or a @ref{1591,,__delete__()} method.  Beyond that, the set of
attributes varies.  A @ref{104f,,__name__} attribute is usually
sensible, and @ref{915,,__doc__} often is.

Methods implemented via descriptors that also pass one of the other tests
return @code{False} from the @ref{1572,,ismethoddescriptor()} test, simply because the
other tests promise more -- you can, e.g., count on having the
@ref{12da,,__func__} attribute (etc) when an object passes
@ref{439a,,ismethod()}.


Modifié dans la version 3.13: This function no longer incorrectly reports objects with @ref{149d,,__get__()}
and @ref{1591,,__delete__()}, but not @ref{1eec,,__set__()}, as being method
descriptors (such objects are data descriptors, not method descriptors).

@end deffn

@geindex isdatadescriptor() (dans le module inspect)
@anchor{library/inspect inspect isdatadescriptor}@anchor{43a3}
@deffn {Fonction} inspect.isdatadescriptor (object)

Renvoie @code{True} si l'objet est un descripteur de données.

Data descriptors have a @ref{1eec,,__set__} or a @ref{1591,,__delete__} method.
Examples are properties (defined in Python), getsets, and members.  The
latter two are defined in C and there are more specific tests available for
those types, which is robust across Python implementations.  Typically, data
descriptors will also have @ref{104f,,__name__} and @code{__doc__} attributes
(properties, getsets, and members have both of these attributes), but this is
not guaranteed.
@end deffn

@geindex isgetsetdescriptor() (dans le module inspect)
@anchor{library/inspect inspect isgetsetdescriptor}@anchor{43a4}
@deffn {Fonction} inspect.isgetsetdescriptor (object)

Renvoie @code{True} si l'objet est un descripteur `getset'.

`Particularité de l'implémentation CPython :' `getsets' sont des attributs définis dans des extensions de modules via des structures @ref{ba6,,PyGetSetDef}. Pour les implémentations Python ne possédant pas ces types, cette méthode renvoie toujours @code{False}.
@end deffn

@geindex ismemberdescriptor() (dans le module inspect)
@anchor{library/inspect inspect ismemberdescriptor}@anchor{43a5}
@deffn {Fonction} inspect.ismemberdescriptor (object)

Renvoie @code{True} si l'objet est un membre descripteur.

`Particularité de l'implémentation CPython :' Les membres descripteurs sont des attributs définis dans des extensions de modules via des structures @ref{53a,,PyMemberDef}. Pour les implémentations Python ne possédant pas ces types, cette méthode renvoie toujours @code{False}.
@end deffn

@node Récupération du code source,Introspection des appelables avec l'objet Signature,Types et membres,inspect --- Inspect live objects
@anchor{library/inspect inspect-source}@anchor{43a6}@anchor{library/inspect retrieving-source-code}@anchor{43a7}
@subsubsection Récupération du code source


@geindex getdoc() (dans le module inspect)
@anchor{library/inspect inspect getdoc}@anchor{9e8}
@deffn {Fonction} inspect.getdoc (object)

Get the documentation string for an object, cleaned up with @ref{163e,,cleandoc()}.
If the documentation string for an object is not provided and the object is
a class, a method, a property or a descriptor, retrieve the documentation
string from the inheritance hierarchy.
Return @code{None} if the documentation string is invalid or missing.


Modifié dans la version 3.5: les chaînes de documentation sont maintenant héritées si elles ne sont pas surchargées.

@end deffn

@geindex getcomments() (dans le module inspect)
@anchor{library/inspect inspect getcomments}@anchor{154e}
@deffn {Fonction} inspect.getcomments (object)

Renvoie en une chaîne de caractères toute ligne de commentaire qui précède immédiatement le code source de l'objet (pour une classe, fonction ou méthode) ou en début d'un fichier de code source Python (si l'objet est un module). Si le code source de l'objet n'est pas disponible, renvoie @code{None}. Cela peut se produire si l'objet a été défini en C ou dans un interpréteur interactif.
@end deffn

@geindex getfile() (dans le module inspect)
@anchor{library/inspect inspect getfile}@anchor{1a32}
@deffn {Fonction} inspect.getfile (object)

Renvoie le nom du fichier (texte ou binaire) dans lequel un objet a été défini. Cette méthode échoue avec @ref{522,,TypeError} si l'objet est un module, une classe ou une fonction native.
@end deffn

@geindex getmodule() (dans le module inspect)
@anchor{library/inspect inspect getmodule}@anchor{1772}
@deffn {Fonction} inspect.getmodule (object)

Try to guess which module an object was defined in. Return @code{None}
if the module cannot be determined.
@end deffn

@geindex getsourcefile() (dans le module inspect)
@anchor{library/inspect inspect getsourcefile}@anchor{1773}
@deffn {Fonction} inspect.getsourcefile (object)

Return the name of the Python source file in which an object was defined
or @code{None} if no way can be identified to get the source.  This
will fail with a @ref{522,,TypeError} if the object is a built-in module, class, or
function.
@end deffn

@geindex getsourcelines() (dans le module inspect)
@anchor{library/inspect inspect getsourcelines}@anchor{43a8}
@deffn {Fonction} inspect.getsourcelines (object)

Return a list of source lines and starting line number for an object. The
argument may be a module, class, method, function, traceback, frame, or code
object.  The source code is returned as a list of the lines corresponding to the
object and the line number indicates where in the original source file the first
line of code was found.  An @ref{40d,,OSError} is raised if the source code cannot
be retrieved.
A @ref{522,,TypeError} is raised if the object is a built-in module, class, or
function.


Modifié dans la version 3.3: @ref{40d,,OSError} est levé plutôt que @ref{103b,,IOError}, qui est maintenant un alias de ce premier.

@end deffn

@geindex getsource() (dans le module inspect)
@anchor{library/inspect inspect getsource}@anchor{154d}
@deffn {Fonction} inspect.getsource (object)

Return the text of the source code for an object. The argument may be a module,
class, method, function, traceback, frame, or code object.  The source code is
returned as a single string.  An @ref{40d,,OSError} is raised if the source code
cannot be retrieved.
A @ref{522,,TypeError} is raised if the object is a built-in module, class, or
function.


Modifié dans la version 3.3: @ref{40d,,OSError} est levé plutôt que @ref{103b,,IOError}, qui est maintenant un alias de ce premier.

@end deffn

@geindex cleandoc() (dans le module inspect)
@anchor{library/inspect inspect cleandoc}@anchor{163e}
@deffn {Fonction} inspect.cleandoc (doc)

Nettoie les indentations des chaînes de documentation qui sont indentées de manières à s'aligner avec les blocs de code.

Enlève tous les espaces blancs en début de ligne à partir de la première. Tout espace blanc en début de ligne qui puisse être enlevé de manière uniforme à partir de la seconde ligne le sera. Les lignes vides en début et en fin de document seront ensuite enlevées. Les tabulations seront converties en espaces.
@end deffn

@node Introspection des appelables avec l'objet Signature,Classes et fonctions<2>,Récupération du code source,inspect --- Inspect live objects
@anchor{library/inspect inspect-signature-object}@anchor{43a9}@anchor{library/inspect introspecting-callables-with-the-signature-object}@anchor{43aa}
@subsubsection Introspection des appelables avec l'objet Signature



Ajouté dans la version 3.3.


The @ref{1ca,,Signature} object represents the call signature of a callable object
and its return annotation. To retrieve a @code{Signature} object,
use the @code{signature()}
function.

@geindex signature() (dans le module inspect)
@anchor{library/inspect inspect signature}@anchor{722}
@deffn {Fonction} inspect.signature (callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Return a @ref{1ca,,Signature} object for the given `callable':

@example
>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b: int, **kwargs)'

>>> str(sig.parameters['b'])
'b: int'

>>> sig.parameters['b'].annotation
<class 'int'>
@end example

La fonction accepte une grande étendue d'appelables Python, des fonctions et classes jusqu'aux objets @code{functools.partials()}.

For objects defined in modules using stringized annotations
(@code{from __future__ import annotations}), @ref{722,,signature()} will
attempt to automatically un-stringize the annotations using
@ref{7fd,,get_annotations()}.  The
`globals', `locals', and `eval_str' parameters are passed
into @ref{7fd,,get_annotations()} when resolving the
annotations; see the documentation for @ref{7fd,,get_annotations()}
for instructions on how to use these parameters.

Raises @ref{1ff,,ValueError} if no signature can be provided, and
@ref{522,,TypeError} if that type of object is not supported.  Also,
if the annotations are stringized, and `eval_str' is not false,
the @code{eval()} call(s) to un-stringize the annotations in @ref{7fd,,get_annotations()}
could potentially raise any kind of exception.

Une barre oblique (@code{/}) dans la signature d'une fonction dénote que les paramètres qui précèdent sont exclusivement positionnels. Pour plus d'information, voir @ref{20fb,,l'entrée de la FAQ sur les arguments exclusivement positionnels}.


Modifié dans la version 3.5: The `follow_wrapped' parameter was added.
Pass @code{False} to get a signature of
`callable' specifically (@code{callable.__wrapped__} will not be used to
unwrap decorated callables.)



Modifié dans la version 3.10: The `globals', `locals', and `eval_str' parameters were added.


@cartouche
@quotation Note 
Certains appelables ne peuvent bénéficier d'introspection dans certains environnements Python. Par exemple, en CPython, certaines fonctions natives définies en C ne fournissent aucune métadonnée sur leurs arguments.
@end quotation
@end cartouche

`Particularité de l'implémentation CPython :' If the passed object has a @code{__signature__} attribute,
we may use it to create the signature.
The exact semantics are an implementation detail and are subject to
unannounced changes. Consult the source code for current semantics.
@end deffn

@geindex Signature (classe dans inspect)
@anchor{library/inspect inspect Signature}@anchor{1ca}
@deffn {Classe} inspect.Signature (parameters=None, *, return_annotation=Signature.empty)

A @code{Signature} object represents the call signature of a function
and its return
annotation.  For each parameter accepted by the function it stores a
@ref{1cb,,Parameter} object in its @ref{43ab,,parameters} collection.

L'argument optionnel `parameters' est une séquence d'objets @code{Parameters}, qui permet de vérifier qu'il n'y a pas de duplication de noms de paramètres, que les paramètres sont dans le bon ordre (positionnels d'abord, positionnels ou nommés ensuite et que les paramètres avec valeurs par défaut sont placés après ceux qui n'en ont pas).

The optional `return_annotation' argument can be an arbitrary Python object.
It represents the "return" annotation of the callable.

@code{Signature} objects are `immutable'.  Use @ref{43ac,,Signature.replace()} or
@ref{150,,copy.replace()} to make a modified copy.


Modifié dans la version 3.5: @code{Signature} objects are now picklable and @ref{5fb,,hashable}.


@geindex empty (attribut inspect.Signature)
@anchor{library/inspect inspect Signature empty}@anchor{43ad}
@deffn {Attribut} empty

Un marqueur spécial, accessible via @code{Signature.empty}, indiquant l'absence d'une annotation de type renvoyé.
@end deffn

@geindex parameters (attribut inspect.Signature)
@anchor{library/inspect inspect Signature parameters}@anchor{43ab}
@deffn {Attribut} parameters

Une table de correspondance ordonnée des noms de paramètres avec les objets @ref{1cb,,Parameter}. Les paramètres apparaissent dans l'ordre strict de leur définition, incluant les paramètres exclusivement nommés.


Modifié dans la version 3.7: Python ne garantit explicitement la préservation de l'ordre des paramètres exclusivement nommés que depuis la version 3.7, bien qu'en pratique cet ordre a toujours été préservé sous Python 3.

@end deffn

@geindex return_annotation (attribut inspect.Signature)
@anchor{library/inspect inspect Signature return_annotation}@anchor{43ae}
@deffn {Attribut} return_annotation

L'annotation du type renvoyé par l'appelable. Si l'appelable n'a pas d'annotation de type, cet attribut est évalué à @ref{43ad,,Signature.empty}.
@end deffn

@geindex bind() (méthode inspect.Signature)
@anchor{library/inspect inspect Signature bind}@anchor{15a2}
@deffn {Méthode} bind (*args, **kwargs)

Crée une table de correspondance entre les arguments positionnels et nommés avec les paramètres. Renvoie @ref{1052,,BoundArguments} si @code{*args} et @code{**kwargs} concordent avec la signature, autrement lève une @ref{522,,TypeError}.
@end deffn

@geindex bind_partial() (méthode inspect.Signature)
@anchor{library/inspect inspect Signature bind_partial}@anchor{43af}
@deffn {Méthode} bind_partial (*args, **kwargs)

Fonctionne de manière similaire à @ref{15a2,,Signature.bind()}, mais permet l'omission de certains arguments (semblable au comportement de @ref{40a,,functools.partial()}). Renvoie @ref{1052,,BoundArguments}, ou lève une @ref{522,,TypeError} si l'argument passé ne correspond pas à la signature.
@end deffn

@geindex replace() (méthode inspect.Signature)
@anchor{library/inspect inspect Signature replace}@anchor{43ac}
@deffn {Méthode} replace (*[, parameters][, return_annotation])

Create a new @ref{1ca,,Signature} instance based on the instance
@ref{43ac,,replace()} was invoked on.
It is possible to pass different `parameters' and/or
`return_annotation' to override the corresponding properties of the base
signature.  To remove @code{return_annotation} from the copied
@code{Signature}, pass in
@ref{43ad,,Signature.empty}.

@example
>>> def test(a, b):
...     pass
...
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"
@end example

@ref{1ca,,Signature} objects are also supported by the generic function
@ref{150,,copy.replace()}.
@end deffn

@geindex format() (méthode inspect.Signature)
@anchor{library/inspect inspect Signature format}@anchor{43b0}
@deffn {Méthode} format (*, max_width=None)

Create a string representation of the @ref{1ca,,Signature} object.

If `max_width' is passed, the method will attempt to fit
the signature into lines of at most `max_width' characters.
If the signature is longer than `max_width',
all parameters will be on separate lines.


Ajouté dans la version 3.13.

@end deffn

@geindex from_callable() (méthode de la classe inspect.Signature)
@anchor{library/inspect inspect Signature from_callable}@anchor{724}
@deffn {Méthode} classmethod from_callable (obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Return a @ref{1ca,,Signature} (or its subclass) object for a given callable
`obj'.

This method simplifies subclassing of @ref{1ca,,Signature}:

@example
class MySignature(Signature):
    pass
sig = MySignature.from_callable(sum)
assert isinstance(sig, MySignature)
@end example

Its behavior is otherwise identical to that of @ref{722,,signature()}.


Ajouté dans la version 3.5.



Modifié dans la version 3.10: The `globals', `locals', and `eval_str' parameters were added.

@end deffn
@end deffn

@geindex Parameter (classe dans inspect)
@anchor{library/inspect inspect Parameter}@anchor{1cb}
@deffn {Classe} inspect.Parameter (name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

@code{Parameter} objects are `immutable'.
Instead of modifying a @code{Parameter} object,
you can use @ref{43b1,,Parameter.replace()} or @ref{150,,copy.replace()} to create a modified copy.


Modifié dans la version 3.5: Parameter objects are now picklable and @ref{5fb,,hashable}.


@geindex empty (attribut inspect.Parameter)
@anchor{library/inspect inspect Parameter empty}@anchor{43b2}
@deffn {Attribut} empty

Un marqueur spécial, accessible via @code{Parameters.empty} indiquant l'absence de valeurs par défaut et d'annotations.
@end deffn

@geindex name (attribut inspect.Parameter)
@anchor{library/inspect inspect Parameter name}@anchor{43b3}
@deffn {Attribut} name

Le nom du paramètre (chaîne de caractères). Le nom doit être un identifiant Python valide.

`Particularité de l'implémentation CPython :' CPython génère un nom de paramètre implicite de forme @code{.0} sur les objets de code utilisés pour implémenter les compréhensions et expressions génératrices.


Modifié dans la version 3.6: These parameter names are now exposed by this module as names like
@code{implicit0}.

@end deffn

@geindex default (attribut inspect.Parameter)
@anchor{library/inspect inspect Parameter default}@anchor{43b4}
@deffn {Attribut} default

La valeur par défaut de ce paramètre. Si le paramètre n'a pas de valeur par défaut, cet attribut vaut @ref{43b2,,Parameter.empty}.
@end deffn

@geindex annotation (attribut inspect.Parameter)
@anchor{library/inspect inspect Parameter annotation}@anchor{43b5}
@deffn {Attribut} annotation

L'annotation du paramètre. Si le paramètre n'a pas d'annotation, cet attribut est défini à @ref{43b2,,Parameter.empty}.
@end deffn

@geindex kind (attribut inspect.Parameter)
@anchor{library/inspect inspect Parameter kind}@anchor{43b6}
@deffn {Attribut} kind

Describes how argument values are bound to the parameter.  The possible
values are accessible via @ref{1cb,,Parameter} (like @code{Parameter.KEYWORD_ONLY}),
and support comparison and ordering, in the following order:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Nom

@tab

Signification

@item

`POSITIONAL_ONLY'

@tab

La valeur doit être donnée comme argument positionnel. Les arguments exclusivement positionnels sont ceux qui apparaissent avant une entrée @code{/} (si présente) dans une définition de fonction Python.

@item

`POSITIONAL_OR_KEYWORD'

@tab

La valeur peut être donnée comme argument nommé ou positionnel (ce qui est l'affectation de variable standard pour les fonctions implémentées en Python).

@item

`VAR_POSITIONAL'

@tab

Un `n'-uplet d'arguments positionnels qui ne sont affectés à aucun autre paramètre. Cela correspond à un paramètre @code{*args} dans une définition de fonction Python.

@item

`KEYWORD_ONLY'

@tab

La valeur doit être donnée comme argument nommé. Les arguments exclusivement nommés sont ceux qui apparaissent après un @code{*} ou @code{*args} dans une définition de fonction Python.

@item

`VAR_KEYWORD'

@tab

Un dictionnaire d'arguments nommés qui ne sont liés à aucun autre paramètre. Cela correspond à une expression @code{**kwargs} dans une définition de fonction Python.

@end multitable


Example: print all keyword-only arguments without default values:

@example
>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c
@end example
@end deffn

@geindex description (attribut inspect.Parameter.kind)
@anchor{library/inspect inspect Parameter kind description}@anchor{43b7}
@deffn {Attribut} kind.description

Describes an enum value of @ref{43b6,,Parameter.kind}.


Ajouté dans la version 3.8.


Example: print all descriptions of arguments:

@example
>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only
@end example
@end deffn

@geindex replace() (méthode inspect.Parameter)
@anchor{library/inspect inspect Parameter replace}@anchor{43b1}
@deffn {Méthode} replace (*[, name][, kind][, default][, annotation])

Create a new @ref{1cb,,Parameter} instance based on the instance replaced was invoked
on.  To override a @code{Parameter} attribute, pass the corresponding
argument.  To remove a default value or/and an annotation from a
@code{Parameter}, pass @ref{43b2,,Parameter.empty}.

@example
>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo: 'spam'"
@end example

@ref{1cb,,Parameter} objects are also supported by the generic function
@ref{150,,copy.replace()}.
@end deffn


Modifié dans la version 3.4: In Python 3.3 @ref{1cb,,Parameter} objects were allowed to have @code{name} set
to @code{None} if their @code{kind} was set to @code{POSITIONAL_ONLY}.
This is no longer permitted.

@end deffn

@geindex BoundArguments (classe dans inspect)
@anchor{library/inspect inspect BoundArguments}@anchor{1052}
@deffn {Classe} inspect.BoundArguments

Le résultat d'un appel à @ref{15a2,,Signature.bind()} ou @ref{43af,,Signature.bind_partial()}. Contient la correspondance entre les arguments et les paramètres de la fonction.

@geindex arguments (attribut inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments arguments}@anchor{8f9}
@deffn {Attribut} arguments

Une correspondance mutable entre les noms de paramètres et les valeurs des arguments. Contient seulement les arguments liés explicitement. Les changements dans @ref{8f9,,arguments} sont reflétés dans @ref{43b8,,args} et @ref{43b9,,kwargs}.

Doit être utilisé en combinaison avec @ref{43ab,,Signature.parameters} pour le traitement d'arguments.

@cartouche
@quotation Note 
Les arguments pour lesquels @ref{15a2,,Signature.bind()} ou @ref{43af,,Signature.bind_partial()} supposent une valeur par défaut sont ignorés. Au besoin, utiliser @ref{e02,,BoundArguments.apply_defaults()} pour les inclure.
@end quotation
@end cartouche


Modifié dans la version 3.9: @ref{8f9,,arguments} est maintenant de type @ref{253,,dict}. Anciennement, il était de type @ref{5c5,,collections.OrderedDict}.

@end deffn

@geindex args (attribut inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments args}@anchor{43b8}
@deffn {Attribut} args

Un `n'-uplets des valeurs d'arguments positionnels. Évalué dynamiquement à partir de l'attribut @ref{8f9,,arguments}.
@end deffn

@geindex kwargs (attribut inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments kwargs}@anchor{43b9}
@deffn {Attribut} kwargs

A dict of keyword arguments values.  Dynamically computed from the
@ref{8f9,,arguments} attribute.  Arguments that can be passed positionally
are included in @ref{43b8,,args} instead.
@end deffn

@geindex signature (attribut inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments signature}@anchor{43ba}
@deffn {Attribut} signature

Une référence à l'objet @ref{1ca,,Signature} de la classe parente.
@end deffn

@geindex apply_defaults() (méthode inspect.BoundArguments)
@anchor{library/inspect inspect BoundArguments apply_defaults}@anchor{e02}
@deffn {Méthode} apply_defaults ()

Assigne les valeurs par défaut pour les arguments manquants.

Pour les arguments positionnels variables (@code{*args}) la valeur par défaut est un `n'-uplet vide.

Pour les arguments nommés variables (@code{**kwargs}) la valeur par défaut est un dictionnaire vide.

@example
>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
@{'a': 'spam', 'b': 'ham', 'args': ()@}
@end example


Ajouté dans la version 3.5.

@end deffn

The @ref{43b8,,args} and @ref{43b9,,kwargs} properties can be used to invoke
functions:

@example
def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)
@end example
@end deffn


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 362

@item PEP 362@footnote{https://peps.python.org/pep-0362/} — `Function Signature Object'.

La spécification détaillée, détails d'implémentation et exemples.
@end table


@node Classes et fonctions<2>,La pile d'interpréteur,Introspection des appelables avec l'objet Signature,inspect --- Inspect live objects
@anchor{library/inspect classes-and-functions}@anchor{43bb}@anchor{library/inspect inspect-classes-functions}@anchor{43bc}
@subsubsection Classes et fonctions


@geindex getclasstree() (dans le module inspect)
@anchor{library/inspect inspect getclasstree}@anchor{43bd}
@deffn {Fonction} inspect.getclasstree (classes, unique=False)

Organise la liste de classes donnée en une hiérarchie de listes imbriquées. Lorsqu'une liste imbriquée apparaît, elle contient les classes dérivées de la classe dont l'entrée précède immédiatement cette liste. Chaque entrée est une paire contenant la classe et un `n'-uplet de ses classes de base. Si l'argument `unique' est vrai, exactement une entrée apparaît dans la structure renvoyée pour chaque classe de la liste donnée en argument. Autrement, les classes utilisant l'héritage multiple et ses descendantes apparaissent plusieurs fois.
@end deffn

@geindex getfullargspec() (dans le module inspect)
@anchor{library/inspect inspect getfullargspec}@anchor{723}
@deffn {Fonction} inspect.getfullargspec (func)

Obtenir les noms et les valeurs par défaut des paramètres de fonction Python. Un @ref{639,,n-uplet nommé} est renvoyé :

@code{FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults,
annotations)}

`args' est une liste de noms de paramètres positionnels. `varargs' est le nom du paramètre @code{*} ou @code{None} si les arguments positionnels arbitraires ne sont pas acceptés. `varkw' est le nom du paramètre @code{**}, ou @code{None} si les paramètres arbitraires nommés ne sont pas acceptés. `defaults' est un `n'-uplet des valeurs des arguments par défaut correspondant aux derniers `n' arguments positionnels, ou @code{None} si aucun défaut n'est défini. `kwonlyargs' est une liste d'arguments exclusivement nommés, ordonnée selon l'ordre de déclaration. `kwonlydefaults' est un dictionnaire de correspondance entre les noms de paramètres de `kwonlyargs' et les valeurs par défaut utilisées si aucun argument n'est donné. `annotations' est un dictionnaire de correspondance entre les noms de paramètres et les annotations. La clef spéciale @code{"return"} est utilisée pour obtenir la valeur de retour de l'annotation la fonction (si elle existe).

Notez que @ref{722,,signature()} et @ref{43a9,,Signature Object} fournissent l'API recommandé pour l’introspection d'appelables et prennent en charge des comportements additionnels (comme les arguments exclusivement positionnels) qui sont parfois rencontrés dans les APIs des modules d'extension. Cette fonction et maintenue principalement pour maintenir la compatibilité avec l'API du module @code{inspect} de Python 2.


Modifié dans la version 3.4: cette fonction est maintenant basée sur @ref{722,,signature()}, mais ignore toujours les attributs @code{_wrapped_} et inclue le premier paramètre (déjà lié) dans la signature des méthodes liées.



Modifié dans la version 3.6: cette méthode fût précédemment documentée comme dépréciée en faveur de @ref{722,,signature()} en Python 3.5, mais cette décision fût renversée afin de ré-introduire une interface standard clairement supportée pour du code unifié Python 2/3 migrant pour se départir de l'API @code{getargspec()}.



Modifié dans la version 3.7: Python ne garantit explicitement la préservation de l'ordre des paramètres exclusivement nommés que depuis la version 3.7, bien qu'en pratique cet ordre a toujours été préservé sous Python 3.

@end deffn

@geindex getargvalues() (dans le module inspect)
@anchor{library/inspect inspect getargvalues}@anchor{ea7}
@deffn {Fonction} inspect.getargvalues (frame)

Obtenir de l'information sur les arguments passés à un cadre particulier. Un @ref{639,,n-uplet nommé} @code{ArgInfo(args, varargs, keywords, locals)} est renvoyé. `args' est une liste de noms d'arguments. `varags' et `keywords' sont les noms des arguments @code{*} et @code{**} ou @code{None}. `locals' est le dictionnaire des variables locales du cadre courant.

@cartouche
@quotation Note 
Cette fonction fût dépréciée par inadvertance en Python 3.5.
@end quotation
@end cartouche
@end deffn

@geindex formatargvalues() (dans le module inspect)
@anchor{library/inspect inspect formatargvalues}@anchor{ea8}
@deffn {Fonction} inspect.formatargvalues (args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Formatage lisible des quatre valeurs renvoyées par @ref{ea7,,getargvalues()}. Les arguments format* sont des fonctions de formatage optionnelles qui sont appelées pour convertir les noms et valeurs en chaînes de caractères.

@cartouche
@quotation Note 
Cette fonction fût dépréciée par inadvertance en Python 3.5.
@end quotation
@end cartouche
@end deffn

@geindex getmro() (dans le module inspect)
@anchor{library/inspect inspect getmro}@anchor{43be}
@deffn {Fonction} inspect.getmro (cls)

Renvoie un `n'-uplet des classes de base de `cls', incluant `cls', selon le l'ordre de résolution des méthodes (`method resolution order'). Aucune classe n'apparaît plus d'une fois dans ce `n'-uplet. Notez que le l'ordre de résolution des méthodes dépend du type de `cls'. Exception faite d'une utilisation très particulière de la métaclasse définie par l'usager, `cls' sera toujours le premier élément du tuple.
@end deffn

@geindex getcallargs() (dans le module inspect)
@anchor{library/inspect inspect getcallargs}@anchor{ea6}
@deffn {Fonction} inspect.getcallargs (func, /, *args, **kwds)

Bind the `args' and `kwds' to the argument names of the Python function or
method `func', as if it was called with them. For bound methods, bind also the
first argument (typically named @code{self}) to the associated instance. A dict
is returned, mapping the argument names (including the names of the @code{*} and
@code{**} arguments, if any) to their values from `args' and `kwds'. In case of
invoking `func' incorrectly, i.e. whenever @code{func(*args, **kwds)} would raise
an exception because of incompatible signature, an exception of the same type
and the same or similar message is raised. For example:

@example
>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
...
>>> getcallargs(f, 1, 2, 3) == @{'a': 1, 'named': @{@}, 'b': 2, 'pos': (3,)@}
True
>>> getcallargs(f, a=2, x=4) == @{'a': 2, 'named': @{'x': 4@}, 'b': 1, 'pos': ()@}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'
@end example


Ajouté dans la version 3.2.



Obsolète depuis la version 3.5: utilisez plutôt @ref{15a2,,Signature.bind()} et @ref{43af,,Signature.bind_partial()}.

@end deffn

@geindex getclosurevars() (dans le module inspect)
@anchor{library/inspect inspect getclosurevars}@anchor{10b7}
@deffn {Fonction} inspect.getclosurevars (func)

Obtenir la correspondance de nom de références externes d'une fonction ou méthode Python `func' avec leur valeur courante. Un @ref{639,,n-uplet nommé} @code{ClosureVars(nonlocals, globals, builtins, unbound)} est renvoyé. `nonlocals' établit une correspondance des noms capturés par les fermetures lexicales, `globals' au module de la fonction et `builtins' aux noms natifs visibles depuis le corps de la fonction. `unbound' est un ensemble de noms référencés dans la fonction ne trouvant aucune résolution dans les valeurs globales du module courant ni à travers le lexique natif.

@ref{522,,TypeError} est levée si `func' n'est ni une fonction ni une méthode Python.


Ajouté dans la version 3.3.

@end deffn

@geindex unwrap() (dans le module inspect)
@anchor{library/inspect inspect unwrap}@anchor{f47}
@deffn {Fonction} inspect.unwrap (func, *, stop=None)

Obtenir l'objet englobé par `func'. Suit une chaîne d'attributs de @code{__wrapped__}, renvoyant le dernier objet de la chaîne.

`stop' est une fonction de `callback' optionnelle qui accepte un objet de la chaîne englobée comme son seul argument et permet d'arrêter le déballage avant la fin si la fonction de `callback' renvoie une valeur vraie. Si la fonction `callback' ne renvoie jamais une valeur vraie, le dernier objet de la chaîne est renvoyé comme d'habitude. Par exemple, @ref{722,,signature()} utilise ceci pour arrêter le déballage si un objet dans la chaîne définit un attribut @code{__signature__}.

@ref{1ff,,ValueError} est levée si un cycle est rencontré.


Ajouté dans la version 3.4.

@end deffn

@geindex get_annotations() (dans le module inspect)
@anchor{library/inspect inspect get_annotations}@anchor{7fd}
@deffn {Fonction} inspect.get_annotations (obj, *, globals=None, locals=None, eval_str=False)

Compute the annotations dict for an object.

@code{obj} may be a callable, class, or module.
Passing in an object of any other type raises @ref{522,,TypeError}.

Returns a dict.  @code{get_annotations()} returns a new dict every time
it's called; calling it twice on the same object will return two
different but equivalent dicts.

This function handles several details for you:


@itemize *

@item 
If @code{eval_str} is true, values of type @code{str} will
be un-stringized using @ref{17e,,eval()}.  This is intended
for use with stringized annotations
(@code{from __future__ import annotations}).

@item 
If @code{obj} doesn't have an annotations dict, returns an
empty dict.  (Functions and methods always have an
annotations dict; classes, modules, and other types of
callables may not.)

@item 
Ignores inherited annotations on classes.  If a class
doesn't have its own annotations dict, returns an empty dict.

@item 
All accesses to object members and dict values are done
using @code{getattr()} and @code{dict.get()} for safety.

@item 
Always, always, always returns a freshly created dict.
@end itemize

@code{eval_str} controls whether or not values of type @code{str} are replaced
with the result of calling @ref{17e,,eval()} on those values:


@itemize *

@item 
If eval_str is true, @ref{17e,,eval()} is called on values of type @code{str}.
(Note that @code{get_annotations} doesn't catch exceptions; if @ref{17e,,eval()}
raises an exception, it will unwind the stack past the @code{get_annotations}
call.)

@item 
If eval_str is false (the default), values of type @code{str} are unchanged.
@end itemize

@code{globals} and @code{locals} are passed in to @ref{17e,,eval()}; see the documentation
for @ref{17e,,eval()} for more information.  If @code{globals} or @code{locals}
is @code{None}, this function may replace that value with a context-specific
default, contingent on @code{type(obj)}:


@itemize *

@item 
If @code{obj} is a module, @code{globals} defaults to @code{obj.__dict__}.

@item 
If @code{obj} is a class, @code{globals} defaults to
@code{sys.modules[obj.__module__].__dict__} and @code{locals} defaults
to the @code{obj} class namespace.

@item 
If @code{obj} is a callable, @code{globals} defaults to
@ref{12b1,,obj.__globals__},
although if @code{obj} is a wrapped function (using
@ref{100b,,functools.update_wrapper()}) it is first unwrapped.
@end itemize

Calling @code{get_annotations} is best practice for accessing the
annotations dict of any object.  See @ref{7c3,,Bonnes pratiques concernant les annotations} for
more information on annotations best practices.


Ajouté dans la version 3.10.

@end deffn

@node La pile d'interpréteur,Recherche dynamique d'attributs,Classes et fonctions<2>,inspect --- Inspect live objects
@anchor{library/inspect inspect-stack}@anchor{43bf}@anchor{library/inspect the-interpreter-stack}@anchor{43c0}
@subsubsection La pile d'interpréteur


Some of the following functions return
@ref{637,,FrameInfo} objects. For backwards compatibility these objects allow
tuple-like operations on all attributes except @code{positions}. This behavior
is considered deprecated and may be removed in the future.

@geindex FrameInfo (classe dans inspect)
@anchor{library/inspect inspect FrameInfo}@anchor{637}
@deffn {Classe} inspect.FrameInfo

@geindex frame (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo frame}@anchor{43c1}
@deffn {Attribut} frame

The @ref{6ca,,frame object} that the record corresponds to.
@end deffn

@geindex filename (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo filename}@anchor{43c2}
@deffn {Attribut} filename

The file name associated with the code being executed by the frame this record
corresponds to.
@end deffn

@geindex lineno (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo lineno}@anchor{43c3}
@deffn {Attribut} lineno

The line number of the current line associated with the code being
executed by the frame this record corresponds to.
@end deffn

@geindex function (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo function}@anchor{43c4}
@deffn {Attribut} function

The function name that is being executed by the frame this record corresponds to.
@end deffn

@geindex code_context (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo code_context}@anchor{43c5}
@deffn {Attribut} code_context

A list of lines of context from the source code that's being executed by the frame
this record corresponds to.
@end deffn

@geindex index (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo index}@anchor{43c6}
@deffn {Attribut} index

The index of the current line being executed in the @ref{43c5,,code_context} list.
@end deffn

@geindex positions (attribut inspect.FrameInfo)
@anchor{library/inspect inspect FrameInfo positions}@anchor{43c7}
@deffn {Attribut} positions

A @ref{43c8,,dis.Positions} object containing the start line number, end line
number, start column offset, and end column offset associated with the
instruction being executed by the frame this record corresponds to.
@end deffn


Modifié dans la version 3.5: Return a @ref{639,,named tuple} instead of a @ref{366,,tuple}.



Modifié dans la version 3.11: @code{FrameInfo} is now a class instance
(that is backwards compatible with the previous @ref{639,,named tuple}).

@end deffn

@geindex Traceback (classe dans inspect)
@anchor{library/inspect inspect Traceback}@anchor{638}
@deffn {Classe} inspect.Traceback

@geindex filename (attribut inspect.Traceback)
@anchor{library/inspect inspect Traceback filename}@anchor{43c9}
@deffn {Attribut} filename

The file name associated with the code being executed by the frame this traceback
corresponds to.
@end deffn

@geindex lineno (attribut inspect.Traceback)
@anchor{library/inspect inspect Traceback lineno}@anchor{43ca}
@deffn {Attribut} lineno

The line number of the current line associated with the code being
executed by the frame this traceback corresponds to.
@end deffn

@geindex function (attribut inspect.Traceback)
@anchor{library/inspect inspect Traceback function}@anchor{43cb}
@deffn {Attribut} function

The function name that is being executed by the frame this traceback corresponds to.
@end deffn

@geindex code_context (attribut inspect.Traceback)
@anchor{library/inspect inspect Traceback code_context}@anchor{43cc}
@deffn {Attribut} code_context

A list of lines of context from the source code that's being executed by the frame
this traceback corresponds to.
@end deffn

@geindex index (attribut inspect.Traceback)
@anchor{library/inspect inspect Traceback index}@anchor{43cd}
@deffn {Attribut} index

The index of the current line being executed in the @ref{43cc,,code_context} list.
@end deffn

@geindex positions (attribut inspect.Traceback)
@anchor{library/inspect inspect Traceback positions}@anchor{43ce}
@deffn {Attribut} positions

A @ref{43c8,,dis.Positions} object containing the start line number, end
line number, start column offset, and end column offset associated with
the instruction being executed by the frame this traceback corresponds
to.
@end deffn


Modifié dans la version 3.11: @code{Traceback} is now a class instance
(that is backwards compatible with the previous @ref{639,,named tuple}).

@end deffn

@cartouche
@quotation Note 
Conserver des références à des objets cadre, tel que trouvé dans le 1er élément des enregistrements de cadres que ces fonctions renvoient, peut créer des cycles de référence dans votre programme. Lorsqu'un cycle de référence a été créé, la durée de vie de tous les objets pouvant être accessibles par ces objets peut être grandement augmentée, même si le détecteur de cycle (optionnel) de Python est activé. Si ces cycles doivent être créés, il est important de s'assurer qu'ils soient explicitement brisés pour éviter la destruction reportée des objets et l'augmentation résultante de l'utilisation de la mémoire.

Bien que le détecteur trouvera ces cycles, la destruction des cadres (et variables locales) peut être fait de manière déterministe en enlevant les cycles dans une clause @ref{9b8,,finally}. Cela est important si le détecteur de cycle a été désactivé lors de la compilation du code Python ou en utilisant @ref{4389,,gc.disable()}. Par exemple :

@example
def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame
@end example

Pour conserver ces cadres (par exemple pour imprimer une trace d'exécution plus tard), vous pouvez briser ces cycles de référence en utilisant la méthode @ref{27d,,frame.clear()}.
@end quotation
@end cartouche

L'argument optionnel `context' supporté par la plupart de ces méthodes spécifie le nombre de lignes de contexte à renvoyer, qui sera centré autour de la ligne courante.

@geindex getframeinfo() (dans le module inspect)
@anchor{library/inspect inspect getframeinfo}@anchor{63a}
@deffn {Fonction} inspect.getframeinfo (frame, context=1)

Get information about a frame or traceback object.  A @ref{638,,Traceback} object
is returned.


Modifié dans la version 3.11: A @ref{638,,Traceback} object is returned instead of a named tuple.

@end deffn

@geindex getouterframes() (dans le module inspect)
@anchor{library/inspect inspect getouterframes}@anchor{63b}
@deffn {Fonction} inspect.getouterframes (frame, context=1)

Get a list of @ref{637,,FrameInfo} objects for a frame and all outer frames.
These frames represent the calls that lead to the creation of `frame'. The
first entry in the returned list represents `frame'; the last entry
represents the outermost call on `frame''s stack.


Modifié dans la version 3.5: une liste de @ref{639,,n-uplet nommé} @code{FrameInfo(frame, filename, lineno, function, code_context, index)} est renvoyée.



Modifié dans la version 3.11: A list of @ref{637,,FrameInfo} objects is returned.

@end deffn

@geindex getinnerframes() (dans le module inspect)
@anchor{library/inspect inspect getinnerframes}@anchor{63c}
@deffn {Fonction} inspect.getinnerframes (traceback, context=1)

Get a list of @ref{637,,FrameInfo} objects for a traceback's frame and all
inner frames.  These frames represent calls made as a consequence of `frame'.
The first entry in the list represents `traceback'; the last entry represents
where the exception was raised.


Modifié dans la version 3.5: une liste de @ref{639,,n-uplet nommé} @code{FrameInfo(frame, filename, lineno, function, code_context, index)} est renvoyée.



Modifié dans la version 3.11: A list of @ref{637,,FrameInfo} objects is returned.

@end deffn

@geindex currentframe() (dans le module inspect)
@anchor{library/inspect inspect currentframe}@anchor{6cc}
@deffn {Fonction} inspect.currentframe ()

Renvoie l'objet cadre de la pile pour le cadre de l’appelant.

`Particularité de l'implémentation CPython :' cette fonction nécessite que l'interpréteur Python implémente une pile de cadres d'appel, ce qui n'est pas forcément le cas de toutes les implémentations Python. Si le code s'exécute dans une implémentation Python n'implémentant pas la pile de cadres, cette fonction renvoie @code{None}.
@end deffn

@geindex stack() (dans le module inspect)
@anchor{library/inspect inspect stack}@anchor{63d}
@deffn {Fonction} inspect.stack (context=1)

Return a list of @ref{637,,FrameInfo} objects for the caller's stack.  The
first entry in the returned list represents the caller; the last entry
represents the outermost call on the stack.


Modifié dans la version 3.5: une liste de @ref{639,,n-uplet nommé} @code{FrameInfo(frame, filename, lineno, function, code_context, index)} est renvoyée.



Modifié dans la version 3.11: A list of @ref{637,,FrameInfo} objects is returned.

@end deffn

@geindex trace() (dans le module inspect)
@anchor{library/inspect inspect trace}@anchor{63e}
@deffn {Fonction} inspect.trace (context=1)

Return a list of @ref{637,,FrameInfo} objects for the stack between the current
frame and the frame in which an exception currently being handled was raised
in.  The first entry in the list represents the caller; the last entry
represents where the exception was raised.


Modifié dans la version 3.5: une liste de @ref{639,,n-uplet nommé} @code{FrameInfo(frame, filename, lineno, function, code_context, index)} est renvoyée.



Modifié dans la version 3.11: A list of @ref{637,,FrameInfo} objects is returned.

@end deffn

@node Recherche dynamique d'attributs,Current State of Generators Coroutines and Asynchronous Generators,La pile d'interpréteur,inspect --- Inspect live objects
@anchor{library/inspect fetching-attributes-statically}@anchor{43cf}
@subsubsection Recherche dynamique d'attributs


Both @ref{bbf,,getattr()} and @ref{4bb,,hasattr()} can trigger code execution when
fetching or checking for the existence of attributes. Descriptors, like
properties, will be invoked and @ref{4bc,,__getattr__()} and
@ref{bc0,,__getattribute__()}
may be called.

Pour les cas où une introspection passive est désirée, comme des outils de documentation, cela peut être inconvenable. @ref{47e,,getattr_static()} possède la même signature que @ref{bbf,,getattr()}, mais évite l'exécution de code lors de la recherche d'attributs.

@geindex getattr_static() (dans le module inspect)
@anchor{library/inspect inspect getattr_static}@anchor{47e}
@deffn {Fonction} inspect.getattr_static (obj, attr, default=None)

Retrieve attributes without triggering dynamic lookup via the
descriptor protocol, @ref{4bc,,__getattr__()}
or @ref{bc0,,__getattribute__()}.

Note : cette fonction ne retrouve pas forcément tous les attributs renvoyés par `getattr' (tel que des attributs générés dynamiquement) et pourrait retrouver des attributs non retrouvés par `getattr' (tel que des descripteurs qui lèvent un `AttributeError'). Elle peut aussi donner des objets descripteurs, plutôt que des membres d'instance.

Si l'instance @ref{546,,__dict__} est cachée (`shadowed') par un autre membre (par exemple une propriété), cette fonction ne pourra pas retrouver les membres de l'instance.


Ajouté dans la version 3.2.

@end deffn

@ref{47e,,getattr_static()} ne résout pas les descripteurs, par exemple `slot descriptors' ou les descripteurs `getset' des objets implémentés en C. Le descripteur de l'objet est renvoyé plutôt que l'attribut sous-jacent.

Vous pouvez gérer ces cas à l'aide du code suivant. Notez que pour des descripteurs arbitraires `getset' les invoquant, de l'exécution de code pourrait être lancée :

@example
# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass
@end example

@node Current State of Generators Coroutines and Asynchronous Generators,Bit d'option des objets code,Recherche dynamique d'attributs,inspect --- Inspect live objects
@anchor{library/inspect current-state-of-generators-coroutines-and-asynchronous-generators}@anchor{43d0}
@subsubsection Current State of Generators, Coroutines, and Asynchronous Generators


Lors de l'implémentation d'ordonnanceur de coroutine et autres utilisations avancées de générateurs, il est utile de déterminer si un générateur est présentement en cours d'exécution, en attente de démarrage ou de continuation, ou s'il a déjà terminé. @ref{1214,,getgeneratorstate()} permet d'aisément déterminer l'état courant d'un générateur.

@geindex getgeneratorstate() (dans le module inspect)
@anchor{library/inspect inspect getgeneratorstate}@anchor{1214}
@deffn {Fonction} inspect.getgeneratorstate (generator)

Donne l'état courant d'un générateur-itérateur.

Les états possibles :


@itemize *

@item 
GEN_CREATED : En attente de démarrage d'exécution.

@item 
GEN_RUNNING : En cours d'exécution par l'interpréteur.

@item 
GEN_SUSPENDED : Présentement suspendu à une expression `yield'.

@item 
GEN_CLOSED : L'exécution est complétée.
@end itemize


Ajouté dans la version 3.2.

@end deffn

@geindex getcoroutinestate() (dans le module inspect)
@anchor{library/inspect inspect getcoroutinestate}@anchor{e06}
@deffn {Fonction} inspect.getcoroutinestate (coroutine)

Donne l'état courant d'un objet coroutine. L'utilisation est prévue avec des objets coroutine créés avec des fonctions @ref{5bb,,async def}, mais accepte n'importe quel objet semblable à une coroutine qui définisse des attributs @code{cr_running} @code{cr_frame}.

Les états possibles :


@itemize *

@item 
CORO_CREATED : En attente de démarrage d'exécution.

@item 
CORO_RUNNING : En cours d'exécution par l'interpréteur.

@item 
CORO_SUSPENDED : Suspendu à une expression `await'.

@item 
CORO_CLOSED : Exécution complétée.
@end itemize


Ajouté dans la version 3.5.

@end deffn

@geindex getasyncgenstate() (dans le module inspect)
@anchor{library/inspect inspect getasyncgenstate}@anchor{47c}
@deffn {Fonction} inspect.getasyncgenstate (agen)

Get current state of an asynchronous generator object.  The function is
intended to be used with asynchronous iterator objects created by
@ref{5bb,,async def} functions which use the @ref{9bb,,yield} statement,
but will accept any asynchronous generator-like object that has
@code{ag_running} and @code{ag_frame} attributes.

Les états possibles :


@itemize *

@item 
AGEN_CREATED: Waiting to start execution.

@item 
AGEN_RUNNING: Currently being executed by the interpreter.

@item 
AGEN_SUSPENDED: Currently suspended at a yield expression.

@item 
AGEN_CLOSED: Execution has completed.
@end itemize


Ajouté dans la version 3.12.

@end deffn

L'état courant interne du générateur peut aussi être vérifié. Ceci est utile pour des tests, afin d'assurer que l'état interne est mise à jour tel que prévu :

@geindex getgeneratorlocals() (dans le module inspect)
@anchor{library/inspect inspect getgeneratorlocals}@anchor{10b8}
@deffn {Fonction} inspect.getgeneratorlocals (generator)

Donne une correspondance de variables locales dans `generator' avec les valeurs courantes. Un dictionnaire est renvoyé, établissant la correspondance entre variables et valeurs. Ceci est équivalent à appeler @ref{140,,locals()} dans le corps du générateur et les mêmes restrictions s'appliquent.

Si `generator' est un @ref{104a,,générateur} sans cadre courant associé, alors un dictionnaire vide est renvoyé. @ref{522,,TypeError} est levé sir `generator' n'est pas un objet générateur Python.

`Particularité de l'implémentation CPython :' Cette fonction repose sur l'exposition d'une pile de cadres Python par le générateur pour l'introspection, ce qui n'est pas garanti dans toutes les implémentations Python. Dans un tel cas, cette fonction renvoie toujours un dictionnaire vide.


Ajouté dans la version 3.3.

@end deffn

@geindex getcoroutinelocals() (dans le module inspect)
@anchor{library/inspect inspect getcoroutinelocals}@anchor{e05}
@deffn {Fonction} inspect.getcoroutinelocals (coroutine)

Cette fonction est semblable à @ref{10b8,,getgeneratorlocals()}, mais fonctionne pour des objets coroutines créés avec des fonctions @ref{5bb,,async def}.


Ajouté dans la version 3.5.

@end deffn

@geindex getasyncgenlocals() (dans le module inspect)
@anchor{library/inspect inspect getasyncgenlocals}@anchor{47d}
@deffn {Fonction} inspect.getasyncgenlocals (agen)

This function is analogous to @ref{10b8,,getgeneratorlocals()}, but
works for asynchronous generator objects created by @ref{5bb,,async def}
functions which use the @ref{9bb,,yield} statement.


Ajouté dans la version 3.12.

@end deffn

@node Bit d'option des objets code,Buffer flags,Current State of Generators Coroutines and Asynchronous Generators,inspect --- Inspect live objects
@anchor{library/inspect code-objects-bit-flags}@anchor{43d1}@anchor{library/inspect inspect-module-co-flags}@anchor{1ecb}
@subsubsection Bit d'option des objets code


Python code objects have a @ref{1eca,,co_flags} attribute,
which is a bitmap of the following flags:

@geindex CO_OPTIMIZED (dans le module inspect)
@anchor{library/inspect inspect CO_OPTIMIZED}@anchor{43d2}
@deffn {Données} inspect.CO_OPTIMIZED

L'objet code est optimisé, utilisant des variables locales rapides.
@end deffn

@geindex CO_NEWLOCALS (dans le module inspect)
@anchor{library/inspect inspect CO_NEWLOCALS}@anchor{43d3}
@deffn {Données} inspect.CO_NEWLOCALS

If set, a new dict will be created for the frame's @ref{180,,f_locals}
when the code object is executed.
@end deffn

@geindex CO_VARARGS (dans le module inspect)
@anchor{library/inspect inspect CO_VARARGS}@anchor{43d4}
@deffn {Données} inspect.CO_VARARGS

L'objet code possède un paramètre de variable positionnel (@code{*args} ou semblable).
@end deffn

@geindex CO_VARKEYWORDS (dans le module inspect)
@anchor{library/inspect inspect CO_VARKEYWORDS}@anchor{43d5}
@deffn {Données} inspect.CO_VARKEYWORDS

L'objet code possède une paramètre par mot-clé variable (@code{**kwargs} ou semblable).
@end deffn

@geindex CO_NESTED (dans le module inspect)
@anchor{library/inspect inspect CO_NESTED}@anchor{43d6}
@deffn {Données} inspect.CO_NESTED

L'option est définie lorsque le code est une fonction imbriquée.
@end deffn

@geindex CO_GENERATOR (dans le module inspect)
@anchor{library/inspect inspect CO_GENERATOR}@anchor{43d7}
@deffn {Données} inspect.CO_GENERATOR

L'option est définie lorsque l'objet code est une fonction génératrice, c'est-à-dire qu'un objet générateur est renvoyé lorsque le code objet est exécuté.
@end deffn

@geindex CO_COROUTINE (dans le module inspect)
@anchor{library/inspect inspect CO_COROUTINE}@anchor{43d8}
@deffn {Données} inspect.CO_COROUTINE

L'option est définie lorsque le code objet est une fonction coroutine. Lors que le code objet est exécuté, il renvoie un objet coroutine. Voir 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} pour plus de détails.


Ajouté dans la version 3.5.

@end deffn

@geindex CO_ITERABLE_COROUTINE (dans le module inspect)
@anchor{library/inspect inspect CO_ITERABLE_COROUTINE}@anchor{43d9}
@deffn {Données} inspect.CO_ITERABLE_COROUTINE

L'option est utilisée pour transformer un générateur en une coroutine basée sur un générateur. Les objets générateurs avec cette option peuvent être utilisés dans une expression @code{await} et un objet coroutine @code{yield from}. Voir 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} pour plus de détails.


Ajouté dans la version 3.5.

@end deffn

@geindex CO_ASYNC_GENERATOR (dans le module inspect)
@anchor{library/inspect inspect CO_ASYNC_GENERATOR}@anchor{43da}
@deffn {Données} inspect.CO_ASYNC_GENERATOR

L'option est définie lorsque l'objet code est une fonction génératrice asynchrone. Lorsque l'objet code est exécuté, il renvoie un objet générateur asynchrone. Voir 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/} pour les détails.


Ajouté dans la version 3.6.

@end deffn

@cartouche
@quotation Note 
Ces options sont spécifiques à CPython et pourraient ne pas être définies dans d'autres implémentations Python. De plus, les options constituent des détails d'implémentation et pourraient être enlevées ou dépréciées dans des versions ultérieures. Il est recommandé d'utiliser les APIs publiques de @ref{7d,,inspect} pour tous les besoins d'introspection.
@end quotation
@end cartouche

@node Buffer flags,Interface en ligne de commande<9>,Bit d'option des objets code,inspect --- Inspect live objects
@anchor{library/inspect buffer-flags}@anchor{43db}
@subsubsection Buffer flags


@geindex BufferFlags (classe dans inspect)
@anchor{library/inspect inspect BufferFlags}@anchor{449}
@deffn {Classe} inspect.BufferFlags

This is an @ref{2280,,enum.IntFlag} that represents the flags that
can be passed to the @ref{448,,__buffer__()} method of objects
implementing the @ref{38e,,buffer protocol}.

The meaning of the flags is explained at @ref{43dc,,Buffer request types}.

@geindex SIMPLE (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags SIMPLE}@anchor{43dd}
@deffn {Attribut} SIMPLE
@end deffn

@geindex WRITABLE (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags WRITABLE}@anchor{43de}
@deffn {Attribut} WRITABLE
@end deffn

@geindex FORMAT (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags FORMAT}@anchor{43df}
@deffn {Attribut} FORMAT
@end deffn

@geindex ND (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags ND}@anchor{43e0}
@deffn {Attribut} ND
@end deffn

@geindex STRIDES (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags STRIDES}@anchor{43e1}
@deffn {Attribut} STRIDES
@end deffn

@geindex C_CONTIGUOUS (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags C_CONTIGUOUS}@anchor{43e2}
@deffn {Attribut} C_CONTIGUOUS
@end deffn

@geindex F_CONTIGUOUS (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags F_CONTIGUOUS}@anchor{43e3}
@deffn {Attribut} F_CONTIGUOUS
@end deffn

@geindex ANY_CONTIGUOUS (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags ANY_CONTIGUOUS}@anchor{43e4}
@deffn {Attribut} ANY_CONTIGUOUS
@end deffn

@geindex INDIRECT (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags INDIRECT}@anchor{43e5}
@deffn {Attribut} INDIRECT
@end deffn

@geindex CONTIG (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags CONTIG}@anchor{43e6}
@deffn {Attribut} CONTIG
@end deffn

@geindex CONTIG_RO (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags CONTIG_RO}@anchor{43e7}
@deffn {Attribut} CONTIG_RO
@end deffn

@geindex STRIDED (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags STRIDED}@anchor{43e8}
@deffn {Attribut} STRIDED
@end deffn

@geindex STRIDED_RO (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags STRIDED_RO}@anchor{43e9}
@deffn {Attribut} STRIDED_RO
@end deffn

@geindex RECORDS (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags RECORDS}@anchor{43ea}
@deffn {Attribut} RECORDS
@end deffn

@geindex RECORDS_RO (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags RECORDS_RO}@anchor{43eb}
@deffn {Attribut} RECORDS_RO
@end deffn

@geindex FULL (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags FULL}@anchor{43ec}
@deffn {Attribut} FULL
@end deffn

@geindex FULL_RO (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags FULL_RO}@anchor{43ed}
@deffn {Attribut} FULL_RO
@end deffn

@geindex READ (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags READ}@anchor{153d}
@deffn {Attribut} READ
@end deffn

@geindex WRITE (attribut inspect.BufferFlags)
@anchor{library/inspect inspect BufferFlags WRITE}@anchor{153e}
@deffn {Attribut} WRITE
@end deffn


Ajouté dans la version 3.12.

@end deffn

@node Interface en ligne de commande<9>,,Buffer flags,inspect --- Inspect live objects
@anchor{library/inspect command-line-interface}@anchor{43ee}@anchor{library/inspect inspect-module-cli}@anchor{f46}
@subsubsection Interface en ligne de commande


Le module @ref{7d,,inspect} fournit également des capacités d'introspection de base en ligne de commande.

Par défaut, il accepte le nom d'un module et affiche la source de ce module. Une classe ou fonction à l'intérieur du module peut également être affichée en ajoutant un ":" et le nom qualifié de l'objet désiré.

@geindex option de ligne de commande inspect; --details
@anchor{library/inspect cmdoption-inspect-details}@anchor{43ef}
@deffn {Option} @w{-}@w{-}details

Affiche de l'information à propos de l'objet spécifié plutôt que du code source.
@end deffn

@node site --- Site-specific configuration hook,,inspect --- Inspect live objects,Environnement d'exécution Python
@anchor{library/site doc}@anchor{43f0}@anchor{library/site module-site}@anchor{c6}@anchor{library/site site-site-specific-configuration-hook}@anchor{43f1}
@subsection @code{site} --- Site-specific configuration hook


@geindex module; site

`Code source :' Lib/site.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/site.py}


__________________________________________________________________


`This module is automatically imported during initialization.' The automatic
import can be suppressed using the interpreter's @ref{1186,,-S} option.

@geindex module;search;path

Importing this module normally appends site-specific paths to the module search path
and adds @ref{2110,,callables}, including @ref{8c4,,help()} to the built-in
namespace. However, Python startup option @ref{1186,,-S} blocks this and this module
can be safely imported with no automatic modifications to the module search path
or additions to the builtins.  To explicitly trigger the usual site-specific
additions, call the @ref{1cc2,,main()} function.


Modifié dans la version 3.3: Importing the module used to trigger paths manipulation even when using
@ref{1186,,-S}.


@geindex site-packages;directory

It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses @code{sys.prefix} and @code{sys.exec_prefix}; empty heads
are skipped.  For the tail part, it uses the empty string and then
@code{lib/site-packages} (on Windows) or
@code{lib/python`X.Y[t]'/site-packages} (on Unix and macOS). (The
optional suffix "t" indicates the @ref{150c,,free threading} build, and is
appended if @code{"t"} is present in the @ref{a52,,sys.abiflags} constant.)
For each
of the distinct head-tail combinations, it sees if it refers to an existing
directory, and if so, adds it to @code{sys.path} and also inspects the newly
added path for configuration files.


Modifié dans la version 3.5: Support for the "site-python" directory has been removed.



Modifié dans la version 3.13: On Unix, @ref{150c,,Free threading} Python installations are
identified by the "t" suffix in the version-specific directory name, such as
@code{lib/python3.13t/}.


If a file named "pyvenv.cfg" exists one directory above sys.executable,
sys.prefix and sys.exec_prefix are set to that directory and
it is also checked for site-packages (sys.base_prefix and
sys.base_exec_prefix will always be the "real" prefixes of the Python
installation). If "pyvenv.cfg" (a bootstrap configuration file) contains
the key "include-system-site-packages" set to anything other than "true"
(case-insensitive), the system-level prefixes will not be
searched for site-packages; otherwise they will.

@geindex # (hash);comment
@geindex statement;import

A path configuration file is a file whose name has the form @code{`name'.pth}
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to @code{sys.path}.  Non-existing items
are never added to @code{sys.path}, and no check is made that the item refers to a
directory rather than a file.  No item is added to @code{sys.path} more than
once.  Blank lines and lines beginning with @code{#} are skipped.  Lines starting
with @code{import} (followed by space or tab) are executed.

@cartouche
@quotation Note 
An executable line in a @code{.pth} file is run at every Python startup,
regardless of whether a particular module is actually going to be used.
Its impact should thus be kept to a minimum.
The primary intended purpose of executable lines is to make the
corresponding module(s) importable
(load 3rd-party import hooks, adjust 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} etc).
Any other initialization is supposed to be done upon a module's
actual import, if and when it happens.
Limiting a code chunk to a single line is a deliberate measure
to discourage putting anything more complex here.
@end quotation
@end cartouche


Modifié dans la version 3.13: The @code{.pth} files are now decoded by UTF-8 at first and then by the
@ref{23f,,locale encoding} if it fails.


@geindex package
@geindex path;configuration;file

For example, suppose @code{sys.prefix} and @code{sys.exec_prefix} are set to
@code{/usr/local}.  The Python X.Y library is then installed in
@code{/usr/local/lib/python`X.Y'}.  Suppose this has
a subdirectory @code{/usr/local/lib/python`X.Y'/site-packages} with three
subsubdirectories, @code{foo}, @code{bar} and @code{spam}, and two path
configuration files, @code{foo.pth} and @code{bar.pth}.  Assume
@code{foo.pth} contains the following:

@example
# foo package configuration

foo
bar
bletch
@end example

and @code{bar.pth} contains:

@example
# bar package configuration

bar
@end example

Then the following version-specific directories are added to
@code{sys.path}, in this order:

@example
/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo
@end example

Note that @code{bletch} is omitted because it doesn't exist; the @code{bar}
directory precedes the @code{foo} directory because @code{bar.pth} comes
alphabetically before @code{foo.pth}; and @code{spam} is omitted because it is
not mentioned in either path configuration file.

@menu
* sitecustomize:: 
* usercustomize:: 
* Readline configuration:: 
* Module contents: Module contents<3>. 
* Interface en ligne de commande: Interface en ligne de commande<10>. 

@end menu

@node sitecustomize,usercustomize,,site --- Site-specific configuration hook
@anchor{library/site module-sitecustomize}@anchor{c7}@anchor{library/site sitecustomize}@anchor{43f2}
@subsubsection @code{sitecustomize}


@geindex module; sitecustomize

After these path manipulations, an attempt is made to import a module named
@ref{c7,,sitecustomize}, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory.  If this import fails with an @ref{40f,,ImportError} or its subclass
exception, and the exception's @ref{2210,,name}
attribute equals to @code{'sitecustomize'},
it is silently ignored.  If Python is started without output streams available, as
with @code{pythonw.exe} on Windows (which is used by default to start IDLE),
attempted output from @ref{c7,,sitecustomize} is ignored.  Any other exception
causes a silent and perhaps mysterious failure of the process.

@node usercustomize,Readline configuration,sitecustomize,site --- Site-specific configuration hook
@anchor{library/site module-usercustomize}@anchor{10d}@anchor{library/site usercustomize}@anchor{43f3}
@subsubsection @code{usercustomize}


@geindex module; usercustomize

After this, an attempt is made to import a module named @ref{10d,,usercustomize},
which can perform arbitrary user-specific customizations, if
@ref{43f4,,ENABLE_USER_SITE} is true.  This file is intended to be created in the
user site-packages directory (see below), which is part of @code{sys.path} unless
disabled by @ref{1362,,-s}.  If this import fails with an @ref{40f,,ImportError} or
its subclass exception, and the exception's @ref{2210,,name}
attribute equals to @code{'usercustomize'}, it is silently ignored.

Note that for some non-Unix systems, @code{sys.prefix} and @code{sys.exec_prefix} are
empty, and the path manipulations are skipped; however the import of
@ref{c7,,sitecustomize} and @ref{10d,,usercustomize} is still attempted.

@node Readline configuration,Module contents<3>,usercustomize,site --- Site-specific configuration hook
@anchor{library/site readline-configuration}@anchor{43f5}@anchor{library/site rlcompleter-config}@anchor{fb4}
@subsubsection Readline configuration


On systems that support @ref{b9,,readline}, this module will also import and
configure the @ref{bc,,rlcompleter} module, if Python is started in
@ref{fb1,,interactive mode} and without the @ref{1186,,-S} option.
The default behavior is enable tab-completion and to use
@code{~/.python_history} as the history save file.  To disable it, delete (or
override) the @ref{fb2,,sys.__interactivehook__} attribute in your
@ref{c7,,sitecustomize} or @ref{10d,,usercustomize} module or your
@geindex PYTHONSTARTUP
@geindex variable d'environnement; PYTHONSTARTUP
@ref{fb3,,PYTHONSTARTUP} file.


Modifié dans la version 3.4: Activation of rlcompleter and history was made automatic.


@node Module contents<3>,Interface en ligne de commande<10>,Readline configuration,site --- Site-specific configuration hook
@anchor{library/site module-contents}@anchor{43f6}
@subsubsection Module contents


@geindex PREFIXES (dans le module site)
@anchor{library/site site PREFIXES}@anchor{43f7}
@deffn {Données} site.PREFIXES

A list of prefixes for site-packages directories.
@end deffn

@geindex ENABLE_USER_SITE (dans le module site)
@anchor{library/site site ENABLE_USER_SITE}@anchor{43f4}
@deffn {Données} site.ENABLE_USER_SITE

Flag showing the status of the user site-packages directory.  @code{True} means
that it is enabled and was added to @code{sys.path}.  @code{False} means that it
was disabled by user request (with @ref{1362,,-s} or
@geindex PYTHONNOUSERSITE
@geindex variable d'environnement; PYTHONNOUSERSITE
@ref{1363,,PYTHONNOUSERSITE}).  @code{None} means it was disabled for security
reasons (mismatch between user or group id and effective id) or by an
administrator.
@end deffn

@geindex USER_SITE (dans le module site)
@anchor{library/site site USER_SITE}@anchor{1cc1}
@deffn {Données} site.USER_SITE

Path to the user site-packages for the running Python.  Can be @code{None} if
@ref{121e,,getusersitepackages()} hasn't been called yet.  Default value is
@code{~/.local/lib/python`X.Y'[t]/site-packages} for UNIX and non-framework
macOS builds, @code{~/Library/Python/`X.Y'/lib/python/site-packages} for macOS
framework builds, and @code{`%APPDATA%'\Python\Python`XY'\site-packages}
on Windows.  The optional "t" indicates the free-threaded build.  This
directory is a site directory, which means that @code{.pth} files in it
will be processed.
@end deffn

@geindex USER_BASE (dans le module site)
@anchor{library/site site USER_BASE}@anchor{12fa}
@deffn {Données} site.USER_BASE

Path to the base directory for the user site-packages.  Can be @code{None} if
@ref{121d,,getuserbase()} hasn't been called yet.  Default value is
@code{~/.local} for UNIX and macOS non-framework builds,
@code{~/Library/Python/`X.Y'} for macOS framework builds, and
@code{`%APPDATA%'\Python} for Windows.  This value is used to
compute the installation directories for scripts, data files, Python modules,
etc. for the @ref{1cd3,,user installation scheme}.
See also 
@geindex PYTHONUSERBASE
@geindex variable d'environnement; PYTHONUSERBASE
@ref{1361,,PYTHONUSERBASE}.
@end deffn

@geindex main() (dans le module site)
@anchor{library/site site main}@anchor{1cc2}
@deffn {Fonction} site.main ()

Adds all the standard site-specific directories to the module search
path.  This function is called automatically when this module is imported,
unless the Python interpreter was started with the @ref{1186,,-S} flag.


Modifié dans la version 3.3: This function used to be called unconditionally.

@end deffn

@geindex addsitedir() (dans le module site)
@anchor{library/site site addsitedir}@anchor{43f8}
@deffn {Fonction} site.addsitedir (sitedir, known_paths=None)

Add a directory to sys.path and process its @code{.pth} files.  Typically
used in @ref{c7,,sitecustomize} or @ref{10d,,usercustomize} (see above).
@end deffn

@geindex getsitepackages() (dans le module site)
@anchor{library/site site getsitepackages}@anchor{121c}
@deffn {Fonction} site.getsitepackages ()

Return a list containing all global site-packages directories.


Ajouté dans la version 3.2.

@end deffn

@geindex getuserbase() (dans le module site)
@anchor{library/site site getuserbase}@anchor{121d}
@deffn {Fonction} site.getuserbase ()

Return the path of the user base directory, @ref{12fa,,USER_BASE}.  If it is not
initialized yet, this function will also set it, respecting
@geindex PYTHONUSERBASE
@geindex variable d'environnement; PYTHONUSERBASE
@ref{1361,,PYTHONUSERBASE}.


Ajouté dans la version 3.2.

@end deffn

@geindex getusersitepackages() (dans le module site)
@anchor{library/site site getusersitepackages}@anchor{121e}
@deffn {Fonction} site.getusersitepackages ()

Return the path of the user-specific site-packages directory,
@ref{1cc1,,USER_SITE}.  If it is not initialized yet, this function will also set
it, respecting @ref{12fa,,USER_BASE}.  To determine if the user-specific
site-packages was added to @code{sys.path} @ref{43f4,,ENABLE_USER_SITE} should be
used.


Ajouté dans la version 3.2.

@end deffn

@node Interface en ligne de commande<10>,,Module contents<3>,site --- Site-specific configuration hook
@anchor{library/site command-line-interface}@anchor{43f9}@anchor{library/site site-commandline}@anchor{43fa}
@subsubsection Interface en ligne de commande


The @ref{c6,,site} module also provides a way to get the user directories from the
command line:

@example
$ python -m site --user-site
/home/user/.local/lib/python3.11/site-packages
@end example

If it is called without arguments, it will print the contents of
@ref{3ab,,sys.path} on the standard output, followed by the value of
@ref{12fa,,USER_BASE} and whether the directory exists, then the same thing for
@ref{1cc1,,USER_SITE}, and finally the value of @ref{43f4,,ENABLE_USER_SITE}.

@geindex option de ligne de commande site; --user-base
@anchor{library/site cmdoption-site-user-base}@anchor{43fb}
@deffn {Option} @w{-}@w{-}user@w{-}base

Print the path to the user base directory.
@end deffn

@geindex option de ligne de commande site; --user-site
@anchor{library/site cmdoption-site-user-site}@anchor{43fc}
@deffn {Option} @w{-}@w{-}user@w{-}site

Print the path to the user site-packages directory.
@end deffn

If both options are given, user base and user site will be printed (always in
this order), separated by @ref{1cd0,,os.pathsep}.

If any option is given, the script will exit with one of these values: @code{0} if
the user site-packages directory is enabled, @code{1} if it was disabled by the
user, @code{2} if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.


@subsubheading Voir aussi



@itemize *

@item 
@geindex Python Enhancement Proposals; PEP 370
PEP 370@footnote{https://peps.python.org/pep-0370/} -- Répertoire site-packages propre à l'utilisateur.

@item 
@ref{1bee,,The initialization of the sys.path module search path} -- The initialization of @ref{3ab,,sys.path}.
@end itemize


@node Interpréteurs Python personnalisés,Importer des modules,Environnement d'exécution Python,La bibliothèque standard
@anchor{library/custominterp doc}@anchor{43fd}@anchor{library/custominterp custom-python-interpreters}@anchor{43fe}@anchor{library/custominterp custominterp}@anchor{43ff}
@section Interpréteurs Python personnalisés


The modules described in this chapter allow writing interfaces similar to
Python's interactive interpreter.  If you want a Python interpreter that
supports some special feature in addition to the Python language, you should
look at the @ref{1a,,code} module.  (The @ref{1c,,codeop} module is lower-level, used
to support compiling a possibly incomplete chunk of Python code.)

La liste complète des modules décrits dans ce chapitre est :

@menu
* code: code --- Interpreter base classes. Interpreter base classes
* codeop: codeop --- Compile Python code. Compile Python code

@end menu

@node code --- Interpreter base classes,codeop --- Compile Python code,,Interpréteurs Python personnalisés
@anchor{library/code doc}@anchor{4400}@anchor{library/code code-interpreter-base-classes}@anchor{4401}@anchor{library/code module-code}@anchor{1a}
@subsection @code{code} --- Interpreter base classes


@geindex module; code

`Code source :' Lib/code.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/code.py}


__________________________________________________________________


The @code{code} module provides facilities to implement read-eval-print loops in
Python.  Two classes and convenience functions are included which can be used to
build applications which provide an interactive interpreter prompt.

@geindex InteractiveInterpreter (classe dans code)
@anchor{library/code code InteractiveInterpreter}@anchor{1561}
@deffn {Classe} code.InteractiveInterpreter (locals=None)

This class deals with parsing and interpreter state (the user's namespace); it
does not deal with input buffering or prompting or input file naming (the
filename is always passed in explicitly). The optional `locals' argument
specifies a mapping to use as the namespace in which code will be executed;
it defaults to a newly created dictionary with key @code{'__name__'} set to
@code{'__console__'} and key @code{'__doc__'} set to @code{None}.
@end deffn

@geindex InteractiveConsole (classe dans code)
@anchor{library/code code InteractiveConsole}@anchor{2323}
@deffn {Classe} code.InteractiveConsole (locals=None, filename='<console>', local_exit=False)

Closely emulate the behavior of the interactive Python interpreter. This class
builds on @ref{1561,,InteractiveInterpreter} and adds prompting using the familiar
@code{sys.ps1} and @code{sys.ps2}, and input buffering. If `local_exit' is true,
@code{exit()} and @code{quit()} in the console will not raise @ref{d2e,,SystemExit}, but
instead return to the calling code.


Modifié dans la version 3.13: Added `local_exit' parameter.

@end deffn

@geindex interact() (dans le module code)
@anchor{library/code code interact}@anchor{165f}
@deffn {Fonction} code.interact (banner=None, readfunc=None, local=None, exitmsg=None, local_exit=False)

Convenience function to run a read-eval-print loop.  This creates a new
instance of @ref{2323,,InteractiveConsole} and sets `readfunc' to be used as
the @ref{4402,,InteractiveConsole.raw_input()} method, if provided.  If `local' is
provided, it is passed to the @ref{2323,,InteractiveConsole} constructor for
use as the default namespace for the interpreter loop.  If `local_exit' is provided,
it is passed to the @ref{2323,,InteractiveConsole} constructor.  The @ref{4403,,interact()}
method of the instance is then run with `banner' and `exitmsg' passed as the
banner and exit message to use, if provided.  The console object is discarded
after use.


Modifié dans la version 3.6: Added `exitmsg' parameter.



Modifié dans la version 3.13: Added `local_exit' parameter.

@end deffn

@geindex compile_command() (dans le module code)
@anchor{library/code code compile_command}@anchor{4404}
@deffn {Fonction} code.compile_command (source, filename='<input>', symbol='single')

This function is useful for programs that want to emulate Python's interpreter
main loop (a.k.a. the read-eval-print loop).  The tricky part is to determine
when the user has entered an incomplete command that can be completed by
entering more text (as opposed to a complete command or a syntax error).  This
function `almost' always makes the same decision as the real interpreter main
loop.

`source' is the source string; `filename' is the optional filename from which
source was read, defaulting to @code{'<input>'}; and `symbol' is the optional
grammar start symbol, which should be @code{'single'} (the default), @code{'eval'}
or @code{'exec'}.

Returns a code object (the same as @code{compile(source, filename, symbol)}) if the
command is complete and valid; @code{None} if the command is incomplete; raises
@ref{18b,,SyntaxError} if the command is complete and contains a syntax error, or
raises @ref{86d,,OverflowError} or @ref{1ff,,ValueError} if the command contains an
invalid literal.
@end deffn

@menu
* Interactive Interpreter Objects:: 
* Interactive Console Objects:: 

@end menu

@node Interactive Interpreter Objects,Interactive Console Objects,,code --- Interpreter base classes
@anchor{library/code interactive-interpreter-objects}@anchor{4405}@anchor{library/code interpreter-objects}@anchor{4406}
@subsubsection Interactive Interpreter Objects


@geindex runsource() (méthode code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter runsource}@anchor{4407}
@deffn {Méthode} InteractiveInterpreter.runsource (source, filename='<input>', symbol='single')

Compile and run some source in the interpreter. Arguments are the same as for
@ref{4404,,compile_command()}; the default for `filename' is @code{'<input>'}, and for
`symbol' is @code{'single'}.  One of several things can happen:


@itemize *

@item 
The input is incorrect; @ref{4404,,compile_command()} raised an exception
(@ref{18b,,SyntaxError} or @ref{86d,,OverflowError}).  A syntax traceback will be
printed by calling the @ref{4408,,showsyntaxerror()} method.  @ref{4407,,runsource()}
returns @code{False}.

@item 
The input is incomplete, and more input is required; @ref{4404,,compile_command()}
returned @code{None}. @ref{4407,,runsource()} returns @code{True}.

@item 
The input is complete; @ref{4404,,compile_command()} returned a code object.  The
code is executed by calling the @ref{4409,,runcode()} (which also handles run-time
exceptions, except for @ref{d2e,,SystemExit}). @ref{4407,,runsource()} returns @code{False}.
@end itemize

The return value can be used to decide whether to use @code{sys.ps1} or @code{sys.ps2}
to prompt the next line.
@end deffn

@geindex runcode() (méthode code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter runcode}@anchor{4409}
@deffn {Méthode} InteractiveInterpreter.runcode (code)

Execute a code object. When an exception occurs, @ref{dbd,,showtraceback()} is called
to display a traceback.  All exceptions are caught except @ref{d2e,,SystemExit},
which is allowed to propagate.

A note about @ref{9bf,,KeyboardInterrupt}: this exception may occur elsewhere in
this code, and may not always be caught.  The caller should be prepared to deal
with it.
@end deffn

@geindex showsyntaxerror() (méthode code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter showsyntaxerror}@anchor{4408}
@deffn {Méthode} InteractiveInterpreter.showsyntaxerror (filename=None)

Display the syntax error that just occurred.  This does not display a stack
trace because there isn't one for syntax errors. If `filename' is given, it is
stuffed into the exception instead of the default filename provided by Python's
parser, because it always uses @code{'<string>'} when reading from a string. The
output is written by the @ref{440a,,write()} method.
@end deffn

@geindex showtraceback() (méthode code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter showtraceback}@anchor{dbd}
@deffn {Méthode} InteractiveInterpreter.showtraceback ()

Display the exception that just occurred.  We remove the first stack item
because it is within the interpreter object implementation. The output is
written by the @ref{440a,,write()} method.


Modifié dans la version 3.5: The full chained traceback is displayed instead
of just the primary traceback.

@end deffn

@geindex write() (méthode code.InteractiveInterpreter)
@anchor{library/code code InteractiveInterpreter write}@anchor{440a}
@deffn {Méthode} InteractiveInterpreter.write (data)

Write a string to the standard error stream (@code{sys.stderr}). Derived classes
should override this to provide the appropriate output handling as needed.
@end deffn

@node Interactive Console Objects,,Interactive Interpreter Objects,code --- Interpreter base classes
@anchor{library/code console-objects}@anchor{440b}@anchor{library/code interactive-console-objects}@anchor{440c}
@subsubsection Interactive Console Objects


The @ref{2323,,InteractiveConsole} class is a subclass of
@ref{1561,,InteractiveInterpreter}, and so offers all the methods of the
interpreter objects as well as the following additions.

@geindex interact() (méthode code.InteractiveConsole)
@anchor{library/code code InteractiveConsole interact}@anchor{4403}
@deffn {Méthode} InteractiveConsole.interact (banner=None, exitmsg=None)

Closely emulate the interactive Python console. The optional `banner' argument
specify the banner to print before the first interaction; by default it prints a
banner similar to the one printed by the standard Python interpreter, followed
by the class name of the console object in parentheses (so as not to confuse
this with the real interpreter -- since it's so close!).

The optional `exitmsg' argument specifies an exit message printed when exiting.
Pass the empty string to suppress the exit message. If `exitmsg' is not given or
@code{None}, a default message is printed.


Modifié dans la version 3.4: To suppress printing any banner, pass an empty string.



Modifié dans la version 3.6: Print an exit message when exiting.

@end deffn

@geindex push() (méthode code.InteractiveConsole)
@anchor{library/code code InteractiveConsole push}@anchor{440d}
@deffn {Méthode} InteractiveConsole.push (line)

Push a line of source text to the interpreter. The line should not have a
trailing newline; it may have internal newlines.  The line is appended to a
buffer and the interpreter's @ref{4407,,runsource()} method is called with the
concatenated contents of the buffer as source.  If this indicates that the
command was executed or invalid, the buffer is reset; otherwise, the command is
incomplete, and the buffer is left as it was after the line was appended.  The
return value is @code{True} if more input is required, @code{False} if the line was
dealt with in some way (this is the same as @code{runsource()}).
@end deffn

@geindex resetbuffer() (méthode code.InteractiveConsole)
@anchor{library/code code InteractiveConsole resetbuffer}@anchor{440e}
@deffn {Méthode} InteractiveConsole.resetbuffer ()

Remove any unhandled source text from the input buffer.
@end deffn

@geindex raw_input() (méthode code.InteractiveConsole)
@anchor{library/code code InteractiveConsole raw_input}@anchor{4402}
@deffn {Méthode} InteractiveConsole.raw_input (prompt='@w{'})

Write a prompt and read a line.  The returned line does not include the trailing
newline.  When the user enters the EOF key sequence, @ref{12b7,,EOFError} is raised.
The base implementation reads from @code{sys.stdin}; a subclass may replace this
with a different implementation.
@end deffn

@node codeop --- Compile Python code,,code --- Interpreter base classes,Interpréteurs Python personnalisés
@anchor{library/codeop doc}@anchor{440f}@anchor{library/codeop codeop-compile-python-code}@anchor{4410}@anchor{library/codeop module-codeop}@anchor{1c}
@subsection @code{codeop} --- Compile Python code


@geindex module; codeop

`Code source :' Lib/codeop.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/codeop.py}


__________________________________________________________________


Le module @ref{1c,,codeop} fournit des outils permettant d'émuler une boucle de lecture-évaluation-affichage (en anglais `read-eval-print-loop' ou REPL), comme dans le module @ref{1a,,code}.  Par conséquent, ce module n'est pas destiné à être utilisé directement ; pour inclure un REPL dans un programme, il est préférable d'utiliser le module @ref{1a,,code}.

Cette tâche se divise en deux parties :


@enumerate 

@item 
Being able to tell if a line of input completes a Python statement: in
short, telling whether to print '@code{>>>}' or '@code{...}' next.

@item 
Remembering which future statements the user has entered, so subsequent
input can be compiled with these in effect.
@end enumerate

Le module @ref{1c,,codeop} fournit un moyen d'effectuer ces deux parties, individuellement ou simultanément.

Pour ne faire que la première partie :

@geindex compile_command() (dans le module codeop)
@anchor{library/codeop codeop compile_command}@anchor{1756}
@deffn {Fonction} codeop.compile_command (source, filename='<input>', symbol='single')

Tries to compile `source', which should be a string of Python code and return a
code object if `source' is valid Python code.  In that case, the filename
attribute of the code object will be `filename', which defaults to
@code{'<input>'}.  Returns @code{None} if `source' is `not' valid Python code, but is a
prefix of valid Python code.

En cas de problème avec `source', une exception est levée ; @ref{18b,,SyntaxError} si la syntaxe Python est incorrecte, et @ref{86d,,OverflowError} ou @ref{1ff,,ValueError} si un littéral invalide est rencontré.

The `symbol' argument determines whether `source' is compiled as a statement
(@code{'single'}, the default), as a sequence of @ref{2704,,statement} (@code{'exec'}) or
as an @ref{1f08,,expression} (@code{'eval'}).  Any other value will
cause @ref{1ff,,ValueError} to be raised.

@cartouche
@quotation Note 
Il est possible (quoique improbable) que l'analyseur s'arrête avant d'atteindre la fin du code source ; dans ce cas, les symboles venant après peuvent être ignorés au lieu de provoquer une erreur. Par exemple, une barre oblique inverse suivie de deux retours à la ligne peut être suivie par de la mémoire non-initialisée. Ceci sera corrigé quand l'interface de l'analyseur aura été améliorée.
@end quotation
@end cartouche
@end deffn

@geindex Compile (classe dans codeop)
@anchor{library/codeop codeop Compile}@anchor{4411}
@deffn {Classe} codeop.Compile

Instances of this class have @ref{543,,__call__()} methods identical in signature to
the built-in function @ref{190,,compile()}, but with the difference that if the
instance compiles program text containing a @ref{0,,__future__} statement, the
instance 'remembers' and compiles all subsequent program texts with the
statement in force.
@end deffn

@geindex CommandCompiler (classe dans codeop)
@anchor{library/codeop codeop CommandCompiler}@anchor{4412}
@deffn {Classe} codeop.CommandCompiler

Instances of this class have @ref{543,,__call__()} methods identical in signature to
@ref{1756,,compile_command()}; the difference is that if the instance compiles program
text containing a @ref{0,,__future__} statement, the instance 'remembers' and
compiles all subsequent program texts with the statement in force.
@end deffn

@node Importer des modules,Services du Langage Python,Interpréteurs Python personnalisés,La bibliothèque standard
@anchor{library/modules doc}@anchor{4413}@anchor{library/modules importing-modules}@anchor{4414}@anchor{library/modules modules}@anchor{4415}
@section Importer des modules


Les modules décrits dans ce chapitre fournissent de nouveaux moyens d'importer d'autres modules Python, et des `hooks' pour personnaliser le processus d'importation.

La liste complète des modules décrits dans ce chapitre est :

@menu
* zipimport: zipimport --- Import modules from Zip archives. Import modules from Zip archives
* pkgutil: pkgutil --- Package extension utility. Package extension utility
* modulefinder: modulefinder --- Find modules used by a script. Find modules used by a script
* runpy: runpy --- Locating and executing Python modules. Locating and executing Python modules
* importlib: importlib --- The implementation of import. The implementation of import
* importlib.resources: importlib resources -- Package resource reading opening and access. Package resource reading, opening and access
* importlib.resources.abc: importlib resources abc -- Abstract base classes for resources. Abstract base classes for resources
* importlib.metadata: importlib metadata -- Accessing package metadata. Accessing package metadata
* The initialization of the sys.path module search path: The initialization of the sys path module search path. 

@end menu

@node zipimport --- Import modules from Zip archives,pkgutil --- Package extension utility,,Importer des modules
@anchor{library/zipimport doc}@anchor{4416}@anchor{library/zipimport module-zipimport}@anchor{131}@anchor{library/zipimport zipimport-import-modules-from-zip-archives}@anchor{4417}
@subsection @code{zipimport} --- Import modules from Zip archives


@geindex module; zipimport

`Code source :' Lib/zipimport.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/zipimport.py}


__________________________________________________________________


Ce module ajoute la possibilité d'importer des modules Python (@code{*.py}, @code{*.pyc}) et des paquets depuis des archives au format ZIP. Il n'est généralement pas nécessaire d'utiliser explicitement le module @ref{131,,zipimport} ; il est automatiquement utilisé par le mécanisme intégré de @ref{5cc,,import} pour les éléments de @ref{3ab,,sys.path} qui sont des chemins vers des archives ZIP.

En général, @ref{3ab,,sys.path} est une liste de noms de répertoires sous forme de chaînes.  Ce module permet également à un élément de @ref{3ab,,sys.path} d'être une chaîne nommant une archive de fichier ZIP. L'archive peut contenir une arborescence de répertoires pour prendre en charge les importations de paquets, et un chemin dans l'archive peut être donné pour importer uniquement à partir d'un sous-répertoire.  Par exemple, le chemin d'accès @code{example.zip/lib/} importerait uniquement depuis le sous-répertoire @code{lib/} dans l'archive.

Tous les fichiers peuvent être présents dans l'archive ZIP, mais les importateurs ne sont invoqués que pour les fichiers @code{.py} et @code{.pyc}.  L'importation ZIP de modules dynamiques (@code{.py}, @code{.so}) n'est pas permise. Notez que si une archive ne contient que des fichiers @code{.py}, Python n'essaiera pas de modifier l'archive en ajoutant le fichier @code{.pyc} correspondant, ce qui signifie que si une archive ZIP ne contient pas de fichiers @code{.pyc}, l'importation peut être assez lente.


Modifié dans la version 3.13: ZIP64 is supported



Modifié dans la version 3.8: auparavant, les archives ZIP avec un commentaire d’archive n’étaient pas prises en charge.



@subsubheading Voir aussi



@table @asis

@item PKZIP Application Note@footnote{https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT}

Documentation sur le format de fichier ZIP par Phil Katz, créateur du format et des algorithmes utilisés.

@geindex Python Enhancement Proposals; PEP 273

@item PEP 273@footnote{https://peps.python.org/pep-0273/} — Importation de modules depuis des archives ZIP

Écrit par James C. Ahlstrom, qui a également fourni une mise en œuvre. Python 2.3 suit les spécifications de 
@geindex Python Enhancement Proposals; PEP 273
PEP 273@footnote{https://peps.python.org/pep-0273/}, mais utilise une implémentation écrite par Just van Rossum qui utilise les crochets d'importation décrits dans 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}.

@item @ref{76,,importlib} — Implémentation du système d'importation

Paquet qui définit les protocoles que doivent implémenter tous les objets importateurs.
@end table


Ce module définit une exception :

@geindex ZipImportError
@anchor{library/zipimport zipimport ZipImportError}@anchor{4418}
@deffn {Exception} zipimport.ZipImportError

Exception levée par les objets `zipimporter'. C'est une sous-classe de @ref{40f,,ImportError}, donc elle peut être aussi interceptée comme une @ref{40f,,ImportError}.
@end deffn

@menu
* Objets zimporter:: 
* Exemples: Exemples<32>. 

@end menu

@node Objets zimporter,Exemples<32>,,zipimport --- Import modules from Zip archives
@anchor{library/zipimport id1}@anchor{4419}@anchor{library/zipimport zipimporter-objects}@anchor{441a}
@subsubsection Objets `zimporter'


@ref{441b,,zipimporter} est la classe pour importer des fichiers ZIP.

@geindex zipimporter (classe dans zipimport)
@anchor{library/zipimport zipimport zipimporter}@anchor{441b}
@deffn {Classe} zipimport.zipimporter (archivepath)

Classe d'objets qui importent depuis les archives. Dans le constructeur, `archivepath' doit être un chemin vers un fichier ZIP, éventuellement augmenté d'un chemin à l'intérieur de l'archive.  Par exemple, un `archivepath' de @code{foo/bar.zip/lib} cherchera les modules dans le répertoire @code{lib} du fichier ZIP @code{foo/bar.zip} (à supposer que ce répertoire existe).

@ref{4418,,ZipImportError} est levée si `archivepath' ne pointe pas vers une archive ZIP valide.


Modifié dans la version 3.12: Methods @code{find_loader()} and @code{find_module()}, deprecated in 3.10 are
now removed.  Use @ref{848,,find_spec()} instead.


@geindex create_module() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter create_module}@anchor{849}
@deffn {Méthode} create_module (spec)

Implémentation de @ref{c9c,,importlib.abc.Loader.create_module()}. Elle renvoie toujours @ref{660,,None}, ce qui déclenche le mécanisme standard.


Ajouté dans la version 3.10.

@end deffn

@geindex exec_module() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter exec_module}@anchor{307}
@deffn {Méthode} exec_module (module)

Implémentation de @ref{855,,importlib.abc.Loader.exec_module()}.


Ajouté dans la version 3.10.

@end deffn

@geindex find_spec() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter find_spec}@anchor{848}
@deffn {Méthode} find_spec (fullname, target=None)

Implémentation de @ref{857,,importlib.abc.PathEntryFinder.find_spec()}.


Ajouté dans la version 3.10.

@end deffn

@geindex get_code() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_code}@anchor{441c}
@deffn {Méthode} get_code (fullname)

Renvoie l'objet de code pour le module spécifié. Lève @ref{4418,,ZipImportError} si l'importation a échoué.
@end deffn

@geindex get_data() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_data}@anchor{441d}
@deffn {Méthode} get_data (pathname)

Renvoie les données associées à `pathname'. Lève @ref{40d,,OSError} si le fichier n'a pas été trouvé.


Modifié dans la version 3.3: @ref{103b,,IOError} used to be raised, it is now an alias of @ref{40d,,OSError}.

@end deffn

@geindex get_filename() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_filename}@anchor{441e}
@deffn {Méthode} get_filename (fullname)

Renvoie la valeur @code{__file____} qui serait définie si le module spécifié était importé. Lève @ref{4418,,ZipImportError} si l'importation a échoué.


Ajouté dans la version 3.1.

@end deffn

@geindex get_source() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter get_source}@anchor{441f}
@deffn {Méthode} get_source (fullname)

Renvoie le code source du module spécifié. Lève @ref{4418,,ZipImportError} si le module n'a pas pu être trouvé, renvoie @ref{660,,None} si l'archive contient le module, mais n'en a pas la source.
@end deffn

@geindex is_package() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter is_package}@anchor{4420}
@deffn {Méthode} is_package (fullname)

Renvoie @code{True} si le module spécifié par `fullname' est un paquet. Lève @ref{4418,,ZipImportError} si le module n'a pas pu être trouvé.
@end deffn

@geindex load_module() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter load_module}@anchor{306}
@deffn {Méthode} load_module (fullname)

Charge et renvoie le module spécifié par `fullname', qui doit être le nom du module entièrement qualifié (avec des points). Lève @ref{4418,,ZipImportError} si l'importation a échoué.


Obsolète depuis la version 3.10: utilisez plutôt @ref{307,,exec_module()}.

@end deffn

@geindex invalidate_caches() (méthode zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter invalidate_caches}@anchor{84a}
@deffn {Méthode} invalidate_caches ()

Efface le cache interne des informations sur les fichiers à l'intérieur de l'archive ZIP.


Ajouté dans la version 3.10.

@end deffn

@geindex archive (attribut zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter archive}@anchor{4421}
@deffn {Attribut} archive

Le nom de fichier de l'archive ZIP associé à l'importateur, sans sous-chemin à l'intérieur.
@end deffn

@geindex prefix (attribut zipimport.zipimporter)
@anchor{library/zipimport zipimport zipimporter prefix}@anchor{4422}
@deffn {Attribut} prefix

Le sous-chemin du fichier ZIP où les modules sont recherchés.  C'est la chaîne vide pour les objets `zipimporter' qui pointent vers la racine du fichier ZIP.
@end deffn

On a schématiquement @ref{4421,,archive} + @code{'/'} + @ref{4422,,prefix} == `archivepath', où `archivepath' est l'argument donné au constructeur @ref{441b,,zipimporter}.
@end deffn

@node Exemples<32>,,Objets zimporter,zipimport --- Import modules from Zip archives
@anchor{library/zipimport examples}@anchor{4423}@anchor{library/zipimport zipimport-examples}@anchor{4424}
@subsubsection Exemples


Voici un exemple qui importe un module d'une archive ZIP — notez que le module @ref{131,,zipimport} n'est pas explicitement utilisé.

@example
$ unzip -l example.zip
Archive:  example.zip
  Length     Date   Time    Name
 --------    ----   ----    ----
     8467  11-26-02 22:30   jwzthreading.py
 --------                   -------
     8467                   1 file
$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, 'example.zip')  # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'example.zip/jwzthreading.py'
@end example

@node pkgutil --- Package extension utility,modulefinder --- Find modules used by a script,zipimport --- Import modules from Zip archives,Importer des modules
@anchor{library/pkgutil doc}@anchor{4425}@anchor{library/pkgutil module-pkgutil}@anchor{a8}@anchor{library/pkgutil pkgutil-package-extension-utility}@anchor{4426}
@subsection @code{pkgutil} --- Package extension utility


@geindex module; pkgutil

`Code source :' Lib/pkgutil.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pkgutil.py}


__________________________________________________________________


Ce module fournit des utilitaires pour le système d'importation, en particulier pour la prise en charge des paquets.

@geindex ModuleInfo (classe dans pkgutil)
@anchor{library/pkgutil pkgutil ModuleInfo}@anchor{d39}
@deffn {Classe} pkgutil.ModuleInfo (module_finder, name, ispkg)

Un `n'-uplet nommé qui contient un bref résumé des informations d'un module.


Ajouté dans la version 3.6.

@end deffn

@geindex extend_path() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil extend_path}@anchor{156d}
@deffn {Fonction} pkgutil.extend_path (path, name)

Étend le chemin de recherche pour les modules qui composent un paquet. L'usage prévu est de placer le code suivant dans le @code{__init__.py} d'un paquet :

@example
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
@end example

For each directory on @ref{3ab,,sys.path} that has a subdirectory that matches the
package name, add the subdirectory to the package's
@ref{1bfc,,__path__}. This is useful
if one wants to distribute different parts of a single logical package as multiple
directories.

It also looks for @code{*.pkg} files beginning where @code{*} matches the
`name' argument.  This feature is similar to @code{*.pth} files (see the
@ref{c6,,site} module for more information), except that it doesn't special-case
lines starting with @code{import}.  A @code{*.pkg} file is trusted at face
value: apart from skipping blank lines and ignoring comments, all entries
found in a @code{*.pkg} file are added to the path, regardless of whether
they exist on the filesystem (this is a feature).

Si le chemin d'entrée n'est pas une liste (comme c'est le cas pour les paquets figés), il est retourné tel quel. Le chemin d'entrée n'est pas modifié ; une copie étendue en est retournée. Les éléments ne sont ajoutés à la copie qu'à la fin.

L'interpréteur estime que @ref{3ab,,sys.path} est une séquence. Les éléments de @ref{3ab,,sys.path} qui ne sont pas des chaînes se référant à des répertoires existants sont ignorés. Les éléments Unicode sur @ref{3ab,,sys.path} qui provoquent des erreurs lorsqu'ils sont utilisés comme noms de fichiers peuvent amener cette fonction à lever une exception (conformément au comportement de @ref{9fe,,os.path.isdir()}).
@end deffn

@geindex find_loader() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil find_loader}@anchor{2c9}
@deffn {Fonction} pkgutil.find_loader (fullname)

Récupère un @ref{1639,,loader} de module pour le `fullname' donné.

Il s'agit d'une surcouche de compatibilité ascendante autour de @ref{2cb,,importlib.util.find_spec()} qui convertit la plupart des échecs en @ref{40f,,ImportError} et ne renvoie que le chargeur, plutôt que le @ref{1ded,,importlib.machinery.ModuleSpec} complet.


Modifié dans la version 3.3: Mise à jour pour être basée directement sur @ref{76,,importlib} au lieu de dépendre de l'émulation interne de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} du paquet.



Modifié dans la version 3.4: Mise à jour pour être basée sur la 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}



Deprecated since version 3.12, will be removed in version 3.14: Use @ref{2cb,,importlib.util.find_spec()} instead.

@end deffn

@geindex get_importer() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil get_importer}@anchor{4427}
@deffn {Fonction} pkgutil.get_importer (path_item)

Récupère un @ref{1ea3,,finder} pour l'élément `path_item' donné.

Le chercheur retourné est mis en cache dans @ref{5ce,,sys.path_importer_cache} s'il a été récemment créé par le chemin d'un point d'entrée.

Le cache (ou une partie de celui-ci) peut être effacé manuellement si une nouvelle analyse de @ref{100d,,sys.path_hooks} est nécessaire.


Modifié dans la version 3.3: Mise à jour pour être basée directement sur @ref{76,,importlib} au lieu de dépendre de l'émulation interne de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} du paquet.

@end deffn

@geindex get_loader() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil get_loader}@anchor{2ca}
@deffn {Fonction} pkgutil.get_loader (module_or_name)

Récupère un objet @ref{1639,,loader} pour `module_or_name'.

Si le module ou le paquet est accessible via le mécanisme d'importation normal, une encapsulation autour de la partie pertinente de cette mécanique est renvoyé. Renvoie @code{None} si le module ne peut pas être trouvé ou importé. Si le module nommé n'est pas déjà importé, son paquet contenant (le cas échéant) est importé afin d'établir le paquet @code{__path__}.


Modifié dans la version 3.3: Mise à jour pour être basée directement sur @ref{76,,importlib} au lieu de dépendre de l'émulation interne de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} du paquet.



Modifié dans la version 3.4: Mise à jour pour être basée sur la 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}



Deprecated since version 3.12, will be removed in version 3.14: Use @ref{2cb,,importlib.util.find_spec()} instead.

@end deffn

@geindex iter_importers() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil iter_importers}@anchor{1178}
@deffn {Fonction} pkgutil.iter_importers (fullname='@w{'})

Génère des objets @ref{1ea3,,finder} pour le nom du module donné.

Si le nom complet contient un @code{'.'}, les chercheurs sont pour le paquet contenant le nom complet, sinon ils sont enregistrés pour tous les chercheurs de niveau supérieur (c'est-à-dire ceux de @ref{d19,,sys.meta_path} et de @ref{100d,,sys.path_hooks}).

Si le module nommé se trouve dans un paquet, ce paquet est importé en tant qu'effet secondaire de l'invocation de cette fonction.

Si aucun nom de module n'est spécifié, tous les chercheurs de niveau supérieur sont générés.


Modifié dans la version 3.3: Mise à jour pour être basée directement sur @ref{76,,importlib} au lieu de dépendre de l'émulation interne de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} du paquet.

@end deffn

@geindex iter_modules() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil iter_modules}@anchor{d38}
@deffn {Fonction} pkgutil.iter_modules (path=None, prefix='@w{'})

Fournit des @ref{d39,,ModuleInfo} pour tous les sous-modules sur `path' ou, si `path' est @code{None}, pour tous les modules de niveau supérieur sur @ref{3ab,,sys.path}.

`path' doit être soit @code{None}, soit une liste de chemins pour rechercher des modules.

`prefix' est une chaîne de caractères à afficher au début de chaque nom de module en sortie.

@cartouche
@quotation Note 
Cela fonctionne uniquement pour un @ref{1ea3,,finder} qui définit une méthode @code{iter_modules()}. Cette interface n'est pas standard, donc le module fournit également des implémentations pour @ref{105b,,importlib.machinery.FileFinder} et @ref{441b,,zipimport.zipimporter}.
@end quotation
@end cartouche


Modifié dans la version 3.3: Mise à jour pour être basée directement sur @ref{76,,importlib} au lieu de dépendre de l'émulation interne de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} du paquet.

@end deffn

@geindex walk_packages() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil walk_packages}@anchor{bed}
@deffn {Fonction} pkgutil.walk_packages (path=None, prefix='@w{'}, onerror=None)

Fournit des @ref{d39,,ModuleInfo} pour tous les modules de manière récursive sur `path' ou, si `path' est @code{None}, tous les modules accessibles.

`path' doit être soit @code{None}, soit une liste de chemins pour rechercher des modules.

`prefix' est une chaîne de caractères à afficher au début de chaque nom de module en sortie.

Notez que cette fonction doit importer tous les `packages' (`pas' tous les modules !) sur le `path' donné, afin d'accéder à l'attribut @code{__path__} pour trouver les sous-modules.

`onerror' est une fonction qui est appelée avec un argument (le nom du paquet qui était en cours d'importation) si une exception se produit lors de la tentative d'importation d'un paquet. Si aucune fonction `onerror' n'est fournie, les @ref{40f,,ImportError}s sont attrapées et ignorées, tandis que toutes les autres exceptions sont propagées, mettant fin à la recherche.

Exemples :

@example
# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')
@end example

@cartouche
@quotation Note 
Cela fonctionne uniquement pour un @ref{1ea3,,finder} qui définit une méthode @code{iter_modules()}. Cette interface n'est pas standard, donc le module fournit également des implémentations pour @ref{105b,,importlib.machinery.FileFinder} et @ref{441b,,zipimport.zipimporter}.
@end quotation
@end cartouche


Modifié dans la version 3.3: Mise à jour pour être basée directement sur @ref{76,,importlib} au lieu de dépendre de l'émulation interne de la 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} du paquet.

@end deffn

@geindex get_data() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil get_data}@anchor{4428}
@deffn {Fonction} pkgutil.get_data (package, resource)

Obtient une ressource à partir d'un paquet.

Ceci est une surcouche pour l'API @ref{1639,,loader} @ref{4429,,get_data}. L'argument `package' doit être le nom d'un paquet, au format module standard (@code{foo.bar}). L'argument `resource' doit être sous forme d'un nom de fichier relatif, en utilisant @code{/} comme séparateur de chemin. Le nom du répertoire parent @code{..} n'est pas autorisé, pas plus qu'un nom racine (commençant par @code{/}).

La fonction renvoie une chaîne binaire qui est le contenu de la ressource spécifiée.

Pour les paquets situés dans le système de fichiers, qui ont déjà été importés, c'est l'équivalent approximatif de :

@example
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
@end example

Si le paquet ne peut pas être localisé ou chargé, ou s'il utilise un @ref{1639,,loader} qui ne prend pas en charge @ref{4429,,get_data}, alors @code{None} est retourné. En particulier, le @ref{1639,,loader} pour les @ref{1bf6,,paquets espaces de noms} ne prend pas en charge @ref{4429,,get_data}.
@end deffn

@geindex resolve_name() (dans le module pkgutil)
@anchor{library/pkgutil pkgutil resolve_name}@anchor{442a}
@deffn {Fonction} pkgutil.resolve_name (name)

Solutionne un nom en un objet.

Cette fonctionnalité est utilisée dans de nombreux endroits de la bibliothèque standard (voir bpo-12915@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=12915}) - et une fonctionnalité équivalente est également présente dans des paquets largement utilisés tels que Setuptools, Django et Pyramid.

Python s'attend à ce que `name' soit une chaîne de caractères dans l'un des formats suivants, où W est une abréviation pour un identifiant Python valide et le point représente un point littéral dans ces pseudo-regexes :


@itemize *

@item 
@code{W(.W)*}

@item 
@code{W(.W)*:(W(.W)*)?}
@end itemize

La première forme est destinée uniquement à assurer la compatibilité ascendante. Elle suppose qu'une partie du nom pointé est un paquet, et que le reste est un objet quelque part à l'intérieur de ce paquet, éventuellement niché à l'intérieur d'autres objets. Puisque l'endroit où le paquet s'arrête et où la hiérarchie des objets commence ne peut pas être déduit par inspection, des tentatives répétées d'importation doivent être effectuées avec cette forme.

Dans la deuxième forme, l'appelant clarifie le point de division en fournissant un seul deux-points : le nom pointé à gauche des deux-points est un package à importer, et le nom pointé à droite est la hiérarchie d'objets à l'intérieur de ce paquet. Seule une importation est nécessaire dans cette forme. Si elle se termine par un deux-points, alors un objet module est retourné.

La fonction renvoie un objet (qui pourrait être un module), ou génère l'une des exceptions suivantes :

@ref{1ff,,ValueError} – si `name' n'est pas un format reconnu.

@ref{40f,,ImportError} – si une importation échoue lorsqu'elle n'aurait pas dû.

@ref{343,,AttributeError} – Si un échec s'est produit lors du parcours de la hiérarchie d'objets dans le paquet importé pour accéder à l'objet souhaité.


Ajouté dans la version 3.9.

@end deffn

@node modulefinder --- Find modules used by a script,runpy --- Locating and executing Python modules,pkgutil --- Package extension utility,Importer des modules
@anchor{library/modulefinder doc}@anchor{442b}@anchor{library/modulefinder module-modulefinder}@anchor{90}@anchor{library/modulefinder modulefinder-find-modules-used-by-a-script}@anchor{442c}
@subsection @code{modulefinder} --- Find modules used by a script


@geindex module; modulefinder

`Code source :' Lib/modulefinder.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/modulefinder.py}


__________________________________________________________________


Ce module fournit une classe @ref{1991,,ModuleFinder} qui peut être utilisée pour déterminer la liste des modules importés par un script. @code{modulefinder.py} peut aussi être utilisé en tant que script, en passant le nom du fichier Python en argument, ce qui affichera un rapport sur les modules importés.

@geindex AddPackagePath() (dans le module modulefinder)
@anchor{library/modulefinder modulefinder AddPackagePath}@anchor{442d}
@deffn {Fonction} modulefinder.AddPackagePath (pkg_name, path)

Enregistre que le paquet `pkg_name' peut être trouvé au chemin `path' spécifié.
@end deffn

@geindex ReplacePackage() (dans le module modulefinder)
@anchor{library/modulefinder modulefinder ReplacePackage}@anchor{442e}
@deffn {Fonction} modulefinder.ReplacePackage (oldname, newname)

Permet de spécifier que le module nommé `oldname' est en réalité le paquet nommé `newname'.
@end deffn

@geindex ModuleFinder (classe dans modulefinder)
@anchor{library/modulefinder modulefinder ModuleFinder}@anchor{1991}
@deffn {Classe} modulefinder.ModuleFinder (path=None, debug=0, excludes=[], replace_paths=[])

Cette classe fournit les méthodes @ref{442f,,run_script()} et @ref{4430,,report()} pour déterminer l'ensemble des modules importés par un script. `path' peut être une liste de dossiers dans lesquels chercher les modules ; si non spécifié, @code{sys.path} est utilisé. `debug' définit le niveau de débogage ; des valeurs plus élevées produisent plus de détails sur ce que fait la classe. `excludes' est une liste de noms de modules à exclure de l'analyse. `replace_paths' est une liste de paires @code{(oldpath, newpath)} qui seront remplacés dans les chemins des modules.

@geindex report() (méthode modulefinder.ModuleFinder)
@anchor{library/modulefinder modulefinder ModuleFinder report}@anchor{4430}
@deffn {Méthode} report ()

Affiche un rapport sur la sortie standard qui liste les modules importés par le script et leurs chemins, ainsi que les modules manquants ou qui n'ont pas été trouvés.
@end deffn

@geindex run_script() (méthode modulefinder.ModuleFinder)
@anchor{library/modulefinder modulefinder ModuleFinder run_script}@anchor{442f}
@deffn {Méthode} run_script (pathname)

Analyse le contenu du fichier `pathname', qui doit contenir du code Python.
@end deffn

@geindex modules (attribut modulefinder.ModuleFinder)
@anchor{library/modulefinder modulefinder ModuleFinder modules}@anchor{4431}
@deffn {Attribut} modules

Un dictionnaire de correspondance entre nom de modules et modules. Voir @ref{4432,,Exemples d'utilisation de la classe ModuleFinder}.
@end deffn
@end deffn

@menu
* Exemples d'utilisation de la classe ModuleFinder:: 

@end menu

@node Exemples d'utilisation de la classe ModuleFinder,,,modulefinder --- Find modules used by a script
@anchor{library/modulefinder example-usage-of-modulefinder}@anchor{4433}@anchor{library/modulefinder modulefinder-example}@anchor{4432}
@subsubsection Exemples d'utilisation de la classe @code{ModuleFinder}


Le script qui sera analysé (`bacon.py') :

@example
import re, itertools

try:
    import baconhameggs
except ImportError:
    pass

try:
    import guido.python.ham
except ImportError:
    pass
@end example

Le script qui va afficher le rapport de `bacon.py' :

@example
from modulefinder import ModuleFinder

finder = ModuleFinder()
finder.run_script('bacon.py')

print('Loaded modules:')
for name, mod in finder.modules.items():
    print('%s: ' % name, end='@w{'})
    print(','.join(list(mod.globalnames.keys())[:3]))

print('-'*50)
print('Modules not imported:')
print('\n'.join(finder.badmodules.keys()))
@end example

Exemple de sortie (peut varier en fonction de l'architecture) :

@example
Loaded modules:
_types:
copyreg:  _inverted_registry,_slotnames,__all__
re._compiler:  isstring,_sre,_optimize_unicode
_sre:
re._constants:  REPEAT_ONE,makedict,AT_END_LINE
sys:
re:  __module__,finditer,_expand
itertools:
__main__:  re,itertools,baconhameggs
re._parser:  _PATTERNENDERS,SRE_FLAG_UNICODE
array:
types:  __module__,IntType,TypeType
---------------------------------------------------
Modules not imported:
guido.python.ham
baconhameggs
@end example

@node runpy --- Locating and executing Python modules,importlib --- The implementation of import,modulefinder --- Find modules used by a script,Importer des modules
@anchor{library/runpy doc}@anchor{4434}@anchor{library/runpy module-runpy}@anchor{bd}@anchor{library/runpy runpy-locating-and-executing-python-modules}@anchor{4435}
@subsection @code{runpy} --- Locating and executing Python modules


@geindex module; runpy

`Code source :' Lib/runpy.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/runpy.py}


__________________________________________________________________


The @ref{bd,,runpy} module is used to locate and run Python modules without
importing them first. Its main use is to implement the @ref{5cb,,-m} command
line switch that allows scripts to be located using the Python module
namespace rather than the filesystem.

Note that this is `not' a sandbox module - all code is executed in the
current process, and any side effects (such as cached imports of other
modules) will remain in place after the functions have returned.

Furthermore, any functions and classes defined by the executed code are not
guaranteed to work correctly after a @ref{bd,,runpy} function has returned.
If that limitation is not acceptable for a given use case, @ref{76,,importlib}
is likely to be a more suitable choice than this module.

The @ref{bd,,runpy} module provides two functions:

@geindex run_module() (dans le module runpy)
@anchor{library/runpy runpy run_module}@anchor{179a}
@deffn {Fonction} runpy.run_module (mod_name, init_globals=None, run_name=None, alter_sys=False)

@geindex module;__main__

Execute the code of the specified module and return the resulting module's
globals dictionary. The module's code is first located using the standard
import mechanism (refer to 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} for details) and then executed in a
fresh module namespace.

The `mod_name' argument should be an absolute module name.
If the module name refers to a package rather than a normal
module, then that package is imported and the @ref{1,,__main__} submodule within
that package is then executed and the resulting module globals dictionary
returned.

The optional dictionary argument `init_globals' may be used to pre-populate
the module's globals dictionary before the code is executed.
`init_globals' will not be modified. If any of the special global variables
below are defined in `init_globals', those definitions are
overridden by @ref{179a,,run_module()}.

The special global variables @code{__name__}, @code{__spec__}, @code{__file__},
@code{__cached__}, @code{__loader__} and @code{__package__} are set in the globals
dictionary before the module code is executed. (Note that this is a
minimal set of variables - other variables may be set implicitly as an
interpreter implementation detail.)

@code{__name__} is set to `run_name' if this optional argument is not
@ref{660,,None}, to @code{mod_name + '.__main__'} if the named module is a
package and to the `mod_name' argument otherwise.

@code{__spec__} will be set appropriately for the `actually' imported
module (that is, @code{__spec__.name} will always be `mod_name' or
@code{mod_name + '.__main__'}, never `run_name').

@code{__file__}, @code{__cached__}, @code{__loader__} and @code{__package__} are
@ref{1e99,,set as normal} based on the module spec.

If the argument `alter_sys' is supplied and evaluates to @ref{bfb,,True},
then @code{sys.argv[0]} is updated with the value of @code{__file__} and
@code{sys.modules[__name__]} is updated with a temporary module object for the
module being executed. Both @code{sys.argv[0]} and @code{sys.modules[__name__]}
are restored to their original values before the function returns.

Note that this manipulation of @ref{d8,,sys} is not thread-safe. Other threads
may see the partially initialised module, as well as the altered list of
arguments. It is recommended that the @code{sys} module be left alone when
invoking this function from threaded code.


@subsubheading Voir aussi


The @ref{5cb,,-m} option offering equivalent functionality from the
command line.



Modifié dans la version 3.1: Added ability to execute packages by looking for a @ref{1,,__main__} submodule.



Modifié dans la version 3.2: Added @code{__cached__} global variable (see 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}).



Modifié dans la version 3.4: Updated to take advantage of the module spec feature added by
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}. This allows @code{__cached__} to be set correctly for modules
run this way, as well as ensuring the real module name is always
accessible as @code{__spec__.name}.



Modifié dans la version 3.12: The setting of @code{__cached__}, @code{__loader__}, and
@code{__package__} are deprecated. See
@ref{1ded,,ModuleSpec} for alternatives.

@end deffn

@geindex run_path() (dans le module runpy)
@anchor{library/runpy runpy run_path}@anchor{17f}
@deffn {Fonction} runpy.run_path (path_name, init_globals=None, run_name=None)

@geindex module;__main__

Execute the code at the named filesystem location and return the resulting
module's globals dictionary. As with a script name supplied to the CPython
command line, `file_path' may refer to a Python source file, a
compiled bytecode file or a valid @ref{3ab,,sys.path} entry containing a
@ref{1,,__main__} module
(e.g. a zipfile containing a top-level @code{__main__.py} file).

For a simple script, the specified code is simply executed in a fresh
module namespace. For a valid @ref{3ab,,sys.path} entry (typically a zipfile or
directory), the entry is first added to the beginning of @code{sys.path}. The
function then looks for and executes a @ref{1,,__main__} module using the
updated path. Note that there is no special protection against invoking
an existing @code{__main__} entry located elsewhere on @code{sys.path} if
there is no such module at the specified location.

The optional dictionary argument `init_globals' may be used to pre-populate
the module's globals dictionary before the code is executed.
`init_globals' will not be modified. If any of the special global variables
below are defined in `init_globals', those definitions are
overridden by @ref{17f,,run_path()}.

The special global variables @code{__name__}, @code{__spec__}, @code{__file__},
@code{__cached__}, @code{__loader__} and @code{__package__} are set in the globals
dictionary before the module code is executed. (Note that this is a
minimal set of variables - other variables may be set implicitly as an
interpreter implementation detail.)

@code{__name__} is set to `run_name' if this optional argument is not
@ref{660,,None} and to @code{'<run_path>'} otherwise.

If `file_path' directly references a script file (whether as source
or as precompiled byte code), then @code{__file__} will be set to
`file_path', and @code{__spec__}, @code{__cached__}, @code{__loader__} and
@code{__package__} will all be set to @ref{660,,None}.

If `file_path' is a reference to a valid @ref{3ab,,sys.path} entry, then
@code{__spec__} will be set appropriately for the imported @ref{1,,__main__}
module (that is, @code{__spec__.name} will always be @code{__main__}).
@code{__file__}, @code{__cached__}, @code{__loader__} and @code{__package__} will be
@ref{1e99,,set as normal} based on the module spec.

A number of alterations are also made to the @ref{d8,,sys} module. Firstly,
@ref{3ab,,sys.path} may be altered as described above. @code{sys.argv[0]} is updated
with the value of `file_path' and @code{sys.modules[__name__]} is updated
with a temporary module object for the module being executed. All
modifications to items in @ref{d8,,sys} are reverted before the function
returns.

Note that, unlike @ref{179a,,run_module()}, the alterations made to @ref{d8,,sys}
are not optional in this function as these adjustments are essential to
allowing the execution of @ref{3ab,,sys.path} entries. As the thread-safety
limitations still apply, use of this function in threaded code should be
either serialised with the import lock or delegated to a separate process.


@subsubheading Voir aussi


@ref{1cb5,,Options de l'interface} for equivalent functionality on the
command line (@code{python path/to/script}).



Ajouté dans la version 3.2.



Modifié dans la version 3.4: Updated to take advantage of the module spec feature added by
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}. This allows @code{__cached__} to be set correctly in the
case where @code{__main__} is imported from a valid @ref{3ab,,sys.path} entry rather
than being executed directly.



Modifié dans la version 3.12: The setting of @code{__cached__}, @code{__loader__}, and
@code{__package__} are deprecated.

@end deffn


@subsubheading Voir aussi



@table @asis

@geindex Python Enhancement Proposals; PEP 338

@item PEP 338@footnote{https://peps.python.org/pep-0338/} -- Exécuter des modules en tant que scripts

PEP written and implemented by Nick Coghlan.

@geindex Python Enhancement Proposals; PEP 366

@item PEP 366@footnote{https://peps.python.org/pep-0366/} -- Main module explicit relative imports

PEP written and implemented by Nick Coghlan.

@geindex Python Enhancement Proposals; PEP 451

@item PEP 451@footnote{https://peps.python.org/pep-0451/} -- A ModuleSpec Type for the Import System

PEP written and implemented by Eric Snow
@end table

@ref{194d,,Ligne de commande et environnement} - CPython command line details

The @ref{501,,importlib.import_module()} function


@node importlib --- The implementation of import,importlib resources -- Package resource reading opening and access,runpy --- Locating and executing Python modules,Importer des modules
@anchor{library/importlib doc}@anchor{4436}@anchor{library/importlib importlib-the-implementation-of-import}@anchor{4437}@anchor{library/importlib module-importlib}@anchor{76}
@subsection @code{importlib} --- The implementation of @code{import}


@geindex module; importlib


Ajouté dans la version 3.1.


`Source code:' Lib/importlib/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/__init__.py}


__________________________________________________________________


@menu
* Introduction: Introduction<11>. 
* Fonctions: Fonctions<12>. 
* importlib.abc: importlib abc -- Abstract base classes related to import. Abstract base classes related to import
* importlib.machinery: importlib machinery -- Importers and path hooks. Importers and path hooks
* importlib.util: importlib util -- Utility code for importers. Utility code for importers
* Exemples: Exemples<33>. 

@end menu

@node Introduction<11>,Fonctions<12>,,importlib --- The implementation of import
@anchor{library/importlib introduction}@anchor{4438}
@subsubsection Introduction


The purpose of the @ref{76,,importlib} package is three-fold.

One is to provide the
implementation of the @ref{5cc,,import} statement (and thus, by extension, the
@ref{8c1,,__import__()} function) in Python source code. This provides an
implementation of @code{import} which is portable to any Python
interpreter. This also provides an implementation which is easier to
comprehend than one implemented in a programming language other than Python.

Two, the components to implement @ref{5cc,,import} are exposed in this
package, making it easier for users to create their own custom objects (known
generically as an @ref{1f6c,,importer}) to participate in the import process.

Three, the package contains modules exposing additional functionality for
managing aspects of Python packages:


@itemize *

@item 
@ref{79,,importlib.metadata} presents access to metadata from third-party
distributions.

@item 
@ref{7a,,importlib.resources} provides routines for accessing non-code
"resources" from Python packages.
@end itemize


@subsubheading Voir aussi



@table @asis

@item @ref{5cc,,L'instruction import}

The language reference for the @ref{5cc,,import} statement.

@item Packages specification@footnote{https://www.python.org/doc/essays/packages/}

Original specification of packages. Some semantics have changed since
the writing of this document (e.g. redirecting based on @code{None}
in @ref{18f9,,sys.modules}).

@item La fonction @ref{1056,,__import__()}

The @ref{5cc,,import} statement is syntactic sugar for this function.

@item @ref{1bee,,The initialization of the sys.path module search path}

The initialization of @ref{3ab,,sys.path}.

@geindex Python Enhancement Proposals; PEP 235

@item PEP 235@footnote{https://peps.python.org/pep-0235/}

Import on Case-Insensitive Platforms

@geindex Python Enhancement Proposals; PEP 263

@item PEP 263@footnote{https://peps.python.org/pep-0263/}

Defining Python Source Code Encodings

@geindex Python Enhancement Proposals; PEP 302

@item PEP 302@footnote{https://peps.python.org/pep-0302/}

New Import Hooks

@geindex Python Enhancement Proposals; PEP 328

@item PEP 328@footnote{https://peps.python.org/pep-0328/}

Imports: Multi-Line and Absolute/Relative

@geindex Python Enhancement Proposals; PEP 366

@item PEP 366@footnote{https://peps.python.org/pep-0366/}

Main module explicit relative imports

@geindex Python Enhancement Proposals; PEP 420

@item PEP 420@footnote{https://peps.python.org/pep-0420/}

Implicit namespace packages

@geindex Python Enhancement Proposals; PEP 451

@item PEP 451@footnote{https://peps.python.org/pep-0451/}

A ModuleSpec Type for the Import System

@geindex Python Enhancement Proposals; PEP 488

@item PEP 488@footnote{https://peps.python.org/pep-0488/}

Elimination of PYO files

@geindex Python Enhancement Proposals; PEP 489

@item PEP 489@footnote{https://peps.python.org/pep-0489/}

Multi-phase extension module initialization

@geindex Python Enhancement Proposals; PEP 552

@item PEP 552@footnote{https://peps.python.org/pep-0552/}

Deterministic pycs

@geindex Python Enhancement Proposals; PEP 3120

@item PEP 3120@footnote{https://peps.python.org/pep-3120/}

Using UTF-8 as the Default Source Encoding

@geindex Python Enhancement Proposals; PEP 3147

@item PEP 3147@footnote{https://peps.python.org/pep-3147/}

PYC Repository Directories
@end table


@node Fonctions<12>,importlib abc -- Abstract base classes related to import,Introduction<11>,importlib --- The implementation of import
@anchor{library/importlib functions}@anchor{4439}
@subsubsection Fonctions


@geindex __import__() (dans le module importlib)
@anchor{library/importlib importlib __import__}@anchor{1056}
@deffn {Fonction} importlib.__import__ (name, globals=None, locals=None, fromlist=(), level=0)

An implementation of the built-in @ref{8c1,,__import__()} function.

@cartouche
@quotation Note 
Programmatic importing of modules should use @ref{501,,import_module()}
instead of this function.
@end quotation
@end cartouche
@end deffn

@geindex import_module() (dans le module importlib)
@anchor{library/importlib importlib import_module}@anchor{501}
@deffn {Fonction} importlib.import_module (name, package=None)

Import a module. The `name' argument specifies what module to
import in absolute or relative terms
(e.g. either @code{pkg.mod} or @code{..mod}). If the name is
specified in relative terms, then the `package' argument must be set to
the name of the package which is to act as the anchor for resolving the
package name (e.g. @code{import_module('..mod', 'pkg.subpkg')} will import
@code{pkg.mod}).

The @ref{501,,import_module()} function acts as a simplifying wrapper around
@ref{1056,,importlib.__import__()}. This means all semantics of the function are
derived from @ref{1056,,importlib.__import__()}. The most important difference
between these two functions is that @ref{501,,import_module()} returns the
specified package or module (e.g. @code{pkg.mod}), while @ref{8c1,,__import__()}
returns the top-level package or module (e.g. @code{pkg}).

If you are dynamically importing a module that was created since the
interpreter began execution (e.g., created a Python source file), you may
need to call @ref{bfe,,invalidate_caches()} in order for the new module to be
noticed by the import system.


Modifié dans la version 3.3: Parent packages are automatically imported.

@end deffn

@geindex invalidate_caches() (dans le module importlib)
@anchor{library/importlib importlib invalidate_caches}@anchor{bfe}
@deffn {Fonction} importlib.invalidate_caches ()

Invalidate the internal caches of finders stored at
@ref{d19,,sys.meta_path}. If a finder implements @code{invalidate_caches()} then it
will be called to perform the invalidation.  This function should be called
if any modules are created/installed while your program is running to
guarantee all finders will notice the new module's existence.


Ajouté dans la version 3.3.



Modifié dans la version 3.10: Namespace packages created/installed in a different @ref{3ab,,sys.path}
location after the same namespace was already imported are noticed.

@end deffn

@geindex reload() (dans le module importlib)
@anchor{library/importlib importlib reload}@anchor{502}
@deffn {Fonction} importlib.reload (module)

Reload a previously imported `module'.  The argument must be a module object,
so it must have been successfully imported before.  This is useful if you
have edited the module source file using an external editor and want to try
out the new version without leaving the Python interpreter.  The return value
is the module object (which can be different if re-importing causes a
different object to be placed in @ref{18f9,,sys.modules}).

When @ref{502,,reload()} is executed:


@itemize *

@item 
Python module's code is recompiled and the module-level code re-executed,
defining a new set of objects which are bound to names in the module's
dictionary by reusing the @ref{1639,,loader} which originally loaded the
module.  The @code{init} function of extension modules is not called a second
time.

@item 
As with all other objects in Python the old objects are only reclaimed
after their reference counts drop to zero.

@item 
The names in the module namespace are updated to point to any new or
changed objects.

@item 
Other references to the old objects (such as names external to the module) are
not rebound to refer to the new objects and must be updated in each namespace
where they occur if that is desired.
@end itemize

There are a number of other caveats:

When a module is reloaded, its dictionary (containing the module's global
variables) is retained.  Redefinitions of names will override the old
definitions, so this is generally not a problem.  If the new version of a
module does not define a name that was defined by the old version, the old
definition remains.  This feature can be used to the module's advantage if it
maintains a global table or cache of objects --- with a @ref{6d3,,try}
statement it can test for the table's presence and skip its initialization if
desired:

@example
try:
    cache
except NameError:
    cache = @{@}
@end example

It is generally not very useful to reload built-in or dynamically loaded
modules.  Reloading @ref{d8,,sys}, @ref{1,,__main__}, @ref{12,,builtins} and other
key modules is not recommended.  In many cases extension modules are not
designed to be initialized more than once, and may fail in arbitrary ways
when reloaded.

If a module imports objects from another module using @ref{1289,,from} ...
@ref{5cc,,import} ..., calling @ref{502,,reload()} for the other module does not
redefine the objects imported from it --- one way around this is to
re-execute the @code{from} statement, another is to use @code{import}
and qualified names (`module.name') instead.

If a module instantiates instances of a class, reloading the module that
defines the class does not affect the method definitions of the instances ---
they continue to use the old class definition.  The same is true for derived
classes.


Ajouté dans la version 3.4.



Modifié dans la version 3.7: @ref{b35,,ModuleNotFoundError} is raised when the module being reloaded lacks
a @ref{1ded,,ModuleSpec}.

@end deffn

@node importlib abc -- Abstract base classes related to import,importlib machinery -- Importers and path hooks,Fonctions<12>,importlib --- The implementation of import
@anchor{library/importlib importlib-abc-abstract-base-classes-related-to-import}@anchor{443a}@anchor{library/importlib module-importlib abc}@anchor{77}
@subsubsection @code{importlib.abc} -- Abstract base classes related to import


@geindex module; importlib.abc

`Source code:' Lib/importlib/abc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/abc.py}


__________________________________________________________________


The @ref{77,,importlib.abc} module contains all of the core abstract base classes
used by @ref{5cc,,import}. Some subclasses of the core abstract base classes
are also provided to help in implementing the core ABCs.

ABC hierarchy:

@example
object
 +-- MetaPathFinder
 +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader
@end example

@geindex MetaPathFinder (classe dans importlib.abc)
@anchor{library/importlib importlib abc MetaPathFinder}@anchor{859}
@deffn {Classe} importlib.abc.MetaPathFinder

An abstract base class representing a @ref{1059,,meta path finder}.


Ajouté dans la version 3.3.



Modifié dans la version 3.10: No longer a subclass of @code{Finder}.


@geindex find_spec() (méthode importlib.abc.MetaPathFinder)
@anchor{library/importlib importlib abc MetaPathFinder find_spec}@anchor{853}
@deffn {Méthode} find_spec (fullname, path, target=None)

An abstract method for finding a @ref{1e9b,,spec} for
the specified module.  If this is a top-level import, `path' will
be @code{None}.  Otherwise, this is a search for a subpackage or
module and `path' will be the value of @ref{1bfc,,__path__} from the
parent package. If a spec cannot be found, @code{None} is returned.
When passed in, @code{target} is a module object that the finder may
use to make a more educated guess about what spec to return.
@ref{858,,importlib.util.spec_from_loader()} may be useful for implementing
concrete @code{MetaPathFinders}.


Ajouté dans la version 3.4.

@end deffn

@geindex invalidate_caches() (méthode importlib.abc.MetaPathFinder)
@anchor{library/importlib importlib abc MetaPathFinder invalidate_caches}@anchor{443b}
@deffn {Méthode} invalidate_caches ()

An optional method which, when called, should invalidate any internal
cache used by the finder. Used by @ref{bfe,,importlib.invalidate_caches()}
when invalidating the caches of all finders on @ref{d19,,sys.meta_path}.


Modifié dans la version 3.4: Returns @code{None} when called instead of @ref{7bc,,NotImplemented}.

@end deffn
@end deffn

@geindex PathEntryFinder (classe dans importlib.abc)
@anchor{library/importlib importlib abc PathEntryFinder}@anchor{85a}
@deffn {Classe} importlib.abc.PathEntryFinder

An abstract base class representing a @ref{105a,,path entry finder}.  Though
it bears some similarities to @ref{859,,MetaPathFinder}, @code{PathEntryFinder}
is meant for use only within the path-based import subsystem provided
by @ref{100c,,importlib.machinery.PathFinder}.


Ajouté dans la version 3.3.



Modifié dans la version 3.10: No longer a subclass of @code{Finder}.


@geindex find_spec() (méthode importlib.abc.PathEntryFinder)
@anchor{library/importlib importlib abc PathEntryFinder find_spec}@anchor{857}
@deffn {Méthode} find_spec (fullname, target=None)

An abstract method for finding a @ref{1e9b,,spec} for
the specified module.  The finder will search for the module only
within the @ref{1f85,,path entry} to which it is assigned.  If a spec
cannot be found, @code{None} is returned.  When passed in, @code{target}
is a module object that the finder may use to make a more educated
guess about what spec to return. @ref{858,,importlib.util.spec_from_loader()}
may be useful for implementing concrete @code{PathEntryFinders}.


Ajouté dans la version 3.4.

@end deffn

@geindex invalidate_caches() (méthode importlib.abc.PathEntryFinder)
@anchor{library/importlib importlib abc PathEntryFinder invalidate_caches}@anchor{443c}
@deffn {Méthode} invalidate_caches ()

An optional method which, when called, should invalidate any internal
cache used by the finder. Used by
@ref{bfd,,importlib.machinery.PathFinder.invalidate_caches()}
when invalidating the caches of all cached finders.
@end deffn
@end deffn

@geindex Loader (classe dans importlib.abc)
@anchor{library/importlib importlib abc Loader}@anchor{eb0}
@deffn {Classe} importlib.abc.Loader

An abstract base class for a @ref{1639,,loader}.
See 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} for the exact definition for a loader.

Loaders that wish to support resource reading should implement a
@code{get_resource_reader()} method as specified by
@ref{443d,,importlib.resources.abc.ResourceReader}.


Modifié dans la version 3.7: Introduced the optional @code{get_resource_reader()} method.


@geindex create_module() (méthode importlib.abc.Loader)
@anchor{library/importlib importlib abc Loader create_module}@anchor{c9c}
@deffn {Méthode} create_module (spec)

A method that returns the module object to use when
importing a module.  This method may return @code{None},
indicating that default module creation semantics should take place.


Ajouté dans la version 3.4.



Modifié dans la version 3.6: This method is no longer optional when
@ref{855,,exec_module()} is defined.

@end deffn

@geindex exec_module() (méthode importlib.abc.Loader)
@anchor{library/importlib importlib abc Loader exec_module}@anchor{855}
@deffn {Méthode} exec_module (module)

An abstract method that executes the module in its own namespace
when a module is imported or reloaded.  The module should already
be initialized when @ref{855,,exec_module()} is called.  When this method exists,
@ref{c9c,,create_module()} must be defined.


Ajouté dans la version 3.4.



Modifié dans la version 3.6: @ref{c9c,,create_module()} must also be defined.

@end deffn

@geindex load_module() (méthode importlib.abc.Loader)
@anchor{library/importlib importlib abc Loader load_module}@anchor{854}
@deffn {Méthode} load_module (fullname)

A legacy method for loading a module.  If the module cannot be
loaded, @ref{40f,,ImportError} is raised, otherwise the loaded module is
returned.

If the requested module already exists in @ref{18f9,,sys.modules}, that
module should be used and reloaded.
Otherwise the loader should create a new module and insert it into
@ref{18f9,,sys.modules} before any loading begins, to prevent recursion
from the import.  If the loader inserted a module and the load fails, it
must be removed by the loader from @ref{18f9,,sys.modules}; modules already
in @ref{18f9,,sys.modules} before the loader began execution should be left
alone.

The loader should set several attributes on the module
(note that some of these attributes can change when a module is
reloaded):


@itemize -

@item 
@ref{135f,,module.__name__}

@item 
@ref{1ea2,,module.__file__}

@item 
@ref{2d4,,module.__cached__} `(deprecated)'

@item 
@ref{1bfc,,module.__path__}

@item 
@ref{2d6,,module.__package__} `(deprecated)'

@item 
@ref{2e0,,module.__loader__} `(deprecated)'
@end itemize

When @ref{855,,exec_module()} is available then backwards-compatible
functionality is provided.


Modifié dans la version 3.4: Raise @ref{40f,,ImportError} when called instead of
@ref{225,,NotImplementedError}.  Functionality provided when
@ref{855,,exec_module()} is available.



Obsolète depuis la version 3.4: The recommended API for loading a module is @ref{855,,exec_module()}
(and @ref{c9c,,create_module()}).  Loaders should implement it instead of
@ref{854,,load_module()}.  The import machinery takes care of all the
other responsibilities of @ref{854,,load_module()} when
@ref{855,,exec_module()} is implemented.

@end deffn
@end deffn

@geindex ResourceLoader (classe dans importlib.abc)
@anchor{library/importlib importlib abc ResourceLoader}@anchor{bd5}
@deffn {Classe} importlib.abc.ResourceLoader

An abstract base class for a @ref{1639,,loader} which implements the optional
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} protocol for loading arbitrary resources from the storage
back-end.


Obsolète depuis la version 3.7: This ABC is deprecated in favour of supporting resource loading
through @ref{443d,,importlib.resources.abc.ResourceReader}.


@geindex get_data() (méthode importlib.abc.ResourceLoader)
@anchor{library/importlib importlib abc ResourceLoader get_data}@anchor{4429}
@deffn {Méthode} abstractmethod get_data (path)

An abstract method to return the bytes for the data located at `path'.
Loaders that have a file-like storage back-end
that allows storing arbitrary data
can implement this abstract method to give direct access
to the data stored. @ref{40d,,OSError} is to be raised if the `path' cannot
be found. The `path' is expected to be constructed using a module's
@ref{1ea2,,__file__} attribute or an item from a package's
@ref{1bfc,,__path__}.


Modifié dans la version 3.4: Raises @ref{40d,,OSError} instead of @ref{225,,NotImplementedError}.

@end deffn
@end deffn

@geindex InspectLoader (classe dans importlib.abc)
@anchor{library/importlib importlib abc InspectLoader}@anchor{f3f}
@deffn {Classe} importlib.abc.InspectLoader

An abstract base class for a @ref{1639,,loader} which implements the optional
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} protocol for loaders that inspect modules.

@geindex get_code() (méthode importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader get_code}@anchor{f40}
@deffn {Méthode} get_code (fullname)

Return the code object for a module, or @code{None} if the module does not
have a code object (as would be the case, for example, for a built-in
module).  Raise an @ref{40f,,ImportError} if loader cannot find the
requested module.

@cartouche
@quotation Note 
While the method has a default implementation, it is suggested that
it be overridden if possible for performance.
@end quotation
@end cartouche

@geindex universal newlines;importlib.abc.InspectLoader.get_source method


Modifié dans la version 3.4: No longer abstract and a concrete implementation is provided.

@end deffn

@geindex get_source() (méthode importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader get_source}@anchor{f43}
@deffn {Méthode} abstractmethod get_source (fullname)

An abstract method to return the source of a module. It is returned as
a text string using @ref{d28,,universal newlines}, translating all
recognized line separators into @code{'\n'} characters.  Returns @code{None}
if no source is available (e.g. a built-in module). Raises
@ref{40f,,ImportError} if the loader cannot find the module specified.


Modifié dans la version 3.4: Raises @ref{40f,,ImportError} instead of @ref{225,,NotImplementedError}.

@end deffn

@geindex is_package() (méthode importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader is_package}@anchor{443e}
@deffn {Méthode} is_package (fullname)

An optional method to return a true value if the module is a package, a
false value otherwise. @ref{40f,,ImportError} is raised if the
@ref{1639,,loader} cannot find the module.


Modifié dans la version 3.4: Raises @ref{40f,,ImportError} instead of @ref{225,,NotImplementedError}.

@end deffn

@geindex source_to_code() (méthode statique importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader source_to_code}@anchor{dfe}
@deffn {Méthode} static source_to_code (data, path='<string>')

Create a code object from Python source.

The `data' argument can be whatever the @ref{190,,compile()} function
supports (i.e. string or bytes). The `path' argument should be
the "path" to where the source code originated from, which can be an
abstract concept (e.g. location in a zip file).

With the subsequent code object one can execute it in a module by
running @code{exec(code, module.__dict__)}.


Ajouté dans la version 3.4.



Modifié dans la version 3.5: Made the method static.

@end deffn

@geindex exec_module() (méthode importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader exec_module}@anchor{ffb}
@deffn {Méthode} exec_module (module)

Implementation of @ref{855,,Loader.exec_module()}.


Ajouté dans la version 3.4.

@end deffn

@geindex load_module() (méthode importlib.abc.InspectLoader)
@anchor{library/importlib importlib abc InspectLoader load_module}@anchor{443f}
@deffn {Méthode} load_module (fullname)

Implementation of @ref{854,,Loader.load_module()}.


Obsolète depuis la version 3.4: use @ref{ffb,,exec_module()} instead.

@end deffn
@end deffn

@geindex ExecutionLoader (classe dans importlib.abc)
@anchor{library/importlib importlib abc ExecutionLoader}@anchor{4440}
@deffn {Classe} importlib.abc.ExecutionLoader

An abstract base class which inherits from @ref{f3f,,InspectLoader} that,
when implemented, helps a module to be executed as a script. The ABC
represents an optional 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/} protocol.

@geindex get_filename() (méthode importlib.abc.ExecutionLoader)
@anchor{library/importlib importlib abc ExecutionLoader get_filename}@anchor{4441}
@deffn {Méthode} abstractmethod get_filename (fullname)

An abstract method that is to return the value of
@ref{1ea2,,__file__} for the specified module. If no path is
available, @ref{40f,,ImportError} is raised.

If source code is available, then the method should return the path to
the source file, regardless of whether a bytecode was used to load the
module.


Modifié dans la version 3.4: Raises @ref{40f,,ImportError} instead of @ref{225,,NotImplementedError}.

@end deffn
@end deffn

@geindex FileLoader (classe dans importlib.abc)
@anchor{library/importlib importlib abc FileLoader}@anchor{105c}
@deffn {Classe} importlib.abc.FileLoader (fullname, path)

An abstract base class which inherits from @ref{bd5,,ResourceLoader} and
@ref{4440,,ExecutionLoader}, providing concrete implementations of
@ref{4429,,ResourceLoader.get_data()} and @ref{4441,,ExecutionLoader.get_filename()}.

The `fullname' argument is a fully resolved name of the module the loader is
to handle. The `path' argument is the path to the file for the module.


Ajouté dans la version 3.3.


@geindex name (attribut importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader name}@anchor{4442}
@deffn {Attribut} name

The name of the module the loader can handle.
@end deffn

@geindex path (attribut importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader path}@anchor{4443}
@deffn {Attribut} path

Path to the file of the module.
@end deffn

@geindex load_module() (méthode importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader load_module}@anchor{4444}
@deffn {Méthode} load_module (fullname)

Calls super's @code{load_module()}.


Obsolète depuis la version 3.4: Use @ref{855,,Loader.exec_module()} instead.

@end deffn

@geindex get_filename() (méthode importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader get_filename}@anchor{4445}
@deffn {Méthode} abstractmethod get_filename (fullname)

Returns @ref{4443,,path}.
@end deffn

@geindex get_data() (méthode importlib.abc.FileLoader)
@anchor{library/importlib importlib abc FileLoader get_data}@anchor{4446}
@deffn {Méthode} abstractmethod get_data (path)

Reads `path' as a binary file and returns the bytes from it.
@end deffn
@end deffn

@geindex SourceLoader (classe dans importlib.abc)
@anchor{library/importlib importlib abc SourceLoader}@anchor{4447}
@deffn {Classe} importlib.abc.SourceLoader

An abstract base class for implementing source (and optionally bytecode)
file loading. The class inherits from both @ref{bd5,,ResourceLoader} and
@ref{4440,,ExecutionLoader}, requiring the implementation of:


@itemize *

@item 
@ref{4429,,ResourceLoader.get_data()}

@item 

@table @asis

@item @ref{4441,,ExecutionLoader.get_filename()}

Should only return the path to the source file; sourceless
loading is not supported.
@end table
@end itemize

The abstract methods defined by this class are to add optional bytecode
file support. Not implementing these optional methods (or causing them to
raise @ref{225,,NotImplementedError}) causes the loader to
only work with source code. Implementing the methods allows the loader to
work with source `and' bytecode files; it does not allow for `sourceless'
loading where only bytecode is provided.  Bytecode files are an
optimization to speed up loading by removing the parsing step of Python's
compiler, and so no bytecode-specific API is exposed.

@geindex path_stats() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader path_stats}@anchor{116a}
@deffn {Méthode} path_stats (path)

Optional abstract method which returns a @ref{253,,dict} containing
metadata about the specified path.  Supported dictionary keys are:


@itemize -

@item 
@code{'mtime'} (mandatory): an integer or floating-point number
representing the modification time of the source code;

@item 
@code{'size'} (optional): the size in bytes of the source code.
@end itemize

Any other keys in the dictionary are ignored, to allow for future
extensions. If the path cannot be handled, @ref{40d,,OSError} is raised.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: Raise @ref{40d,,OSError} instead of @ref{225,,NotImplementedError}.

@end deffn

@geindex path_mtime() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader path_mtime}@anchor{1169}
@deffn {Méthode} path_mtime (path)

Optional abstract method which returns the modification time for the
specified path.


Obsolète depuis la version 3.3: This method is deprecated in favour of @ref{116a,,path_stats()}.  You don't
have to implement it, but it is still available for compatibility
purposes. Raise @ref{40d,,OSError} if the path cannot be handled.



Modifié dans la version 3.4: Raise @ref{40d,,OSError} instead of @ref{225,,NotImplementedError}.

@end deffn

@geindex set_data() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader set_data}@anchor{4448}
@deffn {Méthode} set_data (path, data)

Optional abstract method which writes the specified bytes to a file
path. Any intermediate directories which do not exist are to be created
automatically.

When writing to the path fails because the path is read-only
(@ref{2234,,errno.EACCES}/@ref{d30,,PermissionError}), do not propagate the
exception.


Modifié dans la version 3.4: No longer raises @ref{225,,NotImplementedError} when called.

@end deffn

@geindex get_code() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader get_code}@anchor{4449}
@deffn {Méthode} get_code (fullname)

Concrete implementation of @ref{f40,,InspectLoader.get_code()}.
@end deffn

@geindex exec_module() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader exec_module}@anchor{ffc}
@deffn {Méthode} exec_module (module)

Concrete implementation of @ref{855,,Loader.exec_module()}.


Ajouté dans la version 3.4.

@end deffn

@geindex load_module() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader load_module}@anchor{444a}
@deffn {Méthode} load_module (fullname)

Concrete implementation of @ref{854,,Loader.load_module()}.


Obsolète depuis la version 3.4: utilisez plutôt @ref{ffc,,exec_module()}.

@end deffn

@geindex get_source() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader get_source}@anchor{100a}
@deffn {Méthode} get_source (fullname)

Concrete implementation of @ref{f43,,InspectLoader.get_source()}.
@end deffn

@geindex is_package() (méthode importlib.abc.SourceLoader)
@anchor{library/importlib importlib abc SourceLoader is_package}@anchor{444b}
@deffn {Méthode} is_package (fullname)

Concrete implementation of @ref{443e,,InspectLoader.is_package()}. A module
is determined to be a package if its file path (as provided by
@ref{4441,,ExecutionLoader.get_filename()}) is a file named
@code{__init__} when the file extension is removed `and' the module name
itself does not end in @code{__init__}.
@end deffn
@end deffn

@geindex ResourceReader (classe dans importlib.abc)
@anchor{library/importlib importlib abc ResourceReader}@anchor{aeb}
@deffn {Classe} importlib.abc.ResourceReader

`Superseded by TraversableResources'

An @ref{1193,,abstract base class} to provide the ability to read
`resources'.

From the perspective of this ABC, a `resource' is a binary
artifact that is shipped within a package. Typically this is
something like a data file that lives next to the @code{__init__.py}
file of the package. The purpose of this class is to help abstract
out the accessing of such data files so that it does not matter if
the package and its data file(s) are stored e.g. in a zip file
versus on the file system.

For any of methods of this class, a `resource' argument is
expected to be a @ref{29d,,path-like object} which represents
conceptually just a file name. This means that no subdirectory
paths should be included in the `resource' argument. This is
because the location of the package the reader is for, acts as the
"directory". Hence the metaphor for directories and file
names is packages and resources, respectively. This is also why
instances of this class are expected to directly correlate to
a specific package (instead of potentially representing multiple
packages or a module).

Loaders that wish to support resource reading are expected to
provide a method called @code{get_resource_reader(fullname)} which
returns an object implementing this ABC's interface. If the module
specified by fullname is not a package, this method should return
@ref{660,,None}. An object compatible with this ABC should only be
returned when the specified module is a package.


Ajouté dans la version 3.7.



Deprecated since version 3.12, will be removed in version 3.14: Use @ref{2c3,,importlib.resources.abc.TraversableResources} instead.


@geindex open_resource() (méthode importlib.abc.ResourceReader)
@anchor{library/importlib importlib abc ResourceReader open_resource}@anchor{444c}
@deffn {Méthode} abstractmethod open_resource (resource)

Returns an opened, @ref{250d,,file-like object} for binary reading
of the `resource'.

Si la ressource ne peut pas être trouvée, @ref{eae,,FileNotFoundError} est levée.
@end deffn

@geindex resource_path() (méthode importlib.abc.ResourceReader)
@anchor{library/importlib importlib abc ResourceReader resource_path}@anchor{444d}
@deffn {Méthode} abstractmethod resource_path (resource)

Renvoie le chemin de `resource' dans le système de fichiers.

If the resource does not concretely exist on the file system,
raise @ref{eae,,FileNotFoundError}.
@end deffn

@geindex is_resource() (méthode importlib.abc.ResourceReader)
@anchor{library/importlib importlib abc ResourceReader is_resource}@anchor{444e}
@deffn {Méthode} abstractmethod is_resource (name)

Returns @code{True} if the named `name' is considered a resource.
@ref{eae,,FileNotFoundError} is raised if `name' does not exist.
@end deffn

@geindex contents() (méthode importlib.abc.ResourceReader)
@anchor{library/importlib importlib abc ResourceReader contents}@anchor{19d2}
@deffn {Méthode} abstractmethod contents ()

Returns an @ref{1205,,iterable} of strings over the contents of
the package. Do note that it is not required that all names
returned by the iterator be actual resources, e.g. it is
acceptable to return names for which @ref{444e,,is_resource()} would
be false.

Allowing non-resource names to be returned is to allow for
situations where how a package and its resources are stored
are known a priori and the non-resource names would be useful.
For instance, returning subdirectory names is allowed so that
when it is known that the package and resources are stored on
the file system then those subdirectory names can be used
directly.

The abstract method returns an iterable of no items.
@end deffn
@end deffn

@geindex Traversable (classe dans importlib.abc)
@anchor{library/importlib importlib abc Traversable}@anchor{1812}
@deffn {Classe} importlib.abc.Traversable

An object with a subset of @ref{226,,pathlib.Path} methods suitable for
traversing directories and opening files.

For a representation of the object on the file-system, use
@ref{477,,importlib.resources.as_file()}.


Ajouté dans la version 3.9.



Deprecated since version 3.12, will be removed in version 3.14: Use @ref{1f0,,importlib.resources.abc.Traversable} instead.


@geindex name (attribut importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable name}@anchor{444f}
@deffn {Attribut} name

Abstract. The base name of this object without any parent references.
@end deffn

@geindex iterdir() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable iterdir}@anchor{4450}
@deffn {Méthode} abstractmethod iterdir ()

Yield @code{Traversable} objects in @code{self}.
@end deffn

@geindex is_dir() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable is_dir}@anchor{4451}
@deffn {Méthode} abstractmethod is_dir ()

Return @code{True} if @code{self} is a directory.
@end deffn

@geindex is_file() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable is_file}@anchor{4452}
@deffn {Méthode} abstractmethod is_file ()

Return @code{True} if @code{self} is a file.
@end deffn

@geindex joinpath() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable joinpath}@anchor{4453}
@deffn {Méthode} abstractmethod joinpath (child)

Return Traversable child in @code{self}.
@end deffn

@geindex __truediv__() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable __truediv__}@anchor{4454}
@deffn {Méthode} abstractmethod __truediv__ (child)

Return @code{Traversable} child in @code{self}.
@end deffn

@geindex open() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable open}@anchor{4455}
@deffn {Méthode} abstractmethod open (mode='r', *args, **kwargs)

`mode' may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as @ref{2744,,pathlib.Path.open}).

When opening as text, accepts encoding parameters such as those
accepted by @ref{7a5,,io.TextIOWrapper}.
@end deffn

@geindex read_bytes() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable read_bytes}@anchor{4456}
@deffn {Méthode} read_bytes ()

Read contents of @code{self} as bytes.
@end deffn

@geindex read_text() (méthode importlib.abc.Traversable)
@anchor{library/importlib importlib abc Traversable read_text}@anchor{4457}
@deffn {Méthode} read_text (encoding=None)

Read contents of @code{self} as text.
@end deffn
@end deffn

@geindex TraversableResources (classe dans importlib.abc)
@anchor{library/importlib importlib abc TraversableResources}@anchor{1810}
@deffn {Classe} importlib.abc.TraversableResources

An abstract base class for resource readers capable of serving
the @ref{478,,importlib.resources.files()} interface. Subclasses
@ref{443d,,importlib.resources.abc.ResourceReader} and provides
concrete implementations of the @ref{443d,,importlib.resources.abc.ResourceReader}'s
abstract methods. Therefore, any loader supplying
@ref{1810,,importlib.abc.TraversableResources} also supplies ResourceReader.

Loaders that wish to support resource reading are expected to
implement this interface.


Ajouté dans la version 3.9.



Deprecated since version 3.12, will be removed in version 3.14: Use @ref{2c3,,importlib.resources.abc.TraversableResources} instead.


@geindex files() (méthode importlib.abc.TraversableResources)
@anchor{library/importlib importlib abc TraversableResources files}@anchor{4458}
@deffn {Méthode} abstractmethod files ()

Returns a @ref{1f0,,importlib.resources.abc.Traversable} object for the loaded
package.
@end deffn
@end deffn

@node importlib machinery -- Importers and path hooks,importlib util -- Utility code for importers,importlib abc -- Abstract base classes related to import,importlib --- The implementation of import
@anchor{library/importlib importlib-machinery-importers-and-path-hooks}@anchor{4459}@anchor{library/importlib module-importlib machinery}@anchor{78}
@subsubsection @code{importlib.machinery} -- Importers and path hooks


@geindex module; importlib.machinery

`Source code:' Lib/importlib/machinery.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/machinery.py}


__________________________________________________________________


This module contains the various objects that help @ref{5cc,,import}
find and load modules.

@geindex SOURCE_SUFFIXES (dans le module importlib.machinery)
@anchor{library/importlib importlib machinery SOURCE_SUFFIXES}@anchor{4fd}
@deffn {Attribut} importlib.machinery.SOURCE_SUFFIXES

A list of strings representing the recognized file suffixes for source
modules.


Ajouté dans la version 3.3.

@end deffn

@geindex DEBUG_BYTECODE_SUFFIXES (dans le module importlib.machinery)
@anchor{library/importlib importlib machinery DEBUG_BYTECODE_SUFFIXES}@anchor{445a}
@deffn {Attribut} importlib.machinery.DEBUG_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for non-optimized bytecode
modules.


Ajouté dans la version 3.3.



Obsolète depuis la version 3.5: Use @ref{4ff,,BYTECODE_SUFFIXES} instead.

@end deffn

@geindex OPTIMIZED_BYTECODE_SUFFIXES (dans le module importlib.machinery)
@anchor{library/importlib importlib machinery OPTIMIZED_BYTECODE_SUFFIXES}@anchor{445b}
@deffn {Attribut} importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for optimized bytecode
modules.


Ajouté dans la version 3.3.



Obsolète depuis la version 3.5: Use @ref{4ff,,BYTECODE_SUFFIXES} instead.

@end deffn

@geindex BYTECODE_SUFFIXES (dans le module importlib.machinery)
@anchor{library/importlib importlib machinery BYTECODE_SUFFIXES}@anchor{4ff}
@deffn {Attribut} importlib.machinery.BYTECODE_SUFFIXES

A list of strings representing the recognized file suffixes for bytecode
modules (including the leading dot).


Ajouté dans la version 3.3.



Modifié dans la version 3.5: The value is no longer dependent on @code{__debug__}.

@end deffn

@geindex EXTENSION_SUFFIXES (dans le module importlib.machinery)
@anchor{library/importlib importlib machinery EXTENSION_SUFFIXES}@anchor{4fe}
@deffn {Attribut} importlib.machinery.EXTENSION_SUFFIXES

A list of strings representing the recognized file suffixes for
extension modules.


Ajouté dans la version 3.3.

@end deffn

@geindex all_suffixes() (dans le module importlib.machinery)
@anchor{library/importlib importlib machinery all_suffixes}@anchor{4397}
@deffn {Fonction} importlib.machinery.all_suffixes ()

Returns a combined list of strings representing all file suffixes for
modules recognized by the standard import machinery. This is a
helper for code which simply needs to know if a filesystem path
potentially refers to a module without needing any details on the kind
of module (for example, @ref{d27,,inspect.getmodulename()}).


Ajouté dans la version 3.3.

@end deffn

@geindex BuiltinImporter (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery BuiltinImporter}@anchor{c9d}
@deffn {Classe} importlib.machinery.BuiltinImporter

An @ref{1f6c,,importer} for built-in modules. All known built-in modules are
listed in @ref{1bed,,sys.builtin_module_names}. This class implements the
@ref{859,,importlib.abc.MetaPathFinder} and
@ref{f3f,,importlib.abc.InspectLoader} ABCs.

Only class methods are defined by this class to alleviate the need for
instantiation.


Modifié dans la version 3.5: As part of 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}, the builtin importer now implements
@code{Loader.create_module()} and @code{Loader.exec_module()}

@end deffn

@geindex FrozenImporter (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery FrozenImporter}@anchor{1008}
@deffn {Classe} importlib.machinery.FrozenImporter

An @ref{1f6c,,importer} for frozen modules. This class implements the
@ref{859,,importlib.abc.MetaPathFinder} and
@ref{f3f,,importlib.abc.InspectLoader} ABCs.

Only class methods are defined by this class to alleviate the need for
instantiation.


Modifié dans la version 3.4: Gained @code{create_module()} and @code{exec_module()}
methods.

@end deffn

@geindex WindowsRegistryFinder (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery WindowsRegistryFinder}@anchor{d18}
@deffn {Classe} importlib.machinery.WindowsRegistryFinder

@ref{1ea3,,Finder} for modules declared in the Windows registry.  This class
implements the @ref{859,,importlib.abc.MetaPathFinder} ABC.

Only class methods are defined by this class to alleviate the need for
instantiation.


Ajouté dans la version 3.3.



Obsolète depuis la version 3.6: Use @ref{c6,,site} configuration instead. Future versions of Python may
not enable this finder by default.

@end deffn

@geindex PathFinder (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery PathFinder}@anchor{100c}
@deffn {Classe} importlib.machinery.PathFinder

A @ref{1ea3,,Finder} for @ref{3ab,,sys.path} and package @code{__path__} attributes.
This class implements the @ref{859,,importlib.abc.MetaPathFinder} ABC.

Only class methods are defined by this class to alleviate the need for
instantiation.

@geindex find_spec() (méthode de la classe importlib.machinery.PathFinder)
@anchor{library/importlib importlib machinery PathFinder find_spec}@anchor{ffa}
@deffn {Méthode} classmethod find_spec (fullname, path=None, target=None)

Class method that attempts to find a @ref{1e9b,,spec}
for the module specified by `fullname' on @ref{3ab,,sys.path} or, if
defined, on `path'. For each path entry that is searched,
@ref{5ce,,sys.path_importer_cache} is checked. If a non-false object
is found then it is used as the @ref{105a,,path entry finder} to look
for the module being searched for. If no entry is found in
@ref{5ce,,sys.path_importer_cache}, then @ref{100d,,sys.path_hooks} is
searched for a finder for the path entry and, if found, is stored
in @ref{5ce,,sys.path_importer_cache} along with being queried about
the module. If no finder is ever found then @code{None} is both
stored in the cache and returned.


Ajouté dans la version 3.4.



Modifié dans la version 3.5: If the current working directory -- represented by an empty string --
is no longer valid then @code{None} is returned but no value is cached
in @ref{5ce,,sys.path_importer_cache}.

@end deffn

@geindex invalidate_caches() (méthode de la classe importlib.machinery.PathFinder)
@anchor{library/importlib importlib machinery PathFinder invalidate_caches}@anchor{bfd}
@deffn {Méthode} classmethod invalidate_caches ()

Calls @ref{443c,,importlib.abc.PathEntryFinder.invalidate_caches()} on all
finders stored in @ref{5ce,,sys.path_importer_cache} that define the method.
Otherwise entries in @ref{5ce,,sys.path_importer_cache} set to @code{None} are
deleted.


Modifié dans la version 3.7: Entries of @code{None} in @ref{5ce,,sys.path_importer_cache} are deleted.

@end deffn


Modifié dans la version 3.4: Calls objects in @ref{100d,,sys.path_hooks} with the current working
directory for @code{'@w{'}} (i.e. the empty string).

@end deffn

@geindex FileFinder (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery FileFinder}@anchor{105b}
@deffn {Classe} importlib.machinery.FileFinder (path, *loader_details)

A concrete implementation of @ref{85a,,importlib.abc.PathEntryFinder} which
caches results from the file system.

The `path' argument is the directory for which the finder is in charge of
searching.

The `loader_details' argument is a variable number of 2-item tuples each
containing a loader and a sequence of file suffixes the loader recognizes.
The loaders are expected to be callables which accept two arguments of
the module's name and the path to the file found.

The finder will cache the directory contents as necessary, making stat calls
for each module search to verify the cache is not outdated. Because cache
staleness relies upon the granularity of the operating system's state
information of the file system, there is a potential race condition of
searching for a module, creating a new file, and then searching for the
module the new file represents. If the operations happen fast enough to fit
within the granularity of stat calls, then the module search will fail. To
prevent this from happening, when you create a module dynamically, make sure
to call @ref{bfe,,importlib.invalidate_caches()}.


Ajouté dans la version 3.3.


@geindex path (attribut importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder path}@anchor{445c}
@deffn {Attribut} path

The path the finder will search in.
@end deffn

@geindex find_spec() (méthode importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder find_spec}@anchor{eaf}
@deffn {Méthode} find_spec (fullname, target=None)

Attempt to find the spec to handle `fullname' within @ref{445c,,path}.


Ajouté dans la version 3.4.

@end deffn

@geindex invalidate_caches() (méthode importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder invalidate_caches}@anchor{445d}
@deffn {Méthode} invalidate_caches ()

Clear out the internal cache.
@end deffn

@geindex path_hook() (méthode de la classe importlib.machinery.FileFinder)
@anchor{library/importlib importlib machinery FileFinder path_hook}@anchor{445e}
@deffn {Méthode} classmethod path_hook (*loader_details)

A class method which returns a closure for use on @ref{100d,,sys.path_hooks}.
An instance of @ref{105b,,FileFinder} is returned by the closure using the
path argument given to the closure directly and `loader_details'
indirectly.

If the argument to the closure is not an existing directory,
@ref{40f,,ImportError} is raised.
@end deffn
@end deffn

@geindex SourceFileLoader (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery SourceFileLoader}@anchor{105d}
@deffn {Classe} importlib.machinery.SourceFileLoader (fullname, path)

A concrete implementation of @ref{4447,,importlib.abc.SourceLoader} by
subclassing @ref{105c,,importlib.abc.FileLoader} and providing some concrete
implementations of other methods.


Ajouté dans la version 3.3.


@geindex name (attribut importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader name}@anchor{445f}
@deffn {Attribut} name

The name of the module that this loader will handle.
@end deffn

@geindex path (attribut importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader path}@anchor{4460}
@deffn {Attribut} path

The path to the source file.
@end deffn

@geindex is_package() (méthode importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader is_package}@anchor{4461}
@deffn {Méthode} is_package (fullname)

Return @code{True} if @ref{4460,,path} appears to be for a package.
@end deffn

@geindex path_stats() (méthode importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader path_stats}@anchor{4462}
@deffn {Méthode} path_stats (path)

Concrete implementation of @ref{116a,,importlib.abc.SourceLoader.path_stats()}.
@end deffn

@geindex set_data() (méthode importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader set_data}@anchor{4463}
@deffn {Méthode} set_data (path, data)

Concrete implementation of @ref{4448,,importlib.abc.SourceLoader.set_data()}.
@end deffn

@geindex load_module() (méthode importlib.machinery.SourceFileLoader)
@anchor{library/importlib importlib machinery SourceFileLoader load_module}@anchor{d16}
@deffn {Méthode} load_module (name=None)

Concrete implementation of @ref{854,,importlib.abc.Loader.load_module()} where
specifying the name of the module to load is optional.


Obsolète depuis la version 3.6: Use @ref{855,,importlib.abc.Loader.exec_module()} instead.

@end deffn
@end deffn

@geindex SourcelessFileLoader (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery SourcelessFileLoader}@anchor{105e}
@deffn {Classe} importlib.machinery.SourcelessFileLoader (fullname, path)

A concrete implementation of @ref{105c,,importlib.abc.FileLoader} which can
import bytecode files (i.e. no source code files exist).

Please note that direct use of bytecode files (and thus not source code
files) inhibits your modules from being usable by all Python
implementations or new versions of Python which change the bytecode
format.


Ajouté dans la version 3.3.


@geindex name (attribut importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader name}@anchor{4464}
@deffn {Attribut} name

The name of the module the loader will handle.
@end deffn

@geindex path (attribut importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader path}@anchor{4465}
@deffn {Attribut} path

The path to the bytecode file.
@end deffn

@geindex is_package() (méthode importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader is_package}@anchor{4466}
@deffn {Méthode} is_package (fullname)

Determines if the module is a package based on @ref{4465,,path}.
@end deffn

@geindex get_code() (méthode importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader get_code}@anchor{4467}
@deffn {Méthode} get_code (fullname)

Returns the code object for @ref{4464,,name} created from @ref{4465,,path}.
@end deffn

@geindex get_source() (méthode importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader get_source}@anchor{4468}
@deffn {Méthode} get_source (fullname)

Returns @code{None} as bytecode files have no source when this loader is
used.
@end deffn

@geindex load_module() (méthode importlib.machinery.SourcelessFileLoader)
@anchor{library/importlib importlib machinery SourcelessFileLoader load_module}@anchor{d17}
@deffn {Méthode} load_module (name=None)
@end deffn

Concrete implementation of @ref{854,,importlib.abc.Loader.load_module()} where
specifying the name of the module to load is optional.


Obsolète depuis la version 3.6: Use @ref{855,,importlib.abc.Loader.exec_module()} instead.

@end deffn

@geindex ExtensionFileLoader (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery ExtensionFileLoader}@anchor{c9e}
@deffn {Classe} importlib.machinery.ExtensionFileLoader (fullname, path)

A concrete implementation of @ref{4440,,importlib.abc.ExecutionLoader} for
extension modules.

The `fullname' argument specifies the name of the module the loader is to
support. The `path' argument is the path to the extension module's file.

Note that, by default, importing an extension module will fail
in subinterpreters if it doesn't implement multi-phase init
(see 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}), even if it would otherwise import successfully.


Ajouté dans la version 3.3.



Modifié dans la version 3.12: Multi-phase init is now required for use in subinterpreters.


@geindex name (attribut importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader name}@anchor{4469}
@deffn {Attribut} name

Name of the module the loader supports.
@end deffn

@geindex path (attribut importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader path}@anchor{446a}
@deffn {Attribut} path

Path to the extension module.
@end deffn

@geindex create_module() (méthode importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader create_module}@anchor{446b}
@deffn {Méthode} create_module (spec)

Creates the module object from the given specification in accordance
with 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}.


Ajouté dans la version 3.5.

@end deffn

@geindex exec_module() (méthode importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader exec_module}@anchor{446c}
@deffn {Méthode} exec_module (module)

Initializes the given module object in accordance with 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}.


Ajouté dans la version 3.5.

@end deffn

@geindex is_package() (méthode importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader is_package}@anchor{446d}
@deffn {Méthode} is_package (fullname)

Returns @code{True} if the file path points to a package's @code{__init__}
module based on @ref{4fe,,EXTENSION_SUFFIXES}.
@end deffn

@geindex get_code() (méthode importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_code}@anchor{446e}
@deffn {Méthode} get_code (fullname)

Returns @code{None} as extension modules lack a code object.
@end deffn

@geindex get_source() (méthode importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_source}@anchor{446f}
@deffn {Méthode} get_source (fullname)

Returns @code{None} as extension modules do not have source code.
@end deffn

@geindex get_filename() (méthode importlib.machinery.ExtensionFileLoader)
@anchor{library/importlib importlib machinery ExtensionFileLoader get_filename}@anchor{f44}
@deffn {Méthode} get_filename (fullname)

Returns @ref{446a,,path}.


Ajouté dans la version 3.4.

@end deffn
@end deffn

@geindex NamespaceLoader (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery NamespaceLoader}@anchor{f41}
@deffn {Classe} importlib.machinery.NamespaceLoader (name, path, path_finder)

A concrete implementation of @ref{f3f,,importlib.abc.InspectLoader} for
namespace packages.  This is an alias for a private class and is only made
public for introspecting the @code{__loader__} attribute on namespace
packages:

@example
>>> from importlib.machinery import NamespaceLoader
>>> import my_namespace
>>> isinstance(my_namespace.__loader__, NamespaceLoader)
True
>>> import importlib.abc
>>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
True
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex ModuleSpec (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery ModuleSpec}@anchor{1ded}
@deffn {Classe} importlib.machinery.ModuleSpec (name, loader, *, origin=None, loader_state=None, is_package=None)

A specification for a module's import-system-related state.  This is
typically exposed as the module's @ref{1e9c,,__spec__} attribute.  Many
of these attributes are also available directly on a module: for example,
@code{module.__spec__.origin == module.__file__}.  Note, however, that
while the `values' are usually equivalent, they can differ since there is
no synchronization between the two objects.  For example, it is possible to
update the module's @ref{1ea2,,__file__} at runtime and this will not be
automatically reflected in the module's
@ref{4470,,__spec__.origin}, and vice versa.


Ajouté dans la version 3.4.


@geindex name (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec name}@anchor{1e9d}
@deffn {Attribut} name

The module's fully qualified name (see @ref{135f,,module.__name__}).
The @ref{1ea3,,finder} should always set this attribute to a non-empty string.
@end deffn

@geindex loader (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec loader}@anchor{2e1}
@deffn {Attribut} loader

The @ref{1639,,loader} used to load the module (see @ref{2e0,,module.__loader__}).
The @ref{1ea3,,finder} should always set this attribute.
@end deffn

@geindex origin (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec origin}@anchor{4470}
@deffn {Attribut} origin

The location the @ref{1639,,loader} should use to load the module
(see @ref{1ea2,,module.__file__}).
For example, for modules loaded from a @code{.py} file this is the filename.
The @ref{1ea3,,finder} should always set this attribute to a meaningful value
for the @ref{1639,,loader} to use.  In the uncommon case that there is not one
(like for namespace packages), it should be set to @code{None}.
@end deffn

@geindex submodule_search_locations (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec submodule_search_locations}@anchor{1ea1}
@deffn {Attribut} submodule_search_locations

A (possibly empty) @ref{4db,,sequence} of strings enumerating the locations
in which a package's submodules will be found
(see @ref{1bfc,,module.__path__}). Most of the time there will only be a
single directory in this list.

The @ref{1ea3,,finder} should set this attribute to a sequence, even an empty
one, to indicate
to the import system that the module is a package.  It should be set to @code{None} for
non-package modules.  It is set automatically later to a special object for
namespace packages.
@end deffn

@geindex loader_state (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec loader_state}@anchor{4471}
@deffn {Attribut} loader_state

The @ref{1ea3,,finder} may set this attribute to an object containing additional,
module-specific data to use when loading the module.  Otherwise it should be
set to @code{None}.
@end deffn

@geindex cached (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec cached}@anchor{2d5}
@deffn {Attribut} cached

The filename of a compiled version of the module's code
(see @ref{2d4,,module.__cached__}).
The @ref{1ea3,,finder} should always set this attribute but it may be @code{None}
for modules that do not need compiled code stored.
@end deffn

@geindex parent (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec parent}@anchor{2d7}
@deffn {Attribut} parent

(Read-only) The fully qualified name of the package the module is in (or the
empty string for a top-level module).
See @ref{2d6,,module.__package__}.
If the module is a package then this is the same as @ref{1e9d,,name}.
@end deffn

@geindex has_location (attribut importlib.machinery.ModuleSpec)
@anchor{library/importlib importlib machinery ModuleSpec has_location}@anchor{4472}
@deffn {Attribut} has_location

@code{True} if the spec's @ref{4470,,origin} refers to a loadable location,
@code{False} otherwise.  This value impacts how @code{origin} is interpreted
and how the module's @ref{1ea2,,__file__} is populated.
@end deffn
@end deffn

@geindex AppleFrameworkLoader (classe dans importlib.machinery)
@anchor{library/importlib importlib machinery AppleFrameworkLoader}@anchor{1dec}
@deffn {Classe} importlib.machinery.AppleFrameworkLoader (name, path)

A specialization of @ref{c9e,,importlib.machinery.ExtensionFileLoader} that
is able to load extension modules in Framework format.

For compatibility with the iOS App Store, `all' binary modules in an iOS app
must be dynamic libraries, contained in a framework with appropriate
metadata, stored in the @code{Frameworks} folder of the packaged app. There can
be only a single binary per framework, and there can be no executable binary
material outside the Frameworks folder.

To accommodate this requirement, when running on iOS, extension module
binaries are `not' packaged as @code{.so} files on @code{sys.path}, but as
individual standalone frameworks. To discover those frameworks, this loader
is be registered against the @code{.fwork} file extension, with a @code{.fwork}
file acting as a placeholder in the original location of the binary on
@code{sys.path}. The @code{.fwork} file contains the path of the actual binary in
the @code{Frameworks} folder, relative to the app bundle. To allow for
resolving a framework-packaged binary back to the original location, the
framework is expected to contain a @code{.origin} file that contains the
location of the @code{.fwork} file, relative to the app bundle.

For example, consider the case of an import @code{from foo.bar import _whiz},
where @code{_whiz} is implemented with the binary module
@code{sources/foo/bar/_whiz.abi3.so}, with @code{sources} being the location
registered on @code{sys.path}, relative to the application bundle. This module
`must' be distributed as
@code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz} (creating the framework
name from the full import path of the module), with an @code{Info.plist} file
in the @code{.framework} directory identifying the binary as a framework. The
@code{foo.bar._whiz} module would be represented in the original location with
a @code{sources/foo/bar/_whiz.abi3.fwork} marker file, containing the path
@code{Frameworks/foo.bar._whiz/foo.bar._whiz}. The framework would also contain
@code{Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin}, containing the
path to the @code{.fwork} file.

When a module is loaded with this loader, the @code{__file__} for the module
will report as the location of the @code{.fwork} file. This allows code to use
the @code{__file__} of a  module as an anchor for file system traveral.
However, the spec origin will reference the location of the `actual' binary
in the @code{.framework} folder.

The Xcode project building the app is responsible for converting any @code{.so}
files from wherever they exist in the @code{PYTHONPATH} into frameworks in the
@code{Frameworks} folder (including stripping extensions from the module file,
the addition of framework metadata, and signing the resulting framework),
and creating the @code{.fwork} and @code{.origin} files. This will usually be done
with a build step in the Xcode project; see the iOS documentation for
details on how to construct this build step.


Ajouté dans la version 3.13.


@ref{1ce0,,Availability}: iOS.

@geindex name (attribut importlib.machinery.AppleFrameworkLoader)
@anchor{library/importlib importlib machinery AppleFrameworkLoader name}@anchor{4473}
@deffn {Attribut} name

Name of the module the loader supports.
@end deffn

@geindex path (attribut importlib.machinery.AppleFrameworkLoader)
@anchor{library/importlib importlib machinery AppleFrameworkLoader path}@anchor{4474}
@deffn {Attribut} path

Path to the @code{.fwork} file for the extension module.
@end deffn
@end deffn

@node importlib util -- Utility code for importers,Exemples<33>,importlib machinery -- Importers and path hooks,importlib --- The implementation of import
@anchor{library/importlib importlib-util-utility-code-for-importers}@anchor{4475}@anchor{library/importlib module-importlib util}@anchor{7c}
@subsubsection @code{importlib.util} -- Utility code for importers


@geindex module; importlib.util

`Source code:' Lib/importlib/util.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/util.py}


__________________________________________________________________


This module contains the various objects that help in the construction of
an @ref{1f6c,,importer}.

@geindex MAGIC_NUMBER (dans le module importlib.util)
@anchor{library/importlib importlib util MAGIC_NUMBER}@anchor{4fc}
@deffn {Attribut} importlib.util.MAGIC_NUMBER

The bytes which represent the bytecode version number. If you need help with
loading/writing bytecode then consider @ref{4447,,importlib.abc.SourceLoader}.


Ajouté dans la version 3.4.

@end deffn

@geindex cache_from_source() (dans le module importlib.util)
@anchor{library/importlib importlib util cache_from_source}@anchor{2f2}
@deffn {Fonction} importlib.util.cache_from_source (path, debug_override=None, *, optimization=None)

Return the 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}/
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} path to the byte-compiled file associated
with the source `path'.  For example, if `path' is @code{/foo/bar/baz.py} the return
value would be @code{/foo/bar/__pycache__/baz.cpython-32.pyc} for Python 3.2.
The @code{cpython-32} string comes from the current magic tag (see
@code{get_tag()}; if @code{sys.implementation.cache_tag} is not defined then
@ref{225,,NotImplementedError} will be raised).

The `optimization' parameter is used to specify the optimization level of the
bytecode file. An empty string represents no optimization, so
@code{/foo/bar/baz.py} with an `optimization' of @code{'@w{'}} will result in a
bytecode path of @code{/foo/bar/__pycache__/baz.cpython-32.pyc}. @code{None} causes
the interpreter's optimization level to be used. Any other value's string
representation is used, so @code{/foo/bar/baz.py} with an `optimization' of
@code{2} will lead to the bytecode path of
@code{/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc}. The string representation
of `optimization' can only be alphanumeric, else @ref{1ff,,ValueError} is raised.

The `debug_override' parameter is deprecated and can be used to override
the system's value for @code{__debug__}. A @code{True} value is the equivalent of
setting `optimization' to the empty string. A @code{False} value is the same as
setting `optimization' to @code{1}. If both `debug_override' an `optimization'
are not @code{None} then @ref{522,,TypeError} is raised.


Ajouté dans la version 3.4.



Modifié dans la version 3.5: The `optimization' parameter was added and the `debug_override' parameter
was deprecated.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex source_from_cache() (dans le module importlib.util)
@anchor{library/importlib importlib util source_from_cache}@anchor{503}
@deffn {Fonction} importlib.util.source_from_cache (path)

Given the `path' to a 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} file name, return the associated source code
file path.  For example, if `path' is
@code{/foo/bar/__pycache__/baz.cpython-32.pyc} the returned path would be
@code{/foo/bar/baz.py}.  `path' need not exist, however if it does not conform
to 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} or 
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} format, a @ref{1ff,,ValueError} is raised. If
@code{sys.implementation.cache_tag} is not defined,
@ref{225,,NotImplementedError} is raised.


Ajouté dans la version 3.4.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex decode_source() (dans le module importlib.util)
@anchor{library/importlib importlib util decode_source}@anchor{f42}
@deffn {Fonction} importlib.util.decode_source (source_bytes)

Decode the given bytes representing source code and return it as a string
with universal newlines (as required by
@ref{f43,,importlib.abc.InspectLoader.get_source()}).


Ajouté dans la version 3.4.

@end deffn

@geindex resolve_name() (dans le module importlib.util)
@anchor{library/importlib importlib util resolve_name}@anchor{8f7}
@deffn {Fonction} importlib.util.resolve_name (name, package)

Resolve a relative module name to an absolute one.

If  `name' has no leading dots, then `name' is simply returned. This
allows for usage such as
@code{importlib.util.resolve_name('sys', __spec__.parent)} without doing a
check to see if the `package' argument is needed.

@ref{40f,,ImportError} is raised if `name' is a relative module name but
`package' is a false value (e.g. @code{None} or the empty string).
@ref{40f,,ImportError} is also raised if a relative name would escape its
containing package (e.g. requesting @code{..bacon} from within the @code{spam}
package).


Ajouté dans la version 3.3.



Modifié dans la version 3.9: To improve consistency with import statements, raise
@ref{40f,,ImportError} instead of @ref{1ff,,ValueError} for invalid relative
import attempts.

@end deffn

@geindex find_spec() (dans le module importlib.util)
@anchor{library/importlib importlib util find_spec}@anchor{2cb}
@deffn {Fonction} importlib.util.find_spec (name, package=None)

Find the @ref{1e9b,,spec} for a module, optionally relative to
the specified `package' name. If the module is in @ref{18f9,,sys.modules},
then @code{sys.modules[name].__spec__} is returned (unless the spec would be
@code{None} or is not set, in which case @ref{1ff,,ValueError} is raised).
Otherwise a search using @ref{d19,,sys.meta_path} is done. @code{None} is
returned if no spec is found.

If `name' is for a submodule (contains a dot), the parent module is
automatically imported.

`name' and `package' work the same as for @code{import_module()}.


Ajouté dans la version 3.4.



Modifié dans la version 3.7: Raises @ref{b35,,ModuleNotFoundError} instead of @ref{343,,AttributeError} if
`package' is in fact not a package (i.e. lacks a
@ref{1bfc,,__path__} attribute).

@end deffn

@geindex module_from_spec() (dans le module importlib.util)
@anchor{library/importlib importlib util module_from_spec}@anchor{dff}
@deffn {Fonction} importlib.util.module_from_spec (spec)

Create a new module based on `spec' and
@ref{c9c,,spec.loader.create_module}.

If @ref{c9c,,spec.loader.create_module}
does not return @code{None}, then any pre-existing attributes will not be reset.
Also, no @ref{343,,AttributeError} will be raised if triggered while accessing
`spec' or setting an attribute on the module.

This function is preferred over using @ref{e00,,types.ModuleType} to create a
new module as `spec' is used to set as many import-controlled attributes on
the module as possible.


Ajouté dans la version 3.5.

@end deffn

@geindex spec_from_loader() (dans le module importlib.util)
@anchor{library/importlib importlib util spec_from_loader}@anchor{858}
@deffn {Fonction} importlib.util.spec_from_loader (name, loader, *, origin=None, is_package=None)

A factory function for creating a @ref{1ded,,ModuleSpec}
instance based on a loader.  The parameters have the same meaning as they do
for ModuleSpec.  The function uses available @ref{1639,,loader} APIs, such as
@code{InspectLoader.is_package()}, to fill in any missing
information on the spec.


Ajouté dans la version 3.4.

@end deffn

@geindex spec_from_file_location() (dans le module importlib.util)
@anchor{library/importlib importlib util spec_from_file_location}@anchor{c9f}
@deffn {Fonction} importlib.util.spec_from_file_location (name, location, *, loader=None, submodule_search_locations=None)

A factory function for creating a @ref{1ded,,ModuleSpec}
instance based on the path to a file.  Missing information will be filled in
on the spec by making use of loader APIs and by the implication that the
module will be file-based.


Ajouté dans la version 3.4.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex source_hash() (dans le module importlib.util)
@anchor{library/importlib importlib util source_hash}@anchor{4476}
@deffn {Fonction} importlib.util.source_hash (source_bytes)

Return the hash of `source_bytes' as bytes. A hash-based @code{.pyc} file embeds
the @ref{4476,,source_hash()} of the corresponding source file's contents in its
header.


Ajouté dans la version 3.7.

@end deffn

@geindex _incompatible_extension_module_restrictions() (dans le module importlib.util)
@anchor{library/importlib importlib util _incompatible_extension_module_restrictions}@anchor{4477}
@deffn {Fonction} importlib.util._incompatible_extension_module_restrictions (*, disable_check)

A context manager that can temporarily skip the compatibility check
for extension modules.  By default the check is enabled and will fail
when a single-phase init module is imported in a subinterpreter.
It will also fail for a multi-phase init module that doesn't
explicitly support a per-interpreter GIL, when imported
in an interpreter with its own GIL.

Note that this function is meant to accommodate an unusual case;
one which is likely to eventually go away.  There's is a pretty good
chance this is not what you were looking for.

You can get the same effect as this function by implementing the
basic interface of multi-phase init (
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}) and lying about
support for multiple interpreters (or per-interpreter GIL).

@cartouche
@quotation Avertissement 
Using this function to disable the check can lead to
unexpected behavior and even crashes.  It should only be used during
extension module development.
@end quotation
@end cartouche


Ajouté dans la version 3.12.

@end deffn

@geindex LazyLoader (classe dans importlib.util)
@anchor{library/importlib importlib util LazyLoader}@anchor{c9b}
@deffn {Classe} importlib.util.LazyLoader (loader)

A class which postpones the execution of the loader of a module until the
module has an attribute accessed.

This class `only' works with loaders that define
@ref{855,,exec_module()} as control over what module type
is used for the module is required. For those same reasons, the loader's
@ref{c9c,,create_module()} method must return @code{None} or a
type for which its @code{__class__} attribute can be mutated along with not
using @ref{5c9,,slots}. Finally, modules which substitute the object
placed into @ref{18f9,,sys.modules} will not work as there is no way to properly
replace the module references throughout the interpreter safely;
@ref{1ff,,ValueError} is raised if such a substitution is detected.

@cartouche
@quotation Note 
For projects where startup time is critical, this class allows for
potentially minimizing the cost of loading a module if it is never used.
For projects where startup time is not essential then use of this class is
`heavily' discouraged due to error messages created during loading being
postponed and thus occurring out of context.
@end quotation
@end cartouche


Ajouté dans la version 3.5.



Modifié dans la version 3.6: Began calling @ref{c9c,,create_module()}, removing the
compatibility warning for @ref{c9d,,importlib.machinery.BuiltinImporter} and
@ref{c9e,,importlib.machinery.ExtensionFileLoader}.


@geindex factory() (méthode de la classe importlib.util.LazyLoader)
@anchor{library/importlib importlib util LazyLoader factory}@anchor{4478}
@deffn {Méthode} classmethod factory (loader)

A class method which returns a callable that creates a lazy loader. This
is meant to be used in situations where the loader is passed by class
instead of by instance.

@example
suffixes = importlib.machinery.SOURCE_SUFFIXES
loader = importlib.machinery.SourceFileLoader
lazy_loader = importlib.util.LazyLoader.factory(loader)
finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))
@end example
@end deffn
@end deffn

@node Exemples<33>,,importlib util -- Utility code for importers,importlib --- The implementation of import
@anchor{library/importlib examples}@anchor{4479}@anchor{library/importlib importlib-examples}@anchor{447a}
@subsubsection Exemples


@menu
* Importing programmatically:: 
* Checking if a module can be imported:: 
* Importing a source file directly:: 
* Implementing lazy imports:: 
* Setting up an importer:: 
* Approximating importlib.import_module(): Approximating importlib import_module. 

@end menu

@node Importing programmatically,Checking if a module can be imported,,Exemples<33>
@anchor{library/importlib importing-programmatically}@anchor{447b}
@subsubsection Importing programmatically


To programmatically import a module, use @ref{501,,importlib.import_module()}.

@example
import importlib

itertools = importlib.import_module('itertools')
@end example

@node Checking if a module can be imported,Importing a source file directly,Importing programmatically,Exemples<33>
@anchor{library/importlib checking-if-a-module-can-be-imported}@anchor{447c}
@subsubsection Checking if a module can be imported


If you need to find out if a module can be imported without actually doing the
import, then you should use @ref{2cb,,importlib.util.find_spec()}.

Note that if @code{name} is a submodule (contains a dot),
@ref{2cb,,importlib.util.find_spec()} will import the parent module.

@example
import importlib.util
import sys

# For illustrative purposes.
name = 'itertools'

if name in sys.modules:
    print(f"@{name!r@} already in sys.modules")
elif (spec := importlib.util.find_spec(name)) is not None:
    # If you chose to perform the actual import ...
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    spec.loader.exec_module(module)
    print(f"@{name!r@} has been imported")
else:
    print(f"can't find the @{name!r@} module")
@end example

@node Importing a source file directly,Implementing lazy imports,Checking if a module can be imported,Exemples<33>
@anchor{library/importlib importing-a-source-file-directly}@anchor{447d}
@subsubsection Importing a source file directly


This recipe should be used with caution: it is an approximation of an import
statement where the file path is specified directly, rather than
@ref{3ab,,sys.path} being searched. Alternatives should first be considered first,
such as modifying @ref{3ab,,sys.path} when a proper module is required, or using
@ref{17f,,runpy.run_path()} when the global namespace resulting from running a Python
file is appropriate.

To import a Python source file directly from a path, use the following recipe:

@example
import importlib.util
import sys


def import_from_path(module_name, file_path):
    spec = importlib.util.spec_from_file_location(module_name, file_path)
    module = importlib.util.module_from_spec(spec)
    sys.modules[module_name] = module
    spec.loader.exec_module(module)
    return module


# For illustrative purposes only (use of `json` is arbitrary).
import json
file_path = json.__file__
module_name = json.__name__

# Similar outcome as `import json`.
json = import_from_path(module_name, file_path)
@end example

@node Implementing lazy imports,Setting up an importer,Importing a source file directly,Exemples<33>
@anchor{library/importlib implementing-lazy-imports}@anchor{447e}
@subsubsection Implementing lazy imports


The example below shows how to implement lazy imports:

@example
>>> import importlib.util
>>> import sys
>>> def lazy_import(name):
...     spec = importlib.util.find_spec(name)
...     loader = importlib.util.LazyLoader(spec.loader)
...     spec.loader = loader
...     module = importlib.util.module_from_spec(spec)
...     sys.modules[name] = module
...     loader.exec_module(module)
...     return module
...
>>> lazy_typing = lazy_import("typing")
>>> #lazy_typing is a real module object,
>>> #but it is not loaded in memory yet.
>>> lazy_typing.TYPE_CHECKING
False
@end example

@node Setting up an importer,Approximating importlib import_module,Implementing lazy imports,Exemples<33>
@anchor{library/importlib setting-up-an-importer}@anchor{447f}
@subsubsection Setting up an importer


For deep customizations of import, you typically want to implement an
@ref{1f6c,,importer}. This means managing both the @ref{1ea3,,finder} and @ref{1639,,loader}
side of things. For finders there are two flavours to choose from depending on
your needs: a @ref{1059,,meta path finder} or a @ref{105a,,path entry finder}. The
former is what you would put on @ref{d19,,sys.meta_path} while the latter is what
you create using a @ref{1f87,,path entry hook} on @ref{100d,,sys.path_hooks} which works
with @ref{3ab,,sys.path} entries to potentially create a finder. This example will
show you how to register your own importers so that import will use them (for
creating an importer for yourself, read the documentation for the appropriate
classes defined within this package):

@example
import importlib.machinery
import sys

# For illustrative purposes only.
SpamMetaPathFinder = importlib.machinery.PathFinder
SpamPathEntryFinder = importlib.machinery.FileFinder
loader_details = (importlib.machinery.SourceFileLoader,
                  importlib.machinery.SOURCE_SUFFIXES)

# Setting up a meta path finder.
# Make sure to put the finder in the proper location in the list in terms of
# priority.
sys.meta_path.append(SpamMetaPathFinder)

# Setting up a path entry finder.
# Make sure to put the path hook in the proper location in the list in terms
# of priority.
sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))
@end example

@node Approximating importlib import_module,,Setting up an importer,Exemples<33>
@anchor{library/importlib approximating-importlib-import-module}@anchor{4480}
@subsubsection Approximating @code{importlib.import_module()}


Import itself is implemented in Python code, making it possible to
expose most of the import machinery through importlib. The following
helps illustrate the various APIs that importlib exposes by providing an
approximate implementation of
@ref{501,,importlib.import_module()}:

@example
import importlib.util
import sys

def import_module(name, package=None):
    """An approximate implementation of import."""
    absolute_name = importlib.util.resolve_name(name, package)
    try:
        return sys.modules[absolute_name]
    except KeyError:
        pass

    path = None
    if '.' in absolute_name:
        parent_name, _, child_name = absolute_name.rpartition('.')
        parent_module = import_module(parent_name)
        path = parent_module.__spec__.submodule_search_locations
    for finder in sys.meta_path:
        spec = finder.find_spec(absolute_name, path)
        if spec is not None:
            break
    else:
        msg = f'No module named @{absolute_name!r@}'
        raise ModuleNotFoundError(msg, name=absolute_name)
    module = importlib.util.module_from_spec(spec)
    sys.modules[absolute_name] = module
    spec.loader.exec_module(module)
    if path is not None:
        setattr(parent_module, child_name, module)
    return module
@end example

@node importlib resources -- Package resource reading opening and access,importlib resources abc -- Abstract base classes for resources,importlib --- The implementation of import,Importer des modules
@anchor{library/importlib resources doc}@anchor{4481}@anchor{library/importlib resources importlib-resources-package-resource-reading-opening-and-access}@anchor{4482}@anchor{library/importlib resources module-importlib resources}@anchor{7a}
@subsection @code{importlib.resources} -- Package resource reading, opening and access


@geindex module; importlib.resources

`Source code:' Lib/importlib/resources/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/resources/__init__.py}


__________________________________________________________________



Ajouté dans la version 3.7.


This module leverages Python's import system to provide access to `resources'
within `packages'.

"Resources" are file-like resources associated with a module or package in
Python. The resources may be contained directly in a package, within a
subdirectory contained in that package, or adjacent to modules outside a
package. Resources may be text or binary. As a result, Python module sources
(.py) of a package and compilation artifacts (pycache) are technically
de-facto resources of that package. In practice, however, resources are
primarily those non-Python artifacts exposed specifically by the package
author.

Resources can be opened or read in either binary or text mode.

Resources are roughly akin to files inside directories, though it's important
to keep in mind that this is just a metaphor.  Resources and packages `do
not' have to exist as physical files and directories on the file system:
for example, a package and its resources can be imported from a zip file using
@ref{131,,zipimport}.

@cartouche
@quotation Note 
This module provides functionality similar to pkg_resources@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html} Basic Resource Access@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access}
without the performance overhead of that package.  This makes reading
resources included in packages easier, with more stable and consistent
semantics.

The standalone backport of this module provides more information
on using importlib.resources@footnote{https://importlib-resources.readthedocs.io/en/latest/using.html} and
migrating from pkg_resources to importlib.resources@footnote{https://importlib-resources.readthedocs.io/en/latest/migration.html}.
@end quotation
@end cartouche

@ref{eb0,,Loaders} that wish to support resource reading should implement a
@code{get_resource_reader(fullname)} method as specified by
@ref{443d,,importlib.resources.abc.ResourceReader}.

@geindex Anchor (classe dans importlib.resources)
@anchor{library/importlib resources importlib resources Anchor}@anchor{4483}
@deffn {Classe} importlib.resources.Anchor

Represents an anchor for resources, either a @ref{e00,,module object} or a module name as a string. Defined as
@code{Union[str, ModuleType]}.
@end deffn

@geindex files() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources files}@anchor{478}
@deffn {Fonction} importlib.resources.files (anchor: Anchor | None = None)

Returns a @ref{1f0,,Traversable} object
representing the resource container (think directory) and its resources
(think files). A Traversable may contain other containers (think
subdirectories).

`anchor' is an optional @ref{4483,,Anchor}. If the anchor is a
package, resources are resolved from that package. If a module,
resources are resolved adjacent to that module (in the same package
or the package root). If the anchor is omitted, the caller's module
is used.


Ajouté dans la version 3.9.



Modifié dans la version 3.12: `package' parameter was renamed to `anchor'. `anchor' can now
be a non-package module and if omitted will default to the caller's
module. `package' is still accepted for compatibility but will raise
a @ref{1a3,,DeprecationWarning}. Consider passing the anchor positionally or
using @code{importlib_resources >= 5.10} for a compatible interface
on older Pythons.

@end deffn

@geindex as_file() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources as_file}@anchor{477}
@deffn {Fonction} importlib.resources.as_file (traversable)

Given a @ref{1f0,,Traversable} object representing
a file or directory, typically from @ref{478,,importlib.resources.files()},
return a context manager for use in a @ref{5bc,,with} statement.
The context manager provides a @ref{226,,pathlib.Path} object.

Exiting the context manager cleans up any temporary file or directory
created when the resource was extracted from e.g. a zip file.

Use @code{as_file} when the Traversable methods
(@code{read_text}, etc) are insufficient and an actual file or directory on
the file system is required.


Ajouté dans la version 3.9.



Modifié dans la version 3.12: Added support for `traversable' representing a directory.

@end deffn

@menu
* API par fonction:: 

@end menu

@node API par fonction,,,importlib resources -- Package resource reading opening and access
@anchor{library/importlib resources functional-api}@anchor{4484}@anchor{library/importlib resources importlib-resources-functional}@anchor{4485}
@subsubsection API par fonction


A set of simplified, backwards-compatible helpers is available.
These allow common operations in a single function call.

For all the following functions:


@itemize -

@item 
`anchor' is an @ref{4483,,Anchor},
as in @ref{478,,files()}.
Unlike in @code{files}, it may not be omitted.

@item 
`path_names' are components of a resource's path name, relative to
the anchor.
For example, to get the text of resource named @code{info.txt}, use:

@example
importlib.resources.read_text(my_module, "info.txt")
@end example

Like @ref{1f0,,Traversable.joinpath},
The individual components should use forward slashes (@code{/})
as path separators.
For example, the following are equivalent:

@example
importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")
@end example

For backward compatibility reasons, functions that read text require
an explicit `encoding' argument if multiple `path_names' are given.
For example, to get the text of @code{info/chapter1.txt}, use:

@example
importlib.resources.read_text(my_module, "info", "chapter1.txt",
                              encoding='utf-8')
@end example
@end itemize

@geindex open_binary() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources open_binary}@anchor{1ea}
@deffn {Fonction} importlib.resources.open_binary (anchor, *path_names)

Open the named resource for binary reading.

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.

This function returns a @ref{3ee3,,BinaryIO} object,
that is, a binary stream open for reading.

This function is roughly equivalent to:

@example
files(anchor).joinpath(*path_names).open('rb')
@end example


Modifié dans la version 3.13: Multiple `path_names' are accepted.

@end deffn

@geindex open_text() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources open_text}@anchor{1eb}
@deffn {Fonction} importlib.resources.open_text (anchor, *path_names, encoding='utf-8', errors='strict')

Open the named resource for text reading.
By default, the contents are read as strict UTF-8.

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.
`encoding' and `errors' have the same meaning as in built-in @ref{505,,open()}.

For backward compatibility reasons, the `encoding' argument must be given
explicitly if there are multiple `path_names'.
This limitation is scheduled to be removed in Python 3.15.

This function returns a @ref{3ee2,,TextIO} object,
that is, a text stream open for reading.

This function is roughly equivalent to:

@example
files(anchor).joinpath(*path_names).open('r', encoding=encoding)
@end example


Modifié dans la version 3.13: Multiple `path_names' are accepted.
`encoding' and `errors' must be given as keyword arguments.

@end deffn

@geindex read_binary() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources read_binary}@anchor{1ed}
@deffn {Fonction} importlib.resources.read_binary (anchor, *path_names)

Read and return the contents of the named resource as @ref{1bd,,bytes}.

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.

This function is roughly equivalent to:

@example
files(anchor).joinpath(*path_names).read_bytes()
@end example


Modifié dans la version 3.13: Multiple `path_names' are accepted.

@end deffn

@geindex read_text() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources read_text}@anchor{1ee}
@deffn {Fonction} importlib.resources.read_text (anchor, *path_names, encoding='utf-8', errors='strict')

Read and return the contents of the named resource as @ref{435,,str}.
By default, the contents are read as strict UTF-8.

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.
`encoding' and `errors' have the same meaning as in built-in @ref{505,,open()}.

For backward compatibility reasons, the `encoding' argument must be given
explicitly if there are multiple `path_names'.
This limitation is scheduled to be removed in Python 3.15.

This function is roughly equivalent to:

@example
files(anchor).joinpath(*path_names).read_text(encoding=encoding)
@end example


Modifié dans la version 3.13: Multiple `path_names' are accepted.
`encoding' and `errors' must be given as keyword arguments.

@end deffn

@geindex path() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources path}@anchor{1ec}
@deffn {Fonction} importlib.resources.path (anchor, *path_names)

Provides the path to the `resource' as an actual file system path.  This
function returns a context manager for use in a @ref{5bc,,with} statement.
The context manager provides a @ref{226,,pathlib.Path} object.

Exiting the context manager cleans up any temporary files created, e.g.
when the resource needs to be extracted from a zip file.

For example, the @ref{80d,,stat()} method requires
an actual file system path; it can be used like this:

@example
with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()
@end example

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.

This function is roughly equivalent to:

@example
as_file(files(anchor).joinpath(*path_names))
@end example


Modifié dans la version 3.13: Multiple `path_names' are accepted.
`encoding' and `errors' must be given as keyword arguments.

@end deffn

@geindex is_resource() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources is_resource}@anchor{1e9}
@deffn {Fonction} importlib.resources.is_resource (anchor, *path_names)

Return @code{True} if the named resource exists, otherwise @code{False}.
This function does not consider directories to be resources.

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.

This function is roughly equivalent to:

@example
files(anchor).joinpath(*path_names).is_file()
@end example


Modifié dans la version 3.13: Multiple `path_names' are accepted.

@end deffn

@geindex contents() (dans le module importlib.resources)
@anchor{library/importlib resources importlib resources contents}@anchor{1ef}
@deffn {Fonction} importlib.resources.contents (anchor, *path_names)

Return an iterable over the named items within the package or path.
The iterable returns names of resources (e.g. files) and non-resources
(e.g. directories) as @ref{435,,str}.
The iterable does not recurse into subdirectories.

See @ref{4485,,the introduction} for
details on `anchor' and `path_names'.

This function is roughly equivalent to:

@example
for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name
@end example


Obsolète depuis la version 3.11: Prefer @code{iterdir()} as above, which offers more control over the
results and richer functionality.

@end deffn

@node importlib resources abc -- Abstract base classes for resources,importlib metadata -- Accessing package metadata,importlib resources -- Package resource reading opening and access,Importer des modules
@anchor{library/importlib resources abc doc}@anchor{4486}@anchor{library/importlib resources abc importlib-resources-abc-abstract-base-classes-for-resources}@anchor{4487}@anchor{library/importlib resources abc module-importlib resources abc}@anchor{7b}
@subsection @code{importlib.resources.abc} -- Abstract base classes for resources


@geindex module; importlib.resources.abc

`Source code:' Lib/importlib/resources/abc.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/resources/abc.py}


__________________________________________________________________



Ajouté dans la version 3.11.


@geindex ResourceReader (classe dans importlib.resources.abc)
@anchor{library/importlib resources abc importlib resources abc ResourceReader}@anchor{443d}
@deffn {Classe} importlib.resources.abc.ResourceReader

`Superseded by TraversableResources'

An @ref{1193,,abstract base class} to provide the ability to read
`resources'.

From the perspective of this ABC, a `resource' is a binary
artifact that is shipped within a package. Typically this is
something like a data file that lives next to the @code{__init__.py}
file of the package. The purpose of this class is to help abstract
out the accessing of such data files so that it does not matter if
the package and its data file(s) are stored e.g. in a zip file
versus on the file system.

For any of methods of this class, a `resource' argument is
expected to be a @ref{29d,,path-like object} which represents
conceptually just a file name. This means that no subdirectory
paths should be included in the `resource' argument. This is
because the location of the package the reader is for, acts as the
"directory". Hence the metaphor for directories and file
names is packages and resources, respectively. This is also why
instances of this class are expected to directly correlate to
a specific package (instead of potentially representing multiple
packages or a module).

Loaders that wish to support resource reading are expected to
provide a method called @code{get_resource_reader(fullname)} which
returns an object implementing this ABC's interface. If the module
specified by fullname is not a package, this method should return
@ref{660,,None}. An object compatible with this ABC should only be
returned when the specified module is a package.


Deprecated since version 3.12, will be removed in version 3.14: Use @ref{2c3,,importlib.resources.abc.TraversableResources} instead.


@geindex open_resource() (méthode importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader open_resource}@anchor{4488}
@deffn {Méthode} abstractmethod open_resource (resource)

Returns an opened, @ref{250d,,file-like object} for binary reading
of the `resource'.

Si la ressource ne peut pas être trouvée, @ref{eae,,FileNotFoundError} est levée.
@end deffn

@geindex resource_path() (méthode importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader resource_path}@anchor{4489}
@deffn {Méthode} abstractmethod resource_path (resource)

Renvoie le chemin de `resource' dans le système de fichiers.

If the resource does not concretely exist on the file system,
raise @ref{eae,,FileNotFoundError}.
@end deffn

@geindex is_resource() (méthode importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader is_resource}@anchor{448a}
@deffn {Méthode} abstractmethod is_resource (name)

Returns @code{True} if the named `name' is considered a resource.
@ref{eae,,FileNotFoundError} is raised if `name' does not exist.
@end deffn

@geindex contents() (méthode importlib.resources.abc.ResourceReader)
@anchor{library/importlib resources abc importlib resources abc ResourceReader contents}@anchor{448b}
@deffn {Méthode} abstractmethod contents ()

Returns an @ref{1205,,iterable} of strings over the contents of
the package. Do note that it is not required that all names
returned by the iterator be actual resources, e.g. it is
acceptable to return names for which @ref{448a,,is_resource()} would
be false.

Allowing non-resource names to be returned is to allow for
situations where how a package and its resources are stored
are known a priori and the non-resource names would be useful.
For instance, returning subdirectory names is allowed so that
when it is known that the package and resources are stored on
the file system then those subdirectory names can be used
directly.

The abstract method returns an iterable of no items.
@end deffn
@end deffn

@geindex Traversable (classe dans importlib.resources.abc)
@anchor{library/importlib resources abc importlib resources abc Traversable}@anchor{1f0}
@deffn {Classe} importlib.resources.abc.Traversable

An object with a subset of @ref{226,,pathlib.Path} methods suitable for
traversing directories and opening files.

For a representation of the object on the file-system, use
@ref{477,,importlib.resources.as_file()}.

@geindex name (attribut importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable name}@anchor{448c}
@deffn {Attribut} name

Abstract. The base name of this object without any parent references.
@end deffn

@geindex iterdir() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable iterdir}@anchor{448d}
@deffn {Méthode} abstractmethod iterdir ()

Yield Traversable objects in self.
@end deffn

@geindex is_dir() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable is_dir}@anchor{448e}
@deffn {Méthode} abstractmethod is_dir ()

Return @code{True} if self is a directory.
@end deffn

@geindex is_file() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable is_file}@anchor{448f}
@deffn {Méthode} abstractmethod is_file ()

Return @code{True} if self is a file.
@end deffn

@geindex joinpath() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable joinpath}@anchor{4490}
@deffn {Méthode} abstractmethod joinpath (*pathsegments)

Traverse directories according to `pathsegments' and return
the result as @code{Traversable}.

Each `pathsegments' argument may contain multiple names separated by
forward slashes (@code{/}, @code{posixpath.sep} ).
For example, the following are equivalent:

@example
files.joinpath('subdir', 'subsuddir', 'file.txt')
files.joinpath('subdir/subsuddir/file.txt')
@end example

Note that some @code{Traversable} implementations
might not be updated to the latest version of the protocol.
For compatibility with such implementations, provide a single argument
without path separators to each call to @code{joinpath}. For example:

@example
files.joinpath('subdir').joinpath('subsubdir').joinpath('file.txt')
@end example


Modifié dans la version 3.11: @code{joinpath} accepts multiple `pathsegments', and these segments
may contain forward slashes as path separators.
Previously, only a single `child' argument was accepted.

@end deffn

@geindex __truediv__() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable __truediv__}@anchor{4491}
@deffn {Méthode} abstractmethod __truediv__ (child)

Return Traversable child in self.
Equivalent to @code{joinpath(child)}.
@end deffn

@geindex open() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable open}@anchor{4492}
@deffn {Méthode} abstractmethod open (mode='r', *args, **kwargs)

`mode' may be 'r' or 'rb' to open as text or binary. Return a handle
suitable for reading (same as @ref{2744,,pathlib.Path.open}).

When opening as text, accepts encoding parameters such as those
accepted by @ref{7a5,,io.TextIOWrapper}.
@end deffn

@geindex read_bytes() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable read_bytes}@anchor{4493}
@deffn {Méthode} read_bytes ()

Read contents of self as bytes.
@end deffn

@geindex read_text() (méthode importlib.resources.abc.Traversable)
@anchor{library/importlib resources abc importlib resources abc Traversable read_text}@anchor{4494}
@deffn {Méthode} read_text (encoding=None)

Read contents of self as text.
@end deffn
@end deffn

@geindex TraversableResources (classe dans importlib.resources.abc)
@anchor{library/importlib resources abc importlib resources abc TraversableResources}@anchor{2c3}
@deffn {Classe} importlib.resources.abc.TraversableResources

An abstract base class for resource readers capable of serving
the @ref{478,,importlib.resources.files()} interface. Subclasses
@ref{443d,,ResourceReader} and provides
concrete implementations of the @code{ResourceReader}'s
abstract methods. Therefore, any loader supplying
@code{TraversableResources} also supplies @code{ResourceReader}.

Loaders that wish to support resource reading are expected to
implement this interface.

@geindex files() (méthode importlib.resources.abc.TraversableResources)
@anchor{library/importlib resources abc importlib resources abc TraversableResources files}@anchor{4495}
@deffn {Méthode} abstractmethod files ()

Returns a @ref{1f0,,importlib.resources.abc.Traversable} object for the loaded
package.
@end deffn
@end deffn

@node importlib metadata -- Accessing package metadata,The initialization of the sys path module search path,importlib resources abc -- Abstract base classes for resources,Importer des modules
@anchor{library/importlib metadata doc}@anchor{4496}@anchor{library/importlib metadata importlib-metadata-accessing-package-metadata}@anchor{4497}@anchor{library/importlib metadata module-importlib metadata}@anchor{79}@anchor{library/importlib metadata using}@anchor{4498}
@subsection @code{importlib.metadata} -- Accessing package metadata


@geindex module; importlib.metadata


Ajouté dans la version 3.8.



Modifié dans la version 3.10: @code{importlib.metadata} is no longer provisional.


`Source code:' Lib/importlib/metadata/__init__.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/importlib/metadata/__init__.py}

@code{importlib.metadata} is a library that provides access to
the metadata of an installed Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package},
such as its entry points
or its top-level names (Import Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Import-Package}s, modules, if any).
Built in part on Python's import system, this library
intends to replace similar functionality in the entry point API@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points} and metadata API@footnote{https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api} of @code{pkg_resources}.  Along with
@ref{7a,,importlib.resources},
this package can eliminate the need to use the older and less efficient
@code{pkg_resources} package.

@code{importlib.metadata} operates on third-party `distribution packages'
installed into Python's @code{site-packages} directory via tools such as
pip@footnote{https://pypi.org/project/pip/}.
Specifically, it works with distributions with discoverable
@code{dist-info} or @code{egg-info} directories,
and metadata defined by the Core metadata specifications@footnote{https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata}.

@cartouche
@quotation Important 
These are `not' necessarily equivalent to or correspond 1:1 with
the top-level `import package' names
that can be imported inside Python code.
One `distribution package' can contain multiple `import packages'
(and single modules),
and one top-level `import package'
may map to multiple `distribution packages'
if it is a namespace package.
You can use @ref{7fa,,packages_distributions()}
to get a mapping between them.
@end quotation
@end cartouche

By default, distribution metadata can live on the file system
or in zip archives on
@ref{3ab,,sys.path}.  Through an extension mechanism, the metadata can live almost
anywhere.


@subsubheading Voir aussi



@table @asis

@item @indicateurl{https://importlib-metadata.readthedocs.io/}

The documentation for @code{importlib_metadata}, which supplies a
backport of @code{importlib.metadata}.
This includes an API reference@footnote{https://importlib-metadata.readthedocs.io/en/latest/api.html}
for this module's classes and functions,
as well as a migration guide@footnote{https://importlib-metadata.readthedocs.io/en/latest/migration.html}
for existing users of @code{pkg_resources}.
@end table


@menu
* Aperçu: Aperçu<3>. 
* API par fonction: API par fonction<2>. 
* Distributions:: 
* Distribution Discovery:: 
* Extending the search algorithm:: 

@end menu

@node Aperçu<3>,API par fonction<2>,,importlib metadata -- Accessing package metadata
@anchor{library/importlib metadata overview}@anchor{4499}
@subsubsection Aperçu


Let's say you wanted to get the version string for a
Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package} you've installed
using @code{pip}.  We start by creating a virtual environment and installing
something into it:

@example
$ python -m venv example
$ source example/bin/activate
(example) $ python -m pip install wheel
@end example

You can get the version string for @code{wheel} by running the following:

@example
(example) $ python
>>> from importlib.metadata import version  
>>> version('wheel')  
'0.32.3'
@end example

You can also get a collection of entry points selectable by properties of the EntryPoint (typically 'group' or 'name'), such as
@code{console_scripts}, @code{distutils.commands} and others.  Each group contains a
collection of @ref{281,,EntryPoint} objects.

You can get the @ref{449a,,metadata for a distribution}:

@example
>>> list(metadata('wheel'))  
['Metadata-Version', 'Name', 'Version', 'Summary', 'Home-page', 'Author', 'Author-email', 'Maintainer', 'Maintainer-email', 'License', 'Project-URL', 'Project-URL', 'Project-URL', 'Keywords', 'Platform', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Requires-Python', 'Provides-Extra', 'Requires-Dist', 'Requires-Dist']
@end example

You can also get a @ref{449b,,distribution's version number}, list its
@ref{449c,,constituent files}, and get a list of the distribution's
@ref{449d,,Distribution requirements}.

@geindex PackageNotFoundError
@anchor{library/importlib metadata importlib metadata PackageNotFoundError}@anchor{449e}
@deffn {Exception} importlib.metadata.PackageNotFoundError

Subclass of @ref{b35,,ModuleNotFoundError} raised by several functions in this
module when queried for a distribution package which is not installed in the
current Python environment.
@end deffn

@node API par fonction<2>,Distributions,Aperçu<3>,importlib metadata -- Accessing package metadata
@anchor{library/importlib metadata functional-api}@anchor{449f}
@subsubsection API par fonction


This package provides the following functionality via its public API.

@menu
* Entry points:: 
* Distribution metadata:: 
* Distribution versions:: 
* Distribution files:: 
* Distribution requirements:: 
* Mapping import to distribution packages:: 

@end menu

@node Entry points,Distribution metadata,,API par fonction<2>
@anchor{library/importlib metadata entry-points}@anchor{281}@anchor{library/importlib metadata id2}@anchor{44a0}
@subsubsection Entry points


@geindex entry_points() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata entry_points}@anchor{44a1}
@deffn {Fonction} importlib.metadata.entry_points (**select_params)

Returns a @ref{44a2,,EntryPoints} instance describing entry points for the
current environment. Any given keyword parameters are passed to the
@code{select()} method for comparison to the attributes of
the individual entry point definitions.

Note: it is not currently possible to query for entry points based on
their @code{EntryPoint.dist} attribute (as different @code{Distribution}
instances do not currently compare equal, even if they have the same attributes)
@end deffn

@geindex EntryPoints (classe dans importlib.metadata)
@anchor{library/importlib metadata importlib metadata EntryPoints}@anchor{44a2}
@deffn {Classe} importlib.metadata.EntryPoints

Details of a collection of installed entry points.

Also provides a @code{.groups} attribute that reports all identified entry
point groups, and a @code{.names} attribute that reports all identified entry
point names.
@end deffn

@geindex EntryPoint (classe dans importlib.metadata)
@anchor{library/importlib metadata importlib metadata EntryPoint}@anchor{44a3}
@deffn {Classe} importlib.metadata.EntryPoint

Details of an installed entry point.

Each @code{EntryPoint} instance has @code{.name}, @code{.group}, and @code{.value}
attributes and a @code{.load()} method to resolve the value. There are also
@code{.module}, @code{.attr}, and @code{.extras} attributes for getting the
components of the @code{.value} attribute, and @code{.dist} for obtaining
information regarding the distribution package that provides the entry point.
@end deffn

Query all entry points:

@example
>>> eps = entry_points()  
@end example

The @code{entry_points()} function returns a @code{EntryPoints} object,
a collection of all @code{EntryPoint} objects with @code{names} and @code{groups}
attributes for convenience:

@example
>>> sorted(eps.groups)  
['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
@end example

@code{EntryPoints} has a @code{select()} method to select entry points
matching specific properties. Select entry points in the
@code{console_scripts} group:

@example
>>> scripts = eps.select(group='console_scripts')  
@end example

Equivalently, since @code{entry_points()} passes keyword arguments
through to select:

@example
>>> scripts = entry_points(group='console_scripts')  
@end example

Pick out a specific script named "wheel" (found in the wheel project):

@example
>>> 'wheel' in scripts.names  
True
>>> wheel = scripts['wheel']  
@end example

Equivalently, query for that entry point during selection:

@example
>>> (wheel,) = entry_points(group='console_scripts', name='wheel')  
>>> (wheel,) = entry_points().select(group='console_scripts', name='wheel')  
@end example

Inspect the resolved entry point:

@example
>>> wheel  
EntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')
>>> wheel.module  
'wheel.cli'
>>> wheel.attr  
'main'
>>> wheel.extras  
[]
>>> main = wheel.load()  
>>> main  
<function main at 0x103528488>
@end example

The @code{group} and @code{name} are arbitrary values defined by the package author
and usually a client will wish to resolve all entry points for a particular
group.  Read the setuptools docs@footnote{https://setuptools.pypa.io/en/latest/userguide/entry_point.html}
for more information on entry points, their definition, and usage.


Modifié dans la version 3.12: The "selectable" entry points were introduced in @code{importlib_metadata}
3.6 and Python 3.10. Prior to those changes, @code{entry_points} accepted
no parameters and always returned a dictionary of entry points, keyed
by group. With @code{importlib_metadata} 5.0 and Python 3.12,
@code{entry_points} always returns an @code{EntryPoints} object. See
backports.entry_points_selectable@footnote{https://pypi.org/project/backports.entry_points_selectable/}
for compatibility options.



Modifié dans la version 3.13: @code{EntryPoint} objects no longer present a tuple-like interface
(@ref{280,,__getitem__()}).


@node Distribution metadata,Distribution versions,Entry points,API par fonction<2>
@anchor{library/importlib metadata distribution-metadata}@anchor{44a4}@anchor{library/importlib metadata metadata}@anchor{449a}
@subsubsection Distribution metadata


@geindex metadata() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata metadata}@anchor{44a5}
@deffn {Fonction} importlib.metadata.metadata (distribution_name)

Return the distribution metadata corresponding to the named
distribution package as a @ref{44a6,,PackageMetadata} instance.

Raises @ref{449e,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

@geindex PackageMetadata (classe dans importlib.metadata)
@anchor{library/importlib metadata importlib metadata PackageMetadata}@anchor{44a6}
@deffn {Classe} importlib.metadata.PackageMetadata

A concrete implementation of the
PackageMetadata protocol@footnote{https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata}.

In addition to providing the defined protocol methods and attributes, subscripting
the instance is equivalent to calling the @code{get()} method.
@end deffn

Every Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}
includes some metadata, which you can extract using the @code{metadata()} function:

@example
>>> wheel_metadata = metadata('wheel')  
@end example

The keys of the returned data structure name the metadata keywords, and
the values are returned unparsed from the distribution metadata:

@example
>>> wheel_metadata['Requires-Python']  
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
@end example

@ref{44a6,,PackageMetadata} also presents a @code{json} attribute that returns
all the metadata in a JSON-compatible form per 
@geindex Python Enhancement Proposals; PEP 566
PEP 566@footnote{https://peps.python.org/pep-0566/}:

@example
>>> wheel_metadata.json['requires_python']
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
@end example

The full set of available metadata is not described here.
See the PyPA Core metadata specification@footnote{https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata} for additional details.


Modifié dans la version 3.10: The @code{Description} is now included in the metadata when presented
through the payload. Line continuation characters have been removed.

The @code{json} attribute was added.


@node Distribution versions,Distribution files,Distribution metadata,API par fonction<2>
@anchor{library/importlib metadata distribution-versions}@anchor{44a7}@anchor{library/importlib metadata version}@anchor{449b}
@subsubsection Distribution versions


@geindex version() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata version}@anchor{153a}
@deffn {Fonction} importlib.metadata.version (distribution_name)

Return the installed distribution package version for the named
distribution package.

Raises @ref{449e,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

The @code{version()} function is the quickest way to get a
Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}'s version
number, as a string:

@example
>>> version('wheel')  
'0.32.3'
@end example

@node Distribution files,Distribution requirements,Distribution versions,API par fonction<2>
@anchor{library/importlib metadata distribution-files}@anchor{44a8}@anchor{library/importlib metadata files}@anchor{449c}
@subsubsection Distribution files


@geindex files() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata files}@anchor{44a9}
@deffn {Fonction} importlib.metadata.files (distribution_name)

Return the full set of files contained within the named
distribution package.

Raises @ref{449e,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.

Returns @ref{660,,None} if the distribution is found but the installation
database records reporting the files associated with the distribuion package
are missing.
@end deffn

@geindex PackagePath (classe dans importlib.metadata)
@anchor{library/importlib metadata importlib metadata PackagePath}@anchor{44aa}
@deffn {Classe} importlib.metadata.PackagePath

A @ref{490,,pathlib.PurePath} derived object with additional @code{dist},
@code{size}, and @code{hash} properties corresponding to the distribution
package's installation metadata for that file.
@end deffn

The @code{files()} function takes a
Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}
name and returns all of the files installed by this distribution. Each file is reported
as a @ref{44aa,,PackagePath} instance. For example:

@example
>>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]  
>>> util  
PackagePath('wheel/util.py')
>>> util.size  
859
>>> util.dist  
<importlib.metadata._hooks.PathDistribution object at 0x101e0cef0>
>>> util.hash  
<FileHash mode: sha256 value: bYkw5oMccfazVCoYQwKkkemoVyMAFoR34mmKBx8R1NI>
@end example

Once you have the file, you can also read its contents:

@example
>>> print(util.read_text())  
import base64
import sys
...
def as_bytes(s):
    if isinstance(s, text_type):
        return s.encode('utf-8')
    return s
@end example

You can also use the @code{locate()} method to get the absolute
path to the file:

@example
>>> util.locate()  
PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')
@end example

In the case where the metadata file listing files
(@code{RECORD} or @code{SOURCES.txt}) is missing, @code{files()} will
return @ref{660,,None}. The caller may wish to wrap calls to
@code{files()} in always_iterable@footnote{https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable}
or otherwise guard against this condition if the target
distribution is not known to have the metadata present.

@node Distribution requirements,Mapping import to distribution packages,Distribution files,API par fonction<2>
@anchor{library/importlib metadata distribution-requirements}@anchor{44ab}@anchor{library/importlib metadata requirements}@anchor{449d}
@subsubsection Distribution requirements


@geindex requires() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata requires}@anchor{44ac}
@deffn {Fonction} importlib.metadata.requires (distribution_name)

Return the declared dependency specifiers for the named
distribution package.

Raises @ref{449e,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

To get the full set of requirements for a Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package},
use the @code{requires()}
function:

@example
>>> requires('wheel')  
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]
@end example
@anchor{library/importlib metadata package-distributions}@anchor{7fa}
@node Mapping import to distribution packages,,Distribution requirements,API par fonction<2>
@anchor{library/importlib metadata import-distribution-package-mapping}@anchor{44ad}@anchor{library/importlib metadata mapping-import-to-distribution-packages}@anchor{44ae}
@subsubsection Mapping import to distribution packages


@geindex packages_distributions() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata packages_distributions}@anchor{44af}
@deffn {Fonction} importlib.metadata.packages_distributions ()

Return a mapping from the top level module and import package
names found via @ref{d19,,sys.meta_path} to the names of the distribution
packages (if any) that provide the corresponding files.

To allow for namespace packages (which may have members provided by
multiple distribution packages), each top level import name maps to a
list of distribution names rather than mapping directly to a single name.
@end deffn

A convenience method to resolve the Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}
name (or names, in the case of a namespace package)
that provide each importable top-level
Python module or Import Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Import-Package}:

@example
>>> packages_distributions()
@{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...@}
@end example

Some editable installs, do not supply top-level names@footnote{https://github.com/pypa/packaging-problems/issues/609}, and thus this
function is not reliable with such installs.


Ajouté dans la version 3.10.


@node Distributions,Distribution Discovery,API par fonction<2>,importlib metadata -- Accessing package metadata
@anchor{library/importlib metadata distributions}@anchor{7fb}@anchor{library/importlib metadata id9}@anchor{44b0}
@subsubsection Distributions


@geindex distribution() (dans le module importlib.metadata)
@anchor{library/importlib metadata importlib metadata distribution}@anchor{44b1}
@deffn {Fonction} importlib.metadata.distribution (distribution_name)

Return a @ref{44b2,,Distribution} instance describing the named
distribution package.

Raises @ref{449e,,PackageNotFoundError} if the named distribution
package is not installed in the current Python environment.
@end deffn

@geindex Distribution (classe dans importlib.metadata)
@anchor{library/importlib metadata importlib metadata Distribution}@anchor{44b2}
@deffn {Classe} importlib.metadata.Distribution

Details of an installed distribution package.

Note: different @code{Distribution} instances do not currently compare
equal, even if they relate to the same installed distribution and
accordingly have the same attributes.
@end deffn

While the module level API described above is the most common and convenient usage,
you can get all of that information from the @code{Distribution} class.
@code{Distribution} is an abstract object that represents the metadata for
a Python Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}.
You can get the concreate @code{Distribution} subclass instance for an installed
distribution package by calling the @ref{44b1,,distribution()} function:

@example
>>> from importlib.metadata import distribution  
>>> dist = distribution('wheel')  
>>> type(dist)  
<class 'importlib.metadata.PathDistribution'>
@end example

Thus, an alternative way to get the version number is through the
@code{Distribution} instance:

@example
>>> dist.version  
'0.32.3'
@end example

There are all kinds of additional metadata available on @code{Distribution}
instances:

@example
>>> dist.metadata['Requires-Python']  
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> dist.metadata['License']  
'MIT'
@end example

For editable packages, an @code{origin} property may present 
@geindex Python Enhancement Proposals; PEP 610
PEP 610@footnote{https://peps.python.org/pep-0610/}
metadata:

@example
>>> dist.origin.url
'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'
@end example

The full set of available metadata is not described here.
See the PyPA Core metadata specification@footnote{https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata} for additional details.


Ajouté dans la version 3.13: The @code{.origin} property was added.


@node Distribution Discovery,Extending the search algorithm,Distributions,importlib metadata -- Accessing package metadata
@anchor{library/importlib metadata distribution-discovery}@anchor{44b3}
@subsubsection Distribution Discovery


By default, this package provides built-in support for discovery of metadata
for file system and zip file Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package}s.
This metadata finder search defaults to @code{sys.path}, but varies slightly in how it interprets those values from how other import machinery does. In particular:


@itemize -

@item 
@code{importlib.metadata} does not honor @ref{1bd,,bytes} objects on @code{sys.path}.

@item 
@code{importlib.metadata} will incidentally honor @ref{226,,pathlib.Path} objects on @code{sys.path} even though such values will be ignored for imports.
@end itemize

@node Extending the search algorithm,,Distribution Discovery,importlib metadata -- Accessing package metadata
@anchor{library/importlib metadata extending-the-search-algorithm}@anchor{44b4}
@subsubsection Extending the search algorithm


Because Distribution Package@footnote{https://packaging.python.org/en/latest/glossary/#term-Distribution-Package} metadata
is not available through @ref{3ab,,sys.path} searches, or
package loaders directly,
the metadata for a distribution is found through import
system @ref{1f75,,finders}.  To find a distribution package's metadata,
@code{importlib.metadata} queries the list of @ref{1059,,meta path finders} on
@ref{d19,,sys.meta_path}.

By default @code{importlib.metadata} installs a finder for distribution packages
found on the file system.
This finder doesn't actually find any `distributions',
but it can find their metadata.

The abstract class @ref{859,,importlib.abc.MetaPathFinder} defines the
interface expected of finders by Python's import system.
@code{importlib.metadata} extends this protocol by looking for an optional
@code{find_distributions} callable on the finders from
@ref{d19,,sys.meta_path} and presents this extended interface as the
@code{DistributionFinder} abstract base class, which defines this abstract
method:

@example
@@abc.abstractmethod
def find_distributions(context=DistributionFinder.Context()):
    """Return an iterable of all Distribution instances capable of
    loading the metadata for packages for the indicated `@w{`}context`@w{`}.
    """
@end example

The @code{DistributionFinder.Context} object provides @code{.path} and @code{.name}
properties indicating the path to search and name to match and may
supply other relevant context.

What this means in practice is that to support finding distribution package
metadata in locations other than the file system, subclass
@code{Distribution} and implement the abstract methods. Then from
a custom finder, return instances of this derived @code{Distribution} in the
@code{find_distributions()} method.

@menu
* Exemple: Exemple<15>. 

@end menu

@node Exemple<15>,,,Extending the search algorithm
@anchor{library/importlib metadata example}@anchor{44b5}
@subsubsection Exemple


Consider for example a custom finder that loads Python
modules from a database:

@example
class DatabaseImporter(importlib.abc.MetaPathFinder):
    def __init__(self, db):
        self.db = db

    def find_spec(self, fullname, target=None) -> ModuleSpec:
        return self.db.spec_from_name(fullname)

sys.meta_path.append(DatabaseImporter(connect_db(...)))
@end example

That importer now presumably provides importable modules from a
database, but it provides no metadata or entry points. For this
custom importer to provide metadata, it would also need to implement
@code{DistributionFinder}:

@example
from importlib.metadata import DistributionFinder

class DatabaseImporter(DistributionFinder):
    ...

    def find_distributions(self, context=DistributionFinder.Context()):
        query = dict(name=context.name) if context.name else @{@}
        for dist_record in self.db.query_distributions(query):
            yield DatabaseDistribution(dist_record)
@end example

In this way, @code{query_distributions} would return records for
each distribution served by the database matching the query. For
example, if @code{requests-1.0} is in the database, @code{find_distributions}
would yield a @code{DatabaseDistribution} for @code{Context(name='requests')}
or @code{Context(name=None)}.

For the sake of simplicity, this example ignores @code{context.path}. The
@code{path} attribute defaults to @code{sys.path} and is the set of import paths to
be considered in the search. A @code{DatabaseImporter} could potentially function
without any concern for a search path. Assuming the importer does no
partitioning, the "path" would be irrelevant. In order to illustrate the
purpose of @code{path}, the example would need to illustrate a more complex
@code{DatabaseImporter} whose behavior varied depending on
@code{sys.path}/@code{PYTHONPATH}. In that case, the @code{find_distributions} should
honor the @code{context.path} and only yield @code{Distribution}s pertinent to that
path.

@code{DatabaseDistribution}, then, would look something like:

@example
class DatabaseDistribution(importlib.metadata.Distribution):
    def __init__(self, record):
        self.record = record

    def read_text(self, filename):
        """
        Read a file like "METADATA" for the current distribution.
        """
        if filename == "METADATA":
            return f"""Name: @{self.record.name@}
Version: @{self.record.version@}
"""
        if filename == "entry_points.txt":
            return "\n".join(
              f"""[@{ep.group@}]\n@{ep.name@}=@{ep.value@}"""
              for ep in self.record.entry_points)

    def locate_file(self, path):
        raise RuntimeError("This distribution has no file system")
@end example

This basic implementation should provide metadata and entry points for
packages served by the @code{DatabaseImporter}, assuming that the
@code{record} supplies suitable @code{.name}, @code{.version}, and
@code{.entry_points} attributes.

The @code{DatabaseDistribution} may also provide other metadata files, like
@code{RECORD} (required for @code{Distribution.files}) or override the
implementation of @code{Distribution.files}. See the source for more inspiration.

@node The initialization of the sys path module search path,,importlib metadata -- Accessing package metadata,Importer des modules
@anchor{library/sys_path_init doc}@anchor{44b6}@anchor{library/sys_path_init sys-path-init}@anchor{1bee}@anchor{library/sys_path_init the-initialization-of-the-sys-path-module-search-path}@anchor{44b7}
@subsection The initialization of the @code{sys.path} module search path


A module search path is initialized when Python starts. This module search path
may be accessed at @ref{3ab,,sys.path}.

The first entry in the module search path is the directory that contains the
input script, if there is one. Otherwise, the first entry is the current
directory, which is the case when executing the interactive shell, a @ref{5ca,,-c}
command, or @ref{5cb,,-m} module.

The 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} environment variable is often used to add directories
to the search path. If this environment variable is found then the contents are
added to the module search path.

@cartouche
@quotation Note 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} will affect all installed Python versions/environments.
Be wary of setting this in your shell profile or global environment variables.
The @ref{c6,,site} module offers more nuanced techniques as mentioned below.
@end quotation
@end cartouche

The next items added are the directories containing standard Python modules as
well as any @ref{44b8,,extension module}s that these modules depend on. Extension
modules are @code{.pyd} files on Windows and @code{.so} files on other platforms. The
directory with the platform-independent Python modules is called @code{prefix}.
The directory with the extension modules is called @code{exec_prefix}.

The 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment variable may be used to set the @code{prefix}
and @code{exec_prefix} locations. Otherwise these directories are found by using
the Python executable as a starting point and then looking for various 'landmark'
files and directories. Note that any symbolic links are followed so the real
Python executable location is used as the search starting point. The Python
executable location is called @code{home}.

Once @code{home} is determined, the @code{prefix} directory is found by first looking
for @code{python`majorversion'`minorversion'.zip} (@code{python311.zip}). On Windows
the zip archive is searched for in @code{home} and on Unix the archive is expected
to be in @code{lib}. Note that the expected zip archive location is added to the
module search path even if the archive does not exist. If no archive was found,
Python on Windows will continue the search for @code{prefix} by looking for @code{Lib\os.py}.
Python on Unix will look for @code{lib/python`majorversion'.`minorversion'/os.py}
(@code{lib/python3.11/os.py}). On Windows @code{prefix} and @code{exec_prefix} are the same,
however on other platforms @code{lib/python`majorversion'.`minorversion'/lib-dynload}
(@code{lib/python3.11/lib-dynload}) is searched for and used as an anchor for
@code{exec_prefix}. On some platforms @code{lib} may be @code{lib64} or another value,
see @ref{925,,sys.platlibdir} and 
@geindex PYTHONPLATLIBDIR
@geindex variable d'environnement; PYTHONPLATLIBDIR
@ref{18cd,,PYTHONPLATLIBDIR}.

Once found, @code{prefix} and @code{exec_prefix} are available at @ref{3ad,,sys.prefix} and
@ref{3a9,,sys.exec_prefix} respectively.

Finally, the @ref{c6,,site} module is processed and @code{site-packages} directories
are added to the module search path. A common way to customize the search path is
to create @ref{c7,,sitecustomize} or @ref{10d,,usercustomize} modules as described in
the @ref{c6,,site} module documentation.

@cartouche
@quotation Note 
Certain command line options may further affect path calculations.
See @ref{94a,,-E}, @ref{94b,,-I}, @ref{1362,,-s} and @ref{1186,,-S} for further details.
@end quotation
@end cartouche

@menu
* Environnements virtuels: Environnements virtuels<2>. 
* _pth files:: 
* Embedded Python:: 

@end menu

@node Environnements virtuels<2>,_pth files,,The initialization of the sys path module search path
@anchor{library/sys_path_init virtual-environments}@anchor{44b9}
@subsubsection Environnements virtuels


If Python is run in a virtual environment (as described at @ref{1c8b,,Environnements virtuels et paquets})
then @code{prefix} and @code{exec_prefix} are specific to the virtual environment.

If a @code{pyvenv.cfg} file is found alongside the main executable, or in the
directory one level above the executable, the following variations apply:


@itemize *

@item 
If @code{home} is an absolute path and 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} is not set, this
path is used instead of the path to the main executable when deducing @code{prefix}
and @code{exec_prefix}.
@end itemize

@node _pth files,Embedded Python,Environnements virtuels<2>,The initialization of the sys path module search path
@anchor{library/sys_path_init pth-files}@anchor{44ba}
@subsubsection _pth files


To completely override @ref{3ab,,sys.path} create a @code{._pth} file with the same
name as the shared library or executable (@code{python._pth} or @code{python311._pth}).
The shared library path is always known on Windows, however it may not be
available on other platforms. In the @code{._pth} file specify one line for each path
to add to @ref{3ab,,sys.path}. The file based on the shared library name overrides
the one based on the executable, which allows paths to be restricted for any
program loading the runtime if desired.

Lorsque le fichier existe, toutes les variables de registre et d'environnement sont ignorées, le mode isolé est activé et @ref{c6,,site} n'est pas importé, sauf si une ligne du fichier spécifie @code{import site}. Les chemins et les lignes vides commençant par @code{#} sont ignorés. Chaque chemin d'accès peut être absolu ou relatif à l'emplacement du fichier. Les importations autres que vers `site' ne sont pas autorisées, ni n'importe quelle instruction Python.

Notez que les fichiers @code{.pth} (sans signe souligné précédant le @code{pth}) seront traités normalement par le module @ref{c6,,site} lorsque @code{import site} a été spécifié.

@node Embedded Python,,_pth files,The initialization of the sys path module search path
@anchor{library/sys_path_init embedded-python}@anchor{44bb}
@subsubsection Embedded Python


If Python is embedded within another application @ref{3bc,,Py_InitializeFromConfig()} and
the @ref{39d,,PyConfig} structure can be used to initialize Python. The path specific
details are described at @ref{89a,,Python Path Configuration}.


@subsubheading Voir aussi



@itemize *

@item 
@ref{c0f,,Recherche de modules} for detailed Windows notes.

@item 
@ref{1ce4,,Utilisation de Python sur les plateformes Unix} for Unix details.
@end itemize


@node Services du Langage Python,Services spécifiques à MS Windows,Importer des modules,La bibliothèque standard
@anchor{library/language doc}@anchor{44bc}@anchor{library/language language}@anchor{44bd}@anchor{library/language python-language-services}@anchor{44be}
@section Services du Langage Python


Python fournit quelques modules pour vous aider à travailler avec le langage Python lui-même. Ces modules gèrent entre autres l'analyse lexicale, l'analyse syntaxique, et le désassemblage de `bytecode'.

Ces modules sont :

@menu
* ast: ast --- Abstract Syntax Trees. Abstract Syntax Trees
* symtable: symtable --- Access to the compiler's symbol tables. Access to the compiler's symbol tables
* token: token --- Constants used with Python parse trees. Constants used with Python parse trees
* keyword: keyword --- Testing for Python keywords. Testing for Python keywords
* tokenize: tokenize --- Tokenizer for Python source. Tokenizer for Python source
* tabnanny: tabnanny --- Detection of ambiguous indentation. Detection of ambiguous indentation
* pyclbr: pyclbr --- Python module browser support. Python module browser support
* py_compile: py_compile --- Compile Python source files. Compile Python source files
* compileall: compileall --- Byte-compile Python libraries. Byte-compile Python libraries
* dis: dis --- Disassembler for Python bytecode. Disassembler for Python bytecode
* pickletools: pickletools --- Tools for pickle developers. Tools for pickle developers

@end menu

@node ast --- Abstract Syntax Trees,symtable --- Access to the compiler's symbol tables,,Services du Langage Python
@anchor{library/ast doc}@anchor{44bf}@anchor{library/ast ast-abstract-syntax-trees}@anchor{44c0}@anchor{library/ast module-ast}@anchor{8}
@subsection @code{ast} --- Abstract Syntax Trees


@geindex module; ast

@c import ast

`Code source :' Lib/ast.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/ast.py}


__________________________________________________________________


Le module @ref{8,,ast} permet aux applications Python de traiter les arbres syntaxiques, dérivés directement de la grammaire abstraite du langage. On peut notamment déterminer dans un programme la forme de chaque élément de grammaire, qui est susceptible d'être modifiée par les nouvelles versions de Python.

Un arbre syntaxique abstrait peut être généré en passant l'option @ref{44c1,,ast.PyCF_ONLY_AST} à la fonction native @ref{190,,compile()}, ou à l'aide de la fonction auxiliaire @ref{1a6,,parse()} fournie par ce module. Le résultat est un arbre composé d'objets dont les classes héritent toutes de @ref{1a4,,ast.AST}. On peut compiler les arbres en code objet Python à l'aide de la fonction native @ref{190,,compile()}.

@menu
* Grammaire abstraite:: 
* Classes de nœuds:: 
* Outils du module ast:: 
* Options du compilateur:: 
* Utilisation en ligne de commande: Utilisation en ligne de commande<4>. 

@end menu

@node Grammaire abstraite,Classes de nœuds,,ast --- Abstract Syntax Trees
@anchor{library/ast abstract-grammar}@anchor{44c2}@anchor{library/ast id1}@anchor{44c3}
@subsubsection Grammaire abstraite


La grammaire abstraite est actuellement définie comme suit :

@example
-- ASDL's 4 builtin types are:
-- identifier, int, string, constant

module Python
@{
    mod = Module(stmt* body, type_ignore* type_ignores)
        | Interactive(stmt* body)
        | Expression(expr body)
        | FunctionType(expr* argtypes, expr returns)

    stmt = FunctionDef(identifier name, arguments args,
                       stmt* body, expr* decorator_list, expr? returns,
                       string? type_comment, type_param* type_params)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns,
                             string? type_comment, type_param* type_params)

          | ClassDef(identifier name,
             expr* bases,
             keyword* keywords,
             stmt* body,
             expr* decorator_list,
             type_param* type_params)
          | Return(expr? value)

          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
          | TypeAlias(expr name, type_param* type_params, expr value)
          | AugAssign(expr target, operator op, expr value)
          -- 'simple' indicates that we annotate simple name without parens
          | AnnAssign(expr target, expr annotation, expr? value, int simple)

          -- use 'orelse' because else is a keyword in target languages
          | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | While(expr test, stmt* body, stmt* orelse)
          | If(expr test, stmt* body, stmt* orelse)
          | With(withitem* items, stmt* body, string? type_comment)
          | AsyncWith(withitem* items, stmt* body, string? type_comment)

          | Match(expr subject, match_case* cases)

          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)

          | Import(alias* names)
          | ImportFrom(identifier? module, alias* names, int? level)

          | Global(identifier* names)
          | Nonlocal(identifier* names)
          | Expr(expr value)
          | Pass | Break | Continue

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

          -- BoolOp() can use left & right?
    expr = BoolOp(boolop op, expr* values)
         | NamedExpr(expr target, expr value)
         | BinOp(expr left, operator op, expr right)
         | UnaryOp(unaryop op, expr operand)
         | Lambda(arguments args, expr body)
         | IfExp(expr test, expr body, expr orelse)
         | Dict(expr* keys, expr* values)
         | Set(expr* elts)
         | ListComp(expr elt, comprehension* generators)
         | SetComp(expr elt, comprehension* generators)
         | DictComp(expr key, expr value, comprehension* generators)
         | GeneratorExp(expr elt, comprehension* generators)
         -- the grammar constrains where yield expressions can occur
         | Await(expr value)
         | Yield(expr? value)
         | YieldFrom(expr value)
         -- need sequences for compare to distinguish between
         -- x < 4 < 3 and (x < 4) < 3
         | Compare(expr left, cmpop* ops, expr* comparators)
         | Call(expr func, expr* args, keyword* keywords)
         | FormattedValue(expr value, int conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | Constant(constant value, string? kind)

         -- the following expression can appear in assignment context
         | Attribute(expr value, identifier attr, expr_context ctx)
         | Subscript(expr value, expr slice, expr_context ctx)
         | Starred(expr value, expr_context ctx)
         | Name(identifier id, expr_context ctx)
         | List(expr* elts, expr_context ctx)
         | Tuple(expr* elts, expr_context ctx)

         -- can appear only in Subscript
         | Slice(expr? lower, expr? upper, expr? step)

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    expr_context = Load | Store | Del

    boolop = And | Or

    operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
                 | RShift | BitOr | BitXor | BitAnd | FloorDiv

    unaryop = Invert | Not | UAdd | USub

    cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn

    comprehension = (expr target, expr iter, expr* ifs, int is_async)

    excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
                    attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
                 expr* kw_defaults, arg? kwarg, expr* defaults)

    arg = (identifier arg, expr? annotation, string? type_comment)
           attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- keyword arguments supplied to call (NULL identifier for **kwargs)
    keyword = (identifier? arg, expr value)
               attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- import name with optional 'as' alias.
    alias = (identifier name, identifier? asname)
             attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    withitem = (expr context_expr, expr? optional_vars)

    match_case = (pattern pattern, expr? guard, stmt* body)

    pattern = MatchValue(expr value)
            | MatchSingleton(constant value)
            | MatchSequence(pattern* patterns)
            | MatchMapping(expr* keys, pattern* patterns, identifier? rest)
            | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)

            | MatchStar(identifier? name)
            -- The optional "rest" MatchMapping parameter handles capturing extra mapping keys

            | MatchAs(pattern? pattern, identifier? name)
            | MatchOr(pattern* patterns)

             attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)

    type_ignore = TypeIgnore(int lineno, string tag)

    type_param = TypeVar(identifier name, expr? bound, expr? default_value)
               | ParamSpec(identifier name, expr? default_value)
               | TypeVarTuple(identifier name, expr? default_value)
               attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
@}
@end example

@node Classes de nœuds,Outils du module ast,Grammaire abstraite,ast --- Abstract Syntax Trees
@anchor{library/ast node-classes}@anchor{44c4}
@subsubsection Classes de nœuds


@geindex AST (classe dans ast)
@anchor{library/ast ast AST}@anchor{1a4}
@deffn {Classe} ast.AST

This is the base of all AST node classes.  The actual node classes are
derived from the @code{Parser/Python.asdl} file, which is reproduced
@ref{44c2,,above}.  They are defined in the @code{_ast} C
module and re-exported in @ref{8,,ast}.

Il y a une classe définie pour chacun des symboles présents à gauche dans la grammaire abstraite (par exemple @code{ast.stmt} ou @code{ast.expr}). En plus de cela, une classe est définie pour chacun des constructeurs présentés à droite ; ces classes héritent des classes situées à leur gauche dans l'arbre. Par exemple, la classe @ref{195b,,ast.BinOp} hérite de la classe @code{ast.expr}. Pour les règles de réécriture avec alternatives (les « sommes »), la classe de la partie gauche est abstraite : seules les classes de nœuds à droite sont instanciées.

@geindex ? (question mark);in AST grammar

@geindex * (asterisk);in AST grammar

@geindex _fields (attribut ast.AST)
@anchor{library/ast ast AST _fields}@anchor{152a}
@deffn {Attribut} _fields

Each concrete class has an attribute @code{_fields} which gives the names
of all child nodes.

Chaque instance d'une classe concrète possède un attribut pour chaque nœud enfant, du type défini par la grammaire. Par exemple, les instances @ref{195b,,ast.BinOp} possèdent un attribut @code{left} de type @code{ast.expr}.

Si un attribut est marqué comme optionnel dans la grammaire (avec un point d'interrogation @code{?}), sa valeur peut être @code{None}. S'il peut avoir zéro, une ou plusieurs valeurs (ce qui est marqué par un astérisque @code{*}), elles sont regroupées dans une liste Python. Tous les attributs possibles doivent être présents et avoir une valeur valide pour compiler un arbre syntaxique avec @ref{190,,compile()}.
@end deffn

@geindex _field_types (attribut ast.AST)
@anchor{library/ast ast AST _field_types}@anchor{1a5}
@deffn {Attribut} _field_types

The @code{_field_types} attribute on each concrete class is a dictionary
mapping field names (as also listed in @ref{152a,,_fields}) to their types.

@example
>>> ast.TypeVar._field_types
@{'name': <class 'str'>, 'bound': ast.expr | None, 'default_value': ast.expr | None@}
@end example


Ajouté dans la version 3.13.

@end deffn

@geindex lineno (attribut ast.AST)
@geindex col_offset (attribut ast.AST)
@geindex end_lineno (attribut ast.AST)
@geindex end_col_offset (attribut ast.AST)
@anchor{library/ast ast AST lineno}@anchor{44c5}
@deffn {Attribut} lineno
@anchor{library/ast ast AST col_offset}@anchor{44c6}
@deffnx {Attribut} col_offset
@anchor{library/ast ast AST end_lineno}@anchor{44c7}
@deffnx {Attribut} end_lineno
@anchor{library/ast ast AST end_col_offset}@anchor{44c8}
@deffnx {Attribut} end_col_offset

Instances of @code{ast.expr} and @code{ast.stmt} subclasses have
@ref{44c5,,lineno}, @ref{44c6,,col_offset}, @ref{44c7,,end_lineno}, and
@ref{44c8,,end_col_offset} attributes.  The @ref{44c5,,lineno} and @ref{44c7,,end_lineno}
are the first and last line numbers of source text span (1-indexed so the
first line is line 1) and the @ref{44c6,,col_offset} and @ref{44c8,,end_col_offset}
are the corresponding UTF-8 byte offsets of the first and last tokens that
generated the node. The UTF-8 offset is recorded because the parser uses
UTF-8 internally.

Les décalages `end…' ne sont pas obligatoires ni nécessaires au compilateur. `end_col_offset' pointe `après' le dernier lexème. On peut donc obtenir la partie du code source ayant donné lieu à une expression avec @code{ligne_source[nœud.col_offset : nœud.end_col_offset]}.
@end deffn

Le constructeur d'une classe nommée @code{ast.T} analyse ses arguments comme suit :


@itemize *

@item 
S'il y a des arguments positionnels, il doit y avoir autant de termes dans @code{T._fields} ; ils sont assignés comme attributs portant ces noms.

@item 
S'il y a des arguments nommés, ils définissent les attributs de mêmes noms avec les valeurs données.
@end itemize

Par exemple, pour créer et peupler un nœud @ref{44c9,,ast.UnaryOp}, on peut utiliser

@example
node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)
@end example

If a field that is optional in the grammar is omitted from the constructor,
it defaults to @code{None}. If a list field is omitted, it defaults to the empty
list. If a field of type @code{ast.expr_context} is omitted, it defaults to
@ref{1a2,,Load()}. If any other field is omitted, a @ref{1a3,,DeprecationWarning} is raised
and the AST node will not have this field. In Python 3.15, this condition will
raise an error.
@end deffn


Modifié dans la version 3.8: toutes les constantes sont désormais représentées par des instances de @ref{2b6,,ast.Constant}.



Modifié dans la version 3.9: Simple indices are represented by their value, extended slices are
represented as tuples.



Obsolète depuis la version 3.8: Old classes @code{ast.Num}, @code{ast.Str}, @code{ast.Bytes},
@code{ast.NameConstant} and @code{ast.Ellipsis} are still available,
but they will be removed in future Python releases.  In the meantime,
instantiating them will return an instance of a different class.



Obsolète depuis la version 3.9: Old classes @code{ast.Index} and @code{ast.ExtSlice} are still
available, but they will be removed in future Python releases.
In the meantime, instantiating them will return an instance of
a different class.



Deprecated since version 3.13, will be removed in version 3.15: Previous versions of Python allowed the creation of AST nodes that were missing
required fields. Similarly, AST node constructors allowed arbitrary keyword
arguments that were set as attributes of the AST node, even if they did not
match any of the fields of the AST node. This behavior is deprecated and will
be removed in Python 3.15.


@cartouche
@quotation Note 
Les descriptions individuelles des classes de nœuds dans la prochaine section sont au départ adaptées du merveilleux projet Green Tree Snakes@footnote{https://greentreesnakes.readthedocs.io/en/latest/}, porté par de nombreux contributeurs.
@end quotation
@end cartouche

@menu
* Root nodes:: 
* Littéraux: Littéraux<3>. 
* Variables:: 
* Expressions: Expressions<2>. 
* Instructions: Instructions<2>. 
* Contrôle de l'exécution:: 
* Pattern matching:: 
* Type parameters:: 
* Définition de fonctions et de classes:: 
* async et await:: 

@end menu

@node Root nodes,Littéraux<3>,,Classes de nœuds
@anchor{library/ast ast-root-nodes}@anchor{44ca}@anchor{library/ast root-nodes}@anchor{44cb}
@subsubsection Root nodes


@geindex Module (classe dans ast)
@anchor{library/ast ast Module}@anchor{44cc}
@deffn {Classe} ast.Module (body, type_ignores)

A Python module, as with @ref{20c4,,file input}.
Node type generated by @ref{1a6,,ast.parse()} in the default @code{"exec"} `mode'.

@code{body} is a @ref{5fc,,list} of the module's @ref{44cd,,Instructions}.

@code{type_ignores} is a @ref{5fc,,list} of the module's type ignore comments;
see @ref{1a6,,ast.parse()} for more details.

@example
>>> print(ast.dump(ast.parse('x = 1'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='x', ctx=Store())],
            value=Constant(value=1))])
@end example
@end deffn

@geindex Expression (classe dans ast)
@anchor{library/ast ast Expression}@anchor{44ce}
@deffn {Classe} ast.Expression (body)

A single Python @ref{20ca,,expression input}.
Node type generated by @ref{1a6,,ast.parse()} when `mode' is @code{"eval"}.

@code{body} is a single node,
one of the @ref{44cf,,expression types}.

@example
>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))
@end example
@end deffn

@geindex Interactive (classe dans ast)
@anchor{library/ast ast Interactive}@anchor{44d0}
@deffn {Classe} ast.Interactive (body)

A single @ref{20c7,,interactive input}, like in @ref{16e,,Mode interactif}.
Node type generated by @ref{1a6,,ast.parse()} when `mode' is @code{"single"}.

@code{body} is a @ref{5fc,,list} of @ref{44cd,,statement nodes}.

@example
>>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))
Interactive(
    body=[
        Assign(
            targets=[
                Name(id='x', ctx=Store())],
            value=Constant(value=1)),
        Assign(
            targets=[
                Name(id='y', ctx=Store())],
            value=Constant(value=2))])
@end example
@end deffn

@geindex FunctionType (classe dans ast)
@anchor{library/ast ast FunctionType}@anchor{44d1}
@deffn {Classe} ast.FunctionType (argtypes, returns)

A representation of an old-style type comments for functions,
as Python versions prior to 3.5 didn't support 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} annotations.
Node type generated by @ref{1a6,,ast.parse()} when `mode' is @code{"func_type"}.

Such type comments would look like this:

@example
def sum_two_number(a, b):
    # type: (int, int) -> int
    return a + b
@end example

@code{argtypes} is a @ref{5fc,,list} of @ref{44cf,,expression nodes}.

@code{returns} is a single @ref{44cf,,expression node}.

@example
>>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4))
FunctionType(
    argtypes=[
        Name(id='int', ctx=Load()),
        Name(id='str', ctx=Load())],
    returns=Subscript(
        value=Name(id='List', ctx=Load()),
        slice=Name(id='int', ctx=Load()),
        ctx=Load()))
@end example


Ajouté dans la version 3.8.

@end deffn

@node Littéraux<3>,Variables,Root nodes,Classes de nœuds
@anchor{library/ast literals}@anchor{44d2}
@subsubsection Littéraux


@geindex Constant (classe dans ast)
@anchor{library/ast ast Constant}@anchor{2b6}
@deffn {Classe} ast.Constant (value)

Valeur constante, contenue dans le champ `value'. Les valeurs possibles sont celles de types simples comme les nombres, les chaînes de caractères, ou encore @code{None}, mais aussi certains conteneurs immuables (`n'-uplets et ensembles figés) lorsque tous leurs éléments sont constants.

@example
>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))
@end example
@end deffn

@geindex FormattedValue (classe dans ast)
@anchor{library/ast ast FormattedValue}@anchor{44d3}
@deffn {Classe} ast.FormattedValue (value, conversion, format_spec)

Champ de formatage dans une chaîne littérale formatée (`f-string'). Ce nœud peut être isolé si la chaîne contient un unique champ et rien d'autre. Sinon, il apparaît dans @ref{1674,,JoinedStr}.


@itemize *

@item 
`value' est un nœud d'expression quelconque (comme un littéral, une variable, ou encore un appel de fonction).

@item 
`conversion' est un entier parmi les valeurs suivantes :


@itemize *

@item 
-1, aucun formatage ;

@item 
115, pour le formatage par @code{str()} correspondant à @code{!s} ;

@item 
114, pour le formatage par @code{repr()} correspondant à @code{!r} ;

@item 
97, pour le formatage par @code{ascii()} correspondant à @code{!a}.
@end itemize

@item 
`format_spec' est un nœud @ref{1674,,JoinedStr} qui précise la manière de formater la valeur. Si aucun formatage particulier n'a été donné, `format_spec' vaut @code{None}. `conversion' et `format_spec' peuvent tout à fait coexister.
@end itemize
@end deffn

@geindex JoinedStr (classe dans ast)
@anchor{library/ast ast JoinedStr}@anchor{1674}
@deffn {Classe} ast.JoinedStr (values)

Chaîne littérale formatée (`f-string'), qui contient une liste de nœuds @ref{44d3,,FormattedValue} et @ref{2b6,,Constant}.

@example
>>> print(ast.dump(ast.parse('f"sin(@{a@}) is @{sin(a):.3@}"', mode='eval'), indent=4))
Expression(
    body=JoinedStr(
        values=[
            Constant(value='sin('),
            FormattedValue(
                value=Name(id='a', ctx=Load()),
                conversion=-1),
            Constant(value=') is '),
            FormattedValue(
                value=Call(
                    func=Name(id='sin', ctx=Load()),
                    args=[
                        Name(id='a', ctx=Load())]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))
@end example
@end deffn

@geindex List (classe dans ast)
@geindex Tuple (classe dans ast)
@anchor{library/ast ast List}@anchor{44d4}
@deffn {Classe} ast.List (elts, ctx)
@anchor{library/ast ast Tuple}@anchor{44d5}
@deffnx {Classe} ast.Tuple (elts, ctx)

Liste ou `n'-uplet, dont les éléments sont rassemblés dans la liste `elts'. `ctx' est une instance de @ref{44d6,,Store} si la liste ou le `n'-uplet est la cible d'une affectation (par exemple @code{(x, y) = quelque_chose}). Sinon, c'est une instance de @ref{1a2,,Load}.

@example
>>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))
Expression(
    body=List(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))
>>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))
Expression(
    body=Tuple(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))
@end example
@end deffn

@geindex Set (classe dans ast)
@anchor{library/ast ast Set}@anchor{44d7}
@deffn {Classe} ast.Set (elts)

Ensemble. `elts' est la liste de ses éléments.

@example
>>> print(ast.dump(ast.parse('@{1, 2, 3@}', mode='eval'), indent=4))
Expression(
    body=Set(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)]))
@end example
@end deffn

@geindex Dict (classe dans ast)
@anchor{library/ast ast Dict}@anchor{18ea}
@deffn {Classe} ast.Dict (keys, values)

Dictionnaire. Les listes `keys' et `values' contiennent respectivement les clés et les valeurs. Leurs ordres se correspondent, c'est-à-dire que la valeur associée à l'élément d'indice `i' dans `keys' est à chercher à l'indice `i' de `values'. `keys' et `values' sont donc des équivalents à @code{dictionnaire.keys()} et @code{dictionnaire.values()}.

Si un dictionnaire littéral contient une expression doublement étoilée à déballer, elle est intégrée dans `values', et @code{None} est mis à la place correspondante dans `keys'.

@example
>>> print(ast.dump(ast.parse('@{"a":1, **d@}', mode='eval'), indent=4))
Expression(
    body=Dict(
        keys=[
            Constant(value='a'),
            None],
        values=[
            Constant(value=1),
            Name(id='d', ctx=Load())]))
@end example
@end deffn

@node Variables,Expressions<2>,Littéraux<3>,Classes de nœuds
@anchor{library/ast variables}@anchor{44d8}
@subsubsection Variables


@geindex Name (classe dans ast)
@anchor{library/ast ast Name}@anchor{18cc}
@deffn {Classe} ast.Name (id, ctx)

Variable, dont le nom est `id' (une chaîne de caractères). `ctx' est de l'un des trois types :
@end deffn

@geindex Load (classe dans ast)
@geindex Store (classe dans ast)
@geindex Del (classe dans ast)
@anchor{library/ast ast Load}@anchor{1a2}
@deffn {Classe} ast.Load
@anchor{library/ast ast Store}@anchor{44d6}
@deffnx {Classe} ast.Store
@anchor{library/ast ast Del}@anchor{44d9}
@deffnx {Classe} ast.Del

Ces types de contexte distinguent les variables selon qu'elles sont utilisées pour lire la valeur, mettre la variable à une nouvelle valeur, ou supprimer la variable.

@example
>>> print(ast.dump(ast.parse('a'), indent=4))
Module(
    body=[
        Expr(
            value=Name(id='a', ctx=Load()))])

>>> print(ast.dump(ast.parse('a = 1'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store())],
            value=Constant(value=1))])

>>> print(ast.dump(ast.parse('del a'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='a', ctx=Del())])])
@end example
@end deffn

@geindex Starred (classe dans ast)
@anchor{library/ast ast Starred}@anchor{44da}
@deffn {Classe} ast.Starred (value, ctx)

Élément étoilé. `value' est le nœud auquel s'applique l'étoile. Le plus souvent, `value' est une instance de @ref{18cc,,Name}. Ce type est notamment nécessaire pour les appels de fonction avec déballage d'arguments (par exemple @code{fonction(*args)} ; voir aussi @ref{44db,,Call}).

@example
>>> print(ast.dump(ast.parse('a, *b = it'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Starred(
                            value=Name(id='b', ctx=Store()),
                            ctx=Store())],
                    ctx=Store())],
            value=Name(id='it', ctx=Load()))])
@end example
@end deffn

@node Expressions<2>,Instructions<2>,Variables,Classes de nœuds
@anchor{library/ast ast-expressions}@anchor{44cf}@anchor{library/ast expressions}@anchor{44dc}
@subsubsection Expressions


@geindex Expr (classe dans ast)
@anchor{library/ast ast Expr}@anchor{44dd}
@deffn {Classe} ast.Expr (value)

Lorsque une expression, comme l'appel d'une fonction, apparaît comme une instruction à elle seule, sans que la valeur ne soit utilisée ou sauvegardée, l'expression est insérée dans ce conteneur. Le type de `value' peut être l'un des autres nœuds décrits dans cette section, ou bien parmi @ref{2b6,,Constant}, @ref{18cc,,Name}, @ref{44de,,Lambda}, @ref{44df,,Yield} et @ref{44e0,,YieldFrom}.

@example
>>> print(ast.dump(ast.parse('-a'), indent=4))
Module(
    body=[
        Expr(
            value=UnaryOp(
                op=USub(),
                operand=Name(id='a', ctx=Load())))])
@end example
@end deffn

@geindex UnaryOp (classe dans ast)
@anchor{library/ast ast UnaryOp}@anchor{44c9}
@deffn {Classe} ast.UnaryOp (op, operand)

Unité lexicale désignant une opération unaire. L'opérateur est `op', l'opérande `operand' est un nœud d'expression quelconque.
@end deffn

@geindex UAdd (classe dans ast)
@geindex USub (classe dans ast)
@geindex Not (classe dans ast)
@geindex Invert (classe dans ast)
@anchor{library/ast ast UAdd}@anchor{44e1}
@deffn {Classe} ast.UAdd
@anchor{library/ast ast USub}@anchor{44e2}
@deffnx {Classe} ast.USub
@anchor{library/ast ast Not}@anchor{44e3}
@deffnx {Classe} ast.Not
@anchor{library/ast ast Invert}@anchor{44e4}
@deffnx {Classe} ast.Invert

Unités lexicales désignant des opérations unaires. @ref{44e3,,Not} correspond au mot-clé @code{not}, @ref{44e4,,Invert} à l'opérateur @code{~}.

@example
>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))
Expression(
    body=UnaryOp(
        op=Not(),
        operand=Name(id='x', ctx=Load())))
@end example
@end deffn

@geindex BinOp (classe dans ast)
@anchor{library/ast ast BinOp}@anchor{195b}
@deffn {Classe} ast.BinOp (left, op, right)

Opération binaire (comme l'addition ou la division). L'opérateur est `op', les opérandes `left' et `right' sont des nœuds d'expression quelconques.

@example
>>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))
Expression(
    body=BinOp(
        left=Name(id='x', ctx=Load()),
        op=Add(),
        right=Name(id='y', ctx=Load())))
@end example
@end deffn

@geindex Add (classe dans ast)
@geindex Sub (classe dans ast)
@geindex Mult (classe dans ast)
@geindex Div (classe dans ast)
@geindex FloorDiv (classe dans ast)
@geindex Mod (classe dans ast)
@geindex Pow (classe dans ast)
@geindex LShift (classe dans ast)
@geindex RShift (classe dans ast)
@geindex BitOr (classe dans ast)
@geindex BitXor (classe dans ast)
@geindex BitAnd (classe dans ast)
@geindex MatMult (classe dans ast)
@anchor{library/ast ast Add}@anchor{44e5}
@deffn {Classe} ast.Add
@anchor{library/ast ast Sub}@anchor{44e6}
@deffnx {Classe} ast.Sub
@anchor{library/ast ast Mult}@anchor{44e7}
@deffnx {Classe} ast.Mult
@anchor{library/ast ast Div}@anchor{44e8}
@deffnx {Classe} ast.Div
@anchor{library/ast ast FloorDiv}@anchor{44e9}
@deffnx {Classe} ast.FloorDiv
@anchor{library/ast ast Mod}@anchor{44ea}
@deffnx {Classe} ast.Mod
@anchor{library/ast ast Pow}@anchor{44eb}
@deffnx {Classe} ast.Pow
@anchor{library/ast ast LShift}@anchor{44ec}
@deffnx {Classe} ast.LShift
@anchor{library/ast ast RShift}@anchor{44ed}
@deffnx {Classe} ast.RShift
@anchor{library/ast ast BitOr}@anchor{44ee}
@deffnx {Classe} ast.BitOr
@anchor{library/ast ast BitXor}@anchor{44ef}
@deffnx {Classe} ast.BitXor
@anchor{library/ast ast BitAnd}@anchor{44f0}
@deffnx {Classe} ast.BitAnd
@anchor{library/ast ast MatMult}@anchor{44f1}
@deffnx {Classe} ast.MatMult

Unités lexicales pour les opérations binaires.
@end deffn

@geindex BoolOp (classe dans ast)
@anchor{library/ast ast BoolOp}@anchor{44f2}
@deffn {Classe} ast.BoolOp (op, values)

Opération booléenne, c'est-à-dire @code{and} ou @code{or}, entre `op' et les éléments de `values'. Les deux opérateurs sont distingués par le type de `op', à savoir @ref{44f3,,And} ou @ref{44f4,,Or}. Les applications successives du même opérateur (comme @code{a or b or c}) sont regroupées dans un nœud unique avec plusieurs éléments dans la liste `values'.

L'opérateur @code{not} n'est pas implémenté ici, mais bien dans @ref{44c9,,UnaryOp}.

@example
>>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4))
Expression(
    body=BoolOp(
        op=Or(),
        values=[
            Name(id='x', ctx=Load()),
            Name(id='y', ctx=Load())]))
@end example
@end deffn

@geindex And (classe dans ast)
@geindex Or (classe dans ast)
@anchor{library/ast ast And}@anchor{44f3}
@deffn {Classe} ast.And
@anchor{library/ast ast Or}@anchor{44f4}
@deffnx {Classe} ast.Or

Unités lexicales pour les opérations booléennes.
@end deffn

@geindex Compare (classe dans ast)
@anchor{library/ast ast Compare}@anchor{44f5}
@deffn {Classe} ast.Compare (left, ops, comparators)

Comparaison de deux valeurs ou plus. `left' est le premier élément de la comparaison, `ops' la liste des opérateurs, et `comparators' la liste des éléments restants de la comparaison.

@example
>>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))
Expression(
    body=Compare(
        left=Constant(value=1),
        ops=[
            LtE(),
            Lt()],
        comparators=[
            Name(id='a', ctx=Load()),
            Constant(value=10)]))
@end example
@end deffn

@geindex Eq (classe dans ast)
@geindex NotEq (classe dans ast)
@geindex Lt (classe dans ast)
@geindex LtE (classe dans ast)
@geindex Gt (classe dans ast)
@geindex GtE (classe dans ast)
@geindex Is (classe dans ast)
@geindex IsNot (classe dans ast)
@geindex In (classe dans ast)
@geindex NotIn (classe dans ast)
@anchor{library/ast ast Eq}@anchor{44f6}
@deffn {Classe} ast.Eq
@anchor{library/ast ast NotEq}@anchor{44f7}
@deffnx {Classe} ast.NotEq
@anchor{library/ast ast Lt}@anchor{44f8}
@deffnx {Classe} ast.Lt
@anchor{library/ast ast LtE}@anchor{44f9}
@deffnx {Classe} ast.LtE
@anchor{library/ast ast Gt}@anchor{44fa}
@deffnx {Classe} ast.Gt
@anchor{library/ast ast GtE}@anchor{44fb}
@deffnx {Classe} ast.GtE
@anchor{library/ast ast Is}@anchor{44fc}
@deffnx {Classe} ast.Is
@anchor{library/ast ast IsNot}@anchor{44fd}
@deffnx {Classe} ast.IsNot
@anchor{library/ast ast In}@anchor{44fe}
@deffnx {Classe} ast.In
@anchor{library/ast ast NotIn}@anchor{44ff}
@deffnx {Classe} ast.NotIn

Unités lexicales pour les comparaisons.
@end deffn

@geindex Call (classe dans ast)
@anchor{library/ast ast Call}@anchor{44db}
@deffn {Classe} ast.Call (func, args, keywords)

Appel d'une fonction. Le nœud `func', représentant la fonction appelée, est habituellement de type @ref{18cc,,Name} ou @ref{4500,,Attribute}. Les arguments sont contenus dans :


@itemize *

@item 
`args', la liste des arguments passés sans les nommer (arguments positionnels) ;

@item 
@code{keywords} holds a list of @ref{4501,,keyword} objects representing
arguments passed by keyword.
@end itemize

The @code{args} and @code{keywords} arguments are optional and default to empty lists.

@example
>>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), indent=4))
Expression(
    body=Call(
        func=Name(id='func', ctx=Load()),
        args=[
            Name(id='a', ctx=Load()),
            Starred(
                value=Name(id='d', ctx=Load()),
                ctx=Load())],
        keywords=[
            keyword(
                arg='b',
                value=Name(id='c', ctx=Load())),
            keyword(
                value=Name(id='e', ctx=Load()))]))
@end example
@end deffn

@geindex keyword (classe dans ast)
@anchor{library/ast ast keyword}@anchor{4501}
@deffn {Classe} ast.keyword (arg, value)

A keyword argument to a function call or class definition. @code{arg} is a raw
string of the parameter name, @code{value} is a node to pass in.
@end deffn

@geindex IfExp (classe dans ast)
@anchor{library/ast ast IfExp}@anchor{4502}
@deffn {Classe} ast.IfExp (test, body, orelse)

Expression ternaire (@code{a if b else c}). Chaque champ contient un unique nœud. Dans l'exemple suivant, les trois sont de la classe @ref{18cc,,Name}.

@example
>>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4))
Expression(
    body=IfExp(
        test=Name(id='b', ctx=Load()),
        body=Name(id='a', ctx=Load()),
        orelse=Name(id='c', ctx=Load())))
@end example
@end deffn

@geindex Attribute (classe dans ast)
@anchor{library/ast ast Attribute}@anchor{4500}
@deffn {Classe} ast.Attribute (value, attr, ctx)

Accès à un attribut (comme @code{d.keys}). `value' est un nœud, souvent de la classe @ref{18cc,,Name}. `attr' est le nom de l'attribut, sous forme de chaîne de caractères. `ctx' est de classe @ref{1a2,,Load}, @ref{44d6,,Store} ou @ref{44d9,,Del} selon le type de l'action effectuée sur l'attribut.

@example
>>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4))
Expression(
    body=Attribute(
        value=Name(id='snake', ctx=Load()),
        attr='colour',
        ctx=Load()))
@end example
@end deffn

@geindex NamedExpr (classe dans ast)
@anchor{library/ast ast NamedExpr}@anchor{4503}
@deffn {Classe} ast.NamedExpr (target, value)

Expression d'affectation. Ces nœuds proviennent de l'opérateur « morse » @code{:=}. Contrairement à @ref{4504,,Assign}, dont le premier argument est une liste qui peut contenir plusieurs cibles, les arguments `target' et `value' sont ici des nœuds simples.

@example
>>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))
Expression(
    body=NamedExpr(
        target=Name(id='x', ctx=Store()),
        value=Constant(value=4)))
@end example


Ajouté dans la version 3.8.

@end deffn

@menu
* Indiçage:: 
* Compréhensions:: 

@end menu

@node Indiçage,Compréhensions,,Expressions<2>
@anchor{library/ast subscripting}@anchor{4505}
@subsubsection Indiçage


@geindex Subscript (classe dans ast)
@anchor{library/ast ast Subscript}@anchor{4506}
@deffn {Classe} ast.Subscript (value, slice, ctx)

Accès à un indice, par exemple @code{liste[1]}. `value' est l'objet où l'indice est pris, donc la plupart du temps une séquence ou une table associative. `slice' est soit un indice, soit une tranche, soit une clé. Les instances de @ref{44d5,,Tuple} pour `slice' peuvent contenir des objets @ref{4507,,Slice}. `ctx' est de type @ref{1a2,,Load}, @ref{44d6,,Store} ou @ref{44d9,,Del} selon l'action appliquée à l'indice.

@example
>>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Tuple(
            elts=[
                Slice(
                    lower=Constant(value=1),
                    upper=Constant(value=2)),
                Constant(value=3)],
            ctx=Load()),
        ctx=Load()))
@end example
@end deffn

@geindex Slice (classe dans ast)
@anchor{library/ast ast Slice}@anchor{4507}
@deffn {Classe} ast.Slice (lower, upper, step)

Tranches normales (de la forme @code{début:fin} ou @code{début:fin:pas}). Les instances de cette classe ne peuvent apparaître que dans le champ `slice' d'un @ref{4506,,Subscript}, que ce soit directement ou en tant qu'élément d'un @ref{44d5,,Tuple}.

@example
>>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Slice(
            lower=Constant(value=1),
            upper=Constant(value=2)),
        ctx=Load()))
@end example
@end deffn

@node Compréhensions,,Indiçage,Expressions<2>
@anchor{library/ast comprehensions}@anchor{4508}
@subsubsection Compréhensions


@geindex ListComp (classe dans ast)
@geindex SetComp (classe dans ast)
@geindex GeneratorExp (classe dans ast)
@geindex DictComp (classe dans ast)
@anchor{library/ast ast ListComp}@anchor{4509}
@deffn {Classe} ast.ListComp (elt, generators)
@anchor{library/ast ast SetComp}@anchor{450a}
@deffnx {Classe} ast.SetComp (elt, generators)
@anchor{library/ast ast GeneratorExp}@anchor{450b}
@deffnx {Classe} ast.GeneratorExp (elt, generators)
@anchor{library/ast ast DictComp}@anchor{450c}
@deffnx {Classe} ast.DictComp (key, value, generators)

Liste, ensemble ou dictionnaire en compréhension, ou expression génératrice. `elt' est l'expression avant le premier @code{for}, évaluée à chaque itération. Il est remplacé par `key' (expression pour la clé) et `value' (expression pour la valeur) dans le cas des dictionnaires.

`generators' est une liste de nœuds @ref{450d,,comprehension}.

@example
>>> print(ast.dump(
...     ast.parse('[x for x in numbers]', mode='eval'),
...     indent=4,
... ))
Expression(
    body=ListComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                is_async=0)]))
>>> print(ast.dump(
...     ast.parse('@{x: x**2 for x in numbers@}', mode='eval'),
...     indent=4,
... ))
Expression(
    body=DictComp(
        key=Name(id='x', ctx=Load()),
        value=BinOp(
            left=Name(id='x', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                is_async=0)]))
>>> print(ast.dump(
...     ast.parse('@{x for x in numbers@}', mode='eval'),
...     indent=4,
... ))
Expression(
    body=SetComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                is_async=0)]))
@end example
@end deffn

@geindex comprehension (classe dans ast)
@anchor{library/ast ast comprehension}@anchor{450d}
@deffn {Classe} ast.comprehension (target, iter, ifs, is_async)

Une clause @code{for} à l'intérieur d'une compréhension. `iter' est l'objet à parcourir, `target' est la cible de l'affectation qui se produit à chaque itération (la plupart du temps un nœud @ref{18cc,,Name} ou @ref{44d5,,Tuple}). `ifs' contient les tests  qui décident si l'élément doit être inséré. C'est une liste, car chaque @code{for} peut être suivi de plusieurs @code{if}.

`is_async' est une valeur booléenne sous forme d'entier, 0 ou 1, qui indique si la compréhension est asynchrone, c'est-à-dire qu'elle a été écrite avec @code{async for} au lieu de @code{for}.

@example
>>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', mode='eval'),
...                indent=4)) # Multiple comprehensions in one.
Expression(
    body=ListComp(
        elt=Call(
            func=Name(id='ord', ctx=Load()),
            args=[
                Name(id='c', ctx=Load())]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file', ctx=Load()),
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line', ctx=Load()),
                is_async=0)]))

>>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'),
...                indent=4)) # generator comprehension
Expression(
    body=GeneratorExp(
        elt=BinOp(
            left=Name(id='n', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='n', ctx=Store()),
                iter=Name(id='it', ctx=Load()),
                ifs=[
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Lt()],
                        comparators=[
                            Constant(value=10)])],
                is_async=0)]))

>>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),
...                indent=4)) # Async comprehension
Expression(
    body=ListComp(
        elt=Name(id='i', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='i', ctx=Store()),
                iter=Name(id='soc', ctx=Load()),
                is_async=1)]))
@end example
@end deffn

@node Instructions<2>,Contrôle de l'exécution,Expressions<2>,Classes de nœuds
@anchor{library/ast ast-statements}@anchor{44cd}@anchor{library/ast statements}@anchor{450e}
@subsubsection Instructions


@geindex Assign (classe dans ast)
@anchor{library/ast ast Assign}@anchor{4504}
@deffn {Classe} ast.Assign (targets, value, type_comment)

Affectation. `targets' est une liste de nœuds, `value' est simplement un nœud.

S'il y a plusieurs nœuds dans `targets', ils sont tous pris comme des cibles auxquelles est affectée la même expression. Le déballage de séquences est représenté par des nœuds @ref{44d5,,Tuple} ou @ref{44d4,,List} comme éléments de `targets'.

@geindex type_comment (attribut ast.Assign)
@anchor{library/ast ast Assign type_comment}@anchor{450f}
@deffn {Attribut} type_comment

Le champ facultatif `type_comment' contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.
@end deffn

@example
>>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store()),
                Name(id='b', ctx=Store())],
            value=Constant(value=1))])

>>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Name(id='b', ctx=Store())],
                    ctx=Store())],
            value=Name(id='c', ctx=Load()))])
@end example
@end deffn

@geindex AnnAssign (classe dans ast)
@anchor{library/ast ast AnnAssign}@anchor{4510}
@deffn {Classe} ast.AnnAssign (target, annotation, value, simple)

An assignment with a type annotation. @code{target} is a single node and can
be a @ref{18cc,,Name}, an @ref{4500,,Attribute} or a @ref{4506,,Subscript}.
@code{annotation} is the annotation, such as a @ref{2b6,,Constant} or @ref{18cc,,Name}
node. @code{value} is a single optional node.

@code{simple} is always either 0 (indicating a "complex" target) or 1
(indicating a "simple" target). A "simple" target consists solely of a
@ref{18cc,,Name} node that does not appear between parentheses; all other
targets are considered complex. Only simple targets appear in
the @code{__annotations__} dictionary of modules and classes.

@example
>>> print(ast.dump(ast.parse('c: int'), indent=4))
Module(
    body=[
        AnnAssign(
            target=Name(id='c', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=1)])

>>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with parenthesis
Module(
    body=[
        AnnAssign(
            target=Name(id='a', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            value=Constant(value=1),
            simple=0)])

>>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation
Module(
    body=[
        AnnAssign(
            target=Attribute(
                value=Name(id='a', ctx=Load()),
                attr='b',
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)])

>>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation
Module(
    body=[
        AnnAssign(
            target=Subscript(
                value=Name(id='a', ctx=Load()),
                slice=Constant(value=1),
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)])
@end example
@end deffn

@geindex AugAssign (classe dans ast)
@anchor{library/ast ast AugAssign}@anchor{4511}
@deffn {Classe} ast.AugAssign (target, op, value)

Affectation incrémentale, par exemple @code{a += 1}. Dans l'exemple qui suit, `target' est un nœud de type @ref{18cc,,Name} avec le nom @code{'x'} (de contexte @ref{44d6,,Store}), `op' est une instance de @ref{44e5,,Add}, et `value' est un nœud @ref{2b6,,Constant} contenant la valeur 1.

The @code{target} attribute cannot be of class @ref{44d5,,Tuple} or @ref{44d4,,List},
unlike the targets of @ref{4504,,Assign}.

@example
>>> print(ast.dump(ast.parse('x += 2'), indent=4))
Module(
    body=[
        AugAssign(
            target=Name(id='x', ctx=Store()),
            op=Add(),
            value=Constant(value=2))])
@end example
@end deffn

@geindex Raise (classe dans ast)
@anchor{library/ast ast Raise}@anchor{4512}
@deffn {Classe} ast.Raise (exc, cause)

Instruction @code{raise}. `exc' est l'exception à lever, la plupart du temps un nœud de type @ref{44db,,Call} ou @ref{18cc,,Name}. Ce champ vaut @code{None} dans le cas d'un @code{raise} sans rien d'autre. Le champ facultatif `cause' correspond à la partie après le @code{from} dans @code{raise ... from ...}.

@example
>>> print(ast.dump(ast.parse('raise x from y'), indent=4))
Module(
    body=[
        Raise(
            exc=Name(id='x', ctx=Load()),
            cause=Name(id='y', ctx=Load()))])
@end example
@end deffn

@geindex Assert (classe dans ast)
@anchor{library/ast ast Assert}@anchor{4513}
@deffn {Classe} ast.Assert (test, msg)

Assertion. `test' est la condition, par exemple un nœud @ref{44f5,,Compare}. `msg' est le message d'erreur affiché si le test s'évalue comme faux.

@example
>>> print(ast.dump(ast.parse('assert x,y'), indent=4))
Module(
    body=[
        Assert(
            test=Name(id='x', ctx=Load()),
            msg=Name(id='y', ctx=Load()))])
@end example
@end deffn

@geindex Delete (classe dans ast)
@anchor{library/ast ast Delete}@anchor{4514}
@deffn {Classe} ast.Delete (targets)

Instruction @code{del}. Les éléments à supprimer sont rassemblés dans la liste `target'. Ce sont généralement des nœuds de type @ref{18cc,,Name}, @ref{4500,,Attribute} ou @ref{4506,,Subscript}.

@example
>>> print(ast.dump(ast.parse('del x,y,z'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='x', ctx=Del()),
                Name(id='y', ctx=Del()),
                Name(id='z', ctx=Del())])])
@end example
@end deffn

@geindex Pass (classe dans ast)
@anchor{library/ast ast Pass}@anchor{4515}
@deffn {Classe} ast.Pass

Instruction @code{pass}.

@example
>>> print(ast.dump(ast.parse('pass'), indent=4))
Module(
    body=[
        Pass()])
@end example
@end deffn

@geindex TypeAlias (classe dans ast)
@anchor{library/ast ast TypeAlias}@anchor{166b}
@deffn {Classe} ast.TypeAlias (name, type_params, value)

A @ref{43d,,type alias} created through the @ref{421,,type}
statement. @code{name} is the name of the alias, @code{type_params} is a list of
@ref{4516,,type parameters}, and @code{value} is the value of the
type alias.

@example
>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            value=Name(id='int', ctx=Load()))])
@end example


Ajouté dans la version 3.12.

@end deffn

Il existe d'autres instructions, qui ne peuvent apparaître que dans certains contextes spécifiques comme l'intérieur d'une fonction ou d'une boucle. Elles sont décrites dans d'autres sections de ce document.

@menu
* Importations:: 

@end menu

@node Importations,,,Instructions<2>
@anchor{library/ast imports}@anchor{4517}
@subsubsection Importations


@geindex Import (classe dans ast)
@anchor{library/ast ast Import}@anchor{4518}
@deffn {Classe} ast.Import (names)

Instruction @code{import}. `names' prend la forme d'une liste de nœuds @ref{184c,,alias}.

@example
>>> print(ast.dump(ast.parse('import x,y,z'), indent=4))
Module(
    body=[
        Import(
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')])])
@end example
@end deffn

@geindex ImportFrom (classe dans ast)
@anchor{library/ast ast ImportFrom}@anchor{4519}
@deffn {Classe} ast.ImportFrom (module, names, level)

Instruction @code{from ... import ...}. La partie après @code{from} est mise dans `module' comme une simple chaîne de caractères. Dans le cas des importations relatives, comme @code{from ..module import quelque_chose}, `module' ne contient pas les points au début. Dans les instructions de la forme @code{from . import toto}, `module' vaut @code{None}. `level' est le niveau d'importation relative sous forme d'entier (0 pour les importations absolues).

@example
>>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))
Module(
    body=[
        ImportFrom(
            module='y',
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')],
            level=0)])
@end example
@end deffn

@geindex alias (classe dans ast)
@anchor{library/ast ast alias}@anchor{184c}
@deffn {Classe} ast.alias (name, asname)

Correspond à @code{... as ...} dans une importation. `name' et `asname' sont de simples chaînes de caractères, qui correspondent aux deux parties de @code{... as ...}. Dans les instructions sans @code{as} (où le module n'est pas renommé), `asname' vaut @code{None}.

@example
>>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))
Module(
    body=[
        ImportFrom(
            module='foo.bar',
            names=[
                alias(name='a', asname='b'),
                alias(name='c')],
            level=2)])
@end example
@end deffn

@node Contrôle de l'exécution,Pattern matching,Instructions<2>,Classes de nœuds
@anchor{library/ast control-flow}@anchor{451a}
@subsubsection Contrôle de l'exécution


@cartouche
@quotation Note 
Si une clause facultative comme @code{else} est absente, le champ correspondant dans l'arbre est une liste vide.
@end quotation
@end cartouche

@geindex If (classe dans ast)
@anchor{library/ast ast If}@anchor{451b}
@deffn {Classe} ast.If (test, body, orelse)

Instruction @code{if}. La condition, `test', est un nœud, par exemple une instance de @ref{44f5,,Compare}. `body' est la liste des instructions du bloc. `orelse' contient les instructions dans le @code{else} (liste vide s'il n'y a pas de @code{else}).

Les clauses @code{elif} ne possèdent pas de représentation particulière. Elles sont simplement mises dans le `orelse' du @code{if} ou @code{elif} précédent, comme nœuds de type @ref{451b,,If}.

@example
>>> print(ast.dump(ast.parse("""
... if x:
...    ...
... elif y:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        If(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                If(
                    test=Name(id='y', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))],
                    orelse=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example
@end deffn

@geindex For (classe dans ast)
@anchor{library/ast ast For}@anchor{451c}
@deffn {Classe} ast.For (target, iter, body, orelse, type_comment)

A @code{for} loop. @code{target} holds the variable(s) the loop assigns to, as a
single @ref{18cc,,Name}, @ref{44d5,,Tuple}, @ref{44d4,,List}, @ref{4500,,Attribute} or
@ref{4506,,Subscript} node. @code{iter} holds the item to be looped over, again
as a single node. @code{body} and @code{orelse} contain lists of nodes to execute.
Those in @code{orelse} are executed if the loop finishes normally, rather than
via a @code{break} statement.

@geindex type_comment (attribut ast.For)
@anchor{library/ast ast For type_comment}@anchor{451d}
@deffn {Attribut} type_comment

Le champ facultatif `type_comment' contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.
@end deffn

@example
>>> print(ast.dump(ast.parse("""
... for x in y:
...     ...
... else:
...     ...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='x', ctx=Store()),
            iter=Name(id='y', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex While (classe dans ast)
@anchor{library/ast ast While}@anchor{451e}
@deffn {Classe} ast.While (test, body, orelse)

Boucle @code{while}. `test' est la condition évaluée à chaque itération, par exemple un nœud @ref{44f5,,Compare}. `body' contient les instructions du bloc, et `orelse' celles d'un éventuel bloc @code{else}, exécuté lorsque la boucle termine parce que la condition devient fausse et non pas à cause d'une instruction @code{break}.

@example
>> print(ast.dump(ast.parse("""
... while x:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        While(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex Break (classe dans ast)
@geindex Continue (classe dans ast)
@anchor{library/ast ast Break}@anchor{451f}
@deffn {Classe} ast.Break
@anchor{library/ast ast Continue}@anchor{4520}
@deffnx {Classe} ast.Continue

Instructions @code{break} et @code{continue}.

@example
>>> print(ast.dump(ast.parse("""\
... for a in b:
...     if a > 5:
...         break
...     else:
...         continue
...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='a', ctx=Store()),
            iter=Name(id='b', ctx=Load()),
            body=[
                If(
                    test=Compare(
                        left=Name(id='a', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    body=[
                        Break()],
                    orelse=[
                        Continue()])])])
@end example
@end deffn

@geindex Try (classe dans ast)
@anchor{library/ast ast Try}@anchor{4521}
@deffn {Classe} ast.Try (body, handlers, orelse, finalbody)

Bloc @code{try}. Les nœuds de la liste `body' sont les instructions à exécuter sous contrôle des exceptions. La liste `handlers' contient des nœuds @ref{4522,,ExceptHandler}, un par @code{except}. Les listes `orelse' et `finalbody' contiennent respectivement les instructions se trouvant dans d'éventuels blocs @code{else} et @code{finally}.

@example
>>> print(ast.dump(ast.parse("""
... try:
...    ...
... except Exception:
...    ...
... except OtherException as e:
...    ...
... else:
...    ...
... finally:
...    ...
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            handlers=[
                ExceptHandler(
                    type=Name(id='Exception', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                ExceptHandler(
                    type=Name(id='OtherException', ctx=Load()),
                    name='e',
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))],
            finalbody=[
                Expr(
                    value=Constant(value=Ellipsis))])])
@end example
@end deffn

@geindex TryStar (classe dans ast)
@anchor{library/ast ast TryStar}@anchor{4523}
@deffn {Classe} ast.TryStar (body, handlers, orelse, finalbody)

@code{try} blocks which are followed by @code{except*} clauses. The attributes are the
same as for @ref{4521,,Try} but the @ref{4522,,ExceptHandler} nodes in @code{handlers}
are interpreted as @code{except*} blocks rather then @code{except}.

@example
>>> print(ast.dump(ast.parse("""
... try:
...    ...
... except* Exception:
...    ...
... """), indent=4))
Module(
    body=[
        TryStar(
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            handlers=[
                ExceptHandler(
                    type=Name(id='Exception', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex ExceptHandler (classe dans ast)
@anchor{library/ast ast ExceptHandler}@anchor{4522}
@deffn {Classe} ast.ExceptHandler (type, name, body)

Une clause @code{except}. Elle intercepte les exceptions de types donnés par `type', qui est le plus souvent un nœud @ref{18cc,,Name} ou bien @code{None} (cette dernière valeur pour les clauses fourre-tout @code{except:}). Le nom éventuel de la variable à laquelle affecter l'exception est dans la chaîne de caractères `name' (@code{None} s'il n'y a pas de @code{as}). Les instructions sous le @code{except} sont dans la liste `body'.

@example
>>> print(ast.dump(ast.parse("""\
... try:
...     a + 1
... except TypeError:
...     pass
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=BinOp(
                        left=Name(id='a', ctx=Load()),
                        op=Add(),
                        right=Constant(value=1)))],
            handlers=[
                ExceptHandler(
                    type=Name(id='TypeError', ctx=Load()),
                    body=[
                        Pass()])])])
@end example
@end deffn

@geindex With (classe dans ast)
@anchor{library/ast ast With}@anchor{4524}
@deffn {Classe} ast.With (items, body, type_comment)

Bloc @code{with}. Les gestionnaires de contexte sont stockés dans `items' comme instances de @ref{4525,,withitem}. Les instructions sous le @code{with} forment la liste `body'.

@geindex type_comment (attribut ast.With)
@anchor{library/ast ast With type_comment}@anchor{4526}
@deffn {Attribut} type_comment

Le champ facultatif `type_comment' contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.
@end deffn
@end deffn

@geindex withitem (classe dans ast)
@anchor{library/ast ast withitem}@anchor{4525}
@deffn {Classe} ast.withitem (context_expr, optional_vars)

Gestionnaire de contexte dans un bloc @code{with}. Le gestionnaire est donné par le nœud `context_expr', souvent une instance de @ref{44db,,Call}. S'il y a affectation avec @code{as}, `optional_vars' contient sa cible, qui est un nœud de type @ref{18cc,,Name}, @ref{44d5,,Tuple} ou @ref{44d4,,List}. Sinon, `optional_vars' vaut @code{None}.

@example
>>> print(ast.dump(ast.parse("""\
... with a as b, c as d:
...    something(b, d)
... """), indent=4))
Module(
    body=[
        With(
            items=[
                withitem(
                    context_expr=Name(id='a', ctx=Load()),
                    optional_vars=Name(id='b', ctx=Store())),
                withitem(
                    context_expr=Name(id='c', ctx=Load()),
                    optional_vars=Name(id='d', ctx=Store()))],
            body=[
                Expr(
                    value=Call(
                        func=Name(id='something', ctx=Load()),
                        args=[
                            Name(id='b', ctx=Load()),
                            Name(id='d', ctx=Load())]))])])
@end example
@end deffn

@node Pattern matching,Type parameters,Contrôle de l'exécution,Classes de nœuds
@anchor{library/ast pattern-matching}@anchor{4527}
@subsubsection Pattern matching


@geindex Match (classe dans ast)
@anchor{library/ast ast Match}@anchor{4528}
@deffn {Classe} ast.Match (subject, cases)

A @code{match} statement. @code{subject} holds the subject of the match (the object
that is being matched against the cases) and @code{cases} contains an iterable of
@ref{4529,,match_case} nodes with the different cases.


Ajouté dans la version 3.10.

@end deffn

@geindex match_case (classe dans ast)
@anchor{library/ast ast match_case}@anchor{4529}
@deffn {Classe} ast.match_case (pattern, guard, body)

A single case pattern in a @code{match} statement. @code{pattern} contains the
match pattern that the subject will be matched against. Note that the
@ref{1a4,,AST} nodes produced for patterns differ from those produced for
expressions, even when they share the same syntax.

The @code{guard} attribute contains an expression that will be evaluated if
the pattern matches the subject.

@code{body} contains a list of nodes to execute if the pattern matches and
the result of evaluating the guard expression is true.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] if x>0:
...         ...
...     case tuple():
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchAs(name='x')]),
                    guard=Compare(
                        left=Name(id='x', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=0)]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='tuple', ctx=Load())),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchValue (classe dans ast)
@anchor{library/ast ast MatchValue}@anchor{452a}
@deffn {Classe} ast.MatchValue (value)

A match literal or value pattern that compares by equality. @code{value} is
an expression node. Permitted value nodes are restricted as described in
the match statement documentation. This pattern succeeds if the match
subject is equal to the evaluated value.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case "Relevant":
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchValue(
                        value=Constant(value='Relevant')),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchSingleton (classe dans ast)
@anchor{library/ast ast MatchSingleton}@anchor{452b}
@deffn {Classe} ast.MatchSingleton (value)

A match literal pattern that compares by identity. @code{value} is the
singleton to be compared against: @code{None}, @code{True}, or @code{False}. This
pattern succeeds if the match subject is the given constant.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case None:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSingleton(value=None),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchSequence (classe dans ast)
@anchor{library/ast ast MatchSequence}@anchor{452c}
@deffn {Classe} ast.MatchSequence (patterns)

A match sequence pattern. @code{patterns} contains the patterns to be matched
against the subject elements if the subject is a sequence. Matches a variable
length sequence if one of the subpatterns is a @code{MatchStar} node, otherwise
matches a fixed length sequence.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [1, 2]:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchValue(
                                value=Constant(value=1)),
                            MatchValue(
                                value=Constant(value=2))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchStar (classe dans ast)
@anchor{library/ast ast MatchStar}@anchor{452d}
@deffn {Classe} ast.MatchStar (name)

Matches the rest of the sequence in a variable length match sequence pattern.
If @code{name} is not @code{None}, a list containing the remaining sequence
elements is bound to that name if the overall sequence pattern is successful.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [1, 2, *rest]:
...         ...
...     case [*_]:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchValue(
                                value=Constant(value=1)),
                            MatchValue(
                                value=Constant(value=2)),
                            MatchStar(name='rest')]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchStar()]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchMapping (classe dans ast)
@anchor{library/ast ast MatchMapping}@anchor{452e}
@deffn {Classe} ast.MatchMapping (keys, patterns, rest)

A match mapping pattern. @code{keys} is a sequence of expression nodes.
@code{patterns} is a corresponding sequence of pattern nodes. @code{rest} is an
optional name that can be specified to capture the remaining mapping elements.
Permitted key expressions are restricted as described in the match statement
documentation.

This pattern succeeds if the subject is a mapping, all evaluated key
expressions are present in the mapping, and the value corresponding to each
key matches the corresponding subpattern. If @code{rest} is not @code{None}, a dict
containing the remaining mapping elements is bound to that name if the overall
mapping pattern is successful.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case @{1: _, 2: _@}:
...         ...
...     case @{**rest@}:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchMapping(
                        keys=[
                            Constant(value=1),
                            Constant(value=2)],
                        patterns=[
                            MatchAs(),
                            MatchAs()]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchMapping(rest='rest'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchClass (classe dans ast)
@anchor{library/ast ast MatchClass}@anchor{452f}
@deffn {Classe} ast.MatchClass (cls, patterns, kwd_attrs, kwd_patterns)

A match class pattern. @code{cls} is an expression giving the nominal class to
be matched. @code{patterns} is a sequence of pattern nodes to be matched against
the class defined sequence of pattern matching attributes. @code{kwd_attrs} is a
sequence of additional attributes to be matched (specified as keyword arguments
in the class pattern), @code{kwd_patterns} are the corresponding patterns
(specified as keyword values in the class pattern).

This pattern succeeds if the subject is an instance of the nominated class,
all positional patterns match the corresponding class-defined attributes, and
any specified keyword attributes match their corresponding pattern.

Note: classes may define a property that returns self in order to match a
pattern node against the instance being matched. Several builtin types are
also matched that way, as described in the match statement documentation.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case Point2D(0, 0):
...         ...
...     case Point3D(x=0, y=0, z=0):
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point2D', ctx=Load()),
                        patterns=[
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point3D', ctx=Load()),
                        kwd_attrs=[
                            'x',
                            'y',
                            'z'],
                        kwd_patterns=[
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchAs (classe dans ast)
@anchor{library/ast ast MatchAs}@anchor{4530}
@deffn {Classe} ast.MatchAs (pattern, name)

A match "as-pattern", capture pattern or wildcard pattern. @code{pattern}
contains the match pattern that the subject will be matched against.
If the pattern is @code{None}, the node represents a capture pattern (i.e a
bare name) and will always succeed.

The @code{name} attribute contains the name that will be bound if the pattern
is successful. If @code{name} is @code{None}, @code{pattern} must also be @code{None}
and the node represents the wildcard pattern.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] as y:
...         ...
...     case _:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchAs(
                        pattern=MatchSequence(
                            patterns=[
                                MatchAs(name='x')]),
                        name='y'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchAs(),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@geindex MatchOr (classe dans ast)
@anchor{library/ast ast MatchOr}@anchor{4531}
@deffn {Classe} ast.MatchOr (patterns)

A match "or-pattern". An or-pattern matches each of its subpatterns in turn
to the subject, until one succeeds. The or-pattern is then deemed to
succeed. If none of the subpatterns succeed the or-pattern fails. The
@code{patterns} attribute contains a list of match pattern nodes that will be
matched against the subject.

@example
>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] | (y):
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchOr(
                        patterns=[
                            MatchSequence(
                                patterns=[
                                    MatchAs(name='x')]),
                            MatchAs(name='y')]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])
@end example


Ajouté dans la version 3.10.

@end deffn

@node Type parameters,Définition de fonctions et de classes,Pattern matching,Classes de nœuds
@anchor{library/ast ast-type-params}@anchor{4516}@anchor{library/ast type-parameters}@anchor{4532}
@subsubsection Type parameters


@ref{2b0,,Type parameters} can exist on classes, functions, and type
aliases.

@geindex TypeVar (classe dans ast)
@anchor{library/ast ast TypeVar}@anchor{4533}
@deffn {Classe} ast.TypeVar (name, bound, default_value)

A @ref{15c,,typing.TypeVar}. @code{name} is the name of the type variable.
@code{bound} is the bound or constraints, if any. If @code{bound} is a @ref{44d5,,Tuple},
it represents constraints; otherwise it represents the bound. @code{default_value}
is the default value; if the @code{TypeVar} has no default, this
attribute will be set to @code{None}.

@example
>>> print(ast.dump(ast.parse("type Alias[T: int = bool] = list[T]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVar(
                    name='T',
                    bound=Name(id='int', ctx=Load()),
                    default_value=Name(id='bool', ctx=Load()))],
            value=Subscript(
                value=Name(id='list', ctx=Load()),
                slice=Name(id='T', ctx=Load()),
                ctx=Load()))])
@end example


Ajouté dans la version 3.12.



Modifié dans la version 3.13: Added the `default_value' parameter.

@end deffn

@geindex ParamSpec (classe dans ast)
@anchor{library/ast ast ParamSpec}@anchor{4534}
@deffn {Classe} ast.ParamSpec (name, default_value)

A @ref{15d,,typing.ParamSpec}. @code{name} is the name of the parameter specification.
@code{default_value} is the default value; if the @code{ParamSpec} has no default,
this attribute will be set to @code{None}.

@example
>>> print(ast.dump(ast.parse("type Alias[**P = [int, str]] = Callable[P, int]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                ParamSpec(
                    name='P',
                    default_value=List(
                        elts=[
                            Name(id='int', ctx=Load()),
                            Name(id='str', ctx=Load())],
                        ctx=Load()))],
            value=Subscript(
                value=Name(id='Callable', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Name(id='P', ctx=Load()),
                        Name(id='int', ctx=Load())],
                    ctx=Load()),
                ctx=Load()))])
@end example


Ajouté dans la version 3.12.



Modifié dans la version 3.13: Added the `default_value' parameter.

@end deffn

@geindex TypeVarTuple (classe dans ast)
@anchor{library/ast ast TypeVarTuple}@anchor{4535}
@deffn {Classe} ast.TypeVarTuple (name, default_value)

A @ref{15e,,typing.TypeVarTuple}. @code{name} is the name of the type variable tuple.
@code{default_value} is the default value; if the @code{TypeVarTuple} has no
default, this attribute will be set to @code{None}.

@example
>>> print(ast.dump(ast.parse("type Alias[*Ts = ()] = tuple[*Ts]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVarTuple(
                    name='Ts',
                    default_value=Tuple(ctx=Load()))],
            value=Subscript(
                value=Name(id='tuple', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Starred(
                            value=Name(id='Ts', ctx=Load()),
                            ctx=Load())],
                    ctx=Load()),
                ctx=Load()))])
@end example


Ajouté dans la version 3.12.



Modifié dans la version 3.13: Added the `default_value' parameter.

@end deffn

@node Définition de fonctions et de classes,async et await,Type parameters,Classes de nœuds
@anchor{library/ast function-and-class-definitions}@anchor{4536}
@subsubsection Définition de fonctions et de classes


@geindex FunctionDef (classe dans ast)
@anchor{library/ast ast FunctionDef}@anchor{1691}
@deffn {Classe} ast.FunctionDef (name, args, body, decorator_list, returns, type_comment, type_params)

Définition d'une fonction.


@itemize *

@item 
`name' donne le nom de la fonction sous forme d'une chaîne de caractères.

@item 
@code{args} is an @ref{4537,,arguments} node.

@item 
`body' est la liste des instructions dans le corps de la fonction.

@item 
`decorators_list' est une liste de décorateurs appliqués à la fonction. Ils sont rangés dans leur ordre d'apparition, c'est-à-dire que le premier de la liste est appliqué en dernier.

@item 
`returns' est l'annotation de renvoi éventuelle.

@item 
@code{type_params} is a list of @ref{4516,,type parameters}.
@end itemize

@geindex type_comment (attribut ast.FunctionDef)
@anchor{library/ast ast FunctionDef type_comment}@anchor{4538}
@deffn {Attribut} type_comment

Le champ facultatif `type_comment' contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.
@end deffn


Modifié dans la version 3.12: Added @code{type_params}.

@end deffn

@geindex Lambda (classe dans ast)
@anchor{library/ast ast Lambda}@anchor{44de}
@deffn {Classe} ast.Lambda (args, body)

Fonction anonyme. Elle est créée avec le mot-clé @code{lambda}, limitée à renvoyer une simple expression, et peut être intégrée à une expression plus large. Contrairement à @ref{1691,,FunctionDef}, `body' est ici un nœud unique. `args' est une instance de @code{arguments} qui contient les arguments de la signature.

@example
>>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))
Module(
    body=[
        Expr(
            value=Lambda(
                args=arguments(
                    args=[
                        arg(arg='x'),
                        arg(arg='y')]),
                body=Constant(value=Ellipsis)))])
@end example
@end deffn

@geindex arguments (classe dans ast)
@anchor{library/ast ast arguments}@anchor{4537}
@deffn {Classe} ast.arguments (posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

Arguments d'une fonction.


@itemize *

@item 
`posonlyargs', `args' et `kwonlyargs' sont des listes de nœuds @ref{4539,,arg} qui correspondent respectivement aux arguments obligatoirement positionnels, positionnels ou nommés et obligatoirement nommés.

@item 
`varargs' et `kwargs' sont des nœuds @ref{4539,,arg} qui apparaissent avec la capture des arguments restants, positionnels (@code{*arguments_positionnels}) et nommés (@code{**arguments_nommés}).

@item 
`kw_defaults' est la liste des valeurs par défaut pour les arguments obligatoirement nommés. Si l'un des éléments n'est pas un nœud mais @code{None}, il n'y a pas de valeur par défaut et l'argument correspondant doit être passé obligatoirement à la fonction.

@item 
`defaults' est, quant à elle, la liste des valeurs par défauts pour les arguments qui peuvent être passés de manière positionnelle (obligatoirement ou non). S'il y a moins d'éléments dans la liste que d'arguments positionnels, ces éléments donnent les valeurs par défaut des `n' derniers arguments positionnels (avec `n' la longueur de `defaults').
@end itemize
@end deffn

@geindex arg (classe dans ast)
@anchor{library/ast ast arg}@anchor{4539}
@deffn {Classe} ast.arg (arg, annotation, type_comment)

A single argument in a list. @code{arg} is a raw string of the argument
name; @code{annotation} is its annotation, such as a @ref{18cc,,Name} node.

@geindex type_comment (attribut ast.arg)
@anchor{library/ast ast arg type_comment}@anchor{453a}
@deffn {Attribut} type_comment

Le champ facultatif `type_comment' est, sous forme de chaîne, une annotation de type fournie par un commentaire.
@end deffn

@example
>>> print(ast.dump(ast.parse("""\
... @@decorator1
... @@decorator2
... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return annotation':
...     pass
... """), indent=4))
Module(
    body=[
        FunctionDef(
            name='f',
            args=arguments(
                args=[
                    arg(
                        arg='a',
                        annotation=Constant(value='annotation')),
                    arg(arg='b'),
                    arg(arg='c')],
                vararg=arg(arg='d'),
                kwonlyargs=[
                    arg(arg='e'),
                    arg(arg='f')],
                kw_defaults=[
                    None,
                    Constant(value=3)],
                kwarg=arg(arg='g'),
                defaults=[
                    Constant(value=1),
                    Constant(value=2)]),
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())],
            returns=Constant(value='return annotation'))])
@end example
@end deffn

@geindex Return (classe dans ast)
@anchor{library/ast ast Return}@anchor{453b}
@deffn {Classe} ast.Return (value)

Instruction @code{return}, qui renvoie `value'.

@example
>>> print(ast.dump(ast.parse('return 4'), indent=4))
Module(
    body=[
        Return(
            value=Constant(value=4))])
@end example
@end deffn

@geindex Yield (classe dans ast)
@geindex YieldFrom (classe dans ast)
@anchor{library/ast ast Yield}@anchor{44df}
@deffn {Classe} ast.Yield (value)
@anchor{library/ast ast YieldFrom}@anchor{44e0}
@deffnx {Classe} ast.YieldFrom (value)

A @code{yield} or @code{yield from} expression. Because these are expressions, they
must be wrapped in an @ref{44dd,,Expr} node if the value sent back is not used.

@example
>>> print(ast.dump(ast.parse('yield x'), indent=4))
Module(
    body=[
        Expr(
            value=Yield(
                value=Name(id='x', ctx=Load())))])

>>> print(ast.dump(ast.parse('yield from x'), indent=4))
Module(
    body=[
        Expr(
            value=YieldFrom(
                value=Name(id='x', ctx=Load())))])
@end example
@end deffn

@geindex Global (classe dans ast)
@geindex Nonlocal (classe dans ast)
@anchor{library/ast ast Global}@anchor{453c}
@deffn {Classe} ast.Global (names)
@anchor{library/ast ast Nonlocal}@anchor{453d}
@deffnx {Classe} ast.Nonlocal (names)

Instruction @code{global} ou @code{nonlocal}. Elle s'applique aux noms de variables donnés dans `names', une liste de chaînes de caractères.

@example
>>> print(ast.dump(ast.parse('global x,y,z'), indent=4))
Module(
    body=[
        Global(
            names=[
                'x',
                'y',
                'z'])])

>>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))
Module(
    body=[
        Nonlocal(
            names=[
                'x',
                'y',
                'z'])])
@end example
@end deffn

@geindex ClassDef (classe dans ast)
@anchor{library/ast ast ClassDef}@anchor{168f}
@deffn {Classe} ast.ClassDef (name, bases, keywords, body, decorator_list, type_params)

Définition d'une classe.


@itemize *

@item 
`name' est le nom de la classe sous forme de chaîne de caractères ;

@item 
`bases' est la liste des classes mères données explicitement ;

@item 
@code{keywords} is a list of @ref{4501,,keyword} nodes, principally for 'metaclass'.
Other keywords will be passed to the metaclass, as per 
@geindex Python Enhancement Proposals; PEP 3115
PEP 3115@footnote{https://peps.python.org/pep-3115/}.

@item 
`body' est la liste des instructions contenues dans la définition de classe ;

@item 
`decorators_list' est une liste de nœuds, comme pour @ref{1691,,FunctionDef}.

@item 
@code{type_params} is a list of @ref{4516,,type parameters}.
@end itemize

@example
>>> print(ast.dump(ast.parse("""\
... @@decorator1
... @@decorator2
... class Foo(base1, base2, metaclass=meta):
...     pass
... """), indent=4))
Module(
    body=[
        ClassDef(
            name='Foo',
            bases=[
                Name(id='base1', ctx=Load()),
                Name(id='base2', ctx=Load())],
            keywords=[
                keyword(
                    arg='metaclass',
                    value=Name(id='meta', ctx=Load()))],
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())])])
@end example


Modifié dans la version 3.12: Added @code{type_params}.

@end deffn

@node async et await,,Définition de fonctions et de classes,Classes de nœuds
@anchor{library/ast async-and-await}@anchor{453e}
@subsubsection @code{async} et @code{await}


@geindex AsyncFunctionDef (classe dans ast)
@anchor{library/ast ast AsyncFunctionDef}@anchor{1690}
@deffn {Classe} ast.AsyncFunctionDef (name, args, body, decorator_list, returns, type_comment, type_params)

Fonction déclarée avec @code{async def}. Les champs sont les mêmes que dans @ref{1691,,FunctionDef}.


Modifié dans la version 3.12: Added @code{type_params}.

@end deffn

@geindex Await (classe dans ast)
@anchor{library/ast ast Await}@anchor{453f}
@deffn {Classe} ast.Await (value)

Expression @code{await}, qui attend `value'. Ces nœuds ne peuvent apparaître qu'à l'intérieur de @ref{1690,,AsyncFunctionDef}.
@end deffn

@example
>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4))
Module(
    body=[
        AsyncFunctionDef(
            name='f',
            args=arguments(),
            body=[
                Expr(
                    value=Await(
                        value=Call(
                            func=Name(id='other_func', ctx=Load()))))])])
@end example

@geindex AsyncFor (classe dans ast)
@geindex AsyncWith (classe dans ast)
@anchor{library/ast ast AsyncFor}@anchor{4540}
@deffn {Classe} ast.AsyncFor (target, iter, body, orelse, type_comment)
@anchor{library/ast ast AsyncWith}@anchor{4541}
@deffnx {Classe} ast.AsyncWith (items, body, type_comment)

Instruction @code{async for} ou @code{async with}. Les champs sont les mêmes que ceux de @ref{451c,,For} et @ref{4524,,With}. Ces nœuds ne peuvent apparaître qu'à l'intérieur de @ref{1690,,AsyncFunctionDef}.
@end deffn

@cartouche
@quotation Note 
Lorsqu'une chaîne contenant du code est transformée en arbre syntaxique par @ref{1a6,,ast.parse()}, les nœuds représentants les opérateurs (classes filles de @code{ast.operator}, @code{ast.unaryop}, @code{ast.cmpop}, @code{ast.boolop} et @code{ast.expr_context}) sont des singletons à l'intérieur de l'arbre renvoyé. Si l'un, par exemple une instance de @ref{44e5,,ast.Add}, est muté, la modification sera visible sur toutes les autres apparitions de l'opérateur.
@end quotation
@end cartouche

@node Outils du module ast,Options du compilateur,Classes de nœuds,ast --- Abstract Syntax Trees
@anchor{library/ast ast-helpers}@anchor{4542}
@subsubsection Outils du module @code{ast}


À part les classes de nœuds, le module @ref{8,,ast} définit plusieurs fonctions et classes utilitaires pour traverser les arbres syntaxiques abstraits :

@geindex parse() (dans le module ast)
@anchor{library/ast ast parse}@anchor{1a6}
@deffn {Fonction} ast.parse (source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1)

Parse the source into an AST node.  Equivalent to @code{compile(source,
filename, mode, flags=FLAGS_VALUE, optimize=optimize)},
where @code{FLAGS_VALUE} is @code{ast.PyCF_ONLY_AST} if @code{optimize <= 0}
and @code{ast.PyCF_OPTIMIZED_AST} otherwise.

If @code{type_comments=True} is given, the parser is modified to check
and return type comments as specified by 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} and 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}.
This is equivalent to adding @ref{4543,,ast.PyCF_TYPE_COMMENTS} to the
flags passed to @ref{190,,compile()}.  This will report syntax errors
for misplaced type comments.  Without this flag, type comments will
be ignored, and the @code{type_comment} field on selected AST nodes
will always be @code{None}.  In addition, the locations of @code{# type:
ignore} comments will be returned as the @code{type_ignores}
attribute of @ref{44cc,,Module} (otherwise it is always an empty list).

In addition, if @code{mode} is @code{'func_type'}, the input syntax is
modified to correspond to 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} "signature type comments",
e.g. @code{(str, int) -> List[str]}.

Setting @code{feature_version} to a tuple @code{(major, minor)} will result in
a "best-effort" attempt to parse using that Python version's grammar.
For example, setting @code{feature_version=(3, 9)} will attempt to disallow
parsing of @ref{7f7,,match} statements.
Currently @code{major} must equal to @code{3}. The lowest supported version is
@code{(3, 7)} (and this may increase in future Python versions);
the highest is @code{sys.version_info[0:2]}. "Best-effort" attempt means there
is no guarantee that the parse (or success of the parse) is the same as
when run on the Python version corresponding to @code{feature_version}.

If source contains a null character (@code{\0}), @ref{1ff,,ValueError} is raised.

@cartouche
@quotation Avertissement 
Note that successfully parsing source code into an AST object doesn't
guarantee that the source code provided is valid Python code that can
be executed as the compilation step can raise further @ref{18b,,SyntaxError}
exceptions. For instance, the source @code{return 42} generates a valid
AST node for a return statement, but it cannot be compiled alone (it needs
to be inside a function node).

In particular, @ref{1a6,,ast.parse()} won't do any scoping checks, which the
compilation step does.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Il est possible de faire planter l'interpréteur Python avec des chaînes suffisamment grandes ou complexes lors de la compilation d'un arbre syntaxique en raison de la limitation de la profondeur de la pile d'appels.
@end quotation
@end cartouche


Modifié dans la version 3.8: ajout des paramètres `type_comments' et `feature_version' ainsi que de la valeur @code{'func_type'} pour `mode'.



Modifié dans la version 3.13: The minimum supported version for @code{feature_version} is now @code{(3, 7)}.
The @code{optimize} argument was added.

@end deffn

@geindex unparse() (dans le module ast)
@anchor{library/ast ast unparse}@anchor{8d2}
@deffn {Fonction} ast.unparse (ast_obj)

À partir d'un arbre syntaxique @ref{1a4,,ast.AST}, reconstruit un code sous forme de chaîne de caractères. S'il est passé à @ref{1a6,,ast.parse()}, le résultat produit un arbre @ref{1a4,,ast.AST} équivalent à l'original.

@cartouche
@quotation Avertissement 
The produced code string will not necessarily be equal to the original
code that generated the @ref{1a4,,ast.AST} object (without any compiler
optimizations, such as constant tuples/frozensets).
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
Une @ref{d59,,RecursionError} est levée si l'expression comporte de très nombreux niveaux d'imbrication.
@end quotation
@end cartouche


Ajouté dans la version 3.9.

@end deffn

@geindex literal_eval() (dans le module ast)
@anchor{library/ast ast literal_eval}@anchor{c06}
@deffn {Fonction} ast.literal_eval (node_or_string)

Evaluate an expression node or a string containing only a Python literal or
container display.  The string or node provided may only consist of the
following Python literal structures: strings, bytes, numbers, tuples, lists,
dicts, sets, booleans, @code{None} and @code{Ellipsis}.

This can be used for evaluating strings containing Python values without the
need to parse the values oneself.  It is not capable of evaluating
arbitrarily complex expressions, for example involving operators or
indexing.

This function had been documented as "safe" in the past without defining
what that meant. That was misleading. This is specifically designed not to
execute Python code, unlike the more general @ref{17e,,eval()}. There is no
namespace, no name lookups, or ability to call out. But it is not free from
attack: A relatively small input can lead to memory exhaustion or to C stack
exhaustion, crashing the process. There is also the possibility for
excessive CPU consumption denial of service on some inputs. Calling it on
untrusted data is thus not recommended.

@cartouche
@quotation Avertissement 
It is possible to crash the Python interpreter due to stack depth
limitations in Python's AST compiler.

It can raise @ref{1ff,,ValueError}, @ref{522,,TypeError}, @ref{18b,,SyntaxError},
@ref{164b,,MemoryError} and @ref{d59,,RecursionError} depending on the malformed
input.
@end quotation
@end cartouche


Modifié dans la version 3.2: accepte maintenant les octets et ensembles littéraux.



Modifié dans la version 3.9: accepte @code{set()} pour les ensembles vides.



Modifié dans la version 3.10: For string inputs, leading spaces and tabs are now stripped.

@end deffn

@geindex get_docstring() (dans le module ast)
@anchor{library/ast ast get_docstring}@anchor{19e8}
@deffn {Fonction} ast.get_docstring (node, clean=True)

Renvoie la `docstring' du nœud `node' (de type @ref{1691,,FunctionDef}, @ref{1690,,AsyncFunctionDef}, @ref{168f,,ClassDef} or @ref{44cc,,Module}), ou @code{None} s'il n'a pas de `docstring'. Si `clean' est vrai, cette fonction nettoie l'indentation de la `docstring' avec @ref{163e,,inspect.cleandoc()}.


Modifié dans la version 3.5: @ref{1690,,AsyncFunctionDef} est maintenant gérée.

@end deffn

@geindex get_source_segment() (dans le module ast)
@anchor{library/ast ast get_source_segment}@anchor{9c5}
@deffn {Fonction} ast.get_source_segment (source, node, *, padded=False)

Get source code segment of the `source' that generated `node'.
If some location information (@ref{44c5,,lineno}, @ref{44c7,,end_lineno},
@ref{44c6,,col_offset}, or @ref{44c8,,end_col_offset}) is missing, return @code{None}.

If `padded' is @code{True}, the first line of a multi-line statement will
be padded with spaces to match its original position.


Ajouté dans la version 3.8.

@end deffn

@geindex fix_missing_locations() (dans le module ast)
@anchor{library/ast ast fix_missing_locations}@anchor{4544}
@deffn {Fonction} ast.fix_missing_locations (node)

When you compile a node tree with @ref{190,,compile()}, the compiler expects
@ref{44c5,,lineno} and @ref{44c6,,col_offset} attributes for every node that supports
them.  This is rather tedious to fill in for generated nodes, so this helper
adds these attributes recursively where not already set, by setting them to
the values of the parent node.  It works recursively starting at `node'.
@end deffn

@geindex increment_lineno() (dans le module ast)
@anchor{library/ast ast increment_lineno}@anchor{1724}
@deffn {Fonction} ast.increment_lineno (node, n=1)

Incrémente de `n' les numéros des lignes de début et ligne de fin de chaque nœud dans l'arbre, en commençant par le nœud `node'. C'est utile pour « déplacer du code » à un endroit différent dans un fichier.
@end deffn

@geindex copy_location() (dans le module ast)
@anchor{library/ast ast copy_location}@anchor{4545}
@deffn {Fonction} ast.copy_location (new_node, old_node)

Copy source location (@ref{44c5,,lineno}, @ref{44c6,,col_offset}, @ref{44c7,,end_lineno},
and @ref{44c8,,end_col_offset}) from `old_node' to `new_node' if possible,
and return `new_node'.
@end deffn

@geindex iter_fields() (dans le module ast)
@anchor{library/ast ast iter_fields}@anchor{4546}
@deffn {Fonction} ast.iter_fields (node)

Produit un `n'-uplet de couples @code{(nom_du_champ, valeur)} pour chaque champ de @code{node._fields} qui est présent dans `node'.
@end deffn

@geindex iter_child_nodes() (dans le module ast)
@anchor{library/ast ast iter_child_nodes}@anchor{4547}
@deffn {Fonction} ast.iter_child_nodes (node)

Produit tous les nœuds enfants directs de `node', c'est-à-dire tous les champs qui sont des nœuds et tous les éléments des champs qui sont des listes de nœuds.
@end deffn

@geindex walk() (dans le module ast)
@anchor{library/ast ast walk}@anchor{4548}
@deffn {Fonction} ast.walk (node)

Produit récursivement tous les nœuds enfants dans l'arbre en commençant par `node' (`node' lui-même est inclus), sans ordre spécifique. C'est utile lorsque l'on souhaite modifier les nœuds sur place sans prêter attention au contexte.
@end deffn

@geindex NodeVisitor (classe dans ast)
@anchor{library/ast ast NodeVisitor}@anchor{a5b}
@deffn {Classe} ast.NodeVisitor

Classe de base pour un visiteur de nœud, qui parcourt l'arbre syntaxique abstrait et appelle une fonction de visite pour chacun des nœuds trouvés. Cette fonction peut renvoyer une valeur, qui est transmise par la méthode @ref{4549,,visit()}.

Cette classe est faite pour être dérivée, en ajoutant des méthodes de visite à la sous-classe.

@geindex visit() (méthode ast.NodeVisitor)
@anchor{library/ast ast NodeVisitor visit}@anchor{4549}
@deffn {Méthode} visit (node)

Visite un nœud. L'implémentation par défaut appelle la méthode @code{self.visit_@var{classe}} où `classe' représente le nom de la classe du nœud, ou @ref{454a,,generic_visit()} si cette méthode n'existe pas.
@end deffn

@geindex generic_visit() (méthode ast.NodeVisitor)
@anchor{library/ast ast NodeVisitor generic_visit}@anchor{454a}
@deffn {Méthode} generic_visit (node)

Le visiteur appelle la méthode @ref{4549,,visit()} de tous les enfants du nœud.

Notons que les nœuds enfants qui possèdent une méthode de visite spéciale ne sont pas visités à moins que le visiteur n'appelle la méthode @ref{454a,,generic_visit()} ou ne les visite lui-même.
@end deffn

@geindex visit_Constant() (méthode ast.NodeVisitor)
@anchor{library/ast ast NodeVisitor visit_Constant}@anchor{a5c}
@deffn {Méthode} visit_Constant (node)

Handles all constant nodes.
@end deffn

N'utilisez pas @ref{a5b,,NodeVisitor} si vous souhaitez appliquer des changements sur les nœuds lors du parcours. Pour cela, un visiteur spécial existe (@ref{454b,,NodeTransformer}) qui permet les modifications.


Obsolète depuis la version 3.8: Methods @code{visit_Num()}, @code{visit_Str()}, @code{visit_Bytes()},
@code{visit_NameConstant()} and @code{visit_Ellipsis()} are deprecated
now and will not be called in future Python versions.  Add the
@ref{a5c,,visit_Constant()} method to handle all constant nodes.

@end deffn

@geindex NodeTransformer (classe dans ast)
@anchor{library/ast ast NodeTransformer}@anchor{454b}
@deffn {Classe} ast.NodeTransformer

Une sous-classe de @ref{a5b,,NodeVisitor} qui traverse l'arbre syntaxique abstrait et permet de modifier les nœuds.

Le @ref{454b,,NodeTransformer} traverse l'arbre syntaxique et utilise la valeur renvoyée par les méthodes du visiteur pour remplacer ou supprimer l'ancien nœud. Si la valeur renvoyée par la méthode du visiteur est @code{None}, le nœud est supprimé de sa position, sinon il est remplacé par cette valeur. Elle peut être le nœud original, auquel cas il n'y a pas de remplacement.

Voici un exemple de transformation qui réécrit tous les accès à la valeur d'une variable @code{toto} en @code{data['toto']} :

@example
class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return Subscript(
            value=Name(id='data', ctx=Load()),
            slice=Constant(value=node.id),
            ctx=node.ctx
        )
@end example

Keep in mind that if the node you're operating on has child nodes you must
either transform the child nodes yourself or call the @ref{454a,,generic_visit()}
method for the node first.

Pour les nœuds qui font partie d'un groupe (notamment toutes les instructions), le visiteur peut aussi renvoyer une liste des nœuds plutôt qu'un seul nœud.

If @ref{454b,,NodeTransformer} introduces new nodes (that weren't part of
original tree) without giving them location information (such as
@ref{44c5,,lineno}), @ref{4544,,fix_missing_locations()} should be called with
the new sub-tree to recalculate the location information:

@example
tree = ast.parse('foo', mode='eval')
new_tree = fix_missing_locations(RewriteName().visit(tree))
@end example

Utilisation typique des transformations :

@example
node = YourTransformer().visit(node)
@end example
@end deffn

@geindex dump() (dans le module ast)
@anchor{library/ast ast dump}@anchor{8d1}
@deffn {Fonction} ast.dump (node, annotate_fields=True, include_attributes=False, *, indent=None, show_empty=False)

Renvoie une représentation sous forme de chaîne de caractères de l'arbre contenu dans `node'. Ceci est principalement utile à des fins de débogage. Par défaut, les champs sont passés comme paramètres nommés aux constructeurs des classes d'arbre syntaxiques. Cependant, si `annotate_fields' est mis à @code{False}, les valeurs sont passées, lorsque cela est possible, comme arguments positionnels, rendant la représentation plus compacte. Les attributs comme les numéros de lignes et positions sur les lignes sont masqués par défaut, mais on peut les inclure en mettant `include_attributes' à @code{True}.

La représentation peut comprendre une indentation afin d'être plus lisible. Si `indent' est une chaîne de caractères (par exemple une tabulation @code{"\t"}), elle est insérée au début des lignes en la répétant autant de fois que le niveau d'indentation. Un entier positif équivaut à un certain nombre d'espaces. Un entier strictement négatif produit un effet identique à 0 ou la chaîne vide, c'est-à-dire des retours à la ligne sans indentation. Avec la valeur par défaut de @code{None}, la sortie tient sur une seule ligne.

If `show_empty' is @code{False} (the default), empty lists and fields that are @code{None}
will be omitted from the output.


Modifié dans la version 3.9: ajout du paramètre `indent'.



Modifié dans la version 3.13: Added the `show_empty' option.

@example
>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4, show_empty=True))
Module(
    body=[
        AsyncFunctionDef(
            name='f',
            args=arguments(
                posonlyargs=[],
                args=[],
                kwonlyargs=[],
                kw_defaults=[],
                defaults=[]),
            body=[
                Expr(
                    value=Await(
                        value=Call(
                            func=Name(id='other_func', ctx=Load()),
                            args=[],
                            keywords=[])))],
            decorator_list=[],
            type_params=[])],
    type_ignores=[])
@end example

@end deffn

@node Options du compilateur,Utilisation en ligne de commande<4>,Outils du module ast,ast --- Abstract Syntax Trees
@anchor{library/ast ast-compiler-flags}@anchor{20eb}@anchor{library/ast compiler-flags}@anchor{454c}
@subsubsection Options du compilateur


Les options suivantes sont prises en charge par la fonction @ref{190,,compile()}. Elles permettent de modifier le comportement de la compilation :

@geindex PyCF_ALLOW_TOP_LEVEL_AWAIT (dans le module ast)
@anchor{library/ast ast PyCF_ALLOW_TOP_LEVEL_AWAIT}@anchor{454d}
@deffn {Données} ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

Active la reconnaissance de @code{await}, @code{async for}, @code{async with} et des compréhensions asynchrones au niveau le plus haut.


Ajouté dans la version 3.8.

@end deffn

@geindex PyCF_ONLY_AST (dans le module ast)
@anchor{library/ast ast PyCF_ONLY_AST}@anchor{44c1}
@deffn {Données} ast.PyCF_ONLY_AST

Génère et renvoie un arbre syntaxique au lieu d'un objet de code compilé.
@end deffn

@geindex PyCF_OPTIMIZED_AST (dans le module ast)
@anchor{library/ast ast PyCF_OPTIMIZED_AST}@anchor{454e}
@deffn {Données} ast.PyCF_OPTIMIZED_AST

The returned AST is optimized according to the `optimize' argument
in @ref{190,,compile()} or @ref{1a6,,ast.parse()}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyCF_TYPE_COMMENTS (dans le module ast)
@anchor{library/ast ast PyCF_TYPE_COMMENTS}@anchor{4543}
@deffn {Données} ast.PyCF_TYPE_COMMENTS

Ajoute la prise en charge des commentaires de types tels que définis dans la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} et la 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} (@code{# type: un_type} et @code{# type: ignore}).


Ajouté dans la version 3.8.

@end deffn

@node Utilisation en ligne de commande<4>,,Options du compilateur,ast --- Abstract Syntax Trees
@anchor{library/ast ast-cli}@anchor{454f}@anchor{library/ast command-line-usage}@anchor{4550}
@subsubsection Utilisation en ligne de commande



Ajouté dans la version 3.9.


Le module @ref{8,,ast} peut être exécuté en tant que script en ligne de commande. C'est aussi simple que ceci :

@example
python -m ast [-m <mode>] [-a] [infile]
@end example

Les options suivantes sont acceptées :

@geindex option de ligne de commande ast; -h
@geindex option de ligne de commande ast; --help
@anchor{library/ast cmdoption-ast-h}@anchor{4551}@anchor{library/ast cmdoption-ast-help}@anchor{4552}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Affiche un message d'aide et quitte.
@end deffn

@geindex option de ligne de commande ast; -m
@geindex option de ligne de commande ast; --mode
@anchor{library/ast cmdoption-ast-m}@anchor{4553}
@deffn {Option} @w{-}m <mode>
@anchor{library/ast cmdoption-ast-mode}@anchor{4554}
@deffnx {Option} @w{-}@w{-}mode <mode>

Précise le type de code à compiler, comme l'argument `mode' de la fonction @ref{1a6,,parse()}.
@end deffn

@geindex option de ligne de commande ast; --no-type-comments
@anchor{library/ast cmdoption-ast-no-type-comments}@anchor{4555}
@deffn {Option} @w{-}@w{-}no@w{-}type@w{-}comments

Désactive la reconnaissance des commentaires de type.
@end deffn

@geindex option de ligne de commande ast; -a
@geindex option de ligne de commande ast; --include-attributes
@anchor{library/ast cmdoption-ast-a}@anchor{4556}@anchor{library/ast cmdoption-ast-include-attributes}@anchor{4557}
@deffn {Option} @w{-}a, @w{-}@w{-}include@w{-}attributes

Affiche les attributs comme les numéros de lignes et les décalages par rapport aux débuts des lignes.
@end deffn

@geindex option de ligne de commande ast; -i
@geindex option de ligne de commande ast; --indent
@anchor{library/ast cmdoption-ast-i}@anchor{4558}
@deffn {Option} @w{-}i <indent>
@anchor{library/ast cmdoption-ast-indent}@anchor{4559}
@deffnx {Option} @w{-}@w{-}indent <indent>

Nombre d'espaces pour chaque niveau d'indentation dans la sortie.
@end deffn

L'entrée est lue dans le fichier @code{infile}, s'il est donné, ou l'entrée standard sinon. Le code source est transformé en un arbre syntaxique, qui est affiché sur la sortie standard.


@subsubheading Voir aussi


Green Tree Snakes@footnote{https://greentreesnakes.readthedocs.io/}, une ressource documentaire externe, qui possède plus de détails pour travailler avec des arbres syntaxiques Python.

ASTTokens@footnote{https://asttokens.readthedocs.io/en/latest/user-guide.html} annote les arbres syntaxiques Python avec les positions des lexèmes et les extraits de code source à partir desquels ils sont produits. Ceci est utile pour les outils qui transforment du code source.

leoAst.py@footnote{https://leo-editor.github.io/leo-editor/appendices.html#leoast-py}
unifies the
token-based and parse-tree-based views of python programs by inserting
two-way links between tokens and ast nodes.

LibCST@footnote{https://libcst.readthedocs.io/} produit à partir du code source des arbres syntaxiques concrets, qui ressemblent à leurs homologues abstraits et conservent tous les détails du formatage. Cette bibliothèque est utile aux outils de réusinage et d'analyse de code.

Parso@footnote{https://parso.readthedocs.io} is a Python parser that supports
error recovery and round-trip parsing for different Python versions (in
multiple Python versions). Parso is also able to list multiple syntax errors
in your Python file.


@node symtable --- Access to the compiler's symbol tables,token --- Constants used with Python parse trees,ast --- Abstract Syntax Trees,Services du Langage Python
@anchor{library/symtable doc}@anchor{455a}@anchor{library/symtable module-symtable}@anchor{d7}@anchor{library/symtable symtable-access-to-the-compiler-s-symbol-tables}@anchor{455b}
@subsection @code{symtable} --- Access to the compiler's symbol tables


@geindex module; symtable

`Code source :' Lib/symtable.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/symtable.py}


__________________________________________________________________


Symbol tables are generated by the compiler from AST just before bytecode is
generated.  The symbol table is responsible for calculating the scope of every
identifier in the code.  @ref{d7,,symtable} provides an interface to examine these
tables.

@menu
* Generating Symbol Tables:: 
* Examining Symbol Tables:: 
* Utilisation en ligne de commande.: Utilisation en ligne de commande<5>. 

@end menu

@node Generating Symbol Tables,Examining Symbol Tables,,symtable --- Access to the compiler's symbol tables
@anchor{library/symtable generating-symbol-tables}@anchor{455c}
@subsubsection Generating Symbol Tables


@geindex symtable() (dans le module symtable)
@anchor{library/symtable symtable symtable}@anchor{197b}
@deffn {Fonction} symtable.symtable (code, filename, compile_type)

Return the toplevel @ref{455d,,SymbolTable} for the Python source `code'.
`filename' is the name of the file containing the code.  `compile_type' is
like the `mode' argument to @ref{190,,compile()}.
@end deffn

@node Examining Symbol Tables,Utilisation en ligne de commande<5>,Generating Symbol Tables,symtable --- Access to the compiler's symbol tables
@anchor{library/symtable examining-symbol-tables}@anchor{455e}
@subsubsection Examining Symbol Tables


@geindex SymbolTableType (classe dans symtable)
@anchor{library/symtable symtable SymbolTableType}@anchor{1595}
@deffn {Classe} symtable.SymbolTableType

An enumeration indicating the type of a @ref{455d,,SymbolTable} object.

@geindex MODULE (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType MODULE}@anchor{455f}
@deffn {Attribut} MODULE = "module"

Used for the symbol table of a module.
@end deffn

@geindex FUNCTION (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType FUNCTION}@anchor{4560}
@deffn {Attribut} FUNCTION = "function"

Used for the symbol table of a function.
@end deffn

@geindex CLASS (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType CLASS}@anchor{4561}
@deffn {Attribut} CLASS = "class"

Used for the symbol table of a class.
@end deffn

The following members refer to different flavors of
@ref{186,,annotation scopes}.

@geindex ANNOTATION (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType ANNOTATION}@anchor{4562}
@deffn {Attribut} ANNOTATION = "annotation"

Used for annotations if @code{from __future__ import annotations} is active.
@end deffn

@geindex TYPE_ALIAS (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType TYPE_ALIAS}@anchor{4563}
@deffn {Attribut} TYPE_ALIAS = "type alias"

Used for the symbol table of @ref{421,,type} constructions.
@end deffn

@geindex TYPE_PARAMETERS (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType TYPE_PARAMETERS}@anchor{4564}
@deffn {Attribut} TYPE_PARAMETERS = "type parameters"

Used for the symbol table of @ref{43c,,generic functions}
or @ref{43b,,generic classes}.
@end deffn

@geindex TYPE_VARIABLE (attribut symtable.SymbolTableType)
@anchor{library/symtable symtable SymbolTableType TYPE_VARIABLE}@anchor{4565}
@deffn {Attribut} TYPE_VARIABLE = "type variable"

Used for the symbol table of the bound, the constraint tuple or the
default value of a single type variable in the formal sense, i.e.,
a TypeVar, a TypeVarTuple or a ParamSpec object (the latter two do
not support a bound or a constraint tuple).
@end deffn


Ajouté dans la version 3.13.

@end deffn

@geindex SymbolTable (classe dans symtable)
@anchor{library/symtable symtable SymbolTable}@anchor{455d}
@deffn {Classe} symtable.SymbolTable

A namespace table for a block.  The constructor is not public.

@geindex get_type() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_type}@anchor{1596}
@deffn {Méthode} get_type ()

Return the type of the symbol table.  Possible values are members
of the @ref{1595,,SymbolTableType} enumeration.


Modifié dans la version 3.12: Added @code{'annotation'},  @code{'TypeVar bound'}, @code{'type alias'},
and @code{'type parameter'} as possible return values.



Modifié dans la version 3.13: Return values are members of the @ref{1595,,SymbolTableType} enumeration.

The exact values of the returned string may change in the future,
and thus, it is recommended to use @ref{1595,,SymbolTableType} members
instead of hard-coded strings.

@end deffn

@geindex get_id() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_id}@anchor{4566}
@deffn {Méthode} get_id ()

Return the table's identifier.
@end deffn

@geindex get_name() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_name}@anchor{4567}
@deffn {Méthode} get_name ()

Return the table's name.  This is the name of the class if the table is
for a class, the name of the function if the table is for a function, or
@code{'top'} if the table is global (@ref{1596,,get_type()} returns @code{'module'}).
For type parameter scopes (which are used for generic classes, functions,
and type aliases), it is the name of the underlying class, function, or
type alias. For type alias scopes, it is the name of the type alias.
For @ref{15c,,TypeVar} bound scopes, it is the name of the @code{TypeVar}.
@end deffn

@geindex get_lineno() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_lineno}@anchor{4568}
@deffn {Méthode} get_lineno ()

Return the number of the first line in the block this table represents.
@end deffn

@geindex is_optimized() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable is_optimized}@anchor{4569}
@deffn {Méthode} is_optimized ()

Return @code{True} if the locals in this table can be optimized.
@end deffn

@geindex is_nested() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable is_nested}@anchor{456a}
@deffn {Méthode} is_nested ()

Return @code{True} if the block is a nested class or function.
@end deffn

@geindex has_children() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable has_children}@anchor{456b}
@deffn {Méthode} has_children ()

Return @code{True} if the block has nested namespaces within it.  These can
be obtained with @ref{456c,,get_children()}.
@end deffn

@geindex get_identifiers() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_identifiers}@anchor{456d}
@deffn {Méthode} get_identifiers ()

Return a view object containing the names of symbols in the table.
See the @ref{21cc,,documentation of view objects}.
@end deffn

@geindex lookup() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable lookup}@anchor{456e}
@deffn {Méthode} lookup (name)

Lookup `name' in the table and return a @ref{1658,,Symbol} instance.
@end deffn

@geindex get_symbols() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_symbols}@anchor{456f}
@deffn {Méthode} get_symbols ()

Return a list of @ref{1658,,Symbol} instances for names in the table.
@end deffn

@geindex get_children() (méthode symtable.SymbolTable)
@anchor{library/symtable symtable SymbolTable get_children}@anchor{456c}
@deffn {Méthode} get_children ()

Return a list of the nested symbol tables.
@end deffn
@end deffn

@geindex Function (classe dans symtable)
@anchor{library/symtable symtable Function}@anchor{4570}
@deffn {Classe} symtable.Function

A namespace for a function or method.  This class inherits from
@ref{455d,,SymbolTable}.

@geindex get_parameters() (méthode symtable.Function)
@anchor{library/symtable symtable Function get_parameters}@anchor{4571}
@deffn {Méthode} get_parameters ()

Return a tuple containing names of parameters to this function.
@end deffn

@geindex get_locals() (méthode symtable.Function)
@anchor{library/symtable symtable Function get_locals}@anchor{4572}
@deffn {Méthode} get_locals ()

Return a tuple containing names of locals in this function.
@end deffn

@geindex get_globals() (méthode symtable.Function)
@anchor{library/symtable symtable Function get_globals}@anchor{4573}
@deffn {Méthode} get_globals ()

Return a tuple containing names of globals in this function.
@end deffn

@geindex get_nonlocals() (méthode symtable.Function)
@anchor{library/symtable symtable Function get_nonlocals}@anchor{4574}
@deffn {Méthode} get_nonlocals ()

Return a tuple containing names of explicitly declared nonlocals in this function.
@end deffn

@geindex get_frees() (méthode symtable.Function)
@anchor{library/symtable symtable Function get_frees}@anchor{4575}
@deffn {Méthode} get_frees ()

Return a tuple containing names of @ref{1ec4,,free (closure) variables}
in this function.
@end deffn
@end deffn

@geindex Class (classe dans symtable)
@anchor{library/symtable symtable Class}@anchor{4576}
@deffn {Classe} symtable.Class

A namespace of a class.  This class inherits from @ref{455d,,SymbolTable}.

@geindex get_methods() (méthode symtable.Class)
@anchor{library/symtable symtable Class get_methods}@anchor{2e3}
@deffn {Méthode} get_methods ()

Return a tuple containing the names of method-like functions declared
in the class.

Here, the term 'method' designates `any' function defined in the class
body via @ref{140e,,def} or @ref{5bb,,async def}.

Functions defined in a deeper scope (e.g., in an inner class) are not
picked up by @ref{2e3,,get_methods()}.

For example:

@example
>>> import symtable
>>> st = symtable.symtable('@w{'}'
... def outer(): pass
...
... class A:
...    def f():
...        def w(): pass
...
...    def g(self): pass
...
...    @@classmethod
...    async def h(cls): pass
...
...    global outer
...    def outer(self): pass
... '@w{'}', 'test', 'exec')
>>> class_A = st.get_children()[1]
>>> class_A.get_methods()
('f', 'g', 'h')
@end example

Although @code{A().f()} raises @ref{522,,TypeError} at runtime, @code{A.f} is still
considered as a method-like function.
@end deffn
@end deffn

@geindex Symbol (classe dans symtable)
@anchor{library/symtable symtable Symbol}@anchor{1658}
@deffn {Classe} symtable.Symbol

An entry in a @ref{455d,,SymbolTable} corresponding to an identifier in the
source.  The constructor is not public.

@geindex get_name() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol get_name}@anchor{4577}
@deffn {Méthode} get_name ()

Return the symbol's name.
@end deffn

@geindex is_referenced() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_referenced}@anchor{4578}
@deffn {Méthode} is_referenced ()

Return @code{True} if the symbol is used in its block.
@end deffn

@geindex is_imported() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_imported}@anchor{4579}
@deffn {Méthode} is_imported ()

Return @code{True} if the symbol is created from an import statement.
@end deffn

@geindex is_parameter() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_parameter}@anchor{457a}
@deffn {Méthode} is_parameter ()

Return @code{True} if the symbol is a parameter.
@end deffn

@geindex is_global() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_global}@anchor{457b}
@deffn {Méthode} is_global ()

Return @code{True} if the symbol is global.
@end deffn

@geindex is_nonlocal() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_nonlocal}@anchor{19b9}
@deffn {Méthode} is_nonlocal ()

Return @code{True} if the symbol is nonlocal.
@end deffn

@geindex is_declared_global() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_declared_global}@anchor{1303}
@deffn {Méthode} is_declared_global ()

Return @code{True} if the symbol is declared global with a global statement.
@end deffn

@geindex is_local() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_local}@anchor{457c}
@deffn {Méthode} is_local ()

Return @code{True} if the symbol is local to its block.
@end deffn

@geindex is_annotated() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_annotated}@anchor{457d}
@deffn {Méthode} is_annotated ()

Return @code{True} if the symbol is annotated.


Ajouté dans la version 3.6.

@end deffn

@geindex is_free() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_free}@anchor{457e}
@deffn {Méthode} is_free ()

Return @code{True} if the symbol is referenced in its block, but not assigned
to.
@end deffn

@geindex is_assigned() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_assigned}@anchor{457f}
@deffn {Méthode} is_assigned ()

Return @code{True} if the symbol is assigned to in its block.
@end deffn

@geindex is_namespace() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol is_namespace}@anchor{4580}
@deffn {Méthode} is_namespace ()

Return @code{True} if name binding introduces new namespace.

If the name is used as the target of a function or class statement, this
will be true.

Par exemple :

@example
>>> table = symtable.symtable("def some_func(): pass", "string", "exec")
>>> table.lookup("some_func").is_namespace()
True
@end example

Note that a single name can be bound to multiple objects.  If the result
is @code{True}, the name may also be bound to other objects, like an int or
list, that does not introduce a new namespace.
@end deffn

@geindex get_namespaces() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol get_namespaces}@anchor{4581}
@deffn {Méthode} get_namespaces ()

Return a list of namespaces bound to this name.
@end deffn

@geindex get_namespace() (méthode symtable.Symbol)
@anchor{library/symtable symtable Symbol get_namespace}@anchor{4582}
@deffn {Méthode} get_namespace ()

Return the namespace bound to this name. If more than one or no namespace
is bound to this name, a @ref{1ff,,ValueError} is raised.
@end deffn
@end deffn

@node Utilisation en ligne de commande<5>,,Examining Symbol Tables,symtable --- Access to the compiler's symbol tables
@anchor{library/symtable command-line-usage}@anchor{4583}@anchor{library/symtable symtable-cli}@anchor{4584}
@subsubsection Utilisation en ligne de commande.



Ajouté dans la version 3.13.


The @ref{d7,,symtable} module can be executed as a script from the command line.

@example
python -m symtable [infile...]
@end example

Symbol tables are generated for the specified Python source files and
dumped to stdout.
If no input file is specified, the content is read from stdin.

@node token --- Constants used with Python parse trees,keyword --- Testing for Python keywords,symtable --- Access to the compiler's symbol tables,Services du Langage Python
@anchor{library/token doc}@anchor{4585}@anchor{library/token module-token}@anchor{f9}@anchor{library/token token-constants-used-with-python-parse-trees}@anchor{4586}
@subsection @code{token} --- Constants used with Python parse trees


@geindex module; token

`Code source :' Lib/token.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/token.py}


__________________________________________________________________


This module provides constants which represent the numeric values of leaf nodes
of the parse tree (terminal tokens).  Refer to the file @code{Grammar/Tokens}
in the Python distribution for the definitions of the names in the context of
the language grammar.  The specific numeric values which the names map to may
change between Python versions.

Le module fournit également une correspondance entre les codes numériques et les noms et certaines fonctions. Les fonctions reflètent les définitions des fichiers d'en-tête C de Python.

@geindex tok_name (dans le module token)
@anchor{library/token token tok_name}@anchor{4587}
@deffn {Données} token.tok_name

Dictionnaire faisant correspondre les valeurs numériques des constantes définies dans ce module à leurs noms, permettant de générer une représentation plus humaine des arbres syntaxiques.
@end deffn

@geindex ISTERMINAL() (dans le module token)
@anchor{library/token token ISTERMINAL}@anchor{4588}
@deffn {Fonction} token.ISTERMINAL (x)

Return @code{True} for terminal token values.
@end deffn

@geindex ISNONTERMINAL() (dans le module token)
@anchor{library/token token ISNONTERMINAL}@anchor{4589}
@deffn {Fonction} token.ISNONTERMINAL (x)

Return @code{True} for non-terminal token values.
@end deffn

@geindex ISEOF() (dans le module token)
@anchor{library/token token ISEOF}@anchor{458a}
@deffn {Fonction} token.ISEOF (x)

Return @code{True} if `x' is the marker indicating the end of input.
@end deffn

Les constantes associées aux jetons sont :

@c Auto-generated by Tools/build/generate_token.py

@geindex ENDMARKER (dans le module token)
@anchor{library/token token ENDMARKER}@anchor{458b}
@deffn {Données} token.ENDMARKER
@end deffn

@geindex NAME (dans le module token)
@anchor{library/token token NAME}@anchor{458c}
@deffn {Données} token.NAME
@end deffn

@geindex NUMBER (dans le module token)
@anchor{library/token token NUMBER}@anchor{458d}
@deffn {Données} token.NUMBER
@end deffn

@geindex STRING (dans le module token)
@anchor{library/token token STRING}@anchor{458e}
@deffn {Données} token.STRING
@end deffn

@geindex NEWLINE (dans le module token)
@anchor{library/token token NEWLINE}@anchor{458f}
@deffn {Données} token.NEWLINE
@end deffn

@geindex INDENT (dans le module token)
@anchor{library/token token INDENT}@anchor{4590}
@deffn {Données} token.INDENT
@end deffn

@geindex DEDENT (dans le module token)
@anchor{library/token token DEDENT}@anchor{4591}
@deffn {Données} token.DEDENT
@end deffn

@geindex LPAR (dans le module token)
@anchor{library/token token LPAR}@anchor{4592}
@deffn {Données} token.LPAR

Token value for @code{"("}.
@end deffn

@geindex RPAR (dans le module token)
@anchor{library/token token RPAR}@anchor{4593}
@deffn {Données} token.RPAR

Token value for @code{")"}.
@end deffn

@geindex LSQB (dans le module token)
@anchor{library/token token LSQB}@anchor{4594}
@deffn {Données} token.LSQB

Token value for @code{"["}.
@end deffn

@geindex RSQB (dans le module token)
@anchor{library/token token RSQB}@anchor{4595}
@deffn {Données} token.RSQB

Token value for @code{"]"}.
@end deffn

@geindex COLON (dans le module token)
@anchor{library/token token COLON}@anchor{4596}
@deffn {Données} token.COLON

Token value for @code{":"}.
@end deffn

@geindex COMMA (dans le module token)
@anchor{library/token token COMMA}@anchor{4597}
@deffn {Données} token.COMMA

Token value for @code{","}.
@end deffn

@geindex SEMI (dans le module token)
@anchor{library/token token SEMI}@anchor{4598}
@deffn {Données} token.SEMI

Token value for @code{";"}.
@end deffn

@geindex PLUS (dans le module token)
@anchor{library/token token PLUS}@anchor{4599}
@deffn {Données} token.PLUS

Token value for @code{"+"}.
@end deffn

@geindex MINUS (dans le module token)
@anchor{library/token token MINUS}@anchor{459a}
@deffn {Données} token.MINUS

Token value for @code{"-"}.
@end deffn

@geindex STAR (dans le module token)
@anchor{library/token token STAR}@anchor{459b}
@deffn {Données} token.STAR

Token value for @code{"*"}.
@end deffn

@geindex SLASH (dans le module token)
@anchor{library/token token SLASH}@anchor{459c}
@deffn {Données} token.SLASH

Token value for @code{"/"}.
@end deffn

@geindex VBAR (dans le module token)
@anchor{library/token token VBAR}@anchor{459d}
@deffn {Données} token.VBAR

Token value for @code{"|"}.
@end deffn

@geindex AMPER (dans le module token)
@anchor{library/token token AMPER}@anchor{459e}
@deffn {Données} token.AMPER

Token value for @code{"&"}.
@end deffn

@geindex LESS (dans le module token)
@anchor{library/token token LESS}@anchor{459f}
@deffn {Données} token.LESS

Token value for @code{"<"}.
@end deffn

@geindex GREATER (dans le module token)
@anchor{library/token token GREATER}@anchor{45a0}
@deffn {Données} token.GREATER

Token value for @code{">"}.
@end deffn

@geindex EQUAL (dans le module token)
@anchor{library/token token EQUAL}@anchor{45a1}
@deffn {Données} token.EQUAL

Token value for @code{"="}.
@end deffn

@geindex DOT (dans le module token)
@anchor{library/token token DOT}@anchor{45a2}
@deffn {Données} token.DOT

Token value for @code{"."}.
@end deffn

@geindex PERCENT (dans le module token)
@anchor{library/token token PERCENT}@anchor{45a3}
@deffn {Données} token.PERCENT

Token value for @code{"%"}.
@end deffn

@geindex LBRACE (dans le module token)
@anchor{library/token token LBRACE}@anchor{45a4}
@deffn {Données} token.LBRACE

Token value for @code{"@{"}.
@end deffn

@geindex RBRACE (dans le module token)
@anchor{library/token token RBRACE}@anchor{45a5}
@deffn {Données} token.RBRACE

Token value for @code{"@}"}.
@end deffn

@geindex EQEQUAL (dans le module token)
@anchor{library/token token EQEQUAL}@anchor{45a6}
@deffn {Données} token.EQEQUAL

Token value for @code{"=="}.
@end deffn

@geindex NOTEQUAL (dans le module token)
@anchor{library/token token NOTEQUAL}@anchor{45a7}
@deffn {Données} token.NOTEQUAL

Token value for @code{"!="}.
@end deffn

@geindex LESSEQUAL (dans le module token)
@anchor{library/token token LESSEQUAL}@anchor{45a8}
@deffn {Données} token.LESSEQUAL

Token value for @code{"<="}.
@end deffn

@geindex GREATEREQUAL (dans le module token)
@anchor{library/token token GREATEREQUAL}@anchor{45a9}
@deffn {Données} token.GREATEREQUAL

Token value for @code{">="}.
@end deffn

@geindex TILDE (dans le module token)
@anchor{library/token token TILDE}@anchor{45aa}
@deffn {Données} token.TILDE

Token value for @code{"~"}.
@end deffn

@geindex CIRCUMFLEX (dans le module token)
@anchor{library/token token CIRCUMFLEX}@anchor{45ab}
@deffn {Données} token.CIRCUMFLEX

Token value for @code{"^"}.
@end deffn

@geindex LEFTSHIFT (dans le module token)
@anchor{library/token token LEFTSHIFT}@anchor{45ac}
@deffn {Données} token.LEFTSHIFT

Token value for @code{"<<"}.
@end deffn

@geindex RIGHTSHIFT (dans le module token)
@anchor{library/token token RIGHTSHIFT}@anchor{45ad}
@deffn {Données} token.RIGHTSHIFT

Token value for @code{">>"}.
@end deffn

@geindex DOUBLESTAR (dans le module token)
@anchor{library/token token DOUBLESTAR}@anchor{45ae}
@deffn {Données} token.DOUBLESTAR

Token value for @code{"**"}.
@end deffn

@geindex PLUSEQUAL (dans le module token)
@anchor{library/token token PLUSEQUAL}@anchor{45af}
@deffn {Données} token.PLUSEQUAL

Token value for @code{"+="}.
@end deffn

@geindex MINEQUAL (dans le module token)
@anchor{library/token token MINEQUAL}@anchor{45b0}
@deffn {Données} token.MINEQUAL

Token value for @code{"-="}.
@end deffn

@geindex STAREQUAL (dans le module token)
@anchor{library/token token STAREQUAL}@anchor{45b1}
@deffn {Données} token.STAREQUAL

Token value for @code{"*="}.
@end deffn

@geindex SLASHEQUAL (dans le module token)
@anchor{library/token token SLASHEQUAL}@anchor{45b2}
@deffn {Données} token.SLASHEQUAL

Token value for @code{"/="}.
@end deffn

@geindex PERCENTEQUAL (dans le module token)
@anchor{library/token token PERCENTEQUAL}@anchor{45b3}
@deffn {Données} token.PERCENTEQUAL

Token value for @code{"%="}.
@end deffn

@geindex AMPEREQUAL (dans le module token)
@anchor{library/token token AMPEREQUAL}@anchor{45b4}
@deffn {Données} token.AMPEREQUAL

Token value for @code{"&="}.
@end deffn

@geindex VBAREQUAL (dans le module token)
@anchor{library/token token VBAREQUAL}@anchor{45b5}
@deffn {Données} token.VBAREQUAL

Token value for @code{"|="}.
@end deffn

@geindex CIRCUMFLEXEQUAL (dans le module token)
@anchor{library/token token CIRCUMFLEXEQUAL}@anchor{45b6}
@deffn {Données} token.CIRCUMFLEXEQUAL

Token value for @code{"^="}.
@end deffn

@geindex LEFTSHIFTEQUAL (dans le module token)
@anchor{library/token token LEFTSHIFTEQUAL}@anchor{45b7}
@deffn {Données} token.LEFTSHIFTEQUAL

Token value for @code{"<<="}.
@end deffn

@geindex RIGHTSHIFTEQUAL (dans le module token)
@anchor{library/token token RIGHTSHIFTEQUAL}@anchor{45b8}
@deffn {Données} token.RIGHTSHIFTEQUAL

Token value for @code{">>="}.
@end deffn

@geindex DOUBLESTAREQUAL (dans le module token)
@anchor{library/token token DOUBLESTAREQUAL}@anchor{45b9}
@deffn {Données} token.DOUBLESTAREQUAL

Token value for @code{"**="}.
@end deffn

@geindex DOUBLESLASH (dans le module token)
@anchor{library/token token DOUBLESLASH}@anchor{45ba}
@deffn {Données} token.DOUBLESLASH

Token value for @code{"//"}.
@end deffn

@geindex DOUBLESLASHEQUAL (dans le module token)
@anchor{library/token token DOUBLESLASHEQUAL}@anchor{45bb}
@deffn {Données} token.DOUBLESLASHEQUAL

Token value for @code{"//="}.
@end deffn

@geindex AT (dans le module token)
@anchor{library/token token AT}@anchor{45bc}
@deffn {Données} token.AT

Token value for @code{"@@"}.
@end deffn

@geindex ATEQUAL (dans le module token)
@anchor{library/token token ATEQUAL}@anchor{45bd}
@deffn {Données} token.ATEQUAL

Token value for @code{"@@="}.
@end deffn

@geindex RARROW (dans le module token)
@anchor{library/token token RARROW}@anchor{45be}
@deffn {Données} token.RARROW

Token value for @code{"->"}.
@end deffn

@geindex ELLIPSIS (dans le module token)
@anchor{library/token token ELLIPSIS}@anchor{45bf}
@deffn {Données} token.ELLIPSIS

Token value for @code{"..."}.
@end deffn

@geindex COLONEQUAL (dans le module token)
@anchor{library/token token COLONEQUAL}@anchor{45c0}
@deffn {Données} token.COLONEQUAL

Token value for @code{":="}.
@end deffn

@geindex EXCLAMATION (dans le module token)
@anchor{library/token token EXCLAMATION}@anchor{45c1}
@deffn {Données} token.EXCLAMATION

Token value for @code{"!"}.
@end deffn

@geindex OP (dans le module token)
@anchor{library/token token OP}@anchor{45c2}
@deffn {Données} token.OP
@end deffn

@geindex TYPE_IGNORE (dans le module token)
@anchor{library/token token TYPE_IGNORE}@anchor{45c3}
@deffn {Données} token.TYPE_IGNORE
@end deffn

@geindex TYPE_COMMENT (dans le module token)
@anchor{library/token token TYPE_COMMENT}@anchor{45c4}
@deffn {Données} token.TYPE_COMMENT
@end deffn

@geindex SOFT_KEYWORD (dans le module token)
@anchor{library/token token SOFT_KEYWORD}@anchor{45c5}
@deffn {Données} token.SOFT_KEYWORD
@end deffn

@geindex FSTRING_START (dans le module token)
@anchor{library/token token FSTRING_START}@anchor{45c6}
@deffn {Données} token.FSTRING_START
@end deffn

@geindex FSTRING_MIDDLE (dans le module token)
@anchor{library/token token FSTRING_MIDDLE}@anchor{45c7}
@deffn {Données} token.FSTRING_MIDDLE
@end deffn

@geindex FSTRING_END (dans le module token)
@anchor{library/token token FSTRING_END}@anchor{45c8}
@deffn {Données} token.FSTRING_END
@end deffn

@geindex COMMENT (dans le module token)
@anchor{library/token token COMMENT}@anchor{45c9}
@deffn {Données} token.COMMENT
@end deffn

@geindex NL (dans le module token)
@anchor{library/token token NL}@anchor{45ca}
@deffn {Données} token.NL
@end deffn

@geindex ERRORTOKEN (dans le module token)
@anchor{library/token token ERRORTOKEN}@anchor{45cb}
@deffn {Données} token.ERRORTOKEN
@end deffn

@geindex N_TOKENS (dans le module token)
@anchor{library/token token N_TOKENS}@anchor{45cc}
@deffn {Données} token.N_TOKENS
@end deffn

@geindex NT_OFFSET (dans le module token)
@anchor{library/token token NT_OFFSET}@anchor{45cd}
@deffn {Données} token.NT_OFFSET
@end deffn

Les types de jetons suivants ne sont pas utilisés par l'analyseur lexical C mais sont requis par le module @ref{fa,,tokenize}.


@deffn {Données} token.COMMENT

Valeur du jeton utilisée pour indiquer un commentaire.
@end deffn


@deffn {Données} token.NL

Valeur du jeton utilisée pour indiquer un retour à la ligne non terminal. Le jeton @ref{458f,,NEWLINE} indique la fin d'une ligne logique de code Python; les jetons @code{NL} sont générés quand une ligne logique de code s'étend sur plusieurs lignes.
@end deffn

@geindex ENCODING (dans le module token)
@anchor{library/token token ENCODING}@anchor{45ce}
@deffn {Données} token.ENCODING

Valeur de jeton qui indique l'encodage utilisé pour décoder le fichier initial. Le premier jeton renvoyé par @ref{4c3,,tokenize.tokenize()} sera toujours un jeton @code{ENCODING}.
@end deffn


@deffn {Données} token.TYPE_COMMENT

Token value indicating that a type comment was recognized.  Such
tokens are only produced when @ref{1a6,,ast.parse()} is invoked with
@code{type_comments=True}.
@end deffn

@geindex EXACT_TOKEN_TYPES (dans le module token)
@anchor{library/token token EXACT_TOKEN_TYPES}@anchor{151a}
@deffn {Données} token.EXACT_TOKEN_TYPES

A dictionary mapping the string representation of a token to its numeric code.


Ajouté dans la version 3.8.

@end deffn


Modifié dans la version 3.5: Added @code{AWAIT} and @code{ASYNC} tokens.



Modifié dans la version 3.7: Ajout des jetons @ref{45c9,,COMMENT}, @ref{45ca,,NL} et @ref{45ce,,ENCODING}.



Modifié dans la version 3.7: Removed @code{AWAIT} and @code{ASYNC} tokens. "async" and "await" are
now tokenized as @ref{458c,,NAME} tokens.



Modifié dans la version 3.8: Added @ref{45c4,,TYPE_COMMENT}, @ref{45c3,,TYPE_IGNORE}, @ref{45c0,,COLONEQUAL}.
Added @code{AWAIT} and @code{ASYNC} tokens back (they're needed
to support parsing older Python versions for @ref{1a6,,ast.parse()} with
@code{feature_version} set to 6 or lower).



Modifié dans la version 3.13: Removed @code{AWAIT} and @code{ASYNC} tokens again.


@node keyword --- Testing for Python keywords,tokenize --- Tokenizer for Python source,token --- Constants used with Python parse trees,Services du Langage Python
@anchor{library/keyword doc}@anchor{45cf}@anchor{library/keyword keyword-testing-for-python-keywords}@anchor{45d0}@anchor{library/keyword module-keyword}@anchor{83}
@subsection @code{keyword} --- Testing for Python keywords


@geindex module; keyword

`Code source :' Lib/keyword.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/keyword.py}


__________________________________________________________________


This module allows a Python program to determine if a string is a
@ref{1e22,,keyword} or @ref{7f6,,soft keyword}.

@geindex iskeyword() (dans le module keyword)
@anchor{library/keyword keyword iskeyword}@anchor{214a}
@deffn {Fonction} keyword.iskeyword (s)

Renvoie vrai si `s' est un @ref{1e22,,mot-clé} de Python.
@end deffn

@geindex kwlist (dans le module keyword)
@anchor{library/keyword keyword kwlist}@anchor{45d1}
@deffn {Données} keyword.kwlist

Séquence contenant tous les @ref{1e22,,mots-clés} définis par l'interpréteur.  Si certains mots-clés sont définis pour être actifs seulement si des instructions @ref{0,,__future__} particulières sont effectives, ils seront tout de même inclus.
@end deffn

@geindex issoftkeyword() (dans le module keyword)
@anchor{library/keyword keyword issoftkeyword}@anchor{45d2}
@deffn {Fonction} keyword.issoftkeyword (s)

Return @code{True} if `s' is a Python @ref{7f6,,soft keyword}.


Ajouté dans la version 3.9.

@end deffn

@geindex softkwlist (dans le module keyword)
@anchor{library/keyword keyword softkwlist}@anchor{45d3}
@deffn {Données} keyword.softkwlist

Sequence containing all the @ref{7f6,,soft keywords} defined for the
interpreter.  If any soft keywords are defined to only be active when particular
@ref{0,,__future__} statements are in effect, these will be included as well.


Ajouté dans la version 3.9.

@end deffn

@node tokenize --- Tokenizer for Python source,tabnanny --- Detection of ambiguous indentation,keyword --- Testing for Python keywords,Services du Langage Python
@anchor{library/tokenize doc}@anchor{45d4}@anchor{library/tokenize module-tokenize}@anchor{fa}@anchor{library/tokenize tokenize-tokenizer-for-python-source}@anchor{45d5}
@subsection @code{tokenize} --- Tokenizer for Python source


@geindex module; tokenize

`Code source :' Lib/tokenize.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tokenize.py}


__________________________________________________________________


The @ref{fa,,tokenize} module provides a lexical scanner for Python source code,
implemented in Python.  The scanner in this module returns comments as tokens
as well, making it useful for implementing "pretty-printers", including
colorizers for on-screen displays.

Pour simplifier la gestion de flux de `tokens', tous les `tokens' @ref{1e62,,operator} et @ref{1e63,,delimiter}, ainsi que les @code{Ellipsis*} sont renvoyés en utilisant le `token' générique @ref{45c2,,OP}. Le type exact peut être déterminé en vérifiant la propriété @code{exact_type} du @ref{639,,named tuple} renvoyé par @ref{4c3,,tokenize.tokenize()}.

@cartouche
@quotation Avertissement 
Note that the functions in this module are only designed to parse
syntactically valid Python code (code that does not raise when parsed
using @ref{1a6,,ast.parse()}).  The behavior of the functions in this module is
`undefined' when providing invalid Python code and it can change at any
point.
@end quotation
@end cartouche

@menu
* Analyse Lexicale:: 
* Utilisation en ligne de commande.: Utilisation en ligne de commande<6>. 
* Exemples: Exemples<34>. 

@end menu

@node Analyse Lexicale,Utilisation en ligne de commande<6>,,tokenize --- Tokenizer for Python source
@anchor{library/tokenize tokenizing-input}@anchor{45d6}
@subsubsection Analyse Lexicale


Le point d'entrée principal est un @ref{104a,,générateur} :

@geindex tokenize() (dans le module tokenize)
@anchor{library/tokenize tokenize tokenize}@anchor{4c3}
@deffn {Fonction} tokenize.tokenize (readline)

Le générateur @ref{4c3,,tokenize()} prend un argument `readline' qui doit être un objet appelable exposant la même interface que la méthode @ref{1307,,io.IOBase.readline()} des objets fichiers. Chaque appel a la fonction doit renvoyer une ligne sous forme de `bytes'.

The generator produces 5-tuples with these members: the token type; the
token string; a 2-tuple @code{(srow, scol)} of ints specifying the row and
column where the token begins in the source; a 2-tuple @code{(erow, ecol)} of
ints specifying the row and column where the token ends in the source; and
the line on which the token was found. The line passed (the last tuple item)
is the `physical' line.  The 5 tuple is returned as a @ref{639,,named tuple}
with the field names:
@code{type string start end line}.

Le @ref{639,,n-uplet nommé} a une propriété additionnelle appelée @code{exact_type} qui contient le type exact de l'opérateur pour les jetons @ref{45c2,,OP}. Pour tous les autres types de jetons, @code{exact_type} est égal au champ @code{type} du `n'-uplet nommé.


Modifié dans la version 3.1: prise en charge des `n'-uplets nommés.



Modifié dans la version 3.3: prise en charge de @code{exact_type}.


@ref{4c3,,tokenize()} détermine le codage source du fichier en recherchant une nomenclature UTF-8 ou un cookie d'encodage, selon la 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/}.
@end deffn

@geindex generate_tokens() (dans le module tokenize)
@anchor{library/tokenize tokenize generate_tokens}@anchor{4c4}
@deffn {Fonction} tokenize.generate_tokens (readline)

Tokenize a source reading unicode strings instead of bytes.

Like @ref{4c3,,tokenize()}, the `readline' argument is a callable returning
a single line of input. However, @ref{4c4,,generate_tokens()} expects `readline'
to return a str object rather than bytes.

The result is an iterator yielding named tuples, exactly like
@ref{4c3,,tokenize()}. It does not yield an @ref{45ce,,ENCODING} token.
@end deffn

Toutes les constantes du module @ref{f9,,token} sont également exportées depuis module @ref{fa,,tokenize}.

Une autre fonction est fournie pour inverser le processus de tokenisation. Ceci est utile pour créer des outils permettant de codifier un script, de modifier le flux de jetons et de réécrire le script modifié.

@geindex untokenize() (dans le module tokenize)
@anchor{library/tokenize tokenize untokenize}@anchor{1547}
@deffn {Fonction} tokenize.untokenize (iterable)

Convertit les jetons en code source Python. L'`iterable' doit renvoyer des séquences avec au moins deux éléments, le type de jeton et la chaîne de caractères associée. Tout élément de séquence supplémentaire est ignoré.

Le script reconstruit est renvoyé sous la forme d'une chaîne unique. Le résultat est garanti pour que le jeton corresponde à l'entrée afin que la conversion soit sans perte et que les allers et retours soient assurés.  La garantie ne s'applique qu'au type de jeton et à la chaîne de jetons car l'espacement entre les jetons (positions des colonnes) peut changer.

It returns bytes, encoded using the @ref{45ce,,ENCODING} token, which
is the first token sequence output by @ref{4c3,,tokenize()}. If there is no
encoding token in the input, it returns a str instead.
@end deffn

@ref{4c3,,tokenize()} a besoin de détecter le codage des fichiers sources qu'il code. La fonction utilisée pour cela est disponible :

@geindex detect_encoding() (dans le module tokenize)
@anchor{library/tokenize tokenize detect_encoding}@anchor{27e1}
@deffn {Fonction} tokenize.detect_encoding (readline)

La fonction @ref{27e1,,detect_encoding()} est utilisée pour détecter l'encodage à utiliser pour décoder un fichier source Python. Il nécessite un seul argument, `readline', de la même manière que le générateur @ref{4c3,,tokenize()}.

Il appelle `readline' au maximum deux fois et renvoie le codage utilisé (sous forme de chaîne) et une liste de toutes les lignes (non décodées à partir des octets) dans lesquelles il a été lu.

Il détecte l'encodage par la présence d'une marqueur UTF-8 (`BOM') ou d'un cookie de codage, comme spécifié dans la 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/}. Si un `BOM' et un cookie sont présents, mais en désaccord, un @ref{18b,,SyntaxError} sera levée. Notez que si le `BOM' est trouvé, @code{'utf-8-sig'} sera renvoyé comme encodage.

Si aucun codage n'est spécifié, la valeur par défaut, @code{'utf-8'}, sera renvoyée.

Utilisez @ref{27e0,,open()} pour ouvrir les fichiers source Python : ça utilise @ref{27e1,,detect_encoding()} pour détecter le codage du fichier.
@end deffn

@geindex open() (dans le module tokenize)
@anchor{library/tokenize tokenize open}@anchor{27e0}
@deffn {Fonction} tokenize.open (filename)

Ouvre un fichier en mode lecture seule en utilisant l'encodage détecté par @code{dectect_encoding()}.


Ajouté dans la version 3.2.

@end deffn

@geindex TokenError
@anchor{library/tokenize tokenize TokenError}@anchor{52d}
@deffn {Exception} tokenize.TokenError

Déclenché lorsque soit une `docstring' soit une expression qui pourrait être divisée sur plusieurs lignes n'est pas complété dans le fichier, par exemple :

@example
"""Beginning of
docstring
@end example

ou :

@example
[1,
 2,
 3
@end example
@end deffn

@node Utilisation en ligne de commande<6>,Exemples<34>,Analyse Lexicale,tokenize --- Tokenizer for Python source
@anchor{library/tokenize command-line-usage}@anchor{45d7}@anchor{library/tokenize tokenize-cli}@anchor{45d8}
@subsubsection Utilisation en ligne de commande.



Ajouté dans la version 3.3.


Le module @ref{fa,,tokenize} peut être exécuté en tant que script à partir de la ligne de commande. C'est aussi simple que :

@example
python -m tokenize [-e] [filename.py]
@end example

Les options suivantes sont acceptées :

@geindex option de ligne de commande tokenize; -h
@geindex option de ligne de commande tokenize; --help
@anchor{library/tokenize cmdoption-tokenize-h}@anchor{45d9}@anchor{library/tokenize cmdoption-tokenize-help}@anchor{45da}
@deffn {Option} @w{-}h, @w{-}@w{-}help

Montre ce message d'aide et quitte
@end deffn

@geindex option de ligne de commande tokenize; -e
@geindex option de ligne de commande tokenize; --exact
@anchor{library/tokenize cmdoption-tokenize-e}@anchor{45db}@anchor{library/tokenize cmdoption-tokenize-exact}@anchor{45dc}
@deffn {Option} @w{-}e, @w{-}@w{-}exact

Affiche les noms de jetons en utilisant le même type.
@end deffn

Si @code{filename.py} est spécifié, son contenu est tokenisé vers `stdout'. Sinon, la tokenisation est effectuée sur ce qui est fourni sur `stdin'.

@node Exemples<34>,,Utilisation en ligne de commande<6>,tokenize --- Tokenizer for Python source
@anchor{library/tokenize examples}@anchor{45dd}
@subsubsection Exemples


Exemple d'un script qui transforme les littéraux de type `float' en type `Decimal' :

@example
from tokenize import tokenize, untokenize, NUMBER, STRING, NAME, OP
from io import BytesIO

def decistmt(s):
    """Substitute Decimals for floats in a string of statements.

    >>> from decimal import Decimal
    >>> s = 'print(+21.3e-5*-.1234/81.7)'
    >>> decistmt(s)
    "print (+Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7'))"

    The format of the exponent is inherited from the platform C library.
    Known cases are "e-007" (Windows) and "e-07" (not Windows).  Since
    we're only showing 12 digits, and the 13th isn't close to 5, the
    rest of the output should be platform-independent.

    >>> exec(s)  #doctest: +ELLIPSIS
    -3.21716034272e-0...7

    Output from calculations with Decimal should be identical across all
    platforms.

    >>> exec(decistmt(s))
    -3.217160342717258261933904529E-7
    """
    result = []
    g = tokenize(BytesIO(s.encode('utf-8')).readline)  # tokenize the string
    for toknum, tokval, _, _, _ in g:
        if toknum == NUMBER and '.' in tokval:  # replace NUMBER tokens
            result.extend([
                (NAME, 'Decimal'),
                (OP, '('),
                (STRING, repr(tokval)),
                (OP, ')')
            ])
        else:
            result.append((toknum, tokval))
    return untokenize(result).decode('utf-8')
@end example

Exemple de tokenisation à partir de la ligne de commande. Le script :

@example
def say_hello():
    print("Hello, World!")

say_hello()
@end example

sera tokenisé à la sortie suivante où la première colonne est la plage des coordonnées de la ligne/colonne où se trouve le jeton, la deuxième colonne est le nom du jeton, et la dernière colonne est la valeur du jeton (le cas échéant)

@example
$ python -m tokenize hello.py
0,0-0,0:            ENCODING       'utf-8'
1,0-1,3:            NAME           'def'
1,4-1,13:           NAME           'say_hello'
1,13-1,14:          OP             '('
1,14-1,15:          OP             ')'
1,15-1,16:          OP             ':'
1,16-1,17:          NEWLINE        '\n'
2,0-2,4:            INDENT         '    '
2,4-2,9:            NAME           'print'
2,9-2,10:           OP             '('
2,10-2,25:          STRING         '"Hello, World!"'
2,25-2,26:          OP             ')'
2,26-2,27:          NEWLINE        '\n'
3,0-3,1:            NL             '\n'
4,0-4,0:            DEDENT         '@w{'}
4,0-4,9:            NAME           'say_hello'
4,9-4,10:           OP             '('
4,10-4,11:          OP             ')'
4,11-4,12:          NEWLINE        '\n'
5,0-5,0:            ENDMARKER      '@w{'}
@end example

Les noms exacts des types de jeton peuvent être affichés en utilisant l’option : @ref{45db,,-e} :

@example
$ python -m tokenize -e hello.py
0,0-0,0:            ENCODING       'utf-8'
1,0-1,3:            NAME           'def'
1,4-1,13:           NAME           'say_hello'
1,13-1,14:          LPAR           '('
1,14-1,15:          RPAR           ')'
1,15-1,16:          COLON          ':'
1,16-1,17:          NEWLINE        '\n'
2,0-2,4:            INDENT         '    '
2,4-2,9:            NAME           'print'
2,9-2,10:           LPAR           '('
2,10-2,25:          STRING         '"Hello, World!"'
2,25-2,26:          RPAR           ')'
2,26-2,27:          NEWLINE        '\n'
3,0-3,1:            NL             '\n'
4,0-4,0:            DEDENT         '@w{'}
4,0-4,9:            NAME           'say_hello'
4,9-4,10:           LPAR           '('
4,10-4,11:          RPAR           ')'
4,11-4,12:          NEWLINE        '\n'
5,0-5,0:            ENDMARKER      '@w{'}
@end example

Example of tokenizing a file programmatically, reading unicode
strings instead of bytes with @ref{4c4,,generate_tokens()}:

@example
import tokenize

with tokenize.open('hello.py') as f:
    tokens = tokenize.generate_tokens(f.readline)
    for token in tokens:
        print(token)
@end example

Or reading bytes directly with @ref{4c3,,tokenize()}:

@example
import tokenize

with open('hello.py', 'rb') as f:
    tokens = tokenize.tokenize(f.readline)
    for token in tokens:
        print(token)
@end example

@node tabnanny --- Detection of ambiguous indentation,pyclbr --- Python module browser support,tokenize --- Tokenizer for Python source,Services du Langage Python
@anchor{library/tabnanny doc}@anchor{45de}@anchor{library/tabnanny module-tabnanny}@anchor{dc}@anchor{library/tabnanny tabnanny-detection-of-ambiguous-indentation}@anchor{45df}
@subsection @code{tabnanny} --- Detection of ambiguous indentation


@geindex module; tabnanny

@c rudimentary documentation based on module comments

`Code source :' Lib/tabnanny.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tabnanny.py}


__________________________________________________________________


Pour l'instant ce module est destiné à être appelé comme un script. Toutefois, il est possible de l'importer dans un IDE et d'utiliser la fonction @ref{45e0,,check()} décrite ci-dessous.

@cartouche
@quotation Note 
L'API fournie par ce module est susceptible de changer dans les versions futures ; ces modifications peuvent ne pas être rétro-compatibles.
@end quotation
@end cartouche

@geindex check() (dans le module tabnanny)
@anchor{library/tabnanny tabnanny check}@anchor{45e0}
@deffn {Fonction} tabnanny.check (file_or_dir)

Si `file_or_dir' est un répertoire et non un lien symbolique, alors descend récursivement l'arborescence de répertoire nommé par `file_or_dir', en vérifiant tous les fichiers @code{.py} en chemin.  Si `file_or_dir' est un fichier source Python ordinaire, il est vérifié pour les problèmes liés aux espaces blancs.  Les messages de diagnostic sont écrits sur la sortie standard à l'aide de la fonction @ref{f60,,print()}.
@end deffn

@geindex verbose (dans le module tabnanny)
@anchor{library/tabnanny tabnanny verbose}@anchor{45e1}
@deffn {Données} tabnanny.verbose

Option indiquant s'il faut afficher des messages détaillés. Cela est incrémenté par l'option @code{-v} s'il est appelé comme un script.
@end deffn

@geindex filename_only (dans le module tabnanny)
@anchor{library/tabnanny tabnanny filename_only}@anchor{45e2}
@deffn {Données} tabnanny.filename_only

Option indiquant s'il faut afficher uniquement les noms de fichiers contenant des problèmes liés aux espaces blancs.  Est défini à True par l'option @code{-q} s'il est appelé comme un script.
@end deffn

@geindex NannyNag
@anchor{library/tabnanny tabnanny NannyNag}@anchor{45e3}
@deffn {Exception} tabnanny.NannyNag

Déclenché par @ref{45e4,,process_tokens()} si une indentation ambiguë est détectée. Capturé et géré dans @ref{45e0,,check()}.
@end deffn

@geindex process_tokens() (dans le module tabnanny)
@anchor{library/tabnanny tabnanny process_tokens}@anchor{45e4}
@deffn {Fonction} tabnanny.process_tokens (tokens)

Cette fonction est utilisée par @ref{45e0,,check()} pour traiter les jetons générés par le module @ref{fa,,tokenize}.
@end deffn

@c XXX document errprint, format_witnesses, Whitespace, check_equal, indents,
@c reset_globals


@subsubheading Voir aussi



@table @asis

@item Module @ref{fa,,tokenize}

Analyseur lexical pour le code source Python.
@end table


@node pyclbr --- Python module browser support,py_compile --- Compile Python source files,tabnanny --- Detection of ambiguous indentation,Services du Langage Python
@anchor{library/pyclbr doc}@anchor{45e5}@anchor{library/pyclbr module-pyclbr}@anchor{b3}@anchor{library/pyclbr pyclbr-python-module-browser-support}@anchor{45e6}
@subsection @code{pyclbr} --- Python module browser support


@geindex module; pyclbr

`Code source :' Lib/pyclbr.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pyclbr.py}


__________________________________________________________________


The @ref{b3,,pyclbr} module provides limited information about the
functions, classes, and methods defined in a Python-coded module.  The
information is sufficient to implement a module browser.  The
information is extracted from the Python source code rather than by
importing the module, so this module is safe to use with untrusted code.
This restriction makes it impossible to use this module with modules not
implemented in Python, including all standard and optional extension
modules.

@geindex readmodule() (dans le module pyclbr)
@anchor{library/pyclbr pyclbr readmodule}@anchor{815}
@deffn {Fonction} pyclbr.readmodule (module, path=None)

Return a dictionary mapping module-level class names to class
descriptors.  If possible, descriptors for imported base classes are
included.  Parameter `module' is a string with the name of the module
to read; it may be the name of a module within a package.  If given,
`path' is a sequence of directory paths prepended to @code{sys.path},
which is used to locate the module source code.

This function is the original interface and is only kept for back
compatibility.  It returns a filtered version of the following.
@end deffn

@geindex readmodule_ex() (dans le module pyclbr)
@anchor{library/pyclbr pyclbr readmodule_ex}@anchor{816}
@deffn {Fonction} pyclbr.readmodule_ex (module, path=None)

Return a dictionary-based tree containing a function or class
descriptors for each function and class defined in the module with a
@code{def} or @code{class} statement.  The returned dictionary maps
module-level function and class names to their descriptors.  Nested
objects are entered into the children dictionary of their parent.  As
with readmodule, `module' names the module to be read and `path' is
prepended to sys.path.  If the module being read is a package, the
returned dictionary has a key @code{'__path__'} whose value is a list
containing the package search path.
@end deffn


Ajouté dans la version 3.7: Descriptors for nested definitions.  They are accessed through the
new children attribute.  Each has a new parent attribute.


The descriptors returned by these functions are instances of
Function and Class classes.  Users are not expected to create instances
of these classes.

@menu
* Objets fonctions:: 
* Objets classes: Objets classes<2>. 

@end menu

@node Objets fonctions,Objets classes<2>,,pyclbr --- Python module browser support
@anchor{library/pyclbr function-objects}@anchor{45e7}@anchor{library/pyclbr pyclbr-function-objects}@anchor{45e8}
@subsubsection Objets fonctions


@geindex Function (classe dans pyclbr)
@anchor{library/pyclbr pyclbr Function}@anchor{45e9}
@deffn {Classe} pyclbr.Function

Class @code{Function} instances describe functions defined by def
statements.  They have the following attributes:

@geindex file (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function file}@anchor{45ea}
@deffn {Attribut} file

Name of the file in which the function is defined.
@end deffn

@geindex module (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function module}@anchor{45eb}
@deffn {Attribut} module

The name of the module defining the function described.
@end deffn

@geindex name (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function name}@anchor{45ec}
@deffn {Attribut} name

The name of the function.
@end deffn

@geindex lineno (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function lineno}@anchor{45ed}
@deffn {Attribut} lineno

The line number in the file where the definition starts.
@end deffn

@geindex parent (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function parent}@anchor{45ee}
@deffn {Attribut} parent

For top-level functions, @code{None}.  For nested functions, the parent.


Ajouté dans la version 3.7.

@end deffn

@geindex children (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function children}@anchor{45ef}
@deffn {Attribut} children

A @ref{253,,dictionary} mapping names to descriptors for nested functions and
classes.


Ajouté dans la version 3.7.

@end deffn

@geindex is_async (attribut pyclbr.Function)
@anchor{library/pyclbr pyclbr Function is_async}@anchor{45f0}
@deffn {Attribut} is_async

@code{True} for functions that are defined with the
@ref{5bb,,async} prefix, @code{False} otherwise.


Ajouté dans la version 3.10.

@end deffn
@end deffn

@node Objets classes<2>,,Objets fonctions,pyclbr --- Python module browser support
@anchor{library/pyclbr class-objects}@anchor{45f1}@anchor{library/pyclbr pyclbr-class-objects}@anchor{45f2}
@subsubsection Objets classes


@geindex Class (classe dans pyclbr)
@anchor{library/pyclbr pyclbr Class}@anchor{45f3}
@deffn {Classe} pyclbr.Class

Class @code{Class} instances describe classes defined by class
statements.  They have the same attributes as @ref{45e9,,Functions}
and two more.

@geindex file (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class file}@anchor{45f4}
@deffn {Attribut} file

Name of the file in which the class is defined.
@end deffn

@geindex module (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class module}@anchor{45f5}
@deffn {Attribut} module

The name of the module defining the class described.
@end deffn

@geindex name (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class name}@anchor{45f6}
@deffn {Attribut} name

The name of the class.
@end deffn

@geindex lineno (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class lineno}@anchor{45f7}
@deffn {Attribut} lineno

The line number in the file where the definition starts.
@end deffn

@geindex parent (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class parent}@anchor{45f8}
@deffn {Attribut} parent

For top-level classes, @code{None}.  For nested classes, the parent.


Ajouté dans la version 3.7.

@end deffn

@geindex children (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class children}@anchor{45f9}
@deffn {Attribut} children

A dictionary mapping names to descriptors for nested functions and
classes.


Ajouté dans la version 3.7.

@end deffn

@geindex super (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class super}@anchor{45fa}
@deffn {Attribut} super

A list of @code{Class} objects which describe the immediate base
classes of the class being described.  Classes which are named as
superclasses but which are not discoverable by @ref{816,,readmodule_ex()}
are listed as a string with the class name instead of as
@code{Class} objects.
@end deffn

@geindex methods (attribut pyclbr.Class)
@anchor{library/pyclbr pyclbr Class methods}@anchor{45fb}
@deffn {Attribut} methods

A @ref{253,,dictionary} mapping method names to line numbers.
This can be derived from the newer @ref{45f9,,children} dictionary,
but remains for
back-compatibility.
@end deffn
@end deffn

@node py_compile --- Compile Python source files,compileall --- Byte-compile Python libraries,pyclbr --- Python module browser support,Services du Langage Python
@anchor{library/py_compile doc}@anchor{45fc}@anchor{library/py_compile module-py_compile}@anchor{b2}@anchor{library/py_compile py-compile-compile-python-source-files}@anchor{45fd}
@subsection @code{py_compile} --- Compile Python source files


@geindex module; py_compile

@c documentation based on module docstrings

`Code source :' Lib/py_compile.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/py_compile.py}

@geindex file;byte-code


__________________________________________________________________


Le module @ref{b2,,py_compile} définit une fonction principale qui génère un fichier de code intermédiaire à partir d'un fichier source. Il exporte également la fonction qu'il exécute quand il est lancé en tant que script.

Bien que ce module ne soit pas d'usage fréquent, il peut servir lors de l'installation de bibliothèques partagées, notamment dans le cas où tous les utilisateurs n'ont pas les privilèges d'écriture dans l'emplacement d'installation.

@geindex PyCompileError
@anchor{library/py_compile py_compile PyCompileError}@anchor{45fe}
@deffn {Exception} py_compile.PyCompileError

Exception levée quand une erreur se produit à la compilation.
@end deffn

@geindex compile() (dans le module py_compile)
@anchor{library/py_compile py_compile compile}@anchor{a13}
@deffn {Fonction} py_compile.compile (file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Compile a source file to byte-code and write out the byte-code cache file.
The source code is loaded from the file named `file'.  The byte-code is
written to `cfile', which defaults to the 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}/
@geindex Python Enhancement Proposals; PEP 488
PEP 488@footnote{https://peps.python.org/pep-0488/} path, ending
in @code{.pyc}.
For example, if `file' is @code{/foo/bar/baz.py} `cfile' will default to
@code{/foo/bar/__pycache__/baz.cpython-32.pyc} for Python 3.2.  If `dfile' is
specified, it is used instead of `file' as the name of the source file from
which source lines are obtained for display in exception tracebacks.
If `doraise' is true, a @ref{45fe,,PyCompileError} is raised
when an error is encountered while compiling `file'. If `doraise' is false
(the default), an error string is written to @code{sys.stderr}, but no exception
is raised.  This function returns the path to byte-compiled file, i.e.
whatever `cfile' value was used.

Plus précisément, ce sont les arguments `doraise' et `quiet' qui déterminent la stratégie de gestion des erreurs. En effet, si `quiet' vaut 0 ou 1, et `doraise' est faux, le comportement par défaut s'applique : un message d'erreur est affiché dans @code{sys.stderr}, et la fonction renvoie @code{None} au lieu d'un chemin. Au contraire, si `doraise' est vrai, une exception @ref{45fe,,PyCompileError} est levée, sauf si `quiet' vaut 2. Dans ce dernier cas, aucun message n'est émis, et `doraise' reste sans effet.

Si le chemin de destination, explicité par `cfile' ou choisi automatiquement, est un lien symbolique, ou n'est pas un véritable fichier, une exception de type @ref{1009,,FileExistsError} est levée. Ceci, dans le but de vous avertir que le système d'importation changera ces chemins en fichiers s'il est autorisé à y écrire des fichiers de code intermédiaire. En effet, les importations passent par un renommage final du fichier de code intermédiaire vers sa destination, afin d'éviter les problèmes liés à l'écriture simultanée d'un même fichier par plusieurs processus.

`optimize' règle le niveau d'optimisation. Ce paramètre est passé directement à la fonction native @ref{190,,compile()}. Avec la valeur par défaut de @code{-1}, le code intermédiaire hérite du niveau d'optimisation de l'interpréteur courant.

`invalidation_mode' précise la manière dont le code intermédiaire produit est invalidé à son exécution. Il doit être un membre de l'énumération @ref{45ff,,PycInvalidationMode}. La valeur par défaut est @ref{4600,,PycInvalidationMode.TIMESTAMP}. Elle passe toutefois à @ref{4601,,PycInvalidationMode.CHECKED_HASH} si la variable d'environnement 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} est définie.


Modifié dans la version 3.2: la méthode de choix de destination a changé au profit de celle décrite dans la 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/}. Auparavant, le nom du fichier de code intermédiaire était `file' + @code{'c'} (ou @code{'o'} lorsque les optimisations étaient actives). Le paramètre `optimize' a été ajouté.



Modifié dans la version 3.4: le code a été modifié pour faire appel à @ref{76,,importlib} dans les opérations d'écriture du code intermédiaire. Ce module se comporte donc exactement comme @ref{76,,importlib} en ce qui concerne, par exemple, les permissions, ou le renommage final qui garantit une opération atomique. @ref{1009,,FileExistsError} est désormais levée si la destination est un lien symbolique ou n'est pas un véritable fichier.



Modifié dans la version 3.7: le paramètre `invalidation_mode' a été ajouté comme requis par la 
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/}. Si la variable d'environnement 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} est définie, `invalidation_mode' est ignoré, et @ref{4601,,PycInvalidationMode.CHECKED_HASH} s'applique dans tous les cas.



Modifié dans la version 3.7.2: La variable d'environnement 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} n'a plus préséance sur le paramètre `invalidation_mode', mais détermine seulement le comportement par défaut lorsque ce paramètre n'est pas passé.



Modifié dans la version 3.8: ajout du paramètre `quiet'.

@end deffn

@geindex PycInvalidationMode (classe dans py_compile)
@anchor{library/py_compile py_compile PycInvalidationMode}@anchor{45ff}
@deffn {Classe} py_compile.PycInvalidationMode

An enumeration of possible methods the interpreter can use to determine
whether a bytecode file is up to date with a source file. The @code{.pyc} file
indicates the desired invalidation mode in its header. See
@ref{5d6,,Invalidation de bytecode mis en cache} for more information on how Python invalidates
@code{.pyc} files at runtime.


Ajouté dans la version 3.7.


@geindex TIMESTAMP (attribut py_compile.PycInvalidationMode)
@anchor{library/py_compile py_compile PycInvalidationMode TIMESTAMP}@anchor{4600}
@deffn {Attribut} TIMESTAMP

Le fichier @code{.pyc} contient l'horodatage et la taille de la source. L'interpréteur inspecte les métadonnées du fichier source au moment de l'exécution, et régénère le fichier @code{.pyc} si elles ont changé.
@end deffn

@geindex CHECKED_HASH (attribut py_compile.PycInvalidationMode)
@anchor{library/py_compile py_compile PycInvalidationMode CHECKED_HASH}@anchor{4601}
@deffn {Attribut} CHECKED_HASH

Le fichier @code{.pyc} porte une empreinte du code source. À l'exécution, elle est recalculée à partir de la source éventuellement modifiée, et le fichier @code{.pyc} est régénéré si les deux empreintes sont différentes.
@end deffn

@geindex UNCHECKED_HASH (attribut py_compile.PycInvalidationMode)
@anchor{library/py_compile py_compile PycInvalidationMode UNCHECKED_HASH}@anchor{4602}
@deffn {Attribut} UNCHECKED_HASH

Le principe est le même que @ref{4601,,CHECKED_HASH}, mais à l'exécution, l'interpréteur considère systématiquement que le fichier @code{.pyc} est à jour, sans regarder la source.

Cette option est utile lorsque les fichiers @code{.pyc} sont maintenus par un outil externe, comme un système d'intégration.
@end deffn
@end deffn

@menu
* Interface en ligne de commande: Interface en ligne de commande<11>. 

@end menu

@node Interface en ligne de commande<11>,,,py_compile --- Compile Python source files
@anchor{library/py_compile command-line-interface}@anchor{4603}@anchor{library/py_compile py-compile-cli}@anchor{4604}
@subsubsection Interface en ligne de commande


This module can be invoked as a script to compile several source
files.  The files named in `filenames' are compiled and the resulting
bytecode is cached in the normal manner.  This program does not search
a directory structure to locate source files; it only compiles files
named explicitly. The exit status is nonzero if one of the files could
not be compiled.

@geindex option de ligne de commande python--m-py_compile; <file>
@geindex option de ligne de commande python--m-py_compile; -
@anchor{library/py_compile cmdoption-python-m-py_compile-arg-file}@anchor{4605}
@deffn {Option} <file> ... <fileN>
@anchor{library/py_compile cmdoption-python-m-py_compile}@anchor{4606}
@deffnx {Option} @w{-}

Positional arguments are files to compile.  If @code{-} is the only
parameter, the list of files is taken from standard input.
@end deffn

@geindex option de ligne de commande python--m-py_compile; -q
@geindex option de ligne de commande python--m-py_compile; --quiet
@anchor{library/py_compile cmdoption-python-m-py_compile-q}@anchor{4607}@anchor{library/py_compile cmdoption-python-m-py_compile-quiet}@anchor{4608}
@deffn {Option} @w{-}q, @w{-}@w{-}quiet

Suppress errors output.
@end deffn


Modifié dans la version 3.2: Added support for @code{-}.



Modifié dans la version 3.10: Added support for @ref{4607,,-q}.



@subsubheading Voir aussi



@table @asis

@item Module @ref{20,,compileall}

Utilitaires pour compiler des fichiers source Python dans une arborescence
@end table


@node compileall --- Byte-compile Python libraries,dis --- Disassembler for Python bytecode,py_compile --- Compile Python source files,Services du Langage Python
@anchor{library/compileall doc}@anchor{4609}@anchor{library/compileall compileall-byte-compile-python-libraries}@anchor{460a}@anchor{library/compileall module-compileall}@anchor{20}
@subsection @code{compileall} --- Byte-compile Python libraries


@geindex module; compileall

`Code source :' Lib/compileall.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/compileall.py}


__________________________________________________________________


Ce module contient des fonctions qui facilitent l'installation de bibliothèques Python. Elles compilent, sous forme de code intermédiaire (`bytecode'), les fichiers source situés dans un dossier de votre choix. Ce module est particulièrement utile pour générer les fichiers de code intermédiaire lors de l'installation d'une bibliothèque, les rendant disponibles même pour les utilisateurs qui n'ont pas les privilèges d'écriture dans l'emplacement d'installation.

@c include for modules that don't work on WASM

@ref{1ce0,,Availability}: not WASI.

This module does not work or is not available on WebAssembly. See
@ref{176f,,Plateformes WebAssembly} for more information.

@menu
* Utilisation en ligne de commande: Utilisation en ligne de commande<7>. 
* Fonctions publiques:: 

@end menu

@node Utilisation en ligne de commande<7>,Fonctions publiques,,compileall --- Byte-compile Python libraries
@anchor{library/compileall command-line-use}@anchor{460b}@anchor{library/compileall compileall-cli}@anchor{460c}
@subsubsection Utilisation en ligne de commande


On peut se servir de ce module comme d'un script (avec @code{python -m compileall}) pour compiler les fichiers source Python.

@geindex option de ligne de commande compileall; directory
@geindex option de ligne de commande compileall; file
@anchor{library/compileall cmdoption-compileall-arg-directory}@anchor{460d}
@deffn {Option} directory ...
@anchor{library/compileall cmdoption-compileall-arg-file}@anchor{460e}
@deffnx {Option} file ...

Positional arguments are files to compile or directories that contain
source files, traversed recursively.  If no argument is given, behave as if
the command line was @code{-l @var{<directories from sys.path>}}.
@end deffn

@geindex option de ligne de commande compileall; -l
@anchor{library/compileall cmdoption-compileall-l}@anchor{460f}
@deffn {Option} @w{-}l

Compiler uniquement les fichiers situés directement dans les dossiers passés en argument ou implicites, sans descendre récursivement dans les sous-dossiers.
@end deffn

@geindex option de ligne de commande compileall; -f
@anchor{library/compileall cmdoption-compileall-f}@anchor{4610}
@deffn {Option} @w{-}f

Forcer la recompilation même si les horodatages sont à jour.
@end deffn

@geindex option de ligne de commande compileall; -q
@anchor{library/compileall cmdoption-compileall-q}@anchor{4611}
@deffn {Option} @w{-}q

Supprimer l'affichage des noms des fichiers compilés.Si cette option est donnée une seule fois, les erreurs sont affichées malgré tout. Vous pouvez les supprimer en passant l'option deux fois (c'est-à-dire avec @code{-qq}).
@end deffn

@geindex option de ligne de commande compileall; -d
@anchor{library/compileall cmdoption-compileall-d}@anchor{4612}
@deffn {Option} @w{-}d destdir

Ce nom de dossier est ajouté en tête du chemin de chaque fichier compilé. Il aura une influence sur les traces d'appels pour les erreurs levées lors de la compilation, et sera reflété dans les fichiers de code intermédiaire, pour utilisation dans les traces d'appels et autres messages si le fichier source n'existe pas au moment de l'exécution.
@end deffn

@geindex option de ligne de commande compileall; -s
@anchor{library/compileall cmdoption-compileall-s}@anchor{4613}
@deffn {Option} @w{-}s strip_prefix
@end deffn

@geindex option de ligne de commande compileall; -p
@anchor{library/compileall cmdoption-compileall-p}@anchor{4614}
@deffn {Option} @w{-}p prepend_prefix

Retire (@code{-s}) ou ajoute (@code{-p}) le préfixe aux chemins stockés dans les fichiers @code{.pyc}. Cette option ne peut pas être combinée avec @code{-d}.
@end deffn

@geindex option de ligne de commande compileall; -x
@anchor{library/compileall cmdoption-compileall-x}@anchor{4615}
@deffn {Option} @w{-}x regex

Exclut tous les fichiers dont les noms correspondent à l'expression régulière `regex'.
@end deffn

@geindex option de ligne de commande compileall; -i
@anchor{library/compileall cmdoption-compileall-i}@anchor{4616}
@deffn {Option} @w{-}i list

Ajoute chaque ligne du fichier `list' aux fichiers et dossiers à compiler. `list' peut être @code{-}, auquel cas le script lit l'entrée standard.
@end deffn

@geindex option de ligne de commande compileall; -b
@anchor{library/compileall cmdoption-compileall-b}@anchor{4617}
@deffn {Option} @w{-}b

Utilise l'ancienne manière de nommer et placer les fichiers de code intermédiaire, en écrasant éventuellement ceux générés par une autre version de Python. Par défaut, les règles décrites dans la 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} s'appliquent. Elles permettent à différentes versions de l'interpréteur Python de coexister en conservant chacune ses propres fichiers @code{.pyc}.
@end deffn

@geindex option de ligne de commande compileall; -r
@anchor{library/compileall cmdoption-compileall-r}@anchor{4618}
@deffn {Option} @w{-}r

Règle le niveau de récursion maximal pour le parcours des sous-dossiers. Lorsque cette option est fournie, @code{-l} est ignorée. @code{python -m compileall <dossier> -r 0} revient au même que @code{python -m compileall <dossier> -l}.
@end deffn

@geindex option de ligne de commande compileall; -j
@anchor{library/compileall cmdoption-compileall-j}@anchor{4619}
@deffn {Option} @w{-}j N

Use `N' workers to compile the files within the given directory.
If @code{0} is used, then the result of @ref{1bf,,os.process_cpu_count()}
will be used.
@end deffn

@geindex option de ligne de commande compileall; --invalidation-mode
@anchor{library/compileall cmdoption-compileall-invalidation-mode}@anchor{461a}
@deffn {Option} @w{-}@w{-}invalidation@w{-}mode [timestamp|checked@w{-}hash|unchecked@w{-}hash]

Définit la manière dont les fichiers de code intermédiaire seront invalidés au moment de l'exécution. Avec @code{timestamp}, les fichiers @code{.pyc} générés comportent l'horodatage de la source et sa taille. Avec @code{checked-hash} ou @code{unchecked-hash}, ce seront des pyc utilisant le hachage, qui contiennent une empreinte du code source plutôt qu'un horodatage. Voir @ref{5d6,,Invalidation de bytecode mis en cache} pour plus d'informations sur la manière dont Python valide les fichiers de code intermédiaire conservés en cache lors de l'exécution. La valeur par défaut est @code{timestamp}. Cependant, si la variable d'environnement 
@geindex SOURCE_DATE_EPOCH
@geindex variable d'environnement; SOURCE_DATE_EPOCH
@code{SOURCE_DATE_EPOCH} a été réglée, elle devient @code{checked-hash}.
@end deffn

@geindex option de ligne de commande compileall; -o
@anchor{library/compileall cmdoption-compileall-o}@anchor{461b}
@deffn {Option} @w{-}o level

Compile avec un certain niveau d'optimisation. Cette option peut être passée plusieurs fois afin de compiler pour plusieurs niveaux d'un seul coup (par exemple, @code{compileall -o 1 -o 2}).
@end deffn

@geindex option de ligne de commande compileall; -e
@anchor{library/compileall cmdoption-compileall-e}@anchor{461c}
@deffn {Option} @w{-}e dir

Ignore les liens symboliques qui redirigent en dehors du dossier.
@end deffn

@geindex option de ligne de commande compileall; --hardlink-dupes
@anchor{library/compileall cmdoption-compileall-hardlink-dupes}@anchor{461d}
@deffn {Option} @w{-}@w{-}hardlink@w{-}dupes

Si deux fichiers @code{.pyc} compilés avec des niveaux d'optimisation différents ont finalement le même contenu, emploie des liens physiques pour les fusionner.
@end deffn


Modifié dans la version 3.2: ajout des options @code{-i}, @code{-b} et @code{-h}.



Modifié dans la version 3.5: ajout des options @code{-j}, @code{-r} et @code{-qq} (l'option @code{-q} peut donc prendre plusieurs niveaux). @code{-b} produit toujours un fichier de code intermédiaire portant l'extension @code{.pyc}, et jamais @code{.pyo}.



Modifié dans la version 3.7: ajout de l'option @code{--invalidation-mode}.



Modifié dans la version 3.9: ajout des options @code{-s}, @code{-p}, @code{-e} et @code{--hardlink-dupes}. Rehaussement de la limite de récursion par défaut à @ref{4ad,,sys.getrecursionlimit()} au lieu de 10 précédemment. L'option @code{-o} peut être passée plusieurs fois.


Il n'y a pas d'option en ligne de commande pour contrôler le niveau d'optimisation utilisé par la fonction @ref{190,,compile()}. Il suffit en effet d'utiliser l'option @code{-O} de l'interpréteur Python lui-même : @code{python -O -m compileall}.

Similarly, the @ref{190,,compile()} function respects the @ref{992,,sys.pycache_prefix}
setting. The generated bytecode cache will only be useful if @ref{190,,compile()} is
run with the same @ref{992,,sys.pycache_prefix} (if any) that will be used at
runtime.

@node Fonctions publiques,,Utilisation en ligne de commande<7>,compileall --- Byte-compile Python libraries
@anchor{library/compileall public-functions}@anchor{461e}
@subsubsection Fonctions publiques


@geindex compile_dir() (dans le module compileall)
@anchor{library/compileall compileall compile_dir}@anchor{b14}
@deffn {Fonction} compileall.compile_dir (dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Parcourt récursivement le dossier `dir', en compilant tous les fichiers @code{.py}. Renvoie une valeur vraie si tous les fichiers ont été compilés sans erreur, et une valeur fausse dans le cas contraire.

Le paramètre `maxlevels' permet de limiter la profondeur de récursion. Sa valeur par défaut est celle de @code{sys.getrecursionlimit()}.

Si `ddir' est fourni, il est ajouté en tête du chemin de chaque fichier compilé, ce qui modifie l'affichage des traces d'appels pour les erreurs qui seraient levées lors de la compilation. De plus, il se retrouve dans les fichiers de code intermédiaire, pour utilisation dans les traces et autres messages si le fichier source n'existe pas au moment de l'exécution.

Si `force' est vrai, les modules sont recompilés même si leurs horodatages sont à jour.

Si `rx' est donné, sa méthode @code{search} est appelée sur le chemin complet de chaque fichier source, et si elle renvoie une valeur vraie, le fichier est sauté. `rx' sera habituellement une expression régulière (objet @ref{f71,,re.Pattern}).

Si `quiet' est @code{False} ou bien @code{0} (la valeur par défaut), les noms de fichiers et d'autres informations sont affichés sur la sortie standard. Avec @code{1}, seules les erreurs sont affichées. Avec @code{2}, aucune sortie n'est émise.

Si `legacy' est vrai, les fichiers de code intermédiaire sont nommés et placés selon l'ancienne méthode, en écrasant éventuellement ceux générés par une autre version de Python. Par défaut, les règles décrites dans la 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} s'appliquent. Elles permettent à différentes versions de l'interpréteur Python de coexister en conservant chacune ses propres fichiers @code{.pyc}.

`optimize' définit le niveau d'optimisation qu'applique le compilateur. Cet argument est passé directement à la fonction native @ref{190,,compile()}. Il peut également être fourni sous la forme d'une séquence de niveaux d'optimisation, ce qui permet de compiler chaque fichier @code{.py} plusieurs fois en appliquant divers niveaux d'optimisation.

`workers' est le nombre de tâches lancées en parallèle pour la compilation. Par défaut, les fichiers sont compilés séquentiellement. Cette même stratégie s'applique dans tous les cas lorsque le parallélisme n'est pas possible sur la plateforme d'exécution. Si `workers' vaut 0, autant de tâches sont lancées que le système comporte de cœurs. Si `workers' est strictement négatif, une exception de type @ref{1ff,,ValueError} est levée.

`invalidation_mode' doit être un membre de l'énumération @ref{45ff,,py_compile.PycInvalidationMode} et détermine la manière dont les fichiers @code{.pyc} sont invalidés lorsque l'interpréteur tente de les utiliser.

The `stripdir', `prependdir' and `limit_sl_dest' arguments correspond to
the @code{-s}, @code{-p} and @code{-e} options described above.
They may be specified as @code{str} or @ref{c3f,,os.PathLike}.

Un argument `hardlink_dupes' vrai correspond à l'utilisation de l'option @code{--hardlink-dupes}.


Modifié dans la version 3.2: ajout des paramètres `legacy' et `optimize'.



Modifié dans la version 3.5: ajout du paramètre `workers'.



Modifié dans la version 3.5: le paramètre `quiet' peut prendre plusieurs niveaux.



Modifié dans la version 3.5: Lorsque le paramètre `legacy' est vrai, des fichiers @code{.pyc}, et jamais @code{.pyo}, sont générés, quel que soit le niveau d'optimisation.



Modifié dans la version 3.6: accepte un @ref{29d,,objet simili-chemin}.



Modifié dans la version 3.7: ajout du paramètre `invalidation_mode'.



Modifié dans la version 3.7.2: The `invalidation_mode' parameter's default value is updated to @code{None}.



Modifié dans la version 3.8: Un nombre de processus adapté à la machine est choisi lorsque `workers' vaut 0.



Modifié dans la version 3.9: ajout des arguments `stripdir', `prependdir', `limit_sl_dest' et `hardlink_dupes'. La valeur par défaut de `maxlevels' a été changée pour @code{sys.getrecursionlimit()} (elle était de 10 auparavant).

@end deffn

@geindex compile_file() (dans le module compileall)
@anchor{library/compileall compileall compile_file}@anchor{dce}
@deffn {Fonction} compileall.compile_file (fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Compile le fichier dont le chemin est donné par `fullname'. Renvoie une valeur vraie si et seulement si le fichier est compilé sans erreur.

Si `ddir' est fourni, il est ajouté en tête du chemin de chaque fichier compilé, ce qui modifie l'affichage des traces pour les erreurs qui seraient levées lors de la compilation. De plus, il se retrouve dans les fichiers de code intermédiaire, pour utilisation dans les traces et autres messages si le fichier source n'existe pas au moment de l'exécution.

Si `rx' est donné, sa méthode @code{search} est appelée sur le chemin complet de chaque fichier source, et si elle renvoie une valeur vraie, le fichier est sauté. `rx' sera habituellement une expression régulière (objet @ref{f71,,re.Pattern}).

Si `quiet' est @code{False} ou bien @code{0} (la valeur par défaut), les noms de fichiers et d'autres informations sont affichés sur la sortie standard. Avec @code{1}, seules les erreurs sont affichées. Avec @code{2}, aucune sortie n'est émise.

Si `legacy' est vrai, les fichiers de code intermédiaire sont nommés et placés selon l'ancienne méthode, en écrasant éventuellement ceux générés par une autre version de Python. Par défaut, les règles décrites dans la 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} s'appliquent. Elles permettent à différentes versions de l'interpréteur Python de coexister en conservant chacune ses propres fichiers @code{.pyc}.

`optimize' définit le niveau d'optimisation qu'applique le compilateur. Cet argument est passé directement à la fonction native @ref{190,,compile()}. Il peut également être fourni sous la forme d'une séquence de niveaux d'optimisation, ce qui permet de compiler chaque fichier @code{.py} plusieurs fois en appliquant divers niveaux d'optimisation.

`invalidation_mode' doit être un membre de l'énumération @ref{45ff,,py_compile.PycInvalidationMode} et détermine la manière dont les fichiers @code{.pyc} sont invalidés lorsque l'interpréteur tente de les utiliser.

The `stripdir', `prependdir' and `limit_sl_dest' arguments correspond to
the @code{-s}, @code{-p} and @code{-e} options described above.
They may be specified as @code{str} or @ref{c3f,,os.PathLike}.

Un argument `hardlink_dupes' vrai correspond à l'utilisation de l'option @code{--hardlink-dupes}.


Ajouté dans la version 3.2.



Modifié dans la version 3.5: le paramètre `quiet' peut prendre plusieurs niveaux.



Modifié dans la version 3.5: Lorsque le paramètre `legacy' est vrai, des fichiers @code{.pyc}, et jamais @code{.pyo}, sont générés, quel que soit le niveau d'optimisation.



Modifié dans la version 3.7: ajout du paramètre `invalidation_mode'.



Modifié dans la version 3.7.2: The `invalidation_mode' parameter's default value is updated to @code{None}.



Modifié dans la version 3.9: Ajout des arguments `stripdir', `prependdir', `limit_sl_dest' et `hardlink_dupes'.

@end deffn

@geindex compile_path() (dans le module compileall)
@anchor{library/compileall compileall compile_path}@anchor{dcf}
@deffn {Fonction} compileall.compile_path (skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Compile tous les fichiers @code{.py} contenus dans les dossiers de @code{sys.path}. Renvoie une valeur vraie s'ils ont tous été compilés sans erreur, et une valeur fausse dans le cas contraire.

Si `skip_curdir' est vrai (c'est le cas par défaut), le dossier courant est exclu de la recherche. Les autres paramètres sont passés à @ref{b14,,compile_dir()}. Notez que contrairement aux autres fonctions de ce module, la valeur par défaut de @code{maxlevels} est @code{0}.


Modifié dans la version 3.2: ajout des paramètres `legacy' et `optimize'.



Modifié dans la version 3.5: le paramètre `quiet' peut prendre plusieurs niveaux.



Modifié dans la version 3.5: Lorsque le paramètre `legacy' est vrai, des fichiers @code{.pyc}, et jamais @code{.pyo}, sont générés, quel que soit le niveau d'optimisation.



Modifié dans la version 3.7: ajout du paramètre `invalidation_mode'.



Modifié dans la version 3.7.2: The `invalidation_mode' parameter's default value is updated to @code{None}.

@end deffn

Pour forcer la recompilation de tous les fichiers @code{.py} dans le dossier @code{Lib/} et tous ses sous-dossiers :

@example
import compileall

compileall.compile_dir('Lib/', force=True)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)
@end example


@subsubheading Voir aussi



@table @asis

@item Module @ref{b2,,py_compile}

Compiler un fichier source unique.
@end table


@node dis --- Disassembler for Python bytecode,pickletools --- Tools for pickle developers,compileall --- Byte-compile Python libraries,Services du Langage Python
@anchor{library/dis doc}@anchor{461f}@anchor{library/dis dis-disassembler-for-python-bytecode}@anchor{4620}@anchor{library/dis module-dis}@anchor{38}
@subsection @code{dis} --- Disassembler for Python bytecode


@geindex module; dis

`Code source :' Lib/dis.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/dis.py}

@c import dis
@c def myfunc(alist):
@c     return len(alist)


__________________________________________________________________


La bibliothèque  @ref{38,,dis} supporte l'analyse du @ref{185,,bytecode} CPython en le désassemblant. Le code intermédiaire CPython, que cette bibliothèque  prend en paramètre, est défini dans le fichier @code{Include/opcode.h} et est utilisé par le compilateur et l'interpréteur.

`Particularité de l'implémentation CPython :' Le code intermédiaire est un détail d'implémentation de l'interpréteur CPython. Il n'y a pas de garantie que le code intermédiaire sera ajouté, retiré, ou modifié dans les différentes versions de Python. L'utilisation de cette bibliothèque  ne fonctionne pas nécessairement sur les machines virtuelles Python ni les différentes versions de Python.


Modifié dans la version 3.6: Utilisez 2 bits pour chaque instruction. Avant, le nombre de bits variait par instruction.



Modifié dans la version 3.10: The argument of jump, exception handling and loop instructions is now
the instruction offset rather than the byte offset.



Modifié dans la version 3.11: Some instructions are accompanied by one or more inline cache entries,
which take the form of @ref{6e3,,CACHE} instructions. These instructions
are hidden by default, but can be shown by passing @code{show_caches=True} to
any @ref{38,,dis} utility. Furthermore, the interpreter now adapts the
bytecode to specialize it for different runtime conditions. The
adaptive bytecode can be shown by passing @code{adaptive=True}.



Modifié dans la version 3.12: The argument of a jump is the offset of the target instruction relative
to the instruction that appears immediately after the jump instruction's
@ref{6e3,,CACHE} entries.

As a consequence, the presence of the @ref{6e3,,CACHE} instructions is
transparent for forward jumps but needs to be taken into account when
reasoning about backward jumps.



Modifié dans la version 3.13: The output shows logical labels rather than instruction offsets
for jump targets and exception handlers. The @code{-O} command line
option and the @code{show_offsets} argument were added.


Example: Given the function @code{myfunc()}:

@example
def myfunc(alist):
    return len(alist)
@end example

the following command can be used to display the disassembly of
@code{myfunc()}:

@example
>>> dis.dis(myfunc)
  2           RESUME                   0

  3           LOAD_GLOBAL              1 (len + NULL)
              LOAD_FAST                0 (alist)
              CALL                     1
              RETURN_VALUE
@end example

(Le "2" est un numéro de ligne).

@menu
* Command-line interface: Command-line interface<2>. 
* Analyse du code intermédiaire:: 
* Analyse de fonctions:: 
* Les instructions du code intermédiaire en Python:: 
* Opcode collections:: 

@end menu

@node Command-line interface<2>,Analyse du code intermédiaire,,dis --- Disassembler for Python bytecode
@anchor{library/dis command-line-interface}@anchor{4621}@anchor{library/dis dis-cli}@anchor{4622}
@subsubsection Command-line interface


The @ref{38,,dis} module can be invoked as a script from the command line:

@example
python -m dis [-h] [-C] [-O] [infile]
@end example

Les options suivantes sont acceptées :

@geindex option de ligne de commande dis; -h
@geindex option de ligne de commande dis; --help
@anchor{library/dis cmdoption-dis-h}@anchor{4623}@anchor{library/dis cmdoption-dis-help}@anchor{4624}
@deffn {Option Du Programme} @w{-}h, @w{-}@w{-}help

Display usage and exit.
@end deffn

@geindex option de ligne de commande dis; -C
@geindex option de ligne de commande dis; --show-caches
@anchor{library/dis cmdoption-dis-C}@anchor{4625}@anchor{library/dis cmdoption-dis-show-caches}@anchor{4626}
@deffn {Option Du Programme} @w{-}C, @w{-}@w{-}show@w{-}caches

Show inline caches.
@end deffn

@geindex option de ligne de commande dis; -O
@geindex option de ligne de commande dis; --show-offsets
@anchor{library/dis cmdoption-dis-O}@anchor{1d5}@anchor{library/dis cmdoption-dis-show-offsets}@anchor{4627}
@deffn {Option Du Programme} @w{-}O, @w{-}@w{-}show@w{-}offsets

Show offsets of instructions.
@end deffn

If @code{infile} is specified, its disassembled code will be written to stdout.
Otherwise, disassembly is performed on compiled source code received from stdin.

@node Analyse du code intermédiaire,Analyse de fonctions,Command-line interface<2>,dis --- Disassembler for Python bytecode
@anchor{library/dis bytecode-analysis}@anchor{4628}
@subsubsection Analyse du code intermédiaire



Ajouté dans la version 3.4.


L'analyse de l'`API' code intermédiaire permet de rassembler des blocs de code en Python dans une classe @ref{f19,,Bytecode}, qui permet un accès facile aux détails du code compilé.

@geindex Bytecode (classe dans dis)
@anchor{library/dis dis Bytecode}@anchor{f19}
@deffn {Classe} dis.Bytecode (x, *, first_line=None, current_offset=None, show_caches=False, adaptive=False, show_offsets=False)

Analyse le code intermédiaire correspondant à une fonction, un générateur, un générateur asynchrone, une coroutine, une méthode, une chaîne de caractères du code source, ou bien une classe (comme retourne la fonction @ref{190,,compile()}).

Ceci est `wrapper' sur plusieurs fonctions de la liste ci-dessous, notamment @ref{1d6,,get_instructions()}, étant donné qu'une itération sur une instance de la classe @ref{f19,,Bytecode} rend les opérations du code intermédiaire des instances de @ref{1d7,,Instruction}.

Si `first_line' ne vaut pas @code{None}, elle indique le nombre de la ligne qui doit être considérée comme première ligne source dans le code désassemblé. Autrement, les informations sur la ligne source sont prises directement à partir de la classe du code désassemblé.

Si la valeur de `current_offset' est différente de @code{None}, c'est une référence à un offset d'une instruction dans le code désassemblé. Cela veut dire que @ref{f1a,,dis()} va générer un marqueur  de " l'instruction en cours" contre le code d'opération donné.

If `show_caches' is @code{True}, @ref{f1a,,dis()} will display inline cache
entries used by the interpreter to specialize the bytecode.

If `adaptive' is @code{True}, @ref{f1a,,dis()} will display specialized bytecode
that may be different from the original bytecode.

If `show_offsets' is @code{True}, @ref{f1a,,dis()} will include instruction
offsets in the output.

@geindex from_traceback() (méthode de la classe dis.Bytecode)
@anchor{library/dis dis Bytecode from_traceback}@anchor{f1b}
@deffn {Méthode} classmethod from_traceback (tb, *, show_caches=False)

Construisez une instance @ref{f19,,Bytecode} à partir de la trace d'appel, en mettant `current_offet' à l'instruction responsable de l'exception.
@end deffn

@geindex Bytecode.codeobj (dans le module dis)
@anchor{library/dis dis Bytecode codeobj}@anchor{4629}
@deffn {Données} codeobj

Le code compilé objet.
@end deffn

@geindex Bytecode.first_line (dans le module dis)
@anchor{library/dis dis Bytecode first_line}@anchor{462a}
@deffn {Données} first_line

La première ligne source du code objet (si disponible)
@end deffn

@geindex dis() (méthode dis.Bytecode)
@anchor{library/dis dis Bytecode dis}@anchor{f1a}
@deffn {Méthode} dis ()

Retourne une vue formatée des opérations du code intermédiaire (la même que celle envoyée par @ref{b22,,dis.dis()}, mais comme une chaîne de caractères de plusieurs lignes ).
@end deffn

@geindex info() (méthode dis.Bytecode)
@anchor{library/dis dis Bytecode info}@anchor{462b}
@deffn {Méthode} info ()

Retourne une chaîne de caractères de plusieurs lignes formatée avec des informations détaillées sur l'objet code comme @ref{1217,,code_info()}.
@end deffn


Modifié dans la version 3.7: Cette version supporte la coroutine et les objets générateurs asynchrones.



Modifié dans la version 3.11: Added the `show_caches' and `adaptive' parameters.

@end deffn

Example:

@example
>>> bytecode = dis.Bytecode(myfunc)
>>> for instr in bytecode:
...     print(instr.opname)
...
RESUME
LOAD_GLOBAL
LOAD_FAST
CALL
RETURN_VALUE
@end example

@node Analyse de fonctions,Les instructions du code intermédiaire en Python,Analyse du code intermédiaire,dis --- Disassembler for Python bytecode
@anchor{library/dis analysis-functions}@anchor{462c}
@subsubsection Analyse de fonctions


La bibliothèque  @ref{38,,dis} comprend également l'analyse des fonctions suivantes, qui envoient l'entrée directement à la sortie souhaitée. Elles peuvent être utiles si il n'y a qu'une seule opération à effectuer, la représentation intermédiaire objet n'étant donc pas utile dans ce cas :

@geindex code_info() (dans le module dis)
@anchor{library/dis dis code_info}@anchor{1217}
@deffn {Fonction} dis.code_info (x)

Retourne une chaîne de caractères de plusieurs lignes  formatée avec des informations détaillées sur l'objet code pour les fonctions données, les générateurs asynchrone, coroutine, la méthode, la chaine de caractères du code source ou objet.

Il est à noter que le contenu exact des chaînes de caractères figurant dans  les informations du code dépendent fortement sur l'implémentation, et peuvent changer arbitrairement sous machines virtuelles Python ou les versions de Python.


Ajouté dans la version 3.2.



Modifié dans la version 3.7: Cette version supporte la coroutine et les objets générateurs asynchrones.

@end deffn

@geindex show_code() (dans le module dis)
@anchor{library/dis dis show_code}@anchor{f17}
@deffn {Fonction} dis.show_code (x, *, file=None)

Affiche des informations détaillées sur le code de la fonction fournie, la méthode, la chaîne de caractère du code source ou du code objet à `file' (ou bien @code{sys.stdout} si `file' n'est pas spécifié).

Ceci est un raccourci convenable de @code{print(code_info(x), file=file)}, principalement fait pour l'exploration interactive sur l'invite de l'interpréteur.


Ajouté dans la version 3.2.



Modifié dans la version 3.4: Ajout du paramètre `file'.

@end deffn

@geindex dis() (dans le module dis)
@anchor{library/dis dis dis}@anchor{b22}
@deffn {Fonction} dis.dis (x=None, *, file=None, depth=None, show_caches=False, adaptive=False)

Disassemble the `x' object.  `x' can denote either a module, a class, a
method, a function, a generator, an asynchronous generator, a coroutine,
a code object, a string of source code or a byte sequence of raw bytecode.
For a module, it disassembles all functions. For a class, it disassembles
all methods (including class and static methods). For a code object or
sequence of raw bytecode, it prints one line per bytecode instruction.
It also recursively disassembles nested code objects. These can include
generator expressions, nested functions, the bodies of nested classes,
and the code objects used for @ref{186,,annotation scopes}.
Strings are first compiled to code objects with the @ref{190,,compile()}
built-in function before being disassembled.  If no object is provided, this
function disassembles the last traceback.

Le désassemblage est envoyé sous forme de texte à l'argument du fichier `file' si il est fourni, et à @code{sys.stdout} sinon.

La profondeur maximale de récursion est limitée par `depth' sauf si elle correspond à @code{None}. @code{depth=0} indique qu'il n'y a pas de récursion.

If `show_caches' is @code{True}, this function will display inline cache
entries used by the interpreter to specialize the bytecode.

If `adaptive' is @code{True}, this function will display specialized bytecode
that may be different from the original bytecode.


Modifié dans la version 3.4: Ajout du paramètre `file'.



Modifié dans la version 3.7: Le désassemblage récursif a été implémenté, et le paramètre `depth' a été ajouté.



Modifié dans la version 3.7: Cette version supporte la coroutine et les objets générateurs asynchrones.



Modifié dans la version 3.11: Added the `show_caches' and `adaptive' parameters.

@end deffn


@deffn {Fonction} distb(tb=None, *, file=None, show_caches=False, adaptive=False,

@deffnx {Fonction} show_offset=False)

Désassemble la fonction du haut de la pile des traces d'appels, en utilisant la dernière trace d'appels si rien n'a été envoyé. L'instruction à l'origine de l'exception est indiquée.

Le désassemblage est envoyé sous forme de texte à l'argument du fichier `file' si il est fourni, et à @code{sys.stdout} sinon.


Modifié dans la version 3.4: Ajout du paramètre `file'.



Modifié dans la version 3.11: Added the `show_caches' and `adaptive' parameters.



Modifié dans la version 3.13: Added the `show_offsets' parameter.

@end deffn

@geindex disassemble() (dans le module dis)
@anchor{library/dis dis disassemble}@anchor{f18}
@deffn {Fonction} dis.disassemble (code, lasti=-1, *, file=None, show_caches=False, adaptive=False)

@deffnx {Fonction} disco(code, lasti=@w{-}1, *, file=None, show_caches=False, adaptive=False,

@deffnx {Fonction} show_offsets=False)

Désassemble un code objet, en indiquant la dernière instruction si `lasti' est fournie. La sortie est répartie sur les colonnes suivantes :


@enumerate 

@item 
le numéro de ligne, pour la première instruction de chaque ligne

@item 
l'instruction en cours, indiquée par @code{-->},

@item 
une instruction libellée, indiquée par @code{> >},

@item 
l'adresse de l'instruction,

@item 
le nom de le code d'opération,

@item 
paramètres de l'opération, et

@item 
interprétation des paramètres entre parenthèses.
@end enumerate

L'interprétation du paramètre reconnaît les noms des variables locales et globales, des valeurs constantes, des branchements cibles, et des opérateurs de comparaison.

Le désassemblage est envoyé sous forme de texte à l'argument du fichier `file' si il est fourni, et à @code{sys.stdout} sinon.


Modifié dans la version 3.4: Ajout du paramètre `file'.



Modifié dans la version 3.11: Added the `show_caches' and `adaptive' parameters.



Modifié dans la version 3.13: Added the `show_offsets' parameter.

@end deffn

@geindex get_instructions() (dans le module dis)
@anchor{library/dis dis get_instructions}@anchor{1d6}
@deffn {Fonction} dis.get_instructions (x, *, first_line=None, show_caches=False, adaptive=False)

Retourne un itérateur sur les instructions dans la fonction fournie, la méthode, les chaînes de caractères du code source ou objet.

Cet itérateur génère une série de `n'-uplets de @ref{1d7,,Instruction} qui donnent les détails de chacune des opérations dans le code fourni.

Si `first_line' ne vaut pas @code{None}, elle indique le nombre de la ligne qui doit être considérée comme première ligne source dans le code désassemblé. Autrement, les informations sur la ligne source sont prises directement à partir de la classe du code désassemblé.

The `adaptive' parameter works as it does in @ref{38,,dis()}.


Ajouté dans la version 3.4.



Modifié dans la version 3.11: Added the `show_caches' and `adaptive' parameters.



Modifié dans la version 3.13: The `show_caches' parameter is deprecated and has no effect. The iterator
generates the @ref{1d7,,Instruction} instances with the `cache_info'
field populated (regardless of the value of `show_caches') and it no longer
generates separate items for the cache entries.

@end deffn

@geindex findlinestarts() (dans le module dis)
@anchor{library/dis dis findlinestarts}@anchor{462d}
@deffn {Fonction} dis.findlinestarts (code)

This generator function uses the @ref{2ef,,co_lines()} method
of the @ref{1cd,,code object} `code' to find the offsets which
are starts of
lines in the source code.  They are generated as @code{(offset, lineno)} pairs.


Modifié dans la version 3.6: Les numéros de lignes peuvent être décroissants. Avant, ils étaient toujours croissants.



Modifié dans la version 3.10: The 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/} @ref{2ef,,co_lines()} method is used instead of the
@ref{1ec8,,co_firstlineno} and @ref{2de,,co_lnotab}
attributes of the @ref{1cd,,code object}.



Modifié dans la version 3.13: Line numbers can be @code{None} for bytecode that does not map to source lines.

@end deffn

@geindex findlabels() (dans le module dis)
@anchor{library/dis dis findlabels}@anchor{462e}
@deffn {Fonction} dis.findlabels (code)

Detect all offsets in the raw compiled bytecode string `code' which are jump targets, and
return a list of these offsets.
@end deffn

@geindex stack_effect() (dans le module dis)
@anchor{library/dis dis stack_effect}@anchor{f1c}
@deffn {Fonction} dis.stack_effect (opcode, oparg=None, *, jump=None)

Compute the stack effect of `opcode' with argument `oparg'.

If the code has a jump target and `jump' is @code{True}, @ref{f1c,,stack_effect()}
will return the stack effect of jumping.  If `jump' is @code{False},
it will return the stack effect of not jumping. And if `jump' is
@code{None} (default), it will return the maximal stack effect of both cases.


Ajouté dans la version 3.4.



Modifié dans la version 3.8: Added `jump' parameter.



Modifié dans la version 3.13: If @code{oparg} is omitted (or @code{None}), the stack effect is now returned
for @code{oparg=0}. Previously this was an error for opcodes that use their
arg. It is also no longer an error to pass an integer @code{oparg} when
the @code{opcode} does not use it; the @code{oparg} in this case is ignored.

@end deffn

@node Les instructions du code intermédiaire en Python,Opcode collections,Analyse de fonctions,dis --- Disassembler for Python bytecode
@anchor{library/dis bytecodes}@anchor{59c}@anchor{library/dis python-bytecode-instructions}@anchor{462f}
@subsubsection Les instructions du code intermédiaire en Python


La fonction @ref{1d6,,get_instructions()} et la méthode @ref{f19,,Bytecode} fournit des détails sur le code intermédiaire des instructions comme @ref{1d7,,Instruction} instances :

@geindex Instruction (classe dans dis)
@anchor{library/dis dis Instruction}@anchor{1d7}
@deffn {Classe} dis.Instruction

Détails sur le code intermédiaire de l'opération

@geindex Instruction.opcode (dans le module dis)
@anchor{library/dis dis Instruction opcode}@anchor{4630}
@deffn {Données} opcode

code numérique pour l'opération, correspondant aux valeurs de l'`opcode' ci-dessous et les valeurs du code intermédiaire dans la @ref{4631,,Opcode collections}.
@end deffn

@geindex Instruction.opname (dans le module dis)
@anchor{library/dis dis Instruction opname}@anchor{4632}
@deffn {Données} opname

nom lisible/compréhensible de l'opération
@end deffn

@geindex Instruction.baseopcode (dans le module dis)
@anchor{library/dis dis Instruction baseopcode}@anchor{4633}
@deffn {Données} baseopcode

numeric code for the base operation if operation is specialized;
otherwise equal to @ref{4630,,opcode}
@end deffn

@geindex Instruction.baseopname (dans le module dis)
@anchor{library/dis dis Instruction baseopname}@anchor{4634}
@deffn {Données} baseopname

human readable name for the base operation if operation is specialized;
otherwise equal to @ref{4635,,opname}
@end deffn

@geindex Instruction.arg (dans le module dis)
@anchor{library/dis dis Instruction arg}@anchor{4636}
@deffn {Données} arg

le cas échéant, argument numérique de l'opération sinon @code{None}
@end deffn

@geindex Instruction.oparg (dans le module dis)
@anchor{library/dis dis Instruction oparg}@anchor{4637}
@deffn {Données} oparg

alias for @ref{4636,,arg}
@end deffn

@geindex Instruction.argval (dans le module dis)
@anchor{library/dis dis Instruction argval}@anchor{4638}
@deffn {Données} argval

resolved arg value (if any), otherwise @code{None}
@end deffn

@geindex Instruction.argrepr (dans le module dis)
@anchor{library/dis dis Instruction argrepr}@anchor{4639}
@deffn {Données} argrepr

human readable description of operation argument (if any),
otherwise an empty string.
@end deffn

@geindex Instruction.offset (dans le module dis)
@anchor{library/dis dis Instruction offset}@anchor{463a}
@deffn {Données} offset

start index of operation within bytecode sequence
@end deffn

@geindex Instruction.start_offset (dans le module dis)
@anchor{library/dis dis Instruction start_offset}@anchor{463b}
@deffn {Données} start_offset

start index of operation within bytecode sequence, including prefixed
@code{EXTENDED_ARG} operations if present; otherwise equal to @ref{463a,,offset}
@end deffn

@geindex Instruction.cache_offset (dans le module dis)
@anchor{library/dis dis Instruction cache_offset}@anchor{463c}
@deffn {Données} cache_offset

start index of the cache entries following the operation
@end deffn

@geindex Instruction.end_offset (dans le module dis)
@anchor{library/dis dis Instruction end_offset}@anchor{463d}
@deffn {Données} end_offset

end index of the cache entries following the operation
@end deffn

@geindex Instruction.starts_line (dans le module dis)
@anchor{library/dis dis Instruction starts_line}@anchor{463e}
@deffn {Données} starts_line

@code{True} if this opcode starts a source line, otherwise @code{False}
@end deffn

@geindex Instruction.line_number (dans le module dis)
@anchor{library/dis dis Instruction line_number}@anchor{463f}
@deffn {Données} line_number

source line number associated with this opcode (if any), otherwise @code{None}
@end deffn

@geindex Instruction.is_jump_target (dans le module dis)
@anchor{library/dis dis Instruction is_jump_target}@anchor{4640}
@deffn {Données} is_jump_target

@code{True} if other code jumps to here, otherwise @code{False}
@end deffn

@geindex Instruction.jump_target (dans le module dis)
@anchor{library/dis dis Instruction jump_target}@anchor{4641}
@deffn {Données} jump_target

bytecode index of the jump target if this is a jump operation,
otherwise @code{None}
@end deffn

@geindex Instruction.positions (dans le module dis)
@anchor{library/dis dis Instruction positions}@anchor{4642}
@deffn {Données} positions

@ref{43c8,,dis.Positions} object holding the
start and end locations that are covered by this instruction.
@end deffn

@c data::cache_info
@c 
@c Information about the cache entries of this instruction, as
@c triplets of the form ``(name, size, data)``, where the ``name``
@c and ``size`` describe the cache format and data is the contents
@c of the cache. ``cache_info`` is ``None`` if the instruction does not have
@c caches.


Ajouté dans la version 3.4.



Modifié dans la version 3.11: Field @code{positions} is added.



Modifié dans la version 3.13: Changed field @code{starts_line}.

Added fields @code{start_offset}, @code{cache_offset}, @code{end_offset},
@code{baseopname}, @code{baseopcode}, @code{jump_target}, @code{oparg},
@code{line_number} and @code{cache_info}.

@end deffn

@geindex Positions (classe dans dis)
@anchor{library/dis dis Positions}@anchor{43c8}
@deffn {Classe} dis.Positions

In case the information is not available, some fields might be @code{None}.

@geindex Positions.lineno (dans le module dis)
@anchor{library/dis dis Positions lineno}@anchor{4643}
@deffn {Données} lineno
@end deffn

@geindex Positions.end_lineno (dans le module dis)
@anchor{library/dis dis Positions end_lineno}@anchor{4644}
@deffn {Données} end_lineno
@end deffn

@geindex Positions.col_offset (dans le module dis)
@anchor{library/dis dis Positions col_offset}@anchor{4645}
@deffn {Données} col_offset
@end deffn

@geindex Positions.end_col_offset (dans le module dis)
@anchor{library/dis dis Positions end_col_offset}@anchor{4646}
@deffn {Données} end_col_offset
@end deffn


Ajouté dans la version 3.11.

@end deffn

The Python compiler currently generates the following bytecode instructions.

`General instructions'

In the following, We will refer to the interpreter stack as @code{STACK} and describe
operations on it as if it was a Python list. The top of the stack corresponds to
@code{STACK[-1]} in this language.

@geindex NOP (opcode)
@anchor{library/dis opcode-NOP}@anchor{4647}
@deffn {Opcode} NOP

Do nothing code.  Used as a placeholder by the bytecode optimizer, and to
generate line tracing events.
@end deffn

@geindex POP_TOP (opcode)
@anchor{library/dis opcode-POP_TOP}@anchor{4648}
@deffn {Opcode} POP_TOP

Removes the top-of-stack item:

@example
STACK.pop()
@end example
@end deffn

@geindex END_FOR (opcode)
@anchor{library/dis opcode-END_FOR}@anchor{4649}
@deffn {Opcode} END_FOR

Removes the top-of-stack item.
Equivalent to @code{POP_TOP}.
Used to clean up at the end of loops, hence the name.


Ajouté dans la version 3.12.

@end deffn

@geindex END_SEND (opcode)
@anchor{library/dis opcode-END_SEND}@anchor{464a}
@deffn {Opcode} END_SEND

Implements @code{del STACK[-2]}.
Used to clean up when a generator exits.


Ajouté dans la version 3.12.

@end deffn

@geindex COPY (opcode)
@anchor{library/dis opcode-COPY}@anchor{6f3}
@deffn {Opcode} COPY (i)

Push the i-th item to the top of the stack without removing it from its original
location:

@example
assert i > 0
STACK.append(STACK[-i])
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex SWAP (opcode)
@anchor{library/dis opcode-SWAP}@anchor{6f4}
@deffn {Opcode} SWAP (i)

Swap the top of the stack with the i-th element:

@example
STACK[-i], STACK[-1] = STACK[-1], STACK[-i]
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex CACHE (opcode)
@anchor{library/dis opcode-CACHE}@anchor{6e3}
@deffn {Opcode} CACHE

Rather than being an actual instruction, this opcode is used to mark extra
space for the interpreter to cache useful data directly in the bytecode
itself. It is automatically hidden by all @code{dis} utilities, but can be
viewed with @code{show_caches=True}.

Logically, this space is part of the preceding instruction. Many opcodes
expect to be followed by an exact number of caches, and will instruct the
interpreter to skip over them at runtime.

Populated caches can look like arbitrary instructions, so great care should
be taken when reading or modifying raw, adaptive bytecode containing
quickened data.


Ajouté dans la version 3.11.

@end deffn

`Unary operations'

Unary operations take the top of the stack, apply the operation, and push the
result back on the stack.

@geindex UNARY_NEGATIVE (opcode)
@anchor{library/dis opcode-UNARY_NEGATIVE}@anchor{464b}
@deffn {Opcode} UNARY_NEGATIVE

Implements @code{STACK[-1] = -STACK[-1]}.
@end deffn

@geindex UNARY_NOT (opcode)
@anchor{library/dis opcode-UNARY_NOT}@anchor{1679}
@deffn {Opcode} UNARY_NOT

Implements @code{STACK[-1] = not STACK[-1]}.


Modifié dans la version 3.13: This instruction now requires an exact @ref{451,,bool} operand.

@end deffn

@geindex UNARY_INVERT (opcode)
@anchor{library/dis opcode-UNARY_INVERT}@anchor{464c}
@deffn {Opcode} UNARY_INVERT

Implements @code{STACK[-1] = ~STACK[-1]}.
@end deffn

@geindex GET_ITER (opcode)
@anchor{library/dis opcode-GET_ITER}@anchor{464d}
@deffn {Opcode} GET_ITER

Implements @code{STACK[-1] = iter(STACK[-1])}.
@end deffn

@geindex GET_YIELD_FROM_ITER (opcode)
@anchor{library/dis opcode-GET_YIELD_FROM_ITER}@anchor{464e}
@deffn {Opcode} GET_YIELD_FROM_ITER

If @code{STACK[-1]} is a @ref{bcc,,generator iterator} or @ref{47b,,coroutine} object
it is left as is.  Otherwise, implements @code{STACK[-1] = iter(STACK[-1])}.


Ajouté dans la version 3.5.

@end deffn

@geindex TO_BOOL (opcode)
@anchor{library/dis opcode-TO_BOOL}@anchor{1676}
@deffn {Opcode} TO_BOOL

Implements @code{STACK[-1] = bool(STACK[-1])}.


Ajouté dans la version 3.13.

@end deffn

`Binary and in-place operations'

Binary operations remove the top two items from the stack (@code{STACK[-1]} and
@code{STACK[-2]}). They perform the operation, then put the result back on the stack.

In-place operations are like binary operations, but the operation is done in-place
when @code{STACK[-2]} supports it, and the resulting @code{STACK[-1]} may be (but does
not have to be) the original @code{STACK[-2]}.

@geindex BINARY_OP (opcode)
@anchor{library/dis opcode-BINARY_OP}@anchor{6f0}
@deffn {Opcode} BINARY_OP (op)

Implements the binary and in-place operators (depending on the value of
`op'):

@example
rhs = STACK.pop()
lhs = STACK.pop()
STACK.append(lhs op rhs)
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex BINARY_SUBSCR (opcode)
@anchor{library/dis opcode-BINARY_SUBSCR}@anchor{16cb}
@deffn {Opcode} BINARY_SUBSCR

Implements:

@example
key = STACK.pop()
container = STACK.pop()
STACK.append(container[key])
@end example
@end deffn

@geindex STORE_SUBSCR (opcode)
@anchor{library/dis opcode-STORE_SUBSCR}@anchor{17a9}
@deffn {Opcode} STORE_SUBSCR

Implements:

@example
key = STACK.pop()
container = STACK.pop()
value = STACK.pop()
container[key] = value
@end example
@end deffn

@geindex DELETE_SUBSCR (opcode)
@anchor{library/dis opcode-DELETE_SUBSCR}@anchor{464f}
@deffn {Opcode} DELETE_SUBSCR

Implements:

@example
key = STACK.pop()
container = STACK.pop()
del container[key]
@end example
@end deffn

@geindex BINARY_SLICE (opcode)
@anchor{library/dis opcode-BINARY_SLICE}@anchor{4c9}
@deffn {Opcode} BINARY_SLICE

Implements:

@example
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
STACK.append(container[start:end])
@end example


Ajouté dans la version 3.12.

@end deffn

@geindex STORE_SLICE (opcode)
@anchor{library/dis opcode-STORE_SLICE}@anchor{4ca}
@deffn {Opcode} STORE_SLICE

Implements:

@example
end = STACK.pop()
start = STACK.pop()
container = STACK.pop()
values = STACK.pop()
container[start:end] = value
@end example


Ajouté dans la version 3.12.

@end deffn

`Coroutine opcodes'

@geindex GET_AWAITABLE (opcode)
@anchor{library/dis opcode-GET_AWAITABLE}@anchor{17c4}
@deffn {Opcode} GET_AWAITABLE (where)

Implements @code{STACK[-1] = get_awaitable(STACK[-1])}, where @code{get_awaitable(o)}
returns @code{o} if @code{o} is a coroutine object or a generator object with
the @ref{43d9,,CO_ITERABLE_COROUTINE} flag, or resolves
@code{o.__await__}.

@quotation

If the @code{where} operand is nonzero, it indicates where the instruction
occurs:


@itemize *

@item 
@code{1}: After a call to @code{__aenter__}

@item 
@code{2}: After a call to @code{__aexit__}
@end itemize
@end quotation


Ajouté dans la version 3.5.



Modifié dans la version 3.11: Previously, this instruction did not have an oparg.

@end deffn

@geindex GET_AITER (opcode)
@anchor{library/dis opcode-GET_AITER}@anchor{4650}
@deffn {Opcode} GET_AITER

Implements @code{STACK[-1] = STACK[-1].__aiter__()}.


Ajouté dans la version 3.5.



Modifié dans la version 3.7: Returning awaitable objects from @code{__aiter__} is no longer
supported.

@end deffn

@geindex GET_ANEXT (opcode)
@anchor{library/dis opcode-GET_ANEXT}@anchor{4651}
@deffn {Opcode} GET_ANEXT

Implement @code{STACK.append(get_awaitable(STACK[-1].__anext__()))} to the stack.
See @code{GET_AWAITABLE} for details about @code{get_awaitable}.


Ajouté dans la version 3.5.

@end deffn

@geindex END_ASYNC_FOR (opcode)
@anchor{library/dis opcode-END_ASYNC_FOR}@anchor{a98}
@deffn {Opcode} END_ASYNC_FOR

Terminates an @ref{a99,,async for} loop.  Handles an exception raised
when awaiting a next item. The stack contains the async iterable in
@code{STACK[-2]} and the raised exception in @code{STACK[-1]}. Both are popped.
If the exception is not @ref{19bb,,StopAsyncIteration}, it is re-raised.


Ajouté dans la version 3.8.



Modifié dans la version 3.11: Exception representation on the stack now consist of one, not three, items.

@end deffn

@geindex CLEANUP_THROW (opcode)
@anchor{library/dis opcode-CLEANUP_THROW}@anchor{4cd}
@deffn {Opcode} CLEANUP_THROW

Handles an exception raised during a @ref{4e2,,throw()} or
@ref{167d,,close()} call through the current frame.  If @code{STACK[-1]} is an
instance of @ref{be8,,StopIteration}, pop three values from the stack and push
its @code{value} member.  Otherwise, re-raise @code{STACK[-1]}.


Ajouté dans la version 3.12.

@end deffn

@geindex BEFORE_ASYNC_WITH (opcode)
@anchor{library/dis opcode-BEFORE_ASYNC_WITH}@anchor{4652}
@deffn {Opcode} BEFORE_ASYNC_WITH

Resolves @code{__aenter__} and @code{__aexit__} from @code{STACK[-1]}.
Pushes @code{__aexit__} and result of @code{__aenter__()} to the stack:

@example
STACK.extend((__aexit__, __aenter__())
@end example


Ajouté dans la version 3.5.

@end deffn

`Miscellaneous opcodes'

@geindex SET_ADD (opcode)
@anchor{library/dis opcode-SET_ADD}@anchor{4653}
@deffn {Opcode} SET_ADD (i)

Implements:

@example
item = STACK.pop()
set.add(STACK[-i], item)
@end example

Used to implement set comprehensions.
@end deffn

@geindex LIST_APPEND (opcode)
@anchor{library/dis opcode-LIST_APPEND}@anchor{4654}
@deffn {Opcode} LIST_APPEND (i)

Implements:

@example
item = STACK.pop()
list.append(STACK[-i], item)
@end example

Used to implement list comprehensions.
@end deffn

@geindex MAP_ADD (opcode)
@anchor{library/dis opcode-MAP_ADD}@anchor{a9a}
@deffn {Opcode} MAP_ADD (i)

Implements:

@example
value = STACK.pop()
key = STACK.pop()
dict.__setitem__(STACK[-i], key, value)
@end example

Used to implement dict comprehensions.


Ajouté dans la version 3.1.



Modifié dans la version 3.8: Map value is @code{STACK[-1]} and map key is @code{STACK[-2]}. Before, those
were reversed.

@end deffn

For all of the @ref{4653,,SET_ADD}, @ref{4654,,LIST_APPEND} and @ref{a9a,,MAP_ADD}
instructions, while the added value or key/value pair is popped off, the
container object remains on the stack so that it is available for further
iterations of the loop.

@geindex RETURN_VALUE (opcode)
@anchor{library/dis opcode-RETURN_VALUE}@anchor{1735}
@deffn {Opcode} RETURN_VALUE

Returns with @code{STACK[-1]} to the caller of the function.
@end deffn

@geindex RETURN_CONST (opcode)
@anchor{library/dis opcode-RETURN_CONST}@anchor{4d3}
@deffn {Opcode} RETURN_CONST (consti)

Returns with @code{co_consts[consti]} to the caller of the function.


Ajouté dans la version 3.12.

@end deffn

@geindex YIELD_VALUE (opcode)
@anchor{library/dis opcode-YIELD_VALUE}@anchor{309}
@deffn {Opcode} YIELD_VALUE

Yields @code{STACK.pop()} from a @ref{104a,,generator}.


Modifié dans la version 3.11: oparg set to be the stack depth.



Modifié dans la version 3.12: oparg set to be the exception block depth, for efficient closing of generators.



Modifié dans la version 3.13: oparg is @code{1} if this instruction is part of a yield-from or await, and @code{0}
otherwise.

@end deffn

@geindex SETUP_ANNOTATIONS (opcode)
@anchor{library/dis opcode-SETUP_ANNOTATIONS}@anchor{d42}
@deffn {Opcode} SETUP_ANNOTATIONS

Checks whether @code{__annotations__} is defined in @code{locals()}, if not it is
set up to an empty @code{dict}. This opcode is only emitted if a class
or module body contains @ref{d43,,variable annotations}
statically.


Ajouté dans la version 3.6.

@end deffn

@geindex POP_EXCEPT (opcode)
@anchor{library/dis opcode-POP_EXCEPT}@anchor{4655}
@deffn {Opcode} POP_EXCEPT

Pops a value from the stack, which is used to restore the exception state.


Modifié dans la version 3.11: Exception representation on the stack now consist of one, not three, items.

@end deffn

@geindex RERAISE (opcode)
@anchor{library/dis opcode-RERAISE}@anchor{4656}
@deffn {Opcode} RERAISE

Re-raises the exception currently on top of the stack. If oparg is non-zero,
pops an additional value from the stack which is used to set
@ref{874,,f_lasti} of the current frame.


Ajouté dans la version 3.9.



Modifié dans la version 3.11: Exception representation on the stack now consist of one, not three, items.

@end deffn

@geindex PUSH_EXC_INFO (opcode)
@anchor{library/dis opcode-PUSH_EXC_INFO}@anchor{6ed}
@deffn {Opcode} PUSH_EXC_INFO

Pops a value from the stack. Pushes the current exception to the top of the stack.
Pushes the value originally popped back to the stack.
Used in exception handlers.


Ajouté dans la version 3.11.

@end deffn

@geindex CHECK_EXC_MATCH (opcode)
@anchor{library/dis opcode-CHECK_EXC_MATCH}@anchor{6f5}
@deffn {Opcode} CHECK_EXC_MATCH

Performs exception matching for @code{except}. Tests whether the @code{STACK[-2]}
is an exception matching @code{STACK[-1]}. Pops @code{STACK[-1]} and pushes the boolean
result of the test.


Ajouté dans la version 3.11.

@end deffn

@geindex CHECK_EG_MATCH (opcode)
@anchor{library/dis opcode-CHECK_EG_MATCH}@anchor{6ec}
@deffn {Opcode} CHECK_EG_MATCH

Performs exception matching for @code{except*}. Applies @code{split(STACK[-1])} on
the exception group representing @code{STACK[-2]}.

In case of a match, pops two items from the stack and pushes the
non-matching subgroup (@code{None} in case of full match) followed by the
matching subgroup. When there is no match, pops one item (the match
type) and pushes @code{None}.


Ajouté dans la version 3.11.

@end deffn

@geindex WITH_EXCEPT_START (opcode)
@anchor{library/dis opcode-WITH_EXCEPT_START}@anchor{4657}
@deffn {Opcode} WITH_EXCEPT_START

Calls the function in position 4 on the stack with arguments (type, val, tb)
representing the exception at the top of the stack.
Used to implement the call @code{context_manager.__exit__(*exc_info())} when an exception
has occurred in a @ref{5bc,,with} statement.


Ajouté dans la version 3.9.



Modifié dans la version 3.11: The @code{__exit__} function is in position 4 of the stack rather than 7.
Exception representation on the stack now consist of one, not three, items.

@end deffn

@geindex LOAD_ASSERTION_ERROR (opcode)
@anchor{library/dis opcode-LOAD_ASSERTION_ERROR}@anchor{954}
@deffn {Opcode} LOAD_ASSERTION_ERROR

Pushes @ref{694,,AssertionError} onto the stack.  Used by the @ref{955,,assert}
statement.


Ajouté dans la version 3.9.

@end deffn

@geindex LOAD_BUILD_CLASS (opcode)
@anchor{library/dis opcode-LOAD_BUILD_CLASS}@anchor{4658}
@deffn {Opcode} LOAD_BUILD_CLASS

Pushes @code{builtins.__build_class__()} onto the stack.  It is later called
to construct a class.
@end deffn

@geindex BEFORE_WITH (opcode)
@anchor{library/dis opcode-BEFORE_WITH}@anchor{6f7}
@deffn {Opcode} BEFORE_WITH

This opcode performs several operations before a with block starts.  First,
it loads @ref{12de,,__exit__()} from the context manager and pushes it onto
the stack for later use by @ref{4657,,WITH_EXCEPT_START}.  Then,
@ref{5b2,,__enter__()} is called. Finally, the result of calling the
@code{__enter__()} method is pushed onto the stack.


Ajouté dans la version 3.11.

@end deffn

@geindex GET_LEN (opcode)
@anchor{library/dis opcode-GET_LEN}@anchor{4659}
@deffn {Opcode} GET_LEN

Perform @code{STACK.append(len(STACK[-1]))}. Used in @ref{7f7,,match} statements where
comparison with structure of pattern is needed.


Ajouté dans la version 3.10.

@end deffn

@geindex MATCH_MAPPING (opcode)
@anchor{library/dis opcode-MATCH_MAPPING}@anchor{465a}
@deffn {Opcode} MATCH_MAPPING

If @code{STACK[-1]} is an instance of @ref{8b7,,collections.abc.Mapping} (or, more
technically: if it has the @ref{1831,,Py_TPFLAGS_MAPPING} flag set in its
@ref{184b,,tp_flags}), push @code{True} onto the stack.  Otherwise,
push @code{False}.


Ajouté dans la version 3.10.

@end deffn

@geindex MATCH_SEQUENCE (opcode)
@anchor{library/dis opcode-MATCH_SEQUENCE}@anchor{465b}
@deffn {Opcode} MATCH_SEQUENCE

If @code{STACK[-1]} is an instance of @ref{11a1,,collections.abc.Sequence} and is `not' an instance
of @ref{435,,str}/@ref{1bd,,bytes}/@ref{528,,bytearray} (or, more technically: if it has
the @ref{1832,,Py_TPFLAGS_SEQUENCE} flag set in its @ref{184b,,tp_flags}),
push @code{True} onto the stack.  Otherwise, push @code{False}.


Ajouté dans la version 3.10.

@end deffn

@geindex MATCH_KEYS (opcode)
@anchor{library/dis opcode-MATCH_KEYS}@anchor{6fd}
@deffn {Opcode} MATCH_KEYS

@code{STACK[-1]} is a tuple of mapping keys, and @code{STACK[-2]} is the match subject.
If @code{STACK[-2]} contains all of the keys in @code{STACK[-1]}, push a @ref{366,,tuple}
containing the corresponding values. Otherwise, push @code{None}.


Ajouté dans la version 3.10.



Modifié dans la version 3.11: Previously, this instruction also pushed a boolean value indicating
success (@code{True}) or failure (@code{False}).

@end deffn

@geindex STORE_NAME (opcode)
@anchor{library/dis opcode-STORE_NAME}@anchor{465c}
@deffn {Opcode} STORE_NAME (namei)

Implements @code{name = STACK.pop()}. `namei' is the index of `name' in the attribute
@ref{1ec7,,co_names} of the @ref{1cd,,code object}.
The compiler tries to use @ref{167a,,STORE_FAST} or @ref{465d,,STORE_GLOBAL} if possible.
@end deffn

@geindex DELETE_NAME (opcode)
@anchor{library/dis opcode-DELETE_NAME}@anchor{465e}
@deffn {Opcode} DELETE_NAME (namei)

Implements @code{del name}, where `namei' is the index into @ref{1ec7,,co_names}
attribute of the @ref{1cd,,code object}.
@end deffn

@geindex UNPACK_SEQUENCE (opcode)
@anchor{library/dis opcode-UNPACK_SEQUENCE}@anchor{17c6}
@deffn {Opcode} UNPACK_SEQUENCE (count)

Unpacks @code{STACK[-1]} into `count' individual values, which are put onto the stack
right-to-left. Require there to be exactly `count' values.:

@example
assert(len(STACK[-1]) == count)
STACK.extend(STACK.pop()[:-count-1:-1])
@end example
@end deffn

@geindex UNPACK_EX (opcode)
@anchor{library/dis opcode-UNPACK_EX}@anchor{465f}
@deffn {Opcode} UNPACK_EX (counts)

Implements assignment with a starred target: Unpacks an iterable in @code{STACK[-1]}
into individual values, where the total number of values can be smaller than the
number of items in the iterable: one of the new values will be a list of all
leftover items.

The number of values before and after the list value is limited to 255.

The number of values before the list value is encoded in the argument of the
opcode. The number of values after the list if any is encoded using an
@code{EXTENDED_ARG}. As a consequence, the argument can be seen as a two bytes values
where the low byte of `counts' is the number of values before the list value, the
high byte of `counts' the number of values after it.

The extracted values are put onto the stack right-to-left, i.e. @code{a, *b, c = d}
will be stored after execution as @code{STACK.extend((a, b, c))}.
@end deffn

@geindex STORE_ATTR (opcode)
@anchor{library/dis opcode-STORE_ATTR}@anchor{17c5}
@deffn {Opcode} STORE_ATTR (namei)

Implements:

@example
obj = STACK.pop()
value = STACK.pop()
obj.name = value
@end example

where `namei' is the index of name in @ref{1ec7,,co_names} of the
@ref{1cd,,code object}.
@end deffn

@geindex DELETE_ATTR (opcode)
@anchor{library/dis opcode-DELETE_ATTR}@anchor{4660}
@deffn {Opcode} DELETE_ATTR (namei)

Implements:

@example
obj = STACK.pop()
del obj.name
@end example

where `namei' is the index of name into @ref{1ec7,,co_names} of the
@ref{1cd,,code object}.
@end deffn

@geindex STORE_GLOBAL (opcode)
@anchor{library/dis opcode-STORE_GLOBAL}@anchor{465d}
@deffn {Opcode} STORE_GLOBAL (namei)

Works as @ref{465c,,STORE_NAME}, but stores the name as a global.
@end deffn

@geindex DELETE_GLOBAL (opcode)
@anchor{library/dis opcode-DELETE_GLOBAL}@anchor{4661}
@deffn {Opcode} DELETE_GLOBAL (namei)

Works as @ref{465e,,DELETE_NAME}, but deletes a global name.
@end deffn

@geindex LOAD_CONST (opcode)
@anchor{library/dis opcode-LOAD_CONST}@anchor{4662}
@deffn {Opcode} LOAD_CONST (consti)

Pushes @code{co_consts[consti]} onto the stack.
@end deffn

@geindex LOAD_NAME (opcode)
@anchor{library/dis opcode-LOAD_NAME}@anchor{4663}
@deffn {Opcode} LOAD_NAME (namei)

Pushes the value associated with @code{co_names[namei]} onto the stack.
The name is looked up within the locals, then the globals, then the builtins.
@end deffn

@geindex LOAD_LOCALS (opcode)
@anchor{library/dis opcode-LOAD_LOCALS}@anchor{4d2}
@deffn {Opcode} LOAD_LOCALS

Pushes a reference to the locals dictionary onto the stack.  This is used
to prepare namespace dictionaries for @ref{4d0,,LOAD_FROM_DICT_OR_DEREF}
and @ref{4d1,,LOAD_FROM_DICT_OR_GLOBALS}.


Ajouté dans la version 3.12.

@end deffn

@geindex LOAD_FROM_DICT_OR_GLOBALS (opcode)
@anchor{library/dis opcode-LOAD_FROM_DICT_OR_GLOBALS}@anchor{4d1}
@deffn {Opcode} LOAD_FROM_DICT_OR_GLOBALS (i)

Pops a mapping off the stack and looks up the value for @code{co_names[namei]}.
If the name is not found there, looks it up in the globals and then the builtins,
similar to @ref{1673,,LOAD_GLOBAL}.
This is used for loading global variables in
@ref{186,,annotation scopes} within class bodies.


Ajouté dans la version 3.12.

@end deffn

@geindex BUILD_TUPLE (opcode)
@anchor{library/dis opcode-BUILD_TUPLE}@anchor{4664}
@deffn {Opcode} BUILD_TUPLE (count)

Creates a tuple consuming `count' items from the stack, and pushes the
resulting tuple onto the stack:

@example
if count == 0:
    value = ()
else:
    value = tuple(STACK[-count:])
    STACK = STACK[:-count]

STACK.append(value)
@end example
@end deffn

@geindex BUILD_LIST (opcode)
@anchor{library/dis opcode-BUILD_LIST}@anchor{4665}
@deffn {Opcode} BUILD_LIST (count)

Works as @ref{4664,,BUILD_TUPLE}, but creates a list.
@end deffn

@geindex BUILD_SET (opcode)
@anchor{library/dis opcode-BUILD_SET}@anchor{4666}
@deffn {Opcode} BUILD_SET (count)

Works as @ref{4664,,BUILD_TUPLE}, but creates a set.
@end deffn

@geindex BUILD_MAP (opcode)
@anchor{library/dis opcode-BUILD_MAP}@anchor{166c}
@deffn {Opcode} BUILD_MAP (count)

Pushes a new dictionary object onto the stack.  Pops @code{2 * count} items
so that the dictionary holds `count' entries:
@code{@{..., STACK[-4]: STACK[-3], STACK[-2]: STACK[-1]@}}.


Modifié dans la version 3.5: The dictionary is created from stack items instead of creating an
empty dictionary pre-sized to hold `count' items.

@end deffn

@geindex BUILD_CONST_KEY_MAP (opcode)
@anchor{library/dis opcode-BUILD_CONST_KEY_MAP}@anchor{d3f}
@deffn {Opcode} BUILD_CONST_KEY_MAP (count)

The version of @ref{166c,,BUILD_MAP} specialized for constant keys. Pops the
top element on the stack which contains a tuple of keys, then starting from
@code{STACK[-2]}, pops `count' values to form values in the built dictionary.


Ajouté dans la version 3.6.

@end deffn

@geindex BUILD_STRING (opcode)
@anchor{library/dis opcode-BUILD_STRING}@anchor{d3e}
@deffn {Opcode} BUILD_STRING (count)

Concatenates `count' strings from the stack and pushes the resulting string
onto the stack.


Ajouté dans la version 3.6.

@end deffn

@geindex LIST_EXTEND (opcode)
@anchor{library/dis opcode-LIST_EXTEND}@anchor{4667}
@deffn {Opcode} LIST_EXTEND (i)

Implements:

@example
seq = STACK.pop()
list.extend(STACK[-i], seq)
@end example

Used to build lists.


Ajouté dans la version 3.9.

@end deffn

@geindex SET_UPDATE (opcode)
@anchor{library/dis opcode-SET_UPDATE}@anchor{4668}
@deffn {Opcode} SET_UPDATE (i)

Implements:

@example
seq = STACK.pop()
set.update(STACK[-i], seq)
@end example

Used to build sets.


Ajouté dans la version 3.9.

@end deffn

@geindex DICT_UPDATE (opcode)
@anchor{library/dis opcode-DICT_UPDATE}@anchor{4669}
@deffn {Opcode} DICT_UPDATE (i)

Implements:

@example
map = STACK.pop()
dict.update(STACK[-i], map)
@end example

Used to build dicts.


Ajouté dans la version 3.9.

@end deffn

@geindex DICT_MERGE (opcode)
@anchor{library/dis opcode-DICT_MERGE}@anchor{466a}
@deffn {Opcode} DICT_MERGE (i)

Like @ref{4669,,DICT_UPDATE} but raises an exception for duplicate keys.


Ajouté dans la version 3.9.

@end deffn

@geindex LOAD_ATTR (opcode)
@anchor{library/dis opcode-LOAD_ATTR}@anchor{4c8}
@deffn {Opcode} LOAD_ATTR (namei)

If the low bit of @code{namei} is not set, this replaces @code{STACK[-1]} with
@code{getattr(STACK[-1], co_names[namei>>1])}.

If the low bit of @code{namei} is set, this will attempt to load a method named
@code{co_names[namei>>1]} from the @code{STACK[-1]} object. @code{STACK[-1]} is popped.
This bytecode distinguishes two cases: if @code{STACK[-1]} has a method with the
correct name, the bytecode pushes the unbound method and @code{STACK[-1]}.
@code{STACK[-1]} will be used as the first argument (@code{self}) by @ref{6f1,,CALL}
or @ref{166d,,CALL_KW} when calling the unbound method.
Otherwise, @code{NULL} and the object returned by
the attribute lookup are pushed.


Modifié dans la version 3.12: If the low bit of @code{namei} is set, then a @code{NULL} or @code{self} is
pushed to the stack before the attribute or unbound method respectively.

@end deffn

@geindex LOAD_SUPER_ATTR (opcode)
@anchor{library/dis opcode-LOAD_SUPER_ATTR}@anchor{4c6}
@deffn {Opcode} LOAD_SUPER_ATTR (namei)

This opcode implements @ref{4c5,,super()}, both in its zero-argument and
two-argument forms (e.g. @code{super().method()}, @code{super().attr} and
@code{super(cls, self).method()}, @code{super(cls, self).attr}).

It pops three values from the stack (from top of stack down):


@itemize *

@item 
@code{self}: the first argument to the current method

@item 
@code{cls}: the class within which the current method was defined

@item 
the global @code{super}
@end itemize

With respect to its argument, it works similarly to @ref{4c8,,LOAD_ATTR},
except that @code{namei} is shifted left by 2 bits instead of 1.

The low bit of @code{namei} signals to attempt a method load, as with
@ref{4c8,,LOAD_ATTR}, which results in pushing @code{NULL} and the loaded method.
When it is unset a single value is pushed to the stack.

The second-low bit of @code{namei}, if set, means that this was a two-argument
call to @ref{4c5,,super()} (unset means zero-argument).


Ajouté dans la version 3.12.

@end deffn

@geindex COMPARE_OP (opcode)
@anchor{library/dis opcode-COMPARE_OP}@anchor{956}
@deffn {Opcode} COMPARE_OP (opname)

Performs a Boolean operation.  The operation name can be found in
@code{cmp_op[opname >> 5]}. If the fifth-lowest bit of @code{opname} is set
(@code{opname & 16}), the result should be coerced to @code{bool}.


Modifié dans la version 3.13: The fifth-lowest bit of the oparg now indicates a forced conversion to
@ref{451,,bool}.

@end deffn

@geindex IS_OP (opcode)
@anchor{library/dis opcode-IS_OP}@anchor{466b}
@deffn {Opcode} IS_OP (invert)

Performs @code{is} comparison, or @code{is not} if @code{invert} is 1.


Ajouté dans la version 3.9.

@end deffn

@geindex CONTAINS_OP (opcode)
@anchor{library/dis opcode-CONTAINS_OP}@anchor{466c}
@deffn {Opcode} CONTAINS_OP (invert)

Performs @code{in} comparison, or @code{not in} if @code{invert} is 1.


Ajouté dans la version 3.9.

@end deffn

@geindex IMPORT_NAME (opcode)
@anchor{library/dis opcode-IMPORT_NAME}@anchor{466d}
@deffn {Opcode} IMPORT_NAME (namei)

Imports the module @code{co_names[namei]}.  @code{STACK[-1]} and @code{STACK[-2]} are
popped and provide the `fromlist' and `level' arguments of @ref{8c1,,__import__()}.
The module object is pushed onto the stack.  The current namespace is not affected: for a proper import statement, a subsequent @ref{167a,,STORE_FAST} instruction
modifies the namespace.
@end deffn

@geindex IMPORT_FROM (opcode)
@anchor{library/dis opcode-IMPORT_FROM}@anchor{466e}
@deffn {Opcode} IMPORT_FROM (namei)

Loads the attribute @code{co_names[namei]} from the module found in @code{STACK[-1]}.
The resulting object is pushed onto the stack, to be subsequently stored by a
@ref{167a,,STORE_FAST} instruction.
@end deffn

@geindex JUMP_FORWARD (opcode)
@anchor{library/dis opcode-JUMP_FORWARD}@anchor{1568}
@deffn {Opcode} JUMP_FORWARD (delta)

Increments bytecode counter by `delta'.
@end deffn

@geindex JUMP_BACKWARD (opcode)
@anchor{library/dis opcode-JUMP_BACKWARD}@anchor{6f6}
@deffn {Opcode} JUMP_BACKWARD (delta)

Decrements bytecode counter by `delta'. Checks for interrupts.


Ajouté dans la version 3.11.

@end deffn

@geindex JUMP_BACKWARD_NO_INTERRUPT (opcode)
@anchor{library/dis opcode-JUMP_BACKWARD_NO_INTERRUPT}@anchor{6e9}
@deffn {Opcode} JUMP_BACKWARD_NO_INTERRUPT (delta)

Decrements bytecode counter by `delta'. Does not check for interrupts.


Ajouté dans la version 3.11.

@end deffn

@geindex POP_JUMP_IF_TRUE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_TRUE}@anchor{1677}
@deffn {Opcode} POP_JUMP_IF_TRUE (delta)

If @code{STACK[-1]} is true, increments the bytecode counter by `delta'.
@code{STACK[-1]} is popped.


Modifié dans la version 3.11: The oparg is now a relative delta rather than an absolute target.
This opcode is a pseudo-instruction, replaced in final bytecode by
the directed versions (forward/backward).



Modifié dans la version 3.12: This is no longer a pseudo-instruction.



Modifié dans la version 3.13: This instruction now requires an exact @ref{451,,bool} operand.

@end deffn

@geindex POP_JUMP_IF_FALSE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_FALSE}@anchor{1678}
@deffn {Opcode} POP_JUMP_IF_FALSE (delta)

If @code{STACK[-1]} is false, increments the bytecode counter by `delta'.
@code{STACK[-1]} is popped.


Modifié dans la version 3.11: The oparg is now a relative delta rather than an absolute target.
This opcode is a pseudo-instruction, replaced in final bytecode by
the directed versions (forward/backward).



Modifié dans la version 3.12: This is no longer a pseudo-instruction.



Modifié dans la version 3.13: This instruction now requires an exact @ref{451,,bool} operand.

@end deffn

@geindex POP_JUMP_IF_NOT_NONE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_NOT_NONE}@anchor{1785}
@deffn {Opcode} POP_JUMP_IF_NOT_NONE (delta)

If @code{STACK[-1]} is not @code{None}, increments the bytecode counter by `delta'.
@code{STACK[-1]} is popped.

This opcode is a pseudo-instruction, replaced in final bytecode by
the directed versions (forward/backward).


Ajouté dans la version 3.11.



Modifié dans la version 3.12: This is no longer a pseudo-instruction.

@end deffn

@geindex POP_JUMP_IF_NONE (opcode)
@anchor{library/dis opcode-POP_JUMP_IF_NONE}@anchor{1784}
@deffn {Opcode} POP_JUMP_IF_NONE (delta)

If @code{STACK[-1]} is @code{None}, increments the bytecode counter by `delta'.
@code{STACK[-1]} is popped.

This opcode is a pseudo-instruction, replaced in final bytecode by
the directed versions (forward/backward).


Ajouté dans la version 3.11.



Modifié dans la version 3.12: This is no longer a pseudo-instruction.

@end deffn

@geindex FOR_ITER (opcode)
@anchor{library/dis opcode-FOR_ITER}@anchor{16df}
@deffn {Opcode} FOR_ITER (delta)

@code{STACK[-1]} is an @ref{1aa,,iterator}.  Call its @ref{12ab,,__next__()} method.
If this yields a new value, push it on the stack (leaving the iterator below
it).  If the iterator indicates it is exhausted then the byte code counter is
incremented by `delta'.


Modifié dans la version 3.12: Up until 3.11 the iterator was popped when it was exhausted.

@end deffn

@geindex LOAD_GLOBAL (opcode)
@anchor{library/dis opcode-LOAD_GLOBAL}@anchor{1673}
@deffn {Opcode} LOAD_GLOBAL (namei)

Loads the global named @code{co_names[namei>>1]} onto the stack.


Modifié dans la version 3.11: If the low bit of @code{namei} is set, then a @code{NULL} is pushed to the
stack before the global variable.

@end deffn

@geindex LOAD_FAST (opcode)
@anchor{library/dis opcode-LOAD_FAST}@anchor{466f}
@deffn {Opcode} LOAD_FAST (var_num)

Pushes a reference to the local @code{co_varnames[var_num]} onto the stack.


Modifié dans la version 3.12: This opcode is now only used in situations where the local variable is
guaranteed to be initialized. It cannot raise @ref{14ec,,UnboundLocalError}.

@end deffn

@geindex LOAD_FAST_LOAD_FAST (opcode)
@anchor{library/dis opcode-LOAD_FAST_LOAD_FAST}@anchor{4670}
@deffn {Opcode} LOAD_FAST_LOAD_FAST (var_nums)

Pushes references to @code{co_varnames[var_nums >> 4]} and
@code{co_varnames[var_nums & 15]} onto the stack.


Ajouté dans la version 3.13.

@end deffn

@geindex LOAD_FAST_CHECK (opcode)
@anchor{library/dis opcode-LOAD_FAST_CHECK}@anchor{4cf}
@deffn {Opcode} LOAD_FAST_CHECK (var_num)

Pushes a reference to the local @code{co_varnames[var_num]} onto the stack,
raising an @ref{14ec,,UnboundLocalError} if the local variable has not been
initialized.


Ajouté dans la version 3.12.

@end deffn

@geindex LOAD_FAST_AND_CLEAR (opcode)
@anchor{library/dis opcode-LOAD_FAST_AND_CLEAR}@anchor{4ce}
@deffn {Opcode} LOAD_FAST_AND_CLEAR (var_num)

Pushes a reference to the local @code{co_varnames[var_num]} onto the stack (or
pushes @code{NULL} onto the stack if the local variable has not been
initialized) and sets @code{co_varnames[var_num]} to @code{NULL}.


Ajouté dans la version 3.12.

@end deffn

@geindex STORE_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST}@anchor{167a}
@deffn {Opcode} STORE_FAST (var_num)

Stores @code{STACK.pop()} into the local @code{co_varnames[var_num]}.
@end deffn

@geindex STORE_FAST_STORE_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST_STORE_FAST}@anchor{4671}
@deffn {Opcode} STORE_FAST_STORE_FAST (var_nums)

Stores @code{STACK[-1]} into @code{co_varnames[var_nums >> 4]}
and @code{STACK[-2]} into @code{co_varnames[var_nums & 15]}.


Ajouté dans la version 3.13.

@end deffn

@geindex STORE_FAST_LOAD_FAST (opcode)
@anchor{library/dis opcode-STORE_FAST_LOAD_FAST}@anchor{4672}
@deffn {Opcode} STORE_FAST_LOAD_FAST (var_nums)

Stores @code{STACK.pop()} into the local @code{co_varnames[var_nums >> 4]}
and pushes a reference to the local @code{co_varnames[var_nums & 15]}
onto the stack.


Ajouté dans la version 3.13.

@end deffn

@geindex DELETE_FAST (opcode)
@anchor{library/dis opcode-DELETE_FAST}@anchor{4673}
@deffn {Opcode} DELETE_FAST (var_num)

Deletes local @code{co_varnames[var_num]}.
@end deffn

@geindex MAKE_CELL (opcode)
@anchor{library/dis opcode-MAKE_CELL}@anchor{6ea}
@deffn {Opcode} MAKE_CELL (i)

Creates a new cell in slot @code{i}.  If that slot is nonempty then
that value is stored into the new cell.


Ajouté dans la version 3.11.

@end deffn

@geindex LOAD_DEREF (opcode)
@anchor{library/dis opcode-LOAD_DEREF}@anchor{4674}
@deffn {Opcode} LOAD_DEREF (i)

Loads the cell contained in slot @code{i} of the "fast locals" storage.
Pushes a reference to the object the cell contains on the stack.


Modifié dans la version 3.11: @code{i} is no longer offset by the length of @ref{1ec1,,co_varnames}.

@end deffn

@geindex LOAD_FROM_DICT_OR_DEREF (opcode)
@anchor{library/dis opcode-LOAD_FROM_DICT_OR_DEREF}@anchor{4d0}
@deffn {Opcode} LOAD_FROM_DICT_OR_DEREF (i)

Pops a mapping off the stack and looks up the name associated with
slot @code{i} of the "fast locals" storage in this mapping.
If the name is not found there, loads it from the cell contained in
slot @code{i}, similar to @ref{4674,,LOAD_DEREF}. This is used for loading
@ref{1ec4,,closure variables} in class bodies (which previously used
@code{LOAD_CLASSDEREF}) and in
@ref{186,,annotation scopes} within class bodies.


Ajouté dans la version 3.12.

@end deffn

@geindex STORE_DEREF (opcode)
@anchor{library/dis opcode-STORE_DEREF}@anchor{4675}
@deffn {Opcode} STORE_DEREF (i)

Stores @code{STACK.pop()} into the cell contained in slot @code{i} of the "fast locals"
storage.


Modifié dans la version 3.11: @code{i} is no longer offset by the length of @ref{1ec1,,co_varnames}.

@end deffn

@geindex DELETE_DEREF (opcode)
@anchor{library/dis opcode-DELETE_DEREF}@anchor{4676}
@deffn {Opcode} DELETE_DEREF (i)

Empties the cell contained in slot @code{i} of the "fast locals" storage.
Used by the @ref{1734,,del} statement.


Ajouté dans la version 3.2.



Modifié dans la version 3.11: @code{i} is no longer offset by the length of @ref{1ec1,,co_varnames}.

@end deffn

@geindex COPY_FREE_VARS (opcode)
@anchor{library/dis opcode-COPY_FREE_VARS}@anchor{6e8}
@deffn {Opcode} COPY_FREE_VARS (n)

Copies the @code{n} @ref{1ec4,,free (closure) variables} from the closure
into the frame. Removes the need for special code on the caller's side when calling
closures.


Ajouté dans la version 3.11.

@end deffn

@geindex RAISE_VARARGS (opcode)
@anchor{library/dis opcode-RAISE_VARARGS}@anchor{4677}
@deffn {Opcode} RAISE_VARARGS (argc)

Raises an exception using one of the 3 forms of the @code{raise} statement,
depending on the value of `argc':


@itemize *

@item 
0: @code{raise} (re-raise previous exception)

@item 
1: @code{raise STACK[-1]} (raise exception instance or type at @code{STACK[-1]})

@item 
2: @code{raise STACK[-2] from STACK[-1]} (raise exception instance or type at
@code{STACK[-2]} with @code{__cause__} set to @code{STACK[-1]})
@end itemize
@end deffn

@geindex CALL (opcode)
@anchor{library/dis opcode-CALL}@anchor{6f1}
@deffn {Opcode} CALL (argc)

Calls a callable object with the number of arguments specified by @code{argc}.
On the stack are (in ascending order):


@itemize *

@item 
The callable

@item 
@code{self} or @code{NULL}

@item 
The remaining positional arguments
@end itemize

@code{argc} is the total of the positional arguments, excluding @code{self}.

@code{CALL} pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.


Ajouté dans la version 3.11.



Modifié dans la version 3.13: The callable now always appears at the same position on the stack.



Modifié dans la version 3.13: Calls with keyword arguments are now handled by @ref{166d,,CALL_KW}.

@end deffn

@geindex CALL_KW (opcode)
@anchor{library/dis opcode-CALL_KW}@anchor{166d}
@deffn {Opcode} CALL_KW (argc)

Calls a callable object with the number of arguments specified by @code{argc},
including one or more named arguments. On the stack are (in ascending order):


@itemize *

@item 
The callable

@item 
@code{self} or @code{NULL}

@item 
The remaining positional arguments

@item 
The named arguments

@item 
A @ref{366,,tuple} of keyword argument names
@end itemize

@code{argc} is the total of the positional and named arguments, excluding @code{self}.
The length of the tuple of keyword argument names is the number of named arguments.

@code{CALL_KW} pops all arguments, the keyword names, and the callable object
off the stack, calls the callable object with those arguments, and pushes the
return value returned by the callable object.


Ajouté dans la version 3.13.

@end deffn

@geindex CALL_FUNCTION_EX (opcode)
@anchor{library/dis opcode-CALL_FUNCTION_EX}@anchor{d41}
@deffn {Opcode} CALL_FUNCTION_EX (flags)

Calls a callable object with variable set of positional and keyword
arguments.  If the lowest bit of `flags' is set, the top of the stack
contains a mapping object containing additional keyword arguments.
Before the callable is called, the mapping object and iterable object
are each "unpacked" and their contents passed in as keyword and
positional arguments respectively.
@code{CALL_FUNCTION_EX} pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.


Ajouté dans la version 3.6.

@end deffn

@geindex PUSH_NULL (opcode)
@anchor{library/dis opcode-PUSH_NULL}@anchor{6f2}
@deffn {Opcode} PUSH_NULL

Pushes a @code{NULL} to the stack.
Used in the call sequence to match the @code{NULL} pushed by
@ref{c0d,,LOAD_METHOD} for non-method calls.


Ajouté dans la version 3.11.

@end deffn

@geindex MAKE_FUNCTION (opcode)
@anchor{library/dis opcode-MAKE_FUNCTION}@anchor{d40}
@deffn {Opcode} MAKE_FUNCTION

Pushes a new function object on the stack built from the code object at @code{STACK[-1]}.


Modifié dans la version 3.10: Flag value @code{0x04} is a tuple of strings instead of dictionary



Modifié dans la version 3.11: Qualified name at @code{STACK[-1]} was removed.



Modifié dans la version 3.13: Extra function attributes on the stack, signaled by oparg flags, were
removed. They now use @ref{4678,,SET_FUNCTION_ATTRIBUTE}.

@end deffn

@geindex SET_FUNCTION_ATTRIBUTE (opcode)
@anchor{library/dis opcode-SET_FUNCTION_ATTRIBUTE}@anchor{4678}
@deffn {Opcode} SET_FUNCTION_ATTRIBUTE (flag)

Sets an attribute on a function object. Expects the function at @code{STACK[-1]}
and the attribute value to set at @code{STACK[-2]}; consumes both and leaves the
function at @code{STACK[-1]}. The flag determines which attribute to set:


@itemize *

@item 
@code{0x01} a tuple of default values for positional-only and
positional-or-keyword parameters in positional order

@item 
@code{0x02} a dictionary of keyword-only parameters' default values

@item 
@code{0x04} a tuple of strings containing parameters' annotations

@item 
@code{0x08} a tuple containing cells for free variables, making a closure
@end itemize


Ajouté dans la version 3.13.

@end deffn

@geindex BUILD_SLICE (opcode)
@anchor{library/dis opcode-BUILD_SLICE}@anchor{4679}
@deffn {Opcode} BUILD_SLICE (argc)

@geindex built-in function;slice

Pushes a slice object on the stack.  `argc' must be 2 or 3.  If it is 2, implements:

@example
end = STACK.pop()
start = STACK.pop()
STACK.append(slice(start, end))
@end example

if it is 3, implements:

@example
step = STACK.pop()
end = STACK.pop()
start = STACK.pop()
STACK.append(slice(start, end, step))
@end example

See the @ref{453,,slice()} built-in function for more information.
@end deffn

@geindex EXTENDED_ARG (opcode)
@anchor{library/dis opcode-EXTENDED_ARG}@anchor{1733}
@deffn {Opcode} EXTENDED_ARG (ext)

Prefixes any opcode which has an argument too big to fit into the default one
byte. `ext' holds an additional byte which act as higher bits in the argument.
For each opcode, at most three prefixal @code{EXTENDED_ARG} are allowed, forming
an argument from two-byte to four-byte.
@end deffn

@geindex CONVERT_VALUE (opcode)
@anchor{library/dis opcode-CONVERT_VALUE}@anchor{467a}
@deffn {Opcode} CONVERT_VALUE (oparg)

Convert value to a string, depending on @code{oparg}:

@example
value = STACK.pop()
result = func(value)
STACK.append(result)
@end example


@itemize *

@item 
@code{oparg == 1}: call @ref{435,,str()} on `value'

@item 
@code{oparg == 2}: call @ref{7e7,,repr()} on `value'

@item 
@code{oparg == 3}: call @ref{139d,,ascii()} on `value'
@end itemize

Used for implementing formatted literal strings (f-strings).


Ajouté dans la version 3.13.

@end deffn

@geindex FORMAT_SIMPLE (opcode)
@anchor{library/dis opcode-FORMAT_SIMPLE}@anchor{467b}
@deffn {Opcode} FORMAT_SIMPLE

Formats the value on top of stack:

@example
value = STACK.pop()
result = value.__format__("")
STACK.append(result)
@end example

Used for implementing formatted literal strings (f-strings).


Ajouté dans la version 3.13.

@end deffn

@geindex FORMAT_WITH_SPEC (opcode)
@anchor{library/dis opcode-FORMAT_WITH_SPEC}@anchor{467c}
@deffn {Opcode} FORMAT_WITH_SPEC

Formats the given value with the given format spec:

@example
spec = STACK.pop()
value = STACK.pop()
result = value.__format__(spec)
STACK.append(result)
@end example

Used for implementing formatted literal strings (f-strings).


Ajouté dans la version 3.13.

@end deffn

@geindex MATCH_CLASS (opcode)
@anchor{library/dis opcode-MATCH_CLASS}@anchor{6fc}
@deffn {Opcode} MATCH_CLASS (count)

@code{STACK[-1]} is a tuple of keyword attribute names, @code{STACK[-2]} is the class
being matched against, and @code{STACK[-3]} is the match subject.  `count' is the
number of positional sub-patterns.

Pop @code{STACK[-1]}, @code{STACK[-2]}, and @code{STACK[-3]}. If @code{STACK[-3]} is an
instance of @code{STACK[-2]} and has the positional and keyword attributes
required by `count' and @code{STACK[-1]}, push a tuple of extracted attributes.
Otherwise, push @code{None}.


Ajouté dans la version 3.10.



Modifié dans la version 3.11: Previously, this instruction also pushed a boolean value indicating
success (@code{True}) or failure (@code{False}).

@end deffn

@geindex RESUME (opcode)
@anchor{library/dis opcode-RESUME}@anchor{30a}
@deffn {Opcode} RESUME (context)

A no-op. Performs internal tracing, debugging and optimization checks.

The @code{context} oparand consists of two parts. The lowest two bits
indicate where the @code{RESUME} occurs:


@itemize *

@item 
@code{0} The start of a function, which is neither a generator, coroutine
nor an async generator

@item 
@code{1} After a @code{yield} expression

@item 
@code{2} After a @code{yield from} expression

@item 
@code{3} After an @code{await} expression
@end itemize

The next bit is @code{1} if the RESUME is at except-depth @code{1}, and @code{0}
otherwise.


Ajouté dans la version 3.11.



Modifié dans la version 3.13: The oparg value changed to include information about except-depth

@end deffn

@geindex RETURN_GENERATOR (opcode)
@anchor{library/dis opcode-RETURN_GENERATOR}@anchor{6e6}
@deffn {Opcode} RETURN_GENERATOR

Create a generator, coroutine, or async generator from the current frame.
Used as first opcode of in code object for the above mentioned callables.
Clear the current frame and return the newly created generator.


Ajouté dans la version 3.11.

@end deffn

@geindex SEND (opcode)
@anchor{library/dis opcode-SEND}@anchor{6e7}
@deffn {Opcode} SEND (delta)

Equivalent to @code{STACK[-1] = STACK[-2].send(STACK[-1])}. Used in @code{yield from}
and @code{await} statements.

If the call raises @ref{be8,,StopIteration}, pop the top value from the stack,
push the exception's @code{value} attribute, and increment the bytecode counter
by `delta'.


Ajouté dans la version 3.11.

@end deffn

@geindex HAVE_ARGUMENT (opcode)
@anchor{library/dis opcode-HAVE_ARGUMENT}@anchor{473}
@deffn {Opcode} HAVE_ARGUMENT

This is not really an opcode.  It identifies the dividing line between
opcodes in the range [0,255] which don't use their argument and those
that do (@code{< HAVE_ARGUMENT} and @code{>= HAVE_ARGUMENT}, respectively).

If your application uses pseudo instructions or specialized instructions,
use the @ref{29b,,hasarg} collection instead.


Modifié dans la version 3.6: Now every instruction has an argument, but opcodes @code{< HAVE_ARGUMENT}
ignore it. Before, only opcodes @code{>= HAVE_ARGUMENT} had an argument.



Modifié dans la version 3.12: Pseudo instructions were added to the @ref{38,,dis} module, and for them
it is not true that comparison with @code{HAVE_ARGUMENT} indicates whether
they use their arg.



Obsolète depuis la version 3.13: Use @ref{29b,,hasarg} instead.

@end deffn

@geindex CALL_INTRINSIC_1 (opcode)
@anchor{library/dis opcode-CALL_INTRINSIC_1}@anchor{4cb}
@deffn {Opcode} CALL_INTRINSIC_1

Calls an intrinsic function with one argument. Passes @code{STACK[-1]} as the
argument and sets @code{STACK[-1]} to the result. Used to implement
functionality that is not performance critical.

The operand determines which intrinsic function is called:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operand

@tab

Description

@item

@code{INTRINSIC_1_INVALID}

@tab

Not valid

@item

@code{INTRINSIC_PRINT}

@tab

Prints the argument to standard
out. Used in the REPL.

@item

@code{INTRINSIC_IMPORT_STAR}

@tab

Performs @code{import *} for the
named module.

@item

@code{INTRINSIC_STOPITERATION_ERROR}

@tab

Extracts the return value from a
@code{StopIteration} exception.

@item

@code{INTRINSIC_ASYNC_GEN_WRAP}

@tab

Wraps an async generator value

@item

@code{INTRINSIC_UNARY_POSITIVE}

@tab

Performs the unary @code{+}
operation

@item

@code{INTRINSIC_LIST_TO_TUPLE}

@tab

Converts a list to a tuple

@item

@code{INTRINSIC_TYPEVAR}

@tab

Creates a @ref{15c,,typing.TypeVar}

@item

@code{INTRINSIC_PARAMSPEC}

@tab

Creates a
@ref{15d,,typing.ParamSpec}

@item

@code{INTRINSIC_TYPEVARTUPLE}

@tab

Creates a
@ref{15e,,typing.TypeVarTuple}

@item

@code{INTRINSIC_SUBSCRIPT_GENERIC}

@tab

Returns @ref{15a1,,typing.Generic}
subscripted with the argument

@item

@code{INTRINSIC_TYPEALIAS}

@tab

Creates a
@ref{43e,,typing.TypeAliasType};
used in the @ref{421,,type}
statement. The argument is a tuple
of the type alias's name,
type parameters, and value.

@end multitable



Ajouté dans la version 3.12.

@end deffn

@geindex CALL_INTRINSIC_2 (opcode)
@anchor{library/dis opcode-CALL_INTRINSIC_2}@anchor{4cc}
@deffn {Opcode} CALL_INTRINSIC_2

Calls an intrinsic function with two arguments. Used to implement functionality
that is not performance critical:

@example
arg2 = STACK.pop()
arg1 = STACK.pop()
result = intrinsic2(arg1, arg2)
STACK.append(result)
@end example

The operand determines which intrinsic function is called:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Operand

@tab

Description

@item

@code{INTRINSIC_2_INVALID}

@tab

Not valid

@item

@code{INTRINSIC_PREP_RERAISE_STAR}

@tab

Calculates the
@ref{1b4,,ExceptionGroup} to raise
from a @code{try-except*}.

@item

@code{INTRINSIC_TYPEVAR_WITH_BOUND}

@tab

Creates a @ref{15c,,typing.TypeVar}
with a bound.

@item

@code{INTRINSIC_TYPEVAR_WITH_CONSTRAINTS}

@tab

Creates a
@ref{15c,,typing.TypeVar} with
constraints.

@item

@code{INTRINSIC_SET_FUNCTION_TYPE_PARAMS}

@tab

Sets the @code{__type_params__}
attribute of a function.

@end multitable



Ajouté dans la version 3.12.

@end deffn

`Pseudo-instructions'

These opcodes do not appear in Python bytecode. They are used by the compiler
but are replaced by real opcodes or removed before bytecode is generated.

@geindex SETUP_FINALLY (opcode)
@anchor{library/dis opcode-SETUP_FINALLY}@anchor{467d}
@deffn {Opcode} SETUP_FINALLY (target)

Set up an exception handler for the following code block. If an exception
occurs, the value stack level is restored to its current state and control
is transferred to the exception handler at @code{target}.
@end deffn

@geindex SETUP_CLEANUP (opcode)
@anchor{library/dis opcode-SETUP_CLEANUP}@anchor{467e}
@deffn {Opcode} SETUP_CLEANUP (target)

Like @code{SETUP_FINALLY}, but in case of an exception also pushes the last
instruction (@code{lasti}) to the stack so that @code{RERAISE} can restore it.
If an exception occurs, the value stack level and the last instruction on
the frame are restored to their current state, and control is transferred
to the exception handler at @code{target}.
@end deffn

@geindex SETUP_WITH (opcode)
@anchor{library/dis opcode-SETUP_WITH}@anchor{467f}
@deffn {Opcode} SETUP_WITH (target)

Like @code{SETUP_CLEANUP}, but in case of an exception one more item is popped
from the stack before control is transferred to the exception handler at
@code{target}.

This variant is used in @ref{5bc,,with} and @ref{5bf,,async with}
constructs, which push the return value of the context manager's
@ref{5b2,,__enter__()} or @ref{1f53,,__aenter__()} to the stack.
@end deffn

@geindex POP_BLOCK (opcode)
@anchor{library/dis opcode-POP_BLOCK}@anchor{4680}
@deffn {Opcode} POP_BLOCK

Marks the end of the code block associated with the last @code{SETUP_FINALLY},
@code{SETUP_CLEANUP} or @code{SETUP_WITH}.
@end deffn

@geindex JUMP (opcode)
@anchor{library/dis opcode-JUMP}@anchor{4681}
@deffn {Opcode} JUMP
@end deffn

@geindex JUMP_NO_INTERRUPT (opcode)
@anchor{library/dis opcode-JUMP_NO_INTERRUPT}@anchor{17a7}
@deffn {Opcode} JUMP_NO_INTERRUPT

Undirected relative jump instructions which are replaced by their
directed (forward/backward) counterparts by the assembler.
@end deffn

@geindex LOAD_CLOSURE (opcode)
@anchor{library/dis opcode-LOAD_CLOSURE}@anchor{1675}
@deffn {Opcode} LOAD_CLOSURE (i)

Pushes a reference to the cell contained in slot @code{i} of the "fast locals"
storage.

Note that @code{LOAD_CLOSURE} is replaced with @code{LOAD_FAST} in the assembler.


Modifié dans la version 3.13: This opcode is now a pseudo-instruction.

@end deffn

@geindex LOAD_METHOD (opcode)
@anchor{library/dis opcode-LOAD_METHOD}@anchor{c0d}
@deffn {Opcode} LOAD_METHOD

Optimized unbound method lookup. Emitted as a @code{LOAD_ATTR} opcode
with a flag set in the arg.
@end deffn

@node Opcode collections,,Les instructions du code intermédiaire en Python,dis --- Disassembler for Python bytecode
@anchor{library/dis id1}@anchor{4682}@anchor{library/dis opcode-collections}@anchor{4631}
@subsubsection Opcode collections


These collections are provided for automatic introspection of bytecode
instructions:


Modifié dans la version 3.12: The collections now contain pseudo instructions and instrumented
instructions as well. These are opcodes with values @code{>= MIN_PSEUDO_OPCODE}
and @code{>= MIN_INSTRUMENTED_OPCODE}.


@geindex opname (dans le module dis)
@anchor{library/dis dis opname}@anchor{4635}
@deffn {Données} dis.opname

Sequence of operation names, indexable using the bytecode.
@end deffn

@geindex opmap (dans le module dis)
@anchor{library/dis dis opmap}@anchor{4683}
@deffn {Données} dis.opmap

Dictionary mapping operation names to bytecodes.
@end deffn

@geindex cmp_op (dans le module dis)
@anchor{library/dis dis cmp_op}@anchor{4684}
@deffn {Données} dis.cmp_op

Sequence of all compare operation names.
@end deffn

@geindex hasarg (dans le module dis)
@anchor{library/dis dis hasarg}@anchor{29b}
@deffn {Données} dis.hasarg

Sequence of bytecodes that use their argument.


Ajouté dans la version 3.12.

@end deffn

@geindex hasconst (dans le module dis)
@anchor{library/dis dis hasconst}@anchor{4685}
@deffn {Données} dis.hasconst

Sequence of bytecodes that access a constant.
@end deffn

@geindex hasfree (dans le module dis)
@anchor{library/dis dis hasfree}@anchor{4686}
@deffn {Données} dis.hasfree

Sequence of bytecodes that access a @ref{1ec4,,free (closure) variable}.
'free' in this context refers to names in the current scope that are
referenced by inner scopes or names in outer scopes that are referenced
from this scope.  It does `not' include references to global or builtin scopes.
@end deffn

@geindex hasname (dans le module dis)
@anchor{library/dis dis hasname}@anchor{4687}
@deffn {Données} dis.hasname

Sequence of bytecodes that access an attribute by name.
@end deffn

@geindex hasjump (dans le module dis)
@anchor{library/dis dis hasjump}@anchor{4688}
@deffn {Données} dis.hasjump

Sequence of bytecodes that have a jump target. All jumps
are relative.


Ajouté dans la version 3.13.

@end deffn

@geindex haslocal (dans le module dis)
@anchor{library/dis dis haslocal}@anchor{4689}
@deffn {Données} dis.haslocal

Sequence of bytecodes that access a local variable.
@end deffn

@geindex hascompare (dans le module dis)
@anchor{library/dis dis hascompare}@anchor{468a}
@deffn {Données} dis.hascompare

Sequence of bytecodes of Boolean operations.
@end deffn

@geindex hasexc (dans le module dis)
@anchor{library/dis dis hasexc}@anchor{474}
@deffn {Données} dis.hasexc

Sequence of bytecodes that set an exception handler.


Ajouté dans la version 3.12.

@end deffn

@geindex hasjrel (dans le module dis)
@anchor{library/dis dis hasjrel}@anchor{468b}
@deffn {Données} dis.hasjrel

Sequence of bytecodes that have a relative jump target.


Obsolète depuis la version 3.13: All jumps are now relative. Use @ref{4688,,hasjump}.

@end deffn

@geindex hasjabs (dans le module dis)
@anchor{library/dis dis hasjabs}@anchor{468c}
@deffn {Données} dis.hasjabs

Sequence of bytecodes that have an absolute jump target.


Obsolète depuis la version 3.13: All jumps are now relative. This list is empty.

@end deffn

@node pickletools --- Tools for pickle developers,,dis --- Disassembler for Python bytecode,Services du Langage Python
@anchor{library/pickletools doc}@anchor{468d}@anchor{library/pickletools module-pickletools}@anchor{a6}@anchor{library/pickletools pickletools-tools-for-pickle-developers}@anchor{468e}
@subsection @code{pickletools} --- Tools for pickle developers


@geindex module; pickletools

`Source code:' Lib/pickletools.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pickletools.py}


__________________________________________________________________


This module contains various constants relating to the intimate details of the
@ref{a5,,pickle} module, some lengthy comments about the implementation, and a
few useful functions for analyzing pickled data.  The contents of this module
are useful for Python core developers who are working on the @ref{a5,,pickle};
ordinary users of the @ref{a5,,pickle} module probably won't find the
@ref{a6,,pickletools} module relevant.

@menu
* Utilisation de la ligne de commande: Utilisation de la ligne de commande<2>. 
* Programmatic Interface: Programmatic Interface<2>. 

@end menu

@node Utilisation de la ligne de commande<2>,Programmatic Interface<2>,,pickletools --- Tools for pickle developers
@anchor{library/pickletools command-line-usage}@anchor{468f}@anchor{library/pickletools pickletools-cli}@anchor{4690}
@subsubsection Utilisation de la ligne de commande



Ajouté dans la version 3.2.


When invoked from the command line, @code{python -m pickletools} will
disassemble the contents of one or more pickle files.  Note that if
you want to see the Python object stored in the pickle rather than the
details of pickle format, you may want to use @code{-m pickle} instead.
However, when the pickle file that you want to examine comes from an
untrusted source, @code{-m pickletools} is a safer option because it does
not execute pickle bytecode.

For example, with a tuple @code{(1, 2)} pickled in file @code{x.pickle}:

@example
$ python -m pickle x.pickle
(1, 2)

$ python -m pickletools x.pickle
    0: \x80 PROTO      3
    2: K    BININT1    1
    4: K    BININT1    2
    6: \x86 TUPLE2
    7: q    BINPUT     0
    9: .    STOP
highest protocol among opcodes = 2
@end example

@menu
* Options de la ligne de commande: Options de la ligne de commande<6>. 

@end menu

@node Options de la ligne de commande<6>,,,Utilisation de la ligne de commande<2>
@anchor{library/pickletools command-line-options}@anchor{4691}
@subsubsection Options de la ligne de commande


@geindex option de ligne de commande pickletools; -a
@geindex option de ligne de commande pickletools; --annotate
@anchor{library/pickletools cmdoption-pickletools-a}@anchor{4692}@anchor{library/pickletools cmdoption-pickletools-annotate}@anchor{4693}
@deffn {Option} @w{-}a, @w{-}@w{-}annotate

Annotate each line with a short opcode description.
@end deffn

@geindex option de ligne de commande pickletools; -o
@geindex option de ligne de commande pickletools; --output
@anchor{library/pickletools cmdoption-pickletools-o}@anchor{4694}@anchor{library/pickletools cmdoption-pickletools-output}@anchor{4695}
@deffn {Option} @w{-}o, @w{-}@w{-}output=<file>

Name of a file where the output should be written.
@end deffn

@geindex option de ligne de commande pickletools; -l
@geindex option de ligne de commande pickletools; --indentlevel
@anchor{library/pickletools cmdoption-pickletools-l}@anchor{4696}@anchor{library/pickletools cmdoption-pickletools-indentlevel}@anchor{4697}
@deffn {Option} @w{-}l, @w{-}@w{-}indentlevel=<num>

The number of blanks by which to indent a new MARK level.
@end deffn

@geindex option de ligne de commande pickletools; -m
@geindex option de ligne de commande pickletools; --memo
@anchor{library/pickletools cmdoption-pickletools-m}@anchor{4698}@anchor{library/pickletools cmdoption-pickletools-memo}@anchor{4699}
@deffn {Option} @w{-}m, @w{-}@w{-}memo

When multiple objects are disassembled, preserve memo between
disassemblies.
@end deffn

@geindex option de ligne de commande pickletools; -p
@geindex option de ligne de commande pickletools; --preamble
@anchor{library/pickletools cmdoption-pickletools-p}@anchor{469a}@anchor{library/pickletools cmdoption-pickletools-preamble}@anchor{469b}
@deffn {Option} @w{-}p, @w{-}@w{-}preamble=<preamble>

When more than one pickle file are specified, print given preamble
before each disassembly.
@end deffn

@node Programmatic Interface<2>,,Utilisation de la ligne de commande<2>,pickletools --- Tools for pickle developers
@anchor{library/pickletools programmatic-interface}@anchor{469c}
@subsubsection Programmatic Interface


@geindex dis() (dans le module pickletools)
@anchor{library/pickletools pickletools dis}@anchor{cb1}
@deffn {Fonction} pickletools.dis (pickle, out=None, memo=None, indentlevel=4, annotate=0)

Outputs a symbolic disassembly of the pickle to the file-like
object `out', defaulting to @code{sys.stdout}.  `pickle' can be a
string or a file-like object.  `memo' can be a Python dictionary
that will be used as the pickle's memo; it can be used to perform
disassemblies across multiple pickles created by the same
pickler. Successive levels, indicated by @code{MARK} opcodes in the
stream, are indented by `indentlevel' spaces.  If a nonzero value
is given to `annotate', each opcode in the output is annotated with
a short description.  The value of `annotate' is used as a hint for
the column where annotation should start.


Modifié dans la version 3.2: Added the `annotate' parameter.

@end deffn

@geindex genops() (dans le module pickletools)
@anchor{library/pickletools pickletools genops}@anchor{469d}
@deffn {Fonction} pickletools.genops (pickle)

Provides an @ref{1aa,,iterator} over all of the opcodes in a pickle, returning a
sequence of @code{(opcode, arg, pos)} triples.  `opcode' is an instance of an
@code{OpcodeInfo} class; `arg' is the decoded value, as a Python object, of
the opcode's argument; `pos' is the position at which this opcode is located.
`pickle' can be a string or a file-like object.
@end deffn

@geindex optimize() (dans le module pickletools)
@anchor{library/pickletools pickletools optimize}@anchor{2816}
@deffn {Fonction} pickletools.optimize (picklestring)

Returns a new equivalent pickle string after eliminating unused @code{PUT}
opcodes. The optimized pickle is shorter, takes less transmission time,
requires less storage space, and unpickles more efficiently.
@end deffn

@node Services spécifiques à MS Windows,Services spécifiques à Unix,Services du Langage Python,La bibliothèque standard
@anchor{library/windows doc}@anchor{469e}@anchor{library/windows ms-windows-specific-services}@anchor{469f}@anchor{library/windows mswin-specific-services}@anchor{1dbe}
@section Services spécifiques à MS Windows


Ce chapitre documente les modules qui ne sont disponibles que sous MS Windows.

@menu
* msvcrt: msvcrt --- Useful routines from the MS VC++ runtime. Useful routines from the MS VC++ runtime
* winreg: winreg --- Windows registry access. Windows registry access
* winsound: winsound --- Sound-playing interface for Windows. Sound-playing interface for Windows

@end menu

@node msvcrt --- Useful routines from the MS VC++ runtime,winreg --- Windows registry access,,Services spécifiques à MS Windows
@anchor{library/msvcrt doc}@anchor{46a0}@anchor{library/msvcrt module-msvcrt}@anchor{92}@anchor{library/msvcrt msvcrt-useful-routines-from-the-ms-vc-runtime}@anchor{46a1}
@subsection @code{msvcrt} --- Useful routines from the MS VC++ runtime


@geindex module; msvcrt


__________________________________________________________________


These functions provide access to some useful capabilities on Windows platforms.
Some higher-level modules use these functions to build the Windows
implementations of their services. For example, the @ref{61,,getpass} module uses
this in the implementation of the @ref{61,,getpass()} function.

Further documentation on these functions can be found in the Platform API
documentation.

The module implements both the normal and wide char variants of the console I/O
api. The normal API deals only with ASCII characters and is of limited use
for internationalized applications. The wide char API should be used where
ever possible.


Modifié dans la version 3.3: Les opérations de ce module lèvent désormais @ref{40d,,OSError} au lieu de @ref{103b,,IOError}.


@menu
* Opérations sur les fichiers:: 
* Entrées-sorties sur un terminal:: 
* Autres fonctions: Autres fonctions<4>. 

@end menu

@node Opérations sur les fichiers,Entrées-sorties sur un terminal,,msvcrt --- Useful routines from the MS VC++ runtime
@anchor{library/msvcrt file-operations}@anchor{46a2}@anchor{library/msvcrt msvcrt-files}@anchor{46a3}
@subsubsection Opérations sur les fichiers


@geindex locking() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt locking}@anchor{4118}
@deffn {Fonction} msvcrt.locking (fd, mode, nbytes)

Lock part of a file based on file descriptor `fd' from the C runtime. Raises
@ref{40d,,OSError} on failure. The locked region of the file extends from the
current file position for `nbytes' bytes, and may continue beyond the end of the
file. `mode' must be one of the @code{LK_*} constants listed below. Multiple
regions in a file may be locked at the same time, but may not overlap. Adjacent
regions are not merged; they must be unlocked individually.

Raises an @ref{1848,,auditing event} @code{msvcrt.locking} with arguments @code{fd}, @code{mode}, @code{nbytes}.
@end deffn

@geindex LK_LOCK (dans le module msvcrt)
@geindex LK_RLCK (dans le module msvcrt)
@anchor{library/msvcrt msvcrt LK_LOCK}@anchor{46a4}
@deffn {Données} msvcrt.LK_LOCK
@anchor{library/msvcrt msvcrt LK_RLCK}@anchor{46a5}
@deffnx {Données} msvcrt.LK_RLCK

Locks the specified bytes. If the bytes cannot be locked, the program
immediately tries again after 1 second. If, after 10 attempts, the bytes cannot
be locked, @ref{40d,,OSError} is raised.
@end deffn

@geindex LK_NBLCK (dans le module msvcrt)
@geindex LK_NBRLCK (dans le module msvcrt)
@anchor{library/msvcrt msvcrt LK_NBLCK}@anchor{46a6}
@deffn {Données} msvcrt.LK_NBLCK
@anchor{library/msvcrt msvcrt LK_NBRLCK}@anchor{46a7}
@deffnx {Données} msvcrt.LK_NBRLCK

Verrouille les octets spécifiés. Si les octets ne peuvent pas être verrouillés, @ref{40d,,OSError} est levée.
@end deffn

@geindex LK_UNLCK (dans le module msvcrt)
@anchor{library/msvcrt msvcrt LK_UNLCK}@anchor{46a8}
@deffn {Données} msvcrt.LK_UNLCK

Déverrouille les octets spécifiés, qui doivent avoir été précédemment verrouillés.
@end deffn

@geindex setmode() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt setmode}@anchor{46a9}
@deffn {Fonction} msvcrt.setmode (fd, flags)

Set the line-end translation mode for the file descriptor `fd'. To set it to
text mode, `flags' should be @ref{2add,,os.O_TEXT}; for binary, it should be
@ref{2ace,,os.O_BINARY}.
@end deffn

@geindex open_osfhandle() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt open_osfhandle}@anchor{4119}
@deffn {Fonction} msvcrt.open_osfhandle (handle, flags)

Create a C runtime file descriptor from the file handle `handle'. The `flags'
parameter should be a bitwise OR of @ref{2ad0,,os.O_APPEND},
@ref{2acc,,os.O_RDONLY}, @ref{2add,,os.O_TEXT} and @ref{2ad8,,os.O_NOINHERIT}.
The returned file descriptor may be used as a parameter
to @ref{1eb7,,os.fdopen()} to create a file object.

The file descriptor is inheritable by default. Pass @ref{2ad8,,os.O_NOINHERIT}
flag to make it non inheritable.

Raises an @ref{1848,,auditing event} @code{msvcrt.open_osfhandle} with arguments @code{handle}, @code{flags}.
@end deffn

@geindex get_osfhandle() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt get_osfhandle}@anchor{4117}
@deffn {Fonction} msvcrt.get_osfhandle (fd)

Return the file handle for the file descriptor `fd'. Raises @ref{40d,,OSError} if
`fd' is not recognized.

Raises an @ref{1848,,auditing event} @code{msvcrt.get_osfhandle} with argument @code{fd}.
@end deffn

@node Entrées-sorties sur un terminal,Autres fonctions<4>,Opérations sur les fichiers,msvcrt --- Useful routines from the MS VC++ runtime
@anchor{library/msvcrt console-i-o}@anchor{46aa}@anchor{library/msvcrt msvcrt-console}@anchor{46ab}
@subsubsection Entrées-sorties sur un terminal


@geindex kbhit() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt kbhit}@anchor{46ac}
@deffn {Fonction} msvcrt.kbhit ()

Returns a nonzero value if a keypress is waiting to be read. Otherwise,
return 0.
@end deffn

@geindex getch() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt getch}@anchor{46ad}
@deffn {Fonction} msvcrt.getch ()

Read a keypress and return the resulting character as a byte string.
Nothing is echoed to the console. This call will block if a keypress
is not already available, but will not wait for @code{Enter} to be
pressed. If the pressed key was a special function key, this will
return @code{'\000'} or @code{'\xe0'}; the next call will return the keycode.
The @code{Control-C} keypress cannot be read with this function.
@end deffn

@geindex getwch() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt getwch}@anchor{13ac}
@deffn {Fonction} msvcrt.getwch ()

Variante de @ref{46ad,,getch()} qui lit un caractère large et renvoie une valeur Unicode.
@end deffn

@geindex getche() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt getche}@anchor{46ae}
@deffn {Fonction} msvcrt.getche ()

Similar to @ref{46ad,,getch()}, but the keypress will be echoed if it represents a
printable character.
@end deffn

@geindex getwche() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt getwche}@anchor{13ad}
@deffn {Fonction} msvcrt.getwche ()

Variante de @ref{46ae,,getche()} qui lit un caractère large et renvoie une valeur Unicode.
@end deffn

@geindex putch() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt putch}@anchor{46af}
@deffn {Fonction} msvcrt.putch (char)

Print the byte string `char' to the console without buffering.
@end deffn

@geindex putwch() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt putwch}@anchor{13ae}
@deffn {Fonction} msvcrt.putwch (unicode_char)

Variante de @ref{46af,,putch()} qui accepte une valeur Unicode et l'écrit comme caractère large.
@end deffn

@geindex ungetch() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt ungetch}@anchor{46b0}
@deffn {Fonction} msvcrt.ungetch (char)

Cause the byte string `char' to be "pushed back" into the console buffer;
it will be the next character read by @ref{46ad,,getch()} or @ref{46ae,,getche()}.
@end deffn

@geindex ungetwch() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt ungetwch}@anchor{46b1}
@deffn {Fonction} msvcrt.ungetwch (unicode_char)

Variante de @ref{46b0,,ungetch()} qui accepte une valeur Unicode et l'écrit comme caractère large.
@end deffn

@node Autres fonctions<4>,,Entrées-sorties sur un terminal,msvcrt --- Useful routines from the MS VC++ runtime
@anchor{library/msvcrt msvcrt-other}@anchor{46b2}@anchor{library/msvcrt other-functions}@anchor{46b3}
@subsubsection Autres fonctions


@geindex heapmin() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt heapmin}@anchor{46b4}
@deffn {Fonction} msvcrt.heapmin ()

Force the @code{malloc()} heap to clean itself up and return unused blocks to
the operating system. On failure, this raises @ref{40d,,OSError}.
@end deffn

@geindex set_error_mode() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt set_error_mode}@anchor{46b5}
@deffn {Fonction} msvcrt.set_error_mode (mode)

Changes the location where the C runtime writes an error message for an error
that might end the program. `mode' must be one of the @code{OUT_*}
constants listed below  or @ref{46b6,,REPORT_ERRMODE}. Returns the old setting
or -1 if an error occurs. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex OUT_TO_DEFAULT (dans le module msvcrt)
@anchor{library/msvcrt msvcrt OUT_TO_DEFAULT}@anchor{46b7}
@deffn {Données} msvcrt.OUT_TO_DEFAULT

Error sink is determined by the app's type. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex OUT_TO_STDERR (dans le module msvcrt)
@anchor{library/msvcrt msvcrt OUT_TO_STDERR}@anchor{46b8}
@deffn {Données} msvcrt.OUT_TO_STDERR

Error sink is a standard error. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex OUT_TO_MSGBOX (dans le module msvcrt)
@anchor{library/msvcrt msvcrt OUT_TO_MSGBOX}@anchor{46b9}
@deffn {Données} msvcrt.OUT_TO_MSGBOX

Error sink is a message box. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex REPORT_ERRMODE (dans le module msvcrt)
@anchor{library/msvcrt msvcrt REPORT_ERRMODE}@anchor{46b6}
@deffn {Données} msvcrt.REPORT_ERRMODE

Report the current error mode value. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex CrtSetReportMode() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CrtSetReportMode}@anchor{46ba}
@deffn {Fonction} msvcrt.CrtSetReportMode (type, mode)

Specifies the destination or destinations for a specific report type
generated by @code{_CrtDbgReport()} in the MS VC++ runtime. `type' must be
one of the @code{CRT_*} constants listed below. `mode' must be one of the
@code{CRTDBG_*} constants listed below. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex CrtSetReportFile() (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CrtSetReportFile}@anchor{46bb}
@deffn {Fonction} msvcrt.CrtSetReportFile (type, file)

After you use @ref{46ba,,CrtSetReportMode()} to specify @ref{46bc,,CRTDBG_MODE_FILE},
you can specify the file handle to receive the message text. `type' must be
one of the @code{CRT_*} constants listed below. `file' should be the file
handle your want specified. Only available in
@ref{1f6,,debug build of Python}.
@end deffn

@geindex CRT_WARN (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRT_WARN}@anchor{46bd}
@deffn {Données} msvcrt.CRT_WARN

Warnings, messages, and information that doesn't need immediate attention.
@end deffn

@geindex CRT_ERROR (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRT_ERROR}@anchor{46be}
@deffn {Données} msvcrt.CRT_ERROR

Errors, unrecoverable problems, and issues that require immediate attention.
@end deffn

@geindex CRT_ASSERT (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRT_ASSERT}@anchor{46bf}
@deffn {Données} msvcrt.CRT_ASSERT

Assertion failures.
@end deffn

@geindex CRTDBG_MODE_DEBUG (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_DEBUG}@anchor{46c0}
@deffn {Données} msvcrt.CRTDBG_MODE_DEBUG

Writes the message to the debugger's output window.
@end deffn

@geindex CRTDBG_MODE_FILE (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_FILE}@anchor{46bc}
@deffn {Données} msvcrt.CRTDBG_MODE_FILE

Writes the message to a user-supplied file handle. @ref{46bb,,CrtSetReportFile()}
should be called to define the specific file or stream to use as
the destination.
@end deffn

@geindex CRTDBG_MODE_WNDW (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_MODE_WNDW}@anchor{46c1}
@deffn {Données} msvcrt.CRTDBG_MODE_WNDW

Creates a message box to display the message along with the @code{Abort},
@code{Retry}, and @code{Ignore} buttons.
@end deffn

@geindex CRTDBG_REPORT_MODE (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRTDBG_REPORT_MODE}@anchor{46c2}
@deffn {Données} msvcrt.CRTDBG_REPORT_MODE

Returns current `mode' for the specified `type'.
@end deffn

@geindex CRT_ASSEMBLY_VERSION (dans le module msvcrt)
@anchor{library/msvcrt msvcrt CRT_ASSEMBLY_VERSION}@anchor{1336}
@deffn {Données} msvcrt.CRT_ASSEMBLY_VERSION

The CRT Assembly version, from the @code{crtassem.h} header file.
@end deffn

@geindex VC_ASSEMBLY_PUBLICKEYTOKEN (dans le module msvcrt)
@anchor{library/msvcrt msvcrt VC_ASSEMBLY_PUBLICKEYTOKEN}@anchor{1337}
@deffn {Données} msvcrt.VC_ASSEMBLY_PUBLICKEYTOKEN

The VC Assembly public key token, from the @code{crtassem.h} header file.
@end deffn

@geindex LIBRARIES_ASSEMBLY_NAME_PREFIX (dans le module msvcrt)
@anchor{library/msvcrt msvcrt LIBRARIES_ASSEMBLY_NAME_PREFIX}@anchor{1338}
@deffn {Données} msvcrt.LIBRARIES_ASSEMBLY_NAME_PREFIX

The Libraries Assembly name prefix, from the @code{crtassem.h} header file.
@end deffn

@node winreg --- Windows registry access,winsound --- Sound-playing interface for Windows,msvcrt --- Useful routines from the MS VC++ runtime,Services spécifiques à MS Windows
@anchor{library/winreg doc}@anchor{46c3}@anchor{library/winreg module-winreg}@anchor{115}@anchor{library/winreg winreg-windows-registry-access}@anchor{46c4}
@subsection @code{winreg} --- Windows registry access


@geindex module; winreg


__________________________________________________________________


These functions expose the Windows registry API to Python.  Instead of using an
integer as the registry handle, a @ref{46c5,,handle object} is used
to ensure that the handles are closed correctly, even if the programmer neglects
to explicitly close them.
@anchor{library/winreg exception-changed}@anchor{46c6}

Modifié dans la version 3.3: Several functions in this module used to raise a
@ref{103d,,WindowsError}, which is now an alias of @ref{40d,,OSError}.


@menu
* Fonctions: Fonctions<13>. 
* Constantes: Constantes<10>. 
* Registry Handle Objects:: 

@end menu

@node Fonctions<13>,Constantes<10>,,winreg --- Windows registry access
@anchor{library/winreg functions}@anchor{46c7}@anchor{library/winreg id1}@anchor{46c8}
@subsubsection Fonctions


This module offers the following functions:

@geindex CloseKey() (dans le module winreg)
@anchor{library/winreg winreg CloseKey}@anchor{46c9}
@deffn {Fonction} winreg.CloseKey (hkey)

Closes a previously opened registry key.  The `hkey' argument specifies a
previously opened key.

@cartouche
@quotation Note 
If `hkey' is not closed using this method (or via @ref{46ca,,hkey.Close()}), it is closed when the `hkey' object is destroyed by
Python.
@end quotation
@end cartouche
@end deffn

@geindex ConnectRegistry() (dans le module winreg)
@anchor{library/winreg winreg ConnectRegistry}@anchor{411c}
@deffn {Fonction} winreg.ConnectRegistry (computer_name, key)

Establishes a connection to a predefined registry handle on another computer,
and returns a @ref{46c5,,handle object}.

`computer_name' is the name of the remote computer, of the form
@code{r"\\computername"}.  If @code{None}, the local computer is used.

`key' is the predefined handle to connect to.

The return value is the handle of the opened key. If the function fails, an
@ref{40d,,OSError} exception is raised.

Raises an @ref{1848,,auditing event} @code{winreg.ConnectRegistry} with arguments @code{computer_name}, @code{key}.


Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex CreateKey() (dans le module winreg)
@anchor{library/winreg winreg CreateKey}@anchor{411d}
@deffn {Fonction} winreg.CreateKey (key, sub_key)

Creates or opens the specified key, returning a
@ref{46c5,,handle object}.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that names the key this method opens or creates.

If `key' is one of the predefined keys, `sub_key' may be @code{None}. In that
case, the handle returned is the same key handle passed in to the function.

If the key already exists, this function opens the existing key.

The return value is the handle of the opened key. If the function fails, an
@ref{40d,,OSError} exception is raised.

Raises an @ref{1848,,auditing event} @code{winreg.CreateKey} with arguments @code{key}, @code{sub_key}, @code{access}.

Raises an @ref{1848,,auditing event} @code{winreg.OpenKey/result} with argument @code{key}.


Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex CreateKeyEx() (dans le module winreg)
@anchor{library/winreg winreg CreateKeyEx}@anchor{1339}
@deffn {Fonction} winreg.CreateKeyEx (key, sub_key, reserved=0, access=KEY_WRITE)

Creates or opens the specified key, returning a
@ref{46c5,,handle object}.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that names the key this method opens or creates.

`reserved' is a reserved integer, and must be zero. The default is zero.

`access' is an integer that specifies an access mask that describes the desired
security access for the key.  Default is @ref{46cc,,KEY_WRITE}.  See
@ref{46cd,,Access Rights} for other allowed values.

If `key' is one of the predefined keys, `sub_key' may be @code{None}. In that
case, the handle returned is the same key handle passed in to the function.

If the key already exists, this function opens the existing key.

The return value is the handle of the opened key. If the function fails, an
@ref{40d,,OSError} exception is raised.

Raises an @ref{1848,,auditing event} @code{winreg.CreateKey} with arguments @code{key}, @code{sub_key}, @code{access}.

Raises an @ref{1848,,auditing event} @code{winreg.OpenKey/result} with argument @code{key}.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex DeleteKey() (dans le module winreg)
@anchor{library/winreg winreg DeleteKey}@anchor{411e}
@deffn {Fonction} winreg.DeleteKey (key, sub_key)

Deletes the specified key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that must be a subkey of the key identified by the `key'
parameter.  This value must not be @code{None}, and the key may not have subkeys.

`This method can not delete keys with subkeys.'

If the method succeeds, the entire key, including all of its values, is removed.
If the method fails, an @ref{40d,,OSError} exception is raised.

Raises an @ref{1848,,auditing event} @code{winreg.DeleteKey} with arguments @code{key}, @code{sub_key}, @code{access}.


Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex DeleteKeyEx() (dans le module winreg)
@anchor{library/winreg winreg DeleteKeyEx}@anchor{133a}
@deffn {Fonction} winreg.DeleteKeyEx (key, sub_key, access=KEY_WOW64_64KEY, reserved=0)

Deletes the specified key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that must be a subkey of the key identified by the
`key' parameter. This value must not be @code{None}, and the key may not have
subkeys.

`reserved' is a reserved integer, and must be zero. The default is zero.

`access' is an integer that specifies an access mask that describes the
desired security access for the key.  Default is @ref{46ce,,KEY_WOW64_64KEY}.
On 32-bit Windows, the WOW64 constants are ignored.
See @ref{46cd,,Access Rights} for other allowed values.

`This method can not delete keys with subkeys.'

If the method succeeds, the entire key, including all of its values, is
removed. If the method fails, an @ref{40d,,OSError} exception is raised.

On unsupported Windows versions, @ref{225,,NotImplementedError} is raised.

Raises an @ref{1848,,auditing event} @code{winreg.DeleteKey} with arguments @code{key}, @code{sub_key}, @code{access}.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex DeleteValue() (dans le module winreg)
@anchor{library/winreg winreg DeleteValue}@anchor{411f}
@deffn {Fonction} winreg.DeleteValue (key, value)

Removes a named value from a registry key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`value' is a string that identifies the value to remove.

Raises an @ref{1848,,auditing event} @code{winreg.DeleteValue} with arguments @code{key}, @code{value}.
@end deffn

@geindex EnumKey() (dans le module winreg)
@anchor{library/winreg winreg EnumKey}@anchor{4120}
@deffn {Fonction} winreg.EnumKey (key, index)

Enumerates subkeys of an open registry key, returning a string.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`index' is an integer that identifies the index of the key to retrieve.

The function retrieves the name of one subkey each time it is called.  It is
typically called repeatedly until an @ref{40d,,OSError} exception is
raised, indicating, no more values are available.

Raises an @ref{1848,,auditing event} @code{winreg.EnumKey} with arguments @code{key}, @code{index}.


Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex EnumValue() (dans le module winreg)
@anchor{library/winreg winreg EnumValue}@anchor{4121}
@deffn {Fonction} winreg.EnumValue (key, index)

Enumerates values of an open registry key, returning a tuple.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`index' is an integer that identifies the index of the value to retrieve.

The function retrieves the name of one subkey each time it is called. It is
typically called repeatedly, until an @ref{40d,,OSError} exception is
raised, indicating no more values.

The result is a tuple of 3 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Signification

@item

@code{0}

@tab

A string that identifies the value name

@item

@code{1}

@tab

An object that holds the value data, and
whose type depends on the underlying
registry type

@item

@code{2}

@tab

An integer that identifies the type of the
value data (see table in docs for
@ref{171c,,SetValueEx()})

@end multitable


Raises an @ref{1848,,auditing event} @code{winreg.EnumValue} with arguments @code{key}, @code{index}.


Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex % (percent);environment variables expansion (Windows)

@geindex ExpandEnvironmentStrings() (dans le module winreg)
@anchor{library/winreg winreg ExpandEnvironmentStrings}@anchor{13af}
@deffn {Fonction} winreg.ExpandEnvironmentStrings (str)

Expands environment variable placeholders @code{%NAME%} in strings like
@ref{46cf,,REG_EXPAND_SZ}:

@example
>>> ExpandEnvironmentStrings('%windir%')
'C:\\Windows'
@end example

Raises an @ref{1848,,auditing event} @code{winreg.ExpandEnvironmentStrings} with argument @code{str}.
@end deffn

@geindex FlushKey() (dans le module winreg)
@anchor{library/winreg winreg FlushKey}@anchor{46d0}
@deffn {Fonction} winreg.FlushKey (key)

Writes all the attributes of a key to the registry.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

It is not necessary to call @ref{46d0,,FlushKey()} to change a key. Registry changes are
flushed to disk by the registry using its lazy flusher.  Registry changes are
also flushed to disk at system shutdown.  Unlike @ref{46c9,,CloseKey()}, the
@ref{46d0,,FlushKey()} method returns only when all the data has been written to the
registry. An application should only call @ref{46d0,,FlushKey()} if it requires
absolute certainty that registry changes are on disk.

@cartouche
@quotation Note 
If you don't know whether a @ref{46d0,,FlushKey()} call is required, it probably
isn't.
@end quotation
@end cartouche
@end deffn

@geindex LoadKey() (dans le module winreg)
@anchor{library/winreg winreg LoadKey}@anchor{4122}
@deffn {Fonction} winreg.LoadKey (key, sub_key, file_name)

Creates a subkey under the specified key and stores registration information
from a specified file into that subkey.

`key' is a handle returned by @ref{411c,,ConnectRegistry()} or one of the constants
@ref{46d1,,HKEY_USERS} or @ref{46d2,,HKEY_LOCAL_MACHINE}.

`sub_key' is a string that identifies the subkey to load.

`file_name' is the name of the file to load registry data from. This file must
have been created with the @ref{4128,,SaveKey()} function. Under the file allocation
table (FAT) file system, the filename may not have an extension.

A call to @ref{4122,,LoadKey()} fails if the calling process does not have the
@code{SE_RESTORE_PRIVILEGE} privilege.  Note that privileges are different
from permissions -- see the RegLoadKey documentation@footnote{https://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx} for
more details.

If `key' is a handle returned by @ref{411c,,ConnectRegistry()}, then the path
specified in `file_name' is relative to the remote computer.

Raises an @ref{1848,,auditing event} @code{winreg.LoadKey} with arguments @code{key}, @code{sub_key}, @code{file_name}.
@end deffn

@geindex OpenKey() (dans le module winreg)
@geindex OpenKeyEx() (dans le module winreg)
@anchor{library/winreg winreg OpenKey}@anchor{4123}
@deffn {Fonction} winreg.OpenKey (key, sub_key, reserved=0, access=KEY_READ)
@anchor{library/winreg winreg OpenKeyEx}@anchor{46d3}
@deffnx {Fonction} winreg.OpenKeyEx (key, sub_key, reserved=0, access=KEY_READ)

Opens the specified key, returning a @ref{46c5,,handle object}.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that identifies the sub_key to open.

`reserved' is a reserved integer, and must be zero.  The default is zero.

`access' is an integer that specifies an access mask that describes the desired
security access for the key.  Default is @ref{46d4,,KEY_READ}.  See @ref{46cd,,Access Rights} for other allowed values.

The result is a new handle to the specified key.

If the function fails, @ref{40d,,OSError} is raised.

Raises an @ref{1848,,auditing event} @code{winreg.OpenKey} with arguments @code{key}, @code{sub_key}, @code{access}.

Raises an @ref{1848,,auditing event} @code{winreg.OpenKey/result} with argument @code{key}.


Modifié dans la version 3.2: Allow the use of named arguments.



Modifié dans la version 3.3: See @ref{46c6,,above}.

@end deffn

@geindex QueryInfoKey() (dans le module winreg)
@anchor{library/winreg winreg QueryInfoKey}@anchor{4125}
@deffn {Fonction} winreg.QueryInfoKey (key)

Returns information about a key, as a tuple.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

The result is a tuple of 3 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Signification

@item

@code{0}

@tab

An integer giving the number of sub keys
this key has.

@item

@code{1}

@tab

An integer giving the number of values this
key has.

@item

@code{2}

@tab

An integer giving when the key was last
modified (if available) as 100's of
nanoseconds since Jan 1, 1601.

@end multitable


Raises an @ref{1848,,auditing event} @code{winreg.QueryInfoKey} with argument @code{key}.
@end deffn

@geindex QueryValue() (dans le module winreg)
@anchor{library/winreg winreg QueryValue}@anchor{4126}
@deffn {Fonction} winreg.QueryValue (key, sub_key)

Retrieves the unnamed value for a key, as a string.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that holds the name of the subkey with which the value is
associated.  If this parameter is @code{None} or empty, the function retrieves the
value set by the @ref{4129,,SetValue()} method for the key identified by `key'.

Values in the registry have name, type, and data components. This method
retrieves the data for a key's first value that has a @code{NULL} name. But the
underlying API call doesn't return the type, so always use
@ref{4127,,QueryValueEx()} if possible.

Raises an @ref{1848,,auditing event} @code{winreg.QueryValue} with arguments @code{key}, @code{sub_key}, @code{value_name}.
@end deffn

@geindex QueryValueEx() (dans le module winreg)
@anchor{library/winreg winreg QueryValueEx}@anchor{4127}
@deffn {Fonction} winreg.QueryValueEx (key, value_name)

Retrieves the type and data for a specified value name associated with
an open registry key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`value_name' is a string indicating the value to query.

The result is a tuple of 2 items:


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Signification

@item

@code{0}

@tab

The value of the registry item.

@item

@code{1}

@tab

An integer giving the registry type for
this value (see table in docs for
@ref{171c,,SetValueEx()})

@end multitable


Raises an @ref{1848,,auditing event} @code{winreg.QueryValue} with arguments @code{key}, @code{sub_key}, @code{value_name}.
@end deffn

@geindex SaveKey() (dans le module winreg)
@anchor{library/winreg winreg SaveKey}@anchor{4128}
@deffn {Fonction} winreg.SaveKey (key, file_name)

Saves the specified key, and all its subkeys to the specified file.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`file_name' is the name of the file to save registry data to.  This file
cannot already exist. If this filename includes an extension, it cannot be
used on file allocation table (FAT) file systems by the @ref{4122,,LoadKey()}
method.

If `key' represents a key on a remote computer, the path described by
`file_name' is relative to the remote computer. The caller of this method must
possess the `SeBackupPrivilege' security privilege.  Note that
privileges are different than permissions -- see the
Conflicts Between User Rights and Permissions documentation@footnote{https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx}
for more details.

This function passes @code{NULL} for `security_attributes' to the API.

Raises an @ref{1848,,auditing event} @code{winreg.SaveKey} with arguments @code{key}, @code{file_name}.
@end deffn

@geindex SetValue() (dans le module winreg)
@anchor{library/winreg winreg SetValue}@anchor{4129}
@deffn {Fonction} winreg.SetValue (key, sub_key, type, value)

Associates a value with a specified key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`sub_key' is a string that names the subkey with which the value is associated.

`type' is an integer that specifies the type of the data. Currently this must be
@ref{46d5,,REG_SZ}, meaning only strings are supported.  Use the @ref{171c,,SetValueEx()}
function for support for other data types.

`value' is a string that specifies the new value.

If the key specified by the `sub_key' parameter does not exist, the SetValue
function creates it.

Value lengths are limited by available memory. Long values (more than 2048
bytes) should be stored as files with the filenames stored in the configuration
registry.  This helps the registry perform efficiently.

The key identified by the `key' parameter must have been opened with
@ref{46d6,,KEY_SET_VALUE} access.

Raises an @ref{1848,,auditing event} @code{winreg.SetValue} with arguments @code{key}, @code{sub_key}, @code{type}, @code{value}.
@end deffn

@geindex SetValueEx() (dans le module winreg)
@anchor{library/winreg winreg SetValueEx}@anchor{171c}
@deffn {Fonction} winreg.SetValueEx (key, value_name, reserved, type, value)

Stores data in the value field of an open registry key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

`value_name' is a string that names the subkey with which the value is
associated.

`reserved' can be anything -- zero is always passed to the API.

`type' is an integer that specifies the type of the data. See
@ref{46d7,,Value Types} for the available types.

`value' is a string that specifies the new value.

This method can also set additional value and type information for the specified
key.  The key identified by the key parameter must have been opened with
@ref{46d6,,KEY_SET_VALUE} access.

To open the key, use the @ref{411d,,CreateKey()} or @ref{4123,,OpenKey()} methods.

Value lengths are limited by available memory. Long values (more than 2048
bytes) should be stored as files with the filenames stored in the configuration
registry.  This helps the registry perform efficiently.

Raises an @ref{1848,,auditing event} @code{winreg.SetValue} with arguments @code{key}, @code{sub_key}, @code{type}, @code{value}.
@end deffn

@geindex DisableReflectionKey() (dans le module winreg)
@anchor{library/winreg winreg DisableReflectionKey}@anchor{133b}
@deffn {Fonction} winreg.DisableReflectionKey (key)

Disables registry reflection for 32-bit processes running on a 64-bit
operating system.

`key' is an already open key, or one of the predefined @ref{46cb,,HKEY_* constants}.

Will generally raise @ref{225,,NotImplementedError} if executed on a 32-bit operating
system.

If the key is not on the reflection list, the function succeeds but has no
effect.  Disabling reflection for a key does not affect reflection of any
subkeys.

Raises an @ref{1848,,auditing event} @code{winreg.DisableReflectionKey} with argument @code{key}.
@end deffn

@geindex EnableReflectionKey() (dans le module winreg)
@anchor{library/winreg winreg EnableReflectionKey}@anchor{133c}
@deffn {Fonction} winreg.EnableReflectionKey (key)

Restores registry reflection for the specified disabled key.

`key' is an already open key, or one of the predefined @ref{46cb,,HKEY_* constants}.

Will generally raise @ref{225,,NotImplementedError} if executed on a 32-bit operating
system.

Restoring reflection for a key does not affect reflection of any subkeys.

Raises an @ref{1848,,auditing event} @code{winreg.EnableReflectionKey} with argument @code{key}.
@end deffn

@geindex QueryReflectionKey() (dans le module winreg)
@anchor{library/winreg winreg QueryReflectionKey}@anchor{133d}
@deffn {Fonction} winreg.QueryReflectionKey (key)

Determines the reflection state for the specified key.

`key' is an already open key, or one of the predefined
@ref{46cb,,HKEY_* constants}.

Returns @code{True} if reflection is disabled.

Will generally raise @ref{225,,NotImplementedError} if executed on a 32-bit
operating system.

Raises an @ref{1848,,auditing event} @code{winreg.QueryReflectionKey} with argument @code{key}.
@end deffn

@node Constantes<10>,Registry Handle Objects,Fonctions<13>,winreg --- Windows registry access
@anchor{library/winreg constants}@anchor{46d8}@anchor{library/winreg id2}@anchor{46d9}
@subsubsection Constantes


The following constants are defined for use in many @ref{115,,winreg} functions.

@menu
* HKEY_* Constants:: 
* Access Rights:: 
* Value Types:: 

@end menu

@node HKEY_* Constants,Access Rights,,Constantes<10>
@anchor{library/winreg hkey-constants}@anchor{46cb}@anchor{library/winreg id3}@anchor{46da}
@subsubsection HKEY_* Constants


@geindex HKEY_CLASSES_ROOT (dans le module winreg)
@anchor{library/winreg winreg HKEY_CLASSES_ROOT}@anchor{46db}
@deffn {Données} winreg.HKEY_CLASSES_ROOT

Registry entries subordinate to this key define types (or classes) of
documents and the properties associated with those types. Shell and
COM applications use the information stored under this key.
@end deffn

@geindex HKEY_CURRENT_USER (dans le module winreg)
@anchor{library/winreg winreg HKEY_CURRENT_USER}@anchor{46dc}
@deffn {Données} winreg.HKEY_CURRENT_USER

Registry entries subordinate to this key define the preferences of
the current user. These preferences include the settings of
environment variables, data about program groups, colors, printers,
network connections, and application preferences.
@end deffn

@geindex HKEY_LOCAL_MACHINE (dans le module winreg)
@anchor{library/winreg winreg HKEY_LOCAL_MACHINE}@anchor{46d2}
@deffn {Données} winreg.HKEY_LOCAL_MACHINE

Registry entries subordinate to this key define the physical state
of the computer, including data about the bus type, system memory,
and installed hardware and software.
@end deffn

@geindex HKEY_USERS (dans le module winreg)
@anchor{library/winreg winreg HKEY_USERS}@anchor{46d1}
@deffn {Données} winreg.HKEY_USERS

Registry entries subordinate to this key define the default user
configuration for new users on the local computer and the user
configuration for the current user.
@end deffn

@geindex HKEY_PERFORMANCE_DATA (dans le module winreg)
@anchor{library/winreg winreg HKEY_PERFORMANCE_DATA}@anchor{46dd}
@deffn {Données} winreg.HKEY_PERFORMANCE_DATA

Registry entries subordinate to this key allow you to access
performance data. The data is not actually stored in the registry;
the registry functions cause the system to collect the data from
its source.
@end deffn

@geindex HKEY_CURRENT_CONFIG (dans le module winreg)
@anchor{library/winreg winreg HKEY_CURRENT_CONFIG}@anchor{46de}
@deffn {Données} winreg.HKEY_CURRENT_CONFIG

Contains information about the current hardware profile of the
local computer system.
@end deffn

@geindex HKEY_DYN_DATA (dans le module winreg)
@anchor{library/winreg winreg HKEY_DYN_DATA}@anchor{46df}
@deffn {Données} winreg.HKEY_DYN_DATA

This key is not used in versions of Windows after 98.
@end deffn

@node Access Rights,Value Types,HKEY_* Constants,Constantes<10>
@anchor{library/winreg access-rights}@anchor{46cd}@anchor{library/winreg id4}@anchor{46e0}
@subsubsection Access Rights


For more information, see Registry Key Security and Access@footnote{https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx}.

@geindex KEY_ALL_ACCESS (dans le module winreg)
@anchor{library/winreg winreg KEY_ALL_ACCESS}@anchor{46e1}
@deffn {Données} winreg.KEY_ALL_ACCESS

Combines the STANDARD_RIGHTS_REQUIRED, @ref{46e2,,KEY_QUERY_VALUE},
@ref{46d6,,KEY_SET_VALUE}, @ref{46e3,,KEY_CREATE_SUB_KEY},
@ref{46e4,,KEY_ENUMERATE_SUB_KEYS}, @ref{46e5,,KEY_NOTIFY},
and @ref{46e6,,KEY_CREATE_LINK} access rights.
@end deffn

@geindex KEY_WRITE (dans le module winreg)
@anchor{library/winreg winreg KEY_WRITE}@anchor{46cc}
@deffn {Données} winreg.KEY_WRITE

Combines the STANDARD_RIGHTS_WRITE, @ref{46d6,,KEY_SET_VALUE}, and
@ref{46e3,,KEY_CREATE_SUB_KEY} access rights.
@end deffn

@geindex KEY_READ (dans le module winreg)
@anchor{library/winreg winreg KEY_READ}@anchor{46d4}
@deffn {Données} winreg.KEY_READ

Combines the STANDARD_RIGHTS_READ, @ref{46e2,,KEY_QUERY_VALUE},
@ref{46e4,,KEY_ENUMERATE_SUB_KEYS}, and @ref{46e5,,KEY_NOTIFY} values.
@end deffn

@geindex KEY_EXECUTE (dans le module winreg)
@anchor{library/winreg winreg KEY_EXECUTE}@anchor{46e7}
@deffn {Données} winreg.KEY_EXECUTE

Equivalent to @ref{46d4,,KEY_READ}.
@end deffn

@geindex KEY_QUERY_VALUE (dans le module winreg)
@anchor{library/winreg winreg KEY_QUERY_VALUE}@anchor{46e2}
@deffn {Données} winreg.KEY_QUERY_VALUE

Required to query the values of a registry key.
@end deffn

@geindex KEY_SET_VALUE (dans le module winreg)
@anchor{library/winreg winreg KEY_SET_VALUE}@anchor{46d6}
@deffn {Données} winreg.KEY_SET_VALUE

Required to create, delete, or set a registry value.
@end deffn

@geindex KEY_CREATE_SUB_KEY (dans le module winreg)
@anchor{library/winreg winreg KEY_CREATE_SUB_KEY}@anchor{46e3}
@deffn {Données} winreg.KEY_CREATE_SUB_KEY

Required to create a subkey of a registry key.
@end deffn

@geindex KEY_ENUMERATE_SUB_KEYS (dans le module winreg)
@anchor{library/winreg winreg KEY_ENUMERATE_SUB_KEYS}@anchor{46e4}
@deffn {Données} winreg.KEY_ENUMERATE_SUB_KEYS

Required to enumerate the subkeys of a registry key.
@end deffn

@geindex KEY_NOTIFY (dans le module winreg)
@anchor{library/winreg winreg KEY_NOTIFY}@anchor{46e5}
@deffn {Données} winreg.KEY_NOTIFY

Required to request change notifications for a registry key or for
subkeys of a registry key.
@end deffn

@geindex KEY_CREATE_LINK (dans le module winreg)
@anchor{library/winreg winreg KEY_CREATE_LINK}@anchor{46e6}
@deffn {Données} winreg.KEY_CREATE_LINK

Reserved for system use.
@end deffn

@menu
* 64-bit Specific:: 

@end menu

@node 64-bit Specific,,,Access Rights
@anchor{library/winreg bit-access-rights}@anchor{46e8}@anchor{library/winreg bit-specific}@anchor{46e9}
@subsubsection 64-bit Specific


For more information, see Accessing an Alternate Registry View@footnote{https://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx}.

@geindex KEY_WOW64_64KEY (dans le module winreg)
@anchor{library/winreg winreg KEY_WOW64_64KEY}@anchor{46ce}
@deffn {Données} winreg.KEY_WOW64_64KEY

Indicates that an application on 64-bit Windows should operate on
the 64-bit registry view. On 32-bit Windows, this constant is ignored.
@end deffn

@geindex KEY_WOW64_32KEY (dans le module winreg)
@anchor{library/winreg winreg KEY_WOW64_32KEY}@anchor{46ea}
@deffn {Données} winreg.KEY_WOW64_32KEY

Indicates that an application on 64-bit Windows should operate on
the 32-bit registry view. On 32-bit Windows, this constant is ignored.
@end deffn

@node Value Types,,Access Rights,Constantes<10>
@anchor{library/winreg id5}@anchor{46eb}@anchor{library/winreg value-types}@anchor{46d7}
@subsubsection Value Types


For more information, see Registry Value Types@footnote{https://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx}.

@geindex REG_BINARY (dans le module winreg)
@anchor{library/winreg winreg REG_BINARY}@anchor{46ec}
@deffn {Données} winreg.REG_BINARY

Binary data in any form.
@end deffn

@geindex REG_DWORD (dans le module winreg)
@anchor{library/winreg winreg REG_DWORD}@anchor{46ed}
@deffn {Données} winreg.REG_DWORD

32-bit number.
@end deffn

@geindex REG_DWORD_LITTLE_ENDIAN (dans le module winreg)
@anchor{library/winreg winreg REG_DWORD_LITTLE_ENDIAN}@anchor{46ee}
@deffn {Données} winreg.REG_DWORD_LITTLE_ENDIAN

A 32-bit number in little-endian format. Equivalent to @ref{46ed,,REG_DWORD}.
@end deffn

@geindex REG_DWORD_BIG_ENDIAN (dans le module winreg)
@anchor{library/winreg winreg REG_DWORD_BIG_ENDIAN}@anchor{46ef}
@deffn {Données} winreg.REG_DWORD_BIG_ENDIAN

A 32-bit number in big-endian format.
@end deffn

@geindex REG_EXPAND_SZ (dans le module winreg)
@anchor{library/winreg winreg REG_EXPAND_SZ}@anchor{46cf}
@deffn {Données} winreg.REG_EXPAND_SZ

Null-terminated string containing references to environment
variables (@code{%PATH%}).
@end deffn

@geindex REG_LINK (dans le module winreg)
@anchor{library/winreg winreg REG_LINK}@anchor{46f0}
@deffn {Données} winreg.REG_LINK

A Unicode symbolic link.
@end deffn

@geindex REG_MULTI_SZ (dans le module winreg)
@anchor{library/winreg winreg REG_MULTI_SZ}@anchor{196c}
@deffn {Données} winreg.REG_MULTI_SZ

A sequence of null-terminated strings, terminated by two null characters.
(Python handles this termination automatically.)
@end deffn

@geindex REG_NONE (dans le module winreg)
@anchor{library/winreg winreg REG_NONE}@anchor{46f1}
@deffn {Données} winreg.REG_NONE

No defined value type.
@end deffn

@geindex REG_QWORD (dans le module winreg)
@anchor{library/winreg winreg REG_QWORD}@anchor{cf0}
@deffn {Données} winreg.REG_QWORD

A 64-bit number.


Ajouté dans la version 3.6.

@end deffn

@geindex REG_QWORD_LITTLE_ENDIAN (dans le module winreg)
@anchor{library/winreg winreg REG_QWORD_LITTLE_ENDIAN}@anchor{46f2}
@deffn {Données} winreg.REG_QWORD_LITTLE_ENDIAN

A 64-bit number in little-endian format. Equivalent to @ref{cf0,,REG_QWORD}.


Ajouté dans la version 3.6.

@end deffn

@geindex REG_RESOURCE_LIST (dans le module winreg)
@anchor{library/winreg winreg REG_RESOURCE_LIST}@anchor{46f3}
@deffn {Données} winreg.REG_RESOURCE_LIST

A device-driver resource list.
@end deffn

@geindex REG_FULL_RESOURCE_DESCRIPTOR (dans le module winreg)
@anchor{library/winreg winreg REG_FULL_RESOURCE_DESCRIPTOR}@anchor{46f4}
@deffn {Données} winreg.REG_FULL_RESOURCE_DESCRIPTOR

A hardware setting.
@end deffn

@geindex REG_RESOURCE_REQUIREMENTS_LIST (dans le module winreg)
@anchor{library/winreg winreg REG_RESOURCE_REQUIREMENTS_LIST}@anchor{46f5}
@deffn {Données} winreg.REG_RESOURCE_REQUIREMENTS_LIST

A hardware resource list.
@end deffn

@geindex REG_SZ (dans le module winreg)
@anchor{library/winreg winreg REG_SZ}@anchor{46d5}
@deffn {Données} winreg.REG_SZ

A null-terminated string.
@end deffn

@node Registry Handle Objects,,Constantes<10>,winreg --- Windows registry access
@anchor{library/winreg handle-object}@anchor{46c5}@anchor{library/winreg registry-handle-objects}@anchor{46f6}
@subsubsection Registry Handle Objects


This object wraps a Windows HKEY object, automatically closing it when the
object is destroyed.  To guarantee cleanup, you can call either the
@ref{46ca,,Close()} method on the object, or the @ref{46c9,,CloseKey()} function.

All registry functions in this module return one of these objects.

All registry functions in this module which accept a handle object also accept
an integer, however, use of the handle object is encouraged.

Handle objects provide semantics for @ref{12b3,,__bool__()} -- thus

@example
if handle:
    print("Yes")
@end example

will print @code{Yes} if the handle is currently valid (has not been closed or
detached).

The object also support comparison semantics, so handle objects will compare
true if they both reference the same underlying Windows handle value.

Handle objects can be converted to an integer (e.g., using the built-in
@ref{254,,int()} function), in which case the underlying Windows handle value is
returned.  You can also use the @ref{4124,,Detach()} method to return the
integer handle, and also disconnect the Windows handle from the handle object.

@geindex Close() (méthode winreg.PyHKEY)
@anchor{library/winreg winreg PyHKEY Close}@anchor{46ca}
@deffn {Méthode} PyHKEY.Close ()

Closes the underlying Windows handle.

If the handle is already closed, no error is raised.
@end deffn

@geindex Detach() (méthode winreg.PyHKEY)
@anchor{library/winreg winreg PyHKEY Detach}@anchor{4124}
@deffn {Méthode} PyHKEY.Detach ()

Detaches the Windows handle from the handle object.

The result is an integer that holds the value of the handle before it is
detached.  If the handle is already detached or closed, this will return
zero.

After calling this function, the handle is effectively invalidated, but the
handle is not closed.  You would call this function when you need the
underlying Win32 handle to exist beyond the lifetime of the handle object.

Raises an @ref{1848,,auditing event} @code{winreg.PyHKEY.Detach} with argument @code{key}.
@end deffn

@geindex __enter__() (méthode winreg.PyHKEY)
@geindex __exit__() (méthode winreg.PyHKEY)
@anchor{library/winreg winreg PyHKEY __enter__}@anchor{46f7}
@deffn {Méthode} PyHKEY.__enter__ ()
@anchor{library/winreg winreg PyHKEY __exit__}@anchor{46f8}
@deffnx {Méthode} PyHKEY.__exit__ (*exc_info)

The HKEY object implements @ref{5b2,,__enter__()} and
@ref{12de,,__exit__()} and thus supports the context protocol for the
@ref{5bc,,with} statement:

@example
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
    ...  # work with key
@end example

will automatically close `key' when control leaves the @ref{5bc,,with} block.
@end deffn

@node winsound --- Sound-playing interface for Windows,,winreg --- Windows registry access,Services spécifiques à MS Windows
@anchor{library/winsound doc}@anchor{46f9}@anchor{library/winsound module-winsound}@anchor{116}@anchor{library/winsound winsound-sound-playing-interface-for-windows}@anchor{46fa}
@subsection @code{winsound} --- Sound-playing interface for Windows


@geindex module; winsound


__________________________________________________________________


The @ref{116,,winsound} module provides access to the basic sound-playing machinery
provided by Windows platforms.  It includes functions and several constants.

@geindex Beep() (dans le module winsound)
@anchor{library/winsound winsound Beep}@anchor{cf2}
@deffn {Fonction} winsound.Beep (frequency, duration)

Beep the PC's speaker. The `frequency' parameter specifies frequency, in hertz,
of the sound, and must be in the range 37 through 32,767. The `duration'
parameter specifies the number of milliseconds the sound should last.  If the
system is not able to beep the speaker, @ref{193,,RuntimeError} is raised.
@end deffn

@geindex PlaySound() (dans le module winsound)
@anchor{library/winsound winsound PlaySound}@anchor{cf4}
@deffn {Fonction} winsound.PlaySound (sound, flags)

Call the underlying @code{PlaySound()} function from the Platform API.  The
`sound' parameter may be a filename, a system sound alias, audio data as a
@ref{d1b,,bytes-like object}, or @code{None}.  Its
interpretation depends on the value of `flags', which can be a bitwise ORed
combination of the constants described below. If the `sound' parameter is
@code{None}, any currently playing waveform sound is stopped. If the system
indicates an error, @ref{193,,RuntimeError} is raised.
@end deffn

@geindex MessageBeep() (dans le module winsound)
@anchor{library/winsound winsound MessageBeep}@anchor{cf3}
@deffn {Fonction} winsound.MessageBeep (type=MB_OK)

Call the underlying @code{MessageBeep()} function from the Platform API.  This
plays a sound as specified in the registry.  The `type' argument specifies which
sound to play; possible values are @code{-1}, @code{MB_ICONASTERISK},
@code{MB_ICONEXCLAMATION}, @code{MB_ICONHAND}, @code{MB_ICONQUESTION}, and @code{MB_OK}, all
described below.  The value @code{-1} produces a "simple beep"; this is the final
fallback if a sound cannot be played otherwise.  If the system indicates an
error, @ref{193,,RuntimeError} is raised.
@end deffn

@geindex SND_FILENAME (dans le module winsound)
@anchor{library/winsound winsound SND_FILENAME}@anchor{46fb}
@deffn {Données} winsound.SND_FILENAME

The `sound' parameter is the name of a WAV file. Do not use with
@ref{46fc,,SND_ALIAS}.
@end deffn

@geindex SND_ALIAS (dans le module winsound)
@anchor{library/winsound winsound SND_ALIAS}@anchor{46fc}
@deffn {Données} winsound.SND_ALIAS

The `sound' parameter is a sound association name from the registry.  If the
registry contains no such name, play the system default sound unless
@ref{46fd,,SND_NODEFAULT} is also specified. If no default sound is registered,
raise @ref{193,,RuntimeError}. Do not use with @ref{46fb,,SND_FILENAME}.

All Win32 systems support at least the following; most systems support many
more:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

@ref{cf4,,PlaySound()} `name'

@tab

Corresponding Control Panel Sound name

@item

@code{'SystemAsterisk'}

@tab

Asterisk

@item

@code{'SystemExclamation'}

@tab

Exclamation

@item

@code{'SystemExit'}

@tab

Exit Windows

@item

@code{'SystemHand'}

@tab

Critical Stop

@item

@code{'SystemQuestion'}

@tab

Question

@end multitable


Par exemple :

@example
import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)
@end example
@end deffn

@geindex SND_LOOP (dans le module winsound)
@anchor{library/winsound winsound SND_LOOP}@anchor{46fe}
@deffn {Données} winsound.SND_LOOP

Play the sound repeatedly.  The @ref{46ff,,SND_ASYNC} flag must also be used to
avoid blocking.  Cannot be used with @ref{4700,,SND_MEMORY}.
@end deffn

@geindex SND_MEMORY (dans le module winsound)
@anchor{library/winsound winsound SND_MEMORY}@anchor{4700}
@deffn {Données} winsound.SND_MEMORY

The `sound' parameter to @ref{cf4,,PlaySound()} is a memory image of a WAV file, as a
@ref{d1b,,bytes-like object}.

@cartouche
@quotation Note 
This module does not support playing from a memory image asynchronously, so a
combination of this flag and @ref{46ff,,SND_ASYNC} will raise @ref{193,,RuntimeError}.
@end quotation
@end cartouche
@end deffn

@geindex SND_PURGE (dans le module winsound)
@anchor{library/winsound winsound SND_PURGE}@anchor{4701}
@deffn {Données} winsound.SND_PURGE

Stop playing all instances of the specified sound.

@cartouche
@quotation Note 
This flag is not supported on modern Windows platforms.
@end quotation
@end cartouche
@end deffn

@geindex SND_ASYNC (dans le module winsound)
@anchor{library/winsound winsound SND_ASYNC}@anchor{46ff}
@deffn {Données} winsound.SND_ASYNC

Return immediately, allowing sounds to play asynchronously.
@end deffn

@geindex SND_NODEFAULT (dans le module winsound)
@anchor{library/winsound winsound SND_NODEFAULT}@anchor{46fd}
@deffn {Données} winsound.SND_NODEFAULT

If the specified sound cannot be found, do not play the system default sound.
@end deffn

@geindex SND_NOSTOP (dans le module winsound)
@anchor{library/winsound winsound SND_NOSTOP}@anchor{4702}
@deffn {Données} winsound.SND_NOSTOP

Do not interrupt sounds currently playing.
@end deffn

@geindex SND_NOWAIT (dans le module winsound)
@anchor{library/winsound winsound SND_NOWAIT}@anchor{4703}
@deffn {Données} winsound.SND_NOWAIT

Return immediately if the sound driver is busy.

@cartouche
@quotation Note 
This flag is not supported on modern Windows platforms.
@end quotation
@end cartouche
@end deffn

@geindex MB_ICONASTERISK (dans le module winsound)
@anchor{library/winsound winsound MB_ICONASTERISK}@anchor{4704}
@deffn {Données} winsound.MB_ICONASTERISK

Play the @code{SystemDefault} sound.
@end deffn

@geindex MB_ICONEXCLAMATION (dans le module winsound)
@anchor{library/winsound winsound MB_ICONEXCLAMATION}@anchor{4705}
@deffn {Données} winsound.MB_ICONEXCLAMATION

Play the @code{SystemExclamation} sound.
@end deffn

@geindex MB_ICONHAND (dans le module winsound)
@anchor{library/winsound winsound MB_ICONHAND}@anchor{4706}
@deffn {Données} winsound.MB_ICONHAND

Play the @code{SystemHand} sound.
@end deffn

@geindex MB_ICONQUESTION (dans le module winsound)
@anchor{library/winsound winsound MB_ICONQUESTION}@anchor{4707}
@deffn {Données} winsound.MB_ICONQUESTION

Play the @code{SystemQuestion} sound.
@end deffn

@geindex MB_OK (dans le module winsound)
@anchor{library/winsound winsound MB_OK}@anchor{4708}
@deffn {Données} winsound.MB_OK

Play the @code{SystemDefault} sound.
@end deffn

@node Services spécifiques à Unix,Modules command-line interface CLI,Services spécifiques à MS Windows,La bibliothèque standard
@anchor{library/unix doc}@anchor{4709}@anchor{library/unix unix}@anchor{470a}@anchor{library/unix unix-specific-services}@anchor{470b}
@section Services spécifiques à Unix


Les modules décrits dans ce chapitre fournissent des interfaces aux fonctionnalités propres au système d'exploitation Unix ou, dans certains cas, à certaines de ses variantes, en voici un aperçu :

@menu
* posix: posix --- The most common POSIX system calls. The most common POSIX system calls
* pwd: pwd --- The password database. The password database
* grp: grp --- The group database. The group database
* termios: termios --- POSIX style tty control. POSIX style tty control
* tty: tty --- Terminal control functions. Terminal control functions
* pty: pty --- Pseudo-terminal utilities. Pseudo-terminal utilities
* fcntl: fcntl --- The fcntl and ioctl system calls. The fcntl and ioctl system calls
* resource: resource --- Resource usage information. Resource usage information
* syslog: syslog --- Unix syslog library routines. Unix syslog library routines

@end menu

@node posix --- The most common POSIX system calls,pwd --- The password database,,Services spécifiques à Unix
@anchor{library/posix doc}@anchor{470c}@anchor{library/posix module-posix}@anchor{ac}@anchor{library/posix posix-the-most-common-posix-system-calls}@anchor{470d}
@subsection @code{posix} --- The most common POSIX system calls


@geindex module; posix


__________________________________________________________________


Ce module permet d'accéder aux fonctionnalités du système d'exploitation normalisés par le Standard C et le Standard POSIX (une interface Unix habilement déguisée).

@ref{1ce0,,Availability}: Unix.

@geindex module;os

`Ne pas importer ce module directement.'  À la place, importer le module @ref{a0,,os}, qui fournit une version `portable' de cette interface. Sous Unix, le module @ref{a0,,os} fournit un sur-ensemble de l'interface @ref{ac,,posix}.  Sous les systèmes d'exploitation non Unix le module @ref{ac,,posix} n'est pas disponible, mais un sous ensemble est toujours disponible via l'interface @ref{a0,,os}. Une fois que @ref{a0,,os} est importé, il n'y a aucune perte de performance à l'utiliser à la place de @ref{ac,,posix}.  De plus, @ref{a0,,os} fournit des fonctionnalités supplémentaires, telles que l'appel automatique de @ref{909,,putenv()} lorsqu'une entrée dans @code{os.environ} est modifiée.

Les erreurs sont signalées comme des exceptions; les exceptions habituelles sont données pour les erreurs de type, tandis que les erreurs signalées par les appels système lèvent une erreur @ref{40d,,OSError}.

@menu
* Prise en charge de gros fichiers:: 
* Contenu du Module:: 

@end menu

@node Prise en charge de gros fichiers,Contenu du Module,,posix --- The most common POSIX system calls
@anchor{library/posix large-file-support}@anchor{470e}@anchor{library/posix posix-large-files}@anchor{470f}
@subsubsection Prise en charge de gros fichiers


@geindex large files
@geindex file;large files

Several operating systems (including AIX and Solaris) provide
support for files that are larger than 2 GiB from a C programming model where
int and long are 32-bit values. This is typically accomplished
by defining the relevant size and offset types as 64-bit values. Such files are
sometimes referred to as `large files'.

Large file support is enabled in Python when the size of an @code{off_t} is
larger than a long and the long long is at least as large
as an @code{off_t}.
It may be necessary to configure and compile Python with certain compiler flags
to enable this mode. For example, with Solaris 2.6 and 2.7 you need to do
something like:

@example
CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
        ./configure
@end example

Sur les systèmes Linux capable de supporter les fichiers volumineux, cela pourrait fonctionner :

@example
CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
        ./configure
@end example

@node Contenu du Module,,Prise en charge de gros fichiers,posix --- The most common POSIX system calls
@anchor{library/posix notable-module-contents}@anchor{4710}@anchor{library/posix posix-contents}@anchor{4711}
@subsubsection Contenu du Module


En plus des nombreuses fonctions décrites dans la documentation du module @ref{a0,,os}, @ref{ac,,posix} possède les éléments suivants :

@geindex environ (dans le module posix)
@anchor{library/posix posix environ}@anchor{4712}
@deffn {Données} posix.environ

Un dictionnaire représentant les variables d'environnement au moment où l'interpréteur à été lancé. Les clés et les valeurs sont des @code{bytes} sous Unix et des @code{str} sous Windows. Par exemple, @code{environ[b'HOME']} (@code{environ['HOME']} dans Windows) est le chemin de votre dossier d’accueil, équivalent à @code{getenv("HOME")} en C.

Modifier ce dictionnaire n'affecte pas les variables d'environnements fournis par @ref{2aa1,,execv()}, @ref{a75,,popen()} ou @ref{1411,,system()}; Si vous avez besoin de changer l'environnement, passer le paramètre @code{environ} à @ref{10d9,,execve()} ou ajouter les assignations de variables et les `export' à la commande à exécuter via @ref{1411,,system()} ou @ref{a75,,popen()}.


Modifié dans la version 3.2: Sous Unix, les clés et les valeurs sont des octets.


@cartouche
@quotation Note 
Le module @ref{a0,,os} fournit une implémentation alternative à @code{environ} qui met à jour l'environnement en cas de modification. Notez également que la mise à jour de @ref{1197,,os.environ} rendra ce dictionnaire obsolète. Il est recommandé d'utiliser le module @ref{a0,,os} au lieu du module @ref{ac,,posix} dans ce cas-ci.
@end quotation
@end cartouche
@end deffn

@node pwd --- The password database,grp --- The group database,posix --- The most common POSIX system calls,Services spécifiques à Unix
@anchor{library/pwd doc}@anchor{4713}@anchor{library/pwd module-pwd}@anchor{b1}@anchor{library/pwd pwd-the-password-database}@anchor{4714}
@subsection @code{pwd} --- The password database


@geindex module; pwd


__________________________________________________________________


This module provides access to the Unix user account and password database.  It
is available on all Unix versions.

@ref{1ce0,,Availability}: Unix, not WASI, not iOS.

Password database entries are reported as a tuple-like object, whose attributes
correspond to the members of the @code{passwd} structure (Attribute field below,
see @code{<pwd.h>}):


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Attribut

@tab

Signification

@item

0

@tab

@code{pw_name}

@tab

Nom d’utilisateur

@item

1

@tab

@code{pw_passwd}

@tab

Optional encrypted password

@item

2

@tab

@code{pw_uid}

@tab

Numerical user ID

@item

3

@tab

@code{pw_gid}

@tab

Numerical group ID

@item

4

@tab

@code{pw_gecos}

@tab

User name or comment field

@item

5

@tab

@code{pw_dir}

@tab

Répertoire d’accueil de l’utilisateur

@item

6

@tab

@code{pw_shell}

@tab

User command interpreter

@end multitable


The uid and gid items are integers, all others are strings. @ref{33a,,KeyError} is
raised if the entry asked for cannot be found.

@cartouche
@quotation Note 
In traditional Unix the field @code{pw_passwd} usually contains a password
encrypted with a DES derived algorithm.  However most
modern unices  use a so-called `shadow password' system.  On those unices the
`pw_passwd' field only contains an asterisk (@code{'*'}) or the  letter @code{'x'}
where the encrypted password is stored in a file @code{/etc/shadow} which is
not world readable.  Whether the `pw_passwd' field contains anything useful is
system-dependent.
@end quotation
@end cartouche

It defines the following items:

@geindex getpwuid() (dans le module pwd)
@anchor{library/pwd pwd getpwuid}@anchor{19be}
@deffn {Fonction} pwd.getpwuid (uid)

Return the password database entry for the given numeric user ID.
@end deffn

@geindex getpwnam() (dans le module pwd)
@anchor{library/pwd pwd getpwnam}@anchor{3163}
@deffn {Fonction} pwd.getpwnam (name)

Return the password database entry for the given user name.
@end deffn

@geindex getpwall() (dans le module pwd)
@anchor{library/pwd pwd getpwall}@anchor{4715}
@deffn {Fonction} pwd.getpwall ()

Return a list of all available password database entries, in arbitrary order.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{65,,grp}

Interface pour la base de données des groupes, similaire à celle-ci.
@end table


@node grp --- The group database,termios --- POSIX style tty control,pwd --- The password database,Services spécifiques à Unix
@anchor{library/grp doc}@anchor{4716}@anchor{library/grp grp-the-group-database}@anchor{4717}@anchor{library/grp module-grp}@anchor{65}
@subsection @code{grp} --- The group database


@geindex module; grp


__________________________________________________________________


This module provides access to the Unix group database. It is available on all
Unix versions.

@ref{1ce0,,Availability}: Unix, not WASI, not Android, not iOS.

Group database entries are reported as a tuple-like object, whose attributes
correspond to the members of the @code{group} structure (Attribute field below, see
@code{<grp.h>}):


@multitable {xxxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Attribut

@tab

Signification

@item

0

@tab

gr_name

@tab

the name of the group

@item

1

@tab

gr_passwd

@tab

the (encrypted) group password;
often empty

@item

2

@tab

gr_gid

@tab

the numerical group ID

@item

3

@tab

gr_mem

@tab

all the group member's  user
names

@end multitable


The gid is an integer, name and password are strings, and the member list is a
list of strings. (Note that most users are not explicitly listed as members of
the group they are in according to the password database.  Check both databases
to get complete membership information.  Also note that a @code{gr_name} that
starts with a @code{+} or @code{-} is likely to be a YP/NIS reference and may not be
accessible via @ref{3162,,getgrnam()} or @ref{d14,,getgrgid()}.)

It defines the following items:

@geindex getgrgid() (dans le module grp)
@anchor{library/grp grp getgrgid}@anchor{d14}
@deffn {Fonction} grp.getgrgid (id)

Return the group database entry for the given numeric group ID. @ref{33a,,KeyError}
is raised if the entry asked for cannot be found.


Modifié dans la version 3.10: @ref{522,,TypeError} is raised for non-integer arguments like floats or strings.

@end deffn

@geindex getgrnam() (dans le module grp)
@anchor{library/grp grp getgrnam}@anchor{3162}
@deffn {Fonction} grp.getgrnam (name)

Return the group database entry for the given group name. @ref{33a,,KeyError} is
raised if the entry asked for cannot be found.
@end deffn

@geindex getgrall() (dans le module grp)
@anchor{library/grp grp getgrall}@anchor{151d}
@deffn {Fonction} grp.getgrall ()

Return a list of all available group entries, in arbitrary order.
@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{b1,,pwd}

An interface to the user database, similar to this.
@end table


@node termios --- POSIX style tty control,tty --- Terminal control functions,grp --- The group database,Services spécifiques à Unix
@anchor{library/termios doc}@anchor{4718}@anchor{library/termios module-termios}@anchor{e0}@anchor{library/termios termios-posix-style-tty-control}@anchor{4719}
@subsection @code{termios} --- POSIX style tty control


@geindex module; termios

@geindex POSIX;I/O control
@geindex tty;I/O control


__________________________________________________________________


Ce module fournit une interface aux appels POSIX pour le contrôle des entrées-sorties d'un terminal. Pour une description complète de ces appels, voir la page du manuel UNIX @code{termios(3)@footnote{https://manpages.debian.org/termios(3)}}. Il n'est disponible que pour les versions Unix qui gèrent le contrôle des entrées-sorties du terminal à travers des appels POSIX `termios' configurés à l’installation.

@ref{1ce0,,Availability}: Unix.

Toutes les fonctions de ce module prennent un descripteur de fichier `fd' comme premier argument. Ça peut être un descripteur de fichiers entier, tel que le renvoie @code{sys.stdin.fileno()}, ou un @ref{11a0,,file object}, tel que @code{sys.stdin}.

Ce module définit aussi toutes les constantes nécessaires pour travailler avec les fonctions fournies ici ; elles ont les mêmes noms que leurs équivalents en C. Pour plus d’informations sur l’utilisation de ces terminaux, veuillez vous référer à votre documentation système.

Le module définit les fonctions suivantes :

@geindex tcgetattr() (dans le module termios)
@anchor{library/termios termios tcgetattr}@anchor{15ff}
@deffn {Fonction} termios.tcgetattr (fd)

Renvoie une liste contenant les attributs du terminal pour le descripteur de fichier `fd', tel que : @code{[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]} où `cc' est une liste de caractères spéciaux du terminal (chacun est une chaine de caractère de longueur 1, à l’exception des éléments ayant les indices @code{VMIN} et @code{VTIME}, ceux-ci sont alors des entiers quand ces champs sont définis). L’interprétation des options (`flags' en anglais) et des vitesses ainsi que l’indexation dans le tableau `cc' doivent être faites en utilisant les constantes symboliques définies dans le module @ref{e0,,termios}.
@end deffn

@geindex tcsetattr() (dans le module termios)
@anchor{library/termios termios tcsetattr}@anchor{1681}
@deffn {Fonction} termios.tcsetattr (fd, when, attributes)

Set the tty attributes for file descriptor `fd' from the `attributes', which is
a list like the one returned by @ref{15ff,,tcgetattr()}.  The `when' argument
determines when the attributes are changed:

@geindex TCSANOW (dans le module termios)
@anchor{library/termios termios TCSANOW}@anchor{471a}
@deffn {Données} termios.TCSANOW

Change attributes immediately.
@end deffn

@geindex TCSADRAIN (dans le module termios)
@anchor{library/termios termios TCSADRAIN}@anchor{471b}
@deffn {Données} termios.TCSADRAIN

Change attributes after transmitting all queued output.
@end deffn

@geindex TCSAFLUSH (dans le module termios)
@anchor{library/termios termios TCSAFLUSH}@anchor{471c}
@deffn {Données} termios.TCSAFLUSH

Change attributes after transmitting all queued output and
discarding all queued input.
@end deffn
@end deffn

@geindex tcsendbreak() (dans le module termios)
@anchor{library/termios termios tcsendbreak}@anchor{471d}
@deffn {Fonction} termios.tcsendbreak (fd, duration)

Envoie une pause sur le descripteur de fichier `fd'. Une `duration' à zéro envoie une pause de 0,25 à 0,5 seconde ; une `duration' différente de zéro possède une signification spécifique sur chaque système.
@end deffn

@geindex tcdrain() (dans le module termios)
@anchor{library/termios termios tcdrain}@anchor{471e}
@deffn {Fonction} termios.tcdrain (fd)

Attend que toutes les sorties écrites dans le descripteur de fichier `fd' soient transmises.
@end deffn

@geindex tcflush() (dans le module termios)
@anchor{library/termios termios tcflush}@anchor{471f}
@deffn {Fonction} termios.tcflush (fd, queue)

Vide la queue de données du descripteur de fichier `fd'. Le sélecteur `queue' précise la queue : @code{TCIFLUSH} pour la queue des entrées, @code{TCOFLUSH} pour la queue des sorties, ou @code{TCIOFLUSH} pour les deux queues.
@end deffn

@geindex tcflow() (dans le module termios)
@anchor{library/termios termios tcflow}@anchor{4720}
@deffn {Fonction} termios.tcflow (fd, action)

Suspend ou reprend l’entrée ou la sortie du descripteur de fichier `fd'. L’argument `action' peut être @code{TCOOFF} pour suspendre la sortie, @code{TCOON} pour relancer la sortie, @code{TCIOFF} pour suspendre l’entrée, ou @code{TCION} pour relancer l’entrée.
@end deffn

@geindex tcgetwinsize() (dans le module termios)
@anchor{library/termios termios tcgetwinsize}@anchor{4721}
@deffn {Fonction} termios.tcgetwinsize (fd)

Return a tuple @code{(ws_row, ws_col)} containing the tty window size for file
descriptor `fd'. Requires @code{termios.TIOCGWINSZ} or
@code{termios.TIOCGSIZE}.


Ajouté dans la version 3.11.

@end deffn

@geindex tcsetwinsize() (dans le module termios)
@anchor{library/termios termios tcsetwinsize}@anchor{4722}
@deffn {Fonction} termios.tcsetwinsize (fd, winsize)

Set the tty window size for file descriptor `fd' from `winsize', which is
a two-item tuple @code{(ws_row, ws_col)} like the one returned by
@ref{4721,,tcgetwinsize()}. Requires at least one of the pairs
(@code{termios.TIOCGWINSZ}, @code{termios.TIOCSWINSZ});
(@code{termios.TIOCGSIZE}, @code{termios.TIOCSSIZE}) to be defined.


Ajouté dans la version 3.11.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Le module @ref{ff,,tty}

Fonctions utiles pour les opérations de contrôle communes dans le terminal.
@end table


@menu
* Exemple: Exemple<16>. 

@end menu

@node Exemple<16>,,,termios --- POSIX style tty control
@anchor{library/termios example}@anchor{4723}@anchor{library/termios termios-example}@anchor{4724}
@subsubsection Exemple


Voici une fonction qui demande à l’utilisateur d’entrer un mot de passe sans l’afficher. Remarquez la technique qui consiste à séparer un appel à @ref{15ff,,tcgetattr()} et une instruction @ref{6d3,,try}… @ref{9b8,,finally} pour s’assurer que les anciens attributs du terminal soient restaurés tels quels quoi qu’il arrive :

@example
def getpass(prompt="Password: "):
    import termios, sys
    fd = sys.stdin.fileno()
    old = termios.tcgetattr(fd)
    new = termios.tcgetattr(fd)
    new[3] = new[3] & ~termios.ECHO          # lflags
    try:
        termios.tcsetattr(fd, termios.TCSADRAIN, new)
        passwd = input(prompt)
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old)
    return passwd
@end example

@node tty --- Terminal control functions,pty --- Pseudo-terminal utilities,termios --- POSIX style tty control,Services spécifiques à Unix
@anchor{library/tty doc}@anchor{4725}@anchor{library/tty module-tty}@anchor{ff}@anchor{library/tty tty-terminal-control-functions}@anchor{4726}
@subsection @code{tty} --- Terminal control functions


@geindex module; tty

`Code source :' Lib/tty.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/tty.py}


__________________________________________________________________


Le module @ref{ff,,tty} expose des fonctions permettant de mettre le `tty' en mode `cbreak' ou `raw'.

@ref{1ce0,,Availability}: Unix.

Puisqu'il a besoin du module @ref{e0,,termios}, il ne fonctionnera que sur Unix.

Le module @ref{ff,,tty} définit les fonctions suivantes :

@geindex cfmakeraw() (dans le module tty)
@anchor{library/tty tty cfmakeraw}@anchor{1656}
@deffn {Fonction} tty.cfmakeraw (mode)

Convert the tty attribute list `mode', which is a list like the one returned
by @ref{15ff,,termios.tcgetattr()}, to that of a tty in raw mode.


Ajouté dans la version 3.12.

@end deffn

@geindex cfmakecbreak() (dans le module tty)
@anchor{library/tty tty cfmakecbreak}@anchor{1602}
@deffn {Fonction} tty.cfmakecbreak (mode)

Convert the tty attribute list `mode', which is a list like the one returned
by @ref{15ff,,termios.tcgetattr()}, to that of a tty in cbreak mode.

This clears the @code{ECHO} and @code{ICANON} local mode flags in `mode' as well
as setting the minimum input to 1 byte with no delay.


Ajouté dans la version 3.12.



Modifié dans la version 3.12.2: The @code{ICRNL} flag is no longer cleared. This matches Linux and macOS
@code{stty cbreak} behavior and what @ref{1601,,setcbreak()} historically did.

@end deffn

@geindex setraw() (dans le module tty)
@anchor{library/tty tty setraw}@anchor{1655}
@deffn {Fonction} tty.setraw (fd, when=termios.TCSAFLUSH)

Change the mode of the file descriptor `fd' to raw. If `when' is omitted, it
defaults to @ref{471c,,termios.TCSAFLUSH}, and is passed to
@ref{1681,,termios.tcsetattr()}. The return value of @ref{15ff,,termios.tcgetattr()}
is saved before setting `fd' to raw mode; this value is returned.


Modifié dans la version 3.12: The return value is now the original tty attributes, instead of @code{None}.

@end deffn

@geindex setcbreak() (dans le module tty)
@anchor{library/tty tty setcbreak}@anchor{1601}
@deffn {Fonction} tty.setcbreak (fd, when=termios.TCSAFLUSH)

Change the mode of file descriptor `fd' to cbreak. If `when' is omitted, it
defaults to @ref{471c,,termios.TCSAFLUSH}, and is passed to
@ref{1681,,termios.tcsetattr()}. The return value of @ref{15ff,,termios.tcgetattr()}
is saved before setting `fd' to cbreak mode; this value is returned.

This clears the @code{ECHO} and @code{ICANON} local mode flags as well as setting
the minimum input to 1 byte with no delay.


Modifié dans la version 3.12: The return value is now the original tty attributes, instead of @code{None}.



Modifié dans la version 3.12.2: The @code{ICRNL} flag is no longer cleared. This restores the behavior
of Python 3.11 and earlier as well as matching what Linux, macOS, & BSDs
describe in their @code{stty(1)} man pages regarding cbreak mode.

@end deffn


@subsubheading Voir aussi



@table @asis

@item Module @ref{e0,,termios}

Interface bas niveau de gestion du terminal.
@end table


@node pty --- Pseudo-terminal utilities,fcntl --- The fcntl and ioctl system calls,tty --- Terminal control functions,Services spécifiques à Unix
@anchor{library/pty doc}@anchor{4727}@anchor{library/pty module-pty}@anchor{b0}@anchor{library/pty pty-pseudo-terminal-utilities}@anchor{4728}
@subsection @code{pty} --- Pseudo-terminal utilities


@geindex module; pty

`Code source :' Lib/pty.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/pty.py}


__________________________________________________________________


Le module @ref{b0,,pty} expose des fonctions de manipulation de pseudo-terminaux, il permet d'écrire un programme capable de démarrer un autre processus, d'écrire et de lire depuis son terminal.

@ref{1ce0,,Availability}: Unix.

Pseudo-terminal handling is highly platform dependent. This code is mainly
tested on Linux, FreeBSD, and macOS (it is supposed to work on other POSIX
platforms but it's not been thoroughly tested).

Le module @ref{b0,,pty} expose les fonctions suivantes :

@geindex fork() (dans le module pty)
@anchor{library/pty pty fork}@anchor{16e6}
@deffn {Fonction} pty.fork ()

`Fork'. Connecte le terminal contrôlé par le fils à un pseudo-terminal. La valeur renvoyée est @code{(pid, fd)}. Notez que le fils obtient @code{0} comme `pid' et un `fd' non valide. Le parent obtient le `pid' du fils, et `fd' un descripteur de fichier connecté à un terminal contrôlé par le fils (et donc à l'entrée et la sortie standard du fils).

@cartouche
@quotation Avertissement 
On macOS the use of this function is unsafe when mixed with using
higher-level system APIs, and that includes using @ref{10a,,urllib.request}.
@end quotation
@end cartouche
@end deffn

@geindex openpty() (dans le module pty)
@anchor{library/pty pty openpty}@anchor{2cc}
@deffn {Fonction} pty.openpty ()

Ouvre une nouvelle paire de pseudo-terminaux, en utilisant si possible @ref{2ae3,,os.openpty()}, ou du code émulant la fonctionnalité pour des systèmes `Unix' génériques. Renvoie une paire de descripteurs de fichier @code{(master, slave)}, pour le maître et pour l'esclave respectivement.
@end deffn

@geindex spawn() (dans le module pty)
@anchor{library/pty pty spawn}@anchor{f6d}
@deffn {Fonction} pty.spawn (argv[, master_read[, stdin_read]])

Crée un nouveau processus et connecte son terminal aux entrées/sorties standard du processus courant. Cette stratégie est typiquement utilisée pour les programmes qui veulent lire depuis leur propre terminal. Le processus créé utilisant le `pty' est supposé se terminer et, quand il le fera, l'appel de `spawn' terminera.

A loop copies STDIN of the current process to the child and data received
from the child to STDOUT of the current process. It is not signaled to the
child if STDIN of the current process closes down.

The functions `master_read' and `stdin_read' are passed a file descriptor
which they should read from, and they should always return a byte string. In
order to force spawn to return before the child process exits an
empty byte array should be returned to signal end of file.

L'implémentation par défaut pour les deux fonctions lit et renvoie jusqu'à 1024 octets à chaque appel de la fonction. La fonction de rappel `master_read' reçoit le descripteur de fichier du pseudo-terminal maître pour lire la sortie du processus enfant, et `stdin_read' reçoit le descripteur de fichier 0, pour lire l'entrée standard du processus parent.

Le renvoi d'une chaîne d'octets vide à partir de l'un ou l'autre des rappels est interprété comme une condition de fin de fichier (EOF), et ce rappel ne sera pas appelé après cela. Si `stdin_read' signale EOF, le terminal de contrôle ne peut plus communiquer avec le processus parent OU le processus enfant. À moins que le processus enfant ne quitte sans aucune entrée, `spawn' sera lancé dans une boucle infinie. Si `master_read' indique la fin de fichier, on aura le même comportement (sur Linux au moins).

Return the exit status value from @ref{d87,,os.waitpid()} on the child process.

@ref{90a,,os.waitstatus_to_exitcode()} can be used to convert the exit status into
an exit code.

Raises an @ref{1848,,auditing event} @code{pty.spawn} with argument @code{argv}.


Modifié dans la version 3.4: @ref{f6d,,spawn()} renvoie maintenant la valeur renvoyée par @ref{d87,,os.waitpid()} sur le processus fils.

@end deffn

@menu
* Exemple: Exemple<17>. 

@end menu

@node Exemple<17>,,,pty --- Pseudo-terminal utilities
@anchor{library/pty example}@anchor{4729}
@subsubsection Exemple


Le programme suivant se comporte comme la commande Unix @code{script(1)@footnote{https://manpages.debian.org/script(1)}}, utilisant un pseudo-terminal pour enregistrer toutes les entrées et sorties d'une session dans un fichier `typescript'.

@example
import argparse
import os
import pty
import sys
import time

parser = argparse.ArgumentParser()
parser.add_argument('-a', dest='append', action='store_true')
parser.add_argument('-p', dest='use_python', action='store_true')
parser.add_argument('filename', nargs='?', default='typescript')
options = parser.parse_args()

shell = sys.executable if options.use_python else os.environ.get('SHELL', 'sh')
filename = options.filename
mode = 'ab' if options.append else 'wb'

with open(filename, mode) as script:
    def read(fd):
        data = os.read(fd, 1024)
        script.write(data)
        return data

    print('Script started, file is', filename)
    script.write(('Script started on %s\n' % time.asctime()).encode())

    pty.spawn(shell, read)

    script.write(('Script done on %s\n' % time.asctime()).encode())
    print('Script done, file is', filename)
@end example

@node fcntl --- The fcntl and ioctl system calls,resource --- Resource usage information,pty --- Pseudo-terminal utilities,Services spécifiques à Unix
@anchor{library/fcntl doc}@anchor{472a}@anchor{library/fcntl fcntl-the-fcntl-and-ioctl-system-calls}@anchor{472b}@anchor{library/fcntl module-fcntl}@anchor{58}
@subsection @code{fcntl} --- The @code{fcntl} and @code{ioctl} system calls


@geindex module; fcntl

@geindex UNIX;file control
@geindex UNIX;I/O control


__________________________________________________________________


This module performs file and I/O control on file descriptors. It is an
interface to the @code{fcntl()} and @code{ioctl()} Unix routines.
See the @code{fcntl(2)@footnote{https://manpages.debian.org/fcntl(2)}} and @code{ioctl(2)@footnote{https://manpages.debian.org/ioctl(2)}} Unix manual pages
for full details.

@ref{1ce0,,Availability}: Unix, not WASI.

All functions in this module take a file descriptor `fd' as their first
argument.  This can be an integer file descriptor, such as returned by
@code{sys.stdin.fileno()}, or an @ref{1f2,,io.IOBase} object, such as @code{sys.stdin}
itself, which provides a @ref{27cf,,fileno()} that returns a genuine file
descriptor.


Modifié dans la version 3.3: Operations in this module used to raise an @ref{103b,,IOError} where they now
raise an @ref{40d,,OSError}.



Modifié dans la version 3.8: The @code{fcntl} module now contains @code{F_ADD_SEALS}, @code{F_GET_SEALS}, and
@code{F_SEAL_*} constants for sealing of @ref{9f9,,os.memfd_create()} file
descriptors.



Modifié dans la version 3.9: On macOS, the @code{fcntl} module exposes the @code{F_GETPATH} constant,
which obtains the path of a file from a file descriptor.
On Linux(>=3.15), the @code{fcntl} module exposes the @code{F_OFD_GETLK},
@code{F_OFD_SETLK} and @code{F_OFD_SETLKW} constants, which are used when working
with open file description locks.



Modifié dans la version 3.10: On Linux >= 2.6.11, the @code{fcntl} module exposes the @code{F_GETPIPE_SZ} and
@code{F_SETPIPE_SZ} constants, which allow to check and modify a pipe's size
respectively.



Modifié dans la version 3.11: On FreeBSD, the @code{fcntl} module exposes the @code{F_DUP2FD} and
@code{F_DUP2FD_CLOEXEC} constants, which allow to duplicate a file descriptor,
the latter setting @code{FD_CLOEXEC} flag in addition.



Modifié dans la version 3.12: On Linux >= 4.5, the @ref{58,,fcntl} module exposes the @code{FICLONE} and
@code{FICLONERANGE} constants, which allow to share some data of one file with
another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and
XFS). This behavior is commonly referred to as "copy-on-write".



Modifié dans la version 3.13: On Linux >= 2.6.32, the @code{fcntl} module exposes the
@code{F_GETOWN_EX}, @code{F_SETOWN_EX}, @code{F_OWNER_TID}, @code{F_OWNER_PID}, @code{F_OWNER_PGRP} constants, which allow to direct I/O availability signals
to a specific thread, process, or process group.
On Linux >= 4.13, the @code{fcntl} module exposes the
@code{F_GET_RW_HINT}, @code{F_SET_RW_HINT}, @code{F_GET_FILE_RW_HINT},
@code{F_SET_FILE_RW_HINT}, and @code{RWH_WRITE_LIFE_*} constants, which allow
to inform the kernel about the relative expected lifetime of writes on
a given inode or via a particular open file description.
On Linux >= 5.1 and NetBSD, the @code{fcntl} module exposes the
@code{F_SEAL_FUTURE_WRITE} constant for use with @code{F_ADD_SEALS} and
@code{F_GET_SEALS} operations.
On FreeBSD, the @code{fcntl} module exposes the @code{F_READAHEAD}, @code{F_ISUNIONSTACK}, and @code{F_KINFO} constants.
On macOS and FreeBSD, the @code{fcntl} module exposes the @code{F_RDAHEAD}
constant.
On NetBSD and AIX, the @code{fcntl} module exposes the @code{F_CLOSEM}
constant.
On NetBSD, the @code{fcntl} module exposes the @code{F_MAXFD} constant.
On macOS and NetBSD, the @code{fcntl} module exposes the @code{F_GETNOSIGPIPE}
and @code{F_SETNOSIGPIPE} constant.


Le module définit les fonctions suivantes :

@geindex fcntl() (dans le module fcntl)
@anchor{library/fcntl fcntl fcntl}@anchor{33a1}
@deffn {Fonction} fcntl.fcntl (fd, cmd, arg=0)

Perform the operation `cmd' on file descriptor `fd' (file objects providing
a @ref{27cf,,fileno()} method are accepted as well).  The values used
for `cmd' are operating system dependent, and are available as constants
in the @ref{58,,fcntl} module, using the same names as used in the relevant C
header files. The argument `arg' can either be an integer value, or a
@ref{1bd,,bytes} object. With an integer value, the return value of this
function is the integer return value of the C @code{fcntl()} call.  When
the argument is bytes it represents a binary structure, e.g. created by
@ref{1255,,struct.pack()}. The binary data is copied to a buffer whose address is
passed to the C @code{fcntl()} call.  The return value after a successful
call is the contents of the buffer, converted to a @ref{1bd,,bytes} object.
The length of the returned object will be the same as the length of the
`arg' argument. This is limited to 1024 bytes. If the information returned
in the buffer by the operating system is larger than 1024 bytes, this is
most likely to result in a segmentation violation or a more subtle data
corruption.

If the @code{fcntl()} call fails, an @ref{40d,,OSError} is raised.

Raises an @ref{1848,,auditing event} @code{fcntl.fcntl} with arguments @code{fd}, @code{cmd}, @code{arg}.
@end deffn

@geindex ioctl() (dans le module fcntl)
@anchor{library/fcntl fcntl ioctl}@anchor{142e}
@deffn {Fonction} fcntl.ioctl (fd, request, arg=0, mutate_flag=True)

This function is identical to the @ref{33a1,,fcntl()} function, except
that the argument handling is even more complicated.

The `request' parameter is limited to values that can fit in 32-bits.
Additional constants of interest for use as the `request' argument can be
found in the @ref{e0,,termios} module, under the same names as used in
the relevant C header files.

The parameter `arg' can be one of an integer, an object supporting the
read-only buffer interface (like @ref{1bd,,bytes}) or an object supporting
the read-write buffer interface (like @ref{528,,bytearray}).

In all but the last case, behaviour is as for the @ref{33a1,,fcntl()}
function.

If a mutable buffer is passed, then the behaviour is determined by the value of
the `mutate_flag' parameter.

If it is false, the buffer's mutability is ignored and behaviour is as for a
read-only buffer, except that the 1024 byte limit mentioned above is avoided --
so long as the buffer you pass is at least as long as what the operating system
wants to put there, things should work.

If `mutate_flag' is true (the default), then the buffer is (in effect) passed
to the underlying @ref{142e,,ioctl()} system call, the latter's return code is
passed back to the calling Python, and the buffer's new contents reflect the
action of the @ref{142e,,ioctl()}.  This is a slight simplification, because if the
supplied buffer is less than 1024 bytes long it is first copied into a static
buffer 1024 bytes long which is then passed to @ref{142e,,ioctl()} and copied back
into the supplied buffer.

If the @code{ioctl()} call fails, an @ref{40d,,OSError} exception is raised.

Un exemple :

@example
>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])
@end example

Raises an @ref{1848,,auditing event} @code{fcntl.ioctl} with arguments @code{fd}, @code{request}, @code{arg}.
@end deffn

@geindex flock() (dans le module fcntl)
@anchor{library/fcntl fcntl flock}@anchor{4116}
@deffn {Fonction} fcntl.flock (fd, operation)

Perform the lock operation `operation' on file descriptor `fd' (file objects providing
a @ref{27cf,,fileno()} method are accepted as well). See the Unix manual
@code{flock(2)@footnote{https://manpages.debian.org/flock(2)}} for details.  (On some systems, this function is emulated
using @code{fcntl()}.)

If the @code{flock()} call fails, an @ref{40d,,OSError} exception is raised.

Raises an @ref{1848,,auditing event} @code{fcntl.flock} with arguments @code{fd}, @code{operation}.
@end deffn

@geindex lockf() (dans le module fcntl)
@anchor{library/fcntl fcntl lockf}@anchor{13a3}
@deffn {Fonction} fcntl.lockf (fd, cmd, len=0, start=0, whence=0)

This is essentially a wrapper around the @ref{33a1,,fcntl()} locking calls.
`fd' is the file descriptor (file objects providing a @ref{27cf,,fileno()}
method are accepted as well) of the file to lock or unlock, and `cmd'
is one of the following values:

@geindex LOCK_UN (dans le module fcntl)
@anchor{library/fcntl fcntl LOCK_UN}@anchor{472c}
@deffn {Données} fcntl.LOCK_UN

Release an existing lock.
@end deffn

@geindex LOCK_SH (dans le module fcntl)
@anchor{library/fcntl fcntl LOCK_SH}@anchor{472d}
@deffn {Données} fcntl.LOCK_SH

Acquire a shared lock.
@end deffn

@geindex LOCK_EX (dans le module fcntl)
@anchor{library/fcntl fcntl LOCK_EX}@anchor{472e}
@deffn {Données} fcntl.LOCK_EX

Acquire an exclusive lock.
@end deffn

@geindex LOCK_NB (dans le module fcntl)
@anchor{library/fcntl fcntl LOCK_NB}@anchor{472f}
@deffn {Données} fcntl.LOCK_NB

Bitwise OR with any of the other three @code{LOCK_*} constants to make
the request non-blocking.
@end deffn

If @code{LOCK_NB} is used and the lock cannot be acquired, an
@ref{40d,,OSError} will be raised and the exception will have an `errno'
attribute set to @ref{2234,,EACCES} or @ref{2225,,EAGAIN} (depending on the
operating system; for portability, check for both values).  On at least some
systems, @code{LOCK_EX} can only be used if the file descriptor refers to a
file opened for writing.

`len' is the number of bytes to lock, `start' is the byte offset at
which the lock starts, relative to `whence', and `whence' is as with
@ref{126a,,io.IOBase.seek()}, specifically:


@itemize *

@item 
@code{0} -- relative to the start of the file (@ref{126b,,os.SEEK_SET})

@item 
@code{1} -- relative to the current buffer position (@ref{126c,,os.SEEK_CUR})

@item 
@code{2} -- relative to the end of the file (@ref{126d,,os.SEEK_END})
@end itemize

The default for `start' is 0, which means to start at the beginning of the file.
The default for `len' is 0 which means to lock to the end of the file.  The
default for `whence' is also 0.

Raises an @ref{1848,,auditing event} @code{fcntl.lockf} with arguments @code{fd}, @code{cmd}, @code{len}, @code{start}, @code{whence}.
@end deffn

Examples (all on a SVR4 compliant system):

@example
import struct, fcntl, os

f = open(...)
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)

lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
@end example

Note that in the first example the return value variable `rv' will hold an
integer value; in the second example it will hold a @ref{1bd,,bytes} object.  The
structure lay-out for the `lockdata' variable is system dependent --- therefore
using the @ref{4116,,flock()} call may be better.


@subsubheading Voir aussi



@table @asis

@item Module @ref{a0,,os}

If the locking flags @ref{13e5,,O_SHLOCK} and @ref{13e6,,O_EXLOCK} are
present in the @ref{a0,,os} module (on BSD only), the @ref{d7f,,os.open()}
function provides an alternative to the @ref{13a3,,lockf()} and @ref{4116,,flock()}
functions.
@end table


@node resource --- Resource usage information,syslog --- Unix syslog library routines,fcntl --- The fcntl and ioctl system calls,Services spécifiques à Unix
@anchor{library/resource doc}@anchor{4730}@anchor{library/resource module-resource}@anchor{bb}@anchor{library/resource resource-resource-usage-information}@anchor{4731}
@subsection @code{resource} --- Resource usage information


@geindex module; resource


__________________________________________________________________


This module provides basic mechanisms for measuring and controlling system
resources utilized by a program.

@ref{1ce0,,Availability}: Unix, not WASI.

Symbolic constants are used to specify particular system resources and to
request usage information about either the current process or its children.

An @ref{40d,,OSError} is raised on syscall failure.

@geindex error
@anchor{library/resource resource error}@anchor{4732}
@deffn {Exception} resource.error

A deprecated alias of @ref{40d,,OSError}.


Modifié dans la version 3.3: Following 
@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/}, this class was made an alias of @ref{40d,,OSError}.

@end deffn

@menu
* Resource Limits:: 
* Resource Usage:: 

@end menu

@node Resource Limits,Resource Usage,,resource --- Resource usage information
@anchor{library/resource resource-limits}@anchor{4733}
@subsubsection Resource Limits


Resources usage can be limited using the @ref{40b9,,setrlimit()} function described
below. Each resource is controlled by a pair of limits: a soft limit and a hard
limit. The soft limit is the current limit, and may be lowered or raised by a
process over time. The soft limit can never exceed the hard limit. The hard
limit can be lowered to any value greater than the soft limit, but not raised.
(Only processes with the effective UID of the super-user can raise a hard
limit.)

The specific resources that can be limited are system dependent. They are
described in the @code{getrlimit(2)@footnote{https://manpages.debian.org/getrlimit(2)}} man page.  The resources listed below
are supported when the underlying operating system supports them; resources
which cannot be checked or controlled by the operating system are not defined in
this module for those platforms.

@geindex RLIM_INFINITY (dans le module resource)
@anchor{library/resource resource RLIM_INFINITY}@anchor{4734}
@deffn {Données} resource.RLIM_INFINITY

Constant used to represent the limit for an unlimited resource.
@end deffn

@geindex getrlimit() (dans le module resource)
@anchor{library/resource resource getrlimit}@anchor{4735}
@deffn {Fonction} resource.getrlimit (resource)

Returns a tuple @code{(soft, hard)} with the current soft and hard limits of
`resource'. Raises @ref{1ff,,ValueError} if an invalid resource is specified, or
@ref{4732,,error} if the underlying system call fails unexpectedly.
@end deffn

@geindex setrlimit() (dans le module resource)
@anchor{library/resource resource setrlimit}@anchor{40b9}
@deffn {Fonction} resource.setrlimit (resource, limits)

Sets new limits of consumption of `resource'. The `limits' argument must be a
tuple @code{(soft, hard)} of two integers describing the new limits. A value of
@ref{4734,,RLIM_INFINITY} can be used to request a limit that is
unlimited.

Raises @ref{1ff,,ValueError} if an invalid resource is specified, if the new soft
limit exceeds the hard limit, or if a process tries to raise its hard limit.
Specifying a limit of @ref{4734,,RLIM_INFINITY} when the hard or
system limit for that resource is not unlimited will result in a
@ref{1ff,,ValueError}.  A process with the effective UID of super-user can
request any valid limit value, including unlimited, but @ref{1ff,,ValueError}
will still be raised if the requested limit exceeds the system imposed
limit.

@code{setrlimit} may also raise @ref{4732,,error} if the underlying system call
fails.

VxWorks only supports setting @ref{4736,,RLIMIT_NOFILE}.

Raises an @ref{1848,,auditing event} @code{resource.setrlimit} with arguments @code{resource}, @code{limits}.
@end deffn

@geindex prlimit() (dans le module resource)
@anchor{library/resource resource prlimit}@anchor{f74}
@deffn {Fonction} resource.prlimit (pid, resource[, limits])

Combines @ref{40b9,,setrlimit()} and @ref{4735,,getrlimit()} in one function and
supports to get and set the resources limits of an arbitrary process. If
`pid' is 0, then the call applies to the current process. `resource' and
`limits' have the same meaning as in @ref{40b9,,setrlimit()}, except that
`limits' is optional.

When `limits' is not given the function returns the `resource' limit of the
process `pid'. When `limits' is given the `resource' limit of the process is
set and the former resource limit is returned.

Raises @ref{1044,,ProcessLookupError} when `pid' can't be found and
@ref{d30,,PermissionError} when the user doesn't have @code{CAP_SYS_RESOURCE} for
the process.

Raises an @ref{1848,,auditing event} @code{resource.prlimit} with arguments @code{pid}, @code{resource}, @code{limits}.

@ref{1ce0,,Availability}: Linux >= 2.6.36 with glibc >= 2.13.


Ajouté dans la version 3.4.

@end deffn

These symbols define resources whose consumption can be controlled using the
@ref{40b9,,setrlimit()} and @ref{4735,,getrlimit()} functions described below. The values of
these symbols are exactly the constants used by C programs.

The Unix man page for @code{getrlimit(2)@footnote{https://manpages.debian.org/getrlimit(2)}} lists the available resources.
Note that not all systems use the same symbol or same value to denote the same
resource.  This module does not attempt to mask platform differences --- symbols
not defined for a platform will not be available from this module on that
platform.

@geindex RLIMIT_CORE (dans le module resource)
@anchor{library/resource resource RLIMIT_CORE}@anchor{40ba}
@deffn {Données} resource.RLIMIT_CORE

The maximum size (in bytes) of a core file that the current process can create.
This may result in the creation of a partial core file if a larger core would be
required to contain the entire process image.
@end deffn

@geindex RLIMIT_CPU (dans le module resource)
@anchor{library/resource resource RLIMIT_CPU}@anchor{4737}
@deffn {Données} resource.RLIMIT_CPU

The maximum amount of processor time (in seconds) that a process can use. If
this limit is exceeded, a @code{SIGXCPU} signal is sent to the process. (See
the @ref{c5,,signal} module documentation for information about how to catch this
signal and do something useful, e.g. flush open files to disk.)
@end deffn

@geindex RLIMIT_FSIZE (dans le module resource)
@anchor{library/resource resource RLIMIT_FSIZE}@anchor{4738}
@deffn {Données} resource.RLIMIT_FSIZE

The maximum size of a file which the process may create.
@end deffn

@geindex RLIMIT_DATA (dans le module resource)
@anchor{library/resource resource RLIMIT_DATA}@anchor{4739}
@deffn {Données} resource.RLIMIT_DATA

The maximum size (in bytes) of the process's heap.
@end deffn

@geindex RLIMIT_STACK (dans le module resource)
@anchor{library/resource resource RLIMIT_STACK}@anchor{473a}
@deffn {Données} resource.RLIMIT_STACK

The maximum size (in bytes) of the call stack for the current process.  This only
affects the stack of the main thread in a multi-threaded process.
@end deffn

@geindex RLIMIT_RSS (dans le module resource)
@anchor{library/resource resource RLIMIT_RSS}@anchor{473b}
@deffn {Données} resource.RLIMIT_RSS

The maximum resident set size that should be made available to the process.
@end deffn

@geindex RLIMIT_NPROC (dans le module resource)
@anchor{library/resource resource RLIMIT_NPROC}@anchor{473c}
@deffn {Données} resource.RLIMIT_NPROC

The maximum number of processes the current process may create.
@end deffn

@geindex RLIMIT_NOFILE (dans le module resource)
@anchor{library/resource resource RLIMIT_NOFILE}@anchor{4736}
@deffn {Données} resource.RLIMIT_NOFILE

The maximum number of open file descriptors for the current process.
@end deffn

@geindex RLIMIT_OFILE (dans le module resource)
@anchor{library/resource resource RLIMIT_OFILE}@anchor{473d}
@deffn {Données} resource.RLIMIT_OFILE

The BSD name for @ref{4736,,RLIMIT_NOFILE}.
@end deffn

@geindex RLIMIT_MEMLOCK (dans le module resource)
@anchor{library/resource resource RLIMIT_MEMLOCK}@anchor{473e}
@deffn {Données} resource.RLIMIT_MEMLOCK

The maximum address space which may be locked in memory.
@end deffn

@geindex RLIMIT_VMEM (dans le module resource)
@anchor{library/resource resource RLIMIT_VMEM}@anchor{473f}
@deffn {Données} resource.RLIMIT_VMEM

The largest area of mapped memory which the process may occupy.

@ref{1ce0,,Availability}: FreeBSD >= 11.
@end deffn

@geindex RLIMIT_AS (dans le module resource)
@anchor{library/resource resource RLIMIT_AS}@anchor{4740}
@deffn {Données} resource.RLIMIT_AS

The maximum area (in bytes) of address space which may be taken by the process.
@end deffn

@geindex RLIMIT_MSGQUEUE (dans le module resource)
@anchor{library/resource resource RLIMIT_MSGQUEUE}@anchor{f75}
@deffn {Données} resource.RLIMIT_MSGQUEUE

The number of bytes that can be allocated for POSIX message queues.

@ref{1ce0,,Availability}: Linux >= 2.6.8.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_NICE (dans le module resource)
@anchor{library/resource resource RLIMIT_NICE}@anchor{f76}
@deffn {Données} resource.RLIMIT_NICE

The ceiling for the process's nice level (calculated as 20 - rlim_cur).

@ref{1ce0,,Availability}: Linux >= 2.6.12.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_RTPRIO (dans le module resource)
@anchor{library/resource resource RLIMIT_RTPRIO}@anchor{f77}
@deffn {Données} resource.RLIMIT_RTPRIO

The ceiling of the real-time priority.

@ref{1ce0,,Availability}: Linux >= 2.6.12.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_RTTIME (dans le module resource)
@anchor{library/resource resource RLIMIT_RTTIME}@anchor{f78}
@deffn {Données} resource.RLIMIT_RTTIME

The time limit (in microseconds) on CPU time that a process can spend
under real-time scheduling without making a blocking syscall.

@ref{1ce0,,Availability}: Linux >= 2.6.25.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_SIGPENDING (dans le module resource)
@anchor{library/resource resource RLIMIT_SIGPENDING}@anchor{f79}
@deffn {Données} resource.RLIMIT_SIGPENDING

The number of signals which the process may queue.

@ref{1ce0,,Availability}: Linux >= 2.6.8.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_SBSIZE (dans le module resource)
@anchor{library/resource resource RLIMIT_SBSIZE}@anchor{f7a}
@deffn {Données} resource.RLIMIT_SBSIZE

The maximum size (in bytes) of socket buffer usage for this user.
This limits the amount of network memory, and hence the amount of mbufs,
that this user may hold at any time.

@ref{1ce0,,Availability}: FreeBSD.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_SWAP (dans le module resource)
@anchor{library/resource resource RLIMIT_SWAP}@anchor{f7b}
@deffn {Données} resource.RLIMIT_SWAP

The maximum size (in bytes) of the swap space that may be reserved or
used by all of this user id's processes.
This limit is enforced only if bit 1 of the vm.overcommit sysctl is set.
Please see
tuning(7)@footnote{https://man.freebsd.org/cgi/man.cgi?query=tuning&sektion=7}
for a complete description of this sysctl.

@ref{1ce0,,Availability}: FreeBSD.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_NPTS (dans le module resource)
@anchor{library/resource resource RLIMIT_NPTS}@anchor{f7c}
@deffn {Données} resource.RLIMIT_NPTS

The maximum number of pseudo-terminals created by this user id.

@ref{1ce0,,Availability}: FreeBSD.


Ajouté dans la version 3.4.

@end deffn

@geindex RLIMIT_KQUEUES (dans le module resource)
@anchor{library/resource resource RLIMIT_KQUEUES}@anchor{1876}
@deffn {Données} resource.RLIMIT_KQUEUES

The maximum number of kqueues this user id is allowed to create.

@ref{1ce0,,Availability}: FreeBSD >= 11.


Ajouté dans la version 3.10.

@end deffn

@node Resource Usage,,Resource Limits,resource --- Resource usage information
@anchor{library/resource resource-usage}@anchor{4741}
@subsubsection Resource Usage


These functions are used to retrieve resource usage information:

@geindex getrusage() (dans le module resource)
@anchor{library/resource resource getrusage}@anchor{13e7}
@deffn {Fonction} resource.getrusage (who)

This function returns an object that describes the resources consumed by either
the current process or its children, as specified by the `who' parameter.  The
`who' parameter should be specified using one of the @code{RUSAGE_*}
constants described below.

Un exemple simple :

@example
from resource import *
import time

# a non CPU-bound task
time.sleep(3)
print(getrusage(RUSAGE_SELF))

# a CPU-bound task
for i in range(10 ** 8):
   _ = 1 + 1
print(getrusage(RUSAGE_SELF))
@end example

The fields of the return value each describe how a particular system resource
has been used, e.g. amount of time spent running is user mode or number of times
the process was swapped out of main memory. Some values are dependent on the
clock tick internal, e.g. the amount of memory the process is using.

For backward compatibility, the return value is also accessible as a tuple of 16
elements.

The fields @code{ru_utime} and @code{ru_stime} of the return value are
floating-point values representing the amount of time spent executing in user
mode and the amount of time spent executing in system mode, respectively. The
remaining values are integers. Consult the @code{getrusage(2)@footnote{https://manpages.debian.org/getrusage(2)}} man page for
detailed information about these values. A brief summary is presented here:


@multitable {xxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Index

@tab

Champ

@tab

Resource

@item

@code{0}

@tab

@code{ru_utime}

@tab

time in user mode (float seconds)

@item

@code{1}

@tab

@code{ru_stime}

@tab

time in system mode (float seconds)

@item

@code{2}

@tab

@code{ru_maxrss}

@tab

maximum resident set size

@item

@code{3}

@tab

@code{ru_ixrss}

@tab

shared memory size

@item

@code{4}

@tab

@code{ru_idrss}

@tab

unshared memory size

@item

@code{5}

@tab

@code{ru_isrss}

@tab

unshared stack size

@item

@code{6}

@tab

@code{ru_minflt}

@tab

page faults not requiring I/O

@item

@code{7}

@tab

@code{ru_majflt}

@tab

page faults requiring I/O

@item

@code{8}

@tab

@code{ru_nswap}

@tab

number of swap outs

@item

@code{9}

@tab

@code{ru_inblock}

@tab

block input operations

@item

@code{10}

@tab

@code{ru_oublock}

@tab

block output operations

@item

@code{11}

@tab

@code{ru_msgsnd}

@tab

messages sent

@item

@code{12}

@tab

@code{ru_msgrcv}

@tab

messages received

@item

@code{13}

@tab

@code{ru_nsignals}

@tab

signals received

@item

@code{14}

@tab

@code{ru_nvcsw}

@tab

voluntary context switches

@item

@code{15}

@tab

@code{ru_nivcsw}

@tab

involuntary context switches

@end multitable


This function will raise a @ref{1ff,,ValueError} if an invalid `who' parameter is
specified. It may also raise @ref{4732,,error} exception in unusual circumstances.
@end deffn

@geindex getpagesize() (dans le module resource)
@anchor{library/resource resource getpagesize}@anchor{4742}
@deffn {Fonction} resource.getpagesize ()

Returns the number of bytes in a system page. (This need not be the same as the
hardware page size.)
@end deffn

The following @code{RUSAGE_*} symbols are passed to the @ref{13e7,,getrusage()}
function to specify which processes information should be provided for.

@geindex RUSAGE_SELF (dans le module resource)
@anchor{library/resource resource RUSAGE_SELF}@anchor{4743}
@deffn {Données} resource.RUSAGE_SELF

Pass to @ref{13e7,,getrusage()} to request resources consumed by the calling
process, which is the sum of resources used by all threads in the process.
@end deffn

@geindex RUSAGE_CHILDREN (dans le module resource)
@anchor{library/resource resource RUSAGE_CHILDREN}@anchor{4744}
@deffn {Données} resource.RUSAGE_CHILDREN

Pass to @ref{13e7,,getrusage()} to request resources consumed by child processes
of the calling process which have been terminated and waited for.
@end deffn

@geindex RUSAGE_BOTH (dans le module resource)
@anchor{library/resource resource RUSAGE_BOTH}@anchor{4745}
@deffn {Données} resource.RUSAGE_BOTH

Pass to @ref{13e7,,getrusage()} to request resources consumed by both the current
process and child processes.  May not be available on all systems.
@end deffn

@geindex RUSAGE_THREAD (dans le module resource)
@anchor{library/resource resource RUSAGE_THREAD}@anchor{4746}
@deffn {Données} resource.RUSAGE_THREAD

Pass to @ref{13e7,,getrusage()} to request resources consumed by the current
thread.  May not be available on all systems.


Ajouté dans la version 3.2.

@end deffn

@node syslog --- Unix syslog library routines,,resource --- Resource usage information,Services spécifiques à Unix
@anchor{library/syslog doc}@anchor{4747}@anchor{library/syslog module-syslog}@anchor{db}@anchor{library/syslog syslog-unix-syslog-library-routines}@anchor{4748}
@subsection @code{syslog} --- Unix syslog library routines


@geindex module; syslog


__________________________________________________________________


Ce module fournit une interface aux routines de la bibliothèque @code{syslog} Unix. Consultez les pages du manuel Unix pour plus de détails sur @code{syslog}.

@ref{1ce0,,Availability}: Unix, not WASI, not iOS.

This module wraps the system @code{syslog} family of routines.  A pure Python
library that can speak to a syslog server is available in the
@ref{88,,logging.handlers} module as @ref{647,,SysLogHandler}.

Le module définit les fonctions suivantes :

@geindex syslog() (dans le module syslog)
@anchor{library/syslog syslog syslog}@anchor{52b}
@deffn {Fonction} syslog.syslog (message)

@deffnx {Fonction} syslog.syslog (priority, message)

Envoie la chaîne de caractères `message' au journaliseur système. Un retour à la ligne est ajouté à la fin du message si nécessaire. Chaque message est marqué avec une priorité constituée d'une `fonction' et d'un `niveau'. L'argument optionnel `priority', qui par défaut est @ref{4749,,LOG_INFO}, définit la priorité du message. Si la fonction n'est pas encodée dans `priority' en utilisant un OU logique (@code{LOG_INFO | LOG_USER}), la valeur donnée lors de l'appel à @ref{529,,openlog()} est utilisée.

If @ref{529,,openlog()} has not been called prior to the call to @ref{db,,syslog()},
@ref{529,,openlog()} will be called with no arguments.

Lève un @ref{1848,,évènement d'audit} @code{syslog.syslog} avec les arguments @code{priority}, @code{message}.


Modifié dans la version 3.2: In previous versions, @ref{529,,openlog()} would not be called automatically if
it wasn't called prior to the call to @ref{db,,syslog()}, deferring to the syslog
implementation to call @code{openlog()}.



Modifié dans la version 3.12: This function is restricted in subinterpreters.
(Only code that runs in multiple interpreters is affected and
the restriction is not relevant for most users.)
@ref{529,,openlog()} must be called in the main interpreter before @ref{db,,syslog()} may be used
in a subinterpreter.  Otherwise it will raise @ref{193,,RuntimeError}.

@end deffn

@geindex openlog() (dans le module syslog)
@anchor{library/syslog syslog openlog}@anchor{529}
@deffn {Fonction} syslog.openlog ([ident[, logoption[, facility]]])

Les options de journalisation utilisées lors des appels à @ref{db,,syslog()} peuvent être définies en appelant @ref{529,,openlog()}.  @ref{db,,syslog()} appellera @ref{529,,openlog()} sans argument si le journal n'est pas déjà ouvert.

L'argument nommé optionnel `ident' est une chaîne de caractères qui est ajoutée au début de chaque message. Par défaut, le dernier élément du chemin définit dans @code{sys.argv[0]} est utilisé.  L'argument nommé optionnel `logoption' est un champ de bits (défini à 0 par défaut) -- Voir ci-dessous pour les combinaisons possibles.  L'argument nommé optionnel `facility' définit la fonction à utiliser pour les messages qui n'en définissent pas. Par défaut, @ref{474a,,LOG_USER} est utilisée.

Lève un @ref{1848,,évènement d'audit} @code{syslog.openlog} avec les arguments @code{ident}, @code{logoption}, @code{facility}.


Modifié dans la version 3.2: In previous versions, keyword arguments were not allowed, and `ident' was
required.



Modifié dans la version 3.12: This function is restricted in subinterpreters.
(Only code that runs in multiple interpreters is affected and
the restriction is not relevant for most users.)
This may only be called in the main interpreter.
It will raise @ref{193,,RuntimeError} if called in a subinterpreter.

@end deffn

@geindex closelog() (dans le module syslog)
@anchor{library/syslog syslog closelog}@anchor{52a}
@deffn {Fonction} syslog.closelog ()

Réinitialise la configuration du module `syslog' et appelle la bibliothèque système @code{closelog()}.

Cet appel permet au module de se comporter comme lors de son import initial.  Par exemple, @ref{529,,openlog()} sera appelée lors du premier appel à @ref{db,,syslog()} (sauf si @ref{529,,openlog()} a déjà été appelée). Quant à `ident' et aux paramètres de @ref{529,,openlog()}, ceux-ci seront réinitialisés à leur valeur par défaut.

Lève un @ref{1848,,évènement d'audit} @code{syslog.closelog} sans argument.


Modifié dans la version 3.12: This function is restricted in subinterpreters.
(Only code that runs in multiple interpreters is affected and
the restriction is not relevant for most users.)
This may only be called in the main interpreter.
It will raise @ref{193,,RuntimeError} if called in a subinterpreter.

@end deffn

@geindex setlogmask() (dans le module syslog)
@anchor{library/syslog syslog setlogmask}@anchor{411a}
@deffn {Fonction} syslog.setlogmask (maskpri)

Définit le masque de priorité à la valeur `maskpri' et retourne la précédente valeur du masque.  Les appels à @ref{db,,syslog()} avec un niveau de priorité non présent dans `maskpri' seront ignorés.  La fonction @code{LOG_MASK(pri)} calcule le masque pour la priorité `pri'.  La fonction @code{LOG_UPTO(pri)} calcule le masque pour toutes les priorités jusqu'à `pri' (inclus).

Lève un @ref{1848,,évènement d'audit} @code{syslog.setlogmask} avec l'argument @code{maskpri}.
@end deffn

Le module définit les constantes suivantes :

@geindex LOG_EMERG (dans le module syslog)
@geindex LOG_ALERT (dans le module syslog)
@geindex LOG_CRIT (dans le module syslog)
@geindex LOG_ERR (dans le module syslog)
@geindex LOG_WARNING (dans le module syslog)
@geindex LOG_NOTICE (dans le module syslog)
@geindex LOG_INFO (dans le module syslog)
@geindex LOG_DEBUG (dans le module syslog)
@anchor{library/syslog syslog LOG_EMERG}@anchor{474b}
@deffn {Données} syslog.LOG_EMERG
@anchor{library/syslog syslog LOG_ALERT}@anchor{474c}
@deffnx {Données} syslog.LOG_ALERT
@anchor{library/syslog syslog LOG_CRIT}@anchor{474d}
@deffnx {Données} syslog.LOG_CRIT
@anchor{library/syslog syslog LOG_ERR}@anchor{474e}
@deffnx {Données} syslog.LOG_ERR
@anchor{library/syslog syslog LOG_WARNING}@anchor{474f}
@deffnx {Données} syslog.LOG_WARNING
@anchor{library/syslog syslog LOG_NOTICE}@anchor{4750}
@deffnx {Données} syslog.LOG_NOTICE
@anchor{library/syslog syslog LOG_INFO}@anchor{4749}
@deffnx {Données} syslog.LOG_INFO
@anchor{library/syslog syslog LOG_DEBUG}@anchor{4751}
@deffnx {Données} syslog.LOG_DEBUG

Priority levels (high to low).
@end deffn

@geindex LOG_AUTH (dans le module syslog)
@geindex LOG_AUTHPRIV (dans le module syslog)
@geindex LOG_CRON (dans le module syslog)
@geindex LOG_DAEMON (dans le module syslog)
@geindex LOG_FTP (dans le module syslog)
@geindex LOG_INSTALL (dans le module syslog)
@geindex LOG_KERN (dans le module syslog)
@geindex LOG_LAUNCHD (dans le module syslog)
@geindex LOG_LPR (dans le module syslog)
@geindex LOG_MAIL (dans le module syslog)
@geindex LOG_NETINFO (dans le module syslog)
@geindex LOG_NEWS (dans le module syslog)
@geindex LOG_RAS (dans le module syslog)
@geindex LOG_REMOTEAUTH (dans le module syslog)
@geindex LOG_SYSLOG (dans le module syslog)
@geindex LOG_USER (dans le module syslog)
@geindex LOG_UUCP (dans le module syslog)
@geindex LOG_LOCAL0 (dans le module syslog)
@geindex LOG_LOCAL1 (dans le module syslog)
@geindex LOG_LOCAL2 (dans le module syslog)
@geindex LOG_LOCAL3 (dans le module syslog)
@geindex LOG_LOCAL4 (dans le module syslog)
@geindex LOG_LOCAL5 (dans le module syslog)
@geindex LOG_LOCAL6 (dans le module syslog)
@geindex LOG_LOCAL7 (dans le module syslog)
@anchor{library/syslog syslog LOG_AUTH}@anchor{4752}
@deffn {Données} syslog.LOG_AUTH
@anchor{library/syslog syslog LOG_AUTHPRIV}@anchor{4753}
@deffnx {Données} syslog.LOG_AUTHPRIV
@anchor{library/syslog syslog LOG_CRON}@anchor{4754}
@deffnx {Données} syslog.LOG_CRON
@anchor{library/syslog syslog LOG_DAEMON}@anchor{4755}
@deffnx {Données} syslog.LOG_DAEMON
@anchor{library/syslog syslog LOG_FTP}@anchor{4756}
@deffnx {Données} syslog.LOG_FTP
@anchor{library/syslog syslog LOG_INSTALL}@anchor{4757}
@deffnx {Données} syslog.LOG_INSTALL
@anchor{library/syslog syslog LOG_KERN}@anchor{4758}
@deffnx {Données} syslog.LOG_KERN
@anchor{library/syslog syslog LOG_LAUNCHD}@anchor{4759}
@deffnx {Données} syslog.LOG_LAUNCHD
@anchor{library/syslog syslog LOG_LPR}@anchor{475a}
@deffnx {Données} syslog.LOG_LPR
@anchor{library/syslog syslog LOG_MAIL}@anchor{475b}
@deffnx {Données} syslog.LOG_MAIL
@anchor{library/syslog syslog LOG_NETINFO}@anchor{475c}
@deffnx {Données} syslog.LOG_NETINFO
@anchor{library/syslog syslog LOG_NEWS}@anchor{475d}
@deffnx {Données} syslog.LOG_NEWS
@anchor{library/syslog syslog LOG_RAS}@anchor{475e}
@deffnx {Données} syslog.LOG_RAS
@anchor{library/syslog syslog LOG_REMOTEAUTH}@anchor{475f}
@deffnx {Données} syslog.LOG_REMOTEAUTH
@anchor{library/syslog syslog LOG_SYSLOG}@anchor{4760}
@deffnx {Données} syslog.LOG_SYSLOG
@anchor{library/syslog syslog LOG_USER}@anchor{474a}
@deffnx {Données} syslog.LOG_USER
@anchor{library/syslog syslog LOG_UUCP}@anchor{4761}
@deffnx {Données} syslog.LOG_UUCP
@anchor{library/syslog syslog LOG_LOCAL0}@anchor{4762}
@deffnx {Données} syslog.LOG_LOCAL0
@anchor{library/syslog syslog LOG_LOCAL1}@anchor{4763}
@deffnx {Données} syslog.LOG_LOCAL1
@anchor{library/syslog syslog LOG_LOCAL2}@anchor{4764}
@deffnx {Données} syslog.LOG_LOCAL2
@anchor{library/syslog syslog LOG_LOCAL3}@anchor{4765}
@deffnx {Données} syslog.LOG_LOCAL3
@anchor{library/syslog syslog LOG_LOCAL4}@anchor{4766}
@deffnx {Données} syslog.LOG_LOCAL4
@anchor{library/syslog syslog LOG_LOCAL5}@anchor{4767}
@deffnx {Données} syslog.LOG_LOCAL5
@anchor{library/syslog syslog LOG_LOCAL6}@anchor{4768}
@deffnx {Données} syslog.LOG_LOCAL6
@anchor{library/syslog syslog LOG_LOCAL7}@anchor{4769}
@deffnx {Données} syslog.LOG_LOCAL7

Facilities, depending on availability in @code{<syslog.h>} for @ref{4753,,LOG_AUTHPRIV},
@ref{4756,,LOG_FTP}, @ref{475c,,LOG_NETINFO}, @ref{475f,,LOG_REMOTEAUTH},
@ref{4757,,LOG_INSTALL} and @ref{475e,,LOG_RAS}.


Modifié dans la version 3.13: Added @ref{4756,,LOG_FTP}, @ref{475c,,LOG_NETINFO}, @ref{475f,,LOG_REMOTEAUTH},
@ref{4757,,LOG_INSTALL}, @ref{475e,,LOG_RAS}, and @ref{4759,,LOG_LAUNCHD}.

@end deffn

@geindex LOG_PID (dans le module syslog)
@geindex LOG_CONS (dans le module syslog)
@geindex LOG_NDELAY (dans le module syslog)
@geindex LOG_ODELAY (dans le module syslog)
@geindex LOG_NOWAIT (dans le module syslog)
@geindex LOG_PERROR (dans le module syslog)
@anchor{library/syslog syslog LOG_PID}@anchor{476a}
@deffn {Données} syslog.LOG_PID
@anchor{library/syslog syslog LOG_CONS}@anchor{476b}
@deffnx {Données} syslog.LOG_CONS
@anchor{library/syslog syslog LOG_NDELAY}@anchor{476c}
@deffnx {Données} syslog.LOG_NDELAY
@anchor{library/syslog syslog LOG_ODELAY}@anchor{476d}
@deffnx {Données} syslog.LOG_ODELAY
@anchor{library/syslog syslog LOG_NOWAIT}@anchor{476e}
@deffnx {Données} syslog.LOG_NOWAIT
@anchor{library/syslog syslog LOG_PERROR}@anchor{476f}
@deffnx {Données} syslog.LOG_PERROR

Log options, depending on availability in @code{<syslog.h>} for
@ref{476d,,LOG_ODELAY}, @ref{476e,,LOG_NOWAIT} and @ref{476f,,LOG_PERROR}.
@end deffn

@menu
* Exemples: Exemples<35>. 

@end menu

@node Exemples<35>,,,syslog --- Unix syslog library routines
@anchor{library/syslog examples}@anchor{4770}
@subsubsection Exemples


@menu
* Exemple simple:: 

@end menu

@node Exemple simple,,,Exemples<35>
@anchor{library/syslog simple-example}@anchor{4771}
@subsubsection Exemple simple


Un simple jeu d'exemples :

@example
import syslog

syslog.syslog('Processing started')
if error:
    syslog.syslog(syslog.LOG_ERR, 'Processing started')
@end example

Un exemple montrant comment définir certaines options de journalisation. Ces options ajoutent l'identifiant du processus (`PID') dans les messages journalisés et écrivent ces messages à l'aide de la fonction utilisée pour la journalisation des systèmes de messagerie :

@example
syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')
@end example

@node Modules command-line interface CLI,Modules remplacés,Services spécifiques à Unix,La bibliothèque standard
@anchor{library/cmdline doc}@anchor{4772}@anchor{library/cmdline modules-command-line-interface-cli}@anchor{4773}
@section Modules command-line interface (CLI)


The following modules have a command-line interface.


@itemize *

@item 
@ref{454f,,ast}

@item 
@ref{31dd,,asyncio}

@item 
@ref{e,,base64}

@item 
@ref{246d,,calendar}

@item 
@ref{1a,,code}

@item 
@ref{460c,,compileall}

@item 
@ref{27,,cProfile}: see @ref{41aa,,profile}

@item 
@ref{22bc,,difflib}

@item 
@ref{4622,,dis}

@item 
@ref{3a,,doctest}

@item 
@code{encodings.rot_13}

@item 
@ref{54,,ensurepip}

@item 
@ref{59,,filecmp}

@item 
@ref{5a,,fileinput}

@item 
@ref{5d,,ftplib}

@item 
@ref{28eb,,gzip}

@item 
@ref{f3c,,http.server}

@item 
@code{idlelib}

@item 
@ref{f46,,inspect}

@item 
@ref{35bb,,json.tool}

@item 
@ref{8e,,mimetypes}

@item 
@ref{a4,,pdb}

@item 
@ref{a5,,pickle}

@item 
@ref{4690,,pickletools}

@item 
@ref{a9,,platform}

@item 
@ref{ab,,poplib}

@item 
@ref{41aa,,profile}

@item 
@ref{af,,pstats}

@item 
@ref{4604,,py_compile}

@item 
@ref{b3,,pyclbr}

@item 
@ref{b4,,pydoc}

@item 
@ref{b6,,quopri}

@item 
@ref{153,,random}

@item 
@ref{bd,,runpy}

@item 
@ref{43fa,,site}

@item 
@ref{42a,,sqlite3}

@item 
@ref{4584,,symtable}

@item 
@ref{4303,,sysconfig}

@item 
@ref{dc,,tabnanny}

@item 
@ref{fb6,,tarfile}

@item 
@code{this}

@item 
@ref{41ca,,timeit}

@item 
@ref{45d8,,tokenize}

@item 
@ref{41e6,,trace}

@item 
@ref{101,,turtledemo}

@item 
@ref{3f92,,unittest}

@item 
@ref{42d,,uuid}

@item 
@ref{110,,venv}

@item 
@ref{114,,webbrowser}

@item 
@ref{4263,,zipapp}

@item 
@ref{2959,,zipfile}
@end itemize

See also the @ref{194d,,Python command-line interface}.

@node Modules remplacés,Removed Modules,Modules command-line interface CLI,La bibliothèque standard
@anchor{library/superseded doc}@anchor{4774}@anchor{library/superseded superseded}@anchor{4775}@anchor{library/superseded superseded-modules}@anchor{4776}
@section Modules remplacés


The modules described in this chapter have been superseded by other modules
for most use cases, and are retained primarily to preserve backwards compatibility.

Modules may appear in this chapter because they only cover a limited subset of
a problem space, and a more generally applicable solution is available elsewhere
in the standard library (for example, @ref{60,,getopt} covers the very specific
task of "mimic the C @code{getopt()} API in Python", rather than the broader
command line option parsing and argument parsing capabilities offered by
@ref{9f,,optparse} and @ref{6,,argparse}).

Alternatively, modules may appear in this chapter because they are deprecated
outright, and awaiting removal in a future release, or they are
@ref{206,,soft deprecated} and their use is actively discouraged in new projects.
With the removal of various obsolete modules through 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}, there are
currently no modules in this latter category.

@menu
* getopt: getopt --- C-style parser for command line options. C-style parser for command line options

@end menu

@node getopt --- C-style parser for command line options,,,Modules remplacés
@anchor{library/getopt doc}@anchor{4777}@anchor{library/getopt getopt-c-style-parser-for-command-line-options}@anchor{4778}@anchor{library/getopt module-getopt}@anchor{60}
@subsection @code{getopt} --- C-style parser for command line options


@geindex module; getopt

`Code source :' Lib/getopt.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/getopt.py}

@cartouche
@quotation Note 
This module is considered feature complete. A more declarative and
extensible alternative to this API is provided in the @ref{9f,,optparse}
module. Further functional enhancements for command line parameter
processing are provided either as third party modules on PyPI,
or else as features in the @ref{6,,argparse} module.
@end quotation
@end cartouche


__________________________________________________________________


This module helps scripts to parse the command line arguments in @code{sys.argv}.
It supports the same conventions as the Unix @code{getopt()} function (including
the special meanings of arguments of the form '@code{-}' and '@code{--}').  Long
options similar to those supported by GNU software may be used as well via an
optional third argument.

Users who are unfamiliar with the Unix @code{getopt()} function should consider
using the @ref{6,,argparse} module instead. Users who are familiar with the Unix
@code{getopt()} function, but would like to get equivalent behavior while
writing less code and getting better help and error messages should consider
using the @ref{9f,,optparse} module. See @ref{2dcd,,Choosing an argument parsing library} for
additional details.

Ce module fournit deux fonctions et une exception :

@geindex getopt() (dans le module getopt)
@anchor{library/getopt getopt getopt}@anchor{146f}
@deffn {Fonction} getopt.getopt (args, shortopts, longopts=[])

Parses command line options and parameter list.  `args' is the argument list to
be parsed, without the leading reference to the running program. Typically, this
means @code{sys.argv[1:]}. `shortopts' is the string of option letters that the
script wants to recognize, with options that require an argument followed by a
colon (@code{':'}; i.e., the same format that Unix @code{getopt()} uses).

@cartouche
@quotation Note 
Unlike GNU @code{getopt()}, after a non-option argument, all further
arguments are considered also non-options. This is similar to the way
non-GNU Unix systems work.
@end quotation
@end cartouche

`longopts', si spécifié, doit être une liste de chaînes avec les noms des options longues qui doivent être prises en charge. Le premier @code{'--'} ne dois pas figurer dans le nom de l’option. Les options longues qui requièrent un argument doivent être suivies d’un signe égal (@code{'='}). Les arguments facultatifs ne sont pas pris en charge. Pour accepter uniquement les options longues, `shortopts' doit être une chaîne vide. Les options longues sur la ligne de commande peuvent être reconnues tant qu’elles fournissent un préfixe du nom de l’option qui correspond exactement à l’une des options acceptées. Par exemple, si `longopts' est @code{['foo', 'frob']}, l’option @code{--fo} correspondra à @code{--foo}, mais @code{--f} ne correspondra pas de façon unique, donc @ref{4779,,GetoptError} sera levé.

La valeur de retour se compose de deux éléments : le premier est une liste de paires @code{(option, value)}, la deuxième est la liste des arguments de programme laissés après que la liste d’options est été dépouillée (il s’agit d’une tranche de fin de `args'). Chaque paire option-valeur retournée a l’option comme premier élément, préfixée avec un trait d'union pour les options courtes (par exemple, @code{'-x'}) ou deux tirets pour les options longues (par exemple, @code{'--long-option'}), et l’argument option comme deuxième élément, ou une chaîne vide si le option n’a aucun argument. Les options se trouvent dans la liste dans l’ordre dans lequel elles ont été trouvées, permettant ainsi plusieurs occurrences. Les options longues et courtes peuvent être mélangées.
@end deffn

@geindex gnu_getopt() (dans le module getopt)
@anchor{library/getopt getopt gnu_getopt}@anchor{146e}
@deffn {Fonction} getopt.gnu_getopt (args, shortopts, longopts=[])

Cette fonction fonctionne comme @ref{60,,getopt()}, sauf que le mode de `scan' GNU est utilisé par défaut. Cela signifie que les arguments option et non-option peuvent être `intermixés'. La fonction @ref{60,,getopt()} arrête le traitement des options dès qu’un argument de non-option est rencontré.

If the first character of the option string is @code{'+'}, or if the environment
variable @code{POSIXLY_CORRECT} is set, then option processing stops as
soon as a non-option argument is encountered.
@end deffn

@geindex GetoptError
@anchor{library/getopt getopt GetoptError}@anchor{4779}
@deffn {Exception} getopt.GetoptError

This is raised when an unrecognized option is found in the argument list or when
an option requiring an argument is given none. The argument to the exception is
a string indicating the cause of the error.  For long options, an argument given
to an option which does not require one will also cause this exception to be
raised.  The attributes @code{msg} and @code{opt} give the error message and
related option; if there is no specific option to which the exception relates,
@code{opt} is an empty string.
@end deffn

@c XXX deprecated?

@geindex error
@anchor{library/getopt getopt error}@anchor{477a}
@deffn {Exception} getopt.error

Alias pour @ref{4779,,GetoptError} ; pour la rétrocompatibilité.
@end deffn

Un exemple utilisant uniquement les options de style UNIX :

@example
>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', '@w{'}), ('-b', '@w{'}), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
@end example

L’utilisation de noms d’options longs est tout aussi simple :

@example
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
...     'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', '@w{'}), ('--output-file', 'abc.def'), ('-x', '@w{'})]
>>> args
['a1', 'a2']
@end example

In a script, typical usage is something like this:

@example
import getopt, sys

def main():
    try:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    except getopt.GetoptError as err:
        # print help information and exit:
        print(err)  # will print something like "option -a not recognized"
        usage()
        sys.exit(2)
    output = None
    verbose = False
    for o, a in opts:
        if o == "-v":
            verbose = True
        elif o in ("-h", "--help"):
            usage()
            sys.exit()
        elif o in ("-o", "--output"):
            output = a
        else:
            assert False, "unhandled option"
    process(args, output=output, verbose=verbose)

if __name__ == "__main__":
    main()
@end example

Note that an equivalent command line interface could be produced with less code
and more informative help and error messages by using the @ref{9f,,optparse} module:

@example
import optparse

if __name__ == '__main__':
    parser = optparse.OptionParser()
    parser.add_option('-o', '--output')
    parser.add_option('-v', dest='verbose', action='store_true')
    opts, args = parser.parse_args()
    process(args, output=opts.output, verbose=opts.verbose)
@end example

A roughly equivalent command line interface for this case can also be
produced by using the @ref{6,,argparse} module:

@example
import argparse

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    parser.add_argument('rest', nargs='*')
    args = parser.parse_args()
    process(args.rest, output=args.output, verbose=args.verbose)
@end example

See @ref{2dcd,,Choosing an argument parsing library} for details on how the @code{argparse}
version of this code differs in behaviour from the @code{optparse} (and
@code{getopt}) version.


@subsubheading Voir aussi



@table @asis

@item Module @ref{9f,,optparse}

Declarative command line option parsing.

@item Module @ref{6,,argparse}

More opinionated command line option and argument parsing library.
@end table


@node Removed Modules,Considérations de sécurité<4>,Modules remplacés,La bibliothèque standard
@anchor{library/removed doc}@anchor{477b}@anchor{library/removed removed}@anchor{477c}@anchor{library/removed removed-modules}@anchor{477d}
@section Removed Modules


The modules described in this chapter have been removed from the Python
standard library.  They are documented here to help people find replacements.

@menu
* aifc: aifc --- Read and write AIFF and AIFC files. Read and write AIFF and AIFC files
* asynchat: asynchat --- Asynchronous socket command/response handler. Asynchronous socket command/response handler
* asyncore: asyncore --- Asynchronous socket handler. Asynchronous socket handler
* audioop: audioop --- Manipulate raw audio data. Manipulate raw audio data
* cgi: cgi --- Common Gateway Interface support. Common Gateway Interface support
* cgitb: cgitb --- Traceback manager for CGI scripts. Traceback manager for CGI scripts
* chunk: chunk --- Read IFF chunked data. Read IFF chunked data
* crypt: crypt --- Function to check Unix passwords. Function to check Unix passwords
* distutils: distutils --- Building and installing Python modules. Building and installing Python modules
* imghdr: imghdr --- Determine the type of an image. Determine the type of an image
* imp: imp --- Access the import internals. Access the import internals
* mailcap: mailcap --- Mailcap file handling. Mailcap file handling
* msilib: msilib --- Read and write Microsoft Installer files. Read and write Microsoft Installer files
* nis: nis --- Interface to Sun’s NIS Yellow Pages. Interface to Sun’s NIS (Yellow Pages)
* nntplib: nntplib --- NNTP protocol client. NNTP protocol client
* ossaudiodev: ossaudiodev --- Access to OSS-compatible audio devices. Access to OSS-compatible audio devices
* pipes: pipes --- Interface to shell pipelines. Interface to shell pipelines
* smtpd: smtpd --- SMTP Server. SMTP Server
* sndhdr: sndhdr --- Determine type of sound file. Determine type of sound file
* spwd: spwd --- The shadow password database. The shadow password database
* sunau: sunau --- Read and write Sun AU files. Read and write Sun AU files
* telnetlib: telnetlib --- Telnet client. Telnet client
* uu: uu --- Encode and decode uuencode files. Encode and decode uuencode files
* xdrlib: xdrlib --- Encode and decode XDR data. Encode and decode XDR data

@end menu

@node aifc --- Read and write AIFF and AIFC files,asynchat --- Asynchronous socket command/response handler,,Removed Modules
@anchor{library/aifc doc}@anchor{477e}@anchor{library/aifc aifc-read-and-write-aiff-and-aifc-files}@anchor{477f}@anchor{library/aifc module-aifc}@anchor{5}
@subsection @code{aifc} --- Read and write AIFF and AIFC files


@geindex module; aifc


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{aifc} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/aifc.html}.

@node asynchat --- Asynchronous socket command/response handler,asyncore --- Asynchronous socket handler,aifc --- Read and write AIFF and AIFC files,Removed Modules
@anchor{library/asynchat doc}@anchor{4780}@anchor{library/asynchat asynchat-asynchronous-socket-command-response-handler}@anchor{4781}@anchor{library/asynchat module-asynchat}@anchor{9}
@subsection @code{asynchat} --- Asynchronous socket command/response handler


@geindex module; asynchat


Deprecated since version 3.6, removed in version 3.12.


This module is no longer part of the Python standard library.
It was @ref{4eb,,removed in Python 3.12} after
being deprecated in Python 3.6.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Applications should use the @ref{a,,asyncio} module instead.

The last version of Python that provided the @code{asynchat} module was
Python 3.11@footnote{https://docs.python.org/3.11/library/asynchat.html}.

@node asyncore --- Asynchronous socket handler,audioop --- Manipulate raw audio data,asynchat --- Asynchronous socket command/response handler,Removed Modules
@anchor{library/asyncore doc}@anchor{4782}@anchor{library/asyncore asyncore-asynchronous-socket-handler}@anchor{4783}@anchor{library/asyncore module-asyncore}@anchor{b}
@subsection @code{asyncore} --- Asynchronous socket handler


@geindex module; asyncore


Deprecated since version 3.6, removed in version 3.12.


This module is no longer part of the Python standard library.
It was @ref{4eb,,removed in Python 3.12} after
being deprecated in Python 3.6.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Applications should use the @ref{a,,asyncio} module instead.

The last version of Python that provided the @code{asyncore} module was
Python 3.11@footnote{https://docs.python.org/3.11/library/asyncore.html}.

@node audioop --- Manipulate raw audio data,cgi --- Common Gateway Interface support,asyncore --- Asynchronous socket handler,Removed Modules
@anchor{library/audioop doc}@anchor{4784}@anchor{library/audioop audioop-manipulate-raw-audio-data}@anchor{4785}@anchor{library/audioop module-audioop}@anchor{d}
@subsection @code{audioop} --- Manipulate raw audio data


@geindex module; audioop


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{audioop} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/audioop.html}.

@node cgi --- Common Gateway Interface support,cgitb --- Traceback manager for CGI scripts,audioop --- Manipulate raw audio data,Removed Modules
@anchor{library/cgi doc}@anchor{4786}@anchor{library/cgi cgi-common-gateway-interface-support}@anchor{4787}@anchor{library/cgi module-cgi}@anchor{15}
@subsection @code{cgi} --- Common Gateway Interface support


@geindex module; cgi


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

A fork of the module on PyPI can be used instead: legacy-cgi@footnote{https://pypi.org/project/legacy-cgi/}.
This is a copy of the cgi module, no longer maintained or supported by the core
Python team.

The last version of Python that provided the @code{cgi} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/cgi.html}.

@node cgitb --- Traceback manager for CGI scripts,chunk --- Read IFF chunked data,cgi --- Common Gateway Interface support,Removed Modules
@anchor{library/cgitb doc}@anchor{4788}@anchor{library/cgitb cgitb-traceback-manager-for-cgi-scripts}@anchor{4789}@anchor{library/cgitb module-cgitb}@anchor{16}
@subsection @code{cgitb} --- Traceback manager for CGI scripts


@geindex module; cgitb


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

A fork of the module on PyPI can now be used instead: legacy-cgi@footnote{https://pypi.org/project/legacy-cgi/}.
This is a copy of the cgi module, no longer maintained or supported by the core
Python team.

The last version of Python that provided the @code{cgitb} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/cgitb.html}.

@node chunk --- Read IFF chunked data,crypt --- Function to check Unix passwords,cgitb --- Traceback manager for CGI scripts,Removed Modules
@anchor{library/chunk doc}@anchor{478a}@anchor{library/chunk chunk-read-iff-chunked-data}@anchor{478b}@anchor{library/chunk module-chunk}@anchor{17}
@subsection @code{chunk} --- Read IFF chunked data


@geindex module; chunk


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{chunk} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/chunk.html}.

@node crypt --- Function to check Unix passwords,distutils --- Building and installing Python modules,chunk --- Read IFF chunked data,Removed Modules
@anchor{library/crypt doc}@anchor{478c}@anchor{library/crypt crypt-function-to-check-unix-passwords}@anchor{478d}@anchor{library/crypt module-crypt}@anchor{28}
@subsection @code{crypt} --- Function to check Unix passwords


@geindex module; crypt


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Applications can use the @ref{67,,hashlib} module from the standard library.
Other possible replacements are third-party libraries from PyPI:
legacycrypt@footnote{https://pypi.org/project/legacycrypt/}, bcrypt@footnote{https://pypi.org/project/bcrypt/}, argon2-cffi@footnote{https://pypi.org/project/argon2-cffi/}, or passlib@footnote{https://pypi.org/project/passlib/}.
These are not supported or maintained by the Python core team.

The last version of Python that provided the @code{crypt} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/crypt.html}.

@node distutils --- Building and installing Python modules,imghdr --- Determine the type of an image,crypt --- Function to check Unix passwords,Removed Modules
@anchor{library/distutils doc}@anchor{478e}@anchor{library/distutils distutils-building-and-installing-python-modules}@anchor{478f}@anchor{library/distutils module-distutils}@anchor{39}
@subsection @code{distutils} --- Building and installing Python modules


@geindex module; distutils


Deprecated since version 3.10, removed in version 3.12.


This module is no longer part of the Python standard library.
It was @ref{4f1,,removed in Python 3.12} after
being deprecated in Python 3.10.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 632
PEP 632@footnote{https://peps.python.org/pep-0632/},
which has migration advice@footnote{https://peps.python.org/pep-0632/#migration-advice}.

The last version of Python that provided the @code{distutils} module was
Python 3.11@footnote{https://docs.python.org/3.11/library/distutils.html}.

@node imghdr --- Determine the type of an image,imp --- Access the import internals,distutils --- Building and installing Python modules,Removed Modules
@anchor{library/imghdr doc}@anchor{4790}@anchor{library/imghdr imghdr-determine-the-type-of-an-image}@anchor{4791}@anchor{library/imghdr module-imghdr}@anchor{74}
@subsection @code{imghdr} --- Determine the type of an image


@geindex module; imghdr


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Possible replacements are third-party libraries from PyPI:
filetype@footnote{https://pypi.org/project/filetype/}, puremagic@footnote{https://pypi.org/project/puremagic/}, or python-magic@footnote{https://pypi.org/project/python-magic/}.
These are not supported or maintained by the Python core team.

The last version of Python that provided the @code{imghdr} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/imghdr.html}.

@node imp --- Access the import internals,mailcap --- Mailcap file handling,imghdr --- Determine the type of an image,Removed Modules
@anchor{library/imp doc}@anchor{4792}@anchor{library/imp imp-access-the-import-internals}@anchor{4793}@anchor{library/imp module-imp}@anchor{75}
@subsection @code{imp} --- Access the import internals


@geindex module; imp


Deprecated since version 3.4, removed in version 3.12.


This module is no longer part of the Python standard library.
It was @ref{4fb,,removed in Python 3.12} after
being deprecated in Python 3.4.

The @ref{4fb,,removal notice} includes guidance for
migrating code from @code{imp} to @ref{76,,importlib}.

The last version of Python that provided the @code{imp} module was
Python 3.11@footnote{https://docs.python.org/3.11/library/imp.html}.

@node mailcap --- Mailcap file handling,msilib --- Read and write Microsoft Installer files,imp --- Access the import internals,Removed Modules
@anchor{library/mailcap doc}@anchor{4794}@anchor{library/mailcap mailcap-mailcap-file-handling}@anchor{4795}@anchor{library/mailcap module-mailcap}@anchor{8b}
@subsection @code{mailcap} --- Mailcap file handling


@geindex module; mailcap


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{mailcap} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/mailcap.html}.

@node msilib --- Read and write Microsoft Installer files,nis --- Interface to Sun’s NIS Yellow Pages,mailcap --- Mailcap file handling,Removed Modules
@anchor{library/msilib doc}@anchor{4796}@anchor{library/msilib module-msilib}@anchor{91}@anchor{library/msilib msilib-read-and-write-microsoft-installer-files}@anchor{4797}
@subsection @code{msilib} --- Read and write Microsoft Installer files


@geindex module; msilib


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{msilib} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/msilib.html}.

@node nis --- Interface to Sun’s NIS Yellow Pages,nntplib --- NNTP protocol client,msilib --- Read and write Microsoft Installer files,Removed Modules
@anchor{library/nis doc}@anchor{4798}@anchor{library/nis module-nis}@anchor{9b}@anchor{library/nis nis-interface-to-suns-nis-yellow-pages}@anchor{4799}
@subsection @code{nis} --- Interface to Sun’s NIS (Yellow Pages)


@geindex module; nis


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{nis} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/nis.html}.

@node nntplib --- NNTP protocol client,ossaudiodev --- Access to OSS-compatible audio devices,nis --- Interface to Sun’s NIS Yellow Pages,Removed Modules
@anchor{library/nntplib doc}@anchor{479a}@anchor{library/nntplib module-nntplib}@anchor{9c}@anchor{library/nntplib nntplib-nntp-protocol-client}@anchor{479b}
@subsection @code{nntplib} --- NNTP protocol client


@geindex module; nntplib


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{nntplib} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/nntplib.html}.

@node ossaudiodev --- Access to OSS-compatible audio devices,pipes --- Interface to shell pipelines,nntplib --- NNTP protocol client,Removed Modules
@anchor{library/ossaudiodev doc}@anchor{479c}@anchor{library/ossaudiodev module-ossaudiodev}@anchor{a2}@anchor{library/ossaudiodev ossaudiodev-access-to-oss-compatible-audio-devices}@anchor{479d}
@subsection @code{ossaudiodev} --- Access to OSS-compatible audio devices


@geindex module; ossaudiodev


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{ossaudiodev} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/ossaudiodev.html}.

@node pipes --- Interface to shell pipelines,smtpd --- SMTP Server,ossaudiodev --- Access to OSS-compatible audio devices,Removed Modules
@anchor{library/pipes doc}@anchor{479e}@anchor{library/pipes module-pipes}@anchor{a7}@anchor{library/pipes pipes-interface-to-shell-pipelines}@anchor{479f}
@subsection @code{pipes} --- Interface to shell pipelines


@geindex module; pipes


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Applications should use the @ref{d5,,subprocess} module instead.

The last version of Python that provided the @code{pipes} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/pipes.html}.

@node smtpd --- SMTP Server,sndhdr --- Determine type of sound file,pipes --- Interface to shell pipelines,Removed Modules
@anchor{library/smtpd doc}@anchor{47a0}@anchor{library/smtpd module-smtpd}@anchor{c8}@anchor{library/smtpd smtpd-smtp-server}@anchor{47a1}
@subsection @code{smtpd} --- SMTP Server


@geindex module; smtpd


Deprecated since version 3.6, removed in version 3.12.


This module is no longer part of the Python standard library.
It was @ref{4eb,,removed in Python 3.12} after
being deprecated in Python 3.6.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

A possible replacement is the third-party aiosmtpd@footnote{https://pypi.org/project/aiosmtpd/} library. This
library is not maintained or supported by the Python core team.

The last version of Python that provided the @code{smtpd} module was
Python 3.11@footnote{https://docs.python.org/3.11/library/smtpd.html}.

@node sndhdr --- Determine type of sound file,spwd --- The shadow password database,smtpd --- SMTP Server,Removed Modules
@anchor{library/sndhdr doc}@anchor{47a2}@anchor{library/sndhdr module-sndhdr}@anchor{ca}@anchor{library/sndhdr sndhdr-determine-type-of-sound-file}@anchor{47a3}
@subsection @code{sndhdr} --- Determine type of sound file


@geindex module; sndhdr


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Possible replacements are third-party modules from PyPI:
filetype@footnote{https://pypi.org/project/filetype/}, puremagic@footnote{https://pypi.org/project/puremagic/}, or python-magic@footnote{https://pypi.org/project/python-magic/}.
These are not supported or maintained by the Python core team.

The last version of Python that provided the @code{sndhdr} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/sndhdr.html}.

@node spwd --- The shadow password database,sunau --- Read and write Sun AU files,sndhdr --- Determine type of sound file,Removed Modules
@anchor{library/spwd doc}@anchor{47a4}@anchor{library/spwd module-spwd}@anchor{cd}@anchor{library/spwd spwd-the-shadow-password-database}@anchor{47a5}
@subsection @code{spwd} --- The shadow password database


@geindex module; spwd


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

A possible replacement is the third-party library python-pam@footnote{https://pypi.org/project/python-pam/}.
This library is not supported or maintained by the Python core team.

The last version of Python that provided the @code{spwd} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/spwd.html}.

@node sunau --- Read and write Sun AU files,telnetlib --- Telnet client,spwd --- The shadow password database,Removed Modules
@anchor{library/sunau doc}@anchor{47a6}@anchor{library/sunau module-sunau}@anchor{d6}@anchor{library/sunau sunau-read-and-write-sun-au-files}@anchor{47a7}
@subsection @code{sunau} --- Read and write Sun AU files


@geindex module; sunau


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{sunau} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/sunau.html}.

@node telnetlib --- Telnet client,uu --- Encode and decode uuencode files,sunau --- Read and write Sun AU files,Removed Modules
@anchor{library/telnetlib doc}@anchor{47a8}@anchor{library/telnetlib module-telnetlib}@anchor{de}@anchor{library/telnetlib telnetlib-telnet-client}@anchor{47a9}
@subsection @code{telnetlib} --- Telnet client


@geindex module; telnetlib


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

Possible replacements are third-party libraries from PyPI: telnetlib3@footnote{https://pypi.org/project/telnetlib3/}
or Exscript@footnote{https://pypi.org/project/Exscript/}.  These are not supported or maintained by the Python core
team.

The last version of Python that provided the @code{telnetlib} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/telnetlib.html}.

@node uu --- Encode and decode uuencode files,xdrlib --- Encode and decode XDR data,telnetlib --- Telnet client,Removed Modules
@anchor{library/uu doc}@anchor{47aa}@anchor{library/uu module-uu}@anchor{10e}@anchor{library/uu uu-encode-and-decode-uuencode-files}@anchor{47ab}
@subsection @code{uu} --- Encode and decode uuencode files


@geindex module; uu


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{uu} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/uu.html}.

@node xdrlib --- Encode and decode XDR data,,uu --- Encode and decode uuencode files,Removed Modules
@anchor{library/xdrlib doc}@anchor{47ac}@anchor{library/xdrlib module-xdrlib}@anchor{11e}@anchor{library/xdrlib xdrlib-encode-and-decode-xdr-data}@anchor{47ad}
@subsection @code{xdrlib} --- Encode and decode XDR data


@geindex module; xdrlib


Deprecated since version 3.11, removed in version 3.13.


This module is no longer part of the Python standard library.
It was @ref{142,,removed in Python 3.13} after
being deprecated in Python 3.11.  The removal was decided in 
@geindex Python Enhancement Proposals; PEP 594
PEP 594@footnote{https://peps.python.org/pep-0594/}.

The last version of Python that provided the @code{xdrlib} module was
Python 3.12@footnote{https://docs.python.org/3.12/library/xdrlib.html}.

@geindex security considerations
@anchor{library/security_warnings security-warnings}@anchor{47ae}
@node Considérations de sécurité<4>,,Removed Modules,La bibliothèque standard
@anchor{library/security_warnings doc}@anchor{47af}@anchor{library/security_warnings security-considerations}@anchor{47b0}
@section Considérations de sécurité


The following modules have specific security considerations:


@itemize *

@item 
@ref{e,,base64}: @ref{3689,,base64 security considerations} in
@geindex RFC; RFC 4648
RFC 4648@footnote{https://datatracker.ietf.org/doc/html/rfc4648.html}

@item 
@ref{67,,hashlib}: @ref{2a52,,all constructors take a "usedforsecurity" keyword-only argument disabling known insecure and blocked algorithms}

@item 
@ref{71,,http.server} is not suitable for production use, only implementing
basic security checks. See the @ref{3aab,,security considerations}.

@item 
@ref{86,,logging}: @ref{2c3c,,Logging configuration uses eval()}

@item 
@ref{93,,multiprocessing}: @ref{30cc,,Connection.recv() uses pickle}

@item 
@ref{a5,,pickle}: @ref{2819,,Restricting globals in pickle}

@item 
@ref{b7,,random} shouldn't be used for security purposes, use @ref{bf,,secrets}
instead

@item 
@ref{c2,,shelve}: @ref{2835,,shelve is based on pickle and thus unsuitable for dealing with untrusted sources}

@item 
@ref{cf,,ssl}: @ref{32a2,,SSL/TLS security considerations}

@item 
@ref{d5,,subprocess}: @ref{3172,,Subprocess security considerations}

@item 
@ref{df,,tempfile}: @ref{27d8,,mktemp is deprecated due to vulnerability to race conditions}

@item 
@ref{11f,,xml}: @ref{36b8,,XML vulnerabilities}

@item 
@ref{130,,zipfile}: @ref{2968,,maliciously prepared .zip files can cause disk volume exhaustion}
@end itemize

The @ref{94b,,-I} command line option can be used to run Python in isolated
mode. When it cannot be used, the @ref{58e,,-P} option or the
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} environment variable can be used to not prepend a
potentially unsafe path to @ref{3ab,,sys.path} such as the current directory, the
script's directory or an empty string.

@node Extension et intégration de l'interpréteur Python,Manuel de référence de l'API Python/C,La bibliothèque standard,Top
@anchor{extending/index doc}@anchor{47b1}@anchor{extending/index extending-and-embedding-the-python-interpreter}@anchor{47b2}@anchor{extending/index extending-index}@anchor{1b69}
@chapter Extension et intégration de l'interpréteur Python


Ce document décrit comment écrire des modules en C ou C++ pour étendre l'interpréteur Python à de nouveaux modules. En plus de définir de nouvelles fonctions, ces modules peuvent définir de nouveaux types d'objets ainsi que leur méthodes. Ce document explique aussi comment intégrer l'interpréteur Python dans une autre application, pour être utilisé comme langage d'extension. Enfin, ce document montre comment compiler et lier les modules d'extension pour qu'ils puissent être chargés dynamiquement (à l'exécution) dans l'interpréteur, si le système d'exploitation sous-jacent supporte cette fonctionnalité.

Ce document présuppose que vous avez des connaissances de base sur Python. Pour une introduction informelle du langage, voyez @ref{1b68,,Le tutoriel Python}.  @ref{144,,La référence du langage Python} donne une définition plus formelle du langage. @ref{143,,La bibliothèque standard} documente les objets types, fonctions et modules existants (tous intégrés et écrits en Python) qui donnent au langage sa large gamme d'applications.

Pour une description dans sa totalité de l'API Python/C, voir @ref{1b6a,,Manuel de référence de l'API Python/C}.

@menu
* Les outils tiers recommandés:: 
* Création d'extensions sans outils tiers:: 
* Intégrer l'interpréteur CPython dans une plus grande application:: 

@end menu

@node Les outils tiers recommandés,Création d'extensions sans outils tiers,,Extension et intégration de l'interpréteur Python
@anchor{extending/index recommended-third-party-tools}@anchor{47b3}
@section Les outils tiers recommandés


This guide only covers the basic tools for creating extensions provided
as part of this version of CPython. Third party tools like
Cython@footnote{https://cython.org/}, cffi@footnote{https://cffi.readthedocs.io},
SWIG@footnote{https://www.swig.org} and Numba@footnote{https://numba.pydata.org/}
offer both simpler and more sophisticated approaches to creating C and C++
extensions for Python.


@subsubheading Voir aussi



@table @asis

@item Guide d'utilisation de l'empaquetage Python : Extensions binaires@footnote{https://packaging.python.org/guides/packaging-binary-extensions/}

Le guide d'utilisation de l'empaquetage Python ne couvre pas uniquement quelques outils disponibles qui simplifient la création d'extensions binaires, mais aborde aussi les différentes raisons pour lesquelles créer un module d'extension peut être souhaitable d'entrée.
@end table


@node Création d'extensions sans outils tiers,Intégrer l'interpréteur CPython dans une plus grande application,Les outils tiers recommandés,Extension et intégration de l'interpréteur Python
@anchor{extending/index creating-extensions-without-third-party-tools}@anchor{47b4}
@section Création d'extensions sans outils tiers


Cette section du guide couvre la création d'extensions C et C++ sans l'utilisation d'outils tiers. Cette section est destinée aux créateurs de ces outils, plus que d'être une méthode recommandée pour créer votre propre extension C.

@menu
* Étendre Python en C ou C++:: 
* Tutoriel ; définir des types dans des extensions: Tutoriel définir des types dans des extensions. 
* Définir les types d'extension ; divers sujets: Définir les types d'extension divers sujets. 
* Construire des extensions C et C++:: 
* Construire des extensions C et C++ sur Windows:: 

@end menu

@node Étendre Python en C ou C++,Tutoriel définir des types dans des extensions,,Création d'extensions sans outils tiers
@anchor{extending/extending doc}@anchor{47b5}@anchor{extending/extending extending-intro}@anchor{47b6}@anchor{extending/extending extending-python-with-c-or-c}@anchor{47b7}
@subsection Étendre Python en C ou C++


Il est relativement facile d'ajouter de nouveaux modules à Python, si vous savez programmer en C. Ces `modules d'extension' permettent deux choses qui ne sont pas possibles directement en Python : ils peuvent définir de nouveaux types natifs et peuvent appeler des fonctions de bibliothèques C ou faire des appels systèmes.

Pour gérer les extensions, l'API Python (`Application Programmer Interface') définit un ensemble de fonctions, macros et variables qui donnent accès à la plupart des aspects du système d'exécution de Python. L'API Python est incorporée dans un fichier source C en incluant l'en-tête @code{Python.h}.

La compilation d'un module d'extension dépend de l'usage prévu et de la configuration du système, plus de détails peuvent être trouvés dans les chapitres suivants.

@cartouche
@quotation Note 
l'interface d'extension C est spécifique à `CPython', et les modules d'extension ne fonctionnent pas sur les autres implémentations de Python. Dans de nombreux cas, il est possible d'éviter la rédaction des extensions en C et ainsi préserver la portabilité vers d'autres implémentations. Par exemple, si vous devez appeler une fonction de la bibliothèque C ou faire un appel système, vous devriez envisager d'utiliser le module @ref{2a,,ctypes} ou d'utiliser la bibliothèque cffi@footnote{https://cffi.readthedocs.io/} plutôt que d'écrire du code C sur mesure. Ces modules vous permettent d'écrire du code Python s'interfaçant avec le code C et sont plus portables entre les implémentations de Python que l'écriture et la compilation d'une d'extension C.
@end quotation
@end cartouche

@menu
* Un exemple simple:: 
* Intermezzo ; les erreurs et les exceptions: Intermezzo les erreurs et les exceptions. 
* Retour vers l'exemple:: 
* La fonction d'initialisation et le tableau des méthodes du module:: 
* Compilation et liaison:: 
* Appeler des fonctions Python en C:: 
* Extraire des paramètres dans des fonctions d'extension:: 
* Paramètres nommés pour des fonctions d'extension:: 
* Créer des valeurs arbitraires:: 
* Compteurs de références:: 
* Écrire des extensions en C++:: 
* Fournir une API en langage C pour un module d'extension:: 

@end menu

@node Un exemple simple,Intermezzo les erreurs et les exceptions,,Étendre Python en C ou C++
@anchor{extending/extending a-simple-example}@anchor{47b8}@anchor{extending/extending extending-simpleexample}@anchor{47b9}
@subsubsection Un exemple simple


Créons un module d'extension appelé @code{spam} (la nourriture préférée de fans des `Monty Python') et disons que nous voulons créer une interface Python à la fonction de la bibliothèque C @code{system()} @footnote{
Une interface pour cette fonction existe déjà dans le module standard @ref{a0,,os}, elle a été choisie comme un exemple simple et direct.
}. Cette fonction prend une chaîne de caractères à terminaison nulle comme argument et renvoie un entier. Nous voulons que cette fonction soit appelable à partir de Python comme suit :

@example
>>> import spam
>>> status = spam.system("ls -l")
@end example

Commençons par créer un fichier @code{spammodule.c} (historiquement, si un module se nomme @code{spam}, le fichier C contenant son implémentation est appelé @code{spammodule.c} ; si le nom du module est très long, comme @code{spammify}, le nom du module peut être juste @code{spammify.c}).

Les deux premières lignes de notre fichier peuvent être :

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
@end example

qui récupère l'API Python (vous pouvez ajouter un commentaire décrivant le but du module et un avis de droit d'auteur si vous le souhaitez).

@cartouche
@quotation Note 
il est possible que Python déclare certaines définitions pré-processeur qui affectent les têtes standards sur certains systèmes, vous `devez' donc inclure @code{Python.h} avant les en-têtes standards.

@code{#define PY_SSIZE_T_CLEAN} was used to indicate that @code{Py_ssize_t} should be
used in some APIs instead of @code{int}.
It is not necessary since Python 3.13, but we keep it here for backward compatibility.
See @ref{381,,Chaînes et tampons} for a description of this macro.
@end quotation
@end cartouche

Tous les symboles exposés par @code{Python.h} sont préfixés de @code{Py} ou @code{PY}, sauf ceux qui sont définis dans les en-têtes standards. Pour le confort, et comme ils sont largement utilisés par l'interpréteur Python, @code{"Python.h"} inclut lui-même quelques en-têtes standards : @code{<stdio.h>}, @code{<string.h>}, @code{<errno.h>} et @code{<stdlib.h>}. Si ce dernier n'existe pas sur votre système, il déclare les fonctions @code{malloc()}, @code{free()} et @code{realloc()} directement.

La prochaine chose que nous ajoutons à notre fichier de module est la fonction C qui sera appelée lorsque l'expression Python @code{spam.system(chaîne)} sera évaluée (nous verrons bientôt comment elle finit par être appelée) :

@example
static PyObject *
spam_system(PyObject *self, PyObject *args)
@{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return PyLong_FromLong(sts);
@}
@end example

Il y a une correspondance directe de la liste des arguments en Python (par exemple, l'expression @code{"ls -l"}) aux arguments passés à la fonction C. La fonction C a toujours deux arguments, appelés par convention `self' et `args'.

Pour les fonctions au niveau du module, l'argument `self' pointe sur l'objet module, pour une méthode, il pointe sur l'instance de l'objet.

L'argument `args' sera un pointeur vers un `n'-uplet Python contenant les arguments. Chaque élément du `n'-uplet correspond à un argument dans la liste des arguments de l'appel. Les arguments sont des objets Python, afin d'en faire quelque chose dans notre fonction C, nous devons les convertir en valeurs C. La fonction @ref{55d,,PyArg_ParseTuple()} de l'API Python vérifie les types des arguments et les convertit en valeurs C. Elle utilise un modèle sous forme de chaîne pour déterminer les types requis des arguments ainsi que les types de variables C dans lequel stocker les valeurs converties. Nous approfondirons ceci plus tard.

@ref{55d,,PyArg_ParseTuple()} renvoie vrai (pas zéro) si tous les arguments ont le bon type et que ses composants ont été stockés dans les variables dont les adresses ont été données en entrée. Elle renvoie faux (zéro) si une liste d'arguments invalide a été passée. Dans ce dernier cas, elle lève également une exception appropriée de sorte que la fonction d'appel puisse renvoyer @code{NULL} immédiatement (comme nous l'avons vu dans l'exemple).

@node Intermezzo les erreurs et les exceptions,Retour vers l'exemple,Un exemple simple,Étendre Python en C ou C++
@anchor{extending/extending extending-errors}@anchor{47ba}@anchor{extending/extending intermezzo-errors-and-exceptions}@anchor{47bb}
@subsubsection Intermezzo : les erreurs et les exceptions


Une convention importante dans l'interpréteur Python est la suivante : lorsqu'une fonction échoue, elle doit définir une condition d'exception et renvoyer une valeur d'erreur (généralement @code{-1} ou un pointeur @code{NULL}). Les informations d'exception sont stockées dans trois attributs de l'état du thread de l'interpréteur. Ils valent @code{NULL} s'il n'y a pas d'exception. Sinon, ce sont les équivalents C des membres du `n'-uplet Python renvoyé par @ref{675,,sys.exc_info()}. Il s'agit du type d'exception, de l'instance d'exception et d'un objet de trace. Il est important de les connaître pour comprendre comment les erreurs sont transmises.

L'API Python définit un certain nombre de fonctions pour créer différents types d'exceptions.

La plus courante est @ref{568,,PyErr_SetString()}. Ses arguments sont un objet exception et une chaîne C. L'objet exception est généralement un objet prédéfini comme @code{PyExc_ZeroDivisionError}. La chaîne C indique la cause de l'erreur et est convertie en une chaîne Python puis stockée en tant que « valeur associée » à l'exception.

Une autre fonction utile est @ref{47bc,,PyErr_SetFromErrno()}, qui construit une exception à partir de la valeur de la variable globale @code{errno}. La fonction la plus générale est @ref{567,,PyErr_SetObject()}, qui prend deux arguments : l'exception et sa valeur associée. Vous ne devez pas appliquer @ref{55a,,Py_INCREF()} aux objets transmis à ces fonctions.

Vous pouvez tester de manière non destructive si une exception a été levée avec @ref{187f,,PyErr_Occurred()}. Cela renvoie l'objet exception actuel, ou @code{NULL} si aucune exception n'a eu lieu. Cependant, vous ne devriez pas avoir besoin d'appeler @ref{187f,,PyErr_Occurred()} pour voir si une erreur est survenue durant l'appel d'une fonction, puisque vous devriez être en mesure de le déterminer à partir de la valeur renvoyée.

Lorsqu'une fonction `f' ayant appelé une autre fonction `g' détecte que cette dernière a échoué, `f' devrait donner une valeur d'erreur à son tour (habituellement @code{NULL} ou @code{-1}). La fonction `f' ne devrait `pas' appeler l'une des fonctions @code{PyErr_*}, l'une d'entre elles ayant déjà été appelée par `g'. La fonction appelant `f' est alors censée renvoyer aussi un code d'erreur à celle qui l'a appelée, toujours sans utiliser @code{PyErr_*}, et ainsi de suite. La cause la plus détaillée de l'erreur a déjà été signalée par la fonction l'ayant détecté en premier. Une fois l'erreur remontée à la boucle principale de l'interpréteur Python, il interrompt le code en cours d'exécution et essaie de trouver un gestionnaire d'exception spécifié par le développeur Python.

(Il y a des situations où un module peut effectivement donner un message d'erreur plus détaillé en appelant une autre fonction @code{PyErr_*} et, dans de tels cas, il est tout à fait possible de le faire. Cependant, ce n'est généralement pas nécessaire, et peut amener à perdre des informations sur la cause de l'erreur : la plupart des opérations peuvent échouer pour tout un tas de raisons.)

Pour ignorer une exception qui aurait été émise lors d'un appel de fonction qui a échoué, l'exception doit être retirée explicitement en appelant @ref{101a,,PyErr_Clear()}. Le seul cas pour lequel du code C devrait appeler @ref{101a,,PyErr_Clear()} est lorsqu'il ne veut pas passer l'erreur à l'interpréteur, mais souhaite la gérer lui-même (peut-être en essayant quelque chose d'autre, ou en prétendant que rien n'a mal tourné).

Chaque échec de @code{malloc()} doit être transformé en une exception, l'appelant direct de @code{malloc()} (ou @code{realloc()}) doit appeler @ref{47bd,,PyErr_NoMemory()} et prendre l'initiative de renvoyer une valeur d'erreur. Toutes les fonctions construisant des objets (tels que @ref{17c7,,PyLong_FromLong()}) le font déjà, donc cette note ne concerne que ceux qui appellent @code{malloc()} directement.

Notez également que, à l'exception notable de @ref{55d,,PyArg_ParseTuple()} et compagnie, les fonctions qui renvoient leur statut sous forme d'entier donnent généralement une valeur positive ou zéro en cas de succès et @code{-1} en cas d'échec, comme les appels du système Unix.

Enfin, lorsque vous renvoyez un code d'erreur, n'oubliez pas faire un brin de nettoyage (en appelant @ref{779,,Py_XDECREF()} ou @ref{55b,,Py_DECREF()} avec les objets que vous auriez déjà créés) !

The choice of which exception to raise is entirely yours.  There are predeclared
C objects corresponding to all built-in Python exceptions, such as
@code{PyExc_ZeroDivisionError}, which you can use directly. Of course, you
should choose exceptions wisely --- don't use @code{PyExc_TypeError} to mean
that a file couldn't be opened (that should probably be @code{PyExc_OSError}).
If something's wrong with the argument list, the @ref{55d,,PyArg_ParseTuple()}
function usually raises @code{PyExc_TypeError}.  If you have an argument whose
value must be in a particular range or must satisfy other conditions,
@code{PyExc_ValueError} is appropriate.

Vous pouvez également créer une exception spécifique à votre module. Pour cela, déclarez simplement une variable statique au début de votre fichier :

@example
static PyObject *SpamError;
@end example

and initialize it in your module's initialization function (@code{PyInit_spam()})
with an exception object:

@example
PyMODINIT_FUNC
PyInit_spam(void)
@{
    PyObject *m;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    if (PyModule_AddObjectRef(m, "error", SpamError) < 0) @{
        Py_CLEAR(SpamError);
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

Note that the Python name for the exception object is @code{spam.error}.  The
@ref{1248,,PyErr_NewException()} function may create a class with the base class
being @ref{9c7,,Exception} (unless another class is passed in instead of @code{NULL}),
described in @ref{1811,,Exceptions natives}.

Notez également que la variable @code{SpamError} contient une référence à la nouvelle classe créée ; ceci est intentionnel ! Comme l'exception peut être enlevée du module par du code externe, une référence à la classe est nécessaire pour assurer qu'elle ne sera pas supprimée par le ramasse-miettes, entraînant que @code{SpamError} devienne un pointeur dans le vide. Si cela se produisait, le code C qui lève cette exception peut engendrer un `core dump' ou des effets secondaires inattendus.

We discuss the use of @ref{1489,,PyMODINIT_FUNC} as a function return type later in this
sample.

The @code{spam.error} exception can be raised in your extension module using a
call to @ref{568,,PyErr_SetString()} as shown below:

@example
static PyObject *
spam_system(PyObject *self, PyObject *args)
@{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    if (sts < 0) @{
        PyErr_SetString(SpamError, "System command failed");
        return NULL;
    @}
    return PyLong_FromLong(sts);
@}
@end example

@node Retour vers l'exemple,La fonction d'initialisation et le tableau des méthodes du module,Intermezzo les erreurs et les exceptions,Étendre Python en C ou C++
@anchor{extending/extending back-to-the-example}@anchor{47be}@anchor{extending/extending backtoexample}@anchor{47bf}
@subsubsection Retour vers l'exemple


En revenant vers notre fonction exemple, vous devriez maintenant être capable de comprendre cette affirmation :

@example
if (!PyArg_ParseTuple(args, "s", &command))
    return NULL;
@end example

Elle renvoie @code{NULL} (l'indicateur d'erreur pour les fonctions renvoyant des pointeurs d'objet) si une erreur est détectée dans la liste des arguments, se fiant à l'exception définie par @ref{55d,,PyArg_ParseTuple()}. Autrement, la valeur chaîne de l'argument a été copiée dans la variable locale @code{command}. Il s'agit d'une attribution de pointeur et vous n'êtes pas supposés modifier la chaîne vers laquelle il pointe (donc en C Standard, la variable @code{command} doit être clairement déclarée comme @code{const char *command}).

La prochaine instruction est un appel à la fonction Unix @code{system()}, en lui passant la chaîne que nous venons d'obtenir à partir de @ref{55d,,PyArg_ParseTuple()} :

@example
sts = system(command);
@end example

Notre fonction @code{spam.system()} doit renvoyer la valeur de @code{sts} comme un objet Python. Cela est effectué par l'utilisation de la fonction @ref{17c7,,PyLong_FromLong()}.

@example
return PyLong_FromLong(sts);
@end example

Dans ce cas, elle renvoie un objet de type entier (oui, même les entiers sont des objets, stockés dans le tas, en Python !).

Si vous avez une fonction C qui ne renvoie aucun argument utile (une fonction renvoyant void), la fonction Python correspondante doit renvoyer @code{None}. Vous aurez besoin de cet idiome pour cela (qui est implémenté par la macro @ref{1427,,Py_RETURN_NONE}) :

@example
Py_INCREF(Py_None);
return Py_None;
@end example

@ref{47c0,,Py_None} est la dénomination en C pour l'objet spécial Python @code{None}. C'est un authentique objet Python plutôt qu'un pointeur @code{NULL} qui, dans la plupart des situations, signifie qu'une erreur est survenue comme nous l'avons vu.

@node La fonction d'initialisation et le tableau des méthodes du module,Compilation et liaison,Retour vers l'exemple,Étendre Python en C ou C++
@anchor{extending/extending methodtable}@anchor{47c1}@anchor{extending/extending the-module-s-method-table-and-initialization-function}@anchor{47c2}
@subsubsection La fonction d'initialisation et le tableau des méthodes du module


I promised to show how @code{spam_system()} is called from Python programs.
First, we need to list its name and address in a "method table":

@example
static PyMethodDef SpamMethods[] = @{
    ...
    @{"system",  spam_system, METH_VARARGS,
     "Execute a shell command."@},
    ...
    @{NULL, NULL, 0, NULL@}        /* Sentinel */
@};
@end example

Notez la troisième entrée (@code{METH_VARARGS}). C'est un indicateur du type de convention à utiliser pour la fonction C, à destination de l'interpréteur. Il doit valoir normalement @code{METH_VARARGS} ou @code{METH_VARARGS | METH_KEYWORDS} ; la valeur @code{0} indique qu'une variante obsolète de @ref{55d,,PyArg_ParseTuple()} est utilisée.

Si seulement @code{METH_VARARGS} est utilisé, la fonction s'attend à ce que les paramètres Python soient passés comme un `n'-uplet que l'on peut analyser `via' @ref{55d,,PyArg_ParseTuple()} ; des informations supplémentaires sont fournies plus bas.

Le bit @ref{47c3,,METH_KEYWORDS} peut être mis à un dans le troisième champ si des arguments par mots-clés doivent être passés à la fonction. Dans ce cas, la fonction C doit accepter un troisième paramètre @code{PyObject *} qui est un dictionnaire des mots-clés. Utilisez @ref{379,,PyArg_ParseTupleAndKeywords()} pour analyser les arguments d'une telle fonction.

Le tableau des méthodes doit être référencé dans la structure de définition du module :

@example
static struct PyModuleDef spammodule = @{
    PyModuleDef_HEAD_INIT,
    "spam",   /* name of module */
    spam_doc, /* module documentation, may be NULL */
    -1,       /* size of per-interpreter state of the module,
                 or -1 if the module keeps state in global variables. */
    SpamMethods
@};
@end example

This structure, in turn, must be passed to the interpreter in the module's
initialization function.  The initialization function must be named
@code{PyInit_name()}, where `name' is the name of the module, and should be the
only non-@code{static} item defined in the module file:

@example
PyMODINIT_FUNC
PyInit_spam(void)
@{
    return PyModule_Create(&spammodule);
@}
@end example

Note that @ref{1489,,PyMODINIT_FUNC} declares the function as @code{PyObject *} return type,
declares any special linkage declarations required by the platform, and for C++
declares the function as @code{extern "C"}.

When the Python program imports module @code{spam} for the first time,
@code{PyInit_spam()} is called. (See below for comments about embedding Python.)
It calls @ref{47c4,,PyModule_Create()}, which returns a module object, and
inserts built-in function objects into the newly created module based upon the
table (an array of @ref{148d,,PyMethodDef} structures) found in the module definition.
@ref{47c4,,PyModule_Create()} returns a pointer to the module object
that it creates.  It may abort with a fatal error for
certain errors, or return @code{NULL} if the module could not be initialized
satisfactorily. The init function must return the module object to its caller,
so that it then gets inserted into @code{sys.modules}.

When embedding Python, the @code{PyInit_spam()} function is not called
automatically unless there's an entry in the @code{PyImport_Inittab} table.
To add the module to the initialization table, use @ref{1731,,PyImport_AppendInittab()},
optionally followed by an import of the module:

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
@{
    PyStatus status;
    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Add a built-in module, before Py_Initialize */
    if (PyImport_AppendInittab("spam", PyInit_spam) == -1) @{
        fprintf(stderr, "Error: could not extend in-built modules table\n");
        exit(1);
    @}

    /* Pass argv[0] to the Python interpreter */
    status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}

    /* Initialize the Python interpreter.  Required.
       If this step fails, it will be a fatal error. */
    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}
    PyConfig_Clear(&config);

    /* Optionally import the module; alternatively,
       import can be deferred until the embedded script
       imports it. */
    PyObject *pmodule = PyImport_ImportModule("spam");
    if (!pmodule) @{
        PyErr_Print();
        fprintf(stderr, "Error: could not import module 'spam'\n");
    @}

    // ... use Python C API here ...

    return 0;

  exception:
     PyConfig_Clear(&config);
     Py_ExitStatusException(status);
@}
@end example

@cartouche
@quotation Note 
supprimer des entrées de @code{sys.modules} ou importer des modules compilés dans plusieurs interpréteurs au sein d'un même processus (ou le faire à la suite d'un @code{fork()} sans un @code{exec()} préalable) peut créer des problèmes pour certains modules d'extension. Les auteurs de modules d'extension doivent faire preuve de prudence lorsqu'ils initialisent des structures de données internes.
@end quotation
@end cartouche

Un exemple de module plus substantiel est inclus dans la distribution des sources Python sous le nom @code{Modules/xxmodule.c}. Ce fichier peut être utilisé comme modèle ou simplement lu comme exemple.

@cartouche
@quotation Note 
contrairement à notre exemple de @code{spam}, @code{xxmodule} utilise une `initialisation multi-phases' (nouveau en Python 3.5), où une structure `PyModuleDef' est renvoyée à partir de @code{PyInit_spam}, et la création du module est laissée au mécanisme d'importation. Pour plus de détails sur l'initialisation multi-phases, voir 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}.
@end quotation
@end cartouche

@node Compilation et liaison,Appeler des fonctions Python en C,La fonction d'initialisation et le tableau des méthodes du module,Étendre Python en C ou C++
@anchor{extending/extending compilation}@anchor{47c5}@anchor{extending/extending compilation-and-linkage}@anchor{47c6}
@subsubsection Compilation et liaison


Il y a encore deux choses à faire avant de pouvoir utiliser votre nouvelle extension : la compiler et la lier au système Python. Si vous utilisez le chargement dynamique, les détails peuvent dépendre du style de chargement dynamique utilisé par votre système ; voir les chapitres sur la compilation de modules d'extension (chapitre @ref{47c7,,Construire des extensions C et C++}) et les informations supplémentaires concernant uniquement la construction sous Windows (chapitre @ref{1dc2,,Construire des extensions C et C++ sur Windows}) pour plus d'informations à ce sujet.

Si vous ne pouvez pas utiliser le chargement dynamique, ou si vous voulez faire de votre module une partie permanente de l'interpréteur Python, vous devez modifier la configuration et reconstruire l'interpréteur. Heureusement, c'est très simple sous Unix : placez simplement votre fichier (@code{spammodule.c} par exemple) dans le répertoire @code{Modules/} d'une distribution source décompressée, ajoutez une ligne au fichier @code{Modules/Setup.local} décrivant votre fichier :

@example
spam spammodule.o
@end example

et reconstruisez l'interpréteur en exécutant @code{make} dans le répertoire de niveau supérieur. Vous pouvez également exécuter @code{make} dans le sous-répertoire @code{Modules/}, mais vous devez d'abord reconstruire le @code{Makefile} en exécutant « @code{make} Makefile » (c'est nécessaire chaque fois que vous modifiez le fichier @code{Setup}).

Si votre module nécessite d'être lié à des bibliothèques supplémentaires, celles-ci peuvent être ajoutées à la fin de la ligne de votre module dans le fichier de configuration, par exemple :

@example
spam spammodule.o -lX11
@end example

@node Appeler des fonctions Python en C,Extraire des paramètres dans des fonctions d'extension,Compilation et liaison,Étendre Python en C ou C++
@anchor{extending/extending calling-python-functions-from-c}@anchor{47c8}@anchor{extending/extending callingpython}@anchor{47c9}
@subsubsection Appeler des fonctions Python en C


Jusqu'à présent, nous nous sommes concentrés sur le fait de rendre les fonctions C appelables depuis Python. L'inverse est également utile : appeler des fonctions Python depuis C. C'est notamment le cas pour les bibliothèques qui gèrent les fonctions dites de « rappel » (`callback' en anglais). Si une interface C utilise des rappels, l'équivalent Python doit souvent fournir un mécanisme de rappel au développeur Python ; l'implémentation nécessite d'appeler les fonctions de rappel Python à partir d'un rappel C. D'autres utilisations sont également envisageables.

Heureusement, l'interpréteur Python est facilement appelé de manière récursive et il existe une interface standard pour appeler une fonction Python (nous ne nous attarderons pas sur la façon d'appeler l'analyseur Python avec une chaîne particulière en entrée — si vous êtes intéressé, jetez un œil à l'implémentation de l'option de ligne de commande @ref{5ca,,-c} dans @code{Modules/main.c} à partir du code source Python).

L'appel d'une fonction Python est facile. Tout d'abord, le programme Python doit vous transmettre d'une manière ou d'une autre l'objet de fonction Python. Vous devez fournir une fonction (ou une autre interface) pour ce faire. Lorsque cette fonction est appelée, enregistrez un pointeur vers l'objet de la fonction Python (faites attention à @ref{55a,,Py_INCREF()} !) dans une variable globale — ou là où vous le souhaitez. Par exemple, la fonction suivante peut faire partie d'une définition de module :

@example
static PyObject *my_callback = NULL;

static PyObject *
my_set_callback(PyObject *dummy, PyObject *args)
@{
    PyObject *result = NULL;
    PyObject *temp;

    if (PyArg_ParseTuple(args, "O:set_callback", &temp)) @{
        if (!PyCallable_Check(temp)) @{
            PyErr_SetString(PyExc_TypeError, "parameter must be callable");
            return NULL;
        @}
        Py_XINCREF(temp);         /* Add a reference to new callback */
        Py_XDECREF(my_callback);  /* Dispose of previous callback */
        my_callback = temp;       /* Remember new callback */
        /* Boilerplate to return "None" */
        Py_INCREF(Py_None);
        result = Py_None;
    @}
    return result;
@}
@end example

Cette fonction doit être déclarée en utilisant le drapeau @ref{14c0,,METH_VARARGS} ; ceci est décrit dans la section @ref{47c1,,La fonction d'initialisation et le tableau des méthodes du module}.  La fonction @ref{55d,,PyArg_ParseTuple()} et ses arguments sont documentés dans la section @ref{47ca,,Extraire des paramètres dans des fonctions d'extension}.

Les macros @ref{a53,,Py_XINCREF()} et @ref{779,,Py_XDECREF()} incrémentent/décrémentent le compteur des références d'un objet et sont sûres quant à la présence de pointeurs @code{NULL} (mais notez que `temp' ne sera pas @code{NULL} dans ce contexte).  Plus d'informations à ce sujet dans la section @ref{47cb,,Compteurs de références}.

@geindex PyObject_CallObject (C function)

Plus tard, quand il est temps d'appeler la fonction, vous appelez la fonction C @ref{47cc,,PyObject_CallObject()}. Cette fonction requiert deux arguments, tous deux des pointeurs vers des objets Python arbitraires : la fonction Python et la liste d'arguments. La liste d'arguments doit toujours être un objet `n'-uplet, dont la longueur est le nombre d'arguments. Pour appeler la fonction Python sans argument, passez @code{NULL} ou le `n'-uplet vide ; pour l'appeler avec un argument, passez un `n'-uplet singleton. @ref{894,,Py_BuildValue()} renvoie un `n'-uplet lorsque sa chaîne de format se compose de zéro ou plusieurs codes de format entre parenthèses. Par exemple :

@example
int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Time to call the callback */
arglist = Py_BuildValue("(i)", arg);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
@end example

@ref{47cc,,PyObject_CallObject()} renvoie un pointeur d'objet Python : c'est la valeur de retour de la fonction Python. @ref{47cc,,PyObject_CallObject()} est « neutre en nombre de références » par rapport à ses arguments. Dans l'exemple, un nouveau `n'-uplet a été créé pour servir de liste d'arguments, qui est décrémenté (avec @ref{55b,,Py_DECREF()}) immédiatement après l'appel @ref{47cc,,PyObject_CallObject()}.

La valeur de retour de @ref{47cc,,PyObject_CallObject()} est « nouvelle » : soit c'est un tout nouvel objet, soit c'est un objet existant dont le nombre de références a été incrémenté. Donc, à moins que vous ne vouliez l'enregistrer dans une variable globale, vous devriez en quelque sorte décrémenter avec @ref{55b,,Py_DECREF()} le résultat, même (surtout !) si vous n'êtes pas intéressé par sa valeur.

Mais avant de le faire, il est important de vérifier que la valeur renvoyée n'est pas @code{NULL}.  Si c'est le cas, la fonction Python s'est terminée par une levée d'exception. Si le code C qui a appelé @ref{47cc,,PyObject_CallObject()} est appelé depuis Python, il devrait maintenant renvoyer une indication d'erreur à son appelant Python, afin que l'interpréteur puisse afficher la pile d'appels, ou que le code Python appelant puisse gérer l'exception. Si cela n'est pas possible ou souhaitable, l'exception doit être effacée en appelant @ref{101a,,PyErr_Clear()}. Par exemple :

@example
if (result == NULL)
    return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
@end example

Selon l'interface souhaitée pour la fonction de rappel Python, vous devrez peut-être aussi fournir une liste d'arguments à @ref{47cc,,PyObject_CallObject()}. Dans certains cas, la liste d'arguments est également fournie par le programme Python, par l'intermédiaire de la même interface qui a spécifié la fonction de rappel. Elle peut alors être sauvegardée et utilisée de la même manière que l'objet fonction. Dans d'autres cas, vous pouvez avoir à construire un nouveau `n'-uplet à passer comme liste d'arguments. La façon la plus simple de faire cela est d'appeler @ref{894,,Py_BuildValue()}. Par exemple, si vous voulez passer un code d'événement intégral, vous pouvez utiliser le code suivant :

@example
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
    return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
@end example

Notez la présence de @code{Py_DECREF(arglist)} immédiatement après l'appel, avant la vérification des erreurs ! Notez également qu'à proprement parler, ce code n'est pas complet : @ref{894,,Py_BuildValue()} peut manquer de mémoire, et cela doit être vérifié.

Vous pouvez également appeler une fonction avec des arguments nommés en utilisant @ref{393,,PyObject_Call()}, qui accepte les arguments et les arguments nommés. Comme dans l'exemple ci-dessus, nous utilisons @ref{894,,Py_BuildValue()} pour construire le dictionnaire.

@example
PyObject *dict;
...
dict = Py_BuildValue("@{s:i@}", "name", val);
result = PyObject_Call(my_callback, NULL, dict);
Py_DECREF(dict);
if (result == NULL)
    return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
@end example

@node Extraire des paramètres dans des fonctions d'extension,Paramètres nommés pour des fonctions d'extension,Appeler des fonctions Python en C,Étendre Python en C ou C++
@anchor{extending/extending extracting-parameters-in-extension-functions}@anchor{47cd}@anchor{extending/extending parsetuple}@anchor{47ca}
@subsubsection Extraire des paramètres dans des fonctions d'extension


@geindex PyArg_ParseTuple (C function)

La fonction @ref{55d,,PyArg_ParseTuple()} est déclarée ainsi :

@example
int PyArg_ParseTuple(PyObject *arg, const char *format, ...);
@end example

L'argument `arg' doit être un `n'-uplet contenant une liste d'arguments passée de Python à une fonction C. L'argument `format' doit être une chaîne de format, dont la syntaxe est expliquée dans @ref{895,,Analyse des arguments et construction des valeurs} dans le manuel de référence de l'API Python/C. Les arguments restants doivent être des adresses de variables dont le type est déterminé par la chaîne de format.

Notez que si @ref{55d,,PyArg_ParseTuple()} vérifie que les arguments Python ont les types requis, elle ne peut pas vérifier la validité des adresses des variables C transmises à l'appel : si vous y faites des erreurs, votre code plantera probablement ou au moins écrasera des bits aléatoires en mémoire. Donc soyez prudent !

Notez que toute référence sur un objet Python donnée à l'appelant est une référence `empruntée' ; ne décrémentez pas son compteur de références !

Quelques exemples d'appels :

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
@end example

@example
int ok;
int i, j;
long k, l;
const char *s;
Py_ssize_t size;

ok = PyArg_ParseTuple(args, ""); /* No arguments */
    /* Python call: f() */
@end example

@example
ok = PyArg_ParseTuple(args, "s", &s); /* A string */
    /* Possible Python call: f('whoops!') */
@end example

@example
ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
    /* Possible Python call: f(1, 2, 'three') */
@end example

@example
ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
    /* A pair of ints and a string, whose size is also returned */
    /* Possible Python call: f((1, 2), 'three') */
@end example

@example
@{
    const char *file;
    const char *mode = "r";
    int bufsize = 0;
    ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
    /* A string, and optionally another string and an integer */
    /* Possible Python calls:
       f('spam')
       f('spam', 'w')
       f('spam', 'wb', 100000) */
@}
@end example

@example
@{
    int left, top, right, bottom, h, v;
    ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
             &left, &top, &right, &bottom, &h, &v);
    /* A rectangle and a point */
    /* Possible Python call:
       f(((0, 0), (400, 300)), (10, 10)) */
@}
@end example

@example
@{
    Py_complex c;
    ok = PyArg_ParseTuple(args, "D:myfunction", &c);
    /* a complex, also providing a function name for errors */
    /* Possible Python call: myfunction(1+2j) */
@}
@end example

@node Paramètres nommés pour des fonctions d'extension,Créer des valeurs arbitraires,Extraire des paramètres dans des fonctions d'extension,Étendre Python en C ou C++
@anchor{extending/extending keyword-parameters-for-extension-functions}@anchor{47ce}@anchor{extending/extending parsetupleandkeywords}@anchor{47cf}
@subsubsection Paramètres nommés pour des fonctions d'extension


@geindex PyArg_ParseTupleAndKeywords (C function)

La fonction @ref{379,,PyArg_ParseTupleAndKeywords()} est déclarée ainsi :

@example
int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                const char *format, char * const *kwlist, ...);
@end example

Les paramètres `arg' et `format' sont identiques à ceux de la fonction @ref{55d,,PyArg_ParseTuple()}. Le paramètre `kwdict' est le dictionnaire de mots-clés reçu comme troisième paramètre du `runtime' Python. Le paramètre `kwlist' est une liste de chaînes de caractères terminée par @code{NULL} qui identifie les paramètres ; les noms sont mis en correspondance, de gauche à droite, avec les informations de type de `format'. En cas de succès du processus, @ref{379,,PyArg_ParseTupleAndKeywords()} renvoie vrai, sinon elle renvoie faux et lève une exception appropriée.

@cartouche
@quotation Note 
les `n'-uplets imbriqués ne peuvent pas être traités lorsqu'on utilise des arguments nommés ! Ceux-ci doivent apparaître dans `kwlist', dans le cas contraire une exception @ref{522,,TypeError} est levée.
@end quotation
@end cartouche

@geindex Philbrick@comma{} Geoff

Voici un exemple de module qui utilise des arguments nommés, basé sur un exemple de `Geoff Philbrick' (@email{philbrick@@hks.com}) :

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
@{
    int voltage;
    const char *state = "a stiff";
    const char *action = "voom";
    const char *type = "Norwegian Blue";

    static char *kwlist[] = @{"voltage", "state", "action", "type", NULL@};

    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                     &voltage, &state, &action, &type))
        return NULL;

    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
           action, voltage);
    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

    Py_RETURN_NONE;
@}

static PyMethodDef keywdarg_methods[] = @{
    /* The cast of the function is necessary since PyCFunction values
     * only take two PyObject* parameters, and keywdarg_parrot() takes
     * three.
     */
    @{"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
     "Print a lovely skit to standard output."@},
    @{NULL, NULL, 0, NULL@}   /* sentinel */
@};

static struct PyModuleDef keywdargmodule = @{
    PyModuleDef_HEAD_INIT,
    "keywdarg",
    NULL,
    -1,
    keywdarg_methods
@};

PyMODINIT_FUNC
PyInit_keywdarg(void)
@{
    return PyModule_Create(&keywdargmodule);
@}
@end example

@node Créer des valeurs arbitraires,Compteurs de références,Paramètres nommés pour des fonctions d'extension,Étendre Python en C ou C++
@anchor{extending/extending building-arbitrary-values}@anchor{47d0}@anchor{extending/extending buildvalue}@anchor{47d1}
@subsubsection Créer des valeurs arbitraires


Cette fonction est le complément de @ref{55d,,PyArg_ParseTuple()}.  Elle est déclarée comme suit :

@example
PyObject *Py_BuildValue(const char *format, ...);
@end example

Elle reconnaît un ensemble d'unités de format similaires à celles reconnues par @ref{55d,,PyArg_ParseTuple()}, mais les arguments (qui sont les données en entrée de la fonction, et non de la sortie) ne doivent pas être des pointeurs, mais juste des valeurs. Elle renvoie un nouvel objet Python, adapté pour être renvoyé par une fonction C appelée depuis Python.

Une différence avec @ref{55d,,PyArg_ParseTuple()} : alors que cette dernière nécessite que son premier argument soit un `n'-uplet (puisque les listes d'arguments Python sont toujours représentées comme des `n'-uplets en interne), @ref{894,,Py_BuildValue()} ne construit pas toujours un `n'-uplet. Elle construit un `n'-uplet uniquement si sa chaîne de format contient deux unités de format ou plus. Si la chaîne de format est vide, elle renvoie @code{None} ; si elle contient exactement une unité de format, elle renvoie tout objet décrit par cette unité de format. Pour la forcer à renvoyer un `n'-uplet de taille 0 ou un, mettez la chaîne de format entre parenthèses.

Exemples (à gauche l'appel, à droite la valeur résultante, en Python) :

@example
Py_BuildValue("")                        None
Py_BuildValue("i", 123)                  123
Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
Py_BuildValue("s", "hello")              'hello'
Py_BuildValue("y", "hello")              b'hello'
Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
Py_BuildValue("s#", "hello", 4)          'hell'
Py_BuildValue("y#", "hello", 4)          b'hell'
Py_BuildValue("()")                      ()
Py_BuildValue("(i)", 123)                (123,)
Py_BuildValue("(ii)", 123, 456)          (123, 456)
Py_BuildValue("(i,i)", 123, 456)         (123, 456)
Py_BuildValue("[i,i]", 123, 456)         [123, 456]
Py_BuildValue("@{s:i,s:i@}",
              "abc", 123, "def", 456)    @{'abc': 123, 'def': 456@}
Py_BuildValue("((ii)(ii)) (ii)",
              1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))
@end example

@node Compteurs de références,Écrire des extensions en C++,Créer des valeurs arbitraires,Étendre Python en C ou C++
@anchor{extending/extending refcounts}@anchor{47cb}@anchor{extending/extending reference-counts}@anchor{47d2}
@subsubsection Compteurs de références


Dans les langages comme le C ou le C++, le développeur est responsable de l'allocation dynamique et de la dés-allocation de la mémoire sur le tas. En C, cela se fait à l'aide des fonctions @code{malloc()} et @code{free()}. En C++, les opérateurs  @code{new} et @code{delete}  sont utilisés avec essentiellement la même signification et nous limiterons la discussion suivante au cas du C.

Every block of memory allocated with @code{malloc()} should eventually be
returned to the pool of available memory by exactly one call to @code{free()}.
It is important to call @code{free()} at the right time.  If a block's address
is forgotten but @code{free()} is not called for it, the memory it occupies
cannot be reused until the program terminates.  This is called a `memory
leak'.  On the other hand, if a program calls @code{free()} for a block and then
continues to use the block, it creates a conflict with reuse of the block
through another @code{malloc()} call.  This is called `using freed memory'.
It has the same bad consequences as referencing uninitialized data --- core
dumps, wrong results, mysterious crashes.

Les causes courantes des fuites de mémoire sont des exécutions inhabituelles du code. Par exemple, une fonction peut allouer un bloc de mémoire, effectuer des calculs, puis libérer le bloc. Plus tard, une modification des exigences de la fonction peut ajouter un test au calcul qui détecte une condition d'erreur et peut sortir prématurément de la fonction. Il est facile d'oublier de libérer le bloc de mémoire alloué lors de cette sortie prématurée, surtout lorsqu'elle est ajoutée ultérieurement au code. De telles fuites, une fois introduites, passent souvent inaperçues pendant longtemps : la sortie d'erreur n'est prise que dans une petite fraction de tous les appels, et la plupart des machines modernes ont beaucoup de mémoire virtuelle, de sorte que la fuite ne devient apparente que dans un processus de longue durée qui utilise fréquemment cette fonction. Par conséquent, il est important d'éviter les fuites en ayant une convention ou une stratégie de codage qui minimise ce type d'erreurs.

Comme Python fait un usage intensif de @code{malloc()} et de @code{free()}, il a besoin d'une stratégie pour éviter les fuites de mémoire ainsi que l'utilisation de la mémoire libérée. La méthode choisie est appelée le `comptage de références'. Le principe est simple : chaque objet contient un compteur, qui est incrémenté lorsqu'une référence à l'objet est stockée quelque part, et qui est décrémenté lorsqu'une référence à celui-ci est supprimée. Lorsque le compteur atteint zéro, la dernière référence à l'objet a été supprimée et l'objet est libéré.

Une stratégie alternative est appelée `ramasse-miettes automatique' (`automatic garbage collection' en anglais). Parfois, le comptage des références est également appelé stratégie de ramasse-miettes, d'où l'utilisation du terme « automatique » pour distinguer les deux. Le grand avantage du ramasse-miettes est que l'utilisateur n'a pas besoin d'appeler @code{free()} explicitement (un autre avantage important est l'amélioration de la vitesse ou de l'utilisation de la mémoire, ce n'est cependant pas un fait avéré). L'inconvénient est que pour C, il n'y a pas de ramasse-miettes portable proprement-dit, alors que le comptage des références peut être implémenté de façon portable (tant que les fonctions @code{malloc()} et @code{free()} sont disponibles, ce que la norme C garantit). Peut-être qu'un jour un ramasse-miettes suffisamment portable sera disponible pour C. D'ici là, nous devons utiliser les compteurs de références.

Bien que Python utilise l'implémentation traditionnelle de comptage de références, il contient également un détecteur de cycles qui fonctionne pour détecter les cycles de références. Cela permet aux applications de ne pas se soucier de la création de références circulaires directes ou indirectes ; celles-ci sont les faiblesses des ramasse-miettes utilisant uniquement le comptage de références. Les cycles de références sont constitués d'objets qui contiennent des références (éventuellement indirectes) à eux-mêmes, de sorte que chaque objet du cycle a un compteur de références qui n'est pas nul. Les implémentations typiques de comptage de références ne sont pas capables de récupérer la mémoire des objets appartenant à un cycle de références, ou référencés à partir des objets dans le cycle, même s'il n'y a pas d'autre référence au cycle lui-même.

Le détecteur de cycle est capable de détecter les cycles isolés et peut récupérer la mémoire afférente. Le module @ref{5f,,gc} expose un moyen d'exécuter le détecteur (la fonction @ref{a28,,collect()}), ainsi que des interfaces de configuration et la possibilité de désactiver le détecteur au moment de l'exécution.

@menu
* Comptage de références en Python:: 
* Règles concernant la possession de références:: 
* Terrain dangereux:: 
* Pointeurs NULL:: 

@end menu

@node Comptage de références en Python,Règles concernant la possession de références,,Compteurs de références
@anchor{extending/extending refcountsinpython}@anchor{47d3}@anchor{extending/extending reference-counting-in-python}@anchor{47d4}
@subsubsection Comptage de références en Python


Il existe deux macros, @code{Py_INCREF(x)} et @code{Py_DECREF(x)}, qui gèrent l'incrémentation et la décrémentation du comptage de références. @ref{55b,,Py_DECREF()} libère également l'objet lorsque le compteur atteint zéro. Pour plus de flexibilité, il n'appelle pas @code{free()} directement — plutôt, il fait un appel à travers un pointeur de fonction dans l'objet `type objet' de l'objet.  À cette fin (et pour d'autres), chaque objet contient également un pointeur vers son objet type.

La grande question demeure maintenant : quand utiliser @code{Py_INCREF(x)} et @code{Py_DECREF(x)} ? Commençons par définir quelques termes. Personne ne possède un objet, mais vous pouvez en `avoir une référence'. Le compteur de références d'un objet est maintenant défini comme étant le nombre de références à cet objet. Le propriétaire d'une référence est responsable d'appeler @ref{55b,,Py_DECREF()} lorsque la référence n'est plus nécessaire. La possession d'une référence peut être transférée. Il y a trois façons de se débarrasser d'une référence que l'on possède : la transmettre, la stocker ou appeler @ref{55b,,Py_DECREF()}. Oublier de se débarrasser d'une référence crée une fuite de mémoire.

Il est également possible d'`emprunter' @footnote{
L'expression « emprunter une référence » n'est pas tout à fait correcte, car le propriétaire a toujours une copie de la référence.
} une référence à un objet. L'emprunteur d'une référence ne doit pas appeler @ref{55b,,Py_DECREF()}. L'emprunteur ne doit pas conserver l'objet plus longtemps que le propriétaire à qui il a été emprunté. L'utilisation d'une référence empruntée après que le propriétaire s'en est débarrassée risque d'utiliser de la mémoire libérée et doit être absolument évitée @footnote{
Vérifier que le comptage de référence est d'au moins 1 `ne fonctionne pas', le compte de référence lui-même pourrait être en mémoire libérée et peut donc être réutilisé pour un autre objet !
}.

L'avantage d'emprunter, plutôt qu'être propriétaire d'une référence, est que vous n'avez pas à vous soucier de libérer la référence sur tous les chemins possibles dans le code — en d'autres termes, avec une référence empruntée, vous ne courez pas le risque de fuites lors d'une sortie prématurée. L'inconvénient de l'emprunt par rapport à la possession est qu'il existe certaines situations subtiles où, dans un code apparemment correct, une référence empruntée peut être utilisée après que le propriétaire auquel elle a été empruntée l'a en fait éliminée.

Une référence empruntée peut être changée en une référence possédée en appelant @ref{55a,,Py_INCREF()}. Cela n'affecte pas le statut du propriétaire à qui la référence a été empruntée — cela crée une nouvelle référence possédée et donne l'entière responsabilité au propriétaire (le nouveau propriétaire doit libérer la référence correctement, ainsi que le propriétaire précédent).

@node Règles concernant la possession de références,Terrain dangereux,Comptage de références en Python,Compteurs de références
@anchor{extending/extending ownership-rules}@anchor{47d5}@anchor{extending/extending ownershiprules}@anchor{47d6}
@subsubsection Règles concernant la possession de références


Chaque fois qu'une référence d'objet est passée à l'intérieur ou à l'extérieur d'une fonction, elle fait partie de la spécification de l'interface de la fonction, peu importe que la possession soit transférée avec la référence ou non.

La plupart des fonctions qui renvoient une référence à un objet transmettent la possession avec la référence. En particulier, toutes les fonctions dont la fonction est de créer un nouvel objet, telles que @ref{17c7,,PyLong_FromLong()} et @ref{894,,Py_BuildValue()}, transmettent la possession au récepteur. Même si l'objet n'est pas réellement nouveau, vous recevez toujours la possession d'une nouvelle référence à cet objet. Par exemple, @ref{17c7,,PyLong_FromLong()} maintient un cache des valeurs souvent utilisées et peut renvoyer une référence à un élément mis en cache.

De nombreuses fonctions qui extraient des objets d'autres objets transfèrent également la possession avec la référence, par exemple @ref{342,,PyObject_GetAttrString()}. L'image est moins claire ici, cependant, puisque quelques routines courantes sont des exceptions : @ref{47d7,,PyTuple_GetItem()}, @ref{352,,PyList_GetItem()}, @ref{37d,,PyDict_GetItem()} et @ref{37e,,PyDict_GetItemString()} renvoient toutes des références qui sont empruntées au `n'-uplet, à la liste ou au dictionnaire.

La fonction @ref{34f,,PyImport_AddModule()} renvoie également une référence empruntée, même si elle peut en fait créer l'objet qu'elle renvoie : c'est possible car une référence à l'objet est stockée dans @code{sys.modules}.

Lorsque vous passez une référence d'objet dans une autre fonction, en général, la fonction vous emprunte la référence — si elle a besoin de la stocker, elle utilise @ref{55a,,Py_INCREF()} pour devenir un propriétaire indépendant. Il existe exactement deux exceptions importantes à cette règle : @ref{47d8,,PyTuple_SetItem()} et @ref{47d9,,PyList_SetItem()}. Ces fonctions s'approprient l'élément qui leur est transmis, même en cas d'échec ! (Notez que @ref{47da,,PyDict_SetItem()} et compagnie ne prennent pas la possession de l'objet, elles sont « normales ».)

Lorsqu'une fonction C est appelée depuis Python, elle emprunte à l'appelant des références aux arguments. L'appelant possède une référence à l'objet, de sorte que la durée de vie de la référence empruntée est garantie jusqu'au retour de la fonction. Ce n'est que lorsqu'une telle référence empruntée doit être stockée ou transmise qu'elle doit être transformée en référence possédée en appelant @ref{55a,,Py_INCREF()}.

La référence d'objet renvoyée par une fonction C appelée depuis Python doit être une référence détenue en propre — la possession est transférée de la fonction à son appelant.

@node Terrain dangereux,Pointeurs NULL,Règles concernant la possession de références,Compteurs de références
@anchor{extending/extending thin-ice}@anchor{47db}@anchor{extending/extending thinice}@anchor{47dc}
@subsubsection Terrain dangereux


Il existe quelques situations où l'utilisation apparemment inoffensive d'une référence empruntée peut entraîner des problèmes. Tous ces problèmes sont en lien avec des invocations implicites de l’interpréteur et peuvent amener le propriétaire d'une référence à s'en défaire.

Le premier cas, et le plus important à connaître, est celui de l'utilisation de @ref{55b,,Py_DECREF()} à un objet non relié lors de l'emprunt d'une référence à un élément de liste. Par exemple :

@example
void
bug(PyObject *list)
@{
    PyObject *item = PyList_GetItem(list, 0);

    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0); /* BUG! */
@}
@end example

Cette fonction emprunte d'abord une référence à  @code{list[0]}, puis remplace  @code{list[1]} par la valeur  @code{0}, et enfin affiche la référence empruntée. Ça a l'air inoffensif, n'est-ce pas ? Mais ce n'est pas le cas !

Let's follow the control flow into @ref{47d9,,PyList_SetItem()}.  The list owns
references to all its items, so when item 1 is replaced, it has to dispose of
the original item 1.  Now let's suppose the original item 1 was an instance of a
user-defined class, and let's further suppose that the class defined a
@code{__del__()} method.  If this class instance has a reference count of 1,
disposing of it will call its @code{__del__()} method.

Since it is written in Python, the @code{__del__()} method can execute arbitrary
Python code.  Could it perhaps do something to invalidate the reference to
@code{item} in @code{bug()}?  You bet!  Assuming that the list passed into
@code{bug()} is accessible to the @code{__del__()} method, it could execute a
statement to the effect of @code{del list[0]}, and assuming this was the last
reference to that object, it would free the memory associated with it, thereby
invalidating @code{item}.

La solution, une fois que vous connaissez la source du problème, est simple : incrémentez temporairement le compteur de références. La version correcte de la fonction est :

@example
void
no_bug(PyObject *list)
@{
    PyObject *item = PyList_GetItem(list, 0);

    Py_INCREF(item);
    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0);
    Py_DECREF(item);
@}
@end example

This is a true story.  An older version of Python contained variants of this bug
and someone spent a considerable amount of time in a C debugger to figure out
why his @code{__del__()} methods would fail...

Le deuxième cas de problèmes liés à une référence empruntée est une variante impliquant des fils d'exécution. Normalement, plusieurs threads dans l'interpréteur Python ne peuvent pas se gêner mutuellement, car il existe un verrou global protégeant tout l'espace objet de Python. Cependant, il est possible de libérer temporairement ce verrou en utilisant la macro @ref{47dd,,Py_BEGIN_ALLOW_THREADS}, et de le ré-acquérir en utilisant @ref{a7c,,Py_END_ALLOW_THREADS}. Ceci est un procédé courant pour bloquer les appels d'entrées/sorties, afin de permettre aux autres threads d'utiliser le processeur en attendant que les E/S soient terminées. Évidemment, la fonction suivante a le même problème que la précédente :

@example
void
bug(PyObject *list)
@{
    PyObject *item = PyList_GetItem(list, 0);
    Py_BEGIN_ALLOW_THREADS
    ...some blocking I/O call...
    Py_END_ALLOW_THREADS
    PyObject_Print(item, stdout, 0); /* BUG! */
@}
@end example

@node Pointeurs NULL,,Terrain dangereux,Compteurs de références
@anchor{extending/extending null-pointers}@anchor{47de}@anchor{extending/extending nullpointers}@anchor{47df}
@subsubsection Pointeurs @code{NULL}


En général, les fonctions qui prennent des références d'objets comme arguments ne sont pas conçues pour recevoir des pointeurs @code{NULL}, et si vous en donnez comme arguments, elles causeront une erreur de segmentation (ou provoqueront des `core dump' ultérieurs). Les fonctions qui renvoient des références d'objets renvoient généralement @code{NULL} uniquement pour indiquer qu'une exception s'est produite.  La raison pour laquelle les arguments @code{NULL} ne sont pas testés est que les fonctions passent souvent les objets qu'elles reçoivent à d'autres fonctions, si chaque fonction devait tester pour @code{NULL}, il y aurait beaucoup de tests redondants et le code s'exécuterait plus lentement.

Il est préférable de tester la présence de @code{NULL} uniquement au début : lorsqu'un pointeur qui peut être @code{NULL} est reçu, par exemple, de @code{malloc()} ou d'une fonction qui peut lever une exception.

Les macros @ref{55a,,Py_INCREF()} et @ref{55b,,Py_DECREF()} ne vérifient pas les pointeurs @code{NULL}. Cependant, leurs variantes @ref{a53,,Py_XINCREF()} et @ref{779,,Py_XDECREF()} le font.

Les macros de vérification d'un type d'objet particulier (@code{Pytype_Check()}) ne vérifient pas les pointeurs @code{NULL} — encore une fois, il y a beaucoup de code qui en appelle plusieurs à la suite pour tester un objet par rapport à différents types attendus, ce qui générerait des tests redondants. Il n'y a pas de variantes avec la vérification @code{NULL}.

Le mécanisme d'appel de fonctions C garantit que la liste d'arguments passée aux fonctions C (@code{args} dans les exemples) n'est jamais @code{NULL}. En fait, il garantit qu'il s'agit toujours d'un `n'-uplet @footnote{
Ces garanties ne sont pas valables lorsqu'on emploie les conventions de nommage anciennes, qu'on retrouve encore assez souvent dans beaucoup de code existant.
}.

C'est une grave erreur de laisser un pointeur @code{NULL} « s'échapper » vers l'utilisateur Python.

@c Frank Stajano:
@c A pedagogically buggy example, along the lines of the previous listing, would
@c be helpful here -- showing in more concrete terms what sort of actions could
@c cause the problem. I can't very well imagine it from the description.

@node Écrire des extensions en C++,Fournir une API en langage C pour un module d'extension,Compteurs de références,Étendre Python en C ou C++
@anchor{extending/extending cplusplus}@anchor{47e0}@anchor{extending/extending writing-extensions-in-c}@anchor{47e1}
@subsubsection Écrire des extensions en C++


C'est possible d'écrire des modules d'extension en C++, mais sous certaines conditions. Si le programme principal (l'interpréteur Python) est compilé et lié par le compilateur C, les objets globaux ou statiques avec les constructeurs ne peuvent pas être utilisés. Ceci n'est pas un problème si le programme principal est relié par le compilateur C++. Les fonctions qui seront appelées par l'interpréteur Python (en particulier, les fonctions d'initialisation des modules) doivent être déclarées en utilisant @code{extern "C"}. Il n'est pas nécessaire d'inclure les fichiers d'en-tête Python dans le @code{extern "C" @{…@}}, car ils utilisent déjà ce format si le symbole @code{__cplusplus} est défini (tous les compilateurs C++ récents définissent ce symbole).

@node Fournir une API en langage C pour un module d'extension,,Écrire des extensions en C++,Étendre Python en C ou C++
@anchor{extending/extending providing-a-c-api-for-an-extension-module}@anchor{47e2}@anchor{extending/extending using-capsules}@anchor{1334}
@subsubsection Fournir une API en langage C pour un module d'extension


De nombreux modules d'extension fournissent simplement de nouvelles fonctions et de nouveaux types à utiliser à partir de Python, mais parfois le code d'un module d'extension peut être utile pour d'autres modules d'extension. Par exemple, un module d'extension peut mettre en œuvre un type « collection » qui fonctionne comme des listes sans ordre. Tout comme le type de liste Python standard possède une API C qui permet aux modules d'extension de créer et de manipuler des listes, ce nouveau type de collection devrait posséder un ensemble de fonctions C pour une manipulation directe à partir d'autres modules d'extension.

À première vue, cela semble facile : il suffit d'écrire les fonctions (sans les déclarer « statiques », bien sûr), de fournir un fichier d'en-tête approprié et de documenter l'API C. Et en fait, cela fonctionnerait si tous les modules d'extension étaient toujours liés statiquement avec l'interpréteur Python. Cependant, lorsque les modules sont utilisés comme des bibliothèques partagées, les symboles définis dans un module peuvent ne pas être visibles par un autre module. Les détails de la visibilité dépendent du système d'exploitation ; certains systèmes utilisent un espace de noms global pour l'interpréteur Python et tous les modules d'extension (Windows, par exemple), tandis que d'autres exigent une liste explicite des symboles importés au moment de la liaison des modules (AIX en est un exemple), ou offrent un choix de stratégies différentes (la plupart des `Unix'). Et même si les symboles sont globalement visibles, le module dont on souhaite appeler les fonctions n'est peut-être pas encore chargé !

La portabilité exige donc de ne faire aucune supposition sur la visibilité des symboles. Cela signifie que tous les symboles des modules d'extension doivent être déclarés @code{static}, à l'exception de la fonction d'initialisation du module, afin d'éviter les conflits de noms avec les autres modules d'extension (comme discuté dans la section @ref{47c1,,La fonction d'initialisation et le tableau des méthodes du module}). Et cela signifie que les symboles qui `devraient' être accessibles à partir d'autres modules d'extension doivent être exportés d'une manière différente.

Python fournit un mécanisme spécial pour transmettre des informations de niveau C (pointeurs) d'un module d'extension à un autre : les Capsules. Une capsule est un type de données Python qui stocke un pointeur (void*). Les capsules ne peuvent être créées et accessibles que via leur API C, mais elles peuvent être transmises comme n'importe quel autre objet Python. En particulier, elles peuvent être affectées à un nom dans l'espace de noms d'un module d'extension. D'autres modules d'extension peuvent alors importer ce module, récupérer la valeur de ce nom, puis récupérer le pointeur de la Capsule.

Il existe de nombreuses façons d'utiliser les Capsules pour exporter l'API C d'un module d'extension. Chaque fonction peut obtenir sa propre Capsule, ou tous les pointeurs de l'API C peuvent être stockés dans un tableau dont l'adresse est inscrite dans une Capsule. Et les différentes tâches de stockage et de récupération des pointeurs peuvent être réparties de différentes manières entre le module fournissant le code et les modules clients.

Quelle que soit la méthode que vous choisissez, il est important de bien nommer vos Capsules. La fonction @ref{47e3,,PyCapsule_New()} prend un paramètre nommé (const char*). Vous êtes autorisé à passer un nom @code{NULL}, mais nous vous encourageons vivement à spécifier un nom. Des Capsules correctement nommées offrent un certain degré de sécurité concernant un éventuel conflit de types, car il n'y a pas de moyen de distinguer deux ou plusieurs Capsules non nommées entre elles.

En particulier, les capsules utilisées pour exposer les API C doivent recevoir un nom suivant cette convention :

@example
modulename.attributename
@end example

La fonction de commodité @ref{17fb,,PyCapsule_Import()} permet de charger facilement une API C fournie via une Capsule, mais seulement si le nom de la Capsule correspond à cette convention. Ce comportement donne aux utilisateurs d'API C un degré élevé de certitude que la Capsule qu'ils chargent contient l'API C correcte.

L'exemple suivant montre une approche qui fait peser la plus grande partie de la charge sur le rédacteur du module d'exportation, ce qui est approprié pour les modules de bibliothèque couramment utilisés. Il stocke tous les pointeurs de l'API C (un seul dans l'exemple !) dans un tableau de pointeurs void qui devient la valeur d'une Capsule. Le fichier d'en-tête correspondant au module fournit une macro qui se charge d'importer le module et de récupérer ses pointeurs d'API C. Les modules clients n'ont qu'à appeler cette macro avant d'accéder à l'API C.

The exporting module is a modification of the @code{spam} module from section
@ref{47b9,,Un exemple simple}. The function @code{spam.system()} does not call
the C library function @code{system()} directly, but a function
@code{PySpam_System()}, which would of course do something more complicated in
reality (such as adding "spam" to every command). This function
@code{PySpam_System()} is also exported to other extension modules.

The function @code{PySpam_System()} is a plain C function, declared
@code{static} like everything else:

@example
static int
PySpam_System(const char *command)
@{
    return system(command);
@}
@end example

The function @code{spam_system()} is modified in a trivial way:

@example
static PyObject *
spam_system(PyObject *self, PyObject *args)
@{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = PySpam_System(command);
    return PyLong_FromLong(sts);
@}
@end example

Au début du module, immédiatement après la ligne :

@example
#include <Python.h>
@end example

on doit ajouter deux lignes supplémentaires :

@example
#define SPAM_MODULE
#include "spammodule.h"
@end example

L'indicateur @code{#define} est utilisé pour indiquer au fichier d'en-tête qu'il est inclus dans le module d'exportation, et non dans un module client. Enfin, la fonction d'initialisation du module doit prendre en charge l'initialisation du tableau de pointeurs de l'API C :

@example
PyMODINIT_FUNC
PyInit_spam(void)
@{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    /* Initialize the C API pointer array */
    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

    /* Create a Capsule containing the API pointer array's address */
    c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);

    if (PyModule_Add(m, "_C_API", c_api_object) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

Note that @code{PySpam_API} is declared @code{static}; otherwise the pointer
array would disappear when @code{PyInit_spam()} terminates!

L'essentiel du travail se trouve dans le fichier d'en-tête @code{spammodule.h}, qui ressemble à ceci :

@example
#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" @{
#endif

/* Header file for spammodule */

/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)

/* Total number of C API pointers */
#define PySpam_API_pointers 1


#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else
/* This section is used in modules that use spammodule's API */

static void **PySpam_API;

#define PySpam_System \
 (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* Return -1 on error, 0 on success.
 * PyCapsule_Import will set an exception if there's an error.
 */
static int
import_spam(void)
@{
    PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
    return (PySpam_API != NULL) ? 0 : -1;
@}

#endif

#ifdef __cplusplus
@}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */
@end example

All that a client module must do in order to have access to the function
@code{PySpam_System()} is to call the function (or rather macro)
@code{import_spam()} in its initialization function:

@example
PyMODINIT_FUNC
PyInit_client(void)
@{
    PyObject *m;

    m = PyModule_Create(&clientmodule);
    if (m == NULL)
        return NULL;
    if (import_spam() < 0)
        return NULL;
    /* additional initialization can happen here */
    return m;
@}
@end example

Le principal inconvénient de cette approche est que le fichier @code{spammodule.h} est assez compliqué. Cependant, la structure de base est la même pour chaque fonction exportée, ce qui fait qu'elle ne doit être apprise qu'une seule fois.

Enfin, il convient de mentionner que les Capsules offrent des fonctionnalités supplémentaires, qui sont particulièrement utiles pour l'allocation de la mémoire et la dés-allocation du pointeur stocké dans un objet Capsule. Les détails sont décrits dans le manuel de référence de l'API Python/C dans la section @ref{2501,,Capsules} et dans l'implémentation des Capsules (fichiers @code{Include/pycapsule.h} et @code{Objects/pycapsule.c} dans la distribution du code source Python).

@subsubheading Notes


@node Tutoriel définir des types dans des extensions,Définir les types d'extension divers sujets,Étendre Python en C ou C++,Création d'extensions sans outils tiers
@anchor{extending/newtypes_tutorial doc}@anchor{17b8}@anchor{extending/newtypes_tutorial defining-extension-types-tutorial}@anchor{47e4}@anchor{extending/newtypes_tutorial defining-new-types}@anchor{47e5}
@subsection Tutoriel : définir des types dans des extensions


Python permet à l'auteur d'un module d'extension C de définir de nouveaux types qui peuvent être manipulés depuis du code Python, à la manière des types natifs @ref{435,,str} et @ref{5fc,,list}. Les implémentations de tous les types d'extension ont des similarités, mais quelques subtilités doivent être abordées avant de commencer.

@menu
* Les bases: Les bases<2>. 
* ajout de données et de méthodes à l'exemple basique:: 
* Contrôle précis sur les attributs de données:: 
* Prise en charge du ramasse-miettes cyclique:: 
* Sous-classement d'autres types:: 

@end menu

@node Les bases<2>,ajout de données et de méthodes à l'exemple basique,,Tutoriel définir des types dans des extensions
@anchor{extending/newtypes_tutorial dnt-basics}@anchor{47e6}@anchor{extending/newtypes_tutorial the-basics}@anchor{47e7}
@subsubsection Les bases


@ref{6e0,,CPython} considère que tous les objets Python sont des variables de type @ref{32f,,PyObject}*, qui sert de type de base pour tous les objets Python. La structure de @ref{32f,,PyObject} ne contient que le @ref{47e8,,compteur de références} et un pointeur vers un objet de type « type de l'objet ». C'est ici que tout se joue : l'objet type détermine quelle fonction C doit être appelée par l'interpréteur quand, par exemple, un attribut est recherché sur un objet, quand une méthode est appelée, ou quand l'objet est multiplié par un autre objet. Ces fonctions C sont appelées des « méthodes de type ».

Donc, pour définir un nouveau type dans une extension, vous devez créer un nouvel objet type.

This sort of thing can only be explained by example, so here's a minimal, but
complete, module that defines a new type named @code{Custom} inside a C
extension module @code{custom}:

@cartouche
@quotation Note 
ce qui est montré ici est la manière traditionnelle de définir des types d'extension `statiques', et cela convient dans la majorité des cas. L'API C permet aussi de définir des types alloués sur le tas, via la fonction @ref{569,,PyType_FromSpec()}, mais ce n'est pas couvert par ce tutoriel.
@end quotation
@end cartouche

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

typedef struct @{
    PyObject_HEAD
    /* Type-specific fields go here. */
@} CustomObject;

static PyTypeObject CustomType = @{
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = PyType_GenericNew,
@};

static PyModuleDef custommodule = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
@};

PyMODINIT_FUNC
PyInit_custom(void)
@{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

C'est un peu long, mais vous devez déjà reconnaître quelques morceaux expliqués au chapitre précédent. Ce fichier définit trois choses :


@enumerate 

@item 
What a @code{Custom} `object' contains: this is the @code{CustomObject}
struct, which is allocated once for each @code{Custom} instance.

@item 
How the @code{Custom} `type' behaves: this is the @code{CustomType} struct,
which defines a set of flags and function pointers that the interpreter
inspects when specific operations are requested.

@item 
How to initialize the @code{custom} module: this is the @code{PyInit_custom}
function and the associated @code{custommodule} struct.
@end enumerate

Commençons par :

@example
typedef struct @{
    PyObject_HEAD
@} CustomObject;
@end example

C'est ce qu'un objet @code{Custom} contient. @code{PyObject_HEAD} est obligatoirement au début de chaque structure d'objet et définit un champ appelé @code{ob_base} de type @ref{32f,,PyObject}, contenant un pointeur vers un objet type et un compteur de références (on peut y accéder en utilisant les macros @ref{76a,,Py_TYPE} et @ref{896,,Py_REFCNT}, respectivement). La raison d'être de ces macros est d'abstraire l'agencement de la structure, et ainsi de permettre l'ajout de champs en @ref{1f6,,mode débogage}.

@cartouche
@quotation Note 
il n'y a pas de point-virgule après la macro @ref{12bc,,PyObject_HEAD}. Attention à ne pas l'ajouter par accident : certains compilateurs pourraient s'en plaindre.
@end quotation
@end cartouche

Bien sûr, les objets ajoutent généralement des données supplémentaires après l'entête standard @code{PyObject_HEAD}. Par exemple voici la définition du type standard Python @code{float} :

@example
typedef struct @{
    PyObject_HEAD
    double ob_fval;
@} PyFloatObject;
@end example

La deuxième partie est la définition de l'objet type

@example
static PyTypeObject CustomType = @{
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT,
    .tp_new = PyType_GenericNew,
@};
@end example

@cartouche
@quotation Note 
nous recommandons d'utiliser la syntaxe d'initialisation nommée (C99) pour remplir la structure, comme ci-dessus, afin d'éviter d'avoir à lister les champs de @ref{a93,,PyTypeObject} dont vous n'avez pas besoin, et de ne pas vous soucier de leur ordre.
@end quotation
@end cartouche

La définition de @ref{a93,,PyTypeObject} dans @code{object.h} contient en fait bien plus de @ref{97a,,champs} que la définition ci-dessus. Les champs restants sont mis à zéro par le compilateur C, et c'est une pratique répandue de ne pas spécifier les champs dont vous n'avez pas besoin.

Regardons les champs de cette structure, un par un :

@example
.ob_base = PyVarObject_HEAD_INIT(NULL, 0)
@end example

Cette ligne, obligatoire, initialise le champ @code{ob_base} mentionné précédemment.

@example
.tp_name = "custom.Custom",
@end example

C'est le nom de notre type. Il apparaît dans la représentation textuelle par défaut de nos objets, ainsi que dans quelques messages d'erreur, par exemple :

@example
>>> "" + custom.Custom()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can only concatenate str (not "custom.Custom") to str
@end example

Note that the name is a dotted name that includes both the module name and the
name of the type within the module. The module in this case is @code{custom} and
the type is @code{Custom}, so we set the type name to @code{custom.Custom}.
Using the real dotted import path is important to make your type compatible
with the @ref{b4,,pydoc} and @ref{a5,,pickle} modules.

@example
.tp_basicsize = sizeof(CustomObject),
.tp_itemsize = 0,
@end example

This is so that Python knows how much memory to allocate when creating
new @code{Custom} instances.  @ref{1ef2,,tp_itemsize} is
only used for variable-sized objects and should otherwise be zero.

@cartouche
@quotation Note 
If you want your type to be subclassable from Python, and your type has the same
@ref{974,,tp_basicsize} as its base type, you may have problems with multiple
inheritance.  A Python subclass of your type will have to list your type first
in its @ref{1460,,__bases__}, or else it will not be able to call your type's
@ref{56c,,__new__()} method without getting an error.  You can avoid this problem by
ensuring that your type has a larger value for @ref{974,,tp_basicsize} than its
base type does.  Most of the time, this will be true anyway, because either your
base type will be @ref{a7a,,object}, or else you will be adding data members to
your base type, and therefore increasing its size.
@end quotation
@end cartouche

Nous définissons les drapeaux de la classe à @ref{47e9,,Py_TPFLAGS_DEFAULT} :

@example
.tp_flags = Py_TPFLAGS_DEFAULT,
@end example

Chaque type doit inclure cette constante dans ses options : elle active tous les membres définis jusqu'à au moins Python 3.3. Si vous avez besoin de plus de membres, vous pouvez la combiner à d'autres constantes avec un `OU' binaire.

Nous fournissons une `docstring' pour ce type via le membre @ref{47ea,,tp_doc}.

@example
.tp_doc = PyDoc_STR("Custom objects"),
@end example

To enable object creation, we have to provide a @ref{56b,,tp_new}
handler.  This is the equivalent of the Python method @ref{56c,,__new__()}, but
has to be specified explicitly.  In this case, we can just use the default
implementation provided by the API function @ref{47eb,,PyType_GenericNew()}.

@example
.tp_new = PyType_GenericNew,
@end example

Everything else in the file should be familiar, except for some code in
@code{PyInit_custom()}:

@example
if (PyType_Ready(&CustomType) < 0)
    return;
@end example

This initializes the @code{Custom} type, filling in a number of members
to the appropriate default values, including @ref{47ec,,ob_type} that we initially
set to @code{NULL}.

@example
if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
    Py_DECREF(m);
    return NULL;
@}
@end example

This adds the type to the module dictionary.  This allows us to create
@code{Custom} instances by calling the @code{Custom} class:

@example
>>> import custom
>>> mycustom = custom.Custom()
@end example

That's it!  All that remains is to build it; put the above code in a file called
@code{custom.c},

@example
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "custom"
version = "1"
@end example

in a file called @code{pyproject.toml}, and

@example
from setuptools import Extension, setup
setup(ext_modules=[Extension("custom", ["custom.c"])])
@end example

dans un fichier appelé @code{setup.py} ; puis en tapant

@example
$ python -m pip install .
@end example

in a shell should produce a file @code{custom.so} in a subdirectory
and install it; now fire up Python --- you should be able to @code{import custom}
and play around with @code{Custom} objects.

Ce n'était pas si difficile, n'est-ce pas ?

Bien sûr, le type personnalisé actuel est assez inintéressant. Il n'a pas de données et ne fait rien. Il ne peut même pas être sous-classé.

@node ajout de données et de méthodes à l'exemple basique,Contrôle précis sur les attributs de données,Les bases<2>,Tutoriel définir des types dans des extensions
@anchor{extending/newtypes_tutorial adding-data-and-methods-to-the-basic-example}@anchor{47ed}
@subsubsection ajout de données et de méthodes à l'exemple basique


Let's extend the basic example to add some data and methods.  Let's also make
the type usable as a base class. We'll create a new module, @code{custom2} that
adds these capabilities:

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <stddef.h> /* for offsetof() */

typedef struct @{
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
@} CustomObject;

static void
Custom_dealloc(CustomObject *self)
@{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
@}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
@{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) @{
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
@{
    static char *kwlist[] = @{"first", "last", "number", NULL@};
    PyObject *first = NULL, *last = NULL;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) @{
        Py_XSETREF(self->first, Py_NewRef(first));
    @}
    if (last) @{
        Py_XSETREF(self->last, Py_NewRef(last));
    @}
    return 0;
@}

static PyMemberDef Custom_members[] = @{
    @{"first", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"@},
    @{"last", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"@},
    @{"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
@{
    if (self->first == NULL) @{
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    @}
    if (self->last == NULL) @{
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    @}
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
@}

static PyMethodDef Custom_methods[] = @{
    @{"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    @},
    @{NULL@}  /* Sentinel */
@};

static PyTypeObject CustomType = @{
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom2.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
@};

static PyModuleDef custommodule = @{
    .m_base =PyModuleDef_HEAD_INIT,
    .m_name = "custom2",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
@};

PyMODINIT_FUNC
PyInit_custom2(void)
@{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

Cette version du module comporte un certain nombre de modifications.

The  @code{Custom} type now has three data attributes in its C struct,
`first', `last', and `number'.  The `first' and `last' variables are Python
strings containing first and last names.  The `number' attribute is a C integer.

La structure de l'objet est mise à jour en conséquence

@example
typedef struct @{
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
@} CustomObject;
@end example

Comme nous avons maintenant des données à gérer, nous devons faire plus attention à l'allocation et à la libération d'objets. Au minimum, nous avons besoin d'une méthode de dés-allocation

@example
static void
Custom_dealloc(CustomObject *self)
@{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
@}
@end example

qui est assignée au membre @ref{47ee,,tp_dealloc}

@example
.tp_dealloc = (destructor) Custom_dealloc,
@end example

This method first clears the reference counts of the two Python attributes.
@ref{779,,Py_XDECREF()} correctly handles the case where its argument is
@code{NULL} (which might happen here if @code{tp_new} failed midway).  It then
calls the @ref{47ef,,tp_free} member of the object's type
(computed by @code{Py_TYPE(self)}) to free the object's memory.  Note that
the object's type might not be @code{CustomType}, because the object may
be an instance of a subclass.

@cartouche
@quotation Note 
La conversion explicite en @code{destructor} ci-dessus est nécessaire car nous avons défini @code{Custom_dealloc} pour prendre un argument @code{CustomObject *}, mais le pointeur de fonction @code{tp_dealloc} s'attend à recevoir un argument @code{PyObject *}. Sinon, le compilateur émet un avertissement. C'est du polymorphisme orienté objet, en C !
@end quotation
@end cartouche

Nous voulons nous assurer que le prénom et le nom sont initialisés avec des chaînes vides, nous fournissons donc une implémentation @code{tp_new}

@example
static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
@{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) @{
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}
@end example

et installez-le dans le membre @ref{56b,,tp_new} :

@example
.tp_new = Custom_new,
@end example

The @code{tp_new} handler is responsible for creating (as opposed to initializing)
objects of the type.  It is exposed in Python as the @ref{56c,,__new__()} method.
It is not required to define a @code{tp_new} member, and indeed many extension
types will simply reuse @ref{47eb,,PyType_GenericNew()} as done in the first
version of the @code{Custom} type above.  In this case, we use the @code{tp_new}
handler to initialize the @code{first} and @code{last} attributes to non-@code{NULL}
default values.

@code{tp_new} reçoit le type en cours d'instanciation (pas nécessairement @code{CustomType}, si une sous-classe est instanciée) et tous les arguments passés lorsque le type a été appelé, et devrait renvoyer l'instance créée. Les gestionnaires @code{tp_new} acceptent toujours les arguments positionnels et nommés, mais ils ignorent souvent les arguments, laissant la gestion des arguments aux méthodes d'initialisation (alias @code{tp_init} en C ou @code{__init__} en Python).

@cartouche
@quotation Note 
@code{tp_new} ne doit pas appeler @code{tp_init} explicitement, car l'interpréteur le fera lui-même.
@end quotation
@end cartouche

L'implémentation @code{tp_new} appelle l'emplacement @ref{47f0,,tp_alloc} pour allouer de la mémoire :

@example
self = (CustomObject *) type->tp_alloc(type, 0);
@end example

Puisque l'allocation de mémoire peut échouer, nous devons vérifier le résultat @ref{47f0,,tp_alloc} par rapport à @code{NULL} avant de continuer.

@cartouche
@quotation Note 
Nous n'avons pas rempli l'emplacement @ref{47f0,,tp_alloc} nous-mêmes. C'est @ref{766,,PyType_Ready()} qui le remplit pour nous car il en hérite de notre classe mère, qui est @ref{a7a,,object} par défaut. La plupart des types utilisent la stratégie d'allocation par défaut.
@end quotation
@end cartouche

@cartouche
@quotation Note 
If you are creating a co-operative @ref{56b,,tp_new} (one
that calls a base type's @ref{56b,,tp_new} or @ref{56c,,__new__()}),
you must `not' try to determine what method to call using method resolution
order at runtime.  Always statically determine what type you are going to
call, and call its @ref{56b,,tp_new} directly, or via
@code{type->tp_base->tp_new}.  If you do not do this, Python subclasses of your
type that also inherit from other Python-defined classes may not work correctly.
(Specifically, you may not be able to create instances of such subclasses
without getting a @ref{522,,TypeError}.)
@end quotation
@end cartouche

Nous définissons également une fonction d'initialisation qui accepte des arguments pour fournir des valeurs initiales pour notre instance

@example
static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
@{
    static char *kwlist[] = @{"first", "last", "number", NULL@};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) @{
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_XDECREF(tmp);
    @}
    if (last) @{
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_XDECREF(tmp);
    @}
    return 0;
@}
@end example

en remplissant l'emplacement @ref{56d,,tp_init}.

@example
.tp_init = (initproc) Custom_init,
@end example

The @ref{56d,,tp_init} slot is exposed in Python as the
@ref{69b,,__init__()} method.  It is used to initialize an object after it's
created.  Initializers always accept positional and keyword arguments,
and they should return either @code{0} on success or @code{-1} on error.

Unlike the @code{tp_new} handler, there is no guarantee that @code{tp_init}
is called at all (for example, the @ref{a5,,pickle} module by default
doesn't call @ref{69b,,__init__()} on unpickled instances).  It can also be
called multiple times.  Anyone can call the @code{__init__()} method on
our objects.  For this reason, we have to be extra careful when assigning
the new attribute values.  We might be tempted, for example to assign the
@code{first} member like this:

@example
if (first) @{
    Py_XDECREF(self->first);
    Py_INCREF(first);
    self->first = first;
@}
@end example

Mais ce serait risqué. Notre type ne limite pas le type du membre @code{first}, il peut donc s'agir de n'importe quel type d'objet. Il pourrait avoir un destructeur qui provoque l'exécution de code essayant d'accéder au membre @code{first} ; ou ce destructeur pourrait libérer le @ref{158,,Global interpreter Lock} et laisser du code arbitraire s'exécuter dans d'autres threads qui accèdent et modifient notre objet.

Dans une optique paranoïaque et se prémunir contre cette éventualité, on réaffecte presque toujours les membres avant de décrémenter leur compteur de références. Quand ne devons-nous pas faire cela ?


@itemize *

@item 
lorsque l'on est sûr que le compteur de références est supérieur à 1 ;

@item 
lorsque nous savons que la libération de la mémoire de l'objet @footnote{
C'est vrai lorsque nous savons que l'objet est un type de base, comme une chaîne ou un flottant.
} ne libérera pas le @ref{158,,GIL} ni ne provoquera de rappel dans le code de notre type ;

@item 
lors de la décrémentation d'un compteur de références dans un gestionnaire @ref{47ee,,tp_dealloc} sur un type qui ne prend pas en charge le ramasse-miettes cyclique @footnote{
Nous nous sommes appuyés sur le gestionnaire @ref{47ee,,tp_dealloc} dans cet exemple, car notre type ne prend pas en charge le ramasse-miettes.
}.
@end itemize

Nous voulons exposer nos variables d'instance en tant qu'attributs. Il existe plusieurs façons de le faire. Le moyen le plus simple consiste à définir des définitions de membres :

@example
static PyMemberDef Custom_members[] = @{
    @{"first", Py_T_OBJECT_EX, offsetof(CustomObject, first), 0,
     "first name"@},
    @{"last", Py_T_OBJECT_EX, offsetof(CustomObject, last), 0,
     "last name"@},
    @{"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"@},
    @{NULL@}  /* Sentinel */
@};
@end example

et placer les définitions dans l'emplacement @ref{47f1,,tp_members}

@example
.tp_members = Custom_members,
@end example

Chaque définition de membre possède un nom, un type, un décalage, des indicateurs d'accès et une chaîne de documentation. Voir la section @ref{47f2,,Gestion des attributs génériques} ci-dessous pour plus de détails.

Un inconvénient de cette approche est qu'elle ne permet pas de restreindre les types d'objets pouvant être affectés aux attributs Python. Nous nous attendons à ce que le prénom et le nom soient des chaînes, mais tous les objets Python peuvent être affectés. De plus, les attributs peuvent être supprimés, en définissant les pointeurs C sur @code{NULL}. Même si nous pouvons nous assurer que les membres sont initialisés avec des valeurs non @code{NULL}, les membres peuvent être définis sur @code{NULL} si les attributs sont supprimés.

We define a single method, @code{Custom.name()}, that outputs the objects name as the
concatenation of the first and last names.

@example
static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
@{
    if (self->first == NULL) @{
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    @}
    if (self->last == NULL) @{
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    @}
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
@}
@end example

The method is implemented as a C function that takes a @code{Custom} (or
@code{Custom} subclass) instance as the first argument.  Methods always take an
instance as the first argument. Methods often take positional and keyword
arguments as well, but in this case we don't take any and don't need to accept
a positional argument tuple or keyword argument dictionary. This method is
equivalent to the Python method:

@example
def name(self):
    return "%s %s" % (self.first, self.last)
@end example

Note that we have to check for the possibility that our @code{first} and
@code{last} members are @code{NULL}.  This is because they can be deleted, in which
case they are set to @code{NULL}.  It would be better to prevent deletion of these
attributes and to restrict the attribute values to be strings.  We'll see how to
do that in the next section.

Maintenant que nous avons défini la méthode, nous devons créer un tableau de définitions de méthode

@example
static PyMethodDef Custom_methods[] = @{
    @{"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    @},
    @{NULL@}  /* Sentinel */
@};
@end example

(notez que nous avons utilisé le drapeau @ref{148a,,METH_NOARGS} pour indiquer que la méthode n'attend aucun argument autre que `self')

et assignons-le à l'emplacement @ref{47f3,,tp_methods}

@example
.tp_methods = Custom_methods,
@end example

Enfin, nous rendons notre type utilisable comme classe de base pour le sous-classement. Nous avons écrit nos méthodes avec soin jusqu'à présent afin qu'elles ne fassent aucune hypothèse sur le type de l'objet créé ou utilisé, donc tout ce que nous avons à faire est d'ajouter la macro @ref{47f4,,Py_TPFLAGS_BASETYPE} à notre définition d'indicateur de classe :

@example
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
@end example

We rename @code{PyInit_custom()} to @code{PyInit_custom2()}, update the
module name in the @ref{96a,,PyModuleDef} struct, and update the full class
name in the @ref{a93,,PyTypeObject} struct.

Finally, we update our @code{setup.py} file to include the new module,

@example
from setuptools import Extension, setup
setup(ext_modules=[
    Extension("custom", ["custom.c"]),
    Extension("custom2", ["custom2.c"]),
])
@end example

and then we re-install so that we can @code{import custom2}:

@example
$ python -m pip install .
@end example

@node Contrôle précis sur les attributs de données,Prise en charge du ramasse-miettes cyclique,ajout de données et de méthodes à l'exemple basique,Tutoriel définir des types dans des extensions
@anchor{extending/newtypes_tutorial providing-finer-control-over-data-attributes}@anchor{47f5}
@subsubsection Contrôle précis sur les attributs de données


In this section, we'll provide finer control over how the @code{first} and
@code{last} attributes are set in the @code{Custom} example. In the previous
version of our module, the instance variables @code{first} and @code{last}
could be set to non-string values or even deleted. We want to make sure that
these attributes always contain strings.

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <stddef.h> /* for offsetof() */

typedef struct @{
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
@} CustomObject;

static void
Custom_dealloc(CustomObject *self)
@{
    Py_XDECREF(self->first);
    Py_XDECREF(self->last);
    Py_TYPE(self)->tp_free((PyObject *) self);
@}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
@{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) @{
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
@{
    static char *kwlist[] = @{"first", "last", "number", NULL@};
    PyObject *first = NULL, *last = NULL;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) @{
        Py_SETREF(self->first, Py_NewRef(first));
    @}
    if (last) @{
        Py_SETREF(self->last, Py_NewRef(last));
    @}
    return 0;
@}

static PyMemberDef Custom_members[] = @{
    @{"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
@{
    return Py_NewRef(self->first);
@}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
@{
    if (value == NULL) @{
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    @}
    if (!PyUnicode_Check(value)) @{
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    @}
    Py_SETREF(self->first, Py_NewRef(value));
    return 0;
@}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
@{
    return Py_NewRef(self->last);
@}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
@{
    if (value == NULL) @{
        PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
        return -1;
    @}
    if (!PyUnicode_Check(value)) @{
        PyErr_SetString(PyExc_TypeError,
                        "The last attribute value must be a string");
        return -1;
    @}
    Py_SETREF(self->last, Py_NewRef(value));
    return 0;
@}

static PyGetSetDef Custom_getsetters[] = @{
    @{"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL@},
    @{"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
@{
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
@}

static PyMethodDef Custom_methods[] = @{
    @{"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    @},
    @{NULL@}  /* Sentinel */
@};

static PyTypeObject CustomType = @{
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom3.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
@};

static PyModuleDef custommodule = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom3",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
@};

PyMODINIT_FUNC
PyInit_custom3(void)
@{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

To provide greater control, over the @code{first} and @code{last} attributes,
we'll use custom getter and setter functions.  Here are the functions for
getting and setting the @code{first} attribute:

@example
static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
@{
    Py_INCREF(self->first);
    return self->first;
@}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
@{
    PyObject *tmp;
    if (value == NULL) @{
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    @}
    if (!PyUnicode_Check(value)) @{
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    @}
    tmp = self->first;
    Py_INCREF(value);
    self->first = value;
    Py_DECREF(tmp);
    return 0;
@}
@end example

The getter function is passed a @code{Custom} object and a "closure", which is
a void pointer.  In this case, the closure is ignored.  (The closure supports an
advanced usage in which definition data is passed to the getter and setter. This
could, for example, be used to allow a single set of getter and setter functions
that decide the attribute to get or set based on data in the closure.)

The setter function is passed the @code{Custom} object, the new value, and the
closure.  The new value may be @code{NULL}, in which case the attribute is being
deleted.  In our setter, we raise an error if the attribute is deleted or if its
new value is not a string.

Nous créons un tableau de structures @ref{ba6,,PyGetSetDef}

@example
static PyGetSetDef Custom_getsetters[] = @{
    @{"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL@},
    @{"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL@},
    @{NULL@}  /* Sentinel */
@};
@end example

et l'enregistrons dans l'emplacement @ref{47f6,,tp_getset}

@example
.tp_getset = Custom_getsetters,
@end example

Le dernier élément d'une structure @ref{ba6,,PyGetSetDef} est la fermeture mentionnée ci-dessus. Dans ce cas, nous n'utilisons pas de fermeture, nous passons donc simplement @code{NULL}.

Nous supprimons également les définitions de membre pour ces attributs :

@example
static PyMemberDef Custom_members[] = @{
    @{"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"@},
    @{NULL@}  /* Sentinel */
@};
@end example

Nous devons également mettre à jour le gestionnaire @ref{56d,,tp_init} pour autoriser uniquement le passage des chaînes @footnote{
Nous savons maintenant que les premier et dernier membres sont des chaînes, nous pourrions donc peut-être être moins prudents quant à la décrémentation de leur nombre de références, cependant, nous acceptons les instances de sous-classes de chaînes. Même si la libération de la mémoire des chaînes normales ne rappellera pas nos objets, nous ne pouvons pas garantir que la libération de mémoire d'une instance d'une sous-classe de chaîne ne rappellera pas nos objets.
}

@example
static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
@{
    static char *kwlist[] = @{"first", "last", "number", NULL@};
    PyObject *first = NULL, *last = NULL, *tmp;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) @{
        tmp = self->first;
        Py_INCREF(first);
        self->first = first;
        Py_DECREF(tmp);
    @}
    if (last) @{
        tmp = self->last;
        Py_INCREF(last);
        self->last = last;
        Py_DECREF(tmp);
    @}
    return 0;
@}
@end example

Avec ces modifications, nous pouvons garantir que les membres @code{first} et @code{last} ne sont jamais @code{NULL}, nous pouvons donc supprimer les vérifications des valeurs @code{NULL} dans presque tous les cas. Cela signifie que la plupart des appels @ref{779,,Py_XDECREF()} peuvent être convertis en appels @ref{55b,,Py_DECREF()}. Le seul endroit où nous ne pouvons pas modifier ces appels est dans l'implémentation de @code{tp_dealloc}, où il est possible que l'initialisation de ces membres ait échoué dans @code{tp_new}.

Nous renommons également la fonction d'initialisation du module et le nom du module dans la fonction d'initialisation, comme nous l'avons fait précédemment, et nous ajoutons une définition supplémentaire au fichier @code{setup.py}.

@node Prise en charge du ramasse-miettes cyclique,Sous-classement d'autres types,Contrôle précis sur les attributs de données,Tutoriel définir des types dans des extensions
@anchor{extending/newtypes_tutorial supporting-cyclic-garbage-collection}@anchor{47f7}
@subsubsection Prise en charge du ramasse-miettes cyclique


Python a un @ref{18a7,,ramasse-miettes cyclique} qui peut identifier les objets inutiles même lorsque leur compteur de références n'est pas nul. Cela peut se produire lorsque des objets sont impliqués dans des cycles. Par exemple, considérons :

@example
>>> l = []
>>> l.append(l)
>>> del l
@end example

Dans cet exemple, nous créons une liste qui se contient elle-même. Lorsque nous la supprimons, il existe toujours une référence à elle-même. Son compteur de références ne tombe pas à zéro. Heureusement, le ramasse-miettes cyclique de Python finira par comprendre que la liste est un déchet et la libérera.

In the second version of the @code{Custom} example, we allowed any kind of
object to be stored in the @code{first} or @code{last} attributes @footnote{
De plus, même avec nos attributs limités aux instances de chaînes, l'utilisateur pourrait passer des sous-classes arbitraires @ref{435,,str} et donc encore créer des références cycliques.
}.
Besides, in the second and third versions, we allowed subclassing
@code{Custom}, and subclasses may add arbitrary attributes.  For any of
those two reasons, @code{Custom} objects can participate in cycles:

@example
>>> import custom3
>>> class Derived(custom3.Custom): pass
...
>>> n = Derived()
>>> n.some_attribute = n
@end example

To allow a @code{Custom} instance participating in a reference cycle to
be properly detected and collected by the cyclic GC, our @code{Custom} type
needs to fill two additional slots and to enable a flag that enables these slots:

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
#include <stddef.h> /* for offsetof() */

typedef struct @{
    PyObject_HEAD
    PyObject *first; /* first name */
    PyObject *last;  /* last name */
    int number;
@} CustomObject;

static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
@{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
@}

static int
Custom_clear(CustomObject *self)
@{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
@}

static void
Custom_dealloc(CustomObject *self)
@{
    PyObject_GC_UnTrack(self);
    Custom_clear(self);
    Py_TYPE(self)->tp_free((PyObject *) self);
@}

static PyObject *
Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
@{
    CustomObject *self;
    self = (CustomObject *) type->tp_alloc(type, 0);
    if (self != NULL) @{
        self->first = PyUnicode_FromString("");
        if (self->first == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->last = PyUnicode_FromString("");
        if (self->last == NULL) @{
            Py_DECREF(self);
            return NULL;
        @}
        self->number = 0;
    @}
    return (PyObject *) self;
@}

static int
Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
@{
    static char *kwlist[] = @{"first", "last", "number", NULL@};
    PyObject *first = NULL, *last = NULL;

    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
                                     &first, &last,
                                     &self->number))
        return -1;

    if (first) @{
        Py_SETREF(self->first, Py_NewRef(first));
    @}
    if (last) @{
        Py_SETREF(self->last, Py_NewRef(last));
    @}
    return 0;
@}

static PyMemberDef Custom_members[] = @{
    @{"number", Py_T_INT, offsetof(CustomObject, number), 0,
     "custom number"@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_getfirst(CustomObject *self, void *closure)
@{
    return Py_NewRef(self->first);
@}

static int
Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
@{
    if (value == NULL) @{
        PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
        return -1;
    @}
    if (!PyUnicode_Check(value)) @{
        PyErr_SetString(PyExc_TypeError,
                        "The first attribute value must be a string");
        return -1;
    @}
    Py_XSETREF(self->first, Py_NewRef(value));
    return 0;
@}

static PyObject *
Custom_getlast(CustomObject *self, void *closure)
@{
    return Py_NewRef(self->last);
@}

static int
Custom_setlast(CustomObject *self, PyObject *value, void *closure)
@{
    if (value == NULL) @{
        PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
        return -1;
    @}
    if (!PyUnicode_Check(value)) @{
        PyErr_SetString(PyExc_TypeError,
                        "The last attribute value must be a string");
        return -1;
    @}
    Py_XSETREF(self->last, Py_NewRef(value));
    return 0;
@}

static PyGetSetDef Custom_getsetters[] = @{
    @{"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
     "first name", NULL@},
    @{"last", (getter) Custom_getlast, (setter) Custom_setlast,
     "last name", NULL@},
    @{NULL@}  /* Sentinel */
@};

static PyObject *
Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
@{
    return PyUnicode_FromFormat("%S %S", self->first, self->last);
@}

static PyMethodDef Custom_methods[] = @{
    @{"name", (PyCFunction) Custom_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    @},
    @{NULL@}  /* Sentinel */
@};

static PyTypeObject CustomType = @{
    .ob_base = PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "custom4.Custom",
    .tp_doc = PyDoc_STR("Custom objects"),
    .tp_basicsize = sizeof(CustomObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
    .tp_new = Custom_new,
    .tp_init = (initproc) Custom_init,
    .tp_dealloc = (destructor) Custom_dealloc,
    .tp_traverse = (traverseproc) Custom_traverse,
    .tp_clear = (inquiry) Custom_clear,
    .tp_members = Custom_members,
    .tp_methods = Custom_methods,
    .tp_getset = Custom_getsetters,
@};

static PyModuleDef custommodule = @{
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "custom4",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
@};

PyMODINIT_FUNC
PyInit_custom4(void)
@{
    PyObject *m;
    if (PyType_Ready(&CustomType) < 0)
        return NULL;

    m = PyModule_Create(&custommodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

Tout d'abord, la méthode de parcours (`Custom_traverse') permet au ramasse-miettes cyclique de connaître les sous-objets qui pourraient conduire à des cycles

@example
static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
@{
    int vret;
    if (self->first) @{
        vret = visit(self->first, arg);
        if (vret != 0)
            return vret;
    @}
    if (self->last) @{
        vret = visit(self->last, arg);
        if (vret != 0)
            return vret;
    @}
    return 0;
@}
@end example

For each subobject that can participate in cycles, we need to call the
@code{visit()} function, which is passed to the traversal method. The
@code{visit()} function takes as arguments the subobject and the extra argument
`arg' passed to the traversal method.  It returns an integer value that must be
returned if it is non-zero.

Python fournit une macro @ref{47f8,,Py_VISIT()} qui automatise l'appel des fonctions de visite. Avec @ref{47f8,,Py_VISIT()}, nous pouvons minimiser la quantité de code générique dans @code{Custom_traverse}

@example
static int
Custom_traverse(CustomObject *self, visitproc visit, void *arg)
@{
    Py_VISIT(self->first);
    Py_VISIT(self->last);
    return 0;
@}
@end example

@cartouche
@quotation Note 
l'implémentation @ref{768,,tp_traverse} doit nommer ses arguments exactement `visit' et `arg' afin d'utiliser @ref{47f8,,Py_VISIT()}.
@end quotation
@end cartouche

Deuxièmement, nous devons fournir une méthode pour effacer tous les sous-objets qui peuvent conduire à des cycles

@example
static int
Custom_clear(CustomObject *self)
@{
    Py_CLEAR(self->first);
    Py_CLEAR(self->last);
    return 0;
@}
@end example

Notez l'utilisation de la macro @ref{564,,Py_CLEAR()}. C'est le moyen recommandé et sûr d'effacer les attributs de données de types arbitraires tout en décrémentant leur compteur de références. Si vous deviez appeler @ref{779,,Py_XDECREF()} à la place sur l'attribut avant de le définir sur @code{NULL}, il est possible que le destructeur de l'attribut appelle du code qui lit à nouveau l'attribut (`surtout' s'il existe un cycle de références).

@cartouche
@quotation Note 
vous pouvez émuler @ref{564,,Py_CLEAR()} en écrivant

@example
PyObject *tmp;
tmp = self->first;
self->first = NULL;
Py_XDECREF(tmp);
@end example

Néanmoins, il est beaucoup plus facile et moins sujet aux erreurs de toujours utiliser @ref{564,,Py_CLEAR()} lors de la suppression d'un attribut. N'essayez pas de micro-optimiser au détriment de la robustesse !
@end quotation
@end cartouche

La fonction de libération de la mémoire @code{Custom_dealloc} peut appeler du code arbitraire lors de la suppression des attributs. Cela signifie que le ramasse-miettes cyclique peut être déclenché à l'intérieur de la fonction. Étant donné que le ramasse-miettes suppose que le nombre de références n'est pas nul, nous devons annuler le suivi de l'objet par le ramasse-miettes en appelant @ref{14bd,,PyObject_GC_UnTrack()} avant d'effacer les membres. Voici notre fonction de libération de la mémoire réimplémentée en utilisant @ref{14bd,,PyObject_GC_UnTrack()} et @code{Custom_clear} :

@example
static void
Custom_dealloc(CustomObject *self)
@{
    PyObject_GC_UnTrack(self);
    Custom_clear(self);
    Py_TYPE(self)->tp_free((PyObject *) self);
@}
@end example

Enfin, nous ajoutons le drapeau @ref{767,,Py_TPFLAGS_HAVE_GC} aux drapeaux de la classe :

@example
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@end example

C'est à peu près tout. Si nous avions écrit des gestionnaires personnalisés @ref{47f0,,tp_alloc} ou @ref{47ef,,tp_free}, nous aurions besoin de les modifier pour le ramasse-miettes cyclique. La plupart des extensions utilisent les versions fournies automatiquement.

@node Sous-classement d'autres types,,Prise en charge du ramasse-miettes cyclique,Tutoriel définir des types dans des extensions
@anchor{extending/newtypes_tutorial subclassing-other-types}@anchor{47f9}
@subsubsection Sous-classement d'autres types


Il est possible de créer de nouveaux types d'extension dérivés de types existants. Il est plus facile d'hériter des types natifs, car une extension peut facilement utiliser le @ref{a93,,PyTypeObject} dont elle a besoin. Il peut être difficile de partager ces structures @ref{a93,,PyTypeObject} entre modules d'extension.

In this example we will create a @code{SubList} type that inherits from the
built-in @ref{5fc,,list} type. The new type will be completely compatible with
regular lists, but will have an additional @code{increment()} method that
increases an internal counter:

@example
>>> import sublist
>>> s = sublist.SubList(range(3))
>>> s.extend(s)
>>> print(len(s))
6
>>> print(s.increment())
1
>>> print(s.increment())
2
@end example

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

typedef struct @{
    PyListObject list;
    int state;
@} SubListObject;

static PyObject *
SubList_increment(SubListObject *self, PyObject *unused)
@{
    self->state++;
    return PyLong_FromLong(self->state);
@}

static PyMethodDef SubList_methods[] = @{
    @{"increment", (PyCFunction) SubList_increment, METH_NOARGS,
     PyDoc_STR("increment state counter")@},
    @{NULL@},
@};

static int
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
@{
    if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
@}

static PyTypeObject SubListType = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "sublist.SubList",
    .tp_doc = PyDoc_STR("SubList objects"),
    .tp_basicsize = sizeof(SubListObject),
    .tp_itemsize = 0,
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
    .tp_init = (initproc) SubList_init,
    .tp_methods = SubList_methods,
@};

static PyModuleDef sublistmodule = @{
    PyModuleDef_HEAD_INIT,
    .m_name = "sublist",
    .m_doc = "Example module that creates an extension type.",
    .m_size = -1,
@};

PyMODINIT_FUNC
PyInit_sublist(void)
@{
    PyObject *m;
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0)
        return NULL;

    m = PyModule_Create(&sublistmodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "SubList", (PyObject *) &SubListType) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

As you can see, the source code closely resembles the @code{Custom} examples in
previous sections. We will break down the main differences between them.

@example
typedef struct @{
    PyListObject list;
    int state;
@} SubListObject;
@end example

La principale différence pour les objets d'un type dérivé est que la structure d'objet du type père doit être la première valeur. Le type père inclut déjà le @ref{12bc,,PyObject_HEAD()} au début de sa structure.

When a Python object is a @code{SubList} instance, its @code{PyObject *} pointer
can be safely cast to both @code{PyListObject *} and @code{SubListObject *}:

@example
static int
SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
@{
    if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
        return -1;
    self->state = 0;
    return 0;
@}
@end example

We see above how to call through to the @ref{69b,,__init__()} method of the base
type.

Ce modèle est important lors de l'écriture d'un type avec des membres personnalisés @ref{56b,,tp_new} et @ref{47ee,,tp_dealloc}. Le gestionnaire @ref{56b,,tp_new} ne doit pas réellement allouer la mémoire pour l'objet avec son @ref{47f0,,tp_alloc}, mais laisser la classe mère gérer ça en appelant sa propre @ref{56b,,tp_new}.

La structure @ref{a93,,PyTypeObject} prend en charge un @ref{47fa,,tp_base} spécifiant la classe mère concrète du type. En raison de problèmes de compilateur multiplateformes, vous ne pouvez pas remplir ce champ directement avec une référence à @ref{47fb,,PyList_Type} ; cela doit être fait plus tard dans la fonction d'initialisation du module :

@example
PyMODINIT_FUNC
PyInit_sublist(void)
@{
    PyObject* m;
    SubListType.tp_base = &PyList_Type;
    if (PyType_Ready(&SubListType) < 0)
        return NULL;

    m = PyModule_Create(&sublistmodule);
    if (m == NULL)
        return NULL;

    if (PyModule_AddObjectRef(m, "SubList", (PyObject *) &SubListType) < 0) @{
        Py_DECREF(m);
        return NULL;
    @}

    return m;
@}
@end example

Avant d'appeler @ref{766,,PyType_Ready()}, la structure de type doit avoir l'emplacement @ref{47fa,,tp_base} rempli. Lorsque nous dérivons un type existant, il n'est pas nécessaire de remplir l'emplacement @ref{47f0,,tp_alloc} avec @ref{47eb,,PyType_GenericNew()} – la fonction d'allocation du type père sera héritée.

After that, calling @ref{766,,PyType_Ready()} and adding the type object to the
module is the same as with the basic @code{Custom} examples.

@subsubheading Notes


@node Définir les types d'extension divers sujets,Construire des extensions C et C++,Tutoriel définir des types dans des extensions,Création d'extensions sans outils tiers
@anchor{extending/newtypes doc}@anchor{47fc}@anchor{extending/newtypes defining-extension-types-assorted-topics}@anchor{47fd}@anchor{extending/newtypes new-types-topics}@anchor{47fe}
@subsection Définir les types d'extension : divers sujets

@anchor{extending/newtypes dnt-type-methods}@anchor{47ff}
Cette section vise à donner un aperçu rapide des différentes méthodes de type que vous pouvez implémenter et de ce qu'elles font.

Voici la définition de @ref{a93,,PyTypeObject}, après avoir enlevé certains champs utilisés uniquement dans @ref{1f6,,debug builds} :

@example
typedef struct _typeobject @{
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;
@} PyTypeObject;
@end example

Cela fait `beaucoup' de méthodes. Ne vous inquiétez pas trop cependant : si vous souhaitez définir un type, il y a de fortes chances que vous n'implémentiez qu'une petite partie d'entre elles.

Comme vous vous en doutez probablement maintenant, nous allons passer en revue cela et donner plus d'informations sur les différents gestionnaires. Nous ne suivrons pas l'ordre dans lequel ils sont définis dans la structure, car l'ordre des champs résulte d'un certain historique. Il est souvent plus facile de trouver un exemple qui inclut les champs dont vous avez besoin, puis de modifier les valeurs en fonction de votre nouveau type :

@example
const char *tp_name; /* For printing */
@end example

Le nom du type – comme mentionné dans le chapitre précédent, cela apparaîtra à divers endroits, presque entièrement à des fins de diagnostic. Essayez de choisir quelque chose qui sera utile dans une telle situation !

@example
Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */
@end example

Ces champs indiquent la quantité de mémoire à allouer à l'exécution lorsque de nouveaux objets de ce type sont créés. Python prend en charge nativement des structures de longueur variable (pensez : chaînes, `n'-uplets), c'est là que le champ @ref{1ef2,,tp_itemsize} entre en jeu. Cela sera traité plus tard.

@example
const char *tp_doc;
@end example

Ici vous pouvez mettre une chaîne (ou son adresse) que vous voulez renvoyer lorsque le script Python référence @code{obj.__doc__} pour récupérer le `docstring'.

Nous en arrivons maintenant aux méthodes de type basiques -- celles que la plupart des types d'extension mettront en œuvre.

@menu
* Finalisation et libération de mémoire:: 
* Présentation de l'objet:: 
* Gestion des attributs:: 
* Comparaison des objets:: 
* Gestion de protocoles abstraits:: 
* Prise en charge de la référence faible:: 
* Plus de suggestions:: 

@end menu

@node Finalisation et libération de mémoire,Présentation de l'objet,,Définir les types d'extension divers sujets
@anchor{extending/newtypes finalization-and-de-allocation}@anchor{4800}
@subsubsection Finalisation et libération de mémoire


@geindex object;deallocation
@geindex deallocation@comma{} object
@geindex object;finalization
@geindex finalization@comma{} of objects

@example
destructor tp_dealloc;
@end example

Cette fonction est appelée lorsque le compteur de références de l'instance de votre type tombe à zéro et que l'interpréteur Python veut récupérer la mémoire afférente. Si votre type a de la mémoire à libérer ou un autre nettoyage à effectuer, vous pouvez le mettre ici. L'objet lui-même doit être libéré ici aussi. Voici un exemple de cette fonction :

@example
static void
newdatatype_dealloc(newdatatypeobject *obj)
@{
    free(obj->obj_UnderlyingDatatypePtr);
    Py_TYPE(obj)->tp_free((PyObject *)obj);
@}
@end example

Si votre type prend en charge le ramasse-miettes, le destructeur doit appeler @ref{14bd,,PyObject_GC_UnTrack()} avant d'effacer les champs membres :

@example
static void
newdatatype_dealloc(newdatatypeobject *obj)
@{
    PyObject_GC_UnTrack(obj);
    Py_CLEAR(obj->other_obj);
    ...
    Py_TYPE(obj)->tp_free((PyObject *)obj);
@}
@end example

@geindex PyErr_Fetch (C function)
@geindex PyErr_Restore (C function)

Une exigence importante de la fonction de libération de la mémoire est de ne pas s'occuper de toutes les exceptions en attente. C'est important car les fonctions de libération de la mémoire sont fréquemment appelées lorsque l'interpréteur remonte la pile d'appels Python ; lorsque la pile est remontée à cause d'une exception (plutôt que de retours normaux), les fonctions de libération peuvent voir qu'une exception a déjà été définie. Toute action effectuée par une fonction de libération de la mémoire pouvant entraîner l'exécution de code Python supplémentaire peut détecter qu'une exception a été définie. Cela peut conduire l’interpréteur à se tromper sur la nature de l'erreur. La bonne façon d'éviter cela est d'enregistrer une exception en attente avant d'effectuer l'action non sécurisée et à la restaurer une fois terminée. Cela peut être fait en utilisant les fonctions @ref{3e9,,PyErr_Fetch()} et @ref{3ec,,PyErr_Restore()} :

@example
static void
my_dealloc(PyObject *obj)
@{
    MyObject *self = (MyObject *) obj;
    PyObject *cbresult;

    if (self->my_callback != NULL) @{
        PyObject *err_type, *err_value, *err_traceback;

        /* This saves the current exception state */
        PyErr_Fetch(&err_type, &err_value, &err_traceback);

        cbresult = PyObject_CallNoArgs(self->my_callback);
        if (cbresult == NULL)
            PyErr_WriteUnraisable(self->my_callback);
        else
            Py_DECREF(cbresult);

        /* This restores the saved exception state */
        PyErr_Restore(err_type, err_value, err_traceback);

        Py_DECREF(self->my_callback);
    @}
    Py_TYPE(obj)->tp_free((PyObject*)self);
@}
@end example

@cartouche
@quotation Note 
des limites existent à ce que vous pouvez faire en toute sécurité dans une fonction de libération de la mémoire. Tout d'abord, si votre type prend en charge le ramasse-miettes (en utilisant @ref{768,,tp_traverse} et/ou @ref{4801,,tp_clear}), certains membres de l'objet peuvent avoir été effacés ou finalisés avant que @ref{47ee,,tp_dealloc} ne soit appelé. Deuxièmement, dans @ref{47ee,,tp_dealloc}, votre objet est dans un état instable : son compteur de références est égal à zéro. Tout appel à un objet non trivial ou à une API (comme dans l'exemple ci-dessus) peut finir par appeler @ref{47ee,,tp_dealloc} à nouveau, provoquant une double libération et un plantage.

À partir de Python 3.4, il est recommandé de ne pas mettre de code de finalisation complexe dans @ref{47ee,,tp_dealloc}, et d'utiliser à la place la nouvelle méthode de type @ref{a94,,tp_finalize}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/} explique le nouveau schéma de finalisation.

@end quotation
@end cartouche

@geindex string;object representation
@geindex built-in function;repr

@node Présentation de l'objet,Gestion des attributs,Finalisation et libération de mémoire,Définir les types d'extension divers sujets
@anchor{extending/newtypes object-presentation}@anchor{4802}
@subsubsection Présentation de l'objet


En Python, il existe deux façons de générer une représentation textuelle d'un objet : la fonction @ref{7e7,,repr()} et la fonction @ref{435,,str()} (la fonction @ref{f60,,print()} appelle simplement @ref{435,,str()}). Ces gestionnaires sont tous deux facultatifs.

@example
reprfunc tp_repr;
reprfunc tp_str;
@end example

Le gestionnaire @ref{4803,,tp_repr} doit renvoyer un objet chaîne contenant une représentation de l'instance pour laquelle il est appelé. Voici un exemple simple :

@example
static PyObject *
newdatatype_repr(newdatatypeobject *obj)
@{
    return PyUnicode_FromFormat("Repr-ified_newdatatype@{@{size:%d@}@}",
                                obj->obj_UnderlyingDatatypePtr->size);
@}
@end example

Si aucun gestionnaire @ref{4803,,tp_repr} n'est spécifié, l'interpréteur fournira une représentation qui utilise le type @ref{1880,,tp_name} et une valeur d'identification unique pour l'objet.

Le gestionnaire @ref{4804,,tp_str} est à @ref{435,,str()} ce que le gestionnaire @ref{4803,,tp_repr} décrit ci-dessus est à @ref{7e7,,repr()} ; c'est-à-dire qu'il est appelé lorsque le code Python appelle @ref{435,,str()} sur une instance de votre objet. Son implémentation est très similaire à la fonction @ref{4803,,tp_repr}, mais la chaîne résultante est destinée à être lue par des utilisateurs. Si @ref{4804,,tp_str} n'est pas spécifié, le gestionnaire @ref{4803,,tp_repr} est utilisé à la place.

Voici un exemple simple :

@example
static PyObject *
newdatatype_str(newdatatypeobject *obj)
@{
    return PyUnicode_FromFormat("Stringified_newdatatype@{@{size:%d@}@}",
                                obj->obj_UnderlyingDatatypePtr->size);
@}
@end example

@node Gestion des attributs,Comparaison des objets,Présentation de l'objet,Définir les types d'extension divers sujets
@anchor{extending/newtypes attribute-management}@anchor{4805}
@subsubsection Gestion des attributs


Pour chaque objet pouvant prendre en charge des attributs, le type correspondant doit fournir les fonctions qui contrôlent la façon dont les attributs sont résolus. Il doit y avoir une fonction qui peut récupérer les attributs (le cas échéant) et une autre pour définir les attributs (si la définition des attributs est autorisée). La suppression d'un attribut est un cas particulier, pour lequel la nouvelle valeur transmise au gestionnaire est @code{NULL}.

Python prend en charge deux paires de gestionnaires d'attributs ; un type qui prend en charge les attributs n'a besoin d'implémenter les fonctions que pour une paire. La différence est qu'une paire prend le nom de l'attribut en tant que char*, tandis que l'autre accepte un @ref{32f,,PyObject}*. Chaque type peut utiliser la paire la plus logique pour la commodité de l'implémentation.

@example
getattrfunc  tp_getattr;        /* char * version */
setattrfunc  tp_setattr;
/* ... */
getattrofunc tp_getattro;       /* PyObject * version */
setattrofunc tp_setattro;
@end example

Si accéder aux attributs d'un objet est toujours une opération simple (ceci sera expliqué brièvement), il existe des implémentations génériques qui peuvent être utilisées pour fournir la version @ref{32f,,PyObject}* des fonctions de gestion des attributs. Le besoin réel de gestionnaires d'attributs spécifiques au type a presque complètement disparu à partir de Python 2.2, bien qu'il existe de nombreux exemples qui n'ont pas été mis à jour pour utiliser certains des nouveaux mécanismes génériques disponibles.

@menu
* Gestion des attributs génériques:: 
* Gestion des attributs de type spécifiques:: 

@end menu

@node Gestion des attributs génériques,Gestion des attributs de type spécifiques,,Gestion des attributs
@anchor{extending/newtypes generic-attribute-management}@anchor{47f2}@anchor{extending/newtypes id1}@anchor{4806}
@subsubsection Gestion des attributs génériques


La plupart des types d'extensions n'utilisent que des attributs `simples'. Alors, qu'est-ce qui rend les attributs simples ? Seules quelques conditions doivent être remplies :


@enumerate 

@item 
le nom des attributs doit être déjà connu lorsqu'on lance @ref{766,,PyType_Ready()} ;

@item 
aucun traitement spécial n'est nécessaire pour enregistrer qu'un attribut a été recherché ou défini, et aucune action ne doit être entreprise en fonction de la valeur.
@end enumerate

Notez que cette liste n'impose aucune restriction sur les valeurs des attributs, le moment où les valeurs sont calculées ou la manière dont les données pertinentes sont stockées.

Lorsque @ref{766,,PyType_Ready()} est appelé, il utilise trois tableaux référencés par l'objet type pour créer des @ref{1ef3,,descripteurs} qui sont placés dans le dictionnaire de l'objet type. Chaque descripteur contrôle l'accès à un attribut de l'objet instance. Chacun des tableaux est facultatif ; si les trois sont @code{NULL}, les instances du type n'auront que des attributs hérités de leur type de base et doivent laisser les champs @ref{167b,,tp_getattro} et @ref{4807,,tp_setattro} à @code{NULL} également, permettant au type de base de gérer les attributs.

Les tableaux sont déclarés sous la forme de trois champs de type objet :

@example
struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;
@end example

Si @ref{47f3,,tp_methods} n'est pas @code{NULL}, il doit faire référence à un tableau de structures @ref{148d,,PyMethodDef}. Chaque entrée du tableau est une instance de cette structure :

@example
typedef struct PyMethodDef @{
    const char  *ml_name;       /* method name */
    PyCFunction  ml_meth;       /* implementation function */
    int          ml_flags;      /* flags */
    const char  *ml_doc;        /* docstring */
@} PyMethodDef;
@end example

One entry should be defined for each method provided by the type; no entries are
needed for methods inherited from a base type.  One additional entry is needed
at the end; it is a sentinel that marks the end of the array.  The
@ref{4808,,ml_name} field of the sentinel must be @code{NULL}.

Le deuxième tableau est utilisé pour définir les attributs qui correspondent directement aux données stockées dans l'instance. Divers types C natifs sont pris en charge et l'accès peut être en lecture seule ou en lecture-écriture. Les structures du tableau sont définies comme suit :

@example
typedef struct PyMemberDef @{
    const char *name;
    int         type;
    int         offset;
    int         flags;
    const char *doc;
@} PyMemberDef;
@end example

For each entry in the table, a @ref{1ef3,,descriptor} will be constructed and added to the
type which will be able to extract a value from the instance structure.  The
@ref{4809,,type} field should contain a type code like @ref{57b,,Py_T_INT} or
@ref{57c,,Py_T_DOUBLE}; the value will be used to determine how to
convert Python values to and from C values.  The @ref{480a,,flags} field is used to
store flags which control how the attribute can be accessed: you can set it to
@ref{57d,,Py_READONLY} to prevent Python code from setting it.

An interesting advantage of using the @ref{47f1,,tp_members} table to build
descriptors that are used at runtime is that any attribute defined this way can
have an associated doc string simply by providing the text in the table.  An
application can use the introspection API to retrieve the descriptor from the
class object, and get the doc string using its @ref{1c3a,,__doc__} attribute.

As with the @ref{47f3,,tp_methods} table, a sentinel entry with a @ref{4808,,ml_name} value
of @code{NULL} is required.

@c XXX Descriptors need to be explained in more detail somewhere, but not here.
@c 
@c Descriptor objects have two handler functions which correspond to the
@c \member{tp_getattro} and \member{tp_setattro} handlers.  The
@c \method{__get__()} handler is a function which is passed the descriptor,
@c instance, and type objects, and returns the value of the attribute, or it
@c returns \NULL{} and sets an exception.  The \method{__set__()} handler is
@c passed the descriptor, instance, type, and new value;

@node Gestion des attributs de type spécifiques,,Gestion des attributs génériques,Gestion des attributs
@anchor{extending/newtypes type-specific-attribute-management}@anchor{480b}
@subsubsection Gestion des attributs de type spécifiques


Pour plus de simplicité, seule la version char* est montrée ici ; le type du paramètre `name' est la seule différence entre les variations char* et @ref{32f,,PyObject}* de l'interface. Cet exemple fait effectivement la même chose que l'exemple générique ci-dessus, mais n'utilise pas le support générique ajouté dans Python 2.2. Il explique comment les fonctions de gestionnaire sont appelées, de sorte que si vous avez besoin d'étendre leurs fonctionnalités, vous comprendrez ce qui doit être fait.

The @ref{480c,,tp_getattr} handler is called when the object requires an attribute
look-up.  It is called in the same situations where the @ref{4bc,,__getattr__()}
method of a class would be called.

Voici un exemple :

@example
static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
@{
    if (strcmp(name, "data") == 0)
    @{
        return PyLong_FromLong(obj->data);
    @}

    PyErr_Format(PyExc_AttributeError,
                 "'%.100s' object has no attribute '%.400s'",
                 Py_TYPE(obj)->tp_name, name);
    return NULL;
@}
@end example

The @ref{480d,,tp_setattr} handler is called when the @ref{1eb2,,__setattr__()} or
@ref{1eb3,,__delattr__()} method of a class instance would be called.  When an
attribute should be deleted, the third parameter will be @code{NULL}.  Here is an
example that simply raises an exception; if this were really all you wanted, the
@ref{480d,,tp_setattr} handler should be set to @code{NULL}.

@example
static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
@{
    PyErr_Format(PyExc_RuntimeError, "Read-only attribute: %s", name);
    return -1;
@}
@end example

@node Comparaison des objets,Gestion de protocoles abstraits,Gestion des attributs,Définir les types d'extension divers sujets
@anchor{extending/newtypes object-comparison}@anchor{480e}
@subsubsection Comparaison des objets


@example
richcmpfunc tp_richcompare;
@end example

The @ref{480f,,tp_richcompare} handler is called when comparisons are needed.  It is
analogous to the @ref{1ee4,,rich comparison methods}, like
@code{__lt__()}, and also called by @ref{4810,,PyObject_RichCompare()} and
@ref{1931,,PyObject_RichCompareBool()}.

Cette fonction est appelée avec deux objets Python et l'opérateur comme arguments, où l'opérateur est @code{Py_EQ}, @code{Py_NE}, @code{Py_LE}, @code{Py_GE}, @code{Py_LT} ou @code{Py_GT}. Elle doit comparer les deux objets conformément à l'opérateur spécifié et renvoyer @code{Py_True} ou @code{Py_False} si la comparaison a réussi, @code{Py_NotImplemented} pour indiquer que la comparaison n'est pas implémentée et que la méthode de comparaison de l'autre objet doit être essayée, ou @code{NULL} si une exception doit être levée.

Voici un exemple d'implémentation, pour un type de données où l'égalité signifie que la taille d'un pointeur interne est égale :

@example
static PyObject *
newdatatype_richcmp(newdatatypeobject *obj1, newdatatypeobject *obj2, int op)
@{
    PyObject *result;
    int c, size1, size2;

    /* code to make sure that both arguments are of type
       newdatatype omitted */

    size1 = obj1->obj_UnderlyingDatatypePtr->size;
    size2 = obj2->obj_UnderlyingDatatypePtr->size;

    switch (op) @{
    case Py_LT: c = size1 <  size2; break;
    case Py_LE: c = size1 <= size2; break;
    case Py_EQ: c = size1 == size2; break;
    case Py_NE: c = size1 != size2; break;
    case Py_GT: c = size1 >  size2; break;
    case Py_GE: c = size1 >= size2; break;
    @}
    result = c ? Py_True : Py_False;
    Py_INCREF(result);
    return result;
 @}
@end example

@node Gestion de protocoles abstraits,Prise en charge de la référence faible,Comparaison des objets,Définir les types d'extension divers sujets
@anchor{extending/newtypes abstract-protocol-support}@anchor{4811}
@subsubsection Gestion de protocoles abstraits


Python prend en charge divers « protocoles » `abstraits' ; les interfaces spécifiques fournies pour utiliser ces interfaces sont documentées dans @ref{4812,,Couche d'abstraction des objets}.

Un certain nombre de ces interfaces abstraites ont été définies au début du développement de l'implémentation Python. En particulier, les protocoles de nombre, de correspondance et de séquence font partie de Python depuis le début. D'autres protocoles ont été ajoutés au fil du temps. Pour les protocoles qui dépendent de plusieurs routines de gestionnaire de l'implémentation du type, les anciens protocoles ont été définis comme des blocs facultatifs de gestionnaires référencés par l'objet type. Pour les protocoles plus récents, il existe des emplacements supplémentaires dans l'objet de type principal, avec un bit d'indicateur défini pour indiquer que les emplacements sont présents et doivent être vérifiés par l'interpréteur (le bit d'indicateur n'indique pas que les valeurs d'emplacement ne sont pas @code{NULL} ; il peut être défini pour indiquer la présence d'un emplacement, mais un emplacement peut toujours être vide). :

@example
PyNumberMethods   *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods  *tp_as_mapping;
@end example

Si vous souhaitez que votre objet puisse agir comme un nombre, une séquence ou un tableau de correspondances, placez l'adresse d'une structure qui implémente le type C @ref{13d4,,PyNumberMethods}, @ref{4813,,PySequenceMethods} ou @ref{4814,,PyMappingMethods}, respectivement. C'est à vous de remplir cette structure avec les valeurs appropriées. Vous pouvez trouver des exemples d'utilisation de chacun d'entre eux dans le répertoire @code{Objects} de la distribution source de Python. :

@example
hashfunc tp_hash;
@end example

Cette fonction, si vous la fournissez, doit renvoyer un condensat pour une instance de votre type de données. Voici un exemple simple :

@example
static Py_hash_t
newdatatype_hash(newdatatypeobject *obj)
@{
    Py_hash_t result;
    result = obj->some_size + 32767 * obj->some_number;
    if (result == -1)
       result = -2;
    return result;
@}
@end example

@ref{1242,,Py_hash_t} is a signed integer type with a platform-varying width.
Returning @code{-1} from @ref{4815,,tp_hash} indicates an error,
which is why you should be careful to avoid returning it when hash computation
is successful, as seen above.

@example
ternaryfunc tp_call;
@end example

Cette fonction est appelée lorsqu'une instance de votre type de données est « appelée », par exemple, si @code{obj1} est une instance de votre type de données et que le script Python contient @code{obj1('hello')}, le gestionnaire @ref{544,,tp_call} est appelé.

Cette fonction prend trois arguments :


@enumerate 

@item 
`self' est l'instance du type de données qui fait l'objet de l'appel. Si l'appel est @code{obj1('hello')}, alors `self' est @code{obj1}.

@item 
`args' est un `n'-uplet contenant les arguments de l'appel. Vous pouvez utiliser @ref{55d,,PyArg_ParseTuple()} pour extraire les arguments.

@item 
`kwds' est le dictionnaire d'arguments nommés qui ont été passés. Si ce n'est pas @code{NULL} et que vous gérez les arguments nommés, utilisez @ref{379,,PyArg_ParseTupleAndKeywords()} pour extraire les arguments. Si vous ne souhaitez pas prendre en charge les arguments nommés et qu'il n'est pas @code{NULL}, levez une @ref{522,,TypeError} avec un message indiquant que les arguments nommés ne sont pas pris en charge.
@end enumerate

Ceci est une implémentation @code{tp_call} très simple :

@example
static PyObject *
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *kwds)
@{
    PyObject *result;
    const char *arg1;
    const char *arg2;
    const char *arg3;

    if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) @{
        return NULL;
    @}
    result = PyUnicode_FromFormat(
        "Returning -- value: [%d] arg1: [%s] arg2: [%s] arg3: [%s]\n",
        obj->obj_UnderlyingDatatypePtr->size,
        arg1, arg2, arg3);
    return result;
@}
@end example

@example
/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;
@end example

These functions provide support for the iterator protocol.  Both handlers
take exactly one parameter, the instance for which they are being called,
and return a new reference.  In the case of an error, they should set an
exception and return @code{NULL}.  @ref{14a4,,tp_iter} corresponds
to the Python @ref{1ede,,__iter__()} method, while @ref{14a5,,tp_iternext}
corresponds to the Python @ref{12ab,,__next__()} method.

Tout objet @ref{1205,,iterable} doit implémenter le gestionnaire @ref{14a4,,tp_iter}, qui doit renvoyer un objet de type @ref{1aa,,iterator}.  Ici, les mêmes directives s'appliquent de la même façon que pour les classes `Python' :


@itemize *

@item 
Pour les collections (telles que les listes et les n-uplets) qui peuvent implémenter plusieurs itérateurs indépendants, un nouvel itérateur doit être créé et renvoyé par chaque appel de type @ref{14a4,,tp_iter}.

@item 
Les objets qui ne peuvent être itérés qu'une seule fois (généralement en raison d'effets de bord de l'itération, tels que les objets fichiers) peuvent implémenter @ref{14a4,,tp_iter} en renvoyant une nouvelle référence à eux-mêmes – et doivent donc également implémenter le gestionnaire @ref{14a5,,tp_iternext}.
@end itemize

Tout objet @ref{1aa,,itérateur} doit implémenter à la fois @ref{14a4,,tp_iter} et @ref{14a5,,tp_iternext}. Le gestionnaire @ref{14a4,,tp_iter} d'un itérateur doit renvoyer une nouvelle référence de l'itérateur. Son gestionnaire @ref{14a5,,tp_iternext} doit renvoyer une nouvelle référence à l'objet suivant dans l'itération, s'il y en a un. Si l'itération a atteint la fin, @ref{14a5,,tp_iternext} peut renvoyer @code{NULL} sans définir d'exception, ou il peut définir @ref{be8,,StopIteration} `en plus' de renvoyer @code{NULL} ; éviter de lever une exception peut donner des performances légèrement meilleures. Si une erreur réelle se produit, @ref{14a5,,tp_iternext} doit toujours définir une exception et renvoyer @code{NULL}.

@node Prise en charge de la référence faible,Plus de suggestions,Gestion de protocoles abstraits,Définir les types d'extension divers sujets
@anchor{extending/newtypes weak-reference-support}@anchor{4816}@anchor{extending/newtypes weakref-support}@anchor{24de}
@subsubsection Prise en charge de la référence faible


L'un des objectifs de l'implémentation de la référence faible de `Python' est de permettre à tout type d'objet de participer au mécanisme de référence faible sans avoir à supporter le surcoût de la performance critique des certains objets, tels que les nombres.


@subsubheading Voir aussi


documentation pour le module @ref{113,,weakref}.


For an object to be weakly referenceable, the extension type must set the
@code{Py_TPFLAGS_MANAGED_WEAKREF} bit of the @ref{184b,,tp_flags}
field. The legacy @ref{975,,tp_weaklistoffset} field should
be left as zero.

Concretely, here is how the statically declared type object would look:

@example
static PyTypeObject TrivialType = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    /* ... other members omitted for brevity ... */
    .tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,
@};
@end example

The only further addition is that @code{tp_dealloc} needs to clear any weak
references (by calling @ref{562,,PyObject_ClearWeakRefs()}):

@example
static void
Trivial_dealloc(TrivialObject *self)
@{
    /* Clear weakrefs first before calling any destructors */
    PyObject_ClearWeakRefs((PyObject *) self);
    /* ... remainder of destruction code omitted for brevity ... */
    Py_TYPE(self)->tp_free((PyObject *) self);
@}
@end example

@node Plus de suggestions,,Prise en charge de la référence faible,Définir les types d'extension divers sujets
@anchor{extending/newtypes more-suggestions}@anchor{4817}
@subsubsection Plus de suggestions


Pour savoir comment mettre en œuvre une méthode spécifique pour votre nouveau type de données, téléchargez le code source @ref{6e0,,CPython}. Allez dans le répertoire @code{Objects}, puis cherchez dans les fichiers sources `C' la fonction @code{tp_} plus la fonction que vous voulez (par exemple, @code{tp_richcompare}). Vous trouverez des exemples de la fonction que vous voulez implémenter.

Lorsque vous avez besoin de vérifier qu'un objet est une instance concrète du type que vous implémentez, utilisez la fonction @ref{1885,,PyObject_TypeCheck()}. Voici un exemple de son utilisation :

@example
if (!PyObject_TypeCheck(some_object, &MyType)) @{
    PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
    return NULL;
@}
@end example


@subsubheading Voir aussi



@table @asis

@item Télécharger les versions sources de `CPython'.

@indicateurl{https://www.python.org/downloads/source/}

@item Le projet `CPython' sur `GitHub', où se trouve le code source `CPython'.

@indicateurl{https://github.com/python/cpython}
@end table


@node Construire des extensions C et C++,Construire des extensions C et C++ sur Windows,Définir les types d'extension divers sujets,Création d'extensions sans outils tiers
@anchor{extending/building doc}@anchor{4818}@anchor{extending/building building}@anchor{47c7}@anchor{extending/building building-c-and-c-extensions}@anchor{4819}
@subsection Construire des extensions C et C++


Une extension C pour CPython est une bibliothèque partagée (Un @code{.so} sur Linux, un @code{.pyd} sur Windows), qui expose une `fonction d'initialisation'.

To be importable, the shared library must be available on 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH},
and must be named after the module name, with an appropriate extension.
When using setuptools, the correct filename is generated automatically.

La fonction d'initialisation doit avoir le prototype :

@geindex PyInit_modulename (C function)
@anchor{extending/building c PyInit_modulename}@anchor{481a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyInit_modulename (void)
@end deffn

Elle doit donner soit un module entièrement initialisé, soit une instance de @ref{96a,,PyModuleDef}. Voir @ref{481b,,Initializing C modules} pour plus de détails.

Pour les modules dont les noms sont entièrement en ASCII, la fonction doit être nommée @code{PyInit_<modulename>}, dont @code{<modulename>} est remplacé par le nom du module. En utilisant @ref{481c,,Multi-phase initialization}, il est possible d'utiliser des noms de modules comptant des caractères non ASCII. Dans ce cas, le nom de la fonction d'initialisation est @code{PyInitU_<modulename>}, où @code{modulename} est encodé avec l'encodage `punyencode' de Python, dont les tirets sont remplacés par des tirets-bas. En Python ça donne :

@example
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
@end example

Il est possible d'exporter plusieurs modules depuis une seule bibliothèque partagée en définissant plusieurs fonctions d'initialisation. Cependant pour les importer, un lien symbolique doit être créé pour chacun, ou un `importer' personnalisé, puisque par défaut seule la fonction correspondant au nom du fichier est cherchée. Voir le chapitre `"Multiple modules in one library"' dans la 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} pour plus d'informations.
@anchor{extending/building install-index}@anchor{ee1}
@menu
* Building C and C++ Extensions with setuptools:: 

@end menu

@node Building C and C++ Extensions with setuptools,,,Construire des extensions C et C++
@anchor{extending/building building-c-and-c-extensions-with-setuptools}@anchor{481d}@anchor{extending/building setuptools-index}@anchor{ee2}
@subsubsection Building C and C++ Extensions with setuptools


Python 3.12 and newer no longer come with distutils. Please refer to the
@code{setuptools} documentation at
@indicateurl{https://setuptools.readthedocs.io/en/latest/setuptools.html}
to learn more about how build and distribute C/C++ extensions with setuptools.

@node Construire des extensions C et C++ sur Windows,,Construire des extensions C et C++,Création d'extensions sans outils tiers
@anchor{extending/windows doc}@anchor{481e}@anchor{extending/windows building-c-and-c-extensions-on-windows}@anchor{481f}@anchor{extending/windows building-on-windows}@anchor{1dc2}
@subsection Construire des extensions C et C++ sur Windows


Cette page explique rapidement comment créer un module d'extension Windows pour Python en utilisant Microsoft Visual C++, et donne plus d'informations contextuelles sur son fonctionnement. Le texte explicatif est utile tant pour le développeur Windows qui apprend à construire des extensions Python que pour le développeur Unix souhaitant produire des logiciels pouvant être construits sur Unix et Windows.

Les auteurs de modules sont invités à utiliser l'approche `distutils' pour construire des modules d'extension, au lieu de celle décrite dans cette section. Vous aurez toujours besoin du compilateur C utilisé pour construire Python ; typiquement Microsoft Visual C++.

@cartouche
@quotation Note 
Cette page mentionne plusieurs noms de fichiers comprenant un numéro de version Python encodé. Ces noms de fichiers sont construits sous le format de version @code{XY} ; en pratique, @code{'X'} représente le numéro de version majeure et @code{'Y'} représente le numéro de version mineure de la version Python avec laquelle vous travaillez. Par exemple, si vous utilisez Python 2.2.1, @code{XY} correspond à @code{22}.
@end quotation
@end cartouche

@menu
* Une approche "recette de cuisine":: 
* Différences entre Unix et Windows:: 
* Utiliser les DLL en pratique:: 

@end menu

@node Une approche "recette de cuisine",Différences entre Unix et Windows,,Construire des extensions C et C++ sur Windows
@anchor{extending/windows a-cookbook-approach}@anchor{4820}@anchor{extending/windows win-cookbook}@anchor{4821}
@subsubsection Une approche "recette de cuisine"


There are two approaches to building extension modules on Windows, just as there
are on Unix: use the @code{setuptools} package to control the build process, or
do things manually.  The setuptools approach works well for most extensions;
documentation on using @code{setuptools} to build and package extension modules
is available in @ref{ee2,,Building C and C++ Extensions with setuptools}.  If you find you really need to do
things manually, it may be instructive to study the project file for the
winsound@footnote{https://github.com/python/cpython/tree/3.13/PCbuild/winsound.vcxproj} standard library module.

@node Différences entre Unix et Windows,Utiliser les DLL en pratique,Une approche "recette de cuisine",Construire des extensions C et C++ sur Windows
@anchor{extending/windows differences-between-unix-and-windows}@anchor{4822}@anchor{extending/windows dynamic-linking}@anchor{4823}
@subsubsection Différences entre Unix et Windows


Unix et Windows utilisent des paradigmes complètement différents pour le chargement du code pendant l'exécution. Avant d'essayer de construire un module qui puisse être chargé dynamiquement, soyez conscient du mode de fonctionnement du système.

Sur Unix, un fichier objet partagé (@code{.so}) contient du code servant au programme, ainsi que les noms des fonctions et les données que l'on s'attend  à trouver dans le programme. Quand le fichier est attaché au programme, toutes les références à ces fonctions et données dans le code du fichier sont modifiées pour pointer vers les localisations actuelles dans le programme où sont désormais placées les fonctions et données dans la mémoire. C'est tout simplement une opération de liaison.

Sur Windows, un fichier bibliothèque de liens dynamiques (@code{.dll}) n'a pas de références paresseuses. À la place, un accès aux fonctions ou données passe par une table de conversion. Cela est fait pour que le code DLL ne doive pas être réarrangé à l'exécution pour renvoyer à la mémoire du programme ; à la place, le code utilise déjà la table de conversion DLL, et cette table est modifiée à l'exécution pour pointer vers les fonctions et données.

Sur Unix, il n'y a qu'un type de bibliothèque de fichier (@code{.a}) qui contient du code venant de plusieurs fichiers objets (@code{.o}). Durant l'étape de liaison pour créer un fichier objet partagé (@code{.so}), le lieur peut informer qu'il ne sait pas où un identificateur est défini. Le lieur le cherchera dans les fichiers objet dans les bibliothèques ; s'il le trouve, il inclura tout le code provenant de ce fichier objet.

Sur Windows, il y a deux types de bibliothèques, une bibliothèque statique et une bibliothèque d'importation (toutes deux appelées @code{.lib}). Une bibliothèque statique est comme un fichier Unix @code{.a} ; elle contient du code pouvant être inclus si nécessaire. Une bibliothèque d'importation est uniquement utilisée pour rassurer le lieur qu'un certain identificateur est légal, et sera présent dans le programme quand la DLL est chargée. Comme ça le lieur utilise les informations provenant de la bibliothèque d'importation pour construire la table de conversion pour utiliser les identificateurs qui ne sont pas inclus dans la DLL. Quand une application ou une DLL est liée, une bibliothèque d'importation peut être générée, qui devra être utilisée pour toutes les futures DLL dépendantes aux symboles provenant de l'application ou de la DLL.

Supposons que vous construisez deux modules de chargement dynamiques, B et C, qui ne devraient pas partager un autre bloc de code avec A. Sur Unix, vous ne transmettrez pas @code{A.a} au lieur pour @code{B.so} et @code{C.so} ; cela le ferait être inclus deux fois, pour que B et C aient chacun leur propre copie. Sur Windows, construire @code{A.dll} construira aussi @code{A.lib}. Vous transmettez @code{A.lib} au lieur pour B et C. @code{A.lib} ne contient pas de code ; il contient uniquement des informations qui seront utilisées lors de l'exécution pour accéder au code de A.

Sur Windows, utiliser une bibliothèque d'importation est comme utiliser @code{import spam} ; cela vous donne accès aux noms des spams, mais ne crée par de copie séparée. Sur Unix, se lier à une bibliothèque est plus comme @code{from spam import *} ; cela crée une copie séparée.

@node Utiliser les DLL en pratique,,Différences entre Unix et Windows,Construire des extensions C et C++ sur Windows
@anchor{extending/windows using-dlls-in-practice}@anchor{4824}@anchor{extending/windows win-dlls}@anchor{4825}
@subsubsection Utiliser les DLL en pratique


Le Python de Windows est construit en Microsoft Visual C++ ; utiliser d'autres compilateurs pourrait fonctionner, ou pas. Le reste de cette section est spécifique à MSVC++.

Lorsque vous créez des DLL sur Windows, vous devez transmettre @code{pythonXY.lib} au lieur. Pour construire deux DLL, spam et ni (qui utilisent des fonctions C trouvées dans spam), vous pouvez utiliser ces commandes :

@example
cl /LD /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
@end example

La première commande a créé trois fichiers : @code{spam.obj}, @code{spam.dll} et @code{spam.lib}. @code{Spam.dll} ne contient pas de fonctions Python (telles que @ref{55d,,PyArg_ParseTuple()}), mais il sait comment trouver le code Python grâce à @code{pythonXY.lib}.

La seconde commande a créé @code{ni.dll} (et @code{.obj} et @code{.lib}), qui sait comment trouver les fonctions nécessaires dans spam, ainsi qu'à partir de l'exécutable Python.

Chaque identificateur n'est pas exporté vers la table de conversion. Si vous voulez que tout autre module (y compris Python) soit capable de voir vos identificateurs, vous devez préciser @code{_declspec(dllexport)}, comme dans @code{void _declspec(dllexport) initspam(void)} ou @code{PyObject _declspec(dllexport) *NiGetSpamData(void)}.

Developer Studio will throw in a lot of import libraries that you do not really
need, adding about 100K to your executable.  To get rid of them, use the Project
Settings dialog, Link tab, to specify `ignore default libraries'.  Add the
correct @code{msvcrt`xx'.lib} to the list of libraries.

@node Intégrer l'interpréteur CPython dans une plus grande application,,Création d'extensions sans outils tiers,Extension et intégration de l'interpréteur Python
@anchor{extending/index embedding-the-cpython-runtime-in-a-larger-application}@anchor{4826}
@section Intégrer l'interpréteur CPython dans une plus grande application


Parfois, plutôt que de créer une extension qui s'exécute dans l'interpréteur Python comme application principale, il est préférable d'intégrer l'interpréteur Python dans une application plus large. Cette section donne quelques informations nécessaires au succès de cette opération.

@menu
* Intégrer Python dans une autre application:: 

@end menu

@node Intégrer Python dans une autre application,,,Intégrer l'interpréteur CPython dans une plus grande application
@anchor{extending/embedding doc}@anchor{4827}@anchor{extending/embedding embedding}@anchor{1dde}@anchor{extending/embedding embedding-python-in-another-application}@anchor{4828}
@subsection Intégrer Python dans une autre application


Les chapitres précédents couvraient l'extension de Python, c'est-à-dire, comment enrichir une fonctionnalité de Python en y attachant une bibliothèque de fonctions C. C'est aussi possible dans l'autre sens : enrichir vos applications C/C++ en y intégrant Python. Intégrer Python vous permet d'implémenter certaines fonctionnalités de vos applications en Python plutôt qu'en C ou C++. C'est utile dans de nombreux cas, un exemple serait de permettre aux utilisateurs d'adapter une application à leurs besoins en y écrivant des scripts Python. Vous pouvez aussi l'utiliser vous même si certaines fonctionnalités peuvent être rédigées plus facilement en Python.

Intégrer et étendre Python sont des tâches presque identiques. La différence est qu'en étendant Python, le programme principal reste l'interpréteur Python, alors qu'en intégrant Python le programme principal peut ne rien à voir avec Python. C'est simplement quelques parties du programme qui appellent l'interpréteur Python pour exécuter un peu de code Python.

En intégrant Python, vous fournissez le programme principal. L'une de ses tâches sera d'initialiser l'interpréteur. Au minimum vous devrez appeler @ref{899,,Py_Initialize()}. Il est possible, avec quelques appels supplémentaires, de passer des options à Python. Ensuite vous pourrez appeler l'interpréteur depuis n'importe quelle partie de votre programme.

Il existe différents moyens d'appeler l'interpréteur : vous pouvez donner une chaîne contenant des instructions Python à @ref{4829,,PyRun_SimpleString()}, ou vous pouvez donner un pointeur de fichier `stdio' et un nom de fichier (juste pour nommer les messages d'erreur) à @code{PyRunSimpleFile()}. Vous pouvez aussi appeler les API de bas niveau décrites dans les chapitres précédents pour construire et utiliser des objets Python.


@subsubheading Voir aussi



@table @asis

@item @ref{1b6a,,Manuel de référence de l'API Python/C}

Les détails sur l'interface entre Python et le C sont donnés dans ce manuel. Pléthore informations s'y trouvent.
@end table


@menu
* Intégration de très haut niveau:: 
* Au-delà de l'intégration de haut niveau ; survol: Au-delà de l'intégration de haut niveau survol. 
* Intégration pure:: 
* Étendre un Python intégré:: 
* Intégrer Python dans du C++:: 
* Compiler et Lier en environnement Unix ou similaire:: 

@end menu

@node Intégration de très haut niveau,Au-delà de l'intégration de haut niveau survol,,Intégrer Python dans une autre application
@anchor{extending/embedding high-level-embedding}@anchor{482a}@anchor{extending/embedding very-high-level-embedding}@anchor{482b}
@subsubsection Intégration de très haut niveau


La manière la plus simple d'intégrer Python est d'utiliser une interface de très haut niveau. Cette interface a pour but d'exécuter un script Python sans avoir à interagir avec directement. C'est utile, par exemple, pour effectuer une opération sur un fichier.

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
@{
    PyStatus status;
    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* optional but recommended */
    status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}
    PyConfig_Clear(&config);

    PyRun_SimpleString("from time import time,ctime\n"
                       "print('Today is', ctime(time()))\n");
    if (Py_FinalizeEx() < 0) @{
        exit(120);
    @}
    return 0;

  exception:
     PyConfig_Clear(&config);
     Py_ExitStatusException(status);
@}
@end example

@cartouche
@quotation Note 
@code{#define PY_SSIZE_T_CLEAN} was used to indicate that @code{Py_ssize_t} should be
used in some APIs instead of @code{int}.
It is not necessary since Python 3.13, but we keep it here for backward compatibility.
See @ref{381,,Chaînes et tampons} for a description of this macro.
@end quotation
@end cartouche

Setting @ref{3bb,,PyConfig.program_name} should be called before
@ref{3bc,,Py_InitializeFromConfig()} to inform the interpreter about paths to Python run-time
libraries.  Next, the Python interpreter is initialized with
@ref{899,,Py_Initialize()}, followed by the execution of a hard-coded Python script
that prints the date and time.  Afterwards, the @ref{d03,,Py_FinalizeEx()} call shuts
the interpreter down, followed by the end of the program.  In a real program,
you may want to get the Python script from another source, perhaps a text-editor
routine, a file, or a database.  Getting the Python code from a file can better
be done by using the @ref{482c,,PyRun_SimpleFile()} function, which saves you the
trouble of allocating memory space and loading the file contents.

@node Au-delà de l'intégration de haut niveau survol,Intégration pure,Intégration de très haut niveau,Intégrer Python dans une autre application
@anchor{extending/embedding beyond-very-high-level-embedding-an-overview}@anchor{482d}@anchor{extending/embedding lower-level-embedding}@anchor{482e}
@subsubsection Au-delà de l'intégration de haut niveau : survol


L'interface de haut niveau vous permet d'exécuter n'importe quel morceau de code Python depuis votre application, mais échanger des données est quelque peu alambiqué. Si c'est ce dont vous avez besoin, vous devez utiliser des appels de niveau plus bas. Il vous en coûtera plus de lignes de C à écrire, mais vous pourrez presque tout faire.

Il est à souligner qu'étendre ou intégrer Python revient à la louche au même, en dépit de la différence d'intention. La plupart des sujets parcourus dans les chapitres précédents sont toujours valides. Pour le prouver, regardez ce qu'un code d'extension de Python vers C fait réellement :


@enumerate 

@item 
Convertir des valeurs de Python vers le C,

@item 
Appeler une fonction C en utilisant les valeurs converties, et

@item 
Convertir les résultats de l'appel à la fonction C pour Python.
@end enumerate

Lors de l'intégration de Python, le code de l'interface fait :


@enumerate 

@item 
Convertir les valeurs depuis le C vers Python,

@item 
Effectuer un appel de fonction de l'interface Python en utilisant les valeurs converties, et

@item 
Convertir les valeurs de l'appel Python pour le C.
@end enumerate

Tel que vous le voyez, les conversions sont simplement inversées pour s'adapter aux différentes directions de transfert inter-langage. La seule différence est la fonction que vous appelez entre les deux conversions de données. Lors de l'extension, vous appelez une fonction C, lors de l'intégration vous appelez une fonction Python.

Ce chapitre ne couvrira pas la conversion des données de Python vers le C ni l'inverse. Aussi, un usage correct des références, ainsi que savoir gérer les erreurs sont considérés acquis. Ces aspects étant identiques à l'extension de l'interpréteur, vous pouvez vous référer aux chapitres précédents.

@node Intégration pure,Étendre un Python intégré,Au-delà de l'intégration de haut niveau survol,Intégrer Python dans une autre application
@anchor{extending/embedding id1}@anchor{482f}@anchor{extending/embedding pure-embedding}@anchor{4830}
@subsubsection Intégration pure


L'objectif du premier programme est d'exécuter une fonction dans un script Python. Comme dans la section à propos des interfaces de haut niveau, l'interpréteur n'interagit pas directement avec l'application (mais le fera dans la section suivante).

Le code pour appeler une fonction définie dans un script Python est :

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
@{
    PyObject *pName, *pModule, *pFunc;
    PyObject *pArgs, *pValue;
    int i;

    if (argc < 3) @{
        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
        return 1;
    @}

    Py_Initialize();
    pName = PyUnicode_DecodeFSDefault(argv[1]);
    /* Error checking of pName left out */

    pModule = PyImport_Import(pName);
    Py_DECREF(pName);

    if (pModule != NULL) @{
        pFunc = PyObject_GetAttrString(pModule, argv[2]);
        /* pFunc is a new reference */

        if (pFunc && PyCallable_Check(pFunc)) @{
            pArgs = PyTuple_New(argc - 3);
            for (i = 0; i < argc - 3; ++i) @{
                pValue = PyLong_FromLong(atoi(argv[i + 3]));
                if (!pValue) @{
                    Py_DECREF(pArgs);
                    Py_DECREF(pModule);
                    fprintf(stderr, "Cannot convert argument\n");
                    return 1;
                @}
                /* pValue reference stolen here: */
                PyTuple_SetItem(pArgs, i, pValue);
            @}
            pValue = PyObject_CallObject(pFunc, pArgs);
            Py_DECREF(pArgs);
            if (pValue != NULL) @{
                printf("Result of call: %ld\n", PyLong_AsLong(pValue));
                Py_DECREF(pValue);
            @}
            else @{
                Py_DECREF(pFunc);
                Py_DECREF(pModule);
                PyErr_Print();
                fprintf(stderr,"Call failed\n");
                return 1;
            @}
        @}
        else @{
            if (PyErr_Occurred())
                PyErr_Print();
            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
        @}
        Py_XDECREF(pFunc);
        Py_DECREF(pModule);
    @}
    else @{
        PyErr_Print();
        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
        return 1;
    @}
    if (Py_FinalizeEx() < 0) @{
        return 120;
    @}
    return 0;
@}
@end example

Ce code charge un script Python en utilisant @code{argv[1]}, et appelle une fonction dont le nom est dans @code{argv[2]}. Ses arguments entiers sont les autres valeurs de @code{argv}. Si vous @ref{4831,,compilez et liez} ce programme (appelons l'exécutable @code{call}), et l'appelez pour exécuter un script Python, tel que :

@example
def multiply(a,b):
    print("Will compute", a, "times", b)
    c = 0
    for i in range(0, a):
        c = c + b
    return c
@end example

alors, le résultat sera :

@example
$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6
@end example

Bien que le programme soit plutôt gros pour ses fonctionnalités, la plupart du code n'est que conversion de données entre Python et C, aussi que pour rapporter les erreurs. La partie intéressante, qui concerne l'intégration de Python débute par :

@example
Py_Initialize();
pName = PyUnicode_DecodeFSDefault(argv[1]);
/* Error checking of pName left out */
pModule = PyImport_Import(pName);
@end example

Après avoir initialisé l'interpréteur, le script est chargé en utilisant @ref{13b3,,PyImport_Import()}. Cette fonction prend une chaîne Python pour argument, elle-même construite en utilisant la fonction de conversion @ref{4832,,PyUnicode_FromString()}.

@example
pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */

if (pFunc && PyCallable_Check(pFunc)) @{
    ...
@}
Py_XDECREF(pFunc);
@end example

Une fois le script chargé, le nom recherché est obtenu en utilisant @ref{342,,PyObject_GetAttrString()}. Si le nom existe, et que l'objet récupéré peut être appelé, vous pouvez présumer sans risque que c'est une fonction. Le programme continue, classiquement, par la construction de `n'-uplet d'arguments. L'appel à la fonction Python est alors effectué avec :

@example
pValue = PyObject_CallObject(pFunc, pArgs);
@end example

Après l'exécution de la fonction, @code{pValue} est soit @code{NULL}, soit une référence sur la valeur donnée par la fonction. Assurez-vous de libérer la référence après avoir utilisé la valeur.

@node Étendre un Python intégré,Intégrer Python dans du C++,Intégration pure,Intégrer Python dans une autre application
@anchor{extending/embedding extending-embedded-python}@anchor{4833}@anchor{extending/embedding extending-with-embedding}@anchor{4834}
@subsubsection Étendre un Python intégré


Jusqu'à présent, l'interpréteur Python intégré n'avait pas accès aux fonctionnalités de l'application elle-même. L'API Python le permet en étendant l'interpréteur intégré. Autrement dit, l'interpréteur intégré est étendu avec des fonctions fournies par l'application. Bien que cela puisse sembler complexe, ce n'est pas si dur. Il suffit d'oublier que l'application démarre l'interpréteur Python, au lieu de cela, voyez l'application comme un ensemble de fonctions, et rédigez un peu de code pour exposer ces fonctions à Python, tout comme vous écririez une extension Python normale. Par exemple :

@example
static int numargs=0;

/* Return the number of arguments of the application command line */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
@{
    if(!PyArg_ParseTuple(args, ":numargs"))
        return NULL;
    return PyLong_FromLong(numargs);
@}

static PyMethodDef EmbMethods[] = @{
    @{"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."@},
    @{NULL, NULL, 0, NULL@}
@};

static PyModuleDef EmbModule = @{
    PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
    NULL, NULL, NULL, NULL
@};

static PyObject*
PyInit_emb(void)
@{
    return PyModule_Create(&EmbModule);
@}
@end example

Insérez le code ci-dessus juste avant la fonction @code{main()}. Ajoutez aussi les deux instructions suivantes avant l'appel à @ref{899,,Py_Initialize()} :

@example
numargs = argc;
PyImport_AppendInittab("emb", &PyInit_emb);
@end example

These two lines initialize the @code{numargs} variable, and make the
@code{emb.numargs()} function accessible to the embedded Python interpreter.
With these extensions, the Python script can do things like

@example
import emb
print("Number of arguments", emb.numargs())
@end example

Dans un cas réel, les méthodes exposeraient une API de l'application à Python.

@c TODO: threads, code examples do not really behave well if errors happen
@c (what to watch out for)

@node Intégrer Python dans du C++,Compiler et Lier en environnement Unix ou similaire,Étendre un Python intégré,Intégrer Python dans une autre application
@anchor{extending/embedding embedding-python-in-c}@anchor{4835}@anchor{extending/embedding embeddingincplusplus}@anchor{4836}
@subsubsection Intégrer Python dans du C++


Il est aussi possible d'intégrer Python dans un programme en C++, la manière exacte dont cela se fait dépend de détails du système C++ utilisé. En général vous écrirez le programme principal en C++, utiliserez un compilateur C++ pour compiler et lier votre programme. Il n'y a pas besoin de recompiler Python en utilisant C++.

@node Compiler et Lier en environnement Unix ou similaire,,Intégrer Python dans du C++,Intégrer Python dans une autre application
@anchor{extending/embedding compiling}@anchor{4831}@anchor{extending/embedding compiling-and-linking-under-unix-like-systems}@anchor{4837}
@subsubsection Compiler et Lier en environnement Unix ou similaire


Ce n'est pas évident de trouver les bonnes options à passer au compilateur (et `linker') pour intégrer l'interpréteur Python dans une application, Python ayant besoin de charger des extensions sous forme de bibliothèques dynamiques en C (des @code{.so}) pour se lier avec.

Pour trouver les bonnes options de compilateur et `linker', vous pouvez exécuter le script @code{python`X.Y'-config} généré durant l'installation (un script @code{python3-config} peut aussi être disponible). Ce script a quelques options, celles-ci vous seront utiles :


@itemize *

@item 
@code{pythonX.Y-config --cflags} vous donnera les options recommandées pour compiler :

@example
$ /opt/bin/python3.11-config --cflags
-I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare  -DNDEBUG -g -fwrapv -O3 -Wall
@end example

@item 
@code{pythonX.Y-config --ldflags --embed} vous donnera les drapeaux recommandés lors de l'édition de lien :

@example
$ /opt/bin/python3.11-config --ldflags --embed
-L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -lpthread -ldl  -lutil -lm
@end example
@end itemize

@cartouche
@quotation Note 
Pour éviter la confusion entre différentes installations de Python, (et plus spécialement entre celle de votre système et votre version compilée), il est recommandé d'utiliser un chemin absolu vers @code{python`X.Y'-config}, comme dans l'exemple précédent.
@end quotation
@end cartouche

Si cette procédure ne fonctionne pas pour vous (il n'est pas garanti qu'elle fonctionne pour toutes les plateformes Unix, mais nous traiteront volontiers les @ref{4838,,rapports de bugs}), vous devrez lire la documentation de votre système sur la liaison dynamique (`dynamic linking') et / ou examiner le @code{Makefile} de Python (utilisez @ref{4302,,sysconfig.get_makefile_filename()} pour trouver son emplacement) et les options de compilation. Dans ce cas, le module @ref{da,,sysconfig} est un outil utile pour extraire automatiquement les valeurs de configuration que vous voudrez combiner ensemble. Par exemple :

@example
>>> import sysconfig
>>> sysconfig.get_config_var('LIBS')
'-lpthread -ldl  -lutil'
>>> sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'
@end example

@c XXX similar documentation for Windows missing

@node Manuel de référence de l'API Python/C,Installation de modules Python,Extension et intégration de l'interpréteur Python,Top
@anchor{c-api/index doc}@anchor{4839}@anchor{c-api/index c-api-index}@anchor{1b6a}@anchor{c-api/index python-c-api-reference-manual}@anchor{483a}
@chapter Manuel de référence de l'API Python/C


C'est la documentation de l'API utilisée par les développeurs C et C++ écrivant des modules d'extension ou intégrant Python. Elle va de pair avec @ref{1b69,,Extension et intégration de l'interpréteur Python}, qui décrit les principes généraux de l'écriture d'extensions, mais ne rentre pas dans les détails de chaque fonction de l'API.

@menu
* Introduction: Introduction<12>. 
* Stabilité de l’API C:: 
* The Very High Level Layer:: 
* Reference Counting:: 
* Gestion des exceptions: Gestion des exceptions<2>. 
* Utilitaires: Utilitaires<2>. 
* Couche d'abstraction des objets:: 
* Couche des objets concrets:: 
* Initialization@comma{} Finalization@comma{} and Threads: Initialization Finalization and Threads. 
* Python Initialization Configuration:: 
* Memory Management:: 
* Implémentation d'objets:: 
* Version des API et ABI:: 
* Monitoring C API:: 
* Generating Execution Events:: 

@end menu

@node Introduction<12>,Stabilité de l’API C,,Manuel de référence de l'API Python/C
@anchor{c-api/intro doc}@anchor{483b}@anchor{c-api/intro api-intro}@anchor{483c}@anchor{c-api/intro introduction}@anchor{483d}
@section Introduction


The Application Programmer's Interface to Python gives C and C++ programmers
access to the Python interpreter at a variety of levels.  The API is equally
usable from C++, but for brevity it is generally referred to as the Python/C
API.  There are two fundamentally different reasons for using the Python/C API.
The first reason is to write `extension modules' for specific purposes; these
are C modules that extend the Python interpreter.  This is probably the most
common use.  The second reason is to use Python as a component in a larger
application; this technique is generally referred to as `embedding' Python
in an application.

Writing an extension module is a relatively well-understood process, where a
"cookbook" approach works well.  There are several tools that automate the
process to some extent.  While people have embedded Python in other
applications since its early existence, the process of embedding Python is
less straightforward than writing an extension.

Many API functions are useful independent of whether you're embedding  or
extending Python; moreover, most applications that embed Python  will need to
provide a custom extension as well, so it's probably a  good idea to become
familiar with writing an extension before  attempting to embed Python in a real
application.

@menu
* Coding standards:: 
* Include Files:: 
* Useful macros:: 
* Objects@comma{} Types and Reference Counts: Objects Types and Reference Counts. 
* Exceptions: Exceptions<21>. 
* Embarquer Python: Embarquer Python<2>. 
* Debugging Builds:: 

@end menu

@node Coding standards,Include Files,,Introduction<12>
@anchor{c-api/intro coding-standards}@anchor{483e}
@subsection Coding standards


If you're writing C code for inclusion in CPython, you `must' follow the
guidelines and standards defined in 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/}.  These guidelines apply
regardless of the version of Python you are contributing to.  Following these
conventions is not necessary for your own third party extension modules,
unless you eventually expect to contribute them to Python.

@node Include Files,Useful macros,Coding standards,Introduction<12>
@anchor{c-api/intro api-includes}@anchor{76e}@anchor{c-api/intro include-files}@anchor{483f}
@subsection Include Files


All function, type and macro definitions needed to use the Python/C API are
included in your code by the following line:

@example
#define PY_SSIZE_T_CLEAN
#include <Python.h>
@end example

This implies inclusion of the following standard headers: @code{<stdio.h>},
@code{<string.h>}, @code{<errno.h>}, @code{<limits.h>}, @code{<assert.h>} and @code{<stdlib.h>}
(if available).

@cartouche
@quotation Note 
Python pouvant définir certaines définitions pré-processeur qui affectent les têtes standard sur certains systèmes, vous `devez' inclure @code{Python.h} avant les en-têtes standards.

It is recommended to always define @code{PY_SSIZE_T_CLEAN} before including
@code{Python.h}.  See @ref{895,,Analyse des arguments et construction des valeurs} for a description of this macro.
@end quotation
@end cartouche

All user visible names defined by Python.h (except those defined by the included
standard headers) have one of the prefixes @code{Py} or @code{_Py}.  Names beginning
with @code{_Py} are for internal use by the Python implementation and should not be
used by extension writers. Structure member names do not have a reserved prefix.

@cartouche
@quotation Note 
User code should never define names that begin with @code{Py} or @code{_Py}. This
confuses the reader, and jeopardizes the portability of the user code to
future Python versions, which may define additional names beginning with one
of these prefixes.
@end quotation
@end cartouche

The header files are typically installed with Python.  On Unix, these  are
located in the directories @code{`prefix'/include/pythonversion/} and
@code{`exec_prefix'/include/pythonversion/}, where @ref{1cec,,prefix} and
@ref{1ced,,exec_prefix} are defined by the corresponding parameters to Python's
@code{configure} script and `version' is
@code{'%d.%d' % sys.version_info[:2]}.  On Windows, the headers are installed
in @code{`prefix'/include}, where @code{prefix} is the installation
directory specified to the installer.

To include the headers, place both directories (if different) on your compiler's
search path for includes.  Do `not' place the parent directories on the search
path and then use @code{#include <pythonX.Y/Python.h>}; this will break on
multi-platform builds since the platform independent headers under
@ref{1cec,,prefix} include the platform specific headers from
@ref{1ced,,exec_prefix}.

C++ users should note that although the API is defined entirely using C, the
header files properly declare the entry points to be @code{extern "C"}. As a result,
there is no need to do anything special to use the API from C++.

@node Useful macros,Objects Types and Reference Counts,Include Files,Introduction<12>
@anchor{c-api/intro useful-macros}@anchor{4840}
@subsection Useful macros


Several useful macros are defined in the Python header files.  Many are
defined closer to where they are useful (e.g. @ref{1427,,Py_RETURN_NONE}).
Others of a more general utility are defined here.  This is not necessarily a
complete listing.

@geindex PyMODINIT_FUNC (C macro)
@anchor{c-api/intro c PyMODINIT_FUNC}@anchor{1489}
@deffn {C Macro} PyMODINIT_FUNC

Declare an extension module @code{PyInit} initialization function. The function
return type is @ref{32f,,PyObject}*. The macro declares any special linkage
declarations required by the platform, and for C++ declares the function as
@code{extern "C"}.

The initialization function must be named @code{PyInit_@var{name}}, where
`name' is the name of the module, and should be the only non-@code{static}
item defined in the module file. Example:

@example
static struct PyModuleDef spam_module = @{
    PyModuleDef_HEAD_INIT,
    .m_name = "spam",
    ...
@};

PyMODINIT_FUNC
PyInit_spam(void)
@{
    return PyModule_Create(&spam_module);
@}
@end example
@end deffn

@geindex Py_ABS (C macro)
@anchor{c-api/intro c Py_ABS}@anchor{4841}
@deffn {C Macro} Py_ABS (x)

Return the absolute value of @code{x}.


Ajouté dans la version 3.3.

@end deffn

@geindex Py_ALWAYS_INLINE (C macro)
@anchor{c-api/intro c Py_ALWAYS_INLINE}@anchor{1844}
@deffn {C Macro} Py_ALWAYS_INLINE

Ask the compiler to always inline a static inline function. The compiler can
ignore it and decides to not inline the function.

It can be used to inline performance critical static inline functions when
building Python in debug mode with function inlining disabled. For example,
MSC disables function inlining when building in debug mode.

Marking blindly a static inline function with Py_ALWAYS_INLINE can result in
worse performances (due to increased code size for example). The compiler is
usually smarter than the developer for the cost/benefit analysis.

If Python is @ref{1f6,,built in debug mode} (if the @ref{406a,,Py_DEBUG}
macro is defined), the @ref{1844,,Py_ALWAYS_INLINE} macro does nothing.

It must be specified before the function return type. Usage:

@example
static inline Py_ALWAYS_INLINE int random(void) @{ return 4; @}
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex Py_CHARMASK (C macro)
@anchor{c-api/intro c Py_CHARMASK}@anchor{4842}
@deffn {C Macro} Py_CHARMASK (c)

Argument must be a character or an integer in the range [-128, 127] or [0,
255].  This macro returns @code{c} cast to an @code{unsigned char}.
@end deffn

@geindex Py_DEPRECATED (C macro)
@anchor{c-api/intro c Py_DEPRECATED}@anchor{a92}
@deffn {C Macro} Py_DEPRECATED (version)

Use this for deprecated declarations.  The macro must be placed before the
symbol name.

Exemple :

@example
Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
@end example


Modifié dans la version 3.8: MSVC support was added.

@end deffn

@geindex Py_GETENV (C macro)
@anchor{c-api/intro c Py_GETENV}@anchor{4843}
@deffn {C Macro} Py_GETENV (s)

Like @code{getenv(s)}, but returns @code{NULL} if @ref{94a,,-E} was passed on the
command line (see @ref{3d0,,PyConfig.use_environment}).
@end deffn

@geindex Py_MAX (C macro)
@anchor{c-api/intro c Py_MAX}@anchor{4844}
@deffn {C Macro} Py_MAX (x, y)

Return the maximum value between @code{x} and @code{y}.


Ajouté dans la version 3.3.

@end deffn

@geindex Py_MEMBER_SIZE (C macro)
@anchor{c-api/intro c Py_MEMBER_SIZE}@anchor{4845}
@deffn {C Macro} Py_MEMBER_SIZE (type, member)

Return the size of a structure (@code{type}) @code{member} in bytes.


Ajouté dans la version 3.6.

@end deffn

@geindex Py_MIN (C macro)
@anchor{c-api/intro c Py_MIN}@anchor{4846}
@deffn {C Macro} Py_MIN (x, y)

Return the minimum value between @code{x} and @code{y}.


Ajouté dans la version 3.3.

@end deffn

@geindex Py_NO_INLINE (C macro)
@anchor{c-api/intro c Py_NO_INLINE}@anchor{1845}
@deffn {C Macro} Py_NO_INLINE

Disable inlining on a function. For example, it reduces the C stack
consumption: useful on LTO+PGO builds which heavily inline code (see
bpo-33720@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=33720}).

Utilisation :

@example
Py_NO_INLINE static int random(void) @{ return 4; @}
@end example


Ajouté dans la version 3.11.

@end deffn

@geindex Py_STRINGIFY (C macro)
@anchor{c-api/intro c Py_STRINGIFY}@anchor{4847}
@deffn {C Macro} Py_STRINGIFY (x)

Convert @code{x} to a C string.  E.g. @code{Py_STRINGIFY(123)} returns
@code{"123"}.


Ajouté dans la version 3.4.

@end deffn

@geindex Py_UNREACHABLE (C macro)
@anchor{c-api/intro c Py_UNREACHABLE}@anchor{ba3}
@deffn {C Macro} Py_UNREACHABLE ()

Use this when you have a code path that cannot be reached by design.
For example, in the @code{default:} clause in a @code{switch} statement for which
all possible values are covered in @code{case} statements.  Use this in places
where you might be tempted to put an @code{assert(0)} or @code{abort()} call.

In release mode, the macro helps the compiler to optimize the code, and
avoids a warning about unreachable code.  For example, the macro is
implemented with @code{__builtin_unreachable()} on GCC in release mode.

A use for @code{Py_UNREACHABLE()} is following a call a function that
never returns but that is not declared @code{_Py_NO_RETURN}.

If a code path is very unlikely code but can be reached under exceptional
case, this macro must not be used.  For example, under low memory condition
or if a system call returns a value out of the expected range.  In this
case, it's better to report the error to the caller.  If the error cannot
be reported to caller, @ref{970,,Py_FatalError()} can be used.


Ajouté dans la version 3.7.

@end deffn

@geindex Py_UNUSED (C macro)
@anchor{c-api/intro c Py_UNUSED}@anchor{16a6}
@deffn {C Macro} Py_UNUSED (arg)

Use this for unused arguments in a function definition to silence compiler
warnings. Example: @code{int func(int a, int Py_UNUSED(b)) @{ return a; @}}.


Ajouté dans la version 3.4.

@end deffn

@geindex PyDoc_STRVAR (C macro)
@anchor{c-api/intro c PyDoc_STRVAR}@anchor{1900}
@deffn {C Macro} PyDoc_STRVAR (name, str)

Creates a variable with name @code{name} that can be used in docstrings.
If Python is built without docstrings, the value will be empty.

Use @ref{1900,,PyDoc_STRVAR} for docstrings to support building
Python without docstrings, as specified in 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/}.

Exemple :

@example
PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");

static PyMethodDef deque_methods[] = @{
    // ...
    @{"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc@},
    // ...
@}
@end example
@end deffn

@geindex PyDoc_STR (C macro)
@anchor{c-api/intro c PyDoc_STR}@anchor{1799}
@deffn {C Macro} PyDoc_STR (str)

Creates a docstring for the given input string or an empty string
if docstrings are disabled.

Use @ref{1799,,PyDoc_STR} in specifying docstrings to support
building Python without docstrings, as specified in 
@geindex Python Enhancement Proposals; PEP 7
PEP 7@footnote{https://peps.python.org/pep-0007/}.

Exemple :

@example
static PyMethodDef pysqlite_row_methods[] = @{
    @{"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
        PyDoc_STR("Returns the keys of the row.")@},
    @{NULL, NULL@}
@};
@end example
@end deffn

@node Objects Types and Reference Counts,Exceptions<21>,Useful macros,Introduction<12>
@anchor{c-api/intro api-objects}@anchor{4848}@anchor{c-api/intro objects-types-and-reference-counts}@anchor{4849}
@subsection Objects, Types and Reference Counts


@geindex object;type

Most Python/C API functions have one or more arguments as well as a return value
of type @ref{32f,,PyObject}*.  This type is a pointer to an opaque data type
representing an arbitrary Python object.  Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type.  Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
@ref{32f,,PyObject}, only pointer variables of type @ref{32f,,PyObject}* can  be
declared.  The sole exception are the type objects; since these must never be
deallocated, they are typically static @ref{a93,,PyTypeObject} objects.

All Python objects (even Python integers) have a `type' and a
`reference count'.  An object's type determines what kind of object it is
(e.g., an integer, a list, or a user-defined function; there are many more as
explained in @ref{1e6a,,Hiérarchie des types standards}).  For each of the well-known types there is a macro
to check whether an object is of that type; for instance, @code{PyList_Check(a)} is
true if (and only if) the object pointed to by `a' is a Python list.

@menu
* Compteurs de références: Compteurs de références<2>. 
* Types:: 

@end menu

@node Compteurs de références<2>,Types,,Objects Types and Reference Counts
@anchor{c-api/intro api-refcounts}@anchor{484a}@anchor{c-api/intro reference-counts}@anchor{484b}
@subsubsection Compteurs de références


The reference count is important because today's computers have a  finite
(and often severely limited) memory size; it counts how many different
places there are that have a @ref{333,,strong reference} to an object.
Such a place could be another object, or a global (or static) C variable,
or a local variable in some C function.
When the last @ref{333,,strong reference} to an object is released
(i.e. its reference count becomes zero), the object is deallocated.
If it contains references to other objects, those references are released.
Those other objects may be deallocated in turn, if there are no more
references to them, and so on.  (There's an obvious problem  with
objects that reference each other here; for now, the solution
is "don't do that.")

@geindex Py_INCREF (C function)
@geindex Py_DECREF (C function)

Reference counts are always manipulated explicitly.  The normal way is
to use the macro @ref{55a,,Py_INCREF()} to take a new reference to an
object (i.e. increment its reference count by one),
and @ref{55b,,Py_DECREF()} to release that reference (i.e. decrement the
reference count by one).  The @ref{55b,,Py_DECREF()} macro
is considerably more complex than the incref one, since it must check whether
the reference count becomes zero and then cause the object's deallocator to be
called.  The deallocator is a function pointer contained in the object's type
structure.  The type-specific deallocator takes care of releasing references
for other objects contained in the object if this is a compound
object type, such as a list, as well as performing any additional finalization
that's needed.  There's no chance that the reference count can overflow; at
least as many bits are used to hold the reference count as there are distinct
memory locations in virtual memory (assuming @code{sizeof(Py_ssize_t) >= sizeof(void*)}).
Thus, the reference count increment is a simple operation.

It is not necessary to hold a @ref{333,,strong reference} (i.e. increment
the reference count) for every local variable that contains a pointer
to an object.  In theory, the  object's
reference count goes up by one when the variable is made to  point to it and it
goes down by one when the variable goes out of  scope.  However, these two
cancel each other out, so at the end the  reference count hasn't changed.  The
only real reason to use the  reference count is to prevent the object from being
deallocated as  long as our variable is pointing to it.  If we know that there
is at  least one other reference to the object that lives at least as long as
our variable, there is no need to take a new @ref{333,,strong reference}
(i.e. increment the reference count) temporarily.
An important situation where this arises is in objects  that are passed as
arguments to C functions in an extension module  that are called from Python;
the call mechanism guarantees to hold a  reference to every argument for the
duration of the call.

However, a common pitfall is to extract an object from a list and hold on to it
for a while without taking a new reference.  Some other operation might
conceivably remove the object from the list, releasing that reference,
and possibly deallocating it. The real danger is that innocent-looking
operations may invoke arbitrary Python code which could do this; there is a code
path which allows control to flow back to the user from a @ref{55b,,Py_DECREF()}, so
almost any operation is potentially dangerous.

A safe approach is to always use the generic operations (functions  whose name
begins with @code{PyObject_}, @code{PyNumber_}, @code{PySequence_} or @code{PyMapping_}).
These operations always create a new @ref{333,,strong reference}
(i.e. increment the reference count) of the object they return.
This leaves the caller with the responsibility to call @ref{55b,,Py_DECREF()} when
they are done with the result; this soon becomes second nature.

@menu
* Reference Count Details:: 

@end menu

@node Reference Count Details,,,Compteurs de références<2>
@anchor{c-api/intro api-refcountdetails}@anchor{484c}@anchor{c-api/intro reference-count-details}@anchor{484d}
@subsubsection Reference Count Details


The reference count behavior of functions in the Python/C API is best  explained
in terms of `ownership of references'.  Ownership pertains to references, never
to objects (objects are not owned: they are always shared).  "Owning a
reference" means being responsible for calling Py_DECREF on it when the
reference is no longer needed.  Ownership can also be transferred, meaning that
the code that receives ownership of the reference then becomes responsible for
eventually releasing it by calling @ref{55b,,Py_DECREF()} or @ref{779,,Py_XDECREF()}
when it's no longer needed---or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its caller, the
caller is said to receive a `new' reference.  When no ownership is transferred,
the caller is said to `borrow' the reference. Nothing needs to be done for a
@ref{334,,borrowed reference}.

Conversely, when a calling function passes in a reference to an  object, there
are two possibilities: the function `steals' a  reference to the object, or it
does not.  `Stealing a reference' means that when you pass a reference to a
function, that function assumes that it now owns that reference, and you are not
responsible for it any longer.

@geindex PyList_SetItem (C function)
@geindex PyTuple_SetItem (C function)

Few functions steal references; the two notable exceptions are
@ref{47d9,,PyList_SetItem()} and @ref{47d8,,PyTuple_SetItem()}, which  steal a reference
to the item (but not to the tuple or list into which the item is put!).  These
functions were designed to steal a reference because of a common idiom for
populating a tuple or list with newly created objects; for example, the code to
create the tuple @code{(1, 2, "three")} could look like this (forgetting about
error handling for the moment; a better way to code this is shown below):

@example
PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));
@end example

Here, @ref{17c7,,PyLong_FromLong()} returns a new reference which is immediately
stolen by @ref{47d8,,PyTuple_SetItem()}.  When you want to keep using an object
although the reference to it will be stolen, use @ref{55a,,Py_INCREF()} to grab
another reference before calling the reference-stealing function.

Incidentally, @ref{47d8,,PyTuple_SetItem()} is the `only' way to set tuple items;
@ref{19e2,,PySequence_SetItem()} and @ref{484e,,PyObject_SetItem()} refuse to do this
since tuples are an immutable data type.  You should only use
@ref{47d8,,PyTuple_SetItem()} for tuples that you are creating yourself.

Equivalent code for populating a list can be written using @ref{484f,,PyList_New()}
and @ref{47d9,,PyList_SetItem()}.

However, in practice, you will rarely use these ways of creating and populating
a tuple or list.  There's a generic function, @ref{894,,Py_BuildValue()}, that can
create most common objects from C values, directed by a `format string'.
For example, the above two blocks of code could be replaced by the following
(which also takes care of the error checking):

@example
PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");
@end example

It is much more common to use @ref{484e,,PyObject_SetItem()} and friends with items
whose references you are only borrowing, like arguments that were passed in to
the function you are writing.  In that case, their behaviour regarding references
is much saner, since you don't have to take a new reference just so you
can give that reference away ("have it be stolen").  For example, this function
sets all items of a list (actually, any mutable sequence) to a given item:

@example
int
set_all(PyObject *target, PyObject *item)
@{
    Py_ssize_t i, n;

    n = PyObject_Length(target);
    if (n < 0)
        return -1;
    for (i = 0; i < n; i++) @{
        PyObject *index = PyLong_FromSsize_t(i);
        if (!index)
            return -1;
        if (PyObject_SetItem(target, index, item) < 0) @{
            Py_DECREF(index);
            return -1;
        @}
        Py_DECREF(index);
    @}
    return 0;
@}
@end example

@geindex set_all()

The situation is slightly different for function return values.   While passing
a reference to most functions does not change your  ownership responsibilities
for that reference, many functions that  return a reference to an object give
you ownership of the reference. The reason is simple: in many cases, the
returned object is created  on the fly, and the reference you get is the only
reference to the  object.  Therefore, the generic functions that return object
references, like @ref{33d,,PyObject_GetItem()} and  @ref{19e1,,PySequence_GetItem()},
always return a new reference (the caller becomes the owner of the reference).

It is important to realize that whether you own a reference returned  by a
function depends on which function you call only --- `the plumage' (the type of
the object passed as an argument to the function) `doesn't enter into it!'
Thus, if you  extract an item from a list using @ref{352,,PyList_GetItem()}, you
don't own the reference --- but if you obtain the same item from the same list
using @ref{19e1,,PySequence_GetItem()} (which happens to take exactly the same
arguments), you do own a reference to the returned object.

@geindex PyList_GetItem (C function)
@geindex PySequence_GetItem (C function)

Here is an example of how you could write a function that computes the sum of
the items in a list of integers; once using  @ref{352,,PyList_GetItem()}, and once
using @ref{19e1,,PySequence_GetItem()}.

@example
long
sum_list(PyObject *list)
@{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;

    n = PyList_Size(list);
    if (n < 0)
        return -1; /* Not a list */
    for (i = 0; i < n; i++) @{
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyLong_Check(item)) continue; /* Skip non-integers */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* Integer too big to fit in a C long, bail out */
            return -1;
        total += value;
    @}
    return total;
@}
@end example

@geindex sum_list()

@example
long
sum_sequence(PyObject *sequence)
@{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n < 0)
        return -1; /* Has no length */
    for (i = 0; i < n; i++) @{
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyLong_Check(item)) @{
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* Integer too big to fit in a C long, bail out */
                return -1;
            total += value;
        @}
        else @{
            Py_DECREF(item); /* Discard reference ownership */
        @}
    @}
    return total;
@}
@end example

@geindex sum_sequence()

@node Types,,Compteurs de références<2>,Objects Types and Reference Counts
@anchor{c-api/intro api-types}@anchor{4850}@anchor{c-api/intro types}@anchor{4851}
@subsubsection Types


There are few other data types that play a significant role in  the Python/C
API; most are simple C types such as int,  long,
double and char*.  A few structure types  are used to
describe static tables used to list the functions exported  by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number.  These will  be discussed together with the functions that
use them.

@geindex Py_ssize_t (C type)
@anchor{c-api/intro c Py_ssize_t}@anchor{a4e}
@deffn {C Type} type Py_ssize_t
` Part of the @ref{53e,,Stable ABI}.'
A signed integral type such that @code{sizeof(Py_ssize_t) == sizeof(size_t)}.
C99 doesn't define such a thing directly (size_t is an unsigned integral type).
See 
@geindex Python Enhancement Proposals; PEP 353
PEP 353@footnote{https://peps.python.org/pep-0353/} for details. @code{PY_SSIZE_T_MAX} is the largest positive value
of type @ref{a4e,,Py_ssize_t}.
@end deffn

@node Exceptions<21>,Embarquer Python<2>,Objects Types and Reference Counts,Introduction<12>
@anchor{c-api/intro api-exceptions}@anchor{4852}@anchor{c-api/intro exceptions}@anchor{4853}
@subsection Exceptions


The Python programmer only needs to deal with exceptions if specific  error
handling is required; unhandled exceptions are automatically  propagated to the
caller, then to the caller's caller, and so on, until they reach the top-level
interpreter, where they are reported to the  user accompanied by a stack
traceback.

@geindex PyErr_Occurred (C function)

For C programmers, however, error checking always has to be explicit.  All
functions in the Python/C API can raise exceptions, unless an explicit claim is
made otherwise in a function's documentation.  In general, when a function
encounters an error, it sets an exception, discards any object references that
it owns, and returns an error indicator.  If not documented otherwise, this
indicator is either @code{NULL} or @code{-1}, depending on the function's return type.
A few functions return a Boolean true/false result, with false indicating an
error.  Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with
@ref{187f,,PyErr_Occurred()}.  These exceptions are always explicitly documented.

@geindex PyErr_SetString (C function)
@geindex PyErr_Clear (C function)

Exception state is maintained in per-thread storage (this is  equivalent to
using global storage in an unthreaded application).  A  thread can be in one of
two states: an exception has occurred, or not. The function
@ref{187f,,PyErr_Occurred()} can be used to check for this: it returns a borrowed
reference to the exception type object when an exception has occurred, and
@code{NULL} otherwise.  There are a number of functions to set the exception state:
@ref{568,,PyErr_SetString()} is the most common (though not the most general)
function to set the exception state, and @ref{101a,,PyErr_Clear()} clears the
exception state.

The full exception state consists of three objects (all of which can  be
@code{NULL}): the exception type, the corresponding exception  value, and the
traceback.  These have the same meanings as the Python result of
@code{sys.exc_info()}; however, they are not the same: the Python objects represent
the last exception being handled by a Python  @ref{6d3,,try} ...
@ref{189,,except} statement, while the C level exception state only exists while
an exception is being passed on between C functions until it reaches the Python
bytecode interpreter's  main loop, which takes care of transferring it to
@code{sys.exc_info()} and friends.

@geindex exc_info (in module sys)

Note that starting with Python 1.5, the preferred, thread-safe way to access the
exception state from Python code is to call the function @ref{675,,sys.exc_info()},
which returns the per-thread exception state for Python code.  Also, the
semantics of both ways to access the exception state have changed so that a
function which catches an exception will save and restore its thread's exception
state so as to preserve the exception state of its caller.  This prevents common
bugs in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often unwanted
lifetime extension for objects that are referenced by the stack frames in the
traceback.

As a general principle, a function that calls another function to  perform some
task should check whether the called function raised an  exception, and if so,
pass the exception state on to its caller.  It  should discard any object
references that it owns, and return an  error indicator, but it should `not' set
another exception --- that would overwrite the exception that was just raised,
and lose important information about the exact cause of the error.

@geindex sum_sequence()

A simple example of detecting exceptions and passing them on is shown in the
@code{sum_sequence()} example above.  It so happens that this example doesn't
need to clean up any owned references when it detects an error.  The following
example function shows some error cleanup.  First, to remind you why you like
Python, we show the equivalent Python code:

@example
def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1
@end example

@geindex incr_item()

Here is the corresponding C code, in all its glory:

@example
int
incr_item(PyObject *dict, PyObject *key)
@{
    /* Objects all initialized to NULL for Py_XDECREF */
    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
    int rv = -1; /* Return value initialized to -1 (failure) */

    item = PyObject_GetItem(dict, key);
    if (item == NULL) @{
        /* Handle KeyError only: */
        if (!PyErr_ExceptionMatches(PyExc_KeyError))
            goto error;

        /* Clear the error and use zero: */
        PyErr_Clear();
        item = PyLong_FromLong(0L);
        if (item == NULL)
            goto error;
    @}
    const_one = PyLong_FromLong(1L);
    if (const_one == NULL)
        goto error;

    incremented_item = PyNumber_Add(item, const_one);
    if (incremented_item == NULL)
        goto error;

    if (PyObject_SetItem(dict, key, incremented_item) < 0)
        goto error;
    rv = 0; /* Success */
    /* Continue with cleanup code */

 error:
    /* Cleanup code, shared by success and failure path */

    /* Use Py_XDECREF() to ignore NULL references */
    Py_XDECREF(item);
    Py_XDECREF(const_one);
    Py_XDECREF(incremented_item);

    return rv; /* -1 for error, 0 for success */
@}
@end example

@geindex incr_item()

@geindex PyErr_ExceptionMatches (C function)
@geindex PyErr_Clear (C function)
@geindex Py_XDECREF (C function)

This example represents an endorsed use of the @code{goto} statement  in C!
It illustrates the use of @ref{4854,,PyErr_ExceptionMatches()} and
@ref{101a,,PyErr_Clear()} to handle specific exceptions, and the use of
@ref{779,,Py_XDECREF()} to dispose of owned references that may be @code{NULL} (note the
@code{'X'} in the name; @ref{55b,,Py_DECREF()} would crash when confronted with a
@code{NULL} reference).  It is important that the variables used to hold owned
references are initialized to @code{NULL} for this to work; likewise, the proposed
return value is initialized to @code{-1} (failure) and only set to success after
the final call made is successful.

@node Embarquer Python<2>,Debugging Builds,Exceptions<21>,Introduction<12>
@anchor{c-api/intro api-embedding}@anchor{4855}@anchor{c-api/intro embedding-python}@anchor{4856}
@subsection Embarquer Python


The one important task that only embedders (as opposed to extension writers) of
the Python interpreter have to worry about is the initialization, and possibly
the finalization, of the Python interpreter.  Most functionality of the
interpreter can only be used after the interpreter has been initialized.

@geindex Py_Initialize (C function)
@geindex module;builtins
@geindex module;__main__
@geindex module;sys
@geindex module;search;path
@geindex path (in module sys)

The basic initialization function is @ref{899,,Py_Initialize()}. This initializes
the table of loaded modules, and creates the fundamental modules
@ref{12,,builtins}, @ref{1,,__main__}, and @ref{d8,,sys}.  It also
initializes the module search path (@code{sys.path}).

@ref{899,,Py_Initialize()} does not set the "script argument list"  (@code{sys.argv}).
If this variable is needed by Python code that will be executed later, setting
@ref{3ba,,PyConfig.argv} and @ref{18b6,,PyConfig.parse_argv} must be set: see
@ref{39e,,Python Initialization Configuration}.

On most systems (in particular, on Unix and Windows, although the details are
slightly different), @ref{899,,Py_Initialize()} calculates the module search path
based upon its best guess for the location of the standard Python interpreter
executable, assuming that the Python library is found in a fixed location
relative to the Python interpreter executable.  In particular, it looks for a
directory named @code{lib/python`X.Y'} relative to the parent directory
where the executable named @code{python} is found on the shell command search
path (the environment variable 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}).

For instance, if the Python executable is found in
@code{/usr/local/bin/python}, it will assume that the libraries are in
@code{/usr/local/lib/python`X.Y'}.  (In fact, this particular path is also
the "fallback" location, used when no executable file named @code{python} is
found along 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH}.)  The user can override this behavior by setting the
environment variable 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME}, or insert additional directories in
front of the standard path by setting 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH}.

@geindex Py_GetPath (C function)
@geindex Py_GetPrefix (C function)
@geindex Py_GetExecPrefix (C function)
@geindex Py_GetProgramFullPath (C function)

The embedding application can steer the search by setting
@ref{3bb,,PyConfig.program_name} `before' calling
@ref{3bc,,Py_InitializeFromConfig()}. Note that
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} still overrides this and 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} is still
inserted in front of the standard path.  An application that requires total
control has to provide its own implementation of @ref{3aa,,Py_GetPath()},
@ref{3ac,,Py_GetPrefix()}, @ref{3a8,,Py_GetExecPrefix()}, and
@ref{3ae,,Py_GetProgramFullPath()} (all defined in @code{Modules/getpath.c}).

@geindex Py_IsInitialized (C function)

Sometimes, it is desirable to "uninitialize" Python.  For instance,  the
application may want to start over (make another call to
@ref{899,,Py_Initialize()}) or the application is simply done with its  use of
Python and wants to free memory allocated by Python.  This can be accomplished
by calling @ref{d03,,Py_FinalizeEx()}.  The function @ref{4857,,Py_IsInitialized()} returns
true if Python is currently in the initialized state.  More information about
these functions is given in a later chapter. Notice that @ref{d03,,Py_FinalizeEx()}
does `not' free all memory allocated by the Python interpreter, e.g. memory
allocated by extension modules currently cannot be released.

@node Debugging Builds,,Embarquer Python<2>,Introduction<12>
@anchor{c-api/intro api-debugging}@anchor{4858}@anchor{c-api/intro debugging-builds}@anchor{4859}
@subsection Debugging Builds


Python can be built with several macros to enable extra checks of the
interpreter and extension modules.  These checks tend to add a large amount of
overhead to the runtime so they are not enabled by default.

A full list of the various types of debugging builds is in the file
@code{Misc/SpecialBuilds.txt} in the Python source distribution. Builds are
available that support tracing of reference counts, debugging the memory
allocator, or low-level profiling of the main interpreter loop.  Only the most
frequently used builds will be described in the remainder of this section.

@geindex Py_DEBUG (C macro)
@anchor{c-api/intro c Py_DEBUG}@anchor{406a}
@deffn {C Macro} Py_DEBUG
@end deffn

Compiling the interpreter with the @code{Py_DEBUG} macro defined produces
what is generally meant by @ref{1f6,,a debug build of Python}.
@code{Py_DEBUG} is enabled in the Unix build by adding
@ref{418,,--with-pydebug} to the @code{./configure} command.
It is also implied by the presence of the
not-Python-specific @code{_DEBUG} macro.  When @code{Py_DEBUG} is enabled
in the Unix build, compiler optimization is disabled.

In addition to the reference count debugging described below, extra checks are
performed, see @ref{1f6,,Python Debug Build}.

Defining @code{Py_TRACE_REFS} enables reference tracing
(see the @ref{38b,,configure --with-trace-refs option}).
When defined, a circular doubly linked list of active objects is maintained by adding two extra
fields to every @ref{32f,,PyObject}.  Total allocations are tracked as well.  Upon
exit, all existing references are printed.  (In interactive mode this happens
after every statement run by the interpreter.)

Please refer to @code{Misc/SpecialBuilds.txt} in the Python source distribution
for more detailed information.

@node Stabilité de l’API C,The Very High Level Layer,Introduction<12>,Manuel de référence de l'API Python/C
@anchor{c-api/stable doc}@anchor{485a}@anchor{c-api/stable c-api-stability}@anchor{485b}@anchor{c-api/stable stable}@anchor{53e}
@section Stabilité de l’API C


Unless documented otherwise, Python's C API is covered by the Backwards
Compatibility Policy, 
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/}.
Most changes to it are source-compatible (typically by only adding new API).
Changing existing API or removing API is only done after a deprecation period
or to fix serious issues.

CPython's Application Binary Interface (ABI) is forward- and
backwards-compatible across a minor release (if these are compiled the same
way; see @ref{485c,,Considérations relatives aux plateformes} below).
So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa,
but will need to be compiled separately for 3.9.x and 3.11.x.

There are two tiers of C API with different stability expectations:


@itemize -

@item 
@ref{532,,Unstable API}, may change in minor versions without
a deprecation period. It is marked by the @code{PyUnstable} prefix in names.

@item 
@ref{38c,,Limited API}, is compatible across several minor releases.
When @ref{414,,Py_LIMITED_API} is defined, only this subset is exposed
from @code{Python.h}.
@end itemize

These are discussed in more detail below.

Names prefixed by an underscore, such as @code{_Py_InternalState},
are private API that can change without notice even in patch releases.
If you need to use this API, consider reaching out to
CPython developers@footnote{https://discuss.python.org/c/core-dev/c-api/30}
to discuss adding public API for your use case.

@menu
* Unstable C API:: 
* ABI stable:: 
* Considérations relatives aux plateformes:: 
* Contenu de l’API restreinte:: 

@end menu

@node Unstable C API,ABI stable,,Stabilité de l’API C
@anchor{c-api/stable id1}@anchor{485d}@anchor{c-api/stable unstable-c-api}@anchor{532}
@subsection Unstable C API


@geindex PyUnstable

Any API named with the @code{PyUnstable} prefix exposes CPython implementation
details, and may change in every minor release (e.g. from 3.9 to 3.10) without
any deprecation warnings.
However, it will not change in a bugfix release (e.g. from 3.10.0 to 3.10.1).

It is generally intended for specialized, low-level tools like debuggers.

Projects that use this API are expected to follow
CPython development and spend extra effort adjusting to changes.

@node ABI stable,Considérations relatives aux plateformes,Unstable C API,Stabilité de l’API C
@anchor{c-api/stable stable-application-binary-interface}@anchor{485e}
@subsection ABI stable


For simplicity, this document talks about `extensions', but the Limited API
and Stable ABI work the same way for all uses of the API – for example,
embedding Python.

@menu
* Limited C API:: 
* Stable ABI:: 
* Porté de l’API restreinte et performance:: 
* Inconvénients de l’API restreinte:: 

@end menu

@node Limited C API,Stable ABI,,ABI stable
@anchor{c-api/stable id2}@anchor{485f}@anchor{c-api/stable limited-c-api}@anchor{38c}
@subsubsection Limited C API


Python 3.2 introduced the `Limited API', a subset of Python's C API.
Extensions that only use the Limited API can be
compiled once and be loaded on multiple versions of Python.
Contents of the Limited API are @ref{784,,listed below}.

@geindex Py_LIMITED_API (C macro)
@anchor{c-api/stable c Py_LIMITED_API}@anchor{414}
@deffn {C Macro} Py_LIMITED_API

Définissez cette macro avant d’inclure @code{Python.h} pour n’inclure que l’API restreinte et indiquer sa version.

Define @code{Py_LIMITED_API} to the value of @ref{741,,PY_VERSION_HEX}
corresponding to the lowest Python version your extension supports.
The extension will be ABI-compatible with all Python 3 releases
from the specified one onward, and can use Limited API introduced up to that
version.

Il est recommandé de renseigner une version mineure minimale (par exemple @code{0x030A0000} pour Python 3.10) plutôt que d’utiliser directement la macro @code{PY_VERSION_HEX} pour ne pas dépendre de la version de Python utilisée lors de la compilation.

Vous pouvez aussi définir @code{Py_LIMITED_API} à @code{3}. Cette valeur est équivalente à @code{0x03020000} correspondant à Python 3.2, la première version à supporter l’API restreinte.
@end deffn

@node Stable ABI,Porté de l’API restreinte et performance,Limited C API,ABI stable
@anchor{c-api/stable id3}@anchor{4860}@anchor{c-api/stable stable-abi}@anchor{4861}
@subsubsection Stable ABI


To enable this, Python provides a `Stable ABI': a set of symbols that will
remain ABI-compatible across Python 3.x versions.

@cartouche
@quotation Note 
The Stable ABI prevents ABI issues, like linker errors due to missing
symbols or data corruption due to changes in structure layouts or function
signatures.
However, other changes in Python can change the `behavior' of extensions.
See Python's Backwards Compatibility Policy (
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/}) for details.
@end quotation
@end cartouche

The Stable ABI contains symbols exposed in the @ref{38c,,Limited API}, but also other ones – for example, functions necessary to
support older versions of the Limited API.

Sur Windows les extensions qui utilisent l’ABI stable doivent être liées avec @code{python3.dll} et non pas avec une bibliothèque spécifique à une version comme @code{python39.dll}.

Sur certaines plateformes Python essaiera de charger une bibliothèque partagée dont le nom contient @code{abi3} (par exemple @code{mymodule.abi3.so}). Il ne vérifie pas si ces extensions respectent l’ABI stable. L’utilisateur (ou ses outils d’administration) doit s’assurer que les extensions compilées avec une version donnée de l’API restreinte, par exemple 3.10+, ne sont pas utilisées avec des versions plus anciennes de Python.

Toutes les fonctions de l’ABI stable sont présentes dans la bibliothèque dynamique de Python en tant que fonction, et pas uniquement comme macro. Elles peuvent donc être utilisées avec des langages qui n’utilisent pas le pré-processeur C.

@node Porté de l’API restreinte et performance,Inconvénients de l’API restreinte,Stable ABI,ABI stable
@anchor{c-api/stable limited-api-scope-and-performance}@anchor{4862}
@subsubsection Porté de l’API restreinte et performance


L’objectif de l’API restreinte est de permettre l’ensemble des opérations possibles avec l’API C étendue, mais peut avoir un impact sur les performances.

Par exemple la fonction @ref{352,,PyList_GetItem()} est disponible, mais la macro « dangereuse » @ref{4863,,PyList_GET_ITEM()} ne l’est pas. Cette macro peut être plus rapide car elle dépend de détails d’implémentation spécifique à l’objet @code{list}.

Si @code{Py_LIMITED_API} n’est pas défini certaines fonctions de l’API C seront remplacées par des macros ou une version en-ligne. Définir @code{Py_LIMITED_API} désactive cette optimisation, permettant de se garantir contre les évolutions des structures de données utilisées par Python, et peut réduire les performances.

En omettant la définition de @code{Py_LIMITED_API} il est possible de compiler une extension utilisant l’API restreinte avec une version spécifique de l’ABI. Les performances seront meilleures pour cette version de Python, mais la compatibilité sera réduite. Compiler en définissant @code{Py_LIMITED_API} produira une extension qui peut être utilisée quand une variante spécifique à une version n’est pas disponible — par exemple pour une version alpha de Python.

@node Inconvénients de l’API restreinte,,Porté de l’API restreinte et performance,ABI stable
@anchor{c-api/stable limited-api-caveats}@anchor{4864}
@subsubsection Inconvénients de l’API restreinte


Note that compiling with @code{Py_LIMITED_API} is `not' a complete guarantee that
code conforms to the @ref{38c,,Limited API} or the @ref{4861,,Stable ABI}. @code{Py_LIMITED_API} only covers definitions, but an API also
includes other issues, such as expected semantics.

Une des limitations est que @code{Py_LIMITED_API} ne protège pas contre l’appel d’une fonction avec des arguments qui sont invalides pour une version de Python plus ancienne. Par exemple considérons une fonction qui accepte @code{NULL} comme argument à partir de 3.9. @code{NULL} permet maintenant d’utiliser le comportement par défaut, mais Python 3.8 essayera d’accéder à l’objet pointé et dé-référencera @code{NULL}, causant un crash. Des problèmes similaires peuvent se produire avec les attributs des structures.

Un autre problème est que certains attributs ne sont pas encore cachés lorsque @code{Py_LIMITED_API} est défini, même s’ils ne font pas partie de l’API restreinte.

Pour ces raisons il est recommandé de tester une extension avec `l’ensemble des versions mineures' supportées de Python, et généralement de la compiler avec la plus `ancienne' de ces versions.

Il est aussi recommandé de vérifier la documentation de toutes les API utilisées pour vérifier qu’elles fassent bien partie de l’API restreinte. Même lorsque @code{Py_LIMITED_API} est défini quelques fonctions privées peuvent être exposées aux utilisateurs pour des raisons techniques, ou par erreur.

Notez aussi que l’API restreinte n’est pas forcément stable : compiler avec Python 3.8 en définissant @code{Py_LIMITED_API} garanti que l’extension fonctionnera avec Python 3.12, mais pas qu’elle pourra `être compilée' avec Python 3.12. En particulier certaines parties de l’API restreinte peuvent être dépréciées et retirées tant que l’ABI stable n’est pas modifiée.

@node Considérations relatives aux plateformes,Contenu de l’API restreinte,ABI stable,Stabilité de l’API C
@anchor{c-api/stable platform-considerations}@anchor{4865}@anchor{c-api/stable stable-abi-platform}@anchor{485c}
@subsection Considérations relatives aux plateformes


ABI stability depends not only on Python, but also on the compiler used,
lower-level libraries and compiler options. For the purposes of
the @ref{4861,,Stable ABI}, these details define a “platform”. They
usually depend on the OS type and processor architecture

Les distributeurs de Python doivent s’assurer que toutes les versions de Python pour une plateforme donnée sont compilées de manière à ne pas rompre la compatibilité de l’ABI stable. C’est le cas des versions produites pour Windows et macOS de @code{python.org} et de la plupart des distributions tierces.

@node Contenu de l’API restreinte,,Considérations relatives aux plateformes,Stabilité de l’API C
@anchor{c-api/stable contents-of-limited-api}@anchor{4866}@anchor{c-api/stable limited-api-list}@anchor{784}
@subsection Contenu de l’API restreinte


Currently, the @ref{38c,,Limited API} includes the following items:



@itemize *

@item 
@ref{549,,PY_VECTORCALL_ARGUMENTS_OFFSET}

@item 
@ref{4867,,PyAIter_Check()}

@item 
@ref{1972,,PyArg_Parse()}

@item 
@ref{55d,,PyArg_ParseTuple()}

@item 
@ref{379,,PyArg_ParseTupleAndKeywords()}

@item 
@ref{14be,,PyArg_UnpackTuple()}

@item 
@ref{4868,,PyArg_VaParse()}

@item 
@ref{37a,,PyArg_VaParseTupleAndKeywords()}

@item 
@ref{4869,,PyArg_ValidateKeywordArguments()}

@item 
@code{PyBaseObject_Type}

@item 
@ref{486a,,PyBool_FromLong()}

@item 
@ref{486b,,PyBool_Type}

@item 
@ref{749,,PyBuffer_FillContiguousStrides()}

@item 
@ref{74a,,PyBuffer_FillInfo()}

@item 
@ref{746,,PyBuffer_FromContiguous()}

@item 
@ref{743,,PyBuffer_GetPointer()}

@item 
@ref{748,,PyBuffer_IsContiguous()}

@item 
@ref{391,,PyBuffer_Release()}

@item 
@ref{744,,PyBuffer_SizeFromFormat()}

@item 
@ref{745,,PyBuffer_ToContiguous()}

@item 
@code{PyByteArrayIter_Type}

@item 
@ref{486c,,PyByteArray_AsString()}

@item 
@ref{486d,,PyByteArray_Concat()}

@item 
@ref{136d,,PyByteArray_FromObject()}

@item 
@ref{136e,,PyByteArray_FromStringAndSize()}

@item 
@ref{486e,,PyByteArray_Resize()}

@item 
@ref{486f,,PyByteArray_Size()}

@item 
@ref{4870,,PyByteArray_Type}

@item 
@code{PyBytesIter_Type}

@item 
@ref{873,,PyBytes_AsString()}

@item 
@ref{4871,,PyBytes_AsStringAndSize()}

@item 
@ref{4872,,PyBytes_Concat()}

@item 
@ref{4873,,PyBytes_ConcatAndDel()}

@item 
@code{PyBytes_DecodeEscape()}

@item 
@ref{19b7,,PyBytes_FromFormat()}

@item 
@ref{4874,,PyBytes_FromFormatV()}

@item 
@ref{4875,,PyBytes_FromObject()}

@item 
@ref{4876,,PyBytes_FromString()}

@item 
@ref{136c,,PyBytes_FromStringAndSize()}

@item 
@code{PyBytes_Repr()}

@item 
@ref{4877,,PyBytes_Size()}

@item 
@ref{4878,,PyBytes_Type}

@item 
@ref{142b,,PyCFunction}

@item 
@ref{4879,,PyCFunctionFast}

@item 
@ref{487a,,PyCFunctionFastWithKeywords}

@item 
@ref{487b,,PyCFunctionWithKeywords}

@item 
@code{PyCFunction_GetFlags()}

@item 
@code{PyCFunction_GetFunction()}

@item 
@code{PyCFunction_GetSelf()}

@item 
@ref{1881,,PyCFunction_New()}

@item 
@ref{191b,,PyCFunction_NewEx()}

@item 
@code{PyCFunction_Type}

@item 
@ref{187b,,PyCMethod_New()}

@item 
@ref{487c,,PyCallIter_New()}

@item 
@ref{487d,,PyCallIter_Type}

@item 
@ref{487e,,PyCallable_Check()}

@item 
@ref{487f,,PyCapsule_Destructor}

@item 
@ref{4880,,PyCapsule_GetContext()}

@item 
@ref{4881,,PyCapsule_GetDestructor()}

@item 
@ref{4882,,PyCapsule_GetName()}

@item 
@ref{4883,,PyCapsule_GetPointer()}

@item 
@ref{17fb,,PyCapsule_Import()}

@item 
@ref{1333,,PyCapsule_IsValid()}

@item 
@ref{47e3,,PyCapsule_New()}

@item 
@ref{4884,,PyCapsule_SetContext()}

@item 
@ref{4885,,PyCapsule_SetDestructor()}

@item 
@ref{4886,,PyCapsule_SetName()}

@item 
@ref{4887,,PyCapsule_SetPointer()}

@item 
@code{PyCapsule_Type}

@item 
@code{PyClassMethodDescr_Type}

@item 
@ref{4888,,PyCodec_BackslashReplaceErrors()}

@item 
@ref{3f5,,PyCodec_Decode()}

@item 
@ref{4889,,PyCodec_Decoder()}

@item 
@ref{3f6,,PyCodec_Encode()}

@item 
@ref{488a,,PyCodec_Encoder()}

@item 
@ref{488b,,PyCodec_IgnoreErrors()}

@item 
@ref{488c,,PyCodec_IncrementalDecoder()}

@item 
@ref{488d,,PyCodec_IncrementalEncoder()}

@item 
@ref{488e,,PyCodec_KnownEncoding()}

@item 
@ref{488f,,PyCodec_LookupError()}

@item 
@ref{e98,,PyCodec_NameReplaceErrors()}

@item 
@ref{4890,,PyCodec_Register()}

@item 
@ref{4891,,PyCodec_RegisterError()}

@item 
@ref{4892,,PyCodec_ReplaceErrors()}

@item 
@ref{4893,,PyCodec_StreamReader()}

@item 
@ref{4894,,PyCodec_StreamWriter()}

@item 
@ref{4895,,PyCodec_StrictErrors()}

@item 
@ref{883,,PyCodec_Unregister()}

@item 
@ref{4896,,PyCodec_XMLCharRefReplaceErrors()}

@item 
@ref{4897,,PyComplex_FromDoubles()}

@item 
@ref{1621,,PyComplex_ImagAsDouble()}

@item 
@ref{1620,,PyComplex_RealAsDouble()}

@item 
@ref{4898,,PyComplex_Type}

@item 
@ref{4899,,PyDescr_NewClassMethod()}

@item 
@ref{489a,,PyDescr_NewGetSet()}

@item 
@ref{489b,,PyDescr_NewMember()}

@item 
@ref{191a,,PyDescr_NewMethod()}

@item 
@code{PyDictItems_Type}

@item 
@code{PyDictIterItem_Type}

@item 
@code{PyDictIterKey_Type}

@item 
@code{PyDictIterValue_Type}

@item 
@code{PyDictKeys_Type}

@item 
@ref{489c,,PyDictProxy_New()}

@item 
@code{PyDictProxy_Type}

@item 
@code{PyDictRevIterItem_Type}

@item 
@code{PyDictRevIterKey_Type}

@item 
@code{PyDictRevIterValue_Type}

@item 
@code{PyDictValues_Type}

@item 
@ref{489d,,PyDict_Clear()}

@item 
@ref{32e,,PyDict_Contains()}

@item 
@ref{416,,PyDict_Copy()}

@item 
@ref{489e,,PyDict_DelItem()}

@item 
@ref{489f,,PyDict_DelItemString()}

@item 
@ref{37d,,PyDict_GetItem()}

@item 
@ref{330,,PyDict_GetItemRef()}

@item 
@ref{37e,,PyDict_GetItemString()}

@item 
@ref{331,,PyDict_GetItemStringRef()}

@item 
@ref{332,,PyDict_GetItemWithError()}

@item 
@ref{48a0,,PyDict_Items()}

@item 
@ref{48a1,,PyDict_Keys()}

@item 
@ref{48a2,,PyDict_Merge()}

@item 
@ref{48a3,,PyDict_MergeFromSeq2()}

@item 
@ref{48a4,,PyDict_New()}

@item 
@ref{159a,,PyDict_Next()}

@item 
@ref{47da,,PyDict_SetItem()}

@item 
@ref{1588,,PyDict_SetItemString()}

@item 
@ref{48a5,,PyDict_Size()}

@item 
@ref{48a6,,PyDict_Type}

@item 
@ref{48a7,,PyDict_Update()}

@item 
@ref{48a8,,PyDict_Values()}

@item 
@code{PyEllipsis_Type}

@item 
@code{PyEnum_Type}

@item 
@ref{48a9,,PyErr_BadArgument()}

@item 
@ref{48aa,,PyErr_BadInternalCall()}

@item 
@ref{450,,PyErr_CheckSignals()}

@item 
@ref{101a,,PyErr_Clear()}

@item 
@code{PyErr_Display()}

@item 
@ref{3f8,,PyErr_DisplayException()}

@item 
@ref{4854,,PyErr_ExceptionMatches()}

@item 
@ref{3e9,,PyErr_Fetch()}

@item 
@ref{e9a,,PyErr_Format()}

@item 
@ref{e99,,PyErr_FormatV()}

@item 
@ref{75c,,PyErr_GetExcInfo()}

@item 
@ref{759,,PyErr_GetHandledException()}

@item 
@ref{3ea,,PyErr_GetRaisedException()}

@item 
@ref{48ab,,PyErr_GivenExceptionMatches()}

@item 
@ref{1248,,PyErr_NewException()}

@item 
@ref{1247,,PyErr_NewExceptionWithDoc()}

@item 
@ref{47bd,,PyErr_NoMemory()}

@item 
@ref{3eb,,PyErr_NormalizeException()}

@item 
@ref{187f,,PyErr_Occurred()}

@item 
@ref{18d2,,PyErr_Print()}

@item 
@ref{48ac,,PyErr_PrintEx()}

@item 
@code{PyErr_ProgramText()}

@item 
@ref{d05,,PyErr_ResourceWarning()}

@item 
@ref{3ec,,PyErr_Restore()}

@item 
@ref{48ad,,PyErr_SetExcFromWindowsErr()}

@item 
@ref{16a2,,PyErr_SetExcFromWindowsErrWithFilename()}

@item 
@ref{48ae,,PyErr_SetExcFromWindowsErrWithFilenameObject()}

@item 
@ref{48af,,PyErr_SetExcFromWindowsErrWithFilenameObjects()}

@item 
@ref{75b,,PyErr_SetExcInfo()}

@item 
@ref{47bc,,PyErr_SetFromErrno()}

@item 
@ref{16a1,,PyErr_SetFromErrnoWithFilename()}

@item 
@ref{48b0,,PyErr_SetFromErrnoWithFilenameObject()}

@item 
@ref{48b1,,PyErr_SetFromErrnoWithFilenameObjects()}

@item 
@ref{48b2,,PyErr_SetFromWindowsErr()}

@item 
@ref{16a3,,PyErr_SetFromWindowsErrWithFilename()}

@item 
@ref{75a,,PyErr_SetHandledException()}

@item 
@ref{d2c,,PyErr_SetImportError()}

@item 
@ref{d04,,PyErr_SetImportErrorSubclass()}

@item 
@ref{48b3,,PyErr_SetInterrupt()}

@item 
@ref{88a,,PyErr_SetInterruptEx()}

@item 
@ref{48b4,,PyErr_SetNone()}

@item 
@ref{567,,PyErr_SetObject()}

@item 
@ref{3ed,,PyErr_SetRaisedException()}

@item 
@ref{568,,PyErr_SetString()}

@item 
@ref{48b5,,PyErr_SyntaxLocation()}

@item 
@ref{48b6,,PyErr_SyntaxLocationEx()}

@item 
@ref{1401,,PyErr_WarnEx()}

@item 
@ref{16aa,,PyErr_WarnExplicit()}

@item 
@ref{48b7,,PyErr_WarnFormat()}

@item 
@ref{345,,PyErr_WriteUnraisable()}

@item 
@ref{3a1,,PyEval_AcquireThread()}

@item 
@ref{872,,PyEval_EvalCode()}

@item 
@ref{16f7,,PyEval_EvalCodeEx()}

@item 
@ref{48b8,,PyEval_EvalFrame()}

@item 
@ref{1017,,PyEval_EvalFrameEx()}

@item 
@ref{347,,PyEval_GetBuiltins()}

@item 
@ref{174a,,PyEval_GetFrame()}

@item 
@ref{346,,PyEval_GetFrameBuiltins()}

@item 
@ref{348,,PyEval_GetFrameGlobals()}

@item 
@ref{34a,,PyEval_GetFrameLocals()}

@item 
@ref{48b9,,PyEval_GetFuncDesc()}

@item 
@ref{48ba,,PyEval_GetFuncName()}

@item 
@ref{349,,PyEval_GetGlobals()}

@item 
@ref{34b,,PyEval_GetLocals()}

@item 
@ref{15ca,,PyEval_InitThreads()}

@item 
@ref{48bb,,PyEval_ReleaseThread()}

@item 
@ref{3a0,,PyEval_RestoreThread()}

@item 
@ref{39f,,PyEval_SaveThread()}

@item 
@code{PyExc_ArithmeticError}

@item 
@code{PyExc_AssertionError}

@item 
@code{PyExc_AttributeError}

@item 
@code{PyExc_BaseException}

@item 
@code{PyExc_BaseExceptionGroup}

@item 
@code{PyExc_BlockingIOError}

@item 
@code{PyExc_BrokenPipeError}

@item 
@code{PyExc_BufferError}

@item 
@code{PyExc_BytesWarning}

@item 
@code{PyExc_ChildProcessError}

@item 
@code{PyExc_ConnectionAbortedError}

@item 
@code{PyExc_ConnectionError}

@item 
@code{PyExc_ConnectionRefusedError}

@item 
@code{PyExc_ConnectionResetError}

@item 
@code{PyExc_DeprecationWarning}

@item 
@code{PyExc_EOFError}

@item 
@code{PyExc_EncodingWarning}

@item 
@code{PyExc_EnvironmentError}

@item 
@code{PyExc_Exception}

@item 
@code{PyExc_FileExistsError}

@item 
@code{PyExc_FileNotFoundError}

@item 
@code{PyExc_FloatingPointError}

@item 
@code{PyExc_FutureWarning}

@item 
@code{PyExc_GeneratorExit}

@item 
@code{PyExc_IOError}

@item 
@code{PyExc_ImportError}

@item 
@code{PyExc_ImportWarning}

@item 
@code{PyExc_IndentationError}

@item 
@code{PyExc_IndexError}

@item 
@code{PyExc_InterruptedError}

@item 
@code{PyExc_IsADirectoryError}

@item 
@code{PyExc_KeyError}

@item 
@code{PyExc_KeyboardInterrupt}

@item 
@code{PyExc_LookupError}

@item 
@code{PyExc_MemoryError}

@item 
@code{PyExc_ModuleNotFoundError}

@item 
@code{PyExc_NameError}

@item 
@code{PyExc_NotADirectoryError}

@item 
@code{PyExc_NotImplementedError}

@item 
@code{PyExc_OSError}

@item 
@code{PyExc_OverflowError}

@item 
@code{PyExc_PendingDeprecationWarning}

@item 
@code{PyExc_PermissionError}

@item 
@code{PyExc_ProcessLookupError}

@item 
@code{PyExc_RecursionError}

@item 
@code{PyExc_ReferenceError}

@item 
@code{PyExc_ResourceWarning}

@item 
@code{PyExc_RuntimeError}

@item 
@code{PyExc_RuntimeWarning}

@item 
@code{PyExc_StopAsyncIteration}

@item 
@code{PyExc_StopIteration}

@item 
@code{PyExc_SyntaxError}

@item 
@code{PyExc_SyntaxWarning}

@item 
@code{PyExc_SystemError}

@item 
@code{PyExc_SystemExit}

@item 
@code{PyExc_TabError}

@item 
@code{PyExc_TimeoutError}

@item 
@code{PyExc_TypeError}

@item 
@code{PyExc_UnboundLocalError}

@item 
@code{PyExc_UnicodeDecodeError}

@item 
@code{PyExc_UnicodeEncodeError}

@item 
@code{PyExc_UnicodeError}

@item 
@code{PyExc_UnicodeTranslateError}

@item 
@code{PyExc_UnicodeWarning}

@item 
@code{PyExc_UserWarning}

@item 
@code{PyExc_ValueError}

@item 
@code{PyExc_Warning}

@item 
@code{PyExc_WindowsError}

@item 
@code{PyExc_ZeroDivisionError}

@item 
@code{PyExceptionClass_Name()}

@item 
@ref{556,,PyException_GetArgs()}

@item 
@ref{48bc,,PyException_GetCause()}

@item 
@ref{48bd,,PyException_GetContext()}

@item 
@ref{48be,,PyException_GetTraceback()}

@item 
@ref{557,,PyException_SetArgs()}

@item 
@ref{48bf,,PyException_SetCause()}

@item 
@ref{48c0,,PyException_SetContext()}

@item 
@ref{1978,,PyException_SetTraceback()}

@item 
@ref{48c1,,PyFile_FromFd()}

@item 
@ref{48c2,,PyFile_GetLine()}

@item 
@ref{48c3,,PyFile_WriteObject()}

@item 
@ref{48c4,,PyFile_WriteString()}

@item 
@code{PyFilter_Type}

@item 
@ref{a57,,PyFloat_AsDouble()}

@item 
@ref{48c5,,PyFloat_FromDouble()}

@item 
@ref{48c6,,PyFloat_FromString()}

@item 
@ref{13a7,,PyFloat_GetInfo()}

@item 
@ref{13a5,,PyFloat_GetMax()}

@item 
@ref{13a6,,PyFloat_GetMin()}

@item 
@ref{48c7,,PyFloat_Type}

@item 
@ref{773,,PyFrameObject}

@item 
@ref{774,,PyFrame_GetCode()}

@item 
@ref{775,,PyFrame_GetLineNumber()}

@item 
@ref{13fc,,PyFrozenSet_New()}

@item 
@ref{48c8,,PyFrozenSet_Type}

@item 
@ref{97b,,PyGC_Collect()}

@item 
@ref{891,,PyGC_Disable()}

@item 
@ref{890,,PyGC_Enable()}

@item 
@ref{892,,PyGC_IsEnabled()}

@item 
@ref{3a2,,PyGILState_Ensure()}

@item 
@ref{48c9,,PyGILState_GetThisThreadState()}

@item 
@ref{3a3,,PyGILState_Release()}

@item 
@code{PyGILState_STATE}

@item 
@ref{ba6,,PyGetSetDef}

@item 
@code{PyGetSetDescr_Type}

@item 
@ref{34f,,PyImport_AddModule()}

@item 
@ref{48ca,,PyImport_AddModuleObject()}

@item 
@ref{34e,,PyImport_AddModuleRef()}

@item 
@ref{1731,,PyImport_AppendInittab()}

@item 
@ref{48cb,,PyImport_ExecCodeModule()}

@item 
@ref{48cc,,PyImport_ExecCodeModuleEx()}

@item 
@ref{48cd,,PyImport_ExecCodeModuleObject()}

@item 
@ref{48ce,,PyImport_ExecCodeModuleWithPathnames()}

@item 
@ref{16a0,,PyImport_GetImporter()}

@item 
@ref{1181,,PyImport_GetMagicNumber()}

@item 
@ref{48cf,,PyImport_GetMagicTag()}

@item 
@ref{ba1,,PyImport_GetModule()}

@item 
@ref{48d0,,PyImport_GetModuleDict()}

@item 
@ref{13b3,,PyImport_Import()}

@item 
@ref{48d1,,PyImport_ImportFrozenModule()}

@item 
@ref{48d2,,PyImport_ImportFrozenModuleObject()}

@item 
@ref{3b5,,PyImport_ImportModule()}

@item 
@ref{1182,,PyImport_ImportModuleLevel()}

@item 
@ref{48d3,,PyImport_ImportModuleLevelObject()}

@item 
@ref{3b4,,PyImport_ImportModuleNoBlock()}

@item 
@ref{48d4,,PyImport_ReloadModule()}

@item 
@ref{977,,PyIndex_Check()}

@item 
@ref{8aa,,PyInterpreterState}

@item 
@ref{410f,,PyInterpreterState_Clear()}

@item 
@ref{48d5,,PyInterpreterState_Delete()}

@item 
@ref{3a4,,PyInterpreterState_Get()}

@item 
@ref{48d6,,PyInterpreterState_GetDict()}

@item 
@ref{bb4,,PyInterpreterState_GetID()}

@item 
@ref{4110,,PyInterpreterState_New()}

@item 
@ref{1882,,PyIter_Check()}

@item 
@ref{48d7,,PyIter_Next()}

@item 
@ref{884,,PyIter_Send()}

@item 
@code{PyListIter_Type}

@item 
@code{PyListRevIter_Type}

@item 
@ref{48d8,,PyList_Append()}

@item 
@ref{48d9,,PyList_AsTuple()}

@item 
@ref{352,,PyList_GetItem()}

@item 
@ref{351,,PyList_GetItemRef()}

@item 
@ref{48da,,PyList_GetSlice()}

@item 
@ref{48db,,PyList_Insert()}

@item 
@ref{484f,,PyList_New()}

@item 
@ref{48dc,,PyList_Reverse()}

@item 
@ref{47d9,,PyList_SetItem()}

@item 
@ref{48dd,,PyList_SetSlice()}

@item 
@ref{13d0,,PyList_Size()}

@item 
@ref{48de,,PyList_Sort()}

@item 
@ref{47fb,,PyList_Type}

@item 
@ref{574,,PyLongObject}

@item 
@code{PyLongRangeIter_Type}

@item 
@ref{48df,,PyLong_AsDouble()}

@item 
@ref{355,,PyLong_AsInt()}

@item 
@ref{356,,PyLong_AsLong()}

@item 
@ref{1245,,PyLong_AsLongAndOverflow()}

@item 
@ref{48e0,,PyLong_AsLongLong()}

@item 
@ref{1244,,PyLong_AsLongLongAndOverflow()}

@item 
@ref{48e1,,PyLong_AsSize_t()}

@item 
@ref{48e2,,PyLong_AsSsize_t()}

@item 
@ref{48e3,,PyLong_AsUnsignedLong()}

@item 
@ref{1272,,PyLong_AsUnsignedLongLong()}

@item 
@ref{1974,,PyLong_AsUnsignedLongLongMask()}

@item 
@ref{48e4,,PyLong_AsUnsignedLongMask()}

@item 
@ref{48e5,,PyLong_AsVoidPtr()}

@item 
@ref{92f,,PyLong_FromDouble()}

@item 
@ref{17c7,,PyLong_FromLong()}

@item 
@ref{17c8,,PyLong_FromLongLong()}

@item 
@ref{1951,,PyLong_FromSize_t()}

@item 
@ref{48e6,,PyLong_FromSsize_t()}

@item 
@ref{48e7,,PyLong_FromString()}

@item 
@ref{194f,,PyLong_FromUnsignedLong()}

@item 
@ref{1950,,PyLong_FromUnsignedLongLong()}

@item 
@ref{48e8,,PyLong_FromVoidPtr()}

@item 
@ref{48e9,,PyLong_GetInfo()}

@item 
@ref{48ea,,PyLong_Type}

@item 
@code{PyMap_Type}

@item 
@ref{48eb,,PyMapping_Check()}

@item 
@ref{33e,,PyMapping_GetItemString()}

@item 
@ref{33b,,PyMapping_GetOptionalItem()}

@item 
@ref{33c,,PyMapping_GetOptionalItemString()}

@item 
@ref{375,,PyMapping_HasKey()}

@item 
@ref{377,,PyMapping_HasKeyString()}

@item 
@ref{376,,PyMapping_HasKeyStringWithError()}

@item 
@ref{374,,PyMapping_HasKeyWithError()}

@item 
@ref{bac,,PyMapping_Items()}

@item 
@ref{baa,,PyMapping_Keys()}

@item 
@ref{48ec,,PyMapping_Length()}

@item 
@ref{48ed,,PyMapping_SetItemString()}

@item 
@ref{19e4,,PyMapping_Size()}

@item 
@ref{bab,,PyMapping_Values()}

@item 
@ref{e96,,PyMem_Calloc()}

@item 
@ref{13f9,,PyMem_Free()}

@item 
@ref{c54,,PyMem_Malloc()}

@item 
@ref{387,,PyMem_RawCalloc()}

@item 
@ref{389,,PyMem_RawFree()}

@item 
@ref{386,,PyMem_RawMalloc()}

@item 
@ref{388,,PyMem_RawRealloc()}

@item 
@ref{101b,,PyMem_Realloc()}

@item 
@ref{53a,,PyMemberDef}

@item 
@code{PyMemberDescr_Type}

@item 
@ref{579,,PyMember_GetOne()}

@item 
@ref{57a,,PyMember_SetOne()}

@item 
@ref{74b,,PyMemoryView_FromBuffer()}

@item 
@ref{1150,,PyMemoryView_FromMemory()}

@item 
@ref{48ee,,PyMemoryView_FromObject()}

@item 
@ref{48ef,,PyMemoryView_GetContiguous()}

@item 
@code{PyMemoryView_Type}

@item 
@ref{148d,,PyMethodDef}

@item 
@code{PyMethodDescr_Type}

@item 
@ref{96a,,PyModuleDef}

@item 
@code{PyModuleDef_Base}

@item 
@ref{48f0,,PyModuleDef_Init()}

@item 
@code{PyModuleDef_Type}

@item 
@ref{35a,,PyModule_Add()}

@item 
@ref{48f1,,PyModule_AddFunctions()}

@item 
@ref{14f2,,PyModule_AddIntConstant()}

@item 
@ref{35c,,PyModule_AddObject()}

@item 
@ref{35b,,PyModule_AddObjectRef()}

@item 
@ref{14f3,,PyModule_AddStringConstant()}

@item 
@ref{962,,PyModule_AddType()}

@item 
@ref{48f2,,PyModule_Create2()}

@item 
@ref{e9d,,PyModule_ExecDef()}

@item 
@ref{e9c,,PyModule_FromDefAndSpec2()}

@item 
@ref{48f3,,PyModule_GetDef()}

@item 
@ref{48f4,,PyModule_GetDict()}

@item 
@ref{3ee,,PyModule_GetFilename()}

@item 
@ref{3ef,,PyModule_GetFilenameObject()}

@item 
@ref{48f5,,PyModule_GetName()}

@item 
@ref{48f6,,PyModule_GetNameObject()}

@item 
@ref{96d,,PyModule_GetState()}

@item 
@ref{48f7,,PyModule_New()}

@item 
@ref{48f8,,PyModule_NewObject()}

@item 
@ref{48f9,,PyModule_SetDocString()}

@item 
@ref{48fa,,PyModule_Type}

@item 
@ref{48fb,,PyNumber_Absolute()}

@item 
@ref{48fc,,PyNumber_Add()}

@item 
@ref{48fd,,PyNumber_And()}

@item 
@ref{48fe,,PyNumber_AsSsize_t()}

@item 
@ref{a54,,PyNumber_Check()}

@item 
@ref{48ff,,PyNumber_Divmod()}

@item 
@ref{a56,,PyNumber_Float()}

@item 
@ref{4900,,PyNumber_FloorDivide()}

@item 
@ref{4901,,PyNumber_InPlaceAdd()}

@item 
@ref{4902,,PyNumber_InPlaceAnd()}

@item 
@ref{4903,,PyNumber_InPlaceFloorDivide()}

@item 
@ref{4904,,PyNumber_InPlaceLshift()}

@item 
@ref{e9f,,PyNumber_InPlaceMatrixMultiply()}

@item 
@ref{4905,,PyNumber_InPlaceMultiply()}

@item 
@ref{4906,,PyNumber_InPlaceOr()}

@item 
@ref{4907,,PyNumber_InPlacePower()}

@item 
@ref{4908,,PyNumber_InPlaceRemainder()}

@item 
@ref{4909,,PyNumber_InPlaceRshift()}

@item 
@ref{490a,,PyNumber_InPlaceSubtract()}

@item 
@ref{490b,,PyNumber_InPlaceTrueDivide()}

@item 
@ref{490c,,PyNumber_InPlaceXor()}

@item 
@ref{87f,,PyNumber_Index()}

@item 
@ref{490d,,PyNumber_Invert()}

@item 
@ref{a55,,PyNumber_Long()}

@item 
@ref{490e,,PyNumber_Lshift()}

@item 
@ref{e9e,,PyNumber_MatrixMultiply()}

@item 
@ref{490f,,PyNumber_Multiply()}

@item 
@ref{4910,,PyNumber_Negative()}

@item 
@ref{4911,,PyNumber_Or()}

@item 
@ref{4912,,PyNumber_Positive()}

@item 
@ref{4913,,PyNumber_Power()}

@item 
@ref{4914,,PyNumber_Remainder()}

@item 
@ref{4915,,PyNumber_Rshift()}

@item 
@ref{4916,,PyNumber_Subtract()}

@item 
@ref{1778,,PyNumber_ToBase()}

@item 
@ref{4917,,PyNumber_TrueDivide()}

@item 
@ref{4918,,PyNumber_Xor()}

@item 
@ref{3f0,,PyOS_AfterFork()}

@item 
@ref{3f1,,PyOS_AfterFork_Child()}

@item 
@ref{bae,,PyOS_AfterFork_Parent()}

@item 
@ref{bad,,PyOS_BeforeFork()}

@item 
@ref{17a4,,PyOS_CheckStack()}

@item 
@ref{d06,,PyOS_FSPath()}

@item 
@ref{571,,PyOS_InputHook}

@item 
@code{PyOS_InterruptOccurred()}

@item 
@ref{4919,,PyOS_double_to_string()}

@item 
@ref{14f4,,PyOS_getsig()}

@item 
@code{PyOS_mystricmp()}

@item 
@code{PyOS_mystrnicmp()}

@item 
@ref{14f5,,PyOS_setsig()}

@item 
@ref{491a,,PyOS_sighandler_t}

@item 
@ref{14c1,,PyOS_snprintf()}

@item 
@ref{1273,,PyOS_string_to_double()}

@item 
@ref{491b,,PyOS_strtol()}

@item 
@ref{491c,,PyOS_strtoul()}

@item 
@ref{14c2,,PyOS_vsnprintf()}

@item 
@ref{32f,,PyObject}

@item 
@ref{88b,,PyObject.ob_refcnt}

@item 
@ref{47ec,,PyObject.ob_type}

@item 
@ref{491d,,PyObject_ASCII()}

@item 
@ref{491e,,PyObject_AsFileDescriptor()}

@item 
@ref{491f,,PyObject_Bytes()}

@item 
@ref{393,,PyObject_Call()}

@item 
@ref{395,,PyObject_CallFunction()}

@item 
@ref{4920,,PyObject_CallFunctionObjArgs()}

@item 
@ref{396,,PyObject_CallMethod()}

@item 
@ref{198b,,PyObject_CallMethodObjArgs()}

@item 
@ref{392,,PyObject_CallNoArgs()}

@item 
@ref{47cc,,PyObject_CallObject()}

@item 
@ref{e97,,PyObject_Calloc()}

@item 
@ref{38f,,PyObject_CheckBuffer()}

@item 
@ref{562,,PyObject_ClearWeakRefs()}

@item 
@ref{747,,PyObject_CopyData()}

@item 
@ref{16a7,,PyObject_DelAttr()}

@item 
@ref{158a,,PyObject_DelAttrString()}

@item 
@ref{4921,,PyObject_DelItem()}

@item 
@ref{4922,,PyObject_DelItemString()}

@item 
@ref{4923,,PyObject_Dir()}

@item 
@ref{4924,,PyObject_Format()}

@item 
@ref{c53,,PyObject_Free()}

@item 
@ref{14bb,,PyObject_GC_Del()}

@item 
@ref{964,,PyObject_GC_IsFinalized()}

@item 
@ref{963,,PyObject_GC_IsTracked()}

@item 
@ref{14bc,,PyObject_GC_Track()}

@item 
@ref{14bd,,PyObject_GC_UnTrack()}

@item 
@ref{4925,,PyObject_GenericGetAttr()}

@item 
@ref{18c7,,PyObject_GenericGetDict()}

@item 
@ref{4926,,PyObject_GenericSetAttr()}

@item 
@ref{4927,,PyObject_GenericSetDict()}

@item 
@ref{4928,,PyObject_GetAIter()}

@item 
@ref{341,,PyObject_GetAttr()}

@item 
@ref{342,,PyObject_GetAttrString()}

@item 
@ref{390,,PyObject_GetBuffer()}

@item 
@ref{33d,,PyObject_GetItem()}

@item 
@ref{4929,,PyObject_GetIter()}

@item 
@ref{33f,,PyObject_GetOptionalAttr()}

@item 
@ref{340,,PyObject_GetOptionalAttrString()}

@item 
@ref{534,,PyObject_GetTypeData()}

@item 
@ref{371,,PyObject_HasAttr()}

@item 
@ref{373,,PyObject_HasAttrString()}

@item 
@ref{372,,PyObject_HasAttrStringWithError()}

@item 
@ref{370,,PyObject_HasAttrWithError()}

@item 
@ref{3f9,,PyObject_Hash()}

@item 
@ref{137d,,PyObject_HashNotImplemented()}

@item 
@ref{a58,,PyObject_Init()}

@item 
@ref{18e2,,PyObject_InitVar()}

@item 
@ref{e8f,,PyObject_IsInstance()}

@item 
@ref{e90,,PyObject_IsSubclass()}

@item 
@ref{492a,,PyObject_IsTrue()}

@item 
@ref{492b,,PyObject_Length()}

@item 
@ref{c56,,PyObject_Malloc()}

@item 
@ref{492c,,PyObject_Not()}

@item 
@ref{13fa,,PyObject_Realloc()}

@item 
@ref{1018,,PyObject_Repr()}

@item 
@ref{4810,,PyObject_RichCompare()}

@item 
@ref{1931,,PyObject_RichCompareBool()}

@item 
@ref{492d,,PyObject_SelfIter()}

@item 
@ref{492e,,PyObject_SetAttr()}

@item 
@ref{1589,,PyObject_SetAttrString()}

@item 
@ref{484e,,PyObject_SetItem()}

@item 
@ref{492f,,PyObject_Size()}

@item 
@ref{1019,,PyObject_Str()}

@item 
@ref{4930,,PyObject_Type()}

@item 
@ref{547,,PyObject_Vectorcall()}

@item 
@ref{548,,PyObject_VectorcallMethod()}

@item 
@ref{4931,,PyProperty_Type}

@item 
@code{PyRangeIter_Type}

@item 
@code{PyRange_Type}

@item 
@code{PyReversed_Type}

@item 
@ref{4932,,PySeqIter_New()}

@item 
@ref{4933,,PySeqIter_Type}

@item 
@ref{4934,,PySequence_Check()}

@item 
@ref{4935,,PySequence_Concat()}

@item 
@ref{4936,,PySequence_Contains()}

@item 
@ref{4937,,PySequence_Count()}

@item 
@ref{19e3,,PySequence_DelItem()}

@item 
@ref{4938,,PySequence_DelSlice()}

@item 
@ref{4939,,PySequence_Fast()}

@item 
@ref{19e1,,PySequence_GetItem()}

@item 
@ref{493a,,PySequence_GetSlice()}

@item 
@code{PySequence_In()}

@item 
@ref{493b,,PySequence_InPlaceConcat()}

@item 
@ref{493c,,PySequence_InPlaceRepeat()}

@item 
@ref{493d,,PySequence_Index()}

@item 
@ref{493e,,PySequence_Length()}

@item 
@ref{493f,,PySequence_List()}

@item 
@ref{4940,,PySequence_Repeat()}

@item 
@ref{19e2,,PySequence_SetItem()}

@item 
@ref{4941,,PySequence_SetSlice()}

@item 
@ref{19e0,,PySequence_Size()}

@item 
@ref{4942,,PySequence_Tuple()}

@item 
@code{PySetIter_Type}

@item 
@ref{13fd,,PySet_Add()}

@item 
@ref{4943,,PySet_Clear()}

@item 
@ref{13ff,,PySet_Contains()}

@item 
@ref{13fe,,PySet_Discard()}

@item 
@ref{13fb,,PySet_New()}

@item 
@ref{4944,,PySet_Pop()}

@item 
@ref{1400,,PySet_Size()}

@item 
@ref{4945,,PySet_Type}

@item 
@ref{3f4,,PySlice_AdjustIndices()}

@item 
@ref{4946,,PySlice_GetIndices()}

@item 
@ref{3f2,,PySlice_GetIndicesEx()}

@item 
@ref{4947,,PySlice_New()}

@item 
@ref{4948,,PySlice_Type}

@item 
@ref{3f3,,PySlice_Unpack()}

@item 
@ref{4949,,PyState_AddModule()}

@item 
@ref{494a,,PyState_FindModule()}

@item 
@ref{494b,,PyState_RemoveModule()}

@item 
@ref{ba8,,PyStructSequence_Desc}

@item 
@ref{ba7,,PyStructSequence_Field}

@item 
@ref{494c,,PyStructSequence_GetItem()}

@item 
@ref{494d,,PyStructSequence_New()}

@item 
@ref{494e,,PyStructSequence_NewType()}

@item 
@ref{494f,,PyStructSequence_SetItem()}

@item 
@ref{96f,,PyStructSequence_UnnamedField}

@item 
@code{PySuper_Type}

@item 
@ref{365,,PySys_Audit()}

@item 
@ref{364,,PySys_AuditTuple()}

@item 
@ref{4950,,PySys_FormatStderr()}

@item 
@ref{4951,,PySys_FormatStdout()}

@item 
@ref{37f,,PySys_GetObject()}

@item 
@ref{4952,,PySys_GetXOptions()}

@item 
@ref{3a6,,PySys_ResetWarnOptions()}

@item 
@ref{15c9,,PySys_SetArgv()}

@item 
@ref{15c8,,PySys_SetArgvEx()}

@item 
@ref{4953,,PySys_SetObject()}

@item 
@ref{4954,,PySys_WriteStderr()}

@item 
@ref{4955,,PySys_WriteStdout()}

@item 
@ref{777,,PyThreadState}

@item 
@ref{15aa,,PyThreadState_Clear()}

@item 
@ref{192e,,PyThreadState_Delete()}

@item 
@ref{368,,PyThreadState_Get()}

@item 
@ref{4956,,PyThreadState_GetDict()}

@item 
@ref{778,,PyThreadState_GetFrame()}

@item 
@ref{95f,,PyThreadState_GetID()}

@item 
@ref{95e,,PyThreadState_GetInterpreter()}

@item 
@ref{4957,,PyThreadState_New()}

@item 
@ref{bb2,,PyThreadState_SetAsyncExc()}

@item 
@ref{4958,,PyThreadState_Swap()}

@item 
@code{PyThread_GetInfo()}

@item 
@ref{404,,PyThread_ReInitTLS()}

@item 
@code{PyThread_acquire_lock()}

@item 
@code{PyThread_acquire_lock_timed()}

@item 
@code{PyThread_allocate_lock()}

@item 
@ref{3fa,,PyThread_create_key()}

@item 
@ref{3fc,,PyThread_delete_key()}

@item 
@ref{402,,PyThread_delete_key_value()}

@item 
@code{PyThread_exit_thread()}

@item 
@code{PyThread_free_lock()}

@item 
@ref{400,,PyThread_get_key_value()}

@item 
@code{PyThread_get_stacksize()}

@item 
@code{PyThread_get_thread_ident()}

@item 
@code{PyThread_get_thread_native_id()}

@item 
@code{PyThread_init_thread()}

@item 
@code{PyThread_release_lock()}

@item 
@ref{3fe,,PyThread_set_key_value()}

@item 
@code{PyThread_set_stacksize()}

@item 
@code{PyThread_start_new_thread()}

@item 
@ref{3fb,,PyThread_tss_alloc()}

@item 
@ref{4959,,PyThread_tss_create()}

@item 
@ref{403,,PyThread_tss_delete()}

@item 
@ref{3fd,,PyThread_tss_free()}

@item 
@ref{401,,PyThread_tss_get()}

@item 
@ref{495a,,PyThread_tss_is_created()}

@item 
@ref{3ff,,PyThread_tss_set()}

@item 
@code{PyTraceBack_Here()}

@item 
@code{PyTraceBack_Print()}

@item 
@code{PyTraceBack_Type}

@item 
@code{PyTupleIter_Type}

@item 
@ref{47d7,,PyTuple_GetItem()}

@item 
@ref{495b,,PyTuple_GetSlice()}

@item 
@ref{394,,PyTuple_New()}

@item 
@ref{495c,,PyTuple_Pack()}

@item 
@ref{47d8,,PyTuple_SetItem()}

@item 
@ref{495d,,PyTuple_Size()}

@item 
@ref{495e,,PyTuple_Type}

@item 
@ref{a93,,PyTypeObject}

@item 
@ref{495f,,PyType_ClearCache()}

@item 
@ref{53b,,PyType_FromMetaclass()}

@item 
@ref{53c,,PyType_FromModuleAndSpec()}

@item 
@ref{569,,PyType_FromSpec()}

@item 
@ref{56a,,PyType_FromSpecWithBases()}

@item 
@ref{a59,,PyType_GenericAlloc()}

@item 
@ref{47eb,,PyType_GenericNew()}

@item 
@ref{18e1,,PyType_GetFlags()}

@item 
@ref{369,,PyType_GetFullyQualifiedName()}

@item 
@ref{95b,,PyType_GetModule()}

@item 
@ref{38a,,PyType_GetModuleByDef()}

@item 
@ref{36b,,PyType_GetModuleName()}

@item 
@ref{95c,,PyType_GetModuleState()}

@item 
@ref{73c,,PyType_GetName()}

@item 
@ref{73d,,PyType_GetQualName()}

@item 
@ref{888,,PyType_GetSlot()}

@item 
@ref{535,,PyType_GetTypeDataSize()}

@item 
@ref{4960,,PyType_IsSubtype()}

@item 
@ref{1780,,PyType_Modified()}

@item 
@ref{766,,PyType_Ready()}

@item 
@ref{4961,,PyType_Slot}

@item 
@ref{16a5,,PyType_Spec}

@item 
@ref{538,,PyType_Type}

@item 
@ref{4962,,PyUnicodeDecodeError_Create()}

@item 
@ref{4963,,PyUnicodeDecodeError_GetEncoding()}

@item 
@ref{4964,,PyUnicodeDecodeError_GetEnd()}

@item 
@ref{4965,,PyUnicodeDecodeError_GetObject()}

@item 
@ref{4966,,PyUnicodeDecodeError_GetReason()}

@item 
@ref{4967,,PyUnicodeDecodeError_GetStart()}

@item 
@ref{4968,,PyUnicodeDecodeError_SetEnd()}

@item 
@ref{4969,,PyUnicodeDecodeError_SetReason()}

@item 
@ref{496a,,PyUnicodeDecodeError_SetStart()}

@item 
@ref{496b,,PyUnicodeEncodeError_GetEncoding()}

@item 
@ref{496c,,PyUnicodeEncodeError_GetEnd()}

@item 
@ref{496d,,PyUnicodeEncodeError_GetObject()}

@item 
@ref{496e,,PyUnicodeEncodeError_GetReason()}

@item 
@ref{496f,,PyUnicodeEncodeError_GetStart()}

@item 
@ref{4970,,PyUnicodeEncodeError_SetEnd()}

@item 
@ref{4971,,PyUnicodeEncodeError_SetReason()}

@item 
@ref{4972,,PyUnicodeEncodeError_SetStart()}

@item 
@code{PyUnicodeIter_Type}

@item 
@ref{4973,,PyUnicodeTranslateError_GetEnd()}

@item 
@ref{4974,,PyUnicodeTranslateError_GetObject()}

@item 
@ref{4975,,PyUnicodeTranslateError_GetReason()}

@item 
@ref{4976,,PyUnicodeTranslateError_GetStart()}

@item 
@ref{4977,,PyUnicodeTranslateError_SetEnd()}

@item 
@ref{4978,,PyUnicodeTranslateError_SetReason()}

@item 
@ref{4979,,PyUnicodeTranslateError_SetStart()}

@item 
@code{PyUnicode_Append()}

@item 
@code{PyUnicode_AppendAndDel()}

@item 
@ref{1172,,PyUnicode_AsASCIIString()}

@item 
@ref{497a,,PyUnicode_AsCharmapString()}

@item 
@code{PyUnicode_AsDecodedObject()}

@item 
@code{PyUnicode_AsDecodedUnicode()}

@item 
@code{PyUnicode_AsEncodedObject()}

@item 
@ref{497b,,PyUnicode_AsEncodedString()}

@item 
@code{PyUnicode_AsEncodedUnicode()}

@item 
@ref{1171,,PyUnicode_AsLatin1String()}

@item 
@ref{1173,,PyUnicode_AsMBCSString()}

@item 
@ref{1170,,PyUnicode_AsRawUnicodeEscapeString()}

@item 
@ref{1158,,PyUnicode_AsUCS4()}

@item 
@ref{8a8,,PyUnicode_AsUCS4Copy()}

@item 
@ref{497c,,PyUnicode_AsUTF16String()}

@item 
@ref{497d,,PyUnicode_AsUTF32String()}

@item 
@ref{885,,PyUnicode_AsUTF8AndSize()}

@item 
@ref{116e,,PyUnicode_AsUTF8String()}

@item 
@ref{116f,,PyUnicode_AsUnicodeEscapeString()}

@item 
@ref{19e5,,PyUnicode_AsWideChar()}

@item 
@ref{8a9,,PyUnicode_AsWideCharString()}

@item 
@code{PyUnicode_BuildEncodingMap()}

@item 
@ref{8a4,,PyUnicode_Compare()}

@item 
@ref{1246,,PyUnicode_CompareWithASCIIString()}

@item 
@ref{117f,,PyUnicode_Concat()}

@item 
@ref{497e,,PyUnicode_Contains()}

@item 
@ref{497f,,PyUnicode_Count()}

@item 
@ref{1970,,PyUnicode_Decode()}

@item 
@ref{4980,,PyUnicode_DecodeASCII()}

@item 
@ref{4981,,PyUnicode_DecodeCharmap()}

@item 
@code{PyUnicode_DecodeCodePageStateful()}

@item 
@ref{16a4,,PyUnicode_DecodeFSDefault()}

@item 
@ref{4982,,PyUnicode_DecodeFSDefaultAndSize()}

@item 
@ref{4983,,PyUnicode_DecodeLatin1()}

@item 
@ref{4984,,PyUnicode_DecodeLocale()}

@item 
@ref{bb7,,PyUnicode_DecodeLocaleAndSize()}

@item 
@ref{4985,,PyUnicode_DecodeMBCS()}

@item 
@ref{4986,,PyUnicode_DecodeMBCSStateful()}

@item 
@ref{4987,,PyUnicode_DecodeRawUnicodeEscape()}

@item 
@ref{4988,,PyUnicode_DecodeUTF16()}

@item 
@ref{4989,,PyUnicode_DecodeUTF16Stateful()}

@item 
@ref{498a,,PyUnicode_DecodeUTF32()}

@item 
@ref{498b,,PyUnicode_DecodeUTF32Stateful()}

@item 
@ref{498c,,PyUnicode_DecodeUTF7()}

@item 
@ref{498d,,PyUnicode_DecodeUTF7Stateful()}

@item 
@ref{498e,,PyUnicode_DecodeUTF8()}

@item 
@ref{172d,,PyUnicode_DecodeUTF8Stateful()}

@item 
@ref{498f,,PyUnicode_DecodeUnicodeEscape()}

@item 
@ref{1174,,PyUnicode_EncodeCodePage()}

@item 
@ref{19df,,PyUnicode_EncodeFSDefault()}

@item 
@ref{bb8,,PyUnicode_EncodeLocale()}

@item 
@ref{36d,,PyUnicode_EqualToUTF8()}

@item 
@ref{36c,,PyUnicode_EqualToUTF8AndSize()}

@item 
@ref{d07,,PyUnicode_FSConverter()}

@item 
@ref{563,,PyUnicode_FSDecoder()}

@item 
@ref{4990,,PyUnicode_Find()}

@item 
@ref{8a6,,PyUnicode_FindChar()}

@item 
@ref{4991,,PyUnicode_Format()}

@item 
@ref{4992,,PyUnicode_FromEncodedObject()}

@item 
@ref{380,,PyUnicode_FromFormat()}

@item 
@ref{560,,PyUnicode_FromFormatV()}

@item 
@ref{4993,,PyUnicode_FromObject()}

@item 
@code{PyUnicode_FromOrdinal()}

@item 
@ref{4832,,PyUnicode_FromString()}

@item 
@ref{4994,,PyUnicode_FromStringAndSize()}

@item 
@ref{116c,,PyUnicode_FromWideChar()}

@item 
@code{PyUnicode_GetDefaultEncoding()}

@item 
@ref{8a0,,PyUnicode_GetLength()}

@item 
@ref{1587,,PyUnicode_InternFromString()}

@item 
@ref{89e,,PyUnicode_InternInPlace()}

@item 
@ref{192b,,PyUnicode_IsIdentifier()}

@item 
@ref{1180,,PyUnicode_Join()}

@item 
@code{PyUnicode_Partition()}

@item 
@code{PyUnicode_RPartition()}

@item 
@code{PyUnicode_RSplit()}

@item 
@ref{1151,,PyUnicode_ReadChar()}

@item 
@ref{4995,,PyUnicode_Replace()}

@item 
@code{PyUnicode_Resize()}

@item 
@ref{4996,,PyUnicode_RichCompare()}

@item 
@ref{4997,,PyUnicode_Split()}

@item 
@ref{4998,,PyUnicode_Splitlines()}

@item 
@ref{8a3,,PyUnicode_Substring()}

@item 
@ref{8a5,,PyUnicode_Tailmatch()}

@item 
@ref{4999,,PyUnicode_Translate()}

@item 
@ref{499a,,PyUnicode_Type}

@item 
@ref{1152,,PyUnicode_WriteChar()}

@item 
@ref{4094,,PyVarObject}

@item 
@code{PyVarObject.ob_base}

@item 
@ref{499b,,PyVarObject.ob_size}

@item 
@ref{541,,PyVectorcall_Call()}

@item 
@ref{540,,PyVectorcall_NARGS()}

@item 
@code{PyWeakReference}

@item 
@ref{36f,,PyWeakref_GetObject()}

@item 
@ref{36e,,PyWeakref_GetRef()}

@item 
@ref{499c,,PyWeakref_NewProxy()}

@item 
@ref{17dc,,PyWeakref_NewRef()}

@item 
@code{PyWrapperDescr_Type}

@item 
@ref{499d,,PyWrapper_New()}

@item 
@code{PyZip_Type}

@item 
@ref{96e,,Py_AddPendingCall()}

@item 
@ref{499e,,Py_AtExit()}

@item 
@ref{47dd,,Py_BEGIN_ALLOW_THREADS}

@item 
@ref{499f,,Py_BLOCK_THREADS}

@item 
@ref{894,,Py_BuildValue()}

@item 
@ref{9af,,Py_BytesMain()}

@item 
@ref{871,,Py_CompileString()}

@item 
@ref{49a0,,Py_DecRef()}

@item 
@ref{bb5,,Py_DecodeLocale()}

@item 
@ref{a7c,,Py_END_ALLOW_THREADS}

@item 
@ref{bb6,,Py_EncodeLocale()}

@item 
@ref{17ed,,Py_EndInterpreter()}

@item 
@ref{960,,Py_EnterRecursiveCall()}

@item 
@ref{d3c,,Py_Exit()}

@item 
@ref{970,,Py_FatalError()}

@item 
@code{Py_FileSystemDefaultEncodeErrors}

@item 
@code{Py_FileSystemDefaultEncoding}

@item 
@ref{1330,,Py_Finalize()}

@item 
@ref{d03,,Py_FinalizeEx()}

@item 
@ref{49a1,,Py_GenericAlias()}

@item 
@ref{49a2,,Py_GenericAliasType}

@item 
@ref{13e8,,Py_GetBuildInfo()}

@item 
@ref{49a3,,Py_GetCompiler()}

@item 
@ref{34c,,Py_GetConstant()}

@item 
@ref{34d,,Py_GetConstantBorrowed()}

@item 
@ref{49a4,,Py_GetCopyright()}

@item 
@ref{3a8,,Py_GetExecPrefix()}

@item 
@ref{3aa,,Py_GetPath()}

@item 
@ref{49a5,,Py_GetPlatform()}

@item 
@ref{3ac,,Py_GetPrefix()}

@item 
@ref{3ae,,Py_GetProgramFullPath()}

@item 
@ref{3b0,,Py_GetProgramName()}

@item 
@ref{3b1,,Py_GetPythonHome()}

@item 
@code{Py_GetRecursionLimit()}

@item 
@ref{49a6,,Py_GetVersion()}

@item 
@code{Py_HasFileSystemDefaultEncoding}

@item 
@ref{49a7,,Py_IncRef()}

@item 
@ref{899,,Py_Initialize()}

@item 
@ref{49a8,,Py_InitializeEx()}

@item 
@ref{88c,,Py_Is()}

@item 
@ref{88f,,Py_IsFalse()}

@item 
@ref{350,,Py_IsFinalizing()}

@item 
@ref{4857,,Py_IsInitialized()}

@item 
@ref{88d,,Py_IsNone()}

@item 
@ref{88e,,Py_IsTrue()}

@item 
@ref{961,,Py_LeaveRecursiveCall()}

@item 
@ref{c13,,Py_Main()}

@item 
@code{Py_MakePendingCalls()}

@item 
@ref{1744,,Py_NewInterpreter()}

@item 
@ref{886,,Py_NewRef()}

@item 
@ref{49a9,,Py_ReprEnter()}

@item 
@ref{49aa,,Py_ReprLeave()}

@item 
@ref{15c7,,Py_SetProgramName()}

@item 
@ref{15c6,,Py_SetPythonHome()}

@item 
@code{Py_SetRecursionLimit()}

@item 
@ref{298,,Py_UCS4}

@item 
@ref{49ab,,Py_UNBLOCK_THREADS}

@item 
@code{Py_UTF8Mode}

@item 
@ref{49ac,,Py_VaBuildValue()}

@item 
@ref{740,,Py_Version}

@item 
@ref{887,,Py_XNewRef()}

@item 
@ref{742,,Py_buffer}

@item 
@code{Py_intptr_t}

@item 
@ref{a4e,,Py_ssize_t}

@item 
@code{Py_uintptr_t}

@item 
@ref{49ad,,allocfunc}

@item 
@ref{49ae,,binaryfunc}

@item 
@ref{49af,,descrgetfunc}

@item 
@ref{49b0,,descrsetfunc}

@item 
@ref{49b1,,destructor}

@item 
@ref{49b2,,getattrfunc}

@item 
@ref{49b3,,getattrofunc}

@item 
@ref{49b4,,getbufferproc}

@item 
@ref{49b5,,getiterfunc}

@item 
@ref{49b6,,getter}

@item 
@ref{49b7,,hashfunc}

@item 
@ref{49b8,,initproc}

@item 
@ref{49b9,,inquiry}

@item 
@ref{49ba,,iternextfunc}

@item 
@ref{49bb,,lenfunc}

@item 
@ref{49bc,,newfunc}

@item 
@ref{49bd,,objobjargproc}

@item 
@ref{49be,,objobjproc}

@item 
@ref{49bf,,releasebufferproc}

@item 
@ref{49c0,,reprfunc}

@item 
@ref{49c1,,richcmpfunc}

@item 
@ref{49c2,,setattrfunc}

@item 
@ref{49c3,,setattrofunc}

@item 
@ref{49c4,,setter}

@item 
@ref{49c5,,ssizeargfunc}

@item 
@ref{49c6,,ssizeobjargproc}

@item 
@code{ssizessizeargfunc}

@item 
@code{ssizessizeobjargproc}

@item 
@code{symtable}

@item 
@ref{49c7,,ternaryfunc}

@item 
@ref{49c8,,traverseproc}

@item 
@ref{49c9,,unaryfunc}

@item 
@ref{542,,vectorcallfunc}

@item 
@ref{49ca,,visitproc}
@end itemize


@node The Very High Level Layer,Reference Counting,Stabilité de l’API C,Manuel de référence de l'API Python/C
@anchor{c-api/veryhigh doc}@anchor{49cb}@anchor{c-api/veryhigh the-very-high-level-layer}@anchor{49cc}@anchor{c-api/veryhigh veryhigh}@anchor{49cd}
@section The Very High Level Layer


The functions in this chapter will let you execute Python source code given in a
file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.

Several of these functions accept a start symbol from the grammar as a
parameter.  The available start symbols are @ref{49ce,,Py_eval_input},
@ref{49cf,,Py_file_input}, and @ref{49d0,,Py_single_input}.  These are described
following the functions which accept them as parameters.

Note also that several of these functions take FILE* parameters.  One
particular issue which needs to be handled carefully is that the @code{FILE}
structure for different C libraries can be different and incompatible.  Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that FILE* parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.

@geindex PyRun_AnyFile (C function)
@anchor{c-api/veryhigh c PyRun_AnyFile}@anchor{49d1}
@deffn {C Fonction} int PyRun_AnyFile (FILE *fp, const char *filename)

This is a simplified interface to @ref{49d2,,PyRun_AnyFileExFlags()} below, leaving
`closeit' set to @code{0} and `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_AnyFileFlags (C function)
@anchor{c-api/veryhigh c PyRun_AnyFileFlags}@anchor{49d3}
@deffn {C Fonction} int PyRun_AnyFileFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

This is a simplified interface to @ref{49d2,,PyRun_AnyFileExFlags()} below, leaving
the `closeit' argument set to @code{0}.
@end deffn

@geindex PyRun_AnyFileEx (C function)
@anchor{c-api/veryhigh c PyRun_AnyFileEx}@anchor{49d4}
@deffn {C Fonction} int PyRun_AnyFileEx (FILE *fp, const char *filename, int closeit)

This is a simplified interface to @ref{49d2,,PyRun_AnyFileExFlags()} below, leaving
the `flags' argument set to @code{NULL}.
@end deffn

@geindex PyRun_AnyFileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_AnyFileExFlags}@anchor{49d2}
@deffn {C Fonction} int PyRun_AnyFileExFlags (FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

If `fp' refers to a file associated with an interactive device (console or
terminal input or Unix pseudo-terminal), return the value of
@ref{49d5,,PyRun_InteractiveLoop()}, otherwise return the result of
@ref{482c,,PyRun_SimpleFile()}.  `filename' is decoded from the filesystem
encoding (@ref{c47,,sys.getfilesystemencoding()}).  If `filename' is @code{NULL}, this
function uses @code{"???"} as the filename.
If `closeit' is true, the file is closed before
@code{PyRun_SimpleFileExFlags()} returns.
@end deffn

@geindex PyRun_SimpleString (C function)
@anchor{c-api/veryhigh c PyRun_SimpleString}@anchor{4829}
@deffn {C Fonction} int PyRun_SimpleString (const char *command)

This is a simplified interface to @ref{49d6,,PyRun_SimpleStringFlags()} below,
leaving the @ref{a8f,,PyCompilerFlags}* argument set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleStringFlags (C function)
@anchor{c-api/veryhigh c PyRun_SimpleStringFlags}@anchor{49d6}
@deffn {C Fonction} int PyRun_SimpleStringFlags (const char *command, PyCompilerFlags *flags)

Executes the Python source code from `command' in the @ref{1,,__main__} module
according to the `flags' argument. If @ref{1,,__main__} does not already exist, it
is created.  Returns @code{0} on success or @code{-1} if an exception was raised.  If
there was an error, there is no way to get the exception information. For the
meaning of `flags', see below.

Note that if an otherwise unhandled @ref{d2e,,SystemExit} is raised, this
function will not return @code{-1}, but exit the process, as long as
@ref{3c6,,PyConfig.inspect} is zero.
@end deffn

@geindex PyRun_SimpleFile (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFile}@anchor{482c}
@deffn {C Fonction} int PyRun_SimpleFile (FILE *fp, const char *filename)

This is a simplified interface to @ref{1896,,PyRun_SimpleFileExFlags()} below,
leaving `closeit' set to @code{0} and `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleFileEx (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFileEx}@anchor{49d7}
@deffn {C Fonction} int PyRun_SimpleFileEx (FILE *fp, const char *filename, int closeit)

This is a simplified interface to @ref{1896,,PyRun_SimpleFileExFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_SimpleFileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_SimpleFileExFlags}@anchor{1896}
@deffn {C Fonction} int PyRun_SimpleFileExFlags (FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)

Similar to @ref{49d6,,PyRun_SimpleStringFlags()}, but the Python source code is read
from `fp' instead of an in-memory string. `filename' should be the name of
the file, it is decoded from @ref{525,,filesystem encoding and error handler}.
If `closeit' is true, the file is closed before
@code{PyRun_SimpleFileExFlags()} returns.

@cartouche
@quotation Note 
On Windows, `fp' should be opened as binary mode (e.g. @code{fopen(filename, "rb")}).
Otherwise, Python may not handle script file with LF line ending correctly.
@end quotation
@end cartouche
@end deffn

@geindex PyRun_InteractiveOne (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOne}@anchor{49d8}
@deffn {C Fonction} int PyRun_InteractiveOne (FILE *fp, const char *filename)

This is a simplified interface to @ref{49d9,,PyRun_InteractiveOneFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_InteractiveOneFlags (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveOneFlags}@anchor{49d9}
@deffn {C Fonction} int PyRun_InteractiveOneFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

Read and execute a single statement from a file associated with an
interactive device according to the `flags' argument.  The user will be
prompted using @code{sys.ps1} and @code{sys.ps2}.  `filename' is decoded from the
@ref{525,,filesystem encoding and error handler}.

Returns @code{0} when the input was
executed successfully, @code{-1} if there was an exception, or an error code
from the @code{errcode.h} include file distributed as part of Python if
there was a parse error.  (Note that @code{errcode.h} is not included by
@code{Python.h}, so must be included specifically if needed.)
@end deffn

@geindex PyRun_InteractiveLoop (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveLoop}@anchor{49d5}
@deffn {C Fonction} int PyRun_InteractiveLoop (FILE *fp, const char *filename)

This is a simplified interface to @ref{49da,,PyRun_InteractiveLoopFlags()} below,
leaving `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_InteractiveLoopFlags (C function)
@anchor{c-api/veryhigh c PyRun_InteractiveLoopFlags}@anchor{49da}
@deffn {C Fonction} int PyRun_InteractiveLoopFlags (FILE *fp, const char *filename, PyCompilerFlags *flags)

Read and execute statements from a file associated with an interactive device
until EOF is reached.  The user will be prompted using @code{sys.ps1} and
@code{sys.ps2}.  `filename' is decoded from the @ref{525,,filesystem encoding and error handler}.  Returns @code{0} at EOF or a negative number upon failure.
@end deffn

@geindex PyOS_InputHook (C var)
@anchor{c-api/veryhigh c PyOS_InputHook}@anchor{571}
@deffn {C Variable} int (*PyOS_InputHook)(void)
` Part of the @ref{53e,,Stable ABI}.'
Can be set to point to a function with the prototype
@code{int func(void)}.  The function will be called when Python's
interpreter prompt is about to become idle and wait for user input
from the terminal.  The return value is ignored.  Overriding this
hook can be used to integrate the interpreter's prompt with other
event loops, as done in the @code{Modules/_tkinter.c} in the
Python source code.


Modifié dans la version 3.12: This function is only called from the
@ref{573,,main interpreter}.

@end deffn

@geindex PyOS_ReadlineFunctionPointer (C var)
@anchor{c-api/veryhigh c PyOS_ReadlineFunctionPointer}@anchor{572}
@deffn {C Variable} char *(*PyOS_ReadlineFunctionPointer)(FILE*, FILE*, const char*)

Can be set to point to a function with the prototype
@code{char *func(FILE *stdin, FILE *stdout, char *prompt)},
overriding the default function used to read a single line of input
at the interpreter's prompt.  The function is expected to output
the string `prompt' if it's not @code{NULL}, and then read a line of
input from the provided standard input file, returning the
resulting string.  For example, The @ref{b9,,readline} module sets
this hook to provide line-editing and tab-completion features.

The result must be a string allocated by @ref{386,,PyMem_RawMalloc()} or
@ref{388,,PyMem_RawRealloc()}, or @code{NULL} if an error occurred.


Modifié dans la version 3.4: The result must be allocated by @ref{386,,PyMem_RawMalloc()} or
@ref{388,,PyMem_RawRealloc()}, instead of being allocated by
@ref{c54,,PyMem_Malloc()} or @ref{101b,,PyMem_Realloc()}.



Modifié dans la version 3.12: This function is only called from the
@ref{573,,main interpreter}.

@end deffn

@geindex PyRun_String (C function)
@anchor{c-api/veryhigh c PyRun_String}@anchor{1969}
@deffn {C Fonction} @ref{32f,,PyObject} *PyRun_String (const char *str, int start, PyObject *globals, PyObject *locals)
`Valeur de retour : nouvelle référence.'
This is a simplified interface to @ref{49db,,PyRun_StringFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex PyRun_StringFlags (C function)
@anchor{c-api/veryhigh c PyRun_StringFlags}@anchor{49db}
@deffn {C Fonction} @ref{32f,,PyObject} *PyRun_StringFlags (const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
`Valeur de retour : nouvelle référence.'
Execute Python source code from `str' in the context specified by the
objects `globals' and `locals' with the compiler flags specified by
`flags'.  `globals' must be a dictionary; `locals' can be any object
that implements the mapping protocol.  The parameter `start' specifies
the start token that should be used to parse the source code.

Returns the result of executing the code as a Python object, or @code{NULL} if an
exception was raised.
@end deffn

@geindex PyRun_File (C function)
@anchor{c-api/veryhigh c PyRun_File}@anchor{49dc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyRun_File (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
`Valeur de retour : nouvelle référence.'
This is a simplified interface to @ref{49dd,,PyRun_FileExFlags()} below, leaving
`closeit' set to @code{0} and `flags' set to @code{NULL}.
@end deffn

@geindex PyRun_FileEx (C function)
@anchor{c-api/veryhigh c PyRun_FileEx}@anchor{49de}
@deffn {C Fonction} @ref{32f,,PyObject} *PyRun_FileEx (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
`Valeur de retour : nouvelle référence.'
This is a simplified interface to @ref{49dd,,PyRun_FileExFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex PyRun_FileFlags (C function)
@anchor{c-api/veryhigh c PyRun_FileFlags}@anchor{49df}
@deffn {C Fonction} @ref{32f,,PyObject} *PyRun_FileFlags (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
`Valeur de retour : nouvelle référence.'
This is a simplified interface to @ref{49dd,,PyRun_FileExFlags()} below, leaving
`closeit' set to @code{0}.
@end deffn

@geindex PyRun_FileExFlags (C function)
@anchor{c-api/veryhigh c PyRun_FileExFlags}@anchor{49dd}
@deffn {C Fonction} @ref{32f,,PyObject} *PyRun_FileExFlags (FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
`Valeur de retour : nouvelle référence.'
Similar to @ref{49db,,PyRun_StringFlags()}, but the Python source code is read from
`fp' instead of an in-memory string. `filename' should be the name of the file,
it is decoded from the @ref{525,,filesystem encoding and error handler}.
If `closeit' is true, the file is closed before @ref{49dd,,PyRun_FileExFlags()}
returns.
@end deffn

@geindex Py_CompileString (C function)
@anchor{c-api/veryhigh c Py_CompileString}@anchor{871}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_CompileString (const char *str, const char *filename, int start)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is a simplified interface to @ref{49e0,,Py_CompileStringFlags()} below, leaving
`flags' set to @code{NULL}.
@end deffn

@geindex Py_CompileStringFlags (C function)
@anchor{c-api/veryhigh c Py_CompileStringFlags}@anchor{49e0}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_CompileStringFlags (const char *str, const char *filename, int start, PyCompilerFlags *flags)
`Valeur de retour : nouvelle référence.'
This is a simplified interface to @ref{49e1,,Py_CompileStringExFlags()} below, with
`optimize' set to @code{-1}.
@end deffn

@geindex Py_CompileStringObject (C function)
@anchor{c-api/veryhigh c Py_CompileStringObject}@anchor{49e2}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_CompileStringObject (const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
`Valeur de retour : nouvelle référence.'
Parse and compile the Python source code in `str', returning the resulting code
object.  The start token is given by `start'; this can be used to constrain the
code which can be compiled and should be @ref{49ce,,Py_eval_input},
@ref{49cf,,Py_file_input}, or @ref{49d0,,Py_single_input}.  The filename specified by
`filename' is used to construct the code object and may appear in tracebacks or
@ref{18b,,SyntaxError} exception messages.  This returns @code{NULL} if the code
cannot be parsed or compiled.

The integer `optimize' specifies the optimization level of the compiler; a
value of @code{-1} selects the optimization level of the interpreter as given by
@ref{da2,,-O} options.  Explicit levels are @code{0} (no optimization;
@code{__debug__} is true), @code{1} (asserts are removed, @code{__debug__} is false)
or @code{2} (docstrings are removed too).


Ajouté dans la version 3.4.

@end deffn

@geindex Py_CompileStringExFlags (C function)
@anchor{c-api/veryhigh c Py_CompileStringExFlags}@anchor{49e1}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_CompileStringExFlags (const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
`Valeur de retour : nouvelle référence.'
Like @ref{49e2,,Py_CompileStringObject()}, but `filename' is a byte string
decoded from the @ref{525,,filesystem encoding and error handler}.


Ajouté dans la version 3.2.

@end deffn

@geindex PyEval_EvalCode (C function)
@anchor{c-api/veryhigh c PyEval_EvalCode}@anchor{872}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_EvalCode (PyObject *co, PyObject *globals, PyObject *locals)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is a simplified interface to @ref{16f7,,PyEval_EvalCodeEx()}, with just
the code object, and global and local variables.  The other arguments are
set to @code{NULL}.
@end deffn

@geindex PyEval_EvalCodeEx (C function)
@anchor{c-api/veryhigh c PyEval_EvalCodeEx}@anchor{16f7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_EvalCodeEx (PyObject *co, PyObject *globals, PyObject *locals, PyObject *const *args, int argcount, PyObject *const *kws, int kwcount, PyObject *const *defs, int defcount, PyObject *kwdefs, PyObject *closure)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Evaluate a precompiled code object, given a particular environment for its
evaluation.  This environment consists of a dictionary of global variables,
a mapping object of local variables, arrays of arguments, keywords and
defaults, a dictionary of default values for @ref{2a2,,keyword-only} arguments and a closure tuple of cells.
@end deffn

@geindex PyEval_EvalFrame (C function)
@anchor{c-api/veryhigh c PyEval_EvalFrame}@anchor{48b8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_EvalFrame (PyFrameObject *f)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Evaluate an execution frame.  This is a simplified interface to
@ref{1017,,PyEval_EvalFrameEx()}, for backward compatibility.
@end deffn

@geindex PyEval_EvalFrameEx (C function)
@anchor{c-api/veryhigh c PyEval_EvalFrameEx}@anchor{1017}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_EvalFrameEx (PyFrameObject *f, int throwflag)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is the main, unvarnished function of Python interpretation.  The code
object associated with the execution frame `f' is executed, interpreting
bytecode and executing calls as needed.  The additional `throwflag'
parameter can mostly be ignored - if true, then it causes an exception
to immediately be thrown; this is used for the @ref{4e2,,throw()}
methods of generator objects.


Modifié dans la version 3.4: Cette fonction inclut maintenant une assertion de débogage afin d'assurer qu'elle ne passe pas sous silence une exception active.

@end deffn

@geindex PyEval_MergeCompilerFlags (C function)
@anchor{c-api/veryhigh c PyEval_MergeCompilerFlags}@anchor{49e3}
@deffn {C Fonction} int PyEval_MergeCompilerFlags (PyCompilerFlags *cf)

This function changes the flags of the current evaluation frame, and returns
true on success, false on failure.
@end deffn

@geindex Py_eval_input (C var)
@anchor{c-api/veryhigh c Py_eval_input}@anchor{49ce}
@deffn {C Variable} int Py_eval_input

@geindex Py_CompileString (C function)

The start symbol from the Python grammar for isolated expressions; for use with
@ref{871,,Py_CompileString()}.
@end deffn

@geindex Py_file_input (C var)
@anchor{c-api/veryhigh c Py_file_input}@anchor{49cf}
@deffn {C Variable} int Py_file_input

@geindex Py_CompileString (C function)

The start symbol from the Python grammar for sequences of statements as read
from a file or other source; for use with @ref{871,,Py_CompileString()}.  This is
the symbol to use when compiling arbitrarily long Python source code.
@end deffn

@geindex Py_single_input (C var)
@anchor{c-api/veryhigh c Py_single_input}@anchor{49d0}
@deffn {C Variable} int Py_single_input

@geindex Py_CompileString (C function)

The start symbol from the Python grammar for a single statement; for use with
@ref{871,,Py_CompileString()}. This is the symbol used for the interactive
interpreter loop.
@end deffn

@geindex PyCompilerFlags (C struct)
@anchor{c-api/veryhigh c PyCompilerFlags}@anchor{a8f}
@deffn {C Structure} struct PyCompilerFlags

This is the structure used to hold compiler flags.  In cases where code is only
being compiled, it is passed as @code{int flags}, and in cases where code is being
executed, it is passed as @code{PyCompilerFlags *flags}.  In this case, @code{from
__future__ import} can modify `flags'.

Whenever @code{PyCompilerFlags *flags} is @code{NULL}, @ref{49e4,,cf_flags} is treated as
equal to @code{0}, and any modification due to @code{from __future__ import} is
discarded.

@geindex PyCompilerFlags.cf_flags (C member)
@anchor{c-api/veryhigh c PyCompilerFlags cf_flags}@anchor{49e4}
@deffn {C Membre} int cf_flags

Compiler flags.
@end deffn

@geindex PyCompilerFlags.cf_feature_version (C member)
@anchor{c-api/veryhigh c PyCompilerFlags cf_feature_version}@anchor{49e5}
@deffn {C Membre} int cf_feature_version

`cf_feature_version' is the minor Python version. It should be
initialized to @code{PY_MINOR_VERSION}.

The field is ignored by default, it is used if and only if
@code{PyCF_ONLY_AST} flag is set in @ref{49e4,,cf_flags}.
@end deffn


Modifié dans la version 3.8: Added `cf_feature_version' field.

@end deffn

@geindex CO_FUTURE_DIVISION (C var)
@anchor{c-api/veryhigh c CO_FUTURE_DIVISION}@anchor{49e6}
@deffn {C Variable} int CO_FUTURE_DIVISION

This bit can be set in `flags' to cause division operator @code{/} to be
interpreted as "true division" according to 
@geindex Python Enhancement Proposals; PEP 238
PEP 238@footnote{https://peps.python.org/pep-0238/}.
@end deffn

@node Reference Counting,Gestion des exceptions<2>,The Very High Level Layer,Manuel de référence de l'API Python/C
@anchor{c-api/refcounting doc}@anchor{49e7}@anchor{c-api/refcounting countingrefs}@anchor{49e8}@anchor{c-api/refcounting reference-counting}@anchor{49e9}
@section Reference Counting


The functions and macros in this section are used for managing reference counts
of Python objects.

@geindex Py_REFCNT (C function)
@anchor{c-api/refcounting c Py_REFCNT}@anchor{896}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} Py_REFCNT (PyObject *o)

Get the reference count of the Python object `o'.

Note that the returned value may not actually reflect how many
references to the object are actually held.  For example, some
objects are @ref{42aa,,immortal} and have a very high refcount that does not
reflect the actual number of references.  Consequently, do not rely
on the returned value to be accurate, other than a value of 0 or 1.

Use the @ref{897,,Py_SET_REFCNT()} function to set an object reference count.


Modifié dans la version 3.10: @ref{896,,Py_REFCNT()} is changed to the inline static function.



Modifié dans la version 3.11: The parameter type is no longer const @ref{32f,,PyObject}*.

@end deffn

@geindex Py_SET_REFCNT (C function)
@anchor{c-api/refcounting c Py_SET_REFCNT}@anchor{897}
@deffn {C Fonction} void Py_SET_REFCNT (PyObject *o, Py_ssize_t refcnt)

Set the object `o' reference counter to `refcnt'.

On @ref{1d04,,Python build with Free Threading}, if
`refcnt' is larger than @code{UINT32_MAX}, the object is made @ref{42aa,,immortal}.

This function has no effect on @ref{42aa,,immortal} objects.


Ajouté dans la version 3.9.



Modifié dans la version 3.12: Immortal objects are not modified.

@end deffn

@geindex Py_INCREF (C function)
@anchor{c-api/refcounting c Py_INCREF}@anchor{55a}
@deffn {C Fonction} void Py_INCREF (PyObject *o)

Indicate taking a new @ref{333,,strong reference} to object `o',
indicating it is in use and should not be destroyed.

This function has no effect on @ref{42aa,,immortal} objects.

Cette fonction est souvent utilisée pour convertir une @ref{334,,référence empruntée} en une @ref{333,,référence forte} `sur place'. La fonction @ref{886,,Py_NewRef()} peut être utilisée pour créer une nouvelle @ref{333,,référence forte}.

When done using the object, release is by calling @ref{55b,,Py_DECREF()}.

L'objet ne doit pas être @code{NULL}, la fonction @ref{a53,,Py_XINCREF()} doit être utilisée s'il est possible qu'il soit @code{NULL}.

Do not expect this function to actually modify `o' in any way.
For at least 
@geindex Python Enhancement Proposals; PEP 0683
some objects@footnote{https://peps.python.org/pep-0683/},
this function has no effect.


Modifié dans la version 3.12: Immortal objects are not modified.

@end deffn

@geindex Py_XINCREF (C function)
@anchor{c-api/refcounting c Py_XINCREF}@anchor{a53}
@deffn {C Fonction} void Py_XINCREF (PyObject *o)

Similar to @ref{55a,,Py_INCREF()}, but the object `o' can be @code{NULL},
in which case this has no effect.

Voir aussi @ref{887,,Py_XNewRef()}.
@end deffn

@geindex Py_NewRef (C function)
@anchor{c-api/refcounting c Py_NewRef}@anchor{886}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_NewRef (PyObject *o)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Create a new @ref{333,,strong reference} to an object:
call @ref{55a,,Py_INCREF()} on `o' and return the object `o'.

When the @ref{333,,strong reference} is no longer needed, @ref{55b,,Py_DECREF()}
should be called on it to release the reference.

L'objet `o' ne doit pas être @code{NULL} et la fonction @ref{887,,Py_XNewRef()} doit être utilisée si `o' peut être @code{NULL}.

Par exemple :

@example
Py_INCREF(obj);
self->attr = obj;
@end example

peut s'écrire :

@example
self->attr = Py_NewRef(obj);
@end example

Voir aussi @ref{55a,,Py_INCREF()}.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_XNewRef (C function)
@anchor{c-api/refcounting c Py_XNewRef}@anchor{887}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_XNewRef (PyObject *o)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Semblable à @ref{886,,Py_NewRef()} mais l'objet `o' peut être @code{NULL}.

Cette fonction renvoie @code{NULL} si l'objet `o' est @code{NULL}.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_DECREF (C function)
@anchor{c-api/refcounting c Py_DECREF}@anchor{55b}
@deffn {C Fonction} void Py_DECREF (PyObject *o)

Release a @ref{333,,strong reference} to object `o', indicating the
reference is no longer used.

This function has no effect on @ref{42aa,,immortal} objects.

Once the last @ref{333,,strong reference} is released
(i.e. the object's reference count reaches 0),
the object's type's deallocation
function (which must not be @code{NULL}) is invoked.

Cette fonction est généralement utilisée pour supprimer une @ref{333,,référence forte} avant qu'elle ne soit plus accessible.

L'objet en argument ne doit pas être @code{NULL}. @ref{779,,Py_XDECREF()} doit être utilisée si l'objet peut être @code{NULL}.

Do not expect this function to actually modify `o' in any way.
For at least 
@geindex Python Enhancement Proposals; PEP 683
some objects@footnote{https://peps.python.org/pep-0683/},
this function has no effect.

@cartouche
@quotation Avertissement 
The deallocation function can cause arbitrary Python code to be invoked (e.g.
when a class instance with a @ref{1ee3,,__del__()} method is deallocated).  While
exceptions in such code are not propagated, the executed code has free access to
all Python global variables.  This means that any object that is reachable from
a global variable should be in a consistent state before @ref{55b,,Py_DECREF()} is
invoked.  For example, code to delete an object from a list should copy a
reference to the deleted object in a temporary variable, update the list data
structure, and then call @ref{55b,,Py_DECREF()} for the temporary variable.
@end quotation
@end cartouche


Modifié dans la version 3.12: Immortal objects are not modified.

@end deffn

@geindex Py_XDECREF (C function)
@anchor{c-api/refcounting c Py_XDECREF}@anchor{779}
@deffn {C Fonction} void Py_XDECREF (PyObject *o)

Similar to @ref{55b,,Py_DECREF()}, but the object `o' can be @code{NULL},
in which case this has no effect.
The same warning from @ref{55b,,Py_DECREF()} applies here as well.
@end deffn

@geindex Py_CLEAR (C function)
@anchor{c-api/refcounting c Py_CLEAR}@anchor{564}
@deffn {C Fonction} void Py_CLEAR (PyObject *o)

Release a @ref{333,,strong reference} for object `o'.
The object may be @code{NULL}, in
which case the macro has no effect; otherwise the effect is the same as for
@ref{55b,,Py_DECREF()}, except that the argument is also set to @code{NULL}.  The warning
for @ref{55b,,Py_DECREF()} does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to @code{NULL}
before releasing the reference.

It is a good idea to use this macro whenever releasing a reference
to an object that might be traversed during garbage collection.


Modifié dans la version 3.12: The macro argument is now only evaluated once. If the argument has side
effects, these are no longer duplicated.

@end deffn

@geindex Py_IncRef (C function)
@anchor{c-api/refcounting c Py_IncRef}@anchor{49a7}
@deffn {C Fonction} void Py_IncRef (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Indicate taking a new @ref{333,,strong reference} to object `o'.
A function version of @ref{a53,,Py_XINCREF()}.
It can be used for runtime dynamic embedding of Python.
@end deffn

@geindex Py_DecRef (C function)
@anchor{c-api/refcounting c Py_DecRef}@anchor{49a0}
@deffn {C Fonction} void Py_DecRef (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Release a @ref{333,,strong reference} to object `o'.
A function version of @ref{779,,Py_XDECREF()}.
It can be used for runtime dynamic embedding of Python.
@end deffn

@geindex Py_SETREF (C macro)
@anchor{c-api/refcounting c Py_SETREF}@anchor{565}
@deffn {C Macro} Py_SETREF (dst, src)

Macro safely releasing a @ref{333,,strong reference} to object `dst'
and setting `dst' to `src'.

As in case of @ref{564,,Py_CLEAR()}, "the obvious" code can be deadly:

@example
Py_DECREF(dst);
dst = src;
@end example

The safe way is:

@example
Py_SETREF(dst, src);
@end example

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.


Ajouté dans la version 3.6.



Modifié dans la version 3.12: The macro arguments are now only evaluated once. If an argument has side
effects, these are no longer duplicated.

@end deffn

@geindex Py_XSETREF (C macro)
@anchor{c-api/refcounting c Py_XSETREF}@anchor{566}
@deffn {C Macro} Py_XSETREF (dst, src)

Variant of @ref{565,,Py_SETREF} macro that uses @ref{779,,Py_XDECREF()} instead
of @ref{55b,,Py_DECREF()}.


Ajouté dans la version 3.6.



Modifié dans la version 3.12: The macro arguments are now only evaluated once. If an argument has side
effects, these are no longer duplicated.

@end deffn

@node Gestion des exceptions<2>,Utilitaires<2>,Reference Counting,Manuel de référence de l'API Python/C
@anchor{c-api/exceptions doc}@anchor{49ea}@anchor{c-api/exceptions exception-handling}@anchor{49eb}@anchor{c-api/exceptions exceptionhandling}@anchor{4313}
@section Gestion des exceptions


The functions described in this chapter will let you handle and raise Python
exceptions.  It is important to understand some of the basics of Python
exception handling.  It works somewhat like the POSIX @code{errno} variable:
there is a global indicator (per thread) of the last error that occurred.  Most
C API functions don't clear this on success, but will set it to indicate the
cause of the error on failure.  Most C API functions also return an error
indicator, usually @code{NULL} if they are supposed to return a pointer, or @code{-1}
if they return an integer (exception: the @code{PyArg_*} functions
return @code{1} for success and @code{0} for failure).

Concretely, the error indicator consists of three object pointers: the
exception's type, the exception's value, and the traceback object.  Any
of those pointers can be @code{NULL} if non-set (although some combinations are
forbidden, for example you can't have a non-@code{NULL} traceback if the exception
type is @code{NULL}).

When a function must fail because some function it called failed, it generally
doesn't set the error indicator; the function it called already set it.  It is
responsible for either handling the error and clearing the exception or
returning after cleaning up any resources it holds (such as object references or
memory allocations); it should `not' continue normally if it is not prepared to
handle the error.  If returning due to an error, it is important to indicate to
the caller that an error has been set.  If the error is not handled or carefully
propagated, additional calls into the Python/C API may not behave as intended
and may fail in mysterious ways.

@cartouche
@quotation Note 
The error indicator is `not' the result of @ref{675,,sys.exc_info()}.
The former corresponds to an exception that is not yet caught (and is
therefore still propagating), while the latter returns an exception after
it is caught (and has therefore stopped propagating).
@end quotation
@end cartouche

@menu
* Printing and clearing:: 
* Lever des exceptions:: 
* Issuing warnings:: 
* Querying the error indicator:: 
* Traitement des signaux: Traitement des signaux<2>. 
* Exception Classes:: 
* Objets exception:: 
* Objets exception Unicode:: 
* Contrôle de la récursion:: 
* Exceptions standards:: 
* Standard Warning Categories:: 

@end menu

@node Printing and clearing,Lever des exceptions,,Gestion des exceptions<2>
@anchor{c-api/exceptions printing-and-clearing}@anchor{49ec}
@subsection Printing and clearing


@geindex PyErr_Clear (C function)
@anchor{c-api/exceptions c PyErr_Clear}@anchor{101a}
@deffn {C Fonction} void PyErr_Clear ()
` Part of the @ref{53e,,Stable ABI}.'
Clear the error indicator.  If the error indicator is not set, there is no
effect.
@end deffn

@geindex PyErr_PrintEx (C function)
@anchor{c-api/exceptions c PyErr_PrintEx}@anchor{48ac}
@deffn {C Fonction} void PyErr_PrintEx (int set_sys_last_vars)
` Part of the @ref{53e,,Stable ABI}.'
Print a standard traceback to @code{sys.stderr} and clear the error indicator.
`Unless' the error is a @code{SystemExit}, in that case no traceback is
printed and the Python process will exit with the error code specified by
the @code{SystemExit} instance.

Call this function `only' when the error indicator is set.  Otherwise it
will cause a fatal error!

If `set_sys_last_vars' is nonzero, the variable @ref{4a7,,sys.last_exc} is
set to the printed exception. For backwards compatibility, the
deprecated variables @ref{4a8,,sys.last_type}, @ref{4a9,,sys.last_value} and
@ref{4aa,,sys.last_traceback} are also set to the type, value and traceback
of this exception, respectively.


Modifié dans la version 3.12: The setting of @ref{4a7,,sys.last_exc} was added.

@end deffn

@geindex PyErr_Print (C function)
@anchor{c-api/exceptions c PyErr_Print}@anchor{18d2}
@deffn {C Fonction} void PyErr_Print ()
` Part of the @ref{53e,,Stable ABI}.'
Alias for @code{PyErr_PrintEx(1)}.
@end deffn

@geindex PyErr_WriteUnraisable (C function)
@anchor{c-api/exceptions c PyErr_WriteUnraisable}@anchor{345}
@deffn {C Fonction} void PyErr_WriteUnraisable (PyObject *obj)
` Part of the @ref{53e,,Stable ABI}.'
Call @ref{1f4,,sys.unraisablehook()} using the current exception and `obj'
argument.

This utility function prints a warning message to @code{sys.stderr} when an
exception has been set but it is impossible for the interpreter to actually
raise the exception.  It is used, for example, when an exception occurs in an
@ref{1ee3,,__del__()} method.

The function is called with a single argument `obj' that identifies the context
in which the unraisable exception occurred. If possible,
the repr of `obj' will be printed in the warning message.
If `obj' is @code{NULL}, only the traceback is printed.

An exception must be set when calling this function.


Modifié dans la version 3.4: Print a traceback. Print only traceback if `obj' is @code{NULL}.



Modifié dans la version 3.8: Use @ref{1f4,,sys.unraisablehook()}.

@end deffn

@geindex PyErr_FormatUnraisable (C function)
@anchor{c-api/exceptions c PyErr_FormatUnraisable}@anchor{344}
@deffn {C Fonction} void PyErr_FormatUnraisable (const char *format, ...)

Similar to @ref{345,,PyErr_WriteUnraisable()}, but the `format' and subsequent
parameters help format the warning message; they have the same meaning and
values as in @ref{380,,PyUnicode_FromFormat()}.
@code{PyErr_WriteUnraisable(obj)} is roughly equivalent to
@code{PyErr_FormatUnraisable("Exception ignored in: %R", obj)}.
If `format' is @code{NULL}, only the traceback is printed.


Ajouté dans la version 3.13.

@end deffn

@geindex PyErr_DisplayException (C function)
@anchor{c-api/exceptions c PyErr_DisplayException}@anchor{3f8}
@deffn {C Fonction} void PyErr_DisplayException (PyObject *exc)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Print the standard traceback display of @code{exc} to @code{sys.stderr}, including
chained exceptions and notes.


Ajouté dans la version 3.12.

@end deffn

@node Lever des exceptions,Issuing warnings,Printing and clearing,Gestion des exceptions<2>
@anchor{c-api/exceptions raising-exceptions}@anchor{49ed}
@subsection Lever des exceptions


These functions help you set the current thread's error indicator.
For convenience, some of these functions will always return a
@code{NULL} pointer for use in a @code{return} statement.

@geindex PyErr_SetString (C function)
@anchor{c-api/exceptions c PyErr_SetString}@anchor{568}
@deffn {C Fonction} void PyErr_SetString (PyObject *type, const char *message)
` Part of the @ref{53e,,Stable ABI}.'
This is the most common way to set the error indicator.  The first argument
specifies the exception type; it is normally one of the standard exceptions,
e.g. @code{PyExc_RuntimeError}.  You need not create a new
@ref{333,,strong reference} to it (e.g. with @ref{55a,,Py_INCREF()}).
The second argument is an error message; it is decoded from @code{'utf-8'}.
@end deffn

@geindex PyErr_SetObject (C function)
@anchor{c-api/exceptions c PyErr_SetObject}@anchor{567}
@deffn {C Fonction} void PyErr_SetObject (PyObject *type, PyObject *value)
` Part of the @ref{53e,,Stable ABI}.'
This function is similar to @ref{568,,PyErr_SetString()} but lets you specify an
arbitrary Python object for the "value" of the exception.
@end deffn

@geindex PyErr_Format (C function)
@anchor{c-api/exceptions c PyErr_Format}@anchor{e9a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_Format (PyObject *exception, const char *format, ...)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI}.'
This function sets the error indicator and returns @code{NULL}.  `exception'
should be a Python exception class.  The `format' and subsequent
parameters help format the error message; they have the same meaning and
values as in @ref{380,,PyUnicode_FromFormat()}. `format' is an ASCII-encoded
string.
@end deffn

@geindex PyErr_FormatV (C function)
@anchor{c-api/exceptions c PyErr_FormatV}@anchor{e99}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_FormatV (PyObject *exception, const char *format, va_list vargs)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.5.'
Same as @ref{e9a,,PyErr_Format()}, but taking a @code{va_list} argument rather
than a variable number of arguments.


Ajouté dans la version 3.5.

@end deffn

@geindex PyErr_SetNone (C function)
@anchor{c-api/exceptions c PyErr_SetNone}@anchor{48b4}
@deffn {C Fonction} void PyErr_SetNone (PyObject *type)
` Part of the @ref{53e,,Stable ABI}.'
This is a shorthand for @code{PyErr_SetObject(type, Py_None)}.
@end deffn

@geindex PyErr_BadArgument (C function)
@anchor{c-api/exceptions c PyErr_BadArgument}@anchor{48a9}
@deffn {C Fonction} int PyErr_BadArgument ()
` Part of the @ref{53e,,Stable ABI}.'
This is a shorthand for @code{PyErr_SetString(PyExc_TypeError, message)}, where
`message' indicates that a built-in operation was invoked with an illegal
argument.  It is mostly for internal use.
@end deffn

@geindex PyErr_NoMemory (C function)
@anchor{c-api/exceptions c PyErr_NoMemory}@anchor{47bd}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_NoMemory ()
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI}.'
This is a shorthand for @code{PyErr_SetNone(PyExc_MemoryError)}; it returns @code{NULL}
so an object allocation function can write @code{return PyErr_NoMemory();} when it
runs out of memory.
@end deffn

@geindex PyErr_SetFromErrno (C function)
@anchor{c-api/exceptions c PyErr_SetFromErrno}@anchor{47bc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetFromErrno (PyObject *type)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI}.'
@geindex strerror (C function)

This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable @code{errno}.  It constructs a
tuple object whose first item is the integer @code{errno} value and whose
second item is the corresponding error message (gotten from @code{strerror()}),
and then calls @code{PyErr_SetObject(type, object)}.  On Unix, when the
@code{errno} value is @code{EINTR}, indicating an interrupted system call,
this calls @ref{450,,PyErr_CheckSignals()}, and if that set the error indicator,
leaves it set to that.  The function always returns @code{NULL}, so a wrapper
function around a system call can write @code{return PyErr_SetFromErrno(type);}
when the system call returns an error.
@end deffn

@geindex PyErr_SetFromErrnoWithFilenameObject (C function)
@anchor{c-api/exceptions c PyErr_SetFromErrnoWithFilenameObject}@anchor{48b0}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetFromErrnoWithFilenameObject (PyObject *type, PyObject *filenameObject)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{47bc,,PyErr_SetFromErrno()}, with the additional behavior that if
`filenameObject' is not @code{NULL}, it is passed to the constructor of `type' as
a third parameter.  In the case of @ref{40d,,OSError} exception,
this is used to define the @code{filename} attribute of the
exception instance.
@end deffn

@geindex PyErr_SetFromErrnoWithFilenameObjects (C function)
@anchor{c-api/exceptions c PyErr_SetFromErrnoWithFilenameObjects}@anchor{48b1}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetFromErrnoWithFilenameObjects (PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Similar to @ref{48b0,,PyErr_SetFromErrnoWithFilenameObject()}, but takes a second
filename object, for raising errors when a function that takes two filenames
fails.


Ajouté dans la version 3.4.

@end deffn

@geindex PyErr_SetFromErrnoWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetFromErrnoWithFilename}@anchor{16a1}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetFromErrnoWithFilename (PyObject *type, const char *filename)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{48b0,,PyErr_SetFromErrnoWithFilenameObject()}, but the filename
is given as a C string.  `filename' is decoded from the @ref{525,,filesystem encoding and error handler}.
@end deffn

@geindex PyErr_SetFromWindowsErr (C function)
@anchor{c-api/exceptions c PyErr_SetFromWindowsErr}@anchor{48b2}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetFromWindowsErr (int ierr)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
This is a convenience function to raise @ref{40d,,OSError}. If called with
`ierr' of @code{0}, the error code returned by a call to @code{GetLastError()}
is used instead.  It calls the Win32 function @code{FormatMessage()} to retrieve
the Windows description of error code given by `ierr' or @code{GetLastError()},
then it constructs a @ref{40d,,OSError} object with the @ref{2215,,winerror}
attribute set to the error code, the @ref{2216,,strerror} attribute
set to the corresponding error message (gotten from
@code{FormatMessage()}), and then calls @code{PyErr_SetObject(PyExc_OSError,
object)}. This function always returns @code{NULL}.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErr (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErr}@anchor{48ad}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetExcFromWindowsErr (PyObject *type, int ierr)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Similar to @ref{48b2,,PyErr_SetFromWindowsErr()}, with an additional parameter
specifying the exception type to be raised.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex PyErr_SetFromWindowsErrWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetFromWindowsErrWithFilename}@anchor{16a3}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetFromWindowsErrWithFilename (int ierr, const char *filename)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Similar to @ref{48b2,,PyErr_SetFromWindowsErr()}, with the additional behavior
that if `filename' is not @code{NULL}, it is decoded from the filesystem
encoding (@ref{c42,,os.fsdecode()}) and passed to the constructor of
@ref{40d,,OSError} as a third parameter to be used to define the
@code{filename} attribute of the exception instance.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilenameObject (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilenameObject}@anchor{48ae}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetExcFromWindowsErrWithFilenameObject (PyObject *type, int ierr, PyObject *filename)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Similar to @ref{48ad,,PyErr_SetExcFromWindowsErr()}, with the additional behavior
that if `filename' is not @code{NULL}, it is passed to the constructor of
@ref{40d,,OSError} as a third parameter to be used to define the
@code{filename} attribute of the exception instance.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilenameObjects (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilenameObjects}@anchor{48af}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetExcFromWindowsErrWithFilenameObjects (PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Similar to @ref{48ae,,PyErr_SetExcFromWindowsErrWithFilenameObject()},
but accepts a second filename object.

@ref{1ce0,,Availability}: Windows.


Ajouté dans la version 3.4.

@end deffn

@geindex PyErr_SetExcFromWindowsErrWithFilename (C function)
@anchor{c-api/exceptions c PyErr_SetExcFromWindowsErrWithFilename}@anchor{16a2}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetExcFromWindowsErrWithFilename (PyObject *type, int ierr, const char *filename)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Similar to @ref{16a3,,PyErr_SetFromWindowsErrWithFilename()}, with an additional
parameter specifying the exception type to be raised.

@ref{1ce0,,Availability}: Windows.
@end deffn

@geindex PyErr_SetImportError (C function)
@anchor{c-api/exceptions c PyErr_SetImportError}@anchor{d2c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetImportError (PyObject *msg, PyObject *name, PyObject *path)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
This is a convenience function to raise @ref{40f,,ImportError}. `msg' will be
set as the exception's message string. `name' and `path', both of which can
be @code{NULL}, will be set as the @ref{40f,,ImportError}'s respective @code{name}
and @code{path} attributes.


Ajouté dans la version 3.3.

@end deffn

@geindex PyErr_SetImportErrorSubclass (C function)
@anchor{c-api/exceptions c PyErr_SetImportErrorSubclass}@anchor{d04}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_SetImportErrorSubclass (PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.6.'
Much like @ref{d2c,,PyErr_SetImportError()} but this function allows for
specifying a subclass of @ref{40f,,ImportError} to raise.


Ajouté dans la version 3.6.

@end deffn

@geindex PyErr_SyntaxLocationObject (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocationObject}@anchor{49ee}
@deffn {C Fonction} void PyErr_SyntaxLocationObject (PyObject *filename, int lineno, int col_offset)

Set file, line, and offset information for the current exception.  If the
current exception is not a @ref{18b,,SyntaxError}, then it sets additional
attributes, which make the exception printing subsystem think the exception
is a @ref{18b,,SyntaxError}.


Ajouté dans la version 3.4.

@end deffn

@geindex PyErr_SyntaxLocationEx (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocationEx}@anchor{48b6}
@deffn {C Fonction} void PyErr_SyntaxLocationEx (const char *filename, int lineno, int col_offset)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Like @ref{49ee,,PyErr_SyntaxLocationObject()}, but `filename' is a byte string
decoded from the @ref{525,,filesystem encoding and error handler}.


Ajouté dans la version 3.2.

@end deffn

@geindex PyErr_SyntaxLocation (C function)
@anchor{c-api/exceptions c PyErr_SyntaxLocation}@anchor{48b5}
@deffn {C Fonction} void PyErr_SyntaxLocation (const char *filename, int lineno)
` Part of the @ref{53e,,Stable ABI}.'
Like @ref{48b6,,PyErr_SyntaxLocationEx()}, but the `col_offset' parameter is
omitted.
@end deffn

@geindex PyErr_BadInternalCall (C function)
@anchor{c-api/exceptions c PyErr_BadInternalCall}@anchor{48aa}
@deffn {C Fonction} void PyErr_BadInternalCall ()
` Part of the @ref{53e,,Stable ABI}.'
This is a shorthand for @code{PyErr_SetString(PyExc_SystemError, message)},
where `message' indicates that an internal operation (e.g. a Python/C API
function) was invoked with an illegal argument.  It is mostly for internal
use.
@end deffn

@node Issuing warnings,Querying the error indicator,Lever des exceptions,Gestion des exceptions<2>
@anchor{c-api/exceptions issuing-warnings}@anchor{49ef}
@subsection Issuing warnings


Use these functions to issue warnings from C code.  They mirror similar
functions exported by the Python @ref{111,,warnings} module.  They normally
print a warning message to `sys.stderr'; however, it is
also possible that the user has specified that warnings are to be turned into
errors, and in that case they will raise an exception.  It is also possible that
the functions raise an exception because of a problem with the warning machinery.
The return value is @code{0} if no exception is raised, or @code{-1} if an exception
is raised.  (It is not possible to determine whether a warning message is
actually printed, nor what the reason is for the exception; this is
intentional.)  If an exception is raised, the caller should do its normal
exception handling (for example, @ref{55b,,Py_DECREF()} owned references and return
an error value).

@geindex PyErr_WarnEx (C function)
@anchor{c-api/exceptions c PyErr_WarnEx}@anchor{1401}
@deffn {C Fonction} int PyErr_WarnEx (PyObject *category, const char *message, Py_ssize_t stack_level)
` Part of the @ref{53e,,Stable ABI}.'
Issue a warning message.  The `category' argument is a warning category (see
below) or @code{NULL}; the `message' argument is a UTF-8 encoded string.  `stack_level' is a
positive number giving a number of stack frames; the warning will be issued from
the  currently executing line of code in that stack frame.  A `stack_level' of 1
is the function calling @ref{1401,,PyErr_WarnEx()}, 2 is  the function above that,
and so forth.

Warning categories must be subclasses of @code{PyExc_Warning};
@code{PyExc_Warning} is a subclass of @code{PyExc_Exception};
the default warning category is @code{PyExc_RuntimeWarning}. The standard
Python warning categories are available as global variables whose names are
enumerated at @ref{49f0,,Standard Warning Categories}.

For information about warning control, see the documentation for the
@ref{111,,warnings} module and the @ref{8b4,,-W} option in the command line
documentation.  There is no C API for warning control.
@end deffn

@geindex PyErr_WarnExplicitObject (C function)
@anchor{c-api/exceptions c PyErr_WarnExplicitObject}@anchor{49f1}
@deffn {C Fonction} int PyErr_WarnExplicitObject (PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)

Issue a warning message with explicit control over all warning attributes.  This
is a straightforward wrapper around the Python function
@ref{cee,,warnings.warn_explicit()}; see there for more information.  The `module'
and `registry' arguments may be set to @code{NULL} to get the default effect
described there.


Ajouté dans la version 3.4.

@end deffn

@geindex PyErr_WarnExplicit (C function)
@anchor{c-api/exceptions c PyErr_WarnExplicit}@anchor{16aa}
@deffn {C Fonction} int PyErr_WarnExplicit (PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{49f1,,PyErr_WarnExplicitObject()} except that `message' and
`module' are UTF-8 encoded strings, and `filename' is decoded from the
@ref{525,,filesystem encoding and error handler}.
@end deffn

@geindex PyErr_WarnFormat (C function)
@anchor{c-api/exceptions c PyErr_WarnFormat}@anchor{48b7}
@deffn {C Fonction} int PyErr_WarnFormat (PyObject *category, Py_ssize_t stack_level, const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
Function similar to @ref{1401,,PyErr_WarnEx()}, but use
@ref{380,,PyUnicode_FromFormat()} to format the warning message.  `format' is
an ASCII-encoded string.


Ajouté dans la version 3.2.

@end deffn

@geindex PyErr_ResourceWarning (C function)
@anchor{c-api/exceptions c PyErr_ResourceWarning}@anchor{d05}
@deffn {C Fonction} int PyErr_ResourceWarning (PyObject *source, Py_ssize_t stack_level, const char *format, ...)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.6.'
Function similar to @ref{48b7,,PyErr_WarnFormat()}, but `category' is
@ref{241,,ResourceWarning} and it passes `source' to @code{warnings.WarningMessage}.


Ajouté dans la version 3.6.

@end deffn

@node Querying the error indicator,Traitement des signaux<2>,Issuing warnings,Gestion des exceptions<2>
@anchor{c-api/exceptions querying-the-error-indicator}@anchor{49f2}
@subsection Querying the error indicator


@geindex PyErr_Occurred (C function)
@anchor{c-api/exceptions c PyErr_Occurred}@anchor{187f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_Occurred ()
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Test whether the error indicator is set.  If set, return the exception `type'
(the first argument to the last call to one of the @code{PyErr_Set*}
functions or to @ref{3ec,,PyErr_Restore()}).  If not set, return @code{NULL}.  You do not
own a reference to the return value, so you do not need to @ref{55b,,Py_DECREF()}
it.

The caller must hold the GIL.

@cartouche
@quotation Note 
Do not compare the return value to a specific exception; use
@ref{4854,,PyErr_ExceptionMatches()} instead, shown below.  (The comparison could
easily fail since the exception may be an instance instead of a class, in the
case of a class exception, or it may be a subclass of the expected exception.)
@end quotation
@end cartouche
@end deffn

@geindex PyErr_ExceptionMatches (C function)
@anchor{c-api/exceptions c PyErr_ExceptionMatches}@anchor{4854}
@deffn {C Fonction} int PyErr_ExceptionMatches (PyObject *exc)
` Part of the @ref{53e,,Stable ABI}.'
Equivalent to @code{PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)}.  This
should only be called when an exception is actually set; a memory access
violation will occur if no exception has been raised.
@end deffn

@geindex PyErr_GivenExceptionMatches (C function)
@anchor{c-api/exceptions c PyErr_GivenExceptionMatches}@anchor{48ab}
@deffn {C Fonction} int PyErr_GivenExceptionMatches (PyObject *given, PyObject *exc)
` Part of the @ref{53e,,Stable ABI}.'
Return true if the `given' exception matches the exception type in `exc'.  If
`exc' is a class object, this also returns true when `given' is an instance
of a subclass.  If `exc' is a tuple, all exception types in the tuple (and
recursively in subtuples) are searched for a match.
@end deffn

@geindex PyErr_GetRaisedException (C function)
@anchor{c-api/exceptions c PyErr_GetRaisedException}@anchor{3ea}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_GetRaisedException (void)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Return the exception currently being raised, clearing the error indicator at
the same time. Return @code{NULL} if the error indicator is not set.

This function is used by code that needs to catch exceptions,
or code that needs to save and restore the error indicator temporarily.

Par exemple :

@example
@{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... code that might produce other errors ... */

   PyErr_SetRaisedException(exc);
@}
@end example


@subsubheading Voir aussi


@ref{759,,PyErr_GetHandledException()},
to save the exception currently being handled.



Ajouté dans la version 3.12.

@end deffn

@geindex PyErr_SetRaisedException (C function)
@anchor{c-api/exceptions c PyErr_SetRaisedException}@anchor{3ed}
@deffn {C Fonction} void PyErr_SetRaisedException (PyObject *exc)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Set `exc' as the exception currently being raised,
clearing the existing exception if one is set.

@cartouche
@quotation Avertissement 
This call steals a reference to `exc', which must be a valid exception.
@end quotation
@end cartouche


Ajouté dans la version 3.12.

@end deffn

@geindex PyErr_Fetch (C function)
@anchor{c-api/exceptions c PyErr_Fetch}@anchor{3e9}
@deffn {C Fonction} void PyErr_Fetch (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
` Part of the @ref{53e,,Stable ABI}.'

Obsolète depuis la version 3.12: Use @ref{3ea,,PyErr_GetRaisedException()} instead.


Retrieve the error indicator into three variables whose addresses are passed.
If the error indicator is not set, set all three variables to @code{NULL}.  If it is
set, it will be cleared and you own a reference to each object retrieved.  The
value and traceback object may be @code{NULL} even when the type object is not.

@cartouche
@quotation Note 
This function is normally only used by legacy code that needs to catch
exceptions or save and restore the error indicator temporarily.

Par exemple :

@example
@{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
@}
@end example
@end quotation
@end cartouche
@end deffn

@geindex PyErr_Restore (C function)
@anchor{c-api/exceptions c PyErr_Restore}@anchor{3ec}
@deffn {C Fonction} void PyErr_Restore (PyObject *type, PyObject *value, PyObject *traceback)
` Part of the @ref{53e,,Stable ABI}.'

Obsolète depuis la version 3.12: Use @ref{3ed,,PyErr_SetRaisedException()} instead.


Set the error indicator from the three objects,
`type', `value', and `traceback',
clearing the existing exception if one is set.
If the objects are @code{NULL}, the error
indicator is cleared.  Do not pass a @code{NULL} type and non-@code{NULL} value or
traceback.  The exception type should be a class.  Do not pass an invalid
exception type or value. (Violating these rules will cause subtle problems
later.)  This call takes away a reference to each object: you must own a
reference to each object before the call and after the call you no longer own
these references.  (If you don't understand this, don't use this function.  I
warned you.)

@cartouche
@quotation Note 
This function is normally only used by legacy code that needs to
save and restore the error indicator temporarily.
Use @ref{3e9,,PyErr_Fetch()} to save the current error indicator.
@end quotation
@end cartouche
@end deffn

@geindex PyErr_NormalizeException (C function)
@anchor{c-api/exceptions c PyErr_NormalizeException}@anchor{3eb}
@deffn {C Fonction} void PyErr_NormalizeException (PyObject **exc, PyObject **val, PyObject **tb)
` Part of the @ref{53e,,Stable ABI}.'

Obsolète depuis la version 3.12: Use @ref{3ea,,PyErr_GetRaisedException()} instead,
to avoid any possible de-normalization.


Under certain circumstances, the values returned by @ref{3e9,,PyErr_Fetch()} below
can be "unnormalized", meaning that @code{*exc} is a class object but @code{*val} is
not an instance of the  same class.  This function can be used to instantiate
the class in that case.  If the values are already normalized, nothing happens.
The delayed normalization is implemented to improve performance.

@cartouche
@quotation Note 
This function `does not' implicitly set the
@ref{12a4,,__traceback__}
attribute on the exception value. If setting the traceback
appropriately is desired, the following additional snippet is needed:

@example
if (tb != NULL) @{
  PyException_SetTraceback(val, tb);
@}
@end example
@end quotation
@end cartouche
@end deffn

@geindex PyErr_GetHandledException (C function)
@anchor{c-api/exceptions c PyErr_GetHandledException}@anchor{759}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_GetHandledException (void)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Retrieve the active exception instance, as would be returned by @ref{676,,sys.exception()}.
This refers to an exception that was `already caught', not to an exception that was
freshly raised. Returns a new reference to the exception or @code{NULL}.
Does not modify the interpreter's exception state.

@cartouche
@quotation Note 
This function is not normally used by code that wants to handle exceptions.
Rather, it can be used when code needs to save and restore the exception
state temporarily.  Use @ref{75a,,PyErr_SetHandledException()} to restore or
clear the exception state.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex PyErr_SetHandledException (C function)
@anchor{c-api/exceptions c PyErr_SetHandledException}@anchor{75a}
@deffn {C Fonction} void PyErr_SetHandledException (PyObject *exc)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Set the active exception, as known from @code{sys.exception()}.  This refers
to an exception that was `already caught', not to an exception that was
freshly raised.
To clear the exception state, pass @code{NULL}.

@cartouche
@quotation Note 
This function is not normally used by code that wants to handle exceptions.
Rather, it can be used when code needs to save and restore the exception
state temporarily.  Use @ref{759,,PyErr_GetHandledException()} to get the exception
state.
@end quotation
@end cartouche


Ajouté dans la version 3.11.

@end deffn

@geindex PyErr_GetExcInfo (C function)
@anchor{c-api/exceptions c PyErr_GetExcInfo}@anchor{75c}
@deffn {C Fonction} void PyErr_GetExcInfo (PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Retrieve the old-style representation of the exception info, as known from
@ref{675,,sys.exc_info()}.  This refers to an exception that was `already caught',
not to an exception that was freshly raised.  Returns new references for the
three objects, any of which may be @code{NULL}.  Does not modify the exception
info state.  This function is kept for backwards compatibility. Prefer using
@ref{759,,PyErr_GetHandledException()}.

@cartouche
@quotation Note 
This function is not normally used by code that wants to handle exceptions.
Rather, it can be used when code needs to save and restore the exception
state temporarily.  Use @ref{75b,,PyErr_SetExcInfo()} to restore or clear the
exception state.
@end quotation
@end cartouche


Ajouté dans la version 3.3.

@end deffn

@geindex PyErr_SetExcInfo (C function)
@anchor{c-api/exceptions c PyErr_SetExcInfo}@anchor{75b}
@deffn {C Fonction} void PyErr_SetExcInfo (PyObject *type, PyObject *value, PyObject *traceback)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Set the exception info, as known from @code{sys.exc_info()}.  This refers
to an exception that was `already caught', not to an exception that was
freshly raised.  This function steals the references of the arguments.
To clear the exception state, pass @code{NULL} for all three arguments.
This function is kept for backwards compatibility. Prefer using
@ref{75a,,PyErr_SetHandledException()}.

@cartouche
@quotation Note 
This function is not normally used by code that wants to handle exceptions.
Rather, it can be used when code needs to save and restore the exception
state temporarily.  Use @ref{75c,,PyErr_GetExcInfo()} to read the exception
state.
@end quotation
@end cartouche


Ajouté dans la version 3.3.



Modifié dans la version 3.11: The @code{type} and @code{traceback} arguments are no longer used and
can be NULL. The interpreter now derives them from the exception
instance (the @code{value} argument). The function still steals
references of all three arguments.

@end deffn

@node Traitement des signaux<2>,Exception Classes,Querying the error indicator,Gestion des exceptions<2>
@anchor{c-api/exceptions signal-handling}@anchor{49f3}
@subsection Traitement des signaux


@geindex PyErr_CheckSignals (C function)
@anchor{c-api/exceptions c PyErr_CheckSignals}@anchor{450}
@deffn {C Fonction} int PyErr_CheckSignals ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex module;signal
@geindex SIGINT (C macro)
@geindex KeyboardInterrupt (built-in exception)

This function interacts with Python's signal handling.

If the function is called from the main thread and under the main Python
interpreter, it checks whether a signal has been sent to the processes
and if so, invokes the corresponding signal handler.  If the @ref{c5,,signal}
module is supported, this can invoke a signal handler written in Python.

The function attempts to handle all pending signals, and then returns @code{0}.
However, if a Python signal handler raises an exception, the error
indicator is set and the function returns @code{-1} immediately (such that
other pending signals may not have been handled yet: they will be on the
next @ref{450,,PyErr_CheckSignals()} invocation).

If the function is called from a non-main thread, or under a non-main
Python interpreter, it does nothing and returns @code{0}.

This function can be called by long-running C code that wants to
be interruptible by user requests (such as by pressing Ctrl-C).

@cartouche
@quotation Note 
The default Python signal handler for @code{SIGINT} raises the
@ref{9bf,,KeyboardInterrupt} exception.
@end quotation
@end cartouche
@end deffn

@geindex PyErr_SetInterrupt (C function)
@anchor{c-api/exceptions c PyErr_SetInterrupt}@anchor{48b3}
@deffn {C Fonction} void PyErr_SetInterrupt ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex module;signal
@geindex SIGINT (C macro)
@geindex KeyboardInterrupt (built-in exception)

Simulate the effect of a @code{SIGINT} signal arriving.
This is equivalent to @code{PyErr_SetInterruptEx(SIGINT)}.

@cartouche
@quotation Note 
This function is async-signal-safe.  It can be called without
the @ref{158,,GIL} and from a C signal handler.
@end quotation
@end cartouche
@end deffn

@geindex PyErr_SetInterruptEx (C function)
@anchor{c-api/exceptions c PyErr_SetInterruptEx}@anchor{88a}
@deffn {C Fonction} int PyErr_SetInterruptEx (int signum)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
@geindex module;signal
@geindex KeyboardInterrupt (built-in exception)

Simulate the effect of a signal arriving. The next time
@ref{450,,PyErr_CheckSignals()} is called,  the Python signal handler for
the given signal number will be called.

This function can be called by C code that sets up its own signal handling
and wants Python signal handlers to be invoked as expected when an
interruption is requested (for example when the user presses Ctrl-C
to interrupt an operation).

If the given signal isn't handled by Python (it was set to
@ref{17af,,signal.SIG_DFL} or @ref{17ae,,signal.SIG_IGN}), it will be ignored.

If `signum' is outside of the allowed range of signal numbers, @code{-1}
is returned.  Otherwise, @code{0} is returned.  The error indicator is
never changed by this function.

@cartouche
@quotation Note 
This function is async-signal-safe.  It can be called without
the @ref{158,,GIL} and from a C signal handler.
@end quotation
@end cartouche


Ajouté dans la version 3.10.

@end deffn

@geindex PySignal_SetWakeupFd (C function)
@anchor{c-api/exceptions c PySignal_SetWakeupFd}@anchor{1392}
@deffn {C Fonction} int PySignal_SetWakeupFd (int fd)

This utility function specifies a file descriptor to which the signal number
is written as a single byte whenever a signal is received. `fd' must be
non-blocking. It returns the previous such file descriptor.

The value @code{-1} disables the feature; this is the initial state.
This is equivalent to @ref{b5e,,signal.set_wakeup_fd()} in Python, but without any
error checking.  `fd' should be a valid file descriptor.  The function should
only be called from the main thread.


Modifié dans la version 3.5: On Windows, the function now also supports socket handles.

@end deffn

@node Exception Classes,Objets exception,Traitement des signaux<2>,Gestion des exceptions<2>
@anchor{c-api/exceptions exception-classes}@anchor{49f4}
@subsection Exception Classes


@geindex PyErr_NewException (C function)
@anchor{c-api/exceptions c PyErr_NewException}@anchor{1248}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_NewException (const char *name, PyObject *base, PyObject *dict)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This utility function creates and returns a new exception class. The `name'
argument must be the name of the new exception, a C string of the form
@code{module.classname}.  The `base' and `dict' arguments are normally @code{NULL}.
This creates a class object derived from @ref{9c7,,Exception} (accessible in C as
@code{PyExc_Exception}).

The @ref{36a,,__module__} attribute of the new class is set to the first part (up
to the last dot) of the `name' argument, and the class name is set to the last
part (after the last dot).  The `base' argument can be used to specify alternate
base classes; it can either be only one class or a tuple of classes. The `dict'
argument can be used to specify a dictionary of class variables and methods.
@end deffn

@geindex PyErr_NewExceptionWithDoc (C function)
@anchor{c-api/exceptions c PyErr_NewExceptionWithDoc}@anchor{1247}
@deffn {C Fonction} @ref{32f,,PyObject} *PyErr_NewExceptionWithDoc (const char *name, const char *doc, PyObject *base, PyObject *dict)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Same as @ref{1248,,PyErr_NewException()}, except that the new exception class can
easily be given a docstring: If `doc' is non-@code{NULL}, it will be used as the
docstring for the exception class.


Ajouté dans la version 3.2.

@end deffn

@node Objets exception,Objets exception Unicode,Exception Classes,Gestion des exceptions<2>
@anchor{c-api/exceptions exception-objects}@anchor{49f5}
@subsection Objets exception


@geindex PyException_GetTraceback (C function)
@anchor{c-api/exceptions c PyException_GetTraceback}@anchor{48be}
@deffn {C Fonction} @ref{32f,,PyObject} *PyException_GetTraceback (PyObject *ex)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the traceback associated with the exception as a new reference, as
accessible from Python through the @ref{12a4,,__traceback__}
attribute. If there is no
traceback associated, this returns @code{NULL}.
@end deffn

@geindex PyException_SetTraceback (C function)
@anchor{c-api/exceptions c PyException_SetTraceback}@anchor{1978}
@deffn {C Fonction} int PyException_SetTraceback (PyObject *ex, PyObject *tb)
` Part of the @ref{53e,,Stable ABI}.'
Set the traceback associated with the exception to `tb'.  Use @code{Py_None} to
clear it.
@end deffn

@geindex PyException_GetContext (C function)
@anchor{c-api/exceptions c PyException_GetContext}@anchor{48bd}
@deffn {C Fonction} @ref{32f,,PyObject} *PyException_GetContext (PyObject *ex)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the context (another exception instance during whose handling `ex' was
raised) associated with the exception as a new reference, as accessible from
Python through the @ref{12a5,,__context__} attribute.
If there is no context associated, this returns @code{NULL}.
@end deffn

@geindex PyException_SetContext (C function)
@anchor{c-api/exceptions c PyException_SetContext}@anchor{48c0}
@deffn {C Fonction} void PyException_SetContext (PyObject *ex, PyObject *ctx)
` Part of the @ref{53e,,Stable ABI}.'
Set the context associated with the exception to `ctx'.  Use @code{NULL} to clear
it.  There is no type check to make sure that `ctx' is an exception instance.
This steals a reference to `ctx'.
@end deffn

@geindex PyException_GetCause (C function)
@anchor{c-api/exceptions c PyException_GetCause}@anchor{48bc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyException_GetCause (PyObject *ex)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the cause (either an exception instance, or @code{None},
set by @code{raise ... from ...}) associated with the exception as a new
reference, as accessible from Python through the
@ref{12a6,,__cause__} attribute.
@end deffn

@geindex PyException_SetCause (C function)
@anchor{c-api/exceptions c PyException_SetCause}@anchor{48bf}
@deffn {C Fonction} void PyException_SetCause (PyObject *ex, PyObject *cause)
` Part of the @ref{53e,,Stable ABI}.'
Set the cause associated with the exception to `cause'.  Use @code{NULL} to clear
it.  There is no type check to make sure that `cause' is either an exception
instance or @code{None}.  This steals a reference to `cause'.

The @ref{2037,,__suppress_context__} attribute is implicitly set
to @code{True} by this function.
@end deffn

@geindex PyException_GetArgs (C function)
@anchor{c-api/exceptions c PyException_GetArgs}@anchor{556}
@deffn {C Fonction} @ref{32f,,PyObject} *PyException_GetArgs (PyObject *ex)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Return @ref{558,,args} of exception `ex'.
@end deffn

@geindex PyException_SetArgs (C function)
@anchor{c-api/exceptions c PyException_SetArgs}@anchor{557}
@deffn {C Fonction} void PyException_SetArgs (PyObject *ex, PyObject *args)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Set @ref{558,,args} of exception `ex' to `args'.
@end deffn

@geindex PyUnstable_Exc_PrepReraiseStar (C function)
@anchor{c-api/exceptions c PyUnstable_Exc_PrepReraiseStar}@anchor{49f6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnstable_Exc_PrepReraiseStar (PyObject *orig, PyObject *excs)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Implement part of the interpreter's implementation of @code{except*}.
`orig' is the original exception that was caught, and `excs' is the list of
the exceptions that need to be raised. This list contains the unhandled
part of `orig', if any, as well as the exceptions that were raised from the
@code{except*} clauses (so they have a different traceback from `orig') and
those that were reraised (and have the same traceback as `orig').
Return the @ref{1b4,,ExceptionGroup} that needs to be reraised in the end, or
@code{None} if there is nothing to reraise.


Ajouté dans la version 3.12.

@end deffn

@node Objets exception Unicode,Contrôle de la récursion,Objets exception,Gestion des exceptions<2>
@anchor{c-api/exceptions unicode-exception-objects}@anchor{49f7}@anchor{c-api/exceptions unicodeexceptions}@anchor{49f8}
@subsection Objets exception Unicode


The following functions are used to create and modify Unicode exceptions from C.

@geindex PyUnicodeDecodeError_Create (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_Create}@anchor{4962}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicodeDecodeError_Create (const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a @ref{a01,,UnicodeDecodeError} object with the attributes `encoding',
`object', `length', `start', `end' and `reason'. `encoding' and `reason' are
UTF-8 encoded strings.
@end deffn

@geindex PyUnicodeDecodeError_GetEncoding (C function)
@geindex PyUnicodeEncodeError_GetEncoding (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_GetEncoding}@anchor{4963}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicodeDecodeError_GetEncoding (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetEncoding}@anchor{496b}
@deffnx {C Fonction} @ref{32f,,PyObject} *PyUnicodeEncodeError_GetEncoding (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the `encoding' attribute of the given exception object.
@end deffn

@geindex PyUnicodeDecodeError_GetObject (C function)
@geindex PyUnicodeEncodeError_GetObject (C function)
@geindex PyUnicodeTranslateError_GetObject (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_GetObject}@anchor{4965}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicodeDecodeError_GetObject (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetObject}@anchor{496d}
@deffnx {C Fonction} @ref{32f,,PyObject} *PyUnicodeEncodeError_GetObject (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetObject}@anchor{4974}
@deffnx {C Fonction} @ref{32f,,PyObject} *PyUnicodeTranslateError_GetObject (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the `object' attribute of the given exception object.
@end deffn

@geindex PyUnicodeDecodeError_GetStart (C function)
@geindex PyUnicodeEncodeError_GetStart (C function)
@geindex PyUnicodeTranslateError_GetStart (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_GetStart}@anchor{4967}
@deffn {C Fonction} int PyUnicodeDecodeError_GetStart (PyObject *exc, Py_ssize_t *start)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetStart}@anchor{496f}
@deffnx {C Fonction} int PyUnicodeEncodeError_GetStart (PyObject *exc, Py_ssize_t *start)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetStart}@anchor{4976}
@deffnx {C Fonction} int PyUnicodeTranslateError_GetStart (PyObject *exc, Py_ssize_t *start)
` Part of the @ref{53e,,Stable ABI}.'
Get the `start' attribute of the given exception object and place it into
`*start'.  `start' must not be @code{NULL}.  Return @code{0} on success, @code{-1} on
failure.
@end deffn

@geindex PyUnicodeDecodeError_SetStart (C function)
@geindex PyUnicodeEncodeError_SetStart (C function)
@geindex PyUnicodeTranslateError_SetStart (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_SetStart}@anchor{496a}
@deffn {C Fonction} int PyUnicodeDecodeError_SetStart (PyObject *exc, Py_ssize_t start)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetStart}@anchor{4972}
@deffnx {C Fonction} int PyUnicodeEncodeError_SetStart (PyObject *exc, Py_ssize_t start)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetStart}@anchor{4979}
@deffnx {C Fonction} int PyUnicodeTranslateError_SetStart (PyObject *exc, Py_ssize_t start)
` Part of the @ref{53e,,Stable ABI}.'
Set the `start' attribute of the given exception object to `start'.  Return
@code{0} on success, @code{-1} on failure.
@end deffn

@geindex PyUnicodeDecodeError_GetEnd (C function)
@geindex PyUnicodeEncodeError_GetEnd (C function)
@geindex PyUnicodeTranslateError_GetEnd (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_GetEnd}@anchor{4964}
@deffn {C Fonction} int PyUnicodeDecodeError_GetEnd (PyObject *exc, Py_ssize_t *end)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetEnd}@anchor{496c}
@deffnx {C Fonction} int PyUnicodeEncodeError_GetEnd (PyObject *exc, Py_ssize_t *end)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetEnd}@anchor{4973}
@deffnx {C Fonction} int PyUnicodeTranslateError_GetEnd (PyObject *exc, Py_ssize_t *end)
` Part of the @ref{53e,,Stable ABI}.'
Get the `end' attribute of the given exception object and place it into
`*end'.  `end' must not be @code{NULL}.  Return @code{0} on success, @code{-1} on
failure.
@end deffn

@geindex PyUnicodeDecodeError_SetEnd (C function)
@geindex PyUnicodeEncodeError_SetEnd (C function)
@geindex PyUnicodeTranslateError_SetEnd (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_SetEnd}@anchor{4968}
@deffn {C Fonction} int PyUnicodeDecodeError_SetEnd (PyObject *exc, Py_ssize_t end)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetEnd}@anchor{4970}
@deffnx {C Fonction} int PyUnicodeEncodeError_SetEnd (PyObject *exc, Py_ssize_t end)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetEnd}@anchor{4977}
@deffnx {C Fonction} int PyUnicodeTranslateError_SetEnd (PyObject *exc, Py_ssize_t end)
` Part of the @ref{53e,,Stable ABI}.'
Set the `end' attribute of the given exception object to `end'.  Return @code{0}
on success, @code{-1} on failure.
@end deffn

@geindex PyUnicodeDecodeError_GetReason (C function)
@geindex PyUnicodeEncodeError_GetReason (C function)
@geindex PyUnicodeTranslateError_GetReason (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_GetReason}@anchor{4966}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicodeDecodeError_GetReason (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeEncodeError_GetReason}@anchor{496e}
@deffnx {C Fonction} @ref{32f,,PyObject} *PyUnicodeEncodeError_GetReason (PyObject *exc)
@anchor{c-api/exceptions c PyUnicodeTranslateError_GetReason}@anchor{4975}
@deffnx {C Fonction} @ref{32f,,PyObject} *PyUnicodeTranslateError_GetReason (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the `reason' attribute of the given exception object.
@end deffn

@geindex PyUnicodeDecodeError_SetReason (C function)
@geindex PyUnicodeEncodeError_SetReason (C function)
@geindex PyUnicodeTranslateError_SetReason (C function)
@anchor{c-api/exceptions c PyUnicodeDecodeError_SetReason}@anchor{4969}
@deffn {C Fonction} int PyUnicodeDecodeError_SetReason (PyObject *exc, const char *reason)
@anchor{c-api/exceptions c PyUnicodeEncodeError_SetReason}@anchor{4971}
@deffnx {C Fonction} int PyUnicodeEncodeError_SetReason (PyObject *exc, const char *reason)
@anchor{c-api/exceptions c PyUnicodeTranslateError_SetReason}@anchor{4978}
@deffnx {C Fonction} int PyUnicodeTranslateError_SetReason (PyObject *exc, const char *reason)
` Part of the @ref{53e,,Stable ABI}.'
Set the `reason' attribute of the given exception object to `reason'.  Return
@code{0} on success, @code{-1} on failure.
@end deffn

@node Contrôle de la récursion,Exceptions standards,Objets exception Unicode,Gestion des exceptions<2>
@anchor{c-api/exceptions recursion}@anchor{49f9}@anchor{c-api/exceptions recursion-control}@anchor{49fa}
@subsection Contrôle de la récursion


These two functions provide a way to perform safe recursive calls at the C
level, both in the core and in extension modules.  They are needed if the
recursive code does not necessarily invoke Python code (which tracks its
recursion depth automatically).
They are also not needed for `tp_call' implementations
because the @ref{56f,,call protocol} takes care of recursion handling.

@geindex Py_EnterRecursiveCall (C function)
@anchor{c-api/exceptions c Py_EnterRecursiveCall}@anchor{960}
@deffn {C Fonction} int Py_EnterRecursiveCall (const char *where)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Marks a point where a recursive C-level call is about to be performed.

If @code{USE_STACKCHECK} is defined, this function checks if the OS
stack overflowed using @ref{17a4,,PyOS_CheckStack()}.  If this is the case, it
sets a @ref{164b,,MemoryError} and returns a nonzero value.

The function then checks if the recursion limit is reached.  If this is the
case, a @ref{d59,,RecursionError} is set and a nonzero value is returned.
Otherwise, zero is returned.

`where' should be a UTF-8 encoded string such as @code{" in instance check"} to
be concatenated to the @ref{d59,,RecursionError} message caused by the recursion
depth limit.


Modifié dans la version 3.9: This function is now also available in the @ref{38c,,limited API}.

@end deffn

@geindex Py_LeaveRecursiveCall (C function)
@anchor{c-api/exceptions c Py_LeaveRecursiveCall}@anchor{961}
@deffn {C Fonction} void Py_LeaveRecursiveCall (void)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Ends a @ref{960,,Py_EnterRecursiveCall()}.  Must be called once for each
`successful' invocation of @ref{960,,Py_EnterRecursiveCall()}.


Modifié dans la version 3.9: This function is now also available in the @ref{38c,,limited API}.

@end deffn

Properly implementing @ref{4803,,tp_repr} for container types requires
special recursion handling.  In addition to protecting the stack,
@ref{4803,,tp_repr} also needs to track objects to prevent cycles.  The
following two functions facilitate this functionality.  Effectively,
these are the C equivalent to @ref{11d0,,reprlib.recursive_repr()}.

@geindex Py_ReprEnter (C function)
@anchor{c-api/exceptions c Py_ReprEnter}@anchor{49a9}
@deffn {C Fonction} int Py_ReprEnter (PyObject *object)
` Part of the @ref{53e,,Stable ABI}.'
Called at the beginning of the @ref{4803,,tp_repr} implementation to
detect cycles.

If the object has already been processed, the function returns a
positive integer.  In that case the @ref{4803,,tp_repr} implementation
should return a string object indicating a cycle.  As examples,
@ref{253,,dict} objects return @code{@{...@}} and @ref{5fc,,list} objects
return @code{[...]}.

The function will return a negative integer if the recursion limit
is reached.  In that case the @ref{4803,,tp_repr} implementation should
typically return @code{NULL}.

Otherwise, the function returns zero and the @ref{4803,,tp_repr}
implementation can continue normally.
@end deffn

@geindex Py_ReprLeave (C function)
@anchor{c-api/exceptions c Py_ReprLeave}@anchor{49aa}
@deffn {C Fonction} void Py_ReprLeave (PyObject *object)
` Part of the @ref{53e,,Stable ABI}.'
Ends a @ref{49a9,,Py_ReprEnter()}.  Must be called once for each
invocation of @ref{49a9,,Py_ReprEnter()} that returns zero.
@end deffn

@node Exceptions standards,Standard Warning Categories,Contrôle de la récursion,Gestion des exceptions<2>
@anchor{c-api/exceptions standard-exceptions}@anchor{49fb}@anchor{c-api/exceptions standardexceptions}@anchor{49fc}
@subsection Exceptions standards


All standard Python exceptions are available as global variables whose names are
@code{PyExc_} followed by the Python exception name.  These have the type
@ref{32f,,PyObject}*; they are all class objects.  For completeness, here are all
the variables:

@geindex PyExc_BaseException (C var)
@geindex PyExc_Exception (C var)
@geindex PyExc_ArithmeticError (C var)
@geindex PyExc_AssertionError (C var)
@geindex PyExc_AttributeError (C var)
@geindex PyExc_BlockingIOError (C var)
@geindex PyExc_BrokenPipeError (C var)
@geindex PyExc_BufferError (C var)
@geindex PyExc_ChildProcessError (C var)
@geindex PyExc_ConnectionAbortedError (C var)
@geindex PyExc_ConnectionError (C var)
@geindex PyExc_ConnectionRefusedError (C var)
@geindex PyExc_ConnectionResetError (C var)
@geindex PyExc_EOFError (C var)
@geindex PyExc_FileExistsError (C var)
@geindex PyExc_FileNotFoundError (C var)
@geindex PyExc_FloatingPointError (C var)
@geindex PyExc_GeneratorExit (C var)
@geindex PyExc_ImportError (C var)
@geindex PyExc_IndentationError (C var)
@geindex PyExc_IndexError (C var)
@geindex PyExc_InterruptedError (C var)
@geindex PyExc_IsADirectoryError (C var)
@geindex PyExc_KeyError (C var)
@geindex PyExc_KeyboardInterrupt (C var)
@geindex PyExc_LookupError (C var)
@geindex PyExc_MemoryError (C var)
@geindex PyExc_ModuleNotFoundError (C var)
@geindex PyExc_NameError (C var)
@geindex PyExc_NotADirectoryError (C var)
@geindex PyExc_NotImplementedError (C var)
@geindex PyExc_OSError (C var)
@geindex PyExc_OverflowError (C var)
@geindex PyExc_PermissionError (C var)
@geindex PyExc_ProcessLookupError (C var)
@geindex PyExc_PythonFinalizationError (C var)
@geindex PyExc_RecursionError (C var)
@geindex PyExc_ReferenceError (C var)
@geindex PyExc_RuntimeError (C var)
@geindex PyExc_StopAsyncIteration (C var)
@geindex PyExc_StopIteration (C var)
@geindex PyExc_SyntaxError (C var)
@geindex PyExc_SystemError (C var)
@geindex PyExc_SystemExit (C var)
@geindex PyExc_TabError (C var)
@geindex PyExc_TimeoutError (C var)
@geindex PyExc_TypeError (C var)
@geindex PyExc_UnboundLocalError (C var)
@geindex PyExc_UnicodeDecodeError (C var)
@geindex PyExc_UnicodeEncodeError (C var)
@geindex PyExc_UnicodeError (C var)
@geindex PyExc_UnicodeTranslateError (C var)
@geindex PyExc_ValueError (C var)
@geindex PyExc_ZeroDivisionError (C var)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Nom C

@tab

Nom Python

@tab

Notes

@item

@code{PyExc_BaseException}

@tab

@ref{5a5,,BaseException}

@tab

@footnote{
C'est la classe de base pour les autres exceptions standards.
}

@item

@code{PyExc_Exception}

@tab

@ref{9c7,,Exception}

@tab

@footnote{
C'est la classe de base pour les autres exceptions standards.
}

@item

@code{PyExc_ArithmeticError}

@tab

@ref{220d,,ArithmeticError}

@tab

@footnote{
C'est la classe de base pour les autres exceptions standards.
}

@item

@code{PyExc_AssertionError}

@tab

@ref{694,,AssertionError}

@tab

@item

@code{PyExc_AttributeError}

@tab

@ref{343,,AttributeError}

@tab

@item

@code{PyExc_BlockingIOError}

@tab

@ref{1040,,BlockingIOError}

@tab

@item

@code{PyExc_BrokenPipeError}

@tab

@ref{1045,,BrokenPipeError}

@tab

@item

@code{PyExc_BufferError}

@tab

@ref{17b2,,BufferError}

@tab

@item

@code{PyExc_ChildProcessError}

@tab

@ref{1041,,ChildProcessError}

@tab

@item

@code{PyExc_ConnectionAbortedError}

@tab

@ref{1046,,ConnectionAbortedError}

@tab

@item

@code{PyExc_ConnectionError}

@tab

@ref{df7,,ConnectionError}

@tab

@item

@code{PyExc_ConnectionRefusedError}

@tab

@ref{1047,,ConnectionRefusedError}

@tab

@item

@code{PyExc_ConnectionResetError}

@tab

@ref{1048,,ConnectionResetError}

@tab

@item

@code{PyExc_EOFError}

@tab

@ref{12b7,,EOFError}

@tab

@item

@code{PyExc_FileExistsError}

@tab

@ref{1009,,FileExistsError}

@tab

@item

@code{PyExc_FloatingPointError}

@tab

@ref{eae,,FileNotFoundError}

@tab

@item

@code{PyExc_FloatingPointError}

@tab

@ref{220e,,FloatingPointError}

@tab

@item

@code{PyExc_GeneratorExit}

@tab

@ref{137e,,GeneratorExit}

@tab

@item

@code{PyExc_ImportError}

@tab

@ref{40f,,ImportError}

@tab

@item

@code{PyExc_IndentationError}

@tab

@ref{792,,IndentationError}

@tab

@item

@code{PyExc_IndexError}

@tab

@ref{14eb,,IndexError}

@tab

@item

@code{PyExc_InterruptedError}

@tab

@ref{d75,,InterruptedError}

@tab

@item

@code{PyExc_IsADirectoryError}

@tab

@ref{1042,,IsADirectoryError}

@tab

@item

@code{PyExc_KeyError}

@tab

@ref{33a,,KeyError}

@tab

@item

@code{PyExc_KeyboardInterrupt}

@tab

@ref{9bf,,KeyboardInterrupt}

@tab

@item

@code{PyExc_LookupError}

@tab

@ref{2155,,LookupError}

@tab

@footnote{
C'est la classe de base pour les autres exceptions standards.
}

@item

@code{PyExc_MemoryError}

@tab

@ref{164b,,MemoryError}

@tab

@item

@code{PyExc_ModuleNotFoundError}

@tab

@ref{b35,,ModuleNotFoundError}

@tab

@item

@code{PyExc_NameError}

@tab

@ref{428,,NameError}

@tab

@item

@code{PyExc_NotADirectoryError}

@tab

@ref{1043,,NotADirectoryError}

@tab

@item

@code{PyExc_NotImplementedError}

@tab

@ref{225,,NotImplementedError}

@tab

@item

@code{PyExc_OSError}

@tab

@ref{40d,,OSError}

@tab

@footnote{
C'est la classe de base pour les autres exceptions standards.
}

@item

@code{PyExc_OverflowError}

@tab

@ref{86d,,OverflowError}

@tab

@item

@code{PyExc_PermissionError}

@tab

@ref{d30,,PermissionError}

@tab

@item

@code{PyExc_ProcessLookupError}

@tab

@ref{1044,,ProcessLookupError}

@tab

@item

@code{PyExc_PythonFinalizationError}

@tab

@ref{14c,,PythonFinalizationError}

@tab

@item

@code{PyExc_ReferenceError}

@tab

@ref{d59,,RecursionError}

@tab

@item

@code{PyExc_ReferenceError}

@tab

@ref{14c5,,ReferenceError}

@tab

@item

@code{PyExc_RuntimeError}

@tab

@ref{193,,RuntimeError}

@tab

@item

@code{PyExc_StopAsyncIteration}

@tab

@ref{19bb,,StopAsyncIteration}

@tab

@item

@code{PyExc_StopIteration}

@tab

@ref{be8,,StopIteration}

@tab

@item

@code{PyExc_SyntaxError}

@tab

@ref{18b,,SyntaxError}

@tab

@item

@code{PyExc_SystemError}

@tab

@ref{561,,SystemError}

@tab

@item

@code{PyExc_SystemExit}

@tab

@ref{d2e,,SystemExit}

@tab

@item

@code{PyExc_TabError}

@tab

@ref{52e,,TabError}

@tab

@item

@code{PyExc_ImportError}

@tab

@ref{81f,,TimeoutError}

@tab

@item

@code{PyExc_TypeError}

@tab

@ref{522,,TypeError}

@tab

@item

@code{PyExc_UnboundLocalError}

@tab

@ref{14ec,,UnboundLocalError}

@tab

@item

@code{PyExc_UnicodeDecodeError}

@tab

@ref{a01,,UnicodeDecodeError}

@tab

@item

@code{PyExc_UnicodeEncodeError}

@tab

@ref{662,,UnicodeEncodeError}

@tab

@item

@code{PyExc_UnicodeError}

@tab

@ref{1281,,UnicodeError}

@tab

@item

@code{PyExc_UnicodeTranslateError}

@tab

@ref{2224,,UnicodeTranslateError}

@tab

@item

@code{PyExc_ValueError}

@tab

@ref{1ff,,ValueError}

@tab

@item

@code{PyExc_ZeroDivisionError}

@tab

@ref{932,,ZeroDivisionError}

@tab

@end multitable



Ajouté dans la version 3.3: @code{PyExc_BlockingIOError}, @code{PyExc_BrokenPipeError},
@code{PyExc_ChildProcessError}, @code{PyExc_ConnectionError},
@code{PyExc_ConnectionAbortedError}, @code{PyExc_ConnectionRefusedError},
@code{PyExc_ConnectionResetError}, @code{PyExc_FileExistsError},
@code{PyExc_FileNotFoundError}, @code{PyExc_InterruptedError},
@code{PyExc_IsADirectoryError}, @code{PyExc_NotADirectoryError},
@code{PyExc_PermissionError}, @code{PyExc_ProcessLookupError}
and @code{PyExc_TimeoutError} were introduced following 
@geindex Python Enhancement Proposals; PEP 3151
PEP 3151@footnote{https://peps.python.org/pep-3151/}.



Ajouté dans la version 3.5: @code{PyExc_StopAsyncIteration} et @code{PyExc_RecursionError}.



Ajouté dans la version 3.6: @code{PyExc_ModuleNotFoundError}.


These are compatibility aliases to @code{PyExc_OSError}:

@geindex PyExc_EnvironmentError (C var)
@geindex PyExc_IOError (C var)
@geindex PyExc_WindowsError (C var)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Nom C

@tab

Notes

@item

@code{PyExc_EnvironmentError}

@tab

@item

@code{PyExc_IOError}

@tab

@item

@code{PyExc_WindowsError}

@tab

@footnote{
Only defined on Windows; protect code that uses this by testing that the
preprocessor macro @code{MS_WINDOWS} is defined.
}

@end multitable



Modifié dans la version 3.3: These aliases used to be separate exception types.


Notes :

@node Standard Warning Categories,,Exceptions standards,Gestion des exceptions<2>
@anchor{c-api/exceptions standard-warning-categories}@anchor{49fd}@anchor{c-api/exceptions standardwarningcategories}@anchor{49f0}
@subsection Standard Warning Categories


All standard Python warning categories are available as global variables whose
names are @code{PyExc_} followed by the Python exception name. These have the type
@ref{32f,,PyObject}*; they are all class objects. For completeness, here are all
the variables:

@geindex PyExc_Warning (C var)
@geindex PyExc_BytesWarning (C var)
@geindex PyExc_DeprecationWarning (C var)
@geindex PyExc_FutureWarning (C var)
@geindex PyExc_ImportWarning (C var)
@geindex PyExc_PendingDeprecationWarning (C var)
@geindex PyExc_ResourceWarning (C var)
@geindex PyExc_RuntimeWarning (C var)
@geindex PyExc_SyntaxWarning (C var)
@geindex PyExc_UnicodeWarning (C var)
@geindex PyExc_UserWarning (C var)


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 
@headitem

Nom C

@tab

Nom Python

@tab

Notes

@item

@code{PyExc_Warning}

@tab

@ref{2239,,Warning}

@tab

@footnote{
C'est la classe de base pour les autres catégories de `warning'.
}

@item

@code{PyExc_BytesWarning}

@tab

@ref{c11,,BytesWarning}

@tab

@item

@code{PyExc_DeprecationWarning}

@tab

@ref{1a3,,DeprecationWarning}

@tab

@item

@code{PyExc_FutureWarning}

@tab

@ref{40b,,FutureWarning}

@tab

@item

@code{PyExc_ImportWarning}

@tab

@ref{4e4,,ImportWarning}

@tab

@item

@code{PyExc_PendingDeprecationWarning}

@tab

@ref{8b5,,PendingDeprecationWarning}

@tab

@item

@code{PyExc_ResourceWarning}

@tab

@ref{241,,ResourceWarning}

@tab

@item

@code{PyExc_RuntimeWarning}

@tab

@ref{1bb,,RuntimeWarning}

@tab

@item

@code{PyExc_SyntaxWarning}

@tab

@ref{44f,,SyntaxWarning}

@tab

@item

@code{PyExc_UnicodeWarning}

@tab

@ref{13da,,UnicodeWarning}

@tab

@item

@code{PyExc_UserWarning}

@tab

@ref{223a,,UserWarning}

@tab

@end multitable



Ajouté dans la version 3.2: @code{PyExc_ResourceWarning}.


Notes :

@node Utilitaires<2>,Couche d'abstraction des objets,Gestion des exceptions<2>,Manuel de référence de l'API Python/C
@anchor{c-api/utilities doc}@anchor{49fe}@anchor{c-api/utilities id1}@anchor{49ff}@anchor{c-api/utilities utilities}@anchor{4a00}
@section Utilitaires


Les fonctions de ce chapitre sont utilitaires, certaines aident à rendre le code en C plus portable, d'autres à utiliser des modules Python depuis du C, analyser des arguments de fonctions, ou encore construire des valeurs Python à partir de valeurs C.

@menu
* Operating System Utilities:: 
* System Functions:: 
* Process Control:: 
* Importer des modules: Importer des modules<2>. 
* Data marshalling support:: 
* Analyse des arguments et construction des valeurs:: 
* Conversion et formatage de chaînes:: 
* PyHash API:: 
* Réflexion:: 
* Codec registry and support functions:: 
* PyTime C API:: 
* Support for Perf Maps:: 

@end menu

@node Operating System Utilities,System Functions,,Utilitaires<2>
@anchor{c-api/sys doc}@anchor{4a01}@anchor{c-api/sys operating-system-utilities}@anchor{4a02}@anchor{c-api/sys os}@anchor{4a03}
@subsection Operating System Utilities


@geindex PyOS_FSPath (C function)
@anchor{c-api/sys c PyOS_FSPath}@anchor{d06}
@deffn {C Fonction} @ref{32f,,PyObject} *PyOS_FSPath (PyObject *path)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.6.'
Return the file system representation for `path'. If the object is a
@ref{435,,str} or @ref{1bd,,bytes} object, then a new
@ref{333,,strong reference} is returned.
If the object implements the @ref{c3f,,os.PathLike} interface,
then @ref{c40,,__fspath__()} is returned as long as it is a
@ref{435,,str} or @ref{1bd,,bytes} object. Otherwise @ref{522,,TypeError} is raised
and @code{NULL} is returned.


Ajouté dans la version 3.6.

@end deffn

@geindex Py_FdIsInteractive (C function)
@anchor{c-api/sys c Py_FdIsInteractive}@anchor{4a04}
@deffn {C Fonction} int Py_FdIsInteractive (FILE *fp, const char *filename)

Return true (nonzero) if the standard I/O file `fp' with name `filename' is
deemed interactive.  This is the case for files for which @code{isatty(fileno(fp))}
is true.  If the @ref{3c4,,PyConfig.interactive} is non-zero, this function
also returns true if the `filename' pointer is @code{NULL} or if the name is equal to
one of the strings @code{'<stdin>'} or @code{'???'}.

This function must not be called before Python is initialized.
@end deffn

@geindex PyOS_BeforeFork (C function)
@anchor{c-api/sys c PyOS_BeforeFork}@anchor{bad}
@deffn {C Fonction} void PyOS_BeforeFork ()
` Part of the @ref{53e,,Stable ABI} on platforms with fork() Depuis la version 3.7.'
Function to prepare some internal state before a process fork.  This
should be called before calling @code{fork()} or any similar function
that clones the current process.
Only available on systems where @code{fork()} is defined.

@cartouche
@quotation Avertissement 
The C @code{fork()} call should only be made from the
@ref{4a05,,"main" thread} (of the
@ref{573,,"main" interpreter}).  The same is
true for @code{PyOS_BeforeFork()}.
@end quotation
@end cartouche


Ajouté dans la version 3.7.

@end deffn

@geindex PyOS_AfterFork_Parent (C function)
@anchor{c-api/sys c PyOS_AfterFork_Parent}@anchor{bae}
@deffn {C Fonction} void PyOS_AfterFork_Parent ()
` Part of the @ref{53e,,Stable ABI} on platforms with fork() Depuis la version 3.7.'
Function to update some internal state after a process fork.  This
should be called from the parent process after calling @code{fork()}
or any similar function that clones the current process, regardless
of whether process cloning was successful.
Only available on systems where @code{fork()} is defined.

@cartouche
@quotation Avertissement 
The C @code{fork()} call should only be made from the
@ref{4a05,,"main" thread} (of the
@ref{573,,"main" interpreter}).  The same is
true for @code{PyOS_AfterFork_Parent()}.
@end quotation
@end cartouche


Ajouté dans la version 3.7.

@end deffn

@geindex PyOS_AfterFork_Child (C function)
@anchor{c-api/sys c PyOS_AfterFork_Child}@anchor{3f1}
@deffn {C Fonction} void PyOS_AfterFork_Child ()
` Part of the @ref{53e,,Stable ABI} on platforms with fork() Depuis la version 3.7.'
Function to update internal interpreter state after a process fork.
This must be called from the child process after calling @code{fork()},
or any similar function that clones the current process, if there is
any chance the process will call back into the Python interpreter.
Only available on systems where @code{fork()} is defined.

@cartouche
@quotation Avertissement 
The C @code{fork()} call should only be made from the
@ref{4a05,,"main" thread} (of the
@ref{573,,"main" interpreter}).  The same is
true for @code{PyOS_AfterFork_Child()}.
@end quotation
@end cartouche


Ajouté dans la version 3.7.



@subsubheading Voir aussi


@ref{2f4,,os.register_at_fork()} allows registering custom Python functions
to be called by @ref{bad,,PyOS_BeforeFork()},
@ref{bae,,PyOS_AfterFork_Parent()} and  @ref{3f1,,PyOS_AfterFork_Child()}.

@end deffn

@geindex PyOS_AfterFork (C function)
@anchor{c-api/sys c PyOS_AfterFork}@anchor{3f0}
@deffn {C Fonction} void PyOS_AfterFork ()
` Part of the @ref{53e,,Stable ABI} on platforms with fork().'
Function to update some internal state after a process fork; this should be
called in the new process if the Python interpreter will continue to be used.
If a new executable is loaded into the new process, this function does not need
to be called.


Obsolète depuis la version 3.7: This function is superseded by @ref{3f1,,PyOS_AfterFork_Child()}.

@end deffn

@geindex PyOS_CheckStack (C function)
@anchor{c-api/sys c PyOS_CheckStack}@anchor{17a4}
@deffn {C Fonction} int PyOS_CheckStack ()
` Part of the @ref{53e,,Stable ABI} on platforms with USE_STACKCHECK Depuis la version 3.7.'
@geindex USE_STACKCHECK (C macro)

Return true when the interpreter runs out of stack space.  This is a reliable
check, but is only available when @code{USE_STACKCHECK} is defined (currently
on certain versions of Windows using the Microsoft Visual C++ compiler).
@code{USE_STACKCHECK} will be defined automatically; you should never
change the definition in your own code.
@end deffn

@geindex PyOS_sighandler_t (C type)
@anchor{c-api/sys c PyOS_sighandler_t}@anchor{491a}
@deffn {C Type} typedef void (*PyOS_sighandler_t)(int)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyOS_getsig (C function)
@anchor{c-api/sys c PyOS_getsig}@anchor{14f4}
@deffn {C Fonction} @ref{491a,,PyOS_sighandler_t} PyOS_getsig (int i)
` Part of the @ref{53e,,Stable ABI}.'
Return the current signal handler for signal `i'.  This is a thin wrapper around
either @code{sigaction()} or @code{signal()}.  Do not call those functions
directly!
@end deffn

@geindex PyOS_setsig (C function)
@anchor{c-api/sys c PyOS_setsig}@anchor{14f5}
@deffn {C Fonction} @ref{491a,,PyOS_sighandler_t} PyOS_setsig (int i, PyOS_sighandler_t h)
` Part of the @ref{53e,,Stable ABI}.'
Set the signal handler for signal `i' to be `h'; return the old signal handler.
This is a thin wrapper around either @code{sigaction()} or @code{signal()}.  Do
not call those functions directly!
@end deffn

@geindex Py_DecodeLocale (C function)
@anchor{c-api/sys c Py_DecodeLocale}@anchor{bb5}
@deffn {C Fonction} wchar_t *Py_DecodeLocale (const char *arg, size_t *size)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
@cartouche
@quotation Avertissement 
This function should not be called directly: use the @ref{39d,,PyConfig}
API with the @ref{9a2,,PyConfig_SetBytesString()} function which ensures
that @ref{3c7c,,Python is preinitialized}.

This function must not be called before @ref{3c7c,,Python is preinitialized} and so that the LC_CTYPE locale is properly configured: see
the @ref{3e2,,Py_PreInitialize()} function.
@end quotation
@end cartouche

Decode a byte string from the @ref{525,,filesystem encoding and error handler}.
If the error handler is @ref{236b,,surrogateescape error handler}, undecodable bytes are decoded as characters in range
U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate
character, the bytes are escaped using the surrogateescape error handler
instead of decoding them.

Return a pointer to a newly allocated wide character string, use
@ref{389,,PyMem_RawFree()} to free the memory. If size is not @code{NULL}, write
the number of wide characters excluding the null character into @code{*size}

Return @code{NULL} on decoding error or memory allocation error. If `size' is
not @code{NULL}, @code{*size} is set to @code{(size_t)-1} on memory error or set to
@code{(size_t)-2} on decoding error.

The @ref{525,,filesystem encoding and error handler} are selected by
@ref{77a,,PyConfig_Read()}: see @ref{3df,,filesystem_encoding} and
@ref{3e0,,filesystem_errors} members of @ref{39d,,PyConfig}.

Decoding errors should never happen, unless there is a bug in the C
library.

Use the @ref{bb6,,Py_EncodeLocale()} function to encode the character string
back to a byte string.


@subsubheading Voir aussi


The @ref{4982,,PyUnicode_DecodeFSDefaultAndSize()} and
@ref{bb7,,PyUnicode_DecodeLocaleAndSize()} functions.



Ajouté dans la version 3.5.



Modifié dans la version 3.7: The function now uses the UTF-8 encoding in the @ref{641,,Python UTF-8 Mode}.



Modifié dans la version 3.8: The function now uses the UTF-8 encoding on Windows if
@ref{3dd,,PyPreConfig.legacy_windows_fs_encoding} is zero;

@end deffn

@geindex Py_EncodeLocale (C function)
@anchor{c-api/sys c Py_EncodeLocale}@anchor{bb6}
@deffn {C Fonction} char *Py_EncodeLocale (const wchar_t *text, size_t *error_pos)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Encode a wide character string to the @ref{525,,filesystem encoding and error handler}. If the error handler is @ref{236b,,surrogateescape error handler}, surrogate characters in the range U+DC80..U+DCFF are
converted to bytes 0x80..0xFF.

Return a pointer to a newly allocated byte string, use @ref{13f9,,PyMem_Free()}
to free the memory. Return @code{NULL} on encoding error or memory allocation
error.

If error_pos is not @code{NULL}, @code{*error_pos} is set to @code{(size_t)-1} on
success,  or set to the index of the invalid character on encoding error.

The @ref{525,,filesystem encoding and error handler} are selected by
@ref{77a,,PyConfig_Read()}: see @ref{3df,,filesystem_encoding} and
@ref{3e0,,filesystem_errors} members of @ref{39d,,PyConfig}.

Use the @ref{bb5,,Py_DecodeLocale()} function to decode the bytes string back
to a wide character string.

@cartouche
@quotation Avertissement 
This function must not be called before @ref{3c7c,,Python is preinitialized} and so that the LC_CTYPE locale is properly configured: see
the @ref{3e2,,Py_PreInitialize()} function.
@end quotation
@end cartouche


@subsubheading Voir aussi


The @ref{19df,,PyUnicode_EncodeFSDefault()} and
@ref{bb8,,PyUnicode_EncodeLocale()} functions.



Ajouté dans la version 3.5.



Modifié dans la version 3.7: The function now uses the UTF-8 encoding in the @ref{641,,Python UTF-8 Mode}.



Modifié dans la version 3.8: The function now uses the UTF-8 encoding on Windows if
@ref{3dd,,PyPreConfig.legacy_windows_fs_encoding} is zero.

@end deffn

@node System Functions,Process Control,Operating System Utilities,Utilitaires<2>
@anchor{c-api/sys system-functions}@anchor{4a06}@anchor{c-api/sys systemfunctions}@anchor{4a07}
@subsection System Functions


These are utility functions that make functionality from the @ref{d8,,sys} module
accessible to C code.  They all work with the current interpreter thread's
@ref{d8,,sys} module's dict, which is contained in the internal thread state structure.

@geindex PySys_GetObject (C function)
@anchor{c-api/sys c PySys_GetObject}@anchor{37f}
@deffn {C Fonction} @ref{32f,,PyObject} *PySys_GetObject (const char *name)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return the object `name' from the @ref{d8,,sys} module or @code{NULL} if it does
not exist, without setting an exception.
@end deffn

@geindex PySys_SetObject (C function)
@anchor{c-api/sys c PySys_SetObject}@anchor{4953}
@deffn {C Fonction} int PySys_SetObject (const char *name, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
Set `name' in the @ref{d8,,sys} module to `v' unless `v' is @code{NULL}, in which
case `name' is deleted from the sys module. Returns @code{0} on success, @code{-1}
on error.
@end deffn

@geindex PySys_ResetWarnOptions (C function)
@anchor{c-api/sys c PySys_ResetWarnOptions}@anchor{3a6}
@deffn {C Fonction} void PySys_ResetWarnOptions ()
` Part of the @ref{53e,,Stable ABI}.'
Reset @ref{3a7,,sys.warnoptions} to an empty list. This function may be
called prior to @ref{899,,Py_Initialize()}.


Deprecated since version 3.13, will be removed in version 3.15: Clear @ref{3a7,,sys.warnoptions} and @code{warnings.filters} instead.

@end deffn

@geindex PySys_WriteStdout (C function)
@anchor{c-api/sys c PySys_WriteStdout}@anchor{4955}
@deffn {C Fonction} void PySys_WriteStdout (const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
Write the output string described by `format' to @ref{ac4,,sys.stdout}.  No
exceptions are raised, even if truncation occurs (see below).

`format' should limit the total size of the formatted output string to
1000 bytes or less -- after 1000 bytes, the output string is truncated.
In particular, this means that no unrestricted "%s" formats should occur;
these should be limited using "%.<N>s" where <N> is a decimal number
calculated so that <N> plus the maximum size of other formatted text does not
exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
digits for very large numbers.

If a problem occurs, or @ref{ac4,,sys.stdout} is unset, the formatted message
is written to the real (C level) `stdout'.
@end deffn

@geindex PySys_WriteStderr (C function)
@anchor{c-api/sys c PySys_WriteStderr}@anchor{4954}
@deffn {C Fonction} void PySys_WriteStderr (const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
As @ref{4955,,PySys_WriteStdout()}, but write to @ref{926,,sys.stderr} or `stderr'
instead.
@end deffn

@geindex PySys_FormatStdout (C function)
@anchor{c-api/sys c PySys_FormatStdout}@anchor{4951}
@deffn {C Fonction} void PySys_FormatStdout (const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
Function similar to PySys_WriteStdout() but format the message using
@ref{560,,PyUnicode_FromFormatV()} and don't truncate the message to an
arbitrary length.


Ajouté dans la version 3.2.

@end deffn

@geindex PySys_FormatStderr (C function)
@anchor{c-api/sys c PySys_FormatStderr}@anchor{4950}
@deffn {C Fonction} void PySys_FormatStderr (const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
As @ref{4951,,PySys_FormatStdout()}, but write to @ref{926,,sys.stderr} or `stderr'
instead.


Ajouté dans la version 3.2.

@end deffn

@geindex PySys_GetXOptions (C function)
@anchor{c-api/sys c PySys_GetXOptions}@anchor{4952}
@deffn {C Fonction} @ref{32f,,PyObject} *PySys_GetXOptions ()
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return the current dictionary of @ref{175,,-X} options, similarly to
@ref{1ccb,,sys._xoptions}.  On error, @code{NULL} is returned and an exception is
set.


Ajouté dans la version 3.2.

@end deffn

@geindex PySys_Audit (C function)
@anchor{c-api/sys c PySys_Audit}@anchor{365}
@deffn {C Fonction} int PySys_Audit (const char *event, const char *format, ...)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Raise an auditing event with any active hooks. Return zero for success
and non-zero with an exception set on failure.

The `event' string argument must not be `NULL'.

If any hooks have been added, `format' and other arguments will be used
to construct a tuple to pass. Apart from @code{N}, the same format characters
as used in @ref{894,,Py_BuildValue()} are available. If the built value is not
a tuple, it will be added into a single-element tuple.

The @code{N} format option must not be used. It consumes a reference, but since
there is no way to know whether arguments to this function will be consumed,
using it may cause reference leaks.

Note that @code{#} format characters should always be treated as
@ref{a4e,,Py_ssize_t}, regardless of whether @code{PY_SSIZE_T_CLEAN} was defined.

@ref{153f,,sys.audit()} performs the same function from Python code.

See also @ref{364,,PySys_AuditTuple()}.


Ajouté dans la version 3.8.



Modifié dans la version 3.8.2: Require @ref{a4e,,Py_ssize_t} for @code{#} format characters. Previously, an
unavoidable deprecation warning was raised.

@end deffn

@geindex PySys_AuditTuple (C function)
@anchor{c-api/sys c PySys_AuditTuple}@anchor{364}
@deffn {C Fonction} int PySys_AuditTuple (const char *event, PyObject *args)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Similar to @ref{365,,PySys_Audit()}, but pass arguments as a Python object.
`args' must be a @ref{366,,tuple}. To pass no arguments, `args' can be `NULL'.


Ajouté dans la version 3.13.

@end deffn

@geindex PySys_AddAuditHook (C function)
@anchor{c-api/sys c PySys_AddAuditHook}@anchor{410d}
@deffn {C Fonction} int PySys_AddAuditHook (Py_AuditHookFunction hook, void *userData)

Append the callable `hook' to the list of active auditing hooks.
Return zero on success
and non-zero on failure. If the runtime has been initialized, also set an
error on failure. Hooks added through this API are called for all
interpreters created by the runtime.

The `userData' pointer is passed into the hook function. Since hook
functions may be called from different runtimes, this pointer should not
refer directly to Python state.

This function is safe to call before @ref{899,,Py_Initialize()}. When called
after runtime initialization, existing audit hooks are notified and may
silently abort the operation by raising an error subclassed from
@ref{9c7,,Exception} (other errors will not be silenced).

The hook function is always called with the GIL held by the Python
interpreter that raised the event.

See 
@geindex Python Enhancement Proposals; PEP 578
PEP 578@footnote{https://peps.python.org/pep-0578/} for a detailed description of auditing.  Functions in the
runtime and standard library that raise events are listed in the
@ref{17fe,,audit events table}.
Details are in each function's documentation.


If the interpreter is initialized, this function raises an auditing event
@code{sys.addaudithook} with no arguments. If any existing hooks raise an
exception derived from @ref{9c7,,Exception}, the new hook will not be
added and the exception is cleared. As a result, callers cannot assume
that their hook has been added unless they control all existing hooks.


@geindex Py_AuditHookFunction (C type)
@anchor{c-api/sys c Py_AuditHookFunction}@anchor{4a08}
@deffn {C Type} typedef int (*Py_AuditHookFunction)(const char *event, @ref{32f,,PyObject} *args, void *userData)

The type of the hook function.
`event' is the C string event argument passed to @ref{365,,PySys_Audit()} or
@ref{364,,PySys_AuditTuple()}.
`args' is guaranteed to be a @ref{4a09,,PyTupleObject}.
`userData' is the argument passed to PySys_AddAuditHook().
@end deffn


Ajouté dans la version 3.8.

@end deffn

@node Process Control,Importer des modules<2>,System Functions,Utilitaires<2>
@anchor{c-api/sys process-control}@anchor{4a0a}@anchor{c-api/sys processcontrol}@anchor{4a0b}
@subsection Process Control


@geindex Py_FatalError (C function)
@anchor{c-api/sys c Py_FatalError}@anchor{970}
@deffn {C Fonction} void Py_FatalError (const char *message)
` Part of the @ref{53e,,Stable ABI}.'
@geindex abort (C function)

Print a fatal error message and kill the process.  No cleanup is performed.
This function should only be invoked when a condition is detected that would
make it dangerous to continue using the Python interpreter; e.g., when the
object administration appears to be corrupted.  On Unix, the standard C library
function @code{abort()} is called which will attempt to produce a @code{core}
file.

The @code{Py_FatalError()} function is replaced with a macro which logs
automatically the name of the current function, unless the
@code{Py_LIMITED_API} macro is defined.


Modifié dans la version 3.9: Log the function name automatically.

@end deffn

@geindex Py_Exit (C function)
@anchor{c-api/sys c Py_Exit}@anchor{d3c}
@deffn {C Fonction} void Py_Exit (int status)
` Part of the @ref{53e,,Stable ABI}.'
@geindex Py_FinalizeEx (C function)
@geindex exit (C function)

Exit the current process.  This calls @ref{d03,,Py_FinalizeEx()} and then calls the
standard C library function @code{exit(status)}.  If @ref{d03,,Py_FinalizeEx()}
indicates an error, the exit status is set to 120.


Modifié dans la version 3.6: Errors from finalization no longer ignored.

@end deffn

@geindex Py_AtExit (C function)
@anchor{c-api/sys c Py_AtExit}@anchor{499e}
@deffn {C Fonction} int Py_AtExit (void (*func)())
` Part of the @ref{53e,,Stable ABI}.'
@geindex Py_FinalizeEx (C function)
@geindex cleanup functions

Register a cleanup function to be called by @ref{d03,,Py_FinalizeEx()}.  The cleanup
function will be called with no arguments and should return no value.  At most
32 cleanup functions can be registered.  When the registration is successful,
@ref{499e,,Py_AtExit()} returns @code{0}; on failure, it returns @code{-1}.  The cleanup
function registered last is called first. Each cleanup function will be called
at most once.  Since Python's internal finalization will have completed before
the cleanup function, no Python APIs should be called by `func'.


@subsubheading Voir aussi


@ref{1511,,PyUnstable_AtExit()} for passing a @code{void *data} argument.

@end deffn

@node Importer des modules<2>,Data marshalling support,Process Control,Utilitaires<2>
@anchor{c-api/import doc}@anchor{4a0c}@anchor{c-api/import importing}@anchor{4a0d}@anchor{c-api/import importing-modules}@anchor{4a0e}
@subsection Importer des modules


@geindex PyImport_ImportModule (C function)
@anchor{c-api/import c PyImport_ImportModule}@anchor{3b5}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ImportModule (const char *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex package variable;__all__
@geindex __all__ (package variable)
@geindex modules (in module sys)

This is a wrapper around @ref{13b3,,PyImport_Import()} which takes a
const char* as an argument instead of a @ref{32f,,PyObject}*.
@end deffn

@geindex PyImport_ImportModuleNoBlock (C function)
@anchor{c-api/import c PyImport_ImportModuleNoBlock}@anchor{3b4}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ImportModuleNoBlock (const char *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This function is a deprecated alias of @ref{3b5,,PyImport_ImportModule()}.


Modifié dans la version 3.3: This function used to fail immediately when the import lock was held
by another thread.  In Python 3.3 though, the locking scheme switched
to per-module locks for most purposes, so this function's special
behaviour isn't needed anymore.



Deprecated since version 3.13, will be removed in version 3.15: Use @ref{3b5,,PyImport_ImportModule()} instead.

@end deffn

@geindex PyImport_ImportModuleEx (C function)
@anchor{c-api/import c PyImport_ImportModuleEx}@anchor{1183}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ImportModuleEx (const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
`Valeur de retour : nouvelle référence.'
@geindex built-in function;__import__

Import a module.  This is best described by referring to the built-in Python
function @ref{8c1,,__import__()}.

The return value is a new reference to the imported module or top-level
package, or @code{NULL} with an exception set on failure.  Like for
@ref{8c1,,__import__()}, the return value when a submodule of a package was
requested is normally the top-level package, unless a non-empty `fromlist'
was given.

Failing imports remove incomplete module objects, like with
@ref{3b5,,PyImport_ImportModule()}.
@end deffn

@geindex PyImport_ImportModuleLevelObject (C function)
@anchor{c-api/import c PyImport_ImportModuleLevelObject}@anchor{48d3}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ImportModuleLevelObject (PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Import a module.  This is best described by referring to the built-in Python
function @ref{8c1,,__import__()}, as the standard @ref{8c1,,__import__()} function calls
this function directly.

The return value is a new reference to the imported module or top-level package,
or @code{NULL} with an exception set on failure.  Like for @ref{8c1,,__import__()},
the return value when a submodule of a package was requested is normally the
top-level package, unless a non-empty `fromlist' was given.


Ajouté dans la version 3.3.

@end deffn

@geindex PyImport_ImportModuleLevel (C function)
@anchor{c-api/import c PyImport_ImportModuleLevel}@anchor{1182}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ImportModuleLevel (const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{48d3,,PyImport_ImportModuleLevelObject()}, but the name is a
UTF-8 encoded string instead of a Unicode object.


Modifié dans la version 3.3: Negative values for `level' are no longer accepted.

@end deffn

@geindex PyImport_Import (C function)
@anchor{c-api/import c PyImport_Import}@anchor{13b3}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_Import (PyObject *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is a higher-level interface that calls the current "import hook
function" (with an explicit `level' of 0, meaning absolute import).  It
invokes the @ref{8c1,,__import__()} function from the @code{__builtins__} of the
current globals.  This means that the import is done using whatever import
hooks are installed in the current environment.

This function always uses absolute imports.
@end deffn

@geindex PyImport_ReloadModule (C function)
@anchor{c-api/import c PyImport_ReloadModule}@anchor{48d4}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ReloadModule (PyObject *m)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Reload a module.  Return a new reference to the reloaded module, or @code{NULL} with
an exception set on failure (the module still exists in this case).
@end deffn

@geindex PyImport_AddModuleRef (C function)
@anchor{c-api/import c PyImport_AddModuleRef}@anchor{34e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_AddModuleRef (const char *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return the module object corresponding to a module name.

The `name' argument may be of the form @code{package.module}. First check the
modules dictionary if there's one there, and if not, create a new one and
insert it in the modules dictionary.

Return a @ref{333,,strong reference} to the module on success. Return @code{NULL}
with an exception set on failure.

The module name `name' is decoded from UTF-8.

This function does not load or import the module; if the module wasn't
already loaded, you will get an empty module object. Use
@ref{3b5,,PyImport_ImportModule()} or one of its variants to import a module.
Package structures implied by a dotted name for `name' are not created if
not already present.


Ajouté dans la version 3.13.

@end deffn

@geindex PyImport_AddModuleObject (C function)
@anchor{c-api/import c PyImport_AddModuleObject}@anchor{48ca}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_AddModuleObject (PyObject *name)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Similar to @ref{34e,,PyImport_AddModuleRef()}, but return a @ref{334,,borrowed reference} and `name' is a Python @ref{435,,str} object.


Ajouté dans la version 3.3.

@end deffn

@geindex PyImport_AddModule (C function)
@anchor{c-api/import c PyImport_AddModule}@anchor{34f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_AddModule (const char *name)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{34e,,PyImport_AddModuleRef()}, but return a @ref{334,,borrowed reference}.
@end deffn

@geindex PyImport_ExecCodeModule (C function)
@anchor{c-api/import c PyImport_ExecCodeModule}@anchor{48cb}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ExecCodeModule (const char *name, PyObject *co)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;compile

Given a module name (possibly of the form @code{package.module}) and a code object
read from a Python bytecode file or obtained from the built-in function
@ref{190,,compile()}, load the module.  Return a new reference to the module object,
or @code{NULL} with an exception set if an error occurred.  `name'
is removed from @ref{18f9,,sys.modules} in error cases, even if `name' was already
in @ref{18f9,,sys.modules} on entry to @ref{48cb,,PyImport_ExecCodeModule()}.  Leaving
incompletely initialized modules in @ref{18f9,,sys.modules} is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.

The module's @ref{1e9c,,__spec__} and @ref{2e0,,__loader__} will be
set, if not set already, with the appropriate values.  The spec's loader
will be set to the module's @code{__loader__} (if set) and to an instance
of @ref{105d,,SourceFileLoader} otherwise.

The module's @ref{1ea2,,__file__} attribute will be set to the code
object's @ref{1344,,co_filename}.  If applicable,
@ref{2d4,,__cached__} will also be set.

This function will reload the module if it was already imported.  See
@ref{48d4,,PyImport_ReloadModule()} for the intended way to reload a module.

If `name' points to a dotted name of the form @code{package.module}, any package
structures not already created will still not be created.

See also @ref{48cc,,PyImport_ExecCodeModuleEx()} and
@ref{48ce,,PyImport_ExecCodeModuleWithPathnames()}.


Modifié dans la version 3.12: The setting of @ref{2d4,,__cached__} and @ref{2e0,,__loader__}
is deprecated. See @ref{1ded,,ModuleSpec} for
alternatives.

@end deffn

@geindex PyImport_ExecCodeModuleEx (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleEx}@anchor{48cc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ExecCodeModuleEx (const char *name, PyObject *co, const char *pathname)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Like @ref{48cb,,PyImport_ExecCodeModule()}, but the @ref{1ea2,,__file__}
attribute of the module object is set to `pathname' if it is non-@code{NULL}.

See also @ref{48ce,,PyImport_ExecCodeModuleWithPathnames()}.
@end deffn

@geindex PyImport_ExecCodeModuleObject (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleObject}@anchor{48cd}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ExecCodeModuleObject (PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Like @ref{48cc,,PyImport_ExecCodeModuleEx()}, but the @ref{2d4,,__cached__}
attribute of the module object is set to `cpathname' if it is
non-@code{NULL}.  Of the three functions, this is the preferred one to use.


Ajouté dans la version 3.3.



Modifié dans la version 3.12: Setting @ref{2d4,,__cached__} is deprecated. See
@ref{1ded,,ModuleSpec} for alternatives.

@end deffn

@geindex PyImport_ExecCodeModuleWithPathnames (C function)
@anchor{c-api/import c PyImport_ExecCodeModuleWithPathnames}@anchor{48ce}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_ExecCodeModuleWithPathnames (const char *name, PyObject *co, const char *pathname, const char *cpathname)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Like @ref{48cd,,PyImport_ExecCodeModuleObject()}, but `name', `pathname' and
`cpathname' are UTF-8 encoded strings. Attempts are also made to figure out
what the value for `pathname' should be from `cpathname' if the former is
set to @code{NULL}.


Ajouté dans la version 3.2.



Modifié dans la version 3.3: Uses @code{imp.source_from_cache()} in calculating the source path if
only the bytecode path is provided.



Modifié dans la version 3.12: No longer uses the removed @code{imp} module.

@end deffn

@geindex PyImport_GetMagicNumber (C function)
@anchor{c-api/import c PyImport_GetMagicNumber}@anchor{1181}
@deffn {C Fonction} long PyImport_GetMagicNumber ()
` Part of the @ref{53e,,Stable ABI}.'
Return the magic number for Python bytecode files (a.k.a. @code{.pyc} file).
The magic number should be present in the first four bytes of the bytecode
file, in little-endian byte order. Returns @code{-1} on error.


Modifié dans la version 3.3: Return value of @code{-1} upon failure.

@end deffn

@geindex PyImport_GetMagicTag (C function)
@anchor{c-api/import c PyImport_GetMagicTag}@anchor{48cf}
@deffn {C Fonction} const char *PyImport_GetMagicTag ()
` Part of the @ref{53e,,Stable ABI}.'
Return the magic tag string for 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} format Python bytecode file
names.  Keep in mind that the value at @code{sys.implementation.cache_tag} is
authoritative and should be used instead of this function.


Ajouté dans la version 3.2.

@end deffn

@geindex PyImport_GetModuleDict (C function)
@anchor{c-api/import c PyImport_GetModuleDict}@anchor{48d0}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_GetModuleDict ()
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return the dictionary used for the module administration (a.k.a.
@code{sys.modules}).  Note that this is a per-interpreter variable.
@end deffn

@geindex PyImport_GetModule (C function)
@anchor{c-api/import c PyImport_GetModule}@anchor{ba1}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_GetModule (PyObject *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.8.'
Return the already imported module with the given name.  If the
module has not been imported yet then returns @code{NULL} but does not set
an error.  Returns @code{NULL} and sets an error if the lookup failed.


Ajouté dans la version 3.7.

@end deffn

@geindex PyImport_GetImporter (C function)
@anchor{c-api/import c PyImport_GetImporter}@anchor{16a0}
@deffn {C Fonction} @ref{32f,,PyObject} *PyImport_GetImporter (PyObject *path)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a finder object for a @ref{3ab,,sys.path}/@code{pkg.__path__} item
`path', possibly by fetching it from the @ref{5ce,,sys.path_importer_cache}
dict.  If it wasn't yet cached, traverse @ref{100d,,sys.path_hooks} until a hook
is found that can handle the path item.  Return @code{None} if no hook could;
this tells our caller that the @ref{1f7a,,path based finder} could not find a
finder for this path item. Cache the result in @ref{5ce,,sys.path_importer_cache}.
Return a new reference to the finder object.
@end deffn

@geindex PyImport_ImportFrozenModuleObject (C function)
@anchor{c-api/import c PyImport_ImportFrozenModuleObject}@anchor{48d2}
@deffn {C Fonction} int PyImport_ImportFrozenModuleObject (PyObject *name)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Load a frozen module named `name'.  Return @code{1} for success, @code{0} if the
module is not found, and @code{-1} with an exception set if the initialization
failed.  To access the imported module on a successful load, use
@ref{3b5,,PyImport_ImportModule()}.  (Note the misnomer --- this function would
reload the module if it was already imported.)


Ajouté dans la version 3.3.



Modifié dans la version 3.4: The @code{__file__} attribute is no longer set on the module.

@end deffn

@geindex PyImport_ImportFrozenModule (C function)
@anchor{c-api/import c PyImport_ImportFrozenModule}@anchor{48d1}
@deffn {C Fonction} int PyImport_ImportFrozenModule (const char *name)
` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{48d2,,PyImport_ImportFrozenModuleObject()}, but the name is a
UTF-8 encoded string instead of a Unicode object.
@end deffn

@geindex _frozen (C struct)
@anchor{c-api/import c _frozen}@anchor{75f}
@deffn {C Structure} struct _frozen

@geindex freeze utility

This is the structure type definition for frozen module descriptors, as
generated by the @code{freeze} utility (see @code{Tools/freeze/} in the
Python source distribution).  Its definition, found in @code{Include/import.h},
is:

@example
struct _frozen @{
    const char *name;
    const unsigned char *code;
    int size;
    bool is_package;
@};
@end example


Modifié dans la version 3.11: The new @code{is_package} field indicates whether the module is a package or not.
This replaces setting the @code{size} field to a negative value.

@end deffn

@geindex PyImport_FrozenModules (C var)
@anchor{c-api/import c PyImport_FrozenModules}@anchor{2d81}
@deffn {C Variable} const struct @ref{75f,,_frozen} *PyImport_FrozenModules

This pointer is initialized to point to an array of @ref{75f,,_frozen}
records, terminated by one whose members are all @code{NULL} or zero.  When a frozen
module is imported, it is searched in this table.  Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules.
@end deffn

@geindex PyImport_AppendInittab (C function)
@anchor{c-api/import c PyImport_AppendInittab}@anchor{1731}
@deffn {C Fonction} int PyImport_AppendInittab (const char *name, PyObject *(*initfunc)(void))
` Part of the @ref{53e,,Stable ABI}.'
Add a single module to the existing table of built-in modules.  This is a
convenience wrapper around @ref{1732,,PyImport_ExtendInittab()}, returning @code{-1} if
the table could not be extended.  The new module can be imported by the name
`name', and uses the function `initfunc' as the initialization function called
on the first attempted import.  This should be called before
@ref{899,,Py_Initialize()}.
@end deffn

@geindex _inittab (C struct)
@anchor{c-api/import c _inittab}@anchor{4a0f}
@deffn {C Structure} struct _inittab

Structure describing a single entry in the list of built-in modules.
Programs which
embed Python may use an array of these structures in conjunction with
@ref{1732,,PyImport_ExtendInittab()} to provide additional built-in modules.
The structure consists of two members:

@geindex _inittab.name (C member)
@anchor{c-api/import c _inittab name}@anchor{4a10}
@deffn {C Membre} const char *name

The module name, as an ASCII encoded string.
@end deffn

@geindex _inittab.initfunc (C member)
@anchor{c-api/import c _inittab initfunc}@anchor{4a11}
@deffn {C Membre} @ref{32f,,PyObject} *(*initfunc)(void)

Initialization function for a module built into the interpreter.
@end deffn
@end deffn

@geindex PyImport_ExtendInittab (C function)
@anchor{c-api/import c PyImport_ExtendInittab}@anchor{1732}
@deffn {C Fonction} int PyImport_ExtendInittab (struct _inittab *newtab)

Add a collection of modules to the table of built-in modules.  The `newtab'
array must end with a sentinel entry which contains @code{NULL} for the @ref{4a10,,name}
field; failure to provide the sentinel value can result in a memory fault.
Returns @code{0} on success or @code{-1} if insufficient memory could be allocated to
extend the internal table.  In the event of failure, no modules are added to the
internal table.  This must be called before @ref{899,,Py_Initialize()}.

If Python is initialized multiple times, @ref{1731,,PyImport_AppendInittab()} or
@ref{1732,,PyImport_ExtendInittab()} must be called before each Python
initialization.
@end deffn

@node Data marshalling support,Analyse des arguments et construction des valeurs,Importer des modules<2>,Utilitaires<2>
@anchor{c-api/marshal doc}@anchor{4a12}@anchor{c-api/marshal data-marshalling-support}@anchor{4a13}@anchor{c-api/marshal marshalling-utils}@anchor{4a14}
@subsection Data marshalling support


These routines allow C code to work with serialized objects using the same
data format as the @ref{8c,,marshal} module.  There are functions to write data
into the serialization format, and additional functions that can be used to
read the data back.  Files used to store marshalled data must be opened in
binary mode.

Numeric values are stored with the least significant byte first.

The module supports two versions of the data format: version 0 is the
historical version, version 1 shares interned strings in the file, and upon
unmarshalling.  Version 2 uses a binary format for floating-point numbers.
@code{Py_MARSHAL_VERSION} indicates the current file format (currently 2).

@geindex PyMarshal_WriteLongToFile (C function)
@anchor{c-api/marshal c PyMarshal_WriteLongToFile}@anchor{780}
@deffn {C Fonction} void PyMarshal_WriteLongToFile (long value, FILE *file, int version)

Marshal a long integer, `value', to `file'.  This will only write
the least-significant 32 bits of `value'; regardless of the size of the
native long type.  `version' indicates the file format.

This function can fail, in which case it sets the error indicator.
Use @ref{187f,,PyErr_Occurred()} to check for that.
@end deffn

@geindex PyMarshal_WriteObjectToFile (C function)
@anchor{c-api/marshal c PyMarshal_WriteObjectToFile}@anchor{781}
@deffn {C Fonction} void PyMarshal_WriteObjectToFile (PyObject *value, FILE *file, int version)

Marshal a Python object, `value', to `file'.
`version' indicates the file format.

This function can fail, in which case it sets the error indicator.
Use @ref{187f,,PyErr_Occurred()} to check for that.
@end deffn

@geindex PyMarshal_WriteObjectToString (C function)
@anchor{c-api/marshal c PyMarshal_WriteObjectToString}@anchor{783}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMarshal_WriteObjectToString (PyObject *value, int version)
`Valeur de retour : nouvelle référence.'
Return a bytes object containing the marshalled representation of `value'.
`version' indicates the file format.
@end deffn

The following functions allow marshalled values to be read back in.

@geindex PyMarshal_ReadLongFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadLongFromFile}@anchor{4a15}
@deffn {C Fonction} long PyMarshal_ReadLongFromFile (FILE *file)

Return a C long from the data stream in a FILE* opened
for reading.  Only a 32-bit value can be read in using this function,
regardless of the native size of long.

On error, sets the appropriate exception (@ref{12b7,,EOFError}) and returns
@code{-1}.
@end deffn

@geindex PyMarshal_ReadShortFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadShortFromFile}@anchor{4a16}
@deffn {C Fonction} int PyMarshal_ReadShortFromFile (FILE *file)

Return a C short from the data stream in a FILE* opened
for reading.  Only a 16-bit value can be read in using this function,
regardless of the native size of short.

On error, sets the appropriate exception (@ref{12b7,,EOFError}) and returns
@code{-1}.
@end deffn

@geindex PyMarshal_ReadObjectFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadObjectFromFile}@anchor{4a17}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMarshal_ReadObjectFromFile (FILE *file)
`Valeur de retour : nouvelle référence.'
Return a Python object from the data stream in a FILE* opened for
reading.

On error, sets the appropriate exception (@ref{12b7,,EOFError}, @ref{1ff,,ValueError}
or @ref{522,,TypeError}) and returns @code{NULL}.
@end deffn

@geindex PyMarshal_ReadLastObjectFromFile (C function)
@anchor{c-api/marshal c PyMarshal_ReadLastObjectFromFile}@anchor{4a18}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMarshal_ReadLastObjectFromFile (FILE *file)
`Valeur de retour : nouvelle référence.'
Return a Python object from the data stream in a FILE* opened for
reading.  Unlike @ref{4a17,,PyMarshal_ReadObjectFromFile()}, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can
operate from data in memory rather than reading a byte at a time from the
file.  Only use these variant if you are certain that you won't be reading
anything else from the file.

On error, sets the appropriate exception (@ref{12b7,,EOFError}, @ref{1ff,,ValueError}
or @ref{522,,TypeError}) and returns @code{NULL}.
@end deffn

@geindex PyMarshal_ReadObjectFromString (C function)
@anchor{c-api/marshal c PyMarshal_ReadObjectFromString}@anchor{782}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMarshal_ReadObjectFromString (const char *data, Py_ssize_t len)
`Valeur de retour : nouvelle référence.'
Return a Python object from the data stream in a byte buffer
containing `len' bytes pointed to by `data'.

On error, sets the appropriate exception (@ref{12b7,,EOFError}, @ref{1ff,,ValueError}
or @ref{522,,TypeError}) and returns @code{NULL}.
@end deffn

@node Analyse des arguments et construction des valeurs,Conversion et formatage de chaînes,Data marshalling support,Utilitaires<2>
@anchor{c-api/arg doc}@anchor{4a19}@anchor{c-api/arg arg-parsing}@anchor{895}@anchor{c-api/arg parsing-arguments-and-building-values}@anchor{4a1a}
@subsection Analyse des arguments et construction des valeurs


Ces fonctions sont utiles pour créer vos propres fonctions et méthodes d'extensions. Des informations supplémentaires et des exemples sont disponibles ici: @ref{1b69,,Extension et intégration de l'interpréteur Python}.

Dans Les trois premières de ces fonctions décrites, @ref{55d,,PyArg_ParseTuple()}, @ref{379,,PyArg_ParseTupleAndKeywords()}, et @ref{1972,,PyArg_Parse()}, toutes utilisent `des chaînes de format' qui sont utilisées pour indiquer à la fonction les arguments attendus. Les chaînes de format utilise la même syntaxe pour chacune de ces fonctions.

@menu
* Analyse des arguments: Analyse des arguments<2>. 
* Construction des valeurs:: 

@end menu

@node Analyse des arguments<2>,Construction des valeurs,,Analyse des arguments et construction des valeurs
@anchor{c-api/arg parsing-arguments}@anchor{4a1b}
@subsubsection Analyse des arguments


Une chaîne de format se compose de zéro ou plusieurs "unités de format". Une unité de format décrit un objet Python, elle est généralement composée d'un seul caractère ou d'une séquence d'unités de format entre parenthèses. À quelques exceptions près, une unité de format qui n'est pas une séquence entre parenthèses correspond normalement à un argument d'une seule adresse pour ces fonctions. Dans la description qui suit, la forme entre guillemets est l'unité de format, l'entrée entre parenthèses est le type d'objet Python qui correspond à l'unité de format, et l'entrée entre crochets est le type de la variable C (ou des variables) dont l'adresse doit être donnée.

@menu
* Chaînes et tampons:: 
* Les nombres: Les nombres<2>. 
* Autres objets:: 
* Fonction de l'API:: 

@end menu

@node Chaînes et tampons,Les nombres<2>,,Analyse des arguments<2>
@anchor{c-api/arg arg-parsing-string-and-buffers}@anchor{381}@anchor{c-api/arg strings-and-buffers}@anchor{4a1c}
@subsubsection Chaînes et tampons


@cartouche
@quotation Note 
Dans Python 3.12 et précédents, la macro @code{PY_SSIZE_T_CLEAN} doit être définie avant d'inclure @code{Python.h} pour utiliser toutes les variantes @code{#} de format (@code{s#}, @code{y#}, etc.) détaillées ci-dessous. Ce n'est plus nécessaire pour Python 3.13 et les versions ultérieures.
@end quotation
@end cartouche

Ces formats permettent d'accéder à un objet sous forme d'un fragment de mémoire contiguë. Il n'est pas nécessaire d'allouer la mémoire pour l'`unicode' ou le `bytes' renvoyé.

Sauf indication contraire, les tampons ne se terminent pas par NUL.

Les chaînes de caractères et tampons peuvent être convertis de trois manières vers C:


@itemize *

@item 
Formats such as @code{y*} and @code{s*} fill a @ref{742,,Py_buffer} structure.
This locks the underlying buffer so that the caller can subsequently use
the buffer even inside a @ref{47dd,,Py_BEGIN_ALLOW_THREADS}
block without the risk of mutable data being resized or destroyed.
As a result, `you have to call' @ref{391,,PyBuffer_Release()} after you have
finished processing the data (or in any early abort case).

@item 
Les formats @code{es}, @code{es#}, @code{et} et @code{et#} allouent le tampon de résultats. `Vous devez appeler' @ref{13f9,,PyMem_Free()} après avoir fini de traiter les données (ou en cas d'abandon prématuré).

@item @anchor{c-api/arg c-arg-borrowed-buffer}@anchor{4a1d}
Other formats take a @ref{435,,str} or a read-only @ref{d1b,,bytes-like object},
such as @ref{1bd,,bytes}, and provide a @code{const char *} pointer to
its buffer.
In this case the buffer is "borrowed": it is managed by the corresponding
Python object, and shares the lifetime of this object.
You won't have to release any memory yourself.

To ensure that the underlying buffer may be safely borrowed, the object's
@ref{74d,,PyBufferProcs.bf_releasebuffer} field must be @code{NULL}.
This disallows common mutable objects such as @ref{528,,bytearray},
but also some read-only objects such as @ref{452,,memoryview} of
@ref{1bd,,bytes}.

Besides this @code{bf_releasebuffer} requirement, there is no check to verify
whether the input object is immutable (e.g. whether it would honor a request
for a writable buffer, or whether another thread can mutate the data).
@end itemize


@table @asis

@item @code{s} (@ref{435,,str}) [@code{const char *}]

Convertit un objet Unicode en un pointeur vers une chaîne de caractères. S'il s'agit d'un pointeur vers une chaîne de caractères déjà existante, il est stocké dans la variable de type pointeur vers un caractère dont vous avez donné l'adresse. Une chaîne de caractères en C se termine par `NULL'. La chaîne de caractères Python ne doit donc pas contenir de caractère dont le code est `null'. Si elle en contient, une exception @ref{1ff,,ValueError} est levée. Si la conversion échoue, une @ref{1281,,UnicodeError} est levée.

@cartouche
@quotation Note 
Ce format n'accepte pas les @ref{d1b,,objets compatibles avec une chaîne d'octets}. Si vous voulez accepter les chemins du système de fichiers et les convertir vers des chaînes de caractères C, il est préférable d'utiliser le format @code{O&} avec @ref{d07,,PyUnicode_FSConverter()} en tant que `converter'.
@end quotation
@end cartouche


Modifié dans la version 3.5: Auparavant, une @ref{522,,TypeError} était levée quand la chaîne de caractères Python contenait des codes NULL.


@item @code{s*} (@ref{435,,str} ou @ref{d1b,,bytes-like object}) [@code{Py_buffer}]

Ce format accepte les objets Unicode et les `bytes-like object'. Cela remplit une structure @ref{742,,Py_buffer} qui est fournie par l'appelant. Dans ce cas, la chaîne de caractères C qui en résulte peut contenir des octets NULL. Les objets Unicode sont convertis en chaînes de caractères C en utilisant l'encodage @code{'utf-8'}.

@item @code{s#} (@ref{435,,str}, read-only @ref{d1b,,bytes-like object}) [const char *, @ref{a4e,,Py_ssize_t}]

Like @code{s*}, except that it provides a @ref{4a1d,,borrowed buffer}.
The result is stored into two C variables,
the first one a pointer to a C string, the second one its length.
The string may contain embedded null bytes. Unicode objects are converted
to C strings using @code{'utf-8'} encoding.

@item @code{z} (@ref{435,,str} ou @code{None}) [@code{const char *}]

Like @code{s}, but the Python object may also be @code{None}, in which case the C
pointer is set to @code{NULL}.

@item @code{z*} (@ref{435,,str}, @ref{d1b,,bytes-like object} ou @code{None}) [@code{Py_buffer}]

Comme @code{s*}, mais l'objet Python peut aussi être  @code{None}, auquel cas le membre @code{buf}, dont la structure est @ref{742,,Py_buffer} est fixée à `NULL'.

@item @code{z#} (@ref{435,,str}, read-only @ref{d1b,,bytes-like object} or @code{None}) [const char *, @ref{a4e,,Py_ssize_t}]

Like @code{s#}, but the Python object may also be @code{None}, in which case the C
pointer is set to @code{NULL}.

@item @code{y} (lecture seule @ref{d1b,,objet compatible avec une chaîne d'octets}) [constante char *]

This format converts a bytes-like object to a C pointer to a
@ref{4a1d,,borrowed} character string;
it does not accept Unicode objects.  The bytes buffer must not
contain embedded null bytes; if it does, a @ref{1ff,,ValueError}
exception is raised.


Modifié dans la version 3.5: Auparavant, @ref{522,,TypeError} était levée lorsque des octets `null' étaient rencontrés dans le tampon d'octets.


@item @code{y*} (@ref{d1b,,bytes-like object}) [@code{Py_buffer}]

This variant on @code{s*} doesn't accept Unicode objects, only
bytes-like objects.  `This is the recommended way to accept
binary data.'

@item @code{y#} (read-only @ref{d1b,,bytes-like object}) [const char *, @ref{a4e,,Py_ssize_t}]

Cette variante de @code{s#} n'accepte pas les objets Unicode, uniquement des objets assimilés à des octets.

@item @code{S} (@ref{1bd,,bytes}) [@code{PyBytesObject *}]

Requires that the Python object is a @ref{1bd,,bytes} object, without
attempting any conversion.  Raises @ref{522,,TypeError} if the object is not
a bytes object.  The C variable may also be declared as @ref{32f,,PyObject}*.

@item @code{Y} (@ref{528,,bytearray}) [@code{PyByteArrayObject *}]

Requires that the Python object is a @ref{528,,bytearray} object, without
attempting any conversion.  Raises @ref{522,,TypeError} if the object is not
a @ref{528,,bytearray} object. The C variable may also be declared as @ref{32f,,PyObject}*.

@item @code{U} (@ref{435,,str}) [@code{PyObject *}]

Requires that the Python object is a Unicode object, without attempting
any conversion.  Raises @ref{522,,TypeError} if the object is not a Unicode
object.  The C variable may also be declared as @ref{32f,,PyObject}*.

@item @code{w*} (lecture-écriture @ref{d1b,,bytes-like object}) [@code{Py_buffer}]

This format accepts any object which implements the read-write buffer
interface. It fills a @ref{742,,Py_buffer} structure provided by the caller.
The buffer may contain embedded null bytes. The caller have to call
@ref{391,,PyBuffer_Release()} when it is done with the buffer.

@item @code{es} (@ref{435,,str}) [const char *encoding, char **buffer]

This variant on @code{s} is used for encoding Unicode into a character buffer.
It only works for encoded data without embedded NUL bytes.

This format requires two arguments.  The first is only used as input, and
must be a const char* which points to the name of an encoding as a
NUL-terminated string, or @code{NULL}, in which case @code{'utf-8'} encoding is used.
An exception is raised if the named encoding is not known to Python.  The
second argument must be a char**; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.

@ref{55d,,PyArg_ParseTuple()} will allocate a buffer of the needed size, copy the
encoded data into this buffer and adjust `*buffer' to reference the newly
allocated storage.  The caller is responsible for calling @ref{13f9,,PyMem_Free()} to
free the allocated buffer after use.

@item @code{et} (@ref{435,,str}, @ref{1bd,,bytes} or @ref{528,,bytearray}) [const char *encoding, char **buffer]

Same as @code{es} except that byte string objects are passed through without
recoding them.  Instead, the implementation assumes that the byte string object uses
the encoding passed in as parameter.

@item @code{es#} (@ref{435,,str}) [const char *encoding, char **buffer, @ref{a4e,,Py_ssize_t} *buffer_length]

This variant on @code{s#} is used for encoding Unicode into a character buffer.
Unlike the @code{es} format, this variant allows input data which contains NUL
characters.

It requires three arguments.  The first is only used as input, and must be a
const char* which points to the name of an encoding as a
NUL-terminated string, or @code{NULL}, in which case @code{'utf-8'} encoding is used.
An exception is raised if the named encoding is not known to Python.  The
second argument must be a char**; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
The text will be encoded in the encoding specified by the first argument.
The third argument must be a pointer to an integer; the referenced integer
will be set to the number of bytes in the output buffer.

Il existe deux modes de fonctionnement :

If `*buffer' points a @code{NULL} pointer, the function will allocate a buffer of
the needed size, copy the encoded data into this buffer and set `*buffer' to
reference the newly allocated storage.  The caller is responsible for calling
@ref{13f9,,PyMem_Free()} to free the allocated buffer after usage.

If `*buffer' points to a non-@code{NULL} pointer (an already allocated buffer),
@ref{55d,,PyArg_ParseTuple()} will use this location as the buffer and interpret the
initial value of `*buffer_length' as the buffer size.  It will then copy the
encoded data into the buffer and NUL-terminate it.  If the buffer is not large
enough, a @ref{1ff,,ValueError} will be set.

Dans les deux cas, `*buffer_length' est la longueur des données encodées, sans l'octet NUL de fin.

@item @code{et#} (@ref{435,,str}, @ref{1bd,,bytes} or @ref{528,,bytearray}) [const char *encoding, char **buffer, @ref{a4e,,Py_ssize_t} *buffer_length]

Same as @code{es#} except that byte string objects are passed through without recoding
them. Instead, the implementation assumes that the byte string object uses the
encoding passed in as parameter.
@end table


Modifié dans la version 3.12: @code{u}, @code{u#}, @code{Z}, and @code{Z#} are removed because they used a legacy
@code{Py_UNICODE*} representation.


@node Les nombres<2>,Autres objets,Chaînes et tampons,Analyse des arguments<2>
@anchor{c-api/arg numbers}@anchor{4a1e}
@subsubsection Les nombres



@table @asis

@item @code{b} (@ref{254,,int}) [@code{unsigned char}]

Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
unsigned char.

@item @code{B} (@ref{254,,int}) [@code{unsigned char}]

Convert a Python integer to a tiny int without overflow checking, stored in a C
unsigned char.

@item @code{h} (@ref{254,,int}) [@code{short int}]

Convert a Python integer to a C short int.

@item @code{H} (@ref{254,,int}) [@code{unsigned short int}]

Convert a Python integer to a C unsigned short int, without overflow
checking.

@item @code{i} (@ref{254,,int}) [@code{int}]

Convert a Python integer to a plain C int.

@item @code{I} (@ref{254,,int}) [@code{unsigned int}]

Convert a Python integer to a C unsigned int, without overflow
checking.

@item @code{l} (@ref{254,,int}) [@code{long int}]

Convert a Python integer to a C long int.

@item @code{k} (@ref{254,,int}) [@code{unsigned long}]

Convert a Python integer to a C unsigned long without
overflow checking.

@item @code{L} (@ref{254,,int}) [@code{long long}]

Convert a Python integer to a C long long.

@item @code{K} (@ref{254,,int}) [@code{unsigned long long}]

Convert a Python integer to a C unsigned long long
without overflow checking.

@item @code{n} (@ref{254,,int}) [@ref{a4e,,Py_ssize_t}]

Convertit un entier Python en un @ref{a4e,,Py_ssize_t}.

@item @code{c} (@ref{1bd,,bytes} ou @ref{528,,bytearray} de longueur 1) [@code{char}]

Convert a Python byte, represented as a @ref{1bd,,bytes} or
@ref{528,,bytearray} object of length 1, to a C char.


Modifié dans la version 3.3: Allow @ref{528,,bytearray} objects.


@item @code{C} (@ref{435,,str} de longueur 1) [@code{int}]

Convert a Python character, represented as a @ref{435,,str} object of
length 1, to a C int.

@item @code{f} (@ref{2eb,,float}) [@code{float}]

Convert a Python floating-point number to a C float.

@item @code{d} (@ref{2eb,,float}) [@code{double}]

Convert a Python floating-point number to a C double.

@item @code{D} (@ref{2ec,,complex}) [@code{Py_complex}]

Convertit un nombre complexe Python vers une structure @ref{4a1f,,Py_complex} C.
@end table

@node Autres objets,Fonction de l'API,Les nombres<2>,Analyse des arguments<2>
@anchor{c-api/arg other-objects}@anchor{4a20}
@subsubsection Autres objets



@table @asis

@item @code{O} (objet) [@code{PyObject *}]

Store a Python object (without any conversion) in a C object pointer.  The C
program thus receives the actual object that was passed.  A new
@ref{333,,strong reference} to the object is not created
(i.e. its reference count is not increased).
The pointer stored is not @code{NULL}.

@item @code{O!} (objet) [`typeobject', @code{PyObject *}]

Store a Python object in a C object pointer.  This is similar to @code{O}, but
takes two C arguments: the first is the address of a Python type object, the
second is the address of the C variable (of type @ref{32f,,PyObject}*) into which
the object pointer is stored.  If the Python object does not have the required
type, @ref{522,,TypeError} is raised.
@end table
@anchor{c-api/arg o-ampersand}@anchor{4a21}

@table @asis

@item @code{O&} (objet) [`converter', `anything']

Convert a Python object to a C variable through a `converter' function.  This
takes two arguments: the first is a function, the second is the address of a C
variable (of arbitrary type), converted to void*.  The `converter'
function in turn is called as follows:

@example
status = converter(object, address);
@end example

where `object' is the Python object to be converted and `address' is the
void* argument that was passed to the @code{PyArg_Parse*} function.
The returned `status' should be @code{1} for a successful conversion and @code{0} if
the conversion has failed.  When the conversion fails, the `converter' function
should raise an exception and leave the content of `address' unmodified.

If the `converter' returns @code{Py_CLEANUP_SUPPORTED}, it may get called a
second time if the argument parsing eventually fails, giving the converter a
chance to release any memory that it had already allocated. In this second
call, the `object' parameter will be @code{NULL}; `address' will have the same value
as in the original call.


Modifié dans la version 3.1: @code{Py_CLEANUP_SUPPORTED} à été ajouté.


@item @code{p} (@ref{451,,bool}) [@code{int}]

Tests the value passed in for truth (a boolean `p'redicate) and converts
the result to its equivalent C true/false integer value.
Sets the int to @code{1} if the expression was true and @code{0} if it was false.
This accepts any valid Python value.  See @ref{20e4,,Valeurs booléennes} for more
information about how Python tests values for truth.


Ajouté dans la version 3.3.


@item @code{(items)} (@ref{366,,tuple}) [`matching-items']

L'objet doit être une séquence Python dont la longueur est le nombre d'unités de formats dans `articles'. Les arguments C doivent correspondre à chaque unité de format particulière dans `articles'. Les unités de formats pour les séquences peuvent être imbriquées.
@end table

It is possible to pass "long" integers (integers whose value exceeds the
platform's @code{LONG_MAX}) however no proper range checking is done --- the
most significant bits are silently truncated when the receiving field is too
small to receive the value (actually, the semantics are inherited from downcasts
in C --- your mileage may vary).

Quelques autres caractères ont un sens dans une chaîne de format. On ne doit pas les trouvées dans des parenthèses imbriquées. Ce sont :


@table @asis

@item @code{|}

Indicates that the remaining arguments in the Python argument list are optional.
The C variables corresponding to optional arguments should be initialized to
their default value --- when an optional argument is not specified,
@ref{55d,,PyArg_ParseTuple()} does not touch the contents of the corresponding C
variable(s).

@item @code{$}

@ref{379,,PyArg_ParseTupleAndKeywords()} only:
Indicates that the remaining arguments in the Python argument list are
keyword-only.  Currently, all keyword-only arguments must also be optional
arguments, so @code{|} must always be specified before @code{$} in the format
string.


Ajouté dans la version 3.3.


@item @code{:}

The list of format units ends here; the string after the colon is used as the
function name in error messages (the "associated value" of the exception that
@ref{55d,,PyArg_ParseTuple()} raises).

@item @code{;}

La liste des unités de format s'arrête ici ; la chaîne après le point-virgule est utilise comme message d'erreur `au lieu' du message d'erreur par défaut. @code{:} et @code{;} sont mutuellement exclusifs.
@end table

Note that any Python object references which are provided to the caller are
`borrowed' references; do not release them
(i.e. do not decrement their reference count)!

Les arguments additionnels qui sont donnés à ces fonctions doivent être des adresses de variables dont le type est déterminé par la chaîne de format. Elles sont utilisées pour stocker les valeurs du `n'-uplet d'entrée. Il y a quelques cas, comme décrit précédemment dans le liste des unités de formats, où ces paramètres sont utilisés comme valeurs d'entrée. Dans ce cas, ils devraient correspondre à ce qui est spécifié pour l'unité de format correspondante.

For the conversion to succeed, the `arg' object must match the format
and the format must be exhausted.  On success, the
@code{PyArg_Parse*} functions return true, otherwise they return
false and raise an appropriate exception. When the
@code{PyArg_Parse*} functions fail due to conversion failure in one
of the format units, the variables at the addresses corresponding to that
and the following format units are left untouched.

@node Fonction de l'API,,Autres objets,Analyse des arguments<2>
@anchor{c-api/arg api-functions}@anchor{4a22}
@subsubsection Fonction de l'API


@geindex PyArg_ParseTuple (C function)
@anchor{c-api/arg c PyArg_ParseTuple}@anchor{55d}
@deffn {C Fonction} int PyArg_ParseTuple (PyObject *args, const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
Parse the parameters of a function that takes only positional parameters into
local variables.  Returns true on success; on failure, it returns false and
raises the appropriate exception.
@end deffn

@geindex PyArg_VaParse (C function)
@anchor{c-api/arg c PyArg_VaParse}@anchor{4868}
@deffn {C Fonction} int PyArg_VaParse (PyObject *args, const char *format, va_list vargs)
` Part of the @ref{53e,,Stable ABI}.'
Identical to @ref{55d,,PyArg_ParseTuple()}, except that it accepts a va_list rather
than a variable number of arguments.
@end deffn

@geindex PyArg_ParseTupleAndKeywords (C function)
@anchor{c-api/arg c PyArg_ParseTupleAndKeywords}@anchor{379}
@deffn {C Fonction} int PyArg_ParseTupleAndKeywords (PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)
` Part of the @ref{53e,,Stable ABI}.'
Parse the parameters of a function that takes both positional and keyword
parameters into local variables.
The `keywords' argument is a @code{NULL}-terminated array of keyword parameter
names specified as null-terminated ASCII or UTF-8 encoded C strings.
Empty names denote
@ref{a73,,positional-only parameters}.
Returns true on success; on failure, it returns false and raises the
appropriate exception.

@cartouche
@quotation Note 
The `keywords' parameter declaration is char *const* in C and
const char *const* in C++.
This can be overridden with the @ref{37b,,PY_CXX_CONST} macro.
@end quotation
@end cartouche


Modifié dans la version 3.6: Added support for @ref{a73,,positional-only parameters}.



Modifié dans la version 3.13: The `keywords' parameter has now type char *const* in C and
const char *const* in C++, instead of char**.
Added support for non-ASCII keyword parameter names.

@end deffn

@geindex PyArg_VaParseTupleAndKeywords (C function)
@anchor{c-api/arg c PyArg_VaParseTupleAndKeywords}@anchor{37a}
@deffn {C Fonction} int PyArg_VaParseTupleAndKeywords (PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)
` Part of the @ref{53e,,Stable ABI}.'
Identical to @ref{379,,PyArg_ParseTupleAndKeywords()}, except that it accepts a
va_list rather than a variable number of arguments.
@end deffn

@geindex PyArg_ValidateKeywordArguments (C function)
@anchor{c-api/arg c PyArg_ValidateKeywordArguments}@anchor{4869}
@deffn {C Fonction} int PyArg_ValidateKeywordArguments (PyObject*)
` Part of the @ref{53e,,Stable ABI}.'
Ensure that the keys in the keywords argument dictionary are strings.  This
is only needed if @ref{379,,PyArg_ParseTupleAndKeywords()} is not used, since the
latter already does this check.


Ajouté dans la version 3.2.

@end deffn

@geindex PyArg_Parse (C function)
@anchor{c-api/arg c PyArg_Parse}@anchor{1972}
@deffn {C Fonction} int PyArg_Parse (PyObject *args, const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
Parse the parameter of a function that takes a single positional parameter
into a local variable.  Returns true on success; on failure, it returns
false and raises the appropriate exception.

Exemple :

@example
// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
@{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) @{
        return NULL;
    @}
    // ... use value ...
@}
@end example
@end deffn

@geindex PyArg_UnpackTuple (C function)
@anchor{c-api/arg c PyArg_UnpackTuple}@anchor{14be}
@deffn {C Fonction} int PyArg_UnpackTuple (PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
` Part of the @ref{53e,,Stable ABI}.'
A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments.  Functions which use this method to retrieve
their parameters should be declared as @ref{14c0,,METH_VARARGS} in function or
method tables.  The tuple containing the actual parameters should be passed as
`args'; it must actually be a tuple.  The length of the tuple must be at least
`min' and no more than `max'; `min' and `max' may be equal.  Additional
arguments must be passed to the function, each of which should be a pointer to a
@ref{32f,,PyObject}* variable; these will be filled in with the values from
`args'; they will contain @ref{334,,borrowed references}.
The variables which correspond
to optional parameters not given by `args' will not be filled in; these should
be initialized by the caller. This function returns true on success and false if
`args' is not a tuple or contains the wrong number of elements; an exception
will be set if there was a failure.

This is an example of the use of this function, taken from the sources for the
@code{_weakref} helper module for weak references:

@example
static PyObject *
weakref_ref(PyObject *self, PyObject *args)
@{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) @{
        result = PyWeakref_NewRef(object, callback);
    @}
    return result;
@}
@end example

The call to @ref{14be,,PyArg_UnpackTuple()} in this example is entirely equivalent to
this call to @ref{55d,,PyArg_ParseTuple()}:

@example
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
@end example
@end deffn

@geindex PY_CXX_CONST (C macro)
@anchor{c-api/arg c PY_CXX_CONST}@anchor{37b}
@deffn {C Macro} PY_CXX_CONST

The value to be inserted, if any, before char *const*
in the `keywords' parameter declaration of
@ref{379,,PyArg_ParseTupleAndKeywords()} and
@ref{37a,,PyArg_VaParseTupleAndKeywords()}.
Default empty for C and @code{const} for C++
(const char *const*).
To override, define it to the desired value before including
@code{Python.h}.


Ajouté dans la version 3.13.

@end deffn

@node Construction des valeurs,,Analyse des arguments<2>,Analyse des arguments et construction des valeurs
@anchor{c-api/arg building-values}@anchor{4a23}
@subsubsection Construction des valeurs


@geindex Py_BuildValue (C function)
@anchor{c-api/arg c Py_BuildValue}@anchor{894}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_BuildValue (const char *format, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a new value based on a format string similar to those accepted by the
@code{PyArg_Parse*} family of functions and a sequence of values.  Returns
the value or @code{NULL} in the case of an error; an exception will be raised if
@code{NULL} is returned.

@ref{894,,Py_BuildValue()} does not always build a tuple.  It builds a tuple only if
its format string contains two or more format units.  If the format string is
empty, it returns @code{None}; if it contains exactly one format unit, it returns
whatever object is described by that format unit.  To force it to return a tuple
of size 0 or one, parenthesize the format string.

When memory buffers are passed as parameters to supply data to build objects, as
for the @code{s} and @code{s#} formats, the required data is copied.  Buffers provided
by the caller are never referenced by the objects created by
@ref{894,,Py_BuildValue()}.  In other words, if your code invokes @code{malloc()}
and passes the allocated memory to @ref{894,,Py_BuildValue()}, your code is
responsible for calling @code{free()} for that memory once
@ref{894,,Py_BuildValue()} returns.

In the following description, the quoted form is the format unit; the entry in
(round) parentheses is the Python object type that the format unit will return;
and the entry in [square] brackets is the type of the C value(s) to be passed.

The characters space, tab, colon and comma are ignored in format strings (but
not within format units such as @code{s#}).  This can be used to make long format
strings a tad more readable.


@table @asis

@item @code{s} (@ref{435,,str} ou @code{None}) [@code{const char *}]

Convert a null-terminated C string to a Python @ref{435,,str} object using @code{'utf-8'}
encoding. If the C string pointer is @code{NULL}, @code{None} is used.

@item @code{s#} (@ref{435,,str} or @code{None}) [const char *, @ref{a4e,,Py_ssize_t}]

Convert a C string and its length to a Python @ref{435,,str} object using @code{'utf-8'}
encoding. If the C string pointer is @code{NULL}, the length is ignored and
@code{None} is returned.

@item @code{y} (@ref{1bd,,bytes}) [@code{const char *}]

This converts a C string to a Python @ref{1bd,,bytes} object.  If the C
string pointer is @code{NULL}, @code{None} is returned.

@item @code{y#} (@ref{1bd,,bytes}) [const char *, @ref{a4e,,Py_ssize_t}]

This converts a C string and its lengths to a Python object.  If the C
string pointer is @code{NULL}, @code{None} is returned.

@item @code{z} (@ref{435,,str} ou @code{None}) [@code{const char *}]

Same as @code{s}.

@item @code{z#} (@ref{435,,str} or @code{None}) [const char *, @ref{a4e,,Py_ssize_t}]

Same as @code{s#}.

@item @code{u} (@ref{435,,str}) [@code{const wchar_t *}]

Convert a null-terminated @code{wchar_t} buffer of Unicode (UTF-16 or UCS-4)
data to a Python Unicode object.  If the Unicode buffer pointer is @code{NULL},
@code{None} is returned.

@item @code{u#} (@ref{435,,str}) [const wchar_t *, @ref{a4e,,Py_ssize_t}]

Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
Unicode object.   If the Unicode buffer pointer is @code{NULL}, the length is ignored
and @code{None} is returned.

@item @code{U} (@ref{435,,str} ou @code{None}) [@code{const char *}]

Same as @code{s}.

@item @code{U#} (@ref{435,,str} or @code{None}) [const char *, @ref{a4e,,Py_ssize_t}]

Same as @code{s#}.

@item @code{i} (@ref{254,,int}) [@code{int}]

Convert a plain C int to a Python integer object.

@item @code{b} (@ref{254,,int}) [@code{char}]

Convert a plain C char to a Python integer object.

@item @code{h} (@ref{254,,int}) [@code{short int}]

Convert a plain C short int to a Python integer object.

@item @code{l} (@ref{254,,int}) [@code{long int}]

Convert a C long int to a Python integer object.

@item @code{B} (@ref{254,,int}) [@code{unsigned char}]

Convert a C unsigned char to a Python integer object.

@item @code{H} (@ref{254,,int}) [@code{unsigned short int}]

Convert a C unsigned short int to a Python integer object.

@item @code{I} (@ref{254,,int}) [@code{unsigned int}]

Convert a C unsigned int to a Python integer object.

@item @code{k} (@ref{254,,int}) [@code{unsigned long}]

Convert a C unsigned long to a Python integer object.

@item @code{L} (@ref{254,,int}) [@code{long long}]

Convert a C long long to a Python integer object.

@item @code{K} (@ref{254,,int}) [@code{unsigned long long}]

Convert a C unsigned long long to a Python integer object.

@item @code{n} (@ref{254,,int}) [@ref{a4e,,Py_ssize_t}]

Convert a C @ref{a4e,,Py_ssize_t} to a Python integer.

@item @code{c} (@ref{1bd,,bytes} de taille 1) [@code{char}]

Convert a C int representing a byte to a Python @ref{1bd,,bytes} object of
length 1.

@item @code{C} (@ref{435,,str} de longueur 1) [@code{int}]

Convert a C int representing a character to Python @ref{435,,str}
object of length 1.

@item @code{d} (@ref{2eb,,float}) [@code{double}]

Convert a C double to a Python floating-point number.

@item @code{f} (@ref{2eb,,float}) [@code{float}]

Convert a C float to a Python floating-point number.

@item @code{D} (@ref{2ec,,complex}) [@code{Py_complex *}]

Convert a C @ref{4a1f,,Py_complex} structure to a Python complex number.

@item @code{O} (objet) [@code{PyObject *}]

Pass a Python object untouched but create a new
@ref{333,,strong reference} to it
(i.e. its reference count is incremented by one).
If the object passed in is a @code{NULL} pointer, it is assumed
that this was caused because the call producing the argument found an error and
set an exception. Therefore, @ref{894,,Py_BuildValue()} will return @code{NULL} but won't
raise an exception.  If no exception has been raised yet, @ref{561,,SystemError} is
set.

@item @code{S} (objet) [@code{PyObject *}]

Same as @code{O}.

@item @code{N} (objet) [@code{PyObject *}]

Same as @code{O}, except it doesn't create a new @ref{333,,strong reference}.
Useful when the object is created by a call to an object constructor in the
argument list.

@item @code{O&} (objet) [`converter', `anything']

Convert `anything' to a Python object through a `converter' function.  The
function is called with `anything' (which should be compatible with void*)
as its argument and should return a "new" Python object, or @code{NULL} if an
error occurred.

@item @code{(items)} (@ref{366,,tuple}) [`matching-items']

Convert a sequence of C values to a Python tuple with the same number of items.

@item @code{[items]} (@ref{5fc,,list}) [`matching-items']

Convert a sequence of C values to a Python list with the same number of items.

@item @code{@{items@}} (@ref{253,,dict}) [`matching-items']

Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
C values adds one item to the dictionary, serving as key and value,
respectively.
@end table

If there is an error in the format string, the @ref{561,,SystemError} exception is
set and @code{NULL} returned.
@end deffn

@geindex Py_VaBuildValue (C function)
@anchor{c-api/arg c Py_VaBuildValue}@anchor{49ac}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_VaBuildValue (const char *format, va_list vargs)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Identical to @ref{894,,Py_BuildValue()}, except that it accepts a va_list
rather than a variable number of arguments.
@end deffn

@node Conversion et formatage de chaînes,PyHash API,Analyse des arguments et construction des valeurs,Utilitaires<2>
@anchor{c-api/conversion doc}@anchor{4a24}@anchor{c-api/conversion string-conversion}@anchor{4a25}@anchor{c-api/conversion string-conversion-and-formatting}@anchor{4a26}
@subsection Conversion et formatage de chaînes


Fonctions de conversion pour les nombres et pour la sortie des chaînes formatées.

@geindex PyOS_snprintf (C function)
@anchor{c-api/conversion c PyOS_snprintf}@anchor{14c1}
@deffn {C Fonction} int PyOS_snprintf (char *str, size_t size, const char *format, ...)
` Part of the @ref{53e,,Stable ABI}.'
Output not more than `size' bytes to `str' according to the format string
`format' and the extra arguments. See the Unix man page @code{snprintf(3)@footnote{https://manpages.debian.org/snprintf(3)}}.
@end deffn

@geindex PyOS_vsnprintf (C function)
@anchor{c-api/conversion c PyOS_vsnprintf}@anchor{14c2}
@deffn {C Fonction} int PyOS_vsnprintf (char *str, size_t size, const char *format, va_list va)
` Part of the @ref{53e,,Stable ABI}.'
Output not more than `size' bytes to `str' according to the format string
`format' and the variable argument list `va'. Unix man page
@code{vsnprintf(3)@footnote{https://manpages.debian.org/vsnprintf(3)}}.
@end deffn

@ref{14c1,,PyOS_snprintf()} and @ref{14c2,,PyOS_vsnprintf()} wrap the Standard C library
functions @code{snprintf()} and @code{vsnprintf()}. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.

The wrappers ensure that @code{str[size-1]} is always @code{'\0'} upon return. They
never write more than `size' bytes (including the trailing @code{'\0'}) into str.
Both functions require that @code{str != NULL}, @code{size > 0}, @code{format != NULL}
and @code{size < INT_MAX}. Note that this means there is no equivalent to the C99
@code{n = snprintf(NULL, 0, ...)} which would determine the necessary buffer size.

The return value (`rv') for these functions should be interpreted as follows:


@itemize *

@item 
When @code{0 <= rv < size}, the output conversion was successful and `rv'
characters were written to `str' (excluding the trailing @code{'\0'} byte at
@code{str[rv]}).

@item 
When @code{rv >= size}, the output conversion was truncated and a buffer with
@code{rv + 1} bytes would have been needed to succeed. @code{str[size-1]} is @code{'\0'}
in this case.

@item 
When @code{rv < 0}, "something bad happened." @code{str[size-1]} is @code{'\0'} in
this case too, but the rest of `str' is undefined. The exact cause of the error
depends on the underlying platform.
@end itemize

The following functions provide locale-independent string to number conversions.

@geindex PyOS_strtoul (C function)
@anchor{c-api/conversion c PyOS_strtoul}@anchor{491c}
@deffn {C Fonction} unsigned long PyOS_strtoul (const char *str, char **ptr, int base)
` Part of the @ref{53e,,Stable ABI}.'
Convert the initial part of the string in @code{str} to an unsigned long value according to the given @code{base}, which must be between @code{2} and
@code{36} inclusive, or be the special value @code{0}.

Leading white space and case of characters are ignored.  If @code{base} is zero
it looks for a leading @code{0b}, @code{0o} or @code{0x} to tell which base.  If
these are absent it defaults to @code{10}.  Base must be 0 or between 2 and 36
(inclusive).  If @code{ptr} is non-@code{NULL} it will contain a pointer to the
end of the scan.

If the converted value falls out of range of corresponding return type,
range error occurs (@code{errno} is set to @code{ERANGE}) and
@code{ULONG_MAX} is returned.  If no conversion can be performed, @code{0}
is returned.

See also the Unix man page @code{strtoul(3)@footnote{https://manpages.debian.org/strtoul(3)}}.


Ajouté dans la version 3.2.

@end deffn

@geindex PyOS_strtol (C function)
@anchor{c-api/conversion c PyOS_strtol}@anchor{491b}
@deffn {C Fonction} long PyOS_strtol (const char *str, char **ptr, int base)
` Part of the @ref{53e,,Stable ABI}.'
Convert the initial part of the string in @code{str} to an long value
according to the given @code{base}, which must be between @code{2} and @code{36}
inclusive, or be the special value @code{0}.

Same as @ref{491c,,PyOS_strtoul()}, but return a long value instead
and @code{LONG_MAX} on overflows.

See also the Unix man page @code{strtol(3)@footnote{https://manpages.debian.org/strtol(3)}}.


Ajouté dans la version 3.2.

@end deffn

@geindex PyOS_string_to_double (C function)
@anchor{c-api/conversion c PyOS_string_to_double}@anchor{1273}
@deffn {C Fonction} double PyOS_string_to_double (const char *s, char **endptr, PyObject *overflow_exception)
` Part of the @ref{53e,,Stable ABI}.'
Convert a string @code{s} to a double, raising a Python
exception on failure.  The set of accepted strings corresponds to
the set of strings accepted by Python's @ref{2eb,,float()} constructor,
except that @code{s} must not have leading or trailing whitespace.
The conversion is independent of the current locale.

If @code{endptr} is @code{NULL}, convert the whole string.  Raise
@ref{1ff,,ValueError} and return @code{-1.0} if the string is not a valid
representation of a floating-point number.

If endptr is not @code{NULL}, convert as much of the string as
possible and set @code{*endptr} to point to the first unconverted
character.  If no initial segment of the string is the valid
representation of a floating-point number, set @code{*endptr} to point
to the beginning of the string, raise ValueError, and return
@code{-1.0}.

If @code{s} represents a value that is too large to store in a float
(for example, @code{"1e500"} is such a string on many platforms) then
if @code{overflow_exception} is @code{NULL} return @code{Py_HUGE_VAL} (with
an appropriate sign) and don't set any exception.  Otherwise,
@code{overflow_exception} must point to a Python exception object;
raise that exception and return @code{-1.0}.  In both cases, set
@code{*endptr} to point to the first character after the converted value.

If any other error occurs during the conversion (for example an
out-of-memory error), set the appropriate Python exception and
return @code{-1.0}.


Ajouté dans la version 3.1.

@end deffn

@geindex PyOS_double_to_string (C function)
@anchor{c-api/conversion c PyOS_double_to_string}@anchor{4919}
@deffn {C Fonction} char *PyOS_double_to_string (double val, char format_code, int precision, int flags, int *ptype)
` Part of the @ref{53e,,Stable ABI}.'
Convert a double `val' to a string using supplied
`format_code', `precision', and `flags'.

`format_code' must be one of @code{'e'}, @code{'E'}, @code{'f'}, @code{'F'},
@code{'g'}, @code{'G'} or @code{'r'}.  For @code{'r'}, the supplied `precision'
must be 0 and is ignored.  The @code{'r'} format code specifies the
standard @ref{7e7,,repr()} format.

`flags' can be zero or more of the values @code{Py_DTSF_SIGN},
@code{Py_DTSF_ADD_DOT_0}, or @code{Py_DTSF_ALT}, or-ed together:


@itemize *

@item 
@code{Py_DTSF_SIGN} means to always precede the returned string with a sign
character, even if `val' is non-negative.

@item 
@code{Py_DTSF_ADD_DOT_0} means to ensure that the returned string will not look
like an integer.

@item 
@code{Py_DTSF_ALT} means to apply "alternate" formatting rules.  See the
documentation for the @ref{14c1,,PyOS_snprintf()} @code{'#'} specifier for
details.
@end itemize

If `ptype' is non-@code{NULL}, then the value it points to will be set to one of
@code{Py_DTST_FINITE}, @code{Py_DTST_INFINITE}, or @code{Py_DTST_NAN}, signifying that
`val' is a finite number, an infinite number, or not a number, respectively.

The return value is a pointer to `buffer' with the converted string or
@code{NULL} if the conversion failed. The caller is responsible for freeing the
returned string by calling @ref{13f9,,PyMem_Free()}.


Ajouté dans la version 3.1.

@end deffn

@geindex PyOS_stricmp (C function)
@anchor{c-api/conversion c PyOS_stricmp}@anchor{4a27}
@deffn {C Fonction} int PyOS_stricmp (const char *s1, const char *s2)

Case insensitive comparison of strings. The function works almost
identically to @code{strcmp()} except that it ignores the case.
@end deffn

@geindex PyOS_strnicmp (C function)
@anchor{c-api/conversion c PyOS_strnicmp}@anchor{4a28}
@deffn {C Fonction} int PyOS_strnicmp (const char *s1, const char *s2, Py_ssize_t size)

Case insensitive comparison of strings. The function works almost
identically to @code{strncmp()} except that it ignores the case.
@end deffn

@node PyHash API,Réflexion,Conversion et formatage de chaînes,Utilitaires<2>
@anchor{c-api/hash doc}@anchor{4a29}@anchor{c-api/hash pyhash-api}@anchor{4a2a}
@subsection PyHash API


See also the @ref{4815,,PyTypeObject.tp_hash} member and @ref{2129,,Hachage des types numériques}.

@geindex Py_hash_t (C type)
@anchor{c-api/hash c Py_hash_t}@anchor{1242}
@deffn {C Type} type Py_hash_t

Hash value type: signed integer.


Ajouté dans la version 3.2.

@end deffn

@geindex Py_uhash_t (C type)
@anchor{c-api/hash c Py_uhash_t}@anchor{4a2b}
@deffn {C Type} type Py_uhash_t

Hash value type: unsigned integer.


Ajouté dans la version 3.2.

@end deffn

@geindex PyHASH_MODULUS (C macro)
@anchor{c-api/hash c PyHASH_MODULUS}@anchor{15f2}
@deffn {C Macro} PyHASH_MODULUS

The Mersenne prime@footnote{https://en.wikipedia.org/wiki/Mersenne_prime} @code{P = 2**n -1}, used for numeric hash scheme.


Ajouté dans la version 3.13.

@end deffn

@geindex PyHASH_BITS (C macro)
@anchor{c-api/hash c PyHASH_BITS}@anchor{15f3}
@deffn {C Macro} PyHASH_BITS

The exponent @code{n} of @code{P} in @ref{15f2,,PyHASH_MODULUS}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyHASH_MULTIPLIER (C macro)
@anchor{c-api/hash c PyHASH_MULTIPLIER}@anchor{15ab}
@deffn {C Macro} PyHASH_MULTIPLIER

Prime multiplier used in string and various other hashes.


Ajouté dans la version 3.13.

@end deffn

@geindex PyHASH_INF (C macro)
@anchor{c-api/hash c PyHASH_INF}@anchor{15f4}
@deffn {C Macro} PyHASH_INF

The hash value returned for a positive infinity.


Ajouté dans la version 3.13.

@end deffn

@geindex PyHASH_IMAG (C macro)
@anchor{c-api/hash c PyHASH_IMAG}@anchor{15f5}
@deffn {C Macro} PyHASH_IMAG

The multiplier used for the imaginary part of a complex number.


Ajouté dans la version 3.13.

@end deffn

@geindex PyHash_FuncDef (C type)
@anchor{c-api/hash c PyHash_FuncDef}@anchor{4a2c}
@deffn {C Type} type PyHash_FuncDef

Hash function definition used by @ref{4a2d,,PyHash_GetFuncDef()}.

@c c::member:: Py_hash_t (*const hash)(const void *, Py_ssize_t)
@c 
@c Hash function.

@geindex PyHash_FuncDef.name (C member)
@anchor{c-api/hash c PyHash_FuncDef name}@anchor{4a2e}
@deffn {C Membre} const char *name

Hash function name (UTF-8 encoded string).
@end deffn

@geindex PyHash_FuncDef.hash_bits (C member)
@anchor{c-api/hash c PyHash_FuncDef hash_bits}@anchor{4a2f}
@deffn {C Membre} const int hash_bits

Internal size of the hash value in bits.
@end deffn

@geindex PyHash_FuncDef.seed_bits (C member)
@anchor{c-api/hash c PyHash_FuncDef seed_bits}@anchor{4a30}
@deffn {C Membre} const int seed_bits

Size of seed input in bits.
@end deffn


Ajouté dans la version 3.4.

@end deffn

@geindex PyHash_GetFuncDef (C function)
@anchor{c-api/hash c PyHash_GetFuncDef}@anchor{4a2d}
@deffn {C Fonction} @ref{4a2c,,PyHash_FuncDef} *PyHash_GetFuncDef (void)

Get the hash function definition.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 456
PEP 456@footnote{https://peps.python.org/pep-0456/} "Secure and interchangeable hash algorithm".



Ajouté dans la version 3.4.

@end deffn

@geindex Py_HashPointer (C function)
@anchor{c-api/hash c Py_HashPointer}@anchor{35e}
@deffn {C Fonction} @ref{1242,,Py_hash_t} Py_HashPointer (const void *ptr)

Hash a pointer value: process the pointer value as an integer (cast it to
@code{uintptr_t} internally). The pointer is not dereferenced.

The function cannot fail: it cannot return @code{-1}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyObject_GenericHash (C function)
@anchor{c-api/hash c PyObject_GenericHash}@anchor{35d}
@deffn {C Fonction} @ref{1242,,Py_hash_t} PyObject_GenericHash (PyObject *obj)

Generic hashing function that is meant to be put into a type
object's @code{tp_hash} slot.
Its result only depends on the object's identity.

`Particularité de l'implémentation CPython :' In CPython, it is equivalent to @ref{35e,,Py_HashPointer()}.


Ajouté dans la version 3.13.

@end deffn

@node Réflexion,Codec registry and support functions,PyHash API,Utilitaires<2>
@anchor{c-api/reflection doc}@anchor{4a31}@anchor{c-api/reflection id1}@anchor{4a32}@anchor{c-api/reflection reflection}@anchor{4a33}
@subsection Réflexion


@geindex PyEval_GetBuiltins (C function)
@anchor{c-api/reflection c PyEval_GetBuiltins}@anchor{347}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_GetBuiltins (void)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'

Obsolète depuis la version 3.13: Use @ref{346,,PyEval_GetFrameBuiltins()} instead.


Renvoie un dictionnaire des fonctions natives de la `frame' en cours d'exécution, ou si aucune `frame' n'est exécutée, les fonctions natives du `thread' indiqué par le `thread state'.
@end deffn

@geindex PyEval_GetLocals (C function)
@anchor{c-api/reflection c PyEval_GetLocals}@anchor{34b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_GetLocals (void)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'

Obsolète depuis la version 3.13: Use either @ref{34a,,PyEval_GetFrameLocals()} to obtain the same behaviour as calling
@ref{140,,locals()} in Python code, or else call @ref{415,,PyFrame_GetLocals()} on the result
of @ref{174a,,PyEval_GetFrame()} to access the @ref{180,,f_locals} attribute of the
currently executing frame.


Return a mapping providing access to the local variables in the current execution frame,
or @code{NULL} if no frame is currently executing.

Refer to @ref{140,,locals()} for details of the mapping returned at different scopes.

As this function returns a @ref{334,,borrowed reference}, the dictionary returned for
@ref{17c,,optimized scopes} is cached on the frame object and will remain
alive as long as the frame object does. Unlike @ref{34a,,PyEval_GetFrameLocals()} and
@ref{140,,locals()}, subsequent calls to this function in the same frame will update the
contents of the cached dictionary to reflect changes in the state of the local variables
rather than returning a new snapshot.


Modifié dans la version 3.13: As part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}, @ref{415,,PyFrame_GetLocals()}, @ref{140,,locals()}, and
@ref{180,,FrameType.f_locals} no longer make use of the shared cache
dictionary. Refer to the @ref{141,,What's New entry} for
additional details.

@end deffn

@geindex PyEval_GetGlobals (C function)
@anchor{c-api/reflection c PyEval_GetGlobals}@anchor{349}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_GetGlobals (void)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'

Obsolète depuis la version 3.13: Use @ref{348,,PyEval_GetFrameGlobals()} instead.


Return a dictionary of the global variables in the current execution frame,
or @code{NULL} if no frame is currently executing.
@end deffn

@geindex PyEval_GetFrame (C function)
@anchor{c-api/reflection c PyEval_GetFrame}@anchor{174a}
@deffn {C Fonction} @ref{773,,PyFrameObject} *PyEval_GetFrame (void)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return the current thread state's frame, which is @code{NULL} if no frame is
currently executing.

See also @ref{778,,PyThreadState_GetFrame()}.
@end deffn

@geindex PyEval_GetFrameBuiltins (C function)
@anchor{c-api/reflection c PyEval_GetFrameBuiltins}@anchor{346}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_GetFrameBuiltins (void)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Renvoie un dictionnaire des fonctions natives de la `frame' en cours d'exécution, ou si aucune `frame' n'est exécutée, les fonctions natives du `thread' indiqué par le `thread state'.


Ajouté dans la version 3.13.

@end deffn

@geindex PyEval_GetFrameLocals (C function)
@anchor{c-api/reflection c PyEval_GetFrameLocals}@anchor{34a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_GetFrameLocals (void)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return a dictionary of the local variables in the current execution frame,
or @code{NULL} if no frame is currently executing. Equivalent to calling
@ref{140,,locals()} in Python code.

To access @ref{180,,f_locals} on the current frame without making an independent
snapshot in @ref{17c,,optimized scopes}, call @ref{415,,PyFrame_GetLocals()}
on the result of @ref{174a,,PyEval_GetFrame()}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyEval_GetFrameGlobals (C function)
@anchor{c-api/reflection c PyEval_GetFrameGlobals}@anchor{348}
@deffn {C Fonction} @ref{32f,,PyObject} *PyEval_GetFrameGlobals (void)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return a dictionary of the global variables in the current execution frame,
or @code{NULL} if no frame is currently executing. Equivalent to calling
@ref{17f5,,globals()} in Python code.


Ajouté dans la version 3.13.

@end deffn

@geindex PyEval_GetFuncName (C function)
@anchor{c-api/reflection c PyEval_GetFuncName}@anchor{48ba}
@deffn {C Fonction} const char *PyEval_GetFuncName (PyObject *func)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie le nom de `func' s'il s'agit d'une fonction, d'une classe ou d'un objet d'instance, sinon le nom du type de `func'
@end deffn

@geindex PyEval_GetFuncDesc (C function)
@anchor{c-api/reflection c PyEval_GetFuncDesc}@anchor{48b9}
@deffn {C Fonction} const char *PyEval_GetFuncDesc (PyObject *func)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie une description en chaîne de caractères, en fonction du type de `func'. Les valeurs renvoyées peuvent être @code{"()"} pour les fonction et les méthodes, @code{\" constructor\"}, @code{\" instance\"}, @code{\" object\"}. Concaténé avec le résultat de @ref{48ba,,PyEval_GetFuncName()}, le résultat sera une description de `func'
@end deffn

@node Codec registry and support functions,PyTime C API,Réflexion,Utilitaires<2>
@anchor{c-api/codec doc}@anchor{4a34}@anchor{c-api/codec codec-registry}@anchor{d23}@anchor{c-api/codec codec-registry-and-support-functions}@anchor{4a35}
@subsection Codec registry and support functions


@geindex PyCodec_Register (C function)
@anchor{c-api/codec c PyCodec_Register}@anchor{4890}
@deffn {C Fonction} int PyCodec_Register (PyObject *search_function)
` Part of the @ref{53e,,Stable ABI}.'
Register a new codec search function.

As side effect, this tries to load the @code{encodings} package, if not yet
done, to make sure that it is always first in the list of search functions.
@end deffn

@geindex PyCodec_Unregister (C function)
@anchor{c-api/codec c PyCodec_Unregister}@anchor{883}
@deffn {C Fonction} int PyCodec_Unregister (PyObject *search_function)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Unregister a codec search function and clear the registry's cache.
If the search function is not registered, do nothing.
Return 0 on success. Raise an exception and return -1 on error.


Ajouté dans la version 3.10.

@end deffn

@geindex PyCodec_KnownEncoding (C function)
@anchor{c-api/codec c PyCodec_KnownEncoding}@anchor{488e}
@deffn {C Fonction} int PyCodec_KnownEncoding (const char *encoding)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} or @code{0} depending on whether there is a registered codec for
the given `encoding'.  This function always succeeds.
@end deffn

@geindex PyCodec_Encode (C function)
@anchor{c-api/codec c PyCodec_Encode}@anchor{3f6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_Encode (PyObject *object, const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Generic codec based encoding API.

`object' is passed through the encoder function found for the given
`encoding' using the error handling method defined by `errors'.  `errors' may
be @code{NULL} to use the default method defined for the codec.  Raises a
@ref{2155,,LookupError} if no encoder can be found.
@end deffn

@geindex PyCodec_Decode (C function)
@anchor{c-api/codec c PyCodec_Decode}@anchor{3f5}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_Decode (PyObject *object, const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Generic codec based decoding API.

`object' is passed through the decoder function found for the given
`encoding' using the error handling method defined by `errors'.  `errors' may
be @code{NULL} to use the default method defined for the codec.  Raises a
@ref{2155,,LookupError} if no encoder can be found.
@end deffn

@menu
* Codec lookup API:: 
* Registry API for Unicode encoding error handlers:: 

@end menu

@node Codec lookup API,Registry API for Unicode encoding error handlers,,Codec registry and support functions
@anchor{c-api/codec codec-lookup-api}@anchor{4a36}
@subsubsection Codec lookup API


In the following functions, the `encoding' string is looked up converted to all
lower-case characters, which makes encodings looked up through this mechanism
effectively case-insensitive.  If no codec is found, a @ref{33a,,KeyError} is set
and @code{NULL} returned.

@geindex PyCodec_Encoder (C function)
@anchor{c-api/codec c PyCodec_Encoder}@anchor{488a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_Encoder (const char *encoding)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Get an encoder function for the given `encoding'.
@end deffn

@geindex PyCodec_Decoder (C function)
@anchor{c-api/codec c PyCodec_Decoder}@anchor{4889}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_Decoder (const char *encoding)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Get a decoder function for the given `encoding'.
@end deffn

@geindex PyCodec_IncrementalEncoder (C function)
@anchor{c-api/codec c PyCodec_IncrementalEncoder}@anchor{488d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_IncrementalEncoder (const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Get an @ref{234f,,IncrementalEncoder} object for the given `encoding'.
@end deffn

@geindex PyCodec_IncrementalDecoder (C function)
@anchor{c-api/codec c PyCodec_IncrementalDecoder}@anchor{488c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_IncrementalDecoder (const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Get an @ref{2350,,IncrementalDecoder} object for the given `encoding'.
@end deffn

@geindex PyCodec_StreamReader (C function)
@anchor{c-api/codec c PyCodec_StreamReader}@anchor{4893}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_StreamReader (const char *encoding, PyObject *stream, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Get a @ref{2354,,StreamReader} factory function for the given `encoding'.
@end deffn

@geindex PyCodec_StreamWriter (C function)
@anchor{c-api/codec c PyCodec_StreamWriter}@anchor{4894}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_StreamWriter (const char *encoding, PyObject *stream, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Get a @ref{2353,,StreamWriter} factory function for the given `encoding'.
@end deffn

@node Registry API for Unicode encoding error handlers,,Codec lookup API,Codec registry and support functions
@anchor{c-api/codec registry-api-for-unicode-encoding-error-handlers}@anchor{4a37}
@subsubsection Registry API for Unicode encoding error handlers


@geindex PyCodec_RegisterError (C function)
@anchor{c-api/codec c PyCodec_RegisterError}@anchor{4891}
@deffn {C Fonction} int PyCodec_RegisterError (const char *name, PyObject *error)
` Part of the @ref{53e,,Stable ABI}.'
Register the error handling callback function `error' under the given `name'.
This callback function will be called by a codec when it encounters
unencodable characters/undecodable bytes and `name' is specified as the error
parameter in the call to the encode/decode function.

The callback gets a single argument, an instance of
@ref{662,,UnicodeEncodeError}, @ref{a01,,UnicodeDecodeError} or
@ref{2224,,UnicodeTranslateError} that holds information about the problematic
sequence of characters or bytes and their offset in the original string (see
@ref{49f8,,Objets exception Unicode} for functions to extract this information).  The
callback must either raise the given exception, or return a two-item tuple
containing the replacement for the problematic sequence, and an integer
giving the offset in the original string at which encoding/decoding should be
resumed.

Return @code{0} on success, @code{-1} on error.
@end deffn

@geindex PyCodec_LookupError (C function)
@anchor{c-api/codec c PyCodec_LookupError}@anchor{488f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_LookupError (const char *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Lookup the error handling callback function registered under `name'.  As a
special case @code{NULL} can be passed, in which case the error handling callback
for "strict" will be returned.
@end deffn

@geindex PyCodec_StrictErrors (C function)
@anchor{c-api/codec c PyCodec_StrictErrors}@anchor{4895}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_StrictErrors (PyObject *exc)
`Valeur de retour : toujours NULL.'` Part of the @ref{53e,,Stable ABI}.'
Raise `exc' as an exception.
@end deffn

@geindex PyCodec_IgnoreErrors (C function)
@anchor{c-api/codec c PyCodec_IgnoreErrors}@anchor{488b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_IgnoreErrors (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Ignore the unicode error, skipping the faulty input.
@end deffn

@geindex PyCodec_ReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_ReplaceErrors}@anchor{4892}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_ReplaceErrors (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Replace the unicode encode error with @code{?} or @code{U+FFFD}.
@end deffn

@geindex PyCodec_XMLCharRefReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_XMLCharRefReplaceErrors}@anchor{4896}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_XMLCharRefReplaceErrors (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Replace the unicode encode error with XML character references.
@end deffn

@geindex PyCodec_BackslashReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_BackslashReplaceErrors}@anchor{4888}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_BackslashReplaceErrors (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Replace the unicode encode error with backslash escapes (@code{\x}, @code{\u} and
@code{\U}).
@end deffn

@geindex PyCodec_NameReplaceErrors (C function)
@anchor{c-api/codec c PyCodec_NameReplaceErrors}@anchor{e98}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCodec_NameReplaceErrors (PyObject *exc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Replace the unicode encode error with @code{\N@{...@}} escapes.


Ajouté dans la version 3.5.

@end deffn

@node PyTime C API,Support for Perf Maps,Codec registry and support functions,Utilitaires<2>
@anchor{c-api/time doc}@anchor{159}@anchor{c-api/time c-api-time}@anchor{322}@anchor{c-api/time pytime-c-api}@anchor{4a38}
@subsection PyTime C API



Ajouté dans la version 3.13.


The clock C API provides access to system clocks.
It is similar to the Python @ref{ed,,time} module.

For C API related to the @ref{30,,datetime} module, see @ref{4a39,,Objets DateTime}.

@menu
* Types: Types<2>. 
* Clock Functions:: 
* Raw Clock Functions:: 
* Conversion functions:: 

@end menu

@node Types<2>,Clock Functions,,PyTime C API
@anchor{c-api/time types}@anchor{4a3a}
@subsubsection Types


@geindex PyTime_t (C type)
@anchor{c-api/time c PyTime_t}@anchor{323}
@deffn {C Type} type PyTime_t

A timestamp or duration in nanoseconds, represented as a signed 64-bit
integer.

The reference point for timestamps depends on the clock used. For example,
@ref{32b,,PyTime_Time()} returns timestamps relative to the UNIX epoch.

The supported range is around [-292.3 years; +292.3 years].
Using the Unix epoch (January 1st, 1970) as reference, the supported date
range is around [1677-09-21; 2262-04-11].
The exact limits are exposed as constants:
@end deffn

@geindex PyTime_MIN (C var)
@anchor{c-api/time c PyTime_MIN}@anchor{324}
@deffn {C Variable} @ref{323,,PyTime_t} PyTime_MIN

Minimum value of @ref{323,,PyTime_t}.
@end deffn

@geindex PyTime_MAX (C var)
@anchor{c-api/time c PyTime_MAX}@anchor{325}
@deffn {C Variable} @ref{323,,PyTime_t} PyTime_MAX

Maximum value of @ref{323,,PyTime_t}.
@end deffn

@node Clock Functions,Raw Clock Functions,Types<2>,PyTime C API
@anchor{c-api/time clock-functions}@anchor{4a3b}
@subsubsection Clock Functions


The following functions take a pointer to a @ref{323,,PyTime_t} that they
set to the value of a particular clock.
Details of each clock are given in the documentation of the corresponding
Python function.

The functions return @code{0} on success, or @code{-1} (with an exception set)
on failure.

On integer overflow, they set the @code{PyExc_OverflowError} exception and
set @code{*result} to the value clamped to the @code{[PyTime_MIN; PyTime_MAX]}
range.
(On current systems, integer overflows are likely caused by misconfigured
system time.)

As any other C API (unless otherwise specified), the functions must be called
with the @ref{158,,GIL} held.

@geindex PyTime_Monotonic (C function)
@anchor{c-api/time c PyTime_Monotonic}@anchor{327}
@deffn {C Fonction} int PyTime_Monotonic (PyTime_t *result)

Read the monotonic clock.
See @ref{250,,time.monotonic()} for important details on this clock.
@end deffn

@geindex PyTime_PerfCounter (C function)
@anchor{c-api/time c PyTime_PerfCounter}@anchor{329}
@deffn {C Fonction} int PyTime_PerfCounter (PyTime_t *result)

Read the performance counter.
See @ref{a76,,time.perf_counter()} for important details on this clock.
@end deffn

@geindex PyTime_Time (C function)
@anchor{c-api/time c PyTime_Time}@anchor{32b}
@deffn {C Fonction} int PyTime_Time (PyTime_t *result)

Read the “wall clock” time.
See @ref{251,,time.time()} for details important on this clock.
@end deffn

@node Raw Clock Functions,Conversion functions,Clock Functions,PyTime C API
@anchor{c-api/time raw-clock-functions}@anchor{4a3c}
@subsubsection Raw Clock Functions


Similar to clock functions, but don't set an exception on error and don't
require the caller to hold the GIL.

On success, the functions return @code{0}.

On failure, they set @code{*result} to @code{0} and return @code{-1}, `without' setting
an exception. To get the cause of the error, acquire the GIL and call the
regular (non-@code{Raw}) function. Note that the regular function may succeed after
the @code{Raw} one failed.

@geindex PyTime_MonotonicRaw (C function)
@anchor{c-api/time c PyTime_MonotonicRaw}@anchor{328}
@deffn {C Fonction} int PyTime_MonotonicRaw (PyTime_t *result)

Similar to @ref{327,,PyTime_Monotonic()},
but don't set an exception on error and don't require holding the GIL.
@end deffn

@geindex PyTime_PerfCounterRaw (C function)
@anchor{c-api/time c PyTime_PerfCounterRaw}@anchor{32a}
@deffn {C Fonction} int PyTime_PerfCounterRaw (PyTime_t *result)

Similar to @ref{329,,PyTime_PerfCounter()},
but don't set an exception on error and don't require holding the GIL.
@end deffn

@geindex PyTime_TimeRaw (C function)
@anchor{c-api/time c PyTime_TimeRaw}@anchor{32c}
@deffn {C Fonction} int PyTime_TimeRaw (PyTime_t *result)

Similar to @ref{32b,,PyTime_Time()},
but don't set an exception on error and don't require holding the GIL.
@end deffn

@node Conversion functions,,Raw Clock Functions,PyTime C API
@anchor{c-api/time conversion-functions}@anchor{4a3d}
@subsubsection Conversion functions


@geindex PyTime_AsSecondsDouble (C function)
@anchor{c-api/time c PyTime_AsSecondsDouble}@anchor{326}
@deffn {C Fonction} double PyTime_AsSecondsDouble (PyTime_t t)

Convert a timestamp to a number of seconds as a C double.

The function cannot fail, but note that double has limited
accuracy for large values.
@end deffn

@node Support for Perf Maps,,PyTime C API,Utilitaires<2>
@anchor{c-api/perfmaps doc}@anchor{4a3e}@anchor{c-api/perfmaps perfmaps}@anchor{4a3f}@anchor{c-api/perfmaps support-for-perf-maps}@anchor{4a40}
@subsection Support for Perf Maps


On supported platforms (as of this writing, only Linux), the runtime can take
advantage of `perf map files' to make Python functions visible to an external
profiling tool (such as perf@footnote{https://perf.wiki.kernel.org/index.php/Main_Page}).
A running process may create a file in the @code{/tmp} directory, which contains entries
that can map a section of executable code to a name. This interface is described in the
documentation of the Linux Perf tool@footnote{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt}.

In Python, these helper APIs can be used by libraries and features that rely
on generating machine code on the fly.

Note that holding the Global Interpreter Lock (GIL) is not required for these APIs.

@geindex PyUnstable_PerfMapState_Init (C function)
@anchor{c-api/perfmaps c PyUnstable_PerfMapState_Init}@anchor{16c5}
@deffn {C Fonction} int PyUnstable_PerfMapState_Init (void)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Open the @code{/tmp/perf-$pid.map} file, unless it's already opened, and create
a lock to ensure thread-safe writes to the file (provided the writes are
done through @ref{16c4,,PyUnstable_WritePerfMapEntry()}). Normally, there's no need
to call this explicitly; just use @ref{16c4,,PyUnstable_WritePerfMapEntry()}
and it will initialize the state on first call.

Returns @code{0} on success, @code{-1} on failure to create/open the perf map file,
or @code{-2} on failure to create a lock. Check @code{errno} for more information
about the cause of a failure.
@end deffn

@geindex PyUnstable_WritePerfMapEntry (C function)
@anchor{c-api/perfmaps c PyUnstable_WritePerfMapEntry}@anchor{16c4}
@deffn {C Fonction} int PyUnstable_WritePerfMapEntry (const void *code_addr, unsigned int code_size, const char *entry_name)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Write one single entry to the @code{/tmp/perf-$pid.map} file. This function is
thread safe. Here is what an example entry looks like:

@example
# address      size  name
7f3529fcf759 b     py::bar:/run/t.py
@end example

Will call @ref{16c5,,PyUnstable_PerfMapState_Init()} before writing the entry, if
the perf map file is not already opened. Returns @code{0} on success, or the
same error codes as @ref{16c5,,PyUnstable_PerfMapState_Init()} on failure.
@end deffn

@geindex PyUnstable_PerfMapState_Fini (C function)
@anchor{c-api/perfmaps c PyUnstable_PerfMapState_Fini}@anchor{16c6}
@deffn {C Fonction} void PyUnstable_PerfMapState_Fini (void)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Close the perf map file opened by @ref{16c5,,PyUnstable_PerfMapState_Init()}.
This is called by the runtime itself during interpreter shut-down. In
general, there shouldn't be a reason to explicitly call this, except to
handle specific scenarios such as forking.
@end deffn

@node Couche d'abstraction des objets,Couche des objets concrets,Utilitaires<2>,Manuel de référence de l'API Python/C
@anchor{c-api/abstract doc}@anchor{4a41}@anchor{c-api/abstract abstract}@anchor{4812}@anchor{c-api/abstract abstract-objects-layer}@anchor{4a42}
@section Couche d'abstraction des objets


Dans ce chapitre, les fonctions s'appliquent à des objets Python sans tenir compte de leur type, ou des classes d'objets au sens large (par exemple, tous les types numériques, ou tous les types de séquence). Quand ils sont utilisés sur des types d'objets qui ne correspondent pas, ils lèveront une exception Python.

Il n'est pas possible d'utiliser ces fonctions sur des objets qui n'ont pas été correctement initialisés, comme un objet liste qui a été créé avec @ref{484f,,PyList_New()} mais dont les éléments n'ont pas encore été mis à une valeur non-@code{NULL}.

@menu
* Protocole Objet:: 
* Call Protocol:: 
* Number Protocol:: 
* Sequence Protocol:: 
* Protocole de correspondance:: 
* Protocole d'itération:: 
* Protocole tampon:: 

@end menu

@node Protocole Objet,Call Protocol,,Couche d'abstraction des objets
@anchor{c-api/object doc}@anchor{4a43}@anchor{c-api/object object}@anchor{4a44}@anchor{c-api/object object-protocol}@anchor{4a45}
@subsection Protocole Objet


@geindex Py_GetConstant (C function)
@anchor{c-api/object c Py_GetConstant}@anchor{34c}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_GetConstant (unsigned int constant_id)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Get a @ref{333,,strong reference} to a constant.

Set an exception and return @code{NULL} if `constant_id' is invalid.

`constant_id' must be one of these constant identifiers:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Constant Identifier

@tab

Valeur

@tab

Returned object

@item

@geindex Py_CONSTANT_NONE (C macro)
@anchor{c-api/object c Py_CONSTANT_NONE}@anchor{4a46}
@deffn {C Macro} Py_CONSTANT_NONE
@end deffn

@tab

@code{0}

@tab

@ref{660,,None}

@item

@geindex Py_CONSTANT_FALSE (C macro)
@anchor{c-api/object c Py_CONSTANT_FALSE}@anchor{4a47}
@deffn {C Macro} Py_CONSTANT_FALSE
@end deffn

@tab

@code{1}

@tab

@ref{b25,,False}

@item

@geindex Py_CONSTANT_TRUE (C macro)
@anchor{c-api/object c Py_CONSTANT_TRUE}@anchor{4a48}
@deffn {C Macro} Py_CONSTANT_TRUE
@end deffn

@tab

@code{2}

@tab

@ref{bfb,,True}

@item

@geindex Py_CONSTANT_ELLIPSIS (C macro)
@anchor{c-api/object c Py_CONSTANT_ELLIPSIS}@anchor{4a49}
@deffn {C Macro} Py_CONSTANT_ELLIPSIS
@end deffn

@tab

@code{3}

@tab

@ref{210e,,Ellipsis}

@item

@geindex Py_CONSTANT_NOT_IMPLEMENTED (C macro)
@anchor{c-api/object c Py_CONSTANT_NOT_IMPLEMENTED}@anchor{4a4a}
@deffn {C Macro} Py_CONSTANT_NOT_IMPLEMENTED
@end deffn

@tab

@code{4}

@tab

@ref{7bc,,NotImplemented}

@item

@geindex Py_CONSTANT_ZERO (C macro)
@anchor{c-api/object c Py_CONSTANT_ZERO}@anchor{4a4b}
@deffn {C Macro} Py_CONSTANT_ZERO
@end deffn

@tab

@code{5}

@tab

@code{0}

@item

@geindex Py_CONSTANT_ONE (C macro)
@anchor{c-api/object c Py_CONSTANT_ONE}@anchor{4a4c}
@deffn {C Macro} Py_CONSTANT_ONE
@end deffn

@tab

@code{6}

@tab

@code{1}

@item

@geindex Py_CONSTANT_EMPTY_STR (C macro)
@anchor{c-api/object c Py_CONSTANT_EMPTY_STR}@anchor{4a4d}
@deffn {C Macro} Py_CONSTANT_EMPTY_STR
@end deffn

@tab

@code{7}

@tab

@code{'@w{'}}

@item

@geindex Py_CONSTANT_EMPTY_BYTES (C macro)
@anchor{c-api/object c Py_CONSTANT_EMPTY_BYTES}@anchor{4a4e}
@deffn {C Macro} Py_CONSTANT_EMPTY_BYTES
@end deffn

@tab

@code{8}

@tab

@code{b'@w{'}}

@item

@geindex Py_CONSTANT_EMPTY_TUPLE (C macro)
@anchor{c-api/object c Py_CONSTANT_EMPTY_TUPLE}@anchor{4a4f}
@deffn {C Macro} Py_CONSTANT_EMPTY_TUPLE
@end deffn

@tab

@code{9}

@tab

@code{()}

@end multitable


Numeric values are only given for projects which cannot use the constant
identifiers.


Ajouté dans la version 3.13.


`Particularité de l'implémentation CPython :' In CPython, all of these constants are @ref{42aa,,immortal}.
@end deffn

@geindex Py_GetConstantBorrowed (C function)
@anchor{c-api/object c Py_GetConstantBorrowed}@anchor{34d}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_GetConstantBorrowed (unsigned int constant_id)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Similar to @ref{34c,,Py_GetConstant()}, but return a @ref{334,,borrowed reference}.

This function is primarily intended for backwards compatibility:
using @ref{34c,,Py_GetConstant()} is recommended for new code.

The reference is borrowed from the interpreter, and is valid until the
interpreter finalization.


Ajouté dans la version 3.13.

@end deffn

@geindex Py_NotImplemented (C var)
@anchor{c-api/object c Py_NotImplemented}@anchor{4a50}
@deffn {C Variable} @ref{32f,,PyObject} *Py_NotImplemented

Le singleton @code{NotImplemented}, utilisé pour signaler qu'une opération n'est pas implémentée pour la combinaison de types en question.
@end deffn

@geindex Py_RETURN_NOTIMPLEMENTED (C macro)
@anchor{c-api/object c Py_RETURN_NOTIMPLEMENTED}@anchor{4a51}
@deffn {C Macro} Py_RETURN_NOTIMPLEMENTED

Properly handle returning @ref{4a50,,Py_NotImplemented} from within a C
function (that is, create a new @ref{333,,strong reference}
to @ref{7bc,,NotImplemented} and return it).
@end deffn

@geindex Py_PRINT_RAW (C macro)
@anchor{c-api/object c Py_PRINT_RAW}@anchor{4a52}
@deffn {C Macro} Py_PRINT_RAW

Flag to be used with multiple functions that print the object (like
@ref{1579,,PyObject_Print()} and @ref{48c3,,PyFile_WriteObject()}).
If passed, these function would use the @ref{435,,str()} of the object
instead of the @ref{7e7,,repr()}.
@end deffn

@geindex PyObject_Print (C function)
@anchor{c-api/object c PyObject_Print}@anchor{1579}
@deffn {C Fonction} int PyObject_Print (PyObject *o, FILE *fp, int flags)

Print an object `o', on file `fp'.  Returns @code{-1} on error.  The flags argument
is used to enable certain printing options.  The only option currently supported
is @ref{4a52,,Py_PRINT_RAW}; if given, the @ref{435,,str()} of the object is written
instead of the @ref{7e7,,repr()}.
@end deffn

@geindex PyObject_HasAttrWithError (C function)
@anchor{c-api/object c PyObject_HasAttrWithError}@anchor{370}
@deffn {C Fonction} int PyObject_HasAttrWithError (PyObject *o, PyObject *attr_name)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Returns @code{1} if `o' has the attribute `attr_name', and @code{0} otherwise.
This is equivalent to the Python expression @code{hasattr(o, attr_name)}.
On failure, return @code{-1}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyObject_HasAttrStringWithError (C function)
@anchor{c-api/object c PyObject_HasAttrStringWithError}@anchor{372}
@deffn {C Fonction} int PyObject_HasAttrStringWithError (PyObject *o, const char *attr_name)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
This is the same as @ref{370,,PyObject_HasAttrWithError()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyObject_HasAttr (C function)
@anchor{c-api/object c PyObject_HasAttr}@anchor{371}
@deffn {C Fonction} int PyObject_HasAttr (PyObject *o, PyObject *attr_name)
` Part of the @ref{53e,,Stable ABI}.'
Returns @code{1} if `o' has the attribute `attr_name', and @code{0} otherwise.
This function always succeeds.

@cartouche
@quotation Note 
Exceptions that occur when this calls @ref{4bc,,__getattr__()} and
@ref{bc0,,__getattribute__()} methods aren't propagated,
but instead given to @ref{1f4,,sys.unraisablehook()}.
For proper error handling, use @ref{370,,PyObject_HasAttrWithError()},
@ref{33f,,PyObject_GetOptionalAttr()} or @ref{341,,PyObject_GetAttr()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_HasAttrString (C function)
@anchor{c-api/object c PyObject_HasAttrString}@anchor{373}
@deffn {C Fonction} int PyObject_HasAttrString (PyObject *o, const char *attr_name)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{371,,PyObject_HasAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.

@cartouche
@quotation Note 
Exceptions that occur when this calls @ref{4bc,,__getattr__()} and
@ref{bc0,,__getattribute__()} methods or while creating the temporary
@ref{435,,str} object are silently ignored.
For proper error handling, use @ref{372,,PyObject_HasAttrStringWithError()},
@ref{340,,PyObject_GetOptionalAttrString()}
or @ref{342,,PyObject_GetAttrString()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyObject_GetAttr (C function)
@anchor{c-api/object c PyObject_GetAttr}@anchor{341}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GetAttr (PyObject *o, PyObject *attr_name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Retrieve an attribute named `attr_name' from object `o'. Returns the attribute
value on success, or @code{NULL} on failure.  This is the equivalent of the Python
expression @code{o.attr_name}.

If the missing attribute should not be treated as a failure, you can use
@ref{33f,,PyObject_GetOptionalAttr()} instead.
@end deffn

@geindex PyObject_GetAttrString (C function)
@anchor{c-api/object c PyObject_GetAttrString}@anchor{342}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GetAttrString (PyObject *o, const char *attr_name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{341,,PyObject_GetAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.

If the missing attribute should not be treated as a failure, you can use
@ref{340,,PyObject_GetOptionalAttrString()} instead.
@end deffn

@geindex PyObject_GetOptionalAttr (C function)
@anchor{c-api/object c PyObject_GetOptionalAttr}@anchor{33f}
@deffn {C Fonction} int PyObject_GetOptionalAttr (PyObject *obj, PyObject *attr_name, PyObject **result);
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Variant of @ref{341,,PyObject_GetAttr()} which doesn't raise
@ref{343,,AttributeError} if the attribute is not found.

If the attribute is found, return @code{1} and set `*result' to a new
@ref{333,,strong reference} to the attribute.
If the attribute is not found, return @code{0} and set `*result' to @code{NULL};
the @ref{343,,AttributeError} is silenced.
If an error other than @ref{343,,AttributeError} is raised, return @code{-1} and
set `*result' to @code{NULL}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyObject_GetOptionalAttrString (C function)
@anchor{c-api/object c PyObject_GetOptionalAttrString}@anchor{340}
@deffn {C Fonction} int PyObject_GetOptionalAttrString (PyObject *obj, const char *attr_name, PyObject **result);
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
This is the same as @ref{33f,,PyObject_GetOptionalAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyObject_GenericGetAttr (C function)
@anchor{c-api/object c PyObject_GenericGetAttr}@anchor{4925}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GenericGetAttr (PyObject *o, PyObject *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Accesseur d'attribut générique destiné à être mis dans le `slot' @code{tp_getattro} d'un objet type. Recherche un descripteur dans le dictionnaire de classes du MRO de l'objet ainsi qu'un attribut dans le @ref{546,,__dict__}  de l'objet (si présent). Comme défini dans @ref{c3d,,Implémentation de descripteurs}, les descripteurs de données sont prioritaires sur les attributs d'instance, contrairement aux autres descripteurs. Sinon, une @ref{343,,AttributeError} est levée.
@end deffn

@geindex PyObject_SetAttr (C function)
@anchor{c-api/object c PyObject_SetAttr}@anchor{492e}
@deffn {C Fonction} int PyObject_SetAttr (PyObject *o, PyObject *attr_name, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
Définit la valeur de l'attribut nommé `attr_name', pour l'objet `o', à la valeur `v'. Lève une exception et renvoie @code{-1} en cas d'échec ; renvoie @code{0} en cas de succès. Ceci est équivalent à l'instruction Python @code{o.attr_name = v}.

If `v' is @code{NULL}, the attribute is deleted. This behaviour is deprecated
in favour of using @ref{16a7,,PyObject_DelAttr()}, but there are currently no
plans to remove it.
@end deffn

@geindex PyObject_SetAttrString (C function)
@anchor{c-api/object c PyObject_SetAttrString}@anchor{1589}
@deffn {C Fonction} int PyObject_SetAttrString (PyObject *o, const char *attr_name, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{492e,,PyObject_SetAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.

If `v' is @code{NULL}, the attribute is deleted, but this feature is
deprecated in favour of using @ref{158a,,PyObject_DelAttrString()}.

The number of different attribute names passed to this function
should be kept small, usually by using a statically allocated string
as `attr_name'.
For attribute names that aren't known at compile time, prefer calling
@ref{4832,,PyUnicode_FromString()} and @ref{492e,,PyObject_SetAttr()} directly.
For more details, see @ref{1587,,PyUnicode_InternFromString()}, which may be
used internally to create a key object.
@end deffn

@geindex PyObject_GenericSetAttr (C function)
@anchor{c-api/object c PyObject_GenericSetAttr}@anchor{4926}
@deffn {C Fonction} int PyObject_GenericSetAttr (PyObject *o, PyObject *name, PyObject *value)
` Part of the @ref{53e,,Stable ABI}.'
Accesseur et suppresseur générique d'attributs qui est fait pour être mis dans le @ref{4807,,tp_setattro} d'un objet type. Il cherche un descripteur de données dans le dictionnaire de classes dans le MRO de l'objet et, si ce descripteur est trouvé, c'est lui qui est utilisé de préférence pour la suppression et la définition de l'attribut dans le dictionnaire d'instance. Sinon, l'attribut est défini ou supprimé dans le  @ref{546,,__dict__} de l'objet (si présent). En cas de succès, @code{0} est renvoyé, sinon une @ref{343,,AttributeError} est levée et @code{-1} est renvoyé.
@end deffn

@geindex PyObject_DelAttr (C function)
@anchor{c-api/object c PyObject_DelAttr}@anchor{16a7}
@deffn {C Fonction} int PyObject_DelAttr (PyObject *o, PyObject *attr_name)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Supprime l'attribut nommé `attr_name', pour l'objet `o'. Renvoie @code{-1} en cas d'échec. Ceci est l'équivalent de l'expression Python @code{del o.attr_name}.
@end deffn

@geindex PyObject_DelAttrString (C function)
@anchor{c-api/object c PyObject_DelAttrString}@anchor{158a}
@deffn {C Fonction} int PyObject_DelAttrString (PyObject *o, const char *attr_name)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
This is the same as @ref{16a7,,PyObject_DelAttr()}, but `attr_name' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.

The number of different attribute names passed to this function
should be kept small, usually by using a statically allocated string
as `attr_name'.
For attribute names that aren't known at compile time, prefer calling
@ref{4832,,PyUnicode_FromString()} and @ref{16a7,,PyObject_DelAttr()} directly.
For more details, see @ref{1587,,PyUnicode_InternFromString()}, which may be
used internally to create a key object for lookup.
@end deffn

@geindex PyObject_GenericGetDict (C function)
@anchor{c-api/object c PyObject_GenericGetDict}@anchor{18c7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GenericGetDict (PyObject *o, void *context)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Une implémentation générique de l'accesseur d'un descripteur d'un  @code{__dict__}. Crée le dictionnaire si nécessaire.

This function may also be called to get the @ref{546,,__dict__}
of the object `o'. Pass @code{NULL} for `context' when calling it.
Since this function may need to allocate memory for the
dictionary, it may be more efficient to call @ref{341,,PyObject_GetAttr()}
when accessing an attribute on the object.

On failure, returns @code{NULL} with an exception set.


Ajouté dans la version 3.3.

@end deffn

@geindex PyObject_GenericSetDict (C function)
@anchor{c-api/object c PyObject_GenericSetDict}@anchor{4927}
@deffn {C Fonction} int PyObject_GenericSetDict (PyObject *o, PyObject *value, void *context)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Une implémentation générique du mutateur d'un descripteur de  @code{__dict__}. Cette implémentation n'autorise pas la suppression du dictionnaire.


Ajouté dans la version 3.3.

@end deffn

@geindex _PyObject_GetDictPtr (C function)
@anchor{c-api/object c _PyObject_GetDictPtr}@anchor{4a53}
@deffn {C Fonction} @ref{32f,,PyObject} **_PyObject_GetDictPtr (PyObject *obj)

Return a pointer to @ref{546,,__dict__} of the object `obj'.
If there is no @code{__dict__}, return @code{NULL} without setting an exception.

This function may need to allocate memory for the
dictionary, so it may be more efficient to call @ref{341,,PyObject_GetAttr()}
when accessing an attribute on the object.
@end deffn

@geindex PyObject_RichCompare (C function)
@anchor{c-api/object c PyObject_RichCompare}@anchor{4810}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_RichCompare (PyObject *o1, PyObject *o2, int opid)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Compare the values of `o1' and `o2' using the operation specified by `opid',
which must be one of @ref{4a54,,Py_LT}, @ref{4a55,,Py_LE}, @ref{4a56,,Py_EQ},
@ref{4a57,,Py_NE}, @ref{4a58,,Py_GT}, or @ref{4a59,,Py_GE}, corresponding to @code{<},
@code{<=}, @code{==}, @code{!=}, @code{>}, or @code{>=} respectively. This is the equivalent of
the Python expression @code{o1 op o2}, where @code{op} is the operator corresponding
to `opid'. Returns the value of the comparison on success, or @code{NULL} on failure.
@end deffn

@geindex PyObject_RichCompareBool (C function)
@anchor{c-api/object c PyObject_RichCompareBool}@anchor{1931}
@deffn {C Fonction} int PyObject_RichCompareBool (PyObject *o1, PyObject *o2, int opid)
` Part of the @ref{53e,,Stable ABI}.'
Compare the values of `o1' and `o2' using the operation specified by `opid',
like @ref{4810,,PyObject_RichCompare()}, but returns @code{-1} on error, @code{0} if
the result is false, @code{1} otherwise.
@end deffn

@cartouche
@quotation Note 
If `o1' and `o2' are the same object, @ref{1931,,PyObject_RichCompareBool()}
will always return @code{1} for @ref{4a56,,Py_EQ} and @code{0} for @ref{4a57,,Py_NE}.
@end quotation
@end cartouche

@geindex PyObject_Format (C function)
@anchor{c-api/object c PyObject_Format}@anchor{4924}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Format (PyObject *obj, PyObject *format_spec)
` Part of the @ref{53e,,Stable ABI}.'
Format `obj' using `format_spec'. This is equivalent to the Python
expression @code{format(obj, format_spec)}.

`format_spec' may be @code{NULL}. In this case the call is equivalent
to @code{format(obj)}.
Returns the formatted string on success, @code{NULL} on failure.
@end deffn

@geindex PyObject_Repr (C function)
@anchor{c-api/object c PyObject_Repr}@anchor{1018}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Repr (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;repr

Compute a string representation of object `o'.  Returns the string
representation on success, @code{NULL} on failure.  This is the equivalent of the
Python expression @code{repr(o)}.  Called by the @ref{7e7,,repr()} built-in function.


Modifié dans la version 3.4: Cette fonction inclut maintenant une assertion de débogage afin d'assurer qu'elle ne passe pas sous silence une exception active.

@end deffn

@geindex PyObject_ASCII (C function)
@anchor{c-api/object c PyObject_ASCII}@anchor{491d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_ASCII (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;ascii

Comme @ref{1018,,PyObject_Repr()}, calcule une représentation en chaîne de caractères de l'objet `o', mais échappe les caractères non ASCII dans la chaîne de caractères renvoyée par @ref{1018,,PyObject_Repr()} avec' @code{\x}, @code{\u} ou @code{\U}. Cela génère une chaîne de caractères similaire à celle renvoyée par @ref{1018,,PyObject_Repr()} en Python 2. Appelée par la fonction native @ref{139d,,ascii()}.

@geindex string;PyObject_Str (C function)
@end deffn

@geindex PyObject_Str (C function)
@anchor{c-api/object c PyObject_Str}@anchor{1019}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Str (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Compute a string representation of object `o'.  Returns the string
representation on success, @code{NULL} on failure.  This is the equivalent of the
Python expression @code{str(o)}.  Called by the @ref{435,,str()} built-in function
and, therefore, by the @ref{f60,,print()} function.


Modifié dans la version 3.4: Cette fonction inclut maintenant une assertion de débogage afin d'assurer qu'elle ne passe pas sous silence une exception active.

@end deffn

@geindex PyObject_Bytes (C function)
@anchor{c-api/object c PyObject_Bytes}@anchor{491f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Bytes (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;bytes

Compute a bytes representation of object `o'.  @code{NULL} is returned on
failure and a bytes object on success.  This is equivalent to the Python
expression @code{bytes(o)}, when `o' is not an integer.  Unlike @code{bytes(o)},
a TypeError is raised when `o' is an integer instead of a zero-initialized
bytes object.
@end deffn

@geindex PyObject_IsSubclass (C function)
@anchor{c-api/object c PyObject_IsSubclass}@anchor{e90}
@deffn {C Fonction} int PyObject_IsSubclass (PyObject *derived, PyObject *cls)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie @code{1} si la classe `derived' est identique à ou dérivée de la classe `cls', renvoie @code{0} sinon. En cas d'erreur, renvoie @code{-1}.

Si `cls' est un `n'-uplet, la vérification est menée sur chaque entrée de `cls'. Le résultat sera @code{1} quand au moins une des vérifications renvoie @code{1}, sinon ce sera @code{0}.

If `cls' has a @ref{1f00,,__subclasscheck__()} method, it will be called to
determine the subclass status as described in 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/}.  Otherwise,
`derived' is a subclass of `cls' if it is a direct or indirect subclass,
i.e. contained in @ref{1eae,,cls.__mro__}.

Normally only class objects, i.e. instances of @ref{d36,,type} or a derived
class, are considered classes.  However, objects can override this by having
a @ref{1460,,__bases__} attribute (which must be a tuple of base classes).
@end deffn

@geindex PyObject_IsInstance (C function)
@anchor{c-api/object c PyObject_IsInstance}@anchor{e8f}
@deffn {C Fonction} int PyObject_IsInstance (PyObject *inst, PyObject *cls)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie @code{1} si `inst' est une instance de la classe `cls' ou une sous-classe de `cls', ou @code{0} sinon. En cas d'erreur, renvoie @code{-1} et initialise une exception.

Si `cls' est un `n'-uplet, la vérification est menée sur chaque entrée de `cls'. Le résultat sera @code{1} quand au moins une des vérifications renvoie @code{1}, sinon ce sera @code{0}.

If `cls' has a @ref{1eff,,__instancecheck__()} method, it will be called to
determine the subclass status as described in 
@geindex Python Enhancement Proposals; PEP 3119
PEP 3119@footnote{https://peps.python.org/pep-3119/}.  Otherwise, `inst'
is an instance of `cls' if its class is a subclass of `cls'.

An instance `inst' can override what is considered its class by having a
@ref{1461,,__class__} attribute.

An object `cls' can override if it is considered a class, and what its base
classes are, by having a @ref{1460,,__bases__} attribute (which must be a tuple
of base classes).
@end deffn

@geindex PyObject_Hash (C function)
@anchor{c-api/object c PyObject_Hash}@anchor{3f9}
@deffn {C Fonction} @ref{1242,,Py_hash_t} PyObject_Hash (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;hash

Compute and return the hash value of an object `o'.  On failure, return @code{-1}.
This is the equivalent of the Python expression @code{hash(o)}.


Modifié dans la version 3.2: The return type is now Py_hash_t.  This is a signed integer the same size
as @ref{a4e,,Py_ssize_t}.

@end deffn

@geindex PyObject_HashNotImplemented (C function)
@anchor{c-api/object c PyObject_HashNotImplemented}@anchor{137d}
@deffn {C Fonction} @ref{1242,,Py_hash_t} PyObject_HashNotImplemented (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Set a @ref{522,,TypeError} indicating that @code{type(o)} is not @ref{5fb,,hashable} and return @code{-1}.
This function receives special treatment when stored in a @code{tp_hash} slot,
allowing a type to explicitly indicate to the interpreter that it is not
hashable.
@end deffn

@geindex PyObject_IsTrue (C function)
@anchor{c-api/object c PyObject_IsTrue}@anchor{492a}
@deffn {C Fonction} int PyObject_IsTrue (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Returns @code{1} if the object `o' is considered to be true, and @code{0} otherwise.
This is equivalent to the Python expression @code{not not o}.  On failure, return
@code{-1}.
@end deffn

@geindex PyObject_Not (C function)
@anchor{c-api/object c PyObject_Not}@anchor{492c}
@deffn {C Fonction} int PyObject_Not (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Returns @code{0} if the object `o' is considered to be true, and @code{1} otherwise.
This is equivalent to the Python expression @code{not o}.  On failure, return
@code{-1}.
@end deffn

@geindex PyObject_Type (C function)
@anchor{c-api/object c PyObject_Type}@anchor{4930}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Type (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;type

When `o' is non-@code{NULL}, returns a type object corresponding to the object type
of object `o'. On failure, raises @ref{561,,SystemError} and returns @code{NULL}.  This
is equivalent to the Python expression @code{type(o)}.
This function creates a new @ref{333,,strong reference} to the return value.
There's really no reason to use this
function instead of the @ref{76a,,Py_TYPE()} function, which returns a
pointer of type @ref{a93,,PyTypeObject}*, except when a new
@ref{333,,strong reference} is needed.
@end deffn

@geindex PyObject_TypeCheck (C function)
@anchor{c-api/object c PyObject_TypeCheck}@anchor{1885}
@deffn {C Fonction} int PyObject_TypeCheck (PyObject *o, PyTypeObject *type)

Return non-zero if the object `o' is of type `type' or a subtype of `type', and
@code{0} otherwise.  Both parameters must be non-@code{NULL}.
@end deffn

@geindex PyObject_Size (C function)
@geindex PyObject_Length (C function)
@anchor{c-api/object c PyObject_Size}@anchor{492f}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyObject_Size (PyObject *o)
@anchor{c-api/object c PyObject_Length}@anchor{492b}
@deffnx {C Fonction} @ref{a4e,,Py_ssize_t} PyObject_Length (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;len

Return the length of object `o'.  If the object `o' provides either the sequence
and mapping protocols, the sequence length is returned.  On error, @code{-1} is
returned.  This is the equivalent to the Python expression @code{len(o)}.
@end deffn

@geindex PyObject_LengthHint (C function)
@anchor{c-api/object c PyObject_LengthHint}@anchor{fed}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyObject_LengthHint (PyObject *o, Py_ssize_t defaultvalue)

Return an estimated length for the object `o'. First try to return its
actual length, then an estimate using @ref{ef6,,__length_hint__()}, and
finally return the default value. On error return @code{-1}. This is the
equivalent to the Python expression @code{operator.length_hint(o, defaultvalue)}.


Ajouté dans la version 3.4.

@end deffn

@geindex PyObject_GetItem (C function)
@anchor{c-api/object c PyObject_GetItem}@anchor{33d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GetItem (PyObject *o, PyObject *key)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return element of `o' corresponding to the object `key' or @code{NULL} on failure.
This is the equivalent of the Python expression @code{o[key]}.
@end deffn

@geindex PyObject_SetItem (C function)
@anchor{c-api/object c PyObject_SetItem}@anchor{484e}
@deffn {C Fonction} int PyObject_SetItem (PyObject *o, PyObject *key, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
Map the object `key' to the value `v'.  Raise an exception and
return @code{-1} on failure; return @code{0} on success.  This is the
equivalent of the Python statement @code{o[key] = v}.  This function `does
not' steal a reference to `v'.
@end deffn

@geindex PyObject_DelItem (C function)
@anchor{c-api/object c PyObject_DelItem}@anchor{4921}
@deffn {C Fonction} int PyObject_DelItem (PyObject *o, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Remove the mapping for the object `key' from the object `o'.  Return @code{-1}
on failure.  This is equivalent to the Python statement @code{del o[key]}.
@end deffn

@geindex PyObject_DelItemString (C function)
@anchor{c-api/object c PyObject_DelItemString}@anchor{4922}
@deffn {C Fonction} int PyObject_DelItemString (PyObject *o, const char *key)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{4921,,PyObject_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
@end deffn

@geindex PyObject_Dir (C function)
@anchor{c-api/object c PyObject_Dir}@anchor{4923}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Dir (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is equivalent to the Python expression @code{dir(o)}, returning a (possibly
empty) list of strings appropriate for the object argument, or @code{NULL} if there
was an error.  If the argument is @code{NULL}, this is like the Python @code{dir()},
returning the names of the current locals; in this case, if no execution frame
is active then @code{NULL} is returned but @ref{187f,,PyErr_Occurred()} will return false.
@end deffn

@geindex PyObject_GetIter (C function)
@anchor{c-api/object c PyObject_GetIter}@anchor{4929}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GetIter (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is equivalent to the Python expression @code{iter(o)}. It returns a new
iterator for the object argument, or the object  itself if the object is already
an iterator.  Raises @ref{522,,TypeError} and returns @code{NULL} if the object cannot be
iterated.
@end deffn

@geindex PyObject_SelfIter (C function)
@anchor{c-api/object c PyObject_SelfIter}@anchor{492d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_SelfIter (PyObject *obj)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is equivalent to the Python @code{__iter__(self): return self} method.
It is intended for @ref{1aa,,iterator} types, to be used in the @ref{14a4,,PyTypeObject.tp_iter} slot.
@end deffn

@geindex PyObject_GetAIter (C function)
@anchor{c-api/object c PyObject_GetAIter}@anchor{4928}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_GetAIter (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
This is the equivalent to the Python expression @code{aiter(o)}. Takes an
@code{AsyncIterable} object and returns an @code{AsyncIterator} for it.
This is typically a new iterator but if the argument is an
@code{AsyncIterator}, this returns itself. Raises @ref{522,,TypeError} and
returns @code{NULL} if the object cannot be iterated.


Ajouté dans la version 3.10.

@end deffn

@geindex PyObject_GetTypeData (C function)
@anchor{c-api/object c PyObject_GetTypeData}@anchor{534}
@deffn {C Fonction} void *PyObject_GetTypeData (PyObject *o, PyTypeObject *cls)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Get a pointer to subclass-specific data reserved for `cls'.

The object `o' must be an instance of `cls', and `cls' must have been
created using negative @ref{533,,PyType_Spec.basicsize}.
Python does not check this.

On error, set an exception and return @code{NULL}.


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_GetTypeDataSize (C function)
@anchor{c-api/object c PyType_GetTypeDataSize}@anchor{535}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyType_GetTypeDataSize (PyTypeObject *cls)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Return the size of the instance memory space reserved for `cls', i.e. the size of the
memory @ref{534,,PyObject_GetTypeData()} returns.

This may be larger than requested using @ref{533,,-PyType_Spec.basicsize};
it is safe to use this larger size (e.g. with @code{memset()}).

The type `cls' `must' have been created using
negative @ref{533,,PyType_Spec.basicsize}.
Python does not check this.

On error, set an exception and return a negative value.


Ajouté dans la version 3.12.

@end deffn

@geindex PyObject_GetItemData (C function)
@anchor{c-api/object c PyObject_GetItemData}@anchor{537}
@deffn {C Fonction} void *PyObject_GetItemData (PyObject *o)

Get a pointer to per-item data for a class with
@ref{536,,Py_TPFLAGS_ITEMS_AT_END}.

On error, set an exception and return @code{NULL}.
@ref{522,,TypeError} is raised if `o' does not have
@ref{536,,Py_TPFLAGS_ITEMS_AT_END} set.


Ajouté dans la version 3.12.

@end deffn

@geindex PyObject_VisitManagedDict (C function)
@anchor{c-api/object c PyObject_VisitManagedDict}@anchor{35f}
@deffn {C Fonction} int PyObject_VisitManagedDict (PyObject *obj, visitproc visit, void *arg)

Visit the managed dictionary of `obj'.

This function must only be called in a traverse function of the type which
has the @ref{361,,Py_TPFLAGS_MANAGED_DICT} flag set.


Ajouté dans la version 3.13.

@end deffn

@geindex PyObject_ClearManagedDict (C function)
@anchor{c-api/object c PyObject_ClearManagedDict}@anchor{360}
@deffn {C Fonction} void PyObject_ClearManagedDict (PyObject *obj)

Clear the managed dictionary of `obj'.

This function must only be called in a traverse function of the type which
has the @ref{361,,Py_TPFLAGS_MANAGED_DICT} flag set.


Ajouté dans la version 3.13.

@end deffn

@node Call Protocol,Number Protocol,Protocole Objet,Couche d'abstraction des objets
@anchor{c-api/call doc}@anchor{4a5a}@anchor{c-api/call call}@anchor{56f}@anchor{c-api/call call-protocol}@anchor{4a5b}
@subsection Call Protocol


CPython supports two different calling protocols:
`tp_call' and vectorcall.

@menu
* The tp_call Protocol:: 
* The Vectorcall Protocol:: 
* Object Calling API:: 
* Call Support API:: 

@end menu

@node The tp_call Protocol,The Vectorcall Protocol,,Call Protocol
@anchor{c-api/call the-tp-call-protocol}@anchor{4a5c}
@subsubsection The `tp_call' Protocol


Instances of classes that set @ref{544,,tp_call} are callable.
The signature of the slot is:

@example
PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);
@end example

A call is made using a tuple for the positional arguments
and a dict for the keyword arguments, similarly to
@code{callable(*args, **kwargs)} in Python code.
`args' must be non-NULL (use an empty tuple if there are no arguments)
but `kwargs' may be `NULL' if there are no keyword arguments.

This convention is not only used by `tp_call':
@ref{56b,,tp_new} and @ref{56d,,tp_init}
also pass arguments this way.

To call an object, use @ref{393,,PyObject_Call()} or another
@ref{4a5d,,call API}.

@node The Vectorcall Protocol,Object Calling API,The tp_call Protocol,Call Protocol
@anchor{c-api/call the-vectorcall-protocol}@anchor{4a5e}@anchor{c-api/call vectorcall}@anchor{53d}
@subsubsection The Vectorcall Protocol



Ajouté dans la version 3.9.


The vectorcall protocol was introduced in 
@geindex Python Enhancement Proposals; PEP 590
PEP 590@footnote{https://peps.python.org/pep-0590/} as an additional protocol
for making calls more efficient.

As rule of thumb, CPython will prefer the vectorcall for internal calls
if the callable supports it. However, this is not a hard rule.
Additionally, some third-party extensions use `tp_call' directly
(rather than using @ref{393,,PyObject_Call()}).
Therefore, a class supporting vectorcall must also implement
@ref{544,,tp_call}.
Moreover, the callable must behave the same
regardless of which protocol is used.
The recommended way to achieve this is by setting
@ref{544,,tp_call} to @ref{541,,PyVectorcall_Call()}.
This bears repeating:

@cartouche
@quotation Avertissement 
A class supporting vectorcall `must' also implement
@ref{544,,tp_call} with the same semantics.
@end quotation
@end cartouche


Modifié dans la version 3.12: The @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is now removed from a class
when the class's @ref{543,,__call__()} method is reassigned.
(This internally sets @ref{544,,tp_call} only, and thus
may make it behave differently than the vectorcall function.)
In earlier Python versions, vectorcall should only be used with
@ref{3b9,,immutable} or static types.


A class should not implement vectorcall if that would be slower
than `tp_call'. For example, if the callee needs to convert
the arguments to an args tuple and kwargs dict anyway, then there is no point
in implementing vectorcall.

Classes can implement the vectorcall protocol by enabling the
@ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag and setting
@ref{4a5f,,tp_vectorcall_offset} to the offset inside the
object structure where a `vectorcallfunc' appears.
This is a pointer to a function with the following signature:

@geindex vectorcallfunc (C type)
@anchor{c-api/call c vectorcallfunc}@anchor{542}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*vectorcallfunc)(@ref{32f,,PyObject} *callable, @ref{32f,,PyObject} *const *args, size_t nargsf, @ref{32f,,PyObject} *kwnames)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
@end deffn


@itemize -

@item 
`callable' is the object being called.

@item 

@table @asis

@item `args' is a C array consisting of the positional arguments followed by the

values of the keyword arguments.
This can be `NULL' if there are no arguments.
@end table

@item 

@table @asis

@item `nargsf' is the number of positional arguments plus possibly the

@ref{549,,PY_VECTORCALL_ARGUMENTS_OFFSET} flag.
To get the actual number of positional arguments from `nargsf',
use @ref{540,,PyVectorcall_NARGS()}.
@end table

@item 

@table @asis

@item `kwnames' is a tuple containing the names of the keyword arguments;

in other words, the keys of the kwargs dict.
These names must be strings (instances of @code{str} or a subclass)
and they must be unique.
If there are no keyword arguments, then `kwnames' can instead be `NULL'.
@end table
@end itemize

@geindex PY_VECTORCALL_ARGUMENTS_OFFSET (C macro)
@anchor{c-api/call c PY_VECTORCALL_ARGUMENTS_OFFSET}@anchor{549}
@deffn {C Macro} PY_VECTORCALL_ARGUMENTS_OFFSET
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
If this flag is set in a vectorcall `nargsf' argument, the callee is allowed
to temporarily change @code{args[-1]}. In other words, `args' points to
argument 1 (not 0) in the allocated vector.
The callee must restore the value of @code{args[-1]} before returning.

For @ref{548,,PyObject_VectorcallMethod()}, this flag means instead that
@code{args[0]} may be changed.

Whenever they can do so cheaply (without additional allocation), callers
are encouraged to use @ref{549,,PY_VECTORCALL_ARGUMENTS_OFFSET}.
Doing so will allow callables such as bound methods to make their onward
calls (which include a prepended `self' argument) very efficiently.


Ajouté dans la version 3.8.

@end deffn

To call an object that implements vectorcall, use a @ref{4a5d,,call API}
function as with any other callable.
@ref{547,,PyObject_Vectorcall()} will usually be most efficient.

@menu
* Contrôle de la récursion: Contrôle de la récursion<2>. 
* Vectorcall Support API:: 

@end menu

@node Contrôle de la récursion<2>,Vectorcall Support API,,The Vectorcall Protocol
@anchor{c-api/call recursion-control}@anchor{4a60}
@subsubsection Contrôle de la récursion


When using `tp_call', callees do not need to worry about
@ref{49f9,,recursion}: CPython uses
@ref{960,,Py_EnterRecursiveCall()} and @ref{961,,Py_LeaveRecursiveCall()}
for calls made using `tp_call'.

For efficiency, this is not the case for calls done using vectorcall:
the callee should use `Py_EnterRecursiveCall' and `Py_LeaveRecursiveCall'
if needed.

@node Vectorcall Support API,,Contrôle de la récursion<2>,The Vectorcall Protocol
@anchor{c-api/call vectorcall-support-api}@anchor{4a61}
@subsubsection Vectorcall Support API


@geindex PyVectorcall_NARGS (C function)
@anchor{c-api/call c PyVectorcall_NARGS}@anchor{540}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyVectorcall_NARGS (size_t nargsf)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Given a vectorcall `nargsf' argument, return the actual number of
arguments.
Currently equivalent to:

@example
(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)
@end example

However, the function @code{PyVectorcall_NARGS} should be used to allow
for future extensions.


Ajouté dans la version 3.8.

@end deffn

@geindex PyVectorcall_Function (C function)
@anchor{c-api/call c PyVectorcall_Function}@anchor{4a62}
@deffn {C Fonction} @ref{542,,vectorcallfunc} PyVectorcall_Function (PyObject *op)

If `op' does not support the vectorcall protocol (either because the type
does not or because the specific instance does not), return `NULL'.
Otherwise, return the vectorcall function pointer stored in `op'.
This function never raises an exception.

This is mostly useful to check whether or not `op' supports vectorcall,
which can be done by checking @code{PyVectorcall_Function(op) != NULL}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyVectorcall_Call (C function)
@anchor{c-api/call c PyVectorcall_Call}@anchor{541}
@deffn {C Fonction} @ref{32f,,PyObject} *PyVectorcall_Call (PyObject *callable, PyObject *tuple, PyObject *dict)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Call `callable''s @ref{542,,vectorcallfunc} with positional and keyword
arguments given in a tuple and dict, respectively.

This is a specialized function, intended to be put in the
@ref{544,,tp_call} slot or be used in an implementation of @code{tp_call}.
It does not check the @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag
and it does not fall back to @code{tp_call}.


Ajouté dans la version 3.8.

@end deffn

@node Object Calling API,Call Support API,The Vectorcall Protocol,Call Protocol
@anchor{c-api/call capi-call}@anchor{4a5d}@anchor{c-api/call object-calling-api}@anchor{4a63}
@subsubsection Object Calling API


Various functions are available for calling a Python object.
Each converts its arguments to a convention supported by the called object –
either `tp_call' or vectorcall.
In order to do as little conversion as possible, pick one that best fits
the format of data you have available.

The following table summarizes the available functions;
please see individual documentation for details.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Fonction

@tab

appelable

@tab

args

@tab

kwargs

@item

@ref{393,,PyObject_Call()}

@tab

@code{PyObject *}

@tab

`n'-uplet

@tab

dict/@code{NULL}

@item

@ref{392,,PyObject_CallNoArgs()}

@tab

@code{PyObject *}

@tab

---

@tab

---

@item

@ref{965,,PyObject_CallOneArg()}

@tab

@code{PyObject *}

@tab

1 object

@tab

---

@item

@ref{47cc,,PyObject_CallObject()}

@tab

@code{PyObject *}

@tab

tuple/@code{NULL}

@tab

---

@item

@ref{395,,PyObject_CallFunction()}

@tab

@code{PyObject *}

@tab

format

@tab

---

@item

@ref{396,,PyObject_CallMethod()}

@tab

obj + @code{char*}

@tab

format

@tab

---

@item

@ref{4920,,PyObject_CallFunctionObjArgs()}

@tab

@code{PyObject *}

@tab

variadic

@tab

---

@item

@ref{198b,,PyObject_CallMethodObjArgs()}

@tab

obj + name

@tab

variadic

@tab

---

@item

@ref{4a64,,PyObject_CallMethodNoArgs()}

@tab

obj + name

@tab

---

@tab

---

@item

@ref{4a65,,PyObject_CallMethodOneArg()}

@tab

obj + name

@tab

1 object

@tab

---

@item

@ref{547,,PyObject_Vectorcall()}

@tab

@code{PyObject *}

@tab

vectorcall

@tab

vectorcall

@item

@ref{4a66,,PyObject_VectorcallDict()}

@tab

@code{PyObject *}

@tab

vectorcall

@tab

dict/@code{NULL}

@item

@ref{548,,PyObject_VectorcallMethod()}

@tab

arg + name

@tab

vectorcall

@tab

vectorcall

@end multitable


@geindex PyObject_Call (C function)
@anchor{c-api/call c PyObject_Call}@anchor{393}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Call (PyObject *callable, PyObject *args, PyObject *kwargs)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Appelle un objet Python appelable `callable', avec des arguments donnés par le `n'-uplet `args', et des arguments nommés donnés par le dictionnaire `kwargs'.

`args' must not be `NULL'; use an empty tuple if no arguments are needed.
If no named arguments are needed, `kwargs' can be `NULL'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.

Ceci est l'équivalent de l'expression Python : @code{callable(*args, **kwargs)}.
@end deffn

@geindex PyObject_CallNoArgs (C function)
@anchor{c-api/call c PyObject_CallNoArgs}@anchor{392}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallNoArgs (PyObject *callable)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Call a callable Python object `callable' without any arguments. It is the
most efficient way to call a callable Python object without any argument.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_CallOneArg (C function)
@anchor{c-api/call c PyObject_CallOneArg}@anchor{965}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallOneArg (PyObject *callable, PyObject *arg)
`Valeur de retour : nouvelle référence.'
Call a callable Python object `callable' with exactly 1 positional argument
`arg' and no keyword arguments.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_CallObject (C function)
@anchor{c-api/call c PyObject_CallObject}@anchor{47cc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallObject (PyObject *callable, PyObject *args)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Call a callable Python object `callable', with arguments given by the
tuple `args'.  If no arguments are needed, then `args' can be `NULL'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.

Ceci est l'équivalent de l'expression Python : @code{callable(*args)}.
@end deffn

@geindex PyObject_CallFunction (C function)
@anchor{c-api/call c PyObject_CallFunction}@anchor{395}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallFunction (PyObject *callable, const char *format, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Call a callable Python object `callable', with a variable number of C arguments.
The C arguments are described using a @ref{894,,Py_BuildValue()} style format
string.  The format can be `NULL', indicating that no arguments are provided.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.

Ceci est l'équivalent de l'expression Python : @code{callable(*args)}.

Note that if you only pass @ref{32f,,PyObject}* args,
@ref{4920,,PyObject_CallFunctionObjArgs()} is a faster alternative.


Modifié dans la version 3.4: The type of `format' was changed from @code{char *}.

@end deffn

@geindex PyObject_CallMethod (C function)
@anchor{c-api/call c PyObject_CallMethod}@anchor{396}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallMethod (PyObject *obj, const char *name, const char *format, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Call the method named `name' of object `obj' with a variable number of C
arguments.  The C arguments are described by a @ref{894,,Py_BuildValue()} format
string that should produce a tuple.

The format can be `NULL', indicating that no arguments are provided.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.

This is the equivalent of the Python expression:
@code{obj.name(arg1, arg2, ...)}.

Note that if you only pass @ref{32f,,PyObject}* args,
@ref{198b,,PyObject_CallMethodObjArgs()} is a faster alternative.


Modifié dans la version 3.4: The types of `name' and `format' were changed from @code{char *}.

@end deffn

@geindex PyObject_CallFunctionObjArgs (C function)
@anchor{c-api/call c PyObject_CallFunctionObjArgs}@anchor{4920}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallFunctionObjArgs (PyObject *callable, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Call a callable Python object `callable', with a variable number of
@ref{32f,,PyObject}* arguments.  The arguments are provided as a variable number
of parameters followed by `NULL'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.

This is the equivalent of the Python expression:
@code{callable(arg1, arg2, ...)}.
@end deffn

@geindex PyObject_CallMethodObjArgs (C function)
@anchor{c-api/call c PyObject_CallMethodObjArgs}@anchor{198b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallMethodObjArgs (PyObject *obj, PyObject *name, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Call a method of the Python object `obj', where the name of the method is given as a
Python string object in `name'.  It is called with a variable number of
@ref{32f,,PyObject}* arguments.  The arguments are provided as a variable number
of parameters followed by `NULL'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.
@end deffn

@geindex PyObject_CallMethodNoArgs (C function)
@anchor{c-api/call c PyObject_CallMethodNoArgs}@anchor{4a64}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallMethodNoArgs (PyObject *obj, PyObject *name)

Call a method of the Python object `obj' without arguments,
where the name of the method is given as a Python string object in `name'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_CallMethodOneArg (C function)
@anchor{c-api/call c PyObject_CallMethodOneArg}@anchor{4a65}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_CallMethodOneArg (PyObject *obj, PyObject *name, PyObject *arg)

Call a method of the Python object `obj' with a single positional argument
`arg', where the name of the method is given as a Python string object in
`name'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_Vectorcall (C function)
@anchor{c-api/call c PyObject_Vectorcall}@anchor{547}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Vectorcall (PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Call a callable Python object `callable'.
The arguments are the same as for @ref{542,,vectorcallfunc}.
If `callable' supports @ref{53d,,vectorcall}, this directly calls
the vectorcall function stored in `callable'.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_VectorcallDict (C function)
@anchor{c-api/call c PyObject_VectorcallDict}@anchor{4a66}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_VectorcallDict (PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)

Call `callable' with positional arguments passed exactly as in the @ref{53d,,vectorcall} protocol,
but with keyword arguments passed as a dictionary `kwdict'.
The `args' array contains only the positional arguments.

Regardless of which protocol is used internally,
a conversion of arguments needs to be done.
Therefore, this function should only be used if the caller
already has a dictionary ready to use for the keyword arguments,
but not a tuple for the positional arguments.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_VectorcallMethod (C function)
@anchor{c-api/call c PyObject_VectorcallMethod}@anchor{548}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_VectorcallMethod (PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Call a method using the vectorcall calling convention. The name of the method
is given as a Python string `name'. The object whose method is called is
`args[0]', and the `args' array starting at `args[1]' represents the arguments
of the call. There must be at least one positional argument.
`nargsf' is the number of positional arguments including `args[0]',
plus @ref{549,,PY_VECTORCALL_ARGUMENTS_OFFSET} if the value of @code{args[0]} may
temporarily be changed. Keyword arguments can be passed just like in
@ref{547,,PyObject_Vectorcall()}.

If the object has the @ref{4a67,,Py_TPFLAGS_METHOD_DESCRIPTOR} feature,
this will call the unbound method object with the full
`args' vector as arguments.

Return the result of the call on success, or raise an exception and return
`NULL' on failure.


Ajouté dans la version 3.9.

@end deffn

@node Call Support API,,Object Calling API,Call Protocol
@anchor{c-api/call call-support-api}@anchor{4a68}
@subsubsection Call Support API


@geindex PyCallable_Check (C function)
@anchor{c-api/call c PyCallable_Check}@anchor{487e}
@deffn {C Fonction} int PyCallable_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Détermine si l'objet `o' est appelable. Renvoie @code{1} si c'est le cas, et @code{0} sinon. Cette fonction réussit toujours.
@end deffn

@node Number Protocol,Sequence Protocol,Call Protocol,Couche d'abstraction des objets
@anchor{c-api/number doc}@anchor{4a69}@anchor{c-api/number number}@anchor{4a6a}@anchor{c-api/number number-protocol}@anchor{4a6b}
@subsection Number Protocol


@geindex PyNumber_Check (C function)
@anchor{c-api/number c PyNumber_Check}@anchor{a54}
@deffn {C Fonction} int PyNumber_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Returns @code{1} if the object `o' provides numeric protocols, and false otherwise.
This function always succeeds.


Modifié dans la version 3.8: Returns @code{1} if `o' is an index integer.

@end deffn

@geindex PyNumber_Add (C function)
@anchor{c-api/number c PyNumber_Add}@anchor{48fc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Add (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of adding `o1' and `o2', or @code{NULL} on failure.  This is the
equivalent of the Python expression @code{o1 + o2}.
@end deffn

@geindex PyNumber_Subtract (C function)
@anchor{c-api/number c PyNumber_Subtract}@anchor{4916}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Subtract (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of subtracting `o2' from `o1', or @code{NULL} on failure.  This is
the equivalent of the Python expression @code{o1 - o2}.
@end deffn

@geindex PyNumber_Multiply (C function)
@anchor{c-api/number c PyNumber_Multiply}@anchor{490f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Multiply (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of multiplying `o1' and `o2', or @code{NULL} on failure.  This is
the equivalent of the Python expression @code{o1 * o2}.
@end deffn

@geindex PyNumber_MatrixMultiply (C function)
@anchor{c-api/number c PyNumber_MatrixMultiply}@anchor{e9e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_MatrixMultiply (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Returns the result of matrix multiplication on `o1' and `o2', or @code{NULL} on
failure.  This is the equivalent of the Python expression @code{o1 @@ o2}.


Ajouté dans la version 3.5.

@end deffn

@geindex PyNumber_FloorDivide (C function)
@anchor{c-api/number c PyNumber_FloorDivide}@anchor{4900}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_FloorDivide (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the floor of `o1' divided by `o2', or @code{NULL} on failure.  This is
the equivalent of the Python expression @code{o1 // o2}.
@end deffn

@geindex PyNumber_TrueDivide (C function)
@anchor{c-api/number c PyNumber_TrueDivide}@anchor{4917}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_TrueDivide (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a reasonable approximation for the mathematical value of `o1' divided by
`o2', or @code{NULL} on failure.  The return value is "approximate" because binary
floating-point numbers are approximate; it is not possible to represent all real
numbers in base two.  This function can return a floating-point value when
passed two integers.  This is the equivalent of the Python expression @code{o1 / o2}.
@end deffn

@geindex PyNumber_Remainder (C function)
@anchor{c-api/number c PyNumber_Remainder}@anchor{4914}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Remainder (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the remainder of dividing `o1' by `o2', or @code{NULL} on failure.  This is
the equivalent of the Python expression @code{o1 % o2}.
@end deffn

@geindex PyNumber_Divmod (C function)
@anchor{c-api/number c PyNumber_Divmod}@anchor{48ff}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Divmod (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;divmod

See the built-in function @ref{98f,,divmod()}. Returns @code{NULL} on failure.  This is
the equivalent of the Python expression @code{divmod(o1, o2)}.
@end deffn

@geindex PyNumber_Power (C function)
@anchor{c-api/number c PyNumber_Power}@anchor{4913}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Power (PyObject *o1, PyObject *o2, PyObject *o3)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;pow

See the built-in function @ref{9c0,,pow()}. Returns @code{NULL} on failure.  This is the
equivalent of the Python expression @code{pow(o1, o2, o3)}, where `o3' is optional.
If `o3' is to be ignored, pass @ref{47c0,,Py_None} in its place (passing @code{NULL} for
`o3' would cause an illegal memory access).
@end deffn

@geindex PyNumber_Negative (C function)
@anchor{c-api/number c PyNumber_Negative}@anchor{4910}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Negative (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the negation of `o' on success, or @code{NULL} on failure. This is the
equivalent of the Python expression @code{-o}.
@end deffn

@geindex PyNumber_Positive (C function)
@anchor{c-api/number c PyNumber_Positive}@anchor{4912}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Positive (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns `o' on success, or @code{NULL} on failure.  This is the equivalent of the
Python expression @code{+o}.
@end deffn

@geindex PyNumber_Absolute (C function)
@anchor{c-api/number c PyNumber_Absolute}@anchor{48fb}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Absolute (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;abs

Returns the absolute value of `o', or @code{NULL} on failure.  This is the equivalent
of the Python expression @code{abs(o)}.
@end deffn

@geindex PyNumber_Invert (C function)
@anchor{c-api/number c PyNumber_Invert}@anchor{490d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Invert (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the bitwise negation of `o' on success, or @code{NULL} on failure.  This is
the equivalent of the Python expression @code{~o}.
@end deffn

@geindex PyNumber_Lshift (C function)
@anchor{c-api/number c PyNumber_Lshift}@anchor{490e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Lshift (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of left shifting `o1' by `o2' on success, or @code{NULL} on
failure.  This is the equivalent of the Python expression @code{o1 << o2}.
@end deffn

@geindex PyNumber_Rshift (C function)
@anchor{c-api/number c PyNumber_Rshift}@anchor{4915}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Rshift (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of right shifting `o1' by `o2' on success, or @code{NULL} on
failure.  This is the equivalent of the Python expression @code{o1 >> o2}.
@end deffn

@geindex PyNumber_And (C function)
@anchor{c-api/number c PyNumber_And}@anchor{48fd}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_And (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the "bitwise and" of `o1' and `o2' on success and @code{NULL} on failure.
This is the equivalent of the Python expression @code{o1 & o2}.
@end deffn

@geindex PyNumber_Xor (C function)
@anchor{c-api/number c PyNumber_Xor}@anchor{4918}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Xor (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the "bitwise exclusive or" of `o1' by `o2' on success, or @code{NULL} on
failure.  This is the equivalent of the Python expression @code{o1 ^ o2}.
@end deffn

@geindex PyNumber_Or (C function)
@anchor{c-api/number c PyNumber_Or}@anchor{4911}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Or (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the "bitwise or" of `o1' and `o2' on success, or @code{NULL} on failure.
This is the equivalent of the Python expression @code{o1 | o2}.
@end deffn

@geindex PyNumber_InPlaceAdd (C function)
@anchor{c-api/number c PyNumber_InPlaceAdd}@anchor{4901}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceAdd (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of adding `o1' and `o2', or @code{NULL} on failure.  The operation
is done `in-place' when `o1' supports it.  This is the equivalent of the Python
statement @code{o1 += o2}.
@end deffn

@geindex PyNumber_InPlaceSubtract (C function)
@anchor{c-api/number c PyNumber_InPlaceSubtract}@anchor{490a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceSubtract (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of subtracting `o2' from `o1', or @code{NULL} on failure.  The
operation is done `in-place' when `o1' supports it.  This is the equivalent of
the Python statement @code{o1 -= o2}.
@end deffn

@geindex PyNumber_InPlaceMultiply (C function)
@anchor{c-api/number c PyNumber_InPlaceMultiply}@anchor{4905}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceMultiply (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of multiplying `o1' and `o2', or @code{NULL} on failure.  The
operation is done `in-place' when `o1' supports it.  This is the equivalent of
the Python statement @code{o1 *= o2}.
@end deffn

@geindex PyNumber_InPlaceMatrixMultiply (C function)
@anchor{c-api/number c PyNumber_InPlaceMatrixMultiply}@anchor{e9f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceMatrixMultiply (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Returns the result of matrix multiplication on `o1' and `o2', or @code{NULL} on
failure.  The operation is done `in-place' when `o1' supports it.  This is
the equivalent of the Python statement @code{o1 @@= o2}.


Ajouté dans la version 3.5.

@end deffn

@geindex PyNumber_InPlaceFloorDivide (C function)
@anchor{c-api/number c PyNumber_InPlaceFloorDivide}@anchor{4903}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceFloorDivide (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the mathematical floor of dividing `o1' by `o2', or @code{NULL} on failure.
The operation is done `in-place' when `o1' supports it.  This is the equivalent
of the Python statement @code{o1 //= o2}.
@end deffn

@geindex PyNumber_InPlaceTrueDivide (C function)
@anchor{c-api/number c PyNumber_InPlaceTrueDivide}@anchor{490b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceTrueDivide (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a reasonable approximation for the mathematical value of `o1' divided by
`o2', or @code{NULL} on failure.  The return value is "approximate" because binary
floating-point numbers are approximate; it is not possible to represent all real
numbers in base two.  This function can return a floating-point value when
passed two integers.  The operation is done `in-place' when `o1' supports it.
This is the equivalent of the Python statement @code{o1 /= o2}.
@end deffn

@geindex PyNumber_InPlaceRemainder (C function)
@anchor{c-api/number c PyNumber_InPlaceRemainder}@anchor{4908}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceRemainder (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the remainder of dividing `o1' by `o2', or @code{NULL} on failure.  The
operation is done `in-place' when `o1' supports it.  This is the equivalent of
the Python statement @code{o1 %= o2}.
@end deffn

@geindex PyNumber_InPlacePower (C function)
@anchor{c-api/number c PyNumber_InPlacePower}@anchor{4907}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlacePower (PyObject *o1, PyObject *o2, PyObject *o3)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;pow

See the built-in function @ref{9c0,,pow()}. Returns @code{NULL} on failure.  The operation
is done `in-place' when `o1' supports it.  This is the equivalent of the Python
statement @code{o1 **= o2} when o3 is @ref{47c0,,Py_None}, or an in-place variant of
@code{pow(o1, o2, o3)} otherwise. If `o3' is to be ignored, pass @ref{47c0,,Py_None}
in its place (passing @code{NULL} for `o3' would cause an illegal memory access).
@end deffn

@geindex PyNumber_InPlaceLshift (C function)
@anchor{c-api/number c PyNumber_InPlaceLshift}@anchor{4904}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceLshift (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of left shifting `o1' by `o2' on success, or @code{NULL} on
failure.  The operation is done `in-place' when `o1' supports it.  This is the
equivalent of the Python statement @code{o1 <<= o2}.
@end deffn

@geindex PyNumber_InPlaceRshift (C function)
@anchor{c-api/number c PyNumber_InPlaceRshift}@anchor{4909}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceRshift (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the result of right shifting `o1' by `o2' on success, or @code{NULL} on
failure.  The operation is done `in-place' when `o1' supports it.  This is the
equivalent of the Python statement @code{o1 >>= o2}.
@end deffn

@geindex PyNumber_InPlaceAnd (C function)
@anchor{c-api/number c PyNumber_InPlaceAnd}@anchor{4902}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceAnd (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the "bitwise and" of `o1' and `o2' on success and @code{NULL} on failure. The
operation is done `in-place' when `o1' supports it.  This is the equivalent of
the Python statement @code{o1 &= o2}.
@end deffn

@geindex PyNumber_InPlaceXor (C function)
@anchor{c-api/number c PyNumber_InPlaceXor}@anchor{490c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceXor (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the "bitwise exclusive or" of `o1' by `o2' on success, or @code{NULL} on
failure.  The operation is done `in-place' when `o1' supports it.  This is the
equivalent of the Python statement @code{o1 ^= o2}.
@end deffn

@geindex PyNumber_InPlaceOr (C function)
@anchor{c-api/number c PyNumber_InPlaceOr}@anchor{4906}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_InPlaceOr (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the "bitwise or" of `o1' and `o2' on success, or @code{NULL} on failure.  The
operation is done `in-place' when `o1' supports it.  This is the equivalent of
the Python statement @code{o1 |= o2}.
@end deffn

@geindex PyNumber_Long (C function)
@anchor{c-api/number c PyNumber_Long}@anchor{a55}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Long (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;int

Returns the `o' converted to an integer object on success, or @code{NULL} on
failure.  This is the equivalent of the Python expression @code{int(o)}.
@end deffn

@geindex PyNumber_Float (C function)
@anchor{c-api/number c PyNumber_Float}@anchor{a56}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Float (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;float

Returns the `o' converted to a float object on success, or @code{NULL} on failure.
This is the equivalent of the Python expression @code{float(o)}.
@end deffn

@geindex PyNumber_Index (C function)
@anchor{c-api/number c PyNumber_Index}@anchor{87f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_Index (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the `o' converted to a Python int on success or @code{NULL} with a
@ref{522,,TypeError} exception raised on failure.


Modifié dans la version 3.10: The result always has exact type @ref{254,,int}.  Previously, the result
could have been an instance of a subclass of @code{int}.

@end deffn

@geindex PyNumber_ToBase (C function)
@anchor{c-api/number c PyNumber_ToBase}@anchor{1778}
@deffn {C Fonction} @ref{32f,,PyObject} *PyNumber_ToBase (PyObject *n, int base)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Returns the integer `n' converted to base `base' as a string.  The `base'
argument must be one of 2, 8, 10, or 16.  For base 2, 8, or 16, the
returned string is prefixed with a base marker of @code{'0b'}, @code{'0o'}, or
@code{'0x'}, respectively.  If `n' is not a Python int, it is converted with
@ref{87f,,PyNumber_Index()} first.
@end deffn

@geindex PyNumber_AsSsize_t (C function)
@anchor{c-api/number c PyNumber_AsSsize_t}@anchor{48fe}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyNumber_AsSsize_t (PyObject *o, PyObject *exc)
` Part of the @ref{53e,,Stable ABI}.'
Returns `o' converted to a @ref{a4e,,Py_ssize_t} value if `o' can be interpreted as an
integer.  If the call fails, an exception is raised and @code{-1} is returned.

If `o' can be converted to a Python int but the attempt to
convert to a @ref{a4e,,Py_ssize_t} value would raise an @ref{86d,,OverflowError}, then the
`exc' argument is the type of exception that will be raised (usually
@ref{14eb,,IndexError} or @ref{86d,,OverflowError}).  If `exc' is @code{NULL}, then the
exception is cleared and the value is clipped to @code{PY_SSIZE_T_MIN} for a negative
integer or @code{PY_SSIZE_T_MAX} for a positive integer.
@end deffn

@geindex PyIndex_Check (C function)
@anchor{c-api/number c PyIndex_Check}@anchor{977}
@deffn {C Fonction} int PyIndex_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.8.'
Returns @code{1} if `o' is an index integer (has the @code{nb_index} slot of the
@code{tp_as_number} structure filled in), and @code{0} otherwise.
This function always succeeds.
@end deffn

@node Sequence Protocol,Protocole de correspondance,Number Protocol,Couche d'abstraction des objets
@anchor{c-api/sequence doc}@anchor{4a6c}@anchor{c-api/sequence sequence}@anchor{4a6d}@anchor{c-api/sequence sequence-protocol}@anchor{4a6e}
@subsection Sequence Protocol


@geindex PySequence_Check (C function)
@anchor{c-api/sequence c PySequence_Check}@anchor{4934}
@deffn {C Fonction} int PySequence_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} if the object provides the sequence protocol, and @code{0} otherwise.
Note that it returns @code{1} for Python classes with a @ref{280,,__getitem__()}
method, unless they are @ref{253,,dict} subclasses, since in general it
is impossible to determine what type of keys the class supports.  This
function always succeeds.
@end deffn

@geindex PySequence_Size (C function)
@geindex PySequence_Length (C function)
@anchor{c-api/sequence c PySequence_Size}@anchor{19e0}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySequence_Size (PyObject *o)
@anchor{c-api/sequence c PySequence_Length}@anchor{493e}
@deffnx {C Fonction} @ref{a4e,,Py_ssize_t} PySequence_Length (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;len

Returns the number of objects in sequence `o' on success, and @code{-1} on
failure.  This is equivalent to the Python expression @code{len(o)}.
@end deffn

@geindex PySequence_Concat (C function)
@anchor{c-api/sequence c PySequence_Concat}@anchor{4935}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_Concat (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the concatenation of `o1' and `o2' on success, and @code{NULL} on failure.
This is the equivalent of the Python expression @code{o1 + o2}.
@end deffn

@geindex PySequence_Repeat (C function)
@anchor{c-api/sequence c PySequence_Repeat}@anchor{4940}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_Repeat (PyObject *o, Py_ssize_t count)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the result of repeating sequence object `o' `count' times, or @code{NULL} on
failure.  This is the equivalent of the Python expression @code{o * count}.
@end deffn

@geindex PySequence_InPlaceConcat (C function)
@anchor{c-api/sequence c PySequence_InPlaceConcat}@anchor{493b}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_InPlaceConcat (PyObject *o1, PyObject *o2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the concatenation of `o1' and `o2' on success, and @code{NULL} on failure.
The operation is done `in-place' when `o1' supports it.  This is the equivalent
of the Python expression @code{o1 += o2}.
@end deffn

@geindex PySequence_InPlaceRepeat (C function)
@anchor{c-api/sequence c PySequence_InPlaceRepeat}@anchor{493c}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_InPlaceRepeat (PyObject *o, Py_ssize_t count)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the result of repeating sequence object `o' `count' times, or @code{NULL} on
failure.  The operation is done `in-place' when `o' supports it.  This is the
equivalent of the Python expression @code{o *= count}.
@end deffn

@geindex PySequence_GetItem (C function)
@anchor{c-api/sequence c PySequence_GetItem}@anchor{19e1}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_GetItem (PyObject *o, Py_ssize_t i)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the `i'th element of `o', or @code{NULL} on failure. This is the equivalent of
the Python expression @code{o[i]}.
@end deffn

@geindex PySequence_GetSlice (C function)
@anchor{c-api/sequence c PySequence_GetSlice}@anchor{493a}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_GetSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the slice of sequence object `o' between `i1' and `i2', or @code{NULL} on
failure. This is the equivalent of the Python expression @code{o[i1:i2]}.
@end deffn

@geindex PySequence_SetItem (C function)
@anchor{c-api/sequence c PySequence_SetItem}@anchor{19e2}
@deffn {C Fonction} int PySequence_SetItem (PyObject *o, Py_ssize_t i, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
Assign object `v' to the `i'th element of `o'.  Raise an exception
and return @code{-1} on failure; return @code{0} on success.  This
is the equivalent of the Python statement @code{o[i] = v}.  This function `does
not' steal a reference to `v'.

If `v' is @code{NULL}, the element is deleted, but this feature is
deprecated in favour of using @ref{19e3,,PySequence_DelItem()}.
@end deffn

@geindex PySequence_DelItem (C function)
@anchor{c-api/sequence c PySequence_DelItem}@anchor{19e3}
@deffn {C Fonction} int PySequence_DelItem (PyObject *o, Py_ssize_t i)
` Part of the @ref{53e,,Stable ABI}.'
Delete the `i'th element of object `o'.  Returns @code{-1} on failure.  This is the
equivalent of the Python statement @code{del o[i]}.
@end deffn

@geindex PySequence_SetSlice (C function)
@anchor{c-api/sequence c PySequence_SetSlice}@anchor{4941}
@deffn {C Fonction} int PySequence_SetSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
Assign the sequence object `v' to the slice in sequence object `o' from `i1' to
`i2'.  This is the equivalent of the Python statement @code{o[i1:i2] = v}.
@end deffn

@geindex PySequence_DelSlice (C function)
@anchor{c-api/sequence c PySequence_DelSlice}@anchor{4938}
@deffn {C Fonction} int PySequence_DelSlice (PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
` Part of the @ref{53e,,Stable ABI}.'
Delete the slice in sequence object `o' from `i1' to `i2'.  Returns @code{-1} on
failure.  This is the equivalent of the Python statement @code{del o[i1:i2]}.
@end deffn

@geindex PySequence_Count (C function)
@anchor{c-api/sequence c PySequence_Count}@anchor{4937}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySequence_Count (PyObject *o, PyObject *value)
` Part of the @ref{53e,,Stable ABI}.'
Return the number of occurrences of `value' in `o', that is, return the number
of keys for which @code{o[key] == value}.  On failure, return @code{-1}.  This is
equivalent to the Python expression @code{o.count(value)}.
@end deffn

@geindex PySequence_Contains (C function)
@anchor{c-api/sequence c PySequence_Contains}@anchor{4936}
@deffn {C Fonction} int PySequence_Contains (PyObject *o, PyObject *value)
` Part of the @ref{53e,,Stable ABI}.'
Determine if `o' contains `value'.  If an item in `o' is equal to `value',
return @code{1}, otherwise return @code{0}. On error, return @code{-1}.  This is
equivalent to the Python expression @code{value in o}.
@end deffn

@geindex PySequence_Index (C function)
@anchor{c-api/sequence c PySequence_Index}@anchor{493d}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySequence_Index (PyObject *o, PyObject *value)
` Part of the @ref{53e,,Stable ABI}.'
Return the first index `i' for which @code{o[i] == value}.  On error, return
@code{-1}.    This is equivalent to the Python expression @code{o.index(value)}.
@end deffn

@geindex PySequence_List (C function)
@anchor{c-api/sequence c PySequence_List}@anchor{493f}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_List (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a list object with the same contents as the sequence or iterable `o',
or @code{NULL} on failure.  The returned list is guaranteed to be new.  This is
equivalent to the Python expression @code{list(o)}.
@end deffn

@geindex PySequence_Tuple (C function)
@anchor{c-api/sequence c PySequence_Tuple}@anchor{4942}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_Tuple (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;tuple

Return a tuple object with the same contents as the sequence or iterable `o',
or @code{NULL} on failure.  If `o' is a tuple, a new reference will be returned,
otherwise a tuple will be constructed with the appropriate contents.  This is
equivalent to the Python expression @code{tuple(o)}.
@end deffn

@geindex PySequence_Fast (C function)
@anchor{c-api/sequence c PySequence_Fast}@anchor{4939}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_Fast (PyObject *o, const char *m)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the sequence or iterable `o' as an object usable by the other
@code{PySequence_Fast*} family of functions. If the object is not a sequence or
iterable, raises @ref{522,,TypeError} with `m' as the message text. Returns
@code{NULL} on failure.

The @code{PySequence_Fast*} functions are thus named because they assume
`o' is a @ref{4a09,,PyTupleObject} or a @ref{4a6f,,PyListObject} and access
the data fields of `o' directly.

As a CPython implementation detail, if `o' is already a sequence or list, it
will be returned.
@end deffn

@geindex PySequence_Fast_GET_SIZE (C function)
@anchor{c-api/sequence c PySequence_Fast_GET_SIZE}@anchor{4a70}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySequence_Fast_GET_SIZE (PyObject *o)

Returns the length of `o', assuming that `o' was returned by
@ref{4939,,PySequence_Fast()} and that `o' is not @code{NULL}.  The size can also be
retrieved by calling @ref{19e0,,PySequence_Size()} on `o', but
@ref{4a70,,PySequence_Fast_GET_SIZE()} is faster because it can assume `o' is a
list or tuple.
@end deffn

@geindex PySequence_Fast_GET_ITEM (C function)
@anchor{c-api/sequence c PySequence_Fast_GET_ITEM}@anchor{4a71}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_Fast_GET_ITEM (PyObject *o, Py_ssize_t i)
`Valeur de retour : référence empruntée.'
Return the `i'th element of `o', assuming that `o' was returned by
@ref{4939,,PySequence_Fast()}, `o' is not @code{NULL}, and that `i' is within bounds.
@end deffn

@geindex PySequence_Fast_ITEMS (C function)
@anchor{c-api/sequence c PySequence_Fast_ITEMS}@anchor{4a72}
@deffn {C Fonction} @ref{32f,,PyObject} **PySequence_Fast_ITEMS (PyObject *o)

Return the underlying array of PyObject pointers.  Assumes that `o' was returned
by @ref{4939,,PySequence_Fast()} and `o' is not @code{NULL}.

Note, if a list gets resized, the reallocation may relocate the items array.
So, only use the underlying array pointer in contexts where the sequence
cannot change.
@end deffn

@geindex PySequence_ITEM (C function)
@anchor{c-api/sequence c PySequence_ITEM}@anchor{4a73}
@deffn {C Fonction} @ref{32f,,PyObject} *PySequence_ITEM (PyObject *o, Py_ssize_t i)
`Valeur de retour : nouvelle référence.'
Return the `i'th element of `o' or @code{NULL} on failure. Faster form of
@ref{19e1,,PySequence_GetItem()} but without checking that
@ref{4934,,PySequence_Check()} on `o' is true and without adjustment for negative
indices.
@end deffn

@node Protocole de correspondance,Protocole d'itération,Sequence Protocol,Couche d'abstraction des objets
@anchor{c-api/mapping doc}@anchor{4a74}@anchor{c-api/mapping mapping}@anchor{4a75}@anchor{c-api/mapping mapping-protocol}@anchor{4a76}
@subsection Protocole de correspondance


Voir aussi @ref{33d,,PyObject_GetItem()}, @ref{484e,,PyObject_SetItem()} et @ref{4921,,PyObject_DelItem()}.

@geindex PyMapping_Check (C function)
@anchor{c-api/mapping c PyMapping_Check}@anchor{48eb}
@deffn {C Fonction} int PyMapping_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} if the object provides the mapping protocol or supports slicing,
and @code{0} otherwise.  Note that it returns @code{1} for Python classes with
a @ref{280,,__getitem__()} method, since in general it is impossible to
determine what type of keys the class supports. This function always succeeds.
@end deffn

@geindex PyMapping_Size (C function)
@geindex PyMapping_Length (C function)
@anchor{c-api/mapping c PyMapping_Size}@anchor{19e4}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyMapping_Size (PyObject *o)
@anchor{c-api/mapping c PyMapping_Length}@anchor{48ec}
@deffnx {C Fonction} @ref{a4e,,Py_ssize_t} PyMapping_Length (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;len

Renvoie le nombre de clefs dans l'objet `o' et @code{-1} en cas d'échec. C'est l'équivalent de l'expression Python @code{len(o)}.
@end deffn

@geindex PyMapping_GetItemString (C function)
@anchor{c-api/mapping c PyMapping_GetItemString}@anchor{33e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMapping_GetItemString (PyObject *o, const char *key)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{33d,,PyObject_GetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
@end deffn

@geindex PyMapping_GetOptionalItem (C function)
@anchor{c-api/mapping c PyMapping_GetOptionalItem}@anchor{33b}
@deffn {C Fonction} int PyMapping_GetOptionalItem (PyObject *obj, PyObject *key, PyObject **result)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Variant of @ref{33d,,PyObject_GetItem()} which doesn't raise
@ref{33a,,KeyError} if the key is not found.

If the key is found, return @code{1} and set `*result' to a new
@ref{333,,strong reference} to the corresponding value.
If the key is not found, return @code{0} and set `*result' to @code{NULL};
the @ref{33a,,KeyError} is silenced.
If an error other than @ref{33a,,KeyError} is raised, return @code{-1} and
set `*result' to @code{NULL}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyMapping_GetOptionalItemString (C function)
@anchor{c-api/mapping c PyMapping_GetOptionalItemString}@anchor{33c}
@deffn {C Fonction} int PyMapping_GetOptionalItemString (PyObject *obj, const char *key, PyObject **result)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
This is the same as @ref{33b,,PyMapping_GetOptionalItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyMapping_SetItemString (C function)
@anchor{c-api/mapping c PyMapping_SetItemString}@anchor{48ed}
@deffn {C Fonction} int PyMapping_SetItemString (PyObject *o, const char *key, PyObject *v)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{484e,,PyObject_SetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
@end deffn

@geindex PyMapping_DelItem (C function)
@anchor{c-api/mapping c PyMapping_DelItem}@anchor{4a77}
@deffn {C Fonction} int PyMapping_DelItem (PyObject *o, PyObject *key)

This is an alias of @ref{4921,,PyObject_DelItem()}.
@end deffn

@geindex PyMapping_DelItemString (C function)
@anchor{c-api/mapping c PyMapping_DelItemString}@anchor{4a78}
@deffn {C Fonction} int PyMapping_DelItemString (PyObject *o, const char *key)

This is the same as @ref{4921,,PyObject_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
@end deffn

@geindex PyMapping_HasKeyWithError (C function)
@anchor{c-api/mapping c PyMapping_HasKeyWithError}@anchor{374}
@deffn {C Fonction} int PyMapping_HasKeyWithError (PyObject *o, PyObject *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return @code{1} if the mapping object has the key `key' and @code{0} otherwise.
This is equivalent to the Python expression @code{key in o}.
On failure, return @code{-1}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyMapping_HasKeyStringWithError (C function)
@anchor{c-api/mapping c PyMapping_HasKeyStringWithError}@anchor{376}
@deffn {C Fonction} int PyMapping_HasKeyStringWithError (PyObject *o, const char *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
This is the same as @ref{374,,PyMapping_HasKeyWithError()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyMapping_HasKey (C function)
@anchor{c-api/mapping c PyMapping_HasKey}@anchor{375}
@deffn {C Fonction} int PyMapping_HasKey (PyObject *o, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie @code{1} si l'objet de correspondance possède une clef `key' et @code{0} sinon. C'est l'équivalent de l'expression Python @code{key in o}. Cette fonction ne provoque jamais d'erreur.

@cartouche
@quotation Note 
Exceptions which occur when this calls @ref{280,,__getitem__()}
method are silently ignored.
For proper error handling, use @ref{374,,PyMapping_HasKeyWithError()},
@ref{33b,,PyMapping_GetOptionalItem()} or @ref{33d,,PyObject_GetItem()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyMapping_HasKeyString (C function)
@anchor{c-api/mapping c PyMapping_HasKeyString}@anchor{377}
@deffn {C Fonction} int PyMapping_HasKeyString (PyObject *o, const char *key)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{375,,PyMapping_HasKey()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.

@cartouche
@quotation Note 
Exceptions that occur when this calls @ref{280,,__getitem__()}
method or while creating the temporary @ref{435,,str}
object are silently ignored.
For proper error handling, use @ref{376,,PyMapping_HasKeyStringWithError()},
@ref{33c,,PyMapping_GetOptionalItemString()} or
@ref{33e,,PyMapping_GetItemString()} instead.
@end quotation
@end cartouche
@end deffn

@geindex PyMapping_Keys (C function)
@anchor{c-api/mapping c PyMapping_Keys}@anchor{baa}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMapping_Keys (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie la liste des clefs dans l'objet `o'. En cas d'échec, renvoie `NULL'.


Modifié dans la version 3.7: Auparavant, la fonction renvoyait une liste ou un `n'-uplet.

@end deffn

@geindex PyMapping_Values (C function)
@anchor{c-api/mapping c PyMapping_Values}@anchor{bab}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMapping_Values (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie la liste des valeurs dans l'objet `o'. En cas d'échec, renvoie `NULL'.


Modifié dans la version 3.7: Auparavant, la fonction renvoyait une liste ou un `n'-uplet.

@end deffn

@geindex PyMapping_Items (C function)
@anchor{c-api/mapping c PyMapping_Items}@anchor{bac}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMapping_Items (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie la liste des éléments dans l'objet `o', où chaque élément est un n-uplet contenant une paire clef-valeur. En cas d'échec, renvoie `NULL'.


Modifié dans la version 3.7: Auparavant, la fonction renvoyait une liste ou un `n'-uplet.

@end deffn

@node Protocole d'itération,Protocole tampon,Protocole de correspondance,Couche d'abstraction des objets
@anchor{c-api/iter doc}@anchor{4a79}@anchor{c-api/iter iterator}@anchor{4a7a}@anchor{c-api/iter iterator-protocol}@anchor{4a7b}
@subsection Protocole d'itération


Il existe deux fonctions dédiées à l'interaction avec les itérateurs.

@geindex PyIter_Check (C function)
@anchor{c-api/iter c PyIter_Check}@anchor{1882}
@deffn {C Fonction} int PyIter_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.8.'
Return non-zero if the object `o' can be safely passed to
@ref{48d7,,PyIter_Next()}, and @code{0} otherwise.  This function always succeeds.
@end deffn

@geindex PyAIter_Check (C function)
@anchor{c-api/iter c PyAIter_Check}@anchor{4867}
@deffn {C Fonction} int PyAIter_Check (PyObject *o)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Return non-zero if the object `o' provides the @code{AsyncIterator}
protocol, and @code{0} otherwise.  This function always succeeds.


Ajouté dans la version 3.10.

@end deffn

@geindex PyIter_Next (C function)
@anchor{c-api/iter c PyIter_Next}@anchor{48d7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyIter_Next (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the next value from the iterator `o'.  The object must be an iterator
according to @ref{1882,,PyIter_Check()} (it is up to the caller to check this).
If there are no remaining values, returns @code{NULL} with no exception set.
If an error occurs while retrieving the item, returns @code{NULL} and passes
along the exception.
@end deffn

Pour écrire une boucle itérant un itérateur, le code C devrait ressembler à :

@example
PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) @{
    /* propagate error */
@}

while ((item = PyIter_Next(iterator))) @{
    /* do something with item */
    ...
    /* release reference when done */
    Py_DECREF(item);
@}

Py_DECREF(iterator);

if (PyErr_Occurred()) @{
    /* propagate error */
@}
else @{
    /* continue doing useful work */
@}
@end example

@geindex PySendResult (C type)
@anchor{c-api/iter c PySendResult}@anchor{4a7c}
@deffn {C Type} type PySendResult

The enum value used to represent different results of @ref{884,,PyIter_Send()}.


Ajouté dans la version 3.10.

@end deffn

@geindex PyIter_Send (C function)
@anchor{c-api/iter c PyIter_Send}@anchor{884}
@deffn {C Fonction} @ref{4a7c,,PySendResult} PyIter_Send (PyObject *iter, PyObject *arg, PyObject **presult)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Sends the `arg' value into the iterator `iter'. Returns:


@itemize -

@item 
@code{PYGEN_RETURN} if iterator returns. Return value is returned via `presult'.

@item 
@code{PYGEN_NEXT} if iterator yields. Yielded value is returned via `presult'.

@item 
@code{PYGEN_ERROR} if iterator has raised and exception. `presult' is set to @code{NULL}.
@end itemize


Ajouté dans la version 3.10.

@end deffn

@geindex buffer protocol
@geindex buffer interface;(see buffer protocol)
@geindex buffer object;(see buffer protocol)

@node Protocole tampon,,Protocole d'itération,Couche d'abstraction des objets
@anchor{c-api/buffer doc}@anchor{4a7d}@anchor{c-api/buffer buffer-protocol}@anchor{4a7e}@anchor{c-api/buffer bufferobjects}@anchor{38e}
@subsection Protocole tampon


Certains objets Python enveloppent l'accès à un tableau de mémoire sous-jacente (nommée zone tampon ou simplement tampon, `buffer' en anglais). Les objets natifs @ref{1bd,,bytes} et @ref{528,,bytearray} en sont des exemples, ainsi que quelques types d'extension comme @ref{19e,,array.array}. Les bibliothèques tierces peuvent définir leurs propres types à des fins spéciales, telles que le traitement d'image ou l'analyse numérique.

Alors que chacun de ces types a sa propre sémantique, ils partagent la caractéristique commune d'être soutenus par un tampon de mémoire important.  Il est donc souhaitable, dans certains cas, d'accéder à cette mémoire directement sans l'étape intermédiaire de copie.

Python fournit une telle facilité au niveau du C sous la forme de @ref{38e,,protocole tampon}.  Ce protocole comporte deux aspects :

@geindex PyBufferProcs (C type)


@itemize -

@item 
du côté producteur, un type peut exporter une "interface tampon" qui permet aux objets de ce type d'exposer des informations concernant leur tampon sous-jacent. Cette interface est décrite dans la section @ref{4a7f,,Buffer Object Structures} ;

@item 
du côté consommateur, plusieurs moyens sont disponibles pour obtenir un pointeur vers les données sous-jacentes brutes d'un objet (par exemple un paramètre de méthode).
@end itemize

Des objets simples tels que @ref{1bd,,bytes} et @ref{528,,bytearray} exposent leur tampon sous-jacent dans un format orienté octet. D'autres formes sont possibles ; par exemple, les éléments exposés par un @ref{19e,,array.array} peuvent être des valeurs multi-octets.

An example consumer of the buffer interface is the @ref{cc9,,write()}
method of file objects: any object that can export a series of bytes through
the buffer interface can be written to a file.  While @code{write()} only
needs read-only access to the internal contents of the object passed to it,
other methods such as @ref{2ba5,,readinto()} need write access
to the contents of their argument.  The buffer interface allows objects to
selectively allow or reject exporting of read-write and read-only buffers.

Un consommateur de l'interface tampon peut acquérir un tampon sur un objet cible de deux manières :


@itemize *

@item 
appelez @ref{390,,PyObject_GetBuffer()} avec les paramètres appropriés ;

@item 
appelez @ref{55d,,PyArg_ParseTuple()} (ou l'un de ses fonctions sœurs) avec l'un des @code{y*}, @code{w*} ou @code{s*}  @ref{895,,format codes}.
@end itemize

Dans les deux cas, @ref{391,,PyBuffer_Release()} doit être appelée quand le tampon n'est plus nécessaire. Ne pas le faire peut conduire à divers problèmes tels que des fuites de ressources.

@menu
* La structure buffer:: 
* Buffer request types:: 
* Complex arrays:: 
* Fonctions relatives aux tampons:: 

@end menu

@node La structure buffer,Buffer request types,,Protocole tampon
@anchor{c-api/buffer buffer-structure}@anchor{4a80}@anchor{c-api/buffer id1}@anchor{4a81}
@subsubsection La structure `buffer'


Les structures tampons (ou simplement les "tampons", `buffers' en anglais) sont utiles pour exposer les données binaires d'un autre objet au programmeur Python. Elles peuvent également être utilisées comme un mécanisme de découpage sans copie. En utilisant leur capacité à référencer un bloc de mémoire, il est possible d'exposer toutes les données au programmeur Python assez facilement. La mémoire peut être un grand tableau constant dans une extension C, il peut s'agir d'un bloc brut de mémoire à manipuler avant de passer à une bibliothèque de système d'exploitation ou être utilisé pour transmettre des données structurées dans son format natif en mémoire.

Contrairement à la plupart des types de données exposés par l'interpréteur Python, les tampons ne sont pas de simples pointeurs vers @ref{32f,,PyObject} mais plutôt des structures C simples. Cela leur permet d'être créés et copiés très simplement. lorsque vous avez besoin d'une enveloppe générique (`wrapper' en anglais) pour un tampon, un objet @ref{4a82,,memoryview} peut être créé.

For short instructions how to write an exporting object, see
@ref{4a7f,,Buffer Object Structures}. For obtaining
a buffer, see @ref{390,,PyObject_GetBuffer()}.

@geindex Py_buffer (C type)
@anchor{c-api/buffer c Py_buffer}@anchor{742}
@deffn {C Type} type Py_buffer
` Part of the @ref{53e,,Stable ABI} (including all members) Depuis la version 3.11.'
@geindex Py_buffer.buf (C member)
@anchor{c-api/buffer c Py_buffer buf}@anchor{4a83}
@deffn {C Membre} void *buf

A pointer to the start of the logical structure described by the buffer
fields. This can be any location within the underlying physical memory
block of the exporter. For example, with negative @ref{4a84,,strides}
the value may point to the end of the memory block.

For @ref{21af,,contiguous} arrays, the value points to the beginning of
the memory block.
@end deffn

@geindex Py_buffer.obj (C member)
@anchor{c-api/buffer c Py_buffer obj}@anchor{4a85}
@deffn {C Membre} @ref{32f,,PyObject} *obj

A new reference to the exporting object. The reference is owned by
the consumer and automatically released
(i.e. reference count decremented)
and set to @code{NULL} by
@ref{391,,PyBuffer_Release()}. The field is the equivalent of the return
value of any standard C-API function.

As a special case, for `temporary' buffers that are wrapped by
@ref{74b,,PyMemoryView_FromBuffer()} or @ref{74a,,PyBuffer_FillInfo()}
this field is @code{NULL}. In general, exporting objects MUST NOT
use this scheme.
@end deffn

@geindex Py_buffer.len (C member)
@anchor{c-api/buffer c Py_buffer len}@anchor{4a86}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} len

@code{product(shape) * itemsize}. For contiguous arrays, this is the length
of the underlying memory block. For non-contiguous arrays, it is the length
that the logical structure would have if it were copied to a contiguous
representation.

Accessing @code{((char *)buf)[0] up to ((char *)buf)[len-1]} is only valid
if the buffer has been obtained by a request that guarantees contiguity. In
most cases such a request will be @ref{4a87,,PyBUF_SIMPLE} or @ref{1371,,PyBUF_WRITABLE}.
@end deffn

@geindex Py_buffer.readonly (C member)
@anchor{c-api/buffer c Py_buffer readonly}@anchor{4a88}
@deffn {C Membre} int readonly

An indicator of whether the buffer is read-only. This field is controlled
by the @ref{1371,,PyBUF_WRITABLE} flag.
@end deffn

@geindex Py_buffer.itemsize (C member)
@anchor{c-api/buffer c Py_buffer itemsize}@anchor{4a89}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} itemsize

Item size in bytes of a single element. Same as the value of @ref{1952,,struct.calcsize()}
called on non-@code{NULL} @ref{4a8a,,format} values.

Important exception: If a consumer requests a buffer without the
@ref{4a8b,,PyBUF_FORMAT} flag, @ref{4a8a,,format} will
be set to  @code{NULL},  but @ref{4a89,,itemsize} still has
the value for the original format.

If @ref{4a8c,,shape} is present, the equality
@code{product(shape) * itemsize == len} still holds and the consumer
can use @ref{4a89,,itemsize} to navigate the buffer.

If @ref{4a8c,,shape} is @code{NULL} as a result of a @ref{4a87,,PyBUF_SIMPLE}
or a @ref{1371,,PyBUF_WRITABLE} request, the consumer must disregard
@ref{4a89,,itemsize} and assume @code{itemsize == 1}.
@end deffn

@geindex Py_buffer.format (C member)
@anchor{c-api/buffer c Py_buffer format}@anchor{4a8a}
@deffn {C Membre} char *format

A `NULL' terminated string in @ref{d4,,struct} module style syntax describing
the contents of a single item. If this is @code{NULL}, @code{"B"} (unsigned bytes)
is assumed.

This field is controlled by the @ref{4a8b,,PyBUF_FORMAT} flag.
@end deffn

@geindex Py_buffer.ndim (C member)
@anchor{c-api/buffer c Py_buffer ndim}@anchor{4a8d}
@deffn {C Membre} int ndim

The number of dimensions the memory represents as an n-dimensional array.
If it is @code{0}, @ref{4a83,,buf} points to a single item representing
a scalar. In this case, @ref{4a8c,,shape}, @ref{4a84,,strides}
and @ref{4a8e,,suboffsets} MUST be @code{NULL}.
The maximum number of dimensions is given by @ref{4a8f,,PyBUF_MAX_NDIM}.
@end deffn

@geindex Py_buffer.shape (C member)
@anchor{c-api/buffer c Py_buffer shape}@anchor{4a8c}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} *shape

An array of @ref{a4e,,Py_ssize_t} of length @ref{4a8d,,ndim}
indicating the shape of the memory as an n-dimensional array. Note that
@code{shape[0] * ... * shape[ndim-1] * itemsize} MUST be equal to
@ref{4a86,,len}.

Shape values are restricted to @code{shape[n] >= 0}. The case
@code{shape[n] == 0} requires special attention. See @ref{4a90,,complex arrays}
for further information.

The shape array is read-only for the consumer.
@end deffn

@geindex Py_buffer.strides (C member)
@anchor{c-api/buffer c Py_buffer strides}@anchor{4a84}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} *strides

An array of @ref{a4e,,Py_ssize_t} of length @ref{4a8d,,ndim}
giving the number of bytes to skip to get to a new element in each
dimension.

Stride values can be any integer. For regular arrays, strides are
usually positive, but a consumer MUST be able to handle the case
@code{strides[n] <= 0}. See @ref{4a90,,complex arrays} for further information.

The strides array is read-only for the consumer.
@end deffn

@geindex Py_buffer.suboffsets (C member)
@anchor{c-api/buffer c Py_buffer suboffsets}@anchor{4a8e}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} *suboffsets

An array of @ref{a4e,,Py_ssize_t} of length @ref{4a8d,,ndim}.
If @code{suboffsets[n] >= 0}, the values stored along the nth dimension are
pointers and the suboffset value dictates how many bytes to add to each
pointer after de-referencing. A suboffset value that is negative
indicates that no de-referencing should occur (striding in a contiguous
memory block).

If all suboffsets are negative (i.e. no de-referencing is needed), then
this field must be @code{NULL} (the default value).

This type of array representation is used by the Python Imaging Library
(PIL). See @ref{4a90,,complex arrays} for further information how to access elements
of such an array.

The suboffsets array is read-only for the consumer.
@end deffn

@geindex Py_buffer.internal (C member)
@anchor{c-api/buffer c Py_buffer internal}@anchor{4a91}
@deffn {C Membre} void *internal

This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
about whether or not the shape, strides, and suboffsets arrays must be
freed when the buffer is released. The consumer MUST NOT alter this
value.
@end deffn
@end deffn

Constants:

@geindex PyBUF_MAX_NDIM (C macro)
@anchor{c-api/buffer c PyBUF_MAX_NDIM}@anchor{4a8f}
@deffn {C Macro} PyBUF_MAX_NDIM

The maximum number of dimensions the memory represents.
Exporters MUST respect this limit, consumers of multi-dimensional
buffers SHOULD be able to handle up to @code{PyBUF_MAX_NDIM} dimensions.
Currently set to 64.
@end deffn

@node Buffer request types,Complex arrays,La structure buffer,Protocole tampon
@anchor{c-api/buffer buffer-request-types}@anchor{43dc}@anchor{c-api/buffer id2}@anchor{4a92}
@subsubsection Buffer request types


Buffers are usually obtained by sending a buffer request to an exporting
object via @ref{390,,PyObject_GetBuffer()}. Since the complexity of the logical
structure of the memory can vary drastically, the consumer uses the `flags'
argument to specify the exact buffer type it can handle.

All @ref{742,,Py_buffer} fields are unambiguously defined by the request
type.

@menu
* request-independent fields:: 
* readonly@comma{} format: readonly format. 
* shape@comma{} strides@comma{} suboffsets: shape strides suboffsets. 
* contiguity requests:: 
* compound requests:: 

@end menu

@node request-independent fields,readonly format,,Buffer request types
@anchor{c-api/buffer request-independent-fields}@anchor{4a93}
@subsubsection request-independent fields


The following fields are not influenced by `flags' and must always be filled in
with the correct values: @ref{4a85,,obj}, @ref{4a83,,buf},
@ref{4a86,,len}, @ref{4a89,,itemsize}, @ref{4a8d,,ndim}.

@node readonly format,shape strides suboffsets,request-independent fields,Buffer request types
@anchor{c-api/buffer readonly-format}@anchor{4a94}
@subsubsection readonly, format


@quotation

@geindex PyBUF_WRITABLE (C macro)
@anchor{c-api/buffer c PyBUF_WRITABLE}@anchor{1371}
@deffn {C Macro} PyBUF_WRITABLE

Controls the @ref{4a88,,readonly} field. If set, the exporter
MUST provide a writable buffer or else report failure. Otherwise, the
exporter MAY provide either a read-only or writable buffer, but the choice
MUST be consistent for all consumers. For example, @ref{4a87,,PyBUF_SIMPLE} | @ref{1371,,PyBUF_WRITABLE}
can be used to request a simple writable buffer.
@end deffn

@geindex PyBUF_FORMAT (C macro)
@anchor{c-api/buffer c PyBUF_FORMAT}@anchor{4a8b}
@deffn {C Macro} PyBUF_FORMAT

Controls the @ref{4a8a,,format} field. If set, this field MUST
be filled in correctly. Otherwise, this field MUST be @code{NULL}.
@end deffn
@end quotation

@ref{1371,,PyBUF_WRITABLE} can be |'d to any of the flags in the next section.
Since @ref{4a87,,PyBUF_SIMPLE} is defined as 0, @ref{1371,,PyBUF_WRITABLE}
can be used as a stand-alone flag to request a simple writable buffer.

@ref{4a8b,,PyBUF_FORMAT} must be |'d to any of the flags except @ref{4a87,,PyBUF_SIMPLE}, because
the latter already implies format @code{B} (unsigned bytes). @code{PyBUF_FORMAT} cannot be
used on its own.

@node shape strides suboffsets,contiguity requests,readonly format,Buffer request types
@anchor{c-api/buffer shape-strides-suboffsets}@anchor{4a95}
@subsubsection shape, strides, suboffsets


The flags that control the logical structure of the memory are listed
in decreasing order of complexity. Note that each flag contains all bits
of the flags below it.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Request

@tab

shape

@tab

strides

@tab

suboffsets

@item

@geindex PyBUF_INDIRECT (C macro)
@anchor{c-api/buffer c PyBUF_INDIRECT}@anchor{4a96}
@deffn {C Macro} PyBUF_INDIRECT
@end deffn

@tab

oui

@tab

oui

@tab

si nécessaire

@item

@geindex PyBUF_STRIDES (C macro)
@anchor{c-api/buffer c PyBUF_STRIDES}@anchor{4a97}
@deffn {C Macro} PyBUF_STRIDES
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@item

@geindex PyBUF_ND (C macro)
@anchor{c-api/buffer c PyBUF_ND}@anchor{4a98}
@deffn {C Macro} PyBUF_ND
@end deffn

@tab

oui

@tab

NULL

@tab

NULL

@item

@geindex PyBUF_SIMPLE (C macro)
@anchor{c-api/buffer c PyBUF_SIMPLE}@anchor{4a87}
@deffn {C Macro} PyBUF_SIMPLE
@end deffn

@tab

NULL

@tab

NULL

@tab

NULL

@end multitable


@geindex contiguous
@geindex C-contiguous
@geindex Fortran contiguous

@node contiguity requests,compound requests,shape strides suboffsets,Buffer request types
@anchor{c-api/buffer contiguity-requests}@anchor{4a99}
@subsubsection contiguity requests


C or Fortran @ref{21af,,contiguity} can be explicitly requested,
with and without stride information. Without stride information, the buffer
must be C-contiguous.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxx} 
@headitem

Request

@tab

shape

@tab

strides

@tab

suboffsets

@tab

contig

@item

@geindex PyBUF_C_CONTIGUOUS (C macro)
@anchor{c-api/buffer c PyBUF_C_CONTIGUOUS}@anchor{1372}
@deffn {C Macro} PyBUF_C_CONTIGUOUS
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

C

@item

@geindex PyBUF_F_CONTIGUOUS (C macro)
@anchor{c-api/buffer c PyBUF_F_CONTIGUOUS}@anchor{1373}
@deffn {C Macro} PyBUF_F_CONTIGUOUS
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

F

@item

@geindex PyBUF_ANY_CONTIGUOUS (C macro)
@anchor{c-api/buffer c PyBUF_ANY_CONTIGUOUS}@anchor{4a9a}
@deffn {C Macro} PyBUF_ANY_CONTIGUOUS
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

C or F

@item

@ref{4a98,,PyBUF_ND}

@tab

oui

@tab

NULL

@tab

NULL

@tab

C

@end multitable


@node compound requests,,contiguity requests,Buffer request types
@anchor{c-api/buffer compound-requests}@anchor{4a9b}
@subsubsection compound requests


All possible requests are fully defined by some combination of the flags in
the previous section. For convenience, the buffer protocol provides frequently
used combinations as single flags.

In the following table `U' stands for undefined contiguity. The consumer would
have to call @ref{748,,PyBuffer_IsContiguous()} to determine contiguity.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxx} {xxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxx} {xxxxxxxxxxxx} {xxxxxxxxxx} 
@headitem

Request

@tab

shape

@tab

strides

@tab

suboffsets

@tab

contig

@tab

lecture seule

@tab

format

@item

@geindex PyBUF_FULL (C macro)
@anchor{c-api/buffer c PyBUF_FULL}@anchor{4a9c}
@deffn {C Macro} PyBUF_FULL
@end deffn

@tab

oui

@tab

oui

@tab

si nécessaire

@tab

U

@tab

0

@tab

oui

@item

@geindex PyBUF_FULL_RO (C macro)
@anchor{c-api/buffer c PyBUF_FULL_RO}@anchor{4a9d}
@deffn {C Macro} PyBUF_FULL_RO
@end deffn

@tab

oui

@tab

oui

@tab

si nécessaire

@tab

U

@tab

0 ou 1

@tab

oui

@item

@geindex PyBUF_RECORDS (C macro)
@anchor{c-api/buffer c PyBUF_RECORDS}@anchor{4a9e}
@deffn {C Macro} PyBUF_RECORDS
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

U

@tab

0

@tab

oui

@item

@geindex PyBUF_RECORDS_RO (C macro)
@anchor{c-api/buffer c PyBUF_RECORDS_RO}@anchor{4a9f}
@deffn {C Macro} PyBUF_RECORDS_RO
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

U

@tab

0 ou 1

@tab

oui

@item

@geindex PyBUF_STRIDED (C macro)
@anchor{c-api/buffer c PyBUF_STRIDED}@anchor{4aa0}
@deffn {C Macro} PyBUF_STRIDED
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

U

@tab

0

@tab

NULL

@item

@geindex PyBUF_STRIDED_RO (C macro)
@anchor{c-api/buffer c PyBUF_STRIDED_RO}@anchor{4aa1}
@deffn {C Macro} PyBUF_STRIDED_RO
@end deffn

@tab

oui

@tab

oui

@tab

NULL

@tab

U

@tab

0 ou 1

@tab

NULL

@item

@geindex PyBUF_CONTIG (C macro)
@anchor{c-api/buffer c PyBUF_CONTIG}@anchor{4aa2}
@deffn {C Macro} PyBUF_CONTIG
@end deffn

@tab

oui

@tab

NULL

@tab

NULL

@tab

C

@tab

0

@tab

NULL

@item

@geindex PyBUF_CONTIG_RO (C macro)
@anchor{c-api/buffer c PyBUF_CONTIG_RO}@anchor{4aa3}
@deffn {C Macro} PyBUF_CONTIG_RO
@end deffn

@tab

oui

@tab

NULL

@tab

NULL

@tab

C

@tab

0 ou 1

@tab

NULL

@end multitable


@node Complex arrays,Fonctions relatives aux tampons,Buffer request types,Protocole tampon
@anchor{c-api/buffer complex-arrays}@anchor{4a90}
@subsubsection Complex arrays


@menu
* NumPy-style; shape and strides: NumPy-style shape and strides. 
* PIL-style; shape@comma{} strides and suboffsets: PIL-style shape strides and suboffsets. 

@end menu

@node NumPy-style shape and strides,PIL-style shape strides and suboffsets,,Complex arrays
@anchor{c-api/buffer numpy-style-shape-and-strides}@anchor{4aa4}
@subsubsection NumPy-style: shape and strides


The logical structure of NumPy-style arrays is defined by @ref{4a89,,itemsize},
@ref{4a8d,,ndim}, @ref{4a8c,,shape} and @ref{4a84,,strides}.

If @code{ndim == 0}, the memory location pointed to by @ref{4a83,,buf} is
interpreted as a scalar of size @ref{4a89,,itemsize}. In that case,
both @ref{4a8c,,shape} and @ref{4a84,,strides} are @code{NULL}.

If @ref{4a84,,strides} is @code{NULL}, the array is interpreted as
a standard n-dimensional C-array. Otherwise, the consumer must access an
n-dimensional array as follows:

@example
ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);
@end example

As noted above, @ref{4a83,,buf} can point to any location within
the actual memory block. An exporter can check the validity of a buffer with
this function:

@example
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
    """Verify that the parameters represent a valid array within
       the bounds of the allocated memory:
           char *mem: start of the physical memory block
           memlen: length of the physical memory block
           offset: (char *)buf - mem
    """
    if offset % itemsize:
        return False
    if offset < 0 or offset+itemsize > memlen:
        return False
    if any(v % itemsize for v in strides):
        return False

    if ndim <= 0:
        return ndim == 0 and not shape and not strides
    if 0 in shape:
        return True

    imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] <= 0)
    imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] > 0)

    return 0 <= offset+imin and offset+imax+itemsize <= memlen
@end example

@node PIL-style shape strides and suboffsets,,NumPy-style shape and strides,Complex arrays
@anchor{c-api/buffer pil-style-shape-strides-and-suboffsets}@anchor{4aa5}
@subsubsection PIL-style: shape, strides and suboffsets


In addition to the regular items, PIL-style arrays can contain pointers
that must be followed in order to get to the next element in a dimension.
For example, the regular three-dimensional C-array @code{char v[2][2][3]} can
also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
@code{char (*v[2])[2][3]}. In suboffsets representation, those two pointers
can be embedded at the start of @ref{4a83,,buf}, pointing
to two @code{char x[2][3]} arrays that can be located anywhere in memory.

Here is a function that returns a pointer to the element in an N-D array
pointed to by an N-dimensional index when there are both non-@code{NULL} strides
and suboffsets:

@example
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
                       Py_ssize_t *suboffsets, Py_ssize_t *indices) @{
    char *pointer = (char*)buf;
    int i;
    for (i = 0; i < ndim; i++) @{
        pointer += strides[i] * indices[i];
        if (suboffsets[i] >=0 ) @{
            pointer = *((char**)pointer) + suboffsets[i];
        @}
    @}
    return (void*)pointer;
@}
@end example

@node Fonctions relatives aux tampons,,Complex arrays,Protocole tampon
@anchor{c-api/buffer buffer-related-functions}@anchor{4aa6}
@subsubsection Fonctions relatives aux tampons


@geindex PyObject_CheckBuffer (C function)
@anchor{c-api/buffer c PyObject_CheckBuffer}@anchor{38f}
@deffn {C Fonction} int PyObject_CheckBuffer (PyObject *obj)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Return @code{1} if `obj' supports the buffer interface otherwise @code{0}.  When @code{1} is
returned, it doesn't guarantee that @ref{390,,PyObject_GetBuffer()} will
succeed.  This function always succeeds.
@end deffn

@geindex PyObject_GetBuffer (C function)
@anchor{c-api/buffer c PyObject_GetBuffer}@anchor{390}
@deffn {C Fonction} int PyObject_GetBuffer (PyObject *exporter, Py_buffer *view, int flags)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Send a request to `exporter' to fill in `view' as specified by  `flags'.
If the exporter cannot provide a buffer of the exact type, it MUST raise
@ref{17b2,,BufferError}, set @code{view->obj} to @code{NULL} and
return @code{-1}.

On success, fill in `view', set @code{view->obj} to a new reference
to `exporter' and return 0. In the case of chained buffer providers
that redirect requests to a single object, @code{view->obj} MAY
refer to this object instead of `exporter' (See @ref{4a7f,,Buffer Object Structures}).

Successful calls to @ref{390,,PyObject_GetBuffer()} must be paired with calls
to @ref{391,,PyBuffer_Release()}, similar to @code{malloc()} and @code{free()}.
Thus, after the consumer is done with the buffer, @ref{391,,PyBuffer_Release()}
must be called exactly once.
@end deffn

@geindex PyBuffer_Release (C function)
@anchor{c-api/buffer c PyBuffer_Release}@anchor{391}
@deffn {C Fonction} void PyBuffer_Release (Py_buffer *view)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Release the buffer `view' and release the @ref{333,,strong reference}
(i.e. decrement the reference count) to the view's supporting object,
@code{view->obj}. This function MUST be called when the buffer
is no longer being used, otherwise reference leaks may occur.

It is an error to call this function on a buffer that was not obtained via
@ref{390,,PyObject_GetBuffer()}.
@end deffn

@geindex PyBuffer_SizeFromFormat (C function)
@anchor{c-api/buffer c PyBuffer_SizeFromFormat}@anchor{744}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyBuffer_SizeFromFormat (const char *format)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Return the implied @ref{4a89,,itemsize} from @ref{4a8a,,format}.
On error, raise an exception and return -1.


Ajouté dans la version 3.9.

@end deffn

@geindex PyBuffer_IsContiguous (C function)
@anchor{c-api/buffer c PyBuffer_IsContiguous}@anchor{748}
@deffn {C Fonction} int PyBuffer_IsContiguous (const Py_buffer *view, char order)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Return @code{1} if the memory defined by the `view' is C-style (`order' is
@code{'C'}) or Fortran-style (`order' is @code{'F'}) @ref{21af,,contiguous} or either one
(`order' is @code{'A'}).  Return @code{0} otherwise.  This function always succeeds.
@end deffn

@geindex PyBuffer_GetPointer (C function)
@anchor{c-api/buffer c PyBuffer_GetPointer}@anchor{743}
@deffn {C Fonction} void *PyBuffer_GetPointer (const Py_buffer *view, const Py_ssize_t *indices)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Get the memory area pointed to by the `indices' inside the given `view'.
`indices' must point to an array of @code{view->ndim} indices.
@end deffn

@geindex PyBuffer_FromContiguous (C function)
@anchor{c-api/buffer c PyBuffer_FromContiguous}@anchor{746}
@deffn {C Fonction} int PyBuffer_FromContiguous (const Py_buffer *view, const void *buf, Py_ssize_t len, char fort)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Copy contiguous `len' bytes from `buf' to `view'.
`fort' can be @code{'C'} or @code{'F'} (for C-style or Fortran-style ordering).
@code{0} is returned on success, @code{-1} on error.
@end deffn

@geindex PyBuffer_ToContiguous (C function)
@anchor{c-api/buffer c PyBuffer_ToContiguous}@anchor{745}
@deffn {C Fonction} int PyBuffer_ToContiguous (void *buf, const Py_buffer *src, Py_ssize_t len, char order)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Copy `len' bytes from `src' to its contiguous representation in `buf'.
`order' can be @code{'C'} or @code{'F'} or @code{'A'} (for C-style or Fortran-style
ordering or either one). @code{0} is returned on success, @code{-1} on error.

This function fails if `len' != `src->len'.
@end deffn

@geindex PyObject_CopyData (C function)
@anchor{c-api/buffer c PyObject_CopyData}@anchor{747}
@deffn {C Fonction} int PyObject_CopyData (PyObject *dest, PyObject *src)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Copy data from `src' to `dest' buffer. Can convert between C-style and
or Fortran-style buffers.

@code{0} is returned on success, @code{-1} on error.
@end deffn

@geindex PyBuffer_FillContiguousStrides (C function)
@anchor{c-api/buffer c PyBuffer_FillContiguousStrides}@anchor{749}
@deffn {C Fonction} void PyBuffer_FillContiguousStrides (int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Fill the `strides' array with byte-strides of a @ref{21af,,contiguous} (C-style if
`order' is @code{'C'} or Fortran-style if `order' is @code{'F'}) array of the
given shape with the given number of bytes per element.
@end deffn

@geindex PyBuffer_FillInfo (C function)
@anchor{c-api/buffer c PyBuffer_FillInfo}@anchor{74a}
@deffn {C Fonction} int PyBuffer_FillInfo (Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Handle buffer requests for an exporter that wants to expose `buf' of size `len'
with writability set according to `readonly'. `buf' is interpreted as a sequence
of unsigned bytes.

The `flags' argument indicates the request type. This function always fills in
`view' as specified by flags, unless `buf' has been designated as read-only
and @ref{1371,,PyBUF_WRITABLE} is set in `flags'.

On success, set @code{view->obj} to a new reference to `exporter' and
return 0. Otherwise, raise @ref{17b2,,BufferError}, set
@code{view->obj} to @code{NULL} and return @code{-1};

If this function is used as part of a @ref{4a7f,,getbufferproc},
`exporter' MUST be set to the exporting object and `flags' must be passed
unmodified. Otherwise, `exporter' MUST be @code{NULL}.
@end deffn

@node Couche des objets concrets,Initialization Finalization and Threads,Couche d'abstraction des objets,Manuel de référence de l'API Python/C
@anchor{c-api/concrete doc}@anchor{4aa7}@anchor{c-api/concrete concrete}@anchor{4aa8}@anchor{c-api/concrete concrete-objects-layer}@anchor{4aa9}
@section Couche des objets concrets


Les fonctions de ce chapitre sont spécifiques à certains types d'objets Python. Leur donner un objet du mauvais type n'est pas une bonne idée, si vous recevez un objet d'un programme Python, et que vous n'êtes pas sûr qu'il soit du bon type, vous devez vérifier son type en premier. Par exemple, pour vérifier qu'un objet est un dictionnaire, utilisez @ref{4aaa,,PyDict_Check()}. Ce chapitre est organisé comme un arbre généalogique de types d'objets Python.

@cartouche
@quotation Avertissement 
Tandis que les fonctions décrites dans ce chapitre vérifient avec soin le type des objets qui leur sont passés, beaucoup d'entre elles ne vérifient pas que @code{NULL} est passé au lieu d'un objet valide. Autoriser @code{NULL} à être passé peut provoquer des violations d'accès à la mémoire et ainsi terminer immédiatement l'interpréteur.
@end quotation
@end cartouche

@menu
* Objets fondamentaux:: 
* Objets numériques:: 
* Objets séquences:: 
* Objets conteneurs:: 
* Objets fonctions: Objets fonctions<2>. 
* Autres objets: Autres objets<2>. 

@end menu

@node Objets fondamentaux,Objets numériques,,Couche des objets concrets
@anchor{c-api/concrete fundamental}@anchor{4aab}@anchor{c-api/concrete fundamental-objects}@anchor{4aac}
@subsection Objets fondamentaux


Cette section décrit les objets de type Python et l'objet singleton @code{None}.

@menu
* Objets type: Objets type<2>. 
* L'objet None:: 

@end menu

@node Objets type<2>,L'objet None,,Objets fondamentaux
@anchor{c-api/type doc}@anchor{4aad}@anchor{c-api/type type-objects}@anchor{4aae}@anchor{c-api/type typeobjects}@anchor{4aaf}
@subsubsection Objets type


@geindex object;type

@geindex PyTypeObject (C type)
@anchor{c-api/type c PyTypeObject}@anchor{a93}
@deffn {C Type} type PyTypeObject
` Part of the @ref{53e,,Limited API} (as an opaque struct).'
The C structure of the objects used to describe built-in types.
@end deffn

@geindex PyType_Type (C var)
@anchor{c-api/type c PyType_Type}@anchor{538}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyType_Type
` Part of the @ref{53e,,Stable ABI}.'
This is the type object for type objects; it is the same object as
@ref{d36,,type} in the Python layer.
@end deffn

@geindex PyType_Check (C function)
@anchor{c-api/type c PyType_Check}@anchor{192c}
@deffn {C Fonction} int PyType_Check (PyObject *o)

Return non-zero if the object `o' is a type object, including instances of
types derived from the standard type object.  Return 0 in all other cases.
This function always succeeds.
@end deffn

@geindex PyType_CheckExact (C function)
@anchor{c-api/type c PyType_CheckExact}@anchor{192d}
@deffn {C Fonction} int PyType_CheckExact (PyObject *o)

Return non-zero if the object `o' is a type object, but not a subtype of
the standard type object.  Return 0 in all other cases.  This function
always succeeds.
@end deffn

@geindex PyType_ClearCache (C function)
@anchor{c-api/type c PyType_ClearCache}@anchor{495f}
@deffn {C Fonction} unsigned int PyType_ClearCache ()
` Part of the @ref{53e,,Stable ABI}.'
Clear the internal lookup cache. Return the current version tag.
@end deffn

@geindex PyType_GetFlags (C function)
@anchor{c-api/type c PyType_GetFlags}@anchor{18e1}
@deffn {C Fonction} unsigned long PyType_GetFlags (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI}.'
Return the @ref{184b,,tp_flags} member of `type'. This function is primarily
meant for use with @code{Py_LIMITED_API}; the individual flag bits are
guaranteed to be stable across Python releases, but access to
@ref{184b,,tp_flags} itself is not part of the @ref{38c,,limited API}.


Ajouté dans la version 3.2.



Modifié dans la version 3.4: The return type is now @code{unsigned long} rather than @code{long}.

@end deffn

@geindex PyType_GetDict (C function)
@anchor{c-api/type c PyType_GetDict}@anchor{16a8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetDict (PyTypeObject *type)

Return the type object's internal namespace, which is otherwise only
exposed via a read-only proxy (@ref{c4b,,cls.__dict__}).
This is a
replacement for accessing @ref{16a9,,tp_dict} directly.
The returned dictionary must be treated as read-only.

This function is meant for specific embedding and language-binding cases,
where direct access to the dict is necessary and indirect access
(e.g. via the proxy or @ref{341,,PyObject_GetAttr()}) isn't adequate.

Extension modules should continue to use @code{tp_dict},
directly or indirectly, when setting up their own types.


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_Modified (C function)
@anchor{c-api/type c PyType_Modified}@anchor{1780}
@deffn {C Fonction} void PyType_Modified (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI}.'
Invalidate the internal lookup cache for the type and all of its
subtypes.  This function must be called after any manual
modification of the attributes or base classes of the type.
@end deffn

@geindex PyType_AddWatcher (C function)
@anchor{c-api/type c PyType_AddWatcher}@anchor{550}
@deffn {C Fonction} int PyType_AddWatcher (PyType_WatchCallback callback)

Register `callback' as a type watcher. Return a non-negative integer ID
which must be passed to future calls to @ref{551,,PyType_Watch()}. In case of
error (e.g. no more watcher IDs available), return @code{-1} and set an
exception.


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_ClearWatcher (C function)
@anchor{c-api/type c PyType_ClearWatcher}@anchor{4ab0}
@deffn {C Fonction} int PyType_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' (previously returned from
@ref{550,,PyType_AddWatcher()}). Return @code{0} on success, @code{-1} on error (e.g.
if `watcher_id' was never registered.)

An extension should never call @code{PyType_ClearWatcher} with a `watcher_id'
that was not returned to it by a previous call to
@ref{550,,PyType_AddWatcher()}.


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_Watch (C function)
@anchor{c-api/type c PyType_Watch}@anchor{551}
@deffn {C Fonction} int PyType_Watch (int watcher_id, PyObject *type)

Mark `type' as watched. The callback granted `watcher_id' by
@ref{550,,PyType_AddWatcher()} will be called whenever
@ref{1780,,PyType_Modified()} reports a change to `type'. (The callback may be
called only once for a series of consecutive modifications to `type', if
@code{_PyType_Lookup()} is not called on `type' between the modifications;
this is an implementation detail and subject to change.)

An extension should never call @code{PyType_Watch} with a `watcher_id' that was
not returned to it by a previous call to @ref{550,,PyType_AddWatcher()}.


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_WatchCallback (C type)
@anchor{c-api/type c PyType_WatchCallback}@anchor{4ab1}
@deffn {C Type} typedef int (*PyType_WatchCallback)(@ref{32f,,PyObject} *type)

Type of a type-watcher callback function.

The callback must not modify `type' or cause @ref{1780,,PyType_Modified()} to be
called on `type' or any type in its MRO; violating this rule could cause
infinite recursion.


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_HasFeature (C function)
@anchor{c-api/type c PyType_HasFeature}@anchor{18e0}
@deffn {C Fonction} int PyType_HasFeature (PyTypeObject *o, int feature)

Return non-zero if the type object `o' sets the feature `feature'.
Type features are denoted by single bit flags.
@end deffn

@geindex PyType_IS_GC (C function)
@anchor{c-api/type c PyType_IS_GC}@anchor{4ab2}
@deffn {C Fonction} int PyType_IS_GC (PyTypeObject *o)

Return true if the type object includes support for the cycle detector; this
tests the type flag @ref{767,,Py_TPFLAGS_HAVE_GC}.
@end deffn

@geindex PyType_IsSubtype (C function)
@anchor{c-api/type c PyType_IsSubtype}@anchor{4960}
@deffn {C Fonction} int PyType_IsSubtype (PyTypeObject *a, PyTypeObject *b)
` Part of the @ref{53e,,Stable ABI}.'
Return true if `a' is a subtype of `b'.

This function only checks for actual subtypes, which means that
@ref{1f00,,__subclasscheck__()} is not called on `b'.  Call
@ref{e90,,PyObject_IsSubclass()} to do the same check that @ref{7ab,,issubclass()}
would do.
@end deffn

@geindex PyType_GenericAlloc (C function)
@anchor{c-api/type c PyType_GenericAlloc}@anchor{a59}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GenericAlloc (PyTypeObject *type, Py_ssize_t nitems)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Generic handler for the @ref{47f0,,tp_alloc} slot of a type object.  Use
Python's default memory allocation mechanism to allocate a new instance and
initialize all its contents to @code{NULL}.
@end deffn

@geindex PyType_GenericNew (C function)
@anchor{c-api/type c PyType_GenericNew}@anchor{47eb}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GenericNew (PyTypeObject *type, PyObject *args, PyObject *kwds)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Generic handler for the @ref{56b,,tp_new} slot of a type object.  Create a
new instance using the type's @ref{47f0,,tp_alloc} slot.
@end deffn

@geindex PyType_Ready (C function)
@anchor{c-api/type c PyType_Ready}@anchor{766}
@deffn {C Fonction} int PyType_Ready (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI}.'
Finalize a type object.  This should be called on all type objects to finish
their initialization.  This function is responsible for adding inherited slots
from a type's base class.  Return @code{0} on success, or return @code{-1} and sets an
exception on error.

@cartouche
@quotation Note 
If some of the base classes implements the GC protocol and the provided
type does not include the @ref{767,,Py_TPFLAGS_HAVE_GC} in its flags, then
the GC protocol will be automatically implemented from its parents. On
the contrary, if the type being created does include
@ref{767,,Py_TPFLAGS_HAVE_GC} in its flags then it `must' implement the
GC protocol itself by at least implementing the
@ref{768,,tp_traverse} handle.
@end quotation
@end cartouche
@end deffn

@geindex PyType_GetName (C function)
@anchor{c-api/type c PyType_GetName}@anchor{73c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetName (PyTypeObject *type)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Return the type's name. Equivalent to getting the type's
@ref{145f,,__name__} attribute.


Ajouté dans la version 3.11.

@end deffn

@geindex PyType_GetQualName (C function)
@anchor{c-api/type c PyType_GetQualName}@anchor{73d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetQualName (PyTypeObject *type)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Return the type's qualified name. Equivalent to getting the
type's @ref{1eab,,__qualname__} attribute.


Ajouté dans la version 3.11.

@end deffn

@geindex PyType_GetFullyQualifiedName (C function)
@anchor{c-api/type c PyType_GetFullyQualifiedName}@anchor{369}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetFullyQualifiedName (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return the type's fully qualified name. Equivalent to
@code{f"@{type.__module__@}.@{type.__qualname__@}"}, or @ref{1eab,,type.__qualname__}
if @ref{36a,,type.__module__} is not a string or is equal to @code{"builtins"}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyType_GetModuleName (C function)
@anchor{c-api/type c PyType_GetModuleName}@anchor{36b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetModuleName (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return the type's module name. Equivalent to getting the
@ref{36a,,type.__module__} attribute.


Ajouté dans la version 3.13.

@end deffn

@geindex PyType_GetSlot (C function)
@anchor{c-api/type c PyType_GetSlot}@anchor{888}
@deffn {C Fonction} void *PyType_GetSlot (PyTypeObject *type, int slot)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.4.'
Return the function pointer stored in the given slot. If the
result is @code{NULL}, this indicates that either the slot is @code{NULL},
or that the function was called with invalid parameters.
Callers will typically cast the result pointer into the appropriate
function type.

See @ref{4ab3,,PyType_Slot.slot} for possible values of the `slot' argument.


Ajouté dans la version 3.4.



Modifié dans la version 3.10: @ref{888,,PyType_GetSlot()} can now accept all types.
Previously, it was limited to @ref{952,,heap types}.

@end deffn

@geindex PyType_GetModule (C function)
@anchor{c-api/type c PyType_GetModule}@anchor{95b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetModule (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Return the module object associated with the given type when the type was
created using @ref{53c,,PyType_FromModuleAndSpec()}.

If no module is associated with the given type, sets @ref{522,,TypeError}
and returns @code{NULL}.

This function is usually used to get the module in which a method is defined.
Note that in such a method, @code{PyType_GetModule(Py_TYPE(self))}
may not return the intended result.
@code{Py_TYPE(self)} may be a `subclass' of the intended class, and subclasses
are not necessarily defined in the same module as their superclass.
See @ref{74e,,PyCMethod} to get the class that defines the method.
See @ref{38a,,PyType_GetModuleByDef()} for cases when @code{PyCMethod} cannot
be used.


Ajouté dans la version 3.9.

@end deffn

@geindex PyType_GetModuleState (C function)
@anchor{c-api/type c PyType_GetModuleState}@anchor{95c}
@deffn {C Fonction} void *PyType_GetModuleState (PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Return the state of the module object associated with the given type.
This is a shortcut for calling @ref{96d,,PyModule_GetState()} on the result
of @ref{95b,,PyType_GetModule()}.

If no module is associated with the given type, sets @ref{522,,TypeError}
and returns @code{NULL}.

If the `type' has an associated module but its state is @code{NULL},
returns @code{NULL} without setting an exception.


Ajouté dans la version 3.9.

@end deffn

@geindex PyType_GetModuleByDef (C function)
@anchor{c-api/type c PyType_GetModuleByDef}@anchor{38a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_GetModuleByDef (PyTypeObject *type, struct PyModuleDef *def)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Find the first superclass whose module was created from
the given @ref{96a,,PyModuleDef} `def', and return that module.

If no module is found, raises a @ref{522,,TypeError} and returns @code{NULL}.

This function is intended to be used together with
@ref{96d,,PyModule_GetState()} to get module state from slot methods (such as
@ref{56d,,tp_init} or @ref{4ab4,,nb_add})
and other places where a method's defining class cannot be passed using the
@ref{74e,,PyCMethod} calling convention.


Ajouté dans la version 3.11.

@end deffn

@geindex PyUnstable_Type_AssignVersionTag (C function)
@anchor{c-api/type c PyUnstable_Type_AssignVersionTag}@anchor{4ab5}
@deffn {C Fonction} int PyUnstable_Type_AssignVersionTag (PyTypeObject *type)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Attempt to assign a version tag to the given type.

Returns 1 if the type already had a valid version tag or a new one was
assigned, or 0 if a new tag could not be assigned.


Ajouté dans la version 3.12.

@end deffn

@menu
* Creating Heap-Allocated Types:: 

@end menu

@node Creating Heap-Allocated Types,,,Objets type<2>
@anchor{c-api/type creating-heap-allocated-types}@anchor{4ab6}
@subsubsection Creating Heap-Allocated Types


The following functions and structs are used to create
@ref{952,,heap types}.

@geindex PyType_FromMetaclass (C function)
@anchor{c-api/type c PyType_FromMetaclass}@anchor{53b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_FromMetaclass (PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
Create and return a @ref{952,,heap type} from the `spec'
(see @ref{89c,,Py_TPFLAGS_HEAPTYPE}).

The metaclass `metaclass' is used to construct the resulting type object.
When `metaclass' is @code{NULL}, the metaclass is derived from `bases'
(or `Py_tp_base[s]' slots if `bases' is @code{NULL}, see below).

Metaclasses that override @ref{56b,,tp_new} are not
supported, except if @code{tp_new} is @code{NULL}.
(For backwards compatibility, other @code{PyType_From*} functions allow
such metaclasses. They ignore @code{tp_new}, which may result in incomplete
initialization. This is deprecated and in Python 3.14+ such metaclasses will
not be supported.)

The `bases' argument can be used to specify base classes; it can either
be only one class or a tuple of classes.
If `bases' is @code{NULL}, the `Py_tp_bases' slot is used instead.
If that also is @code{NULL}, the `Py_tp_base' slot is used instead.
If that also is @code{NULL}, the new type derives from @ref{a7a,,object}.

The `module' argument can be used to record the module in which the new
class is defined. It must be a module object or @code{NULL}.
If not @code{NULL}, the module is associated with the new type and can later be
retrieved with @ref{95b,,PyType_GetModule()}.
The associated module is not inherited by subclasses; it must be specified
for each class individually.

This function calls @ref{766,,PyType_Ready()} on the new type.

Note that this function does `not' fully match the behavior of
calling @ref{d36,,type()} or using the @ref{12b5,,class} statement.
With user-provided base types or metaclasses, prefer
@ref{4a5d,,calling} @ref{d36,,type} (or the metaclass)
over @code{PyType_From*} functions.
Specifically:


@itemize *

@item 
@ref{56c,,__new__()} is not called on the new class
(and it must be set to @code{type.__new__}).

@item 
@ref{69b,,__init__()} is not called on the new class.

@item 
@ref{61c,,__init_subclass__()} is not called on any bases.

@item 
@ref{c3c,,__set_name__()} is not called on new descriptors.
@end itemize


Ajouté dans la version 3.12.

@end deffn

@geindex PyType_FromModuleAndSpec (C function)
@anchor{c-api/type c PyType_FromModuleAndSpec}@anchor{53c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_FromModuleAndSpec (PyObject *module, PyType_Spec *spec, PyObject *bases)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Equivalent to @code{PyType_FromMetaclass(NULL, module, spec, bases)}.


Ajouté dans la version 3.9.



Modifié dans la version 3.10: The function now accepts a single class as the `bases' argument and
@code{NULL} as the @code{tp_doc} slot.



Modifié dans la version 3.12: The function now finds and uses a metaclass corresponding to the provided
base classes.  Previously, only @ref{d36,,type} instances were returned.

The @ref{56b,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@ref{56b,,tp_new} is deprecated and in Python 3.14+ it
will be no longer allowed.

@end deffn

@geindex PyType_FromSpecWithBases (C function)
@anchor{c-api/type c PyType_FromSpecWithBases}@anchor{56a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_FromSpecWithBases (PyType_Spec *spec, PyObject *bases)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.3.'
Equivalent to @code{PyType_FromMetaclass(NULL, NULL, spec, bases)}.


Ajouté dans la version 3.3.



Modifié dans la version 3.12: The function now finds and uses a metaclass corresponding to the provided
base classes.  Previously, only @ref{d36,,type} instances were returned.

The @ref{56b,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@ref{56b,,tp_new} is deprecated and in Python 3.14+ it
will be no longer allowed.

@end deffn

@geindex PyType_FromSpec (C function)
@anchor{c-api/type c PyType_FromSpec}@anchor{569}
@deffn {C Fonction} @ref{32f,,PyObject} *PyType_FromSpec (PyType_Spec *spec)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Equivalent to @code{PyType_FromMetaclass(NULL, NULL, spec, NULL)}.


Modifié dans la version 3.12: The function now finds and uses a metaclass corresponding to the
base classes provided in `Py_tp_base[s]' slots.
Previously, only @ref{d36,,type} instances were returned.

The @ref{56b,,tp_new} of the metaclass is `ignored'.
which may result in incomplete initialization.
Creating classes whose metaclass overrides
@ref{56b,,tp_new} is deprecated and in Python 3.14+ it
will be no longer allowed.

@end deffn

@geindex PyType_Spec (C type)
@anchor{c-api/type c PyType_Spec}@anchor{16a5}
@deffn {C Type} type PyType_Spec
` Part of the @ref{53e,,Stable ABI} (including all members).'
Structure defining a type's behavior.

@geindex PyType_Spec.name (C member)
@anchor{c-api/type c PyType_Spec name}@anchor{4ab7}
@deffn {C Membre} const char *name

Name of the type, used to set @ref{1880,,PyTypeObject.tp_name}.
@end deffn

@geindex PyType_Spec.basicsize (C member)
@anchor{c-api/type c PyType_Spec basicsize}@anchor{533}
@deffn {C Membre} int basicsize

If positive, specifies the size of the instance in bytes.
It is used to set @ref{974,,PyTypeObject.tp_basicsize}.

If zero, specifies that @ref{974,,tp_basicsize}
should be inherited.

If negative, the absolute value specifies how much space instances of the
class need `in addition' to the superclass.
Use @ref{534,,PyObject_GetTypeData()} to get a pointer to subclass-specific
memory reserved this way.


Modifié dans la version 3.12: Previously, this field could not be negative.

@end deffn

@geindex PyType_Spec.itemsize (C member)
@anchor{c-api/type c PyType_Spec itemsize}@anchor{4ab8}
@deffn {C Membre} int itemsize

Size of one element of a variable-size type, in bytes.
Used to set @ref{1ef2,,PyTypeObject.tp_itemsize}.
See @code{tp_itemsize} documentation for caveats.

If zero, @ref{1ef2,,tp_itemsize} is inherited.
Extending arbitrary variable-sized classes is dangerous,
since some types use a fixed offset for variable-sized memory,
which can then overlap fixed-sized memory used by a subclass.
To help prevent mistakes, inheriting @code{itemsize} is only possible
in the following situations:


@itemize -

@item 
The base is not variable-sized (its
@ref{1ef2,,tp_itemsize}).

@item 
The requested @ref{533,,PyType_Spec.basicsize} is positive,
suggesting that the memory layout of the base class is known.

@item 
The requested @ref{533,,PyType_Spec.basicsize} is zero,
suggesting that the subclass does not access the instance's memory
directly.

@item 
With the @ref{536,,Py_TPFLAGS_ITEMS_AT_END} flag.
@end itemize
@end deffn

@geindex PyType_Spec.flags (C member)
@anchor{c-api/type c PyType_Spec flags}@anchor{4ab9}
@deffn {C Membre} unsigned int flags

Type flags, used to set @ref{184b,,PyTypeObject.tp_flags}.

If the @code{Py_TPFLAGS_HEAPTYPE} flag is not set,
@ref{56a,,PyType_FromSpecWithBases()} sets it automatically.
@end deffn

@geindex PyType_Spec.slots (C member)
@anchor{c-api/type c PyType_Spec slots}@anchor{4aba}
@deffn {C Membre} @ref{4961,,PyType_Slot} *slots

Array of @ref{4961,,PyType_Slot} structures.
Terminated by the special slot value @code{@{0, NULL@}}.

Each slot ID should be specified at most once.
@end deffn
@end deffn

@geindex PyType_Slot (C type)
@anchor{c-api/type c PyType_Slot}@anchor{4961}
@deffn {C Type} type PyType_Slot
` Part of the @ref{53e,,Stable ABI} (including all members).'
Structure defining optional functionality of a type, containing a slot ID
and a value pointer.

@geindex PyType_Slot.slot (C member)
@anchor{c-api/type c PyType_Slot slot}@anchor{4ab3}
@deffn {C Membre} int slot

A slot ID.

Slot IDs are named like the field names of the structures
@ref{a93,,PyTypeObject}, @ref{13d4,,PyNumberMethods},
@ref{4813,,PySequenceMethods}, @ref{4814,,PyMappingMethods} and
@ref{4abb,,PyAsyncMethods} with an added @code{Py_} prefix.
For example, use:


@itemize *

@item 
@code{Py_tp_dealloc} to set @ref{47ee,,PyTypeObject.tp_dealloc}

@item 
@code{Py_nb_add} to set @ref{4ab4,,PyNumberMethods.nb_add}

@item 
@code{Py_sq_length} to set @ref{4abc,,PySequenceMethods.sq_length}
@end itemize

The following “offset” fields cannot be set using @ref{4961,,PyType_Slot}:


@itemize *

@item 
@ref{975,,tp_weaklistoffset}
(use @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} instead if possible)

@item 
@ref{4abd,,tp_dictoffset}
(use @ref{361,,Py_TPFLAGS_MANAGED_DICT} instead if possible)

@item 
@ref{4a5f,,tp_vectorcall_offset}
(use @code{"__vectorcalloffset__"} in
@ref{4abe,,PyMemberDef})
@end itemize

If it is not possible to switch to a @code{MANAGED} flag (for example,
for vectorcall or to support Python older than 3.12), specify the
offset in @ref{47f1,,Py_tp_members}.
See @ref{4abe,,PyMemberDef documentation}
for details.

The following fields cannot be set at all when creating a heap type:


@itemize *

@item 
@ref{4abf,,tp_vectorcall}
(use @ref{56b,,tp_new} and/or
@ref{56d,,tp_init})

@item 
Internal fields:
@ref{16a9,,tp_dict},
@ref{4ac0,,tp_mro},
@ref{4ac1,,tp_cache},
@ref{55e,,tp_subclasses}, and
@ref{4ac2,,tp_weaklist}.
@end itemize

Setting @code{Py_tp_bases} or @code{Py_tp_base} may be
problematic on some platforms.
To avoid issues, use the `bases' argument of
@ref{56a,,PyType_FromSpecWithBases()} instead.


Modifié dans la version 3.9: Slots in @ref{4ac3,,PyBufferProcs} may be set in the unlimited API.



Modifié dans la version 3.11: @ref{74c,,bf_getbuffer} and
@ref{74d,,bf_releasebuffer} are now available
under the @ref{38c,,limited API}.

@end deffn

@geindex PyType_Slot.pfunc (C member)
@anchor{c-api/type c PyType_Slot pfunc}@anchor{4ac4}
@deffn {C Membre} void *pfunc

The desired value of the slot. In most cases, this is a pointer
to a function.

Slots other than @code{Py_tp_doc} may not be @code{NULL}.
@end deffn
@end deffn

@node L'objet None,,Objets type<2>,Objets fondamentaux
@anchor{c-api/none doc}@anchor{4ac5}@anchor{c-api/none noneobject}@anchor{4ac6}@anchor{c-api/none the-none-object}@anchor{4ac7}
@subsubsection L'objet @code{None}


@geindex object;None

Note that the @ref{a93,,PyTypeObject} for @code{None} is not directly exposed in the
Python/C API.  Since @code{None} is a singleton, testing for object identity (using
@code{==} in C) is sufficient. There is no @code{PyNone_Check()} function for the
same reason.

@geindex Py_None (C var)
@anchor{c-api/none c Py_None}@anchor{47c0}
@deffn {C Variable} @ref{32f,,PyObject} *Py_None

The Python @code{None} object, denoting lack of value.  This object has no methods
and is @ref{42aa,,immortal}.


Modifié dans la version 3.12: @ref{47c0,,Py_None} is @ref{42aa,,immortal}.

@end deffn

@geindex Py_RETURN_NONE (C macro)
@anchor{c-api/none c Py_RETURN_NONE}@anchor{1427}
@deffn {C Macro} Py_RETURN_NONE

Return @ref{47c0,,Py_None} from a function.
@end deffn

@node Objets numériques,Objets séquences,Objets fondamentaux,Couche des objets concrets
@anchor{c-api/concrete numeric-objects}@anchor{4ac8}@anchor{c-api/concrete numericobjects}@anchor{4ac9}
@subsection Objets numériques


@geindex object;numeric

@menu
* Objets Integer:: 
* Les objets booléens:: 
* Floating-Point Objects:: 
* Objets représentant des nombres complexes:: 

@end menu

@node Objets Integer,Les objets booléens,,Objets numériques
@anchor{c-api/long doc}@anchor{4aca}@anchor{c-api/long integer-objects}@anchor{4acb}@anchor{c-api/long longobjects}@anchor{4acc}
@subsubsection Objets `Integer'


@geindex object;long integer
@geindex object;integer

All integers are implemented as "long" integer objects of arbitrary size.

On error, most @code{PyLong_As*} APIs return @code{(return type)-1} which cannot be
distinguished from a number.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.

@geindex PyLongObject (C type)
@anchor{c-api/long c PyLongObject}@anchor{574}
@deffn {C Type} type PyLongObject
` Part of the @ref{53e,,Limited API} (as an opaque struct).'
This subtype of @ref{32f,,PyObject} represents a Python integer object.
@end deffn

@geindex PyLong_Type (C var)
@anchor{c-api/long c PyLong_Type}@anchor{48ea}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyLong_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python integer type.
This is the same object as @ref{254,,int} in the Python layer.
@end deffn

@geindex PyLong_Check (C function)
@anchor{c-api/long c PyLong_Check}@anchor{4acd}
@deffn {C Fonction} int PyLong_Check (PyObject *p)

Return true if its argument is a @ref{574,,PyLongObject} or a subtype of
@ref{574,,PyLongObject}.  This function always succeeds.
@end deffn

@geindex PyLong_CheckExact (C function)
@anchor{c-api/long c PyLong_CheckExact}@anchor{4ace}
@deffn {C Fonction} int PyLong_CheckExact (PyObject *p)

Return true if its argument is a @ref{574,,PyLongObject}, but not a subtype of
@ref{574,,PyLongObject}.  This function always succeeds.
@end deffn

@geindex PyLong_FromLong (C function)
@anchor{c-api/long c PyLong_FromLong}@anchor{17c7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromLong (long v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from `v', or @code{NULL} on failure.

The current implementation keeps an array of integer objects for all integers
between @code{-5} and @code{256}. When you create an int in that range you actually
just get back a reference to the existing object.
@end deffn

@geindex PyLong_FromUnsignedLong (C function)
@anchor{c-api/long c PyLong_FromUnsignedLong}@anchor{194f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromUnsignedLong (unsigned long v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from a C unsigned long, or
@code{NULL} on failure.
@end deffn

@geindex PyLong_FromSsize_t (C function)
@anchor{c-api/long c PyLong_FromSsize_t}@anchor{48e6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromSsize_t (Py_ssize_t v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from a C @ref{a4e,,Py_ssize_t}, or
@code{NULL} on failure.
@end deffn

@geindex PyLong_FromSize_t (C function)
@anchor{c-api/long c PyLong_FromSize_t}@anchor{1951}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromSize_t (size_t v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from a C @code{size_t}, or
@code{NULL} on failure.
@end deffn

@geindex PyLong_FromLongLong (C function)
@anchor{c-api/long c PyLong_FromLongLong}@anchor{17c8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromLongLong (long long v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from a C long long, or @code{NULL}
on failure.
@end deffn

@geindex PyLong_FromUnsignedLongLong (C function)
@anchor{c-api/long c PyLong_FromUnsignedLongLong}@anchor{1950}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromUnsignedLongLong (unsigned long long v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from a C unsigned long long,
or @code{NULL} on failure.
@end deffn

@geindex PyLong_FromDouble (C function)
@anchor{c-api/long c PyLong_FromDouble}@anchor{92f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromDouble (double v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} object from the integer part of `v', or
@code{NULL} on failure.
@end deffn

@geindex PyLong_FromString (C function)
@anchor{c-api/long c PyLong_FromString}@anchor{48e7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromString (const char *str, char **pend, int base)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{574,,PyLongObject} based on the string value in `str', which
is interpreted according to the radix in `base', or @code{NULL} on failure.  If
`pend' is non-@code{NULL}, `*pend' will point to the end of `str' on success or
to the first character that could not be processed on error.  If `base' is @code{0},
`str' is interpreted using the @ref{1e4b,,Entiers littéraux} definition; in this case, leading
zeros in a non-zero decimal number raises a @ref{1ff,,ValueError}.  If `base' is not
@code{0}, it must be between @code{2} and @code{36}, inclusive.  Leading and trailing
whitespace and single underscores after a base specifier and between digits are
ignored.  If there are no digits or `str' is not NULL-terminated following the
digits and trailing whitespace, @ref{1ff,,ValueError} will be raised.


@subsubheading Voir aussi


Python methods @ref{181d,,int.to_bytes()} and @ref{17dd,,int.from_bytes()}
to convert a @ref{574,,PyLongObject} to/from an array of bytes in base
@code{256}. You can call those from C using @ref{396,,PyObject_CallMethod()}.

@end deffn

@geindex PyLong_FromUnicodeObject (C function)
@anchor{c-api/long c PyLong_FromUnicodeObject}@anchor{8a7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromUnicodeObject (PyObject *u, int base)
`Valeur de retour : nouvelle référence.'
Convert a sequence of Unicode digits in the string `u' to a Python integer
value.


Ajouté dans la version 3.3.

@end deffn

@geindex PyLong_FromVoidPtr (C function)
@anchor{c-api/long c PyLong_FromVoidPtr}@anchor{48e8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromVoidPtr (void *p)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Python integer from the pointer `p'. The pointer value can be
retrieved from the resulting value using @ref{48e5,,PyLong_AsVoidPtr()}.
@end deffn

@geindex PyLong_FromNativeBytes (C function)
@anchor{c-api/long c PyLong_FromNativeBytes}@anchor{358}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromNativeBytes (const void *buffer, size_t n_bytes, int flags)

Create a Python integer from the value contained in the first `n_bytes' of
`buffer', interpreted as a two's-complement signed number.

`flags' are as for @ref{357,,PyLong_AsNativeBytes()}. Passing @code{-1} will select
the native endian that CPython was compiled with and assume that the
most-significant bit is a sign bit. Passing
@code{Py_ASNATIVEBYTES_UNSIGNED_BUFFER} will produce the same result as calling
@ref{359,,PyLong_FromUnsignedNativeBytes()}. Other flags are ignored.


Ajouté dans la version 3.13.

@end deffn

@geindex PyLong_FromUnsignedNativeBytes (C function)
@anchor{c-api/long c PyLong_FromUnsignedNativeBytes}@anchor{359}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_FromUnsignedNativeBytes (const void *buffer, size_t n_bytes, int flags)

Create a Python integer from the value contained in the first `n_bytes' of
`buffer', interpreted as an unsigned number.

`flags' are as for @ref{357,,PyLong_AsNativeBytes()}. Passing @code{-1} will select
the native endian that CPython was compiled with and assume that the
most-significant bit is not a sign bit. Flags other than endian are ignored.


Ajouté dans la version 3.13.

@end deffn

@geindex PyLong_AsLong (C function)
@anchor{c-api/long c PyLong_AsLong}@anchor{356}
@deffn {C Fonction} long PyLong_AsLong (PyObject *obj)
` Part of the @ref{53e,,Stable ABI}.'
@geindex LONG_MAX (C macro)
@geindex OverflowError (built-in exception)

Return a C long representation of `obj'.  If `obj' is not an
instance of @ref{574,,PyLongObject}, first call its @ref{707,,__index__()} method
(if present) to convert it to a @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `obj' is out of range for a
long.

Returns @code{-1} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.



Modifié dans la version 3.10: This function will no longer use @ref{706,,__int__()}.


@geindex PyLong_AS_LONG (C function)
@anchor{c-api/long c PyLong_AS_LONG}@anchor{4acf}
@deffn {C Fonction} long PyLong_AS_LONG (PyObject *obj)

A @ref{206,,soft deprecated} alias.
Exactly equivalent to the preferred @code{PyLong_AsLong}. In particular,
it can fail with @ref{86d,,OverflowError} or another exception.


Obsolète depuis la version 3.14: The function is soft deprecated.

@end deffn
@end deffn

@geindex PyLong_AsInt (C function)
@anchor{c-api/long c PyLong_AsInt}@anchor{355}
@deffn {C Fonction} int PyLong_AsInt (PyObject *obj)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Similar to @ref{356,,PyLong_AsLong()}, but store the result in a C
int instead of a C long.


Ajouté dans la version 3.13.

@end deffn

@geindex PyLong_AsLongAndOverflow (C function)
@anchor{c-api/long c PyLong_AsLongAndOverflow}@anchor{1245}
@deffn {C Fonction} long PyLong_AsLongAndOverflow (PyObject *obj, int *overflow)
` Part of the @ref{53e,,Stable ABI}.'
Return a C long representation of `obj'.  If `obj' is not an
instance of @ref{574,,PyLongObject}, first call its @ref{707,,__index__()}
method (if present) to convert it to a @ref{574,,PyLongObject}.

If the value of `obj' is greater than @code{LONG_MAX} or less than
@code{LONG_MIN}, set `*overflow' to @code{1} or @code{-1}, respectively, and
return @code{-1}; otherwise, set `*overflow' to @code{0}.  If any other exception
occurs set `*overflow' to @code{0} and return @code{-1} as usual.

Returns @code{-1} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.



Modifié dans la version 3.10: This function will no longer use @ref{706,,__int__()}.

@end deffn

@geindex PyLong_AsLongLong (C function)
@anchor{c-api/long c PyLong_AsLongLong}@anchor{48e0}
@deffn {C Fonction} long long PyLong_AsLongLong (PyObject *obj)
` Part of the @ref{53e,,Stable ABI}.'
@geindex OverflowError (built-in exception)

Return a C long long representation of `obj'.  If `obj' is not an
instance of @ref{574,,PyLongObject}, first call its @ref{707,,__index__()} method
(if present) to convert it to a @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `obj' is out of range for a
long long.

Returns @code{-1} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.



Modifié dans la version 3.10: This function will no longer use @ref{706,,__int__()}.

@end deffn

@geindex PyLong_AsLongLongAndOverflow (C function)
@anchor{c-api/long c PyLong_AsLongLongAndOverflow}@anchor{1244}
@deffn {C Fonction} long long PyLong_AsLongLongAndOverflow (PyObject *obj, int *overflow)
` Part of the @ref{53e,,Stable ABI}.'
Return a C long long representation of `obj'.  If `obj' is not an
instance of @ref{574,,PyLongObject}, first call its @ref{707,,__index__()} method
(if present) to convert it to a @ref{574,,PyLongObject}.

If the value of `obj' is greater than @code{LLONG_MAX} or less than
@code{LLONG_MIN}, set `*overflow' to @code{1} or @code{-1}, respectively,
and return @code{-1}; otherwise, set `*overflow' to @code{0}.  If any other
exception occurs set `*overflow' to @code{0} and return @code{-1} as usual.

Returns @code{-1} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.


Ajouté dans la version 3.2.



Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.



Modifié dans la version 3.10: This function will no longer use @ref{706,,__int__()}.

@end deffn

@geindex PyLong_AsSsize_t (C function)
@anchor{c-api/long c PyLong_AsSsize_t}@anchor{48e2}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyLong_AsSsize_t (PyObject *pylong)
` Part of the @ref{53e,,Stable ABI}.'
@geindex PY_SSIZE_T_MAX (C macro)
@geindex OverflowError (built-in exception)

Return a C @ref{a4e,,Py_ssize_t} representation of `pylong'.  `pylong' must
be an instance of @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `pylong' is out of range for a
@ref{a4e,,Py_ssize_t}.

Returns @code{-1} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsUnsignedLong (C function)
@anchor{c-api/long c PyLong_AsUnsignedLong}@anchor{48e3}
@deffn {C Fonction} unsigned long PyLong_AsUnsignedLong (PyObject *pylong)
` Part of the @ref{53e,,Stable ABI}.'
@geindex ULONG_MAX (C macro)
@geindex OverflowError (built-in exception)

Return a C unsigned long representation of `pylong'.  `pylong'
must be an instance of @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `pylong' is out of range for a
unsigned long.

Returns @code{(unsigned long)-1} on error.
Use @ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsSize_t (C function)
@anchor{c-api/long c PyLong_AsSize_t}@anchor{48e1}
@deffn {C Fonction} size_t PyLong_AsSize_t (PyObject *pylong)
` Part of the @ref{53e,,Stable ABI}.'
@geindex SIZE_MAX (C macro)
@geindex OverflowError (built-in exception)

Return a C @code{size_t} representation of `pylong'.  `pylong' must be
an instance of @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `pylong' is out of range for a
@code{size_t}.

Returns @code{(size_t)-1} on error.
Use @ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsUnsignedLongLong (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongLong}@anchor{1272}
@deffn {C Fonction} unsigned long long PyLong_AsUnsignedLongLong (PyObject *pylong)
` Part of the @ref{53e,,Stable ABI}.'
@geindex OverflowError (built-in exception)

Return a C unsigned long long representation of `pylong'.  `pylong'
must be an instance of @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `pylong' is out of range for an
unsigned long long.

Returns @code{(unsigned long long)-1} on error.
Use @ref{187f,,PyErr_Occurred()} to disambiguate.


Modifié dans la version 3.1: A negative `pylong' now raises @ref{86d,,OverflowError}, not @ref{522,,TypeError}.

@end deffn

@geindex PyLong_AsUnsignedLongMask (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongMask}@anchor{48e4}
@deffn {C Fonction} unsigned long PyLong_AsUnsignedLongMask (PyObject *obj)
` Part of the @ref{53e,,Stable ABI}.'
Return a C unsigned long representation of `obj'.  If `obj' is not
an instance of @ref{574,,PyLongObject}, first call its @ref{707,,__index__()}
method (if present) to convert it to a @ref{574,,PyLongObject}.

If the value of `obj' is out of range for an unsigned long,
return the reduction of that value modulo @code{ULONG_MAX + 1}.

Returns @code{(unsigned long)-1} on error.  Use @ref{187f,,PyErr_Occurred()} to
disambiguate.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.



Modifié dans la version 3.10: This function will no longer use @ref{706,,__int__()}.

@end deffn

@geindex PyLong_AsUnsignedLongLongMask (C function)
@anchor{c-api/long c PyLong_AsUnsignedLongLongMask}@anchor{1974}
@deffn {C Fonction} unsigned long long PyLong_AsUnsignedLongLongMask (PyObject *obj)
` Part of the @ref{53e,,Stable ABI}.'
Return a C unsigned long long representation of `obj'.  If `obj'
is not an instance of @ref{574,,PyLongObject}, first call its
@ref{707,,__index__()} method (if present) to convert it to a
@ref{574,,PyLongObject}.

If the value of `obj' is out of range for an unsigned long long,
return the reduction of that value modulo @code{ULLONG_MAX + 1}.

Returns @code{(unsigned long long)-1} on error.  Use @ref{187f,,PyErr_Occurred()}
to disambiguate.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.



Modifié dans la version 3.10: This function will no longer use @ref{706,,__int__()}.

@end deffn

@geindex PyLong_AsDouble (C function)
@anchor{c-api/long c PyLong_AsDouble}@anchor{48df}
@deffn {C Fonction} double PyLong_AsDouble (PyObject *pylong)
` Part of the @ref{53e,,Stable ABI}.'
Return a C double representation of `pylong'.  `pylong' must be
an instance of @ref{574,,PyLongObject}.

Raise @ref{86d,,OverflowError} if the value of `pylong' is out of range for a
double.

Returns @code{-1.0} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsVoidPtr (C function)
@anchor{c-api/long c PyLong_AsVoidPtr}@anchor{48e5}
@deffn {C Fonction} void *PyLong_AsVoidPtr (PyObject *pylong)
` Part of the @ref{53e,,Stable ABI}.'
Convert a Python integer `pylong' to a C void pointer.
If `pylong' cannot be converted, an @ref{86d,,OverflowError} will be raised.  This
is only assured to produce a usable void pointer for values created
with @ref{48e8,,PyLong_FromVoidPtr()}.

Returns @code{NULL} on error.  Use @ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyLong_AsNativeBytes (C function)
@anchor{c-api/long c PyLong_AsNativeBytes}@anchor{357}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyLong_AsNativeBytes (PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int flags)

Copy the Python integer value `pylong' to a native `buffer' of size
`n_bytes'. The `flags' can be set to @code{-1} to behave similarly to a C cast,
or to values documented below to control the behavior.

Returns @code{-1} with an exception raised on error.  This may happen if
`pylong' cannot be interpreted as an integer, or if `pylong' was negative
and the @code{Py_ASNATIVEBYTES_REJECT_NEGATIVE} flag was set.

Otherwise, returns the number of bytes required to store the value.
If this is equal to or less than `n_bytes', the entire value was copied.
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
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.

@cartouche
@quotation Note 
Overflow is not considered an error. If the returned value
is larger than `n_bytes', most significant bits were discarded.
@end quotation
@end cartouche

@code{0} will never be returned.

Values are always copied as two's-complement.

Usage example:

@example
int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) @{
    // Failed. A Python exception was set with the reason.
    return NULL;
@}
else if (bytes <= (Py_ssize_t)sizeof(value)) @{
    // Success!
@}
else @{
    // Overflow occurred, but 'value' contains the truncated
    // lowest bits of pylong.
@}
@end example

Passing zero to `n_bytes' will return the size of a buffer that would
be large enough to hold the value. This may be larger than technically
necessary, but not unreasonably so. If `n_bytes=0', `buffer' may be
@code{NULL}.

@cartouche
@quotation Note 
Passing `n_bytes=0' to this function is not an accurate way to determine
the bit length of the value.
@end quotation
@end cartouche

To get at the entire Python value of an unknown size, the function can be
called twice: first to determine the buffer size, then to fill it:

@example
// Ask how much space we need.
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) @{
    // Failed. A Python exception was set with the reason.
    return NULL;
@}
assert(expected != 0);  // Impossible per the API definition.
uint8_t *bignum = malloc(expected);
if (!bignum) @{
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
@}
// Safely get the entire value.
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) @{  // Exception has been set.
    free(bignum);
    return NULL;
@}
else if (bytes > expected) @{  // This should not be possible.
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
@}
// The expected success given the above pre-check.
// ... use bignum ...
free(bignum);
@end example

`flags' is either @code{-1} (@code{Py_ASNATIVEBYTES_DEFAULTS}) to select defaults
that behave most like a C cast, or a combination of the other flags in
the table below.
Note that @code{-1} cannot be combined with other flags.

Currently, @code{-1} corresponds to
@code{Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxx} 
@headitem

Option

@tab

Valeur

@item

@geindex Py_ASNATIVEBYTES_DEFAULTS (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_DEFAULTS}@anchor{4ad0}
@deffn {C Macro} Py_ASNATIVEBYTES_DEFAULTS
@end deffn

@tab

@code{-1}

@item

@geindex Py_ASNATIVEBYTES_BIG_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_BIG_ENDIAN}@anchor{4ad1}
@deffn {C Macro} Py_ASNATIVEBYTES_BIG_ENDIAN
@end deffn

@tab

@code{0}

@item

@geindex Py_ASNATIVEBYTES_LITTLE_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_LITTLE_ENDIAN}@anchor{4ad2}
@deffn {C Macro} Py_ASNATIVEBYTES_LITTLE_ENDIAN
@end deffn

@tab

@code{1}

@item

@geindex Py_ASNATIVEBYTES_NATIVE_ENDIAN (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_NATIVE_ENDIAN}@anchor{4ad3}
@deffn {C Macro} Py_ASNATIVEBYTES_NATIVE_ENDIAN
@end deffn

@tab

@code{3}

@item

@geindex Py_ASNATIVEBYTES_UNSIGNED_BUFFER (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_UNSIGNED_BUFFER}@anchor{4ad4}
@deffn {C Macro} Py_ASNATIVEBYTES_UNSIGNED_BUFFER
@end deffn

@tab

@code{4}

@item

@geindex Py_ASNATIVEBYTES_REJECT_NEGATIVE (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_REJECT_NEGATIVE}@anchor{4ad5}
@deffn {C Macro} Py_ASNATIVEBYTES_REJECT_NEGATIVE
@end deffn

@tab

@code{8}

@item

@geindex Py_ASNATIVEBYTES_ALLOW_INDEX (C macro)
@anchor{c-api/long c Py_ASNATIVEBYTES_ALLOW_INDEX}@anchor{4ad6}
@deffn {C Macro} Py_ASNATIVEBYTES_ALLOW_INDEX
@end deffn

@tab

@code{16}

@end multitable


Specifying @code{Py_ASNATIVEBYTES_NATIVE_ENDIAN} will override any other endian
flags. Passing @code{2} is reserved.

By default, sufficient buffer will be requested to include a sign bit.
For example, when converting 128 with `n_bytes=1', the function will return
2 (or more) in order to store a zero sign bit.

If @code{Py_ASNATIVEBYTES_UNSIGNED_BUFFER} is specified, a zero sign bit
will be omitted from size calculations. This allows, for example, 128 to fit
in a single-byte buffer. If the destination buffer is later treated as
signed, a positive input value may become negative.
Note that the flag does not affect handling of negative values: for those,
space for a sign bit is always requested.

Specifying @code{Py_ASNATIVEBYTES_REJECT_NEGATIVE} causes an exception to be set
if `pylong' is negative. Without this flag, negative values will be copied
provided there is enough space for at least one sign bit, regardless of
whether @code{Py_ASNATIVEBYTES_UNSIGNED_BUFFER} was specified.

If @code{Py_ASNATIVEBYTES_ALLOW_INDEX} is specified and a non-integer value is
passed, its @ref{707,,__index__()} method will be called first. This may
result in Python code executing and other threads being allowed to run, which
could cause changes to other objects or values in use. When `flags' is
@code{-1}, this option is not set, and non-integer values will raise
@ref{522,,TypeError}.

@cartouche
@quotation Note 
With the default `flags' (@code{-1}, or `UNSIGNED_BUFFER'  without
`REJECT_NEGATIVE'), multiple Python integers can map to a single value
without overflow. For example, both @code{255} and @code{-1} fit a single-byte
buffer and set all its bits.
This matches typical C cast behavior.
@end quotation
@end cartouche


Ajouté dans la version 3.13.

@end deffn

@geindex PyLong_GetInfo (C function)
@anchor{c-api/long c PyLong_GetInfo}@anchor{48e9}
@deffn {C Fonction} @ref{32f,,PyObject} *PyLong_GetInfo (void)
` Part of the @ref{53e,,Stable ABI}.'
On success, return a read only @ref{639,,named tuple}, that holds
information about Python's internal representation of integers.
See @ref{1271,,sys.int_info} for description of individual fields.

On failure, return @code{NULL} with an exception set.


Ajouté dans la version 3.1.

@end deffn

@geindex PyUnstable_Long_IsCompact (C function)
@anchor{c-api/long c PyUnstable_Long_IsCompact}@anchor{575}
@deffn {C Fonction} int PyUnstable_Long_IsCompact (const PyLongObject *op)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Return 1 if `op' is compact, 0 otherwise.

This function makes it possible for performance-critical code to implement
a “fast path” for small integers. For compact values use
@ref{576,,PyUnstable_Long_CompactValue()}; for others fall back to a
@ref{48e1,,PyLong_As*} function or
@ref{357,,PyLong_AsNativeBytes()}.

The speedup is expected to be negligible for most users.

Exactly what values are considered compact is an implementation detail
and is subject to change.


Ajouté dans la version 3.12.

@end deffn

@geindex PyUnstable_Long_CompactValue (C function)
@anchor{c-api/long c PyUnstable_Long_CompactValue}@anchor{576}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnstable_Long_CompactValue (const PyLongObject *op)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

If `op' is compact, as determined by @ref{575,,PyUnstable_Long_IsCompact()},
return its value.

Otherwise, the return value is undefined.


Ajouté dans la version 3.12.

@end deffn

@node Les objets booléens,Floating-Point Objects,Objets Integer,Objets numériques
@anchor{c-api/bool doc}@anchor{4ad7}@anchor{c-api/bool boolean-objects}@anchor{4ad8}@anchor{c-api/bool boolobjects}@anchor{4ad9}
@subsubsection Les objets booléens


Booleans in Python are implemented as a subclass of integers.  There are only
two booleans, @ref{4ada,,Py_False} and @ref{4adb,,Py_True}.  As such, the normal
creation and deletion functions don't apply to booleans.  The following macros
are available, however.

@geindex PyBool_Type (C var)
@anchor{c-api/bool c PyBool_Type}@anchor{486b}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyBool_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python boolean type; it
is the same object as @ref{451,,bool} in the Python layer.
@end deffn

@geindex PyBool_Check (C function)
@anchor{c-api/bool c PyBool_Check}@anchor{4adc}
@deffn {C Fonction} int PyBool_Check (PyObject *o)

Renvoie vrai si `o' est de type @code{PyBook_Type}. Cette fonction réussit systématiquement.
@end deffn

@geindex Py_False (C var)
@anchor{c-api/bool c Py_False}@anchor{4ada}
@deffn {C Variable} @ref{32f,,PyObject} *Py_False

The Python @code{False} object.  This object has no methods and is
@ref{42aa,,immortal}.


Modifié dans la version 3.12: @ref{4ada,,Py_False} is @ref{42aa,,immortal}.

@end deffn

@geindex Py_True (C var)
@anchor{c-api/bool c Py_True}@anchor{4adb}
@deffn {C Variable} @ref{32f,,PyObject} *Py_True

The Python @code{True} object.  This object has no methods and is
@ref{42aa,,immortal}.


Modifié dans la version 3.12: @ref{4adb,,Py_True} is @ref{42aa,,immortal}.

@end deffn

@geindex Py_RETURN_FALSE (C macro)
@anchor{c-api/bool c Py_RETURN_FALSE}@anchor{1429}
@deffn {C Macro} Py_RETURN_FALSE

Return @ref{4ada,,Py_False} from a function.
@end deffn

@geindex Py_RETURN_TRUE (C macro)
@anchor{c-api/bool c Py_RETURN_TRUE}@anchor{1428}
@deffn {C Macro} Py_RETURN_TRUE

Return @ref{4adb,,Py_True} from a function.
@end deffn

@geindex PyBool_FromLong (C function)
@anchor{c-api/bool c PyBool_FromLong}@anchor{486a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyBool_FromLong (long v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return @ref{4adb,,Py_True} or @ref{4ada,,Py_False}, depending on the truth value of `v'.
@end deffn

@node Floating-Point Objects,Objets représentant des nombres complexes,Les objets booléens,Objets numériques
@anchor{c-api/float doc}@anchor{4add}@anchor{c-api/float floating-point-objects}@anchor{4ade}@anchor{c-api/float floatobjects}@anchor{4adf}
@subsubsection Floating-Point Objects


@geindex object;floating-point

@geindex PyFloatObject (C type)
@anchor{c-api/float c PyFloatObject}@anchor{4ae0}
@deffn {C Type} type PyFloatObject

This subtype of @ref{32f,,PyObject} represents a Python floating-point object.
@end deffn

@geindex PyFloat_Type (C var)
@anchor{c-api/float c PyFloat_Type}@anchor{48c7}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyFloat_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python floating-point
type.  This is the same object as @ref{2eb,,float} in the Python layer.
@end deffn

@geindex PyFloat_Check (C function)
@anchor{c-api/float c PyFloat_Check}@anchor{4ae1}
@deffn {C Fonction} int PyFloat_Check (PyObject *p)

Return true if its argument is a @ref{4ae0,,PyFloatObject} or a subtype of
@ref{4ae0,,PyFloatObject}.  This function always succeeds.
@end deffn

@geindex PyFloat_CheckExact (C function)
@anchor{c-api/float c PyFloat_CheckExact}@anchor{4ae2}
@deffn {C Fonction} int PyFloat_CheckExact (PyObject *p)

Return true if its argument is a @ref{4ae0,,PyFloatObject}, but not a subtype of
@ref{4ae0,,PyFloatObject}.  This function always succeeds.
@end deffn

@geindex PyFloat_FromString (C function)
@anchor{c-api/float c PyFloat_FromString}@anchor{48c6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFloat_FromString (PyObject *str)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a @ref{4ae0,,PyFloatObject} object based on the string value in `str', or
@code{NULL} on failure.
@end deffn

@geindex PyFloat_FromDouble (C function)
@anchor{c-api/float c PyFloat_FromDouble}@anchor{48c5}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFloat_FromDouble (double v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a @ref{4ae0,,PyFloatObject} object from `v', or @code{NULL} on failure.
@end deffn

@geindex PyFloat_AsDouble (C function)
@anchor{c-api/float c PyFloat_AsDouble}@anchor{a57}
@deffn {C Fonction} double PyFloat_AsDouble (PyObject *pyfloat)
` Part of the @ref{53e,,Stable ABI}.'
Return a C double representation of the contents of `pyfloat'.  If
`pyfloat' is not a Python floating-point object but has a @ref{9ba,,__float__()}
method, this method will first be called to convert `pyfloat' into a float.
If @code{__float__()} is not defined then it falls back to @ref{707,,__index__()}.
This method returns @code{-1.0} upon failure, so one should call
@ref{187f,,PyErr_Occurred()} to check for errors.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.

@end deffn

@geindex PyFloat_AS_DOUBLE (C function)
@anchor{c-api/float c PyFloat_AS_DOUBLE}@anchor{4ae3}
@deffn {C Fonction} double PyFloat_AS_DOUBLE (PyObject *pyfloat)

Return a C double representation of the contents of `pyfloat', but
without error checking.
@end deffn

@geindex PyFloat_GetInfo (C function)
@anchor{c-api/float c PyFloat_GetInfo}@anchor{13a7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFloat_GetInfo (void)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie une instance `structseq' qui contient les informations sur la précision et les valeurs minimales et maximales pour un nombre à virgule flottante. C'est une enveloppe autour du fichier d'entête @code{float.h}.
@end deffn

@geindex PyFloat_GetMax (C function)
@anchor{c-api/float c PyFloat_GetMax}@anchor{13a5}
@deffn {C Fonction} double PyFloat_GetMax ()
` Part of the @ref{53e,,Stable ABI}.'
Return the maximum representable finite float `DBL_MAX' as C double.
@end deffn

@geindex PyFloat_GetMin (C function)
@anchor{c-api/float c PyFloat_GetMin}@anchor{13a6}
@deffn {C Fonction} double PyFloat_GetMin ()
` Part of the @ref{53e,,Stable ABI}.'
Return the minimum normalized positive float `DBL_MIN' as C double.
@end deffn

@menu
* Pack and Unpack functions:: 

@end menu

@node Pack and Unpack functions,,,Floating-Point Objects
@anchor{c-api/float pack-and-unpack-functions}@anchor{4ae4}
@subsubsection Pack and Unpack functions


The pack and unpack functions provide an efficient platform-independent way to
store floating-point values as byte strings. The Pack routines produce a bytes
string from a C double, and the Unpack routines produce a C
double from such a bytes string. The suffix (2, 4 or 8) specifies the
number of bytes in the bytes string.

On platforms that appear to use IEEE 754 formats these functions work by
copying bits. On other platforms, the 2-byte format is identical to the IEEE
754 binary16 half-precision format, the 4-byte format (32-bit) is identical to
the IEEE 754 binary32 single precision format, and the 8-byte format to the
IEEE 754 binary64 double precision format, although the packing of INFs and
NaNs (if such things exist on the platform) isn't handled correctly, and
attempting to unpack a bytes string containing an IEEE INF or NaN will raise an
exception.

On non-IEEE platforms with more precision, or larger dynamic range, than IEEE
754 supports, not all values can be packed; on non-IEEE platforms with less
precision, or smaller dynamic range, not all values can be unpacked. What
happens in such cases is partly accidental (alas).


Ajouté dans la version 3.11.


@menu
* Pack functions:: 
* Unpack functions:: 

@end menu

@node Pack functions,Unpack functions,,Pack and Unpack functions
@anchor{c-api/float pack-functions}@anchor{4ae5}
@subsubsection Pack functions


The pack routines write 2, 4 or 8 bytes, starting at `p'. `le' is an
int argument, non-zero if you want the bytes string in little-endian
format (exponent last, at @code{p+1}, @code{p+3}, or @code{p+6} @code{p+7}), zero if you
want big-endian format (exponent first, at `p'). The @code{PY_BIG_ENDIAN}
constant can be used to use the native endian: it is equal to @code{1} on big
endian processor, or @code{0} on little endian processor.

Return value: @code{0} if all is OK, @code{-1} if error (and an exception is set,
most likely @ref{86d,,OverflowError}).

There are two problems on non-IEEE platforms:


@itemize *

@item 
What this does is undefined if `x' is a NaN or infinity.

@item 
@code{-0.0} and @code{+0.0} produce the same bytes string.
@end itemize

@geindex PyFloat_Pack2 (C function)
@anchor{c-api/float c PyFloat_Pack2}@anchor{74f}
@deffn {C Fonction} int PyFloat_Pack2 (double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary16 half-precision format.
@end deffn

@geindex PyFloat_Pack4 (C function)
@anchor{c-api/float c PyFloat_Pack4}@anchor{750}
@deffn {C Fonction} int PyFloat_Pack4 (double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary32 single precision format.
@end deffn

@geindex PyFloat_Pack8 (C function)
@anchor{c-api/float c PyFloat_Pack8}@anchor{751}
@deffn {C Fonction} int PyFloat_Pack8 (double x, unsigned char *p, int le)

Pack a C double as the IEEE 754 binary64 double precision format.
@end deffn

@node Unpack functions,,Pack functions,Pack and Unpack functions
@anchor{c-api/float unpack-functions}@anchor{4ae6}
@subsubsection Unpack functions


The unpack routines read 2, 4 or 8 bytes, starting at `p'.  `le' is an
int argument, non-zero if the bytes string is in little-endian format
(exponent last, at @code{p+1}, @code{p+3} or @code{p+6} and @code{p+7}), zero if big-endian
(exponent first, at `p'). The @code{PY_BIG_ENDIAN} constant can be used to
use the native endian: it is equal to @code{1} on big endian processor, or @code{0}
on little endian processor.

Return value: The unpacked double.  On error, this is @code{-1.0} and
@ref{187f,,PyErr_Occurred()} is true (and an exception is set, most likely
@ref{86d,,OverflowError}).

Note that on a non-IEEE platform this will refuse to unpack a bytes string that
represents a NaN or infinity.

@geindex PyFloat_Unpack2 (C function)
@anchor{c-api/float c PyFloat_Unpack2}@anchor{752}
@deffn {C Fonction} double PyFloat_Unpack2 (const unsigned char *p, int le)

Unpack the IEEE 754 binary16 half-precision format as a C double.
@end deffn

@geindex PyFloat_Unpack4 (C function)
@anchor{c-api/float c PyFloat_Unpack4}@anchor{753}
@deffn {C Fonction} double PyFloat_Unpack4 (const unsigned char *p, int le)

Unpack the IEEE 754 binary32 single precision format as a C double.
@end deffn

@geindex PyFloat_Unpack8 (C function)
@anchor{c-api/float c PyFloat_Unpack8}@anchor{754}
@deffn {C Fonction} double PyFloat_Unpack8 (const unsigned char *p, int le)

Unpack the IEEE 754 binary64 double precision format as a C double.
@end deffn

@node Objets représentant des nombres complexes,,Floating-Point Objects,Objets numériques
@anchor{c-api/complex doc}@anchor{4ae7}@anchor{c-api/complex complex-number-objects}@anchor{4ae8}@anchor{c-api/complex complexobjects}@anchor{4ae9}
@subsubsection Objets représentant des nombres complexes


@geindex object;complex number

Les nombres complexes Python sont implémentés comme deux types distincts, lorsqu'ils sont vus de l'API C : l'un est l'objet Python tel qu'il est vu par les programmes Python, et l'autre est une structure C qui représente la valeur exacte du nombre complexe. L'API fournit des fonctions pour travailler avec ces deux représentations.

@menu
* Nombres complexes en tant que structures C:: 
* Nombres complexes en tant qu'objets Python:: 

@end menu

@node Nombres complexes en tant que structures C,Nombres complexes en tant qu'objets Python,,Objets représentant des nombres complexes
@anchor{c-api/complex complex-numbers-as-c-structures}@anchor{4aea}
@subsubsection Nombres complexes en tant que structures C


Les fonctions qui acceptent ces structures comme paramètres et les renvoient comme résultats le font en fonction de leur `valeur' au lieu de les dé-référencer en utilisant des pointeurs. C'est constant dans toute l'API.

@geindex Py_complex (C type)
@anchor{c-api/complex c Py_complex}@anchor{4a1f}
@deffn {C Type} type Py_complex

The C structure which corresponds to the value portion of a Python complex
number object.  Most of the functions for dealing with complex number objects
use structures of this type as input or output values, as appropriate.

@geindex Py_complex.real (C member)
@geindex Py_complex.imag (C member)
@anchor{c-api/complex c Py_complex real}@anchor{4aeb}
@deffn {C Membre} double real
@anchor{c-api/complex c Py_complex imag}@anchor{4aec}
@deffnx {C Membre} double imag
@end deffn

The structure is defined as:

@example
typedef struct @{
    double real;
    double imag;
@} Py_complex;
@end example
@end deffn

@geindex _Py_c_sum (C function)
@anchor{c-api/complex c _Py_c_sum}@anchor{4aed}
@deffn {C Fonction} @ref{4a1f,,Py_complex} _Py_c_sum (Py_complex left, Py_complex right)

Renvoie la somme de deux nombres complexes, sous la forme d'un @ref{4a1f,,Py_complex} en C.
@end deffn

@geindex _Py_c_diff (C function)
@anchor{c-api/complex c _Py_c_diff}@anchor{4aee}
@deffn {C Fonction} @ref{4a1f,,Py_complex} _Py_c_diff (Py_complex left, Py_complex right)

Renvoie la différence de deux nombres complexes, sous la forme d'un @ref{4a1f,,Py_complex} en C.
@end deffn

@geindex _Py_c_neg (C function)
@anchor{c-api/complex c _Py_c_neg}@anchor{4aef}
@deffn {C Fonction} @ref{4a1f,,Py_complex} _Py_c_neg (Py_complex num)

Return the negation of the complex number `num', using the C
@ref{4a1f,,Py_complex} representation.
@end deffn

@geindex _Py_c_prod (C function)
@anchor{c-api/complex c _Py_c_prod}@anchor{4af0}
@deffn {C Fonction} @ref{4a1f,,Py_complex} _Py_c_prod (Py_complex left, Py_complex right)

Renvoie le produit de deux nombres complexes, sous la forme d'un @ref{4a1f,,Py_complex} en C.
@end deffn

@geindex _Py_c_quot (C function)
@anchor{c-api/complex c _Py_c_quot}@anchor{4af1}
@deffn {C Fonction} @ref{4a1f,,Py_complex} _Py_c_quot (Py_complex dividend, Py_complex divisor)

Renvoie le quotient de deux nombres complexes, sous la forme d'un @ref{4a1f,,Py_complex} en C.

If `divisor' is null, this method returns zero and sets
@code{errno} to @code{EDOM}.
@end deffn

@geindex _Py_c_pow (C function)
@anchor{c-api/complex c _Py_c_pow}@anchor{153c}
@deffn {C Fonction} @ref{4a1f,,Py_complex} _Py_c_pow (Py_complex num, Py_complex exp)

Renvoie `num' à la puissance `exp', sous la forme d'un @ref{4a1f,,Py_complex} en C.

If `num' is null and `exp' is not a positive real number,
this method returns zero and sets @code{errno} to @code{EDOM}.
@end deffn

@node Nombres complexes en tant qu'objets Python,,Nombres complexes en tant que structures C,Objets représentant des nombres complexes
@anchor{c-api/complex complex-numbers-as-python-objects}@anchor{4af2}
@subsubsection Nombres complexes en tant qu'objets Python


@geindex PyComplexObject (C type)
@anchor{c-api/complex c PyComplexObject}@anchor{4af3}
@deffn {C Type} type PyComplexObject

Ce sous-type de l'objet @ref{32f,,PyObject} représente un nombre complexe en Python.
@end deffn

@geindex PyComplex_Type (C var)
@anchor{c-api/complex c PyComplex_Type}@anchor{4898}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyComplex_Type
` Part of the @ref{53e,,Stable ABI}.'
Cette instance de @ref{a93,,PyTypeObject} représente le type nombre complexe Python. C'est le même objet que la classe @ref{2ec,,complex} de la couche Python.
@end deffn

@geindex PyComplex_Check (C function)
@anchor{c-api/complex c PyComplex_Check}@anchor{4af4}
@deffn {C Fonction} int PyComplex_Check (PyObject *p)

Return true if its argument is a @ref{4af3,,PyComplexObject} or a subtype of
@ref{4af3,,PyComplexObject}.  This function always succeeds.
@end deffn

@geindex PyComplex_CheckExact (C function)
@anchor{c-api/complex c PyComplex_CheckExact}@anchor{4af5}
@deffn {C Fonction} int PyComplex_CheckExact (PyObject *p)

Return true if its argument is a @ref{4af3,,PyComplexObject}, but not a subtype of
@ref{4af3,,PyComplexObject}.  This function always succeeds.
@end deffn

@geindex PyComplex_FromCComplex (C function)
@anchor{c-api/complex c PyComplex_FromCComplex}@anchor{4af6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyComplex_FromCComplex (Py_complex v)
`Valeur de retour : nouvelle référence.'
Create a new Python complex number object from a C @ref{4a1f,,Py_complex} value.
Return @code{NULL} with an exception set on error.
@end deffn

@geindex PyComplex_FromDoubles (C function)
@anchor{c-api/complex c PyComplex_FromDoubles}@anchor{4897}
@deffn {C Fonction} @ref{32f,,PyObject} *PyComplex_FromDoubles (double real, double imag)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{4af3,,PyComplexObject} object from `real' and `imag'.
Return @code{NULL} with an exception set on error.
@end deffn

@geindex PyComplex_RealAsDouble (C function)
@anchor{c-api/complex c PyComplex_RealAsDouble}@anchor{1620}
@deffn {C Fonction} double PyComplex_RealAsDouble (PyObject *op)
` Part of the @ref{53e,,Stable ABI}.'
Return the real part of `op' as a C double.

If `op' is not a Python complex number object but has a
@ref{5d1,,__complex__()} method, this method will first be called to
convert `op' to a Python complex number object.  If @code{__complex__()} is
not defined then it falls back to call @ref{a57,,PyFloat_AsDouble()} and
returns its result.

Upon failure, this method returns @code{-1.0} with an exception set, so one
should call @ref{187f,,PyErr_Occurred()} to check for errors.


Modifié dans la version 3.13: Use @ref{5d1,,__complex__()} if available.

@end deffn

@geindex PyComplex_ImagAsDouble (C function)
@anchor{c-api/complex c PyComplex_ImagAsDouble}@anchor{1621}
@deffn {C Fonction} double PyComplex_ImagAsDouble (PyObject *op)
` Part of the @ref{53e,,Stable ABI}.'
Return the imaginary part of `op' as a C double.

If `op' is not a Python complex number object but has a
@ref{5d1,,__complex__()} method, this method will first be called to
convert `op' to a Python complex number object.  If @code{__complex__()} is
not defined then it falls back to call @ref{a57,,PyFloat_AsDouble()} and
returns @code{0.0} on success.

Upon failure, this method returns @code{-1.0} with an exception set, so one
should call @ref{187f,,PyErr_Occurred()} to check for errors.


Modifié dans la version 3.13: Use @ref{5d1,,__complex__()} if available.

@end deffn

@geindex PyComplex_AsCComplex (C function)
@anchor{c-api/complex c PyComplex_AsCComplex}@anchor{13a8}
@deffn {C Fonction} @ref{4a1f,,Py_complex} PyComplex_AsCComplex (PyObject *op)

Renvoie la valeur du nombre complexe `op' sous la forme d'un @ref{4a1f,,Py_complex} en C.

If `op' is not a Python complex number object but has a @ref{5d1,,__complex__()}
method, this method will first be called to convert `op' to a Python complex
number object.  If @code{__complex__()} is not defined then it falls back to
@ref{9ba,,__float__()}.  If @code{__float__()} is not defined then it falls back
to @ref{707,,__index__()}.

Upon failure, this method returns @ref{4a1f,,Py_complex}
with @ref{4aeb,,real} set to @code{-1.0} and with an exception set, so one
should call @ref{187f,,PyErr_Occurred()} to check for errors.


Modifié dans la version 3.8: Use @ref{707,,__index__()} if available.

@end deffn

@node Objets séquences,Objets conteneurs,Objets numériques,Couche des objets concrets
@anchor{c-api/concrete sequence-objects}@anchor{4af7}@anchor{c-api/concrete sequenceobjects}@anchor{4af8}
@subsection Objets séquences


@geindex object;sequence

Les opérations génériques sur les objets séquences ont été discutées dans le chapitre précédent. Cette section traite des genres spécifiques d'objets séquences qui sont intrinsèques au langage Python.

@c XXX sort out unicode, str, bytes and bytearray

@menu
* Objets bytes: Objets bytes<2>. 
* Objets tableau d'octets:: 
* Objets Unicode et Codecs:: 
* Tuple Objects:: 
* Struct Sequence Objects:: 
* List Objects:: 

@end menu

@node Objets bytes<2>,Objets tableau d'octets,,Objets séquences
@anchor{c-api/bytes doc}@anchor{4af9}@anchor{c-api/bytes bytes-objects}@anchor{4afa}@anchor{c-api/bytes bytesobjects}@anchor{4afb}
@subsubsection Objets `bytes'


These functions raise @ref{522,,TypeError} when expecting a bytes parameter and
called with a non-bytes parameter.

@geindex object;bytes

@geindex PyBytesObject (C type)
@anchor{c-api/bytes c PyBytesObject}@anchor{77c}
@deffn {C Type} type PyBytesObject

This subtype of @ref{32f,,PyObject} represents a Python bytes object.
@end deffn

@geindex PyBytes_Type (C var)
@anchor{c-api/bytes c PyBytes_Type}@anchor{4878}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyBytes_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python bytes type; it
is the same object as @ref{1bd,,bytes} in the Python layer.
@end deffn

@geindex PyBytes_Check (C function)
@anchor{c-api/bytes c PyBytes_Check}@anchor{136b}
@deffn {C Fonction} int PyBytes_Check (PyObject *o)

Return true if the object `o' is a bytes object or an instance of a subtype
of the bytes type.  This function always succeeds.
@end deffn

@geindex PyBytes_CheckExact (C function)
@anchor{c-api/bytes c PyBytes_CheckExact}@anchor{4afc}
@deffn {C Fonction} int PyBytes_CheckExact (PyObject *o)

Return true if the object `o' is a bytes object, but not an instance of a
subtype of the bytes type.  This function always succeeds.
@end deffn

@geindex PyBytes_FromString (C function)
@anchor{c-api/bytes c PyBytes_FromString}@anchor{4876}
@deffn {C Fonction} @ref{32f,,PyObject} *PyBytes_FromString (const char *v)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new bytes object with a copy of the string `v' as value on success,
and @code{NULL} on failure.  The parameter `v' must not be @code{NULL}; it will not be
checked.
@end deffn

@geindex PyBytes_FromStringAndSize (C function)
@anchor{c-api/bytes c PyBytes_FromStringAndSize}@anchor{136c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyBytes_FromStringAndSize (const char *v, Py_ssize_t len)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new bytes object with a copy of the string `v' as value and length
`len' on success, and @code{NULL} on failure.  If `v' is @code{NULL}, the contents of
the bytes object are uninitialized.
@end deffn

@geindex PyBytes_FromFormat (C function)
@anchor{c-api/bytes c PyBytes_FromFormat}@anchor{19b7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyBytes_FromFormat (const char *format, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Take a C @code{printf()}-style `format' string and a variable number of
arguments, calculate the size of the resulting Python bytes object and return
a bytes object with the values formatted into it.  The variable arguments
must be C types and must correspond exactly to the format characters in the
`format' string.  The following format characters are allowed:

@c % XXX: This should be exactly the same as the table in PyErr_Format.

@c % One should just refer to the other.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Caractères de format

@tab

Type

@tab

Comment

@item

@code{%%}

@tab

`n/a'

@tab

The literal % character.

@item

@code{%c}

@tab

`int'

@tab

A single byte,
represented as a C int.

@item

@code{%d}

@tab

`int'

@tab

Equivalent to
@code{printf("%d")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%u}

@tab

@code{unsigned int}

@tab

Equivalent to
@code{printf("%u")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%ld}

@tab

long

@tab

Equivalent to
@code{printf("%ld")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%lu}

@tab

@code{unsigned long}

@tab

Equivalent to
@code{printf("%lu")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%zd}

@tab

@ref{a4e,,Py_ssize_t}

@tab

Equivalent to
@code{printf("%zd")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%zu}

@tab

size_t

@tab

Equivalent to
@code{printf("%zu")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%i}

@tab

`int'

@tab

Equivalent to
@code{printf("%i")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%x}

@tab

`int'

@tab

Equivalent to
@code{printf("%x")}. @footnote{
For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion
flag has effect even when a precision is given.
}

@item

@code{%s}

@tab

const char*

@tab

A null-terminated C character
array.

@item

@code{%p}

@tab

const void*

@tab

The hex representation of a C
pointer. Mostly equivalent to
@code{printf("%p")} except that
it is guaranteed to start with
the literal @code{0x} regardless
of what the platform's
@code{printf} yields.

@end multitable


An unrecognized format character causes all the rest of the format string to be
copied as-is to the result object, and any extra arguments discarded.
@end deffn

@geindex PyBytes_FromFormatV (C function)
@anchor{c-api/bytes c PyBytes_FromFormatV}@anchor{4874}
@deffn {C Fonction} @ref{32f,,PyObject} *PyBytes_FromFormatV (const char *format, va_list vargs)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Identical to @ref{19b7,,PyBytes_FromFormat()} except that it takes exactly two
arguments.
@end deffn

@geindex PyBytes_FromObject (C function)
@anchor{c-api/bytes c PyBytes_FromObject}@anchor{4875}
@deffn {C Fonction} @ref{32f,,PyObject} *PyBytes_FromObject (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the bytes representation of object `o' that implements the buffer
protocol.
@end deffn

@geindex PyBytes_Size (C function)
@anchor{c-api/bytes c PyBytes_Size}@anchor{4877}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyBytes_Size (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Return the length of the bytes in bytes object `o'.
@end deffn

@geindex PyBytes_GET_SIZE (C function)
@anchor{c-api/bytes c PyBytes_GET_SIZE}@anchor{4afd}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyBytes_GET_SIZE (PyObject *o)

Similar to @ref{4877,,PyBytes_Size()}, but without error checking.
@end deffn

@geindex PyBytes_AsString (C function)
@anchor{c-api/bytes c PyBytes_AsString}@anchor{873}
@deffn {C Fonction} char *PyBytes_AsString (PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Return a pointer to the contents of `o'.  The pointer
refers to the internal buffer of `o', which consists of @code{len(o) + 1}
bytes.  The last byte in the buffer is always null, regardless of
whether there are any other null bytes.  The data must not be
modified in any way, unless the object was just created using
@code{PyBytes_FromStringAndSize(NULL, size)}. It must not be deallocated.  If
`o' is not a bytes object at all, @ref{873,,PyBytes_AsString()} returns @code{NULL}
and raises @ref{522,,TypeError}.
@end deffn

@geindex PyBytes_AS_STRING (C function)
@anchor{c-api/bytes c PyBytes_AS_STRING}@anchor{4afe}
@deffn {C Fonction} char *PyBytes_AS_STRING (PyObject *string)

Similar to @ref{873,,PyBytes_AsString()}, but without error checking.
@end deffn

@geindex PyBytes_AsStringAndSize (C function)
@anchor{c-api/bytes c PyBytes_AsStringAndSize}@anchor{4871}
@deffn {C Fonction} int PyBytes_AsStringAndSize (PyObject *obj, char **buffer, Py_ssize_t *length)
` Part of the @ref{53e,,Stable ABI}.'
Return the null-terminated contents of the object `obj'
through the output variables `buffer' and `length'.
Returns @code{0} on success.

If `length' is @code{NULL}, the bytes object
may not contain embedded null bytes;
if it does, the function returns @code{-1} and a @ref{1ff,,ValueError} is raised.

The buffer refers to an internal buffer of `obj', which includes an
additional null byte at the end (not counted in `length').  The data
must not be modified in any way, unless the object was just created using
@code{PyBytes_FromStringAndSize(NULL, size)}.  It must not be deallocated.  If
`obj' is not a bytes object at all, @ref{4871,,PyBytes_AsStringAndSize()}
returns @code{-1} and raises @ref{522,,TypeError}.


Modifié dans la version 3.5: Previously, @ref{522,,TypeError} was raised when embedded null bytes were
encountered in the bytes object.

@end deffn

@geindex PyBytes_Concat (C function)
@anchor{c-api/bytes c PyBytes_Concat}@anchor{4872}
@deffn {C Fonction} void PyBytes_Concat (PyObject **bytes, PyObject *newpart)
` Part of the @ref{53e,,Stable ABI}.'
Create a new bytes object in `*bytes' containing the contents of `newpart'
appended to `bytes'; the caller will own the new reference.  The reference to
the old value of `bytes' will be stolen.  If the new object cannot be
created, the old reference to `bytes' will still be discarded and the value
of `*bytes' will be set to @code{NULL}; the appropriate exception will be set.
@end deffn

@geindex PyBytes_ConcatAndDel (C function)
@anchor{c-api/bytes c PyBytes_ConcatAndDel}@anchor{4873}
@deffn {C Fonction} void PyBytes_ConcatAndDel (PyObject **bytes, PyObject *newpart)
` Part of the @ref{53e,,Stable ABI}.'
Create a new bytes object in `*bytes' containing the contents of `newpart'
appended to `bytes'.  This version releases the @ref{333,,strong reference}
to `newpart' (i.e. decrements its reference count).
@end deffn

@geindex _PyBytes_Resize (C function)
@anchor{c-api/bytes c _PyBytes_Resize}@anchor{15dd}
@deffn {C Fonction} int _PyBytes_Resize (PyObject **bytes, Py_ssize_t newsize)

Resize a bytes object. `newsize' will be the new length of the bytes object.
You can think of it as creating a new bytes object and destroying the old
one, only more efficiently.
Pass the address of an
existing bytes object as an lvalue (it may be written into), and the new size
desired.  On success, `*bytes' holds the resized bytes object and @code{0} is
returned; the address in `*bytes' may differ from its input value.  If the
reallocation fails, the original bytes object at `*bytes' is deallocated,
`*bytes' is set to @code{NULL}, @ref{164b,,MemoryError} is set, and @code{-1} is
returned.
@end deffn

@node Objets tableau d'octets,Objets Unicode et Codecs,Objets bytes<2>,Objets séquences
@anchor{c-api/bytearray doc}@anchor{4aff}@anchor{c-api/bytearray byte-array-objects}@anchor{4b00}@anchor{c-api/bytearray bytearrayobjects}@anchor{4b01}
@subsubsection Objets tableau d'octets


@geindex object;bytearray

@geindex PyByteArrayObject (C type)
@anchor{c-api/bytearray c PyByteArrayObject}@anchor{4b02}
@deffn {C Type} type PyByteArrayObject

Ce sous-type de @ref{32f,,PyObject} représente un objet @code{bytearray} Python.
@end deffn

@geindex PyByteArray_Type (C var)
@anchor{c-api/bytearray c PyByteArray_Type}@anchor{4870}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyByteArray_Type
` Part of the @ref{53e,,Stable ABI}.'
Cette instance de @ref{a93,,PyTypeObject} représente le type Python `bytearray', c'est le même que @ref{528,,bytearray} côté Python.
@end deffn

@menu
* Macros de vérification de type:: 
* Fonctions directes sur l'API:: 
* Macros:: 

@end menu

@node Macros de vérification de type,Fonctions directes sur l'API,,Objets tableau d'octets
@anchor{c-api/bytearray type-check-macros}@anchor{4b03}
@subsubsection Macros de vérification de type


@geindex PyByteArray_Check (C function)
@anchor{c-api/bytearray c PyByteArray_Check}@anchor{4b04}
@deffn {C Fonction} int PyByteArray_Check (PyObject *o)

Renvoie vrai si l'objet `o' est un @code{bytearray} ou une instance d'un sous-type du type @code{bytearray}. Cette méthode réussit toujours.
@end deffn

@geindex PyByteArray_CheckExact (C function)
@anchor{c-api/bytearray c PyByteArray_CheckExact}@anchor{4b05}
@deffn {C Fonction} int PyByteArray_CheckExact (PyObject *o)

Renvoie vrai si l'objet `o' est un @code{bytearray}, mais pas une instance d'un sous-type du type @code{bytearray}. Cette méthode réussit toujours.
@end deffn

@node Fonctions directes sur l'API,Macros,Macros de vérification de type,Objets tableau d'octets
@anchor{c-api/bytearray direct-api-functions}@anchor{4b06}
@subsubsection Fonctions directes sur l'API


@geindex PyByteArray_FromObject (C function)
@anchor{c-api/bytearray c PyByteArray_FromObject}@anchor{136d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyByteArray_FromObject (PyObject *o)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie un nouvel objet `bytearray' depuis n'importe quel objet, `o', qui implémente le @ref{38e,,protocole buffer}.

On failure, return @code{NULL} with an exception set.
@end deffn

@geindex PyByteArray_FromStringAndSize (C function)
@anchor{c-api/bytearray c PyByteArray_FromStringAndSize}@anchor{136e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyByteArray_FromStringAndSize (const char *string, Py_ssize_t len)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a new bytearray object from `string' and its length, `len'.

On failure, return @code{NULL} with an exception set.
@end deffn

@geindex PyByteArray_Concat (C function)
@anchor{c-api/bytearray c PyByteArray_Concat}@anchor{486d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyByteArray_Concat (PyObject *a, PyObject *b)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Concatène les @code{bytearrays} `a' et `b' et renvoie un nouveau @code{bytearray} avec le résultat.

On failure, return @code{NULL} with an exception set.
@end deffn

@geindex PyByteArray_Size (C function)
@anchor{c-api/bytearray c PyByteArray_Size}@anchor{486f}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyByteArray_Size (PyObject *bytearray)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie la taille de `bytearray' après vérification de la présence d'un pointeur @code{NULL}.
@end deffn

@geindex PyByteArray_AsString (C function)
@anchor{c-api/bytearray c PyByteArray_AsString}@anchor{486c}
@deffn {C Fonction} char *PyByteArray_AsString (PyObject *bytearray)
` Part of the @ref{53e,,Stable ABI}.'
Renvoie le contenu de `bytearray' sous forme d'un tableau de caractères, en vérifiant que ce n'est pas un pointeur @code{NULL}. Le tableau renvoyé a toujours un caractère `null' rajouté.
@end deffn

@geindex PyByteArray_Resize (C function)
@anchor{c-api/bytearray c PyByteArray_Resize}@anchor{486e}
@deffn {C Fonction} int PyByteArray_Resize (PyObject *bytearray, Py_ssize_t len)
` Part of the @ref{53e,,Stable ABI}.'
Redimensionne le tampon interne de `bytearray' à la taille `len'.
@end deffn

@node Macros,,Fonctions directes sur l'API,Objets tableau d'octets
@anchor{c-api/bytearray macros}@anchor{4b07}
@subsubsection Macros


Ces macros sont taillées pour la vitesse d'exécution et ne vérifient pas les pointeurs.

@geindex PyByteArray_AS_STRING (C function)
@anchor{c-api/bytearray c PyByteArray_AS_STRING}@anchor{4b08}
@deffn {C Fonction} char *PyByteArray_AS_STRING (PyObject *bytearray)

Similar to @ref{486c,,PyByteArray_AsString()}, but without error checking.
@end deffn

@geindex PyByteArray_GET_SIZE (C function)
@anchor{c-api/bytearray c PyByteArray_GET_SIZE}@anchor{4b09}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyByteArray_GET_SIZE (PyObject *bytearray)

Similar to @ref{486f,,PyByteArray_Size()}, but without error checking.
@end deffn

@node Objets Unicode et Codecs,Tuple Objects,Objets tableau d'octets,Objets séquences
@anchor{c-api/unicode doc}@anchor{117e}@anchor{c-api/unicode unicode-objects-and-codecs}@anchor{4b0a}@anchor{c-api/unicode unicodeobjects}@anchor{4b0b}
@subsubsection Objets Unicode et Codecs


@menu
* Objets Unicode:: 
* Built-in Codecs:: 
* Methods and Slot Functions:: 

@end menu

@node Objets Unicode,Built-in Codecs,,Objets Unicode et Codecs
@anchor{c-api/unicode unicode-objects}@anchor{4b0c}
@subsubsection Objets Unicode


Depuis l'implémentation de 
@geindex Python Enhancement Proposals; PEP 393
PEP 393@footnote{https://peps.python.org/pep-0393/} dans Python 3.3, les objets Unicode utilisent une variété de représentations internes, pour permettre de gérer l'intervalle complet des caractères Unicode en restant efficace en termes de mémoire. Il y a des cas spéciaux pour les chaînes où tous les points de code sont inférieurs à 128, 256, ou 65536 ; sinon, les points de code doivent être inférieurs à 1114112 (qui est l'intervalle Unicode complet).

UTF-8 representation is created on demand and cached in the Unicode object.

@cartouche
@quotation Note 
The @ref{3e4,,Py_UNICODE} representation has been removed since Python 3.12
with deprecated APIs.
See 
@geindex Python Enhancement Proposals; PEP 623
PEP 623@footnote{https://peps.python.org/pep-0623/} for more information.
@end quotation
@end cartouche

@menu
* Type Unicode:: 
* Unicode Character Properties:: 
* Creating and accessing Unicode strings:: 
* Locale Encoding:: 
* File System Encoding:: 
* wchar_t Support:: 

@end menu

@node Type Unicode,Unicode Character Properties,,Objets Unicode
@anchor{c-api/unicode unicode-type}@anchor{4b0d}
@subsubsection Type Unicode


Voici les types d'objets Unicode utilisés pour l'implémentation Unicode en Python :

@geindex Py_UCS4 (C type)
@geindex Py_UCS2 (C type)
@geindex Py_UCS1 (C type)
@anchor{c-api/unicode c Py_UCS4}@anchor{298}
@deffn {C Type} type Py_UCS4
@anchor{c-api/unicode c Py_UCS2}@anchor{1154}
@deffnx {C Type} type Py_UCS2
@anchor{c-api/unicode c Py_UCS1}@anchor{1153}
@deffnx {C Type} type Py_UCS1
` Part of the @ref{53e,,Stable ABI}.'
Voici les `typedefs' pour les types entiers non signés suffisamment large pour contenir des caractères de 32 bits, 16 bits et 8 bits, respectivement. Pour traiter des caractères uniques, utilisez @ref{298,,Py_UCS4}.


Ajouté dans la version 3.3.

@end deffn

@geindex Py_UNICODE (C type)
@anchor{c-api/unicode c Py_UNICODE}@anchor{3e4}
@deffn {C Type} type Py_UNICODE

This is a typedef of @code{wchar_t}, which is a 16-bit type or 32-bit type
depending on the platform.


Modifié dans la version 3.3: Dans les versions précédentes, ceci était un type 16-bit ou un type 32-bit selon que vous choisissiez une version Unicode `narrow' ou `wide' de Python à la compilation.



Deprecated since version 3.13, will be removed in version 3.15.

@end deffn

@geindex PyASCIIObject (C type)
@geindex PyCompactUnicodeObject (C type)
@geindex PyUnicodeObject (C type)
@anchor{c-api/unicode c PyASCIIObject}@anchor{1155}
@deffn {C Type} type PyASCIIObject
@anchor{c-api/unicode c PyCompactUnicodeObject}@anchor{1156}
@deffnx {C Type} type PyCompactUnicodeObject
@anchor{c-api/unicode c PyUnicodeObject}@anchor{77e}
@deffnx {C Type} type PyUnicodeObject

These subtypes of @ref{32f,,PyObject} represent a Python Unicode object.  In
almost all cases, they shouldn't be used directly, since all API functions
that deal with Unicode objects take and return @ref{32f,,PyObject} pointers.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_Type (C var)
@anchor{c-api/unicode c PyUnicode_Type}@anchor{499a}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyUnicode_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python Unicode type.  It
is exposed to Python code as @code{str}.
@end deffn

The following APIs are C macros and static inlined functions for fast checks and
access to internal read-only data of Unicode objects:

@geindex PyUnicode_Check (C function)
@anchor{c-api/unicode c PyUnicode_Check}@anchor{4b0e}
@deffn {C Fonction} int PyUnicode_Check (PyObject *obj)

Return true if the object `obj' is a Unicode object or an instance of a Unicode
subtype.  This function always succeeds.
@end deffn

@geindex PyUnicode_CheckExact (C function)
@anchor{c-api/unicode c PyUnicode_CheckExact}@anchor{4b0f}
@deffn {C Fonction} int PyUnicode_CheckExact (PyObject *obj)

Return true if the object `obj' is a Unicode object, but not an instance of a
subtype.  This function always succeeds.
@end deffn

@geindex PyUnicode_READY (C function)
@anchor{c-api/unicode c PyUnicode_READY}@anchor{3f7}
@deffn {C Fonction} int PyUnicode_READY (PyObject *unicode)

Returns @code{0}. This API is kept only for backward compatibility.


Ajouté dans la version 3.3.



Obsolète depuis la version 3.10: This API does nothing since Python 3.12.

@end deffn

@geindex PyUnicode_GET_LENGTH (C function)
@anchor{c-api/unicode c PyUnicode_GET_LENGTH}@anchor{8a1}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_GET_LENGTH (PyObject *unicode)

Return the length of the Unicode string, in code points.  `unicode' has to be a
Unicode object in the "canonical" representation (not checked).


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_1BYTE_DATA (C function)
@geindex PyUnicode_2BYTE_DATA (C function)
@geindex PyUnicode_4BYTE_DATA (C function)
@anchor{c-api/unicode c PyUnicode_1BYTE_DATA}@anchor{115a}
@deffn {C Fonction} @ref{1153,,Py_UCS1} *PyUnicode_1BYTE_DATA (PyObject *unicode)
@anchor{c-api/unicode c PyUnicode_2BYTE_DATA}@anchor{115b}
@deffnx {C Fonction} @ref{1154,,Py_UCS2} *PyUnicode_2BYTE_DATA (PyObject *unicode)
@anchor{c-api/unicode c PyUnicode_4BYTE_DATA}@anchor{115c}
@deffnx {C Fonction} @ref{298,,Py_UCS4} *PyUnicode_4BYTE_DATA (PyObject *unicode)

Return a pointer to the canonical representation cast to UCS1, UCS2 or UCS4
integer types for direct character access.  No checks are performed if the
canonical representation has the correct character size; use
@ref{115d,,PyUnicode_KIND()} to select the right function.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_1BYTE_KIND (C macro)
@geindex PyUnicode_2BYTE_KIND (C macro)
@geindex PyUnicode_4BYTE_KIND (C macro)
@anchor{c-api/unicode c PyUnicode_1BYTE_KIND}@anchor{115e}
@deffn {C Macro} PyUnicode_1BYTE_KIND
@anchor{c-api/unicode c PyUnicode_2BYTE_KIND}@anchor{115f}
@deffnx {C Macro} PyUnicode_2BYTE_KIND
@anchor{c-api/unicode c PyUnicode_4BYTE_KIND}@anchor{1160}
@deffnx {C Macro} PyUnicode_4BYTE_KIND

Return values of the @ref{115d,,PyUnicode_KIND()} macro.


Ajouté dans la version 3.3.



Modifié dans la version 3.12: @code{PyUnicode_WCHAR_KIND} has been removed.

@end deffn

@geindex PyUnicode_KIND (C function)
@anchor{c-api/unicode c PyUnicode_KIND}@anchor{115d}
@deffn {C Fonction} int PyUnicode_KIND (PyObject *unicode)

Return one of the PyUnicode kind constants (see above) that indicate how many
bytes per character this Unicode object uses to store its data.  `unicode' has to
be a Unicode object in the "canonical" representation (not checked).


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_DATA (C function)
@anchor{c-api/unicode c PyUnicode_DATA}@anchor{1159}
@deffn {C Fonction} void *PyUnicode_DATA (PyObject *unicode)

Return a void pointer to the raw Unicode buffer.  `unicode' has to be a Unicode
object in the "canonical" representation (not checked).


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_WRITE (C function)
@anchor{c-api/unicode c PyUnicode_WRITE}@anchor{1163}
@deffn {C Fonction} void PyUnicode_WRITE (int kind, void *data, Py_ssize_t index, Py_UCS4 value)

Write into a canonical representation `data' (as obtained with
@ref{1159,,PyUnicode_DATA()}).  This function performs no sanity checks, and is
intended for usage in loops.  The caller should cache the `kind' value and
`data' pointer as obtained from other calls.  `index' is the index in
the string (starts at 0) and `value' is the new code point value which should
be written to that location.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_READ (C function)
@anchor{c-api/unicode c PyUnicode_READ}@anchor{1161}
@deffn {C Fonction} @ref{298,,Py_UCS4} PyUnicode_READ (int kind, void *data, Py_ssize_t index)

Read a code point from a canonical representation `data' (as obtained with
@ref{1159,,PyUnicode_DATA()}).  No checks or ready calls are performed.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_READ_CHAR (C function)
@anchor{c-api/unicode c PyUnicode_READ_CHAR}@anchor{1162}
@deffn {C Fonction} @ref{298,,Py_UCS4} PyUnicode_READ_CHAR (PyObject *unicode, Py_ssize_t index)

Read a character from a Unicode object `unicode', which must be in the "canonical"
representation.  This is less efficient than @ref{1161,,PyUnicode_READ()} if you
do multiple consecutive reads.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_MAX_CHAR_VALUE (C function)
@anchor{c-api/unicode c PyUnicode_MAX_CHAR_VALUE}@anchor{1164}
@deffn {C Fonction} @ref{298,,Py_UCS4} PyUnicode_MAX_CHAR_VALUE (PyObject *unicode)

Return the maximum code point that is suitable for creating another string
based on `unicode', which must be in the "canonical" representation.  This is
always an approximation but more efficient than iterating over the string.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_IsIdentifier (C function)
@anchor{c-api/unicode c PyUnicode_IsIdentifier}@anchor{192b}
@deffn {C Fonction} int PyUnicode_IsIdentifier (PyObject *unicode)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} if the string is a valid identifier according to the language
definition, section @ref{1e1a,,Identifiants et mots-clés}. Return @code{0} otherwise.


Modifié dans la version 3.9: The function does not call @ref{970,,Py_FatalError()} anymore if the string
is not ready.

@end deffn

@node Unicode Character Properties,Creating and accessing Unicode strings,Type Unicode,Objets Unicode
@anchor{c-api/unicode unicode-character-properties}@anchor{4b10}
@subsubsection Unicode Character Properties


Unicode provides many different character properties. The most often needed ones
are available through these macros which are mapped to C functions depending on
the Python configuration.

@geindex Py_UNICODE_ISSPACE (C function)
@anchor{c-api/unicode c Py_UNICODE_ISSPACE}@anchor{1893}
@deffn {C Fonction} int Py_UNICODE_ISSPACE (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a whitespace character.
@end deffn

@geindex Py_UNICODE_ISLOWER (C function)
@anchor{c-api/unicode c Py_UNICODE_ISLOWER}@anchor{4b11}
@deffn {C Fonction} int Py_UNICODE_ISLOWER (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a lowercase character.
@end deffn

@geindex Py_UNICODE_ISUPPER (C function)
@anchor{c-api/unicode c Py_UNICODE_ISUPPER}@anchor{4b12}
@deffn {C Fonction} int Py_UNICODE_ISUPPER (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is an uppercase character.
@end deffn

@geindex Py_UNICODE_ISTITLE (C function)
@anchor{c-api/unicode c Py_UNICODE_ISTITLE}@anchor{4b13}
@deffn {C Fonction} int Py_UNICODE_ISTITLE (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a titlecase character.
@end deffn

@geindex Py_UNICODE_ISLINEBREAK (C function)
@anchor{c-api/unicode c Py_UNICODE_ISLINEBREAK}@anchor{4b14}
@deffn {C Fonction} int Py_UNICODE_ISLINEBREAK (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a linebreak character.
@end deffn

@geindex Py_UNICODE_ISDECIMAL (C function)
@anchor{c-api/unicode c Py_UNICODE_ISDECIMAL}@anchor{4b15}
@deffn {C Fonction} int Py_UNICODE_ISDECIMAL (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a decimal character.
@end deffn

@geindex Py_UNICODE_ISDIGIT (C function)
@anchor{c-api/unicode c Py_UNICODE_ISDIGIT}@anchor{4b16}
@deffn {C Fonction} int Py_UNICODE_ISDIGIT (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a digit character.
@end deffn

@geindex Py_UNICODE_ISNUMERIC (C function)
@anchor{c-api/unicode c Py_UNICODE_ISNUMERIC}@anchor{4b17}
@deffn {C Fonction} int Py_UNICODE_ISNUMERIC (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a numeric character.
@end deffn

@geindex Py_UNICODE_ISALPHA (C function)
@anchor{c-api/unicode c Py_UNICODE_ISALPHA}@anchor{4b18}
@deffn {C Fonction} int Py_UNICODE_ISALPHA (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is an alphabetic character.
@end deffn

@geindex Py_UNICODE_ISALNUM (C function)
@anchor{c-api/unicode c Py_UNICODE_ISALNUM}@anchor{4b19}
@deffn {C Fonction} int Py_UNICODE_ISALNUM (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is an alphanumeric character.
@end deffn

@geindex Py_UNICODE_ISPRINTABLE (C function)
@anchor{c-api/unicode c Py_UNICODE_ISPRINTABLE}@anchor{4b1a}
@deffn {C Fonction} int Py_UNICODE_ISPRINTABLE (Py_UCS4 ch)

Return @code{1} or @code{0} depending on whether `ch' is a printable character.
Nonprintable characters are those characters defined in the Unicode character
database as "Other" or "Separator", excepting the ASCII space (0x20) which is
considered printable.  (Note that printable characters in this context are
those which should not be escaped when @ref{7e7,,repr()} is invoked on a string.
It has no bearing on the handling of strings written to @ref{ac4,,sys.stdout} or
@ref{926,,sys.stderr}.)
@end deffn

These APIs can be used for fast direct character conversions:

@geindex Py_UNICODE_TOLOWER (C function)
@anchor{c-api/unicode c Py_UNICODE_TOLOWER}@anchor{4b1b}
@deffn {C Fonction} @ref{298,,Py_UCS4} Py_UNICODE_TOLOWER (Py_UCS4 ch)

Return the character `ch' converted to lower case.
@end deffn

@geindex Py_UNICODE_TOUPPER (C function)
@anchor{c-api/unicode c Py_UNICODE_TOUPPER}@anchor{4b1c}
@deffn {C Fonction} @ref{298,,Py_UCS4} Py_UNICODE_TOUPPER (Py_UCS4 ch)

Return the character `ch' converted to upper case.
@end deffn

@geindex Py_UNICODE_TOTITLE (C function)
@anchor{c-api/unicode c Py_UNICODE_TOTITLE}@anchor{4b1d}
@deffn {C Fonction} @ref{298,,Py_UCS4} Py_UNICODE_TOTITLE (Py_UCS4 ch)

Return the character `ch' converted to title case.
@end deffn

@geindex Py_UNICODE_TODECIMAL (C function)
@anchor{c-api/unicode c Py_UNICODE_TODECIMAL}@anchor{4b1e}
@deffn {C Fonction} int Py_UNICODE_TODECIMAL (Py_UCS4 ch)

Return the character `ch' converted to a decimal positive integer.  Return
@code{-1} if this is not possible.  This function does not raise exceptions.
@end deffn

@geindex Py_UNICODE_TODIGIT (C function)
@anchor{c-api/unicode c Py_UNICODE_TODIGIT}@anchor{4b1f}
@deffn {C Fonction} int Py_UNICODE_TODIGIT (Py_UCS4 ch)

Return the character `ch' converted to a single digit integer. Return @code{-1} if
this is not possible.  This function does not raise exceptions.
@end deffn

@geindex Py_UNICODE_TONUMERIC (C function)
@anchor{c-api/unicode c Py_UNICODE_TONUMERIC}@anchor{4b20}
@deffn {C Fonction} double Py_UNICODE_TONUMERIC (Py_UCS4 ch)

Return the character `ch' converted to a double. Return @code{-1.0} if this is not
possible.  This function does not raise exceptions.
@end deffn

These APIs can be used to work with surrogates:

@geindex Py_UNICODE_IS_SURROGATE (C function)
@anchor{c-api/unicode c Py_UNICODE_IS_SURROGATE}@anchor{4b21}
@deffn {C Fonction} int Py_UNICODE_IS_SURROGATE (Py_UCS4 ch)

Check if `ch' is a surrogate (@code{0xD800 <= ch <= 0xDFFF}).
@end deffn

@geindex Py_UNICODE_IS_HIGH_SURROGATE (C function)
@anchor{c-api/unicode c Py_UNICODE_IS_HIGH_SURROGATE}@anchor{4b22}
@deffn {C Fonction} int Py_UNICODE_IS_HIGH_SURROGATE (Py_UCS4 ch)

Check if `ch' is a high surrogate (@code{0xD800 <= ch <= 0xDBFF}).
@end deffn

@geindex Py_UNICODE_IS_LOW_SURROGATE (C function)
@anchor{c-api/unicode c Py_UNICODE_IS_LOW_SURROGATE}@anchor{4b23}
@deffn {C Fonction} int Py_UNICODE_IS_LOW_SURROGATE (Py_UCS4 ch)

Check if `ch' is a low surrogate (@code{0xDC00 <= ch <= 0xDFFF}).
@end deffn

@geindex Py_UNICODE_JOIN_SURROGATES (C function)
@anchor{c-api/unicode c Py_UNICODE_JOIN_SURROGATES}@anchor{4b24}
@deffn {C Fonction} @ref{298,,Py_UCS4} Py_UNICODE_JOIN_SURROGATES (Py_UCS4 high, Py_UCS4 low)

Join two surrogate code points and return a single @ref{298,,Py_UCS4} value.
`high' and `low' are respectively the leading and trailing surrogates in a
surrogate pair. `high' must be in the range [0xD800; 0xDBFF] and `low' must
be in the range [0xDC00; 0xDFFF].
@end deffn

@node Creating and accessing Unicode strings,Locale Encoding,Unicode Character Properties,Objets Unicode
@anchor{c-api/unicode creating-and-accessing-unicode-strings}@anchor{4b25}
@subsubsection Creating and accessing Unicode strings


To create Unicode objects and access their basic sequence properties, use these
APIs:

@geindex PyUnicode_New (C function)
@anchor{c-api/unicode c PyUnicode_New}@anchor{898}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_New (Py_ssize_t size, Py_UCS4 maxchar)
`Valeur de retour : nouvelle référence.'
Create a new Unicode object.  `maxchar' should be the true maximum code point
to be placed in the string.  As an approximation, it can be rounded up to the
nearest value in the sequence 127, 255, 65535, 1114111.

This is the recommended way to allocate a new Unicode object.  Objects
created using this function are not resizable.

On error, set an exception and return @code{NULL}.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_FromKindAndData (C function)
@anchor{c-api/unicode c PyUnicode_FromKindAndData}@anchor{1157}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromKindAndData (int kind, const void *buffer, Py_ssize_t size)
`Valeur de retour : nouvelle référence.'
Create a new Unicode object with the given `kind' (possible values are
@ref{115e,,PyUnicode_1BYTE_KIND} etc., as returned by
@ref{115d,,PyUnicode_KIND()}).  The `buffer' must point to an array of `size'
units of 1, 2 or 4 bytes per character, as given by the kind.

If necessary, the input `buffer' is copied and transformed into the
canonical representation.  For example, if the `buffer' is a UCS4 string
(@ref{1160,,PyUnicode_4BYTE_KIND}) and it consists only of codepoints in
the UCS1 range, it will be transformed into UCS1
(@ref{115e,,PyUnicode_1BYTE_KIND}).


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_FromStringAndSize (C function)
@anchor{c-api/unicode c PyUnicode_FromStringAndSize}@anchor{4994}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromStringAndSize (const char *str, Py_ssize_t size)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object from the char buffer `str'.  The bytes will be
interpreted as being UTF-8 encoded.  The buffer is copied into the new
object.
The return value might be a shared object, i.e. modification of the data is
not allowed.

This function raises @ref{561,,SystemError} when:


@itemize *

@item 
`size' < 0,

@item 
`str' is @code{NULL} and `size' > 0
@end itemize


Modifié dans la version 3.12: `str' == @code{NULL} with `size' > 0 is not allowed anymore.

@end deffn

@geindex PyUnicode_FromString (C function)
@anchor{c-api/unicode c PyUnicode_FromString}@anchor{4832}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromString (const char *str)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object from a UTF-8 encoded null-terminated char buffer
`str'.
@end deffn

@geindex PyUnicode_FromFormat (C function)
@anchor{c-api/unicode c PyUnicode_FromFormat}@anchor{380}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromFormat (const char *format, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Take a C @code{printf()}-style `format' string and a variable number of
arguments, calculate the size of the resulting Python Unicode string and return
a string with the values formatted into it.  The variable arguments must be C
types and must correspond exactly to the format characters in the `format'
ASCII-encoded string.

Un indicateur de conversion contient deux ou plusieurs caractères et comporte les éléments suivants, qui doivent apparaître dans cet ordre :


@enumerate 

@item 
le caractère @code{'%'}, qui marque le début du marqueur ;

@item 
des indications de conversion, facultatives, qui affectent le résultat de certains types de conversion ;

@item 
Minimum field width (optional).
If specified as an @code{'*'} (asterisk), the actual width is given in the
next argument, which must be of type int, and the object to
convert comes after the minimum field width and optional precision.

@item 
Precision (optional), given as a @code{'.'} (dot) followed by the precision.
If specified as @code{'*'} (an asterisk), the actual precision is given in
the next argument, which must be of type int, and the value to
convert comes after the precision.

@item 
modificateur de longueur (facultatif) ;

@item 
type de conversion.
@end enumerate

Les caractères indicateurs de conversion sont :


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@item

@code{0}

@tab

Les valeurs numériques converties sont complétées de zéros.

@item

@code{-}

@tab

The converted value is left adjusted (overrides the @code{0}
flag if both are given).

@end multitable


The length modifiers for following integer conversions (@code{d}, @code{i},
@code{o}, @code{u}, @code{x}, or @code{X}) specify the type of the argument
(int by default):


@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Modifier

@tab

Types

@item

@code{l}

@tab

long or unsigned long

@item

@code{ll}

@tab

long long or unsigned long long

@item

@code{j}

@tab

@code{intmax_t} or @code{uintmax_t}

@item

@code{z}

@tab

@code{size_t} or @code{ssize_t}

@item

@code{t}

@tab

@code{ptrdiff_t}

@end multitable


The length modifier @code{l} for following conversions @code{s} or @code{V} specify
that the type of the argument is const wchar_t*.

The conversion specifiers are:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Conversion Specifier

@tab

Type

@tab

Comment

@item

@code{%}

@tab

`n/a'

@tab

The literal @code{%} character.

@item

@code{d}, @code{i}

@tab

Specified by the length modifier

@tab

The decimal representation of a signed C integer.

@item

@code{u}

@tab

Specified by the length modifier

@tab

The decimal representation of an unsigned C integer.

@item

@code{o}

@tab

Specified by the length modifier

@tab

The octal representation of an unsigned C integer.

@item

@code{x}

@tab

Specified by the length modifier

@tab

The hexadecimal representation of an unsigned C integer (lowercase).

@item

@code{X}

@tab

Specified by the length modifier

@tab

The hexadecimal representation of an unsigned C integer (uppercase).

@item

@code{c}

@tab

int

@tab

A single character.

@item

@code{s}

@tab

const char* or const wchar_t*

@tab

A null-terminated C character array.

@item

@code{p}

@tab

const void*

@tab

The hex representation of a C  pointer.
Mostly equivalent to @code{printf("%p")} except that it is guaranteed to
start with the literal @code{0x} regardless of what the platform's
@code{printf} yields.

@item

@code{A}

@tab

@ref{32f,,PyObject}*

@tab

The result of calling @ref{139d,,ascii()}.

@item

@code{U}

@tab

@ref{32f,,PyObject}*

@tab

A Unicode object.

@item

@code{V}

@tab

@ref{32f,,PyObject}*, const char* or const wchar_t*

@tab

A Unicode object (which may be @code{NULL}) and a null-terminated
C character array as a second parameter (which will be used,
if the first parameter is @code{NULL}).

@item

@code{S}

@tab

@ref{32f,,PyObject}*

@tab

The result of calling @ref{1019,,PyObject_Str()}.

@item

@code{R}

@tab

@ref{32f,,PyObject}*

@tab

The result of calling @ref{1018,,PyObject_Repr()}.

@item

@code{T}

@tab

@ref{32f,,PyObject}*

@tab

Get the fully qualified name of an object type;
call @ref{369,,PyType_GetFullyQualifiedName()}.

@item

@code{#T}

@tab

@ref{32f,,PyObject}*

@tab

Similar to @code{T} format, but use a colon (@code{:}) as separator between
the module name and the qualified name.

@item

@code{N}

@tab

@ref{a93,,PyTypeObject}*

@tab

Get the fully qualified name of a type;
call @ref{369,,PyType_GetFullyQualifiedName()}.

@item

@code{#N}

@tab

@ref{a93,,PyTypeObject}*

@tab

Similar to @code{N} format, but use a colon (@code{:}) as separator between
the module name and the qualified name.

@end multitable


@cartouche
@quotation Note 
The width formatter unit is number of characters rather than bytes.
The precision formatter unit is number of bytes or @code{wchar_t}
items (if the length modifier @code{l} is used) for @code{"%s"} and
@code{"%V"} (if the @code{PyObject*} argument is @code{NULL}), and a number of
characters for @code{"%A"}, @code{"%U"}, @code{"%S"}, @code{"%R"} and @code{"%V"}
(if the @code{PyObject*} argument is not @code{NULL}).
@end quotation
@end cartouche

@cartouche
@quotation Note 
Unlike to C @code{printf()} the @code{0} flag has effect even when
a precision is given for integer conversions (@code{d}, @code{i}, @code{u}, @code{o},
@code{x}, or @code{X}).
@end quotation
@end cartouche


Modifié dans la version 3.2: Support for @code{"%lld"} and @code{"%llu"} added.



Modifié dans la version 3.3: Support for @code{"%li"}, @code{"%lli"} and @code{"%zi"} added.



Modifié dans la version 3.4: Support width and precision formatter for @code{"%s"}, @code{"%A"}, @code{"%U"},
@code{"%V"}, @code{"%S"}, @code{"%R"} added.



Modifié dans la version 3.12: Support for conversion specifiers @code{o} and @code{X}.
Support for length modifiers @code{j} and @code{t}.
Length modifiers are now applied to all integer conversions.
Length modifier @code{l} is now applied to conversion specifiers @code{s} and @code{V}.
Support for variable width and precision @code{*}.
Support for flag @code{-}.

An unrecognized format character now sets a @ref{561,,SystemError}.
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.



Modifié dans la version 3.13: Support for @code{%T}, @code{%#T}, @code{%N} and @code{%#N} formats added.

@end deffn

@geindex PyUnicode_FromFormatV (C function)
@anchor{c-api/unicode c PyUnicode_FromFormatV}@anchor{560}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromFormatV (const char *format, va_list vargs)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Identical to @ref{380,,PyUnicode_FromFormat()} except that it takes exactly two
arguments.
@end deffn

@geindex PyUnicode_FromObject (C function)
@anchor{c-api/unicode c PyUnicode_FromObject}@anchor{4993}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromObject (PyObject *obj)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Copy an instance of a Unicode subtype to a new true Unicode object if
necessary. If `obj' is already a true Unicode object (not a subtype),
return a new @ref{333,,strong reference} to the object.

Objects other than Unicode or its subtypes will cause a @ref{522,,TypeError}.
@end deffn

@geindex PyUnicode_FromEncodedObject (C function)
@anchor{c-api/unicode c PyUnicode_FromEncodedObject}@anchor{4992}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromEncodedObject (PyObject *obj, const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Decode an encoded object `obj' to a Unicode object.

@ref{1bd,,bytes}, @ref{528,,bytearray} and other
@ref{d1b,,bytes-like objects}
are decoded according to the given `encoding' and using the error handling
defined by `errors'. Both can be @code{NULL} to have the interface use the default
values (see @ref{4b26,,Built-in Codecs} for details).

All other objects, including Unicode objects, cause a @ref{522,,TypeError} to be
set.

The API returns @code{NULL} if there was an error.  The caller is responsible for
decref'ing the returned objects.
@end deffn

@geindex PyUnicode_GetLength (C function)
@anchor{c-api/unicode c PyUnicode_GetLength}@anchor{8a0}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_GetLength (PyObject *unicode)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return the length of the Unicode object, in code points.

On error, set an exception and return @code{-1}.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_CopyCharacters (C function)
@anchor{c-api/unicode c PyUnicode_CopyCharacters}@anchor{8a2}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_CopyCharacters (PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)

Copy characters from one Unicode object into another.  This function performs
character conversion when necessary and falls back to @code{memcpy()} if
possible.  Returns @code{-1} and sets an exception on error, otherwise returns
the number of copied characters.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_Fill (C function)
@anchor{c-api/unicode c PyUnicode_Fill}@anchor{116d}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_Fill (PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)

Fill a string with a character: write `fill_char' into
@code{unicode[start:start+length]}.

Fail if `fill_char' is bigger than the string maximum character, or if the
string has more than 1 reference.

Return the number of written character, or return @code{-1} and raise an
exception on error.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_WriteChar (C function)
@anchor{c-api/unicode c PyUnicode_WriteChar}@anchor{1152}
@deffn {C Fonction} int PyUnicode_WriteChar (PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Write a character to a string.  The string must have been created through
@ref{898,,PyUnicode_New()}.  Since Unicode strings are supposed to be immutable,
the string must not be shared, or have been hashed yet.

This function checks that `unicode' is a Unicode object, that the index is
not out of bounds, and that the object can be modified safely (i.e. that it
its reference count is one).

Return @code{0} on success, @code{-1} on error with an exception set.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_ReadChar (C function)
@anchor{c-api/unicode c PyUnicode_ReadChar}@anchor{1151}
@deffn {C Fonction} @ref{298,,Py_UCS4} PyUnicode_ReadChar (PyObject *unicode, Py_ssize_t index)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Read a character from a string.  This function checks that `unicode' is a
Unicode object and the index is not out of bounds, in contrast to
@ref{1162,,PyUnicode_READ_CHAR()}, which performs no error checking.

Return character on success, @code{-1} on error with an exception set.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_Substring (C function)
@anchor{c-api/unicode c PyUnicode_Substring}@anchor{8a3}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Substring (PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return a substring of `unicode', from character index `start' (included) to
character index `end' (excluded).  Negative indices are not supported.
On error, set an exception and return @code{NULL}.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_AsUCS4 (C function)
@anchor{c-api/unicode c PyUnicode_AsUCS4}@anchor{1158}
@deffn {C Fonction} @ref{298,,Py_UCS4} *PyUnicode_AsUCS4 (PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Copy the string `unicode' into a UCS4 buffer, including a null character, if
`copy_null' is set.  Returns @code{NULL} and sets an exception on error (in
particular, a @ref{561,,SystemError} if `buflen' is smaller than the length of
`unicode').  `buffer' is returned on success.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_AsUCS4Copy (C function)
@anchor{c-api/unicode c PyUnicode_AsUCS4Copy}@anchor{8a8}
@deffn {C Fonction} @ref{298,,Py_UCS4} *PyUnicode_AsUCS4Copy (PyObject *unicode)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Copy the string `unicode' into a new UCS4 buffer that is allocated using
@ref{c54,,PyMem_Malloc()}.  If this fails, @code{NULL} is returned with a
@ref{164b,,MemoryError} set.  The returned buffer always has an extra
null code point appended.


Ajouté dans la version 3.3.

@end deffn

@node Locale Encoding,File System Encoding,Creating and accessing Unicode strings,Objets Unicode
@anchor{c-api/unicode locale-encoding}@anchor{4b27}
@subsubsection Locale Encoding


The current locale encoding can be used to decode text from the operating
system.

@geindex PyUnicode_DecodeLocaleAndSize (C function)
@anchor{c-api/unicode c PyUnicode_DecodeLocaleAndSize}@anchor{bb7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeLocaleAndSize (const char *str, Py_ssize_t length, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Decode a string from UTF-8 on Android and VxWorks, or from the current
locale encoding on other platforms. The supported
error handlers are @code{"strict"} and @code{"surrogateescape"}
(
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/}). The decoder uses @code{"strict"} error handler if
`errors' is @code{NULL}.  `str' must end with a null character but
cannot contain embedded null characters.

Use @ref{4982,,PyUnicode_DecodeFSDefaultAndSize()} to decode a string from
the @ref{525,,filesystem encoding and error handler}.

This function ignores the @ref{641,,Python UTF-8 Mode}.


@subsubheading Voir aussi


The @ref{bb5,,Py_DecodeLocale()} function.



Ajouté dans la version 3.3.



Modifié dans la version 3.7: The function now also uses the current locale encoding for the
@code{surrogateescape} error handler, except on Android. Previously, @ref{bb5,,Py_DecodeLocale()}
was used for the @code{surrogateescape}, and the current locale encoding was
used for @code{strict}.

@end deffn

@geindex PyUnicode_DecodeLocale (C function)
@anchor{c-api/unicode c PyUnicode_DecodeLocale}@anchor{4984}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeLocale (const char *str, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Similar to @ref{bb7,,PyUnicode_DecodeLocaleAndSize()}, but compute the string
length using @code{strlen()}.


Ajouté dans la version 3.3.

@end deffn

@geindex PyUnicode_EncodeLocale (C function)
@anchor{c-api/unicode c PyUnicode_EncodeLocale}@anchor{bb8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_EncodeLocale (PyObject *unicode, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Encode a Unicode object to UTF-8 on Android and VxWorks, or to the current
locale encoding on other platforms. The
supported error handlers are @code{"strict"} and @code{"surrogateescape"}
(
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/}). The encoder uses @code{"strict"} error handler if
`errors' is @code{NULL}. Return a @ref{1bd,,bytes} object. `unicode' cannot
contain embedded null characters.

Use @ref{19df,,PyUnicode_EncodeFSDefault()} to encode a string to the
@ref{525,,filesystem encoding and error handler}.

This function ignores the @ref{641,,Python UTF-8 Mode}.


@subsubheading Voir aussi


The @ref{bb6,,Py_EncodeLocale()} function.



Ajouté dans la version 3.3.



Modifié dans la version 3.7: The function now also uses the current locale encoding for the
@code{surrogateescape} error handler, except on Android. Previously,
@ref{bb6,,Py_EncodeLocale()}
was used for the @code{surrogateescape}, and the current locale encoding was
used for @code{strict}.

@end deffn

@node File System Encoding,wchar_t Support,Locale Encoding,Objets Unicode
@anchor{c-api/unicode file-system-encoding}@anchor{4b28}
@subsubsection File System Encoding


Functions encoding to and decoding from the @ref{525,,filesystem encoding and error handler} (
@geindex Python Enhancement Proposals; PEP 383
PEP 383@footnote{https://peps.python.org/pep-0383/} and 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/}).

To encode file names to @ref{1bd,,bytes} during argument parsing, the @code{"O&"}
converter should be used, passing @ref{d07,,PyUnicode_FSConverter()} as the
conversion function:

@geindex PyUnicode_FSConverter (C function)
@anchor{c-api/unicode c PyUnicode_FSConverter}@anchor{d07}
@deffn {C Fonction} int PyUnicode_FSConverter (PyObject *obj, void *result)
` Part of the @ref{53e,,Stable ABI}.'
ParseTuple converter: encode @ref{435,,str} objects -- obtained directly or
through the @ref{c3f,,os.PathLike} interface -- to @ref{1bd,,bytes} using
@ref{19df,,PyUnicode_EncodeFSDefault()}; @ref{1bd,,bytes} objects are output as-is.
`result' must be a @ref{77c,,PyBytesObject}* which must be released when it is
no longer used.


Ajouté dans la version 3.1.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

To decode file names to @ref{435,,str} during argument parsing, the @code{"O&"}
converter should be used, passing @ref{563,,PyUnicode_FSDecoder()} as the
conversion function:

@geindex PyUnicode_FSDecoder (C function)
@anchor{c-api/unicode c PyUnicode_FSDecoder}@anchor{563}
@deffn {C Fonction} int PyUnicode_FSDecoder (PyObject *obj, void *result)
` Part of the @ref{53e,,Stable ABI}.'
ParseTuple converter: decode @ref{1bd,,bytes} objects -- obtained either
directly or indirectly through the @ref{c3f,,os.PathLike} interface -- to
@ref{435,,str} using @ref{4982,,PyUnicode_DecodeFSDefaultAndSize()}; @ref{435,,str}
objects are output as-is. `result' must be a @ref{77e,,PyUnicodeObject}* which
must be released when it is no longer used.


Ajouté dans la version 3.2.



Modifié dans la version 3.6: Accepte un @ref{29d,,path-like object}.

@end deffn

@geindex PyUnicode_DecodeFSDefaultAndSize (C function)
@anchor{c-api/unicode c PyUnicode_DecodeFSDefaultAndSize}@anchor{4982}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeFSDefaultAndSize (const char *str, Py_ssize_t size)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Decode a string from the @ref{525,,filesystem encoding and error handler}.

If you need to decode a string from the current locale encoding, use
@ref{bb7,,PyUnicode_DecodeLocaleAndSize()}.


@subsubheading Voir aussi


The @ref{bb5,,Py_DecodeLocale()} function.



Modifié dans la version 3.6: The @ref{525,,filesystem error handler} is now used.

@end deffn

@geindex PyUnicode_DecodeFSDefault (C function)
@anchor{c-api/unicode c PyUnicode_DecodeFSDefault}@anchor{16a4}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeFSDefault (const char *str)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Decode a null-terminated string from the @ref{525,,filesystem encoding and error handler}.

If the string length is known, use
@ref{4982,,PyUnicode_DecodeFSDefaultAndSize()}.


Modifié dans la version 3.6: The @ref{525,,filesystem error handler} is now used.

@end deffn

@geindex PyUnicode_EncodeFSDefault (C function)
@anchor{c-api/unicode c PyUnicode_EncodeFSDefault}@anchor{19df}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_EncodeFSDefault (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object to the @ref{525,,filesystem encoding and error handler}, and return @ref{1bd,,bytes}. Note that the resulting @ref{1bd,,bytes}
object can contain null bytes.

If you need to encode a string to the current locale encoding, use
@ref{bb8,,PyUnicode_EncodeLocale()}.


@subsubheading Voir aussi


The @ref{bb6,,Py_EncodeLocale()} function.



Ajouté dans la version 3.2.



Modifié dans la version 3.6: The @ref{525,,filesystem error handler} is now used.

@end deffn

@node wchar_t Support,,File System Encoding,Objets Unicode
@anchor{c-api/unicode wchar-t-support}@anchor{4b29}
@subsubsection wchar_t Support


@code{wchar_t} support for platforms which support it:

@geindex PyUnicode_FromWideChar (C function)
@anchor{c-api/unicode c PyUnicode_FromWideChar}@anchor{116c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_FromWideChar (const wchar_t *wstr, Py_ssize_t size)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object from the @code{wchar_t} buffer `wstr' of the given `size'.
Passing @code{-1} as the `size' indicates that the function must itself compute the length,
using @code{wcslen()}.
Return @code{NULL} on failure.
@end deffn

@geindex PyUnicode_AsWideChar (C function)
@anchor{c-api/unicode c PyUnicode_AsWideChar}@anchor{19e5}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_AsWideChar (PyObject *unicode, wchar_t *wstr, Py_ssize_t size)
` Part of the @ref{53e,,Stable ABI}.'
Copy the Unicode object contents into the @code{wchar_t} buffer `wstr'.  At most
`size' @code{wchar_t} characters are copied (excluding a possibly trailing
null termination character).  Return the number of @code{wchar_t} characters
copied or @code{-1} in case of an error.

When `wstr' is @code{NULL}, instead return the `size' that would be required
to store all of `unicode' including a terminating null.

Note that the resulting wchar_t*
string may or may not be null-terminated.  It is the responsibility of the caller
to make sure that the wchar_t* string is null-terminated in case this is
required by the application. Also, note that the wchar_t* string
might contain null characters, which would cause the string to be truncated
when used with most C functions.
@end deffn

@geindex PyUnicode_AsWideCharString (C function)
@anchor{c-api/unicode c PyUnicode_AsWideCharString}@anchor{8a9}
@deffn {C Fonction} wchar_t *PyUnicode_AsWideCharString (PyObject *unicode, Py_ssize_t *size)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Convert the Unicode object to a wide character string. The output string
always ends with a null character. If `size' is not @code{NULL}, write the number
of wide characters (excluding the trailing null termination character) into
`*size'. Note that the resulting @code{wchar_t} string might contain
null characters, which would cause the string to be truncated when used with
most C functions. If `size' is @code{NULL} and the wchar_t* string
contains null characters a @ref{1ff,,ValueError} is raised.

Returns a buffer allocated by @ref{14db,,PyMem_New} (use
@ref{13f9,,PyMem_Free()} to free it) on success. On error, returns @code{NULL}
and `*size' is undefined. Raises a @ref{164b,,MemoryError} if memory allocation
is failed.


Ajouté dans la version 3.2.



Modifié dans la version 3.7: Raises a @ref{1ff,,ValueError} if `size' is @code{NULL} and the wchar_t*
string contains null characters.

@end deffn

@node Built-in Codecs,Methods and Slot Functions,Objets Unicode,Objets Unicode et Codecs
@anchor{c-api/unicode built-in-codecs}@anchor{4b2a}@anchor{c-api/unicode builtincodecs}@anchor{4b26}
@subsubsection Built-in Codecs


Python provides a set of built-in codecs which are written in C for speed. All of
these codecs are directly usable via the following functions.

Many of the following APIs take two arguments encoding and errors, and they
have the same semantics as the ones of the built-in @ref{435,,str()} string object
constructor.

Setting encoding to @code{NULL} causes the default encoding to be used
which is UTF-8.  The file system calls should use
@ref{d07,,PyUnicode_FSConverter()} for encoding file names. This uses the
@ref{525,,filesystem encoding and error handler} internally.

Error handling is set by errors which may also be set to @code{NULL} meaning to use
the default handling defined for the codec.  Default error handling for all
built-in codecs is "strict" (@ref{1ff,,ValueError} is raised).

The codecs all use a similar interface.  Only deviations from the following
generic ones are documented for simplicity.

@menu
* Generic Codecs:: 
* UTF-8 Codecs:: 
* UTF-32 Codecs:: 
* UTF-16 Codecs:: 
* UTF-7 Codecs:: 
* Unicode-Escape Codecs:: 
* Raw-Unicode-Escape Codecs:: 
* Latin-1 Codecs:: 
* ASCII Codecs:: 
* Character Map Codecs:: 
* MBCS codecs for Windows:: 
* Methods & Slots:: 

@end menu

@node Generic Codecs,UTF-8 Codecs,,Built-in Codecs
@anchor{c-api/unicode generic-codecs}@anchor{4b2b}
@subsubsection Generic Codecs


These are the generic codec APIs:

@geindex PyUnicode_Decode (C function)
@anchor{c-api/unicode c PyUnicode_Decode}@anchor{1970}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Decode (const char *str, Py_ssize_t size, const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the encoded string `str'.
`encoding' and `errors' have the same meaning as the parameters of the same name
in the @ref{435,,str()} built-in function.  The codec to be used is looked up
using the Python codec registry.  Return @code{NULL} if an exception was raised by
the codec.
@end deffn

@geindex PyUnicode_AsEncodedString (C function)
@anchor{c-api/unicode c PyUnicode_AsEncodedString}@anchor{497b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsEncodedString (PyObject *unicode, const char *encoding, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object and return the result as Python bytes object.
`encoding' and `errors' have the same meaning as the parameters of the same
name in the Unicode @ref{8c2,,encode()} method. The codec to be used is looked up
using the Python codec registry. Return @code{NULL} if an exception was raised by
the codec.
@end deffn

@node UTF-8 Codecs,UTF-32 Codecs,Generic Codecs,Built-in Codecs
@anchor{c-api/unicode utf-8-codecs}@anchor{4b2c}
@subsubsection UTF-8 Codecs


These are the UTF-8 codec APIs:

@geindex PyUnicode_DecodeUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF8}@anchor{498e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF8 (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the UTF-8 encoded string
`str'. Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_DecodeUTF8Stateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF8Stateful}@anchor{172d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF8Stateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
If `consumed' is @code{NULL}, behave like @ref{498e,,PyUnicode_DecodeUTF8()}. If
`consumed' is not @code{NULL}, trailing incomplete UTF-8 byte sequences will not be
treated as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in `consumed'.
@end deffn

@geindex PyUnicode_AsUTF8String (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF8String}@anchor{116e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsUTF8String (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object using UTF-8 and return the result as Python bytes
object.  Error handling is "strict".  Return @code{NULL} if an exception was
raised by the codec.

The function fails if the string contains surrogate code points
(@code{U+D800} - @code{U+DFFF}).
@end deffn

@geindex PyUnicode_AsUTF8AndSize (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF8AndSize}@anchor{885}
@deffn {C Fonction} const char *PyUnicode_AsUTF8AndSize (PyObject *unicode, Py_ssize_t *size)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Return a pointer to the UTF-8 encoding of the Unicode object, and
store the size of the encoded representation (in bytes) in `size'.  The
`size' argument can be @code{NULL}; in this case no size will be stored.  The
returned buffer always has an extra null byte appended (not included in
`size'), regardless of whether there are any other null code points.

On error, set an exception, set `size' to @code{-1} (if it's not NULL) and
return @code{NULL}.

The function fails if the string contains surrogate code points
(@code{U+D800} - @code{U+DFFF}).

This caches the UTF-8 representation of the string in the Unicode object, and
subsequent calls will return a pointer to the same buffer.  The caller is not
responsible for deallocating the buffer. The buffer is deallocated and
pointers to it become invalid when the Unicode object is garbage collected.


Ajouté dans la version 3.3.



Modifié dans la version 3.7: The return type is now @code{const char *} rather of @code{char *}.



Modifié dans la version 3.10: This function is a part of the @ref{38c,,limited API}.

@end deffn

@geindex PyUnicode_AsUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF8}@anchor{ba9}
@deffn {C Fonction} const char *PyUnicode_AsUTF8 (PyObject *unicode)

As @ref{885,,PyUnicode_AsUTF8AndSize()}, but does not store the size.


Ajouté dans la version 3.3.



Modifié dans la version 3.7: The return type is now @code{const char *} rather of @code{char *}.

@end deffn

@node UTF-32 Codecs,UTF-16 Codecs,UTF-8 Codecs,Built-in Codecs
@anchor{c-api/unicode utf-32-codecs}@anchor{4b2d}
@subsubsection UTF-32 Codecs


These are the UTF-32 codec APIs:

@geindex PyUnicode_DecodeUTF32 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF32}@anchor{498a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF32 (const char *str, Py_ssize_t size, const char *errors, int *byteorder)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Decode `size' bytes from a UTF-32 encoded buffer string and return the
corresponding Unicode object.  `errors' (if non-@code{NULL}) defines the error
handling. It defaults to "strict".

If `byteorder' is non-@code{NULL}, the decoder starts decoding using the given byte
order:

@example
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
@end example

If @code{*byteorder} is zero, and the first four bytes of the input data are a
byte order mark (BOM), the decoder switches to this byte order and the BOM is
not copied into the resulting Unicode string.  If @code{*byteorder} is @code{-1} or
@code{1}, any byte order mark is copied to the output.

After completion, `*byteorder' is set to the current byte order at the end
of input data.

If `byteorder' is @code{NULL}, the codec starts in native order mode.

Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_DecodeUTF32Stateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF32Stateful}@anchor{498b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF32Stateful (const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
If `consumed' is @code{NULL}, behave like @ref{498a,,PyUnicode_DecodeUTF32()}. If
`consumed' is not @code{NULL}, @ref{498b,,PyUnicode_DecodeUTF32Stateful()} will not treat
trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
by four) as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in `consumed'.
@end deffn

@geindex PyUnicode_AsUTF32String (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF32String}@anchor{497d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsUTF32String (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a Python byte string using the UTF-32 encoding in native byte
order. The string always starts with a BOM mark.  Error handling is "strict".
Return @code{NULL} if an exception was raised by the codec.
@end deffn

@node UTF-16 Codecs,UTF-7 Codecs,UTF-32 Codecs,Built-in Codecs
@anchor{c-api/unicode utf-16-codecs}@anchor{4b2e}
@subsubsection UTF-16 Codecs


These are the UTF-16 codec APIs:

@geindex PyUnicode_DecodeUTF16 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF16}@anchor{4988}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF16 (const char *str, Py_ssize_t size, const char *errors, int *byteorder)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Decode `size' bytes from a UTF-16 encoded buffer string and return the
corresponding Unicode object.  `errors' (if non-@code{NULL}) defines the error
handling. It defaults to "strict".

If `byteorder' is non-@code{NULL}, the decoder starts decoding using the given byte
order:

@example
*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
@end example

If @code{*byteorder} is zero, and the first two bytes of the input data are a
byte order mark (BOM), the decoder switches to this byte order and the BOM is
not copied into the resulting Unicode string.  If @code{*byteorder} is @code{-1} or
@code{1}, any byte order mark is copied to the output (where it will result in
either a @code{\ufeff} or a @code{\ufffe} character).

After completion, @code{*byteorder} is set to the current byte order at the end
of input data.

If `byteorder' is @code{NULL}, the codec starts in native order mode.

Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_DecodeUTF16Stateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF16Stateful}@anchor{4989}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF16Stateful (const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
If `consumed' is @code{NULL}, behave like @ref{4988,,PyUnicode_DecodeUTF16()}. If
`consumed' is not @code{NULL}, @ref{4989,,PyUnicode_DecodeUTF16Stateful()} will not treat
trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
split surrogate pair) as an error. Those bytes will not be decoded and the
number of bytes that have been decoded will be stored in `consumed'.
@end deffn

@geindex PyUnicode_AsUTF16String (C function)
@anchor{c-api/unicode c PyUnicode_AsUTF16String}@anchor{497c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsUTF16String (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a Python byte string using the UTF-16 encoding in native byte
order. The string always starts with a BOM mark.  Error handling is "strict".
Return @code{NULL} if an exception was raised by the codec.
@end deffn

@node UTF-7 Codecs,Unicode-Escape Codecs,UTF-16 Codecs,Built-in Codecs
@anchor{c-api/unicode utf-7-codecs}@anchor{4b2f}
@subsubsection UTF-7 Codecs


These are the UTF-7 codec APIs:

@geindex PyUnicode_DecodeUTF7 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF7}@anchor{498c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF7 (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the UTF-7 encoded string
`str'.  Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_DecodeUTF7Stateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUTF7Stateful}@anchor{498d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUTF7Stateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
If `consumed' is @code{NULL}, behave like @ref{498c,,PyUnicode_DecodeUTF7()}.  If
`consumed' is not @code{NULL}, trailing incomplete UTF-7 base-64 sections will not
be treated as an error.  Those bytes will not be decoded and the number of
bytes that have been decoded will be stored in `consumed'.
@end deffn

@node Unicode-Escape Codecs,Raw-Unicode-Escape Codecs,UTF-7 Codecs,Built-in Codecs
@anchor{c-api/unicode unicode-escape-codecs}@anchor{4b30}
@subsubsection Unicode-Escape Codecs


These are the "Unicode Escape" codec APIs:

@geindex PyUnicode_DecodeUnicodeEscape (C function)
@anchor{c-api/unicode c PyUnicode_DecodeUnicodeEscape}@anchor{498f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeUnicodeEscape (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the Unicode-Escape encoded
string `str'.  Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_AsUnicodeEscapeString (C function)
@anchor{c-api/unicode c PyUnicode_AsUnicodeEscapeString}@anchor{116f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsUnicodeEscapeString (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object using Unicode-Escape and return the result as a
bytes object.  Error handling is "strict".  Return @code{NULL} if an exception was
raised by the codec.
@end deffn

@node Raw-Unicode-Escape Codecs,Latin-1 Codecs,Unicode-Escape Codecs,Built-in Codecs
@anchor{c-api/unicode raw-unicode-escape-codecs}@anchor{4b31}
@subsubsection Raw-Unicode-Escape Codecs


These are the "Raw Unicode Escape" codec APIs:

@geindex PyUnicode_DecodeRawUnicodeEscape (C function)
@anchor{c-api/unicode c PyUnicode_DecodeRawUnicodeEscape}@anchor{4987}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeRawUnicodeEscape (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the Raw-Unicode-Escape
encoded string `str'.  Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_AsRawUnicodeEscapeString (C function)
@anchor{c-api/unicode c PyUnicode_AsRawUnicodeEscapeString}@anchor{1170}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsRawUnicodeEscapeString (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object using Raw-Unicode-Escape and return the result as
a bytes object.  Error handling is "strict".  Return @code{NULL} if an exception
was raised by the codec.
@end deffn

@node Latin-1 Codecs,ASCII Codecs,Raw-Unicode-Escape Codecs,Built-in Codecs
@anchor{c-api/unicode latin-1-codecs}@anchor{4b32}
@subsubsection Latin-1 Codecs


These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
ordinals and only these are accepted by the codecs during encoding.

@geindex PyUnicode_DecodeLatin1 (C function)
@anchor{c-api/unicode c PyUnicode_DecodeLatin1}@anchor{4983}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeLatin1 (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the Latin-1 encoded string
`str'.  Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_AsLatin1String (C function)
@anchor{c-api/unicode c PyUnicode_AsLatin1String}@anchor{1171}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsLatin1String (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object using Latin-1 and return the result as Python bytes
object.  Error handling is "strict".  Return @code{NULL} if an exception was
raised by the codec.
@end deffn

@node ASCII Codecs,Character Map Codecs,Latin-1 Codecs,Built-in Codecs
@anchor{c-api/unicode ascii-codecs}@anchor{4b33}
@subsubsection ASCII Codecs


These are the ASCII codec APIs.  Only 7-bit ASCII data is accepted. All other
codes generate errors.

@geindex PyUnicode_DecodeASCII (C function)
@anchor{c-api/unicode c PyUnicode_DecodeASCII}@anchor{4980}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeASCII (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the ASCII encoded string
`str'.  Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_AsASCIIString (C function)
@anchor{c-api/unicode c PyUnicode_AsASCIIString}@anchor{1172}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsASCIIString (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object using ASCII and return the result as Python bytes
object.  Error handling is "strict".  Return @code{NULL} if an exception was
raised by the codec.
@end deffn

@node Character Map Codecs,MBCS codecs for Windows,ASCII Codecs,Built-in Codecs
@anchor{c-api/unicode character-map-codecs}@anchor{4b34}
@subsubsection Character Map Codecs


This codec is special in that it can be used to implement many different codecs
(and this is in fact what was done to obtain most of the standard codecs
included in the @code{encodings} package). The codec uses mappings to encode and
decode characters.  The mapping objects provided must support the
@ref{280,,__getitem__()} mapping interface; dictionaries and sequences work well.

These are the mapping codec APIs:

@geindex PyUnicode_DecodeCharmap (C function)
@anchor{c-api/unicode c PyUnicode_DecodeCharmap}@anchor{4981}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeCharmap (const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Unicode object by decoding `size' bytes of the encoded string `str'
using the given `mapping' object.  Return @code{NULL} if an exception was raised
by the codec.

If `mapping' is @code{NULL}, Latin-1 decoding will be applied.  Else
`mapping' must map bytes ordinals (integers in the range from 0 to 255)
to Unicode strings, integers (which are then interpreted as Unicode
ordinals) or @code{None}.  Unmapped data bytes -- ones which cause a
@ref{2155,,LookupError}, as well as ones which get mapped to @code{None},
@code{0xFFFE} or @code{'\ufffe'}, are treated as undefined mappings and cause
an error.
@end deffn

@geindex PyUnicode_AsCharmapString (C function)
@anchor{c-api/unicode c PyUnicode_AsCharmapString}@anchor{497a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsCharmapString (PyObject *unicode, PyObject *mapping)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Encode a Unicode object using the given `mapping' object and return the
result as a bytes object.  Error handling is "strict".  Return @code{NULL} if an
exception was raised by the codec.

The `mapping' object must map Unicode ordinal integers to bytes objects,
integers in the range from 0 to 255 or @code{None}.  Unmapped character
ordinals (ones which cause a @ref{2155,,LookupError}) as well as mapped to
@code{None} are treated as "undefined mapping" and cause an error.
@end deffn

The following codec API is special in that maps Unicode to Unicode.

@geindex PyUnicode_Translate (C function)
@anchor{c-api/unicode c PyUnicode_Translate}@anchor{4999}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Translate (PyObject *unicode, PyObject *table, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Translate a string by applying a character mapping table to it and return the
resulting Unicode object. Return @code{NULL} if an exception was raised by the
codec.

The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or @code{None} (causing deletion of the character).

Mapping tables need only provide the @ref{280,,__getitem__()} interface; dictionaries
and sequences work well.  Unmapped character ordinals (ones which cause a
@ref{2155,,LookupError}) are left untouched and are copied as-is.

`errors' has the usual meaning for codecs. It may be @code{NULL} which indicates to
use the default error handling.
@end deffn

@node MBCS codecs for Windows,Methods & Slots,Character Map Codecs,Built-in Codecs
@anchor{c-api/unicode mbcs-codecs-for-windows}@anchor{4b35}
@subsubsection MBCS codecs for Windows


These are the MBCS codec APIs. They are currently only available on Windows and
use the Win32 MBCS converters to implement the conversions.  Note that MBCS (or
DBCS) is a class of encodings, not just one.  The target encoding is defined by
the user settings on the machine running the codec.

@geindex PyUnicode_DecodeMBCS (C function)
@anchor{c-api/unicode c PyUnicode_DecodeMBCS}@anchor{4985}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeMBCS (const char *str, Py_ssize_t size, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Create a Unicode object by decoding `size' bytes of the MBCS encoded string `str'.
Return @code{NULL} if an exception was raised by the codec.
@end deffn

@geindex PyUnicode_DecodeMBCSStateful (C function)
@anchor{c-api/unicode c PyUnicode_DecodeMBCSStateful}@anchor{4986}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_DecodeMBCSStateful (const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
If `consumed' is @code{NULL}, behave like @ref{4985,,PyUnicode_DecodeMBCS()}. If
`consumed' is not @code{NULL}, @ref{4986,,PyUnicode_DecodeMBCSStateful()} will not decode
trailing lead byte and the number of bytes that have been decoded will be stored
in `consumed'.
@end deffn

@geindex PyUnicode_AsMBCSString (C function)
@anchor{c-api/unicode c PyUnicode_AsMBCSString}@anchor{1173}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_AsMBCSString (PyObject *unicode)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Encode a Unicode object using MBCS and return the result as Python bytes
object.  Error handling is "strict".  Return @code{NULL} if an exception was
raised by the codec.
@end deffn

@geindex PyUnicode_EncodeCodePage (C function)
@anchor{c-api/unicode c PyUnicode_EncodeCodePage}@anchor{1174}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_EncodeCodePage (int code_page, PyObject *unicode, const char *errors)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} on Windows Depuis la version 3.7.'
Encode the Unicode object using the specified code page and return a Python
bytes object.  Return @code{NULL} if an exception was raised by the codec. Use
@code{CP_ACP} code page to get the MBCS encoder.


Ajouté dans la version 3.3.

@end deffn

@node Methods & Slots,,MBCS codecs for Windows,Built-in Codecs
@anchor{c-api/unicode methods-slots}@anchor{4b36}
@subsubsection Methods & Slots


@node Methods and Slot Functions,,Built-in Codecs,Objets Unicode et Codecs
@anchor{c-api/unicode methods-and-slot-functions}@anchor{4b37}@anchor{c-api/unicode unicodemethodsandslots}@anchor{4b38}
@subsubsection Methods and Slot Functions


The following APIs are capable of handling Unicode objects and strings on input
(we refer to them as strings in the descriptions) and return Unicode objects or
integers as appropriate.

They all return @code{NULL} or @code{-1} if an exception occurs.

@geindex PyUnicode_Concat (C function)
@anchor{c-api/unicode c PyUnicode_Concat}@anchor{117f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Concat (PyObject *left, PyObject *right)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Concat two strings giving a new Unicode string.
@end deffn

@geindex PyUnicode_Split (C function)
@anchor{c-api/unicode c PyUnicode_Split}@anchor{4997}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Split (PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Split a string giving a list of Unicode strings.  If `sep' is @code{NULL}, splitting
will be done at all whitespace substrings.  Otherwise, splits occur at the given
separator.  At most `maxsplit' splits will be done.  If negative, no limit is
set.  Separators are not included in the resulting list.
@end deffn

@geindex PyUnicode_Splitlines (C function)
@anchor{c-api/unicode c PyUnicode_Splitlines}@anchor{4998}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Splitlines (PyObject *unicode, int keepends)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Split a Unicode string at line breaks, returning a list of Unicode strings.
CRLF is considered to be one line break.  If `keepends' is @code{0}, the Line break
characters are not included in the resulting strings.
@end deffn

@geindex PyUnicode_Join (C function)
@anchor{c-api/unicode c PyUnicode_Join}@anchor{1180}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Join (PyObject *separator, PyObject *seq)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Join a sequence of strings using the given `separator' and return the resulting
Unicode string.
@end deffn

@geindex PyUnicode_Tailmatch (C function)
@anchor{c-api/unicode c PyUnicode_Tailmatch}@anchor{8a5}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_Tailmatch (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} if `substr' matches @code{unicode[start:end]} at the given tail end
(`direction' == @code{-1} means to do a prefix match, `direction' == @code{1} a suffix match),
@code{0} otherwise. Return @code{-1} if an error occurred.
@end deffn

@geindex PyUnicode_Find (C function)
@anchor{c-api/unicode c PyUnicode_Find}@anchor{4990}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_Find (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
` Part of the @ref{53e,,Stable ABI}.'
Return the first position of `substr' in @code{unicode[start:end]} using the given
`direction' (`direction' == @code{1} means to do a forward search, `direction' == @code{-1} a
backward search).  The return value is the index of the first match; a value of
@code{-1} indicates that no match was found, and @code{-2} indicates that an error
occurred and an exception has been set.
@end deffn

@geindex PyUnicode_FindChar (C function)
@anchor{c-api/unicode c PyUnicode_FindChar}@anchor{8a6}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_FindChar (PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return the first position of the character `ch' in @code{unicode[start:end]} using
the given `direction' (`direction' == @code{1} means to do a forward search,
`direction' == @code{-1} a backward search).  The return value is the index of the
first match; a value of @code{-1} indicates that no match was found, and @code{-2}
indicates that an error occurred and an exception has been set.


Ajouté dans la version 3.3.



Modifié dans la version 3.7: `start' and `end' are now adjusted to behave like @code{unicode[start:end]}.

@end deffn

@geindex PyUnicode_Count (C function)
@anchor{c-api/unicode c PyUnicode_Count}@anchor{497f}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnicode_Count (PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
` Part of the @ref{53e,,Stable ABI}.'
Return the number of non-overlapping occurrences of `substr' in
@code{unicode[start:end]}.  Return @code{-1} if an error occurred.
@end deffn

@geindex PyUnicode_Replace (C function)
@anchor{c-api/unicode c PyUnicode_Replace}@anchor{4995}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Replace (PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Replace at most `maxcount' occurrences of `substr' in `unicode' with `replstr' and
return the resulting Unicode object. `maxcount' == @code{-1} means replace all
occurrences.
@end deffn

@geindex PyUnicode_Compare (C function)
@anchor{c-api/unicode c PyUnicode_Compare}@anchor{8a4}
@deffn {C Fonction} int PyUnicode_Compare (PyObject *left, PyObject *right)
` Part of the @ref{53e,,Stable ABI}.'
Compare two strings and return @code{-1}, @code{0}, @code{1} for less than, equal, and greater than,
respectively.

This function returns @code{-1} upon failure, so one should call
@ref{187f,,PyErr_Occurred()} to check for errors.
@end deffn

@geindex PyUnicode_EqualToUTF8AndSize (C function)
@anchor{c-api/unicode c PyUnicode_EqualToUTF8AndSize}@anchor{36c}
@deffn {C Fonction} int PyUnicode_EqualToUTF8AndSize (PyObject *unicode, const char *string, Py_ssize_t size)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Compare a Unicode object with a char buffer which is interpreted as
being UTF-8 or ASCII encoded and return true (@code{1}) if they are equal,
or false (@code{0}) otherwise.
If the Unicode object contains surrogate code points
(@code{U+D800} - @code{U+DFFF}) or the C string is not valid UTF-8,
false (@code{0}) is returned.

This function does not raise exceptions.


Ajouté dans la version 3.13.

@end deffn

@geindex PyUnicode_EqualToUTF8 (C function)
@anchor{c-api/unicode c PyUnicode_EqualToUTF8}@anchor{36d}
@deffn {C Fonction} int PyUnicode_EqualToUTF8 (PyObject *unicode, const char *string)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Similar to @ref{36c,,PyUnicode_EqualToUTF8AndSize()}, but compute `string'
length using @code{strlen()}.
If the Unicode object contains null characters, false (@code{0}) is returned.


Ajouté dans la version 3.13.

@end deffn

@geindex PyUnicode_CompareWithASCIIString (C function)
@anchor{c-api/unicode c PyUnicode_CompareWithASCIIString}@anchor{1246}
@deffn {C Fonction} int PyUnicode_CompareWithASCIIString (PyObject *unicode, const char *string)
` Part of the @ref{53e,,Stable ABI}.'
Compare a Unicode object, `unicode', with `string' and return @code{-1}, @code{0}, @code{1} for less
than, equal, and greater than, respectively. It is best to pass only
ASCII-encoded strings, but the function interprets the input string as
ISO-8859-1 if it contains non-ASCII characters.

This function does not raise exceptions.
@end deffn

@geindex PyUnicode_RichCompare (C function)
@anchor{c-api/unicode c PyUnicode_RichCompare}@anchor{4996}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_RichCompare (PyObject *left, PyObject *right, int op)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Rich compare two Unicode strings and return one of the following:


@itemize *

@item 
@code{NULL} in case an exception was raised

@item 
@ref{4adb,,Py_True} or @ref{4ada,,Py_False} for successful comparisons

@item 
@ref{4a50,,Py_NotImplemented} in case the type combination is unknown
@end itemize

Possible values for `op' are @ref{4a58,,Py_GT}, @ref{4a59,,Py_GE}, @ref{4a56,,Py_EQ},
@ref{4a57,,Py_NE}, @ref{4a54,,Py_LT}, and @ref{4a55,,Py_LE}.
@end deffn

@geindex PyUnicode_Format (C function)
@anchor{c-api/unicode c PyUnicode_Format}@anchor{4991}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_Format (PyObject *format, PyObject *args)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new string object from `format' and `args'; this is analogous to
@code{format % args}.
@end deffn

@geindex PyUnicode_Contains (C function)
@anchor{c-api/unicode c PyUnicode_Contains}@anchor{497e}
@deffn {C Fonction} int PyUnicode_Contains (PyObject *unicode, PyObject *substr)
` Part of the @ref{53e,,Stable ABI}.'
Check whether `substr' is contained in `unicode' and return true or false
accordingly.

`substr' has to coerce to a one element Unicode string. @code{-1} is returned
if there was an error.
@end deffn

@geindex PyUnicode_InternInPlace (C function)
@anchor{c-api/unicode c PyUnicode_InternInPlace}@anchor{89e}
@deffn {C Fonction} void PyUnicode_InternInPlace (PyObject **p_unicode)
` Part of the @ref{53e,,Stable ABI}.'
Intern the argument *@ref{89e,,p_unicode} in place.  The argument must be the address of a
pointer variable pointing to a Python Unicode string object.  If there is an
existing interned string that is the same as *@ref{89e,,p_unicode}, it sets *@ref{89e,,p_unicode} to
it (releasing the reference to the old string object and creating a new
@ref{333,,strong reference} to the interned string object), otherwise it leaves
*@ref{89e,,p_unicode} alone and interns it.

(Clarification: even though there is a lot of talk about references, think
of this function as reference-neutral. You must own the object you pass in;
after the call you no longer own the passed-in reference, but you newly own
the result.)

This function never raises an exception.
On error, it leaves its argument unchanged without interning it.

Instances of subclasses of @ref{435,,str} may not be interned, that is,
@ref{4b0f,,PyUnicode_CheckExact}(*@ref{89e,,p_unicode}) must be true. If it is not,
then -- as with any other error -- the argument is left unchanged.

Note that interned strings are not “immortal”.
You must keep a reference to the result to benefit from interning.
@end deffn

@geindex PyUnicode_InternFromString (C function)
@anchor{c-api/unicode c PyUnicode_InternFromString}@anchor{1587}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnicode_InternFromString (const char *str)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
A combination of @ref{4832,,PyUnicode_FromString()} and
@ref{89e,,PyUnicode_InternInPlace()}, meant for statically allocated strings.

Return a new ("owned") reference to either a new Unicode string object
that has been interned, or an earlier interned string object with the
same value.

Python may keep a reference to the result, or make it @ref{42aa,,immortal},
preventing it from being garbage-collected promptly.
For interning an unbounded number of different strings, such as ones coming
from user input, prefer calling @ref{4832,,PyUnicode_FromString()} and
@ref{89e,,PyUnicode_InternInPlace()} directly.

`Particularité de l'implémentation CPython :' Strings interned this way are made @ref{42aa,,immortal}.
@end deffn

@node Tuple Objects,Struct Sequence Objects,Objets Unicode et Codecs,Objets séquences
@anchor{c-api/tuple doc}@anchor{4b39}@anchor{c-api/tuple tuple-objects}@anchor{4b3a}@anchor{c-api/tuple tupleobjects}@anchor{4b3b}
@subsubsection Tuple Objects


@geindex object;tuple

@geindex PyTupleObject (C type)
@anchor{c-api/tuple c PyTupleObject}@anchor{4a09}
@deffn {C Type} type PyTupleObject

This subtype of @ref{32f,,PyObject} represents a Python tuple object.
@end deffn

@geindex PyTuple_Type (C var)
@anchor{c-api/tuple c PyTuple_Type}@anchor{495e}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyTuple_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python tuple type; it
is the same object as @ref{366,,tuple} in the Python layer.
@end deffn

@geindex PyTuple_Check (C function)
@anchor{c-api/tuple c PyTuple_Check}@anchor{4b3c}
@deffn {C Fonction} int PyTuple_Check (PyObject *p)

Return true if `p' is a tuple object or an instance of a subtype of the
tuple type.  This function always succeeds.
@end deffn

@geindex PyTuple_CheckExact (C function)
@anchor{c-api/tuple c PyTuple_CheckExact}@anchor{4b3d}
@deffn {C Fonction} int PyTuple_CheckExact (PyObject *p)

Return true if `p' is a tuple object, but not an instance of a subtype of the
tuple type.  This function always succeeds.
@end deffn

@geindex PyTuple_New (C function)
@anchor{c-api/tuple c PyTuple_New}@anchor{394}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTuple_New (Py_ssize_t len)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new tuple object of size `len',
or @code{NULL} with an exception set on failure.
@end deffn

@geindex PyTuple_Pack (C function)
@anchor{c-api/tuple c PyTuple_Pack}@anchor{495c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTuple_Pack (Py_ssize_t n, ...)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new tuple object of size `n',
or @code{NULL} with an exception set on failure. The tuple values
are initialized to the subsequent `n' C arguments pointing to Python objects.
@code{PyTuple_Pack(2, a, b)} is equivalent to @code{Py_BuildValue("(OO)", a, b)}.
@end deffn

@geindex PyTuple_Size (C function)
@anchor{c-api/tuple c PyTuple_Size}@anchor{495d}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyTuple_Size (PyObject *p)
` Part of the @ref{53e,,Stable ABI}.'
Take a pointer to a tuple object, and return the size of that tuple.
On error, return @code{-1} and with an exception set.
@end deffn

@geindex PyTuple_GET_SIZE (C function)
@anchor{c-api/tuple c PyTuple_GET_SIZE}@anchor{4b3e}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyTuple_GET_SIZE (PyObject *p)

Like @ref{495d,,PyTuple_Size()}, but without error checking.
@end deffn

@geindex PyTuple_GetItem (C function)
@anchor{c-api/tuple c PyTuple_GetItem}@anchor{47d7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTuple_GetItem (PyObject *p, Py_ssize_t pos)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return the object at position `pos' in the tuple pointed to by `p'.  If `pos' is
negative or out of bounds, return @code{NULL} and set an @ref{14eb,,IndexError} exception.

The returned reference is borrowed from the tuple `p'
(that is: it is only valid as long as you hold a reference to `p').
To get a @ref{333,,strong reference}, use
@ref{886,,Py_NewRef(PyTuple_GetItem(...))}
or @ref{19e1,,PySequence_GetItem()}.
@end deffn

@geindex PyTuple_GET_ITEM (C function)
@anchor{c-api/tuple c PyTuple_GET_ITEM}@anchor{4b3f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTuple_GET_ITEM (PyObject *p, Py_ssize_t pos)
`Valeur de retour : référence empruntée.'
Like @ref{47d7,,PyTuple_GetItem()}, but does no checking of its arguments.
@end deffn

@geindex PyTuple_GetSlice (C function)
@anchor{c-api/tuple c PyTuple_GetSlice}@anchor{495b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTuple_GetSlice (PyObject *p, Py_ssize_t low, Py_ssize_t high)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return the slice of the tuple pointed to by `p' between `low' and `high',
or @code{NULL} with an exception set on failure.

This is the equivalent of the Python expression @code{p[low:high]}.
Indexing from the end of the tuple is not supported.
@end deffn

@geindex PyTuple_SetItem (C function)
@anchor{c-api/tuple c PyTuple_SetItem}@anchor{47d8}
@deffn {C Fonction} int PyTuple_SetItem (PyObject *p, Py_ssize_t pos, PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Insert a reference to object `o' at position `pos' of the tuple pointed to by
`p'.  Return @code{0} on success.  If `pos' is out of bounds, return @code{-1}
and set an @ref{14eb,,IndexError} exception.

@cartouche
@quotation Note 
This function "steals" a reference to `o' and discards a reference to
an item already in the tuple at the affected position.
@end quotation
@end cartouche
@end deffn

@geindex PyTuple_SET_ITEM (C function)
@anchor{c-api/tuple c PyTuple_SET_ITEM}@anchor{383}
@deffn {C Fonction} void PyTuple_SET_ITEM (PyObject *p, Py_ssize_t pos, PyObject *o)

Like @ref{47d8,,PyTuple_SetItem()}, but does no error checking, and should `only' be
used to fill in brand new tuples.

Bounds checking is performed as an assertion if Python is built in
@ref{1f6,,debug mode} or @ref{382,,with assertions}.

@cartouche
@quotation Note 
This function "steals" a reference to `o', and, unlike
@ref{47d8,,PyTuple_SetItem()}, does `not' discard a reference to any item that
is being replaced; any reference in the tuple at position `pos' will be
leaked.
@end quotation
@end cartouche
@end deffn

@geindex _PyTuple_Resize (C function)
@anchor{c-api/tuple c _PyTuple_Resize}@anchor{14c3}
@deffn {C Fonction} int _PyTuple_Resize (PyObject **p, Py_ssize_t newsize)

Can be used to resize a tuple.  `newsize' will be the new length of the tuple.
Because tuples are `supposed' to be immutable, this should only be used if there
is only one reference to the object.  Do `not' use this if the tuple may already
be known to some other part of the code.  The tuple will always grow or shrink
at the end.  Think of this as destroying the old tuple and creating a new one,
only more efficiently.  Returns @code{0} on success. Client code should never
assume that the resulting value of @code{*p} will be the same as before calling
this function. If the object referenced by @code{*p} is replaced, the original
@code{*p} is destroyed.  On failure, returns @code{-1} and sets @code{*p} to @code{NULL}, and
raises @ref{164b,,MemoryError} or @ref{561,,SystemError}.
@end deffn

@node Struct Sequence Objects,List Objects,Tuple Objects,Objets séquences
@anchor{c-api/tuple id1}@anchor{4b40}@anchor{c-api/tuple struct-sequence-objects}@anchor{119c}
@subsubsection Struct Sequence Objects


Struct sequence objects are the C equivalent of @ref{1c5,,namedtuple()}
objects, i.e. a sequence whose items can also be accessed through attributes.
To create a struct sequence, you first have to create a specific struct sequence
type.

@geindex PyStructSequence_NewType (C function)
@anchor{c-api/tuple c PyStructSequence_NewType}@anchor{494e}
@deffn {C Fonction} @ref{a93,,PyTypeObject} *PyStructSequence_NewType (PyStructSequence_Desc *desc)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a new struct sequence type from the data in `desc', described below. Instances
of the resulting type can be created with @ref{494d,,PyStructSequence_New()}.

Return @code{NULL} with an exception set on failure.
@end deffn

@geindex PyStructSequence_InitType (C function)
@anchor{c-api/tuple c PyStructSequence_InitType}@anchor{fec}
@deffn {C Fonction} void PyStructSequence_InitType (PyTypeObject *type, PyStructSequence_Desc *desc)

Initializes a struct sequence type `type' from `desc' in place.
@end deffn

@geindex PyStructSequence_InitType2 (C function)
@anchor{c-api/tuple c PyStructSequence_InitType2}@anchor{feb}
@deffn {C Fonction} int PyStructSequence_InitType2 (PyTypeObject *type, PyStructSequence_Desc *desc)

Like @ref{fec,,PyStructSequence_InitType()}, but returns @code{0} on success
and @code{-1} with an exception set on failure.


Ajouté dans la version 3.4.

@end deffn

@geindex PyStructSequence_Desc (C type)
@anchor{c-api/tuple c PyStructSequence_Desc}@anchor{ba8}
@deffn {C Type} type PyStructSequence_Desc
` Part of the @ref{53e,,Stable ABI} (including all members).'
Contains the meta information of a struct sequence type to create.

@geindex PyStructSequence_Desc.name (C member)
@anchor{c-api/tuple c PyStructSequence_Desc name}@anchor{4b41}
@deffn {C Membre} const char *name

Fully qualified name of the type; null-terminated UTF-8 encoded.
The name must contain the module name.
@end deffn

@geindex PyStructSequence_Desc.doc (C member)
@anchor{c-api/tuple c PyStructSequence_Desc doc}@anchor{4b42}
@deffn {C Membre} const char *doc

Pointer to docstring for the type or @code{NULL} to omit.
@end deffn

@geindex PyStructSequence_Desc.fields (C member)
@anchor{c-api/tuple c PyStructSequence_Desc fields}@anchor{4b43}
@deffn {C Membre} @ref{ba7,,PyStructSequence_Field} *fields

Pointer to @code{NULL}-terminated array with field names of the new type.
@end deffn

@geindex PyStructSequence_Desc.n_in_sequence (C member)
@anchor{c-api/tuple c PyStructSequence_Desc n_in_sequence}@anchor{4b44}
@deffn {C Membre} int n_in_sequence

Number of fields visible to the Python side (if used as tuple).
@end deffn
@end deffn

@geindex PyStructSequence_Field (C type)
@anchor{c-api/tuple c PyStructSequence_Field}@anchor{ba7}
@deffn {C Type} type PyStructSequence_Field
` Part of the @ref{53e,,Stable ABI} (including all members).'
Describes a field of a struct sequence. As a struct sequence is modeled as a
tuple, all fields are typed as @ref{32f,,PyObject}*.  The index in the
@ref{4b43,,fields} array of
the @ref{ba8,,PyStructSequence_Desc} determines which
field of the struct sequence is described.

@geindex PyStructSequence_Field.name (C member)
@anchor{c-api/tuple c PyStructSequence_Field name}@anchor{4b45}
@deffn {C Membre} const char *name

Name for the field or @code{NULL} to end the list of named fields,
set to @ref{96f,,PyStructSequence_UnnamedField} to leave unnamed.
@end deffn

@geindex PyStructSequence_Field.doc (C member)
@anchor{c-api/tuple c PyStructSequence_Field doc}@anchor{4b46}
@deffn {C Membre} const char *doc

Field docstring or @code{NULL} to omit.
@end deffn
@end deffn

@geindex PyStructSequence_UnnamedField (C var)
@anchor{c-api/tuple c PyStructSequence_UnnamedField}@anchor{96f}
@deffn {C Variable} const char *const PyStructSequence_UnnamedField
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Special value for a field name to leave it unnamed.


Modifié dans la version 3.9: The type was changed from @code{char *}.

@end deffn

@geindex PyStructSequence_New (C function)
@anchor{c-api/tuple c PyStructSequence_New}@anchor{494d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyStructSequence_New (PyTypeObject *type)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Creates an instance of `type', which must have been created with
@ref{494e,,PyStructSequence_NewType()}.

Return @code{NULL} with an exception set on failure.
@end deffn

@geindex PyStructSequence_GetItem (C function)
@anchor{c-api/tuple c PyStructSequence_GetItem}@anchor{494c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyStructSequence_GetItem (PyObject *p, Py_ssize_t pos)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return the object at position `pos' in the struct sequence pointed to by `p'.

Bounds checking is performed as an assertion if Python is built in
@ref{1f6,,debug mode} or @ref{382,,with assertions}.
@end deffn

@geindex PyStructSequence_GET_ITEM (C function)
@anchor{c-api/tuple c PyStructSequence_GET_ITEM}@anchor{4b47}
@deffn {C Fonction} @ref{32f,,PyObject} *PyStructSequence_GET_ITEM (PyObject *p, Py_ssize_t pos)
`Valeur de retour : référence empruntée.'
Alias to @ref{494c,,PyStructSequence_GetItem()}.


Modifié dans la version 3.13: Now implemented as an alias to @ref{494c,,PyStructSequence_GetItem()}.

@end deffn

@geindex PyStructSequence_SetItem (C function)
@anchor{c-api/tuple c PyStructSequence_SetItem}@anchor{494f}
@deffn {C Fonction} void PyStructSequence_SetItem (PyObject *p, Py_ssize_t pos, PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Sets the field at index `pos' of the struct sequence `p' to value `o'.  Like
@ref{383,,PyTuple_SET_ITEM()}, this should only be used to fill in brand new
instances.

Bounds checking is performed as an assertion if Python is built in
@ref{1f6,,debug mode} or @ref{382,,with assertions}.

@cartouche
@quotation Note 
This function "steals" a reference to `o'.
@end quotation
@end cartouche
@end deffn

@geindex PyStructSequence_SET_ITEM (C function)
@anchor{c-api/tuple c PyStructSequence_SET_ITEM}@anchor{4b48}
@deffn {C Fonction} void PyStructSequence_SET_ITEM (PyObject *p, Py_ssize_t *pos, PyObject *o)

Alias to @ref{494f,,PyStructSequence_SetItem()}.


Modifié dans la version 3.13: Now implemented as an alias to @ref{494f,,PyStructSequence_SetItem()}.

@end deffn

@node List Objects,,Struct Sequence Objects,Objets séquences
@anchor{c-api/list doc}@anchor{4b49}@anchor{c-api/list list-objects}@anchor{4b4a}@anchor{c-api/list listobjects}@anchor{4b4b}
@subsubsection List Objects


@geindex object;list

@geindex PyListObject (C type)
@anchor{c-api/list c PyListObject}@anchor{4a6f}
@deffn {C Type} type PyListObject

This subtype of @ref{32f,,PyObject} represents a Python list object.
@end deffn

@geindex PyList_Type (C var)
@anchor{c-api/list c PyList_Type}@anchor{47fb}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyList_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python list type.
This is the same object as @ref{5fc,,list} in the Python layer.
@end deffn

@geindex PyList_Check (C function)
@anchor{c-api/list c PyList_Check}@anchor{4b4c}
@deffn {C Fonction} int PyList_Check (PyObject *p)

Return true if `p' is a list object or an instance of a subtype of the list
type.  This function always succeeds.
@end deffn

@geindex PyList_CheckExact (C function)
@anchor{c-api/list c PyList_CheckExact}@anchor{4b4d}
@deffn {C Fonction} int PyList_CheckExact (PyObject *p)

Return true if `p' is a list object, but not an instance of a subtype of
the list type.  This function always succeeds.
@end deffn

@geindex PyList_New (C function)
@anchor{c-api/list c PyList_New}@anchor{484f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyList_New (Py_ssize_t len)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new list of length `len' on success, or @code{NULL} on failure.

@cartouche
@quotation Note 
If `len' is greater than zero, the returned list object's items are
set to @code{NULL}. Thus you cannot use abstract API functions such as
@ref{19e2,,PySequence_SetItem()} or expose the object to Python code before
setting all items to a real object with @ref{47d9,,PyList_SetItem()} or
@ref{384,,PyList_SET_ITEM()}. The following APIs are safe APIs before
the list is fully initialized: @ref{47d9,,PyList_SetItem()} and @ref{384,,PyList_SET_ITEM()}.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Size (C function)
@anchor{c-api/list c PyList_Size}@anchor{13d0}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyList_Size (PyObject *list)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;len

Return the length of the list object in `list'; this is equivalent to
@code{len(list)} on a list object.
@end deffn

@geindex PyList_GET_SIZE (C function)
@anchor{c-api/list c PyList_GET_SIZE}@anchor{4b4e}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyList_GET_SIZE (PyObject *list)

Similar to @ref{13d0,,PyList_Size()}, but without error checking.
@end deffn

@geindex PyList_GetItemRef (C function)
@anchor{c-api/list c PyList_GetItemRef}@anchor{351}
@deffn {C Fonction} @ref{32f,,PyObject} *PyList_GetItemRef (PyObject *list, Py_ssize_t index)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return the object at position `index' in the list pointed to by `list'.  The
position must be non-negative; indexing from the end of the list is not
supported.  If `index' is out of bounds (@code{<0 or >=len(list)}),
return @code{NULL} and set an @ref{14eb,,IndexError} exception.


Ajouté dans la version 3.13.

@end deffn

@geindex PyList_GetItem (C function)
@anchor{c-api/list c PyList_GetItem}@anchor{352}
@deffn {C Fonction} @ref{32f,,PyObject} *PyList_GetItem (PyObject *list, Py_ssize_t index)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Like @ref{351,,PyList_GetItemRef()}, but returns a
@ref{334,,borrowed reference} instead of a @ref{333,,strong reference}.
@end deffn

@geindex PyList_GET_ITEM (C function)
@anchor{c-api/list c PyList_GET_ITEM}@anchor{4863}
@deffn {C Fonction} @ref{32f,,PyObject} *PyList_GET_ITEM (PyObject *list, Py_ssize_t i)
`Valeur de retour : référence empruntée.'
Similar to @ref{352,,PyList_GetItem()}, but without error checking.
@end deffn

@geindex PyList_SetItem (C function)
@anchor{c-api/list c PyList_SetItem}@anchor{47d9}
@deffn {C Fonction} int PyList_SetItem (PyObject *list, Py_ssize_t index, PyObject *item)
` Part of the @ref{53e,,Stable ABI}.'
Set the item at index `index' in list to `item'.  Return @code{0} on success.
If `index' is out of bounds, return @code{-1} and set an @ref{14eb,,IndexError}
exception.

@cartouche
@quotation Note 
This function "steals" a reference to `item' and discards a reference to
an item already in the list at the affected position.
@end quotation
@end cartouche
@end deffn

@geindex PyList_SET_ITEM (C function)
@anchor{c-api/list c PyList_SET_ITEM}@anchor{384}
@deffn {C Fonction} void PyList_SET_ITEM (PyObject *list, Py_ssize_t i, PyObject *o)

Macro form of @ref{47d9,,PyList_SetItem()} without error checking. This is
normally only used to fill in new lists where there is no previous content.

Bounds checking is performed as an assertion if Python is built in
@ref{1f6,,debug mode} or @ref{382,,with assertions}.

@cartouche
@quotation Note 
This macro "steals" a reference to `item', and, unlike
@ref{47d9,,PyList_SetItem()}, does `not' discard a reference to any item that
is being replaced; any reference in `list' at position `i' will be
leaked.
@end quotation
@end cartouche
@end deffn

@geindex PyList_Insert (C function)
@anchor{c-api/list c PyList_Insert}@anchor{48db}
@deffn {C Fonction} int PyList_Insert (PyObject *list, Py_ssize_t index, PyObject *item)
` Part of the @ref{53e,,Stable ABI}.'
Insert the item `item' into list `list' in front of index `index'.  Return
@code{0} if successful; return @code{-1} and set an exception if unsuccessful.
Analogous to @code{list.insert(index, item)}.
@end deffn

@geindex PyList_Append (C function)
@anchor{c-api/list c PyList_Append}@anchor{48d8}
@deffn {C Fonction} int PyList_Append (PyObject *list, PyObject *item)
` Part of the @ref{53e,,Stable ABI}.'
Append the object `item' at the end of list `list'. Return @code{0} if
successful; return @code{-1} and set an exception if unsuccessful.  Analogous
to @code{list.append(item)}.
@end deffn

@geindex PyList_GetSlice (C function)
@anchor{c-api/list c PyList_GetSlice}@anchor{48da}
@deffn {C Fonction} @ref{32f,,PyObject} *PyList_GetSlice (PyObject *list, Py_ssize_t low, Py_ssize_t high)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a list of the objects in `list' containing the objects `between' `low'
and `high'.  Return @code{NULL} and set an exception if unsuccessful.  Analogous
to @code{list[low:high]}.  Indexing from the end of the list is not supported.
@end deffn

@geindex PyList_SetSlice (C function)
@anchor{c-api/list c PyList_SetSlice}@anchor{48dd}
@deffn {C Fonction} int PyList_SetSlice (PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
` Part of the @ref{53e,,Stable ABI}.'
Set the slice of `list' between `low' and `high' to the contents of
`itemlist'.  Analogous to @code{list[low:high] = itemlist}. The `itemlist' may
be @code{NULL}, indicating the assignment of an empty list (slice deletion).
Return @code{0} on success, @code{-1} on failure.  Indexing from the end of the
list is not supported.
@end deffn

@geindex PyList_Extend (C function)
@anchor{c-api/list c PyList_Extend}@anchor{353}
@deffn {C Fonction} int PyList_Extend (PyObject *list, PyObject *iterable)

Extend `list' with the contents of `iterable'.  This is the same as
@code{PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)}
and analogous to @code{list.extend(iterable)} or @code{list += iterable}.

Raise an exception and return @code{-1} if `list' is not a @ref{5fc,,list}
object. Return 0 on success.


Ajouté dans la version 3.13.

@end deffn

@geindex PyList_Clear (C function)
@anchor{c-api/list c PyList_Clear}@anchor{354}
@deffn {C Fonction} int PyList_Clear (PyObject *list)

Remove all items from `list'.  This is the same as
@code{PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)} and analogous to
@code{list.clear()} or @code{del list[:]}.

Raise an exception and return @code{-1} if `list' is not a @ref{5fc,,list}
object.  Return 0 on success.


Ajouté dans la version 3.13.

@end deffn

@geindex PyList_Sort (C function)
@anchor{c-api/list c PyList_Sort}@anchor{48de}
@deffn {C Fonction} int PyList_Sort (PyObject *list)
` Part of the @ref{53e,,Stable ABI}.'
Sort the items of `list' in place.  Return @code{0} on success, @code{-1} on
failure.  This is equivalent to @code{list.sort()}.
@end deffn

@geindex PyList_Reverse (C function)
@anchor{c-api/list c PyList_Reverse}@anchor{48dc}
@deffn {C Fonction} int PyList_Reverse (PyObject *list)
` Part of the @ref{53e,,Stable ABI}.'
Reverse the items of `list' in place.  Return @code{0} on success, @code{-1} on
failure.  This is the equivalent of @code{list.reverse()}.
@end deffn

@geindex PyList_AsTuple (C function)
@anchor{c-api/list c PyList_AsTuple}@anchor{48d9}
@deffn {C Fonction} @ref{32f,,PyObject} *PyList_AsTuple (PyObject *list)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;tuple

Return a new tuple object containing the contents of `list'; equivalent to
@code{tuple(list)}.
@end deffn

@node Objets conteneurs,Objets fonctions<2>,Objets séquences,Couche des objets concrets
@anchor{c-api/concrete container-objects}@anchor{4b4f}@anchor{c-api/concrete mapobjects}@anchor{4b50}
@subsection Objets conteneurs


@geindex object;mapping

@menu
* Objets dictionnaires:: 
* Set Objects:: 

@end menu

@node Objets dictionnaires,Set Objects,,Objets conteneurs
@anchor{c-api/dict doc}@anchor{4b51}@anchor{c-api/dict dictionary-objects}@anchor{4b52}@anchor{c-api/dict dictobjects}@anchor{4b53}
@subsubsection Objets dictionnaires


@geindex object;dictionary

@geindex PyDictObject (C type)
@anchor{c-api/dict c PyDictObject}@anchor{3b8}
@deffn {C Type} type PyDictObject

This subtype of @ref{32f,,PyObject} represents a Python dictionary object.
@end deffn

@geindex PyDict_Type (C var)
@anchor{c-api/dict c PyDict_Type}@anchor{48a6}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyDict_Type
` Part of the @ref{53e,,Stable ABI}.'
This instance of @ref{a93,,PyTypeObject} represents the Python dictionary
type.  This is the same object as @ref{253,,dict} in the Python layer.
@end deffn

@geindex PyDict_Check (C function)
@anchor{c-api/dict c PyDict_Check}@anchor{4aaa}
@deffn {C Fonction} int PyDict_Check (PyObject *p)

Return true if `p' is a dict object or an instance of a subtype of the dict
type.  This function always succeeds.
@end deffn

@geindex PyDict_CheckExact (C function)
@anchor{c-api/dict c PyDict_CheckExact}@anchor{4b54}
@deffn {C Fonction} int PyDict_CheckExact (PyObject *p)

Return true if `p' is a dict object, but not an instance of a subtype of
the dict type.  This function always succeeds.
@end deffn

@geindex PyDict_New (C function)
@anchor{c-api/dict c PyDict_New}@anchor{48a4}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_New ()
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new empty dictionary, or @code{NULL} on failure.
@end deffn

@geindex PyDictProxy_New (C function)
@anchor{c-api/dict c PyDictProxy_New}@anchor{489c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDictProxy_New (PyObject *mapping)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a @ref{457,,types.MappingProxyType} object for a mapping which
enforces read-only behavior.  This is normally used to create a view to
prevent modification of the dictionary for non-dynamic class types.
@end deffn

@geindex PyDict_Clear (C function)
@anchor{c-api/dict c PyDict_Clear}@anchor{489d}
@deffn {C Fonction} void PyDict_Clear (PyObject *p)
` Part of the @ref{53e,,Stable ABI}.'
Empty an existing dictionary of all key-value pairs.
@end deffn

@geindex PyDict_Contains (C function)
@anchor{c-api/dict c PyDict_Contains}@anchor{32e}
@deffn {C Fonction} int PyDict_Contains (PyObject *p, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Determine if dictionary `p' contains `key'.  If an item in `p' is matches
`key', return @code{1}, otherwise return @code{0}.  On error, return @code{-1}.
This is equivalent to the Python expression @code{key in p}.
@end deffn

@geindex PyDict_ContainsString (C function)
@anchor{c-api/dict c PyDict_ContainsString}@anchor{32d}
@deffn {C Fonction} int PyDict_ContainsString (PyObject *p, const char *key)

This is the same as @ref{32e,,PyDict_Contains()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyDict_Copy (C function)
@anchor{c-api/dict c PyDict_Copy}@anchor{416}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_Copy (PyObject *p)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new dictionary that contains the same key-value pairs as `p'.
@end deffn

@geindex PyDict_SetItem (C function)
@anchor{c-api/dict c PyDict_SetItem}@anchor{47da}
@deffn {C Fonction} int PyDict_SetItem (PyObject *p, PyObject *key, PyObject *val)
` Part of the @ref{53e,,Stable ABI}.'
Insert `val' into the dictionary `p' with a key of `key'.  `key' must be
@ref{5fb,,hashable}; if it isn't, @ref{522,,TypeError} will be raised. Return
@code{0} on success or @code{-1} on failure.  This function `does not' steal a
reference to `val'.
@end deffn

@geindex PyDict_SetItemString (C function)
@anchor{c-api/dict c PyDict_SetItemString}@anchor{1588}
@deffn {C Fonction} int PyDict_SetItemString (PyObject *p, const char *key, PyObject *val)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{47da,,PyDict_SetItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
@end deffn

@geindex PyDict_DelItem (C function)
@anchor{c-api/dict c PyDict_DelItem}@anchor{489e}
@deffn {C Fonction} int PyDict_DelItem (PyObject *p, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Remove the entry in dictionary `p' with key `key'. `key' must be @ref{5fb,,hashable};
if it isn't, @ref{522,,TypeError} is raised.
If `key' is not in the dictionary, @ref{33a,,KeyError} is raised.
Return @code{0} on success or @code{-1} on failure.
@end deffn

@geindex PyDict_DelItemString (C function)
@anchor{c-api/dict c PyDict_DelItemString}@anchor{489f}
@deffn {C Fonction} int PyDict_DelItemString (PyObject *p, const char *key)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{489e,,PyDict_DelItem()}, but `key' is
specified as a const char* UTF-8 encoded bytes string,
rather than a @ref{32f,,PyObject}*.
@end deffn

@geindex PyDict_GetItemRef (C function)
@anchor{c-api/dict c PyDict_GetItemRef}@anchor{330}
@deffn {C Fonction} int PyDict_GetItemRef (PyObject *p, PyObject *key, PyObject **result)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return a new @ref{333,,strong reference} to the object from dictionary `p'
which has a key `key':


@itemize *

@item 
If the key is present, set `*result' to a new @ref{333,,strong reference}
to the value and return @code{1}.

@item 
If the key is missing, set `*result' to @code{NULL} and return @code{0}.

@item 
On error, raise an exception and return @code{-1}.
@end itemize


Ajouté dans la version 3.13.


See also the @ref{33d,,PyObject_GetItem()} function.
@end deffn

@geindex PyDict_GetItem (C function)
@anchor{c-api/dict c PyDict_GetItem}@anchor{37d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_GetItem (PyObject *p, PyObject *key)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return a @ref{334,,borrowed reference} to the object from dictionary `p' which
has a key `key'.  Return @code{NULL} if the key `key' is missing `without'
setting an exception.

@cartouche
@quotation Note 
Exceptions that occur while this calls @ref{ae9,,__hash__()} and
@ref{ae8,,__eq__()} methods are silently ignored.
Prefer the @ref{332,,PyDict_GetItemWithError()} function instead.
@end quotation
@end cartouche


Modifié dans la version 3.10: Calling this API without @ref{158,,GIL} held had been allowed for historical
reason. It is no longer allowed.

@end deffn

@geindex PyDict_GetItemWithError (C function)
@anchor{c-api/dict c PyDict_GetItemWithError}@anchor{332}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_GetItemWithError (PyObject *p, PyObject *key)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Variant of @ref{37d,,PyDict_GetItem()} that does not suppress
exceptions. Return @code{NULL} `with' an exception set if an exception
occurred.  Return @code{NULL} `without' an exception set if the key
wasn't present.
@end deffn

@geindex PyDict_GetItemString (C function)
@anchor{c-api/dict c PyDict_GetItemString}@anchor{37e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_GetItemString (PyObject *p, const char *key)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
This is the same as @ref{37d,,PyDict_GetItem()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{32f,,PyObject}*.

@cartouche
@quotation Note 
Exceptions that occur while this calls @ref{ae9,,__hash__()} and
@ref{ae8,,__eq__()} methods or while creating the temporary @ref{435,,str}
object are silently ignored.
Prefer using the @ref{332,,PyDict_GetItemWithError()} function with your own
@ref{4832,,PyUnicode_FromString()} `key' instead.
@end quotation
@end cartouche
@end deffn

@geindex PyDict_GetItemStringRef (C function)
@anchor{c-api/dict c PyDict_GetItemStringRef}@anchor{331}
@deffn {C Fonction} int PyDict_GetItemStringRef (PyObject *p, const char *key, PyObject **result)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Similar than @ref{330,,PyDict_GetItemRef()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyDict_SetDefault (C function)
@anchor{c-api/dict c PyDict_SetDefault}@anchor{336}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_SetDefault (PyObject *p, PyObject *key, PyObject *defaultobj)
`Valeur de retour : référence empruntée.'
This is the same as the Python-level @ref{1062,,dict.setdefault()}.  If present, it
returns the value corresponding to `key' from the dictionary `p'.  If the key
is not in the dict, it is inserted with value `defaultobj' and `defaultobj'
is returned.  This function evaluates the hash function of `key' only once,
instead of evaluating it independently for the lookup and the insertion.


Ajouté dans la version 3.4.

@end deffn

@geindex PyDict_SetDefaultRef (C function)
@anchor{c-api/dict c PyDict_SetDefaultRef}@anchor{335}
@deffn {C Fonction} int PyDict_SetDefaultRef (PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)

Inserts `default_value' into the dictionary `p' with a key of `key' if the
key is not already present in the dictionary. If `result' is not @code{NULL},
then `*result' is set to a @ref{333,,strong reference} to either
`default_value', if the key was not present, or the existing value, if `key'
was already present in the dictionary.
Returns @code{1} if the key was present and `default_value' was not inserted,
or @code{0} if the key was not present and `default_value' was inserted.
On failure, returns @code{-1}, sets an exception, and sets @code{*result}
to @code{NULL}.

For clarity: if you have a strong reference to `default_value' before
calling this function, then after it returns, you hold a strong reference
to both `default_value' and `*result' (if it's not @code{NULL}).
These may refer to the same object: in that case you hold two separate
references to it.


Ajouté dans la version 3.13.

@end deffn

@geindex PyDict_Pop (C function)
@anchor{c-api/dict c PyDict_Pop}@anchor{337}
@deffn {C Fonction} int PyDict_Pop (PyObject *p, PyObject *key, PyObject **result)

Remove `key' from dictionary `p' and optionally return the removed value.
Do not raise @ref{33a,,KeyError} if the key missing.


@itemize -

@item 
If the key is present, set `*result' to a new reference to the removed
value if `result' is not @code{NULL}, and return @code{1}.

@item 
If the key is missing, set `*result' to @code{NULL} if `result' is not
@code{NULL}, and return @code{0}.

@item 
On error, raise an exception and return @code{-1}.
@end itemize

This is similar to @ref{339,,dict.pop()}, but without the default value and
not raising @ref{33a,,KeyError} if the key missing.


Ajouté dans la version 3.13.

@end deffn

@geindex PyDict_PopString (C function)
@anchor{c-api/dict c PyDict_PopString}@anchor{338}
@deffn {C Fonction} int PyDict_PopString (PyObject *p, const char *key, PyObject **result)

Similar to @ref{337,,PyDict_Pop()}, but `key' is specified as a
const char* UTF-8 encoded bytes string, rather than a
@ref{32f,,PyObject}*.


Ajouté dans la version 3.13.

@end deffn

@geindex PyDict_Items (C function)
@anchor{c-api/dict c PyDict_Items}@anchor{48a0}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_Items (PyObject *p)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a @ref{4a6f,,PyListObject} containing all the items from the dictionary.
@end deffn

@geindex PyDict_Keys (C function)
@anchor{c-api/dict c PyDict_Keys}@anchor{48a1}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_Keys (PyObject *p)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a @ref{4a6f,,PyListObject} containing all the keys from the dictionary.
@end deffn

@geindex PyDict_Values (C function)
@anchor{c-api/dict c PyDict_Values}@anchor{48a8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDict_Values (PyObject *p)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a @ref{4a6f,,PyListObject} containing all the values from the dictionary
`p'.
@end deffn

@geindex PyDict_Size (C function)
@anchor{c-api/dict c PyDict_Size}@anchor{48a5}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyDict_Size (PyObject *p)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;len

Return the number of items in the dictionary.  This is equivalent to
@code{len(p)} on a dictionary.
@end deffn

@geindex PyDict_Next (C function)
@anchor{c-api/dict c PyDict_Next}@anchor{159a}
@deffn {C Fonction} int PyDict_Next (PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
` Part of the @ref{53e,,Stable ABI}.'
Iterate over all key-value pairs in the dictionary `p'.  The
@ref{a4e,,Py_ssize_t} referred to by `ppos' must be initialized to @code{0}
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported.  The parameters `pkey' and `pvalue' should either
point to @ref{32f,,PyObject}* variables that will be filled in with each key
and value, respectively, or may be @code{NULL}.  Any references returned through
them are borrowed.  `ppos' should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive.

Par exemple :

@example
PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) @{
    /* do something interesting with the values... */
    ...
@}
@end example

The dictionary `p' should not be mutated during iteration.  It is safe to
modify the values of the keys as you iterate over the dictionary, but only
so long as the set of keys does not change.  For example:

@example
PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) @{
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) @{
        return -1;
    @}
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) @{
        Py_DECREF(o);
        return -1;
    @}
    Py_DECREF(o);
@}
@end example

The function is not thread-safe in the @ref{150c,,free-threaded}
build without external synchronization.  You can use
@ref{4b55,,Py_BEGIN_CRITICAL_SECTION} to lock the dictionary while iterating
over it:

@example
Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) @{
    ...
@}
Py_END_CRITICAL_SECTION();
@end example
@end deffn

@geindex PyDict_Merge (C function)
@anchor{c-api/dict c PyDict_Merge}@anchor{48a2}
@deffn {C Fonction} int PyDict_Merge (PyObject *a, PyObject *b, int override)
` Part of the @ref{53e,,Stable ABI}.'
Iterate over mapping object `b' adding key-value pairs to dictionary `a'.
`b' may be a dictionary, or any object supporting @ref{baa,,PyMapping_Keys()}
and @ref{33d,,PyObject_GetItem()}. If `override' is true, existing pairs in `a'
will be replaced if a matching key is found in `b', otherwise pairs will
only be added if there is not a matching key in `a'. Return @code{0} on
success or @code{-1} if an exception was raised.
@end deffn

@geindex PyDict_Update (C function)
@anchor{c-api/dict c PyDict_Update}@anchor{48a7}
@deffn {C Fonction} int PyDict_Update (PyObject *a, PyObject *b)
` Part of the @ref{53e,,Stable ABI}.'
This is the same as @code{PyDict_Merge(a, b, 1)} in C, and is similar to
@code{a.update(b)} in Python except that @ref{48a7,,PyDict_Update()} doesn't fall
back to the iterating over a sequence of key value pairs if the second
argument has no "keys" attribute.  Return @code{0} on success or @code{-1} if an
exception was raised.
@end deffn

@geindex PyDict_MergeFromSeq2 (C function)
@anchor{c-api/dict c PyDict_MergeFromSeq2}@anchor{48a3}
@deffn {C Fonction} int PyDict_MergeFromSeq2 (PyObject *a, PyObject *seq2, int override)
` Part of the @ref{53e,,Stable ABI}.'
Update or merge into dictionary `a', from the key-value pairs in `seq2'.
`seq2' must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs.  In case of duplicate keys, the last wins if
`override' is true, else the first wins. Return @code{0} on success or @code{-1}
if an exception was raised. Equivalent Python (except for the return
value):

@example
def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value
@end example
@end deffn

@geindex PyDict_AddWatcher (C function)
@anchor{c-api/dict c PyDict_AddWatcher}@anchor{54e}
@deffn {C Fonction} int PyDict_AddWatcher (PyDict_WatchCallback callback)

Register `callback' as a dictionary watcher. Return a non-negative integer
id which must be passed to future calls to @ref{54f,,PyDict_Watch()}. In case
of error (e.g. no more watcher IDs available), return @code{-1} and set an
exception.


Ajouté dans la version 3.12.

@end deffn

@geindex PyDict_ClearWatcher (C function)
@anchor{c-api/dict c PyDict_ClearWatcher}@anchor{4b56}
@deffn {C Fonction} int PyDict_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{54e,,PyDict_AddWatcher()}. Return @code{0} on success, @code{-1} on error (e.g.
if the given `watcher_id' was never registered.)


Ajouté dans la version 3.12.

@end deffn

@geindex PyDict_Watch (C function)
@anchor{c-api/dict c PyDict_Watch}@anchor{54f}
@deffn {C Fonction} int PyDict_Watch (int watcher_id, PyObject *dict)

Mark dictionary `dict' as watched. The callback granted `watcher_id' by
@ref{54e,,PyDict_AddWatcher()} will be called when `dict' is modified or
deallocated. Return @code{0} on success or @code{-1} on error.


Ajouté dans la version 3.12.

@end deffn

@geindex PyDict_Unwatch (C function)
@anchor{c-api/dict c PyDict_Unwatch}@anchor{4b57}
@deffn {C Fonction} int PyDict_Unwatch (int watcher_id, PyObject *dict)

Mark dictionary `dict' as no longer watched. The callback granted
`watcher_id' by @ref{54e,,PyDict_AddWatcher()} will no longer be called when
`dict' is modified or deallocated. The dict must previously have been
watched by this watcher. Return @code{0} on success or @code{-1} on error.


Ajouté dans la version 3.12.

@end deffn

@geindex PyDict_WatchEvent (C type)
@anchor{c-api/dict c PyDict_WatchEvent}@anchor{4b58}
@deffn {C Type} type PyDict_WatchEvent

Enumeration of possible dictionary watcher events: @code{PyDict_EVENT_ADDED},
@code{PyDict_EVENT_MODIFIED}, @code{PyDict_EVENT_DELETED}, @code{PyDict_EVENT_CLONED},
@code{PyDict_EVENT_CLEARED}, or @code{PyDict_EVENT_DEALLOCATED}.


Ajouté dans la version 3.12.

@end deffn

@geindex PyDict_WatchCallback (C type)
@anchor{c-api/dict c PyDict_WatchCallback}@anchor{4b59}
@deffn {C Type} typedef int (*PyDict_WatchCallback)(@ref{4b58,,PyDict_WatchEvent} event, @ref{32f,,PyObject} *dict, @ref{32f,,PyObject} *key, @ref{32f,,PyObject} *new_value)

Type of a dict watcher callback function.

If `event' is @code{PyDict_EVENT_CLEARED} or @code{PyDict_EVENT_DEALLOCATED}, both
`key' and `new_value' will be @code{NULL}. If `event' is @code{PyDict_EVENT_ADDED}
or @code{PyDict_EVENT_MODIFIED}, `new_value' will be the new value for `key'.
If `event' is @code{PyDict_EVENT_DELETED}, `key' is being deleted from the
dictionary and `new_value' will be @code{NULL}.

@code{PyDict_EVENT_CLONED} occurs when `dict' was previously empty and another
dict is merged into it. To maintain efficiency of this operation, per-key
@code{PyDict_EVENT_ADDED} events are not issued in this case; instead a
single @code{PyDict_EVENT_CLONED} is issued, and `key' will be the source
dictionary.

The callback may inspect but must not modify `dict'; doing so could have
unpredictable effects, including infinite recursion. Do not trigger Python
code execution in the callback, as it could modify the dict as a side effect.

If `event' is @code{PyDict_EVENT_DEALLOCATED}, taking a new reference in the
callback to the about-to-be-destroyed dictionary will resurrect it and
prevent it from being freed at this time. When the resurrected object is
destroyed later, any watcher callbacks active at that time will be called
again.

Callbacks occur before the notified modification to `dict' takes place, so
the prior state of `dict' can be inspected.

If the callback sets an exception, it must return @code{-1}; this exception will
be printed as an unraisable exception using @ref{345,,PyErr_WriteUnraisable()}.
Otherwise it should return @code{0}.

There may already be a pending exception set on entry to the callback. In
this case, the callback should return @code{0} with the same exception still
set. This means the callback may not call any other API that can set an
exception unless it saves and clears the exception state first, and restores
it before returning.


Ajouté dans la version 3.12.

@end deffn

@node Set Objects,,Objets dictionnaires,Objets conteneurs
@anchor{c-api/set doc}@anchor{4b5a}@anchor{c-api/set set-objects}@anchor{4b5b}@anchor{c-api/set setobjects}@anchor{4b5c}
@subsubsection Set Objects


@geindex object;set
@geindex object;frozenset

This section details the public API for @ref{5c3,,set} and @ref{5c4,,frozenset}
objects.  Any functionality not listed below is best accessed using either
the abstract object protocol (including @ref{396,,PyObject_CallMethod()},
@ref{1931,,PyObject_RichCompareBool()}, @ref{3f9,,PyObject_Hash()},
@ref{1018,,PyObject_Repr()}, @ref{492a,,PyObject_IsTrue()}, @ref{1579,,PyObject_Print()}, and
@ref{4929,,PyObject_GetIter()}) or the abstract number protocol (including
@ref{48fd,,PyNumber_And()}, @ref{4916,,PyNumber_Subtract()}, @ref{4911,,PyNumber_Or()},
@ref{4918,,PyNumber_Xor()}, @ref{4902,,PyNumber_InPlaceAnd()},
@ref{490a,,PyNumber_InPlaceSubtract()}, @ref{4906,,PyNumber_InPlaceOr()}, and
@ref{490c,,PyNumber_InPlaceXor()}).

@geindex PySetObject (C type)
@anchor{c-api/set c PySetObject}@anchor{4b5d}
@deffn {C Type} type PySetObject

This subtype of @ref{32f,,PyObject} is used to hold the internal data for both
@ref{5c3,,set} and @ref{5c4,,frozenset} objects.  It is like a @ref{3b8,,PyDictObject}
in that it is a fixed size for small sets (much like tuple storage) and will
point to a separate, variable sized block of memory for medium and large sized
sets (much like list storage). None of the fields of this structure should be
considered public and all are subject to change.  All access should be done through
the documented API rather than by manipulating the values in the structure.
@end deffn

@geindex PySet_Type (C var)
@anchor{c-api/set c PySet_Type}@anchor{4945}
@deffn {C Variable} @ref{a93,,PyTypeObject} PySet_Type
` Part of the @ref{53e,,Stable ABI}.'
This is an instance of @ref{a93,,PyTypeObject} representing the Python
@ref{5c3,,set} type.
@end deffn

@geindex PyFrozenSet_Type (C var)
@anchor{c-api/set c PyFrozenSet_Type}@anchor{48c8}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyFrozenSet_Type
` Part of the @ref{53e,,Stable ABI}.'
This is an instance of @ref{a93,,PyTypeObject} representing the Python
@ref{5c4,,frozenset} type.
@end deffn

The following type check macros work on pointers to any Python object. Likewise,
the constructor functions work with any iterable Python object.

@geindex PySet_Check (C function)
@anchor{c-api/set c PySet_Check}@anchor{4b5e}
@deffn {C Fonction} int PySet_Check (PyObject *p)

Return true if `p' is a @ref{5c3,,set} object or an instance of a subtype.
This function always succeeds.
@end deffn

@geindex PyFrozenSet_Check (C function)
@anchor{c-api/set c PyFrozenSet_Check}@anchor{4b5f}
@deffn {C Fonction} int PyFrozenSet_Check (PyObject *p)

Return true if `p' is a @ref{5c4,,frozenset} object or an instance of a
subtype.  This function always succeeds.
@end deffn

@geindex PyAnySet_Check (C function)
@anchor{c-api/set c PyAnySet_Check}@anchor{4b60}
@deffn {C Fonction} int PyAnySet_Check (PyObject *p)

Return true if `p' is a @ref{5c3,,set} object, a @ref{5c4,,frozenset} object, or an
instance of a subtype.  This function always succeeds.
@end deffn

@geindex PySet_CheckExact (C function)
@anchor{c-api/set c PySet_CheckExact}@anchor{889}
@deffn {C Fonction} int PySet_CheckExact (PyObject *p)

Return true if `p' is a @ref{5c3,,set} object but not an instance of a
subtype.  This function always succeeds.


Ajouté dans la version 3.10.

@end deffn

@geindex PyAnySet_CheckExact (C function)
@anchor{c-api/set c PyAnySet_CheckExact}@anchor{4b61}
@deffn {C Fonction} int PyAnySet_CheckExact (PyObject *p)

Return true if `p' is a @ref{5c3,,set} object or a @ref{5c4,,frozenset} object but
not an instance of a subtype.  This function always succeeds.
@end deffn

@geindex PyFrozenSet_CheckExact (C function)
@anchor{c-api/set c PyFrozenSet_CheckExact}@anchor{4b62}
@deffn {C Fonction} int PyFrozenSet_CheckExact (PyObject *p)

Return true if `p' is a @ref{5c4,,frozenset} object but not an instance of a
subtype.  This function always succeeds.
@end deffn

@geindex PySet_New (C function)
@anchor{c-api/set c PySet_New}@anchor{13fb}
@deffn {C Fonction} @ref{32f,,PyObject} *PySet_New (PyObject *iterable)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{5c3,,set} containing objects returned by the `iterable'.  The
`iterable' may be @code{NULL} to create a new empty set.  Return the new set on
success or @code{NULL} on failure.  Raise @ref{522,,TypeError} if `iterable' is not
actually iterable.  The constructor is also useful for copying a set
(@code{c=set(s)}).
@end deffn

@geindex PyFrozenSet_New (C function)
@anchor{c-api/set c PyFrozenSet_New}@anchor{13fc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrozenSet_New (PyObject *iterable)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new @ref{5c4,,frozenset} containing objects returned by the `iterable'.
The `iterable' may be @code{NULL} to create a new empty frozenset.  Return the new
set on success or @code{NULL} on failure.  Raise @ref{522,,TypeError} if `iterable' is
not actually iterable.
@end deffn

The following functions and macros are available for instances of @ref{5c3,,set}
or @ref{5c4,,frozenset} or instances of their subtypes.

@geindex PySet_Size (C function)
@anchor{c-api/set c PySet_Size}@anchor{1400}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySet_Size (PyObject *anyset)
` Part of the @ref{53e,,Stable ABI}.'
@geindex built-in function;len

Return the length of a @ref{5c3,,set} or @ref{5c4,,frozenset} object. Equivalent to
@code{len(anyset)}.  Raises a @ref{561,,SystemError} if `anyset' is not a
@ref{5c3,,set}, @ref{5c4,,frozenset}, or an instance of a subtype.
@end deffn

@geindex PySet_GET_SIZE (C function)
@anchor{c-api/set c PySet_GET_SIZE}@anchor{4b63}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySet_GET_SIZE (PyObject *anyset)

Macro form of @ref{1400,,PySet_Size()} without error checking.
@end deffn

@geindex PySet_Contains (C function)
@anchor{c-api/set c PySet_Contains}@anchor{13ff}
@deffn {C Fonction} int PySet_Contains (PyObject *anyset, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} if found, @code{0} if not found, and @code{-1} if an error is encountered.  Unlike
the Python @ref{1ee0,,__contains__()} method, this function does not automatically
convert unhashable sets into temporary frozensets.  Raise a @ref{522,,TypeError} if
the `key' is unhashable. Raise @ref{561,,SystemError} if `anyset' is not a
@ref{5c3,,set}, @ref{5c4,,frozenset}, or an instance of a subtype.
@end deffn

@geindex PySet_Add (C function)
@anchor{c-api/set c PySet_Add}@anchor{13fd}
@deffn {C Fonction} int PySet_Add (PyObject *set, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Add `key' to a @ref{5c3,,set} instance.  Also works with @ref{5c4,,frozenset}
instances (like @ref{47d8,,PyTuple_SetItem()} it can be used to fill in the values
of brand new frozensets before they are exposed to other code).  Return @code{0} on
success or @code{-1} on failure. Raise a @ref{522,,TypeError} if the `key' is
unhashable. Raise a @ref{164b,,MemoryError} if there is no room to grow.  Raise a
@ref{561,,SystemError} if `set' is not an instance of @ref{5c3,,set} or its
subtype.
@end deffn

The following functions are available for instances of @ref{5c3,,set} or its
subtypes but not for instances of @ref{5c4,,frozenset} or its subtypes.

@geindex PySet_Discard (C function)
@anchor{c-api/set c PySet_Discard}@anchor{13fe}
@deffn {C Fonction} int PySet_Discard (PyObject *set, PyObject *key)
` Part of the @ref{53e,,Stable ABI}.'
Return @code{1} if found and removed, @code{0} if not found (no action taken), and @code{-1} if an
error is encountered.  Does not raise @ref{33a,,KeyError} for missing keys.  Raise a
@ref{522,,TypeError} if the `key' is unhashable.  Unlike the Python @ref{21c5,,discard()}
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise @ref{561,,SystemError} if `set' is not an
instance of @ref{5c3,,set} or its subtype.
@end deffn

@geindex PySet_Pop (C function)
@anchor{c-api/set c PySet_Pop}@anchor{4944}
@deffn {C Fonction} @ref{32f,,PyObject} *PySet_Pop (PyObject *set)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new reference to an arbitrary object in the `set', and removes the
object from the `set'.  Return @code{NULL} on failure.  Raise @ref{33a,,KeyError} if the
set is empty. Raise a @ref{561,,SystemError} if `set' is not an instance of
@ref{5c3,,set} or its subtype.
@end deffn

@geindex PySet_Clear (C function)
@anchor{c-api/set c PySet_Clear}@anchor{4943}
@deffn {C Fonction} int PySet_Clear (PyObject *set)
` Part of the @ref{53e,,Stable ABI}.'
Empty an existing set of all elements. Return @code{0} on
success. Return @code{-1} and raise @ref{561,,SystemError} if `set' is not an instance of
@ref{5c3,,set} or its subtype.
@end deffn

@node Objets fonctions<2>,Autres objets<2>,Objets conteneurs,Couche des objets concrets
@anchor{c-api/concrete function-objects}@anchor{4b64}@anchor{c-api/concrete otherobjects}@anchor{4b65}
@subsection Objets fonctions


@menu
* Objets fonction:: 
* Instance Method Objects:: 
* Objets méthode: Objets méthode<2>. 
* Objets Cellules:: 
* Objets code: Objets code<2>. 
* Extra information:: 

@end menu

@node Objets fonction,Instance Method Objects,,Objets fonctions<2>
@anchor{c-api/function doc}@anchor{4b66}@anchor{c-api/function function-objects}@anchor{4b67}@anchor{c-api/function id1}@anchor{4b68}
@subsubsection Objets fonction


@geindex object;function

Certaines fonctions sont spécifiques aux fonctions Python.

@geindex PyFunctionObject (C type)
@anchor{c-api/function c PyFunctionObject}@anchor{54d}
@deffn {C Type} type PyFunctionObject

La structure C utilisée pour les fonctions.
@end deffn

@geindex PyFunction_Type (C var)
@anchor{c-api/function c PyFunction_Type}@anchor{4b69}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyFunction_Type

@geindex MethodType (in module types)

C'est une instance de @ref{a93,,PyTypeObject} et représente le type fonction en Python. Il est exposé aux développeurs comme @code{types.FunctionType}.
@end deffn

@geindex PyFunction_Check (C function)
@anchor{c-api/function c PyFunction_Check}@anchor{4b6a}
@deffn {C Fonction} int PyFunction_Check (PyObject *o)

Renvoie vrai si `o' est un objet de type fonction (a comme type @ref{4b69,,PyFunction_Type}). Le paramètre ne doit pas être @code{NULL}. Cette fonction réussit toujours.
@end deffn

@geindex PyFunction_New (C function)
@anchor{c-api/function c PyFunction_New}@anchor{4b6b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_New (PyObject *code, PyObject *globals)
`Valeur de retour : nouvelle référence.'
Renvoie une nouvelle fonction associée avec l'objet `code'. `globals' doit être un dictionnaire avec les variables globales accessibles à la fonction.

The function's docstring and name are retrieved from the code object.
@ref{1e81,,__module__}
is retrieved from `globals'. The argument defaults, annotations and closure are
set to @code{NULL}. @ref{1e80,,__qualname__} is set to the same value as
the code object's @ref{1ebc,,co_qualname} field.
@end deffn

@geindex PyFunction_NewWithQualName (C function)
@anchor{c-api/function c PyFunction_NewWithQualName}@anchor{4b6c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_NewWithQualName (PyObject *code, PyObject *globals, PyObject *qualname)
`Valeur de retour : nouvelle référence.'
As @ref{4b6b,,PyFunction_New()}, but also allows setting the function object's
@ref{1e80,,__qualname__} attribute.
`qualname' should be a unicode object or @code{NULL};
if @code{NULL}, the @code{__qualname__} attribute is set to the same value as
the code object's @ref{1ebc,,co_qualname} field.


Ajouté dans la version 3.3.

@end deffn

@geindex PyFunction_GetCode (C function)
@anchor{c-api/function c PyFunction_GetCode}@anchor{4b6d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_GetCode (PyObject *op)
`Valeur de retour : référence empruntée.'
Renvoie l'objet code associé avec l'objet de la fonction `op'.
@end deffn

@geindex PyFunction_GetGlobals (C function)
@anchor{c-api/function c PyFunction_GetGlobals}@anchor{4b6e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_GetGlobals (PyObject *op)
`Valeur de retour : référence empruntée.'
Renvoie le dictionnaire global associé avec l'objet de la fonction `op'.
@end deffn

@geindex PyFunction_GetModule (C function)
@anchor{c-api/function c PyFunction_GetModule}@anchor{4b6f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_GetModule (PyObject *op)
`Valeur de retour : référence empruntée.'
Return a @ref{334,,borrowed reference} to the @ref{1e81,,__module__}
attribute of the @ref{296,,function object} `op'.
It can be `NULL'.

This is normally a @ref{435,,string} containing the module name,
but can be set to any other object by Python code.
@end deffn

@geindex PyFunction_GetDefaults (C function)
@anchor{c-api/function c PyFunction_GetDefaults}@anchor{4b70}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_GetDefaults (PyObject *op)
`Valeur de retour : référence empruntée.'
Renvoie les valeurs par défaut de l'argument de l'objet de la fonction `op'. Cela peut être un tuple d'arguments ou @code{NULL}.
@end deffn

@geindex PyFunction_SetDefaults (C function)
@anchor{c-api/function c PyFunction_SetDefaults}@anchor{4b71}
@deffn {C Fonction} int PyFunction_SetDefaults (PyObject *op, PyObject *defaults)

Définir les valeurs par défaut de l'argument pour l'objet de la fonction `op'. `defaults' doit être @code{Py_None} ou un tuple.

Lève @ref{561,,SystemError} et renvoie @code{-1} en cas de d'échec.
@end deffn

@geindex PyFunction_SetVectorcall (C function)
@anchor{c-api/function c PyFunction_SetVectorcall}@anchor{54c}
@deffn {C Fonction} void PyFunction_SetVectorcall (PyFunctionObject *func, vectorcallfunc vectorcall)

Set the vectorcall field of a given function object `func'.

Warning: extensions using this API must preserve the behavior
of the unaltered (default) vectorcall function!


Ajouté dans la version 3.12.

@end deffn

@geindex PyFunction_GetClosure (C function)
@anchor{c-api/function c PyFunction_GetClosure}@anchor{4b72}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_GetClosure (PyObject *op)
`Valeur de retour : référence empruntée.'
Renvoie la fermeture associée avec l'objet de la fonction `op'. Cela peut être @code{NULL} ou un tuple d'objets cellule.
@end deffn

@geindex PyFunction_SetClosure (C function)
@anchor{c-api/function c PyFunction_SetClosure}@anchor{4b73}
@deffn {C Fonction} int PyFunction_SetClosure (PyObject *op, PyObject *closure)

Définir la fermeture associée avec l'objet de la fonction `op'. `closure' doit être @code{Py_None} ou un tuple d'objets cellule.

Lève @ref{561,,SystemError} et renvoie @code{-1} en cas de d'échec.
@end deffn

@geindex PyFunction_GetAnnotations (C function)
@anchor{c-api/function c PyFunction_GetAnnotations}@anchor{1748}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFunction_GetAnnotations (PyObject *op)
`Valeur de retour : référence empruntée.'
Renvoie les annotations de l'objet de la fonction `op'. Cela peut être un dictionnaire mutable ou @code{NULL}.
@end deffn

@geindex PyFunction_SetAnnotations (C function)
@anchor{c-api/function c PyFunction_SetAnnotations}@anchor{4b74}
@deffn {C Fonction} int PyFunction_SetAnnotations (PyObject *op, PyObject *annotations)

Définir les annotations pour l'objet de la fonction `op'. `annotations' doit être un dictionnaire ou @code{Py_None}.

Lève @ref{561,,SystemError} et renvoie @code{-1} en cas de d'échec.
@end deffn

@geindex PyFunction_AddWatcher (C function)
@anchor{c-api/function c PyFunction_AddWatcher}@anchor{4b75}
@deffn {C Fonction} int PyFunction_AddWatcher (PyFunction_WatchCallback callback)

Register `callback' as a function watcher for the current interpreter.
Return an ID which may be passed to @ref{4b76,,PyFunction_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


Ajouté dans la version 3.12.

@end deffn

@geindex PyFunction_ClearWatcher (C function)
@anchor{c-api/function c PyFunction_ClearWatcher}@anchor{4b76}
@deffn {C Fonction} int PyFunction_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{4b75,,PyFunction_AddWatcher()} for the current interpreter.
Return @code{0} on success, or @code{-1} and set an exception on error
(e.g.  if the given `watcher_id' was never registered.)


Ajouté dans la version 3.12.

@end deffn

@geindex PyFunction_WatchEvent (C type)
@anchor{c-api/function c PyFunction_WatchEvent}@anchor{4b77}
@deffn {C Type} type PyFunction_WatchEvent

Enumeration of possible function watcher events:
- @code{PyFunction_EVENT_CREATE}
- @code{PyFunction_EVENT_DESTROY}
- @code{PyFunction_EVENT_MODIFY_CODE}
- @code{PyFunction_EVENT_MODIFY_DEFAULTS}
- @code{PyFunction_EVENT_MODIFY_KWDEFAULTS}


Ajouté dans la version 3.12.

@end deffn

@geindex PyFunction_WatchCallback (C type)
@anchor{c-api/function c PyFunction_WatchCallback}@anchor{4b78}
@deffn {C Type} typedef int (*PyFunction_WatchCallback)(@ref{4b77,,PyFunction_WatchEvent} event, @ref{54d,,PyFunctionObject} *func, @ref{32f,,PyObject} *new_value)

Type of a function watcher callback function.

If `event' is @code{PyFunction_EVENT_CREATE} or @code{PyFunction_EVENT_DESTROY}
then `new_value' will be @code{NULL}. Otherwise, `new_value' will hold a
@ref{334,,borrowed reference} to the new value that is about to be stored in
`func' for the attribute that is being modified.

The callback may inspect but must not modify `func'; doing so could have
unpredictable effects, including infinite recursion.

If `event' is @code{PyFunction_EVENT_CREATE}, then the callback is invoked
after @cite{func} has been fully initialized. Otherwise, the callback is invoked
before the modification to `func' takes place, so the prior state of `func'
can be inspected. The runtime is permitted to optimize away the creation of
function objects when possible. In such cases no event will be emitted.
Although this creates the possibility of an observable difference of
runtime behavior depending on optimization decisions, it does not change
the semantics of the Python code being executed.

If `event' is @code{PyFunction_EVENT_DESTROY},  Taking a reference in the
callback to the about-to-be-destroyed function will resurrect it, preventing
it from being freed at this time. When the resurrected object is destroyed
later, any watcher callbacks active at that time will be called again.

If the callback sets an exception, it must return @code{-1}; this exception will
be printed as an unraisable exception using @ref{345,,PyErr_WriteUnraisable()}.
Otherwise it should return @code{0}.

There may already be a pending exception set on entry to the callback. In
this case, the callback should return @code{0} with the same exception still
set. This means the callback may not call any other API that can set an
exception unless it saves and clears the exception state first, and restores
it before returning.


Ajouté dans la version 3.12.

@end deffn

@node Instance Method Objects,Objets méthode<2>,Objets fonction,Objets fonctions<2>
@anchor{c-api/method doc}@anchor{4b79}@anchor{c-api/method instance-method-objects}@anchor{4b7a}@anchor{c-api/method instancemethod-objects}@anchor{4b7b}
@subsubsection Instance Method Objects


@geindex object;instancemethod

An instance method is a wrapper for a @ref{142b,,PyCFunction} and the new way
to bind a @ref{142b,,PyCFunction} to a class object. It replaces the former call
@code{PyMethod_New(func, NULL, class)}.

@geindex PyInstanceMethod_Type (C var)
@anchor{c-api/method c PyInstanceMethod_Type}@anchor{4b7c}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyInstanceMethod_Type

This instance of @ref{a93,,PyTypeObject} represents the Python instance
method type. It is not exposed to Python programs.
@end deffn

@geindex PyInstanceMethod_Check (C function)
@anchor{c-api/method c PyInstanceMethod_Check}@anchor{4b7d}
@deffn {C Fonction} int PyInstanceMethod_Check (PyObject *o)

Return true if `o' is an instance method object (has type
@ref{4b7c,,PyInstanceMethod_Type}).  The parameter must not be @code{NULL}.
This function always succeeds.
@end deffn

@geindex PyInstanceMethod_New (C function)
@anchor{c-api/method c PyInstanceMethod_New}@anchor{4b7e}
@deffn {C Fonction} @ref{32f,,PyObject} *PyInstanceMethod_New (PyObject *func)
`Valeur de retour : nouvelle référence.'
Return a new instance method object, with `func' being any callable object.
`func' is the function that will be called when the instance method is
called.
@end deffn

@geindex PyInstanceMethod_Function (C function)
@anchor{c-api/method c PyInstanceMethod_Function}@anchor{4b7f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyInstanceMethod_Function (PyObject *im)
`Valeur de retour : référence empruntée.'
Return the function object associated with the instance method `im'.
@end deffn

@geindex PyInstanceMethod_GET_FUNCTION (C function)
@anchor{c-api/method c PyInstanceMethod_GET_FUNCTION}@anchor{4b80}
@deffn {C Fonction} @ref{32f,,PyObject} *PyInstanceMethod_GET_FUNCTION (PyObject *im)
`Valeur de retour : référence empruntée.'
Macro version of @ref{4b7f,,PyInstanceMethod_Function()} which avoids error checking.
@end deffn

@node Objets méthode<2>,Objets Cellules,Instance Method Objects,Objets fonctions<2>
@anchor{c-api/method id1}@anchor{4b81}@anchor{c-api/method method-objects}@anchor{4b82}
@subsubsection Objets méthode


@geindex object;method

Methods are bound function objects. Methods are always bound to an instance of
a user-defined class. Unbound methods (methods bound to a class object) are
no longer available.

@geindex PyMethod_Type (C var)
@anchor{c-api/method c PyMethod_Type}@anchor{4b83}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyMethod_Type

@geindex MethodType (in module types)

This instance of @ref{a93,,PyTypeObject} represents the Python method type.  This
is exposed to Python programs as @code{types.MethodType}.
@end deffn

@geindex PyMethod_Check (C function)
@anchor{c-api/method c PyMethod_Check}@anchor{4b84}
@deffn {C Fonction} int PyMethod_Check (PyObject *o)

Return true if `o' is a method object (has type @ref{4b83,,PyMethod_Type}).  The
parameter must not be @code{NULL}.  This function always succeeds.
@end deffn

@geindex PyMethod_New (C function)
@anchor{c-api/method c PyMethod_New}@anchor{4b85}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMethod_New (PyObject *func, PyObject *self)
`Valeur de retour : nouvelle référence.'
Return a new method object, with `func' being any callable object and `self'
the instance the method should be bound. `func' is the function that will
be called when the method is called. `self' must not be @code{NULL}.
@end deffn

@geindex PyMethod_Function (C function)
@anchor{c-api/method c PyMethod_Function}@anchor{4b86}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMethod_Function (PyObject *meth)
`Valeur de retour : référence empruntée.'
Return the function object associated with the method `meth'.
@end deffn

@geindex PyMethod_GET_FUNCTION (C function)
@anchor{c-api/method c PyMethod_GET_FUNCTION}@anchor{4b87}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMethod_GET_FUNCTION (PyObject *meth)
`Valeur de retour : référence empruntée.'
Macro version of @ref{4b86,,PyMethod_Function()} which avoids error checking.
@end deffn

@geindex PyMethod_Self (C function)
@anchor{c-api/method c PyMethod_Self}@anchor{4b88}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMethod_Self (PyObject *meth)
`Valeur de retour : référence empruntée.'
Return the instance associated with the method `meth'.
@end deffn

@geindex PyMethod_GET_SELF (C function)
@anchor{c-api/method c PyMethod_GET_SELF}@anchor{4b89}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMethod_GET_SELF (PyObject *meth)
`Valeur de retour : référence empruntée.'
Macro version of @ref{4b88,,PyMethod_Self()} which avoids error checking.
@end deffn

@node Objets Cellules,Objets code<2>,Objets méthode<2>,Objets fonctions<2>
@anchor{c-api/cell doc}@anchor{4b8a}@anchor{c-api/cell cell-objects}@anchor{6eb}@anchor{c-api/cell id1}@anchor{4b8b}
@subsubsection Objets Cellules


Les objets "Cellules" (`cell' en anglais) sont utilisés pour implémenter des variables référencées dans de multiples environnements. Pour chacune de ces variables, un objet cellule est créé pour stocker sa valeur ; les variables locales de chaque pile d'exécution qui référence cette valeur contiennent une référence sur les cellules des autres environnements qui utilisent aussi cette variable. Quand la valeur est accédée, la valeur de la cellule est utilisée, au lei de celle de l'objet cellule proprement dit. Ce dé-référencement de l'objet cellule requiert l'intervention du `bytecode' généré ; il n'est pas automatiquement dé-référencé quand il est accédé. Il est plausible que les objets cellules ne soit utilisés ailleurs.

@geindex PyCellObject (C type)
@anchor{c-api/cell c PyCellObject}@anchor{4b8c}
@deffn {C Type} type PyCellObject

Structure C utilisée pour les objets cellules.
@end deffn

@geindex PyCell_Type (C var)
@anchor{c-api/cell c PyCell_Type}@anchor{4b8d}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyCell_Type

Type objet correspondant aux objets cellules.
@end deffn

@geindex PyCell_Check (C function)
@anchor{c-api/cell c PyCell_Check}@anchor{4b8e}
@deffn {C Fonction} int PyCell_Check (PyObject *ob)

Return true if `ob' is a cell object; `ob' must not be @code{NULL}.  This
function always succeeds.
@end deffn

@geindex PyCell_New (C function)
@anchor{c-api/cell c PyCell_New}@anchor{4b8f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCell_New (PyObject *ob)
`Valeur de retour : nouvelle référence.'
Create and return a new cell object containing the value `ob'. The parameter may
be @code{NULL}.
@end deffn

@geindex PyCell_Get (C function)
@anchor{c-api/cell c PyCell_Get}@anchor{4b90}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCell_Get (PyObject *cell)
`Valeur de retour : nouvelle référence.'
Return the contents of the cell `cell', which can be @code{NULL}.
If `cell' is not a cell object, returns @code{NULL} with an exception set.
@end deffn

@geindex PyCell_GET (C function)
@anchor{c-api/cell c PyCell_GET}@anchor{4b91}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCell_GET (PyObject *cell)
`Valeur de retour : référence empruntée.'
Return the contents of the cell `cell', but without checking that `cell' is
non-@code{NULL} and a cell object.
@end deffn

@geindex PyCell_Set (C function)
@anchor{c-api/cell c PyCell_Set}@anchor{4b92}
@deffn {C Fonction} int PyCell_Set (PyObject *cell, PyObject *value)

Set the contents of the cell object `cell' to `value'.  This releases the
reference to any current content of the cell. `value' may be @code{NULL}.  `cell'
must be non-@code{NULL}.

On success, return @code{0}.
If `cell' is not a cell object, set an exception and return @code{-1}.
@end deffn

@geindex PyCell_SET (C function)
@anchor{c-api/cell c PyCell_SET}@anchor{89b}
@deffn {C Fonction} void PyCell_SET (PyObject *cell, PyObject *value)

Sets the value of the cell object `cell' to `value'.  No reference counts are
adjusted, and no checks are made for safety; `cell' must be non-@code{NULL} and must
be a cell object.
@end deffn

@geindex object;code
@geindex code object

@node Objets code<2>,Extra information,Objets Cellules,Objets fonctions<2>
@anchor{c-api/code doc}@anchor{4b93}@anchor{c-api/code code-objects}@anchor{4b94}@anchor{c-api/code codeobjects}@anchor{59f}
@subsubsection Objets code


Les objets `Code' sont spécifiques à l'implémentation bas niveau de CPython. Chacun d'eux représente une partie de code exécutable, qui n'a pas encore été lié dans une fonction.

@geindex PyCodeObject (C type)
@anchor{c-api/code c PyCodeObject}@anchor{761}
@deffn {C Type} type PyCodeObject

La structure C utilisée pour décrire les objets `Code'. Les attributs de cette structure sont sujets à changer à tout moment.
@end deffn

@geindex PyCode_Type (C var)
@anchor{c-api/code c PyCode_Type}@anchor{4b95}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyCode_Type

This is an instance of @ref{a93,,PyTypeObject} representing the Python
@ref{1cd,,code object}.
@end deffn

@geindex PyCode_Check (C function)
@anchor{c-api/code c PyCode_Check}@anchor{4b96}
@deffn {C Fonction} int PyCode_Check (PyObject *co)

Return true if `co' is a @ref{1cd,,code object}.
This function always succeeds.
@end deffn

@geindex PyCode_GetNumFree (C function)
@anchor{c-api/code c PyCode_GetNumFree}@anchor{4b97}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyCode_GetNumFree (PyCodeObject *co)

Return the number of @ref{1ec4,,free (closure) variables}
in a code object.
@end deffn

@geindex PyUnstable_Code_GetFirstFree (C function)
@anchor{c-api/code c PyUnstable_Code_GetFirstFree}@anchor{37c}
@deffn {C Fonction} int PyUnstable_Code_GetFirstFree (PyCodeObject *co)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Return the position of the first @ref{1ec4,,free (closure) variable}
in a code object.


Modifié dans la version 3.13: Renamed from @code{PyCode_GetFirstFree} as part of @ref{532,,Unstable C API}.
The old name is deprecated, but will remain available until the
signature changes again.

@end deffn

@geindex PyUnstable_Code_New (C function)
@anchor{c-api/code c PyUnstable_Code_New}@anchor{4b98}
@deffn {C Fonction} @ref{761,,PyCodeObject} *PyUnstable_Code_New (int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Return a new code object.  If you need a dummy code object to create a frame,
use @ref{132f,,PyCode_NewEmpty()} instead.

Since the definition of the bytecode changes often, calling
@ref{4b98,,PyUnstable_Code_New()} directly can bind you to a precise Python version.

The many arguments of this function are inter-dependent in complex
ways, meaning that subtle changes to values are likely to result in incorrect
execution or VM crashes. Use this function only with extreme care.


Modifié dans la version 3.11: Added @code{qualname} and @code{exceptiontable} parameters.


@geindex PyCode_New (C function)


Modifié dans la version 3.12: Renamed from @code{PyCode_New} as part of @ref{532,,Unstable C API}.
The old name is deprecated, but will remain available until the
signature changes again.

@end deffn

@geindex PyUnstable_Code_NewWithPosOnlyArgs (C function)
@anchor{c-api/code c PyUnstable_Code_NewWithPosOnlyArgs}@anchor{4b99}
@deffn {C Fonction} @ref{761,,PyCodeObject} *PyUnstable_Code_NewWithPosOnlyArgs (int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Similar to @ref{4b98,,PyUnstable_Code_New()}, but with an extra "posonlyargcount" for positional-only arguments.
The same caveats that apply to @code{PyUnstable_Code_New} also apply to this function.

@geindex PyCode_NewWithPosOnlyArgs (C function)


Ajouté dans la version 3.8: as @code{PyCode_NewWithPosOnlyArgs}



Modifié dans la version 3.11: Added @code{qualname} and  @code{exceptiontable} parameters.



Modifié dans la version 3.12: Renamed to @code{PyUnstable_Code_NewWithPosOnlyArgs}.
The old name is deprecated, but will remain available until the
signature changes again.

@end deffn

@geindex PyCode_NewEmpty (C function)
@anchor{c-api/code c PyCode_NewEmpty}@anchor{132f}
@deffn {C Fonction} @ref{761,,PyCodeObject} *PyCode_NewEmpty (const char *filename, const char *funcname, int firstlineno)
`Valeur de retour : nouvelle référence.'
Return a new empty code object with the specified filename,
function name, and first line number. The resulting code
object will raise an @code{Exception} if executed.
@end deffn

@geindex PyCode_Addr2Line (C function)
@anchor{c-api/code c PyCode_Addr2Line}@anchor{875}
@deffn {C Fonction} int PyCode_Addr2Line (PyCodeObject *co, int byte_offset)

Return the line number of the instruction that occurs on or before @code{byte_offset} and ends after it.
If you just need the line number of a frame, use @ref{775,,PyFrame_GetLineNumber()} instead.

For efficiently iterating over the line numbers in a code object, use 
@geindex Python Enhancement Proposals; PEP 0626#out-of-process-debuggers-and-profilers
the API described in PEP 626@footnote{https://peps.python.org/pep-0626/#out-of-process-debuggers-and-profilers}.
@end deffn

@geindex PyCode_Addr2Location (C function)
@anchor{c-api/code c PyCode_Addr2Location}@anchor{59e}
@deffn {C Fonction} int PyCode_Addr2Location (PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)

Sets the passed @code{int} pointers to the source code line and column numbers
for the instruction at @code{byte_offset}. Sets the value to @code{0} when
information is not available for any particular element.

Returns @code{1} if the function succeeds and 0 otherwise.


Ajouté dans la version 3.11.

@end deffn

@geindex PyCode_GetCode (C function)
@anchor{c-api/code c PyCode_GetCode}@anchor{762}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCode_GetCode (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_code')}.
Returns a strong reference to a @ref{77c,,PyBytesObject} representing the
bytecode in a code object. On error, @code{NULL} is returned and an exception
is raised.

This @code{PyBytesObject} may be created on-demand by the interpreter and does
not necessarily represent the bytecode actually executed by CPython. The
primary use case for this function is debuggers and profilers.


Ajouté dans la version 3.11.

@end deffn

@geindex PyCode_GetVarnames (C function)
@anchor{c-api/code c PyCode_GetVarnames}@anchor{763}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCode_GetVarnames (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_varnames')}.
Returns a new reference to a @ref{4a09,,PyTupleObject} containing the names of
the local variables. On error, @code{NULL} is returned and an exception
is raised.


Ajouté dans la version 3.11.

@end deffn

@geindex PyCode_GetCellvars (C function)
@anchor{c-api/code c PyCode_GetCellvars}@anchor{764}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCode_GetCellvars (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_cellvars')}.
Returns a new reference to a @ref{4a09,,PyTupleObject} containing the names of
the local variables that are referenced by nested functions. On error, @code{NULL}
is returned and an exception is raised.


Ajouté dans la version 3.11.

@end deffn

@geindex PyCode_GetFreevars (C function)
@anchor{c-api/code c PyCode_GetFreevars}@anchor{765}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCode_GetFreevars (PyCodeObject *co)

Equivalent to the Python code @code{getattr(co, 'co_freevars')}.
Returns a new reference to a @ref{4a09,,PyTupleObject} containing the names of
the @ref{1ec4,,free (closure) variables}. On error, @code{NULL} is returned
and an exception is raised.


Ajouté dans la version 3.11.

@end deffn

@geindex PyCode_AddWatcher (C function)
@anchor{c-api/code c PyCode_AddWatcher}@anchor{552}
@deffn {C Fonction} int PyCode_AddWatcher (PyCode_WatchCallback callback)

Register `callback' as a code object watcher for the current interpreter.
Return an ID which may be passed to @ref{553,,PyCode_ClearWatcher()}.
In case of error (e.g. no more watcher IDs available),
return @code{-1} and set an exception.


Ajouté dans la version 3.12.

@end deffn

@geindex PyCode_ClearWatcher (C function)
@anchor{c-api/code c PyCode_ClearWatcher}@anchor{553}
@deffn {C Fonction} int PyCode_ClearWatcher (int watcher_id)

Clear watcher identified by `watcher_id' previously returned from
@ref{552,,PyCode_AddWatcher()} for the current interpreter.
Return @code{0} on success, or @code{-1} and set an exception on error
(e.g. if the given `watcher_id' was never registered.)


Ajouté dans la version 3.12.

@end deffn

@geindex PyCodeEvent (C type)
@anchor{c-api/code c PyCodeEvent}@anchor{4b9a}
@deffn {C Type} type PyCodeEvent

Enumeration of possible code object watcher events:
- @code{PY_CODE_EVENT_CREATE}
- @code{PY_CODE_EVENT_DESTROY}


Ajouté dans la version 3.12.

@end deffn

@geindex PyCode_WatchCallback (C type)
@anchor{c-api/code c PyCode_WatchCallback}@anchor{4b9b}
@deffn {C Type} typedef int (*PyCode_WatchCallback)(@ref{4b9a,,PyCodeEvent} event, @ref{761,,PyCodeObject} *co)

Type of a code object watcher callback function.

If `event' is @code{PY_CODE_EVENT_CREATE}, then the callback is invoked
after @cite{co} has been fully initialized. Otherwise, the callback is invoked
before the destruction of `co' takes place, so the prior state of `co'
can be inspected.

If `event' is @code{PY_CODE_EVENT_DESTROY}, taking a reference in the callback
to the about-to-be-destroyed code object will resurrect it and prevent it
from being freed at this time. When the resurrected object is destroyed
later, any watcher callbacks active at that time will be called again.

Users of this API should not rely on internal runtime implementation
details. Such details may include, but are not limited to, the exact
order and timing of creation and destruction of code objects. While
changes in these details may result in differences observable by watchers
(including whether a callback is invoked or not), it does not change
the semantics of the Python code being executed.

If the callback sets an exception, it must return @code{-1}; this exception will
be printed as an unraisable exception using @ref{345,,PyErr_WriteUnraisable()}.
Otherwise it should return @code{0}.

There may already be a pending exception set on entry to the callback. In
this case, the callback should return @code{0} with the same exception still
set. This means the callback may not call any other API that can set an
exception unless it saves and clears the exception state first, and restores
it before returning.


Ajouté dans la version 3.12.

@end deffn

@node Extra information,,Objets code<2>,Objets fonctions<2>
@anchor{c-api/code extra-information}@anchor{4b9c}
@subsubsection Extra information


To support low-level extensions to frame evaluation, such as external
just-in-time compilers, it is possible to attach arbitrary extra data to
code objects.

These functions are part of the unstable C API tier:
this functionality is a CPython implementation detail, and the API
may change without deprecation warnings.

@geindex PyUnstable_Eval_RequestCodeExtraIndex (C function)
@anchor{c-api/code c PyUnstable_Eval_RequestCodeExtraIndex}@anchor{4b9d}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyUnstable_Eval_RequestCodeExtraIndex (freefunc free)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Return a new an opaque index value used to adding data to code objects.

You generally call this function once (per interpreter) and use the result
with @code{PyCode_GetExtra} and @code{PyCode_SetExtra} to manipulate
data on individual code objects.

If `free' is not @code{NULL}: when a code object is deallocated,
`free' will be called on non-@code{NULL} data stored under the new index.
Use @ref{49a0,,Py_DecRef()} when storing @ref{32f,,PyObject}.

@geindex _PyEval_RequestCodeExtraIndex (C function)


Ajouté dans la version 3.6: as @code{_PyEval_RequestCodeExtraIndex}



Modifié dans la version 3.12: Renamed to @code{PyUnstable_Eval_RequestCodeExtraIndex}.
The old private name is deprecated, but will be available until the API
changes.

@end deffn

@geindex PyUnstable_Code_GetExtra (C function)
@anchor{c-api/code c PyUnstable_Code_GetExtra}@anchor{4b9e}
@deffn {C Fonction} int PyUnstable_Code_GetExtra (PyObject *code, Py_ssize_t index, void **extra)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Set `extra' to the extra data stored under the given index.
Return 0 on success. Set an exception and return -1 on failure.

If no data was set under the index, set `extra' to @code{NULL} and return
0 without setting an exception.

@geindex _PyCode_GetExtra (C function)


Ajouté dans la version 3.6: as @code{_PyCode_GetExtra}



Modifié dans la version 3.12: Renamed to @code{PyUnstable_Code_GetExtra}.
The old private name is deprecated, but will be available until the API
changes.

@end deffn

@geindex PyUnstable_Code_SetExtra (C function)
@anchor{c-api/code c PyUnstable_Code_SetExtra}@anchor{4b9f}
@deffn {C Fonction} int PyUnstable_Code_SetExtra (PyObject *code, Py_ssize_t index, void *extra)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Set the extra data stored under the given index to `extra'.
Return 0 on success. Set an exception and return -1 on failure.

@geindex _PyCode_SetExtra (C function)


Ajouté dans la version 3.6: as @code{_PyCode_SetExtra}



Modifié dans la version 3.12: Renamed to @code{PyUnstable_Code_SetExtra}.
The old private name is deprecated, but will be available until the API
changes.

@end deffn

@node Autres objets<2>,,Objets fonctions<2>,Couche des objets concrets
@anchor{c-api/concrete other-objects}@anchor{4ba0}
@subsection Autres objets


@menu
* Objets fichiers:: 
* Module Objects:: 
* Itérateurs: Itérateurs<2>. 
* Les descripteurs:: 
* Slice Objects:: 
* Objets de type MemoryView:: 
* Objets à références faibles: Objets à références faibles<2>. 
* Capsules: Capsules<2>. 
* Objets décrivant les frames:: 
* Objets générateur:: 
* Objets coroutines: Objets coroutines<2>. 
* Context Variables Objects:: 
* Objets DateTime: Objets DateTime<2>. 
* Objects for Type Hinting:: 

@end menu

@node Objets fichiers,Module Objects,,Autres objets<2>
@anchor{c-api/file doc}@anchor{4ba1}@anchor{c-api/file file-objects}@anchor{4ba2}@anchor{c-api/file fileobjects}@anchor{4ba3}
@subsubsection Objets fichiers


@geindex object;file

These APIs are a minimal emulation of the Python 2 C API for built-in file
objects, which used to rely on the buffered I/O (FILE*) support
from the C standard library.  In Python 3, files and streams use the new
@ref{7e,,io} module, which defines several layers over the low-level unbuffered
I/O of the operating system.  The functions described below are
convenience C wrappers over these new APIs, and meant mostly for internal
error reporting in the interpreter; third-party code is advised to access
the @ref{7e,,io} APIs instead.

@geindex PyFile_FromFd (C function)
@anchor{c-api/file c PyFile_FromFd}@anchor{48c1}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFile_FromFd (int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a Python file object from the file descriptor of an already
opened file `fd'.  The arguments `name', `encoding', `errors' and `newline'
can be @code{NULL} to use the defaults; `buffering' can be `-1' to use the
default. `name' is ignored and kept for backward compatibility. Return
@code{NULL} on failure. For a more comprehensive description of the arguments,
please refer to the @ref{506,,io.open()} function documentation.

@cartouche
@quotation Avertissement 
Étant donné que les flux de données Python possèdent leur propre couche de tampon, les mélanger avec des descripteurs de fichiers du niveau du système d'exploitation peut produire des erreurs (comme par exemple un ordre des données inattendu).
@end quotation
@end cartouche


Modifié dans la version 3.2: ignore l'attribut `name'

@end deffn

@geindex PyObject_AsFileDescriptor (C function)
@anchor{c-api/file c PyObject_AsFileDescriptor}@anchor{491e}
@deffn {C Fonction} int PyObject_AsFileDescriptor (PyObject *p)
` Part of the @ref{53e,,Stable ABI}.'
Return the file descriptor associated with `p' as an int.  If the
object is an integer, its value is returned.  If not, the
object's @ref{27cf,,fileno()} method is called if it exists; the
method must return an integer, which is returned as the file descriptor
value.  Sets an exception and returns @code{-1} on failure.
@end deffn

@geindex PyFile_GetLine (C function)
@anchor{c-api/file c PyFile_GetLine}@anchor{48c2}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFile_GetLine (PyObject *p, int n)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex EOFError (built-in exception)

Cette fonction, équivalente à @code{p.readline([n])}, lit une ligne de l'objet `p'. `p' peut être un objet fichier ou n'importe quel objet qui possède une méthode @ref{1307,,readline()}. Si `n' vaut @code{0}, une seule ligne est lue, indépendamment de la taille de la ligne. Si `n' est plus grand que @code{0}, un maximum de `n' octets seront lus en provenance du fichier ; une ligne partielle peut être renvoyée. Dans les deux cas, une chaîne de caractères vide est renvoyée si la fin du fichier est atteinte immédiatement. Cependant, si `n' est plus petit que @code{0}, une ligne est lue indépendamment de sa taille, mais @ref{12b7,,EOFError} est levée si la fin du fichier est atteinte immédiatement.
@end deffn

@geindex PyFile_SetOpenCodeHook (C function)
@anchor{c-api/file c PyFile_SetOpenCodeHook}@anchor{16b4}
@deffn {C Fonction} int PyFile_SetOpenCodeHook (Py_OpenCodeHookFunction handler)

Overrides the normal behavior of @ref{16b2,,io.open_code()} to pass its parameter
through the provided handler.

The `handler' is a function of type:

@geindex Py_OpenCodeHookFunction (C type)
@anchor{c-api/file c Py_OpenCodeHookFunction}@anchor{4ba4}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*Py_OpenCodeHookFunction)(@ref{32f,,PyObject}*, void*)

Equivalent of @ref{32f,,PyObject} *(*)(@ref{32f,,PyObject} *path, void *userData), where `path' is guaranteed to be
@ref{77e,,PyUnicodeObject}.
@end deffn

The `userData' pointer is passed into the hook function. Since hook
functions may be called from different runtimes, this pointer should not
refer directly to Python state.

As this hook is intentionally used during import, avoid importing new modules
during its execution unless they are known to be frozen or available in
@code{sys.modules}.

Once a hook has been set, it cannot be removed or replaced, and later calls to
@ref{16b4,,PyFile_SetOpenCodeHook()} will fail. On failure, the function returns
-1 and sets an exception if the interpreter has been initialized.

This function is safe to call before @ref{899,,Py_Initialize()}.

Raises an @ref{1848,,auditing event} @code{setopencodehook} with no arguments.


Ajouté dans la version 3.8.

@end deffn

@geindex PyFile_WriteObject (C function)
@anchor{c-api/file c PyFile_WriteObject}@anchor{48c3}
@deffn {C Fonction} int PyFile_WriteObject (PyObject *obj, PyObject *p, int flags)
` Part of the @ref{53e,,Stable ABI}.'
@geindex Py_PRINT_RAW (C macro)

Write object `obj' to file object `p'.  The only supported flag for `flags' is
@ref{4a52,,Py_PRINT_RAW}; if given, the @ref{435,,str()} of the object is written
instead of the @ref{7e7,,repr()}.  Return @code{0} on success or @code{-1} on failure; the
appropriate exception will be set.
@end deffn

@geindex PyFile_WriteString (C function)
@anchor{c-api/file c PyFile_WriteString}@anchor{48c4}
@deffn {C Fonction} int PyFile_WriteString (const char *s, PyObject *p)
` Part of the @ref{53e,,Stable ABI}.'
Écrit la chaîne de caractères `s' dans l'objet fichier `p'. Retourne @code{0} en cas de succès ou @code{-1} en cas d'échec ; l'exception appropriée sera mise en place.
@end deffn

@node Module Objects,Itérateurs<2>,Objets fichiers,Autres objets<2>
@anchor{c-api/module doc}@anchor{4ba5}@anchor{c-api/module module-objects}@anchor{4ba6}@anchor{c-api/module moduleobjects}@anchor{4ba7}
@subsubsection Module Objects


@geindex object;module

@geindex PyModule_Type (C var)
@anchor{c-api/module c PyModule_Type}@anchor{48fa}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyModule_Type
` Part of the @ref{53e,,Stable ABI}.'
@geindex ModuleType (in module types)

This instance of @ref{a93,,PyTypeObject} represents the Python module type.  This
is exposed to Python programs as @code{types.ModuleType}.
@end deffn

@geindex PyModule_Check (C function)
@anchor{c-api/module c PyModule_Check}@anchor{4ba8}
@deffn {C Fonction} int PyModule_Check (PyObject *p)

Return true if `p' is a module object, or a subtype of a module object.
This function always succeeds.
@end deffn

@geindex PyModule_CheckExact (C function)
@anchor{c-api/module c PyModule_CheckExact}@anchor{4ba9}
@deffn {C Fonction} int PyModule_CheckExact (PyObject *p)

Return true if `p' is a module object, but not a subtype of
@ref{48fa,,PyModule_Type}.  This function always succeeds.
@end deffn

@geindex PyModule_NewObject (C function)
@anchor{c-api/module c PyModule_NewObject}@anchor{48f8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_NewObject (PyObject *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
@geindex __name__ (module attribute)
@geindex __doc__ (module attribute)
@geindex __file__ (module attribute)
@geindex __package__ (module attribute)
@geindex __loader__ (module attribute)

Return a new module object with @ref{135f,,module.__name__} set to `name'.
The module's @code{__name__}, @ref{17e0,,__doc__},
@ref{2d6,,__package__} and @ref{2e0,,__loader__} attributes are
filled in (all but @code{__name__} are set to @code{None}). The caller is
responsible for setting a @ref{1ea2,,__file__} attribute.

Return @code{NULL} with an exception set on error.


Ajouté dans la version 3.3.



Modifié dans la version 3.4: @ref{2d6,,__package__} and @ref{2e0,,__loader__} are now set to
@code{None}.

@end deffn

@geindex PyModule_New (C function)
@anchor{c-api/module c PyModule_New}@anchor{48f7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_New (const char *name)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{48f8,,PyModule_NewObject()}, but the name is a UTF-8 encoded
string instead of a Unicode object.
@end deffn

@geindex PyModule_GetDict (C function)
@anchor{c-api/module c PyModule_GetDict}@anchor{48f4}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_GetDict (PyObject *module)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
@geindex __dict__ (module attribute)

Return the dictionary object that implements `module''s namespace; this object
is the same as the @ref{546,,__dict__} attribute of the module object.
If `module' is not a module object (or a subtype of a module object),
@ref{561,,SystemError} is raised and @code{NULL} is returned.

It is recommended extensions use other @code{PyModule_*} and
@code{PyObject_*} functions rather than directly manipulate a module's
@ref{546,,__dict__}.
@end deffn

@geindex PyModule_GetNameObject (C function)
@anchor{c-api/module c PyModule_GetNameObject}@anchor{48f6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_GetNameObject (PyObject *module)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
@geindex __name__ (module attribute)
@geindex SystemError (built-in exception)

Return `module''s @ref{135f,,__name__} value.  If the module does not
provide one, or if it is not a string, @ref{561,,SystemError} is raised and
@code{NULL} is returned.


Ajouté dans la version 3.3.

@end deffn

@geindex PyModule_GetName (C function)
@anchor{c-api/module c PyModule_GetName}@anchor{48f5}
@deffn {C Fonction} const char *PyModule_GetName (PyObject *module)
` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{48f6,,PyModule_GetNameObject()} but return the name encoded to
@code{'utf-8'}.
@end deffn

@geindex PyModule_GetState (C function)
@anchor{c-api/module c PyModule_GetState}@anchor{96d}
@deffn {C Fonction} void *PyModule_GetState (PyObject *module)
` Part of the @ref{53e,,Stable ABI}.'
Return the "state" of the module, that is, a pointer to the block of memory
allocated at module creation time, or @code{NULL}.  See
@ref{96c,,PyModuleDef.m_size}.
@end deffn

@geindex PyModule_GetDef (C function)
@anchor{c-api/module c PyModule_GetDef}@anchor{48f3}
@deffn {C Fonction} @ref{96a,,PyModuleDef} *PyModule_GetDef (PyObject *module)
` Part of the @ref{53e,,Stable ABI}.'
Return a pointer to the @ref{96a,,PyModuleDef} struct from which the module was
created, or @code{NULL} if the module wasn't created from a definition.
@end deffn

@geindex PyModule_GetFilenameObject (C function)
@anchor{c-api/module c PyModule_GetFilenameObject}@anchor{3ef}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_GetFilenameObject (PyObject *module)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@geindex __file__ (module attribute)
@geindex SystemError (built-in exception)

Return the name of the file from which `module' was loaded using `module''s
@ref{1ea2,,__file__} attribute.  If this is not defined, or if it is not a
string, raise @ref{561,,SystemError} and return @code{NULL}; otherwise return
a reference to a Unicode object.


Ajouté dans la version 3.2.

@end deffn

@geindex PyModule_GetFilename (C function)
@anchor{c-api/module c PyModule_GetFilename}@anchor{3ee}
@deffn {C Fonction} const char *PyModule_GetFilename (PyObject *module)
` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{3ef,,PyModule_GetFilenameObject()} but return the filename
encoded to 'utf-8'.


Obsolète depuis la version 3.2: @ref{3ee,,PyModule_GetFilename()} raises @ref{662,,UnicodeEncodeError} on
unencodable filenames, use @ref{3ef,,PyModule_GetFilenameObject()} instead.

@end deffn

@menu
* Initializing C modules:: 
* Module lookup:: 

@end menu

@node Initializing C modules,Module lookup,,Module Objects
@anchor{c-api/module initializing-c-modules}@anchor{4baa}@anchor{c-api/module initializing-modules}@anchor{481b}
@subsubsection Initializing C modules


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 @ref{1731,,PyImport_AppendInittab()}).
See @ref{47c7,,Construire des extensions C et C++} or @ref{4834,,Étendre un Python intégré} for details.

The initialization function can either pass a module definition instance
to @ref{47c4,,PyModule_Create()}, and return the resulting module object,
or request "multi-phase initialization" by returning the definition struct itself.

@geindex PyModuleDef (C type)
@anchor{c-api/module c PyModuleDef}@anchor{96a}
@deffn {C Type} type PyModuleDef
` Part of the @ref{53e,,Stable ABI} (including all members).'
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.

@geindex PyModuleDef.m_base (C member)
@anchor{c-api/module c PyModuleDef m_base}@anchor{4bab}
@deffn {C Membre} PyModuleDef_Base m_base

Always initialize this member to @code{PyModuleDef_HEAD_INIT}.
@end deffn

@geindex PyModuleDef.m_name (C member)
@anchor{c-api/module c PyModuleDef m_name}@anchor{4bac}
@deffn {C Membre} const char *m_name

Name for the new module.
@end deffn

@geindex PyModuleDef.m_doc (C member)
@anchor{c-api/module c PyModuleDef m_doc}@anchor{4bad}
@deffn {C Membre} const char *m_doc

Docstring for the module; usually a docstring variable created with
@ref{1900,,PyDoc_STRVAR} is used.
@end deffn

@geindex PyModuleDef.m_size (C member)
@anchor{c-api/module c PyModuleDef m_size}@anchor{96c}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} m_size

Module state may be kept in a per-module memory area that can be
retrieved with @ref{96d,,PyModule_GetState()}, rather than in static globals.
This makes modules safe for use in multiple sub-interpreters.

This memory area is allocated based on `m_size' on module creation,
and freed when the module object is deallocated, after the
@ref{969,,m_free} function has been called, if present.

Setting @code{m_size} to @code{-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 @code{m_size} is required for multi-phase
initialization.

See 
@geindex Python Enhancement Proposals; PEP 3121
PEP 3121@footnote{https://peps.python.org/pep-3121/} for more details.
@end deffn

@geindex PyModuleDef.m_methods (C member)
@anchor{c-api/module c PyModuleDef m_methods}@anchor{4bae}
@deffn {C Membre} @ref{148d,,PyMethodDef} *m_methods

A pointer to a table of module-level functions, described by
@ref{148d,,PyMethodDef} values.  Can be @code{NULL} if no functions are present.
@end deffn

@geindex PyModuleDef.m_slots (C member)
@anchor{c-api/module c PyModuleDef m_slots}@anchor{4baf}
@deffn {C Membre} @ref{4bb0,,PyModuleDef_Slot} *m_slots

An array of slot definitions for multi-phase initialization, terminated by
a @code{@{0, NULL@}} entry.
When using single-phase initialization, `m_slots' must be @code{NULL}.


Modifié dans la version 3.5: Prior to version 3.5, this member was always set to @code{NULL},
and was defined as:

@quotation

@geindex PyModuleDef.m_slots.m_reload (C member)
@anchor{c-api/module c PyModuleDef m_slots m_reload}@anchor{4bb1}
@deffn {C Membre} @ref{49b9,,inquiry} m_reload
@end deffn
@end quotation

@end deffn

@geindex PyModuleDef.m_traverse (C member)
@anchor{c-api/module c PyModuleDef m_traverse}@anchor{967}
@deffn {C Membre} @ref{49c8,,traverseproc} m_traverse

A traversal function to call during GC traversal of the module object, or
@code{NULL} if not needed.

This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (@ref{96b,,Py_mod_exec} function). More
precisely, this function is not called if @ref{96c,,m_size} is greater
than 0 and the module state (as returned by @ref{96d,,PyModule_GetState()})
is @code{NULL}.


Modifié dans la version 3.9: No longer called before the module state is allocated.

@end deffn

@geindex PyModuleDef.m_clear (C member)
@anchor{c-api/module c PyModuleDef m_clear}@anchor{968}
@deffn {C Membre} @ref{49b9,,inquiry} m_clear

A clear function to call during GC clearing of the module object, or
@code{NULL} if not needed.

This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (@ref{96b,,Py_mod_exec} function). More
precisely, this function is not called if @ref{96c,,m_size} is greater
than 0 and the module state (as returned by @ref{96d,,PyModule_GetState()})
is @code{NULL}.

Like @ref{4801,,PyTypeObject.tp_clear}, this function is not `always'
called before a module is deallocated. For example, when reference
counting is enough to determine that an object is no longer used,
the cyclic garbage collector is not involved and
@ref{969,,m_free} is called directly.


Modifié dans la version 3.9: No longer called before the module state is allocated.

@end deffn

@geindex PyModuleDef.m_free (C member)
@anchor{c-api/module c PyModuleDef m_free}@anchor{969}
@deffn {C Membre} @ref{4bb2,,freefunc} m_free

A function to call during deallocation of the module object, or @code{NULL}
if not needed.

This function is not called if the module state was requested but is not
allocated yet. This is the case immediately after the module is created
and before the module is executed (@ref{96b,,Py_mod_exec} function). More
precisely, this function is not called if @ref{96c,,m_size} is greater
than 0 and the module state (as returned by @ref{96d,,PyModule_GetState()})
is @code{NULL}.


Modifié dans la version 3.9: No longer called before the module state is allocated.

@end deffn
@end deffn

@menu
* Single-phase initialization:: 
* Multi-phase initialization:: 
* Low-level module creation functions:: 
* Support functions:: 

@end menu

@node Single-phase initialization,Multi-phase initialization,,Initializing C modules
@anchor{c-api/module single-phase-initialization}@anchor{4bb3}
@subsubsection 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:

@geindex PyModule_Create (C function)
@anchor{c-api/module c PyModule_Create}@anchor{47c4}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_Create (PyModuleDef *def)
`Valeur de retour : nouvelle référence.'
Create a new module object, given the definition in `def'.  This behaves
like @ref{48f2,,PyModule_Create2()} with `module_api_version' set to
@code{PYTHON_API_VERSION}.
@end deffn

@geindex PyModule_Create2 (C function)
@anchor{c-api/module c PyModule_Create2}@anchor{48f2}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_Create2 (PyModuleDef *def, int module_api_version)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
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 @ref{1bb,,RuntimeWarning} is emitted.

Return @code{NULL} with an exception set on error.

@cartouche
@quotation Note 
Most uses of this function should be using @ref{47c4,,PyModule_Create()}
instead; only use this if you are sure you need it.
@end quotation
@end cartouche
@end deffn

Before it is returned from in the initialization function, the resulting module
object is typically populated using functions like @ref{35b,,PyModule_AddObjectRef()}.

@node Multi-phase initialization,Low-level module creation functions,Single-phase initialization,Initializing C modules
@anchor{c-api/module id1}@anchor{4bb4}@anchor{c-api/module multi-phase-initialization}@anchor{481c}
@subsubsection 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 @code{__new__()} and @code{__init__()} methods
of classes.

Unlike modules created using single-phase initialization, these modules are not
singletons: if the `sys.modules' entry is removed and the module is re-imported,
a new module object is created, and the old module is subject to normal garbage
collection -- as with Python modules.
By default, multiple modules created from the same definition should be
independent: changes to one should not affect the others.
This means that all state should be specific to the module object (using e.g.
using @ref{96d,,PyModule_GetState()}), or its contents (such as the module's
@ref{546,,__dict__} or individual classes created with @ref{569,,PyType_FromSpec()}).

All modules created using multi-phase initialization are expected to support
@ref{573,,sub-interpreters}. Making sure multiple modules
are independent is typically enough to achieve this.

To request multi-phase initialization, the initialization function
(PyInit_modulename) returns a @ref{96a,,PyModuleDef} instance with non-empty
@ref{4baf,,m_slots}. Before it is returned, the @code{PyModuleDef}
instance must be initialized with the following function:

@geindex PyModuleDef_Init (C function)
@anchor{c-api/module c PyModuleDef_Init}@anchor{48f0}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModuleDef_Init (PyModuleDef *def)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.5.'
Ensures a module definition is a properly initialized Python object that
correctly reports its type and reference count.

Returns `def' cast to @code{PyObject*}, or @code{NULL} if an error occurred.


Ajouté dans la version 3.5.

@end deffn

The `m_slots' member of the module definition must point to an array of
@code{PyModuleDef_Slot} structures:

@geindex PyModuleDef_Slot (C type)
@anchor{c-api/module c PyModuleDef_Slot}@anchor{4bb0}
@deffn {C Type} type PyModuleDef_Slot

@geindex PyModuleDef_Slot.slot (C member)
@anchor{c-api/module c PyModuleDef_Slot slot}@anchor{4bb5}
@deffn {C Membre} int slot

A slot ID, chosen from the available values explained below.
@end deffn

@geindex PyModuleDef_Slot.value (C member)
@anchor{c-api/module c PyModuleDef_Slot value}@anchor{4bb6}
@deffn {C Membre} void *value

Value of the slot, whose meaning depends on the slot ID.
@end deffn


Ajouté dans la version 3.5.

@end deffn

The `m_slots' array must be terminated by a slot with id 0.

The available slot types are:

@geindex Py_mod_create (C macro)
@anchor{c-api/module c Py_mod_create}@anchor{4bb7}
@deffn {C Macro} Py_mod_create

Specifies a function that is called to create the module object itself.
The `value' pointer of this slot must point to a function of the signature:

@anchor{c-api/module c Py_mod_create create_module}@anchor{4bb8}
@deffn {C Fonction} @ref{32f,,PyObject} *create_module (PyObject *spec, PyModuleDef *def)
@end deffn

The function receives a @ref{1ded,,ModuleSpec}
instance, as defined in 
@geindex Python Enhancement Proposals; PEP 451
PEP 451@footnote{https://peps.python.org/pep-0451/}, and the module definition.
It should return a new module object, or set an error
and return @code{NULL}.

This function should be kept minimal. In particular, it should not
call arbitrary Python code, as trying to import the same module again may
result in an infinite loop.

Multiple @code{Py_mod_create} slots may not be specified in one module
definition.

If @code{Py_mod_create} is not specified, the import machinery will create
a normal module object using @ref{48f7,,PyModule_New()}. The name is taken from
`spec', not the definition, to allow extension modules to dynamically adjust
to their place in the module hierarchy and be imported under different
names through symlinks, all while sharing a single module definition.

There is no requirement for the returned object to be an instance of
@ref{48fa,,PyModule_Type}. Any type can be used, as long as it supports
setting and getting import-related attributes.
However, only @code{PyModule_Type} instances may be returned if the
@code{PyModuleDef} has non-@code{NULL} @code{m_traverse}, @code{m_clear},
@code{m_free}; non-zero @code{m_size}; or slots other than @code{Py_mod_create}.
@end deffn

@geindex Py_mod_exec (C macro)
@anchor{c-api/module c Py_mod_exec}@anchor{96b}
@deffn {C Macro} Py_mod_exec

Specifies a function that is called to `execute' the module.
This is equivalent to executing the code of a Python module: typically,
this function adds classes and constants to the module.
The signature of the function is:

@anchor{c-api/module c Py_mod_exec exec_module}@anchor{4bb9}
@deffn {C Fonction} int exec_module (PyObject *module)
@end deffn

If multiple @code{Py_mod_exec} slots are specified, they are processed in the
order they appear in the `m_slots' array.
@end deffn

@geindex Py_mod_multiple_interpreters (C macro)
@anchor{c-api/module c Py_mod_multiple_interpreters}@anchor{4bba}
@deffn {C Macro} Py_mod_multiple_interpreters

Specifies one of the following values:

@geindex Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED (C macro)
@anchor{c-api/module c Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED}@anchor{4bbb}
@deffn {C Macro} Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

The module does not support being imported in subinterpreters.
@end deffn

@geindex Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED (C macro)
@anchor{c-api/module c Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED}@anchor{4bbc}
@deffn {C Macro} Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

The module supports being imported in subinterpreters,
but only when they share the main interpreter's GIL.
(See @ref{4bbd,,Isolating Extension Modules}.)
@end deffn

@geindex Py_MOD_PER_INTERPRETER_GIL_SUPPORTED (C macro)
@anchor{c-api/module c Py_MOD_PER_INTERPRETER_GIL_SUPPORTED}@anchor{4bbe}
@deffn {C Macro} Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

The module supports being imported in subinterpreters,
even when they have their own GIL.
(See @ref{4bbd,,Isolating Extension Modules}.)
@end deffn

This slot determines whether or not importing this module
in a subinterpreter will fail.

Multiple @code{Py_mod_multiple_interpreters} slots may not be specified
in one module definition.

If @code{Py_mod_multiple_interpreters} is not specified, the import
machinery defaults to @code{Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED}.


Ajouté dans la version 3.12.

@end deffn

@geindex Py_mod_gil (C macro)
@anchor{c-api/module c Py_mod_gil}@anchor{157}
@deffn {C Macro} Py_mod_gil

Specifies one of the following values:

@geindex Py_MOD_GIL_USED (C macro)
@anchor{c-api/module c Py_MOD_GIL_USED}@anchor{4bbf}
@deffn {C Macro} Py_MOD_GIL_USED

The module depends on the presence of the global interpreter lock (GIL),
and may access global state without synchronization.
@end deffn

@geindex Py_MOD_GIL_NOT_USED (C macro)
@anchor{c-api/module c Py_MOD_GIL_NOT_USED}@anchor{4bc0}
@deffn {C Macro} Py_MOD_GIL_NOT_USED

The module is safe to run without an active GIL.
@end deffn

This slot is ignored by Python builds not configured with
@ref{173,,--disable-gil}.  Otherwise, it determines whether or not importing
this module will cause the GIL to be automatically enabled. See
@ref{13e,,Free-threaded CPython} for more detail.

Multiple @code{Py_mod_gil} slots may not be specified in one module definition.

If @code{Py_mod_gil} is not specified, the import machinery defaults to
@code{Py_MOD_GIL_USED}.


Ajouté dans la version 3.13.

@end deffn

See 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/} for more details on multi-phase initialization.

@node Low-level module creation functions,Support functions,Multi-phase initialization,Initializing C modules
@anchor{c-api/module low-level-module-creation-functions}@anchor{4bc1}
@subsubsection Low-level module creation functions


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 @code{PyModule_FromDefAndSpec} and
@code{PyModule_ExecDef} must be called to fully initialize a module.

@geindex PyModule_FromDefAndSpec (C function)
@anchor{c-api/module c PyModule_FromDefAndSpec}@anchor{e9b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_FromDefAndSpec (PyModuleDef *def, PyObject *spec)
`Valeur de retour : nouvelle référence.'
Create a new module object, given the definition in `def' and the
ModuleSpec `spec'.  This behaves like @ref{e9c,,PyModule_FromDefAndSpec2()}
with `module_api_version' set to @code{PYTHON_API_VERSION}.


Ajouté dans la version 3.5.

@end deffn

@geindex PyModule_FromDefAndSpec2 (C function)
@anchor{c-api/module c PyModule_FromDefAndSpec2}@anchor{e9c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyModule_FromDefAndSpec2 (PyModuleDef *def, PyObject *spec, int module_api_version)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Create a new module object, given the definition in `def' and the
ModuleSpec `spec', assuming the API version `module_api_version'.
If that version does not match the version of the running interpreter,
a @ref{1bb,,RuntimeWarning} is emitted.

Return @code{NULL} with an exception set on error.

@cartouche
@quotation Note 
Most uses of this function should be using @ref{e9b,,PyModule_FromDefAndSpec()}
instead; only use this if you are sure you need it.
@end quotation
@end cartouche


Ajouté dans la version 3.5.

@end deffn

@geindex PyModule_ExecDef (C function)
@anchor{c-api/module c PyModule_ExecDef}@anchor{e9d}
@deffn {C Fonction} int PyModule_ExecDef (PyObject *module, PyModuleDef *def)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Process any execution slots (@ref{96b,,Py_mod_exec}) given in `def'.


Ajouté dans la version 3.5.

@end deffn

@geindex PyModule_SetDocString (C function)
@anchor{c-api/module c PyModule_SetDocString}@anchor{48f9}
@deffn {C Fonction} int PyModule_SetDocString (PyObject *module, const char *docstring)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Set the docstring for `module' to `docstring'.
This function is called automatically when creating a module from
@code{PyModuleDef}, using either @code{PyModule_Create} or
@code{PyModule_FromDefAndSpec}.


Ajouté dans la version 3.5.

@end deffn

@geindex PyModule_AddFunctions (C function)
@anchor{c-api/module c PyModule_AddFunctions}@anchor{48f1}
@deffn {C Fonction} int PyModule_AddFunctions (PyObject *module, PyMethodDef *functions)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Add the functions from the @code{NULL} terminated `functions' array to `module'.
Refer to the @ref{148d,,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
@code{PyModuleDef}, using either @code{PyModule_Create} or
@code{PyModule_FromDefAndSpec}.


Ajouté dans la version 3.5.

@end deffn

@node Support functions,,Low-level module creation functions,Initializing C modules
@anchor{c-api/module support-functions}@anchor{4bc2}
@subsubsection 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:

@geindex PyModule_AddObjectRef (C function)
@anchor{c-api/module c PyModule_AddObjectRef}@anchor{35b}
@deffn {C Fonction} int PyModule_AddObjectRef (PyObject *module, const char *name, PyObject *value)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Add an object to `module' as `name'.  This is a convenience function which
can be used from the module's initialization function.

On success, return @code{0}. On error, raise an exception and return @code{-1}.

Return @code{-1} if `value' is @code{NULL}. It must be called with an exception
raised in this case.

Exemple d'utilisation :

@example
static int
add_spam(PyObject *module, int value)
@{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) @{
        return -1;
    @}
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 @}
@end example

The example can also be written without checking explicitly if `obj' is
@code{NULL}:

@example
static int
add_spam(PyObject *module, int value)
@{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 @}
@end example

Note that @code{Py_XDECREF()} should be used instead of @code{Py_DECREF()} in
this case, since `obj' can be @code{NULL}.

The number of different `name' strings passed to this function
should be kept small, usually by only using statically allocated strings
as `name'.
For names that aren't known at compile time, prefer calling
@ref{4832,,PyUnicode_FromString()} and @ref{492e,,PyObject_SetAttr()} directly.
For more details, see @ref{1587,,PyUnicode_InternFromString()}, which may be
used internally to create a key object.


Ajouté dans la version 3.10.

@end deffn

@geindex PyModule_Add (C function)
@anchor{c-api/module c PyModule_Add}@anchor{35a}
@deffn {C Fonction} int PyModule_Add (PyObject *module, const char *name, PyObject *value)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Similar to @ref{35b,,PyModule_AddObjectRef()}, but "steals" a reference
to `value'.
It can be called with a result of function that returns a new reference
without bothering to check its result or even saving it to a variable.

Exemple d'utilisation :

@example
if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) @{
    goto error;
@}
@end example


Ajouté dans la version 3.13.

@end deffn

@geindex PyModule_AddObject (C function)
@anchor{c-api/module c PyModule_AddObject}@anchor{35c}
@deffn {C Fonction} int PyModule_AddObject (PyObject *module, const char *name, PyObject *value)
` Part of the @ref{53e,,Stable ABI}.'
Similar to @ref{35b,,PyModule_AddObjectRef()}, but steals a reference to
`value' on success (if it returns @code{0}).

The new @ref{35a,,PyModule_Add()} or @ref{35b,,PyModule_AddObjectRef()}
functions are recommended, since it is
easy to introduce reference leaks by misusing the
@ref{35c,,PyModule_AddObject()} function.

@cartouche
@quotation Note 
Unlike other functions that steal references, @code{PyModule_AddObject()}
only releases the reference to `value' `on success'.

This means that its return value must be checked, and calling code must
@ref{779,,Py_XDECREF()} `value' manually on error.
@end quotation
@end cartouche

Exemple d'utilisation :

@example
PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) @{
    // If 'obj' is not NULL and PyModule_AddObject() failed,
    // 'obj' strong reference must be deleted with Py_XDECREF().
    // If 'obj' is NULL, Py_XDECREF() does nothing.
    Py_XDECREF(obj);
    goto error;
@}
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.
@end example


Obsolète depuis la version 3.13: @ref{35c,,PyModule_AddObject()} is @ref{206,,soft deprecated}.

@end deffn

@geindex PyModule_AddIntConstant (C function)
@anchor{c-api/module c PyModule_AddIntConstant}@anchor{14f2}
@deffn {C Fonction} int PyModule_AddIntConstant (PyObject *module, const char *name, long value)
` Part of the @ref{53e,,Stable ABI}.'
Add an integer constant to `module' as `name'.  This convenience function can be
used from the module's initialization function.
Return @code{-1} with an exception set on error, @code{0} on success.

This is a convenience function that calls @ref{17c7,,PyLong_FromLong()} and
@ref{35b,,PyModule_AddObjectRef()}; see their documentation for details.
@end deffn

@geindex PyModule_AddStringConstant (C function)
@anchor{c-api/module c PyModule_AddStringConstant}@anchor{14f3}
@deffn {C Fonction} int PyModule_AddStringConstant (PyObject *module, const char *name, const char *value)
` Part of the @ref{53e,,Stable ABI}.'
Add a string constant to `module' as `name'.  This convenience function can be
used from the module's initialization function.  The string `value' must be
@code{NULL}-terminated.
Return @code{-1} with an exception set on error, @code{0} on success.

This is a convenience function that calls
@ref{1587,,PyUnicode_InternFromString()} and @ref{35b,,PyModule_AddObjectRef()};
see their documentation for details.
@end deffn

@geindex PyModule_AddIntMacro (C macro)
@anchor{c-api/module c PyModule_AddIntMacro}@anchor{13aa}
@deffn {C Macro} PyModule_AddIntMacro (module, macro)

Add an int constant to `module'. The name and the value are taken from
`macro'. For example @code{PyModule_AddIntMacro(module, AF_INET)} adds the int
constant `AF_INET' with the value of `AF_INET' to `module'.
Return @code{-1} with an exception set on error, @code{0} on success.
@end deffn

@geindex PyModule_AddStringMacro (C macro)
@anchor{c-api/module c PyModule_AddStringMacro}@anchor{13a9}
@deffn {C Macro} PyModule_AddStringMacro (module, macro)

Add a string constant to `module'.
@end deffn

@geindex PyModule_AddType (C function)
@anchor{c-api/module c PyModule_AddType}@anchor{962}
@deffn {C Fonction} int PyModule_AddType (PyObject *module, PyTypeObject *type)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Add a type object to `module'.
The type object is finalized by calling internally @ref{766,,PyType_Ready()}.
The name of the type object is taken from the last component of
@ref{1880,,tp_name} after dot.
Return @code{-1} with an exception set on error, @code{0} on success.


Ajouté dans la version 3.9.

@end deffn

@geindex PyUnstable_Module_SetGIL (C function)
@anchor{c-api/module c PyUnstable_Module_SetGIL}@anchor{178}
@deffn {C Fonction} int PyUnstable_Module_SetGIL (PyObject *module, void *gil)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Indicate that `module' does or does not support running without the global
interpreter lock (GIL), using one of the values from
@ref{157,,Py_mod_gil}. It must be called during `module''s initialization
function. 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
@ref{173,,--disable-gil}.
Return @code{-1} with an exception set on error, @code{0} on success.


Ajouté dans la version 3.13.

@end deffn

@node Module lookup,,Initializing C modules,Module Objects
@anchor{c-api/module module-lookup}@anchor{4bc3}
@subsubsection Module lookup


Single-phase initialization 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.

These functions will not work on modules created using multi-phase initialization,
since multiple such modules can be created from a single definition.

@geindex PyState_FindModule (C function)
@anchor{c-api/module c PyState_FindModule}@anchor{494a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyState_FindModule (PyModuleDef *def)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Returns the module object that was created from `def' for the current interpreter.
This method requires that the module object has been attached to the interpreter state with
@ref{4949,,PyState_AddModule()} beforehand. In case the corresponding module object is not
found or has not been attached to the interpreter state yet, it returns @code{NULL}.
@end deffn

@geindex PyState_AddModule (C function)
@anchor{c-api/module c PyState_AddModule}@anchor{4949}
@deffn {C Fonction} int PyState_AddModule (PyObject *module, PyModuleDef *def)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.3.'
Attaches the module object passed to the function to the interpreter state. This allows
the module object to be accessible via @ref{494a,,PyState_FindModule()}.

Only effective on modules created using single-phase initialization.

Python calls @code{PyState_AddModule} automatically after importing a module,
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 @code{PyState_FindModule}.
The function is mainly intended for implementing alternative import
mechanisms (either by calling it directly, or by referring to its
implementation for details of the required state updates).

The caller must hold the GIL.

Return @code{-1} with an exception set on error, @code{0} on success.


Ajouté dans la version 3.3.

@end deffn

@geindex PyState_RemoveModule (C function)
@anchor{c-api/module c PyState_RemoveModule}@anchor{494b}
@deffn {C Fonction} int PyState_RemoveModule (PyModuleDef *def)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.3.'
Removes the module object created from `def' from the interpreter state.
Return @code{-1} with an exception set on error, @code{0} on success.

The caller must hold the GIL.


Ajouté dans la version 3.3.

@end deffn

@node Itérateurs<2>,Les descripteurs,Module Objects,Autres objets<2>
@anchor{c-api/iterator doc}@anchor{4bc4}@anchor{c-api/iterator id1}@anchor{4bc5}@anchor{c-api/iterator iterator-objects}@anchor{4bc6}
@subsubsection Itérateurs


Python provides two general-purpose iterator objects.  The first, a sequence
iterator, works with an arbitrary sequence supporting the @ref{280,,__getitem__()}
method.  The second works with a callable object and a sentinel value, calling
the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.

@geindex PySeqIter_Type (C var)
@anchor{c-api/iterator c PySeqIter_Type}@anchor{4933}
@deffn {C Variable} @ref{a93,,PyTypeObject} PySeqIter_Type
` Part of the @ref{53e,,Stable ABI}.'
Type des itérateurs renvoyés par les fonctions @ref{4932,,PySeqIter_New()} et la forme à un argument de la fonction native @ref{7c1,,iter()} pour les séquences natives.
@end deffn

@geindex PySeqIter_Check (C function)
@anchor{c-api/iterator c PySeqIter_Check}@anchor{4bc7}
@deffn {C Fonction} int PySeqIter_Check (PyObject *op)

Return true if the type of `op' is @ref{4933,,PySeqIter_Type}.  This function
always succeeds.
@end deffn

@geindex PySeqIter_New (C function)
@anchor{c-api/iterator c PySeqIter_New}@anchor{4932}
@deffn {C Fonction} @ref{32f,,PyObject} *PySeqIter_New (PyObject *seq)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie un itérateur sur la séquence `seq'. L'itération prend fin lorsque la séquence lève @ref{14eb,,IndexError} lors d'une tentative d'accès.
@end deffn

@geindex PyCallIter_Type (C var)
@anchor{c-api/iterator c PyCallIter_Type}@anchor{487d}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyCallIter_Type
` Part of the @ref{53e,,Stable ABI}.'
Type de l'itérateur renvoyé par les fonctions @ref{487c,,PyCallIter_New()} et @ref{7c1,,iter()} à deux arguments.
@end deffn

@geindex PyCallIter_Check (C function)
@anchor{c-api/iterator c PyCallIter_Check}@anchor{4bc8}
@deffn {C Fonction} int PyCallIter_Check (PyObject *op)

Return true if the type of `op' is @ref{487d,,PyCallIter_Type}.  This
function always succeeds.
@end deffn

@geindex PyCallIter_New (C function)
@anchor{c-api/iterator c PyCallIter_New}@anchor{487c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCallIter_New (PyObject *callable, PyObject *sentinel)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Renvoie un nouvel itérateur. Le premier paramètre, `callable', peut être n'importe quel objet Python appelable sans aucun paramètre ; chaque appel doit renvoyer l'élément suivant de l'itération. Lorsque `callable' renvoie une valeur égale à `sentinel', l'itération prend fin.
@end deffn

@node Les descripteurs,Slice Objects,Itérateurs<2>,Autres objets<2>
@anchor{c-api/descriptor doc}@anchor{4bc9}@anchor{c-api/descriptor descriptor-objects}@anchor{4bca}@anchor{c-api/descriptor id1}@anchor{4bcb}
@subsubsection Les descripteurs


Les "Descripteurs" sont des objets décrivant des attributs pour un objet. Ils se trouvent dans le dictionnaire du type de l'objet.

@c XXX document these!

@geindex PyProperty_Type (C var)
@anchor{c-api/descriptor c PyProperty_Type}@anchor{4931}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyProperty_Type
` Part of the @ref{53e,,Stable ABI}.'
L'objet `type' des descripteurs natifs.
@end deffn

@geindex PyDescr_NewGetSet (C function)
@anchor{c-api/descriptor c PyDescr_NewGetSet}@anchor{489a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDescr_NewGetSet (PyTypeObject *type, struct PyGetSetDef *getset)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyDescr_NewMember (C function)
@anchor{c-api/descriptor c PyDescr_NewMember}@anchor{489b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDescr_NewMember (PyTypeObject *type, struct PyMemberDef *meth)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyDescr_NewMethod (C function)
@anchor{c-api/descriptor c PyDescr_NewMethod}@anchor{191a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDescr_NewMethod (PyTypeObject *type, struct PyMethodDef *meth)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyDescr_NewWrapper (C function)
@anchor{c-api/descriptor c PyDescr_NewWrapper}@anchor{4bcc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDescr_NewWrapper (PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
`Valeur de retour : nouvelle référence.'
@end deffn

@geindex PyDescr_NewClassMethod (C function)
@anchor{c-api/descriptor c PyDescr_NewClassMethod}@anchor{4899}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDescr_NewClassMethod (PyTypeObject *type, PyMethodDef *method)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyDescr_IsData (C function)
@anchor{c-api/descriptor c PyDescr_IsData}@anchor{1883}
@deffn {C Fonction} int PyDescr_IsData (PyObject *descr)

Return non-zero if the descriptor objects `descr' describes a data attribute, or
@code{0} if it describes a method.  `descr' must be a descriptor object; there is
no error checking.
@end deffn

@geindex PyWrapper_New (C function)
@anchor{c-api/descriptor c PyWrapper_New}@anchor{499d}
@deffn {C Fonction} @ref{32f,,PyObject} *PyWrapper_New (PyObject*, PyObject*)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@node Slice Objects,Objets de type MemoryView,Les descripteurs,Autres objets<2>
@anchor{c-api/slice doc}@anchor{4bcd}@anchor{c-api/slice id1}@anchor{4bce}@anchor{c-api/slice slice-objects}@anchor{4bcf}
@subsubsection Slice Objects


@geindex PySlice_Type (C var)
@anchor{c-api/slice c PySlice_Type}@anchor{4948}
@deffn {C Variable} @ref{a93,,PyTypeObject} PySlice_Type
` Part of the @ref{53e,,Stable ABI}.'
The type object for slice objects.  This is the same as @ref{453,,slice} in the
Python layer.
@end deffn

@geindex PySlice_Check (C function)
@anchor{c-api/slice c PySlice_Check}@anchor{4bd0}
@deffn {C Fonction} int PySlice_Check (PyObject *ob)

Return true if `ob' is a slice object; `ob' must not be @code{NULL}.  This
function always succeeds.
@end deffn

@geindex PySlice_New (C function)
@anchor{c-api/slice c PySlice_New}@anchor{4947}
@deffn {C Fonction} @ref{32f,,PyObject} *PySlice_New (PyObject *start, PyObject *stop, PyObject *step)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a new slice object with the given values.  The `start', `stop', and
`step' parameters are used as the values of the slice object attributes of
the same names.  Any of the values may be @code{NULL}, in which case the
@code{None} will be used for the corresponding attribute.

Return @code{NULL} with an exception set if
the new object could not be allocated.
@end deffn

@geindex PySlice_GetIndices (C function)
@anchor{c-api/slice c PySlice_GetIndices}@anchor{4946}
@deffn {C Fonction} int PySlice_GetIndices (PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
` Part of the @ref{53e,,Stable ABI}.'
Retrieve the start, stop and step indices from the slice object `slice',
assuming a sequence of length `length'. Treats indices greater than
`length' as errors.

Returns @code{0} on success and @code{-1} on error with no exception set (unless one of
the indices was not @code{None} and failed to be converted to an integer,
in which case @code{-1} is returned with an exception set).

You probably do not want to use this function.


Modifié dans la version 3.2: The parameter type for the `slice' parameter was @code{PySliceObject*}
before.

@end deffn

@geindex PySlice_GetIndicesEx (C function)
@anchor{c-api/slice c PySlice_GetIndicesEx}@anchor{3f2}
@deffn {C Fonction} int PySlice_GetIndicesEx (PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
` Part of the @ref{53e,,Stable ABI}.'
Usable replacement for @ref{4946,,PySlice_GetIndices()}.  Retrieve the start,
stop, and step indices from the slice object `slice' assuming a sequence of
length `length', and store the length of the slice in `slicelength'.  Out
of bounds indices are clipped in a manner consistent with the handling of
normal slices.

Return @code{0} on success and @code{-1} on error with an exception set.

@cartouche
@quotation Note 
This function is considered not safe for resizable sequences.
Its invocation should be replaced by a combination of
@ref{3f3,,PySlice_Unpack()} and @ref{3f4,,PySlice_AdjustIndices()} where

@example
if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) @{
    // return error
@}
@end example

is replaced by

@example
if (PySlice_Unpack(slice, &start, &stop, &step) < 0) @{
    // return error
@}
slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
@end example
@end quotation
@end cartouche


Modifié dans la version 3.2: The parameter type for the `slice' parameter was @code{PySliceObject*}
before.



Modifié dans la version 3.6.1: If @code{Py_LIMITED_API} is not set or set to the value between @code{0x03050400}
and @code{0x03060000} (not including) or @code{0x03060100} or higher
@code{PySlice_GetIndicesEx()} is implemented as a macro using
@code{PySlice_Unpack()} and @code{PySlice_AdjustIndices()}.
Arguments `start', `stop' and `step' are evaluated more than once.



Obsolète depuis la version 3.6.1: If @code{Py_LIMITED_API} is set to the value less than @code{0x03050400} or
between @code{0x03060000} and @code{0x03060100} (not including)
@code{PySlice_GetIndicesEx()} is a deprecated function.

@end deffn

@geindex PySlice_Unpack (C function)
@anchor{c-api/slice c PySlice_Unpack}@anchor{3f3}
@deffn {C Fonction} int PySlice_Unpack (PyObject *slice, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Extract the start, stop and step data members from a slice object as
C integers.  Silently reduce values larger than @code{PY_SSIZE_T_MAX} to
@code{PY_SSIZE_T_MAX}, silently boost the start and stop values less than
@code{PY_SSIZE_T_MIN} to @code{PY_SSIZE_T_MIN}, and silently boost the step
values less than @code{-PY_SSIZE_T_MAX} to @code{-PY_SSIZE_T_MAX}.

Return @code{-1} with an exception set on error, @code{0} on success.


Ajouté dans la version 3.6.1.

@end deffn

@geindex PySlice_AdjustIndices (C function)
@anchor{c-api/slice c PySlice_AdjustIndices}@anchor{3f4}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PySlice_AdjustIndices (Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t step)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Adjust start/end slice indices assuming a sequence of the specified length.
Out of bounds indices are clipped in a manner consistent with the handling
of normal slices.

Return the length of the slice.  Always successful.  Doesn't call Python
code.


Ajouté dans la version 3.6.1.

@end deffn

@menu
* Ellipsis Object:: 

@end menu

@node Ellipsis Object,,,Slice Objects
@anchor{c-api/slice ellipsis-object}@anchor{4bd1}
@subsubsection Ellipsis Object


@geindex Py_Ellipsis (C var)
@anchor{c-api/slice c Py_Ellipsis}@anchor{4bd2}
@deffn {C Variable} @ref{32f,,PyObject} *Py_Ellipsis

The Python @code{Ellipsis} object.  This object has no methods.  Like
@ref{47c0,,Py_None}, it is an @ref{42aa,,immortal} singleton object.


Modifié dans la version 3.12: @ref{4bd2,,Py_Ellipsis} is immortal.

@end deffn

@geindex object;memoryview
@anchor{c-api/memoryview memoryview-objects}@anchor{4a82}
@node Objets de type MemoryView,Objets à références faibles<2>,Slice Objects,Autres objets<2>
@anchor{c-api/memoryview doc}@anchor{4bd3}@anchor{c-api/memoryview id1}@anchor{4bd4}
@subsubsection Objets de type MemoryView


Un objet Python @ref{452,,memoryview} expose le @ref{38e,,protocole tampon} du C. Cet objet peut ensuite être passé comme n'importe quel objet.

@geindex PyMemoryView_FromObject (C function)
@anchor{c-api/memoryview c PyMemoryView_FromObject}@anchor{48ee}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMemoryView_FromObject (PyObject *obj)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Crée un objet `memoryview' à partir d'un objet implémentant le protocole tampon. Si `obj' permet d'exporter des tampons modifiables, l'objet `memoryview' crée acceptera la lecture et écriture, sinon l'objet crée est soit en lecture seule ou lecture/écriture, à la discrétion de l'`exporteur'.
@end deffn

@geindex PyBUF_READ (C macro)
@anchor{c-api/memoryview c PyBUF_READ}@anchor{1619}
@deffn {C Macro} PyBUF_READ

Flag to request a readonly buffer.
@end deffn

@geindex PyBUF_WRITE (C macro)
@anchor{c-api/memoryview c PyBUF_WRITE}@anchor{161a}
@deffn {C Macro} PyBUF_WRITE

Flag to request a writable buffer.
@end deffn

@geindex PyMemoryView_FromMemory (C function)
@anchor{c-api/memoryview c PyMemoryView_FromMemory}@anchor{1150}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMemoryView_FromMemory (char *mem, Py_ssize_t size, int flags)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Crée un objet `memoryview' utilisant `mem' comme un tampon sous-jacent. `flags' peut être @ref{1619,,PyBUF_READ} ou @ref{161a,,PyBUF_WRITE}.


Ajouté dans la version 3.3.

@end deffn

@geindex PyMemoryView_FromBuffer (C function)
@anchor{c-api/memoryview c PyMemoryView_FromBuffer}@anchor{74b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMemoryView_FromBuffer (const Py_buffer *view)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
Crée un objet `memoryview' à partir de la structure tampon `view'. Pour de simples tampons d'octets, @ref{1150,,PyMemoryView_FromMemory()} est préférée.
@end deffn

@geindex PyMemoryView_GetContiguous (C function)
@anchor{c-api/memoryview c PyMemoryView_GetContiguous}@anchor{48ef}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMemoryView_GetContiguous (PyObject *obj, int buffertype, char order)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Crée un objet `memoryview' vers un segment de mémoire @ref{21af,,contiguous} (organisé comme en @code{'C'} ou comme en @code{'F'} pour Fortran) à partir d'un objet qui expose le protocole tampon. Si la mémoire est contiguë, l'objet `memoryview' pointe vers la mémoire d'origine. Sinon une copie est faite et la `memoryview' pointe vers un nouvel objet `bytes'.

`buffertype' can be one of @ref{1619,,PyBUF_READ} or @ref{161a,,PyBUF_WRITE}.
@end deffn

@geindex PyMemoryView_Check (C function)
@anchor{c-api/memoryview c PyMemoryView_Check}@anchor{4bd5}
@deffn {C Fonction} int PyMemoryView_Check (PyObject *obj)

Return true if the object `obj' is a memoryview object.  It is not
currently allowed to create subclasses of @ref{452,,memoryview}.  This
function always succeeds.
@end deffn

@geindex PyMemoryView_GET_BUFFER (C function)
@anchor{c-api/memoryview c PyMemoryView_GET_BUFFER}@anchor{4bd6}
@deffn {C Fonction} @ref{742,,Py_buffer} *PyMemoryView_GET_BUFFER (PyObject *mview)

Retourne un pointeur vers la copie privée du tampon de l'`exporteur' de `memoryview'. `mview' `doit' être une instance de `memoryview'; cette macro ne vérifie pas le type, vous devez le faire vous-même sinon vous pourriez subir un crash.
@end deffn

@geindex PyMemoryView_GET_BASE (C function)
@anchor{c-api/memoryview c PyMemoryView_GET_BASE}@anchor{4bd7}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMemoryView_GET_BASE (PyObject *mview)

Renvoie soit un pointeur vers l'objet exporté sur lequel est basé la `memoryview' ou @code{NULL} si la `memoryview' a été crée par @ref{1150,,PyMemoryView_FromMemory()} ou @ref{74b,,PyMemoryView_FromBuffer()}. `mview' `doit' être une instance de `memoryview'.
@end deffn

@node Objets à références faibles<2>,Capsules<2>,Objets de type MemoryView,Autres objets<2>
@anchor{c-api/weakref doc}@anchor{4bd8}@anchor{c-api/weakref weak-reference-objects}@anchor{4bd9}@anchor{c-api/weakref weakrefobjects}@anchor{4bda}
@subsubsection Objets à références faibles


Python gère les `références faibles' comme des objets de première classe. Il existe deux types d'objets spécifiques qui implémentent directement les références faibles. Le premier est un objet de référence simple, et le second agit autant que possible comme un mandataire vers l'objet original.

@geindex PyWeakref_Check (C function)
@anchor{c-api/weakref c PyWeakref_Check}@anchor{4bdb}
@deffn {C Fonction} int PyWeakref_Check (PyObject *ob)

Return non-zero if `ob' is either a reference or proxy object.  This function
always succeeds.
@end deffn

@geindex PyWeakref_CheckRef (C function)
@anchor{c-api/weakref c PyWeakref_CheckRef}@anchor{4bdc}
@deffn {C Fonction} int PyWeakref_CheckRef (PyObject *ob)

Return non-zero if `ob' is a reference object.  This function always succeeds.
@end deffn

@geindex PyWeakref_CheckProxy (C function)
@anchor{c-api/weakref c PyWeakref_CheckProxy}@anchor{4bdd}
@deffn {C Fonction} int PyWeakref_CheckProxy (PyObject *ob)

Return non-zero if `ob' is a proxy object.  This function always succeeds.
@end deffn

@geindex PyWeakref_NewRef (C function)
@anchor{c-api/weakref c PyWeakref_NewRef}@anchor{17dc}
@deffn {C Fonction} @ref{32f,,PyObject} *PyWeakref_NewRef (PyObject *ob, PyObject *callback)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a weak reference object for the object `ob'.  This will always return
a new reference, but is not guaranteed to create a new object; an existing
reference object may be returned.  The second parameter, `callback', can be a
callable object that receives notification when `ob' is garbage collected; it
should accept a single parameter, which will be the weak reference object
itself. `callback' may also be @code{None} or @code{NULL}.  If `ob' is not a
weakly referenceable object, or if `callback' is not callable, @code{None}, or
@code{NULL}, this will return @code{NULL} and raise @ref{522,,TypeError}.
@end deffn

@geindex PyWeakref_NewProxy (C function)
@anchor{c-api/weakref c PyWeakref_NewProxy}@anchor{499c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyWeakref_NewProxy (PyObject *ob, PyObject *callback)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Return a weak reference proxy object for the object `ob'.  This will always
return a new reference, but is not guaranteed to create a new object; an
existing proxy object may be returned.  The second parameter, `callback', can
be a callable object that receives notification when `ob' is garbage
collected; it should accept a single parameter, which will be the weak
reference object itself. `callback' may also be @code{None} or @code{NULL}.  If `ob'
is not a weakly referenceable object, or if `callback' is not callable,
@code{None}, or @code{NULL}, this will return @code{NULL} and raise @ref{522,,TypeError}.
@end deffn

@geindex PyWeakref_GetRef (C function)
@anchor{c-api/weakref c PyWeakref_GetRef}@anchor{36e}
@deffn {C Fonction} int PyWeakref_GetRef (PyObject *ref, PyObject **pobj)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Get a @ref{333,,strong reference} to the referenced object from a weak
reference, `ref', into `*pobj'.


@itemize *

@item 
On success, set `*pobj' to a new @ref{333,,strong reference} to the
referenced object and return 1.

@item 
If the reference is dead, set `*pobj' to @code{NULL} and return 0.

@item 
On error, raise an exception and return -1.
@end itemize


Ajouté dans la version 3.13.

@end deffn

@geindex PyWeakref_GetObject (C function)
@anchor{c-api/weakref c PyWeakref_GetObject}@anchor{36f}
@deffn {C Fonction} @ref{32f,,PyObject} *PyWeakref_GetObject (PyObject *ref)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return a @ref{334,,borrowed reference} to the referenced object from a weak
reference, `ref'.  If the referent is no longer live, returns @code{Py_None}.

@cartouche
@quotation Note 
This function returns a @ref{334,,borrowed reference} to the referenced object.
This means that you should always call @ref{55a,,Py_INCREF()} on the object
except when it cannot be destroyed before the last usage of the borrowed
reference.
@end quotation
@end cartouche


Deprecated since version 3.13, will be removed in version 3.15: Use @ref{36e,,PyWeakref_GetRef()} instead.

@end deffn

@geindex PyWeakref_GET_OBJECT (C function)
@anchor{c-api/weakref c PyWeakref_GET_OBJECT}@anchor{3b6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyWeakref_GET_OBJECT (PyObject *ref)
`Valeur de retour : référence empruntée.'
Similar to @ref{36f,,PyWeakref_GetObject()}, but does no error checking.


Deprecated since version 3.13, will be removed in version 3.15: Use @ref{36e,,PyWeakref_GetRef()} instead.

@end deffn

@geindex PyObject_ClearWeakRefs (C function)
@anchor{c-api/weakref c PyObject_ClearWeakRefs}@anchor{562}
@deffn {C Fonction} void PyObject_ClearWeakRefs (PyObject *object)
` Part of the @ref{53e,,Stable ABI}.'
This function is called by the @ref{47ee,,tp_dealloc} handler
to clear weak references.

This iterates through the weak references for `object' and calls callbacks
for those references which have one. It returns when all callbacks have
been attempted.
@end deffn

@geindex PyUnstable_Object_ClearWeakRefsNoCallbacks (C function)
@anchor{c-api/weakref c PyUnstable_Object_ClearWeakRefsNoCallbacks}@anchor{159b}
@deffn {C Fonction} void PyUnstable_Object_ClearWeakRefsNoCallbacks (PyObject *object)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Clears the weakrefs for `object' without calling the callbacks.

This function is called by the @ref{47ee,,tp_dealloc} handler
for types with finalizers (i.e., @ref{1ee3,,__del__()}).  The handler for
those objects first calls @ref{562,,PyObject_ClearWeakRefs()} to clear weakrefs
and call their callbacks, then the finalizer, and finally this function to
clear any weakrefs that may have been created by the finalizer.

In most circumstances, it's more appropriate to use
@ref{562,,PyObject_ClearWeakRefs()} to clear weakrefs instead of this function.


Ajouté dans la version 3.13.

@end deffn

@node Capsules<2>,Objets décrivant les frames,Objets à références faibles<2>,Autres objets<2>
@anchor{c-api/capsule doc}@anchor{4bde}@anchor{c-api/capsule capsules}@anchor{2501}@anchor{c-api/capsule id1}@anchor{4bdf}
@subsubsection Capsules


@geindex object;Capsule

Reportez-vous à @ref{1334,,Fournir une API en langage C pour un module d'extension} pour plus d'informations sur l'utilisation de ces objets.


Ajouté dans la version 3.1.


@geindex PyCapsule (C type)
@anchor{c-api/capsule c PyCapsule}@anchor{1251}
@deffn {C Type} type PyCapsule

This subtype of @ref{32f,,PyObject} represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a void*
pointer) through Python code to other C code.  It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.
@end deffn

@geindex PyCapsule_Destructor (C type)
@anchor{c-api/capsule c PyCapsule_Destructor}@anchor{487f}
@deffn {C Type} type PyCapsule_Destructor
` Part of the @ref{53e,,Stable ABI}.'
The type of a destructor callback for a capsule.  Defined as:

@example
typedef void (*PyCapsule_Destructor)(PyObject *);
@end example

See @ref{47e3,,PyCapsule_New()} for the semantics of PyCapsule_Destructor
callbacks.
@end deffn

@geindex PyCapsule_CheckExact (C function)
@anchor{c-api/capsule c PyCapsule_CheckExact}@anchor{4be0}
@deffn {C Fonction} int PyCapsule_CheckExact (PyObject *p)

Return true if its argument is a @ref{1251,,PyCapsule}.  This function always
succeeds.
@end deffn

@geindex PyCapsule_New (C function)
@anchor{c-api/capsule c PyCapsule_New}@anchor{47e3}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCapsule_New (void *pointer, const char *name, PyCapsule_Destructor destructor)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Create a @ref{1251,,PyCapsule} encapsulating the `pointer'.  The `pointer'
argument may not be @code{NULL}.

On failure, set an exception and return @code{NULL}.

The `name' string may either be @code{NULL} or a pointer to a valid C string.  If
non-@code{NULL}, this string must outlive the capsule.  (Though it is permitted to
free it inside the `destructor'.)

If the `destructor' argument is not @code{NULL}, it will be called with the
capsule as its argument when it is destroyed.

If this capsule will be stored as an attribute of a module, the `name' should
be specified as @code{modulename.attributename}.  This will enable other modules
to import the capsule using @ref{17fb,,PyCapsule_Import()}.
@end deffn

@geindex PyCapsule_GetPointer (C function)
@anchor{c-api/capsule c PyCapsule_GetPointer}@anchor{4883}
@deffn {C Fonction} void *PyCapsule_GetPointer (PyObject *capsule, const char *name)
` Part of the @ref{53e,,Stable ABI}.'
Retrieve the `pointer' stored in the capsule.  On failure, set an exception
and return @code{NULL}.

The `name' parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is @code{NULL}, the `name' passed in must also
be @code{NULL}.  Python uses the C function @code{strcmp()} to compare capsule
names.
@end deffn

@geindex PyCapsule_GetDestructor (C function)
@anchor{c-api/capsule c PyCapsule_GetDestructor}@anchor{4881}
@deffn {C Fonction} @ref{487f,,PyCapsule_Destructor} PyCapsule_GetDestructor (PyObject *capsule)
` Part of the @ref{53e,,Stable ABI}.'
Return the current destructor stored in the capsule.  On failure, set an
exception and return @code{NULL}.

It is legal for a capsule to have a @code{NULL} destructor.  This makes a @code{NULL}
return code somewhat ambiguous; use @ref{1333,,PyCapsule_IsValid()} or
@ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_GetContext (C function)
@anchor{c-api/capsule c PyCapsule_GetContext}@anchor{4880}
@deffn {C Fonction} void *PyCapsule_GetContext (PyObject *capsule)
` Part of the @ref{53e,,Stable ABI}.'
Return the current context stored in the capsule.  On failure, set an
exception and return @code{NULL}.

It is legal for a capsule to have a @code{NULL} context.  This makes a @code{NULL}
return code somewhat ambiguous; use @ref{1333,,PyCapsule_IsValid()} or
@ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_GetName (C function)
@anchor{c-api/capsule c PyCapsule_GetName}@anchor{4882}
@deffn {C Fonction} const char *PyCapsule_GetName (PyObject *capsule)
` Part of the @ref{53e,,Stable ABI}.'
Return the current name stored in the capsule.  On failure, set an exception
and return @code{NULL}.

It is legal for a capsule to have a @code{NULL} name.  This makes a @code{NULL} return
code somewhat ambiguous; use @ref{1333,,PyCapsule_IsValid()} or
@ref{187f,,PyErr_Occurred()} to disambiguate.
@end deffn

@geindex PyCapsule_Import (C function)
@anchor{c-api/capsule c PyCapsule_Import}@anchor{17fb}
@deffn {C Fonction} void *PyCapsule_Import (const char *name, int no_block)
` Part of the @ref{53e,,Stable ABI}.'
Import a pointer to a C object from a capsule attribute in a module.  The
`name' parameter should specify the full name to the attribute, as in
@code{module.attribute}.  The `name' stored in the capsule must match this
string exactly.

Return the capsule's internal `pointer' on success.  On failure, set an
exception and return @code{NULL}.


Modifié dans la version 3.3: `no_block' has no effect anymore.

@end deffn

@geindex PyCapsule_IsValid (C function)
@anchor{c-api/capsule c PyCapsule_IsValid}@anchor{1333}
@deffn {C Fonction} int PyCapsule_IsValid (PyObject *capsule, const char *name)
` Part of the @ref{53e,,Stable ABI}.'
Determines whether or not `capsule' is a valid capsule.  A valid capsule is
non-@code{NULL}, passes @ref{4be0,,PyCapsule_CheckExact()}, has a non-@code{NULL} pointer
stored in it, and its internal name matches the `name' parameter.  (See
@ref{4883,,PyCapsule_GetPointer()} for information on how capsule names are
compared.)

In other words, if @ref{1333,,PyCapsule_IsValid()} returns a true value, calls to
any of the accessors (any function starting with @code{PyCapsule_Get}) are
guaranteed to succeed.

Return a nonzero value if the object is valid and matches the name passed in.
Return @code{0} otherwise.  This function will not fail.
@end deffn

@geindex PyCapsule_SetContext (C function)
@anchor{c-api/capsule c PyCapsule_SetContext}@anchor{4884}
@deffn {C Fonction} int PyCapsule_SetContext (PyObject *capsule, void *context)
` Part of the @ref{53e,,Stable ABI}.'
Set the context pointer inside `capsule' to `context'.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@geindex PyCapsule_SetDestructor (C function)
@anchor{c-api/capsule c PyCapsule_SetDestructor}@anchor{4885}
@deffn {C Fonction} int PyCapsule_SetDestructor (PyObject *capsule, PyCapsule_Destructor destructor)
` Part of the @ref{53e,,Stable ABI}.'
Set the destructor inside `capsule' to `destructor'.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@geindex PyCapsule_SetName (C function)
@anchor{c-api/capsule c PyCapsule_SetName}@anchor{4886}
@deffn {C Fonction} int PyCapsule_SetName (PyObject *capsule, const char *name)
` Part of the @ref{53e,,Stable ABI}.'
Set the name inside `capsule' to `name'.  If non-@code{NULL}, the name must
outlive the capsule.  If the previous `name' stored in the capsule was not
@code{NULL}, no attempt is made to free it.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@geindex PyCapsule_SetPointer (C function)
@anchor{c-api/capsule c PyCapsule_SetPointer}@anchor{4887}
@deffn {C Fonction} int PyCapsule_SetPointer (PyObject *capsule, void *pointer)
` Part of the @ref{53e,,Stable ABI}.'
Set the void pointer inside `capsule' to `pointer'.  The pointer may not be
@code{NULL}.

Return @code{0} on success.  Return nonzero and set an exception on failure.
@end deffn

@node Objets décrivant les frames,Objets générateur,Capsules<2>,Autres objets<2>
@anchor{c-api/frame doc}@anchor{4be1}@anchor{c-api/frame frame-objects}@anchor{4be2}
@subsubsection Objets décrivant les `frames'


@geindex PyFrameObject (C type)
@anchor{c-api/frame c PyFrameObject}@anchor{773}
@deffn {C Type} type PyFrameObject
` Part of the @ref{53e,,Limited API} (as an opaque struct).'
Structure des objets C utilisée pour décrire les objets `frame'.

Il n'y a pas de membres publics dans cette structure.


Modifié dans la version 3.11: Les membres de la structure API publique ont été retirés de l'API publique de C. Visiter @ref{772,,l'entrée dans la page des nouveautés de Python} pour plus détails.

@end deffn

Les fonctions @code{PyEval_GetFrame()} et @ref{778,,PyThreadState_GetFrame()} peuvent être utilisées pour avoir un objet de `frame'.

Voir aussi @ref{4a33,,Réflexion}

@geindex PyFrame_Type (C var)
@anchor{c-api/frame c PyFrame_Type}@anchor{771}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyFrame_Type

Le type des objets de `frame'. C'est le même objet que @ref{17df,,types.FrameType} dans la couche de Python.


Modifié dans la version 3.11: Précédemment, ce type était disponible uniquement après l'inclusion de @code{<frameobject.h>}.

@end deffn

@geindex PyFrame_Check (C function)
@anchor{c-api/frame c PyFrame_Check}@anchor{76f}
@deffn {C Fonction} int PyFrame_Check (PyObject *obj)

Renvoie un entier non nul si `obj' est un objet `frame'.


Modifié dans la version 3.11: Précédemment, ce type était disponible uniquement après l'inclusion de @code{<frameobject.h>}.

@end deffn

@geindex PyFrame_GetBack (C function)
@anchor{c-api/frame c PyFrame_GetBack}@anchor{770}
@deffn {C Fonction} @ref{773,,PyFrameObject} *PyFrame_GetBack (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'
Renvoie la `frame' encadrant immédiatement à `frame'.

Renvoie un @ref{333,,strong reference}, ou @code{NULL} si `frame' n'a pas de `frame' encadrante.


Ajouté dans la version 3.9.

@end deffn

@geindex PyFrame_GetBuiltins (C function)
@anchor{c-api/frame c PyFrame_GetBuiltins}@anchor{755}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrame_GetBuiltins (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'
Get the `frame''s @ref{1ed2,,f_builtins} attribute.

Renvoie un @ref{333,,strong reference}. Le résultat ne peut être @code{NULL}.


Ajouté dans la version 3.11.

@end deffn

@geindex PyFrame_GetCode (C function)
@anchor{c-api/frame c PyFrame_GetCode}@anchor{774}
@deffn {C Fonction} @ref{761,,PyCodeObject} *PyFrame_GetCode (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Obtenir le code `frame'.

Renvoie un @ref{333,,strong reference}.

Le résultat (code `frame') ne peut être @code{NULL}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyFrame_GetGenerator (C function)
@anchor{c-api/frame c PyFrame_GetGenerator}@anchor{756}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrame_GetGenerator (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'
Obtenir le générateur, coroutine, ou un générateur asynchrone qui maintient cette `frame', ou @code{NULL} si cette `frame' n'est pas maintenu par un générateur. Il ne lève pas d'exception, même si la valeur renvoyée est @code{NULL}.

Renvoie un @ref{333,,strong reference}, ou @code{NULL}.


Ajouté dans la version 3.11.

@end deffn

@geindex PyFrame_GetGlobals (C function)
@anchor{c-api/frame c PyFrame_GetGlobals}@anchor{757}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrame_GetGlobals (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'
Get the `frame''s @ref{1ed1,,f_globals} attribute.

Renvoie un @ref{333,,strong reference}. Le résultat ne peut être @code{NULL}.


Ajouté dans la version 3.11.

@end deffn

@geindex PyFrame_GetLasti (C function)
@anchor{c-api/frame c PyFrame_GetLasti}@anchor{758}
@deffn {C Fonction} int PyFrame_GetLasti (PyFrameObject *frame)

Get the `frame''s @ref{874,,f_lasti} attribute.

Renvoie -1 si @code{frame.f_lasti} est @code{None}.


Ajouté dans la version 3.11.

@end deffn

@geindex PyFrame_GetVar (C function)
@anchor{c-api/frame c PyFrame_GetVar}@anchor{554}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrame_GetVar (PyFrameObject *frame, PyObject *name)
`Valeur de retour : nouvelle référence.'
Get the variable `name' of `frame'.


@itemize *

@item 
Return a @ref{333,,strong reference} to the variable value on success.

@item 
Raise @ref{428,,NameError} and return @code{NULL} if the variable does not exist.

@item 
Raise an exception and return @code{NULL} on error.
@end itemize

`name' type must be a @ref{435,,str}.


Ajouté dans la version 3.12.

@end deffn

@geindex PyFrame_GetVarString (C function)
@anchor{c-api/frame c PyFrame_GetVarString}@anchor{555}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrame_GetVarString (PyFrameObject *frame, const char *name)
`Valeur de retour : nouvelle référence.'
Similar to @ref{554,,PyFrame_GetVar()}, but the variable name is a C string
encoded in UTF-8.


Ajouté dans la version 3.12.

@end deffn

@geindex PyFrame_GetLocals (C function)
@anchor{c-api/frame c PyFrame_GetLocals}@anchor{415}
@deffn {C Fonction} @ref{32f,,PyObject} *PyFrame_GetLocals (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'
Get the `frame''s @ref{180,,f_locals} attribute.
If the frame refers to an @ref{17c,,optimized scope}, this returns a
write-through proxy object that allows modifying the locals.
In all other cases (classes, modules, @ref{17d,,exec()}, @ref{17e,,eval()}) it returns
the mapping representing the frame locals directly (as described for
@ref{140,,locals()}).

Renvoie un @ref{333,,strong reference}.


Ajouté dans la version 3.11.



Modifié dans la version 3.13: As part of 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/}, return an instance of @ref{4be3,,PyFrameLocalsProxy_Type}.

@end deffn

@geindex PyFrame_GetLineNumber (C function)
@anchor{c-api/frame c PyFrame_GetLineNumber}@anchor{775}
@deffn {C Fonction} int PyFrame_GetLineNumber (PyFrameObject *frame)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Renvoie le numéro de ligne que cette `frame' est en train d'exécuter.
@end deffn

@menu
* Frame Locals Proxies:: 
* Internal Frames:: 

@end menu

@node Frame Locals Proxies,Internal Frames,,Objets décrivant les frames
@anchor{c-api/frame frame-locals-proxies}@anchor{4be4}
@subsubsection Frame Locals Proxies



Ajouté dans la version 3.13.


The @ref{180,,f_locals} attribute on a @ref{6ca,,frame object}
is an instance of a "frame-locals proxy". The proxy object exposes a
write-through view of the underlying locals dictionary for the frame. This
ensures that the variables exposed by @code{f_locals} are always up to date with
the live local variables in the frame itself.

See 
@geindex Python Enhancement Proposals; PEP 667
PEP 667@footnote{https://peps.python.org/pep-0667/} for more information.

@geindex PyFrameLocalsProxy_Type (C var)
@anchor{c-api/frame c PyFrameLocalsProxy_Type}@anchor{4be3}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyFrameLocalsProxy_Type

The type of frame @ref{140,,locals()} proxy objects.
@end deffn

@geindex PyFrameLocalsProxy_Check (C function)
@anchor{c-api/frame c PyFrameLocalsProxy_Check}@anchor{4be5}
@deffn {C Fonction} int PyFrameLocalsProxy_Check (PyObject *obj)

Return non-zero if `obj' is a frame @ref{140,,locals()} proxy.
@end deffn

@node Internal Frames,,Frame Locals Proxies,Objets décrivant les frames
@anchor{c-api/frame internal-frames}@anchor{4be6}
@subsubsection Internal Frames


Unless using 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/}, you will not need this.

@geindex _PyInterpreterFrame (C struct)
@anchor{c-api/frame c _PyInterpreterFrame}@anchor{4be7}
@deffn {C Structure} struct _PyInterpreterFrame

The interpreter's internal frame representation.


Ajouté dans la version 3.11.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetCode (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetCode}@anchor{4be8}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnstable_InterpreterFrame_GetCode (struct _PyInterpreterFrame *frame);

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

@quotation

Return a @ref{333,,strong reference} to the code object for the frame.
@end quotation


Ajouté dans la version 3.12.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetLasti (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetLasti}@anchor{4be9}
@deffn {C Fonction} int PyUnstable_InterpreterFrame_GetLasti (struct _PyInterpreterFrame *frame);

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Return the byte offset into the last executed instruction.


Ajouté dans la version 3.12.

@end deffn

@geindex PyUnstable_InterpreterFrame_GetLine (C function)
@anchor{c-api/frame c PyUnstable_InterpreterFrame_GetLine}@anchor{4bea}
@deffn {C Fonction} int PyUnstable_InterpreterFrame_GetLine (struct _PyInterpreterFrame *frame);

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Return the currently executing line number, or -1 if there is no line number.


Ajouté dans la version 3.12.

@end deffn

@node Objets générateur,Objets coroutines<2>,Objets décrivant les frames,Autres objets<2>
@anchor{c-api/gen doc}@anchor{4beb}@anchor{c-api/gen gen-objects}@anchor{4bec}@anchor{c-api/gen generator-objects}@anchor{4bed}
@subsubsection Objets générateur


Python utilise des objets générateurs pour implémenter les itérations de générateurs. Ils sont normalement crées en itérant sur une fonction donnant des valeurs via @code{yield}, au lieu d'appeler explicitement @ref{4bee,,PyGen_New()} ou @ref{4bef,,PyGen_NewWithQualName()}.

@geindex PyGenObject (C type)
@anchor{c-api/gen c PyGenObject}@anchor{4bf0}
@deffn {C Type} type PyGenObject

La structure C utilisée pour les objets générateurs.
@end deffn

@geindex PyGen_Type (C var)
@anchor{c-api/gen c PyGen_Type}@anchor{4bf1}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyGen_Type

Le type objet correspondant aux objets générateurs.
@end deffn

@geindex PyGen_Check (C function)
@anchor{c-api/gen c PyGen_Check}@anchor{4bf2}
@deffn {C Fonction} int PyGen_Check (PyObject *ob)

Return true if `ob' is a generator object; `ob' must not be @code{NULL}.  This
function always succeeds.
@end deffn

@geindex PyGen_CheckExact (C function)
@anchor{c-api/gen c PyGen_CheckExact}@anchor{4bf3}
@deffn {C Fonction} int PyGen_CheckExact (PyObject *ob)

Return true if `ob''s type is @ref{4bf1,,PyGen_Type}; `ob' must not be
@code{NULL}.  This function always succeeds.
@end deffn

@geindex PyGen_New (C function)
@anchor{c-api/gen c PyGen_New}@anchor{4bee}
@deffn {C Fonction} @ref{32f,,PyObject} *PyGen_New (PyFrameObject *frame)
`Valeur de retour : nouvelle référence.'
Create and return a new generator object based on the `frame' object.
A reference to `frame' is stolen by this function. The argument must not be
@code{NULL}.
@end deffn

@geindex PyGen_NewWithQualName (C function)
@anchor{c-api/gen c PyGen_NewWithQualName}@anchor{4bef}
@deffn {C Fonction} @ref{32f,,PyObject} *PyGen_NewWithQualName (PyFrameObject *frame, PyObject *name, PyObject *qualname)
`Valeur de retour : nouvelle référence.'
Create and return a new generator object based on the `frame' object,
with @code{__name__} and @code{__qualname__} set to `name' and `qualname'.
A reference to `frame' is stolen by this function.  The `frame' argument
must not be @code{NULL}.
@end deffn

@node Objets coroutines<2>,Context Variables Objects,Objets générateur,Autres objets<2>
@anchor{c-api/coro doc}@anchor{4bf4}@anchor{c-api/coro coro-objects}@anchor{eb9}@anchor{c-api/coro coroutine-objects}@anchor{4bf5}
@subsubsection Objets coroutines



Ajouté dans la version 3.5.


Les objets coroutines sont les objets renvoyés par les fonctions déclarées avec le mot clef @code{async}.

@geindex PyCoroObject (C type)
@anchor{c-api/coro c PyCoroObject}@anchor{4bf6}
@deffn {C Type} type PyCoroObject

La structure C utilisée pour les objets coroutine.
@end deffn

@geindex PyCoro_Type (C var)
@anchor{c-api/coro c PyCoro_Type}@anchor{4bf7}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyCoro_Type

L'objet type correspondant aux objets coroutines.
@end deffn

@geindex PyCoro_CheckExact (C function)
@anchor{c-api/coro c PyCoro_CheckExact}@anchor{4bf8}
@deffn {C Fonction} int PyCoro_CheckExact (PyObject *ob)

Return true if `ob''s type is @ref{4bf7,,PyCoro_Type}; `ob' must not be @code{NULL}.
This function always succeeds.
@end deffn

@geindex PyCoro_New (C function)
@anchor{c-api/coro c PyCoro_New}@anchor{4bf9}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCoro_New (PyFrameObject *frame, PyObject *name, PyObject *qualname)
`Valeur de retour : nouvelle référence.'
Create and return a new coroutine object based on the `frame' object,
with @code{__name__} and @code{__qualname__} set to `name' and `qualname'.
A reference to `frame' is stolen by this function.  The `frame' argument
must not be @code{NULL}.
@end deffn

@node Context Variables Objects,Objets DateTime<2>,Objets coroutines<2>,Autres objets<2>
@anchor{c-api/contextvars doc}@anchor{4bfa}@anchor{c-api/contextvars context-variables-objects}@anchor{4bfb}@anchor{c-api/contextvars contextvarsobjects}@anchor{ae6}
@subsubsection Context Variables Objects

@anchor{c-api/contextvars contextvarsobjects-pointertype-change}@anchor{c14}

Ajouté dans la version 3.7.



Modifié dans la version 3.7.1: 

@cartouche
@quotation Note 
In Python 3.7.1 the signatures of all context variables
C APIs were `changed' to use @ref{32f,,PyObject} pointers instead
of @ref{4bfc,,PyContext}, @ref{4bfd,,PyContextVar}, and
@ref{4bfe,,PyContextToken}, e.g.:

@example
// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);
@end example

See bpo-34762@footnote{https://bugs.python.org/issue?@@action=redirect&bpo=34762} for more details.
@end quotation
@end cartouche


This section details the public C API for the @ref{24,,contextvars} module.

@geindex PyContext (C type)
@anchor{c-api/contextvars c PyContext}@anchor{4bfc}
@deffn {C Type} type PyContext

The C structure used to represent a @ref{152f,,contextvars.Context}
object.
@end deffn

@geindex PyContextVar (C type)
@anchor{c-api/contextvars c PyContextVar}@anchor{4bfd}
@deffn {C Type} type PyContextVar

The C structure used to represent a @ref{31af,,contextvars.ContextVar}
object.
@end deffn

@geindex PyContextToken (C type)
@anchor{c-api/contextvars c PyContextToken}@anchor{4bfe}
@deffn {C Type} type PyContextToken

The C structure used to represent a @ref{31b5,,contextvars.Token} object.
@end deffn

@geindex PyContext_Type (C var)
@anchor{c-api/contextvars c PyContext_Type}@anchor{4bff}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyContext_Type

The type object representing the `context' type.
@end deffn

@geindex PyContextVar_Type (C var)
@anchor{c-api/contextvars c PyContextVar_Type}@anchor{4c00}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyContextVar_Type

The type object representing the `context variable' type.
@end deffn

@geindex PyContextToken_Type (C var)
@anchor{c-api/contextvars c PyContextToken_Type}@anchor{4c01}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyContextToken_Type

The type object representing the `context variable token' type.
@end deffn

Macros pour vérifier les types :

@geindex PyContext_CheckExact (C function)
@anchor{c-api/contextvars c PyContext_CheckExact}@anchor{4c02}
@deffn {C Fonction} int PyContext_CheckExact (PyObject *o)

Return true if `o' is of type @ref{4bff,,PyContext_Type}. `o' must not be
@code{NULL}.  This function always succeeds.
@end deffn

@geindex PyContextVar_CheckExact (C function)
@anchor{c-api/contextvars c PyContextVar_CheckExact}@anchor{4c03}
@deffn {C Fonction} int PyContextVar_CheckExact (PyObject *o)

Return true if `o' is of type @ref{4c00,,PyContextVar_Type}. `o' must not be
@code{NULL}.  This function always succeeds.
@end deffn

@geindex PyContextToken_CheckExact (C function)
@anchor{c-api/contextvars c PyContextToken_CheckExact}@anchor{4c04}
@deffn {C Fonction} int PyContextToken_CheckExact (PyObject *o)

Return true if `o' is of type @ref{4c01,,PyContextToken_Type}.
`o' must not be @code{NULL}.  This function always succeeds.
@end deffn

Context object management functions:

@geindex PyContext_New (C function)
@anchor{c-api/contextvars c PyContext_New}@anchor{4c05}
@deffn {C Fonction} @ref{32f,,PyObject} *PyContext_New (void)
`Valeur de retour : nouvelle référence.'
Create a new empty context object.  Returns @code{NULL} if an error
has occurred.
@end deffn

@geindex PyContext_Copy (C function)
@anchor{c-api/contextvars c PyContext_Copy}@anchor{4c06}
@deffn {C Fonction} @ref{32f,,PyObject} *PyContext_Copy (PyObject *ctx)
`Valeur de retour : nouvelle référence.'
Create a shallow copy of the passed `ctx' context object.
Returns @code{NULL} if an error has occurred.
@end deffn

@geindex PyContext_CopyCurrent (C function)
@anchor{c-api/contextvars c PyContext_CopyCurrent}@anchor{4c07}
@deffn {C Fonction} @ref{32f,,PyObject} *PyContext_CopyCurrent (void)
`Valeur de retour : nouvelle référence.'
Create a shallow copy of the current thread context.
Returns @code{NULL} if an error has occurred.
@end deffn

@geindex PyContext_Enter (C function)
@anchor{c-api/contextvars c PyContext_Enter}@anchor{4c08}
@deffn {C Fonction} int PyContext_Enter (PyObject *ctx)

Set `ctx' as the current context for the current thread.
Returns @code{0} on success, and @code{-1} on error.
@end deffn

@geindex PyContext_Exit (C function)
@anchor{c-api/contextvars c PyContext_Exit}@anchor{4c09}
@deffn {C Fonction} int PyContext_Exit (PyObject *ctx)

Deactivate the `ctx' context and restore the previous context as the
current context for the current thread.  Returns @code{0} on success,
and @code{-1} on error.
@end deffn

Context variable functions:

@geindex PyContextVar_New (C function)
@anchor{c-api/contextvars c PyContextVar_New}@anchor{4c0a}
@deffn {C Fonction} @ref{32f,,PyObject} *PyContextVar_New (const char *name, PyObject *def)
`Valeur de retour : nouvelle référence.'
Create a new @code{ContextVar} object.  The `name' parameter is used
for introspection and debug purposes.  The `def' parameter specifies
a default value for the context variable, or @code{NULL} for no default.
If an error has occurred, this function returns @code{NULL}.
@end deffn

@geindex PyContextVar_Get (C function)
@anchor{c-api/contextvars c PyContextVar_Get}@anchor{4c0b}
@deffn {C Fonction} int PyContextVar_Get (PyObject *var, PyObject *default_value, PyObject **value)

Get the value of a context variable.  Returns @code{-1} if an error has
occurred during lookup, and @code{0} if no error occurred, whether or not
a value was found.

If the context variable was found, `value' will be a pointer to it.
If the context variable was `not' found, `value' will point to:


@itemize -

@item 
`default_value', if not @code{NULL};

@item 
the default value of `var', if not @code{NULL};

@item 
@code{NULL}
@end itemize

Except for @code{NULL}, the function returns a new reference.
@end deffn

@geindex PyContextVar_Set (C function)
@anchor{c-api/contextvars c PyContextVar_Set}@anchor{4c0c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyContextVar_Set (PyObject *var, PyObject *value)
`Valeur de retour : nouvelle référence.'
Set the value of `var' to `value' in the current context.  Returns
a new token object for this change, or @code{NULL} if an error has occurred.
@end deffn

@geindex PyContextVar_Reset (C function)
@anchor{c-api/contextvars c PyContextVar_Reset}@anchor{4c0d}
@deffn {C Fonction} int PyContextVar_Reset (PyObject *var, PyObject *token)

Reset the state of the `var' context variable to that it was in before
@ref{4c0c,,PyContextVar_Set()} that returned the `token' was called.
This function returns @code{0} on success and @code{-1} on error.
@end deffn

@node Objets DateTime<2>,Objects for Type Hinting,Context Variables Objects,Autres objets<2>
@anchor{c-api/datetime doc}@anchor{4c0e}@anchor{c-api/datetime datetime-objects}@anchor{4c0f}@anchor{c-api/datetime datetimeobjects}@anchor{4a39}
@subsubsection Objets DateTime


Various date and time objects are supplied by the @ref{30,,datetime} module.
Before using any of these functions, the header file @code{datetime.h} must be
included in your source (note that this is not included by @code{Python.h}),
and the macro @code{PyDateTime_IMPORT} must be invoked, usually as part of
the module initialisation function.  The macro puts a pointer to a C structure
into a static variable, @code{PyDateTimeAPI}, that is used by the following
macros.

@geindex PyDateTime_Date (C type)
@anchor{c-api/datetime c PyDateTime_Date}@anchor{4c10}
@deffn {C Type} type PyDateTime_Date

This subtype of @ref{32f,,PyObject} represents a Python date object.
@end deffn

@geindex PyDateTime_DateTime (C type)
@anchor{c-api/datetime c PyDateTime_DateTime}@anchor{4c11}
@deffn {C Type} type PyDateTime_DateTime

This subtype of @ref{32f,,PyObject} represents a Python datetime object.
@end deffn

@geindex PyDateTime_Time (C type)
@anchor{c-api/datetime c PyDateTime_Time}@anchor{4c12}
@deffn {C Type} type PyDateTime_Time

This subtype of @ref{32f,,PyObject} represents a Python time object.
@end deffn

@geindex PyDateTime_Delta (C type)
@anchor{c-api/datetime c PyDateTime_Delta}@anchor{4c13}
@deffn {C Type} type PyDateTime_Delta

This subtype of @ref{32f,,PyObject} represents the difference between two datetime values.
@end deffn

@geindex PyDateTime_DateType (C var)
@anchor{c-api/datetime c PyDateTime_DateType}@anchor{4c14}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyDateTime_DateType

This instance of @ref{a93,,PyTypeObject} represents the Python date type;
it is the same object as @ref{1c8,,datetime.date} in the Python layer.
@end deffn

@geindex PyDateTime_DateTimeType (C var)
@anchor{c-api/datetime c PyDateTime_DateTimeType}@anchor{4c15}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyDateTime_DateTimeType

This instance of @ref{a93,,PyTypeObject} represents the Python datetime type;
it is the same object as @ref{1c7,,datetime.datetime} in the Python layer.
@end deffn

@geindex PyDateTime_TimeType (C var)
@anchor{c-api/datetime c PyDateTime_TimeType}@anchor{4c16}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyDateTime_TimeType

This instance of @ref{a93,,PyTypeObject} represents the Python time type;
it is the same object as @ref{1c9,,datetime.time} in the Python layer.
@end deffn

@geindex PyDateTime_DeltaType (C var)
@anchor{c-api/datetime c PyDateTime_DeltaType}@anchor{4c17}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyDateTime_DeltaType

This instance of @ref{a93,,PyTypeObject} represents Python type for
the difference between two datetime values;
it is the same object as @ref{9bd,,datetime.timedelta} in the Python layer.
@end deffn

@geindex PyDateTime_TZInfoType (C var)
@anchor{c-api/datetime c PyDateTime_TZInfoType}@anchor{4c18}
@deffn {C Variable} @ref{a93,,PyTypeObject} PyDateTime_TZInfoType

This instance of @ref{a93,,PyTypeObject} represents the Python time zone info type;
it is the same object as @ref{5c8,,datetime.tzinfo} in the Python layer.
@end deffn

Macro pour accéder au singleton UTC :

@geindex PyDateTime_TimeZone_UTC (C var)
@anchor{c-api/datetime c PyDateTime_TimeZone_UTC}@anchor{bb1}
@deffn {C Variable} @ref{32f,,PyObject} *PyDateTime_TimeZone_UTC

Renvoie le singleton du fuseau horaire UTC, qui est le même objet que @ref{5ff,,datetime.timezone.utc}.


Ajouté dans la version 3.7.

@end deffn

Macros pour vérifier les types :

@geindex PyDate_Check (C function)
@anchor{c-api/datetime c PyDate_Check}@anchor{4c19}
@deffn {C Fonction} int PyDate_Check (PyObject *ob)

Return true if `ob' is of type @ref{4c14,,PyDateTime_DateType} or a subtype of
@code{PyDateTime_DateType}.  `ob' must not be @code{NULL}.  This function always
succeeds.
@end deffn

@geindex PyDate_CheckExact (C function)
@anchor{c-api/datetime c PyDate_CheckExact}@anchor{4c1a}
@deffn {C Fonction} int PyDate_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{4c14,,PyDateTime_DateType}. `ob' must not be
@code{NULL}.  This function always succeeds.
@end deffn

@geindex PyDateTime_Check (C function)
@anchor{c-api/datetime c PyDateTime_Check}@anchor{4c1b}
@deffn {C Fonction} int PyDateTime_Check (PyObject *ob)

Return true if `ob' is of type @ref{4c15,,PyDateTime_DateTimeType} or a subtype of
@code{PyDateTime_DateTimeType}.  `ob' must not be @code{NULL}.  This function always
succeeds.
@end deffn

@geindex PyDateTime_CheckExact (C function)
@anchor{c-api/datetime c PyDateTime_CheckExact}@anchor{4c1c}
@deffn {C Fonction} int PyDateTime_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{4c15,,PyDateTime_DateTimeType}. `ob' must not
be @code{NULL}.  This function always succeeds.
@end deffn

@geindex PyTime_Check (C function)
@anchor{c-api/datetime c PyTime_Check}@anchor{4c1d}
@deffn {C Fonction} int PyTime_Check (PyObject *ob)

Return true if `ob' is of type @ref{4c16,,PyDateTime_TimeType} or a subtype of
@code{PyDateTime_TimeType}.  `ob' must not be @code{NULL}.  This function always
succeeds.
@end deffn

@geindex PyTime_CheckExact (C function)
@anchor{c-api/datetime c PyTime_CheckExact}@anchor{4c1e}
@deffn {C Fonction} int PyTime_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{4c16,,PyDateTime_TimeType}. `ob' must not be
@code{NULL}.  This function always succeeds.
@end deffn

@geindex PyDelta_Check (C function)
@anchor{c-api/datetime c PyDelta_Check}@anchor{4c1f}
@deffn {C Fonction} int PyDelta_Check (PyObject *ob)

Return true if `ob' is of type @ref{4c17,,PyDateTime_DeltaType} or a subtype of
@code{PyDateTime_DeltaType}.  `ob' must not be @code{NULL}.  This function always
succeeds.
@end deffn

@geindex PyDelta_CheckExact (C function)
@anchor{c-api/datetime c PyDelta_CheckExact}@anchor{4c20}
@deffn {C Fonction} int PyDelta_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{4c17,,PyDateTime_DeltaType}. `ob' must not be
@code{NULL}.  This function always succeeds.
@end deffn

@geindex PyTZInfo_Check (C function)
@anchor{c-api/datetime c PyTZInfo_Check}@anchor{4c21}
@deffn {C Fonction} int PyTZInfo_Check (PyObject *ob)

Return true if `ob' is of type @ref{4c18,,PyDateTime_TZInfoType} or a subtype of
@code{PyDateTime_TZInfoType}.  `ob' must not be @code{NULL}.  This function always
succeeds.
@end deffn

@geindex PyTZInfo_CheckExact (C function)
@anchor{c-api/datetime c PyTZInfo_CheckExact}@anchor{4c22}
@deffn {C Fonction} int PyTZInfo_CheckExact (PyObject *ob)

Return true if `ob' is of type @ref{4c18,,PyDateTime_TZInfoType}. `ob' must not be
@code{NULL}.  This function always succeeds.
@end deffn

Macros pour créer des objets :

@geindex PyDate_FromDate (C function)
@anchor{c-api/datetime c PyDate_FromDate}@anchor{4c23}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDate_FromDate (int year, int month, int day)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{1c8,,datetime.date} avec l'année, le mois et le jour spécifiés.
@end deffn

@geindex PyDateTime_FromDateAndTime (C function)
@anchor{c-api/datetime c PyDateTime_FromDateAndTime}@anchor{4c24}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDateTime_FromDateAndTime (int year, int month, int day, int hour, int minute, int second, int usecond)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{1c7,,datetime.datetime} avec l'année, le mois, le jour, l'heure, la minute, la seconde et la microseconde spécifiés.
@end deffn

@geindex PyDateTime_FromDateAndTimeAndFold (C function)
@anchor{c-api/datetime c PyDateTime_FromDateAndTimeAndFold}@anchor{4c25}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDateTime_FromDateAndTimeAndFold (int year, int month, int day, int hour, int minute, int second, int usecond, int fold)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{1c7,,datetime.datetime} avec l'année, le mois, le jour, l'heure, la minute, la seconde, la microseconde et le pli (`fold' en anglais) spécifiés.


Ajouté dans la version 3.6.

@end deffn

@geindex PyTime_FromTime (C function)
@anchor{c-api/datetime c PyTime_FromTime}@anchor{4c26}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTime_FromTime (int hour, int minute, int second, int usecond)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{1c9,,datetime.time} avec l'heure, la minute, la seconde et la microseconde spécifiées.
@end deffn

@geindex PyTime_FromTimeAndFold (C function)
@anchor{c-api/datetime c PyTime_FromTimeAndFold}@anchor{4c27}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTime_FromTimeAndFold (int hour, int minute, int second, int usecond, int fold)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{1c9,,datetime.time} avec l'heure, la minute, la seconde, la microseconde et le pli (`fold' en anglais) spécifiés.


Ajouté dans la version 3.6.

@end deffn

@geindex PyDelta_FromDSU (C function)
@anchor{c-api/datetime c PyDelta_FromDSU}@anchor{4c28}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDelta_FromDSU (int days, int seconds, int useconds)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{9bd,,datetime.timedelta} représentant le nombre passé en paramètre de jours, de secondes et de microsecondes. Le résultat est normalisé pour que le nombre de microsecondes et de secondes tombe dans la plage documentée pour les objets @ref{9bd,,datetime.timedelta}.
@end deffn

@geindex PyTimeZone_FromOffset (C function)
@anchor{c-api/datetime c PyTimeZone_FromOffset}@anchor{baf}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTimeZone_FromOffset (PyObject *offset)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{10a1,,datetime.timezone} avec un décalage anonyme fixe représenté par l'argument `offset'.


Ajouté dans la version 3.7.

@end deffn

@geindex PyTimeZone_FromOffsetAndName (C function)
@anchor{c-api/datetime c PyTimeZone_FromOffsetAndName}@anchor{bb0}
@deffn {C Fonction} @ref{32f,,PyObject} *PyTimeZone_FromOffsetAndName (PyObject *offset, PyObject *name)
`Valeur de retour : nouvelle référence.'
Renvoie un objet @ref{10a1,,datetime.timezone} avec un décalage fixe représenté par l'argument `offset' et avec le nom de fuseau horaire `name'.


Ajouté dans la version 3.7.

@end deffn

Macros to extract fields from date objects.  The argument must be an instance of
@ref{4c10,,PyDateTime_Date}, including subclasses (such as
@ref{4c11,,PyDateTime_DateTime}).  The argument must not be @code{NULL}, and the type is
not checked:

@geindex PyDateTime_GET_YEAR (C function)
@anchor{c-api/datetime c PyDateTime_GET_YEAR}@anchor{4c29}
@deffn {C Fonction} int PyDateTime_GET_YEAR (PyDateTime_Date *o)

Renvoie l'année, sous forme d'entier positif.
@end deffn

@geindex PyDateTime_GET_MONTH (C function)
@anchor{c-api/datetime c PyDateTime_GET_MONTH}@anchor{4c2a}
@deffn {C Fonction} int PyDateTime_GET_MONTH (PyDateTime_Date *o)

Renvoie le mois, sous forme d'entier allant de 1 à 12.
@end deffn

@geindex PyDateTime_GET_DAY (C function)
@anchor{c-api/datetime c PyDateTime_GET_DAY}@anchor{4c2b}
@deffn {C Fonction} int PyDateTime_GET_DAY (PyDateTime_Date *o)

Renvoie le jour, sous forme d'entier allant de 1 à 31.
@end deffn

Macros to extract fields from datetime objects.  The argument must be an
instance of @ref{4c11,,PyDateTime_DateTime}, including subclasses. The argument
must not be @code{NULL}, and the type is not checked:

@geindex PyDateTime_DATE_GET_HOUR (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_HOUR}@anchor{4c2c}
@deffn {C Fonction} int PyDateTime_DATE_GET_HOUR (PyDateTime_DateTime *o)

Renvoie l'heure, sous forme d'entier allant de 0 à 23.
@end deffn

@geindex PyDateTime_DATE_GET_MINUTE (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_MINUTE}@anchor{4c2d}
@deffn {C Fonction} int PyDateTime_DATE_GET_MINUTE (PyDateTime_DateTime *o)

Renvoie la minute, sous forme d'entier allant de 0 à 59.
@end deffn

@geindex PyDateTime_DATE_GET_SECOND (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_SECOND}@anchor{4c2e}
@deffn {C Fonction} int PyDateTime_DATE_GET_SECOND (PyDateTime_DateTime *o)

Renvoie la seconde, sous forme d'entier allant de 0 à 59.
@end deffn

@geindex PyDateTime_DATE_GET_MICROSECOND (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_MICROSECOND}@anchor{4c2f}
@deffn {C Fonction} int PyDateTime_DATE_GET_MICROSECOND (PyDateTime_DateTime *o)

Renvoie la microseconde, sous forme d'entier allant de 0 à 999999.
@end deffn

@geindex PyDateTime_DATE_GET_FOLD (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_FOLD}@anchor{4c30}
@deffn {C Fonction} int PyDateTime_DATE_GET_FOLD (PyDateTime_DateTime *o)

Return the fold, as an int from 0 through 1.


Ajouté dans la version 3.6.

@end deffn

@geindex PyDateTime_DATE_GET_TZINFO (C function)
@anchor{c-api/datetime c PyDateTime_DATE_GET_TZINFO}@anchor{881}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDateTime_DATE_GET_TZINFO (PyDateTime_DateTime *o)

Return the tzinfo (which may be @code{None}).


Ajouté dans la version 3.10.

@end deffn

Macros to extract fields from time objects.  The argument must be an instance of
@ref{4c12,,PyDateTime_Time}, including subclasses. The argument must not be @code{NULL},
and the type is not checked:

@geindex PyDateTime_TIME_GET_HOUR (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_HOUR}@anchor{4c31}
@deffn {C Fonction} int PyDateTime_TIME_GET_HOUR (PyDateTime_Time *o)

Renvoie l'heure, sous forme d'entier allant de 0 à 23.
@end deffn

@geindex PyDateTime_TIME_GET_MINUTE (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_MINUTE}@anchor{4c32}
@deffn {C Fonction} int PyDateTime_TIME_GET_MINUTE (PyDateTime_Time *o)

Renvoie la minute, sous forme d'entier allant de 0 à 59.
@end deffn

@geindex PyDateTime_TIME_GET_SECOND (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_SECOND}@anchor{4c33}
@deffn {C Fonction} int PyDateTime_TIME_GET_SECOND (PyDateTime_Time *o)

Renvoie la seconde, sous forme d'entier allant de 0 à 59.
@end deffn

@geindex PyDateTime_TIME_GET_MICROSECOND (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_MICROSECOND}@anchor{4c34}
@deffn {C Fonction} int PyDateTime_TIME_GET_MICROSECOND (PyDateTime_Time *o)

Renvoie la microseconde, sous forme d'entier allant de 0 à 999999.
@end deffn

@geindex PyDateTime_TIME_GET_FOLD (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_FOLD}@anchor{4c35}
@deffn {C Fonction} int PyDateTime_TIME_GET_FOLD (PyDateTime_Time *o)

Return the fold, as an int from 0 through 1.


Ajouté dans la version 3.6.

@end deffn

@geindex PyDateTime_TIME_GET_TZINFO (C function)
@anchor{c-api/datetime c PyDateTime_TIME_GET_TZINFO}@anchor{882}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDateTime_TIME_GET_TZINFO (PyDateTime_Time *o)

Return the tzinfo (which may be @code{None}).


Ajouté dans la version 3.10.

@end deffn

Macros to extract fields from time delta objects.  The argument must be an
instance of @ref{4c13,,PyDateTime_Delta}, including subclasses. The argument must
not be @code{NULL}, and the type is not checked:

@geindex PyDateTime_DELTA_GET_DAYS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_DAYS}@anchor{4c36}
@deffn {C Fonction} int PyDateTime_DELTA_GET_DAYS (PyDateTime_Delta *o)

Renvoie le nombre de jours, sous forme d'entier allant de @code{-999999999} à @code{999999999}.


Ajouté dans la version 3.3.

@end deffn

@geindex PyDateTime_DELTA_GET_SECONDS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_SECONDS}@anchor{4c37}
@deffn {C Fonction} int PyDateTime_DELTA_GET_SECONDS (PyDateTime_Delta *o)

Renvoie le nombre de secondes sous forme d'entier allant de 0 à 86399.


Ajouté dans la version 3.3.

@end deffn

@geindex PyDateTime_DELTA_GET_MICROSECONDS (C function)
@anchor{c-api/datetime c PyDateTime_DELTA_GET_MICROSECONDS}@anchor{4c38}
@deffn {C Fonction} int PyDateTime_DELTA_GET_MICROSECONDS (PyDateTime_Delta *o)

Renvoie le nombre de microsecondes, sous forme d'entier allant de 0 à 999999.


Ajouté dans la version 3.3.

@end deffn

Macros de confort pour les modules implémentant l'API DB :

@geindex PyDateTime_FromTimestamp (C function)
@anchor{c-api/datetime c PyDateTime_FromTimestamp}@anchor{4c39}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDateTime_FromTimestamp (PyObject *args)
`Valeur de retour : nouvelle référence.'
Create and return a new @ref{1c7,,datetime.datetime} object given an argument
tuple suitable for passing to @ref{4d7,,datetime.datetime.fromtimestamp()}.
@end deffn

@geindex PyDate_FromTimestamp (C function)
@anchor{c-api/datetime c PyDate_FromTimestamp}@anchor{199c}
@deffn {C Fonction} @ref{32f,,PyObject} *PyDate_FromTimestamp (PyObject *args)
`Valeur de retour : nouvelle référence.'
Create and return a new @ref{1c8,,datetime.date} object given an argument
tuple suitable for passing to @ref{1592,,datetime.date.fromtimestamp()}.
@end deffn

@node Objects for Type Hinting,,Objets DateTime<2>,Autres objets<2>
@anchor{c-api/typehints doc}@anchor{4c3a}@anchor{c-api/typehints objects-for-type-hinting}@anchor{4c3b}@anchor{c-api/typehints typehintobjects}@anchor{4c3c}
@subsubsection Objects for Type Hinting


Various built-in types for type hinting are provided.  Currently,
two types exist -- @ref{69d,,GenericAlias} and
@ref{7ac,,Union}.  Only @code{GenericAlias} is exposed to C.

@geindex Py_GenericAlias (C function)
@anchor{c-api/typehints c Py_GenericAlias}@anchor{49a1}
@deffn {C Fonction} @ref{32f,,PyObject} *Py_GenericAlias (PyObject *origin, PyObject *args)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Create a @ref{69d,,GenericAlias} object.
Equivalent to calling the Python class
@ref{7d5,,types.GenericAlias}.  The `origin' and `args' arguments set the
@code{GenericAlias}'s @code{__origin__} and @code{__args__} attributes respectively.
`origin' should be a @ref{a93,,PyTypeObject}*, and `args' can be a
@ref{4a09,,PyTupleObject}* or any @code{PyObject*}.  If `args' passed is
not a tuple, a 1-tuple is automatically constructed and @code{__args__} is set
to @code{(args,)}.
Minimal checking is done for the arguments, so the function will succeed even
if `origin' is not a type.
The @code{GenericAlias}'s @code{__parameters__} attribute is constructed lazily
from @code{__args__}.  On failure, an exception is raised and @code{NULL} is
returned.

Here's an example of how to make an extension type generic:

@example
...
static PyMethodDef my_obj_methods[] = @{
    // Other methods.
    ...
    @{"__class_getitem__", Py_GenericAlias, METH_O|METH_CLASS, "See PEP 585"@}
    ...
@}
@end example


@subsubheading Voir aussi


The data model method @ref{725,,__class_getitem__()}.



Ajouté dans la version 3.9.

@end deffn

@geindex Py_GenericAliasType (C var)
@anchor{c-api/typehints c Py_GenericAliasType}@anchor{49a2}
@deffn {C Variable} @ref{a93,,PyTypeObject} Py_GenericAliasType
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
The C type of the object returned by @ref{49a1,,Py_GenericAlias()}. Equivalent to
@ref{7d5,,types.GenericAlias} in Python.


Ajouté dans la version 3.9.

@end deffn

@node Initialization Finalization and Threads,Python Initialization Configuration,Couche des objets concrets,Manuel de référence de l'API Python/C
@anchor{c-api/init doc}@anchor{4c3d}@anchor{c-api/init initialization}@anchor{4c3e}@anchor{c-api/init initialization-finalization-and-threads}@anchor{4c3f}
@section Initialization, Finalization, and Threads


See @ref{39e,,Python Initialization Configuration} for details
on how to configure the interpreter prior to initialization.

@menu
* Before Python Initialization:: 
* Global configuration variables:: 
* Initializing and finalizing the interpreter:: 
* Process-wide parameters:: 
* Thread State and the Global Interpreter Lock:: 
* Sub-interpreter support:: 
* Asynchronous Notifications:: 
* Profiling and Tracing:: 
* Reference tracing:: 
* Support avancé du débogueur:: 
* Thread Local Storage Support:: 
* Primitives de synchronisation: Primitives de synchronisation<3>. 

@end menu

@node Before Python Initialization,Global configuration variables,,Initialization Finalization and Threads
@anchor{c-api/init before-python-initialization}@anchor{4c40}@anchor{c-api/init pre-init-safe}@anchor{bb3}
@subsection Before Python Initialization


In an application embedding  Python, the @ref{899,,Py_Initialize()} function must
be called before using any other Python/C API functions; with the exception of
a few functions and the @ref{4c41,,global configuration variables}.

The following functions can be safely called before Python is initialized:


@itemize *

@item 
Functions that initialize the interpreter:


@itemize *

@item 
@ref{899,,Py_Initialize()}

@item 
@ref{49a8,,Py_InitializeEx()}

@item 
@ref{3bc,,Py_InitializeFromConfig()}

@item 
@ref{9af,,Py_BytesMain()}

@item 
@ref{c13,,Py_Main()}

@item 
the runtime pre-initialization functions covered in @ref{39e,,Python Initialization Configuration}
@end itemize

@item 
Configuration functions:


@itemize *

@item 
@ref{1731,,PyImport_AppendInittab()}

@item 
@ref{1732,,PyImport_ExtendInittab()}

@item 
@code{PyInitFrozenExtensions()}

@item 
@ref{577,,PyMem_SetAllocator()}

@item 
@ref{c58,,PyMem_SetupDebugHooks()}

@item 
@ref{4c42,,PyObject_SetArenaAllocator()}

@item 
@ref{15c7,,Py_SetProgramName()}

@item 
@ref{15c6,,Py_SetPythonHome()}

@item 
@ref{3a6,,PySys_ResetWarnOptions()}

@item 
the configuration functions covered in @ref{39e,,Python Initialization Configuration}
@end itemize

@item 
Informative functions:


@itemize *

@item 
@ref{4857,,Py_IsInitialized()}

@item 
@ref{4c43,,PyMem_GetAllocator()}

@item 
@ref{4c44,,PyObject_GetArenaAllocator()}

@item 
@ref{13e8,,Py_GetBuildInfo()}

@item 
@ref{49a3,,Py_GetCompiler()}

@item 
@ref{49a4,,Py_GetCopyright()}

@item 
@ref{49a5,,Py_GetPlatform()}

@item 
@ref{49a6,,Py_GetVersion()}

@item 
@ref{4857,,Py_IsInitialized()}
@end itemize

@item 
Utilities:


@itemize *

@item 
@ref{bb5,,Py_DecodeLocale()}

@item 
the status reporting and utility functions covered in @ref{39e,,Python Initialization Configuration}
@end itemize

@item 
Memory allocators:


@itemize *

@item 
@ref{386,,PyMem_RawMalloc()}

@item 
@ref{388,,PyMem_RawRealloc()}

@item 
@ref{387,,PyMem_RawCalloc()}

@item 
@ref{389,,PyMem_RawFree()}
@end itemize

@item 
Synchronization:


@itemize *

@item 
@ref{320,,PyMutex_Lock()}

@item 
@ref{321,,PyMutex_Unlock()}
@end itemize
@end itemize

@cartouche
@quotation Note 
Despite their apparent similarity to some of the functions listed above,
the following functions `should not be called' before the interpreter has
been initialized: @ref{bb6,,Py_EncodeLocale()}, @ref{3aa,,Py_GetPath()},
@ref{3ac,,Py_GetPrefix()}, @ref{3a8,,Py_GetExecPrefix()},
@ref{3ae,,Py_GetProgramFullPath()}, @ref{3b1,,Py_GetPythonHome()},
@ref{3b0,,Py_GetProgramName()}, @ref{15ca,,PyEval_InitThreads()}, and
@ref{9b3,,Py_RunMain()}.
@end quotation
@end cartouche

@node Global configuration variables,Initializing and finalizing the interpreter,Before Python Initialization,Initialization Finalization and Threads
@anchor{c-api/init global-conf-vars}@anchor{4c41}@anchor{c-api/init global-configuration-variables}@anchor{4c45}
@subsection Global configuration variables


Python has variables for the global configuration to control different features
and options. By default, these flags are controlled by @ref{1cb5,,command line options}.

When a flag is set by an option, the value of the flag is the number of times
that the option was set. For example, @code{-b} sets @ref{3cb,,Py_BytesWarningFlag}
to 1 and @code{-bb} sets @ref{3cb,,Py_BytesWarningFlag} to 2.

@geindex Py_BytesWarningFlag (C var)
@anchor{c-api/init c Py_BytesWarningFlag}@anchor{3cb}
@deffn {C Variable} int Py_BytesWarningFlag

This API is kept for backward compatibility: setting
@ref{3cc,,PyConfig.bytes_warning} should be used instead, see @ref{39e,,Python Initialization Configuration}.

Issue a warning when comparing @ref{1bd,,bytes} or @ref{528,,bytearray} with
@ref{435,,str} or @ref{1bd,,bytes} with @ref{254,,int}.  Issue an error if greater
or equal to @code{2}.

Set by the @ref{5cd,,-b} option.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_DebugFlag (C var)
@anchor{c-api/init c Py_DebugFlag}@anchor{3bd}
@deffn {C Variable} int Py_DebugFlag

This API is kept for backward compatibility: setting
@ref{3be,,PyConfig.parser_debug} should be used instead, see @ref{39e,,Python Initialization Configuration}.

Turn on parser debugging output (for expert only, depending on compilation
options).

Set by the @ref{1cbd,,-d} option and the 
@geindex PYTHONDEBUG
@geindex variable d'environnement; PYTHONDEBUG
@ref{1cbe,,PYTHONDEBUG} environment
variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_DontWriteBytecodeFlag (C var)
@anchor{c-api/init c Py_DontWriteBytecodeFlag}@anchor{3d1}
@deffn {C Variable} int Py_DontWriteBytecodeFlag

This API is kept for backward compatibility: setting
@ref{3d2,,PyConfig.write_bytecode} should be used instead, see @ref{39e,,Python Initialization Configuration}.

If set to non-zero, Python won't try to write @code{.pyc} files on the
import of source modules.

Set by the @ref{1384,,-B} option and the 
@geindex PYTHONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@ref{1385,,PYTHONDONTWRITEBYTECODE}
environment variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_FrozenFlag (C var)
@anchor{c-api/init c Py_FrozenFlag}@anchor{3cd}
@deffn {C Variable} int Py_FrozenFlag

This API is kept for backward compatibility: setting
@ref{3ce,,PyConfig.pathconfig_warnings} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

Suppress error messages when calculating the module search path in
@ref{3aa,,Py_GetPath()}.

Private flag used by @code{_freeze_module} and @code{frozenmain} programs.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_HashRandomizationFlag (C var)
@anchor{c-api/init c Py_HashRandomizationFlag}@anchor{3d7}
@deffn {C Variable} int Py_HashRandomizationFlag

This API is kept for backward compatibility: setting
@ref{3d9,,PyConfig.hash_seed} and @ref{3d8,,PyConfig.use_hash_seed} should
be used instead, see @ref{39e,,Python Initialization Configuration}.

Set to @code{1} if the 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} environment variable is set to
a non-empty string.

If the flag is non-zero, read the 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} environment
variable to initialize the secret hash seed.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_IgnoreEnvironmentFlag (C var)
@anchor{c-api/init c Py_IgnoreEnvironmentFlag}@anchor{3cf}
@deffn {C Variable} int Py_IgnoreEnvironmentFlag

This API is kept for backward compatibility: setting
@ref{3d0,,PyConfig.use_environment} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

Ignore all @code{PYTHON*} environment variables, e.g.
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} and 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME}, that might be set.

Set by the @ref{94a,,-E} and @ref{94b,,-I} options.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_InspectFlag (C var)
@anchor{c-api/init c Py_InspectFlag}@anchor{3c5}
@deffn {C Variable} int Py_InspectFlag

This API is kept for backward compatibility: setting
@ref{3c6,,PyConfig.inspect} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

When a script is passed as first argument or the @ref{5ca,,-c} option is used,
enter interactive mode after executing the script or the command, even when
@ref{527,,sys.stdin} does not appear to be a terminal.

Set by the @ref{1491,,-i} option and the 
@geindex PYTHONINSPECT
@geindex variable d'environnement; PYTHONINSPECT
@ref{1490,,PYTHONINSPECT} environment
variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_InteractiveFlag (C var)
@anchor{c-api/init c Py_InteractiveFlag}@anchor{3c3}
@deffn {C Variable} int Py_InteractiveFlag

This API is kept for backward compatibility: setting
@ref{3c4,,PyConfig.interactive} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

Set by the @ref{1491,,-i} option.


Obsolète depuis la version 3.12.

@end deffn

@geindex Py_IsolatedFlag (C var)
@anchor{c-api/init c Py_IsolatedFlag}@anchor{3da}
@deffn {C Variable} int Py_IsolatedFlag

This API is kept for backward compatibility: setting
@ref{3db,,PyConfig.isolated} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

Run Python in isolated mode. In isolated mode @ref{3ab,,sys.path} contains
neither the script's directory nor the user's site-packages directory.

Set by the @ref{94b,,-I} option.


Ajouté dans la version 3.4.



Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_LegacyWindowsFSEncodingFlag (C var)
@anchor{c-api/init c Py_LegacyWindowsFSEncodingFlag}@anchor{3dc}
@deffn {C Variable} int Py_LegacyWindowsFSEncodingFlag

This API is kept for backward compatibility: setting
@ref{3dd,,PyPreConfig.legacy_windows_fs_encoding} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

If the flag is non-zero, use the @code{mbcs} encoding with @code{replace} error
handler, instead of the UTF-8 encoding with @code{surrogatepass} error handler,
for the @ref{525,,filesystem encoding and error handler}.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} environment
variable is set to a non-empty string.

Voir la 
@geindex Python Enhancement Proposals; PEP 529
PEP 529@footnote{https://peps.python.org/pep-0529/} pour plus d'informations.

@ref{1ce0,,Availability}: Windows.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_LegacyWindowsStdioFlag (C var)
@anchor{c-api/init c Py_LegacyWindowsStdioFlag}@anchor{3de}
@deffn {C Variable} int Py_LegacyWindowsStdioFlag

This API is kept for backward compatibility: setting
@ref{39b,,PyConfig.legacy_windows_stdio} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

If the flag is non-zero, use @ref{12ee,,io.FileIO} instead of
@code{io._WindowsConsoleIO} for @ref{d8,,sys} standard streams.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex variable d'environnement; PYTHONLEGACYWINDOWSSTDIO
@ref{c49,,PYTHONLEGACYWINDOWSSTDIO} environment
variable is set to a non-empty string.

See 
@geindex Python Enhancement Proposals; PEP 528
PEP 528@footnote{https://peps.python.org/pep-0528/} for more details.

@ref{1ce0,,Availability}: Windows.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_NoSiteFlag (C var)
@anchor{c-api/init c Py_NoSiteFlag}@anchor{3c9}
@deffn {C Variable} int Py_NoSiteFlag

This API is kept for backward compatibility: setting
@ref{3ca,,PyConfig.site_import} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

Désactive l’importation du module @ref{c6,,site} et les modifications locales de @ref{3ab,,sys.path} qu’il implique. Désactive aussi ces manipulations si @ref{c6,,site} est importé explicitement plus tard (appelez @ref{1cc2,,site.main()} si vous voulez les déclencher).

Set by the @ref{1186,,-S} option.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_NoUserSiteDirectory (C var)
@anchor{c-api/init c Py_NoUserSiteDirectory}@anchor{3d3}
@deffn {C Variable} int Py_NoUserSiteDirectory

This API is kept for backward compatibility: setting
@ref{3d4,,PyConfig.user_site_directory} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

N'ajoute pas le répertoire utilisateur @ref{1cc1,,site-packages} à @ref{3ab,,sys.path}.

Set by the @ref{1362,,-s} and @ref{94b,,-I} options, and the
@geindex PYTHONNOUSERSITE
@geindex variable d'environnement; PYTHONNOUSERSITE
@ref{1363,,PYTHONNOUSERSITE} environment variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_OptimizeFlag (C var)
@anchor{c-api/init c Py_OptimizeFlag}@anchor{3c7}
@deffn {C Variable} int Py_OptimizeFlag

This API is kept for backward compatibility: setting
@ref{3c8,,PyConfig.optimization_level} should be used instead, see
@ref{39e,,Python Initialization Configuration}.

Set by the @ref{da2,,-O} option and the 
@geindex PYTHONOPTIMIZE
@geindex variable d'environnement; PYTHONOPTIMIZE
@ref{1cbf,,PYTHONOPTIMIZE} environment
variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_QuietFlag (C var)
@anchor{c-api/init c Py_QuietFlag}@anchor{3c1}
@deffn {C Variable} int Py_QuietFlag

This API is kept for backward compatibility: setting
@ref{3c2,,PyConfig.quiet} should be used instead, see @ref{39e,,Python Initialization Configuration}.

N'affiche pas le copyright et la version, même en mode interactif.

Set by the @ref{1cc0,,-q} option.


Ajouté dans la version 3.2.



Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_UnbufferedStdioFlag (C var)
@anchor{c-api/init c Py_UnbufferedStdioFlag}@anchor{3d5}
@deffn {C Variable} int Py_UnbufferedStdioFlag

This API is kept for backward compatibility: setting
@ref{3d6,,PyConfig.buffered_stdio} should be used instead, see @ref{39e,,Python Initialization Configuration}.

Force the stdout and stderr streams to be unbuffered.

Set by the @ref{1932,,-u} option and the 
@geindex PYTHONUNBUFFERED
@geindex variable d'environnement; PYTHONUNBUFFERED
@ref{1933,,PYTHONUNBUFFERED}
environment variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@geindex Py_VerboseFlag (C var)
@anchor{c-api/init c Py_VerboseFlag}@anchor{3bf}
@deffn {C Variable} int Py_VerboseFlag

This API is kept for backward compatibility: setting
@ref{3c0,,PyConfig.verbose} should be used instead, see @ref{39e,,Python Initialization Configuration}.

Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded.  If greater or equal
to @code{2}, print a message for each file that is checked for when
searching for a module. Also provides information on module cleanup at exit.

Set by the @ref{13db,,-v} option and the 
@geindex PYTHONVERBOSE
@geindex variable d'environnement; PYTHONVERBOSE
@ref{1cc3,,PYTHONVERBOSE} environment
variable.


Deprecated since version 3.12, will be removed in version 3.14.

@end deffn

@node Initializing and finalizing the interpreter,Process-wide parameters,Global configuration variables,Initialization Finalization and Threads
@anchor{c-api/init initializing-and-finalizing-the-interpreter}@anchor{4c46}
@subsection Initializing and finalizing the interpreter


@geindex Py_Initialize (C function)
@anchor{c-api/init c Py_Initialize}@anchor{899}
@deffn {C Fonction} void Py_Initialize ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex PyEval_InitThreads()
@geindex modules (in module sys)
@geindex path (in module sys)
@geindex module;builtins
@geindex module;__main__
@geindex module;sys
@geindex module;search;path
@geindex Py_FinalizeEx (C function)

Initialize the Python interpreter.  In an application embedding  Python,
this should be called before using any other Python/C API functions; see
@ref{bb3,,Before Python Initialization} for the few exceptions.

This initializes the table of loaded modules (@code{sys.modules}), and creates
the fundamental modules @ref{12,,builtins}, @ref{1,,__main__} and @ref{d8,,sys}.
It also initializes the module search path (@code{sys.path}). It does not set
@code{sys.argv}; use the @ref{39e,,Python Initialization Configuration}
API for that. This is a no-op when called for a second time (without calling
@ref{d03,,Py_FinalizeEx()} first).  There is no return value; it is a fatal
error if the initialization fails.

Use @ref{3bc,,Py_InitializeFromConfig()} to customize the
@ref{39e,,Python Initialization Configuration}.

@cartouche
@quotation Note 
On Windows, changes the console mode from @code{O_TEXT} to @code{O_BINARY},
which will also affect non-Python uses of the console using the C Runtime.
@end quotation
@end cartouche
@end deffn

@geindex Py_InitializeEx (C function)
@anchor{c-api/init c Py_InitializeEx}@anchor{49a8}
@deffn {C Fonction} void Py_InitializeEx (int initsigs)
` Part of the @ref{53e,,Stable ABI}.'
This function works like @ref{899,,Py_Initialize()} if `initsigs' is @code{1}. If
`initsigs' is @code{0}, it skips initialization registration of signal handlers,
which may be useful when CPython is embedded as part of a larger application.

Use @ref{3bc,,Py_InitializeFromConfig()} to customize the
@ref{39e,,Python Initialization Configuration}.
@end deffn

@geindex Py_InitializeFromConfig (C function)
@anchor{c-api/init c Py_InitializeFromConfig}@anchor{3bc}
@deffn {C Fonction} @ref{99b,,PyStatus} Py_InitializeFromConfig (const PyConfig *config)

Initialize Python from `config' configuration, as described in
@ref{4c47,,Initialization with PyConfig}.

See the @ref{39e,,Python Initialization Configuration} section for details on pre-initializing the
interpreter, populating the runtime configuration structure, and querying
the returned status structure.
@end deffn

@geindex Py_IsInitialized (C function)
@anchor{c-api/init c Py_IsInitialized}@anchor{4857}
@deffn {C Fonction} int Py_IsInitialized ()
` Part of the @ref{53e,,Stable ABI}.'
Return true (nonzero) when the Python interpreter has been initialized, false
(zero) if not.  After @ref{d03,,Py_FinalizeEx()} is called, this returns false until
@ref{899,,Py_Initialize()} is called again.
@end deffn

@geindex Py_IsFinalizing (C function)
@anchor{c-api/init c Py_IsFinalizing}@anchor{350}
@deffn {C Fonction} int Py_IsFinalizing ()
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Return true (non-zero) if the main Python interpreter is
@ref{14d,,shutting down}. Return false (zero) otherwise.


Ajouté dans la version 3.13.

@end deffn

@geindex Py_FinalizeEx (C function)
@anchor{c-api/init c Py_FinalizeEx}@anchor{d03}
@deffn {C Fonction} int Py_FinalizeEx ()
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.6.'
Undo all initializations made by @ref{899,,Py_Initialize()} and subsequent use of
Python/C API functions, and destroy all sub-interpreters (see
@ref{1744,,Py_NewInterpreter()} below) that were created and not yet destroyed since
the last call to @ref{899,,Py_Initialize()}.  Ideally, this frees all memory
allocated by the Python interpreter.  This is a no-op when called for a second
time (without calling @ref{899,,Py_Initialize()} again first).

Since this is the reverse of @ref{899,,Py_Initialize()}, it should be called
in the same thread with the same interpreter active.  That means
the main thread and the main interpreter.
This should never be called while @ref{9b3,,Py_RunMain()} is running.

Normally the return value is @code{0}.
If there were errors during finalization (flushing buffered data),
@code{-1} is returned.

This function is provided for a number of reasons.  An embedding application
might want to restart Python without having to restart the application itself.
An application that has loaded the Python interpreter from a dynamically
loadable library (or DLL) might want to free all memory allocated by Python
before unloading the DLL. During a hunt for memory leaks in an application a
developer might want to free all memory allocated by Python before exiting from
the application.

`Bugs and caveats:' The destruction of modules and objects in modules is done
in random order; this may cause destructors (@ref{1ee3,,__del__()} methods) to fail
when they depend on other objects (even functions) or modules.  Dynamically
loaded extension modules loaded by Python are not unloaded.  Small amounts of
memory allocated by the Python interpreter may not be freed (if you find a leak,
please report it).  Memory tied up in circular references between objects is not
freed.  Some memory allocated by extension modules may not be freed.  Some
extensions may not work properly if their initialization routine is called more
than once; this can happen if an application calls @ref{899,,Py_Initialize()} and
@ref{d03,,Py_FinalizeEx()} more than once.

Raises an @ref{1848,,auditing event} @code{cpython._PySys_ClearAuditHooks} with no arguments.


Ajouté dans la version 3.6.

@end deffn

@geindex Py_Finalize (C function)
@anchor{c-api/init c Py_Finalize}@anchor{1330}
@deffn {C Fonction} void Py_Finalize ()
` Part of the @ref{53e,,Stable ABI}.'
This is a backwards-compatible version of @ref{d03,,Py_FinalizeEx()} that
disregards the return value.
@end deffn

@geindex Py_BytesMain (C function)
@anchor{c-api/init c Py_BytesMain}@anchor{9af}
@deffn {C Fonction} int Py_BytesMain (int argc, char **argv)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.8.'
Similar to @ref{c13,,Py_Main()} but `argv' is an array of bytes strings,
allowing the calling application to delegate the text decoding step to
the CPython runtime.


Ajouté dans la version 3.8.

@end deffn

@geindex Py_Main (C function)
@anchor{c-api/init c Py_Main}@anchor{c13}
@deffn {C Fonction} int Py_Main (int argc, wchar_t **argv)
` Part of the @ref{53e,,Stable ABI}.'
The main program for the standard interpreter, encapsulating a full
initialization/finalization cycle, as well as additional
behaviour to implement reading configurations settings from the environment
and command line, and then executing @code{__main__} in accordance with
@ref{ff0,,Ligne de commande}.

This is made available for programs which wish to support the full CPython
command line interface, rather than just embedding a Python runtime in a
larger application.

The `argc' and `argv' parameters are similar to those which are passed to a
C program's @code{main()} function, except that the `argv' entries are first
converted to @code{wchar_t} using @ref{bb5,,Py_DecodeLocale()}. It is also
important to note that the argument list entries may be modified to point to
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 @code{0} if the interpreter exits normally (i.e.,
without an exception), @code{1} if the interpreter exits due to an exception,
or @code{2} if the argument list does not represent a valid Python command
line.

Note that if an otherwise unhandled @ref{d2e,,SystemExit} is raised, this
function will not return @code{1}, but exit the process, as long as
@code{Py_InspectFlag} is not set. If @code{Py_InspectFlag} is set, execution will
drop into the interactive Python prompt, at which point a second otherwise
unhandled @ref{d2e,,SystemExit} will still exit the process, while any other
means of exiting will set the return value as described above.

In terms of the CPython runtime configuration APIs documented in the
@ref{39e,,runtime configuration} section (and without accounting
for error handling), @code{Py_Main} is approximately equivalent to:

@example
PyConfig config;
PyConfig_InitPythonConfig(&config);
PyConfig_SetArgv(&config, argc, argv);
Py_InitializeFromConfig(&config);
PyConfig_Clear(&config);

Py_RunMain();
@end example

In normal usage, an embedding application will call this function
`instead' of calling @ref{899,,Py_Initialize()}, @ref{49a8,,Py_InitializeEx()} or
@ref{3bc,,Py_InitializeFromConfig()} directly, and all settings will be applied
as described elsewhere in this documentation. If this function is instead
called `after' a preceding runtime initialization API call, then exactly
which environmental and command line configuration settings will be updated
is version dependent (as it depends on which settings correctly support
being modified after they have already been set once when the runtime was
first initialized).
@end deffn

@geindex Py_RunMain (C function)
@anchor{c-api/init c Py_RunMain}@anchor{9b3}
@deffn {C Fonction} int Py_RunMain (void)

Executes the main module in a fully configured CPython runtime.

Executes the command (@ref{4c48,,PyConfig.run_command}), the script
(@ref{4c49,,PyConfig.run_filename}) or the module
(@ref{4c4a,,PyConfig.run_module}) specified on the command line or in the
configuration. If none of these values are set, runs the interactive Python
prompt (REPL) using the @code{__main__} module's global namespace.

If @ref{3c6,,PyConfig.inspect} is not set (the default), the return value
will be @code{0} if the interpreter exits normally (that is, without raising
an exception), or @code{1} if the interpreter exits due to an exception. If an
otherwise unhandled @ref{d2e,,SystemExit} is raised, the function will immediately
exit the process instead of returning @code{1}.

If @ref{3c6,,PyConfig.inspect} is set (such as when the @ref{1491,,-i} option
is used), rather than returning when the interpreter exits, execution will
instead resume in an interactive Python prompt (REPL) using the @code{__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 @code{0}
if the session terminates without raising an unhandled exception, exiting
immediately for an unhandled @ref{d2e,,SystemExit}, and returning @code{1} for
any other unhandled exception.

This function always finalizes the Python interpreter regardless of whether
it returns a value or immediately exits the process due to an unhandled
@ref{d2e,,SystemExit} exception.

See @ref{4c4b,,Python Configuration} for an example of a
customized Python that always runs in isolated mode using
@ref{9b3,,Py_RunMain()}.
@end deffn

@geindex PyUnstable_AtExit (C function)
@anchor{c-api/init c PyUnstable_AtExit}@anchor{1511}
@deffn {C Fonction} int PyUnstable_AtExit (PyInterpreterState *interp, void (*func)(void*), void *data)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Register an @ref{c,,atexit} callback for the target interpreter `interp'.
This is similar to @ref{499e,,Py_AtExit()}, but takes an explicit interpreter and
data pointer for the callback.

The @ref{158,,GIL} must be held for `interp'.


Ajouté dans la version 3.13.

@end deffn

@node Process-wide parameters,Thread State and the Global Interpreter Lock,Initializing and finalizing the interpreter,Initialization Finalization and Threads
@anchor{c-api/init process-wide-parameters}@anchor{4c4c}
@subsection Process-wide parameters


@geindex Py_SetProgramName (C function)
@anchor{c-api/init c Py_SetProgramName}@anchor{15c7}
@deffn {C Fonction} void Py_SetProgramName (const wchar_t *name)
` Part of the @ref{53e,,Stable ABI}.'
@geindex Py_Initialize()
@geindex main()
@geindex Py_GetPath()

This API is kept for backward compatibility: setting
@ref{3bb,,PyConfig.program_name} should be used instead, see @ref{39e,,Python Initialization Configuration}.

This function should be called before @ref{899,,Py_Initialize()} is called for
the first time, if it is called at all.  It tells the interpreter the value
of the @code{argv[0]} argument to the @code{main()} function of the program
(converted to wide characters).
This is used by @ref{3aa,,Py_GetPath()} and some other functions below to find
the Python run-time libraries relative to the interpreter executable.  The
default value is @code{'python'}.  The argument should point to a
zero-terminated wide character string in static storage whose contents will not
change for the duration of the program's execution.  No code in the Python
interpreter will change the contents of this storage.

Use @ref{bb5,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_* string.


Obsolète depuis la version 3.11.

@end deffn

@geindex Py_GetProgramName (C function)
@anchor{c-api/init c Py_GetProgramName}@anchor{3b0}
@deffn {C Fonction} wchar_t *Py_GetProgramName ()
` Part of the @ref{53e,,Stable ABI}.'
Return the program name set with @ref{3bb,,PyConfig.program_name}, or the default.
The returned string points into static storage; the caller should not modify its
value.

This function should not be called before @ref{899,,Py_Initialize()}, otherwise
it returns @code{NULL}.


Modifié dans la version 3.10: It now returns @code{NULL} if called before @ref{899,,Py_Initialize()}.



Deprecated since version 3.13, will be removed in version 3.15: Get @ref{3af,,sys.executable} instead.

@end deffn

@geindex Py_GetPrefix (C function)
@anchor{c-api/init c Py_GetPrefix}@anchor{3ac}
@deffn {C Fonction} wchar_t *Py_GetPrefix ()
` Part of the @ref{53e,,Stable ABI}.'
Return the `prefix' for installed platform-independent files. This is derived
through a number of complicated rules from the program name set with
@ref{3bb,,PyConfig.program_name} and some environment variables; for example, if the
program name is @code{'/usr/local/bin/python'}, the prefix is @code{'/usr/local'}. The
returned string points into static storage; the caller should not modify its
value.  This corresponds to the @code{prefix} variable in the top-level
@code{Makefile} and the @ref{1cec,,--prefix} argument to the @code{configure}
script at build time.  The value is available to Python code as @code{sys.base_prefix}.
It is only useful on Unix.  See also the next function.

This function should not be called before @ref{899,,Py_Initialize()}, otherwise
it returns @code{NULL}.


Modifié dans la version 3.10: It now returns @code{NULL} if called before @ref{899,,Py_Initialize()}.



Deprecated since version 3.13, will be removed in version 3.15: Get @ref{3e6,,sys.base_prefix} instead, or @ref{3ad,,sys.prefix} if
@ref{4252,,virtual environments} need to be handled.

@end deffn

@geindex Py_GetExecPrefix (C function)
@anchor{c-api/init c Py_GetExecPrefix}@anchor{3a8}
@deffn {C Fonction} wchar_t *Py_GetExecPrefix ()
` Part of the @ref{53e,,Stable ABI}.'
Return the `exec-prefix' for installed platform-`dependent' files.  This is
derived through a number of complicated rules from the program name set with
@ref{3bb,,PyConfig.program_name} and some environment variables; for example, if the
program name is @code{'/usr/local/bin/python'}, the exec-prefix is
@code{'/usr/local'}.  The returned string points into static storage; the caller
should not modify its value.  This corresponds to the @code{exec_prefix}
variable in the top-level @code{Makefile} and the @code{--exec-prefix}
argument to the @code{configure} script at build  time.  The value is
available to Python code as @code{sys.base_exec_prefix}.  It is only useful on
Unix.

Background: The exec-prefix differs from the prefix when platform dependent
files (such as executables and shared libraries) are installed in a different
directory tree.  In a typical installation, platform dependent files may be
installed in the @code{/usr/local/plat} subtree while platform independent may
be installed in @code{/usr/local}.

Generally speaking, a platform is a combination of hardware and software
families, e.g.  Sparc machines running the Solaris 2.x operating system are
considered the same platform, but Intel machines running Solaris 2.x are another
platform, and Intel machines running Linux are yet another platform.  Different
major revisions of the same operating system generally also form different
platforms.  Non-Unix operating systems are a different story; the installation
strategies on those systems are so different that the prefix and exec-prefix are
meaningless, and set to the empty string. Note that compiled Python bytecode
files are platform independent (but not independent from the Python version by
which they were compiled!).

System administrators will know how to configure the @code{mount} or
@code{automount} programs to share @code{/usr/local} between platforms
while having @code{/usr/local/plat} be a different filesystem for each
platform.

This function should not be called before @ref{899,,Py_Initialize()}, otherwise
it returns @code{NULL}.


Modifié dans la version 3.10: It now returns @code{NULL} if called before @ref{899,,Py_Initialize()}.



Deprecated since version 3.13, will be removed in version 3.15: Get @ref{3e5,,sys.base_exec_prefix} instead, or @ref{3a9,,sys.exec_prefix} if
@ref{4252,,virtual environments} need to be handled.

@end deffn

@geindex Py_GetProgramFullPath (C function)
@anchor{c-api/init c Py_GetProgramFullPath}@anchor{3ae}
@deffn {C Fonction} wchar_t *Py_GetProgramFullPath ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex executable (in module sys)

Return the full program name of the Python executable; this is  computed as a
side-effect of deriving the default module search path  from the program name
(set by @ref{3bb,,PyConfig.program_name}). The returned string points into
static storage; the caller should not modify its value.  The value is available
to Python code as @code{sys.executable}.

This function should not be called before @ref{899,,Py_Initialize()}, otherwise
it returns @code{NULL}.


Modifié dans la version 3.10: It now returns @code{NULL} if called before @ref{899,,Py_Initialize()}.



Deprecated since version 3.13, will be removed in version 3.15: Get @ref{3af,,sys.executable} instead.

@end deffn

@geindex Py_GetPath (C function)
@anchor{c-api/init c Py_GetPath}@anchor{3aa}
@deffn {C Fonction} wchar_t *Py_GetPath ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex module;search;path
@geindex path (in module sys)

Return the default module search path; this is computed from the program name
(set by @ref{3bb,,PyConfig.program_name}) and some environment variables.
The returned string consists of a series of directory names separated by a
platform dependent delimiter character.  The delimiter character is @code{':'}
on Unix and macOS, @code{';'} on Windows.  The returned string points into
static storage; the caller should not modify its value.  The list
@ref{3ab,,sys.path} is initialized with this value on interpreter startup; it
can be (and usually is) modified later to change the search path for loading
modules.

This function should not be called before @ref{899,,Py_Initialize()}, otherwise
it returns @code{NULL}.

@c XXX should give the exact rules


Modifié dans la version 3.10: It now returns @code{NULL} if called before @ref{899,,Py_Initialize()}.



Deprecated since version 3.13, will be removed in version 3.15: Get @ref{3ab,,sys.path} instead.

@end deffn

@geindex Py_GetVersion (C function)
@anchor{c-api/init c Py_GetVersion}@anchor{49a6}
@deffn {C Fonction} const char *Py_GetVersion ()
` Part of the @ref{53e,,Stable ABI}.'
Return the version of this Python interpreter.  This is a string that looks
something like

@example
"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
@end example

@geindex version (in module sys)

The first word (up to the first space character) is the current Python version;
the first characters are the major and minor version separated by a
period.  The returned string points into static storage; the caller should not
modify its value.  The value is available to Python code as @ref{177,,sys.version}.

See also the @ref{740,,Py_Version} constant.
@end deffn

@geindex Py_GetPlatform (C function)
@anchor{c-api/init c Py_GetPlatform}@anchor{49a5}
@deffn {C Fonction} const char *Py_GetPlatform ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex platform (in module sys)

Return the platform identifier for the current platform.  On Unix, this is
formed from the "official" name of the operating system, converted to lower
case, followed by the major revision number; e.g., for Solaris 2.x, which is
also known as SunOS 5.x, the value is @code{'sunos5'}.  On macOS, it is
@code{'darwin'}.  On Windows, it is @code{'win'}.  The returned string points into
static storage; the caller should not modify its value.  The value is available
to Python code as @code{sys.platform}.
@end deffn

@geindex Py_GetCopyright (C function)
@anchor{c-api/init c Py_GetCopyright}@anchor{49a4}
@deffn {C Fonction} const char *Py_GetCopyright ()
` Part of the @ref{53e,,Stable ABI}.'
Return the official copyright string for the current Python version, for example

@code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}

@geindex copyright (in module sys)

The returned string points into static storage; the caller should not modify its
value.  The value is available to Python code as @code{sys.copyright}.
@end deffn

@geindex Py_GetCompiler (C function)
@anchor{c-api/init c Py_GetCompiler}@anchor{49a3}
@deffn {C Fonction} const char *Py_GetCompiler ()
` Part of the @ref{53e,,Stable ABI}.'
Return an indication of the compiler used to build the current Python version,
in square brackets, for example:

@example
"[GCC 2.7.2.2]"
@end example

@geindex version (in module sys)

The returned string points into static storage; the caller should not modify its
value.  The value is available to Python code as part of the variable
@code{sys.version}.
@end deffn

@geindex Py_GetBuildInfo (C function)
@anchor{c-api/init c Py_GetBuildInfo}@anchor{13e8}
@deffn {C Fonction} const char *Py_GetBuildInfo ()
` Part of the @ref{53e,,Stable ABI}.'
Return information about the sequence number and build date and time  of the
current Python interpreter instance, for example

@example
"#67, Aug  1 1997, 22:34:28"
@end example

@geindex version (in module sys)

The returned string points into static storage; the caller should not modify its
value.  The value is available to Python code as part of the variable
@code{sys.version}.
@end deffn

@geindex PySys_SetArgvEx (C function)
@anchor{c-api/init c PySys_SetArgvEx}@anchor{15c8}
@deffn {C Fonction} void PySys_SetArgvEx (int argc, wchar_t **argv, int updatepath)
` Part of the @ref{53e,,Stable ABI}.'
@geindex main()
@geindex Py_FatalError()
@geindex argv (in module sys)

This API is kept for backward compatibility: setting
@ref{3ba,,PyConfig.argv}, @ref{18b6,,PyConfig.parse_argv} and
@ref{75d,,PyConfig.safe_path} should be used instead, see @ref{39e,,Python Initialization Configuration}.

Set @ref{1243,,sys.argv} based on `argc' and `argv'.  These parameters are
similar to those passed to the program's @code{main()} function with the
difference that the first entry should refer to the script file to be
executed rather than the executable hosting the Python interpreter.  If there
isn't a script that will be run, the first entry in `argv' can be an empty
string.  If this function fails to initialize @ref{1243,,sys.argv}, a fatal
condition is signalled using @ref{970,,Py_FatalError()}.

If `updatepath' is zero, this is all the function does.  If `updatepath'
is non-zero, the function also modifies @ref{3ab,,sys.path} according to the
following algorithm:


@itemize -

@item 
If the name of an existing script is passed in @code{argv[0]}, the absolute
path of the directory where the script is located is prepended to
@ref{3ab,,sys.path}.

@item 
Otherwise (that is, if `argc' is @code{0} or @code{argv[0]} doesn't point
to an existing file name), an empty string is prepended to
@ref{3ab,,sys.path}, which is the same as prepending the current working
directory (@code{"."}).
@end itemize

Use @ref{bb5,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_* string.

See also @ref{880,,PyConfig.orig_argv} and @ref{3ba,,PyConfig.argv}
members of the @ref{39e,,Python Initialization Configuration}.

@cartouche
@quotation Note 
It is recommended that applications embedding the Python interpreter
for purposes other than executing a single script pass @code{0} as `updatepath',
and update @ref{3ab,,sys.path} themselves if desired.
See 
@geindex Common Vulnerabilities and Exposures; CVE 2008-5983
CVE 2008-5983@footnote{https://www.cve.org/CVERecord?id=CVE-2008-5983}.

On versions before 3.1.3, you can achieve the same effect by manually
popping the first @ref{3ab,,sys.path} element after having called
@ref{15c9,,PySys_SetArgv()}, for example using:

@example
PyRun_SimpleString("import sys; sys.path.pop(0)\n");
@end example
@end quotation
@end cartouche


Ajouté dans la version 3.1.3.


@c XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
@c check w/ Guido.


Obsolète depuis la version 3.11.

@end deffn

@geindex PySys_SetArgv (C function)
@anchor{c-api/init c PySys_SetArgv}@anchor{15c9}
@deffn {C Fonction} void PySys_SetArgv (int argc, wchar_t **argv)
` Part of the @ref{53e,,Stable ABI}.'
This API is kept for backward compatibility: setting
@ref{3ba,,PyConfig.argv} and @ref{18b6,,PyConfig.parse_argv} should be used
instead, see @ref{39e,,Python Initialization Configuration}.

This function works like @ref{15c8,,PySys_SetArgvEx()} with `updatepath' set
to @code{1} unless the @code{python} interpreter was started with the
@ref{94b,,-I}.

Use @ref{bb5,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_* string.

See also @ref{880,,PyConfig.orig_argv} and @ref{3ba,,PyConfig.argv}
members of the @ref{39e,,Python Initialization Configuration}.


Modifié dans la version 3.4: The `updatepath' value depends on @ref{94b,,-I}.



Obsolète depuis la version 3.11.

@end deffn

@geindex Py_SetPythonHome (C function)
@anchor{c-api/init c Py_SetPythonHome}@anchor{15c6}
@deffn {C Fonction} void Py_SetPythonHome (const wchar_t *home)
` Part of the @ref{53e,,Stable ABI}.'
This API is kept for backward compatibility: setting
@ref{3b2,,PyConfig.home} should be used instead, see @ref{39e,,Python Initialization Configuration}.

Set the default "home" directory, that is, the location of the standard
Python libraries.  See 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} for the meaning of the
argument string.

The argument should point to a zero-terminated character string in static
storage whose contents will not change for the duration of the program's
execution.  No code in the Python interpreter will change the contents of
this storage.

Use @ref{bb5,,Py_DecodeLocale()} to decode a bytes string to get a
wchar_* string.


Obsolète depuis la version 3.11.

@end deffn

@geindex Py_GetPythonHome (C function)
@anchor{c-api/init c Py_GetPythonHome}@anchor{3b1}
@deffn {C Fonction} wchar_t *Py_GetPythonHome ()
` Part of the @ref{53e,,Stable ABI}.'
Return the default "home", that is, the value set by
@ref{3b2,,PyConfig.home}, or the value of the 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME}
environment variable if it is set.

This function should not be called before @ref{899,,Py_Initialize()}, otherwise
it returns @code{NULL}.


Modifié dans la version 3.10: It now returns @code{NULL} if called before @ref{899,,Py_Initialize()}.



Deprecated since version 3.13, will be removed in version 3.15: Get @ref{3b2,,PyConfig.home} or 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment
variable instead.

@end deffn

@node Thread State and the Global Interpreter Lock,Sub-interpreter support,Process-wide parameters,Initialization Finalization and Threads
@anchor{c-api/init thread-state-and-the-global-interpreter-lock}@anchor{4c4d}@anchor{c-api/init threads}@anchor{4c4e}
@subsection Thread State and the Global Interpreter Lock


@geindex global interpreter lock
@geindex interpreter lock
@geindex lock@comma{} interpreter

The Python interpreter is not fully thread-safe.  In order to support
multi-threaded Python programs, there's a global lock, called the @ref{147,,global interpreter lock} or @ref{158,,GIL}, that must be held by the current thread before
it can safely access Python objects. Without the lock, even the simplest
operations could cause problems in a multi-threaded program: for example, when
two threads simultaneously increment the reference count of the same object, the
reference count could end up being incremented only once instead of twice.

@geindex setswitchinterval (in module sys)

Therefore, the rule exists that only the thread that has acquired the
@ref{158,,GIL} may operate on Python objects or call Python/C API functions.
In order to emulate concurrency of execution, the interpreter regularly
tries to switch threads (see @ref{937,,sys.setswitchinterval()}).  The lock is also
released around potentially blocking I/O operations like reading or writing
a file, so that other Python threads can run in the meantime.

@geindex PyThreadState (C type)

The Python interpreter keeps some thread-specific bookkeeping information
inside a data structure called @ref{777,,PyThreadState}.  There's also one
global variable pointing to the current @ref{777,,PyThreadState}: it can
be retrieved using @ref{368,,PyThreadState_Get()}.

@menu
* Releasing the GIL from extension code:: 
* Non-Python created threads:: 
* Cautions about fork(): Cautions about fork. 
* High-level API:: 
* Low-level API:: 

@end menu

@node Releasing the GIL from extension code,Non-Python created threads,,Thread State and the Global Interpreter Lock
@anchor{c-api/init releasing-the-gil-from-extension-code}@anchor{4c4f}
@subsubsection Releasing the GIL from extension code


Most extension code manipulating the @ref{158,,GIL} has the following simple
structure:

@example
Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.
@end example

This is so common that a pair of macros exists to simplify it:

@example
Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS
@end example

@geindex Py_BEGIN_ALLOW_THREADS (C macro)
@geindex Py_END_ALLOW_THREADS (C macro)

The @ref{47dd,,Py_BEGIN_ALLOW_THREADS} macro opens a new block and declares a
hidden local variable; the @ref{a7c,,Py_END_ALLOW_THREADS} macro closes the
block.

The block above expands to the following code:

@example
PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);
@end example

@geindex PyEval_RestoreThread (C function)
@geindex PyEval_SaveThread (C function)

Here is how these functions work: the global interpreter lock is used to protect the pointer to the
current thread state.  When releasing the lock and saving the thread state,
the current thread state pointer must be retrieved before the lock is released
(since another thread could immediately acquire the lock and store its own thread
state in the global variable). Conversely, when acquiring the lock and restoring
the thread state, the lock must be acquired before storing the thread state
pointer.

@cartouche
@quotation Note 
Calling system I/O functions is the most common use case for releasing
the GIL, but it can also be useful before calling long-running computations
which don't need access to Python objects, such as compression or
cryptographic functions operating over memory buffers.  For example, the
standard @ref{132,,zlib} and @ref{67,,hashlib} modules release the GIL when
compressing or hashing data.
@end quotation
@end cartouche

@node Non-Python created threads,Cautions about fork,Releasing the GIL from extension code,Thread State and the Global Interpreter Lock
@anchor{c-api/init gilstate}@anchor{4c50}@anchor{c-api/init non-python-created-threads}@anchor{4c51}
@subsubsection Non-Python created threads


When threads are created using the dedicated Python APIs (such as the
@ref{ec,,threading} module), a thread state is automatically associated to them
and the code showed above is therefore correct.  However, when threads are
created from C (for example by a third-party library with its own thread
management), they don't hold the GIL, nor is there a thread state structure
for them.

If you need to call Python code from these threads (often this will be part
of a callback API provided by the aforementioned third-party library),
you must first register these threads with the interpreter by
creating a thread state data structure, then acquiring the GIL, and finally
storing their thread state pointer, before you can start using the Python/C
API.  When you are done, you should reset the thread state pointer, release
the GIL, and finally free the thread state data structure.

The @ref{3a2,,PyGILState_Ensure()} and @ref{3a3,,PyGILState_Release()} functions do
all of the above automatically.  The typical idiom for calling into Python
from a C thread is:

@example
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);
@end example

Note that the @code{PyGILState_*} functions assume there is only one global
interpreter (created automatically by @ref{899,,Py_Initialize()}).  Python
supports the creation of additional interpreters (using
@ref{1744,,Py_NewInterpreter()}), but mixing multiple interpreters and the
@code{PyGILState_*} API is unsupported.

@node Cautions about fork,High-level API,Non-Python created threads,Thread State and the Global Interpreter Lock
@anchor{c-api/init cautions-about-fork}@anchor{4c52}@anchor{c-api/init fork-and-threads}@anchor{4a05}
@subsubsection Cautions about fork()


Another important thing to note about threads is their behaviour in the face
of the C @code{fork()} call. On most systems with @code{fork()}, after a
process forks only the thread that issued the fork will exist.  This has a
concrete impact both on how locks must be handled and on all stored state
in CPython's runtime.

The fact that only the "current" thread remains
means any locks held by other threads will never be released. Python solves
this for @ref{195,,os.fork()} by acquiring the locks it uses internally before
the fork, and releasing them afterwards. In addition, it resets any
@ref{3069,,Verrous} in the child. When extending or embedding Python, there
is no way to inform Python of additional (non-Python) locks that need to be
acquired before or reset after a fork. OS facilities such as
@code{pthread_atfork()} would need to be used to accomplish the same thing.
Additionally, when extending or embedding Python, calling @code{fork()}
directly rather than through @ref{195,,os.fork()} (and returning to or calling
into Python) may result in a deadlock by one of Python's internal locks
being held by a thread that is defunct after the fork.
@ref{3f1,,PyOS_AfterFork_Child()} tries to reset the necessary locks, but is not
always able to.

The fact that all other threads go away also means that CPython's
runtime state there must be cleaned up properly, which @ref{195,,os.fork()}
does.  This means finalizing all other @ref{777,,PyThreadState} objects
belonging to the current interpreter and all other
@ref{8aa,,PyInterpreterState} objects.  Due to this and the special
nature of the @ref{573,,"main" interpreter},
@code{fork()} should only be called in that interpreter's "main"
thread, where the CPython global runtime was originally initialized.
The only exception is if @code{exec()} will be called immediately
after.

@node High-level API,Low-level API,Cautions about fork,Thread State and the Global Interpreter Lock
@anchor{c-api/init high-level-api}@anchor{4c53}
@subsubsection High-level API


These are the most commonly used types and functions when writing C extension
code, or when embedding the Python interpreter:

@geindex PyInterpreterState (C type)
@anchor{c-api/init c PyInterpreterState}@anchor{8aa}
@deffn {C Type} type PyInterpreterState
` Part of the @ref{53e,,Limited API} (as an opaque struct).'
This data structure represents the state shared by a number of cooperating
threads.  Threads belonging to the same interpreter share their module
administration and a few other internal items. There are no public members in
this structure.

Threads belonging to different interpreters initially share nothing, except
process state like available memory, open file descriptors and such.  The global
interpreter lock is also shared by all threads, regardless of to which
interpreter they belong.
@end deffn

@geindex PyThreadState (C type)
@anchor{c-api/init c PyThreadState}@anchor{777}
@deffn {C Type} type PyThreadState
` Part of the @ref{53e,,Limited API} (as an opaque struct).'
This data structure represents the state of a single thread.  The only public
data member is:

@geindex PyThreadState.interp (C member)
@anchor{c-api/init c PyThreadState interp}@anchor{4c54}
@deffn {C Membre} @ref{8aa,,PyInterpreterState} *interp

This thread's interpreter state.
@end deffn
@end deffn

@geindex PyEval_InitThreads (C function)
@anchor{c-api/init c PyEval_InitThreads}@anchor{15ca}
@deffn {C Fonction} void PyEval_InitThreads ()
` Part of the @ref{53e,,Stable ABI}.'
@geindex PyEval_AcquireThread()
@geindex PyEval_ReleaseThread()
@geindex PyEval_SaveThread()
@geindex PyEval_RestoreThread()

Deprecated function which does nothing.

In Python 3.6 and older, this function created the GIL if it didn't exist.


Modifié dans la version 3.9: The function now does nothing.



Modifié dans la version 3.7: This function is now called by @ref{899,,Py_Initialize()}, so you don't
have to call it yourself anymore.



Modifié dans la version 3.2: This function cannot be called before @ref{899,,Py_Initialize()} anymore.



Obsolète depuis la version 3.9.


@geindex module;_thread
@end deffn

@geindex PyEval_SaveThread (C function)
@anchor{c-api/init c PyEval_SaveThread}@anchor{39f}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyEval_SaveThread ()
` Part of the @ref{53e,,Stable ABI}.'
Release the global interpreter lock (if it has been created) and reset the
thread state to @code{NULL}, returning the previous thread state (which is not
@code{NULL}).  If the lock has been created, the current thread must have
acquired it.
@end deffn

@geindex PyEval_RestoreThread (C function)
@anchor{c-api/init c PyEval_RestoreThread}@anchor{3a0}
@deffn {C Fonction} void PyEval_RestoreThread (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
Acquire the global interpreter lock (if it has been created) and set the
thread state to `tstate', which must not be @code{NULL}.  If the lock has been
created, the current thread must not have acquired it, otherwise deadlock
ensues.

@cartouche
@quotation Note 
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use @ref{350,,Py_IsFinalizing()} or @ref{a7d,,sys.is_finalizing()} to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
@end quotation
@end cartouche
@end deffn

@geindex PyThreadState_Get (C function)
@anchor{c-api/init c PyThreadState_Get}@anchor{368}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyThreadState_Get ()
` Part of the @ref{53e,,Stable ABI}.'
Return the current thread state.  The global interpreter lock must be held.
When the current thread state is @code{NULL}, this issues a fatal error (so that
the caller needn't check for @code{NULL}).

See also @ref{367,,PyThreadState_GetUnchecked()}.
@end deffn

@geindex PyThreadState_GetUnchecked (C function)
@anchor{c-api/init c PyThreadState_GetUnchecked}@anchor{367}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyThreadState_GetUnchecked ()

Similar to @ref{368,,PyThreadState_Get()}, but don't kill the process with a
fatal error if it is NULL. The caller is responsible to check if the result
is NULL.


Ajouté dans la version 3.13: In Python 3.5 to 3.12, the function was private and known as
@code{_PyThreadState_UncheckedGet()}.

@end deffn

@geindex PyThreadState_Swap (C function)
@anchor{c-api/init c PyThreadState_Swap}@anchor{4958}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyThreadState_Swap (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
Swap the current thread state with the thread state given by the argument
`tstate', which may be @code{NULL}.  The global interpreter lock must be held
and is not released.
@end deffn

The following functions use thread-local storage, and are not compatible
with sub-interpreters:

@geindex PyGILState_Ensure (C function)
@anchor{c-api/init c PyGILState_Ensure}@anchor{3a2}
@deffn {C Fonction} PyGILState_STATE PyGILState_Ensure ()
` Part of the @ref{53e,,Stable ABI}.'
Ensure that the current thread is ready to call the Python C API regardless
of the current state of Python, or of the global interpreter lock. This may
be called as many times as desired by a thread as long as each call is
matched with a call to @ref{3a3,,PyGILState_Release()}. In general, other
thread-related APIs may be used between @ref{3a2,,PyGILState_Ensure()} and
@ref{3a3,,PyGILState_Release()} calls as long as the thread state is restored to
its previous state before the Release().  For example, normal usage of the
@ref{47dd,,Py_BEGIN_ALLOW_THREADS} and @ref{a7c,,Py_END_ALLOW_THREADS} macros is
acceptable.

The return value is an opaque "handle" to the thread state when
@ref{3a2,,PyGILState_Ensure()} was called, and must be passed to
@ref{3a3,,PyGILState_Release()} to ensure Python is left in the same state. Even
though recursive calls are allowed, these handles `cannot' be shared - each
unique call to @ref{3a2,,PyGILState_Ensure()} must save the handle for its call
to @ref{3a3,,PyGILState_Release()}.

When the function returns, the current thread will hold the GIL and be able
to call arbitrary Python code.  Failure is a fatal error.

@cartouche
@quotation Note 
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use @ref{350,,Py_IsFinalizing()} or @ref{a7d,,sys.is_finalizing()} to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
@end quotation
@end cartouche
@end deffn

@geindex PyGILState_Release (C function)
@anchor{c-api/init c PyGILState_Release}@anchor{3a3}
@deffn {C Fonction} void PyGILState_Release (PyGILState_STATE)
` Part of the @ref{53e,,Stable ABI}.'
Release any resources previously acquired.  After this call, Python's state will
be the same as it was prior to the corresponding @ref{3a2,,PyGILState_Ensure()} call
(but generally this state will be unknown to the caller, hence the use of the
GILState API).

Every call to @ref{3a2,,PyGILState_Ensure()} must be matched by a call to
@ref{3a3,,PyGILState_Release()} on the same thread.
@end deffn

@geindex PyGILState_GetThisThreadState (C function)
@anchor{c-api/init c PyGILState_GetThisThreadState}@anchor{48c9}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyGILState_GetThisThreadState ()
` Part of the @ref{53e,,Stable ABI}.'
Get the current thread state for this thread.  May return @code{NULL} if no
GILState API has been used on the current thread.  Note that the main thread
always has such a thread-state, even if no auto-thread-state call has been
made on the main thread.  This is mainly a helper/diagnostic function.
@end deffn

@geindex PyGILState_Check (C function)
@anchor{c-api/init c PyGILState_Check}@anchor{4c55}
@deffn {C Fonction} int PyGILState_Check ()

Return @code{1} if the current thread is holding the GIL and @code{0} otherwise.
This function can be called from any thread at any time.
Only if it has had its Python thread state initialized and currently is
holding the GIL will it return @code{1}.
This is mainly a helper/diagnostic function.  It can be useful
for example in callback contexts or memory allocation functions when
knowing that the GIL is locked can allow the caller to perform sensitive
actions or otherwise behave differently.


Ajouté dans la version 3.4.

@end deffn

The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.

@geindex Py_BEGIN_ALLOW_THREADS (C macro)
@anchor{c-api/init c Py_BEGIN_ALLOW_THREADS}@anchor{47dd}
@deffn {C Macro} Py_BEGIN_ALLOW_THREADS
` Part of the @ref{53e,,Stable ABI}.'
This macro expands to @code{@{ PyThreadState *_save; _save = PyEval_SaveThread();}.
Note that it contains an opening brace; it must be matched with a following
@ref{a7c,,Py_END_ALLOW_THREADS} macro.  See above for further discussion of this
macro.
@end deffn

@geindex Py_END_ALLOW_THREADS (C macro)
@anchor{c-api/init c Py_END_ALLOW_THREADS}@anchor{a7c}
@deffn {C Macro} Py_END_ALLOW_THREADS
` Part of the @ref{53e,,Stable ABI}.'
This macro expands to @code{PyEval_RestoreThread(_save); @}}. Note that it contains
a closing brace; it must be matched with an earlier
@ref{47dd,,Py_BEGIN_ALLOW_THREADS} macro.  See above for further discussion of
this macro.
@end deffn

@geindex Py_BLOCK_THREADS (C macro)
@anchor{c-api/init c Py_BLOCK_THREADS}@anchor{499f}
@deffn {C Macro} Py_BLOCK_THREADS
` Part of the @ref{53e,,Stable ABI}.'
This macro expands to @code{PyEval_RestoreThread(_save);}: it is equivalent to
@ref{a7c,,Py_END_ALLOW_THREADS} without the closing brace.
@end deffn

@geindex Py_UNBLOCK_THREADS (C macro)
@anchor{c-api/init c Py_UNBLOCK_THREADS}@anchor{49ab}
@deffn {C Macro} Py_UNBLOCK_THREADS
` Part of the @ref{53e,,Stable ABI}.'
This macro expands to @code{_save = PyEval_SaveThread();}: it is equivalent to
@ref{47dd,,Py_BEGIN_ALLOW_THREADS} without the opening brace and variable
declaration.
@end deffn

@node Low-level API,,High-level API,Thread State and the Global Interpreter Lock
@anchor{c-api/init low-level-api}@anchor{4c56}
@subsubsection Low-level API


All of the following functions must be called after @ref{899,,Py_Initialize()}.


Modifié dans la version 3.7: @ref{899,,Py_Initialize()} now initializes the @ref{158,,GIL}.


@geindex PyInterpreterState_New (C function)
@anchor{c-api/init c PyInterpreterState_New}@anchor{4110}
@deffn {C Fonction} @ref{8aa,,PyInterpreterState} *PyInterpreterState_New ()
` Part of the @ref{53e,,Stable ABI}.'
Create a new interpreter state object.  The global interpreter lock need not
be held, but may be held if it is necessary to serialize calls to this
function.

Raises an @ref{1848,,auditing event} @code{cpython.PyInterpreterState_New} with no arguments.
@end deffn

@geindex PyInterpreterState_Clear (C function)
@anchor{c-api/init c PyInterpreterState_Clear}@anchor{410f}
@deffn {C Fonction} void PyInterpreterState_Clear (PyInterpreterState *interp)
` Part of the @ref{53e,,Stable ABI}.'
Reset all information in an interpreter state object.  The global interpreter
lock must be held.

Raises an @ref{1848,,auditing event} @code{cpython.PyInterpreterState_Clear} with no arguments.
@end deffn

@geindex PyInterpreterState_Delete (C function)
@anchor{c-api/init c PyInterpreterState_Delete}@anchor{48d5}
@deffn {C Fonction} void PyInterpreterState_Delete (PyInterpreterState *interp)
` Part of the @ref{53e,,Stable ABI}.'
Destroy an interpreter state object.  The global interpreter lock need not be
held.  The interpreter state must have been reset with a previous call to
@ref{410f,,PyInterpreterState_Clear()}.
@end deffn

@geindex PyThreadState_New (C function)
@anchor{c-api/init c PyThreadState_New}@anchor{4957}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyThreadState_New (PyInterpreterState *interp)
` Part of the @ref{53e,,Stable ABI}.'
Create a new thread state object belonging to the given interpreter object.
The global interpreter lock need not be held, but may be held if it is
necessary to serialize calls to this function.
@end deffn

@geindex PyThreadState_Clear (C function)
@anchor{c-api/init c PyThreadState_Clear}@anchor{15aa}
@deffn {C Fonction} void PyThreadState_Clear (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
Reset all information in a thread state object.  The global interpreter lock
must be held.


Modifié dans la version 3.9: This function now calls the @code{PyThreadState.on_delete} callback.
Previously, that happened in @ref{192e,,PyThreadState_Delete()}.



Modifié dans la version 3.13: The @code{PyThreadState.on_delete} callback was removed.

@end deffn

@geindex PyThreadState_Delete (C function)
@anchor{c-api/init c PyThreadState_Delete}@anchor{192e}
@deffn {C Fonction} void PyThreadState_Delete (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
Destroy a thread state object.  The global interpreter lock need not be held.
The thread state must have been reset with a previous call to
@ref{15aa,,PyThreadState_Clear()}.
@end deffn

@geindex PyThreadState_DeleteCurrent (C function)
@anchor{c-api/init c PyThreadState_DeleteCurrent}@anchor{1961}
@deffn {C Fonction} void PyThreadState_DeleteCurrent (void)

Destroy the current thread state and release the global interpreter lock.
Like @ref{192e,,PyThreadState_Delete()}, the global interpreter lock must
be held. The thread state must have been reset with a previous call
to @ref{15aa,,PyThreadState_Clear()}.
@end deffn

@geindex PyThreadState_GetFrame (C function)
@anchor{c-api/init c PyThreadState_GetFrame}@anchor{778}
@deffn {C Fonction} @ref{773,,PyFrameObject} *PyThreadState_GetFrame (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Get the current frame of the Python thread state `tstate'.

Return a @ref{333,,strong reference}. Return @code{NULL} if no frame is currently
executing.

See also @ref{174a,,PyEval_GetFrame()}.

`tstate' must not be @code{NULL}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyThreadState_GetID (C function)
@anchor{c-api/init c PyThreadState_GetID}@anchor{95f}
@deffn {C Fonction} uint64_t PyThreadState_GetID (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Get the unique thread state identifier of the Python thread state `tstate'.

`tstate' must not be @code{NULL}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyThreadState_GetInterpreter (C function)
@anchor{c-api/init c PyThreadState_GetInterpreter}@anchor{95e}
@deffn {C Fonction} @ref{8aa,,PyInterpreterState} *PyThreadState_GetInterpreter (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Get the interpreter of the Python thread state `tstate'.

`tstate' must not be @code{NULL}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyThreadState_EnterTracing (C function)
@anchor{c-api/init c PyThreadState_EnterTracing}@anchor{73e}
@deffn {C Fonction} void PyThreadState_EnterTracing (PyThreadState *tstate)

Suspend tracing and profiling in the Python thread state `tstate'.

Resume them using the @ref{73f,,PyThreadState_LeaveTracing()} function.


Ajouté dans la version 3.11.

@end deffn

@geindex PyThreadState_LeaveTracing (C function)
@anchor{c-api/init c PyThreadState_LeaveTracing}@anchor{73f}
@deffn {C Fonction} void PyThreadState_LeaveTracing (PyThreadState *tstate)

Resume tracing and profiling in the Python thread state `tstate' suspended
by the @ref{73e,,PyThreadState_EnterTracing()} function.

See also @ref{14b4,,PyEval_SetTrace()} and @ref{14b3,,PyEval_SetProfile()}
functions.


Ajouté dans la version 3.11.

@end deffn

@geindex PyInterpreterState_Get (C function)
@anchor{c-api/init c PyInterpreterState_Get}@anchor{3a4}
@deffn {C Fonction} @ref{8aa,,PyInterpreterState} *PyInterpreterState_Get (void)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Get the current interpreter.

Issue a fatal error if there no current Python thread state or no current
interpreter. It cannot return NULL.

The caller must hold the GIL.


Ajouté dans la version 3.9.

@end deffn

@geindex PyInterpreterState_GetID (C function)
@anchor{c-api/init c PyInterpreterState_GetID}@anchor{bb4}
@deffn {C Fonction} int64_t PyInterpreterState_GetID (PyInterpreterState *interp)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return the interpreter's unique ID.  If there was any error in doing
so then @code{-1} is returned and an error is set.

The caller must hold the GIL.


Ajouté dans la version 3.7.

@end deffn

@geindex PyInterpreterState_GetDict (C function)
@anchor{c-api/init c PyInterpreterState_GetDict}@anchor{48d6}
@deffn {C Fonction} @ref{32f,,PyObject} *PyInterpreterState_GetDict (PyInterpreterState *interp)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.8.'
Return a dictionary in which interpreter-specific data may be stored.
If this function returns @code{NULL} then no exception has been raised and
the caller should assume no interpreter-specific dict is available.

This is not a replacement for @ref{96d,,PyModule_GetState()}, which
extensions should use to store interpreter-specific state information.


Ajouté dans la version 3.8.

@end deffn

@geindex _PyFrameEvalFunction (C type)
@anchor{c-api/init c _PyFrameEvalFunction}@anchor{760}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*_PyFrameEvalFunction)(@ref{777,,PyThreadState} *tstate, @ref{4be7,,_PyInterpreterFrame} *frame, int throwflag)

Type of a frame evaluation function.

The `throwflag' parameter is used by the @code{throw()} method of generators:
if non-zero, handle the current exception.


Modifié dans la version 3.9: The function now takes a `tstate' parameter.



Modifié dans la version 3.11: The `frame' parameter changed from @code{PyFrameObject*} to @code{_PyInterpreterFrame*}.

@end deffn

@geindex _PyInterpreterState_GetEvalFrameFunc (C function)
@anchor{c-api/init c _PyInterpreterState_GetEvalFrameFunc}@anchor{191c}
@deffn {C Fonction} @ref{760,,_PyFrameEvalFunction} _PyInterpreterState_GetEvalFrameFunc (PyInterpreterState *interp)

Get the frame evaluation function.

See the 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} "Adding a frame evaluation API to CPython".


Ajouté dans la version 3.9.

@end deffn

@geindex _PyInterpreterState_SetEvalFrameFunc (C function)
@anchor{c-api/init c _PyInterpreterState_SetEvalFrameFunc}@anchor{191d}
@deffn {C Fonction} void _PyInterpreterState_SetEvalFrameFunc (PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)

Set the frame evaluation function.

See the 
@geindex Python Enhancement Proposals; PEP 523
PEP 523@footnote{https://peps.python.org/pep-0523/} "Adding a frame evaluation API to CPython".


Ajouté dans la version 3.9.

@end deffn

@geindex PyThreadState_GetDict (C function)
@anchor{c-api/init c PyThreadState_GetDict}@anchor{4956}
@deffn {C Fonction} @ref{32f,,PyObject} *PyThreadState_GetDict ()
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Return a dictionary in which extensions can store thread-specific state
information.  Each extension should use a unique key to use to store state in
the dictionary.  It is okay to call this function when no current thread state
is available. If this function returns @code{NULL}, no exception has been raised and
the caller should assume no current thread state is available.
@end deffn

@geindex PyThreadState_SetAsyncExc (C function)
@anchor{c-api/init c PyThreadState_SetAsyncExc}@anchor{bb2}
@deffn {C Fonction} int PyThreadState_SetAsyncExc (unsigned long id, PyObject *exc)
` Part of the @ref{53e,,Stable ABI}.'
Asynchronously raise an exception in a thread. The `id' argument is the thread
id of the target thread; `exc' is the exception object to be raised. This
function does not steal any references to `exc'. To prevent naive misuse, you
must write your own C extension to call this.  Must be called with the GIL held.
Returns the number of thread states modified; this is normally one, but will be
zero if the thread id isn't found.  If `exc' is @code{NULL}, the pending
exception (if any) for the thread is cleared. This raises no exceptions.


Modifié dans la version 3.7: The type of the `id' parameter changed from long to
unsigned long.

@end deffn

@geindex PyEval_AcquireThread (C function)
@anchor{c-api/init c PyEval_AcquireThread}@anchor{3a1}
@deffn {C Fonction} void PyEval_AcquireThread (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
Acquire the global interpreter lock and set the current thread state to
`tstate', which must not be @code{NULL}.  The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.

@cartouche
@quotation Note 
Calling this function from a thread when the runtime is finalizing
will terminate the thread, even if the thread was not created by Python.
You can use @ref{350,,Py_IsFinalizing()} or @ref{a7d,,sys.is_finalizing()} to
check if the interpreter is in process of being finalized before calling
this function to avoid unwanted termination.
@end quotation
@end cartouche


Modifié dans la version 3.8: Updated to be consistent with @ref{3a0,,PyEval_RestoreThread()},
@ref{a7c,,Py_END_ALLOW_THREADS()}, and @ref{3a2,,PyGILState_Ensure()},
and terminate the current thread if called while the interpreter is finalizing.


@ref{3a0,,PyEval_RestoreThread()} is a higher-level function which is always
available (even when threads have not been initialized).
@end deffn

@geindex PyEval_ReleaseThread (C function)
@anchor{c-api/init c PyEval_ReleaseThread}@anchor{48bb}
@deffn {C Fonction} void PyEval_ReleaseThread (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
Reset the current thread state to @code{NULL} and release the global interpreter
lock.  The lock must have been created earlier and must be held by the current
thread.  The `tstate' argument, which must not be @code{NULL}, is only used to check
that it represents the current thread state --- if it isn't, a fatal error is
reported.

@ref{39f,,PyEval_SaveThread()} is a higher-level function which is always
available (even when threads have not been initialized).
@end deffn

@node Sub-interpreter support,Asynchronous Notifications,Thread State and the Global Interpreter Lock,Initialization Finalization and Threads
@anchor{c-api/init id1}@anchor{4c57}@anchor{c-api/init sub-interpreter-support}@anchor{573}
@subsection Sub-interpreter support


While in most uses, you will only embed a single Python interpreter, there
are cases where you need to create several independent interpreters in the
same process and perhaps even in the same thread. Sub-interpreters allow
you to do that.

The "main" interpreter is the first one created when the runtime initializes.
It is usually the only Python interpreter in a process.  Unlike sub-interpreters,
the main interpreter has unique process-global responsibilities like signal
handling.  It is also responsible for execution during runtime initialization and
is usually the active interpreter during runtime finalization.  The
@ref{4c58,,PyInterpreterState_Main()} function returns a pointer to its state.

You can switch between sub-interpreters using the @ref{4958,,PyThreadState_Swap()}
function. You can create and destroy them using the following functions:

@geindex PyInterpreterConfig (C type)
@anchor{c-api/init c PyInterpreterConfig}@anchor{559}
@deffn {C Type} type PyInterpreterConfig

Structure containing most parameters to configure a sub-interpreter.
Its values are used only in @ref{445,,Py_NewInterpreterFromConfig()} and
never modified by the runtime.


Ajouté dans la version 3.12.


Structure fields:

@geindex PyInterpreterConfig.use_main_obmalloc (C member)
@anchor{c-api/init c PyInterpreterConfig use_main_obmalloc}@anchor{42ab}
@deffn {C Membre} int use_main_obmalloc

If this is @code{0} then the sub-interpreter will use its own
"object" allocator state.
Otherwise it will use (share) the main interpreter's.

If this is @code{0} then
@ref{4c59,,check_multi_interp_extensions}
must be @code{1} (non-zero).
If this is @code{1} then @ref{4c5a,,gil}
must not be @ref{4c5b,,PyInterpreterConfig_OWN_GIL}.
@end deffn

@geindex PyInterpreterConfig.allow_fork (C member)
@anchor{c-api/init c PyInterpreterConfig allow_fork}@anchor{4c5c}
@deffn {C Membre} int allow_fork

If this is @code{0} then the runtime will not support forking the
process in any thread where the sub-interpreter is currently active.
Otherwise fork is unrestricted.

Note that the @ref{d5,,subprocess} module still works
when fork is disallowed.
@end deffn

@geindex PyInterpreterConfig.allow_exec (C member)
@anchor{c-api/init c PyInterpreterConfig allow_exec}@anchor{4c5d}
@deffn {C Membre} int allow_exec

If this is @code{0} then the runtime will not support replacing the
current process via exec (e.g. @ref{2aa1,,os.execv()}) in any thread
where the sub-interpreter is currently active.
Otherwise exec is unrestricted.

Note that the @ref{d5,,subprocess} module still works
when exec is disallowed.
@end deffn

@geindex PyInterpreterConfig.allow_threads (C member)
@anchor{c-api/init c PyInterpreterConfig allow_threads}@anchor{4c5e}
@deffn {C Membre} int allow_threads

If this is @code{0} then the sub-interpreter's @ref{ec,,threading} module
won't create threads.
Otherwise threads are allowed.
@end deffn

@geindex PyInterpreterConfig.allow_daemon_threads (C member)
@anchor{c-api/init c PyInterpreterConfig allow_daemon_threads}@anchor{4c5f}
@deffn {C Membre} int allow_daemon_threads

If this is @code{0} then the sub-interpreter's @ref{ec,,threading} module
won't create daemon threads.
Otherwise daemon threads are allowed (as long as
@ref{4c5e,,allow_threads} is non-zero).
@end deffn

@geindex PyInterpreterConfig.check_multi_interp_extensions (C member)
@anchor{c-api/init c PyInterpreterConfig check_multi_interp_extensions}@anchor{4c59}
@deffn {C Membre} int check_multi_interp_extensions

If this is @code{0} then all extension modules may be imported,
including legacy (single-phase init) modules,
in any thread where the sub-interpreter is currently active.
Otherwise only multi-phase init extension modules
(see 
@geindex Python Enhancement Proposals; PEP 489
PEP 489@footnote{https://peps.python.org/pep-0489/}) may be imported.
(Also see @ref{4bba,,Py_mod_multiple_interpreters}.)

This must be @code{1} (non-zero) if
@ref{42ab,,use_main_obmalloc} is @code{0}.
@end deffn

@geindex PyInterpreterConfig.gil (C member)
@anchor{c-api/init c PyInterpreterConfig gil}@anchor{4c5a}
@deffn {C Membre} int gil

This determines the operation of the GIL for the sub-interpreter.
It may be one of the following:

@geindex PyInterpreterConfig_DEFAULT_GIL (C macro)
@anchor{c-api/init c PyInterpreterConfig_DEFAULT_GIL}@anchor{4c60}
@deffn {C Macro} PyInterpreterConfig_DEFAULT_GIL

Use the default selection (@ref{4c61,,PyInterpreterConfig_SHARED_GIL}).
@end deffn

@geindex PyInterpreterConfig_SHARED_GIL (C macro)
@anchor{c-api/init c PyInterpreterConfig_SHARED_GIL}@anchor{4c61}
@deffn {C Macro} PyInterpreterConfig_SHARED_GIL

Use (share) the main interpreter's GIL.
@end deffn

@geindex PyInterpreterConfig_OWN_GIL (C macro)
@anchor{c-api/init c PyInterpreterConfig_OWN_GIL}@anchor{4c5b}
@deffn {C Macro} PyInterpreterConfig_OWN_GIL

Use the sub-interpreter's own GIL.
@end deffn

If this is @ref{4c5b,,PyInterpreterConfig_OWN_GIL} then
@ref{42ab,,PyInterpreterConfig.use_main_obmalloc} must be @code{0}.
@end deffn
@end deffn

@geindex Py_NewInterpreterFromConfig (C function)
@anchor{c-api/init c Py_NewInterpreterFromConfig}@anchor{445}
@deffn {C Fonction} @ref{99b,,PyStatus} Py_NewInterpreterFromConfig (PyThreadState **tstate_p, const PyInterpreterConfig *config)

@geindex module;builtins
@geindex module;__main__
@geindex module;sys
@geindex stdout (in module sys)
@geindex stderr (in module sys)
@geindex stdin (in module sys)

Create a new sub-interpreter.  This is an (almost) totally separate environment
for the execution of Python code.  In particular, the new interpreter has
separate, independent versions of all imported modules, including the
fundamental modules @ref{12,,builtins}, @ref{1,,__main__} and @ref{d8,,sys}.  The
table of loaded modules (@code{sys.modules}) and the module search path
(@code{sys.path}) are also separate.  The new environment has no @code{sys.argv}
variable.  It has new standard I/O stream file objects @code{sys.stdin},
@code{sys.stdout} and @code{sys.stderr} (however these refer to the same underlying
file descriptors).

The given `config' controls the options with which the interpreter
is initialized.

Upon success, `tstate_p' will be set to the first thread state
created in the new
sub-interpreter.  This thread state is made in the current thread state.
Note that no actual thread is created; see the discussion of thread states
below.  If creation of the new interpreter is unsuccessful,
`tstate_p' is set to @code{NULL};
no exception is set since the exception state is stored in the
current thread state and there may not be a current thread state.

Like all other Python/C API functions, the global interpreter lock
must be held before calling this function and is still held when it
returns.  Likewise a current thread state must be set on entry.  On
success, the returned thread state will be set as current.  If the
sub-interpreter is created with its own GIL then the GIL of the
calling interpreter will be released.  When the function returns,
the new interpreter's GIL will be held by the current thread and
the previously interpreter's GIL will remain released here.


Ajouté dans la version 3.12.


Sub-interpreters are most effective when isolated from each other,
with certain functionality restricted:

@example
PyInterpreterConfig config = @{
    .use_main_obmalloc = 0,
    .allow_fork = 0,
    .allow_exec = 0,
    .allow_threads = 1,
    .allow_daemon_threads = 0,
    .check_multi_interp_extensions = 1,
    .gil = PyInterpreterConfig_OWN_GIL,
@};
PyThreadState *tstate = NULL;
PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
if (PyStatus_Exception(status)) @{
    Py_ExitStatusException(status);
@}
@end example

Note that the config is used only briefly and does not get modified.
During initialization the config's values are converted into various
@ref{8aa,,PyInterpreterState} values.  A read-only copy of the config
may be stored internally on the @ref{8aa,,PyInterpreterState}.

@geindex Py_FinalizeEx (C function)
@geindex Py_Initialize (C function)

Extension modules are shared between (sub-)interpreters as follows:


@itemize *

@item 
For modules using multi-phase initialization,
e.g. @ref{e9b,,PyModule_FromDefAndSpec()}, a separate module object is
created and initialized for each interpreter.
Only C-level static and global variables are shared between these
module objects.

@item 
For modules using single-phase initialization,
e.g. @ref{47c4,,PyModule_Create()}, the first time a particular extension
is imported, it is initialized normally, and a (shallow) copy of its
module's dictionary is squirreled away.
When the same extension is imported by another (sub-)interpreter, a new
module is initialized and filled with the contents of this copy; the
extension's @code{init} function is not called.
Objects in the module's dictionary thus end up shared across
(sub-)interpreters, which might cause unwanted behavior (see
@ref{4c62,,Bugs and caveats} below).

Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by
calling @ref{d03,,Py_FinalizeEx()} and @ref{899,,Py_Initialize()}; in that
case, the extension's @code{initmodule} function `is' called again.
As with multi-phase initialization, this means that only C-level static
and global variables are shared between these modules.
@end itemize

@geindex close (in module os)
@end deffn

@geindex Py_NewInterpreter (C function)
@anchor{c-api/init c Py_NewInterpreter}@anchor{1744}
@deffn {C Fonction} @ref{777,,PyThreadState} *Py_NewInterpreter (void)
` Part of the @ref{53e,,Stable ABI}.'
@geindex module;builtins
@geindex module;__main__
@geindex module;sys
@geindex stdout (in module sys)
@geindex stderr (in module sys)
@geindex stdin (in module sys)

Create a new sub-interpreter.  This is essentially just a wrapper
around @ref{445,,Py_NewInterpreterFromConfig()} with a config that
preserves the existing behavior.  The result is an unisolated
sub-interpreter that shares the main interpreter's GIL, allows
fork/exec, allows daemon threads, and allows single-phase init
modules.
@end deffn

@geindex Py_EndInterpreter (C function)
@anchor{c-api/init c Py_EndInterpreter}@anchor{17ed}
@deffn {C Fonction} void Py_EndInterpreter (PyThreadState *tstate)
` Part of the @ref{53e,,Stable ABI}.'
@geindex Py_FinalizeEx (C function)

Destroy the (sub-)interpreter represented by the given thread state.
The given thread state must be the current thread state.  See the
discussion of thread states below.  When the call returns,
the current thread state is @code{NULL}.  All thread states associated
with this interpreter are destroyed.  The global interpreter lock
used by the target interpreter must be held before calling this
function.  No GIL is held when it returns.

@ref{d03,,Py_FinalizeEx()} will destroy all sub-interpreters that
haven't been explicitly destroyed at that point.
@end deffn

@menu
* A Per-Interpreter GIL:: 
* Bugs and caveats:: 

@end menu

@node A Per-Interpreter GIL,Bugs and caveats,,Sub-interpreter support
@anchor{c-api/init a-per-interpreter-gil}@anchor{4c63}
@subsubsection A Per-Interpreter GIL


Using @ref{445,,Py_NewInterpreterFromConfig()} you can create
a sub-interpreter that is completely isolated from other interpreters,
including having its own GIL.  The most important benefit of this
isolation is that such an interpreter can execute Python code without
being blocked by other interpreters or blocking any others.  Thus a
single Python process can truly take advantage of multiple CPU cores
when running Python code.  The isolation also encourages a different
approach to concurrency than that of just using threads.
(See 
@geindex Python Enhancement Proposals; PEP 554
PEP 554@footnote{https://peps.python.org/pep-0554/}.)

Using an isolated interpreter requires vigilance in preserving that
isolation.  That especially means not sharing any objects or mutable
state without guarantees about thread-safety.  Even objects that are
otherwise immutable (e.g. @code{None}, @code{(1, 5)}) can't normally be shared
because of the refcount.  One simple but less-efficient approach around
this is to use a global lock around all use of some state (or object).
Alternately, effectively immutable objects (like integers or strings)
can be made safe in spite of their refcounts by making them @ref{42aa,,immortal}.
In fact, this has been done for the builtin singletons, small integers,
and a number of other builtin objects.

If you preserve isolation then you will have access to proper multi-core
computing without the complications that come with free-threading.
Failure to preserve isolation will expose you to the full consequences
of free-threading, including races and hard-to-debug crashes.

Aside from that, one of the main challenges of using multiple isolated
interpreters is how to communicate between them safely (not break
isolation) and efficiently.  The runtime and stdlib do not provide
any standard approach to this yet.  A future stdlib module would help
mitigate the effort of preserving isolation and expose effective tools
for communicating (and sharing) data between interpreters.


Ajouté dans la version 3.12.


@node Bugs and caveats,,A Per-Interpreter GIL,Sub-interpreter support
@anchor{c-api/init bugs-and-caveats}@anchor{4c62}
@subsubsection Bugs and caveats


Because sub-interpreters (and the main interpreter) are part of the same
process, the insulation between them isn't perfect --- for example, using
low-level file operations like  @ref{b62,,os.close()} they can
(accidentally or maliciously) affect each other's open files.  Because of the
way extensions are shared between (sub-)interpreters, some extensions may not
work properly; this is especially likely when using single-phase initialization
or (static) global variables.
It is possible to insert objects created in one sub-interpreter into
a namespace of another (sub-)interpreter; this should be avoided if possible.

Special care should be taken to avoid sharing user-defined functions,
methods, instances or classes between sub-interpreters, since import
operations executed by such objects may affect the wrong (sub-)interpreter's
dictionary of loaded modules. It is equally important to avoid sharing
objects from which the above are reachable.

Also note that combining this functionality with @code{PyGILState_*} APIs
is delicate, because these APIs assume a bijection between Python thread states
and OS-level threads, an assumption broken by the presence of sub-interpreters.
It is highly recommended that you don't switch sub-interpreters between a pair
of matching @ref{3a2,,PyGILState_Ensure()} and @ref{3a3,,PyGILState_Release()} calls.
Furthermore, extensions (such as @ref{2a,,ctypes}) using these APIs to allow calling
of Python code from non-Python created threads will probably be broken when using
sub-interpreters.

@node Asynchronous Notifications,Profiling and Tracing,Sub-interpreter support,Initialization Finalization and Threads
@anchor{c-api/init asynchronous-notifications}@anchor{4c64}
@subsection Asynchronous Notifications


A mechanism is provided to make asynchronous notifications to the main
interpreter thread.  These notifications take the form of a function
pointer and a void pointer argument.

@geindex Py_AddPendingCall (C function)
@anchor{c-api/init c Py_AddPendingCall}@anchor{96e}
@deffn {C Fonction} int Py_AddPendingCall (int (*func)(void*), void *arg)
` Part of the @ref{53e,,Stable ABI}.'
Schedule a function to be called from the main interpreter thread.  On
success, @code{0} is returned and `func' is queued for being called in the
main thread.  On failure, @code{-1} is returned without setting any exception.

When successfully queued, `func' will be `eventually' called from the
main interpreter thread with the argument `arg'.  It will be called
asynchronously with respect to normally running Python code, but with
both these conditions met:


@itemize *

@item 
on a @ref{185,,bytecode} boundary;

@item 
with the main thread holding the @ref{147,,global interpreter lock}
(`func' can therefore use the full C API).
@end itemize

`func' must return @code{0} on success, or @code{-1} on failure with an exception
set.  `func' won't be interrupted to perform another asynchronous
notification recursively, but it can still be interrupted to switch
threads if the global interpreter lock is released.

This function doesn't need a current thread state to run, and it doesn't
need the global interpreter lock.

To call this function in a subinterpreter, the caller must hold the GIL.
Otherwise, the function `func' can be scheduled to be called from the wrong
interpreter.

@cartouche
@quotation Avertissement 
This is a low-level function, only useful for very special cases.
There is no guarantee that `func' will be called as quick as
possible.  If the main thread is busy executing a system call,
`func' won't be called before the system call returns.  This
function is generally `not' suitable for calling Python code from
arbitrary C threads.  Instead, use the @ref{4c50,,PyGILState API}.
@end quotation
@end cartouche


Ajouté dans la version 3.1.



Modifié dans la version 3.9: If this function is called in a subinterpreter, the function `func' is
now scheduled to be called from the subinterpreter, rather than being
called from the main interpreter. Each subinterpreter now has its own
list of scheduled calls.

@end deffn

@node Profiling and Tracing,Reference tracing,Asynchronous Notifications,Initialization Finalization and Threads
@anchor{c-api/init profiling}@anchor{4c65}@anchor{c-api/init profiling-and-tracing}@anchor{4c66}
@subsection Profiling and Tracing


The Python interpreter provides some low-level support for attaching profiling
and execution tracing facilities.  These are used for profiling, debugging, and
coverage analysis tools.

This C interface allows the profiling or tracing code to avoid the overhead of
calling through Python-level callable objects, making a direct C function call
instead.  The essential attributes of the facility have not changed; the
interface allows trace functions to be installed per-thread, and the basic
events reported to the trace function are the same as had been reported to the
Python-level trace functions in previous versions.

@geindex Py_tracefunc (C type)
@anchor{c-api/init c Py_tracefunc}@anchor{4c67}
@deffn {C Type} typedef int (*Py_tracefunc)(@ref{32f,,PyObject} *obj, @ref{773,,PyFrameObject} *frame, int what, @ref{32f,,PyObject} *arg)

The type of the trace function registered using @ref{14b3,,PyEval_SetProfile()} and
@ref{14b4,,PyEval_SetTrace()}. The first parameter is the object passed to the
registration function as `obj', `frame' is the frame object to which the event
pertains, `what' is one of the constants @ref{4c68,,PyTrace_CALL},
@ref{4c69,,PyTrace_EXCEPTION}, @ref{4c6a,,PyTrace_LINE}, @ref{4c6b,,PyTrace_RETURN},
@ref{4c6c,,PyTrace_C_CALL}, @ref{4c6d,,PyTrace_C_EXCEPTION}, @ref{4c6e,,PyTrace_C_RETURN},
or @ref{4c6f,,PyTrace_OPCODE}, and `arg' depends on the value of `what':


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Value of `what'

@tab

Meaning of `arg'

@item

@ref{4c68,,PyTrace_CALL}

@tab

Always @ref{47c0,,Py_None}.

@item

@ref{4c69,,PyTrace_EXCEPTION}

@tab

Exception information as returned by
@ref{675,,sys.exc_info()}.

@item

@ref{4c6a,,PyTrace_LINE}

@tab

Always @ref{47c0,,Py_None}.

@item

@ref{4c6b,,PyTrace_RETURN}

@tab

Value being returned to the caller,
or @code{NULL} if caused by an exception.

@item

@ref{4c6c,,PyTrace_C_CALL}

@tab

Function object being called.

@item

@ref{4c6d,,PyTrace_C_EXCEPTION}

@tab

Function object being called.

@item

@ref{4c6e,,PyTrace_C_RETURN}

@tab

Function object being called.

@item

@ref{4c6f,,PyTrace_OPCODE}

@tab

Always @ref{47c0,,Py_None}.

@end multitable

@end deffn

@geindex PyTrace_CALL (C var)
@anchor{c-api/init c PyTrace_CALL}@anchor{4c68}
@deffn {C Variable} int PyTrace_CALL

The value of the `what' parameter to a @ref{4c67,,Py_tracefunc} function when a new
call to a function or method is being reported, or a new entry into a generator.
Note that the creation of the iterator for a generator function is not reported
as there is no control transfer to the Python bytecode in the corresponding
frame.
@end deffn

@geindex PyTrace_EXCEPTION (C var)
@anchor{c-api/init c PyTrace_EXCEPTION}@anchor{4c69}
@deffn {C Variable} int PyTrace_EXCEPTION

The value of the `what' parameter to a @ref{4c67,,Py_tracefunc} function when an
exception has been raised.  The callback function is called with this value for
`what' when after any bytecode is processed after which the exception becomes
set within the frame being executed.  The effect of this is that as exception
propagation causes the Python stack to unwind, the callback is called upon
return to each frame as the exception propagates.  Only trace functions receives
these events; they are not needed by the profiler.
@end deffn

@geindex PyTrace_LINE (C var)
@anchor{c-api/init c PyTrace_LINE}@anchor{4c6a}
@deffn {C Variable} int PyTrace_LINE

The value passed as the `what' parameter to a @ref{4c67,,Py_tracefunc} function
(but not a profiling function) when a line-number event is being reported.
It may be disabled for a frame by setting @ref{bc9,,f_trace_lines} to
`0' on that frame.
@end deffn

@geindex PyTrace_RETURN (C var)
@anchor{c-api/init c PyTrace_RETURN}@anchor{4c6b}
@deffn {C Variable} int PyTrace_RETURN

The value for the `what' parameter to @ref{4c67,,Py_tracefunc} functions when a
call is about to return.
@end deffn

@geindex PyTrace_C_CALL (C var)
@anchor{c-api/init c PyTrace_C_CALL}@anchor{4c6c}
@deffn {C Variable} int PyTrace_C_CALL

The value for the `what' parameter to @ref{4c67,,Py_tracefunc} functions when a C
function is about to be called.
@end deffn

@geindex PyTrace_C_EXCEPTION (C var)
@anchor{c-api/init c PyTrace_C_EXCEPTION}@anchor{4c6d}
@deffn {C Variable} int PyTrace_C_EXCEPTION

The value for the `what' parameter to @ref{4c67,,Py_tracefunc} functions when a C
function has raised an exception.
@end deffn

@geindex PyTrace_C_RETURN (C var)
@anchor{c-api/init c PyTrace_C_RETURN}@anchor{4c6e}
@deffn {C Variable} int PyTrace_C_RETURN

The value for the `what' parameter to @ref{4c67,,Py_tracefunc} functions when a C
function has returned.
@end deffn

@geindex PyTrace_OPCODE (C var)
@anchor{c-api/init c PyTrace_OPCODE}@anchor{4c6f}
@deffn {C Variable} int PyTrace_OPCODE

The value for the `what' parameter to @ref{4c67,,Py_tracefunc} functions (but not
profiling functions) when a new opcode is about to be executed.  This event is
not emitted by default: it must be explicitly requested by setting
@ref{bca,,f_trace_opcodes} to `1' on the frame.
@end deffn

@geindex PyEval_SetProfile (C function)
@anchor{c-api/init c PyEval_SetProfile}@anchor{14b3}
@deffn {C Fonction} void PyEval_SetProfile (Py_tracefunc func, PyObject *obj)

Set the profiler function to `func'.  The `obj' parameter is passed to the
function as its first parameter, and may be any Python object, or @code{NULL}.  If
the profile function needs to maintain state, using a different value for `obj'
for each thread provides a convenient and thread-safe place to store it.  The
profile function is called for all monitored events except @ref{4c6a,,PyTrace_LINE}
@ref{4c6f,,PyTrace_OPCODE} and @ref{4c69,,PyTrace_EXCEPTION}.

See also the @ref{14b5,,sys.setprofile()} function.

The caller must hold the @ref{158,,GIL}.
@end deffn

@geindex PyEval_SetProfileAllThreads (C function)
@anchor{c-api/init c PyEval_SetProfileAllThreads}@anchor{54a}
@deffn {C Fonction} void PyEval_SetProfileAllThreads (Py_tracefunc func, PyObject *obj)

Like @ref{14b3,,PyEval_SetProfile()} but sets the profile function in all running threads
belonging to the current interpreter instead of the setting it only on the current thread.

The caller must hold the @ref{158,,GIL}.

As @ref{14b3,,PyEval_SetProfile()}, this function ignores any exceptions raised while
setting the profile functions in all threads.
@end deffn


Ajouté dans la version 3.12.


@geindex PyEval_SetTrace (C function)
@anchor{c-api/init c PyEval_SetTrace}@anchor{14b4}
@deffn {C Fonction} void PyEval_SetTrace (Py_tracefunc func, PyObject *obj)

Set the tracing function to `func'.  This is similar to
@ref{14b3,,PyEval_SetProfile()}, except the tracing function does receive line-number
events and per-opcode events, but does not receive any event related to C function
objects being called.  Any trace function registered using @ref{14b4,,PyEval_SetTrace()}
will not receive @ref{4c6c,,PyTrace_C_CALL}, @ref{4c6d,,PyTrace_C_EXCEPTION} or
@ref{4c6e,,PyTrace_C_RETURN} as a value for the `what' parameter.

See also the @ref{14b6,,sys.settrace()} function.

The caller must hold the @ref{158,,GIL}.
@end deffn

@geindex PyEval_SetTraceAllThreads (C function)
@anchor{c-api/init c PyEval_SetTraceAllThreads}@anchor{54b}
@deffn {C Fonction} void PyEval_SetTraceAllThreads (Py_tracefunc func, PyObject *obj)

Like @ref{14b4,,PyEval_SetTrace()} but sets the tracing function in all running threads
belonging to the current interpreter instead of the setting it only on the current thread.

The caller must hold the @ref{158,,GIL}.

As @ref{14b4,,PyEval_SetTrace()}, this function ignores any exceptions raised while
setting the trace functions in all threads.
@end deffn


Ajouté dans la version 3.12.


@node Reference tracing,Support avancé du débogueur,Profiling and Tracing,Initialization Finalization and Threads
@anchor{c-api/init reference-tracing}@anchor{4c70}
@subsection Reference tracing



Ajouté dans la version 3.13.


@geindex PyRefTracer (C type)
@anchor{c-api/init c PyRefTracer}@anchor{4c71}
@deffn {C Type} typedef int (*PyRefTracer)(@ref{32f,,PyObject}*, int event, void *data)

The type of the trace function registered using @ref{362,,PyRefTracer_SetTracer()}.
The first parameter is a Python object that has been just created (when `event'
is set to @ref{4c72,,PyRefTracer_CREATE}) or about to be destroyed (when `event'
is set to @ref{4c73,,PyRefTracer_DESTROY}). The `data' argument is the opaque pointer
that was provided when @ref{362,,PyRefTracer_SetTracer()} was called.
@end deffn


Ajouté dans la version 3.13.


@geindex PyRefTracer_CREATE (C var)
@anchor{c-api/init c PyRefTracer_CREATE}@anchor{4c72}
@deffn {C Variable} int PyRefTracer_CREATE

The value for the `event' parameter to @ref{4c71,,PyRefTracer} functions when a Python
object has been created.
@end deffn

@geindex PyRefTracer_DESTROY (C var)
@anchor{c-api/init c PyRefTracer_DESTROY}@anchor{4c73}
@deffn {C Variable} int PyRefTracer_DESTROY

The value for the `event' parameter to @ref{4c71,,PyRefTracer} functions when a Python
object has been destroyed.
@end deffn

@geindex PyRefTracer_SetTracer (C function)
@anchor{c-api/init c PyRefTracer_SetTracer}@anchor{362}
@deffn {C Fonction} int PyRefTracer_SetTracer (PyRefTracer tracer, void *data)

Register a reference tracer function. The function will be called when a new
Python has been created or when an object is going to be destroyed. If
`data' is provided it must be an opaque pointer that will be provided when
the tracer function is called. Return @code{0} on success. Set an exception and
return @code{-1} on error.

Not that tracer functions `must not' create Python objects inside or
otherwise the call will be re-entrant. The tracer also `must not' clear
any existing exception or set an exception.  The GIL will be held every time
the tracer function is called.

The GIL must be held when calling this function.
@end deffn


Ajouté dans la version 3.13.


@geindex PyRefTracer_GetTracer (C function)
@anchor{c-api/init c PyRefTracer_GetTracer}@anchor{363}
@deffn {C Fonction} @ref{4c71,,PyRefTracer} PyRefTracer_GetTracer (void **data)

Get the registered reference tracer function and the value of the opaque data
pointer that was registered when @ref{362,,PyRefTracer_SetTracer()} was called.
If no tracer was registered this function will return NULL and will set the
`data' pointer to NULL.

The GIL must be held when calling this function.
@end deffn


Ajouté dans la version 3.13.


@node Support avancé du débogueur,Thread Local Storage Support,Reference tracing,Initialization Finalization and Threads
@anchor{c-api/init advanced-debugger-support}@anchor{4c74}@anchor{c-api/init advanced-debugging}@anchor{4c75}
@subsection Support avancé du débogueur


These functions are only intended to be used by advanced debugging tools.

@geindex PyInterpreterState_Head (C function)
@anchor{c-api/init c PyInterpreterState_Head}@anchor{14b7}
@deffn {C Fonction} @ref{8aa,,PyInterpreterState} *PyInterpreterState_Head ()

Return the interpreter state object at the head of the list of all such objects.
@end deffn

@geindex PyInterpreterState_Main (C function)
@anchor{c-api/init c PyInterpreterState_Main}@anchor{4c58}
@deffn {C Fonction} @ref{8aa,,PyInterpreterState} *PyInterpreterState_Main ()

Return the main interpreter state object.
@end deffn

@geindex PyInterpreterState_Next (C function)
@anchor{c-api/init c PyInterpreterState_Next}@anchor{14b8}
@deffn {C Fonction} @ref{8aa,,PyInterpreterState} *PyInterpreterState_Next (PyInterpreterState *interp)

Return the next interpreter state object after `interp' from the list of all
such objects.
@end deffn

@geindex PyInterpreterState_ThreadHead (C function)
@anchor{c-api/init c PyInterpreterState_ThreadHead}@anchor{14b9}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyInterpreterState_ThreadHead (PyInterpreterState *interp)

Return the pointer to the first @ref{777,,PyThreadState} object in the list of
threads associated with the interpreter `interp'.
@end deffn

@geindex PyThreadState_Next (C function)
@anchor{c-api/init c PyThreadState_Next}@anchor{14ba}
@deffn {C Fonction} @ref{777,,PyThreadState} *PyThreadState_Next (PyThreadState *tstate)

Return the next thread state object after `tstate' from the list of all such
objects belonging to the same @ref{8aa,,PyInterpreterState} object.
@end deffn

@node Thread Local Storage Support,Primitives de synchronisation<3>,Support avancé du débogueur,Initialization Finalization and Threads
@anchor{c-api/init thread-local-storage}@anchor{4c76}@anchor{c-api/init thread-local-storage-support}@anchor{4c77}
@subsection Thread Local Storage Support


The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread local storage API (@ref{16f9,,threading.local}).  The
CPython C level APIs are similar to those offered by pthreads and Windows:
use a thread key and functions to associate a void* value per
thread.

The GIL does `not' need to be held when calling these functions; they supply
their own locking.

Note that @code{Python.h} does not include the declaration of the TLS APIs,
you need to include @code{pythread.h} to use thread-local storage.

@cartouche
@quotation Note 
None of these API functions handle memory management on behalf of the
void* values.  You need to allocate and deallocate them yourself.
If the void* values happen to be @ref{32f,,PyObject}*, these
functions don't do refcount operations on them either.
@end quotation
@end cartouche

@menu
* Thread Specific Storage (TSS) API: Thread Specific Storage TSS API. 
* Thread Local Storage (TLS) API: Thread Local Storage TLS API. 

@end menu

@node Thread Specific Storage TSS API,Thread Local Storage TLS API,,Thread Local Storage Support
@anchor{c-api/init thread-specific-storage-api}@anchor{acc}@anchor{c-api/init thread-specific-storage-tss-api}@anchor{4c78}
@subsubsection Thread Specific Storage (TSS) API


TSS API is introduced to supersede the use of the existing TLS API within the
CPython interpreter.  This API uses a new type @ref{acd,,Py_tss_t} instead of
int to represent thread keys.


Ajouté dans la version 3.7.



@subsubheading Voir aussi


"A New C-API for Thread-Local Storage in CPython" (
@geindex Python Enhancement Proposals; PEP 539
PEP 539@footnote{https://peps.python.org/pep-0539/})


@geindex Py_tss_t (C type)
@anchor{c-api/init c Py_tss_t}@anchor{acd}
@deffn {C Type} type Py_tss_t

This data structure represents the state of a thread key, the definition of
which may depend on the underlying TLS implementation, and it has an
internal field representing the key's initialization state.  There are no
public members in this structure.

When @ref{53e,,Py_LIMITED_API} is not defined, static allocation of
this type by @ref{4c79,,Py_tss_NEEDS_INIT} is allowed.
@end deffn

@geindex Py_tss_NEEDS_INIT (C macro)
@anchor{c-api/init c Py_tss_NEEDS_INIT}@anchor{4c79}
@deffn {C Macro} Py_tss_NEEDS_INIT

This macro expands to the initializer for @ref{acd,,Py_tss_t} variables.
Note that this macro won't be defined with @ref{53e,,Py_LIMITED_API}.
@end deffn

@menu
* Dynamic Allocation:: 
* Méthodes: Méthodes<2>. 

@end menu

@node Dynamic Allocation,Méthodes<2>,,Thread Specific Storage TSS API
@anchor{c-api/init dynamic-allocation}@anchor{4c7a}
@subsubsection Dynamic Allocation


Dynamic allocation of the @ref{acd,,Py_tss_t}, required in extension modules
built with @ref{53e,,Py_LIMITED_API}, where static allocation of this type
is not possible due to its implementation being opaque at build time.

@geindex PyThread_tss_alloc (C function)
@anchor{c-api/init c PyThread_tss_alloc}@anchor{3fb}
@deffn {C Fonction} @ref{acd,,Py_tss_t} *PyThread_tss_alloc ()
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return a value which is the same state as a value initialized with
@ref{4c79,,Py_tss_NEEDS_INIT}, or @code{NULL} in the case of dynamic allocation
failure.
@end deffn

@geindex PyThread_tss_free (C function)
@anchor{c-api/init c PyThread_tss_free}@anchor{3fd}
@deffn {C Fonction} void PyThread_tss_free (Py_tss_t *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Free the given `key' allocated by @ref{3fb,,PyThread_tss_alloc()}, after
first calling @ref{403,,PyThread_tss_delete()} to ensure any associated
thread locals have been unassigned. This is a no-op if the `key'
argument is @code{NULL}.

@cartouche
@quotation Note 
A freed key becomes a dangling pointer. You should reset the key to
@code{NULL}.
@end quotation
@end cartouche
@end deffn

@node Méthodes<2>,,Dynamic Allocation,Thread Specific Storage TSS API
@anchor{c-api/init methods}@anchor{4c7b}
@subsubsection Méthodes


The parameter `key' of these functions must not be @code{NULL}.  Moreover, the
behaviors of @ref{3ff,,PyThread_tss_set()} and @ref{401,,PyThread_tss_get()} are
undefined if the given @ref{acd,,Py_tss_t} has not been initialized by
@ref{4959,,PyThread_tss_create()}.

@geindex PyThread_tss_is_created (C function)
@anchor{c-api/init c PyThread_tss_is_created}@anchor{495a}
@deffn {C Fonction} int PyThread_tss_is_created (Py_tss_t *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return a non-zero value if the given @ref{acd,,Py_tss_t} has been initialized
by @ref{4959,,PyThread_tss_create()}.
@end deffn

@geindex PyThread_tss_create (C function)
@anchor{c-api/init c PyThread_tss_create}@anchor{4959}
@deffn {C Fonction} int PyThread_tss_create (Py_tss_t *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return a zero value on successful initialization of a TSS key.  The behavior
is undefined if the value pointed to by the `key' argument is not
initialized by @ref{4c79,,Py_tss_NEEDS_INIT}.  This function can be called
repeatedly on the same key -- calling it on an already initialized key is a
no-op and immediately returns success.
@end deffn

@geindex PyThread_tss_delete (C function)
@anchor{c-api/init c PyThread_tss_delete}@anchor{403}
@deffn {C Fonction} void PyThread_tss_delete (Py_tss_t *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Destroy a TSS key to forget the values associated with the key across all
threads, and change the key's initialization state to uninitialized.  A
destroyed key is able to be initialized again by
@ref{4959,,PyThread_tss_create()}. This function can be called repeatedly on
the same key -- calling it on an already destroyed key is a no-op.
@end deffn

@geindex PyThread_tss_set (C function)
@anchor{c-api/init c PyThread_tss_set}@anchor{3ff}
@deffn {C Fonction} int PyThread_tss_set (Py_tss_t *key, void *value)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return a zero value to indicate successfully associating a void*
value with a TSS key in the current thread.  Each thread has a distinct
mapping of the key to a void* value.
@end deffn

@geindex PyThread_tss_get (C function)
@anchor{c-api/init c PyThread_tss_get}@anchor{401}
@deffn {C Fonction} void *PyThread_tss_get (Py_tss_t *key)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Return the void* value associated with a TSS key in the current
thread.  This returns @code{NULL} if no value is associated with the key in the
current thread.
@end deffn

@node Thread Local Storage TLS API,,Thread Specific Storage TSS API,Thread Local Storage Support
@anchor{c-api/init thread-local-storage-api}@anchor{acb}@anchor{c-api/init thread-local-storage-tls-api}@anchor{4c7c}
@subsubsection Thread Local Storage (TLS) API



Obsolète depuis la version 3.7: This API is superseded by
@ref{acc,,Thread Specific Storage (TSS) API}.


@cartouche
@quotation Note 
This version of the API does not support platforms where the native TLS key
is defined in a way that cannot be safely cast to @code{int}.  On such platforms,
@ref{3fa,,PyThread_create_key()} will return immediately with a failure status,
and the other TLS functions will all be no-ops on such platforms.
@end quotation
@end cartouche

Due to the compatibility problem noted above, this version of the API should not
be used in new code.

@geindex PyThread_create_key (C function)
@anchor{c-api/init c PyThread_create_key}@anchor{3fa}
@deffn {C Fonction} int PyThread_create_key ()
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyThread_delete_key (C function)
@anchor{c-api/init c PyThread_delete_key}@anchor{3fc}
@deffn {C Fonction} void PyThread_delete_key (int key)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyThread_set_key_value (C function)
@anchor{c-api/init c PyThread_set_key_value}@anchor{3fe}
@deffn {C Fonction} int PyThread_set_key_value (int key, void *value)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyThread_get_key_value (C function)
@anchor{c-api/init c PyThread_get_key_value}@anchor{400}
@deffn {C Fonction} void *PyThread_get_key_value (int key)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyThread_delete_key_value (C function)
@anchor{c-api/init c PyThread_delete_key_value}@anchor{402}
@deffn {C Fonction} void PyThread_delete_key_value (int key)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex PyThread_ReInitTLS (C function)
@anchor{c-api/init c PyThread_ReInitTLS}@anchor{404}
@deffn {C Fonction} void PyThread_ReInitTLS ()
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@node Primitives de synchronisation<3>,,Thread Local Storage Support,Initialization Finalization and Threads
@anchor{c-api/init synchronization-primitives}@anchor{4c7d}
@subsection Primitives de synchronisation


The C-API provides a basic mutual exclusion lock.

@geindex PyMutex (C type)
@anchor{c-api/init c PyMutex}@anchor{15a}
@deffn {C Type} type PyMutex

A mutual exclusion lock.  The @code{PyMutex} should be initialized to
zero to represent the unlocked state.  For example:

@example
PyMutex mutex = @{0@};
@end example

Instances of @code{PyMutex} should not be copied or moved.  Both the
contents and address of a @code{PyMutex} are meaningful, and it must
remain at a fixed, writable location in memory.

@cartouche
@quotation Note 
A @code{PyMutex} currently occupies one byte, but the size should be
considered unstable.  The size may change in future Python releases
without a deprecation period.
@end quotation
@end cartouche


Ajouté dans la version 3.13.

@end deffn

@geindex PyMutex_Lock (C function)
@anchor{c-api/init c PyMutex_Lock}@anchor{320}
@deffn {C Fonction} void PyMutex_Lock (PyMutex *m)

Lock mutex `m'.  If another thread has already locked it, the calling
thread will block until the mutex is unlocked.  While blocked, the thread
will temporarily release the @ref{158,,GIL} if it is held.


Ajouté dans la version 3.13.

@end deffn

@geindex PyMutex_Unlock (C function)
@anchor{c-api/init c PyMutex_Unlock}@anchor{321}
@deffn {C Fonction} void PyMutex_Unlock (PyMutex *m)

Unlock mutex `m'. The mutex must be locked --- otherwise, the function will
issue a fatal error.


Ajouté dans la version 3.13.

@end deffn

@menu
* Python Critical Section API:: 

@end menu

@node Python Critical Section API,,,Primitives de synchronisation<3>
@anchor{c-api/init id2}@anchor{4c7e}@anchor{c-api/init python-critical-section-api}@anchor{4c7f}
@subsubsection Python Critical Section API


The critical section API provides a deadlock avoidance layer on top of
per-object locks for @ref{150c,,free-threaded} CPython.  They are
intended to replace reliance on the @ref{147,,global interpreter lock}, and are
no-ops in versions of Python with the global interpreter lock.

Critical sections avoid deadlocks by implicitly suspending active critical
sections and releasing the locks during calls to @ref{39f,,PyEval_SaveThread()}.
When @ref{3a0,,PyEval_RestoreThread()} is called, the most recent critical section
is resumed, and its locks reacquired.  This means the critical section API
provides weaker guarantees than traditional locks -- they are useful because
their behavior is similar to the @ref{158,,GIL}.

The functions and structs used by the macros are exposed for cases
where C macros are not available. They should only be used as in the
given macro expansions. Note that the sizes and contents of the structures may
change in future Python versions.

@cartouche
@quotation Note 
Operations that need to lock two objects at once must use
@ref{4c80,,Py_BEGIN_CRITICAL_SECTION2}.  You `cannot' use nested critical
sections to lock more than one object at once, because the inner critical
section may suspend the outer critical sections.  This API does not provide
a way to lock more than two objects at once.
@end quotation
@end cartouche

Exemple d'utilisation :

@example
static PyObject *
set_field(MyObject *self, PyObject *value)
@{
   Py_BEGIN_CRITICAL_SECTION(self);
   Py_SETREF(self->field, Py_XNewRef(value));
   Py_END_CRITICAL_SECTION();
   Py_RETURN_NONE;
@}
@end example

In the above example, @ref{565,,Py_SETREF} calls @ref{55b,,Py_DECREF}, which
can call arbitrary code through an object's deallocation function.  The critical
section API avoids potential deadlocks due to reentrancy and lock ordering
by allowing the runtime to temporarily suspend the critical section if the
code triggered by the finalizer blocks and calls @ref{39f,,PyEval_SaveThread()}.

@geindex Py_BEGIN_CRITICAL_SECTION (C macro)
@anchor{c-api/init c Py_BEGIN_CRITICAL_SECTION}@anchor{4b55}
@deffn {C Macro} Py_BEGIN_CRITICAL_SECTION (op)

Acquires the per-object lock for the object `op' and begins a
critical section.

In the free-threaded build, this macro expands to:

@example
@{
    PyCriticalSection _py_cs;
    PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))
@end example

In the default build, this macro expands to @code{@{}.


Ajouté dans la version 3.13.

@end deffn

@geindex Py_END_CRITICAL_SECTION (C macro)
@anchor{c-api/init c Py_END_CRITICAL_SECTION}@anchor{4c81}
@deffn {C Macro} Py_END_CRITICAL_SECTION ()

Ends the critical section and releases the per-object lock.

In the free-threaded build, this macro expands to:

@example
    PyCriticalSection_End(&_py_cs);
@}
@end example

In the default build, this macro expands to @code{@}}.


Ajouté dans la version 3.13.

@end deffn

@geindex Py_BEGIN_CRITICAL_SECTION2 (C macro)
@anchor{c-api/init c Py_BEGIN_CRITICAL_SECTION2}@anchor{4c80}
@deffn {C Macro} Py_BEGIN_CRITICAL_SECTION2 (a, b)

Acquires the per-objects locks for the objects `a' and `b' and begins a
critical section.  The locks are acquired in a consistent order (lowest
address first) to avoid lock ordering deadlocks.

In the free-threaded build, this macro expands to:

@example
@{
    PyCriticalSection2 _py_cs2;
    PyCriticalSection2_Begin(&_py_cs2, (PyObject*)(a), (PyObject*)(b))
@end example

In the default build, this macro expands to @code{@{}.


Ajouté dans la version 3.13.

@end deffn

@geindex Py_END_CRITICAL_SECTION2 (C macro)
@anchor{c-api/init c Py_END_CRITICAL_SECTION2}@anchor{4c82}
@deffn {C Macro} Py_END_CRITICAL_SECTION2 ()

Ends the critical section and releases the per-object locks.

In the free-threaded build, this macro expands to:

@example
    PyCriticalSection2_End(&_py_cs2);
@}
@end example

In the default build, this macro expands to @code{@}}.


Ajouté dans la version 3.13.

@end deffn

@node Python Initialization Configuration,Memory Management,Initialization Finalization and Threads,Manuel de référence de l'API Python/C
@anchor{c-api/init_config doc}@anchor{4c83}@anchor{c-api/init_config init-config}@anchor{39e}@anchor{c-api/init_config python-initialization-configuration}@anchor{4c84}
@section Python Initialization Configuration



Ajouté dans la version 3.8.


Python can be initialized with @ref{3bc,,Py_InitializeFromConfig()} and the
@ref{39d,,PyConfig} structure. It can be preinitialized with
@ref{3e2,,Py_PreInitialize()} and the @ref{99a,,PyPreConfig} structure.

There are two kinds of configuration:


@itemize *

@item 
The @ref{4c4b,,Python Configuration} can be used to build a
customized Python which behaves as the regular Python. For example,
environment variables and command line arguments are used to configure
Python.

@item 
The @ref{4c85,,Isolated Configuration} can be used to embed
Python into an application. It isolates Python from the system. For example,
environment variables are ignored, the LC_CTYPE locale is left unchanged and
no signal handler is registered.
@end itemize

The @ref{9b3,,Py_RunMain()} function can be used to write a customized Python
program.

See also @ref{4c3e,,Initialization@comma{} Finalization@comma{} and Threads}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 587
PEP 587@footnote{https://peps.python.org/pep-0587/} "Python Initialization Configuration".


@menu
* Example:: 
* PyWideStringList:: 
* PyStatus:: 
* PyPreConfig:: 
* Preinitialize Python with PyPreConfig:: 
* PyConfig:: 
* Initialization with PyConfig:: 
* Isolated Configuration:: 
* Python Configuration:: 
* Python Path Configuration:: 
* Py_GetArgcArgv(): Py_GetArgcArgv. 
* Multi-Phase Initialization Private Provisional API:: 

@end menu

@node Example,PyWideStringList,,Python Initialization Configuration
@anchor{c-api/init_config example}@anchor{4c86}
@subsection Example


Example of customized Python always running in isolated mode:

@example
int main(int argc, char **argv)
@{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config.isolated = 1;

    /* Decode command line arguments.
       Implicitly preinitialize Python (in isolated mode). */
    status = PyConfig_SetBytesArgv(&config, argc, argv);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}
    PyConfig_Clear(&config);

    return Py_RunMain();

exception:
    PyConfig_Clear(&config);
    if (PyStatus_IsExit(status)) @{
        return status.exitcode;
    @}
    /* Display the error message and exit the process with
       non-zero exit code */
    Py_ExitStatusException(status);
@}
@end example

@node PyWideStringList,PyStatus,Example,Python Initialization Configuration
@anchor{c-api/init_config pywidestringlist}@anchor{4c87}
@subsection PyWideStringList


@geindex PyWideStringList (C type)
@anchor{c-api/init_config c PyWideStringList}@anchor{99c}
@deffn {C Type} type PyWideStringList

List of @code{wchar_t*} strings.

If `length' is non-zero, `items' must be non-@code{NULL} and all strings must be
non-@code{NULL}.

Methods:

@geindex PyWideStringList_Append (C function)
@anchor{c-api/init_config c PyWideStringList_Append}@anchor{9ad}
@deffn {C Fonction} @ref{99b,,PyStatus} PyWideStringList_Append (PyWideStringList *list, const wchar_t *item)

Append `item' to `list'.

Python must be preinitialized to call this function.
@end deffn

@geindex PyWideStringList_Insert (C function)
@anchor{c-api/init_config c PyWideStringList_Insert}@anchor{9ae}
@deffn {C Fonction} @ref{99b,,PyStatus} PyWideStringList_Insert (PyWideStringList *list, Py_ssize_t index, const wchar_t *item)

Insert `item' into `list' at `index'.

If `index' is greater than or equal to `list' length, append `item' to
`list'.

`index' must be greater than or equal to @code{0}.

Python must be preinitialized to call this function.
@end deffn

Structure fields:

@geindex PyWideStringList.length (C member)
@anchor{c-api/init_config c PyWideStringList length}@anchor{4c88}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} length

List length.
@end deffn

@geindex PyWideStringList.items (C member)
@anchor{c-api/init_config c PyWideStringList items}@anchor{4c89}
@deffn {C Membre} wchar_t **items

List items.
@end deffn
@end deffn

@node PyStatus,PyPreConfig,PyWideStringList,Python Initialization Configuration
@anchor{c-api/init_config pystatus}@anchor{4c8a}
@subsection PyStatus


@geindex PyStatus (C type)
@anchor{c-api/init_config c PyStatus}@anchor{99b}
@deffn {C Type} type PyStatus

Structure to store an initialization function status: success, error
or exit.

For an error, it can store the C function name which created the error.

Structure fields:

@geindex PyStatus.exitcode (C member)
@anchor{c-api/init_config c PyStatus exitcode}@anchor{4c8b}
@deffn {C Membre} int exitcode

Exit code. Argument passed to @code{exit()}.
@end deffn

@geindex PyStatus.err_msg (C member)
@anchor{c-api/init_config c PyStatus err_msg}@anchor{4c8c}
@deffn {C Membre} const char *err_msg

Error message.
@end deffn

@geindex PyStatus.func (C member)
@anchor{c-api/init_config c PyStatus func}@anchor{4c8d}
@deffn {C Membre} const char *func

Name of the function which created an error, can be @code{NULL}.
@end deffn

Functions to create a status:

@geindex PyStatus_Ok (C function)
@anchor{c-api/init_config c PyStatus_Ok}@anchor{9ac}
@deffn {C Fonction} @ref{99b,,PyStatus} PyStatus_Ok (void)

Success.
@end deffn

@geindex PyStatus_Error (C function)
@anchor{c-api/init_config c PyStatus_Error}@anchor{9a6}
@deffn {C Fonction} @ref{99b,,PyStatus} PyStatus_Error (const char *err_msg)

Initialization error with a message.

`err_msg' must not be @code{NULL}.
@end deffn

@geindex PyStatus_NoMemory (C function)
@anchor{c-api/init_config c PyStatus_NoMemory}@anchor{9ab}
@deffn {C Fonction} @ref{99b,,PyStatus} PyStatus_NoMemory (void)

Memory allocation failure (out of memory).
@end deffn

@geindex PyStatus_Exit (C function)
@anchor{c-api/init_config c PyStatus_Exit}@anchor{9a8}
@deffn {C Fonction} @ref{99b,,PyStatus} PyStatus_Exit (int exitcode)

Exit Python with the specified exit code.
@end deffn

Functions to handle a status:

@geindex PyStatus_Exception (C function)
@anchor{c-api/init_config c PyStatus_Exception}@anchor{9a7}
@deffn {C Fonction} int PyStatus_Exception (PyStatus status)

Is the status an error or an exit? If true, the exception must be
handled; by calling @ref{9b0,,Py_ExitStatusException()} for example.
@end deffn

@geindex PyStatus_IsError (C function)
@anchor{c-api/init_config c PyStatus_IsError}@anchor{9a9}
@deffn {C Fonction} int PyStatus_IsError (PyStatus status)

Is the result an error?
@end deffn

@geindex PyStatus_IsExit (C function)
@anchor{c-api/init_config c PyStatus_IsExit}@anchor{9aa}
@deffn {C Fonction} int PyStatus_IsExit (PyStatus status)

Is the result an exit?
@end deffn

@geindex Py_ExitStatusException (C function)
@anchor{c-api/init_config c Py_ExitStatusException}@anchor{9b0}
@deffn {C Fonction} void Py_ExitStatusException (PyStatus status)

Call @code{exit(exitcode)} if `status' is an exit. Print the error
message and exit with a non-zero exit code if `status' is an error.  Must
only be called if @code{PyStatus_Exception(status)} is non-zero.
@end deffn
@end deffn

@cartouche
@quotation Note 
Internally, Python uses macros which set @code{PyStatus.func},
whereas functions to create a status set @code{func} to @code{NULL}.
@end quotation
@end cartouche

Exemple :

@example
PyStatus alloc(void **ptr, size_t size)
@{
    *ptr = PyMem_RawMalloc(size);
    if (*ptr == NULL) @{
        return PyStatus_NoMemory();
    @}
    return PyStatus_Ok();
@}

int main(int argc, char **argv)
@{
    void *ptr;
    PyStatus status = alloc(&ptr, 16);
    if (PyStatus_Exception(status)) @{
        Py_ExitStatusException(status);
    @}
    PyMem_Free(ptr);
    return 0;
@}
@end example

@node PyPreConfig,Preinitialize Python with PyPreConfig,PyStatus,Python Initialization Configuration
@anchor{c-api/init_config pypreconfig}@anchor{4c8e}
@subsection PyPreConfig


@geindex PyPreConfig (C type)
@anchor{c-api/init_config c PyPreConfig}@anchor{99a}
@deffn {C Type} type PyPreConfig

Structure used to preinitialize Python.

Function to initialize a preconfiguration:

@geindex PyPreConfig_InitPythonConfig (C function)
@anchor{c-api/init_config c PyPreConfig_InitPythonConfig}@anchor{9a5}
@deffn {C Fonction} void PyPreConfig_InitPythonConfig (PyPreConfig *preconfig)

Initialize the preconfiguration with @ref{4c4b,,Python Configuration}.
@end deffn

@geindex PyPreConfig_InitIsolatedConfig (C function)
@anchor{c-api/init_config c PyPreConfig_InitIsolatedConfig}@anchor{9a4}
@deffn {C Fonction} void PyPreConfig_InitIsolatedConfig (PyPreConfig *preconfig)

Initialize the preconfiguration with @ref{4c85,,Isolated Configuration}.
@end deffn

Structure fields:

@geindex PyPreConfig.allocator (C member)
@anchor{c-api/init_config c PyPreConfig allocator}@anchor{4c8f}
@deffn {C Membre} int allocator

Name of the Python memory allocators:


@itemize *

@item 
@code{PYMEM_ALLOCATOR_NOT_SET} (@code{0}): don't change memory allocators
(use defaults).

@item 
@code{PYMEM_ALLOCATOR_DEFAULT} (@code{1}): @ref{1cdc,,default memory allocators}.

@item 
@code{PYMEM_ALLOCATOR_DEBUG} (@code{2}): @ref{1cdc,,default memory allocators} with @ref{1cdf,,debug hooks}.

@item 
@code{PYMEM_ALLOCATOR_MALLOC} (@code{3}): use @code{malloc()} of the C library.

@item 
@code{PYMEM_ALLOCATOR_MALLOC_DEBUG} (@code{4}): force usage of
@code{malloc()} with @ref{1cdf,,debug hooks}.

@item 
@code{PYMEM_ALLOCATOR_PYMALLOC} (@code{5}): @ref{cfd,,Python pymalloc memory allocator}.

@item 
@code{PYMEM_ALLOCATOR_PYMALLOC_DEBUG} (@code{6}): @ref{cfd,,Python pymalloc memory allocator} with @ref{1cdf,,debug hooks}.

@item 
@code{PYMEM_ALLOCATOR_MIMALLOC} (@code{6}): use @code{mimalloc}, a fast
malloc replacement.

@item 
@code{PYMEM_ALLOCATOR_MIMALLOC_DEBUG} (@code{7}): use @code{mimalloc}, a fast
malloc replacement with @ref{1cdf,,debug hooks}.
@end itemize

@code{PYMEM_ALLOCATOR_PYMALLOC} and @code{PYMEM_ALLOCATOR_PYMALLOC_DEBUG} are
not supported if Python is @ref{1d3a,,configured using --without-pymalloc}.

@code{PYMEM_ALLOCATOR_MIMALLOC} and @code{PYMEM_ALLOCATOR_MIMALLOC_DEBUG} are
not supported if Python is @ref{1d39,,configured using --without-mimalloc} or if the underlying atomic support isn't
available.

See @ref{4c90,,Memory Management}.

Default: @code{PYMEM_ALLOCATOR_NOT_SET}.
@end deffn

@geindex PyPreConfig.configure_locale (C member)
@anchor{c-api/init_config c PyPreConfig configure_locale}@anchor{4c91}
@deffn {C Membre} int configure_locale

Set the LC_CTYPE locale to the user preferred locale.

If equals to @code{0}, set @ref{4c92,,coerce_c_locale} and
@ref{4c93,,coerce_c_locale_warn} members to @code{0}.

See the @ref{23f,,locale encoding}.

Default: @code{1} in Python config, @code{0} in isolated config.
@end deffn

@geindex PyPreConfig.coerce_c_locale (C member)
@anchor{c-api/init_config c PyPreConfig coerce_c_locale}@anchor{4c92}
@deffn {C Membre} int coerce_c_locale

If equals to @code{2}, coerce the C locale.

If equals to @code{1}, read the LC_CTYPE locale to decide if it should be
coerced.

See the @ref{23f,,locale encoding}.

Default: @code{-1} in Python config, @code{0} in isolated config.
@end deffn

@geindex PyPreConfig.coerce_c_locale_warn (C member)
@anchor{c-api/init_config c PyPreConfig coerce_c_locale_warn}@anchor{4c93}
@deffn {C Membre} int coerce_c_locale_warn

If non-zero, emit a warning if the C locale is coerced.

Default: @code{-1} in Python config, @code{0} in isolated config.
@end deffn

@geindex PyPreConfig.dev_mode (C member)
@anchor{c-api/init_config c PyPreConfig dev_mode}@anchor{4c94}
@deffn {C Membre} int dev_mode

@ref{1f5,,Python Development Mode}: see
@ref{4c95,,PyConfig.dev_mode}.

Default: @code{-1} in Python mode, @code{0} in isolated mode.
@end deffn

@geindex PyPreConfig.isolated (C member)
@anchor{c-api/init_config c PyPreConfig isolated}@anchor{4c96}
@deffn {C Membre} int isolated

Isolated mode: see @ref{3db,,PyConfig.isolated}.

Default: @code{0} in Python mode, @code{1} in isolated mode.
@end deffn

@geindex PyPreConfig.legacy_windows_fs_encoding (C member)
@anchor{c-api/init_config c PyPreConfig legacy_windows_fs_encoding}@anchor{3dd}
@deffn {C Membre} int legacy_windows_fs_encoding

If non-zero:


@itemize *

@item 
Set @ref{3e1,,PyPreConfig.utf8_mode} to @code{0},

@item 
Set @ref{3df,,PyConfig.filesystem_encoding} to @code{"mbcs"},

@item 
Set @ref{3e0,,PyConfig.filesystem_errors} to @code{"replace"}.
@end itemize

Initialized from the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} environment
variable value.

Only available on Windows. @code{#ifdef MS_WINDOWS} macro can be used for
Windows specific code.

Default: @code{0}.
@end deffn

@geindex PyPreConfig.parse_argv (C member)
@anchor{c-api/init_config c PyPreConfig parse_argv}@anchor{4c97}
@deffn {C Membre} int parse_argv

If non-zero, @ref{9b1,,Py_PreInitializeFromArgs()} and
@ref{9b2,,Py_PreInitializeFromBytesArgs()} parse their @code{argv} argument the
same way the regular Python parses command line arguments: see
@ref{ff0,,Command Line Arguments}.

Default: @code{1} in Python config, @code{0} in isolated config.
@end deffn

@geindex PyPreConfig.use_environment (C member)
@anchor{c-api/init_config c PyPreConfig use_environment}@anchor{4c98}
@deffn {C Membre} int use_environment

Use @ref{5db,,environment variables}? See
@ref{3d0,,PyConfig.use_environment}.

Default: @code{1} in Python config and @code{0} in isolated config.
@end deffn

@geindex PyPreConfig.utf8_mode (C member)
@anchor{c-api/init_config c PyPreConfig utf8_mode}@anchor{3e1}
@deffn {C Membre} int utf8_mode

If non-zero, enable the @ref{641,,Python UTF-8 Mode}.

Set to @code{0} or @code{1} by the @ref{175,,-X utf8} command line option
and the 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8} environment variable.

Also set to @code{1} if the @code{LC_CTYPE} locale is @code{C} or @code{POSIX}.

Default: @code{-1} in Python config and @code{0} in isolated config.
@end deffn
@end deffn

@node Preinitialize Python with PyPreConfig,PyConfig,PyPreConfig,Python Initialization Configuration
@anchor{c-api/init_config c-preinit}@anchor{3c7c}@anchor{c-api/init_config preinitialize-python-with-pypreconfig}@anchor{4c99}
@subsection Preinitialize Python with PyPreConfig


The preinitialization of Python:


@itemize *

@item 
Set the Python memory allocators (@ref{4c8f,,PyPreConfig.allocator})

@item 
Configure the LC_CTYPE locale (@ref{23f,,locale encoding})

@item 
Set the @ref{641,,Python UTF-8 Mode}
(@ref{3e1,,PyPreConfig.utf8_mode})
@end itemize

The current preconfiguration (@code{PyPreConfig} type) is stored in
@code{_PyRuntime.preconfig}.

Functions to preinitialize Python:

@geindex Py_PreInitialize (C function)
@anchor{c-api/init_config c Py_PreInitialize}@anchor{3e2}
@deffn {C Fonction} @ref{99b,,PyStatus} Py_PreInitialize (const PyPreConfig *preconfig)

Preinitialize Python from `preconfig' preconfiguration.

`preconfig' must not be @code{NULL}.
@end deffn

@geindex Py_PreInitializeFromBytesArgs (C function)
@anchor{c-api/init_config c Py_PreInitializeFromBytesArgs}@anchor{9b2}
@deffn {C Fonction} @ref{99b,,PyStatus} Py_PreInitializeFromBytesArgs (const PyPreConfig *preconfig, int argc, char *const *argv)

Preinitialize Python from `preconfig' preconfiguration.

Parse `argv' command line arguments (bytes strings) if
@ref{4c97,,parse_argv} of `preconfig' is non-zero.

`preconfig' must not be @code{NULL}.
@end deffn

@geindex Py_PreInitializeFromArgs (C function)
@anchor{c-api/init_config c Py_PreInitializeFromArgs}@anchor{9b1}
@deffn {C Fonction} @ref{99b,,PyStatus} Py_PreInitializeFromArgs (const PyPreConfig *preconfig, int argc, wchar_t *const *argv)

Preinitialize Python from `preconfig' preconfiguration.

Parse `argv' command line arguments (wide strings) if
@ref{4c97,,parse_argv} of `preconfig' is non-zero.

`preconfig' must not be @code{NULL}.
@end deffn

The caller is responsible to handle exceptions (error or exit) using
@ref{9a7,,PyStatus_Exception()} and @ref{9b0,,Py_ExitStatusException()}.

For @ref{4c4b,,Python Configuration}
(@ref{9a5,,PyPreConfig_InitPythonConfig()}), if Python is initialized with
command line arguments, the command line arguments must also be passed to
preinitialize Python, since they have an effect on the pre-configuration
like encodings. For example, the @ref{175,,-X utf8} command line option
enables the @ref{641,,Python UTF-8 Mode}.

@code{PyMem_SetAllocator()} can be called after @ref{3e2,,Py_PreInitialize()} and
before @ref{3bc,,Py_InitializeFromConfig()} to install a custom memory allocator.
It can be called before @ref{3e2,,Py_PreInitialize()} if
@ref{4c8f,,PyPreConfig.allocator} is set to @code{PYMEM_ALLOCATOR_NOT_SET}.

Python memory allocation functions like @ref{386,,PyMem_RawMalloc()} must not be
used before the Python preinitialization, whereas calling directly @code{malloc()}
and @code{free()} is always safe. @ref{bb5,,Py_DecodeLocale()} must not be called
before the Python preinitialization.

Example using the preinitialization to enable
the @ref{641,,Python UTF-8 Mode}:

@example
PyStatus status;
PyPreConfig preconfig;
PyPreConfig_InitPythonConfig(&preconfig);

preconfig.utf8_mode = 1;

status = Py_PreInitialize(&preconfig);
if (PyStatus_Exception(status)) @{
    Py_ExitStatusException(status);
@}

/* at this point, Python speaks UTF-8 */

Py_Initialize();
/* ... use Python API here ... */
Py_Finalize();
@end example

@node PyConfig,Initialization with PyConfig,Preinitialize Python with PyPreConfig,Python Initialization Configuration
@anchor{c-api/init_config pyconfig}@anchor{4c9a}
@subsection PyConfig


@geindex PyConfig (C type)
@anchor{c-api/init_config c PyConfig}@anchor{39d}
@deffn {C Type} type PyConfig

Structure containing most parameters to configure Python.

When done, the @ref{99d,,PyConfig_Clear()} function must be used to release the
configuration memory.

Structure methods:

@geindex PyConfig_InitPythonConfig (C function)
@anchor{c-api/init_config c PyConfig_InitPythonConfig}@anchor{99f}
@deffn {C Fonction} void PyConfig_InitPythonConfig (PyConfig *config)

Initialize configuration with the @ref{4c4b,,Python Configuration}.
@end deffn

@geindex PyConfig_InitIsolatedConfig (C function)
@anchor{c-api/init_config c PyConfig_InitIsolatedConfig}@anchor{99e}
@deffn {C Fonction} void PyConfig_InitIsolatedConfig (PyConfig *config)

Initialize configuration with the @ref{4c85,,Isolated Configuration}.
@end deffn

@geindex PyConfig_SetString (C function)
@anchor{c-api/init_config c PyConfig_SetString}@anchor{9a3}
@deffn {C Fonction} @ref{99b,,PyStatus} PyConfig_SetString (PyConfig *config, wchar_t *const *config_str, const wchar_t *str)

Copy the wide character string `str' into @code{*config_str}.

@ref{3c7c,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetBytesString (C function)
@anchor{c-api/init_config c PyConfig_SetBytesString}@anchor{9a2}
@deffn {C Fonction} @ref{99b,,PyStatus} PyConfig_SetBytesString (PyConfig *config, wchar_t *const *config_str, const char *str)

Decode `str' using @ref{bb5,,Py_DecodeLocale()} and set the result into
@code{*config_str}.

@ref{3c7c,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetArgv (C function)
@anchor{c-api/init_config c PyConfig_SetArgv}@anchor{9a0}
@deffn {C Fonction} @ref{99b,,PyStatus} PyConfig_SetArgv (PyConfig *config, int argc, wchar_t *const *argv)

Set command line arguments (@ref{3ba,,argv} member of
`config') from the `argv' list of wide character strings.

@ref{3c7c,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetBytesArgv (C function)
@anchor{c-api/init_config c PyConfig_SetBytesArgv}@anchor{9a1}
@deffn {C Fonction} @ref{99b,,PyStatus} PyConfig_SetBytesArgv (PyConfig *config, int argc, char *const *argv)

Set command line arguments (@ref{3ba,,argv} member of
`config') from the `argv' list of bytes strings. Decode bytes using
@ref{bb5,,Py_DecodeLocale()}.

@ref{3c7c,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_SetWideStringList (C function)
@anchor{c-api/init_config c PyConfig_SetWideStringList}@anchor{1973}
@deffn {C Fonction} @ref{99b,,PyStatus} PyConfig_SetWideStringList (PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)

Set the list of wide strings `list' to `length' and `items'.

@ref{3c7c,,Preinitialize Python} if needed.
@end deffn

@geindex PyConfig_Read (C function)
@anchor{c-api/init_config c PyConfig_Read}@anchor{77a}
@deffn {C Fonction} @ref{99b,,PyStatus} PyConfig_Read (PyConfig *config)

Read all Python configuration.

Fields which are already initialized are left unchanged.

Fields for @ref{89a,,path configuration} are no longer
calculated or modified when calling this function, as of Python 3.11.

The @ref{77a,,PyConfig_Read()} function only parses
@ref{3ba,,PyConfig.argv} arguments once: @ref{18b6,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
stripped from @ref{3ba,,PyConfig.argv}, parsing arguments twice would
parse the application options as Python options.

@ref{3c7c,,Preinitialize Python} if needed.


Modifié dans la version 3.10: The @ref{3ba,,PyConfig.argv} arguments are now only parsed once,
@ref{18b6,,PyConfig.parse_argv} is set to @code{2} after arguments are
parsed, and arguments are only parsed if
@ref{18b6,,PyConfig.parse_argv} equals @code{1}.



Modifié dans la version 3.11: @ref{77a,,PyConfig_Read()} no longer calculates all paths, and so fields
listed under @ref{89a,,Python Path Configuration} may
no longer be updated until @ref{3bc,,Py_InitializeFromConfig()} is
called.

@end deffn

@geindex PyConfig_Clear (C function)
@anchor{c-api/init_config c PyConfig_Clear}@anchor{99d}
@deffn {C Fonction} void PyConfig_Clear (PyConfig *config)

Release configuration memory.
@end deffn

Most @code{PyConfig} methods @ref{3c7c,,preinitialize Python} if needed.
In that case, the Python preinitialization configuration
(@ref{99a,,PyPreConfig}) in based on the @ref{39d,,PyConfig}. If configuration
fields which are in common with @ref{99a,,PyPreConfig} are tuned, they must
be set before calling a @ref{39d,,PyConfig} method:


@itemize *

@item 
@ref{4c95,,PyConfig.dev_mode}

@item 
@ref{3db,,PyConfig.isolated}

@item 
@ref{18b6,,PyConfig.parse_argv}

@item 
@ref{3d0,,PyConfig.use_environment}
@end itemize

Moreover, if @ref{9a0,,PyConfig_SetArgv()} or @ref{9a1,,PyConfig_SetBytesArgv()}
is used, this method must be called before other methods, since the
preinitialization configuration depends on command line arguments (if
@ref{18b6,,parse_argv} is non-zero).

The caller of these methods is responsible to handle exceptions (error or
exit) using @code{PyStatus_Exception()} and @code{Py_ExitStatusException()}.

Structure fields:

@geindex PyConfig.argv (C member)
@anchor{c-api/init_config c PyConfig argv}@anchor{3ba}
@deffn {C Membre} @ref{99c,,PyWideStringList} argv

@geindex main()
@geindex argv (in module sys)

Set @ref{1243,,sys.argv} command line arguments based on
@ref{3ba,,argv}.  These parameters are similar to those passed
to the program's @code{main()} function with the difference that the
first entry should refer to the script file to be executed rather than
the executable hosting the Python interpreter.  If there isn't a script
that will be run, the first entry in @ref{3ba,,argv} can be an
empty string.

Set @ref{18b6,,parse_argv} to @code{1} to parse
@ref{3ba,,argv} the same way the regular Python parses Python
command line arguments and then to strip Python arguments from
@ref{3ba,,argv}.

If @ref{3ba,,argv} is empty, an empty string is added to
ensure that @ref{1243,,sys.argv} always exists and is never empty.

Default: @code{NULL}.

See also the @ref{880,,orig_argv} member.
@end deffn

@geindex PyConfig.safe_path (C member)
@anchor{c-api/init_config c PyConfig safe_path}@anchor{75d}
@deffn {C Membre} int safe_path

If equals to zero, @code{Py_RunMain()} prepends a potentially unsafe path to
@ref{3ab,,sys.path} at startup:


@itemize *

@item 
If @ref{3ba,,argv[0]} is equal to @code{L"-m"}
(@code{python -m module}), prepend the current working directory.

@item 
If running a script (@code{python script.py}), prepend the script's
directory.  If it's a symbolic link, resolve symbolic links.

@item 
Otherwise (@code{python -c code} and @code{python}), prepend an empty string,
which means the current working directory.
@end itemize

Set to @code{1} by the @ref{58e,,-P} command line option and the
@geindex PYTHONSAFEPATH
@geindex variable d'environnement; PYTHONSAFEPATH
@ref{58f,,PYTHONSAFEPATH} environment variable.

Default: @code{0} in Python config, @code{1} in isolated config.


Ajouté dans la version 3.11.

@end deffn

@geindex PyConfig.base_exec_prefix (C member)
@anchor{c-api/init_config c PyConfig base_exec_prefix}@anchor{4c9b}
@deffn {C Membre} wchar_t *base_exec_prefix

@ref{3e5,,sys.base_exec_prefix}.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} output.

See also @ref{4c9c,,PyConfig.exec_prefix}.
@end deffn

@geindex PyConfig.base_executable (C member)
@anchor{c-api/init_config c PyConfig base_executable}@anchor{4c9d}
@deffn {C Membre} wchar_t *base_executable

Python base executable: @code{sys._base_executable}.

Set by the 
@geindex __PYVENV_LAUNCHER__
@geindex variable d'environnement; __PYVENV_LAUNCHER__
@code{__PYVENV_LAUNCHER__} environment variable.

Set from @ref{39c,,PyConfig.executable} if @code{NULL}.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} output.

See also @ref{39c,,PyConfig.executable}.
@end deffn

@geindex PyConfig.base_prefix (C member)
@anchor{c-api/init_config c PyConfig base_prefix}@anchor{4c9e}
@deffn {C Membre} wchar_t *base_prefix

@ref{3e6,,sys.base_prefix}.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} output.

See also @ref{4c9f,,PyConfig.prefix}.
@end deffn

@geindex PyConfig.buffered_stdio (C member)
@anchor{c-api/init_config c PyConfig buffered_stdio}@anchor{3d6}
@deffn {C Membre} int buffered_stdio

If equals to @code{0} and @ref{4ca0,,configure_c_stdio} is non-zero,
disable buffering on the C streams stdout and stderr.

Set to @code{0} by the @ref{1932,,-u} command line option and the
@geindex PYTHONUNBUFFERED
@geindex variable d'environnement; PYTHONUNBUFFERED
@ref{1933,,PYTHONUNBUFFERED} environment variable.

stdin is always opened in buffered mode.

Default: @code{1}.
@end deffn

@geindex PyConfig.bytes_warning (C member)
@anchor{c-api/init_config c PyConfig bytes_warning}@anchor{3cc}
@deffn {C Membre} int bytes_warning

If equals to @code{1}, issue a warning when comparing @ref{1bd,,bytes} or
@ref{528,,bytearray} with @ref{435,,str}, or comparing @ref{1bd,,bytes} with
@ref{254,,int}.

If equal or greater to @code{2}, raise a @ref{c11,,BytesWarning} exception in these
cases.

Incremented by the @ref{5cd,,-b} command line option.

Default: @code{0}.
@end deffn

@geindex PyConfig.warn_default_encoding (C member)
@anchor{c-api/init_config c PyConfig warn_default_encoding}@anchor{4ca1}
@deffn {C Membre} int warn_default_encoding

If non-zero, emit a @ref{1cc9,,EncodingWarning} warning when @ref{7a5,,io.TextIOWrapper}
uses its default encoding. See @ref{1ce1,,Opt-in EncodingWarning} for details.

Default: @code{0}.


Ajouté dans la version 3.10.

@end deffn

@geindex PyConfig.code_debug_ranges (C member)
@anchor{c-api/init_config c PyConfig code_debug_ranges}@anchor{4ca2}
@deffn {C Membre} int code_debug_ranges

If equals to @code{0}, disables the inclusion of the end line and column
mappings in code objects. Also disables traceback printing carets to
specific error locations.

Set to @code{0} by the 
@geindex PYTHONNODEBUGRANGES
@geindex variable d'environnement; PYTHONNODEBUGRANGES
@ref{5a0,,PYTHONNODEBUGRANGES} environment variable
and by the @ref{175,,-X no_debug_ranges} command line option.

Default: @code{1}.


Ajouté dans la version 3.11.

@end deffn

@geindex PyConfig.check_hash_pycs_mode (C member)
@anchor{c-api/init_config c PyConfig check_hash_pycs_mode}@anchor{4ca3}
@deffn {C Membre} wchar_t *check_hash_pycs_mode

Control the validation behavior of hash-based @code{.pyc} files:
value of the @ref{1cbc,,--check-hash-based-pycs} command line option.

Valid values:


@itemize -

@item 
@code{L"always"}: Hash the source file for invalidation regardless of
value of the 'check_source' flag.

@item 
@code{L"never"}: Assume that hash-based pycs always are valid.

@item 
@code{L"default"}: The 'check_source' flag in hash-based pycs
determines invalidation.
@end itemize

Default: @code{L"default"}.

See also 
@geindex Python Enhancement Proposals; PEP 552
PEP 552@footnote{https://peps.python.org/pep-0552/} "Deterministic pycs".
@end deffn

@geindex PyConfig.configure_c_stdio (C member)
@anchor{c-api/init_config c PyConfig configure_c_stdio}@anchor{4ca0}
@deffn {C Membre} int configure_c_stdio

If non-zero, configure C standard streams:


@itemize *

@item 
On Windows, set the binary mode (@code{O_BINARY}) on stdin, stdout and
stderr.

@item 
If @ref{3d6,,buffered_stdio} equals zero, disable buffering
of stdin, stdout and stderr streams.

@item 
If @ref{3c4,,interactive} is non-zero, enable stream
buffering on stdin and stdout (only stdout on Windows).
@end itemize

Default: @code{1} in Python config, @code{0} in isolated config.
@end deffn

@geindex PyConfig.dev_mode (C member)
@anchor{c-api/init_config c PyConfig dev_mode}@anchor{4c95}
@deffn {C Membre} int dev_mode

If non-zero, enable the @ref{1f5,,Python Development Mode}.

Set to @code{1} by the @ref{175,,-X dev} option and the
@geindex PYTHONDEVMODE
@geindex variable d'environnement; PYTHONDEVMODE
@ref{adb,,PYTHONDEVMODE} environment variable.

Default: @code{-1} in Python mode, @code{0} in isolated mode.
@end deffn

@geindex PyConfig.dump_refs (C member)
@anchor{c-api/init_config c PyConfig dump_refs}@anchor{4ca4}
@deffn {C Membre} int dump_refs

Dump Python references?

If non-zero, dump all objects which are still alive at exit.

Set to @code{1} by the 
@geindex PYTHONDUMPREFS
@geindex variable d'environnement; PYTHONDUMPREFS
@ref{994,,PYTHONDUMPREFS} environment variable.

Needs a special build of Python with the @code{Py_TRACE_REFS} macro defined:
see the @ref{38b,,configure --with-trace-refs option}.

Default: @code{0}.
@end deffn

@geindex PyConfig.exec_prefix (C member)
@anchor{c-api/init_config c PyConfig exec_prefix}@anchor{4c9c}
@deffn {C Membre} wchar_t *exec_prefix

The site-specific directory prefix where the platform-dependent Python
files are installed: @ref{3a9,,sys.exec_prefix}.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} output.

See also @ref{4c9b,,PyConfig.base_exec_prefix}.
@end deffn

@geindex PyConfig.executable (C member)
@anchor{c-api/init_config c PyConfig executable}@anchor{39c}
@deffn {C Membre} wchar_t *executable

The absolute path of the executable binary for the Python interpreter:
@ref{3af,,sys.executable}.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} output.

See also @ref{4c9d,,PyConfig.base_executable}.
@end deffn

@geindex PyConfig.faulthandler (C member)
@anchor{c-api/init_config c PyConfig faulthandler}@anchor{4ca5}
@deffn {C Membre} int faulthandler

Enable faulthandler?

If non-zero, call @ref{c8c,,faulthandler.enable()} at startup.

Set to @code{1} by @ref{175,,-X faulthandler} and the
@geindex PYTHONFAULTHANDLER
@geindex variable d'environnement; PYTHONFAULTHANDLER
@ref{1069,,PYTHONFAULTHANDLER} environment variable.

Default: @code{-1} in Python mode, @code{0} in isolated mode.
@end deffn

@geindex PyConfig.filesystem_encoding (C member)
@anchor{c-api/init_config c PyConfig filesystem_encoding}@anchor{3df}
@deffn {C Membre} wchar_t *filesystem_encoding

@ref{525,,Filesystem encoding}:
@ref{c47,,sys.getfilesystemencoding()}.

On macOS, Android and VxWorks: use @code{"utf-8"} by default.

On Windows: use @code{"utf-8"} by default, or @code{"mbcs"} if
@ref{3dd,,legacy_windows_fs_encoding} of
@ref{99a,,PyPreConfig} is non-zero.

Default encoding on other platforms:


@itemize *

@item 
@code{"utf-8"} if @ref{3e1,,PyPreConfig.utf8_mode} is non-zero.

@item 
@code{"ascii"} if Python detects that @code{nl_langinfo(CODESET)} announces
the ASCII encoding, whereas the @code{mbstowcs()} function
decodes from a different encoding (usually Latin1).

@item 
@code{"utf-8"} if @code{nl_langinfo(CODESET)} returns an empty string.

@item 
Otherwise, use the @ref{23f,,locale encoding}:
@code{nl_langinfo(CODESET)} result.
@end itemize

At Python startup, the encoding name is normalized to the Python codec
name. For example, @code{"ANSI_X3.4-1968"} is replaced with @code{"ascii"}.

See also the @ref{3e0,,filesystem_errors} member.
@end deffn

@geindex PyConfig.filesystem_errors (C member)
@anchor{c-api/init_config c PyConfig filesystem_errors}@anchor{3e0}
@deffn {C Membre} wchar_t *filesystem_errors

@ref{525,,Filesystem error handler}:
@ref{cd4,,sys.getfilesystemencodeerrors()}.

On Windows: use @code{"surrogatepass"} by default, or @code{"replace"}  if
@ref{3dd,,legacy_windows_fs_encoding} of
@ref{99a,,PyPreConfig} is non-zero.

On other platforms: use @code{"surrogateescape"} by default.

Supported error handlers:


@itemize *

@item 
@code{"strict"}

@item 
@code{"surrogateescape"}

@item 
@code{"surrogatepass"} (only supported with the UTF-8 encoding)
@end itemize

See also the @ref{3df,,filesystem_encoding} member.
@end deffn

@geindex PyConfig.hash_seed (C member)
@anchor{c-api/init_config c PyConfig hash_seed}@anchor{3d9}
@deffn {C Membre} unsigned long hash_seed
@end deffn

@geindex PyConfig.use_hash_seed (C member)
@anchor{c-api/init_config c PyConfig use_hash_seed}@anchor{3d8}
@deffn {C Membre} int use_hash_seed

Randomized hash function seed.

If @ref{3d8,,use_hash_seed} is zero, a seed is chosen randomly
at Python startup, and @ref{3d9,,hash_seed} is ignored.

Set by the 
@geindex PYTHONHASHSEED
@geindex variable d'environnement; PYTHONHASHSEED
@ref{1066,,PYTHONHASHSEED} environment variable.

Default `use_hash_seed' value: @code{-1} in Python mode, @code{0} in isolated
mode.
@end deffn

@geindex PyConfig.home (C member)
@anchor{c-api/init_config c PyConfig home}@anchor{3b2}
@deffn {C Membre} wchar_t *home

Set the default Python "home" directory, that is, the location of the
standard Python libraries (see 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME}).

Set by the 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment variable.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.import_time (C member)
@anchor{c-api/init_config c PyConfig import_time}@anchor{4ca6}
@deffn {C Membre} int import_time

If non-zero, profile import time.

Set the @code{1} by the @ref{175,,-X importtime} option and the
@geindex PYTHONPROFILEIMPORTTIME
@geindex variable d'environnement; PYTHONPROFILEIMPORTTIME
@ref{ae3,,PYTHONPROFILEIMPORTTIME} environment variable.

Default: @code{0}.
@end deffn

@geindex PyConfig.inspect (C member)
@anchor{c-api/init_config c PyConfig inspect}@anchor{3c6}
@deffn {C Membre} int inspect

Enter interactive mode after executing a script or a command.

If greater than @code{0}, enable inspect: when a script is passed as first
argument or the -c option is used, enter interactive mode after executing
the script or the command, even when @ref{527,,sys.stdin} does not appear to
be a terminal.

Incremented by the @ref{1491,,-i} command line option. Set to @code{1} if the
@geindex PYTHONINSPECT
@geindex variable d'environnement; PYTHONINSPECT
@ref{1490,,PYTHONINSPECT} environment variable is non-empty.

Default: @code{0}.
@end deffn

@geindex PyConfig.install_signal_handlers (C member)
@anchor{c-api/init_config c PyConfig install_signal_handlers}@anchor{8ab}
@deffn {C Membre} int install_signal_handlers

Install Python signal handlers?

Default: @code{1} in Python mode, @code{0} in isolated mode.
@end deffn

@geindex PyConfig.interactive (C member)
@anchor{c-api/init_config c PyConfig interactive}@anchor{3c4}
@deffn {C Membre} int interactive

If greater than @code{0}, enable the interactive mode (REPL).

Incremented by the @ref{1491,,-i} command line option.

Default: @code{0}.
@end deffn

@geindex PyConfig.int_max_str_digits (C member)
@anchor{c-api/init_config c PyConfig int_max_str_digits}@anchor{4ca7}
@deffn {C Membre} int int_max_str_digits

Configures the @ref{5df,,integer string conversion length limitation}.  An initial value of @code{-1} means the value will
be taken from the command line or environment or otherwise default to
4300 (@ref{2204,,sys.int_info.default_max_str_digits}).  A value of @code{0}
disables the limitation.  Values greater than zero but less than 640
(@ref{42b8,,sys.int_info.str_digits_check_threshold}) are unsupported and
will produce an error.

Configured by the @ref{175,,-X int_max_str_digits} command line
flag or the 
@geindex PYTHONINTMAXSTRDIGITS
@geindex variable d'environnement; PYTHONINTMAXSTRDIGITS
@ref{174b,,PYTHONINTMAXSTRDIGITS} environment variable.

Default: @code{-1} in Python mode.  4300
(@ref{2204,,sys.int_info.default_max_str_digits}) in isolated mode.


Ajouté dans la version 3.12.

@end deffn

@geindex PyConfig.cpu_count (C member)
@anchor{c-api/init_config c PyConfig cpu_count}@anchor{4ca8}
@deffn {C Membre} int cpu_count

If the value of @ref{4ca8,,cpu_count} is not @code{-1} then it will
override the return values of @ref{1c0,,os.cpu_count()},
@ref{1bf,,os.process_cpu_count()}, and @ref{f5a,,multiprocessing.cpu_count()}.

Configured by the @code{-X cpu_count=@var{n|default}} command line
flag or the 
@geindex PYTHON_CPU_COUNT
@geindex variable d'environnement; PYTHON_CPU_COUNT
@ref{20d,,PYTHON_CPU_COUNT} environment variable.

Default: @code{-1}.


Ajouté dans la version 3.13.

@end deffn

@geindex PyConfig.isolated (C member)
@anchor{c-api/init_config c PyConfig isolated}@anchor{3db}
@deffn {C Membre} int isolated

If greater than @code{0}, enable isolated mode:


@itemize *

@item 
Set @ref{75d,,safe_path} to @code{1}:
don't prepend a potentially unsafe path to @ref{3ab,,sys.path} at Python
startup, such as the current directory, the script's directory or an
empty string.

@item 
Set @ref{3d0,,use_environment} to @code{0}: ignore @code{PYTHON}
environment variables.

@item 
Set @ref{3d4,,user_site_directory} to @code{0}: don't add the user
site directory to @ref{3ab,,sys.path}.

@item 
Python REPL doesn't import @ref{b9,,readline} nor enable default readline
configuration on interactive prompts.
@end itemize

Set to @code{1} by the @ref{94b,,-I} command line option.

Default: @code{0} in Python mode, @code{1} in isolated mode.

See also the @ref{4c85,,Isolated Configuration} and
@ref{4c96,,PyPreConfig.isolated}.
@end deffn

@geindex PyConfig.legacy_windows_stdio (C member)
@anchor{c-api/init_config c PyConfig legacy_windows_stdio}@anchor{39b}
@deffn {C Membre} int legacy_windows_stdio

If non-zero, use @ref{12ee,,io.FileIO} instead of
@code{io._WindowsConsoleIO} for @ref{527,,sys.stdin}, @ref{ac4,,sys.stdout}
and @ref{926,,sys.stderr}.

Set to @code{1} if the 
@geindex PYTHONLEGACYWINDOWSSTDIO
@geindex variable d'environnement; PYTHONLEGACYWINDOWSSTDIO
@ref{c49,,PYTHONLEGACYWINDOWSSTDIO} environment
variable is set to a non-empty string.

Only available on Windows. @code{#ifdef MS_WINDOWS} macro can be used for
Windows specific code.

Default: @code{0}.

See also the 
@geindex Python Enhancement Proposals; PEP 528
PEP 528@footnote{https://peps.python.org/pep-0528/} (Change Windows console encoding to UTF-8).
@end deffn

@geindex PyConfig.malloc_stats (C member)
@anchor{c-api/init_config c PyConfig malloc_stats}@anchor{4ca9}
@deffn {C Membre} int malloc_stats

If non-zero, dump statistics on @ref{cfd,,Python pymalloc memory allocator} at exit.

Set to @code{1} by the 
@geindex PYTHONMALLOCSTATS
@geindex variable d'environnement; PYTHONMALLOCSTATS
@ref{1ae4,,PYTHONMALLOCSTATS} environment variable.

The option is ignored if Python is @ref{1d3a,,configured using the --without-pymalloc option}.

Default: @code{0}.
@end deffn

@geindex PyConfig.platlibdir (C member)
@anchor{c-api/init_config c PyConfig platlibdir}@anchor{18cb}
@deffn {C Membre} wchar_t *platlibdir

Platform library directory name: @ref{925,,sys.platlibdir}.

Set by the 
@geindex PYTHONPLATLIBDIR
@geindex variable d'environnement; PYTHONPLATLIBDIR
@ref{18cd,,PYTHONPLATLIBDIR} environment variable.

Default: value of the @code{PLATLIBDIR} macro which is set by the
@ref{1d02,,configure --with-platlibdir option}
(default: @code{"lib"}, or @code{"DLLs"} on Windows).

Part of the @ref{89a,,Python Path Configuration} input.


Ajouté dans la version 3.9.



Modifié dans la version 3.11: This macro is now used on Windows to locate the standard
library extension modules, typically under @code{DLLs}. However,
for compatibility, note that this value is ignored for any
non-standard layouts, including in-tree builds and virtual
environments.

@end deffn

@geindex PyConfig.pythonpath_env (C member)
@anchor{c-api/init_config c PyConfig pythonpath_env}@anchor{4caa}
@deffn {C Membre} wchar_t *pythonpath_env

Module search paths (@ref{3ab,,sys.path}) as a string separated by @code{DELIM}
(@ref{1cd0,,os.pathsep}).

Set by the 
@geindex PYTHONPATH
@geindex variable d'environnement; PYTHONPATH
@ref{1006,,PYTHONPATH} environment variable.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.module_search_paths (C member)
@anchor{c-api/init_config c PyConfig module_search_paths}@anchor{399}
@deffn {C Membre} @ref{99c,,PyWideStringList} module_search_paths
@end deffn

@geindex PyConfig.module_search_paths_set (C member)
@anchor{c-api/init_config c PyConfig module_search_paths_set}@anchor{5d9}
@deffn {C Membre} int module_search_paths_set

Module search paths: @ref{3ab,,sys.path}.

If @ref{5d9,,module_search_paths_set} is equal to @code{0},
@ref{3bc,,Py_InitializeFromConfig()} will replace
@ref{399,,module_search_paths} and sets
@ref{5d9,,module_search_paths_set} to @code{1}.

Default: empty list (@code{module_search_paths}) and @code{0}
(@code{module_search_paths_set}).

Part of the @ref{89a,,Python Path Configuration} output.
@end deffn

@geindex PyConfig.optimization_level (C member)
@anchor{c-api/init_config c PyConfig optimization_level}@anchor{3c8}
@deffn {C Membre} int optimization_level

Compilation optimization level:


@itemize *

@item 
@code{0}: Peephole optimizer, set @code{__debug__} to @code{True}.

@item 
@code{1}: Level 0, remove assertions, set @code{__debug__} to @code{False}.

@item 
@code{2}: Level 1, strip docstrings.
@end itemize

Incremented by the @ref{da2,,-O} command line option. Set to the
@geindex PYTHONOPTIMIZE
@geindex variable d'environnement; PYTHONOPTIMIZE
@ref{1cbf,,PYTHONOPTIMIZE} environment variable value.

Default: @code{0}.
@end deffn

@geindex PyConfig.orig_argv (C member)
@anchor{c-api/init_config c PyConfig orig_argv}@anchor{880}
@deffn {C Membre} @ref{99c,,PyWideStringList} orig_argv

The list of the original command line arguments passed to the Python
executable: @ref{82a,,sys.orig_argv}.

If @ref{880,,orig_argv} list is empty and
@ref{3ba,,argv} is not a list only containing an empty
string, @ref{77a,,PyConfig_Read()} copies @ref{3ba,,argv} into
@ref{880,,orig_argv} before modifying
@ref{3ba,,argv} (if @ref{18b6,,parse_argv} is
non-zero).

See also the @ref{3ba,,argv} member and the
@ref{18e3,,Py_GetArgcArgv()} function.

Default: empty list.


Ajouté dans la version 3.10.

@end deffn

@geindex PyConfig.parse_argv (C member)
@anchor{c-api/init_config c PyConfig parse_argv}@anchor{18b6}
@deffn {C Membre} int parse_argv

Parse command line arguments?

If equals to @code{1}, parse @ref{3ba,,argv} the same way the regular
Python parses @ref{ff0,,command line arguments}, and strip
Python arguments from @ref{3ba,,argv}.

The @ref{77a,,PyConfig_Read()} function only parses
@ref{3ba,,PyConfig.argv} arguments once: @ref{18b6,,PyConfig.parse_argv}
is set to @code{2} after arguments are parsed. Since Python arguments are
stripped from @ref{3ba,,PyConfig.argv}, parsing arguments twice would
parse the application options as Python options.

Default: @code{1} in Python mode, @code{0} in isolated mode.


Modifié dans la version 3.10: The @ref{3ba,,PyConfig.argv} arguments are now only parsed if
@ref{18b6,,PyConfig.parse_argv} equals to @code{1}.

@end deffn

@geindex PyConfig.parser_debug (C member)
@anchor{c-api/init_config c PyConfig parser_debug}@anchor{3be}
@deffn {C Membre} int parser_debug

Parser debug mode. If greater than @code{0}, turn on parser debugging output (for expert only, depending
on compilation options).

Incremented by the @ref{1cbd,,-d} command line option. Set to the
@geindex PYTHONDEBUG
@geindex variable d'environnement; PYTHONDEBUG
@ref{1cbe,,PYTHONDEBUG} environment variable value.

Needs a @ref{1f6,,debug build of Python} (the @code{Py_DEBUG} macro
must be defined).

Default: @code{0}.
@end deffn

@geindex PyConfig.pathconfig_warnings (C member)
@anchor{c-api/init_config c PyConfig pathconfig_warnings}@anchor{3ce}
@deffn {C Membre} int pathconfig_warnings

If non-zero, calculation of path configuration is allowed to log
warnings into @code{stderr}. If equals to @code{0}, suppress these warnings.

Default: @code{1} in Python mode, @code{0} in isolated mode.

Part of the @ref{89a,,Python Path Configuration} input.


Modifié dans la version 3.11: Now also applies on Windows.

@end deffn

@geindex PyConfig.prefix (C member)
@anchor{c-api/init_config c PyConfig prefix}@anchor{4c9f}
@deffn {C Membre} wchar_t *prefix

The site-specific directory prefix where the platform independent Python
files are installed: @ref{3ad,,sys.prefix}.

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} output.

See also @ref{4c9e,,PyConfig.base_prefix}.
@end deffn

@geindex PyConfig.program_name (C member)
@anchor{c-api/init_config c PyConfig program_name}@anchor{3bb}
@deffn {C Membre} wchar_t *program_name

Program name used to initialize @ref{39c,,executable} and in
early error messages during Python initialization.


@itemize *

@item 
On macOS, use 
@geindex PYTHONEXECUTABLE
@geindex variable d'environnement; PYTHONEXECUTABLE
@ref{1cd4,,PYTHONEXECUTABLE} environment variable if set.

@item 
If the @code{WITH_NEXT_FRAMEWORK} macro is defined, use
@geindex __PYVENV_LAUNCHER__
@geindex variable d'environnement; __PYVENV_LAUNCHER__
@code{__PYVENV_LAUNCHER__} environment variable if set.

@item 
Use @code{argv[0]} of @ref{3ba,,argv} if available and
non-empty.

@item 
Otherwise, use @code{L"python"} on Windows, or @code{L"python3"} on other
platforms.
@end itemize

Default: @code{NULL}.

Part of the @ref{89a,,Python Path Configuration} input.
@end deffn

@geindex PyConfig.pycache_prefix (C member)
@anchor{c-api/init_config c PyConfig pycache_prefix}@anchor{4cab}
@deffn {C Membre} wchar_t *pycache_prefix

Directory where cached @code{.pyc} files are written:
@ref{992,,sys.pycache_prefix}.

Set by the @ref{175,,-X pycache_prefix=PATH} command line option and
the 
@geindex PYTHONPYCACHEPREFIX
@geindex variable d'environnement; PYTHONPYCACHEPREFIX
@ref{991,,PYTHONPYCACHEPREFIX} environment variable.
The command-line option takes precedence.

If @code{NULL}, @ref{992,,sys.pycache_prefix} is set to @code{None}.

Default: @code{NULL}.
@end deffn

@geindex PyConfig.quiet (C member)
@anchor{c-api/init_config c PyConfig quiet}@anchor{3c2}
@deffn {C Membre} int quiet

Quiet mode. If greater than @code{0}, don't display the copyright and version at
Python startup in interactive mode.

Incremented by the @ref{1cc0,,-q} command line option.

Default: @code{0}.
@end deffn

@geindex PyConfig.run_command (C member)
@anchor{c-api/init_config c PyConfig run_command}@anchor{4c48}
@deffn {C Membre} wchar_t *run_command

Value of the @ref{5ca,,-c} command line option.

Used by @ref{9b3,,Py_RunMain()}.

Default: @code{NULL}.
@end deffn

@geindex PyConfig.run_filename (C member)
@anchor{c-api/init_config c PyConfig run_filename}@anchor{4c49}
@deffn {C Membre} wchar_t *run_filename

Filename passed on the command line: trailing command line argument
without @ref{5ca,,-c} or @ref{5cb,,-m}. It is used by the
@ref{9b3,,Py_RunMain()} function.

For example, it is set to @code{script.py} by the @code{python3 script.py arg}
command line.

See also the @ref{4cac,,PyConfig.skip_source_first_line} option.

Default: @code{NULL}.
@end deffn

@geindex PyConfig.run_module (C member)
@anchor{c-api/init_config c PyConfig run_module}@anchor{4c4a}
@deffn {C Membre} wchar_t *run_module

Value of the @ref{5cb,,-m} command line option.

Used by @ref{9b3,,Py_RunMain()}.

Default: @code{NULL}.
@end deffn

@geindex PyConfig.run_presite (C member)
@anchor{c-api/init_config c PyConfig run_presite}@anchor{4cad}
@deffn {C Membre} wchar_t *run_presite

@code{package.module} path to module that should be imported before
@code{site.py} is run.

Set by the @ref{175,,-X presite=package.module} command-line
option and the 
@geindex PYTHON_PRESITE
@geindex variable d'environnement; PYTHON_PRESITE
@ref{1cca,,PYTHON_PRESITE} environment variable.
The command-line option takes precedence.

Needs a @ref{1f6,,debug build of Python} (the @code{Py_DEBUG} macro
must be defined).

Default: @code{NULL}.
@end deffn

@geindex PyConfig.show_ref_count (C member)
@anchor{c-api/init_config c PyConfig show_ref_count}@anchor{4cae}
@deffn {C Membre} int show_ref_count

Show total reference count at exit (excluding @ref{42aa,,immortal} objects)?

Set to @code{1} by @ref{175,,-X showrefcount} command line option.

Needs a @ref{1f6,,debug build of Python} (the @code{Py_REF_DEBUG}
macro must be defined).

Default: @code{0}.
@end deffn

@geindex PyConfig.site_import (C member)
@anchor{c-api/init_config c PyConfig site_import}@anchor{3ca}
@deffn {C Membre} int site_import

Import the @ref{c6,,site} module at startup?

If equal to zero, disable the import of the module site and the
site-dependent manipulations of @ref{3ab,,sys.path} that it entails.

Also disable these manipulations if the @ref{c6,,site} module is explicitly
imported later (call @ref{1cc2,,site.main()} if you want them to be triggered).

Set to @code{0} by the @ref{1186,,-S} command line option.

@ref{677,,sys.flags.no_site} is set to the inverted value of
@ref{3ca,,site_import}.

Default: @code{1}.
@end deffn

@geindex PyConfig.skip_source_first_line (C member)
@anchor{c-api/init_config c PyConfig skip_source_first_line}@anchor{4cac}
@deffn {C Membre} int skip_source_first_line

If non-zero, skip the first line of the @ref{4c49,,PyConfig.run_filename}
source.

It allows the usage of non-Unix forms of @code{#!cmd}. This is intended for
a DOS specific hack only.

Set to @code{1} by the @ref{1cc6,,-x} command line option.

Default: @code{0}.
@end deffn

@geindex PyConfig.stdio_encoding (C member)
@anchor{c-api/init_config c PyConfig stdio_encoding}@anchor{39a}
@deffn {C Membre} wchar_t *stdio_encoding
@end deffn

@geindex PyConfig.stdio_errors (C member)
@anchor{c-api/init_config c PyConfig stdio_errors}@anchor{42ba}
@deffn {C Membre} wchar_t *stdio_errors

Encoding and encoding errors of @ref{527,,sys.stdin}, @ref{ac4,,sys.stdout} and
@ref{926,,sys.stderr} (but @ref{926,,sys.stderr} always uses
@code{"backslashreplace"} error handler).

Use the 
@geindex PYTHONIOENCODING
@geindex variable d'environnement; PYTHONIOENCODING
@ref{ff3,,PYTHONIOENCODING} environment variable if it is
non-empty.

Default encoding:


@itemize *

@item 
@code{"UTF-8"} if @ref{3e1,,PyPreConfig.utf8_mode} is non-zero.

@item 
Otherwise, use the @ref{23f,,locale encoding}.
@end itemize

Default error handler:


@itemize *

@item 
On Windows: use @code{"surrogateescape"}.

@item 
@code{"surrogateescape"} if @ref{3e1,,PyPreConfig.utf8_mode} is non-zero,
or if the LC_CTYPE locale is "C" or "POSIX".

@item 
@code{"strict"} otherwise.
@end itemize

See also @ref{39b,,PyConfig.legacy_windows_stdio}.
@end deffn

@geindex PyConfig.tracemalloc (C member)
@anchor{c-api/init_config c PyConfig tracemalloc}@anchor{4caf}
@deffn {C Membre} int tracemalloc

Enable tracemalloc?

If non-zero, call @ref{1cc7,,tracemalloc.start()} at startup.

Set by @ref{175,,-X tracemalloc=N} command line option and by the
@geindex PYTHONTRACEMALLOC
@geindex variable d'environnement; PYTHONTRACEMALLOC
@ref{1cc8,,PYTHONTRACEMALLOC} environment variable.

Default: @code{-1} in Python mode, @code{0} in isolated mode.
@end deffn

@geindex PyConfig.perf_profiling (C member)
@anchor{c-api/init_config c PyConfig perf_profiling}@anchor{4cb0}
@deffn {C Membre} int perf_profiling

Enable compatibility mode with the perf profiler?

If non-zero, initialize the perf trampoline. See @ref{18d,,Python support for the Linux perf profiler}
for more information.

Set by @ref{175,,-X perf} command-line option and by the
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex variable d'environnement; PYTHON_PERF_JIT_SUPPORT
@ref{18e,,PYTHON_PERF_JIT_SUPPORT} environment variable for perf support
with stack pointers and @ref{175,,-X perf_jit} command-line option
and by the 
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex variable d'environnement; PYTHON_PERF_JIT_SUPPORT
@ref{18e,,PYTHON_PERF_JIT_SUPPORT} environment variable for perf
support with DWARF JIT information.

Default: @code{-1}.


Ajouté dans la version 3.12.

@end deffn

@geindex PyConfig.use_environment (C member)
@anchor{c-api/init_config c PyConfig use_environment}@anchor{3d0}
@deffn {C Membre} int use_environment

Use @ref{5db,,environment variables}?

If equals to zero, ignore the @ref{5db,,environment variables}.

Set to @code{0} by the @ref{94a,,-E} environment variable.

Default: @code{1} in Python config and @code{0} in isolated config.
@end deffn

@geindex PyConfig.use_system_logger (C member)
@anchor{c-api/init_config c PyConfig use_system_logger}@anchor{1df2}
@deffn {C Membre} int use_system_logger

If non-zero, @code{stdout} and @code{stderr} will be redirected to the system
log.

Only available on macOS 10.12 and later, and on iOS.

Default: @code{0} (don't use system log).


Ajouté dans la version 3.13.2.

@end deffn

@geindex PyConfig.user_site_directory (C member)
@anchor{c-api/init_config c PyConfig user_site_directory}@anchor{3d4}
@deffn {C Membre} int user_site_directory

If non-zero, add the user site directory to @ref{3ab,,sys.path}.

Set to @code{0} by the @ref{1362,,-s} and @ref{94b,,-I} command line options.

Set to @code{0} by the 
@geindex PYTHONNOUSERSITE
@geindex variable d'environnement; PYTHONNOUSERSITE
@ref{1363,,PYTHONNOUSERSITE} environment variable.

Default: @code{1} in Python mode, @code{0} in isolated mode.
@end deffn

@geindex PyConfig.verbose (C member)
@anchor{c-api/init_config c PyConfig verbose}@anchor{3c0}
@deffn {C Membre} int verbose

Verbose mode. If greater than @code{0}, print a message each time a module is
imported, showing the place (filename or built-in module) from which
it is loaded.

If greater than or equal to @code{2}, print a message for each file that is
checked for when searching for a module. Also provides information on
module cleanup at exit.

Incremented by the @ref{13db,,-v} command line option.

Set by the 
@geindex PYTHONVERBOSE
@geindex variable d'environnement; PYTHONVERBOSE
@ref{1cc3,,PYTHONVERBOSE} environment variable value.

Default: @code{0}.
@end deffn

@geindex PyConfig.warnoptions (C member)
@anchor{c-api/init_config c PyConfig warnoptions}@anchor{397}
@deffn {C Membre} @ref{99c,,PyWideStringList} warnoptions

Options of the @ref{111,,warnings} module to build warnings filters, lowest
to highest priority: @ref{3a7,,sys.warnoptions}.

The @ref{111,,warnings} module adds @ref{3a7,,sys.warnoptions} in the reverse
order: the last @ref{397,,PyConfig.warnoptions} item becomes the first
item of @code{warnings.filters} which is checked first (highest
priority).

The @ref{8b4,,-W} command line options adds its value to
@ref{397,,warnoptions}, it can be used multiple times.

The 
@geindex PYTHONWARNINGS
@geindex variable d'environnement; PYTHONWARNINGS
@ref{b98,,PYTHONWARNINGS} environment variable can also be used to add
warning options. Multiple options can be specified, separated by commas
(@code{,}).

Default: empty list.
@end deffn

@geindex PyConfig.write_bytecode (C member)
@anchor{c-api/init_config c PyConfig write_bytecode}@anchor{3d2}
@deffn {C Membre} int write_bytecode

If equal to @code{0}, Python won't try to write @code{.pyc} files on the import of
source modules.

Set to @code{0} by the @ref{1384,,-B} command line option and the
@geindex PYTHONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@ref{1385,,PYTHONDONTWRITEBYTECODE} environment variable.

@ref{4283,,sys.dont_write_bytecode} is initialized to the inverted value of
@ref{3d2,,write_bytecode}.

Default: @code{1}.
@end deffn

@geindex PyConfig.xoptions (C member)
@anchor{c-api/init_config c PyConfig xoptions}@anchor{398}
@deffn {C Membre} @ref{99c,,PyWideStringList} xoptions

Values of the @ref{175,,-X} command line options: @ref{1ccb,,sys._xoptions}.

Default: empty list.
@end deffn
@end deffn

If @ref{18b6,,parse_argv} is non-zero, @ref{3ba,,argv}
arguments are parsed the same way the regular Python parses @ref{ff0,,command line arguments}, and Python arguments are stripped from
@ref{3ba,,argv}.

The @ref{398,,xoptions} options are parsed to set other options: see
the @ref{175,,-X} command line option.


Modifié dans la version 3.9: The @code{show_alloc_count} field has been removed.


@node Initialization with PyConfig,Isolated Configuration,PyConfig,Python Initialization Configuration
@anchor{c-api/init_config init-from-config}@anchor{4c47}@anchor{c-api/init_config initialization-with-pyconfig}@anchor{4cb1}
@subsection Initialization with PyConfig


Initializing the interpreter from a populated configuration struct is handled
by calling @ref{3bc,,Py_InitializeFromConfig()}.

The caller is responsible to handle exceptions (error or exit) using
@ref{9a7,,PyStatus_Exception()} and @ref{9b0,,Py_ExitStatusException()}.

If @ref{2d81,,PyImport_FrozenModules()}, @ref{1731,,PyImport_AppendInittab()} or
@ref{1732,,PyImport_ExtendInittab()} are used, they must be set or called after
Python preinitialization and before the Python initialization. If Python is
initialized multiple times, @ref{1731,,PyImport_AppendInittab()} or
@ref{1732,,PyImport_ExtendInittab()} must be called before each Python
initialization.

The current configuration (@code{PyConfig} type) is stored in
@code{PyInterpreterState.config}.

Example setting the program name:

@example
void init_python(void)
@{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name. Implicitly preinitialize Python. */
    status = PyConfig_SetString(&config, &config.program_name,
                                L"/path/to/my_program");
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}

    status = Py_InitializeFromConfig(&config);
    if (PyStatus_Exception(status)) @{
        goto exception;
    @}
    PyConfig_Clear(&config);
    return;

exception:
    PyConfig_Clear(&config);
    Py_ExitStatusException(status);
@}
@end example

More complete example modifying the default configuration, read the
configuration, and then override some parameters. Note that since
3.11, many parameters are not calculated until initialization, and
so values cannot be read from the configuration structure. Any values
set before initialize is called will be left unchanged by
initialization:

@example
PyStatus init_python(const char *program_name)
@{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);

    /* Set the program name before reading the configuration
       (decode byte string from the locale encoding).

       Implicitly preinitialize Python. */
    status = PyConfig_SetBytesString(&config, &config.program_name,
                                     program_name);
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    /* Read all configuration at once */
    status = PyConfig_Read(&config);
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    /* Specify sys.path explicitly */
    /* If you want to modify the default set of paths, finish
       initialization first and then use PySys_GetObject("path") */
    config.module_search_paths_set = 1;
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/stdlib");
    if (PyStatus_Exception(status)) @{
        goto done;
    @}
    status = PyWideStringList_Append(&config.module_search_paths,
                                     L"/path/to/more/modules");
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    /* Override executable computed by PyConfig_Read() */
    status = PyConfig_SetString(&config, &config.executable,
                                L"/path/to/my_executable");
    if (PyStatus_Exception(status)) @{
        goto done;
    @}

    status = Py_InitializeFromConfig(&config);

done:
    PyConfig_Clear(&config);
    return status;
@}
@end example

@node Isolated Configuration,Python Configuration,Initialization with PyConfig,Python Initialization Configuration
@anchor{c-api/init_config init-isolated-conf}@anchor{4c85}@anchor{c-api/init_config isolated-configuration}@anchor{4cb2}
@subsection Isolated Configuration


@ref{9a4,,PyPreConfig_InitIsolatedConfig()} and
@ref{99e,,PyConfig_InitIsolatedConfig()} functions create a configuration to
isolate Python from the system. For example, to embed Python into an
application.

This configuration ignores global configuration variables, environment
variables, command line arguments (@ref{3ba,,PyConfig.argv} is not parsed)
and user site directory. The C standard streams (ex: @code{stdout}) and the
LC_CTYPE locale are left unchanged. Signal handlers are not installed.

Configuration files are still used with this configuration to determine
paths that are unspecified. Ensure @ref{3b2,,PyConfig.home} is specified
to avoid computing the default path configuration.

@node Python Configuration,Python Path Configuration,Isolated Configuration,Python Initialization Configuration
@anchor{c-api/init_config init-python-config}@anchor{4c4b}@anchor{c-api/init_config python-configuration}@anchor{4cb3}
@subsection Python Configuration


@ref{9a5,,PyPreConfig_InitPythonConfig()} and @ref{99f,,PyConfig_InitPythonConfig()}
functions create a configuration to build a customized Python which behaves as
the regular Python.

Environments variables and command line arguments are used to configure
Python, whereas global configuration variables are ignored.

This function enables C locale coercion (
@geindex Python Enhancement Proposals; PEP 538
PEP 538@footnote{https://peps.python.org/pep-0538/})
and @ref{641,,Python UTF-8 Mode}
(
@geindex Python Enhancement Proposals; PEP 540
PEP 540@footnote{https://peps.python.org/pep-0540/}) depending on the LC_CTYPE locale, 
@geindex PYTHONUTF8
@geindex variable d'environnement; PYTHONUTF8
@ref{ac6,,PYTHONUTF8} and
@geindex PYTHONCOERCECLOCALE
@geindex variable d'environnement; PYTHONCOERCECLOCALE
@ref{ac3,,PYTHONCOERCECLOCALE} environment variables.

@node Python Path Configuration,Py_GetArgcArgv,Python Configuration,Python Initialization Configuration
@anchor{c-api/init_config init-path-config}@anchor{89a}@anchor{c-api/init_config python-path-configuration}@anchor{4cb4}
@subsection Python Path Configuration


@ref{39d,,PyConfig} contains multiple fields for the path configuration:


@itemize *

@item 
Path configuration inputs:


@itemize *

@item 
@ref{3b2,,PyConfig.home}

@item 
@ref{18cb,,PyConfig.platlibdir}

@item 
@ref{3ce,,PyConfig.pathconfig_warnings}

@item 
@ref{3bb,,PyConfig.program_name}

@item 
@ref{4caa,,PyConfig.pythonpath_env}

@item 
current working directory: to get absolute paths

@item 
@code{PATH} environment variable to get the program full path
(from @ref{3bb,,PyConfig.program_name})

@item 
@code{__PYVENV_LAUNCHER__} environment variable

@item 
(Windows only) Application paths in the registry under
"SoftwarePythonPythonCoreX.YPythonPath" of HKEY_CURRENT_USER and
HKEY_LOCAL_MACHINE (where X.Y is the Python version).
@end itemize

@item 
Path configuration output fields:


@itemize *

@item 
@ref{4c9b,,PyConfig.base_exec_prefix}

@item 
@ref{4c9d,,PyConfig.base_executable}

@item 
@ref{4c9e,,PyConfig.base_prefix}

@item 
@ref{4c9c,,PyConfig.exec_prefix}

@item 
@ref{39c,,PyConfig.executable}

@item 
@ref{5d9,,PyConfig.module_search_paths_set},
@ref{399,,PyConfig.module_search_paths}

@item 
@ref{4c9f,,PyConfig.prefix}
@end itemize
@end itemize

If at least one "output field" is not set, Python calculates the path
configuration to fill unset fields. If
@ref{5d9,,module_search_paths_set} is equal to @code{0},
@ref{399,,module_search_paths} is overridden and
@ref{5d9,,module_search_paths_set} is set to @code{1}.

It is possible to completely ignore the function calculating the default
path configuration by setting explicitly all path configuration output
fields listed above. A string is considered as set even if it is non-empty.
@code{module_search_paths} is considered as set if
@code{module_search_paths_set} is set to @code{1}. In this case,
@code{module_search_paths} will be used without modification.

Set @ref{3ce,,pathconfig_warnings} to @code{0} to suppress warnings when
calculating the path configuration (Unix only, Windows does not log any warning).

If @ref{4c9e,,base_prefix} or @ref{4c9b,,base_exec_prefix}
fields are not set, they inherit their value from @ref{4c9f,,prefix}
and @ref{4c9c,,exec_prefix} respectively.

@ref{9b3,,Py_RunMain()} and @ref{c13,,Py_Main()} modify @ref{3ab,,sys.path}:


@itemize *

@item 
If @ref{4c49,,run_filename} is set and is a directory which contains a
@code{__main__.py} script, prepend @ref{4c49,,run_filename} to
@ref{3ab,,sys.path}.

@item 
If @ref{3db,,isolated} is zero:


@itemize *

@item 
If @ref{4c4a,,run_module} is set, prepend the current directory
to @ref{3ab,,sys.path}. Do nothing if the current directory cannot be read.

@item 
If @ref{4c49,,run_filename} is set, prepend the directory of the
filename to @ref{3ab,,sys.path}.

@item 
Otherwise, prepend an empty string to @ref{3ab,,sys.path}.
@end itemize
@end itemize

If @ref{3ca,,site_import} is non-zero, @ref{3ab,,sys.path} can be
modified by the @ref{c6,,site} module. If
@ref{3d4,,user_site_directory} is non-zero and the user's
site-package directory exists, the @ref{c6,,site} module appends the user's
site-package directory to @ref{3ab,,sys.path}.

The following configuration files are used by the path configuration:


@itemize *

@item 
@code{pyvenv.cfg}

@item 
@code{._pth} file (ex: @code{python._pth})

@item 
@code{pybuilddir.txt} (Unix only)
@end itemize

If a @code{._pth} file is present:


@itemize *

@item 
Set @ref{3db,,isolated} to @code{1}.

@item 
Set @ref{3d0,,use_environment} to @code{0}.

@item 
Set @ref{3ca,,site_import} to @code{0}.

@item 
Set @ref{75d,,safe_path} to @code{1}.
@end itemize

The @code{__PYVENV_LAUNCHER__} environment variable is used to set
@ref{4c9d,,PyConfig.base_executable}.

@node Py_GetArgcArgv,Multi-Phase Initialization Private Provisional API,Python Path Configuration,Python Initialization Configuration
@anchor{c-api/init_config py-getargcargv}@anchor{4cb5}
@subsection Py_GetArgcArgv()


@geindex Py_GetArgcArgv (C function)
@anchor{c-api/init_config c Py_GetArgcArgv}@anchor{18e3}
@deffn {C Fonction} void Py_GetArgcArgv (int *argc, wchar_t ***argv)

Get the original command line arguments, before Python modified them.

See also @ref{880,,PyConfig.orig_argv} member.
@end deffn

@node Multi-Phase Initialization Private Provisional API,,Py_GetArgcArgv,Python Initialization Configuration
@anchor{c-api/init_config multi-phase-initialization-private-provisional-api}@anchor{4cb6}
@subsection Multi-Phase Initialization Private Provisional API


This section is a private provisional API introducing multi-phase
initialization, the core feature of 
@geindex Python Enhancement Proposals; PEP 432
PEP 432@footnote{https://peps.python.org/pep-0432/}:


@itemize *

@item 
"Core" initialization phase, "bare minimum Python":


@itemize *

@item 
Builtin types;

@item 
Builtin exceptions;

@item 
Builtin and frozen modules;

@item 
The @ref{d8,,sys} module is only partially initialized
(ex: @ref{3ab,,sys.path} doesn't exist yet).
@end itemize

@item 
"Main" initialization phase, Python is fully initialized:


@itemize *

@item 
Install and configure @ref{76,,importlib};

@item 
Apply the @ref{89a,,Path Configuration};

@item 
Install signal handlers;

@item 
Finish @ref{d8,,sys} module initialization (ex: create @ref{ac4,,sys.stdout}
and @ref{3ab,,sys.path});

@item 
Enable optional features like @ref{57,,faulthandler} and @ref{fe,,tracemalloc};

@item 
Import the @ref{c6,,site} module;

@item 
etc.
@end itemize
@end itemize

Private provisional API:


@itemize *

@item 
@code{PyConfig._init_main}: if set to @code{0},
@ref{3bc,,Py_InitializeFromConfig()} stops at the "Core" initialization phase.
@end itemize

@geindex _Py_InitializeMain (C function)
@anchor{c-api/init_config c _Py_InitializeMain}@anchor{4cb7}
@deffn {C Fonction} @ref{99b,,PyStatus} _Py_InitializeMain (void)

Move to the "Main" initialization phase, finish the Python initialization.
@end deffn

No module is imported during the "Core" phase and the @code{importlib} module is
not configured: the @ref{89a,,Path Configuration} is only
applied during the "Main" phase. It may allow to customize Python in Python to
override or tune the @ref{89a,,Path Configuration}, maybe
install a custom @ref{d19,,sys.meta_path} importer or an import hook, etc.

It may become possible to calculate the @ref{89a,,Path Configuration} in Python, after the Core phase and before the Main phase,
which is one of the 
@geindex Python Enhancement Proposals; PEP 432
PEP 432@footnote{https://peps.python.org/pep-0432/} motivation.

The "Core" phase is not properly defined: what should be and what should
not be available at this phase is not specified yet. The API is marked
as private and provisional: the API can be modified or even be removed
anytime until a proper public API is designed.

Example running Python code between "Core" and "Main" initialization
phases:

@example
void init_python(void)
@{
    PyStatus status;

    PyConfig config;
    PyConfig_InitPythonConfig(&config);
    config._init_main = 0;

    /* ... customize 'config' configuration ... */

    status = Py_InitializeFromConfig(&config);
    PyConfig_Clear(&config);
    if (PyStatus_Exception(status)) @{
        Py_ExitStatusException(status);
    @}

    /* Use sys.stderr because sys.stdout is only created
       by _Py_InitializeMain() */
    int res = PyRun_SimpleString(
        "import sys; "
        "print('Run Python code before _Py_InitializeMain', "
               "file=sys.stderr)");
    if (res < 0) @{
        exit(1);
    @}

    /* ... put more configuration code here ... */

    status = _Py_InitializeMain();
    if (PyStatus_Exception(status)) @{
        Py_ExitStatusException(status);
    @}
@}
@end example

@node Memory Management,Implémentation d'objets,Python Initialization Configuration,Manuel de référence de l'API Python/C
@anchor{c-api/memory doc}@anchor{4cb8}@anchor{c-api/memory memory}@anchor{4c90}@anchor{c-api/memory memory-management}@anchor{4cb9}
@section Memory Management


@menu
* Aperçu: Aperçu<4>. 
* Allocator Domains:: 
* Raw Memory Interface:: 
* Memory Interface:: 
* Object allocators:: 
* Default Memory Allocators:: 
* Customize Memory Allocators:: 
* Debug hooks on the Python memory allocators:: 
* The pymalloc allocator:: 
* The mimalloc allocator:: 
* tracemalloc C API:: 
* Exemples: Exemples<36>. 

@end menu

@node Aperçu<4>,Allocator Domains,,Memory Management
@anchor{c-api/memory memoryoverview}@anchor{4cba}@anchor{c-api/memory overview}@anchor{4cbb}
@subsection Aperçu


Memory management in Python involves a private heap containing all Python
objects and data structures. The management of this private heap is ensured
internally by the `Python memory manager'.  The Python memory manager has
different components which deal with various dynamic storage management aspects,
like sharing, segmentation, preallocation or caching.

At the lowest level, a raw memory allocator ensures that there is enough room in
the private heap for storing all Python-related data by interacting with the
memory manager of the operating system. On top of the raw memory allocator,
several object-specific allocators operate on the same heap and implement
distinct memory management policies adapted to the peculiarities of every object
type. For example, integer objects are managed differently within the heap than
strings, tuples or dictionaries because integers imply different storage
requirements and speed/space tradeoffs. The Python memory manager thus delegates
some of the work to the object-specific allocators, but ensures that the latter
operate within the bounds of the private heap.

It is important to understand that the management of the Python heap is
performed by the interpreter itself and that the user has no control over it,
even if they regularly manipulate object pointers to memory blocks inside that
heap.  The allocation of heap space for Python objects and other internal
buffers is performed on demand by the Python memory manager through the Python/C
API functions listed in this document.

@geindex malloc (C function)
@geindex calloc (C function)
@geindex realloc (C function)
@geindex free (C function)

To avoid memory corruption, extension writers should never try to operate on
Python objects with the functions exported by the C library: @code{malloc()},
@code{calloc()}, @code{realloc()} and @code{free()}.  This will result in  mixed
calls between the C allocator and the Python memory manager with fatal
consequences, because they implement different algorithms and operate on
different heaps.  However, one may safely allocate and release memory blocks
with the C library allocator for individual purposes, as shown in the following
example:

@example
PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyBytes_FromString(buf);
free(buf); /* malloc'ed */
return res;
@end example

In this example, the memory request for the I/O buffer is handled by the C
library allocator. The Python memory manager is involved only in the allocation
of the bytes object returned as a result.

In most situations, however, it is recommended to allocate memory from the
Python heap specifically because the latter is under control of the Python
memory manager. For example, this is required when the interpreter is extended
with new object types written in C. Another reason for using the Python heap is
the desire to `inform' the Python memory manager about the memory needs of the
extension module. Even when the requested memory is used exclusively for
internal, highly specific purposes, delegating all memory requests to the Python
memory manager causes the interpreter to have a more accurate image of its
memory footprint as a whole. Consequently, under certain circumstances, the
Python memory manager may or may not trigger appropriate actions, like garbage
collection, memory compaction or other preventive procedures. Note that by using
the C library allocator as shown in the previous example, the allocated memory
for the I/O buffer escapes completely the Python memory manager.


@subsubheading Voir aussi


The 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable can be used to configure
the memory allocators used by Python.

The 
@geindex PYTHONMALLOCSTATS
@geindex variable d'environnement; PYTHONMALLOCSTATS
@ref{1ae4,,PYTHONMALLOCSTATS} environment variable can be used to print
statistics of the @ref{cfd,,pymalloc memory allocator} every time a
new pymalloc object arena is created, and on shutdown.


@node Allocator Domains,Raw Memory Interface,Aperçu<4>,Memory Management
@anchor{c-api/memory allocator-domains}@anchor{4cbc}
@subsection Allocator Domains

@anchor{c-api/memory id1}@anchor{4cbd}
All allocating functions belong to one of three different "domains" (see also
@ref{4cbe,,PyMemAllocatorDomain}). These domains represent different allocation
strategies and are optimized for different purposes. The specific details on
how every domain allocates memory or what internal functions each domain calls
is considered an implementation detail, but for debugging purposes a simplified
table can be found at @ref{1cdc,,here}.
The APIs used to allocate and free a block of memory must be from the same domain.
For example, @ref{13f9,,PyMem_Free()} must be used to free memory allocated using @ref{c54,,PyMem_Malloc()}.

The three allocation domains are:


@itemize *

@item 
Raw domain: intended for allocating memory for general-purpose memory
buffers where the allocation `must' go to the system allocator or where the
allocator can operate without the @ref{158,,GIL}. The memory is requested directly
from the system. See @ref{4cbf,,Raw Memory Interface}.

@item 
"Mem" domain: intended for allocating memory for Python buffers and
general-purpose memory buffers where the allocation must be performed with
the @ref{158,,GIL} held. The memory is taken from the Python private heap.
See @ref{4cc0,,Memory Interface}.

@item 
Object domain: intended for allocating memory for Python objects. The
memory is taken from the Python private heap. See @ref{4cc1,,Object allocators}.
@end itemize

@cartouche
@quotation Note 
The @ref{150c,,free-threaded} build requires that only Python objects are allocated using the "object" domain
and that all Python objects are allocated using that domain. This differs from the prior Python versions,
where this was only a best practice and not a hard requirement.

For example, buffers (non-Python objects) should be allocated using @ref{c54,,PyMem_Malloc()},
@ref{386,,PyMem_RawMalloc()}, or @code{malloc()}, but not @ref{c56,,PyObject_Malloc()}.

See @ref{4cc2,,Memory Allocation APIs}.
@end quotation
@end cartouche

@node Raw Memory Interface,Memory Interface,Allocator Domains,Memory Management
@anchor{c-api/memory raw-memory-interface}@anchor{4cc3}@anchor{c-api/memory raw-memoryinterface}@anchor{4cbf}
@subsection Raw Memory Interface


The following function sets are wrappers to the system allocator. These
functions are thread-safe, the @ref{147,,GIL} does not
need to be held.

The @ref{1cdc,,default raw memory allocator} uses
the following functions: @code{malloc()}, @code{calloc()}, @code{realloc()}
and @code{free()}; call @code{malloc(1)} (or @code{calloc(1, 1)}) when requesting
zero bytes.


Ajouté dans la version 3.4.


@geindex PyMem_RawMalloc (C function)
@anchor{c-api/memory c PyMem_RawMalloc}@anchor{386}
@deffn {C Fonction} void *PyMem_RawMalloc (size_t n)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Allocates `n' bytes and returns a pointer of type void* to the
allocated memory, or @code{NULL} if the request fails.

Requesting zero bytes returns a distinct non-@code{NULL} pointer if possible, as
if @code{PyMem_RawMalloc(1)} had been called instead. The memory will not have
been initialized in any way.
@end deffn

@geindex PyMem_RawCalloc (C function)
@anchor{c-api/memory c PyMem_RawCalloc}@anchor{387}
@deffn {C Fonction} void *PyMem_RawCalloc (size_t nelem, size_t elsize)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Allocates `nelem' elements each whose size in bytes is `elsize' and returns
a pointer of type void* to the allocated memory, or @code{NULL} if the
request fails. The memory is initialized to zeros.

Requesting zero elements or elements of size zero bytes returns a distinct
non-@code{NULL} pointer if possible, as if @code{PyMem_RawCalloc(1, 1)} had been
called instead.


Ajouté dans la version 3.5.

@end deffn

@geindex PyMem_RawRealloc (C function)
@anchor{c-api/memory c PyMem_RawRealloc}@anchor{388}
@deffn {C Fonction} void *PyMem_RawRealloc (void *p, size_t n)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Resizes the memory block pointed to by `p' to `n' bytes. The contents will
be unchanged to the minimum of the old and the new sizes.

If `p' is @code{NULL}, the call is equivalent to @code{PyMem_RawMalloc(n)}; else if
`n' is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-@code{NULL}.

Unless `p' is @code{NULL}, it must have been returned by a previous call to
@ref{386,,PyMem_RawMalloc()}, @ref{388,,PyMem_RawRealloc()} or
@ref{387,,PyMem_RawCalloc()}.

If the request fails, @ref{388,,PyMem_RawRealloc()} returns @code{NULL} and `p'
remains a valid pointer to the previous memory area.
@end deffn

@geindex PyMem_RawFree (C function)
@anchor{c-api/memory c PyMem_RawFree}@anchor{389}
@deffn {C Fonction} void PyMem_RawFree (void *p)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{386,,PyMem_RawMalloc()}, @ref{388,,PyMem_RawRealloc()} or
@ref{387,,PyMem_RawCalloc()}.  Otherwise, or if @code{PyMem_RawFree(p)} has been
called before, undefined behavior occurs.

If `p' is @code{NULL}, no operation is performed.
@end deffn

@node Memory Interface,Object allocators,Raw Memory Interface,Memory Management
@anchor{c-api/memory memory-interface}@anchor{4cc4}@anchor{c-api/memory memoryinterface}@anchor{4cc0}
@subsection Memory Interface


The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.

The @ref{1cdc,,default memory allocator} uses the
@ref{cfd,,pymalloc memory allocator}.

@cartouche
@quotation Avertissement 
The @ref{147,,GIL} must be held when using these
functions.
@end quotation
@end cartouche


Modifié dans la version 3.6: The default allocator is now pymalloc instead of system @code{malloc()}.


@geindex PyMem_Malloc (C function)
@anchor{c-api/memory c PyMem_Malloc}@anchor{c54}
@deffn {C Fonction} void *PyMem_Malloc (size_t n)
` Part of the @ref{53e,,Stable ABI}.'
Allocates `n' bytes and returns a pointer of type void* to the
allocated memory, or @code{NULL} if the request fails.

Requesting zero bytes returns a distinct non-@code{NULL} pointer if possible, as
if @code{PyMem_Malloc(1)} had been called instead. The memory will not have
been initialized in any way.
@end deffn

@geindex PyMem_Calloc (C function)
@anchor{c-api/memory c PyMem_Calloc}@anchor{e96}
@deffn {C Fonction} void *PyMem_Calloc (size_t nelem, size_t elsize)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Allocates `nelem' elements each whose size in bytes is `elsize' and returns
a pointer of type void* to the allocated memory, or @code{NULL} if the
request fails. The memory is initialized to zeros.

Requesting zero elements or elements of size zero bytes returns a distinct
non-@code{NULL} pointer if possible, as if @code{PyMem_Calloc(1, 1)} had been called
instead.


Ajouté dans la version 3.5.

@end deffn

@geindex PyMem_Realloc (C function)
@anchor{c-api/memory c PyMem_Realloc}@anchor{101b}
@deffn {C Fonction} void *PyMem_Realloc (void *p, size_t n)
` Part of the @ref{53e,,Stable ABI}.'
Resizes the memory block pointed to by `p' to `n' bytes. The contents will be
unchanged to the minimum of the old and the new sizes.

If `p' is @code{NULL}, the call is equivalent to @code{PyMem_Malloc(n)}; else if `n'
is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-@code{NULL}.

Unless `p' is @code{NULL}, it must have been returned by a previous call to
@ref{c54,,PyMem_Malloc()}, @ref{101b,,PyMem_Realloc()} or @ref{e96,,PyMem_Calloc()}.

If the request fails, @ref{101b,,PyMem_Realloc()} returns @code{NULL} and `p' remains
a valid pointer to the previous memory area.
@end deffn

@geindex PyMem_Free (C function)
@anchor{c-api/memory c PyMem_Free}@anchor{13f9}
@deffn {C Fonction} void PyMem_Free (void *p)
` Part of the @ref{53e,,Stable ABI}.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{c54,,PyMem_Malloc()}, @ref{101b,,PyMem_Realloc()} or
@ref{e96,,PyMem_Calloc()}.  Otherwise, or if @code{PyMem_Free(p)} has been called
before, undefined behavior occurs.

If `p' is @code{NULL}, no operation is performed.
@end deffn

The following type-oriented macros are provided for convenience.  Note  that
`TYPE' refers to any C type.

@geindex PyMem_New (C macro)
@anchor{c-api/memory c PyMem_New}@anchor{14db}
@deffn {C Macro} PyMem_New (TYPE, n)

Same as @ref{c54,,PyMem_Malloc()}, but allocates @code{(n * sizeof(TYPE))} bytes of
memory.  Returns a pointer cast to @code{TYPE*}.  The memory will not have
been initialized in any way.
@end deffn

@geindex PyMem_Resize (C macro)
@anchor{c-api/memory c PyMem_Resize}@anchor{4cc5}
@deffn {C Macro} PyMem_Resize (p, TYPE, n)

Same as @ref{101b,,PyMem_Realloc()}, but the memory block is resized to @code{(n *
sizeof(TYPE))} bytes.  Returns a pointer cast to @code{TYPE*}. On return,
`p' will be a pointer to the new memory area, or @code{NULL} in the event of
failure.

This is a C preprocessor macro; `p' is always reassigned.  Save the original
value of `p' to avoid losing memory when handling errors.
@end deffn

@geindex PyMem_Del (C function)
@anchor{c-api/memory c PyMem_Del}@anchor{14dc}
@deffn {C Fonction} void PyMem_Del (void *p)

Same as @ref{13f9,,PyMem_Free()}.
@end deffn

In addition, the following macro sets are provided for calling the Python memory
allocator directly, without involving the C API functions listed above. However,
note that their use does not preserve binary compatibility across Python
versions and is therefore deprecated in extension modules.


@itemize *

@item 
@code{PyMem_MALLOC(size)}

@item 
@code{PyMem_NEW(type, size)}

@item 
@code{PyMem_REALLOC(ptr, size)}

@item 
@code{PyMem_RESIZE(ptr, type, size)}

@item 
@code{PyMem_FREE(ptr)}

@item 
@code{PyMem_DEL(ptr)}
@end itemize

@node Object allocators,Default Memory Allocators,Memory Interface,Memory Management
@anchor{c-api/memory object-allocators}@anchor{4cc6}@anchor{c-api/memory objectinterface}@anchor{4cc1}
@subsection Object allocators


The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.

@cartouche
@quotation Note 
There is no guarantee that the memory returned by these allocators can be
successfully cast to a Python object when intercepting the allocating
functions in this domain by the methods described in
the @ref{4cc7,,Customize Memory Allocators} section.
@end quotation
@end cartouche

The @ref{1cdc,,default object allocator} uses the
@ref{cfd,,pymalloc memory allocator}.

@cartouche
@quotation Avertissement 
The @ref{147,,GIL} must be held when using these
functions.
@end quotation
@end cartouche

@geindex PyObject_Malloc (C function)
@anchor{c-api/memory c PyObject_Malloc}@anchor{c56}
@deffn {C Fonction} void *PyObject_Malloc (size_t n)
` Part of the @ref{53e,,Stable ABI}.'
Allocates `n' bytes and returns a pointer of type void* to the
allocated memory, or @code{NULL} if the request fails.

Requesting zero bytes returns a distinct non-@code{NULL} pointer if possible, as
if @code{PyObject_Malloc(1)} had been called instead. The memory will not have
been initialized in any way.
@end deffn

@geindex PyObject_Calloc (C function)
@anchor{c-api/memory c PyObject_Calloc}@anchor{e97}
@deffn {C Fonction} void *PyObject_Calloc (size_t nelem, size_t elsize)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.7.'
Allocates `nelem' elements each whose size in bytes is `elsize' and returns
a pointer of type void* to the allocated memory, or @code{NULL} if the
request fails. The memory is initialized to zeros.

Requesting zero elements or elements of size zero bytes returns a distinct
non-@code{NULL} pointer if possible, as if @code{PyObject_Calloc(1, 1)} had been called
instead.


Ajouté dans la version 3.5.

@end deffn

@geindex PyObject_Realloc (C function)
@anchor{c-api/memory c PyObject_Realloc}@anchor{13fa}
@deffn {C Fonction} void *PyObject_Realloc (void *p, size_t n)
` Part of the @ref{53e,,Stable ABI}.'
Resizes the memory block pointed to by `p' to `n' bytes. The contents will be
unchanged to the minimum of the old and the new sizes.

If `p' is @code{NULL}, the call is equivalent to @code{PyObject_Malloc(n)}; else if `n'
is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-@code{NULL}.

Unless `p' is @code{NULL}, it must have been returned by a previous call to
@ref{c56,,PyObject_Malloc()}, @ref{13fa,,PyObject_Realloc()} or @ref{e97,,PyObject_Calloc()}.

If the request fails, @ref{13fa,,PyObject_Realloc()} returns @code{NULL} and `p' remains
a valid pointer to the previous memory area.
@end deffn

@geindex PyObject_Free (C function)
@anchor{c-api/memory c PyObject_Free}@anchor{c53}
@deffn {C Fonction} void PyObject_Free (void *p)
` Part of the @ref{53e,,Stable ABI}.'
Frees the memory block pointed to by `p', which must have been returned by a
previous call to @ref{c56,,PyObject_Malloc()}, @ref{13fa,,PyObject_Realloc()} or
@ref{e97,,PyObject_Calloc()}.  Otherwise, or if @code{PyObject_Free(p)} has been called
before, undefined behavior occurs.

If `p' is @code{NULL}, no operation is performed.
@end deffn

@node Default Memory Allocators,Customize Memory Allocators,Object allocators,Memory Management
@anchor{c-api/memory default-memory-allocators}@anchor{1cdc}@anchor{c-api/memory id2}@anchor{4cc8}
@subsection Default Memory Allocators


Default memory allocators:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Configuration

@tab

Nom

@tab

PyMem_RawMalloc

@tab

PyMem_Malloc

@tab

PyObject_Malloc

@item

Release build

@tab

@code{"pymalloc"}

@tab

@code{malloc}

@tab

@code{pymalloc}

@tab

@code{pymalloc}

@item

Debug build

@tab

@code{"pymalloc_debug"}

@tab

@code{malloc} + debug

@tab

@code{pymalloc} + debug

@tab

@code{pymalloc} + debug

@item

Release build, without pymalloc

@tab

@code{"malloc"}

@tab

@code{malloc}

@tab

@code{malloc}

@tab

@code{malloc}

@item

Debug build, without pymalloc

@tab

@code{"malloc_debug"}

@tab

@code{malloc} + debug

@tab

@code{malloc} + debug

@tab

@code{malloc} + debug

@end multitable


Legend:


@itemize *

@item 
Name: value for 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable.

@item 
@code{malloc}: system allocators from the standard C library, C functions:
@code{malloc()}, @code{calloc()}, @code{realloc()} and @code{free()}.

@item 
@code{pymalloc}: @ref{cfd,,pymalloc memory allocator}.

@item 
@code{mimalloc}: @ref{1cde,,mimalloc memory allocator}.  The pymalloc
allocator will be used if mimalloc support isn't available.

@item 
"+ debug": with @ref{1cdf,,debug hooks on the Python memory allocators}.

@item 
"Debug build": @ref{1f6,,Python build in debug mode}.
@end itemize

@node Customize Memory Allocators,Debug hooks on the Python memory allocators,Default Memory Allocators,Memory Management
@anchor{c-api/memory customize-memory-allocators}@anchor{4cc7}@anchor{c-api/memory id3}@anchor{4cc9}
@subsection Customize Memory Allocators



Ajouté dans la version 3.4.


@geindex PyMemAllocatorEx (C type)
@anchor{c-api/memory c PyMemAllocatorEx}@anchor{eb7}
@deffn {C Type} type PyMemAllocatorEx

Structure used to describe a memory block allocator. The structure has
the following fields:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Champ

@tab

Signification

@item

@code{void *ctx}

@tab

user context passed as first argument

@item

@code{void* malloc(void *ctx, size_t size)}

@tab

allocate a memory block

@item

@code{void* calloc(void *ctx, size_t nelem, size_t elsize)}

@tab

allocate a memory block initialized
with zeros

@item

@code{void* realloc(void *ctx, void *ptr, size_t new_size)}

@tab

allocate or resize a memory block

@item

@code{void free(void *ctx, void *ptr)}

@tab

free a memory block

@end multitable



Modifié dans la version 3.5: The @code{PyMemAllocator} structure was renamed to
@ref{eb7,,PyMemAllocatorEx} and a new @code{calloc} field was added.

@end deffn

@geindex PyMemAllocatorDomain (C type)
@anchor{c-api/memory c PyMemAllocatorDomain}@anchor{4cbe}
@deffn {C Type} type PyMemAllocatorDomain

Enum used to identify an allocator domain. Domains:

@geindex PYMEM_DOMAIN_RAW (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_RAW}@anchor{1cdd}
@deffn {C Macro} PYMEM_DOMAIN_RAW

Functions:


@itemize *

@item 
@ref{386,,PyMem_RawMalloc()}

@item 
@ref{388,,PyMem_RawRealloc()}

@item 
@ref{387,,PyMem_RawCalloc()}

@item 
@ref{389,,PyMem_RawFree()}
@end itemize
@end deffn

@geindex PYMEM_DOMAIN_MEM (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_MEM}@anchor{c57}
@deffn {C Macro} PYMEM_DOMAIN_MEM

Functions:


@itemize *

@item 
@ref{c54,,PyMem_Malloc()},

@item 
@ref{101b,,PyMem_Realloc()}

@item 
@ref{e96,,PyMem_Calloc()}

@item 
@ref{13f9,,PyMem_Free()}
@end itemize
@end deffn

@geindex PYMEM_DOMAIN_OBJ (C macro)
@anchor{c-api/memory c PYMEM_DOMAIN_OBJ}@anchor{c55}
@deffn {C Macro} PYMEM_DOMAIN_OBJ

Functions:


@itemize *

@item 
@ref{c56,,PyObject_Malloc()}

@item 
@ref{13fa,,PyObject_Realloc()}

@item 
@ref{e97,,PyObject_Calloc()}

@item 
@ref{c53,,PyObject_Free()}
@end itemize
@end deffn
@end deffn

@geindex PyMem_GetAllocator (C function)
@anchor{c-api/memory c PyMem_GetAllocator}@anchor{4c43}
@deffn {C Fonction} void PyMem_GetAllocator (PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

Get the memory block allocator of the specified domain.
@end deffn

@geindex PyMem_SetAllocator (C function)
@anchor{c-api/memory c PyMem_SetAllocator}@anchor{577}
@deffn {C Fonction} void PyMem_SetAllocator (PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)

Set the memory block allocator of the specified domain.

The new allocator must return a distinct non-@code{NULL} pointer when requesting
zero bytes.

For the @ref{1cdd,,PYMEM_DOMAIN_RAW} domain, the allocator must be
thread-safe: the @ref{147,,GIL} is not held when the
allocator is called.

For the remaining domains, the allocator must also be thread-safe:
the allocator may be called in different interpreters that do not
share a @code{GIL}.

If the new allocator is not a hook (does not call the previous allocator),
the @ref{c58,,PyMem_SetupDebugHooks()} function must be called to reinstall the
debug hooks on top on the new allocator.

See also @ref{4c8f,,PyPreConfig.allocator} and @ref{3c7c,,Preinitialize Python with PyPreConfig}.

@cartouche
@quotation Avertissement 
@ref{577,,PyMem_SetAllocator()} does have the following contract:


@itemize *

@item 
It can be called after @ref{3e2,,Py_PreInitialize()} and before
@ref{3bc,,Py_InitializeFromConfig()} to install a custom memory
allocator. There are no restrictions over the installed allocator
other than the ones imposed by the domain (for instance, the Raw
Domain allows the allocator to be called without the GIL held). See
@ref{4cbd,,the section on allocator domains} for more
information.

@item 
If called after Python has finish initializing (after
@ref{3bc,,Py_InitializeFromConfig()} has been called) the allocator
`must' wrap the existing allocator. Substituting the current
allocator for some other arbitrary one is `not supported'.
@end itemize
@end quotation
@end cartouche


Modifié dans la version 3.12: All allocators must be thread-safe.

@end deffn

@geindex PyMem_SetupDebugHooks (C function)
@anchor{c-api/memory c PyMem_SetupDebugHooks}@anchor{c58}
@deffn {C Fonction} void PyMem_SetupDebugHooks (void)

Setup @ref{1cdf,,debug hooks in the Python memory allocators}
to detect memory errors.
@end deffn

@node Debug hooks on the Python memory allocators,The pymalloc allocator,Customize Memory Allocators,Memory Management
@anchor{c-api/memory debug-hooks-on-the-python-memory-allocators}@anchor{4cca}@anchor{c-api/memory pymem-debug-hooks}@anchor{1cdf}
@subsection Debug hooks on the Python memory allocators


When @ref{1f6,,Python is built in debug mode}, the
@ref{c58,,PyMem_SetupDebugHooks()} function is called at the @ref{3c7c,,Python preinitialization} to setup debug hooks on Python memory allocators
to detect memory errors.

The 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable can be used to install debug
hooks on a Python compiled in release mode (ex: @code{PYTHONMALLOC=debug}).

The @ref{c58,,PyMem_SetupDebugHooks()} function can be used to set debug hooks
after calling @ref{577,,PyMem_SetAllocator()}.

These debug hooks fill dynamically allocated memory blocks with special,
recognizable bit patterns. Newly allocated memory is filled with the byte
@code{0xCD} (@code{PYMEM_CLEANBYTE}), freed memory is filled with the byte @code{0xDD}
(@code{PYMEM_DEADBYTE}). Memory blocks are surrounded by "forbidden bytes"
filled with the byte @code{0xFD} (@code{PYMEM_FORBIDDENBYTE}). Strings of these bytes
are unlikely to be valid addresses, floats, or ASCII strings.

Runtime checks:


@itemize -

@item 
Detect API violations. For example, detect if @ref{c53,,PyObject_Free()} is
called on a memory block allocated by @ref{c54,,PyMem_Malloc()}.

@item 
Detect write before the start of the buffer (buffer underflow).

@item 
Detect write after the end of the buffer (buffer overflow).

@item 
Check that the @ref{147,,GIL} is held when
allocator functions of @ref{c55,,PYMEM_DOMAIN_OBJ} (ex:
@ref{c56,,PyObject_Malloc()}) and @ref{c57,,PYMEM_DOMAIN_MEM} (ex:
@ref{c54,,PyMem_Malloc()}) domains are called.
@end itemize

On error, the debug hooks use the @ref{fe,,tracemalloc} module to get the
traceback where a memory block was allocated. The traceback is only displayed
if @ref{fe,,tracemalloc} is tracing Python memory allocations and the memory block
was traced.

Let `S' = @code{sizeof(size_t)}. @code{2*S} bytes are added at each end of each block
of `N' bytes requested.  The memory layout is like so, where p represents the
address returned by a malloc-like or realloc-like function (@code{p[i:j]} means
the slice of bytes from @code{*(p+i)} inclusive up to @code{*(p+j)} exclusive; note
that the treatment of negative indices differs from a Python slice):


@table @asis

@item @code{p[-2*S:-S]}

Number of bytes originally asked for.  This is a size_t, big-endian (easier
to read in a memory dump).

@item @code{p[-S]}

API identifier (ASCII character):


@itemize *

@item 
@code{'r'} for @ref{1cdd,,PYMEM_DOMAIN_RAW}.

@item 
@code{'m'} for @ref{c57,,PYMEM_DOMAIN_MEM}.

@item 
@code{'o'} for @ref{c55,,PYMEM_DOMAIN_OBJ}.
@end itemize

@item @code{p[-S+1:0]}

Copies of PYMEM_FORBIDDENBYTE.  Used to catch under- writes and reads.

@item @code{p[0:N]}

The requested memory, filled with copies of PYMEM_CLEANBYTE, used to catch
reference to uninitialized memory.  When a realloc-like function is called
requesting a larger memory block, the new excess bytes are also filled with
PYMEM_CLEANBYTE.  When a free-like function is called, these are
overwritten with PYMEM_DEADBYTE, to catch reference to freed memory.  When
a realloc- like function is called requesting a smaller memory block, the
excess old bytes are also filled with PYMEM_DEADBYTE.

@item @code{p[N:N+S]}

Copies of PYMEM_FORBIDDENBYTE.  Used to catch over- writes and reads.

@item @code{p[N+S:N+2*S]}

Only used if the @code{PYMEM_DEBUG_SERIALNO} macro is defined (not defined by
default).

A serial number, incremented by 1 on each call to a malloc-like or
realloc-like function.  Big-endian @code{size_t}.  If "bad memory" is detected
later, the serial number gives an excellent way to set a breakpoint on the
next run, to capture the instant at which this block was passed out.  The
static function bumpserialno() in obmalloc.c is the only place the serial
number is incremented, and exists so you can set such a breakpoint easily.
@end table

A realloc-like or free-like function first checks that the PYMEM_FORBIDDENBYTE
bytes at each end are intact.  If they've been altered, diagnostic output is
written to stderr, and the program is aborted via Py_FatalError().  The other
main failure mode is provoking a memory error when a program reads up one of
the special bit patterns and tries to use it as an address.  If you get in a
debugger then and look at the object, you're likely to see that it's entirely
filled with PYMEM_DEADBYTE (meaning freed memory is getting used) or
PYMEM_CLEANBYTE (meaning uninitialized memory is getting used).


Modifié dans la version 3.6: The @ref{c58,,PyMem_SetupDebugHooks()} function now also works on Python
compiled in release mode.  On error, the debug hooks now use
@ref{fe,,tracemalloc} to get the traceback where a memory block was allocated.
The debug hooks now also check if the GIL is held when functions of
@ref{c55,,PYMEM_DOMAIN_OBJ} and @ref{c57,,PYMEM_DOMAIN_MEM} domains are
called.



Modifié dans la version 3.8: Byte patterns @code{0xCB} (@code{PYMEM_CLEANBYTE}), @code{0xDB} (@code{PYMEM_DEADBYTE})
and @code{0xFB} (@code{PYMEM_FORBIDDENBYTE}) have been replaced with @code{0xCD},
@code{0xDD} and @code{0xFD} to use the same values than Windows CRT debug
@code{malloc()} and @code{free()}.


@node The pymalloc allocator,The mimalloc allocator,Debug hooks on the Python memory allocators,Memory Management
@anchor{c-api/memory pymalloc}@anchor{cfd}@anchor{c-api/memory the-pymalloc-allocator}@anchor{4ccb}
@subsection The pymalloc allocator


Python has a `pymalloc' allocator optimized for small objects (smaller or equal
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
with a fixed size of either 256 KiB on 32-bit platforms or 1 MiB on 64-bit
platforms. It falls back to @ref{386,,PyMem_RawMalloc()} and
@ref{388,,PyMem_RawRealloc()} for allocations larger than 512 bytes.

`pymalloc' is the @ref{1cdc,,default allocator} of the
@ref{c57,,PYMEM_DOMAIN_MEM} (ex: @ref{c54,,PyMem_Malloc()}) and
@ref{c55,,PYMEM_DOMAIN_OBJ} (ex: @ref{c56,,PyObject_Malloc()}) domains.

The arena allocator uses the following functions:


@itemize *

@item 
@code{VirtualAlloc()} and @code{VirtualFree()} on Windows,

@item 
@code{mmap()} and @code{munmap()} if available,

@item 
@code{malloc()} and @code{free()} otherwise.
@end itemize

This allocator is disabled if Python is configured with the
@ref{1d3a,,--without-pymalloc} option. It can also be disabled at runtime using
the 
@geindex PYTHONMALLOC
@geindex variable d'environnement; PYTHONMALLOC
@ref{c52,,PYTHONMALLOC} environment variable (ex: @code{PYTHONMALLOC=malloc}).

@menu
* Customize pymalloc Arena Allocator:: 

@end menu

@node Customize pymalloc Arena Allocator,,,The pymalloc allocator
@anchor{c-api/memory customize-pymalloc-arena-allocator}@anchor{4ccc}
@subsubsection Customize pymalloc Arena Allocator



Ajouté dans la version 3.4.


@geindex PyObjectArenaAllocator (C type)
@anchor{c-api/memory c PyObjectArenaAllocator}@anchor{4ccd}
@deffn {C Type} type PyObjectArenaAllocator

Structure used to describe an arena allocator. The structure has
three fields:


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Champ

@tab

Signification

@item

@code{void *ctx}

@tab

user context passed as first argument

@item

@code{void* alloc(void *ctx, size_t size)}

@tab

allocate an arena of size bytes

@item

@code{void free(void *ctx, void *ptr, size_t size)}

@tab

free an arena

@end multitable

@end deffn

@geindex PyObject_GetArenaAllocator (C function)
@anchor{c-api/memory c PyObject_GetArenaAllocator}@anchor{4c44}
@deffn {C Fonction} void PyObject_GetArenaAllocator (PyObjectArenaAllocator *allocator)

Get the arena allocator.
@end deffn

@geindex PyObject_SetArenaAllocator (C function)
@anchor{c-api/memory c PyObject_SetArenaAllocator}@anchor{4c42}
@deffn {C Fonction} void PyObject_SetArenaAllocator (PyObjectArenaAllocator *allocator)

Set the arena allocator.
@end deffn

@node The mimalloc allocator,tracemalloc C API,The pymalloc allocator,Memory Management
@anchor{c-api/memory mimalloc}@anchor{1cde}@anchor{c-api/memory the-mimalloc-allocator}@anchor{4cce}
@subsection The mimalloc allocator



Ajouté dans la version 3.13.


Python supports the mimalloc allocator when the underlying platform support is available.
mimalloc "is a general purpose allocator with excellent performance characteristics.
Initially developed by Daan Leijen for the runtime systems of the Koka and Lean languages."

@node tracemalloc C API,Exemples<36>,The mimalloc allocator,Memory Management
@anchor{c-api/memory tracemalloc-c-api}@anchor{4ccf}
@subsection tracemalloc C API



Ajouté dans la version 3.7.


@geindex PyTraceMalloc_Track (C function)
@anchor{c-api/memory c PyTraceMalloc_Track}@anchor{ba4}
@deffn {C Fonction} int PyTraceMalloc_Track (unsigned int domain, uintptr_t ptr, size_t size)

Track an allocated memory block in the @ref{fe,,tracemalloc} module.

Return @code{0} on success, return @code{-1} on error (failed to allocate memory to
store the trace). Return @code{-2} if tracemalloc is disabled.

If memory block is already tracked, update the existing trace.
@end deffn

@geindex PyTraceMalloc_Untrack (C function)
@anchor{c-api/memory c PyTraceMalloc_Untrack}@anchor{ba5}
@deffn {C Fonction} int PyTraceMalloc_Untrack (unsigned int domain, uintptr_t ptr)

Untrack an allocated memory block in the @ref{fe,,tracemalloc} module.
Do nothing if the block was not tracked.

Return @code{-2} if tracemalloc is disabled, otherwise return @code{0}.
@end deffn

@node Exemples<36>,,tracemalloc C API,Memory Management
@anchor{c-api/memory examples}@anchor{4cd0}@anchor{c-api/memory memoryexamples}@anchor{4cd1}
@subsection Exemples


Here is the example from section @ref{4cba,,Aperçu}, rewritten so that the
I/O buffer is allocated from the Python heap by using the first function set:

@example
PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;
@end example

The same code using the type-oriented function set:

@example
PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */

if (buf == NULL)
    return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyBytes_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;
@end example

Note that in the two examples above, the buffer is always manipulated via
functions belonging to the same set. Indeed, it is required to use the same
memory API family for a given memory block, so that the risk of mixing different
allocators is reduced to a minimum. The following code sequence contains two
errors, one of which is labeled as `fatal' because it mixes two different
allocators operating on different heaps.

@example
char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Del()  */
@end example

In addition to the functions aimed at handling raw memory blocks from the Python
heap, objects in Python are allocated and released with @ref{972,,PyObject_New},
@ref{973,,PyObject_NewVar} and @ref{1487,,PyObject_Del()}.

These will be explained in the next chapter on defining and implementing new
object types in C.

@node Implémentation d'objets,Version des API et ABI,Memory Management,Manuel de référence de l'API Python/C
@anchor{c-api/objimpl doc}@anchor{4cd2}@anchor{c-api/objimpl newtypes}@anchor{4cd3}@anchor{c-api/objimpl object-implementation-support}@anchor{4cd4}
@section Implémentation d'objets


Ce chapitre décrit les fonctions, types, et macros utilisées pour définir de nouveaux types d'objets.

@menu
* Allouer des objets dans le tas:: 
* Common Object Structures:: 
* Objets type: Objets type<3>. 
* Supporting Cyclic Garbage Collection:: 

@end menu

@node Allouer des objets dans le tas,Common Object Structures,,Implémentation d'objets
@anchor{c-api/allocation doc}@anchor{4cd5}@anchor{c-api/allocation allocating-objects}@anchor{4cd6}@anchor{c-api/allocation allocating-objects-on-the-heap}@anchor{4cd7}
@subsection Allouer des objets dans le tas


@geindex _PyObject_New (C function)
@anchor{c-api/allocation c _PyObject_New}@anchor{4cd8}
@deffn {C Fonction} @ref{32f,,PyObject} *_PyObject_New (PyTypeObject *type)
`Valeur de retour : nouvelle référence.'
@end deffn

@geindex _PyObject_NewVar (C function)
@anchor{c-api/allocation c _PyObject_NewVar}@anchor{4cd9}
@deffn {C Fonction} @ref{4094,,PyVarObject} *_PyObject_NewVar (PyTypeObject *type, Py_ssize_t size)
`Valeur de retour : nouvelle référence.'
@end deffn

@geindex PyObject_Init (C function)
@anchor{c-api/allocation c PyObject_Init}@anchor{a58}
@deffn {C Fonction} @ref{32f,,PyObject} *PyObject_Init (PyObject *op, PyTypeObject *type)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Initialize a newly allocated object `op' with its type and initial
reference.  Returns the initialized object.  Other fields of the object are
not affected.
@end deffn

@geindex PyObject_InitVar (C function)
@anchor{c-api/allocation c PyObject_InitVar}@anchor{18e2}
@deffn {C Fonction} @ref{4094,,PyVarObject} *PyObject_InitVar (PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
`Valeur de retour : référence empruntée.'` Part of the @ref{53e,,Stable ABI}.'
Effectue les mêmes opérations que @ref{a58,,PyObject_Init()} fait, et initialise également l'information de la longueur pour un objet de taille variable.
@end deffn

@geindex PyObject_New (C macro)
@anchor{c-api/allocation c PyObject_New}@anchor{972}
@deffn {C Macro} PyObject_New (TYPE, typeobj)

Allocate a new Python object using the C structure type `TYPE'
and the Python type object `typeobj' (@code{PyTypeObject*}).
Fields not defined by the Python object header are not initialized.
The caller will own the only reference to the object
(i.e. its reference count will be one).
The size of the memory allocation is determined from the
@ref{974,,tp_basicsize} field of the type object.
@end deffn

@geindex PyObject_NewVar (C macro)
@anchor{c-api/allocation c PyObject_NewVar}@anchor{973}
@deffn {C Macro} PyObject_NewVar (TYPE, typeobj, size)

Allocate a new Python object using the C structure type `TYPE' and the
Python type object `typeobj' (@code{PyTypeObject*}).
Fields not defined by the Python object header
are not initialized.  The allocated memory allows for the `TYPE' structure
plus `size' (@code{Py_ssize_t}) fields of the size
given by the @ref{1ef2,,tp_itemsize} field of
`typeobj'.  This is useful for implementing objects like tuples, which are
able to determine their size at construction time.  Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
@end deffn

@geindex PyObject_Del (C function)
@anchor{c-api/allocation c PyObject_Del}@anchor{1487}
@deffn {C Fonction} void PyObject_Del (void *op)

Releases memory allocated to an object using @ref{972,,PyObject_New} or
@ref{973,,PyObject_NewVar}.  This is normally called from the
@ref{47ee,,tp_dealloc} handler specified in the object's type.  The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.
@end deffn

@geindex _Py_NoneStruct (C var)
@anchor{c-api/allocation c _Py_NoneStruct}@anchor{4cda}
@deffn {C Variable} @ref{32f,,PyObject} _Py_NoneStruct

Objet qui est visible en tant que @code{None} dans Python. Ne devrait être accessible uniquement en utilisant la macro @ref{47c0,,Py_None}, qui évalue cet objet à un pointeur.
@end deffn


@subsubheading Voir aussi



@table @asis

@item @ref{47c4,,PyModule_Create()}

Allouer et créer des modules d'extension.
@end table


@node Common Object Structures,Objets type<3>,Allouer des objets dans le tas,Implémentation d'objets
@anchor{c-api/structures doc}@anchor{4cdb}@anchor{c-api/structures common-object-structures}@anchor{4cdc}@anchor{c-api/structures common-structs}@anchor{4cdd}
@subsection Common Object Structures


There are a large number of structures which are used in the definition of
object types for Python.  This section describes these structures and how they
are used.

@menu
* Base object types and macros:: 
* Implementing functions and methods:: 
* Accessing attributes of extension types:: 

@end menu

@node Base object types and macros,Implementing functions and methods,,Common Object Structures
@anchor{c-api/structures base-object-types-and-macros}@anchor{4cde}
@subsubsection Base object types and macros


All Python objects ultimately share a small number of fields at the beginning
of the object's representation in memory.  These are represented by the
@ref{32f,,PyObject} and @ref{4094,,PyVarObject} types, which are defined, in turn,
by the expansions of some macros also used, whether directly or indirectly, in
the definition of all other Python objects.  Additional macros can be found
under @ref{49e8,,reference counting}.

@geindex PyObject (C type)
@anchor{c-api/structures c PyObject}@anchor{32f}
@deffn {C Type} type PyObject
` Part of the @ref{53e,,Limited API}. (Only some members are part of the stable ABI.)'
All object types are extensions of this type.  This is a type which
contains the information Python needs to treat a pointer to an object as an
object.  In a normal "release" build, it contains only the object's
reference count and a pointer to the corresponding type object.
Nothing is actually declared to be a @ref{32f,,PyObject}, but every pointer
to a Python object can be cast to a @ref{32f,,PyObject}*.  Access to the
members must be done by using the macros @ref{896,,Py_REFCNT} and
@ref{76a,,Py_TYPE}.
@end deffn

@geindex PyVarObject (C type)
@anchor{c-api/structures c PyVarObject}@anchor{4094}
@deffn {C Type} type PyVarObject
` Part of the @ref{53e,,Limited API}. (Only some members are part of the stable ABI.)'
This is an extension of @ref{32f,,PyObject} that adds the @ref{499b,,ob_size}
field.  This is only used for objects that have some notion of `length'.
This type does not often appear in the Python/C API.
Access to the members must be done by using the macros
@ref{896,,Py_REFCNT}, @ref{76a,,Py_TYPE}, and @ref{76c,,Py_SIZE}.
@end deffn

@geindex PyObject_HEAD (C macro)
@anchor{c-api/structures c PyObject_HEAD}@anchor{12bc}
@deffn {C Macro} PyObject_HEAD

This is a macro used when declaring new types which represent objects
without a varying length.  The PyObject_HEAD macro expands to:

@example
PyObject ob_base;
@end example

See documentation of @ref{32f,,PyObject} above.
@end deffn

@geindex PyObject_VAR_HEAD (C macro)
@anchor{c-api/structures c PyObject_VAR_HEAD}@anchor{4cdf}
@deffn {C Macro} PyObject_VAR_HEAD

This is a macro used when declaring new types which represent objects
with a length that varies from instance to instance.
The PyObject_VAR_HEAD macro expands to:

@example
PyVarObject ob_base;
@end example

See documentation of @ref{4094,,PyVarObject} above.
@end deffn

@geindex Py_Is (C function)
@anchor{c-api/structures c Py_Is}@anchor{88c}
@deffn {C Fonction} int Py_Is (PyObject *x, PyObject *y)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Test if the `x' object is the `y' object, the same as @code{x is y} in Python.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_IsNone (C function)
@anchor{c-api/structures c Py_IsNone}@anchor{88d}
@deffn {C Fonction} int Py_IsNone (PyObject *x)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Test if an object is the @code{None} singleton,
the same as @code{x is None} in Python.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_IsTrue (C function)
@anchor{c-api/structures c Py_IsTrue}@anchor{88e}
@deffn {C Fonction} int Py_IsTrue (PyObject *x)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Test if an object is the @code{True} singleton,
the same as @code{x is True} in Python.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_IsFalse (C function)
@anchor{c-api/structures c Py_IsFalse}@anchor{88f}
@deffn {C Fonction} int Py_IsFalse (PyObject *x)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Test if an object is the @code{False} singleton,
the same as @code{x is False} in Python.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_TYPE (C function)
@anchor{c-api/structures c Py_TYPE}@anchor{76a}
@deffn {C Fonction} @ref{a93,,PyTypeObject} *Py_TYPE (PyObject *o)
`Valeur de retour : référence empruntée.'
Get the type of the Python object `o'.

Return a @ref{334,,borrowed reference}.

Use the @ref{76b,,Py_SET_TYPE()} function to set an object type.


Modifié dans la version 3.11: @ref{76a,,Py_TYPE()} is changed to an inline static function.
The parameter type is no longer const @ref{32f,,PyObject}*.

@end deffn

@geindex Py_IS_TYPE (C function)
@anchor{c-api/structures c Py_IS_TYPE}@anchor{17a3}
@deffn {C Fonction} int Py_IS_TYPE (PyObject *o, PyTypeObject *type)

Return non-zero if the object `o' type is `type'. Return zero otherwise.
Equivalent to: @code{Py_TYPE(o) == type}.


Ajouté dans la version 3.9.

@end deffn

@geindex Py_SET_TYPE (C function)
@anchor{c-api/structures c Py_SET_TYPE}@anchor{76b}
@deffn {C Fonction} void Py_SET_TYPE (PyObject *o, PyTypeObject *type)

Set the object `o' type to `type'.


Ajouté dans la version 3.9.

@end deffn

@geindex Py_SIZE (C function)
@anchor{c-api/structures c Py_SIZE}@anchor{76c}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} Py_SIZE (PyVarObject *o)

Get the size of the Python object `o'.

Use the @ref{76d,,Py_SET_SIZE()} function to set an object size.


Modifié dans la version 3.11: @ref{76c,,Py_SIZE()} is changed to an inline static function.
The parameter type is no longer const @ref{4094,,PyVarObject}*.

@end deffn

@geindex Py_SET_SIZE (C function)
@anchor{c-api/structures c Py_SET_SIZE}@anchor{76d}
@deffn {C Fonction} void Py_SET_SIZE (PyVarObject *o, Py_ssize_t size)

Set the object `o' size to `size'.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_HEAD_INIT (C macro)
@anchor{c-api/structures c PyObject_HEAD_INIT}@anchor{4ce0}
@deffn {C Macro} PyObject_HEAD_INIT (type)

This is a macro which expands to initialization values for a new
@ref{32f,,PyObject} type.  This macro expands to:

@example
_PyObject_EXTRA_INIT
1, type,
@end example
@end deffn

@geindex PyVarObject_HEAD_INIT (C macro)
@anchor{c-api/structures c PyVarObject_HEAD_INIT}@anchor{4ce1}
@deffn {C Macro} PyVarObject_HEAD_INIT (type, size)

This is a macro which expands to initialization values for a new
@ref{4094,,PyVarObject} type, including the @ref{499b,,ob_size} field.
This macro expands to:

@example
_PyObject_EXTRA_INIT
1, type, size,
@end example
@end deffn

@node Implementing functions and methods,Accessing attributes of extension types,Base object types and macros,Common Object Structures
@anchor{c-api/structures implementing-functions-and-methods}@anchor{4ce2}
@subsubsection Implementing functions and methods


@geindex PyCFunction (C type)
@anchor{c-api/structures c PyCFunction}@anchor{142b}
@deffn {C Type} type PyCFunction
` Part of the @ref{53e,,Stable ABI}.'
Type of the functions used to implement most Python callables in C.
Functions of this type take two @ref{32f,,PyObject}* parameters and return
one such value.  If the return value is @code{NULL}, an exception shall have
been set.  If not @code{NULL}, the return value is interpreted as the return
value of the function as exposed in Python.  The function must return a new
reference.

The function signature is:

@example
PyObject *PyCFunction(PyObject *self,
                      PyObject *args);
@end example
@end deffn

@geindex PyCFunctionWithKeywords (C type)
@anchor{c-api/structures c PyCFunctionWithKeywords}@anchor{487b}
@deffn {C Type} type PyCFunctionWithKeywords
` Part of the @ref{53e,,Stable ABI}.'
Type of the functions used to implement Python callables in C
with signature @ref{4ce3,,METH_VARARGS | METH_KEYWORDS}.
The function signature is:

@example
PyObject *PyCFunctionWithKeywords(PyObject *self,
                                  PyObject *args,
                                  PyObject *kwargs);
@end example
@end deffn

@geindex PyCFunctionFast (C type)
@anchor{c-api/structures c PyCFunctionFast}@anchor{4879}
@deffn {C Type} type PyCFunctionFast
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Type of the functions used to implement Python callables in C
with signature @ref{15b0,,METH_FASTCALL}.
The function signature is:

@example
PyObject *PyCFunctionFast(PyObject *self,
                          PyObject *const *args,
                          Py_ssize_t nargs);
@end example
@end deffn

@geindex PyCFunctionFastWithKeywords (C type)
@anchor{c-api/structures c PyCFunctionFastWithKeywords}@anchor{487a}
@deffn {C Type} type PyCFunctionFastWithKeywords
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.13.'
Type of the functions used to implement Python callables in C
with signature @ref{4ce4,,METH_FASTCALL | METH_KEYWORDS}.
The function signature is:

@example
PyObject *PyCFunctionFastWithKeywords(PyObject *self,
                                      PyObject *const *args,
                                      Py_ssize_t nargs,
                                      PyObject *kwnames);
@end example
@end deffn

@geindex PyCMethod (C type)
@anchor{c-api/structures c PyCMethod}@anchor{74e}
@deffn {C Type} type PyCMethod

Type of the functions used to implement Python callables in C
with signature @ref{1617,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
The function signature is:

@example
PyObject *PyCMethod(PyObject *self,
                    PyTypeObject *defining_class,
                    PyObject *const *args,
                    Py_ssize_t nargs,
                    PyObject *kwnames)
@end example


Ajouté dans la version 3.9.

@end deffn

@geindex PyMethodDef (C type)
@anchor{c-api/structures c PyMethodDef}@anchor{148d}
@deffn {C Type} type PyMethodDef
` Part of the @ref{53e,,Stable ABI} (including all members).'
Structure used to describe a method of an extension type.  This structure has
four fields:

@geindex PyMethodDef.ml_name (C member)
@anchor{c-api/structures c PyMethodDef ml_name}@anchor{4808}
@deffn {C Membre} const char *ml_name

Name of the method.
@end deffn

@geindex PyMethodDef.ml_meth (C member)
@anchor{c-api/structures c PyMethodDef ml_meth}@anchor{4ce5}
@deffn {C Membre} @ref{142b,,PyCFunction} ml_meth

Pointer to the C implementation.
@end deffn

@geindex PyMethodDef.ml_flags (C member)
@anchor{c-api/structures c PyMethodDef ml_flags}@anchor{4ce6}
@deffn {C Membre} int ml_flags

Flags bits indicating how the call should be constructed.
@end deffn

@geindex PyMethodDef.ml_doc (C member)
@anchor{c-api/structures c PyMethodDef ml_doc}@anchor{4ce7}
@deffn {C Membre} const char *ml_doc

Points to the contents of the docstring.
@end deffn
@end deffn

The @ref{4ce5,,ml_meth} is a C function pointer.
The functions may be of different
types, but they always return @ref{32f,,PyObject}*.  If the function is not of
the @ref{142b,,PyCFunction}, the compiler will require a cast in the method table.
Even though @ref{142b,,PyCFunction} defines the first parameter as
@ref{32f,,PyObject}*, it is common that the method implementation uses the
specific C type of the `self' object.

The @ref{4ce6,,ml_flags} field is a bitfield which can include
the following flags.
The individual flags indicate either a calling convention or a binding
convention.

There are these calling conventions:

@geindex METH_VARARGS (C macro)
@anchor{c-api/structures c METH_VARARGS}@anchor{14c0}
@deffn {C Macro} METH_VARARGS

This is the typical calling convention, where the methods have the type
@ref{142b,,PyCFunction}. The function expects two @ref{32f,,PyObject}* values.
The first one is the `self' object for methods; for module functions, it is
the module object.  The second parameter (often called `args') is a tuple
object representing all arguments. This parameter is typically processed
using @ref{55d,,PyArg_ParseTuple()} or @ref{14be,,PyArg_UnpackTuple()}.
@end deffn

@geindex METH_KEYWORDS (C macro)
@anchor{c-api/structures c METH_KEYWORDS}@anchor{47c3}
@deffn {C Macro} METH_KEYWORDS

Can only be used in certain combinations with other flags:
@ref{4ce3,,METH_VARARGS | METH_KEYWORDS},
@ref{4ce4,,METH_FASTCALL | METH_KEYWORDS} and
@ref{1617,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
@end deffn
@anchor{c-api/structures meth-varargs-meth-keywords}@anchor{4ce3}

@table @asis

@item @ref{14c0,,METH_VARARGS} | @ref{47c3,,METH_KEYWORDS}

Methods with these flags must be of type @ref{487b,,PyCFunctionWithKeywords}.
The function expects three parameters: `self', `args', `kwargs' where
`kwargs' is a dictionary of all the keyword arguments or possibly @code{NULL}
if there are no keyword arguments.  The parameters are typically processed
using @ref{379,,PyArg_ParseTupleAndKeywords()}.
@end table

@geindex METH_FASTCALL (C macro)
@anchor{c-api/structures c METH_FASTCALL}@anchor{15b0}
@deffn {C Macro} METH_FASTCALL

Fast calling convention supporting only positional arguments.
The methods have the type @ref{4879,,PyCFunctionFast}.
The first parameter is `self', the second parameter is a C array
of @ref{32f,,PyObject}* values indicating the arguments and the third
parameter is the number of arguments (the length of the array).


Ajouté dans la version 3.7.



Modifié dans la version 3.10: @code{METH_FASTCALL} is now part of the @ref{4861,,stable ABI}.

@end deffn
@anchor{c-api/structures meth-fastcall-meth-keywords}@anchor{4ce4}

@table @asis

@item @ref{15b0,,METH_FASTCALL} | @ref{47c3,,METH_KEYWORDS}

Extension of @ref{15b0,,METH_FASTCALL} supporting also keyword arguments,
with methods of type @ref{487a,,PyCFunctionFastWithKeywords}.
Keyword arguments are passed the same way as in the
@ref{53d,,vectorcall protocol}:
there is an additional fourth @ref{32f,,PyObject}* parameter
which is a tuple representing the names of the keyword arguments
(which are guaranteed to be strings)
or possibly @code{NULL} if there are no keywords.  The values of the keyword
arguments are stored in the `args' array, after the positional arguments.


Ajouté dans la version 3.7.

@end table

@geindex METH_METHOD (C macro)
@anchor{c-api/structures c METH_METHOD}@anchor{95d}
@deffn {C Macro} METH_METHOD

Can only be used in the combination with other flags:
@ref{1617,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}.
@end deffn
@anchor{c-api/structures meth-method-meth-fastcall-meth-keywords}@anchor{1617}

@table @asis

@item @ref{95d,,METH_METHOD} | @ref{15b0,,METH_FASTCALL} | @ref{47c3,,METH_KEYWORDS}

Extension of @ref{4ce4,,METH_FASTCALL | METH_KEYWORDS}
supporting the `defining class', that is,
the class that contains the method in question.
The defining class might be a superclass of @code{Py_TYPE(self)}.

The method needs to be of type @ref{74e,,PyCMethod}, the same as for
@code{METH_FASTCALL | METH_KEYWORDS} with @code{defining_class} argument added after
@code{self}.


Ajouté dans la version 3.9.

@end table

@geindex METH_NOARGS (C macro)
@anchor{c-api/structures c METH_NOARGS}@anchor{148a}
@deffn {C Macro} METH_NOARGS

Methods without parameters don't need to check whether arguments are given if
they are listed with the @ref{148a,,METH_NOARGS} flag.  They need to be of type
@ref{142b,,PyCFunction}.  The first parameter is typically named `self' and will
hold a reference to the module or object instance.  In all cases the second
parameter will be @code{NULL}.

The function must have 2 parameters. Since the second parameter is unused,
@ref{16a6,,Py_UNUSED} can be used to prevent a compiler warning.
@end deffn

@geindex METH_O (C macro)
@anchor{c-api/structures c METH_O}@anchor{14bf}
@deffn {C Macro} METH_O

Methods with a single object argument can be listed with the @ref{14bf,,METH_O}
flag, instead of invoking @ref{55d,,PyArg_ParseTuple()} with a @code{"O"} argument.
They have the type @ref{142b,,PyCFunction}, with the `self' parameter, and a
@ref{32f,,PyObject}* parameter representing the single argument.
@end deffn

These two constants are not used to indicate the calling convention but the
binding when use with methods of classes.  These may not be used for functions
defined for modules.  At most one of these flags may be set for any given
method.

@geindex METH_CLASS (C macro)
@anchor{c-api/structures c METH_CLASS}@anchor{148b}
@deffn {C Macro} METH_CLASS

@geindex built-in function;classmethod

The method will be passed the type object as the first parameter rather
than an instance of the type.  This is used to create `class methods',
similar to what is created when using the @ref{165,,classmethod()} built-in
function.
@end deffn

@geindex METH_STATIC (C macro)
@anchor{c-api/structures c METH_STATIC}@anchor{148c}
@deffn {C Macro} METH_STATIC

@geindex built-in function;staticmethod

The method will be passed @code{NULL} as the first parameter rather than an
instance of the type.  This is used to create `static methods', similar to
what is created when using the @ref{40c,,staticmethod()} built-in function.
@end deffn

One other constant controls whether a method is loaded in place of another
definition with the same method name.

@geindex METH_COEXIST (C macro)
@anchor{c-api/structures c METH_COEXIST}@anchor{142a}
@deffn {C Macro} METH_COEXIST

The method will be loaded in place of existing definitions.  Without
`METH_COEXIST', the default is to skip repeated definitions.  Since slot
wrappers are loaded before the method table, the existence of a
`sq_contains' slot, for example, would generate a wrapped method named
@ref{1ee0,,__contains__()} and preclude the loading of a corresponding
PyCFunction with the same name.  With the flag defined, the PyCFunction
will be loaded in place of the wrapper object and will co-exist with the
slot.  This is helpful because calls to PyCFunctions are optimized more
than wrapper object calls.
@end deffn

@geindex PyCMethod_New (C function)
@anchor{c-api/structures c PyCMethod_New}@anchor{187b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCMethod_New (PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Turn `ml' into a Python @ref{2870,,callable} object.
The caller must ensure that `ml' outlives the @ref{2870,,callable}.
Typically, `ml' is defined as a static variable.

The `self' parameter will be passed as the `self' argument
to the C function in @code{ml->ml_meth} when invoked.
`self' can be @code{NULL}.

The @ref{2870,,callable} object's @code{__module__} attribute
can be set from the given `module' argument.
`module' should be a Python string,
which will be used as name of the module the function is defined in.
If unavailable, it can be set to @ref{660,,None} or @code{NULL}.


@subsubheading Voir aussi


@ref{1e81,,function.__module__}


The `cls' parameter will be passed as the `defining_class'
argument to the C function.
Must be set if @ref{95d,,METH_METHOD} is set on @code{ml->ml_flags}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyCFunction_NewEx (C function)
@anchor{c-api/structures c PyCFunction_NewEx}@anchor{191b}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCFunction_NewEx (PyMethodDef *ml, PyObject *self, PyObject *module)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI}.'
Equivalent to @code{PyCMethod_New(ml, self, module, NULL)}.
@end deffn

@geindex PyCFunction_New (C function)
@anchor{c-api/structures c PyCFunction_New}@anchor{1881}
@deffn {C Fonction} @ref{32f,,PyObject} *PyCFunction_New (PyMethodDef *ml, PyObject *self)
`Valeur de retour : nouvelle référence.'` Part of the @ref{53e,,Stable ABI} Depuis la version 3.4.'
Equivalent to @code{PyCMethod_New(ml, self, NULL, NULL)}.
@end deffn

@node Accessing attributes of extension types,,Implementing functions and methods,Common Object Structures
@anchor{c-api/structures accessing-attributes-of-extension-types}@anchor{4ce8}
@subsubsection Accessing attributes of extension types


@geindex PyMemberDef (C type)
@anchor{c-api/structures c PyMemberDef}@anchor{53a}
@deffn {C Type} type PyMemberDef
` Part of the @ref{53e,,Stable ABI} (including all members).'
Structure which describes an attribute of a type which corresponds to a C
struct member.
When defining a class, put a NULL-terminated array of these
structures in the @ref{47f1,,tp_members} slot.

Its fields are, in order:

@geindex PyMemberDef.name (C member)
@anchor{c-api/structures c PyMemberDef name}@anchor{4ce9}
@deffn {C Membre} const char *name

Name of the member.
A NULL value marks the end of a @code{PyMemberDef[]} array.

The string should be static, no copy is made of it.
@end deffn

@geindex PyMemberDef.type (C member)
@anchor{c-api/structures c PyMemberDef type}@anchor{4809}
@deffn {C Membre} int type

The type of the member in the C struct.
See @ref{15fc,,Member types} for the possible values.
@end deffn

@geindex PyMemberDef.offset (C member)
@anchor{c-api/structures c PyMemberDef offset}@anchor{4cea}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} offset

The offset in bytes that the member is located on the type’s object struct.
@end deffn

@geindex PyMemberDef.flags (C member)
@anchor{c-api/structures c PyMemberDef flags}@anchor{480a}
@deffn {C Membre} int flags

Zero or more of the @ref{4ceb,,Member flags}, combined using bitwise OR.
@end deffn

@geindex PyMemberDef.doc (C member)
@anchor{c-api/structures c PyMemberDef doc}@anchor{4cec}
@deffn {C Membre} const char *doc

The docstring, or NULL.
The string should be static, no copy is made of it.
Typically, it is defined using @ref{1799,,PyDoc_STR}.
@end deffn

By default (when @ref{480a,,flags} is @code{0}), members allow
both read and write access.
Use the @ref{57d,,Py_READONLY} flag for read-only access.
Certain types, like @ref{4ced,,Py_T_STRING}, imply @ref{57d,,Py_READONLY}.
Only @ref{580,,Py_T_OBJECT_EX} (and legacy @ref{57f,,T_OBJECT}) members can
be deleted.
@anchor{c-api/structures pymemberdef-offsets}@anchor{4abe}
For heap-allocated types (created using @ref{569,,PyType_FromSpec()} or similar),
@code{PyMemberDef} may contain a definition for the special member
@code{"__vectorcalloffset__"}, corresponding to
@ref{4a5f,,tp_vectorcall_offset} in type objects.
These must be defined with @code{Py_T_PYSSIZET} and @code{Py_READONLY}, for example:

@example
static PyMemberDef spam_type_members[] = @{
    @{"__vectorcalloffset__", Py_T_PYSSIZET,
     offsetof(Spam_object, vectorcall), Py_READONLY@},
    @{NULL@}  /* Sentinel */
@};
@end example

(You may need to @code{#include <stddef.h>} for @code{offsetof()}.)

The legacy offsets @ref{4abd,,tp_dictoffset} and
@ref{975,,tp_weaklistoffset} can be defined similarly using
@code{"__dictoffset__"} and @code{"__weaklistoffset__"} members, but extensions
are strongly encouraged to use @ref{361,,Py_TPFLAGS_MANAGED_DICT} and
@ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} instead.


Modifié dans la version 3.12: @code{PyMemberDef} is always available.
Previously, it required including @code{"structmember.h"}.

@end deffn

@geindex PyMember_GetOne (C function)
@anchor{c-api/structures c PyMember_GetOne}@anchor{579}
@deffn {C Fonction} @ref{32f,,PyObject} *PyMember_GetOne (const char *obj_addr, struct PyMemberDef *m)
` Part of the @ref{53e,,Stable ABI}.'
Get an attribute belonging to the object at address `obj_addr'.  The
attribute is described by @code{PyMemberDef} `m'.  Returns @code{NULL}
on error.


Modifié dans la version 3.12: @code{PyMember_GetOne} is always available.
Previously, it required including @code{"structmember.h"}.

@end deffn

@geindex PyMember_SetOne (C function)
@anchor{c-api/structures c PyMember_SetOne}@anchor{57a}
@deffn {C Fonction} int PyMember_SetOne (char *obj_addr, struct PyMemberDef *m, PyObject *o)
` Part of the @ref{53e,,Stable ABI}.'
Set an attribute belonging to the object at address `obj_addr' to object `o'.
The attribute to set is described by @code{PyMemberDef} `m'.  Returns @code{0}
if successful and a negative value on failure.


Modifié dans la version 3.12: @code{PyMember_SetOne} is always available.
Previously, it required including @code{"structmember.h"}.

@end deffn

@menu
* Member flags:: 
* Member types:: 
* Defining Getters and Setters:: 

@end menu

@node Member flags,Member types,,Accessing attributes of extension types
@anchor{c-api/structures member-flags}@anchor{4cee}@anchor{c-api/structures pymemberdef-flags}@anchor{4ceb}
@subsubsection Member flags


The following flags can be used with @ref{480a,,PyMemberDef.flags}:

@geindex Py_READONLY (C macro)
@anchor{c-api/structures c Py_READONLY}@anchor{57d}
@deffn {C Macro} Py_READONLY

Not writable.
@end deffn

@geindex Py_AUDIT_READ (C macro)
@anchor{c-api/structures c Py_AUDIT_READ}@anchor{57e}
@deffn {C Macro} Py_AUDIT_READ

Emit an @code{object.__getattr__} @ref{17fe,,audit event}
before reading.
@end deffn

@geindex Py_RELATIVE_OFFSET (C macro)
@anchor{c-api/structures c Py_RELATIVE_OFFSET}@anchor{539}
@deffn {C Macro} Py_RELATIVE_OFFSET

Indicates that the @ref{4cea,,offset} of this @code{PyMemberDef}
entry indicates an offset from the subclass-specific data, rather than
from @code{PyObject}.

Can only be used as part of @ref{47f1,,Py_tp_members}
@ref{4961,,slot} when creating a class using negative
@ref{533,,basicsize}.
It is mandatory in that case.

This flag is only used in @ref{4961,,PyType_Slot}.
When setting @ref{47f1,,tp_members} during
class creation, Python clears it and sets
@ref{4cea,,PyMemberDef.offset} to the offset from the @code{PyObject} struct.
@end deffn

@geindex READ_RESTRICTED (C macro)
@geindex WRITE_RESTRICTED (C macro)
@geindex RESTRICTED (C macro)


Modifié dans la version 3.10: The @code{RESTRICTED}, @code{READ_RESTRICTED} and
@code{WRITE_RESTRICTED} macros available with
@code{#include "structmember.h"} are deprecated.
@code{READ_RESTRICTED} and @code{RESTRICTED} are equivalent to
@ref{57e,,Py_AUDIT_READ}; @code{WRITE_RESTRICTED} does nothing.


@geindex READONLY (C macro)


Modifié dans la version 3.12: The @code{READONLY} macro was renamed to @ref{57d,,Py_READONLY}.
The @code{PY_AUDIT_READ} macro was renamed with the @code{Py_} prefix.
The new names are now always available.
Previously, these required @code{#include "structmember.h"}.
The header is still available and it provides the old names.


@node Member types,Defining Getters and Setters,Member flags,Accessing attributes of extension types
@anchor{c-api/structures member-types}@anchor{4cef}@anchor{c-api/structures pymemberdef-types}@anchor{15fc}
@subsubsection Member types


@ref{4809,,PyMemberDef.type} can be one of the following macros corresponding
to various C types.
When the member is accessed in Python, it will be converted to the
equivalent Python type.
When it is set from Python, it will be converted back to the C type.
If that is not possible, an exception such as @ref{522,,TypeError} or
@ref{1ff,,ValueError} is raised.

Unless marked (D), attributes defined this way cannot be deleted
using e.g. @ref{1734,,del} or @ref{20da,,delattr()}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Macro name

@tab

Type C

@tab

Type Python

@item

@geindex Py_T_BYTE (C macro)
@anchor{c-api/structures c Py_T_BYTE}@anchor{4cf0}
@deffn {C Macro} Py_T_BYTE
@end deffn

@tab

char

@tab

@ref{254,,int}

@item

@geindex Py_T_SHORT (C macro)
@anchor{c-api/structures c Py_T_SHORT}@anchor{4cf1}
@deffn {C Macro} Py_T_SHORT
@end deffn

@tab

short

@tab

@ref{254,,int}

@item

@geindex Py_T_INT (C macro)
@anchor{c-api/structures c Py_T_INT}@anchor{57b}
@deffn {C Macro} Py_T_INT
@end deffn

@tab

int

@tab

@ref{254,,int}

@item

@geindex Py_T_LONG (C macro)
@anchor{c-api/structures c Py_T_LONG}@anchor{4cf2}
@deffn {C Macro} Py_T_LONG
@end deffn

@tab

long

@tab

@ref{254,,int}

@item

@geindex Py_T_LONGLONG (C macro)
@anchor{c-api/structures c Py_T_LONGLONG}@anchor{4cf3}
@deffn {C Macro} Py_T_LONGLONG
@end deffn

@tab

long long

@tab

@ref{254,,int}

@item

@geindex Py_T_UBYTE (C macro)
@anchor{c-api/structures c Py_T_UBYTE}@anchor{4cf4}
@deffn {C Macro} Py_T_UBYTE
@end deffn

@tab

unsigned char

@tab

@ref{254,,int}

@item

@geindex Py_T_UINT (C macro)
@anchor{c-api/structures c Py_T_UINT}@anchor{4cf5}
@deffn {C Macro} Py_T_UINT
@end deffn

@tab

unsigned int

@tab

@ref{254,,int}

@item

@geindex Py_T_USHORT (C macro)
@anchor{c-api/structures c Py_T_USHORT}@anchor{4cf6}
@deffn {C Macro} Py_T_USHORT
@end deffn

@tab

unsigned short

@tab

@ref{254,,int}

@item

@geindex Py_T_ULONG (C macro)
@anchor{c-api/structures c Py_T_ULONG}@anchor{4cf7}
@deffn {C Macro} Py_T_ULONG
@end deffn

@tab

unsigned long

@tab

@ref{254,,int}

@item

@geindex Py_T_ULONGLONG (C macro)
@anchor{c-api/structures c Py_T_ULONGLONG}@anchor{4cf8}
@deffn {C Macro} Py_T_ULONGLONG
@end deffn

@tab

unsigned long long

@tab

@ref{254,,int}

@item

@geindex Py_T_PYSSIZET (C macro)
@anchor{c-api/structures c Py_T_PYSSIZET}@anchor{4cf9}
@deffn {C Macro} Py_T_PYSSIZET
@end deffn

@tab

@ref{a4e,,Py_ssize_t}

@tab

@ref{254,,int}

@item

@geindex Py_T_FLOAT (C macro)
@anchor{c-api/structures c Py_T_FLOAT}@anchor{4cfa}
@deffn {C Macro} Py_T_FLOAT
@end deffn

@tab

float

@tab

@ref{2eb,,float}

@item

@geindex Py_T_DOUBLE (C macro)
@anchor{c-api/structures c Py_T_DOUBLE}@anchor{57c}
@deffn {C Macro} Py_T_DOUBLE
@end deffn

@tab

double

@tab

@ref{2eb,,float}

@item

@geindex Py_T_BOOL (C macro)
@anchor{c-api/structures c Py_T_BOOL}@anchor{4cfb}
@deffn {C Macro} Py_T_BOOL
@end deffn

@tab

char
(written as 0 or 1)

@tab

@ref{451,,bool}

@item

@geindex Py_T_STRING (C macro)
@anchor{c-api/structures c Py_T_STRING}@anchor{4ced}
@deffn {C Macro} Py_T_STRING
@end deffn

@tab

const char* (*)

@tab

@ref{435,,str} (RO)

@item

@geindex Py_T_STRING_INPLACE (C macro)
@anchor{c-api/structures c Py_T_STRING_INPLACE}@anchor{4cfc}
@deffn {C Macro} Py_T_STRING_INPLACE
@end deffn

@tab

const char[] (*)

@tab

@ref{435,,str} (RO)

@item

@geindex Py_T_CHAR (C macro)
@anchor{c-api/structures c Py_T_CHAR}@anchor{4cfd}
@deffn {C Macro} Py_T_CHAR
@end deffn

@tab

char (0-127)

@tab

@ref{435,,str} (**)

@item

@geindex Py_T_OBJECT_EX (C macro)
@anchor{c-api/structures c Py_T_OBJECT_EX}@anchor{580}
@deffn {C Macro} Py_T_OBJECT_EX
@end deffn

@tab

@ref{32f,,PyObject}*

@tab

@ref{a7a,,object} (D)

@end multitable


@quotation

(*): Zero-terminated, UTF8-encoded C string.
With @code{Py_T_STRING} the C representation is a pointer;
with @code{Py_T_STRING_INPLACE} the string is stored directly
in the structure.

(**): String of length 1. Only ASCII is accepted.

(RO): Implies @ref{57d,,Py_READONLY}.

(D): Can be deleted, in which case the pointer is set to @code{NULL}.
Reading a @code{NULL} pointer raises @ref{343,,AttributeError}.
@end quotation

@geindex T_BYTE (C macro)
@geindex T_SHORT (C macro)
@geindex T_INT (C macro)
@geindex T_LONG (C macro)
@geindex T_LONGLONG (C macro)
@geindex T_UBYTE (C macro)
@geindex T_USHORT (C macro)
@geindex T_UINT (C macro)
@geindex T_ULONG (C macro)
@geindex T_ULONGULONG (C macro)
@geindex T_PYSSIZET (C macro)
@geindex T_FLOAT (C macro)
@geindex T_DOUBLE (C macro)
@geindex T_BOOL (C macro)
@geindex T_CHAR (C macro)
@geindex T_STRING (C macro)
@geindex T_STRING_INPLACE (C macro)
@geindex T_OBJECT_EX (C macro)
@geindex structmember.h


Ajouté dans la version 3.12: In previous versions, the macros were only available with
@code{#include "structmember.h"} and were named without the @code{Py_} prefix
(e.g. as @code{T_INT}).
The header is still available and contains the old names, along with
the following deprecated types:

@geindex T_OBJECT (C macro)
@anchor{c-api/structures c T_OBJECT}@anchor{57f}
@deffn {C Macro} T_OBJECT

Like @code{Py_T_OBJECT_EX}, but @code{NULL} is converted to @code{None}.
This results in surprising behavior in Python: deleting the attribute
effectively sets it to @code{None}.
@end deffn

@geindex T_NONE (C macro)
@anchor{c-api/structures c T_NONE}@anchor{581}
@deffn {C Macro} T_NONE

Always @code{None}. Must be used with @ref{57d,,Py_READONLY}.
@end deffn


@node Defining Getters and Setters,,Member types,Accessing attributes of extension types
@anchor{c-api/structures defining-getters-and-setters}@anchor{4cfe}
@subsubsection Defining Getters and Setters


@geindex PyGetSetDef (C type)
@anchor{c-api/structures c PyGetSetDef}@anchor{ba6}
@deffn {C Type} type PyGetSetDef
` Part of the @ref{53e,,Stable ABI} (including all members).'
Structure to define property-like access for a type. See also description of
the @ref{47f6,,PyTypeObject.tp_getset} slot.

@geindex PyGetSetDef.name (C member)
@anchor{c-api/structures c PyGetSetDef name}@anchor{4cff}
@deffn {C Membre} const char *name

attribute name
@end deffn

@geindex PyGetSetDef.get (C member)
@anchor{c-api/structures c PyGetSetDef get}@anchor{4d00}
@deffn {C Membre} @ref{49b6,,getter} get

C function to get the attribute.
@end deffn

@geindex PyGetSetDef.set (C member)
@anchor{c-api/structures c PyGetSetDef set}@anchor{4d01}
@deffn {C Membre} @ref{49c4,,setter} set

Optional C function to set or delete the attribute.
If @code{NULL}, the attribute is read-only.
@end deffn

@geindex PyGetSetDef.doc (C member)
@anchor{c-api/structures c PyGetSetDef doc}@anchor{4d02}
@deffn {C Membre} const char *doc

optional docstring
@end deffn

@geindex PyGetSetDef.closure (C member)
@anchor{c-api/structures c PyGetSetDef closure}@anchor{4d03}
@deffn {C Membre} void *closure

Optional user data pointer, providing additional data for getter and setter.
@end deffn
@end deffn

@geindex getter (C type)
@anchor{c-api/structures c getter}@anchor{49b6}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*getter)(@ref{32f,,PyObject}*, void*)
` Part of the @ref{53e,,Stable ABI}.'
The @code{get} function takes one @ref{32f,,PyObject}* parameter (the
instance) and a user data pointer (the associated @code{closure}):

It should return a new reference on success or @code{NULL} with a set exception
on failure.
@end deffn

@geindex setter (C type)
@anchor{c-api/structures c setter}@anchor{49c4}
@deffn {C Type} typedef int (*setter)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, void*)
` Part of the @ref{53e,,Stable ABI}.'
@code{set} functions take two @ref{32f,,PyObject}* parameters (the instance and
the value to be set) and a user data pointer (the associated @code{closure}):

In case the attribute should be deleted the second parameter is @code{NULL}.
Should return @code{0} on success or @code{-1} with a set exception on failure.
@end deffn

@node Objets type<3>,Supporting Cyclic Garbage Collection,Common Object Structures,Implémentation d'objets
@anchor{c-api/typeobj doc}@anchor{4d04}@anchor{c-api/typeobj type-objects}@anchor{4d05}@anchor{c-api/typeobj type-structs}@anchor{97a}
@subsection Objets type


Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the @ref{a93,,PyTypeObject} structure.  Type
objects can be handled using any of the @code{PyObject_*} or
@code{PyType_*} functions, but do not offer much that's interesting to most
Python applications. These objects are fundamental to how objects behave, so
they are very important to the interpreter itself and to any extension module
that implements new types.

Type objects are fairly large compared to most of the standard types. The reason
for the size is that each type object stores a large number of values, mostly C
function pointers, each of which implements a small part of the type's
functionality.  The fields of the type object are examined in detail in this
section.  The fields will be described in the order in which they occur in the
structure.

In addition to the following quick reference, the @ref{4d06,,Exemples}
section provides at-a-glance insight into the meaning and use of
@ref{a93,,PyTypeObject}.

@menu
* Quick Reference:: 
* PyTypeObject Definition:: 
* PyObject Slots:: 
* PyVarObject Slots:: 
* PyTypeObject Slots:: 
* Static Types:: 
* Heap Types:: 
* Number Object Structures:: 
* Mapping Object Structures:: 
* Sequence Object Structures:: 
* Buffer Object Structures:: 
* Async Object Structures:: 
* Slot Type typedefs:: 
* Exemples: Exemples<37>. 

@end menu

@node Quick Reference,PyTypeObject Definition,,Objets type<3>
@anchor{c-api/typeobj quick-reference}@anchor{4d07}
@subsubsection Quick Reference


@menu
* "tp slots":: 
* sub-slots:: 
* slot typedefs:: 

@end menu

@node "tp slots",sub-slots,,Quick Reference
@anchor{c-api/typeobj tp-slots}@anchor{4d08}@anchor{c-api/typeobj tp-slots-table}@anchor{4d09}
@subsubsection "tp slots"



@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} {xxx} {xxx} {xxx} {xxx} 
@headitem

PyTypeObject Slot @footnote{
`()': A slot name in parentheses indicates it is (effectively) deprecated.

`<>': Names in angle brackets should be initially set to @code{NULL} and
treated as read-only.

`[]': Names in square brackets are for internal use only.

`<R>' (as a prefix) means the field is required (must be non-@code{NULL}).
}

@tab

@ref{4d0a,,Type}

@tab

special
methods/attrs

@tab

Info @footnote{
Columns:

`"O"':  set on @code{PyBaseObject_Type}

`"T"':  set on @ref{538,,PyType_Type}

`"D"':  default (if slot is set to @code{NULL})

@example
X - PyType_Ready sets this value if it is NULL
~ - PyType_Ready always sets this value (it should be NULL)
? - PyType_Ready may set this value depending on other slots

Also see the inheritance column ("I").
@end example

`"I"':  inheritance

@example
X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value
% - the slots of the sub-struct are inherited individually
G - inherited, but only in combination with other slots; see the slot's description
? - it's complicated; see the slot's description
@end example

Note that some slots are effectively inherited through the normal
attribute lookup chain.
}

@tab

@tab

@tab

@item

O

@tab

T

@tab

D

@tab

I

@item

<R> @ref{1880,,tp_name}

@tab

const char *

@tab

__name__

@tab

X

@tab

X

@tab

@tab

@item

@ref{974,,tp_basicsize}

@tab

@ref{a4e,,Py_ssize_t}

@tab

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{1ef2,,tp_itemsize}

@tab

@ref{a4e,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

X

@item

@ref{47ee,,tp_dealloc}

@tab

@ref{49b1,,destructor}

@tab

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{4a5f,,tp_vectorcall_offset}

@tab

@ref{a4e,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

X

@item

(@ref{480c,,tp_getattr})

@tab

@ref{49b2,,getattrfunc}

@tab

__getattribute__,
__getattr__

@tab

@tab

@tab

@tab

G

@item

(@ref{480d,,tp_setattr})

@tab

@ref{49c2,,setattrfunc}

@tab

__setattr__,
__delattr__

@tab

@tab

@tab

@tab

G

@item

@ref{eb8,,tp_as_async}

@tab

@ref{4abb,,PyAsyncMethods} *

@tab

@ref{4d0b,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{4803,,tp_repr}

@tab

@ref{49c0,,reprfunc}

@tab

__repr__

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{978,,tp_as_number}

@tab

@ref{13d4,,PyNumberMethods} *

@tab

@ref{4d0b,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{4d0c,,tp_as_sequence}

@tab

@ref{4813,,PySequenceMethods} *

@tab

@ref{4d0b,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{4d0d,,tp_as_mapping}

@tab

@ref{4814,,PyMappingMethods} *

@tab

@ref{4d0b,,sub-slots}

@tab

@tab

@tab

@tab

%

@item

@ref{4815,,tp_hash}

@tab

@ref{49b7,,hashfunc}

@tab

__hash__

@tab

X

@tab

@tab

@tab

G

@item

@ref{544,,tp_call}

@tab

@ref{49c7,,ternaryfunc}

@tab

__call__

@tab

@tab

X

@tab

@tab

X

@item

@ref{4804,,tp_str}

@tab

@ref{49c0,,reprfunc}

@tab

__str__

@tab

X

@tab

@tab

@tab

X

@item

@ref{167b,,tp_getattro}

@tab

@ref{49b3,,getattrofunc}

@tab

__getattribute__,
__getattr__

@tab

X

@tab

X

@tab

@tab

G

@item

@ref{4807,,tp_setattro}

@tab

@ref{49c3,,setattrofunc}

@tab

__setattr__,
__delattr__

@tab

X

@tab

X

@tab

@tab

G

@item

@ref{976,,tp_as_buffer}

@tab

@ref{4ac3,,PyBufferProcs} *

@tab

@tab

@tab

@tab

@tab

%

@item

@ref{184b,,tp_flags}

@tab

@code{unsigned long}

@tab

@tab

X

@tab

X

@tab

@tab

?

@item

@ref{47ea,,tp_doc}

@tab

const char *

@tab

__doc__

@tab

X

@tab

X

@tab

@tab

@item

@ref{768,,tp_traverse}

@tab

@ref{49c8,,traverseproc}

@tab

@tab

@tab

X

@tab

@tab

G

@item

@ref{4801,,tp_clear}

@tab

@ref{49b9,,inquiry}

@tab

@tab

@tab

X

@tab

@tab

G

@item

@ref{480f,,tp_richcompare}

@tab

@ref{49c1,,richcmpfunc}

@tab

__lt__,
__le__,
__eq__,
__ne__,
__gt__,
__ge__

@tab

X

@tab

@tab

@tab

G

@item

(@ref{975,,tp_weaklistoffset})

@tab

@ref{a4e,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

?

@item

@ref{14a4,,tp_iter}

@tab

@ref{49b5,,getiterfunc}

@tab

__iter__

@tab

@tab

@tab

@tab

X

@item

@ref{14a5,,tp_iternext}

@tab

@ref{49ba,,iternextfunc}

@tab

__next__

@tab

@tab

@tab

@tab

X

@item

@ref{47f3,,tp_methods}

@tab

@ref{148d,,PyMethodDef} []

@tab

@tab

X

@tab

X

@tab

@tab

@item

@ref{47f1,,tp_members}

@tab

@ref{53a,,PyMemberDef} []

@tab

@tab

@tab

X

@tab

@tab

@item

@ref{47f6,,tp_getset}

@tab

@ref{ba6,,PyGetSetDef} []

@tab

@tab

X

@tab

X

@tab

@tab

@item

@ref{47fa,,tp_base}

@tab

@ref{a93,,PyTypeObject} *

@tab

__base__

@tab

@tab

@tab

X

@tab

@item

@ref{16a9,,tp_dict}

@tab

@ref{32f,,PyObject} *

@tab

__dict__

@tab

@tab

@tab

?

@tab

@item

@ref{4d0e,,tp_descr_get}

@tab

@ref{49af,,descrgetfunc}

@tab

__get__

@tab

@tab

@tab

@tab

X

@item

@ref{1884,,tp_descr_set}

@tab

@ref{49b0,,descrsetfunc}

@tab

__set__,
__delete__

@tab

@tab

@tab

@tab

X

@item

(@ref{4abd,,tp_dictoffset})

@tab

@ref{a4e,,Py_ssize_t}

@tab

@tab

@tab

X

@tab

@tab

?

@item

@ref{56d,,tp_init}

@tab

@ref{49b8,,initproc}

@tab

__init__

@tab

X

@tab

X

@tab

@tab

X

@item

@ref{47f0,,tp_alloc}

@tab

@ref{49ad,,allocfunc}

@tab

@tab

X

@tab

@tab

?

@tab

?

@item

@ref{56b,,tp_new}

@tab

@ref{49bc,,newfunc}

@tab

__new__

@tab

X

@tab

X

@tab

?

@tab

?

@item

@ref{47ef,,tp_free}

@tab

@ref{4bb2,,freefunc}

@tab

@tab

X

@tab

X

@tab

?

@tab

?

@item

@ref{4d0f,,tp_is_gc}

@tab

@ref{49b9,,inquiry}

@tab

@tab

@tab

X

@tab

@tab

X

@item

<@ref{4d10,,tp_bases}>

@tab

@ref{32f,,PyObject} *

@tab

__bases__

@tab

@tab

@tab

~

@tab

@item

<@ref{4ac0,,tp_mro}>

@tab

@ref{32f,,PyObject} *

@tab

__mro__

@tab

@tab

@tab

~

@tab

@item

[@ref{4ac1,,tp_cache}]

@tab

@ref{32f,,PyObject} *

@tab

@tab

@tab

@tab

@tab

@item

[@ref{55e,,tp_subclasses}]

@tab

void *

@tab

__subclasses__

@tab

@tab

@tab

@tab

@item

[@ref{4ac2,,tp_weaklist}]

@tab

@ref{32f,,PyObject} *

@tab

@tab

@tab

@tab

@tab

@item

(@ref{4d11,,tp_del})

@tab

@ref{49b1,,destructor}

@tab

@tab

@tab

@tab

@tab

@item

[@ref{4d12,,tp_version_tag}]

@tab

@code{unsigned int}

@tab

@tab

@tab

@tab

@tab

@item

@ref{a94,,tp_finalize}

@tab

@ref{49b1,,destructor}

@tab

__del__

@tab

@tab

@tab

@tab

X

@item

@ref{4abf,,tp_vectorcall}

@tab

@ref{542,,vectorcallfunc}

@tab

@tab

@tab

@tab

@tab

@item

[@ref{4d13,,tp_watched}]

@tab

unsigned char

@tab

@tab

@tab

@tab

@tab

@end multitable


@node sub-slots,slot typedefs,"tp slots",Quick Reference
@anchor{c-api/typeobj id3}@anchor{4d14}@anchor{c-api/typeobj sub-slots}@anchor{4d0b}
@subsubsection sub-slots



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Slot

@tab

@ref{4d0a,,Type}

@tab

special
methods

@item

@ref{4d15,,am_await}

@tab

@ref{49c9,,unaryfunc}

@tab

__await__

@item

@ref{4d16,,am_aiter}

@tab

@ref{49c9,,unaryfunc}

@tab

__aiter__

@item

@ref{4d17,,am_anext}

@tab

@ref{49c9,,unaryfunc}

@tab

__anext__

@item

@ref{4d18,,am_send}

@tab

@ref{4d19,,sendfunc}

@tab

@item

@tab

@tab

@item

@ref{4ab4,,nb_add}

@tab

@ref{49ae,,binaryfunc}

@tab

__add__
__radd__

@item

@ref{4d1a,,nb_inplace_add}

@tab

@ref{49ae,,binaryfunc}

@tab

__iadd__

@item

@ref{4d1b,,nb_subtract}

@tab

@ref{49ae,,binaryfunc}

@tab

__sub__
__rsub__

@item

@ref{4d1c,,nb_inplace_subtract}

@tab

@ref{49ae,,binaryfunc}

@tab

__isub__

@item

@ref{4d1d,,nb_multiply}

@tab

@ref{49ae,,binaryfunc}

@tab

__mul__
__rmul__

@item

@ref{4d1e,,nb_inplace_multiply}

@tab

@ref{49ae,,binaryfunc}

@tab

__imul__

@item

@ref{4d1f,,nb_remainder}

@tab

@ref{49ae,,binaryfunc}

@tab

__mod__
__rmod__

@item

@ref{4d20,,nb_inplace_remainder}

@tab

@ref{49ae,,binaryfunc}

@tab

__imod__

@item

@ref{4d21,,nb_divmod}

@tab

@ref{49ae,,binaryfunc}

@tab

__divmod__
__rdivmod__

@item

@ref{4d22,,nb_power}

@tab

@ref{49c7,,ternaryfunc}

@tab

__pow__
__rpow__

@item

@ref{4d23,,nb_inplace_power}

@tab

@ref{49c7,,ternaryfunc}

@tab

__ipow__

@item

@ref{4d24,,nb_negative}

@tab

@ref{49c9,,unaryfunc}

@tab

__neg__

@item

@ref{4d25,,nb_positive}

@tab

@ref{49c9,,unaryfunc}

@tab

__pos__

@item

@ref{4d26,,nb_absolute}

@tab

@ref{49c9,,unaryfunc}

@tab

__abs__

@item

@ref{4d27,,nb_bool}

@tab

@ref{49b9,,inquiry}

@tab

__bool__

@item

@ref{4d28,,nb_invert}

@tab

@ref{49c9,,unaryfunc}

@tab

__invert__

@item

@ref{4d29,,nb_lshift}

@tab

@ref{49ae,,binaryfunc}

@tab

__lshift__
__rlshift__

@item

@ref{4d2a,,nb_inplace_lshift}

@tab

@ref{49ae,,binaryfunc}

@tab

__ilshift__

@item

@ref{4d2b,,nb_rshift}

@tab

@ref{49ae,,binaryfunc}

@tab

__rshift__
__rrshift__

@item

@ref{4d2c,,nb_inplace_rshift}

@tab

@ref{49ae,,binaryfunc}

@tab

__irshift__

@item

@ref{4d2d,,nb_and}

@tab

@ref{49ae,,binaryfunc}

@tab

__and__
__rand__

@item

@ref{4d2e,,nb_inplace_and}

@tab

@ref{49ae,,binaryfunc}

@tab

__iand__

@item

@ref{4d2f,,nb_xor}

@tab

@ref{49ae,,binaryfunc}

@tab

__xor__
__rxor__

@item

@ref{4d30,,nb_inplace_xor}

@tab

@ref{49ae,,binaryfunc}

@tab

__ixor__

@item

@ref{4d31,,nb_or}

@tab

@ref{49ae,,binaryfunc}

@tab

__or__
__ror__

@item

@ref{4d32,,nb_inplace_or}

@tab

@ref{49ae,,binaryfunc}

@tab

__ior__

@item

@ref{4d33,,nb_int}

@tab

@ref{49c9,,unaryfunc}

@tab

__int__

@item

@ref{4d34,,nb_reserved}

@tab

void *

@tab

@item

@ref{4d35,,nb_float}

@tab

@ref{49c9,,unaryfunc}

@tab

__float__

@item

@ref{4d36,,nb_floor_divide}

@tab

@ref{49ae,,binaryfunc}

@tab

__floordiv__

@item

@ref{4d37,,nb_inplace_floor_divide}

@tab

@ref{49ae,,binaryfunc}

@tab

__ifloordiv__

@item

@ref{4d38,,nb_true_divide}

@tab

@ref{49ae,,binaryfunc}

@tab

__truediv__

@item

@ref{4d39,,nb_inplace_true_divide}

@tab

@ref{49ae,,binaryfunc}

@tab

__itruediv__

@item

@ref{13d3,,nb_index}

@tab

@ref{49c9,,unaryfunc}

@tab

__index__

@item

@ref{4d3a,,nb_matrix_multiply}

@tab

@ref{49ae,,binaryfunc}

@tab

__matmul__
__rmatmul__

@item

@ref{4d3b,,nb_inplace_matrix_multiply}

@tab

@ref{49ae,,binaryfunc}

@tab

__imatmul__

@item

@tab

@tab

@item

@ref{4d3c,,mp_length}

@tab

@ref{49bb,,lenfunc}

@tab

__len__

@item

@ref{18bb,,mp_subscript}

@tab

@ref{49ae,,binaryfunc}

@tab

__getitem__

@item

@ref{4d3d,,mp_ass_subscript}

@tab

@ref{49bd,,objobjargproc}

@tab

__setitem__,
__delitem__

@item

@tab

@tab

@item

@ref{4abc,,sq_length}

@tab

@ref{49bb,,lenfunc}

@tab

__len__

@item

@ref{4d3e,,sq_concat}

@tab

@ref{49ae,,binaryfunc}

@tab

__add__

@item

@ref{4d3f,,sq_repeat}

@tab

@ref{49c5,,ssizeargfunc}

@tab

__mul__

@item

@ref{18ba,,sq_item}

@tab

@ref{49c5,,ssizeargfunc}

@tab

__getitem__

@item

@ref{4d40,,sq_ass_item}

@tab

@ref{49c6,,ssizeobjargproc}

@tab

__setitem__
__delitem__

@item

@ref{4d41,,sq_contains}

@tab

@ref{49be,,objobjproc}

@tab

__contains__

@item

@ref{4d42,,sq_inplace_concat}

@tab

@ref{49ae,,binaryfunc}

@tab

__iadd__

@item

@ref{4d43,,sq_inplace_repeat}

@tab

@ref{49c5,,ssizeargfunc}

@tab

__imul__

@item

@tab

@tab

@item

@ref{74c,,bf_getbuffer}

@tab

@ref{49b4,,getbufferproc()}

@tab

@item

@ref{74d,,bf_releasebuffer}

@tab

@ref{49bf,,releasebufferproc()}

@tab

@end multitable


@node slot typedefs,,sub-slots,Quick Reference
@anchor{c-api/typeobj slot-typedefs}@anchor{4d44}@anchor{c-api/typeobj slot-typedefs-table}@anchor{4d0a}
@subsubsection slot typedefs



@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

typedef

@tab

Parameter Types

@tab

Return Type

@item

@ref{49ad,,allocfunc}

@tab


@display
@ref{a93,,PyTypeObject} *@w{ }
@ref{a4e,,Py_ssize_t}@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49b1,,destructor}

@tab

@ref{32f,,PyObject} *

@tab

void

@item

@ref{4bb2,,freefunc}

@tab

void *

@tab

void

@item

@ref{49c8,,traverseproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{49ca,,visitproc}@w{ }
void *@w{ }
@end display



@tab

`int'

@item

@ref{49bc,,newfunc}

@tab


@display
@ref{a93,,PyTypeObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49b8,,initproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@item

@ref{49c0,,reprfunc}

@tab

@ref{32f,,PyObject} *

@tab

@ref{32f,,PyObject} *

@item

@ref{49b2,,getattrfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
const char *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49c2,,setattrfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
const char *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@item

@ref{49b3,,getattrofunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49c3,,setattrofunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@item

@ref{49af,,descrgetfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49b0,,descrsetfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@item

@ref{49b7,,hashfunc}

@tab

@ref{32f,,PyObject} *

@tab

Py_hash_t

@item

@ref{49c1,,richcmpfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
`int'@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49b5,,getiterfunc}

@tab

@ref{32f,,PyObject} *

@tab

@ref{32f,,PyObject} *

@item

@ref{49ba,,iternextfunc}

@tab

@ref{32f,,PyObject} *

@tab

@ref{32f,,PyObject} *

@item

@ref{49bb,,lenfunc}

@tab

@ref{32f,,PyObject} *

@tab

@ref{a4e,,Py_ssize_t}

@item

@ref{49b4,,getbufferproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{742,,Py_buffer} *@w{ }
`int'@w{ }
@end display



@tab

`int'

@item

@ref{49bf,,releasebufferproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{742,,Py_buffer} *@w{ }
@end display



@tab

void

@item

@ref{49b9,,inquiry}

@tab

@ref{32f,,PyObject} *

@tab

`int'

@item

@ref{49c9,,unaryfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49ae,,binaryfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49c7,,ternaryfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49c5,,ssizeargfunc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{a4e,,Py_ssize_t}@w{ }
@end display



@tab

@ref{32f,,PyObject} *

@item

@ref{49c6,,ssizeobjargproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{a4e,,Py_ssize_t}@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@item

@ref{49be,,objobjproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@item

@ref{49bd,,objobjargproc}

@tab


@display
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@ref{32f,,PyObject} *@w{ }
@end display



@tab

`int'

@end multitable


See @ref{4d45,,Slot Type typedefs} below for more detail.

@node PyTypeObject Definition,PyObject Slots,Quick Reference,Objets type<3>
@anchor{c-api/typeobj pytypeobject-definition}@anchor{4d46}
@subsubsection PyTypeObject Definition


The structure definition for @ref{a93,,PyTypeObject} can be found in
@code{Include/object.h}.  For convenience of reference, this repeats the
definition found there:

@c XXX Drop this?

@example
typedef struct _typeobject @{
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    Py_ssize_t tp_vectorcall_offset;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* Assigned meaning in release 2.0 */
    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* Assigned meaning in release 2.1 */
    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    // Strong reference on a heap type, borrowed reference on a static type
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;
    vectorcallfunc tp_vectorcall;

    /* bitset of which type-watchers care about this type */
    unsigned char tp_watched;
@} PyTypeObject;
@end example

@node PyObject Slots,PyVarObject Slots,PyTypeObject Definition,Objets type<3>
@anchor{c-api/typeobj pyobject-slots}@anchor{4d47}
@subsubsection PyObject Slots


The type object structure extends the @ref{4094,,PyVarObject} structure. The
@ref{499b,,ob_size} field is used for dynamic types (created by @code{type_new()},
usually called from a class statement). Note that @ref{538,,PyType_Type} (the
metatype) initializes @ref{1ef2,,tp_itemsize}, which means that its instances (i.e.
type objects) `must' have the @ref{499b,,ob_size} field.

@geindex PyObject.ob_refcnt (C member)
@anchor{c-api/typeobj c PyObject ob_refcnt}@anchor{88b}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} @ref{32f,,PyObject}.ob_refcnt
` Part of the @ref{53e,,Stable ABI}.'
This is the type object's reference count, initialized to @code{1} by the
@code{PyObject_HEAD_INIT} macro.  Note that for @ref{769,,statically allocated type objects}, the type's instances (objects whose @ref{47ec,,ob_type}
points back to the type) do `not' count as references.  But for
@ref{952,,dynamically allocated type objects}, the instances `do'
count as references.

`Inheritance:'

This field is not inherited by subtypes.
@end deffn

@geindex PyObject.ob_type (C member)
@anchor{c-api/typeobj c PyObject ob_type}@anchor{47ec}
@deffn {C Membre} @ref{a93,,PyTypeObject} *@ref{32f,,PyObject}.ob_type
` Part of the @ref{53e,,Stable ABI}.'
This is the type's type, in other words its metatype.  It is initialized by the
argument to the @code{PyObject_HEAD_INIT} macro, and its value should normally be
@code{&PyType_Type}.  However, for dynamically loadable extension modules that must
be usable on Windows (at least), the compiler complains that this is not a valid
initializer.  Therefore, the convention is to pass @code{NULL} to the
@code{PyObject_HEAD_INIT} macro and to initialize this field explicitly at the
start of the module's initialization function, before doing anything else.  This
is typically done like this:

@example
Foo_Type.ob_type = &PyType_Type;
@end example

This should be done before any instances of the type are created.
@ref{766,,PyType_Ready()} checks if @ref{47ec,,ob_type} is @code{NULL}, and if so,
initializes it to the @ref{47ec,,ob_type} field of the base class.
@ref{766,,PyType_Ready()} will not change this field if it is non-zero.

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@node PyVarObject Slots,PyTypeObject Slots,PyObject Slots,Objets type<3>
@anchor{c-api/typeobj pyvarobject-slots}@anchor{4d48}
@subsubsection PyVarObject Slots


@geindex PyVarObject.ob_size (C member)
@anchor{c-api/typeobj c PyVarObject ob_size}@anchor{499b}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} @ref{4094,,PyVarObject}.ob_size
` Part of the @ref{53e,,Stable ABI}.'
For @ref{769,,statically allocated type objects}, this should be
initialized to zero. For @ref{952,,dynamically allocated type objects}, this field has a special internal meaning.

`Inheritance:'

This field is not inherited by subtypes.
@end deffn

@node PyTypeObject Slots,Static Types,PyVarObject Slots,Objets type<3>
@anchor{c-api/typeobj pytypeobject-slots}@anchor{4d49}
@subsubsection PyTypeObject Slots


Each slot has a section describing inheritance.  If @ref{766,,PyType_Ready()}
may set a value when the field is set to @code{NULL} then there will also be
a "Default" section.  (Note that many fields set on @code{PyBaseObject_Type}
and @ref{538,,PyType_Type} effectively act as defaults.)

@geindex PyTypeObject.tp_name (C member)
@anchor{c-api/typeobj c PyTypeObject tp_name}@anchor{1880}
@deffn {C Membre} const char *@ref{a93,,PyTypeObject}.tp_name

Pointer to a NUL-terminated string containing the name of the type. For types
that are accessible as module globals, the string should be the full module
name, followed by a dot, followed by the type name; for built-in types, it
should be just the type name.  If the module is a submodule of a package, the
full package name is part of the full module name.  For example, a type named
@code{T} defined in module @code{M} in subpackage @code{Q} in package @code{P}
should have the @ref{1880,,tp_name} initializer @code{"P.Q.M.T"}.

For @ref{952,,dynamically allocated type objects},
this should just be the type name, and
the module name explicitly stored in the type dict as the value for key
@code{'__module__'}.

For @ref{769,,statically allocated type objects},
the `tp_name' field should contain a dot.
Everything before the last dot is made accessible as the @ref{36a,,__module__}
attribute, and everything after the last dot is made accessible as the
@ref{145f,,__name__} attribute.

If no dot is present, the entire @ref{1880,,tp_name} field is made accessible as the
@ref{145f,,__name__} attribute, and the @ref{36a,,__module__} attribute is undefined
(unless explicitly set in the dictionary, as explained above).  This means your
type will be impossible to pickle.  Additionally, it will not be listed in
module documentations created with pydoc.

This field must not be @code{NULL}.  It is the only required field
in @ref{a93,,PyTypeObject()} (other than potentially
@ref{1ef2,,tp_itemsize}).

`Inheritance:'

This field is not inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_basicsize (C member)
@geindex PyTypeObject.tp_itemsize (C member)
@anchor{c-api/typeobj c PyTypeObject tp_basicsize}@anchor{974}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} @ref{a93,,PyTypeObject}.tp_basicsize
@anchor{c-api/typeobj c PyTypeObject tp_itemsize}@anchor{1ef2}
@deffnx {C Membre} @ref{a4e,,Py_ssize_t} @ref{a93,,PyTypeObject}.tp_itemsize

These fields allow calculating the size in bytes of instances of the type.

There are two kinds of types: types with fixed-length instances have a zero
@ref{1ef2,,tp_itemsize} field, types with variable-length instances have a non-zero
@ref{1ef2,,tp_itemsize} field.  For a type with fixed-length instances, all
instances have the same size, given in @ref{974,,tp_basicsize}.

For a type with variable-length instances, the instances must have an
@ref{499b,,ob_size} field, and the instance size is @ref{974,,tp_basicsize} plus N
times @ref{1ef2,,tp_itemsize}, where N is the "length" of the object.  The value of
N is typically stored in the instance's @ref{499b,,ob_size} field.  There are
exceptions:  for example, ints use a negative @ref{499b,,ob_size} to indicate a
negative number, and N is @code{abs(ob_size)} there.  Also, the presence of an
@ref{499b,,ob_size} field in the instance layout doesn't mean that the instance
structure is variable-length (for example, the structure for the list type has
fixed-length instances, yet those instances have a meaningful @ref{499b,,ob_size}
field).

The basic size includes the fields in the instance declared by the macro
@ref{12bc,,PyObject_HEAD} or @ref{4cdf,,PyObject_VAR_HEAD} (whichever is used to
declare the instance struct) and this in turn includes the  @code{_ob_prev} and
@code{_ob_next} fields if they are present.  This means that the only correct
way to get an initializer for the @ref{974,,tp_basicsize} is to use the
@code{sizeof} operator on the struct used to declare the instance layout.
The basic size does not include the GC header size.

A note about alignment: if the variable items require a particular alignment,
this should be taken care of by the value of @ref{974,,tp_basicsize}.  Example:
suppose a type implements an array of @code{double}. @ref{1ef2,,tp_itemsize} is
@code{sizeof(double)}. It is the programmer's responsibility that
@ref{974,,tp_basicsize} is a multiple of @code{sizeof(double)} (assuming this is the
alignment requirement for @code{double}).

For any type with variable-length instances, this field must not be @code{NULL}.

`Inheritance:'

These fields are inherited separately by subtypes.  If the base type has a
non-zero @ref{1ef2,,tp_itemsize}, it is generally not safe to set
@ref{1ef2,,tp_itemsize} to a different non-zero value in a subtype (though this
depends on the implementation of the base type).
@end deffn

@geindex PyTypeObject.tp_dealloc (C member)
@anchor{c-api/typeobj c PyTypeObject tp_dealloc}@anchor{47ee}
@deffn {C Membre} @ref{49b1,,destructor} @ref{a93,,PyTypeObject}.tp_dealloc

A pointer to the instance destructor function.  This function must be defined
unless the type guarantees that its instances will never be deallocated (as is
the case for the singletons @code{None} and @code{Ellipsis}).  The function signature is:

@example
void tp_dealloc(PyObject *self);
@end example

The destructor function is called by the @ref{55b,,Py_DECREF()} and
@ref{779,,Py_XDECREF()} macros when the new reference count is zero.  At this point,
the instance is still in existence, but there are no references to it.  The
destructor function should free all references which the instance owns, free all
memory buffers owned by the instance (using the freeing function corresponding
to the allocation function used to allocate the buffer), and call the type's
@ref{47ef,,tp_free} function.  If the type is not subtypable
(doesn't have the @ref{47f4,,Py_TPFLAGS_BASETYPE} flag bit set), it is
permissible to call the object deallocator directly instead of via
@ref{47ef,,tp_free}.  The object deallocator should be the one used to allocate the
instance; this is normally @ref{1487,,PyObject_Del()} if the instance was allocated
using @ref{972,,PyObject_New} or @ref{973,,PyObject_NewVar}, or
@ref{14bb,,PyObject_GC_Del()} if the instance was allocated using
@ref{a90,,PyObject_GC_New} or @ref{a91,,PyObject_GC_NewVar}.

If the type supports garbage collection (has the @ref{767,,Py_TPFLAGS_HAVE_GC}
flag bit set), the destructor should call @ref{14bd,,PyObject_GC_UnTrack()}
before clearing any member fields.

@example
static void foo_dealloc(foo_object *self) @{
    PyObject_GC_UnTrack(self);
    Py_CLEAR(self->ref);
    Py_TYPE(self)->tp_free((PyObject *)self);
@}
@end example

Finally, if the type is heap allocated (@ref{89c,,Py_TPFLAGS_HEAPTYPE}), the
deallocator should release the owned reference to its type object
(via @ref{55b,,Py_DECREF()})  after
calling the type deallocator. In order to avoid dangling pointers, the
recommended way to achieve this is:

@example
static void foo_dealloc(foo_object *self) @{
    PyTypeObject *tp = Py_TYPE(self);
    // free references and buffers here
    tp->tp_free(self);
    Py_DECREF(tp);
@}
@end example

@cartouche
@quotation Avertissement 
In a garbage collected Python, @code{tp_dealloc} may be called from
any Python thread, not just the thread which created the object (if the
object becomes part of a refcount cycle, that cycle might be collected by
a garbage collection on any thread).  This is not a problem for Python
API calls, since the thread on which @code{tp_dealloc} is called
will own the Global Interpreter Lock (GIL).  However, if the object being
destroyed in turn destroys objects from some other C or C++ library, care
should be taken to ensure that destroying those objects on the thread
which called @code{tp_dealloc} will not violate any assumptions of
the library.
@end quotation
@end cartouche

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_vectorcall_offset (C member)
@anchor{c-api/typeobj c PyTypeObject tp_vectorcall_offset}@anchor{4a5f}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} @ref{a93,,PyTypeObject}.tp_vectorcall_offset

An optional offset to a per-instance function that implements calling
the object using the @ref{53d,,vectorcall protocol},
a more efficient alternative
of the simpler @ref{544,,tp_call}.

This field is only used if the flag @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL}
is set. If so, this must be a positive integer containing the offset in the
instance of a @ref{542,,vectorcallfunc} pointer.

The `vectorcallfunc' pointer may be @code{NULL}, in which case the instance behaves
as if @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} was not set: calling the instance
falls back to @ref{544,,tp_call}.

Any class that sets @code{Py_TPFLAGS_HAVE_VECTORCALL} must also set
@ref{544,,tp_call} and make sure its behaviour is consistent
with the `vectorcallfunc' function.
This can be done by setting `tp_call' to @ref{541,,PyVectorcall_Call()}.


Modifié dans la version 3.8: Before version 3.8, this slot was named @code{tp_print}.
In Python 2.x, it was used for printing to a file.
In Python 3.0 to 3.7, it was unused.



Modifié dans la version 3.12: Before version 3.12, it was not recommended for
@ref{952,,mutable heap types} to implement the vectorcall
protocol.
When a user sets @ref{543,,__call__} in Python code, only `tp_call' is
updated, likely making it inconsistent with the vectorcall function.
Since 3.12, setting @code{__call__} will disable vectorcall optimization
by clearing the @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag.


`Inheritance:'

This field is always inherited.
However, the @ref{53f,,Py_TPFLAGS_HAVE_VECTORCALL} flag is not
always inherited. If it's not set, then the subclass won't use
@ref{53d,,vectorcall}, except when
@ref{541,,PyVectorcall_Call()} is explicitly called.
@end deffn

@geindex PyTypeObject.tp_getattr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_getattr}@anchor{480c}
@deffn {C Membre} @ref{49b2,,getattrfunc} @ref{a93,,PyTypeObject}.tp_getattr

An optional pointer to the get-attribute-string function.

This field is deprecated.  When it is defined, it should point to a function
that acts the same as the @ref{167b,,tp_getattro} function, but taking a C string
instead of a Python string object to give the attribute name.

`Inheritance:'

Group: @ref{480c,,tp_getattr}, @ref{167b,,tp_getattro}

This field is inherited by subtypes together with @ref{167b,,tp_getattro}: a subtype
inherits both @ref{480c,,tp_getattr} and @ref{167b,,tp_getattro} from its base type when
the subtype's @ref{480c,,tp_getattr} and @ref{167b,,tp_getattro} are both @code{NULL}.
@end deffn

@geindex PyTypeObject.tp_setattr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_setattr}@anchor{480d}
@deffn {C Membre} @ref{49c2,,setattrfunc} @ref{a93,,PyTypeObject}.tp_setattr

An optional pointer to the function for setting and deleting attributes.

This field is deprecated.  When it is defined, it should point to a function
that acts the same as the @ref{4807,,tp_setattro} function, but taking a C string
instead of a Python string object to give the attribute name.

`Inheritance:'

Group: @ref{480d,,tp_setattr}, @ref{4807,,tp_setattro}

This field is inherited by subtypes together with @ref{4807,,tp_setattro}: a subtype
inherits both @ref{480d,,tp_setattr} and @ref{4807,,tp_setattro} from its base type when
the subtype's @ref{480d,,tp_setattr} and @ref{4807,,tp_setattro} are both @code{NULL}.
@end deffn

@geindex PyTypeObject.tp_as_async (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_async}@anchor{eb8}
@deffn {C Membre} @ref{4abb,,PyAsyncMethods} *@ref{a93,,PyTypeObject}.tp_as_async

Pointer to an additional structure that contains fields relevant only to
objects which implement @ref{1ab,,awaitable} and @ref{1a9,,asynchronous iterator}
protocols at the C-level.  See @ref{4d4a,,Async Object Structures} for details.


Ajouté dans la version 3.5: Formerly known as @code{tp_compare} and @code{tp_reserved}.


`Inheritance:'

The @ref{eb8,,tp_as_async} field is not inherited,
but the contained fields are inherited individually.
@end deffn

@geindex PyTypeObject.tp_repr (C member)
@anchor{c-api/typeobj c PyTypeObject tp_repr}@anchor{4803}
@deffn {C Membre} @ref{49c0,,reprfunc} @ref{a93,,PyTypeObject}.tp_repr

@geindex built-in function;repr

An optional pointer to a function that implements the built-in function
@ref{7e7,,repr()}.

The signature is the same as for @ref{1018,,PyObject_Repr()}:

@example
PyObject *tp_repr(PyObject *self);
@end example

The function must return a string or a Unicode object.  Ideally,
this function should return a string that, when passed to
@ref{17e,,eval()}, given a suitable environment, returns an object with the
same value.  If this is not feasible, it should return a string starting with
@code{'<'} and ending with @code{'>'} from which both the type and the value of the
object can be deduced.

`Inheritance:'

This field is inherited by subtypes.

`Default:'

When this field is not set, a string of the form @code{<%s object at %p>} is
returned, where @code{%s} is replaced by the type name, and @code{%p} by the object's
memory address.
@end deffn

@geindex PyTypeObject.tp_as_number (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_number}@anchor{978}
@deffn {C Membre} @ref{13d4,,PyNumberMethods} *@ref{a93,,PyTypeObject}.tp_as_number

Pointer to an additional structure that contains fields relevant only to
objects which implement the number protocol.  These fields are documented in
@ref{4d4b,,Number Object Structures}.

`Inheritance:'

The @ref{978,,tp_as_number} field is not inherited, but the contained fields are
inherited individually.
@end deffn

@geindex PyTypeObject.tp_as_sequence (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_sequence}@anchor{4d0c}
@deffn {C Membre} @ref{4813,,PySequenceMethods} *@ref{a93,,PyTypeObject}.tp_as_sequence

Pointer to an additional structure that contains fields relevant only to
objects which implement the sequence protocol.  These fields are documented
in @ref{4d4c,,Sequence Object Structures}.

`Inheritance:'

The @ref{4d0c,,tp_as_sequence} field is not inherited, but the contained fields
are inherited individually.
@end deffn

@geindex PyTypeObject.tp_as_mapping (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_mapping}@anchor{4d0d}
@deffn {C Membre} @ref{4814,,PyMappingMethods} *@ref{a93,,PyTypeObject}.tp_as_mapping

Pointer to an additional structure that contains fields relevant only to
objects which implement the mapping protocol.  These fields are documented in
@ref{4d4d,,Mapping Object Structures}.

`Inheritance:'

The @ref{4d0d,,tp_as_mapping} field is not inherited, but the contained fields
are inherited individually.
@end deffn

@geindex PyTypeObject.tp_hash (C member)
@anchor{c-api/typeobj c PyTypeObject tp_hash}@anchor{4815}
@deffn {C Membre} @ref{49b7,,hashfunc} @ref{a93,,PyTypeObject}.tp_hash

@geindex built-in function;hash

An optional pointer to a function that implements the built-in function
@ref{5d5,,hash()}.

The signature is the same as for @ref{3f9,,PyObject_Hash()}:

@example
Py_hash_t tp_hash(PyObject *);
@end example

The value @code{-1} should not be returned as a
normal return value; when an error occurs during the computation of the hash
value, the function should set an exception and return @code{-1}.

When this field is not set (`and' @ref{480f,,tp_richcompare} is not set),
an attempt to take the hash of the object raises @ref{522,,TypeError}.
This is the same as setting it to @ref{137d,,PyObject_HashNotImplemented()}.

This field can be set explicitly to @ref{137d,,PyObject_HashNotImplemented()} to
block inheritance of the hash method from a parent type. This is interpreted
as the equivalent of @code{__hash__ = None} at the Python level, causing
@code{isinstance(o, collections.Hashable)} to correctly return @code{False}. Note
that the converse is also true - setting @code{__hash__ = None} on a class at
the Python level will result in the @code{tp_hash} slot being set to
@ref{137d,,PyObject_HashNotImplemented()}.

`Inheritance:'

Group: @ref{4815,,tp_hash}, @ref{480f,,tp_richcompare}

This field is inherited by subtypes together with
@ref{480f,,tp_richcompare}: a subtype inherits both of
@ref{480f,,tp_richcompare} and @ref{4815,,tp_hash}, when the subtype's
@ref{480f,,tp_richcompare} and @ref{4815,,tp_hash} are both @code{NULL}.

`Default:'

@code{PyBaseObject_Type} uses @ref{35d,,PyObject_GenericHash()}.
@end deffn

@geindex PyTypeObject.tp_call (C member)
@anchor{c-api/typeobj c PyTypeObject tp_call}@anchor{544}
@deffn {C Membre} @ref{49c7,,ternaryfunc} @ref{a93,,PyTypeObject}.tp_call

An optional pointer to a function that implements calling the object.  This
should be @code{NULL} if the object is not callable.  The signature is the same as
for @ref{393,,PyObject_Call()}:

@example
PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs);
@end example

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_str (C member)
@anchor{c-api/typeobj c PyTypeObject tp_str}@anchor{4804}
@deffn {C Membre} @ref{49c0,,reprfunc} @ref{a93,,PyTypeObject}.tp_str

An optional pointer to a function that implements the built-in operation
@ref{435,,str()}.  (Note that @ref{435,,str} is a type now, and @ref{435,,str()} calls the
constructor for that type.  This constructor calls @ref{1019,,PyObject_Str()} to do
the actual work, and @ref{1019,,PyObject_Str()} will call this handler.)

The signature is the same as for @ref{1019,,PyObject_Str()}:

@example
PyObject *tp_str(PyObject *self);
@end example

The function must return a string or a Unicode object.  It should be a "friendly" string
representation of the object, as this is the representation that will be used,
among other things, by the @ref{f60,,print()} function.

`Inheritance:'

This field is inherited by subtypes.

`Default:'

When this field is not set, @ref{1018,,PyObject_Repr()} is called to return a string
representation.
@end deffn

@geindex PyTypeObject.tp_getattro (C member)
@anchor{c-api/typeobj c PyTypeObject tp_getattro}@anchor{167b}
@deffn {C Membre} @ref{49b3,,getattrofunc} @ref{a93,,PyTypeObject}.tp_getattro

An optional pointer to the get-attribute function.

The signature is the same as for @ref{341,,PyObject_GetAttr()}:

@example
PyObject *tp_getattro(PyObject *self, PyObject *attr);
@end example

It is usually convenient to set this field to @ref{4925,,PyObject_GenericGetAttr()},
which implements the normal way of looking for object attributes.

`Inheritance:'

Group: @ref{480c,,tp_getattr}, @ref{167b,,tp_getattro}

This field is inherited by subtypes together with @ref{480c,,tp_getattr}: a subtype
inherits both @ref{480c,,tp_getattr} and @ref{167b,,tp_getattro} from its base type when
the subtype's @ref{480c,,tp_getattr} and @ref{167b,,tp_getattro} are both @code{NULL}.

`Default:'

@code{PyBaseObject_Type} uses @ref{4925,,PyObject_GenericGetAttr()}.
@end deffn

@geindex PyTypeObject.tp_setattro (C member)
@anchor{c-api/typeobj c PyTypeObject tp_setattro}@anchor{4807}
@deffn {C Membre} @ref{49c3,,setattrofunc} @ref{a93,,PyTypeObject}.tp_setattro

An optional pointer to the function for setting and deleting attributes.

The signature is the same as for @ref{492e,,PyObject_SetAttr()}:

@example
int tp_setattro(PyObject *self, PyObject *attr, PyObject *value);
@end example

In addition, setting `value' to @code{NULL} to delete an attribute must be
supported.  It is usually convenient to set this field to
@ref{4926,,PyObject_GenericSetAttr()}, which implements the normal
way of setting object attributes.

`Inheritance:'

Group: @ref{480d,,tp_setattr}, @ref{4807,,tp_setattro}

This field is inherited by subtypes together with @ref{480d,,tp_setattr}: a subtype
inherits both @ref{480d,,tp_setattr} and @ref{4807,,tp_setattro} from its base type when
the subtype's @ref{480d,,tp_setattr} and @ref{4807,,tp_setattro} are both @code{NULL}.

`Default:'

@code{PyBaseObject_Type} uses @ref{4926,,PyObject_GenericSetAttr()}.
@end deffn

@geindex PyTypeObject.tp_as_buffer (C member)
@anchor{c-api/typeobj c PyTypeObject tp_as_buffer}@anchor{976}
@deffn {C Membre} @ref{4ac3,,PyBufferProcs} *@ref{a93,,PyTypeObject}.tp_as_buffer

Pointer to an additional structure that contains fields relevant only to objects
which implement the buffer interface.  These fields are documented in
@ref{4a7f,,Buffer Object Structures}.

`Inheritance:'

The @ref{976,,tp_as_buffer} field is not inherited,
but the contained fields are inherited individually.
@end deffn

@geindex PyTypeObject.tp_flags (C member)
@anchor{c-api/typeobj c PyTypeObject tp_flags}@anchor{184b}
@deffn {C Membre} unsigned long @ref{a93,,PyTypeObject}.tp_flags

This field is a bit mask of various flags.  Some flags indicate variant
semantics for certain situations; others are used to indicate that certain
fields in the type object (or in the extension structures referenced via
@ref{978,,tp_as_number}, @ref{4d0c,,tp_as_sequence}, @ref{4d0d,,tp_as_mapping}, and
@ref{976,,tp_as_buffer}) that were historically not always present are valid; if
such a flag bit is clear, the type fields it guards must not be accessed and
must be considered to have a zero or @code{NULL} value instead.

`Inheritance:'

Inheritance of this field is complicated.  Most flag bits are inherited
individually, i.e. if the base type has a flag bit set, the subtype inherits
this flag bit.  The flag bits that pertain to extension structures are strictly
inherited if the extension structure is inherited, i.e. the base type's value of
the flag bit is copied into the subtype together with a pointer to the extension
structure.  The @ref{767,,Py_TPFLAGS_HAVE_GC} flag bit is inherited together with
the @ref{768,,tp_traverse} and @ref{4801,,tp_clear} fields, i.e. if the
@ref{767,,Py_TPFLAGS_HAVE_GC} flag bit is clear in the subtype and the
@ref{768,,tp_traverse} and @ref{4801,,tp_clear} fields in the subtype exist and have
@code{NULL} values.
.. XXX are most flag bits `really' inherited individually?

`Default:'

@code{PyBaseObject_Type} uses
@code{Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE}.

`Bit Masks:'

The following bit masks are currently defined; these can be ORed together using
the @code{|} operator to form the value of the @ref{184b,,tp_flags} field.  The macro
@ref{18e0,,PyType_HasFeature()} takes a type and a flags value, `tp' and `f', and
checks whether @code{tp->tp_flags & f} is non-zero.

@geindex Py_TPFLAGS_HEAPTYPE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HEAPTYPE}@anchor{89c}
@deffn {C Macro} Py_TPFLAGS_HEAPTYPE

This bit is set when the type object itself is allocated on the heap, for
example, types created dynamically using @ref{569,,PyType_FromSpec()}.  In this
case, the @ref{47ec,,ob_type} field of its instances is considered a reference to
the type, and the type object is INCREF'ed when a new instance is created, and
DECREF'ed when an instance is destroyed (this does not apply to instances of
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
DECREF'ed). Heap types should also @ref{4d4e,,support garbage collection}
as they can form a reference cycle with their own module object.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_BASETYPE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_BASETYPE}@anchor{47f4}
@deffn {C Macro} Py_TPFLAGS_BASETYPE

This bit is set when the type can be used as the base type of another type.  If
this bit is clear, the type cannot be subtyped (similar to a "final" class in
Java).

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_READY (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_READY}@anchor{4d4f}
@deffn {C Macro} Py_TPFLAGS_READY

This bit is set when the type object has been fully initialized by
@ref{766,,PyType_Ready()}.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_READYING (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_READYING}@anchor{4d50}
@deffn {C Macro} Py_TPFLAGS_READYING

This bit is set while @ref{766,,PyType_Ready()} is in the process of initializing
the type object.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_HAVE_GC (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_GC}@anchor{767}
@deffn {C Macro} Py_TPFLAGS_HAVE_GC

This bit is set when the object supports garbage collection.  If this bit
is set, instances must be created using @ref{a90,,PyObject_GC_New} and
destroyed using @ref{14bb,,PyObject_GC_Del()}.  More information in section
@ref{4d4e,,Supporting Cyclic Garbage Collection}.  This bit also implies that the
GC-related fields @ref{768,,tp_traverse} and @ref{4801,,tp_clear} are present in
the type object.

`Inheritance:'

Group: @ref{767,,Py_TPFLAGS_HAVE_GC}, @ref{768,,tp_traverse}, @ref{4801,,tp_clear}

The @ref{767,,Py_TPFLAGS_HAVE_GC} flag bit is inherited
together with the @ref{768,,tp_traverse} and @ref{4801,,tp_clear}
fields, i.e.  if the @ref{767,,Py_TPFLAGS_HAVE_GC} flag bit is
clear in the subtype and the @ref{768,,tp_traverse} and
@ref{4801,,tp_clear} fields in the subtype exist and have @code{NULL}
values.
@end deffn

@geindex Py_TPFLAGS_DEFAULT (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_DEFAULT}@anchor{47e9}
@deffn {C Macro} Py_TPFLAGS_DEFAULT

This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
the following bits: @code{Py_TPFLAGS_HAVE_STACKLESS_EXTENSION}.

`Inheritance:'

???
@end deffn

@geindex Py_TPFLAGS_METHOD_DESCRIPTOR (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_METHOD_DESCRIPTOR}@anchor{4a67}
@deffn {C Macro} Py_TPFLAGS_METHOD_DESCRIPTOR

This bit indicates that objects behave like unbound methods.

If this flag is set for @code{type(meth)}, then:


@itemize -

@item 
@code{meth.__get__(obj, cls)(*args, **kwds)} (with @code{obj} not None)
must be equivalent to @code{meth(obj, *args, **kwds)}.

@item 
@code{meth.__get__(None, cls)(*args, **kwds)}
must be equivalent to @code{meth(*args, **kwds)}.
@end itemize

This flag enables an optimization for typical method calls like
@code{obj.meth()}: it avoids creating a temporary "bound method" object for
@code{obj.meth}.


Ajouté dans la version 3.8.


`Inheritance:'

This flag is never inherited by types without the
@ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} flag set.  For extension types, it is
inherited whenever @ref{4d0e,,tp_descr_get} is inherited.
@end deffn

@geindex Py_TPFLAGS_MANAGED_DICT (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MANAGED_DICT}@anchor{361}
@deffn {C Macro} Py_TPFLAGS_MANAGED_DICT

This bit indicates that instances of the class have a @cite{~object.__dict__}
attribute, and that the space for the dictionary is managed by the VM.

If this flag is set, @ref{767,,Py_TPFLAGS_HAVE_GC} should also be set.

The type traverse function must call @ref{35f,,PyObject_VisitManagedDict()}
and its clear function must call @ref{360,,PyObject_ClearManagedDict()}.


Ajouté dans la version 3.12.


`Inheritance:'

This flag is inherited unless the
@ref{4abd,,tp_dictoffset} field is set in a superclass.
@end deffn

@geindex Py_TPFLAGS_MANAGED_WEAKREF (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MANAGED_WEAKREF}@anchor{545}
@deffn {C Macro} Py_TPFLAGS_MANAGED_WEAKREF

This bit indicates that instances of the class should be weakly
referenceable.


Ajouté dans la version 3.12.


`Inheritance:'

This flag is inherited unless the
@ref{975,,tp_weaklistoffset} field is set in a superclass.
@end deffn

@geindex Py_TPFLAGS_ITEMS_AT_END (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_ITEMS_AT_END}@anchor{536}
@deffn {C Macro} Py_TPFLAGS_ITEMS_AT_END

Only usable with variable-size types, i.e. ones with non-zero
@ref{1ef2,,tp_itemsize}.

Indicates that the variable-sized portion of an instance of this type is
at the end of the instance's memory area, at an offset of
@code{Py_TYPE(obj)->tp_basicsize} (which may be different in each
subclass).

When setting this flag, be sure that all superclasses either
use this memory layout, or are not variable-sized.
Python does not check this.


Ajouté dans la version 3.12.


`Inheritance:'

This flag is inherited.
@end deffn

@c XXX Document more flags here?

@geindex Py_TPFLAGS_LONG_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_LONG_SUBCLASS}@anchor{4d51}
@deffn {C Macro} Py_TPFLAGS_LONG_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_LIST_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_LIST_SUBCLASS}@anchor{4d52}
@deffn {C Macro} Py_TPFLAGS_LIST_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_TUPLE_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_TUPLE_SUBCLASS}@anchor{4d53}
@deffn {C Macro} Py_TPFLAGS_TUPLE_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_BYTES_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_BYTES_SUBCLASS}@anchor{4d54}
@deffn {C Macro} Py_TPFLAGS_BYTES_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_UNICODE_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_UNICODE_SUBCLASS}@anchor{4d55}
@deffn {C Macro} Py_TPFLAGS_UNICODE_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_DICT_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_DICT_SUBCLASS}@anchor{4d56}
@deffn {C Macro} Py_TPFLAGS_DICT_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_BASE_EXC_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_BASE_EXC_SUBCLASS}@anchor{4d57}
@deffn {C Macro} Py_TPFLAGS_BASE_EXC_SUBCLASS
@end deffn

@geindex Py_TPFLAGS_TYPE_SUBCLASS (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_TYPE_SUBCLASS}@anchor{4d58}
@deffn {C Macro} Py_TPFLAGS_TYPE_SUBCLASS

These flags are used by functions such as
@ref{4acd,,PyLong_Check()} to quickly determine if a type is a subclass
of a built-in type; such specific checks are faster than a generic
check, like @ref{e8f,,PyObject_IsInstance()}. Custom types that inherit
from built-ins should have their @ref{184b,,tp_flags}
set appropriately, or the code that interacts with such types
will behave differently depending on what kind of check is used.
@end deffn

@geindex Py_TPFLAGS_HAVE_FINALIZE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_FINALIZE}@anchor{3e8}
@deffn {C Macro} Py_TPFLAGS_HAVE_FINALIZE

This bit is set when the @ref{a94,,tp_finalize} slot is present in the
type structure.


Ajouté dans la version 3.4.



Obsolète depuis la version 3.8: This flag isn't necessary anymore, as the interpreter assumes the
@ref{a94,,tp_finalize} slot is always present in the
type structure.

@end deffn

@geindex Py_TPFLAGS_HAVE_VECTORCALL (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_HAVE_VECTORCALL}@anchor{53f}
@deffn {C Macro} Py_TPFLAGS_HAVE_VECTORCALL

This bit is set when the class implements
the @ref{53d,,vectorcall protocol}.
See @ref{4a5f,,tp_vectorcall_offset} for details.

`Inheritance:'

This bit is inherited if @ref{544,,tp_call} is also
inherited.


Ajouté dans la version 3.9.



Modifié dans la version 3.12: This flag is now removed from a class when the class's
@ref{543,,__call__()} method is reassigned.

This flag can now be inherited by mutable classes.

@end deffn

@geindex Py_TPFLAGS_IMMUTABLETYPE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_IMMUTABLETYPE}@anchor{3b9}
@deffn {C Macro} Py_TPFLAGS_IMMUTABLETYPE

This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.

@ref{766,,PyType_Ready()} automatically applies this flag to
@ref{769,,static types}.

`Inheritance:'

This flag is not inherited.


Ajouté dans la version 3.10.

@end deffn

@geindex Py_TPFLAGS_DISALLOW_INSTANTIATION (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_DISALLOW_INSTANTIATION}@anchor{56e}
@deffn {C Macro} Py_TPFLAGS_DISALLOW_INSTANTIATION

Disallow creating instances of the type: set
@ref{56b,,tp_new} to NULL and don't create the @code{__new__}
key in the type dictionary.

The flag must be set before creating the type, not after. For example, it
must be set before @ref{766,,PyType_Ready()} is called on the type.

The flag is set automatically on @ref{769,,static types} if
@ref{47fa,,tp_base} is NULL or @code{&PyBaseObject_Type} and
@ref{56b,,tp_new} is NULL.

`Inheritance:'

This flag is not inherited.
However, subclasses will not be instantiable unless they provide a
non-NULL @ref{56b,,tp_new} (which is only possible
via the C API).

@cartouche
@quotation Note 
To disallow instantiating a class directly but allow instantiating
its subclasses (e.g. for an @ref{1193,,abstract base class}),
do not use this flag.
Instead, make @ref{56b,,tp_new} only succeed for
subclasses.
@end quotation
@end cartouche


Ajouté dans la version 3.10.

@end deffn

@geindex Py_TPFLAGS_MAPPING (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_MAPPING}@anchor{1831}
@deffn {C Macro} Py_TPFLAGS_MAPPING

This bit indicates that instances of the class may match mapping patterns
when used as the subject of a @ref{7f7,,match} block. It is automatically
set when registering or subclassing @ref{8b7,,collections.abc.Mapping}, and
unset when registering @ref{11a1,,collections.abc.Sequence}.

@cartouche
@quotation Note 
@ref{1831,,Py_TPFLAGS_MAPPING} and @ref{1832,,Py_TPFLAGS_SEQUENCE} are
mutually exclusive; it is an error to enable both flags simultaneously.
@end quotation
@end cartouche

`Inheritance:'

This flag is inherited by types that do not already set
@ref{1832,,Py_TPFLAGS_SEQUENCE}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} — Spécifications pour le filtrage par motif



Ajouté dans la version 3.10.

@end deffn

@geindex Py_TPFLAGS_SEQUENCE (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_SEQUENCE}@anchor{1832}
@deffn {C Macro} Py_TPFLAGS_SEQUENCE

This bit indicates that instances of the class may match sequence patterns
when used as the subject of a @ref{7f7,,match} block. It is automatically
set when registering or subclassing @ref{11a1,,collections.abc.Sequence}, and
unset when registering @ref{8b7,,collections.abc.Mapping}.

@cartouche
@quotation Note 
@ref{1831,,Py_TPFLAGS_MAPPING} and @ref{1832,,Py_TPFLAGS_SEQUENCE} are
mutually exclusive; it is an error to enable both flags simultaneously.
@end quotation
@end cartouche

`Inheritance:'

This flag is inherited by types that do not already set
@ref{1831,,Py_TPFLAGS_MAPPING}.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 634
PEP 634@footnote{https://peps.python.org/pep-0634/} — Spécifications pour le filtrage par motif



Ajouté dans la version 3.10.

@end deffn

@geindex Py_TPFLAGS_VALID_VERSION_TAG (C macro)
@anchor{c-api/typeobj c Py_TPFLAGS_VALID_VERSION_TAG}@anchor{4d59}
@deffn {C Macro} Py_TPFLAGS_VALID_VERSION_TAG

Internal. Do not set or unset this flag.
To indicate that a class has changed call @ref{1780,,PyType_Modified()}

@cartouche
@quotation Avertissement 
This flag is present in header files, but is not be used.
It will be removed in a future version of CPython
@end quotation
@end cartouche
@end deffn
@end deffn

@geindex PyTypeObject.tp_doc (C member)
@anchor{c-api/typeobj c PyTypeObject tp_doc}@anchor{47ea}
@deffn {C Membre} const char *@ref{a93,,PyTypeObject}.tp_doc

An optional pointer to a NUL-terminated C string giving the docstring for this
type object.  This is exposed as the @ref{1c3a,,__doc__} attribute on the
type and instances of the type.

`Inheritance:'

This field is `not' inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_traverse (C member)
@anchor{c-api/typeobj c PyTypeObject tp_traverse}@anchor{768}
@deffn {C Membre} @ref{49c8,,traverseproc} @ref{a93,,PyTypeObject}.tp_traverse

An optional pointer to a traversal function for the garbage collector.  This is
only used if the @ref{767,,Py_TPFLAGS_HAVE_GC} flag bit is set.  The signature is:

@example
int tp_traverse(PyObject *self, visitproc visit, void *arg);
@end example

More information about Python's garbage collection scheme can be found
in section @ref{4d4e,,Supporting Cyclic Garbage Collection}.

The @ref{768,,tp_traverse} pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a @ref{768,,tp_traverse} function
simply calls @ref{47f8,,Py_VISIT()} on each of the instance's members that are Python
objects that the instance owns. For example, this is function @code{local_traverse()} from the
@code{_thread} extension module:

@example
static int
local_traverse(localobject *self, visitproc visit, void *arg)
@{
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
@}
@end example

Note that @ref{47f8,,Py_VISIT()} is called only on those members that can participate
in reference cycles.  Although there is also a @code{self->key} member, it can only
be @code{NULL} or a Python string and therefore cannot be part of a reference cycle.

On the other hand, even if you know a member can never be part of a cycle, as a
debugging aid you may want to visit it anyway just so the @ref{5f,,gc} module's
@ref{7ef,,get_referents()} function will include it.

Heap types (@ref{89c,,Py_TPFLAGS_HEAPTYPE}) must visit their type with:

@example
Py_VISIT(Py_TYPE(self));
@end example

It is only needed since Python 3.9. To support Python 3.8 and older, this
line must be conditional:

@example
#if PY_VERSION_HEX >= 0x03090000
    Py_VISIT(Py_TYPE(self));
#endif
@end example

If the @ref{361,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{184b,,tp_flags} field, the traverse function must call
@ref{35f,,PyObject_VisitManagedDict()} like this:

@example
PyObject_VisitManagedDict((PyObject*)self, visit, arg);
@end example

@cartouche
@quotation Avertissement 
When implementing @ref{768,,tp_traverse}, only the
members that the instance `owns' (by having @ref{333,,strong references} to them) must be
visited. For instance, if an object supports weak references via the
@ref{4ac2,,tp_weaklist} slot, the pointer supporting
the linked list (what `tp_weaklist' points to) must `not' be
visited as the instance does not directly own the weak references to itself
(the weakreference list is there to support the weak reference machinery,
but the instance has no strong reference to the elements inside it, as they
are allowed to be removed even if the instance is still alive).
@end quotation
@end cartouche

Note that @ref{47f8,,Py_VISIT()} requires the `visit' and `arg' parameters to
@code{local_traverse()} to have these specific names; don't name them just
anything.

Instances of @ref{952,,heap-allocated types} hold a reference to
their type. Their traversal function must therefore either visit
@ref{76a,,Py_TYPE(self)}, or delegate this responsibility by
calling @code{tp_traverse} of another heap-allocated type (such as a
heap-allocated superclass).
If they do not, the type object may not be garbage-collected.


Modifié dans la version 3.9: Heap-allocated types are expected to visit @code{Py_TYPE(self)} in
@code{tp_traverse}.  In earlier versions of Python, due to
bug 40217@footnote{https://bugs.python.org/issue40217}, doing this
may lead to crashes in subclasses.


`Inheritance:'

Group: @ref{767,,Py_TPFLAGS_HAVE_GC}, @ref{768,,tp_traverse}, @ref{4801,,tp_clear}

This field is inherited by subtypes together with @ref{4801,,tp_clear} and the
@ref{767,,Py_TPFLAGS_HAVE_GC} flag bit: the flag bit, @ref{768,,tp_traverse}, and
@ref{4801,,tp_clear} are all inherited from the base type if they are all zero in
the subtype.
@end deffn

@geindex PyTypeObject.tp_clear (C member)
@anchor{c-api/typeobj c PyTypeObject tp_clear}@anchor{4801}
@deffn {C Membre} @ref{49b9,,inquiry} @ref{a93,,PyTypeObject}.tp_clear

An optional pointer to a clear function for the garbage collector. This is only
used if the @ref{767,,Py_TPFLAGS_HAVE_GC} flag bit is set.  The signature is:

@example
int tp_clear(PyObject *);
@end example

The @ref{4801,,tp_clear} member function is used to break reference cycles in cyclic
garbage detected by the garbage collector.  Taken together, all @ref{4801,,tp_clear}
functions in the system must combine to break all reference cycles.  This is
subtle, and if in any doubt supply a @ref{4801,,tp_clear} function.  For example,
the tuple type does not implement a @ref{4801,,tp_clear} function, because it's
possible to prove that no reference cycle can be composed entirely of tuples.
Therefore the @ref{4801,,tp_clear} functions of other types must be sufficient to
break any cycle containing a tuple.  This isn't immediately obvious, and there's
rarely a good reason to avoid implementing @ref{4801,,tp_clear}.

Implementations of @ref{4801,,tp_clear} should drop the instance's references to
those of its members that may be Python objects, and set its pointers to those
members to @code{NULL}, as in the following example:

@example
static int
local_clear(localobject *self)
@{
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
@}
@end example

The @ref{564,,Py_CLEAR()} macro should be used, because clearing references is
delicate:  the reference to the contained object must not be released
(via @ref{55b,,Py_DECREF()}) until
after the pointer to the contained object is set to @code{NULL}.  This is because
releasing the reference may cause the contained object to become trash,
triggering a chain of reclamation activity that may include invoking arbitrary
Python code (due to finalizers, or weakref callbacks, associated with the
contained object). If it's possible for such code to reference `self' again,
it's important that the pointer to the contained object be @code{NULL} at that time,
so that `self' knows the contained object can no longer be used.  The
@ref{564,,Py_CLEAR()} macro performs the operations in a safe order.

If the @ref{361,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{184b,,tp_flags} field, the traverse function must call
@ref{360,,PyObject_ClearManagedDict()} like this:

@example
PyObject_ClearManagedDict((PyObject*)self);
@end example

Note that @ref{4801,,tp_clear} is not `always' called
before an instance is deallocated. For example, when reference counting
is enough to determine that an object is no longer used, the cyclic garbage
collector is not involved and @ref{47ee,,tp_dealloc} is
called directly.

Because the goal of @ref{4801,,tp_clear} functions is to break reference cycles,
it's not necessary to clear contained objects like Python strings or Python
integers, which can't participate in reference cycles. On the other hand, it may
be convenient to clear all contained Python objects, and write the type's
@ref{47ee,,tp_dealloc} function to invoke @ref{4801,,tp_clear}.

More information about Python's garbage collection scheme can be found in
section @ref{4d4e,,Supporting Cyclic Garbage Collection}.

`Inheritance:'

Group: @ref{767,,Py_TPFLAGS_HAVE_GC}, @ref{768,,tp_traverse}, @ref{4801,,tp_clear}

This field is inherited by subtypes together with @ref{768,,tp_traverse} and the
@ref{767,,Py_TPFLAGS_HAVE_GC} flag bit: the flag bit, @ref{768,,tp_traverse}, and
@ref{4801,,tp_clear} are all inherited from the base type if they are all zero in
the subtype.
@end deffn

@geindex PyTypeObject.tp_richcompare (C member)
@anchor{c-api/typeobj c PyTypeObject tp_richcompare}@anchor{480f}
@deffn {C Membre} @ref{49c1,,richcmpfunc} @ref{a93,,PyTypeObject}.tp_richcompare

An optional pointer to the rich comparison function, whose signature is:

@example
PyObject *tp_richcompare(PyObject *self, PyObject *other, int op);
@end example

The first parameter is guaranteed to be an instance of the type
that is defined by @ref{a93,,PyTypeObject}.

The function should return the result of the comparison (usually @code{Py_True}
or @code{Py_False}).  If the comparison is undefined, it must return
@code{Py_NotImplemented}, if another error occurred it must return @code{NULL} and
set an exception condition.

The following constants are defined to be used as the third argument for
@ref{480f,,tp_richcompare} and for @ref{4810,,PyObject_RichCompare()}:


@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} 
@headitem

Constante

@tab

Comparaison

@item

@geindex Py_LT (C macro)
@anchor{c-api/typeobj c Py_LT}@anchor{4a54}
@deffn {C Macro} Py_LT
@end deffn

@tab

@code{<}

@item

@geindex Py_LE (C macro)
@anchor{c-api/typeobj c Py_LE}@anchor{4a55}
@deffn {C Macro} Py_LE
@end deffn

@tab

@code{<=}

@item

@geindex Py_EQ (C macro)
@anchor{c-api/typeobj c Py_EQ}@anchor{4a56}
@deffn {C Macro} Py_EQ
@end deffn

@tab

@code{==}

@item

@geindex Py_NE (C macro)
@anchor{c-api/typeobj c Py_NE}@anchor{4a57}
@deffn {C Macro} Py_NE
@end deffn

@tab

@code{!=}

@item

@geindex Py_GT (C macro)
@anchor{c-api/typeobj c Py_GT}@anchor{4a58}
@deffn {C Macro} Py_GT
@end deffn

@tab

@code{>}

@item

@geindex Py_GE (C macro)
@anchor{c-api/typeobj c Py_GE}@anchor{4a59}
@deffn {C Macro} Py_GE
@end deffn

@tab

@code{>=}

@end multitable


The following macro is defined to ease writing rich comparison functions:

@geindex Py_RETURN_RICHCOMPARE (C macro)
@anchor{c-api/typeobj c Py_RETURN_RICHCOMPARE}@anchor{ba2}
@deffn {C Macro} Py_RETURN_RICHCOMPARE (VAL_A, VAL_B, op)

Return @code{Py_True} or @code{Py_False} from the function, depending on the
result of a comparison.
VAL_A and VAL_B must be orderable by C comparison operators (for example,
they may be C ints or floats). The third argument specifies the requested
operation, as for @ref{4810,,PyObject_RichCompare()}.

The returned value is a new @ref{333,,strong reference}.

On error, sets an exception and returns @code{NULL} from the function.


Ajouté dans la version 3.7.

@end deffn

`Inheritance:'

Group: @ref{4815,,tp_hash}, @ref{480f,,tp_richcompare}

This field is inherited by subtypes together with @ref{4815,,tp_hash}:
a subtype inherits @ref{480f,,tp_richcompare} and @ref{4815,,tp_hash} when
the subtype's @ref{480f,,tp_richcompare} and @ref{4815,,tp_hash} are both
@code{NULL}.

`Default:'

@code{PyBaseObject_Type} provides a @ref{480f,,tp_richcompare}
implementation, which may be inherited.  However, if only
@ref{4815,,tp_hash} is defined, not even the inherited function is used
and instances of the type will not be able to participate in any
comparisons.
@end deffn

@geindex PyTypeObject.tp_weaklistoffset (C member)
@anchor{c-api/typeobj c PyTypeObject tp_weaklistoffset}@anchor{975}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} @ref{a93,,PyTypeObject}.tp_weaklistoffset

While this field is still supported, @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF}
should be used instead, if at all possible.

If the instances of this type are weakly referenceable, this field is greater
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
@ref{562,,PyObject_ClearWeakRefs()} and the @code{PyWeakref_*} functions.  The
instance structure needs to include a field of type @ref{32f,,PyObject}* which is
initialized to @code{NULL}.

Do not confuse this field with @ref{4ac2,,tp_weaklist}; that is the list head for
weak references to the type object itself.

It is an error to set both the @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} bit and
@ref{975,,tp_weaklistoffset}.

`Inheritance:'

This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype uses a different weak
reference list head than the base type.  Since the list head is always found via
@ref{975,,tp_weaklistoffset}, this should not be a problem.

`Default:'

If the @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} bit is set in the
@ref{184b,,tp_flags} field, then
@ref{975,,tp_weaklistoffset} will be set to a negative value,
to indicate that it is unsafe to use this field.
@end deffn

@geindex PyTypeObject.tp_iter (C member)
@anchor{c-api/typeobj c PyTypeObject tp_iter}@anchor{14a4}
@deffn {C Membre} @ref{49b5,,getiterfunc} @ref{a93,,PyTypeObject}.tp_iter

An optional pointer to a function that returns an @ref{1aa,,iterator} for the
object.  Its presence normally signals that the instances of this type are
@ref{1205,,iterable} (although sequences may be iterable without this function).

This function has the same signature as @ref{4929,,PyObject_GetIter()}:

@example
PyObject *tp_iter(PyObject *self);
@end example

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_iternext (C member)
@anchor{c-api/typeobj c PyTypeObject tp_iternext}@anchor{14a5}
@deffn {C Membre} @ref{49ba,,iternextfunc} @ref{a93,,PyTypeObject}.tp_iternext

An optional pointer to a function that returns the next item in an
@ref{1aa,,iterator}. The signature is:

@example
PyObject *tp_iternext(PyObject *self);
@end example

When the iterator is exhausted, it must return @code{NULL}; a @ref{be8,,StopIteration}
exception may or may not be set.  When another error occurs, it must return
@code{NULL} too.  Its presence signals that the instances of this type are
iterators.

Iterator types should also define the @ref{14a4,,tp_iter} function, and that
function should return the iterator instance itself (not a new iterator
instance).

This function has the same signature as @ref{48d7,,PyIter_Next()}.

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_methods (C member)
@anchor{c-api/typeobj c PyTypeObject tp_methods}@anchor{47f3}
@deffn {C Membre} struct @ref{148d,,PyMethodDef} *@ref{a93,,PyTypeObject}.tp_methods

An optional pointer to a static @code{NULL}-terminated array of @ref{148d,,PyMethodDef}
structures, declaring regular methods of this type.

For each entry in the array, an entry is added to the type's dictionary (see
@ref{16a9,,tp_dict} below) containing a method descriptor.

`Inheritance:'

This field is not inherited by subtypes (methods are inherited through a
different mechanism).
@end deffn

@geindex PyTypeObject.tp_members (C member)
@anchor{c-api/typeobj c PyTypeObject tp_members}@anchor{47f1}
@deffn {C Membre} struct @ref{53a,,PyMemberDef} *@ref{a93,,PyTypeObject}.tp_members

An optional pointer to a static @code{NULL}-terminated array of @ref{53a,,PyMemberDef}
structures, declaring regular data members (fields or slots) of instances of
this type.

For each entry in the array, an entry is added to the type's dictionary (see
@ref{16a9,,tp_dict} below) containing a member descriptor.

`Inheritance:'

This field is not inherited by subtypes (members are inherited through a
different mechanism).
@end deffn

@geindex PyTypeObject.tp_getset (C member)
@anchor{c-api/typeobj c PyTypeObject tp_getset}@anchor{47f6}
@deffn {C Membre} struct @ref{ba6,,PyGetSetDef} *@ref{a93,,PyTypeObject}.tp_getset

An optional pointer to a static @code{NULL}-terminated array of @ref{ba6,,PyGetSetDef}
structures, declaring computed attributes of instances of this type.

For each entry in the array, an entry is added to the type's dictionary (see
@ref{16a9,,tp_dict} below) containing a getset descriptor.

`Inheritance:'

This field is not inherited by subtypes (computed attributes are inherited
through a different mechanism).
@end deffn

@geindex PyTypeObject.tp_base (C member)
@anchor{c-api/typeobj c PyTypeObject tp_base}@anchor{47fa}
@deffn {C Membre} @ref{a93,,PyTypeObject} *@ref{a93,,PyTypeObject}.tp_base

An optional pointer to a base type from which type properties are inherited.  At
this level, only single inheritance is supported; multiple inheritance require
dynamically creating a type object by calling the metatype.

@cartouche
@quotation Note 
@c from Modules/xxmodule.c

Slot initialization is subject to the rules of initializing globals.
C99 requires the initializers to be "address constants".  Function
designators like @ref{47eb,,PyType_GenericNew()}, with implicit conversion
to a pointer, are valid C99 address constants.

However, the unary '&' operator applied to a non-static variable
like @code{PyBaseObject_Type} is not required to produce an address
constant.  Compilers may support this (gcc does), MSVC does not.
Both compilers are strictly standard conforming in this particular
behavior.

Consequently, @ref{47fa,,tp_base} should be set in
the extension module's init function.
@end quotation
@end cartouche

`Inheritance:'

This field is not inherited by subtypes (obviously).

`Default:'

This field defaults to @code{&PyBaseObject_Type} (which to Python
programmers is known as the type @ref{a7a,,object}).
@end deffn

@geindex PyTypeObject.tp_dict (C member)
@anchor{c-api/typeobj c PyTypeObject tp_dict}@anchor{16a9}
@deffn {C Membre} @ref{32f,,PyObject} *@ref{a93,,PyTypeObject}.tp_dict

The type's dictionary is stored here by @ref{766,,PyType_Ready()}.

This field should normally be initialized to @code{NULL} before PyType_Ready is
called; it may also be initialized to a dictionary containing initial attributes
for the type.  Once @ref{766,,PyType_Ready()} has initialized the type, extra
attributes for the type may be added to this dictionary only if they don't
correspond to overloaded operations (like @ref{1f0f,,__add__()}).  Once
initialization for the type has finished, this field should be
treated as read-only.

Some types may not store their dictionary in this slot.
Use @ref{16a8,,PyType_GetDict()} to retrieve the dictionary for an arbitrary
type.


Modifié dans la version 3.12: Internals detail: For static builtin types, this is always @code{NULL}.
Instead, the dict for such types is stored on @code{PyInterpreterState}.
Use @ref{16a8,,PyType_GetDict()} to get the dict for an arbitrary type.


`Inheritance:'

This field is not inherited by subtypes (though the attributes defined in here
are inherited through a different mechanism).

`Default:'

If this field is @code{NULL}, @ref{766,,PyType_Ready()} will assign a new
dictionary to it.

@cartouche
@quotation Avertissement 
It is not safe to use @ref{47da,,PyDict_SetItem()} on or otherwise modify
@ref{16a9,,tp_dict} with the dictionary C-API.
@end quotation
@end cartouche
@end deffn

@geindex PyTypeObject.tp_descr_get (C member)
@anchor{c-api/typeobj c PyTypeObject tp_descr_get}@anchor{4d0e}
@deffn {C Membre} @ref{49af,,descrgetfunc} @ref{a93,,PyTypeObject}.tp_descr_get

An optional pointer to a "descriptor get" function.

The function signature is:

@example
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
@end example

@c XXX explain more?

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_descr_set (C member)
@anchor{c-api/typeobj c PyTypeObject tp_descr_set}@anchor{1884}
@deffn {C Membre} @ref{49b0,,descrsetfunc} @ref{a93,,PyTypeObject}.tp_descr_set

An optional pointer to a function for setting and deleting
a descriptor's value.

The function signature is:

@example
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
@end example

The `value' argument is set to @code{NULL} to delete the value.

@c XXX explain more?

`Inheritance:'

This field is inherited by subtypes.
@end deffn

@geindex PyTypeObject.tp_dictoffset (C member)
@anchor{c-api/typeobj c PyTypeObject tp_dictoffset}@anchor{4abd}
@deffn {C Membre} @ref{a4e,,Py_ssize_t} @ref{a93,,PyTypeObject}.tp_dictoffset

While this field is still supported, @ref{361,,Py_TPFLAGS_MANAGED_DICT} should be
used instead, if at all possible.

If the instances of this type have a dictionary containing instance variables,
this field is non-zero and contains the offset in the instances of the type of
the instance variable dictionary; this offset is used by
@ref{4925,,PyObject_GenericGetAttr()}.

Do not confuse this field with @ref{16a9,,tp_dict}; that is the dictionary for
attributes of the type object itself.

The value specifies the offset of the dictionary from the start of the instance structure.

The @ref{4abd,,tp_dictoffset} should be regarded as write-only.
To get the pointer to the dictionary call @ref{18c7,,PyObject_GenericGetDict()}.
Calling @ref{18c7,,PyObject_GenericGetDict()} may need to allocate memory for the
dictionary, so it is may be more efficient to call @ref{341,,PyObject_GetAttr()}
when accessing an attribute on the object.

It is an error to set both the @ref{545,,Py_TPFLAGS_MANAGED_WEAKREF} bit and
@ref{4abd,,tp_dictoffset}.

`Inheritance:'

This field is inherited by subtypes. A subtype should not override this offset;
doing so could be unsafe, if C code tries to access the dictionary at the
previous offset.
To properly support inheritance, use @ref{361,,Py_TPFLAGS_MANAGED_DICT}.

`Default:'

This slot has no default.  For @ref{769,,static types}, if the
field is @code{NULL} then no @ref{546,,__dict__} gets created for instances.

If the @ref{361,,Py_TPFLAGS_MANAGED_DICT} bit is set in the
@ref{184b,,tp_flags} field, then
@ref{4abd,,tp_dictoffset} will be set to @code{-1}, to indicate
that it is unsafe to use this field.
@end deffn

@geindex PyTypeObject.tp_init (C member)
@anchor{c-api/typeobj c PyTypeObject tp_init}@anchor{56d}
@deffn {C Membre} @ref{49b8,,initproc} @ref{a93,,PyTypeObject}.tp_init

An optional pointer to an instance initialization function.

This function corresponds to the @ref{69b,,__init__()} method of classes.  Like
@code{__init__()}, it is possible to create an instance without calling
@code{__init__()}, and it is possible to reinitialize an instance by calling its
@code{__init__()} method again.

The function signature is:

@example
int tp_init(PyObject *self, PyObject *args, PyObject *kwds);
@end example

The self argument is the instance to be initialized; the `args' and `kwds'
arguments represent positional and keyword arguments of the call to
@ref{69b,,__init__()}.

The @ref{56d,,tp_init} function, if not @code{NULL}, is called when an instance is
created normally by calling its type, after the type's @ref{56b,,tp_new} function
has returned an instance of the type.  If the @ref{56b,,tp_new} function returns an
instance of some other type that is not a subtype of the original type, no
@ref{56d,,tp_init} function is called; if @ref{56b,,tp_new} returns an instance of a
subtype of the original type, the subtype's @ref{56d,,tp_init} is called.

Returns @code{0} on success, @code{-1} and sets an exception on error.

`Inheritance:'

This field is inherited by subtypes.

`Default:'

For @ref{769,,static types} this field does not have a default.
@end deffn

@geindex PyTypeObject.tp_alloc (C member)
@anchor{c-api/typeobj c PyTypeObject tp_alloc}@anchor{47f0}
@deffn {C Membre} @ref{49ad,,allocfunc} @ref{a93,,PyTypeObject}.tp_alloc

An optional pointer to an instance allocation function.

The function signature is:

@example
PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems);
@end example

`Inheritance:'

This field is inherited by static subtypes, but not by dynamic
subtypes (subtypes created by a class statement).

`Default:'

For dynamic subtypes, this field is always set to
@ref{a59,,PyType_GenericAlloc()}, to force a standard heap
allocation strategy.

For static subtypes, @code{PyBaseObject_Type} uses
@ref{a59,,PyType_GenericAlloc()}.  That is the recommended value
for all statically defined types.
@end deffn

@geindex PyTypeObject.tp_new (C member)
@anchor{c-api/typeobj c PyTypeObject tp_new}@anchor{56b}
@deffn {C Membre} @ref{49bc,,newfunc} @ref{a93,,PyTypeObject}.tp_new

An optional pointer to an instance creation function.

The function signature is:

@example
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds);
@end example

The `subtype' argument is the type of the object being created; the `args' and
`kwds' arguments represent positional and keyword arguments of the call to the
type.  Note that `subtype' doesn't have to equal the type whose @ref{56b,,tp_new}
function is called; it may be a subtype of that type (but not an unrelated
type).

The @ref{56b,,tp_new} function should call @code{subtype->tp_alloc(subtype, nitems)}
to allocate space for the object, and then do only as much further
initialization as is absolutely necessary.  Initialization that can safely be
ignored or repeated should be placed in the @ref{56d,,tp_init} handler.  A good
rule of thumb is that for immutable types, all initialization should take place
in @ref{56b,,tp_new}, while for mutable types, most initialization should be
deferred to @ref{56d,,tp_init}.

Set the @ref{56e,,Py_TPFLAGS_DISALLOW_INSTANTIATION} flag to disallow creating
instances of the type in Python.

`Inheritance:'

This field is inherited by subtypes, except it is not inherited by
@ref{769,,static types} whose @ref{47fa,,tp_base}
is @code{NULL} or @code{&PyBaseObject_Type}.

`Default:'

For @ref{769,,static types} this field has no default.
This means if the slot is defined as @code{NULL}, the type cannot be called
to create new instances; presumably there is some other way to create
instances, like a factory function.
@end deffn

@geindex PyTypeObject.tp_free (C member)
@anchor{c-api/typeobj c PyTypeObject tp_free}@anchor{47ef}
@deffn {C Membre} @ref{4bb2,,freefunc} @ref{a93,,PyTypeObject}.tp_free

An optional pointer to an instance deallocation function.  Its signature is:

@example
void tp_free(void *self);
@end example

An initializer that is compatible with this signature is @ref{c53,,PyObject_Free()}.

`Inheritance:'

This field is inherited by static subtypes, but not by dynamic
subtypes (subtypes created by a class statement)

`Default:'

In dynamic subtypes, this field is set to a deallocator suitable to
match @ref{a59,,PyType_GenericAlloc()} and the value of the
@ref{767,,Py_TPFLAGS_HAVE_GC} flag bit.

For static subtypes, @code{PyBaseObject_Type} uses @ref{1487,,PyObject_Del()}.
@end deffn

@geindex PyTypeObject.tp_is_gc (C member)
@anchor{c-api/typeobj c PyTypeObject tp_is_gc}@anchor{4d0f}
@deffn {C Membre} @ref{49b9,,inquiry} @ref{a93,,PyTypeObject}.tp_is_gc

An optional pointer to a function called by the garbage collector.

The garbage collector needs to know whether a particular object is collectible
or not.  Normally, it is sufficient to look at the object's type's
@ref{184b,,tp_flags} field, and check the @ref{767,,Py_TPFLAGS_HAVE_GC} flag bit.  But
some types have a mixture of statically and dynamically allocated instances, and
the statically allocated instances are not collectible.  Such types should
define this function; it should return @code{1} for a collectible instance, and
@code{0} for a non-collectible instance. The signature is:

@example
int tp_is_gc(PyObject *self);
@end example

(The only example of this are types themselves.  The metatype,
@ref{538,,PyType_Type}, defines this function to distinguish between statically
and @ref{952,,dynamically allocated types}.)

`Inheritance:'

This field is inherited by subtypes.

`Default:'

This slot has no default.  If this field is @code{NULL},
@ref{767,,Py_TPFLAGS_HAVE_GC} is used as the functional equivalent.
@end deffn

@geindex PyTypeObject.tp_bases (C member)
@anchor{c-api/typeobj c PyTypeObject tp_bases}@anchor{4d10}
@deffn {C Membre} @ref{32f,,PyObject} *@ref{a93,,PyTypeObject}.tp_bases

Tuple of base types.

This field should be set to @code{NULL} and treated as read-only.
Python will fill it in when the type is @ref{766,,initialized}.

For dynamically created classes, the @code{Py_tp_bases}
@ref{4961,,slot} can be used instead of the `bases' argument
of @ref{56a,,PyType_FromSpecWithBases()}.
The argument form is preferred.

@cartouche
@quotation Avertissement 
Multiple inheritance does not work well for statically defined types.
If you set @code{tp_bases} to a tuple, Python will not raise an error,
but some slots will only be inherited from the first base.
@end quotation
@end cartouche

`Inheritance:'

This field is not inherited.
@end deffn

@geindex PyTypeObject.tp_mro (C member)
@anchor{c-api/typeobj c PyTypeObject tp_mro}@anchor{4ac0}
@deffn {C Membre} @ref{32f,,PyObject} *@ref{a93,,PyTypeObject}.tp_mro

Tuple containing the expanded set of base types, starting with the type itself
and ending with @ref{a7a,,object}, in Method Resolution Order.

This field should be set to @code{NULL} and treated as read-only.
Python will fill it in when the type is @ref{766,,initialized}.

`Inheritance:'

This field is not inherited; it is calculated fresh by
@ref{766,,PyType_Ready()}.
@end deffn

@geindex PyTypeObject.tp_cache (C member)
@anchor{c-api/typeobj c PyTypeObject tp_cache}@anchor{4ac1}
@deffn {C Membre} @ref{32f,,PyObject} *@ref{a93,,PyTypeObject}.tp_cache

Unused.  Internal use only.

`Inheritance:'

This field is not inherited.
@end deffn

@geindex PyTypeObject.tp_subclasses (C member)
@anchor{c-api/typeobj c PyTypeObject tp_subclasses}@anchor{55e}
@deffn {C Membre} void *@ref{a93,,PyTypeObject}.tp_subclasses

A collection of subclasses.  Internal use only.  May be an invalid pointer.

To get a list of subclasses, call the Python method
@ref{55f,,__subclasses__()}.


Modifié dans la version 3.12: For some types, this field does not hold a valid @ref{32f,,PyObject}*.
The type was changed to void* to indicate this.


`Inheritance:'

This field is not inherited.
@end deffn

@geindex PyTypeObject.tp_weaklist (C member)
@anchor{c-api/typeobj c PyTypeObject tp_weaklist}@anchor{4ac2}
@deffn {C Membre} @ref{32f,,PyObject} *@ref{a93,,PyTypeObject}.tp_weaklist

Weak reference list head, for weak references to this type object.  Not
inherited.  Internal use only.


Modifié dans la version 3.12: Internals detail: For the static builtin types this is always @code{NULL},
even if weakrefs are added.  Instead, the weakrefs for each are stored
on @code{PyInterpreterState}.  Use the public C-API or the internal
@code{_PyObject_GET_WEAKREFS_LISTPTR()} macro to avoid the distinction.


`Inheritance:'

This field is not inherited.
@end deffn

@geindex PyTypeObject.tp_del (C member)
@anchor{c-api/typeobj c PyTypeObject tp_del}@anchor{4d11}
@deffn {C Membre} @ref{49b1,,destructor} @ref{a93,,PyTypeObject}.tp_del

This field is deprecated.  Use @ref{a94,,tp_finalize} instead.
@end deffn

@geindex PyTypeObject.tp_version_tag (C member)
@anchor{c-api/typeobj c PyTypeObject tp_version_tag}@anchor{4d12}
@deffn {C Membre} unsigned int @ref{a93,,PyTypeObject}.tp_version_tag

Used to index into the method cache.  Internal use only.

`Inheritance:'

This field is not inherited.
@end deffn

@geindex PyTypeObject.tp_finalize (C member)
@anchor{c-api/typeobj c PyTypeObject tp_finalize}@anchor{a94}
@deffn {C Membre} @ref{49b1,,destructor} @ref{a93,,PyTypeObject}.tp_finalize

An optional pointer to an instance finalization function.  Its signature is:

@example
void tp_finalize(PyObject *self);
@end example

If @ref{a94,,tp_finalize} is set, the interpreter calls it once when
finalizing an instance.  It is called either from the garbage
collector (if the instance is part of an isolated reference cycle) or
just before the object is deallocated.  Either way, it is guaranteed
to be called before attempting to break reference cycles, ensuring
that it finds the object in a sane state.

@ref{a94,,tp_finalize} should not mutate the current exception status;
therefore, a recommended way to write a non-trivial finalizer is:

@example
static void
local_finalize(PyObject *self)
@{
    PyObject *error_type, *error_value, *error_traceback;

    /* Save the current exception, if any. */
    PyErr_Fetch(&error_type, &error_value, &error_traceback);

    /* ... */

    /* Restore the saved exception. */
    PyErr_Restore(error_type, error_value, error_traceback);
@}
@end example

`Inheritance:'

This field is inherited by subtypes.


Ajouté dans la version 3.4.



Modifié dans la version 3.8: Before version 3.8 it was necessary to set the
@ref{3e8,,Py_TPFLAGS_HAVE_FINALIZE} flags bit in order for this field to be
used.  This is no longer required.



@subsubheading Voir aussi


"Safe object finalization" (
@geindex Python Enhancement Proposals; PEP 442
PEP 442@footnote{https://peps.python.org/pep-0442/})

@end deffn

@geindex PyTypeObject.tp_vectorcall (C member)
@anchor{c-api/typeobj c PyTypeObject tp_vectorcall}@anchor{4abf}
@deffn {C Membre} @ref{542,,vectorcallfunc} @ref{a93,,PyTypeObject}.tp_vectorcall

Vectorcall function to use for calls of this type object.
In other words, it is used to implement
@ref{53d,,vectorcall} for @code{type.__call__}.
If @code{tp_vectorcall} is @code{NULL}, the default call implementation
using @ref{56c,,__new__()} and @ref{69b,,__init__()} is used.

`Inheritance:'

This field is never inherited.


Ajouté dans la version 3.9: (the field exists since 3.8 but it's only used since 3.9)

@end deffn

@geindex PyTypeObject.tp_watched (C member)
@anchor{c-api/typeobj c PyTypeObject tp_watched}@anchor{4d13}
@deffn {C Membre} unsigned char @ref{a93,,PyTypeObject}.tp_watched

Internal. Do not use.


Ajouté dans la version 3.12.

@end deffn

@node Static Types,Heap Types,PyTypeObject Slots,Objets type<3>
@anchor{c-api/typeobj id4}@anchor{4d5a}@anchor{c-api/typeobj static-types}@anchor{769}
@subsubsection Static Types


Traditionally, types defined in C code are `static', that is,
a static @ref{a93,,PyTypeObject} structure is defined directly in code
and initialized using @ref{766,,PyType_Ready()}.

This results in types that are limited relative to types defined in Python:


@itemize *

@item 
Static types are limited to one base, i.e. they cannot use multiple
inheritance.

@item 
Static type objects (but not necessarily their instances) are immutable.
It is not possible to add or modify the type object's attributes from Python.

@item 
Static type objects are shared across
@ref{573,,sub-interpreters}, so they should not
include any subinterpreter-specific state.
@end itemize

Also, since @ref{a93,,PyTypeObject} is only part of the @ref{38c,,Limited API} as an opaque struct, any extension modules using static types must be
compiled for a specific Python minor version.

@node Heap Types,Number Object Structures,Static Types,Objets type<3>
@anchor{c-api/typeobj heap-types}@anchor{952}@anchor{c-api/typeobj id5}@anchor{4d5b}
@subsubsection Heap Types


An alternative to @ref{769,,static types} is `heap-allocated types',
or `heap types' for short, which correspond closely to classes created by
Python's @code{class} statement. Heap types have the @ref{89c,,Py_TPFLAGS_HEAPTYPE}
flag set.

This is done by filling a @ref{16a5,,PyType_Spec} structure and calling
@ref{569,,PyType_FromSpec()}, @ref{56a,,PyType_FromSpecWithBases()},
@ref{53c,,PyType_FromModuleAndSpec()}, or @ref{53b,,PyType_FromMetaclass()}.

@node Number Object Structures,Mapping Object Structures,Heap Types,Objets type<3>
@anchor{c-api/typeobj number-object-structures}@anchor{4d5c}@anchor{c-api/typeobj number-structs}@anchor{4d4b}
@subsubsection Number Object Structures


@geindex PyNumberMethods (C type)
@anchor{c-api/typeobj c PyNumberMethods}@anchor{13d4}
@deffn {C Type} type PyNumberMethods

This structure holds pointers to the functions which an object uses to
implement the number protocol.  Each function is used by the function of
similar name documented in the @ref{4a6a,,Number Protocol} section.

@c XXX Drop the definition?

Here is the structure definition:

@example
typedef struct @{
     binaryfunc nb_add;
     binaryfunc nb_subtract;
     binaryfunc nb_multiply;
     binaryfunc nb_remainder;
     binaryfunc nb_divmod;
     ternaryfunc nb_power;
     unaryfunc nb_negative;
     unaryfunc nb_positive;
     unaryfunc nb_absolute;
     inquiry nb_bool;
     unaryfunc nb_invert;
     binaryfunc nb_lshift;
     binaryfunc nb_rshift;
     binaryfunc nb_and;
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
     void *nb_reserved;
     unaryfunc nb_float;

     binaryfunc nb_inplace_add;
     binaryfunc nb_inplace_subtract;
     binaryfunc nb_inplace_multiply;
     binaryfunc nb_inplace_remainder;
     ternaryfunc nb_inplace_power;
     binaryfunc nb_inplace_lshift;
     binaryfunc nb_inplace_rshift;
     binaryfunc nb_inplace_and;
     binaryfunc nb_inplace_xor;
     binaryfunc nb_inplace_or;

     binaryfunc nb_floor_divide;
     binaryfunc nb_true_divide;
     binaryfunc nb_inplace_floor_divide;
     binaryfunc nb_inplace_true_divide;

     unaryfunc nb_index;

     binaryfunc nb_matrix_multiply;
     binaryfunc nb_inplace_matrix_multiply;
@} PyNumberMethods;
@end example

@cartouche
@quotation Note 
Binary and ternary functions must check the type of all their operands,
and implement the necessary conversions (at least one of the operands is
an instance of the defined type).  If the operation is not defined for the
given operands, binary and ternary functions must return
@code{Py_NotImplemented}, if another error occurred they must return @code{NULL}
and set an exception.
@end quotation
@end cartouche

@cartouche
@quotation Note 
The @ref{4d34,,nb_reserved} field should always be @code{NULL}.  It
was previously called @code{nb_long}, and was renamed in
Python 3.0.1.
@end quotation
@end cartouche
@end deffn

@geindex PyNumberMethods.nb_add (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_add}@anchor{4ab4}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_add
@end deffn

@geindex PyNumberMethods.nb_subtract (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_subtract}@anchor{4d1b}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_subtract
@end deffn

@geindex PyNumberMethods.nb_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_multiply}@anchor{4d1d}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_multiply
@end deffn

@geindex PyNumberMethods.nb_remainder (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_remainder}@anchor{4d1f}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_remainder
@end deffn

@geindex PyNumberMethods.nb_divmod (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_divmod}@anchor{4d21}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_divmod
@end deffn

@geindex PyNumberMethods.nb_power (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_power}@anchor{4d22}
@deffn {C Membre} @ref{49c7,,ternaryfunc} @ref{13d4,,PyNumberMethods}.nb_power
@end deffn

@geindex PyNumberMethods.nb_negative (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_negative}@anchor{4d24}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_negative
@end deffn

@geindex PyNumberMethods.nb_positive (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_positive}@anchor{4d25}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_positive
@end deffn

@geindex PyNumberMethods.nb_absolute (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_absolute}@anchor{4d26}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_absolute
@end deffn

@geindex PyNumberMethods.nb_bool (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_bool}@anchor{4d27}
@deffn {C Membre} @ref{49b9,,inquiry} @ref{13d4,,PyNumberMethods}.nb_bool
@end deffn

@geindex PyNumberMethods.nb_invert (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_invert}@anchor{4d28}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_invert
@end deffn

@geindex PyNumberMethods.nb_lshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_lshift}@anchor{4d29}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_lshift
@end deffn

@geindex PyNumberMethods.nb_rshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_rshift}@anchor{4d2b}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_rshift
@end deffn

@geindex PyNumberMethods.nb_and (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_and}@anchor{4d2d}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_and
@end deffn

@geindex PyNumberMethods.nb_xor (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_xor}@anchor{4d2f}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_xor
@end deffn

@geindex PyNumberMethods.nb_or (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_or}@anchor{4d31}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_or
@end deffn

@geindex PyNumberMethods.nb_int (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_int}@anchor{4d33}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_int
@end deffn

@geindex PyNumberMethods.nb_reserved (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_reserved}@anchor{4d34}
@deffn {C Membre} void *@ref{13d4,,PyNumberMethods}.nb_reserved
@end deffn

@geindex PyNumberMethods.nb_float (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_float}@anchor{4d35}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_float
@end deffn

@geindex PyNumberMethods.nb_inplace_add (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_add}@anchor{4d1a}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_add
@end deffn

@geindex PyNumberMethods.nb_inplace_subtract (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_subtract}@anchor{4d1c}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_subtract
@end deffn

@geindex PyNumberMethods.nb_inplace_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_multiply}@anchor{4d1e}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_multiply
@end deffn

@geindex PyNumberMethods.nb_inplace_remainder (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_remainder}@anchor{4d20}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_remainder
@end deffn

@geindex PyNumberMethods.nb_inplace_power (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_power}@anchor{4d23}
@deffn {C Membre} @ref{49c7,,ternaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_power
@end deffn

@geindex PyNumberMethods.nb_inplace_lshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_lshift}@anchor{4d2a}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_lshift
@end deffn

@geindex PyNumberMethods.nb_inplace_rshift (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_rshift}@anchor{4d2c}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_rshift
@end deffn

@geindex PyNumberMethods.nb_inplace_and (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_and}@anchor{4d2e}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_and
@end deffn

@geindex PyNumberMethods.nb_inplace_xor (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_xor}@anchor{4d30}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_xor
@end deffn

@geindex PyNumberMethods.nb_inplace_or (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_or}@anchor{4d32}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_or
@end deffn

@geindex PyNumberMethods.nb_floor_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_floor_divide}@anchor{4d36}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_floor_divide
@end deffn

@geindex PyNumberMethods.nb_true_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_true_divide}@anchor{4d38}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_true_divide
@end deffn

@geindex PyNumberMethods.nb_inplace_floor_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_floor_divide}@anchor{4d37}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_floor_divide
@end deffn

@geindex PyNumberMethods.nb_inplace_true_divide (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_true_divide}@anchor{4d39}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_true_divide
@end deffn

@geindex PyNumberMethods.nb_index (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_index}@anchor{13d3}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{13d4,,PyNumberMethods}.nb_index
@end deffn

@geindex PyNumberMethods.nb_matrix_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_matrix_multiply}@anchor{4d3a}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_matrix_multiply
@end deffn

@geindex PyNumberMethods.nb_inplace_matrix_multiply (C member)
@anchor{c-api/typeobj c PyNumberMethods nb_inplace_matrix_multiply}@anchor{4d3b}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{13d4,,PyNumberMethods}.nb_inplace_matrix_multiply
@end deffn

@node Mapping Object Structures,Sequence Object Structures,Number Object Structures,Objets type<3>
@anchor{c-api/typeobj mapping-object-structures}@anchor{4d5d}@anchor{c-api/typeobj mapping-structs}@anchor{4d4d}
@subsubsection Mapping Object Structures


@geindex PyMappingMethods (C type)
@anchor{c-api/typeobj c PyMappingMethods}@anchor{4814}
@deffn {C Type} type PyMappingMethods

This structure holds pointers to the functions which an object uses to
implement the mapping protocol.  It has three members:
@end deffn

@geindex PyMappingMethods.mp_length (C member)
@anchor{c-api/typeobj c PyMappingMethods mp_length}@anchor{4d3c}
@deffn {C Membre} @ref{49bb,,lenfunc} @ref{4814,,PyMappingMethods}.mp_length

This function is used by @ref{19e4,,PyMapping_Size()} and
@ref{492f,,PyObject_Size()}, and has the same signature.  This slot may be set to
@code{NULL} if the object has no defined length.
@end deffn

@geindex PyMappingMethods.mp_subscript (C member)
@anchor{c-api/typeobj c PyMappingMethods mp_subscript}@anchor{18bb}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{4814,,PyMappingMethods}.mp_subscript

This function is used by @ref{33d,,PyObject_GetItem()} and
@ref{493a,,PySequence_GetSlice()}, and has the same signature as
@code{PyObject_GetItem()}.  This slot must be filled for the
@ref{48eb,,PyMapping_Check()} function to return @code{1}, it can be @code{NULL}
otherwise.
@end deffn

@geindex PyMappingMethods.mp_ass_subscript (C member)
@anchor{c-api/typeobj c PyMappingMethods mp_ass_subscript}@anchor{4d3d}
@deffn {C Membre} @ref{49bd,,objobjargproc} @ref{4814,,PyMappingMethods}.mp_ass_subscript

This function is used by @ref{484e,,PyObject_SetItem()},
@ref{4921,,PyObject_DelItem()}, @ref{4941,,PySequence_SetSlice()} and
@ref{4938,,PySequence_DelSlice()}.  It has the same signature as
@code{PyObject_SetItem()}, but `v' can also be set to @code{NULL} to delete
an item.  If this slot is @code{NULL}, the object does not support item
assignment and deletion.
@end deffn

@node Sequence Object Structures,Buffer Object Structures,Mapping Object Structures,Objets type<3>
@anchor{c-api/typeobj sequence-object-structures}@anchor{4d5e}@anchor{c-api/typeobj sequence-structs}@anchor{4d4c}
@subsubsection Sequence Object Structures


@geindex PySequenceMethods (C type)
@anchor{c-api/typeobj c PySequenceMethods}@anchor{4813}
@deffn {C Type} type PySequenceMethods

This structure holds pointers to the functions which an object uses to
implement the sequence protocol.
@end deffn

@geindex PySequenceMethods.sq_length (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_length}@anchor{4abc}
@deffn {C Membre} @ref{49bb,,lenfunc} @ref{4813,,PySequenceMethods}.sq_length

This function is used by @ref{19e0,,PySequence_Size()} and
@ref{492f,,PyObject_Size()}, and has the same signature.  It is also used for
handling negative indices via the @ref{18ba,,sq_item}
and the @ref{4d40,,sq_ass_item} slots.
@end deffn

@geindex PySequenceMethods.sq_concat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_concat}@anchor{4d3e}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{4813,,PySequenceMethods}.sq_concat

This function is used by @ref{4935,,PySequence_Concat()} and has the same
signature.  It is also used by the @code{+} operator, after trying the numeric
addition via the @ref{4ab4,,nb_add} slot.
@end deffn

@geindex PySequenceMethods.sq_repeat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_repeat}@anchor{4d3f}
@deffn {C Membre} @ref{49c5,,ssizeargfunc} @ref{4813,,PySequenceMethods}.sq_repeat

This function is used by @ref{4940,,PySequence_Repeat()} and has the same
signature.  It is also used by the @code{*} operator, after trying numeric
multiplication via the @ref{4d1d,,nb_multiply} slot.
@end deffn

@geindex PySequenceMethods.sq_item (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_item}@anchor{18ba}
@deffn {C Membre} @ref{49c5,,ssizeargfunc} @ref{4813,,PySequenceMethods}.sq_item

This function is used by @ref{19e1,,PySequence_GetItem()} and has the same
signature.  It is also used by @ref{33d,,PyObject_GetItem()}, after trying
the subscription via the @ref{18bb,,mp_subscript} slot.
This slot must be filled for the @ref{4934,,PySequence_Check()}
function to return @code{1}, it can be @code{NULL} otherwise.

Negative indexes are handled as follows: if the @ref{4abc,,sq_length} slot is
filled, it is called and the sequence length is used to compute a positive
index which is passed to  @ref{18ba,,sq_item}.  If @code{sq_length} is @code{NULL},
the index is passed as is to the function.
@end deffn

@geindex PySequenceMethods.sq_ass_item (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_ass_item}@anchor{4d40}
@deffn {C Membre} @ref{49c6,,ssizeobjargproc} @ref{4813,,PySequenceMethods}.sq_ass_item

This function is used by @ref{19e2,,PySequence_SetItem()} and has the same
signature.  It is also used by @ref{484e,,PyObject_SetItem()} and
@ref{4921,,PyObject_DelItem()}, after trying the item assignment and deletion
via the @ref{4d3d,,mp_ass_subscript} slot.
This slot may be left to @code{NULL} if the object does not support
item assignment and deletion.
@end deffn

@geindex PySequenceMethods.sq_contains (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_contains}@anchor{4d41}
@deffn {C Membre} @ref{49be,,objobjproc} @ref{4813,,PySequenceMethods}.sq_contains

This function may be used by @ref{4936,,PySequence_Contains()} and has the same
signature.  This slot may be left to @code{NULL}, in this case
@code{PySequence_Contains()} simply traverses the sequence until it
finds a match.
@end deffn

@geindex PySequenceMethods.sq_inplace_concat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_inplace_concat}@anchor{4d42}
@deffn {C Membre} @ref{49ae,,binaryfunc} @ref{4813,,PySequenceMethods}.sq_inplace_concat

This function is used by @ref{493b,,PySequence_InPlaceConcat()} and has the same
signature.  It should modify its first operand, and return it.  This slot
may be left to @code{NULL}, in this case @code{PySequence_InPlaceConcat()}
will fall back to @ref{4935,,PySequence_Concat()}.  It is also used by the
augmented assignment @code{+=}, after trying numeric in-place addition
via the @ref{4d1a,,nb_inplace_add} slot.
@end deffn

@geindex PySequenceMethods.sq_inplace_repeat (C member)
@anchor{c-api/typeobj c PySequenceMethods sq_inplace_repeat}@anchor{4d43}
@deffn {C Membre} @ref{49c5,,ssizeargfunc} @ref{4813,,PySequenceMethods}.sq_inplace_repeat

This function is used by @ref{493c,,PySequence_InPlaceRepeat()} and has the same
signature.  It should modify its first operand, and return it.  This slot
may be left to @code{NULL}, in this case @code{PySequence_InPlaceRepeat()}
will fall back to @ref{4940,,PySequence_Repeat()}.  It is also used by the
augmented assignment @code{*=}, after trying numeric in-place multiplication
via the @ref{4d1e,,nb_inplace_multiply} slot.
@end deffn

@node Buffer Object Structures,Async Object Structures,Sequence Object Structures,Objets type<3>
@anchor{c-api/typeobj buffer-object-structures}@anchor{4d5f}@anchor{c-api/typeobj buffer-structs}@anchor{4a7f}
@subsubsection Buffer Object Structures


@geindex PyBufferProcs (C type)
@anchor{c-api/typeobj c PyBufferProcs}@anchor{4ac3}
@deffn {C Type} type PyBufferProcs

This structure holds pointers to the functions required by the
@ref{38e,,Buffer protocol}. The protocol defines how
an exporter object can expose its internal data to consumer objects.
@end deffn

@geindex PyBufferProcs.bf_getbuffer (C member)
@anchor{c-api/typeobj c PyBufferProcs bf_getbuffer}@anchor{74c}
@deffn {C Membre} @ref{49b4,,getbufferproc} @ref{4ac3,,PyBufferProcs}.bf_getbuffer

The signature of this function is:

@example
int (PyObject *exporter, Py_buffer *view, int flags);
@end example

Handle a request to `exporter' to fill in `view' as specified by `flags'.
Except for point (3), an implementation of this function MUST take these
steps:


@enumerate 

@item 
Check if the request can be met. If not, raise @ref{17b2,,BufferError},
set view->obj to @code{NULL} and return @code{-1}.

@item 
Fill in the requested fields.

@item 
Increment an internal counter for the number of exports.

@item 
Set view->obj to `exporter' and increment view->obj.

@item 
Return @code{0}.
@end enumerate

If `exporter' is part of a chain or tree of buffer providers, two main
schemes can be used:


@itemize *

@item 
Re-export: Each member of the tree acts as the exporting object and
sets view->obj to a new reference to itself.

@item 
Redirect: The buffer request is redirected to the root object of the
tree. Here, view->obj will be a new reference to the root
object.
@end itemize

The individual fields of `view' are described in section
@ref{4a80,,Buffer structure}, the rules how an exporter
must react to specific requests are in section
@ref{43dc,,Buffer request types}.

All memory pointed to in the @ref{742,,Py_buffer} structure belongs to
the exporter and must remain valid until there are no consumers left.
@ref{4a8a,,format}, @ref{4a8c,,shape},
@ref{4a84,,strides}, @ref{4a8e,,suboffsets}
and @ref{4a91,,internal}
are read-only for the consumer.

@ref{74a,,PyBuffer_FillInfo()} provides an easy way of exposing a simple
bytes buffer while dealing correctly with all request types.

@ref{390,,PyObject_GetBuffer()} is the interface for the consumer that
wraps this function.
@end deffn

@geindex PyBufferProcs.bf_releasebuffer (C member)
@anchor{c-api/typeobj c PyBufferProcs bf_releasebuffer}@anchor{74d}
@deffn {C Membre} @ref{49bf,,releasebufferproc} @ref{4ac3,,PyBufferProcs}.bf_releasebuffer

The signature of this function is:

@example
void (PyObject *exporter, Py_buffer *view);
@end example

Handle a request to release the resources of the buffer. If no resources
need to be released, @ref{74d,,PyBufferProcs.bf_releasebuffer} may be
@code{NULL}. Otherwise, a standard implementation of this function will take
these optional steps:


@enumerate 

@item 
Decrement an internal counter for the number of exports.

@item 
If the counter is @code{0}, free all memory associated with `view'.
@end enumerate

The exporter MUST use the @ref{4a91,,internal} field to keep
track of buffer-specific resources. This field is guaranteed to remain
constant, while a consumer MAY pass a copy of the original buffer as the
`view' argument.

This function MUST NOT decrement view->obj, since that is
done automatically in @ref{391,,PyBuffer_Release()} (this scheme is
useful for breaking reference cycles).

@ref{391,,PyBuffer_Release()} is the interface for the consumer that
wraps this function.
@end deffn

@node Async Object Structures,Slot Type typedefs,Buffer Object Structures,Objets type<3>
@anchor{c-api/typeobj async-object-structures}@anchor{4d60}@anchor{c-api/typeobj async-structs}@anchor{4d4a}
@subsubsection Async Object Structures



Ajouté dans la version 3.5.


@geindex PyAsyncMethods (C type)
@anchor{c-api/typeobj c PyAsyncMethods}@anchor{4abb}
@deffn {C Type} type PyAsyncMethods

This structure holds pointers to the functions required to implement
@ref{1ab,,awaitable} and @ref{1a9,,asynchronous iterator} objects.

Here is the structure definition:

@example
typedef struct @{
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
    sendfunc am_send;
@} PyAsyncMethods;
@end example
@end deffn

@geindex PyAsyncMethods.am_await (C member)
@anchor{c-api/typeobj c PyAsyncMethods am_await}@anchor{4d15}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{4abb,,PyAsyncMethods}.am_await

The signature of this function is:

@example
PyObject *am_await(PyObject *self);
@end example

The returned object must be an @ref{1aa,,iterator}, i.e. @ref{1882,,PyIter_Check()}
must return @code{1} for it.

This slot may be set to @code{NULL} if an object is not an @ref{1ab,,awaitable}.
@end deffn

@geindex PyAsyncMethods.am_aiter (C member)
@anchor{c-api/typeobj c PyAsyncMethods am_aiter}@anchor{4d16}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{4abb,,PyAsyncMethods}.am_aiter

The signature of this function is:

@example
PyObject *am_aiter(PyObject *self);
@end example

Must return an @ref{1a9,,asynchronous iterator} object.
See @ref{1e8f,,__anext__()} for details.

This slot may be set to @code{NULL} if an object does not implement
asynchronous iteration protocol.
@end deffn

@geindex PyAsyncMethods.am_anext (C member)
@anchor{c-api/typeobj c PyAsyncMethods am_anext}@anchor{4d17}
@deffn {C Membre} @ref{49c9,,unaryfunc} @ref{4abb,,PyAsyncMethods}.am_anext

The signature of this function is:

@example
PyObject *am_anext(PyObject *self);
@end example

Must return an @ref{1ab,,awaitable} object.
See @ref{1e8f,,__anext__()} for details.
This slot may be set to @code{NULL}.
@end deffn

@geindex PyAsyncMethods.am_send (C member)
@anchor{c-api/typeobj c PyAsyncMethods am_send}@anchor{4d18}
@deffn {C Membre} @ref{4d19,,sendfunc} @ref{4abb,,PyAsyncMethods}.am_send

The signature of this function is:

@example
PySendResult am_send(PyObject *self, PyObject *arg, PyObject **result);
@end example

See @ref{884,,PyIter_Send()} for details.
This slot may be set to @code{NULL}.


Ajouté dans la version 3.10.

@end deffn

@node Slot Type typedefs,Exemples<37>,Async Object Structures,Objets type<3>
@anchor{c-api/typeobj id6}@anchor{4d45}@anchor{c-api/typeobj slot-type-typedefs}@anchor{4d61}
@subsubsection Slot Type typedefs


@geindex allocfunc (C type)
@anchor{c-api/typeobj c allocfunc}@anchor{49ad}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*allocfunc)(@ref{a93,,PyTypeObject} *cls, @ref{a4e,,Py_ssize_t} nitems)
` Part of the @ref{53e,,Stable ABI}.'
The purpose of this function is to separate memory allocation from memory
initialization.  It should return a pointer to a block of memory of adequate
length for the instance, suitably aligned, and initialized to zeros, but with
@ref{88b,,ob_refcnt} set to @code{1} and @ref{47ec,,ob_type} set to the type argument.  If
the type's @ref{1ef2,,tp_itemsize} is non-zero, the object's @ref{499b,,ob_size} field
should be initialized to `nitems' and the length of the allocated memory block
should be @code{tp_basicsize + nitems*tp_itemsize}, rounded up to a multiple of
@code{sizeof(void*)}; otherwise, `nitems' is not used and the length of the block
should be @ref{974,,tp_basicsize}.

This function should not do any other instance initialization, not even to
allocate additional memory; that should be done by @ref{56b,,tp_new}.
@end deffn

@geindex destructor (C type)
@anchor{c-api/typeobj c destructor}@anchor{49b1}
@deffn {C Type} typedef void (*destructor)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex freefunc (C type)
@anchor{c-api/typeobj c freefunc}@anchor{4bb2}
@deffn {C Type} typedef void (*freefunc)(void*)

See @ref{47ef,,tp_free}.
@end deffn

@geindex newfunc (C type)
@anchor{c-api/typeobj c newfunc}@anchor{49bc}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*newfunc)(@ref{a93,,PyTypeObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{56b,,tp_new}.
@end deffn

@geindex initproc (C type)
@anchor{c-api/typeobj c initproc}@anchor{49b8}
@deffn {C Type} typedef int (*initproc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{56d,,tp_init}.
@end deffn

@geindex reprfunc (C type)
@anchor{c-api/typeobj c reprfunc}@anchor{49c0}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*reprfunc)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{4803,,tp_repr}.
@end deffn

@geindex getattrfunc (C type)
@anchor{c-api/typeobj c getattrfunc}@anchor{49b2}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*getattrfunc)(@ref{32f,,PyObject} *self, char *attr)
` Part of the @ref{53e,,Stable ABI}.'
Return the value of the named attribute for the object.
@end deffn

@geindex setattrfunc (C type)
@anchor{c-api/typeobj c setattrfunc}@anchor{49c2}
@deffn {C Type} typedef int (*setattrfunc)(@ref{32f,,PyObject} *self, char *attr, @ref{32f,,PyObject} *value)
` Part of the @ref{53e,,Stable ABI}.'
Set the value of the named attribute for the object.
The value argument is set to @code{NULL} to delete the attribute.
@end deffn

@geindex getattrofunc (C type)
@anchor{c-api/typeobj c getattrofunc}@anchor{49b3}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*getattrofunc)(@ref{32f,,PyObject} *self, @ref{32f,,PyObject} *attr)
` Part of the @ref{53e,,Stable ABI}.'
Return the value of the named attribute for the object.

See @ref{167b,,tp_getattro}.
@end deffn

@geindex setattrofunc (C type)
@anchor{c-api/typeobj c setattrofunc}@anchor{49c3}
@deffn {C Type} typedef int (*setattrofunc)(@ref{32f,,PyObject} *self, @ref{32f,,PyObject} *attr, @ref{32f,,PyObject} *value)
` Part of the @ref{53e,,Stable ABI}.'
Set the value of the named attribute for the object.
The value argument is set to @code{NULL} to delete the attribute.

See @ref{4807,,tp_setattro}.
@end deffn

@geindex descrgetfunc (C type)
@anchor{c-api/typeobj c descrgetfunc}@anchor{49af}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*descrgetfunc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{4d0e,,tp_descr_get}.
@end deffn

@geindex descrsetfunc (C type)
@anchor{c-api/typeobj c descrsetfunc}@anchor{49b0}
@deffn {C Type} typedef int (*descrsetfunc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{1884,,tp_descr_set}.
@end deffn

@geindex hashfunc (C type)
@anchor{c-api/typeobj c hashfunc}@anchor{49b7}
@deffn {C Type} typedef @ref{1242,,Py_hash_t} (*hashfunc)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{4815,,tp_hash}.
@end deffn

@geindex richcmpfunc (C type)
@anchor{c-api/typeobj c richcmpfunc}@anchor{49c1}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*richcmpfunc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, int)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{480f,,tp_richcompare}.
@end deffn

@geindex getiterfunc (C type)
@anchor{c-api/typeobj c getiterfunc}@anchor{49b5}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*getiterfunc)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{14a4,,tp_iter}.
@end deffn

@geindex iternextfunc (C type)
@anchor{c-api/typeobj c iternextfunc}@anchor{49ba}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*iternextfunc)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
See @ref{14a5,,tp_iternext}.
@end deffn

@geindex lenfunc (C type)
@anchor{c-api/typeobj c lenfunc}@anchor{49bb}
@deffn {C Type} typedef @ref{a4e,,Py_ssize_t} (*lenfunc)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex getbufferproc (C type)
@anchor{c-api/typeobj c getbufferproc}@anchor{49b4}
@deffn {C Type} typedef int (*getbufferproc)(@ref{32f,,PyObject}*, @ref{742,,Py_buffer}*, int)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
@end deffn

@geindex releasebufferproc (C type)
@anchor{c-api/typeobj c releasebufferproc}@anchor{49bf}
@deffn {C Type} typedef void (*releasebufferproc)(@ref{32f,,PyObject}*, @ref{742,,Py_buffer}*)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.12.'
@end deffn

@geindex unaryfunc (C type)
@anchor{c-api/typeobj c unaryfunc}@anchor{49c9}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*unaryfunc)(@ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex binaryfunc (C type)
@anchor{c-api/typeobj c binaryfunc}@anchor{49ae}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*binaryfunc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex sendfunc (C type)
@anchor{c-api/typeobj c sendfunc}@anchor{4d19}
@deffn {C Type} typedef @ref{4a7c,,PySendResult} (*sendfunc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}**)

See @ref{4d18,,am_send}.
@end deffn

@geindex ternaryfunc (C type)
@anchor{c-api/typeobj c ternaryfunc}@anchor{49c7}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*ternaryfunc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex ssizeargfunc (C type)
@anchor{c-api/typeobj c ssizeargfunc}@anchor{49c5}
@deffn {C Type} typedef @ref{32f,,PyObject} *(*ssizeargfunc)(@ref{32f,,PyObject}*, @ref{a4e,,Py_ssize_t})
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex ssizeobjargproc (C type)
@anchor{c-api/typeobj c ssizeobjargproc}@anchor{49c6}
@deffn {C Type} typedef int (*ssizeobjargproc)(@ref{32f,,PyObject}*, @ref{a4e,,Py_ssize_t}, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex objobjproc (C type)
@anchor{c-api/typeobj c objobjproc}@anchor{49be}
@deffn {C Type} typedef int (*objobjproc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@geindex objobjargproc (C type)
@anchor{c-api/typeobj c objobjargproc}@anchor{49bd}
@deffn {C Type} typedef int (*objobjargproc)(@ref{32f,,PyObject}*, @ref{32f,,PyObject}*, @ref{32f,,PyObject}*)
` Part of the @ref{53e,,Stable ABI}.'
@end deffn

@node Exemples<37>,,Slot Type typedefs,Objets type<3>
@anchor{c-api/typeobj examples}@anchor{4d62}@anchor{c-api/typeobj typedef-examples}@anchor{4d06}
@subsubsection Exemples


The following are simple examples of Python type definitions.  They
include common usage you may encounter.  Some demonstrate tricky corner
cases.  For more examples, practical info, and a tutorial, see
@ref{47e5,,Tutoriel ; définir des types dans des extensions} and @ref{47fe,,Définir les types d'extension ; divers sujets}.

A basic @ref{769,,static type}:

@example
typedef struct @{
    PyObject_HEAD
    const char *data;
@} MyObject;

static PyTypeObject MyObject_Type = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = PyDoc_STR("My objects"),
    .tp_new = myobj_new,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
@};
@end example

You may also find older code (especially in the CPython code base)
with a more verbose initializer:

@example
static PyTypeObject MyObject_Type = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    "mymod.MyObject",               /* tp_name */
    sizeof(MyObject),               /* tp_basicsize */
    0,                              /* tp_itemsize */
    (destructor)myobj_dealloc,      /* tp_dealloc */
    0,                              /* tp_vectorcall_offset */
    0,                              /* tp_getattr */
    0,                              /* tp_setattr */
    0,                              /* tp_as_async */
    (reprfunc)myobj_repr,           /* tp_repr */
    0,                              /* tp_as_number */
    0,                              /* tp_as_sequence */
    0,                              /* tp_as_mapping */
    0,                              /* tp_hash */
    0,                              /* tp_call */
    0,                              /* tp_str */
    0,                              /* tp_getattro */
    0,                              /* tp_setattro */
    0,                              /* tp_as_buffer */
    0,                              /* tp_flags */
    PyDoc_STR("My objects"),        /* tp_doc */
    0,                              /* tp_traverse */
    0,                              /* tp_clear */
    0,                              /* tp_richcompare */
    0,                              /* tp_weaklistoffset */
    0,                              /* tp_iter */
    0,                              /* tp_iternext */
    0,                              /* tp_methods */
    0,                              /* tp_members */
    0,                              /* tp_getset */
    0,                              /* tp_base */
    0,                              /* tp_dict */
    0,                              /* tp_descr_get */
    0,                              /* tp_descr_set */
    0,                              /* tp_dictoffset */
    0,                              /* tp_init */
    0,                              /* tp_alloc */
    myobj_new,                      /* tp_new */
@};
@end example

A type that supports weakrefs, instance dicts, and hashing:

@example
typedef struct @{
    PyObject_HEAD
    const char *data;
@} MyObject;

static PyTypeObject MyObject_Type = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject),
    .tp_doc = PyDoc_STR("My objects"),
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE |
         Py_TPFLAGS_HAVE_GC | Py_TPFLAGS_MANAGED_DICT |
         Py_TPFLAGS_MANAGED_WEAKREF,
    .tp_new = myobj_new,
    .tp_traverse = (traverseproc)myobj_traverse,
    .tp_clear = (inquiry)myobj_clear,
    .tp_alloc = PyType_GenericNew,
    .tp_dealloc = (destructor)myobj_dealloc,
    .tp_repr = (reprfunc)myobj_repr,
    .tp_hash = (hashfunc)myobj_hash,
    .tp_richcompare = PyBaseObject_Type.tp_richcompare,
@};
@end example

A str subclass that cannot be subclassed and cannot be called
to create instances (e.g. uses a separate factory func) using
@ref{56e,,Py_TPFLAGS_DISALLOW_INSTANTIATION} flag:

@example
typedef struct @{
    PyUnicodeObject raw;
    char *extra;
@} MyStr;

static PyTypeObject MyStr_Type = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyStr",
    .tp_basicsize = sizeof(MyStr),
    .tp_base = NULL,  // set to &PyUnicode_Type in module init
    .tp_doc = PyDoc_STR("my custom str"),
    .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,
    .tp_repr = (reprfunc)myobj_repr,
@};
@end example

The simplest @ref{769,,static type} with fixed-length instances:

@example
typedef struct @{
    PyObject_HEAD
@} MyObject;

static PyTypeObject MyObject_Type = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
@};
@end example

The simplest @ref{769,,static type} with variable-length instances:

@example
typedef struct @{
    PyObject_VAR_HEAD
    const char *data[1];
@} MyObject;

static PyTypeObject MyObject_Type = @{
    PyVarObject_HEAD_INIT(NULL, 0)
    .tp_name = "mymod.MyObject",
    .tp_basicsize = sizeof(MyObject) - sizeof(char *),
    .tp_itemsize = sizeof(char *),
@};
@end example

@node Supporting Cyclic Garbage Collection,,Objets type<3>,Implémentation d'objets
@anchor{c-api/gcsupport doc}@anchor{4d63}@anchor{c-api/gcsupport supporting-cycle-detection}@anchor{4d4e}@anchor{c-api/gcsupport supporting-cyclic-garbage-collection}@anchor{4d64}
@subsection Supporting Cyclic Garbage Collection


Python's support for detecting and collecting garbage which involves circular
references requires support from object types which are "containers" for other
objects which may also be containers.  Types which do not store references to
other objects, or which only store references to atomic types (such as numbers
or strings), do not need to provide any explicit support for garbage
collection.

To create a container type, the @ref{184b,,tp_flags} field of the type object must
include the @ref{767,,Py_TPFLAGS_HAVE_GC} and provide an implementation of the
@ref{768,,tp_traverse} handler.  If instances of the type are mutable, a
@ref{4801,,tp_clear} implementation must also be provided.


@table @asis

@item @ref{767,,Py_TPFLAGS_HAVE_GC}

Objects with a type with this flag set must conform with the rules
documented here.  For convenience these objects will be referred to as
container objects.
@end table

Constructors for container types must conform to two rules:


@enumerate 

@item 
The memory for the object must be allocated using @ref{a90,,PyObject_GC_New}
or @ref{a91,,PyObject_GC_NewVar}.

@item 
Once all the fields which may contain references to other containers are
initialized, it must call @ref{14bc,,PyObject_GC_Track()}.
@end enumerate

Similarly, the deallocator for the object must conform to a similar pair of
rules:


@enumerate 

@item 
Before fields which refer to other containers are invalidated,
@ref{14bd,,PyObject_GC_UnTrack()} must be called.

@item 
The object's memory must be deallocated using @ref{14bb,,PyObject_GC_Del()}.

@cartouche
@quotation Avertissement 
If a type adds the Py_TPFLAGS_HAVE_GC, then it `must' implement at least
a @ref{768,,tp_traverse} handler or explicitly use one
from its subclass or subclasses.

When calling @ref{766,,PyType_Ready()} or some of the APIs that indirectly
call it like @ref{56a,,PyType_FromSpecWithBases()} or
@ref{569,,PyType_FromSpec()} the interpreter will automatically populate the
@ref{184b,,tp_flags}, @ref{768,,tp_traverse}
and @ref{4801,,tp_clear} fields if the type inherits from a
class that implements the garbage collector protocol and the child class
does `not' include the @ref{767,,Py_TPFLAGS_HAVE_GC} flag.
@end quotation
@end cartouche
@end enumerate

@geindex PyObject_GC_New (C macro)
@anchor{c-api/gcsupport c PyObject_GC_New}@anchor{a90}
@deffn {C Macro} PyObject_GC_New (TYPE, typeobj)

Analogous to @ref{972,,PyObject_New} but for container objects with the
@ref{767,,Py_TPFLAGS_HAVE_GC} flag set.
@end deffn

@geindex PyObject_GC_NewVar (C macro)
@anchor{c-api/gcsupport c PyObject_GC_NewVar}@anchor{a91}
@deffn {C Macro} PyObject_GC_NewVar (TYPE, typeobj, size)

Analogous to @ref{973,,PyObject_NewVar} but for container objects with the
@ref{767,,Py_TPFLAGS_HAVE_GC} flag set.
@end deffn

@geindex PyUnstable_Object_GC_NewWithExtraData (C function)
@anchor{c-api/gcsupport c PyUnstable_Object_GC_NewWithExtraData}@anchor{16c3}
@deffn {C Fonction} @ref{32f,,PyObject} *PyUnstable_Object_GC_NewWithExtraData (PyTypeObject *type, size_t extra_size)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Analogous to @ref{a90,,PyObject_GC_New} but allocates `extra_size'
bytes at the end of the object (at offset
@ref{974,,tp_basicsize}).
The allocated memory is initialized to zeros,
except for the @ref{32f,,Python object header}.

The extra data will be deallocated with the object, but otherwise it is
not managed by Python.

@cartouche
@quotation Avertissement 
The function is marked as unstable because the final mechanism
for reserving extra data after an instance is not yet decided.
For allocating a variable number of fields, prefer using
@ref{4094,,PyVarObject} and @ref{1ef2,,tp_itemsize}
instead.
@end quotation
@end cartouche


Ajouté dans la version 3.12.

@end deffn

@geindex PyObject_GC_Resize (C macro)
@anchor{c-api/gcsupport c PyObject_GC_Resize}@anchor{16c8}
@deffn {C Macro} PyObject_GC_Resize (TYPE, op, newsize)

Resize an object allocated by @ref{973,,PyObject_NewVar}.
Returns the resized object of type @code{TYPE*} (refers to any C type)
or @code{NULL} on failure.

`op' must be of type @ref{4094,,PyVarObject}*
and must not be tracked by the collector yet.
`newsize' must be of type @ref{a4e,,Py_ssize_t}.
@end deffn

@geindex PyObject_GC_Track (C function)
@anchor{c-api/gcsupport c PyObject_GC_Track}@anchor{14bc}
@deffn {C Fonction} void PyObject_GC_Track (PyObject *op)
` Part of the @ref{53e,,Stable ABI}.'
Adds the object `op' to the set of container objects tracked by the
collector.  The collector can run at unexpected times so objects must be
valid while being tracked.  This should be called once all the fields
followed by the @ref{768,,tp_traverse} handler become valid, usually near the
end of the constructor.
@end deffn

@geindex PyObject_IS_GC (C function)
@anchor{c-api/gcsupport c PyObject_IS_GC}@anchor{971}
@deffn {C Fonction} int PyObject_IS_GC (PyObject *obj)

Returns non-zero if the object implements the garbage collector protocol,
otherwise returns 0.

The object cannot be tracked by the garbage collector if this function returns 0.
@end deffn

@geindex PyObject_GC_IsTracked (C function)
@anchor{c-api/gcsupport c PyObject_GC_IsTracked}@anchor{963}
@deffn {C Fonction} int PyObject_GC_IsTracked (PyObject *op)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Returns 1 if the object type of `op' implements the GC protocol and `op' is being
currently tracked by the garbage collector and 0 otherwise.

This is analogous to the Python function @ref{12ec,,gc.is_tracked()}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_GC_IsFinalized (C function)
@anchor{c-api/gcsupport c PyObject_GC_IsFinalized}@anchor{964}
@deffn {C Fonction} int PyObject_GC_IsFinalized (PyObject *op)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.9.'
Returns 1 if the object type of `op' implements the GC protocol and `op' has been
already finalized by the garbage collector and 0 otherwise.

This is analogous to the Python function @ref{8ea,,gc.is_finalized()}.


Ajouté dans la version 3.9.

@end deffn

@geindex PyObject_GC_Del (C function)
@anchor{c-api/gcsupport c PyObject_GC_Del}@anchor{14bb}
@deffn {C Fonction} void PyObject_GC_Del (void *op)
` Part of the @ref{53e,,Stable ABI}.'
Releases memory allocated to an object using @ref{a90,,PyObject_GC_New} or
@ref{a91,,PyObject_GC_NewVar}.
@end deffn

@geindex PyObject_GC_UnTrack (C function)
@anchor{c-api/gcsupport c PyObject_GC_UnTrack}@anchor{14bd}
@deffn {C Fonction} void PyObject_GC_UnTrack (void *op)
` Part of the @ref{53e,,Stable ABI}.'
Remove the object `op' from the set of container objects tracked by the
collector.  Note that @ref{14bc,,PyObject_GC_Track()} can be called again on
this object to add it back to the set of tracked objects.  The deallocator
(@ref{47ee,,tp_dealloc} handler) should call this for the object before any of
the fields used by the @ref{768,,tp_traverse} handler become invalid.
@end deffn


Modifié dans la version 3.8: The @code{_PyObject_GC_TRACK()} and @code{_PyObject_GC_UNTRACK()} macros
have been removed from the public C API.


The @ref{768,,tp_traverse} handler accepts a function parameter of this type:

@geindex visitproc (C type)
@anchor{c-api/gcsupport c visitproc}@anchor{49ca}
@deffn {C Type} typedef int (*visitproc)(@ref{32f,,PyObject} *object, void *arg)
` Part of the @ref{53e,,Stable ABI}.'
Type of the visitor function passed to the @ref{768,,tp_traverse} handler.
The function should be called with an object to traverse as `object' and
the third parameter to the @ref{768,,tp_traverse} handler as `arg'.  The
Python core uses several visitor functions to implement cyclic garbage
detection; it's not expected that users will need to write their own
visitor functions.
@end deffn

The @ref{768,,tp_traverse} handler must have the following type:

@geindex traverseproc (C type)
@anchor{c-api/gcsupport c traverseproc}@anchor{49c8}
@deffn {C Type} typedef int (*traverseproc)(@ref{32f,,PyObject} *self, @ref{49ca,,visitproc} visit, void *arg)
` Part of the @ref{53e,,Stable ABI}.'
Traversal function for a container object.  Implementations must call the
`visit' function for each object directly contained by `self', with the
parameters to `visit' being the contained object and the `arg' value passed
to the handler.  The `visit' function must not be called with a @code{NULL}
object argument.  If `visit' returns a non-zero value that value should be
returned immediately.
@end deffn

To simplify writing @ref{768,,tp_traverse} handlers, a @ref{47f8,,Py_VISIT()} macro is
provided.  In order to use this macro, the @ref{768,,tp_traverse} implementation
must name its arguments exactly `visit' and `arg':

@geindex Py_VISIT (C function)
@anchor{c-api/gcsupport c Py_VISIT}@anchor{47f8}
@deffn {C Fonction} void Py_VISIT (PyObject *o)

If `o' is not @code{NULL}, call the `visit' callback, with arguments `o'
and `arg'.  If `visit' returns a non-zero value, then return it.
Using this macro, @ref{768,,tp_traverse} handlers
look like:

@example
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
@{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
@}
@end example
@end deffn

The @ref{4801,,tp_clear} handler must be of the @ref{49b9,,inquiry} type, or @code{NULL}
if the object is immutable.

@geindex inquiry (C type)
@anchor{c-api/gcsupport c inquiry}@anchor{49b9}
@deffn {C Type} typedef int (*inquiry)(@ref{32f,,PyObject} *self)
` Part of the @ref{53e,,Stable ABI}.'
Drop references that may have created reference cycles.  Immutable objects
do not have to define this method since they can never directly create
reference cycles.  Note that the object must still be valid after calling
this method (don't just call @ref{55b,,Py_DECREF()} on a reference).  The
collector will call this method if it detects that this object is involved
in a reference cycle.
@end deffn

@menu
* Controlling the Garbage Collector State:: 
* Querying Garbage Collector State:: 

@end menu

@node Controlling the Garbage Collector State,Querying Garbage Collector State,,Supporting Cyclic Garbage Collection
@anchor{c-api/gcsupport controlling-the-garbage-collector-state}@anchor{4d65}
@subsubsection Controlling the Garbage Collector State


The C-API provides the following functions for controlling
garbage collection runs.

@geindex PyGC_Collect (C function)
@anchor{c-api/gcsupport c PyGC_Collect}@anchor{97b}
@deffn {C Fonction} @ref{a4e,,Py_ssize_t} PyGC_Collect (void)
` Part of the @ref{53e,,Stable ABI}.'
Perform a full garbage collection, if the garbage collector is enabled.
(Note that @ref{a28,,gc.collect()} runs it unconditionally.)

Returns the number of collected + unreachable objects which cannot
be collected.
If the garbage collector is disabled or already collecting,
returns @code{0} immediately.
Errors during garbage collection are passed to @ref{1f4,,sys.unraisablehook}.
This function does not raise exceptions.
@end deffn

@geindex PyGC_Enable (C function)
@anchor{c-api/gcsupport c PyGC_Enable}@anchor{890}
@deffn {C Fonction} int PyGC_Enable (void)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Enable the garbage collector: similar to @ref{4388,,gc.enable()}.
Returns the previous state, 0 for disabled and 1 for enabled.


Ajouté dans la version 3.10.

@end deffn

@geindex PyGC_Disable (C function)
@anchor{c-api/gcsupport c PyGC_Disable}@anchor{891}
@deffn {C Fonction} int PyGC_Disable (void)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Disable the garbage collector: similar to @ref{4389,,gc.disable()}.
Returns the previous state, 0 for disabled and 1 for enabled.


Ajouté dans la version 3.10.

@end deffn

@geindex PyGC_IsEnabled (C function)
@anchor{c-api/gcsupport c PyGC_IsEnabled}@anchor{892}
@deffn {C Fonction} int PyGC_IsEnabled (void)
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.10.'
Query the state of the garbage collector: similar to @ref{438a,,gc.isenabled()}.
Returns the current state, 0 for disabled and 1 for enabled.


Ajouté dans la version 3.10.

@end deffn

@node Querying Garbage Collector State,,Controlling the Garbage Collector State,Supporting Cyclic Garbage Collection
@anchor{c-api/gcsupport querying-garbage-collector-state}@anchor{4d66}
@subsubsection Querying Garbage Collector State


The C-API provides the following interface for querying information about
the garbage collector.

@geindex PyUnstable_GC_VisitObjects (C function)
@anchor{c-api/gcsupport c PyUnstable_GC_VisitObjects}@anchor{4d67}
@deffn {C Fonction} void PyUnstable_GC_VisitObjects (gcvisitobjects_t callback, void *arg)

@cartouche
@quotation This is Unstable API. It may change without warning in minor releases. `This is @ref{532,,Unstable API}. It may change without warning in minor releases.'
@end quotation
@end cartouche

Run supplied `callback' on all live GC-capable objects. `arg' is passed through to
all invocations of `callback'.

@cartouche
@quotation Avertissement 
If new objects are (de)allocated by the callback it is undefined if they
will be visited.

Garbage collection is disabled during operation. Explicitly running a collection
in the callback may lead to undefined behaviour e.g. visiting the same objects
multiple times or not at all.
@end quotation
@end cartouche


Ajouté dans la version 3.12.

@end deffn

@geindex gcvisitobjects_t (C type)
@anchor{c-api/gcsupport c gcvisitobjects_t}@anchor{4d68}
@deffn {C Type} typedef int (*gcvisitobjects_t)(@ref{32f,,PyObject} *object, void *arg)

Type of the visitor function to be passed to @ref{4d67,,PyUnstable_GC_VisitObjects()}.
`arg' is the same as the `arg' passed to @code{PyUnstable_GC_VisitObjects}.
Return @code{0} to continue iteration, return @code{1} to stop iteration. Other return
values are reserved for now so behavior on returning anything else is undefined.


Ajouté dans la version 3.12.

@end deffn

@node Version des API et ABI,Monitoring C API,Implémentation d'objets,Manuel de référence de l'API Python/C
@anchor{c-api/apiabiversion doc}@anchor{4d69}@anchor{c-api/apiabiversion api-and-abi-versioning}@anchor{4d6a}@anchor{c-api/apiabiversion apiabiversion}@anchor{42b5}
@section Version des API et ABI


CPython révèle son numéro de version dans les macros suivantes. À noter qu'ils correspondent au code de la version `compilée' avec, pas nécessairement la version utilisée à l'`exécution'.

Voir @ref{53e,,Stabilité de l’API C} pour une discussion sur la stabilité des API et ABI entre (ou en fonction) de la version.

@geindex PY_MAJOR_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MAJOR_VERSION}@anchor{4d6b}
@deffn {C Macro} PY_MAJOR_VERSION

Le @code{3} dans @code{3.4.1a2}.)
@end deffn

@geindex PY_MINOR_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MINOR_VERSION}@anchor{4d6c}
@deffn {C Macro} PY_MINOR_VERSION

Le @code{4} dans @code{3.4.1a2}.
@end deffn

@geindex PY_MICRO_VERSION (C macro)
@anchor{c-api/apiabiversion c PY_MICRO_VERSION}@anchor{4d6d}
@deffn {C Macro} PY_MICRO_VERSION

Le @code{1} dans @code{3.4.1a2}.)
@end deffn

@geindex PY_RELEASE_LEVEL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_LEVEL}@anchor{4d6e}
@deffn {C Macro} PY_RELEASE_LEVEL

The @code{a} in @code{3.4.1a2}.
This can be @code{0xA} for alpha, @code{0xB} for beta, @code{0xC} for release
candidate or @code{0xF} for final.
@end deffn

@geindex PY_RELEASE_SERIAL (C macro)
@anchor{c-api/apiabiversion c PY_RELEASE_SERIAL}@anchor{4d6f}
@deffn {C Macro} PY_RELEASE_SERIAL

Le @code{2} dans @code{3.4.1a2}. Nul pour des versions finales.
@end deffn

@geindex PY_VERSION_HEX (C macro)
@anchor{c-api/apiabiversion c PY_VERSION_HEX}@anchor{741}
@deffn {C Macro} PY_VERSION_HEX

Le numéro de version de Python encodé en un seul entier.

L'information sur la version sous-jacente peut être trouvée en la traitant comme un nombre sous 32 bits de la manière suivante :


@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Octets

@tab

Bits (ordre gros-boutiste)

@tab

Signification

@tab

Valeur pour @code{3.4.1a2}

@item

1

@tab

1-8

@tab

@code{PY_MAJOR_VERSION}

@tab

@code{0x03}

@item

2

@tab

9-16

@tab

@code{PY_MINOR_VERSION}

@tab

@code{0x04}

@item

3

@tab

17-24

@tab

@code{PY_MICRO_VERSION}

@tab

@code{0x01}

@item

4

@tab

25-28

@tab

@code{PY_RELEASE_LEVEL}

@tab

@code{0xA}

@item

29-32

@tab

@code{PY_RELEASE_SERIAL}

@tab

@code{0x2}

@end multitable


Ainsi, @code{0x030401a2} est la version en notation hexadécimale sur un entier de @code{3.4.1a2} et @code{0x030a00f0} est la version en notation hexadécimale sur un entier de @code{3.10.0}

Vous pouvez l'utiliser pour les comparaisons numériques, par exemple, @code{#if PY_VERSION_HEX >= ...}.

This version is also available via the symbol @ref{740,,Py_Version}.
@end deffn

@geindex Py_Version (C var)
@anchor{c-api/apiabiversion c Py_Version}@anchor{740}
@deffn {C Variable} const unsigned long Py_Version
` Part of the @ref{53e,,Stable ABI} Depuis la version 3.11.'
La version à l'exécution de Python est encodée en une constante, avec le même format que la macro @ref{741,,PY_VERSION_HEX}. Cela contient la version de Python utilisée lors de l'exécution.


Ajouté dans la version 3.11.

@end deffn

Toutes les macros données sont définies dans Include/patchlevel.h@footnote{https://github.com/python/cpython/tree/3.13/Include/patchlevel.h}.

@node Monitoring C API,Generating Execution Events,Version des API et ABI,Manuel de référence de l'API Python/C
@anchor{c-api/monitoring doc}@anchor{4d70}@anchor{c-api/monitoring c-api-monitoring}@anchor{15b}@anchor{c-api/monitoring monitoring-c-api}@anchor{4d71}
@section Monitoring C API


Added in version 3.13.

An extension may need to interact with the event monitoring system. Subscribing
to events and registering callbacks can be done via the Python API exposed in
@ref{d9,,sys.monitoring}.

@node Generating Execution Events,,Monitoring C API,Manuel de référence de l'API Python/C
@anchor{c-api/monitoring generating-execution-events}@anchor{4d72}
@section Generating Execution Events


The functions below make it possible for an extension to fire monitoring
events as it emulates the execution of Python code. Each of these functions
accepts a @code{PyMonitoringState} struct which contains concise information
about the activation state of events, as well as the event arguments, which
include a @code{PyObject*} representing the code object, the instruction offset
and sometimes additional, event-specific arguments (see @ref{d9,,sys.monitoring}
for details about the signatures of the different event callbacks).
The @code{codelike} argument should be an instance of @ref{2dd,,types.CodeType}
or of a type that emulates it.

The VM disables tracing when firing an event, so there is no need for user
code to do that.

Monitoring functions should not be called with an exception set,
except those listed below as working with the current exception.

@geindex PyMonitoringState (C type)
@anchor{c-api/monitoring c PyMonitoringState}@anchor{30d}
@deffn {C Type} type PyMonitoringState

Representation of the state of an event type. It is allocated by the user
while its contents are maintained by the monitoring API functions described below.
@end deffn

All of the functions below return 0 on success and -1 (with an exception set) on error.

See @ref{d9,,sys.monitoring} for descriptions of the events.

@geindex PyMonitoring_FirePyStartEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyStartEvent}@anchor{30e}
@deffn {C Fonction} int PyMonitoring_FirePyStartEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{PY_START} event.
@end deffn

@geindex PyMonitoring_FirePyResumeEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyResumeEvent}@anchor{30f}
@deffn {C Fonction} int PyMonitoring_FirePyResumeEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{PY_RESUME} event.
@end deffn

@geindex PyMonitoring_FirePyReturnEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyReturnEvent}@anchor{310}
@deffn {C Fonction} int PyMonitoring_FirePyReturnEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

Fire a @code{PY_RETURN} event.
@end deffn

@geindex PyMonitoring_FirePyYieldEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyYieldEvent}@anchor{311}
@deffn {C Fonction} int PyMonitoring_FirePyYieldEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

Fire a @code{PY_YIELD} event.
@end deffn

@geindex PyMonitoring_FireCallEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCallEvent}@anchor{312}
@deffn {C Fonction} int PyMonitoring_FireCallEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)

Fire a @code{CALL} event.
@end deffn

@geindex PyMonitoring_FireLineEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireLineEvent}@anchor{313}
@deffn {C Fonction} int PyMonitoring_FireLineEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)

Fire a @code{LINE} event.
@end deffn

@geindex PyMonitoring_FireJumpEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireJumpEvent}@anchor{314}
@deffn {C Fonction} int PyMonitoring_FireJumpEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Fire a @code{JUMP} event.
@end deffn

@geindex PyMonitoring_FireBranchEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireBranchEvent}@anchor{315}
@deffn {C Fonction} int PyMonitoring_FireBranchEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Fire a @code{BRANCH} event.
@end deffn

@geindex PyMonitoring_FireCReturnEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCReturnEvent}@anchor{316}
@deffn {C Fonction} int PyMonitoring_FireCReturnEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

Fire a @code{C_RETURN} event.
@end deffn

@geindex PyMonitoring_FirePyThrowEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyThrowEvent}@anchor{317}
@deffn {C Fonction} int PyMonitoring_FirePyThrowEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{PY_THROW} event with the current exception (as returned by
@ref{3ea,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireRaiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireRaiseEvent}@anchor{318}
@deffn {C Fonction} int PyMonitoring_FireRaiseEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{RAISE} event with the current exception (as returned by
@ref{3ea,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireCRaiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireCRaiseEvent}@anchor{319}
@deffn {C Fonction} int PyMonitoring_FireCRaiseEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{C_RAISE} event with the current exception (as returned by
@ref{3ea,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireReraiseEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireReraiseEvent}@anchor{31a}
@deffn {C Fonction} int PyMonitoring_FireReraiseEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{RERAISE} event with the current exception (as returned by
@ref{3ea,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireExceptionHandledEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireExceptionHandledEvent}@anchor{31b}
@deffn {C Fonction} int PyMonitoring_FireExceptionHandledEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire an @code{EXCEPTION_HANDLED} event with the current exception (as returned by
@ref{3ea,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FirePyUnwindEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FirePyUnwindEvent}@anchor{31c}
@deffn {C Fonction} int PyMonitoring_FirePyUnwindEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset)

Fire a @code{PY_UNWIND} event with the current exception (as returned by
@ref{3ea,,PyErr_GetRaisedException()}).
@end deffn

@geindex PyMonitoring_FireStopIterationEvent (C function)
@anchor{c-api/monitoring c PyMonitoring_FireStopIterationEvent}@anchor{31d}
@deffn {C Fonction} int PyMonitoring_FireStopIterationEvent (PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)

Fire a @code{STOP_ITERATION} event. If @code{value} is an instance of @ref{be8,,StopIteration}, it is used. Otherwise,
a new @ref{be8,,StopIteration} instance is created with @code{value} as its argument.
@end deffn

@menu
* Managing the Monitoring State:: 

@end menu

@node Managing the Monitoring State,,,Generating Execution Events
@anchor{c-api/monitoring managing-the-monitoring-state}@anchor{4d73}
@subsection Managing the Monitoring State


Monitoring states can be managed with the help of monitoring scopes. A scope
would typically correspond to a python function.

@geindex PyMonitoring_EnterScope (C function)
@anchor{c-api/monitoring c PyMonitoring_EnterScope}@anchor{31e}
@deffn {C Fonction} int PyMonitoring_EnterScope (PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)

Enter a monitored scope. @code{event_types} is an array of the event IDs for
events that may be fired from the scope. For example, the ID of a @code{PY_START}
event is the value @code{PY_MONITORING_EVENT_PY_START}, which is numerically equal
to the base-2 logarithm of @code{sys.monitoring.events.PY_START}.
@code{state_array} is an array with a monitoring state entry for each event in
@code{event_types}, it is allocated by the user but populated by
@code{PyMonitoring_EnterScope()} with information about the activation state of
the event. The size of @code{event_types} (and hence also of @code{state_array})
is given in @code{length}.

The @code{version} argument is a pointer to a value which should be allocated
by the user together with @code{state_array} and initialized to 0,
and then set only by @code{PyMonitoring_EnterScope()} itself. It allows this
function to determine whether event states have changed since the previous call,
and to return quickly if they have not.

The scopes referred to here are lexical scopes: a function, class or method.
@code{PyMonitoring_EnterScope()} should be called whenever the lexical scope is
entered. Scopes can be reentered, reusing the same `state_array' and `version',
in situations like when emulating a recursive Python function. When a code-like's
execution is paused, such as when emulating a generator, the scope needs to
be exited and re-entered.

The macros for `event_types' are:

@c The table is here to make the docs searchable, and to allow automatic
@c links to the identifiers.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Macro

@tab

Événement

@item

@geindex PY_MONITORING_EVENT_BRANCH (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_BRANCH}@anchor{4d74}
@deffn {C Macro} PY_MONITORING_EVENT_BRANCH
@end deffn

@tab

@ref{42ca,,BRANCH}

@item

@geindex PY_MONITORING_EVENT_CALL (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_CALL}@anchor{4d75}
@deffn {C Macro} PY_MONITORING_EVENT_CALL
@end deffn

@tab

@ref{15cf,,CALL}

@item

@geindex PY_MONITORING_EVENT_C_RAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_C_RAISE}@anchor{4d76}
@deffn {C Macro} PY_MONITORING_EVENT_C_RAISE
@end deffn

@tab

@ref{42cb,,C_RAISE}

@item

@geindex PY_MONITORING_EVENT_C_RETURN (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_C_RETURN}@anchor{4d77}
@deffn {C Macro} PY_MONITORING_EVENT_C_RETURN
@end deffn

@tab

@ref{42cc,,C_RETURN}

@item

@geindex PY_MONITORING_EVENT_EXCEPTION_HANDLED (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_EXCEPTION_HANDLED}@anchor{4d78}
@deffn {C Macro} PY_MONITORING_EVENT_EXCEPTION_HANDLED
@end deffn

@tab

@ref{42cd,,EXCEPTION_HANDLED}

@item

@geindex PY_MONITORING_EVENT_INSTRUCTION (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_INSTRUCTION}@anchor{4d79}
@deffn {C Macro} PY_MONITORING_EVENT_INSTRUCTION
@end deffn

@tab

@ref{42ce,,INSTRUCTION}

@item

@geindex PY_MONITORING_EVENT_JUMP (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_JUMP}@anchor{4d7a}
@deffn {C Macro} PY_MONITORING_EVENT_JUMP
@end deffn

@tab

@ref{42cf,,JUMP}

@item

@geindex PY_MONITORING_EVENT_LINE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_LINE}@anchor{4d7b}
@deffn {C Macro} PY_MONITORING_EVENT_LINE
@end deffn

@tab

@ref{42d0,,LINE}

@item

@geindex PY_MONITORING_EVENT_PY_RESUME (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_RESUME}@anchor{4d7c}
@deffn {C Macro} PY_MONITORING_EVENT_PY_RESUME
@end deffn

@tab

@ref{42d1,,PY_RESUME}

@item

@geindex PY_MONITORING_EVENT_PY_RETURN (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_RETURN}@anchor{4d7d}
@deffn {C Macro} PY_MONITORING_EVENT_PY_RETURN
@end deffn

@tab

@ref{42d2,,PY_RETURN}

@item

@geindex PY_MONITORING_EVENT_PY_START (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_START}@anchor{4d7e}
@deffn {C Macro} PY_MONITORING_EVENT_PY_START
@end deffn

@tab

@ref{42d3,,PY_START}

@item

@geindex PY_MONITORING_EVENT_PY_THROW (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_THROW}@anchor{4d7f}
@deffn {C Macro} PY_MONITORING_EVENT_PY_THROW
@end deffn

@tab

@ref{42d4,,PY_THROW}

@item

@geindex PY_MONITORING_EVENT_PY_UNWIND (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_UNWIND}@anchor{4d80}
@deffn {C Macro} PY_MONITORING_EVENT_PY_UNWIND
@end deffn

@tab

@ref{42d5,,PY_UNWIND}

@item

@geindex PY_MONITORING_EVENT_PY_YIELD (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_PY_YIELD}@anchor{4d81}
@deffn {C Macro} PY_MONITORING_EVENT_PY_YIELD
@end deffn

@tab

@ref{42d6,,PY_YIELD}

@item

@geindex PY_MONITORING_EVENT_RAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_RAISE}@anchor{4d82}
@deffn {C Macro} PY_MONITORING_EVENT_RAISE
@end deffn

@tab

@ref{1577,,RAISE}

@item

@geindex PY_MONITORING_EVENT_RERAISE (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_RERAISE}@anchor{4d83}
@deffn {C Macro} PY_MONITORING_EVENT_RERAISE
@end deffn

@tab

@ref{42d8,,RERAISE}

@item

@geindex PY_MONITORING_EVENT_STOP_ITERATION (C macro)
@anchor{c-api/monitoring c PY_MONITORING_EVENT_STOP_ITERATION}@anchor{4d84}
@deffn {C Macro} PY_MONITORING_EVENT_STOP_ITERATION
@end deffn

@tab

@ref{42d7,,STOP_ITERATION}

@end multitable

@end deffn

@geindex PyMonitoring_ExitScope (C function)
@anchor{c-api/monitoring c PyMonitoring_ExitScope}@anchor{31f}
@deffn {C Fonction} int PyMonitoring_ExitScope (void)

Exit the last scope that was entered with @code{PyMonitoring_EnterScope()}.
@end deffn

@node Installation de modules Python,Les HOWTOs de Python,Manuel de référence de l'API Python/C,Top
@anchor{installing/index doc}@anchor{4d85}@anchor{installing/index installing-index}@anchor{ee0}@anchor{installing/index installing-python-modules}@anchor{4d86}
@chapter Installation de modules Python


@*Email: 
@email{distutils-sig@@python.org}


En tant que logiciel libre populaire, Python bénéficie d'une communauté active de contributeurs et d'utilisateurs qui rendent à leur tour leurs logiciels disponibles, sous licence libre, pour les autres développeurs Python.

Cela permet aux utilisateurs de Python de partager et de collaborer efficacement, bénéficiant des solutions que les autres ont déjà crées pour résoudre les problèmes communs (ou même, parfois, rares !), aussi que de partager leurs propres solutions à tous.

This guide covers the installation part of the process. For a guide to
creating and sharing your own Python projects, refer to the
Python packaging user guide@footnote{https://packaging.python.org/en/latest/tutorials/packaging-projects/}.

@cartouche
@quotation Note 
Pour les entreprises et autres institutions, gardez en tête que certaines organisations ont leurs propres règles sur l'utilisation et la contribution au logiciel libre. Prenez ces règles en compte lorsque vous utilisez les outils de distribution et d'installation fournis par Python.
@end quotation
@end cartouche

@menu
* Vocabulaire:: 
* Utilisation de base: Utilisation de base<2>. 
* Comment puis-je … ?:: 
* Les problèmes d'installation typiques:: 

@end menu

@node Vocabulaire,Utilisation de base<2>,,Installation de modules Python
@anchor{installing/index key-terms}@anchor{4d87}
@section Vocabulaire



@itemize *

@item 
@code{pip} est l'outil d'installation de prédilection. À partir de Python 3.4, il est inclus par défaut avec l'installateur de Python.

@item 
Un `environnement virtuel' est un environnement Python semi-isolé qui autorise les paquets à être installés pour une application particulière, plutôt que d'être installés au niveau du système.

@item 
@code{venv} est l'outil standard pour créer des environnements virtuels, et est intégré à Python depuis la version 3.3. Depuis Python 3.4, il installe aussi @code{pip} dans tous les environnements virtuels créés.

@item 
@code{virtualenv} est une alternative tierce à @code{venv} (et son prédécesseur). Elle permet la création d'environnements virtuels pour les versions de Python antérieures à 3.4, qui ne fournissent pas de @code{venv}, ou ne sont pas capables d'installer automatiquement @code{pip} dans les environnements créés.

@item 
L'Index des Paquets Python@footnote{https://pypi.org} est un dépôt public des paquets sous licence ouverte disponibles pour tous les utilisateurs Python.

@item 
the Python Packaging Authority@footnote{https://www.pypa.io/} is the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation,
and issue trackers on GitHub@footnote{https://github.com/pypa}.

@item 
@code{distutils} est le premier système de construction et de distribution ajouté à la bibliothèque standard en 1998. Bien que l'utilisation directe de @code{distutils} soit progressivement supprimée, elle reste le fondement de l'infrastructure actuelle de construction de paquet et de distribution. Au-delà de rester dans la bibliothèque standard, son nom vit aussi sous d'autres formes, tel que la liste de diffusion utilisée pour coordonner le développement et les standards de la création de paquet.
@end itemize


Modifié dans la version 3.5: L'utilisation de @code{venv} est maintenant recommandée pour créer vos environnements virtuels.



@subsubheading Voir aussi


Guide Utilisateur de l'Empaquetage Python : Créer et utiliser des environnements virtuels@footnote{https://packaging.python.org/installing/#creating-virtual-environments}


@node Utilisation de base<2>,Comment puis-je … ?,Vocabulaire,Installation de modules Python
@anchor{installing/index basic-usage}@anchor{4d88}
@section Utilisation de base


Les outils standards de création de paquets sont tous conçus pour être utilisés à partir de la ligne de commande.

La commande suivante va installer la dernière version d'un module et ses dépendances depuis le `Python Package Index' :

@example
python -m pip install SomePackage
@end example

@cartouche
@quotation Note 
Pour les utilisateurs POSIX (y compris Mac OS X et Linux), les exemples de ce guide supposent l'utilisation d'un @ref{1c8e,,environnement virtuel}.

Pour les utilisateurs de Windows, les exemples de ce guide supposent que l'option proposant de modifier la variable d'environnement PATH à été cochée lors de l'installation de Python.
@end quotation
@end cartouche

Il est aussi possible de préciser une version minimum exacte directement depuis la ligne de commande. Utiliser des caractères de comparaison tel que @code{>}, @code{<} ou d'autres caractères spéciaux qui sont interprétés par le `shell', le nom du paquet et la version doivent être mis entre guillemets :

@example
python -m pip install SomePackage==1.0.4    # specific version
python -m pip install "SomePackage>=1.0.4"  # minimum version
@end example

Normalement, si un module approprié est déjà installé, l'installer à nouveau n'aura aucun effet. La mise à jour de modules existants doit être demandée explicitement :

@example
python -m pip install --upgrade SomePackage
@end example

Plus d'informations et de ressources concernant @code{pip} et ses capacités peuvent être trouvées dans le Python Packaging User Guide@footnote{https://packaging.python.org}.

La création d'environnements virtuels est réalisée grâce au module @ref{110,,venv}. Installer des paquets au sein de l'environnement virtuel courant utilise les commandes montrées précédemment.


@subsubheading Voir aussi


Guide Utilisateur de l'Empaquetage Python : Installer les paquets de la distribution Python@footnote{https://packaging.python.org/installing/}


@node Comment puis-je … ?,Les problèmes d'installation typiques,Utilisation de base<2>,Installation de modules Python
@anchor{installing/index how-do-i}@anchor{4d89}
@section Comment puis-je … ?


Ce sont des réponses rapides ou des liens pour certaines tâches courantes.

@menu
* ... Installer pip avec une version de Python antérieures à la 3.4 ?: Installer pip avec une version de Python antérieures à la 3 4 ?. 
* ... Installer des paquets juste pour l'utilisateur actuel ?: Installer des paquets juste pour l'utilisateur actuel ?. 
* ... Installer des paquets Python scientifiques ?: Installer des paquets Python scientifiques ?. 
* ... Travailler avec plusieurs versions de Python installés en parallèle ?: Travailler avec plusieurs versions de Python installés en parallèle ?. 

@end menu

@node Installer pip avec une version de Python antérieures à la 3 4 ?,Installer des paquets juste pour l'utilisateur actuel ?,,Comment puis-je … ?
@anchor{installing/index install-pip-in-versions-of-python-prior-to-python-3-4}@anchor{4d8a}
@subsection ... Installer @code{pip} avec une version de Python antérieures à la 3.4 ?


Python n'a commencé à fournir @code{pip} depuis Python 3.4. Pour les versions précédentes, @code{pip} a besoin d'être "amorcé" tel que décrit dans le `Python Packaging User Guide'.


@subsubheading Voir aussi


Guide Utilisateur de l'Empaquetage Python : Pré-requis pour installer des paquets@footnote{https://packaging.python.org/installing/#requirements-for-installing-packages}


@c installing-per-user-installation:

@node Installer des paquets juste pour l'utilisateur actuel ?,Installer des paquets Python scientifiques ?,Installer pip avec une version de Python antérieures à la 3 4 ?,Comment puis-je … ?
@anchor{installing/index install-packages-just-for-the-current-user}@anchor{4d8b}
@subsection ... Installer des paquets juste pour l'utilisateur actuel ?


Donner l'option @code{--user} à @code{python -m pip install} lui fera installer un paquet juste pour l'utilisateur en cours, plutôt que pour tous les utilisateurs du système.

@node Installer des paquets Python scientifiques ?,Travailler avec plusieurs versions de Python installés en parallèle ?,Installer des paquets juste pour l'utilisateur actuel ?,Comment puis-je … ?
@anchor{installing/index install-scientific-python-packages}@anchor{4d8c}
@subsection ... Installer des paquets Python scientifiques ?


Un certain nombre de paquets scientifiques Python ont des dépendances binaires complexes, et ne sont pas actuellement faciles à installer directement avec @code{pip}. Pour le moment, il est souvent plus simple pour les utilisateurs d'installer ces paquets par d'autres moyens@footnote{https://packaging.python.org/science/} plutôt que d'essayer de les installer avec @code{pip}.


@subsubheading Voir aussi


Guide Utilisateur de l'Empaquetage Python : Installer des paquets scientifiques@footnote{https://packaging.python.org/science/}


@node Travailler avec plusieurs versions de Python installés en parallèle ?,,Installer des paquets Python scientifiques ?,Comment puis-je … ?
@anchor{installing/index work-with-multiple-versions-of-python-installed-in-parallel}@anchor{4d8d}
@subsection ... Travailler avec plusieurs versions de Python installés en parallèle ?


Sous Linux, Max OS X et autres systèmes POSIX, utiliser les commandes Python de la version souhaitée en combinaison avec l'option @code{-m} permet de lancer la version appropriée de @code{pip} :

@example
python2   -m pip install SomePackage  # default Python 2
python2.7 -m pip install SomePackage  # specifically Python 2.7
python3   -m pip install SomePackage  # default Python 3
python3.4 -m pip install SomePackage  # specifically Python 3.4
@end example

Les versions appropriées des commandes @code{pip} peuvent aussi être disponibles.

Sous Windows, utilisez le lanceur Python @code{py} en combinaison avec l'option @code{-m} :

@example
py -2   -m pip install SomePackage  # default Python 2
py -2.7 -m pip install SomePackage  # specifically Python 2.7
py -3   -m pip install SomePackage  # default Python 3
py -3.4 -m pip install SomePackage  # specifically Python 3.4
@end example

@c other questions:
@c 
@c Once the Development & Deployment part of PPUG is fleshed out, some of
@c those sections should be linked from new questions here (most notably,
@c we should have a question about avoiding depending on PyPI that links to
@c https://packaging.python.org/en/latest/mirrors/)

@node Les problèmes d'installation typiques,,Comment puis-je … ?,Installation de modules Python
@anchor{installing/index common-installation-issues}@anchor{4d8e}
@section Les problèmes d'installation typiques


@menu
* Installer dans le Python du système sur Linux:: 
* Pip n'est pas installé:: 
* Installation d'extensions binaires:: 

@end menu

@node Installer dans le Python du système sur Linux,Pip n'est pas installé,,Les problèmes d'installation typiques
@anchor{installing/index installing-into-the-system-python-on-linux}@anchor{4d8f}
@subsection Installer dans le Python du système sur Linux


Sur les systèmes Linux, une installation de Python sera généralement incluse dans le cadre de la distribution. Installer dans cette installation de Python nécessite un accès `root' sur le système, et peut interférer avec le fonctionnement du gestionnaire de paquets du système et d'autres composants du système si un composant est mis à jour de façon inattendue en utilisant @code{pip}.

Sur de tels systèmes, il est souvent préférable d'utiliser un environnement virtuel ou une installation par l'utilisateur lors de l'installation des paquets avec @code{pip}.

@node Pip n'est pas installé,Installation d'extensions binaires,Installer dans le Python du système sur Linux,Les problèmes d'installation typiques
@anchor{installing/index pip-not-installed}@anchor{4d90}
@subsection @code{Pip} n'est pas installé


Il est possible que @code{pip} ne soit pas installé par défaut. Une solution est :

@example
python -m ensurepip --default-pip
@end example

Il existe également des ressources supplémentaires pour installer pip.@footnote{https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date}

@node Installation d'extensions binaires,,Pip n'est pas installé,Les problèmes d'installation typiques
@anchor{installing/index installing-binary-extensions}@anchor{4d91}
@subsection Installation d'extensions binaires


Python a généralement beaucoup misé sur une distribution basée sur les sources, avec laquelle les utilisateurs finaux devaient compiler, lors de l'installation, les modules d'extension à partir des sources.

Avec l'introduction du format binaire @code{wheel}, et la possibilité de publier des `wheels', pour, au moins Windows et Mac OS X, via le `Python Package Index', ce problème devrait diminuer au fil du temps, car les utilisateurs sont plus régulièrement en mesure d'installer des extensions pré-compilées plutôt que de devoir les compiler eux-mêmes.

Certaines solutions pour installer des paquets scientifiques@footnote{https://packaging.python.org/science/} qui ne sont pas encore disponibles comme @code{wheel} pré-construites peuvent aussi aider à obtenir d'autres extensions binaires sans devoir les construire localement.


@subsubheading Voir aussi


Guide Utilisateur de l'Empaquetage Python : Extensions binaires@footnote{https://packaging.python.org/extensions/}


@node Les HOWTOs de Python,Questions fréquemment posées sur Python,Installation de modules Python,Top
@anchor{howto/index doc}@anchor{4d92}@anchor{howto/index python-howtos}@anchor{4d93}
@chapter Les HOWTOs de Python


Python HOWTOs are documents that cover a specific topic in-depth.
Modeled on the Linux Documentation Project's HOWTO collection, this collection is an
effort to foster documentation that's more detailed than the
Python Library Reference.

@menu
* Portage des modules d'extension vers Python 3:: 
* Programmation Curses avec Python:: 
* Descriptor Guide:: 
* Debugging C API extensions and CPython Internals with GDB:: 
* Guide sur l'utilisation d'Enum:: 
* Guide pratique ; programmation fonctionnelle: Guide pratique programmation fonctionnelle. 
* Tutoriel sur la journalisation:: 
* Recettes pour la journalisation:: 
* Guide des expressions régulières:: 
* Guide pratique ; programmation avec les sockets: Guide pratique programmation avec les sockets. 
* Sorting Techniques:: 
* Guide Unicode:: 
* Guide pratique ; récupérer des ressources web en utilisant le module urllib: Guide pratique récupérer des ressources web en utilisant le module urllib. 
* Introduction au module ipaddress:: 
* Instrumenter CPython avec DTrace et SystemTap:: 
* Python support for the Linux perf profiler:: 
* Bonnes pratiques concernant les annotations:: 
* Isolating Extension Modules:: 
* timer file descriptor HOWTO:: 
* The Python 2.3 Method Resolution Order: The Python 2 3 Method Resolution Order. 
* Python experimental support for free threading:: 
* C API Extension Support for Free Threading:: 

@end menu

@node Portage des modules d'extension vers Python 3,Programmation Curses avec Python,,Les HOWTOs de Python
@anchor{howto/cporting doc}@anchor{4d94}@anchor{howto/cporting cporting-howto}@anchor{12bf}@anchor{howto/cporting porting-extension-modules-to-python-3}@anchor{4d95}
@section Portage des modules d'extension vers Python 3


Nous recommandons les ressources suivantes pour migrer les modules d'extensions vers Python 3 :


@itemize *

@item 
Le chapitre Migrating C extension@footnote{http://python3porting.com/cextensions.html} du livre `Supporting Python 3: An in-depth guide' (un livre sur le portage de Python 2 à Python 3) guide le lecteur souhaitant porter un module d'extension.

@item 
Le Porting guide@footnote{https://py3c.readthedocs.io/en/latest/guide.html} du projet `py3c' fournit des suggestions argumentées avec le code correspondant.

@item 
Les bibliothèques Cython@footnote{https://cython.org/} et CFFI@footnote{https://cffi.readthedocs.io/en/latest/} fournissent des abstractions de l'API C de Python. Les extensions ont généralement besoin d'être réécrites pour profiter de ces bibliothèques, mais elles prennent en charge les différences entre versions et implémentations de Python.
@end itemize

@node Programmation Curses avec Python,Descriptor Guide,Portage des modules d'extension vers Python 3,Les HOWTOs de Python
@anchor{howto/curses doc}@anchor{4d96}@anchor{howto/curses curses-howto}@anchor{2ec1}@anchor{howto/curses curses-programming-with-python}@anchor{4d97}
@section Programmation `Curses' avec Python


@*Auteur: 
A.M. Kuchling, Eric S. Raymond


@*Version: 
2.04


@subsubheading Résumé



Ce document décrit comment utiliser le module d'extension @ref{2b,,curses} pour contrôler l'affichage en mode texte.

@menu
* Qu'est-ce que curses ?:: 
* Lancement et arrêt une application curses:: 
* Fenêtres et tampons (pads en anglais): Fenêtres et tampons pads en anglais. 
* Affichage de texte:: 
* Entrées de l'utilisateur:: 
* Pour aller plus loin: Pour aller plus loin<2>. 

@end menu

@node Qu'est-ce que curses ?,Lancement et arrêt une application curses,,Programmation Curses avec Python
@anchor{howto/curses what-is-curses}@anchor{4d98}
@subsection Qu'est-ce que `curses' ?


La bibliothèque `curses' fournit une capacité de dessin à l'écran et de gestion du clavier indépendante du terminal pour les terminaux textuels ; ces terminaux comprennent les `VT100', la console Linux et le terminal simulé fourni par divers programmes. Les terminaux d'affichage prennent en charge divers codes de commande pour effectuer des opérations courantes telles que déplacer le curseur, faire défiler l'écran et effacer des zones. Différents terminaux utilisent des codes très différents et ont souvent leurs propres bizarreries mineures.

Dans un monde d'affichages graphiques, on pourrait se demander « pourquoi s'embêter ? ». Il est vrai que les terminaux d'affichage caractère par caractère sont une technologie obsolète, mais il existe des niches pour lesquelles la possibilité de faire des choses fantaisistes est encore précieuse. En exemple de niche, on peut citer les systèmes de type Unix de petite taille ou embarqués qui n'utilisent pas de serveur X. Il y a aussi les outils tels que les installateurs d'OS et les outils de configuration du noyau qui doivent être exécutés avant qu'un support graphique ne soit disponible.

The curses library provides fairly basic functionality, providing the
programmer with an abstraction of a display containing multiple
non-overlapping windows of text.  The contents of a window can be
changed in various ways---adding text, erasing it, changing its
appearance---and the curses library will figure out what control codes
need to be sent to the terminal to produce the right output.  curses
doesn't provide many user-interface concepts such as buttons, checkboxes,
or dialogs; if you need such features, consider a user interface library such as
Urwid@footnote{https://pypi.org/project/Urwid/}.

La bibliothèque `curses' a été écrite à l'origine pour BSD Unix ; les dernières versions `System V' d'Unix d'AT&T ont ajouté de nombreuses améliorations et de nouvelles fonctions. BSD `curses' n'est plus maintenu, ayant été remplacé par `ncurses', qui est une implémentation open-source de l'interface AT&T. Si vous utilisez un Unix open-source comme Linux ou FreeBSD, votre système utilise presque certainement `ncurses'. Comme la plupart des versions commerciales actuelles d'Unix sont basées sur le code `System V', toutes les fonctions décrites ici seront probablement disponibles. Les anciennes versions de `curses' portées par certains Unix propriétaires pourraient ne pas gérer toutes les fonctions.

The Windows version of Python doesn't include the @ref{2b,,curses}
module.  A ported version called UniCurses@footnote{https://pypi.org/project/UniCurses/} is available.

@menu
* Le module curses de Python:: 

@end menu

@node Le module curses de Python,,,Qu'est-ce que curses ?
@anchor{howto/curses the-python-curses-module}@anchor{4d99}
@subsubsection Le module `curses' de Python


The Python module is a fairly simple wrapper over the C functions provided by
curses; if you're already familiar with curses programming in C, it's really
easy to transfer that knowledge to Python.  The biggest difference is that the
Python interface makes things simpler by merging different C functions such as
@code{addstr()}, @code{mvaddstr()}, and @code{mvwaddstr()} into a single
@ref{2ed7,,addstr()} method.  You'll see this covered in more
detail later.

Ce guide pratique est une introduction à l'écriture de programmes en mode texte avec `curses' et Python. Il n'essaie pas d'être un guide complet de l'API `curses' ; pour cela, consultez la section du guide de la bibliothèque Python sur `ncurses' et les pages du manuel C pour `ncurses'. Il vous donne cependant les idées de base.

@node Lancement et arrêt une application curses,Fenêtres et tampons pads en anglais,Qu'est-ce que curses ?,Programmation Curses avec Python
@anchor{howto/curses starting-and-ending-a-curses-application}@anchor{4d9a}
@subsection Lancement et arrêt une application `curses'


Before doing anything, curses must be initialized.  This is done by
calling the @ref{1528,,initscr()} function, which will determine the
terminal type, send any required setup codes to the terminal, and
create various internal data structures.  If successful,
@code{initscr()} returns a window object representing the entire
screen; this is usually called @code{stdscr} after the name of the
corresponding C variable.

@example
import curses
stdscr = curses.initscr()
@end example

Habituellement, les applications `curses' désactivent l'écho automatique des touches à l'écran, afin de pouvoir lire les touches et ne les afficher que dans certaines circonstances. Cela nécessite d'appeler la fonction @ref{2f01,,noecho()}.

@example
curses.noecho()
@end example

Également, les applications réagissent généralement instantanément aux touches sans qu'il soit nécessaire d'appuyer sur la touche Entrée ; c'est ce qu'on appelle le mode `cbreak', par opposition au mode d'entrée habituel avec un tampon.

@example
curses.cbreak()
@end example

Les terminaux renvoient généralement les touches spéciales, telles que les touches de curseur ou les touches de navigation (Page précédente et Accueil par exemple), comme une séquence d'échappement sur plusieurs octets. Bien que vous puissiez écrire votre application pour vous attendre à de telles séquences et les traiter en conséquence, `curses' peut le faire pour vous, renvoyant une valeur spéciale telle que @ref{2f7b,,curses.KEY_LEFT}. Pour que `curses' fasse le travail, vous devez activer le mode `keypad'.

@example
stdscr.keypad(True)
@end example

Arrêter une application `curses' est beaucoup plus facile que d'en démarrer une. Appelez :

@example
curses.nocbreak()
stdscr.keypad(False)
curses.echo()
@end example

pour inverser les réglages du terminal mis en place pour `curses'. Ensuite, appelez la fonction @code{enddwin()} pour restaurer le terminal dans son mode de fonctionnement original.

@example
curses.endwin()
@end example

Un problème courant lors du débogage d'une application `curses' est de se retrouver avec un terminal sans queue ni tête lorsque l'application meurt sans restaurer le terminal à son état précédent. Avec Python, cela arrive souvent lorsque votre code est bogué et lève une exception non interceptée. Les touches ne sont plus répétées à l'écran lorsque vous les tapez, par exemple, ce qui rend l'utilisation de l'interface de commande du `shell' difficile.

En Python, vous pouvez éviter ces complications et faciliter le débogage en important la fonction @ref{a6e,,curses.wrapper()} et en l'utilisant comme suit :

@example
from curses import wrapper

def main(stdscr):
    # Clear screen
    stdscr.clear()

    # This raises ZeroDivisionError when i == 10.
    for i in range(0, 11):
        v = i-10
        stdscr.addstr(i, 0, '10 divided by @{@} is @{@}'.format(v, 10/v))

    stdscr.refresh()
    stdscr.getkey()

wrapper(main)
@end example

The @ref{a6e,,wrapper()} function takes a callable object and does the
initializations described above, also initializing colors if color
support is present.  @code{wrapper()} then runs your provided callable.
Once the callable returns, @code{wrapper()} will restore the original
state of the terminal.  The callable is called inside a
@ref{6d3,,try}...@ref{189,,except} that catches exceptions, restores
the state of the terminal, and then re-raises the exception.  Therefore
your terminal won't be left in a funny state on exception and you'll be
able to read the exception's message and traceback.

@node Fenêtres et tampons pads en anglais,Affichage de texte,Lancement et arrêt une application curses,Programmation Curses avec Python
@anchor{howto/curses windows-and-pads}@anchor{4d9b}
@subsection Fenêtres et tampons (`pads' en anglais)


Les fenêtres sont l'abstraction de base de `curses'. Un objet fenêtre représente une zone rectangulaire de l'écran qui gère des méthodes pour afficher du texte, l'effacer, permettre à l'utilisateur de saisir des chaînes, etc.

L'objet @code{stdscr} renvoyé par la fonction @ref{1528,,initscr()} est un objet fenêtre qui couvre l'écran entier. De nombreux programmes peuvent n'avoir besoin que de cette fenêtre unique, mais vous pouvez diviser l'écran en fenêtres plus petites, afin de les redessiner ou de les effacer séparément. La fonction @ref{2eff,,newwin()} crée une nouvelle fenêtre d'une taille donnée, renvoyant le nouvel objet fenêtre.

@example
begin_x = 20; begin_y = 7
height = 5; width = 40
win = curses.newwin(height, width, begin_y, begin_x)
@end example

Notez que le système de coordonnées utilisé dans `curses' est inhabituel. Les coordonnées sont toujours passées dans l'ordre `y,x' et le coin supérieur gauche d'une fenêtre a pour coordonnées (0,0). Ceci rompt la convention normale des coordonnées où la coordonnée `x' vient en premier. C'est une différence malheureuse par rapport à la plupart des autres applications informatiques, mais elle fait partie de `curses' depuis qu'il a été écrit et il est trop tard pour changer les choses maintenant.

Votre application peut déterminer la taille de l'écran en utilisant les variables @ref{1695,,curses.LINES} et @ref{1696,,curses.COLS} pour obtenir les tailles `y' et `x'. Les coordonnées licites s'étendent alors de @code{(0,0)} à @code{(curses.LINES - 1, curses.COLS - 1)}.

Quand vous appelez une méthode pour afficher ou effacer du texte, l'affichage ne le reflète pas immédiatement. Vous devez appeler la méthode @ref{2ed8,,refresh()} des objets fenêtre pour mettre à jour l'écran.

This is because curses was originally written with slow 300-baud
terminal connections in mind; with these terminals, minimizing the
time required to redraw the screen was very important.  Instead curses
accumulates changes to the screen and displays them in the most
efficient manner when you call @code{refresh()}.  For example, if your
program displays some text in a window and then clears the window,
there's no need to send the original text because they're never
visible.

In practice, explicitly telling curses to redraw a window doesn't
really complicate programming with curses much. Most programs go into a flurry
of activity, and then pause waiting for a keypress or some other action on the
part of the user.  All you have to do is to be sure that the screen has been
redrawn before pausing to wait for user input, by first calling
@code{stdscr.refresh()} or the @code{refresh()} method of some other relevant
window.

Un tampon (`pad' en anglais) est une forme spéciale de fenêtre ; il peut être plus grand que l'écran effectif et il est possible de n'afficher qu'une partie du tampon à la fois. La création d'un tampon nécessite de fournir sa hauteur et sa largeur, tandis que pour le rafraîchissement du tampon, vous devez fournir les coordonnées de la zone de l'écran où une partie du tampon sera affichée.

@example
pad = curses.newpad(100, 100)
# These loops fill the pad with letters; addch() is
# explained in the next section
for y in range(0, 99):
    for x in range(0, 99):
        pad.addch(y,x, ord('a') + (x*x+y*y) % 26)

# Displays a section of the pad in the middle of the screen.
# (0,0) : coordinate of upper-left corner of pad area to display.
# (5,5) : coordinate of upper-left corner of window area to be filled
#         with pad content.
# (20, 75) : coordinate of lower-right corner of window area to be
#          : filled with pad content.
pad.refresh( 0,0, 5,5, 20,75)
@end example

The @code{refresh()} call displays a section of the pad in the rectangle
extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper
left corner of the displayed section is coordinate (0,0) on the pad.  Beyond
that difference, pads are exactly like ordinary windows and support the same
methods.

If you have multiple windows and pads on screen there is a more
efficient way to update the screen and prevent annoying screen flicker
as each part of the screen gets updated.  @code{refresh()} actually
does two things:


@enumerate 

@item 
elle appelle la méthode @ref{2ed6,,noutrefresh()} de chaque fenêtre pour mettre à jour les données sous-jacentes qui permettent d'obtenir l'affichage voulu ;

@item 
elle appelle la fonction @ref{2ed5,,doupdate()} pour modifier l'écran physique afin de correspondre à l'état défini par les données sous-jacentes.
@end enumerate

Instead you can call @code{noutrefresh()} on a number of windows to
update the data structure, and then call @code{doupdate()} to update
the screen.

@node Affichage de texte,Entrées de l'utilisateur,Fenêtres et tampons pads en anglais,Programmation Curses avec Python
@anchor{howto/curses displaying-text}@anchor{4d9c}
@subsection Affichage de texte


From a C programmer's point of view, curses may sometimes look like a
twisty maze of functions, all subtly different.  For example,
@code{addstr()} displays a string at the current cursor location in
the @code{stdscr} window, while @code{mvaddstr()} moves to a given y,x
coordinate first before displaying the string. @code{waddstr()} is just
like @code{addstr()}, but allows specifying a window to use instead of
using @code{stdscr} by default. @code{mvwaddstr()} allows specifying both
a window and a coordinate.

Heureusement, l'interface Python masque tous ces détails. @code{stdscr} est un objet fenêtre comme les autres et les méthodes telles que @ref{2ed7,,addstr()} acceptent leurs arguments sous de multiples formes, habituellement quatre.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Forme

@tab

Description

@item

`str' ou `ch'

@tab

Affiche la chaîne `str' ou le caractère `ch' à la position actuelle

@item

`str' ou `ch', `attr'

@tab

Affiche la chaîne `str' ou le caractère `ch', en utilisant l'attribut `attr' à la position actuelle

@item

`y', `x', `str' ou `ch'

@tab

Se déplace à la position `y,x' dans la fenêtre et affiche la chaîne `str' ou le caractère `ch'

@item

`y', `x', `str' ou `ch', `attr'

@tab

Se déplace à la position `y,x' dans la fenêtre et affiche la chaîne `str' ou le caractère `ch' en utilisant l'attribut `attr'

@end multitable


Les attributs permettent de mettre en valeur du texte : gras, souligné, mode vidéo inversé ou en couleur. Nous les voyons plus en détail dans la section suivante.

The @ref{2ed7,,addstr()} method takes a Python string or
bytestring as the value to be displayed.  The contents of bytestrings
are sent to the terminal as-is.  Strings are encoded to bytes using
the value of the window's @ref{107f,,encoding} attribute; this defaults to
the default system encoding as returned by @ref{2db,,locale.getencoding()}.

Les méthodes @ref{2f1a,,addch()} prennent un caractère, soit sous la forme d'une chaîne de longueur 1, d'une chaîne d'octets de longueur 1 ou d'un entier.

Des constantes sont disponibles pour étendre les caractères ; ces constantes sont des entiers supérieurs à 255. Par exemple, @ref{2fe8,,ACS_PLMINUS} correspond au symbole +/- et @ref{2f24,,ACS_ULCORNER} correspond au coin en haut et à gauche d'une boîte (utile pour dessiner des encadrements). Vous pouvez aussi utiliser les caractères Unicode adéquats.

Windows se souvient de l'endroit où le curseur était positionné lors de la dernière opération, de manière à ce que si vous n'utilisez pas les coordonnées `y,x', l'affichage se produit au dernier endroit utilisé. Vous pouvez aussi déplacer le curseur avec la méthode @code{move(y,x)}. Comme certains terminaux affichent un curseur clignotant, vous pouvez ainsi vous assurer que celui-ci est positionné à un endroit où il ne distrait pas l'utilisateur (il peut être déroutant d'avoir un curseur qui clignote à des endroits apparemment aléatoires).

Si votre application n'a pas besoin d'un curseur clignotant, vous pouvez appeler @code{curs_set(False)} pour le rendre invisible. Par souci de compatibilité avec les anciennes versions de `curses', il existe la fonction @code{leaveok(bool)} qui est un synonyme de @ref{2ecf,,curs_set()}. Quand `bool' vaut @code{True}, la bibliothèque `curses' essaie de supprimer le curseur clignotant et vous n'avez plus besoin de vous soucier de le laisser trainer à des endroits bizarres.

@menu
* Attributs et couleurs:: 

@end menu

@node Attributs et couleurs,,,Affichage de texte
@anchor{howto/curses attributes-and-color}@anchor{4d9d}
@subsubsection Attributs et couleurs


Les caractères peuvent être affichés de différentes façons. Les lignes de statut des applications en mode texte sont généralement affichées en mode vidéo inversé ; vous pouvez avoir besoin de mettre en valeur certains mots. À ces fins, `curses' vous permet de spécifier un attribut pour chaque caractère à l'écran.

Un attribut est un entier dont chaque bit représente un attribut différent. Vous pouvez essayer d'afficher du texte avec plusieurs attributs définis simultanément mais `curses' ne garantit pas que toutes les combinaisons soient prises en compte ou que le résultat soit visuellement différent. Cela dépend de la capacité de chaque terminal utilisé, il est donc plus sage de se cantonner aux attributs les plus communément utilisés, dont la liste est fournie ci-dessous.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Attribut

@tab

Description

@item

@ref{2f67,,A_BLINK}

@tab

Texte clignotant

@item

@ref{2f68,,A_BOLD}

@tab

Texte en surbrillance ou en gras

@item

@ref{2f69,,A_DIM}

@tab

Texte en demi-ton

@item

@ref{2ecd,,A_REVERSE}

@tab

Texte en mode vidéo inversé

@item

@ref{2ecc,,A_STANDOUT}

@tab

Le meilleur mode de mis en valeur pour le texte

@item

@ref{2f6d,,A_UNDERLINE}

@tab

Texte souligné

@end multitable


Ainsi, pour mettre la ligne de statut située en haut de l'écran en mode vidéo inversé, vous pouvez coder :

@example
stdscr.addstr(0, 0, "Current mode: Typing mode",
              curses.A_REVERSE)
stdscr.refresh()
@end example

La bibliothèque `curses' gère également les couleurs pour les terminaux compatibles. Le plus répandu de ces terminaux est sûrement la console Linux, suivie par `xterm' en couleurs.

Pour utiliser les couleurs, vous devez d'abord appeler la fonction @ref{2f0b,,start_color()} juste après avoir appelé @ref{1528,,initscr()} afin d'initialiser (la fonction @ref{a6e,,curses.wrapper()} le fait automatiquement). Ensuite, la fonction @ref{2eee,,has_colors()} renvoie @code{True} si le terminal utilisé gère les couleurs (note : `curses' utilise l'orthographe américaine `color' et non pas l'orthographe britannique ou canadienne `colour' ; si vous êtes habitué à l'orthographe britannique, vous devrez vous résigner à mal l'orthographier tant que vous utilisez `curses').

La bibliothèque `curses' maintient un nombre restreint de paires de couleurs, constituées d'une couleur de texte (`foreground') et de fond (`background'). Vous pouvez obtenir la valeur des attributs correspondant à une paire de couleur avec la fonction @ref{2ecb,,color_pair()} ; cette valeur peut être combinée bit par bit (avec la fonction `OR') avec les autres attributs tels que @ref{2ecd,,A_REVERSE},mais là encore, de telles combinaisons risquent de ne pas fonctionner sur tous les terminaux.

Un exemple d'affichage d'une ligne de texte en utilisant la paire de couleur 1 :

@example
stdscr.addstr("Pretty text", curses.color_pair(1))
stdscr.refresh()
@end example

Comme indiqué auparavant, une paire de couleurs est constituée d'une couleur de texte et d'une couleur de fond. La fonction @code{init_pair(n, f, b)} change la définition de la paire de couleurs `n', en définissant la couleur de texte à `f' et la couleur de fond à `b'. La paire de couleurs 0 est codée en dur à blanc sur noir et ne peut être modifiée.

Les couleurs sont numérotées et @ref{2f0b,,start_color()} initialise 8 couleurs basiques lors de l'activation du mode en couleurs. Ce sont : 0 pour noir (`black'), 1 pour rouge (`red'), 2 pour vert (`green'), 3 pour jaune (`yellow'), 4 pour bleu `(blue'), 5 pour magenta, 6 pour cyan et 7 pour blanc (`white'). Le module @ref{2b,,curses} définit des constantes nommées pour chacune de ces couleurs : @ref{2ffa,,curses.COLOR_BLACK}, @ref{2fff,,curses.COLOR_RED} et ainsi de suite.

Testons tout ça. Pour changer la couleur 1 à rouge sur fond blanc, appelez :

@example
curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)
@end example

Quand vous modifiez une paire de couleurs, tout le texte déjà affiché qui utilise cette paire de couleur voit les nouvelles couleurs s'appliquer à lui. Vous pouvez aussi afficher du nouveau texte dans cette couleur avec :

@example
stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1))
@end example

Les terminaux « de luxe » peuvent définir les couleurs avec des valeurs `RGB'. Cela vous permet de modifier la couleur 1, habituellement rouge, en violet ou bleu voire toute autre couleur selon votre goût. Malheureusement, la console Linux ne gère pas cette fonctionnalité, je suis donc bien incapable de la tester et de vous en fournir un exemple. Vous pouvez vérifier si votre terminal la prend en charge en appelant @ref{2ec8,,can_change_color()}, qui renvoie @code{True} en cas de succès. Si vous avez la chance d'avoir un terminal aussi perfectionné, consultez les pages du manuel de votre système pour obtenir plus d'informations.

@node Entrées de l'utilisateur,Pour aller plus loin<2>,Affichage de texte,Programmation Curses avec Python
@anchor{howto/curses user-input}@anchor{4d9e}
@subsection Entrées de l'utilisateur


The C curses library offers only very simple input mechanisms. Python's
@ref{2b,,curses} module adds a basic text-input widget.  (Other libraries
such as Urwid@footnote{https://pypi.org/project/Urwid/} have more extensive collections of widgets.)

Il y a deux méthodes pour obtenir des entrées dans une fenêtre :


@itemize *

@item 
@ref{2ee0,,getch()} rafraîchit l'écran et attend que l'utilisateur appuie sur une touche, affichant cette touche si @ref{2ed9,,echo()} a été appelé auparavant. Vous pouvez en option spécifier des coordonnées où positionner le curseur avant la mise en pause ;

@item 
@ref{2f38,,getkey()} effectue la même chose mais convertit l'entier en chaîne. Les caractères individuels sont renvoyés en chaînes de longueur 1 alors que les touches spéciales (telles que les touches de fonction) renvoient des chaînes plus longues contenant le nom de la touche (tel que @code{KEY_UP} ou @code{^G}).
@end itemize

It's possible to not wait for the user using the
@ref{2f4e,,nodelay()} window method. After @code{nodelay(True)},
@code{getch()} and @code{getkey()} for the window become
non-blocking. To signal that no input is ready, @code{getch()} returns
@code{curses.ERR} (a value of -1) and @code{getkey()} raises an exception.
There's also a @ref{2ef2,,halfdelay()} function, which can be used to (in
effect) set a timer on each @code{getch()}; if no input becomes
available within a specified delay (measured in tenths of a second),
curses raises an exception.

The @code{getch()} method returns an integer; if it's between 0 and 255, it
represents the ASCII code of the key pressed.  Values greater than 255 are
special keys such as Page Up, Home, or the cursor keys. You can compare the
value returned to constants such as @ref{2f8c,,curses.KEY_PPAGE},
@ref{2f7d,,curses.KEY_HOME}, or @ref{2f7b,,curses.KEY_LEFT}.  The main loop of
your program may look something like this:

@example
while True:
    c = stdscr.getch()
    if c == ord('p'):
        PrintDocument()
    elif c == ord('q'):
        break  # Exit the while loop
    elif c == curses.KEY_HOME:
        x = y = 0
@end example

Le module @ref{2c,,curses.ascii} fournit des fonctions pour déterminer si l'entier ou la chaîne de longueur 1 passés en arguments font partie de la classe ASCII ; elles peuvent s'avérer utile pour écrire du code plus lisible dans ce genre de boucles. Il fournit également des fonctions de conversion qui prennent un entier ou une chaîne de longueur 1 en entrée et renvoient le type correspondant au nom de la fonction. Par exemple, @ref{3041,,curses.ascii.ctrl()} renvoie le caractère de contrôle correspondant à son paramètre.

Il existe aussi une méthode pour récupérer une chaîne entière, @ref{2f3b,,getstr()}. Elle n'est pas beaucoup utilisée car son utilité est limitée : les seules touches d'édition disponibles sont le retour arrière et la touche Entrée, qui termine la chaîne. Elle peut, en option, être limitée à un nombre fixé de caractères.

@example
curses.echo()            # Enable echoing of characters

# Get a 15-character string, with the cursor on the top line
s = stdscr.getstr(0,0, 15)
@end example

Le module @ref{2e,,curses.textpad} fournit un type de boîte texte qui gère des touches de fonctions à la façon d'`Emacs'. Plusieurs méthodes de la classe @ref{3003,,Textbox} gèrent l'édition avec la validation des entrées et le regroupement de l'entrée avec ou sans les espaces de début et de fin. Par exemple :

@example
import curses
from curses.textpad import Textbox, rectangle

def main(stdscr):
    stdscr.addstr(0, 0, "Enter IM message: (hit Ctrl-G to send)")

    editwin = curses.newwin(5,30, 2,1)
    rectangle(stdscr, 1,0, 1+5+1, 1+30+1)
    stdscr.refresh()

    box = Textbox(editwin)

    # Let the user edit until Ctrl-G is struck.
    box.edit()

    # Get resulting contents
    message = box.gather()
@end example

Consultez la documentation de la bibliothèque pour plus de détails sur @ref{2e,,curses.textpad}.

@node Pour aller plus loin<2>,,Entrées de l'utilisateur,Programmation Curses avec Python
@anchor{howto/curses for-more-information}@anchor{4d9f}
@subsection Pour aller plus loin


Ce guide pratique ne couvre pas certains sujets avancés, tels que la lecture du contenu de l'écran ou la capture des événements relatifs à la souris dans une instance `xterm', mais la page de la bibliothèque Python du module @ref{2b,,curses} est maintenant suffisamment complète. Nous vous encourageons à la parcourir.

If you're in doubt about the detailed behavior of the curses
functions, consult the manual pages for your curses implementation,
whether it's ncurses or a proprietary Unix vendor's.  The manual pages
will document any quirks, and provide complete lists of all the
functions, attributes, and @ref{2fd4,,ACS_*} characters available to
you.

Étant donné que l'API `curses' est si volumineuse, certaines fonctions ne sont pas prises en charge dans l'interface Python. Souvent, ce n'est pas parce qu'elles sont difficiles à implémenter, mais parce que personne n'en a eu encore besoin. De plus, Python ne prend pas encore en charge la bibliothèque de gestion des menus associée à `ncurses'. Les correctifs ajoutant cette prise en charge seraient bienvenus ; reportez-vous au guide du développeur Python@footnote{https://devguide.python.org/} pour apprendre comment soumettre des améliorations à Python.


@itemize *

@item 
Writing Programs with NCURSES@footnote{https://invisible-island.net/ncurses/ncurses-intro.html}:
a lengthy tutorial for C programmers.

@item 
La page de manuel ncurses@footnote{https://linux.die.net/man/3/ncurses}

@item 
The ncurses FAQ@footnote{https://invisible-island.net/ncurses/ncurses.faq.html}

@item 
"Use curses... don't swear"@footnote{https://www.youtube.com/watch?v=eN1eZtjLEnU} : vidéo d'une conférence lors de la PyCon 2013 sur la gestion des terminaux à l'aide de `curses' et `Urwid' (vidéo en anglais).

@item 
"Console Applications with Urwid"@footnote{https://pyvideo.org/video/1568/console-applications-with-urwid}:
video of a PyCon CA 2012 talk demonstrating some applications written using
Urwid.
@end itemize

@node Descriptor Guide,Debugging C API extensions and CPython Internals with GDB,Programmation Curses avec Python,Les HOWTOs de Python
@anchor{howto/descriptor doc}@anchor{4da0}@anchor{howto/descriptor descriptor-guide}@anchor{4da1}@anchor{howto/descriptor descriptorhowto}@anchor{14a2}
@section Descriptor Guide


@*Auteur: 
Raymond Hettinger


@*Contact: 
<python at rcn dot com>


Les @ref{1ef3,,descripteurs} permettent de personnaliser la recherche, le stockage et la suppression des attributs des objets.

Ce guide comporte quatre parties principales :


@enumerate 

@item 
l'« introduction » donne un premier aperçu, en partant d'exemples simples, puis en ajoutant une fonctionnalité à la fois. Commencez par là si vous débutez avec les descripteurs ;

@item 
la deuxième partie montre un exemple de descripteur complet et pratique. Si vous connaissez déjà les bases, commencez par là ;

@item 
la troisième partie fournit un didacticiel plus technique qui décrit de manière détaillée comment fonctionnent les descripteurs. La plupart des gens n'ont pas besoin de ce niveau de détail ;

@item 
la dernière partie contient des équivalents en pur Python des descripteurs natifs écrits en C. Lisez ceci si vous êtes curieux de savoir comment les fonctions se transforment en méthodes liées ou si vous voulez connaître l'implémentation d'outils courants comme @ref{165,,classmethod()}, @ref{40c,,staticmethod()}, @ref{192,,property()} et @ref{5c9,,__slots__}.
@end enumerate

@menu
* Introduction: Introduction<13>. 
* Exemple complet pratique:: 
* Tutoriel technique:: 
* Équivalents en Python pur:: 

@end menu

@node Introduction<13>,Exemple complet pratique,,Descriptor Guide
@anchor{howto/descriptor primer}@anchor{4da2}
@subsection Introduction


Dans cette introduction, nous commençons par l'exemple le plus simple possible, puis nous ajoutons de nouvelles fonctionnalités une par une.

@menu
* Un exemple simple ; un descripteur qui renvoie une constante: Un exemple simple un descripteur qui renvoie une constante. 
* Recherches dynamiques:: 
* Attributs gérés:: 
* Noms personnalisés:: 
* Réflexions finales:: 

@end menu

@node Un exemple simple un descripteur qui renvoie une constante,Recherches dynamiques,,Introduction<13>
@anchor{howto/descriptor simple-example-a-descriptor-that-returns-a-constant}@anchor{4da3}
@subsubsection Un exemple simple : un descripteur qui renvoie une constante


The @code{Ten} class is a descriptor whose @ref{149d,,__get__()} method always
returns the constant @code{10}:

@example
class Ten:
    def __get__(self, obj, objtype=None):
        return 10
@end example

Pour utiliser le descripteur, il doit être stocké en tant que variable de classe dans une autre classe :

@example
class A:
    x = 5                       # Regular class attribute
    y = Ten()                   # Descriptor instance
@end example

Une session interactive montre la différence entre la recherche d'attribut normale et la recherche `via' un descripteur :

@example
>>> a = A()                     # Make an instance of class A
>>> a.x                         # Normal attribute lookup
5
>>> a.y                         # Descriptor lookup
10
@end example

Dans la recherche d'attribut @code{a.x}, l'opérateur « point » trouve @code{'x': 5} dans le dictionnaire de classe. Dans la recherche @code{a.y}, l'opérateur « point » trouve une instance de descripteur, reconnue par sa méthode @code{__get__}. L'appel de cette méthode renvoie @code{10}.

Notez que la valeur @code{10} n'est stockée ni dans le dictionnaire de classe ni dans le dictionnaire d'instance. Non, la valeur @code{10} est calculée à la demande.

Cet exemple montre comment fonctionne un descripteur simple, mais il n'est pas très utile. Pour récupérer des constantes, une recherche d'attribut normale est préférable.

Dans la section suivante, nous allons créer quelque chose de plus utile, une recherche dynamique.

@node Recherches dynamiques,Attributs gérés,Un exemple simple un descripteur qui renvoie une constante,Introduction<13>
@anchor{howto/descriptor dynamic-lookups}@anchor{4da4}
@subsubsection Recherches dynamiques


Les descripteurs intéressants exécutent généralement des calculs au lieu de renvoyer des constantes :

@example
import os

class DirectorySize:

    def __get__(self, obj, objtype=None):
        return len(os.listdir(obj.dirname))

class Directory:

    size = DirectorySize()              # Descriptor instance

    def __init__(self, dirname):
        self.dirname = dirname          # Regular instance attribute
@end example

Une session interactive montre que la recherche est dynamique — elle calcule des réponses différentes, mises à jour à chaque fois :

@example
>>> s = Directory('songs')
>>> g = Directory('games')
>>> s.size                              # The songs directory has twenty files
20
>>> g.size                              # The games directory has three files
3
>>> os.remove('games/chess')            # Delete a game
>>> g.size                              # File count is automatically updated
2
@end example

Besides showing how descriptors can run computations, this example also
reveals the purpose of the parameters to @ref{149d,,__get__()}.  The `self'
parameter is `size', an instance of `DirectorySize'.  The `obj' parameter is
either `g' or `s', an instance of `Directory'.  It is the `obj' parameter that
lets the @ref{149d,,__get__()} method learn the target directory.  The `objtype'
parameter is the class `Directory'.

@node Attributs gérés,Noms personnalisés,Recherches dynamiques,Introduction<13>
@anchor{howto/descriptor managed-attributes}@anchor{4da5}
@subsubsection Attributs gérés


A popular use for descriptors is managing access to instance data.  The
descriptor is assigned to a public attribute in the class dictionary while the
actual data is stored as a private attribute in the instance dictionary.  The
descriptor's @ref{149d,,__get__()} and @ref{1eec,,__set__()} methods are triggered when
the public attribute is accessed.

Dans l'exemple qui suit, `age' est l'attribut public et `_age' est l'attribut privé. Lors de l'accès à l'attribut public, le descripteur journalise la recherche ou la mise à jour :

@example
import logging

logging.basicConfig(level=logging.INFO)

class LoggedAgeAccess:

    def __get__(self, obj, objtype=None):
        value = obj._age
        logging.info('Accessing %r giving %r', 'age', value)
        return value

    def __set__(self, obj, value):
        logging.info('Updating %r to %r', 'age', value)
        obj._age = value

class Person:

    age = LoggedAgeAccess()             # Descriptor instance

    def __init__(self, name, age):
        self.name = name                # Regular instance attribute
        self.age = age                  # Calls __set__()

    def birthday(self):
        self.age += 1                   # Calls both __get__() and __set__()
@end example

Une session interactive montre que tous les accès à l'attribut géré `age' sont consignés, mais que rien n'est journalisé pour l'attribut normal `name' :

@c import logging, sys
@c logging.basicConfig(level=logging.INFO, stream=sys.stdout, force=True)

@example
>>> mary = Person('Mary M', 30)         # The initial age update is logged
INFO:root:Updating 'age' to 30
>>> dave = Person('David D', 40)
INFO:root:Updating 'age' to 40

>>> vars(mary)                          # The actual data is in a private attribute
@{'name': 'Mary M', '_age': 30@}
>>> vars(dave)
@{'name': 'David D', '_age': 40@}

>>> mary.age                            # Access the data and log the lookup
INFO:root:Accessing 'age' giving 30
30
>>> mary.birthday()                     # Updates are logged as well
INFO:root:Accessing 'age' giving 30
INFO:root:Updating 'age' to 31

>>> dave.name                           # Regular attribute lookup isn't logged
'David D'
>>> dave.age                            # Only the managed attribute is logged
INFO:root:Accessing 'age' giving 40
40
@end example

Un problème majeur avec cet exemple est que le nom privé `_age' est écrit en dur dans la classe `LoggedAgeAccess'. Cela signifie que chaque instance ne peut avoir qu'un seul attribut journalisé et que son nom est immuable. Dans l'exemple suivant, nous allons résoudre ce problème.

@node Noms personnalisés,Réflexions finales,Attributs gérés,Introduction<13>
@anchor{howto/descriptor customized-names}@anchor{4da6}
@subsubsection Noms personnalisés


Lorsqu'une classe utilise des descripteurs, elle peut informer chaque descripteur du nom de variable utilisé.

In this example, the @code{Person} class has two descriptor instances,
`name' and `age'.  When the @code{Person} class is defined, it makes a
callback to @ref{c3c,,__set_name__()} in `LoggedAccess' so that the field names can
be recorded, giving each descriptor its own `public_name' and `private_name':

@example
import logging

logging.basicConfig(level=logging.INFO)

class LoggedAccess:

    def __set_name__(self, owner, name):
        self.public_name = name
        self.private_name = '_' + name

    def __get__(self, obj, objtype=None):
        value = getattr(obj, self.private_name)
        logging.info('Accessing %r giving %r', self.public_name, value)
        return value

    def __set__(self, obj, value):
        logging.info('Updating %r to %r', self.public_name, value)
        setattr(obj, self.private_name, value)

class Person:

    name = LoggedAccess()                # First descriptor instance
    age = LoggedAccess()                 # Second descriptor instance

    def __init__(self, name, age):
        self.name = name                 # Calls the first descriptor
        self.age = age                   # Calls the second descriptor

    def birthday(self):
        self.age += 1
@end example

An interactive session shows that the @code{Person} class has called
@ref{c3c,,__set_name__()} so that the field names would be recorded.  Here
we call @ref{19d0,,vars()} to look up the descriptor without triggering it:

@example
>>> vars(vars(Person)['name'])
@{'public_name': 'name', 'private_name': '_name'@}
>>> vars(vars(Person)['age'])
@{'public_name': 'age', 'private_name': '_age'@}
@end example

La nouvelle classe enregistre désormais l'accès à la fois à `name' et `age' :

@c import logging, sys
@c logging.basicConfig(level=logging.INFO, stream=sys.stdout, force=True)

@example
>>> pete = Person('Peter P', 10)
INFO:root:Updating 'name' to 'Peter P'
INFO:root:Updating 'age' to 10
>>> kate = Person('Catherine C', 20)
INFO:root:Updating 'name' to 'Catherine C'
INFO:root:Updating 'age' to 20
@end example

Les deux instances de `Person' ne contiennent que les noms privés :

@example
>>> vars(pete)
@{'_name': 'Peter P', '_age': 10@}
>>> vars(kate)
@{'_name': 'Catherine C', '_age': 20@}
@end example

@node Réflexions finales,,Noms personnalisés,Introduction<13>
@anchor{howto/descriptor closing-thoughts}@anchor{4da7}
@subsubsection Réflexions finales


A @ref{1ef3,,descriptor} is what we call any object that defines @ref{149d,,__get__()},
@ref{1eec,,__set__()}, or @ref{1591,,__delete__()}.

Optionally, descriptors can have a @ref{c3c,,__set_name__()} method.  This is only
used in cases where a descriptor needs to know either the class where it was
created or the name of class variable it was assigned to.  (This method, if
present, is called even if the class is not a descriptor.)

Les descripteurs sont invoqués par l'opérateur « point » lors de la recherche d'attribut. Si on accède indirectement au descripteur avec @code{vars(some_class)[descriptor_name]}, l'instance du descripteur est renvoyée sans l'invoquer.

Les descripteurs ne fonctionnent que lorsqu'ils sont utilisés comme variables de classe. Lorsqu'ils sont placés dans des instances, ils n'ont aucun effet.

La principale raison d'être des descripteurs est de fournir un point d'entrée permettant aux objets stockés dans des variables de classe de contrôler ce qui se passe lors de la recherche d'attributs.

Traditionnellement, la classe appelante contrôle ce qui se passe pendant la recherche. Les descripteurs inversent cette relation et permettent aux données recherchées d'avoir leur mot à dire.

Les descripteurs sont utilisés partout dans le langage. C'est ainsi que les fonctions se transforment en méthodes liées. Les outils courants tels que @ref{165,,classmethod()}, @ref{40c,,staticmethod()}, @ref{192,,property()} et @ref{52c,,functools.cached_property()} sont tous implémentés en tant que descripteurs.

@node Exemple complet pratique,Tutoriel technique,Introduction<13>,Descriptor Guide
@anchor{howto/descriptor complete-practical-example}@anchor{4da8}
@subsection Exemple complet pratique


Dans cet exemple, nous créons un outil pratique et puissant pour localiser les bogues de corruption de données notoirement difficiles à trouver.

@menu
* Classe « validateur »:: 
* Validateurs personnalisés:: 
* Application pratique:: 

@end menu

@node Classe « validateur »,Validateurs personnalisés,,Exemple complet pratique
@anchor{howto/descriptor validator-class}@anchor{4da9}
@subsubsection Classe « validateur »


Un validateur est un descripteur pour l'accès aux attributs gérés. Avant de stocker des données, il vérifie que la nouvelle valeur respecte différentes restrictions de type et de plage. Si ces restrictions ne sont pas respectées, il lève une exception pour empêcher la corruption des données à la source.

This @code{Validator} class is both an @ref{1193,,abstract base class} and a
managed attribute descriptor:

@example
from abc import ABC, abstractmethod

class Validator(ABC):

    def __set_name__(self, owner, name):
        self.private_name = '_' + name

    def __get__(self, obj, objtype=None):
        return getattr(obj, self.private_name)

    def __set__(self, obj, value):
        self.validate(value)
        setattr(obj, self.private_name, value)

    @@abstractmethod
    def validate(self, value):
        pass
@end example

Custom validators need to inherit from @code{Validator} and must supply a
@code{validate()} method to test various restrictions as needed.

@node Validateurs personnalisés,Application pratique,Classe « validateur »,Exemple complet pratique
@anchor{howto/descriptor custom-validators}@anchor{4daa}
@subsubsection Validateurs personnalisés


Voici trois utilitaires concrets de validation de données :


@enumerate 

@item 
@code{OneOf} verifies that a value is one of a restricted set of options.

@item 
@code{Number} verifies that a value is either an @ref{254,,int} or
@ref{2eb,,float}.  Optionally, it verifies that a value is between a given
minimum or maximum.

@item 
@code{String} verifies that a value is a @ref{435,,str}.  Optionally, it
validates a given minimum or maximum length.  It can validate a
user-defined predicate@footnote{https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)} as well.
@end enumerate

@example
class OneOf(Validator):

    def __init__(self, *options):
        self.options = set(options)

    def validate(self, value):
        if value not in self.options:
            raise ValueError(
                f'Expected @{value!r@} to be one of @{self.options!r@}'
            )

class Number(Validator):

    def __init__(self, minvalue=None, maxvalue=None):
        self.minvalue = minvalue
        self.maxvalue = maxvalue

    def validate(self, value):
        if not isinstance(value, (int, float)):
            raise TypeError(f'Expected @{value!r@} to be an int or float')
        if self.minvalue is not None and value < self.minvalue:
            raise ValueError(
                f'Expected @{value!r@} to be at least @{self.minvalue!r@}'
            )
        if self.maxvalue is not None and value > self.maxvalue:
            raise ValueError(
                f'Expected @{value!r@} to be no more than @{self.maxvalue!r@}'
            )

class String(Validator):

    def __init__(self, minsize=None, maxsize=None, predicate=None):
        self.minsize = minsize
        self.maxsize = maxsize
        self.predicate = predicate

    def validate(self, value):
        if not isinstance(value, str):
            raise TypeError(f'Expected @{value!r@} to be an str')
        if self.minsize is not None and len(value) < self.minsize:
            raise ValueError(
                f'Expected @{value!r@} to be no smaller than @{self.minsize!r@}'
            )
        if self.maxsize is not None and len(value) > self.maxsize:
            raise ValueError(
                f'Expected @{value!r@} to be no bigger than @{self.maxsize!r@}'
            )
        if self.predicate is not None and not self.predicate(value):
            raise ValueError(
                f'Expected @{self.predicate@} to be true for @{value!r@}'
            )
@end example

@node Application pratique,,Validateurs personnalisés,Exemple complet pratique
@anchor{howto/descriptor practical-application}@anchor{4dab}
@subsubsection Application pratique


Voici comment les validateurs de données peuvent être utilisés par une classe réelle :

@example
class Component:

    name = String(minsize=3, maxsize=10, predicate=str.isupper)
    kind = OneOf('wood', 'metal', 'plastic')
    quantity = Number(minvalue=0)

    def __init__(self, name, kind, quantity):
        self.name = name
        self.kind = kind
        self.quantity = quantity
@end example

Les descripteurs empêchent la création d'instances non valides :

@example
>>> Component('Widget', 'metal', 5)      # Blocked: 'Widget' is not all uppercase
Traceback (most recent call last):
    ...
ValueError: Expected <method 'isupper' of 'str' objects> to be true for 'Widget'

>>> Component('WIDGET', 'metle', 5)      # Blocked: 'metle' is misspelled
Traceback (most recent call last):
    ...
ValueError: Expected 'metle' to be one of @{'metal', 'plastic', 'wood'@}

>>> Component('WIDGET', 'metal', -5)     # Blocked: -5 is negative
Traceback (most recent call last):
    ...
ValueError: Expected -5 to be at least 0

>>> Component('WIDGET', 'metal', 'V')    # Blocked: 'V' isn't a number
Traceback (most recent call last):
    ...
TypeError: Expected 'V' to be an int or float

>>> c = Component('WIDGET', 'metal', 5)  # Allowed:  The inputs are valid
@end example

@node Tutoriel technique,Équivalents en Python pur,Exemple complet pratique,Descriptor Guide
@anchor{howto/descriptor technical-tutorial}@anchor{4dac}
@subsection Tutoriel technique


Ce qui suit est un tutoriel plus technique relatif aux mécanismes et détails de fonctionnement des descripteurs.

@menu
* Résumé:: 
* Définition et introduction:: 
* Protocole descripteur:: 
* Présentation de l'appel de descripteur:: 
* Appel depuis une instance:: 
* Appel depuis une classe:: 
* Appel depuis super:: 
* Résumé de la logique d'appel:: 
* Notification automatique des noms:: 
* Exemple d'ORM:: 

@end menu

@node Résumé,Définition et introduction,,Tutoriel technique
@anchor{howto/descriptor abstract}@anchor{4dad}
@subsubsection Résumé


Ce tutoriel définit des descripteurs, résume le protocole et montre comment les descripteurs sont appelés. Il fournit un exemple montrant comment fonctionnent les correspondances relationnelles entre objets.

L'apprentissage des descripteurs permet non seulement d'accéder à un ensemble d'outils plus vaste, mais aussi de mieux comprendre le fonctionnement de Python.

@node Définition et introduction,Protocole descripteur,Résumé,Tutoriel technique
@anchor{howto/descriptor definition-and-introduction}@anchor{4dae}
@subsubsection Définition et introduction


In general, a descriptor is an attribute value that has one of the methods in
the descriptor protocol.  Those methods are @ref{149d,,__get__()}, @ref{1eec,,__set__()},
and @ref{1591,,__delete__()}.  If any of those methods are defined for an
attribute, it is said to be a @ref{1ef3,,descriptor}.

Le comportement par défaut pour l'accès aux attributs consiste à obtenir, définir ou supprimer l'attribut dans le dictionnaire d'un objet. Par exemple, pour chercher @code{a.x} Python commence par chercher @code{a.__dict__['x']}, puis @code{type(a).__dict__['x']}, et continue la recherche en utilisant la MRO (l'ordre de résolution des méthodes) de @code{type(a)}. Si la valeur recherchée est un objet définissant l'une des méthodes de descripteur, Python remplace le comportement par défaut par un appel à la méthode du descripteur. Le moment où cela se produit dans la chaîne de recherche dépend des méthodes définies par le descripteur.

Descriptors are a powerful, general purpose protocol.  They are the mechanism
behind properties, methods, static methods, class methods, and
@ref{4c5,,super()}.  They are used throughout Python itself.  Descriptors
simplify the underlying C code and offer a flexible set of new tools for
everyday Python programs.

@node Protocole descripteur,Présentation de l'appel de descripteur,Définition et introduction,Tutoriel technique
@anchor{howto/descriptor descriptor-protocol}@anchor{4daf}
@subsubsection Protocole descripteur


@code{descr.__get__(self, obj, type=None)}

@code{descr.__set__(self, obj, value)}

@code{descr.__delete__(self, obj)}

C'est tout ce qu'il y a à faire. Définissez n'importe laquelle de ces méthodes et un objet est considéré comme un descripteur ; il peut alors remplacer le comportement par défaut lorsqu'il est recherché en tant qu'attribut.

If an object defines @ref{1eec,,__set__()} or @ref{1591,,__delete__()}, it is considered
a data descriptor.  Descriptors that only define @ref{149d,,__get__()} are called
non-data descriptors (they are often used for methods but other uses are
possible).

Les descripteurs de données et les descripteurs hors-données diffèrent dans la façon dont les changements de comportement sont calculés en ce qui concerne les entrées du dictionnaire d'une instance. Si le dictionnaire d'une instance comporte une entrée portant le même nom qu'un descripteur de données, le descripteur de données est prioritaire. Si le dictionnaire d'une instance comporte une entrée portant le même nom qu'un descripteur hors-données, l'entrée du dictionnaire a la priorité.

To make a read-only data descriptor, define both @ref{149d,,__get__()} and
@ref{1eec,,__set__()} with the @ref{1eec,,__set__()} raising an @ref{343,,AttributeError} when
called.  Defining the @ref{1eec,,__set__()} method with an exception raising
placeholder is enough to make it a data descriptor.

@node Présentation de l'appel de descripteur,Appel depuis une instance,Protocole descripteur,Tutoriel technique
@anchor{howto/descriptor overview-of-descriptor-invocation}@anchor{4db0}
@subsubsection Présentation de l'appel de descripteur


Un descripteur peut être appelé directement par @code{desc.__get__(obj)} ou @code{desc.__get__(None, cls)}.

Mais il est plus courant qu'un descripteur soit invoqué automatiquement à partir d'un accès à un attribut.

The expression @code{obj.x} looks up the attribute @code{x} in the chain of
namespaces for @code{obj}.  If the search finds a descriptor outside of the
instance @ref{546,,__dict__}, its @ref{149d,,__get__()} method is
invoked according to the precedence rules listed below.

Les détails de l'appel varient selon que @code{obj} est un objet, une classe ou une instance de `super'.

@node Appel depuis une instance,Appel depuis une classe,Présentation de l'appel de descripteur,Tutoriel technique
@anchor{howto/descriptor invocation-from-an-instance}@anchor{4db1}
@subsubsection Appel depuis une instance


Instance lookup scans through a chain of namespaces giving data descriptors
the highest priority, followed by instance variables, then non-data
descriptors, then class variables, and lastly @ref{4bc,,__getattr__()} if it is
provided.

Si un descripteur est trouvé pour @code{a.x}, alors il est appelé par @code{desc.__get__(a, type(a))}.

La logique d'une recherche « après un point » se trouve dans @ref{bc0,,object.__getattribute__()}. Voici un équivalent en Python pur :

@example
def find_name_in_mro(cls, name, default):
    "Emulate _PyType_Lookup() in Objects/typeobject.c"
    for base in cls.__mro__:
        if name in vars(base):
            return vars(base)[name]
    return default

def object_getattribute(obj, name):
    "Emulate PyObject_GenericGetAttr() in Objects/object.c"
    null = object()
    objtype = type(obj)
    cls_var = find_name_in_mro(objtype, name, null)
    descr_get = getattr(type(cls_var), '__get__', null)
    if descr_get is not null:
        if (hasattr(type(cls_var), '__set__')
            or hasattr(type(cls_var), '__delete__')):
            return descr_get(cls_var, obj, objtype)     # data descriptor
    if hasattr(obj, '__dict__') and name in vars(obj):
        return vars(obj)[name]                          # instance variable
    if descr_get is not null:
        return descr_get(cls_var, obj, objtype)         # non-data descriptor
    if cls_var is not null:
        return cls_var                                  # class variable
    raise AttributeError(name)
@end example

@c # Test the fidelity of object_getattribute() by comparing it with the
@c # normal object.__getattribute__().  The former will be accessed by
@c # square brackets and the latter by the dot operator.
@c 
@c class Object:
@c 
@c     def __getitem__(obj, name):
@c         try:
@c             return object_getattribute(obj, name)
@c         except AttributeError:
@c             if not hasattr(type(obj), '__getattr__'):
@c                 raise
@c         return type(obj).__getattr__(obj, name)             # __getattr__
@c 
@c class DualOperator(Object):
@c 
@c     x = 10
@c 
@c     def __init__(self, z):
@c         self.z = z
@c 
@c     @property
@c     def p2(self):
@c         return 2 * self.x
@c 
@c     @property
@c     def p3(self):
@c         return 3 * self.x
@c 
@c     def m5(self, y):
@c         return 5 * y
@c 
@c     def m7(self, y):
@c         return 7 * y
@c 
@c     def __getattr__(self, name):
@c         return ('getattr_hook', self, name)
@c 
@c class DualOperatorWithSlots:
@c 
@c     __getitem__ = Object.__getitem__
@c 
@c     __slots__ = ['z']
@c 
@c     x = 15
@c 
@c     def __init__(self, z):
@c         self.z = z
@c 
@c     @property
@c     def p2(self):
@c         return 2 * self.x
@c 
@c     def m5(self, y):
@c         return 5 * y
@c 
@c     def __getattr__(self, name):
@c         return ('getattr_hook', self, name)
@c 
@c class D1:
@c     def __get__(self, obj, objtype=None):
@c         return type(self), obj, objtype
@c 
@c class U1:
@c     x = D1()
@c 
@c class U2(U1):
@c     pass

@c >>> a = DualOperator(11)
@c >>> vars(a).update(p3 = '_p3', m7 = '_m7')
@c >>> a.x == a['x'] == 10
@c True
@c >>> a.z == a['z'] == 11
@c True
@c >>> a.p2 == a['p2'] == 20
@c True
@c >>> a.p3 == a['p3'] == 30
@c True
@c >>> a.m5(100) == a.m5(100) == 500
@c True
@c >>> a.m7 == a['m7'] == '_m7'
@c True
@c >>> a.g == a['g'] == ('getattr_hook', a, 'g')
@c True
@c 
@c >>> b = DualOperatorWithSlots(22)
@c >>> b.x == b['x'] == 15
@c True
@c >>> b.z == b['z'] == 22
@c True
@c >>> b.p2 == b['p2'] == 30
@c True
@c >>> b.m5(200) == b['m5'](200) == 1000
@c True
@c >>> b.g == b['g'] == ('getattr_hook', b, 'g')
@c True
@c 
@c >>> u2 = U2()
@c >>> object_getattribute(u2, 'x') == u2.x == (D1, u2, U2)
@c True

Note, there is no @ref{4bc,,__getattr__()} hook in the @ref{bc0,,__getattribute__()}
code.  That is why calling @ref{bc0,,__getattribute__()} directly or with
@code{super().__getattribute__} will bypass @ref{4bc,,__getattr__()} entirely.

Instead, it is the dot operator and the @ref{bbf,,getattr()} function that are
responsible for invoking @ref{4bc,,__getattr__()} whenever @ref{bc0,,__getattribute__()}
raises an @ref{343,,AttributeError}.  Their logic is encapsulated in a helper
function:

@example
def getattr_hook(obj, name):
    "Emulate slot_tp_getattr_hook() in Objects/typeobject.c"
    try:
        return obj.__getattribute__(name)
    except AttributeError:
        if not hasattr(type(obj), '__getattr__'):
            raise
    return type(obj).__getattr__(obj, name)             # __getattr__
@end example

@c >>> class ClassWithGetAttr:
@c ...     x = 123
@c ...     def __getattr__(self, attr):
@c ...         return attr.upper()
@c ...
@c >>> cw = ClassWithGetAttr()
@c >>> cw.y = 456
@c >>> getattr_hook(cw, 'x')
@c 123
@c >>> getattr_hook(cw, 'y')
@c 456
@c >>> getattr_hook(cw, 'z')
@c 'Z'
@c 
@c >>> class ClassWithoutGetAttr:
@c ...     x = 123
@c ...
@c >>> cwo = ClassWithoutGetAttr()
@c >>> cwo.y = 456
@c >>> getattr_hook(cwo, 'x')
@c 123
@c >>> getattr_hook(cwo, 'y')
@c 456
@c >>> getattr_hook(cwo, 'z')
@c Traceback (most recent call last):
@c     ...
@c AttributeError: 'ClassWithoutGetAttr' object has no attribute 'z'

@node Appel depuis une classe,Appel depuis super,Appel depuis une instance,Tutoriel technique
@anchor{howto/descriptor invocation-from-a-class}@anchor{4db2}
@subsubsection Appel depuis une classe


The logic for a dotted lookup such as @code{A.x} is in
@code{type.__getattribute__()}.  The steps are similar to those for
@code{object.__getattribute__()} but the instance dictionary lookup is replaced
by a search through the class's @ref{2109,,method resolution order}.

Si un descripteur est trouvé, il est appelé par @code{desc.__get__(None, A)}.

The full C implementation can be found in @code{type_getattro()} and
@code{_PyType_Lookup()} in Objects/typeobject.c@footnote{https://github.com/python/cpython/tree/3.13/Objects/typeobject.c}.

@node Appel depuis super,Résumé de la logique d'appel,Appel depuis une classe,Tutoriel technique
@anchor{howto/descriptor invocation-from-super}@anchor{4db3}
@subsubsection Appel depuis super


The logic for super's dotted lookup is in the @ref{bc0,,__getattribute__()} method for
object returned by @ref{4c5,,super()}.

La recherche d'attribut @code{super(A, obj).m} recherche dans @code{obj.__class__.__mro__} la classe @code{B} qui suit immédiatement A, et renvoie @code{B.__dict__['m'].__get__(obj, A)}. Si ce n'est pas un descripteur, @code{m} est renvoyé inchangé.

The full C implementation can be found in @code{super_getattro()} in
Objects/typeobject.c@footnote{https://github.com/python/cpython/tree/3.13/Objects/typeobject.c}.  A pure Python equivalent can be found in
Guido's Tutorial@footnote{https://www.python.org/download/releases/2.2.3/descrintro/#cooperation}.

@node Résumé de la logique d'appel,Notification automatique des noms,Appel depuis super,Tutoriel technique
@anchor{howto/descriptor summary-of-invocation-logic}@anchor{4db4}
@subsubsection Résumé de la logique d'appel


The mechanism for descriptors is embedded in the @ref{bc0,,__getattribute__()}
methods for @ref{a7a,,object}, @ref{d36,,type}, and @ref{4c5,,super()}.

Les points importants à retenir sont :


@itemize *

@item 
Descriptors are invoked by the @ref{bc0,,__getattribute__()} method.

@item 
les classes héritent ce mécanisme de @ref{a7a,,object}, @ref{d36,,type} ou @ref{4c5,,super()} ;

@item 
Overriding @ref{bc0,,__getattribute__()} prevents automatic descriptor calls
because all the descriptor logic is in that method.

@item 
@code{object.__getattribute__()} and @code{type.__getattribute__()} make
different calls to @ref{149d,,__get__()}.  The first includes the instance and may
include the class.  The second puts in @code{None} for the instance and always
includes the class.

@item 
les descripteurs de données sont toujours prioritaires sur les dictionnaires d'instances.

@item 
les descripteurs hors-données peuvent céder la priorité aux dictionnaires d'instance.
@end itemize

@node Notification automatique des noms,Exemple d'ORM,Résumé de la logique d'appel,Tutoriel technique
@anchor{howto/descriptor automatic-name-notification}@anchor{4db5}
@subsubsection Notification automatique des noms


Sometimes it is desirable for a descriptor to know what class variable name it
was assigned to.  When a new class is created, the @ref{d36,,type} metaclass
scans the dictionary of the new class.  If any of the entries are descriptors
and if they define @ref{c3c,,__set_name__()}, that method is called with two
arguments.  The `owner' is the class where the descriptor is used, and the
`name' is the class variable the descriptor was assigned to.

The implementation details are in @code{type_new()} and
@code{set_names()} in Objects/typeobject.c@footnote{https://github.com/python/cpython/tree/3.13/Objects/typeobject.c}.

Since the update logic is in @code{type.__new__()}, notifications only take
place at the time of class creation.  If descriptors are added to the class
afterwards, @ref{c3c,,__set_name__()} will need to be called manually.

@node Exemple d'ORM,,Notification automatique des noms,Tutoriel technique
@anchor{howto/descriptor orm-example}@anchor{4db6}
@subsubsection Exemple d'ORM


Le code suivant est une ossature simplifiée montrant comment les descripteurs de données peuvent être utilisés pour implémenter une correspondance objet-relationnel@footnote{https://fr.wikipedia.org/wiki/Mapping_objet-relationnel}.

L'idée essentielle est que les données sont stockées dans une base de données externe. Les instances Python ne contiennent que les clés des tables de la base de données. Les descripteurs s'occupent des recherches et des mises à jour :

@example
class Field:

    def __set_name__(self, owner, name):
        self.fetch = f'SELECT @{name@} FROM @{owner.table@} WHERE @{owner.key@}=?;'
        self.store = f'UPDATE @{owner.table@} SET @{name@}=? WHERE @{owner.key@}=?;'

    def __get__(self, obj, objtype=None):
        return conn.execute(self.fetch, [obj.key]).fetchone()[0]

    def __set__(self, obj, value):
        conn.execute(self.store, [value, obj.key])
        conn.commit()
@end example

We can use the @code{Field} class to define models@footnote{https://en.wikipedia.org/wiki/Database_model} that describe the schema for
each table in a database:

@example
class Movie:
    table = 'Movies'                    # Table name
    key = 'title'                       # Primary key
    director = Field()
    year = Field()

    def __init__(self, key):
        self.key = key

class Song:
    table = 'Music'
    key = 'title'
    artist = Field()
    year = Field()
    genre = Field()

    def __init__(self, key):
        self.key = key
@end example

Pour utiliser les modèles, connectons-nous d'abord à la base de données :

@example
>>> import sqlite3
>>> conn = sqlite3.connect('entertainment.db')
@end example

Une session interactive montre comment les données sont extraites de la base de données et comment elles peuvent être mises à jour :

@c song_data = [
@c     ('Country Roads', 'John Denver', 1972),
@c     ('Me and Bobby McGee', 'Janice Joplin', 1971),
@c     ('Coal Miners Daughter', 'Loretta Lynn', 1970),
@c ]
@c 
@c movie_data = [
@c     ('Star Wars', 'George Lucas', 1977),
@c     ('Jaws', 'Steven Spielberg', 1975),
@c     ('Aliens', 'James Cameron', 1986),
@c ]
@c 
@c import sqlite3
@c 
@c conn = sqlite3.connect(':memory:')
@c conn.execute('CREATE TABLE Music (title text, artist text, year integer);')
@c conn.execute('CREATE INDEX MusicNdx ON Music (title);')
@c conn.executemany('INSERT INTO Music VALUES (?, ?, ?);', song_data)
@c conn.execute('CREATE TABLE Movies (title text, director text, year integer);')
@c conn.execute('CREATE INDEX MovieNdx ON Music (title);')
@c conn.executemany('INSERT INTO Movies VALUES (?, ?, ?);', movie_data)
@c conn.commit()

@example
>>> Movie('Star Wars').director
'George Lucas'
>>> jaws = Movie('Jaws')
>>> f'Released in @{jaws.year@} by @{jaws.director@}'
'Released in 1975 by Steven Spielberg'

>>> Song('Country Roads').artist
'John Denver'

>>> Movie('Star Wars').director = 'J.J. Abrams'
>>> Movie('Star Wars').director
'J.J. Abrams'
@end example

@c conn.close()

@node Équivalents en Python pur,,Tutoriel technique,Descriptor Guide
@anchor{howto/descriptor pure-python-equivalents}@anchor{4db7}
@subsection Équivalents en Python pur


Le protocole descripteur est simple et offre des possibilités très intéressantes. Plusieurs cas d'utilisation sont si courants qu'ils ont été regroupés dans des outils intégrés. Les propriétés, les méthodes liées, les méthodes statiques et les méthodes de classe sont toutes basées sur le protocole descripteur.

@menu
* Propriétés:: 
* Fonctions et méthodes:: 
* Types de méthodes:: 
* Méthodes statiques:: 
* Méthodes de classe:: 
* Objets membres et __slots__:: 

@end menu

@node Propriétés,Fonctions et méthodes,,Équivalents en Python pur
@anchor{howto/descriptor properties}@anchor{4db8}
@subsubsection Propriétés


Appeler @ref{192,,property()} construit de façon succincte un descripteur de données qui déclenche un appel de fonction lors de l'accès à un attribut. Sa signature est :

@example
property(fget=None, fset=None, fdel=None, doc=None) -> property
@end example

La documentation montre une utilisation caractéristique pour définir un attribut géré @code{x} :

@example
class C:
    def getx(self): return self.__x
    def setx(self, value): self.__x = value
    def delx(self): del self.__x
    x = property(getx, setx, delx, "I'm the 'x' property.")
@end example

@c >>> C.x.__doc__
@c "I'm the 'x' property."
@c >>> c.x = 2.71828
@c >>> c.x
@c 2.71828
@c >>> del c.x
@c >>> c.x
@c Traceback (most recent call last):
@c   ...
@c AttributeError: 'C' object has no attribute '_C__x'

To see how @ref{192,,property()} is implemented in terms of the descriptor protocol,
here is a pure Python equivalent that implements most of the core functionality:

@example
class Property:
    "Emulate PyProperty_Type() in Objects/descrobject.c"

    def __init__(self, fget=None, fset=None, fdel=None, doc=None):
        self.fget = fget
        self.fset = fset
        self.fdel = fdel
        if doc is None and fget is not None:
            doc = fget.__doc__
        self.__doc__ = doc

    def __set_name__(self, owner, name):
        self.__name__ = name

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        if self.fget is None:
            raise AttributeError
        return self.fget(obj)

    def __set__(self, obj, value):
        if self.fset is None:
            raise AttributeError
        self.fset(obj, value)

    def __delete__(self, obj):
        if self.fdel is None:
            raise AttributeError
        self.fdel(obj)

    def getter(self, fget):
        return type(self)(fget, self.fset, self.fdel, self.__doc__)

    def setter(self, fset):
        return type(self)(self.fget, fset, self.fdel, self.__doc__)

    def deleter(self, fdel):
        return type(self)(self.fget, self.fset, fdel, self.__doc__)
@end example

@c # Verify the Property() emulation
@c 
@c class CC:
@c     def getx(self):
@c         return self.__x
@c     def setx(self, value):
@c         self.__x = value
@c     def delx(self):
@c         del self.__x
@c     x = Property(getx, setx, delx, "I'm the 'x' property.")
@c     no_getter = Property(None, setx, delx, "I'm the 'x' property.")
@c     no_setter = Property(getx, None, delx, "I'm the 'x' property.")
@c     no_deleter = Property(getx, setx, None, "I'm the 'x' property.")
@c     no_doc = Property(getx, setx, delx, None)
@c 
@c 
@c # Now do it again but use the decorator style
@c 
@c class CCC:
@c     @Property
@c     def x(self):
@c         return self.__x
@c     @x.setter
@c     def x(self, value):
@c         self.__x = value
@c     @x.deleter
@c     def x(self):
@c         del self.__x

@c >>> cc = CC()
@c >>> hasattr(cc, 'x')
@c False
@c >>> cc.x = 33
@c >>> cc.x
@c 33
@c >>> del cc.x
@c >>> hasattr(cc, 'x')
@c False
@c 
@c >>> ccc = CCC()
@c >>> hasattr(ccc, 'x')
@c False
@c >>> ccc.x = 333
@c >>> ccc.x == 333
@c True
@c >>> del ccc.x
@c >>> hasattr(ccc, 'x')
@c False
@c 
@c >>> cc = CC()
@c >>> cc.x = 33
@c >>> try:
@c ...     cc.no_getter
@c ... except AttributeError as e:
@c ...     type(e).__name__
@c ...
@c 'AttributeError'
@c 
@c >>> try:
@c ...     cc.no_setter = 33
@c ... except AttributeError as e:
@c ...     type(e).__name__
@c ...
@c 'AttributeError'
@c 
@c >>> try:
@c ...     del cc.no_deleter
@c ... except AttributeError as e:
@c ...     type(e).__name__
@c ...
@c 'AttributeError'
@c 
@c >>> CC.no_doc.__doc__ is None
@c True

La fonction native @ref{192,,property()} aide chaque fois qu'une interface utilisateur a accordé l'accès à un attribut et que des modifications ultérieures nécessitent l'intervention d'une méthode.

Par exemple, une classe de tableur peut donner accès à une valeur de cellule via @code{Cell('b10').value}. Les améliorations ultérieures du programme exigent que la cellule soit recalculée à chaque accès ; cependant, le programmeur ne veut pas impacter le code client existant accédant directement à l'attribut. La solution consiste à envelopper l'accès à l'attribut `value' dans un descripteur de données :

@example
class Cell:
    ...

    @@property
    def value(self):
        "Recalculate the cell before returning value"
        self.recalc()
        return self._value
@end example

Either the built-in @ref{192,,property()} or our @code{Property()} equivalent would
work in this example.

@node Fonctions et méthodes,Types de méthodes,Propriétés,Équivalents en Python pur
@anchor{howto/descriptor functions-and-methods}@anchor{4db9}
@subsubsection Fonctions et méthodes


Les fonctionnalités orientées objet de Python sont construites sur un environnement basé sur des fonctions. À l'aide de descripteurs hors-données, les deux sont fusionnés de façon transparente.

Les fonctions placées dans les dictionnaires des classes sont transformées en méthodes au moment de l'appel. Les méthodes ne diffèrent des fonctions ordinaires que par le fait que le premier argument est réservé à l'instance de l'objet.  Par convention Python, la référence de l'instance est appelée `self', bien qu'il soit possible de l'appeler `this' ou tout autre nom de variable.

Les méthodes peuvent être créées manuellement avec @ref{1787,,types.MethodType}, qui équivaut à peu près à :

@example
class MethodType:
    "Emulate PyMethod_Type in Objects/classobject.c"

    def __init__(self, func, obj):
        self.__func__ = func
        self.__self__ = obj

    def __call__(self, *args, **kwargs):
        func = self.__func__
        obj = self.__self__
        return func(obj, *args, **kwargs)

    def __getattribute__(self, name):
        "Emulate method_getset() in Objects/classobject.c"
        if name == '__doc__':
            return self.__func__.__doc__
        return object.__getattribute__(self, name)

    def __getattr__(self, name):
        "Emulate method_getattro() in Objects/classobject.c"
        return getattr(self.__func__, name)

    def __get__(self, obj, objtype=None):
        "Emulate method_descr_get() in Objects/classobject.c"
        return self
@end example

To support automatic creation of methods, functions include the
@ref{149d,,__get__()} method for binding methods during attribute access.  This
means that functions are non-data descriptors that return bound methods
during dotted lookup from an instance.  Here's how it works:

@example
class Function:
    ...

    def __get__(self, obj, objtype=None):
        "Simulate func_descr_get() in Objects/funcobject.c"
        if obj is None:
            return self
        return MethodType(self, obj)
@end example

L'exécution de la classe suivante dans l'interpréteur montre comment le descripteur de fonction se comporte en pratique :

@example
class D:
    def f(self):
         return self

class D2:
    pass
@end example

@c >>> d = D()
@c >>> d2 = D2()
@c >>> d2.f = d.f.__get__(d2, D2)
@c >>> d2.f() is d
@c True

La fonction possède un attribut @code{__qualname__} (@ref{18ce,,nom qualifié}) pour prendre en charge l'introspection :

@example
>>> D.f.__qualname__
'D.f'
@end example

Accessing the function through the class dictionary does not invoke
@ref{149d,,__get__()}.  Instead, it just returns the underlying function object:

@example
>>> D.__dict__['f']
<function D.f at 0x00C45070>
@end example

Dotted access from a class calls @ref{149d,,__get__()} which just returns the
underlying function unchanged:

@example
>>> D.f
<function D.f at 0x00C45070>
@end example

The interesting behavior occurs during dotted access from an instance.  The
dotted lookup calls @ref{149d,,__get__()} which returns a bound method object:

@example
>>> d = D()
>>> d.f
<bound method D.f of <__main__.D object at 0x00B18C90>>
@end example

En interne, la méthode liée stocke la fonction sous-jacente et l'instance liée :

@example
>>> d.f.__func__
<function D.f at 0x00C45070>

>>> d.f.__self__
<__main__.D object at 0x00B18C90>
@end example

Si vous vous êtes déjà demandé d'où vient `self' dans les méthodes ordinaires ou d'où vient `cls' dans les méthodes de classe, c'est ça !

@node Types de méthodes,Méthodes statiques,Fonctions et méthodes,Équivalents en Python pur
@anchor{howto/descriptor kinds-of-methods}@anchor{4dba}
@subsubsection Types de méthodes


Les descripteurs hors-données constituent un moyen simple pour modifier le modèle usuel de transformation des fonctions en méthodes.

To recap, functions have a @ref{149d,,__get__()} method so that they can be converted
to a method when accessed as attributes.  The non-data descriptor transforms an
@code{obj.f(*args)} call into @code{f(obj, *args)}.  Calling @code{cls.f(*args)}
becomes @code{f(*args)}.

Ce tableau résume le lien classique (`binding') et ses deux variantes les plus utiles :

@quotation


@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 
@headitem

Transformation

@tab

Appelée depuis un objet

@tab

Appelée depuis une classe

@item

fonction

@tab

f(obj, *args)

@tab

f(*args)

@item

méthode statique

@tab

f(*args)

@tab

f(*args)

@item

méthode de classe

@tab

f(type(obj), *args)

@tab

f(cls, *args)

@end multitable

@end quotation

@node Méthodes statiques,Méthodes de classe,Types de méthodes,Équivalents en Python pur
@anchor{howto/descriptor static-methods}@anchor{4dbb}
@subsubsection Méthodes statiques


Les méthodes statiques renvoient la fonction sous-jacente sans modification. Appeler @code{c.f} ou @code{C.f} est l'équivalent d'une recherche directe dans @code{objet.__getattribute__(c, "f")} ou @code{objet.__getattribute__(C, "f")}. Par conséquent, l'accès à la fonction devient identique que ce soit à partir d'un objet ou d'une classe.

Les bonnes candidates pour être méthode statique sont des méthodes qui ne font pas référence à la variable @code{self}.

For instance, a statistics package may include a container class for
experimental data.  The class provides normal methods for computing the average,
mean, median, and other descriptive statistics that depend on the data. However,
there may be useful functions which are conceptually related but do not depend
on the data.  For instance, @code{erf(x)} is handy conversion routine that comes up
in statistical work but does not directly depend on a particular dataset.
It can be called either from an object or the class:  @code{s.erf(1.5) --> 0.9332}
or @code{Sample.erf(1.5) --> 0.9332}.

Puisque les méthodes statiques renvoient la fonction sous-jacente sans changement, les exemples d’appels sont d'une grande banalité :

@example
class E:
    @@staticmethod
    def f(x):
        return x * 10
@end example

@example
>>> E.f(3)
30
>>> E().f(3)
30
@end example

En utilisant le protocole de descripteur hors-données, une version Python pure de @ref{40c,,staticmethod()} ressemblerait à ceci :

@example
import functools

class StaticMethod:
    "Emulate PyStaticMethod_Type() in Objects/funcobject.c"

    def __init__(self, f):
        self.f = f
        functools.update_wrapper(self, f)

    def __get__(self, obj, objtype=None):
        return self.f

    def __call__(self, *args, **kwds):
        return self.f(*args, **kwds)
@end example

The @ref{100b,,functools.update_wrapper()} call adds a @code{__wrapped__} attribute
that refers to the underlying function.  Also it carries forward
the attributes necessary to make the wrapper look like the wrapped
function: @ref{12b2,,__name__}, @ref{1e80,,__qualname__},
@ref{11b6,,__doc__}, and @ref{11b5,,__annotations__}.

@c class E_sim:
@c     @StaticMethod
@c     def f(x: int) -> str:
@c         "Simple function example"
@c         return "!" * x
@c 
@c wrapped_ord = StaticMethod(ord)

@c >>> E_sim.f(3)
@c '!!!'
@c >>> E_sim().f(3)
@c '!!!'
@c 
@c >>> sm = vars(E_sim)['f']
@c >>> type(sm).__name__
@c 'StaticMethod'
@c >>> f = E_sim.f
@c >>> type(f).__name__
@c 'function'
@c >>> sm.__name__
@c 'f'
@c >>> f.__name__
@c 'f'
@c >>> sm.__qualname__
@c 'E_sim.f'
@c >>> f.__qualname__
@c 'E_sim.f'
@c >>> sm.__doc__
@c 'Simple function example'
@c >>> f.__doc__
@c 'Simple function example'
@c >>> sm.__annotations__
@c {'x': <class 'int'>, 'return': <class 'str'>}
@c >>> f.__annotations__
@c {'x': <class 'int'>, 'return': <class 'str'>}
@c >>> sm.__module__ == f.__module__
@c True
@c >>> sm(3)
@c '!!!'
@c >>> f(3)
@c '!!!'
@c 
@c >>> wrapped_ord('A')
@c 65
@c >>> wrapped_ord.__module__ == ord.__module__
@c True
@c >>> wrapped_ord.__wrapped__ == ord
@c True
@c >>> wrapped_ord.__name__ == ord.__name__
@c True
@c >>> wrapped_ord.__qualname__ == ord.__qualname__
@c True
@c >>> wrapped_ord.__doc__ == ord.__doc__
@c True

@node Méthodes de classe,Objets membres et __slots__,Méthodes statiques,Équivalents en Python pur
@anchor{howto/descriptor class-methods}@anchor{4dbc}
@subsubsection Méthodes de classe


Contrairement aux méthodes statiques, les méthodes de classe ajoutent la référence de classe en tête de la liste d'arguments, avant d'appeler la fonction. C'est le même format que l'appelant soit un objet ou une classe :

@example
class F:
    @@classmethod
    def f(cls, x):
        return cls.__name__, x
@end example

@example
>>> F.f(3)
('F', 3)
>>> F().f(3)
('F', 3)
@end example

Ce comportement est utile lorsque la fonction n'a besoin que d'une référence de classe et ne se soucie pas des données propres à une instance particulière. Une des utilisations des méthodes de classe est de créer des constructeurs de classe personnalisés. Par exemple, la méthode de classe @ref{21ca,,dict.fromkeys()} crée un nouveau dictionnaire à partir d'une liste de clés.  L'équivalent Python pur est :

@example
class Dict(dict):
    @@classmethod
    def fromkeys(cls, iterable, value=None):
        "Emulate dict_fromkeys() in Objects/dictobject.c"
        d = cls()
        for key in iterable:
            d[key] = value
        return d
@end example

Maintenant un nouveau dictionnaire de clés uniques peut être construit comme ceci :

@example
>>> d = Dict.fromkeys('abracadabra')
>>> type(d) is Dict
True
>>> d
@{'a': None, 'b': None, 'r': None, 'c': None, 'd': None@}
@end example

En utilisant le protocole de descripteur hors-données, une version Python pure de @ref{165,,classmethod()} ressemblerait à ceci :

@example
import functools

class ClassMethod:
    "Emulate PyClassMethod_Type() in Objects/funcobject.c"

    def __init__(self, f):
        self.f = f
        functools.update_wrapper(self, f)

    def __get__(self, obj, cls=None):
        if cls is None:
            cls = type(obj)
        return MethodType(self.f, cls)
@end example

@c # Verify the emulation works
@c class T:
@c     @ClassMethod
@c     def cm(cls, x: int, y: str) -> tuple[str, int, str]:
@c         "Class method that returns a tuple"
@c         return (cls.__name__, x, y)

@c >>> T.cm(11, 22)
@c ('T', 11, 22)
@c 
@c # Also call it from an instance
@c >>> t = T()
@c >>> t.cm(11, 22)
@c ('T', 11, 22)
@c 
@c # Verify that T uses our emulation
@c >>> type(vars(T)['cm']).__name__
@c 'ClassMethod'
@c 
@c # Verify that update_wrapper() correctly copied attributes
@c >>> T.cm.__name__
@c 'cm'
@c >>> T.cm.__qualname__
@c 'T.cm'
@c >>> T.cm.__doc__
@c 'Class method that returns a tuple'
@c >>> T.cm.__annotations__
@c {'x': <class 'int'>, 'y': <class 'str'>, 'return': tuple[str, int, str]}
@c 
@c # Verify that __wrapped__ was added and works correctly
@c >>> f = vars(T)['cm'].__wrapped__
@c >>> type(f).__name__
@c 'function'
@c >>> f.__name__
@c 'cm'
@c >>> f(T, 11, 22)
@c ('T', 11, 22)

The @ref{100b,,functools.update_wrapper()} call in @code{ClassMethod} adds a
@code{__wrapped__} attribute that refers to the underlying function.  Also
it carries forward the attributes necessary to make the wrapper look
like the wrapped function: @ref{12b2,,__name__},
@ref{1e80,,__qualname__}, @ref{11b6,,__doc__},
and @ref{11b5,,__annotations__}.

@node Objets membres et __slots__,,Méthodes de classe,Équivalents en Python pur
@anchor{howto/descriptor member-objects-and-slots}@anchor{4dbd}
@subsubsection Objets membres et `__slots__'


Lorsqu'une classe définit @code{__slots__}, Python remplace le dictionnaire d'instance par un tableau de longueur fixe de créneaux prédéfinis. D'un point de vue utilisateur, cela :

1/ permet une détection immédiate des bogues dus à des affectations d'attributs mal orthographiés. Seuls les noms d'attribut spécifiés dans @code{__slots__} sont autorisés :

@example
class Vehicle:
    __slots__ = ('id_number', 'make', 'model')
@end example

@example
>>> auto = Vehicle()
>>> auto.id_nubmer = 'VYE483814LQEX'
Traceback (most recent call last):
    ...
AttributeError: 'Vehicle' object has no attribute 'id_nubmer'
@end example

2/ aide à créer des objets immuables où les descripteurs gèrent l'accès aux attributs privés stockés dans @code{__slots__} :

@example
class Immutable:

    __slots__ = ('_dept', '_name')          # Replace the instance dictionary

    def __init__(self, dept, name):
        self._dept = dept                   # Store to private attribute
        self._name = name                   # Store to private attribute

    @@property                               # Read-only descriptor
    def dept(self):
        return self._dept

    @@property
    def name(self):                         # Read-only descriptor
        return self._name
@end example

@example
>>> mark = Immutable('Botany', 'Mark Watney')
>>> mark.dept
'Botany'
>>> mark.dept = 'Space Pirate'
Traceback (most recent call last):
    ...
AttributeError: property 'dept' of 'Immutable' object has no setter
>>> mark.location = 'Mars'
Traceback (most recent call last):
    ...
AttributeError: 'Immutable' object has no attribute 'location'
@end example

3/ économise de la mémoire. Sur une version Linux 64 bits, une instance avec deux attributs prend 48 octets avec @code{__slots__} et 152 octets sans. Ce patron de conception poids mouche@footnote{https://fr.wikipedia.org/wiki/Poids-mouche_(patron_de_conception)} n'a probablement d'importance que si un grand nombre d'instances doivent être créées ;

4/ améliore la vitesse. La lecture des variables d'instance est 35 % plus rapide avec @code{__slots__} (mesure effectuée avec Python 3.10 sur un processeur Apple M1) ;

5/ bloque les outils comme @ref{52c,,functools.cached_property()} qui nécessitent un dictionnaire d'instance pour fonctionner correctement :

@example
from functools import cached_property

class CP:
    __slots__ = ()                          # Eliminates the instance dict

    @@cached_property                        # Requires an instance dict
    def pi(self):
        return 4 * sum((-1.0)**n / (2.0*n + 1.0)
                       for n in reversed(range(100_000)))
@end example

@example
>>> CP().pi
Traceback (most recent call last):
  ...
TypeError: No '__dict__' attribute on 'CP' instance to cache 'pi' property.
@end example

Il n'est pas possible de créer une version Python pure exacte de @code{__slots__} car il faut un accès direct aux structures C et un contrôle sur l'allocation de la mémoire des objets. Cependant, nous pouvons construire une simulation presque fidèle où la structure C réelle pour les `slots' est émulée par une liste privée @code{_slotvalues}. Les lectures et écritures dans cette structure privée sont gérées par des descripteurs de membres :

@example
null = object()

class Member:

    def __init__(self, name, clsname, offset):
        'Emulate PyMemberDef in Include/structmember.h'
        # Also see descr_new() in Objects/descrobject.c
        self.name = name
        self.clsname = clsname
        self.offset = offset

    def __get__(self, obj, objtype=None):
        'Emulate member_get() in Objects/descrobject.c'
        # Also see PyMember_GetOne() in Python/structmember.c
        if obj is None:
            return self
        value = obj._slotvalues[self.offset]
        if value is null:
            raise AttributeError(self.name)
        return value

    def __set__(self, obj, value):
        'Emulate member_set() in Objects/descrobject.c'
        obj._slotvalues[self.offset] = value

    def __delete__(self, obj):
        'Emulate member_delete() in Objects/descrobject.c'
        value = obj._slotvalues[self.offset]
        if value is null:
            raise AttributeError(self.name)
        obj._slotvalues[self.offset] = null

    def __repr__(self):
        'Emulate member_repr() in Objects/descrobject.c'
        return f'<Member @{self.name!r@} of @{self.clsname!r@}>'
@end example

The @code{type.__new__()} method takes care of adding member objects to class
variables:

@example
class Type(type):
    'Simulate how the type metaclass adds member objects for slots'

    def __new__(mcls, clsname, bases, mapping, **kwargs):
        'Emulate type_new() in Objects/typeobject.c'
        # type_new() calls PyTypeReady() which calls add_methods()
        slot_names = mapping.get('slot_names', [])
        for offset, name in enumerate(slot_names):
            mapping[name] = Member(name, clsname, offset)
        return type.__new__(mcls, clsname, bases, mapping, **kwargs)
@end example

La méthode @ref{56c,,object.__new__()} s'occupe de créer des instances qui ont des `slots' au lieu d'un dictionnaire d'instances. Voici une simulation approximative en Python pur :

@example
class Object:
    'Simulate how object.__new__() allocates memory for __slots__'

    def __new__(cls, *args, **kwargs):
        'Emulate object_new() in Objects/typeobject.c'
        inst = super().__new__(cls)
        if hasattr(cls, 'slot_names'):
            empty_slots = [null] * len(cls.slot_names)
            object.__setattr__(inst, '_slotvalues', empty_slots)
        return inst

    def __setattr__(self, name, value):
        'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'
        cls = type(self)
        if hasattr(cls, 'slot_names') and name not in cls.slot_names:
            raise AttributeError(
                f'@{cls.__name__!r@} object has no attribute @{name!r@}'
            )
        super().__setattr__(name, value)

    def __delattr__(self, name):
        'Emulate _PyObject_GenericSetAttrWithDict() Objects/object.c'
        cls = type(self)
        if hasattr(cls, 'slot_names') and name not in cls.slot_names:
            raise AttributeError(
                f'@{cls.__name__!r@} object has no attribute @{name!r@}'
            )
        super().__delattr__(name)
@end example

To use the simulation in a real class, just inherit from @code{Object} and
set the @ref{1f09,,metaclass} to @code{Type}:

@example
class H(Object, metaclass=Type):
    'Instance variables stored in slots'

    slot_names = ['x', 'y']

    def __init__(self, x, y):
        self.x = x
        self.y = y
@end example

À ce stade, la métaclasse a chargé des objets membres pour `x' et `y' :

@example
>>> from pprint import pp
>>> pp(dict(vars(H)))
@{'__module__': '__main__',
 '__doc__': 'Instance variables stored in slots',
 'slot_names': ['x', 'y'],
 '__init__': <function H.__init__ at 0x7fb5d302f9d0>,
 'x': <Member 'x' of 'H'>,
 'y': <Member 'y' of 'H'>@}
@end example

@c # We test this separately because the preceding section is not
@c # doctestable due to the hex memory address for the __init__ function
@c >>> isinstance(vars(H)['x'], Member)
@c True
@c >>> isinstance(vars(H)['y'], Member)
@c True

Lorsque les instances sont créées, elles ont une liste @code{slot_values} où les attributs sont stockés :

@example
>>> h = H(10, 20)
>>> vars(h)
@{'_slotvalues': [10, 20]@}
>>> h.x = 55
>>> vars(h)
@{'_slotvalues': [55, 20]@}
@end example

Les attributs mal orthographiés ou non attribués lèvent une exception :

@example
>>> h.xz
Traceback (most recent call last):
    ...
AttributeError: 'H' object has no attribute 'xz'
@end example

@c  # Examples for deleted attributes are not shown because this section
@c  # is already a bit lengthy.  We still test that code here.
@c  >>> del h.x
@c  >>> hasattr(h, 'x')
@c  False
@c 
@c  # Also test the code for uninitialized slots
@c  >>> class HU(Object, metaclass=Type):
@c  ...     slot_names = ['x', 'y']
@c  ...
@c  >>> hu = HU()
@c  >>> hasattr(hu, 'x')
@c  False
@c  >>> hasattr(hu, 'y')
@c  False

@node Debugging C API extensions and CPython Internals with GDB,Guide sur l'utilisation d'Enum,Descriptor Guide,Les HOWTOs de Python
@anchor{howto/gdb_helpers doc}@anchor{4dbe}@anchor{howto/gdb_helpers debugging-c-api-extensions-and-cpython-internals-with-gdb}@anchor{4dbf}@anchor{howto/gdb_helpers gdb}@anchor{4dc0}
@section Debugging C API extensions and CPython Internals with GDB


This document explains how the Python GDB extension, @code{python-gdb.py}, can
be used with the GDB debugger to debug CPython extensions and the
CPython interpreter itself.

When debugging low-level problems such as crashes or deadlocks, a low-level
debugger, such as GDB, is useful to diagnose and correct the issue.
By default, GDB (or any of its front-ends) doesn't support high-level
information specific to the CPython interpreter.

The @code{python-gdb.py} extension adds CPython interpreter information to GDB.
The extension helps introspect the stack of currently executing Python functions.
Given a Python object represented by a @ref{32f,,PyObject}* pointer,
the extension surfaces the type and value of the object.

Developers who are working on CPython extensions or tinkering with parts
of CPython that are written in C can use this document to learn how to use the
@code{python-gdb.py} extension with GDB.

@cartouche
@quotation Note 
This document assumes that you are familiar with the basics of GDB and the
CPython C API. It consolidates guidance from the
devguide@footnote{https://devguide.python.org}  and the
Python wiki@footnote{https://wiki.python.org/moin/DebuggingWithGdb}.
@end quotation
@end cartouche

@menu
* Prerequisites:: 
* Using the Debug build and Development mode:: 
* Using the python-gdb extension:: 
* Use with GDB commands:: 

@end menu

@node Prerequisites,Using the Debug build and Development mode,,Debugging C API extensions and CPython Internals with GDB
@anchor{howto/gdb_helpers prerequisites}@anchor{4dc1}
@subsection Prerequisites


You need to have:


@itemize -

@item 
GDB 7 or later. (For earlier versions of GDB, see @code{Misc/gdbinit} in the
sources of Python 3.11 or earlier.)

@item 
GDB-compatible debugging information for Python and any extension you are
debugging.

@item 
The @code{python-gdb.py} extension.
@end itemize

The extension is built with Python, but might be distributed separately or
not at all. Below, we include tips for a few common systems as examples.
Note that even if the instructions match your system, they might be outdated.

@menu
* Setup with Python built from source:: 
* Setup for Python from a Linux distro:: 

@end menu

@node Setup with Python built from source,Setup for Python from a Linux distro,,Prerequisites
@anchor{howto/gdb_helpers setup-with-python-built-from-source}@anchor{4dc2}
@subsubsection Setup with Python built from source


When you build CPython from source, debugging information should be available,
and the build should add a @code{python-gdb.py} file to the root directory of
your repository.

To activate support, you must add the directory containing @code{python-gdb.py}
to GDB's "auto-load-safe-path".
If you haven't done this, recent versions of GDB will print out a warning
with instructions on how to do this.

@cartouche
@quotation Note 
If you do not see instructions for your version of GDB, put this in your
configuration file (@code{~/.gdbinit} or @code{~/.config/gdb/gdbinit}):

@example
add-auto-load-safe-path /path/to/cpython
@end example

You can also add multiple paths, separated by @code{:}.
@end quotation
@end cartouche

@node Setup for Python from a Linux distro,,Setup with Python built from source,Prerequisites
@anchor{howto/gdb_helpers setup-for-python-from-a-linux-distro}@anchor{4dc3}
@subsubsection Setup for Python from a Linux distro


Most Linux systems provide debug information for the system Python
in a package called @code{python-debuginfo}, @code{python-dbg} or similar.
For example:


@itemize -

@item 
Fedora:

@quotation

@example
sudo dnf install gdb
sudo dnf debuginfo-install python3
@end example
@end quotation

@item 
Ubuntu:

@quotation

@example
sudo apt install gdb python3-dbg
@end example
@end quotation
@end itemize

On several recent Linux systems, GDB can download debugging symbols
automatically using `debuginfod'.
However, this will not install the @code{python-gdb.py} extension;
you generally do need to install the debug info package separately.

@node Using the Debug build and Development mode,Using the python-gdb extension,Prerequisites,Debugging C API extensions and CPython Internals with GDB
@anchor{howto/gdb_helpers using-the-debug-build-and-development-mode}@anchor{4dc4}
@subsection Using the Debug build and Development mode


For easier debugging, you might want to:


@itemize -

@item 
Use a @ref{1f6,,debug build} of Python. (When building from source,
use @code{configure --with-pydebug}. On Linux distros, install and run a package
like @code{python-debug} or @code{python-dbg}, if available.)

@item 
Use the runtime @ref{1f5,,development mode} (@code{-X dev}).
@end itemize

Both enable extra assertions and disable some optimizations.
Sometimes this hides the bug you are trying to find, but in most cases they
make the process easier.

@node Using the python-gdb extension,Use with GDB commands,Using the Debug build and Development mode,Debugging C API extensions and CPython Internals with GDB
@anchor{howto/gdb_helpers using-the-python-gdb-extension}@anchor{4dc5}
@subsection Using the @code{python-gdb} extension


When the extension is loaded, it provides two main features:
pretty printers for Python values, and additional commands.

@menu
* Pretty-printers:: 
* py-list:: 
* py-up and py-down:: 
* py-bt:: 
* py-print:: 
* py-locals:: 

@end menu

@node Pretty-printers,py-list,,Using the python-gdb extension
@anchor{howto/gdb_helpers pretty-printers}@anchor{4dc6}
@subsubsection Pretty-printers


This is what a GDB backtrace looks like (truncated) when this extension is
enabled:

@example
#0  0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at address 0x7fffff7fefe8
) at Objects/obmalloc.c:748
#1  0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) at Objects/obmalloc.c:1445
#2  0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/obmalloc.c:1412
#3  0x000000000044060a in _PyUnicode_New (length=11) at Objects/unicodeobject.c:346
#4  0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d "__lltrace__", size=11, errors=0x0, consumed=
    0x0) at Objects/unicodeobject.c:2531
#5  0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d "__lltrace__", size=11, errors=0x0)
    at Objects/unicodeobject.c:2495
#6  0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d "__lltrace__", size=11)
    at Objects/unicodeobject.c:551
#7  0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d "__lltrace__") at Objects/unicodeobject.c:569
#8  0x0000000000584abd in PyDict_GetItemString (v=
    @{'Yuck': <type at remote 0xad4730>, '__builtins__': <module at remote 0x7ffff7fd5ee8>, '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', '__package__': None, 'y': <Yuck(i=0) at remote 0xaacd80>, 'dict': @{0: 0, 1: 1, 2: 2, 3: 3@}, '__cached__': None, '__name__': '__main__', 'z': <Yuck(i=0) at remote 0xaace60>, '__doc__': None@}, key=
    0x5c2b8d "__lltrace__") at Objects/dictobject.c:2171
@end example

Notice how the dictionary argument to @code{PyDict_GetItemString} is displayed
as its @code{repr()}, rather than an opaque @code{PyObject *} pointer.

The extension works by supplying a custom printing routine for values of type
@code{PyObject *}.  If you need to access lower-level details of an object, then
cast the value to a pointer of the appropriate type.  For example:

@example
(gdb) p globals
$1 = @{'__builtins__': <module at remote 0x7ffff7fb1868>, '__name__':
'__main__', 'ctypes': <module at remote 0x7ffff7f14360>, '__doc__': None,
'__package__': None@}

(gdb) p *(PyDictObject*)globals
$2 = @{ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,
ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70
<lookdict_string>, ma_smalltable = @{@{me_hash = 7065186196740147912,
me_key = '__builtins__', me_value = <module at remote 0x7ffff7fb1868>@},
@{me_hash = -368181376027291943, me_key = '__name__',
me_value ='__main__'@}, @{me_hash = 0, me_key = 0x0, me_value = 0x0@},
@{me_hash = 0, me_key = 0x0, me_value = 0x0@},
@{me_hash = -9177857982131165996, me_key = 'ctypes',
me_value = <module at remote 0x7ffff7f14360>@},
@{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None@},
@{me_hash = 0, me_key = 0x0, me_value = 0x0@}, @{
  me_hash = 6614918939584953775, me_key = '__package__', me_value = None@}@}@}
@end example

Note that the pretty-printers do not actually call @code{repr()}.
For basic types, they try to match its result closely.

An area that can be confusing is that the custom printer for some types look a
lot like GDB's built-in printer for standard types.  For example, the
pretty-printer for a Python @code{int} (@ref{574,,PyLongObject}*)
gives a representation that is not distinguishable from one of a
regular machine-level integer:

@example
(gdb) p some_machine_integer
$3 = 42

(gdb) p some_python_integer
$4 = 42
@end example

The internal structure can be revealed with a cast to @ref{574,,PyLongObject}*:

@example
(gdb) p *(PyLongObject*)some_python_integer
$5 = @{ob_base = @{ob_base = @{ob_refcnt = 8, ob_type = 0x3dad39f5e0@}, ob_size = 1@},
ob_digit = @{42@}@}
@end example

A similar confusion can arise with the @code{str} type, where the output looks a
lot like gdb's built-in printer for @code{char *}:

@example
(gdb) p ptr_to_python_str
$6 = '__builtins__'
@end example

The pretty-printer for @code{str} instances defaults to using single-quotes (as
does Python's @code{repr} for strings) whereas the standard printer for @code{char *}
values uses double-quotes and contains a hexadecimal address:

@example
(gdb) p ptr_to_char_star
$7 = 0x6d72c0 "hello world"
@end example

Again, the implementation details can be revealed with a cast to
@ref{77e,,PyUnicodeObject}*:

@example
(gdb) p *(PyUnicodeObject*)$6
$8 = @{ob_base = @{ob_refcnt = 33, ob_type = 0x3dad3a95a0@}, length = 12,
str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0@}
@end example

@node py-list,py-up and py-down,Pretty-printers,Using the python-gdb extension
@anchor{howto/gdb_helpers py-list}@anchor{4dc7}
@subsubsection @code{py-list}


@quotation

The extension adds a @code{py-list} command, which
lists the Python source code (if any) for the current frame in the selected
thread.  The current line is marked with a ">":

@example
(gdb) py-list
 901        if options.profile:
 902            options.profile = False
 903            profile_me()
 904            return
 905
>906        u = UI()
 907        if not u.quit:
 908            try:
 909                gtk.main()
 910            except KeyboardInterrupt:
 911                # properly quit on a keyboard interrupt...
@end example

Use @code{py-list START} to list at a different line number within the Python
source, and @code{py-list START,END} to list a specific range of lines within
the Python source.
@end quotation

@node py-up and py-down,py-bt,py-list,Using the python-gdb extension
@anchor{howto/gdb_helpers py-up-and-py-down}@anchor{4dc8}
@subsubsection @code{py-up} and @code{py-down}


@quotation

The @code{py-up} and @code{py-down} commands are analogous to GDB's regular @code{up}
and @code{down} commands, but try to move at the level of CPython frames, rather
than C frames.

GDB is not always able to read the relevant frame information, depending on
the optimization level with which CPython was compiled. Internally, the
commands look for C frames that are executing the default frame evaluation
function (that is, the core bytecode interpreter loop within CPython) and
look up the value of the related @code{PyFrameObject *}.

They emit the frame number (at the C level) within the thread.

Par exemple :

@example
(gdb) py-up
#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/
gnome_sudoku/main.py, line 906, in start_game ()
    u = UI()
(gdb) py-up
#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/
gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=<module at remote 0xb771b7f4>)
    main.start_game()
(gdb) py-up
Unable to find an older python frame
@end example

so we're at the top of the Python stack.

The frame numbers correspond to those displayed by GDB's standard
@code{backtrace} command.
The command skips C frames which are not executing Python code.

Going back down:

@example
(gdb) py-down
#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game ()
    u = UI()
(gdb) py-down
#34 (unable to read python frame information)
(gdb) py-down
#23 (unable to read python frame information)
(gdb) py-down
#19 (unable to read python frame information)
(gdb) py-down
#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=<NewOrSavedGameSelector(new_game_model=<gtk.ListStore at remote 0x98fab44>, puzzle=None, saved_games=[@{'gsd.auto_fills': 0, 'tracking': @{@}, 'trackers': @{@}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': <float at remote 0x984b474>, 'gsd.hints': 0, 'timer.active_time': <float at remote 0x984b494>, 'timer.total_time': <float at remote 0x984b464>@}], dialog=<gtk.Dialog at remote 0x98faaa4>, saved_game_model=<gtk.ListStore at remote 0x98fad24>, sudoku_maker=<SudokuMaker(terminated=False, played=[], batch_siz...(truncated)
            swallower.run_dialog(self.dialog)
(gdb) py-down
#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=<SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>, main_page=0) at remote 0x98fa6e4>, d=<gtk.Dialog at remote 0x98faaa4>)
            gtk.main()
(gdb) py-down
#8 (unable to read python frame information)
(gdb) py-down
Unable to find a newer python frame
@end example

and we're at the bottom of the Python stack.

Note that in Python 3.12 and newer, the same C stack frame can be used for
multiple Python stack frames. This means that @code{py-up} and @code{py-down}
may move multiple Python frames at once. For example:

@example
(gdb) py-up
#6 Frame 0x7ffff7fb62b0, for file /tmp/rec.py, line 5, in recursive_function (n=0)
   time.sleep(5)
#6 Frame 0x7ffff7fb6240, for file /tmp/rec.py, line 7, in recursive_function (n=1)
   recursive_function(n-1)
#6 Frame 0x7ffff7fb61d0, for file /tmp/rec.py, line 7, in recursive_function (n=2)
   recursive_function(n-1)
#6 Frame 0x7ffff7fb6160, for file /tmp/rec.py, line 7, in recursive_function (n=3)
   recursive_function(n-1)
#6 Frame 0x7ffff7fb60f0, for file /tmp/rec.py, line 7, in recursive_function (n=4)
   recursive_function(n-1)
#6 Frame 0x7ffff7fb6080, for file /tmp/rec.py, line 7, in recursive_function (n=5)
   recursive_function(n-1)
#6 Frame 0x7ffff7fb6020, for file /tmp/rec.py, line 9, in <module> ()
   recursive_function(5)
(gdb) py-up
Unable to find an older python frame
@end example
@end quotation

@node py-bt,py-print,py-up and py-down,Using the python-gdb extension
@anchor{howto/gdb_helpers py-bt}@anchor{4dc9}
@subsubsection @code{py-bt}


@quotation

The @code{py-bt} command attempts to display a Python-level backtrace of the
current thread.

Par exemple :

@example
(gdb) py-bt
#8 (unable to read python frame information)
#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=<SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>, main_page=0) at remote 0x98fa6e4>, d=<gtk.Dialog at remote 0x98faaa4>)
            gtk.main()
#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=<NewOrSavedGameSelector(new_game_model=<gtk.ListStore at remote 0x98fab44>, puzzle=None, saved_games=[@{'gsd.auto_fills': 0, 'tracking': @{@}, 'trackers': @{@}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': <float at remote 0x984b474>, 'gsd.hints': 0, 'timer.active_time': <float at remote 0x984b494>, 'timer.total_time': <float at remote 0x984b464>@}], dialog=<gtk.Dialog at remote 0x98faaa4>, saved_game_model=<gtk.ListStore at remote 0x98fad24>, sudoku_maker=<SudokuMaker(terminated=False, played=[], batch_siz...(truncated)
            swallower.run_dialog(self.dialog)
#19 (unable to read python frame information)
#23 (unable to read python frame information)
#34 (unable to read python frame information)
#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game ()
    u = UI()
#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/gnome_sudoku/gnome_sudoku.py, line 22, in start_game (main=<module at remote 0xb771b7f4>)
    main.start_game()
@end example

The frame numbers correspond to those displayed by GDB's standard
@code{backtrace} command.
@end quotation

@node py-print,py-locals,py-bt,Using the python-gdb extension
@anchor{howto/gdb_helpers py-print}@anchor{4dca}
@subsubsection @code{py-print}


@quotation

The @code{py-print} command looks up a Python name and tries to print it.
It looks in locals within the current thread, then globals, then finally
builtins:

@example
(gdb) py-print self
local 'self' = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
main_page=0) at remote 0x98fa6e4>
(gdb) py-print __name__
global '__name__' = 'gnome_sudoku.dialog_swallower'
(gdb) py-print len
builtin 'len' = <built-in function len>
(gdb) py-print scarlet_pimpernel
'scarlet_pimpernel' not found
@end example

If the current C frame corresponds to multiple Python frames, @code{py-print}
only considers the first one.
@end quotation

@node py-locals,,py-print,Using the python-gdb extension
@anchor{howto/gdb_helpers py-locals}@anchor{4dcb}
@subsubsection @code{py-locals}


@quotation

The @code{py-locals} command looks up all Python locals within the current
Python frame in the selected thread, and prints their representations:

@example
(gdb) py-locals
self = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
main_page=0) at remote 0x98fa6e4>
d = <gtk.Dialog at remote 0x98faaa4>
@end example

If the current C frame corresponds to multiple Python frames, locals from
all of them will be shown:

@example
(gdb) py-locals
Locals for recursive_function
n = 0
Locals for recursive_function
n = 1
Locals for recursive_function
n = 2
Locals for recursive_function
n = 3
Locals for recursive_function
n = 4
Locals for recursive_function
n = 5
Locals for <module>
@end example
@end quotation

@node Use with GDB commands,,Using the python-gdb extension,Debugging C API extensions and CPython Internals with GDB
@anchor{howto/gdb_helpers use-with-gdb-commands}@anchor{4dcc}
@subsection Use with GDB commands


The extension commands complement GDB's built-in commands.
For example, you can use a frame numbers shown by @code{py-bt} with the @code{frame}
command to go a specific frame within the selected thread, like this:

@example
(gdb) py-bt
(output snipped)
#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> ()
        main()
(gdb) frame 68
#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> (), throwflag=0) at Python/ceval.c:2665
2665                            x = call_function(&sp, oparg);
(gdb) py-list
1543        # Run the tests in a context manager that temporary changes the CWD to a
1544        # temporary and writable directory. If it's not possible to create or
1545        # change the CWD, the original CWD will be used. The original CWD is
1546        # available from test_support.SAVEDCWD.
1547        with test_support.temp_cwd(TESTCWD, quiet=True):
>1548            main()
@end example

The @code{info threads} command will give you a list of the threads within the
process, and you can use the @code{thread} command to select a different one:

@example
(gdb) info threads
  105 Thread 0x7fffefa18710 (LWP 10260)  sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86
  104 Thread 0x7fffdf5fe710 (LWP 10259)  sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86
* 1 Thread 0x7ffff7fe2700 (LWP 10145)  0x00000038e46d73e3 in select () at ../sysdeps/unix/syscall-template.S:82
@end example

You can use @code{thread apply all COMMAND} or (@code{t a a COMMAND} for short) to run
a command on all threads.  With @code{py-bt}, this lets you see what every
thread is doing at the Python level:

@example
(gdb) t a a py-bt

Thread 105 (Thread 0x7fffefa18710 (LWP 10260)):
#5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140737213728528), count=1, owner=140737213728528)
        self.__block.acquire()
#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, acquire=<instancemethod at remote 0xd80260>, _is_owned=<instancemethod at remote 0xd80160>, _release_save=<instancemethod at remote 0xd803e0>, release=<instancemethod at remote 0xd802e0>, _acquire_restore=<instancemethod at remote 0xd7ee60>, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=<thread.lock at remote 0x858a90>, saved_state=(1, 140737213728528))
            self._acquire_restore(saved_state)
#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f ()
            cond.wait()
#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140737213728528)
                f()

Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):
#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140736940992272), count=1, owner=140736940992272)
        self.__block.acquire()
#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, acquire=<instancemethod at remote 0xd80260>, _is_owned=<instancemethod at remote 0xd80160>, _release_save=<instancemethod at remote 0xd803e0>, release=<instancemethod at remote 0xd802e0>, _acquire_restore=<instancemethod at remote 0xd7ee60>, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=<thread.lock at remote 0x858860>, saved_state=(1, 140736940992272))
            self._acquire_restore(saved_state)
#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f ()
            cond.wait()
#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140736940992272)
                f()

Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):
#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 16, in _wait ()
    time.sleep(0.01)
#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 378, in _check_notify (self=<ConditionTests(_testMethodName='test_notify', _resultForDoCleanups=<TestResult(_original_stdout=<cStringIO.StringO at remote 0xc191e0>, skipped=[], _mirrorOutput=False, testsRun=39, buffer=False, _original_stderr=<file at remote 0x7ffff7fc6340>, _stdout_buffer=<cStringIO.StringO at remote 0xc9c7f8>, _stderr_buffer=<cStringIO.StringO at remote 0xc9c790>, _moduleSetUpFailed=False, expectedFailures=[], errors=[], _previousTestClass=<type at remote 0x928310>, unexpectedSuccesses=[], failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, _threads=(0,), _cleanups=[], _type_equality_funcs=@{<type at remote 0x7eba00>: <instancemethod at remote 0xd750e0>, <type at remote 0x7e7820>: <instancemethod at remote 0xd75160>, <type at remote 0x7e30e0>: <instancemethod at remote 0xd75060>, <type at remote 0x7e7d20>: <instancemethod at remote 0xd751e0>, <type at remote 0x7f19e0...(truncated)
        _wait()
@end example

@node Guide sur l'utilisation d'Enum,Guide pratique programmation fonctionnelle,Debugging C API extensions and CPython Internals with GDB,Les HOWTOs de Python
@anchor{howto/enum doc}@anchor{4dcd}@anchor{howto/enum enum-howto}@anchor{4dce}@anchor{howto/enum id1}@anchor{4dcf}
@section Guide sur l'utilisation d'`Enum'

@anchor{howto/enum enum-basic-tutorial}@anchor{2533}
An @ref{61b,,Enum} is a set of symbolic names bound to unique values.  They are
similar to global variables, but they offer a more useful @ref{7e7,,repr()},
grouping, type-safety, and a few other features.

Elles sont particulièrement utiles lorsque vous avez une variable qui peut prendre une valeur dans une plage limitée de valeurs. Par exemple, les jours de la semaine :

@example
>>> from enum import Enum
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
@end example

Ou alors les couleurs primaires `RVB' (NdT : `RGB' en anglais) :

@example
>>> from enum import Enum
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
@end example

Comme vous pouvez le voir, créer une @ref{61b,,Enum} est très simple à écrire, il suffit qu'elle hérite de @ref{61b,,Enum} elle-même.

@cartouche
@quotation Note 
casse des membres d'une énumération

Because Enums are used to represent constants, and to help avoid issues
with name clashes between mixin-class methods/attributes and enum names,
we strongly recommend using UPPER_CASE names for members, and will be using
that style in our examples.
@end quotation
@end cartouche

Selon la nature de l'énumération, il peut être important d'avoir accès à la valeur d'un membre. Dans tous les cas, cette valeur peut être utilisée pour obtenir le membre correspondant :

@example
>>> Weekday(3)
<Weekday.WEDNESDAY: 3>
@end example

Comme vous pouvez le constater, la @code{repr()} d'un membre affiche le nom de l'énumération, le nom du membre et la valeur. La @code{str()} d'un membre affiche uniquement le nom de l'énumération et le nom du membre :

@example
>>> print(Weekday.THURSDAY)
Weekday.THURSDAY
@end example

Le `type' d'un membre d'énumération est l'énumération à laquelle il appartient :

@example
>>> type(Weekday.MONDAY)
<enum 'Weekday'>
>>> isinstance(Weekday.FRIDAY, Weekday)
True
@end example

Enum members have an attribute that contains just their @code{name}:

@example
>>> print(Weekday.TUESDAY.name)
TUESDAY
@end example

Likewise, they have an attribute for their @code{value}:

@example
>>> Weekday.WEDNESDAY.value
3
@end example

Unlike many languages that treat enumerations solely as name/value pairs,
Python Enums can have behavior added.  For example, @ref{1c8,,datetime.date}
has two methods for returning the weekday:
@ref{23d3,,weekday()} and @ref{23d4,,isoweekday()}.
The difference is that one of them counts from 0-6 and the other from 1-7.
Rather than keep track of that ourselves we can add a method to the @code{Weekday}
enum to extract the day from the @ref{1c8,,date} instance and return the matching
enum member:

@example
@@classmethod
def from_date(cls, date):
    return cls(date.isoweekday())
@end example

The complete @code{Weekday} enum now looks like this:

@example
>>> class Weekday(Enum):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 3
...     THURSDAY = 4
...     FRIDAY = 5
...     SATURDAY = 6
...     SUNDAY = 7
...     #
...     @@classmethod
...     def from_date(cls, date):
...         return cls(date.isoweekday())
@end example

Maintenant, nous pouvons découvrir quel jour nous sommes aujourd'hui ! Regardez :

@example
>>> from datetime import date
>>> Weekday.from_date(date.today())     
<Weekday.TUESDAY: 2>
@end example

Bien sûr, si vous lisez cette page un autre jour, vous verrez ce jour-là à la place.

This @code{Weekday} enum is great if our variable only needs one day, but
what if we need several?  Maybe we're writing a function to plot chores during
a week, and don't want to use a @ref{5fc,,list} -- we could use a different type
of @ref{61b,,Enum}:

@example
>>> from enum import Flag
>>> class Weekday(Flag):
...     MONDAY = 1
...     TUESDAY = 2
...     WEDNESDAY = 4
...     THURSDAY = 8
...     FRIDAY = 16
...     SATURDAY = 32
...     SUNDAY = 64
@end example

Nous avons changé deux choses : nous héritons de @ref{60e,,Flag} et les valeurs sont toutes des puissances de 2.

Just like the original @code{Weekday} enum above, we can have a single selection:

@example
>>> first_week_day = Weekday.MONDAY
>>> first_week_day
<Weekday.MONDAY: 1>
@end example

Mais @ref{60e,,Flag} nous permet aussi de combiner plusieurs membres en une seule variable :

@example
>>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
>>> weekend
<Weekday.SATURDAY|SUNDAY: 96>
@end example

Nous pouvons même itérer sur une variable @ref{60e,,Flag} :

@example
>>> for day in weekend:
...     print(day)
Weekday.SATURDAY
Weekday.SUNDAY
@end example

Bien, préparons quelques corvées :

@example
>>> chores_for_ethan = @{
...     'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday.FRIDAY,
...     'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,
...     'answer SO questions': Weekday.SATURDAY,
...     @}
@end example

Et une fonction pour afficher les corvées d'un jour donné :

@example
>>> def show_chores(chores, day):
...     for chore, days in chores.items():
...         if day in days:
...             print(chore)
...
>>> show_chores(chores_for_ethan, Weekday.SATURDAY)
answer SO questions
@end example

In cases where the actual values of the members do not matter, you can save
yourself some work and use @ref{c8a,,auto()} for the values:

@example
>>> from enum import auto
>>> class Weekday(Flag):
...     MONDAY = auto()
...     TUESDAY = auto()
...     WEDNESDAY = auto()
...     THURSDAY = auto()
...     FRIDAY = auto()
...     SATURDAY = auto()
...     SUNDAY = auto()
...     WEEKEND = SATURDAY | SUNDAY
@end example

@menu
* Accès par programme aux membres de l'énumération et à leurs attributs:: 
* Duplication des membres et des valeurs d'une énumération:: 
* Garantie de valeurs d'énumération uniques:: 
* Utilisation de valeurs automatiques:: 
* Itération: Itération<2>. 
* Comparaisons: Comparaisons<3>. 
* Membres et attributs autorisés des énumérations:: 
* Restrictions sur la dérivation d'énumérations:: 
* Dataclass support:: 
* Sérialisation:: 
* API fonctionnelle:: 
* Déclinaisons d'énumérations:: 
* When to use __new__() vs. __init__(): When to use __new__ vs __init__. 
* How are Enums and Flags different?:: 
* Enum Cookbook:: 
* Dérivations d'EnumType:: 

@end menu

@node Accès par programme aux membres de l'énumération et à leurs attributs,Duplication des membres et des valeurs d'une énumération,,Guide sur l'utilisation d'Enum
@anchor{howto/enum enum-advanced-tutorial}@anchor{2534}@anchor{howto/enum programmatic-access-to-enumeration-members-and-their-attributes}@anchor{4dd0}
@subsection Accès par programme aux membres de l'énumération et à leurs attributs


Il est parfois utile d'accéder aux membres d'une énumération programmatiquement (c'est-à-dire les cas où @code{Color.RED} ne suffit pas car la couleur exacte n'est pas connue au moment de l'écriture du programme). @code{Enum} permet de tels accès :

@example
>>> Color(1)
<Color.RED: 1>
>>> Color(3)
<Color.BLUE: 3>
@end example

Si vous souhaitez accéder aux membres d'une énumération par leur nom, utilisez l'accès par indice :

@example
>>> Color['RED']
<Color.RED: 1>
>>> Color['GREEN']
<Color.GREEN: 2>
@end example

If you have an enum member and need its @code{name} or @code{value}:

@example
>>> member = Color.RED
>>> member.name
'RED'
>>> member.value
1
@end example

@node Duplication des membres et des valeurs d'une énumération,Garantie de valeurs d'énumération uniques,Accès par programme aux membres de l'énumération et à leurs attributs,Guide sur l'utilisation d'Enum
@anchor{howto/enum duplicating-enum-members-and-values}@anchor{4dd1}
@subsection Duplication des membres et des valeurs d'une énumération


Il n'est pas licite d'avoir deux membres d'une énumération avec le même nom :

@example
>>> class Shape(Enum):
...     SQUARE = 2
...     SQUARE = 3
...
Traceback (most recent call last):
...
TypeError: 'SQUARE' already defined as 2
@end example

Cependant, un membre peut avoir d'autres noms qui lui sont associés. Étant donné deux entrées @code{A} et @code{B} avec la même valeur (et @code{A} définie en premier), @code{B} est un synonyme (ou alias) du membre @code{A}. La recherche par valeur de la valeur de @code{A} renvoie le membre @code{A}. La recherche par nom de @code{A} renvoie le membre @code{A}. La recherche par nom de @code{B} renvoie également le membre @code{A} :

@example
>>> class Shape(Enum):
...     SQUARE = 2
...     DIAMOND = 1
...     CIRCLE = 3
...     ALIAS_FOR_SQUARE = 2
...
>>> Shape.SQUARE
<Shape.SQUARE: 2>
>>> Shape.ALIAS_FOR_SQUARE
<Shape.SQUARE: 2>
>>> Shape(2)
<Shape.SQUARE: 2>
@end example

@cartouche
@quotation Note 
tenter de créer un membre portant le même nom qu'un attribut déjà défini (un autre membre, une méthode, etc.) ou tenter de créer un attribut portant le même nom qu'un membre n'est pas autorisé.
@end quotation
@end cartouche

@node Garantie de valeurs d'énumération uniques,Utilisation de valeurs automatiques,Duplication des membres et des valeurs d'une énumération,Guide sur l'utilisation d'Enum
@anchor{howto/enum ensuring-unique-enumeration-values}@anchor{4dd2}
@subsection Garantie de valeurs d'énumération uniques


Par défaut, les énumérations autorisent plusieurs noms comme synonymes pour la même valeur. Lorsque ce comportement n'est pas souhaité, vous pouvez utiliser le décorateur @ref{2539,,unique()} :

@example
>>> from enum import Enum, unique
>>> @@unique
... class Mistake(Enum):
...     ONE = 1
...     TWO = 2
...     THREE = 3
...     FOUR = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
@end example

@node Utilisation de valeurs automatiques,Itération<2>,Garantie de valeurs d'énumération uniques,Guide sur l'utilisation d'Enum
@anchor{howto/enum using-automatic-values}@anchor{4dd3}
@subsection Utilisation de valeurs automatiques


Si la valeur exacte n'est pas importante, vous pouvez utiliser @ref{c8a,,auto} :

@example
>>> from enum import Enum, auto
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> [member.value for member in Color]
[1, 2, 3]
@end example

The values are chosen by @ref{254f,,_generate_next_value_()}, which can be
overridden:

@example
>>> class AutoName(Enum):
...     @@staticmethod
...     def _generate_next_value_(name, start, count, last_values):
...         return name
...
>>> class Ordinal(AutoName):
...     NORTH = auto()
...     SOUTH = auto()
...     EAST = auto()
...     WEST = auto()
...
>>> [member.value for member in Ordinal]
['NORTH', 'SOUTH', 'EAST', 'WEST']
@end example

@cartouche
@quotation Note 
The @ref{254f,,_generate_next_value_()} method must be defined before any members.
@end quotation
@end cartouche

@node Itération<2>,Comparaisons<3>,Utilisation de valeurs automatiques,Guide sur l'utilisation d'Enum
@anchor{howto/enum iteration}@anchor{4dd4}
@subsection Itération


L'itération sur les membres d'une énumération ne fournit pas les synonymes :

@example
>>> list(Shape)
[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
>>> list(Weekday)
[<Weekday.MONDAY: 1>, <Weekday.TUESDAY: 2>, <Weekday.WEDNESDAY: 4>, <Weekday.THURSDAY: 8>, <Weekday.FRIDAY: 16>, <Weekday.SATURDAY: 32>, <Weekday.SUNDAY: 64>]
@end example

Note that the aliases @code{Shape.ALIAS_FOR_SQUARE} and @code{Weekday.WEEKEND} aren't shown.

L'attribut spécial @code{__members__} est un tableau de correspondances ordonné en lecture seule des noms vers les membres. Il inclut tous les noms définis dans l'énumération, y compris les synonymes :

@example
>>> for name, member in Shape.__members__.items():
...     name, member
...
('SQUARE', <Shape.SQUARE: 2>)
('DIAMOND', <Shape.DIAMOND: 1>)
('CIRCLE', <Shape.CIRCLE: 3>)
('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)
@end example

L'attribut @code{__members__} peut être utilisé pour un accès programmatique détaillé aux membres de l'énumération. Par exemple, trouver tous les synonymes :

@example
>>> [name for name, member in Shape.__members__.items() if member.name != name]
['ALIAS_FOR_SQUARE']
@end example

@cartouche
@quotation Note 
Aliases for flags include values with multiple flags set, such as @code{3},
and no flags set, i.e. @code{0}.
@end quotation
@end cartouche

@node Comparaisons<3>,Membres et attributs autorisés des énumérations,Itération<2>,Guide sur l'utilisation d'Enum
@anchor{howto/enum comparisons}@anchor{4dd5}
@subsection Comparaisons


Les membres de l'énumération sont comparés par identité :

@example
>>> Color.RED is Color.RED
True
>>> Color.RED is Color.BLUE
False
>>> Color.RED is not Color.BLUE
True
@end example

Les comparaisons ordonnées entre les valeurs d'énumération `ne sont pas' prises en charge. Les membres d'une énumération ne sont pas des entiers (mais voir @ref{4dd6,,IntEnum} plus bas) :

@example
>>> Color.RED < Color.BLUE
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'Color' and 'Color'
@end example

Les comparaisons d'égalité sont cependant définies :

@example
>>> Color.BLUE == Color.RED
False
>>> Color.BLUE != Color.RED
True
>>> Color.BLUE == Color.BLUE
True
@end example

Les comparaisons avec des valeurs en dehors de l'énumération sont toujours fausses (encore une fois, @ref{ccd,,IntEnum} a été explicitement conçue pour se comporter différemment, voir ci-dessous) :

@example
>>> Color.BLUE == 2
False
@end example

@cartouche
@quotation Avertissement 
It is possible to reload modules -- if a reloaded module contains
enums, they will be recreated, and the new members may not
compare identical/equal to the original members.
@end quotation
@end cartouche

@node Membres et attributs autorisés des énumérations,Restrictions sur la dérivation d'énumérations,Comparaisons<3>,Guide sur l'utilisation d'Enum
@anchor{howto/enum allowed-members-and-attributes-of-enumerations}@anchor{4dd7}
@subsection Membres et attributs autorisés des énumérations


La plupart des exemples ci-dessus utilisent des nombres entiers pour les valeurs d'énumération. L'utilisation d'entiers est rapide et pratique (et fournie par défaut par l'@ref{4dd8,,API fonctionnelle}), mais n'est pas strictement obligatoire. Dans la grande majorité des cas, on ne se soucie pas de la valeur réelle des membres d'une énumération. Mais si la valeur `est' importante, les énumérations peuvent avoir des valeurs arbitraires.

Les énumérations sont des classes Python et peuvent avoir des méthodes ainsi que des méthodes spéciales comme d'habitude. Prenons cette énumération :

@example
>>> class Mood(Enum):
...     FUNKY = 1
...     HAPPY = 3
...
...     def describe(self):
...         # self is the member here
...         return self.name, self.value
...
...     def __str__(self):
...         return 'my custom str! @{0@}'.format(self.value)
...
...     @@classmethod
...     def favorite_mood(cls):
...         # cls here is the enumeration
...         return cls.HAPPY
...
@end example

alors :

@example
>>> Mood.favorite_mood()
<Mood.HAPPY: 3>
>>> Mood.HAPPY.describe()
('HAPPY', 3)
>>> str(Mood.FUNKY)
'my custom str! 1'
@end example

The rules for what is allowed are as follows: names that start and end with
a single underscore are reserved by enum and cannot be used; all other
attributes defined within an enumeration will become members of this
enumeration, with the exception of special methods (@ref{608,,__str__()},
@ref{1f0f,,__add__()}, etc.), descriptors (methods are also descriptors), and
variable names listed in @ref{254d,,_ignore_}.

Note:  if your enumeration defines @ref{56c,,__new__()} and/or @ref{69b,,__init__()},
any value(s) given to the enum member will be passed into those methods.
See @ref{4dd9,,Planet} for an example.

@cartouche
@quotation Note 
The @ref{56c,,__new__()} method, if defined, is used during creation of the Enum
members; it is then replaced by Enum's @ref{56c,,__new__()} which is used after
class creation for lookup of existing members.  See @ref{4dda,,When to use __new__() vs. __init__()} for
more details.
@end quotation
@end cartouche

@node Restrictions sur la dérivation d'énumérations,Dataclass support,Membres et attributs autorisés des énumérations,Guide sur l'utilisation d'Enum
@anchor{howto/enum restricted-enum-subclassing}@anchor{4ddb}
@subsection Restrictions sur la dérivation d'énumérations


Une nouvelle classe @ref{61b,,Enum} doit avoir une classe mère `Enum', jusqu'à un type de données concret, et autant de classes mélangées filles de @ref{a7a,,object} que nécessaire. L'ordre de ces classes mères est :

@example
class EnumName([mix-in, ...,] [data-type,] base-enum):
    pass
@end example

De plus, la dérivation d'une énumération n'est autorisée que si l'énumération ne définit aucun membre. Donc ceci est interdit :

@example
>>> class MoreColor(Color):
...     PINK = 17
...
Traceback (most recent call last):
...
TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'>
@end example

Mais ceci est autorisé :

@example
>>> class Foo(Enum):
...     def some_behavior(self):
...         pass
...
>>> class Bar(Foo):
...     HAPPY = 1
...     SAD = 2
...
@end example

Autoriser la dérivation d'énumérations qui définissent les membres conduirait à une violation de certains invariants importants des types et des instances. D'un autre côté, il est logique de permettre le partage d'un comportement commun entre un groupe d'énumérations (voir @ref{4ddc,,OrderedEnum} pour un exemple).

@node Dataclass support,Sérialisation,Restrictions sur la dérivation d'énumérations,Guide sur l'utilisation d'Enum
@anchor{howto/enum dataclass-support}@anchor{4ddd}@anchor{howto/enum enum-dataclass-support}@anchor{1712}
@subsection Dataclass support


When inheriting from a @ref{1c6,,dataclass},
the @ref{1713,,__repr__()} omits the inherited class' name.  For example:

@example
>>> from dataclasses import dataclass, field
>>> @@dataclass
... class CreatureDataMixin:
...     size: str
...     legs: int
...     tail: bool = field(repr=False, default=True)
...
>>> class Creature(CreatureDataMixin, Enum):
...     BEETLE = 'small', 6
...     DOG = 'medium', 4
...
>>> Creature.DOG
<Creature.DOG: size='medium', legs=4>
@end example

Use the @ref{1c6,,dataclass()} argument @code{repr=False}
to use the standard @ref{7e7,,repr()}.


Modifié dans la version 3.12: Only the dataclass fields are shown in the value area, not the dataclass'
name.


@cartouche
@quotation Note 
Adding @ref{1c6,,dataclass()} decorator to @ref{61b,,Enum}
and its subclasses is not supported. It will not raise any errors,
but it will produce very strange results at runtime, such as members
being equal to each other:

@example
>>> @@dataclass               # don't do this: it does not make any sense
... class Color(Enum):
...    RED = 1
...    BLUE = 2
...
>>> Color.RED is Color.BLUE
False
>>> Color.RED == Color.BLUE  # problem is here: they should not be equal
True
@end example
@end quotation
@end cartouche

@node Sérialisation,API fonctionnelle,Dataclass support,Guide sur l'utilisation d'Enum
@anchor{howto/enum pickling}@anchor{4dde}
@subsection Sérialisation


Les énumérations peuvent être sérialisées et désérialisées :

@example
>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
True
@end example

Les restrictions habituelles pour la sérialisation s'appliquent : les énumérations sérialisables doivent être définies au niveau supérieur d'un module, car la sérialisation nécessite qu'elles puissent être importées à partir de ce module.

@cartouche
@quotation Note 
avec la version 4 du protocole `pickle', il est possible de sérialiser facilement les énumérations imbriquées dans d'autres classes.
@end quotation
@end cartouche

It is possible to modify how enum members are pickled/unpickled by defining
@ref{1540,,__reduce_ex__()} in the enumeration class.  The default method is by-value,
but enums with complicated values may want to use by-name:

@example
>>> import enum
>>> class MyEnum(enum.Enum):
...     __reduce_ex__ = enum.pickle_by_enum_name
@end example

@cartouche
@quotation Note 
Using by-name for flags is not recommended, as unnamed aliases will
not unpickle.
@end quotation
@end cartouche

@node API fonctionnelle,Déclinaisons d'énumérations,Sérialisation,Guide sur l'utilisation d'Enum
@anchor{howto/enum functional-api}@anchor{4dd8}
@subsection API fonctionnelle


La classe @ref{61b,,Enum} est appelable, elle fournit l'API fonctionnelle suivante :

@example
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 1>
>>> list(Animal)
[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
@end example

La sémantique de cette API ressemble à celle des @ref{1c5,,namedtuple}. Le premier argument de l'appel à @ref{61b,,Enum} est le nom de l'énumération.

The second argument is the `source' of enumeration member names.  It can be a
whitespace-separated string of names, a sequence of names, a sequence of
2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to
values.  The last two options enable assigning arbitrary values to
enumerations; the others auto-assign increasing integers starting with 1 (use
the @code{start} parameter to specify a different starting value).  A
new class derived from @ref{61b,,Enum} is returned.  In other words, the above
assignment to @code{Animal} is equivalent to:

@example
>>> class Animal(Enum):
...     ANT = 1
...     BEE = 2
...     CAT = 3
...     DOG = 4
...
@end example

La raison de la valeur par défaut de @code{1} comme numéro de départ et non de @code{0} est que le sens booléen de @code{0} est @code{False}. Or, par défaut, les membres d'une énumération s'évaluent tous à @code{True}.

La sérialisation d'énumérations créées avec l'API fonctionnelle peut être délicat car les détails d'implémentation de la pile d'appels sont utilisés pour essayer de déterminer dans quel module l'énumération est créée (par exemple, cela échoue si vous utilisez une fonction utilitaire dans un module séparé, et peut également ne pas fonctionner sur `IronPython' ou `Jython'). La solution consiste à spécifier explicitement le nom du module comme suit :

@example
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)
@end example

@cartouche
@quotation Avertissement 
si le @code{module} n'est pas fourni et qu'`Enum' ne peut pas le déterminer, les nouveaux membres de l'énumération ne pourront pas être sélectionnés ; pour garder les erreurs au plus près de la source, la sérialisation est désactivée.
@end quotation
@end cartouche

The new pickle protocol 4 also, in some circumstances, relies on
@ref{1eab,,__qualname__} being set to the location where pickle will be able
to find the class.  For example, if the class was made available in class
SomeData in the global scope:

@example
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')
@end example

La signature complète est :

@example
Enum(
    value='NewEnumName',
    names=<...>,
    *,
    module='...',
    qualname='...',
    type=<mixed-in class>,
    start=1,
    )
@end example


@itemize *

@item 
`value': What the new enum class will record as its name.

@item 
`names': The enum members.  This can be a whitespace- or comma-separated string
(values will start at 1 unless otherwise specified):

@example
'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
@end example

ou un itérateur sur des noms :

@example
['RED', 'GREEN', 'BLUE']
@end example

ou un itérateur sur des paires (nom, valeur) :

@example
[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
@end example

ou un tableau de correspondances :

@example
@{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42@}
@end example

@item 
`module': name of module where new enum class can be found.

@item 
`qualname': where in module new enum class can be found.

@item 
`type': type to mix in to new enum class.

@item 
`start': number to start counting at if only names are passed in.
@end itemize


Modifié dans la version 3.5: le paramètre `start' a été ajouté.


@node Déclinaisons d'énumérations,When to use __new__ vs __init__,API fonctionnelle,Guide sur l'utilisation d'Enum
@anchor{howto/enum derived-enumerations}@anchor{4ddf}
@subsection Déclinaisons d'énumérations


@menu
* IntEnum:: 
* StrEnum:: 
* IntFlag:: 
* Flag:: 
* Autres énumérations:: 

@end menu

@node IntEnum,StrEnum,,Déclinaisons d'énumérations
@anchor{howto/enum intenum}@anchor{4dd6}
@subsubsection `IntEnum'


La première variante de @ref{61b,,Enum} fournie est également une sous-classe de @ref{254,,int}. Les membres d'une @ref{ccd,,IntEnum} peuvent être comparés à des entiers ; par extension, des énumérations `IntEnum' de différents types peuvent aussi être comparées :

@example
>>> from enum import IntEnum
>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Request(IntEnum):
...     POST = 1
...     GET = 2
...
>>> Shape == 1
False
>>> Shape.CIRCLE == 1
True
>>> Shape.CIRCLE == Request.POST
True
@end example

Cependant, elles ne peuvent toujours pas être comparées aux énumérations classiques @ref{61b,,Enum} :

@example
>>> class Shape(IntEnum):
...     CIRCLE = 1
...     SQUARE = 2
...
>>> class Color(Enum):
...     RED = 1
...     GREEN = 2
...
>>> Shape.CIRCLE == Color.RED
False
@end example

Les valeurs @ref{ccd,,IntEnum} se comportent comme des entiers, comme vous pouvez vous y attendre :

@example
>>> int(Shape.CIRCLE)
1
>>> ['a', 'b', 'c'][Shape.CIRCLE]
'b'
>>> [i for i in range(Shape.SQUARE)]
[0, 1]
@end example

@node StrEnum,IntFlag,IntEnum,Déclinaisons d'énumérations
@anchor{howto/enum strenum}@anchor{4de0}
@subsubsection `StrEnum'


La deuxième variante de @ref{61b,,Enum} fournie est également une sous-classe de @ref{435,,str}. Les membres d'une @ref{605,,StrEnum} peuvent être comparés à des chaînes ; par extension, les énumérations `StrEnum' de différents types peuvent également être comparées les unes aux autres.


Ajouté dans la version 3.11.


@node IntFlag,Flag,StrEnum,Déclinaisons d'énumérations
@anchor{howto/enum intflag}@anchor{4de1}
@subsubsection `IntFlag'


La variante suivante fournie d'@ref{61b,,Enum} est @ref{2280,,IntFlag}, également basée sur @ref{254,,int}. La différence étant que les membres @ref{2280,,IntFlag} peuvent être combinés à l'aide des opérateurs bit-à-bit (&, |, ^, ~) et le résultat est toujours un membre @ref{2280,,IntFlag}, si possible. Comme @ref{ccd,,IntEnum}, les membres de @ref{2280,,IntFlag} sont aussi des entiers et peuvent être utilisés partout où on utilise un @ref{254,,int}.

@cartouche
@quotation Note 
toute opération sur un membre @ref{2280,,IntFlag}, en dehors des opérations bit-à-bit, fait perdre l'appartenance à @ref{2280,,IntFlag}.

Les opérations bit-à-bit qui entraînent des valeurs @ref{2280,,IntFlag} invalides font perdre l'appartenance à @ref{2280,,IntFlag}. Voir @ref{60f,,FlagBoundary} pour plus de détails.
@end quotation
@end cartouche


Ajouté dans la version 3.6.



Modifié dans la version 3.11.


Classe exemple dérivée d'@code{Intflag} :

@example
>>> from enum import IntFlag
>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...
>>> Perm.R | Perm.W
<Perm.R|W: 6>
>>> Perm.R + Perm.W
6
>>> RW = Perm.R | Perm.W
>>> Perm.R in RW
True
@end example

Il est également possible de nommer les combinaisons :

@example
>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...     RWX = 7
...
>>> Perm.RWX
<Perm.RWX: 7>
>>> ~Perm.RWX
<Perm: 0>
>>> Perm(7)
<Perm.RWX: 7>
@end example

@cartouche
@quotation Note 
les combinaisons nommées sont considérées être des synonymes (ou alias). Les synonymes n'apparaissent pas dans une itération, mais peuvent être renvoyés à partir de recherches par valeur.
@end quotation
@end cartouche


Modifié dans la version 3.11.


Une autre différence importante entre @ref{2280,,IntFlag} et @ref{61b,,Enum} est que si aucun indicateur n'est défini (la valeur est 0), son évaluation booléenne est @ref{b25,,False} :

@example
>>> Perm.R & Perm.X
<Perm: 0>
>>> bool(Perm.R & Perm.X)
False
@end example

Comme les membres d'une @ref{2280,,IntFlag} sont aussi des sous-classes de @ref{254,,int}, ils peuvent être combinés avec eux (mais peuvent alors perdre l'appartenance à @ref{2280,,IntFlag}) :

@example
>>> Perm.X | 4
<Perm.R|X: 5>

>>> Perm.X + 8
9
@end example

@cartouche
@quotation Note 
l'opérateur de négation, @code{~}, renvoie toujours un membre @ref{2280,,IntFlag} avec une valeur positive :

@example
>>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
True
@end example
@end quotation
@end cartouche

On peut aussi itérer sur les membres d'une @ref{2280,,IntFlag} :

@example
>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]
@end example


Ajouté dans la version 3.11.


@node Flag,Autres énumérations,IntFlag,Déclinaisons d'énumérations
@anchor{howto/enum flag}@anchor{4de2}
@subsubsection `Flag'


La dernière variante est @ref{60e,,Flag}. Comme @ref{2280,,IntFlag}, les membres de @ref{60e,,Flag} peuvent être combinés à l'aide des opérateurs bit-à-bit (&, |, ^, ~). Contrairement à @ref{2280,,IntFlag}, ils ne peuvent être combinés ni comparés à aucune autre énumération @ref{60e,,Flag}, ni à @ref{254,,int}. Bien qu'il soit possible de spécifier les valeurs directement, il est recommandé d'utiliser @ref{c8a,,auto} comme valeur et de laisser @ref{60e,,Flag} sélectionner une valeur appropriée.


Ajouté dans la version 3.6.


Comme pour @ref{2280,,IntFlag}, si une combinaison de membres @ref{60e,,Flag} entraîne qu'aucun indicateur n'est défini, l'évaluation booléenne est @ref{b25,,False} :

@example
>>> from enum import Flag, auto
>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.RED & Color.GREEN
<Color: 0>
>>> bool(Color.RED & Color.GREEN)
False
@end example

Individual flags should have values that are powers of two (1, 2, 4, 8, ...),
while combinations of flags will not:

@example
>>> class Color(Flag):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...     WHITE = RED | BLUE | GREEN
...
>>> Color.WHITE
<Color.WHITE: 7>
@end example

Donner un nom à la condition « aucun indicateur défini » ne change pas sa valeur booléenne :

@example
>>> class Color(Flag):
...     BLACK = 0
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> bool(Color.BLACK)
False
@end example

On peut aussi itérer sur les membres d'une @ref{60e,,Flag} :

@example
>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]
@end example


Ajouté dans la version 3.11.


@cartouche
@quotation Note 
pour la majorité du code nouveau, @ref{61b,,Enum} et @ref{60e,,Flag} sont fortement recommandées, car @ref{ccd,,IntEnum} et @ref{2280,,IntFlag} brisent certaines promesses sémantiques d'une énumération (en pouvant être comparées à des entiers et donc, par transitivité, à d'autres énumérations sans rapport). @ref{ccd,,IntEnum} et @ref{2280,,IntFlag} ne doivent être utilisées que dans les cas où @ref{61b,,Enum} et @ref{60e,,Flag} ne suffisent pas ; par exemple, lorsque des constantes entières sont remplacées par des énumérations, ou pour l'interopérabilité avec d'autres systèmes.
@end quotation
@end cartouche

@node Autres énumérations,,Flag,Déclinaisons d'énumérations
@anchor{howto/enum others}@anchor{4de3}
@subsubsection Autres énumérations


Bien que @ref{ccd,,IntEnum} fasse partie du module @ref{55,,enum}, il serait très simple de l'implémenter indépendamment :

@example
class IntEnum(int, ReprEnum):   # or Enum instead of ReprEnum
    pass
@end example

This demonstrates how similar derived enumerations can be defined; for example
a @code{FloatEnum} that mixes in @ref{2eb,,float} instead of @ref{254,,int}.

Quelques règles :


@enumerate 

@item 
When subclassing @ref{61b,,Enum}, mix-in types must appear before the
@ref{61b,,Enum} class itself in the sequence of bases, as in the @ref{ccd,,IntEnum}
example above.

@item 
Les types mélangés doivent pouvoir être sous-classés. Par exemple, @ref{451,,bool} et @ref{930,,range} ne peuvent pas être sous-classés et génèrent une erreur lors de la création d'une énumération s'ils sont utilisés comme type de mélange.

@item 
Alors qu'@ref{61b,,Enum} peut avoir des membres de n'importe quel type, une fois que vous avez mélangé un type supplémentaire, tous les membres doivent avoir des valeurs de ce type, par exemple @ref{254,,int} ci-dessus. Cette restriction ne s'applique pas aux classes de mélange qui ajoutent uniquement des méthodes et ne spécifient pas d'autre type.

@item 
When another data type is mixed in, the @ref{2548,,value} attribute is `not the
same' as the enum member itself, although it is equivalent and will compare
equal.

@item 
A @code{data type} is a mixin that defines @ref{56c,,__new__()}, or a
@ref{1c6,,dataclass}

@item 
%-style formatting:  @code{%s} and @code{%r} call the @ref{61b,,Enum} class's
@ref{608,,__str__()} and @ref{607,,__repr__()} respectively; other codes (such as
@code{%i} or @code{%h} for IntEnum) treat the enum member as its mixed-in type.

@item 
@ref{997,,Formatted string literals}, @ref{60c,,str.format()},
and @ref{60a,,format()} will use the enum's @ref{608,,__str__()} method.
@end enumerate

@cartouche
@quotation Note 
Because @ref{ccd,,IntEnum}, @ref{2280,,IntFlag}, and @ref{605,,StrEnum} are
designed to be drop-in replacements for existing constants, their
@ref{608,,__str__()} method has been reset to their data types'
@ref{608,,__str__()} method.
@end quotation
@end cartouche

@node When to use __new__ vs __init__,How are Enums and Flags different?,Déclinaisons d'énumérations,Guide sur l'utilisation d'Enum
@anchor{howto/enum new-vs-init}@anchor{4dda}@anchor{howto/enum when-to-use-new-vs-init}@anchor{4de4}
@subsection When to use @code{__new__()} vs. @code{__init__()}


@ref{56c,,__new__()} must be used whenever you want to customize the actual value of
the @ref{61b,,Enum} member.  Any other modifications may go in either
@ref{56c,,__new__()} or @ref{69b,,__init__()}, with @ref{69b,,__init__()} being preferred.

Par exemple, si vous souhaitez passer plusieurs éléments au constructeur, mais que vous souhaitez qu'un seul d'entre eux soit la valeur :

@example
>>> class Coordinate(bytes, Enum):
...     """
...     Coordinate with binary codes that can be indexed by the int code.
...     """
...     def __new__(cls, value, label, unit):
...         obj = bytes.__new__(cls, [value])
...         obj._value_ = value
...         obj.label = label
...         obj.unit = unit
...         return obj
...     PX = (0, 'P.X', 'km')
...     PY = (1, 'P.Y', 'km')
...     VX = (2, 'V.X', 'km/s')
...     VY = (3, 'V.Y', 'km/s')
...

>>> print(Coordinate['PY'])
Coordinate.PY

>>> print(Coordinate(3))
Coordinate.VY
@end example

@cartouche
@quotation Avertissement 
`Do not' call @code{super().__new__()}, as the lookup-only @code{__new__} is the one
that is found; instead, use the data type directly.
@end quotation
@end cartouche

@menu
* Approfondissements:: 

@end menu

@node Approfondissements,,,When to use __new__ vs __init__
@anchor{howto/enum finer-points}@anchor{4de5}
@subsubsection Approfondissements


@menu
* Noms de la forme __dunder__ disponibles: Noms de la forme __dunder__ disponibles<2>. 
* Noms de la forme _sunder_ disponibles: Noms de la forme _sunder_ disponibles<2>. 
* _Private__names:: 
* Types des membres d'une Enum:: 
* Création de membres mélangés avec d'autres types de données:: 
* Valeur booléenne des classes et membres Enum:: 
* Méthodes dans les classes Enum:: 
* Combinaisons de membres de Flag:: 
* Précisions sur Flag et IntFlag:: 

@end menu

@node Noms de la forme __dunder__ disponibles<2>,Noms de la forme _sunder_ disponibles<2>,,Approfondissements
@anchor{howto/enum supported-dunder-names}@anchor{4de6}
@subsubsection Noms de la forme @code{__dunder__} disponibles


@ref{2543,,__members__} is a read-only ordered mapping of @code{member_name}:@code{member}
items.  It is only available on the class.

@ref{56c,,__new__()}, if specified, must create and return the enum members; it is
also a very good idea to set the member's @ref{254b,,_value_} appropriately.  Once
all the members are created it is no longer used.

@node Noms de la forme _sunder_ disponibles<2>,_Private__names,Noms de la forme __dunder__ disponibles<2>,Approfondissements
@anchor{howto/enum supported-sunder-names}@anchor{4de7}
@subsubsection Noms de la forme @code{_sunder_} disponibles



@itemize -

@item 
@ref{254a,,_name_} -- name of the member

@item 
@ref{254b,,_value_} -- value of the member; can be set in @code{__new__}

@item 
@ref{2552,,_missing_()} -- a lookup function used when a value is not found;
may be overridden

@item 
@ref{254d,,_ignore_} -- a list of names, either as a @ref{5fc,,list} or a
@ref{435,,str}, that will not be transformed into members, and will be removed
from the final class

@item 
@ref{254f,,_generate_next_value_()} -- used to get an appropriate value for
an enum member; may be overridden

@item 
@ref{2545,,_add_alias_()} -- adds a new name as an alias to an existing
member.

@item 
@ref{2546,,_add_value_alias_()} -- adds a new value as an alias to an
existing member.  See @ref{4de8,,MultiValueEnum} for an example.

@cartouche
@quotation Note 
For standard @ref{61b,,Enum} classes the next value chosen is the highest
value seen incremented by one.

For @ref{60e,,Flag} classes the next value chosen will be the next highest
power-of-two.
@end quotation
@end cartouche


Modifié dans la version 3.13: Prior versions would use the last seen value instead of the highest value.

@end itemize


Ajouté dans la version 3.6: @code{_missing_}, @code{_order_}, @code{_generate_next_value_}



Ajouté dans la version 3.7: @code{_ignore_}



Ajouté dans la version 3.13: @code{_add_alias_}, @code{_add_value_alias_}


To help keep Python 2 / Python 3 code in sync an @ref{254c,,_order_} attribute can
be provided.  It will be checked against the actual order of the enumeration
and raise an error if the two do not match:

@example
>>> class Color(Enum):
...     _order_ = 'RED GREEN BLUE'
...     RED = 1
...     BLUE = 3
...     GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
  ['RED', 'BLUE', 'GREEN']
  ['RED', 'GREEN', 'BLUE']
@end example

@cartouche
@quotation Note 
In Python 2 code the @ref{254c,,_order_} attribute is necessary as definition
order is lost before it can be recorded.
@end quotation
@end cartouche

@node _Private__names,Types des membres d'une Enum,Noms de la forme _sunder_ disponibles<2>,Approfondissements
@anchor{howto/enum private-names}@anchor{4de9}
@subsubsection `_Private__names'


@ref{1c48,,Les noms privés} ne sont pas convertis en membres de l'énumération, mais restent des attributs normaux.


Modifié dans la version 3.11.


@node Types des membres d'une Enum,Création de membres mélangés avec d'autres types de données,_Private__names,Approfondissements
@anchor{howto/enum enum-member-type}@anchor{4dea}
@subsubsection Types des membres d'une @code{Enum}


Enum members are instances of their enum class, and are normally accessed as
@code{EnumClass.member}.  In certain situations, such as writing custom enum
behavior, being able to access one member directly from another is useful,
and is supported; however, in order to avoid name clashes between member names
and attributes/methods from mixed-in classes, upper-case names are strongly
recommended.


Modifié dans la version 3.5.


@node Création de membres mélangés avec d'autres types de données,Valeur booléenne des classes et membres Enum,Types des membres d'une Enum,Approfondissements
@anchor{howto/enum creating-members-that-are-mixed-with-other-data-types}@anchor{4deb}
@subsubsection Création de membres mélangés avec d'autres types de données


Lorsque vous dérivez d'autres types de données, tels que @ref{254,,int} ou @ref{435,,str}, avec une @ref{61b,,Enum}, toutes les valeurs après @code{=} sont passées au constructeur de ce type de données. Par exemple :

@example
>>> class MyEnum(IntEnum):      # help(int) -> int(x, base=10) -> integer
...     example = '11', 16      # so x='11' and base=16
...
>>> MyEnum.example.value        # and hex(11) is...
17
@end example

@node Valeur booléenne des classes et membres Enum,Méthodes dans les classes Enum,Création de membres mélangés avec d'autres types de données,Approfondissements
@anchor{howto/enum boolean-value-of-enum-classes-and-members}@anchor{4dec}
@subsubsection Valeur booléenne des classes et membres @code{Enum}


Les classes `Enum' mélangées avec des types non-@ref{61b,,Enum} (tels que @ref{254,,int}, @ref{435,,str}, etc.) sont évaluées selon les règles du type mélangé ; sinon, tous les membres sont évalués comme @ref{bfb,,True}. Pour que l'évaluation booléenne de votre propre énumération dépende de la valeur du membre, ajoutez ce qui suit à votre classe :

@example
def __bool__(self):
    return bool(self.value)
@end example

Les classes simples @ref{61b,,Enum} sont toujours évaluées comme @ref{bfb,,True}.

@node Méthodes dans les classes Enum,Combinaisons de membres de Flag,Valeur booléenne des classes et membres Enum,Approfondissements
@anchor{howto/enum enum-classes-with-methods}@anchor{4ded}
@subsubsection Méthodes dans les classes @code{Enum}


Si vous dotez votre sous-classe énumération de méthodes supplémentaires, comme la classe @ref{4dd9,,Planet} ci-dessous, ces méthodes apparaissent dans le @ref{61d,,dir()} des membres, mais pas dans celui de la classe :

@example
>>> dir(Planet)                         
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
>>> dir(Planet.EARTH)                   
['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']
@end example

@node Combinaisons de membres de Flag,Précisions sur Flag et IntFlag,Méthodes dans les classes Enum,Approfondissements
@anchor{howto/enum combining-members-of-flag}@anchor{4dee}
@subsubsection Combinaisons de membres de @code{Flag}


L'itération sur une combinaison de membres @ref{60e,,Flag} ne renvoie que les membres dont un seul bit est à 1 :

@example
>>> class Color(Flag):
...     RED = auto()
...     GREEN = auto()
...     BLUE = auto()
...     MAGENTA = RED | BLUE
...     YELLOW = RED | GREEN
...     CYAN = GREEN | BLUE
...
>>> Color(3)  # named combination
<Color.YELLOW: 3>
>>> Color(7)      # not named combination
<Color.RED|GREEN|BLUE: 7>
@end example

@node Précisions sur Flag et IntFlag,,Combinaisons de membres de Flag,Approfondissements
@anchor{howto/enum flag-and-intflag-minutia}@anchor{4def}
@subsubsection Précisions sur @code{Flag} et @code{IntFlag}


En utilisant l'extrait suivant pour nos exemples :

@example
>>> class Color(IntFlag):
...     BLACK = 0
...     RED = 1
...     GREEN = 2
...     BLUE = 4
...     PURPLE = RED | BLUE
...     WHITE = RED | GREEN | BLUE
...
@end example

ce qui suit est vrai :


@itemize -

@item 
les membres dont un seul bit est à 1 sont canoniques ;

@item 
ceux qui ont plusieurs bits à 1 ou aucun bit à 1 sont des synonymes ;

@item 
seuls les membres canoniques sont renvoyés pendant une itération :

@example
>>> list(Color.WHITE)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
@end example

@item 
la négation d'un membre ou d'une composition de membres renvoie un nouveau membre (ou composition de membres) avec la valeur entière positive correspondante :

@example
>>> Color.BLUE
<Color.BLUE: 4>

>>> ~Color.BLUE
<Color.RED|GREEN: 3>
@end example

@item 
les noms des pseudo-membres sont construits à partir des noms de leurs membres :

@example
>>> (Color.RED | Color.GREEN).name
'RED|GREEN'

>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...
>>> (Perm.R & Perm.W).name is None  # effectively Perm(0)
True
@end example

@item 
les membres avec plusieurs bits à 1 (des alias) peuvent être renvoyés par les opérations :

@example
>>> Color.RED | Color.BLUE
<Color.PURPLE: 5>

>>> Color(7)  # or Color(-1)
<Color.WHITE: 7>

>>> Color(0)
<Color.BLACK: 0>
@end example

@item 
pour la vérification d'appartenance, les membres dont la valeur est 0 sont toujours considérés comme étant membres :

@example
>>> Color.BLACK in Color.WHITE
True
@end example

sinon, seulement si tous les bits à 1 d'un membre sont aussi à 1 dans l'autre membre, renvoie `True' :

@example
>>> Color.PURPLE in Color.WHITE
True

>>> Color.GREEN in Color.PURPLE
False
@end example
@end itemize

Il existe un nouveau mécanisme de délimitation qui contrôle la façon dont les bits hors plage/invalides sont gérés : @code{STRICT}, @code{CONFORM}, @code{EJECT} et @code{KEEP} :


@itemize *

@item 
`STRICT' --> lève une exception lorsqu'on lui présente des valeurs invalides

@item 
`CONFORM' --> ignore les bits invalides

@item 
`EJECT' --> la valeur présentée perd le statut de membre et devient un entier normal

@item 
`KEEP' --> garde les bits supplémentaires


@itemize -

@item 
garde le statut de membre avec les bits supplémentaires

@item 
les bits supplémentaires ne sont pas produits dans une itération

@item 
les bits supplémentaires ne sont pas représentés par `repr()' et `str()'
@end itemize
@end itemize

La valeur par défaut pour `Flag' est @code{STRICT}, la valeur par défaut pour @code{IntFlag} est @code{EJECT} et la valeur par défaut pour @code{_convert_} est @code{KEEP} (voir @code{ssl.Options} pour un exemple de cas où @code{KEEP} est nécessaire).

@node How are Enums and Flags different?,Enum Cookbook,When to use __new__ vs __init__,Guide sur l'utilisation d'Enum
@anchor{howto/enum enum-class-differences}@anchor{2536}@anchor{howto/enum how-are-enums-and-flags-different}@anchor{4df0}
@subsection How are Enums and Flags different?


Les énumérations ont une métaclasse personnalisée qui modifie de nombreux aspects des classes dérivées d'@ref{61b,,Enum} et de leurs instances (membres).

@menu
* Classes Enum:: 
* Flag Classes:: 
* Membres d'une Enum (les instances): Membres d'une Enum les instances. 
* Flag Members:: 

@end menu

@node Classes Enum,Flag Classes,,How are Enums and Flags different?
@anchor{howto/enum enum-classes}@anchor{4df1}
@subsubsection Classes `Enum'


The @ref{1e2,,EnumType} metaclass is responsible for providing the
@ref{1ee0,,__contains__()}, @ref{1ee9,,__dir__()}, @ref{1ede,,__iter__()} and other methods that
allow one to do things with an @ref{61b,,Enum} class that fail on a typical
class, such as @code{list(Color)} or @code{some_enum_var in Color}.  @ref{1e2,,EnumType} is
responsible for ensuring that various other methods on the final @ref{61b,,Enum}
class are correct (such as @ref{56c,,__new__()}, @ref{1459,,__getnewargs__()},
@ref{608,,__str__()} and @ref{607,,__repr__()}).

@node Flag Classes,Membres d'une Enum les instances,Classes Enum,How are Enums and Flags different?
@anchor{howto/enum flag-classes}@anchor{4df2}
@subsubsection Flag Classes


Flags have an expanded view of aliasing: to be canonical, the value of a flag
needs to be a power-of-two value, and not a duplicate name.  So, in addition to the
@ref{61b,,Enum} definition of alias, a flag with no value (a.k.a. @code{0}) or with more than one
power-of-two value (e.g. @code{3}) is considered an alias.

@node Membres d'une Enum les instances,Flag Members,Flag Classes,How are Enums and Flags different?
@anchor{howto/enum enum-members-aka-instances}@anchor{4df3}
@subsubsection Membres d'une `Enum' (les instances)


The most interesting thing about enum members is that they are singletons.
@ref{1e2,,EnumType} creates them all while it is creating the enum class itself,
and then puts a custom @ref{56c,,__new__()} in place to ensure that no new ones are
ever instantiated by returning only the existing member instances.

@node Flag Members,,Membres d'une Enum les instances,How are Enums and Flags different?
@anchor{howto/enum flag-members}@anchor{4df4}
@subsubsection Flag Members


Flag members can be iterated over just like the @ref{60e,,Flag} class, and only the
canonical members will be returned.  For example:

@example
>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
@end example

(Note that @code{BLACK}, @code{PURPLE}, and @code{WHITE} do not show up.)

Inverting a flag member returns the corresponding positive value,
rather than a negative value --- for example:

@example
>>> ~Color.RED
<Color.GREEN|BLUE: 6>
@end example

Flag members have a length corresponding to the number of power-of-two values
they contain.  For example:

@example
>>> len(Color.PURPLE)
2
@end example

@node Enum Cookbook,Dérivations d'EnumType,How are Enums and Flags different?,Guide sur l'utilisation d'Enum
@anchor{howto/enum enum-cookbook}@anchor{2535}@anchor{howto/enum id2}@anchor{4df5}
@subsection Enum Cookbook


@ref{61b,,Enum}, @ref{ccd,,IntEnum}, @ref{605,,StrEnum}, @ref{60e,,Flag} et @ref{2280,,IntFlag} sont censées couvrir la majorité des cas d'utilisation, mais elles ne peuvent pas tout couvrir. Voici quelques recettes pour différents types d'énumérations qui peuvent être utilisées directement, ou pour servir d'exemples afin de créer les vôtres.

@menu
* Omission de valeurs:: 
* Énumération ordonnée:: 
* Énumération sans doublon:: 
* MultiValueEnum:: 
* Planète:: 
* Intervalle de temps:: 

@end menu

@node Omission de valeurs,Énumération ordonnée,,Enum Cookbook
@anchor{howto/enum omitting-values}@anchor{4df6}
@subsubsection Omission de valeurs


Dans de nombreux cas d'utilisation, on ne se soucie pas de la valeur réelle d'une énumération. Il existe plusieurs manières de définir ce type d'énumération simple :


@itemize -

@item 
utilisez des instances d'@ref{c8a,,auto} pour la valeur ;

@item 
utilisez des instances d'@ref{a7a,,object} comme valeur ;

@item 
utilisez une chaîne de caractères descriptive comme valeur ;

@item 
use a tuple as the value and a custom @ref{56c,,__new__()} to replace the
tuple with an @ref{254,,int} value
@end itemize

L'utilisation de l'une de ces méthodes signifie au lecteur que ces valeurs ne sont pas importantes et permet également d'ajouter, de supprimer ou de réorganiser des membres sans avoir à renuméroter les autres membres.

@menu
* Utilisation d'auto:: 
* Utilisation d'object:: 
* Utilisation d'une chaîne de caractères descriptive:: 
* Using a custom __new__(): Using a custom __new__. 

@end menu

@node Utilisation d'auto,Utilisation d'object,,Omission de valeurs
@anchor{howto/enum using-auto}@anchor{4df7}
@subsubsection Utilisation d'@code{auto}


Voici un exemple où nous utilisons @ref{c8a,,auto} :

@example
>>> class Color(Enum):
...     RED = auto()
...     BLUE = auto()
...     GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN: 3>
@end example

@node Utilisation d'object,Utilisation d'une chaîne de caractères descriptive,Utilisation d'auto,Omission de valeurs
@anchor{howto/enum using-object}@anchor{4df8}
@subsubsection Utilisation d'@code{object}


Voici un exemple où nous utilisons @ref{a7a,,object} :

@example
>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...
>>> Color.GREEN                         
<Color.GREEN: <object object at 0x...>>
@end example

This is also a good example of why you might want to write your own
@ref{607,,__repr__()}:

@example
>>> class Color(Enum):
...     RED = object()
...     GREEN = object()
...     BLUE = object()
...     def __repr__(self):
...         return "<%s.%s>" % (self.__class__.__name__, self._name_)
...
>>> Color.GREEN
<Color.GREEN>
@end example

@node Utilisation d'une chaîne de caractères descriptive,Using a custom __new__,Utilisation d'object,Omission de valeurs
@anchor{howto/enum using-a-descriptive-string}@anchor{4df9}
@subsubsection Utilisation d'une chaîne de caractères descriptive


Voici un exemple où nous utilisons une chaîne de caractères :

@example
>>> class Color(Enum):
...     RED = 'stop'
...     GREEN = 'go'
...     BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN: 'go'>
@end example

@node Using a custom __new__,,Utilisation d'une chaîne de caractères descriptive,Omission de valeurs
@anchor{howto/enum using-a-custom-new}@anchor{4dfa}
@subsubsection Using a custom @code{__new__()}


Using an auto-numbering @ref{56c,,__new__()} would look like:

@example
>>> class AutoNumber(Enum):
...     def __new__(cls):
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...
>>> class Color(AutoNumber):
...     RED = ()
...     GREEN = ()
...     BLUE = ()
...
>>> Color.GREEN
<Color.GREEN: 2>
@end example

Pour créer une @code{AutoNumber} plus générale, ajoutons @code{*args} à la signature :

@example
>>> class AutoNumber(Enum):
...     def __new__(cls, *args):      # this is the only change from above
...         value = len(cls.__members__) + 1
...         obj = object.__new__(cls)
...         obj._value_ = value
...         return obj
...
@end example

Ensuite, lorsque nous héritons de @code{AutoNumber}, nous pouvons écrire notre propre @code{__init__} pour gérer les arguments supplémentaires :

@example
>>> class Swatch(AutoNumber):
...     def __init__(self, pantone='unknown'):
...         self.pantone = pantone
...     AUBURN = '3497'
...     SEA_GREEN = '1246'
...     BLEACHED_CORAL = () # New color, no Pantone code yet!
...
>>> Swatch.SEA_GREEN
<Swatch.SEA_GREEN: 2>
>>> Swatch.SEA_GREEN.pantone
'1246'
>>> Swatch.BLEACHED_CORAL.pantone
'unknown'
@end example

@cartouche
@quotation Note 
The @ref{56c,,__new__()} method, if defined, is used during creation of the Enum
members; it is then replaced by Enum's @ref{56c,,__new__()} which is used after
class creation for lookup of existing members.
@end quotation
@end cartouche

@cartouche
@quotation Avertissement 
`Do not' call @code{super().__new__()}, as the lookup-only @code{__new__} is the one
that is found; instead, use the data type directly -- e.g.:

@example
obj = int.__new__(cls, value)
@end example
@end quotation
@end cartouche

@node Énumération ordonnée,Énumération sans doublon,Omission de valeurs,Enum Cookbook
@anchor{howto/enum orderedenum}@anchor{4ddc}
@subsubsection Énumération ordonnée


Voici une énumération ordonnée qui n'est pas basée sur @ref{ccd,,IntEnum} et maintient donc les invariants normaux d'@ref{61b,,Enum} (comme ne pas pouvoir être comparée à d'autres énumérations) :

@example
>>> class OrderedEnum(Enum):
...     def __ge__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value >= other.value
...         return NotImplemented
...     def __gt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value > other.value
...         return NotImplemented
...     def __le__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value <= other.value
...         return NotImplemented
...     def __lt__(self, other):
...         if self.__class__ is other.__class__:
...             return self.value < other.value
...         return NotImplemented
...
>>> class Grade(OrderedEnum):
...     A = 5
...     B = 4
...     C = 3
...     D = 2
...     F = 1
...
>>> Grade.C < Grade.A
True
@end example

@node Énumération sans doublon,MultiValueEnum,Énumération ordonnée,Enum Cookbook
@anchor{howto/enum duplicatefreeenum}@anchor{4dfb}
@subsubsection Énumération sans doublon


Raises an error if a duplicate member value is found instead of creating an
alias:

@example
>>> class DuplicateFreeEnum(Enum):
...     def __init__(self, *args):
...         cls = self.__class__
...         if any(self.value == e.value for e in cls):
...             a = self.name
...             e = cls(self.value).name
...             raise ValueError(
...                 "aliases not allowed in DuplicateFreeEnum:  %r --> %r"
...                 % (a, e))
...
>>> class Color(DuplicateFreeEnum):
...     RED = 1
...     GREEN = 2
...     BLUE = 3
...     GRENE = 2
...
Traceback (most recent call last):
  ...
ValueError: aliases not allowed in DuplicateFreeEnum:  'GRENE' --> 'GREEN'
@end example

@cartouche
@quotation Note 
c'est un exemple utile de dérivation d'`Enum' pour ajouter ou modifier d'autres comportements ainsi que pour interdire les synonymes. Si le seul changement souhaité est l'interdiction des synonymes, le décorateur @ref{2539,,unique()} peut être utilisé à la place.
@end quotation
@end cartouche

@node MultiValueEnum,Planète,Énumération sans doublon,Enum Cookbook
@anchor{howto/enum multivalueenum}@anchor{4de8}
@subsubsection MultiValueEnum


Supports having more than one value per member:

@example
>>> class MultiValueEnum(Enum):
...     def __new__(cls, value, *values):
...         self = object.__new__(cls)
...         self._value_ = value
...         for v in values:
...             self._add_value_alias_(v)
...         return self
...
>>> class DType(MultiValueEnum):
...     float32 = 'f', 8
...     double64 = 'd', 9
...
>>> DType('f')
<DType.float32: 'f'>
>>> DType(9)
<DType.double64: 'd'>
@end example

@node Planète,Intervalle de temps,MultiValueEnum,Enum Cookbook
@anchor{howto/enum planet}@anchor{4dd9}
@subsubsection Planète


If @ref{56c,,__new__()} or @ref{69b,,__init__()} is defined, the value of the enum member
will be passed to those methods:

@example
>>> class Planet(Enum):
...     MERCURY = (3.303e+23, 2.4397e6)
...     VENUS   = (4.869e+24, 6.0518e6)
...     EARTH   = (5.976e+24, 6.37814e6)
...     MARS    = (6.421e+23, 3.3972e6)
...     JUPITER = (1.9e+27,   7.1492e7)
...     SATURN  = (5.688e+26, 6.0268e7)
...     URANUS  = (8.686e+25, 2.5559e7)
...     NEPTUNE = (1.024e+26, 2.4746e7)
...     def __init__(self, mass, radius):
...         self.mass = mass       # in kilograms
...         self.radius = radius   # in meters
...     @@property
...     def surface_gravity(self):
...         # universal gravitational constant  (m3 kg-1 s-2)
...         G = 6.67300E-11
...         return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129
@end example

@node Intervalle de temps,,Planète,Enum Cookbook
@anchor{howto/enum enum-time-period}@anchor{254e}@anchor{howto/enum timeperiod}@anchor{4dfc}
@subsubsection Intervalle de temps


An example to show the @ref{254d,,_ignore_} attribute in use:

@example
>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
...     "different lengths of time"
...     _ignore_ = 'Period i'
...     Period = vars()
...     for i in range(367):
...         Period['day_%d' % i] = i
...
>>> list(Period)[:2]
[<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
>>> list(Period)[-2:]
[<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]
@end example

@node Dérivations d'EnumType,,Enum Cookbook,Guide sur l'utilisation d'Enum
@anchor{howto/enum enumtype-examples}@anchor{253c}@anchor{howto/enum subclassing-enumtype}@anchor{4dfd}
@subsection Dérivations d'`EnumType'


Alors que la plupart des besoins d'énumérations peuvent être satisfaits en sous-classant @ref{61b,,Enum}, avec des décorateurs de classe ou des fonctions personnalisées, @ref{1e2,,EnumType} peut être dérivée pour créer des énumérations vraiment différentes.

@node Guide pratique programmation fonctionnelle,Tutoriel sur la journalisation,Guide sur l'utilisation d'Enum,Les HOWTOs de Python
@anchor{howto/functional doc}@anchor{4dfe}@anchor{howto/functional functional-howto}@anchor{4dff}@anchor{howto/functional functional-programming-howto}@anchor{4e00}
@section Guide pratique : programmation fonctionnelle


@*Auteur: 
A. M. Kuchling


@*Version: 
0.32


Dans ce document, nous allons faire un tour des fonctionnalités de Python adaptées à la réalisation d'un programme dans un style fonctionnel. Après une introduction à la programmation fonctionnelle, nous aborderons des outils tels que les @ref{1aa,,iterator}s et les @ref{104a,,generator}s ainsi que les modules @ref{80,,itertools} et @ref{5e,,functools}.

@menu
* Introduction: Introduction<14>. 
* Itérateurs: Itérateurs<3>. 
* Expressions génératrices et compréhension de listes:: 
* Générateurs: Générateurs<2>. 
* Fonctions natives: Fonctions natives<3>. 
* Le module itertools:: 
* Le module functools:: 
* Expressions lambda et fonctions courtes:: 
* Historique des modifications et remerciements:: 
* Références: Références<3>. 

@end menu

@node Introduction<14>,Itérateurs<3>,,Guide pratique programmation fonctionnelle
@anchor{howto/functional introduction}@anchor{4e01}
@subsection Introduction


Cette section détaille les fondamentaux de la programmation fonctionnelle. Si seules les fonctionnalités de Python vous intéressent, vous pouvez sauter cette partie et lire la section suivante sur les @ref{4e02,,Itérateurs}.

Les langages de programmation permettent de traiter des problèmes selon différentes approches :


@itemize *

@item 
la plupart des langages de programmation suivent une logique `procédurale' : les programmes sont constitués de listes d'instructions qui détaillent les opérations que l'ordinateur doit appliquer aux entrées du programme. C, Pascal ou encore les interpréteurs de commandes Unix sont des langages procéduraux ;

@item 
les langages `déclaratifs' permettent d'écrire la spécification du problème et laissent l'implémentation du langage trouver une façon efficace de réaliser les calculs nécessaires à sa résolution. SQL est un langage déclaratif que vous êtes susceptible de connaître ; une requête SQL décrit le jeu de données que vous souhaitez récupérer et le moteur SQL choisit de parcourir les tables ou d'utiliser les index, l'ordre de résolution des sous-clauses, etc. ;

@item 
les programmes `orientés objet' manipulent des ensembles d'objets. Ceux-ci possèdent un état interne et des méthodes qui interrogent ou modifient cet état d'une façon ou d'une autre. Smalltalk et Java sont deux langages orientés objet. C++ et Python gèrent la programmation orientée objet mais n'imposent pas l'utilisation de telles fonctionnalités ;

@item 
la programmation `fonctionnelle' implique de décomposer un problème en un ensemble de fonctions. Dans l'idéal, les fonctions produisent des sorties à partir d'entrées et ne possède pas d'état interne qui soit susceptible de modifier la sortie pour une entrée donnée. Les langages fonctionnels les plus connus sont ceux de la famille ML (Standard ML, OCaml et autres) et Haskell ;
@end itemize

Les personnes qui conçoivent des langages de programmation peuvent choisir de privilégier une approche par rapport à une autre. Cela complexifie l'écriture de programmes appliquant un paradigme différent de celui considéré. Certains langages sont multi-paradigmes et gère plusieurs approches différentes. Lisp, C++ et Python sont de tels langages ; vous pouvez écrire des programmes ou des bibliothèques dans un style procédural, orienté objet ou fonctionnel dans chacun d'entre eux. Différentes parties d'une application peuvent être écrites selon des approches différentes ; par exemple, l'interface graphique peut suivre le paradigme orienté objet tandis que la logique de traitement est procédurale ou fonctionnelle.

Dans un programme fonctionnel, l'entrée traverse un ensemble de fonctions. Chaque fonction opère sur son entrée et produit une sortie. Le style fonctionnel préconise de ne pas écrire de fonctions ayant des effets de bord, c'est-à-dire qui modifient un état interne ou réalisent d'autres changements qui ne sont pas visibles dans la valeur de sortie de la fonction. Les fonctions qui ne présentent aucun effet de bord sont dites `purement fonctionnelles'. L'interdiction des effets de bord signifie qu'aucune structure de données n'est mise à jour lors de l'exécution du programme ; chaque sortie d'une fonction ne dépend que de son entrée.

Certains langages sont très stricts en ce qui concerne la pureté des fonctions et ne laissent même pas la possibilité d'assigner des variables avec des expressions telles que @code{a = 3} ou @code{c = a + b}, cependant il est difficile d'éviter tous les effets de bord. Afficher un message sur l'écran ou écrire un fichier sur le disque sont des effets de bord. Pour prendre un autre exemple, un appel aux fonctions @ref{f60,,print()} ou @ref{688,,time.sleep()} en Python ne renvoie aucune valeur utile ; ces fonctions ne sont appelées que pour leur effet de bord (afficher du texte sur l'écran ou mettre en pause l'exécution du programme).

Les programmes Python écrits dans un style fonctionnel ne poussent généralement pas le curseur de la pureté à l'extrême en interdisant toute entrée-sortie ou les assignations ; ils exhibent une interface fonctionnelle en apparence mais utilisent des fonctionnalités impures en interne. Par exemple, l'implémentation d'une fonction peut assigner dans des variables locales mais ne modifiera pas de variable globale et n'aura pas d'autre effet de bord.

La programmation fonctionnelle peut être considérée comme l'opposé de la programmation orientée objet. Les objets encapsulent un état interne ainsi qu'une collection de méthodes qui permettent de modifier cet état. Les programmes consistent à appliquer les bons changements à ces états. La programmation fonctionnelle vous impose d'éviter au maximum ces changements d'états en travaillant sur des données qui traversent un flux de fonctions. En Python, vous pouvez combiner ces deux approches en écrivant des fonctions qui prennent en argument et renvoient des instances représentants des objets de votre application (courriers électroniques, transactions, etc.).

Programmer sous la contrainte du paradigme fonctionnel peut sembler étrange. Pourquoi vouloir éviter les objets et les effets de bord ? Il existe des avantages théoriques et pratiques au style fonctionnel :


@itemize *

@item 
preuves formelles ;

@item 
modularité ;

@item 
composabilité ;

@item 
facilité de débogage et de test.
@end itemize

@menu
* Preuves formelles:: 
* Modularité:: 
* Facilité de débogage et de test:: 
* Composabilité:: 

@end menu

@node Preuves formelles,Modularité,,Introduction<14>
@anchor{howto/functional formal-provability}@anchor{4e03}
@subsubsection Preuves formelles


Un avantage théorique est qu'il plus facile de construire une preuve mathématique de l'exactitude d'un programme fonctionnel.

Les chercheurs ont longtemps souhaité trouver des façons de prouver mathématiquement qu'un programme est correct. Cela ne se borne pas à tester si la sortie d'un programme est correcte sur de nombreuses entrées ou lire le code source et en conclure que le celui-ci semble juste. L'objectif est d'établir une preuve rigoureuse que le programme produit le bon résultat pour toutes les entrées possibles.

La technique utilisée pour prouver l'exactitude d'un programme est d'écrire des `invariants', c'est-à-dire des propriétés de l'entrée et des variables du programme qui sont toujours vérifiées. Pour chaque ligne de code, il suffit de montrer que si les invariants X et Y sont vrais `avant' l'exécution de cette ligne, les invariants légèrement modifiés X' et Y' sont vérifiés `après' son exécution. Ceci se répète jusqu'à atteindre la fin du programme. À ce stade, les invariants doivent alors correspondre aux propriétés que l'on souhaite que la sortie du programme vérifie.

L'aversion du style fonctionnel envers les assignations de variable est apparue car celles-ci sont difficiles à gérer avec cette méthode. Les assignations peuvent rompre des invariants qui étaient vrais auparavant sans pour autant produire de nouveaux invariants qui pourraient être propagés.

Malheureusement, prouver l'exactitude d'un programme est très peu commode et ne concerne que rarement des logiciels en Python. Même des programmes triviaux nécessitent souvent des preuves s'étalant sur plusieurs pages ; la preuve de l'exactitude d'un programme relativement gros serait gigantesque. Peu, voire aucun, des programmes que vous utilisez quotidiennement (l'interpréteur Python, votre analyseur syntaxique XML, votre navigateur web) ne peuvent être prouvés exacts. Même si vous écriviez ou généreriez une preuve, il faudrait encore vérifier celle-ci. Peut-être qu'elle contient une erreur et que vous pensez désormais, à tort, que vous avez prouvé que votre programme est correct.

@node Modularité,Facilité de débogage et de test,Preuves formelles,Introduction<14>
@anchor{howto/functional modularity}@anchor{4e04}
@subsubsection Modularité


Un intérêt plus pratique de la programmation fonctionnelle est qu'elle impose de décomposer le problème en petits morceaux. Les programmes qui en résultent sont souvent plus modulaires. Il est plus simple de spécifier et d'écrire une petite fonction qui ne fait qu'une seule tâche plutôt qu'une grosse fonction qui réalise une transformation complexe. Les petites fonctions sont plus faciles à lire et à vérifier.

@node Facilité de débogage et de test,Composabilité,Modularité,Introduction<14>
@anchor{howto/functional ease-of-debugging-and-testing}@anchor{4e05}
@subsubsection Facilité de débogage et de test


Tester et déboguer un programme fonctionnel est plus facile.

Déboguer est plus simple car les fonctions sont généralement petites et bien spécifiées. Lorsqu'un programme ne fonctionne pas, chaque fonction constitue une étape intermédiaire au niveau de laquelle vous pouvez vérifier que les valeurs sont justes. Vous pouvez observer les entrées intermédiaires et les sorties afin d'isoler rapidement la fonction qui est à l'origine du bogue.

Les tests sont plus faciles car chaque fonction est désormais un sujet potentiel pour un test unitaire. Les fonctions ne dépendent pas d'un état particulier du système qui devrait être répliqué avant d'exécuter un test ; à la place vous n'avez qu'à produire une entrée synthétique et vérifier que le résultat correspond à ce que vous attendez.

@node Composabilité,,Facilité de débogage et de test,Introduction<14>
@anchor{howto/functional composability}@anchor{4e06}
@subsubsection Composabilité


En travaillant sur un programme dans le style fonctionnel, vous écrivez un certain nombre de fonctions avec des entrées et des sorties variables. Certaines de ces fonctions sont inévitablement spécifiques à une application en particulier, mais d'autres peuvent s'appliquer à de nombreux cas d'usage. Par exemple, une fonction qui liste l'ensemble des fichiers XML d'un répertoire à partir du chemin de celui-ci ou une fonction qui renvoie le contenu d'un fichier à partir de son nom peuvent être utiles dans de nombreuses situations.

Au fur et à mesure, vous constituez ainsi une bibliothèque personnelle d'utilitaires. Souvent, vous pourrez construire de nouveaux programmes en agençant des fonctions existantes dans une nouvelle configuration et en écrivant quelques fonctions spécifiques à votre objectif en cours.

@node Itérateurs<3>,Expressions génératrices et compréhension de listes,Introduction<14>,Guide pratique programmation fonctionnelle
@anchor{howto/functional functional-howto-iterators}@anchor{4e02}@anchor{howto/functional iterators}@anchor{4e07}
@subsection Itérateurs


Commençons par jeter un œil à une des fonctionnalités les plus importantes pour écrire en style fonctionnel avec Python : les itérateurs.

Un itérateur est un objet qui représente un flux de données ; cet objet renvoie les données un élément à la fois. Un itérateur Python doit posséder une méthode @ref{12ab,,__next__()} qui ne prend pas d'argument et renvoie toujours l'élément suivant du flux. S'il n'y plus d'élément dans le flux, @ref{12ab,,__next__()} doit lever une exception @ref{be8,,StopIteration}. Toutefois, ce n'est pas indispensable ; il est envisageable d'écrire un itérateur qui produit un flux infini de données.

La fonction native @ref{7c1,,iter()} prend un objet arbitraire et tente de construire un itérateur qui renvoie le contenu de l'objet (ou ses éléments) en levant une exception @ref{522,,TypeError} si l'objet ne gère pas l'itération. Plusieurs types de données natifs à Python gèrent l'itération, notamment les listes et les dictionnaires. On appelle @ref{1205,,iterable} un objet pour lequel il est possible de construire un itérateur.

Vous pouvez expérimenter avec l'interface d'itération manuellement :

@example
>>> L = [1, 2, 3]
>>> it = iter(L)
>>> it  
<...iterator object at ...>
>>> it.__next__()  # same as next(it)
1
>>> next(it)
2
>>> next(it)
3
>>> next(it)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
StopIteration
>>>
@end example

Python s'attend à travailler sur des objets itérables dans divers contextes et tout particulièrement dans une boucle @ref{2e6,,for}. Dans l'expression @code{for X in Y}, Y doit être un itérateur ou un objet pour lequel @ref{7c1,,iter()} peut générer un itérateur. Ces deux expressions sont équivalentes :

@example
for i in iter(obj):
    print(i)

for i in obj:
    print(i)
@end example

Les itérateurs peuvent être transformés en listes ou en `n'-uplets en appelant les constructeurs respectifs @ref{5fc,,list()} et @ref{366,,tuple()} :

@example
>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> t = tuple(iterator)
>>> t
(1, 2, 3)
@end example

Le dépaquetage de séquences fonctionne également sur les itérateurs : si vous savez qu'un itérateur renvoie N éléments, vous pouvez les dépaqueter dans un `n'-uplet :

@example
>>> L = [1, 2, 3]
>>> iterator = iter(L)
>>> a, b, c = iterator
>>> a, b, c
(1, 2, 3)
@end example

Certaines fonctions natives telles que @ref{ef4,,max()} et @ref{ef3,,min()} prennent un itérateur en argument et en renvoie le plus grand ou le plus petit élément. Les opérateurs @code{"in"} et @code{"not in"} gèrent également les itérateurs : @code{X in iterator} est vrai si X a été trouvé dans le flux renvoyé par l'itérateur. Vous rencontrerez bien sûr des problèmes si l'itérateur est infini : @ref{ef4,,max()}, @ref{ef3,,min()} ne termineront jamais et, si l'élément X n'apparaît pas dans le flux, les opérateurs @code{"in"} et @code{"not in"} non plus.

Notez qu'il n'est possible de parcourir un itérateur que vers l'avant et qu'il est impossible de récupérer l'élément précédent, de réinitialiser l'itérateur ou d'en créer une copie. Des objets itérateurs peuvent offrir ces possibilités de façon facultative, mais le protocole d'itération ne spécifie que la méthode @ref{12ab,,__next__()}. Certaines fonctions peuvent ainsi consommer l'entièreté de la sortie d'un itérateur et, si vous devez utiliser le même flux pour autre chose, vous devrez en créer un nouveau.

@menu
* Types de données itérables:: 

@end menu

@node Types de données itérables,,,Itérateurs<3>
@anchor{howto/functional data-types-that-support-iterators}@anchor{4e08}
@subsubsection Types de données itérables


Nous avons vu précédemment comment les listes et les `n'-uplets gèrent les itérateurs. En réalité, n'importe quel type de séquence en Python, par exemple les chaînes de caractères, sont itérables.

Appeler @ref{7c1,,iter()} sur un dictionnaire renvoie un itérateur qui parcourt l'ensemble de ses clés :

@example
>>> m = @{'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
...      'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12@}
>>> for key in m:
...     print(key, m[key])
Jan 1
Feb 2
Mar 3
Apr 4
May 5
Jun 6
Jul 7
Aug 8
Sep 9
Oct 10
Nov 11
Dec 12
@end example

Notez qu'à partir de la version 3.7, Python garantit que l'ordre de l'itération sur un dictionnaire est identique à l'ordre d'insertion des clés. Dans les versions précédentes, ce comportement n'était pas spécifié et pouvait varier en fonction de l'implémentation.

Appliquer @ref{7c1,,iter()} sur un dictionnaire produit un itérateur sur ses clés mais il est possible d'obtenir d'autres itérateurs par d'autres méthodes. Si vous souhaitez itérer sur les valeurs ou les paires clé/valeur du dictionnaire, vous pouvez explicitement appeler les méthodes @ref{7b8,,values()} ou @ref{7b9,,items()} pour obtenir l'itérateur idoine.

Le constructeur @ref{253,,dict()} accepte de prendre un itérateur en argument qui renvoie un flux fini de pairs @code{(clé, valeur)} :

@example
>>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')]
>>> dict(iter(L))
@{'Italy': 'Rome', 'France': 'Paris', 'US': 'Washington DC'@}
@end example

Les fichiers gèrent aussi l'itération en appelant la méthode @ref{1c4b,,readline()} jusqu'à ce qu'il n'y ait plus d'autre ligne dans le fichier. Cela signifie que vous pouvez lire l'intégralité d'un fichier de la façon suivante :

@example
for line in file:
    # do something for each line
    ...
@end example

Les ensembles peuvent être créés à partir d'un itérable et autorisent l'itération sur les éléments de l'ensemble :

@example
>>> S = @{2, 3, 5, 7, 11, 13@}
>>> for i in S:
...     print(i)
2
3
5
7
11
13
@end example

@node Expressions génératrices et compréhension de listes,Générateurs<2>,Itérateurs<3>,Guide pratique programmation fonctionnelle
@anchor{howto/functional generator-expressions-and-list-comprehensions}@anchor{4e09}
@subsection Expressions génératrices et compréhension de listes


Deux opérations courantes réalisables sur la sortie d'un itérateur sont 1) effectuer une opération pour chaque élément, 2) extraire le sous-ensemble des éléments qui vérifient une certaine condition. Par exemple, pour une liste de chaînes de caractères, vous pouvez choisir de retirer tous les caractères blancs à la fin de chaque ligne ou extraire toutes les chaînes contenant une sous-chaîne précise.

Les compréhensions de listes et les expressions génératrices sont des façons concises d'exprimer de telles opérations, inspirées du langage de programmation fonctionnel Haskell (@indicateurl{https://www.haskell.org/}).  Vous pouvez retirer tous les caractères blancs initiaux et finaux d'un flux de chaînes de caractères à l'aide du code suivant :

@example
>>> line_list = ['  line 1\n', 'line 2  \n', ' \n', '@w{'}]

>>> # Generator expression -- returns iterator
>>> stripped_iter = (line.strip() for line in line_list)

>>> # List comprehension -- returns list
>>> stripped_list = [line.strip() for line in line_list]
@end example

Vous pouvez ne sélectionner que certains éléments en ajoutant une condition « @code{if} » :

@example
>>> stripped_list = [line.strip() for line in line_list
...                  if line != ""]
@end example

La compréhension de liste renvoie une liste Python ; @code{stripped_list} est une liste contenant les lignes après transformation, pas un itérateur. Les expressions génératrices renvoient un itérateur qui calcule les valeurs au fur et à mesure sans toutes les matérialiser d'un seul coup. Cela signifie que les compréhensions de listes ne sont pas très utiles si vous travaillez sur des itérateurs infinis ou produisant une très grande quantité de données. Les expressions génératrices sont préférables dans ce cas.

Les expressions génératrices sont écrites entre parenthèses (« () ») et les compréhensions de listes entre crochets (« [] »). Les expressions génératrices sont de la forme :

@example
( expression for expr in sequence1
             if condition1
             for expr2 in sequence2
             if condition2
             for expr3 in sequence3
             ...
             if condition3
             for exprN in sequenceN
             if conditionN )
@end example

La compréhension de liste équivalente s'écrit de la même manière, utilisez juste des crochets à la place des parenthèses.

Les éléments de la sortie sont les valeurs successives de @code{expression}. La clause @code{if} est facultative ; si elle est présente, @code{expression} n'est évaluée et ajoutée au résultat que si @code{condition} est vérifiée.

Les expressions génératrices doivent toujours être écrites entre parenthèses, mais les parenthèses qui encadrent un appel de fonction comptent aussi. Si vous souhaitez créer un itérateur qui soit immédiatement passé à une fonction, vous pouvez écrire :

@example
obj_total = sum(obj.count for obj in list_all_objects())
@end example

Les clauses @code{for ... in} indiquent les séquences sur lesquelles itérer. Celles-ci peuvent être de longueurs différentes car l'itération est réalisée de gauche à droite et non en parallèle. @code{sequence2} est parcourue entièrement pour chaque élément de @code{sequence1}. @code{sequence3} est ensuite parcourue dans son intégralité pour chaque paire d'éléments de @code{sequence1} et @code{sequence2}.

Autrement dit, une compréhension de liste ou une expression génératrice est équivalente au code Python ci-dessous :

@example
for expr1 in sequence1:
    if not (condition1):
        continue   # Skip this element
    for expr2 in sequence2:
        if not (condition2):
            continue   # Skip this element
        ...
        for exprN in sequenceN:
            if not (conditionN):
                continue   # Skip this element

            # Output the value of
            # the expression.
@end example

Ainsi lorsque plusieurs clauses @code{for ... in} sont présentes mais sans condition @code{if}, la longueur totale de la nouvelle séquence est égale au produit des longueurs des séquences itérées. Si vous travaillez sur deux listes de longueur 3, la sortie contiendra 9 éléments :

@example
>>> seq1 = 'abc'
>>> seq2 = (1, 2, 3)
>>> [(x, y) for x in seq1 for y in seq2]  
[('a', 1), ('a', 2), ('a', 3),
 ('b', 1), ('b', 2), ('b', 3),
 ('c', 1), ('c', 2), ('c', 3)]
@end example

Afin de ne pas créer une ambiguïté dans la grammaire de Python, @code{expression} doit être encadrée par des parenthèses si elle produit un n-uplet. La première compréhension de liste ci-dessous n'est pas valide syntaxiquement, tandis que la seconde l'est :

@example
# Syntax error
[x, y for x in seq1 for y in seq2]
# Correct
[(x, y) for x in seq1 for y in seq2]
@end example

@node Générateurs<2>,Fonctions natives<3>,Expressions génératrices et compréhension de listes,Guide pratique programmation fonctionnelle
@anchor{howto/functional generators}@anchor{4e0a}
@subsection Générateurs


Les générateurs forment une classe spéciale de fonctions qui simplifie la création d'itérateurs. Les fonctions habituelles calculent une valeur et la renvoie, tandis que les générateurs renvoient un itérateur qui produit un flux de valeurs.

Vous connaissez sans doute le fonctionnement des appels de fonctions en Python ou en C. Lorsqu'une fonction est appelée, un espace de nommage privé lui est associé pour ses variables locales. Lorsque le programme atteint une instruction @code{return}, les variables locales sont détruites et la valeur est renvoyée à l'appelant. Les appels postérieurs à la même fonction créent un nouvel espace de nommage privé et de nouvelles variables locales. Cependant, que se passerait-il si les variables locales n'étaient pas détruites lors de la sortie d'une fonction ? Et s'il était possible de reprendre l'exécution de la fonction là où elle s'était arrêtée ? Les générateurs sont une réponse à ces questions ; vous pouvez considérer qu'il s'agit de fonctions qu'il est possible d'interrompre, puis de relancer sans perdre leur progression.

Voici un exemple simple de fonction génératrice :

@example
>>> def generate_ints(N):
...    for i in range(N):
...        yield i
@end example

N'importe quelle fonction contenant le mot-clé @ref{9bb,,yield} est un générateur ; le compilateur @ref{185,,bytecode} de Python détecte ce mot-clé et prend en compte cette particularité de la fonction.

Lorsque vous appelez une fonction génératrice, celle-ci ne renvoie pas une unique valeur ; elle renvoie un objet générateur qui implémente le protocole d'itération. Lorsque l'expression @code{yield} est exécutée, le générateur renvoie la valeur de @code{i}, d'une façon similaire à un @code{return}. La différence principale entre @code{yield} et @code{return} est qu'en atteignant l'instruction @code{yield}, l'état du générateur est suspendu et les variables locales sont conservées. Lors de l'appel suivant à la méthode @ref{1c52,,__next__()} du générateur, la fonction reprend son exécution.

Voici un exemple d'utilisation du générateur @code{generate_ints()} :

@example
>>> gen = generate_ints(3)
>>> gen  
<generator object generate_ints at ...>
>>> next(gen)
0
>>> next(gen)
1
>>> next(gen)
2
>>> next(gen)
Traceback (most recent call last):
  File "stdin", line 1, in <module>
  File "stdin", line 2, in generate_ints
StopIteration
@end example

Vous pourriez de façon équivalente écrire @code{for i in generate_ints(5)} ou @code{a, b, c = generate_ints(3)}.

Dans une fonction génératrice, une instruction @code{return value} entraîne la levée d'une exception @code{StopIteration(value)} dans la méthode @ref{1c52,,__next__()}. Lorsque cela se produit (ou que la fin de la fonction est atteinte), le flot de nouvelles valeurs s'arrête et le générateur ne peut plus rien produire.

Vous pouvez obtenir le même comportement que celui des générateurs en écrivant votre propre classe qui stocke les variables locales du générateur comme variables d'instance. Pour renvoyer une liste d'entiers, par exemple, vous pouvez initialiser @code{self.count} à 0 et écrire la méthode @ref{12ab,,__next__()} de telle sorte qu'elle incrémente @code{self.count} puis le renvoie. Cependant, cela devient beaucoup plus complexe pour des générateurs relativement sophistiqués.

Lib/test/test_generators.py@footnote{https://github.com/python/cpython/tree/3.13/Lib/test/test_generators.py}, la suite de test de la bibliothèque Python, contient de nombreux exemples intéressants. Voici un générateur qui implémente le parcours d'un arbre dans l'ordre en utilisant des générateurs de façon récursive.

@example
# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
    if t:
        for x in inorder(t.left):
            yield x

        yield t.label

        for x in inorder(t.right):
            yield x
@end example

Deux autres exemples de @code{test_generators.py} permettent de résoudre le problème des N Reines (placer `N' reines sur un échiquier de dimensions `NxN' de telle sorte qu'aucune reine ne soit en position d'en prendre une autre) et le problème du cavalier (trouver un chemin permettant au cavalier de visiter toutes les cases d'un échiquier `NxN' sans jamais visiter la même case deux fois).

@menu
* Transmettre des valeurs au générateur:: 

@end menu

@node Transmettre des valeurs au générateur,,,Générateurs<2>
@anchor{howto/functional passing-values-into-a-generator}@anchor{4e0b}
@subsubsection Transmettre des valeurs au générateur


Avant Python 2.5, les générateurs ne pouvaient que produire des sorties. Une fois le code du générateur exécuté pour créer un itérateur, il était impossible d'introduire de l'information nouvelle dans la fonction mise en pause. Une astuce consistait à obtenir cette fonctionnalité en autorisant le générateur à consulter des variables globales ou en lui passant des objets mutables modifiés hors du générateur, mais ces approches étaient compliquées.

À partir de Python 2.5, il existe une méthode simple pour transmettre des valeurs à un générateur. Le mot-clé @ref{9bb,,yield} est devenu une expression qui renvoie une valeur sur laquelle il est possible d'opérer et que vous pouvez assigner à une variable :

@example
val = (yield i)
@end example

Comme dans l'exemple ci-dessus, nous vous recommandons de `toujours' encadrer les expressions @code{yield} par des parenthèses lorsque vous utilisez leur valeur de retour. Elles ne sont pas toujours indispensables mais mieux vaut prévenir que guérir : il est plus facile de les ajouter systématiquement que de prendre le risque de les oublier là où elles sont requises.

(Les règles exactes de parenthésage sont spécifies dans la 
@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/} : une expression @code{yield} doit toujours être parenthésée sauf s'il s'agit de l'expression la plus externe du côté droit d'une assignation. Cela signifie que vous pouvez écrire @code{val = yield i} mais que les parenthèses sont requises s'il y a une opération, comme dans @code{val = (yield i) + 12}.)

Des valeurs peuvent être transmises à un générateur en appelant sa méthode @ref{1f4f,,send(value)}. Celle-ci reprend l'exécution du générateur et l'expression @code{yield} renvoie la valeur spécifiée. Si c'est la méthode @ref{1c52,,__next__()} habituelle qui est appelée, alors @code{yield} renvoie @code{None}.

Voici un exemple de compteur qui s'incrémente de 1 mais dont il est possible de modifier le compte interne.

@example
def counter(maximum):
    i = 0
    while i < maximum:
        val = (yield i)
        # If value provided, change counter
        if val is not None:
            i = val
        else:
            i += 1
@end example

Et voici comment il est possible de modifier le compteur :

@example
>>> it = counter(10)  
>>> next(it)  
0
>>> next(it)  
1
>>> it.send(8)  
8
>>> next(it)  
9
>>> next(it)  
Traceback (most recent call last):
  File "t.py", line 15, in <module>
    it.next()
StopIteration
@end example

Puisque @code{yield} renvoie souvent @code{None}, vous devez toujours vérifier si c'est le cas. N'utilisez pas la valeur de retour à moins d'être certain que seule la méthode @ref{1f4f,,send()} sera utilisée pour reprendre l'exécution de la fonction génératrice.

En plus de @ref{1f4f,,send()}, il existe deux autres méthodes s'appliquant aux générateurs :


@itemize *

@item 
@ref{4e2,,throw(value)} permet de lever une exception dans le générateur ; celle-ci est levée par l'expression @code{yield} à l'endroit où l'exécution a été mise en pause.

@item 
@ref{167d,,close()} lève une exception @ref{137e,,GeneratorExit} dans le générateur afin de terminer l'itération. Le code du générateur qui reçoit cette exception doit lever à son tour @ref{137e,,GeneratorExit} ou @ref{be8,,StopIteration}. Il est illégal d'attraper cette exception et de faire quoi que ce soit d'autre, ceci déclenche une erreur @ref{193,,RuntimeError}. Lorsque le ramasse-miette de Python collecte le générateur, il appelle sa méthode @ref{167d,,close()}.

Si vous devez exécuter du code pour faire le ménage lors d'une @ref{137e,,GeneratorExit}, nous vous suggérons d'utiliser une structure @code{try: ... finally} plutôt que d'attraper @ref{137e,,GeneratorExit}.
@end itemize

Ces changements cumulés transforment les générateurs de producteurs unidirectionnels d'information vers un statut hybride à la fois producteur et consommateur.

Les générateurs sont également devenus des `coroutines', une forme généralisée de sous-routine. L'exécution des sous-routines démarre à un endroit et se termine à un autre (au début de la fonction et au niveau de l'instruction @code{return}), tandis qu'il est possible d'entrer, de sortir ou de reprendre une coroutine à différents endroits (les instructions @code{yield}).

@node Fonctions natives<3>,Le module itertools,Générateurs<2>,Guide pratique programmation fonctionnelle
@anchor{howto/functional built-in-functions}@anchor{4e0c}
@subsection Fonctions natives


Voyons un peu plus en détail les fonctions natives souvent utilisées de concert avec les itérateurs.

@ref{84e,,map()} et @ref{84f,,filter()} sont deux fonctions natives de Python qui clonent les propriétés des expressions génératrices :


@table @asis

@item @ref{84e,,map(f@comma{} iterA@comma{} iterB@comma{} ...)} renvoie un itérateur sur une séquence

@code{f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...}.

@example
>>> def upper(s):
...     return s.upper()
@end example

@example
>>> list(map(upper, ['sentence', 'fragment']))
['SENTENCE', 'FRAGMENT']
>>> [upper(s) for s in ['sentence', 'fragment']]
['SENTENCE', 'FRAGMENT']
@end example
@end table

Vous pouvez obtenir le même comportement à l'aide d'une compréhension de liste.

@ref{84f,,filter(predicate@comma{} iter)} renvoie un itérateur sur l'ensemble des éléments de la séquence qui vérifient une certaine condition. Son comportement peut également être reproduit par une compréhension de liste. Un `prédicat' est une fonction qui renvoie vrai ou faux en fonction d'une certaine condition. Dans le cas de @ref{84f,,filter()}, le prédicat ne doit prendre qu'un seul argument.

@example
>>> def is_even(x):
...     return (x % 2) == 0
@end example

@example
>>> list(filter(is_even, range(10)))
[0, 2, 4, 6, 8]
@end example

Cela peut se réécrire sous la forme d'une compréhension de liste :

@example
>>> list(x for x in range(10) if is_even(x))
[0, 2, 4, 6, 8]
@end example

@ref{1433,,enumerate(iter@comma{} start=0)} énumère les éléments de l'itérable en renvoyant des paires contenant le nombre d'éléments déjà listés (depuis le `début') et l'élément en cours

@example
>>> for item in enumerate(['subject', 'verb', 'object']):
...     print(item)
(0, 'subject')
(1, 'verb')
(2, 'object')
@end example

@ref{1433,,enumerate()} est souvent utilisée lorsque l'on souhaite boucler sur une liste tout en listant les indices pour lesquels une certaine condition est vérifiée :

@example
f = open('data.txt', 'r')
for i, line in enumerate(f):
    if line.strip() == '@w{'}:
        print('Blank line at line #%i' % i)
@end example

@ref{bbc,,sorted(iterable@comma{} key=None@comma{} reverse=False)} rassemble tous les éléments de l'itérable dans une liste, les classe et renvoie le résultat classé. Les arguments `key' et `reverse' sont passés à la méthode @ref{bbd,,sort()} de la liste ainsi construite.

@example
>>> import random
>>> # Generate 8 random numbers between [0, 10000)
>>> rand_list = random.sample(range(10000), 8)
>>> rand_list  
[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]
>>> sorted(rand_list)  
[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]
>>> sorted(rand_list, reverse=True)  
[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]
@end example

(Pour plus de détails sur les algorithmes de tri, se référer à @ref{2107,,Sorting Techniques}.)

Les fonctions natives @ref{13d7,,any(iter)} et @ref{13d8,,all(iter)} permettent d'observer les valeurs de vérité des éléments d'un itérable. @ref{13d7,,any()} renvoie @code{True} si au moins un élément de l'itérable s'évalue comme vrai et @ref{13d8,,all()} renvoie @code{True} si tous les éléments s'évaluent comme vrai :

@example
>>> any([0, 1, 0])
True
>>> any([0, 0, 0])
False
>>> any([1, 1, 1])
True
>>> all([0, 1, 0])
False
>>> all([0, 0, 0])
False
>>> all([1, 1, 1])
True
@end example

@ref{7ba,,zip(iterA@comma{} iterB@comma{} ...)} rassemble un élément de chaque itérable dans un `n'-uplet :

@example
zip(['a', 'b', 'c'], (1, 2, 3)) =>
  ('a', 1), ('b', 2), ('c', 3)
@end example

Cela ne construit pas de liste stockée en mémoire, ni ne vide les itérateurs d'entrée avant de renvoyer sa valeur ; en réalité les `n'-uplets sont construits et renvoyés au fur et à mesure (il s'agit techniquement parlant d'un comportement d'évaluation paresseuse@footnote{https://fr.wikipedia.org/wiki/%C3%89valuation_paresseuse}).

Cet itérateur suppose qu'il opère sur des itérables de même longueur. Si la longueur des itérables diffère, le flux résultant a la même longueur que le plus court des itérables.

@example
zip(['a', 'b'], (1, 2, 3)) =>
  ('a', 1), ('b', 2)
@end example

Toutefois, vous devez éviter de dépendre de ce comportement. En effet un élément d'un des itérables les plus longs peut être retiré puis jeté (car l'autre itérable est trop court). Cela signifie que vous ne pouvez alors plus utiliser cet itérable car vous allez sauter l'élément qui vient d'être jeté.

@node Le module itertools,Le module functools,Fonctions natives<3>,Guide pratique programmation fonctionnelle
@anchor{howto/functional the-itertools-module}@anchor{4e0d}
@subsection Le module `itertools'


The @ref{80,,itertools} module contains a number of commonly used iterators as well
as functions for combining several iterators.  This section will introduce the
module's contents by showing small examples.

Les fonctions du module se divisent en quelques grandes catégories :


@itemize *

@item 
les fonctions qui transforment un itérateur existant en un nouvel itérateur ;

@item 
les fonctions qui traitent les éléments d'un itérateur comme les arguments d'une fonction ;

@item 
les fonctions qui permettent de sélectionner des portions de la sortie d'un itérateur ;

@item 
une fonction qui permet de grouper la sortie d'un itérateur.
@end itemize

@menu
* Créer de nouveaux itérateurs:: 
* Appliquer des fonctions au contenu des itérateurs:: 
* Sélectionner des éléments:: 
* Fonctions combinatoires:: 
* Grouper les éléments:: 

@end menu

@node Créer de nouveaux itérateurs,Appliquer des fonctions au contenu des itérateurs,,Le module itertools
@anchor{howto/functional creating-new-iterators}@anchor{4e0e}
@subsubsection Créer de nouveaux itérateurs


@ref{1261,,itertools.count(start@comma{} step)} renvoie un flux infini de valeurs régulièrement espacées. Vous pouvez spécifier la valeur de départ (par défaut, 0) et l'intervalle entre les nombres (par défaut, 1) :

@example
itertools.count() =>
  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
itertools.count(10) =>
  10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...
itertools.count(10, 5) =>
  10, 15, 20, 25, 30, 35, 40, 45, 50, 55, ...
@end example

@ref{26ad,,itertools.cycle(iter)} sauvegarde une copie du contenu de l'itérable passé en argument et renvoie un nouvel itérateur qui produit tous les éléments du premier au dernier et se répète indéfiniment.

@example
itertools.cycle([1, 2, 3, 4, 5]) =>
  1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ...
@end example

@ref{26ae,,itertools.repeat(elem@comma{} [n])} renvoie l'élément passé en argument `n' fois ou répète l'élément à l'infini si `n' n'est pas spécifié.

@example
itertools.repeat('abc') =>
  abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...
itertools.repeat('abc', 5) =>
  abc, abc, abc, abc, abc
@end example

@ref{2108,,itertools.chain(iterA@comma{} iterB@comma{} ...)} reçoit un nombre arbitraire d'itérables en entrée et les concatène, renvoyant tous les éléments du premier itérateur, puis tous ceux du second et ainsi de suite jusqu'à ce que tous les itérables aient été épuisés.

@example
itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
  a, b, c, 1, 2, 3
@end example

@ref{b3a,,itertools.islice(iter@comma{} [start]@comma{} stop@comma{} [step])} renvoie une portion de l'itérateur. En passant seulement l'argument `stop', il renvoie les `stop' premiers éléments. En spécifiant un indice de début, vous récupérez `stop - start' éléments ; utilisez `step' pour spécifier une valeur de pas. Cependant vous ne pouvez pas utiliser de valeurs négatives pour `start', `stop' ou `step' (contrairement aux listes et chaînes de caractères de Python).

@example
itertools.islice(range(10), 8) =>
  0, 1, 2, 3, 4, 5, 6, 7
itertools.islice(range(10), 2, 8) =>
  2, 3, 4, 5, 6, 7
itertools.islice(range(10), 2, 8, 2) =>
  2, 4, 6
@end example

@ref{26b3,,itertools.tee(iter@comma{} [n])} duplique un itérateur et renvoie `n' itérateurs indépendants, chacun copiant le contenu de l'itérateur source. La valeur par défaut pour `n' est 2. La réplication des itérateurs nécessite la sauvegarde d'une partie du contenu de l'itérateur source, ce qui peut consommer beaucoup de mémoire si l'itérateur est grand et que l'un des nouveaux itérateurs est plus consommé que les autres.

@example
itertools.tee( itertools.count() ) =>
   iterA, iterB

where iterA ->
   0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...

and   iterB ->
   0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
@end example

@node Appliquer des fonctions au contenu des itérateurs,Sélectionner des éléments,Créer de nouveaux itérateurs,Le module itertools
@anchor{howto/functional calling-functions-on-elements}@anchor{4e0f}
@subsubsection Appliquer des fonctions au contenu des itérateurs


Le module @ref{9e,,operator} rassemble des fonctions équivalentes aux opérateurs Python. Par exemple, @ref{26d6,,operator.add(a@comma{}b)} additionne deux valeurs, @ref{26c6,,operator.ne(a@comma{} b)} est équivalent à @code{a != b} et @ref{e20,,operator.attrgetter('id')} renvoie un objet appelable qui récupère l'attribut @code{.id}.

@ref{10c5,,itertools.starmap(func@comma{} iter)} suppose que l'itérable renvoie une séquence de `n'-uplets et appelle `func' en utilisant tous les `n'-uplets comme arguments :

@example
itertools.starmap(os.path.join,
                  [('/bin', 'python'), ('/usr', 'bin', 'java'),
                   ('/usr', 'bin', 'perl'), ('/usr', 'bin', 'ruby')])
=>
  /bin/python, /usr/bin/java, /usr/bin/perl, /usr/bin/ruby
@end example

@node Sélectionner des éléments,Fonctions combinatoires,Appliquer des fonctions au contenu des itérateurs,Le module itertools
@anchor{howto/functional selecting-elements}@anchor{4e10}
@subsubsection Sélectionner des éléments


Une autre catégorie de fonctions est celle permettant de sélectionner un sous-ensemble des éléments de l'itérateur selon un prédicat donné.

@ref{20ef,,itertools.filterfalse(predicate@comma{} iter)} est l'opposé de @ref{84f,,filter()} et renvoie tous les éléments pour lesquels le prédicat est faux :

@example
itertools.filterfalse(is_even, itertools.count()) =>
  1, 3, 5, 7, 9, 11, 13, 15, ...
@end example

@ref{26b2,,itertools.takewhile(predicate@comma{} iter)} renvoie les éléments de l'itérateur tant que ceux-ci vérifient le prédicat. Dès lors que le prédicat renvoie faux, l'itération s'arrête.

@example
def less_than_10(x):
    return x < 10

itertools.takewhile(less_than_10, itertools.count()) =>
  0, 1, 2, 3, 4, 5, 6, 7, 8, 9

itertools.takewhile(is_even, itertools.count()) =>
  0
@end example

@ref{26b0,,itertools.dropwhile(predicate@comma{} iter)} supprime des éléments tant que le prédicat renvoie vrai puis renvoie le reste des éléments de l'itérable.

@example
itertools.dropwhile(less_than_10, itertools.count()) =>
  10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...

itertools.dropwhile(is_even, itertools.count()) =>
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...
@end example

@ref{1260,,itertools.compress(data@comma{} selectors)} prend un itérateur `data' et un itérateur `selectors' et renvoie les éléments de `data' pour lesquels l'élément correspondant de `selectors' est évalué à vrai. L'itération s'arrête lorsque l'un des deux itérateurs est épuisé :

@example
itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) =>
   1, 2, 5
@end example

@node Fonctions combinatoires,Grouper les éléments,Sélectionner des éléments,Le module itertools
@anchor{howto/functional combinatoric-functions}@anchor{4e11}
@subsubsection Fonctions combinatoires


@ref{12f0,,itertools.combinations(iterable@comma{} r)} renvoie un itérateur qui produit toutes les combinaisons possibles de `r'-uplets des éléments de `iterable'.

@example
itertools.combinations([1, 2, 3, 4, 5], 2) =>
  (1, 2), (1, 3), (1, 4), (1, 5),
  (2, 3), (2, 4), (2, 5),
  (3, 4), (3, 5),
  (4, 5)

itertools.combinations([1, 2, 3, 4, 5], 3) =>
  (1, 2, 3), (1, 2, 4), (1, 2, 5), (1, 3, 4), (1, 3, 5), (1, 4, 5),
  (2, 3, 4), (2, 3, 5), (2, 4, 5),
  (3, 4, 5)
@end example

Les éléments de chaque `n'-uplet sont ordonnés dans le même ordre que leur apparition dans `iterable'. Ainsi, dans les exemples ci-dessus, le nombre 1 se trouve toujours avant 2, 3, 4 ou 5. La fonction @ref{18a8,,itertools.permutations(iterable@comma{} r=None)} supprime la contrainte sur l'ordre et renvoie tous les arrangements possibles de longueur `r' :

@example
itertools.permutations([1, 2, 3, 4, 5], 2) =>
  (1, 2), (1, 3), (1, 4), (1, 5),
  (2, 1), (2, 3), (2, 4), (2, 5),
  (3, 1), (3, 2), (3, 4), (3, 5),
  (4, 1), (4, 2), (4, 3), (4, 5),
  (5, 1), (5, 2), (5, 3), (5, 4)

itertools.permutations([1, 2, 3, 4, 5]) =>
  (1, 2, 3, 4, 5), (1, 2, 3, 5, 4), (1, 2, 4, 3, 5),
  ...
  (5, 4, 3, 2, 1)
@end example

Si vous ne spécifiez pas de valeur pour `r', la longueur de l'itérable est utilisée par défaut, c'est-à-dire que toutes les permutations de la séquence sont renvoyées.

Notez que ces fonctions génèrent toutes les combinaisons possibles en se basant sur la position des éléments et ne requièrent pas que les éléments de `iterable' soient uniques :

@example
itertools.permutations('aba', 3) =>
  ('a', 'b', 'a'), ('a', 'a', 'b'), ('b', 'a', 'a'),
  ('b', 'a', 'a'), ('a', 'a', 'b'), ('a', 'b', 'a')
@end example

Le triplet @code{('a', 'a', 'b')} apparaît deux fois mais les deux chaînes de caractères @code{'a'} proviennent de deux positions différentes.

La fonction @ref{125f,,itertools.combinations_with_replacement(iterable@comma{} r)} assouplit une autre contrainte : les éléments peuvent être répétés au sein du même `n'-uplet. Il s'agit d'un tirage avec remise : le premier élément sélectionné pour chaque `n'-uplet est replacé dans la séquence avant le tirage du deuxième.

@example
itertools.combinations_with_replacement([1, 2, 3, 4, 5], 2) =>
  (1, 1), (1, 2), (1, 3), (1, 4), (1, 5),
  (2, 2), (2, 3), (2, 4), (2, 5),
  (3, 3), (3, 4), (3, 5),
  (4, 4), (4, 5),
  (5, 5)
@end example

@node Grouper les éléments,,Fonctions combinatoires,Le module itertools
@anchor{howto/functional grouping-elements}@anchor{4e12}
@subsubsection Grouper les éléments


La dernière fonction que allons voir, @ref{26b1,,itertools.groupby(iter@comma{} key_func=None)} est la plus complexe. @code{key_func(elem)} est une fonction qui produit une clé pour chaque élément renvoyé par l'itérable. Si vous ne spécifiez pas de fonction `key', alors celle-ci est l'identité par défaut (c'est-à-dire que la clé d'un élément est l'élément lui-même).

@ref{26b1,,groupby()} rassemble tous éléments consécutifs de l'itérable sous-jacent qui ont la même clé et renvoie un flux de paires contenant la clé et un itérateur produisant la liste des éléments pour cette clé.

@example
city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),
             ('Anchorage', 'AK'), ('Nome', 'AK'),
             ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),
             ...
            ]

def get_state(city_state):
    return city_state[1]

itertools.groupby(city_list, get_state) =>
  ('AL', iterator-1),
  ('AK', iterator-2),
  ('AZ', iterator-3), ...

where
iterator-1 =>
  ('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')
iterator-2 =>
  ('Anchorage', 'AK'), ('Nome', 'AK')
iterator-3 =>
  ('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')
@end example

@ref{26b1,,groupby()} fait l'hypothèse que le contenu de l'itérable sous-jacent est d'ores et déjà ordonné en fonction de la clé. Notez que les itérateurs générés utilisent également l'itérable sous-jacent. Vous devez donc consommer l'intégralité des résultats du premier itérateur renvoyé (`iterator-1' dans l'exemple ci-dessus) avant de récupérer le deuxième itérateur (`iterator-2' dans l'exemple ci-dessus) et la clé à laquelle il est associé.

@node Le module functools,Expressions lambda et fonctions courtes,Le module itertools,Guide pratique programmation fonctionnelle
@anchor{howto/functional the-functools-module}@anchor{4e13}
@subsection Le module `functools'


The @ref{5e,,functools} module contains some higher-order functions.
A `higher-order function' takes one or more functions as input and returns a
new function.  The most useful tool in this module is the
@ref{40a,,functools.partial()} function.

En programmant dans un style fonctionnel, il est courant de vouloir construire des variantes de fonctions existantes dont certains paramètres sont prédéfinis. Par exemple, considérons une fonction Python @code{f(a, b, c)}. Si vous voulez une nouvelle fonction @code{g(b, c)} équivalente à @code{f(1, b, c)}, c'est-à-dire fixer le premier paramètre de @code{f()}. La fonction @code{g()} est une appelée « application partielle » de @code{f()}.

Le constructeur de @ref{40a,,partial()} prend en argument @code{(fonction, arg1, arg2, ..., kwarg1=value1, kwarg2=value2, ...)}. Un appel à l'objet ainsi créé invoque la fonction @code{fonction} avec les arguments spécifiés.

Voici un exemple court mais réaliste :

@example
import functools

def log(message, subsystem):
    """Write the contents of 'message' to the specified subsystem."""
    print('%s: %s' % (subsystem, message))
    ...

server_log = functools.partial(log, subsystem='server')
server_log('Unable to open socket')
@end example

@ref{12ba,,functools.reduce(func@comma{} iter@comma{} [initial_value])}  applique une opération cumulative à tous les éléments d'un itérable et ne peut donc être appliquée à des itérables infinis. `func' doit être une fonction qui prend deux éléments et renvoie une seule valeur. @ref{12ba,,functools.reduce()} prend les deux premiers éléments A et B renvoyés par l'itérateur et calcule @code{func(A, B)}. Elle extrait ensuite le troisième élément C et calcule @code{func(func(A, B), C)} puis combine ce résultat avec le quatrième élément renvoyé etc. jusqu'à épuisement de l'itérable. Une exception @ref{522,,TypeError} est levée si l'itérable ne renvoie aucune valeur. La valeur initiale `initial_value', si spécifiée, est utilisée comme point de départ et le premier calcul est alors @code{func(inital_value, A)}.

@example
>>> import operator, functools
>>> functools.reduce(operator.concat, ['A', 'BB', 'C'])
'ABBC'
>>> functools.reduce(operator.concat, [])
Traceback (most recent call last):
  ...
TypeError: reduce() of empty sequence with no initial value
>>> functools.reduce(operator.mul, [1, 2, 3], 1)
6
>>> functools.reduce(operator.mul, [], 1)
1
@end example

Si vous combinez @ref{26d6,,operator.add()} avec @ref{12ba,,functools.reduce()}, vous allez additionner tous les éléments de l'itérable. Ce cas est suffisamment courant pour qu'il existe une fonction native @ref{454,,sum()} qui lui est équivalent :

@example
>>> import functools, operator
>>> functools.reduce(operator.add, [1, 2, 3, 4], 0)
10
>>> sum([1, 2, 3, 4])
10
>>> sum([])
0
@end example

Cependant, il peut être plus lisible dans de nombreuses situations impliquant @ref{12ba,,functools.reduce()} de simplement écrire la boucle @ref{2e6,,for} :

@example
import functools
# Instead of:
product = functools.reduce(operator.mul, [1, 2, 3], 1)

# You can write:
product = 1
for i in [1, 2, 3]:
    product *= i
@end example

A related function is @ref{9eb,,itertools.accumulate(iterable@comma{} func=operator.add)}.  It performs the same calculation, but instead of
returning only the final result, @ref{9eb,,accumulate()} returns an iterator
that also yields each partial result:

@example
itertools.accumulate([1, 2, 3, 4, 5]) =>
  1, 3, 6, 10, 15

itertools.accumulate([1, 2, 3, 4, 5], operator.mul) =>
  1, 2, 6, 24, 120
@end example

@menu
* Le module operator:: 

@end menu

@node Le module operator,,,Le module functools
@anchor{howto/functional the-operator-module}@anchor{4e14}
@subsubsection Le module `operator'


Le module @ref{9e,,operator} mentionné précédemment contient un ensemble de fonctions reproduisant les opérateurs de Python. Ces fonctions sont souvent utiles en programmation fonctionnelle car elles permettent de ne pas avoir à écrire des fonctions triviales qui ne réalisent qu'une seule opération.

Voici quelques fonctions de ce module :


@itemize *

@item 
les opérations mathématiques : @code{add()}, @code{sub()}, @code{mul()}, @code{floordiv()}, @code{abs()}… ;

@item 
les opérations logiques : @code{not_()}, @code{truth()} ;

@item 
les opérations bit à bit : @code{and_()}, @code{or_()}, @code{invert()} ;

@item 
les comparaisons : @code{eq()}, @code{ne()}, @code{lt()}, @code{le()}, @code{gt()}, et @code{ge()} ;

@item 
l'identification des objets : @code{is_()}, @code{is_not()}.
@end itemize

Veuillez vous référer à la documentation du module `operator' pour une liste complète.

@node Expressions lambda et fonctions courtes,Historique des modifications et remerciements,Le module functools,Guide pratique programmation fonctionnelle
@anchor{howto/functional small-functions-and-the-lambda-expression}@anchor{4e15}
@subsection Expressions lambda et fonctions courtes


Dans un style de programmation fonctionnel, il est courant d'avoir besoin de petites fonctions utilisées comme prédicats ou pour combiner des éléments d'une façon ou d'une autre.

S'il existe une fonction native Python ou une fonction d'un module qui convient, vous n'avez pas besoin de définir de nouvelle fonction :

@example
stripped_lines = [line.strip() for line in lines]
existing_files = filter(os.path.exists, file_list)
@end example

Si la fonction dont vous avez besoin n'existe pas, vous devez l'écrire. Une façon d'écrire des fonctions courtes consiste à utiliser les expressions @ref{127a,,lambda}. @code{lambda} prend plusieurs paramètres et une expression combinant ces derniers afin de créer une fonction anonyme qui renvoie la valeur de cette expression :

@example
adder = lambda x, y: x+y

print_assign = lambda name, value: name + '=' + str(value)
@end example

Une autre façon de faire est de simplement utiliser l'instruction @code{def} afin de définir une fonction de la manière habituelle :

@example
def adder(x, y):
    return x + y

def print_assign(name, value):
    return name + '=' + str(value)
@end example

La méthode à préférer est une question de style, en général l'auteur évite l'utilisation de @code{lambda}.

Une des raisons est que @code{lambda} ne peut pas définir toutes les fonctions. Le résultat doit pouvoir se calculer en une seule expression, ce qui signifie qu'il est impossible d'avoir des comparaisons @code{if ... elif ... else} à plusieurs branches ou des structures @code{try ... except}. Si vous essayez de trop en faire dans une expression @code{lambda}, vous finirez avec une expression illisible. Par exemple, pouvez-vous dire du premier coup d’œil ce que fait le code ci-dessous ?

@example
import functools
total = functools.reduce(lambda a, b: (0, a[1] + b[1]), items)[1]
@end example

Vous pouvez sûrement comprendre ce que fait ce code mais cela prend du temps de démêler l'expression pour y voir plus clair. Une clause @code{def} concise améliore la situation :

@example
import functools
def combine(a, b):
    return 0, a[1] + b[1]

total = functools.reduce(combine, items)[1]
@end example

Toutefois l'idéal aurait été de simplement se contenter d'une boucle @code{for} :

@example
total = 0
for a, b in items:
    total += b
@end example

ou de la fonction native @ref{454,,sum()} et d'une expression génératrice :

@example
total = sum(b for a, b in items)
@end example

Les boucles @code{for} sont souvent plus lisibles que la fonction @ref{12ba,,functools.reduce()}.

Frederik Lundh a suggéré quelques règles pour le réusinage de code impliquant les expressions @code{lambda} :


@enumerate 

@item 
Écrire une fonction lambda.

@item 
Écrire un commentaire qui explique ce que fait cette satanée fonction lambda.

@item 
Scruter le commentaire pendant quelques temps et réfléchir à un nom qui synthétise son essence.

@item 
Réécrire la fonction lambda en une définition `def' en utilisant ce nom.

@item 
Effacer le commentaire.
@end enumerate

J'aime beaucoup ces règles, mais vous êtes libre de ne pas être d'accord et de préférer un style avec des lambdas.

@node Historique des modifications et remerciements,Références<3>,Expressions lambda et fonctions courtes,Guide pratique programmation fonctionnelle
@anchor{howto/functional revision-history-and-acknowledgements}@anchor{4e16}
@subsection Historique des modifications et remerciements


L'auteur souhaiterait remercier les personnes suivantes pour leurs suggestions, leurs corrections et leur aide sur les premières versions de cet article : Ian Bicking, Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro Lameiro, Jussi Salmela, Collin Winter, Blake Winton.

Version 0.1 : publiée le 30 juin 2006.

Version 0.11 : publiée le 1@w{^er} juillet 2006. Correction orthographique.

Version 0.2 : publiée le 10 juillet 2006. Fusion des sections `genexp' et `listcomp'. Correction orthographique.

Version 0.21 : ajout de plusieurs références suggérées sur la liste de diffusion `tutor'.

Version 0.30 : ajout d'une section sur le module @code{functional} écrite par Collin Winter ; ajout d'une courte section sur le module @code{operator} ; quelques autres modifications.

@node Références<3>,,Historique des modifications et remerciements,Guide pratique programmation fonctionnelle
@anchor{howto/functional references}@anchor{4e17}
@subsection Références


@menu
* Général:: 
* Spécifique à Python:: 
* Documentation Python:: 

@end menu

@node Général,Spécifique à Python,,Références<3>
@anchor{howto/functional general}@anchor{4e18}
@subsubsection Général


`Structure and Interpretation of Computer Programs', by Harold Abelson and
Gerald Jay Sussman with Julie Sussman.  The book can be found at
@indicateurl{https://mitpress.mit.edu/sicp}.  In this classic textbook of computer science,
chapters 2 and 3 discuss the use of sequences and streams to organize the data
flow inside a program.  The book uses Scheme for its examples, but many of the
design approaches described in these chapters are applicable to functional-style
Python code.

@indicateurl{https://www.defmacro.org/ramblings/fp.html}: A general introduction to functional
programming that uses Java examples and has a lengthy historical introduction.

@indicateurl{https://fr.wikipedia.org/wiki/Programmation_fonctionnelle} : l'entrée Wikipédia qui décrit la programmation fonctionnelle.

@indicateurl{https://fr.wikipedia.org/wiki/Coroutine} : l'entrée pour les coroutines.

@indicateurl{https://en.wikipedia.org/wiki/Partial_application}: Entry for the concept of partial function application.

@indicateurl{https://fr.wikipedia.org/wiki/Curryfication} : l'entrée pour le concept de curryfication (création d'applications partielles).

@node Spécifique à Python,Documentation Python,Général,Références<3>
@anchor{howto/functional python-specific}@anchor{4e19}
@subsubsection Spécifique à Python


@indicateurl{https://gnosis.cx/TPiP/}: The first chapter of David Mertz's book
@cite{Text Processing in Python} discusses functional programming
for text processing, in the section titled "Utilizing Higher-Order Functions in
Text Processing".

Mertz a également écrit une série de 3 articles (en anglais) sur la programmation fonctionnelle pour le site DeveloperWorks d'IBM. Voir partie 1@footnote{https://developer.ibm.com/articles/l-prog/}, partie 2@footnote{https://developer.ibm.com/tutorials/l-prog2/} et partie 3@footnote{https://developer.ibm.com/tutorials/l-prog3/},

@node Documentation Python,,Spécifique à Python,Références<3>
@anchor{howto/functional python-documentation}@anchor{4e1a}
@subsubsection Documentation Python


Documentation du module @ref{80,,itertools}.

Documentation du module @ref{5e,,functools}.

Documentation du module @ref{9e,,operator}.

@geindex Python Enhancement Proposals; PEP 289
PEP 289@footnote{https://peps.python.org/pep-0289/}: `"Generator Expressions"'

@geindex Python Enhancement Proposals; PEP 342
PEP 342@footnote{https://peps.python.org/pep-0342/}: `"Coroutines via Enhanced Generators"' décrit les nouvelles fonctionnalités des générateurs en Python 2.5.

@c comment
@c 
@c Handy little function for printing part of an iterator -- used
@c while writing this document.
@c 
@c import itertools
@c def print_iter(it):
@c      slice = itertools.islice(it, 10)
@c      for elem in slice[:-1]:
@c          sys.stdout.write(str(elem))
@c          sys.stdout.write(', ')
@c     print(elem[-1])

@node Tutoriel sur la journalisation,Recettes pour la journalisation,Guide pratique programmation fonctionnelle,Les HOWTOs de Python
@anchor{howto/logging doc}@anchor{4e1b}@anchor{howto/logging id1}@anchor{4e1c}@anchor{howto/logging logging-howto}@anchor{4e1d}
@section Tutoriel sur la journalisation


@*Auteur: 
Vinay Sajip <vinay_sajip at red-dove dot com>

@anchor{howto/logging logging-basic-tutorial}@anchor{11d2}
This page contains tutorial information. For links to reference information and a
logging cookbook, please see @ref{4e1e,,Autres ressources}.

@menu
* Les bases de l'utilisation du module logging:: 
* Usage avancé de Logging:: 
* Niveaux de journalisation: Niveaux de journalisation<2>. 
* Gestionnaires utiles:: 
* Exceptions levées par la journalisation:: 
* Utilisation d'objets arbitraires comme messages:: 
* Optimisation:: 
* Autres ressources: Autres ressources<2>. 

@end menu

@node Les bases de l'utilisation du module logging,Usage avancé de Logging,,Tutoriel sur la journalisation
@anchor{howto/logging basic-logging-tutorial}@anchor{4e1f}
@subsection Les bases de l'utilisation du module @code{logging}


La journalisation (`logging' en anglais) est une façon de suivre les événements qui ont lieu durant le fonctionnement d'un logiciel. Le développeur du logiciel ajoute des appels à l'outil de journalisation dans son code pour indiquer que certains événements ont eu lieu. Un événement est décrit par un message descriptif, qui peut éventuellement contenir des données variables (c'est-à-dire qui peuvent être différentes pour chaque occurrence de l'événement). Un événement a aussi une importance que le développeur lui attribue ; cette importance peut aussi être appelée `niveau' ou `sévérité'.

@menu
* Quand utiliser logging:: 
* Un exemple simple: Un exemple simple<2>. 
* Enregistrer les évènements dans un fichier:: 
* Journalisation de données variables:: 
* Modifier le format du message affiché:: 
* Afficher l'horodatage dans les messages:: 
* Étapes suivantes:: 

@end menu

@node Quand utiliser logging,Un exemple simple<2>,,Les bases de l'utilisation du module logging
@anchor{howto/logging when-to-use-logging}@anchor{4e20}
@subsubsection Quand utiliser @code{logging}


You can access logging functionality by creating a logger via @code{logger =
getLogger(__name__)}, and then calling the logger's @ref{e17,,debug()},
@ref{2beb,,info()}, @ref{168d,,warning()}, @ref{2bed,,error()} and
@ref{e16,,critical()} methods. To determine when to use logging, and to see
which logger methods to use when, see the table below. It states, for each of a
set of common tasks, the best tool to use for that task.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Tâche que vous souhaitez mener

@tab

Le meilleur outil pour cette tâche

@item

Affiche la sortie console d'un script en ligne de commande ou d'un programme lors de son utilisation ordinaire

@tab

@ref{f60,,print()}

@item

Rapporter des évènements qui ont lieu au cours du fonctionnement normal d'un programme (par exemple pour suivre un statut ou examiner des dysfonctionnements)

@tab

A logger's @ref{2beb,,info()} (or
@ref{e17,,debug()} method for very
detailed output for diagnostic
purposes)

@item

Émettre un avertissement (`warning' en anglais) en relation avec un évènement particulier au cours du fonctionnement d’un programme

@tab

@ref{14d0,,warnings.warn()} dans le code de la bibliothèque si le problème est évitable et l'application cliente doit être modifiée pour éliminer cet avertissement

A logger's @ref{168d,,warning()}
method if there is nothing the client
application can do about the
situation, but the event should still
be noted

@item

Rapporter une erreur lors d'un évènement particulier en cours d'exécution

@tab

Lever une exception

@item

Rapporter la suppression d'une erreur sans lever d'exception (par exemple pour la gestion d'erreur d'un processus de long terme sur un serveur)

@tab

A logger's @ref{2bed,,error()},
@ref{e15,,exception()} or
@ref{e16,,critical()} method as
appropriate for the specific error
and application domain

@end multitable


The logger methods are named after the level or severity of the events
they are used to track. The standard levels and their applicability are
described below (in increasing order of severity):


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Niveau

@tab

Quand il est utilisé

@item

@code{DEBUG}

@tab

Information détaillée, intéressante seulement lorsqu'on diagnostique un problème.

@item

@code{INFO}

@tab

Confirmation que tout fonctionne comme prévu.

@item

@code{WARNING}

@tab

L'indication que quelque chose d'inattendu a eu lieu, ou de la possibilité d'un problème dans un futur proche (par exemple « espace disque faible »). Le logiciel fonctionne encore normalement.

@item

@code{ERROR}

@tab

Du fait d'un problème plus sérieux, le logiciel n'a pas été capable de réaliser une tâche.

@item

@code{CRITICAL}

@tab

Une erreur sérieuse, indiquant que le programme lui-même pourrait être incapable de continuer à fonctionner.

@end multitable


The default level is @code{WARNING}, which means that only events of this severity and higher
will be tracked, unless the logging package is configured to do otherwise.

Les évènements suivis peuvent être gérés de différentes façons. La manière la plus simple est de les afficher dans la console. Une autre méthode commune est de les écrire dans un fichier.

@node Un exemple simple<2>,Enregistrer les évènements dans un fichier,Quand utiliser logging,Les bases de l'utilisation du module logging
@anchor{howto/logging a-simple-example}@anchor{4e21}@anchor{howto/logging howto-minimal-example}@anchor{4e22}
@subsubsection Un exemple simple


Un exemple très simple est :

@example
import logging
logging.warning('Watch out!')  # will print a message to the console
logging.info('I told you so')  # will not print anything
@end example

Si vous entrez ces lignes dans un script que vous exécutez, vous verrez :

@example
WARNING:root:Watch out!
@end example

printed out on the console. The @code{INFO} message doesn't appear because the
default level is @code{WARNING}. The printed message includes the indication of the
level and the description of the event provided in the logging call, i.e.
'Watch out!'. The actual output can be formatted quite flexibly if you need
that; formatting options will also be explained later.

Notice that in this example, we use functions directly on the @code{logging}
module, like @code{logging.debug}, rather than creating a logger and calling
functions on it. These functions operation on the root logger, but can be useful
as they will call @ref{9ee,,basicConfig()} for you if it has not been called yet, like in
this example.  In larger programs you'll usually want to control the logging
configuration explicitly however - so for that reason as well as others, it's
better to create loggers and call their methods.

@node Enregistrer les évènements dans un fichier,Journalisation de données variables,Un exemple simple<2>,Les bases de l'utilisation du module logging
@anchor{howto/logging logging-to-a-file}@anchor{4e23}
@subsubsection Enregistrer les évènements dans un fichier


Il est très commun d'enregistrer les évènements dans un fichier, c'est donc ce que nous allons regarder maintenant. Il faut essayer ce qui suit avec un interpréteur Python nouvellement démarré, ne poursuivez pas la session commencée ci-dessus :

@example
import logging
logger = logging.getLogger(__name__)
logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
logger.debug('This message should go to the log file')
logger.info('So should this')
logger.warning('And this, too')
logger.error('And non-ASCII stuff, too, like Øresund and Malmö')
@end example


Modifié dans la version 3.9: L'argument `encoding' a été rajouté. Dans les versions précédentes de Python, ou si non spécifié, l'encodage utilisé est la valeur par défaut utilisée par @ref{505,,open()}. Bien que non montré dans l'exemple ci-dessus, un argument `errors' peut aussi être passé, qui détermine comment les erreurs d'encodage sont gérées. Pour voir les valeurs disponibles et par défaut, consultez la documentation de @ref{505,,open()}.


Maintenant, si nous ouvrons le fichier et lisons ce qui s'y trouve, nous trouvons les messages de journalisation :

@example
DEBUG:__main__:This message should go to the log file
INFO:__main__:So should this
WARNING:__main__:And this, too
ERROR:__main__:And non-ASCII stuff, too, like Øresund and Malmö
@end example

Cet exemple montre aussi comment on peut régler le niveau de journalisation qui sert de seuil pour le suivi. Dans ce cas, comme nous avons réglé le seuil à @code{DEBUG}, tous les messages ont été écrits.

Si vous souhaitez régler le niveau de journalisation à partir d'une option de la ligne de commande comme :

@example
--log=INFO
@end example

et que vous passez ensuite la valeur du paramètre donné à l'option @code{--log} dans une variable `loglevel', vous pouvez utiliser :

@example
getattr(logging, loglevel.upper())
@end example

de manière à obtenir la valeur à passer à @ref{9ee,,basicConfig()} à travers l'argument `level'. Vous pouvez vérifier que l'utilisateur n'a fait aucune erreur pour la valeur de ce paramètre, comme dans l'exemple ci-dessous :

@example
# assuming loglevel is bound to the string value obtained from the
# command line argument. Convert to upper case to allow the user to
# specify --log=DEBUG or --log=debug
numeric_level = getattr(logging, loglevel.upper(), None)
if not isinstance(numeric_level, int):
    raise ValueError('Invalid log level: %s' % loglevel)
logging.basicConfig(level=numeric_level, ...)
@end example

The call to @ref{9ee,,basicConfig()} should come `before' any calls to a logger's
methods such as @ref{e17,,debug()}, @ref{2beb,,info()}, etc. Otherwise,
that logging event may not be handled in the desired manner.

Si vous exécutez le script plusieurs fois, les messages des exécutions successives sont ajoutés au fichier `example.log'. Si vous voulez que chaque exécution reprenne un fichier vierge, sans conserver les messages des exécutions précédentes, vous pouvez spécifier l'argument `filemode', en changeant l'appel à l'exemple précédent par :

@example
logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
@end example

La sortie est identique à la précédente, mais le texte n'est plus ajouté au fichier de log, donc les messages des exécutions précédentes sont perdus.

@node Journalisation de données variables,Modifier le format du message affiché,Enregistrer les évènements dans un fichier,Les bases de l'utilisation du module logging
@anchor{howto/logging logging-variable-data}@anchor{4e24}
@subsubsection Journalisation de données variables


Pour enregistrer des données variables, utilisez une chaîne formatée dans le message de description de l'évènement et ajoutez les données variables comme argument. Par exemple :

@example
import logging
logging.warning('%s before you %s', 'Look', 'leap!')
@end example

affiche :

@example
WARNING:root:Look before you leap!
@end example

Comme vous pouvez le voir, l'inclusion des données variables dans le message de description de l'évènement emploie le vieux style de formatage avec %. C'est pour assurer la rétrocompatibilité : le module @code{logging} est antérieur aux nouvelles options de formatage comme @ref{60c,,str.format()} ou @ref{672,,string.Template}. Ces nouvelles options de formatage `sont' gérées, mais leur exploration sort du cadre de ce tutoriel, voyez @ref{2c0c,,Using particular formatting styles throughout your application} pour plus d'information.

@node Modifier le format du message affiché,Afficher l'horodatage dans les messages,Journalisation de données variables,Les bases de l'utilisation du module logging
@anchor{howto/logging changing-the-format-of-displayed-messages}@anchor{4e25}
@subsubsection Modifier le format du message affiché


Pour changer le format utilisé pour afficher le message, vous devez préciser le format que vous souhaitez employer :

@example
import logging
logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
logging.debug('This message should appear on the console')
logging.info('So should this')
logging.warning('And this, too')
@end example

ce qui affiche :

@example
DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too
@end example

Notez que le @code{root} qui apparaissait dans les exemples précédents a disparu. Pour voir l'ensemble des éléments qui peuvent apparaître dans la chaîne de format, référez-vous à la documentation pour @ref{2c0a,,LogRecord attributes}. Pour une utilisation simple, vous avez seulement besoin du `levelname' (la sévérité), du `message' (la description de l'évènement, avec les données variables) et peut-être du moment auquel l'évènement a eu lieu. Nous décrivons ces points dans la prochaine section.

@node Afficher l'horodatage dans les messages,Étapes suivantes,Modifier le format du message affiché,Les bases de l'utilisation du module logging
@anchor{howto/logging displaying-the-date-time-in-messages}@anchor{4e26}
@subsubsection Afficher l'horodatage dans les messages


Pour afficher la date ou le temps d'un évènement, ajoutez @code{'%(asctime)'} dans votre chaîne de formatage :

@example
import logging
logging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')
@end example

ce qui affichera quelque chose comme :

@example
2010-12-12 11:41:42,612 is when this event was logged.
@end example

Le format par défaut de l'horodatage (comme ci-dessus) est donné par la norme ISO8601 ou 
@geindex RFC; RFC 3339
RFC 3339@footnote{https://datatracker.ietf.org/doc/html/rfc3339.html}. Pour plus de contrôle sur le formatage de l'horodatage, vous pouvez fournir à @code{basicConfig} un argument `datefmt', comme dans l'exemple suivant :

@example
import logging
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
logging.warning('is when this event was logged.')
@end example

ce qui affichera quelque chose comme :

@example
12/12/2010 11:46:36 AM is when this event was logged.
@end example

Le format de `datefmt' est le même que celui de @ref{11c6,,time.strftime()}.

@node Étapes suivantes,,Afficher l'horodatage dans les messages,Les bases de l'utilisation du module logging
@anchor{howto/logging next-steps}@anchor{4e27}
@subsubsection Étapes suivantes


Nous concluons ainsi le tutoriel basique. Il devrait suffire à vous mettre le pied à l'étrier pour utiliser @code{logging}. Le module @code{logging} a beaucoup d'autre cordes à son arc, mais pour en profiter au maximum, vous devez prendre le temps de lire les sections suivantes. Si vous êtes prêt, servez-vous votre boisson préférée et poursuivons.

If your logging needs are simple, then use the above examples to incorporate
logging into your own scripts, and if you run into problems or don't
understand something, please post a question on the comp.lang.python Usenet
group (available at @indicateurl{https://groups.google.com/g/comp.lang.python}) and you
should receive help before too long.

Vous êtes encore là ? Vous pouvez lire les prochaines sections, qui donnent un peu plus de détails que l'introduction ci-dessus. Après ça, vous pouvez jeter un œil à @ref{11d4,,Recettes pour la journalisation}.

@node Usage avancé de Logging,Niveaux de journalisation<2>,Les bases de l'utilisation du module logging,Tutoriel sur la journalisation
@anchor{howto/logging advanced-logging-tutorial}@anchor{4e28}@anchor{howto/logging logging-advanced-tutorial}@anchor{11d3}
@subsection Usage avancé de Logging


La bibliothèque de journalisation adopte une approche modulaire et offre différentes catégories de composants : `loggers', `handlers', `filters' et `formatters'.


@itemize *

@item 
Les enregistreurs (`loggers' en anglais) exposent l'interface que le code de l'application utilise directement.

@item 
Les gestionnaires (`handlers') envoient les entrées de journal (créés par les `loggers') vers les destinations voulues.

@item 
Les filtres (`filters') fournissent un moyen de choisir finement quelles entrées de journal doivent être sorties.

@item 
Les formateurs (`formatters') spécifient la structure de l'entrée de journal dans la sortie finale.
@end itemize

L'information relative à un événement est passée entre `loggers', `handlers' et `formatters' dans une instance de la classe @ref{fd1,,LogRecord}.

La journalisation est réalisée en appelant les méthodes d'instance de la classe @ref{b3d,,Logger} (que l'on appelle ci-dessous `loggers'). Chaque instance a un nom et les instances sont organisées conceptuellement comme des hiérarchies dans l'espace de nommage, en utilisant un point comme séparateur. Par exemple, un `logger' appelé @code{scan} est le parent des `loggers' @code{scan.text}, @code{scan.html} et @code{scan.pdf}. Les noms des `loggers' peuvent être ce que vous voulez et indiquent le sous-domaine d'une application depuis lequel le message enregistré a été émis.

Une bonne convention lorsqu'on nomme les `loggers' est d'utiliser un `logger' au niveau du module, dans chaque module qui emploie @code{logging}, nommé de la façon suivante :

@example
logger = logging.getLogger(__name__)
@end example

Cela signifie que le nom d'un `logger' se rapporte à la hiérarchie du paquet et des modules, et il est évident de voir où un événement a été enregistré simplement en regardant le nom du `logger'.

La racine de la hiérarchie des enregistreurs est appelée le `root logger'. C'est l'enregistreur utilisé par les fonctions @ref{2bec,,debug()}, @ref{2c17,,info()}, @ref{2f3,,warning()}, @ref{2c2b,,error()} et @ref{2c2c,,critical()}, qui appelle en fait les méthodes du même nom de l'objet `root logger'. Les fonctions et les méthodes ont la même signature. Le nom de l'enregistreur racine est affiché comme « @code{'root'} » dans la sortie.

Il est bien sûr possible d'enregistrer des messages pour des destinations différentes. Ce paquet permet d'écrire des entrées de journal dans des fichiers, des ressources HTTP GET/POST, par courriel via SMTP, des connecteurs (`socket' en anglais) génériques, des files d'attente, ou des mécanismes d'enregistrement spécifiques au système d'exploitation, comme `syslog' ou le journal d'événements de Windows NT. Les destinations sont servies par des classes `handler'. Vous pouvez créer votre propre classe de destination si vous avez des besoins spéciaux qui ne sont couverts par aucune classe `handler' prédéfinie.

Par défaut, aucune destination n'est prédéfinie pour les messages de journalisation. Vous pouvez définir une destination (comme la console ou un fichier) en utilisant @ref{9ee,,basicConfig()} comme dans les exemples donnés dans le tutoriel. Si vous appelez les fonctions @ref{2bec,,debug()}, @ref{2c17,,info()}, @ref{2f3,,warning()}, @ref{2c2b,,error()} et @ref{2c2c,,critical()}, celles-ci vérifient si une destination a été définie ; si ce n'est pas le cas, la destination est assignée à la console (@code{sys.stderr}) avec un format par défaut pour le message affiché, avant d'être déléguée au `logger' racine, qui sort le message.

Le format par défaut des messages est défini par @ref{9ee,,basicConfig()} comme suit :

@example
severity:logger name:message
@end example

Vous pouvez modifier ce comportement en passant une chaîne de formatage à @ref{9ee,,basicConfig()} par l'argument nommé `format'. Consultez @ref{2c08,,Formateurs} pour toutes les options de construction de cette chaîne de formatage.

@menu
* Flux du processus de journalisation:: 
* Loggers:: 
* Handlers:: 
* Formatters:: 
* Configuration de logging:: 
* Comportement par défaut (si aucune configuration n'est fournie): Comportement par défaut si aucune configuration n'est fournie. 
* Configuration de la journalisation pour une bibliothèque:: 

@end menu

@node Flux du processus de journalisation,Loggers,,Usage avancé de Logging
@anchor{howto/logging logging-flow}@anchor{4e29}
@subsubsection Flux du processus de journalisation


Le flux des informations associées à un évènement dans les `loggers' et les `handlers' est illustré dans le diagramme suivant.

@image{python-figures/logging_flow,,,,png}

@node Loggers,Handlers,Flux du processus de journalisation,Usage avancé de Logging
@anchor{howto/logging loggers}@anchor{4e2a}
@subsubsection Loggers


Les objets de classe @ref{b3d,,Logger} ont un rôle triple. Premièrement, ils exposent plusieurs méthodes au code de l'application, de manière à ce qu'elle puisse enregistrer des messages en cours d'exécution. Deuxièmement, les objets `logger' déterminent sur quel message agir selon leur sévérité (à partir des filtres par défaut) ou selon les objets `filter' associés. Troisièmement, les objets `logger' transmettent les messages pertinents à tous les `handlers' concernés.

Les méthodes des objets `logger' les plus utilisées appartiennent à deux catégories : la configuration et l'envoi de messages.

Voici les méthodes de configuration les plus communes :


@itemize *

@item 
@ref{1445,,Logger.setLevel()} spécifie le plus bas niveau de sévérité qu'un `logger' traitera. Ainsi, @code{DEBUG} est le niveau de sévérité défini par défaut le plus bas et @code{CRITICAL} est le plus haut. Par exemple, si le niveau de sévérité est @code{INFO}, le `logger' ne traite que les messages de niveau @code{INFO}, @code{WARNING}, @code{ERROR} et @code{CRITICAL} ; il ignore les messages de niveau DEBUG.

@item 
@ref{2be6,,Logger.addHandler()} et @ref{2be7,,Logger.removeHandler()} ajoutent ou enlèvent des objets `handlers' au `logger'. Les objets `handlers' sont expliqués plus en détail dans @ref{4e2b,,Handlers}.

@item 
@ref{2bee,,Logger.addFilter()} et @ref{2bef,,Logger.removeFilter()} ajoutent ou enlèvent des objets `filter' au `logger'. Les objets `filters' sont expliqués plus en détail dans @ref{2c14,,Filtres}.
@end itemize

Comme nous l'expliquons aux deux derniers paragraphes de cette section, vous n'avez pas besoin de faire appel à ces méthodes à chaque fois que vous créez un `logger'.

Une fois que l'objet `logger' est correctement configuré, les méthodes suivantes permettent de créer un message :


@itemize *

@item 
Les méthodes @ref{e17,,Logger.debug()}, @ref{2beb,,Logger.info()}, @ref{168d,,Logger.warning()}, @ref{2bed,,Logger.error()} et @ref{e16,,Logger.critical()} créent des entrées de journal avec un message et un niveau correspondant à leur nom. Le message est en fait une chaîne de caractères qui peut contenir la syntaxe standard de substitution de chaînes de caractères : @code{%s}, @code{%d}, @code{%f}, etc. L'argument suivant est une liste des objets correspondant aux champs à substituer dans le message. En ce qui concerne @code{**kwargs}, les méthodes de @code{logging} ne tiennent compte que du mot clef @code{exc_info} et l'utilisent pour déterminer s'il faut enregistrer les informations associées à une exception.

@item 
@ref{e15,,Logger.exception()} crée un message similaire à @ref{2bed,,Logger.error()}. La différence est que @ref{e15,,Logger.exception()} ajoute la trace de la pile d'exécution au message. On ne peut appeler cette méthode qu'à l'intérieur d'un bloc de gestion d'exception.

@item 
@ref{e14,,Logger.log()} prend le niveau de sévérité comme argument explicite. C'est un peu plus verbeux pour enregistrer des messages que d'utiliser les méthodes plus pratiques décrites si dessus, mais c'est ce qui permet d'enregistrer des messages pour des niveaux de sévérité définis par l'utilisateur.
@end itemize

@ref{94d,,getLogger()} renvoie une référence à un objet `logger' du nom spécifié si celui-ci est donné en argument. Dans le cas contraire, c'est l'enregistreur racine. Les noms sont des structures hiérarchiques séparées par des points. Des appels répétés à @ref{94d,,getLogger()} avec le même nom renvoient une référence au même objet `logger'. Les `loggers' qui sont plus bas dans cette liste hiérarchique sont des enfants des `loggers' plus haut dans la liste. Par exemple, si un enregistreur a le nom @code{foo}, les enregistreurs avec les noms @code{foo.bar}, @code{foo.bar.baz} et @code{foo.bam} sont tous des descendants de @code{foo}.

On associe aux `loggers' un concept de `niveau effectif'. Si aucun niveau n'est explicitement défini pour un `logger', c'est le niveau du parent qui est utilisé comme niveau effectif. Si le parent n'a pas de niveau défini, c'est celui de `son' parent qui est considéré, et ainsi de suite ; on examine tous les ancêtres jusqu'à ce qu'un niveau explicite soit trouvé. Le `logger root' a toujours un niveau explicite (@code{WARNING} par défaut). Quand le `logger' traite un événement, c'est ce niveau effectif qui est utilisé pour déterminer si cet événement est transmis à ses `handlers'.

Les `loggers' fils font remonter leurs messages aux `handlers' associés à leurs `loggers' parents. De ce fait, il n'est pas nécessaire de définir et configurer des `handlers' pour tous les `loggers' employés par une application. Il suffit de configurer les `handlers' pour un `logger' de haut niveau et de créer des `loggers' fils quand c'est nécessaire (on peut cependant empêcher la propagation aux ancêtres des messages en donnant la valeur @code{False} à l'attribut `propagate' d'un `logger').

@node Handlers,Formatters,Loggers,Usage avancé de Logging
@anchor{howto/logging handler-basic}@anchor{4e2b}@anchor{howto/logging handlers}@anchor{4e2c}
@subsubsection Handlers


Les objets de type @ref{1448,,Handler} sont responsables de la distribution des messages (selon leur niveau de sévérité) vers les destinations spécifiées pour ce `handler'. Les objets @ref{b3d,,Logger} peuvent ajouter des objets `handler' à eux-mêmes en appelant @ref{2be6,,addHandler()}. Pour donner un exemple, une application peut envoyer tous les messages dans un fichier journal, tous les messages de niveau @code{ERROR} ou supérieur vers la sortie standard, et tous les messages de niveau @code{CRITICAL} vers une adresse de courriel. Dans ce scénario, nous avons besoin de trois `handlers', responsable chacun d'envoyer des messages d'une sévérité donnée vers une destination donnée.

La bibliothèque standard inclut déjà un bon nombre de types de gestionnaires (voir @ref{4e2d,,Gestionnaires utiles}) ; le tutoriel utilise surtout @ref{11d5,,StreamHandler} et @ref{182c,,FileHandler} dans ses exemples.

Peu de méthodes des objets `handlers' sont intéressantes pour les développeurs. Les seules méthodes intéressantes lorsqu'on utilise les objets `handlers' natifs (c'est-à-dire si l'on ne crée pas de `handler' personnalisé) sont les méthodes de configuration suivantes :


@itemize *

@item 
The @ref{2bfc,,setLevel()} method, just as in logger objects, specifies the
lowest severity that will be dispatched to the appropriate destination.  Why
are there two @ref{2bfc,,setLevel()} methods?  The level set in the logger
determines which severity of messages it will pass to its handlers.  The level
set in each handler determines which messages that handler will send on.

@item 
@ref{2bfd,,setFormatter()} sélectionne l'objet @code{Formatter} utilisé par ce @code{handler}.

@item 
@ref{2bfe,,addFilter()} et @ref{2bff,,removeFilter()} configurent et respectivement dé-configurent des objets `filter' sur les `handlers'.
@end itemize

Le code d'une application ne devrait ni instancier, ni utiliser d'instances de la classe @ref{1448,,Handler}. La classe @ref{1448,,Handler} est plutôt une classe mère qui définit l'interface que tous les gestionnaires doivent avoir et établit les comportements par défaut que les classes filles peuvent employer (ou redéfinir).

@node Formatters,Configuration de logging,Handlers,Usage avancé de Logging
@anchor{howto/logging formatters}@anchor{4e2e}
@subsubsection Formatters


Les objets `formatter' configurent l'ordre final, la structure et le contenu du message. Contrairement à la classe mère @ref{1448,,logging.Handler}, le code d'une application peut instancier un objet de classe `formatter', même si vous pouvez toujours sous-classer `formatter' si vous avez besoin d'un comportement spécial dans votre application. Le constructeur a trois arguments optionnels : une chaîne de formatage du message, une chaîne de formatage de la date et un indicateur de style.

@geindex __init__() (méthode logging.logging.Formatter)
@anchor{howto/logging logging logging Formatter __init__}@anchor{4e2f}
@deffn {Méthode} logging.Formatter.__init__ (fmt=None, datefmt=None, style='%')
@end deffn

S'il n'y a pas de chaîne de formatage, la chaîne brute est utilisée par défaut. S'il n'y a pas de chaîne de formatage de date, le format de date par défaut est :

@example
%Y-%m-%d %H:%M:%S
@end example

avec les millisecondes ajoutées à la fin. @code{style} est l'un des suivants : @code{'%'}, @code{'@{'}, ou @code{'$'}. Si l'un de ces styles n'est pas spécifié, alors @code{'%'} sera utilisé.

Si l'argument @code{style} est @code{'%'}, la chaîne de formatage utilise @code{%(<clef de dictionnaire>)s} comme style de substitution de chaîne de caractères. Les clefs possibles sont documentées dans @ref{2c0a,,LogRecord attributes}. Si le style est @code{'@{'}, le message de la chaîne de formatage est compatible avec @ref{60c,,str.format()} (en employant des arguments nommés). Enfin si le style est @code{'$'} alors la chaîne de formatage du message doit être conforme à ce qui est attendu de @ref{1c77,,string.Template.substitute()}.


Modifié dans la version 3.2: Ajout du paramètre @code{style}.


La chaîne de formatage de message suivante enregistrera le temps dans un format lisible par les humains, la sévérité du message et son contenu, dans cet ordre :

@example
'%(asctime)s - %(levelname)s - %(message)s'
@end example

Les `formatters' emploient une fonction configurable par l'utilisateur pour convertir le temps de création d'une entrée de journal en un `n'-uplet. Par défaut, @ref{14af,,time.localtime()} est employé ; pour changer cela pour une instance particulière de `formatter', assignez une fonction avec la même signature que @ref{14af,,time.localtime()} ou @ref{119d,,time.gmtime()} à l'attribut @code{converter} de cette instance. Pour changer cela pour tous les `formatters', par exemple si vous voulez que tous votre horodatage soit affiché en GMT, changez l'attribut @code{converter} de la classe @code{Formatter} en @code{time.gmtime}.

@node Configuration de logging,Comportement par défaut si aucune configuration n'est fournie,Formatters,Usage avancé de Logging
@anchor{howto/logging configuring-logging}@anchor{4e30}
@subsubsection Configuration de @code{logging}


On peut configurer @code{logging} de trois façons :


@enumerate 

@item 
Créer des `loggers', `handlers' et `formatters' explicitement en utilisant du code Python qui appelle les méthodes de configuration listées ci-dessus.

@item 
Créer un fichier de configuration de @code{logging} et le lire en employant la fonction @ref{b3f,,fileConfig()}.

@item 
Créer un dictionnaire d'informations de configuration et le passer à la fonction @ref{118d,,dictConfig()}.
@end enumerate

Pour la documentation de référence de ces deux dernières options, voyez @ref{12cf,,Configuration functions}. L'exemple suivant configure un `logger' très simple, un `handler' employant la console, et un `formatter' simple en utilisant du code Python :

@example
import logging

# create logger
logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)

# create console handler and set level to debug
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)

# create formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# add formatter to ch
ch.setFormatter(formatter)

# add ch to logger
logger.addHandler(ch)

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')
@end example

L'exécution de ce module via la ligne de commande produit la sortie suivante :

@example
$ python simple_logging_module.py
2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
2005-03-19 15:10:26,620 - simple_example - INFO - info message
2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
2005-03-19 15:10:26,697 - simple_example - ERROR - error message
2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
@end example

Le module Python suivant crée un `logger', un `handler' et un `formatter' identiques à ceux de l'exemple détaillé au-dessus, au nom des objets près :

@example
import logging
import logging.config

logging.config.fileConfig('logging.conf')

# create logger
logger = logging.getLogger('simpleExample')

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')
@end example

Voici le fichier `logging.conf' :

@example
[loggers]
keys=root,simpleExample

[handlers]
keys=consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
@end example

La sortie est presque identique à celle de l'exemple qui n'est pas basé sur un fichier de configuration :

@example
$ python simple_logging_config.py
2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
2005-03-19 15:38:55,979 - simpleExample - INFO - info message
2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
@end example

Vous pouvez constater les avantages de l'approche par fichier de configuration par rapport à celle du code Python, principalement la séparation de la configuration et du code, et la possibilité pour une personne qui ne code pas de modifier facilement les propriétés de journalisation.

@cartouche
@quotation Avertissement 
La fonction @ref{b3f,,fileConfig()} accepte un paramètre par défaut @code{disable_existing_loggers}, qui vaut @code{True} par défaut pour des raisons de compatibilité ascendante. Ce n'est pas forcément ce que vous souhaitez : en effet, tous les `loggers' créés avant l'appel à @ref{b3f,,fileConfig()} seront désactivés sauf si eux-mêmes (ou l'un de leurs parents) sont explicitement nommés dans le fichier de configuration. Veuillez vous reporter à la documentation pour plus de détails, et donner la valeur @code{False} à ce paramètre si vous le souhaitez.

Le dictionnaire passé à @ref{118d,,dictConfig()} peut aussi spécifier une valeur Booléenne pour la clef @code{disable_existing_loggers}. Si cette valeur n'est pas donnée, elle est interprétée comme vraie par défaut. Cela conduit au comportement de désactivation des `loggers' décrit ci-dessus, qui n'est pas forcément celui que vous souhaitez ; dans ce cas, donnez explicitement la valeur @code{False} à cette clef.
@end quotation
@end cartouche

Notez que les noms de classe référencés dans le fichier de configuration doivent être relatifs au module @code{logging}, ou des valeurs absolues qui peuvent être résolues à travers les mécanismes d'importation habituels. Ainsi, on peut soit utiliser @ref{2c69,,WatchedFileHandler} (relativement au module @code{logging}) ou @code{mypackage.mymodule.MyHandler} (pour une classe définie dans le paquet @code{mypackage} et le module @code{mymodule}, si @code{mypackage} est disponible dans les chemins d'importation de Python).

Dans Python 3.2, un nouveau moyen de configuration de la journalisation a été introduit, à l'aide de dictionnaires pour contenir les informations de configuration. Cela fournit un sur-ensemble de la fonctionnalité décrite ci-dessus basée sur un fichier de configuration et c’est la méthode recommandée pour les nouvelles applications et les déploiements. Étant donné qu'un dictionnaire Python est utilisé pour contenir des informations de configuration et que vous pouvez remplir ce dictionnaire à l'aide de différents moyens, vous avez plus d'options pour la configuration. Par exemple, vous pouvez utiliser un fichier de configuration au format JSON ou, si vous avez accès à la fonctionnalité de traitement YAML, un fichier au format YAML, pour remplir le dictionnaire de configuration. Ou bien sûr, vous pouvez construire le dictionnaire dans le code Python, le recevoir sous forme de `pickle' sur un connecteur, ou utiliser n'importe quelle approche suivant la logique de votre application.

Voici un exemple définissant la même configuration que ci-dessus, au format YAML  pour le dictionnaire correspondant à cette nouvelle approche :

@example
version: 1
formatters:
  simple:
    format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handlers:
  console:
    class: logging.StreamHandler
    level: DEBUG
    formatter: simple
    stream: ext://sys.stdout
loggers:
  simpleExample:
    level: DEBUG
    handlers: [console]
    propagate: no
root:
  level: DEBUG
  handlers: [console]
@end example

Pour plus d'informations sur la journalisation à l'aide d'un dictionnaire, consultez @ref{12cf,,Configuration functions}.

@node Comportement par défaut si aucune configuration n'est fournie,Configuration de la journalisation pour une bibliothèque,Configuration de logging,Usage avancé de Logging
@anchor{howto/logging what-happens-if-no-configuration-is-provided}@anchor{4e31}
@subsubsection Comportement par défaut (si aucune configuration n'est fournie)


If no logging configuration is provided, it is possible to have a situation
where a logging event needs to be output, but no handlers can be found to
output the event.

The event is output using a 'handler of last resort', stored in
@ref{11d7,,lastResort}. This internal handler is not associated with any
logger, and acts like a @ref{11d5,,StreamHandler} which writes the
event description message to the current value of @code{sys.stderr} (therefore
respecting any redirections which may be in effect). No formatting is
done on the message - just the bare event description message is printed.
The handler's level is set to @code{WARNING}, so all events at this and
greater severities will be output.


Modifié dans la version 3.2: Pour les versions de Python antérieures à 3.2, le comportement est le suivant :


@itemize *

@item 
If @ref{11d6,,raiseExceptions} is @code{False} (production mode), the event is
silently dropped.

@item 
If @ref{11d6,,raiseExceptions} is @code{True} (development mode), a message
'No handlers could be found for logger X.Y.Z' is printed once.
@end itemize

To obtain the pre-3.2 behaviour,
@ref{11d7,,lastResort} can be set to @code{None}.


@node Configuration de la journalisation pour une bibliothèque,,Comportement par défaut si aucune configuration n'est fournie,Usage avancé de Logging
@anchor{howto/logging configuring-logging-for-a-library}@anchor{4e32}@anchor{howto/logging library-config}@anchor{2c66}
@subsubsection Configuration de la journalisation pour une bibliothèque


Lors du développement d'une bibliothèque qui utilise la journalisation, vous devez prendre soin de documenter la façon dont la bibliothèque utilise la journalisation (par exemple, les noms des enregistreurs utilisés). Consacrez aussi un peu de temps à la configuration de la journalisation. Si l'application utilisant votre bibliothèque n'utilise pas la journalisation et que le code de la bibliothèque effectue des appels de journalisation, alors (comme décrit dans la section précédente), les événements de gravité @code{WARNING} et au-dessus seront écrits sur @code{sys.stderr}. Cela est considéré comme le meilleur comportement par défaut.

Si, pour une raison quelconque, vous ne voulez `pas' que ces messages soient affichés en l'absence de toute configuration de journalisation, vous pouvez attacher un gestionnaire `ne-fait-rien' à l'enregistreur de niveau supérieur de votre bibliothèque. Cela évite qu’un message ne soit écrit, puisqu’un gestionnaire sera toujours trouvé pour les événements de la bibliothèque, il ne produit tout simplement pas de sortie. Si celui qui utilise la bibliothèque configure la journalisation pour son application, il est vraisemblable que la configuration ajoutera certains gestionnaires et, si les niveaux sont convenablement configurés, alors la journalisation des appels effectués dans le code de bibliothèque enverra la sortie à ces gestionnaires, comme d'habitude.

Un gestionnaire `ne-fait-rien' est inclus dans le paquet de journalisation : @ref{1262,,NullHandler} (depuis Python 3.1). Une instance de ce gestionnaire peut être ajoutée à l'enregistreur de niveau supérieur de l'espace de nommage de journalisation utilisé par la bibliothèque (`si' vous souhaitez empêcher la copie de la journalisation de votre bibliothèque dans @code{sys.stderr} en l'absence de configuration de journalisation). Si toute la journalisation par une bibliothèque `foo' est effectuée en utilisant des enregistreurs avec des noms correspondant à `foo.x', `foo.x.y', etc., alors le code :

@example
import logging
logging.getLogger('foo').addHandler(logging.NullHandler())
@end example

doit avoir l'effet désiré. Si une organisation produit un certain nombre de bibliothèques, le nom de l'enregistreur spécifié peut être @code{orgname.foo} plutôt que simplement @code{foo}.

@cartouche
@quotation Note 
Il est fortement conseillé de `ne pas journaliser vers l'enregistreur racine' dans votre bibliothèque. À la place, utilisez un enregistreur avec un nom unique et facilement identifiable, tel que @code{__name__} pour le paquet ou le module de niveau supérieur de votre bibliothèque. La journalisation dans l'enregistreur racine rend difficile voire impossible pour le développeur de l'application de configurer la verbosité de journalisation ou les gestionnaires de votre bibliothèque comme il le souhaite.
@end quotation
@end cartouche

@cartouche
@quotation Note 
Il est vivement conseillé de ne `pas ajouter de gestionnaires autres que' @ref{1262,,NullHandler} `aux enregistreurs de votre bibliothèque'. Cela est dû au fait que la configuration des gestionnaires est la prérogative du développeur d'applications qui utilise votre bibliothèque. Le développeur d'applications connaît le public cible et les gestionnaires les plus appropriés pour ses applications : si vous ajoutez des gestionnaires « sous le manteau », vous pourriez bien interférer avec les tests unitaires et la journalisation qui convient à ses exigences.
@end quotation
@end cartouche

@node Niveaux de journalisation<2>,Gestionnaires utiles,Usage avancé de Logging,Tutoriel sur la journalisation
@anchor{howto/logging logging-levels}@anchor{4e33}
@subsection Niveaux de journalisation


Les valeurs numériques des niveaux de journalisation sont données dans le tableau suivant. Celles-ci n'ont d'intérêt que si vous voulez définir vos propres niveaux, avec des valeurs spécifiques par rapport aux niveaux prédéfinis. Si vous définissez un niveau avec la même valeur numérique, il écrase la valeur prédéfinie ; le nom prédéfini est perdu.


@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} 
@headitem

Niveau

@tab

Valeur numérique

@item

@code{CRITICAL}

@tab

50

@item

@code{ERROR}

@tab

40

@item

@code{WARNING}

@tab

30

@item

@code{INFO}

@tab

20

@item

@code{DEBUG}

@tab

10

@item

@code{NOTSET}

@tab

0

@end multitable


Les niveaux peuvent également être associés à des enregistreurs, étant définis soit par le développeur, soit par le chargement d'une configuration de journalisation enregistrée. Lorsqu'une méthode de journalisation est appelée sur un enregistreur, l'enregistreur compare son propre niveau avec le niveau associé à l'appel de méthode. Si le niveau de l'enregistreur est supérieur à l'appel de méthode, aucun message de journalisation n'est réellement généré. C'est le mécanisme de base contrôlant la verbosité de la sortie de journalisation.

Les messages de journalisation sont codés en tant qu'instances de @ref{fd1,,LogRecord}. Lorsqu'un enregistreur décide de réellement enregistrer un événement, une instance de @ref{fd1,,LogRecord} est créée à partir du message de journalisation.

Les messages de journalisation sont soumis à un mécanisme d'expédition via l'utilisation de `handlers', qui sont des instances de sous-classes de la classe @ref{1448,,Handler}. Les gestionnaires sont chargés de s'assurer qu'un message journalisé (sous la forme d'un @ref{fd1,,LogRecord}) atterrit dans un emplacement particulier (ou un ensemble d'emplacements) qui est utile pour le public cible pour ce message (tels que les utilisateurs finaux, le personnel chargé de l'assistance aux utilisateurs, les administrateurs système ou les développeurs). Des instances de @ref{fd1,,LogRecord} adaptées à leur destination finale sont passées aux gestionnaires destinées à des destinations particulières. Chaque enregistreur peut avoir zéro, un ou plusieurs gestionnaires associés à celui-ci (via la méthode @ref{2be6,,addHandler()} de @ref{b3d,,Logger}). En plus de tous les gestionnaires directement associés à un enregistreur, `tous les gestionnaires associés à tous les ancêtres de l'enregistreur' sont appelés pour envoyer le message (à moins que l'indicateur `propager' pour un enregistreur soit défini sur la valeur @code{False}, auquel cas le passage au gestionnaire ancêtre s'arrête).

Tout comme pour les enregistreurs, les gestionnaires peuvent avoir des niveaux associés. Le niveau d'un gestionnaire agit comme un filtre de la même manière que le niveau d'un enregistreur. Si un gestionnaire décide de réellement distribuer un événement, la méthode @ref{2c06,,emit()} est utilisée pour envoyer le message à sa destination. La plupart des sous-classes définies par l'utilisateur de @ref{1448,,Handler} devront remplacer ce @ref{2c06,,emit()}.

@menu
* Niveaux personnalisés:: 

@end menu

@node Niveaux personnalisés,,,Niveaux de journalisation<2>
@anchor{howto/logging custom-levels}@anchor{2c30}@anchor{howto/logging id2}@anchor{4e34}
@subsubsection Niveaux personnalisés


La définition de vos propres niveaux est possible, mais ne devrait pas être nécessaire, car les niveaux existants ont été choisis par expérience. Cependant, si vous êtes convaincu que vous avez besoin de niveaux personnalisés, prenez grand soin à leur réalisation et il est pratiquement certain que c’est `une très mauvaise idée de définir des niveaux personnalisés si vous développez une bibliothèque'. Car si plusieurs auteurs de bibliothèque définissent tous leurs propres niveaux personnalisés, il y a une chance que la sortie de journalisation de ces multiples bibliothèques utilisées ensemble sera difficile pour le développeur à utiliser pour contrôler et/ou interpréter, car une valeur numérique donnée peut signifier des choses différentes pour différentes bibliothèques.

@node Gestionnaires utiles,Exceptions levées par la journalisation,Niveaux de journalisation<2>,Tutoriel sur la journalisation
@anchor{howto/logging id3}@anchor{4e35}@anchor{howto/logging useful-handlers}@anchor{4e2d}
@subsection Gestionnaires utiles


En plus de la classe mère @ref{1448,,Handler}, de nombreuses sous-classes utiles sont fournies :


@enumerate 

@item 
Les instances @ref{11d5,,StreamHandler} envoient des messages aux flux (objets de type fichier).

@item 
Les instances @ref{182c,,FileHandler} envoient des messages à des fichiers sur le disque.

@item 
@ref{2c6d,,BaseRotatingHandler} est la classe mère pour les gestionnaires qui assurent la rotation des fichiers de journalisation à partir d’un certain point. Elle n'est pas destinée à être instanciée directement. Utilisez plutôt @ref{1560,,RotatingFileHandler} ou @ref{f4c,,TimedRotatingFileHandler}.

@item 
Les instances @ref{1560,,RotatingFileHandler} envoient des messages à des fichiers sur le disque, avec la prise en charge des tailles maximales de fichiers de journalisation et de la rotation des fichiers de journalisation.

@item 
Les instances de @ref{f4c,,TimedRotatingFileHandler} envoient des messages aux fichiers de disque, en permutant le fichier journal à intervalles réguliers.

@item 
Les instances de @ref{f4d,,SocketHandler} envoient des messages aux connecteurs TCP/IP. Depuis 3.4, les connecteurs UNIX sont également pris en charge.

@item 
Les instances de @ref{f4e,,DatagramHandler} envoient des messages aux connecteurs UDP. Depuis 3.4, les connecteurs UNIX sont également pris en charge.

@item 
Les instances de @ref{2c99,,SMTPHandler} envoient des messages à une adresse e-mail désignée.

@item 
Les instances de @ref{647,,SysLogHandler} envoient des messages à un `daemon' `syslog' UNIX, éventuellement sur un ordinateur distant.

@item 
Les instances de @ref{2c91,,NTEventLogHandler} envoient des messages à un journal des événements Windows NT/2000/XP.

@item 
Les instances de @ref{2c4d,,MemoryHandler} envoient des messages à un tampon en mémoire, qui est vidé chaque fois que des critères spécifiques sont remplis.

@item 
Les instances de @ref{e18,,HTTPHandler} envoient des messages à un serveur HTTP à l'aide de la sémantique @code{GET} ou @code{POST}.

@item 
Les instances de @ref{2c69,,WatchedFileHandler} surveillent le fichier sur lequel elles se connectent. Si le fichier change, il est fermé et rouvert à l'aide du nom de fichier. Ce gestionnaire n'est utile que sur les systèmes de type UNIX ; Windows ne prend pas en charge le mécanisme sous-jacent utilisé.

@item 
Les instances de @ref{1765,,QueueHandler} envoient des messages à une file d'attente, telles que celles implémentées dans les modules @ref{b5,,queue} ou @ref{93,,multiprocessing}.

@item 
@ref{1262,,NullHandler} instances do nothing with error messages. They are used
by library developers who want to use logging, but want to avoid the 'No
handlers could be found for logger `XXX'' message which can be displayed if
the library user has not configured logging. See @ref{2c66,,Configuration de la journalisation pour une bibliothèque} for
more information.
@end enumerate


Ajouté dans la version 3.1: La classe @ref{1262,,NullHandler}.



Ajouté dans la version 3.2: La classe @ref{1765,,QueueHandler}.


Les classes @ref{1262,,NullHandler}, @ref{11d5,,StreamHandler} et @ref{182c,,FileHandler} sont définies dans le module de journalisation de base. Les autres gestionnaires sont définis dans un sous-module, @ref{88,,logging.handlers} (il existe également un autre sous-module, @ref{87,,logging.config}, pour la fonctionnalité de configuration).

Les messages journalisés sont mis en forme pour la présentation via des instances de la classe @ref{1449,,Formatter}. Ils sont initialisés avec une chaîne de format appropriée pour une utilisation avec l'opérateur % et un dictionnaire.

For formatting multiple messages in a batch, instances of
@ref{2c10,,BufferingFormatter} can be used. In addition to the format
string (which is applied to each message in the batch), there is provision for
header and trailer format strings.

Lorsque le filtrage basé sur le niveau de l'enregistreur et/ou le niveau du gestionnaire ne suffit pas, les instances de @ref{11d8,,Filter} peuvent être ajoutées aux deux instances de @ref{b3d,,Logger} et @ref{1448,,Handler} (par le biais de leur méthode @ref{2bfe,,addFilter()}). Avant de décider de traiter un message plus loin, les enregistreurs et les gestionnaires consultent tous leurs filtres pour obtenir l'autorisation. Si un filtre renvoie une valeur @code{False}, le traitement du message est arrêté.

La fonctionnalité de base @ref{11d8,,Filter} permet de filtrer par nom de `logger' spécifique. Si cette fonctionnalité est utilisée, les messages envoyés à l'enregistreur nommé et à ses enfants sont autorisés via le filtre et tous les autres sont abandonnés.

@node Exceptions levées par la journalisation,Utilisation d'objets arbitraires comme messages,Gestionnaires utiles,Tutoriel sur la journalisation
@anchor{howto/logging exceptions-raised-during-logging}@anchor{4e36}@anchor{howto/logging logging-exceptions}@anchor{4e37}
@subsection Exceptions levées par la journalisation


Le paquet de journalisation est conçu pour ne pas faire apparaître les exceptions qui se produisent lors de la journalisation en production. Il s'agit de sorte que les erreurs qui se produisent lors de la gestion des événements de journalisation (telles qu'une mauvaise configuration de la journalisation, une erreur réseau ou d'autres erreurs similaires) ne provoquent pas l'arrêt de l'application utilisant la journalisation.

Les exceptions @ref{d2e,,SystemExit} et @ref{9bf,,KeyboardInterrupt} ne sont jamais passées sous silence. Les autres exceptions qui se produisent pendant la méthode @ref{2c06,,emit()} d'une sous-classe @ref{1448,,Handler} sont passées à sa méthode @ref{2c05,,handleError()}.

L'implémentation par défaut de @ref{2c05,,handleError()} dans la classe @ref{1448,,Handler} vérifie si une variable au niveau du module, @ref{11d6,,raiseExceptions}, est définie. Si cette valeur est définie, la trace de la pile d'appels est affichée sur @ref{926,,sys.stderr}. Si elle n'est pas définie, l'exception est passée sous silence.

@cartouche
@quotation Note 
La valeur par défaut de @ref{11d6,,raiseExceptions} est @code{True}. C'est parce que pendant le développement, vous voulez généralement être notifié de toutes les exceptions qui se produisent. Il est conseillé de définir @ref{11d6,,raiseExceptions} à @code{False} pour une utilisation en production.
@end quotation
@end cartouche

@node Utilisation d'objets arbitraires comme messages,Optimisation,Exceptions levées par la journalisation,Tutoriel sur la journalisation
@anchor{howto/logging arbitrary-object-messages}@anchor{2c1c}@anchor{howto/logging using-arbitrary-objects-as-messages}@anchor{4e38}
@subsection Utilisation d'objets arbitraires comme messages


Dans les sections et exemples précédents, il a été supposé que le message passé lors de la journalisation de l'événement est une chaîne. Cependant, ce n'est pas la seule possibilité. Vous pouvez passer un objet arbitraire en tant que message et sa méthode @ref{608,,__str__()} est appelée lorsque le système de journalisation doit le convertir en une représentation sous forme de chaîne. En fait, si vous le souhaitez, vous pouvez complètement éviter de calculer une représentation sous forme de chaîne. Par exemple, les gestionnaires @ref{f4d,,SocketHandler} émettent un événement en lui appliquant `pickle' et en l'envoyant sur le réseau.

@node Optimisation,Autres ressources<2>,Utilisation d'objets arbitraires comme messages,Tutoriel sur la journalisation
@anchor{howto/logging optimization}@anchor{4e39}
@subsection Optimisation


La mise en forme des arguments de message est différée jusqu'à ce qu'elle ne puisse pas être évitée. Toutefois, le calcul des arguments passés à la méthode de journalisation peut également être coûteux et vous voudrez peut-être éviter de le faire si l'enregistreur va simplement jeter votre événement. Pour décider de ce qu'il faut faire, vous pouvez appeler la méthode @ref{12d4,,isEnabledFor()} qui prend en argument le niveau et renvoie @code{True} si un événement est créé par l'enregistreur pour ce niveau d'appel. Vous pouvez écrire un code qui ressemble à ça :

@example
if logger.isEnabledFor(logging.DEBUG):
    logger.debug('Message with %s, %s', expensive_func1(),
                                        expensive_func2())
@end example

so that if the logger's threshold is set above @code{DEBUG}, the calls to
@code{expensive_func1} and @code{expensive_func2} are never made.

@cartouche
@quotation Note 
Dans certains cas, @ref{12d4,,isEnabledFor()} peut être plus coûteux que vous le souhaitez (par exemple pour les enregistreurs profondément imbriqués où un niveau explicite n'est défini que dans la hiérarchie des enregistreurs). Dans de tels cas (ou si vous souhaitez éviter d'appeler une méthode dans des boucles optimisées), vous pouvez mettre en cache le résultat d'un appel à @ref{12d4,,isEnabledFor()} dans une variable locale ou d'instance, et l'utiliser au lieu d'appeler la méthode à chaque fois. Une telle valeur mise en cache ne doit être recalculée que lorsque la configuration de journalisation change dynamiquement pendant l'exécution de l'application (ce qui est rarement le cas).
@end quotation
@end cartouche

Il existe d'autres optimisations qui peuvent être faites pour des applications spécifiques qui nécessitent un contrôle plus précis sur les informations de journalisation collectées. Voici une liste de choses que vous pouvez faire pour éviter le traitement pendant la journalisation dont vous n'avez pas besoin :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Ce que vous ne voulez pas collecter

@tab

Comment éviter de le collecter

@item

Informations sur l'endroit où les appels ont été faits.

@tab

Définissez @code{logging._srcfile} à @code{None}. Cela évite d'appeler @ref{6cb,,sys._getframe()}, qui peut aider à accélérer votre code dans des environnements comme PyPy (qui ne peut pas accélérer le code qui utilise @ref{6cb,,sys._getframe()}).

@item

Informations de `threading'.

@tab

Mettez @code{logging.logThreads} à @code{False}.

@item

Identifiant du processus courant (résultat de @ref{2a88,,os.getpid()})

@tab

Mettez @code{logging.logProcesses} à @code{False}.

@item

Nom du processus actuel, si vous vous servez de @code{multiprocessing} pour gérer plusieurs processus à la fois

@tab

Mettez @code{logging.logMultiProcessing} à @code{False}.

@item

Current @ref{4c2,,asyncio.Task} name when using
@code{asyncio}.

@tab

Set @code{logging.logAsyncioTasks} to @code{False}.

@end multitable


Notez également que le module de journalisation principale inclut uniquement les gestionnaires de base. Si vous n'importez pas @ref{88,,logging.handlers} et @ref{87,,logging.config}, ils ne prendront pas de mémoire.

@node Autres ressources<2>,,Optimisation,Tutoriel sur la journalisation
@anchor{howto/logging other-resources}@anchor{4e3a}@anchor{howto/logging tutorial-ref-links}@anchor{4e1e}
@subsection Autres ressources



@subsubheading Voir aussi



@table @asis

@item Module @ref{86,,logging}

Référence d'API pour le module de journalisation.

@item Module @ref{87,,logging.config}

API de configuration pour le module de journalisation.

@item Module @ref{88,,logging.handlers}

Gestionnaires utiles inclus avec le module de journalisation.
@end table

@ref{11d4,,A logging cookbook}


@node Recettes pour la journalisation,Guide des expressions régulières,Tutoriel sur la journalisation,Les HOWTOs de Python
@anchor{howto/logging-cookbook doc}@anchor{4e3b}@anchor{howto/logging-cookbook id1}@anchor{4e3c}@anchor{howto/logging-cookbook logging-cookbook}@anchor{11d4}
@section Recettes pour la journalisation


@*Auteur: 
Vinay Sajip <vinay_sajip at red-dove dot com>


Cette page contient des recettes relatives à la journalisation qui se sont avérées utiles par le passé. Pour des liens vers le tutoriel et des informations de référence, consultez @ref{4e3d,,ces autres ressources}.

@menu
* Journalisation dans plusieurs modules:: 
* Journalisation avec des fils d’exécution multiples:: 
* Plusieurs gestionnaires et formateurs:: 
* Journalisation vers plusieurs destinations:: 
* Personnalisation du niveau de journalisation:: 
* Exemple d’un serveur de configuration:: 
* Utilisation de gestionnaires bloquants:: 
* Envoi et réception d’événements de journalisation à travers le réseau:: 
* Ajout d’informations contextuelles dans la journalisation:: 
* Use of contextvars:: 
* Ajout d'informations contextuelles dans la journalisation:: 
* Journalisation vers un fichier unique à partir de plusieurs processus:: 
* Utilisation du roulement de fichiers:: 
* Utilisation d’autres styles de formatage:: 
* Personnalisation de LogRecord:: 
* Subclassing QueueHandler and QueueListener- a ZeroMQ example:: 
* Subclassing QueueHandler and QueueListener- a pynng example:: 
* Exemple de configuration basée sur un dictionnaire:: 
* Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux:: 
* Exemple plus élaboré avec traitement en parallèle:: 
* Insertion d’une BOM dans les messages envoyés à un SysLogHandler:: 
* Journalisation structurée:: 
* Personnalisation des gestionnaires avec dictConfig(): Personnalisation des gestionnaires avec dictConfig. 
* Using particular formatting styles throughout your application:: 
* Configuring filters with dictConfig(): Configuring filters with dictConfig. 
* Customized exception formatting:: 
* Speaking logging messages:: 
* Buffering logging messages and outputting them conditionally:: 
* Sending logging messages to email@comma{} with buffering: Sending logging messages to email with buffering. 
* Formatting times using UTC (GMT) via configuration: Formatting times using UTC GMT via configuration. 
* Using a context manager for selective logging:: 
* A CLI application starter template:: 
* A Qt GUI for logging:: 
* Logging to syslog with RFC5424 support:: 
* How to treat a logger like an output stream:: 
* Patterns to avoid:: 
* Autres ressources: Autres ressources<3>. 

@end menu

@node Journalisation dans plusieurs modules,Journalisation avec des fils d’exécution multiples,,Recettes pour la journalisation
@anchor{howto/logging-cookbook using-logging-in-multiple-modules}@anchor{4e3e}
@subsection Journalisation dans plusieurs modules


Deux appels à  @code{logging.getLogger('unLogger')} renvoient toujours une référence vers le même objet de journalisation. C’est valable à l’intérieur d’un module, mais aussi dans des modules différents pour autant que ce soit le même processus de l’interpréteur Python. En plus, le code d’une application peut définir et configurer une journalisation parente dans un module et créer (mais pas configurer) une journalisation fille dans un module séparé. Les appels à la journalisation fille passeront alors à la journalisation parente. Voici un module principal :

@example
import logging
import auxiliary_module

# create logger with 'spam_application'
logger = logging.getLogger('spam_application')
logger.setLevel(logging.DEBUG)
# create file handler which logs even debug messages
fh = logging.FileHandler('spam.log')
fh.setLevel(logging.DEBUG)
# create console handler with a higher log level
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# create formatter and add it to the handlers
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
fh.setFormatter(formatter)
ch.setFormatter(formatter)
# add the handlers to the logger
logger.addHandler(fh)
logger.addHandler(ch)

logger.info('creating an instance of auxiliary_module.Auxiliary')
a = auxiliary_module.Auxiliary()
logger.info('created an instance of auxiliary_module.Auxiliary')
logger.info('calling auxiliary_module.Auxiliary.do_something')
a.do_something()
logger.info('finished auxiliary_module.Auxiliary.do_something')
logger.info('calling auxiliary_module.some_function()')
auxiliary_module.some_function()
logger.info('done with auxiliary_module.some_function()')
@end example

Voici un module auxiliaire :

@example
import logging

# create logger
module_logger = logging.getLogger('spam_application.auxiliary')

class Auxiliary:
    def __init__(self):
        self.logger = logging.getLogger('spam_application.auxiliary.Auxiliary')
        self.logger.info('creating an instance of Auxiliary')

    def do_something(self):
        self.logger.info('doing something')
        a = 1 + 1
        self.logger.info('done doing something')

def some_function():
    module_logger.info('received a call to "some_function"')
@end example

La sortie ressemble à ceci :

@example
2005-03-23 23:47:11,663 - spam_application - INFO -
   creating an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
   creating an instance of Auxiliary
2005-03-23 23:47:11,665 - spam_application - INFO -
   created an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,668 - spam_application - INFO -
   calling auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
   doing something
2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
   done doing something
2005-03-23 23:47:11,670 - spam_application - INFO -
   finished auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,671 - spam_application - INFO -
   calling auxiliary_module.some_function()
2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
   received a call to 'some_function'
2005-03-23 23:47:11,673 - spam_application - INFO -
   done with auxiliary_module.some_function()
@end example

@node Journalisation avec des fils d’exécution multiples,Plusieurs gestionnaires et formateurs,Journalisation dans plusieurs modules,Recettes pour la journalisation
@anchor{howto/logging-cookbook logging-from-multiple-threads}@anchor{4e3f}
@subsection Journalisation avec des fils d’exécution multiples


La journalisation avec des fils d’exécution multiples ne requiert pas d’effort particulier. L’exemple suivant montre comment journaliser depuis le fil principal (c.-à-d. initial) et un autre fil :

@example
import logging
import threading
import time

def worker(arg):
    while not arg['stop']:
        logging.debug('Hi from myfunc')
        time.sleep(0.5)

def main():
    logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %(threadName)s %(message)s')
    info = @{'stop': False@}
    thread = threading.Thread(target=worker, args=(info,))
    thread.start()
    while True:
        try:
            logging.debug('Hello from main')
            time.sleep(0.75)
        except KeyboardInterrupt:
            info['stop'] = True
            break
    thread.join()

if __name__ == '__main__':
    main()
@end example

À l’exécution, le script doit afficher quelque chose comme ça :

@example
   0 Thread-1 Hi from myfunc
   3 MainThread Hello from main
 505 Thread-1 Hi from myfunc
 755 MainThread Hello from main
1007 Thread-1 Hi from myfunc
1507 MainThread Hello from main
1508 Thread-1 Hi from myfunc
2010 Thread-1 Hi from myfunc
2258 MainThread Hello from main
2512 Thread-1 Hi from myfunc
3009 MainThread Hello from main
3013 Thread-1 Hi from myfunc
3515 Thread-1 Hi from myfunc
3761 MainThread Hello from main
4017 Thread-1 Hi from myfunc
4513 MainThread Hello from main
4518 Thread-1 Hi from myfunc
@end example

Les entrées de journalisation sont entrelacées, comme on pouvait s’y attendre. Cette approche fonctionne aussi avec plus de fils que dans l’exemple, bien sûr.

@node Plusieurs gestionnaires et formateurs,Journalisation vers plusieurs destinations,Journalisation avec des fils d’exécution multiples,Recettes pour la journalisation
@anchor{howto/logging-cookbook multiple-handlers-and-formatters}@anchor{4e40}
@subsection Plusieurs gestionnaires et formateurs


Les gestionnaires de journalisation sont des objets Python ordinaires. La méthode @ref{2be6,,addHandler()} n’est pas limitée, en nombre minimum ou maximum, en gestionnaires que vous pouvez ajouter. Parfois, il peut être utile pour une application de journaliser tous les messages quels que soient leurs niveaux vers un fichier texte, tout en journalisant les erreurs (et plus grave) dans la console. Pour ce faire, configurez simplement les gestionnaires de manière adéquate. Les appels de journalisation dans le code de l’application resteront les mêmes. Voici une légère modification de l’exemple précédent dans une configuration au niveau du module :

@example
import logging

logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)
# create file handler which logs even debug messages
fh = logging.FileHandler('spam.log')
fh.setLevel(logging.DEBUG)
# create console handler with a higher log level
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# create formatter and add it to the handlers
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
ch.setFormatter(formatter)
fh.setFormatter(formatter)
# add the handlers to logger
logger.addHandler(ch)
logger.addHandler(fh)

# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warning('warn message')
logger.error('error message')
logger.critical('critical message')
@end example

Notez que le code de « l’application » ignore la multiplicité des gestionnaires. Les modifications consistent simplement en l’ajout et la configuration d’un nouveau gestionnaire appelé `fh'.

La possibilité de créer de nouveaux gestionnaires avec des filtres sur un niveau de gravité supérieur ou inférieur peut être très utile lors de l’écriture ou du test d’une application. Au lieu d’utiliser de nombreuses instructions @code{print} pour le débogage, utilisez @code{logger.debug} : contrairement aux instructions @code{print}, que vous devrez supprimer ou commenter plus tard, les instructions @code{logger.debug} peuvent demeurer telles quelles dans le code source et restent dormantes jusqu’à ce que vous en ayez à nouveau besoin. À ce moment-là, il suffit de modifier le niveau de gravité de la journalisation ou du gestionnaire pour déboguer.

@node Journalisation vers plusieurs destinations,Personnalisation du niveau de journalisation,Plusieurs gestionnaires et formateurs,Recettes pour la journalisation
@anchor{howto/logging-cookbook logging-to-multiple-destinations}@anchor{4e41}@anchor{howto/logging-cookbook multiple-destinations}@anchor{4e42}
@subsection Journalisation vers plusieurs destinations


Supposons que vous souhaitiez journaliser dans la console et dans un fichier avec différents formats de messages et avec différents critères. Supposons que vous souhaitiez consigner les messages de niveau DEBUG et supérieur dans le fichier, et les messages de niveau INFO et supérieur dans la console. Supposons également que le fichier doive contenir des horodatages, mais pas les messages de la console. Voici comment y parvenir :

@example
import logging

# set up logging to file - see previous section for more details
logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
                    datefmt='%m-%d %H:%M',
                    filename='/tmp/myapp.log',
                    filemode='w')
# define a Handler which writes INFO messages or higher to the sys.stderr
console = logging.StreamHandler()
console.setLevel(logging.INFO)
# set a format which is simpler for console use
formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
# tell the handler to use this format
console.setFormatter(formatter)
# add the handler to the root logger
logging.getLogger('@w{'}).addHandler(console)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')
@end example

Quand vous le lancez, vous devez voir

@example
root        : INFO     Jackdaws love my big sphinx of quartz.
myapp.area1 : INFO     How quickly daft jumping zebras vex.
myapp.area2 : WARNING  Jail zesty vixen who grabbed pay from quack.
myapp.area2 : ERROR    The five boxing wizards jump quickly.
@end example

et, dans le fichier, vous devez trouver

@example
10-22 22:19 root         INFO     Jackdaws love my big sphinx of quartz.
10-22 22:19 myapp.area1  DEBUG    Quick zephyrs blow, vexing daft Jim.
10-22 22:19 myapp.area1  INFO     How quickly daft jumping zebras vex.
10-22 22:19 myapp.area2  WARNING  Jail zesty vixen who grabbed pay from quack.
10-22 22:19 myapp.area2  ERROR    The five boxing wizards jump quickly.
@end example

Comme vous pouvez le constater, le message DEBUG n’apparaît que dans le fichier. Les autres messages sont envoyés vers les deux destinations.

Cet exemple utilise la console et des gestionnaires de fichier, mais vous pouvez utiliser et combiner autant de gestionnaires que de besoin.

Notez que le choix du nom de fichier journal @code{/tmp/myapp.log} ci-dessus implique l'utilisation d'un emplacement standard pour les fichiers temporaires sur les systèmes POSIX. Sous Windows, vous devrez peut-être choisir un nom de répertoire différent pour le journal – assurez-vous simplement que le répertoire existe et que vous disposez des autorisations nécessaires pour créer et mettre à jour des fichiers dans celui-ci.

@node Personnalisation du niveau de journalisation,Exemple d’un serveur de configuration,Journalisation vers plusieurs destinations,Recettes pour la journalisation
@anchor{howto/logging-cookbook custom-handling-of-levels}@anchor{4e43}@anchor{howto/logging-cookbook custom-level-handling}@anchor{4e44}
@subsection Personnalisation du niveau de journalisation


Il peut arriver que vous souhaitiez que vos gestionnaires journalisent légèrement différemment de la gestion standard des niveaux, où tous les niveaux au-dessus d'un seuil sont traités par un gestionnaire. Pour ce faire, vous devez utiliser des filtres. Examinons un scénario dans lequel vous souhaitez organiser les choses comme suit :


@itemize *

@item 
envoyer les messages de niveau @code{INFO} et @code{WARNING} à @code{sys.stdout} ;

@item 
envoyer les messages de niveau @code{ERROR} et au-dessus à @code{sys.stderr} ;

@item 
envoyer les messages de niveau @code{DEBUG} et au-dessus vers le fichier @code{app.log}.
@end itemize

Supposons que vous configurez la journalisation avec le contenu au format JSON suivant :

@example
@{
    "version": 1,
    "disable_existing_loggers": false,
    "formatters": @{
        "simple": @{
            "format": "%(levelname)-8s - %(message)s"
        @}
    @},
    "handlers": @{
        "stdout": @{
            "class": "logging.StreamHandler",
            "level": "INFO",
            "formatter": "simple",
            "stream": "ext://sys.stdout"
        @},
        "stderr": @{
            "class": "logging.StreamHandler",
            "level": "ERROR",
            "formatter": "simple",
            "stream": "ext://sys.stderr"
        @},
        "file": @{
            "class": "logging.FileHandler",
            "formatter": "simple",
            "filename": "app.log",
            "mode": "w"
        @}
    @},
    "root": @{
        "level": "DEBUG",
        "handlers": [
            "stderr",
            "stdout",
            "file"
        ]
    @}
@}
@end example

This configuration does `almost' what we want, except that @code{sys.stdout} would show messages
of severity @code{ERROR} and only events of this severity and higher will be tracked
as well as @code{INFO} and @code{WARNING} messages. To prevent this, we can set up a filter which
excludes those messages and add it to the relevant handler. This can be configured by
adding a @code{filters} section parallel to @code{formatters} and @code{handlers}:

@example
@{
    "filters": @{
        "warnings_and_below": @{
            "()" : "__main__.filter_maker",
            "level": "WARNING"
        @}
    @}
@}
@end example

et en changeant la section du gestionnaire @code{stdout} pour ajouter le filtre :

@example
@{
    "stdout": @{
        "class": "logging.StreamHandler",
        "level": "INFO",
        "formatter": "simple",
        "stream": "ext://sys.stdout",
        "filters": ["warnings_and_below"]
    @}
@}
@end example

Un filtre n'est qu'une fonction, nous pouvons donc définir un @code{filter_maker} (une fonction fabrique) comme suit :

@example
def filter_maker(level):
    level = getattr(logging, level)

    def filter(record):
        return record.levelno <= level

    return filter
@end example

Elle convertit la chaîne transmise en argument vers un niveau numérique puis renvoie une fonction qui ne renvoie @code{True} que si le niveau de l'enregistrement transmis est inférieur ou égal au niveau spécifié. Notez que dans cet exemple, nous avons défini @code{filter_maker} dans un script de test @code{main.py} qui est exécuté depuis la ligne de commande, donc son module est @code{__main__} – d'où le @code{__main__.filter_maker} dans la configuration du filtre. Vous devez le changer si vous la définissez dans un module différent.

Avec le filtre, nous pouvons exécuter @code{main.py} dont voici la version complète :

@example
import json
import logging
import logging.config

CONFIG = '@w{'}'
@{
    "version": 1,
    "disable_existing_loggers": false,
    "formatters": @{
        "simple": @{
            "format": "%(levelname)-8s - %(message)s"
        @}
    @},
    "filters": @{
        "warnings_and_below": @{
            "()" : "__main__.filter_maker",
            "level": "WARNING"
        @}
    @},
    "handlers": @{
        "stdout": @{
            "class": "logging.StreamHandler",
            "level": "INFO",
            "formatter": "simple",
            "stream": "ext://sys.stdout",
            "filters": ["warnings_and_below"]
        @},
        "stderr": @{
            "class": "logging.StreamHandler",
            "level": "ERROR",
            "formatter": "simple",
            "stream": "ext://sys.stderr"
        @},
        "file": @{
            "class": "logging.FileHandler",
            "formatter": "simple",
            "filename": "app.log",
            "mode": "w"
        @}
    @},
    "root": @{
        "level": "DEBUG",
        "handlers": [
            "stderr",
            "stdout",
            "file"
        ]
    @}
@}
'@w{'}'

def filter_maker(level):
    level = getattr(logging, level)

    def filter(record):
        return record.levelno <= level

    return filter

logging.config.dictConfig(json.loads(CONFIG))
logging.debug('A DEBUG message')
logging.info('An INFO message')
logging.warning('A WARNING message')
logging.error('An ERROR message')
logging.critical('A CRITICAL message')
@end example

Et après l'avoir exécuté comme ceci :

@example
python main.py 2>stderr.log >stdout.log
@end example

Nous obtenons le résultat attendu :

@example
$ more *.log
::::::::::::::
app.log
::::::::::::::
DEBUG    - A DEBUG message
INFO     - An INFO message
WARNING  - A WARNING message
ERROR    - An ERROR message
CRITICAL - A CRITICAL message
::::::::::::::
stderr.log
::::::::::::::
ERROR    - An ERROR message
CRITICAL - A CRITICAL message
::::::::::::::
stdout.log
::::::::::::::
INFO     - An INFO message
WARNING  - A WARNING message
@end example

@node Exemple d’un serveur de configuration,Utilisation de gestionnaires bloquants,Personnalisation du niveau de journalisation,Recettes pour la journalisation
@anchor{howto/logging-cookbook configuration-server-example}@anchor{4e45}
@subsection Exemple d’un serveur de configuration


Voici un exemple de module mettant en œuvre la configuration de la journalisation `via' un serveur :

@example
import logging
import logging.config
import time
import os

# read initial config file
logging.config.fileConfig('logging.conf')

# create and start listener on port 9999
t = logging.config.listen(9999)
t.start()

logger = logging.getLogger('simpleExample')

try:
    # loop through logging calls to see the difference
    # new configurations make, until Ctrl+C is pressed
    while True:
        logger.debug('debug message')
        logger.info('info message')
        logger.warning('warn message')
        logger.error('error message')
        logger.critical('critical message')
        time.sleep(5)
except KeyboardInterrupt:
    # cleanup
    logging.config.stopListening()
    t.join()
@end example

Et voici un script qui, à partir d’un nom de fichier, commence par envoyer la taille du fichier encodée en binaire (comme il se doit), puis envoie ce fichier au serveur pour définir la nouvelle configuration de journalisation :

@example
#!/usr/bin/env python
import socket, sys, struct

with open(sys.argv[1], 'rb') as f:
    data_to_send = f.read()

HOST = 'localhost'
PORT = 9999
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
print('connecting...')
s.connect((HOST, PORT))
print('sending config...')
s.send(struct.pack('>L', len(data_to_send)))
s.send(data_to_send)
s.close()
print('complete')
@end example

@node Utilisation de gestionnaires bloquants,Envoi et réception d’événements de journalisation à travers le réseau,Exemple d’un serveur de configuration,Recettes pour la journalisation
@anchor{howto/logging-cookbook blocking-handlers}@anchor{3352}@anchor{howto/logging-cookbook dealing-with-handlers-that-block}@anchor{4e46}
@subsection Utilisation de gestionnaires bloquants


Parfois, il est nécessaire que les gestionnaires de journalisation fassent leur travail sans bloquer le fil d’exécution qui émet des événements. C’est généralement le cas dans les applications Web, mais aussi bien sûr dans d’autres scénarios.

Un gestionnaire classiquement lent est le @ref{2c99,,SMTPHandler} : l’envoi d’e-mails peut prendre beaucoup de temps, pour un certain nombre de raisons indépendantes du développeur (par exemple, une infrastructure de messagerie ou de réseau peu performante). Mais n’importe quel autre gestionnaire utilisant le réseau ou presque peut aussi s’avérer bloquant : même une simple opération @ref{f4d,,SocketHandler} peut faire une requête DNS implicite et être ainsi très lente (cette requête peut être enfouie profondément dans le code de la bibliothèque d’accès réseau, sous la couche Python, et hors de votre contrôle).

Une solution consiste à utiliser une approche en deux parties. Pour la première partie, affectez un seul @ref{1765,,QueueHandler} à la journalisation des fils d’exécution critiques pour les performances. Ils écrivent simplement dans leur file d’attente, qui peut être dimensionnée à une capacité suffisamment grande ou initialisée sans limite supérieure en taille. L’écriture dans la file d’attente est généralement acceptée rapidement, mais nous vous conseillons quand même de prévoir d’intercepter l’exception @ref{30b2,,queue.Full} par précaution dans votre code. Si vous développez une bibliothèque avec des fils d’exécution critiques pour les performances, documentez-le bien (avec une suggestion de n’affecter que des @code{QueueHandlers} à votre journalisation) pour faciliter le travail des développeurs qui utilisent votre code.

La deuxième partie de la solution est la classe @ref{e19,,QueueListener}, conçue comme l’homologue de @ref{1765,,QueueHandler}. Un @ref{e19,,QueueListener} est très simple : vous lui passez une file d’attente et des gestionnaires, et il lance un fil d’exécution interne qui scrute la file d’attente pour récupérer les événements envoyés par les @code{QueueHandlers} (ou toute autre source de @code{LogRecords}, d’ailleurs). Les @code{LogRecords} sont supprimés de la file d’attente et transmis aux gestionnaires pour traitement.

L’avantage d’avoir une classe @ref{e19,,QueueListener} séparée est que vous pouvez utiliser la même instance pour servir plusieurs @code{QueueHandlers}. Cela consomme moins de ressources que des instances de gestionnaires réparties chacune dans un fil d’exécution séparé.

Voici un exemple d’utilisation de ces deux classes (les importations sont omises) :

@example
que = queue.Queue(-1)  # no limit on size
queue_handler = QueueHandler(que)
handler = logging.StreamHandler()
listener = QueueListener(que, handler)
root = logging.getLogger()
root.addHandler(queue_handler)
formatter = logging.Formatter('%(threadName)s: %(message)s')
handler.setFormatter(formatter)
listener.start()
# The log output will display the thread which generated
# the event (the main thread) rather than the internal
# thread which monitors the internal queue. This is what
# you want to happen.
root.warning('Look out!')
listener.stop()
@end example

ce qui produit ceci à l’exécution :

@example
MainThread: Look out!
@end example

@cartouche
@quotation Note 
bien que la discussion précédente n'aborde pas spécifiquement l'utilisation de code asynchrone, mais concerne les gestionnaires de journalisation lents, notez que lors de la journalisation à partir de code asynchrone, les gestionnaires qui écrivent vers le réseau ou même dans des fichiers peuvent entraîner des problèmes (blocage de la boucle d'événements) car une certaine journalisation est faite à partir du code natif de @ref{a,,asyncio}. Il peut être préférable, si un code asynchrone est utilisé dans une application, d'utiliser l'approche ci-dessus pour la journalisation, de sorte que tout ce qui utilise du code bloquant ne s'exécute que dans le thread @code{QueueListener}.
@end quotation
@end cartouche


Modifié dans la version 3.5: avant Python 3.5, la classe @ref{e19,,QueueListener} passait chaque message reçu de la file d’attente à chaque gestionnaire avec lequel l’instance avait été initialisée (on supposait que le filtrage de niveau était entièrement effectué de l’autre côté, au niveau de l’alimentation de la file d’attente). Depuis Python 3.5, le comportement peut être modifié en passant l’argument par mot-clé @code{respect_handler_level=True} au constructeur. Dans ce cas, la @code{QueueListener} compare le niveau de chaque message avec le niveau défini dans chaque gestionnaire et ne transmet le message que si c’est opportun.


@node Envoi et réception d’événements de journalisation à travers le réseau,Ajout d’informations contextuelles dans la journalisation,Utilisation de gestionnaires bloquants,Recettes pour la journalisation
@anchor{howto/logging-cookbook network-logging}@anchor{4e47}@anchor{howto/logging-cookbook sending-and-receiving-logging-events-across-a-network}@anchor{4e48}
@subsection Envoi et réception d’événements de journalisation à travers le réseau


Supposons que vous souhaitiez envoyer des événements de journalisation sur un réseau et les traiter à la réception. Une façon simple de faire est d’attacher une instance @ref{f4d,,SocketHandler} à la journalisation racine de l’émetteur :

@example
import logging, logging.handlers

rootLogger = logging.getLogger('@w{'})
rootLogger.setLevel(logging.DEBUG)
socketHandler = logging.handlers.SocketHandler('localhost',
                    logging.handlers.DEFAULT_TCP_LOGGING_PORT)
# don't bother with a formatter, since a socket handler sends the event as
# an unformatted pickle
rootLogger.addHandler(socketHandler)

# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')

# Now, define a couple of other loggers which might represent areas in your
# application:

logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')

logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')
@end example

Vous pouvez configurer le récepteur en utilisant le module @ref{cc,,socketserver}. Voici un exemple élémentaire :

@example
import pickle
import logging
import logging.handlers
import socketserver
import struct


class LogRecordStreamHandler(socketserver.StreamRequestHandler):
    """Handler for a streaming logging request.

    This basically logs the record using whatever logging policy is
    configured locally.
    """

    def handle(self):
        """
        Handle multiple requests - each expected to be a 4-byte length,
        followed by the LogRecord in pickle format. Logs the record
        according to whatever policy is configured locally.
        """
        while True:
            chunk = self.connection.recv(4)
            if len(chunk) < 4:
                break
            slen = struct.unpack('>L', chunk)[0]
            chunk = self.connection.recv(slen)
            while len(chunk) < slen:
                chunk = chunk + self.connection.recv(slen - len(chunk))
            obj = self.unPickle(chunk)
            record = logging.makeLogRecord(obj)
            self.handleLogRecord(record)

    def unPickle(self, data):
        return pickle.loads(data)

    def handleLogRecord(self, record):
        # if a name is specified, we use the named logger rather than the one
        # implied by the record.
        if self.server.logname is not None:
            name = self.server.logname
        else:
            name = record.name
        logger = logging.getLogger(name)
        # N.B. EVERY record gets logged. This is because Logger.handle
        # is normally called AFTER logger-level filtering. If you want
        # to do filtering, do it at the client end to save wasting
        # cycles and network bandwidth!
        logger.handle(record)

class LogRecordSocketReceiver(socketserver.ThreadingTCPServer):
    """
    Simple TCP socket-based logging receiver suitable for testing.
    """

    allow_reuse_address = True

    def __init__(self, host='localhost',
                 port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
                 handler=LogRecordStreamHandler):
        socketserver.ThreadingTCPServer.__init__(self, (host, port), handler)
        self.abort = 0
        self.timeout = 1
        self.logname = None

    def serve_until_stopped(self):
        import select
        abort = 0
        while not abort:
            rd, wr, ex = select.select([self.socket.fileno()],
                                       [], [],
                                       self.timeout)
            if rd:
                self.handle_request()
            abort = self.abort

def main():
    logging.basicConfig(
        format='%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s')
    tcpserver = LogRecordSocketReceiver()
    print('About to start TCP server...')
    tcpserver.serve_until_stopped()

if __name__ == '__main__':
    main()
@end example

Lancez d’abord le serveur, puis le client. Côté client, rien ne s’affiche sur la console ; côté serveur, vous devez voir quelque chose comme ça :

@example
About to start TCP server...
   59 root            INFO     Jackdaws love my big sphinx of quartz.
   59 myapp.area1     DEBUG    Quick zephyrs blow, vexing daft Jim.
   69 myapp.area1     INFO     How quickly daft jumping zebras vex.
   69 myapp.area2     WARNING  Jail zesty vixen who grabbed pay from quack.
   69 myapp.area2     ERROR    The five boxing wizards jump quickly.
@end example

Note that there are some security issues with pickle in some scenarios. If
these affect you, you can use an alternative serialization scheme by overriding
the @ref{2c82,,makePickle()} method and implementing your
alternative there, as well as adapting the above script to use your alternative
serialization.

@menu
* Journalisation en production à l’aide d’un connecteur en écoute sur le réseau:: 

@end menu

@node Journalisation en production à l’aide d’un connecteur en écoute sur le réseau,,,Envoi et réception d’événements de journalisation à travers le réseau
@anchor{howto/logging-cookbook running-a-logging-socket-listener-in-production}@anchor{4e49}
@subsubsection Journalisation en production à l’aide d’un connecteur en écoute sur le réseau


Pour de la journalisation en production `via' un connecteur réseau en écoute, il est probable que vous ayez besoin d’utiliser un outil de surveillance tel que Supervisor@footnote{http://supervisord.org/}. Vous trouverez dans ce Gist@footnote{https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b} des gabarits pour assurer cette fonction avec `Supervisor'. Il est composé des fichiers suivants :


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Fichier

@tab

Objectif

@item

@code{prepare.sh}

@tab

Script Bash pour préparer l'environnement de test

@item

@code{supervisor.conf}

@tab

Fichier de configuration de `Supervisor', avec les entrées pour le connecteur en écoute et l'application web multi-processus

@item

@code{ensure_app.sh}

@tab

Script Bash pour s'assurer que `Supervisor' fonctionne bien avec la configuration ci-dessus

@item

@code{log_listener.py}

@tab

Programme en écoute sur le réseau qui reçoit les événements de journalisation et les enregistre dans un fichier

@item

@code{main.py}

@tab

Application web simple qui journalise `via' un connecteur réseau

@item

@code{webapp.json}

@tab

Fichier JSON de configuration de l'application web

@item

@code{client.py}

@tab

Script Python qui interagit avec l'application web pour effectuer des appels à la journalisation

@end multitable


L'application Web utilise Gunicorn@footnote{https://gunicorn.org/}, qui est un serveur d'applications Web populaire qui démarre plusieurs processus de travail pour gérer les demandes. Cet exemple de configuration montre comment les processus peuvent écrire dans le même fichier journal sans entrer en conflit les uns avec les autres — ils passent tous par le connecteur en écoute.

Pour tester ces fichiers, suivez cette procédure dans un environnement POSIX :


@enumerate 

@item 
Téléchargez l'archive ZIP du Gist@footnote{https://gist.github.com/vsajip/4b227eeec43817465ca835ca66f75e2b}  à l'aide du bouton Download ZIP.

@item 
Décompressez les fichiers de l'archive dans un répertoire de travail.

@item 
Dans le répertoire de travail, exécutez le script de préparation par @code{bash prepare.sh}. Cela crée un sous-répertoire @code{run} pour contenir les fichiers journaux et ceux relatifs à `Supervisor', ainsi qu'un sous-répertoire @code{venv} pour contenir un environnement virtuel dans lequel @code{bottle}, @code{gunicorn} et @code{supervisor} sont installés.

@item 
Exécutez @code{bash ensure_app.sh} pour vous assurer que `Supervisor' s'exécute avec la configuration ci-dessus.

@item 
Exécutez @code{venv/bin/python client.py} pour tester l'application Web, ce qui entraîne l'écriture d'enregistrements dans le journal.

@item 
Inspectez les fichiers journaux dans le sous-répertoire @code{run}. Vous devriez voir les lignes de journal les plus récentes dans les fichiers de type @code{app.log*}. Ils ne seront pas dans un ordre particulier, car ils ont été traités par les différents processus de travail de manière non déterministe.

@item 
Vous pouvez arrêter le connecteur en écoute et l'application Web en exécutant @code{venv/bin/supervisorctl -c supervisor.conf shutdown}.
@end enumerate

Vous devrez peut-être modifier les fichiers de configuration dans le cas peu probable où les ports configurés entrent en conflit avec autre chose dans votre environnement de test.

@node Ajout d’informations contextuelles dans la journalisation,Use of contextvars,Envoi et réception d’événements de journalisation à travers le réseau,Recettes pour la journalisation
@anchor{howto/logging-cookbook adding-contextual-information-to-your-logging-output}@anchor{4e4a}@anchor{howto/logging-cookbook context-info}@anchor{2c23}
@subsection Ajout d’informations contextuelles dans la journalisation


Dans certains cas, vous pouvez souhaiter que la journalisation contienne des informations contextuelles en plus des paramètres transmis à l’appel de journalisation. Par exemple, dans une application réseau, il peut être souhaitable de consigner des informations spécifiques au client dans le journal (par exemple, le nom d’utilisateur ou l’adresse IP du client distant). Bien que vous puissiez utiliser le paramètre `extra' pour y parvenir, il n’est pas toujours pratique de transmettre les informations de cette manière. Il peut être aussi tentant de créer des instances @ref{b3d,,Logger} connexion par connexion, mais ce n’est pas une bonne idée car ces instances @ref{b3d,,Logger} ne sont pas éliminées par le ramasse-miettes. Même si ce point n’est pas problématique en soi si la journalisation est configurée avec plusieurs niveaux de granularité, cela peut devenir difficile de gérer un nombre potentiellement illimité d’instances de @ref{b3d,,Logger}.

@menu
* Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles:: 
* Utilisation de filtres pour transmettre des informations contextuelles:: 

@end menu

@node Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles,Utilisation de filtres pour transmettre des informations contextuelles,,Ajout d’informations contextuelles dans la journalisation
@anchor{howto/logging-cookbook using-loggeradapters-to-impart-contextual-information}@anchor{4e4b}
@subsubsection Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles


Un moyen simple de transmettre des informations contextuelles accompagnant les informations de journalisation consiste à utiliser la classe @ref{12d3,,LoggerAdapter}. Cette classe est conçue pour ressembler à un @ref{b3d,,Logger}, de sorte que vous pouvez appeler @ref{2bec,,debug()}, @ref{2c17,,info()}, @ref{2f3,,warning()}, @ref{2c2b,,error()}, @ref{1446,,exception()}, @ref{2c2c,,critical()} et @ref{2c2d,,log()}. Ces méthodes ont les mêmes signatures que leurs homologues dans @ref{b3d,,Logger}, vous pouvez donc utiliser les deux types d’instances de manière interchangeable.

Lorsque vous créez une instance de @ref{12d3,,LoggerAdapter}, vous lui transmettez une instance de @ref{b3d,,Logger} et un objet dictionnaire qui contient vos informations contextuelles. Lorsque vous appelez l’une des méthodes de journalisation sur une instance de @ref{12d3,,LoggerAdapter}, elle délègue l’appel à l’instance sous-jacente de @ref{b3d,,Logger} transmise à son constructeur et s’arrange pour intégrer les informations contextuelles dans l’appel délégué. Voici un extrait du code de @ref{12d3,,LoggerAdapter} :

@example
def debug(self, msg, /, *args, **kwargs):
    """
    Delegate a debug call to the underlying logger, after adding
    contextual information from this adapter instance.
    """
    msg, kwargs = self.process(msg, kwargs)
    self.logger.debug(msg, *args, **kwargs)
@end example

Les informations contextuelles sont ajoutées dans la méthode @ref{2c24,,process()} de @ref{12d3,,LoggerAdapter}. On lui passe le message et les arguments par mot-clé de l’appel de journalisation, et elle en renvoie des versions (potentiellement) modifiées à utiliser pour la journalisation sous-jacente. L’implémentation par défaut de cette méthode laisse le message seul, mais insère une clé @code{extra} dans l’argument par mot-clé dont la valeur est l’objet dictionnaire passé au constructeur. Bien sûr, si vous avez passé un argument par mot-clé @code{extra} dans l’appel à l’adaptateur, il est écrasé silencieusement.

L’avantage d’utiliser @code{extra} est que les valeurs de l’objet dictionnaire sont fusionnées dans le @code{__dict__} de l’instance @ref{fd1,,LogRecord}, ce qui vous permet d’utiliser des chaînes personnalisées avec vos instances @ref{1449,,Formatter} qui connaissent les clés de l’objet dictionnaire. Si vous avez besoin d’une méthode différente, par exemple si vous souhaitez ajouter des informations contextuelles avant ou après la chaîne de message, il vous suffit de surcharger @ref{12d3,,LoggerAdapter} et de remplacer @ref{2c24,,process()} pour faire ce dont vous avez besoin. Voici un exemple simple :

@example
class CustomAdapter(logging.LoggerAdapter):
    """
    This example adapter expects the passed in dict-like object to have a
    'connid' key, whose value in brackets is prepended to the log message.
    """
    def process(self, msg, kwargs):
        return '[%s] %s' % (self.extra['connid'], msg), kwargs
@end example

que vous pouvez utiliser comme ceci :

@example
logger = logging.getLogger(__name__)
adapter = CustomAdapter(logger, @{'connid': some_conn_id@})
@end example

Ainsi, tout événement journalisé aura la valeur de @code{some_conn_id} insérée en début de message de journalisation.

@menu
* Utilisation d’objets autres que les dictionnaires pour passer des informations contextuelles:: 

@end menu

@node Utilisation d’objets autres que les dictionnaires pour passer des informations contextuelles,,,Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles
@anchor{howto/logging-cookbook using-objects-other-than-dicts-to-pass-contextual-information}@anchor{4e4c}
@subsubsection Utilisation d’objets autres que les dictionnaires pour passer des informations contextuelles


Il n’est pas obligatoire de passer un dictionnaire réel à un @ref{12d3,,LoggerAdapter}, vous pouvez passer une instance d’une classe qui implémente @code{__getitem__} et @code{__iter__} pour qu’il ressemble à un dictionnaire du point de vue de la journalisation. C’est utile si vous souhaitez générer des valeurs de manière dynamique (alors que les valeurs d’un dictionnaire seraient constantes).

@node Utilisation de filtres pour transmettre des informations contextuelles,,Utilisation d’adaptateurs de journalisation pour transmettre des informations contextuelles,Ajout d’informations contextuelles dans la journalisation
@anchor{howto/logging-cookbook filters-contextual}@anchor{2c18}@anchor{howto/logging-cookbook using-filters-to-impart-contextual-information}@anchor{4e4d}
@subsubsection Utilisation de filtres pour transmettre des informations contextuelles


Un @ref{11d8,,Filter} défini par l’utilisateur peut aussi ajouter des informations contextuelles à la journalisation. Les instances de @code{Filter} sont autorisées à modifier les @code{LogRecords} qui leur sont transmis, y compris par l’ajout d’attributs supplémentaires qui peuvent ensuite être intégrés à la journalisation en utilisant une chaîne de formatage appropriée ou, si nécessaire, un @ref{1449,,Formatter} personnalisé.

Par exemple, dans une application Web, la requête en cours de traitement (ou du moins ce qu’elle contient d’intéressant) peut être stockée dans une variable locale au fil d’exécution (@ref{16f9,,threading.local}), puis utilisée dans un @code{Filter} pour ajouter, par exemple, des informations relatives à la requête (par exemple, l’adresse IP distante et le nom de l’utilisateur) au @code{LogRecord}, en utilisant les noms d’attribut @code{ip} et @code{user} comme dans l’exemple @code{LoggerAdapter} ci-dessus. Dans ce cas, la même chaîne de formatage peut être utilisée pour obtenir une sortie similaire à celle indiquée ci-dessus. Voici un exemple de script :

@example
import logging
from random import choice

class ContextFilter(logging.Filter):
    """
    This is a filter which injects contextual information into the log.

    Rather than use actual contextual information, we just use random
    data in this demo.
    """

    USERS = ['jim', 'fred', 'sheila']
    IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']

    def filter(self, record):

        record.ip = choice(ContextFilter.IPS)
        record.user = choice(ContextFilter.USERS)
        return True

if __name__ == '__main__':
    levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
    logging.basicConfig(level=logging.DEBUG,
                        format='%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s')
    a1 = logging.getLogger('a.b.c')
    a2 = logging.getLogger('d.e.f')

    f = ContextFilter()
    a1.addFilter(f)
    a2.addFilter(f)
    a1.debug('A debug message')
    a1.info('An info message with %s', 'some parameters')
    for x in range(10):
        lvl = choice(levels)
        lvlname = logging.getLevelName(lvl)
        a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, 'parameters')
@end example

qui, à l’exécution, produit quelque chose comme ça :

@example
2010-09-06 22:38:15,292 a.b.c DEBUG    IP: 123.231.231.123 User: fred     A debug message
2010-09-06 22:38:15,300 a.b.c INFO     IP: 192.168.0.1     User: sheila   An info message with some parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR    IP: 127.0.0.1       User: jim      A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 127.0.0.1       User: sheila   A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR    IP: 123.231.231.123 User: fred     A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1     User: jim      A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1       User: sheila   A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG    IP: 192.168.0.1     User: jim      A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f ERROR    IP: 127.0.0.1       User: sheila   A message at ERROR level with 2 parameters
2010-09-06 22:38:15,301 d.e.f DEBUG    IP: 123.231.231.123 User: fred     A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f INFO     IP: 123.231.231.123 User: fred     A message at INFO level with 2 parameters
@end example

@node Use of contextvars,Ajout d'informations contextuelles dans la journalisation,Ajout d’informations contextuelles dans la journalisation,Recettes pour la journalisation
@anchor{howto/logging-cookbook use-of-contextvars}@anchor{4e4e}
@subsection Use of @code{contextvars}


Since Python 3.7, the @ref{24,,contextvars} module has provided context-local storage
which works for both @ref{ec,,threading} and @ref{a,,asyncio} processing needs. This type
of storage may thus be generally preferable to thread-locals. The following example
shows how, in a multi-threaded environment, logs can populated with contextual
information such as, for example, request attributes handled by web applications.

For the purposes of illustration, say that you have different web applications, each
independent of the other but running in the same Python process and using a library
common to them. How can each of these applications have their own log, where all
logging messages from the library (and other request processing code) are directed to
the appropriate application's log file, while including in the log additional
contextual information such as client IP, HTTP request method and client username?

Let's assume that the library can be simulated by the following code:

@example
# webapplib.py
import logging
import time

logger = logging.getLogger(__name__)

def useful():
    # Just a representative event logged from the library
    logger.debug('Hello from webapplib!')
    # Just sleep for a bit so other threads get to run
    time.sleep(0.01)
@end example

We can simulate the multiple web applications by means of two simple classes,
@code{Request} and @code{WebApp}. These simulate how real threaded web applications work -
each request is handled by a thread:

@example
# main.py
import argparse
from contextvars import ContextVar
import logging
import os
from random import choice
import threading
import webapplib

logger = logging.getLogger(__name__)
root = logging.getLogger()
root.setLevel(logging.DEBUG)

class Request:
    """
    A simple dummy request class which just holds dummy HTTP request method,
    client IP address and client username
    """
    def __init__(self, method, ip, user):
        self.method = method
        self.ip = ip
        self.user = user

# A dummy set of requests which will be used in the simulation - we'll just pick
# from this list randomly. Note that all GET requests are from 192.168.2.XXX
# addresses, whereas POST requests are from 192.16.3.XXX addresses. Three users
# are represented in the sample requests.

REQUESTS = [
    Request('GET', '192.168.2.20', 'jim'),
    Request('POST', '192.168.3.20', 'fred'),
    Request('GET', '192.168.2.21', 'sheila'),
    Request('POST', '192.168.3.21', 'jim'),
    Request('GET', '192.168.2.22', 'fred'),
    Request('POST', '192.168.3.22', 'sheila'),
]

# Note that the format string includes references to request context information
# such as HTTP method, client IP and username

formatter = logging.Formatter('%(threadName)-11s %(appName)s %(name)-9s %(user)-6s %(ip)s %(method)-4s %(message)s')

# Create our context variables. These will be filled at the start of request
# processing, and used in the logging that happens during that processing

ctx_request = ContextVar('request')
ctx_appname = ContextVar('appname')

class InjectingFilter(logging.Filter):
    """
    A filter which injects context-specific information into logs and ensures
    that only information for a specific webapp is included in its log
    """
    def __init__(self, app):
        self.app = app

    def filter(self, record):
        request = ctx_request.get()
        record.method = request.method
        record.ip = request.ip
        record.user = request.user
        record.appName = appName = ctx_appname.get()
        return appName == self.app.name

class WebApp:
    """
    A dummy web application class which has its own handler and filter for a
    webapp-specific log.
    """
    def __init__(self, name):
        self.name = name
        handler = logging.FileHandler(name + '.log', 'w')
        f = InjectingFilter(self)
        handler.setFormatter(formatter)
        handler.addFilter(f)
        root.addHandler(handler)
        self.num_requests = 0

    def process_request(self, request):
        """
        This is the dummy method for processing a request. It's called on a
        different thread for every request. We store the context information into
        the context vars before doing anything else.
        """
        ctx_request.set(request)
        ctx_appname.set(self.name)
        self.num_requests += 1
        logger.debug('Request processing started')
        webapplib.useful()
        logger.debug('Request processing finished')

def main():
    fn = os.path.splitext(os.path.basename(__file__))[0]
    adhf = argparse.ArgumentDefaultsHelpFormatter
    ap = argparse.ArgumentParser(formatter_class=adhf, prog=fn,
                                 description='Simulate a couple of web '
                                             'applications handling some '
                                             'requests, showing how request '
                                             'context can be used to '
                                             'populate logs')
    aa = ap.add_argument
    aa('--count', '-c', type=int, default=100, help='How many requests to simulate')
    options = ap.parse_args()

    # Create the dummy webapps and put them in a list which we can use to select
    # from randomly
    app1 = WebApp('app1')
    app2 = WebApp('app2')
    apps = [app1, app2]
    threads = []
    # Add a common handler which will capture all events
    handler = logging.FileHandler('app.log', 'w')
    handler.setFormatter(formatter)
    root.addHandler(handler)

    # Generate calls to process requests
    for i in range(options.count):
        try:
            # Pick an app at random and a request for it to process
            app = choice(apps)
            request = choice(REQUESTS)
            # Process the request in its own thread
            t = threading.Thread(target=app.process_request, args=(request,))
            threads.append(t)
            t.start()
        except KeyboardInterrupt:
            break

    # Wait for the threads to terminate
    for t in threads:
        t.join()

    for app in apps:
        print('%s processed %s requests' % (app.name, app.num_requests))

if __name__ == '__main__':
    main()
@end example

If you run the above, you should find that roughly half the requests go
into @code{app1.log} and the rest into @code{app2.log}, and the all the requests are
logged to @code{app.log}. Each webapp-specific log will contain only log entries for
only that webapp, and the request information will be displayed consistently in the
log (i.e. the information in each dummy request will always appear together in a log
line). This is illustrated by the following shell output:

@example
~/logging-contextual-webapp$ python main.py
app1 processed 51 requests
app2 processed 49 requests
~/logging-contextual-webapp$ wc -l *.log
  153 app1.log
  147 app2.log
  300 app.log
  600 total
~/logging-contextual-webapp$ head -3 app1.log
Thread-3 (process_request) app1 __main__  jim    192.168.3.21 POST Request processing started
Thread-3 (process_request) app1 webapplib jim    192.168.3.21 POST Hello from webapplib!
Thread-5 (process_request) app1 __main__  jim    192.168.3.21 POST Request processing started
~/logging-contextual-webapp$ head -3 app2.log
Thread-1 (process_request) app2 __main__  sheila 192.168.2.21 GET  Request processing started
Thread-1 (process_request) app2 webapplib sheila 192.168.2.21 GET  Hello from webapplib!
Thread-2 (process_request) app2 __main__  jim    192.168.2.20 GET  Request processing started
~/logging-contextual-webapp$ head app.log
Thread-1 (process_request) app2 __main__  sheila 192.168.2.21 GET  Request processing started
Thread-1 (process_request) app2 webapplib sheila 192.168.2.21 GET  Hello from webapplib!
Thread-2 (process_request) app2 __main__  jim    192.168.2.20 GET  Request processing started
Thread-3 (process_request) app1 __main__  jim    192.168.3.21 POST Request processing started
Thread-2 (process_request) app2 webapplib jim    192.168.2.20 GET  Hello from webapplib!
Thread-3 (process_request) app1 webapplib jim    192.168.3.21 POST Hello from webapplib!
Thread-4 (process_request) app2 __main__  fred   192.168.2.22 GET  Request processing started
Thread-5 (process_request) app1 __main__  jim    192.168.3.21 POST Request processing started
Thread-4 (process_request) app2 webapplib fred   192.168.2.22 GET  Hello from webapplib!
Thread-6 (process_request) app1 __main__  jim    192.168.3.21 POST Request processing started
~/logging-contextual-webapp$ grep app1 app1.log | wc -l
153
~/logging-contextual-webapp$ grep app2 app2.log | wc -l
147
~/logging-contextual-webapp$ grep app1 app.log | wc -l
153
~/logging-contextual-webapp$ grep app2 app.log | wc -l
147
@end example

@node Ajout d'informations contextuelles dans la journalisation,Journalisation vers un fichier unique à partir de plusieurs processus,Use of contextvars,Recettes pour la journalisation
@anchor{howto/logging-cookbook imparting-contextual-information-in-handlers}@anchor{4e4f}
@subsection Ajout d'informations contextuelles dans la journalisation


Chaque @ref{1448,,Handler} possède sa propre chaîne de filtres. Si vous souhaitez ajouter des informations contextuelles à un @ref{fd1,,LogRecord} sans impacter d'autres gestionnaires, vous pouvez utiliser un filtre qui renvoie un nouveau @ref{fd1,,LogRecord} au lieu de le modifier sur place, comme dans le script suivant :

@example
import copy
import logging

def filter(record: logging.LogRecord):
    record = copy.copy(record)
    record.user = 'jim'
    return record

if __name__ == '__main__':
    logger = logging.getLogger()
    logger.setLevel(logging.INFO)
    handler = logging.StreamHandler()
    formatter = logging.Formatter('%(message)s from %(user)-8s')
    handler.setFormatter(formatter)
    handler.addFilter(filter)
    logger.addHandler(handler)

    logger.info('A log message')
@end example

@node Journalisation vers un fichier unique à partir de plusieurs processus,Utilisation du roulement de fichiers,Ajout d'informations contextuelles dans la journalisation,Recettes pour la journalisation
@anchor{howto/logging-cookbook logging-to-a-single-file-from-multiple-processes}@anchor{4e50}@anchor{howto/logging-cookbook multiple-processes}@anchor{4e51}
@subsection Journalisation vers un fichier unique à partir de plusieurs processus


La journalisation est fiable avec les programmes à fils d’exécution multiples (`thread-safe') : rien n’empêche plusieurs fils d’exécution de journaliser dans le même fichier, du moment que ces fils d’exécution font partie du même processus. En revanche, il n’existe aucun moyen standard de sérialiser l’accès à un seul fichier sur plusieurs processus en Python. Si vous avez besoin de vous connecter à un seul fichier à partir de plusieurs processus, une façon de le faire est de faire en sorte que tous les processus se connectent à un @ref{f4d,,SocketHandler}, et d’avoir un processus séparé qui implémente un serveur qui lit à partir de ce connecteur et écrit les journaux dans le fichier (si vous préférez, vous pouvez dédier un fil d’exécution dans l’un des processus existants pour exécuter cette tâche). @ref{4e47,,Cette section} documente cette approche plus en détail et inclut un connecteur en écoute réseau fonctionnel qui peut être utilisé comme point de départ pour l’adapter à vos propres applications.

You could also write your own handler which uses the @ref{1522,,Lock}
class from the @ref{93,,multiprocessing} module to serialize access to the
file from your processes. The stdlib @ref{182c,,FileHandler} and subclasses do
not make use of @ref{93,,multiprocessing}.

Autrement, vous pouvez utiliser une @code{Queue} et un @ref{1765,,QueueHandler} pour envoyer tous les événements de journalisation à l’un des processus de votre application multi-processus. L’exemple de script suivant montre comment procéder ; dans l’exemple, un processus d’écoute distinct écoute les événements envoyés par les autres processus et les journalise en fonction de sa propre configuration de journalisation. Bien que l’exemple ne montre qu’une seule façon de faire (par exemple, vous pouvez utiliser un fil d’exécution d’écoute plutôt qu’un processus d’écoute séparé – l’implémentation serait analogue), il permet des configurations de journalisation complètement différentes pour celui qui écoute ainsi que pour les autres processus de votre application, et peut être utilisé comme base pour répondre à vos propres exigences :

@example
# You'll need these imports in your own code
import logging
import logging.handlers
import multiprocessing

# Next two import lines for this demo only
from random import choice, random
import time

#
# Because you'll want to define the logging configurations for listener and workers, the
# listener and worker process functions take a configurer parameter which is a callable
# for configuring logging for that process. These functions are also passed the queue,
# which they use for communication.
#
# In practice, you can configure the listener however you want, but note that in this
# simple example, the listener does not apply level or filter logic to received records.
# In practice, you would probably want to do this logic in the worker processes, to avoid
# sending events which would be filtered out between processes.
#
# The size of the rotated files is made small so you can see the results easily.
def listener_configurer():
    root = logging.getLogger()
    h = logging.handlers.RotatingFileHandler('mptest.log', 'a', 300, 10)
    f = logging.Formatter('%(asctime)s %(processName)-10s %(name)s %(levelname)-8s %(message)s')
    h.setFormatter(f)
    root.addHandler(h)

# This is the listener process top-level loop: wait for logging events
# (LogRecords)on the queue and handle them, quit when you get a None for a
# LogRecord.
def listener_process(queue, configurer):
    configurer()
    while True:
        try:
            record = queue.get()
            if record is None:  # We send this as a sentinel to tell the listener to quit.
                break
            logger = logging.getLogger(record.name)
            logger.handle(record)  # No level or filter logic applied - just do it!
        except Exception:
            import sys, traceback
            print('Whoops! Problem:', file=sys.stderr)
            traceback.print_exc(file=sys.stderr)

# Arrays used for random selections in this demo

LEVELS = [logging.DEBUG, logging.INFO, logging.WARNING,
          logging.ERROR, logging.CRITICAL]

LOGGERS = ['a.b.c', 'd.e.f']

MESSAGES = [
    'Random message #1',
    'Random message #2',
    'Random message #3',
]

# The worker configuration is done at the start of the worker process run.
# Note that on Windows you can't rely on fork semantics, so each process
# will run the logging configuration code when it starts.
def worker_configurer(queue):
    h = logging.handlers.QueueHandler(queue)  # Just the one handler needed
    root = logging.getLogger()
    root.addHandler(h)
    # send all messages, for demo; no other level or filter logic applied.
    root.setLevel(logging.DEBUG)

# This is the worker process top-level loop, which just logs ten events with
# random intervening delays before terminating.
# The print messages are just so you know it's doing something!
def worker_process(queue, configurer):
    configurer(queue)
    name = multiprocessing.current_process().name
    print('Worker started: %s' % name)
    for i in range(10):
        time.sleep(random())
        logger = logging.getLogger(choice(LOGGERS))
        level = choice(LEVELS)
        message = choice(MESSAGES)
        logger.log(level, message)
    print('Worker finished: %s' % name)

# Here's where the demo gets orchestrated. Create the queue, create and start
# the listener, create ten workers and start them, wait for them to finish,
# then send a None to the queue to tell the listener to finish.
def main():
    queue = multiprocessing.Queue(-1)
    listener = multiprocessing.Process(target=listener_process,
                                       args=(queue, listener_configurer))
    listener.start()
    workers = []
    for i in range(10):
        worker = multiprocessing.Process(target=worker_process,
                                         args=(queue, worker_configurer))
        workers.append(worker)
        worker.start()
    for w in workers:
        w.join()
    queue.put_nowait(None)
    listener.join()

if __name__ == '__main__':
    main()
@end example

Une variante du script ci-dessus conserve la journalisation dans le processus principal, dans un fil séparé :

@example
import logging
import logging.config
import logging.handlers
from multiprocessing import Process, Queue
import random
import threading
import time

def logger_thread(q):
    while True:
        record = q.get()
        if record is None:
            break
        logger = logging.getLogger(record.name)
        logger.handle(record)


def worker_process(q):
    qh = logging.handlers.QueueHandler(q)
    root = logging.getLogger()
    root.setLevel(logging.DEBUG)
    root.addHandler(qh)
    levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
              logging.CRITICAL]
    loggers = ['foo', 'foo.bar', 'foo.bar.baz',
               'spam', 'spam.ham', 'spam.ham.eggs']
    for i in range(100):
        lvl = random.choice(levels)
        logger = logging.getLogger(random.choice(loggers))
        logger.log(lvl, 'Message no. %d', i)

if __name__ == '__main__':
    q = Queue()
    d = @{
        'version': 1,
        'formatters': @{
            'detailed': @{
                'class': 'logging.Formatter',
                'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            @}
        @},
        'handlers': @{
            'console': @{
                'class': 'logging.StreamHandler',
                'level': 'INFO',
            @},
            'file': @{
                'class': 'logging.FileHandler',
                'filename': 'mplog.log',
                'mode': 'w',
                'formatter': 'detailed',
            @},
            'foofile': @{
                'class': 'logging.FileHandler',
                'filename': 'mplog-foo.log',
                'mode': 'w',
                'formatter': 'detailed',
            @},
            'errors': @{
                'class': 'logging.FileHandler',
                'filename': 'mplog-errors.log',
                'mode': 'w',
                'level': 'ERROR',
                'formatter': 'detailed',
            @},
        @},
        'loggers': @{
            'foo': @{
                'handlers': ['foofile']
            @}
        @},
        'root': @{
            'level': 'DEBUG',
            'handlers': ['console', 'file', 'errors']
        @},
    @}
    workers = []
    for i in range(5):
        wp = Process(target=worker_process, name='worker %d' % (i + 1), args=(q,))
        workers.append(wp)
        wp.start()
    logging.config.dictConfig(d)
    lp = threading.Thread(target=logger_thread, args=(q,))
    lp.start()
    # At this point, the main process could do some useful work of its own
    # Once it's done that, it can wait for the workers to terminate...
    for wp in workers:
        wp.join()
    # And now tell the logging thread to finish up, too
    q.put(None)
    lp.join()
@end example

Cette variante montre comment appliquer la configuration pour des enregistreurs particuliers – par exemple l’enregistreur @code{foo} a un gestionnaire spécial qui stocke tous les événements du sous-système @code{foo} dans un fichier @code{mplog-foo.log}. C’est utilisé par le mécanisme de journalisation dans le processus principal (même si les événements de journalisation sont générés dans les processus de travail) pour diriger les messages vers les destinations appropriées.

@menu
* Utilisation de concurrent.futures.ProcessPoolExecutor: Utilisation de concurrent futures ProcessPoolExecutor. 
* Déploiement d’applications Web avec Gunicorn et uWSGI:: 

@end menu

@node Utilisation de concurrent futures ProcessPoolExecutor,Déploiement d’applications Web avec Gunicorn et uWSGI,,Journalisation vers un fichier unique à partir de plusieurs processus
@anchor{howto/logging-cookbook using-concurrent-futures-processpoolexecutor}@anchor{4e52}
@subsubsection Utilisation de concurrent.futures.ProcessPoolExecutor


Si vous souhaitez utiliser @ref{8db,,concurrent.futures.ProcessPoolExecutor} pour démarrer vos processus de travail, vous devez créer la file d’attente légèrement différemment. À la place de

@example
queue = multiprocessing.Queue(-1)
@end example

vous devez écrire

@example
queue = multiprocessing.Manager().Queue(-1)  # also works with the examples above
@end example

et vous pouvez alors remplacer la création du processus de travail telle que :

@example
workers = []
for i in range(10):
    worker = multiprocessing.Process(target=worker_process,
                                     args=(queue, worker_configurer))
    workers.append(worker)
    worker.start()
for w in workers:
    w.join()
@end example

par celle-ci (souvenez-vous d’importer au préalable @ref{21,,concurrent.futures}) :

@example
with concurrent.futures.ProcessPoolExecutor(max_workers=10) as executor:
    for i in range(10):
        executor.submit(worker_process, queue, worker_configurer)
@end example

@node Déploiement d’applications Web avec Gunicorn et uWSGI,,Utilisation de concurrent futures ProcessPoolExecutor,Journalisation vers un fichier unique à partir de plusieurs processus
@anchor{howto/logging-cookbook deploying-web-applications-using-gunicorn-and-uwsgi}@anchor{4e53}
@subsubsection Déploiement d’applications Web avec `Gunicorn' et `uWSGI'


Lors du déploiement d’applications Web qui utilisent Gunicorn@footnote{https://gunicorn.org/} ou uWSGI@footnote{https://uwsgi-docs.readthedocs.io/en/latest/} (ou équivalent), plusieurs processus de travail sont créés pour traiter les requêtes des clients. Dans de tels environnements, évitez de créer des gestionnaires à fichiers directement dans votre application Web. Au lieu de cela, utilisez un @ref{f4d,,SocketHandler} pour journaliser depuis l’application Web vers gestionnaire réseau à l’écoute dans un processus séparé. Cela peut être configuré à l’aide d’un outil de gestion de processus tel que `Supervisor' (voir @ref{4e49,,Journalisation en production à l’aide d’un connecteur en écoute sur le réseau} pour plus de détails).

@node Utilisation du roulement de fichiers,Utilisation d’autres styles de formatage,Journalisation vers un fichier unique à partir de plusieurs processus,Recettes pour la journalisation
@anchor{howto/logging-cookbook using-file-rotation}@anchor{4e54}
@subsection Utilisation du roulement de fichiers


@c (see <https://pymotw.com/3/logging/>)

Sometimes you want to let a log file grow to a certain size, then open a new
file and log to that. You may want to keep a certain number of these files, and
when that many files have been created, rotate the files so that the number of
files and the size of the files both remain bounded. For this usage pattern, the
logging package provides a @ref{1560,,RotatingFileHandler}:

@example
import glob
import logging
import logging.handlers

LOG_FILENAME = 'logging_rotatingfile_example.out'

# Set up a specific logger with our desired output level
my_logger = logging.getLogger('MyLogger')
my_logger.setLevel(logging.DEBUG)

# Add the log message handler to the logger
handler = logging.handlers.RotatingFileHandler(
              LOG_FILENAME, maxBytes=20, backupCount=5)

my_logger.addHandler(handler)

# Log some messages
for i in range(20):
    my_logger.debug('i = %d' % i)

# See what files are created
logfiles = glob.glob('%s*' % LOG_FILENAME)

for filename in logfiles:
    print(filename)
@end example

Vous devez obtenir 6 fichiers séparés, chacun contenant une partie de l’historique de journalisation de l’application :

@example
logging_rotatingfile_example.out
logging_rotatingfile_example.out.1
logging_rotatingfile_example.out.2
logging_rotatingfile_example.out.3
logging_rotatingfile_example.out.4
logging_rotatingfile_example.out.5
@end example

Le fichier de journalisation actuel est toujours @code{logging_rotatingfile_example.out}, et chaque fois qu’il atteint la taille limite, il est renommé avec le suffixe @code{.1}. Chacun des fichiers de sauvegarde existants est renommé pour incrémenter le suffixe (@code{.1} devient @code{.2}, etc.) et le fichier @code{.6} est effacé.

De toute évidence, la longueur du journal définie dans cet exemple est beaucoup trop petite. À vous de définir `maxBytes' à une valeur appropriée.

@node Utilisation d’autres styles de formatage,Personnalisation de LogRecord,Utilisation du roulement de fichiers,Recettes pour la journalisation
@anchor{howto/logging-cookbook format-styles}@anchor{4e55}@anchor{howto/logging-cookbook use-of-alternative-formatting-styles}@anchor{4e56}
@subsection Utilisation d’autres styles de formatage


Lorsque la journalisation a été ajoutée à la bibliothèque standard Python, la seule façon de formater les messages avec un contenu variable était d’utiliser la méthode de formatage avec « % ». Depuis, Python s’est enrichi de deux nouvelles méthode de formatage : @ref{672,,string.Template} (ajouté dans Python 2.4) et @ref{60c,,str.format()} (ajouté dans Python 2.6).

La journalisation (à partir de la version 3.2) offre une meilleure prise en charge de ces deux styles de formatage supplémentaires. La classe @ref{1449,,Formatter} a été améliorée pour accepter un paramètre par mot-clé facultatif supplémentaire nommé @code{style}. La valeur par défaut est @code{'%'}, les autres valeurs possibles étant @code{'@{'} et @code{'$'}, qui correspondent aux deux autres styles de formatage. La rétrocompatibilité est maintenue par défaut (comme vous vous en doutez) mais, en spécifiant explicitement un paramètre de style, vous avez la possibilité de spécifier des chaînes de format qui fonctionnent avec @ref{60c,,str.format()} ou @ref{672,,string.Template}. Voici un exemple de session interactive en console pour montrer les possibilités :

@example
>>> import logging
>>> root = logging.getLogger()
>>> root.setLevel(logging.DEBUG)
>>> handler = logging.StreamHandler()
>>> bf = logging.Formatter('@{asctime@} @{name@} @{levelname:8s@} @{message@}',
...                        style='@{')
>>> handler.setFormatter(bf)
>>> root.addHandler(handler)
>>> logger = logging.getLogger('foo.bar')
>>> logger.debug('This is a DEBUG message')
2010-10-28 15:11:55,341 foo.bar DEBUG    This is a DEBUG message
>>> logger.critical('This is a CRITICAL message')
2010-10-28 15:12:11,526 foo.bar CRITICAL This is a CRITICAL message
>>> df = logging.Formatter('$asctime $name $@{levelname@} $message',
...                        style='$')
>>> handler.setFormatter(df)
>>> logger.debug('This is a DEBUG message')
2010-10-28 15:13:06,924 foo.bar DEBUG This is a DEBUG message
>>> logger.critical('This is a CRITICAL message')
2010-10-28 15:13:11,494 foo.bar CRITICAL This is a CRITICAL message
>>>
@end example

Notez que le formatage des messages de journalisation est, au final, complètement indépendant de la façon dont un message de journalisation individuel est construit. Vous pouvez toujours utiliser formatage `via' « % », comme ici :

@example
>>> logger.error('This is an%s %s %s', 'other,', 'ERROR,', 'message')
2010-10-28 15:19:29,833 foo.bar ERROR This is another, ERROR, message
>>>
@end example

Les appels de journalisation (@code{logger.debug()}, @code{logger.info()} etc.) ne prennent que des paramètres positionnels pour le message de journalisation lui-même, les paramètres par mots-clés étant utilisés uniquement pour déterminer comment gérer le message réel (par exemple, le paramètre par mot-clé @code{exc_info} indique que les informations de trace doivent être enregistrées, ou le paramètre par mot-clé @code{extra} indique des informations contextuelles supplémentaires à ajouter au journal). Vous ne pouvez donc pas inclure dans les appels de journalisation à l’aide de la syntaxe @ref{60c,,str.format()} ou @ref{672,,string.Template}, car le paquet de journalisation utilise le formatage via « % » en interne pour fusionner la chaîne de format et les arguments de variables. Il n’est pas possible de changer ça tout en préservant la rétrocompatibilité puisque tous les appels de journalisation dans le code pré-existant utilisent des chaînes au format « % ».

Il existe cependant un moyen d’utiliser le formatage `via' « @{@} » et « $ » pour vos messages de journalisation. Rappelez-vous que, pour un message, vous pouvez utiliser un objet arbitraire comme chaîne de format de message, et que le package de journalisation appelle @code{str()} sur cet objet pour fabriquer la chaîne finale. Considérez les deux classes suivantes :

@example
class BraceMessage:
    def __init__(self, fmt, /, *args, **kwargs):
        self.fmt = fmt
        self.args = args
        self.kwargs = kwargs

    def __str__(self):
        return self.fmt.format(*self.args, **self.kwargs)

class DollarMessage:
    def __init__(self, fmt, /, **kwargs):
        self.fmt = fmt
        self.kwargs = kwargs

    def __str__(self):
        from string import Template
        return Template(self.fmt).substitute(**self.kwargs)
@end example

L’une ou l’autre peut être utilisée à la place d’une chaîne de format "%(message)s" ou "@{message@}" ou "$message", afin de mettre en forme `via' « @{ @} » ou « $ » la partie « message réel » qui apparaît dans la sortie de journal formatée. Il est un peu lourd d’utiliser les noms de classe chaque fois que vous voulez journaliser quelque chose, mais ça devient acceptable si vous utilisez un alias tel que __ (double trait de soulignement — à ne pas confondre avec _, le trait de soulignement unique utilisé comme alias pour @ref{141d,,gettext.gettext()} ou ses homologues).

Les classes ci-dessus ne sont pas incluses dans Python, bien qu’elles soient assez faciles à copier et coller dans votre propre code. Elles peuvent être utilisées comme suit (en supposant qu’elles soient déclarées dans un module appelé @code{wherever}) :

@example
>>> from wherever import BraceMessage as __
>>> print(__('Message with @{0@} @{name@}', 2, name='placeholders'))
Message with 2 placeholders
>>> class Point: pass
...
>>> p = Point()
>>> p.x = 0.5
>>> p.y = 0.5
>>> print(__('Message with coordinates: (@{point.x:.2f@}, @{point.y:.2f@})',
...       point=p))
Message with coordinates: (0.50, 0.50)
>>> from wherever import DollarMessage as __
>>> print(__('Message with $num $what', num=2, what='placeholders'))
Message with 2 placeholders
>>>
@end example

Alors que les exemples ci-dessus utilisent @code{print()} pour montrer comment fonctionne le formatage, utilisez bien sûr @code{logger.debug()} ou similaire pour journaliser avec cette approche.

One thing to note is that you pay no significant performance penalty with this
approach: the actual formatting happens not when you make the logging call, but
when (and if) the logged message is actually about to be output to a log by a
handler. So the only slightly unusual thing which might trip you up is that the
parentheses go around the format string and the arguments, not just the format
string. That's because the __ notation is just syntax sugar for a constructor
call to one of the @code{@var{XXX}Message} classes.

Si vous préférez, vous pouvez utiliser un @ref{12d3,,LoggerAdapter} pour obtenir un effet similaire à ce qui précède, comme dans l’exemple suivant :

@example
import logging

class Message:
    def __init__(self, fmt, args):
        self.fmt = fmt
        self.args = args

    def __str__(self):
        return self.fmt.format(*self.args)

class StyleAdapter(logging.LoggerAdapter):
    def log(self, level, msg, /, *args, stacklevel=1, **kwargs):
        if self.isEnabledFor(level):
            msg, kwargs = self.process(msg, kwargs)
            self.logger.log(level, Message(msg, args), **kwargs,
                            stacklevel=stacklevel+1)

logger = StyleAdapter(logging.getLogger(__name__))

def main():
    logger.debug('Hello, @{@}', 'world!')

if __name__ == '__main__':
    logging.basicConfig(level=logging.DEBUG)
    main()
@end example

The above script should log the message @code{Hello, world!} when run with
Python 3.8 or later.

@node Personnalisation de LogRecord,Subclassing QueueHandler and QueueListener- a ZeroMQ example,Utilisation d’autres styles de formatage,Recettes pour la journalisation
@anchor{howto/logging-cookbook custom-logrecord}@anchor{4e57}@anchor{howto/logging-cookbook customizing-logrecord}@anchor{4e58}
@subsection Personnalisation de @code{LogRecord}


Chaque événement de journalisation est représenté par une instance @ref{fd1,,LogRecord}. Lorsqu’un événement est enregistré et non filtré en raison du niveau d’un enregistreur, un @ref{fd1,,LogRecord} est créé, rempli avec les informations de l’événement, puis transmis aux gestionnaires de cet enregistreur (et ses ancêtres, jusqu’à et y compris l’enregistreur où la propagation vers le haut de la hiérarchie est désactivée). Avant Python 3.2, il n’y avait que deux endroits où cette création était effectuée :


@itemize *

@item 
@ref{2bf3,,Logger.makeRecord()}, qui est appelée dans le processus normal de journalisation d’un événement. Elle appelait @ref{fd1,,LogRecord} directement pour créer une instance.

@item 
@ref{2c1b,,makeLogRecord()}, qui est appelée avec un dictionnaire contenant des attributs à ajouter au `LogRecord'. Elle est généralement invoquée lorsqu’un dictionnaire approprié a été reçu par le réseau (par exemple, sous forme de `pickle' `via' un @ref{f4d,,SocketHandler}, ou sous format JSON `via' un @ref{e18,,HTTPHandler}).
@end itemize

Cela signifiait généralement que, si vous deviez faire quelque chose de spécial avec un @ref{fd1,,LogRecord}, vous deviez faire l’une des choses suivantes.


@itemize *

@item 
Créer votre propre sous-classe @ref{b3d,,Logger}, surchargeant @ref{2bf3,,Logger.makeRecord()}, et la personnaliser à l’aide de @ref{2c2a,,setLoggerClass()} avant que les enregistreurs qui vous intéressaient ne soient instanciés.

@item 
Ajouter un @ref{11d8,,Filter} à un enregistreur ou un gestionnaire, qui effectuait la manipulation spéciale nécessaire dont vous aviez besoin lorsque sa méthode @ref{2c16,,filter()} était appelée.
@end itemize

La première approche est un peu lourde dans le scénario où (disons) plusieurs bibliothèques différentes veulent faire des choses différentes. Chacun essaie de définir sa propre sous-classe @ref{b3d,,Logger}, et celui qui l’a fait en dernier gagne.

La seconde approche fonctionne raisonnablement bien dans de nombreux cas, mais ne vous permet pas, par exemple, d’utiliser une sous-classe spécialisée de @ref{fd1,,LogRecord}. Les développeurs de bibliothèques peuvent définir un filtre approprié sur leurs enregistreurs, mais ils doivent se rappeler de le faire chaque fois qu’ils introduisent un nouvel enregistreur (ce qu’ils font simplement en ajoutant de nouveaux paquets ou modules et en écrivant

@example
logger = logging.getLogger(__name__)
@end example

au niveau des modules). C’est probablement trop de choses auxquelles penser. Les développeurs pourraient également ajouter le filtre à un @ref{1262,,NullHandler} attaché à leur enregistreur de niveau supérieur, mais cela ne serait pas invoqué si un développeur d’application attachait un gestionnaire à un enregistreur de bibliothèque de niveau inférieur — donc la sortie de ce gestionnaire ne refléterait pas les intentions du développeur de la bibliothèque.

Dans Python 3.2 et ultérieurs, la création de @ref{fd1,,LogRecord} est effectuée via une fabrique, que vous pouvez spécifier. La fabrique est juste un appelable que vous pouvez définir avec @ref{2c1f,,setLogRecordFactory()}, et interroger avec @ref{2c1e,,getLogRecordFactory()}. La fabrique est invoquée avec la même signature que le constructeur @ref{fd1,,LogRecord}, car @ref{fd1,,LogRecord} est le paramètre par défaut de la fabrique.

Cette approche permet à une fabrique personnalisée de contrôler tous les aspects de la création d’un `LogRecord'. Par exemple, vous pouvez renvoyer une sous-classe ou simplement ajouter des attributs supplémentaires à l’enregistrement une fois créé, en utilisant un modèle similaire à celui-ci :

@example
old_factory = logging.getLogRecordFactory()

def record_factory(*args, **kwargs):
    record = old_factory(*args, **kwargs)
    record.custom_attribute = 0xdecafbad
    return record

logging.setLogRecordFactory(record_factory)
@end example

Ce modèle permet à différentes bibliothèques d’enchaîner des fabriques, et tant qu’elles n’écrasent pas les attributs des autres ou n’écrasent pas involontairement les attributs fournis en standard, il ne devrait pas y avoir de surprise. Cependant, il faut garder à l’esprit que chaque maillon de la chaîne ajoute une surcharge d’exécution à toutes les opérations de journalisation, et la technique ne doit être utilisée que lorsque l’utilisation d’un @ref{11d8,,Filter} ne permet pas d’obtenir le résultat souhaité.

@node Subclassing QueueHandler and QueueListener- a ZeroMQ example,Subclassing QueueHandler and QueueListener- a pynng example,Personnalisation de LogRecord,Recettes pour la journalisation
@anchor{howto/logging-cookbook subclassing-queuehandler-and-queuelistener-a-zeromq-example}@anchor{4e59}@anchor{howto/logging-cookbook zeromq-handlers}@anchor{4e5a}
@subsection Subclassing QueueHandler and QueueListener- a ZeroMQ example


@menu
* Subclass QueueHandler:: 
* Subclass QueueListener:: 

@end menu

@node Subclass QueueHandler,Subclass QueueListener,,Subclassing QueueHandler and QueueListener- a ZeroMQ example
@anchor{howto/logging-cookbook subclass-queuehandler}@anchor{4e5b}
@subsubsection Subclass @code{QueueHandler}


Vous pouvez utiliser une sous-classe @ref{1765,,QueueHandler} pour envoyer des messages à d’autres types de files d’attente, par exemple un connecteur `ZeroMQ publish'. Dans l’exemple ci-dessous, le connecteur est créé séparément et transmis au gestionnaire (en tant que file d’attente) :

@example
import zmq   # using pyzmq, the Python binding for ZeroMQ
import json  # for serializing records portably

ctx = zmq.Context()
sock = zmq.Socket(ctx, zmq.PUB)  # or zmq.PUSH, or other suitable value
sock.bind('tcp://*:5556')        # or wherever

class ZeroMQSocketHandler(QueueHandler):
    def enqueue(self, record):
        self.queue.send_json(record.__dict__)


handler = ZeroMQSocketHandler(sock)
@end example

Bien sûr, il existe d’autres manières de faire, par exemple en transmettant les données nécessaires au gestionnaire pour créer le connecteur :

@example
class ZeroMQSocketHandler(QueueHandler):
    def __init__(self, uri, socktype=zmq.PUB, ctx=None):
        self.ctx = ctx or zmq.Context()
        socket = zmq.Socket(self.ctx, socktype)
        socket.bind(uri)
        super().__init__(socket)

    def enqueue(self, record):
        self.queue.send_json(record.__dict__)

    def close(self):
        self.queue.close()
@end example

@node Subclass QueueListener,,Subclass QueueHandler,Subclassing QueueHandler and QueueListener- a ZeroMQ example
@anchor{howto/logging-cookbook subclass-queuelistener}@anchor{4e5c}
@subsubsection Subclass @code{QueueListener}


Vous pouvez également dériver @ref{e19,,QueueListener} pour obtenir des messages d’autres types de files d’attente, par exemple un connecteur `ZeroMQ subscribe'. Voici un exemple :

@example
class ZeroMQSocketListener(QueueListener):
    def __init__(self, uri, /, *handlers, **kwargs):
        self.ctx = kwargs.get('ctx') or zmq.Context()
        socket = zmq.Socket(self.ctx, zmq.SUB)
        socket.setsockopt_string(zmq.SUBSCRIBE, '@w{'})  # subscribe to everything
        socket.connect(uri)
        super().__init__(socket, *handlers, **kwargs)

    def dequeue(self):
        msg = self.queue.recv_json()
        return logging.makeLogRecord(msg)
@end example

@node Subclassing QueueHandler and QueueListener- a pynng example,Exemple de configuration basée sur un dictionnaire,Subclassing QueueHandler and QueueListener- a ZeroMQ example,Recettes pour la journalisation
@anchor{howto/logging-cookbook pynng-handlers}@anchor{4e5d}@anchor{howto/logging-cookbook subclassing-queuehandler-and-queuelistener-a-pynng-example}@anchor{4e5e}
@subsection Subclassing QueueHandler and QueueListener- a @code{pynng} example


In a similar way to the above section, we can implement a listener and handler
using pynng@footnote{https://pypi.org/project/pynng/}, which is a Python binding to
NNG@footnote{https://nng.nanomsg.org/}, billed as a spiritual successor to ZeroMQ.
The following snippets illustrate -- you can test them in an environment which has
@code{pynng} installed. Just for variety, we present the listener first.

@menu
* Subclass QueueListener: Subclass QueueListener<2>. 
* Subclass QueueHandler: Subclass QueueHandler<2>. 

@end menu

@node Subclass QueueListener<2>,Subclass QueueHandler<2>,,Subclassing QueueHandler and QueueListener- a pynng example
@anchor{howto/logging-cookbook id3}@anchor{4e5f}
@subsubsection Subclass @code{QueueListener}


@example
# listener.py
import json
import logging
import logging.handlers

import pynng

DEFAULT_ADDR = "tcp://localhost:13232"

interrupted = False

class NNGSocketListener(logging.handlers.QueueListener):

    def __init__(self, uri, /, *handlers, **kwargs):
        # Have a timeout for interruptability, and open a
        # subscriber socket
        socket = pynng.Sub0(listen=uri, recv_timeout=500)
        # The b'@w{'} subscription matches all topics
        topics = kwargs.pop('topics', None) or b'@w{'}
        socket.subscribe(topics)
        # We treat the socket as a queue
        super().__init__(socket, *handlers, **kwargs)

    def dequeue(self, block):
        data = None
        # Keep looping while not interrupted and no data received over the
        # socket
        while not interrupted:
            try:
                data = self.queue.recv(block=block)
                break
            except pynng.Timeout:
                pass
            except pynng.Closed:  # sometimes happens when you hit Ctrl-C
                break
        if data is None:
            return None
        # Get the logging event sent from a publisher
        event = json.loads(data.decode('utf-8'))
        return logging.makeLogRecord(event)

    def enqueue_sentinel(self):
        # Not used in this implementation, as the socket isn't really a
        # queue
        pass

logging.getLogger('pynng').propagate = False
listener = NNGSocketListener(DEFAULT_ADDR, logging.StreamHandler(), topics=b'@w{'})
listener.start()
print('Press Ctrl-C to stop.')
try:
    while True:
        pass
except KeyboardInterrupt:
    interrupted = True
finally:
    listener.stop()
@end example

@node Subclass QueueHandler<2>,,Subclass QueueListener<2>,Subclassing QueueHandler and QueueListener- a pynng example
@anchor{howto/logging-cookbook id4}@anchor{4e60}
@subsubsection Subclass @code{QueueHandler}


@example
# sender.py
import json
import logging
import logging.handlers
import time
import random

import pynng

DEFAULT_ADDR = "tcp://localhost:13232"

class NNGSocketHandler(logging.handlers.QueueHandler):

    def __init__(self, uri):
        socket = pynng.Pub0(dial=uri, send_timeout=500)
        super().__init__(socket)

    def enqueue(self, record):
        # Send the record as UTF-8 encoded JSON
        d = dict(record.__dict__)
        data = json.dumps(d)
        self.queue.send(data.encode('utf-8'))

    def close(self):
        self.queue.close()

logging.getLogger('pynng').propagate = False
handler = NNGSocketHandler(DEFAULT_ADDR)
# Make sure the process ID is in the output
logging.basicConfig(level=logging.DEBUG,
                    handlers=[logging.StreamHandler(), handler],
                    format='%(levelname)-8s %(name)10s %(process)6s %(message)s')
levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
          logging.CRITICAL)
logger_names = ('myapp', 'myapp.lib1', 'myapp.lib2')
msgno = 1
while True:
    # Just randomly select some loggers and levels and log away
    level = random.choice(levels)
    logger = logging.getLogger(random.choice(logger_names))
    logger.log(level, 'Message no. %5d' % msgno)
    msgno += 1
    delay = random.random() * 2 + 0.5
    time.sleep(delay)
@end example

You can run the above two snippets in separate command shells. If we run the
listener in one shell and run the sender in two separate shells, we should see
something like the following. In the first sender shell:

@example
$ python sender.py
DEBUG         myapp    613 Message no.     1
WARNING  myapp.lib2    613 Message no.     2
CRITICAL myapp.lib2    613 Message no.     3
WARNING  myapp.lib2    613 Message no.     4
CRITICAL myapp.lib1    613 Message no.     5
DEBUG         myapp    613 Message no.     6
CRITICAL myapp.lib1    613 Message no.     7
INFO     myapp.lib1    613 Message no.     8
(and so on)
@end example

In the second sender shell:

@example
$ python sender.py
INFO     myapp.lib2    657 Message no.     1
CRITICAL myapp.lib2    657 Message no.     2
CRITICAL      myapp    657 Message no.     3
CRITICAL myapp.lib1    657 Message no.     4
INFO     myapp.lib1    657 Message no.     5
WARNING  myapp.lib2    657 Message no.     6
CRITICAL      myapp    657 Message no.     7
DEBUG    myapp.lib1    657 Message no.     8
(and so on)
@end example

In the listener shell:

@example
$ python listener.py
Press Ctrl-C to stop.
DEBUG         myapp    613 Message no.     1
WARNING  myapp.lib2    613 Message no.     2
INFO     myapp.lib2    657 Message no.     1
CRITICAL myapp.lib2    613 Message no.     3
CRITICAL myapp.lib2    657 Message no.     2
CRITICAL      myapp    657 Message no.     3
WARNING  myapp.lib2    613 Message no.     4
CRITICAL myapp.lib1    613 Message no.     5
CRITICAL myapp.lib1    657 Message no.     4
INFO     myapp.lib1    657 Message no.     5
DEBUG         myapp    613 Message no.     6
WARNING  myapp.lib2    657 Message no.     6
CRITICAL      myapp    657 Message no.     7
CRITICAL myapp.lib1    613 Message no.     7
INFO     myapp.lib1    613 Message no.     8
DEBUG    myapp.lib1    657 Message no.     8
(and so on)
@end example

As you can see, the logging from the two sender processes is interleaved in the
listener's output.

@node Exemple de configuration basée sur un dictionnaire,Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux,Subclassing QueueHandler and QueueListener- a pynng example,Recettes pour la journalisation
@anchor{howto/logging-cookbook an-example-dictionary-based-configuration}@anchor{4e61}
@subsection Exemple de configuration basée sur un dictionnaire


Vous trouverez ci-dessous un exemple de dictionnaire de configuration de journalisation ­– il est tiré de la documentation du projet Django@footnote{https://docs.djangoproject.com/fr/stable/topics/logging/#configuring-logging}. Ce dictionnaire est passé à @ref{118d,,dictConfig()} pour activer la configuration :

@example
LOGGING = @{
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': @{
        'verbose': @{
            'format': '@{levelname@} @{asctime@} @{module@} @{process:d@} @{thread:d@} @{message@}',
            'style': '@{',
        @},
        'simple': @{
            'format': '@{levelname@} @{message@}',
            'style': '@{',
        @},
    @},
    'filters': @{
        'special': @{
            '()': 'project.logging.SpecialFilter',
            'foo': 'bar',
        @},
    @},
    'handlers': @{
        'console': @{
            'level': 'INFO',
            'class': 'logging.StreamHandler',
            'formatter': 'simple',
        @},
        'mail_admins': @{
            'level': 'ERROR',
            'class': 'django.utils.log.AdminEmailHandler',
            'filters': ['special']
        @}
    @},
    'loggers': @{
        'django': @{
            'handlers': ['console'],
            'propagate': True,
        @},
        'django.request': @{
            'handlers': ['mail_admins'],
            'level': 'ERROR',
            'propagate': False,
        @},
        'myproject.custom': @{
            'handlers': ['console', 'mail_admins'],
            'level': 'INFO',
            'filters': ['special']
        @}
    @}
@}
@end example

Pour plus d’informations sur cette configuration, vous pouvez consulter la section correspondante@footnote{https://docs.djangoproject.com/fr/stable/topics/logging/#configuring-logging} de la documentation de `Django'.

@node Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux,Exemple plus élaboré avec traitement en parallèle,Exemple de configuration basée sur un dictionnaire,Recettes pour la journalisation
@anchor{howto/logging-cookbook cookbook-rotator-namer}@anchor{2c73}@anchor{howto/logging-cookbook using-a-rotator-and-namer-to-customize-log-rotation-processing}@anchor{4e62}
@subsection Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux


L’extrait de code suivant fournit un exemple de la façon dont vous pouvez définir un nom et un rotateur, avec la compression par `zlib' du journal :

@example
import gzip
import logging
import logging.handlers
import os
import shutil

def namer(name):
    return name + ".gz"

def rotator(source, dest):
    with open(source, 'rb') as f_in:
        with gzip.open(dest, 'wb') as f_out:
            shutil.copyfileobj(f_in, f_out)
    os.remove(source)


rh = logging.handlers.RotatingFileHandler('rotated.log', maxBytes=128, backupCount=5)
rh.rotator = rotator
rh.namer = namer

root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(rh)
f = logging.Formatter('%(asctime)s %(message)s')
rh.setFormatter(f)
for i in range(1000):
    root.info(f'Message no. @{i + 1@}')
@end example

Après l'avoir exécuté, vous verrez six nouveaux fichiers, dont cinq sont compressés :

@example
$ ls rotated.log*
rotated.log       rotated.log.2.gz  rotated.log.4.gz
rotated.log.1.gz  rotated.log.3.gz  rotated.log.5.gz
$ zcat rotated.log.1.gz
2023-01-20 02:28:17,767 Message no. 996
2023-01-20 02:28:17,767 Message no. 997
2023-01-20 02:28:17,767 Message no. 998
@end example

@node Exemple plus élaboré avec traitement en parallèle,Insertion d’une BOM dans les messages envoyés à un SysLogHandler,Utilisation d’un rotateur et d’un nom pour personnaliser la rotation des journaux,Recettes pour la journalisation
@anchor{howto/logging-cookbook a-more-elaborate-multiprocessing-example}@anchor{4e63}
@subsection Exemple plus élaboré avec traitement en parallèle


L’exemple suivant que nous allons étudier montre comment la journalisation peut être utilisée, à l’aide de fichiers de configuration, pour un programme effectuant des traitements parallèles. Les configurations sont assez simples, mais servent à illustrer comment des configurations plus complexes pourraient être implémentées dans un scénario multi-processus réel.

Dans l’exemple, le processus principal génère un processus d’écoute et des processus de travail. Chacun des processus, le principal, l’auditeur (`listener_process' dans l’exemple) et les processus de travail (`worker_process' dans l’exemple) ont trois configurations distinctes (les processus de travail partagent tous la même configuration). Nous pouvons voir la journalisation dans le processus principal, comment les processus de travail se connectent à un `QueueHandler' et comment l’auditeur implémente un `QueueListener' avec une configuration de journalisation plus complexe, et s’arrange pour envoyer les événements reçus `via' la file d’attente aux gestionnaires spécifiés dans la configuration. Notez que ces configurations sont purement illustratives, mais vous devriez pouvoir adapter cet exemple à votre propre scénario.

Voici le script – les chaines de documentation et les commentaires expliquent (en anglais), le principe de fonctionnement :

@example
import logging
import logging.config
import logging.handlers
from multiprocessing import Process, Queue, Event, current_process
import os
import random
import time

class MyHandler:
    """
    A simple handler for logging events. It runs in the listener process and
    dispatches events to loggers based on the name in the received record,
    which then get dispatched, by the logging system, to the handlers
    configured for those loggers.
    """

    def handle(self, record):
        if record.name == "root":
            logger = logging.getLogger()
        else:
            logger = logging.getLogger(record.name)

        if logger.isEnabledFor(record.levelno):
            # The process name is transformed just to show that it's the listener
            # doing the logging to files and console
            record.processName = '%s (for %s)' % (current_process().name, record.processName)
            logger.handle(record)

def listener_process(q, stop_event, config):
    """
    This could be done in the main process, but is just done in a separate
    process for illustrative purposes.

    This initialises logging according to the specified configuration,
    starts the listener and waits for the main process to signal completion
    via the event. The listener is then stopped, and the process exits.
    """
    logging.config.dictConfig(config)
    listener = logging.handlers.QueueListener(q, MyHandler())
    listener.start()
    if os.name == 'posix':
        # On POSIX, the setup logger will have been configured in the
        # parent process, but should have been disabled following the
        # dictConfig call.
        # On Windows, since fork isn't used, the setup logger won't
        # exist in the child, so it would be created and the message
        # would appear - hence the "if posix" clause.
        logger = logging.getLogger('setup')
        logger.critical('Should not appear, because of disabled logger ...')
    stop_event.wait()
    listener.stop()

def worker_process(config):
    """
    A number of these are spawned for the purpose of illustration. In
    practice, they could be a heterogeneous bunch of processes rather than
    ones which are identical to each other.

    This initialises logging according to the specified configuration,
    and logs a hundred messages with random levels to randomly selected
    loggers.

    A small sleep is added to allow other processes a chance to run. This
    is not strictly needed, but it mixes the output from the different
    processes a bit more than if it's left out.
    """
    logging.config.dictConfig(config)
    levels = [logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
              logging.CRITICAL]
    loggers = ['foo', 'foo.bar', 'foo.bar.baz',
               'spam', 'spam.ham', 'spam.ham.eggs']
    if os.name == 'posix':
        # On POSIX, the setup logger will have been configured in the
        # parent process, but should have been disabled following the
        # dictConfig call.
        # On Windows, since fork isn't used, the setup logger won't
        # exist in the child, so it would be created and the message
        # would appear - hence the "if posix" clause.
        logger = logging.getLogger('setup')
        logger.critical('Should not appear, because of disabled logger ...')
    for i in range(100):
        lvl = random.choice(levels)
        logger = logging.getLogger(random.choice(loggers))
        logger.log(lvl, 'Message no. %d', i)
        time.sleep(0.01)

def main():
    q = Queue()
    # The main process gets a simple configuration which prints to the console.
    config_initial = @{
        'version': 1,
        'handlers': @{
            'console': @{
                'class': 'logging.StreamHandler',
                'level': 'INFO'
            @}
        @},
        'root': @{
            'handlers': ['console'],
            'level': 'DEBUG'
        @}
    @}
    # The worker process configuration is just a QueueHandler attached to the
    # root logger, which allows all messages to be sent to the queue.
    # We disable existing loggers to disable the "setup" logger used in the
    # parent process. This is needed on POSIX because the logger will
    # be there in the child following a fork().
    config_worker = @{
        'version': 1,
        'disable_existing_loggers': True,
        'handlers': @{
            'queue': @{
                'class': 'logging.handlers.QueueHandler',
                'queue': q
            @}
        @},
        'root': @{
            'handlers': ['queue'],
            'level': 'DEBUG'
        @}
    @}
    # The listener process configuration shows that the full flexibility of
    # logging configuration is available to dispatch events to handlers however
    # you want.
    # We disable existing loggers to disable the "setup" logger used in the
    # parent process. This is needed on POSIX because the logger will
    # be there in the child following a fork().
    config_listener = @{
        'version': 1,
        'disable_existing_loggers': True,
        'formatters': @{
            'detailed': @{
                'class': 'logging.Formatter',
                'format': '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            @},
            'simple': @{
                'class': 'logging.Formatter',
                'format': '%(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
            @}
        @},
        'handlers': @{
            'console': @{
                'class': 'logging.StreamHandler',
                'formatter': 'simple',
                'level': 'INFO'
            @},
            'file': @{
                'class': 'logging.FileHandler',
                'filename': 'mplog.log',
                'mode': 'w',
                'formatter': 'detailed'
            @},
            'foofile': @{
                'class': 'logging.FileHandler',
                'filename': 'mplog-foo.log',
                'mode': 'w',
                'formatter': 'detailed'
            @},
            'errors': @{
                'class': 'logging.FileHandler',
                'filename': 'mplog-errors.log',
                'mode': 'w',
                'formatter': 'detailed',
                'level': 'ERROR'
            @}
        @},
        'loggers': @{
            'foo': @{
                'handlers': ['foofile']
            @}
        @},
        'root': @{
            'handlers': ['console', 'file', 'errors'],
            'level': 'DEBUG'
        @}
    @}
    # Log some initial events, just to show that logging in the parent works
    # normally.
    logging.config.dictConfig(config_initial)
    logger = logging.getLogger('setup')
    logger.info('About to create workers ...')
    workers = []
    for i in range(5):
        wp = Process(target=worker_process, name='worker %d' % (i + 1),
                     args=(config_worker,))
        workers.append(wp)
        wp.start()
        logger.info('Started worker: %s', wp.name)
    logger.info('About to create listener ...')
    stop_event = Event()
    lp = Process(target=listener_process, name='listener',
                 args=(q, stop_event, config_listener))
    lp.start()
    logger.info('Started listener')
    # We now hang around for the workers to finish their work.
    for wp in workers:
        wp.join()
    # Workers all done, listening can now stop.
    # Logging in the parent still works normally.
    logger.info('Telling listener to stop ...')
    stop_event.set()
    lp.join()
    logger.info('All done.')

if __name__ == '__main__':
    main()
@end example

@node Insertion d’une BOM dans les messages envoyés à un SysLogHandler,Journalisation structurée,Exemple plus élaboré avec traitement en parallèle,Recettes pour la journalisation
@anchor{howto/logging-cookbook inserting-a-bom-into-messages-sent-to-a-sysloghandler}@anchor{4e64}
@subsection Insertion d’une `BOM' dans les messages envoyés à un `SysLogHandler'


La 
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html} requiert qu’un message Unicode soit envoyé à un démon `syslog' sous la forme d’un ensemble d’octets ayant la structure suivante : un composant ASCII pur facultatif, suivi d’une marque d’ordre d’octet (`BOM' pour `Byte Order Mark' en anglais) UTF-8, suivie de contenu Unicode UTF-8 (voir la 
@geindex RFC; RFC 5424 Section 6
la spécification correspondante@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html#section-6}).

Dans Python 3.1, du code a été ajouté à @ref{647,,SysLogHandler} pour insérer une `BOM' dans le message mais, malheureusement, il a été implémenté de manière incorrecte, la `BOM' apparaissant au début du message et n’autorisant donc aucun composant ASCII pur à être placé devant.

Comme ce comportement est inadéquat, le code incorrect d’insertion de la `BOM' a été supprimé de Python 3.2.4 et ultérieurs. Cependant, il n’est pas remplacé et, si vous voulez produire des messages conformes 
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html} qui incluent une `BOM', une séquence facultative en ASCII pur avant et un Unicode arbitraire après, encodé en UTF-8, alors vous devez appliquer ce qui suit :


@enumerate 

@item 
Adjoignez une instance @ref{1449,,Formatter} à votre instance @ref{647,,SysLogHandler}, avec une chaîne de format telle que :

@example
'ASCII section\ufeffUnicode section'
@end example

Le point de code Unicode U+FEFF, lorsqu’il est encodé en UTF-8, est encodé comme une `BOM' UTF-8 – la chaîne d’octets @code{b'\xef\xbb\xbf'}.

@item 
Remplacez la section ASCII par les caractères de votre choix, mais assurez-vous que les données qui y apparaissent après la substitution sont toujours ASCII (ainsi elles resteront inchangées après l’encodage UTF-8).

@item 
Remplacez la section Unicode par le contenu de votre choix ; si les données qui y apparaissent après la substitution contiennent des caractères en dehors de la plage ASCII, c’est pris en charge – elles seront encodées en UTF-8.
@end enumerate

Le message formaté `sera' encodé en UTF-8 par @code{SysLogHandler}. Si vous suivez les règles ci-dessus, vous devriez pouvoir produire des messages conformes à la 
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html}. Si vous ne le faites pas, la journalisation ne se plaindra peut-être pas, mais vos messages ne seront pas conformes à la RFC 5424 et votre démon `syslog' est susceptible de se plaindre.

@node Journalisation structurée,Personnalisation des gestionnaires avec dictConfig,Insertion d’une BOM dans les messages envoyés à un SysLogHandler,Recettes pour la journalisation
@anchor{howto/logging-cookbook implementing-structured-logging}@anchor{4e65}
@subsection Journalisation structurée


Bien que la plupart des messages de journalisation soient destinés à être lus par des humains, et donc difficilement analysables par la machine, il peut arriver que vous souhaitiez produire des messages dans un format structuré dans le but d’être analysé par un programme (sans avoir besoin d’expressions régulières complexes pour analyser le message du journal). C’est simple à réaliser en utilisant le paquet de journalisation. Il existe plusieurs façons d’y parvenir et voici une approche simple qui utilise JSON pour sérialiser l’événement de manière à être analysable par une machine :

@example
import json
import logging

class StructuredMessage:
    def __init__(self, message, /, **kwargs):
        self.message = message
        self.kwargs = kwargs

    def __str__(self):
        return '%s >>> %s' % (self.message, json.dumps(self.kwargs))

_ = StructuredMessage   # optional, to improve readability

logging.basicConfig(level=logging.INFO, format='%(message)s')
logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))
@end example

Si vous lancez le script ci-dessus, il imprime :

@example
message 1 >>> @{"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"@}
@end example

Notez que l’ordre des éléments peut être différent en fonction de la version de Python utilisée.

Si vous avez besoin d’un traitement plus spécifique, vous pouvez utiliser un encodeur JSON personnalisé, comme dans l’exemple complet suivant :

@example
import json
import logging


class Encoder(json.JSONEncoder):
    def default(self, o):
        if isinstance(o, set):
            return tuple(o)
        elif isinstance(o, str):
            return o.encode('unicode_escape').decode('ascii')
        return super().default(o)

class StructuredMessage:
    def __init__(self, message, /, **kwargs):
        self.message = message
        self.kwargs = kwargs

    def __str__(self):
        s = Encoder().encode(self.kwargs)
        return '%s >>> %s' % (self.message, s)

_ = StructuredMessage   # optional, to improve readability

def main():
    logging.basicConfig(level=logging.INFO, format='%(message)s')
    logging.info(_('message 1', set_value=@{1, 2, 3@}, snowman='\u2603'))

if __name__ == '__main__':
    main()
@end example

Quand vous exécutez le script ci-dessus, il imprime :

@example
message 1 >>> @{"snowman": "\u2603", "set_value": [1, 2, 3]@}
@end example

Notez que l’ordre des éléments peut être différent en fonction de la version de Python utilisée.

@node Personnalisation des gestionnaires avec dictConfig,Using particular formatting styles throughout your application,Journalisation structurée,Recettes pour la journalisation
@anchor{howto/logging-cookbook custom-handlers}@anchor{4e66}@anchor{howto/logging-cookbook customizing-handlers-with-dictconfig}@anchor{4e67}
@subsection Personnalisation des gestionnaires avec @code{dictConfig()}


Il arrive de souhaiter personnaliser les gestionnaires de journalisation d’une manière particulière et, en utilisant @ref{118d,,dictConfig()}, vous pourrez peut-être le faire sans avoir à dériver les classes mères. Par exemple, supposons que vous souhaitiez définir le propriétaire d’un fichier journal. Dans un environnement POSIX, cela se fait facilement en utilisant @ref{23d,,shutil.chown()}, mais les gestionnaires de fichiers de la bibliothèque standard n’offrent pas cette gestion nativement. Vous pouvez personnaliser la création du gestionnaire à l’aide d’une fonction simple telle que :

@example
def owned_file_handler(filename, mode='a', encoding=None, owner=None):
    if owner:
        if not os.path.exists(filename):
            open(filename, 'a').close()
        shutil.chown(filename, *owner)
    return logging.FileHandler(filename, mode, encoding)
@end example

Vous pouvez ensuite spécifier, dans une configuration de journalisation transmise à @ref{118d,,dictConfig()}, qu’un gestionnaire de journalisation soit créé en appelant cette fonction :

@example
LOGGING = @{
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': @{
        'default': @{
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
        @},
    @},
    'handlers': @{
        'file':@{
            # The values below are popped from this dictionary and
            # used to create the handler, set the handler's level and
            # its formatter.
            '()': owned_file_handler,
            'level':'DEBUG',
            'formatter': 'default',
            # The values below are passed to the handler creator callable
            # as keyword arguments.
            'owner': ['pulse', 'pulse'],
            'filename': 'chowntest.log',
            'mode': 'w',
            'encoding': 'utf-8',
        @},
    @},
    'root': @{
        'handlers': ['file'],
        'level': 'DEBUG',
    @},
@}
@end example

Dans cet exemple, nous définissons le propriétaire à l’utilisateur et au groupe @code{pulse}, uniquement à des fins d’illustration. Rassemblons le tout dans un script @code{chowntest.py} :

@example
import logging, logging.config, os, shutil

def owned_file_handler(filename, mode='a', encoding=None, owner=None):
    if owner:
        if not os.path.exists(filename):
            open(filename, 'a').close()
        shutil.chown(filename, *owner)
    return logging.FileHandler(filename, mode, encoding)

LOGGING = @{
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': @{
        'default': @{
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
        @},
    @},
    'handlers': @{
        'file':@{
            # The values below are popped from this dictionary and
            # used to create the handler, set the handler's level and
            # its formatter.
            '()': owned_file_handler,
            'level':'DEBUG',
            'formatter': 'default',
            # The values below are passed to the handler creator callable
            # as keyword arguments.
            'owner': ['pulse', 'pulse'],
            'filename': 'chowntest.log',
            'mode': 'w',
            'encoding': 'utf-8',
        @},
    @},
    'root': @{
        'handlers': ['file'],
        'level': 'DEBUG',
    @},
@}

logging.config.dictConfig(LOGGING)
logger = logging.getLogger('mylogger')
logger.debug('A debug message')
@end example

Pour l’exécuter, vous devrez probablement le faire en tant que @code{root} :

@example
$ sudo python3.3 chowntest.py
$ cat chowntest.log
2013-11-05 09:34:51,128 DEBUG mylogger A debug message
$ ls -l chowntest.log
-rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log
@end example

Notez que cet exemple utilise Python 3.3 car c’est là que @ref{23d,,shutil.chown()} fait son apparition. Cette approche devrait fonctionner avec n’importe quelle version de Python prenant en charge @ref{118d,,dictConfig()} – à savoir, Python 2.7, 3.2 ou version ultérieure. Avec les versions antérieures à la 3.3, vous devrez implémenter le changement de propriétaire réel en utilisant par exemple @ref{10cf,,os.chown()}.

En pratique, la fonction de création de gestionnaire peut être située dans un module utilitaire ailleurs dans votre projet. Au lieu de cette ligne dans la configuration :

@example
'()': owned_file_handler,
@end example

vous pouvez écrire par exemple :

@example
'()': 'ext://project.util.owned_file_handler',
@end example

où @code{project.util} peut être remplacé par le nom réel du paquet où réside la fonction. Dans le script étudié ci-dessus, l’utilisation de @code{'ext://__main__.owned_file_handler'} devrait fonctionner. Dans le cas présent, l’appelable réel est résolu par @ref{118d,,dictConfig()} à partir de la spécification @code{ext://}.

Nous espérons qu'à partir de cet exemple vous saurez implémenter d’autres types de modification de fichier – par ex. définir des bits d’autorisation POSIX spécifiques – de la même manière, en utilisant @ref{218,,os.chmod()}.

Bien sûr, l’approche pourrait également être étendue à des types de gestionnaires autres qu’un @ref{182c,,FileHandler} – par exemple, l’un des gestionnaires à roulement de fichiers ou un autre type de gestionnaire complètement différent.

@node Using particular formatting styles throughout your application,Configuring filters with dictConfig,Personnalisation des gestionnaires avec dictConfig,Recettes pour la journalisation
@anchor{howto/logging-cookbook formatting-styles}@anchor{2c0c}@anchor{howto/logging-cookbook using-particular-formatting-styles-throughout-your-application}@anchor{4e68}
@subsection Using particular formatting styles throughout your application


In Python 3.2, the @ref{1449,,Formatter} gained a @code{style} keyword
parameter which, while defaulting to @code{%} for backward compatibility, allowed
the specification of @code{@{} or @code{$} to support the formatting approaches
supported by @ref{60c,,str.format()} and @ref{672,,string.Template}. Note that this
governs the formatting of logging messages for final output to logs, and is
completely orthogonal to how an individual logging message is constructed.

Logging calls (@ref{e17,,debug()}, @ref{2beb,,info()} etc.) only take
positional parameters for the actual logging message itself, with keyword
parameters used only for determining options for how to handle the logging call
(e.g. the @code{exc_info} keyword parameter to indicate that traceback information
should be logged, or the @code{extra} keyword parameter to indicate additional
contextual information to be added to the log). So you cannot directly make
logging calls using @ref{60c,,str.format()} or @ref{672,,string.Template} syntax,
because internally the logging package uses %-formatting to merge the format
string and the variable arguments. There would be no changing this while preserving
backward compatibility, since all logging calls which are out there in existing
code will be using %-format strings.

There have been suggestions to associate format styles with specific loggers,
but that approach also runs into backward compatibility problems because any
existing code could be using a given logger name and using %-formatting.

For logging to work interoperably between any third-party libraries and your
code, decisions about formatting need to be made at the level of the
individual logging call. This opens up a couple of ways in which alternative
formatting styles can be accommodated.

@menu
* Using LogRecord factories:: 
* Using custom message objects:: 

@end menu

@node Using LogRecord factories,Using custom message objects,,Using particular formatting styles throughout your application
@anchor{howto/logging-cookbook using-logrecord-factories}@anchor{4e69}
@subsubsection Using LogRecord factories


In Python 3.2, along with the @ref{1449,,Formatter} changes mentioned
above, the logging package gained the ability to allow users to set their own
@ref{fd1,,LogRecord} subclasses, using the @ref{2c1f,,setLogRecordFactory()} function.
You can use this to set your own subclass of @ref{fd1,,LogRecord}, which does the
Right Thing by overriding the @ref{2c1d,,getMessage()} method. The base
class implementation of this method is where the @code{msg % args} formatting
happens, and where you can substitute your alternate formatting; however, you
should be careful to support all formatting styles and allow %-formatting as
the default, to ensure interoperability with other code. Care should also be
taken to call @code{str(self.msg)}, just as the base implementation does.

Refer to the reference documentation on @ref{2c1f,,setLogRecordFactory()} and
@ref{fd1,,LogRecord} for more information.

@node Using custom message objects,,Using LogRecord factories,Using particular formatting styles throughout your application
@anchor{howto/logging-cookbook using-custom-message-objects}@anchor{4e6a}
@subsubsection Using custom message objects


There is another, perhaps simpler way that you can use @{@}- and $- formatting to
construct your individual log messages. You may recall (from
@ref{2c1c,,Utilisation d'objets arbitraires comme messages}) that when logging you can use an arbitrary
object as a message format string, and that the logging package will call
@ref{435,,str()} on that object to get the actual format string. Consider the
following two classes:

@example
class BraceMessage:
    def __init__(self, fmt, /, *args, **kwargs):
        self.fmt = fmt
        self.args = args
        self.kwargs = kwargs

    def __str__(self):
        return self.fmt.format(*self.args, **self.kwargs)

class DollarMessage:
    def __init__(self, fmt, /, **kwargs):
        self.fmt = fmt
        self.kwargs = kwargs

    def __str__(self):
        from string import Template
        return Template(self.fmt).substitute(**self.kwargs)
@end example

Either of these can be used in place of a format string, to allow @{@}- or
$-formatting to be used to build the actual "message" part which appears in the
formatted log output in place of “%(message)s” or “@{message@}” or “$message”.
If you find it a little unwieldy to use the class names whenever you want to log
something, you can make it more palatable if you use an alias such as @code{M} or
@code{_} for the message (or perhaps @code{__}, if you are using @code{_} for
localization).

Examples of this approach are given below. Firstly, formatting with
@ref{60c,,str.format()}:

@example
>>> __ = BraceMessage
>>> print(__('Message with @{0@} @{1@}', 2, 'placeholders'))
Message with 2 placeholders
>>> class Point: pass
...
>>> p = Point()
>>> p.x = 0.5
>>> p.y = 0.5
>>> print(__('Message with coordinates: (@{point.x:.2f@}, @{point.y:.2f@})', point=p))
Message with coordinates: (0.50, 0.50)
@end example

Secondly, formatting with @ref{672,,string.Template}:

@example
>>> __ = DollarMessage
>>> print(__('Message with $num $what', num=2, what='placeholders'))
Message with 2 placeholders
>>>
@end example

One thing to note is that you pay no significant performance penalty with this
approach: the actual formatting happens not when you make the logging call, but
when (and if) the logged message is actually about to be output to a log by a
handler. So the only slightly unusual thing which might trip you up is that the
parentheses go around the format string and the arguments, not just the format
string. That’s because the __ notation is just syntax sugar for a constructor
call to one of the @code{@var{XXX}Message} classes shown above.

@node Configuring filters with dictConfig,Customized exception formatting,Using particular formatting styles throughout your application,Recettes pour la journalisation
@anchor{howto/logging-cookbook configuring-filters-with-dictconfig}@anchor{4e6b}@anchor{howto/logging-cookbook filters-dictconfig}@anchor{4e6c}
@subsection Configuring filters with @code{dictConfig()}


You `can' configure filters using @ref{118d,,dictConfig()}, though it
might not be obvious at first glance how to do it (hence this recipe). Since
@ref{11d8,,Filter} is the only filter class included in the standard
library, and it is unlikely to cater to many requirements (it's only there as a
base class), you will typically need to define your own @ref{11d8,,Filter}
subclass with an overridden @ref{2c16,,filter()} method. To do this,
specify the @code{()} key in the configuration dictionary for the filter,
specifying a callable which will be used to create the filter (a class is the
most obvious, but you can provide any callable which returns a
@ref{11d8,,Filter} instance). Here is a complete example:

@example
import logging
import logging.config
import sys

class MyFilter(logging.Filter):
    def __init__(self, param=None):
        self.param = param

    def filter(self, record):
        if self.param is None:
            allow = True
        else:
            allow = self.param not in record.msg
        if allow:
            record.msg = 'changed: ' + record.msg
        return allow

LOGGING = @{
    'version': 1,
    'filters': @{
        'myfilter': @{
            '()': MyFilter,
            'param': 'noshow',
        @}
    @},
    'handlers': @{
        'console': @{
            'class': 'logging.StreamHandler',
            'filters': ['myfilter']
        @}
    @},
    'root': @{
        'level': 'DEBUG',
        'handlers': ['console']
    @},
@}

if __name__ == '__main__':
    logging.config.dictConfig(LOGGING)
    logging.debug('hello')
    logging.debug('hello - noshow')
@end example

This example shows how you can pass configuration data to the callable which
constructs the instance, in the form of keyword parameters. When run, the above
script will print:

@example
changed: hello
@end example

which shows that the filter is working as configured.

A couple of extra points to note:


@itemize *

@item 
If you can't refer to the callable directly in the configuration (e.g. if it
lives in a different module, and you can't import it directly where the
configuration dictionary is), you can use the form @code{ext://...} as described
in @ref{2c4a,,Access to external objects}. For example, you could have used
the text @code{'ext://__main__.MyFilter'} instead of @code{MyFilter} in the above
example.

@item 
As well as for filters, this technique can also be used to configure custom
handlers and formatters. See @ref{2c3e,,User-defined objects} for more
information on how logging supports using user-defined objects in its
configuration, and see the other cookbook recipe @ref{4e66,,Personnalisation des gestionnaires avec dictConfig()} above.
@end itemize

@node Customized exception formatting,Speaking logging messages,Configuring filters with dictConfig,Recettes pour la journalisation
@anchor{howto/logging-cookbook custom-format-exception}@anchor{4e6d}@anchor{howto/logging-cookbook customized-exception-formatting}@anchor{4e6e}
@subsection Customized exception formatting


There might be times when you want to do customized exception formatting - for
argument's sake, let's say you want exactly one line per logged event, even
when exception information is present. You can do this with a custom formatter
class, as shown in the following example:

@example
import logging

class OneLineExceptionFormatter(logging.Formatter):
    def formatException(self, exc_info):
        """
        Format an exception so that it prints on a single line.
        """
        result = super().formatException(exc_info)
        return repr(result)  # or format into one line however you want to

    def format(self, record):
        s = super().format(record)
        if record.exc_text:
            s = s.replace('\n', '@w{'}) + '|'
        return s

def configure_logging():
    fh = logging.FileHandler('output.txt', 'w')
    f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|',
                                  '%d/%m/%Y %H:%M:%S')
    fh.setFormatter(f)
    root = logging.getLogger()
    root.setLevel(logging.DEBUG)
    root.addHandler(fh)

def main():
    configure_logging()
    logging.info('Sample message')
    try:
        x = 1 / 0
    except ZeroDivisionError as e:
        logging.exception('ZeroDivisionError: %s', e)

if __name__ == '__main__':
    main()
@end example

When run, this produces a file with exactly two lines:

@example
28/01/2015 07:21:23|INFO|Sample message|
28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n  File "logtest7.py", line 30, in main\n    x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|
@end example

While the above treatment is simplistic, it points the way to how exception
information can be formatted to your liking. The @ref{fd,,traceback} module may be
helpful for more specialized needs.

@node Speaking logging messages,Buffering logging messages and outputting them conditionally,Customized exception formatting,Recettes pour la journalisation
@anchor{howto/logging-cookbook speaking-logging-messages}@anchor{4e6f}@anchor{howto/logging-cookbook spoken-messages}@anchor{4e70}
@subsection Speaking logging messages


There might be situations when it is desirable to have logging messages rendered
in an audible rather than a visible format. This is easy to do if you have
text-to-speech (TTS) functionality available in your system, even if it doesn't have
a Python binding. Most TTS systems have a command line program you can run, and
this can be invoked from a handler using @ref{d5,,subprocess}. It's assumed here
that TTS command line programs won't expect to interact with users or take a
long time to complete, and that the frequency of logged messages will be not so
high as to swamp the user with messages, and that it's acceptable to have the
messages spoken one at a time rather than concurrently, The example implementation
below waits for one message to be spoken before the next is processed, and this
might cause other handlers to be kept waiting. Here is a short example showing
the approach, which assumes that the @code{espeak} TTS package is available:

@example
import logging
import subprocess
import sys

class TTSHandler(logging.Handler):
    def emit(self, record):
        msg = self.format(record)
        # Speak slowly in a female English voice
        cmd = ['espeak', '-s150', '-ven+f3', msg]
        p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
                             stderr=subprocess.STDOUT)
        # wait for the program to finish
        p.communicate()

def configure_logging():
    h = TTSHandler()
    root = logging.getLogger()
    root.addHandler(h)
    # the default formatter just returns the message
    root.setLevel(logging.DEBUG)

def main():
    logging.info('Hello')
    logging.debug('Goodbye')

if __name__ == '__main__':
    configure_logging()
    sys.exit(main())
@end example

When run, this script should say "Hello" and then "Goodbye" in a female voice.

The above approach can, of course, be adapted to other TTS systems and even
other systems altogether which can process messages via external programs run
from a command line.

@node Buffering logging messages and outputting them conditionally,Sending logging messages to email with buffering,Speaking logging messages,Recettes pour la journalisation
@anchor{howto/logging-cookbook buffered-logging}@anchor{4e71}@anchor{howto/logging-cookbook buffering-logging-messages-and-outputting-them-conditionally}@anchor{4e72}
@subsection Buffering logging messages and outputting them conditionally


There might be situations where you want to log messages in a temporary area
and only output them if a certain condition occurs. For example, you may want to
start logging debug events in a function, and if the function completes without
errors, you don't want to clutter the log with the collected debug information,
but if there is an error, you want all the debug information to be output as well
as the error.

Here is an example which shows how you could do this using a decorator for your
functions where you want logging to behave this way. It makes use of the
@ref{2c4d,,logging.handlers.MemoryHandler}, which allows buffering of logged events
until some condition occurs, at which point the buffered events are @code{flushed}
- passed to another handler (the @code{target} handler) for processing. By default,
the @code{MemoryHandler} flushed when its buffer gets filled up or an event whose
level is greater than or equal to a specified threshold is seen. You can use this
recipe with a more specialised subclass of @code{MemoryHandler} if you want custom
flushing behavior.

The example script has a simple function, @code{foo}, which just cycles through
all the logging levels, writing to @code{sys.stderr} to say what level it's about
to log at, and then actually logging a message at that level. You can pass a
parameter to @code{foo} which, if true, will log at ERROR and CRITICAL levels -
otherwise, it only logs at DEBUG, INFO and WARNING levels.

The script just arranges to decorate @code{foo} with a decorator which will do the
conditional logging that's required. The decorator takes a logger as a parameter
and attaches a memory handler for the duration of the call to the decorated
function. The decorator can be additionally parameterised using a target handler,
a level at which flushing should occur, and a capacity for the buffer (number of
records buffered). These default to a @ref{11d5,,StreamHandler} which
writes to @code{sys.stderr}, @code{logging.ERROR} and @code{100} respectively.

Here's the script:

@example
import logging
from logging.handlers import MemoryHandler
import sys

logger = logging.getLogger(__name__)
logger.addHandler(logging.NullHandler())

def log_if_errors(logger, target_handler=None, flush_level=None, capacity=None):
    if target_handler is None:
        target_handler = logging.StreamHandler()
    if flush_level is None:
        flush_level = logging.ERROR
    if capacity is None:
        capacity = 100
    handler = MemoryHandler(capacity, flushLevel=flush_level, target=target_handler)

    def decorator(fn):
        def wrapper(*args, **kwargs):
            logger.addHandler(handler)
            try:
                return fn(*args, **kwargs)
            except Exception:
                logger.exception('call failed')
                raise
            finally:
                super(MemoryHandler, handler).flush()
                logger.removeHandler(handler)
        return wrapper

    return decorator

def write_line(s):
    sys.stderr.write('%s\n' % s)

def foo(fail=False):
    write_line('about to log at DEBUG ...')
    logger.debug('Actually logged at DEBUG')
    write_line('about to log at INFO ...')
    logger.info('Actually logged at INFO')
    write_line('about to log at WARNING ...')
    logger.warning('Actually logged at WARNING')
    if fail:
        write_line('about to log at ERROR ...')
        logger.error('Actually logged at ERROR')
        write_line('about to log at CRITICAL ...')
        logger.critical('Actually logged at CRITICAL')
    return fail

decorated_foo = log_if_errors(logger)(foo)

if __name__ == '__main__':
    logger.setLevel(logging.DEBUG)
    write_line('Calling undecorated foo with False')
    assert not foo(False)
    write_line('Calling undecorated foo with True')
    assert foo(True)
    write_line('Calling decorated foo with False')
    assert not decorated_foo(False)
    write_line('Calling decorated foo with True')
    assert decorated_foo(True)
@end example

When this script is run, the following output should be observed:

@example
Calling undecorated foo with False
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
Calling undecorated foo with True
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
about to log at ERROR ...
about to log at CRITICAL ...
Calling decorated foo with False
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
Calling decorated foo with True
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
about to log at ERROR ...
Actually logged at DEBUG
Actually logged at INFO
Actually logged at WARNING
Actually logged at ERROR
about to log at CRITICAL ...
Actually logged at CRITICAL
@end example

As you can see, actual logging output only occurs when an event is logged whose
severity is ERROR or greater, but in that case, any previous events at lower
severities are also logged.

You can of course use the conventional means of decoration:

@example
@@log_if_errors(logger)
def foo(fail=False):
    ...
@end example

@node Sending logging messages to email with buffering,Formatting times using UTC GMT via configuration,Buffering logging messages and outputting them conditionally,Recettes pour la journalisation
@anchor{howto/logging-cookbook buffered-smtp}@anchor{4e73}@anchor{howto/logging-cookbook sending-logging-messages-to-email-with-buffering}@anchor{4e74}
@subsection Sending logging messages to email, with buffering


To illustrate how you can send log messages via email, so that a set number of
messages are sent per email, you can subclass
@ref{2c9e,,BufferingHandler}. In the following  example, which you can
adapt to suit your specific needs, a simple test harness is provided which allows you
to run the script with command line arguments specifying what you typically need to
send things via SMTP. (Run the downloaded script with the @code{-h} argument to see the
required and optional arguments.)

@example
import logging
import logging.handlers
import smtplib

class BufferingSMTPHandler(logging.handlers.BufferingHandler):
    def __init__(self, mailhost, port, username, password, fromaddr, toaddrs,
                 subject, capacity):
        logging.handlers.BufferingHandler.__init__(self, capacity)
        self.mailhost = mailhost
        self.mailport = port
        self.username = username
        self.password = password
        self.fromaddr = fromaddr
        if isinstance(toaddrs, str):
            toaddrs = [toaddrs]
        self.toaddrs = toaddrs
        self.subject = subject
        self.setFormatter(logging.Formatter("%(asctime)s %(levelname)-5s %(message)s"))

    def flush(self):
        if len(self.buffer) > 0:
            try:
                smtp = smtplib.SMTP(self.mailhost, self.mailport)
                smtp.starttls()
                smtp.login(self.username, self.password)
                msg = "From: %s\r\nTo: %s\r\nSubject: %s\r\n\r\n" % (self.fromaddr, ','.join(self.toaddrs), self.subject)
                for record in self.buffer:
                    s = self.format(record)
                    msg = msg + s + "\r\n"
                smtp.sendmail(self.fromaddr, self.toaddrs, msg)
                smtp.quit()
            except Exception:
                if logging.raiseExceptions:
                    raise
            self.buffer = []

if __name__ == '__main__':
    import argparse

    ap = argparse.ArgumentParser()
    aa = ap.add_argument
    aa('host', metavar='HOST', help='SMTP server')
    aa('--port', '-p', type=int, default=587, help='SMTP port')
    aa('user', metavar='USER', help='SMTP username')
    aa('password', metavar='PASSWORD', help='SMTP password')
    aa('to', metavar='TO', help='Addressee for emails')
    aa('sender', metavar='SENDER', help='Sender email address')
    aa('--subject', '-s',
       default='Test Logging email from Python logging module (buffering)',
       help='Subject of email')
    options = ap.parse_args()
    logger = logging.getLogger()
    logger.setLevel(logging.DEBUG)
    h = BufferingSMTPHandler(options.host, options.port, options.user,
                             options.password, options.sender,
                             options.to, options.subject, 10)
    logger.addHandler(h)
    for i in range(102):
        logger.info("Info index = %d", i)
    h.flush()
    h.close()
@end example

If you run this script and your SMTP server is correctly set up, you should find that
it sends eleven emails to the addressee you specify. The first ten emails will each
have ten log messages, and the eleventh will have two messages. That makes up 102
messages as specified in the script.

@node Formatting times using UTC GMT via configuration,Using a context manager for selective logging,Sending logging messages to email with buffering,Recettes pour la journalisation
@anchor{howto/logging-cookbook formatting-times-using-utc-gmt-via-configuration}@anchor{4e75}@anchor{howto/logging-cookbook utc-formatting}@anchor{4e76}
@subsection Formatting times using UTC (GMT) via configuration


Sometimes you want to format times using UTC, which can be done using a class
such as @code{UTCFormatter}, shown below:

@example
import logging
import time

class UTCFormatter(logging.Formatter):
    converter = time.gmtime
@end example

and you can then use the @code{UTCFormatter} in your code instead of
@ref{1449,,Formatter}. If you want to do that via configuration, you can
use the @ref{118d,,dictConfig()} API with an approach illustrated by
the following complete example:

@example
import logging
import logging.config
import time

class UTCFormatter(logging.Formatter):
    converter = time.gmtime

LOGGING = @{
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': @{
        'utc': @{
            '()': UTCFormatter,
            'format': '%(asctime)s %(message)s',
        @},
        'local': @{
            'format': '%(asctime)s %(message)s',
        @}
    @},
    'handlers': @{
        'console1': @{
            'class': 'logging.StreamHandler',
            'formatter': 'utc',
        @},
        'console2': @{
            'class': 'logging.StreamHandler',
            'formatter': 'local',
        @},
    @},
    'root': @{
        'handlers': ['console1', 'console2'],
   @}
@}

if __name__ == '__main__':
    logging.config.dictConfig(LOGGING)
    logging.warning('The local time is %s', time.asctime())
@end example

When this script is run, it should print something like:

@example
2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015
2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015
@end example

showing how the time is formatted both as local time and UTC, one for each
handler.

@node Using a context manager for selective logging,A CLI application starter template,Formatting times using UTC GMT via configuration,Recettes pour la journalisation
@anchor{howto/logging-cookbook context-manager}@anchor{4e77}@anchor{howto/logging-cookbook using-a-context-manager-for-selective-logging}@anchor{4e78}
@subsection Using a context manager for selective logging


There are times when it would be useful to temporarily change the logging
configuration and revert it back after doing something. For this, a context
manager is the most obvious way of saving and restoring the logging context.
Here is a simple example of such a context manager, which allows you to
optionally change the logging level and add a logging handler purely in the
scope of the context manager:

@example
import logging
import sys

class LoggingContext:
    def __init__(self, logger, level=None, handler=None, close=True):
        self.logger = logger
        self.level = level
        self.handler = handler
        self.close = close

    def __enter__(self):
        if self.level is not None:
            self.old_level = self.logger.level
            self.logger.setLevel(self.level)
        if self.handler:
            self.logger.addHandler(self.handler)

    def __exit__(self, et, ev, tb):
        if self.level is not None:
            self.logger.setLevel(self.old_level)
        if self.handler:
            self.logger.removeHandler(self.handler)
        if self.handler and self.close:
            self.handler.close()
        # implicit return of None => don't swallow exceptions
@end example

If you specify a level value, the logger's level is set to that value in the
scope of the with block covered by the context manager. If you specify a
handler, it is added to the logger on entry to the block and removed on exit
from the block. You can also ask the manager to close the handler for you on
block exit - you could do this if you don't need the handler any more.

To illustrate how it works, we can add the following block of code to the
above:

@example
if __name__ == '__main__':
    logger = logging.getLogger('foo')
    logger.addHandler(logging.StreamHandler())
    logger.setLevel(logging.INFO)
    logger.info('1. This should appear just once on stderr.')
    logger.debug('2. This should not appear.')
    with LoggingContext(logger, level=logging.DEBUG):
        logger.debug('3. This should appear once on stderr.')
    logger.debug('4. This should not appear.')
    h = logging.StreamHandler(sys.stdout)
    with LoggingContext(logger, level=logging.DEBUG, handler=h, close=True):
        logger.debug('5. This should appear twice - once on stderr and once on stdout.')
    logger.info('6. This should appear just once on stderr.')
    logger.debug('7. This should not appear.')
@end example

We initially set the logger's level to @code{INFO}, so message #1 appears and
message #2 doesn't. We then change the level to @code{DEBUG} temporarily in the
following @code{with} block, and so message #3 appears. After the block exits, the
logger's level is restored to @code{INFO} and so message #4 doesn't appear. In the
next @code{with} block, we set the level to @code{DEBUG} again but also add a handler
writing to @code{sys.stdout}. Thus, message #5 appears twice on the console (once
via @code{stderr} and once via @code{stdout}). After the @code{with} statement's
completion, the status is as it was before so message #6 appears (like message
#1) whereas message #7 doesn't (just like message #2).

If we run the resulting script, the result is as follows:

@example
$ python logctx.py
1. This should appear just once on stderr.
3. This should appear once on stderr.
5. This should appear twice - once on stderr and once on stdout.
5. This should appear twice - once on stderr and once on stdout.
6. This should appear just once on stderr.
@end example

If we run it again, but pipe @code{stderr} to @code{/dev/null}, we see the following,
which is the only message written to @code{stdout}:

@example
$ python logctx.py 2>/dev/null
5. This should appear twice - once on stderr and once on stdout.
@end example

Once again, but piping @code{stdout} to @code{/dev/null}, we get:

@example
$ python logctx.py >/dev/null
1. This should appear just once on stderr.
3. This should appear once on stderr.
5. This should appear twice - once on stderr and once on stdout.
6. This should appear just once on stderr.
@end example

In this case, the message #5 printed to @code{stdout} doesn't appear, as expected.

Of course, the approach described here can be generalised, for example to attach
logging filters temporarily. Note that the above code works in Python 2 as well
as Python 3.

@node A CLI application starter template,A Qt GUI for logging,Using a context manager for selective logging,Recettes pour la journalisation
@anchor{howto/logging-cookbook a-cli-application-starter-template}@anchor{4e79}@anchor{howto/logging-cookbook starter-template}@anchor{4e7a}
@subsection A CLI application starter template


Here's an example which shows how you can:


@itemize *

@item 
Use a logging level based on command-line arguments

@item 
Dispatch to multiple subcommands in separate files, all logging at the same
level in a consistent way

@item 
Make use of simple, minimal configuration
@end itemize

Suppose we have a command-line application whose job is to stop, start or
restart some services. This could be organised for the purposes of illustration
as a file @code{app.py} that is the main script for the application, with individual
commands implemented in @code{start.py}, @code{stop.py} and @code{restart.py}. Suppose
further that we want to control the verbosity of the application via a
command-line argument, defaulting to @code{logging.INFO}. Here's one way that
@code{app.py} could be written:

@example
import argparse
import importlib
import logging
import os
import sys

def main(args=None):
    scriptname = os.path.basename(__file__)
    parser = argparse.ArgumentParser(scriptname)
    levels = ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')
    parser.add_argument('--log-level', default='INFO', choices=levels)
    subparsers = parser.add_subparsers(dest='command',
                                       help='Available commands:')
    start_cmd = subparsers.add_parser('start', help='Start a service')
    start_cmd.add_argument('name', metavar='NAME',
                           help='Name of service to start')
    stop_cmd = subparsers.add_parser('stop',
                                     help='Stop one or more services')
    stop_cmd.add_argument('names', metavar='NAME', nargs='+',
                          help='Name of service to stop')
    restart_cmd = subparsers.add_parser('restart',
                                        help='Restart one or more services')
    restart_cmd.add_argument('names', metavar='NAME', nargs='+',
                             help='Name of service to restart')
    options = parser.parse_args()
    # the code to dispatch commands could all be in this file. For the purposes
    # of illustration only, we implement each command in a separate module.
    try:
        mod = importlib.import_module(options.command)
        cmd = getattr(mod, 'command')
    except (ImportError, AttributeError):
        print('Unable to find the code for command \'%s\'@w{'} % options.command)
        return 1
    # Could get fancy here and load configuration from file or dictionary
    logging.basicConfig(level=options.log_level,
                        format='%(levelname)s %(name)s %(message)s')
    cmd(options)

if __name__ == '__main__':
    sys.exit(main())
@end example

And the @code{start}, @code{stop} and @code{restart} commands can be implemented in
separate modules, like so for starting:

@example
# start.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    logger.debug('About to start %s', options.name)
    # actually do the command processing here ...
    logger.info('Started the \'%s\' service.', options.name)
@end example

and thus for stopping:

@example
# stop.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    n = len(options.names)
    if n == 1:
        plural = '@w{'}
        services = '\'%s\'@w{'} % options.names[0]
    else:
        plural = 's'
        services = ', '.join('\'%s\'@w{'} % name for name in options.names)
        i = services.rfind(', ')
        services = services[:i] + ' and ' + services[i + 2:]
    logger.debug('About to stop %s', services)
    # actually do the command processing here ...
    logger.info('Stopped the %s service%s.', services, plural)
@end example

and similarly for restarting:

@example
# restart.py
import logging

logger = logging.getLogger(__name__)

def command(options):
    n = len(options.names)
    if n == 1:
        plural = '@w{'}
        services = '\'%s\'@w{'} % options.names[0]
    else:
        plural = 's'
        services = ', '.join('\'%s\'@w{'} % name for name in options.names)
        i = services.rfind(', ')
        services = services[:i] + ' and ' + services[i + 2:]
    logger.debug('About to restart %s', services)
    # actually do the command processing here ...
    logger.info('Restarted the %s service%s.', services, plural)
@end example

If we run this application with the default log level, we get output like this:

@example
$ python app.py start foo
INFO start Started the 'foo' service.

$ python app.py stop foo bar
INFO stop Stopped the 'foo' and 'bar' services.

$ python app.py restart foo bar baz
INFO restart Restarted the 'foo', 'bar' and 'baz' services.
@end example

The first word is the logging level, and the second word is the module or
package name of the place where the event was logged.

If we change the logging level, then we can change the information sent to the
log. For example, if we want more information:

@example
$ python app.py --log-level DEBUG start foo
DEBUG start About to start foo
INFO start Started the 'foo' service.

$ python app.py --log-level DEBUG stop foo bar
DEBUG stop About to stop 'foo' and 'bar'
INFO stop Stopped the 'foo' and 'bar' services.

$ python app.py --log-level DEBUG restart foo bar baz
DEBUG restart About to restart 'foo', 'bar' and 'baz'
INFO restart Restarted the 'foo', 'bar' and 'baz' services.
@end example

And if we want less:

@example
$ python app.py --log-level WARNING start foo
$ python app.py --log-level WARNING stop foo bar
$ python app.py --log-level WARNING restart foo bar baz
@end example

In this case, the commands don't print anything to the console, since nothing
at @code{WARNING} level or above is logged by them.

@node A Qt GUI for logging,Logging to syslog with RFC5424 support,A CLI application starter template,Recettes pour la journalisation
@anchor{howto/logging-cookbook a-qt-gui-for-logging}@anchor{4e7b}@anchor{howto/logging-cookbook qt-gui}@anchor{4e7c}
@subsection A Qt GUI for logging


A question that comes up from time to time is about how to log to a GUI
application. The Qt@footnote{https://www.qt.io/} framework is a popular
cross-platform UI framework with Python bindings using PySide2@footnote{https://pypi.org/project/PySide2/}
or PyQt5@footnote{https://pypi.org/project/PyQt5/} libraries.

The following example shows how to log to a Qt GUI. This introduces a simple
@code{QtHandler} class which takes a callable, which should be a slot in the main
thread that does GUI updates. A worker thread is also created to show how you
can log to the GUI from both the UI itself (via a button for manual logging)
as well as a worker thread doing work in the background (here, just logging
messages at random levels with random short delays in between).

The worker thread is implemented using Qt's @code{QThread} class rather than the
@ref{ec,,threading} module, as there are circumstances where one has to use
@code{QThread}, which offers better integration with other @code{Qt} components.

The code should work with recent releases of any of @code{PySide6}, @code{PyQt6},
@code{PySide2} or @code{PyQt5}. You should be able to adapt the approach to earlier
versions of Qt. Please refer to the comments in the code snippet for more
detailed information.

@example
import datetime
import logging
import random
import sys
import time

# Deal with minor differences between different Qt packages
try:
    from PySide6 import QtCore, QtGui, QtWidgets
    Signal = QtCore.Signal
    Slot = QtCore.Slot
except ImportError:
    try:
        from PyQt6 import QtCore, QtGui, QtWidgets
        Signal = QtCore.pyqtSignal
        Slot = QtCore.pyqtSlot
    except ImportError:
        try:
            from PySide2 import QtCore, QtGui, QtWidgets
            Signal = QtCore.Signal
            Slot = QtCore.Slot
        except ImportError:
            from PyQt5 import QtCore, QtGui, QtWidgets
            Signal = QtCore.pyqtSignal
            Slot = QtCore.pyqtSlot

logger = logging.getLogger(__name__)


#
# Signals need to be contained in a QObject or subclass in order to be correctly
# initialized.
#
class Signaller(QtCore.QObject):
    signal = Signal(str, logging.LogRecord)

#
# Output to a Qt GUI is only supposed to happen on the main thread. So, this
# handler is designed to take a slot function which is set up to run in the main
# thread. In this example, the function takes a string argument which is a
# formatted log message, and the log record which generated it. The formatted
# string is just a convenience - you could format a string for output any way
# you like in the slot function itself.
#
# You specify the slot function to do whatever GUI updates you want. The handler
# doesn't know or care about specific UI elements.
#
class QtHandler(logging.Handler):
    def __init__(self, slotfunc, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.signaller = Signaller()
        self.signaller.signal.connect(slotfunc)

    def emit(self, record):
        s = self.format(record)
        self.signaller.signal.emit(s, record)

#
# This example uses QThreads, which means that the threads at the Python level
# are named something like "Dummy-1". The function below gets the Qt name of the
# current thread.
#
def ctname():
    return QtCore.QThread.currentThread().objectName()


#
# Used to generate random levels for logging.
#
LEVELS = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR,
          logging.CRITICAL)

#
# This worker class represents work that is done in a thread separate to the
# main thread. The way the thread is kicked off to do work is via a button press
# that connects to a slot in the worker.
#
# Because the default threadName value in the LogRecord isn't much use, we add
# a qThreadName which contains the QThread name as computed above, and pass that
# value in an "extra" dictionary which is used to update the LogRecord with the
# QThread name.
#
# This example worker just outputs messages sequentially, interspersed with
# random delays of the order of a few seconds.
#
class Worker(QtCore.QObject):
    @@Slot()
    def start(self):
        extra = @{'qThreadName': ctname() @}
        logger.debug('Started work', extra=extra)
        i = 1
        # Let the thread run until interrupted. This allows reasonably clean
        # thread termination.
        while not QtCore.QThread.currentThread().isInterruptionRequested():
            delay = 0.5 + random.random() * 2
            time.sleep(delay)
            try:
                if random.random() < 0.1:
                    raise ValueError('Exception raised: %d' % i)
                else:
                    level = random.choice(LEVELS)
                    logger.log(level, 'Message after delay of %3.1f: %d', delay, i, extra=extra)
            except ValueError as e:
                logger.exception('Failed: %s', e, extra=extra)
            i += 1

#
# Implement a simple UI for this cookbook example. This contains:
#
# * A read-only text edit window which holds formatted log messages
# * A button to start work and log stuff in a separate thread
# * A button to log something from the main thread
# * A button to clear the log window
#
class Window(QtWidgets.QWidget):

    COLORS = @{
        logging.DEBUG: 'black',
        logging.INFO: 'blue',
        logging.WARNING: 'orange',
        logging.ERROR: 'red',
        logging.CRITICAL: 'purple',
    @}

    def __init__(self, app):
        super().__init__()
        self.app = app
        self.textedit = te = QtWidgets.QPlainTextEdit(self)
        # Set whatever the default monospace font is for the platform
        f = QtGui.QFont('nosuchfont')
        if hasattr(f, 'Monospace'):
            f.setStyleHint(f.Monospace)
        else:
            f.setStyleHint(f.StyleHint.Monospace)  # for Qt6
        te.setFont(f)
        te.setReadOnly(True)
        PB = QtWidgets.QPushButton
        self.work_button = PB('Start background work', self)
        self.log_button = PB('Log a message at a random level', self)
        self.clear_button = PB('Clear log window', self)
        self.handler = h = QtHandler(self.update_status)
        # Remember to use qThreadName rather than threadName in the format string.
        fs = '%(asctime)s %(qThreadName)-12s %(levelname)-8s %(message)s'
        formatter = logging.Formatter(fs)
        h.setFormatter(formatter)
        logger.addHandler(h)
        # Set up to terminate the QThread when we exit
        app.aboutToQuit.connect(self.force_quit)

        # Lay out all the widgets
        layout = QtWidgets.QVBoxLayout(self)
        layout.addWidget(te)
        layout.addWidget(self.work_button)
        layout.addWidget(self.log_button)
        layout.addWidget(self.clear_button)
        self.setFixedSize(900, 400)

        # Connect the non-worker slots and signals
        self.log_button.clicked.connect(self.manual_update)
        self.clear_button.clicked.connect(self.clear_display)

        # Start a new worker thread and connect the slots for the worker
        self.start_thread()
        self.work_button.clicked.connect(self.worker.start)
        # Once started, the button should be disabled
        self.work_button.clicked.connect(lambda : self.work_button.setEnabled(False))

    def start_thread(self):
        self.worker = Worker()
        self.worker_thread = QtCore.QThread()
        self.worker.setObjectName('Worker')
        self.worker_thread.setObjectName('WorkerThread')  # for qThreadName
        self.worker.moveToThread(self.worker_thread)
        # This will start an event loop in the worker thread
        self.worker_thread.start()

    def kill_thread(self):
        # Just tell the worker to stop, then tell it to quit and wait for that
        # to happen
        self.worker_thread.requestInterruption()
        if self.worker_thread.isRunning():
            self.worker_thread.quit()
            self.worker_thread.wait()
        else:
            print('worker has already exited.')

    def force_quit(self):
        # For use when the window is closed
        if self.worker_thread.isRunning():
            self.kill_thread()

    # The functions below update the UI and run in the main thread because
    # that's where the slots are set up

    @@Slot(str, logging.LogRecord)
    def update_status(self, status, record):
        color = self.COLORS.get(record.levelno, 'black')
        s = '<pre><font color="%s">%s</font></pre>' % (color, status)
        self.textedit.appendHtml(s)

    @@Slot()
    def manual_update(self):
        # This function uses the formatted message passed in, but also uses
        # information from the record to format the message in an appropriate
        # color according to its severity (level).
        level = random.choice(LEVELS)
        extra = @{'qThreadName': ctname() @}
        logger.log(level, 'Manually logged!', extra=extra)

    @@Slot()
    def clear_display(self):
        self.textedit.clear()


def main():
    QtCore.QThread.currentThread().setObjectName('MainThread')
    logging.getLogger().setLevel(logging.DEBUG)
    app = QtWidgets.QApplication(sys.argv)
    example = Window(app)
    example.show()
    if hasattr(app, 'exec'):
        rc = app.exec()
    else:
        rc = app.exec_()
    sys.exit(rc)

if __name__=='__main__':
    main()
@end example

@node Logging to syslog with RFC5424 support,How to treat a logger like an output stream,A Qt GUI for logging,Recettes pour la journalisation
@anchor{howto/logging-cookbook logging-to-syslog-with-rfc5424-support}@anchor{4e7d}
@subsection Logging to syslog with RFC5424 support


Although 
@geindex RFC; RFC 5424
RFC 5424@footnote{https://datatracker.ietf.org/doc/html/rfc5424.html} dates from 2009, most syslog servers are configured by default to
use the older 
@geindex RFC; RFC 3164
RFC 3164@footnote{https://datatracker.ietf.org/doc/html/rfc3164.html}, which hails from 2001. When @code{logging} was added to Python
in 2003, it supported the earlier (and only existing) protocol at the time. Since
RFC5424 came out, as there has not been widespread deployment of it in syslog
servers, the @ref{647,,SysLogHandler} functionality has not been
updated.

RFC 5424 contains some useful features such as support for structured data, and if you
need to be able to log to a syslog server with support for it, you can do so with a
subclassed handler which looks something like this:

@example
import datetime
import logging.handlers
import re
import socket
import time

class SysLogHandler5424(logging.handlers.SysLogHandler):

    tz_offset = re.compile(r'([+-]\d@{2@})(\d@{2@})$')
    escaped = re.compile(r'([\]"\\])')

    def __init__(self, *args, **kwargs):
        self.msgid = kwargs.pop('msgid', None)
        self.appname = kwargs.pop('appname', None)
        super().__init__(*args, **kwargs)

    def format(self, record):
        version = 1
        asctime = datetime.datetime.fromtimestamp(record.created).isoformat()
        m = self.tz_offset.match(time.strftime('%z'))
        has_offset = False
        if m and time.timezone:
            hrs, mins = m.groups()
            if int(hrs) or int(mins):
                has_offset = True
        if not has_offset:
            asctime += 'Z'
        else:
            asctime += f'@{hrs@}:@{mins@}'
        try:
            hostname = socket.gethostname()
        except Exception:
            hostname = '-'
        appname = self.appname or '-'
        procid = record.process
        msgid = '-'
        msg = super().format(record)
        sdata = '-'
        if hasattr(record, 'structured_data'):
            sd = record.structured_data
            # This should be a dict where the keys are SD-ID and the value is a
            # dict mapping PARAM-NAME to PARAM-VALUE (refer to the RFC for what these
            # mean)
            # There's no error checking here - it's purely for illustration, and you
            # can adapt this code for use in production environments
            parts = []

            def replacer(m):
                g = m.groups()
                return '\\' + g[0]

            for sdid, dv in sd.items():
                part = f'[@{sdid@}'
                for k, v in dv.items():
                    s = str(v)
                    s = self.escaped.sub(replacer, s)
                    part += f' @{k@}="@{s@}"'
                part += ']'
                parts.append(part)
            sdata = '@w{'}.join(parts)
        return f'@{version@} @{asctime@} @{hostname@} @{appname@} @{procid@} @{msgid@} @{sdata@} @{msg@}'
@end example

You'll need to be familiar with RFC 5424 to fully understand the above code, and it
may be that you have slightly different needs (e.g. for how you pass structural data
to the log). Nevertheless, the above should be adaptable to your speciric needs. With
the above handler, you'd pass structured data using something like this:

@example
sd = @{
    'foo@@12345': @{'bar': 'baz', 'baz': 'bozz', 'fizz': r'buzz'@},
    'foo@@54321': @{'rab': 'baz', 'zab': 'bozz', 'zzif': r'buzz'@}
@}
extra = @{'structured_data': sd@}
i = 1
logger.debug('Message %d', i, extra=extra)
@end example

@node How to treat a logger like an output stream,Patterns to avoid,Logging to syslog with RFC5424 support,Recettes pour la journalisation
@anchor{howto/logging-cookbook how-to-treat-a-logger-like-an-output-stream}@anchor{4e7e}
@subsection How to treat a logger like an output stream


Sometimes, you need to interface to a third-party API which expects a file-like
object to write to, but you want to direct the API's output to a logger. You
can do this using a class which wraps a logger with a file-like API.
Here's a short script illustrating such a class:

@example
import logging

class LoggerWriter:
    def __init__(self, logger, level):
        self.logger = logger
        self.level = level

    def write(self, message):
        if message != '\n':  # avoid printing bare newlines, if you like
            self.logger.log(self.level, message)

    def flush(self):
        # doesn't actually do anything, but might be expected of a file-like
        # object - so optional depending on your situation
        pass

    def close(self):
        # doesn't actually do anything, but might be expected of a file-like
        # object - so optional depending on your situation. You might want
        # to set a flag so that later calls to write raise an exception
        pass

def main():
    logging.basicConfig(level=logging.DEBUG)
    logger = logging.getLogger('demo')
    info_fp = LoggerWriter(logger, logging.INFO)
    debug_fp = LoggerWriter(logger, logging.DEBUG)
    print('An INFO message', file=info_fp)
    print('A DEBUG message', file=debug_fp)

if __name__ == "__main__":
    main()
@end example

When this script is run, it prints

@example
INFO:demo:An INFO message
DEBUG:demo:A DEBUG message
@end example

You could also use @code{LoggerWriter} to redirect @code{sys.stdout} and
@code{sys.stderr} by doing something like this:

@example
import sys

sys.stdout = LoggerWriter(logger, logging.INFO)
sys.stderr = LoggerWriter(logger, logging.WARNING)
@end example

You should do this `after' configuring logging for your needs. In the above
example, the @ref{9ee,,basicConfig()} call does this (using the
@code{sys.stderr} value `before' it is overwritten by a @code{LoggerWriter}
instance). Then, you'd get this kind of result:

@example
>>> print('Foo')
INFO:demo:Foo
>>> print('Bar', file=sys.stderr)
WARNING:demo:Bar
>>>
@end example

Of course, the examples above show output according to the format used by
@ref{9ee,,basicConfig()}, but you can use a different formatter when you
configure logging.

Note that with the above scheme, you are somewhat at the mercy of buffering and
the sequence of write calls which you are intercepting. For example, with the
definition of @code{LoggerWriter} above, if you have the snippet

@example
sys.stderr = LoggerWriter(logger, logging.WARNING)
1 / 0
@end example

then running the script results in

@example
WARNING:demo:Traceback (most recent call last):

WARNING:demo:  File "/home/runner/cookbook-loggerwriter/test.py", line 53, in <module>

WARNING:demo:
WARNING:demo:main()
WARNING:demo:  File "/home/runner/cookbook-loggerwriter/test.py", line 49, in main

WARNING:demo:
WARNING:demo:1 / 0
WARNING:demo:ZeroDivisionError
WARNING:demo::
WARNING:demo:division by zero
@end example

As you can see, this output isn't ideal. That's because the underlying code
which writes to @code{sys.stderr} makes multiple writes, each of which results in a
separate logged line (for example, the last three lines above). To get around
this problem, you need to buffer things and only output log lines when newlines
are seen. Let's use a slightly better implementation of @code{LoggerWriter}:

@example
class BufferingLoggerWriter(LoggerWriter):
    def __init__(self, logger, level):
        super().__init__(logger, level)
        self.buffer = '@w{'}

    def write(self, message):
        if '\n' not in message:
            self.buffer += message
        else:
            parts = message.split('\n')
            if self.buffer:
                s = self.buffer + parts.pop(0)
                self.logger.log(self.level, s)
            self.buffer = parts.pop()
            for part in parts:
                self.logger.log(self.level, part)
@end example

This just buffers up stuff until a newline is seen, and then logs complete
lines. With this approach, you get better output:

@example
WARNING:demo:Traceback (most recent call last):
WARNING:demo:  File "/home/runner/cookbook-loggerwriter/main.py", line 55, in <module>
WARNING:demo:    main()
WARNING:demo:  File "/home/runner/cookbook-loggerwriter/main.py", line 52, in main
WARNING:demo:    1/0
WARNING:demo:ZeroDivisionError: division by zero
@end example

@c patterns-to-avoid:

@node Patterns to avoid,Autres ressources<3>,How to treat a logger like an output stream,Recettes pour la journalisation
@anchor{howto/logging-cookbook patterns-to-avoid}@anchor{4e7f}
@subsection Patterns to avoid


Although the preceding sections have described ways of doing things you might
need to do or deal with, it is worth mentioning some usage patterns which are
`unhelpful', and which should therefore be avoided in most cases. The following
sections are in no particular order.

@menu
* Opening the same log file multiple times:: 
* Using loggers as attributes in a class or passing them as parameters:: 
* Adding handlers other than NullHandler to a logger in a library:: 
* Creating a lot of loggers:: 

@end menu

@node Opening the same log file multiple times,Using loggers as attributes in a class or passing them as parameters,,Patterns to avoid
@anchor{howto/logging-cookbook opening-the-same-log-file-multiple-times}@anchor{4e80}
@subsubsection Opening the same log file multiple times


On Windows, you will generally not be able to open the same file multiple times
as this will lead to a "file is in use by another process" error. However, on
POSIX platforms you'll not get any errors if you open the same file multiple
times. This could be done accidentally, for example by:


@itemize *

@item 
Adding a file handler more than once which references the same file (e.g. by
a copy/paste/forget-to-change error).

@item 
Opening two files that look different, as they have different names, but are
the same because one is a symbolic link to the other.

@item 
Forking a process, following which both parent and child have a reference to
the same file. This might be through use of the @ref{93,,multiprocessing} module,
for example.
@end itemize

Opening a file multiple times might `appear' to work most of the time, but can
lead to a number of problems in practice:


@itemize *

@item 
Logging output can be garbled because multiple threads or processes try to
write to the same file. Although logging guards against concurrent use of the
same handler instance by multiple threads, there is no such protection if
concurrent writes are attempted by two different threads using two different
handler instances which happen to point to the same file.

@item 
An attempt to delete a file (e.g. during file rotation) silently fails,
because there is another reference pointing to it. This can lead to confusion
and wasted debugging time - log entries end up in unexpected places, or are
lost altogether. Or a file that was supposed to be moved remains in place,
and grows in size unexpectedly despite size-based rotation being supposedly
in place.
@end itemize

Use the techniques outlined in @ref{4e51,,Journalisation vers un fichier unique à partir de plusieurs processus} to circumvent such
issues.

@node Using loggers as attributes in a class or passing them as parameters,Adding handlers other than NullHandler to a logger in a library,Opening the same log file multiple times,Patterns to avoid
@anchor{howto/logging-cookbook using-loggers-as-attributes-in-a-class-or-passing-them-as-parameters}@anchor{4e81}
@subsubsection Using loggers as attributes in a class or passing them as parameters


While there might be unusual cases where you'll need to do this, in general
there is no point because loggers are singletons. Code can always access a
given logger instance by name using @code{logging.getLogger(name)}, so passing
instances around and holding them as instance attributes is pointless. Note
that in other languages such as Java and C#, loggers are often static class
attributes. However, this pattern doesn't make sense in Python, where the
module (and not the class) is the unit of software decomposition.

@node Adding handlers other than NullHandler to a logger in a library,Creating a lot of loggers,Using loggers as attributes in a class or passing them as parameters,Patterns to avoid
@anchor{howto/logging-cookbook adding-handlers-other-than-nullhandler-to-a-logger-in-a-library}@anchor{4e82}
@subsubsection Adding handlers other than @code{NullHandler} to a logger in a library


Configuring logging by adding handlers, formatters and filters is the
responsibility of the application developer, not the library developer. If you
are maintaining a library, ensure that you don't add handlers to any of your
loggers other than a @ref{1262,,NullHandler} instance.

@node Creating a lot of loggers,,Adding handlers other than NullHandler to a logger in a library,Patterns to avoid
@anchor{howto/logging-cookbook creating-a-lot-of-loggers}@anchor{4e83}
@subsubsection Creating a lot of loggers


Loggers are singletons that are never freed during a script execution, and so
creating lots of loggers will use up memory which can't then be freed. Rather
than create a logger per e.g. file processed or network connection made, use
the @ref{2c23,,existing mechanisms} for passing contextual
information into your logs and restrict the loggers created to those describing
areas within your application (generally modules, but occasionally slightly
more fine-grained than that).

@node Autres ressources<3>,,Patterns to avoid,Recettes pour la journalisation
@anchor{howto/logging-cookbook cookbook-ref-links}@anchor{4e3d}@anchor{howto/logging-cookbook other-resources}@anchor{4e84}
@subsection Autres ressources



@subsubheading Voir aussi



@table @asis

@item Module @ref{86,,logging}

Référence de l’API du module de journalisation.

@item Module @ref{87,,logging.config}

API pour la configuration du module de journalisation.

@item Module @ref{88,,logging.handlers}

Gestionnaires utiles inclus avec le module de journalisation.
@end table

@ref{11d2,,Tutoriel de découverte}

@ref{11d3,,Tutoriel avancé}


@node Guide des expressions régulières,Guide pratique programmation avec les sockets,Recettes pour la journalisation,Les HOWTOs de Python
@anchor{howto/regex doc}@anchor{4e85}@anchor{howto/regex regex-howto}@anchor{2272}@anchor{howto/regex regular-expression-howto}@anchor{4e86}
@section Guide des expressions régulières


@*Auteur: 
A.M. Kuchling <@email{amk@@amk.ca}>


@c TODO:
@c Document lookbehind assertions
@c Better way of displaying a RE, a string, and what it matches
@c Mention optional argument to match.groups()
@c Unicode (at least a reference)

@subsubheading Résumé



Ce document constitue un guide d'introduction à l'utilisation des expressions régulières en Python avec le module @ref{b8,,re}. Il fournit une introduction plus abordable que la section correspondante dans le guide de référence de la bibliothèque.

@menu
* Introduction: Introduction<15>. 
* Motifs simples:: 
* Utilisation des expressions régulières:: 
* Des motifs plus puissants:: 
* Modification de chaînes:: 
* Problèmes classiques:: 
* Vos commentaires:: 

@end menu

@node Introduction<15>,Motifs simples,,Guide des expressions régulières
@anchor{howto/regex introduction}@anchor{4e87}
@subsection Introduction


Les expressions régulières (notées RE ou motifs `regex' dans ce document) sont essentiellement un petit langage de programmation hautement spécialisé embarqué dans Python et dont la manipulation est rendue possible par l'utilisation du module @ref{b8,,re}. En utilisant ce petit langage, vous définissez des règles pour spécifier une correspondance avec un ensemble souhaité de chaînes de caractères ; ces chaînes peuvent être des phrases, des adresses de courriel, des commandes `TeX' ou tout ce que vous voulez. Vous pouvez ensuite poser des questions telles que « Est-ce que cette chaîne de caractères correspond au motif ? » ou « Y a-t-il une correspondance pour ce motif à l'intérieur de la chaîne de caractères ? ». Vous pouvez aussi utiliser les RE pour modifier une chaîne de caractères ou la découper de différentes façons.

Un motif d'expression régulière est compilé en code intermédiaire (`bytecode' en anglais) qui est ensuite exécuté par un moteur de correspondance écrit en C. Pour une utilisation plus poussée, il peut s'avérer nécessaire de s'intéresser à la manière dont le moteur exécute la RE afin d'écrire une expression dont le code intermédiaire est plus rapide. L'optimisation n'est pas traitée dans ce document, parce qu'elle nécessite d'avoir une bonne compréhension des mécanismes internes du moteur de correspondance.

Le langage des expressions régulières est relativement petit et restreint, donc toutes les tâches de manipulation de chaînes de caractères ne peuvent pas être réalisées à l'aide d'expressions régulières. Il existe aussi des tâches qui `peuvent' être réalisées à l'aide d'expressions régulières mais qui ont tendance à produire des expressions régulières très compliquées. Dans ces cas, il est plus utile d'écrire du code Python pour réaliser le traitement ; même si le code Python est plus lent qu'une expression régulière élaborée, il sera probablement plus compréhensible.

@node Motifs simples,Utilisation des expressions régulières,Introduction<15>,Guide des expressions régulières
@anchor{howto/regex simple-patterns}@anchor{4e88}
@subsection Motifs simples


Nous commençons par étudier les expressions régulières les plus simples. Dans la mesure où les expressions régulières sont utilisées pour manipuler des chaînes de caractères, nous commençons par l'action la plus courante : la correspondance de caractères.

Pour une explication détaillée sur le concept informatique sous-jacent aux expressions régulières (automate à états déterministe ou non-déterministe), vous pouvez vous référer à n'importe quel manuel sur l'écriture de compilateurs.

@menu
* Correspondance de caractères:: 
* Répétitions:: 

@end menu

@node Correspondance de caractères,Répétitions,,Motifs simples
@anchor{howto/regex matching-characters}@anchor{4e89}
@subsubsection Correspondance de caractères


La plupart des lettres ou caractères correspondent simplement à eux-mêmes. Par exemple, l'expression régulière @code{test} correspond à la chaîne de caractères @code{test}, précisément. Vous pouvez activer le mode non-sensible à la casse qui permet à cette RE de correspondre également à @code{Test} ou @code{TEST} (ce sujet est traité par la suite).

Il existe des exceptions à cette règle ; certains caractères sont des `métacaractères' spéciaux et ne correspondent pas à eux-mêmes. Au lieu de cela, ils signalent que certaines choses non ordinaires doivent correspondre, ou ils affectent d'autre portions de la RE en les répétant ou en changeant leur sens. Une grande partie de ce document est consacrée au fonctionnement de ces métacaractères.

Voici une liste complète des métacaractères ; leur sens est décrit dans la suite de ce guide.

@example
. ^ $ * + ? @{ @} [ ] \ | ( )
@end example

Les premiers métacaractères que nous étudions sont @code{[} et @code{]}. Ils sont utilisés pour spécifier une classe de caractères, qui forme un ensemble de caractères dont vous souhaitez trouver la correspondance. Les caractères peuvent être listés individuellement, ou une plage de caractères peut être indiquée en fournissant deux caractères séparés par un @code{'-'}. Par exemple, @code{[abc]} correspond à n'importe quel caractère parmi @code{a}, @code{b} ou @code{c} ; c'est équivalent à @code{[a-c]}, qui utilise une plage pour exprimer le même ensemble de caractères. Si vous voulez trouver une chaîne qui ne contient que des lettres en minuscules, la RE est @code{[a-z]}.

Les métacaractères (à l’exception de @code{\}) ne sont pas actifs dans les classes. Par exemple, @code{[akm$]} correspond à n'importe quel caractère parmi @code{'a'}, @code{'k'}, @code{'m'} ou @code{'$'} ; @code{'$'} est habituellement un métacaractère mais dans une classe de caractères, il est dépourvu de sa signification spéciale.

Vous pouvez trouver une correspondance avec les caractères non listés dans une classe en spécifiant le `complément' de l'ensemble. Ceci est indiqué en plaçant un @code{'^'} en tant que premier caractère de la classe. Par exemple, @code{[^5]} correspond à tous les caractères, sauf @code{'5'}. Si le caret se trouve ailleurs dans la classe de caractères, il ne possède pas de signification spéciale. Ainsi, @code{[5^]} correspond au @code{'5'} ou au caractère @code{'^'}.

Le métacaractère le plus important est probablement la barre oblique inverse (`backslash' en anglais), @code{\}. Comme dans les chaînes de caractères en Python, la barre oblique inverse peut être suivie par différents caractères pour signaler différentes séquences spéciales. Elle est aussi utilisée pour échapper tous les métacaractères afin d'en trouver les correspondances dans les motifs ; par exemple, si vous devez trouver une correspondance pour @code{[} ou @code{\}, vous pouvez les précéder avec une barre oblique inverse pour annuler leur signification spéciale : @code{\[} ou @code{\\}.

Certaines séquences spéciales commençant par @code{'\'} représentent des ensembles de caractères prédéfinis qui sont souvent utiles, tels que l'ensemble des chiffres, l'ensemble des lettres ou l'ensemble des caractères qui ne sont pas des « blancs ».

Prenons un exemple : @code{\w} correspond à n'importe quel caractère alphanumérique. Si l'expression régulière est exprimée en `bytes', c'est équivalent à la classe @code{[a-zA-Z0-9_]}. Si l'expression régulière est une chaîne de caractères, @code{\w} correspond à tous les caractères identifiés comme lettre dans la base de données Unicode fournie par le module @ref{104,,unicodedata}. Vous pouvez utiliser la définition plus restrictive de @code{\w} dans un motif exprimé en chaîne de caractères en spécifiant l'option @ref{617,,re.ASCII} lors de la compilation de l'expression régulière.

La liste de séquences spéciales suivante est incomplète. Pour une liste complète des séquences et définitions de classes étendues relatives aux motifs de chaînes de caractères Unicode, reportez-vous à la dernière partie de la référence @ref{70e,,Syntaxe d'Expressions Régulières} de la bibliothèque standard. En général, les versions Unicode trouvent une correspondance avec n'importe quel caractère présent dans la catégorie appropriée de la base de données Unicode.


@table @asis

@item @code{\d}

Correspond à n'importe quel caractère numérique ; équivalent à la classe @code{[0-9]}.

@item @code{\D}

Correspond à n'importe quel caractère non numérique ; équivalent à la classe @code{[^0-9]}.

@item @code{\s}

Correspond à n'importe quel caractère « blanc » ; équivalent à la classe @code{[ \t\n\r\f\v]}.

@item @code{\S}

Correspond à n'importe quel caractère autre que « blanc » ; équivalent à la classe @code{[^ \t\n\r\f\v]}.

@item @code{\w}

Correspond à n'importe quel caractère alphanumérique ; équivalent à la classe @code{[a-zA-Z0-9_]}.

@item @code{\W}

Correspond à n'importe quel caractère non-alphanumérique ; équivalent à la classe @code{[^a-zA-Z0-9_]}.
@end table

Ces séquences peuvent être incluses dans une classe de caractères. Par exemple, @code{[\s,.]} est une classe de caractères qui correspond à tous les caractères « blanc » ou @code{','} ou @code{'.'}.

Le dernier métacaractère de cette section est @code{.}. Il correspond à tous les caractères, à l'exception du caractère de retour à la ligne ; il existe un mode alternatif (@ref{2273,,re.DOTALL}) dans lequel il correspond également au caractère de retour à la ligne. @code{.} est souvent utilisé lorsque l'on veut trouver une correspondance avec « n'importe quel caractère ».

@node Répétitions,,Correspondance de caractères,Motifs simples
@anchor{howto/regex repeating-things}@anchor{4e8a}
@subsubsection Répétitions


Trouver des correspondances de divers ensembles de caractères est la première utilisation des expressions régulières, ce que l'on ne peut pas faire avec les méthodes des chaînes. Cependant, si c'était la seule possibilité des expressions régulières, le gain ne serait pas significatif. Une autre utilisation consiste à spécifier des portions d'une RE qui peuvent être répétées un certain nombre de fois.

Le premier métacaractère pour la répétition que nous abordons est @code{*}. @code{*} ne correspond pas au caractère littéral @code{'*'} ; à la place, il spécifie que le caractère précédent peut correspondre zéro, une ou plusieurs fois (au lieu d'une seule fois).

Par exemple, @code{cha*t} correspond à @code{'cht'} (0 caractère @code{'a'}), @code{'chat'} (1 @code{'a'}), @code{'chaaat'} (3 caractères  @code{'a'}) et ainsi de suite.

Les répétitions telles que @code{*} sont `gloutonnes' ; quand vous répétez une RE, le moteur de correspondance essaie de trouver la correspondance la plus longue en répétant le motif tant qu'il le peut. Si la suite du motif ne correspond pas, le moteur de correspondance revient en arrière et essaie avec moins de répétitions.

Un exemple étape par étape mettra les choses au clair. Considérons l'expression @code{a[bcd]*b}. Elle correspond à la lettre @code{'a'}, suivi d'aucune ou plusieurs lettres de la classe @code{[bcd]} et finit par un @code{'b'}. Maintenant, supposons que nous cherchons une correspondance de cette RE avec la chaîne de caractères @code{'abcbd'}.


@multitable {xxxxxxxx} {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Étape

@tab

Correspond

@tab

Explication

@item

1

@tab

@code{a}

@tab

Le @code{a} correspond dans la RE.

@item

2

@tab

@code{abcbd}

@tab

Le moteur de correspondance trouve @code{[bcd]*}, va aussi loin qu'il le peut, c.-à-d. la fin de la chaîne.

@item

3

@tab

`échec'

@tab

Le moteur essaie de trouver une correspondance avec @code{b} mais la position courante est à la fin de la chaîne de caractères, donc il échoue.

@item

4

@tab

@code{abcb}

@tab

Retour en arrière, de manière à ce que @code{[bcd]*} corresponde avec un caractère de moins.

@item

5

@tab

`échec'

@tab

Essaie encore @code{b}, mais la position courante est le dernier caractère, qui est @code{'d'}.

@item

6

@tab

@code{abc}

@tab

Encore un retour en arrière, de manière à ce que @code{[bcd]*} ne corresponde qu'à @code{bc}.

@item

6

@tab

@code{abcb}

@tab

Essaie @code{b} encore une fois. Cette fois, le caractère à la position courante est @code{'b'}, donc cela fonctionne.

@end multitable


La fin de la RE est maintenant atteinte et la correspondance trouvée est @code{'abcb'}. Ceci démontre comment le moteur de correspondance essaie d'aller le plus loin possible en premier et, si la correspondance échoue, il revient progressivement en arrière et ré-essaie avec le reste de la RE encore et encore. Il revient en arrière jusqu'à qu'il n'y ait aucune correspondance pour @code{[bcd]*} et, si cela échoue toujours, le moteur conclut que la chaîne de caractères et la RE ne correspondent pas du tout.

Un autre métacaractère de répétition est @code{+}, qui fait correspondre une ou plusieurs fois. Faites bien attention à la différence entre @code{*} et @code{+} ; @code{*} fait correspondre `zéro' fois ou plus, ainsi ce qui doit être répété peut ne pas être présent du tout, alors que  @code{+} requiert au moins `une' occurrence. Pour continuer avec le même exemple, @code{cha+t} correspond avec @code{'chat'} (1 @code{'a'}), @code{'chaaat'} (3 @code{'a'}) mais ne correspond pas avec @code{'cht'}.

Il existe deux autres quantificateurs pour les répétitions. Le point d'interrogation, @code{?}, fait correspondre zéro ou une fois ; vous pouvez vous le représenter comme indiquant une option. Par exemple, @code{méta-?caractère} fait correspondre soit @code{'métacaractère'}, soit @code{'méta-caractère'}.

Le plus compliqué des quantificateurs est @code{@{m,n@}} où `m' et `n' sont des entiers décimaux. Ce quantificateur indique qu'il faut au moins `m' répétitions et au plus `n'. Par exemple, @code{a/@{1,3@}b} fait correspondre @code{'a/b'}, @code{'a//b'} et @code{'a///b'}. Elle ne fait pas correspondre @code{'ab'} (pas de barre oblique) ni @code{'a////b'} (quatre barres obliques).

Vous pouvez omettre soit `m', soit `n' ; dans ce cas, une valeur raisonnable est prise pour la valeur manquante. Omettre `m' considère que la borne basse est 0 alors qu'omettre `n' signifie qu'il n'y a pas de borne supérieure.

The simplest case @code{@{m@}} matches the preceding item exactly `m' times.
For example, @code{a/@{2@}b} will only match @code{'a//b'}.

Le lecteur attentif aura noté que les trois premiers quantificateurs peuvent être exprimés en utilisant cette notation. @code{@{0,@}} est la même chose que @code{*}, @code{@{1,@}} est équivalent à @code{+} et @code{@{0,1@}} se comporte comme @code{?}. Il est préférable d'utiliser @code{*}, @code{+} ou @code{?} quand vous le pouvez, simplement parce qu'ils sont plus courts et plus faciles à lire.

@node Utilisation des expressions régulières,Des motifs plus puissants,Motifs simples,Guide des expressions régulières
@anchor{howto/regex using-regular-expressions}@anchor{4e8b}
@subsection Utilisation des expressions régulières


Maintenant que nous avons vu quelques expressions régulières simples, utilisons-les concrètement. Le module @ref{b8,,re} fournit une interface pour le moteur de correspondance, ce qui permet de compiler les RE en objets et d'effectuer des correspondances avec.

@menu
* Compilation des expressions régulières:: 
* La maudite barre oblique inverse:: 
* Recherche de correspondances:: 
* Fonctions de niveau module: Fonctions de niveau module<3>. 
* Options de compilation:: 

@end menu

@node Compilation des expressions régulières,La maudite barre oblique inverse,,Utilisation des expressions régulières
@anchor{howto/regex compiling-regular-expressions}@anchor{4e8c}
@subsubsection Compilation des expressions régulières


Les expressions régulières sont compilées en objets motifs, qui possèdent des méthodes pour diverses opérations telles que la recherche de correspondances ou les substitutions dans les chaînes.

@example
>>> import re
>>> p = re.compile('ab*')
>>> p
re.compile('ab*')
@end example

@ref{bc1,,re.compile()} accepte aussi une option `flags', utilisée pour activer des fonctionnalités particulières et des variations de syntaxe. Nous étudierons les options disponibles plus tard et, pour l'instant, un petit exemple suffit :

@example
>>> p = re.compile('ab*', re.IGNORECASE)
@end example

La RE passée à @ref{bc1,,re.compile()} est une chaîne. Les RE sont des chaînes car les expressions régulières ne font pas partie intrinsèque du langage Python et aucune syntaxe particulière n'a été créée pour les exprimer (il existe des applications qui ne nécessitent aucune RE et il n'a donc aucune raison de grossir les spécifications du langage en incluant les RE). Ainsi, le module @ref{b8,,re} est simplement un module d'extension en C inclus dans Python, tout comme les modules @ref{cb,,socket} ou @ref{132,,zlib}.

Exprimer les RE comme des chaînes de caractères garde le langage Python plus simple mais introduit un inconvénient qui fait l'objet de la section suivante.

@node La maudite barre oblique inverse,Recherche de correspondances,Compilation des expressions régulières,Utilisation des expressions régulières
@anchor{howto/regex id1}@anchor{4e8d}@anchor{howto/regex the-backslash-plague}@anchor{4e8e}
@subsubsection La maudite barre oblique inverse


Comme indiqué précédemment, les expressions régulières utilisent la barre oblique inverse (`backslash' en anglais) pour indiquer des constructions particulières ou pour autoriser des caractères spéciaux sans que leur signification spéciale ne soit invoquée. C'est en contradiction avec l'usage de Python qui est qu'un caractère doit avoir la même signification dans les littéraux de chaînes de caractères.

Considérons que vous voulez écrire une RE qui fait correspondre la chaîne de caractères @code{\section} (on en trouve dans un fichier `LaTeX'). Pour savoir ce qu'il faut coder dans votre programme, commençons par la chaîne de caractères cherchée. Ensuite, nous devons échapper chaque barre oblique inverse et tout autre métacaractère en les précédant d'une barre oblique inverse, ce qui donne la chaîne de caractères @code{\\section}. La chaîne résultante qui doit être passée à @ref{bc1,,re.compile()} est donc @code{\\section}. Comme nous devons l'exprimer sous la forme d'une chaîne littérale Python, nous devons échapper les deux barres obliques inverses `encore une fois'.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Caractères

@tab

Niveau

@item

@code{\section}

@tab

Chaîne de caractère à chercher

@item

@code{\\section}

@tab

Barre oblique inverse échappée pour @ref{bc1,,re.compile()}

@item

@code{"\\\\section"}

@tab

Barres obliques inverses échappées pour un littéral de chaîne de caractères

@end multitable


Pour faire court, si vous cherchez une correspondance pour une barre oblique inverse littérale, écrivez @code{'\\\\'} dans votre chaîne RE, car l'expression régulière doit être @code{\\} et que chaque barre oblique inverse doit être exprimée comme @code{\\} dans un littéral chaîne de caractères Python. Dans les RE qui comportent plusieurs barres obliques inverses, cela conduit à beaucoup de barres obliques inverses et rend la chaîne résultante difficile à comprendre.

La solution consiste à utiliser les chaînes brutes Python pour les expressions régulières ; les barres obliques inverses ne sont pas gérées d'une manière particulière dans les chaînes littérales préfixées avec @code{'r'}. Ainsi, @code{r"\n"} est la chaîne de deux caractères contenant @code{'\'} et @code{'n'} alors que @code{"\n"} est la chaîne contenant uniquement le caractère retour à la ligne. Les expressions régulières sont souvent écrites dans le code Python en utilisant la notation « chaînes brutes ».

En complément, les séquences d'échappement valides dans les expressions régulières, mais non valides dans les littéraux chaînes classiques, produisent dorénavant un @ref{1a3,,DeprecationWarning} et, possiblement, deviendront une @ref{18b,,SyntaxError}, ce qui signifie que les séquences seront invalides si la notation « chaîne brute » ou l'échappement des barres obliques inverses ne sont pas utilisés.


@multitable {xxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 
@headitem

Chaîne normale

@tab

Chaîne de caractères brute

@item

@code{"ab*"}

@tab

@code{r"ab*"}

@item

@code{"\\\\section"}

@tab

@code{r"\\section"}

@item

@code{"\\w+\\s+\\1"}

@tab

@code{r"\w+\s+\1"}

@end multitable


@node Recherche de correspondances,Fonctions de niveau module<3>,La maudite barre oblique inverse,Utilisation des expressions régulières
@anchor{howto/regex performing-matches}@anchor{4e8f}
@subsubsection Recherche de correspondances


Une fois que nous avons un objet représentant une expression régulière compilée, qu'en faisons-nous ? Les objets motifs ont plusieurs méthodes et attributs. Seuls les plus significatifs seront couverts ici ; consultez la documentation @ref{b8,,re} pour la liste complète.


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Méthode/Attribut

@tab

Objectif

@item

@code{match()}

@tab

Détermine si la RE fait correspond dès le début de la chaîne.

@item

@code{search()}

@tab

Analyse la chaîne à la recherche d'une position où la RE correspond.

@item

@code{findall()}

@tab

Trouve toutes les sous-chaînes qui correspondent à la RE et les renvoie sous la forme d'une liste.

@item

@code{finditer()}

@tab

Trouve toutes les sous-chaînes qui correspondent à la RE et les renvoie sous la forme d'un @ref{1aa,,itérateur}.

@end multitable


@ref{2285,,match()} et @ref{2286,,search()} renvoient @code{None} si aucune correspondance ne peut être trouvée. Si elles trouvent une correspondance, une instance d'@ref{f72,,objet correspondance} est renvoyée, contenant les informations relatives à la correspondance : position de départ et de fin, la sous-chaîne qui correspond et d'autres informations.

You can learn about this by interactively experimenting with the @ref{b8,,re}
module.

Ce guide utilise l'interpréteur standard de Python pour ses exemples. Commencez par lancer l'interpréteur Python, importez le module @ref{b8,,re} et compilez une RE :

@example
>>> import re
>>> p = re.compile('[a-z]+')
>>> p
re.compile('[a-z]+')
@end example

Maintenant, vous pouvez tester des correspondances de la RE @code{[a-z]+} avec différentes chaînes. Une chaîne vide ne doit pas correspondre, puisque @code{+} indique « une ou plusieurs occurrences ». @ref{2285,,match()} doit renvoyer @code{None} dans ce cas, ce qui fait que l'interpréteur n'affiche rien. Vous pouvez afficher le résultat de @code{match()} explicitement pour que ce soit clair.

@example
>>> p.match("")
>>> print(p.match(""))
None
@end example

Maintenant, essayons sur une chaîne qui doit correspondre, par exemple @code{tempo}. Dans ce cas, @ref{2285,,match()} renvoie un @ref{f72,,objet correspondance}, vous pouvez ainsi stocker le résultat dans une variable pour une utilisation ultérieure.

@example
>>> m = p.match('tempo')
>>> m
<re.Match object; span=(0, 5), match='tempo'>
@end example

Maintenant, vous pouvez interroger l'@ref{f72,,objet correspondance} pour obtenir des informations sur la chaîne qui correspond. Les instances d'objets correspondances possèdent plusieurs méthodes et attributs ; les plus importants sont :


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Méthode/Attribut

@tab

Objectif

@item

@code{group()}

@tab

Renvoie la chaîne de caractères correspondant à la RE

@item

@code{start()}

@tab

Renvoie la position de début de la correspondance

@item

@code{end()}

@tab

Renvoie la position de fin de la correspondance

@item

@code{span()}

@tab

Renvoie un `n'-uplet contenant les positions (début, fin) de la correspondance

@end multitable


Essayons ces méthodes pour clarifier leur signification :

@example
>>> m.group()
'tempo'
>>> m.start(), m.end()
(0, 5)
>>> m.span()
(0, 5)
@end example

@ref{229b,,group()} renvoie la sous-chaîne qui correspond à la RE. @ref{229f,,start()} et @ref{22a0,,end()} renvoient les indices de début et de fin de la correspondance. @ref{22a1,,span()} renvoie les indices de début et de fin dans un seul couple. Comme la méthode @ref{2285,,match()} ne fait que vérifier si la RE correspond au début de la chaîne, @code{start()} vaut toujours zéro. Cependant, la méthode @ref{2286,,search()} d'un motif analyse toute la chaîne, afin de trouver une correspondance potentielle qui ne commence pas à zéro.

@example
>>> print(p.match('::: message'))
None
>>> m = p.search('::: message'); print(m)
<re.Match object; span=(4, 11), match='message'>
>>> m.group()
'message'
>>> m.span()
(4, 11)
@end example

Dans les programmes réels, la façon de faire la plus courante consiste à stocker l'@ref{f72,,objet correspondance} dans une variable, puis à vérifier s'il vaut @code{None}. Généralement, cela ressemble à ceci :

@example
p = re.compile( ... )
m = p.match( 'string goes here' )
if m:
    print('Match found: ', m.group())
else:
    print('No match')
@end example

Deux méthodes de motifs renvoient toutes les correspondances pour un motif. @ref{2291,,findall()} renvoie une liste des chaînes qui correspondent :

@example
>>> p = re.compile(r'\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']
@end example

Le préfixe @code{r}, qui indique une chaîne brute littérale, est nécessaire dans cet exemple car les séquences d'échappement dans une chaîne littérale qui ne sont pas reconnues par Python, alors qu'elles le sont par les expressions régulières, produisent maintenant un @ref{1a3,,DeprecationWarning} et deviendront possiblement des @ref{18b,,SyntaxError}.  Reportez-vous à @ref{4e8e,,La maudite barre oblique inverse}.

@ref{2291,,findall()} doit créer la liste entière avant de la renvoyer comme résultat. La méthode @ref{2292,,finditer()} renvoie une séquence d'instances d'@ref{f72,,objets correspondances} en tant @ref{1aa,,qu'itérateur} :

@example
>>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
>>> iterator  
<callable_iterator object at 0x...>
>>> for match in iterator:
...     print(match.span())
...
(0, 2)
(22, 24)
(29, 31)
@end example

@node Fonctions de niveau module<3>,Options de compilation,Recherche de correspondances,Utilisation des expressions régulières
@anchor{howto/regex module-level-functions}@anchor{4e90}
@subsubsection Fonctions de niveau module


Vous n'avez pas besoin de créer un objet motif et d'appeler ses méthodes ; le module @ref{b8,,re} fournit des fonctions à son niveau, ce sont @ref{120b,,match()}, @ref{120a,,search()}, @ref{1013,,findall()}, @ref{2a0,,sub()} et ainsi de suite. Ces fonctions prennent les mêmes arguments que les méthodes correspondantes des objets motifs, avec la chaîne RE ajoutée en tant que premier argument. Elles renvoient toujours @code{None} ou une instance d'@ref{f72,,objet correspondance}.

@example
>>> print(re.match(r'From\s+', 'Fromage amk'))
None
>>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998')  
<re.Match object; span=(0, 5), match='From '>
@end example

En interne, ces fonctions créent simplement un objet motif pour vous et appellent la méthode appropriée de cet objet. Elles stockent également l'objet compilé dans un cache afin que les appels suivants qui utilisent la même RE n'aient pas besoin d'analyser le motif une nouvelle fois.

Devez-vous utiliser ces fonctions au niveau des modules ou devez-vous calculer le motif et appeler vous-même ses méthodes ? Si vous utilisez l'expression régulière à l'intérieur d'une boucle, la pré-compilation permet d'économiser quelques appels de fonctions. En dehors des boucles, il n'y a pas beaucoup de différence grâce au cache interne.

@node Options de compilation,,Fonctions de niveau module<3>,Utilisation des expressions régulières
@anchor{howto/regex compilation-flags}@anchor{4e91}
@subsubsection Options de compilation


Les options de compilation vous permettent de modifier le comportement des expressions régulières. Ces options sont accessibles dans le module @ref{b8,,re} par deux noms, un long du type @ref{16b0,,IGNORECASE} et un court (une seule lettre) tel que @ref{2277,,I} (si vous êtes habitués aux modificateurs de motifs Perl, la version courte utilise les mêmes lettres que Perl, par exemple la version courte de @ref{2283,,re.VERBOSE} est @ref{227c,,re.X}). Plusieurs options peuvent être spécifiées en appliquant l'opérateur bit-à-bit `OR' ; par exemple, @code{re.I | re.M} active à la fois les options @ref{2277,,I} et @ref{2279,,M}.

Vous trouvez ci-dessous le tableau des options disponibles, suivies d'explications détaillées.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Option

@tab

Signification

@item

@ref{617,,ASCII}, @ref{2276,,A}

@tab

Transforme plusieurs échappements tels que @code{\w}, @code{\b}, @code{\s} et @code{\d} de manière à ce qu'ils ne correspondent qu'à des caractères ASCII ayant la propriété demandée.

@item

@ref{2273,,DOTALL}, @ref{227a,,S}

@tab

Fait en sorte que @code{.} corresponde à n'importe quel caractère, caractère de retour à la ligne inclus.

@item

@ref{16b0,,IGNORECASE}, @ref{2277,,I}

@tab

Recherche une correspondance sans tenir compte de la casse.

@item

@ref{b5a,,LOCALE}, @ref{2278,,L}

@tab

Recherche une correspondance en tenant compte de la configuration de la région.

@item

@ref{2274,,MULTILINE}, @ref{2279,,M}

@tab

Correspondance multi-lignes, affecte @code{^} et @code{$}.

@item

@ref{2283,,VERBOSE}, @ref{227c,,X} (pour `extended', c.-à-d. étendu en anglais)

@tab

Active les RE verbeuses, qui peuvent être organisées de manière plus propre et compréhensible.

@end multitable



@deffn {Données} re.I

@deffnx {Données} re.IGNORECASE

Perform case-insensitive matching; character class and literal strings will
match letters by ignoring case.  For example, @code{[A-Z]} will match lowercase
letters, too. Full Unicode matching also works unless the @ref{617,,ASCII}
flag is used to disable non-ASCII matches.  When the Unicode patterns
@code{[a-z]} or @code{[A-Z]} are used in combination with the @ref{16b0,,IGNORECASE}
flag, they will match the 52 ASCII letters and 4 additional non-ASCII
letters: 'İ' (U+0130, Latin capital letter I with dot above), 'ı' (U+0131,
Latin small letter dotless i), 'ſ' (U+017F, Latin small letter long s) and
'K' (U+212A, Kelvin sign).  @code{Spam} will match @code{'Spam'}, @code{'spam'},
@code{'spAM'}, or @code{'ſpam'} (the latter is matched only in Unicode mode).
This lowercasing doesn't take the current locale into account;
it will if you also set the @ref{b5a,,LOCALE} flag.
@end deffn


@deffn {Données} re.L

@deffnx {Données} re.LOCALE

Rend @code{\w}, @code{\W}, @code{\b}, @code{\B} et les correspondances non sensibles à la casse dépendants de la configuration de la région courante au lieu de la base de données Unicode.

Les `locales' sont une caractéristique de la bibliothèque C destinées à favoriser une programmation qui tient compte des différences linguistiques (NdT : nous utilisons `configuration de région' dans cette page pour désigner ce concept de la bibliothèque C). Par exemple, si vous traitez du texte français, vous souhaitez pouvoir écrire @code{\w+} pour faire correspondre les mots, mais @code{\w} ne correspond qu'à la classe de caractères @code{[A-Za-za-z]} en octets ; cette classe ne correspond pas avec les octets codant @code{é} ou @code{ç}. Si votre système est configuré correctement et que la configuration de région est définie sur 'français', certaines fonctions C diront à votre programme que l'octet codant @code{é} doit être considéré comme une lettre. Définir l'option @ref{b5a,,LOCALE} lors de la compilation d'une expression régulière fait que l'objet compilé résultant utilise ces fonctions C pour @code{\w} ; c'est plus lent mais cela permet à @code{\w+} de correspondre avec les mots français tel qu'attendu. L'utilisation de cette option est déconseillée en Python 3 car le mécanisme de locale est très peu fiable, il ne gère qu'une seule « culture » à la fois et il ne fonctionne qu'avec des locales 8 bits. La correspondance Unicode est déjà activée par défaut dans Python 3 pour les motifs Unicode (type `str') et elle est capable de gérer différentes configurations de régions.
@end deffn


@deffn {Données} re.M

@deffnx {Données} re.MULTILINE

Nota : @code{^} et @code{$} n'ont pas encore été expliqués ; ils sont introduits dans la section @ref{4e92,,Plus de métacaractères}.

Normalement, @code{^} correspond uniquement au début de la chaîne, et @code{$} correspond uniquement à la fin de la chaîne et immédiatement avant la nouvelle ligne (s'il y en a une) à la fin de la chaîne. Lorsque cette option est spécifiée, @code{^} correspond au début de la chaîne de caractères et au début de chaque ligne de la chaîne de caractères, immédiatement après le début de la nouvelle ligne. De même, le métacaractère @code{$} correspond à la fin de la chaîne de caractères ou à la fin de chaque ligne (précédant immédiatement chaque nouvelle ligne).
@end deffn


@deffn {Données} re.S

@deffnx {Données} re.DOTALL

Fait que le caractère spécial @code{'.'} corresponde avec n'importe quel caractère, y compris le retour à la ligne ; sans cette option, @code{'.'} correspond avec tout, `sauf' le retour à la ligne.
@end deffn


@deffn {Données} re.A

@deffnx {Données} re.ASCII

Fait que @code{\w}, @code{\W}, @code{\b}, @code{\B}, @code{\s} et @code{\S} ne correspondent qu'avec des caractères ASCII au lieu de l'ensemble des caractères Unicode. Cette option n'a de sens que pour des motifs Unicode, elle est ignorée pour les motifs `bytes'.
@end deffn


@deffn {Données} re.X

@deffnx {Données} re.VERBOSE

Cette option vous permet d'écrire des expressions régulières plus lisibles en vous permettant plus de flexibilité pour le formatage. Lorsque cette option est activée, les « blancs » dans la chaîne RE sont ignorés, sauf lorsque le « blancs » se trouve dans une classe de caractères ou est précédé d'une barre oblique inverse ; ceci vous permet d'organiser et d'indenter vos RE plus clairement. Cette option vous permet également de placer des commentaires dans une RE, ils seront ignorés par le moteur ; les commentaires commencent par un @code{'#'} qui n'est ni dans une classe de caractères, ni précédé d'une barre oblique inverse.

Par exemple, voici une RE qui utilise @ref{2283,,re.VERBOSE} ; vous pouvez constater qu'elle est beaucoup plus facile à lire

@example
charref = re.compile(r"""
 &[#]                # Start of a numeric entity reference
 (
     0[0-7]+         # Octal form
   | [0-9]+          # Decimal form
   | x[0-9a-fA-F]+   # Hexadecimal form
 )
 ;                   # Trailing semicolon
""", re.VERBOSE)
@end example

Sans l'option verbeuse, cette RE ressemble à ceci :

@example
charref = re.compile("&#(0[0-7]+"
                     "|[0-9]+"
                     "|x[0-9a-fA-F]+);")
@end example

Dans l'exemple ci-dessus, Python concatène automatiquement les littéraux chaînes de caractères qui ont été utilisés pour séparer la RE en petits morceaux, mais la RE reste plus difficile à comprendre que sa version utilisant @ref{2283,,re.VERBOSE}.
@end deffn

@node Des motifs plus puissants,Modification de chaînes,Utilisation des expressions régulières,Guide des expressions régulières
@anchor{howto/regex more-pattern-power}@anchor{4e93}
@subsection Des motifs plus puissants


Jusqu'à présent nous avons seulement couvert une partie des fonctionnalités des expressions régulières. Dans cette section, nous couvrirons quelques nouveaux métacaractères et l'utilisation des groupes pour récupérer des portions de textes correspondantes.

@menu
* Plus de métacaractères:: 
* Regroupement:: 
* Groupes non de capture et groupes nommés:: 
* Assertions prédictives:: 

@end menu

@node Plus de métacaractères,Regroupement,,Des motifs plus puissants
@anchor{howto/regex id2}@anchor{4e94}@anchor{howto/regex more-metacharacters}@anchor{4e92}
@subsubsection Plus de métacaractères


Nous n'avons pas encore couvert tous les métacaractères. Cette section traite de la plupart de ceux que nous n'avons pas abordés.

Certains métacaractères restants sont des `assertions de largeur zéro' (`zero-width assertions' en anglais). Ils ne font pas avancer le moteur dans la chaîne de caractères ; ils ne consomment aucun caractère et ils réussissent ou échouent tout simplement. Par exemple, @code{\b} est une assertion selon laquelle la position actuelle est située à la limite d'un mot ; la position n'est pas modifiée par le " b ". Cela signifie que les assertions de largeur zéro ne doivent pas être répétées car, si elles correspondent à un endroit donné, elles correspondent automatiquement un nombre infini de fois.


@table @asis

@item @code{|}

Union ensembliste ou opérateur « ou ». Si `A' et `B' sont des expressions régulières, @code{A|B} correspond à toute chaîne qui correspond à A ou à B. La priorité de @code{|} est très faible afin de pouvoir effectuer simplement des unions de chaînes de plusieurs caractères. @code{Crow|Servo} correspond avec @code{'Crow'} ou @code{'Servo'}, mais pas avec @code{'Cro'}, un @code{'w'} ou un @code{'S'}, ou encore @code{'ervo'}.

Pour correspondre avec un @code{'|'} littéral, utilisez @code{\|} ou placez-le dans une classe de caractères, comme ceci @code{[|]}.

@item @code{^}

Correspond à un début de ligne. À moins que l'option @ref{2274,,MULTILINE} ne soit activée, cela ne fait correspondre que le début de la chaîne. Dans le mode @ref{2274,,MULTILINE}, cela fait aussi correspondre immédiatement après chaque nouvelle ligne à l'intérieur de la chaîne.

Par exemple, si vous voulez trouver le mot @code{From} uniquement quand il est en début de ligne, la RE à utiliser est @code{^From}.

@example
>>> print(re.search('^From', 'From Here to Eternity'))  
<re.Match object; span=(0, 4), match='From'>
>>> print(re.search('^From', 'Reciting From Memory'))
None
@end example

Pour trouver un @code{'^'} littéral, utilisez @code{\^}.

@item @code{$}

Correspond à une fin de ligne, ce qui veut dire soit la fin de la chaîne, soit tout emplacement qui est suivi du caractère de nouvelle ligne.

@example
>>> print(re.search('@}$', '@{block@}'))  
<re.Match object; span=(6, 7), match='@}'>
>>> print(re.search('@}$', '@{block@} '))
None
>>> print(re.search('@}$', '@{block@}\n'))  
<re.Match object; span=(6, 7), match='@}'>
@end example

Pour trouver un @code{'$'} littéral, utilisez @code{\$} ou placez-le à l'intérieur d'une classe de caractères, comme ceci @code{[$]}.

@item @code{\A}

Correspond au début de la chaîne de caractères, uniquement. Si l'option @ref{2274,,MULTILINE} n'est pas activée, @code{\A} et @code{^} sont équivalents. Dans le mode @ref{2274,,MULTILINE}, ils sont différents : @code{\A} ne correspond toujours qu'au début de la chaîne alors que @code{^} correspond aussi aux emplacements situés immédiatement après une nouvelle ligne à l'intérieur de la chaîne.

@item @code{\Z}

Correspond uniquement à la fin d'une chaîne de caractères.

@item @code{\b}

Limite de mot. C'est une assertion de largeur zéro qui correspond uniquement aux positions de début et de fin de mot. Un mot est défini comme une séquence de caractères alphanumériques ; ainsi, la fin d'un mot est indiquée par un « blanc » ou un caractère non-alphanumérique.

L'exemple suivant fait correspondre @code{class} seulement si c'est un mot complet ; il n'y a pas de correspondance quand il est à l'intérieur d'un autre mot.

@example
>>> p = re.compile(r'\bclass\b')
>>> print(p.search('no class at all'))
<re.Match object; span=(3, 8), match='class'>
>>> print(p.search('the declassified algorithm'))
None
>>> print(p.search('one subclass is'))
None
@end example

Quand vous utilisez cette séquence spéciale, gardez deux choses à l'esprit. Tout d'abord, c'est la pire collision entre les littéraux des chaînes Python et les séquences d'expressions régulières.  Dans les littéraux de chaîne de caractères Python, @code{\b} est le caractère de retour-arrière (`backspace' en anglais), dont la valeur ASCII est 8.  Si vous n'utilisez pas les chaînes de caractères brutes, alors Python convertit le @code{\b} en retour-arrière, et votre RE ne correspond pas à ce que vous attendez. L'exemple suivant ressemble à notre RE précédente, mais nous avons omis le @code{'r'} devant la chaîne RE.

@example
>>> p = re.compile('\bclass\b')
>>> print(p.search('no class at all'))
None
>>> print(p.search('\b' + 'class' + '\b'))
<re.Match object; span=(0, 7), match='\x08class\x08'>
@end example

Ensuite, dans une classe de caractères, où cette assertion n'a pas lieu d'être, @code{\b} représente le caractère retour-arrière, afin d'être compatible avec les littéraux de chaînes de caractères.

@item @code{\B}

Encore une assertion de largeur zéro, qui est l'opposée de @code{\b}, c'est-à-dire qu'elle fait correspondre uniquement les emplacements qui ne sont pas à la limite d'un mot.
@end table

@node Regroupement,Groupes non de capture et groupes nommés,Plus de métacaractères,Des motifs plus puissants
@anchor{howto/regex grouping}@anchor{4e95}
@subsubsection Regroupement


Souvent, vous avez besoin d'obtenir plus d'informations que le simple fait que la RE corresponde ou non. Ainsi, les expressions régulières sont souvent utilisées pour analyser des chaînes de caractères en écrivant une RE qui divise une chaîne en plusieurs sous-groupes, correspondant chacun à une information particulière. Par exemple, une ligne d'en-tête RFC-822 peut se diviser en un nom d'en-tête et une valeur associée, séparés par un @code{':'}, comme ceci :

@example
From: author@@example.com
User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
MIME-Version: 1.0
To: editor@@example.com
@end example

Vous pouvez alors écrire une expression régulière qui fait correspondre une ligne d'en-tête entière et qui comporte un groupe correspondant au nom de l'en-tête, et un autre groupe correspondant à la valeur de l'en-tête.

Les groupes sont délimités par les métacaractères marqueurs @code{'('} et @code{')'}. @code{'('} et @code{')'} ont à peu près le même sens que dans les expressions mathématiques ; ils forment un groupe à partir des expressions qu'ils encadrent ; vous pouvez répéter le contenu d'un groupe à l'aide d'un quantificateur, comme @code{*}, @code{+}, @code{?} ou @code{@{m,n@}}. Par exemple, @code{(ab)*} correspond à zéro, une ou plusieurs fois @code{ab}.

@example
>>> p = re.compile('(ab)*')
>>> print(p.match('ababababab').span())
(0, 10)
@end example

Les groupes délimités par @code{'('} et @code{')'} capturent également les indices de début et de fin du texte avec lequel ils correspondent ; ces indices peuvent être récupérés en passant un argument à @ref{229b,,group()}, @ref{229f,,start()}, @ref{22a0,,end()} ou @ref{22a1,,span()}. Les groupes sont numérotés à partir de 0, le groupe 0 étant toujours présent ; c'est l'ensemble de la RE, donc les méthodes de l'@ref{f72,,objet correspondance} ont le groupe 0 comme argument par défaut. Plus loin, nous voyons comment exprimer les groupes qui ne capturent pas l'étendue du texte avec lequel ils correspondent.

@example
>>> p = re.compile('(a)b')
>>> m = p.match('ab')
>>> m.group()
'ab'
>>> m.group(0)
'ab'
@end example

Les sous-groupes sont numérotés de la gauche vers la droite, à partir de 1. Les groupes peuvent être imbriqués ; pour déterminer le numéro, il vous suffit de compter le nombre de parenthèses ouvrantes de la gauche vers la droite.

@example
>>> p = re.compile('(a(b)c)d')
>>> m = p.match('abcd')
>>> m.group(0)
'abcd'
>>> m.group(1)
'abc'
>>> m.group(2)
'b'
@end example

Vous pouvez passer plusieurs numéros de groupes à @ref{229b,,group()} en même temps, elle vous renvoie alors un `n'-uplet contenant les valeurs correspondantes pour ces groupes.

@example
>>> m.group(2,1,2)
('b', 'abc', 'b')
@end example

La méthode  @ref{229d,,groups()} renvoie un `n'-uplet contenant les chaînes pour tous les sous-groupes, en commençant par le numéro 1 jusqu'au dernier.

@example
>>> m.groups()
('abc', 'b')
@end example

Les renvois dans un motif vous permettent de spécifier que le contenu d'un groupe précédent doit aussi être trouvé à l'emplacement actuel dans la chaîne. Par exemple, @code{\1} réussit si le contenu du premier groupe se trouve aussi à la position courante, sinon il échoue. Rappelez-vous que les littéraux de chaînes Python utilisent aussi la barre oblique inverse suivie d'un nombre pour insérer des caractères arbitraires dans une chaîne ; soyez sûr d'utiliser une chaîne brute quand vous faites des renvois dans une RE.

Par exemple, la RE suivante détecte les mots doublés dans une chaîne.

@example
>>> p = re.compile(r'\b(\w+)\s+\1\b')
>>> p.search('Paris in the the spring').group()
'the the'
@end example

Les renvois tels que celui-ci ne sont pas très utiles pour effectuer une simple recherche dans une chaîne — il n'y a que peu de formats de textes qui répètent des données ainsi — mais vous verrez bientôt qu'ils sont `très' utiles pour effectuer des substitutions dans les chaînes.

@node Groupes non de capture et groupes nommés,Assertions prédictives,Regroupement,Des motifs plus puissants
@anchor{howto/regex non-capturing-and-named-groups}@anchor{4e96}
@subsubsection Groupes non de capture et groupes nommés


Les RE élaborées peuvent utiliser de nombreux groupes, à la fois pour capturer des sous-chaînes intéressantes ainsi que pour regrouper et structurer la RE elle-même. Dans les RE complexes, il devient difficile de garder la trace des numéros de groupes. Deux caractéristiques aident à résoudre ce problème, toutes deux utilisant la même syntaxe d'extension des expressions régulières. Nous allons donc commencer en examinant cette syntaxe.

Les puissantes extensions des expressions régulières de Perl 5 sont réputées. Pour les mettre en œuvre, les développeurs Perl ne pouvaient pas utiliser de nouveaux métacaractères simples ou de nouvelles séquences commençant par @code{\} sans que les RE Perl ne deviennent trop différentes des RE standards au point de créer de la confusion. S'ils avaient choisi @code{&} comme nouveau métacaractère, par exemple, les expressions déjà écrites auraient considéré que @code{&} était un caractère standard et ne l'aurait pas échappé en écrivant @code{\&} ou @code{[&]}.

La solution adoptée par les développeurs Perl a été d'utiliser @code{(?...)} comme syntaxe d'extension. Placer @code{?} immédiatement après une parenthèse était une erreur de syntaxe, parce que le @code{?} n'a alors rien à répéter. Ainsi, cela n'a pas introduit de problème de compatibilité. Les caractères qui suivent immédiatement le @code{?} indiquent quelle extension est utilisée, donc @code{(?=truc)} est une chose (une assertion positive anticipée) et @code{(?:truc)} est une autre chose (la sous-expression @code{truc} que l'on groupe).

Python gère plusieurs des extensions Perl et rajoute une extension à la syntaxe des extensions Perl. Si le premier caractère après le point d'interrogation est @code{P}, cela signifie que c'est une extension spécifique à Python.

Après avoir vu la syntaxe générale d'extension des RE, nous pouvons revenir aux fonctionnalités qui simplifient le travail avec les groupes dans des RE complexes.

Parfois, vous souhaitez utiliser un groupe pour marquer une partie de l'expression régulière mais le contenu de ce groupe ne vous intéresse pas vraiment. Vous pouvez l'indiquer explicitement en utilisant la syntaxe de groupe, mais sans indiquer que vous voulez en capturer le contenu : @code{(?:...)}, où vous remplacez les @code{...} par n'importe quelle expression régulière.

@example
>>> m = re.match("([abc])+", "abc")
>>> m.groups()
('c',)
>>> m = re.match("(?:[abc])+", "abc")
>>> m.groups()
()
@end example

À part le fait que vous n'avez pas accès au contenu du groupe, un groupe se comporte exactement de la même manière qu'un groupe de capture ; vous pouvez placer n'importe quoi dedans, spécifier une répétition avec un métacaractère tel que @code{*} et l'imbriquer dans un autre groupe (de capture ou pas). @code{(?:...)} est particulièrement utile quand vous modifiez des motifs existants, puisque vous pouvez ajouter de nouveaux groupes sans changer la façon dont les autres groupes sont numérotés. Nous devons mentionner ici qu'il n'y a aucune différence de performance dans la recherche de groupes, de capture ou non ; les deux formes travaillent à la même vitesse.

Une fonctionnalité plus importante est le nommage des groupes : au lieu d'y faire référence par des nombres, vous pouvez référencer des groupes par leur nom.

La syntaxe pour nommer les groupes est l'une des extensions spécifiques à Python : @code{(?P<nom>....)}. `nom' est, vous vous en doutez, le nom du groupe. Les groupes nommés se comportent exactement comme des groupes de capture, sauf qu'ils associent en plus un nom à un groupe. Les méthodes des @ref{f72,,objets correspondances} qui gèrent les groupes de capture acceptent soit des entiers qui font référence aux numéros des groupes, soit des chaînes de caractères qui désignent les noms des groupes désirés. Les groupes nommés se voient toujours attribuer un numéro, vous pouvez ainsi récupérer les informations d'un groupe de deux façons :

@example
>>> p = re.compile(r'(?P<word>\b\w+\b)')
>>> m = p.search( '(((( Lots of punctuation )))' )
>>> m.group('word')
'Lots'
>>> m.group(1)
'Lots'
@end example

De plus, vous pouvez récupérer les groupes nommés comme dictionnaire avec @ref{229e,,groupdict()} :

@example
>>> m = re.match(r'(?P<first>\w+) (?P<last>\w+)', 'Jane Doe')
>>> m.groupdict()
@{'first': 'Jane', 'last': 'Doe'@}
@end example

Les groupes nommés sont pratiques car il est plus facile de se rappeler un nom qu'un numéro. Voici un exemple de RE tirée du module @ref{73,,imaplib} :

@example
InternalDate = re.compile(r'INTERNALDATE "'
        r'(?P<day>[ 123][0-9])-(?P<mon>[A-Z][a-z][a-z])-'
        r'(?P<year>[0-9][0-9][0-9][0-9])'
        r' (?P<hour>[0-9][0-9]):(?P<min>[0-9][0-9]):(?P<sec>[0-9][0-9])'
        r' (?P<zonen>[-+])(?P<zoneh>[0-9][0-9])(?P<zonem>[0-9][0-9])'
        r'"')
@end example

Il est évidemment plus facile de récupérer @code{m.group('zonem')} que de se rappeler de récupérer le groupe 9.

La syntaxe des renvois dans une expression telle que @code{(....)\1} fait référence au numéro du groupe. Il y a naturellement une variante qui utilise le nom du groupe au lieu du numéro. C'est une autre extension Python : @code{(?P=nom)} indique que le contenu du groupe appelé `nom' doit correspondre à nouveau avec l'emplacement courant. L'expression régulière pour trouver des mots doublés, @code{\b(\w+)\s+\1\b} peut ainsi être ré-écrite en @code{\b(?P<mot>\w+)\s+(?P=mot)\b} :

@example
>>> p = re.compile(r'\b(?P<word>\w+)\s+(?P=word)\b')
>>> p.search('Paris in the the spring').group()
'the the'
@end example

@node Assertions prédictives,,Groupes non de capture et groupes nommés,Des motifs plus puissants
@anchor{howto/regex lookahead-assertions}@anchor{4e97}
@subsubsection Assertions prédictives


Une autre assertion de largeur zéro est l'assertion prédictive. Une assertion prédictive peut s'exprimer sous deux formes, la positive et la négative, comme ceci :


@table @asis

@item @code{(?=...)}

Assertion prédictive positive. Elle réussit si l'expression régulière contenue, représentée ici par  @code{...}, correspond effectivement à l'emplacement courant ; dans le cas contraire, elle échoue. Mais, une fois que l'expression contenue a été essayée, le moteur de correspondance n'avance pas ; le reste du motif est testé à l'endroit même où l'assertion a commencé.

@item @code{(?!...)}

Assertion prédictive négative. C'est l'opposée de l'assertion positive ; elle réussit si l'expression régulière contenue `ne' correspond `pas' à l'emplacement courant dans la chaîne.
@end table

Pour rendre ceci plus concret, regardons le cas où une prédiction est utile. Considérons un motif simple qui doit faire correspondre un nom de fichier et le diviser en un nom de base et une extension, séparés par un @code{.}. Par exemple, dans @code{news.rc}, @code{news} est le nom de base et @code{rc} est l'extension du nom de fichier.

Le motif de correspondance est plutôt simple :

@code{.*[.].*$}

Notez que le @code{.} doit être traité spécialement car c'est un métacaractère, nous le plaçons donc à l'intérieur d'une classe de caractères pour ne faire correspondre que ce caractère spécifique. Notez également le @code{$} en fin ; nous l'avons ajouté pour nous assurer que tout le reste de la chaîne est bien inclus dans l'extension. Cette expression régulière fait correspondre @code{truc.bar}, @code{autoexec.bat}, @code{sendmail.cf} et @code{printers.conf}.

Maintenant, compliquons un peu le problème ; si nous voulons faire correspondre les noms de fichiers dont l'extension n'est pas @code{bat} ? voici quelques tentatives incorrectes :

@code{.*[.][^b].*$} Le premier essai ci-dessus tente d'exclure @code{bat} en spécifiant que le premier caractère de l'extension ne doit pas être @code{b}. Cela ne fonctionne pas, car le motif n'accepte pas @code{truc.bar}.

@code{.*[.]([^b]..|.[^a].|..[^t])$}

L'expression devient plus confuse si nous essayons de réparer la première solution en spécifiant l'un des cas suivants : le premier caractère de l'extension n'est pas @code{b} ; le deuxième caractère n'est pas @code{a} ; ou le troisième caractère n'est pas @code{t}. Ce motif accepte @code{truc.bar} et rejette @code{autoexec.bat}, mais elle nécessite une extension de trois lettres et n'accepte pas un nom de fichier avec une extension de deux lettres comme @code{sendmail.cf}. Compliquons encore une fois le motif pour essayer de le réparer.

@code{.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$}

Pour cette troisième tentative, les deuxième et troisième lettres sont devenues facultatives afin de permettre la correspondance avec des extensions plus courtes que trois caractères, comme @code{sendmail.cf}.

Le motif devient vraiment compliqué maintenant, ce qui le rend difficile à lire et à comprendre. Pire, si le problème change et que vous voulez exclure à la fois @code{bat} et @code{exe} en tant qu'extensions, le modèle deviendra encore plus compliqué et confus.

Une assertion prédictive négative supprime toute cette confusion :

@code{.*[.](?!bat$)[^.]*$} Cette assertion prédictive négative signifie : si l'expression @code{bat} ne correspond pas à cet emplacement, essaie le reste du motif ; si @code{bat$} correspond, tout le motif échoue. Le @code{$} est nécessaire pour s'assurer que quelque chose comme @code{sample.batch}, où c'est seulement le début de l'extension qui vaut @code{bat}, est autorisé. Le @code{[^...]*} s'assure que le motif fonctionne lorsqu'il y a plusieurs points dans le nom de fichier.

Exclure une autre extension de nom de fichier est maintenant facile ; il suffit de l'ajouter comme alternative à l'intérieur de l'assertion. Le motif suivant exclut les noms de fichiers qui se terminent par @code{bat} ou @code{exe} :

@code{.*[.](?!bat$|exe$)[^.]*$}

@node Modification de chaînes,Problèmes classiques,Des motifs plus puissants,Guide des expressions régulières
@anchor{howto/regex modifying-strings}@anchor{4e98}
@subsection Modification de chaînes


Jusqu'à présent, nous avons simplement effectué des recherches dans une chaîne statique. Les expressions régulières sont aussi couramment utilisées pour modifier les chaînes de caractères de diverses manières, en utilisant les méthodes suivantes des motifs :


@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Méthode/Attribut

@tab

Objectif

@item

@code{split()}

@tab

Découpe la chaîne de caractère en liste, la découpant partout où la RE correspond

@item

@code{sub()}

@tab

Recherche toutes les sous-chaînes de caractères où la RE correspond et les substitue par une chaîne de caractères différente

@item

@code{subn()}

@tab

Fait la même chose que @code{sub()},  mais renvoie la nouvelle chaîne et le nombre de remplacements effectués

@end multitable


@menu
* Découpage de chaînes:: 
* Recherche et substitution: Recherche et substitution<2>. 

@end menu

@node Découpage de chaînes,Recherche et substitution<2>,,Modification de chaînes
@anchor{howto/regex splitting-strings}@anchor{4e99}
@subsubsection Découpage de chaînes


La méthode @code{split()} d'un motif divise une chaîne de caractères à chaque fois que la RE correspond, retournant la liste des morceaux. C'est similaire à la méthode @ref{e93,,split()} mais est beaucoup plus générale par les délimiteurs que vous pouvez spécifier ; la méthode  @code{split()} du type `string' ne gère que les découpages en suivant les « blancs » ou suivant une chaîne définie. Comme vous pouvez vous y attendre, il y a aussi une fonction @ref{29f,,re.split()} de niveau module.


@deffn {Méthode} .split (string[, maxsplit=0])

Découpe `string' en suivant les correspondances de l'expression régulière. Si des parenthèses de capture sont utilisées dans la RE, leur contenu est également renvoyé dans la liste résultante. Si `maxsplit' n'est pas nul, au plus `maxsplit' découpages sont effectués.
@end deffn

Vous pouvez limiter le nombre de découpages effectués en passant une valeur pour `maxsplit'. Quand `maxsplit' n'est pas nul, au plus `maxsplit' découpages sont effectués et le reste de la chaîne est renvoyé comme dernier élément de la liste. Dans l'exemple suivant, le délimiteur est toute séquence de caractères non alphanumériques.

@example
>>> p = re.compile(r'\W+')
>>> p.split('This is a test, short and sweet, of split().')
['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '@w{'}]
>>> p.split('This is a test, short and sweet, of split().', 3)
['This', 'is', 'a', 'test, short and sweet, of split().']
@end example

Parfois, vous voulez récupérer le texte entre les délimiteurs mais aussi quel était le délimiteur. Si des parenthèses de capture sont utilisées dans la RE, leurs valeurs sont également renvoyées dans la liste. Comparons les appels suivants :

@example
>>> p = re.compile(r'\W+')
>>> p2 = re.compile(r'(\W+)')
>>> p.split('This... is a test.')
['This', 'is', 'a', 'test', '@w{'}]
>>> p2.split('This... is a test.')
['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '@w{'}]
@end example

La fonction de niveau module @ref{29f,,re.split()} ajoute la RE à utiliser comme premier argument, mais est par ailleurs identique.

@example
>>> re.split(r'[\W]+', 'Words, words, words.')
['Words', 'words', 'words', '@w{'}]
>>> re.split(r'([\W]+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '@w{'}]
>>> re.split(r'[\W]+', 'Words, words, words.', 1)
['Words', 'words, words.']
@end example

@node Recherche et substitution<2>,,Découpage de chaînes,Modification de chaînes
@anchor{howto/regex search-and-replace}@anchor{4e9a}
@subsubsection Recherche et substitution


Une autre tâche classique est de trouver toutes les correspondances d'un motif et de les remplacer par une autre chaîne. La méthode @ref{2293,,sub()} prend une valeur de substitution, qui peut être une chaîne de caractères ou une fonction, et la chaîne à traiter.


@deffn {Méthode} .sub (replacement, string[, count=0])

Renvoie la chaîne obtenue en remplaçant les occurrences sans chevauchement les plus à gauche de la RE dans `string' par la substitution `replacement'. Si le motif n'est pas trouvé, `string' est renvoyée inchangée.

L'argument optionnel `count' est le nombre maximum d'occurrences du motif à remplacer ; `count' doit être un entier positif ou nul. La valeur par défaut de 0 signifie qu'il faut remplacer toutes les occurrences.
@end deffn

Voici un exemple simple utilisant la méthode @ref{2293,,sub()}. Nous remplaçons les noms des couleurs par le mot @code{colour} :

@example
>>> p = re.compile('(blue|white|red)')
>>> p.sub('colour', 'blue socks and red shoes')
'colour socks and colour shoes'
>>> p.sub('colour', 'blue socks and red shoes', count=1)
'colour socks and red shoes'
@end example

La méthode @code{subn()} fait la même chose mais renvoie un couple contenant la nouvelle valeur de la chaîne de caractères et le nombre de remplacements effectués :

@example
>>> p = re.compile('(blue|white|red)')
>>> p.subn('colour', 'blue socks and red shoes')
('colour socks and colour shoes', 2)
>>> p.subn('colour', 'no colours at all')
('no colours at all', 0)
@end example

Les correspondances vides ne sont remplacées que lorsqu'elles ne sont pas adjacentes à une correspondance vide précédente.

@example
>>> p = re.compile('x*')
>>> p.sub('-', 'abxd')
'-a-b--d-'
@end example

Si `replacement' est une chaîne de caractères, toute barre oblique inverse d'échappement est traitée.  C'est-à-dire que @code{\n} est converti en caractère de nouvelle ligne, @code{\r} est converti en retour chariot, et ainsi de suite. Les échappements inconnus comme @code{\&} sont laissés tels quels. Les renvois, tels que @code{\6}, sont remplacés par la sous-chaîne correspondante au groupe dans le RE. Ceci vous permet d'incorporer des parties du texte original dans la chaîne de remplacement résultante.

Cet exemple fait correspondre le mot @code{section} suivi par une chaîne encadrée par  @code{@{} et @code{@}}, et modifie @code{section} en @code{subsection} :

@example
>>> p = re.compile('section@{ ( [^@}]* ) @}', re.VERBOSE)
>>> p.sub(r'subsection@{\1@}','section@{First@} section@{second@}')
'subsection@{First@} subsection@{second@}'
@end example

Il existe aussi une syntaxe pour faire référence aux groupes nommés définis par la syntaxe @code{(?P<nom>....)}. @code{\g<nom>} utilise la sous-chaîne correspondante au groupe nommé @code{nom} et @code{\g<numéro>} utilise le numéro de groupe correspondant. @code{\g<2>} est donc l'équivalent de @code{\2}, mais n'est pas ambigu dans une chaîne de substitution telle que @code{\g<2>0} (@code{\20} serait interprété comme une référence au groupe 20 et non comme une référence au groupe 2 suivie du caractère littéral @code{'0'}). Les substitutions suivantes sont toutes équivalentes mais utilisent les trois variantes de la chaîne de remplacement.

@example
>>> p = re.compile('section@{ (?P<name> [^@}]* ) @}', re.VERBOSE)
>>> p.sub(r'subsection@{\1@}','section@{First@}')
'subsection@{First@}'
>>> p.sub(r'subsection@{\g<1>@}','section@{First@}')
'subsection@{First@}'
>>> p.sub(r'subsection@{\g<name>@}','section@{First@}')
'subsection@{First@}'
@end example

`replacement' peut aussi être une fonction, ce qui vous donne encore plus de contrôle. Si `replacement' est une fonction, la fonction est appelée pour chaque occurrence non chevauchante de `pattern'. À chaque appel, un argument @ref{f72,,objet correspondance} est passé à la fonction, qui peut utiliser cette information pour calculer la chaîne de remplacement désirée et la renvoyer.

Dans l'exemple suivant, la fonction de substitution convertit un nombre décimal en hexadécimal :

@example
>>> def hexrepl(match):
...     "Return the hex string for a decimal number"
...     value = int(match.group())
...     return hex(value)
...
>>> p = re.compile(r'\d+')
>>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.')
'Call 0xffd2 for printing, 0xc000 for user code.'
@end example

Quand vous utilisez la fonction de niveau module @ref{2a0,,re.sub()}, le motif est passé comme premier argument. Vous pouvez fournir le motif sous forme d'objet ou de chaîne de caractères ; si vous avez besoin de spécifier des options pour l'expression régulière, vous devez soit utiliser un objet motif comme premier paramètre, soit utiliser des modificateurs intégrés dans la chaîne de caractères, par exemple @code{sub("(?i)b+", "x", "bbbb BBBBB")} renvoie @code{'x x'}.

@node Problèmes classiques,Vos commentaires,Modification de chaînes,Guide des expressions régulières
@anchor{howto/regex common-problems}@anchor{4e9b}
@subsection Problèmes classiques


Les expressions régulières constituent un outil puissant pour certaines applications mais, à certains égards, leur comportement n'est pas intuitif et, parfois, elles ne se comportent pas comme vous pouvez vous y attendre.  Cette section met en évidence certains des pièges les plus courants.

@menu
* Utilisez les méthodes du type string:: 
* match() contre search(): match contre search. 
* Glouton contre non-glouton:: 
* Utilisez re.VERBOSE: Utilisez re VERBOSE. 

@end menu

@node Utilisez les méthodes du type string,match contre search,,Problèmes classiques
@anchor{howto/regex use-string-methods}@anchor{4e9c}
@subsubsection Utilisez les méthodes du type `string'


Parfois, il ne faut pas utiliser le module @ref{b8,,re}. Si vous faites correspondre une chaîne fixe, ou une classe à un seul caractère, et que vous n'utilisez pas les fonctionnalités de @ref{b8,,re} telles que l'option @ref{16b0,,IGNORECASE}, alors la puissance des expressions régulières n'est pas nécessaire. Les chaînes de caractères ont plusieurs méthodes pour opérer sur des chaînes fixes et elles sont généralement beaucoup plus rapides, parce que l'implémentation est une seule petite boucle C qui a été optimisée, au lieu du gros moteur d'expressions régulières plus généraliste.

Nous pouvons prendre l'exemple du remplacement d'une seule chaîne fixe par une autre ; vous souhaitez remplacer @code{mot} par @code{acte}. @ref{2a0,,re.sub()} semble être faite pour cela, mais regardons la méthode @ref{198,,replace()}. Notons que @code{replace()} remplace aussi @code{mot} à l'intérieur des mots, transformant @code{moteur} en @code{acteeur}, mais la RE naïve @code{mot} aurait aussi fait cela (pour éviter d'effectuer la substitution sur des parties de mots, le motif doit être @code{\bmot\b}, qui exige que @code{mot} soit en limite de mot d'un côté et de l'autre ; c'est au-delà des capacités de la méthode @code{replace()}).

Une autre tâche classique est de supprimer chaque occurrence d'un seul caractère d'une chaîne de caractères ou de le remplacer par un autre caractère unique. Vous pouvez le faire avec quelque chose comme @code{re.sub('\n', ' ', S)}, mais @ref{2151,,translate()} en est capable et est plus rapide que n'importe quelle opération d'expression régulière.

Bref, avant de passer au module @ref{b8,,re}, évaluez d'abord si votre problème peut être résolu avec une méthode de chaîne plus rapide et plus simple.

@node match contre search,Glouton contre non-glouton,Utilisez les méthodes du type string,Problèmes classiques
@anchor{howto/regex match-versus-search}@anchor{4e9d}
@subsubsection `match()' contre `search()'


La fonction @ref{120b,,match()} vérifie seulement si la RE correspond au début de la chaîne de caractères tandis que @ref{120a,,search()} parcourt la chaîne de caractères pour trouver une correspondance. Il est important de garder cette distinction à l'esprit. Rappelez-vous, @code{match()} ne trouve qu'une correspondance qui commence à 0 ; si la correspondance commence plus loin, @code{match()} `ne la trouve pas'.

@example
>>> print(re.match('super', 'superstition').span())
(0, 5)
>>> print(re.match('super', 'insuperable'))
None
@end example

D'un autre côté, @ref{120a,,search()} balaie la chaîne de caractères, rapportant la première correspondance qu'elle trouve.

@example
>>> print(re.search('super', 'superstition').span())
(0, 5)
>>> print(re.search('super', 'insuperable').span())
(2, 7)
@end example

Vous pouvez être tenté d'utiliser @ref{120b,,re.match()} en ajoutant simplement @code{.*} au début de votre RE. Ce n'est pas une bonne idée, utilisez plutôt @ref{120a,,re.search()}. Le compilateur d'expressions régulières analyse les RE pour optimiser le processus de recherche d'une correspondance. Cette analyse permet de déterminer ce que doit être le premier caractère d'une correspondance ; par exemple, un motif commençant par @code{Corbeau} doit faire correspondre un @code{'C'} en tête. L'analyse permet au moteur de parcourir rapidement la chaîne de caractères à la recherche du caractère de départ, n'essayant la correspondance complète que si un @code{'C'} a déjà été trouvé.

Ajouter @code{.*} annihile cette optimisation, nécessitant un balayage jusqu'à la fin de la chaîne de caractères, puis un retour en arrière pour trouver une correspondance pour le reste de la RE. Préférez l'utilisation @ref{120a,,re.search()}.

@node Glouton contre non-glouton,Utilisez re VERBOSE,match contre search,Problèmes classiques
@anchor{howto/regex greedy-versus-non-greedy}@anchor{4e9e}
@subsubsection Glouton contre non-glouton


Si vous répétez un motif dans une expression régulière, comme @code{a*}, l'action résultante est de consommer autant de motifs que possible. C'est un problème lorsque vous essayez de faire correspondre une paire de délimiteurs, comme des chevrons encadrant une balise HTML. Le motif naïf pour faire correspondre une seule balise HTML ne fonctionne pas en raison de la nature gloutonne de @code{.*}.

@example
>>> s = '<html><head><title>Title</title>'
>>> len(s)
32
>>> print(re.match('<.*>', s).span())
(0, 32)
>>> print(re.match('<.*>', s).group())
<html><head><title>Title</title>
@end example

La RE correspond au @code{'<'} de @code{'<html>'} et le @code{.*} consomme le reste de la chaîne. Mais, comme il reste des éléments du motif dans la RE et que le @code{>} ne peut pas correspondre à la fin de la chaîne de caractères, le moteur d'expression régulière doit faire marche arrière caractère par caractère jusqu'à ce qu'il trouve une correspondance pour le @code{>}.  La correspondance finale s'étend du @code{'<'} de @code{'<html>'} au @code{'>'} de @code{'</title>'}, ce qui n'est pas ce que vous voulez.

Dans ce cas, la solution consiste à utiliser des quantificateurs non gloutons tels que @code{*?}, @code{+?}, @code{??} ou @code{@{m,n@}?}, qui effectuent une correspondance aussi `petite' que possible. Dans l'exemple ci-dessus, le @code{'>'} est essayé immédiatement après que le @code{'<'} corresponde et, s'il échoue, le moteur avance caractère par caractère, ré-essayant @code{'>'} à chaque pas. Nous obtenons alors le bon résultat :

@example
>>> print(re.match('<.*?>', s).group())
<html>
@end example

Note : l'analyse du HTML ou du XML avec des expressions régulières est tout sauf une sinécure. Les motifs écrits à la va-vite traiteront les cas communs, mais HTML et XML ont des cas spéciaux qui font planter l'expression régulière évidente ; quand vous aurez écrit une expression régulière qui traite tous les cas possibles, les motifs seront `très' compliqués.  Utilisez un module d'analyse HTML ou XML pour de telles tâches.

@node Utilisez re VERBOSE,,Glouton contre non-glouton,Problèmes classiques
@anchor{howto/regex using-re-verbose}@anchor{4e9f}
@subsubsection Utilisez `re.VERBOSE'


À présent, vous vous êtes rendu compte que les expressions régulières sont une notation très compacte, mais qu'elles ne sont pas très lisibles. Une RE modérément complexe  peut rapidement devenir une longue collection de barres obliques inverses, de parenthèses et de métacaractères, ce qui la rend difficile à lire et à comprendre.

Pour de telles RE, activer l'option @ref{2283,,re.VERBOSE} à la compilation de l'expression régulière peut être utile ; cela vous permet de formater l'expression régulière de manière plus claire.

L'option @code{re.VERBOSE} a plusieurs effets. Les espaces dans l'expression régulière qui `ne sont pas' à l'intérieur d'une classe de caractères sont ignorées. Cela signifie qu'une expression comme @code{chien | chat} est équivalente à @code{chien|chat} qui est moins lisible, mais @code{[a b]} correspond toujours aux caractères @code{'a'}, @code{'b'} ou à une espace. En outre, vous avez la possibilité de mettre des commentaires à l'intérieur d'une RE ; les commentaires s'étendent du caractère @code{#} à la nouvelle ligne suivante. Lorsque vous l'utilisez avec des chaînes à triple guillemets, cela permet aux RE d'être formatées plus proprement :

@example
pat = re.compile(r"""
 \s*                 # Skip leading whitespace
 (?P<header>[^:]+)   # Header name
 \s* :               # Whitespace, and a colon
 (?P<value>.*?)      # The header's value -- *? used to
                     # lose the following trailing whitespace
 \s*$                # Trailing whitespace to end-of-line
""", re.VERBOSE)
@end example

Ceci est beaucoup plus lisible que :

@example
pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")
@end example

@node Vos commentaires,,Problèmes classiques,Guide des expressions régulières
@anchor{howto/regex feedback}@anchor{4ea0}
@subsection Vos commentaires


Les expressions régulières sont un sujet compliqué. Est-ce que ce document vous a aidé à les comprendre ? Des parties ne sont pas claires, ou des problèmes que vous avez rencontrés ne sont pas traités ici ? Si tel est le cas, merci d'envoyer vos suggestions d'améliorations à l'auteur.

Le livre le plus complet sur les expressions régulières est certainement `Mastering Regular Expressions' de Jeffrey Friedl, publié par O'Reilly. Malheureusement, il se concentre sur les déclinaisons Perl et Java des expressions régulières et ne contient aucun contenu pour Python ; il n'est donc pas utile d'en faire référence pour la programmation Python. (La première édition traitait du module Python @code{regex}, maintenant supprimé, ce qui ne vous aidera pas beaucoup.) Pensez à le retirer de votre bibliothèque.

@node Guide pratique programmation avec les sockets,Sorting Techniques,Guide des expressions régulières,Les HOWTOs de Python
@anchor{howto/sockets doc}@anchor{4ea1}@anchor{howto/sockets socket-howto}@anchor{33a2}@anchor{howto/sockets socket-programming-howto}@anchor{4ea2}
@section Guide pratique : programmation avec les `sockets'


@*Auteur: 
Gordon McMillan


@subsubheading Résumé



Les connecteurs (`sockets', en anglais) sont utilisés presque partout, mais ils sont l'une des technologies les plus méconnues. En voici un aperçu très général. Ce n'est pas vraiment un tutoriel — vous aurez encore du travail à faire pour avoir un résultat opérationnel. Il ne couvre pas les détails (et il y en a beaucoup), mais j'espère qu'il vous donnera suffisamment d'informations pour commencer à les utiliser correctement.

@menu
* Connecteurs (sockets): Connecteurs sockets. 
* Création d'un connecteur:: 
* Utilisation d'un connecteur:: 
* Déconnexion:: 
* Connecteurs non bloquants:: 

@end menu

@node Connecteurs sockets,Création d'un connecteur,,Guide pratique programmation avec les sockets
@anchor{howto/sockets sockets}@anchor{4ea3}
@subsection Connecteurs (`sockets')


Je ne parlerai que des connecteurs `INET' (c'est-à-dire IPv4), mais ils représentent au moins 99 % des connecteurs utilisés. Et je ne parlerai que des connecteurs `STREAM' (c.-à-d. `TCP') — à moins que vous ne sachiez vraiment ce que vous faites (auquel cas ce guide n'est pas pour vous), vous obtiendrez un meilleur comportement et de meilleures performances avec un connecteur `STREAM' qu'avec n'importe quel autre. Je vais essayer d'éclaircir le mystère de ce qu'est un connecteur, ainsi que quelques conseils sur la façon de travailler avec des connecteurs bloquants et non bloquants. Mais je commencerai par parler des connecteurs bloquants. Vous devez savoir comment ils fonctionnent avant de vous intéresser aux connecteurs non bloquants.

Une partie de la difficulté à comprendre ces choses est que « connecteur » peut désigner plusieurs choses très légèrement différentes, selon le contexte. Faisons donc d'abord une distinction entre un connecteur « client » — point final d'une conversation — et un connecteur « serveur », qui ressemble davantage à un standardiste. L'application cliente (votre navigateur par exemple) utilise exclusivement des connecteurs « client » ; le serveur web avec lequel elle parle utilise à la fois des connecteurs « serveur » et des connecteurs « client ».

@menu
* Historique:: 

@end menu

@node Historique,,,Connecteurs sockets
@anchor{howto/sockets history}@anchor{4ea4}
@subsubsection Historique


Parmi les différentes formes d’@abbr{IPC,Inter Process Communication}, les connecteurs sont de loin les plus populaires. Sur une plate-forme donnée, il est probable que d'autres formes d'`IPC' soient plus rapides, mais pour la communication entre plates-formes, les connecteurs sont à peu près la seule solution valable.

Ils ont été inventés à Berkeley dans le cadre de la déclinaison `BSD' d'Unix. Ils se sont répandus comme une traînée de poudre avec Internet. Et pour cause : la combinaison des connecteurs avec `INET' rend le dialogue avec n’importe quelle machine dans le monde entier incroyablement facile (du moins par rapport à d'autres systèmes).

@node Création d'un connecteur,Utilisation d'un connecteur,Connecteurs sockets,Guide pratique programmation avec les sockets
@anchor{howto/sockets creating-a-socket}@anchor{4ea5}
@subsection Création d'un connecteur


Grosso modo, lorsque vous avez cliqué sur le lien qui vous a amené à cette page, votre navigateur a fait quelque chose comme ceci :

@example
# create an INET, STREAMing socket
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# now connect to the web server on port 80 - the normal http port
s.connect(("www.python.org", 80))
@end example

Lorsque l’appel à @code{connect} est terminé, le connecteur @code{s} peut être utilisé pour envoyer une requête demandant le texte de la page. Le même connecteur lira la réponse, puis sera mis au rebut. C'est exact, mis au rebut. Les connecteurs clients ne sont normalement utilisés que pour un seul échange (ou un petit ensemble d'échanges séquentiels).

Ce qui se passe dans le serveur web est un peu plus complexe. Tout d'abord, le serveur web crée un « connecteur serveur » :

@example
# create an INET, STREAMing socket
serversocket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# bind the socket to a public host, and a well-known port
serversocket.bind((socket.gethostname(), 80))
# become a server socket
serversocket.listen(5)
@end example

Quelques remarques : nous avons utilisé @code{socket.gethostname()} pour que le connecteur soit visible par le monde extérieur.  Si nous avions utilisé @code{s.bind(('localhost', 80))} ou @code{s.bind(('127.0.0.1', 80))}, nous aurions toujours un connecteur « serveur », mais qui ne serait visible qu'à l'intérieur de la même machine. @code{s.bind(('@w{'}, 80))} précise que le connecteur est accessible par n'importe quelle adresse que la machine possède.

Une deuxième chose à noter : les ports dont le numéro est petit sont généralement réservés aux services « bien connus » (HTTP, SNMP, etc.). Si vous expérimentez, utilisez un nombre suffisamment élevé (4 chiffres).

Enfin, l'argument passé à @code{listen} indique à la bibliothèque de connecteurs que nous voulons mettre en file d'attente jusqu'à 5 requêtes de connexion (le maximum normal) avant de refuser les connexions externes. Si le reste du code est écrit correctement, cela devrait suffire.

Maintenant que nous avons un connecteur « serveur », en écoute sur le port 80, nous pouvons entrer dans la boucle principale du serveur web :

@example
while True:
    # accept connections from outside
    (clientsocket, address) = serversocket.accept()
    # now do something with the clientsocket
    # in this case, we'll pretend this is a threaded server
    ct = client_thread(clientsocket)
    ct.run()
@end example

Il y a en fait trois façons générales de faire fonctionner cette boucle : mobiliser un fil d'exécution pour gérer les @code{clientsocket}s, créer un nouveau processus pour gérer les @code{clientsocket}s, ou restructurer cette application pour utiliser des connecteurs non bloquants, et multiplexer entre notre connecteur « serveur » et n'importe quel @code{clientsocket} actif en utilisant @code{select}. Plus d'informations à ce sujet plus tard. La chose importante à comprendre maintenant est la suivante : c'est `tout' ce que fait un connecteur « serveur ». Il n'envoie aucune donnée. Il ne reçoit aucune donnée. Il ne fait que produire des connecteurs « clients ». Chaque @code{clientsocket} est créé en réponse à un `autre' connecteur « client » qui se connecte à l'hôte et au port auxquels nous sommes liés. Dès que nous avons créé ce @code{clientsocket}, nous retournons à l'écoute pour d'autres connexions. Les deux « clients » sont libres de discuter — ils utilisent un port alloué dynamiquement qui sera recyclé à la fin de la conversation.

@menu
* IPC (Communication Entre Processus): IPC Communication Entre Processus. 

@end menu

@node IPC Communication Entre Processus,,,Création d'un connecteur
@anchor{howto/sockets ipc}@anchor{4ea6}
@subsubsection `IPC' (Communication Entre Processus)


Si vous avez besoin d'une communication rapide entre deux processus sur une même machine, vous devriez regarder comment utiliser les tubes (`pipe', en anglais) ou la mémoire partagée. Si vous décidez d'utiliser les connecteurs `AF_INET', liez le connecteur « serveur » à @code{'localhost'}. Sur la plupart des plates-formes, cela contourne quelques couches réseau et est un peu plus rapide.


@subsubheading Voir aussi


Le @ref{93,,multiprocessing} intègre de l’IPC multiplateformes dans une API de plus haut niveau.


@node Utilisation d'un connecteur,Déconnexion,Création d'un connecteur,Guide pratique programmation avec les sockets
@anchor{howto/sockets using-a-socket}@anchor{4ea7}
@subsection Utilisation d'un connecteur


La première chose à noter, c'est que la prise « client » du navigateur web et la prise « client » du serveur web sont des bêtes identiques. C'est-à-dire qu'il s'agit d'une conversation « pair à pair ». Ou pour le dire autrement, `en tant que concepteur, vous devrez décider quelles sont les règles d'étiquette pour une conversation'. Normalement, la connexion via @code{connect} lance la conversation en envoyant une demande, ou peut-être un signe. Mais c'est une décision de conception — ce n'est pas une règle des connecteurs.

Il y a maintenant deux ensembles de verbes à utiliser pour la communication. Vous pouvez utiliser @code{send} et @code{recv}, ou vous pouvez transformer votre connecteur client en une bête imitant un fichier et utiliser @code{read} et @code{write}. C'est la façon dont Java présente ses connecteurs. Je ne vais pas en parler ici, sauf pour vous avertir que vous devez utiliser @code{flush} sur les connecteurs. Ce sont des « fichiers », mis en mémoire tampon, et une erreur courante est d'« écrire » via @code{write} quelque chose, puis de « lire » via @code{read} pour obtenir une réponse. Sans un @code{flush}, vous pouvez attendre la réponse pour toujours, parce que la requête peut encore être dans votre mémoire tampon de sortie.

Nous arrivons maintenant au principal écueil des connecteurs — @code{send} et @code{recv} fonctionnent sur les mémoires tampons du réseau. Ils ne traitent pas nécessairement tous les octets que vous leur passez (ou que vous attendez d'eux), car leur principal objectif est de gérer les tampons réseau. En général, leur exécution se termine lorsque les tampons réseau associés ont été remplis (@code{send}) ou vidés (@code{recv}). Ils vous indiquent alors combien d'octets ils ont traité. Il est de `votre' responsabilité de les rappeler jusqu'à ce que votre message ait été complètement traité.

Lorsqu'un @code{recv} renvoie 0 octet, cela signifie que l'autre partie a fermé (ou est en train de fermer) la connexion. Vous ne recevrez plus de données sur cette connexion. Jamais. Vous pouvez peut-être envoyer des données avec succès. J’en parlerai plus tard.

Un protocole comme HTTP utilise un connecteur pour un seul transfert. Le client envoie une demande, puis lit une réponse. C'est tout. Le connecteur est mis au rebut. Cela signifie qu'un client peut détecter la fin de la réponse en recevant 0 octet.

Mais si vous prévoyez de réutiliser votre connecteur pour d'autres transferts, vous devez réaliser qu'`il n'y a pas' d'@abbr{EOT,End of Transfer} `sur un connecteur'. Je répète : si un appel à @code{send} ou @code{recv} se termine après avoir traité 0 octet, la connexion a été interrompue. Si la connexion n'a `pas' été interrompue, vous pouvez attendre sur un @code{recv} pour toujours, car le connecteur ne vous dira pas qu'il n'y a plus rien à lire (pour le moment). Maintenant, si vous y réfléchissez un peu, vous allez vous rendre compte d'une vérité fondamentale sur les connecteurs : `les messages doivent être de longueur fixe' (beurk), `ou être délimités' (bof), `ou indiquer de quelle longueur ils sont' (beaucoup mieux), `ou terminer en coupant la connexion'. Le choix est entièrement de votre côté (mais certaines façons sont meilleurs que d'autres).

En supposant que vous ne vouliez pas terminer la connexion, la solution la plus simple est un message de longueur fixe :

@example
class MySocket:
    """demonstration class only
      - coded for clarity, not efficiency
    """

    def __init__(self, sock=None):
        if sock is None:
            self.sock = socket.socket(
                            socket.AF_INET, socket.SOCK_STREAM)
        else:
            self.sock = sock

    def connect(self, host, port):
        self.sock.connect((host, port))

    def mysend(self, msg):
        totalsent = 0
        while totalsent < MSGLEN:
            sent = self.sock.send(msg[totalsent:])
            if sent == 0:
                raise RuntimeError("socket connection broken")
            totalsent = totalsent + sent

    def myreceive(self):
        chunks = []
        bytes_recd = 0
        while bytes_recd < MSGLEN:
            chunk = self.sock.recv(min(MSGLEN - bytes_recd, 2048))
            if chunk == b'@w{'}:
                raise RuntimeError("socket connection broken")
            chunks.append(chunk)
            bytes_recd = bytes_recd + len(chunk)
        return b'@w{'}.join(chunks)
@end example

Le code d'envoi ici est utilisable pour presque tous les systèmes de messagerie — en Python, vous envoyez des chaînes de caractères, et vous pouvez utiliser @code{len()} pour en déterminer la longueur (même si elle contient des caractères @code{\0}). C'est surtout le code de réception qui devient plus complexe. (Et en C, ce n'est pas bien pire, sauf que vous ne pouvez pas utiliser @code{strlen} si le message contient des @code{\0}s).

Le plus simple est de faire du premier caractère du message un indicateur du type de message, et de faire en sorte que le type détermine la longueur. Vous avez maintenant deux @code{recv}s — le premier pour obtenir (au moins) ce premier caractère afin de pouvoir déterminer la longueur, et le second dans une boucle pour obtenir le reste. Si vous décidez de suivre la route délimitée, vous recevrez un morceau de taille arbitraire (4096 ou 8192 est fréquemment une bonne valeur pour correspondre à la taille de la mémoire tampon du réseau), et vous analyserez ce que vous avez reçu pour trouver un délimiteur.

Une subtilité dont il faut être conscient : si votre protocole de conversation permet de renvoyer plusieurs messages les uns à la suite des autres (sans aucune sorte de réponse), et que vous passez à @code{recv} une taille de morceau arbitraire, vous pouvez en arriver à lire le début du message suivant. Vous devrez alors le mettre de côté et le conserver, jusqu'à ce que vous en ayez besoin.

Préfixer le message avec sa longueur (disons, sous la forme de 5 caractères numériques) devient plus complexe, parce que (croyez-le ou non), vous pouvez ne pas recevoir les 5 caractères en un seul @code{recv}. Pour une utilisation triviale, vous vous en tirerez à bon compte ; mais en cas de forte charge réseau, votre code se cassera très rapidement, à moins que vous n’utilisiez deux boucles @code{recv} — la première pour déterminer la longueur, la deuxième pour obtenir la partie « données » du message. Vilain. C’est aussi à ce moment que vous découvrirez que « l’envoi » via @code{send} ne parvient pas toujours à tout évacuer en un seul passage. Et bien que vous ayez lu cet avertissement, vous finirez par vous faire avoir par cette subtilité !

Pour garder une longueur raisonnable à cette page, pour forger votre caractère (et afin de garder l’avantage concurrentiel que j’ai sur vous), ces améliorations ne seront pas abordées et sont laissées en exercice au lecteur. Passons maintenant au nettoyage.

@menu
* Données binaires:: 

@end menu

@node Données binaires,,,Utilisation d'un connecteur
@anchor{howto/sockets binary-data}@anchor{4ea8}
@subsubsection Données binaires


Il est parfaitement possible d'envoyer des données binaires par l'intermédiaire d'un connecteur. Le problème majeur est que toutes les machines n'utilisent pas les mêmes formats pour les données binaires. Par exemple, l’ordre des octets du réseau@footnote{https://fr.wikipedia.org/wiki/Boutisme#Dans_les_communications} est gros-boutiste, avec l'octet le plus significatif en premier, de sorte qu'un entier de 16 bits avec la valeur @code{1} serait les deux octets hexadécimaux @code{00 01}. Cependant, la plupart des processeurs courants (x86/AMD64, ARM, RISC-V) sont petit-boutistes, avec l'octet le moins significatif en premier - ce même @code{1} serait @code{01 00}.

Les bibliothèques de sockets ont des appels pour convertir les entiers 16 et 32 bits - @code{ntohl, htonl, ntohs, htons} où « n » signifie `network' (réseau) et « h » signifie `host' (hôte), « s » signifie `short' (court) et « l » signifie `long'. Lorsque l’ordre du réseau est l’ordre de l’hôte, ils ne font rien, mais lorsque la machine fonctionne en ordre inversé, ils échangent les octets de manière appropriée.

De nos jours, avec les machines 64 bits, la représentation `ASCII' des données binaires est souvent plus compacte que la représentation binaire. C’est parce que dans un nombre surprenant de cas, tous ces `entiers' ont la valeur 0 et parfois 1. La chaîne « 0 » serait codée sur deux octets, alors qu'elle le serait sur 8 en tant que binaire 64 bits. Bien sûr, cela ne fonctionne pas très bien avec les messages de longueur fixe. C’est une affaire de choix.

@node Déconnexion,Connecteurs non bloquants,Utilisation d'un connecteur,Guide pratique programmation avec les sockets
@anchor{howto/sockets disconnecting}@anchor{4ea9}
@subsection Déconnexion


À proprement parler, vous êtes censé utiliser @code{shutdown} sur un connecteur pour l’arrêter avant de le fermer via @code{close}. Le @code{shutdown} est un avertissement au connecteur de l’autre côté. Selon l’argument que vous lui passez, cela peut signifier « Je ne vais plus envoyer, mais je vais quand même écouter », ou « Je n’écoute pas, bon débarras ! ». La plupart des bibliothèques de connecteurs, cependant, sont tellement habituées à ce que les programmeurs négligent d’utiliser ce morceau d’étiquette que normalement un @code{close} est équivalent à @code{shutdown() ; close()}. Ainsi, dans la plupart des situations, un @code{shutdown} explicite n’est pas nécessaire.

Une façon d’utiliser efficacement le @code{shutdown} est d’utiliser un échange de type HTTP. Le client envoie une requête et effectue ensuite un @code{shutdown(1)}. Cela indique au serveur que « ce client a fini d’envoyer, mais peut encore recevoir ». Le serveur peut détecter `EOF' par une réception de 0 octet. Il peut supposer qu’il a la requête complète. Le serveur envoie une réponse. Si le @code{send} se termine avec succès, alors, en effet, le client était encore en train de recevoir.

Python pousse l’arrêt automatique un peu plus loin, et dit que lorsqu’un connecteur est collecté par le ramasse-miette, il effectue automatiquement une fermeture via @code{close} si elle est nécessaire. Mais c’est une très mauvaise habitude de s’appuyer sur ce système. Si votre connecteur disparaît sans avoir fait un @code{close}, le connecteur à l’autre bout peut rester suspendu indéfiniment, pensant que vous êtes juste lent. Fermez vos connecteurs quand vous avez terminé `s’il vous plaît'.

@menu
* Quand les connecteurs meurent:: 

@end menu

@node Quand les connecteurs meurent,,,Déconnexion
@anchor{howto/sockets when-sockets-die}@anchor{4eaa}
@subsubsection Quand les connecteurs meurent


Le pire dans l'utilisation de connecteurs bloquants est probablement ce qui se passe lorsque l'autre côté s'interrompt brutalement (sans faire de fermeture via @code{close}). Votre connecteur risque d’attendre infiniment. TCP est un protocole fiable, et il attendra très, très longtemps avant d'abandonner une connexion. Si vous utilisez des fils d’exécution, le fil entier est pratiquement mort. Il n'y a pas grand-chose que vous puissiez faire à ce sujet. Du moment que vous ne faites rien de stupide, comme tenir un verrou verrouillé pendant une lecture bloquante, le fil ne consomme pas vraiment beaucoup de ressources. N'essayez `pas' de tuer le fil — si les fils sont plus efficients que les processus, c'est en partie parce qu'ils évitent les coûts significatifs liés au recyclage automatique des ressources. En d'autres termes, si vous parvenez à tuer le fil, tout votre processus risque d'être foutu.

@node Connecteurs non bloquants,,Déconnexion,Guide pratique programmation avec les sockets
@anchor{howto/sockets non-blocking-sockets}@anchor{4eab}
@subsection Connecteurs non bloquants


Si vous avez compris ce qui précède, vous savez déjà tout ce que vous devez savoir sur la mécanique de l’utilisation des connecteurs. Vous utiliserez toujours les mêmes appels, de la même façon. Il n’y que ça. Si vous le faites bien, c’est presque dans la poche.

En Python, vous utilisez @code{socket.setblocking(0)} pour rendre non-bloquant. En C, c’est plus complexe (pour commencer, vous devez choisir entre la version BSD @code{O_NONBLOCK} et la version POSIX presque impossible à distinguer @code{O_NDELAY}, qui est complètement différente de @code{TCP_NODELAY}), mais c’est exactement la même idée. Vous le faites après avoir créé le connecteur mais avant de l’utiliser (en fait, si vous êtes fou, vous pouvez alterner).

La différence majeure de fonctionnement est que @code{send}, @code{recv}, @code{connect} et @code{accept} peuvent rendre la main sans avoir rien fait. Vous avez (bien sûr) un certain nombre de choix. Vous pouvez vérifier le code de retour et les codes d'erreur et, en général, devenir fou. Si vous ne me croyez pas, essayez un jour. Votre application va grossir, boguer et vampiriser le processeur. Alors, évitons les solutions vouées à l’échec dès le départ et faisons les choses correctement.

Utilisation de @code{select}.

En C, implémenter @code{select} est assez complexe. En Python, c'est du gâteau, mais c'est assez proche de la version C ; aussi, si vous comprenez @code{select} en Python, vous aurez peu de problèmes en C :

@example
ready_to_read, ready_to_write, in_error = \
               select.select(
                  potential_readers,
                  potential_writers,
                  potential_errs,
                  timeout)
@end example

Vous passez à @code{select} trois listes : la première contient tous les connecteurs dont vous souhaiter lire le contenu ; la deuxième tous les connecteurs sur lesquels vous voudriez écrire, et la dernière (normalement laissée vide) ceux sur lesquels vous voudriez vérifier s’il y a des erreurs. Prenez note qu'un connecteur peut figurer dans plus d'une liste. L'appel à @code{select} est bloquant, mais vous pouvez lui donner un délai d'attente. C'est généralement une bonne chose à faire — donnez-lui un bon gros délai d'attente (disons une minute), à moins que vous n'ayez une bonne raison de ne pas le faire.

En retour, vous recevrez trois listes. Elles contiennent les connecteurs qui sont réellement lisibles, inscriptibles et en erreur. Chacune de ces listes est un sous-ensemble (éventuellement vide) de la liste correspondante que vous avez transmise.

Si un connecteur se trouve dans la liste renvoyée des connecteurs lisibles, vous pouvez être pratiquement certain qu'un @code{recv} sur ce connecteur renvoie `quelque chose'. Même chose pour la liste renvoyée des connecteurs inscriptibles. Vous pourrez envoyer `quelque chose'. Peut-être pas tout ce que vous voudrez, mais `quelque chose' est mieux que rien (en fait, n'importe quel connecteur raisonnablement sain sera présent dans la liste des connecteurs inscriptibles — cela signifie simplement que l'espace tampon réseau sortant est disponible).

Si vous avez un connecteur « serveur », mettez-le dans la liste des connecteurs potentiellement lisibles @code{potential_readers}. S’il apparaît dans la liste renvoyée des connecteurs que vous pouvez lire, votre @code{accept} fonctionnera (presque certainement). Si vous avez créé un nouveau connecteur pour se connecter via @code{connect} à quelqu'un d'autre, mettez-le dans la liste des connecteurs potentiellement inscriptibles. S’il apparaît dans la liste renvoyée des connecteurs sur lesquels vous pouvez écrire, vous avez une bonne chance qu'il se soit connecté.

En fait, @code{select} peut être pratique même avec des connecteurs bloquants. C'est une façon de déterminer si vous allez bloquer — le connecteur est renvoyé comme lisible lorsqu'il y a quelque chose dans les mémoires tampons. Cependant, cela n'aide pas encore à déterminer si l'autre extrémité a terminé, ou si elle est simplement occupée par autre chose.

`Alerte de portabilité' : Sous Unix, @code{select} fonctionne aussi bien avec les connecteurs qu'avec les fichiers. N'essayez pas cela sous Windows. Sous Windows, @code{select} ne fonctionne qu'avec les connecteurs. Notez également qu'en C, la plupart des options de connecteurs les plus avancées se font différemment sous Windows. En fait, sous Windows, j'utilise habituellement des fils d'exécution (qui fonctionnent très, très bien) avec mes connecteurs.

@node Sorting Techniques,Guide Unicode,Guide pratique programmation avec les sockets,Les HOWTOs de Python
@anchor{howto/sorting doc}@anchor{4eac}@anchor{howto/sorting sorting-techniques}@anchor{4ead}@anchor{howto/sorting sortinghowto}@anchor{2107}
@section Sorting Techniques


@*Auteur: 
Andrew Dalke et Raymond Hettinger


Les listes Python ont une méthode native @ref{bbd,,list.sort()} qui modifie les listes elles-mêmes. Il y a également une fonction native @ref{bbc,,sorted()} qui construit une nouvelle liste triée depuis un itérable.

Dans ce document, nous explorons différentes techniques pour trier les données en Python.

@menu
* Les bases du tri:: 
* Fonctions clef:: 
* Operator Module Functions and Partial Function Evaluation:: 
* Ascendant et descendant:: 
* Stabilité des tris et tris complexes:: 
* Decorate-Sort-Undecorate:: 
* Comparison Functions:: 
* Et n'oublions pas:: 
* Partial Sorts:: 

@end menu

@node Les bases du tri,Fonctions clef,,Sorting Techniques
@anchor{howto/sorting sorting-basics}@anchor{4eae}
@subsection Les bases du tri


Un tri ascendant simple est très facile : il suffit d'appeler la fonction @ref{bbc,,sorted()}. Elle renvoie une nouvelle liste triée :

@example
>>> sorted([5, 2, 3, 1, 4])
[1, 2, 3, 4, 5]
@end example

Vous pouvez aussi utiliser la méthode @ref{bbd,,list.sort()}. Elle modifie la liste elle-même (et renvoie @code{None} pour éviter les confusions). Habituellement, cette méthode est moins pratique que la fonction @ref{bbc,,sorted()} -- mais si vous n'avez pas besoin de la liste originale, cette technique est légèrement plus efficace.

@example
>>> a = [5, 2, 3, 1, 4]
>>> a.sort()
>>> a
[1, 2, 3, 4, 5]
@end example

Une autre différence est que la méthode @ref{bbd,,list.sort()} est seulement définie pour les listes. Au contraire, la fonction @ref{bbc,,sorted()} accepte n'importe quel itérable.

@example
>>> sorted(@{1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'@})
[1, 2, 3, 4, 5]
@end example

@node Fonctions clef,Operator Module Functions and Partial Function Evaluation,Les bases du tri,Sorting Techniques
@anchor{howto/sorting key-functions}@anchor{4eaf}
@subsection Fonctions clef


@ref{bbd,,list.sort()} et @ref{bbc,,sorted()} ont un paramètre `key' afin de spécifier une fonction (ou autre appelable) qui peut être appelée sur chaque élément de la liste avant d'effectuer des comparaisons.

Par exemple, voici une comparaison de texte insensible à la casse :

@example
>>> sorted("This is a test string from Andrew".split(), key=str.casefold)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']
@end example

La valeur du paramètre `key' doit être une fonction (ou autre appelable) qui prend un seul argument et renvoie une clef à utiliser à des fins de tri. Cette technique est rapide car la fonction clef est appelée exactement une seule fois pour chaque enregistrement en entrée.

Un usage fréquent est de faire un tri sur des objets complexes en utilisant les indices des objets en tant que clef. Par exemple :

@example
>>> student_tuples = [
...     ('john', 'A', 15),
...     ('jane', 'B', 12),
...     ('dave', 'B', 10),
... ]
>>> sorted(student_tuples, key=lambda student: student[2])   # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

La même technique marche pour des objets avec des attributs nommés. Par exemple :

@example
>>> class Student:
...     def __init__(self, name, grade, age):
...         self.name = name
...         self.grade = grade
...         self.age = age
...     def __repr__(self):
...         return repr((self.name, self.grade, self.age))

>>> student_objects = [
...     Student('john', 'A', 15),
...     Student('jane', 'B', 12),
...     Student('dave', 'B', 10),
... ]
>>> sorted(student_objects, key=lambda student: student.age)   # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

Objects with named attributes can be made by a regular class as shown
above, or they can be instances of @ref{1c6,,dataclass} or
a @ref{639,,named tuple}.

@node Operator Module Functions and Partial Function Evaluation,Ascendant et descendant,Fonctions clef,Sorting Techniques
@anchor{howto/sorting operator-module-functions-and-partial-function-evaluation}@anchor{4eb0}
@subsection Operator Module Functions and Partial Function Evaluation


The @ref{df2,,key function} patterns shown above are very common, so Python provides
convenience functions to make accessor functions easier and faster. The
@ref{9e,,operator} module has @ref{a50,,itemgetter()},
@ref{e20,,attrgetter()}, and a @ref{e21,,methodcaller()} function.

En utilisant ces fonctions, les exemples au dessus deviennent plus simples et plus rapides :

@example
>>> from operator import itemgetter, attrgetter

>>> sorted(student_tuples, key=itemgetter(2))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]

>>> sorted(student_objects, key=attrgetter('age'))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

Les fonctions du module `operator' permettent plusieurs niveaux de tri. Par exemple, pour trier par `grade' puis par `age' :

@example
>>> sorted(student_tuples, key=itemgetter(1,2))
[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]

>>> sorted(student_objects, key=attrgetter('grade', 'age'))
[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]
@end example

The @ref{5e,,functools} module provides another helpful tool for making
key-functions.  The @ref{40a,,partial()} function can reduce the
arity@footnote{https://en.wikipedia.org/wiki/Arity} of a multi-argument
function making it suitable for use as a key-function.

@example
>>> from functools import partial
>>> from unicodedata import normalize

>>> names = 'Zoë Åbjørn Núñez Élana Zeke Abe Nubia Eloise'.split()

>>> sorted(names, key=partial(normalize, 'NFD'))
['Abe', 'Åbjørn', 'Eloise', 'Élana', 'Nubia', 'Núñez', 'Zeke', 'Zoë']

>>> sorted(names, key=partial(normalize, 'NFC'))
['Abe', 'Eloise', 'Nubia', 'Núñez', 'Zeke', 'Zoë', 'Åbjørn', 'Élana']
@end example

@node Ascendant et descendant,Stabilité des tris et tris complexes,Operator Module Functions and Partial Function Evaluation,Sorting Techniques
@anchor{howto/sorting ascending-and-descending}@anchor{4eb1}
@subsection Ascendant et descendant


@ref{bbd,,list.sort()} et @ref{bbc,,sorted()} acceptent un paramètre nommé `reverse' avec une valeur booléenne. C'est utilisé pour déterminer l'ordre descendant des tris. Par exemple, pour avoir les données des étudiants dans l'ordre inverse par `age' :

@example
>>> sorted(student_tuples, key=itemgetter(2), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]

>>> sorted(student_objects, key=attrgetter('age'), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
@end example

@node Stabilité des tris et tris complexes,Decorate-Sort-Undecorate,Ascendant et descendant,Sorting Techniques
@anchor{howto/sorting sort-stability-and-complex-sorts}@anchor{4eb2}
@subsection Stabilité des tris et tris complexes


Les tris sont garantis stables@footnote{https://fr.wikipedia.org/wiki/Algorithme_de_tri#Caract.C3.A8re_stable}. Cela signifie que lorsque plusieurs enregistrements on la même clef, leur ordre original est préservé.

@example
>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> sorted(data, key=itemgetter(0))
[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]
@end example

Notez comme les deux enregistrements pour `blue' gardent leur ordre original et que par conséquent il est garanti que @code{('blue', 1)} précède @code{('blue', 2)}.

Cette propriété fantastique vous permet de construire des tris complexes dans des tris en plusieurs étapes. Par exemple, afin de sortir les données des étudiants en ordre descendant par `grade' puis en ordre ascendant par `age', effectuez un tri par `age' en premier puis un second tri par `grade' :

@example
>>> s = sorted(student_objects, key=attrgetter('age'))     # sort on secondary key
>>> sorted(s, key=attrgetter('grade'), reverse=True)       # now sort on primary key, descending
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

Ceci peut être encapsulé dans une fonction qui prend une liste et des n-uplets (attribut, ordre) pour les trier en plusieurs passes.

@example
>>> def multisort(xs, specs):
...     for key, reverse in reversed(specs):
...         xs.sort(key=attrgetter(key), reverse=reverse)
...     return xs

>>> multisort(list(student_objects), (('grade', True), ('age', False)))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

L'algorithme Timsort@footnote{https://fr.wikipedia.org/wiki/Timsort} utilisé dans Python effectue de multiples tris efficacement parce qu'il peut tirer avantage de l'ordre existant dans un jeu de données.

@node Decorate-Sort-Undecorate,Comparison Functions,Stabilité des tris et tris complexes,Sorting Techniques
@anchor{howto/sorting decorate-sort-undecorate}@anchor{4eb3}
@subsection Decorate-Sort-Undecorate


Cette technique est appelée Decorate-Sort-Undecorate et se base sur trois étapes :


@itemize *

@item 
Premièrement, la liste de départ est décorée avec les nouvelles valeurs qui contrôlent l'ordre du tri.

@item 
En second lieu, la liste décorée est triée.

@item 
Enfin, la décoration est supprimée, créant ainsi une liste qui contient seulement la valeur initiale dans le nouvel ordre.
@end itemize

Par exemple, pour trier les données étudiant par `grade' en utilisant l'approche DSU :

@example
>>> decorated = [(student.grade, i, student) for i, student in enumerate(student_objects)]
>>> decorated.sort()
>>> [student for grade, i, student in decorated]               # undecorate
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
@end example

Cette technique marche parce que les `n'-uplets sont comparés par ordre lexicographique; les premiers objets sont comparés; si il y a des objets identiques, alors l'objet suivant est comparé, et ainsi de suite.

Il n'est pas strictement nécessaire dans tous les cas d’inclure l'indice `i' dans la liste décorée, mais l'inclure donne deux avantages :


@itemize *

@item 
Le tri est stable -- si deux objets on la même clef, leur ordre sera préservé dans la liste triée.

@item 
Les objets d'origine ne sont pas nécessairement comparables car l'ordre des `n'-uplets décorés sera déterminé par au plus les deux premiers objets. Donc par exemple la liste originale pourrait contenir des nombres complexes qui pourraient ne pas être triés directement.
@end itemize

Un autre nom pour cette technique est Schwartzian transform@footnote{https://en.wikipedia.org/wiki/Schwartzian_transform}, après que Randal L. Schwartz l'ait popularisé chez les développeurs Perl.

Maintenant que le tri Python fournit des fonctions-clef, cette technique n'est plus souvent utilisée.

@node Comparison Functions,Et n'oublions pas,Decorate-Sort-Undecorate,Sorting Techniques
@anchor{howto/sorting comparison-functions}@anchor{4eb4}
@subsection Comparison Functions


Unlike key functions that return an absolute value for sorting, a comparison
function computes the relative ordering for two inputs.

For example, a balance scale@footnote{https://upload.wikimedia.org/wikipedia/commons/1/17/Balance_à_tabac_1850.JPG}
compares two samples giving a relative ordering: lighter, equal, or heavier.
Likewise, a comparison function such as @code{cmp(a, b)} will return a negative
value for less-than, zero if the inputs are equal, or a positive value for
greater-than.

It is common to encounter comparison functions when translating algorithms from
other languages.  Also, some libraries provide comparison functions as part of
their API.  For example, @ref{3c7e,,locale.strcoll()} is a comparison function.

To accommodate those situations, Python provides
@ref{11b7,,functools.cmp_to_key} to wrap the comparison function
to make it usable as a key function:

@example
sorted(words, key=cmp_to_key(strcoll))  # locale-aware sort order
@end example

@node Et n'oublions pas,Partial Sorts,Comparison Functions,Sorting Techniques
@anchor{howto/sorting odds-and-ends}@anchor{4eb5}
@subsection Et n'oublions pas



@itemize *

@item 
For locale aware sorting, use @ref{3c80,,locale.strxfrm()} for a key function or
@ref{3c7e,,locale.strcoll()} for a comparison function.  This is necessary
because "alphabetical" sort orderings can vary across cultures even
if the underlying alphabet is the same.

@item 
Le paramètre `reverse' maintient toujours un tri stable (de telle sorte que les enregistrements avec des clef égales gardent le même ordre). Notez que cet effet peut être simulé sans le paramètre en utilisant la fonction native @ref{850,,reversed()} deux fois :

@example
>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> standard_way = sorted(data, key=itemgetter(0), reverse=True)
>>> double_reversed = list(reversed(sorted(reversed(data), key=itemgetter(0))))
>>> assert standard_way == double_reversed
>>> standard_way
[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]
@end example

@item 
The sort routines use @code{<} when making comparisons
between two objects. So, it is easy to add a standard sort order to a class by
defining an @ref{127d,,__lt__()} method:

@example
>>> Student.__lt__ = lambda self, other: self.age < other.age
>>> sorted(student_objects)
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
@end example

However, note that @code{<} can fall back to using @ref{12ea,,__gt__()} if
@ref{127d,,__lt__()} is not implemented (see @ref{127d,,object.__lt__()}
for details on the mechanics).  To avoid surprises, 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}
recommends that all six comparison methods be implemented.
The @ref{f2d,,total_ordering()} decorator is provided to make that
task easier.

@item 
Les fonctions clef n'ont pas besoin de dépendre directement des objets triés. Une fonction clef peut aussi accéder à des ressources externes. En l'occurrence, si les grades des étudiants sont stockés dans un dictionnaire, ils peuvent être utilisés pour trier une liste différentes de noms d'étudiants :

@example
>>> students = ['dave', 'john', 'jane']
>>> newgrades = @{'john': 'F', 'jane':'A', 'dave': 'C'@}
>>> sorted(students, key=newgrades.__getitem__)
['jane', 'dave', 'john']
@end example
@end itemize

@node Partial Sorts,,Et n'oublions pas,Sorting Techniques
@anchor{howto/sorting partial-sorts}@anchor{4eb6}
@subsection Partial Sorts


Some applications require only some of the data to be ordered.  The standard
library provides several tools that do less work than a full sort:


@itemize *

@item 
@ref{ef3,,min()} and @ref{ef4,,max()} return the smallest and largest values,
respectively.  These functions make a single pass over the input data and
require almost no auxiliary memory.

@item 
@ref{24b8,,heapq.nsmallest()} and @ref{24b7,,heapq.nlargest()} return
the `n' smallest and largest values, respectively.  These functions
make a single pass over the data keeping only `n' elements in memory
at a time.  For values of `n' that are small relative to the number of
inputs, these functions make far fewer comparisons than a full sort.

@item 
@ref{1470,,heapq.heappush()} and @ref{1471,,heapq.heappop()} create and maintain a
partially sorted arrangement of data that keeps the smallest element
at position @code{0}.  These functions are suitable for implementing
priority queues which are commonly used for task scheduling.
@end itemize

@node Guide Unicode,Guide pratique récupérer des ressources web en utilisant le module urllib,Sorting Techniques,Les HOWTOs de Python
@anchor{howto/unicode doc}@anchor{4eb7}@anchor{howto/unicode id1}@anchor{4eb8}@anchor{howto/unicode unicode-howto}@anchor{1282}
@section Guide Unicode


@*Version: 
1.12


Ce guide décrit la gestion de la spécification Unicode par Python pour les données textuelles et explique les différents problèmes généralement rencontrés par les utilisateurs qui travaillent avec Unicode.

@menu
* Introduction à Unicode:: 
* Prise en charge Unicode de Python:: 
* Lecture et écriture de données Unicode:: 
* Remerciements: Remerciements<10>. 

@end menu

@node Introduction à Unicode,Prise en charge Unicode de Python,,Guide Unicode
@anchor{howto/unicode introduction-to-unicode}@anchor{4eb9}
@subsection Introduction à Unicode


@menu
* Définitions:: 
* Encodages:: 
* Références: Références<4>. 

@end menu

@node Définitions,Encodages,,Introduction à Unicode
@anchor{howto/unicode definitions}@anchor{4eba}
@subsubsection Définitions


Les programmes d'aujourd'hui doivent être capables de traiter une grande variété de caractères. Les applications sont souvent internationalisées pour afficher les messages et les résultats dans une variété de langues sélectionnables par l'utilisateur ; le même programme peut avoir besoin d'afficher un message d'erreur en anglais, français, japonais, hébreu ou russe. Le contenu Web peut être écrit dans n'importe laquelle de ces langues et peut également inclure une variété de symboles émoji. Le type de chaîne de caractères de Python utilise le standard Unicode pour représenter les caractères, ce qui permet aux programmes Python de travailler avec tous ces différents caractères possibles.

Unicode (@indicateurl{https://www.unicode.org/}) est une spécification qui vise à lister tous les caractères utilisés par les langues humaines et à donner à chaque caractère son propre code unique. Les spécifications Unicode sont continuellement révisées et mises à jour pour ajouter de nouvelles langues et de nouveaux symboles.

Un `caractère' est le plus petit composant possible d'un texte. « A », « B », « C », etc. sont tous des caractères différents. Il en va de même pour « È » et « Í ». Les caractères varient selon la langue ou le contexte dont vous parlez. Par exemple, il y a un caractère pour « Chiffre Romain Un » (`Roman Numeral One'), « Ⅰ », qui est séparé de la lettre majuscule « I ». Ils se ressemblent généralement, mais ce sont deux caractères différents qui ont des significations différentes.

Le standard Unicode décrit comment les caractères sont représentés par les `points de code'. Une valeur de point de code est un nombre entier compris entre @code{0} et @code{0x10FFFF} (environ 1,1 million de valeurs possibles, le nombre de valeurs réellement assignées@footnote{https://www.unicode.org/versions/latest/#Summary} est inférieur à ce nombre). Dans le standard et dans le présent document, un point de code est écrit en utilisant la notation @code{U+265E} pour désigner le caractère avec la valeur @code{0x265e} (9 822 en décimal).

La standard Unicode contient de nombreux tableaux contenant la liste des caractères et des points de code correspondants :

@example
0061    'a'; LATIN SMALL LETTER A
0062    'b'; LATIN SMALL LETTER B
0063    'c'; LATIN SMALL LETTER C
...
007B    '@{'; LEFT CURLY BRACKET
...
2167    'Ⅷ'; ROMAN NUMERAL EIGHT
2168    'Ⅸ'; ROMAN NUMERAL NINE
...
265E    '♞'; BLACK CHESS KNIGHT
265F    '♟'; BLACK CHESS PAWN
...
1F600   '😀'; GRINNING FACE
1F609   '😉'; WINKING FACE
...
@end example

À proprement parler, ces définitions laissent entendre qu'il est inutile de dire « c'est le caractère @code{U+265E} ». @code{U+265E} est un point de code, qui représente un caractère particulier ; dans ce cas, il représente le caractère « BLACK CHESS KNIGHT », « ♞ ». Dans des contextes informels, cette distinction entre les points de code et les caractères sera parfois oubliée.

Un caractère est représenté sur un écran ou sur papier par un ensemble d’éléments graphiques appelé `glyphe'. Le glyphe d’un A majuscule, par exemple, est deux traits diagonaux et un trait horizontal, bien que les détails exacts dépendent de la police utilisée. La plupart du code Python n’a pas besoin de s’inquiéter des glyphes ; trouver le bon glyphe à afficher est généralement le travail d’une boîte à outils GUI ou du moteur de rendu des polices d’un terminal.

@node Encodages,Références<4>,Définitions,Introduction à Unicode
@anchor{howto/unicode encodings}@anchor{4ebb}
@subsubsection Encodages


Pour résumer la section précédente : une chaîne Unicode est une séquence de points de code, qui sont des nombres de @code{0} à @code{0x10FFFF} (1 114 111 en décimal). Cette séquence de points de code doit être stockée en mémoire sous la forme d'un ensemble de `unités de code', et les `unités de code' sont ensuite transposées en octets de 8 bits. Les règles de traduction d'une chaîne Unicode en une séquence d'octets sont appelées un `encodage de caractères' ou simplement un `encodage'.

Le premier encodage auquel vous pouvez penser est l'utilisation d'entiers 32 bits comme unité de code, puis l'utilisation de la représentation des entiers 32 bits par le CPU. Dans cette représentation, la chaîne « Python » ressemblerait à ceci :

@example
   P           y           t           h           o           n
0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00
   0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
@end example

Cette représentation est simple mais son utilisation pose un certain nombre de problèmes.


@enumerate 

@item 
Elle n’est pas portable ; des processeurs différents ordonnent les octets différemment.

@item 
Elle gâche beaucoup d'espace. Dans la plupart des textes, la majorité des points de code sont inférieurs à 127, ou à 255, donc beaucoup d'espace est occupé par des octets @code{0x00}. La chaîne ci-dessus occupe 24 octets, à comparer aux 6 octets nécessaires pour une représentation en ASCII. L'utilisation supplémentaire de RAM n'a pas trop d'importance (les ordinateurs de bureau ont des gigaoctets de RAM et les chaînes ne sont généralement pas si grandes que ça), mais l'accroissement de notre utilisation du disque et de la bande passante réseau par un facteur de 4 est intolérable.

@item 
Elle n’est pas compatible avec les fonctions C existantes telles que @code{strlen()}, il faudrait donc utiliser une nouvelle famille de fonctions, celle des chaînes larges (`wide strings').
@end enumerate

Par conséquent, cet encodage n'est pas très utilisé et d'autres encodages, plus efficaces et pratiques comme UTF-8, sont plutôt choisis.

UTF-8 est l’un des encodages les plus couramment utilisés et Python l’utilise souvent par défaut. UTF signifie « Unicode Transformation Format » (format de transformation Unicode) et « 8 » signifie que des nombres à 8 bits sont utilisés dans l'encodage (il existe également des codages UTF-16 et UTF-32, mais ils sont moins souvent utilisés que UTF-8). UTF-8 utilise les règles suivantes :


@enumerate 

@item 
Si le point de code est < 128, il est représenté par la valeur de l'octet correspondant.

@item 
Si le point de code est ≥ 128, il est transformé en une séquence de deux, trois ou quatre octets, où chaque octet de la séquence est compris entre 128 et 255.
@end enumerate

UTF-8 a plusieurs propriétés intéressantes :


@enumerate 

@item 
Il peut gérer n'importe quel point de code Unicode.

@item 
Une chaîne Unicode est transformée en une séquence d’octets qui contient des octets zéro uniquement lorsqu’ils représentent le caractère nul (U+0000). Cela signifie que les chaînes UTF-8 peuvent être traitées par des fonctions C telles que @code{strcpy()} et envoyées par des protocoles pour qui les octets zéro signifient forcément la fin de chaîne.

@item 
Une chaîne de texte ASCII est également un texte UTF-8 valide.

@item 
UTF-8 est assez compact. La majorité des caractères couramment utilisés peuvent être représentés avec un ou deux octets.

@item 
Si des octets sont corrompus ou perdus, il est possible de déterminer le début du prochain point de code encodé en UTF-8 et de se resynchroniser. Il est également improbable que des données 8-bits aléatoires ressemblent à du UTF-8 valide.

@item 
UTF-8 est un encodage orienté octet. L'encodage spécifie que chaque caractère est représenté par une séquence spécifique d'un ou plusieurs octets. Ceci permet d'éviter les problèmes d'ordre des octets qui peuvent survenir avec les encodages orientés entiers (`integer') ou orientés mots processeurs (`words'), comme UTF-16 et UTF-32, où la séquence des octets varie en fonction du matériel sur lequel la chaîne a été encodée.
@end enumerate

@node Références<4>,,Encodages,Introduction à Unicode
@anchor{howto/unicode references}@anchor{4ebc}
@subsubsection Références


Le site du Consortium Unicode@footnote{https://www.unicode.org}, en anglais, a des diagrammes de caractères, un glossaire et des versions PDF de la spécification Unicode. Préparez-vous à une lecture difficile. Une chronologie@footnote{https://www.unicode.org/history/} de l’origine et du développement de l’Unicode est également disponible sur le site.

Sur la chaîne Youtube `Computerphile', Tom Scott parle brièvement de l’histoire d’Unicode et d’UTF-8@footnote{https://www.youtube.com/watch?v=MijmeoH9LT4} (9 minutes et 36 secondes).

Pour aider à comprendre le standard, Jukka Korpela a écrit un guide d’introduction@footnote{https://jkorpela.fi/unicode/guide.html} à la lecture des tables de caractères Unicode (ressource en anglais).

Un autre bon article d'introduction@footnote{https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/} a été écrit par Joel Spolsky. Si cette présente introduction ne vous a pas clarifié les choses, vous devriez essayer de lire cet article-là avant de continuer.

Les pages Wikipédia sont souvent utiles ; voir les pages pour « Codage des caractères@footnote{https://fr.wikipedia.org/wiki/Codage_des_caract%C3%A8res} » et UTF-8@footnote{https://fr.wikipedia.org/wiki/UTF-8}, par exemple.

@node Prise en charge Unicode de Python,Lecture et écriture de données Unicode,Introduction à Unicode,Guide Unicode
@anchor{howto/unicode python-s-unicode-support}@anchor{4ebd}
@subsection Prise en charge Unicode de Python


Maintenant que vous avez appris les rudiments de l'Unicode, nous pouvons regarder les fonctionnalités Unicode de Python.

@menu
* Le type String:: 
* Conversion en octets:: 
* Littéraux Unicode dans le code source Python:: 
* Propriétés Unicode:: 
* Comparaison de chaînes de caractères:: 
* Expressions régulières Unicode:: 
* Références: Références<5>. 

@end menu

@node Le type String,Conversion en octets,,Prise en charge Unicode de Python
@anchor{howto/unicode the-string-type}@anchor{4ebe}
@subsubsection Le type `String'


Depuis Python 3.0, le type @ref{435,,str} du langage contient des caractères Unicode, c'est-à-dire n'importe quelle chaîne créée à l'aide de @code{"unicode déchire !"}, @code{'unicode déchire !'} ou la syntaxe à triples guillemets est enregistrée comme Unicode.

L'encodage par défaut pour le code source Python est UTF-8, il est donc facile d'inclure des caractères Unicode dans une chaîne littérale :

@example
try:
    with open('/tmp/input.txt', 'r') as f:
        ...
except OSError:
    # 'File not found' error message.
    print("Fichier non trouvé")
@end example

Note : Python 3 sait gérer les caractères Unicode dans les identifiants :

@example
répertoire = "/tmp/records.log"
with open(répertoire, "w") as f:
    f.write("test\n")
@end example

Si vous ne pouvez pas entrer un caractère particulier dans votre éditeur ou si vous voulez garder le code source uniquement en ASCII pour une raison quelconque, vous pouvez également utiliser des séquences d'échappement dans les littéraux de chaîne (en fonction de votre système, il se peut que vous voyiez le glyphe réel du `delta majuscule' au lieu d'une séquence d'échappement @code{\u...})

@example
>>> "\N@{GREEK CAPITAL LETTER DELTA@}"  # Using the character name
'\u0394'
>>> "\u0394"                          # Using a 16-bit hex value
'\u0394'
>>> "\U00000394"                      # Using a 32-bit hex value
'\u0394'
@end example

De plus, une chaîne de caractères peut être créée en utilisant la méthode @ref{8c3,,decode()} de la classe @ref{1bd,,bytes}. Cette méthode prend un argument `encoding', @code{UTF-8} par exemple, et optionnellement un argument `errors'.

L'argument `errors' détermine la réponse lorsque la chaîne en entrée ne peut pas être convertie selon les règles de l'encodage. Les valeurs autorisées pour cet argument sont @code{'strict'} (« strict » : lève une exception @ref{a01,,UnicodeDecodeError}), @code{'replace'} (« remplacer » : utilise @code{U+FFFD}, @code{REPLACEMENT CARACTER}), @code{'ignore'} (« ignorer » : n'inclut pas le caractère dans le résultat Unicode) ou @code{'backslashreplace'} (« remplacer avec antislash » : insère une séquence d’échappement @code{\xNN}). Les exemples suivants illustrent les différences :

@example
>>> b'\x80abc'.decode("utf-8", "strict")  
Traceback (most recent call last):
    ...
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 0:
  invalid start byte
>>> b'\x80abc'.decode("utf-8", "replace")
'\ufffdabc'
>>> b'\x80abc'.decode("utf-8", "backslashreplace")
'\\x80abc'
>>> b'\x80abc'.decode("utf-8", "ignore")
'abc'
@end example

Les encodages sont spécifiés sous forme de chaînes de caractères contenant le nom de l'encodage. Python est livré avec une centaine d'encodages différents ; voir la référence de la bibliothèque Python sur les @ref{da6,,encodages standards} pour une liste. Certains encodages ont plusieurs noms ; par exemple, @code{'latin-1'}, @code{'iso_8859_1'} et @code{'8859'} sont tous synonymes du même encodage.

Des chaînes Unicode à un caractère peuvent également être créées avec la fonction native @ref{15fb,,chr()}, qui prend des entiers et renvoie une chaîne Unicode de longueur 1 qui contient le point de code correspondant. L'opération inverse est la fonction native @ref{1e75,,ord()} qui prend une chaîne Unicode d'un caractère et renvoie la valeur du point de code :

@example
>>> chr(57344)
'\ue000'
>>> ord('\ue000')
57344
@end example

@node Conversion en octets,Littéraux Unicode dans le code source Python,Le type String,Prise en charge Unicode de Python
@anchor{howto/unicode converting-to-bytes}@anchor{4ebf}
@subsubsection Conversion en octets


La méthode inverse de @ref{8c3,,bytes.decode()} est @ref{8c2,,str.encode()}, qui renvoie une représentation @ref{1bd,,bytes} de la chaîne Unicode, codée dans l’encodage `encoding' demandé.

Le paramètre `errors' est le même que le paramètre de la méthode @ref{8c3,,decode()} mais possède quelques gestionnaires supplémentaires. En plus de @code{'strict'}, @code{'ignore'} et @code{'remplace'} (qui dans ce cas insère un point d'interrogation au lieu du caractère non encodable), il y a aussi @code{'xmlcharrefreplace'} (insère une référence XML), @code{backslashreplace} (insère une séquence @code{\uNNNN}) et @code{namereplace} (insère une séquence @code{\N@{...@}}).

L'exemple suivant montre les différents résultats :

@example
>>> u = chr(40960) + 'abcd' + chr(1972)
>>> u.encode('utf-8')
b'\xea\x80\x80abcd\xde\xb4'
>>> u.encode('ascii')  
Traceback (most recent call last):
    ...
UnicodeEncodeError: 'ascii' codec can't encode character '\ua000' in
  position 0: ordinal not in range(128)
>>> u.encode('ascii', 'ignore')
b'abcd'
>>> u.encode('ascii', 'replace')
b'?abcd?'
>>> u.encode('ascii', 'xmlcharrefreplace')
b'&#40960;abcd&#1972;'
>>> u.encode('ascii', 'backslashreplace')
b'\\ua000abcd\\u07b4'
>>> u.encode('ascii', 'namereplace')
b'\\N@{YI SYLLABLE IT@}abcd\\u07b4'
@end example

Les routines de bas niveau pour enregistrer et accéder aux encodages disponibles se trouvent dans le module @ref{1b,,codecs}. L'implémentation de nouveaux encodages nécessite également de comprendre le module @ref{1b,,codecs}. Cependant, les fonctions d'encodage et de décodage renvoyées par ce module sont généralement de bas-niveau pour être facilement utilisées et l'écriture de nouveaux encodages est une tâche très spécialisée, donc le module ne sera pas couvert dans ce guide.

@node Littéraux Unicode dans le code source Python,Propriétés Unicode,Conversion en octets,Prise en charge Unicode de Python
@anchor{howto/unicode unicode-literals-in-python-source-code}@anchor{4ec0}
@subsubsection Littéraux Unicode dans le code source Python


Dans le code source Python, des points de code Unicode spécifiques peuvent être écrits en utilisant la séquence d'échappement @code{\u}, suivie de quatre chiffres hexadécimaux donnant le point de code. La séquence d'échappement @code{\U} est similaire, mais attend huit chiffres hexadécimaux, pas quatre :

@example
>>> s = "a\xac\u1234\u20ac\U00008000"
... #     ^^^^ two-digit hex escape
... #         ^^^^^^ four-digit Unicode escape
... #                     ^^^^^^^^^^ eight-digit Unicode escape
>>> [ord(c) for c in s]
[97, 172, 4660, 8364, 32768]
@end example

L'utilisation de séquences d'échappement pour des points de code supérieurs à 127 est acceptable à faible dose, mais devient gênante si vous utilisez beaucoup de caractères accentués, comme c'est le cas dans un programme avec des messages en français ou dans une autre langue utilisant des lettres accentuées. Vous pouvez également assembler des chaînes de caractères à l'aide de la fonction native @ref{15fb,,chr()}, mais c'est encore plus fastidieux.

Idéalement, vous devriez être capable d'écrire des littéraux dans l'encodage naturel de votre langue. Vous pourriez alors éditer le code source de Python avec votre éditeur favori qui affiche les caractères accentués naturellement, et a les bons caractères utilisés au moment de l'exécution.

Python considère que le code source est écrit en UTF-8 par défaut, mais vous pouvez utiliser presque n'importe quel encodage si vous déclarez l'encodage utilisé. Cela se fait en incluant un commentaire spécial sur la première ou la deuxième ligne du fichier source :

@example
#!/usr/bin/env python
# -*- coding: latin-1 -*-

u = 'abcdé'
print(ord(u[-1]))
@end example

La syntaxe s'inspire de la notation d'`Emacs' pour spécifier les variables locales à un fichier. `Emacs' supporte de nombreuses variables différentes, mais Python ne gère que `coding'. Les symboles @code{-*-} indiquent à `Emacs' que le commentaire est spécial ; ils n'ont aucune signification pour Python mais sont une convention. Python cherche @code{coding: name} ou @code{coding=name} dans le commentaire.

Si vous n'incluez pas un tel commentaire, l'encodage par défaut est UTF-8 comme déjà mentionné. Voir aussi la 
@geindex Python Enhancement Proposals; PEP 263
PEP 263@footnote{https://peps.python.org/pep-0263/} pour plus d'informations.

@node Propriétés Unicode,Comparaison de chaînes de caractères,Littéraux Unicode dans le code source Python,Prise en charge Unicode de Python
@anchor{howto/unicode unicode-properties}@anchor{4ec1}
@subsubsection Propriétés Unicode


La spécification Unicode inclut une base de données d'informations sur les points de code. Pour chaque point de code défini, l'information comprend le nom du caractère, sa catégorie, la valeur numérique s'il y a lieu (pour les caractères représentant des concepts numériques tels que les chiffres romains, les fractions telles qu'un tiers et quatre cinquièmes, etc.). Il existe également des propriétés liées à l'affichage, telles que l'utilisation du point de code dans un texte bidirectionnel.

Le programme suivant affiche des informations sur plusieurs caractères et affiche la valeur numérique d'un caractère particulier :

@example
import unicodedata

u = chr(233) + chr(0x0bf2) + chr(3972) + chr(6000) + chr(13231)

for i, c in enumerate(u):
    print(i, '%04x' % ord(c), unicodedata.category(c), end=" ")
    print(unicodedata.name(c))

# Get numeric value of second character
print(unicodedata.numeric(u[1]))
@end example

Si vous l'exécutez, cela affiche :

@example
0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE
1 0bf2 No TAMIL NUMBER ONE THOUSAND
2 0f84 Mn TIBETAN MARK HALANTA
3 1770 Lo TAGBANWA LETTER SA
4 33af So SQUARE RAD OVER S SQUARED
1000.0
@end example

Les codes de catégorie sont des abréviations décrivant la nature du caractère. Celles-ci sont regroupées en catégories telles que « Lettre », « Nombre », « Ponctuation » ou « Symbole », qui sont à leur tour divisées en sous-catégories. Pour prendre par exemple les codes de la sortie ci-dessus, @code{'Ll'} signifie « Lettre, minuscules », @code{'No'} signifie « Nombre, autre », @code{'Mn'} est « Marque, non-espaçant », et @code{'So'} est « Symbole, autre ». Voir la section Valeurs générales des catégories de la documentation de la base de données de caractères Unicode@footnote{https://www.unicode.org/reports/tr44/#General_Category_Values} (ressource en anglais) pour une liste de codes de catégories.

@node Comparaison de chaînes de caractères,Expressions régulières Unicode,Propriétés Unicode,Prise en charge Unicode de Python
@anchor{howto/unicode comparing-strings}@anchor{4ec2}
@subsubsection Comparaison de chaînes de caractères


Unicode ajoute une certaine complication à la comparaison des chaînes de caractères, car le même jeu de caractères peut être représenté par différentes séquences de points de code. Par exemple, une lettre comme « ê » peut être représentée comme un point de code unique @code{U+00EA}, ou comme @code{U+0065 U+0302}, qui est le point de code pour « e » suivi d'un point de code pour @code{COMBINING CIRCUMFLEX ACCENT}. Celles-ci produisent le même résultat lorsqu'elles sont affichées, mais l'une est une chaîne de caractères de longueur 1 et l'autre de longueur 2.

Un outil pour une comparaison insensible à la casse est la méthode @ref{dc3,,casefold()} qui convertit une chaîne en une forme insensible à la casse suivant un algorithme décrit par le standard Unicode. Cet algorithme a un traitement spécial pour les caractères tels que la lettre allemande « `ß' » (point de code @code{U+00DF}), qui devient la paire de lettres minuscules « `ss' ».

@example
>>> street = 'Gürzenichstraße'
>>> street.casefold()
'gürzenichstrasse'
@end example

A second tool is the @ref{104,,unicodedata} module's
@ref{6bf,,normalize()} function that converts strings to one
of several normal forms, where letters followed by a combining character are
replaced with single characters.  @ref{6bf,,normalize()} can
be used to perform string comparisons that won't falsely report
inequality if two strings use combining characters differently:

@example
import unicodedata

def compare_strs(s1, s2):
    def NFD(s):
        return unicodedata.normalize('NFD', s)

    return NFD(s1) == NFD(s2)

single_char = 'ê'
multiple_chars = '\N@{LATIN SMALL LETTER E@}\N@{COMBINING CIRCUMFLEX ACCENT@}'
print('length of first string=', len(single_char))
print('length of second string=', len(multiple_chars))
print(compare_strs(single_char, multiple_chars))
@end example

Si vous l'exécutez, cela affiche :

@example
$ python compare-strs.py
length of first string= 1
length of second string= 2
True
@end example

Le premier argument de la fonction @ref{6bf,,normalize()} est une chaîne de caractères donnant la forme de normalisation désirée, qui peut être une de celles-ci : @code{'NFC'}, @code{'NFKC'}, @code{'NFD'} et @code{'NFKD'}.

La norme Unicode spécifie également comment faire des comparaisons insensibles à la casse :

@example
import unicodedata

def compare_caseless(s1, s2):
    def NFD(s):
        return unicodedata.normalize('NFD', s)

    return NFD(NFD(s1).casefold()) == NFD(NFD(s2).casefold())

# Example usage
single_char = 'ê'
multiple_chars = '\N@{LATIN CAPITAL LETTER E@}\N@{COMBINING CIRCUMFLEX ACCENT@}'

print(compare_caseless(single_char, multiple_chars))
@end example

This will print @code{True}.  (Why is @code{NFD()} invoked twice?  Because
there are a few characters that make @ref{dc3,,casefold()} return a
non-normalized string, so the result needs to be normalized again. See
section 3.13 of the Unicode Standard for a discussion and an example.)

@node Expressions régulières Unicode,Références<5>,Comparaison de chaînes de caractères,Prise en charge Unicode de Python
@anchor{howto/unicode unicode-regular-expressions}@anchor{4ec3}
@subsubsection Expressions régulières Unicode


Les expressions régulières gérées par le module @ref{b8,,re} peuvent être fournies sous forme de chaîne d'octets ou de texte. Certaines séquences de caractères spéciaux telles que @code{\d} et @code{\w} ont des significations différentes selon que le motif est fourni en octets ou en texte. Par exemple, @code{\d} correspond aux caractères @code{[0-9]} en octets mais dans les chaînes de caractères correspond à tout caractère de la catégorie @code{'Nd'}.

Dans cet exemple, la chaîne contient le nombre 57 écrit en chiffres arabes et thaïlandais :

@example
import re
p = re.compile(r'\d+')

s = "Over \u0e55\u0e57 57 flavours"
m = p.search(s)
print(repr(m.group()))
@end example

Une fois exécuté, @code{\d+} correspond aux chiffres thaïlandais et les affiche. Si vous fournissez le drapeau @ref{617,,re.ASCII} à @ref{bc1,,compile()}, @code{\d+} correspond cette fois à la chaîne "57".

De même, @code{\w} correspond à une grande variété de caractères Unicode mais seulement @code{[a-zA-Z0-9_]} en octets (ou si @ref{617,,re.ASCII} est fourni) et @code{\s} correspond soit aux caractères blancs Unicode soit aux caractères @code{[ \t\n\r\f\v]}.

@node Références<5>,,Expressions régulières Unicode,Prise en charge Unicode de Python
@anchor{howto/unicode id2}@anchor{4ec4}
@subsubsection Références


@c comment should these be mentioned earlier, e.g. at the start of the "introduction to Unicode" first section?

Quelques bonnes discussions alternatives sur la gestion d'Unicode par Python sont :


@itemize *

@item 
Processing Text Files in Python 3@footnote{https://python-notes.curiousefficiency.org/en/latest/python3/text_file_processing.html}, par Nick Coghlan.

@item 
Pragmatic Unicode@footnote{https://nedbatchelder.com/text/unipain.html}, une présentation `PyCon' 2012 par Ned Batchelder.
@end itemize

Le type @ref{435,,str} est décrit dans la référence de la bibliothèque Python à @ref{1b8a,,Type Séquence de Texte — str}.

La documentation du module @ref{104,,unicodedata}.

La documentation du module @ref{1b,,codecs}.

Marc-André Lemburg a donné une présentation intitulée « Python et Unicode » (diapositives PDF)@footnote{https://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf} à `EuroPython' 2002. Les diapositives sont un excellent aperçu de la conception des fonctionnalités Unicode de Python 2 (où le type de chaîne Unicode est appelé @code{unicode} et les littéraux commencent par @code{u}).

@node Lecture et écriture de données Unicode,Remerciements<10>,Prise en charge Unicode de Python,Guide Unicode
@anchor{howto/unicode reading-and-writing-unicode-data}@anchor{4ec5}
@subsection Lecture et écriture de données Unicode


Une fois que vous avez écrit du code qui fonctionne avec des données Unicode, le problème suivant concerne les entrées/sorties. Comment obtenir des chaînes Unicode dans votre programme et comment convertir les chaînes Unicode dans une forme appropriée pour le stockage ou la transmission ?

Il est possible que vous n'ayez rien à faire en fonction de vos sources d'entrée et des destinations de vos données de sortie ; il convient de vérifier si les bibliothèques utilisées dans votre application gèrent l'Unicode nativement. Par exemple, les analyseurs XML renvoient souvent des données Unicode. De nombreuses bases de données relationnelles prennent également en charge les colonnes encodées en Unicode et peuvent renvoyer des valeurs Unicode à partir d'une requête SQL.

Les données Unicode sont généralement converties en un encodage particulier avant d'être écrites sur le disque ou envoyées sur un connecteur réseau. Il est possible de faire tout le travail vous-même : ouvrir un fichier, lire un élément 8-bits, puis convertir les octets avec @code{bytes.decode(encoding)}. Cependant, l'approche manuelle n'est pas recommandée.

La nature multi-octets des encodages pose problème ; un caractère Unicode peut être représenté par plusieurs octets. Si vous voulez lire le fichier par morceaux de taille arbitraire (disons 1024 ou 4096 octets), vous devez écrire un code de gestion des erreurs pour détecter le cas où une partie seulement des octets codant un seul caractère Unicode est lue à la fin d'un morceau. Une solution serait de lire le fichier entier en mémoire et d'effectuer le décodage, mais cela vous empêche de travailler avec des fichiers extrêmement volumineux ; si vous avez besoin de lire un fichier de 2 Gio, vous avez besoin de 2 Gio de RAM (plus que ça, en fait, puisque pendant un moment, vous aurez besoin d'avoir à la fois la chaîne encodée et sa version Unicode en mémoire).

La solution serait d'utiliser l'interface de décodage de bas-niveau pour intercepter le cas des séquences d'encodage incomplètes. Ce travail d'implémentation a déjà été fait pour vous : la fonction native @ref{505,,open()} peut renvoyer un objet de type fichier qui suppose que le contenu du fichier est dans un encodage spécifié et accepte les paramètres Unicode pour des méthodes telles que @ref{1c13,,read()} et @ref{1c02,,write()}. Ceci fonctionne grâce aux paramètres `encoding' et `errors' de @ref{505,,open()} qui sont interprétés comme ceux de @ref{8c2,,str.encode()} et @ref{8c3,,bytes.decode()}.

Lire de l'Unicode à partir d'un fichier est donc simple :

@example
with open('unicode.txt', encoding='utf-8') as f:
    for line in f:
        print(repr(line))
@end example

Il est également possible d'ouvrir des fichiers en mode « mise à jour », permettant à la fois la lecture et l'écriture :

@example
with open('test', encoding='utf-8', mode='w+') as f:
    f.write('\u4500 blah blah blah\n')
    f.seek(0)
    print(repr(f.readline()[:1]))
@end example

Le caractère Unicode @code{U+FEFFF} est utilisé comme marque pour indiquer le boutisme (c'est-à-dire l'ordre dans lequel les octets sont placés pour indiquer une valeur sur plusieurs octets, `byte-order mark' en anglais ou `BOM'), et est souvent écrit en tête (premier caractère) d'un fichier afin d'aider à l'auto-détection du boutisme du fichier. Certains encodages, comme UTF-16, s'attendent à ce qu'une `BOM' soit présente au début d'un fichier ; lorsqu'un tel encodage est utilisé, la `BOM' sera automatiquement écrite comme premier caractère et sera silencieusement retirée lorsque le fichier sera lu. Il existe des variantes de ces encodages, comme @code{utf-16-le} et @code{utf-16-be} pour les encodages petit-boutiste et gros-boutiste, qui spécifient un ordre d'octets donné et ne sautent pas la `BOM'.

Dans certains cas, il est également d'usage d'utiliser une `BOM' au début des fichiers encodés en UTF-8 ; le nom est trompeur puisque l'UTF-8 ne dépend pas de l'ordre des octets. La marque annonce simplement que le fichier est encodé en UTF-8. Pour lire ces fichiers, utilisez le codec @code{utf-8-sig} pour sauter automatiquement la marque si elle est présente.

@menu
* Noms de fichiers Unicode:: 
* Conseils pour écrire des programmes compatibles Unicode:: 
* Références: Références<6>. 

@end menu

@node Noms de fichiers Unicode,Conseils pour écrire des programmes compatibles Unicode,,Lecture et écriture de données Unicode
@anchor{howto/unicode unicode-filenames}@anchor{4ec6}
@subsubsection Noms de fichiers Unicode


La plupart des systèmes d'exploitation couramment utilisés aujourd'hui prennent en charge les noms de fichiers qui contiennent des caractères Unicode arbitraires. Habituellement, ceci est implémenté en convertissant la chaîne Unicode en un encodage qui varie en fonction du système. Aujourd'hui, Python converge vers l'utilisation d'UTF-8 : Python sous MacOS utilise UTF-8 depuis plusieurs versions et Python 3.6 sous Windows est passé à UTF-8 également. Sur les systèmes Unix, il n'y aura un @ref{525,,encodage pour le système de fichiers} que si vous avez défini les variables d'environnement @code{LANG} ou @code{LC_CTYPE} ; sinon, l'encodage par défaut est UTF-8.

La fonction @ref{c47,,sys.getfilesystemencoding()} renvoie l'encodage à utiliser sur votre système actuel, au cas où vous voudriez faire l'encodage manuellement, mais il n'y a pas vraiment de raisons de s'embêter avec ça. Lors de l'ouverture d'un fichier pour la lecture ou l'écriture, vous pouvez généralement simplement fournir la chaîne Unicode comme nom de fichier et elle est automatiquement convertie à l'encodage qui convient :

@example
filename = 'filename\u4500abc'
with open(filename, 'w') as f:
    f.write('blah\n')
@end example

Les fonctions du module @ref{a0,,os} telles que @ref{48a,,os.stat()} acceptent également les noms de fichiers Unicode.

La fonction @ref{10da,,os.listdir()} renvoie des noms de fichiers, ce qui soulève un problème : doit-elle renvoyer la version Unicode des noms de fichiers ou doit-elle renvoyer des chaînes d'octets contenant les versions encodées ? @ref{10da,,os.listdir()} peut faire les deux, selon que vous fournissez le chemin du répertoire en chaîne d'octets ou en chaîne Unicode. Si vous passez une chaîne Unicode comme chemin d'accès, les noms de fichiers sont décodés en utilisant l'encodage du système de fichiers et une liste de chaînes Unicode est renvoyée, tandis que passer un chemin d'accès en chaîne d'octets renvoie les noms de fichiers comme chaîne d'octets. Par exemple, en supposant que l'@ref{525,,encodage par défaut du système de fichiers} est UTF-8, exécuter le programme suivant :

@example
fn = 'filename\u4500abc'
f = open(fn, 'w')
f.close()

import os
print(os.listdir(b'.'))
print(os.listdir('.'))
@end example

produit la sortie suivante :

@example
$ python listdir-test.py
[b'filename\xe4\x94\x80abc', ...]
['filename\u4500abc', ...]
@end example

La première liste contient les noms de fichiers encodés en UTF-8 et la seconde contient les versions Unicode.

Notez que, dans la plupart des cas, il convient de vous en tenir à l'utilisation d'Unicode avec ces `APIs'. Les `API' d'octets ne devraient être utilisées que sur les systèmes où des noms de fichiers non décodables peuvent être présents. Cela ne concerne pratiquement que des systèmes Unix maintenant.

@node Conseils pour écrire des programmes compatibles Unicode,Références<6>,Noms de fichiers Unicode,Lecture et écriture de données Unicode
@anchor{howto/unicode tips-for-writing-unicode-aware-programs}@anchor{4ec7}
@subsubsection Conseils pour écrire des programmes compatibles Unicode


Cette section fournit quelques suggestions sur l'écriture de logiciels qui traitent de l'Unicode.

Le conseil le plus important est :

@quotation

Il convient que le logiciel ne traite que des chaînes Unicode en interne, décodant les données d'entrée dès que possible et encodant la sortie uniquement à la fin.
@end quotation

Si vous essayez d'écrire des fonctions de traitement qui acceptent à la fois les chaînes Unicode et les chaînes d'octets, les possibilités d'occurrences de bogues dans votre programme augmentent partout où vous combinez les deux différents types de chaînes. Il n'y a pas d'encodage ou de décodage automatique : si vous faites par exemple @code{str + octets}, une @ref{522,,TypeError} est levée.

Lors de l'utilisation de données provenant d'un navigateur Web ou d'une autre source non fiable, une technique courante consiste à vérifier la présence de caractères illégaux dans une chaîne de caractères avant de l'utiliser pour générer une ligne de commande ou de la stocker dans une base de données. Si vous le faites, vérifiez bien la chaîne décodée, pas les données d'octets codés ; certains encodages peuvent avoir des propriétés intéressantes, comme ne pas être bijectifs ou ne pas être entièrement compatibles avec l'ASCII. C'est particulièrement vrai si l'encodage est spécifié explicitement dans vos données d'entrée, car l'attaquant peut alors choisir un moyen intelligent de cacher du texte malveillant dans le flux de données encodé.

@menu
* Conversion entre les encodages de fichiers:: 
* Fichiers dans un encodage inconnu:: 

@end menu

@node Conversion entre les encodages de fichiers,Fichiers dans un encodage inconnu,,Conseils pour écrire des programmes compatibles Unicode
@anchor{howto/unicode converting-between-file-encodings}@anchor{4ec8}
@subsubsection Conversion entre les encodages de fichiers


La classe @ref{197f,,StreamRecoder} peut convertir de manière transparente entre les encodages : prenant un flux qui renvoie des données dans l'encodage #1, elle se comporte comme un flux qui renvoie des données dans l'encodage #2.

Par exemple, si vous avez un fichier d'entrée `f' qui est en Latin-1, vous pouvez l'encapsuler dans un @ref{197f,,StreamRecoder} pour qu'il renvoie des octets encodés en UTF-8 :

@example
new_f = codecs.StreamRecoder(f,
    # en/decoder: used by read() to encode its results and
    # by write() to decode its input.
    codecs.getencoder('utf-8'), codecs.getdecoder('utf-8'),

    # reader/writer: used to read and write to the stream.
    codecs.getreader('latin-1'), codecs.getwriter('latin-1') )
@end example

@node Fichiers dans un encodage inconnu,,Conversion entre les encodages de fichiers,Conseils pour écrire des programmes compatibles Unicode
@anchor{howto/unicode files-in-an-unknown-encoding}@anchor{4ec9}
@subsubsection Fichiers dans un encodage inconnu


Vous avez besoin de modifier un fichier, mais vous ne connaissez pas son encodage ? Si vous savez que l'encodage est compatible ASCII et que vous voulez seulement examiner ou modifier les parties ASCII, vous pouvez ouvrir le fichier avec le gestionnaire d'erreurs @code{surrogateescape} :

@example
with open(fname, 'r', encoding="ascii", errors="surrogateescape") as f:
    data = f.read()

# make changes to the string 'data'

with open(fname + '.new', 'w',
          encoding="ascii", errors="surrogateescape") as f:
    f.write(data)
@end example

Le gestionnaire d'erreurs @code{surrogateescape} décode tous les octets non-ASCII comme points de code dans une plage spéciale allant de @code{U+DC80} à @code{U+DCFF}. Ces points de code redeviennent alors les mêmes octets lorsque le gestionnaire d'erreurs @code{surrogateescape} est utilisé pour encoder les données et les réécrire.

@node Références<6>,,Conseils pour écrire des programmes compatibles Unicode,Lecture et écriture de données Unicode
@anchor{howto/unicode id3}@anchor{4eca}
@subsubsection Références


Une partie de la conférence Mastering Python 3 Input/Output@footnote{https://pyvideo.org/video/289/pycon-2010--mastering-python-3-i-o} (ressource en anglais), donnée lors de `PyCon' 2010 de David Beazley, parle du traitement de texte et du traitement des données binaires.

Le PDF du diaporama de la présentation de Marc-André Lemburg "Writing Unicodeaware Applications in Python"@footnote{https://downloads.egenix.com/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf} (ressource en anglais) traite des questions d'encodage de caractères ainsi que de l'internationalisation et de la localisation d'une application. Ces diapositives ne couvrent que Python 2.x.

The Guts of Unicode in Python@footnote{https://pyvideo.org/video/1768/the-guts-of-unicode-in-python} (ressource en anglais) est une conférence `PyCon' 2013 donnée par Benjamin Peterson qui traite de la représentation interne Unicode en Python 3.3.

@node Remerciements<10>,,Lecture et écriture de données Unicode,Guide Unicode
@anchor{howto/unicode acknowledgements}@anchor{4ecb}
@subsection Remerciements


La première ébauche de ce document a été rédigée par Andrew Kuchling. Il a depuis été révisé par Alexander Belopolsky, Georg Brandl, Andrew Kuchling et Ezio Melotti.

Merci aux personnes suivantes qui ont noté des erreurs ou qui ont fait des suggestions sur cet article : Éric Araujo, Nicholas Bastin, Nick Coghlan, Marius Gedminas, Kent Johnson, Ken Krugler, Marc-André Lemburg, Martin von Löwis, Terry J. Reedy, Serhiy Storchaka, Eryk Sun, Chad Whitacre, Graham Wideman.

@node Guide pratique récupérer des ressources web en utilisant le module urllib,Introduction au module ipaddress,Guide Unicode,Les HOWTOs de Python
@anchor{howto/urllib2 doc}@anchor{4ecc}@anchor{howto/urllib2 howto-fetch-internet-resources-using-the-urllib-package}@anchor{4ecd}@anchor{howto/urllib2 urllib-howto}@anchor{3956}
@section Guide pratique : récupérer des ressources web en utilisant le module `urllib'


@*Auteur: 
Michael Foord@footnote{https://agileabstractions.com/}


@menu
* Introduction: Introduction<16>. 
* Fetching URLs:: 
* Gestion des exceptions: Gestion des exceptions<3>. 
* info and geturl:: 
* Openers and Handlers:: 
* Basic Authentication:: 
* Proxies:: 
* Sockets and Layers:: 
* Notes: Notes<3>. 

@end menu

@node Introduction<16>,Fetching URLs,,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 introduction}@anchor{4ece}
@subsection Introduction


@subsubheading Related Articles



You may also find useful the following article on fetching web resources
with Python:


@itemize *

@item 
Basic Authentication@footnote{https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml}

@quotation

A tutorial on `Basic Authentication', with examples in Python.
@end quotation
@end itemize

`urllib.request' is a Python module for fetching URLs
(Uniform Resource Locators). It offers a very simple interface, in the form of
the `urlopen' function. This is capable of fetching URLs using a variety of
different protocols. It also offers a slightly more complex interface for
handling common situations - like basic authentication, cookies, proxies and so
on. These are provided by objects called handlers and openers.

urllib.request supports fetching URLs for many "URL schemes" (identified by the string
before the @code{":"} in URL - for example @code{"ftp"} is the URL scheme of
@code{"ftp://python.org/"}) using their associated network protocols (e.g. FTP, HTTP).
This tutorial focuses on the most common case, HTTP.

For straightforward situations `urlopen' is very easy to use. But as soon as you
encounter errors or non-trivial cases when opening HTTP URLs, you will need some
understanding of the HyperText Transfer Protocol. The most comprehensive and
authoritative reference to HTTP is 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}. This is a technical document and
not intended to be easy to read. This HOWTO aims to illustrate using `urllib',
with enough detail about HTTP to help you through. It is not intended to replace
the @ref{10a,,urllib.request} docs, but is supplementary to them.

@node Fetching URLs,Gestion des exceptions<3>,Introduction<16>,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 fetching-urls}@anchor{4ecf}
@subsection Fetching URLs


The simplest way to use urllib.request is as follows:

@example
import urllib.request
with urllib.request.urlopen('http://python.org/') as response:
   html = response.read()
@end example

If you wish to retrieve a resource via URL and store it in a temporary
location, you can do so via the @ref{a4b,,shutil.copyfileobj()} and
@ref{4af,,tempfile.NamedTemporaryFile()} functions:

@example
import shutil
import tempfile
import urllib.request

with urllib.request.urlopen('http://python.org/') as response:
    with tempfile.NamedTemporaryFile(delete=False) as tmp_file:
        shutil.copyfileobj(response, tmp_file)

with open(tmp_file.name) as html:
    pass
@end example

Many uses of urllib will be that simple (note that instead of an 'http:' URL we
could have used a URL starting with 'ftp:', 'file:', etc.).  However, it's the
purpose of this tutorial to explain the more complicated cases, concentrating on
HTTP.

HTTP is based on requests and responses - the client makes requests and servers
send responses. urllib.request mirrors this with a @code{Request} object which represents
the HTTP request you are making. In its simplest form you create a Request
object that specifies the URL you want to fetch. Calling @code{urlopen} with this
Request object returns a response object for the URL requested. This response is
a file-like object, which means you can for example call @code{.read()} on the
response:

@example
import urllib.request

req = urllib.request.Request('http://python.org/')
with urllib.request.urlopen(req) as response:
   the_page = response.read()
@end example

Note that urllib.request makes use of the same Request interface to handle all URL
schemes.  For example, you can make an FTP request like so:

@example
req = urllib.request.Request('ftp://example.com/')
@end example

In the case of HTTP, there are two extra things that Request objects allow you
to do: First, you can pass data to be sent to the server.  Second, you can pass
extra information ("metadata") `about' the data or about the request itself, to
the server - this information is sent as HTTP "headers".  Let's look at each of
these in turn.

@menu
* Data:: 
* Headers:: 

@end menu

@node Data,Headers,,Fetching URLs
@anchor{howto/urllib2 data}@anchor{4ed0}
@subsubsection Data


Sometimes you want to send data to a URL (often the URL will refer to a CGI
(Common Gateway Interface) script or other web application). With HTTP,
this is often done using what's known as a `POST' request. This is often what
your browser does when you submit a HTML form that you filled in on the web. Not
all POSTs have to come from forms: you can use a POST to transmit arbitrary data
to your own application. In the common case of HTML forms, the data needs to be
encoded in a standard way, and then passed to the Request object as the @code{data}
argument. The encoding is done using a function from the @ref{109,,urllib.parse}
library.

@example
import urllib.parse
import urllib.request

url = 'http://www.someserver.com/cgi-bin/register.cgi'
values = @{'name' : 'Michael Foord',
          'location' : 'Northampton',
          'language' : 'Python' @}

data = urllib.parse.urlencode(values)
data = data.encode('ascii') # data should be bytes
req = urllib.request.Request(url, data)
with urllib.request.urlopen(req) as response:
   the_page = response.read()
@end example

Note that other encodings are sometimes required (e.g. for file upload from HTML
forms - see HTML Specification@comma{} Form Submission@footnote{https://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13} for more
details).

If you do not pass the @code{data} argument, urllib uses a `GET' request. One
way in which GET and POST requests differ is that POST requests often have
"side-effects": they change the state of the system in some way (for example by
placing an order with the website for a hundredweight of tinned spam to be
delivered to your door).  Though the HTTP standard makes it clear that POSTs are
intended to `always' cause side-effects, and GET requests `never' to cause
side-effects, nothing prevents a GET request from having side-effects, nor a
POST requests from having no side-effects. Data can also be passed in an HTTP
GET request by encoding it in the URL itself.

This is done as follows:

@example
>>> import urllib.request
>>> import urllib.parse
>>> data = @{@}
>>> data['name'] = 'Somebody Here'
>>> data['location'] = 'Northampton'
>>> data['language'] = 'Python'
>>> url_values = urllib.parse.urlencode(data)
>>> print(url_values)  # The order may differ from below.  
name=Somebody+Here&language=Python&location=Northampton
>>> url = 'http://www.example.com/example.cgi'
>>> full_url = url + '?' + url_values
>>> data = urllib.request.urlopen(full_url)
@end example

Notice that the full URL is created by adding a @code{?} to the URL, followed by
the encoded values.

@node Headers,,Data,Fetching URLs
@anchor{howto/urllib2 headers}@anchor{4ed1}
@subsubsection Headers


We'll discuss here one particular HTTP header, to illustrate how to add headers
to your HTTP request.

Some websites @footnote{
Google for example.
} dislike being browsed by programs, or send different versions
to different browsers @footnote{
Browser sniffing is a very bad practice for website design - building
sites using web standards is much more sensible. Unfortunately a lot of
sites still send different versions to different browsers.
}. By default urllib identifies itself as
@code{Python-urllib/x.y} (where @code{x} and @code{y} are the major and minor version
numbers of the Python release,
e.g. @code{Python-urllib/2.5}), which may confuse the site, or just plain
not work. The way a browser identifies itself is through the
@code{User-Agent} header @footnote{
The user agent for MSIE 6 is
`'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)''
}. When you create a Request object you can
pass a dictionary of headers in. The following example makes the same
request as above, but identifies itself as a version of Internet
Explorer @footnote{
For details of more HTTP request headers, see
@uref{https://jkorpela.fi/http.html,Quick Reference to HTTP Headers}.
}.

@example
import urllib.parse
import urllib.request

url = 'http://www.someserver.com/cgi-bin/register.cgi'
user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'
values = @{'name': 'Michael Foord',
          'location': 'Northampton',
          'language': 'Python' @}
headers = @{'User-Agent': user_agent@}

data = urllib.parse.urlencode(values)
data = data.encode('ascii')
req = urllib.request.Request(url, data, headers)
with urllib.request.urlopen(req) as response:
   the_page = response.read()
@end example

The response also has two useful methods. See the section on @ref{4ed2,,info and geturl}
which comes after we have a look at what happens when things go wrong.

@node Gestion des exceptions<3>,info and geturl,Fetching URLs,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 handling-exceptions}@anchor{4ed3}
@subsection Gestion des exceptions


`urlopen' raises @ref{38e1,,URLError} when it cannot handle a response (though as
usual with Python APIs, built-in exceptions such as @ref{1ff,,ValueError},
@ref{522,,TypeError} etc. may also be raised).

@ref{fc9,,HTTPError} is the subclass of @ref{38e1,,URLError} raised in the specific case of
HTTP URLs.

The exception classes are exported from the @ref{108,,urllib.error} module.

@menu
* URLError:: 
* HTTPError:: 
* Wrapping it Up:: 

@end menu

@node URLError,HTTPError,,Gestion des exceptions<3>
@anchor{howto/urllib2 urlerror}@anchor{4ed4}
@subsubsection URLError


Often, URLError is raised because there is no network connection (no route to
the specified server), or the specified server doesn't exist.  In this case, the
exception raised will have a 'reason' attribute, which is a tuple containing an
error code and a text error message.

e.g.

@example
>>> req = urllib.request.Request('http://www.pretend_server.org')
>>> try: urllib.request.urlopen(req)
... except urllib.error.URLError as e:
...     print(e.reason)      
...
(4, 'getaddrinfo failed')
@end example

@node HTTPError,Wrapping it Up,URLError,Gestion des exceptions<3>
@anchor{howto/urllib2 httperror}@anchor{4ed5}
@subsubsection HTTPError


Every HTTP response from the server contains a numeric "status code". Sometimes
the status code indicates that the server is unable to fulfil the request. The
default handlers will handle some of these responses for you (for example, if
the response is a "redirection" that requests the client fetch the document from
a different URL, urllib will handle that for you). For those it can't handle,
urlopen will raise an @ref{fc9,,HTTPError}. Typical errors include '404' (page not
found), '403' (request forbidden), and '401' (authentication required).

See section 10 of 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html} for a reference on all the HTTP error codes.

The @ref{fc9,,HTTPError} instance raised will have an integer 'code' attribute, which
corresponds to the error sent by the server.

@menu
* Error Codes:: 

@end menu

@node Error Codes,,,HTTPError
@anchor{howto/urllib2 error-codes}@anchor{4ed6}
@subsubsection Error Codes


Because the default handlers handle redirects (codes in the 300 range), and
codes in the 100--299 range indicate success, you will usually only see error
codes in the 400--599 range.

@ref{397f,,http.server.BaseHTTPRequestHandler.responses} is a useful dictionary of
response codes in that shows all the response codes used by 
@geindex RFC; RFC 2616
RFC 2616@footnote{https://datatracker.ietf.org/doc/html/rfc2616.html}. The
dictionary is reproduced here for convenience

@example
# Table mapping response codes to messages; entries have the
# form @{code: (shortmessage, longmessage)@}.
responses = @{
    100: ('Continue', 'Request received, please continue'),
    101: ('Switching Protocols',
          'Switching to new protocol; obey Upgrade header'),

    200: ('OK', 'Request fulfilled, document follows'),
    201: ('Created', 'Document created, URL follows'),
    202: ('Accepted',
          'Request accepted, processing continues off-line'),
    203: ('Non-Authoritative Information', 'Request fulfilled from cache'),
    204: ('No Content', 'Request fulfilled, nothing follows'),
    205: ('Reset Content', 'Clear input form for further input.'),
    206: ('Partial Content', 'Partial content follows.'),

    300: ('Multiple Choices',
          'Object has several resources -- see URI list'),
    301: ('Moved Permanently', 'Object moved permanently -- see URI list'),
    302: ('Found', 'Object moved temporarily -- see URI list'),
    303: ('See Other', 'Object moved -- see Method and URL list'),
    304: ('Not Modified',
          'Document has not changed since given time'),
    305: ('Use Proxy',
          'You must use proxy specified in Location to access this '
          'resource.'),
    307: ('Temporary Redirect',
          'Object moved temporarily -- see URI list'),

    400: ('Bad Request',
          'Bad request syntax or unsupported method'),
    401: ('Unauthorized',
          'No permission -- see authorization schemes'),
    402: ('Payment Required',
          'No payment -- see charging schemes'),
    403: ('Forbidden',
          'Request forbidden -- authorization will not help'),
    404: ('Not Found', 'Nothing matches the given URI'),
    405: ('Method Not Allowed',
          'Specified method is invalid for this server.'),
    406: ('Not Acceptable', 'URI not available in preferred format.'),
    407: ('Proxy Authentication Required', 'You must authenticate with '
          'this proxy before proceeding.'),
    408: ('Request Timeout', 'Request timed out; try again later.'),
    409: ('Conflict', 'Request conflict.'),
    410: ('Gone',
          'URI no longer exists and has been permanently removed.'),
    411: ('Length Required', 'Client must specify Content-Length.'),
    412: ('Precondition Failed', 'Precondition in headers is false.'),
    413: ('Request Entity Too Large', 'Entity is too large.'),
    414: ('Request-URI Too Long', 'URI is too long.'),
    415: ('Unsupported Media Type', 'Entity body in unsupported format.'),
    416: ('Requested Range Not Satisfiable',
          'Cannot satisfy request range.'),
    417: ('Expectation Failed',
          'Expect condition could not be satisfied.'),

    500: ('Internal Server Error', 'Server got itself in trouble'),
    501: ('Not Implemented',
          'Server does not support this operation'),
    502: ('Bad Gateway', 'Invalid responses from another server/proxy.'),
    503: ('Service Unavailable',
          'The server cannot process the request due to a high load'),
    504: ('Gateway Timeout',
          'The gateway server did not receive a timely response'),
    505: ('HTTP Version Not Supported', 'Cannot fulfill request.'),
    @}
@end example

When an error is raised the server responds by returning an HTTP error code
`and' an error page. You can use the @ref{fc9,,HTTPError} instance as a response on the
page returned. This means that as well as the code attribute, it also has read,
geturl, and info, methods as returned by the @code{urllib.response} module:

@example
>>> req = urllib.request.Request('http://www.python.org/fish.html')
>>> try:
...     urllib.request.urlopen(req)
... except urllib.error.HTTPError as e:
...     print(e.code)
...     print(e.read())  
...
404
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
  ...
  <title>Page Not Found</title>\n
  ...
@end example

@node Wrapping it Up,,HTTPError,Gestion des exceptions<3>
@anchor{howto/urllib2 wrapping-it-up}@anchor{4ed7}
@subsubsection Wrapping it Up


So if you want to be prepared for @ref{fc9,,HTTPError} `or' @ref{38e1,,URLError} there are two
basic approaches. I prefer the second approach.

@menu
* Number 1:: 
* Number 2:: 

@end menu

@node Number 1,Number 2,,Wrapping it Up
@anchor{howto/urllib2 number-1}@anchor{4ed8}
@subsubsection Number 1


@example
from urllib.request import Request, urlopen
from urllib.error import URLError, HTTPError
req = Request(someurl)
try:
    response = urlopen(req)
except HTTPError as e:
    print('The server couldn\'t fulfill the request.')
    print('Error code: ', e.code)
except URLError as e:
    print('We failed to reach a server.')
    print('Reason: ', e.reason)
else:
    # everything is fine
@end example

@cartouche
@quotation Note 
The @code{except HTTPError} `must' come first, otherwise @code{except URLError}
will `also' catch an @ref{fc9,,HTTPError}.
@end quotation
@end cartouche

@node Number 2,,Number 1,Wrapping it Up
@anchor{howto/urllib2 number-2}@anchor{4ed9}
@subsubsection Number 2


@example
from urllib.request import Request, urlopen
from urllib.error import URLError
req = Request(someurl)
try:
    response = urlopen(req)
except URLError as e:
    if hasattr(e, 'reason'):
        print('We failed to reach a server.')
        print('Reason: ', e.reason)
    elif hasattr(e, 'code'):
        print('The server couldn\'t fulfill the request.')
        print('Error code: ', e.code)
else:
    # everything is fine
@end example

@node info and geturl,Openers and Handlers,Gestion des exceptions<3>,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 info-and-geturl}@anchor{4ed2}
@subsection info and geturl


The response returned by urlopen (or the @ref{fc9,,HTTPError} instance) has two
useful methods @code{info()} and @code{geturl()} and is defined in the module
@ref{10b,,urllib.response}.


@itemize *

@item 
`geturl' - this returns the real URL of the page fetched. This is useful
because @code{urlopen} (or the opener object used) may have followed a
redirect. The URL of the page fetched may not be the same as the URL requested.

@item 
`info' - this returns a dictionary-like object that describes the page
fetched, particularly the headers sent by the server. It is currently an
@ref{3996,,http.client.HTTPMessage} instance.
@end itemize

Typical headers include 'Content-length', 'Content-type', and so on. See the
Quick Reference to HTTP Headers@footnote{https://jkorpela.fi/http.html}
for a useful listing of HTTP headers with brief explanations of their meaning
and use.

@node Openers and Handlers,Basic Authentication,info and geturl,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 openers-and-handlers}@anchor{4eda}
@subsection Openers and Handlers


When you fetch a URL you use an opener (an instance of the perhaps
confusingly named @ref{38e2,,urllib.request.OpenerDirector}). Normally we have been using
the default opener - via @code{urlopen} - but you can create custom
openers. Openers use handlers. All the "heavy lifting" is done by the
handlers. Each handler knows how to open URLs for a particular URL scheme (http,
ftp, etc.), or how to handle an aspect of URL opening, for example HTTP
redirections or HTTP cookies.

You will want to create openers if you want to fetch URLs with specific handlers
installed, for example to get an opener that handles cookies, or to get an
opener that does not handle redirections.

To create an opener, instantiate an @code{OpenerDirector}, and then call
@code{.add_handler(some_handler_instance)} repeatedly.

Alternatively, you can use @code{build_opener}, which is a convenience function for
creating opener objects with a single function call.  @code{build_opener} adds
several handlers by default, but provides a quick way to add more and/or
override the default handlers.

Other sorts of handlers you might want to can handle proxies, authentication,
and other common but slightly specialised situations.

@code{install_opener} can be used to make an @code{opener} object the (global) default
opener. This means that calls to @code{urlopen} will use the opener you have
installed.

Opener objects have an @code{open} method, which can be called directly to fetch
urls in the same way as the @code{urlopen} function: there's no need to call
@code{install_opener}, except as a convenience.

@node Basic Authentication,Proxies,Openers and Handlers,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 id5}@anchor{4edb}
@subsection Basic Authentication


To illustrate creating and installing a handler we will use the
@code{HTTPBasicAuthHandler}. For a more detailed discussion of this subject --
including an explanation of how Basic Authentication works - see the Basic Authentication Tutorial@footnote{https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml}.

When authentication is required, the server sends a header (as well as the 401
error code) requesting authentication.  This specifies the authentication scheme
and a 'realm'. The header looks like: @code{WWW-Authenticate: SCHEME
realm="REALM"}.

e.g.

@example
WWW-Authenticate: Basic realm="cPanel Users"
@end example

The client should then retry the request with the appropriate name and password
for the realm included as a header in the request. This is 'basic
authentication'. In order to simplify this process we can create an instance of
@code{HTTPBasicAuthHandler} and an opener to use this handler.

The @code{HTTPBasicAuthHandler} uses an object called a password manager to handle
the mapping of URLs and realms to passwords and usernames. If you know what the
realm is (from the authentication header sent by the server), then you can use a
@code{HTTPPasswordMgr}. Frequently one doesn't care what the realm is. In that
case, it is convenient to use @code{HTTPPasswordMgrWithDefaultRealm}. This allows
you to specify a default username and password for a URL. This will be supplied
in the absence of you providing an alternative combination for a specific
realm. We indicate this by providing @code{None} as the realm argument to the
@code{add_password} method.

The top-level URL is the first URL that requires authentication. URLs "deeper"
than the URL you pass to .add_password() will also match.

@example
# create a password manager
password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()

# Add the username and password.
# If we knew the realm, we could use it instead of None.
top_level_url = "http://example.com/foo/"
password_mgr.add_password(None, top_level_url, username, password)

handler = urllib.request.HTTPBasicAuthHandler(password_mgr)

# create "opener" (OpenerDirector instance)
opener = urllib.request.build_opener(handler)

# use the opener to fetch a URL
opener.open(a_url)

# Install the opener.
# Now all calls to urllib.request.urlopen use our opener.
urllib.request.install_opener(opener)
@end example

@cartouche
@quotation Note 
In the above example we only supplied our @code{HTTPBasicAuthHandler} to
@code{build_opener}. By default openers have the handlers for normal situations
-- @code{ProxyHandler} (if a proxy setting such as an @code{http_proxy}
environment variable is set), @code{UnknownHandler}, @code{HTTPHandler},
@code{HTTPDefaultErrorHandler}, @code{HTTPRedirectHandler}, @code{FTPHandler},
@code{FileHandler}, @code{DataHandler}, @code{HTTPErrorProcessor}.
@end quotation
@end cartouche

@code{top_level_url} is in fact `either' a full URL (including the 'http:' scheme
component and the hostname and optionally the port number)
e.g. @code{"http://example.com/"} `or' an "authority" (i.e. the hostname,
optionally including the port number) e.g. @code{"example.com"} or @code{"example.com:8080"}
(the latter example includes a port number).  The authority, if present, must
NOT contain the "userinfo" component - for example @code{"joe:password@@example.com"} is
not correct.

@node Proxies,Sockets and Layers,Basic Authentication,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 proxies}@anchor{4edc}
@subsection Proxies


`urllib' will auto-detect your proxy settings and use those. This is through
the @code{ProxyHandler}, which is part of the normal handler chain when a proxy
setting is detected.  Normally that's a good thing, but there are occasions
when it may not be helpful @footnote{
In my case I have to use a proxy to access the internet at work. If you
attempt to fetch `localhost' URLs through this proxy it blocks them. IE
is set to use the proxy, which urllib picks up on. In order to test
scripts with a localhost server, I have to prevent urllib from using
the proxy.
}. One way to do this is to setup our own
@code{ProxyHandler}, with no proxies defined. This is done using similar steps to
setting up a Basic Authentication@footnote{https://web.archive.org/web/20201215133350/http://www.voidspace.org.uk/python/articles/authentication.shtml} handler:

@example
>>> proxy_support = urllib.request.ProxyHandler(@{@})
>>> opener = urllib.request.build_opener(proxy_support)
>>> urllib.request.install_opener(opener)
@end example

@cartouche
@quotation Note 
Currently @code{urllib.request} `does not' support fetching of @code{https} locations
through a proxy.  However, this can be enabled by extending urllib.request as
shown in the recipe @footnote{
urllib opener for SSL proxy (CONNECT method): @uref{https://code.activestate.com/recipes/456195-urrlib2-opener-for-ssl-proxy-connect-method/,ASPN Cookbook Recipe}.
}.
@end quotation
@end cartouche

@cartouche
@quotation Note 
@code{HTTP_PROXY} will be ignored if a variable @code{REQUEST_METHOD} is set; see
the documentation on @ref{38de,,getproxies()}.
@end quotation
@end cartouche

@node Sockets and Layers,Notes<3>,Proxies,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 sockets-and-layers}@anchor{4edd}
@subsection Sockets and Layers


The Python support for fetching resources from the web is layered.  urllib uses
the @ref{6e,,http.client} library, which in turn uses the socket library.

As of Python 2.3 you can specify how long a socket should wait for a response
before timing out. This can be useful in applications which have to fetch web
pages. By default the socket module has `no timeout' and can hang. Currently,
the socket timeout is not exposed at the http.client or urllib.request levels.
However, you can set the default timeout globally for all sockets using

@example
import socket
import urllib.request

# timeout in seconds
timeout = 10
socket.setdefaulttimeout(timeout)

# this call to urllib.request.urlopen now uses the default timeout
# we have set in the socket module
req = urllib.request.Request('http://www.voidspace.org.uk')
response = urllib.request.urlopen(req)
@end example


__________________________________________________________________


@node Notes<3>,,Sockets and Layers,Guide pratique récupérer des ressources web en utilisant le module urllib
@anchor{howto/urllib2 footnotes}@anchor{4ede}
@subsection Notes


This document was reviewed and revised by John Lee.

@c import ipaddress

@node Introduction au module ipaddress,Instrumenter CPython avec DTrace et SystemTap,Guide pratique récupérer des ressources web en utilisant le module urllib,Les HOWTOs de Python
@anchor{howto/ipaddress doc}@anchor{4edf}@anchor{howto/ipaddress an-introduction-to-the-ipaddress-module}@anchor{4ee0}@anchor{howto/ipaddress ipaddress-howto}@anchor{3b7c}
@section Introduction au module @code{ipaddress}


@*auteur: 
Peter Moody


@*auteur: 
Nick Coghlan


@subsubheading Aperçu



Ce document vise à fournir une introduction rapide au module @ref{7f,,ipaddress}. Il est destiné aux utilisateurs qui ne sont pas familiers avec la terminologie des réseaux IP, mais il peut aussi être utile aux ingénieurs réseaux qui cherchent un aperçu de la représentation des concepts d'adressage IP avec le module @ref{7f,,ipaddress}.

@menu
* Créer un objet Adresse/Réseau/Interface:: 
* Inspecter les objets Address/Network/Interface:: 
* Réseaux en tant que listes d'adresses:: 
* Comparaisons: Comparaisons<4>. 
* Utiliser des adresse IP avec d'autre modules:: 
* Obtenir plus de détails lors de l'échec de la création de l'instance:: 

@end menu

@node Créer un objet Adresse/Réseau/Interface,Inspecter les objets Address/Network/Interface,,Introduction au module ipaddress
@anchor{howto/ipaddress creating-address-network-interface-objects}@anchor{4ee1}
@subsection Créer un objet Adresse/Réseau/Interface


Vu que @ref{7f,,ipaddress} est un module pour inspecter et manipuler des adresses IP, la première chose que vous voudrez faire est de créer quelques objets. Vous pouvez utiliser @ref{7f,,ipaddress} pour créer des objets à partir de chaînes de caractères et d'entiers.

@menu
* Note sur les versions d'IP:: 
* Adresses IP des hôtes:: 
* Définir des réseaux:: 
* Interfaces des hôtes:: 

@end menu

@node Note sur les versions d'IP,Adresses IP des hôtes,,Créer un objet Adresse/Réseau/Interface
@anchor{howto/ipaddress a-note-on-ip-versions}@anchor{4ee2}
@subsubsection Note sur les versions d'IP


Pour les lecteurs qui ne sont pas particulièrement familiers avec l'adressage IP il est important de savoir que le `protocole Internet' (IP) est actuellement en évolution de la version 4 du protocole vers la version 6. Cette transition est largement due au fait que la version 4 du protocole ne fournit pas assez d'adresses pour gérer les besoins du monde entier, particulièrement à cause de la croissance des périphériques directement connectés à Internet.

Expliquer les détails des différences entre les deux versions du protocole est au-delà du périmètre de cette introduction, mais les lecteurs doivent au moins être avertis de l'existence de ces deux versions et qu'il sera nécessaire de forcer l'utilisation d'une version ou de l'autre.

@node Adresses IP des hôtes,Définir des réseaux,Note sur les versions d'IP,Créer un objet Adresse/Réseau/Interface
@anchor{howto/ipaddress ip-host-addresses}@anchor{4ee3}
@subsubsection Adresses IP des hôtes


Les adresses, souvent dénommées "adresses hôtes" sont les unités les plus basiques quand on travaille avec l'adressage IP. Le moyen le plus simple de créer des adresses est d'utiliser la fonction de fabrication @ref{3b7e,,ipaddress.ip_address()} qui va automatiquement déterminer quoi créer entre une adresse IPv4 ou une adresse IPv6 en fonction de la valeur qui est transmise :

@example
>>> ipaddress.ip_address('192.0.2.1')
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address('2001:DB8::1')
IPv6Address('2001:db8::1')
@end example

Les adresses peuvent être créées directement depuis des entiers. Les valeurs qui correspondent à des entiers 32 bits sont assimilées à des adresses IPv4 :

@example
>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address(42540766411282592856903984951653826561)
IPv6Address('2001:db8::1')
@end example

Pour forcer l'utilisation d'IPv4 ou d'IPv6, la classe appropriée peut être invoquée directement. C'est particulièrement utile pour forcer la création d'adresse IPv6 pour de petits entiers :

@example
>>> ipaddress.ip_address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv4Address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv6Address(1)
IPv6Address('::1')
@end example

@node Définir des réseaux,Interfaces des hôtes,Adresses IP des hôtes,Créer un objet Adresse/Réseau/Interface
@anchor{howto/ipaddress defining-networks}@anchor{4ee4}
@subsubsection Définir des réseaux


Les adresses hôtes sont souvent regroupées dans des réseaux IP, donc @ref{7f,,ipaddress} fournit un moyen de créer, d'inspecter et de manipuler les définitions des réseaux. Les objets correspondants aux réseaux IP sont construits à partir de chaînes de caractères qui définissent le périmètre des adresses hôtes qui font partie de ce réseau. La forme la plus simple de cette information est un couple "adresse réseau/préfixe réseau" , où le préfixe définit le nombre de bits de tête qui sont comparés pour déterminer si l'adresse fait ou ne fait pas partie de ce réseau et l'adresse réseau définit la valeur attendue pour ces bits.

Tout comme pour les adresses, une fonction de fabrication est disponible et détermine automatiquement la version correcte d'IP :

@example
>>> ipaddress.ip_network('192.0.2.0/24')
IPv4Network('192.0.2.0/24')
>>> ipaddress.ip_network('2001:db8::0/96')
IPv6Network('2001:db8::/96')
@end example

Il est interdit pour des objets réseaux d'avoir des bits affectés à leurs hôtes mis à 1. Ainsi la chaîne de caractères @code{192.0.2.1/24} ne peut définir un réseau. Ces objets réseaux sont aussi appelés objets d'interfaces car la notation @code{adresse ip / réseau} est couramment utilisée pour décrire les interfaces réseau d'un ordinateur sur un réseau donné (nous les détaillons plus loin dans cette section).

Par défaut, tenter de créer un objet réseau avec des bits d'hôtes mis à 1 lève une @ref{1ff,,ValueError}. Pour demander que les bits supplémentaires soient plutôt forcés à zéro, l'attribut @code{strict=False} peut être passé au constructeur :

@example
>>> ipaddress.ip_network('192.0.2.1/24')
Traceback (most recent call last):
   ...
ValueError: 192.0.2.1/24 has host bits set
>>> ipaddress.ip_network('192.0.2.1/24', strict=False)
IPv4Network('192.0.2.0/24')
@end example

Alors que la forme textuelle offre davantage de flexibilité les réseaux peuvent aussi être définis avec des entiers, tout comme les adresses hôtes. Dans ce cas le réseau est considéré comme contenant uniquement l'adresse identifiée par l'entier, donc le préfixe réseau inclut l'adresse du réseau complet :

@example
>>> ipaddress.ip_network(3221225984)
IPv4Network('192.0.2.0/32')
>>> ipaddress.ip_network(42540766411282592856903984951653826560)
IPv6Network('2001:db8::/128')
@end example

Comme avec les adresses, la création d'un type de réseau particulier peut être forcée en appelant directement le constructeur de la classe plutôt que d'utiliser la fonction de fabrication.

@node Interfaces des hôtes,,Définir des réseaux,Créer un objet Adresse/Réseau/Interface
@anchor{howto/ipaddress host-interfaces}@anchor{4ee5}
@subsubsection Interfaces des hôtes


Comme mentionné ci-dessus, si vous avez besoin de décrire une adresse sur un réseau particulier, ni l'adresse ni les classes réseaux ne sont suffisantes. Les notations comme @code{192.0.2.1/24} sont généralement utilisées par les ingénieurs réseaux et les personnes qui écrivent des outils pour les pare-feu et les routeurs comme raccourci pour " l'hôte @code{192.0.2.1} sur le réseau  @code{192.0.2.0/24}", par conséquent, @ref{7f,,ipaddress} fournit un ensemble de classes hybrides qui associent une adresse à un réseau particulier. L'interface pour la création est identique à celle pour la définition des objets réseaux, excepté que la partie adresse n'est pas contrainte d'être une adresse réseau.

@example
>>> ipaddress.ip_interface('192.0.2.1/24')
IPv4Interface('192.0.2.1/24')
>>> ipaddress.ip_interface('2001:db8::1/96')
IPv6Interface('2001:db8::1/96')
@end example

Les entiers sont acceptés en entrée (comme avec les réseaux) et l'utilisation d'une version d'IP peut être forcée en appelant directement le constructeur adapté.

@node Inspecter les objets Address/Network/Interface,Réseaux en tant que listes d'adresses,Créer un objet Adresse/Réseau/Interface,Introduction au module ipaddress
@anchor{howto/ipaddress inspecting-address-network-interface-objects}@anchor{4ee6}
@subsection Inspecter les objets Address/Network/Interface


Vous vous êtes donné la peine de créer un objet (adresse|réseau|interface)IPv(4|6), donc vous voudrez probablement des informations sur celui-ci. @ref{7f,,ipaddress} essaie de rendre ceci facile et intuitif.

Extraire la version du protocole IP :

@example
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr6 = ipaddress.ip_address('2001:db8::1')
>>> addr6.version
6
>>> addr4.version
4
@end example

Obtenir le réseau à partir de l'interface :

@example
>>> host4 = ipaddress.ip_interface('192.0.2.1/24')
>>> host4.network
IPv4Network('192.0.2.0/24')
>>> host6 = ipaddress.ip_interface('2001:db8::1/96')
>>> host6.network
IPv6Network('2001:db8::/96')
@end example

Trouver combien d'adresses individuelles sont dans un réseau :

@example
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> net4.num_addresses
256
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
>>> net6.num_addresses
4294967296
@end example

Itération sur chacune des adresses "utilisables" d'un réseau :

@example
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> for x in net4.hosts():
...     print(x)  
192.0.2.1
192.0.2.2
192.0.2.3
192.0.2.4
...
192.0.2.252
192.0.2.253
192.0.2.254
@end example

Obtenir le masque réseau (définit les bits correspondant au préfixe du réseau) ou le masque de l'hôte (tous les bits qui ne sont pas dans le masque du réseau) :

@example
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> net4.netmask
IPv4Address('255.255.255.0')
>>> net4.hostmask
IPv4Address('0.0.0.255')
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
>>> net6.netmask
IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')
>>> net6.hostmask
IPv6Address('::ffff:ffff')
@end example

Éclater ou compresser l'adresse :

@example
>>> addr6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0001'
>>> addr6.compressed
'2001:db8::1'
>>> net6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0000/96'
>>> net6.compressed
'2001:db8::/96'
@end example

Alors que IPv4 ne gère pas l'éclatement ou la compression, les objets associés fournissent toujours les propriétés adaptées pour que du code, le plus neutre possible vis-à-vis de la version, puisse facilement s'assurer que la forme la plus concise ou la plus verbeuse utilisée pour des adresses IPv6 va aussi fonctionner pour gérer des adresses IPv4.

@node Réseaux en tant que listes d'adresses,Comparaisons<4>,Inspecter les objets Address/Network/Interface,Introduction au module ipaddress
@anchor{howto/ipaddress networks-as-lists-of-addresses}@anchor{4ee7}
@subsection Réseaux en tant que listes d'adresses


Il est parfois utile de traiter les réseaux en tant que listes. Cela  signifie qu'il est possible de les indexer comme ça :

@example
>>> net4[1]
IPv4Address('192.0.2.1')
>>> net4[-1]
IPv4Address('192.0.2.255')
>>> net6[1]
IPv6Address('2001:db8::1')
>>> net6[-1]
IPv6Address('2001:db8::ffff:ffff')
@end example

Cela signifie aussi que les objets réseaux se prêtent bien à l'utilisation de la syntaxe suivante pour le test d'appartenance à la liste :

@example
if address in network:
    # do something
@end example

En se basant sur le préfixe réseau on peut efficacement tester l'appartenance :

@example
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr4 in ipaddress.ip_network('192.0.2.0/24')
True
>>> addr4 in ipaddress.ip_network('192.0.3.0/24')
False
@end example

@node Comparaisons<4>,Utiliser des adresse IP avec d'autre modules,Réseaux en tant que listes d'adresses,Introduction au module ipaddress
@anchor{howto/ipaddress comparisons}@anchor{4ee8}
@subsection Comparaisons


@ref{7f,,ipaddress} fournit des moyens simples et intuitifs (du moins nous l'espérons) pour comparer les objets, quand cela fait sens :

@example
>>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')
True
@end example

Une exception @ref{522,,TypeError} est levée si vous tentez de comparer des objets de différentes versions ou de types différents.

@node Utiliser des adresse IP avec d'autre modules,Obtenir plus de détails lors de l'échec de la création de l'instance,Comparaisons<4>,Introduction au module ipaddress
@anchor{howto/ipaddress using-ip-addresses-with-other-modules}@anchor{4ee9}
@subsection Utiliser des adresse IP avec d'autre modules


Les autres modules qui utilisent des adresses IP (comme @ref{cb,,socket}) n'acceptent généralement pas les objets de ce module directement. Au lieu de cela, ils doivent être convertis en entiers ou en chaînes de caractères que l'autre module va accepter :

@example
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> str(addr4)
'192.0.2.1'
>>> int(addr4)
3221225985
@end example

@node Obtenir plus de détails lors de l'échec de la création de l'instance,,Utiliser des adresse IP avec d'autre modules,Introduction au module ipaddress
@anchor{howto/ipaddress getting-more-detail-when-instance-creation-fails}@anchor{4eea}
@subsection Obtenir plus de détails lors de l'échec de la création de l'instance


Lors de la création des objets Adresse/Réseau/Interface en utilisant les fonctions de fabrication agnostiques à la version, n'importe quelle erreur va être signalée en tant que @ref{1ff,,ValueError} avec un message d'erreur générique qui dit simplement que la valeur entrée n'a pas été reconnue en tant qu'objet de ce type. Pour fournir plus de détails sur la cause du rejet, il faudrait reconnaître si la valeur est `supposée' être une adresse IPv4 ou IPv6.

Pour gérer les cas d'usage où il est utile d'avoir accès à ces détails, les constructeurs individuels des classes lèvent actuellement les sous-classes de @ref{1ff,,ValueError}, @ref{3b83,,ipaddress.AddressValueError} et @ref{3ba5,,ipaddress.NetmaskValueError} pour indiquer précisément quelle partie de la définition n'a pas pu être correctement traitée.

Les messages d'erreur sont particulièrement plus détaillés lors de l'utilisation directe du constructeur. Par exemple :

@example
>>> ipaddress.ip_address("192.168.0.256")
Traceback (most recent call last):
  ...
ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address
>>> ipaddress.IPv4Address("192.168.0.256")
Traceback (most recent call last):
  ...
ipaddress.AddressValueError: Octet 256 (> 255) not permitted in '192.168.0.256'

>>> ipaddress.ip_network("192.168.0.1/64")
Traceback (most recent call last):
  ...
ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network
>>> ipaddress.IPv4Network("192.168.0.1/64")
Traceback (most recent call last):
  ...
ipaddress.NetmaskValueError: '64' is not a valid netmask
@end example

Cependant, les exceptions spécifiques des deux modules ont @ref{1ff,,ValueError} comme classe parent ; donc si vous n'êtes pas intéressé par le type particulier d'erreur remontée, vous pouvez écrire votre code comme suit :

@example
try:
    network = ipaddress.IPv4Network(address)
except ValueError:
    print('address/netmask is invalid for IPv4:', address)
@end example

@node Instrumenter CPython avec DTrace et SystemTap,Python support for the Linux perf profiler,Introduction au module ipaddress,Les HOWTOs de Python
@anchor{howto/instrumentation doc}@anchor{4eeb}@anchor{howto/instrumentation instrumentation}@anchor{c5a}@anchor{howto/instrumentation instrumenting-cpython-with-dtrace-and-systemtap}@anchor{4eec}
@section Instrumenter CPython avec DTrace et SystemTap


@*auteur: 
David Malcolm


@*auteur: 
Łukasz Langa


`DTrace' et `SystemTap' sont des outils de surveillance, chacun fournissant un moyen de d'inspecter ce que font les processus d'un système informatique. Ils utilisent tous les deux des langages dédiés permettant à un utilisateur d'écrire des scripts qui permettent de :


@itemize -

@item 
Filtrer les processus à observer.

@item 
Recueillir des données sur le processus choisi.

@item 
Générer des rapports sur les données.
@end itemize

À partir de Python 3.6, CPython peut être compilé avec des « marqueurs » intégrés, aussi appelés « sondes », qui peuvent être observés par un script `DTrace' ou `SystemTap', ce qui facilite le suivi des processus CPython.

`Particularité de l'implémentation CPython :' Les marqueurs DTrace sont des détails d'implémentation de l'interpréteur CPython. Aucune garantie n'est donnée quant à la compatibilité des sondes entre les versions de CPython. Les scripts DTrace peuvent s'arrêter de fonctionner ou fonctionner incorrectement sans avertissement lors du changement de version de CPython.

@menu
* Activer les marqueurs statiques:: 
* Sondes DTrace statiques:: 
* Marqueurs statiques SystemTap:: 
* Marqueurs statiques disponibles:: 
* Tapsets de SystemTap:: 
* Exemples: Exemples<38>. 

@end menu

@node Activer les marqueurs statiques,Sondes DTrace statiques,,Instrumenter CPython avec DTrace et SystemTap
@anchor{howto/instrumentation enabling-the-static-markers}@anchor{4eed}
@subsection Activer les marqueurs statiques


macOS est livré avec un support intégré pour `DTrace'. Sous Linux, pour construire CPython avec les marqueurs embarqués pour `SystemTap', les outils de développement `SystemTap' doivent être installés.

Sur une machine Linux, cela se fait via :

@example
$ yum install systemtap-sdt-devel
@end example

ou :

@example
$ sudo apt-get install systemtap-sdt-dev
@end example

CPython doit être configuré avec l'option @ref{1d41,,--with-dtrace} :

@example
checking for --with-dtrace... yes
@end example

Sous macOS, vous pouvez lister les sondes `DTrace' disponibles en exécutant un processus Python en arrière-plan et en listant toutes les sondes mises à disposition par le fournisseur Python :

@example
$ python3.6 -q &
$ sudo dtrace -l -P python$!  # or: dtrace -l -m python3.6

   ID   PROVIDER            MODULE                          FUNCTION NAME
29564 python18035        python3.6          _PyEval_EvalFrameDefault function-entry
29565 python18035        python3.6             dtrace_function_entry function-entry
29566 python18035        python3.6          _PyEval_EvalFrameDefault function-return
29567 python18035        python3.6            dtrace_function_return function-return
29568 python18035        python3.6                           collect gc-done
29569 python18035        python3.6                           collect gc-start
29570 python18035        python3.6          _PyEval_EvalFrameDefault line
29571 python18035        python3.6                 maybe_dtrace_line line
@end example

Sous Linux, pour vérifier que les marqueurs statiques `SystemTap' sont présents dans le binaire compilé, il suffit de regarder s'il contient une section @code{.note.stapsdt}.

@example
$ readelf -S ./python | grep .note.stapsdt
[30] .note.stapsdt        NOTE         0000000000000000 00308d78
@end example

Si vous avez compilé Python en tant que bibliothèque partagée (avec l'option @ref{84d,,--enable-shared} du script @code{configure}), vous devez plutôt regarder dans la bibliothèque partagée. Par exemple :

@example
$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt
[29] .note.stapsdt        NOTE         0000000000000000 00365b68
@end example

Une version suffisamment moderne de `readelf' peut afficher les métadonnées :

@example
$ readelf -n ./python

Displaying notes found at file offset 0x00000254 with length 0x00000020:
    Owner                 Data size          Description
    GNU                  0x00000010          NT_GNU_ABI_TAG (ABI version tag)
        OS: Linux, ABI: 2.6.32

Displaying notes found at file offset 0x00000274 with length 0x00000024:
    Owner                 Data size          Description
    GNU                  0x00000014          NT_GNU_BUILD_ID (unique build ID bitstring)
        Build ID: df924a2b08a7e89f6e11251d4602022977af2670

Displaying notes found at file offset 0x002d6c30 with length 0x00000144:
    Owner                 Data size          Description
    stapsdt              0x00000031          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: gc__start
        Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf6
        Arguments: -4@@%ebx
    stapsdt              0x00000030          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: gc__done
        Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf8
        Arguments: -8@@%rax
    stapsdt              0x00000045          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: function__entry
        Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6be8
        Arguments: 8@@%rbp 8@@%r12 -4@@%eax
    stapsdt              0x00000046          NT_STAPSDT (SystemTap probe descriptors)
        Provider: python
        Name: function__return
        Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bea
        Arguments: 8@@%rbp 8@@%r12 -4@@%eax
@end example

The above metadata contains information for SystemTap describing how it
can patch strategically placed machine code instructions to enable the
tracing hooks used by a SystemTap script.

@node Sondes DTrace statiques,Marqueurs statiques SystemTap,Activer les marqueurs statiques,Instrumenter CPython avec DTrace et SystemTap
@anchor{howto/instrumentation static-dtrace-probes}@anchor{4eee}
@subsection Sondes DTrace statiques


L'exemple suivant de script `DTrace' montre la hiérarchie d'appel/retour d'un script Python, en ne traçant que l'invocation d'une fonction @code{start}. En d'autres termes, les appels de fonctions lors de la phase d'import ne seront pas répertoriées :

@example
self int indent;

python$target:::function-entry
/copyinstr(arg1) == "start"/
@{
        self->trace = 1;
@}

python$target:::function-entry
/self->trace/
@{
        printf("%d\t%*s:", timestamp, 15, probename);
        printf("%*s", self->indent, "");
        printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2);
        self->indent++;
@}

python$target:::function-return
/self->trace/
@{
        self->indent--;
        printf("%d\t%*s:", timestamp, 15, probename);
        printf("%*s", self->indent, "");
        printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2);
@}

python$target:::function-return
/copyinstr(arg1) == "start"/
@{
        self->trace = 0;
@}
@end example

Il peut être utilisé de cette manière :

@example
$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"
@end example

La sortie ressemble à ceci :

@example
156641360502280  function-entry:call_stack.py:start:23
156641360518804  function-entry: call_stack.py:function_1:1
156641360532797  function-entry:  call_stack.py:function_3:9
156641360546807 function-return:  call_stack.py:function_3:10
156641360563367 function-return: call_stack.py:function_1:2
156641360578365  function-entry: call_stack.py:function_2:5
156641360591757  function-entry:  call_stack.py:function_1:1
156641360605556  function-entry:   call_stack.py:function_3:9
156641360617482 function-return:   call_stack.py:function_3:10
156641360629814 function-return:  call_stack.py:function_1:2
156641360642285 function-return: call_stack.py:function_2:6
156641360656770  function-entry: call_stack.py:function_3:9
156641360669707 function-return: call_stack.py:function_3:10
156641360687853  function-entry: call_stack.py:function_4:13
156641360700719 function-return: call_stack.py:function_4:14
156641360719640  function-entry: call_stack.py:function_5:18
156641360732567 function-return: call_stack.py:function_5:21
156641360747370 function-return:call_stack.py:start:28
@end example

@node Marqueurs statiques SystemTap,Marqueurs statiques disponibles,Sondes DTrace statiques,Instrumenter CPython avec DTrace et SystemTap
@anchor{howto/instrumentation static-systemtap-markers}@anchor{4eef}
@subsection Marqueurs statiques `SystemTap'


La façon la plus simple d'utiliser l'intégration `SystemTap' est d'utiliser directement les marqueurs statiques. Pour cela vous devez pointer explicitement le fichier binaire qui les contient.

Par exemple, ce script `SystemTap' peut être utilisé pour afficher la hiérarchie d'appel/retour d'un script Python :

@example
probe process("python").mark("function__entry") @{
     filename = user_string($arg1);
     funcname = user_string($arg2);
     lineno = $arg3;

     printf("%s => %s in %s:%d\\n",
            thread_indent(1), funcname, filename, lineno);
@}

probe process("python").mark("function__return") @{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;

    printf("%s <= %s in %s:%d\\n",
           thread_indent(-1), funcname, filename, lineno);
@}
@end example

Il peut être utilisé de cette manière :

@example
$ stap \
  show-call-hierarchy.stp \
  -c "./python test.py"
@end example

La sortie ressemble à ceci :

@example
11408 python(8274):        => __contains__ in Lib/_abcoll.py:362
11414 python(8274):         => __getitem__ in Lib/os.py:425
11418 python(8274):          => encode in Lib/os.py:490
11424 python(8274):          <= encode in Lib/os.py:493
11428 python(8274):         <= __getitem__ in Lib/os.py:426
11433 python(8274):        <= __contains__ in Lib/_abcoll.py:366
@end example

où les colonnes sont :


@itemize -

@item 
temps en microsecondes depuis le début du script

@item 
nom de l'exécutable

@item 
PID du processus
@end itemize

et le reste indique la hiérarchie d'appel/retour lorsque le script s'exécute.

Pour une compilation @ref{84d,,--enable-shared} de CPython, les marqueurs sont contenus dans la bibliothèque partagée `libpython', et le chemin du module de la sonde doit le refléter. Par exemple, la ligne de l'exemple ci-dessus :

@example
probe process("python").mark("function__entry") @{
@end example

doit plutôt se lire comme :

@example
probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") @{
@end example

(en supposant une version de CPython 3.6 compilée avec le @ref{1f6,,débogage} activé)

@node Marqueurs statiques disponibles,Tapsets de SystemTap,Marqueurs statiques SystemTap,Instrumenter CPython avec DTrace et SystemTap
@anchor{howto/instrumentation available-static-markers}@anchor{4ef0}
@subsection Marqueurs statiques disponibles



@deffn {Object} function__entry(str filename, str funcname, int lineno)

Ce marqueur indique que l'exécution d'une fonction Python a commencé. Il n'est déclenché que pour les fonctions en Python pur (code intermédiaire).

Le nom de fichier, le nom de la fonction et le numéro de ligne sont renvoyés au script de traçage sous forme d'arguments positionnels, auxquels il faut accéder en utilisant @code{$arg1}, @code{$arg2}, @code{$arg3} :

@quotation


@itemize *

@item 
@code{$arg1} : @code{(const char *)} nom de fichier, accessible via @code{user_string($arg1)}

@item 
@code{$arg2} : @code{(const char *)} nom de la fonction, accessible via @code{user_string($arg2)}

@item 
@code{$arg3} : numéro de ligne @code{int}
@end itemize
@end quotation
@end deffn


@deffn {Object} function__return(str filename, str funcname, int lineno)

This marker is the converse of @code{function__entry()}, and indicates that
execution of a Python function has ended (either via @code{return}, or via an
exception).  It is only triggered for pure-Python (bytecode) functions.

The arguments are the same as for @code{function__entry()}
@end deffn


@deffn {Object} line(str filename, str funcname, int lineno)

Ce marqueur indique qu'une ligne Python est sur le point d'être exécutée. C'est l'équivalent du traçage ligne par ligne avec un profileur Python. Il n'est pas déclenché dans les fonctions C.

The arguments are the same as for @code{function__entry()}.
@end deffn


@deffn {Object} gc__start(int generation)

Fires when the Python interpreter starts a garbage collection cycle.
@code{arg0} is the generation to scan, like @ref{a28,,gc.collect()}.
@end deffn


@deffn {Object} gc__done(long collected)

Fonction appelée lorsque l'interpréteur Python termine un cycle de collecte du ramasse-miettes. @code{Arg0} est le nombre d'objets collectés.
@end deffn


@deffn {Object} import__find__load__start(str modulename)

Fonction appelée avant que @ref{76,,importlib} essaye de trouver et de charger le module. @code{arg0} est le nom du module.


Ajouté dans la version 3.7.

@end deffn


@deffn {Object} import__find__load__done(str modulename, int found)

Fonction appelée après que la fonction @code{find_and_load} du module @ref{76,,importlib} soit appelée. @code{arg0} est le nom du module, @code{arg1} indique si le module a été chargé avec succès.


Ajouté dans la version 3.7.

@end deffn


@deffn {Object} audit(str event, void *tuple)

Fonction appelée quand les fonctions @ref{153f,,sys.audit()} ou @ref{365,,PySys_Audit()} sont appelées. @code{arg0} est le nom de l'évènement de type chaîne de caractère C. @code{arg1} est un pointeur sur un `n'-uplet d'objet de type @ref{32f,,PyObject}.


Ajouté dans la version 3.8.

@end deffn

@node Tapsets de SystemTap,Exemples<38>,Marqueurs statiques disponibles,Instrumenter CPython avec DTrace et SystemTap
@anchor{howto/instrumentation systemtap-tapsets}@anchor{4ef1}
@subsection `Tapsets' de `SystemTap'


La façon la plus simple d'utiliser l'intégration `SystemTap' est d'utiliser un `« tapset »'. L'équivalent pour `SystemTap' d'une bibliothèque, qui permet de masquer les détails de niveau inférieur des marqueurs statiques.

Voici un fichier `tapset', basé sur une version non partagée compilée de CPython :

@example
/*
   Provide a higher-level wrapping around the function__entry and
   function__return markers:
 \*/
probe python.function.entry = process("python").mark("function__entry")
@{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;
    frameptr = $arg4
@}
probe python.function.return = process("python").mark("function__return")
@{
    filename = user_string($arg1);
    funcname = user_string($arg2);
    lineno = $arg3;
    frameptr = $arg4
@}
@end example

Si ce fichier est installé dans le répertoire `tapset' de `SystemTap' (par exemple @code{/usr/share/systemtap/tapset}), alors ces sondes supplémentaires deviennent disponibles :


@deffn {Object} python.function.entry(str filename, str funcname, int lineno, frameptr)

Cette sonde indique que l'exécution d'une fonction Python a commencé. Elle n'est déclenchée que pour les fonctions en Python pur (code intermédiaire).
@end deffn


@deffn {Object} python.function.return(str filename, str funcname, int lineno, frameptr)

Cette sonde est l'inverse de @code{python.function.return}, et indique que l'exécution d'une fonction Python est terminée (soit via @code{return}, soit via une exception). Elle est uniquement déclenchée pour les fonctions en Python pur (code intermédiaire ou `bytecode').
@end deffn

@node Exemples<38>,,Tapsets de SystemTap,Instrumenter CPython avec DTrace et SystemTap
@anchor{howto/instrumentation examples}@anchor{4ef2}
@subsection Exemples


Ce script `SystemTap' utilise le `tapset' ci-dessus pour implémenter plus proprement l'exemple précédent de traçage de la hiérarchie des appels de fonctions Python, sans avoir besoin de nommer directement les marqueurs statiques :

@example
probe python.function.entry
@{
  printf("%s => %s in %s:%d\n",
         thread_indent(1), funcname, filename, lineno);
@}

probe python.function.return
@{
  printf("%s <= %s in %s:%d\n",
         thread_indent(-1), funcname, filename, lineno);
@}
@end example

The following script uses the tapset above to provide a top-like view of all
running CPython code, showing the top 20 most frequently entered bytecode
frames, each second, across the whole system:

@example
global fn_calls;

probe python.function.entry
@{
    fn_calls[pid(), filename, funcname, lineno] += 1;
@}

probe timer.ms(1000) @{
    printf("\033[2J\033[1;1H") /* clear screen \*/
    printf("%6s %80s %6s %30s %6s\n",
           "PID", "FILENAME", "LINE", "FUNCTION", "CALLS")
    foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) @{
        printf("%6d %80s %6d %30s %6d\n",
            pid, filename, lineno, funcname,
            fn_calls[pid, filename, funcname, lineno]);
    @}
    delete fn_calls;
@}
@end example

@node Python support for the Linux perf profiler,Bonnes pratiques concernant les annotations,Instrumenter CPython avec DTrace et SystemTap,Les HOWTOs de Python
@anchor{howto/perf_profiling doc}@anchor{16c7}@anchor{howto/perf_profiling perf-profiling}@anchor{18d}@anchor{howto/perf_profiling python-support-for-the-linux-perf-profiler}@anchor{4ef3}
@section Python support for the Linux @code{perf} profiler


@*auteur: 
Pablo Galindo


The Linux perf profiler@footnote{https://perf.wiki.kernel.org}
is a very powerful tool that allows you to profile and obtain
information about the performance of your application.
@code{perf} also has a very vibrant ecosystem of tools
that aid with the analysis of the data that it produces.

The main problem with using the @code{perf} profiler with Python applications is that
@code{perf} only gets information about native symbols, that is, the names of
functions and procedures written in C. This means that the names and file names
of Python functions in your code will not appear in the output of @code{perf}.

Since Python 3.12, the interpreter can run in a special mode that allows Python
functions to appear in the output of the @code{perf} profiler. When this mode is
enabled, the interpreter will interpose a small piece of code compiled on the
fly before the execution of every Python function and it will teach @code{perf} the
relationship between this piece of code and the associated Python function using
@ref{4a3e,,perf map files}.

@cartouche
@quotation Note 
Support for the @code{perf} profiler is currently only available for Linux on
select architectures. Check the output of the @code{configure} build step or
check the output of @code{python -m sysconfig | grep HAVE_PERF_TRAMPOLINE}
to see if your system is supported.
@end quotation
@end cartouche

For example, consider the following script:

@example
def foo(n):
    result = 0
    for _ in range(n):
        result += 1
    return result

def bar(n):
    foo(n)

def baz(n):
    bar(n)

if __name__ == "__main__":
    baz(1000000)
@end example

We can run @code{perf} to sample CPU stack traces at 9999 hertz:

@example
$ perf record -F 9999 -g -o perf.data python my_script.py
@end example

Then we can use @code{perf report} to analyze the data:

@example
$ perf report --stdio -n -g

# Children      Self       Samples  Command     Shared Object       Symbol
# ........  ........  ............  ..........  ..................  ..........................................
#
    91.08%     0.00%             0  python.exe  python.exe          [.] _start
            |
            ---_start
            |
                --90.71%--__libc_start_main
                        Py_BytesMain
                        |
                        |--56.88%--pymain_run_python.constprop.0
                        |          |
                        |          |--56.13%--_PyRun_AnyFileObject
                        |          |          _PyRun_SimpleFileObject
                        |          |          |
                        |          |          |--55.02%--run_mod
                        |          |          |          |
                        |          |          |           --54.65%--PyEval_EvalCode
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     |
                        |          |          |                     |--51.67%--_PyEval_EvalFrameDefault
                        |          |          |                     |          |
                        |          |          |                     |          |--11.52%--_PyLong_Add
                        |          |          |                     |          |          |
                        |          |          |                     |          |          |--2.97%--_PyObject_Malloc
...
@end example

As you can see, the Python functions are not shown in the output, only @code{_PyEval_EvalFrameDefault}
(the function that evaluates the Python bytecode) shows up. Unfortunately that's not very useful because all Python
functions use the same C function to evaluate bytecode so we cannot know which Python function corresponds to which
bytecode-evaluating function.

Instead, if we run the same experiment with @code{perf} support enabled we get:

@example
$ perf report --stdio -n -g

# Children      Self       Samples  Command     Shared Object       Symbol
# ........  ........  ............  ..........  ..................  .....................................................................
#
    90.58%     0.36%             1  python.exe  python.exe          [.] _start
            |
            ---_start
            |
                --89.86%--__libc_start_main
                        Py_BytesMain
                        |
                        |--55.43%--pymain_run_python.constprop.0
                        |          |
                        |          |--54.71%--_PyRun_AnyFileObject
                        |          |          _PyRun_SimpleFileObject
                        |          |          |
                        |          |          |--53.62%--run_mod
                        |          |          |          |
                        |          |          |           --53.26%--PyEval_EvalCode
                        |          |          |                     py::<module>:/src/script.py
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     py::baz:/src/script.py
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     py::bar:/src/script.py
                        |          |          |                     _PyEval_EvalFrameDefault
                        |          |          |                     PyObject_Vectorcall
                        |          |          |                     _PyEval_Vector
                        |          |          |                     py::foo:/src/script.py
                        |          |          |                     |
                        |          |          |                     |--51.81%--_PyEval_EvalFrameDefault
                        |          |          |                     |          |
                        |          |          |                     |          |--13.77%--_PyLong_Add
                        |          |          |                     |          |          |
                        |          |          |                     |          |          |--3.26%--_PyObject_Malloc
@end example

@menu
* How to enable perf profiling support:: 
* How to obtain the best results:: 
* How to work without frame pointers:: 

@end menu

@node How to enable perf profiling support,How to obtain the best results,,Python support for the Linux perf profiler
@anchor{howto/perf_profiling how-to-enable-perf-profiling-support}@anchor{4ef4}
@subsection How to enable @code{perf} profiling support


@code{perf} profiling support can be enabled either from the start using
the environment variable 
@geindex PYTHONPERFSUPPORT
@geindex variable d'environnement; PYTHONPERFSUPPORT
@ref{458,,PYTHONPERFSUPPORT} or the
@ref{175,,-X perf} option,
or dynamically using @ref{459,,sys.activate_stack_trampoline()} and
@ref{45a,,sys.deactivate_stack_trampoline()}.

The @code{sys} functions take precedence over the @code{-X} option,
the @code{-X} option takes precedence over the environment variable.

Example, using the environment variable:

@example
$ PYTHONPERFSUPPORT=1 perf record -F 9999 -g -o perf.data python script.py
$ perf report -g -i perf.data
@end example

Example, using the @code{-X} option:

@example
$ perf record -F 9999 -g -o perf.data python -X perf script.py
$ perf report -g -i perf.data
@end example

Example, using the @ref{d8,,sys} APIs in file @code{example.py}:

@example
import sys

sys.activate_stack_trampoline("perf")
do_profiled_stuff()
sys.deactivate_stack_trampoline()

non_profiled_stuff()
@end example

...then:

@example
$ perf record -F 9999 -g -o perf.data python ./example.py
$ perf report -g -i perf.data
@end example

@node How to obtain the best results,How to work without frame pointers,How to enable perf profiling support,Python support for the Linux perf profiler
@anchor{howto/perf_profiling how-to-obtain-the-best-results}@anchor{4ef5}
@subsection How to obtain the best results


For best results, Python should be compiled with
@code{CFLAGS="-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer"} as this allows
profilers to unwind using only the frame pointer and not on DWARF debug
information. This is because as the code that is interposed to allow @code{perf}
support is dynamically generated it doesn't have any DWARF debugging information
available.

You can check if your system has been compiled with this flag by running:

@example
$ python -m sysconfig | grep 'no-omit-frame-pointer'
@end example

If you don't see any output it means that your interpreter has not been compiled with
frame pointers and therefore it may not be able to show Python functions in the output
of @code{perf}.

@node How to work without frame pointers,,How to obtain the best results,Python support for the Linux perf profiler
@anchor{howto/perf_profiling how-to-work-without-frame-pointers}@anchor{4ef6}
@subsection How to work without frame pointers


If you are working with a Python interpreter that has been compiled without
frame pointers, you can still use the @code{perf} profiler, but the overhead will be
a bit higher because Python needs to generate unwinding information for every
Python function call on the fly. Additionally, @code{perf} will take more time to
process the data because it will need to use the DWARF debugging information to
unwind the stack and this is a slow process.

To enable this mode, you can use the environment variable
@geindex PYTHON_PERF_JIT_SUPPORT
@geindex variable d'environnement; PYTHON_PERF_JIT_SUPPORT
@ref{18e,,PYTHON_PERF_JIT_SUPPORT} or the @ref{175,,-X perf_jit} option,
which will enable the JIT mode for the @code{perf} profiler.

@cartouche
@quotation Note 
Due to a bug in the @code{perf} tool, only @code{perf} versions higher than v6.8
will work with the JIT mode.  The fix was also backported to the v6.7.2
version of the tool.

Note that when checking the version of the @code{perf} tool (which can be done
by running @code{perf version}) you must take into account that some distros
add some custom version numbers including a @code{-} character.  This means
that @code{perf 6.7-3} is not necessarily @code{perf 6.7.3}.
@end quotation
@end cartouche

When using the perf JIT mode, you need an extra step before you can run @code{perf
report}. You need to call the @code{perf inject} command to inject the JIT
information into the @code{perf.data} file.:

@example
$ perf record -F 9999 -g --call-graph dwarf -o perf.data python -Xperf_jit my_script.py
$ perf inject -i perf.data --jit --output perf.jit.data
$ perf report -g -i perf.jit.data
@end example

or using the environment variable:

@example
$ PYTHON_PERF_JIT_SUPPORT=1 perf record -F 9999 -g --call-graph dwarf -o perf.data python my_script.py
$ perf inject -i perf.data --jit --output perf.jit.data
$ perf report -g -i perf.jit.data
@end example

@code{perf inject --jit} command will read @code{perf.data},
automatically pick up the perf dump file that Python creates (in
@code{/tmp/perf-$PID.dump}), and then create @code{perf.jit.data} which merges all the
JIT information together. It should also create a lot of @code{jitted-XXXX-N.so}
files in the current directory which are ELF images for all the JIT trampolines
that were created by Python.

@cartouche
@quotation Avertissement 
Notice that when using @code{--call-graph dwarf} the @code{perf} tool will take
snapshots of the stack of the process being profiled and save the
information in the @code{perf.data} file. By default the size of the stack dump
is 8192 bytes but the user can change the size by passing the size after
comma like @code{--call-graph dwarf,4096}. The size of the stack dump is
important because if the size is too small @code{perf} will not be able to
unwind the stack and the output will be incomplete. On the other hand, if
the size is too big, then @code{perf} won't be able to sample the process as
frequently as it would like as the overhead will be higher.
@end quotation
@end cartouche

@node Bonnes pratiques concernant les annotations,Isolating Extension Modules,Python support for the Linux perf profiler,Les HOWTOs de Python
@anchor{howto/annotations doc}@anchor{4ef7}@anchor{howto/annotations annotations-best-practices}@anchor{4ef8}@anchor{howto/annotations annotations-howto}@anchor{7c3}
@section Bonnes pratiques concernant les annotations


@*auteur: 
Larry Hastings


@subsubheading Résumé



Ce document a pour but de regrouper les bonnes pratiques de travail avec le dictionnaire d'annotations.  Si vous écrivez du code Python qui examine les @code{__annotations__} des objets, nous vous encourageons à suivre les recommandations décrites dans la suite.

Ce document est organisé en quatre sections : bonnes pratiques pour accéder aux annotations d'un objet en Python 3.10 et plus récent, bonnes pratiques pour accéder aux annotations d'un objet en Python 3.9 et antérieur, autres bonnes pratiques pour @code{__annotations__} à appliquer quelle que soit la version de Python, et enfin les curiosités concernant @code{__annotations__}.

Notez que ce document traite spécifiquement du traitement des @code{__annotations__}, et non de l'`utilisation' des annotations. Si vous cherchez des informations sur la façon d'utiliser les « indications de type » dans votre code, veuillez consulter le module @ref{103,,typing}.

@menu
* Accès au dictionnaire des annotations d'un objet dans Python 3.10 et plus récent: Accès au dictionnaire des annotations d'un objet dans Python 3 10 et plus récent. 
* Accès au dictionnaire des annotations d'un objet en Python 3.9 et antérieur: Accès au dictionnaire des annotations d'un objet en Python 3 9 et antérieur. 
* Conversion manuelle des annotations contenues dans une chaîne de caractères:: 
* Bonnes pratiques pour __annotations__ dans toutes les versions de Python:: 
* Les curiosités concernant __annotations__:: 

@end menu

@node Accès au dictionnaire des annotations d'un objet dans Python 3 10 et plus récent,Accès au dictionnaire des annotations d'un objet en Python 3 9 et antérieur,,Bonnes pratiques concernant les annotations
@anchor{howto/annotations accessing-the-annotations-dict-of-an-object-in-python-3-10-and-newer}@anchor{4ef9}
@subsection Accès au dictionnaire des annotations d'un objet dans Python 3.10 et plus récent


Python 3.10 ajoute une nouvelle fonction à la bibliothèque standard : @ref{7fd,,inspect.get_annotations()}.  Dans les versions Python 3.10 et plus récentes, l'appel à cette fonction est la meilleure pratique pour accéder au dictionnaire d'annotations de tout objet qui prend en charge les annotations.  Cette fonction peut également convertir pour vous les annotations contenues dans des chaînes de caractères en objets.

Si pour une raison quelconque, @ref{7fd,,inspect.get_annotations()} n'est pas viable pour votre cas d'utilisation, vous pouvez accéder à l'attribut de données @code{__annotations__} manuellement.  La bonne pratique pour cela a également changé en Python 3.10 : à partir de Python 3.10, le fonctionnement de @code{o.__annotations__} est `toujours' garanti sur les fonctions, classes et modules Python.  Si vous êtes certain que l'objet que vous examinez est l'un de ces trois objets `spécifiques', vous pouvez simplement utiliser @code{o.__annotations__} pour accéder au dictionnaire d'annotations de l'objet.

Cependant, d'autres types d'objets appelables – par exemple, les objets appelables créés par @ref{40a,,functools.partial()} – peuvent ne pas avoir d'attribut @code{__annotations__} défini.  Pour accéder à l'attribut @code{__annotations__} d'un objet éventuellement inconnu, la meilleure pratique, à partir de la version 3.10 de Python, est d'appeler @ref{bbf,,getattr()} avec trois arguments, par exemple @code{getattr(o, '__annotations__', None)}.

Dans les versions antérieures à Python 3.10, l'accès aux @code{__annotations__} d'une classe qui n'a pas d'annotation mais dont un parent de cette classe en a, aurait renvoyé les @code{__annotations__} de la classe parent. Dans les versions 3.10 et plus récentes, le résultat d'annotations de la classe enfant est un dictionnaire vide.

@node Accès au dictionnaire des annotations d'un objet en Python 3 9 et antérieur,Conversion manuelle des annotations contenues dans une chaîne de caractères,Accès au dictionnaire des annotations d'un objet dans Python 3 10 et plus récent,Bonnes pratiques concernant les annotations
@anchor{howto/annotations accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older}@anchor{4efa}
@subsection Accès au dictionnaire des annotations d'un objet en Python 3.9 et antérieur


En Python 3.9 et antérieur, l'accès au dictionnaire des annotations d'un objet est beaucoup plus compliqué que dans les versions plus récentes. Le problème est dû à un défaut de conception de ces anciennes versions de Python, notamment en ce qui concerne les annotations de classe.

La bonne pratique pour accéder au dictionnaire d'annotations d'autres objets – fonctions, autres objets appelables et modules – est la même que pour la 3.10, en supposant que vous n'appelez pas @ref{7fd,,inspect.get_annotations()} : vous devez utiliser la forme à trois arguments de @ref{bbf,,getattr()} pour accéder à l'attribut @code{__annotations__} de l'objet.

Malheureusement, ce n'est pas la bonne pratique pour les classes.  Le problème est que, puisque @code{__annotations__} est optionnel sur les classes et que les classes peuvent hériter des attributs de leurs classes de base, accéder à l'attribut @code{__annotations__} d'une classe peut par inadvertance renvoyer le dictionnaire d'annotations d'une `classe de base.' Par exemple :

@example
class Base:
    a: int = 3
    b: str = 'abc'

class Derived(Base):
    pass

print(Derived.__annotations__)
@end example

Ceci affiche le dictionnaire d'annotations de @code{Base}, pas de @code{Derived}.

Your code will have to have a separate code path if the object
you're examining is a class (@code{isinstance(o, type)}).
In that case, best practice relies on an implementation detail
of Python 3.9 and before: if a class has annotations defined,
they are stored in the class's @ref{c4b,,__dict__} dictionary.  Since
the class may or may not have annotations defined, best practice
is to call the @ref{21cb,,get()} method on the class dict.

Pour résumer, voici un exemple de code qui accède en toute sécurité à l'attribut @code{__annotations__} d'un objet quelconque en Python 3.9 et antérieur :

@example
if isinstance(o, type):
    ann = o.__dict__.get('__annotations__', None)
else:
    ann = getattr(o, '__annotations__', None)
@end example

Après avoir exécuté ce code, @code{ann} pourra être soit un dictionnaire, soit @code{None}.  Nous vous conseillons de vérifier le type de @code{ann} en utilisant @ref{42b,,isinstance()} avant de poursuivre l'analyse.

Note that some exotic or malformed type objects may not have
a @ref{c4b,,__dict__} attribute, so for extra safety you may also wish
to use @ref{bbf,,getattr()} to access @code{__dict__}.

@node Conversion manuelle des annotations contenues dans une chaîne de caractères,Bonnes pratiques pour __annotations__ dans toutes les versions de Python,Accès au dictionnaire des annotations d'un objet en Python 3 9 et antérieur,Bonnes pratiques concernant les annotations
@anchor{howto/annotations manually-un-stringizing-stringized-annotations}@anchor{4efb}
@subsection Conversion manuelle des annotations contenues dans une chaîne de caractères


Dans les situations où certaines annotations peuvent se présenter sous forme de chaînes de caractères brutes, et que vous souhaitez évaluer ces chaînes pour trouver les valeurs Python qu'elles représentent, il est vraiment préférable d'appeler @ref{7fd,,inspect.get_annotations()} pour faire ce travail à votre place.

Si vous utilisez Python 3.9 ou antérieur ou, si pour une raison quelconque, vous ne pouvez pas utiliser @ref{7fd,,inspect.get_annotations()}, vous devrez dupliquer son principe de fonctionnement.  Nous vous encourageons à examiner l'implémentation de @ref{7fd,,inspect.get_annotations()} dans la version actuelle de Python et à suivre une approche similaire.

En bref, si vous souhaitez évaluer une annotation empaquetée en chaîne de caractères sur un objet arbitraire @code{o} :


@itemize *

@item 
Si @code{o} est un module, utilisez @code{o.__dict__} pour accéder aux noms @code{globals} lors de l'appel à @ref{17e,,eval()}.

@item 
Si @code{o} est une classe, utilisez @code{sys.modules[o.__module__].__dict__} pour désigner les noms @code{globals}, et @code{dict(vars(o))} pour désigner les @code{locals}, lorsque vous appelez @ref{17e,,eval()}.

@item 
Si @code{o} est un appelable encapsulé à l'aide de @ref{100b,,functools.update_wrapper()}, @ref{f48,,functools.wraps()}, ou @ref{40a,,functools.partial()}, dés-encapsulez-le itérativement en accédant à @code{o.__wrapped__} ou @code{o.func} selon le cas, jusqu'à ce que vous ayez trouvé la fonction racine.

@item 
If @code{o} is a callable (but not a class), use
@ref{12b1,,o.__globals__} as the globals when calling
@ref{17e,,eval()}.
@end itemize

Cependant, toutes les valeurs de chaîne utilisées comme annotations ne peuvent pas être transformées avec succès en valeurs Python par @ref{17e,,eval()}. Les valeurs de chaîne peuvent théoriquement contenir des chaînes valides et, en pratique, il existe des cas d'utilisation valables pour les indications de type qui nécessitent d'annoter avec des valeurs de chaîne qui `ne peuvent pas' être évaluées.  Par exemple :


@itemize *

@item 
Les types d'union de style 
@geindex Python Enhancement Proposals; PEP 604
PEP 604@footnote{https://peps.python.org/pep-0604/} avec @code{|}, avant que cette prise en charge ne soit ajoutée à Python 3.10.

@item 
Les définitions qui ne sont pas nécessaires à l'exécution, importées uniquement lorsque @ref{ce2,,typing.TYPE_CHECKING} est vrai.
@end itemize

Si @ref{17e,,eval()} tente d'évaluer de telles valeurs, elle échoue et lève une exception.  Ainsi, lors de la conception d'une API de bibliothèque fonctionnant avec des annotations, il est recommandé de ne tenter d'évaluer des valeurs de type chaîne que si l'appelant le demande explicitement.

@node Bonnes pratiques pour __annotations__ dans toutes les versions de Python,Les curiosités concernant __annotations__,Conversion manuelle des annotations contenues dans une chaîne de caractères,Bonnes pratiques concernant les annotations
@anchor{howto/annotations best-practices-for-annotations-in-any-python-version}@anchor{4efc}
@subsection Bonnes pratiques pour @code{__annotations__} dans toutes les versions de Python



@itemize *

@item 
Évitez d'assigner directement des objets à l'élément @code{__annotations__}.  Laissez Python gérer le paramétrage de @code{__annotations__}.

@item 
Si vous assignez directement à l'élément @code{__annotations__} d'un objet, vous devez toujours le définir comme un @code{dict}.

@item 
Si vous accédez directement à l'élément @code{__annotations__} d'un objet, vous devez vous assurer qu'il s'agit d'un dictionnaire avant de tenter d'examiner son contenu.

@item 
Évitez de modifier les dictionnaires @code{__annotations__}.

@item 
Évitez de supprimer l'attribut @code{__annotations__} d'un objet.
@end itemize

@node Les curiosités concernant __annotations__,,Bonnes pratiques pour __annotations__ dans toutes les versions de Python,Bonnes pratiques concernant les annotations
@anchor{howto/annotations annotations-quirks}@anchor{4efd}
@subsection Les curiosités concernant @code{__annotations__}


Dans toutes les versions de Python 3, les fonctions créent paresseusement un dictionnaire d'annotations si aucune annotation n'est définie sur cet objet.  Vous pouvez supprimer l'attribut @code{__annotations__} en utilisant @code{del fn.__annotations__}, mais si vous accédez ensuite à @code{fn.__annotations__}, l'objet créera un nouveau dictionnaire vide qu'il stockera et renverra quand on lui demande ses annotations.  Si vous supprimez les annotations d'une fonction avant qu'elle n'ait créé paresseusement son dictionnaire d'annotations, vous obtiendrez une exception @code{AttributeError} ; si vous utilisez @code{del fn.__annotations__} deux fois de suite, vous êtes sûr de toujours obtenir @code{AttributeError}.

Tout ce qui est dit dans le paragraphe précédent s'applique également aux objets de type classe et module en Python 3.10 et suivants.

Dans toutes les versions de Python 3, vous pouvez définir à @code{None} l'élément @code{__annotations__} sur un objet fonction.  Cependant, si vous accédez ensuite aux annotations de cet objet en utilisant @code{fn.__annotations__}, un dictionnaire vide sera créé paresseusement, comme indiqué dans le premier paragraphe de cette section.  Ce `n'est pas' le cas des modules et des classes, quelle que soit la version de Python ; ces objets permettent de définir @code{__annotations__} à n'importe quelle valeur Python, et conserveront la valeur définie.

Si Python convertit vos annotations en chaînes de caractères (en utilisant @code{from __future__ import annotations}), et que vous spécifiez une chaîne de caractères comme annotation, la chaîne sera elle-même entre guillemets.  En fait, l'annotation est mise entre guillemets `deux fois'. Par exemple :

@example
from __future__ import annotations
def foo(a: "str"): pass

print(foo.__annotations__)
@end example

Ceci renvoie : @code{@{'a': "'str'"@}}.  Cela ne devrait pas vraiment être considéré comme une « bizarrerie » ; nous le mentionnons ici simplement parce que cela peut être surprenant.

@node Isolating Extension Modules,timer file descriptor HOWTO,Bonnes pratiques concernant les annotations,Les HOWTOs de Python
@anchor{howto/isolating-extensions doc}@anchor{4efe}@anchor{howto/isolating-extensions isolating-extension-modules}@anchor{4eff}@anchor{howto/isolating-extensions isolating-extensions-howto}@anchor{4bbd}
@section Isolating Extension Modules


@subsubheading Résumé



Traditionally, state belonging to Python extension modules was kept in C
@code{static} variables, which have process-wide scope. This document
describes problems of such per-process state and shows a safer way:
per-module state.

The document also describes how to switch to per-module state where
possible. This transition involves allocating space for that state, potentially
switching from static types to heap types, and—perhaps most
importantly—accessing per-module state from code.

@menu
* Who should read this:: 
* Background: Background<2>. 
* Making Modules Safe with Multiple Interpreters:: 
* Heap Types: Heap Types<2>. 
* Open Issues:: 

@end menu

@node Who should read this,Background<2>,,Isolating Extension Modules
@anchor{howto/isolating-extensions who-should-read-this}@anchor{4f00}
@subsection Who should read this


This guide is written for maintainers of @ref{1b6a,,C-API} extensions
who would like to make that extension safer to use in applications where
Python itself is used as a library.

@node Background<2>,Making Modules Safe with Multiple Interpreters,Who should read this,Isolating Extension Modules
@anchor{howto/isolating-extensions background}@anchor{4f01}
@subsection Background


An `interpreter' is the context in which Python code runs. It contains
configuration (e.g. the import path) and runtime state (e.g. the set of
imported modules).

Python supports running multiple interpreters in one process. There are
two cases to think about—users may run interpreters:


@itemize -

@item 
in sequence, with several @ref{49a8,,Py_InitializeEx()}/@ref{d03,,Py_FinalizeEx()}
cycles, and

@item 
in parallel, managing "sub-interpreters" using
@ref{1744,,Py_NewInterpreter()}/@ref{17ed,,Py_EndInterpreter()}.
@end itemize

Both cases (and combinations of them) would be most useful when
embedding Python within a library. Libraries generally shouldn't make
assumptions about the application that uses them, which include
assuming a process-wide "main Python interpreter".

Historically, Python extension modules don't handle this use case well.
Many extension modules (and even some stdlib modules) use `per-process'
global state, because C @code{static} variables are extremely easy to use.
Thus, data that should be specific to an interpreter ends up being shared
between interpreters. Unless the extension developer is careful, it is very
easy to introduce edge cases that lead to crashes when a module is loaded in
more than one interpreter in the same process.

Unfortunately, `per-interpreter' state is not easy to achieve. Extension
authors tend to not keep multiple interpreters in mind when developing,
and it is currently cumbersome to test the behavior.

@menu
* Enter Per-Module State:: 
* Isolated Module Objects:: 
* Surprising Edge Cases:: 

@end menu

@node Enter Per-Module State,Isolated Module Objects,,Background<2>
@anchor{howto/isolating-extensions enter-per-module-state}@anchor{4f02}
@subsubsection Enter Per-Module State


Instead of focusing on per-interpreter state, Python's C API is evolving
to better support the more granular `per-module' state.
This means that C-level data should be attached to a `module object'.
Each interpreter creates its own module object, keeping the data separate.
For testing the isolation, multiple module objects corresponding to a single
extension can even be loaded in a single interpreter.

Per-module state provides an easy way to think about lifetime and
resource ownership: the extension module will initialize when a
module object is created, and clean up when it's freed. In this regard,
a module is just like any other @ref{32f,,PyObject}*; there are no "on
interpreter shutdown" hooks to think—or forget—about.

Note that there are use cases for different kinds of "globals":
per-process, per-interpreter, per-thread or per-task state.
With per-module state as the default, these are still possible,
but you should treat them as exceptional cases:
if you need them, you should give them additional care and testing.
(Note that this guide does not cover them.)

@node Isolated Module Objects,Surprising Edge Cases,Enter Per-Module State,Background<2>
@anchor{howto/isolating-extensions isolated-module-objects}@anchor{4f03}
@subsubsection Isolated Module Objects


The key point to keep in mind when developing an extension module is
that several module objects can be created from a single shared library.
For example:

@example
>>> import sys
>>> import binascii
>>> old_binascii = binascii
>>> del sys.modules['binascii']
>>> import binascii  # create a new module object
>>> old_binascii == binascii
False
@end example

As a rule of thumb, the two modules should be completely independent.
All objects and state specific to the module should be encapsulated
within the module object, not shared with other module objects, and
cleaned up when the module object is deallocated.
Since this just is a rule of thumb, exceptions are possible
(see @ref{4f04,,Managing Global State}), but they will need more
thought and attention to edge cases.

While some modules could do with less stringent restrictions, isolated
modules make it easier to set clear expectations and guidelines that
work across a variety of use cases.

@node Surprising Edge Cases,,Isolated Module Objects,Background<2>
@anchor{howto/isolating-extensions surprising-edge-cases}@anchor{4f05}
@subsubsection Surprising Edge Cases


Note that isolated modules do create some surprising edge cases. Most
notably, each module object will typically not share its classes and
exceptions with other similar modules. Continuing from the
@ref{4f03,,example above},
note that @code{old_binascii.Error} and @code{binascii.Error} are
separate objects. In the following code, the exception is `not' caught:

@example
>>> old_binascii.Error == binascii.Error
False
>>> try:
...     old_binascii.unhexlify(b'qwertyuiop')
... except binascii.Error:
...     print('boo')
...
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
binascii.Error: Non-hexadecimal digit found
@end example

This is expected. Notice that pure-Python modules behave the same way:
it is a part of how Python works.

The goal is to make extension modules safe at the C level, not to make
hacks behave intuitively. Mutating @code{sys.modules} "manually" counts
as a hack.

@node Making Modules Safe with Multiple Interpreters,Heap Types<2>,Background<2>,Isolating Extension Modules
@anchor{howto/isolating-extensions making-modules-safe-with-multiple-interpreters}@anchor{4f06}
@subsection Making Modules Safe with Multiple Interpreters


@menu
* Managing Global State:: 
* Managing Per-Module State:: 
* Opt-Out; Limiting to One Module Object per Process: Opt-Out Limiting to One Module Object per Process. 
* Module State Access from Functions:: 

@end menu

@node Managing Global State,Managing Per-Module State,,Making Modules Safe with Multiple Interpreters
@anchor{howto/isolating-extensions managing-global-state}@anchor{4f04}
@subsubsection Managing Global State


Sometimes, the state associated with a Python module is not specific to that module, but
to the entire process (or something else "more global" than a module).
For example:


@itemize -

@item 
The @code{readline} module manages `the' terminal.

@item 
A module running on a circuit board wants to control `the' on-board
LED.
@end itemize

In these cases, the Python module should provide `access' to the global
state, rather than `own' it. If possible, write the module so that
multiple copies of it can access the state independently (along with
other libraries, whether for Python or other languages). If that is not
possible, consider explicit locking.

If it is necessary to use process-global state, the simplest way to
avoid issues with multiple interpreters is to explicitly prevent a
module from being loaded more than once per process—see
@ref{4f07,,Opt-Out; Limiting to One Module Object per Process}.

@node Managing Per-Module State,Opt-Out Limiting to One Module Object per Process,Managing Global State,Making Modules Safe with Multiple Interpreters
@anchor{howto/isolating-extensions managing-per-module-state}@anchor{4f08}
@subsubsection Managing Per-Module State


To use per-module state, use
@ref{481c,,multi-phase extension module initialization}.
This signals that your module supports multiple interpreters correctly.

Set @code{PyModuleDef.m_size} to a positive number to request that many
bytes of storage local to the module. Usually, this will be set to the
size of some module-specific @code{struct}, which can store all of the
module's C-level state. In particular, it is where you should put
pointers to classes (including exceptions, but excluding static types)
and settings (e.g. @code{csv}'s @ref{1794,,field_size_limit})
which the C code needs to function.

@cartouche
@quotation Note 
Another option is to store state in the module's @code{__dict__},
but you must avoid crashing when users modify @code{__dict__} from
Python code. This usually means error- and type-checking at the C level,
which is easy to get wrong and hard to test sufficiently.

However, if module state is not needed in C code, storing it in
@code{__dict__} only is a good idea.
@end quotation
@end cartouche

If the module state includes @code{PyObject} pointers, the module object
must hold references to those objects and implement the module-level hooks
@code{m_traverse}, @code{m_clear} and @code{m_free}. These work like
@code{tp_traverse}, @code{tp_clear} and @code{tp_free} of a class. Adding them will
require some work and make the code longer; this is the price for
modules which can be unloaded cleanly.

An example of a module with per-module state is currently available as
xxlimited@footnote{https://github.com/python/cpython/blob/master/Modules/xxlimited.c};
example module initialization shown at the bottom of the file.

@node Opt-Out Limiting to One Module Object per Process,Module State Access from Functions,Managing Per-Module State,Making Modules Safe with Multiple Interpreters
@anchor{howto/isolating-extensions opt-out-limiting-to-one-module-object-per-process}@anchor{4f07}
@subsubsection Opt-Out: Limiting to One Module Object per Process


A non-negative @code{PyModuleDef.m_size} signals that a module supports
multiple interpreters correctly. If this is not yet the case for your
module, you can explicitly make your module loadable only once per
process. For example:

@example
static int loaded = 0;

static int
exec_module(PyObject* module)
@{
    if (loaded) @{
        PyErr_SetString(PyExc_ImportError,
                        "cannot load module more than once per process");
        return -1;
    @}
    loaded = 1;
    // ... rest of initialization
@}
@end example

@node Module State Access from Functions,,Opt-Out Limiting to One Module Object per Process,Making Modules Safe with Multiple Interpreters
@anchor{howto/isolating-extensions module-state-access-from-functions}@anchor{4f09}
@subsubsection Module State Access from Functions


Accessing the state from module-level functions is straightforward.
Functions get the module object as their first argument; for extracting
the state, you can use @code{PyModule_GetState}:

@example
static PyObject *
func(PyObject *module, PyObject *args)
@{
    my_struct *state = (my_struct*)PyModule_GetState(module);
    if (state == NULL) @{
        return NULL;
    @}
    // ... rest of logic
@}
@end example

@cartouche
@quotation Note 
@code{PyModule_GetState} may return @code{NULL} without setting an
exception if there is no module state, i.e. @code{PyModuleDef.m_size} was
zero. In your own module, you're in control of @code{m_size}, so this is
easy to prevent.
@end quotation
@end cartouche

@node Heap Types<2>,Open Issues,Making Modules Safe with Multiple Interpreters,Isolating Extension Modules
@anchor{howto/isolating-extensions heap-types}@anchor{4f0a}
@subsection Heap Types


Traditionally, types defined in C code are `static'; that is,
@code{static PyTypeObject} structures defined directly in code and
initialized using @code{PyType_Ready()}.

Such types are necessarily shared across the process. Sharing them
between module objects requires paying attention to any state they own
or access. To limit the possible issues, static types are immutable at
the Python level: for example, you can't set @code{str.myattribute = 123}.

`Particularité de l'implémentation CPython :' Sharing truly immutable objects between interpreters is fine,
as long as they don't provide access to mutable objects.
However, in CPython, every Python object has a mutable implementation
detail: the reference count. Changes to the refcount are guarded by the GIL.
Thus, code that shares any Python objects across interpreters implicitly
depends on CPython's current, process-wide GIL.

Because they are immutable and process-global, static types cannot access
"their" module state.
If any method of such a type requires access to module state,
the type must be converted to a `heap-allocated type', or `heap type'
for short. These correspond more closely to classes created by Python's
@code{class} statement.

For new modules, using heap types by default is a good rule of thumb.

@menu
* Changing Static Types to Heap Types:: 
* Defining Heap Types:: 
* Garbage-Collection Protocol:: 
* Module State Access from Classes:: 
* Module State Access from Regular Methods:: 
* Module State Access from Slot Methods@comma{} Getters and Setters: Module State Access from Slot Methods Getters and Setters. 
* Lifetime of the Module State:: 

@end menu

@node Changing Static Types to Heap Types,Defining Heap Types,,Heap Types<2>
@anchor{howto/isolating-extensions changing-static-types-to-heap-types}@anchor{4f0b}
@subsubsection Changing Static Types to Heap Types


Static types can be converted to heap types, but note that
the heap type API was not designed for "lossless" conversion
from static types—that is, creating a type that works exactly like a given
static type.
So, when rewriting the class definition in a new API,
you are likely to unintentionally change a few details (e.g. pickleability
or inherited slots).
Always test the details that are important to you.

Watch out for the following two points in particular (but note that this is not
a comprehensive list):


@itemize *

@item 
Unlike static types, heap type objects are mutable by default.
Use the @ref{3b9,,Py_TPFLAGS_IMMUTABLETYPE} flag to prevent mutability.

@item 
Heap types inherit @ref{56b,,tp_new} by default,
so it may become possible to instantiate them from Python code.
You can prevent this with the @ref{56e,,Py_TPFLAGS_DISALLOW_INSTANTIATION} flag.
@end itemize

@node Defining Heap Types,Garbage-Collection Protocol,Changing Static Types to Heap Types,Heap Types<2>
@anchor{howto/isolating-extensions defining-heap-types}@anchor{4f0c}
@subsubsection Defining Heap Types


Heap types can be created by filling a @ref{16a5,,PyType_Spec} structure, a
description or "blueprint" of a class, and calling
@ref{53c,,PyType_FromModuleAndSpec()} to construct a new class object.

@cartouche
@quotation Note 
Other functions, like @ref{569,,PyType_FromSpec()}, can also create
heap types, but @ref{53c,,PyType_FromModuleAndSpec()} associates the module
with the class, allowing access to the module state from methods.
@end quotation
@end cartouche

The class should generally be stored in `both' the module state (for
safe access from C) and the module's @code{__dict__} (for access from
Python code).

@node Garbage-Collection Protocol,Module State Access from Classes,Defining Heap Types,Heap Types<2>
@anchor{howto/isolating-extensions garbage-collection-protocol}@anchor{4f0d}
@subsubsection Garbage-Collection Protocol


Instances of heap types hold a reference to their type.
This ensures that the type isn't destroyed before all its instances are,
but may result in reference cycles that need to be broken by the
garbage collector.

To avoid memory leaks, instances of heap types must implement the
garbage collection protocol.
That is, heap types should:


@itemize -

@item 
Have the @ref{767,,Py_TPFLAGS_HAVE_GC} flag.

@item 
Define a traverse function using @code{Py_tp_traverse}, which
visits the type (e.g. using @code{Py_VISIT(Py_TYPE(self))}).
@end itemize

Please refer to the documentation of
@ref{767,,Py_TPFLAGS_HAVE_GC} and @ref{768,,tp_traverse}
for additional considerations.

The API for defining heap types grew organically, leaving it
somewhat awkward to use in its current state.
The following sections will guide you through common issues.

@menu
* tp_traverse in Python 3.8 and lower: tp_traverse in Python 3 8 and lower. 
* Delegating tp_traverse:: 
* Defining tp_dealloc:: 
* Not overriding tp_free:: 
* Avoiding PyObject_New:: 

@end menu

@node tp_traverse in Python 3 8 and lower,Delegating tp_traverse,,Garbage-Collection Protocol
@anchor{howto/isolating-extensions tp-traverse-in-python-3-8-and-lower}@anchor{4f0e}
@subsubsection @code{tp_traverse} in Python 3.8 and lower


The requirement to visit the type from @code{tp_traverse} was added in Python 3.9.
If you support Python 3.8 and lower, the traverse function must `not'
visit the type, so it must be more complicated:

@example
static int my_traverse(PyObject *self, visitproc visit, void *arg)
@{
    if (Py_Version >= 0x03090000) @{
        Py_VISIT(Py_TYPE(self));
    @}
    return 0;
@}
@end example

Unfortunately, @ref{740,,Py_Version} was only added in Python 3.11.
As a replacement, use:


@itemize *

@item 
@ref{741,,PY_VERSION_HEX}, if not using the stable ABI, or

@item 
@ref{68b,,sys.version_info} (via @ref{37f,,PySys_GetObject()} and
@ref{55d,,PyArg_ParseTuple()}).
@end itemize

@node Delegating tp_traverse,Defining tp_dealloc,tp_traverse in Python 3 8 and lower,Garbage-Collection Protocol
@anchor{howto/isolating-extensions delegating-tp-traverse}@anchor{4f0f}
@subsubsection Delegating @code{tp_traverse}


If your traverse function delegates to the @ref{768,,tp_traverse}
of its base class (or another type), ensure that @code{Py_TYPE(self)} is visited
only once.
Note that only heap type are expected to visit the type in @code{tp_traverse}.

For example, if your traverse function includes:

@example
base->tp_traverse(self, visit, arg)
@end example

...and @code{base} may be a static type, then it should also include:

@example
if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) @{
    // a heap type's tp_traverse already visited Py_TYPE(self)
@} else @{
    if (Py_Version >= 0x03090000) @{
        Py_VISIT(Py_TYPE(self));
    @}
@}
@end example

It is not necessary to handle the type's reference count in
@ref{56b,,tp_new} and @ref{4801,,tp_clear}.

@node Defining tp_dealloc,Not overriding tp_free,Delegating tp_traverse,Garbage-Collection Protocol
@anchor{howto/isolating-extensions defining-tp-dealloc}@anchor{4f10}
@subsubsection Defining @code{tp_dealloc}


If your type has a custom @ref{47ee,,tp_dealloc} function,
it needs to:


@itemize -

@item 
call @ref{14bd,,PyObject_GC_UnTrack()} before any fields are invalidated, and

@item 
decrement the reference count of the type.
@end itemize

To keep the type valid while @code{tp_free} is called, the type's refcount needs
to be decremented `after' the instance is deallocated. For example:

@example
static void my_dealloc(PyObject *self)
@{
    PyObject_GC_UnTrack(self);
    ...
    PyTypeObject *type = Py_TYPE(self);
    type->tp_free(self);
    Py_DECREF(type);
@}
@end example

The default @code{tp_dealloc} function does this, so
if your type does `not' override
@code{tp_dealloc} you don't need to add it.

@node Not overriding tp_free,Avoiding PyObject_New,Defining tp_dealloc,Garbage-Collection Protocol
@anchor{howto/isolating-extensions not-overriding-tp-free}@anchor{4f11}
@subsubsection Not overriding @code{tp_free}


The @ref{47ef,,tp_free} slot of a heap type must be set to
@ref{14bb,,PyObject_GC_Del()}.
This is the default; do not override it.

@node Avoiding PyObject_New,,Not overriding tp_free,Garbage-Collection Protocol
@anchor{howto/isolating-extensions avoiding-pyobject-new}@anchor{4f12}
@subsubsection Avoiding @code{PyObject_New}


GC-tracked objects need to be allocated using GC-aware functions.

If you use use @ref{972,,PyObject_New()} or @ref{973,,PyObject_NewVar()}:


@itemize -

@item 
Get and call type's @ref{47f0,,tp_alloc} slot, if possible.
That is, replace @code{TYPE *o = PyObject_New(TYPE, typeobj)} with:

@example
TYPE *o = typeobj->tp_alloc(typeobj, 0);
@end example

Replace @code{o = PyObject_NewVar(TYPE, typeobj, size)} with the same,
but use size instead of the 0.

@item 
If the above is not possible (e.g. inside a custom @code{tp_alloc}),
call @ref{a90,,PyObject_GC_New()} or @ref{a91,,PyObject_GC_NewVar()}:

@example
TYPE *o = PyObject_GC_New(TYPE, typeobj);

TYPE *o = PyObject_GC_NewVar(TYPE, typeobj, size);
@end example
@end itemize

@node Module State Access from Classes,Module State Access from Regular Methods,Garbage-Collection Protocol,Heap Types<2>
@anchor{howto/isolating-extensions module-state-access-from-classes}@anchor{4f13}
@subsubsection Module State Access from Classes


If you have a type object defined with @ref{53c,,PyType_FromModuleAndSpec()},
you can call @ref{95b,,PyType_GetModule()} to get the associated module, and then
@ref{96d,,PyModule_GetState()} to get the module's state.

To save a some tedious error-handling boilerplate code, you can combine
these two steps with @ref{95c,,PyType_GetModuleState()}, resulting in:

@example
my_struct *state = (my_struct*)PyType_GetModuleState(type);
if (state == NULL) @{
    return NULL;
@}
@end example

@node Module State Access from Regular Methods,Module State Access from Slot Methods Getters and Setters,Module State Access from Classes,Heap Types<2>
@anchor{howto/isolating-extensions module-state-access-from-regular-methods}@anchor{4f14}
@subsubsection Module State Access from Regular Methods


Accessing the module-level state from methods of a class is somewhat more
complicated, but is possible thanks to API introduced in Python 3.9.
To get the state, you need to first get the `defining class', and then
get the module state from it.

The largest roadblock is getting `the class a method was defined in', or
that method's "defining class" for short. The defining class can have a
reference to the module it is part of.

Do not confuse the defining class with @code{Py_TYPE(self)}. If the method
is called on a `subclass' of your type, @code{Py_TYPE(self)} will refer to
that subclass, which may be defined in different module than yours.

@cartouche
@quotation Note 
The following Python code can illustrate the concept.
@code{Base.get_defining_class} returns @code{Base} even
if @code{type(self) == Sub}:

@example
class Base:
    def get_type_of_self(self):
        return type(self)

    def get_defining_class(self):
        return __class__

class Sub(Base):
    pass
@end example
@end quotation
@end cartouche

For a method to get its "defining class", it must use the
@ref{1617,,METH_METHOD | METH_FASTCALL | METH_KEYWORDS}
@ref{148d,,calling convention}
and the corresponding @ref{74e,,PyCMethod} signature:

@example
PyObject *PyCMethod(
    PyObject *self,               // object the method was called on
    PyTypeObject *defining_class, // defining class
    PyObject *const *args,        // C array of arguments
    Py_ssize_t nargs,             // length of "args"
    PyObject *kwnames)            // NULL, or dict of keyword arguments
@end example

Once you have the defining class, call @ref{95c,,PyType_GetModuleState()} to get
the state of its associated module.

Par exemple :

@example
static PyObject *
example_method(PyObject *self,
        PyTypeObject *defining_class,
        PyObject *const *args,
        Py_ssize_t nargs,
        PyObject *kwnames)
@{
    my_struct *state = (my_struct*)PyType_GetModuleState(defining_class);
    if (state == NULL) @{
        return NULL;
    @}
    ... // rest of logic
@}

PyDoc_STRVAR(example_method_doc, "...");

static PyMethodDef my_methods[] = @{
    @{"example_method",
      (PyCFunction)(void(*)(void))example_method,
      METH_METHOD|METH_FASTCALL|METH_KEYWORDS,
      example_method_doc@}
    @{NULL@},
@}
@end example

@node Module State Access from Slot Methods Getters and Setters,Lifetime of the Module State,Module State Access from Regular Methods,Heap Types<2>
@anchor{howto/isolating-extensions module-state-access-from-slot-methods-getters-and-setters}@anchor{4f15}
@subsubsection Module State Access from Slot Methods, Getters and Setters


@cartouche
@quotation Note 
This is new in Python 3.11.

@c After adding to limited API:
@c 
@c If you use the :ref:`limited API <limited-c-api>`,
@c you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI
@c compatibility with earlier versions.
@end quotation
@end cartouche

Slot methods—the fast C equivalents for special methods, such as
@ref{4ab4,,nb_add} for @ref{1f0f,,__add__} or
@ref{56b,,tp_new} for initialization—have a very simple API that
doesn't allow passing in the defining class, unlike with @ref{74e,,PyCMethod}.
The same goes for getters and setters defined with
@ref{ba6,,PyGetSetDef}.

To access the module state in these cases, use the
@ref{38a,,PyType_GetModuleByDef()} function, and pass in the module definition.
Once you have the module, call @ref{96d,,PyModule_GetState()}
to get the state:

@example
PyObject *module = PyType_GetModuleByDef(Py_TYPE(self), &module_def);
my_struct *state = (my_struct*)PyModule_GetState(module);
if (state == NULL) @{
    return NULL;
@}
@end example

@code{PyType_GetModuleByDef()} works by searching the
@ref{2109,,method resolution order} (i.e. all superclasses) for the first
superclass that has a corresponding module.

@cartouche
@quotation Note 
In very exotic cases (inheritance chains spanning multiple modules
created from the same definition), @code{PyType_GetModuleByDef()} might not
return the module of the true defining class. However, it will always
return a module with the same definition, ensuring a compatible
C memory layout.
@end quotation
@end cartouche

@node Lifetime of the Module State,,Module State Access from Slot Methods Getters and Setters,Heap Types<2>
@anchor{howto/isolating-extensions lifetime-of-the-module-state}@anchor{4f16}
@subsubsection Lifetime of the Module State


When a module object is garbage-collected, its module state is freed.
For each pointer to (a part of) the module state, you must hold a reference
to the module object.

Usually this is not an issue, because types created with
@ref{53c,,PyType_FromModuleAndSpec()}, and their instances, hold a reference
to the module.
However, you must be careful in reference counting when you reference
module state from other places, such as callbacks for external
libraries.

@node Open Issues,,Heap Types<2>,Isolating Extension Modules
@anchor{howto/isolating-extensions open-issues}@anchor{4f17}
@subsection Open Issues


Several issues around per-module state and heap types are still open.

Discussions about improving the situation are best held on the capi-sig mailing list@footnote{https://mail.python.org/mailman3/lists/capi-sig.python.org/}.

@menu
* Per-Class Scope:: 
* Lossless Conversion to Heap Types:: 

@end menu

@node Per-Class Scope,Lossless Conversion to Heap Types,,Open Issues
@anchor{howto/isolating-extensions per-class-scope}@anchor{4f18}
@subsubsection Per-Class Scope


It is currently (as of Python 3.11) not possible to attach state to individual
`types' without relying on CPython implementation details (which may change
in the future—perhaps, ironically, to allow a proper solution for
per-class scope).

@node Lossless Conversion to Heap Types,,Per-Class Scope,Open Issues
@anchor{howto/isolating-extensions lossless-conversion-to-heap-types}@anchor{4f19}
@subsubsection Lossless Conversion to Heap Types


The heap type API was not designed for "lossless" conversion from static types;
that is, creating a type that works exactly like a given static type.

@node timer file descriptor HOWTO,The Python 2 3 Method Resolution Order,Isolating Extension Modules,Les HOWTOs de Python
@anchor{howto/timerfd doc}@anchor{4f1a}@anchor{howto/timerfd timer-file-descriptor-howto}@anchor{4f1b}@anchor{howto/timerfd timerfd-howto}@anchor{4f1c}
@section timer file descriptor HOWTO


@*Version: 
1.13


This HOWTO discusses Python's support for the linux timer file descriptor.

@menu
* Exemples: Exemples<39>. 

@end menu

@node Exemples<39>,,,timer file descriptor HOWTO
@anchor{howto/timerfd examples}@anchor{4f1d}
@subsection Exemples


The following example shows how to use a timer file descriptor
to execute a function twice a second:

@example
# Practical scripts should use really use a non-blocking timer,
# we use a blocking timer here for simplicity.
import os, time

# Create the timer file descriptor
fd = os.timerfd_create(time.CLOCK_REALTIME)

# Start the timer in 1 second, with an interval of half a second
os.timerfd_settime(fd, initial=1, interval=0.5)

try:
    # Process timer events four times.
    for _ in range(4):
        # read() will block until the timer expires
        _ = os.read(fd, 8)
        print("Timer expired")
finally:
    # Remember to close the timer file descriptor!
    os.close(fd)
@end example

To avoid the precision loss caused by the @ref{2eb,,float} type,
timer file descriptors allow specifying initial expiration and interval
in integer nanoseconds with @code{_ns} variants of the functions.

This example shows how @ref{f7e,,epoll()} can be used with timer file
descriptors to wait until the file descriptor is ready for reading:

@example
import os, time, select, socket, sys

# Create an epoll object
ep = select.epoll()

# In this example, use loopback address to send "stop" command to the server.
#
# $ telnet 127.0.0.1 1234
# Trying 127.0.0.1...
# Connected to 127.0.0.1.
# Escape character is '^]'.
# stop
# Connection closed by foreign host.
#
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.bind(("127.0.0.1", 1234))
sock.setblocking(False)
sock.listen(1)
ep.register(sock, select.EPOLLIN)

# Create timer file descriptors in non-blocking mode.
num = 3
fds = []
for _ in range(num):
    fd = os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)
    fds.append(fd)
    # Register the timer file descriptor for read events
    ep.register(fd, select.EPOLLIN)

# Start the timer with os.timerfd_settime_ns() in nanoseconds.
# Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc
for i, fd in enumerate(fds, start=1):
    one_sec_in_nsec = 10**9
    i = i * one_sec_in_nsec
    os.timerfd_settime_ns(fd, initial=i//4, interval=i//4)

timeout = 3
try:
    conn = None
    is_active = True
    while is_active:
        # Wait for the timer to expire for 3 seconds.
        # epoll.poll() returns a list of (fd, event) pairs.
        # fd is a file descriptor.
        # sock and conn[=returned value of socket.accept()] are socket objects, not file descriptors.
        # So use sock.fileno() and conn.fileno() to get the file descriptors.
        events = ep.poll(timeout)

        # If more than one timer file descriptors are ready for reading at once,
        # epoll.poll() returns a list of (fd, event) pairs.
        #
        # In this example settings,
        #    1st timer fires every 0.25 seconds in 0.25 seconds. (0.25, 0.5, 0.75, 1.0, ...)
        #    2nd timer every 0.5 seconds in 0.5 seconds. (0.5, 1.0, 1.5, 2.0, ...)
        #    3rd timer every 0.75 seconds in 0.75 seconds. (0.75, 1.5, 2.25, 3.0, ...)
        #
        #    In 0.25 seconds, only 1st timer fires.
        #    In 0.5 seconds, 1st timer and 2nd timer fires at once.
        #    In 0.75 seconds, 1st timer and 3rd timer fires at once.
        #    In 1.5 seconds, 1st timer, 2nd timer and 3rd timer fires at once.
        #
        # If a timer file descriptor is signaled more than once since
        # the last os.read() call, os.read() returns the number of signaled
        # as host order of class bytes.
        print(f"Signaled events=@{events@}")
        for fd, event in events:
            if event & select.EPOLLIN:
                if fd == sock.fileno():
                    # Check if there is a connection request.
                    print(f"Accepting connection @{fd@}")
                    conn, addr = sock.accept()
                    conn.setblocking(False)
                    print(f"Accepted connection @{conn@} from @{addr@}")
                    ep.register(conn, select.EPOLLIN)
                elif conn and fd == conn.fileno():
                    # Check if there is data to read.
                    print(f"Reading data @{fd@}")
                    data = conn.recv(1024)
                    if data:
                        # You should catch UnicodeDecodeError exception for safety.
                        cmd = data.decode()
                        if cmd.startswith("stop"):
                            print(f"Stopping server")
                            is_active = False
                        else:
                            print(f"Unknown command: @{cmd@}")
                    else:
                        # No more data, close connection
                        print(f"Closing connection @{fd@}")
                        ep.unregister(conn)
                        conn.close()
                        conn = None
                elif fd in fds:
                    print(f"Reading timer @{fd@}")
                    count = int.from_bytes(os.read(fd, 8), byteorder=sys.byteorder)
                    print(f"Timer @{fds.index(fd) + 1@} expired @{count@} times")
                else:
                    print(f"Unknown file descriptor @{fd@}")
finally:
    for fd in fds:
        ep.unregister(fd)
        os.close(fd)
    ep.close()
@end example

This example shows how @ref{d8d,,select()} can be used with timer file
descriptors to wait until the file descriptor is ready for reading:

@example
import os, time, select, socket, sys

# In this example, use loopback address to send "stop" command to the server.
#
# $ telnet 127.0.0.1 1234
# Trying 127.0.0.1...
# Connected to 127.0.0.1.
# Escape character is '^]'.
# stop
# Connection closed by foreign host.
#
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.bind(("127.0.0.1", 1234))
sock.setblocking(False)
sock.listen(1)

# Create timer file descriptors in non-blocking mode.
num = 3
fds = [os.timerfd_create(time.CLOCK_REALTIME, flags=os.TFD_NONBLOCK)
       for _ in range(num)]
select_fds = fds + [sock]

# Start the timers with os.timerfd_settime() in seconds.
# Timer 1 fires every 0.25 seconds; timer 2 every 0.5 seconds; etc
for i, fd in enumerate(fds, start=1):
   os.timerfd_settime(fd, initial=i/4, interval=i/4)

timeout = 3
try:
    conn = None
    is_active = True
    while is_active:
       # Wait for the timer to expire for 3 seconds.
       # select.select() returns a list of file descriptors or objects.
       rfd, wfd, xfd = select.select(select_fds, select_fds, select_fds, timeout)
       for fd in rfd:
           if fd == sock:
               # Check if there is a connection request.
               print(f"Accepting connection @{fd@}")
               conn, addr = sock.accept()
               conn.setblocking(False)
               print(f"Accepted connection @{conn@} from @{addr@}")
               select_fds.append(conn)
           elif conn and fd == conn:
               # Check if there is data to read.
               print(f"Reading data @{fd@}")
               data = conn.recv(1024)
               if data:
                   # You should catch UnicodeDecodeError exception for safety.
                   cmd = data.decode()
                   if cmd.startswith("stop"):
                       print(f"Stopping server")
                       is_active = False
                   else:
                       print(f"Unknown command: @{cmd@}")
               else:
                   # No more data, close connection
                   print(f"Closing connection @{fd@}")
                   select_fds.remove(conn)
                   conn.close()
                   conn = None
           elif fd in fds:
               print(f"Reading timer @{fd@}")
               count = int.from_bytes(os.read(fd, 8), byteorder=sys.byteorder)
               print(f"Timer @{fds.index(fd) + 1@} expired @{count@} times")
           else:
               print(f"Unknown file descriptor @{fd@}")
finally:
    for fd in fds:
       os.close(fd)
    sock.close()
    sock = None
@end example

@node The Python 2 3 Method Resolution Order,Python experimental support for free threading,timer file descriptor HOWTO,Les HOWTOs de Python
@anchor{howto/mro doc}@anchor{4f1e}@anchor{howto/mro python-2-3-mro}@anchor{145e}@anchor{howto/mro the-python-2-3-method-resolution-order}@anchor{4f1f}
@section The Python 2.3 Method Resolution Order


@cartouche
@quotation Note 
This is a historical document, provided as an appendix to the official
documentation.
The Method Resolution Order discussed here was `introduced' in Python 2.3,
but it is still used in later versions -- including Python 3.
@end quotation
@end cartouche

By Michele Simionato@footnote{https://www.phyast.pitt.edu/~micheles/}.

@*Résumé: 
`This document is intended for Python programmers who want to
understand the C3 Method Resolution Order used in Python 2.3.
Although it is not intended for newbies, it is quite pedagogical with
many worked out examples.  I am not aware of other publicly available
documents with the same scope, therefore it should be useful.'


Disclaimer:

@quotation

`I donate this document to the Python Software Foundation, under the
Python 2.3 license.  As usual in these circumstances, I warn the
reader that what follows' should `be correct, but I don't give any
warranty.  Use it at your own risk and peril!'
@end quotation

Acknowledgments:

@quotation

`All the people of the Python mailing list who sent me their support.
Paul Foley who pointed out various imprecisions and made me to add the
part on local precedence ordering. David Goodger for help with the
formatting in reStructuredText. David Mertz for help with the editing.
Finally, Guido van Rossum who enthusiastically added this document to
the official Python 2.3 home-page.'
@end quotation

@menu
* The beginning:: 
* The C3 Method Resolution Order:: 
* Exemples: Exemples<40>. 
* Bad Method Resolution Orders:: 
* The end:: 
* Resources:: 

@end menu

@node The beginning,The C3 Method Resolution Order,,The Python 2 3 Method Resolution Order
@anchor{howto/mro the-beginning}@anchor{4f20}
@subsection The beginning


@quotation

`Felix qui potuit rerum cognoscere causas' -- Virgilius
@end quotation

Everything started with a post by Samuele Pedroni to the Python
development mailing list @footnote{
The thread on python-dev started by Samuele Pedroni:
@indicateurl{https://mail.python.org/pipermail/python-dev/2002-October/029035.html}
}.  In his post, Samuele showed that the
Python 2.2 method resolution order is not monotonic and he proposed to
replace it with the C3 method resolution order.  Guido agreed with his
arguments and therefore now Python 2.3 uses C3.  The C3 method itself
has nothing to do with Python, since it was invented by people working
on Dylan and it is described in a paper intended for lispers @footnote{
The paper `A Monotonic Superclass Linearization for Dylan':
@indicateurl{https://doi.org/10.1145/236337.236343}
}.  The
present paper gives a (hopefully) readable discussion of the C3
algorithm for Pythonistas who want to understand the reasons for the
change.

First of all, let me point out that what I am going to say only applies
to the `new style classes' introduced in Python 2.2:  `classic classes'
maintain their old method resolution order, depth first and then left to
right.  Therefore, there is no breaking of old code for classic classes;
and even if in principle there could be breaking of code for Python 2.2
new style classes, in practice the cases in which the C3 resolution
order differs from the Python 2.2 method resolution order are so rare
that no real breaking of code is expected.  Therefore:

@quotation

`Don't be scared!'
@end quotation

Moreover, unless you make strong use of multiple inheritance and you
have non-trivial hierarchies, you don't need to understand the C3
algorithm, and you can easily skip this paper.  On the other hand, if
you really want to know how multiple inheritance works, then this paper
is for you.  The good news is that things are not as complicated as you
might expect.

Let me begin with some basic definitions.


@enumerate 

@item 
Given a class C in a complicated multiple inheritance hierarchy, it
is a non-trivial task to specify the order in which methods are
overridden, i.e. to specify the order of the ancestors of C.

@item 
The list of the ancestors of a class C, including the class itself,
ordered from the nearest ancestor to the furthest, is called the
class precedence list or the `linearization' of C.

@item 
The `Method Resolution Order' (MRO) is the set of rules that
construct the linearization.  In the Python literature, the idiom
"the MRO of C" is also used as a synonymous for the linearization of
the class C.

@item 
For instance, in the case of single inheritance hierarchy, if C is a
subclass of C1, and C1 is a subclass of C2, then the linearization of
C is simply the list [C, C1 , C2].  However, with multiple
inheritance hierarchies, the construction of the linearization is
more cumbersome, since it is more difficult to construct a
linearization that respects `local precedence ordering' and
`monotonicity'.

@item 
I will discuss the local precedence ordering later, but I can give
the definition of monotonicity here.  A MRO is monotonic when the
following is true:  `if C1 precedes C2 in the linearization of C,
then C1 precedes C2 in the linearization of any subclass of C'.
Otherwise, the innocuous operation of deriving a new class could
change the resolution order of methods, potentially introducing very
subtle bugs.  Examples where this happens will be shown later.

@item 
Not all classes admit a linearization.  There are cases, in
complicated hierarchies, where it is not possible to derive a class
such that its linearization respects all the desired properties.
@end enumerate

Here I give an example of this situation. Consider the hierarchy

@example
>>> O = object
>>> class X(O): pass
>>> class Y(O): pass
>>> class A(X,Y): pass
>>> class B(Y,X): pass
@end example

which can be represented with the following inheritance graph, where I
have denoted with O the @code{object} class, which is the beginning of any
hierarchy for new style classes:

@quotation

@example
 -----------
|           |
|    O      |
|  /   \    |
 - X    Y  /
   |  / | /
   | /  |/
   A    B
   \   /
     ?
@end example
@end quotation

In this case, it is not possible to derive a new class C from A and B,
since X precedes Y in A, but Y precedes X in B, therefore the method
resolution order would be ambiguous in C.

Python 2.3 raises an exception in this situation (TypeError:  MRO
conflict among bases Y, X) forbidding the naive programmer from creating
ambiguous hierarchies.  Python 2.2 instead does not raise an exception,
but chooses an `ad hoc' ordering (CABXYO in this case).

@node The C3 Method Resolution Order,Exemples<40>,The beginning,The Python 2 3 Method Resolution Order
@anchor{howto/mro the-c3-method-resolution-order}@anchor{4f21}
@subsection The C3 Method Resolution Order


Let me introduce a few simple notations which will be useful for the
following discussion.  I will use the shortcut notation:

@example
C1 C2 ... CN
@end example

to indicate the list of classes [C1, C2, ... , CN].

The `head' of the list is its first element:

@example
head = C1
@end example

whereas the `tail' is the rest of the list:

@example
tail = C2 ... CN.
@end example

I shall also use the notation:

@example
C + (C1 C2 ... CN) = C C1 C2 ... CN
@end example

to denote the sum of the lists [C] + [C1, C2, ... ,CN].

Now I can explain how the MRO works in Python 2.3.

Consider a class C in a multiple inheritance hierarchy, with C
inheriting from the base classes B1, B2, ...  , BN.  We want to
compute the linearization L[C] of the class C. The rule is the
following:

@quotation

`the linearization of C is the sum of C plus the merge of the
linearizations of the parents and the list of the parents.'
@end quotation

In symbolic notation:

@example
L[C(B1 ... BN)] = C + merge(L[B1] ... L[BN], B1 ... BN)
@end example

In particular, if C is the @code{object} class, which has no parents, the
linearization is trivial:

@example
L[object] = object.
@end example

However, in general one has to compute the merge according to the following
prescription:

@quotation

`take the head of the first list, i.e L[B1][0]; if this head is not in
the tail of any of the other lists, then add it to the linearization
of C and remove it from the lists in the merge, otherwise look at the
head of the next list and take it, if it is a good head.  Then repeat
the operation until all the class are removed or it is impossible to
find good heads.  In this case, it is impossible to construct the
merge, Python 2.3 will refuse to create the class C and will raise an
exception.'
@end quotation

This prescription ensures that the merge operation `preserves' the
ordering, if the ordering can be preserved.  On the other hand, if the
order cannot be preserved (as in the example of serious order
disagreement discussed above) then the merge cannot be computed.

The computation of the merge is trivial if C has only one parent
(single inheritance); in this case:

@example
L[C(B)] = C + merge(L[B],B) = C + L[B]
@end example

However, in the case of multiple inheritance things are more cumbersome
and I don't expect you can understand the rule without a couple of
examples ;-)

@node Exemples<40>,Bad Method Resolution Orders,The C3 Method Resolution Order,The Python 2 3 Method Resolution Order
@anchor{howto/mro examples}@anchor{4f22}
@subsection Exemples


First example. Consider the following hierarchy:

@example
>>> O = object
>>> class F(O): pass
>>> class E(O): pass
>>> class D(O): pass
>>> class C(D,F): pass
>>> class B(D,E): pass
>>> class A(B,C): pass
@end example

In this case the inheritance graph can be drawn as:

@quotation

@example
                          6
                         ---
Level 3                 | O |                  (more general)
                      /  ---  \
                     /    |    \                      |
                    /     |     \                     |
                   /      |      \                    |
                  ---    ---    ---                   |
Level 2        3 | D | 4| E |  | F | 5                |
                  ---    ---    ---                   |
                   \  \ _ /       |                   |
                    \    / \ _    |                   |
                     \  /      \  |                   |
                      ---      ---                    |
Level 1            1 | B |    | C | 2                 |
                      ---      ---                    |
                        \      /                      |
                         \    /                      \ /
                           ---
Level 0                 0 | A |                (more specialized)
                           ---
@end example
@end quotation

The linearizations of O,D,E and F are trivial:

@example
L[O] = O
L[D] = D O
L[E] = E O
L[F] = F O
@end example

The linearization of B can be computed as:

@example
L[B] = B + merge(DO, EO, DE)
@end example

We see that D is a good head, therefore we take it and we are reduced to
compute @code{merge(O,EO,E)}.  Now O is not a good head, since it is in the
tail of the sequence EO.  In this case the rule says that we have to
skip to the next sequence.  Then we see that E is a good head; we take
it and we are reduced to compute @code{merge(O,O)} which gives O. Therefore:

@example
L[B] =  B D E O
@end example

Using the same procedure one finds:

@example
L[C] = C + merge(DO,FO,DF)
     = C + D + merge(O,FO,F)
     = C + D + F + merge(O,O)
     = C D F O
@end example

Now we can compute:

@example
L[A] = A + merge(BDEO,CDFO,BC)
     = A + B + merge(DEO,CDFO,C)
     = A + B + C + merge(DEO,DFO)
     = A + B + C + D + merge(EO,FO)
     = A + B + C + D + E + merge(O,FO)
     = A + B + C + D + E + F + merge(O,O)
     = A B C D E F O
@end example

In this example, the linearization is ordered in a pretty nice way
according to the inheritance level, in the sense that lower levels (i.e.
more specialized classes) have higher precedence (see the inheritance
graph).  However, this is not the general case.

I leave as an exercise for the reader to compute the linearization for
my second example:

@example
>>> O = object
>>> class F(O): pass
>>> class E(O): pass
>>> class D(O): pass
>>> class C(D,F): pass
>>> class B(E,D): pass
>>> class A(B,C): pass
@end example

The only difference with the previous example is the change B(D,E) -->
B(E,D); however even such a little modification completely changes the
ordering of the hierarchy:

@quotation

@example
                           6
                          ---
Level 3                  | O |
                       /  ---  \
                      /    |    \
                     /     |     \
                    /      |      \
                  ---     ---    ---
Level 2        2 | E | 4 | D |  | F | 5
                  ---     ---    ---
                   \      / \     /
                    \    /   \   /
                     \  /     \ /
                      ---     ---
Level 1            1 | B |   | C | 3
                      ---     ---
                       \       /
                        \     /
                          ---
Level 0                0 | A |
                          ---
@end example
@end quotation

Notice that the class E, which is in the second level of the hierarchy,
precedes the class C, which is in the first level of the hierarchy, i.e.
E is more specialized than C, even if it is in a higher level.

A lazy programmer can obtain the MRO directly from Python 2.2, since in
this case it coincides with the Python 2.3 linearization.  It is enough
to invoke the @ref{1eb0,,mro()} method of class A:

@example
>>> A.mro()  
[<class 'A'>, <class 'B'>, <class 'E'>,
<class 'C'>, <class 'D'>, <class 'F'>,
<class 'object'>]
@end example

Finally, let me consider the example discussed in the first section,
involving a serious order disagreement.  In this case, it is
straightforward to compute the linearizations of O, X, Y, A and B:

@quotation

@example
L[O] = 0
L[X] = X O
L[Y] = Y O
L[A] = A X Y O
L[B] = B Y X O
@end example
@end quotation

However, it is impossible to compute the linearization for a class C
that inherits from A and B:

@example
L[C] = C + merge(AXYO, BYXO, AB)
     = C + A + merge(XYO, BYXO, B)
     = C + A + B + merge(XYO, YXO)
@end example

At this point we cannot merge the lists XYO and YXO, since X is in the
tail of YXO whereas Y is in the tail of XYO:  therefore there are no
good heads and the C3 algorithm stops.  Python 2.3 raises an error and
refuses to create the class C.

@node Bad Method Resolution Orders,The end,Exemples<40>,The Python 2 3 Method Resolution Order
@anchor{howto/mro bad-method-resolution-orders}@anchor{4f23}
@subsection Bad Method Resolution Orders


A MRO is `bad' when it breaks such fundamental properties as local
precedence ordering and monotonicity.  In this section, I will show
that both the MRO for classic classes and the MRO for new style classes
in Python 2.2 are bad.

It is easier to start with the local precedence ordering.  Consider the
following example:

@example
>>> F=type('Food',(),@{'remember2buy':'spam'@})
>>> E=type('Eggs',(F,),@{'remember2buy':'eggs'@})
>>> G=type('GoodFood',(F,E),@{@}) # under Python 2.3 this is an error!  
@end example

with inheritance diagram

@quotation

@example
             O
             |
(buy spam)   F
             | \
             | E   (buy eggs)
             | /
             G

      (buy eggs or spam ?)
@end example
@end quotation

We see that class G inherits from F and E, with F `before' E:  therefore
we would expect the attribute `G.remember2buy' to be inherited by
`F.rembermer2buy' and not by `E.remember2buy':  nevertheless Python 2.2
gives

@example
>>> G.remember2buy  
'eggs'
@end example

This is a breaking of local precedence ordering since the order in the
local precedence list, i.e. the list of the parents of G, is not
preserved in the Python 2.2 linearization of G:

@example
L[G,P22]= G E F object   # F *follows* E
@end example

One could argue that the reason why F follows E in the Python 2.2
linearization is that F is less specialized than E, since F is the
superclass of E; nevertheless the breaking of local precedence ordering
is quite non-intuitive and error prone.  This is particularly true since
it is a different from old style classes:

@example
>>> class F: remember2buy='spam'
>>> class E(F): remember2buy='eggs'
>>> class G(F,E): pass  
>>> G.remember2buy  
'spam'
@end example

In this case the MRO is GFEF and the local precedence ordering is
preserved.

As a general rule, hierarchies such as the previous one should be
avoided, since it is unclear if F should override E or vice-versa.
Python 2.3 solves the ambiguity by raising an exception in the creation
of class G, effectively stopping the programmer from generating
ambiguous hierarchies.  The reason for that is that the C3 algorithm
fails when the merge:

@example
merge(FO,EFO,FE)
@end example

cannot be computed, because F is in the tail of EFO and E is in the tail
of FE.

The real solution is to design a non-ambiguous hierarchy, i.e. to derive
G from E and F (the more specific first) and not from F and E; in this
case the MRO is GEF without any doubt.

@quotation

@example
           O
           |
           F (spam)
         / |
(eggs)   E |
         \ |
           G
             (eggs, no doubt)
@end example
@end quotation

Python 2.3 forces the programmer to write good hierarchies (or, at
least, less error-prone ones).

On a related note, let me point out that the Python 2.3 algorithm is
smart enough to recognize obvious mistakes, as the duplication of
classes in the list of parents:

@example
>>> class A(object): pass
>>> class C(A,A): pass # error
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: duplicate base class A
@end example

Python 2.2 (both for classic classes and new style classes) in this
situation, would not raise any exception.

Finally, I would like to point out two lessons we have learned from this
example:


@enumerate 

@item 
despite the name, the MRO determines the resolution order of
attributes, not only of methods;

@item 
the default food for Pythonistas is spam !  (but you already knew
that ;-)
@end enumerate

Having discussed the issue of local precedence ordering, let me now
consider the issue of monotonicity.  My goal is to show that neither the
MRO for classic classes nor that for Python 2.2 new style classes is
monotonic.

To prove that the MRO for classic classes is non-monotonic is rather
trivial, it is enough to look at the diamond diagram:

@quotation

@example
   C
  / \
 /   \
A     B
 \   /
  \ /
   D
@end example
@end quotation

One easily discerns the inconsistency:

@example
L[B,P21] = B C        # B precedes C : B's methods win
L[D,P21] = D A C B C  # B follows C  : C's methods win!
@end example

On the other hand, there are no problems with the Python 2.2 and 2.3
MROs, they give both:

@example
L[D] = D A B C
@end example

Guido points out in his essay @footnote{
Guido van Rossum's essay, `Unifying types and classes in Python 2.2':
@indicateurl{https://web.archive.org/web/20140210194412/http://www.python.org/download/releases/2.2.2/descrintro}
} that the classic MRO is not so bad in
practice, since one can typically avoids diamonds for classic classes.
But all new style classes inherit from @code{object}, therefore diamonds are
unavoidable and inconsistencies shows up in every multiple inheritance
graph.

The MRO of Python 2.2 makes breaking monotonicity difficult, but not
impossible.  The following example, originally provided by Samuele
Pedroni, shows that the MRO of Python 2.2 is non-monotonic:

@example
>>> class A(object): pass
>>> class B(object): pass
>>> class C(object): pass
>>> class D(object): pass
>>> class E(object): pass
>>> class K1(A,B,C): pass
>>> class K2(D,B,E): pass
>>> class K3(D,A):   pass
>>> class Z(K1,K2,K3): pass
@end example

Here are the linearizations according to the C3 MRO (the reader should
verify these linearizations as an exercise and draw the inheritance
diagram ;-)

@example
L[A] = A O
L[B] = B O
L[C] = C O
L[D] = D O
L[E] = E O
L[K1]= K1 A B C O
L[K2]= K2 D B E O
L[K3]= K3 D A O
L[Z] = Z K1 K2 K3 D A B C E O
@end example

Python 2.2 gives exactly the same linearizations for A, B, C, D, E, K1,
K2 and K3, but a different linearization for Z:

@example
L[Z,P22] = Z K1 K3 A K2 D B C E O
@end example

It is clear that this linearization is `wrong', since A comes before D
whereas in the linearization of K3 A comes `after' D. In other words, in
K3 methods derived by D override methods derived by A, but in Z, which
still is a subclass of K3, methods derived by A override methods derived
by D!  This is a violation of monotonicity.  Moreover, the Python 2.2
linearization of Z is also inconsistent with local precedence ordering,
since the local precedence list of the class Z is [K1, K2, K3] (K2
precedes K3), whereas in the linearization of Z K2 `follows' K3.  These
problems explain why the 2.2 rule has been dismissed in favor of the C3
rule.

@node The end,Resources,Bad Method Resolution Orders,The Python 2 3 Method Resolution Order
@anchor{howto/mro the-end}@anchor{4f24}
@subsection The end


This section is for the impatient reader, who skipped all the previous
sections and jumped immediately to the end.  This section is for the
lazy programmer too, who didn't want to exercise her/his brain.
Finally, it is for the programmer with some hubris, otherwise s/he would
not be reading a paper on the C3 method resolution order in multiple
inheritance hierarchies ;-) These three virtues taken all together (and
`not' separately) deserve a prize:  the prize is a short Python 2.2
script that allows you to compute the 2.3 MRO without risk to your
brain.  Simply change the last line to play with the various examples I
have discussed in this paper.:

@example
#<mro.py>

"""C3 algorithm by Samuele Pedroni (with readability enhanced by me)."""

class __metaclass__(type):
    "All classes are metamagically modified to be nicely printed"
    __repr__ = lambda cls: cls.__name__

class ex_2:
    "Serious order disagreement" #From Guido
    class O: pass
    class X(O): pass
    class Y(O): pass
    class A(X,Y): pass
    class B(Y,X): pass
    try:
        class Z(A,B): pass #creates Z(A,B) in Python 2.2
    except TypeError:
        pass # Z(A,B) cannot be created in Python 2.3

class ex_5:
    "My first example"
    class O: pass
    class F(O): pass
    class E(O): pass
    class D(O): pass
    class C(D,F): pass
    class B(D,E): pass
    class A(B,C): pass

class ex_6:
    "My second example"
    class O: pass
    class F(O): pass
    class E(O): pass
    class D(O): pass
    class C(D,F): pass
    class B(E,D): pass
    class A(B,C): pass

class ex_9:
    "Difference between Python 2.2 MRO and C3" #From Samuele
    class O: pass
    class A(O): pass
    class B(O): pass
    class C(O): pass
    class D(O): pass
    class E(O): pass
    class K1(A,B,C): pass
    class K2(D,B,E): pass
    class K3(D,A): pass
    class Z(K1,K2,K3): pass

def merge(seqs):
    print '\n\nCPL[%s]=%s' % (seqs[0][0],seqs),
    res = []; i=0
    while 1:
      nonemptyseqs=[seq for seq in seqs if seq]
      if not nonemptyseqs: return res
      i+=1; print '\n',i,'round: candidates...',
      for seq in nonemptyseqs: # find merge candidates among seq heads
          cand = seq[0]; print ' ',cand,
          nothead=[s for s in nonemptyseqs if cand in s[1:]]
          if nothead: cand=None #reject candidate
          else: break
      if not cand: raise "Inconsistent hierarchy"
      res.append(cand)
      for seq in nonemptyseqs: # remove cand
          if seq[0] == cand: del seq[0]

def mro(C):
    "Compute the class precedence list (mro) according to C3"
    return merge([[C]]+map(mro,C.__bases__)+[list(C.__bases__)])

def print_mro(C):
    print '\nMRO[%s]=%s' % (C,mro(C))
    print '\nP22 MRO[%s]=%s' % (C,C.mro())

print_mro(ex_9.Z)

#</mro.py>
@end example

That's all folks,

@quotation

enjoy !
@end quotation

@node Resources,,The end,The Python 2 3 Method Resolution Order
@anchor{howto/mro resources}@anchor{4f25}
@subsection Resources


@node Python experimental support for free threading,C API Extension Support for Free Threading,The Python 2 3 Method Resolution Order,Les HOWTOs de Python
@anchor{howto/free-threading-python doc}@anchor{4f26}@anchor{howto/free-threading-python freethreading-python-howto}@anchor{4f27}@anchor{howto/free-threading-python python-experimental-support-for-free-threading}@anchor{4f28}
@section Python experimental support for free threading


Starting with the 3.13 release, CPython has experimental support for a build of
Python called @ref{150c,,free threading} where the @ref{147,,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.

This document describes the implications of free threading
for Python code.  See @ref{4f29,,C API Extension Support for Free Threading} for information on
how to write C extensions that support the free-threaded build.


@subsubheading Voir aussi


@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/} – Making the Global Interpreter Lock Optional in CPython for an
overall description of free-threaded Python.


@menu
* Installation:: 
* Identifying free-threaded Python:: 
* The global interpreter lock in free-threaded Python:: 
* Thread safety:: 
* Known limitations:: 

@end menu

@node Installation,Identifying free-threaded Python,,Python experimental support for free threading
@anchor{howto/free-threading-python installation}@anchor{4f2a}
@subsection Installation


Starting with Python 3.13, the official macOS and Windows installers
optionally support installing free-threaded Python binaries.  The installers
are available at @indicateurl{https://www.python.org/downloads/}.

For information on other platforms, see the Installing a Free-Threaded Python@footnote{https://py-free-threading.github.io/installing_cpython/}, a
community-maintained installation guide for installing free-threaded Python.

When building CPython from source, the @ref{173,,--disable-gil} configure option
should be used to build a free-threaded Python interpreter.

@node Identifying free-threaded Python,The global interpreter lock in free-threaded Python,Installation,Python experimental support for free threading
@anchor{howto/free-threading-python identifying-free-threaded-python}@anchor{4f2b}
@subsection Identifying free-threaded Python


To check if the current interpreter supports free-threading, @ref{176,,python -VV}
and @ref{177,,sys.version} contain "experimental free-threading build".
The new @ref{42b9,,sys._is_gil_enabled()} function can be used to check whether
the GIL is actually disabled in the running process.

The @code{sysconfig.get_config_var("Py_GIL_DISABLED")} configuration variable can
be used to determine whether the build supports free threading.  If the variable
is set to @code{1}, then the build supports free threading.  This is the recommended
mechanism for decisions related to the build configuration.

@node The global interpreter lock in free-threaded Python,Thread safety,Identifying free-threaded Python,Python experimental support for free threading
@anchor{howto/free-threading-python the-global-interpreter-lock-in-free-threaded-python}@anchor{4f2c}
@subsection The global interpreter lock in free-threaded Python


Free-threaded builds of CPython support optionally running with the GIL enabled
at runtime using the environment variable 
@geindex PYTHON_GIL
@geindex variable d'environnement; PYTHON_GIL
@ref{174,,PYTHON_GIL} or
the command-line option @ref{175,,-X gil}.

The GIL may also automatically be enabled when importing a C-API extension
module that is not explicitly marked as supporting free threading.  A warning
will be printed in this case.

In addition to individual package documentation, the following websites track
the status of popular packages support for free threading:


@itemize *

@item 
@indicateurl{https://py-free-threading.github.io/tracking/}

@item 
@indicateurl{https://hugovk.github.io/free-threaded-wheels/}
@end itemize

@node Thread safety,Known limitations,The global interpreter lock in free-threaded Python,Python experimental support for free threading
@anchor{howto/free-threading-python thread-safety}@anchor{4f2d}
@subsection Thread safety


The free-threaded build of CPython aims to provide similar thread-safety
behavior at the Python level to the default GIL-enabled build.  Built-in
types like @ref{253,,dict}, @ref{5fc,,list}, and @ref{5c3,,set} use internal locks
to protect against concurrent modifications in ways that behave similarly to
the GIL.  However, Python has not historically guaranteed specific behavior for
concurrent modifications to these built-in types, so this should be treated
as a description of the current implementation, not a guarantee of current or
future behavior.

@cartouche
@quotation Note 
It's recommended to use the @ref{1600,,threading.Lock} or other synchronization
primitives instead of relying on the internal locks of built-in types, when
possible.
@end quotation
@end cartouche

@node Known limitations,,Thread safety,Python experimental support for free threading
@anchor{howto/free-threading-python known-limitations}@anchor{4f2e}
@subsection Known limitations


This section describes known limitations of the free-threaded CPython build.

@menu
* Immortalization:: 
* Objets cadres: Objets cadres<2>. 
* Itérateurs: Itérateurs<4>. 
* Single-threaded performance:: 

@end menu

@node Immortalization,Objets cadres<2>,,Known limitations
@anchor{howto/free-threading-python immortalization}@anchor{4f2f}
@subsubsection Immortalization


The free-threaded build of the 3.13 release makes some objects @ref{42aa,,immortal}.
Immortal objects are not deallocated and have reference counts that are
never modified.  This is done to avoid reference count contention that would
prevent efficient multi-threaded scaling.

An object will be made immortal when a new thread is started for the first time
after the main thread is running.  The following objects are immortalized:


@itemize *

@item 
@ref{296,,function} objects declared at the module level

@item 
@ref{1e86,,method} descriptors

@item 
@ref{1cd,,code} objects

@item 
@ref{15e8,,module} objects and their dictionaries

@item 
@ref{1e93,,classes} (type objects)
@end itemize

Because immortal objects are never deallocated, applications that create many
objects of these types may see increased memory usage.  This is expected to be
addressed in the 3.14 release.

Additionally, numeric and string literals in the code as well as strings
returned by @ref{12b9,,sys.intern()} are also immortalized.  This behavior is
expected to remain in the 3.14 free-threaded build.

@node Objets cadres<2>,Itérateurs<4>,Immortalization,Known limitations
@anchor{howto/free-threading-python frame-objects}@anchor{4f30}
@subsubsection Objets cadres


It is not safe to access @ref{6ca,,frame} objects from other
threads and doing so may cause your program to crash .  This means that
@ref{13e9,,sys._current_frames()} is generally not safe to use in a free-threaded
build.  Functions like @ref{6cc,,inspect.currentframe()} and @ref{6cb,,sys._getframe()}
are generally safe as long as the resulting frame object is not passed to
another thread.

@node Itérateurs<4>,Single-threaded performance,Objets cadres<2>,Known limitations
@anchor{howto/free-threading-python iterators}@anchor{4f31}
@subsubsection Itérateurs


Sharing the same iterator object between multiple threads is generally not
safe and threads may see duplicate or missing elements when iterating or crash
the interpreter.

@node Single-threaded performance,,Itérateurs<4>,Known limitations
@anchor{howto/free-threading-python single-threaded-performance}@anchor{4f32}
@subsubsection Single-threaded performance


The free-threaded build has additional overhead when executing Python code
compared to the default GIL-enabled build.  In 3.13, this overhead is about
40% on the pyperformance@footnote{https://pyperformance.readthedocs.io/} suite.
Programs that spend most of their time in C extensions or I/O will see
less of an impact.  The largest impact is because the specializing adaptive
interpreter (
@geindex Python Enhancement Proposals; PEP 659
PEP 659@footnote{https://peps.python.org/pep-0659/}) is disabled in the free-threaded build.  We expect
to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
expected to be reduced in upcoming Python release.   We are aiming for an
overhead of 10% or less on the pyperformance suite compared to the default
GIL-enabled build.

@node C API Extension Support for Free Threading,,Python experimental support for free threading,Les HOWTOs de Python
@anchor{howto/free-threading-extensions doc}@anchor{4f33}@anchor{howto/free-threading-extensions c-api-extension-support-for-free-threading}@anchor{4f34}@anchor{howto/free-threading-extensions freethreading-extensions-howto}@anchor{4f29}
@section C API Extension Support for Free Threading


Starting with the 3.13 release, CPython has experimental support for running
with the @ref{147,,global interpreter lock} (GIL) disabled in a configuration
called @ref{150c,,free threading}.  This document describes how to adapt C API
extensions to support free threading.

@menu
* Identifying the Free-Threaded Build in C:: 
* Module Initialization:: 
* General API Guidelines:: 
* Borrowed References:: 
* Memory Allocation APIs:: 
* Thread State and GIL APIs:: 
* Protecting Internal Extension State:: 
* Building Extensions for the Free-Threaded Build:: 

@end menu

@node Identifying the Free-Threaded Build in C,Module Initialization,,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions identifying-the-free-threaded-build-in-c}@anchor{4f35}
@subsection Identifying the Free-Threaded Build in C


The CPython C API exposes the @code{Py_GIL_DISABLED} macro: in the free-threaded
build it's defined to @code{1}, and in the regular build it's not defined.
You can use it to enable code that only runs under the free-threaded build:

@example
#ifdef Py_GIL_DISABLED
/* code that only runs in the free-threaded build */
#endif
@end example

@node Module Initialization,General API Guidelines,Identifying the Free-Threaded Build in C,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions module-initialization}@anchor{4f36}
@subsection Module Initialization


Extension modules need to explicitly indicate that they support running with
the GIL disabled; otherwise importing the extension will raise a warning and
enable the GIL at runtime.

There are two ways to indicate that an extension module supports running with
the GIL disabled depending on whether the extension uses multi-phase or
single-phase initialization.

@menu
* Multi-Phase Initialization:: 
* Single-Phase Initialization:: 

@end menu

@node Multi-Phase Initialization,Single-Phase Initialization,,Module Initialization
@anchor{howto/free-threading-extensions multi-phase-initialization}@anchor{4f37}
@subsubsection Multi-Phase Initialization


Extensions that use multi-phase initialization (i.e.,
@ref{48f0,,PyModuleDef_Init()}) should add a @ref{157,,Py_mod_gil} slot in the
module definition.  If your extension supports older versions of CPython,
you should guard the slot with a @ref{741,,PY_VERSION_HEX} check.

@example
static struct PyModuleDef_Slot module_slots[] = @{
    ...
#if PY_VERSION_HEX >= 0x030D0000
    @{Py_mod_gil, Py_MOD_GIL_NOT_USED@},
#endif
    @{0, NULL@}
@};

static struct PyModuleDef moduledef = @{
    PyModuleDef_HEAD_INIT,
    .m_slots = module_slots,
    ...
@};
@end example

@node Single-Phase Initialization,,Multi-Phase Initialization,Module Initialization
@anchor{howto/free-threading-extensions single-phase-initialization}@anchor{4f38}
@subsubsection Single-Phase Initialization


Extensions that use single-phase initialization (i.e.,
@ref{47c4,,PyModule_Create()}) should call @ref{178,,PyUnstable_Module_SetGIL()} to
indicate that they support running with the GIL disabled.  The function is
only defined in the free-threaded build, so you should guard the call with
@code{#ifdef Py_GIL_DISABLED} to avoid compilation errors in the regular build.

@example
static struct PyModuleDef moduledef = @{
    PyModuleDef_HEAD_INIT,
    ...
@};

PyMODINIT_FUNC
PyInit_mymodule(void)
@{
    PyObject *m = PyModule_Create(&moduledef);
    if (m == NULL) @{
        return NULL;
    @}
#ifdef Py_GIL_DISABLED
    PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);
#endif
    return m;
@}
@end example

@node General API Guidelines,Borrowed References,Module Initialization,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions general-api-guidelines}@anchor{4f39}
@subsection General API Guidelines


Most of the C API is thread-safe, but there are some exceptions.


@itemize *

@item 
`Struct Fields': Accessing fields in Python C API objects or structs
directly is not thread-safe if the field may be concurrently modified.

@item 
`Macros': Accessor macros like @ref{4863,,PyList_GET_ITEM} and
@ref{384,,PyList_SET_ITEM} do not perform any error checking or locking.
These macros are not thread-safe if the container object may be modified
concurrently.

@item 
`Borrowed References': C API functions that return
@ref{334,,borrowed references} may not be thread-safe if
the containing object is modified concurrently.  See the section on
@ref{4f3a,,borrowed references} for more information.
@end itemize

@menu
* Container Thread Safety:: 

@end menu

@node Container Thread Safety,,,General API Guidelines
@anchor{howto/free-threading-extensions container-thread-safety}@anchor{4f3b}
@subsubsection Container Thread Safety


Containers like @ref{4a6f,,PyListObject},
@ref{3b8,,PyDictObject}, and @ref{4b5d,,PySetObject} perform internal locking
in the free-threaded build.  For example, the @ref{48d8,,PyList_Append()} will
lock the list before appending an item.

@menu
* PyDict_Next:: 

@end menu

@node PyDict_Next,,,Container Thread Safety
@anchor{howto/free-threading-extensions id1}@anchor{4f3c}@anchor{howto/free-threading-extensions pydict-next}@anchor{4f3d}
@subsubsection @code{PyDict_Next}


A notable exception is @ref{159a,,PyDict_Next()}, which does not lock the
dictionary.  You should use @ref{4b55,,Py_BEGIN_CRITICAL_SECTION} to protect
the dictionary while iterating over it if the dictionary may be concurrently
modified:

@example
Py_BEGIN_CRITICAL_SECTION(dict);
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(dict, &pos, &key, &value)) @{
    ...
@}
Py_END_CRITICAL_SECTION();
@end example

@node Borrowed References,Memory Allocation APIs,General API Guidelines,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions borrowed-references}@anchor{4f3e}
@subsection Borrowed References

@anchor{howto/free-threading-extensions id2}@anchor{4f3a}
Some C API functions return @ref{334,,borrowed references}.
These APIs are not thread-safe if the containing object is modified
concurrently.  For example, it's not safe to use @ref{352,,PyList_GetItem()}
if the list may be modified concurrently.

The following table lists some borrowed reference APIs and their replacements
that return @ref{333,,strong references}.


@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 
@headitem

Borrowed reference API

@tab

Strong reference API

@item

@ref{352,,PyList_GetItem()}

@tab

@ref{351,,PyList_GetItemRef()}

@item

@ref{37d,,PyDict_GetItem()}

@tab

@ref{330,,PyDict_GetItemRef()}

@item

@ref{332,,PyDict_GetItemWithError()}

@tab

@ref{330,,PyDict_GetItemRef()}

@item

@ref{37e,,PyDict_GetItemString()}

@tab

@ref{331,,PyDict_GetItemStringRef()}

@item

@ref{336,,PyDict_SetDefault()}

@tab

@ref{335,,PyDict_SetDefaultRef()}

@item

@ref{159a,,PyDict_Next()}

@tab

none (see @ref{4f3d,,PyDict_Next})

@item

@ref{36f,,PyWeakref_GetObject()}

@tab

@ref{36e,,PyWeakref_GetRef()}

@item

@ref{3b6,,PyWeakref_GET_OBJECT()}

@tab

@ref{36e,,PyWeakref_GetRef()}

@item

@ref{34f,,PyImport_AddModule()}

@tab

@ref{34e,,PyImport_AddModuleRef()}

@end multitable


Not all APIs that return borrowed references are problematic.  For
example, @ref{47d7,,PyTuple_GetItem()} is safe because tuples are immutable.
Similarly, not all uses of the above APIs are problematic.  For example,
@ref{37d,,PyDict_GetItem()} is often used for parsing keyword argument
dictionaries in function calls; those keyword argument dictionaries are
effectively private (not accessible by other threads), so using borrowed
references in that context is safe.

Some of these functions were added in Python 3.13.  You can use the
pythoncapi-compat@footnote{https://github.com/python/pythoncapi-compat} package
to provide implementations of these functions for older Python versions.

@node Memory Allocation APIs,Thread State and GIL APIs,Borrowed References,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions free-threaded-memory-allocation}@anchor{4cc2}@anchor{howto/free-threading-extensions memory-allocation-apis}@anchor{4f3f}
@subsection Memory Allocation APIs


Python's memory management C API provides functions in three different
@ref{4cbd,,allocation domains}: "raw", "mem", and "object".
For thread-safety, the free-threaded build requires that only Python objects
are allocated using the object domain, and that all Python object are
allocated using that domain.  This differs from the prior Python versions,
where this was only a best practice and not a hard requirement.

@cartouche
@quotation Note 
Search for uses of @ref{c56,,PyObject_Malloc()} in your
extension and check that the allocated memory is used for Python objects.
Use @ref{c54,,PyMem_Malloc()} to allocate buffers instead of
@ref{c56,,PyObject_Malloc()}.
@end quotation
@end cartouche

@node Thread State and GIL APIs,Protecting Internal Extension State,Memory Allocation APIs,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions thread-state-and-gil-apis}@anchor{4f40}
@subsection Thread State and GIL APIs


Python provides a set of functions and macros to manage thread state and the
GIL, such as:


@itemize *

@item 
@ref{3a2,,PyGILState_Ensure()} and @ref{3a3,,PyGILState_Release()}

@item 
@ref{39f,,PyEval_SaveThread()} and @ref{3a0,,PyEval_RestoreThread()}

@item 
@ref{47dd,,Py_BEGIN_ALLOW_THREADS} and @ref{a7c,,Py_END_ALLOW_THREADS}
@end itemize

These functions should still be used in the free-threaded build to manage
thread state even when the @ref{158,,GIL} is disabled.  For example, if you
create a thread outside of Python, you must call @ref{3a2,,PyGILState_Ensure()}
before calling into the Python API to ensure that the thread has a valid
Python thread state.

You should continue to call @ref{39f,,PyEval_SaveThread()} or
@ref{47dd,,Py_BEGIN_ALLOW_THREADS} around blocking operations, such as I/O or
lock acquisitions, to allow other threads to run the
@ref{18a7,,cyclic garbage collector}.

@node Protecting Internal Extension State,Building Extensions for the Free-Threaded Build,Thread State and GIL APIs,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions protecting-internal-extension-state}@anchor{4f41}
@subsection Protecting Internal Extension State


Your extension may have internal state that was previously protected by the
GIL.  You may need to add locking to protect this state.  The approach will
depend on your extension, but some common patterns include:


@itemize *

@item 
`Caches': global caches are a common source of shared state.  Consider
using a lock to protect the cache or disabling it in the free-threaded build
if the cache is not critical for performance.

@item 
`Global State': global state may need to be protected by a lock or moved
to thread local storage. C11 and C++11 provide the @code{thread_local} or
@code{_Thread_local} for
thread-local storage@footnote{https://en.cppreference.com/w/c/language/storage_duration}.
@end itemize

@node Building Extensions for the Free-Threaded Build,,Protecting Internal Extension State,C API Extension Support for Free Threading
@anchor{howto/free-threading-extensions building-extensions-for-the-free-threaded-build}@anchor{4f42}
@subsection Building Extensions for the Free-Threaded Build


C API extensions need to be built specifically for the free-threaded build.
The wheels, shared libraries, and binaries are indicated by a @code{t} suffix.


@itemize *

@item 
pypa/manylinux@footnote{https://github.com/pypa/manylinux} supports the
free-threaded build, with the @code{t} suffix, such as @code{python3.13t}.

@item 
pypa/cibuildwheel@footnote{https://github.com/pypa/cibuildwheel} supports the
free-threaded build if you set
CIBW_FREE_THREADED_SUPPORT@footnote{https://cibuildwheel.pypa.io/en/stable/options/#free-threaded-support}.
@end itemize

@menu
* Limited C API and Stable ABI:: 
* Windows: Windows<76>. 

@end menu

@node Limited C API and Stable ABI,Windows<76>,,Building Extensions for the Free-Threaded Build
@anchor{howto/free-threading-extensions limited-c-api-and-stable-abi}@anchor{4f43}
@subsubsection Limited C API and Stable ABI


The free-threaded build does not currently support the
@ref{38c,,Limited C API} or the stable ABI.  If you use
setuptools@footnote{https://setuptools.pypa.io/en/latest/setuptools.html} to build
your extension and currently set @code{py_limited_api=True} you can use
@code{py_limited_api=not sysconfig.get_config_var("Py_GIL_DISABLED")} to opt out
of the limited API when building with the free-threaded build.

@cartouche
@quotation Note 
You will need to build separate wheels specifically for the free-threaded
build.  If you currently use the stable ABI, you can continue to build a
single wheel for multiple non-free-threaded Python versions.
@end quotation
@end cartouche

@node Windows<76>,,Limited C API and Stable ABI,Building Extensions for the Free-Threaded Build
@anchor{howto/free-threading-extensions windows}@anchor{4f44}
@subsubsection Windows


Due to a limitation of the official Windows installer, you will need to
manually define @code{Py_GIL_DISABLED=1} when building extensions from source.


@subsubheading Voir aussi


Porting Extension Modules to Support Free-Threading@footnote{https://py-free-threading.github.io/porting/}:
A community-maintained porting guide for extension authors.


General:


@itemize *

@item 
@ref{7c3,,Bonnes pratiques concernant les annotations}

@item 
@ref{2dce,,Tutoriel argparse}

@item 
@ref{14a2,,Descriptor Guide}

@item 
@ref{4dce,,Guide sur l'utilisation d'Enum}

@item 
@ref{4dff,,Guide pratique ; programmation fonctionnelle}

@item 
@ref{3b7c,,Introduction au module ipaddress}

@item 
@ref{4e1d,,Tutoriel sur la journalisation}

@item 
@ref{11d4,,Recettes pour la journalisation}

@item 
@ref{2272,,Guide des expressions régulières}

@item 
@ref{2107,,Sorting Techniques}

@item 
@ref{1282,,Guide Unicode}

@item 
@ref{3956,,Guide pratique ; récupérer des ressources web en utilisant le module urllib}
@end itemize

Advanced development:


@itemize *

@item 
@ref{2ec1,,Programmation Curses avec Python}

@item 
@ref{4f27,,Python experimental support for free threading}

@item 
@ref{4f29,,C API Extension Support for Free Threading}

@item 
@ref{4bbd,,Isolating Extension Modules}

@item 
@ref{145e,,The Python 2.3 Method Resolution Order}

@item 
@ref{33a2,,Guide pratique ; programmation avec les sockets}

@item 
@ref{4f1c,,timer file descriptor HOWTO}

@item 
@ref{12bf,,Portage des modules d'extension vers Python 3}
@end itemize

Debugging and profiling:


@itemize *

@item 
@ref{4dc0,,Debugging C API extensions and CPython Internals with GDB}

@item 
@ref{c5a,,Instrumenter CPython avec DTrace et SystemTap}

@item 
@ref{18d,,Python support for the Linux perf profiler}
@end itemize

@node Questions fréquemment posées sur Python,Deprecations,Les HOWTOs de Python,Top
@anchor{faq/index doc}@anchor{4f45}@anchor{faq/index faq-index}@anchor{1c94}@anchor{faq/index python-frequently-asked-questions}@anchor{4f46}
@chapter Questions fréquemment posées sur Python


@menu
* FAQ générale sur Python:: 
* FAQ de programmation:: 
* FAQ sur l'histoire et la conception:: 
* FAQ sur la bibliothèque et les extensions:: 
* FAQ extension/intégration:: 
* FAQ ; Python et Windows: FAQ Python et Windows. 
* FAQ interface graphique:: 
* FAQ "Pourquoi Python est installé sur mon ordinateur ?":: 

@end menu

@node FAQ générale sur Python,FAQ de programmation,,Questions fréquemment posées sur Python
@anchor{faq/general doc}@anchor{4f47}@anchor{faq/general general-python-faq}@anchor{4f48}
@section FAQ générale sur Python



@menu
* Informations générales:: 
* Python c'est le monde réel:: 

@end menu

@node Informations générales,Python c'est le monde réel,,FAQ générale sur Python
@anchor{faq/general general-information}@anchor{4f49}
@subsection Informations générales


@menu
* Qu'est-ce que Python ?:: 
* Qu'est ce que la Python Software Foundation ?:: 
* Existe-t-il des restrictions liées à la propriété intellectuelle quant à l'utilisation de Python ?:: 
* Pourquoi Python a été créé ?:: 
* Pour quoi Python est-il fait ?:: 
* Comment fonctionne le numérotage des versions de Python ?:: 
* Comment obtenir une copie du code source de Python ?:: 
* Comment obtenir la documentation de Python ?:: 
* Je n'ai jamais programmé avant. Existe-t-il un tutoriel Python ?: Je n'ai jamais programmé avant Existe-t-il un tutoriel Python ?. 
* Y a-t-il un forum ou une liste de diffusion dédié à Python ?:: 
* Comment obtenir une version bêta test de Python ?:: 
* Comment soumettre un rapport de bogues ou un correctif pour Python ?:: 
* Existe-t-il des articles publiés au sujet de Python auxquels je peux me référer ?:: 
* Y a-t-il des livres au sujet de Python ?:: 
* Où www.python.org est-il localisé dans le monde ?: Où www python org est-il localisé dans le monde ?. 
* Pourquoi le nom Python ?:: 
* Dois-je aimer "Monty Python's Flying Circus" ?:: 

@end menu

@node Qu'est-ce que Python ?,Qu'est ce que la Python Software Foundation ?,,Informations générales
@anchor{faq/general what-is-python}@anchor{4f4a}
@subsubsection Qu'est-ce que Python ?


Python est un langage de programmation interprété, interactif et orienté objet.  Il intègre des modules, des exceptions, un typage dynamique, des types de données dynamiques de très haut niveau et des classes.  Il gère de multiples paradigmes de programmation au-delà de la programmation orientée objet, tels que la programmation procédurale et fonctionnelle. Python combine une puissance remarquable avec une syntaxe très claire. Il possède des interfaces avec de nombreux appels système et bibliothèques, ainsi qu'avec divers systèmes d'interfaces graphiques, et il peut être étendu avec du C ou du C++.  Il est également utilisable comme langage d'extension pour les applications qui nécessitent une interface de programmation. Enfin, Python est portable : il fonctionne sur de nombreuses variantes d'Unix, y compris Linux et macOS, et sur Windows.

Pour en savoir plus, commencez par @ref{1b68,,Le tutoriel Python}. Le « Guide des Débutants pour Python@footnote{https://wiki.python.org/moin/BeginnersGuide} » renvoie vers d'autres tutoriels et ressources d'initiation pour apprendre Python.

@node Qu'est ce que la Python Software Foundation ?,Existe-t-il des restrictions liées à la propriété intellectuelle quant à l'utilisation de Python ?,Qu'est-ce que Python ?,Informations générales
@anchor{faq/general what-is-the-python-software-foundation}@anchor{4f4b}
@subsubsection Qu'est ce que la Python Software Foundation ?


La Python Software Foundation (PSF) est une organisation indépendante à but non lucratif qui détient les droits d'auteur sur les versions Python 2.1 et plus récentes. La mission de la PSF est de faire progresser les technologies ouvertes (`open source') relatives au langage de programmation Python et de promouvoir son utilisation. Le page d'accueil de la PSF se trouve à l'adresse suivante : @indicateurl{https://www.python.org/psf/}.

Si vous utilisez Python et que vous le trouvez utile, merci de contribuer par le biais de la page de donation de la PSF@footnote{https://www.python.org/psf/donations/}.

@node Existe-t-il des restrictions liées à la propriété intellectuelle quant à l'utilisation de Python ?,Pourquoi Python a été créé ?,Qu'est ce que la Python Software Foundation ?,Informations générales
@anchor{faq/general are-there-copyright-restrictions-on-the-use-of-python}@anchor{4f4c}
@subsubsection Existe-t-il des restrictions liées à la propriété intellectuelle quant à l'utilisation de Python ?


Vous pouvez faire ce que vous souhaitez avec la source, tant que vous respecterez la licence d'utilisation et que vous l'afficherez dans toute documentation que vous produirez au sujet de Python. Si vous respectez ces règles, vous pouvez utiliser Python dans un cadre commercial, vendre le code source ou la forme binaire (modifiée ou non), ou vendre des produits qui incorporent Python sous une forme quelconque. Bien entendu, nous souhaiterions avoir connaissance de tous les projets commerciaux utilisant Python.

See the license page@footnote{https://docs.python.org/3/license.html} to find further
explanations and the full text of the PSF License.

Le logo de Python est une marque déposée, et dans certains cas une autorisation est nécessaire pour l'utiliser. Consultez la politique d'utilisation de la marque@footnote{https://www.python.org/psf/trademarks/} pour plus d'informations.

@node Pourquoi Python a été créé ?,Pour quoi Python est-il fait ?,Existe-t-il des restrictions liées à la propriété intellectuelle quant à l'utilisation de Python ?,Informations générales
@anchor{faq/general why-was-python-created-in-the-first-place}@anchor{4f4d}
@subsubsection Pourquoi Python a été créé ?


Voici un `très' bref résumé de comment tout a commencé, écrit par Guido van Rossum (puis traduit en français) :

@quotation

J'avais une expérience complète avec la mise en œuvre du langage interprété ABC au sein du CWI, et en travaillant dans ce groupe j'ai appris beaucoup à propos de la conception de langage. C'est l'origine de nombreuses fonctionnalités de Python, notamment l'utilisation de l'indentation pour le groupement et l'inclusion de types de très haut niveau (bien que dans les détails ils soient tous différents dans Python).

J'avais un certain nombre de différends avec le langage ABC, mais j'aimais aussi beaucoup de ses fonctionnalités. Il était impossible d'étendre le langage ABC (ou ses implémentations) pour remédier à mes réclamations -- en vérité le manque d'extensibilité était l'un des plus gros problème. J'avais un peu d'expérience avec l'utilisation de Modula-2+ et j'en ai parlé avec les concepteurs de Modula-3 et j'ai lu le rapport sur Modula-3. Modula-3 est à l'origine de la syntaxe et de la sémantique utilisée pour les exceptions, et quelques autres fonctionnalités en Python.

Je travaillais sur un groupe de systèmes d'exploitation distribués Amoeba au CWI. Nous avions besoin d'un meilleur moyen pour gérer l'administration système qu'écrire un programme en C ou en script Bourne shell, puisque l'Amoeba avait sa propre interface d'appels système qui n'était pas facilement accessible depuis les scripts Bourne shell. Mon expérience avec le traitement des erreurs dans l'Amoeba m'a vraiment fait prendre conscience de l'importance des exceptions en tant que fonctionnalité d'un langage de programmation.

Il m'est venu à l'esprit qu'un langage de script avec une syntaxe comme ABC mais avec un accès aux appels systèmes d'Amoeba remplirait les besoins. J'ai réalisé que ce serait idiot d'écrire un langage spécifique à Amoeba, donc j'ai décidé que j'avais besoin d'un langage qui serait généralement extensible.

Pendant les vacances de Noël 1989, j'avais beaucoup de temps à disposition, donc j'ai décidé de faire un essai. Durant l'année suivante, j'ai encore beaucoup travaillé dessus sur mon propre temps. Python a été utilisé dans le projet Amoeba avec un succès croissant, et les retours de mes collègues m'ont permis d'ajouter beaucoup des premières améliorations.

En Février 1991, juste après un peu plus d'un an de développement, j'ai décidé de le poster sur USENET. Le reste se trouve dans le fichier « Misc/HISTORY ».
@end quotation

@node Pour quoi Python est-il fait ?,Comment fonctionne le numérotage des versions de Python ?,Pourquoi Python a été créé ?,Informations générales
@anchor{faq/general what-is-python-good-for}@anchor{4f4e}
@subsubsection Pour quoi Python est-il fait ?


Python est un langage de programmation haut niveau généraliste qui peut être utilisé pour pallier à différents problèmes.

Le langage vient avec une bibliothèque standard importante qui couvre des domaines tels que le traitement des chaînes de caractères (expressions régulières, Unicode, calcul de différences entre les fichiers), les protocoles internet (HTTP, FTP, SMTP, XML-RPC, POP, IMAP, script CGI), ingénierie logicielle (tests unitaires, enregistrement, analyse de code Python), et interfaces pour systèmes d'exploitation (appels système, système de fichiers, connecteurs TCP/IP). Regardez la table des matières @ref{143,,La bibliothèque standard} pour avoir une idée de ce qui est disponible. Une grande variété de greffons tiers existent aussi. Consultez le sommaire des paquets Python@footnote{https://pypi.org} pour trouver les paquets qui pourraient vous intéresser.

@node Comment fonctionne le numérotage des versions de Python ?,Comment obtenir une copie du code source de Python ?,Pour quoi Python est-il fait ?,Informations générales
@anchor{faq/general faq-version-numbering-scheme}@anchor{4f4f}@anchor{faq/general how-does-the-python-version-numbering-scheme-work}@anchor{4f50}
@subsubsection Comment fonctionne le numérotage des versions de Python ?


Python versions are numbered "A.B.C" or "A.B":


@itemize *

@item 
`A' is the major version number -- it is only incremented for really major
changes in the language.

@item 
`B' is the minor version number -- it is incremented for less earth-shattering
changes.

@item 
`C' is the micro version number -- it is incremented for each bugfix release.
@end itemize

Not all releases are bugfix releases.  In the run-up to a new feature release, a
series of development releases are made, denoted as alpha, beta, or release
candidate.  Alphas are early releases in which interfaces aren't yet finalized;
it's not unexpected to see an interface change between two alpha releases.
Betas are more stable, preserving existing interfaces but possibly adding new
modules, and release candidates are frozen, making no changes except as needed
to fix critical bugs.

Alpha, beta and release candidate versions have an additional suffix:


@itemize *

@item 
The suffix for an alpha version is "aN" for some small number `N'.

@item 
The suffix for a beta version is "bN" for some small number `N'.

@item 
The suffix for a release candidate version is "rcN" for some small number `N'.
@end itemize

In other words, all versions labeled `2.0aN' precede the versions labeled
`2.0bN', which precede versions labeled `2.0rcN', and `those' precede 2.0.

Vous pouvez aussi trouver des versions avec un signe « + » en suffixe, par exemple « 2.2+ ». Ces versions sont non distribuées, construites directement depuis le dépôt de développement de CPython. En pratique, après la sortie finale d'une version mineure, la version est augmentée à la prochaine version mineure, qui devient la version `a0', c'est-à-dire `2.4a0'.

See the Developer's Guide@footnote{https://devguide.python.org/developer-workflow/development-cycle/}
for more information about the development cycle, and
@geindex Python Enhancement Proposals; PEP 387
PEP 387@footnote{https://peps.python.org/pep-0387/} to learn more about Python's backward compatibility policy.  See also
the documentation for @ref{177,,sys.version}, @ref{42b4,,sys.hexversion}, and
@ref{68b,,sys.version_info}.

@node Comment obtenir une copie du code source de Python ?,Comment obtenir la documentation de Python ?,Comment fonctionne le numérotage des versions de Python ?,Informations générales
@anchor{faq/general how-do-i-obtain-a-copy-of-the-python-source}@anchor{4f51}
@subsubsection Comment obtenir une copie du code source de Python ?


La dernière version du code source déployée est toujours disponible sur python.org, à @indicateurl{https://www.python.org/downloads/}. Le code source de la dernière version en développement peut être obtenue à @indicateurl{https://github.com/python/cpython/}.

Le code source est dans une archive `gzippée' au format `tar', elle contient le code source C complet, la documentation formatée avec Sphinx, les libraires Python, des exemples de programmes, et plusieurs morceaux de code utiles distribuables librement. Le code source sera compilé et prêt à fonctionner immédiatement sur la plupart des plateformes UNIX.

Consultez la section Premiers pas du Guide des Développeurs Python@footnote{https://devguide.python.org/setup/} pour plus d'informations sur comment obtenir le code source et le compiler.

@node Comment obtenir la documentation de Python ?,Je n'ai jamais programmé avant Existe-t-il un tutoriel Python ?,Comment obtenir une copie du code source de Python ?,Informations générales
@anchor{faq/general how-do-i-get-documentation-on-python}@anchor{4f52}
@subsubsection Comment obtenir la documentation de Python ?


La documentation standard pour la version stable actuelle est disponible à @indicateurl{https://docs.python.org/3/}.  Des versions aux formats PDF, texte et HTML sont aussi disponibles à @indicateurl{https://docs.python.org/3/download.html}.

La documentation est écrite au format `reStructuredText' et traitée par l'outil de documentation Sphinx@footnote{https://sphinx-doc.org/}. La source du `reStructuredText' pour la documentation constitue une partie des sources de Python.

@node Je n'ai jamais programmé avant Existe-t-il un tutoriel Python ?,Y a-t-il un forum ou une liste de diffusion dédié à Python ?,Comment obtenir la documentation de Python ?,Informations générales
@anchor{faq/general i-ve-never-programmed-before-is-there-a-python-tutorial}@anchor{4f53}
@subsubsection Je n'ai jamais programmé avant. Existe-t-il un tutoriel Python ?


Il y a de nombreux tutoriels et livres disponibles. La documentation standard inclut @ref{1b68,,Le tutoriel Python}.

Consultez le Guide du Débutant@footnote{https://wiki.python.org/moin/BeginnersGuide} afin de trouver des informations pour les développeurs Python débutants, incluant une liste de tutoriels.

@node Y a-t-il un forum ou une liste de diffusion dédié à Python ?,Comment obtenir une version bêta test de Python ?,Je n'ai jamais programmé avant Existe-t-il un tutoriel Python ?,Informations générales
@anchor{faq/general is-there-a-newsgroup-or-mailing-list-devoted-to-python}@anchor{4f54}
@subsubsection Y a-t-il un forum ou une liste de diffusion dédié à Python ?


Il y a un forum, @code{comp.lang.python} et une liste de diffusion, python-list@footnote{https://mail.python.org/mailman/listinfo/python-list}. Le forum et la liste de diffusion sont des passerelles l'un vers l'autre -- si vous pouvez lire les `news' ce n'est pas inutile de souscrire à la liste de diffusion. @code{comp.lang.python} a beaucoup d'activité, il reçoit des centaines de messages chaque jour, et les lecteurs du réseau Usenet sont souvent plus capables de faire face à ce volume.

Announcements of new software releases and events can be found in
comp.lang.python.announce, a low-traffic moderated list that receives about five
postings per day.  It's available as the python-announce mailing list@footnote{https://mail.python.org/mailman3/lists/python-announce-list.python.org/}.

Plus d'informations à propos des autres listes de diffusion et forums peuvent être trouvées à @indicateurl{https://www.python.org/community/lists/}.

@node Comment obtenir une version bêta test de Python ?,Comment soumettre un rapport de bogues ou un correctif pour Python ?,Y a-t-il un forum ou une liste de diffusion dédié à Python ?,Informations générales
@anchor{faq/general how-do-i-get-a-beta-test-version-of-python}@anchor{4f55}
@subsubsection Comment obtenir une version bêta test de Python ?


Les versions alpha et bêta sont disponibles depuis @indicateurl{https://www.python.org/downloads/}. Toutes les versions sont annoncées sur les `newsgroups' `comp.lang.python' et `comp.lang.python.announce' ainsi que sur la page d'accueil de Python à @indicateurl{https://www.python.org/}; un flux RSS d'actualités y est aussi disponible.

Vous pouvez aussi accéder aux de Python en développement grâce à Git. Voir Le Guide du Développeur Python@footnote{https://devguide.python.org/} pour plus de détails.

@node Comment soumettre un rapport de bogues ou un correctif pour Python ?,Existe-t-il des articles publiés au sujet de Python auxquels je peux me référer ?,Comment obtenir une version bêta test de Python ?,Informations générales
@anchor{faq/general how-do-i-submit-bug-reports-and-patches-for-python}@anchor{4f56}
@subsubsection Comment soumettre un rapport de bogues ou un correctif pour Python ?


Pour signaler un bogue ou soumettre un correctif, utilisez le système de suivi des problèmes à l'adresse @indicateurl{https://github.com/python/cpython/issues}.

Pour davantage d'informations sur comment Python est développé, consultez le Guide du Développeur Python@footnote{https://devguide.python.org/}.

@node Existe-t-il des articles publiés au sujet de Python auxquels je peux me référer ?,Y a-t-il des livres au sujet de Python ?,Comment soumettre un rapport de bogues ou un correctif pour Python ?,Informations générales
@anchor{faq/general are-there-any-published-articles-about-python-that-i-can-reference}@anchor{4f57}
@subsubsection Existe-t-il des articles publiés au sujet de Python auxquels je peux me référer ?


C'est probablement mieux de vous référer à votre livre favori à propos de Python.

Le tout premier article@footnote{https://ir.cwi.nl/pub/18204} sur Python a été écrit en 1991 et est aujourd'hui assez dépassé.

@quotation

Guido van Rossum et Jelke de Boer, « `Interactively Testing Remote Servers Using the Python Programming Language' », CWI Quarterly, Volume 4, Issue 4 (December 1991), Amsterdam, pp 283--303.
@end quotation

@node Y a-t-il des livres au sujet de Python ?,Où www python org est-il localisé dans le monde ?,Existe-t-il des articles publiés au sujet de Python auxquels je peux me référer ?,Informations générales
@anchor{faq/general are-there-any-books-on-python}@anchor{4f58}
@subsubsection Y a-t-il des livres au sujet de Python ?


Oui, il y en a beaucoup, et d'autres sont en cours de publication. Voir le wiki python à @indicateurl{https://wiki.python.org/moin/PythonBooks} pour avoir une liste.

Vous pouvez aussi chercher chez les revendeurs de livres en ligne avec le terme « Python » et éliminer les références concernant les Monty Python, ou peut-être faire une recherche avec les termes « langage » et « Python ».

@node Où www python org est-il localisé dans le monde ?,Pourquoi le nom Python ?,Y a-t-il des livres au sujet de Python ?,Informations générales
@anchor{faq/general where-in-the-world-is-www-python-org-located}@anchor{4f59}
@subsubsection Où www.python.org est-il localisé dans le monde ?


L'infrastructure du projet Python est située dans le monde entier et est gérée par l'équipe de l'infrastructure Python. Plus de détails ici@footnote{https://infra.psf.io}.

@node Pourquoi le nom Python ?,Dois-je aimer "Monty Python's Flying Circus" ?,Où www python org est-il localisé dans le monde ?,Informations générales
@anchor{faq/general why-is-it-called-python}@anchor{4f5a}
@subsubsection Pourquoi le nom Python ?


Quand il a commencé à implémenter Python, Guido van Rossum a aussi lu le script publié par "Monty Python's Flying Circus"@footnote{https://en.wikipedia.org/wiki/Monty_Python}, une série comique des années 1970 diffusée par la BBC. Van Rossum a pensé qu'il avait besoin d'un nom court, unique, et un peu mystérieux, donc il a décidé de l'appeler le langage Python.

@node Dois-je aimer "Monty Python's Flying Circus" ?,,Pourquoi le nom Python ?,Informations générales
@anchor{faq/general do-i-have-to-like-monty-python-s-flying-circus}@anchor{4f5b}
@subsubsection Dois-je aimer "Monty Python's Flying Circus" ?


Non, mais ça peut aider. :)

@node Python c'est le monde réel,,Informations générales,FAQ générale sur Python
@anchor{faq/general python-in-the-real-world}@anchor{4f5c}
@subsection Python c'est le monde réel


@menu
* Quel est le niveau de stabilité de Python ?:: 
* Combien de personnes utilisent Python ?:: 
* Y a-t-il un nombre de projets significatif réalisés en Python ?:: 
* Quelles sont les nouveautés en développement attendues pour Python ?:: 
* Est-il raisonnable de proposer des changements incompatibles dans Python ?:: 
* Existe-t-il un meilleur langage de programmation pour les programmeurs débutants ?:: 

@end menu

@node Quel est le niveau de stabilité de Python ?,Combien de personnes utilisent Python ?,,Python c'est le monde réel
@anchor{faq/general how-stable-is-python}@anchor{4f5d}
@subsubsection Quel est le niveau de stabilité de Python ?


Very stable.  New, stable releases have been coming out roughly every 6 to 18
months since 1991, and this seems likely to continue.  As of version 3.9,
Python will have a new feature release every 12 months (
@geindex Python Enhancement Proposals; PEP 602
PEP 602@footnote{https://peps.python.org/pep-0602/}).

The developers issue bugfix releases of older versions, so the stability of
existing releases gradually improves.  Bugfix releases, indicated by a third
component of the version number (e.g. 3.5.3, 3.6.2), are managed for stability;
only fixes for known problems are included in a bugfix release, and it's
guaranteed that interfaces will remain the same throughout a series of bugfix
releases.

The latest stable releases can always be found on the Python download page@footnote{https://www.python.org/downloads/}.
Python 3.x is the recommended version and supported by most widely used libraries.
Python 2.x 
@geindex Python Enhancement Proposals; PEP 373
is not maintained anymore@footnote{https://peps.python.org/pep-0373/}.

@node Combien de personnes utilisent Python ?,Y a-t-il un nombre de projets significatif réalisés en Python ?,Quel est le niveau de stabilité de Python ?,Python c'est le monde réel
@anchor{faq/general how-many-people-are-using-python}@anchor{4f5e}
@subsubsection Combien de personnes utilisent Python ?


Il y a probablement des millions d'utilisateurs, bien qu'il soit difficile d'en déterminer le nombre exact.

Python est disponible en téléchargement gratuit, donc il n'y a pas de chiffres de ventes, il est disponible depuis de nombreux sites différents et il est inclus avec de beaucoup de distributions Linux, donc les statistiques de téléchargement ne donnent pas la totalité non plus.

Le forum `comp.lang.python' est très actif, mais tous les utilisateurs de Python ne laissent pas de messages dessus ou même ne le lisent pas.

@node Y a-t-il un nombre de projets significatif réalisés en Python ?,Quelles sont les nouveautés en développement attendues pour Python ?,Combien de personnes utilisent Python ?,Python c'est le monde réel
@anchor{faq/general have-any-significant-projects-been-done-in-python}@anchor{4f5f}
@subsubsection Y a-t-il un nombre de projets significatif réalisés en Python ?


Voir @indicateurl{https://www.python.org/about/success} pour avoir une liste des projets qui utilisent Python. En consultant les comptes-rendus des conférences Python précédentes@footnote{https://www.python.org/community/workshops/} il s'avère que les contributions proviennent de nombreux organismes et entreprises divers.

Les projets Python les plus connus incluent Mailman mailing list manager@footnote{https://www.list.org} et l'application serveur Zope@footnote{https://www.zope.org}.  Plusieurs distributions Linux, notamment Red Hat@footnote{https://www.redhat.com}, qui a écrit tout ou partie de son installateur et de son logiciel d'administration système en Python.  Les entreprises qui utilisent Python en interne comprennent Google, Yahoo, et Lucasfilm Ltd.

@node Quelles sont les nouveautés en développement attendues pour Python ?,Est-il raisonnable de proposer des changements incompatibles dans Python ?,Y a-t-il un nombre de projets significatif réalisés en Python ?,Python c'est le monde réel
@anchor{faq/general what-new-developments-are-expected-for-python-in-the-future}@anchor{4f60}
@subsubsection Quelles sont les nouveautés en développement attendues pour Python ?


Regardez les propositions d'amélioration de Python (« `Python Enhancement Proposals' », ou `PEP') sur @indicateurl{https://peps.python.org/}. Les PEP sont des documents techniques qui décrivent une nouvelle fonctionnalité qui a été suggérée pour Python, en fournissant une spécification technique concise et logique. Recherchez une PEP intitulée "Python X.Y Release Schedule", où X.Y est la version qui n'a pas encore été publiée.

New development is discussed on the python-dev mailing list@footnote{https://mail.python.org/mailman3/lists/python-dev.python.org/}.

@node Est-il raisonnable de proposer des changements incompatibles dans Python ?,Existe-t-il un meilleur langage de programmation pour les programmeurs débutants ?,Quelles sont les nouveautés en développement attendues pour Python ?,Python c'est le monde réel
@anchor{faq/general is-it-reasonable-to-propose-incompatible-changes-to-python}@anchor{4f61}
@subsubsection Est-il raisonnable de proposer des changements incompatibles dans Python ?


En général, non. Il y a déjà des millions de lignes de code de Python tout autour du monde, donc n'importe quel changement dans le langage qui rend invalide ne serait-ce qu'une très petite fraction du code de programmes existants doit être désapprouvé. Même si vous pouvez fournir un programme de conversion, il y a toujours des problèmes de mise à jour dans toutes les documentations, beaucoup de livres ont été écrits au sujet de Python, et nous ne voulons pas les rendre invalides soudainement.

En fournissant un rythme de mise à jour progressif qui est obligatoire si une fonctionnalité doit être changée.

@node Existe-t-il un meilleur langage de programmation pour les programmeurs débutants ?,,Est-il raisonnable de proposer des changements incompatibles dans Python ?,Python c'est le monde réel
@anchor{faq/general is-python-a-good-language-for-beginning-programmers}@anchor{4f62}
@subsubsection Existe-t-il un meilleur langage de programmation pour les programmeurs débutants ?


Oui.

Il reste commun pour les étudiants de commencer avec un langage procédural et à typage statique comme le Pascal, le C, ou un sous-ensemble du C++ ou Java. Les étudiants pourraient être mieux servis en apprenant Python comme premier langage. Python a une syntaxe très simple et cohérente ainsi qu'une vaste libraire standard, plus important encore, utiliser Python dans les cours d'initiation à la programmation permet aux étudiants de se concentrer sur les compétences de programmation les cruciales comme les problèmes de découpage et d'architecture. Avec Python, les étudiants peuvent rapidement aborder des concepts fondamentaux comme les boucles et les procédures. Ils peuvent même probablement travailler avec des objets définis dans leurs premiers cours.

Pour un étudiant qui n'a jamais programmé avant, utiliser un langage à typage statique peut sembler contre-nature. Cela représente une complexité additionnelle que l'étudiant doit maîtriser ce qui ralentit le cours. Les étudiants essaient d'apprendre à penser comme un ordinateur, décomposer les problèmes, établir une architecture propre, et résumer les données. Apprendre à utiliser un langage typé statiquement est important sur le long terme, ce n'est pas nécessairement la meilleure idée pour s'adresser aux étudiants durant leur tout premier cours.

De nombreux autres aspects de Python en font un bon premier langage. Comme Java, Python a une large bibliothèque standard donc les étudiants peuvent être assigner à la programmation de projets très tôt dans leur apprentissage qui `fait' quelque chose. Les missions ne sont pas restreintes aux quatre fonction standards. En utilisant la bibliothèque standard, les étudiants peuvent ressentir de la satisfaction en travaillant sur des applications réalistes alors qu'ils apprennent les fondamentaux de la programmation. Utiliser la bibliothèque standard apprend aussi aux étudiants la réutilisation de code. Les modules tiers tels que PyGame sont aussi très utiles pour étendre les compétences des étudiants.

L'interpréteur interactif de Python permet aux étudiants de tester les fonctionnalités du langage pendant qu'ils programment. Ils peuvent garder une fenêtre avec l'interpréteur en fonctionnement pendant qu'ils rentrent la source de leur programme dans une autre fenêtre. S'ils ne peuvent pas se souvenir des méthodes pour une liste, ils peuvent faire quelque chose comme ça :

@example
>>> L = []
>>> dir(L) 
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',
'__dir__', '__doc__', '__eq__', '__format__', '__ge__',
'__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__',
'__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__',
'__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',
'__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__',
'__sizeof__', '__str__', '__subclasshook__', 'append', 'clear',
'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove',
'reverse', 'sort']
>>> [d for d in dir(L) if '__' not in d]
['append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

>>> help(L.append)
Help on built-in function append:

append(...)
    L.append(object) -> None -- append object to end

>>> L.append(1)
>>> L
[1]
@end example

Avec l'interpréteur, la documentation n'est jamais loin des étudiants quand ils travaillent.

Il y a aussi de bons environnements de développement intégrés (EDIs) pour Python. IDLE est un EDI multiplateformes pour Python qui est écrit en Python en utilisant Tkinter. Les utilisateurs d'Emacs seront heureux d'apprendre qu'il y a un très bon mode Python pour Emacs. Tous ces environnements de développement intégrés fournissent la coloration syntaxique, l'auto-indentation, et l'accès à l'interpréteur interactif durant le codage. Consultez le wiki Python@footnote{https://wiki.python.org/moin/PythonEditors} pour une liste complète des environnements de développement intégrés.

Si vous voulez discuter de l'usage de Python dans l'éducation, vous devriez intéressé pour rejoindre la liste de diffusion pour l'enseignement@footnote{https://www.python.org/community/sigs/current/edu-sig}.

@node FAQ de programmation,FAQ sur l'histoire et la conception,FAQ générale sur Python,Questions fréquemment posées sur Python
@anchor{faq/programming doc}@anchor{4f63}@anchor{faq/programming programming-faq}@anchor{4f64}
@section FAQ de programmation



@menu
* Questions générales:: 
* Fondamentaux:: 
* Nombres et chaînes de caractères:: 
* Performances: Performances<4>. 
* Séquences (n-uplets / listes): Séquences n-uplets / listes. 
* Objets:: 
* Modules: Modules<5>. 

@end menu

@node Questions générales,Fondamentaux,,FAQ de programmation
@anchor{faq/programming general-questions}@anchor{4f65}
@subsection Questions générales


@menu
* Existe-t-il un débogueur de code source avec points d'arrêts@comma{} exécution pas-à-pas@comma{} etc. ?: Existe-t-il un débogueur de code source avec points d'arrêts exécution pas-à-pas etc ?. 
* Existe-t-il des outils pour aider à trouver des bogues ou faire de l'analyse statique de code ?:: 
* Comment créer un binaire autonome à partir d'un script Python ?:: 
* Existe-t-il des normes de développement ou un guide de style pour écrire des programmes Python ?:: 

@end menu

@node Existe-t-il un débogueur de code source avec points d'arrêts exécution pas-à-pas etc ?,Existe-t-il des outils pour aider à trouver des bogues ou faire de l'analyse statique de code ?,,Questions générales
@anchor{faq/programming is-there-a-source-code-level-debugger-with-breakpoints-single-stepping-etc}@anchor{4f66}
@subsubsection Existe-t-il un débogueur de code source avec points d'arrêts, exécution pas-à-pas, etc. ?


Oui.

Plusieurs débogueurs sont décrits ci-dessous et la fonction native @ref{231,,breakpoint()} permet d'utiliser n'importe lequel d'entre eux.

Le module @code{pdb} est un débogueur console simple, mais parfaitement adapté à Python. Il fait partie de la bibliothèque standard de Python, sa documentation se trouve dans le @ref{a4,,manuel de référence}. Vous pouvez vous inspirer du code de @code{pdb} pour écrire votre propre débogueur.

L'environnement de développement interactif IDLE, qui est fourni avec la distribution standard de Python (normalement disponible dans Tools/scripts/idle3@footnote{https://github.com/python/cpython/blob/main/Tools/scripts/idle3}) contient un débogueur graphique.

`PythonWin' est un environnement de développement intégré (EDI) Python qui embarque un débogueur graphique basé sur @code{pdb}. Le débogueur `PythonWin' colore les points d'arrêts et possède quelques fonctionnalités sympathiques, comme la possibilité de déboguer des programmes développés sans `PythonWin'.  `PythonWin' est disponible dans le projet pywin32@footnote{https://github.com/mhammond/pywin32} et fait partie de la distribution ActivePython@footnote{https://www.activestate.com/products/python/}.

Eric@footnote{https://eric-ide.python-projects.org/} est un EDI basé sur PyQt et l'outil d'édition Scintilla.

trepan3k@footnote{https://github.com/rocky/python3-trepan/} est un débogueur semblable à GDB.

Visual Studio Code@footnote{https://code.visualstudio.com/} est un EDI qui contient des outils de débogage. Il sait interagir avec les outils de gestion de versions.

Il existe de nombreux EDI Python propriétaires qui embarquent un débogueur graphique, notamment :


@itemize *

@item 
Wing IDE@footnote{https://wingware.com/} ;

@item 
Komodo IDE@footnote{https://www.activestate.com/products/komodo-ide/} ;

@item 
PyCharm@footnote{https://www.jetbrains.com/pycharm/} ;
@end itemize

@node Existe-t-il des outils pour aider à trouver des bogues ou faire de l'analyse statique de code ?,Comment créer un binaire autonome à partir d'un script Python ?,Existe-t-il un débogueur de code source avec points d'arrêts exécution pas-à-pas etc ?,Questions générales
@anchor{faq/programming are-there-tools-to-help-find-bugs-or-perform-static-analysis}@anchor{4f67}
@subsubsection Existe-t-il des outils pour aider à trouver des bogues ou faire de l'analyse statique de code ?


Oui.

Pylint@footnote{https://pylint.pycqa.org/en/latest/index.html} et Pyflakes@footnote{https://github.com/PyCQA/pyflakes} font des vérifications de base et vous aideront à trouver des bogues plus tôt.

Static type checkers such as Mypy@footnote{https://mypy-lang.org/},
Pyre@footnote{https://pyre-check.org/}, and
Pytype@footnote{https://github.com/google/pytype} can check type hints in Python
source code.

@node Comment créer un binaire autonome à partir d'un script Python ?,Existe-t-il des normes de développement ou un guide de style pour écrire des programmes Python ?,Existe-t-il des outils pour aider à trouver des bogues ou faire de l'analyse statique de code ?,Questions générales
@anchor{faq/programming faq-create-standalone-binary}@anchor{4f68}@anchor{faq/programming how-can-i-create-a-stand-alone-binary-from-a-python-script}@anchor{4f69}
@subsubsection Comment créer un binaire autonome à partir d'un script Python ?


Pour créer un programme autonome, c'est-à-dire un programme que n'importe qui peut télécharger et exécuter sans avoir à installer une distribution Python au préalable, il n'est pas nécessaire de compiler du code Python en code C. Il existe en effet plusieurs outils qui déterminent les modules requis par un programme et lient ces modules avec un binaire Python pour produire un seul exécutable.

Un de ces outils est `freeze', qui se trouve dans Tools/freeze@footnote{https://github.com/python/cpython/tree/main/Tools/freeze} de l'arborescence des sources de Python. Il convertit le code intermédiaire (`bytecode') Python en tableaux C ; avec un compilateur C, vous pouvez intégrer tous vos modules dans un nouveau programme, qui est ensuite lié aux modules standards Python.

Il fonctionne en cherchant de manière récursive les instructions d'importation (sous les deux formes) dans le code source et en recherchant ces modules dans le chemin Python standard ainsi que dans le répertoire source (pour les modules natifs). Il transforme ensuite le code intermédiaire des modules écrits en Python en code C (des tableaux pré-remplis qui peuvent être transformés en objets code à l'aide du module `marshal') et crée un fichier de configuration personnalisé qui contient uniquement les modules natifs qui sont réellement utilisés dans le programme. Il compile ensuite le code C généré et le lie au reste de l'interpréteur Python pour former un binaire autonome qui fait exactement la même chose que le script.

Voici quelques paquets qui permettent de créer des exécutables en ligne de commande comme graphiques :


@itemize *

@item 
Nuitka@footnote{https://nuitka.net/} (multiplateformes) ;

@item 
PyInstaller@footnote{https://pyinstaller.org/} (Cross-platform)

@item 
PyOxidizer@footnote{https://pyoxidizer.readthedocs.io/en/stable/} (multi-plateforme) ;

@item 
cx_Freeze@footnote{https://marcelotduarte.github.io/cx_Freeze/} (multi-plateforme) ;

@item 
py2app@footnote{https://github.com/ronaldoussoren/py2app} (uniquement pour macOS) ;

@item 
py2exe@footnote{https://www.py2exe.org/} (uniquement pour Windows).
@end itemize

@node Existe-t-il des normes de développement ou un guide de style pour écrire des programmes Python ?,,Comment créer un binaire autonome à partir d'un script Python ?,Questions générales
@anchor{faq/programming are-there-coding-standards-or-a-style-guide-for-python-programs}@anchor{4f6a}
@subsubsection Existe-t-il des normes de développement ou un guide de style pour écrire des programmes Python ?


Oui. Le style de développement que les modules de la bibliothèque standard doivent obligatoirement respecter est documenté dans la 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}.

@node Fondamentaux,Nombres et chaînes de caractères,Questions générales,FAQ de programmation
@anchor{faq/programming core-language}@anchor{4f6b}
@subsection Fondamentaux


@menu
* Pourquoi une UnboundLocalError est levée alors qu'une variable a une valeur ?:: 
* Quelles sont les règles pour les variables locales et globales en Python ?:: 
* Pourquoi des expressions lambda définies dans une boucle avec des valeurs différentes retournent-elles le même résultat ?:: 
* Comment partager des variables globales entre modules ?:: 
* Quelles sont les « bonnes pratiques » pour utiliser import dans un module ?:: 
* Pourquoi les arguments par défaut sont-ils partagés entre les objets ?:: 
* Comment passer des paramètres optionnels ou nommés d'une fonction à l'autre ?:: 
* Quelle est la différence entre les arguments et les paramètres ?:: 
* Pourquoi modifier la liste 'y' modifie aussi la liste 'x' ?:: 
* Comment écrire une fonction qui modifie ses paramètres ? (passage par référence): Comment écrire une fonction qui modifie ses paramètres ? passage par référence. 
* Comment construire une fonction d'ordre supérieur en Python ?:: 
* Comment copier un objet en Python ?:: 
* Comment récupérer les méthodes ou les attributs d'un objet ?:: 
* Comment un code peut-il obtenir le nom d'un objet ?:: 
* Qu'en est-il de la précédence de l'opérateur virgule ?:: 
* Existe-t-il un équivalent à l'opérateur ternaire « ?; » du C ?: Existe-t-il un équivalent à l'opérateur ternaire « ? » du C ?. 
* Est-il possible d'écrire des programmes obscurcis (obfuscated) d'une ligne en Python ?: Est-il possible d'écrire des programmes obscurcis obfuscated d'une ligne en Python ?. 
* Que signifie la barre oblique (/) dans la liste des paramètres d'une fonction ?: Que signifie la barre oblique / dans la liste des paramètres d'une fonction ?. 

@end menu

@node Pourquoi une UnboundLocalError est levée alors qu'une variable a une valeur ?,Quelles sont les règles pour les variables locales et globales en Python ?,,Fondamentaux
@anchor{faq/programming faq-unboundlocalerror}@anchor{1f60}@anchor{faq/programming why-am-i-getting-an-unboundlocalerror-when-the-variable-has-a-value}@anchor{4f6c}
@subsubsection Pourquoi une UnboundLocalError est levée alors qu'une variable a une valeur ?


Il est parfois surprenant d'obtenir une @ref{14ec,,UnboundLocalError} dans du code jusqu'à présent correct, quand celui-ci est modifié en ajoutant une instruction d'affectation quelque part dans le corps d'une fonction.

Le code suivant :

@example
>>> x = 10
>>> def bar():
...     print(x)
...
>>> bar()
10
@end example

fonctionne, mais le suivant :

@example
>>> x = 10
>>> def foo():
...     print(x)
...     x += 1
@end example

results in an @code{UnboundLocalError}:

@example
>>> foo()
Traceback (most recent call last):
  ...
UnboundLocalError: local variable 'x' referenced before assignment
@end example

Cela est dû au fait que, quand une variable est affectée dans un contexte, cette variable devient locale à ce contexte et remplace toute variable du même nom du contexte appelant. Vu que la dernière instruction dans `foo' affecte une nouvelle valeur à @code{x}, le compilateur la traite comme une nouvelle variable. Par conséquent, quand le @code{print(x)} essaye d'afficher la variable non initialisée, une erreur se produit.

Dans l'exemple ci-dessus, la variable du contexte appelant reste accessible en la déclarant globale :

@example
>>> x = 10
>>> def foobar():
...     global x
...     print(x)
...     x += 1
...
>>> foobar()
10
@end example

Cette déclaration explicite est obligatoire pour se rappeler que (contrairement au cas à peu près similaire avec des variables de classe et d'instance), c'est la valeur de la variable du contexte appelant qui est modifiée :

@example
>>> print(x)
11
@end example

Une alternative dans un contexte imbriqué consiste à utiliser le mot-clé @ref{1285,,nonlocal} :

@example
>>> def foo():
...    x = 10
...    def bar():
...        nonlocal x
...        print(x)
...        x += 1
...    bar()
...    print(x)
...
>>> foo()
10
11
@end example

@node Quelles sont les règles pour les variables locales et globales en Python ?,Pourquoi des expressions lambda définies dans une boucle avec des valeurs différentes retournent-elles le même résultat ?,Pourquoi une UnboundLocalError est levée alors qu'une variable a une valeur ?,Fondamentaux
@anchor{faq/programming what-are-the-rules-for-local-and-global-variables-in-python}@anchor{4f6d}
@subsubsection Quelles sont les règles pour les variables locales et globales en Python ?


En Python, si une variable n'est pas modifiée dans une fonction mais seulement lue, elle est implicitement considérée comme globale. Si une valeur lui est affectée, elle est considérée locale (sauf si elle est explicitement déclarée globale).

Bien que surprenant au premier abord, ce choix s'explique facilement. D'une part, exiger @ref{188,,global} pour des variables affectées est une protection contre des effets de bord inattendus. D'autre part, si @code{global} était obligatoire pour toutes les références à des objets globaux, il faudrait mettre @code{global} partout, car il faudrait dans ce cas déclarer globale chaque référence à une fonction native ou à un composant d'un module importé. Le codé serait alors truffé de déclarations @code{global}, ce qui nuirait à leur raison d'être : identifier les effets de bords.

@node Pourquoi des expressions lambda définies dans une boucle avec des valeurs différentes retournent-elles le même résultat ?,Comment partager des variables globales entre modules ?,Quelles sont les règles pour les variables locales et globales en Python ?,Fondamentaux
@anchor{faq/programming why-do-lambdas-defined-in-a-loop-with-different-values-all-return-the-same-result}@anchor{4f6e}
@subsubsection Pourquoi des expressions lambda définies dans une boucle avec des valeurs différentes retournent-elles le même résultat ?


Supposons que l'on utilise une boucle itérative pour définir des expressions lambda (voire des fonctions) différentes, par exemple :

@example
>>> squares = []
>>> for x in range(5):
...     squares.append(lambda: x**2)
@end example

Le code précédent crée une liste de 5 expressions lambda qui calculent chacune @code{x**2}. En les exécutant, on pourrait s'attendre à obtenir  @code{0}, @code{1}, @code{4}, @code{9} et @code{16}. Elles renvoient en réalité toutes @code{16} :

@example
>>> squares[2]()
16
>>> squares[4]()
16
@end example

Ceci s'explique par le fait que @code{x} n'est pas une variable locale aux expressions, mais est définie dans le contexte appelant. Elle est lue à l'appel de l'expression lambda – et non au moment où cette expression est définie. À la fin de la boucle, @code{x} vaut @code{4}, donc toutes les fonctions renvoient @code{4*2}, c.-à-d. @code{16}. Ceci se vérifie également en changeant la valeur de @code{x} et en constatant que les résultats sont modifiés :

@example
>>> x = 8
>>> squares[2]()
64
@end example

Pour éviter ce phénomène, les valeurs doivent être stockées dans des variables locales aux expressions lambda pour que celles-ci ne se basent plus sur la variable globale @code{x} :

@example
>>> squares = []
>>> for x in range(5):
...     squares.append(lambda n=x: n**2)
@end example

Dans ce code, @code{n=x} crée une nouvelle variable @code{n}, locale à l'expression. Cette variable est évaluée quand l'expression est définie donc @code{n} a la même valeur que @code{x} à ce moment. La valeur de @code{n} est donc @code{0} dans la première lambda, @code{1} dans la deuxième, @code{2} dans la troisième et ainsi de suite. Chaque expression lambda renvoie donc le résultat correct :

@example
>>> squares[2]()
4
>>> squares[4]()
16
@end example

Ce comportement n'est pas propre aux expressions lambda, mais s'applique aussi aux fonctions normales.

@node Comment partager des variables globales entre modules ?,Quelles sont les « bonnes pratiques » pour utiliser import dans un module ?,Pourquoi des expressions lambda définies dans une boucle avec des valeurs différentes retournent-elles le même résultat ?,Fondamentaux
@anchor{faq/programming how-do-i-share-global-variables-across-modules}@anchor{4f6f}
@subsubsection Comment partager des variables globales entre modules ?


La manière standard de partager des informations entre modules d'un même programme est de créer un module spécial (souvent appelé `config' ou `cfg') et de l'importer dans tous les modules de l'application ; le module devient accessible depuis l'espace de nommage global. Vu qu'il n'y a qu'une instance de chaque module, tout changement dans l'instance est propagé partout. Par exemple :

`config.py' :

@example
x = 0   # Default value of the 'x' configuration setting
@end example

`mod.py' :

@example
import config
config.x = 1
@end example

`main.py' :

@example
import config
import mod
print(config.x)
@end example

Pour les mêmes raisons, l'utilisation d'un module est aussi à la base de l'implémentation du patron de conception singleton.

@node Quelles sont les « bonnes pratiques » pour utiliser import dans un module ?,Pourquoi les arguments par défaut sont-ils partagés entre les objets ?,Comment partager des variables globales entre modules ?,Fondamentaux
@anchor{faq/programming what-are-the-best-practices-for-using-import-in-a-module}@anchor{4f70}
@subsubsection Quelles sont les « bonnes pratiques » pour utiliser import dans un module ?


De manière générale, il ne faut pas faire @code{from modulename import *}. Ceci encombre l'espace de nommage de l'importateur et rend la détection de noms non-définis beaucoup plus ardue pour les analyseurs de code.

Les modules doivent être importés au début d'un fichier. Ceci permet d'afficher clairement de quels modules le code à besoin et évite de se demander si le module est dans le contexte. Faire un seul @code{import} par ligne rend l'ajout et la suppression d'une importation de module plus aisé, mais importer plusieurs modules sur une même ligne prend moins d'espace.

Il est recommandé d'importer les modules dans l'ordre suivant :


@enumerate 

@item 
les modules de la bibliothèque standard — p. ex. @ref{d8,,sys}, @ref{a0,,os}, @ref{60,,getopt}, @ref{b8,,re}

@item 
les modules externes (tout ce qui est installé dans le dossier `site-packages' de Python) — par exemple @code{dateutil}, @code{requests}, @code{PIL.Image}

@item 
les modules développés en local
@end enumerate

Il est parfois nécessaire de déplacer des importations dans une fonction ou une classe pour éviter les problèmes d'importations circulaires. Comme le souligne Gordon McMillan :

@quotation

Il n'y a aucun souci à faire des importations circulaires tant que les deux modules utilisent la forme @code{import <module>}. Ça ne pose problème que si le second module cherche à récupérer un nom du premier module (`"from module import name"') et que l'importation est dans l'espace de nommage du fichier. Les noms du premier module ne sont en effet pas encore disponibles car le premier module est occupé à importer le second.
@end quotation

Dans ce cas, si le second module n'est utilisé que dans une fonction, l'importation peut facilement être déplacée dans cette fonction. Au moment où l'importation sera appelée, le premier module aura fini de s'initialiser et le second pourra faire son importation.

Il peut parfois être nécessaire de déplacer des importations de modules hors de l'espace de plus haut niveau du code si certains de ces modules dépendent de la machine utilisée. Dans ce cas de figure, il est parfois impossible d'importer tous les modules au début du fichier. Dans ce cas, il est recommandé d'importer les modules adéquats dans le code spécifique à la machine.

Les importations ne devraient être déplacées dans un espace de nommage local, comme dans la définition d'une fonction, que si cela est nécessaire pour résoudre un problème comme éviter des dépendances circulaires ou réduire le temps d'initialisation d'un module. Cette technique est particulièrement utile si la majorité des importations est superflue selon le flux d'exécution du programme. Il est également pertinent de déplacer des importations dans une fonction si le module n'est utilisé qu'au sein de cette fonction. Le premier chargement d'un module peut être coûteux à cause du coût fixe d'initialisation d'un module, mais charger un module plusieurs fois est quasiment gratuit, cela ne coûte que quelques indirections dans un dictionnaire. Même si le nom du module est sorti du contexte courant, le module est probablement disponible dans @ref{18f9,,sys.modules}.

@node Pourquoi les arguments par défaut sont-ils partagés entre les objets ?,Comment passer des paramètres optionnels ou nommés d'une fonction à l'autre ?,Quelles sont les « bonnes pratiques » pour utiliser import dans un module ?,Fondamentaux
@anchor{faq/programming why-are-default-values-shared-between-objects}@anchor{4f71}
@subsubsection Pourquoi les arguments par défaut sont-ils partagés entre les objets ?


C'est un problème que rencontrent souvent les programmeurs débutants. Examinons la fonction suivante :

@example
def foo(mydict=@{@}):  # Danger: shared reference to one dict for all calls
    ... compute something ...
    mydict[key] = value
    return mydict
@end example

Au premier appel de cette fonction, @code{mydict} ne contient qu'un seul élément. Au second appel, @code{mydict} contient deux éléments car quand @code{foo()} commence son exécution, @code{mydict} contient déjà un élément.

On est souvent amené à croire qu'un appel de fonction créé des nouveaux objets pour les valeurs par défaut. Ce n'est pas le cas. Les valeurs par défaut ne sont créées qu'une et une seule fois, au moment où la fonction est définie. Si l'objet est modifié, comme le dictionnaire dans cet exemple, les appels suivants à cette fonction font référence à l'objet ainsi modifié.

Par définition, les objets immuables comme les nombres, les chaînes de caractères, les `n'-uplets et @code{None} ne sont pas modifiés. Les changements sur des objets modifiables comme les dictionnaires, les listes et les instances de classe peuvent porter à confusion.

En raison de cette fonctionnalité, il vaut mieux ne pas utiliser d'objets modifiables comme valeurs par défaut. Il vaut mieux utiliser @code{None} comme valeur par défaut et, à l'intérieur de la fonction, vérifier si le paramètre est à @code{None} et créer une nouvelle liste, dictionnaire ou autre, le cas échéant. Par exemple, il ne faut pas écrire :

@example
def foo(mydict=@{@}):
    ...
@end example

mais plutôt :

@example
def foo(mydict=None):
    if mydict is None:
        mydict = @{@}  # create a new dict for local namespace
@end example

Cette fonctionnalité a une utilité. Il est courant de mettre en cache les paramètres et la valeur de retour de chacun des appels d'une fonction coûteuse à exécuter, et de renvoyer la valeur stockée en cache si le même appel est ré-effectué. C'est la technique dite de « mémoïsation », qui s'implémente de la manière suivante :

@example
# Callers can only provide two parameters and optionally pass _cache by keyword
def expensive(arg1, arg2, *, _cache=@{@}):
    if (arg1, arg2) in _cache:
        return _cache[(arg1, arg2)]

    # Calculate the value
    result = ... expensive computation ...
    _cache[(arg1, arg2)] = result           # Store result in the cache
    return result
@end example

Il est possible d'utiliser une variable globale contenant un dictionnaire à la place de la valeur par défaut ; ce n'est qu'une question de goût.

@node Comment passer des paramètres optionnels ou nommés d'une fonction à l'autre ?,Quelle est la différence entre les arguments et les paramètres ?,Pourquoi les arguments par défaut sont-ils partagés entre les objets ?,Fondamentaux
@anchor{faq/programming how-can-i-pass-optional-or-keyword-parameters-from-one-function-to-another}@anchor{4f72}
@subsubsection Comment passer des paramètres optionnels ou nommés d'une fonction à l'autre ?


Il faut récupérer les arguments en utilisant les sélecteurs @code{*} et @code{**} dans la liste des paramètres de la fonction ; ceci donne les arguments positionnels sous la forme d'un `n'-uplet et les arguments nommés sous forme de dictionnaire. Ces arguments peuvent être passés à une autre fonction en utilisant @code{*} et @code{**} :

@example
def f(x, *args, **kwargs):
    ...
    kwargs['width'] = '14.3c'
    ...
    g(x, *args, **kwargs)
@end example

@geindex argument;difference from parameter
@geindex parameter;difference from argument

@node Quelle est la différence entre les arguments et les paramètres ?,Pourquoi modifier la liste 'y' modifie aussi la liste 'x' ?,Comment passer des paramètres optionnels ou nommés d'une fonction à l'autre ?,Fondamentaux
@anchor{faq/programming faq-argument-vs-parameter}@anchor{4f73}@anchor{faq/programming what-is-the-difference-between-arguments-and-parameters}@anchor{4f74}
@subsubsection Quelle est la différence entre les arguments et les paramètres ?


Les @ref{1e82,,paramètres} sont les noms qui apparaissent dans une définition de fonction, alors que les @ref{432,,arguments} sont les valeurs qui sont réellement passées à une fonction lors de l'appel de celle-ci. Les paramètres définissent les @ref{1e82,,types d'arguments} qu'une fonction accepte. Ainsi, avec la définition de fonction suivante :

@example
def func(foo, bar=None, **kwargs):
    pass
@end example

`foo', `bar' et `kwargs' sont des paramètres de @code{func}. Mais à l'appel de @code{func} avec, par exemple :

@example
func(42, bar=314, extra=somevar)
@end example

les valeurs @code{42}, @code{314}, et @code{somevar} sont des arguments.

@node Pourquoi modifier la liste 'y' modifie aussi la liste 'x' ?,Comment écrire une fonction qui modifie ses paramètres ? passage par référence,Quelle est la différence entre les arguments et les paramètres ?,Fondamentaux
@anchor{faq/programming why-did-changing-list-y-also-change-list-x}@anchor{4f75}
@subsubsection Pourquoi modifier la liste 'y' modifie aussi la liste 'x' ?


Si vous avez écrit du code comme :

@example
>>> x = []
>>> y = x
>>> y.append(10)
>>> y
[10]
>>> x
[10]
@end example

vous vous demandez peut-être pourquoi l'ajout d'un élément à @code{y} a aussi changé @code{x}.

Il y a deux raisons qui conduisent à ce comportement :


@enumerate 

@item 
Les variables ne sont que des noms qui font référence à des objets. La ligne @code{y = x} ne crée pas une copie de la liste — elle crée une nouvelle variable @code{y} qui pointe sur le même objet que @code{x}. Ceci signifie qu'il n'existe qu'un seul objet (la liste) auquel @code{x} et @code{y} font référence.

@item 
Les listes sont des @ref{1b8e,,mutable}, ce qui signifie que leur contenu peut être modifié.
@end enumerate

After the call to @code{append()}, the content of the mutable object has
changed from @code{[]} to @code{[10]}.  Since both the variables refer to the same
object, using either name accesses the modified value @code{[10]}.

Si au contraire, on affecte un objet immuable à @code{x} :

@example
>>> x = 5  # ints are immutable
>>> y = x
>>> x = x + 1  # 5 can't be mutated, we are creating a new object here
>>> x
6
>>> y
5
@end example

on observe que @code{x} et @code{y} ne sont ici plus égales. Les entiers sont des immuables (@ref{97e,,immutable}), et @code{x = x + 1} ne change pas l'entier @code{5} en incrémentant sa valeur. Au contraire, un nouvel objet est créé (l'entier @code{6}) et affecté à @code{x} (c'est-à-dire qu'on change l'objet auquel fait référence @code{x}). Après cette affectation on a deux objets (les entiers @code{6} et @code{5}) et deux variables qui font référence à ces deux objets (@code{x} fait désormais référence à @code{6} mais @code{y} fait toujours référence à @code{5}).

Certaines opérations (par exemple, @code{y.append(10)} et @code{y.sort()}) modifient l'objet, alors que des opérations identiques en apparence (par exemple @code{y = y + [10]} et @code{sorted(y)()}) créent un nouvel objet. En général, en Python, une méthode qui modifie un objet renvoie @code{None} (c'est même systématique dans la bibliothèque standard) pour éviter la confusion entre les deux opérations. Donc écrire par erreur @code{y.sort()} en pensant obtenir une copie triée de @code{y} donne @code{None}, ce qui conduit très souvent le programme à générer une erreur facile à diagnostiquer.

Il existe cependant une classe d'opérations qui se comporte différemment selon le type : les opérateurs d'affectation incrémentaux. Par exemple, @code{+=} modifie les listes mais pas les `n'-uplets ni les entiers (@code{a_list += [1, 2, 3]} équivaut à @code{a_list.extend([1, 2, 3])} et modifie @code{a_list}, alors que @code{some_tuple += (1, 2, 3)} et @code{some_int += 1} créent de nouveaux objets).

En d'autres termes :


@itemize *

@item 
Il est possible d'appliquer des opérations qui modifient un objet mutable (@ref{5fc,,list}, @ref{253,,dict}, @ref{5c3,,set}, etc.) et toutes les variables qui y font référence verront le changement.

@item 
Toutes les variables qui font référence à un objet immuable (@ref{435,,str}, @ref{254,,int}, @ref{366,,tuple}, etc.) renvoient la même valeur, mais les opérations qui transforment cette valeur en une nouvelle valeur renvoient toujours un nouvel objet.
@end itemize

L'opérateur @ref{2e9,,is} ou la fonction native @ref{13d9,,id()} permettent de savoir si deux variables font référence au même objet.

@node Comment écrire une fonction qui modifie ses paramètres ? passage par référence,Comment construire une fonction d'ordre supérieur en Python ?,Pourquoi modifier la liste 'y' modifie aussi la liste 'x' ?,Fondamentaux
@anchor{faq/programming how-do-i-write-a-function-with-output-parameters-call-by-reference}@anchor{4f76}
@subsubsection Comment écrire une fonction qui modifie ses paramètres ? (passage par référence)


En Python, les arguments sont passés comme des affectations de variables. Vu qu'une affectation crée des références à des objets, il n'y a pas de lien entre un argument dans l'appel de la fonction et sa définition, et donc pas de passage par référence en soi. Il y a cependant plusieurs façons d'en émuler un.


@enumerate 

@item 
En renvoyant un `n'-uplet de résultats :

@example
>>> def func1(a, b):
...     a = 'new-value'        # a and b are local names
...     b = b + 1              # assigned to new objects
...     return a, b            # return new values
...
>>> x, y = 'old-value', 99
>>> func1(x, y)
('new-value', 100)
@end example

C'est presque toujours la meilleure solution.

@item 
En utilisant des variables globales. Cette approche ne fonctionne pas dans des contextes à plusieurs fils d'exécution (elle n'est pas `thread-safe'), et n'est donc pas recommandée.

@item 
En passant un objet mutable (modifiable sur place) :

@example
>>> def func2(a):
...     a[0] = 'new-value'     # 'a' references a mutable list
...     a[1] = a[1] + 1        # changes a shared object
...
>>> args = ['old-value', 99]
>>> func2(args)
>>> args
['new-value', 100]
@end example

@item 
En passant un dictionnaire, qui sera modifié :

@example
>>> def func3(args):
...     args['a'] = 'new-value'     # args is a mutable dictionary
...     args['b'] = args['b'] + 1   # change it in-place
...
>>> args = @{'a': 'old-value', 'b': 99@}
>>> func3(args)
>>> args
@{'a': 'new-value', 'b': 100@}
@end example

@item 
Ou regrouper les valeurs dans une instance de classe :

@example
>>> class Namespace:
...     def __init__(self, /, **args):
...         for key, value in args.items():
...             setattr(self, key, value)
...
>>> def func4(args):
...     args.a = 'new-value'        # args is a mutable Namespace
...     args.b = args.b + 1         # change object in-place
...
>>> args = Namespace(a='old-value', b=99)
>>> func4(args)
>>> vars(args)
@{'a': 'new-value', 'b': 100@}
@end example

Faire quelque chose d'aussi compliqué est rarement une bonne idée.
@end enumerate

La meilleure option reste de renvoyer un `n'-uplet contenant les différents résultats.

@node Comment construire une fonction d'ordre supérieur en Python ?,Comment copier un objet en Python ?,Comment écrire une fonction qui modifie ses paramètres ? passage par référence,Fondamentaux
@anchor{faq/programming how-do-you-make-a-higher-order-function-in-python}@anchor{4f77}
@subsubsection Comment construire une fonction d'ordre supérieur en Python ?


Deux possibilités : on peut utiliser des portées imbriquées ou bien des objets appelables. Par exemple, supposons que l'on souhaite définir @code{linear(a, b)} qui renvoie une fonction @code{f(x)} qui calcule la valeur @code{a*x+b}. En utilisant les portées imbriquées :

@example
def linear(a, b):
    def result(x):
        return a * x + b
    return result
@end example

Ou en utilisant un objet appelable :

@example
class linear:

    def __init__(self, a, b):
        self.a, self.b = a, b

    def __call__(self, x):
        return self.a * x + self.b
@end example

Dans les deux cas

@example
taxes = linear(0.3, 2)
@end example

donne un objet appelable où @code{taxes(10e6) == 0.3 * 10e6 + 2}.

L'approche par objet appelable a le désavantage d'être légèrement plus lente et de produire un code légèrement plus long. Cependant, il faut noter qu'une collection d'objet appelables peuvent partager leurs signatures par héritage :

@example
class exponential(linear):
    # __init__ inherited
    def __call__(self, x):
        return self.a * (x ** self.b)
@end example

Les objets peuvent encapsuler un état pour plusieurs méthodes :

@example
class counter:

    value = 0

    def set(self, x):
        self.value = x

    def up(self):
        self.value = self.value + 1

    def down(self):
        self.value = self.value - 1

count = counter()
inc, dec, reset = count.up, count.down, count.set
@end example

Ici @code{inc()}, @code{dec()} et @code{reset()} agissent comme des fonctions partageant une même variable compteur.

@node Comment copier un objet en Python ?,Comment récupérer les méthodes ou les attributs d'un objet ?,Comment construire une fonction d'ordre supérieur en Python ?,Fondamentaux
@anchor{faq/programming how-do-i-copy-an-object-in-python}@anchor{4f78}
@subsubsection Comment copier un objet en Python ?


En général, essayez @ref{51d,,copy.copy()} ou @ref{b5c,,copy.deepcopy()}. Tous les objets ne peuvent pas être copiés, mais la plupart le peuvent.

Certains objets peuvent être copiés plus facilement que d'autres. Les dictionnaires ont une méthode @ref{bbe,,copy()} :

@example
newdict = olddict.copy()
@end example

Les séquences peuvent être copiées via la syntaxe des tranches :

@example
new_l = l[:]
@end example

@node Comment récupérer les méthodes ou les attributs d'un objet ?,Comment un code peut-il obtenir le nom d'un objet ?,Comment copier un objet en Python ?,Fondamentaux
@anchor{faq/programming how-can-i-find-the-methods-or-attributes-of-an-object}@anchor{4f79}
@subsubsection Comment récupérer les méthodes ou les attributs d'un objet ?


Pour une instance @code{x} d'une classe définie par un utilisateur, @ref{61d,,dir(x)} renvoie une liste alphabétique des noms contenants les attributs de l'instance, et les attributs et méthodes définies par sa classe.

@node Comment un code peut-il obtenir le nom d'un objet ?,Qu'en est-il de la précédence de l'opérateur virgule ?,Comment récupérer les méthodes ou les attributs d'un objet ?,Fondamentaux
@anchor{faq/programming how-can-my-code-discover-the-name-of-an-object}@anchor{4f7a}
@subsubsection Comment un code peut-il obtenir le nom d'un objet ?


C'est impossible en général, parce qu'un objet n'a pas de nom à proprement parler. Schématiquement, l'affectation fait correspondre un nom à une valeur ; c'est vrai aussi pour les instructions @code{def} et @code{class}, à la différence près que, dans ce cas, la valeur est un appelable. Par exemple, dans le code suivant :

@example
>>> class A:
...     pass
...
>>> B = A
>>> a = B()
>>> b = a
>>> print(b)
<__main__.A object at 0x16D07CC>
>>> print(a)
<__main__.A object at 0x16D07CC>
@end example

Affirmer que la classe a un nom est discutable. Bien qu'elle soit liée à deux noms, et qu'elle soit appelée via le nom @code{B}, l'instance créée déclare tout de même être une instance de la classe @code{A}. De même, il est impossible de dire si le nom de l'instance est @code{a} ou @code{b}, les deux noms étant attachés à la même valeur.

De façon générale, une application ne devrait pas avoir besoin de « connaître le nom » d'une valeur particulière. À moins d'être délibérément en train d'écrire un programme introspectif, c'est souvent l'indication qu'un changement d'approche serait bénéfique.

Sur `comp.lang.python', Fredrik Lundh a donné un jour une excellente analogie pour répondre à cette question :

@quotation

C'est pareil que trouver le nom du chat qui traîne devant votre porte : le chat (objet) ne peut pas vous dire lui-même son nom, et il s'en moque un peu ­– alors le meilleur moyen de savoir comment il s'appelle est de demander à tous vos voisins (espaces de nommage) si c'est leur chat (objet)…

…et ne soyez pas surpris si vous découvrez qu'il est connu sous plusieurs noms, ou s'il n'a pas de nom du tout !
@end quotation

@node Qu'en est-il de la précédence de l'opérateur virgule ?,Existe-t-il un équivalent à l'opérateur ternaire « ? » du C ?,Comment un code peut-il obtenir le nom d'un objet ?,Fondamentaux
@anchor{faq/programming what-s-up-with-the-comma-operator-s-precedence}@anchor{4f7b}
@subsubsection Qu'en est-il de la précédence de l'opérateur virgule ?


La virgule n'est pas un opérateur en Python. Observez le code suivant :

@example
>>> "a" in "b", "a"
(False, 'a')
@end example

Comme la virgule n'est pas un opérateur, mais un séparateur entre deux expressions, l'expression ci-dessus est évaluée de la même façon que si vous aviez écrit :

@example
("a" in "b"), "a"
@end example

et non :

@example
"a" in ("b", "a")
@end example

Ceci est vrai pour tous les opérateurs d'affectation (@code{=}, @code{+=} etc). Ce ne sont pas vraiment des opérateurs mais plutôt des délimiteurs syntaxiques dans les instructions d'affectation.

@node Existe-t-il un équivalent à l'opérateur ternaire « ? » du C ?,Est-il possible d'écrire des programmes obscurcis obfuscated d'une ligne en Python ?,Qu'en est-il de la précédence de l'opérateur virgule ?,Fondamentaux
@anchor{faq/programming is-there-an-equivalent-of-c-s-ternary-operator}@anchor{4f7c}
@subsubsection Existe-t-il un équivalent à l'opérateur ternaire « ?: » du C ?


Oui. Sa syntaxe est la suivante :

@example
[on_true] if [expression] else [on_false]

x, y = 50, 25
small = x if x < y else y
@end example

Avant l'introduction de cette syntaxe dans Python 2.5, il était courant d'utiliser les opérateurs de logique :

@example
[expression] and [on_true] or [on_false]
@end example

Cet idiome est dangereux, car il donne un résultat erroné quand `on_true' a la valeur booléenne fausse. Il faut donc toujours utiliser la forme @code{... if ... else ...}.

@node Est-il possible d'écrire des programmes obscurcis obfuscated d'une ligne en Python ?,Que signifie la barre oblique / dans la liste des paramètres d'une fonction ?,Existe-t-il un équivalent à l'opérateur ternaire « ? » du C ?,Fondamentaux
@anchor{faq/programming is-it-possible-to-write-obfuscated-one-liners-in-python}@anchor{4f7d}
@subsubsection Est-il possible d'écrire des programmes obscurcis (`obfuscated') d'une ligne en Python ?


Oui. C'est souvent le cas en imbriquant des @ref{127a,,lambda} dans des @code{lambda}. Par exemple les trois morceaux de code suivants, légèrement adaptés par Ulf Bartelt :

@example
from functools import reduce

# Primes < 1000
print(list(filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,
map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))))

# First 10 Fibonacci numbers
print(list(map(lambda x,f=lambda x,f:(f(x-1,f)+f(x-2,f)) if x>1 else 1:
f(x,f), range(10))))

# Mandelbrot set
print((lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+'\n'+y,map(lambda y,
Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y
>=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy
))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24))
#    \___ ___/  \___ ___/  |   |   |__ lines on screen
#        V          V      |   |______ columns on screen
#        |          |      |__________ maximum of "iterations"
#        |          |_________________ range on y axis
#        |____________________________ range on x axis
@end example

Les enfants, ne faites pas ça chez vous !

@node Que signifie la barre oblique / dans la liste des paramètres d'une fonction ?,,Est-il possible d'écrire des programmes obscurcis obfuscated d'une ligne en Python ?,Fondamentaux
@anchor{faq/programming faq-positional-only-arguments}@anchor{20fb}@anchor{faq/programming what-does-the-slash-in-the-parameter-list-of-a-function-mean}@anchor{4f7e}
@subsubsection Que signifie la barre oblique (/) dans la liste des paramètres d'une fonction ?


Une barre oblique dans la liste des arguments d'une fonction indique que les paramètres la précédant sont uniquement positionnels. Les paramètres uniquement positionnels ne peuvent pas être référencés par leur nom depuis l'extérieur. Lors de l'appel d'une fonction qui accepte des paramètres uniquement positionnels, les arguments sont affectés aux paramètres en fonction de leur position. Par exemple, la fonction @ref{98f,,divmod()} n'accepte que des paramètres uniquement positionnels. Sa documentation est la suivante :

@example
>>> help(divmod)
Help on built-in function divmod in module builtins:

divmod(x, y, /)
    Return the tuple (x//y, x%y).  Invariant: div*y + mod == x.
@end example

La barre oblique à la fin de la liste des paramètres signifie que les trois paramètres sont uniquement positionnels. Et donc, appeler @ref{98f,,divmod()} avec des arguments nommés provoque une erreur :

@example
>>> divmod(x=3, y=4)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: divmod() takes no keyword arguments
@end example

@node Nombres et chaînes de caractères,Performances<4>,Fondamentaux,FAQ de programmation
@anchor{faq/programming numbers-and-strings}@anchor{4f7f}
@subsection Nombres et chaînes de caractères


@menu
* Comment écrire des entiers hexadécimaux ou octaux ?:: 
* Pourquoi -22 // 10 donne-t-il -3 ?:: 
* Pourquoi ai-je une erreur de syntaxe en essayant de lire un attribut d'un entier littéral ?:: 
* Comment convertir une chaîne de caractères en nombre ?:: 
* Comment convertir un nombre en chaîne de caractères ?:: 
* Comment modifier une chaîne de caractères « sur place » ?:: 
* Comment utiliser des chaînes de caractères pour appeler des fonctions/méthodes ?:: 
* Existe-t-il un équivalent à la fonction chomp() de Perl@comma{} pour retirer les caractères de fin de ligne d'une chaîne de caractères ?: Existe-t-il un équivalent à la fonction chomp de Perl pour retirer les caractères de fin de ligne d'une chaîne de caractères ?. 
* Existe-t-il un équivalent à scanf() ou sscanf() ?: Existe-t-il un équivalent à scanf ou sscanf ?. 
* Que signifient les erreurs UnicodeDecodeError ou UnicodeEncodeError ?:: 
* Can I end a raw string with an odd number of backslashes?:: 

@end menu

@node Comment écrire des entiers hexadécimaux ou octaux ?,Pourquoi -22 // 10 donne-t-il -3 ?,,Nombres et chaînes de caractères
@anchor{faq/programming how-do-i-specify-hexadecimal-and-octal-integers}@anchor{4f80}
@subsubsection Comment écrire des entiers hexadécimaux ou octaux ?


Pour écrire un entier octal, faites précéder la valeur octale par un zéro, puis un "o" majuscule ou minuscule. Par exemple pour affecter la valeur octale "10" (8 en décimal) à la variable "a", tapez :

@example
>>> a = 0o10
>>> a
8
@end example

L'hexadécimal est tout aussi simple, faites précéder le nombre hexadécimal par un zéro, puis un "x" majuscule ou minuscule. Les nombres hexadécimaux peuvent être écrits en majuscules ou en minuscules. Par exemple, dans l'interpréteur Python :

@example
>>> a = 0xa5
>>> a
165
>>> b = 0XB2
>>> b
178
@end example

@node Pourquoi -22 // 10 donne-t-il -3 ?,Pourquoi ai-je une erreur de syntaxe en essayant de lire un attribut d'un entier littéral ?,Comment écrire des entiers hexadécimaux ou octaux ?,Nombres et chaînes de caractères
@anchor{faq/programming why-does-22-10-return-3}@anchor{4f81}
@subsubsection Pourquoi @code{-22 // 10} donne-t-il @code{-3} ?


Cela est principalement dû à la volonté que @code{i % j} ait le même signe que j. Si vous voulez en plus que :

@example
i == (i // j) * j + (i % j)
@end example

alors la division entière doit renvoyer l'entier inférieur. Le C impose également que cette égalité soit vérifiée, et donc les compilateurs qui tronquent @code{i // j} ont besoin que @code{i % j} ait le même signe que @code{i}.

Il y a peu de cas d'utilisation réels pour @code{i % j} quand @code{j} est négatif. Quand @code{j} est positif, il y en a beaucoup, et dans pratiquement tous, il est plus utile que @code{i % j} soit @code{>=0}.  Si l'horloge affiche 10 h maintenant, qu'affichait-elle il y a 200 heures ? @code{-190 % 12 == 2} est utile ; @code{-190 % 12 == -10} est un bogue en puissance.

@node Pourquoi ai-je une erreur de syntaxe en essayant de lire un attribut d'un entier littéral ?,Comment convertir une chaîne de caractères en nombre ?,Pourquoi -22 // 10 donne-t-il -3 ?,Nombres et chaînes de caractères
@anchor{faq/programming how-do-i-get-int-literal-attribute-instead-of-syntaxerror}@anchor{4f82}
@subsubsection Pourquoi ai-je une erreur de syntaxe en essayant de lire un attribut d'un entier littéral ?


Essayer d'utiliser l'opérateur d'accès à un attribut sur un entier littéral lève une @ref{18b,,SyntaxError} car le point est compris comme un séparateur décimal en notation anglo-saxonne :

@example
>>> 1.__class__
  File "<stdin>", line 1
  1.__class__
   ^
SyntaxError: invalid decimal literal
@end example

Il faut séparer l'entier du point, soit avec une espace, soit avec des parenthèses.

@example
>>> 1 .__class__
<class 'int'>
>>> (1).__class__
<class 'int'>
@end example

@node Comment convertir une chaîne de caractères en nombre ?,Comment convertir un nombre en chaîne de caractères ?,Pourquoi ai-je une erreur de syntaxe en essayant de lire un attribut d'un entier littéral ?,Nombres et chaînes de caractères
@anchor{faq/programming how-do-i-convert-a-string-to-a-number}@anchor{4f83}
@subsubsection Comment convertir une chaîne de caractères en nombre ?


For integers, use the built-in @ref{254,,int()} type constructor, e.g. @code{int('144')
== 144}.  Similarly, @ref{2eb,,float()} converts to a floating-point number,
e.g. @code{float('144') == 144.0}.

Par défaut, ces fonctions interprètent les nombres comme des décimaux, de telle façon que @code{int('0144') == 144} et @code{int('0x144')} lève une @ref{1ff,,ValueError}. Le second argument (optionnel) de @code{int(string, base)} est la base dans laquelle convertir, donc @code{int('0x144', 16) == 324}. Si la base donnée est 0, le nombre est interprété selon les règles Python : un préfixe @code{0o} indique de l'octal et @code{0x} indique de l'hexadécimal.

N'utilisez pas la fonction native @ref{17e,,eval()} pour convertir des chaînes de caractères en nombres. @ref{17e,,eval()} est beaucoup plus lente et pose des problèmes de sécurité : quelqu'un pourrait vous envoyer une expression Python pouvant avoir des effets de bord indésirables. Par exemple, quelqu'un pourrait passer @code{__import__('os').system("rm -rf $HOME")} ce qui effacerait votre répertoire personnel.

@ref{17e,,eval()} a aussi pour effet d'interpréter les nombres comme des expressions Python. Ainsi @code{eval('09')} produit une erreur de syntaxe, parce que Python ne permet pas les '0' en tête d'un nombre décimal (à l'exception du nombre '0').

@node Comment convertir un nombre en chaîne de caractères ?,Comment modifier une chaîne de caractères « sur place » ?,Comment convertir une chaîne de caractères en nombre ?,Nombres et chaînes de caractères
@anchor{faq/programming how-do-i-convert-a-number-to-a-string}@anchor{4f84}
@subsubsection Comment convertir un nombre en chaîne de caractères ?


Pour transformer, par exemple, le nombre @code{144} en la chaîne de caractères @code{'144'}, il faut utiliser la fonction native @ref{435,,str()}. Pour obtenir la représentation hexadécimale ou octale, il faut utiliser les fonctions natives @ref{12ad,,hex()} ou @ref{12ac,,oct()}. Pour des représentations non-conventionnelles, se référer aux sections @ref{997,,f-strings} et @ref{1367,,Syntaxe de formatage de chaîne}, par exemple @code{"@{:04d@}".format(144)} produit @code{'0144'} et @code{"@{:.3f@}".format(1.0/3.0)} produit @code{'0.333'}.

@node Comment modifier une chaîne de caractères « sur place » ?,Comment utiliser des chaînes de caractères pour appeler des fonctions/méthodes ?,Comment convertir un nombre en chaîne de caractères ?,Nombres et chaînes de caractères
@anchor{faq/programming how-do-i-modify-a-string-in-place}@anchor{4f85}
@subsubsection Comment modifier une chaîne de caractères « sur place » ?


C'est impossible car les chaînes de caractères sont immuables. Dans la plupart des cas, il faut tout simplement construire une nouvelle chaîne à partir des morceaux de l'ancienne. Si toutefois vous avez besoin d'un objet capable de modifier de la donnée Unicode « sur place », essayez d'utiliser un objet @ref{f12,,io.StringIO} ou le module @ref{7,,array} :

@example
>>> import io
>>> s = "Hello, world"
>>> sio = io.StringIO(s)
>>> sio.getvalue()
'Hello, world'
>>> sio.seek(7)
7
>>> sio.write("there!")
6
>>> sio.getvalue()
'Hello, there!'

>>> import array
>>> a = array.array('w', s)
>>> print(a)
array('w', 'Hello, world')
>>> a[0] = 'y'
>>> print(a)
array('w', 'yello, world')
>>> a.tounicode()
'yello, world'
@end example

@node Comment utiliser des chaînes de caractères pour appeler des fonctions/méthodes ?,Existe-t-il un équivalent à la fonction chomp de Perl pour retirer les caractères de fin de ligne d'une chaîne de caractères ?,Comment modifier une chaîne de caractères « sur place » ?,Nombres et chaînes de caractères
@anchor{faq/programming how-do-i-use-strings-to-call-functions-methods}@anchor{4f86}
@subsubsection Comment utiliser des chaînes de caractères pour appeler des fonctions/méthodes ?


Il y a plusieurs façons de faire.


@itemize *

@item 
La meilleure est d'utiliser un dictionnaire qui fait correspondre les chaînes de caractères à des fonctions. Le principal avantage de cette technique est que les chaînes n'ont pas besoin d'être égales aux noms de fonctions. C'est aussi la façon principale d'imiter la construction "case" :

@example
def a():
    pass

def b():
    pass

dispatch = @{'go': a, 'stop': b@}  # Note lack of parens for funcs

dispatch[get_input()]()  # Note trailing parens to call function
@end example

@item 
Utiliser la fonction @ref{bbf,,getattr()} :

@example
import foo
getattr(foo, 'bar')()
@end example

Notez que @ref{bbf,,getattr()} marche sur n'importe quel objet, ceci inclut les classes, les instances de classes, les modules et ainsi de suite.

Ceci est utilisé à plusieurs reprises dans la bibliothèque standard, de cette façon :

@example
class Foo:
    def do_foo(self):
        ...

    def do_bar(self):
        ...

f = getattr(foo_instance, 'do_' + opname)
f()
@end example

@item 
Utilisez @ref{140,,locals()} pour résoudre le nom de la fonction :

@example
def myFunc():
    print("hello")

fname = "myFunc"

f = locals()[fname]
f()
@end example
@end itemize

@node Existe-t-il un équivalent à la fonction chomp de Perl pour retirer les caractères de fin de ligne d'une chaîne de caractères ?,Existe-t-il un équivalent à scanf ou sscanf ?,Comment utiliser des chaînes de caractères pour appeler des fonctions/méthodes ?,Nombres et chaînes de caractères
@anchor{faq/programming is-there-an-equivalent-to-perl-s-chomp-for-removing-trailing-newlines-from-strings}@anchor{4f87}
@subsubsection Existe-t-il un équivalent à la fonction @code{chomp()} de Perl, pour retirer les caractères de fin de ligne d'une chaîne de caractères ?


Vous pouvez utiliser @code{S.rstrip("\r\n")} pour retirer toutes les occurrences de tout marqueur de fin de ligne à la fin d'une chaîne de caractère @code{S}, sans en enlever aucune espace. Si la chaîne @code{S} représente plus d'une ligne, avec plusieurs lignes vides, les marqueurs de fin de ligne de chaque ligne vide seront retirés :

@example
>>> lines = ("line 1 \r\n"
...          "\r\n"
...          "\r\n")
>>> lines.rstrip("\n\r")
'line 1 '
@end example

Vu que cela ne sert presque qu'à lire un texte ligne à ligne, utiliser @code{S.rstrip()} de cette manière fonctionne correctement.

@node Existe-t-il un équivalent à scanf ou sscanf ?,Que signifient les erreurs UnicodeDecodeError ou UnicodeEncodeError ?,Existe-t-il un équivalent à la fonction chomp de Perl pour retirer les caractères de fin de ligne d'une chaîne de caractères ?,Nombres et chaînes de caractères
@anchor{faq/programming is-there-a-scanf-or-sscanf-equivalent}@anchor{4f88}
@subsubsection Existe-t-il un équivalent à @code{scanf()} ou @code{sscanf()} ?


Pas exactement.

For simple input parsing, the easiest approach is usually to split the line into
whitespace-delimited words using the @ref{e93,,split()} method of string objects
and then convert decimal strings to numeric values using @ref{254,,int()} or
@ref{2eb,,float()}.  @code{split()} supports an optional "sep" parameter which is useful
if the line uses something other than whitespace as a separator.

Pour des analyses plus compliquées, les expressions rationnelles sont plus puissantes que la fonction @code{sscanf} de C et mieux adaptées à la tâche.

@node Que signifient les erreurs UnicodeDecodeError ou UnicodeEncodeError ?,Can I end a raw string with an odd number of backslashes?,Existe-t-il un équivalent à scanf ou sscanf ?,Nombres et chaînes de caractères
@anchor{faq/programming what-does-unicodedecodeerror-or-unicodeencodeerror-error-mean}@anchor{4f89}
@subsubsection Que signifient les erreurs @code{UnicodeDecodeError} ou @code{UnicodeEncodeError} ?


Voir @ref{1282,,Guide Unicode}.

@node Can I end a raw string with an odd number of backslashes?,,Que signifient les erreurs UnicodeDecodeError ou UnicodeEncodeError ?,Nombres et chaînes de caractères
@anchor{faq/programming can-i-end-a-raw-string-with-an-odd-number-of-backslashes}@anchor{4f8a}@anchor{faq/programming faq-programming-raw-string-backslash}@anchor{1b89}
@subsubsection Can I end a raw string with an odd number of backslashes?


A raw string ending with an odd number of backslashes will escape the string's quote:

@example
>>> r'C:\this\will\not\work\'
  File "<stdin>", line 1
    r'C:\this\will\not\work\'
         ^
SyntaxError: unterminated string literal (detected at line 1)
@end example

There are several workarounds for this. One is to use regular strings and double
the backslashes:

@example
>>> 'C:\\this\\will\\work\\'
'C:\\this\\will\\work\\'
@end example

Another is to concatenate a regular string containing an escaped backslash to the
raw string:

@example
>>> r'C:\this\will\work' '\\'
'C:\\this\\will\\work\\'
@end example

It is also possible to use @ref{15bc,,os.path.join()} to append a backslash on Windows:

@example
>>> os.path.join(r'C:\this\will\work', '@w{'})
'C:\\this\\will\\work\\'
@end example

Note that while a backslash will "escape" a quote for the purposes of
determining where the raw string ends, no escaping occurs when interpreting the
value of the raw string. That is, the backslash remains present in the value of
the raw string:

@example
>>> r'backslash\'preserved'
"backslash\\'preserved"
@end example

Also see the specification in the @ref{1e2a,,language reference}.

@node Performances<4>,Séquences n-uplets / listes,Nombres et chaînes de caractères,FAQ de programmation
@anchor{faq/programming performance}@anchor{4f8b}
@subsection Performances


@menu
* Mon programme est trop lent. Comment l'accélérer ?: Mon programme est trop lent Comment l'accélérer ?. 
* Quelle est la manière la plus efficace de concaténer un grand nombre de chaînes de caractères ?:: 

@end menu

@node Mon programme est trop lent Comment l'accélérer ?,Quelle est la manière la plus efficace de concaténer un grand nombre de chaînes de caractères ?,,Performances<4>
@anchor{faq/programming my-program-is-too-slow-how-do-i-speed-it-up}@anchor{4f8c}
@subsubsection Mon programme est trop lent. Comment l'accélérer ?


Question difficile en général. Il faut garder en tête les points suivants avant d'aller plus loin :


@itemize *

@item 
Les performances varient en fonction des implémentations de Python. Cette FAQ ne traite que de @ref{6e0,,CPython}.

@item 
Les comportements peuvent différer d'un système d'exploitation à l'autre, tout particulièrement quand il s'agit d'entrée/sortie ou de fils d'exécution multiples.

@item 
Il faut toujours essayer de trouver où sont les points de contention d'un programme `avant' d'essayer d'optimiser du code (voir le module @ref{ae,,profile}).

@item 
Écrire des scripts d'évaluation de performances permet de progresser rapidement dans la recherche d'améliorations (voir le module @ref{ee,,timeit}).

@item 
Il est très fortement recommandé d'avoir une bonne couverture de code (avec des tests unitaires ou autre) avant d'ajouter des erreurs dans des optimisations sophistiquées.
@end itemize

Ceci étant dit, il y a beaucoup d'astuces pour accélérer du code Python. Voici quelques principes généraux qui peuvent aider à atteindre des niveaux de performance satisfaisants :


@itemize *

@item 
Améliorer les algorithmes (ou en changer pour des plus performants) peut produire de bien meilleurs résultats que d'optimiser çà et là de petites portions du code.

@item 
Utiliser les structures de données adaptées. Se référer à la documentation des @ref{2117,,Types natifs} et du module @ref{1d,,collections}.

@item 
Quand la bibliothèque standard fournit une implémentation pour quelque chose, il y a de fortes chances (même si ce n'est pas systématique) que cette implémentation soit plus rapide que la vôtre. C'est d'autant plus vrai pour les routines écrites en C, comme les routines natives et certaines extensions de types. Par exemple, il faut utiliser la méthode native @ref{bbd,,list.sort()} ou la fonction @ref{bbc,,sorted()} similaire pour classer (et se référer à la section @ref{2107,,Sorting Techniques} pour des exemples d'utilisation courante).

@item 
Les abstractions ont tendance à créer des indirections et obligent l'interpréteur à faire plus d'efforts. Si le niveau d'indirection dépasse la quantité de travail effectif, le programme sera ralenti. Il faut toujours éviter trop d'indirections, en particulier sous la forme de fonctions ou méthodes trop petites (qui nuisent aussi souvent à la clarté du code).
@end itemize

Si vous atteignez les limites de ce que du Python « pur » permet de faire, il y a des outils qui permettent d'aller plus loin. Par exemple, Cython@footnote{https://cython.org} peut compiler une version légèrement modifiée de code Python en une extension C et est disponible sur de nombreuses plate-formes. Cython peut bénéficier de la compilation (et de l'annotation, optionnelle, des types) pour rendre votre code beaucoup plus rapide que s'il était interprété. Si vous avez confiance en vos capacités de programmation en C, vous pouvez aussi @ref{1b69,,écrire un module d'extension en C} vous-même.


@subsubheading Voir aussi


La page wiki dédiée aux astuces de performance@footnote{https://wiki.python.org/moin/PythonSpeed/PerformanceTips}.


@node Quelle est la manière la plus efficace de concaténer un grand nombre de chaînes de caractères ?,,Mon programme est trop lent Comment l'accélérer ?,Performances<4>
@anchor{faq/programming efficient-string-concatenation}@anchor{4f8d}@anchor{faq/programming what-is-the-most-efficient-way-to-concatenate-many-strings-together}@anchor{4f8e}
@subsubsection Quelle est la manière la plus efficace de concaténer un grand nombre de chaînes de caractères ?


Les objets @ref{435,,str} et @ref{1bd,,bytes} sont immuables, par conséquent concaténer un grand nombre de chaînes de caractères entre elles n'est pas très efficace car chaque concaténation crée un nouvel objet. Dans le cas général, la complexité est quadratique par rapport à la taille totale de la chaîne.

Pour mettre bout à bout un grand nombre d'objets @ref{435,,str}, la technique recommandée consiste à toutes les mettre dans une liste et appeler la méthode @ref{2134,,str.join()} à la fin :

@example
chunks = []
for s in my_strings:
    chunks.append(s)
result = '@w{'}.join(chunks)
@end example

(une autre technique relativement efficace consiste à utiliser @ref{f12,,io.StringIO})

Pour concaténer un grand nombre d'objets @ref{1bd,,bytes}, la technique recommandée consiste à étendre un objet @ref{528,,bytearray} en utilisant la concaténation en-place (l'opérateur @code{+=}) :

@example
result = bytearray()
for b in my_bytes_objects:
    result += b
@end example

@node Séquences n-uplets / listes,Objets,Performances<4>,FAQ de programmation
@anchor{faq/programming sequences-tuples-lists}@anchor{4f8f}
@subsection Séquences (`n'-uplets / listes)


@menu
* Comment convertir les listes en n-uplets et inversement ?:: 
* Qu'est-ce qu'un indice négatif ?:: 
* Comment itérer à rebours sur une séquence ?:: 
* Comment retirer les doublons d'une liste ?:: 
* Comment retirer les doublons d'une liste:: 
* Comment construire un tableau en Python ?:: 
* Comment créer une liste à plusieurs dimensions ?:: 
* Comment appliquer une méthode ou une fonction à une séquence d'objets ?:: 
* Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?:: 
* Je souhaite faire un classement compliqué ; peut-on faire une transformation de Schwartz en Python ?: Je souhaite faire un classement compliqué peut-on faire une transformation de Schwartz en Python ?. 
* Comment ordonner une liste en fonction des valeurs d'une autre liste ?:: 

@end menu

@node Comment convertir les listes en n-uplets et inversement ?,Qu'est-ce qu'un indice négatif ?,,Séquences n-uplets / listes
@anchor{faq/programming how-do-i-convert-between-tuples-and-lists}@anchor{4f90}
@subsubsection Comment convertir les listes en `n'-uplets et inversement ?


Le constructeur de type @code{tuple(seq)} convertit toute séquence (plus précisément, tout itérable) en un `n'-uplet avec les mêmes éléments dans le même ordre.

Par exemple @code{tuple([1, 2, 3])} renvoie @code{(1, 2, 3)} et @code{tuple('abc')} renvoie @code{('a', 'b', 'c')}. Si l'argument est un `n'-uplet, cela ne crée pas de copie, mais renvoie le même objet, ce qui fait de @ref{366,,tuple()} une fonction économique à appeler quand vous ne savez pas si votre objet est déjà un `n'-uplet.

Le constructeur de type @code{list(seq)} convertit toute séquence ou itérable en liste contenant les mêmes éléments dans le même ordre. Par exemple, @code{list((1,2,3))} renvoie @code{[1,2,3]} et @code{list('abc')} renvoie @code{['a','b','c']}. Si l'argument est une liste, il renvoie une copie, de la même façon que @code{seq[:]}.

@node Qu'est-ce qu'un indice négatif ?,Comment itérer à rebours sur une séquence ?,Comment convertir les listes en n-uplets et inversement ?,Séquences n-uplets / listes
@anchor{faq/programming what-s-a-negative-index}@anchor{4f91}
@subsubsection Qu'est-ce qu'un indice négatif ?


Les séquences Python sont indicées avec des nombres positifs aussi bien que négatifs. Pour les nombres positifs, 0 est le premier indice, 1 est le deuxième, et ainsi de suite. Pour les indices négatifs, @code{-1} est le dernier indice, @code{-2} est le pénultième (avant-dernier), et ainsi de suite. On peut aussi dire que @code{seq[-n]} est équivalent à @code{seq[len(seq)-n]}.

Utiliser des indices négatifs peut être très pratique. Par exemple @code{S[:-1]} représente la chaîne tout entière à l'exception du dernier caractère, ce qui est pratique pour retirer un caractère de fin de ligne à la fin d'une chaîne.

@node Comment itérer à rebours sur une séquence ?,Comment retirer les doublons d'une liste ?,Qu'est-ce qu'un indice négatif ?,Séquences n-uplets / listes
@anchor{faq/programming how-do-i-iterate-over-a-sequence-in-reverse-order}@anchor{4f92}
@subsubsection Comment itérer à rebours sur une séquence ?


Utilisez la fonction native @ref{850,,reversed()} :

@example
for x in reversed(sequence):
    ...  # do something with x ...
@end example

Cela ne modifie pas la séquence initiale, mais construit à la place une copie en ordre inverse pour itérer dessus.

@node Comment retirer les doublons d'une liste ?,Comment retirer les doublons d'une liste,Comment itérer à rebours sur une séquence ?,Séquences n-uplets / listes
@anchor{faq/programming how-do-you-remove-duplicates-from-a-list}@anchor{4f93}
@subsubsection Comment retirer les doublons d'une liste ?


Lisez le « livre de recettes » Python pour trouver une longue discussion sur les nombreuses approches possibles :

@quotation

@indicateurl{https://code.activestate.com/recipes/52560/}
@end quotation

Si changer l'ordre de la liste ne vous dérange pas, commencez par ordonner celle-ci, puis parcourez-la d'un bout à l'autre, en supprimant les doublons trouvés en chemin :

@example
if mylist:
    mylist.sort()
    last = mylist[-1]
    for i in range(len(mylist)-2, -1, -1):
        if last == mylist[i]:
            del mylist[i]
        else:
            last = mylist[i]
@end example

Si tous les éléments de la liste peuvent être utilisés comme des clés de dictionnaire (c'est-à-dire, qu'elles sont toutes @ref{5fb,,hachables}) ceci est souvent plus rapide

@example
mylist = list(set(mylist))
@end example

Ceci convertit la liste en un ensemble, ce qui supprime automatiquement les doublons, puis la transforme à nouveau en liste.

@node Comment retirer les doublons d'une liste,Comment construire un tableau en Python ?,Comment retirer les doublons d'une liste ?,Séquences n-uplets / listes
@anchor{faq/programming how-do-you-remove-multiple-items-from-a-list}@anchor{4f94}
@subsubsection Comment retirer les doublons d'une liste


Comme pour supprimer les doublons, il est possible d’itérer explicitement à l’envers avec une condition de suppression. Cependant, il est plus facile et plus rapide d’utiliser le remplacement des tranches par une itération avant, implicite ou explicite. Voici trois variantes :

@example
mylist[:] = filter(keep_function, mylist)
mylist[:] = (x for x in mylist if keep_condition)
mylist[:] = [x for x in mylist if keep_condition]
@end example

La liste en compréhension est peut-être la plus rapide :

@node Comment construire un tableau en Python ?,Comment créer une liste à plusieurs dimensions ?,Comment retirer les doublons d'une liste,Séquences n-uplets / listes
@anchor{faq/programming how-do-you-make-an-array-in-python}@anchor{4f95}
@subsubsection Comment construire un tableau en Python ?


Utilisez une liste :

@example
["this", 1, "is", "an", "array"]
@end example

Les listes ont un coût équivalent à celui des tableaux C ou Pascal ; la principale différence est qu'une liste Python peut contenir des objets de différents types.

Le module @code{array} fournit des méthodes pour créer des tableaux de types fixes dans une représentation compacte, mais ils sont plus lents à indexer que les listes. Notez aussi que NumPy@footnote{https://numpy.org/} (et d'autres) fournissent différentes structures de type tableaux, avec des caractéristiques différentes.

Pour obtenir des listes chaînées à la sauce Lisp, vous pouvez émuler les `cons cells' en utilisant des `n'-uplets :

@example
lisp_list = ("like",  ("this",  ("example", None) ) )
@end example

Si vous voulez pouvoir modifier les éléments, utilisez une liste plutôt qu'un `n'-uplet. Ici la version équivalente du `car' de Lisp est @code{lisp_list[0]} et l'équivalent de `cdr' est @code{lisp_list[1]}. Ne faites ceci que si vous êtes réellement sûr d'en avoir besoin, cette méthode est en général bien plus lente que les listes Python.

@node Comment créer une liste à plusieurs dimensions ?,Comment appliquer une méthode ou une fonction à une séquence d'objets ?,Comment construire un tableau en Python ?,Séquences n-uplets / listes
@anchor{faq/programming faq-multidimensional-list}@anchor{2133}@anchor{faq/programming how-do-i-create-a-multidimensional-list}@anchor{4f96}
@subsubsection Comment créer une liste à plusieurs dimensions ?


Vous avez probablement essayé de créer une liste à plusieurs dimensions de cette façon :

@example
>>> A = [[None] * 2] * 3
@end example

Elle semble correcte si on l'affiche :

@c A = [[None] * 2] * 3

@example
>>> A
[[None, None], [None, None], [None, None]]
@end example

Mais quand vous affectez une valeur, celle-ci apparaît à plusieurs endroits :

@c A = [[None] * 2] * 3

@example
>>> A[0][0] = 5
>>> A
[[5, None], [5, None], [5, None]]
@end example

Dupliquer une liste en utilisant @code{*} ne crée en réalité pas de copie mais seulement des références aux objets existants. Le @code{*3} crée une liste contenant trois références à la même liste de longueur deux. Un changement dans une colonne apparaîtra donc dans toutes les colonnes, ce qui n'est très probablement pas ce que vous souhaitiez.

L'approche suggérée est d'abord de créer une liste de la longueur désirée, puis de remplir tous les éléments avec une nouvelle chaîne :

@example
A = [None] * 3
for i in range(3):
    A[i] = [None] * 2
@end example

Cela génère une liste contenant elle-même trois listes distinctes, de longueur deux. Vous pouvez aussi utiliser la syntaxe des listes en compréhension :

@example
w, h = 2, 3
A = [[None] * w for i in range(h)]
@end example

Vous pouvez aussi utiliser une extension qui fournit un type matriciel natif ; NumPy@footnote{https://www.numpy.org/} est la plus répandue.

@node Comment appliquer une méthode ou une fonction à une séquence d'objets ?,Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?,Comment créer une liste à plusieurs dimensions ?,Séquences n-uplets / listes
@anchor{faq/programming how-do-i-apply-a-method-or-function-to-a-sequence-of-objects}@anchor{4f97}
@subsubsection Comment appliquer une méthode ou une fonction à une séquence d'objets ?


Pour appeler une méthode ou une fonction et accumuler les valeurs renvoyées dans une liste, une @ref{6b8,,compréhension de liste} est une solution élégante :

@example
result = [obj.method() for obj in mylist]

result = [function(obj) for obj in mylist]
@end example

To just run the method or function without saving the return values,
a plain @ref{2e6,,for} loop will suffice:

@example
for obj in mylist:
    obj.method()

for obj in mylist:
    function(obj)
@end example

@node Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?,Je souhaite faire un classement compliqué peut-on faire une transformation de Schwartz en Python ?,Comment appliquer une méthode ou une fonction à une séquence d'objets ?,Séquences n-uplets / listes
@anchor{faq/programming faq-augmented-assignment-tuple-error}@anchor{1f37}@anchor{faq/programming why-does-a-tuple-i-item-raise-an-exception-when-the-addition-works}@anchor{4f98}
@subsubsection Pourquoi @code{a_tuple[i] += ['item']} lève-t-il une exception alors que l'addition fonctionne ?


Ceci est dû à la combinaison de deux facteurs : le fait que les opérateurs d'affectation incrémentaux sont des opérateurs d'`affectation' et à la différence entre les objets mutables et immuables en Python.

Cette discussion est valable, en général, quand des opérateurs d'affectation incrémentale sont appliqués aux éléments d'un `n'-uplet qui pointe sur des objets mutables, mais on prendra @code{list} et @code{+=} comme exemple.

Si vous écrivez :

@example
>>> a_tuple = (1, 2)
>>> a_tuple[0] += 1
Traceback (most recent call last):
   ...
TypeError: 'tuple' object does not support item assignment
@end example

La cause de l'exception est claire : @code{1} est ajouté à l'objet @code{a_tuple[0]} qui pointe sur (@code{1}), ce qui produit l'objet résultant @code{2}, mais, lorsque l'on tente d'affecter le résultat du calcul, @code{2}, à l'élément @code{0} du `n'-uplet, on obtient une erreur car il est impossible de modifier la cible sur laquelle pointe un élément d'un `n'-uplet.

Sous le capot, une instruction d'affectation incrémentale fait à peu près ceci :

@example
>>> result = a_tuple[0] + 1
>>> a_tuple[0] = result
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment
@end example

C'est la partie de l'affectation de l'opération qui génère l'erreur, vu qu'un `n'-uplet est immuable.

Quand vous écrivez un code du style :

@example
>>> a_tuple = (['foo'], 'bar')
>>> a_tuple[0] += ['item']
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment
@end example

L'exception est un peu plus surprenante et, chose encore plus étrange, malgré l'erreur, l'ajout a fonctionné :

@example
>>> a_tuple[0]
['foo', 'item']
@end example

To see why this happens, you need to know that (a) if an object implements an
@ref{1f11,,__iadd__()} magic method, it gets called when the @code{+=} augmented
assignment
is executed, and its return value is what gets used in the assignment statement;
and (b) for lists, @code{__iadd__()} is equivalent to calling @code{extend()} on the list
and returning the list.  That's why we say that for lists, @code{+=} is a
"shorthand" for @code{list.extend()}:

@example
>>> a_list = []
>>> a_list += [1]
>>> a_list
[1]
@end example

C’est équivalent à :

@example
>>> result = a_list.__iadd__([1])
>>> a_list = result
@end example

L'objet sur lequel pointe @code{a_list} a été modifié et le pointeur vers l'objet modifié est réaffecté à @code{a_list}. `In fine', l'affectation ne change rien, puisque c'est un pointeur vers le même objet que sur lequel pointait @code{a_list}, mais l'affectation a tout de même lieu.

Donc, dans notre exemple avec un `n'-uplet, il se passe quelque chose équivalent à :

@example
>>> result = a_tuple[0].__iadd__(['item'])
>>> a_tuple[0] = result
Traceback (most recent call last):
  ...
TypeError: 'tuple' object does not support item assignment
@end example

L'appel à @code{__iadd__()} réussit et la liste est étendue, mais bien que @code{result} pointe sur le même objet que @code{a_tuple[0]}, l'affectation finale échoue car les `n'-uplets ne sont pas mutables.

@node Je souhaite faire un classement compliqué peut-on faire une transformation de Schwartz en Python ?,Comment ordonner une liste en fonction des valeurs d'une autre liste ?,Pourquoi a_tuple[i] += ['item'] lève-t-il une exception alors que l'addition fonctionne ?,Séquences n-uplets / listes
@anchor{faq/programming i-want-to-do-a-complicated-sort-can-you-do-a-schwartzian-transform-in-python}@anchor{4f99}
@subsubsection Je souhaite faire un classement compliqué : peut-on faire une transformation de Schwartz en Python ?


Cette technique, attribuée à Randal Schwartz de la communauté Perl, ordonne les éléments d'une liste à l'aide une transformation qui fait correspondre chaque élément à sa "valeur de tri". En Python, ceci est géré par l'argument @code{key} de la méthode @ref{bbd,,list.sort()} :

@example
Isorted = L[:]
Isorted.sort(key=lambda s: int(s[10:15]))
@end example

@node Comment ordonner une liste en fonction des valeurs d'une autre liste ?,,Je souhaite faire un classement compliqué peut-on faire une transformation de Schwartz en Python ?,Séquences n-uplets / listes
@anchor{faq/programming how-can-i-sort-one-list-by-values-from-another-list}@anchor{4f9a}
@subsubsection Comment ordonner une liste en fonction des valeurs d'une autre liste ?


Fusionnez-les dans un itérateur de `n'-uplets, ordonnez la liste obtenue, puis choisissez l'élément que vous voulez

@example
>>> list1 = ["what", "I'm", "sorting", "by"]
>>> list2 = ["something", "else", "to", "sort"]
>>> pairs = zip(list1, list2)
>>> pairs = sorted(pairs)
>>> pairs
[("I'm", 'else'), ('by', 'sort'), ('sorting', 'to'), ('what', 'something')]
>>> result = [x[1] for x in pairs]
>>> result
['else', 'sort', 'to', 'something']
@end example

@node Objets,Modules<5>,Séquences n-uplets / listes,FAQ de programmation
@anchor{faq/programming objects}@anchor{4f9b}
@subsection Objets


@menu
* Qu'est-ce qu'une classe ?:: 
* Qu'est-ce qu'une méthode ?:: 
* Qu'est-ce que self ?:: 
* Comment vérifier si un objet est une instance d'une classe donnée ou d'une sous-classe de celle-ci ?:: 
* Qu'est-ce que la délégation ?:: 
* Comment appeler une méthode définie dans une classe mère depuis une classe dérivée qui la surcharge ?:: 
* Comment organiser un code pour permettre de changer la classe mère plus facilement ?:: 
* Comment créer des données statiques de classe et des méthodes statiques de classe ?:: 
* Comment surcharger les constructeurs (ou méthodes) en Python ?: Comment surcharger les constructeurs ou méthodes en Python ?. 
* J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam.: J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam. 
* Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet.: Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet. 
* Comment obtenir toutes les instances d'une classe ?:: 
* Pourquoi le résultat de id() peut-il être le même pour deux objets différents ?: Pourquoi le résultat de id peut-il être le même pour deux objets différents ?. 
* Quand puis-je raisonnablement utiliser le test d'identité is ?:: 
* Comment définir dans une classe fille les attributs d'une instance immuable ?:: 
* Comment mettre en cache le résultat d'une méthode ?:: 

@end menu

@node Qu'est-ce qu'une classe ?,Qu'est-ce qu'une méthode ?,,Objets
@anchor{faq/programming what-is-a-class}@anchor{4f9c}
@subsubsection Qu'est-ce qu'une classe ?


Une classe est le type d'objet particulier créé par l'exécution d'une déclaration de classe. Les objets de classe sont utilisés comme modèles pour créer des objets, qui incarnent à la fois les données (attributs) et le code (méthodes) spécifiques à un type de données.

Une classe peut être fondée sur une ou plusieurs autres classes, appelée sa (ou ses) classe(s) de base. Elle hérite alors des attributs et des méthodes de ses classes mères. Cela permet à un modèle d'objet d'être successivement raffiné par héritage. Vous pourriez avoir une classe générique @code{Mailbox}, qui fournit des méthodes d'accès de base pour une boîte aux lettres, et des sous-classes telles que @code{MboxMailbox}, @code{MaildirMailbox}, @code{OutlookMailbox} qui gèrent les plusieurs formats spécifiques de boîtes aux lettres.

@node Qu'est-ce qu'une méthode ?,Qu'est-ce que self ?,Qu'est-ce qu'une classe ?,Objets
@anchor{faq/programming what-is-a-method}@anchor{4f9d}
@subsubsection Qu'est-ce qu'une méthode ?


Une méthode est une fonction sur un  objet @code{x} qu'on appelle de manière générale sous la forme @code{x.name(arguments…)}. Les méthodes sont définies comme des fonctions à l'intérieur de la définition de classe :

@example
class C:
    def meth(self, arg):
        return arg * 2 + self.attribute
@end example

@node Qu'est-ce que self ?,Comment vérifier si un objet est une instance d'une classe donnée ou d'une sous-classe de celle-ci ?,Qu'est-ce qu'une méthode ?,Objets
@anchor{faq/programming what-is-self}@anchor{4f9e}
@subsubsection Qu'est-ce que self ?


Par convention, le premier argument d'une méthode est appelé self. Une méthode @code{meth(self, a, b, c)} doit être appelée sous la forme @code{x.meth(a, b, c)} où @code{x} est une instance de la classe dans laquelle cette méthode est définie ; tout se passe comme si la méthode était appelée comme @code{meth(x, a, b, c)}.

Voir aussi @ref{4f9f,,Pourquoi self doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?}.

@node Comment vérifier si un objet est une instance d'une classe donnée ou d'une sous-classe de celle-ci ?,Qu'est-ce que la délégation ?,Qu'est-ce que self ?,Objets
@anchor{faq/programming how-do-i-check-if-an-object-is-an-instance-of-a-given-class-or-of-a-subclass-of-it}@anchor{4fa0}
@subsubsection Comment vérifier si un objet est une instance d'une classe donnée ou d'une sous-classe de celle-ci ?


Utilisez la fonction native @ref{42b,,isinstance(obj@comma{} cls)}. Vous pouvez vérifier qu'un objet est une instance de plusieurs classes à la fois en fournissant un `n'-uplet à la place d'une seule classe, par exemple, @code{isinstance(obj, (class1, class2, ...))}. Vous pouvez également vérifier qu'un objet est l'un des types natifs de Python, par exemple @code{isinstance(obj, str)} ou @code{isinstance(obj, (int, float, complex))}.

Notez que @ref{42b,,isinstance()} prend aussi en compte l'héritage virtuel d'une @ref{1193,,classe mère abstraite}, c'est à dire qu'elle renvoie @code{True} pour une classe A enregistrée auprès d'une classe mère abstraite B même si A n'est pas directement ou indirectement une classe fille de B. Pour vérifier l'héritage dans le sens plus restreint, parcourez l'@ref{3556,,ordre de résolution des méthodes} de la classe :

@example
from collections.abc import Mapping

class P:
     pass

class C(P):
    pass

Mapping.register(P)
@end example

@example
>>> c = C()
>>> isinstance(c, C)        # direct
True
>>> isinstance(c, P)        # indirect
True
>>> isinstance(c, Mapping)  # virtual
True

# Actual inheritance chain
>>> type(c).__mro__
(<class 'C'>, <class 'P'>, <class 'object'>)

# Test for "true inheritance"
>>> Mapping in type(c).__mro__
False
@end example

Notez que la plupart des programmes n'utilisent que rarement @code{isInstance()} sur les classes définies par l'utilisateur. Si vous développez vous-même des classes, une approche plus orientée-objet consiste définir des méthodes sur les classes qui sont porteuses d'un comportement particulier, plutôt que de vérifier la classe de l'objet et de faire un traitement ad-hoc. Par exemple, si vous avez une fonction qui fait quelque chose :

@example
def search(obj):
    if isinstance(obj, Mailbox):
        ...  # code to search a mailbox
    elif isinstance(obj, Document):
        ...  # code to search a document
    elif ...
@end example

Une meilleure approche est de définir une méthode @code{search()} dans toutes les classes et qu'il suffit d'appeler de la manière suivante :

@example
class Mailbox:
    def search(self):
        ...  # code to search a mailbox

class Document:
    def search(self):
        ...  # code to search a document

obj.search()
@end example

@node Qu'est-ce que la délégation ?,Comment appeler une méthode définie dans une classe mère depuis une classe dérivée qui la surcharge ?,Comment vérifier si un objet est une instance d'une classe donnée ou d'une sous-classe de celle-ci ?,Objets
@anchor{faq/programming what-is-delegation}@anchor{4fa1}
@subsubsection Qu'est-ce que la délégation ?


La délégation est une technique orientée objet (aussi appelée « patron de conception). Prenons un objet @code{x} dont on souhaite modifier le comportement d'une seule de ses méthodes. On peut créer une nouvelle classe qui fournit une nouvelle implémentation de la méthode qui nous intéresse dans l'évolution et qui délègue toute autre méthode à la méthode correspondante de @code{x}.

Les programmeurs Python peuvent facilement mettre en œuvre la délégation. Par exemple, la classe suivante implémente une classe qui se comporte comme un fichier, mais convertit toutes les données écrites en majuscules :

@example
class UpperOut:

    def __init__(self, outfile):
        self._outfile = outfile

    def write(self, s):
        self._outfile.write(s.upper())

    def __getattr__(self, name):
        return getattr(self._outfile, name)
@end example

Here the @code{UpperOut} class redefines the @code{write()} method to convert the
argument string to uppercase before calling the underlying
@code{self._outfile.write()} method.  All other methods are delegated to the
underlying @code{self._outfile} object.  The delegation is accomplished via the
@ref{4bc,,__getattr__()} method; consult @ref{1ee6,,the language reference}
for more information about controlling attribute access.

Note that for more general cases delegation can get trickier. When attributes
must be set as well as retrieved, the class must define a @ref{1eb2,,__setattr__()}
method too, and it must do so carefully.  The basic implementation of
@code{__setattr__()} is roughly equivalent to the following:

@example
class X:
    ...
    def __setattr__(self, name, value):
        self.__dict__[name] = value
    ...
@end example

Many @ref{1eb2,,__setattr__()} implementations call @code{object.__setattr__()} to set
an attribute on self without causing infinite recursion:

@example
class X:
    def __setattr__(self, name, value):
        # Custom logic here...
        object.__setattr__(self, name, value)
@end example

Alternatively, it is possible to set attributes by inserting
entries into @ref{546,,self.__dict__} directly.

@node Comment appeler une méthode définie dans une classe mère depuis une classe dérivée qui la surcharge ?,Comment organiser un code pour permettre de changer la classe mère plus facilement ?,Qu'est-ce que la délégation ?,Objets
@anchor{faq/programming how-do-i-call-a-method-defined-in-a-base-class-from-a-derived-class-that-extends-it}@anchor{4fa2}
@subsubsection Comment appeler une méthode définie dans une classe mère depuis une classe dérivée qui la surcharge ?


Utilisez la fonction native @ref{4c5,,super()} :

@example
class Derived(Base):
    def meth(self):
        super().meth()  # calls Base.meth
@end example

Dans cet exemple, @ref{4c5,,super()} détermine automatiquement l'instance dont une méthode l'appelle (l'objet @code{self}), observe l'@ref{2109,,ordre de résolution des méthodes} obtenu avec @code{type(self).__mro__}, et renvoie la classe qui suit @code{Derived} dans cet ordre, donc @code{Base}.

@node Comment organiser un code pour permettre de changer la classe mère plus facilement ?,Comment créer des données statiques de classe et des méthodes statiques de classe ?,Comment appeler une méthode définie dans une classe mère depuis une classe dérivée qui la surcharge ?,Objets
@anchor{faq/programming how-can-i-organize-my-code-to-make-it-easier-to-change-the-base-class}@anchor{4fa3}
@subsubsection Comment organiser un code pour permettre de changer la classe mère plus facilement ?


Vous pouvez définir un alias pour la classe mère et dériver depuis l'alias. Ensuite, tout ce que vous devez changer est la valeur attribuée à cet alias. Accessoirement, cette astuce est également utile pour déterminer dynamiquement (par exemple en fonction de la disponibilité de certaines ressources) la classe mère à utiliser. Exemple :

@example
class Base:
    ...

BaseAlias = Base

class Derived(BaseAlias):
    ...
@end example

@node Comment créer des données statiques de classe et des méthodes statiques de classe ?,Comment surcharger les constructeurs ou méthodes en Python ?,Comment organiser un code pour permettre de changer la classe mère plus facilement ?,Objets
@anchor{faq/programming how-do-i-create-static-class-data-and-static-class-methods}@anchor{4fa4}
@subsubsection Comment créer des données statiques de classe et des méthodes statiques de classe ?


Les données statiques et les méthodes statiques (au sens C++ ou Java) sont prises en charge en Python.

Pour les données statiques, il suffit de définir un attribut de classe. Pour attribuer une nouvelle valeur à l'attribut, vous devez explicitement utiliser le nom de classe dans l'affectation :

@example
class C:
    count = 0   # number of times C.__init__ called

    def __init__(self):
        C.count = C.count + 1

    def getcount(self):
        return C.count  # or return self.count
@end example

@code{c.count} se réfère également à @code{C.count} pour tout @code{c} tel que @code{isInstance (c, C)} est vrai, sauf remplacement par @code{c} lui-même ou par une classe sur le chemin de recherche de classe mère de @code{c.__class__} jusqu'à @code{C}.

Attention : dans une méthode de C, une affectation comme @code{self.count = 42} crée une nouvelle instance sans rapport avec le nom @code{count} dans le dictionnaire de données de @code{self}. La redéfinition d'une donnée statique de classe doit toujours spécifier la classe, que l'on soit à l'intérieur d'une méthode ou non :

@example
C.count = 314
@end example

Il est possible d'utiliser des méthodes statiques :

@example
class C:
    @@staticmethod
    def static(arg1, arg2, arg3):
        # No 'self' parameter!
        ...
@end example

Cependant, d'une manière beaucoup plus simple pour obtenir l'effet d'une méthode statique se fait par une simple fonction au niveau du module :

@example
def getcount():
    return C.count
@end example

Si votre code est structuré de manière à définir une classe (ou bien la hiérarchie des classes connexes) par module, ceci fournira l'encapsulation souhaitée.

@node Comment surcharger les constructeurs ou méthodes en Python ?,J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam,Comment créer des données statiques de classe et des méthodes statiques de classe ?,Objets
@anchor{faq/programming how-can-i-overload-constructors-or-methods-in-python}@anchor{4fa5}
@subsubsection Comment surcharger les constructeurs (ou méthodes) en Python ?


Cette réponse s'applique en fait à toutes les méthodes, mais la question se pose généralement dans le contexte des constructeurs.

En C++, on écrirait

@example
class C @{
    C() @{ cout << "No arguments\n"; @}
    C(int i) @{ cout << "Argument is " << i << "\n"; @}
@}
@end example

En Python, vous devez écrire un constructeur unique qui considère tous les cas en utilisant des arguments par défaut. Par exemple :

@example
class C:
    def __init__(self, i=None):
        if i is None:
            print("No arguments")
        else:
            print("Argument is", i)
@end example

Ce n'est pas tout à fait équivalent, mais suffisamment proche dans la pratique.

Vous pouvez aussi utiliser une liste d'arguments de longueur variable, par exemple

@example
def __init__(self, *args):
    ...
@end example

La même approche fonctionne pour toutes les définitions de méthode.

@node J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam,Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet,Comment surcharger les constructeurs ou méthodes en Python ?,Objets
@anchor{faq/programming i-try-to-use-spam-and-i-get-an-error-about-someclassname-spam}@anchor{4fa6}
@subsubsection J'essaie d'utiliser @code{__spam} et j'obtiens une erreur à propos de @code{_SomeClassName__spam}.


Les noms de variables commençant avec deux tirets bas sont « déformés », c'est un moyen simple mais efficace de définir des variables privées à une classe. Tout identifiant de la forme @code{__spam} (commençant par au moins deux tirets bas et se terminant par au plus un tiret bas) est textuellement remplacé par @code{_classname__spam}, où @code{classname} est le nom de la classe en cours sans les éventuels tirets bas du début.

The identifier can be used unchanged within the class, but to access it outside
the class, the mangled name must be used:

@example
class A:
    def __one(self):
        return 1
    def two(self):
        return 2 * self.__one()

class B(A):
    def three(self):
        return 3 * self._A__one()

four = 4 * A()._A__one()
@end example

In particular, this does not guarantee privacy since an outside user can still
deliberately access the private attribute; many Python programmers never bother
to use private variable names at all.


@subsubheading Voir aussi


The @ref{1c48,,private name mangling specifications}
for details and special cases.


@node Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet,Comment obtenir toutes les instances d'une classe ?,J'essaie d'utiliser __spam et j'obtiens une erreur à propos de _SomeClassName__spam,Objets
@anchor{faq/programming my-class-defines-del-but-it-is-not-called-when-i-delete-the-object}@anchor{4fa7}
@subsubsection Ma classe définit @code{__del__} mais elle n'est pas appelée lorsque je supprime l'objet.


Il y a plusieurs explications possibles.

The @ref{1734,,del} statement does not necessarily call @ref{1ee3,,__del__()} -- it simply
decrements the object's reference count, and if this reaches zero
@code{__del__()} is called.

If your data structures contain circular links (e.g. a tree where each child has
a parent reference and each parent has a list of children) the reference counts
will never go back to zero.  Once in a while Python runs an algorithm to detect
such cycles, but the garbage collector might run some time after the last
reference to your data structure vanishes, so your @code{__del__()} method may be
called at an inconvenient and random time. This is inconvenient if you're trying
to reproduce a problem. Worse, the order in which object's @code{__del__()}
methods are executed is arbitrary.  You can run @ref{a28,,gc.collect()} to force a
collection, but there `are' pathological cases where objects will never be
collected.

Despite the cycle collector, it's still a good idea to define an explicit
@code{close()} method on objects to be called whenever you're done with them.  The
@code{close()} method can then remove attributes that refer to subobjects.  Don't
call @code{__del__()} directly -- @code{__del__()} should call @code{close()} and
@code{close()} should make sure that it can be called more than once for the same
object.

Une alternative pour éviter les références cycliques consiste à utiliser le module @ref{113,,weakref}, qui permet de faire référence à des objets sans incrémenter leur compteur de références. Par exemple, les structures d'arbres devraient utiliser des références faibles entre pères et fils (si nécessaire !).

@c XXX relevant for Python 3?
@c 
@c If the object has ever been a local variable in a function that caught an
@c expression in an except clause, chances are that a reference to the object
@c still exists in that function's stack frame as contained in the stack trace.
@c Normally, calling :func:`sys.exc_clear` will take care of this by clearing
@c the last recorded exception.

Finally, if your @code{__del__()} method raises an exception, a warning message
is printed to @ref{926,,sys.stderr}.

@node Comment obtenir toutes les instances d'une classe ?,Pourquoi le résultat de id peut-il être le même pour deux objets différents ?,Ma classe définit __del__ mais elle n'est pas appelée lorsque je supprime l'objet,Objets
@anchor{faq/programming how-do-i-get-a-list-of-all-instances-of-a-given-class}@anchor{4fa8}
@subsubsection Comment obtenir toutes les instances d'une classe ?


Python ne tient pas de registre de toutes les instances d'une classe (ni de n'importe quel type natif). Il est cependant possible de programmer le constructeur de la classe de façon à tenir un tel registre, en maintenant une liste de références faibles vers chaque instance.

@node Pourquoi le résultat de id peut-il être le même pour deux objets différents ?,Quand puis-je raisonnablement utiliser le test d'identité is ?,Comment obtenir toutes les instances d'une classe ?,Objets
@anchor{faq/programming why-does-the-result-of-id-appear-to-be-not-unique}@anchor{4fa9}
@subsubsection Pourquoi le résultat de @code{id()} peut-il être le même pour deux objets différents ?


La fonction native @ref{13d9,,id()} renvoie un entier dont l'unicité est garantie durant toute la vie de l'objet. Vu qu'en CPython cet entier est en réalité l'adresse mémoire de l'objet, il est fréquent qu'un nouvel objet soit alloué à une adresse mémoire identique à celle d'un objet venant d'être supprimé. Comme l'illustre le code suivant :

@example
>>> id(1000) 
13901272
>>> id(2000) 
13901272
@end example

Les deux identifiants appartiennent à des objets entiers créés juste avant l'appel à @code{id()} et détruits immédiatement après. Pour s'assurer que les objets dont on veut examiner les identifiants sont toujours en vie, créons une nouvelle référence à l'objet :

@example
>>> a = 1000; b = 2000
>>> id(a) 
13901272
>>> id(b) 
13891296
@end example

@node Quand puis-je raisonnablement utiliser le test d'identité is ?,Comment définir dans une classe fille les attributs d'une instance immuable ?,Pourquoi le résultat de id peut-il être le même pour deux objets différents ?,Objets
@anchor{faq/programming when-can-i-rely-on-identity-tests-with-the-is-operator}@anchor{4faa}
@subsubsection Quand puis-je raisonnablement utiliser le test d'identité `is' ?


L'opérateur @code{is} détermine si deux objets sont identiques, c'est-à-dire le même objet. Le test @code{a is b} est équivalent à @code{id(a) == id(b)}.

La propriété la plus importante du test d'identité est qu'un objet est toujours identique à lui-même. Quelle que soit la valeur de `a', @code{a is a} vaut toujours @code{True}. Un test d'identité est généralement plus rapide qu'un test d'égalité. De plus, contrairement à l'opérateur @code{==}, l'opérateur @code{is} renvoie toujours un booléen, @code{True} ou @code{False}.

Cependant, les tests d'identité ne peuvent remplacer les tests d'égalité que si l'identité est garantie. C'est le cas dans les trois situations suivantes :

1) Assignments create new names but do not change object identity.  After the
assignment @code{new = old}, it is guaranteed that @code{new is old}.

Le stockage d'un objet dans un conteneur qui fonctionne avec des références n'altère pas l'identité. Si @code{s} est une liste, alors après l'affectation de `x' à l'indice 0, @code{s[0] = x}, le test @code{s[0] is x} s'évalue forcément à @code{True}.

3) If an object is a singleton, it means that only one instance of that object
can exist.  After the assignments @code{a = None} and @code{b = None}, it is
guaranteed that @code{a is b} because @code{None} is a singleton.

Dans la plupart des autres cas, un test d'identité n'est pas approprié par rapport à un test d'égalité. En particulier, il ne faut pas utiliser @code{is} pour comparer à des constantes comme les entiers (type @ref{254,,int}) ou des chaînes de caractères (type @ref{435,,str}) car ces valeurs ne sont pas nécessairement des singletons :

@example
>>> a = 1000
>>> b = 500
>>> c = b + 500
>>> a is c
False

>>> a = 'Python'
>>> b = 'Py'
>>> c = b + 'thon'
>>> a is c
False
@end example

De même, deux instances fraîchement créées d'un type de conteneurs mutables ne sont jamais identiques :

@example
>>> a = []
>>> b = []
>>> a is b
False
@end example

Voici quelques exemples de la bibliothèque standard qui illustrent comment utiliser correctement les tests d'identité dans certaines situations particulières :

1) As recommended by 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}, an identity test is the preferred way to check
for @code{None}.  This reads like plain English in code and avoids confusion with
other objects that may have boolean values that evaluate to false.

2) Detecting optional arguments can be tricky when @code{None} is a valid input
value.  In those situations, you can create a singleton sentinel object
guaranteed to be distinct from other objects.  For example, here is how
to implement a method that behaves like @ref{339,,dict.pop()}:

@example
_sentinel = object()

def pop(self, key, default=_sentinel):
    if key in self:
        value = self[key]
        del self[key]
        return value
    if default is _sentinel:
        raise KeyError(key)
    return default
@end example

3) Container implementations sometimes need to augment equality tests with
identity tests.  This prevents the code from being confused by objects such as
@code{float('NaN')} that are not equal to themselves.

For example, here is the implementation of
@code{collections.abc.Sequence.__contains__()}:

@example
def __contains__(self, value):
    for v in self:
        if v is value or v == value:
            return True
    return False
@end example

@node Comment définir dans une classe fille les attributs d'une instance immuable ?,Comment mettre en cache le résultat d'une méthode ?,Quand puis-je raisonnablement utiliser le test d'identité is ?,Objets
@anchor{faq/programming how-can-a-subclass-control-what-data-is-stored-in-an-immutable-instance}@anchor{4fab}
@subsubsection Comment définir dans une classe fille les attributs d'une instance immuable ?


When subclassing an immutable type, override the @ref{56c,,__new__()} method
instead of the @ref{69b,,__init__()} method.  The latter only runs `after' an
instance is created, which is too late to alter data in an immutable
instance.

Toutes les classes d'objets immuables suivantes ont des signatures de constructeur différentes de leur classe mère :

@example
from datetime import date

class FirstOfMonthDate(date):
    "Always choose the first day of the month"
    def __new__(cls, year, month, day):
        return super().__new__(cls, year, month, 1)

class NamedInt(int):
    "Allow text names for some numbers"
    xlat = @{'zero': 0, 'one': 1, 'ten': 10@}
    def __new__(cls, value):
        value = cls.xlat.get(value, value)
        return super().__new__(cls, value)

class TitleStr(str):
    "Convert str to name suitable for a URL path"
    def __new__(cls, s):
        s = s.lower().replace(' ', '-')
        s = '@w{'}.join([c for c in s if c.isalnum() or c == '-'])
        return super().__new__(cls, s)
@end example

Ces classes s'utilisent comme ceci :

@example
>>> FirstOfMonthDate(2012, 2, 14)
FirstOfMonthDate(2012, 2, 1)
>>> NamedInt('ten')
10
>>> NamedInt(20)
20
>>> TitleStr('Blog: Why Python Rocks')
'blog-why-python-rocks'
@end example

@node Comment mettre en cache le résultat d'une méthode ?,,Comment définir dans une classe fille les attributs d'une instance immuable ?,Objets
@anchor{faq/programming faq-cache-method-calls}@anchor{26ba}@anchor{faq/programming how-do-i-cache-method-calls}@anchor{4fac}
@subsubsection Comment mettre en cache le résultat d'une méthode ?


Il existe deux outils principaux pour mettre en cache la valeur de retour d'une méthode, à savoir @ref{52c,,functools.cached_property()}, qui stocke les valeurs au niveau de l'instance, et @ref{9dd,,functools.lru_cache()}, qui le fait au niveau de la classe.

La fonction @code{cached_property} n'est applicable qu'aux méthodes sans argument. Elle n'induit aucune référence vers l'instance. Le cache est simplement conservé aussi longtemps que l'instance elle-même.

L'avantage est que le cache est supprimé aussitôt que l'instance est détruite. L'inconvénient est que les caches peuvent s'accumuler avec les instances, sans limite de nombre.

La fonction @code{lru_cache} s'applique quant à elle aux méthodes dont les arguments sont @ref{5fb,,hachables}. Elle crée une référence forte à l'instance, sauf à passer par des circonvolutions pour que la référence soit faible.

L'avantage de l'algorithme LRU est d'offrir une limitation sur la taille du cache, que l'on peut régler avec le paramètre `maxsize' (NdT : LRU signifie `Least Recently Used' en anglais, les entrées du cache les plus anciennes sont évincées pour conserver la taille). L'inconvénient est qu'une référence forte vers l'instance est conservée dans le cache, ce qui maintient l'instance hors de portée du ramasse-miettes jusqu'à ce que l'entrée soit effacée du cache ou que le cache soit remis à zéro.

Voici une démonstration des différentes techniques :

@example
class Weather:
    "Lookup weather information on a government website"

    def __init__(self, station_id):
        self._station_id = station_id
        # The _station_id is private and immutable

    def current_temperature(self):
        "Latest hourly observation"
        # Do not cache this because old results
        # can be out of date.

    @@cached_property
    def location(self):
        "Return the longitude/latitude coordinates of the station"
        # Result only depends on the station_id

    @@lru_cache(maxsize=20)
    def historic_rainfall(self, date, units='mm'):
        "Rainfall on a given date"
        # Depends on the station_id, date, and units.
@end example

Cet exemple suppose que l'attribut `station_id' n'est jamais changé. Si les attributs utilisés par la méthode sont susceptibles d'être modifiés, @code{cached_property} ne peut pas fonctionner car elle ne peut pas détecter les mutations pour invalider le cache.

To make the `lru_cache' approach work when the `station_id' is mutable,
the class needs to define the @ref{ae8,,__eq__()} and @ref{ae9,,__hash__()}
methods so that the cache can detect relevant attribute updates:

@example
class Weather:
    "Example with a mutable station identifier"

    def __init__(self, station_id):
        self.station_id = station_id

    def change_station(self, station_id):
        self.station_id = station_id

    def __eq__(self, other):
        return self.station_id == other.station_id

    def __hash__(self):
        return hash(self.station_id)

    @@lru_cache(maxsize=20)
    def historic_rainfall(self, date, units='cm'):
        'Rainfall on a given date'
        # Depends on the station_id, date, and units.
@end example

@node Modules<5>,,Objets,FAQ de programmation
@anchor{faq/programming modules}@anchor{4fad}
@subsection Modules


@menu
* Comment créer des fichiers .pyc ?: Comment créer des fichiers pyc ?. 
* Comment obtenir le nom du module actuel ?:: 
* Comment avoir des modules qui s'importent mutuellement ?:: 
* __import__('x.y.z') renvoie <module 'x'> ; comment accéder à z ?: __import__ 'x y z' renvoie <module 'x'> ; comment accéder à z ?. 
* Quand j'édite un module et que je le réimporte@comma{} je ne vois pas les changements. Pourquoi ?: Quand j'édite un module et que je le réimporte je ne vois pas les changements Pourquoi ?. 

@end menu

@node Comment créer des fichiers pyc ?,Comment obtenir le nom du module actuel ?,,Modules<5>
@anchor{faq/programming how-do-i-create-a-pyc-file}@anchor{4fae}
@subsubsection Comment créer des fichiers @code{.pyc} ?


Quand un module est importé pour la première fois (ou si le fichier source a été modifié depuis la création du fichier compilé), un fichier @code{.pyc} contenant le code précompilé est créé dans un sous-dossier @code{__pycache__} du dossier contentant le fichier @code{.py}. Le nom du fichier @code{.pyc} est identique au fichier @code{.py} et se termine par @code{.pyc}, avec une partie centrale qui dépend du binaire @code{python} qui l'a créé (voir la 
@geindex Python Enhancement Proposals; PEP 3147
PEP 3147@footnote{https://peps.python.org/pep-3147/} pour de plus amples précisions).

Une des raisons pour lesquelles un fichier @code{.pyc} peut ne pas être créé est un problème de droits sur le dossier qui contient le fichier source, ce qui veut dire qu'il est impossible de créer le sous-dossier @code{__pycache__}. Ceci peut arriver, par exemple, si vous développez en tant qu'un certain utilisateur, mais que le code est exécuté en tant qu'un autre utilisateur, par exemple pour tester un serveur Web.

La création du fichier @code{.pyc} est automatique durant l'importation d'un module si Python est capable (en termes de droits, d'espace disque, etc) de créer un sous-dossier @code{__pycache__} et d'écrire le module ainsi compilé dans ce sous-répertoire, à moins que la variable d'environnement 
@geindex PYTHONDONTWRITEBYTECODE
@geindex variable d'environnement; PYTHONDONTWRITEBYTECODE
@ref{1385,,PYTHONDONTWRITEBYTECODE} soit définie.

Exécuter du Python dans un script de plus haut niveau n'est pas considéré comme une importation et le fichier @code{.pyc} n'est pas créé. Par exemple, si un module de plus haut niveau @code{foo.py} importe un autre module @code{xyz.py}, alors à l'exécution de @code{foo} (en tapant @code{python foo.py} dans la console), un fichier @code{.pyc} est créé pour @code{xyz} mais pas pour @code{foo} car @code{foo.py} n'est pas importé.

Pour créer un fichier @code{.pyc} pour @code{foo} — c'est-à-dire créer un fichier @code{.pyc} pour un module qui n'est pas importé — il existe les modules @ref{b2,,py_compile} et @ref{20,,compileall}.

Le module @ref{b2,,py_compile} peut compiler n'importe quel module manuellement. Il est ainsi possible d'appeler la fonction @code{compile()} de manière interactive :

@example
>>> import py_compile
>>> py_compile.compile('foo.py')                 
@end example

Ces lignes écrivent le @code{.pyc} dans un sous-dossier @code{__pycache__} à côté de @code{foo.py} (le paramètre optionnel @code{cfile} permet de changer ce comportement).

Tous les fichiers d'un ou plusieurs dossiers peuvent aussi être compilés avec le module @ref{20,,compileall}. C'est possible depuis l'invite de commande en exécutant @code{compileall.py} avec le chemin du dossier contenant les fichiers Python à compiler :

@example
python -m compileall .
@end example

@node Comment obtenir le nom du module actuel ?,Comment avoir des modules qui s'importent mutuellement ?,Comment créer des fichiers pyc ?,Modules<5>
@anchor{faq/programming how-do-i-find-the-current-module-name}@anchor{4faf}
@subsubsection Comment obtenir le nom du module actuel ?


Un module peut déterminer son propre nom en examinant la variable globale prédéfinie @code{__name__}. Si celle-ci vaut @code{'__main__'}, c'est que le programme est exécuté comme un script. Beaucoup de modules qui doivent normalement être importés pour pouvoir être utilisés fournissent aussi une interface en ligne de commande ou un test automatique. Ils n'exécutent cette portion du code qu'après avoir vérifié la valeur de @code{__name__} :

@example
def main():
    print('Running test...')
    ...

if __name__ == '__main__':
    main()
@end example

@node Comment avoir des modules qui s'importent mutuellement ?,__import__ 'x y z' renvoie <module 'x'> ; comment accéder à z ?,Comment obtenir le nom du module actuel ?,Modules<5>
@anchor{faq/programming how-can-i-have-modules-that-mutually-import-each-other}@anchor{4fb0}
@subsubsection Comment avoir des modules qui s'importent mutuellement ?


Considérons les modules suivants :

@code{foo.py} :

@example
from bar import bar_var
foo_var = 1
@end example

@code{bar.py} :

@example
from foo import foo_var
bar_var = 2
@end example

Le problème réside dans les étapes que l'interpréteur va réaliser :


@itemize *

@item 
`main' importe `foo' ;

@item 
Les variables globales (vides) de `foo' sont créées ;

@item 
`foo' est compilé et commence à s'exécuter ;

@item 
`foo' importe `bar' ;

@item 
Les variables globales (vides) de `bar' sont créées ;

@item 
`bar' est compilé et commence à s'exécuter ;

@item 
`bar' importe `foo' (en réalité, rien ne passe car il y a déjà un module appelé `foo') ;

@item 
La mécanique des importations tente de lire `foo_var' dans les variables globales de `foo' pour procéder à l'affectation @code{bar.foo_var = foo.foo_var}.
@end itemize

La dernière étape échoue car Python n'a pas fini d'interpréter @code{foo} et le dictionnaire global des symboles de @code{foo} est encore vide.

Le même phénomène arrive quand on utilise @code{import foo}, et qu'on essaye ensuite d'accéder à @code{foo.foo_var} dans le code global.

Il y a (au moins) trois façons de contourner ce problème.

Guido van Rossum déconseille d'utiliser @code{from <module> import ...} et de mettre tout le code dans des fonctions.  L'initialisation des variables globales et des variables de classe ne doit utiliser que des constantes ou des fonctions natives.  Ceci implique que tout ce qui est fourni par un module soit référencé par @code{<module>.<nom>}.

Jim Roskind recommande d'effectuer les étapes suivantes dans cet ordre dans chaque module :


@itemize *

@item 
les exportations (variables globales, fonctions et les classes qui ne nécessitent d'importer des classes mères)

@item 
les instructions @code{import}

@item 
le code (avec les variables globales qui sont initialisées à partir de valeurs importées).
@end itemize

van Rossum désapprouve cette approche car les importations se trouvent à un endroit bizarre, mais cela fonctionne.

Matthias Urlichs conseille de restructurer le code pour éviter les importations récursives.

Ces solutions peuvent être combinées.

@node __import__ 'x y z' renvoie <module 'x'> ; comment accéder à z ?,Quand j'édite un module et que je le réimporte je ne vois pas les changements Pourquoi ?,Comment avoir des modules qui s'importent mutuellement ?,Modules<5>
@anchor{faq/programming import-x-y-z-returns-module-x-how-do-i-get-z}@anchor{4fb1}
@subsubsection @code{__import__('x.y.z')} renvoie @code{<module 'x'>} ; comment accéder à @code{z} ?


Utilisez plutôt la fonction @ref{501,,import_module()} de @ref{76,,importlib} :

@example
z = importlib.import_module('x.y.z')
@end example

@node Quand j'édite un module et que je le réimporte je ne vois pas les changements Pourquoi ?,,__import__ 'x y z' renvoie <module 'x'> ; comment accéder à z ?,Modules<5>
@anchor{faq/programming when-i-edit-an-imported-module-and-reimport-it-the-changes-don-t-show-up-why-does-this-happen}@anchor{4fb2}
@subsubsection Quand j'édite un module et que je le réimporte, je ne vois pas les changements. Pourquoi ?


Pour des raisons de performance et de cohérence, Python ne lit le fichier d'un module que la première fois où celui-ci est importé. Si ce n'était pas le cas, dans un programme composé d'un très grand nombre de modules qui importent tous le même module de base, ce module de base serait analysé et ré-analysé un très grand nombre de fois. Pour forcer la relecture d'un module, il faut faire :

@example
import importlib
import modname
importlib.reload(modname)
@end example

Attention, cette technique ne marche pas systématiquement. En particulier, les modules qui contiennent des instructions comme

@example
from modname import some_objects
@end example

continuent de fonctionner avec l'ancienne version des objets importés. Si le module contient une définition de classe, les instances déjà existantes de celle-ci ne sont `pas' mises à jour avec la nouvelle définition de la classe. Ceci peut conduire au comportement paradoxal suivant :

@example
>>> import importlib
>>> import cls
>>> c = cls.C()                # Create an instance of C
>>> importlib.reload(cls)
<module 'cls' from 'cls.py'>
>>> isinstance(c, cls.C)       # isinstance is false?!?
False
@end example

La nature du problème apparaît clairement en affichant « l'identité » des objets de la classe :

@example
>>> hex(id(c.__class__))
'0x7352a0'
>>> hex(id(cls.C))
'0x4198d0'
@end example

@node FAQ sur l'histoire et la conception,FAQ sur la bibliothèque et les extensions,FAQ de programmation,Questions fréquemment posées sur Python
@anchor{faq/design doc}@anchor{4fb3}@anchor{faq/design design-and-history-faq}@anchor{4fb4}
@section FAQ sur l'histoire et la conception



@menu
* Pourquoi Python utilise-t-il l'indentation pour grouper les instructions ?:: 
* Pourquoi ai-je d'étranges résultats suite à de simples opérations arithmétiques ?:: 
* Pourquoi les calculs à virgules flottantes sont si imprécis ?:: 
* Pourquoi les chaînes de caractères Python sont-elles immuables ?:: 
* Pourquoi self doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?:: 
* Pourquoi ne puis-je pas utiliser d'assignation dans une expression ?:: 
* Pourquoi Python utilise des méthodes pour certaines fonctionnalités (ex ; list.index()) mais des fonctions pour d'autres (ex ; len(list)) ?: Pourquoi Python utilise des méthodes pour certaines fonctionnalités ex list index mais des fonctions pour d'autres ex len list ?. 
* Pourquoi join() est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?: Pourquoi join est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?. 
* À quel point les exceptions sont-elles rapides ?:: 
* Pourquoi n'y a-t-il pas une instruction switch ou une structure similaire à switch / case en Python ?:: 
* Est-il possible d'émuler des fils d'exécution dans l'interpréteur plutôt que se baser sur les implémentations spécifiques aux systèmes d'exploitation ?:: 
* Pourquoi les expressions lambda ne peuvent pas contenir d'instructions ?:: 
* Python peut-il être compilé en code machine@comma{} en C ou dans un autre langage ?: Python peut-il être compilé en code machine en C ou dans un autre langage ?. 
* Comment Python gère la mémoire ?:: 
* Pourquoi CPython n'utilise-t-il pas un modèle de ramasse-miettes plus traditionnel ?:: 
* Pourquoi toute la mémoire n'est pas libérée lorsque CPython s'arrête ?:: 
* Pourquoi les n-uplets et les list sont deux types de données séparés ?:: 
* Comment les listes sont-elles implémentées dans CPython ?:: 
* Comment les dictionnaires sont-ils implémentés dans CPython ?:: 
* Pourquoi les clés du dictionnaire sont immuables ?:: 
* Pourquoi list.sort() ne renvoie pas la liste triée ?: Pourquoi list sort ne renvoie pas la liste triée ?. 
* Comment spécifier une interface et appliquer une spécification d’interface en Python ?:: 
* Pourquoi n'y a-t-il pas de goto en Python ?:: 
* Pourquoi les chaînes de caractères brutes (r-strings) ne peuvent-elles pas se terminer par un backslash ?: Pourquoi les chaînes de caractères brutes r-strings ne peuvent-elles pas se terminer par un backslash ?. 
* Pourquoi la déclaration with pour les assignations d'attributs n'existe pas en Python ?:: 
* Pourquoi l'instruction with ne prend-elle pas en charge les générateurs ?:: 
* Pourquoi les deux-points sont-ils nécessaires pour les déclarations if/while/def/class ?:: 
* Pourquoi Python permet-il les virgules à la fin des listes et des n-uplets ?:: 

@end menu

@node Pourquoi Python utilise-t-il l'indentation pour grouper les instructions ?,Pourquoi ai-je d'étranges résultats suite à de simples opérations arithmétiques ?,,FAQ sur l'histoire et la conception
@anchor{faq/design why-does-python-use-indentation-for-grouping-of-statements}@anchor{4fb5}
@subsection Pourquoi Python utilise-t-il l'indentation pour grouper les instructions ?


Guido van Rossum considère que l'usage de l'indentation pour regrouper les blocs d'instruction est élégant et contribue énormément à la clarté d'un programme Python ordinaire. La plupart des gens finissent par aimer cette particularité au bout d'un moment.

Comme il n'y a pas d'accolades de début et fin, il ne peut y avoir de différence entre le bloc perçu par l'analyseur syntaxique et le lecteur humain. Parfois les programmeurs C pourront trouver un morceau de code comme celui-ci :

@example
if (x <= y)
        x++;
        y--;
z++;
@end example

Seule l'instruction @code{x++} est exécutée si la condition est vraie, mais l'indentation conduit beaucoup de gens à penser le contraire. Mêmes des développeurs C expérimentés peuvent parfois rester pendant un moment à se demander pourquoi @code{y} est décrémenté même si @code{x > y}.

Comme il n'y a pas d'accolades de début et fin, Python est moins sujet aux conflits de style de code. En C, on peut placer les accolades de nombreuses façons. Après s'être habitué à lire et écrire selon un style particulier, il est normal de se sentir perturbé en lisant (ou en devant écrire) avec un autre style.

Nombre de styles de programmation utilisent des accolades de début et fin sur une ligne à part. Cela rend les programmes beaucoup plus longs et fait perdre une bonne partie de l'espace visible sur l'écran, empêchant un peu d'avoir une vue globale du programme. Idéalement, une fonction doit être visible sur un écran (environ 20 ou 30 lignes). 20 lignes de Python peuvent faire beaucoup plus que 20 lignes de C. Ce n'est pas seulement dû à l'absence d'accolades de début et fin — l'absence de déclarations et la présence de types de haut-niveau en sont également responsables — mais la syntaxe basée sur l'indentation aide sûrement.

@node Pourquoi ai-je d'étranges résultats suite à de simples opérations arithmétiques ?,Pourquoi les calculs à virgules flottantes sont si imprécis ?,Pourquoi Python utilise-t-il l'indentation pour grouper les instructions ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-am-i-getting-strange-results-with-simple-arithmetic-operations}@anchor{4fb6}
@subsection Pourquoi ai-je d'étranges résultats suite à de simples opérations arithmétiques ?


Voir la question suivante.

@node Pourquoi les calculs à virgules flottantes sont si imprécis ?,Pourquoi les chaînes de caractères Python sont-elles immuables ?,Pourquoi ai-je d'étranges résultats suite à de simples opérations arithmétiques ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-are-floating-point-calculations-so-inaccurate}@anchor{4fb7}
@subsection Pourquoi les calculs à virgules flottantes sont si imprécis ?


Les gens sont très souvent surpris par des résultats comme celui-ci :

@example
>>> 1.2 - 1.0
0.19999999999999996
@end example

et pensent que c'est un bogue dans Python. Ça n'en est pas un. Ceci n'a d'ailleurs que peu à voir avec Python, mais avec la manière dont la plateforme sous-jacente gère les nombres à virgule flottante.

La classe @ref{2eb,,float} dans CPython utilise le type double du langage C comme stockage. La valeur d'un objet @ref{2eb,,float} est stockée dans un format binaire à virgule flottante avec une précision fixe (généralement 53 bits). Python utilise des opérations qui proviennent du langage C qui à leur tour reposent sur l'implémentation au niveau du processeur afin d'effectuer des opérations en virgule flottante. Cela signifie que, dans le cadre des opérations sur les nombres à virgule flottante, Python se comporte comme beaucoup de langages populaires dont C et Java.

Many numbers that can be written easily in decimal notation cannot be expressed
exactly in binary floating point.  For example, after:

@example
>>> x = 1.2
@end example

la valeur stockée pour @code{x} est une (très bonne) approximation de la valeur décimale @code{1.2}, mais cette valeur n'est pas exacte. Sur une machine typique, la valeur stockée est en fait :

@example
1.0011001100110011001100110011001100110011001100110011 (binary)
@end example

qui est, exactement :

@example
1.1999999999999999555910790149937383830547332763671875 (decimal)
@end example

La précision typique de 53 bits des `floats' Python permet une précision de 15–16 décimales.

For a fuller explanation, please see the @ref{1c9d,,floating-point arithmetic} chapter in the Python tutorial.

@node Pourquoi les chaînes de caractères Python sont-elles immuables ?,Pourquoi self doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?,Pourquoi les calculs à virgules flottantes sont si imprécis ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-are-python-strings-immutable}@anchor{4fb8}
@subsection Pourquoi les chaînes de caractères Python sont-elles immuables ?


Il y a plusieurs avantages.

La première concerne la performance : savoir qu'une chaîne de caractères est immuable signifie que l'allocation mémoire allouée lors de la création de cette chaîne est fixe et figée. C'est aussi l'une des raisons pour lesquelles on fait la distinction entre les `n'-uplets et les listes.

Un autre avantage est que les chaînes en Python sont considérées aussi « élémentaires » que les nombres. Aucun processus ne changera la valeur du nombre 8 en autre chose et, en Python, aucun processus ne changera la chaîne de caractères "huit" en autre chose.

@node Pourquoi self doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?,Pourquoi ne puis-je pas utiliser d'assignation dans une expression ?,Pourquoi les chaînes de caractères Python sont-elles immuables ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-must-self-be-used-explicitly-in-method-definitions-and-calls}@anchor{4fb9}@anchor{faq/design why-self}@anchor{4f9f}
@subsection Pourquoi `self' doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?


L'idée a été empruntée à Modula-3. Cela s'avère très utile, pour diverses raisons.

Tout d'abord, il est plus évident d'utiliser une méthode ou un attribut d'instance par exemple au lieu d'une variable locale. Lire @code{self.x} ou @code{self.meth()} est sans ambiguïté sur le fait que c'est une variable d'instance ou une méthode qui est utilisée, même si vous ne connaissez pas la définition de classe par cœur. En C++, vous pouvez les reconnaître par l'absence d'une déclaration de variable locale (en supposant que les variables globales sont rares ou facilement reconnaissables) — mais en Python, il n'y a pas de déclarations de variables locales, de sorte que vous devriez chercher la définition de classe pour être sûr. Certaines normes de programmation C++ et Java préfixent les attributs d'instance par @code{m_}. Cette syntaxe explicite est ainsi utile également pour ces langages.

Second, it means that no special syntax is necessary if you want to explicitly
reference or call the method from a particular class.  In C++, if you want to
use a method from a base class which is overridden in a derived class, you have
to use the @code{::} operator -- in Python you can write
@code{baseclass.methodname(self, <argument list>)}.  This is particularly useful
for @ref{69b,,__init__()} methods, and in general in cases where a derived class
method wants to extend the base class method of the same name and thus has to
call the base class method somehow.

Enfin, pour des variables d'instance, ça résout un problème syntactique pour l'assignation : puisque les variables locales en Python sont (par définition !) ces variables auxquelles les valeurs sont assignées dans le corps d'une fonction (et n'étant pas déclarées explicitement globales), il doit y avoir un moyen de dire à l'interpréteur qu'une assignation est censée assigner une variable d'instance plutôt qu'une variable locale, et doit de préférence être syntactique (pour des raisons d'efficacité). C++ fait ça au travers de déclarations, mais Python n'a pas de déclarations et ça serait dommage d'avoir à les introduire juste pour cette raison. Utiliser explicitement @code{self.var} résout ça avec élégance. Pareillement, pour utiliser des variables d'instance, avoir à écrire @code{self.var} signifie que les références vers des noms non-qualifiés au sein d'une méthode n'ont pas à être cherchés dans l'annuaire d'instances. En d'autres termes, les variables locales et les variables d'instance vivent dans deux différents espaces de nommage, et vous devez dire à Python quel espace de nommage utiliser.

@node Pourquoi ne puis-je pas utiliser d'assignation dans une expression ?,Pourquoi Python utilise des méthodes pour certaines fonctionnalités ex list index mais des fonctions pour d'autres ex len list ?,Pourquoi self doit-il être explicitement utilisé dans les définitions et les appels de méthodes ?,FAQ sur l'histoire et la conception
@anchor{faq/design id1}@anchor{4fba}@anchor{faq/design why-can-t-i-use-an-assignment-in-an-expression}@anchor{1bdf}
@subsection Pourquoi ne puis-je pas utiliser d'assignation dans une expression ?


Depuis Python 3.8, c'est possible !

Les expressions d'affectation qui utilisent l'opérateur morse @code{:=} affectent une variable dans une expression :

@example
while chunk := fp.read(200):
   print(chunk)
@end example

Voir la 
@geindex Python Enhancement Proposals; PEP 572
PEP 572@footnote{https://peps.python.org/pep-0572/} pour plus d'informations.

@node Pourquoi Python utilise des méthodes pour certaines fonctionnalités ex list index mais des fonctions pour d'autres ex len list ?,Pourquoi join est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?,Pourquoi ne puis-je pas utiliser d'assignation dans une expression ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-does-python-use-methods-for-some-functionality-e-g-list-index-but-functions-for-other-e-g-len-list}@anchor{4fbb}
@subsection Pourquoi Python utilise des méthodes pour certaines fonctionnalités (ex : @code{list.index()}) mais des fonctions pour d'autres (ex : @code{len(list)}) ?


Comme l'a dit Guido :

@quotation

(a) Pour certaines opérations, la notation préfixe se lit mieux que celle suffixe — les opérations préfixe (et infixe !) sont une longue tradition en mathématique, où on apprécie les notations qui aident visuellement le mathématicien à réfléchir sur un problème. Comparez la facilité avec laquelle nous réécrivons une formule comme x*(a+b) en x*a + x*b à la lourdeur de faire la même chose avec une notation orientée objet brute.

(b) Quand je lis du code qui dit @code{len(x)} `je sais' qu'il demande la longueur de quelque chose. Cela me dit deux choses : le résultat est un entier, et l'argument est une sorte de conteneur. Au contraire, quand je lis @code{x.len()}, je dois déjà savoir que x est une sorte de conteneur implémentant une interface ou héritant d'une classe qui a un @code{len()} standard. Voyez la confusion qui arrive parfois quand une classe qui n'implémente pas une interface de dictionnaire a une méthode @code{get()} ou @code{key()}, ou quand un objet qui n'est pas un fichier implémente une méthode @code{write()}.


@center --- @indicateurl{https://mail.python.org/pipermail/python-3000/2006-November/004643.html}

@end quotation

@node Pourquoi join est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?,À quel point les exceptions sont-elles rapides ?,Pourquoi Python utilise des méthodes pour certaines fonctionnalités ex list index mais des fonctions pour d'autres ex len list ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-is-join-a-string-method-instead-of-a-list-or-tuple-method}@anchor{4fbc}
@subsection Pourquoi @code{join()} est une méthode de chaîne plutôt qu'une méthode de liste ou de `n'-uplet ?


Les chaînes sont devenues bien plus comme d'autres types standards à partir de Python 1.6, lorsque les méthodes ont été ajoutées fournissant ainsi les mêmes fonctionnalités que celles qui étaient déjà disponibles en utilisant les fonctions du module string. La plupart de ces nouvelles méthodes ont été largement acceptées, mais celle qui semble rendre certains programmeurs mal à l'aise est :

@example
", ".join(['1', '2', '4', '8', '16'])
@end example

qui donne le résultat :

@example
"1, 2, 4, 8, 16"
@end example

Il y a deux arguments fréquents contre cet usage.

Le premier argument peut se résumer à : « c'est vraiment moche d'utiliser une méthode de chaîne littérale (c.-à-d. constante) ». La réponse est « certes, mais une chaîne littérale est une valeur comme une autre, juste fixe ». Si on utilise les méthodes sur des noms de variables, il n'y a pas de raison à les interdire sur des chaînes littérales.

Le second consiste à se demander : « suis-je réellement en train de dire à une séquence de joindre ses membres avec une constante de chaîne ? ». Malheureusement, ce n'est pas ça. Allez savoir, il semble être bien moins difficile de comprendre ce qui se passe avec @ref{e93,,split()} en tant que méthode de chaîne, puisque dans ce cas il est facile de voir que

@example
"1, 2, 4, 8, 16".split(", ")
@end example

est une instruction à une chaîne littérale de renvoyer les sous-chaînes délimitées par le séparateur fourni (ou, par défaut, les espaces ou groupes d'espaces).

@ref{2134,,join()} est une méthode de chaîne parce qu'en l'utilisant vous dites au séparateur de chaîne d'itérer une séquence de chaînes et de s'insérer entre les éléments adjacents. Cette méthode peut être utilisée avec n'importe quel argument qui obéit aux règles d'objets séquence, incluant n'importe quelles nouvelles classes que vous pourriez définir vous-même. Des méthodes similaires existent pour des objets @code{bytes} et @code{bytearray}.

@node À quel point les exceptions sont-elles rapides ?,Pourquoi n'y a-t-il pas une instruction switch ou une structure similaire à switch / case en Python ?,Pourquoi join est une méthode de chaîne plutôt qu'une méthode de liste ou de n-uplet ?,FAQ sur l'histoire et la conception
@anchor{faq/design how-fast-are-exceptions}@anchor{4fbd}
@subsection À quel point les exceptions sont-elles rapides ?


A @ref{6d3,,try}/@ref{189,,except} block is extremely efficient if no exceptions
are raised.  Actually
catching an exception is expensive.  In versions of Python prior to 2.0 it was
common to use this idiom:

@example
try:
    value = mydict[key]
except KeyError:
    mydict[key] = getvalue(key)
    value = mydict[key]
@end example

Cela n'a de sens que si vous vous attendez à ce que le dictionnaire ait la clé presque tout le temps. Si ce n'était pas le cas, vous l'auriez codé comme suit :

@example
if key in mydict:
    value = mydict[key]
else:
    value = mydict[key] = getvalue(key)
@end example

Pour ce cas, vous pouvez également utiliser @code{value = dict.setdefault(key, getvalue(key))}, mais seulement si l'appel à @code{getvalue()} est suffisamment peu coûteux car il est évalué dans tous les cas.

@node Pourquoi n'y a-t-il pas une instruction switch ou une structure similaire à switch / case en Python ?,Est-il possible d'émuler des fils d'exécution dans l'interpréteur plutôt que se baser sur les implémentations spécifiques aux systèmes d'exploitation ?,À quel point les exceptions sont-elles rapides ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-isn-t-there-a-switch-or-case-statement-in-python}@anchor{4fbe}
@subsection Pourquoi n'y a-t-il pas une instruction `switch' ou une structure similaire à `switch / case' en Python ?


In general, structured switch statements execute one block of code
when an expression has a particular value or set of values.
Since Python 3.10 one can easily match literal values, or constants
within a namespace, with a @code{match ... case} statement.
An older alternative is a sequence of @code{if... elif... elif... else}.

Dans les cas où vous devez choisir parmi un très grand nombre de possibilités, vous pouvez créer un dictionnaire faisant correspondre des valeurs à des fonctions à appeler. Par exemple :

@example
functions = @{'a': function_1,
             'b': function_2,
             'c': self.method_1@}

func = functions[value]
func()
@end example

Pour appeler les méthodes sur des objets, vous pouvez simplifier davantage en utilisant la fonction native @ref{bbf,,getattr()} pour récupérer les méthodes avec un nom donné :

@example
class MyVisitor:
    def visit_a(self):
        ...

    def dispatch(self, value):
        method_name = 'visit_' + str(value)
        method = getattr(self, method_name)
        method()
@end example

Il est suggéré que vous utilisiez un préfixe pour les noms de méthodes, telles que @code{visit_} dans cet exemple. Sans ce préfixe, si les valeurs proviennent d'une source non fiable, un attaquant serait en mesure d'appeler n'importe quelle méthode sur votre objet.

Imitating switch with fallthrough, as with C's switch-case-default,
is possible, much harder, and less needed.

@node Est-il possible d'émuler des fils d'exécution dans l'interpréteur plutôt que se baser sur les implémentations spécifiques aux systèmes d'exploitation ?,Pourquoi les expressions lambda ne peuvent pas contenir d'instructions ?,Pourquoi n'y a-t-il pas une instruction switch ou une structure similaire à switch / case en Python ?,FAQ sur l'histoire et la conception
@anchor{faq/design can-t-you-emulate-threads-in-the-interpreter-instead-of-relying-on-an-os-specific-thread-implementation}@anchor{4fbf}
@subsection Est-il possible d'émuler des fils d'exécution dans l'interpréteur plutôt que se baser sur les implémentations spécifiques aux systèmes d'exploitation ?


Réponse 1 : malheureusement, l'interpréteur pousse au moins un bloc de pile C (`stack frame') pour chaque bloc de pile de Python. Aussi, les extensions peuvent rappeler dans Python à presque n'importe quel moment. Par conséquent, une implémentation complète des fils d'exécution nécessiterait une gestion complète pour le C.

Réponse 2 : heureusement, il existe Stackless Python@footnote{https://github.com/stackless-dev/stackless/wiki}, qui a complètement ré-architecturé la boucle principale de l'interpréteur afin de ne pas utiliser la pile C.

@node Pourquoi les expressions lambda ne peuvent pas contenir d'instructions ?,Python peut-il être compilé en code machine en C ou dans un autre langage ?,Est-il possible d'émuler des fils d'exécution dans l'interpréteur plutôt que se baser sur les implémentations spécifiques aux systèmes d'exploitation ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-can-t-lambda-expressions-contain-statements}@anchor{4fc0}
@subsection Pourquoi les expressions lambda ne peuvent pas contenir d'instructions ?


Les expressions lambda de Python ne peuvent pas contenir d'instructions parce que le cadre syntaxique de Python ne peut pas gérer les instructions imbriquées à l'intérieur d'expressions. Cependant, en Python, ce n'est pas vraiment un problème. Contrairement aux formes lambda dans d'autres langages, où elles ajoutent des fonctionnalités,  les expressions lambda de Python sont seulement une notation concise si vous êtes trop paresseux pour définir une fonction.

Les fonctions sont déjà des objets de première classe en Python et peuvent être déclarées dans une portée locale. L'unique avantage d'utiliser une fonction lambda au lieu d'une fonction définie localement est que vous n'avez nullement besoin d'un nom pour la fonction — mais c'est juste une variable locale à laquelle est affecté l'objet fonction (qui est exactement le même type d'objet que celui renvoyé par une expression lambda) !

@node Python peut-il être compilé en code machine en C ou dans un autre langage ?,Comment Python gère la mémoire ?,Pourquoi les expressions lambda ne peuvent pas contenir d'instructions ?,FAQ sur l'histoire et la conception
@anchor{faq/design can-python-be-compiled-to-machine-code-c-or-some-other-language}@anchor{4fc1}
@subsection Python peut-il être compilé en code machine, en C ou dans un autre langage ?


Cython@footnote{https://cython.org/} compiles a modified version of Python with
optional annotations into C extensions.  Nuitka@footnote{https://nuitka.net/} is
an up-and-coming compiler of Python into C++ code, aiming to support the full
Python language.

@node Comment Python gère la mémoire ?,Pourquoi CPython n'utilise-t-il pas un modèle de ramasse-miettes plus traditionnel ?,Python peut-il être compilé en code machine en C ou dans un autre langage ?,FAQ sur l'histoire et la conception
@anchor{faq/design how-does-python-manage-memory}@anchor{4fc2}
@subsection Comment Python gère la mémoire ?


Les détails de la gestion de la mémoire en Python dépendent de l'implémentation. En effet, l'implémentation standard de Python, @ref{6e0,,CPython}, utilise des compteurs de références afin de détecter des objets inaccessibles et un autre mécanisme pour collecter les références circulaires, exécutant périodiquement un algorithme de détection de cycles qui recherche les cycles inaccessibles et supprime les objets impliqués. Le module @ref{5f,,gc} fournit des fonctions pour lancer le ramasse-miettes, d'obtenir des statistiques de débogage et ajuster ses paramètres.

Other implementations (such as Jython@footnote{https://www.jython.org} or
PyPy@footnote{https://pypy.org}), however, can rely on a different mechanism
such as a full-blown garbage collector.  This difference can cause some
subtle porting problems if your Python code depends on the behavior of the
reference counting implementation.

Dans certaines implémentations de Python, le code suivant (qui fonctionne parfaitement avec `CPython') aurait probablement manqué de descripteurs de fichiers :

@example
for file in very_long_list_of_files:
    f = open(file)
    c = f.read(1)
@end example

Indeed, using CPython's reference counting and destructor scheme, each new
assignment to @code{f} closes the previous file.  With a traditional GC, however,
those file objects will only get collected (and closed) at varying and possibly
long intervals.

Si vous souhaitez écrire du code qui fonctionne avec n'importe quelle implémentation de Python, vous devez explicitement fermer le fichier ou utiliser l'instruction @ref{5bc,,with} ; ceci fonctionne indépendamment du système de gestion de la mémoire :

@example
for file in very_long_list_of_files:
    with open(file) as f:
        c = f.read(1)
@end example

@node Pourquoi CPython n'utilise-t-il pas un modèle de ramasse-miettes plus traditionnel ?,Pourquoi toute la mémoire n'est pas libérée lorsque CPython s'arrête ?,Comment Python gère la mémoire ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-doesn-t-cpython-use-a-more-traditional-garbage-collection-scheme}@anchor{4fc3}
@subsection Pourquoi CPython n'utilise-t-il pas un modèle de ramasse-miettes plus traditionnel ?


D'une part, ce n'est pas une caractéristique normalisée en C et, par conséquent, ce n'est pas portable. (Oui, nous connaissons la bibliothèque `GC Boehm'. Elle contient du code assembleur pour la plupart des plateformes classiques, mais pas toutes, et bien qu'elle soit le plus souvent transparente, elle ne l'est pas complètement ; des correctifs sont nécessaires afin que Python fonctionne correctement avec.)

Traditional GC also becomes a problem when Python is embedded into other
applications.  While in a standalone Python it's fine to replace the standard
@code{malloc()} and @code{free()} with versions provided by the GC library, an application
embedding Python may want to have its `own' substitute for @code{malloc()} and @code{free()},
and may not want Python's.  Right now, CPython works with anything that
implements @code{malloc()} and @code{free()} properly.

@node Pourquoi toute la mémoire n'est pas libérée lorsque CPython s'arrête ?,Pourquoi les n-uplets et les list sont deux types de données séparés ?,Pourquoi CPython n'utilise-t-il pas un modèle de ramasse-miettes plus traditionnel ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-isn-t-all-memory-freed-when-cpython-exits}@anchor{4fc4}
@subsection Pourquoi toute la mémoire n'est pas libérée lorsque `CPython' s'arrête ?


Les objets référencés depuis les espaces de nommage globaux des modules Python ne sont pas toujours désalloués lorsque Python s'arrête. Cela peut se produire s'il y a des références circulaires. Il y a aussi certaines parties de mémoire qui sont allouées par la bibliothèque C qui sont impossibles à libérer (par exemple un outil comme `Purify' s'en plaindra). Python est, cependant, agressif sur le nettoyage de la mémoire en quittant et cherche à détruire chaque objet.

Si vous voulez forcer Python à désallouer certains objets en quittant, utilisez le module @ref{c,,atexit} pour exécuter une fonction qui va forcer ces destructions.

@node Pourquoi les n-uplets et les list sont deux types de données séparés ?,Comment les listes sont-elles implémentées dans CPython ?,Pourquoi toute la mémoire n'est pas libérée lorsque CPython s'arrête ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-are-there-separate-tuple-and-list-data-types}@anchor{4fc5}
@subsection Pourquoi les `n'-uplets et les `list' sont deux types de données séparés ?


Lists and tuples, while similar in many respects, are generally used in
fundamentally different ways.  Tuples can be thought of as being similar to
Pascal @code{records} or C @code{structs}; they're small collections of related data which may
be of different types which are operated on as a group.  For example, a
Cartesian coordinate is appropriately represented as a tuple of two or three
numbers.

Lists, on the other hand, are more like arrays in other languages.  They tend to
hold a varying number of objects all of which have the same type and which are
operated on one-by-one.  For example, @ref{10da,,os.listdir('.')}
returns a list of
strings representing the files in the current directory.  Functions which
operate on this output would generally not break if you added another file or
two to the directory.

Les `n'-uplets sont immuables, ce qui signifie que lorsqu'un `n'-uplet a été créé, vous ne pouvez remplacer aucun de ses éléments par une nouvelle valeur. Les listes sont mutables, ce qui signifie que vous pouvez toujours modifier les éléments d'une liste. Seuls des éléments immuables peuvent être utilisés comme clés de dictionnaires, et donc de @code{tuple} et @code{list} seul des `n'-uplets peuvent être utilisés comme clés.

@node Comment les listes sont-elles implémentées dans CPython ?,Comment les dictionnaires sont-ils implémentés dans CPython ?,Pourquoi les n-uplets et les list sont deux types de données séparés ?,FAQ sur l'histoire et la conception
@anchor{faq/design how-are-lists-implemented-in-cpython}@anchor{4fc6}
@subsection Comment les listes sont-elles implémentées dans CPython ?


Les listes en CPython sont de vrais tableaux de longueur variable contrairement à des listes orientées `Lisp' (c.-à-d. des listes chaînées). L'implémentation utilise un tableau contigu de références à d'autres objets. Elle conserve également un pointeur vers ce tableau et la longueur du tableau dans une structure de tête de liste.

Cela rend l'indexation d'une liste @code{a[i]} une opération dont le coût est indépendant de la taille de la liste ou de la valeur de l'indice.

Lorsque des éléments sont ajoutés ou insérés, le tableau de références est redimensionné. Un savoir-faire ingénieux permet l'amélioration des performances lors de l'ajout fréquent d'éléments ; lorsque le tableau doit être étendu, un certain espace supplémentaire est alloué de sorte que pour la prochaine fois, ceci ne nécessite plus un redimensionnement effectif.

@node Comment les dictionnaires sont-ils implémentés dans CPython ?,Pourquoi les clés du dictionnaire sont immuables ?,Comment les listes sont-elles implémentées dans CPython ?,FAQ sur l'histoire et la conception
@anchor{faq/design how-are-dictionaries-implemented-in-cpython}@anchor{4fc7}
@subsection Comment les dictionnaires sont-ils implémentés dans CPython ?


Les dictionnaires CPython sont implémentés sous forme de tables de hachage redimensionnables.  Par rapport aux `B-trees', cela donne de meilleures performances pour la recherche (l'opération la plus courante de loin) dans la plupart des circonstances, et leur implémentation est plus simple.

Dictionaries work by computing a hash code for each key stored in the dictionary
using the @ref{5d5,,hash()} built-in function.  The hash code varies widely depending
on the key and a per-process seed; for example, @code{'Python'} could hash to
@code{-539294296} while @code{'python'}, a string that differs by a single bit, could hash
to @code{1142331976}.  The hash code is then used to calculate a location in an
internal array where the value will be stored.  Assuming that you're storing
keys that all have different hash values, this means that dictionaries take
constant time -- `O'(1), in Big-O notation -- to retrieve a key.

@node Pourquoi les clés du dictionnaire sont immuables ?,Pourquoi list sort ne renvoie pas la liste triée ?,Comment les dictionnaires sont-ils implémentés dans CPython ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-must-dictionary-keys-be-immutable}@anchor{4fc8}
@subsection Pourquoi les clés du dictionnaire sont immuables ?


L'implémentation de la table de hachage des dictionnaires utilise une valeur de hachage calculée à partir de la valeur de la clé pour trouver la clé elle-même.  Si la clé était un objet mutable, sa valeur peut changer, et donc son hachage pourrait également changer.  Mais toute personne modifiant l'objet clé ne peut pas dire qu'elle a été utilisée comme une clé de dictionnaire. Il ne peut déplacer l'entrée dans le dictionnaire.  Ainsi, lorsque vous essayez de rechercher le même objet dans le dictionnaire, il ne sera pas disponible parce que sa valeur de hachage est différente. Si vous essayez de chercher l'ancienne valeur, elle serait également introuvable car la valeur de l'objet trouvé dans cet emplacement de hachage serait différente.

Si vous voulez un dictionnaire indexé avec une liste, il faut simplement convertir la liste en un `n'-uplet ; la fonction @code{tuple(L)} crée un `n'-uplet avec les mêmes entrées que la liste @code{L}. Les `n'-uplets sont immuables et peuvent donc être utilisés comme clés du dictionnaire.

Certaines solutions insatisfaisantes ont été proposées :


@itemize -

@item 
Hacher les listes par leur adresse (`ID' de l'objet). Cela ne fonctionne pas parce que si vous créez une nouvelle liste avec la même valeur, elle ne sera pas retrouvée ; par exemple :

@example
mydict = @{[1, 2]: '12'@}
print(mydict[[1, 2]])
@end example

lèverait une exception @ref{33a,,KeyError} car l'ID de @code{[1, 2]} utilisé dans la deuxième ligne diffère de celui de la première ligne. En d'autres termes, les clés de dictionnaire doivent être comparées à l'aide du comparateur @code{==} et non à l'aide du mot clé @ref{2e9,,is}.

@item 
Faire une copie lors de l'utilisation d'une liste en tant que clé.  Cela ne fonctionne pas puisque la liste, étant un objet mutable, pourrait contenir une référence à elle-même ou avoir une boucle infinie au niveau du code copié.

@item 
Autoriser les listes en tant que clés, mais indiquer à l'utilisateur de ne pas les modifier. Cela permettrait un ensemble de bogues difficiles à suivre dans les programmes lorsque vous avez oublié ou modifié une liste par accident. Cela casse également un impératif important des dictionnaires : chaque valeur de @code{d.keys()} est utilisable comme clé du dictionnaire.

@item 
Marquer les listes comme étant en lecture seule une fois qu'elles sont utilisées comme clé de dictionnaire. Le problème est que ce n'est pas seulement l'objet de niveau supérieur qui pourrait changer sa valeur ; vous pourriez utiliser un `n'-uplet contenant une liste comme clé. Utiliser n'importe quoi comme une clé dans un dictionnaire nécessiterait de marquer tous les objets accessibles à partir de là comme en lecture seule — et encore une fois, les objets se faisant référence pourraient provoquer une boucle infinie.
@end itemize

There is a trick to get around this if you need to, but use it at your own risk:
You can wrap a mutable structure inside a class instance which has both a
@ref{ae8,,__eq__()} and a @ref{ae9,,__hash__()} method.
You must then make sure that the
hash value for all such wrapper objects that reside in a dictionary (or other
hash based structure), remain fixed while the object is in the dictionary (or
other structure).

@example
class ListWrapper:
    def __init__(self, the_list):
        self.the_list = the_list

    def __eq__(self, other):
        return self.the_list == other.the_list

    def __hash__(self):
        l = self.the_list
        result = 98767 - len(l)*555
        for i, el in enumerate(l):
            try:
                result = result + (hash(el) % 9999999) * 1001 + i
            except Exception:
                result = (result % 7777777) + i * 333
        return result
@end example

Notez que le calcul de hachage peut être compliqué car il est possible que certains membres de la liste soient impossibles à hacher et aussi par la possibilité de débordement arithmétique.

De plus, il faut toujours que, si @code{o1 == o2} (par exemple @code{o1.__eq__(o2) vaut True}) alors @code{hash(o1) == hash(o2)} (par exemple, @code{o1.__hash__() == o2.__hash__()}), que l’objet se trouve dans un dictionnaire ou pas. Si vous ne remplissez pas ces conditions, les dictionnaires et autres structures basées sur le hachage se comporteront mal.

In the case of @code{ListWrapper}, whenever the wrapper object is in a dictionary the
wrapped list must not change to avoid anomalies.  Don't do this unless you are
prepared to think hard about the requirements and the consequences of not
meeting them correctly.  Consider yourself warned.

@node Pourquoi list sort ne renvoie pas la liste triée ?,Comment spécifier une interface et appliquer une spécification d’interface en Python ?,Pourquoi les clés du dictionnaire sont immuables ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-doesn-t-list-sort-return-the-sorted-list}@anchor{4fc9}
@subsection Pourquoi @code{list.sort()} ne renvoie pas la liste triée ?


Dans les situations où la performance est importante, faire une copie de la liste juste pour la classer serait un gaspillage. Par conséquent, @ref{bbd,,list.sort()} classe la liste en place. Afin de vous le rappeler, elle ne renvoie pas la liste classée. De cette façon, vous ne serez pas dupés en écrasant accidentellement une liste lorsque vous avez besoin d’une copie triée tout en gardant sous la main la version non triée.

Si vous souhaitez qu'une nouvelle liste soit renvoyée, utilisez plutôt la fonction native @ref{bbc,,sorted()}.  Cette fonction crée une nouvelle liste à partir d’un itérable fourni, la classe et la renvoie. Par exemple, voici comment itérer dans l’ordre sur les clés d’un dictionnaire :

@example
for key in sorted(mydict):
    ...  # do whatever with mydict[key]...
@end example

@node Comment spécifier une interface et appliquer une spécification d’interface en Python ?,Pourquoi n'y a-t-il pas de goto en Python ?,Pourquoi list sort ne renvoie pas la liste triée ?,FAQ sur l'histoire et la conception
@anchor{faq/design how-do-you-specify-and-enforce-an-interface-spec-in-python}@anchor{4fca}
@subsection Comment spécifier une interface et appliquer une spécification d’interface en Python ?


Une spécification d'interface pour un module fourni par des langages tels que C++ et Java décrit les prototypes pour les méthodes et les fonctions du module. Beaucoup estiment que la vérification au moment de la compilation des spécifications d'interface facilite la construction de grands programmes.

Python 2.6 ajoute un module @ref{4,,abc} qui vous permet de définir des classes mères abstraites (ABC pour `abstract base classes' en anglais). Vous pouvez ensuite utiliser @ref{42b,,isinstance()} et @ref{7ab,,issubclass()} pour vérifier si une instance ou une classe implémente une ABC particulière. Le module @ref{1e,,collections.abc} définit un ensemble d'ABC utiles telles que @ref{21d6,,Iterable}, @ref{21d8,,Container} et @ref{1090,,collections.abc.MutableMapping}.

Pour Python, la plupart des avantages des spécifications d'interface peuvent être obtenus par une discipline de test appropriée pour les composants.

Une bonne suite de tests pour un module peut à la fois fournir un test de non-régression et servir de spécification d'interface de module ainsi qu'un ensemble d'exemples. De nombreux modules Python peuvent être exécutés en tant que script pour fournir un simple « auto-test ». Même les modules qui utilisent des interfaces externes complexes peuvent souvent être testés isolément à l'aide d'émulations triviales embryonnaires de l'interface externe. Les modules @ref{3a,,doctest} et @code{UnitTest} ou des cadriciels de test tiers peuvent être utilisés pour construire des suites de tests exhaustives qui éprouvent chaque ligne de code dans un module.

An appropriate testing discipline can help build large complex applications in
Python as well as having interface specifications would.  In fact, it can be
better because an interface specification cannot test certain properties of a
program.  For example, the @code{list.append()} method is expected to add new elements
to the end of some internal list; an interface specification cannot test that
your @code{list.append()} implementation will actually do this correctly, but it's
trivial to check this property in a test suite.

L'écriture des suites de tests est très utile, et vous voudrez peut-être concevoir votre code de manière à le rendre facilement testable. Une technique de plus en plus populaire, le développement dirigé par les tests, requiert d'écrire d'abord des éléments de la suite de tests, avant d'écrire le code réel. Bien sûr, Python vous permet d'être laxiste et de ne pas écrire de test du tout.

@node Pourquoi n'y a-t-il pas de goto en Python ?,Pourquoi les chaînes de caractères brutes r-strings ne peuvent-elles pas se terminer par un backslash ?,Comment spécifier une interface et appliquer une spécification d’interface en Python ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-is-there-no-goto}@anchor{4fcb}
@subsection Pourquoi n'y a-t-il pas de @code{goto} en Python ?


In the 1970s people realized that unrestricted goto could lead
to messy "spaghetti" code that was hard to understand and revise.
In a high-level language, it is also unneeded as long as there
are ways to branch (in Python, with @ref{2e7,,if} statements and @ref{2ea,,or},
@ref{2e5,,and}, and @ref{2e7,,if}/@ref{18a,,else} expressions) and loop (with @ref{1b92,,while}
and @ref{2e6,,for} statements, possibly containing @ref{9b7,,continue} and @ref{a97,,break}).

One can also use exceptions to provide a "structured goto"
that works even across
function calls.  Many feel that exceptions can conveniently emulate all
reasonable uses of the @code{go} or @code{goto} constructs of C, Fortran, and other
languages.  For example:

@example
class label(Exception): pass  # declare a label

try:
    ...
    if condition: raise label()  # goto label
    ...
except label:  # where to goto
    pass
...
@end example

This doesn't allow you to jump into the middle of a loop, but that's usually
considered an abuse of @code{goto} anyway.  Use sparingly.

@node Pourquoi les chaînes de caractères brutes r-strings ne peuvent-elles pas se terminer par un backslash ?,Pourquoi la déclaration with pour les assignations d'attributs n'existe pas en Python ?,Pourquoi n'y a-t-il pas de goto en Python ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-can-t-raw-strings-r-strings-end-with-a-backslash}@anchor{4fcc}
@subsection Pourquoi les chaînes de caractères brutes (r-strings) ne peuvent-elles pas se terminer par un `backslash' ?


Plus précisément, elles ne peuvent pas se terminer par un nombre impair de `backslashes' : le `backslash' non appairé à la fin échappe le caractère de guillemet final, laissant la chaîne non terminée.

Les chaînes brutes ont été conçues pour faciliter la création de données pour les processeurs de texte (principalement les moteurs d'expressions régulières) qui veulent faire leur propre traitement d'échappement d'`antislashes'. Ces processeurs considèrent un `antislash' de fin non-appairé comme une erreur, alors les chaînes brutes ne le permettent pas. En retour, elles vous permettent de transmettre le caractère de citation de la chaîne en l'échappant avec un `antislash'. Ces règles fonctionnent bien lorsque les chaînes brutes sont utilisées pour leur but premier.

Si vous essayez de construire des chemins d'accès Windows, notez que tous les appels système Windows acceptent également les `slashes' « classiques » :

@example
f = open("/mydir/file.txt")  # works fine!
@end example

Si vous essayez de construire un chemin d'accès pour une commande DOS, essayez par exemple l'un de ceux-ci

@example
dir = r"\this\is\my\dos\dir" "\\"
dir = r"\this\is\my\dos\dir\ "[:-1]
dir = "\\this\\is\\my\\dos\\dir\\"
@end example

@node Pourquoi la déclaration with pour les assignations d'attributs n'existe pas en Python ?,Pourquoi l'instruction with ne prend-elle pas en charge les générateurs ?,Pourquoi les chaînes de caractères brutes r-strings ne peuvent-elles pas se terminer par un backslash ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-doesn-t-python-have-a-with-statement-for-attribute-assignments}@anchor{4fcd}
@subsection Pourquoi la déclaration @code{with} pour les assignations d'attributs n'existe pas en Python ?


Python has a @ref{5bc,,with} statement that wraps the execution of a block, calling code
on the entrance and exit from the block.  Some languages have a construct that
looks like this:

@example
with obj:
    a = 1               # equivalent to obj.a = 1
    total = total + 1   # obj.total = obj.total + 1
@end example

En Python, une telle construction serait ambiguë.

Les autres langages, tels que Pascal, Delphi et C++ utilisent des types statiques, il est donc possible de savoir d'une manière claire et directe ce à quoi est attribué un membre. C'est le point principal du typage statique — le compilateur connaît `toujours' la portée de toutes les variables au moment de la compilation.

Python utilise le typage dynamique. Il est impossible de savoir à l'avance quel attribut sera référencé lors de l'exécution. Les attributs membres peuvent être ajoutés ou retirés des objets à la volée. Il est donc impossible de savoir, d'une simple lecture, quel attribut est référencé : s'il est local, global ou un attribut membre ?

Prenons par exemple l'extrait incomplet suivant :

@example
def foo(a):
    with a:
        print(x)
@end example

The snippet assumes that @code{a} must have a member attribute called @code{x}. However,
there is nothing in Python that tells the interpreter this. What should happen
if @code{a} is, let us say, an integer?  If there is a global variable named @code{x},
will it be used inside the @ref{5bc,,with} block?  As you see, the dynamic nature of Python
makes such choices much harder.

The primary benefit of @ref{5bc,,with} and similar language features (reduction of code
volume) can, however, easily be achieved in Python by assignment.  Instead of:

@example
function(args).mydict[index][index].a = 21
function(args).mydict[index][index].b = 42
function(args).mydict[index][index].c = 63
@end example

écrivez ceci :

@example
ref = function(args).mydict[index][index]
ref.a = 21
ref.b = 42
ref.c = 63
@end example

Cela a également pour effet secondaire d'augmenter la vitesse d'exécution car les liaisons de noms sont résolues au moment de l'exécution en Python, et la deuxième version n'a besoin d'exécuter la résolution qu'une seule fois.

Similar proposals that would introduce syntax to further reduce code volume,
such as using a 'leading dot', have been rejected in favour of explicitness (see
@indicateurl{https://mail.python.org/pipermail/python-ideas/2016-May/040070.html}).

@node Pourquoi l'instruction with ne prend-elle pas en charge les générateurs ?,Pourquoi les deux-points sont-ils nécessaires pour les déclarations if/while/def/class ?,Pourquoi la déclaration with pour les assignations d'attributs n'existe pas en Python ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-don-t-generators-support-the-with-statement}@anchor{4fce}
@subsection Pourquoi l'instruction @code{with} ne prend-elle pas en charge les générateurs ?


For technical reasons, a generator used directly as a context manager
would not work correctly.  When, as is most common, a generator is used as
an iterator run to completion, no closing is needed.  When it is, wrap
it as @ref{28c6,,contextlib.closing(generator)}
in the @ref{5bc,,with} statement.

@node Pourquoi les deux-points sont-ils nécessaires pour les déclarations if/while/def/class ?,Pourquoi Python permet-il les virgules à la fin des listes et des n-uplets ?,Pourquoi l'instruction with ne prend-elle pas en charge les générateurs ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-are-colons-required-for-the-if-while-def-class-statements}@anchor{4fcf}
@subsection Pourquoi les deux-points sont-ils nécessaires pour les déclarations @code{if/while/def/class} ?


Le deux-points est principalement nécessaire pour améliorer la lisibilité (l'un des résultats du langage expérimental ABC).  Considérez ceci :

@example
if a == b
    print(a)
@end example

et cela

@example
if a == b:
    print(a)
@end example

Remarquez comment le deuxième est un peu plus facile à lire.  Remarquez aussi comment un deux-points introduit l'exemple dans cette réponse à la FAQ ; c'est un usage standard en français (et en anglais).

Une autre raison mineure est que les deux-points facilitent la tâche des éditeurs avec coloration syntaxique ; ils peuvent rechercher les deux-points pour décider quand l'indentation doit être augmentée au lieu d'avoir à faire une analyse plus élaborée du texte du programme.

@node Pourquoi Python permet-il les virgules à la fin des listes et des n-uplets ?,,Pourquoi les deux-points sont-ils nécessaires pour les déclarations if/while/def/class ?,FAQ sur l'histoire et la conception
@anchor{faq/design why-does-python-allow-commas-at-the-end-of-lists-and-tuples}@anchor{4fd0}
@subsection Pourquoi Python permet-il les virgules à la fin des listes et des `n'-uplets ?


Python vous permet d'ajouter une virgule à la fin des listes, des `n'-uplets et des dictionnaires :

@example
[1, 2, 3,]
('a', 'b', 'c',)
d = @{
    "A": [1, 5],
    "B": [6, 7],  # last trailing comma is optional but good style
@}
@end example

Il y a plusieurs raisons d'accepter cela.

Lorsque vous avez une valeur littérale pour une liste, un `n'-uplet ou un dictionnaire réparti sur plusieurs lignes, il est plus facile d'ajouter plus d'éléments parce que vous n'avez pas besoin de vous rappeler d'ajouter une virgule à la ligne précédente.  Les lignes peuvent aussi être réorganisées sans créer une erreur de syntaxe.

L'omission accidentelle de la virgule peut entraîner des erreurs difficiles à diagnostiquer, par exemple :

@example
x = [
  "fee",
  "fie"
  "foo",
  "fum"
]
@end example

Cette liste a l'air d'avoir quatre éléments, mais elle en contient en fait trois : "`fee'", "`fiefoo'" et "`fum'". Toujours ajouter la virgule permet d'éviter cette source d'erreur.

Permettre la virgule de fin peut également faciliter la génération de code.

@node FAQ sur la bibliothèque et les extensions,FAQ extension/intégration,FAQ sur l'histoire et la conception,Questions fréquemment posées sur Python
@anchor{faq/library doc}@anchor{4fd1}@anchor{faq/library library-and-extension-faq}@anchor{4fd2}
@section FAQ sur la bibliothèque et les extensions



@menu
* Questions générales sur la bibliothèque:: 
* Tâches fréquentes:: 
* Fils d'exécution: Fils d'exécution<4>. 
* Les entrées/sorties: Les entrées/sorties<2>. 
* Programmation réseau et Internet:: 
* Bases de données:: 
* Mathématiques et calcul numérique:: 

@end menu

@node Questions générales sur la bibliothèque,Tâches fréquentes,,FAQ sur la bibliothèque et les extensions
@anchor{faq/library general-library-questions}@anchor{4fd3}
@subsection Questions générales sur la bibliothèque


@menu
* Comment trouver un module ou une application pour effectuer la tâche X ?:: 
* Où sont stockés les fichiers sources math.py@comma{} socket.py@comma{} regex.py@comma{} etc ?: Où sont stockés les fichiers sources math py socket py regex py etc ?. 
* Comment rendre un script Python exécutable sous Unix ?:: 
* Existe-t-il un module curses ou termcap en Python ?:: 
* Existe-t-il un équivalent à la fonction C onexit() en Python ?: Existe-t-il un équivalent à la fonction C onexit en Python ?. 
* Pourquoi mes gestionnaires de signaux ne fonctionnent-ils pas ?:: 

@end menu

@node Comment trouver un module ou une application pour effectuer la tâche X ?,Où sont stockés les fichiers sources math py socket py regex py etc ?,,Questions générales sur la bibliothèque
@anchor{faq/library how-do-i-find-a-module-or-application-to-perform-task-x}@anchor{4fd4}
@subsubsection Comment trouver un module ou une application pour effectuer la tâche X ?


Regardez si la @ref{143,,bibliothèque standard} contient un module approprié (avec l'expérience, vous connaîtrez le contenu de la bibliothèque standard et pourrez sauter cette étape).

Pour des paquets tiers, regardez dans l'index des paquets Python@footnote{https://pypi.org} ou essayez Google@footnote{https://www.google.com} ou un autre moteur de recherche (NDT : comme le moteur français Qwant@footnote{https://www.qwant.com}). Rechercher « Python » accompagné d'un ou deux mots-clés se rapportant à ce qui vous intéresse donne souvent de bons résultats.

@node Où sont stockés les fichiers sources math py socket py regex py etc ?,Comment rendre un script Python exécutable sous Unix ?,Comment trouver un module ou une application pour effectuer la tâche X ?,Questions générales sur la bibliothèque
@anchor{faq/library where-is-the-math-py-socket-py-regex-py-etc-source-file}@anchor{4fd5}
@subsubsection Où sont stockés les fichiers sources `math.py', `socket.py', `regex.py', etc ?


Si vous ne parvenez pas à trouver le fichier source d'un module, c'est peut-être parce que celui-ci est un module natif ou bien un module implémenté en C, C++, ou autre langage compilé, qui est chargé dynamiquement. Dans ce cas, vous ne possédez peut-être pas le fichier source ou celui-ci est en réalité stocké quelque part dans un dossier de fichiers source C (qui ne sera pas dans le chemin Python), comme par exemple @code{mathmodule.c}.

Il y a (au moins) trois types de modules dans Python :


@enumerate 

@item 
les modules écrits en Python (`.py') ;

@item 
les modules écrits en C et chargés dynamiquement (`.dll', `.pyd', `.so', `.sl', `etc.') ;

@item 
les modules écrits en C et liés à l'interpréteur ; pour obtenir leur liste, entrez :

@example
import sys
print(sys.builtin_module_names)
@end example
@end enumerate

@node Comment rendre un script Python exécutable sous Unix ?,Existe-t-il un module curses ou termcap en Python ?,Où sont stockés les fichiers sources math py socket py regex py etc ?,Questions générales sur la bibliothèque
@anchor{faq/library how-do-i-make-a-python-script-executable-on-unix}@anchor{4fd6}
@subsubsection Comment rendre un script Python exécutable sous Unix ?


Deux conditions doivent être remplies : les droits d'accès au fichier doivent permettre son exécution et la première ligne du script doit commencer par @code{#!} suivi du chemin vers l'interpréteur Python.

La première condition est remplie en exécutant  @code{chmod +x scriptfile} ou @code{chmod 755 scriptfile}.

Il y a plusieurs façons de remplir la seconde. La plus simple consiste à écrire au tout début du fichier

@example
#!/usr/local/bin/python
@end example

en utilisant le chemin de l'interpréteur Python sur votre machine.

Pour rendre ce script indépendant de la localisation de l'interpréteur Python, il faut utiliser le programme @code{env}. La ligne ci-dessous fonctionne sur la quasi-totalité des dérivés de Unix, à condition que l'interpréteur Python soit dans un dossier référencé dans la variable 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} de l'utilisateur :

@example
#!/usr/bin/env python
@end example

Ne faites `pas' ceci pour des scripts CGI. La variable 
@geindex PATH
@geindex variable d'environnement; PATH
@code{PATH} des scripts CGI est souvent très succincte, il faut par conséquent préciser le chemin absolu réel de l'interpréteur.

Il peut arriver que l'environnement d'un utilisateur soit si chargé que le programme @code{/usr/bin/env} échoue ; ou que le programme `env' n'existe pas du tout. Dans ce cas, vous pouvez utiliser l'astuce suivante, élaborée par Alex Rezinsky :

@example
#! /bin/sh
""":"
exec python $0 $@{1+"$@@"@}
"""
@end example

Le léger inconvénient est que cela définit la variable `__doc__' du script. Cependant, il est possible de corriger cela en ajoutant

@example
__doc__ = """...Whatever..."""
@end example

@node Existe-t-il un module curses ou termcap en Python ?,Existe-t-il un équivalent à la fonction C onexit en Python ?,Comment rendre un script Python exécutable sous Unix ?,Questions générales sur la bibliothèque
@anchor{faq/library is-there-a-curses-termcap-package-for-python}@anchor{4fd7}
@subsubsection Existe-t-il un module `curses' ou `termcap' en Python ?


@c XXX curses *is* built by default, isn't it?

Pour les dérivés d'Unix : la distribution standard de Python contient un module `curses' dans le sous-dossier Modules@footnote{https://github.com/python/cpython/tree/3.13/Modules}, bien qu'il ne soit pas compilé par défaut. Il n'est pas disponible en Windows — le module `curses' n'existant pas en Windows.

Le module @ref{2b,,curses} comprend les fonctionnalités de base de `curses' et beaucoup de fonctionnalités supplémentaires provenant de `ncurses' et de `SYSV curses' comme la couleur, la gestion des ensembles de caractères alternatifs, la prise en charge du pavé tactile et de la souris. Cela implique que le module n'est pas compatible avec des systèmes d'exploitation qui n'ont que le `curses' de BSD mais, de nos jours, de tels systèmes d'exploitation ne semblent plus exister ou être maintenus.

@node Existe-t-il un équivalent à la fonction C onexit en Python ?,Pourquoi mes gestionnaires de signaux ne fonctionnent-ils pas ?,Existe-t-il un module curses ou termcap en Python ?,Questions générales sur la bibliothèque
@anchor{faq/library is-there-an-equivalent-to-c-s-onexit-in-python}@anchor{4fd8}
@subsubsection Existe-t-il un équivalent à la fonction C @code{onexit()} en Python ?


The @ref{c,,atexit} module provides a register function that is similar to C's
@code{onexit()}.

@node Pourquoi mes gestionnaires de signaux ne fonctionnent-ils pas ?,,Existe-t-il un équivalent à la fonction C onexit en Python ?,Questions générales sur la bibliothèque
@anchor{faq/library why-don-t-my-signal-handlers-work}@anchor{4fd9}
@subsubsection Pourquoi mes gestionnaires de signaux ne fonctionnent-ils pas ?


Le problème le plus courant est d'appeler le gestionnaire de signaux avec les mauvais arguments. Un gestionnaire est appelé de la façon suivante

@example
handler(signum, frame)
@end example

donc il doit être déclaré avec deux paramètres :

@example
def handler(signum, frame):
    ...
@end example

@node Tâches fréquentes,Fils d'exécution<4>,Questions générales sur la bibliothèque,FAQ sur la bibliothèque et les extensions
@anchor{faq/library common-tasks}@anchor{4fda}
@subsection Tâches fréquentes


@menu
* Comment tester un programme ou un composant Python ?:: 
* Comment générer la documentation à partir des docstrings ?:: 
* Comment détecter qu'une touche est pressée ?:: 

@end menu

@node Comment tester un programme ou un composant Python ?,Comment générer la documentation à partir des docstrings ?,,Tâches fréquentes
@anchor{faq/library how-do-i-test-a-python-program-or-component}@anchor{4fdb}
@subsubsection Comment tester un programme ou un composant Python ?


Python fournit deux cadriciels de test. Le module @ref{3a,,doctest} cherche des exemples dans les `docstrings' d'un module et les exécute. Il compare alors la sortie avec la sortie attendue, telle que définie dans la `docstring'.

Le module @ref{105,,unittest} est un cadriciel un peu plus élaboré basé sur les cadriciels de test de Java et de Smalltalk.

Pour rendre le test plus aisé, il est nécessaire de bien découper le code d'un programme. Votre programme doit avoir la quasi-totalité des fonctionnalités dans des fonctions ou des classes — et ceci a parfois l'avantage aussi plaisant qu'inattendu de rendre le programme plus rapide, les accès aux variables locales étant en effet plus rapides que les accès aux variables globales. De plus le programme doit éviter au maximum de manipuler des variables globales, car ceci rend le test beaucoup plus difficile.

La « logique générale » d'un programme devrait être aussi simple que

@example
if __name__ == "__main__":
    main_logic()
@end example

à la fin du module principal du programme.

Une fois que la logique du programme est implémentée par un ensemble de fonctions et de comportements de classes, il faut écrire des fonctions de test qui vont éprouver cette logique. À chaque module, il est possible d'associer une suite de tests qui joue de manière automatique un ensemble de tests. Au premier abord, il semble qu'il faille fournir un effort conséquent, mais comme Python est un langage concis et flexible, c'est surprenamment aisé. Écrire simultanément le code « de production » et les fonctions de test associées rend le développement plus agréable et plus amusant, car ceci permet de trouver des bogues, voire des défauts de conception, plus facilement.

Les « modules auxiliaires » qui n'ont pas vocation à être le module principal du programme peuvent inclure un test pour se vérifier eux-mêmes.

@example
if __name__ == "__main__":
    self_test()
@end example

Les programmes qui interagissent avec des interfaces externes complexes peuvent être testés même quand ces interfaces ne sont pas disponibles, en utilisant des interfaces « simulacres » implémentées en Python.

@node Comment générer la documentation à partir des docstrings ?,Comment détecter qu'une touche est pressée ?,Comment tester un programme ou un composant Python ?,Tâches fréquentes
@anchor{faq/library how-do-i-create-documentation-from-doc-strings}@anchor{4fdc}
@subsubsection Comment générer la documentation à partir des `docstrings' ?


Le module @ref{b4,,pydoc} peut générer du HTML à partir des `docstrings' du code source Python. Il est aussi possible de documenter une API uniquement à partir des `docstrings' à l'aide de epydoc@footnote{https://epydoc.sourceforge.net/}.  Sphinx@footnote{https://sphinx-doc.org} peut également inclure du contenu provenant de `docstrings'.

@node Comment détecter qu'une touche est pressée ?,,Comment générer la documentation à partir des docstrings ?,Tâches fréquentes
@anchor{faq/library how-do-i-get-a-single-keypress-at-a-time}@anchor{4fdd}
@subsubsection Comment détecter qu'une touche est pressée ?


Pour les dérivés d'Unix, plusieurs solutions s'offrent à vous. C'est facile en utilisant le module `curses', mais `curses' est un module assez conséquent à apprendre.

@c XXX this doesn't work out of the box, some IO expert needs to check why
@c 
@c Here's a solution without curses::
@c 
@c import termios, fcntl, sys, os
@c fd = sys.stdin.fileno()
@c 
@c oldterm = termios.tcgetattr(fd)
@c newattr = termios.tcgetattr(fd)
@c newattr[3] = newattr[3] & ~termios.ICANON & ~termios.ECHO
@c termios.tcsetattr(fd, termios.TCSANOW, newattr)
@c 
@c oldflags = fcntl.fcntl(fd, fcntl.F_GETFL)
@c fcntl.fcntl(fd, fcntl.F_SETFL, oldflags | os.O_NONBLOCK)
@c 
@c try:
@c     while True:
@c         try:
@c             c = sys.stdin.read(1)
@c             print("Got character", repr(c))
@c         except OSError:
@c             pass
@c finally:
@c     termios.tcsetattr(fd, termios.TCSAFLUSH, oldterm)
@c     fcntl.fcntl(fd, fcntl.F_SETFL, oldflags)
@c 
@c You need the :mod:`termios` and the :mod:`fcntl` module for any of this to
@c work, and I've only tried it on Linux, though it should work elsewhere.  In
@c this code, characters are read and printed one at a time.
@c 
@c :func:`termios.tcsetattr` turns off stdin's echoing and disables canonical
@c mode.  :func:`fcntl.fnctl` is used to obtain stdin's file descriptor flags
@c and modify them for non-blocking mode.  Since reading stdin when it is empty
@c results in an :exc:`OSError`, this error is caught and ignored.
@c 
@c .. versionchanged:: 3.3
@c    *sys.stdin.read* used to raise :exc:`IOError`. Starting from Python 3.3
@c    :exc:`IOError` is alias for :exc:`OSError`.

@node Fils d'exécution<4>,Les entrées/sorties<2>,Tâches fréquentes,FAQ sur la bibliothèque et les extensions
@anchor{faq/library threads}@anchor{4fde}
@subsection Fils d'exécution


@menu
* Comment programmer avec des fils d'exécution ?:: 
* Aucun de mes fils ne semble s'exécuter ; pourquoi ?: Aucun de mes fils ne semble s'exécuter pourquoi ?. 
* Comment découper et répartir une tâche au sein d'un ensemble de fils d'exécutions ?:: 
* Quels types de mutations sur des variables globales sont compatibles avec les programmes à fils d'exécution multiples ? sécurisé ?:: 
* Pourquoi ne pas se débarrasser du verrou global de l'interpréteur ?:: 

@end menu

@node Comment programmer avec des fils d'exécution ?,Aucun de mes fils ne semble s'exécuter pourquoi ?,,Fils d'exécution<4>
@anchor{faq/library how-do-i-program-using-threads}@anchor{4fdf}
@subsubsection Comment programmer avec des fils d'exécution ?


Veillez à bien utiliser le module @ref{ec,,threading} et non le module @ref{2,,_thread}. Le module @ref{ec,,threading} fournit une abstraction plus facile à manipuler que les primitives de bas-niveau du module @ref{2,,_thread}.

@node Aucun de mes fils ne semble s'exécuter pourquoi ?,Comment découper et répartir une tâche au sein d'un ensemble de fils d'exécutions ?,Comment programmer avec des fils d'exécution ?,Fils d'exécution<4>
@anchor{faq/library none-of-my-threads-seem-to-run-why}@anchor{4fe0}
@subsubsection Aucun de mes fils ne semble s'exécuter : pourquoi ?


Dès que le fil d'exécution principal se termine, tous les fils sont tués. Le fil principal s'exécute trop rapidement, sans laisser le temps aux autres fils de faire quoi que ce soit.

Une correction simple consiste à ajouter un temps d'attente suffisamment long à la fin du programme pour que tous les fils puissent se terminer :

@example
import threading, time

def thread_task(name, n):
    for i in range(n):
        print(name, i)

for i in range(10):
    T = threading.Thread(target=thread_task, args=(str(i), i))
    T.start()

time.sleep(10)  # <---------------------------!
@end example

Mais à présent, sur beaucoup de plates-formes, les fils ne s'exécutent pas en parallèle, mais semblent s'exécuter de manière séquentielle, l'un après l'autre ! En réalité, l'ordonnanceur de fils du système d'exploitation ne démarre pas de nouveau fil avant que le précédent ne soit bloqué.

Une correction simple consiste à ajouter un petit temps d'attente au début de la fonction :

@example
def thread_task(name, n):
    time.sleep(0.001)  # <--------------------!
    for i in range(n):
        print(name, i)

for i in range(10):
    T = threading.Thread(target=thread_task, args=(str(i), i))
    T.start()

time.sleep(10)
@end example

Au lieu d'essayer de trouver une bonne valeur d'attente pour la fonction @ref{688,,time.sleep()}, il vaut mieux utiliser un mécanisme basé sur les sémaphores. Une solution consiste à utiliser le module @ref{b5,,queue} pour créer un objet file, faire en sorte que chaque fil ajoute un jeton à la file quand il se termine, et que le fil principal retire autant de jetons de la file qu'il y a de fils.

@node Comment découper et répartir une tâche au sein d'un ensemble de fils d'exécutions ?,Quels types de mutations sur des variables globales sont compatibles avec les programmes à fils d'exécution multiples ? sécurisé ?,Aucun de mes fils ne semble s'exécuter pourquoi ?,Fils d'exécution<4>
@anchor{faq/library how-do-i-parcel-out-work-among-a-bunch-of-worker-threads}@anchor{4fe1}
@subsubsection Comment découper et répartir une tâche au sein d'un ensemble de fils d'exécutions ?


La manière la plus simple est d'utiliser le module @ref{21,,concurrent.futures}, en particulier la classe @ref{72c,,ThreadPoolExecutor}.

Ou bien, si vous désirez contrôler plus finement l'algorithme de distribution, vous pouvez écrire votre propre logique « à la main ». Utilisez le module @ref{b5,,queue} pour créer une file de tâches ; la classe @ref{1365,,Queue} gère une liste d'objets et a une méthode @code{.put(objet)} pour ajouter un élément à la file, et une méthode @code{.get()} pour les récupérer. La classe s'occupe de gérer les verrous pour que chaque tâche soit exécutée une et une seule fois.

Voici un exemple trivial :

@example
import threading, queue, time

# The worker thread gets jobs off the queue.  When the queue is empty, it
# assumes there will be no more work and exits.
# (Realistically workers will run until terminated.)
def worker():
    print('Running worker')
    time.sleep(0.1)
    while True:
        try:
            arg = q.get(block=False)
        except queue.Empty:
            print('Worker', threading.current_thread(), end=' ')
            print('queue empty')
            break
        else:
            print('Worker', threading.current_thread(), end=' ')
            print('running with argument', arg)
            time.sleep(0.5)

# Create queue
q = queue.Queue()

# Start a pool of 5 workers
for i in range(5):
    t = threading.Thread(target=worker, name='worker %i' % (i+1))
    t.start()

# Begin adding work to the queue
for i in range(50):
    q.put(i)

# Give threads time to run
print('Main thread sleeping')
time.sleep(5)
@end example

Quand celui-ci est exécuté, il produit la sortie suivante :

@example
Running worker
Running worker
Running worker
Running worker
Running worker
Main thread sleeping
Worker <Thread(worker 1, started 130283832797456)> running with argument 0
Worker <Thread(worker 2, started 130283824404752)> running with argument 1
Worker <Thread(worker 3, started 130283816012048)> running with argument 2
Worker <Thread(worker 4, started 130283807619344)> running with argument 3
Worker <Thread(worker 5, started 130283799226640)> running with argument 4
Worker <Thread(worker 1, started 130283832797456)> running with argument 5
...
@end example

Consultez la documentation du module pour plus de détails ; la classe @ref{1365,,Queue} fournit une interface pleine de fonctionnalités.

@node Quels types de mutations sur des variables globales sont compatibles avec les programmes à fils d'exécution multiples ? sécurisé ?,Pourquoi ne pas se débarrasser du verrou global de l'interpréteur ?,Comment découper et répartir une tâche au sein d'un ensemble de fils d'exécutions ?,Fils d'exécution<4>
@anchor{faq/library what-kinds-of-global-value-mutation-are-thread-safe}@anchor{4fe2}
@subsubsection Quels types de mutations sur des variables globales sont compatibles avec les programmes à fils d'exécution multiples ? sécurisé ?


Le @ref{147,,verrou global de l'interpréteur} (GIL pour `global interpreter lock') est utilisé en interne pour s'assurer que la machine virtuelle Python (MVP) n'exécute qu'un seul fil à la fois. De manière générale, Python ne change de fil qu'entre les instructions du code intermédiaire ; @ref{937,,sys.setswitchinterval()} permet de contrôler la fréquence de bascule entre les fils. Chaque instruction du code intermédiaire, et, par conséquent, tout le code C appelé par cette instruction est donc atomique du point de vue d'un programme Python.

En théorie, cela veut dire qu'un décompte exact nécessite une connaissance parfaite de l'implémentation de la MVP. En pratique, cela veut dire que les opérations sur des variables partagées de type natif (les entier, les listes, les dictionnaires, etc.) qui « semblent atomiques » le sont réellement.

Par exemple, les opérations suivantes sont toutes atomiques (`L', `L1' et `L2' sont des listes, `D', `D1' et `D2' sont des dictionnaires, `x' et `y' sont des objets, `i' et `j' des entiers) :

@example
L.append(x)
L1.extend(L2)
x = L[i]
x = L.pop()
L1[i:j] = L2
L.sort()
x = y
x.field = y
D[x] = y
D1.update(D2)
D.keys()
@end example

Les suivantes ne le sont pas :

@example
i = i+1
L.append(L[-1])
L[i] = L[j]
D[x] = D[x] + 1
@end example

Operations that replace other objects may invoke those other objects'
@ref{1ee3,,__del__()} method when their reference count reaches zero, and that can
affect things.  This is especially true for the mass updates to dictionaries and
lists.  When in doubt, use a mutex!

@node Pourquoi ne pas se débarrasser du verrou global de l'interpréteur ?,,Quels types de mutations sur des variables globales sont compatibles avec les programmes à fils d'exécution multiples ? sécurisé ?,Fils d'exécution<4>
@anchor{faq/library can-t-we-get-rid-of-the-global-interpreter-lock}@anchor{4fe3}
@subsubsection Pourquoi ne pas se débarrasser du verrou global de l'interpréteur ?


Le @ref{147,,verrou global de l'interpréteur} (GIL) est souvent vu comme un obstacle au déploiement de code Python sur des serveurs puissants avec de nombreux processeurs, car un programme Python à fils d'exécutions multiples n'utilise en réalité qu'un seul processeur. Presque tout le code Python ne peut en effet être exécuté qu'avec le GIL acquis.

With the approval of 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/} work is now underway to remove the GIL from the
CPython implementation of Python.  Initially it will be implemented as an
optional compiler flag when building the interpreter, and so separate
builds will be available with and without the GIL.  Long-term, the hope is
to settle on a single build, once the performance implications of removing the
GIL are fully understood.  Python 3.13 is likely to be the first release
containing this work, although it may not be completely functional in this
release.

The current work to remove the GIL is based on a
fork of Python 3.9 with the GIL removed@footnote{https://github.com/colesbury/nogil}
by Sam Gross.
Prior to that,
in the days of Python 1.5, Greg Stein actually implemented a comprehensive
patch set (the "free threading" patches) that removed the GIL and replaced it
with fine-grained locking.  Adam Olsen did a similar experiment
in his python-safethread@footnote{https://code.google.com/archive/p/python-safethread}
project.  Unfortunately, both of these earlier experiments exhibited a sharp
drop in single-thread
performance (at least 30% slower), due to the amount of fine-grained locking
necessary to compensate for the removal of the GIL.  The Python 3.9 fork
is the first attempt at removing the GIL with an acceptable performance
impact.

The presence of the GIL in current Python releases
doesn't mean that you can't make good use of Python on multi-CPU machines!
You just have to be creative with dividing the work up between multiple
`processes' rather than multiple `threads'.  The
@ref{8db,,ProcessPoolExecutor} class in the new
@ref{21,,concurrent.futures} module provides an easy way of doing so; the
@ref{93,,multiprocessing} module provides a lower-level API in case you want
more control over dispatching of tasks.

Des extensions C appropriées peuvent aussi aider ; en utilisant une extension C pour effectuer une tâche longue, l'extension peut relâcher le GIL pendant que le fil est en train d'exécuter ce code et laisser les autres fils travailler. Des modules de la bibliothèque standard comme @ref{132,,zlib} ou @ref{67,,hashlib} utilisent cette technique.

An alternative approach to reducing the impact of the GIL is
to make the GIL a per-interpreter-state lock rather than truly global.
This was @ref{425,,first implemented in Python 3.12} and is
available in the C API. A Python interface to it is expected in Python 3.13.
The main limitation to it at the moment is likely to be 3rd party extension
modules, since these must be written with multiple interpreters in mind in
order to be usable, so many older extension modules will not be usable.

@node Les entrées/sorties<2>,Programmation réseau et Internet,Fils d'exécution<4>,FAQ sur la bibliothèque et les extensions
@anchor{faq/library input-and-output}@anchor{4fe4}
@subsection Les entrées/sorties


@menu
* Comment supprimer un fichier ? (et autres questions sur les fichiers…): Comment supprimer un fichier ? et autres questions sur les fichiers…. 
* Comment copier un fichier ?:: 
* Comment lire (ou écrire) des données binaires ?: Comment lire ou écrire des données binaires ?. 
* Il me semble impossible d'utiliser os.read() sur un tube créé avec os.popen() ; pourquoi ?: Il me semble impossible d'utiliser os read sur un tube créé avec os popen ; pourquoi ?. 
* Comment accéder au port de transmission en série (RS-232) ?: Comment accéder au port de transmission en série RS-232 ?. 
* Pourquoi fermer sys.stdout@comma{} sys.stdin@comma{} sys.stderr ne les ferme pas réellement ?: Pourquoi fermer sys stdout sys stdin sys stderr ne les ferme pas réellement ?. 

@end menu

@node Comment supprimer un fichier ? et autres questions sur les fichiers…,Comment copier un fichier ?,,Les entrées/sorties<2>
@anchor{faq/library how-do-i-delete-a-file-and-other-file-questions}@anchor{4fe5}
@subsubsection Comment supprimer un fichier ? (et autres questions sur les fichiers…)


Utilisez @code{os.remove(filename)} ou @code{os.unlink(filename)} ; pour la documentation, référez-vous au module @ref{a0,,os}. Ces deux fonctions sont identiques, @ref{10d6,,unlink()} n'est tout simplement que le nom de l'appel système à cette fonction sous Unix.

Utilisez @ref{10d4,,os.rmdir()} pour supprimer un dossier et @ref{21a,,os.mkdir()} pour en créer un nouveau. @code{os.makedirs(chemin)} crée les dossiers intermédiaires de @code{chemin} qui n'existent pas et @code{os.removedirs(chemin)} supprime les dossiers intermédiaires si ceux-ci sont vides. Pour supprimer une arborescence et tout son contenu, utilisez @ref{2f5,,shutil.rmtree()}.

@code{os.rename(ancien_chemin, nouveau_chemin)} permet de renommer un fichier.

Pour supprimer le contenu d'un fichier, ouvrez celui-ci avec @code{f = open(nom_du_fichier, "rb+")}, puis exécutez @code{f.truncate(décalage)} où `décalage' est par défaut la position actuelle de la tête de lecture. Il existe aussi @code{os.ftruncate(df, décalage)} pour les fichiers ouverts avec @ref{d7f,,os.open()}, où `df' est le descripteur de fichier (un entier court).

Le module @ref{c4,,shutil} propose aussi un grand nombre de fonctions pour effectuer des opérations sur des fichiers comme @ref{a47,,copyfile()}, @ref{a17,,copytree()} et @ref{2f5,,rmtree()}.

@node Comment copier un fichier ?,Comment lire ou écrire des données binaires ?,Comment supprimer un fichier ? et autres questions sur les fichiers…,Les entrées/sorties<2>
@anchor{faq/library how-do-i-copy-a-file}@anchor{4fe6}
@subsubsection Comment copier un fichier ?


The @ref{c4,,shutil} module contains a @ref{a47,,copyfile()} function.
Note that on Windows NTFS volumes, it does not copy
alternate data streams@footnote{https://en.wikipedia.org/wiki/NTFS#Alternate_data_stream_(ADS)}
nor resource forks@footnote{https://en.wikipedia.org/wiki/Resource_fork}
on macOS HFS+ volumes, though both are now rarely used.
It also doesn't copy file permissions and metadata, though using
@ref{a49,,shutil.copy2()} instead will preserve most (though not all) of it.

@node Comment lire ou écrire des données binaires ?,Il me semble impossible d'utiliser os read sur un tube créé avec os popen ; pourquoi ?,Comment copier un fichier ?,Les entrées/sorties<2>
@anchor{faq/library how-do-i-read-or-write-binary-data}@anchor{4fe7}
@subsubsection Comment lire (ou écrire) des données binaires ?


Pour lire ou écrire des formats de données complexes en binaire, il est recommandé d'utiliser le module @ref{d4,,struct}. Celui-ci permet de convertir une chaîne de caractères qui contient des données binaires, souvent des nombres, en objets Python, et vice-versa.

Par exemple, le code suivant lit, depuis un fichier, deux entiers codés sur 2 octets et un entier codé sur 4 octets, en format gros-boutiste :

@example
import struct

with open(filename, "rb") as f:
    s = f.read(8)
    x, y, z = struct.unpack(">hhl", s)
@end example

« > » dans la chaîne de formatage indique que la donnée doit être lue en mode gros-boutiste, la lettre « h » indique un entier court (2 octets) et la lettre « l » indique un entier long (4 octets).

Pour une donnée plus régulière (p. ex. une liste homogène d'entiers ou de nombres à virgule flottante), il est possible d'utiliser le module @ref{7,,array}.

@cartouche
@quotation Note 
Pour lire et écrire de la donnée binaire, il est obligatoire d'ouvrir le fichier en mode binaire également (ici, en passant @code{"rb"} à @ref{505,,open()}). En utilisant @code{"r"} (valeur par défaut), le fichier est ouvert en mode textuel et @code{f.read()} renvoie des objets @ref{435,,str} au lieu d'objets @ref{1bd,,bytes}.
@end quotation
@end cartouche

@node Il me semble impossible d'utiliser os read sur un tube créé avec os popen ; pourquoi ?,Comment accéder au port de transmission en série RS-232 ?,Comment lire ou écrire des données binaires ?,Les entrées/sorties<2>
@anchor{faq/library i-can-t-seem-to-use-os-read-on-a-pipe-created-with-os-popen-why}@anchor{4fe8}
@subsubsection Il me semble impossible d'utiliser @code{os.read()} sur un tube créé avec @code{os.popen()} ; pourquoi ?


@ref{d82,,os.read()} est une fonction de bas niveau qui prend en paramètre un descripteur de fichier — un entier court qui représente le fichier ouvert. @ref{a75,,os.popen()} crée un objet fichier de haut niveau, du même type que celui renvoyé par la fonction native @ref{505,,open()}. Par conséquent, pour lire `n' octets d'un tube `p' créé avec @ref{a75,,os.popen()}, il faut utiliser @code{p.read(n)}.

@c XXX update to use subprocess. See the :ref:`subprocess-replacements` section.
@c 
@c How do I run a subprocess with pipes connected to both input and output?
@c ------------------------------------------------------------------------
@c 
@c Use the :mod:`popen2` module.  For example::
@c 
@c    import popen2
@c    fromchild, tochild = popen2.popen2("command")
@c    tochild.write("input\n")
@c    tochild.flush()
@c    output = fromchild.readline()
@c 
@c Warning: in general it is unwise to do this because you can easily cause a
@c deadlock where your process is blocked waiting for output from the child
@c while the child is blocked waiting for input from you.  This can be caused
@c by the parent expecting the child to output more text than it does or
@c by data being stuck in stdio buffers due to lack of flushing.
@c The Python parent can of course explicitly flush the data it sends to the
@c child before it reads any output, but if the child is a naive C program it
@c may have been written to never explicitly flush its output, even if it is
@c interactive, since flushing is normally automatic.
@c 
@c Note that a deadlock is also possible if you use :func:`popen3` to read
@c stdout and stderr. If one of the two is too large for the internal buffer
@c (increasing the buffer size does not help) and you ``read()`` the other one
@c first, there is a deadlock, too.
@c 
@c Note on a bug in popen2: unless your program calls ``wait()`` or
@c ``waitpid()``, finished child processes are never removed, and eventually
@c calls to popen2 will fail because of a limit on the number of child
@c processes.  Calling :func:`os.waitpid` with the :const:`os.WNOHANG` option can
@c prevent this; a good place to insert such a call would be before calling
@c ``popen2`` again.
@c 
@c In many cases, all you really need is to run some data through a command and
@c get the result back.  Unless the amount of data is very large, the easiest
@c way to do this is to write it to a temporary file and run the command with
@c that temporary file as input.  The standard module :mod:`tempfile` exports a
@c :func:`~tempfile.mktemp` function to generate unique temporary file names. ::
@c 
@c    import tempfile
@c    import os
@c 
@c    class Popen3:
@c        """
@c        This is a deadlock-safe version of popen that returns
@c        an object with errorlevel, out (a string) and err (a string).
@c        (capturestderr may not work under windows.)
@c        Example: print(Popen3('grep spam','\n\nhere spam\n\n').out)
@c        """
@c        def __init__(self,command,input=None,capturestderr=None):
@c            outfile=tempfile.mktemp()
@c            command="( %s ) > %s" % (command,outfile)
@c            if input:
@c                infile=tempfile.mktemp()
@c                open(infile,"w").write(input)
@c                command=command+" <"+infile
@c            if capturestderr:
@c                errfile=tempfile.mktemp()
@c                command=command+" 2>"+errfile
@c            self.errorlevel=os.system(command) >> 8
@c            self.out=open(outfile,"r").read()
@c            os.remove(outfile)
@c            if input:
@c                os.remove(infile)
@c            if capturestderr:
@c                self.err=open(errfile,"r").read()
@c                os.remove(errfile)
@c 
@c Note that many interactive programs (e.g. vi) don't work well with pipes
@c substituted for standard input and output.  You will have to use pseudo ttys
@c ("ptys") instead of pipes. Or you can use a Python interface to Don Libes'
@c "expect" library.  A Python extension that interfaces to expect is called
@c "expy" and available from https://expectpy.sourceforge.net.  A pure Python
@c solution that works like expect is :pypi:`pexpect`.

@node Comment accéder au port de transmission en série RS-232 ?,Pourquoi fermer sys stdout sys stdin sys stderr ne les ferme pas réellement ?,Il me semble impossible d'utiliser os read sur un tube créé avec os popen ; pourquoi ?,Les entrées/sorties<2>
@anchor{faq/library how-do-i-access-the-serial-rs232-port}@anchor{4fe9}
@subsubsection Comment accéder au port de transmission en série (RS-232) ?


Pour Win32, OSX, Linux, BSD, Jython et IronPython :

@quotation

pyserial@footnote{https://pypi.org/project/pyserial/}
@end quotation

Pour Unix, référez-vous à une publication sur Usenet de Mitch Chapman :

@quotation

@indicateurl{https://groups.google.com/groups?selm=34A04430.CF9@@ohioee.com}
@end quotation

@node Pourquoi fermer sys stdout sys stdin sys stderr ne les ferme pas réellement ?,,Comment accéder au port de transmission en série RS-232 ?,Les entrées/sorties<2>
@anchor{faq/library why-doesn-t-closing-sys-stdout-stdin-stderr-really-close-it}@anchor{4fea}
@subsubsection Pourquoi fermer `sys.stdout', `sys.stdin', `sys.stderr' ne les ferme pas réellement ?


Les @ref{11a0,,objets fichiers} en Python sont des abstractions de haut niveau sur les descripteurs de fichier C de bas niveau.

Pour la plupart des objets fichiers créés en Python avec la fonction native @ref{505,,open()}, @code{f.close()} marque le fichier comme fermé du point de vue de Python et ferme aussi le descripteur C sous-jacent. Le même mécanisme est enclenché automatiquement dans le destructeur de @code{f}, lorsque @code{f} est recyclé.

Mais `stdin', `stdout' et `stderr' ont droit à un traitement spécial en Python, car leur statut en C est lui aussi spécial.  Exécuter @code{sys.stdout.close()} marque l'objet fichier comme fermé du point de vue de Python, mais le descripteur de fichier C associé n'est `pas' fermé.

Pour fermer le descripteur de fichier sous-jacent C de l'une de ces trois sorties, demandez-vous avant tout si vous êtes sûr de vous (cela peut, par exemple, perturber le bon fonctionnement de modules qui font des opérations d'entrée-sortie). Si c'est le cas, utilisez @ref{b62,,os.close()} :

@example
os.close(stdin.fileno())
os.close(stdout.fileno())
os.close(stderr.fileno())
@end example

Il est aussi possible de fermer respectivement les constantes numériques 0, 1 ou 2.

@node Programmation réseau et Internet,Bases de données,Les entrées/sorties<2>,FAQ sur la bibliothèque et les extensions
@anchor{faq/library network-internet-programming}@anchor{4feb}
@subsection Programmation réseau et Internet


@menu
* Quels sont les outils Python dédiés à au web ?:: 
* Quel module utiliser pour générer du HTML ?:: 
* Comment envoyer un courriel avec un script Python ?:: 
* Comment éviter de bloquer dans la méthode connect() d'un connecteur réseau ?: Comment éviter de bloquer dans la méthode connect d'un connecteur réseau ?. 

@end menu

@node Quels sont les outils Python dédiés à au web ?,Quel module utiliser pour générer du HTML ?,,Programmation réseau et Internet
@anchor{faq/library what-www-tools-are-there-for-python}@anchor{4fec}
@subsubsection Quels sont les outils Python dédiés à au web ?


Référez-vous aux chapitres intitulés @ref{388f,,Gestion des protocoles internet} et @ref{34aa,,Traitement des données provenant d'Internet} dans le manuel de référence de la bibliothèque. Python a de nombreux modules pour construire des applications web côté client comme côté serveur.

@c XXX check if wiki page is still up to date

Un résumé des cadriciels disponibles est maintenu par Paul Boddie à l'adresse @indicateurl{https://wiki.python.org/moin/WebProgramming}.

@node Quel module utiliser pour générer du HTML ?,Comment envoyer un courriel avec un script Python ?,Quels sont les outils Python dédiés à au web ?,Programmation réseau et Internet
@anchor{faq/library what-module-should-i-use-to-help-with-generating-html}@anchor{4fed}
@subsubsection Quel module utiliser pour générer du HTML ?


@c XXX add modern template languages

La page wiki de la programmation web@footnote{https://wiki.python.org/moin/WebProgramming} (en anglais) répertorie un ensemble de liens pertinents.

@node Comment envoyer un courriel avec un script Python ?,Comment éviter de bloquer dans la méthode connect d'un connecteur réseau ?,Quel module utiliser pour générer du HTML ?,Programmation réseau et Internet
@anchor{faq/library how-do-i-send-mail-from-a-python-script}@anchor{4fee}
@subsubsection Comment envoyer un courriel avec un script Python ?


Utilisez le module @ref{c9,,smtplib} de la bibliothèque standard.

Voici un exemple très simple d'un envoyeur de courriel qui l'utilise. Cette méthode fonctionne sur tous les serveurs qui implémentent SMTP.

@example
import sys, smtplib

fromaddr = input("From: ")
toaddrs  = input("To: ").split(',')
print("Enter message, end with ^D:")
msg = '@w{'}
while True:
    line = sys.stdin.readline()
    if not line:
        break
    msg += line

# The actual mail send
server = smtplib.SMTP('localhost')
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
@end example

Sous Unix, il est possible d'utiliser `sendmail'. La localisation de l'exécutable `sendmail' dépend du système ; cela peut-être @code{/usr/lib/sendmail} ou @code{/usr/sbin/sendmail}, la page de manuel de `sendmail' peut vous aider. Par exemple :

@example
import os

SENDMAIL = "/usr/sbin/sendmail"  # sendmail location
p = os.popen("%s -t -i" % SENDMAIL, "w")
p.write("To: receiver@@example.com\n")
p.write("Subject: test\n")
p.write("\n")  # blank line separating headers from body
p.write("Some text\n")
p.write("some more text\n")
sts = p.close()
if sts != 0:
    print("Sendmail exit status", sts)
@end example

@node Comment éviter de bloquer dans la méthode connect d'un connecteur réseau ?,,Comment envoyer un courriel avec un script Python ?,Programmation réseau et Internet
@anchor{faq/library how-do-i-avoid-blocking-in-the-connect-method-of-a-socket}@anchor{4fef}
@subsubsection Comment éviter de bloquer dans la méthode @code{connect()} d'un connecteur réseau ?


Le module @ref{c0,,select} est fréquemment utilisé pour effectuer des entrées-sorties asynchrones sur des connecteurs réseaux.

To prevent the TCP connect from blocking, you can set the socket to non-blocking
mode.  Then when you do the @ref{d90,,connect()},
you will either connect immediately
(unlikely) or get an exception that contains the error number as @code{.errno}.
@code{errno.EINPROGRESS} indicates that the connection is in progress, but hasn't
finished yet.  Different OSes will return different values, so you're going to
have to check what's returned on your system.

You can use the @ref{14ef,,connect_ex()} method
to avoid creating an exception.
It will just return the errno value.
To poll, you can call @ref{14ef,,connect_ex()} again later
-- @code{0} or @code{errno.EISCONN} indicate that you're connected -- or you can pass this
socket to @ref{d8d,,select.select()} to check if it's writable.

@cartouche
@quotation Note 
The @ref{a,,asyncio} module provides a general purpose single-threaded and
concurrent asynchronous library, which can be used for writing non-blocking
network code.
The third-party Twisted@footnote{https://twisted.org/} library is
a popular and feature-rich alternative.
@end quotation
@end cartouche

@node Bases de données,Mathématiques et calcul numérique,Programmation réseau et Internet,FAQ sur la bibliothèque et les extensions
@anchor{faq/library databases}@anchor{4ff0}
@subsection Bases de données


@menu
* Existe-t-il des modules Python pour s'interfacer avec des bases de données ?:: 
* Comment implémenter la persistance d'objets en Python ?:: 

@end menu

@node Existe-t-il des modules Python pour s'interfacer avec des bases de données ?,Comment implémenter la persistance d'objets en Python ?,,Bases de données
@anchor{faq/library are-there-any-interfaces-to-database-packages-in-python}@anchor{4ff1}
@subsubsection Existe-t-il des modules Python pour s'interfacer avec des bases de données ?


Oui.

La distribution standard de Python fournit aussi des interfaces à des bases de données comme @ref{34,,DBM} ou @ref{33,,GDBM}.  Il existe aussi le module @ref{ce,,sqlite3} qui implémente une base de données relationnelle légère sur disque.

La gestion de la plupart des bases de données relationnelles est assurée. Voir la page wiki DatabaseProgramming@footnote{https://wiki.python.org/moin/DatabaseProgramming} pour plus de détails.

@node Comment implémenter la persistance d'objets en Python ?,,Existe-t-il des modules Python pour s'interfacer avec des bases de données ?,Bases de données
@anchor{faq/library how-do-you-implement-persistent-objects-in-python}@anchor{4ff2}
@subsubsection Comment implémenter la persistance d'objets en Python ?


Le module @ref{a5,,pickle} répond à cela de manière large (bien qu'il ne soit pas possible de stocker des fichiers ouverts, des connecteurs ou des fenêtres par exemple), et le module @ref{c2,,shelve} de la bibliothèque utilise `pickle' et `(g)dbm' pour créer des liens persistants vers des objets Python.

@node Mathématiques et calcul numérique,,Bases de données,FAQ sur la bibliothèque et les extensions
@anchor{faq/library mathematics-and-numerics}@anchor{4ff3}
@subsection Mathématiques et calcul numérique


@menu
* Comment générer des nombres aléatoires en Python ?:: 

@end menu

@node Comment générer des nombres aléatoires en Python ?,,,Mathématiques et calcul numérique
@anchor{faq/library how-do-i-generate-random-numbers-in-python}@anchor{4ff4}
@subsubsection Comment générer des nombres aléatoires en Python ?


Le module @ref{b7,,random} de la bibliothèque standard comprend un générateur de nombres aléatoires. Son utilisation est simple :

@example
import random
random.random()
@end example

This returns a random floating-point number in the range [0, 1).

Ce module fournit beaucoup d'autres générateurs spécialisés comme :


@itemize *

@item 
@code{randrange(a, b)} génère un entier dans l'intervalle [a, b[.

@item 
@code{uniform(a, b)} chooses a floating-point number in the range [a, b).

@item 
@code{normalvariate(mean, sdev)} simule la loi normale (Gaussienne).
@end itemize

Des fonctions de haut niveau opèrent directement sur des séquences comme :


@itemize *

@item 
@code{choice(S)} sélectionne au hasard un élément d'une séquence donnée.

@item 
@code{shuffle(L)} mélange une liste en-place, c.-à-d. lui applique une permutation aléatoire.
@end itemize

Il existe aussi une classe @code{Random} qu'il est possible d'instancier pour créer des générateurs aléatoires indépendants.

@node FAQ extension/intégration,FAQ Python et Windows,FAQ sur la bibliothèque et les extensions,Questions fréquemment posées sur Python
@anchor{faq/extending doc}@anchor{4ff5}@anchor{faq/extending extending-embedding-faq}@anchor{4ff6}
@section FAQ extension/intégration



@c XXX need review for Python 3.

@menu
* Puis-je créer mes propres fonctions en C ?:: 
* Puis-je créer mes propres fonctions en C++ ?:: 
* Écrire directement en C est difficile ; existe-t-il des alternatives ?:: 
* Comment puis-je exécuter des instructions quelconques Python à partir de C ?:: 
* Comment puis-je évaluer une expression quelconque de Python à partir de C ?:: 
* Comment puis-je extraire des donnés en C d'un objet Python ?:: 
* Comment utiliser Py_BuildValue() pour créer un n-uplet de longueur définie ?: Comment utiliser Py_BuildValue pour créer un n-uplet de longueur définie ?. 
* Comment puis-je appeler la méthode d'un objet à partir de C ?:: 
* Comment puis-je récupérer la sortie de PyErr_Print() (ou tout ce qui s'affiche sur stdout/stderr) ?: Comment puis-je récupérer la sortie de PyErr_Print ou tout ce qui s'affiche sur stdout/stderr ?. 
* Comment accéder à un module écrit en Python à partir de C ?:: 
* Comment s'interfacer avec les objets C++ depuis Python ?:: 
* J'ai ajouté un module en utilisant le fichier Setup et la compilation échoue ; pourquoi ?:: 
* Comment déboguer une extension ?:: 
* Je veux compiler un module Python sur mon système Linux@comma{} mais il manque certains fichiers. Pourquoi ?: Je veux compiler un module Python sur mon système Linux mais il manque certains fichiers Pourquoi ?. 
* Comment distinguer une « entrée incomplète » (incomplete input) d'une « entrée invalide » (invalid input) ?: Comment distinguer une « entrée incomplète » incomplete input d'une « entrée invalide » invalid input ?. 
* Comment puis-je trouver les symboles g++ indéfinis __builtin_new ou __pure_virtual ?:: 
* Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python (p. ex. en utilisant l'héritage) ?: Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python p ex en utilisant l'héritage ?. 

@end menu

@node Puis-je créer mes propres fonctions en C ?,Puis-je créer mes propres fonctions en C++ ?,,FAQ extension/intégration
@anchor{faq/extending can-i-create-my-own-functions-in-c}@anchor{4ff7}
@subsection Puis-je créer mes propres fonctions en C ?


Oui, vous pouvez créer des modules intégrés contenant des fonctions, des variables, des exceptions et même de nouveaux types en C. Ceci est expliqué dans le document @ref{1b69,,Extension et intégration de l'interpréteur Python}.

La plupart des livres Python intermédiaires ou avancés couvrent également ce sujet.

@node Puis-je créer mes propres fonctions en C++ ?,Écrire directement en C est difficile ; existe-t-il des alternatives ?,Puis-je créer mes propres fonctions en C ?,FAQ extension/intégration
@anchor{faq/extending id1}@anchor{4ff8}
@subsection Puis-je créer mes propres fonctions en C++ ?


Oui, en utilisant les fonctionnalités de compatibilité C existantes en C++.  Placez @code{extern "C" @{ ... @}} autour des fichiers Python inclus et mettez  @code{extern "C"} avant chaque fonction qui va être appelée par l'interpréteur Python.  Les objets  C++ globaux ou statiques avec les constructeurs ne sont probablement pas une bonne idée.

@node Écrire directement en C est difficile ; existe-t-il des alternatives ?,Comment puis-je exécuter des instructions quelconques Python à partir de C ?,Puis-je créer mes propres fonctions en C++ ?,FAQ extension/intégration
@anchor{faq/extending c-wrapper-software}@anchor{4ff9}@anchor{faq/extending writing-c-is-hard-are-there-any-alternatives}@anchor{4ffa}
@subsection Écrire directement en C est difficile ; existe-t-il des alternatives ?


Il y a un certain nombre de solutions existantes qui vous permettent d'écrire vos propres extensions C, selon ce que vous essayez de faire.

@c XXX make sure these all work

Cython@footnote{https://cython.org} and its relative Pyrex@footnote{https://www.csse.canterbury.ac.nz/greg.ewing/python/Pyrex/} are compilers
that accept a slightly modified form of Python and generate the corresponding
C code.  Cython and Pyrex make it possible to write an extension without having
to learn Python's C API.

If you need to interface to some C or C++ library for which no Python extension
currently exists, you can try wrapping the library's data types and functions
with a tool such as SWIG@footnote{https://www.swig.org}.  SIP@footnote{https://github.com/Python-SIP/sip}, CXX@footnote{https://cxx.sourceforge.net/} Boost@footnote{https://www.boost.org/libs/python/doc/index.html}, or Weave@footnote{https://github.com/scipy/weave} are also
alternatives for wrapping C++ libraries.

@node Comment puis-je exécuter des instructions quelconques Python à partir de C ?,Comment puis-je évaluer une expression quelconque de Python à partir de C ?,Écrire directement en C est difficile ; existe-t-il des alternatives ?,FAQ extension/intégration
@anchor{faq/extending how-can-i-execute-arbitrary-python-statements-from-c}@anchor{4ffb}
@subsection Comment puis-je exécuter des instructions quelconques Python à partir de C ?


La fonction de plus haut niveau pour ce faire est @code{PyRun_SimpleStringString()} qui prend une chaîne pour seul argument afin de l'exécuter dans le contexte du module @code{__main__} et renvoie @code{0} en cas de succès et @code{-1} quand une exception se produit (incluant @ref{18b,,SyntaxError}). Pour une meilleure maîtrise, utilisez @ref{1969,,PyRun_String()} ; voir le code source pour @ref{4829,,PyRun_SimpleString()} dans @code{Python/pythonrun.c}.

@node Comment puis-je évaluer une expression quelconque de Python à partir de C ?,Comment puis-je extraire des donnés en C d'un objet Python ?,Comment puis-je exécuter des instructions quelconques Python à partir de C ?,FAQ extension/intégration
@anchor{faq/extending how-can-i-evaluate-an-arbitrary-python-expression-from-c}@anchor{4ffc}
@subsection Comment puis-je évaluer une expression quelconque de Python à partir de C ?


Appelez la fonction @ref{1969,,PyRun_String()} de la question précédente avec le symbole de départ @ref{49ce,,Py_eval_input} ; il analyse une expression, l'évalue et renvoie sa valeur.

@node Comment puis-je extraire des donnés en C d'un objet Python ?,Comment utiliser Py_BuildValue pour créer un n-uplet de longueur définie ?,Comment puis-je évaluer une expression quelconque de Python à partir de C ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-extract-c-values-from-a-python-object}@anchor{4ffd}
@subsection Comment puis-je extraire des donnés en C d'un objet Python ?


That depends on the object's type.  If it's a tuple, @ref{495d,,PyTuple_Size()}
returns its length and @ref{47d7,,PyTuple_GetItem()} returns the item at a specified
index.  Lists have similar functions, @ref{13d0,,PyList_Size()} and
@ref{352,,PyList_GetItem()}.

For bytes, @ref{4877,,PyBytes_Size()} returns its length and
@ref{4871,,PyBytes_AsStringAndSize()} provides a pointer to its value and its
length.  Note that Python bytes objects may contain null bytes so C's
@code{strlen()} should not be used.

Pour tester le type d'un objet, assurez-vous d'abord qu'il ne soit pas @code{NULL}, puis utilisez @ref{136b,,PyBytes_Check()}, @ref{4b3c,,PyTuple_Check()}, @ref{4b4c,,PyList_Check()}, etc.

Il y a aussi une API de haut niveau pour les objets Python qui est fournie par l'interface dite « abstraite » — voir @code{Include/abstract.h} pour plus de détails. Elle permet l'interfaçage avec tout type de séquence Python en utilisant des appels tels que @ref{493e,,PySequence_Length()}, @ref{19e1,,PySequence_GetItem()}, etc. ainsi que de nombreux autres protocoles utiles tels que les nombres (@ref{87f,,PyNumber_Index()} et autres) et les correspondances dans les APIs PyMapping.

@node Comment utiliser Py_BuildValue pour créer un n-uplet de longueur définie ?,Comment puis-je appeler la méthode d'un objet à partir de C ?,Comment puis-je extraire des donnés en C d'un objet Python ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-use-py-buildvalue-to-create-a-tuple-of-arbitrary-length}@anchor{4ffe}
@subsection Comment utiliser Py_BuildValue() pour créer un `n'-uplet de longueur définie ?


Vous ne pouvez pas. Utilisez @ref{495c,,PyTuple_Pack()} à la place.

@node Comment puis-je appeler la méthode d'un objet à partir de C ?,Comment puis-je récupérer la sortie de PyErr_Print ou tout ce qui s'affiche sur stdout/stderr ?,Comment utiliser Py_BuildValue pour créer un n-uplet de longueur définie ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-call-an-object-s-method-from-c}@anchor{4fff}
@subsection Comment puis-je appeler la méthode d'un objet à partir de C ?


La fonction @ref{396,,PyObject_CallMethod()} peut être utilisée pour appeler la méthode d'un objet. Les paramètres sont l'objet, le nom de la méthode à appeler, une chaîne de caractères comme celle utilisée pour @ref{894,,Py_BuildValue()} et les valeurs des arguments :

@example
PyObject *
PyObject_CallMethod(PyObject *object, const char *method_name,
                    const char *arg_format, ...);
@end example

Cela fonctionne pour tous les objets qui ont des méthodes — qu'elles soient intégrées ou définies par l'utilisateur. Vous êtes responsable de « @ref{55b,,Py_DECREF()}`er' » la valeur de retour à la fin.

Pour appeler, p. ex., la méthode `seek' d'un objet `file' avec les arguments 10, 0 (en supposant que le pointeur de l'objet fichier est `f') :

@example
res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
if (res == NULL) @{
        ... an exception occurred ...
@}
else @{
        Py_DECREF(res);
@}
@end example

Notez que @ref{47cc,,PyObject_CallObject()} veut `toujours' un `n'-uplet comme liste d'arguments. Aussi, pour appeler une fonction sans arguments, utilisez "()" pour être conforme au type et, pour appeler une fonction avec un paramètre, entourez-le de parenthèses, p. ex. "(i)".

@node Comment puis-je récupérer la sortie de PyErr_Print ou tout ce qui s'affiche sur stdout/stderr ?,Comment accéder à un module écrit en Python à partir de C ?,Comment puis-je appeler la méthode d'un objet à partir de C ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-catch-the-output-from-pyerr-print-or-anything-that-prints-to-stdout-stderr}@anchor{5000}
@subsection Comment puis-je récupérer la sortie de @code{PyErr_Print()} (ou tout ce qui s'affiche sur `stdout'/`stderr') ?


Dans le code Python, définissez un objet qui possède la méthode @code{write()}. Affectez cet objet à @ref{ac4,,sys.stdout} et @ref{926,,sys.stderr}. Appelez `print_error' ou faites simplement en sorte que le mécanisme standard de remontée des erreurs fonctionne. Ensuite, la sortie sera dirigée vers l'endroit où votre méthode @code{write()} écrit.

La façon la plus simple consiste à utiliser la classe @ref{f12,,io.StringIO} :

@example
>>> import io, sys
>>> sys.stdout = io.StringIO()
>>> print('foo')
>>> print('hello world!')
>>> sys.stderr.write(sys.stdout.getvalue())
foo
hello world!
@end example

Le code d'un objet à la fonctionnalité similaire ressemblerait à ceci :

@example
>>> import io, sys
>>> class StdoutCatcher(io.TextIOBase):
...     def __init__(self):
...         self.data = []
...     def write(self, stuff):
...         self.data.append(stuff)
...
>>> import sys
>>> sys.stdout = StdoutCatcher()
>>> print('foo')
>>> print('hello world!')
>>> sys.stderr.write('@w{'}.join(sys.stdout.data))
foo
hello world!
@end example

@node Comment accéder à un module écrit en Python à partir de C ?,Comment s'interfacer avec les objets C++ depuis Python ?,Comment puis-je récupérer la sortie de PyErr_Print ou tout ce qui s'affiche sur stdout/stderr ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-access-a-module-written-in-python-from-c}@anchor{5001}
@subsection Comment accéder à un module écrit en Python à partir de C ?


Vous pouvez obtenir un pointeur sur l'objet module comme suit :

@example
module = PyImport_ImportModule("<modulename>");
@end example

Si le module n'a pas encore été importé (c.-à-d. qu'il n'est pas encore présent dans @ref{18f9,,sys.modules}), cela initialise le module ; sinon il renvoie simplement la valeur de @code{sys.modules["<modulename>"]}. Notez qu'il n'inscrit le module dans aucun espace de nommage — il s'assure seulement qu'il a été initialisé et qu'il est stocké dans @ref{18f9,,sys.modules}.

Vous pouvez alors accéder aux attributs du module (c.-à-d. à tout nom défini dans le module) comme suit :

@example
attr = PyObject_GetAttrString(module, "<attrname>");
@end example

Appeler @ref{1589,,PyObject_SetAttrString()} pour assigner des valeurs aux variables du module fonctionne également.

@node Comment s'interfacer avec les objets C++ depuis Python ?,J'ai ajouté un module en utilisant le fichier Setup et la compilation échoue ; pourquoi ?,Comment accéder à un module écrit en Python à partir de C ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-interface-to-c-objects-from-python}@anchor{5002}
@subsection Comment s'interfacer avec les objets C++ depuis Python ?


Selon vos besoins, de nombreuses approches sont possibles. Pour le faire manuellement, commencez par lire @ref{1b69,,le document "Extension et intégration"}. Sachez que pour le système d'exécution Python, il n'y a pas beaucoup de différence entre C et C++ — donc la méthode pour construire un nouveau type Python à partir d'une structure C (pointeur) fonctionne également avec des objets en C++.

Pour les bibliothèques C++, voir @ref{4ff9,,Écrire directement en C est difficile ; existe-t-il des alternatives ?}.

@node J'ai ajouté un module en utilisant le fichier Setup et la compilation échoue ; pourquoi ?,Comment déboguer une extension ?,Comment s'interfacer avec les objets C++ depuis Python ?,FAQ extension/intégration
@anchor{faq/extending i-added-a-module-using-the-setup-file-and-the-make-fails-why}@anchor{5003}
@subsection J'ai ajouté un module en utilisant le fichier `Setup' et la compilation échoue ; pourquoi ?


Le fichier `Setup' doit se terminer par une ligne vide, s'il n'y a pas de ligne vide, le processus de compilation échoue (ce problème peut se régler en bidouillant un script shell, et ce bogue est si mineur qu'il ne mérite pas qu'on s'y attarde).

@node Comment déboguer une extension ?,Je veux compiler un module Python sur mon système Linux mais il manque certains fichiers Pourquoi ?,J'ai ajouté un module en utilisant le fichier Setup et la compilation échoue ; pourquoi ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-debug-an-extension}@anchor{5004}
@subsection Comment déboguer une extension ?


Lorsque vous utilisez GDB avec des extensions chargées dynamiquement, vous ne pouvez pas placer de point d'arrêt dans votre extension tant que celle-ci n'est pas chargée.

Dans votre fichier @code{.gdbinit} (ou manuellement), ajoutez la commande :

@example
br _PyImport_LoadDynamicModule
@end example

Ensuite, lorsque vous exécutez GDB :

@example
$ gdb /local/bin/python
gdb) run myscript.py
gdb) continue # repeat until your extension is loaded
gdb) finish   # so that your extension is loaded
gdb) br myfunction.c:50
gdb) continue
@end example

@node Je veux compiler un module Python sur mon système Linux mais il manque certains fichiers Pourquoi ?,Comment distinguer une « entrée incomplète » incomplete input d'une « entrée invalide » invalid input ?,Comment déboguer une extension ?,FAQ extension/intégration
@anchor{faq/extending i-want-to-compile-a-python-module-on-my-linux-system-but-some-files-are-missing-why}@anchor{5005}
@subsection Je veux compiler un module Python sur mon système Linux, mais il manque certains fichiers. Pourquoi ?


Most packaged versions of Python omit some files
required for compiling Python extensions.

For Red Hat, install the python3-devel RPM to get the necessary files.

For Debian, run @code{apt-get install python3-dev}.

@node Comment distinguer une « entrée incomplète » incomplete input d'une « entrée invalide » invalid input ?,Comment puis-je trouver les symboles g++ indéfinis __builtin_new ou __pure_virtual ?,Je veux compiler un module Python sur mon système Linux mais il manque certains fichiers Pourquoi ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-tell-incomplete-input-from-invalid-input}@anchor{5006}
@subsection Comment distinguer une « entrée incomplète » (`incomplete input') d'une « entrée invalide » (`invalid input') ?


Parfois vous souhaitez émuler le comportement de l'interpréteur interactif Python, quand il vous donne une invite de continuation lorsque l'entrée est incomplète (par exemple, vous avez tapé le début d'une instruction "if" ou vous n'avez pas fermé vos parenthèses ou triple guillemets) mais il vous renvoie immédiatement une erreur syntaxique quand la saisie est incorrecte.

En Python, vous pouvez utiliser le module @ref{1c,,codeop}, qui se rapproche assez du comportement de l'analyseur. Par exemple, IDLE l'utilise.

La façon la plus simple de le faire en C est d'appeler @ref{49d5,,PyRun_InteractiveLoop()} (peut-être dans un autre fil d'exécution) et laisser l'interpréteur Python gérer l'entrée pour vous. Vous pouvez également définir @ref{572,,PyOS_ReadlineFunctionPointer()} pour pointer vers votre fonction d'entrée personnalisée. Voir @code{Modules/readline.c} et @code{Parser/myreadline.c} pour plus de conseils.

@node Comment puis-je trouver les symboles g++ indéfinis __builtin_new ou __pure_virtual ?,Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python p ex en utilisant l'héritage ?,Comment distinguer une « entrée incomplète » incomplete input d'une « entrée invalide » invalid input ?,FAQ extension/intégration
@anchor{faq/extending how-do-i-find-undefined-g-symbols-builtin-new-or-pure-virtual}@anchor{5007}
@subsection Comment puis-je trouver les symboles g++ indéfinis @code{__builtin_new} ou @code{__pure_virtual} ?


Pour charger dynamiquement les modules d'extension g++, vous devez recompiler Python, effectuer l'édition de liens en utilisant g++ (modifiez `LINKCC' dans le `Python Modules Makefile'), et effectuer l'édition de liens de votre module d'extension avec g++ (par exemple, @code{g++ -shared -o mymodule.so mymodule.o}).

@node Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python p ex en utilisant l'héritage ?,,Comment puis-je trouver les symboles g++ indéfinis __builtin_new ou __pure_virtual ?,FAQ extension/intégration
@anchor{faq/extending can-i-create-an-object-class-with-some-methods-implemented-in-c-and-others-in-python-e-g-through-inheritance}@anchor{5008}
@subsection Puis-je créer une classe d'objets avec certaines méthodes implémentées en C et d'autres en Python (p. ex. en utilisant l'héritage) ?


Oui, vous pouvez hériter de classes intégrées telles que @ref{254,,int}, @ref{5fc,,list}, @ref{253,,dict}, etc.

The Boost Python Library (BPL, @indicateurl{https://www.boost.org/libs/python/doc/index.html})
provides a way of doing this from C++ (i.e. you can inherit from an extension
class written in C++ using the BPL).

@node FAQ Python et Windows,FAQ interface graphique,FAQ extension/intégration,Questions fréquemment posées sur Python
@anchor{faq/windows doc}@anchor{5009}@anchor{faq/windows python-on-windows-faq}@anchor{500a}@anchor{faq/windows windows-faq}@anchor{500b}
@section FAQ : Python et Windows



@c XXX need review for Python 3.
@c XXX need review for Windows Vista/Seven?

@menu
* Comment exécuter un programme Python sous Windows ?:: 
* Comment rendre des scripts Python exécutables ?:: 
* Pourquoi Python met-il du temps à démarrer ?:: 
* Comment construire un exécutable depuis un script Python ?:: 
* Est-ce qu'un fichier *.pyd est la même chose qu'une DLL ?: Est-ce qu'un fichier * pyd est la même chose qu'une DLL ?. 
* Comment puis-je intégrer Python dans une application Windows ?:: 
* Comment empêcher mon éditeur d'utiliser des tabulations dans mes fichiers Python ?:: 
* Comment puis-je vérifier de manière non bloquante qu'une touche a été pressée ?:: 
* Comment résoudre l'erreur « api-ms-win-crt-runtime-l1-1-0.dll manquante » ?: Comment résoudre l'erreur « api-ms-win-crt-runtime-l1-1-0 dll manquante » ?. 

@end menu

@node Comment exécuter un programme Python sous Windows ?,Comment rendre des scripts Python exécutables ?,,FAQ Python et Windows
@anchor{faq/windows faq-run-program-under-windows}@anchor{500c}@anchor{faq/windows how-do-i-run-a-python-program-under-windows}@anchor{500d}
@subsection Comment exécuter un programme Python sous Windows ?


Ce n'est pas forcément une question simple. Si vous êtes déjà familier avec le lancement de programmes depuis la ligne de commande de Windows alors tout semblera évident ; sinon, vous pourriez avoir besoin d'être un peu guidé.

À moins que vous n'utilisiez une sorte d'environnement de développement, vous finirez par `taper' des commandes Windows dans ce qui est appelé une « invite de commande Windows ». En général vous pouvez ouvrir un telle fenêtre depuis votre barre de recherche en cherchant @code{cmd}. Vous devriez être capable de reconnaître quand vous avez lancé une telle fenêtre parce que vous verrez une « invite de commande » Windows, qui en en général ressemble à ça :

@example
C:\>
@end example

La lettre peut être différente, et il peut y avoir d'autres choses à la suite, alors il se peut que ça ressemble également à ça :

@example
D:\YourName\Projects\Python>
@end example

selon la configuration de votre ordinateur et ce que vous avez récemment fait avec. Une fois que vous avez ouvert cette fenêtre, vous êtes bien partis pour pouvoir lancer des programmes Python.

Retenez que vos scripts Python doivent être traités par un autre programme appelé "l’interpréteur" Python. L’interpréteur lit votre script, le compile en `bytecode', et exécute le `bytecode' pour faire tourner votre programme. Alors, comment faire pour donner votre code Python à l'interpréteur ?

Tout d'abord, vous devez vous assurer que votre fenêtre d'invite de commande reconnaît le mot "python" comme une instruction pour démarrer l'interpréteur. Si vous avez ouvert une invite de commande, entrez la commande @code{py}, puis appuyez sur entrée :

@example
C:\Users\YourName> py
@end example

Vous devez voir quelque chose comme ça :

@example
Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
@end example

Vous avez lancé l'interpréteur dans son "mode interactif". Cela signifie que vous pouvez entrer des instructions ou des expressions Python de manière interactive pour qu'elles soient exécutées. Il s'agit là d'une des plus puissantes fonctionnalités de Python. Vous pouvez le vérifier en entrant quelques commandes de votre choix et en regardant le résultat :

@example
>>> print("Hello")
Hello
>>> "Hello" * 3
'HelloHelloHello'
@end example

Beaucoup de gens utilisent le mode interactif comme une calculatrice pratique mais néanmoins hautement programmable. Lorsque vous souhaitez mettre fin à votre session Python interactive, appelez la fonction @ref{2112,,exit()} ou maintenez la touche @code{Ctrl} enfoncée pendant que vous entrez un @code{Z}, puis appuyez sur la touche "@code{Enter}" pour revenir à votre invite de commande Windows.

Peut-être avez-vous remarqué une nouvelle entrée dans votre menu Démarrer telle que Démarrer ‣ Programmes ‣ Python 3.x ‣ Python (ligne de commande) qui a pour résultat que vous voyez l'invite @code{>>>} dans une nouvelle fenêtre.  Si oui, la fenêtre va disparaître quand vous appellerez la fonction @ref{2112,,exit()} ou entrez le caractère @code{Ctrl-Z} ; Windows exécute une commande "python" dans la fenêtre et ferme celle-ci lorsque vous fermez l'interpréteur.

Maintenant que nous savons que la commande @code{py} est reconnue, vous pouvez lui donner votre script Python. Vous devez donner le chemin absolu ou relatif du script Python. Disons que votre script Python est situé sur votre bureau et est nommé @code{hello.py}, et votre invite de commande est bien ouvert dans votre répertoire d’accueil, alors vous voyez quelque chose comme :

@example
C:\Users\YourName>
@end example

Alors maintenant, vous demanderez à la commande @code{py} de donner votre script à Python en tapant @code{py} suivi de votre chemin de script :

@example
C:\Users\YourName> py Desktop\hello.py
hello
@end example

@node Comment rendre des scripts Python exécutables ?,Pourquoi Python met-il du temps à démarrer ?,Comment exécuter un programme Python sous Windows ?,FAQ Python et Windows
@anchor{faq/windows how-do-i-make-python-scripts-executable}@anchor{500e}
@subsection Comment rendre des scripts Python exécutables ?


Sous Windows, l'installateur Python associe l'extension `.py' avec un type de fichier (Python.File) et une commande qui lance l’interpréteur (@code{D:\Program Files\Python\python.exe "%1" %*}). Cela suffit pour pouvoir exécuter les scripts Python depuis la ligne de commande en saisissant `foo.py'. Si vous souhaitez pouvoir exécuter les scripts en saisissant simplement `foo' sans l’extension, vous devez ajouter `.py' au paramètre d’environnement PATHEXT.

@node Pourquoi Python met-il du temps à démarrer ?,Comment construire un exécutable depuis un script Python ?,Comment rendre des scripts Python exécutables ?,FAQ Python et Windows
@anchor{faq/windows why-does-python-sometimes-take-so-long-to-start}@anchor{500f}
@subsection Pourquoi Python met-il du temps à démarrer ?


Normalement, sous Windows, Python se lance très rapidement, mais parfois des rapports d'erreurs indiquent que Python commence soudain à prendre beaucoup de temps pour démarrer. C'est d'autant plus intrigant que Python fonctionne correctement avec d'autres Windows configurés de façon similaire.

Le problème peut venir d'un antivirus mal configuré. Certains antivirus sont connus pour doubler le temps de démarrage lorsqu'ils sont configurés pour surveiller toutes les lectures du système de fichiers. Essayez de regarder si les antivirus des deux machines sont bien paramétrés à l'identique. `McAfee' est particulièrement problématique lorsqu'il est paramétré pour surveiller toutes les lectures du système de fichiers.

@node Comment construire un exécutable depuis un script Python ?,Est-ce qu'un fichier * pyd est la même chose qu'une DLL ?,Pourquoi Python met-il du temps à démarrer ?,FAQ Python et Windows
@anchor{faq/windows how-do-i-make-an-executable-from-a-python-script}@anchor{5010}
@subsection Comment construire un exécutable depuis un script Python ?


Voir @ref{4f68,,Comment créer un binaire autonome à partir d'un script Python ?} pour une liste d'outils qui créent des exécutables.

@node Est-ce qu'un fichier * pyd est la même chose qu'une DLL ?,Comment puis-je intégrer Python dans une application Windows ?,Comment construire un exécutable depuis un script Python ?,FAQ Python et Windows
@anchor{faq/windows is-a-pyd-file-the-same-as-a-dll}@anchor{5011}
@subsection Est-ce qu'un fichier @code{*.pyd} est la même chose qu'une DLL ?


Oui, les fichiers `.pyd' sont des fichiers `dll', mais il y a quelques différences.  Si vous avez une `DLL' @code{foo.pyd}, celle-ci doit posséder une fonction @code{PyInit_foo()}.  Vous pouvez alors écrire en Python « `import foo' » et Python recherchera le fichier `foo.pyd' (ainsi que `foo.py' et `foo.pyc'); s'il le trouve, il tentera d'appeler @code{PyInit_foo()} pour l'initialiser.  Ne liez pas votre `.exe' avec `foo.lib' car dans ce cas Windows aura besoin de la DLL.

Notez que le chemin de recherche pour `foo.pyd' est `PYTHONPATH', il est différent de celui qu'utilise Windows pour rechercher `foo.dll'.  De plus, `foo.pyd' n'a pas besoin d'être présent pour que votre programme s'exécute alors que si vous avez lié votre programme avec une `dll' celle-ci est requise.  Bien sûr `foo.pyd' est nécessaire si vous écrivez @code{import foo}.  Dans une `DLL' le lien est déclaré dans le code source avec @code{__declspec(dllexport)}. Dans un `.pyd' la liaison est définie dans une liste de fonctions disponibles.

@node Comment puis-je intégrer Python dans une application Windows ?,Comment empêcher mon éditeur d'utiliser des tabulations dans mes fichiers Python ?,Est-ce qu'un fichier * pyd est la même chose qu'une DLL ?,FAQ Python et Windows
@anchor{faq/windows how-can-i-embed-python-into-a-windows-application}@anchor{5012}
@subsection Comment puis-je intégrer Python dans une application Windows ?


L'intégration de l'interpréteur Python dans une application Windows peut se résumer comme suit :


@enumerate 

@item 
Ne compilez `pas' Python directement dans votre fichier `.exe'.  Sous Windows, Python doit être une DLL pour pouvoir importer des modules qui sont eux-mêmes des DLL (ceci constitue une information de première importance non documentée). Au lieu de cela faites un lien vers @code{python`NN'.dll} qui est généralement placé dans @code{C:\Windows\System}.  `NN' étant la version Python, par exemple « 33 » pour Python 3.3.

Vous pouvez créer un lien vers Python de deux manières différentes.  Un lien au moment du chargement signifie pointer vers @code{python`NN'.lib}, tandis qu'un lien au moment de l'exécution signifie pointer vers @code{python`NN'.dll}.  (Note générale : @code{python`NN'.lib} est le soi-disant « `import lib' » correspondant à @code{python`NN'.dll}.  Il définit simplement des  liens symboliques pour l'éditeur de liens.)

La liaison en temps réel simplifie grandement les options de liaison ; tout se passe au moment de l'exécution.  Votre code doit charger @code{python`NN'.dll} en utilisant la routine Windows @code{LoadLibraryEx()}.  Le code doit aussi utiliser des routines d'accès et des données dans @code{python`NN'.dll} (c'est-à-dire les API C de Python) en utilisant des pointeurs obtenus par la routine Windows @code{GetProcAddress()}.  Les macros peuvent rendre l'utilisation de ces pointeurs transparente à tout code C qui appelle des routines dans l'API C de Python.

@c XXX what about static linking?

@item 
Si vous utilisez SWIG, il est facile de créer un « module d'extension » Python qui rendra les données et les méthodes de l'application disponibles pour Python.  SWIG s'occupera de tous les détails ennuyeux pour vous.  Le résultat est du code C que vous liez `dans' votre `fichier.exe' (!) Vous n'avez `pas' besoin de créer un fichier DLL, et cela simplifie également la liaison.

@item 
SWIG va créer une fonction d'initialisation (fonction en C) dont le nom dépend du nom du module d'extension.  Par exemple, si le nom du module est `leo', la fonction `init' sera appelée `initleo()'.  Si vous utilisez des classes `shadow' SWIG, comme vous le devriez, la fonction `init' sera appelée `initleoc()'.  Ceci initialise une classe auxiliaire invisible utilisée par la classe `shadow'.

La raison pour laquelle vous pouvez lier le code C à l'étape 2 dans votre `fichier.exe' est que l'appel de la fonction d'initialisation équivaut à importer le module dans Python ! (C'est le deuxième fait clé non documenté.)

@item 
En bref, vous pouvez utiliser le code suivant pour initialiser l'interpréteur Python avec votre module d'extension.

@example
#include <Python.h>
...
Py_Initialize();  // Initialize Python.
initmyAppc();  // Initialize (import) the helper class.
PyRun_SimpleString("import myApp");  // Import the shadow class.
@end example

@item 
Il y a deux problèmes avec l'API C de Python qui apparaîtront si vous utilisez un compilateur autre que MSVC, le compilateur utilisé pour construire `pythonNN.dll'.

Problème 1 : Les fonctions dites de « Très Haut Niveau » qui prennent les arguments @code{FILE *} ne fonctionneront pas dans un environnement multi-compilateur car chaque compilateur aura une notion différente de @code{struct FILE}.  Du point de vue de l'implémentation, il s'agit de fonctions de très bas niveau.

Problème 2 : SWIG génère le code suivant lors de la génération `d'encapsuleurs' pour annuler les fonctions :

@example
Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;
@end example

Hélas, `Py_None' est une macro qui se développe en référence à une structure de données complexe appelée `_Py_NoneStruct' dans `pythonNN.dll'.  Encore une fois, ce code échouera dans un environnement multi-compilateur.  Remplacez ce code par :

@example
return Py_BuildValue("");
@end example

Il est possible d'utiliser la commande @code{%typemap} de SWIG pour effectuer le changement automatiquement, bien que je n'ai pas réussi à le faire fonctionner (je suis un débutant complet avec SWIG).

@item 
Utiliser un script shell Python pour créer une fenêtre d'interpréteur Python depuis votre application Windows n'est pas une bonne idée ; la fenêtre résultante sera indépendante du système de fenêtrage de votre application.  Vous (ou la classe `wxPythonWindow') devriez plutôt créer une fenêtre d'interpréteur « native ». Il est facile de connecter cette fenêtre à l'interpréteur Python. Vous pouvez rediriger l'entrée/sortie de Python vers `n'importe quel' objet qui supporte la lecture et l'écriture, donc tout ce dont vous avez besoin est un objet Python (défini dans votre module d'extension) qui contient les méthodes `read()' et `write()'.
@end enumerate

@node Comment empêcher mon éditeur d'utiliser des tabulations dans mes fichiers Python ?,Comment puis-je vérifier de manière non bloquante qu'une touche a été pressée ?,Comment puis-je intégrer Python dans une application Windows ?,FAQ Python et Windows
@anchor{faq/windows how-do-i-keep-editors-from-inserting-tabs-into-my-python-source}@anchor{5013}
@subsection Comment empêcher mon éditeur d'utiliser des tabulations dans mes fichiers Python ?


La FAQ ne recommande pas l'utilisation des indentations et le guide stylistique de Python, la 
@geindex Python Enhancement Proposals; PEP 8
PEP 8@footnote{https://peps.python.org/pep-0008/}, recommande l'utilisation de 4 espaces dans les codes Python. C'est aussi le comportement par défaut d'Emacs avec Python.

Quel que soit votre éditeur, mélanger des tabulations et des espaces est une mauvaise idée. `Visual C++', par exemple, peut être facilement configuré pour utiliser des espaces : allez dans Tools ‣ Options ‣ Tabs et pour le type de fichier par défaut, vous devez mettre `Tab size' et `Indent size' à 4, puis sélectionner `Insert spaces'.

Python va lever @ref{792,,IndentationError} ou @ref{52e,,TabError} si un mélange de tabulation et d’indentation pose problème en début de ligne. Vous pouvez aussi utiliser le module  @ref{dc,,tabnanny} pour détecter ces erreurs.

@node Comment puis-je vérifier de manière non bloquante qu'une touche a été pressée ?,Comment résoudre l'erreur « api-ms-win-crt-runtime-l1-1-0 dll manquante » ?,Comment empêcher mon éditeur d'utiliser des tabulations dans mes fichiers Python ?,FAQ Python et Windows
@anchor{faq/windows how-do-i-check-for-a-keypress-without-blocking}@anchor{5014}
@subsection Comment puis-je vérifier de manière non bloquante qu'une touche a été pressée ?


Utilisez le module @ref{92,,msvcrt}. C'est une extension standard spécifique à Windows, qui définit une fonction @code{kbhit()} qui vérifie si une pression de touche s'est produite, et @code{getch()} qui récupère le caractère sans l'afficher.

@node Comment résoudre l'erreur « api-ms-win-crt-runtime-l1-1-0 dll manquante » ?,,Comment puis-je vérifier de manière non bloquante qu'une touche a été pressée ?,FAQ Python et Windows
@anchor{faq/windows how-do-i-solve-the-missing-api-ms-win-crt-runtime-l1-1-0-dll-error}@anchor{5015}
@subsection Comment résoudre l'erreur « @code{api-ms-win-crt-runtime-l1-1-0.dll} manquante » ?


Ce problème peut se produire avec Python 3.5 et les versions ultérieures lorsque vous utilisez Windows 8.1 ou une version antérieure sans que toutes les mises à jour aient été installées. Assurez-vous d'abord que votre système d'exploitation est pris en charge et qu'il est à jour, et si cela ne résout pas le problème, visitez la page d’assistance de Microsoft@footnote{https://support.microsoft.com/en-us/help/3118401/} pour obtenir des conseils sur l'installation manuelle de la mise à jour du `C Runtime'.

@node FAQ interface graphique,FAQ "Pourquoi Python est installé sur mon ordinateur ?",FAQ Python et Windows,Questions fréquemment posées sur Python
@anchor{faq/gui doc}@anchor{5016}@anchor{faq/gui graphic-user-interface-faq}@anchor{5017}
@section FAQ interface graphique



@c XXX need review for Python 3.

@menu
* Questions générales sur l'interface graphique:: 
* Quelles boîtes à outils IUG existent pour Python ?:: 
* Questions à propos de Tkinter:: 

@end menu

@node Questions générales sur l'interface graphique,Quelles boîtes à outils IUG existent pour Python ?,,FAQ interface graphique
@anchor{faq/gui general-gui-questions}@anchor{5018}
@subsection Questions générales sur l'interface graphique


@node Quelles boîtes à outils IUG existent pour Python ?,Questions à propos de Tkinter,Questions générales sur l'interface graphique,FAQ interface graphique
@anchor{faq/gui what-gui-toolkits-exist-for-python}@anchor{5019}
@subsection Quelles boîtes à outils IUG existent pour Python ?


Les versions standards de Python incluent une interface orientée objet pour le jeu d'objets graphiques `Tcl/Tk', appelée @ref{3d79,,tkinter}.  C'est probablement la plus facile à installer (puisqu'elle est incluse avec la plupart des distributions binaires@footnote{https://www.python.org/downloads/} de Python) et à utiliser. Pour plus d'informations sur `Tk', y compris les liens vers les sources, voir la page d'accueil Tcl/Tk@footnote{https://www.tcl.tk}.  `Tcl/Tk' est entièrement portable sur les plates-formes macOS, Windows et Unix.

D'autres outils existent. Le choix doit dépendre notamment de la ou des plateformes que vous visez. Sur le Wiki Python se trouvent des listes de bibliothèques graphiques multiplateformes@footnote{https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks} et pour une seule plate-forme@footnote{https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks}.

@node Questions à propos de Tkinter,,Quelles boîtes à outils IUG existent pour Python ?,FAQ interface graphique
@anchor{faq/gui tkinter-questions}@anchor{501a}
@subsection Questions à propos de `Tkinter'


@menu
* Comment puis-je geler (freezer) les applications Tkinter ?: Comment puis-je geler freezer les applications Tkinter ?. 
* Puis-je modifier des événements Tk pendant l'écoute des E/S ?:: 
* Je n'arrive pas à faire fonctionner les raccourcis clavier dans Tkinter ; pourquoi ?: Je n'arrive pas à faire fonctionner les raccourcis clavier dans Tkinter pourquoi ?. 

@end menu

@node Comment puis-je geler freezer les applications Tkinter ?,Puis-je modifier des événements Tk pendant l'écoute des E/S ?,,Questions à propos de Tkinter
@anchor{faq/gui how-do-i-freeze-tkinter-applications}@anchor{501b}
@subsubsection Comment puis-je geler (`freezer') les applications `Tkinter' ?


`Freeze' est un outil pour créer des applications autonomes.  Lors du `freezage' des applications Tkinter, les applications ne seront pas vraiment autonomes, car l'application aura toujours besoin des bibliothèques Tcl et Tk.

One solution is to ship the application with the Tcl and Tk libraries, and point
to them at run-time using the @code{TCL_LIBRARY} and @code{TK_LIBRARY}
environment variables.

Various third-party freeze libraries such as py2exe and cx_Freeze have
handling for Tkinter applications built-in.

@node Puis-je modifier des événements Tk pendant l'écoute des E/S ?,Je n'arrive pas à faire fonctionner les raccourcis clavier dans Tkinter pourquoi ?,Comment puis-je geler freezer les applications Tkinter ?,Questions à propos de Tkinter
@anchor{faq/gui can-i-have-tk-events-handled-while-waiting-for-i-o}@anchor{501c}
@subsubsection Puis-je modifier des événements `Tk' pendant l'écoute des `E/S' ?


On platforms other than Windows, yes, and you don't even
need threads!  But you'll have to restructure your I/O
code a bit.  Tk has the equivalent of Xt's @code{XtAddInput()} call, which allows you
to register a callback function which will be called from the Tk mainloop when
I/O is possible on a file descriptor.  See @ref{3d96,,Gestionnaires de fichiers}.

@node Je n'arrive pas à faire fonctionner les raccourcis clavier dans Tkinter pourquoi ?,,Puis-je modifier des événements Tk pendant l'écoute des E/S ?,Questions à propos de Tkinter
@anchor{faq/gui i-can-t-get-key-bindings-to-work-in-tkinter-why}@anchor{501d}
@subsubsection Je n'arrive pas à faire fonctionner les raccourcis clavier dans `Tkinter' : pourquoi ?


An often-heard complaint is that event handlers @ref{3d91,,bound}
to events with the @code{bind()} method
don't get handled even when the appropriate key is pressed.

La cause la plus fréquente est que l'objet graphique auquel s'applique la liaison n'a pas de « focus clavier ».  Consultez la documentation `Tk' pour la commande `focus'. Habituellement, un objet graphique reçoit le focus du clavier en cliquant dessus (mais pas pour les étiquettes ; voir l'option `takefocus').

@node FAQ "Pourquoi Python est installé sur mon ordinateur ?",,FAQ interface graphique,Questions fréquemment posées sur Python
@anchor{faq/installed doc}@anchor{501e}@anchor{faq/installed why-is-python-installed-on-my-computer-faq}@anchor{501f}
@section FAQ "Pourquoi Python est installé sur mon ordinateur ?"


@menu
* Qu'est-ce que Python ?: Qu'est-ce que Python ?<2>. 
* Pourquoi Python est installé sur ma machine ?:: 
* Puis-je supprimer Python ?:: 

@end menu

@node Qu'est-ce que Python ?<2>,Pourquoi Python est installé sur ma machine ?,,FAQ "Pourquoi Python est installé sur mon ordinateur ?"
@anchor{faq/installed what-is-python}@anchor{5020}
@subsection Qu'est-ce que Python ?


Python est un langage de programmation. Il est utilisé dans de nombreuses applications. Souvent utilisé dans les lycées et universités comme langage d'introduction à la programmation pour sa simplicité d'apprentissage, il est aussi utilisé par des développeurs professionnels appartenant à des grands groupes comme Google, la NASA, Lucasfilm etc.

Si vous voulez en apprendre plus sur Python, vous pouvez commencer par le Guide des Débutants pour Python@footnote{https://wiki.python.org/moin/BeginnersGuide}.

@node Pourquoi Python est installé sur ma machine ?,Puis-je supprimer Python ?,Qu'est-ce que Python ?<2>,FAQ "Pourquoi Python est installé sur mon ordinateur ?"
@anchor{faq/installed why-is-python-installed-on-my-machine}@anchor{5021}
@subsection Pourquoi Python est installé sur ma machine ?


Si Python est installé sur votre système mais que vous ne vous rappelez pas l'avoir installé, il y a plusieurs raisons possibles à sa présence.


@itemize *

@item 
Peut être qu'un autre utilisateur de l'ordinateur voulait apprendre la programmation et l'a installé, dans ce cas vous allez devoir trouver qui a utilisé votre machine et aurait pu l'installer.

@item 
Une application tierce installée sur votre machine écrite en Python installera Python. Il existe de nombreuses applications de ce type, allant de programme avec interface graphique, jusqu'aux scripts d'administration, en passant par les serveurs.

@item 
Certaines machines fonctionnant avec le système d'exploitation Windows possèdent une installation de Python. À ce jour, les ordinateurs des marques Hewlett-Packard et Compaq incluent nativement Python. Certains outils d'administration de ces marques sont écrits en Python.

@item 
Python est installé par défaut sur de nombreux systèmes compatibles Unix, comme macOS et certaines distributions Linux.
@end itemize

@node Puis-je supprimer Python ?,,Pourquoi Python est installé sur ma machine ?,FAQ "Pourquoi Python est installé sur mon ordinateur ?"
@anchor{faq/installed can-i-delete-python}@anchor{5022}
@subsection Puis-je supprimer Python ?


Cela dépend de l'origine de Python.

Si Python a été installé délibérément par une personne tierce ou vous même, vous pouvez le supprimer sans causer de dommage. Sous Windows, vous pouvez simplement utiliser l'icône d'Ajout / Suppression de programmes du Panneau de configuration.

Si Python a été installé par une application tierce, Python peut être désinstallé, l'application l'ayant installé cessera alors de fonctionner. Dans ce cas, désinstallez l'application en utilisant son outil de désinstallation est plus indiqué que supprimer Python.

Si Python a été installé avec votre système d'exploitation, le supprimer n'est pas recommandé. Si vous choisissez tout de même de le supprimer, tous les outils écrits en python cesseront alors de fonctionner, certains outils pouvant être importants. La réinstallation intégrale du système pourrait être nécessaire pour résoudre les problèmes suite à la désinstallation de Python.

@node Deprecations,Glossaire,Questions fréquemment posées sur Python,Top
@anchor{deprecations/index doc}@anchor{5023}@anchor{deprecations/index deprecations}@anchor{5024}
@chapter Deprecations


@menu
* Pending Removal in Python 3.14: Pending Removal in Python 3 14<5>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<5>. 
* Pending removal in Python 3.16: Pending removal in Python 3 16<3>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<5>. 
* C API Deprecations:: 

@end menu

@node Pending Removal in Python 3 14<5>,Pending Removal in Python 3 15<5>,,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-14}@anchor{5025}
@section Pending Removal in Python 3.14



@itemize *

@item 
@ref{6,,argparse}: The `type', `choices', and `metavar' parameters
of @code{argparse.BooleanOptionalAction} are deprecated
and will be removed in 3.14.
(Contributed by Nikita Sobolev in gh-92248@footnote{https://github.com/python/cpython/issues/92248}.)

@item 
@ref{8,,ast}: The following features have been deprecated in documentation
since Python 3.8, now cause a @ref{1a3,,DeprecationWarning} to be emitted at
runtime when they are accessed or used, and will be removed in Python 3.14:


@itemize *

@item 
@code{ast.Num}

@item 
@code{ast.Str}

@item 
@code{ast.Bytes}

@item 
@code{ast.NameConstant}

@item 
@code{ast.Ellipsis}
@end itemize

Use @ref{2b6,,ast.Constant} instead.
(Contributed by Serhiy Storchaka in gh-90953@footnote{https://github.com/python/cpython/issues/90953}.)

@item 
@ref{a,,asyncio}:


@itemize *

@item 
The child watcher classes @ref{2b7,,MultiLoopChildWatcher},
@ref{2b8,,FastChildWatcher}, @ref{2b9,,AbstractChildWatcher}
and @ref{2ba,,SafeChildWatcher} are deprecated and
will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
@ref{2bb,,asyncio.set_child_watcher()}, @ref{2bc,,asyncio.get_child_watcher()},
@ref{2bd,,asyncio.AbstractEventLoopPolicy.set_child_watcher()} and
@ref{2be,,asyncio.AbstractEventLoopPolicy.get_child_watcher()} are deprecated
and will be removed in Python 3.14.
(Contributed by Kumar Aditya in gh-94597@footnote{https://github.com/python/cpython/issues/94597}.)

@item 
The @ref{2bf,,get_event_loop()} method of the
default event loop policy now emits a @ref{1a3,,DeprecationWarning} if there
is no current event loop set and it decides to create one.
(Contributed by Serhiy Storchaka and Guido van Rossum in gh-100160@footnote{https://github.com/python/cpython/issues/100160}.)
@end itemize

@item 
@ref{1e,,collections.abc}: Deprecated @ref{2c0,,ByteString}.
Prefer @code{Sequence} or @ref{2c1,,Buffer}.
For use in typing, prefer a union, like @code{bytes | bytearray},
or @ref{2c1,,collections.abc.Buffer}.
(Contributed by Shantanu Jain in gh-91896@footnote{https://github.com/python/cpython/issues/91896}.)

@item 
@ref{3b,,email}: Deprecated the `isdst' parameter in @ref{2c2,,email.utils.localtime()}.
(Contributed by Alan Williams in gh-72346@footnote{https://github.com/python/cpython/issues/72346}.)

@item 
@ref{77,,importlib.abc} deprecated classes:


@itemize *

@item 
@code{importlib.abc.ResourceReader}

@item 
@code{importlib.abc.Traversable}

@item 
@code{importlib.abc.TraversableResources}
@end itemize

Use @ref{7b,,importlib.resources.abc} classes instead:


@itemize *

@item 
@ref{1f0,,importlib.resources.abc.Traversable}

@item 
@ref{2c3,,importlib.resources.abc.TraversableResources}
@end itemize

(Contributed by Jason R. Coombs and Hugo van Kemenade in gh-93963@footnote{https://github.com/python/cpython/issues/93963}.)

@item 
@ref{80,,itertools} had undocumented, inefficient, historically buggy,
and inconsistent support for copy, deepcopy, and pickle operations.
This will be removed in 3.14 for a significant reduction in code
volume and maintenance burden.
(Contributed by Raymond Hettinger in gh-101588@footnote{https://github.com/python/cpython/issues/101588}.)

@item 
@ref{93,,multiprocessing}: The default start method will change to a safer one on
Linux, BSDs, and other non-macOS POSIX platforms where @code{'fork'} is currently
the default (gh-84559@footnote{https://github.com/python/cpython/issues/84559}). Adding a runtime warning about this was deemed too
disruptive as the majority of code is not expected to care. Use the
@ref{2c4,,get_context()} or
@ref{2c5,,set_start_method()} APIs to explicitly specify when
your code `requires' @code{'fork'}.  See @ref{2c6,,Contextes et méthodes de démarrage}.

@item 
@ref{a3,,pathlib}: @ref{2c7,,is_relative_to()} and
@ref{2c8,,relative_to()}: passing additional arguments is
deprecated.

@item 
@ref{a8,,pkgutil}: @ref{2c9,,find_loader()} and @ref{2ca,,get_loader()}
now raise @ref{1a3,,DeprecationWarning};
use @ref{2cb,,importlib.util.find_spec()} instead.
(Contributed by Nikita Sobolev in gh-97850@footnote{https://github.com/python/cpython/issues/97850}.)

@item 
@ref{b0,,pty}:


@itemize *

@item 
@code{master_open()}: use @ref{2cc,,pty.openpty()}.

@item 
@code{slave_open()}: use @ref{2cc,,pty.openpty()}.
@end itemize

@item 
@ref{ce,,sqlite3}:


@itemize *

@item 
@ref{2cd,,version} and @ref{2ce,,version_info}.

@item 
@ref{2cf,,execute()} and @ref{2d0,,executemany()}
if @ref{2d1,,named placeholders} are used and
`parameters' is a sequence instead of a @ref{253,,dict}.
@end itemize

@item 
@ref{103,,typing}: @ref{2d2,,ByteString}, deprecated since Python 3.9,
now causes a @ref{1a3,,DeprecationWarning} to be emitted when it is used.

@item 
@ref{107,,urllib}:
@code{urllib.parse.Quoter} is deprecated: it was not intended to be a
public API.
(Contributed by Gregory P. Smith in gh-88168@footnote{https://github.com/python/cpython/issues/88168}.)
@end itemize

@node Pending Removal in Python 3 15<5>,Pending removal in Python 3 16<3>,Pending Removal in Python 3 14<5>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-15}@anchor{5026}
@section Pending Removal in Python 3.15



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2d4,,__cached__} on a module while
failing to set @ref{2d5,,__spec__.cached}
is deprecated. In Python 3.15, @code{__cached__} will cease to be set or
take into consideration by the import system or standard library. (gh-97879@footnote{https://github.com/python/cpython/issues/97879})

@item 
Setting @ref{2d6,,__package__} on a module while
failing to set @ref{2d7,,__spec__.parent}
is deprecated. In Python 3.15, @code{__package__} will cease to be set or
take into consideration by the import system or standard library. (gh-97879@footnote{https://github.com/python/cpython/issues/97879})
@end itemize

@item 
@ref{2a,,ctypes}:


@itemize *

@item 
The undocumented @code{ctypes.SetPointerType()} function
has been deprecated since Python 3.13.
@end itemize

@item 
@ref{71,,http.server}:


@itemize *

@item 
The obsolete and rarely used @ref{29e,,CGIHTTPRequestHandler}
has been deprecated since Python 3.13.
No direct replacement exists.
`Anything' is better than CGI to interface
a web server with a request handler.

@item 
The @code{--cgi} flag to the @code{python -m http.server}
command-line interface has been deprecated since Python 3.13.
@end itemize

@item 
@ref{85,,locale}:


@itemize *

@item 
The @ref{2d8,,getdefaultlocale()} function
has been deprecated since Python 3.11.
Its removal was originally planned for Python 3.13 (gh-90817@footnote{https://github.com/python/cpython/issues/90817}),
but has been postponed to Python 3.15.
Use @ref{2d9,,getlocale()}, @ref{2da,,setlocale()},
and @ref{2db,,getencoding()} instead.
(Contributed by Hugo van Kemenade in gh-111187@footnote{https://github.com/python/cpython/issues/111187}.)
@end itemize

@item 
@ref{a3,,pathlib}:


@itemize *

@item 
@ref{2a3,,PurePath.is_reserved()}
has been deprecated since Python 3.13.
Use @ref{220,,os.path.isreserved()} to detect reserved paths on Windows.
@end itemize

@item 
@ref{a9,,platform}:


@itemize *

@item 
@ref{2a4,,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.
@end itemize

@item 
@ref{ec,,threading}:


@itemize *

@item 
@ref{2dc,,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.
@end itemize

@item 
@ref{102,,types}:


@itemize *

@item 
@ref{2dd,,types.CodeType}: Accessing @ref{2de,,co_lnotab} was
deprecated in 
@geindex Python Enhancement Proposals; PEP 626
PEP 626@footnote{https://peps.python.org/pep-0626/}
since 3.10 and was planned to be removed in 3.12,
but it only got a proper @ref{1a3,,DeprecationWarning} in 3.12.
May be removed in 3.15.
(Contributed by Nikita Sobolev in gh-101866@footnote{https://github.com/python/cpython/issues/101866}.)
@end itemize

@item 
@ref{103,,typing}:


@itemize *

@item 
The undocumented keyword argument syntax for creating
@ref{2ad,,NamedTuple} classes
(e.g. @code{Point = NamedTuple("Point", x=int, y=int)})
has been deprecated since Python 3.13.
Use the class-based syntax or the functional syntax instead.

@item 
The @ref{2ae,,typing.no_type_check_decorator()} decorator function
has been deprecated since Python 3.13.
After eight years in the @ref{103,,typing} module,
it has yet to be supported by any major type checker.
@end itemize

@item 
@ref{112,,wave}:


@itemize *

@item 
The @ref{2b1,,getmark()}, @code{setmark()},
and @ref{2b2,,getmarkers()} methods of
the @ref{2b3,,Wave_read} and @ref{2b4,,Wave_write} classes
have been deprecated since Python 3.13.
@end itemize
@end itemize

@node Pending removal in Python 3 16<3>,Pending Removal in Future Versions<5>,Pending Removal in Python 3 15<5>,Deprecations
@anchor{deprecations/index pending-removal-in-python-3-16}@anchor{5027}
@section Pending removal in Python 3.16



@itemize *

@item 
The import system:


@itemize *

@item 
Setting @ref{2e0,,__loader__} on a module while
failing to set @ref{2e1,,__spec__.loader}
is deprecated. In Python 3.16, @code{__loader__} will cease to be set or
taken into consideration by the import system or the standard library.
@end itemize

@item 
@ref{7,,array}:


@itemize *

@item 
The @code{'u'} format code (@code{wchar_t})
has been deprecated in documentation since Python 3.3
and at runtime since Python 3.13.
Use the @code{'w'} format code (@ref{298,,Py_UCS4})
for Unicode characters instead.
@end itemize

@item 
@ref{a,,asyncio}:


@itemize *

@item 
@code{asyncio.iscoroutinefunction()} is deprecated
and will be removed in Python 3.16,
use @ref{2e2,,inspect.iscoroutinefunction()} instead.
(Contributed by Jiahao Li and Kumar Aditya in gh-122875@footnote{https://github.com/python/cpython/issues/122875}.)
@end itemize

@item 
@ref{12,,builtins}:


@itemize *

@item 
Bitwise inversion on boolean types, @code{~True} or @code{~False}
has been deprecated since Python 3.12,
as it produces surprising and unintuitive results (@code{-2} and @code{-1}).
Use @code{not x} instead for the logical negation of a Boolean.
In the rare case that you need the bitwise inversion of
the underlying integer, convert to @code{int} explicitly (@code{~int(x)}).
@end itemize

@item 
@ref{c4,,shutil}:


@itemize *

@item 
The @code{ExecError} exception
has been deprecated since Python 3.14.
It has not been used by any function in @code{shutil} since Python 3.4,
and is now an alias of @ref{193,,RuntimeError}.
@end itemize

@item 
@ref{d7,,symtable}:


@itemize *

@item 
The @ref{2e3,,Class.get_methods} method
has been deprecated since Python 3.14.
@end itemize

@item 
@ref{d8,,sys}:


@itemize *

@item 
The @ref{2ab,,_enablelegacywindowsfsencoding()} function
has been deprecated since Python 3.13.
Use the 
@geindex PYTHONLEGACYWINDOWSFSENCODING
@geindex variable d'environnement; PYTHONLEGACYWINDOWSFSENCODING
@ref{2ac,,PYTHONLEGACYWINDOWSFSENCODING} environment variable instead.
@end itemize

@item 
@ref{dd,,tarfile}:


@itemize *

@item 
The undocumented and unused @code{TarFile.tarfile} attribute
has been deprecated since Python 3.13.
@end itemize
@end itemize

@node Pending Removal in Future Versions<5>,C API Deprecations,Pending removal in Python 3 16<3>,Deprecations
@anchor{deprecations/index pending-removal-in-future-versions}@anchor{5028}
@section Pending Removal in Future Versions


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


@itemize *

@item 
@ref{6,,argparse}: Nesting argument groups and nesting mutually exclusive
groups are deprecated.

@item 
@ref{7,,array}'s @code{'u'} format code (gh-57281@footnote{https://github.com/python/cpython/issues/57281})

@item 
@ref{12,,builtins}:


@itemize *

@item 
@code{bool(NotImplemented)}.

@item 
Generators: @code{throw(type, exc, tb)} and @code{athrow(type, exc, tb)}
signature is deprecated: use @code{throw(exc)} and @code{athrow(exc)} instead,
the single argument signature.

@item 
Currently Python accepts numeric literals immediately followed by keywords,
for example @code{0in x}, @code{1or x}, @code{0if 1else 2}.  It allows confusing and
ambiguous expressions like @code{[0x1for x in y]} (which can be interpreted as
@code{[0x1 for x in y]} or @code{[0x1f or x in y]}).  A syntax warning is raised
if the numeric literal is immediately followed by one of keywords
@ref{2e5,,and}, @ref{18a,,else}, @ref{2e6,,for}, @ref{2e7,,if},
@ref{2e8,,in}, @ref{2e9,,is} and @ref{2ea,,or}.  In a future release it
will be changed to a syntax error. (gh-87999@footnote{https://github.com/python/cpython/issues/87999})

@item 
Support for @code{__index__()} and @code{__int__()} method returning non-int type:
these methods will be required to return an instance of a strict subclass of
@ref{254,,int}.

@item 
Support for @code{__float__()} method returning a strict subclass of
@ref{2eb,,float}: these methods will be required to return an instance of
@ref{2eb,,float}.

@item 
Support for @code{__complex__()} method returning a strict subclass of
@ref{2ec,,complex}: these methods will be required to return an instance of
@ref{2ec,,complex}.

@item 
Delegation of @code{int()} to @code{__trunc__()} method.

@item 
Passing a complex number as the `real' or `imag' argument in the
@ref{2ec,,complex()} constructor is now deprecated; it should only be passed
as a single positional argument.
(Contributed by Serhiy Storchaka in gh-109218@footnote{https://github.com/python/cpython/issues/109218}.)
@end itemize

@item 
@ref{14,,calendar}: @code{calendar.January} and @code{calendar.February} constants are
deprecated and replaced by @ref{2ed,,calendar.JANUARY} and
@ref{2ee,,calendar.FEBRUARY}.
(Contributed by Prince Roshan in gh-103636@footnote{https://github.com/python/cpython/issues/103636}.)

@item 
@ref{2de,,codeobject.co_lnotab}: use the @ref{2ef,,codeobject.co_lines()} method
instead.

@item 
@ref{30,,datetime}:


@itemize *

@item 
@ref{2f0,,utcnow()}:
use @code{datetime.datetime.now(tz=datetime.UTC)}.

@item 
@ref{2f1,,utcfromtimestamp()}:
use @code{datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)}.
@end itemize

@item 
@ref{62,,gettext}: Plural value must be an integer.

@item 
@ref{76,,importlib}:


@itemize *

@item 
@code{load_module()} method: use @code{exec_module()} instead.

@item 
@ref{2f2,,cache_from_source()} `debug_override' parameter is
deprecated: use the `optimization' parameter instead.
@end itemize

@item 
@ref{79,,importlib.metadata}:


@itemize *

@item 
@code{EntryPoints} tuple interface.

@item 
Implicit @code{None} on return values.
@end itemize

@item 
@ref{86,,logging}: the @code{warn()} method has been deprecated
since Python 3.3, use @ref{2f3,,warning()} instead.

@item 
@ref{8a,,mailbox}: Use of StringIO input and text mode is deprecated, use
BytesIO and binary mode instead.

@item 
@ref{a0,,os}: Calling @ref{2f4,,os.register_at_fork()} in multi-threaded process.

@item 
@code{pydoc.ErrorDuringImport}: A tuple value for `exc_info' parameter is
deprecated, use an exception instance.

@item 
@ref{b8,,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 in gh-91760@footnote{https://github.com/python/cpython/issues/91760}.)

@item 
@code{sre_compile}, @code{sre_constants} and @code{sre_parse} modules.

@item 
@ref{c4,,shutil}: @ref{2f5,,rmtree()}'s `onerror' parameter is deprecated in
Python 3.12; use the `onexc' parameter instead.

@item 
@ref{cf,,ssl} options and protocols:


@itemize *

@item 
@ref{291,,ssl.SSLContext} without protocol argument is deprecated.

@item 
@ref{291,,ssl.SSLContext}: @ref{2f6,,set_npn_protocols()} and
@code{selected_npn_protocol()} are deprecated: use ALPN
instead.

@item 
@code{ssl.OP_NO_SSL*} options

@item 
@code{ssl.OP_NO_TLS*} options

@item 
@code{ssl.PROTOCOL_SSLv3}

@item 
@code{ssl.PROTOCOL_TLS}

@item 
@code{ssl.PROTOCOL_TLSv1}

@item 
@code{ssl.PROTOCOL_TLSv1_1}

@item 
@code{ssl.PROTOCOL_TLSv1_2}

@item 
@code{ssl.TLSVersion.SSLv3}

@item 
@code{ssl.TLSVersion.TLSv1}

@item 
@code{ssl.TLSVersion.TLSv1_1}
@end itemize

@item 
@ref{2f7,,sysconfig.is_python_build()} `check_home' parameter is deprecated and
ignored.

@item 
@ref{ec,,threading} methods:


@itemize *

@item 
@code{threading.Condition.notifyAll()}: use @ref{2f8,,notify_all()}.

@item 
@code{threading.Event.isSet()}: use @ref{2f9,,is_set()}.

@item 
@code{threading.Thread.isDaemon()}, @ref{2fa,,threading.Thread.setDaemon()}:
use @ref{2fb,,threading.Thread.daemon} attribute.

@item 
@code{threading.Thread.getName()}, @ref{2fc,,threading.Thread.setName()}:
use @ref{2fd,,threading.Thread.name} attribute.

@item 
@code{threading.currentThread()}: use @ref{2fe,,threading.current_thread()}.

@item 
@code{threading.activeCount()}: use @ref{2ff,,threading.active_count()}.
@end itemize

@item 
@ref{300,,typing.Text} (gh-92332@footnote{https://github.com/python/cpython/issues/92332}).

@item 
@ref{301,,unittest.IsolatedAsyncioTestCase}: it is deprecated to return a value
that is not @code{None} from a test case.

@item 
@ref{109,,urllib.parse} deprecated functions: @ref{302,,urlparse()} instead


@itemize *

@item 
@code{splitattr()}

@item 
@code{splithost()}

@item 
@code{splitnport()}

@item 
@code{splitpasswd()}

@item 
@code{splitport()}

@item 
@code{splitquery()}

@item 
@code{splittag()}

@item 
@code{splittype()}

@item 
@code{splituser()}

@item 
@code{splitvalue()}

@item 
@code{to_bytes()}
@end itemize

@item 
@ref{10a,,urllib.request}: @ref{303,,URLopener} and
@ref{304,,FancyURLopener} style of invoking requests is
deprecated. Use newer @ref{290,,urlopen()} functions and methods.

@item 
@ref{117,,wsgiref}: @code{SimpleHandler.stdout.write()} should not do partial
writes.

@item 
@ref{124,,xml.etree.ElementTree}: Testing the truth value of an
@ref{305,,Element} is deprecated. In a future release it
will always return @code{True}. Prefer explicit @code{len(elem)} or
@code{elem is not None} tests instead.

@item 
@ref{306,,zipimport.zipimporter.load_module()} is deprecated:
use @ref{307,,exec_module()} instead.
@end itemize

@node C API Deprecations,,Pending Removal in Future Versions<5>,Deprecations
@anchor{deprecations/index c-api-deprecations}@anchor{5029}
@section C API Deprecations


@menu
* Pending Removal in Python 3.14: Pending Removal in Python 3 14<6>. 
* Pending Removal in Python 3.15: Pending Removal in Python 3 15<6>. 
* Pending Removal in Future Versions: Pending Removal in Future Versions<6>. 

@end menu

@node Pending Removal in Python 3 14<6>,Pending Removal in Python 3 15<6>,,C API Deprecations
@anchor{deprecations/index id1}@anchor{502a}
@subsection Pending Removal in Python 3.14



@itemize *

@item 
The @code{ma_version_tag} field in @ref{3b8,,PyDictObject} for extension modules
(
@geindex Python Enhancement Proposals; PEP 699
PEP 699@footnote{https://peps.python.org/pep-0699/}; gh-101193@footnote{https://github.com/python/cpython/issues/101193}).

@item 
Creating @ref{3b9,,immutable types} with mutable
bases (gh-95388@footnote{https://github.com/python/cpython/issues/95388}).

@item 
Functions to configure Python's initialization, deprecated in Python 3.11:


@itemize *

@item 
@code{PySys_SetArgvEx()}:
Set @ref{3ba,,PyConfig.argv} instead.

@item 
@code{PySys_SetArgv()}:
Set @ref{3ba,,PyConfig.argv} instead.

@item 
@code{Py_SetProgramName()}:
Set @ref{3bb,,PyConfig.program_name} instead.

@item 
@code{Py_SetPythonHome()}:
Set @ref{3b2,,PyConfig.home} instead.
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.

@item 
Global configuration variables:


@itemize *

@item 
@ref{3bd,,Py_DebugFlag}:
Use @ref{3be,,PyConfig.parser_debug} instead.

@item 
@ref{3bf,,Py_VerboseFlag}:
Use @ref{3c0,,PyConfig.verbose} instead.

@item 
@ref{3c1,,Py_QuietFlag}:
Use @ref{3c2,,PyConfig.quiet} instead.

@item 
@ref{3c3,,Py_InteractiveFlag}:
Use @ref{3c4,,PyConfig.interactive} instead.

@item 
@ref{3c5,,Py_InspectFlag}:
Use @ref{3c6,,PyConfig.inspect} instead.

@item 
@ref{3c7,,Py_OptimizeFlag}:
Use @ref{3c8,,PyConfig.optimization_level} instead.

@item 
@ref{3c9,,Py_NoSiteFlag}:
Use @ref{3ca,,PyConfig.site_import} instead.

@item 
@ref{3cb,,Py_BytesWarningFlag}:
Use @ref{3cc,,PyConfig.bytes_warning} instead.

@item 
@ref{3cd,,Py_FrozenFlag}:
Use @ref{3ce,,PyConfig.pathconfig_warnings} instead.

@item 
@ref{3cf,,Py_IgnoreEnvironmentFlag}:
Use @ref{3d0,,PyConfig.use_environment} instead.

@item 
@ref{3d1,,Py_DontWriteBytecodeFlag}:
Use @ref{3d2,,PyConfig.write_bytecode} instead.

@item 
@ref{3d3,,Py_NoUserSiteDirectory}:
Use @ref{3d4,,PyConfig.user_site_directory} instead.

@item 
@ref{3d5,,Py_UnbufferedStdioFlag}:
Use @ref{3d6,,PyConfig.buffered_stdio} instead.

@item 
@ref{3d7,,Py_HashRandomizationFlag}:
Use @ref{3d8,,PyConfig.use_hash_seed}
and @ref{3d9,,PyConfig.hash_seed} instead.

@item 
@ref{3da,,Py_IsolatedFlag}:
Use @ref{3db,,PyConfig.isolated} instead.

@item 
@ref{3dc,,Py_LegacyWindowsFSEncodingFlag}:
Use @ref{3dd,,PyPreConfig.legacy_windows_fs_encoding} instead.

@item 
@ref{3de,,Py_LegacyWindowsStdioFlag}:
Use @ref{39b,,PyConfig.legacy_windows_stdio} instead.

@item 
@code{Py_FileSystemDefaultEncoding}:
Use @ref{3df,,PyConfig.filesystem_encoding} instead.

@item 
@code{Py_HasFileSystemDefaultEncoding}:
Use @ref{3df,,PyConfig.filesystem_encoding} instead.

@item 
@code{Py_FileSystemDefaultEncodeErrors}:
Use @ref{3e0,,PyConfig.filesystem_errors} instead.

@item 
@code{Py_UTF8Mode}:
Use @ref{3e1,,PyPreConfig.utf8_mode} instead.
(see @ref{3e2,,Py_PreInitialize()})
@end itemize

The @ref{3bc,,Py_InitializeFromConfig()} API should be used with
@ref{39d,,PyConfig} instead.
@end itemize

@node Pending Removal in Python 3 15<6>,Pending Removal in Future Versions<6>,Pending Removal in Python 3 14<6>,C API Deprecations
@anchor{deprecations/index id2}@anchor{502b}
@subsection Pending Removal in Python 3.15



@itemize *

@item 
The bundled copy of @code{libmpdecimal}.

@item 
The @ref{3b4,,PyImport_ImportModuleNoBlock()}:
Use @ref{3b5,,PyImport_ImportModule()} instead.

@item 
@ref{36f,,PyWeakref_GetObject()} and @ref{3b6,,PyWeakref_GET_OBJECT()}:
Use @ref{36e,,PyWeakref_GetRef()} instead.

@item 
@ref{3e4,,Py_UNICODE} type and the @code{Py_UNICODE_WIDE} macro:
Use @code{wchar_t} instead.

@item 
Python initialization functions:


@itemize *

@item 
@ref{3a6,,PySys_ResetWarnOptions()}:
Clear @ref{3a7,,sys.warnoptions} and @code{warnings.filters} instead.

@item 
@ref{3a8,,Py_GetExecPrefix()}:
Get @ref{3e5,,sys.base_exec_prefix} and @ref{3a9,,sys.exec_prefix} instead.

@item 
@ref{3aa,,Py_GetPath()}:
Get @ref{3ab,,sys.path} instead.

@item 
@ref{3ac,,Py_GetPrefix()}:
Get @ref{3e6,,sys.base_prefix} and @ref{3ad,,sys.prefix} instead.

@item 
@ref{3ae,,Py_GetProgramFullPath()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b0,,Py_GetProgramName()}:
Get @ref{3af,,sys.executable} instead.

@item 
@ref{3b1,,Py_GetPythonHome()}:
Get @ref{3b2,,PyConfig.home}
or the 
@geindex PYTHONHOME
@geindex variable d'environnement; PYTHONHOME
@ref{3b3,,PYTHONHOME} environment variable instead.
@end itemize
@end itemize

@node Pending Removal in Future Versions<6>,,Pending Removal in Python 3 15<6>,C API Deprecations
@anchor{deprecations/index id3}@anchor{502c}
@subsection Pending Removal in Future Versions


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


@itemize *

@item 
@ref{3e8,,Py_TPFLAGS_HAVE_FINALIZE}:
Unneeded since Python 3.8.

@item 
@ref{3e9,,PyErr_Fetch()}:
Use @ref{3ea,,PyErr_GetRaisedException()} instead.

@item 
@ref{3eb,,PyErr_NormalizeException()}:
Use @ref{3ea,,PyErr_GetRaisedException()} instead.

@item 
@ref{3ec,,PyErr_Restore()}:
Use @ref{3ed,,PyErr_SetRaisedException()} instead.

@item 
@ref{3ee,,PyModule_GetFilename()}:
Use @ref{3ef,,PyModule_GetFilenameObject()} instead.

@item 
@ref{3f0,,PyOS_AfterFork()}:
Use @ref{3f1,,PyOS_AfterFork_Child()} instead.

@item 
@ref{3f2,,PySlice_GetIndicesEx()}:
Use @ref{3f3,,PySlice_Unpack()} and @ref{3f4,,PySlice_AdjustIndices()} instead.

@item 
@code{PyUnicode_AsDecodedObject()}:
Use @ref{3f5,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsDecodedUnicode()}:
Use @ref{3f5,,PyCodec_Decode()} instead.

@item 
@code{PyUnicode_AsEncodedObject()}:
Use @ref{3f6,,PyCodec_Encode()} instead.

@item 
@code{PyUnicode_AsEncodedUnicode()}:
Use @ref{3f6,,PyCodec_Encode()} instead.

@item 
@ref{3f7,,PyUnicode_READY()}:
Unneeded since Python 3.12

@item 
@code{PyErr_Display()}:
Use @ref{3f8,,PyErr_DisplayException()} instead.

@item 
@code{_PyErr_ChainExceptions()}:
Use @code{_PyErr_ChainExceptions1()} instead.

@item 
@code{PyBytesObject.ob_shash} member:
call @ref{3f9,,PyObject_Hash()} instead.

@item 
@code{PyDictObject.ma_version_tag} member.

@item 
Thread Local Storage (TLS) API:


@itemize *

@item 
@ref{3fa,,PyThread_create_key()}:
Use @ref{3fb,,PyThread_tss_alloc()} instead.

@item 
@ref{3fc,,PyThread_delete_key()}:
Use @ref{3fd,,PyThread_tss_free()} instead.

@item 
@ref{3fe,,PyThread_set_key_value()}:
Use @ref{3ff,,PyThread_tss_set()} instead.

@item 
@ref{400,,PyThread_get_key_value()}:
Use @ref{401,,PyThread_tss_get()} instead.

@item 
@ref{402,,PyThread_delete_key_value()}:
Use @ref{403,,PyThread_tss_delete()} instead.

@item 
@ref{404,,PyThread_ReInitTLS()}:
Unneeded since Python 3.7.
@end itemize
@end itemize

@node Glossaire,About this documentation,Deprecations,Top
@anchor{glossary doc}@anchor{502d}@anchor{glossary glossary}@anchor{1b6b}@anchor{glossary id1}@anchor{502e}
@chapter Glossaire


@c if you add new entries, keep the alphabetical sorting!


@table @asis
@anchor{glossary term-0}@anchor{16b}
@geindex >>>

@item @code{>>>}

The default Python prompt of the @ref{168,,interactive} shell.  Often
seen for code examples which can be executed interactively in the
interpreter.
@anchor{glossary term-}@anchor{16c}
@geindex ...

@item @code{...}

Peut faire référence à :


@itemize *

@item 
The default Python prompt of the @ref{168,,interactive} shell when entering the
code for an indented code block, when within a pair of matching left and
right delimiters (parentheses, square brackets, curly braces or triple
quotes), or after specifying a decorator.

@item 
La constante @ref{210e,,Ellipsis}.
@end itemize
@anchor{glossary term-abstract-base-class}@anchor{1193}
@geindex classe mère abstraite

@item classe mère abstraite

Les classes mères abstraites (ABC, suivant l'abréviation anglaise `Abstract Base Class') complètent le @ref{502f,,duck-typing} en fournissant un moyen de définir des interfaces pour les cas où d'autres techniques comme @ref{4bb,,hasattr()} seraient inélégantes ou subtilement fausses (par exemple avec les @ref{1ee8,,méthodes magiques}). Les ABC introduisent des sous-classes virtuelles qui n'héritent pas d'une classe mais qui sont quand même reconnues par @ref{42b,,isinstance()} ou @ref{7ab,,issubclass()} (voir la documentation du module @ref{4,,abc}). Python contient de nombreuses ABC pour les structures de données (dans le module @ref{1e,,collections.abc}), les nombres (dans le module @ref{9d,,numbers}), les flux (dans le module @ref{7e,,io}) et les chercheurs-chargeurs du système d'importation (dans le module @ref{77,,importlib.abc}). Vous pouvez créer vos propres ABC avec le module @ref{4,,abc}.
@anchor{glossary term-annotation}@anchor{441}
@geindex annotation

@item annotation

Étiquette associée à une variable, un attribut de classe, un paramètre de fonction ou une valeur de retour. Elle est utilisée par convention comme @ref{1f04,,type hint}.

Les annotations de variables locales ne sont pas accessibles au moment de l'exécution, mais les annotations de variables globales, d'attributs de classe et de fonctions sont stockées dans l'attribut spécial @code{__annotations__} des modules, classes et fonctions, respectivement.

Voir @ref{d43,,annotation de variable}, @ref{1bc5,,annotation de fonction}, les 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} et 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/}, qui décrivent cette fonctionnalité. Voir aussi @ref{7c3,,Bonnes pratiques concernant les annotations} sur les bonnes pratiques concernant les annotations.
@anchor{glossary term-argument}@anchor{432}
@geindex argument

@item argument

Valeur, donnée à une @ref{1fd8,,fonction} ou à une @ref{5030,,méthode} lors de son appel. Il existe deux types d'arguments :


@itemize *

@item 
`argument nommé' : un argument précédé d'un identifiant (comme @code{name=}) ou un dictionnaire précédé de @code{**}, lors d'un appel de fonction. Par exemple, @code{3} et @code{5} sont tous les deux des arguments nommés dans l'appel à @ref{2ec,,complex()} ici :

@example
complex(real=3, imag=5)
complex(**@{'real': 3, 'imag': 5@})
@end example

@item 
`argument positionnel' : un argument qui n'est pas nommé. Les arguments positionnels apparaissent au début de la liste des arguments, ou donnés sous forme d'un @ref{1205,,itérable} précédé par @code{*}. Par exemple, @code{3} et @code{5} sont tous les deux des arguments positionnels dans les appels suivants :

@example
complex(3, 5)
complex(*(3, 5))
@end example
@end itemize

Les arguments se retrouvent dans le corps de la fonction appelée parmi les variables locales. Voir la section @ref{d6a,,Appels} à propos des règles dictant cette affectation. Syntaxiquement, toute expression est acceptée comme argument, et c'est la valeur résultante de l'expression qui sera affectée à la variable locale.

Voir aussi @ref{1e82,,paramètre} dans le glossaire, la question @ref{4f73,,Différence entre argument et paramètre} de la FAQ et la 
@geindex Python Enhancement Proposals; PEP 362
PEP 362@footnote{https://peps.python.org/pep-0362/}.
@anchor{glossary term-asynchronous-context-manager}@anchor{5c1}
@geindex gestionnaire de contexte asynchrone

@item gestionnaire de contexte asynchrone

(`asynchronous context manager' en anglais) Objet contrôlant l'environnement à l'intérieur d'une instruction @ref{5bf,,async with} en définissant les méthodes @ref{1f53,,__aenter__()} et @ref{15b3,,__aexit__()}. A été Introduit par la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-asynchronous-generator}@anchor{1fba}
@geindex générateur asynchrone

@item générateur asynchrone

Fonction qui renvoie un @ref{42ac,,itérateur de générateur asynchrone}. Cela ressemble à une coroutine définie par @ref{5bb,,async def}, sauf qu'elle contient une ou des expressions @ref{9bb,,yield} produisant ainsi uns série de valeurs utilisables dans une boucle @ref{a99,,async for}.

Générateur asynchrone fait généralement référence à une fonction, mais peut faire référence à un `itérateur de générateur asynchrone' dans certains contextes. Dans les cas où le sens voulu n'est pas clair, utiliser l'ensemble des termes lève l’ambiguïté.

Un générateur asynchrone peut contenir des expressions @ref{1b7,,await} ainsi que des instructions @ref{a99,,async for}, et @ref{5bf,,async with}.
@anchor{glossary term-asynchronous-generator-iterator}@anchor{42ac}
@geindex itérateur de générateur asynchrone

@item itérateur de générateur asynchrone

Objet créé par un @ref{1fba,,générateur asynchrone}.

C'est un @ref{1a9,,asynchronous iterator} qui, lorsqu'il est appelé via la méthode @ref{1e8f,,__anext__()} renvoie un objet `awaitable' qui exécute le corps de la fonction du générateur asynchrone jusqu'au prochain @ref{9bb,,yield}.

Chaque @ref{9bb,,yield} suspend temporairement l'exécution, en gardant en mémoire l'emplacement et l'état de l'exécution (ce qui inclut les variables locales et les `try' en cours). Lorsque l'exécution de l'itérateur de générateur asynchrone reprend avec un nouvel `awaitable' renvoyé par @ref{1e8f,,__anext__()}, elle repart de là où elle s'était arrêtée. Voir les 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/} et 
@geindex Python Enhancement Proposals; PEP 525
PEP 525@footnote{https://peps.python.org/pep-0525/}.
@anchor{glossary term-asynchronous-iterable}@anchor{d65}
@geindex itérable asynchrone

@item itérable asynchrone

Objet qui peut être utilisé dans une instruction @ref{a99,,async for}. Sa méthode @ref{be9,,__aiter__()} doit renvoyer un @ref{1a9,,asynchronous iterator}. A été introduit par la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-asynchronous-iterator}@anchor{1a9}
@geindex itérateur asynchrone

@item itérateur asynchrone

Objet qui implémente les méthodes @ref{be9,,__aiter__()} et @ref{1e8f,,__anext__()}. @ref{1e8f,,__anext__()} doit renvoyer un objet @ref{1ab,,awaitable}. Tant que la méthode @ref{1e8f,,__anext__()} produit des objets `awaitable', le @ref{a99,,async for} appelant les consomme. L'itérateur asynchrone lève une exception @ref{19bb,,StopAsyncIteration} pour signifier la fin de l'itération. A été introduit par la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-attribute}@anchor{2422}
@geindex attribut

@item attribut

Valeur associée à un objet et habituellement désignée par son nom `via' une notation utilisant des points. Par exemple, si un objet `o' possède un attribut `a', cet attribut est référencé par `o.a'.

Il est possible de donner à un objet un attribut dont le nom n'est pas un identifiant tel que défini pour les @ref{1e1a,,Identifiants et mots-clés}, par exemple en utilisant @ref{20e1,,setattr()}, si l'objet le permet. Un tel attribut ne sera pas accessible à l'aide d'une expression pointée et on devra y accéder avec @ref{bbf,,getattr()}.
@anchor{glossary term-awaitable}@anchor{1ab}
@geindex attendable (awaitable)

@item attendable (`awaitable')

Objet pouvant être utilisé dans une expression @ref{1b7,,await}. Ce peut être une @ref{47b,,coroutine} ou un objet avec une méthode @ref{1f4a,,__await__()}. Voir aussi la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-BDFL}@anchor{5031}
@geindex BDFL

@item BDFL

Dictateur bienveillant à vie (`Benevolent Dictator For Life' en anglais). Pseudonyme de Guido van Rossum@footnote{https://gvanrossum.github.io/}, le créateur de Python.
@anchor{glossary term-binary-file}@anchor{1c15}
@geindex fichier binaire

@item fichier binaire

A @ref{11a0,,file object} able to read and write
@ref{d1b,,bytes-like objects}.
Examples of binary files are files opened in binary mode (@code{'rb'},
@code{'wb'} or @code{'rb+'}), @ref{527,,sys.stdin.buffer},
@ref{ac4,,sys.stdout.buffer}, and instances of
@ref{e8d,,io.BytesIO} and @ref{410,,gzip.GzipFile}.

Consultez @ref{1c14,,fichier texte}, un objet fichier capable de lire et d'écrire des objets @ref{435,,str}.
@anchor{glossary term-borrowed-reference}@anchor{334}
@geindex référence empruntée

@item référence empruntée

In Python's C API, a borrowed reference is a reference to an object,
where the code using the object does not own the reference.
It becomes a dangling
pointer if the object is destroyed. For example, a garbage collection can
remove the last @ref{333,,strong reference} to the object and so destroy it.

Il est recommandé d'appeler @ref{55a,,Py_INCREF()} sur la @ref{334,,référence empruntée}, ce qui la transforme `in situ' en une @ref{333,,référence forte}. Vous pouvez faire une exception si vous êtes certain que l'objet ne peut pas être supprimé avant la dernière utilisation de la référence empruntée. Voir aussi la fonction @ref{886,,Py_NewRef()}, qui crée une nouvelle @ref{333,,référence forte}.
@anchor{glossary term-bytes-like-object}@anchor{d1b}
@geindex objet octet-compatible

@item objet octet-compatible

Un objet gérant le @ref{38e,,protocole tampon} et pouvant exporter un tampon (`buffer' en anglais) C-@ref{21af,,contigu}. Cela inclut les objets @ref{1bd,,bytes}, @ref{528,,bytearray} et @ref{19e,,array.array}, ainsi que beaucoup d'objets @ref{452,,memoryview}. Les objets octets-compatibles peuvent être utilisés pour diverses opérations sur des données binaires, comme la compression, la sauvegarde dans un fichier binaire ou l'envoi sur le réseau.

Certaines opérations nécessitent de travailler sur des données binaires variables. La documentation parle de ceux-ci comme des `read-write bytes-like objects'. Par exemple, @ref{528,,bytearray} ou une @ref{452,,memoryview} d'un @ref{528,,bytearray} en font partie. D'autres opérations nécessitent de travailler sur des données binaires stockées dans des objets immuables (« `objets octets-compatibles en lecture seule' »), par exemple des @ref{1bd,,bytes} ou des @ref{452,,memoryview} d'un objet @ref{1bd,,bytes}.
@anchor{glossary term-bytecode}@anchor{185}
@geindex code intermédiaire (bytecode)

@item code intermédiaire (`bytecode')

Le code source, en Python, est compilé en un code intermédiaire (`bytecode' en anglais), la représentation interne à CPython d'un programme Python. Le code intermédiaire est mis en cache dans un fichier @code{.pyc} de manière à ce qu'une seconde exécution soit plus rapide (la compilation en code intermédiaire a déjà été faite). On dit que ce `langage intermédiaire' est exécuté sur une @ref{3458,,virtual machine} qui exécute des instructions machine pour chaque instruction du code intermédiaire. Notez que le code intermédiaire n'a pas vocation à fonctionner sur différentes machines virtuelles Python ou à être stable entre différentes versions de Python.

La documentation du @ref{59c,,module dis} fournit une liste des instructions du code intermédiaire.
@anchor{glossary term-callable}@anchor{2870}
@geindex appelable (callable)

@item appelable (`callable')

Un appelable est un objet qui peut être appelé, éventuellement avec un ensemble d'arguments (voir  @ref{432,,argument}), avec la syntaxe suivante :

@example
callable(argument1, argument2, argumentN)
@end example

Une @ref{1fd8,,fonction}, et par extension une @ref{5030,,méthode}, est un appelable. Une instance d'une classe qui implémente la méthode @ref{543,,__call__()} est également un appelable.
@anchor{glossary term-callback}@anchor{2893}
@geindex fonction de rappel (callback)

@item fonction de rappel (`callback')

Une fonction (classique, par opposition à une coroutine) passée en argument pour être exécutée plus tard.
@anchor{glossary term-class}@anchor{18bf}
@geindex classe

@item classe

Modèle pour créer des objets définis par l'utilisateur. Une définition de classe (`class') contient normalement des définitions de méthodes qui agissent sur les instances de la classe.
@anchor{glossary term-class-variable}@anchor{5032}
@geindex variable de classe

@item variable de classe

Une variable définie dans une classe et destinée à être modifiée uniquement au niveau de la classe (c'est-à-dire, pas dans une instance de la classe).
@anchor{glossary term-closure-variable}@anchor{1ec4}
@geindex closure variable

@item closure variable

A @ref{1f5d,,free variable} referenced from a @ref{1ec3,,nested scope} that is defined in an outer
scope rather than being resolved at runtime from the globals or builtin namespaces.
May be explicitly defined with the @ref{1285,,nonlocal} keyword to allow write access,
or implicitly defined if the variable is only being read.

For example, in the @code{inner} function in the following code, both @code{x} and @code{print} are
@ref{1f5d,,free variables}, but only @code{x} is a `closure variable':

@example
def outer():
    x = 0
    def inner():
        nonlocal x
        x += 1
        print(x)
    return inner
@end example

Due to the @ref{1e7e,,codeobject.co_freevars} attribute (which, despite its name, only
includes the names of closure variables rather than listing all referenced free
variables), the more general @ref{1f5d,,free variable} term is sometimes used even
when the intended meaning is to refer specifically to closure variables.
@anchor{glossary term-complex-number}@anchor{5033}
@geindex nombre complexe

@item nombre complexe

Extension des nombres réels familiers, dans laquelle tous les nombres sont exprimés sous la forme d'une somme d'une partie réelle et d'une partie imaginaire. Les nombres imaginaires sont les nombres réels multipliés par l'unité imaginaire (la racine carrée de @code{-1}, souvent écrite @code{i} en mathématiques ou @code{j} par les ingénieurs). Python comprend nativement les nombres complexes, écrits avec cette dernière notation : la partie imaginaire est écrite avec un suffixe @code{j}, exemple, @code{3+1j}. Pour utiliser les équivalents complexes de @ref{8d,,math}, utilisez @ref{18,,cmath}. Les nombres complexes sont un concept assez avancé en mathématiques. Si vous ne connaissez pas ce concept, vous pouvez tranquillement les ignorer.
@anchor{glossary term-context}@anchor{1537}
@geindex context

@item context

This term has different meanings depending on where and how it is used.
Some common meanings:


@itemize *

@item 
The temporary state or environment established by a @ref{5be,,context manager} via a @ref{5bc,,with} statement.

@item 
The collection of key­value bindings associated with a particular
@ref{152f,,contextvars.Context} object and accessed via
@ref{31af,,ContextVar} objects.  Also see @ref{5034,,context variable}.

@item 
A @ref{152f,,contextvars.Context} object.  Also see @ref{1538,,current context}.
@end itemize
@anchor{glossary term-context-management-protocol}@anchor{1539}
@geindex context management protocol

@item context management protocol

The @ref{5b2,,__enter__()} and @ref{12de,,__exit__()} methods called
by the @ref{5bc,,with} statement.  See 
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}.
@anchor{glossary term-context-manager}@anchor{5be}
@geindex gestionnaire de contexte

@item gestionnaire de contexte

An object which implements the @ref{1539,,context management protocol} and
controls the environment seen in a @ref{5bc,,with} statement.  See
@geindex Python Enhancement Proposals; PEP 343
PEP 343@footnote{https://peps.python.org/pep-0343/}.
@anchor{glossary term-context-variable}@anchor{5034}
@geindex variable de contexte

@item variable de contexte

A variable whose value depends on which context is the @ref{1538,,current context}.  Values are accessed via @ref{31af,,contextvars.ContextVar}
objects.  Context variables are primarily used to isolate state between
concurrent asynchronous tasks.
@anchor{glossary term-contiguous}@anchor{21af}
@geindex contigu

@item contigu

@geindex C-contiguous
@geindex Fortran contiguous

Un tampon (`buffer' en anglais) est considéré comme contigu s’il est soit `C-contigu' soit `Fortran-contigu'. Les tampons de dimension zéro sont C-contigus et Fortran-contigus. Pour un tableau à une dimension, ses éléments doivent être placés en mémoire l’un à côté de l’autre, dans l’ordre croissant de leur indice, en commençant à zéro. Pour qu’un tableau multidimensionnel soit C-contigu, le dernier indice doit être celui qui varie le plus rapidement lors du parcours de ses éléments dans l’ordre de leur adresse mémoire. À l'inverse, dans les tableaux Fortran-contigu, c’est le premier indice qui doit varier le plus rapidement.
@anchor{glossary term-coroutine}@anchor{47b}
@geindex coroutine

@item coroutine

Les coroutines sont une forme généralisée des fonctions. On entre dans une fonction en un point et on en sort en un autre point. On peut entrer, sortir et reprendre l'exécution d'une coroutine en plusieurs points. Elles peuvent être implémentées en utilisant l'instruction @ref{5bb,,async def}. Voir aussi la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-coroutine-function}@anchor{d64}
@geindex fonction coroutine

@item fonction coroutine

Fonction qui renvoie un objet @ref{47b,,coroutine}. Une fonction coroutine peut être définie par l'instruction @ref{5bb,,async def} et peut contenir les mots clés @ref{1b7,,await}, @ref{a99,,async for} ainsi que @ref{5bf,,async with}. A été introduit par la 
@geindex Python Enhancement Proposals; PEP 492
PEP 492@footnote{https://peps.python.org/pep-0492/}.
@anchor{glossary term-CPython}@anchor{6e0}
@geindex CPython

@item CPython

L'implémentation canonique du langage de programmation Python, tel que distribué sur python.org@footnote{https://www.python.org}. Le terme "CPython" est utilisé dans certains contextes lorsqu'il est nécessaire de distinguer cette implémentation des autres comme `Jython' ou `IronPython'.
@anchor{glossary term-current-context}@anchor{1538}
@geindex current context

@item current context

The @ref{1537,,context} (@ref{152f,,contextvars.Context} object) that is
currently used by @ref{31af,,ContextVar} objects to access (get
or set) the values of @ref{5034,,context variables}.  Each
thread has its own current context.  Frameworks for executing asynchronous
tasks (see @ref{a,,asyncio}) associate each task with a context which
becomes the current context whenever the task starts or resumes execution.
@anchor{glossary term-decorator}@anchor{71b}
@geindex décorateur

@item décorateur

Fonction dont la valeur de retour est une autre fonction. Un décorateur est habituellement utilisé pour transformer une fonction via la syntaxe @code{@@wrapper}, dont les exemples typiques sont : @ref{165,,classmethod()} et @ref{40c,,staticmethod()}.

La syntaxe des décorateurs est simplement du sucre syntaxique, les définitions des deux fonctions suivantes sont sémantiquement équivalentes :

@example
def f(arg):
    ...
f = staticmethod(f)

@@staticmethod
def f(arg):
    ...
@end example

Quoique moins fréquemment utilisé, le même concept existe pour les classes. Consultez la documentation @ref{1bc4,,définitions de fonctions} et @ref{12b5,,définitions de classes} pour en savoir plus sur les décorateurs.
@anchor{glossary term-descriptor}@anchor{1ef3}
@geindex descripteur

@item descripteur

Any object which defines the methods @ref{149d,,__get__()},
@ref{1eec,,__set__()}, or @ref{1591,,__delete__()}.
When a class attribute is a descriptor, its special
binding behavior is triggered upon attribute lookup.  Normally, using
`a.b' to get, set or delete an attribute looks up the object named `b' in
the class dictionary for `a', but if `b' is a descriptor, the respective
descriptor method gets called.  Understanding descriptors is a key to a
deep understanding of Python because they are the basis for many features
including functions, methods, properties, class methods, static methods,
and reference to super classes.

Pour plus d'informations sur les méthodes des descripteurs, consultez @ref{c3d,,Implémentation de descripteurs} ou le @ref{14a2,,guide pour l'utilisation des descripteurs}.
@anchor{glossary term-dictionary}@anchor{1f0e}
@geindex dictionnaire

@item dictionnaire

An associative array, where arbitrary keys are mapped to values.  The
keys can be any object with @ref{ae9,,__hash__()} and
@ref{ae8,,__eq__()} methods.
Called a hash in Perl.
@anchor{glossary term-dictionary-comprehension}@anchor{5035}
@geindex dictionnaire en compréhension (ou dictionnaire en intension)

@item dictionnaire en compréhension (ou dictionnaire en intension)

Écriture concise pour traiter tout ou partie des éléments d'un itérable et renvoyer un dictionnaire contenant les résultats. @code{results = @{n: n ** 2 for n in range(10)@}} génère un dictionnaire contenant des clés @code{n} liées à leurs valeurs @code{n ** 2}. Voir @ref{5ba,,compréhensions}.
@anchor{glossary term-dictionary-view}@anchor{24a2}
@geindex vue de dictionnaire

@item vue de dictionnaire

Objets retournés par les méthodes @ref{7b7,,dict.keys()}, @ref{7b8,,dict.values()} et @ref{7b9,,dict.items()}. Ils fournissent des vues dynamiques des entrées du dictionnaire, ce qui signifie que lorsque le dictionnaire change, la vue change. Pour transformer une vue en vraie liste, utilisez @code{list(dictview)}. Voir @ref{21cc,,Les vues de dictionnaires}.
@anchor{glossary term-docstring}@anchor{20aa}
@geindex chaîne de documentation (docstring)

@item chaîne de documentation (`docstring')

A string literal which appears as the first expression in a class,
function or module.  While ignored when the suite is executed, it is
recognized by the compiler and put into the @ref{915,,__doc__} attribute
of the enclosing class, function or module.  Since it is available via
introspection, it is the canonical place for documentation of the
object.
@anchor{glossary term-duck-typing}@anchor{502f}
@geindex typage canard (duck-typing)

@item typage canard (`duck-typing')

Style de programmation qui ne prend pas en compte le type d'un objet pour déterminer s'il respecte une interface, mais qui appelle simplement la méthode ou l'attribut (`Si ça a un bec et que ça cancane, ça doit être un canard', `duck' signifie canard en anglais). En se concentrant sur les interfaces plutôt que les types, du code bien construit améliore sa flexibilité en autorisant des substitutions polymorphiques. Le `duck-typing' évite de vérifier les types via @ref{d36,,type()} ou @ref{42b,,isinstance()}, Notez cependant que le `duck-typing' peut travailler de pair avec les @ref{1193,,classes mère abstraites}. À la place, le `duck-typing' utilise plutôt @ref{4bb,,hasattr()} ou la programmation @ref{2b03,,EAFP}.
@anchor{glossary term-EAFP}@anchor{2b03}
@geindex EAFP

@item EAFP

Il est plus simple de demander pardon que demander la permission (`Easier to Ask for Forgiveness than Permission' en anglais). Ce style de développement Python fait l'hypothèse que le code est valide et traite les exceptions si cette hypothèse s'avère fausse. Ce style, propre et efficace, est caractérisé par la présence de beaucoup de mots clés @ref{6d3,,try} et @ref{189,,except}. Cette technique de programmation contraste avec le style @ref{5036,,LBYL} utilisé couramment dans les langages tels que C.
@anchor{glossary term-expression}@anchor{1f08}
@geindex expression

@item expression

Suite logique de termes et chiffres conformes à la syntaxe Python dont l'évaluation fournit une valeur. En d'autres termes, une expression est une suite d'éléments tels que des noms, opérateurs, littéraux, accès d'attributs, méthodes ou fonctions qui aboutissent à une valeur. Contrairement à beaucoup d'autres langages, les différentes constructions du langage ne sont pas toutes des expressions. On trouve également des @ref{2704,,instructions} qui ne peuvent pas être utilisées comme expressions, tel que @ref{1b92,,while}. Les affectations sont également des instructions et non des expressions.
@anchor{glossary term-extension-module}@anchor{44b8}
@geindex module d'extension

@item module d'extension

Module écrit en C ou C++, utilisant l'API C de Python pour interagir avec Python et le code de l'utilisateur.
@anchor{glossary term-f-string}@anchor{41f}
@geindex f-string

@item f-string

Chaîne littérale préfixée de @code{'f'} ou @code{'F'}. Les "f-strings" sont un raccourci pour @ref{997,,formatted string literals}. Voir la 
@geindex Python Enhancement Proposals; PEP 498
PEP 498@footnote{https://peps.python.org/pep-0498/}.
@anchor{glossary term-file-object}@anchor{11a0}
@geindex objet fichier

@item objet fichier

An object exposing a file-oriented API (with methods such as
@code{read()} or @code{write()}) to an underlying resource.  Depending
on the way it was created, a file object can mediate access to a real
on-disk file or to another type of storage or communication device
(for example standard input/output, in-memory buffers, sockets, pipes,
etc.).  File objects are also called `file-like objects' or
`streams'.

Il existe en réalité trois catégories de fichiers objets : les @ref{1c15,,fichiers binaires} bruts, les @ref{1c15,,fichiers binaires} avec tampon (`buffer') et les @ref{1c14,,fichiers textes}. Leurs interfaces sont définies dans le module @ref{7e,,io}. Le moyen le plus simple et direct de créer un objet fichier est d'utiliser la fonction @ref{505,,open()}.
@anchor{glossary term-file-like-object}@anchor{250d}
@geindex objet fichier-compatible

@item objet fichier-compatible

Synonyme de @ref{11a0,,objet fichier}.
@anchor{glossary term-filesystem-encoding-and-error-handler}@anchor{525}
@geindex encodage du système de fichiers et gestionnaire d'erreurs associé

@item encodage du système de fichiers et gestionnaire d'erreurs associé

Encodage et gestionnaire d'erreurs utilisés par Python pour décoder les octets fournis par le système d'exploitation et encoder les chaînes de caractères Unicode afin de les passer au système.

L'encodage du système de fichiers doit impérativement pouvoir décoder tous les octets jusqu'à 128. Si ce n'est pas le cas, certaines fonctions de l'API lèvent @ref{1281,,UnicodeError}.

Cet encodage et son gestionnaire d'erreur peuvent être obtenus à l'aide des fonctions @ref{c47,,sys.getfilesystemencoding()} et @ref{cd4,,sys.getfilesystemencodeerrors()}.

L'@ref{525,,encodage du système de fichiers et gestionnaire d'erreurs associé} sont configurés au démarrage de Python par la fonction @ref{77a,,PyConfig_Read()} : regardez @ref{3df,,filesystem_encoding} et @ref{3e0,,filesystem_errors} dans les membres de @ref{39d,,PyConfig}.

Voir aussi @ref{23f,,encodage régional}.
@anchor{glossary term-finder}@anchor{1ea3}
@geindex chercheur

@item chercheur

Objet qui essaie de trouver un @ref{1639,,chargeur} pour le module en cours d'importation.

There are two types of finder: @ref{1059,,meta path finders} for use with @ref{d19,,sys.meta_path}, and @ref{105a,,path entry finders} for use with @ref{100d,,sys.path_hooks}.

See @ref{1f75,,Chercheurs et chargeurs} and @ref{76,,importlib} for much more detail.
@anchor{glossary term-floor-division}@anchor{931}
@geindex division entière

@item division entière

Division mathématique arrondissant à l'entier inférieur. L'opérateur de la division entière est @code{//}. Par exemple l'expression @code{11 // 4} vaut @code{2}, contrairement à @code{11 / 4} qui vaut @code{2.75}. Notez que @code{(-11) // 4} vaut @code{-3} car l'arrondi se fait à l'entier inférieur. Voir la 
@geindex Python Enhancement Proposals; PEP 328
PEP 328@footnote{https://peps.python.org/pep-0328/}.
@anchor{glossary term-free-threading}@anchor{150c}
@geindex free threading

@item free threading

A threading model where multiple threads can run Python bytecode
simultaneously within the same interpreter.  This is in contrast to
the @ref{147,,global interpreter lock} which allows only one thread to
execute Python bytecode at a time.  See 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}.
@anchor{glossary term-free-variable}@anchor{1f5d}
@geindex free variable

@item free variable

Formally, as defined in the @ref{1f5a,,language execution model}, a free
variable is any variable used in a namespace which is not a local variable in that
namespace. See @ref{1ec4,,closure variable} for an example.
Pragmatically, due to the name of the @ref{1e7e,,codeobject.co_freevars} attribute,
the term is also sometimes used as a synonym for @ref{1ec4,,closure variable}.
@anchor{glossary term-function}@anchor{1fd8}
@geindex fonction

@item fonction

Suite d'instructions qui renvoie une valeur à son appelant. On peut lui passer des @ref{432,,arguments} qui pourront être utilisés dans le corps de la fonction. Voir aussi @ref{1e82,,paramètre}, @ref{5030,,méthode} et @ref{1bc4,,Définition de fonctions}.
@anchor{glossary term-function-annotation}@anchor{1bc5}
@geindex annotation de fonction

@item annotation de fonction

@ref{441,,annotation} d'un paramètre de fonction ou valeur de retour.

Les annotations de fonctions sont généralement utilisées pour des @ref{1f04,,indications de types} : par exemple, cette fonction devrait prendre deux arguments @ref{254,,int} et devrait également avoir une valeur de retour de type @ref{254,,int} :

@example
def sum_two_numbers(a: int, b: int) -> int:
   return a + b
@end example

L'annotation syntaxique de la fonction est expliquée dans la section @ref{1bc4,,Définition de fonctions}.

Voir @ref{d43,,annotation de variable} et la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, qui décrivent cette fonctionnalité. Voir aussi @ref{7c3,,Bonnes pratiques concernant les annotations} sur les bonnes pratiques concernant les annotations.
@anchor{glossary term-__future__}@anchor{d9a}
@geindex __future__

@item __future__

Une @ref{187,,importation depuis le futur} s'écrit @code{from __future__ import <fonctionnalité>}. Lorsqu'une importation du futur est active dans un module, Python compile ce module avec une certaine modification de la syntaxe ou du comportement qui est vouée à devenir standard dans une version ultérieure. Le module @ref{0,,__future__} documente les possibilités pour `fonctionnalité'. L'importation a aussi l'effet normal d'importer une variable du module. Cette variable contient des informations utiles sur la fonctionnalité en question, notamment la version de Python dans laquelle elle a été ajoutée, et celle dans laquelle elle deviendra standard :

@example
>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
@end example
@anchor{glossary term-garbage-collection}@anchor{18a7}
@geindex ramasse-miettes

@item ramasse-miettes

(`garbage collection' en anglais) Mécanisme permettant de libérer de la mémoire lorsqu'elle n'est plus utilisée. Python utilise un ramasse-miettes par comptage de référence et un ramasse-miettes cyclique capable de détecter et casser les références circulaires. Le ramasse-miettes peut être contrôlé en utilisant le module @ref{5f,,gc}.

@geindex générateur
@anchor{glossary term-generator}@anchor{104a}
@geindex générateur

@item générateur

Fonction qui renvoie un @ref{bcc,,itérateur de générateur}. Cela ressemble à une fonction normale, en dehors du fait qu'elle contient une ou des expressions @ref{9bb,,yield} produisant une série de valeurs utilisable dans une boucle `for' ou récupérées une à une via la fonction @ref{7c2,,next()}.

Fait généralement référence à une fonction génératrice mais peut faire référence à un `itérateur de générateur' dans certains contextes. Dans les cas où le sens voulu n'est pas clair, utiliser les termes complets lève l’ambiguïté.
@anchor{glossary term-generator-iterator}@anchor{bcc}
@geindex itérateur de générateur

@item itérateur de générateur

Objet créé par une fonction @ref{104a,,générateur}.

Chaque @ref{9bb,,yield} suspend temporairement l'exécution, en se rappelant l'endroit et l'état de l'exécution (y compris les variables locales et les `try' en cours). Lorsque l'itérateur de générateur reprend, il repart là où il en était (contrairement à une fonction qui prendrait un nouveau départ à chaque invocation).

@geindex expression génératrice
@anchor{glossary term-generator-expression}@anchor{5037}
@geindex expression génératrice

@item expression génératrice

An @ref{1f08,,expression} that returns an @ref{1aa,,iterator}.  It looks like a normal expression
followed by a @code{for} clause defining a loop variable, range,
and an optional @code{if} clause.  The combined expression
generates values for an enclosing function:

@example
>>> sum(i*i for i in range(10))         # sum of squares 0, 1, 4, ... 81
285
@end example
@anchor{glossary term-generic-function}@anchor{9df}
@geindex fonction générique

@item fonction générique

Fonction composée de plusieurs fonctions implémentant les mêmes opérations pour différents types. L'implémentation à utiliser est déterminée lors de l'appel par l'algorithme de répartition.

Voir aussi @ref{9e0,,single dispatch}, le décorateur @ref{624,,functools.singledispatch()} et la 
@geindex Python Enhancement Proposals; PEP 443
PEP 443@footnote{https://peps.python.org/pep-0443/}.
@anchor{glossary term-generic-type}@anchor{422}
@geindex type générique

@item type générique

Un @ref{18c0,,type} qui peut être paramétré ; généralement un @ref{1f0d,,conteneur} comme @ref{5fc,,list} ou @ref{253,,dict}. Utilisé pour les @ref{1f04,,indications de type} et les @ref{441,,annotations}.

Pour plus de détails, voir @ref{69d,,types alias génériques} et le module @ref{103,,typing}.  On trouvera l'historique de cette fonctionnalité dans les 
@geindex Python Enhancement Proposals; PEP 483
PEP 483@footnote{https://peps.python.org/pep-0483/}, 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} et 
@geindex Python Enhancement Proposals; PEP 585
PEP 585@footnote{https://peps.python.org/pep-0585/}.
@anchor{glossary term-GIL}@anchor{158}
@geindex GIL

@item GIL

Voir @ref{147,,global interpreter lock}.
@anchor{glossary term-global-interpreter-lock}@anchor{147}
@geindex verrou global de l'interpréteur

@item verrou global de l'interpréteur

(`global interpreter lock' en anglais) Mécanisme utilisé par l'interpréteur @ref{6e0,,CPython} pour s'assurer qu'un seul fil d'exécution (`thread' en anglais) n'exécute le @ref{185,,bytecode} à la fois. Cela simplifie l'implémentation de CPython en rendant le modèle objet (incluant des parties critiques comme la classe native @ref{253,,dict}) implicitement protégé contre les accès concourants. Verrouiller l'interpréteur entier rend plus facile l'implémentation de multiples fils d'exécution (`multi-thread' en anglais), au détriment malheureusement de beaucoup du parallélisme possible sur les machines ayant plusieurs processeurs.

Cependant, certains modules d'extension, standards ou non, sont conçus de manière à libérer le GIL lorsqu'ils effectuent des tâches lourdes tel que la compression ou le hachage. De la même manière, le GIL est toujours libéré lors des entrées-sorties.

As of Python 3.13, the GIL can be disabled using the @ref{173,,--disable-gil}
build configuration. After building Python with this option, code must be
run with @ref{175,,-X gil=0} or after setting the 
@geindex PYTHON_GIL
@geindex variable d'environnement; PYTHON_GIL
@ref{174,,PYTHON_GIL=0}
environment variable. This feature enables improved performance for
multi-threaded applications and makes it easier to use multi-core CPUs
efficiently. For more details, see 
@geindex Python Enhancement Proposals; PEP 703
PEP 703@footnote{https://peps.python.org/pep-0703/}.
@anchor{glossary term-hash-based-pyc}@anchor{5038}
@geindex pyc utilisant le hachage

@item `pyc' utilisant le hachage

Un fichier de cache de code intermédiaire (`bytecode' en anglais) qui utilise le hachage plutôt que l'heure de dernière modification du fichier source correspondant pour déterminer sa validité. Voir @ref{5d6,,Invalidation de bytecode mis en cache}.
@anchor{glossary term-hashable}@anchor{5fb}
@geindex hachable

@item hachable

An object is `hashable' if it has a hash value which never changes during
its lifetime (it needs a @ref{ae9,,__hash__()} method), and can be
compared to other objects (it needs an @ref{ae8,,__eq__()} method).
Hashable objects which
compare equal must have the same hash value.

La hachabilité permet à un objet d'être utilisé comme clé de dictionnaire ou en tant que membre d'un ensemble (type `set'), car ces structures de données utilisent ce `hash'.

La plupart des types immuables natifs de Python sont hachables, mais les conteneurs mutables (comme les listes ou les dictionnaires) ne le sont pas ; les conteneurs immuables (comme les n-uplets ou les ensembles figés) ne sont hachables que si leurs éléments sont hachables. Les instances de classes définies par les utilisateurs sont hachables par défaut. Elles sont toutes considérées différentes (sauf avec elles-mêmes) et leur valeur de hachage est calculée à partir de leur @ref{13d9,,id()}.
@anchor{glossary term-IDLE}@anchor{5039}
@geindex IDLE

@item IDLE

Environnement d'apprentissage et de développement intégré pour Python. @ref{ffe,,IDLE} est un éditeur basique et un interpréteur livré avec la distribution standard de Python.
@anchor{glossary term-immortal}@anchor{42aa}
@geindex immortal

@item immortal

`Immortal objects' are a CPython implementation detail introduced
in 
@geindex Python Enhancement Proposals; PEP 683
PEP 683@footnote{https://peps.python.org/pep-0683/}.

If an object is immortal, its @ref{47e8,,reference count} is never modified,
and therefore it is never deallocated while the interpreter is running.
For example, @ref{bfb,,True} and @ref{660,,None} are immortal in CPython.
@anchor{glossary term-immutable}@anchor{97e}
@geindex immuable

@item immuable

Objet dont la valeur ne change pas. Les nombres, les chaînes et les `n'-uplets sont immuables. Ils ne peuvent être modifiés. Un nouvel objet doit être créé si une valeur différente doit être stockée. Ils jouent un rôle important quand une valeur de `hash' constante est requise, typiquement en clé de dictionnaire.
@anchor{glossary term-import-path}@anchor{1f77}
@geindex chemin des importations

@item chemin des importations

Liste de @ref{1f85,,entrées} dans lesquelles le @ref{1f7a,,chercheur basé sur les chemins} cherche les modules à importer. Typiquement, lors d'une importation, cette liste vient de @ref{3ab,,sys.path} ; pour les sous-paquets, elle peut aussi venir de l'attribut @code{__path__} du paquet parent.
@anchor{glossary term-importing}@anchor{503a}
@geindex importation

@item importation

Processus rendant le code Python d'un module disponible dans un autre.
@anchor{glossary term-importer}@anchor{1f6c}
@geindex importateur

@item importateur

Objet qui trouve et charge un module, en même temps un @ref{1ea3,,chercheur} et un @ref{1639,,chargeur}.
@anchor{glossary term-interactive}@anchor{168}
@geindex interactif

@item interactif

Python has an interactive interpreter which means you can enter
statements and expressions at the interpreter prompt, immediately
execute them and see their results.  Just launch @code{python} with no
arguments (possibly by selecting it from your computer's main
menu). It is a very powerful way to test out new ideas or inspect
modules and packages (remember @code{help(x)}). For more on interactive
mode, see @ref{16e,,Mode interactif}.
@anchor{glossary term-interpreted}@anchor{503b}
@geindex interprété

@item interprété

Python est un langage interprété, en opposition aux langages compilés, bien que la frontière soit floue en raison de la présence d'un compilateur en code intermédiaire. Cela signifie que les fichiers sources peuvent être exécutés directement, sans avoir à compiler un fichier exécutable intermédiaire. Les langages interprétés ont généralement un cycle de développement / débogage plus court que les langages compilés. Cependant, ils s'exécutent généralement plus lentement. Voir aussi @ref{168,,interactif}.
@anchor{glossary term-interpreter-shutdown}@anchor{14d}
@geindex arrêt de l'interpréteur

@item arrêt de l'interpréteur

Lorsqu'on lui demande de s'arrêter, l'interpréteur Python entre dans une phase spéciale où il libère graduellement les ressources allouées, comme les modules ou quelques structures de données internes. Il fait aussi quelques appels au @ref{18a7,,ramasse-miettes}. Cela peut déclencher l'exécution de code dans des destructeurs ou des fonctions de rappels de `weakrefs'. Le code exécuté lors de l'arrêt peut rencontrer des exceptions puisque les ressources auxquelles il fait appel sont susceptibles de ne plus fonctionner, (typiquement les modules des bibliothèques ou le mécanisme de `warning').

La principale raison d'arrêt de l'interpréteur est que le module @code{__main__} ou le script en cours d'exécution a terminé de s'exécuter.
@anchor{glossary term-iterable}@anchor{1205}
@geindex itérable

@item itérable

An object capable of returning its members one at a time. Examples of
iterables include all sequence types (such as @ref{5fc,,list}, @ref{435,,str},
and @ref{366,,tuple}) and some non-sequence types like @ref{253,,dict},
@ref{11a0,,file objects}, and objects of any classes you define
with an @ref{1c51,,__iter__()} method or with a
@ref{280,,__getitem__()} method
that implements @ref{4db,,sequence} semantics.

Iterables can be
used in a @ref{2e6,,for} loop and in many other places where a sequence is
needed (@ref{7ba,,zip()}, @ref{84e,,map()}, ...).  When an iterable object is passed
as an argument to the built-in function @ref{7c1,,iter()}, it returns an
iterator for the object.  This iterator is good for one pass over the set
of values.  When using iterables, it is usually not necessary to call
@ref{7c1,,iter()} or deal with iterator objects yourself.  The @ref{2e6,,for}
statement does that automatically for you, creating a temporary unnamed
variable to hold the iterator for the duration of the loop.  See also
@ref{1aa,,iterator}, @ref{4db,,sequence}, and @ref{104a,,generator}.
@anchor{glossary term-iterator}@anchor{1aa}
@geindex itérateur

@item itérateur

An object representing a stream of data.  Repeated calls to the iterator's
@ref{12ab,,__next__()} method (or passing it to the built-in function
@ref{7c2,,next()}) return successive items in the stream.  When no more data
are available a @ref{be8,,StopIteration} exception is raised instead.  At this
point, the iterator object is exhausted and any further calls to its
@code{__next__()} method just raise @ref{be8,,StopIteration} again.  Iterators
are required to have an @ref{1c51,,__iter__()} method that returns the iterator
object itself so every iterator is also iterable and may be used in most
places where other iterables are accepted.  One notable exception is code
which attempts multiple iteration passes.  A container object (such as a
@ref{5fc,,list}) produces a fresh new iterator each time you pass it to the
@ref{7c1,,iter()} function or use it in a @ref{2e6,,for} loop.  Attempting this
with an iterator will just return the same exhausted iterator object used
in the previous iteration pass, making it appear like an empty container.

Vous trouverez davantage d'informations dans @ref{20fc,,Les types itérateurs}.

`Particularité de l'implémentation CPython :' CPython does not consistently apply the requirement that an iterator
define @ref{1c51,,__iter__()}.
And also please note that the free-threading CPython does not guarantee
the thread-safety of iterator operations.
@anchor{glossary term-key-function}@anchor{df2}
@geindex fonction clé

@item fonction clé

Une fonction clé est un objet appelable qui renvoie une valeur à fins de tri ou de classement. Par exemple, la fonction @ref{3c80,,locale.strxfrm()} est utilisée pour générer une clé de classement prenant en compte les conventions de classement spécifiques aux paramètres régionaux courants.

Plusieurs outils dans Python acceptent des fonctions clés pour déterminer comment les éléments sont classés ou groupés. On peut citer les fonctions @ref{ef3,,min()}, @ref{ef4,,max()}, @ref{bbc,,sorted()}, @ref{bbd,,list.sort()}, @ref{df1,,heapq.merge()}, @ref{24b8,,heapq.nsmallest()}, @ref{24b7,,heapq.nlargest()} et @ref{26b1,,itertools.groupby()}.

Il existe plusieurs moyens de créer une fonction clé. Par exemple, la méthode @ref{177b,,str.lower()} peut servir de fonction clé pour effectuer des recherches insensibles à la casse. Aussi, il est possible de créer des fonctions clés avec des expressions @ref{127a,,lambda}, comme @code{lambda r: (r[0], r[2])}. Par ailleurs @ref{e20,,attrgetter()}, @ref{a50,,itemgetter()} et @ref{e21,,methodcaller()} permettent de créer des fonctions clés. Voir @ref{2107,,le guide pour le tri} pour des exemples de création et d'utilisation de fonctions clefs.
@anchor{glossary term-keyword-argument}@anchor{d00}
@geindex argument nommé

@item argument nommé

Voir @ref{432,,argument}.
@anchor{glossary term-lambda}@anchor{26bc}
@geindex lambda

@item lambda

Fonction anonyme sous la forme d'une @ref{1f08,,expression} et ne contenant qu'une seule expression, exécutée lorsque la fonction est appelée. La syntaxe pour créer des fonctions lambda est : @code{lambda [parameters]: expression}
@anchor{glossary term-LBYL}@anchor{5036}
@geindex LBYL

@item LBYL

Regarde avant de sauter, (`Look before you leap' en anglais). Ce style de programmation consiste à vérifier des conditions avant d'effectuer des appels ou des accès. Ce style contraste avec le style @ref{2b03,,EAFP} et se caractérise par la présence de beaucoup d'instructions @ref{2e7,,if}.

Dans un environnement avec plusieurs fils d'exécution (`multi-threaded' en anglais), le style `LBYL' peut engendrer un séquencement critique (`race condition' en anglais) entre le "regarde" et le "sauter". Par exemple, le code @code{if key in mapping: return mapping[key]} peut échouer si un autre fil d'exécution supprime la clé `key' du `mapping' après le test mais avant l'accès. Ce problème peut être résolu avec des verrous (`locks') ou avec l'approche EAFP.
@anchor{glossary term-list}@anchor{503c}
@geindex liste

@item liste

A built-in Python @ref{4db,,sequence}.  Despite its name it is more akin
to an array in other languages than to a linked list since access to
elements is `O'(1).
@anchor{glossary term-list-comprehension}@anchor{6b8}
@geindex liste en compréhension (ou liste en intension)

@item liste en compréhension (ou liste en intension)

Écriture concise pour manipuler tout ou partie des éléments d'une séquence et renvoyer une liste contenant les résultats. @code{result = ['@{:#04x@}'.format(x) for x in range(256) if x % 2 == 0]} génère la liste composée des nombres pairs de 0 à 255 écrits sous formes de chaînes de caractères et en hexadécimal (@code{0x…}). La clause @ref{2e7,,if} est optionnelle. Si elle est omise, tous les éléments du @code{range(256)} seront utilisés.
@anchor{glossary term-loader}@anchor{1639}
@geindex chargeur

@item chargeur

An object that loads a module. It must define a method named
@code{load_module()}. A loader is typically returned by a
@ref{1ea3,,finder}. See also:


@itemize *

@item 
@ref{1f75,,Chercheurs et chargeurs}

@item 
@ref{eb0,,importlib.abc.Loader}

@item 
@geindex Python Enhancement Proposals; PEP 302
PEP 302@footnote{https://peps.python.org/pep-0302/}
@end itemize
@anchor{glossary term-locale-encoding}@anchor{23f}
@geindex encodage régional

@item encodage régional

Sous Unix, il est défini par la variable régionale LC_CTYPE. Il peut être modifié par @ref{2da,,locale.setlocale(locale.LC_CTYPE@comma{} new_locale)}.

Sous Windows, c'est un encodage ANSI (par ex. : @code{"cp1252"}).

Sous Android et VxWorks, Python utilise @code{"utf-8"} comme encodage régional.

@ref{2db,,locale.getencoding()} can be used to get the locale encoding.

Voir aussi l'@ref{525,,encodage du systèmes de fichiers et gestionnaire d'erreurs associé}.
@anchor{glossary term-magic-method}@anchor{402b}
@geindex méthode magique

@item méthode magique

@geindex magic;méthode

Un synonyme informel de @ref{1839,,special method}.
@anchor{glossary term-mapping}@anchor{1199}
@geindex tableau de correspondances (mapping en anglais)

@item tableau de correspondances (`mapping' en anglais)

Conteneur permettant de rechercher des éléments à partir de clés et implémentant les méthodes spécifiées dans les classes mères abstraites des @ref{8b7,,tableaux de correspondances} (immuables) ou @ref{1090,,tableaux de correspondances mutables} (voir les @ref{863,,classes mères abstraites}). Les classes suivantes sont des exemples de tableaux de correspondances : @ref{253,,dict}, @ref{119a,,collections.defaultdict}, @ref{5c5,,collections.OrderedDict} et @ref{107b,,collections.Counter}.
@anchor{glossary term-meta-path-finder}@anchor{1059}
@geindex chercheur dans les méta-chemins

@item chercheur dans les méta-chemins

Un @ref{1ea3,,chercheur} renvoyé par une recherche dans @ref{d19,,sys.meta_path}. Les chercheurs dans les méta-chemins ressemblent, mais sont différents des @ref{105a,,chercheurs d'entrée dans path}.

Voir @ref{859,,importlib.abc.MetaPathFinder} pour les méthodes que les chercheurs dans les méta-chemins doivent implémenter.
@anchor{glossary term-metaclass}@anchor{1f09}
@geindex métaclasse

@item métaclasse

Classe d'une classe. Les définitions de classe créent un nom pour la classe, un dictionnaire de classe et une liste de classes parentes. La métaclasse a pour rôle de réunir ces trois paramètres pour construire la classe. La plupart des langages orientés objet fournissent une implémentation par défaut. La particularité de Python est la possibilité de créer des métaclasses personnalisées. La plupart des utilisateurs n'auront jamais besoin de cet outil, mais lorsque le besoin survient, les métaclasses offrent des solutions élégantes et puissantes. Elles sont utilisées pour journaliser les accès à des propriétés, rendre sûrs les environnements `multi-threads', suivre la création d'objets, implémenter des singletons et bien d'autres tâches.

Plus d'informations sont disponibles dans : @ref{1ef6,,Métaclasses}.
@anchor{glossary term-method}@anchor{5030}
@geindex méthode

@item méthode

Fonction définie à l'intérieur d'une classe. Lorsqu'elle est appelée comme un attribut d'une instance de cette classe, la méthode reçoit l'instance en premier @ref{432,,argument} (qui, par convention, est habituellement nommé @code{self}). Voir @ref{1fd8,,function} et @ref{1ec3,,nested scope}.
@anchor{glossary term-method-resolution-order}@anchor{2109}
@geindex ordre de résolution des méthodes

@item ordre de résolution des méthodes

Method Resolution Order is the order in which base classes are searched
for a member during lookup. See @ref{145e,,The Python 2.3 Method Resolution Order} for details of the
algorithm used by the Python interpreter since the 2.3 release.
@anchor{glossary term-module}@anchor{15e8}
@geindex module

@item module

Objet utilisé pour organiser une portion unitaire de code en Python. Les modules ont un espace de nommage et peuvent contenir n'importe quels objets Python. Charger des modules est appelé @ref{503a,,importer}.

Voir aussi @ref{1e9f,,paquet}.
@anchor{glossary term-module-spec}@anchor{1e9b}
@geindex spécificateur de module

@item spécificateur de module

Espace de nommage contenant les informations, relatives à l'importation, utilisées pour charger un module. C'est une instance de la classe @ref{1ded,,importlib.machinery.ModuleSpec}.

See also @ref{1e9e,,Spécificateurs de modules}.
@anchor{glossary term-MRO}@anchor{3556}
@geindex MRO

@item MRO

Voir @ref{2109,,ordre de résolution des méthodes}.
@anchor{glossary term-mutable}@anchor{1b8e}
@geindex mutable

@item mutable

Un objet mutable peut changer de valeur tout en gardant le même @ref{13d9,,id()}. Voir aussi @ref{97e,,immuable}.
@anchor{glossary term-named-tuple}@anchor{639}
@geindex n-uplet nommé

@item `n'-uplet nommé

Le terme "n-uplet nommé" s'applique à tous les types ou classes qui héritent de la classe @code{tuple} et dont les éléments indexables sont aussi accessibles en utilisant des attributs nommés. Les types et classes peuvent avoir aussi d'autres caractéristiques.

Plusieurs types natifs sont appelés n-uplets, y compris les valeurs retournées par @ref{14af,,time.localtime()} et @ref{48a,,os.stat()}. Un autre exemple est @ref{1979,,sys.float_info} :

@example
>>> sys.float_info[1]                   # indexed access
1024
>>> sys.float_info.max_exp              # named field access
1024
>>> isinstance(sys.float_info, tuple)   # kind of tuple
True
@end example

Some named tuples are built-in types (such as the above examples).
Alternatively, a named tuple can be created from a regular class
definition that inherits from @ref{366,,tuple} and that defines named
fields.  Such a class can be written by hand, or it can be created by
inheriting @ref{2ad,,typing.NamedTuple}, or with the factory function
@ref{1c5,,collections.namedtuple()}.  The latter techniques also add some
extra methods that may not be found in hand-written or built-in named
tuples.
@anchor{glossary term-namespace}@anchor{1be5}
@geindex espace de nommage

@item espace de nommage

L'endroit où une variable est stockée. Les espaces de nommage sont implémentés avec des dictionnaires. Il existe des espaces de nommage globaux, natifs ou imbriqués dans les objets (dans les méthodes). Les espaces de nommage favorisent la modularité car ils permettent d'éviter les conflits de noms. Par exemple, les fonctions @ref{505,,builtins.open} et @ref{d7f,,os.open()} sont différenciées par leurs espaces de nom. Les espaces de nommage aident aussi à la lisibilité et la maintenabilité en rendant clair quel module implémente une fonction. Par exemple, écrire @ref{1252,,random.seed()} ou @ref{b3a,,itertools.islice()} affiche clairement que ces fonctions sont implémentées respectivement dans les modules @ref{b7,,random} et @ref{80,,itertools}.
@anchor{glossary term-namespace-package}@anchor{1bf6}
@geindex paquet-espace de nommage

@item paquet-espace de nommage

Un @ref{1e9f,,paquet} tel que défini dans la 
@geindex Python Enhancement Proposals; PEP 421
PEP 421@footnote{https://peps.python.org/pep-0421/} qui ne sert qu'à contenir des sous-paquets. Les paquets-espace de nommage peuvent n'avoir aucune représentation physique et, plus spécifiquement, ne sont pas comme un @ref{1f70,,paquet classique} puisqu'ils n'ont pas de fichier @code{__init__.py}.

Voir aussi @ref{15e8,,module}.
@anchor{glossary term-nested-scope}@anchor{1ec3}
@geindex portée imbriquée

@item portée imbriquée

Possibilité de faire référence à une variable déclarée dans une définition englobante. Typiquement, une fonction définie à l'intérieur d'une autre fonction a accès aux variables de cette dernière. Souvenez-vous cependant que cela ne fonctionne que pour accéder à des variables, pas pour les assigner. Les variables locales sont lues et assignées dans l'espace de nommage le plus proche. Tout comme les variables globales qui sont stockés dans l'espace de nommage global, le mot clef @ref{1285,,nonlocal} permet d'écrire dans l'espace de nommage dans lequel est déclarée la variable.
@anchor{glossary term-new-style-class}@anchor{2809}
@geindex nouvelle classe

@item nouvelle classe

Old name for the flavor of classes now used for all class objects.  In
earlier Python versions, only new-style classes could use Python's newer,
versatile features like @ref{14a0,,__slots__}, descriptors,
properties, @ref{bc0,,__getattribute__()}, class methods, and static
methods.
@anchor{glossary term-object}@anchor{299b}
@geindex objet

@item objet

N'importe quelle donnée comportant des états (sous forme d'attributs ou d'une valeur) et un comportement (des méthodes). C'est aussi (@code{object}) l'ancêtre commun à absolument toutes les @ref{2809,,nouvelles classes}.
@anchor{glossary term-optimized-scope}@anchor{17c}
@geindex optimized scope

@item optimized scope

A scope where target local variable names are reliably known to the
compiler when the code is compiled, allowing optimization of read and
write access to these names. The local namespaces for functions,
generators, coroutines, comprehensions, and generator expressions are
optimized in this fashion. Note: most interpreter optimizations are
applied to all scopes, only those relying on a known set of local
and nonlocal variable names are restricted to optimized scopes.
@anchor{glossary term-package}@anchor{1e9f}
@geindex paquet

@item paquet

@ref{15e8,,module} Python qui peut contenir des sous-modules ou des sous-paquets. Techniquement, un paquet est un module qui possède un attribut @code{__path__}.

Voir aussi @ref{1f70,,paquet classique} et @ref{1bf6,,namespace package}.
@anchor{glossary term-parameter}@anchor{1e82}
@geindex paramètre

@item paramètre

Entité nommée dans la définition d'une @ref{1fd8,,fonction} (ou méthode), décrivant un @ref{432,,argument} (ou dans certains cas des arguments) que la fonction accepte. Il existe cinq sortes de paramètres :


@itemize *

@item 
`positional-or-keyword' : l'argument peut être passé soit par sa @ref{432,,position}, soit en tant que @ref{432,,argument nommé}. C'est le type de paramètre par défaut. Par exemple, `foo' et `bar' dans l'exemple suivant :

@example
def func(foo, bar=None): ...
@end example
@end itemize
@anchor{glossary positional-only-parameter}@anchor{a73}

@itemize *

@item 
`positional-only' : définit un argument qui ne peut être fourni que par position. Les paramètres `positional-only' peuvent être définis en insérant un caractère "/" dans la liste de paramètres de la définition de fonction après eux. Par exemple : `posonly1' et `posonly2' dans le code suivant :

@example
def func(posonly1, posonly2, /, positional_or_keyword): ...
@end example
@end itemize
@anchor{glossary keyword-only-parameter}@anchor{2a2}

@itemize *

@item 
`keyword-only' : l'argument ne peut être fourni que nommé. Les paramètres `keyword-only' peuvent être définis en utilisant un seul paramètre `var-positional', ou en ajoutant une étoile (@code{*}) seule dans la liste des paramètres avant eux. Par exemple, `kw_only1' et `kw_only2' dans le code suivant :

@example
def func(arg, *, kw_only1, kw_only2): ...
@end example

@item 
`var-positional' : une séquence d'arguments positionnels peut être fournie (en plus de tous les arguments positionnels déjà acceptés par d'autres paramètres). Un tel paramètre peut être défini en préfixant son nom par une @code{*}. Par exemple `args' ci-après :

@example
def func(*args, **kwargs): ...
@end example

@item 
`var-keyword' : une quantité arbitraire d'arguments peut être passée, chacun étant nommé (en plus de tous les arguments nommés déjà acceptés par d'autres paramètres). Un tel paramètre est défini en préfixant le nom du paramètre par @code{**}. Par exemple, `kwargs' ci-dessus.
@end itemize

Les paramètres peuvent spécifier des arguments obligatoires ou optionnels, ainsi que des valeurs par défaut pour les arguments optionnels.

Voir aussi @ref{432,,argument} dans le glossaire, la question sur @ref{4f73,,la différence entre les arguments et les paramètres} dans la FAQ, la classe @ref{1cb,,inspect.Parameter}, la section @ref{1bc4,,Définition de fonctions} et la 
@geindex Python Enhancement Proposals; PEP 362
PEP 362@footnote{https://peps.python.org/pep-0362/}.
@anchor{glossary term-path-entry}@anchor{1f85}
@geindex entrée de chemin

@item entrée de chemin

Emplacement dans le @ref{1f77,,chemin des importations} (`import path' en anglais, d'où le `path') que le @ref{1f7a,,chercheur basé sur les chemins} consulte pour trouver des modules à importer.
@anchor{glossary term-path-entry-finder}@anchor{105a}
@geindex chercheur de chemins

@item chercheur de chemins

@ref{1ea3,,chercheur} renvoyé par un appelable sur un @ref{100d,,sys.path_hooks} (c'est-à-dire un @ref{1f87,,point d'entrée pour la recherche dans path}) qui sait où trouver des modules lorsqu'on lui donne une @ref{1f85,,entrée de path}.

Voir @ref{85a,,importlib.abc.PathEntryFinder} pour les méthodes qu'un chercheur d'entrée dans `path' doit implémenter.
@anchor{glossary term-path-entry-hook}@anchor{1f87}
@geindex point d'entrée pour la recherche dans path

@item point d'entrée pour la recherche dans `path'

A callable on the @ref{100d,,sys.path_hooks} list which returns a @ref{105a,,path entry finder} if it knows how to find modules on a specific @ref{1f85,,path entry}.
@anchor{glossary term-path-based-finder}@anchor{1f7a}
@geindex chercheur basé sur les chemins

@item chercheur basé sur les chemins

L'un des @ref{1059,,chercheurs dans les méta-chemins} par défaut qui cherche des modules dans un @ref{1f77,,chemin des importations}.
@anchor{glossary term-path-like-object}@anchor{29d}
@geindex objet simili-chemin

@item objet simili-chemin

Objet représentant un chemin du système de fichiers. Un objet simili-chemin est un objet @ref{435,,str} ou un objet @ref{1bd,,bytes} représentant un chemin ou un objet implémentant le protocole @ref{c3f,,os.PathLike}. Un objet qui accepte le protocole @ref{c3f,,os.PathLike} peut être converti en un chemin @ref{435,,str} ou @ref{1bd,,bytes} du système de fichiers en appelant la fonction @ref{c41,,os.fspath()}. @ref{c42,,os.fsdecode()} et @ref{c43,,os.fsencode()} peuvent être utilisées, respectivement, pour garantir un résultat de type @ref{435,,str} ou @ref{1bd,,bytes} à la place. A été Introduit par la 
@geindex Python Enhancement Proposals; PEP 519
PEP 519@footnote{https://peps.python.org/pep-0519/}.
@anchor{glossary term-PEP}@anchor{503d}
@geindex PEP

@item PEP

`Python Enhancement Proposal' (Proposition d'amélioration de Python). Une PEP est un document de conception fournissant des informations à la communauté Python ou décrivant une nouvelle fonctionnalité pour Python, ses processus ou son environnement. Les PEP doivent fournir une spécification technique concise et une justification des fonctionnalités proposées.

Les PEP sont censées être les principaux mécanismes pour proposer de nouvelles fonctionnalités majeures, pour recueillir les commentaires de la communauté sur une question et pour documenter les décisions de conception qui sont intégrées en Python. L’auteur du PEP est responsable de l’établissement d’un consensus au sein de la communauté et de documenter les opinions contradictoires.

Voir la 
@geindex Python Enhancement Proposals; PEP 1
PEP 1@footnote{https://peps.python.org/pep-0001/}.
@anchor{glossary term-portion}@anchor{1f72}
@geindex portion

@item portion

Jeu de fichiers dans un seul dossier (pouvant être stocké sous forme de fichier zip) qui contribue à l'espace de nommage d'un paquet, tel que défini dans la 
@geindex Python Enhancement Proposals; PEP 420
PEP 420@footnote{https://peps.python.org/pep-0420/}.
@anchor{glossary term-positional-argument}@anchor{d01}
@geindex argument positionnel

@item argument positionnel

Voir @ref{432,,argument}.
@anchor{glossary term-provisional-API}@anchor{af1}
@geindex API provisoire

@item API provisoire

Une API provisoire est une API qui n'offre aucune garantie de rétrocompatibilité (la bibliothèque standard exige la rétrocompatibilité). Bien que des changements majeurs d'une telle interface ne soient pas attendus, tant qu'elle est étiquetée provisoire, des changements cassant la rétrocompatibilité (y compris sa suppression complète) peuvent survenir si les développeurs principaux le jugent nécessaire. Ces modifications ne surviendront que si de sérieux problèmes sont découverts et qu'ils n'avaient pas été identifiés avant l'ajout de l'API.

Même pour les API provisoires, les changements cassant la rétrocompatibilité sont considérés comme des "solutions de dernier recours". Tout ce qui est possible sera fait pour tenter de résoudre les problèmes en conservant la rétrocompatibilité.

Ce processus permet à la bibliothèque standard de continuer à évoluer avec le temps, sans se bloquer longtemps sur des erreurs d'architecture. Voir la 
@geindex Python Enhancement Proposals; PEP 411
PEP 411@footnote{https://peps.python.org/pep-0411/} pour plus de détails.
@anchor{glossary term-provisional-package}@anchor{102a}
@geindex paquet provisoire

@item paquet provisoire

Voir @ref{af1,,provisional API}.
@anchor{glossary term-Python-3000}@anchor{503e}
@geindex Python 3000

@item Python 3000

Surnom donné à la série des Python 3.x (très vieux surnom donné à l'époque où Python 3 représentait un futur lointain). Aussi abrégé `Py3k'.
@anchor{glossary term-Pythonic}@anchor{503f}
@geindex Pythonique

@item `Pythonique'

Idée, ou bout de code, qui colle aux idiomes de Python plutôt qu'aux concepts communs rencontrés dans d'autres langages. Par exemple, il est idiomatique en Python de parcourir les éléments d'un itérable en utilisant @ref{2e6,,for}. Beaucoup d'autres langages n'ont pas cette possibilité, donc les gens qui ne sont pas habitués à Python utilisent parfois un compteur numérique à la place :

@example
for i in range(len(food)):
    print(food[i])
@end example

Plutôt qu'utiliser la méthode, plus propre et élégante, donc `Pythonique' :

@example
for piece in food:
    print(piece)
@end example
@anchor{glossary term-qualified-name}@anchor{18ce}
@geindex nom qualifié

@item nom qualifié

Nom, comprenant des points, montrant le "chemin" de l'espace de nommage global d'un module vers une classe, fonction ou méthode définie dans ce module, tel que défini dans la 
@geindex Python Enhancement Proposals; PEP 3155
PEP 3155@footnote{https://peps.python.org/pep-3155/}. Pour les fonctions et classes de premier niveau, le nom qualifié est le même que le nom de l'objet :

@example
>>> class C:
...     class D:
...         def meth(self):
...             pass
...
>>> C.__qualname__
'C'
>>> C.D.__qualname__
'C.D'
>>> C.D.meth.__qualname__
'C.D.meth'
@end example

Lorsqu'il est utilisé pour nommer des modules, le `nom qualifié complet' (`fully qualified name - FQN' en anglais) signifie le chemin complet (séparé par des points) vers le module, incluant tous les paquets parents. Par exemple : @code{email.mime.text} :

@example
>>> import email.mime.text
>>> email.mime.text.__name__
'email.mime.text'
@end example
@anchor{glossary term-reference-count}@anchor{47e8}
@geindex nombre de références

@item nombre de références

The number of references to an object.  When the reference count of an
object drops to zero, it is deallocated.  Some objects are
@ref{42aa,,immortal} and have reference counts that are never modified, and
therefore the objects are never deallocated.  Reference counting is
generally not visible to Python code, but it is a key element of the
@ref{6e0,,CPython} implementation.  Programmers can call the
@ref{42a9,,sys.getrefcount()} function to return the
reference count for a particular object.
@anchor{glossary term-regular-package}@anchor{1f70}
@geindex paquet classique

@item paquet classique

@ref{1e9f,,paquet} traditionnel, tel qu'un dossier contenant un fichier @code{__init__.py}.

Voir aussi @ref{1bf6,,paquet-espace de nommage}.
@anchor{glossary term-REPL}@anchor{169}
@geindex REPL

@item REPL

An acronym for the "read–eval–print loop", another name for the
@ref{168,,interactive} interpreter shell.
@anchor{glossary term-__slots__}@anchor{5c9}
@geindex __slots__

@item __slots__

Déclaration dans une classe qui économise de la mémoire en pré-allouant de l'espace pour les attributs des instances et qui élimine le dictionnaire (des attributs) des instances. Bien que populaire, cette technique est difficile à maîtriser et devrait être réservée à de rares cas où un grand nombre d'instances dans une application devient un sujet critique pour la mémoire.
@anchor{glossary term-sequence}@anchor{4db}
@geindex séquence

@item séquence

An @ref{1205,,iterable} which supports efficient element access using integer
indices via the @ref{280,,__getitem__()} special method and defines a
@ref{1ee5,,__len__()} method that returns the length of the sequence.
Some built-in sequence types are @ref{5fc,,list}, @ref{435,,str},
@ref{366,,tuple}, and @ref{1bd,,bytes}. Note that @ref{253,,dict} also
supports @ref{280,,__getitem__()} and @code{__len__()}, but is considered a
mapping rather than a sequence because the lookups use arbitrary
@ref{5fb,,hashable} keys rather than integers.

The @ref{11a1,,collections.abc.Sequence} abstract base class
defines a much richer interface that goes beyond just
@ref{280,,__getitem__()} and @ref{1ee5,,__len__()}, adding
@code{count()}, @code{index()}, @ref{1ee0,,__contains__()}, and
@ref{1edf,,__reversed__()}. Types that implement this expanded
interface can be registered explicitly using
@ref{1072,,register()}. For more documentation on sequence
methods generally, see
@ref{2132,,Common Sequence Operations}.
@anchor{glossary term-set-comprehension}@anchor{5040}
@geindex ensemble en compréhension (ou ensemble en intension)

@item ensemble en compréhension (ou ensemble en intension)

Une façon compacte de traiter tout ou partie des éléments d'un itérable et de renvoyer un `set' avec les résultats. @code{results = @{c for c in 'abracadabra' if c not in 'abc'@}} génère l'ensemble contenant les lettres « r » et « d » @code{@{'r', 'd'@}}. Voir @ref{5ba,,Agencements des listes@comma{} ensembles et dictionnaires}.
@anchor{glossary term-single-dispatch}@anchor{9e0}
@geindex distribution simple

@item distribution simple

Forme de distribution, comme les @ref{9df,,fonction génériques}, où l'implémentation est choisie en fonction du type d'un seul argument.
@anchor{glossary term-slice}@anchor{2106}
@geindex tranche

@item tranche

(`slice' en anglais), un objet contenant habituellement une portion de @ref{4db,,séquence}. Une tranche est créée en utilisant la notation @code{[]} avec des @code{:} entre les nombres lorsque plusieurs sont fournis, comme dans @code{variable_name[1:3:5]}. Cette notation utilise des objets @ref{453,,slice} en interne.
@anchor{glossary term-soft-deprecated}@anchor{206}
@geindex soft deprecated

@item soft deprecated

A soft deprecated API should not be used in new code,
but it is safe for already existing code to use it.
The API remains documented and tested, but will not be enhanced further.

Soft deprecation, unlike normal deprecation, does not plan on removing the API
and will not emit warnings.

See PEP 387: Soft Deprecation@footnote{https://peps.python.org/pep-0387/#soft-deprecation}.
@anchor{glossary term-special-method}@anchor{1839}
@geindex méthode spéciale

@item méthode spéciale

@geindex special;méthode

(`special method' en anglais) Méthode appelée implicitement par Python pour exécuter une opération sur un type, comme une addition. De telles méthodes ont des noms commençant et terminant par des doubles tirets bas. Les méthodes spéciales sont documentées dans @ref{c5c,,Méthodes spéciales}.
@anchor{glossary term-statement}@anchor{2704}
@geindex instruction

@item instruction

Une instruction (`statement' en anglais) est un composant d'un "bloc" de code. Une instruction est soit une @ref{1f08,,expression}, soit une ou plusieurs constructions basées sur un mot-clé, comme @ref{2e7,,if}, @ref{1b92,,while} ou @ref{2e6,,for}.
@anchor{glossary term-static-type-checker}@anchor{26a}
@geindex static type checker

@item static type checker

An external tool that reads Python code and analyzes it, looking for
issues such as incorrect types. See also @ref{1f04,,type hints}
and the @ref{103,,typing} module.
@anchor{glossary term-strong-reference}@anchor{333}
@geindex référence forte

@item référence forte

In Python's C API, a strong reference is a reference to an object
which is owned by the code holding the reference.  The strong
reference is taken by calling @ref{55a,,Py_INCREF()} when the
reference is created and released with @ref{55b,,Py_DECREF()}
when the reference is deleted.

Une référence forte est créée à l'aide de la fonction @ref{886,,Py_NewRef()}. Il faut normalement appeler @ref{55b,,Py_DECREF()} dessus avant de sortir de sa portée lexicale, sans quoi il y a une fuite de référence.

Voir aussi @ref{334,,référence empruntée}.
@anchor{glossary term-text-encoding}@anchor{2101}
@geindex encodages de texte

@item encodages de texte

Une chaîne de caractères en Python est une suite de points de code Unicode (dans l'intervalle @code{U+0000}--@code{U+10FFFF}). Pour stocker ou transmettre une chaîne, il est nécessaire de la sérialiser en suite d'octets.

Sérialiser une chaîne de caractères en une suite d'octets s'appelle « encoder » et recréer la chaîne à partir de la suite d'octets s'appelle « décoder ».

Il existe de multiples @ref{da6,,codecs} pour la sérialisation de texte, que l'on regroupe sous l'expression « encodages de texte ».
@anchor{glossary term-text-file}@anchor{1c14}
@geindex fichier texte

@item fichier texte

@ref{11a0,,Objet fichier} capable de lire et d'écrire des objets @ref{435,,str}. Souvent, un fichier texte (`text file' en anglais) accède en fait à un flux de donnée en octets et gère l'@ref{2101,,encodage de texte} automatiquement. Des exemples de fichiers textes sont les fichiers ouverts en mode texte (@code{'r'} ou @code{'w'}), @ref{527,,sys.stdin}, @ref{ac4,,sys.stdout} et les instances de @ref{f12,,io.StringIO}.

Voir aussi @ref{1c15,,fichier binaire} pour un objet fichier capable de lire et d'écrire des @ref{d1b,,objets octets-compatibles}.
@anchor{glossary term-triple-quoted-string}@anchor{5041}
@geindex chaîne entre triple guillemets

@item chaîne entre triple guillemets

Chaîne qui est délimitée par trois guillemets simples (@code{'}) ou trois guillemets doubles (@code{"}). Bien qu'elle ne fournisse aucune fonctionnalité qui ne soit pas disponible avec une chaîne entre guillemets, elle est utile pour de nombreuses raisons. Elle vous autorise à insérer des guillemets simples et doubles dans une chaîne sans avoir à les protéger et elle peut s'étendre sur plusieurs lignes sans avoir à terminer chaque ligne par un @code{\}. Elle est ainsi particulièrement utile pour les chaînes de documentation (`docstrings').
@anchor{glossary term-type}@anchor{18c0}
@geindex type

@item type

The type of a Python object determines what kind of object it is; every
object has a type.  An object's type is accessible as its
@ref{1461,,__class__} attribute or can be retrieved with
@code{type(obj)}.
@anchor{glossary term-type-alias}@anchor{423}
@geindex alias de type

@item alias de type

Synonyme d'un type, créé en affectant le type à un identifiant.

Les alias de types sont utiles pour simplifier les @ref{1f04,,indications de types}. Par exemple :

@example
def remove_gray_shades(
        colors: list[tuple[int, int, int]]) -> list[tuple[int, int, int]]:
    pass
@end example

pourrait être rendu plus lisible comme ceci :

@example
Color = tuple[int, int, int]

def remove_gray_shades(colors: list[Color]) -> list[Color]:
    pass
@end example

Voir @ref{103,,typing} et la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, qui décrivent cette fonctionnalité.
@anchor{glossary term-type-hint}@anchor{1f04}
@geindex indication de type

@item indication de type

L'@ref{441,,annotation} qui spécifie le type attendu pour une variable, un attribut de classe, un paramètre de fonction ou une valeur de retour.

Type hints are optional and are not enforced by Python but
they are useful to @ref{26a,,static type checkers}.
They can also aid IDEs with code completion and refactoring.

Les indications de type de variables globales, d'attributs de classe et de fonctions, mais pas de variables locales, peuvent être consultées en utilisant @ref{69c,,typing.get_type_hints()}.

Voir @ref{103,,typing} et la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/}, qui décrivent cette fonctionnalité.
@anchor{glossary term-universal-newlines}@anchor{d28}
@geindex retours à la ligne universels

@item retours à la ligne universels

Une manière d'interpréter des flux de texte dans lesquels sont reconnues toutes les fins de ligne suivantes : la convention Unix @code{'\n'}, la convention Windows @code{'\r\n'} et l'ancienne convention Macintosh @code{'\r'}. Voir la 
@geindex Python Enhancement Proposals; PEP 278
PEP 278@footnote{https://peps.python.org/pep-0278/} et la 
@geindex Python Enhancement Proposals; PEP 3116
PEP 3116@footnote{https://peps.python.org/pep-3116/}, ainsi que la fonction @ref{219d,,bytes.splitlines()} pour d'autres usages.
@anchor{glossary term-variable-annotation}@anchor{d43}
@geindex annotation de variable

@item annotation de variable

@ref{441,,annotation} d'une variable ou d'un attribut de classe.

Lorsque vous annotez une variable ou un attribut de classe, l'affectation est facultative :

@example
class C:
    field: 'annotation'
@end example

Les annotations de variables sont généralement utilisées pour des @ref{1f04,,indications de types} : par exemple, cette variable devrait prendre des valeurs de type @ref{254,,int} :

@example
count: int = 0
@end example

La syntaxe d'annotation de variable est expliquée dans la section @ref{2027,,Les assignations annotées}.

Reportez-vous à @ref{1bc5,,annotation de fonction}, à la 
@geindex Python Enhancement Proposals; PEP 484
PEP 484@footnote{https://peps.python.org/pep-0484/} et à la 
@geindex Python Enhancement Proposals; PEP 526
PEP 526@footnote{https://peps.python.org/pep-0526/} qui décrivent cette fonctionnalité. Voir aussi @ref{7c3,,Bonnes pratiques concernant les annotations} sur les bonnes pratiques concernant les annotations.
@anchor{glossary term-virtual-environment}@anchor{1c8e}
@geindex environnement virtuel

@item environnement virtuel

Environnement d'exécution isolé (en mode coopératif) qui permet aux utilisateurs de Python et aux applications d'installer et de mettre à jour des paquets sans interférer avec d'autres applications Python fonctionnant sur le même système.

Voir aussi @ref{110,,venv}.
@anchor{glossary term-virtual-machine}@anchor{3458}
@geindex machine virtuelle

@item machine virtuelle

Ordinateur défini entièrement par du logiciel. La machine virtuelle (`virtual machine') de Python exécute le @ref{185,,code intermédiaire} produit par le compilateur de `bytecode'.
@anchor{glossary term-Zen-of-Python}@anchor{5042}
@geindex Le zen de Python

@item Le zen de Python

Liste de principes et de préceptes utiles pour comprendre et utiliser le langage. Cette liste peut être obtenue en tapant "@code{import this}" dans une invite Python interactive.
@end table

@node About this documentation,S'attaquer aux bogues,Glossaire,Top
@anchor{about doc}@anchor{5043}@anchor{about about-this-documentation}@anchor{5044}
@chapter About this documentation


Python's documentation is generated from reStructuredText@footnote{https://docutils.sourceforge.io/rst.html} sources
using Sphinx@footnote{https://www.sphinx-doc.org/}, a documentation generator originally created for Python
and now maintained as an independent project.

@c In the online version of these documents, you can submit comments and suggest
@c changes directly on the documentation pages.

Le développement de la documentation et de ses outils est entièrement basé sur le volontariat, tout comme Python. Si vous voulez contribuer, allez voir la page @ref{4838,,S'attaquer aux bogues} qui contient des informations pour vous y aider. Les nouveaux volontaires sont toujours les bienvenus !

Merci beaucoup à :


@itemize *

@item 
Fred L. Drake, Jr., the creator of the original Python documentation toolset
and author of much of the content;

@item 
le projet Docutils@footnote{https://docutils.sourceforge.io/} pour avoir créé `reStructuredText' et la suite d'outils `Docutils' ;

@item 
Fredrik Lundh pour son projet `Alternative Python Reference', dont Sphinx a pris beaucoup de bonnes idées.
@end itemize

@menu
* Contributors to the Python documentation:: 

@end menu

@node Contributors to the Python documentation,,,About this documentation
@anchor{about contributors-to-the-python-documentation}@anchor{5045}
@section Contributors to the Python documentation


De nombreuses personnes ont contribué au langage Python, à sa bibliothèque standard et à sa documentation. Consultez Misc/ACKS@footnote{https://github.com/python/cpython/tree/3.13/Misc/ACKS} dans les sources de la distribution Python pour avoir une liste partielle des contributeurs.

Ce n'est que grâce aux suggestions et contributions de la communauté Python que Python a une documentation si merveilleuse — Merci !

@node S'attaquer aux bogues,Copyright,About this documentation,Top
@anchor{bugs doc}@anchor{5046}@anchor{bugs dealing-with-bugs}@anchor{5047}@anchor{bugs reporting-bugs}@anchor{4838}
@chapter S'attaquer aux bogues


Python est un langage de programmation robuste réputé pour sa stabilité. Afin de maintenir cette réputation, les développeurs souhaitent connaître tout problème que vous pourriez rencontrer dans Python.

Il est parfois plus rapide de réparer les bogues soi-même et d'en proposer les correctifs, ça simplifie le processus et implique moins de monde. Apprenez à @ref{5048,,contribuer}.

@menu
* Bogues de documentation:: 
* Utilisation du gestionnaire de tickets Python:: 
* Commencer à contribuer à Python vous-même:: 

@end menu

@node Bogues de documentation,Utilisation du gestionnaire de tickets Python,,S'attaquer aux bogues
@anchor{bugs documentation-bugs}@anchor{5049}
@section Bogues de documentation


Si vous trouvez un bogue dans cette documentation ou si vous désirez proposer une amélioration, si cela concerne aussi la documentation en anglais, ouvrez un rapport sur le @ref{24b,,traqueur} décrivant en anglais le bogue et où vous l'avez trouvé. Si le problème ne touche que la traduction en français, ouvrez un ticket sur @indicateurl{https://git.afpy.org/AFPy/python-docs-fr/issues}, ou venez nous en toucher un mot sur le canal #python-fr sur `libera.chat' (@indicateurl{https://kiwiirc.com/nextclient/#irc://irc.libera.chat}/#python-fr). Si vous avez une suggestion de correction, merci de l'inclure également.

Vous pouvez aussi commenter une discussion sur le forum de discussion de la documentation@footnote{https://discuss.python.org/c/documentation/26}.

If you find a bug in the theme (HTML / CSS / JavaScript) of the
documentation, please submit a bug report on the python-doc-theme bug tracker@footnote{https://github.com/python/python-docs-theme}.

Si vous êtes limité par le temps, vous pouvez aussi envoyer un courriel à @email{docs@@python.org} (les bogues de comportement peuvent être envoyés à @email{python-list@@python.org}). « docs@@ » est une liste de diffusion gérée par des volontaires, votre requête sera vue, mais elle peut prendre un moment pour être traitée.


@subsubheading Voir aussi



@table @asis

@item @ref{5049,,Bogues de documentation}

Liste des bogues de documentation soumis à l'outil de suivi des problèmes Python.

@item Outil de suivi des problèmes@footnote{https://devguide.python.org/tracker/}

Vue d'ensemble du processus pour proposer une amélioration avec l'outil de suivi.

@item Aider avec la documentation@footnote{https://devguide.python.org/docquality/#helping-with-documentation}

Guide complet pour qui souhaite contribuer à la documentation Python.

@item Traductions de la Documentation@footnote{https://devguide.python.org/documentation/translating/}

Liste de dépôts GitHub où la documentation est traduite, avec les personnes à contacter.
@end table


@node Utilisation du gestionnaire de tickets Python,Commencer à contribuer à Python vous-même,Bogues de documentation,S'attaquer aux bogues
@anchor{bugs using-the-python-issue-tracker}@anchor{504a}@anchor{bugs using-the-tracker}@anchor{24b}
@section Utilisation du gestionnaire de tickets Python


Les rapports concernant un problème relatif à Python lui-même doivent être soumis `via' l'outil de suivi des problèmes de GitHub (@indicateurl{https://github.com/python/cpython/issues}). Le gestionnaire de tickets propose un formulaire Web permettant de saisir des informations pertinentes à soumettre aux développeurs.

La première étape pour remplir un rapport est de déterminer si le problème a déjà été rapporté. L'avantage de cette approche, en plus d'économiser du temps aux développeurs, est d'apprendre ce qui a été fait pour le résoudre ; il se peut que le problème soit déjà résolu dans la prochaine version, ou que des informations complémentaires soient attendues (auquel cas votre contribution est la bienvenue !). Pour ce faire, cherchez dans le gestionnaire de tickets grâce à la boîte de recherche en haut de la page.

Si le problème que vous soumettez n'est pas déjà dans la liste, connectez-vous à GitHub. Si vous n'avez pas déjà un compte GitHub, créez un nouveau compte en cliquant sur le lien « Sign Up ». Il n'est pas possible de soumettre un rapport de bogue de manière anonyme.

Une fois connecté, vous pouvez rapporter un problème. Sélectionnez le bouton `New issue' dans la barre en haut pour ouvrir un nouveau formulaire de rapport.

Le formulaire de rapport contient deux champs, `Title' et `Comment'.

Dans le champ `Title', entrez une `très' brève description du problème rencontré : dix mots ou moins suffiront.

Dans le champ « Commentaire », décrivez le problème de manière détaillée, incluant ce à quoi vous vous attendiez et ce qui s'est vraiment produit. Assurez-vous d'y inclure les éventuels modules d'extensions impliqués et la plateforme matérielle et logicielle vous utilisiez (en incluant les informations de versions).

Chaque rapport sera attribué à un développeur qui déterminera ce qui est nécessaire d'entreprendre pour corriger le problème. Vous recevrez une notification à chaque action concernant le rapport.


@subsubheading Voir aussi



@table @asis

@item Comment signaler des bogues de manière efficace@footnote{https://www.chiark.greenend.org.uk/~sgtatham/bugs.html} (en anglais)

Article qui entre dans les détails sur la manière de créer un rapport de bogue utile. Il décrit quel genre d'information est utile et pourquoi elle est utile.

@item Guide pour la rédaction de rapports de bogues@footnote{https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html}

Conseils pour écrire un bon rapport de bogue. Certains sont spécifiques au projet Mozilla mais présentent des bonnes pratiques générales.
@end table


@node Commencer à contribuer à Python vous-même,,Utilisation du gestionnaire de tickets Python,S'attaquer aux bogues
@anchor{bugs contributing-to-python}@anchor{5048}@anchor{bugs getting-started-contributing-to-python-yourself}@anchor{504b}
@section Commencer à contribuer à Python vous-même


Au-delà de simplement remonter les bogues que vous trouvez, il est aussi apprécié d'y attacher des correctifs. Vous pouvez trouver plus d'informations pour débuter la rédaction de correctifs dans le Python Developer's Guide@footnote{https://devguide.python.org/}. Si vous avez des questions, le core-mentorship mailing list@footnote{https://mail.python.org/mailman3/lists/core-mentorship.python.org/} est un endroit amical pour obtenir des réponses à toutes les questions à propos du processus de corrections de bugs dans Python.

@node Copyright,Histoire et licence,S'attaquer aux bogues,Top
@anchor{copyright doc}@anchor{504c}@anchor{copyright copyright}@anchor{504d}
@chapter Copyright


Python et cette documentation sont :

Copyright © 2001-2024 Python Software Foundation. Tous droits réservés.

Copyright © 2000 `BeOpen.com'. Tous droits réservés.

Copyright © 1995-2000 `Corporation for National Research Initiatives'. Tous droits réservés.

Copyright © 1991-1995 `Stichting Mathematisch Centrum'. Tous droits réservés.


__________________________________________________________________


Voir @ref{504e,,Histoire et licence} pour des informations complètes concernant la licence et les permissions.

@node Histoire et licence,Index des modules Python,Copyright,Top
@anchor{license doc}@anchor{504f}@anchor{license history-and-license}@anchor{504e}@anchor{license id1}@anchor{5050}
@chapter Histoire et licence


@menu
* Histoire du logiciel:: 
* Conditions générales pour accéder à@comma{} ou utiliser@comma{} Python: Conditions générales pour accéder à ou utiliser Python. 
* Licences et remerciements pour les logiciels tiers:: 

@end menu

@node Histoire du logiciel,Conditions générales pour accéder à ou utiliser Python,,Histoire et licence
@anchor{license history-of-the-software}@anchor{5051}
@section Histoire du logiciel


Python a été créé au début des années 1990 par Guido van Rossum, au Stichting Mathematisch Centrum (CWI, voir @indicateurl{https://www.cwi.nl/}) aux Pays-Bas en tant que successeur d'un langage appelé ABC. Guido est l'auteur principal de Python, bien qu'il inclut de nombreuses contributions de la part d'autres personnes.

En 1995, Guido continua son travail sur Python au Corporation for National Research Initiatives (CNRI, voir @indicateurl{https://www.cnri.reston.va.us/}) de Reston, en Viriginie, d'où il diffusa plusieurs versions du logiciel.

En mai 2000, Guido et l'équipe de développement centrale de Python sont partis vers BeOpen.com pour former l'équipe BeOpen PythonLabs. En octobre de la même année, l'équipe de PythonLabs est partie vers Digital Creations (désormais Zope Corporation ; voir @indicateurl{https://www.zope.com/}). En 2001, la Python Software Foundation (PSF, voir @indicateurl{https://www.python.org/psf/}) voit le jour. Il s'agit d'une organisation à but non lucratif détenant les droits de propriété intellectuelle de Python. Zope Corporation en est un sponsor.

Toutes les versions de Python sont Open Source (voir @indicateurl{https://www.opensource.org/} pour la définition d'Open Source). Historiquement, la plupart, mais pas toutes, des versions de Python ont également été compatible avec la GPL, le tableau ci-dessous résume les différentes versions.


@multitable {xxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxx} 
@headitem

Version

@tab

Dérivé de

@tab

Année

@tab

Propriétaire

@tab

Compatible avec la GPL ?

@item

0.9.0 à 1.2

@tab

n/a

@tab

1991-1995

@tab

CWI

@tab

oui

@item

1.3 à 1.5.2

@tab

1.2

@tab

1995-1999

@tab

CNRI

@tab

oui

@item

1.6

@tab

1.5.2

@tab

2000

@tab

CNRI

@tab

non

@item

2.0

@tab

1.6

@tab

2000

@tab

BeOpen.com

@tab

non

@item

1.6.1

@tab

1.6

@tab

2001

@tab

CNRI

@tab

non

@item

2.1

@tab

2.0+1.6.1

@tab

2001

@tab

PSF

@tab

non

@item

2.0.1

@tab

2.0+1.6.1

@tab

2001

@tab

PSF

@tab

oui

@item

2.1.1

@tab

2.1+2.0.1

@tab

2001

@tab

PSF

@tab

oui

@item

2.1.2

@tab

2.1.1

@tab

2002

@tab

PSF

@tab

oui

@item

2.1.3

@tab

2.1.2

@tab

2002

@tab

PSF

@tab

oui

@item

2.2 et ultérieure

@tab

2.1.1

@tab

2001-maintenant

@tab

PSF

@tab

oui

@end multitable


@cartouche
@quotation Note 
Compatible GPL ne signifie pas que nous distribuons Python sous licence GPL. Toutes les licences Python, excepté la licence GPL, vous permettent la distribution d'une version modifiée sans rendre open source ces changements. La licence « compatible GPL » rend possible la diffusion de Python avec un autre logiciel qui est lui, diffusé sous la licence GPL ; les licences « non-compatibles GPL » ne le peuvent pas.
@end quotation
@end cartouche

Merci aux nombreux bénévoles qui ont travaillé sous la direction de Guido pour rendre ces versions possibles.

@node Conditions générales pour accéder à ou utiliser Python,Licences et remerciements pour les logiciels tiers,Histoire du logiciel,Histoire et licence
@anchor{license terms-and-conditions-for-accessing-or-otherwise-using-python}@anchor{5052}
@section Conditions générales pour accéder à, ou utiliser, Python


Le logiciel Python et sa documentation sont distribués sous @ref{5053,,la licence d'utilisation PSF}.

Depuis Python 3.8.6, les exemples, recettes et autres codes présents dans la documentation sont sous la double licence d'utilisation PSF et @ref{5054,,la licence Zero-Clause BSD}.

Certains logiciels faisant partie de Python sont soumis à d'autres licences. Ces licences sont incluses avec le code lié à celles-ci. Voir @ref{5055,,Licences et remerciements pour les logiciels tiers} pour une liste non exhaustive de ces licences.

@menu
* PSF LICENSE AGREEMENT FOR PYTHON 3.13.1: PSF LICENSE AGREEMENT FOR PYTHON 3 13 1. 
* LICENCE D'UTILISATION BEOPEN.COM POUR PYTHON 2.0: LICENCE D'UTILISATION BEOPEN COM POUR PYTHON 2 0. 
* LICENCE D'UTILISATION CNRI POUR PYTHON 1.6.1: LICENCE D'UTILISATION CNRI POUR PYTHON 1 6 1. 
* LICENCE D'UTILISATION CWI POUR PYTHON 0.9.0 à 1.2: LICENCE D'UTILISATION CWI POUR PYTHON 0 9 0 à 1 2. 
* LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3.13.1: LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3 13 1. 

@end menu

@node PSF LICENSE AGREEMENT FOR PYTHON 3 13 1,LICENCE D'UTILISATION BEOPEN COM POUR PYTHON 2 0,,Conditions générales pour accéder à ou utiliser Python
@anchor{license psf-license}@anchor{5053}@anchor{license psf-license-agreement-for-python-release}@anchor{5056}
@subsection PSF LICENSE AGREEMENT FOR PYTHON 3.13.1


@example
1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
   the Individual or Organization ("Licensee") accessing and otherwise using Python
   3.13.1 software in source or binary form and its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF hereby
   grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
   analyze, test, perform and/or display publicly, prepare derivative works,
   distribute, and otherwise use Python 3.13.1 alone or in any derivative
   version, provided, however, that PSF's License Agreement and PSF's notice of
   copyright, i.e., "Copyright © 2001-2024 Python Software Foundation; All Rights
   Reserved" are retained in Python 3.13.1 alone or in any derivative version
   prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or
   incorporates Python 3.13.1 or any part thereof, and wants to make the
   derivative work available to others as provided herein, then Licensee hereby
   agrees to include in any such work a brief summary of the changes made to Python
   3.13.1.

4. PSF is making Python 3.13.1 available to Licensee on an "AS IS" basis.
   PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
   EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
   WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
   USE OF PYTHON 3.13.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.13.1
   FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.13.1, OR ANY DERIVATIVE
   THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any relationship
   of agency, partnership, or joint venture between PSF and Licensee.  This License
   Agreement does not grant permission to use PSF trademarks or trade name in a
   trademark sense to endorse or promote products or services of Licensee, or any
   third party.

8. By copying, installing or otherwise using Python 3.13.1, Licensee agrees
   to be bound by the terms and conditions of this License Agreement.
@end example

@node LICENCE D'UTILISATION BEOPEN COM POUR PYTHON 2 0,LICENCE D'UTILISATION CNRI POUR PYTHON 1 6 1,PSF LICENSE AGREEMENT FOR PYTHON 3 13 1,Conditions générales pour accéder à ou utiliser Python
@anchor{license beopen-com-license-agreement-for-python-2-0}@anchor{5057}
@subsection LICENCE D'UTILISATION BEOPEN.COM POUR PYTHON 2.0


LICENCE D'UTILISATION LIBRE BEOPEN PYTHON VERSION 1

@example
1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at
   160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization
   ("Licensee") accessing and otherwise using this software in source or binary
   form and its associated documentation ("the Software").

2. Subject to the terms and conditions of this BeOpen Python License Agreement,
   BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license
   to reproduce, analyze, test, perform and/or display publicly, prepare derivative
   works, distribute, and otherwise use the Software alone or in any derivative
   version, provided, however, that the BeOpen Python License is retained in the
   Software, alone or in any derivative version prepared by Licensee.

3. BeOpen is making the Software available to Licensee on an "AS IS" basis.
   BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF
   EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
   WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
   USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR
   ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING,
   MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF
   ADVISED OF THE POSSIBILITY THEREOF.

5. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

6. This License Agreement shall be governed by and interpreted in all respects
   by the law of the State of California, excluding conflict of law provisions.
   Nothing in this License Agreement shall be deemed to create any relationship of
   agency, partnership, or joint venture between BeOpen and Licensee.  This License
   Agreement does not grant permission to use BeOpen trademarks or trade names in a
   trademark sense to endorse or promote products or services of Licensee, or any
   third party.  As an exception, the "BeOpen Python" logos available at
   @indicateurl{http://www.pythonlabs.com/logos.html} may be used according to the permissions
   granted on that web page.

7. By copying, installing or otherwise using the software, Licensee agrees to be
   bound by the terms and conditions of this License Agreement.
@end example

@node LICENCE D'UTILISATION CNRI POUR PYTHON 1 6 1,LICENCE D'UTILISATION CWI POUR PYTHON 0 9 0 à 1 2,LICENCE D'UTILISATION BEOPEN COM POUR PYTHON 2 0,Conditions générales pour accéder à ou utiliser Python
@anchor{license cnri-license-agreement-for-python-1-6-1}@anchor{5058}
@subsection LICENCE D'UTILISATION CNRI POUR PYTHON 1.6.1


@example
1. This LICENSE AGREEMENT is between the Corporation for National Research
   Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191
   ("CNRI"), and the Individual or Organization ("Licensee") accessing and
   otherwise using Python 1.6.1 software in source or binary form and its
   associated documentation.

2. Subject to the terms and conditions of this License Agreement, CNRI hereby
   grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
   analyze, test, perform and/or display publicly, prepare derivative works,
   distribute, and otherwise use Python 1.6.1 alone or in any derivative version,
   provided, however, that CNRI's License Agreement and CNRI's notice of copyright,
   i.e., "Copyright © 1995-2001 Corporation for National Research Initiatives; All
   Rights Reserved" are retained in Python 1.6.1 alone or in any derivative version
   prepared by Licensee.  Alternately, in lieu of CNRI's License Agreement,
   Licensee may substitute the following text (omitting the quotes): "Python 1.6.1
   is made available subject to the terms and conditions in CNRI's License
   Agreement.  This Agreement together with Python 1.6.1 may be located on the
   internet using the following unique, persistent identifier (known as a handle):
   1895.22/1013.  This Agreement may also be obtained from a proxy server on the
   internet using the following URL: @indicateurl{http://hdl.handle.net/1895.22/1013}."

3. In the event Licensee prepares a derivative work that is based on or
   incorporates Python 1.6.1 or any part thereof, and wants to make the derivative
   work available to others as provided herein, then Licensee hereby agrees to
   include in any such work a brief summary of the changes made to Python 1.6.1.

4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis.  CNRI
   MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE,
   BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY
   OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
   PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR
   ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
   MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE
   THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of
   its terms and conditions.

7. This License Agreement shall be governed by the federal intellectual property
   law of the United States, including without limitation the federal copyright
   law, and, to the extent such U.S. federal law does not apply, by the law of the
   Commonwealth of Virginia, excluding Virginia's conflict of law provisions.
   Notwithstanding the foregoing, with regard to derivative works based on Python
   1.6.1 that incorporate non-separable material that was previously distributed
   under the GNU General Public License (GPL), the law of the Commonwealth of
   Virginia shall govern this License Agreement only as to issues arising under or
   with respect to Paragraphs 4, 5, and 7 of this License Agreement.  Nothing in
   this License Agreement shall be deemed to create any relationship of agency,
   partnership, or joint venture between CNRI and Licensee.  This License Agreement
   does not grant permission to use CNRI trademarks or trade name in a trademark
   sense to endorse or promote products or services of Licensee, or any third
   party.

8. By clicking on the "ACCEPT" button where indicated, or by copying, installing
   or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and
   conditions of this License Agreement.
@end example

@node LICENCE D'UTILISATION CWI POUR PYTHON 0 9 0 à 1 2,LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3 13 1,LICENCE D'UTILISATION CNRI POUR PYTHON 1 6 1,Conditions générales pour accéder à ou utiliser Python
@anchor{license cwi-license-agreement-for-python-0-9-0-through-1-2}@anchor{5059}
@subsection LICENCE D'UTILISATION CWI POUR PYTHON 0.9.0 à 1.2


@example
Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The
Netherlands.  All rights reserved.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided that
the above copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation, and that
the name of Stichting Mathematisch Centrum or CWI not be used in advertising or
publicity pertaining to distribution of the software without specific, written
prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.
@end example

@node LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3 13 1,,LICENCE D'UTILISATION CWI POUR PYTHON 0 9 0 à 1 2,Conditions générales pour accéder à ou utiliser Python
@anchor{license bsd0}@anchor{5054}@anchor{license zero-clause-bsd-license-for-code-in-the-python-release-documentation}@anchor{505a}
@subsection LICENCE BSD ZERO-CLAUSE POUR LE CODE DANS LA DOCUMENTATION DE PYTHON 3.13.1


@example
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
@end example

@node Licences et remerciements pour les logiciels tiers,,Conditions générales pour accéder à ou utiliser Python,Histoire et licence
@anchor{license licenses-and-acknowledgements-for-incorporated-software}@anchor{505b}@anchor{license otherlicenses}@anchor{5055}
@section Licences et remerciements pour les logiciels tiers


Cette section est une liste incomplète mais grandissante de licences et remerciements pour les logiciels tiers incorporés dans la distribution de Python.

@menu
* Mersenne twister:: 
* Interfaces de connexion (sockets): Interfaces de connexion sockets. 
* Interfaces de connexion asynchrones:: 
* Gestion de témoin (cookie): Gestion de témoin cookie. 
* Traçage d'exécution:: 
* Les fonctions UUencode et UUdecode:: 
* Appel de procédures distantes en XML (RPC@comma{} pour Remote Procedure Call): Appel de procédures distantes en XML RPC pour Remote Procedure Call. 
* test_epoll:: 
* Select kqueue:: 
* SipHash24:: 
* strtod et dtoa:: 
* OpenSSL: OpenSSL<2>. 
* expat:: 
* libffi:: 
* zlib: zlib<3>. 
* cfuhash:: 
* libmpdec:: 
* Ensemble de tests C14N du W3C:: 
* mimalloc:: 
* asyncio: asyncio<12>. 
* Global Unbounded Sequences (GUS): Global Unbounded Sequences GUS. 

@end menu

@node Mersenne twister,Interfaces de connexion sockets,,Licences et remerciements pour les logiciels tiers
@anchor{license mersenne-twister}@anchor{505c}
@subsection Mersenne twister


The @code{_random} C extension underlying the @ref{b7,,random} module
includes code based on a download from
@indicateurl{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html}. The following are
the verbatim comments from the original code:

@example
A C-program for MT19937, with initialization improved 2002/1/26.
Coded by Takuji Nishimura and Makoto Matsumoto.

Before using, initialize the state by using init_genrand(seed)
or init_by_array(init_key, key_length).

Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

 3. The names of its contributors may not be used to endorse or promote
    products derived from this software without specific prior written
    permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Any feedback is very welcome.
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
email: m-mat @@ math.sci.hiroshima-u.ac.jp (remove space)
@end example

@node Interfaces de connexion sockets,Interfaces de connexion asynchrones,Mersenne twister,Licences et remerciements pour les logiciels tiers
@anchor{license sockets}@anchor{505d}
@subsection Interfaces de connexion (`sockets')


The @ref{cb,,socket} module uses the functions, @code{getaddrinfo()}, and
@code{getnameinfo()}, which are coded in separate source files from the WIDE
Project, @indicateurl{https://www.wide.ad.jp/}.

@example
Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS `@w{`}AS IS'@w{'} AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
@end example

@node Interfaces de connexion asynchrones,Gestion de témoin cookie,Interfaces de connexion sockets,Licences et remerciements pour les logiciels tiers
@anchor{license asynchronous-socket-services}@anchor{505e}
@subsection Interfaces de connexion asynchrones


The @code{test.support.asynchat} and @code{test.support.asyncore}
modules contain the following notice:

@example
Copyright 1996 by Sam Rushing

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of Sam
Rushing not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.

SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
@end example

@node Gestion de témoin cookie,Traçage d'exécution,Interfaces de connexion asynchrones,Licences et remerciements pour les logiciels tiers
@anchor{license cookie-management}@anchor{505f}
@subsection Gestion de témoin (`cookie')


Le module @ref{70,,http.cookies} contient la note suivante :

@example
Copyright 2000 by Timothy O'Malley <timo@@alum.mit.edu>

               All Rights Reserved

Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Timothy O'Malley  not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
@end example

@node Traçage d'exécution,Les fonctions UUencode et UUdecode,Gestion de témoin cookie,Licences et remerciements pour les logiciels tiers
@anchor{license execution-tracing}@anchor{5060}
@subsection Traçage d'exécution


Le module @ref{fc,,trace} contient la note suivante :

@example
portions copyright 2001, Autonomous Zones Industries, Inc., all rights...
err...  reserved and offered to the public under the terms of the
Python 2.2 license.
Author: Zooko O'Whielacronx
http://zooko.com/
mailto:zooko@@zooko.com

Copyright 2000, Mojam Media, Inc., all rights reserved.
Author: Skip Montanaro

Copyright 1999, Bioreason, Inc., all rights reserved.
Author: Andrew Dalke

Copyright 1995-1997, Automatrix, Inc., all rights reserved.
Author: Skip Montanaro

Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.


Permission to use, copy, modify, and distribute this Python software and
its associated documentation for any purpose without fee is hereby
granted, provided that the above copyright notice appears in all copies,
and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of neither Automatrix,
Bioreason or Mojam Media be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.
@end example

@node Les fonctions UUencode et UUdecode,Appel de procédures distantes en XML RPC pour Remote Procedure Call,Traçage d'exécution,Licences et remerciements pour les logiciels tiers
@anchor{license uuencode-and-uudecode-functions}@anchor{5061}
@subsection Les fonctions UUencode et UUdecode


The @code{uu} codec contains the following notice:

@example
Copyright 1994 by Lance Ellinghouse
Cathedral City, California Republic, United States of America.
                       All Rights Reserved
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Lance Ellinghouse
not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.
LANCE ELLINGHOUSE DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL LANCE ELLINGHOUSE CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Modified by Jack Jansen, CWI, July 1995:
- Use binascii module to do the actual line-by-line conversion
  between ascii and binary. This results in a 1000-fold speedup. The C
  version is still 5 times faster, though.
- Arguments more compliant with Python standard
@end example

@node Appel de procédures distantes en XML RPC pour Remote Procedure Call,test_epoll,Les fonctions UUencode et UUdecode,Licences et remerciements pour les logiciels tiers
@anchor{license xml-remote-procedure-calls}@anchor{5062}
@subsection Appel de procédures distantes en XML (`RPC', pour `Remote Procedure Call')


Le module @ref{12d,,xmlrpc.client} contient la note suivante :

@example
    The XML-RPC client interface is

Copyright (c) 1999-2002 by Secret Labs AB
Copyright (c) 1999-2002 by Fredrik Lundh

By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:

Permission to use, copy, modify, and distribute this software and
its associated documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appears in
all copies, and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Secret Labs AB or the author not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.

SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
ABILITY AND FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.
@end example

@node test_epoll,Select kqueue,Appel de procédures distantes en XML RPC pour Remote Procedure Call,Licences et remerciements pour les logiciels tiers
@anchor{license test-epoll}@anchor{5063}
@subsection test_epoll


The @code{test.test_epoll} module contains the following notice:

@example
Copyright (c) 2001-2006 Twisted Matrix Laboratories.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@end example

@node Select kqueue,SipHash24,test_epoll,Licences et remerciements pour les logiciels tiers
@anchor{license select-kqueue}@anchor{5064}
@subsection Select kqueue


Le module @ref{c0,,select} contient la note suivante pour l'interface `kqueue' :

@example
Copyright (c) 2000 Doug White, 2006 James Knight, 2007 Christian Heimes
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS `@w{`}AS IS'@w{'} AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
@end example

@node SipHash24,strtod et dtoa,Select kqueue,Licences et remerciements pour les logiciels tiers
@anchor{license siphash24}@anchor{5065}
@subsection SipHash24


Le fichier @code{Python/pyhash.c} contient une implémentation par Marek Majkowski de l'algorithme `SipHash24' de Dan Bernstein. Il contient la note suivante :

@example
<MIT License>
Copyright (c) 2013  Marek Majkowski <marek@@popcount.org>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</MIT License>

Original location:
   https://github.com/majek/csiphash/

Solution inspired by code from:
   Samuel Neves (supercop/crypto_auth/siphash24/little)
   djb (supercop/crypto_auth/siphash24/little2)
   Jean-Philippe Aumasson (https://131002.net/siphash/siphash24.c)
@end example

@node strtod et dtoa,OpenSSL<2>,SipHash24,Licences et remerciements pour les logiciels tiers
@anchor{license strtod-and-dtoa}@anchor{5066}
@subsection `strtod' et `dtoa'


The file @code{Python/dtoa.c}, which supplies C functions dtoa and
strtod for conversion of C doubles to and from strings, is derived
from the file of the same name by David M. Gay, currently available
from @indicateurl{https://web.archive.org/web/20220517033456/http://www.netlib.org/fp/dtoa.c}.
The original file, as retrieved on March 16, 2009, contains the following
copyright and licensing notice:

@example
/****************************************************************
 *
 * The author of this software is David M. Gay.
 *
 * Copyright (c) 1991, 2000, 2001 by Lucent Technologies.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose without fee is hereby granted, provided that this entire notice
 * is included in all copies of any software which is or includes a copy
 * or modification of this software and in all copies of the supporting
 * documentation for such software.
 *
 * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
 * WARRANTY.  IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY
 * REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
 * OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
 *
 ***************************************************************/
@end example

@node OpenSSL<2>,expat,strtod et dtoa,Licences et remerciements pour les logiciels tiers
@anchor{license openssl}@anchor{5067}
@subsection OpenSSL


The modules @ref{67,,hashlib}, @ref{ac,,posix} and @ref{cf,,ssl} use
the OpenSSL library for added performance if made available by the
operating system. Additionally, the Windows and macOS installers for
Python may include a copy of the OpenSSL libraries, so we include a copy
of the OpenSSL license here. For the OpenSSL 3.0 release,
and later releases derived from that, the Apache License v2 applies:

@example
                              Apache License
                        Version 2.0, January 2004
                     https://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

   "License" shall mean the terms and conditions for use, reproduction,
   and distribution as defined by Sections 1 through 9 of this document.

   "Licensor" shall mean the copyright owner or entity authorized by
   the copyright owner that is granting the License.

   "Legal Entity" shall mean the union of the acting entity and all
   other entities that control, are controlled by, or are under common
   control with that entity. For the purposes of this definition,
   "control" means (i) the power, direct or indirect, to cause the
   direction or management of such entity, whether by contract or
   otherwise, or (ii) ownership of fifty percent (50%) or more of the
   outstanding shares, or (iii) beneficial ownership of such entity.

   "You" (or "Your") shall mean an individual or Legal Entity
   exercising permissions granted by this License.

   "Source" form shall mean the preferred form for making modifications,
   including but not limited to software source code, documentation
   source, and configuration files.

   "Object" form shall mean any form resulting from mechanical
   transformation or translation of a Source form, including but
   not limited to compiled object code, generated documentation,
   and conversions to other media types.

   "Work" shall mean the work of authorship, whether in Source or
   Object form, made available under the License, as indicated by a
   copyright notice that is included in or attached to the work
   (an example is provided in the Appendix below).

   "Derivative Works" shall mean any work, whether in Source or Object
   form, that is based on (or derived from) the Work and for which the
   editorial revisions, annotations, elaborations, or other modifications
   represent, as a whole, an original work of authorship. For the purposes
   of this License, Derivative Works shall not include works that remain
   separable from, or merely link (or bind by name) to the interfaces of,
   the Work and Derivative Works thereof.

   "Contribution" shall mean any work of authorship, including
   the original version of the Work and any modifications or additions
   to that Work or Derivative Works thereof, that is intentionally
   submitted to Licensor for inclusion in the Work by the copyright owner
   or by an individual or Legal Entity authorized to submit on behalf of
   the copyright owner. For the purposes of this definition, "submitted"
   means any form of electronic, verbal, or written communication sent
   to the Licensor or its representatives, including but not limited to
   communication on electronic mailing lists, source code control systems,
   and issue tracking systems that are managed by, or on behalf of, the
   Licensor for the purpose of discussing and improving the Work, but
   excluding communication that is conspicuously marked or otherwise
   designated in writing by the copyright owner as "Not a Contribution."

   "Contributor" shall mean Licensor and any individual or Legal Entity
   on behalf of whom a Contribution has been received by Licensor and
   subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of
   this License, each Contributor hereby grants to You a perpetual,
   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
   copyright license to reproduce, prepare Derivative Works of,
   publicly display, publicly perform, sublicense, and distribute the
   Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of
   this License, each Contributor hereby grants to You a perpetual,
   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
   (except as stated in this section) patent license to make, have made,
   use, offer to sell, sell, import, and otherwise transfer the Work,
   where such license applies only to those patent claims licensable
   by such Contributor that are necessarily infringed by their
   Contribution(s) alone or by combination of their Contribution(s)
   with the Work to which such Contribution(s) was submitted. If You
   institute patent litigation against any entity (including a
   cross-claim or counterclaim in a lawsuit) alleging that the Work
   or a Contribution incorporated within the Work constitutes direct
   or contributory patent infringement, then any patent licenses
   granted to You under this License for that Work shall terminate
   as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the
   Work or Derivative Works thereof in any medium, with or without
   modifications, and in Source or Object form, provided that You
   meet the following conditions:

   (a) You must give any other recipients of the Work or
       Derivative Works a copy of this License; and

   (b) You must cause any modified files to carry prominent notices
       stating that You changed the files; and

   (c) You must retain, in the Source form of any Derivative Works
       that You distribute, all copyright, patent, trademark, and
       attribution notices from the Source form of the Work,
       excluding those notices that do not pertain to any part of
       the Derivative Works; and

   (d) If the Work includes a "NOTICE" text file as part of its
       distribution, then any Derivative Works that You distribute must
       include a readable copy of the attribution notices contained
       within such NOTICE file, excluding those notices that do not
       pertain to any part of the Derivative Works, in at least one
       of the following places: within a NOTICE text file distributed
       as part of the Derivative Works; within the Source form or
       documentation, if provided along with the Derivative Works; or,
       within a display generated by the Derivative Works, if and
       wherever such third-party notices normally appear. The contents
       of the NOTICE file are for informational purposes only and
       do not modify the License. You may add Your own attribution
       notices within Derivative Works that You distribute, alongside
       or as an addendum to the NOTICE text from the Work, provided
       that such additional attribution notices cannot be construed
       as modifying the License.

   You may add Your own copyright statement to Your modifications and
   may provide additional or different license terms and conditions
   for use, reproduction, or distribution of Your modifications, or
   for any such Derivative Works as a whole, provided Your use,
   reproduction, and distribution of the Work otherwise complies with
   the conditions stated in this License.

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade
   names, trademarks, service marks, or product names of the Licensor,
   except as required for reasonable and customary use in describing the
   origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or
   agreed to in writing, Licensor provides the Work (and each
   Contributor provides its Contributions) on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
   implied, including, without limitation, any warranties or conditions
   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
   PARTICULAR PURPOSE. You are solely responsible for determining the
   appropriateness of using or redistributing the Work and assume any
   risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory,
   whether in tort (including negligence), contract, or otherwise,
   unless required by applicable law (such as deliberate and grossly
   negligent acts) or agreed to in writing, shall any Contributor be
   liable to You for damages, including any direct, indirect, special,
   incidental, or consequential damages of any character arising as a
   result of this License or out of the use or inability to use the
   Work (including but not limited to damages for loss of goodwill,
   work stoppage, computer failure or malfunction, or any and all
   other commercial damages or losses), even if such Contributor
   has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing
   the Work or Derivative Works thereof, You may choose to offer,
   and charge a fee for, acceptance of support, warranty, indemnity,
   or other liability obligations and/or rights consistent with this
   License. However, in accepting such obligations, You may act only
   on Your own behalf and on Your sole responsibility, not on behalf
   of any other Contributor, and only if You agree to indemnify,
   defend, and hold each Contributor harmless for any liability
   incurred by, or claims asserted against, such Contributor by reason
   of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS
@end example

@node expat,libffi,OpenSSL<2>,Licences et remerciements pour les logiciels tiers
@anchor{license expat}@anchor{5068}
@subsection expat


The @ref{125,,pyexpat} extension is built using an included copy of the expat
sources unless the build is configured @code{--with-system-expat}:

@example
Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
                               and Clark Cooper

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@end example

@node libffi,zlib<3>,expat,Licences et remerciements pour les logiciels tiers
@anchor{license libffi}@anchor{5069}
@subsection libffi


The @code{_ctypes} C extension underlying the @ref{2a,,ctypes} module
is built using an included copy of the libffi
sources unless the build is configured @code{--with-system-libffi}:

@example
Copyright (c) 1996-2008  Red Hat, Inc and others.

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
`@w{`}Software'@w{'}), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED `@w{`}AS IS'@w{'}, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
@end example

@node zlib<3>,cfuhash,libffi,Licences et remerciements pour les logiciels tiers
@anchor{license zlib}@anchor{506a}
@subsection zlib


Le module @ref{132,,zlib} est compilé en utilisant une copie du code source de `zlib' si la version de `zlib' trouvée sur le système est trop vieille pour être utilisée :

@example
Copyright (C) 1995-2011 Jean-loup Gailly and Mark Adler

This software is provided 'as-is', without any express or implied
warranty.  In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would be
   appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Jean-loup Gailly        Mark Adler
jloup@@gzip.org          madler@@alumni.caltech.edu
@end example

@node cfuhash,libmpdec,zlib<3>,Licences et remerciements pour les logiciels tiers
@anchor{license cfuhash}@anchor{506b}
@subsection cfuhash


L'implémentation des dictionnaires, utilisée par le module @ref{fe,,tracemalloc} est basée sur le projet `cfuhash' :

@example
Copyright (c) 2005 Don Owens
All rights reserved.

This code is released under the BSD license:

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the following
    disclaimer in the documentation and/or other materials provided
    with the distribution.

  * Neither the name of the author nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
@end example

@node libmpdec,Ensemble de tests C14N du W3C,cfuhash,Licences et remerciements pour les logiciels tiers
@anchor{license libmpdec}@anchor{506c}
@subsection libmpdec


The @code{_decimal} C extension underlying the @ref{36,,decimal} module
is built using an included copy of the libmpdec
library unless the build is configured @code{--with-system-libmpdec}:

@example
Copyright (c) 2008-2020 Stefan Krah. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
@end example

@node Ensemble de tests C14N du W3C,mimalloc,libmpdec,Licences et remerciements pour les logiciels tiers
@anchor{license w3c-c14n-test-suite}@anchor{506d}
@subsection Ensemble de tests C14N du W3C


Les tests de C14N version 2.0 du module @ref{e1,,test} (@code{Lib/test/xmltestdata/c14n-20/}) proviennent du site du W3C à l'adresse @indicateurl{https://www.w3.org/TR/xml-c14n2-testcases/} et sont distribués sous licence BSD modifiée :

@example
Copyright (c) 2013 W3C(R) (MIT, ERCIM, Keio, Beihang),
All Rights Reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

* Redistributions of works must retain the original copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the original copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
* Neither the name of the W3C nor the names of its contributors may be
  used to endorse or promote products derived from this work without
  specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@end example

@node mimalloc,asyncio<12>,Ensemble de tests C14N du W3C,Licences et remerciements pour les logiciels tiers
@anchor{license mimalloc}@anchor{506e}@anchor{license mimalloc-license}@anchor{407}
@subsection mimalloc


MIT License:

@example
Copyright (c) 2018-2021 Microsoft Corporation, Daan Leijen

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@end example

@node asyncio<12>,Global Unbounded Sequences GUS,mimalloc,Licences et remerciements pour les logiciels tiers
@anchor{license asyncio}@anchor{506f}
@subsection `asyncio'


Parts of the @ref{a,,asyncio} module are incorporated from
uvloop 0.16@footnote{https://github.com/MagicStack/uvloop/tree/v0.16.0},
which is distributed under the MIT license:

@example
Copyright (c) 2015-2021 MagicStack Inc.  http://magic.io

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@end example

@node Global Unbounded Sequences GUS,,asyncio<12>,Licences et remerciements pour les logiciels tiers
@anchor{license global-unbounded-sequences-gus}@anchor{5070}
@subsection Global Unbounded Sequences (GUS)


The file @code{Python/qsbr.c} is adapted from FreeBSD's "Global Unbounded
Sequences" safe memory reclamation scheme in
subr_smr.c@footnote{https://github.com/freebsd/freebsd-src/blob/main/sys/kern/subr_smr.c}.
The file is distributed under the 2-Clause BSD License:

@example
Copyright (c) 2019,2020 Jeffrey Roberson <jeff@@FreeBSD.org>

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice unmodified, this list of conditions, and the following
   disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR `@w{`}AS IS'@w{'} AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@end example

@node Index des modules Python,Index,Histoire et licence,Top
@unnumbered Index des modules Python


@menu
* __future__: 0. Future statement definitions
* __main__: 1. The environment where top-level code is run. Covers
                        command-line interfaces@comma{} import-time
                        behavior@comma{} and `@w{`}__name__ ==
                        '__main__'`@w{`}.
* _thread: 2. Low-level threading API.
* _tkinter: 3. A binary module that contains the low-level interface
                        to Tcl/Tk.
* abc: 4. Abstract base classes according to :pep:`3119`.
* aifc: 5. Removed in 3.13.
* argparse: 6. Command-line option and argument parsing library.
* array: 7. Space efficient arrays of uniformly typed numeric
                        values.
* ast: 8. Abstract Syntax Tree classes and manipulation.
* asynchat: 9. Removed in 3.12.
* asyncio: a. Asynchronous I/O.
* asyncore: b. Removed in 3.12.
* atexit: c. Register and execute cleanup functions.
* audioop: d. Removed in 3.13.
* base64: e. RFC 4648: Base16@comma{} Base32@comma{} Base64 Data
                        Encodings; Base85 and Ascii85
* bdb: f. Debugger framework.
* binascii: 10. Tools for converting between binary and various ASCII-
                        encoded binary representations.
* bisect: 11. Array bisection algorithms for binary searching.
* builtins: 12. The module that provides the built-in namespace.
* bz2: 13. Interfaces for bzip2 compression and decompression.
* calendar: 14. Functions for working with calendars@comma{} including
                        some emulation of the Unix cal program.
* cgi: 15. Removed in 3.13.
* cgitb: 16. Removed in 3.13.
* chunk: 17. Removed in 3.13.
* cmath: 18. Mathematical functions for complex numbers.
* cmd: 19. Build line-oriented command interpreters.
* code: 1a. Facilities to implement read-eval-print loops.
* codecs: 1b. Encode and decode data and streams.
* codeop: 1c. Compile (possibly incomplete) Python code.
* collections: 1d. Container datatypes
* collections.abc: 1e. Abstract base classes for containers
* colorsys: 1f. Conversion functions between RGB and other color
                        systems.
* compileall: 20. Tools for byte-compiling all Python source files in a
                        directory tree.
* concurrent.futures: 21. Execute computations concurrently using threads or
                        processes.
* configparser: 22. Configuration file parser.
* contextlib: 23. Utilities for with-statement contexts.
* contextvars: 24. Context Variables
* copy: 25. Shallow and deep copy operations.
* copyreg: 26. Register pickle support functions.
* cProfile: 27. 
* crypt: 28. Removed in 3.13.
* csv: 29. Write and read tabular data to and from delimited
                        files.
* ctypes: 2a. A foreign function library for Python.
* curses: 2b. An interface to the curses library@comma{} providing
                        portable terminal handling.
* curses.ascii: 2c. Constants and set-membership functions for ASCII
                        characters.
* curses.panel: 2d. A panel stack extension that adds depth to curses
                        windows.
* curses.textpad: 2e. Emacs-like input editing in a curses window.
* dataclasses: 2f. Generate special methods on user-defined classes.
* datetime: 30. Basic date and time types.
* dbm: 31. Interfaces to various Unix "database" formats.
* dbm.dumb: 32. Portable implementation of the simple DBM interface.
* dbm.gnu: 33. GNU database manager
* dbm.ndbm: 34. The New Database Manager
* dbm.sqlite3: 35. SQLite backend for dbm
* decimal: 36. Implementation of the General Decimal Arithmetic
                        Specification.
* difflib: 37. Helpers for computing differences between objects.
* dis: 38. Disassembler for Python bytecode.
* distutils: 39. Removed in 3.12.
* doctest: 3a. Test pieces of code within docstrings.
* email: 3b. Package supporting the parsing@comma{}
                        manipulating@comma{} and generating email messages.
* email.charset: 3c. Character Sets
* email.contentmanager: 3d. Storing and Retrieving Content from MIME Parts
* email.encoders: 3e. Encoders for email message payloads.
* email.errors: 3f. The exception classes used by the email package.
* email.generator: 40. Generate flat text email messages from a message
                        structure.
* email.header: 41. Representing non-ASCII headers
* email.headerregistry: 42. Automatic Parsing of headers based on the field name
* email.iterators: 43. Iterate over a message object tree.
* email.message: 44. The base class representing email messages.
* email.mime: 45. Build MIME messages.
* email.mime.application: 46. 
* email.mime.audio: 47. 
* email.mime.base: 48. 
* email.mime.image: 49. 
* email.mime.message: 4a. 
* email.mime.multipart: 4b. 
* email.mime.nonmultipart: 4c. 
* email.mime.text: 4d. 
* email.parser: 4e. Parse flat text email messages to produce a message
                        object structure.
* email.policy: 4f. Controlling the parsing and generating of messages
* email.utils: 50. Miscellaneous email package utilities.
* encodings.idna: 51. Internationalized Domain Names implementation
* encodings.mbcs: 52. Windows ANSI codepage
* encodings.utf_8_sig: 53. UTF-8 codec with BOM signature
* ensurepip: 54. Bootstrapping the "pip" installer into an existing
                        Python installation or virtual environment.
* enum: 55. Implementation of an enumeration class.
* errno: 56. Standard errno system symbols.
* faulthandler: 57. Dump the Python traceback.
* fcntl: 58. The fcntl() and ioctl() system calls.
* filecmp: 59. Compare files efficiently.
* fileinput: 5a. Loop over standard input or a list of files.
* fnmatch: 5b. Unix shell style filename pattern matching.
* fractions: 5c. Rational numbers.
* ftplib: 5d. FTP protocol client (requires sockets).
* functools: 5e. Higher-order functions and operations on callable
                        objects.
* gc: 5f. Interface to the cycle-detecting garbage collector.
* getopt: 60. Portable parser for command line options; support both
                        short and long option names.
* getpass: 61. Portable reading of passwords and retrieval of the
                        userid.
* gettext: 62. Multilingual internationalization services.
* glob: 63. Unix shell style pathname pattern expansion.
* graphlib: 64. Functionality to operate with graph-like structures
* grp: 65. The group database (getgrnam() and friends).
* gzip: 66. Interfaces for gzip compression and decompression
                        using file objects.
* hashlib: 67. Secure hash and message digest algorithms.
* heapq: 68. Heap queue algorithm (a.k.a. priority queue).
* hmac: 69. Keyed-Hashing for Message Authentication (HMAC)
                        implementation
* html: 6a. Helpers for manipulating HTML.
* html.entities: 6b. Definitions of HTML general entities.
* html.parser: 6c. A simple parser that can handle HTML and XHTML.
* http: 6d. HTTP status codes and messages
* http.client: 6e. HTTP and HTTPS protocol client (requires sockets).
* http.cookiejar: 6f. Classes for automatic handling of HTTP cookies.
* http.cookies: 70. Support for HTTP state management (cookies).
* http.server: 71. HTTP server and request handlers.
* idlelib: 72. Implementation package for the IDLE shell/editor.
* imaplib: 73. IMAP4 protocol client (requires sockets).
* imghdr: 74. Removed in 3.13.
* imp: 75. Removed in 3.12.
* importlib: 76. The implementation of the import machinery.
* importlib.abc: 77. Abstract base classes related to import
* importlib.machinery: 78. Importers and path hooks
* importlib.metadata: 79. Accessing package metadata
* importlib.resources: 7a. Package resource reading@comma{} opening@comma{} and
                        access
* importlib.resources.abc: 7b. Abstract base classes for resources
* importlib.util: 7c. Utility code for importers
* inspect: 7d. Extract information and source code from live objects.
* io: 7e. Core tools for working with streams.
* ipaddress: 7f. IPv4/IPv6 manipulation library.
* itertools: 80. Functions creating iterators for efficient looping.
* json: 81. Encode and decode the JSON format.
* json.tool: 82. A command line to validate and pretty-print JSON.
* keyword: 83. Test whether a string is a keyword in Python.
* linecache: 84. Provides random access to individual lines from text
                        files.
* locale: 85. Internationalization services.
* logging: 86. Flexible event logging system for applications.
* logging.config: 87. Configuration of the logging module.
* logging.handlers: 88. Handlers for the logging module.
* lzma: 89. A Python wrapper for the liblzma compression library.
* mailbox: 8a. Manipulate mailboxes in various formats
* mailcap: 8b. Removed in 3.13.
* marshal: 8c. Convert Python objects to streams of bytes and back
                        (with different constraints).
* math: 8d. Mathematical functions (sin() etc.).
* mimetypes: 8e. Mapping of filename extensions to MIME types.
* mmap: 8f. Interface to memory-mapped files for Unix and Windows.
* modulefinder: 90. Find modules used by a script.
* msilib: 91. Removed in 3.13.
* msvcrt: 92. Miscellaneous useful routines from the MS VC++
                        runtime.
* multiprocessing: 93. Process-based parallelism.
* multiprocessing.connection: 94. API for dealing with sockets.
* multiprocessing.dummy: 95. Dumb wrapper around threading.
* multiprocessing.managers: 96. Share data between process with shared objects.
* multiprocessing.pool: 97. Create pools of processes.
* multiprocessing.shared_memory: 98. Provides shared memory for direct access
                                 across processes.
* multiprocessing.sharedctypes: 99. Allocate ctypes objects from shared memory.
* netrc: 9a. Loading of .netrc files.
* nis: 9b. Removed in 3.13.
* nntplib: 9c. Removed in 3.13.
* numbers: 9d. Numeric abstract base classes (Complex@comma{}
                        Real@comma{} Integral@comma{} etc.).
* operator: 9e. Functions corresponding to the standard operators.
* optparse: 9f. Command-line option parsing library.
* os: a0. Miscellaneous operating system interfaces.
* os.path: a1. Operations on pathnames.
* ossaudiodev: a2. Removed in 3.13.
* pathlib: a3. Object-oriented filesystem paths
* pdb: a4. The Python debugger for interactive interpreters.
* pickle: a5. Convert Python objects to streams of bytes and back.
* pickletools: a6. Contains extensive comments about the pickle protocols
                        and pickle-machine opcodes@comma{} as well as some
                        useful functions.
* pipes: a7. Removed in 3.13.
* pkgutil: a8. Utilities for the import system.
* platform: a9. Retrieves as much platform identifying data as
                        possible.
* plistlib: aa. Generate and parse Apple plist files.
* poplib: ab. POP3 protocol client (requires sockets).
* posix: ac. The most common POSIX system calls (normally used via
                        module os).
* pprint: ad. Data pretty printer.
* profile: ae. Python source profiler.
* pstats: af. Statistics object for use with the profiler.
* pty: b0. Pseudo-Terminal Handling for Unix.
* pwd: b1. The password database (getpwnam() and friends).
* py_compile: b2. Generate byte-code files from Python source files.
* pyclbr: b3. Supports information extraction for a Python module
                        browser.
* pydoc: b4. Documentation generator and online help system.
* queue: b5. A synchronized queue class.
* quopri: b6. Encode and decode files using the MIME quoted-
                        printable encoding.
* random: b7. Generate pseudo-random numbers with various common
                        distributions.
* re: b8. Regular expression operations.
* readline: b9. GNU readline support for Python.
* reprlib: ba. Alternate repr() implementation with size limits.
* resource: bb. An interface to provide resource usage information on
                        the current process.
* rlcompleter: bc. Python identifier completion@comma{} suitable for the
                        GNU readline library.
* runpy: bd. Locate and run Python modules without importing them
                        first.
* sched: be. General purpose event scheduler.
* secrets: bf. Generate secure random numbers for managing secrets.
* select: c0. Wait for I/O completion on multiple streams.
* selectors: c1. High-level I/O multiplexing.
* shelve: c2. Python object persistence.
* shlex: c3. Simple lexical analysis for Unix shell-like languages.
* shutil: c4. High-level file operations@comma{} including copying.
* signal: c5. Set handlers for asynchronous events.
* site: c6. Module responsible for site-specific configuration.
* sitecustomize: c7. 
* smtpd: c8. Removed in 3.12.
* smtplib: c9. SMTP protocol client (requires sockets).
* sndhdr: ca. Removed in 3.13.
* socket: cb. Low-level networking interface.
* socketserver: cc. A framework for network servers.
* spwd: cd. Removed in 3.13.
* sqlite3: ce. A DB-API 2.0 implementation using SQLite 3.x.
* ssl: cf. TLS/SSL wrapper for socket objects
* stat: d0. Utilities for interpreting the results of
                        os.stat()@comma{} os.lstat() and os.fstat().
* statistics: d1. Mathematical statistics functions
* string: d2. Common string operations.
* stringprep: d3. String preparation@comma{} as per RFC 3453
* struct: d4. Interpret bytes as packed binary data.
* subprocess: d5. Subprocess management.
* sunau: d6. Removed in 3.13.
* symtable: d7. Interface to the compiler's internal symbol tables.
* sys: d8. Access system-specific parameters and functions.
* sys.monitoring: d9. Access and control event monitoring
* sysconfig: da. Python's configuration information
* syslog: db. An interface to the Unix syslog library routines.
* tabnanny: dc. Tool for detecting white space related problems in
                        Python source files in a directory tree.
* tarfile: dd. Read and write tar-format archive files.
* telnetlib: de. Removed in 3.13.
* tempfile: df. Generate temporary files and directories.
* termios: e0. POSIX style tty control.
* test: e1. Regression tests package containing the testing suite
                        for Python.
* test.regrtest: e2. Drives the regression test suite.
* test.support: e3. Support for Python's regression test suite.
* test.support.bytecode_helper: e4. Support tools for testing correct bytecode
                                generation.
* test.support.import_helper: e5. Support for import tests.
* test.support.os_helper: e6. Support for os tests.
* test.support.script_helper: e7. Support for Python's script execution tests.
* test.support.socket_helper: e8. Support for socket tests.
* test.support.threading_helper: e9. Support for threading tests.
* test.support.warnings_helper: ea. Support for warnings tests.
* textwrap: eb. Text wrapping and filling
* threading: ec. Thread-based parallelism.
* time: ed. Time access and conversions.
* timeit: ee. Measure the execution time of small code snippets.
* tkinter: ef. Interface to Tcl/Tk for graphical user interfaces
* tkinter.colorchooser: f0. Color choosing dialog
* tkinter.commondialog: f1. Tkinter base class for dialogs
* tkinter.dnd: f2. Tkinter drag-and-drop interface
* tkinter.filedialog: f3. Dialog classes for file selection
* tkinter.font: f4. Tkinter font-wrapping class
* tkinter.messagebox: f5. Various types of alert dialogs
* tkinter.scrolledtext: f6. Text widget with a vertical scroll bar.
* tkinter.simpledialog: f7. Simple dialog windows
* tkinter.ttk: f8. Tk themed widget set
* token: f9. Constants representing terminal nodes of the parse
                        tree.
* tokenize: fa. Lexical scanner for Python source code.
* tomllib: fb. Parse TOML files.
* trace: fc. Trace or track Python statement execution.
* traceback: fd. Print or retrieve a stack traceback.
* tracemalloc: fe. Trace memory allocations.
* tty: ff. Utility functions that perform common terminal control
                        operations.
* turtle: 100. An educational framework for simple graphics
                        applications
* turtledemo: 101. A viewer for example turtle scripts
* types: 102. Names for built-in types.
* typing: 103. Support for type hints (see :pep:`484`).
* unicodedata: 104. Access the Unicode Database.
* unittest: 105. Unit testing framework for Python.
* unittest.mock: 106. Mock object library.
* urllib: 107. 
* urllib.error: 108. Exception classes raised by urllib.request.
* urllib.parse: 109. Parse URLs into or assemble them from components.
* urllib.request: 10a. Extensible library for opening URLs.
* urllib.response: 10b. Response classes used by urllib.
* urllib.robotparser: 10c. Load a robots.txt file and answer questions about
                        fetchability of other URLs.
* usercustomize: 10d. 
* uu: 10e. Removed in 3.13.
* uuid: 10f. UUID objects (universally unique identifiers)
                        according to RFC 4122
* venv: 110. Creation of virtual environments.
* warnings: 111. Issue warning messages and control their disposition.
* wave: 112. Provide an interface to the WAV sound format.
* weakref: 113. Support for weak references and weak dictionaries.
* webbrowser: 114. Easy-to-use controller for web browsers.
* winreg: 115. Routines and objects for manipulating the Windows
                        registry.
* winsound: 116. Access to the sound-playing machinery for Windows.
* wsgiref: 117. WSGI Utilities and Reference Implementation.
* wsgiref.handlers: 118. WSGI server/gateway base classes.
* wsgiref.headers: 119. WSGI response header tools.
* wsgiref.simple_server: 11a. A simple WSGI HTTP server.
* wsgiref.types: 11b. WSGI types for static type checking
* wsgiref.util: 11c. WSGI environment utilities.
* wsgiref.validate: 11d. WSGI conformance checker.
* xdrlib: 11e. Removed in 3.13.
* xml: 11f. Package containing XML processing modules
* xml.dom: 120. Document Object Model API for Python.
* xml.dom.minidom: 121. Minimal Document Object Model (DOM) implementation.
* xml.dom.pulldom: 122. Support for building partial DOM trees from SAX
                        events.
* xml.etree.ElementInclude: 123. 
* xml.etree.ElementTree: 124. Implementation of the ElementTree API.
* xml.parsers.expat: 125. An interface to the Expat non-validating XML parser.
* xml.parsers.expat.errors: 126. 
* xml.parsers.expat.model: 127. 
* xml.sax: 128. Package containing SAX2 base classes and convenience
                        functions.
* xml.sax.handler: 129. Base classes for SAX event handlers.
* xml.sax.saxutils: 12a. Convenience functions and classes for use with SAX.
* xml.sax.xmlreader: 12b. Interface which SAX-compliant XML parsers must
                        implement.
* xmlrpc: 12c. Server and client modules implementing XML-RPC.
* xmlrpc.client: 12d. XML-RPC client access.
* xmlrpc.server: 12e. Basic XML-RPC server implementations.
* zipapp: 12f. Manage executable Python zip archives
* zipfile: 130. Read and write ZIP-format archive files.
* zipimport: 131. Support for importing Python modules from ZIP
                        archives.
* zlib: 132. Low-level interface to compression and decompression
                        routines compatible with gzip.
* zoneinfo: 133. IANA time zone support
@end menu


@node Index,,Index des modules Python,Top
@unnumbered Index


@printindex ge

@anchor{410e}@w{                              }
@anchor{library/time audit_event_time_sleep_0}@w{                              }
@anchor{4112}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_file_0}@w{                              }
@anchor{library/asyncio audit_event_cpython_run_stdin_0}@w{                              }
@anchor{411b}@w{                              }
@anchor{4113}@w{                              }
@anchor{4114}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_stdin_1}@w{                              }
@anchor{using/cmdline audit_event_cpython_run_stdin_0}@w{                              }
@anchor{library/_thread start_new_thread}@w{                              }
@anchor{4111}@w{                              }

@c %**end of body
@bye
